mandrel 1.59.0 → 1.61.0

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);