[how2how2how2-arch]

Refs #28

Summary

Adds one job, smoke, to .github/workflows/ci.yml. It installs the package, starts the console script, and round-trips a saved trace on macOS and Windows. The existing test job is not modified — the diff is additions only (63 insertions, 0 deletions).

I commented the proposal on the issue first, as its text asks. This PR is that proposal, runnable.

Changes

smoke:
  runs-on: ${{ matrix.os }}          # macos-latest, windows-latest
  matrix.python-version: ["3.11", "3.13"]

Steps: uv sync --locked → stepfork --version → stepfork --help → pytest tests/unit/test_storage.py tests/unit/test_cli.py -q.

Why this subset:

• test_storage.py is the trace save/load surface (every test uses tmp_path), and test_cli.py covers help, version and no-command. Together they are the "installation, CLI startup, trace save/load" the issue names.
• Both are fast and offline — 28 tests in 0.46 s on the machine below — so this stays a smoke job rather than a second full matrix.
• Both use tmp_path or the in-process CliRunner, so neither reads a committed .sftrace bundle. That matters, see the limitation below.
• The console script is exercised directly (stepfork --version), because a missing or broken entry point on a new OS is the failure this job exists to catch, and the in-process runner would not see it.

Python versions are 3.11 and 3.13, the lowest and highest supported per requires-python. The middle version stays covered by the Linux matrix; that is a deliberate cost choice, not a claim of equal coverage. Adding 3.12 takes it from 4 jobs to 6.

Platform limitation found, documented in the job rather than fixed here

Checking whether the job could actually be green turned up a cross-platform issue worth its own change:

• trace/integrity.py::_hash_file and export/receipt.py::bundle_digest hash file bytes;
• the writers in trace/storage.py use write_text and path.open("w") without newline="";
• there are 37 committed .sftrace/integrity files under examples/ and tests/golden/, and no .gitattributes.

So a bundle written on Windows contains \r\n and cannot reproduce a digest recorded on Linux, and on windows-latest git's default core.autocrlf=true rewrites those committed files to CRLF at checkout, before any test runs. A Windows job that read them would fail for a reason unrelated to installation. The fix is newline="" on the writers and/or .gitattributes with eol=lf; it changes the on-disk format contract, so it should have its own test rather than ride along in a CI PR. Happy to do it next if you want it.

Testing

I can only test the macOS half locally: this machine is macOS arm64, Python 3.13.9. Running the job's exact commands:

$ uv run --no-sync stepfork --version
stepfork 0.2.1

$ uv run --no-sync stepfork --help        # exit 0

$ uv run --no-sync pytest tests/unit/test_storage.py tests/unit/test_cli.py -q
28 passed in 0.46s

The workflow file parses, and both jobs are present:

jobs: ['test', 'smoke']
  test  | runs-on: ubuntu-latest   | steps: 9 | matrix: {'python-version': ['3.11', '3.12', '3.13']}
  smoke | runs-on: ${{ matrix.os }} | steps: 7 | matrix: {'os': ['macos-latest', 'windows-latest'], 'python-version': ['3.11', '3.13']}

I have no Windows machine, so the Windows jobs are unverified by me until CI runs them here. That is what this PR is for; if they fail, the failure log is the deliverable.

Checklist

• Tests added/updated — no test changes needed; this job runs existing tests
• pytest passes
• ruff check passes (no Python changed)
• ruff format check passes (no Python changed)
• mypy passes (no Python changed)
• docs updated if necessary — the limitation is documented in the workflow comments; a docs page can follow if you want it user-facing
• no secrets/sensitive traces included

[how2how2how2-arch]

CI has run: all eight jobs pass, including the four this PR adds.

Smoke macos-latest / Python 3.11     pass   18s
Smoke macos-latest / Python 3.13     pass   25s
Smoke windows-latest / Python 3.11   pass   37s
Smoke windows-latest / Python 3.13   pass   27s

So the part of the description that said the Windows jobs were "unverified by me" is now answered by CI, and I could not have produced that answer from here.

One thing this result does not establish, stated so nobody reads "Windows smoke passes" as more than it is: it does not show that a bundle written on Windows is interchangeable with one written on Linux. Every save/load test in test_storage.py writes and reads back inside one platform, so CRLF on disk is self-consistent and invisible. The byte-digest difference described in the body is still open, and still needs its own change. If you want, I can follow up with newline="" on the writers plus a .gitattributes carrying eol=lf, and a test that asserts a bundle's digest is identical whichever platform wrote it — that is the assertion this job cannot make.

[utsab345]

Thanks for opening this PR and for the fix, @how2how2how2-arch. The new macOS and Windows smoke jobs are green, and documenting the CRLF digest limitation as a follow up was the right call. Appreciate the detailed testing notes. Merged.