mandrel 1.60.0 → 1.62.0

package/lib/cli/registry.js

@@ -26,7 +26,17 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import {
+  REQUIRED_NODE_CEILING_MAJOR,
+  REQUIRED_NODE_FLOOR,
+  satisfiesNodeEngine,
+} from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
+import {
+  defaultResolvePackageRoot,
+  listFiles as listPayloadFiles,
+} from './sync.js';
 import { readCache } from './version-check.js';
+import { compareVersions as compareSemver } from './version-helpers.js';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -53,32 +63,6 @@ function spawn(cmd, args) {
 // check: node-version
 // ---------------------------------------------------------------------------
 
-/**
- * The minimum Node version the framework requires (`engines.node`).
- * Mirrors `lib/bootstrap/project-bootstrap.js#REQUIRED_NODE_FLOOR`.
- */
-const REQUIRED_NODE_FLOOR = '22.22.1';
-const REQUIRED_NODE_CEILING_MAJOR = 25;
-
-/**
- * Return true when `version` satisfies `>=22.22.1 <25`.
- *
- * @param {string} version
- * @returns {boolean}
- */
-function satisfiesNodeEngine(version) {
-  const [majorRaw, minorRaw, patchRaw] = String(version).split('.');
-  const major = Number.parseInt(majorRaw, 10) || 0;
-  const minor = Number.parseInt(minorRaw, 10) || 0;
-  const patch = Number.parseInt(patchRaw, 10) || 0;
-  if (major >= REQUIRED_NODE_CEILING_MAJOR) return false;
-  if (major > 22) return true;
-  if (major < 22) return false;
-  if (minor > 22) return true;
-  if (minor < 22) return false;
-  return patch >= 1;
-}
-
 /**
  * @param {{ nodeVersion?: string }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -235,19 +219,6 @@ function runGhAuth({ runner = spawn, env = process.env } = {}) {
 // check: commands-in-sync
 // ---------------------------------------------------------------------------
 
-/**
- * Resolve the project root — the directory that contains `.agents/` and
- * `.claude/`. Walks up from this file's own location.
- *
- * @returns {string}
- */
-function resolveProjectRoot() {
-  // lib/cli/registry.js lives at <root>/lib/cli/registry.js, so walk up two
-  // levels from __dirname to reach the project root.
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', '..');
-}
-
 /**
  * Dry-run the sync-claude-commands logic: compare `.agents/workflows/*.md`
  * sources to the generated flat command tree `.claude/commands/*.md`
@@ -324,6 +295,14 @@ function runCommandsInSync({ projectRoot, cwd, readDir } = {}) {
  * Verify that the framework's required runtime dependencies are resolvable
  * from the project's node_modules.
  *
+ * `projectRoot` defaults to `process.cwd()` (the consumer project root) so
+ * the manifest path and the require-resolution context mirror the context in
+ * which the framework scripts actually run (Story #4046 A2). Using
+ * `resolveProjectRoot()` (the package root inside `node_modules/mandrel/`)
+ * breaks the check under pnpm isolated-mode layouts where the consumer's
+ * node_modules are hoisted above `node_modules/mandrel/` and are invisible
+ * from the package root's resolver.
+ *
  * Injectable seams:
  * - `resolve(dep)` — replaces the real `require.resolve`; throws when a dep
  *   is missing.
@@ -338,10 +317,15 @@ function runRuntimeDeps({
   resolve: resolveSeam,
   manifestRequired,
 } = {}) {
+  // Anchor at process.cwd() (the consumer root), not resolveProjectRoot() (the
+  // package root). Under pnpm isolated-mode the consumer's node_modules are not
+  // visible from inside node_modules/mandrel/, so the old anchor produced false
+  // "missing" reports on a clean install (Story #4046 A2).
+  const root = projectRoot ?? process.cwd();
+
   let required = manifestRequired;
   if (!required) {
     try {
-      const root = projectRoot ?? resolveProjectRoot();
       const manifestPath = path.join(root, '.agents', 'runtime-deps.json');
       const raw = fs.readFileSync(manifestPath, 'utf8');
       const parsed = JSON.parse(raw);
@@ -366,9 +350,11 @@ function runRuntimeDeps({
       }
     }
   } else {
-    // Anchor resolution to the project root so it mirrors the context in which
-    // the framework scripts run (they free-ride on the consumer's node_modules).
-    const root = projectRoot ?? resolveProjectRoot();
+    // Anchor resolution to the consumer project root so it mirrors the context
+    // in which the framework scripts run (they free-ride on the consumer's
+    // node_modules). Under pnpm isolated-mode the consumer's node_modules are
+    // not reachable from inside node_modules/mandrel/; anchoring at process.cwd()
+    // finds them correctly.
     const req = createRequire(path.join(root, 'package.json'));
     for (const dep of required) {
       try {
@@ -467,68 +453,9 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
 // check: agents-drift
 // ---------------------------------------------------------------------------
 
-/**
- * Package name whose `.agents/` payload is the drift baseline. Mirrors
- * `lib/cli/sync.js#PACKAGE_NAME`.
- */
-const PACKAGE_NAME = 'mandrel';
-
-/**
- * Top-level directory name (relative to `.agents/`) reserved as the
- * sync-exempt local-additions zone (Story #3498, f-drift-local-zone).
- *
- * `.agents/local/` is consumer-owned space that `mandrel sync` never
- * materializes nor prunes, so it is excluded from the drift comparison —
- * a hand-authored file under `.agents/local/` is sanctioned, not drift.
- * Mirrors `lib/cli/sync.js#LOCAL_ZONE_DIR`.
- */
-const LOCAL_ZONE_DIR = 'local';
-
-/**
- * Default resolver: locate the installed `mandrel` package root by
- * resolving its `package.json` and returning the directory that contains it.
- * Mirrors `lib/cli/sync.js#defaultResolvePackageRoot` so the drift baseline
- * is exactly the payload that `mandrel sync` would copy.
- *
- * @param {string} fromDir - Directory to resolve from (the consumer project).
- * @returns {string} Absolute path to the package root.
- */
-function defaultResolvePackageRoot(fromDir) {
-  const requireFrom = createRequire(path.join(fromDir, 'noop.js'));
-  const pkgJsonPath = requireFrom.resolve(`${PACKAGE_NAME}/package.json`);
-  return path.dirname(pkgJsonPath);
-}
-
-/**
- * Recursively enumerate every regular file under `dir`, returning paths
- * relative to `dir` using OS separators. The top-level `local/` subtree is
- * skipped entirely — it is the consumer-owned local-additions zone and is
- * never part of the package payload (Story #3498). Mirrors
- * `lib/cli/sync.js#listFiles` so source enumeration matches the materializer.
- *
- * @param {string} dir - Absolute directory to walk.
- * @param {typeof fs} fsImpl
- * @param {string} [prefix] - Accumulated relative prefix (internal).
- * @returns {string[]} Relative file paths.
- */
-function listPayloadFiles(dir, fsImpl, prefix = '') {
-  const out = [];
-  for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
-    // Scope the local-zone skip to the top-level `.agents/local/` only; a
-    // deeper directory that happens to be named `local` stays in scope.
-    if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
-      continue;
-    }
-    const rel = prefix ? path.join(prefix, ent.name) : ent.name;
-    const abs = path.join(dir, ent.name);
-    if (ent.isDirectory()) {
-      out.push(...listPayloadFiles(abs, fsImpl, rel));
-    } else {
-      out.push(rel);
-    }
-  }
-  return out;
-}
+// defaultResolvePackageRoot and listPayloadFiles (re-exported as `listFiles`
+// from sync.js) are imported from `lib/cli/sync.js` at the top of this file
+// (Story #4048 B3 — no mirror copies).
 
 /**
  * Compare the consumer's materialized `./.agents/<f>` bytes against the
@@ -556,7 +483,7 @@ function listPayloadFiles(dir, fsImpl, prefix = '') {
  * }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
  */
-function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
+export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   const getCwd = cwd ?? (() => process.cwd());
   const resolveRoot = resolvePackageRoot ?? defaultResolvePackageRoot;
   const projectRoot = getCwd();
@@ -630,39 +557,9 @@ function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
 // check: version-current
 // ---------------------------------------------------------------------------
 
-/**
- * Parse a dotted semver-ish string into a numeric tuple. Non-numeric or
- * missing segments coerce to 0 so a partial version still compares sanely.
- * Mirrors `lib/cli/update.js#parseVersion`.
- *
- * @param {string} version
- * @returns {[number, number, number]}
- */
-function parseVersionTuple(version) {
-  const [major, minor, patch] = String(version).split('.');
-  return [
-    Number.parseInt(major, 10) || 0,
-    Number.parseInt(minor, 10) || 0,
-    Number.parseInt(patch, 10) || 0,
-  ];
-}
-
-/**
- * Compare two version strings. Negative when `a < b`, zero when equal,
- * positive when `a > b`. Mirrors `lib/cli/update.js#compareVersions`.
- *
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function compareSemver(a, b) {
-  const pa = parseVersionTuple(a);
-  const pb = parseVersionTuple(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
-  }
-  return 0;
-}
+// parseVersion and compareVersions are imported from `lib/cli/version-helpers.js`
+// at the top of this file (Story #4048 B3 — no mirror copies). `compareSemver`
+// is the registry-local alias for the imported `compareVersions`.
 
 /**
  * Resolve the installed `mandrel` version from this package's own
@@ -685,17 +582,16 @@ function defaultInstalledVersion(fsImpl) {
 const DEFAULT_VERSION_CACHE_FILENAME = 'version-check.json';
 
 /**
- * Default cache path: `<projectRoot>/temp/version-check.json`, the same daily
- * freshness cache that `lib/cli/version-check.js` reads and refreshes.
+ * Default cache path: `<consumerRoot>/temp/version-check.json`, anchored at
+ * `process.cwd()` (the consumer project root) so the cache file survives
+ * npm/pnpm reinstalls that may replace `node_modules/` entirely (Story #4046
+ * A2). Mirrors `commands-in-sync` / `agents-materialized` / `agents-drift`
+ * which all anchor at `process.cwd()`.
  *
  * @returns {string}
  */
 function defaultVersionCachePath() {
-  return path.join(
-    resolveProjectRoot(),
-    'temp',
-    DEFAULT_VERSION_CACHE_FILENAME,
-  );
+  return path.join(process.cwd(), 'temp', DEFAULT_VERSION_CACHE_FILENAME);
 }
 
 /**

package/lib/cli/sync.js

@@ -7,7 +7,8 @@
  * `./.agents/` directory by **plain file copy** — never a symlink — so
  * Windows and POSIX behave identically (Tech Spec #3459, Feature #3461).
  *
- * Design contract (per Story #3467 AC and Tech Spec #3459 "API Changes"):
+ * Design contract (per Story #3467 AC, Tech Spec #3459 "API Changes", and
+ * Story #4046 sync-prune):
  *   - Copy, not symlink. The materialized tree is plain regular files.
  *   - Idempotent. A second run overwrites in place and leaves ./.agents/
  *     byte-identical to the package payload.
@@ -17,12 +18,14 @@
  *   - Exits non-zero with an actionable message when `mandrel` is
  *     not resolvable in node_modules.
  *   - `--dry-run` reports the planned copies and writes nothing.
- *   - `--force` is accepted; the copy is overwrite-in-place either way, so
- *     it exists for explicitness/forward-compat and changes no behaviour.
  *   - Local-additions zone. The `.agents/local/` subtree is never copied
  *     into nor pruned from the destination (Story #3498). It is the
  *     consumer-owned space for hand-authored additions that must survive
  *     every re-materialization.
+ *   - Sync prune (Story #4046). After the copy pass, any file inside the
+ *     managed `.agents/` zone (everything except `.agents/local/`) that has
+ *     no counterpart in the package payload is deleted. Consumer additions
+ *     under `.agents/local/` are never touched.
  *
  * Security (Tech Spec #3459 "Postinstall safety"):
  *   - Does nothing beyond a local file copy: no network, no shell, no writes
@@ -42,7 +45,7 @@ import nodeFs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
-const PACKAGE_NAME = 'mandrel';
+export const PACKAGE_NAME = 'mandrel';
 
 /**
  * Top-level directory name (relative to `.agents/`) reserved as the
@@ -56,7 +59,16 @@ const PACKAGE_NAME = 'mandrel';
  * which keeps both the dry-run plan and the real copy free of any
  * `.agents/local/**` path even if a future payload were to ship one.
  */
-const LOCAL_ZONE_DIR = 'local';
+export const LOCAL_ZONE_DIR = 'local';
+
+/**
+ * Basename pattern for consumer local-override files (`*.local.<ext>`,
+ * e.g. `instructions.local.md`, `foo.local.json`). Matches the gitignore
+ * convention (`.agents/*.local.md`, `.agentrc.local.json`) and the override
+ * mechanism documented in `.agents/instructions.md` § 1.E. These files never
+ * ship in the payload and are exempt from the sync prune pass.
+ */
+export const LOCAL_OVERRIDE_RE = /\.local\.[^.]+$/;
 
 /**
  * Default resolver: locate the installed `mandrel` package root by
@@ -68,7 +80,7 @@ const LOCAL_ZONE_DIR = 'local';
  * @param {string} fromDir - Directory to resolve from (the consumer project).
  * @returns {string} Absolute path to the package root.
  */
-function defaultResolvePackageRoot(fromDir) {
+export function defaultResolvePackageRoot(fromDir) {
   // Resolve relative to the consumer project so we find *their* install,
   // not a copy hoisted next to this CLI module.
   const requireFrom = createRequire(path.join(fromDir, 'noop.js'));
@@ -88,13 +100,13 @@ function defaultResolvePackageRoot(fromDir) {
  * from the package payload (Story #3498). See {@link LOCAL_ZONE_DIR}.
  *
  * @param {string} dir - Absolute directory to walk.
- * @param {typeof nodeFs} fs
+ * @param {typeof nodeFs} fsImpl
  * @param {string} [prefix] - Accumulated relative prefix (internal).
  * @returns {string[]} Relative file paths.
  */
-function listFiles(dir, fs, prefix = '') {
+export function listFiles(dir, fsImpl, prefix = '') {
   const out = [];
-  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+  for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
     // Never enumerate the sync-exempt local-additions zone. Matching on the
     // empty prefix scopes the skip to the top-level `.agents/local/` only,
     // leaving any deeper directory that happens to be named `local` intact.
@@ -104,7 +116,55 @@ function listFiles(dir, fs, prefix = '') {
     const rel = prefix ? path.join(prefix, ent.name) : ent.name;
     const abs = path.join(dir, ent.name);
     if (ent.isDirectory()) {
-      out.push(...listFiles(abs, fs, rel));
+      out.push(...listFiles(abs, fsImpl, rel));
+    } else {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Recursively enumerate every regular file under `dir`, returning paths
+ * relative to `dir` using OS separators. The top-level `local/` subtree is
+ * skipped so consumer additions inside `.agents/local/` are never pruned
+ * (Story #3498). Files following the `*.local.*` naming convention (e.g.
+ * `.agents/instructions.local.md` — the documented consumer override
+ * mechanism, instructions.md § 1.E) are also skipped: they never ship in
+ * the payload and must survive every sync.
+ *
+ * Mirrors `listFiles` but operates on the destination tree so we can
+ * identify stale files that have no payload counterpart (Story #4046 A3).
+ *
+ * @param {string} dir - Absolute directory to walk.
+ * @param {typeof nodeFs} fsImpl
+ * @param {string} [prefix] - Accumulated relative prefix (internal).
+ * @returns {string[]} Relative file paths.
+ */
+function listDestFiles(dir, fsImpl, prefix = '') {
+  const out = [];
+  let entries;
+  try {
+    entries = fsImpl.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    // Directory absent — nothing to prune.
+    return out;
+  }
+  for (const ent of entries) {
+    // The local-additions zone is never pruned; skip it at the top level.
+    if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
+      continue;
+    }
+    // Consumer local-override files (`*.local.*`, e.g. instructions.local.md,
+    // foo.local.json) are gitignored, never shipped in the payload, and a
+    // documented override mechanism (instructions.md § 1.E) — never prune.
+    if (!ent.isDirectory() && LOCAL_OVERRIDE_RE.test(ent.name)) {
+      continue;
+    }
+    const rel = prefix ? path.join(prefix, ent.name) : ent.name;
+    const abs = path.join(dir, ent.name);
+    if (ent.isDirectory()) {
+      out.push(...listDestFiles(abs, fsImpl, rel));
     } else {
       out.push(rel);
     }
@@ -115,6 +175,11 @@ function listFiles(dir, fs, prefix = '') {
 /**
  * Materialize the package's `.agents/` tree into `./.agents/`.
  *
+ * After the copy pass, any file inside the managed zone of the destination
+ * `.agents/` tree (everything outside `.agents/local/`) that has no
+ * counterpart in the package payload is deleted (sync-prune, Story #4046 A3).
+ * Consumer additions placed under `.agents/local/` are never touched.
+ *
  * @param {{
  *   argv?: string[],
  *   resolvePackageRoot?: (fromDir: string) => string,
@@ -124,8 +189,8 @@ function listFiles(dir, fs, prefix = '') {
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
  * }} [opts]
- * @returns {{ copied: number, planned: number, dryRun: boolean }} Summary
- *   (also returned in dry-run / error paths for testability).
+ * @returns {{ copied: number, planned: number, pruned: number, dryRun: boolean }}
+ *   Summary (also returned in dry-run / error paths for testability).
  */
 export function runSync({
   argv = [],
@@ -137,8 +202,6 @@ export function runSync({
   exit = (code) => process.exit(code),
 } = {}) {
   const dryRun = argv.includes('--dry-run');
-  // `--force` overwrites local edits. The copy is overwrite-in-place
-  // regardless, so the flag is accepted but does not branch behaviour.
   const projectRoot = cwd();
 
   let packageRoot;
@@ -150,7 +213,7 @@ export function runSync({
         `   → Install it first: npm install ${PACKAGE_NAME}\n`,
     );
     exit(1);
-    return { copied: 0, planned: 0, dryRun };
+    return { copied: 0, planned: 0, pruned: 0, dryRun };
   }
 
   const sourceRoot = path.join(packageRoot, '.agents');
@@ -160,23 +223,36 @@ export function runSync({
         `   → Reinstall the package: npm install ${PACKAGE_NAME}\n`,
     );
     exit(1);
-    return { copied: 0, planned: 0, dryRun };
+    return { copied: 0, planned: 0, pruned: 0, dryRun };
   }
 
   const destRoot = path.join(projectRoot, '.agents');
-  const files = listFiles(sourceRoot, fs);
+  const payloadFiles = listFiles(sourceRoot, fs);
 
   if (dryRun) {
-    for (const rel of files) {
+    for (const rel of payloadFiles) {
       write(`would copy  ${path.join('.agents', rel)}\n`);
     }
+    // Compute stale files (managed-zone destination files with no payload
+    // counterpart) for the dry-run plan so operators can preview pruning.
+    const payloadSet = new Set(payloadFiles);
+    const destFiles = listDestFiles(destRoot, fs);
+    const stale = destFiles.filter((f) => !payloadSet.has(f));
+    for (const rel of stale) {
+      write(`would prune ${path.join('.agents', rel)}\n`);
+    }
     write(
-      `✅  Dry run: ${files.length} file(s) would be materialized into ./.agents/\n`,
+      `✅  Dry run: ${payloadFiles.length} file(s) would be materialized, ${stale.length} stale file(s) would be pruned from ./.agents/\n`,
     );
-    return { copied: 0, planned: files.length, dryRun: true };
+    return {
+      copied: 0,
+      planned: payloadFiles.length,
+      pruned: 0,
+      dryRun: true,
+    };
   }
 
-  for (const rel of files) {
+  for (const rel of payloadFiles) {
     const src = path.join(sourceRoot, rel);
     const dest = path.join(destRoot, rel);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -185,8 +261,31 @@ export function runSync({
     fs.copyFileSync(src, dest);
   }
 
-  write(`✅  Materialized ${files.length} file(s) into ./.agents/\n`);
-  return { copied: files.length, planned: files.length, dryRun: false };
+  // Prune pass (Story #4046 A3): remove managed-zone destination files that
+  // have no counterpart in the payload. The local-additions zone
+  // (.agents/local/) is never enumerated by listDestFiles and is therefore
+  // never pruned — consumer additions there are sanctioned, not stale.
+  const payloadSet = new Set(payloadFiles);
+  const destFiles = listDestFiles(destRoot, fs);
+  const staleFiles = destFiles.filter((f) => !payloadSet.has(f));
+  for (const rel of staleFiles) {
+    const dest = path.join(destRoot, rel);
+    fs.unlinkSync(dest);
+  }
+
+  if (staleFiles.length > 0) {
+    write(
+      `✅  Materialized ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,
+    );
+  } else {
+    write(`✅  Materialized ${payloadFiles.length} file(s) into ./.agents/\n`);
+  }
+  return {
+    copied: payloadFiles.length,
+    planned: payloadFiles.length,
+    pruned: staleFiles.length,
+    dryRun: false,
+  };
 }
 
 /**

package/lib/cli/uninstall.js

@@ -54,7 +54,6 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 import {
   LEDGER_SCHEMA_VERSION,
@@ -640,6 +639,7 @@ function formatOutcome(outcome) {
  *   write?: (s: string) => void,
  *   exit?: (code: number) => void,
  *   includeGithub?: boolean,
+ *   dryRun?: boolean,
  * }} [opts]
  * @returns {{ revertedCount: number, manualCount: number, ledgerFound: boolean, parseErrorCount: number }}
  */
@@ -650,6 +650,7 @@ export function runUninstall({
   write = (s) => process.stdout.write(s),
   exit = (code) => process.exit(code),
   includeGithub = false,
+  dryRun = false,
 } = {}) {
   const root = projectRoot ?? resolveProjectRoot(cwd);
 
@@ -695,6 +696,39 @@ export function runUninstall({
 
   const { fileTargets, manual, executedActionByTarget } = planUninstall(ledger);
 
+  // --- Dry run — show what would be reversed without touching anything. ---
+  if (dryRun) {
+    write('mandrel uninstall — planned reversal (dry run)\n');
+    for (const target of fileTargets) {
+      write(
+        formatOutcome({
+          kind: 'reverted',
+          target,
+          detail: '(would be reverted)',
+        }),
+      );
+    }
+    for (const entry of manual) {
+      const note = includeGithub
+        ? `${entry.detail} (acknowledged — reverse manually via the GitHub UI/API)`
+        : `${entry.detail} (left untouched — pass --include-github to acknowledge)`;
+      write(
+        formatOutcome({ kind: 'manual', target: entry.target, detail: note }),
+      );
+    }
+    write(
+      `Dry run: ${fileTargets.length} file target(s) would be reverted, ` +
+        `${manual.length} manual follow-up(s).\n`,
+    );
+    exit(0);
+    return {
+      revertedCount: 0,
+      manualCount: manual.length,
+      ledgerFound: true,
+      parseErrorCount: 0,
+    };
+  }
+
   let revertedCount = 0;
   let parseErrorCount = 0;
   for (const target of fileTargets) {
@@ -782,14 +816,15 @@ export function runUninstall({
 /**
  * Default export consumed by `bin/mandrel.js`.
  *
- * @param {string[]} argv — supports the single `--include-github` flag.
+ * Supported flags:
+ *   --include-github   Acknowledge GitHub-side manual follow-ups.
+ *   --dry-run          Show what would be reversed without touching anything.
+ *
+ * @param {string[]} argv
  * @returns {Promise<void>}
  */
 export default async function run(argv = []) {
   const includeGithub = argv.includes('--include-github');
-  runUninstall({ includeGithub });
+  const dryRun = argv.includes('--dry-run');
+  runUninstall({ includeGithub, dryRun });
 }
-
-// Re-export so tests and callers can reference the resolved module path
-// without re-deriving it.
-export const __filenameForTests = fileURLToPath(import.meta.url);