Metadata-Version: 2.4
Name: calamum_vulcan
Version: 0.2.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.2.0` is the current packaged-and-pushed release boundary in this repository. The latest publicly published registry/release boundary remains `0.1.0` until the `0.2.0` publication lane is executed.

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.2.0`
- current push boundary: `v0.2.0` on the nested release repo
- latest public PyPI/GitHub release: `0.1.0`
- live PyPI project: `https://pypi.org/project/calamum-vulcan/`
- live GitHub release: `https://github.com/joediggidyyy/calamum_vulcan/releases/tag/v0.1.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 orchestration-close --suite-format markdown --suite-output temp/fs2_07_orchestration_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.2.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.

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.2.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
- bounded ADB/Fastboot companion controls for detection and reboot handoffs

## Support posture for `0.2.0`

| Surface                 | `0.2.0` posture                                                   |
| ----------------------- | ----------------------------------------------------------------- |
| Windows packaged build  | empirically reviewed                                              |
| Linux packaged build    | scripted-simulation target only; empirical closeout still pending |
| macOS                   | deferred and outside the published `0.2.0` support boundary       |
| Core flashing workflow  | simulation-validated                                              |
| Live companion controls | bounded lab review only for device detection and reboot handoffs  |
| Live firmware flashing  | not part of the published `0.2.0` support boundary                |

## Known limitations

| Area                  | Current limitation                                                                                            |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| Transport execution   | the published flashing workflow remains fixture-backed rather than live-subprocess-backed                     |
| PIT operator controls | PIT download and print capabilities exist at the adapter seam but are not yet exposed as public shell actions |
| Host matrix           | Windows is the only empirically reviewed packaged host for `0.2.0`                                            |
| Qt deployment         | Qt font packaging still emits a warning in some review environments                                           |

## 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 `0.2.0` 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

`calamum-vulcan==0.2.0` is the current source/package boundary for this repository and is validated through local build, installed-artifact, scripted-simulation, and empirical-review gates before push. The last public registry/release publication still points at `0.1.0`.
