Add session apply --dry-run

Validates the manifest against an opened session without committing
any change. Useful for CI gates that want to catch typos and broken
bundle paths before the real apply runs.

What gets checked:
  * Parse — schema is well-formed (deny_unknown_fields, missing
    required fields, wrong types — same as a real run).
  * Local source files exist — every `sources` entry in `insert` and
    every `replacement` in `replace` is resolved against the manifest
    directory and verified.
  * Step shape — `insert` with multiple sources but `directory: false`
    is rejected (since the real run would too).

What's intentionally left to the real run:
  * Glob match counts — `remove` / `replace` patterns are matched
    against the live data tree, so we can't tell at validate-time
    whether they'll match zero files.
  * `read-field` assertions — they depend on the cumulative effect
    of earlier (unapplied) steps.

The session directory is left bit-for-bit unchanged.

Tests:
  * 5 new unit tests in `check_step` covering missing-source,
    existing-source, multi-source-without-directory-flag,
    missing-replacement, and metadata-op no-ops.
  * 2 new integration tests: dry-run on a valid plan leaves every
    control field and data file untouched; dry-run on a plan with a
    missing source file surfaces the error.

docs/session-manifest.md gains a "Dry runs" section spelling out
exactly what is and isn't checked.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dkijania

docs/session-manifest.md

@@ -255,6 +255,42 @@ deb-toolkit session apply /tmp/session /elsewhere/variant-bundle/plan.json
 (cd /tmp && deb-toolkit session apply /tmp/session ~/variant-bundle/plan.json)
 ```
 
+## Dry runs
+
+Pass `--dry-run` to `session apply` to validate the manifest against
+an opened session **without committing any change**:
+
+```bash
+deb-toolkit session apply /tmp/session ./plan.json --dry-run
+```
+
+What `--dry-run` checks:
+
+- **Parse** — schema is well-formed (unknown ops, missing required
+  fields, wrong types all fail before the first step runs).
+- **Local files exist** — every `sources` entry in `insert` and every
+  `replacement` in `replace` is resolved against the manifest
+  directory and verified to point at an existing file.
+- **Step shape** — `insert` with `directory: false` and multiple
+  sources is rejected (since the corresponding real run would fail).
+
+What `--dry-run` does **not** check:
+
+- **Glob match counts.** `remove` and `replace` patterns are evaluated
+  against the live data tree, so we can't tell at dry-run time
+  whether a pattern will match zero files (which would fail) without
+  scanning the session.
+- **`read-field` assertions.** Their value depends on the control
+  file's current state, which earlier (unapplied) steps would have
+  changed.
+- **Permission / disk-space issues** at write time.
+
+So `--dry-run` is a CI gate against the manifest itself — it catches
+the typos and broken bundle paths early, but doesn't promise a clean
+real run.
+
+The session directory is left bit-for-bit unchanged.
+
 ## Failure semantics
 
 Steps run sequentially. On the first failure, `apply` returns the error

src/cli.rs

@@ -155,6 +155,12 @@ pub struct SessionApplyArgs {
     pub session_dir: String,
     /// Path to the JSON manifest describing the steps to apply
     pub manifest: String,
+    /// Validate the manifest and log what would happen, but don't
+    /// mutate the session. Local source files referenced by `insert`
+    /// and `replace` are checked for existence; pattern matches and
+    /// control-field assertions are deferred to a real run.
+    #[arg(long = "dry-run", default_value_t = false)]
+    pub dry_run: bool,
 }
 
 #[derive(Subcommand, Debug)]

src/main.rs

@@ -145,7 +145,7 @@ fn dispatch_session(cmd: SessionCommand) -> Result<()> {
                 .ok()
                 .and_then(|p| p.parent().map(|p| p.to_path_buf()))
                 .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")));
-            session::apply(&session, &plan, &manifest_dir)
+            session::apply(&session, &plan, &manifest_dir, args.dry_run)
         }
     }
 }

src/session/apply.rs

@@ -234,31 +234,117 @@ impl Plan {
 /// bundle portable. For programmatically-constructed plans, pass the
 /// directory the source files live in (often the process cwd).
 ///
+/// When `dry_run` is true, no session mutations are performed: each
+/// step's intent is logged, local source files referenced by `insert`
+/// and `replace` are verified to exist, and parse-level errors still
+/// surface — but the control file and data tree under `<session>/` are
+/// left untouched. Useful for CI gates that want to validate a manifest
+/// against an opened session without committing to the change.
+///
 /// Errors abort the apply: see [module-level docs](self) for the
 /// failure-semantics rationale.
-pub fn apply(session: &Session, plan: &Plan, manifest_dir: &Path) -> Result<()> {
+pub fn apply(session: &Session, plan: &Plan, manifest_dir: &Path, dry_run: bool) -> Result<()> {
     if let Some(desc) = &plan.description {
         log::info!("Plan: {}", desc);
     }
-    log::info!("=== Applying {} step(s) ===", plan.steps.len());
+    if dry_run {
+        log::info!(
+            "=== DRY RUN: would apply {} step(s), no changes will be made ===",
+            plan.steps.len()
+        );
+    } else {
+        log::info!("=== Applying {} step(s) ===", plan.steps.len());
+    }
 
     for (idx, step) in plan.steps.iter().enumerate() {
         let step_num = idx + 1;
         log::info!("[{}/{}] {}", step_num, plan.steps.len(), step.summary());
-        apply_step(session, step, manifest_dir).with_context(|| {
-            format!(
-                "Step {} of {} failed ({})",
-                step_num,
-                plan.steps.len(),
-                step.summary()
-            )
-        })?;
+        if dry_run {
+            check_step(step, manifest_dir).with_context(|| {
+                format!(
+                    "Step {} of {} would fail ({})",
+                    step_num,
+                    plan.steps.len(),
+                    step.summary()
+                )
+            })?;
+        } else {
+            apply_step(session, step, manifest_dir).with_context(|| {
+                format!(
+                    "Step {} of {} failed ({})",
+                    step_num,
+                    plan.steps.len(),
+                    step.summary()
+                )
+            })?;
+        }
     }
 
-    log::info!("✓ All {} step(s) applied", plan.steps.len());
+    if dry_run {
+        log::info!(
+            "✓ Dry run complete: {} step(s) validated, no changes applied",
+            plan.steps.len()
+        );
+    } else {
+        log::info!("✓ All {} step(s) applied", plan.steps.len());
+    }
     Ok(())
 }
 
+/// Dry-run validation for a single step. Only checks what can be
+/// verified without mutating the session: that local source files
+/// referenced by `insert` / `replace` exist on disk, and that step
+/// fields are individually well-formed. Does **not** verify that
+/// `remove` / `move` patterns will match anything, since glob
+/// matching requires looking at the live data tree.
+fn check_step(step: &Step, manifest_dir: &Path) -> Result<()> {
+    match step {
+        Step::Insert {
+            sources, directory, ..
+        } => {
+            if sources.is_empty() {
+                return Err(anyhow!("insert: `sources` is empty"));
+            }
+            if !*directory && sources.len() > 1 {
+                return Err(anyhow!(
+                    "insert: {} sources but `directory` is false — must be true to use multiple sources",
+                    sources.len()
+                ));
+            }
+            for s in sources {
+                let p = resolve_local(manifest_dir, s);
+                if !p.exists() {
+                    return Err(anyhow!(
+                        "insert: source file does not exist: {}",
+                        p.display()
+                    ));
+                }
+            }
+            Ok(())
+        }
+        Step::Replace { replacement, .. } => {
+            let p = resolve_local(manifest_dir, replacement);
+            if !p.exists() {
+                return Err(anyhow!(
+                    "replace: replacement file does not exist: {}",
+                    p.display()
+                ));
+            }
+            Ok(())
+        }
+        // The remaining ops are pure metadata mutations or glob-driven
+        // operations whose outcome depends on session state. They have
+        // nothing to validate at dry-run time beyond what the schema
+        // already enforced at parse time.
+        Step::RenamePackage { .. }
+        | Step::ReplaceSuite { .. }
+        | Step::Reversion { .. }
+        | Step::Remove { .. }
+        | Step::Move { .. }
+        | Step::ReadField { .. } => Ok(()),
+    }
+}
+
 impl Step {
     /// A short one-line label for the step, used in log lines and error
     /// context so the user can pinpoint which step failed without
@@ -454,4 +540,82 @@ mod tests {
         let r = resolve_local(Path::new("/manifests"), "data/foo.tar.gz");
         assert_eq!(r, PathBuf::from("/manifests/data/foo.tar.gz"));
     }
+
+    // --- check_step (dry-run validation) ---------------------------------
+
+    #[test]
+    fn check_step_insert_rejects_missing_source() {
+        let tmp = tempfile::tempdir().unwrap();
+        let step = Step::Insert {
+            dest: "/x".into(),
+            sources: vec!["./missing.bin".into()],
+            directory: false,
+        };
+        let err = check_step(&step, tmp.path()).unwrap_err();
+        assert!(err.to_string().contains("does not exist"), "{}", err);
+    }
+
+    #[test]
+    fn check_step_insert_accepts_existing_source() {
+        let tmp = tempfile::tempdir().unwrap();
+        std::fs::write(tmp.path().join("there.bin"), b"x").unwrap();
+        let step = Step::Insert {
+            dest: "/x".into(),
+            sources: vec!["./there.bin".into()],
+            directory: false,
+        };
+        check_step(&step, tmp.path()).unwrap();
+    }
+
+    #[test]
+    fn check_step_insert_rejects_multi_source_without_directory_flag() {
+        let tmp = tempfile::tempdir().unwrap();
+        std::fs::write(tmp.path().join("a"), b"a").unwrap();
+        std::fs::write(tmp.path().join("b"), b"b").unwrap();
+        let step = Step::Insert {
+            dest: "/x".into(),
+            sources: vec!["./a".into(), "./b".into()],
+            directory: false,
+        };
+        let err = check_step(&step, tmp.path()).unwrap_err();
+        assert!(err.to_string().contains("directory"), "{}", err);
+    }
+
+    #[test]
+    fn check_step_replace_rejects_missing_replacement() {
+        let tmp = tempfile::tempdir().unwrap();
+        let step = Step::Replace {
+            pattern: "/x".into(),
+            replacement: "./missing".into(),
+        };
+        let err = check_step(&step, tmp.path()).unwrap_err();
+        assert!(err.to_string().contains("does not exist"), "{}", err);
+    }
+
+    #[test]
+    fn check_step_metadata_ops_have_nothing_to_check() {
+        // None of these touch the filesystem at validate-time.
+        check_step(
+            &Step::RenamePackage {
+                new_name: "x".into(),
+            },
+            Path::new("/"),
+        )
+        .unwrap();
+        check_step(
+            &Step::Reversion {
+                new_version: "1.0".into(),
+                update_deps: false,
+            },
+            Path::new("/"),
+        )
+        .unwrap();
+        check_step(
+            &Step::Remove {
+                pattern: "/x/*".into(),
+            },
+            Path::new("/"),
+        )
+        .unwrap();
+    }
 }

tests/common/mod.rs

@@ -192,6 +192,15 @@ impl Toolkit {
             manifest.as_os_str(),
         ])
     }
+
+    pub fn session_apply_dry_run(&self, session_dir: &Path, manifest: &Path) -> CmdOutput {
+        self.session([
+            OsStr::new("apply"),
+            OsStr::new("--dry-run"),
+            session_dir.as_os_str(),
+            manifest.as_os_str(),
+        ])
+    }
 }
 
 impl Default for Toolkit {

tests/session_apply.rs

@@ -185,3 +185,79 @@ fn apply_rejects_unknown_op() {
 
     tk.session_apply(&session, &plan).assert_failure();
 }
+
+#[test]
+fn apply_dry_run_leaves_session_untouched() {
+    skip_unless!("dpkg-deb");
+
+    let tk = Toolkit::new();
+    let tmp = tempfile::tempdir().unwrap();
+
+    let input = DebFixture::new("example-app")
+        .version("1.0.0")
+        .file("/var/lib/example/data.bin", b"ORIGINAL\n".to_vec())
+        .build(&tmp.path().join("input.deb"));
+
+    // Bundle with a valid plan that, if actually applied, would change
+    // every field we check afterwards.
+    let bundle = tmp.path().join("bundle");
+    std::fs::create_dir_all(&bundle).unwrap();
+    std::fs::write(bundle.join("new_data.bin"), b"NEW\n").unwrap();
+    std::fs::write(
+        bundle.join("plan.json"),
+        r#"{ "steps": [
+            { "op": "rename-package", "new_name": "would-be-renamed" },
+            { "op": "reversion", "new_version": "9.9.9" },
+            { "op": "insert", "dest": "/var/lib/example/data.bin",
+              "sources": ["./new_data.bin"] }
+        ] }"#,
+    )
+    .unwrap();
+
+    let session = tmp.path().join("session");
+    tk.session_open(&input, &session).assert_success();
+
+    tk.session_apply_dry_run(&session, &bundle.join("plan.json"))
+        .assert_success();
+
+    // Control fields untouched.
+    let pkg = tk.session_read_field(&session, "Package").assert_success();
+    assert_eq!(pkg.stdout_trim(), "example-app");
+    let ver = tk.session_read_field(&session, "Version").assert_success();
+    assert_eq!(ver.stdout_trim(), "1.0.0");
+
+    // Data file untouched.
+    let data = std::fs::read(session.join("data/var/lib/example/data.bin")).unwrap();
+    assert_eq!(data, b"ORIGINAL\n");
+}
+
+#[test]
+fn apply_dry_run_catches_missing_source_file() {
+    skip_unless!("dpkg-deb");
+
+    let tk = Toolkit::new();
+    let tmp = tempfile::tempdir().unwrap();
+
+    let input = DebFixture::new("example-app")
+        .file("/usr/share/example/x", b"x\n".to_vec())
+        .build(&tmp.path().join("input.deb"));
+
+    // The plan references ./does-not-exist.bin — dry-run should
+    // surface this before the user runs the real apply.
+    let plan = tmp.path().join("plan.json");
+    std::fs::write(
+        &plan,
+        r#"{ "steps": [
+            { "op": "insert", "dest": "/var/lib/example/data.bin",
+              "sources": ["./does-not-exist.bin"] }
+        ] }"#,
+    )
+    .unwrap();
+
+    let session = tmp.path().join("session");
+    tk.session_open(&input, &session).assert_success();
+
+    tk.session_apply_dry_run(&session, &plan)
+        .assert_failure()
+        .stderr_contains("does not exist");
+}