Metadata-Version: 2.4
Name: calamum_vulcan
Version: 0.3.0
Summary: Samsung-focused open-source Android flashing platform with GUI-first workflows, preflight validation, and audit-ready evidence.
Author: Joe Waller
License-Expression: MIT
Project-URL: Homepage, https://github.com/joediggidyyy/calamum_vulcan
Project-URL: Repository, https://github.com/joediggidyyy/calamum_vulcan
Project-URL: Issues, https://github.com/joediggidyyy/calamum_vulcan/issues
Project-URL: Documentation, https://github.com/joediggidyyy/calamum_vulcan#readme
Project-URL: Changelog, https://github.com/joediggidyyy/calamum_vulcan/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/joediggidyyy/calamum_vulcan/blob/main/SECURITY.md
Keywords: android,samsung,flashing,gui,heimdall
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Hardware
Requires-Python: <3.15,>=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6<7,>=6.8
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == "release"
Requires-Dist: twine<7,>=6; extra == "release"
Dynamic: license-file

# Calamum Vulcan

Samsung-focused open-source Android flashing platform with GUI-first workflows, preflight validation, and audit-ready evidence.

## Current status

`0.3.0` is the current Calamum Vulcan candidate boundary in this repository.

Current release posture:

- public GitHub seed: `https://github.com/joediggidyyy/calamum_vulcan`
- release root: this repository root
- validated source-checkout runtime: Python `3.14`
- license: MIT
- current repository package version: `0.3.0`
- current candidate tag target: `v0.3.0`
- latest public PyPI/GitHub release before candidate seal: `0.2.0`
- live PyPI project: `https://pypi.org/project/calamum-vulcan/`
- latest public GitHub release: `https://github.com/joediggidyyy/calamum_vulcan/releases/tag/v0.2.0`

## Source checkout quickstart

From the repository root:

1. activate a validated Python `3.14` environment
2. run the unit suite
3. launch a shell scenario or an integration bundle review

Representative commands:

- `python -m unittest discover -s tests/unit -p "test_*.py"`
- `python calamum_vulcan/launch_shell.py --scenario ready --describe-only`
- `python -m calamum_vulcan.app --integration-suite read-side-close --suite-format markdown --suite-output temp/fs3_07_read_side_close.md`

## Installed-artifact quickstart

For a release-style review from the built wheel:

1. build the artifacts from this repository root
2. install the wheel into a clean Python `3.14` environment
3. verify the public CLI, evidence export, and GUI launch surface

Representative commands:

- `python scripts/build_release_artifacts.py`
- `python -m pip install dist/calamum_vulcan-0.3.0-py3-none-any.whl`
- `calamum-vulcan --scenario ready --describe-only`
- `calamum-vulcan --scenario blocked --describe-only --export-evidence --evidence-format markdown --evidence-output blocked_review.md`
- `calamum-vulcan-gui`

## Packaging and build

Build and inspect release artifacts from the repository root with:

- `python -m pip install -e .[release]`
- `python scripts/build_release_artifacts.py`
- `python scripts/validate_installed_artifact.py`
- `python scripts/run_scripted_simulation_suite.py`

This produces and inspects both `sdist` and `wheel` artifacts from the nested release root.

The installed-artifact runner creates a clean temporary environment, installs the built wheel outside the source tree, verifies the public entry points, exercises evidence export and the sprint-close bundle, and audits the packaged file surface.

For the `0.3.0` candidate boundary, the installed-artifact runner also proves that the packaged wheel preserves the `read-side-close` bundle and the explicit inspect-only / fallback evidence posture.

The scripted simulation runner executes the publication-safe scenario matrix from both the release root and an installed wheel context, checks deterministic JSON and Markdown evidence outputs, validates offscreen GUI launch behavior, and archives the resulting bundle evidence under `temp/fs_p04_scripted_simulation/`.

The empirical review runner performs the clean-install walkthrough, captures packaged GUI screenshots for human review, inspects release-facing evidence exports, and archives the resulting artifacts under `temp/fs_p05_empirical_review/`.

- `python scripts/run_empirical_review_stack.py`

The TestPyPI rehearsal runner performs the final publication gate, attempts the registry rehearsal when credentials are configured, validates registry-delivered install behavior, and records a final go/no-go summary under `temp/fs_p06_testpypi_rehearsal/`.

- `python scripts/run_testpypi_rehearsal.py`

The publication rehearsal accepts TestPyPI credentials from the release-root `.env`, the active shell environment, or the user-level `.pypirc`:

- `CALAMUM_VULCAN_TESTPYPI_TOKEN`
- optional fallback: `TWINE_USERNAME=__token__` and `TWINE_PASSWORD`
- optional shared-user profile: `[testpypi]` in `~/.pypirc`

## Installed entry points

The packaging contract for `0.3.0` defines these installed entry points:

- `calamum-vulcan` — console entry point for CLI review flows and GUI launch
- `calamum-vulcan-gui` — console-visible GUI launcher entry point

## Repository layout

| Path                                                          | Purpose                                                  |
| ------------------------------------------------------------- | -------------------------------------------------------- |
| `calamum_vulcan/`                                             | package source, launcher, fixtures, and runtime surfaces |
| `tests/`                                                      | unit and release-lane validation surfaces                |
| `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md` | tracked public documentation surfaces                    |
| `LICENSE`                                                     | project license                                          |

## Tracked documentation

The tracked documentation surface for this repository stays at the root:

- `README.md` — install, build, support posture, and public usage guidance
- `CHANGELOG.md` — release notes and user-visible change history
- `CONTRIBUTING.md` — contributor workflow and release-lane checks
- `SECURITY.md` — private vulnerability-reporting and disclosure guidance

If you need to report a security issue, use `SECURITY.md` and prefer a private disclosure path over a public issue.

## Scope

Calamum Vulcan is currently focused on Samsung-first flashing workflows with:

- GUI-first operator flows
- package-aware preflight gating
- structured session evidence
- a bounded Heimdall adapter seam for reviewed runtime execution
- repo-owned read-side device detection, info capture, and PIT-aware inspection evidence for the reviewed Samsung subset
- bounded ADB/Fastboot companion controls for detection and reboot handoffs where native ownership is incomplete

## Support posture for `0.3.0` candidate

| Surface                    | `0.3.0` posture                                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| Windows packaged build     | empirically reviewed                                                                             |
| Linux packaged build       | scripted / installed-artifact validation target only; empirical closeout still pending           |
| macOS                      | deferred and outside the intended `0.3.0` public support boundary                                |
| Core flashing workflow     | simulation-validated                                                                             |
| Read-side inspection lane  | supported as an evidence-first review workflow for the reviewed Samsung subset                    |
| Selective fallback surface | explicit where native ADB/PIT ownership stops; fallback remains visible rather than implied away |
| Live firmware flashing     | not part of the intended `0.3.0` public support boundary                                         |

## Known limitations

| Area                    | Current limitation                                                                                                          |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Transport execution     | the packaged flashing workflow remains fixture-backed rather than public live-subprocess-backed                             |
| Read-side device matrix | native read-side ownership is still limited to the reviewed Samsung subset; fallback and exhausted states remain explicit |
| Host matrix             | Windows is the only empirically reviewed packaged host for the `0.3.0` candidate                                           |
| Qt deployment           | Qt font packaging still emits a warning in some review environments                                                         |
| Fixture debt            | warning-tier checksum placeholder debt remains in legacy fixture manifests                                                  |

## Troubleshooting

| Symptom                                       | Likely cause                                                                                    | What to do                                                                                                               |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `calamum-vulcan` will not launch              | wrong interpreter or missing runtime dependency                                                 | use Python `3.14` and reinstall the wheel so `PySide6>=6.8,<7` is present                                                |
| GUI opens without branded assets              | stale wheel built before the branding assets were packaged                                      | rebuild with `python scripts/build_release_artifacts.py` and reinstall the fresh wheel                                   |
| No device appears in the live companion panel | device is not in the expected mode, ADB is not authorized, or Windows driver state is not ready | re-enter the correct device mode, authorize ADB if applicable, and review the Windows USB/driver posture before retrying |
| Qt prints a font warning during review        | known packaging debt                                                                            | treat it as a non-blocking warning for now; the shell remains usable while the font-packaging lane is hardened           |
| Evidence file was not written where expected  | output path or permissions are wrong                                                            | choose a writable output path and rerun the export command                                                               |

## Release note

The `0.3.0` candidate boundary carries the read-side-close bundle, packaged inspect-only evidence, PIT-aware inspection truth, and the standalone security/adversarial gate forward into packaging. Until the sealed `v0.3.0` boundary is tagged and released, `0.2.0` remains the latest public PyPI/GitHub release.
