mandrel 1.94.0 → 2.1.0

package/lib/cli/sync-agents.js

@@ -0,0 +1,157 @@
+// lib/cli/sync-agents.js
+/**
+ * `mandrel sync-agents` subcommand (Story #4528 / #4530).
+ *
+ * Thin wrapper that delegates to the canonical sync script
+ * (.agents/scripts/sync-claude-agents.js), projecting `.agents/agents/` into
+ * a flat `.claude/agents/` tree. Exact sibling of `sync-commands.js` —
+ * same delegation shape, same marker-gated refusal check, same seams —
+ * targeting the role-agent tree instead of the command tree. The sync
+ * script owns all sync logic; this module exists only to expose it through
+ * the mandrel CLI surface without reimplementing it.
+ *
+ * `sync-claude-agents.js` uses top-level await and has no exported `main()`
+ * function (marked `cli-opt-out`), so delegation runs via a child process
+ * rather than a direct import. Exit code and all output are forwarded
+ * verbatim to the caller so `mandrel sync-agents` is transparent to scripts
+ * that check $?.
+ *
+ * ## Prior to this Story
+ *
+ * `sync-claude-agents.js` was invoked on the **bootstrap** path
+ * (`project-bootstrap.js`'s `sync:agents` script, `prepare`, and
+ * `runSyncCommands`) but had no `lib/cli/` subcommand counterpart and was
+ * never run by `mandrel sync` / `mandrel update` on the CLI path — the gap
+ * #4528 reported. See `update.js`'s `driftHealSteps()` /
+ * `fullUpgradeSteps()`, which now spawn a `sync-agents` phase alongside
+ * `sync-commands` so `.claude/agents/` materializes on that path too.
+ *
+ * ## Marker-gated refusal (Story #4526 / #4530) — same shape as sync-commands
+ *
+ * Before delegating, this wrapper checks whether the `.agents/` tree it is
+ * about to project agents FROM actually matches the running CLI's own
+ * payload version, exactly as `sync-commands.js` does for the command tree.
+ * See that module's doc comment for the full rationale and the anchor-trap
+ * warning — it applies identically here (`PROJECT_ROOT` is deliberately the
+ * package root, used only to read the running CLI's OWN version; the marker
+ * read is anchored at `cwd()`, never at `PROJECT_ROOT`).
+ *
+ * Gate order:
+ *   1. Marker present (`.agents/.mandrel-version`) → compare it to the
+ *      running CLI's own package version. Mismatch → refuse.
+ *   2. Marker absent (a pre-marker install) → fall back to the existing
+ *      `agents-drift` content-hash check. Drift detected → refuse.
+ *   3. Clean either way → project as before.
+ */
+
+import { spawnSync } from 'node:child_process';
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runAgentsDrift } from './registry.js';
+import { readVersionMarker } from './sync.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// lib/cli/ → lib/ → project root
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+const SYNC_SCRIPT = path.join(
+  PROJECT_ROOT,
+  '.agents',
+  'scripts',
+  'sync-claude-agents.js',
+);
+
+/**
+ * Resolve the running CLI's own package version from `PROJECT_ROOT`'s
+ * `package.json`. See `sync-commands.js`'s "anchor trap" module doc: this is
+ * the ONE place `PROJECT_ROOT` (the package's own two-dirs-up root) is the
+ * correct anchor.
+ *
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string}
+ */
+function resolveOwnPackageVersion(fsImpl) {
+  const parsed = JSON.parse(
+    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
+  );
+  return String(parsed.version);
+}
+
+/**
+ * Run the sync-claude-agents script and forward its output + exit code —
+ * unless the marker-gated refusal check (see module doc) finds the
+ * `.agents/` tree mismatched against the running CLI, in which case it
+ * refuses and exits non-zero before spawning anything.
+ *
+ * Injectable seams — identical shape to `sync-commands.js`:
+ * - `runner` — replaces `spawnSync` for the real delegation.
+ * - `cwd()` — replaces `process.cwd`; anchors the marker read at the
+ *   consumer project root.
+ * - `fs` — replaces the `node:fs` surface for both the marker read and the
+ *   own-version read.
+ * - `ownVersion` — overrides the running CLI's own resolved version
+ *   directly, bypassing `resolveOwnPackageVersion`.
+ * - `checkAgentsDrift` — overrides the fallback drift probe used when the
+ *   marker is absent; defaults to `runAgentsDrift({ cwd })`.
+ * - `writeErr` / `exit` — replace the corresponding process surfaces.
+ *
+ * @param {string[]} _argv - Unused; reserved for future flags.
+ * @param {{
+ *   runner?: typeof spawnSync,
+ *   cwd?: () => string,
+ *   fs?: typeof nodeFs,
+ *   ownVersion?: string,
+ *   checkAgentsDrift?: () => { ok: boolean, detail: string },
+ *   writeErr?: (s: string) => void,
+ *   exit?: (code: number) => void,
+ * }} [opts]
+ * @returns {void}
+ */
+export default function run(
+  _argv = [],
+  {
+    runner = spawnSync,
+    cwd = () => process.cwd(),
+    fs = nodeFs,
+    ownVersion,
+    checkAgentsDrift,
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
+  } = {},
+) {
+  const projectRoot = cwd();
+  const resolvedOwnVersion = ownVersion ?? resolveOwnPackageVersion(fs);
+  const marker = readVersionMarker(projectRoot, fs);
+
+  if (marker) {
+    if (marker !== resolvedOwnVersion) {
+      writeErr(
+        `mandrel sync-agents: the materialized .agents/ tree is v${marker} but the running CLI is v${resolvedOwnVersion} — refusing to project .claude/agents/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to re-materialize .agents/ to the current version, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  } else {
+    const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
+    if (!drift.ok) {
+      writeErr(
+        `mandrel sync-agents: .agents/ appears to have drifted from the installed package payload (${drift.detail}) — refusing to project .claude/agents/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to restore the materialized .agents/ payload, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  }
+
+  const result = runner(process.execPath, [SYNC_SCRIPT], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  const exitCode = result.status ?? 1;
+  if (exitCode !== 0) {
+    exit(exitCode);
+  }
+}

package/lib/cli/sync-commands.js

@@ -11,12 +11,49 @@
  * (marked `cli-opt-out`), so delegation runs via a child process rather than
  * a direct import. Exit code and all output are forwarded verbatim to the
  * caller so `mandrel sync-commands` is transparent to scripts that check $?.
+ *
+ * ## Marker-gated refusal (Story #4526 / #4530)
+ *
+ * Before delegating, this wrapper checks whether the `.agents/` tree it is
+ * about to project commands FROM actually matches the running CLI's own
+ * payload version. Without this gate, a consumer whose `.agents/` tree lags
+ * the installed package (see #4525's pin-skew scenario) gets commands
+ * faithfully projected from a **stale** tree — describing a workflow whose
+ * backing scripts are not installed. Because `.claude/*` is conventionally
+ * gitignored, that wrong projection leaves no diff and no signal until an
+ * agent hits a missing-module error mid-task, far from the actual cause.
+ *
+ * Gate order:
+ *   1. Marker present (`.agents/.mandrel-version`, Story #4530) → compare it
+ *      to the running CLI's own package version. Mismatch → refuse.
+ *   2. Marker absent (a pre-marker install with no baseline to compare) →
+ *      fall back to the existing `agents-drift` content-hash check
+ *      (`registry.js`). Drift detected → refuse.
+ *   3. Clean either way → project as before.
+ *
+ * ## Anchor trap (do not repeat)
+ *
+ * `PROJECT_ROOT` below is deliberately the **package** root — resolved from
+ * this module's own two-dirs-up location — because it is used ONLY to read
+ * the running CLI's OWN version, which is exactly what that self-referential
+ * pattern correctly answers (contrast with the #4525 bug in `update.js`,
+ * where the same pattern was wrongly used to answer a *consumer*-pin
+ * question). The marker read is a SEPARATE resolution, anchored at `cwd()`
+ * (the consumer project root) via `readVersionMarker` — never at
+ * `PROJECT_ROOT`. Comparing the marker to `PROJECT_ROOT`'s own version would
+ * make the check compare the package against itself and could never fire —
+ * the exact trap `registry.js`'s `agents-in-sync` check documents for the
+ * same reason.
  */
 
 import { spawnSync } from 'node:child_process';
+import nodeFs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { runAgentsDrift } from './registry.js';
+import { readVersionMarker } from './sync.js';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // lib/cli/ → lib/ → project root
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
@@ -28,16 +65,88 @@ const SYNC_SCRIPT = path.join(
 );
 
 /**
- * Run the sync-claude-commands script and forward its output + exit code.
+ * Resolve the running CLI's own package version from `PROJECT_ROOT`'s
+ * `package.json`. See the "anchor trap" module doc: this is the ONE place
+ * `PROJECT_ROOT` (the package's own two-dirs-up root) is the correct anchor.
+ *
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string}
+ */
+function resolveOwnPackageVersion(fsImpl) {
+  const parsed = JSON.parse(
+    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
+  );
+  return String(parsed.version);
+}
+
+/**
+ * Run the sync-claude-commands script and forward its output + exit code —
+ * unless the marker-gated refusal check (see module doc) finds the
+ * `.agents/` tree mismatched against the running CLI, in which case it
+ * refuses and exits non-zero before spawning anything.
  *
- * Injectable seam: `runner` replaces `spawnSync` so tests can drive every
- * branch without spawning a real child process.
+ * Injectable seams (used by tests so no real filesystem, child process, or
+ * package resolution occurs on the gate path):
+ * - `runner` — replaces `spawnSync` for the real delegation.
+ * - `cwd()` — replaces `process.cwd`; anchors the marker read at the
+ *   consumer project root.
+ * - `fs` — replaces the `node:fs` surface for both the marker read and the
+ *   own-version read.
+ * - `ownVersion` — overrides the running CLI's own resolved version
+ *   directly, bypassing `resolveOwnPackageVersion`.
+ * - `checkAgentsDrift` — overrides the fallback drift probe used when the
+ *   marker is absent; defaults to `runAgentsDrift({ cwd })`.
+ * - `writeErr` / `exit` — replace the corresponding process surfaces.
  *
  * @param {string[]} _argv - Unused; reserved for future flags.
- * @param {{ runner?: typeof spawnSync }} [opts]
+ * @param {{
+ *   runner?: typeof spawnSync,
+ *   cwd?: () => string,
+ *   fs?: typeof nodeFs,
+ *   ownVersion?: string,
+ *   checkAgentsDrift?: () => { ok: boolean, detail: string },
+ *   writeErr?: (s: string) => void,
+ *   exit?: (code: number) => void,
+ * }} [opts]
  * @returns {void}
  */
-export default function run(_argv = [], { runner = spawnSync } = {}) {
+export default function run(
+  _argv = [],
+  {
+    runner = spawnSync,
+    cwd = () => process.cwd(),
+    fs = nodeFs,
+    ownVersion,
+    checkAgentsDrift,
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
+  } = {},
+) {
+  const projectRoot = cwd();
+  const resolvedOwnVersion = ownVersion ?? resolveOwnPackageVersion(fs);
+  const marker = readVersionMarker(projectRoot, fs);
+
+  if (marker) {
+    if (marker !== resolvedOwnVersion) {
+      writeErr(
+        `mandrel sync-commands: the materialized .agents/ tree is v${marker} but the running CLI is v${resolvedOwnVersion} — refusing to project .claude/commands/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to re-materialize .agents/ to the current version, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  } else {
+    const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
+    if (!drift.ok) {
+      writeErr(
+        `mandrel sync-commands: .agents/ appears to have drifted from the installed package payload (${drift.detail}) — refusing to project .claude/commands/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to restore the materialized .agents/ payload, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  }
+
   const result = runner(process.execPath, [SYNC_SCRIPT], {
     stdio: 'inherit',
     env: process.env,
@@ -45,6 +154,6 @@ export default function run(_argv = [], { runner = spawnSync } = {}) {
 
   const exitCode = result.status ?? 1;
   if (exitCode !== 0) {
-    process.exit(exitCode);
+    exit(exitCode);
   }
 }

package/lib/cli/sync.js

@@ -26,6 +26,16 @@
  *     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.
+ *   - Generated, never-pruned registry (Story #4534). Framework-generated
+ *     `.agents/` files have no payload counterpart by design, so the prune
+ *     pass would delete each one unless it is declared in
+ *     {@link GENERATED_FILES}. That registry — not a per-file special case in
+ *     {@link listDestFiles} — is the single place a generated artifact is
+ *     exempted. Registered today: the version marker (Story #4530) and the
+ *     install ledger the bootstrap writes and `mandrel uninstall` reads.
+ *   - Version marker (Story #4530). After the prune pass, `.agents/.mandrel-
+ *     version` is (re)written with the executing package's own version. See
+ *     {@link readVersionMarker} for how callers consume it.
  *
  * Security (Tech Spec #3459 "Postinstall safety"):
  *   - Does nothing beyond a local file copy: no network, no shell, no writes
@@ -45,8 +55,19 @@ import nodeFs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
+import { LEDGER_RELATIVE_PATH } from '../../.agents/scripts/lib/bootstrap/install-ledger.js';
+
 export const PACKAGE_NAME = 'mandrel';
 
+/**
+ * Name of the managed destination directory, relative to the project root.
+ * Generating modules export their artifact paths relative to the *project
+ * root* (e.g. `install-ledger.js`'s `LEDGER_RELATIVE_PATH`), whereas the
+ * prune pass compares paths relative to this directory — {@link
+ * toManagedZoneRelative} is the one conversion between the two.
+ */
+const AGENTS_DIR = '.agents';
+
 /**
  * Top-level directory name (relative to `.agents/`) reserved as the
  * sync-exempt local-additions zone (Story #3498, f-drift-local-zone).
@@ -70,6 +91,119 @@ export const LOCAL_ZONE_DIR = 'local';
  */
 export const LOCAL_OVERRIDE_RE = /\.local\.[^.]+$/;
 
+/**
+ * Relative path (from `.agents/`) of the version marker `runSync` writes
+ * after every sync, carrying the executing package's own version.
+ */
+export const VERSION_MARKER_RELATIVE_PATH = '.mandrel-version';
+
+/**
+ * Convert a project-root-relative POSIX path — the shape a generating module
+ * exports as its own source of truth (e.g. `install-ledger.js`'s
+ * `LEDGER_RELATIVE_PATH`, `'.agents/.install-manifest.json'`) — into the
+ * `.agents/`-relative, OS-separator form {@link listDestFiles} enumerates and
+ * {@link GENERATED_FILES} is compared against.
+ *
+ * Throws on a path outside `.agents/`: a generated file the sync prune pass
+ * never walks has no business in the registry, and registering one would be a
+ * silent no-op that reads as protection. Failing at module load surfaces the
+ * mistake at the first import rather than as a mystery deletion in a
+ * consumer's tree.
+ *
+ * @param {string} projectRelativePosixPath - e.g. `.agents/.install-manifest.json`.
+ * @returns {string} e.g. `.install-manifest.json` (OS separators).
+ */
+function toManagedZoneRelative(projectRelativePosixPath) {
+  const segments = projectRelativePosixPath.split('/');
+  if (segments[0] !== AGENTS_DIR || segments.length < 2) {
+    throw new Error(
+      `generated-files registry: '${projectRelativePosixPath}' is not inside ${AGENTS_DIR}/ — ` +
+        'only files the sync prune pass walks can be registered as never-pruned.',
+    );
+  }
+  return path.join(...segments.slice(1));
+}
+
+/**
+ * The **generated, never-pruned registry**: every framework-generated
+ * `.agents/` file that has no payload counterpart and must therefore be
+ * exempted from the prune pass. Paths are `.agents/`-relative with OS
+ * separators, matching what {@link listDestFiles} enumerates.
+ *
+ * The prune pass (Story #4046 A3) deletes any managed-zone file absent from
+ * the payload. That is the correct rule for consumer drift, but it is also
+ * exactly the shape of every file the framework itself generates into
+ * `.agents/` outside the payload — so each such artifact is deleted by the very
+ * sync that wrote it unless registered here. Two have hit this already: the
+ * install ledger (`.agents/.install-manifest.json`), whose loss made
+ * `mandrel uninstall` silently reverse nothing and exit 0 (Story #4534), and
+ * the version marker (Story #4530).
+ *
+ * This is deliberately a **registry, not a list of special cases**. Register a
+ * new generated file by adding one entry here — keyed off the generating
+ * module's own exported constant wherever one exists, never a duplicated
+ * string literal — rather than by adding another branch to
+ * {@link listDestFiles}. That keeps the never-prune contract declared in one
+ * place and keeps the registry honest: if the generator renames its artifact,
+ * the exemption moves with it.
+ *
+ * This registry does **not** subsume the `.agents/local/` zone or the
+ * `*.local.*` overrides ({@link LOCAL_ZONE_DIR}, {@link LOCAL_OVERRIDE_RE}).
+ * Those are a different concept — consumer-authored overrides, not
+ * framework-generated artifacts — and stay separate on purpose.
+ */
+export const GENERATED_FILES = Object.freeze([
+  // Version marker (Story #4530) — written by runSync itself, below.
+  VERSION_MARKER_RELATIVE_PATH,
+  // Install ledger (Story #4534) — written by the bootstrap
+  // (`install-ledger.js`), read by `mandrel uninstall` as its single source of
+  // truth. Keyed off the generator's exported constant.
+  toManagedZoneRelative(LEDGER_RELATIVE_PATH),
+]);
+
+/**
+ * Resolve the version of the package whose `.agents/` payload was just
+ * copied — i.e. the version the marker must carry. Reads `package.json` at
+ * the already-resolved `packageRoot`, never the two-directories-up
+ * self-referential pattern `lib/cli/update.js`'s pre-Story-#4530
+ * `defaultCurrentVersion` used (that pattern conflates "the CLI that is
+ * running" with "the payload that was materialized" — the exact confusion
+ * #4525 fixes on the consumer-pin side of this Story).
+ *
+ * @param {string} packageRoot - Absolute path to the resolved package root.
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string}
+ */
+function resolvePackageVersion(packageRoot, fsImpl) {
+  const pkgJsonPath = path.join(packageRoot, 'package.json');
+  const parsed = JSON.parse(fsImpl.readFileSync(pkgJsonPath, 'utf8'));
+  return String(parsed.version);
+}
+
+/**
+ * Read the consumer's `.agents/.mandrel-version` marker. Returns `null` when
+ * absent — a pre-marker install, or a tree that has never been synced —
+ * so callers (the sync-commands mismatch refusal, the doctor pin check) can
+ * degrade to their existing content-hash drift check rather than failing.
+ *
+ * @param {string} consumerRoot - Consumer project root (not `.agents/`).
+ * @param {typeof nodeFs} [fsImpl]
+ * @returns {string | null}
+ */
+export function readVersionMarker(consumerRoot, fsImpl = nodeFs) {
+  const markerPath = path.join(
+    consumerRoot,
+    '.agents',
+    VERSION_MARKER_RELATIVE_PATH,
+  );
+  try {
+    const raw = fsImpl.readFileSync(markerPath, 'utf8').trim();
+    return raw || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Default resolver: locate the installed `mandrel` package root by
  * resolving its `package.json` and returning the directory that contains it.
@@ -126,12 +260,22 @@ export function listFiles(dir, fsImpl, prefix = '') {
 
 /**
  * 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.
+ * relative to `dir` using OS separators. Three disjoint classes are skipped,
+ * so a caller diffing this against the payload never treats them as stale:
+ *
+ *   1. The top-level `local/` subtree — consumer additions inside
+ *      `.agents/local/` are never pruned (Story #3498).
+ *   2. Files matching the `*.local.*` convention (e.g.
+ *      `.agents/instructions.local.md`) — the documented consumer override
+ *      mechanism (instructions.md § 1.E); they never ship in the payload and
+ *      must survive every sync.
+ *   3. Everything declared in the {@link GENERATED_FILES} registry —
+ *      framework-generated artifacts with no payload counterpart by design
+ *      (Story #4534). New generated files are registered there, not added as
+ *      a fourth branch here.
+ *
+ * (1) and (2) are consumer-authored; (3) is framework-generated. They are
+ * kept separate deliberately — conflating them would muddy both contracts.
  *
  * Mirrors `listFiles` but operates on the destination tree so we can
  * identify stale files that have no payload counterpart (Story #4046 A3).
@@ -162,6 +306,11 @@ function listDestFiles(dir, fsImpl, prefix = '') {
       continue;
     }
     const rel = prefix ? path.join(prefix, ent.name) : ent.name;
+    // Framework-generated artifacts — declared once in the never-pruned
+    // registry (Story #4534); see GENERATED_FILES.
+    if (!ent.isDirectory() && GENERATED_FILES.includes(rel)) {
+      continue;
+    }
     const abs = path.join(dir, ent.name);
     if (ent.isDirectory()) {
       out.push(...listDestFiles(abs, fsImpl, rel));
@@ -273,6 +422,19 @@ export function runSync({
     fs.unlinkSync(dest);
   }
 
+  // Version marker (Story #4530): written AFTER the prune pass, never
+  // before — the GENERATED_FILES registry already keeps listDestFiles from
+  // ever enumerating it as stale, but ordering the write after prune is a
+  // second, independent safeguard against the same class of bug (see the
+  // GENERATED_FILES doc comment) surviving a future prune-pass reorder. The
+  // install ledger gets no such belt-and-braces: it is written by the
+  // bootstrap, not here, so the registry is its only protection.
+  const packageVersion = resolvePackageVersion(packageRoot, fs);
+  fs.writeFileSync(
+    path.join(destRoot, VERSION_MARKER_RELATIVE_PATH),
+    `${packageVersion}\n`,
+  );
+
   if (staleFiles.length > 0) {
     write(
       `✅  Installed ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,