Add declarative JSON-manifest mode: session apply

[dkijania]

Summary

Adds deb-toolkit session apply <session-dir> <plan.json>, a declarative twin of the existing CLI verb chain. Every CLI verb has an equivalent manifest step, and both modes dispatch into the same Session methods — anything achievable in one is achievable in the other.

Why

The existing verbs are great for interactive / one-off use, but when the transformation itself is the artifact (CI pipelines, hardfork release engineering, anything reviewed in a PR) a declarative manifest is a much better fit:

• One process, one outcome — the plan either completes or aborts at the failing step.
• Self-documenting — the manifest IS the change list. No wrapper bash script to grep through.
• Path-relative — local source paths are resolved against the manifest's own directory, so a folder containing plan.json + its referenced data files is a portable, hashable bundle.

Situation	Mode
Interactive poking, one-off ops	CLI verbs
Wrapper bash scripts on dev boxes	CLI verbs
CI-driven hardfork generation	JSON manifest
Anything reviewed in a PR	JSON manifest
Reproducible release engineering	JSON manifest

Schema (informal)

```json
{
"description": "Generate mina-hardfork-mainnet from a 3.0.0devnet base",
"steps": [
{ "op": "remove", "pattern": "/var/lib/coda/genesis_ledger_devnet.tar.gz" },
{ "op": "insert", "dest": "/var/lib/coda/genesis_ledger.tar.gz",
"sources": ["./genesis_ledger.tar.gz"] },
{ "op": "rename-package", "new_name": "mina-hardfork-mainnet" },
{ "op": "reversion", "new_version": "4.0.0", "update_deps": true },
{ "op": "replace-suite", "new_suite": "umt" },
{ "op": "read-field", "field": "Version", "expected": "4.0.0" }
]
}
```

Full reference: docs/session-manifest.md.

Notable design choices

• read-field doubles as an assertion primitive — when expected is set, the step fails unless the actual value matches. Lets CI plans pin Version after a reversion step to catch regressions in the verb itself before they ship.
• serde(deny_unknown_fields) everywhere — a typo in a manifest fails at parse time rather than silently changing behaviour.
• No automatic rollback on failure — session mutations are cheap (temp dir) and the original .deb is never touched until session save, so a half-applied session is discardable. Persistent step-state tracking would add complexity for a rarely-exercised "resume" path. Documented in docs/session-manifest.md#failure-semantics.
• Local-source-paths resolve against the manifest dir, not cwd — makes a plan.json + data-files directory a self-contained portable bundle (terraform / docker-compose convention). Package paths (dest, pattern) are unaffected and remain anchored at /.

Documentation added (the user explicitly asked for this to be widely documented)

• docs/session-manifest.md — full schema reference, path resolution rules, failure semantics, idempotency notes, design rationale, when-to-use-which-mode table.
• examples/manifests/README.md — example index.
• examples/manifests/simple-rename.json — minimal worked example.
• examples/manifests/hardfork-bundle/ — complete realistic hardfork bundle (plan + README explaining each step).
• Module-level doc comment on src/session/apply.rs with the same rationale, inline.
• Per-variant doc comments on every Step enum variant.
• README.md gains a "Session subsystem" section pointing at all of the above.

Tests

• 7 new unit tests in apply.rs covering schema validation (deny_unknown_fields, default values, unknown ops, path resolution).
• tests/session_apply.rs — three integration tests:
  • Full hardfork manifest applied end-to-end, including verification that bundle-relative source paths resolve correctly when the manifest lives in its own directory.
  • read-field assertion failure aborts the plan at the failing step (earlier steps remain applied, later steps don't run).
  • Unknown op produces a useful error rather than silently succeeding.

Total: 36 unit + 6 integration tests, all green; clippy and fmt clean.

Test plan

• CI: full cargo test passes.
• CI: cargo clippy --no-deps --all-targets -- -D warnings clean.
• CI: cargo fmt --check clean.
• Manual: run the example hardfork bundle against a real `mina-mainnet` .deb and verify the produced `mina-hardfork-mainnet` package installs cleanly.

🤖 Generated with Claude Code

[dkijania]

Force-pushed a refactor addressing the review feedback:

1. Extracted test utilities (tests/common/mod.rs) — every integration test in tests/ now shares:

• Toolkit — typed wrapper around the deb-toolkit binary with one method per session verb (session_open, session_rename_package, …). Returns a chainable CmdOutput.
• DebFixture — fluent builder for fixture .deb files. Replaces the inline fs::create_dir_all + fs::write(DEBIAN/control) + dpkg-deb --build boilerplate every test used to carry.
• dpkg::info() / dpkg::contents() — assertion helpers.
• skip_unless!("dpkg-deb") macro.

2. Generic naming throughout. Dropped all the mina-specific fixtures and replaced with a project-agnostic example-app → example-app-variant rebrand scenario. Same shape of workflow (rename, reversion, swap data/config, flip suite) but no terminology bias. Affects:

• tests/session_hardfork_scenario.rs → tests/session_variant_scenario.rs
• examples/manifests/hardfork-bundle/ → examples/manifests/variant-bundle/
• docs/session-manifest.md examples
• Module-level docs in src/session/apply.rs

3. Rewrote the existing tests on top of the helpers. Each test now reads top-to-bottom as a narrative — tk.session_rename_package(&session, "...") instead of Command::new(bin).args(["session", "rename-package", ...]).status().unwrap() everywhere. Includes refactoring the already-merged session_roundtrip.rs.

4. The variant-bundle example README explicitly walks through how to adapt the template to a real project — generic enough to be a starting point.

All 36 unit + 6 integration tests still green, clippy and fmt clean.