@memnexus-ai/mx-agent-cli 0.1.203 → 0.1.205

package/scripts/generate-claude.mjs

@@ -64,8 +64,8 @@
  */
 
 import {
-  chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync,
-  rmSync, unlinkSync, writeFileSync,
+  chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync,
+  renameSync, rmSync, unlinkSync, writeFileSync,
 } from 'fs';
 import { homedir, tmpdir } from 'os';
 import { dirname, join, relative, resolve, sep } from 'path';
@@ -189,6 +189,88 @@ function pruneExtras(destDir, expected) {
   }
 }
 
+// ── GENERATE-TO-STAGING + ATOMIC SWAP (Phase 4 prereq; Red Team finding 1) ────
+//
+// Generation writes the WHOLE tree into a staging dir (a sibling of destRoot so
+// the final rename stays on one filesystem), then atomically swaps it into place.
+// A crash mid-generation can only ever leave a `.claude.staging-*` sibling behind
+// — never a half-written `.claude/`. On ANY staging-phase failure the caller
+// removes the staging dir and leaves the existing `.claude/` byte-untouched.
+
+/**
+ * Copy every existing-dest entry the current generation does NOT manage into the
+ * staging tree, so the swap loses nothing that lives under `.claude/` but is not
+ * generator-owned — chiefly `.claude/settings.local.json` (user-local, never
+ * generated), plus scheduled-task locks and, in the skipPermissionLayer degrade
+ * mode, the existing settings.json + hooks/ backstop (which staging does not
+ * contain in that mode). Anything the generator DID write into staging keeps its
+ * freshly generated version (managed wins) — which also preserves the historical
+ * prune behavior (a managed file removed upstream does not linger).
+ *
+ * FAILS CLOSED if the existing dest apex is a symlink, or if any entry nested in
+ * the existing dest is a symlink — carry-over copies plain files only, and the
+ * swap must never move a smuggled link into place. The real committed `.claude/`
+ * is symlink-free, so this is a no-op in the field.
+ */
+function carryOverUnmanaged(destRoot, staging) {
+  let st;
+  try { st = lstatSync(destRoot); } catch { return; } // no existing dest — nothing to carry
+  if (st.isSymbolicLink()) {
+    throw new Error(
+      `generate-claude: FAIL-CLOSED — existing ${destRoot} is a symlink; ` +
+      `refusing to carry over or swap through it.`,
+    );
+  }
+  assertNoSymlinksInTree(destRoot, '.claude');
+  for (const ent of listDir(destRoot)) {
+    if (existsSync(join(staging, ent.name))) continue; // generator-managed — its version wins
+    cpSync(join(destRoot, ent.name), join(staging, ent.name), { recursive: true });
+  }
+}
+
+/**
+ * Atomically move `staging` into place at `destRoot`:
+ *   1. rename existing `destRoot` → `destRoot.prev-<ts>` (if it exists)
+ *   2. rename `staging` → `destRoot`
+ *   3. remove the prev dir on success
+ * If step 2 fails after step 1, restore the prev dir back to `destRoot`
+ * (best-effort, loud). The caller removes `staging` on any throw.
+ */
+function swapStagingIntoPlace(destRoot, staging) {
+  let destExists = true;
+  try { lstatSync(destRoot); } catch { destExists = false; }
+  const prev = `${destRoot}.prev-${Date.now()}-${process.pid}`;
+  if (destExists) renameSync(destRoot, prev);
+  try {
+    // Test-only crash injection (Change 3): simulate a failure AFTER the existing
+    // dest was moved to prev but BEFORE staging is swapped in, to prove the
+    // prev→destRoot restore path leaves the existing `.claude/` byte-identical
+    // with no staging/prev debris. Never set in production.
+    if (process.env.MX_GENCLAUDE_TEST_FAIL_MID_SWAP === '1') {
+      throw new Error('generate-claude: injected mid-swap failure (MX_GENCLAUDE_TEST_FAIL_MID_SWAP)');
+    }
+    renameSync(staging, destRoot);
+  } catch (err) {
+    if (destExists) {
+      try {
+        renameSync(prev, destRoot);
+        process.stderr.write(
+          `generate-claude: WARN — staging swap failed; restored the previous ` +
+          `.claude/ from ${prev}. No changes were applied.\n`,
+        );
+      } catch (restoreErr) {
+        const d = restoreErr instanceof Error ? restoreErr.message : String(restoreErr);
+        process.stderr.write(
+          `generate-claude: CRITICAL — swap failed AND could not restore the previous ` +
+          `.claude/ from ${prev} (${d}). Recover manually: mv ${prev} ${destRoot}\n`,
+        );
+      }
+    }
+    throw err;
+  }
+  if (destExists) rmSync(prev, { recursive: true, force: true });
+}
+
 // ── last-known-good permission-layer cache (Red Team CRITICAL B) ─────────────
 //
 // The boot degrade path must NOT trust the working tree. If the origin fetch of
@@ -398,109 +480,136 @@ export function generateClaudeConfig(opts) {
   };
   scanSources();
 
-  // CRITICAL (Red Team round 3): guard the dest APEX before creating it. The five
-  // managed subdirs each get guardManagedDir, but destRoot itself was unguarded —
-  // if `.claude` is pre-planted as a symlink, mkdirSync follows it and every
-  // subsequent write escapes the repo. lstat + FAIL-CLOSED on a symlinked apex.
-  guardManagedDir(destRoot);
-  mkdirSync(destRoot, { recursive: true });
-
-  // MINOR (scan-to-copy race hardening): re-scan the source immediately before
-  // the write phase. If a link was planted between the pre-scan and now (TOCTOU),
-  // abort FAIL-CLOSED instead of silently skipping the mutated entry.
-  scanSources();
+  // Build the FULL tree into a STAGING dir that is a sibling of destRoot (so the
+  // final rename stays on one filesystem), then atomically swap it into place. A
+  // crash mid-generation can only ever leave a `.claude.staging-*` sibling behind,
+  // never a half-written `.claude/`. All the fail-closed guards below still apply,
+  // now against staging (fresh mkdtemp — so a smuggled dest-side symlink cannot
+  // reach the write phase); the existing dest is guarded separately at swap time.
+  const parent = dirname(destRoot);
+  mkdirSync(parent, { recursive: true });
+  const staging = mkdtempSync(join(parent, '.claude.staging-'));
 
-  // 1. settings.json — verbatim, 0644. From the permission source (origin/<base>
-  //    at boot; baseDir otherwise). Skipped in degraded fallback.
-  if (!skipPermissionLayer) {
-    writeManagedFile(join(destRoot, 'settings.json'), readFileSync(join(permissionSrcDir, 'settings.json')), 0o644);
-  }
+  try {
+    // MINOR (scan-to-copy race hardening): re-scan the source immediately before
+    // the write phase. If a link was planted between the pre-scan and now (TOCTOU),
+    // abort FAIL-CLOSED instead of silently skipping the mutated entry.
+    scanSources();
+
+    // 1. settings.json — verbatim, 0644. From the permission source (origin/<base>
+    //    at boot; baseDir otherwise). Skipped in degraded fallback.
+    if (!skipPermissionLayer) {
+      writeManagedFile(join(staging, 'settings.json'), readFileSync(join(permissionSrcDir, 'settings.json')), 0o644);
+    }
 
-  // 2. hooks/ — every file verbatim; *.sh → 0755 (incl. *.test.sh), else 0644.
-  //    Permission layer: from permissionSrcDir. Skipped in degraded fallback.
-  let hookCount = 0;
-  if (!skipPermissionLayer) {
-    const hooksDest = guardManagedDir(join(destRoot, 'hooks'));
-    mkdirSync(hooksDest, { recursive: true });
-    const hookNames = new Set();
-    for (const ent of listDir(join(permissionSrcDir, 'hooks'))) {
-      if (!ent.isFile()) continue;
-      const mode = ent.name.endsWith('.sh') ? 0o755 : 0o644;
-      writeManagedFile(join(hooksDest, ent.name), readFileSync(join(permissionSrcDir, 'hooks', ent.name)), mode);
-      hookNames.add(ent.name);
+    // 2. hooks/ — every file verbatim; *.sh → 0755 (incl. *.test.sh), else 0644.
+    //    Permission layer: from permissionSrcDir. Skipped in degraded fallback.
+    let hookCount = 0;
+    if (!skipPermissionLayer) {
+      const hooksDest = guardManagedDir(join(staging, 'hooks'));
+      mkdirSync(hooksDest, { recursive: true });
+      const hookNames = new Set();
+      for (const ent of listDir(join(permissionSrcDir, 'hooks'))) {
+        if (!ent.isFile()) continue;
+        const mode = ent.name.endsWith('.sh') ? 0o755 : 0o644;
+        writeManagedFile(join(hooksDest, ent.name), readFileSync(join(permissionSrcDir, 'hooks', ent.name)), mode);
+        hookNames.add(ent.name);
+      }
+      pruneExtras(hooksDest, hookNames);
+      hookCount = hookNames.size;
     }
-    pruneExtras(hooksDest, hookNames);
-    hookCount = hookNames.size;
-  }
 
-  // 3. rules/ — verbatim, 0644.
-  const rulesDest = guardManagedDir(join(destRoot, 'rules'));
-  mkdirSync(rulesDest, { recursive: true });
-  const ruleNames = new Set();
-  for (const ent of listDir(join(baseDir, 'rules'))) {
-    if (!ent.isFile()) continue;
-    writeManagedFile(join(rulesDest, ent.name), readFileSync(join(baseDir, 'rules', ent.name)), 0o644);
-    ruleNames.add(ent.name);
-  }
-  pruneExtras(rulesDest, ruleNames);
-
-  // 4. agents/ — union of base + overlay, 0644. Overlay overlays base on a
-  //    name collision (last write wins) — by design disjoint today.
-  const agentsDest = guardManagedDir(join(destRoot, 'agents'));
-  mkdirSync(agentsDest, { recursive: true });
-  const agentNames = new Set();
-  for (const src of [join(baseDir, 'agents'), join(overlayDir, 'agents')]) {
-    for (const ent of listDir(src)) {
+    // 3. rules/ — verbatim, 0644.
+    const rulesDest = guardManagedDir(join(staging, 'rules'));
+    mkdirSync(rulesDest, { recursive: true });
+    const ruleNames = new Set();
+    for (const ent of listDir(join(baseDir, 'rules'))) {
       if (!ent.isFile()) continue;
-      writeManagedFile(join(agentsDest, ent.name), readFileSync(join(src, ent.name)), 0o644);
-      agentNames.add(ent.name);
+      writeManagedFile(join(rulesDest, ent.name), readFileSync(join(baseDir, 'rules', ent.name)), 0o644);
+      ruleNames.add(ent.name);
     }
-  }
-  pruneExtras(agentsDest, agentNames);
-
-  // 5. skills/ — union of base + overlay skill DIRECTORIES, recursive, 0644.
-  const skillsDest = guardManagedDir(join(destRoot, 'skills'));
-  mkdirSync(skillsDest, { recursive: true });
-  const skillNames = new Set();
-  for (const src of [join(baseDir, 'skills'), join(overlayDir, 'skills')]) {
-    for (const ent of listDir(src)) {
-      if (!ent.isDirectory()) continue;
-      const d = join(skillsDest, ent.name);
-      guardManagedDir(d); // CRITICAL A: guard per-skill dir before mkdir
-      mkdirSync(d, { recursive: true });
-      copyFileTree(join(src, ent.name), d);
-      skillNames.add(ent.name);
+    pruneExtras(rulesDest, ruleNames);
+
+    // 4. agents/ — union of base + overlay, 0644. Overlay overlays base on a
+    //    name collision (last write wins) — by design disjoint today.
+    const agentsDest = guardManagedDir(join(staging, 'agents'));
+    mkdirSync(agentsDest, { recursive: true });
+    const agentNames = new Set();
+    for (const src of [join(baseDir, 'agents'), join(overlayDir, 'agents')]) {
+      for (const ent of listDir(src)) {
+        if (!ent.isFile()) continue;
+        writeManagedFile(join(agentsDest, ent.name), readFileSync(join(src, ent.name)), 0o644);
+        agentNames.add(ent.name);
+      }
     }
-  }
-  pruneExtras(skillsDest, skillNames);
-
-  // 6. commands/ — from overlay/commands only. All regular files now (the former
-  //    mx-find/mx-rules/mx-save SYMLINKS were replaced by plain files), 0644.
-  const commandsSrc = join(overlayDir, 'commands');
-  const commandsDest = guardManagedDir(join(destRoot, 'commands'));
-  mkdirSync(commandsDest, { recursive: true });
-  const commandNames = new Set();
-  for (const ent of listDir(commandsSrc)) {
-    const s = join(commandsSrc, ent.name);
-    const d = join(commandsDest, ent.name);
-    if (ent.isSymbolicLink()) {
-      // Should be unreachable after the pre-scan; kept as defense-in-depth.
-      throw new Error(`generate-claude: FAIL-CLOSED — unexpected symlink in ${commandsSrc}: ${ent.name}`);
-    } else if (ent.isFile()) {
-      writeManagedFile(d, readFileSync(s), 0o644);
-    } else if (ent.isDirectory()) {
-      guardManagedDir(d); // CRITICAL A: guard per-command dir before mkdir
-      mkdirSync(d, { recursive: true });
-      copyFileTree(s, d);
+    pruneExtras(agentsDest, agentNames);
+
+    // 5. skills/ — union of base + overlay skill DIRECTORIES, recursive, 0644.
+    const skillsDest = guardManagedDir(join(staging, 'skills'));
+    mkdirSync(skillsDest, { recursive: true });
+    const skillNames = new Set();
+    for (const src of [join(baseDir, 'skills'), join(overlayDir, 'skills')]) {
+      for (const ent of listDir(src)) {
+        if (!ent.isDirectory()) continue;
+        const d = join(skillsDest, ent.name);
+        guardManagedDir(d); // CRITICAL A: guard per-skill dir before mkdir
+        mkdirSync(d, { recursive: true });
+        copyFileTree(join(src, ent.name), d);
+        skillNames.add(ent.name);
+      }
     }
-    commandNames.add(ent.name);
-  }
-  pruneExtras(commandsDest, commandNames);
+    pruneExtras(skillsDest, skillNames);
+
+    // 6. commands/ — from overlay/commands only. All regular files now (the former
+    //    mx-find/mx-rules/mx-save SYMLINKS were replaced by plain files), 0644.
+    const commandsSrc = join(overlayDir, 'commands');
+    const commandsDest = guardManagedDir(join(staging, 'commands'));
+    mkdirSync(commandsDest, { recursive: true });
+    const commandNames = new Set();
+    for (const ent of listDir(commandsSrc)) {
+      const s = join(commandsSrc, ent.name);
+      const d = join(commandsDest, ent.name);
+      if (ent.isSymbolicLink()) {
+        // Should be unreachable after the pre-scan; kept as defense-in-depth.
+        throw new Error(`generate-claude: FAIL-CLOSED — unexpected symlink in ${commandsSrc}: ${ent.name}`);
+      } else if (ent.isFile()) {
+        writeManagedFile(d, readFileSync(s), 0o644);
+      } else if (ent.isDirectory()) {
+        guardManagedDir(d); // CRITICAL A: guard per-command dir before mkdir
+        mkdirSync(d, { recursive: true });
+        copyFileTree(s, d);
+      }
+      commandNames.add(ent.name);
+    }
+    pruneExtras(commandsDest, commandNames);
 
-  return { destRoot, counts: {
-    hooks: hookCount, rules: ruleNames.size, agents: agentNames.size,
-    skills: skillNames.size, commands: commandNames.size,
-  } };
+    // Defense-in-depth: the generated staging tree must contain zero symlinks
+    // (generation only emits plain files). Fail closed BEFORE the swap if not.
+    assertNoSymlinksInTree(staging, '.claude.staging');
+
+    // Test-only crash injection (Change 3): simulate a failure between a fully
+    // generated staging tree and the swap, to prove the existing `.claude/` is
+    // left byte-untouched and no staging debris survives. Never set in production.
+    if (process.env.MX_GENCLAUDE_TEST_FAIL_BEFORE_SWAP === '1') {
+      throw new Error('generate-claude: injected pre-swap failure (MX_GENCLAUDE_TEST_FAIL_BEFORE_SWAP)');
+    }
+
+    // Carry over settings.local.json + every other unmanaged existing entry
+    // (guards the existing dest against symlinks — FAILS CLOSED on a pre-planted
+    // apex/subdir symlink), then atomically swap staging into place.
+    carryOverUnmanaged(destRoot, staging);
+    swapStagingIntoPlace(destRoot, staging);
+
+    return { destRoot, counts: {
+      hooks: hookCount, rules: ruleNames.size, agents: agentNames.size,
+      skills: skillNames.size, commands: commandNames.size,
+    } };
+  } catch (err) {
+    // Staging-phase failure: remove the staging dir and leave the existing
+    // `.claude/` completely untouched.
+    rmSync(staging, { recursive: true, force: true });
+    throw err;
+  }
 }
 
 // ── --from-git: source agent-config from a git ref (tamper-resistant) ────────