feat(cli): pearlite reconcile subcommand + vm-10 scenario (#67)

UnbreakableMJ · claude · web-flow · commit 3bf14b68bd93 · 2026-05-05T07:22:58.000Z
* docs(todo): refresh post-#65 reconcile + bootstrap status TODO.md was 8 days stale. Marks the M4 W1 reconcile read-side (Engine::reconcile, #65) as done; resolves the M3 W1 runuser / per-user nix.conf line as the bootstrap stack (#55-#58) plus ADR-0013 (Home Manager owns per-user nix.conf); updates the M3 W2 vm-09 prose to reflect that vm-09-nix-bootstrap.sh shipped in M4 W1 (#59) rather than remaining deferred. Bumps Last updated to 2026-05-04. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cli): pearlite reconcile subcommand wires Engine::reconcile Read-only CLI surface for the M4 W1 reconcile read-side that landed in #65. Adds Command::Reconcile (no flags), dispatch_reconcile, reconcile_outcome_view, and reconcile_error_payload mapping every pearlite_engine::ReconcileError variant to a typed error code: RECONCILE_PROBE_FAILED — probe adapter failure RECONCILE_EMPTY_HOSTNAME — /etc/hostname is blank RECONCILE_INVALID_HOSTNAME — `/`, `\`, or NUL in hostname RECONCILE_ALREADY_EXISTS — refuses to clobber operator review RECONCILE_IO_FAILED — mkdir or atomic-write failure All five are class=preflight, exit_code=2 — reconcile is read-only with respect to state.toml; the only system-side effect is the atomic write of <config_dir>/hosts/<hostname>.imported.ncl, and a failed write leaves the operator's config repo untouched (tempfile is dropped before rename). Three dispatch tests cover the happy path (writes the imported.ncl to disk and returns hostname + path in the envelope), the already-exists guard (pre-seeded file is preserved verbatim), and the metadata.command label. Out of scope for this chunk: - `--commit` and `--adopt-all` flags (need Engine::reconcile_commit) - vm-10-reconcile-fresh-install.sh Refs: PRD §11, Plan §7.5 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * style(cli): rustfmt reconcile dispatch tests Two mechanical wrappings flagged by `cargo fmt --all --check`: - assert! is_file() chain breaks across lines - let preserved = ... fits on a single line at 100 cols No behavior change. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor(cli): extract dispatch_plan_or_status to fit too_many_lines Adding `Command::Reconcile` pushed `dispatch()` to 101 lines (clippy limit is 100). Pulled the inline Plan/Status arm into `dispatch_plan_or_status`, mirroring the existing extraction pattern for Apply, Bootstrap, Reconcile, etc. Behavior is identical; read-only test run via cargo test -p pearlite-cli passes 42 tests under WSL Arch. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(vm): vm-10 reconcile-fresh-install scenario Verifies the read-side reconcile pipeline end-to-end against the `pearlite reconcile` CLI shipped earlier in this branch. Phase A (happy path): - exit 0 - envelope: command=pearlite reconcile, hostname non-empty, imported_path resolves to <sandbox>/repo/hosts/<hostname>.imported.ncl - on-disk file contains the Nickel record markers emit_host produces (meta = {, kernel = {, packages = {, services = {) Phase B (clobber refusal): - re-running with the same --config-dir exits 2 with RECONCILE_ALREADY_EXISTS, class=preflight - the original .imported.ncl is byte-identical to the Phase A capture (cmp -s) Whitelisted alongside vm-01 in scripts/ci/run-vm-tests.sh -- vm-10 is read-only with respect to system state (only mutation is a single Nickel file inside a tempdir), so it runs unconditionally without PEARLITE_VM_TEST=1. Verified locally via WSL Arch: bash tests/vm/vm-10-reconcile-fresh-install.sh -> PASS Refs: PRD §11, Plan §7.5 Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(todo): mark vm-10 reconcile-fresh-install done Shipped earlier in this branch (commit 3d22c36) and verified locally via WSL Arch. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(agents): document pearlite reconcile flow + error codes Adds a Reconcile-flow section enumerating the five RECONCILE_* error codes and the read-only / interactive split, so future agents can discover the surface without re-deriving it from dispatch.rs. Notes the users / config empty-array placeholders as intentional per PRD §11, references vm-10 for end-to-end coverage, and points at the M4 W1 remainder (reconcile --commit). Bumps Last updated to 2026-05-04. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/AGENTS.md b/AGENTS.md
@@ -108,6 +108,36 @@ The five-way taxonomy is fixed. Never invent a sixth.
 
 Get this wrong and Pearlite removes packages the user wants to keep.
 
+## Reconcile flow (PRD §11, M4 W1)
+
+`pearlite reconcile` (read-only) probes the live system and writes a fresh
+`<config_dir>/hosts/<hostname>.imported.ncl` as a **review draft** for operator
+hand-curation. The emitted Nickel record carries `meta`, `kernel`, `packages`,
+and `services` blocks from probe data; `users` and `config` are deliberately
+emitted as empty arrays per PRD §11 (no `/etc/passwd` enumeration; no clobbering
+of operator config-repo paths). The imported file is a draft, not a validated
+declaration — the operator hand-curates it and renames it to `<hostname>.ncl`
+for the next `pearlite plan`.
+
+The interactive counterpart `pearlite reconcile --commit` (M4 W1 remainder)
+commits the import to `state.toml` with a drift-threshold safety check. Until
+it lands, reconcile only writes the review draft.
+
+Error codes (all class 1 preflight, exit 2 — reconcile never mutates
+`state.toml` and a failed atomic write leaves the operator config repo
+untouched):
+
+| `error.code` | Triggers |
+|---|---|
+| `RECONCILE_PROBE_FAILED` | adapter failure during probe |
+| `RECONCILE_EMPTY_HOSTNAME` | blank `/etc/hostname` |
+| `RECONCILE_INVALID_HOSTNAME` | `/`, `\`, or NUL in hostname |
+| `RECONCILE_ALREADY_EXISTS` | refuses to clobber an existing imported.ncl |
+| `RECONCILE_IO_FAILED` | mkdir or atomic-write failure |
+
+VM-tier coverage: [`tests/vm/vm-10-reconcile-fresh-install.sh`](tests/vm/vm-10-reconcile-fresh-install.sh)
+exercises the read-side end-to-end (happy path + clobber refusal).
+
 ## Always
 
 - Run `cargo clippy --workspace --all-targets -- -D warnings` before claiming a
@@ -152,4 +182,4 @@ Do not propose names outside this convention.
 
 ---
 
-*Last updated: 2026-04-27.*
+*Last updated: 2026-05-04.*
diff --git a/TODO.md b/TODO.md
@@ -86,24 +86,24 @@
 ### Week 1 — Adapter and bootstrap
 - [✓] `pearlite-userenv` with `HomeManagerBackend` (PR #44)
 - [✓] `DeterminateNixInstaller` (hash-pinned curl|sh) + `MockInstaller` (PR #45)
-- [~] `runuser` drop wrapper; per-user `nix.conf` handling — runuser wrap shipped via `LiveHmBackend`; per-user `nix.conf` provisioning deferred to M4 alongside the bootstrap-config story
+- [✓] `runuser` drop wrapper; per-user `nix.conf` handling — runuser wrap shipped via `LiveHmBackend`; bootstrap-config story landed in M4 W1 (PRs #55–#58); per-user `nix.conf` resolved as Home Manager's responsibility per ADR-0013
 
 ### Week 2 — Engine integration
 - [✓] Wire phase 7 into `pearlite-engine::apply` (PRs #46 / #47 / #50)
 - [✓] Extend `state.toml` schema with `[[managed.user_env]]` (PR #50; schema already shipped in M1)
 - [✓] `pearlite-diff` surfaces HM config-hash drift (PRs #48 / #49)
-- [✓] VM scenarios: `vm-07` user-env apply, `vm-08` user-env drift (PR #51); `vm-09` Nix bootstrap deferred until `LiveNixInstaller` has a wired apply-time caller (M4 W1)
+- [✓] VM scenarios: `vm-07` user-env apply, `vm-08` user-env drift (PR #51); `vm-09` Nix bootstrap shipped in M4 W1 (PR #59)
 - [~] Tag `m3-exit` (signed tag from this commit)
 
 ---
 
 ## M4 — Reconcile and Codify (2 weeks)
 
 ### Week 1 — Reconcile flow
-- [ ] `pearlite-engine::reconcile()` (read-only) → writes `hosts/<host>.imported.ncl`
+- [✓] `pearlite-engine::reconcile()` (read-only) → writes `hosts/<host>.imported.ncl` (PR #65)
 - [ ] `pearlite-engine::reconcile_commit()` — interactive prompts, drift threshold safety, state.toml write
 - [ ] `pearlite reconcile`, `reconcile --commit`, `--adopt-all`
-- [ ] VM scenario `vm-10-reconcile-fresh-install.sh`
+- [✓] VM scenario `vm-10-reconcile-fresh-install.sh` (PR #67)
 
 ### Week 2 — Codify and the sidecar
 - [ ] Codified sidecar emitter — deterministic, byte-identical re-emission
@@ -187,4 +187,4 @@ Defer until ADR is written; each blocks a specific milestone exit.
 
 ---
 
-*Last updated: 2026-04-27. Mirrors `Pearlite-Plan-v1.0.docx`.*
+*Last updated: 2026-05-04. Mirrors `Pearlite-Plan-v1.0.docx`.*
diff --git a/crates/pearlite-cli/src/args.rs b/crates/pearlite-cli/src/args.rs
@@ -162,6 +162,20 @@ pub enum Command {
         #[arg(long, default_value = "/etc/nix/nix.conf")]
         nix_conf: PathBuf,
     },
+    /// Probe the live system and write a fresh
+    /// `<config_dir>/hosts/<hostname>.imported.ncl` for operator review.
+    ///
+    /// Read-only with respect to `state.toml`: probes pacman, cargo,
+    /// systemd, and the kernel via `Engine::reconcile`, renders the
+    /// result through `pearlite_nickel::emit_host`, and lands the text
+    /// at the imported path. Refuses to clobber an existing
+    /// `.imported.ncl` — `RECONCILE_ALREADY_EXISTS` surfaces and the
+    /// operator removes or renames it before retrying.
+    ///
+    /// The interactive `--commit` and `--adopt-all` flags that mutate
+    /// `state.toml` ride along with `Engine::reconcile_commit` in a
+    /// follow-up PR (M4 W1 remainder).
+    Reconcile,
 }
 
 /// Sub-actions for [`Command::Gen`].
diff --git a/crates/pearlite-cli/src/dispatch.rs b/crates/pearlite-cli/src/dispatch.rs
@@ -70,32 +70,7 @@ pub fn dispatch(args: &Args, ctx: &RunContext) -> Envelope {
 
     match &args.command {
         Command::Plan { host_file } | Command::Status { host_file } => {
-            let host_path = host_file
-                .clone()
-                .unwrap_or_else(|| default_host_file(&args.config_dir, &ctx.fallback_host));
-            let state = match read_state_or_empty(&ctx.state_path, &ctx.fallback_host) {
-                Ok(s) => s,
-                Err(payload) => {
-                    return Envelope::failure(metadata_at(None), payload);
-                }
-            };
-            match ctx.engine.plan(&host_path, &state, false) {
-                Ok(plan) => match serde_json::to_value(&plan) {
-                    Ok(v) => Envelope::success(metadata_at(Some(plan.host)), v),
-                    Err(e) => Envelope::failure(
-                        metadata_at(None),
-                        ErrorPayload {
-                            code: "RENDER_FAILED".to_owned(),
-                            class: "internal".to_owned(),
-                            exit_code: 1,
-                            message: format!("could not serialize plan: {e}"),
-                            hint: "report this as a Pearlite bug".to_owned(),
-                            details: serde_json::Value::Null,
-                        },
-                    ),
-                },
-                Err(e) => Envelope::failure(metadata_at(None), engine_error_payload(&e)),
-            }
+            dispatch_plan_or_status(args, ctx, host_file.as_ref(), &metadata_at)
         }
         Command::Apply {
             host_file,
@@ -138,6 +113,7 @@ pub fn dispatch(args: &Args, ctx: &RunContext) -> Envelope {
             nix_conf,
             &metadata_at,
         ),
+        Command::Reconcile => dispatch_reconcile(args, ctx, &metadata_at),
         Command::Schema { bare } => {
             if *bare {
                 Envelope::success(metadata_at(None), bare_schema())
@@ -159,6 +135,48 @@ pub fn dispatch(args: &Args, ctx: &RunContext) -> Envelope {
     }
 }
 
+/// Dispatch arm for `pearlite plan` and `pearlite status`.
+///
+/// Both subcommands share the same read-only flow: load the state file
+/// (tolerating its absence — a fresh host has no `state.toml` yet),
+/// run [`Engine::plan`], and either serialize the plan or surface a
+/// typed error payload. Pulled out of [`dispatch`] so the top-level
+/// match stays under clippy's `too_many_lines` limit; logic is
+/// otherwise identical to the previous inline form.
+fn dispatch_plan_or_status(
+    args: &Args,
+    ctx: &RunContext,
+    host_file: Option<&PathBuf>,
+    metadata_at: &dyn Fn(Option<String>) -> Metadata,
+) -> Envelope {
+    let host_path = host_file
+        .cloned()
+        .unwrap_or_else(|| default_host_file(&args.config_dir, &ctx.fallback_host));
+    let state = match read_state_or_empty(&ctx.state_path, &ctx.fallback_host) {
+        Ok(s) => s,
+        Err(payload) => {
+            return Envelope::failure(metadata_at(None), payload);
+        }
+    };
+    match ctx.engine.plan(&host_path, &state, false) {
+        Ok(plan) => match serde_json::to_value(&plan) {
+            Ok(v) => Envelope::success(metadata_at(Some(plan.host)), v),
+            Err(e) => Envelope::failure(
+                metadata_at(None),
+                ErrorPayload {
+                    code: "RENDER_FAILED".to_owned(),
+                    class: "internal".to_owned(),
+                    exit_code: 1,
+                    message: format!("could not serialize plan: {e}"),
+                    hint: "report this as a Pearlite bug".to_owned(),
+                    details: serde_json::Value::Null,
+                },
+            ),
+        },
+        Err(e) => Envelope::failure(metadata_at(None), engine_error_payload(&e)),
+    }
+}
+
 /// Dispatch arm for `pearlite apply`.
 ///
 /// Plan → apply → render. Pulled out of [`dispatch`] so the top-level
@@ -409,6 +427,98 @@ fn bootstrap_error_payload(err: &pearlite_engine::BootstrapError) -> ErrorPayloa
     }
 }
 
+/// Dispatch arm for `pearlite reconcile` (read-only).
+///
+/// Probes the live system and writes
+/// `<config_dir>/hosts/<hostname>.imported.ncl` via
+/// [`Engine::reconcile`]. Does not touch `state.toml` — the operator
+/// reviews the import, hand-curates it, and renames it to
+/// `<hostname>.ncl` for `pearlite plan` to pick up. The interactive
+/// `--commit` and `--adopt-all` flags (which DO mutate state) ride
+/// along with `Engine::reconcile_commit` in a follow-up PR.
+fn dispatch_reconcile(
+    args: &Args,
+    ctx: &RunContext,
+    metadata_at: &dyn Fn(Option<String>) -> Metadata,
+) -> Envelope {
+    match ctx.engine.reconcile(&args.config_dir) {
+        Ok(outcome) => Envelope::success(
+            metadata_at(Some(outcome.hostname.clone())),
+            reconcile_outcome_view(&outcome),
+        ),
+        Err(e) => Envelope::failure(metadata_at(None), reconcile_error_payload(&e)),
+    }
+}
+
+/// Render-friendly view of [`pearlite_engine::ReconcileOutcome`].
+fn reconcile_outcome_view(outcome: &pearlite_engine::ReconcileOutcome) -> serde_json::Value {
+    serde_json::json!({
+        "imported_path": outcome.path.to_string_lossy(),
+        "hostname": outcome.hostname,
+    })
+}
+
+/// Map `ReconcileError` to a typed [`ErrorPayload`].
+///
+/// Reconcile is class 1 (preflight) throughout: the only system-side
+/// effect is the atomic write of the `.imported.ncl` file, and a
+/// failure of that write leaves the operator's config repo untouched
+/// (the temp file is dropped). `state.toml` is never read or written
+/// on this path, so no recoverable/incoherent classes apply.
+fn reconcile_error_payload(err: &pearlite_engine::ReconcileError) -> ErrorPayload {
+    use pearlite_engine::ReconcileError as R;
+    match err {
+        R::Probe(e) => ErrorPayload {
+            code: "RECONCILE_PROBE_FAILED".to_owned(),
+            class: "preflight".to_owned(),
+            exit_code: 2,
+            message: format!("probing live system failed: {e}"),
+            hint: "run `pearlite plan` first to surface the underlying probe error".to_owned(),
+            details: serde_json::Value::Null,
+        },
+        R::EmptyHostname => ErrorPayload {
+            code: "RECONCILE_EMPTY_HOSTNAME".to_owned(),
+            class: "preflight".to_owned(),
+            exit_code: 2,
+            message: "probe returned an empty hostname".to_owned(),
+            hint: "set /etc/hostname to a non-empty value, then re-run `pearlite reconcile`"
+                .to_owned(),
+            details: serde_json::Value::Null,
+        },
+        R::InvalidHostname { hostname } => ErrorPayload {
+            code: "RECONCILE_INVALID_HOSTNAME".to_owned(),
+            class: "preflight".to_owned(),
+            exit_code: 2,
+            message: format!("hostname {hostname:?} is not a valid filename component"),
+            hint: "set /etc/hostname to an RFC-1123-compliant value (no `/`, `\\`, or NUL)"
+                .to_owned(),
+            details: serde_json::json!({ "hostname": hostname }),
+        },
+        R::AlreadyExists { path } => ErrorPayload {
+            code: "RECONCILE_ALREADY_EXISTS".to_owned(),
+            class: "preflight".to_owned(),
+            exit_code: 2,
+            message: format!("{} already exists", path.display()),
+            hint: format!(
+                "rm {} or rename it before re-running `pearlite reconcile`",
+                path.display()
+            ),
+            details: serde_json::json!({ "path": path.to_string_lossy() }),
+        },
+        R::Io { path, source } => ErrorPayload {
+            code: "RECONCILE_IO_FAILED".to_owned(),
+            class: "preflight".to_owned(),
+            exit_code: 2,
+            message: format!("I/O error at {}: {source}", path.display()),
+            hint: format!(
+                "ensure pearlite can write to {}; re-run as the user who owns the config repo",
+                path.display()
+            ),
+            details: serde_json::json!({ "path": path.to_string_lossy() }),
+        },
+    }
+}
+
 /// Default plans directory: `<state_file dir>/plans`.
 ///
 /// Mirrors [`default_failures_dir`]: on a production install with
@@ -693,6 +803,7 @@ fn label_for(command: &Command) -> String {
         },
         Command::Schema { .. } => "pearlite schema".to_owned(),
         Command::Bootstrap { .. } => "pearlite bootstrap".to_owned(),
+        Command::Reconcile => "pearlite reconcile".to_owned(),
     }
 }
 
@@ -2325,4 +2436,87 @@ expected_sha256 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abc
             env.error
         );
     }
+
+    fn args_for_reconcile(config_dir: PathBuf, state_file: PathBuf) -> Args {
+        Args {
+            format: OutputFormat::Json,
+            config_dir,
+            state_file,
+            command: Command::Reconcile,
+        }
+    }
+
+    #[test]
+    fn reconcile_dispatches_through_engine_and_writes_imported_ncl() {
+        let dir = TempDir::new().expect("tempdir");
+        let config_dir = dir.path().join("repo");
+        let state_path = dir.path().join("state.toml");
+        // ctx_with seeds a host file path into MockNickel, but reconcile
+        // never consults the evaluator (see reconcile.rs:174). Any path
+        // is fine here.
+        let host = config_dir.join("hosts").join("forge.ncl");
+
+        let ctx = ctx_with(host, MINIMAL_HOST, state_path.clone());
+        let args = args_for_reconcile(config_dir.clone(), state_path);
+        let env = dispatch(&args, &ctx);
+
+        assert!(env.error.is_none(), "got error {:?}", env.error);
+        let data = env.data.expect("data populated");
+        assert_eq!(
+            data.get("hostname").and_then(serde_json::Value::as_str),
+            Some("forge")
+        );
+        let path_str = data
+            .get("imported_path")
+            .and_then(serde_json::Value::as_str)
+            .expect("imported_path");
+        assert!(
+            path_str.ends_with("forge.imported.ncl"),
+            "imported_path was {path_str}"
+        );
+        assert!(
+            config_dir
+                .join("hosts")
+                .join("forge.imported.ncl")
+                .is_file(),
+            "imported.ncl was not written to disk"
+        );
+    }
+
+    #[test]
+    fn reconcile_surfaces_already_exists_when_file_present() {
+        let dir = TempDir::new().expect("tempdir");
+        let config_dir = dir.path().join("repo");
+        let hosts = config_dir.join("hosts");
+        std::fs::create_dir_all(&hosts).expect("mkdir");
+        std::fs::write(hosts.join("forge.imported.ncl"), b"prior").expect("seed");
+
+        let state_path = dir.path().join("state.toml");
+        let host = config_dir.join("hosts").join("forge.ncl");
+
+        let ctx = ctx_with(host, MINIMAL_HOST, state_path.clone());
+        let args = args_for_reconcile(config_dir.clone(), state_path);
+        let env = dispatch(&args, &ctx);
+
+        let err = env.error.expect("must error");
+        assert_eq!(err.code, "RECONCILE_ALREADY_EXISTS");
+        assert_eq!(err.class, "preflight");
+        assert_eq!(err.exit_code, 2);
+        // Pre-seeded file must be untouched.
+        let preserved = std::fs::read_to_string(hosts.join("forge.imported.ncl")).expect("read");
+        assert_eq!(preserved, "prior");
+    }
+
+    #[test]
+    fn reconcile_metadata_command_label() {
+        let dir = TempDir::new().expect("tempdir");
+        let config_dir = dir.path().join("repo");
+        let state_path = dir.path().join("state.toml");
+        let host = config_dir.join("hosts").join("forge.ncl");
+
+        let ctx = ctx_with(host, MINIMAL_HOST, state_path.clone());
+        let args = args_for_reconcile(config_dir, state_path);
+        let env = dispatch(&args, &ctx);
+        assert_eq!(env.metadata.command, "pearlite reconcile");
+    }
 }
diff --git a/scripts/ci/run-vm-tests.sh b/scripts/ci/run-vm-tests.sh
diff --git a/tests/vm/vm-10-reconcile-fresh-install.sh b/tests/vm/vm-10-reconcile-fresh-install.sh
