mandrel 1.57.0

package/.agents/scripts/sync-branch-from-base.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+/**
+ * sync-branch-from-base.js — operator-facing CLI wrapper around
+ * `lib/git/sync-from-base.js` (Story #2580).
+ *
+ * Use this from workflow markdown when the operator needs to sync a
+ * working branch with `origin/<baseBranch>` before opening a PR — for
+ * example as a pre-Phase-6 step in `/epic-deliver` so the Epic→main PR
+ * opens with the latest `main` commits already integrated.
+ *
+ * For `/single-story-deliver`, the sync runs in-process inside
+ * `single-story-close.js`; this CLI is the operator surface for
+ * workflows that don't have a built-in close pipeline.
+ *
+ * Usage:
+ *   node .agents/scripts/sync-branch-from-base.js \
+ *     --branch <branchName> --base <baseBranch> [--cwd <path>]
+ *
+ * Exit codes:
+ *   0 — synced (`fast-forward`, `merge-commit`, or `noop-already-current`).
+ *   1 — fetch/merge failed or conflict; error message on stderr names the
+ *       outcome kind and (for conflicts) the conflicting file list.
+ *
+ * The script does NOT post structured comments or flip ticket labels —
+ * it is a pure git operation. Recovery surfaces are the caller's
+ * responsibility (the workflow doc tells the operator what to do when
+ * this exits non-zero).
+ */
+
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT } from './lib/config-resolver.js';
+import { syncBranchFromBase } from './lib/git/sync-from-base.js';
+import { gitSpawn, gitSync } from './lib/git-utils.js';
+import { Logger } from './lib/Logger.js';
+
+const progress = Logger.createProgress('sync-branch-from-base', {
+  stderr: true,
+});
+
+/**
+ * Core runner. Exported for tests so the CLI surface can be exercised
+ * without spawning a subprocess.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.branch] Branch name expected to be checked out.
+ * @param {string} [opts.base] Base branch name on origin (e.g. `main`).
+ * @param {string} [opts.cwd] Worktree or repo root. Defaults to PROJECT_ROOT.
+ * @param {typeof syncBranchFromBase} [opts.injectedSync] Test-only seam.
+ * @param {(cwd: string, ...args: string[]) => string} [opts.injectedGitSync]
+ *   Test-only seam for the branch-name guard.
+ */
+export async function runSyncBranchFromBase(opts = {}) {
+  const parsed = opts.branch ? opts : parseArgv(process.argv.slice(2));
+  const branch = opts.branch ?? parsed.branch;
+  const base = opts.base ?? parsed.base;
+  if (!branch || !base) {
+    throw new Error(
+      'Usage: node sync-branch-from-base.js --branch <branchName> --base <baseBranch> [--cwd <path>]',
+    );
+  }
+  const cwd = path.resolve(opts.cwd ?? parsed.cwd ?? PROJECT_ROOT);
+
+  // Guard: refuse to sync if the active branch doesn't match the
+  // operator's intent. A mismatched checkout would merge `origin/<base>`
+  // into the wrong branch — silently — and only surface as a confusing
+  // diff later. Skipped when injectedGitSync is set so tests can run
+  // without a real git repo.
+  const gitSyncFn = opts.injectedGitSync ?? gitSync;
+  let activeBranch = null;
+  try {
+    activeBranch = gitSyncFn(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+  } catch (err) {
+    throw new Error(
+      `[sync-branch-from-base] Could not resolve active branch in ${cwd}: ${err?.message ?? err}`,
+    );
+  }
+  if (activeBranch !== branch) {
+    throw new Error(
+      `[sync-branch-from-base] Active branch is "${activeBranch}" but --branch is "${branch}". ` +
+        `Check out ${branch} first, or pass --cwd to the correct worktree.`,
+    );
+  }
+
+  progress('INIT', `Syncing ${branch} from origin/${base} in ${cwd}...`);
+  const syncFn = opts.injectedSync ?? syncBranchFromBase;
+  const result = await syncFn({
+    cwd,
+    baseBranch: base,
+    log: (tag, msg) => progress(tag, msg),
+    gitSpawn,
+  });
+
+  Logger.info(
+    `\n--- SYNC RESULT ---\n${JSON.stringify(result, null, 2)}\n--- END RESULT ---\n`,
+  );
+
+  if (!result.synced) {
+    const detail =
+      result.kind === 'conflict'
+        ? `: ${result.conflictFiles?.join(', ') ?? '(no file list)'}`
+        : result.stderr
+          ? `: ${result.stderr.slice(0, 200)}`
+          : '';
+    throw new Error(
+      `[sync-branch-from-base] sync failed (${result.kind})${detail}`,
+    );
+  }
+  progress('DONE', `✅ Synced ${branch} from origin/${base} (${result.kind}).`);
+  return { success: true, result };
+}
+
+/**
+ * Tiny argv parser scoped to this CLI's three flags. Exported for
+ * tests.
+ */
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      branch: { type: 'string' },
+      base: { type: 'string' },
+      cwd: { type: 'string' },
+    },
+    strict: false,
+  });
+  return {
+    branch: values.branch ?? null,
+    base: values.base ?? null,
+    cwd: values.cwd ?? null,
+  };
+}
+
+runAsCli(import.meta.url, runSyncBranchFromBase, {
+  source: 'sync-branch-from-base',
+});

package/.agents/scripts/sync-claude-commands.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * Projects .agents/workflows/ into a flat `.claude/commands/` tree so Claude
+ * Code exposes each workflow as a bare `/<name>` slash command. The workflows
+ * directory remains the single source of truth; this script is the only writer
+ * of `.claude/commands/`.
+ *
+ * Flat projection (reverts the #3576 plugin cutover): the plugin command tree
+ * (`.claude/plugins/mandrel/`) and the repo-local marketplace
+ * (`.claude/.claude-plugin/marketplace.json`) are NOT written, because the
+ * plugin system is unavailable in some Claude Code environments (`/plugin` not
+ * present), which left the namespaced `/mandrel:<name>` commands unreachable.
+ * Flat `.claude/commands/*.md` is the surface that loads across every
+ * environment (CLI, IDE, GUI, web, SDK). On a machine that previously synced
+ * the plugin tree, this script reaps it on the next run (see reapPluginTree).
+ *
+ * Only top-level .md files are projected. The `.agents/workflows/helpers/`
+ * subdirectory holds path-included modules (e.g. epic-code-review, epic-retro)
+ * that parent workflows read by relative path — they are intentionally **not**
+ * exposed as commands, so helpers/ is skipped.
+ *
+ * Usage:  node .agents/scripts/sync-claude-commands.js
+ */
+
+// cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { applyHeader } from './lib/command-header.js';
+import { Logger } from './lib/Logger.js';
+
+// Resolve the project root from the invocation cwd — the consumer project where
+// `.agents/` is materialized and where Claude Code loads `.claude/commands/`.
+// It MUST NOT use `__dirname/../..`: in an npm-installed consumer this script
+// runs from `node_modules/mandrel/.agents/scripts/`, so that climb
+// lands on the package dir and the commands would be written *inside
+// node_modules* rather than the consumer — leaving `/<name>` commands
+// unloadable and the `commands-in-sync` doctor check (which resolves the same
+// consumer root via cwd — Story #3588) reporting "N not synced". Every real
+// invocation runs with cwd at the project root: `npm run sync:commands`, the
+// UserPromptSubmit hook, and `mandrel sync-commands` (which inherits the
+// caller's cwd). Tests drive fixture trees via the SYNC_CLAUDE_COMMANDS_SRC/DEST
+// overrides below.
+const PROJECT_ROOT = process.cwd();
+
+// Env-var overrides exist so the sync logic can be exercised against a
+// fixture workflow tree in isolation (regression test for the Epic #1185
+// frontmatter pass-through contract). When unset, behaviour is unchanged
+// — the script defaults to the real workflows / commands directories.
+const SRC_DIR =
+  process.env.SYNC_CLAUDE_COMMANDS_SRC ??
+  path.join(PROJECT_ROOT, '.agents', 'workflows');
+const DEST_DIR =
+  process.env.SYNC_CLAUDE_COMMANDS_DEST ??
+  path.join(PROJECT_ROOT, '.claude', 'commands');
+
+export const HEADER =
+  '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
+
+/**
+ * Reap the generated plugin projection (the #3576 surface) so the namespaced
+ * `/mandrel:<name>` commands and the repo-local marketplace stop shadowing the
+ * flat `/<name>` commands. This is the cutover-back step on existing machines:
+ * the plugin tree is no longer written, but a developer who synced under #3576
+ * still has it on disk. Removing `.claude/plugins/mandrel/` and the marketplace
+ * listing is idempotent and never blocks the flat sync.
+ *
+ * Skipped when SYNC_CLAUDE_COMMANDS_DEST is set (fixture runs own their tree).
+ *
+ * @returns {void}
+ */
+function reapPluginTree() {
+  if (process.env.SYNC_CLAUDE_COMMANDS_DEST) return;
+  const pluginRoot = path.join(PROJECT_ROOT, '.claude', 'plugins', 'mandrel');
+  const marketplace = path.join(
+    PROJECT_ROOT,
+    '.claude',
+    '.claude-plugin',
+    'marketplace.json',
+  );
+  for (const target of [pluginRoot, marketplace]) {
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+    } catch (err) {
+      Logger.warn(`  skip reap ${target}: ${err.message}`);
+    }
+  }
+  // Remove the now-empty .claude-plugin/ dir (ignore if absent or non-empty).
+  try {
+    fs.rmdirSync(path.join(PROJECT_ROOT, '.claude', '.claude-plugin'));
+  } catch {
+    /* not empty or absent — leave it */
+  }
+}
+
+reapPluginTree();
+fs.mkdirSync(DEST_DIR, { recursive: true });
+
+// Only sync top-level .md files. Subdirectories (notably helpers/) are
+// ignored — they contain path-included modules, not slash commands.
+const isTopLevelWorkflow = (entry) =>
+  entry.isFile() && entry.name.endsWith('.md');
+
+const existing = fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
+const sources = fs
+  .readdirSync(SRC_DIR, { withFileTypes: true })
+  .filter(isTopLevelWorkflow)
+  .map((entry) => entry.name);
+const sourceSet = new Set(sources);
+
+for (const file of existing) {
+  if (!sourceSet.has(file)) {
+    fs.unlinkSync(path.join(DEST_DIR, file));
+    Logger.info(`  removed  ${file} (no longer in workflows)`);
+  }
+}
+
+// Copy each workflow, injecting the auto-generated header after any leading
+// frontmatter (so the `---` block stays on line 1 and Claude Code parses the
+// command description). Parallelised so the ~30-file sync doesn't serialise on
+// per-file fs latency (noticeable on Windows where each syscall pays a larger
+// fixed cost).
+let synced = 0;
+await Promise.all(
+  sources.map(async (file) => {
+    const content = await fs.promises.readFile(
+      path.join(SRC_DIR, file),
+      'utf8',
+    );
+    const dest = path.join(DEST_DIR, file);
+    const target = applyHeader(content, HEADER);
+
+    // Skip write if content is already identical (avoid noisy git diffs).
+    // Use try/catch over existsSync+readFile so we only pay one syscall.
+    try {
+      const existingContent = await fs.promises.readFile(dest, 'utf8');
+      if (existingContent === target) return;
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+
+    await fs.promises.writeFile(dest, target, 'utf8');
+    synced++;
+    Logger.info(`  synced   ${file}`);
+  }),
+);
+
+Logger.info(
+  `\n✔ ${synced} file(s) synced, ${sources.length} total commands in .claude/commands/`,
+);

package/.agents/scripts/test-isolate.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * test-isolate — diagnose test-pollution cascades.
+ *
+ * Runs the matching test files individually (`--test-concurrency=1`,
+ * one process per file), then again as a single suite under default
+ * concurrency. Files that pass alone but fail in the suite are
+ * **flippers**. For each flipper the script binary-bisects the
+ * remaining files to surface the smallest reproducing subset (the
+ * polluter suspect set).
+ *
+ * Files whose process exited with leftover `process.env` mutations are
+ * called out so an operator can spot global-state leaks at a glance —
+ * even when the failure cascade hasn't yet manifested. See
+ * `lib/test-isolate/env-snapshot-loader.js`.
+ *
+ * Usage:
+ *
+ *   node .agents/scripts/test-isolate.js                   # all tests
+ *   node .agents/scripts/test-isolate.js 'tests/lib/**'    # glob subset
+ *   node .agents/scripts/test-isolate.js tests/foo.test.js # single file
+ *
+ * Output: human-readable text by default; pass `--json` for the raw
+ * report envelope.
+ */
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveTestFiles } from './lib/test-isolate/list-files.js';
+import { diagnoseIsolation } from './lib/test-isolate/runner.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * @param {string[]} argv
+ */
+export function parseIsolateArgv(argv) {
+  const options = {
+    pattern: undefined,
+    workers: undefined,
+    maxBisectDepth: 8,
+    maxBisectTargets: 5,
+    suiteConcurrency: 8,
+    json: false,
+    quiet: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--workers' && argv[i + 1]) {
+      options.workers = Number(argv[++i]);
+    } else if (arg === '--max-bisect-depth' && argv[i + 1]) {
+      options.maxBisectDepth = Number(argv[++i]);
+    } else if (arg === '--max-bisect-targets' && argv[i + 1]) {
+      options.maxBisectTargets = Number(argv[++i]);
+    } else if (arg === '--suite-concurrency' && argv[i + 1]) {
+      options.suiteConcurrency = Number(argv[++i]);
+    } else if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--quiet') {
+      options.quiet = true;
+    } else if (!arg.startsWith('--') && !options.pattern) {
+      options.pattern = arg;
+    }
+  }
+  return options;
+}
+
+/**
+ * @param {import('./lib/test-isolate/runner.js').IsolateReport} report
+ */
+export function renderReport(report) {
+  const lines = [];
+  lines.push('');
+  lines.push('=== test-isolate diagnostic report ===');
+  lines.push(`Files scanned:  ${report.files.length}`);
+  lines.push(`Wall duration:  ${(report.durationMs / 1000).toFixed(1)}s`);
+  lines.push('');
+
+  if (report.flippers.length === 0) {
+    lines.push('✓ No flippers detected — every file that passed alone');
+    lines.push('  also passed in the full suite run.');
+  } else {
+    lines.push(`✗ ${report.flippers.length} flipper(s) detected:`);
+    for (const f of report.flippers) {
+      lines.push(`  - ${f}`);
+    }
+    lines.push('');
+    if (report.bisections.length > 0) {
+      lines.push('Likely polluters (bisection suspects):');
+      for (const b of report.bisections) {
+        const tag = b.inconclusive ? ' [inconclusive]' : '';
+        lines.push(`  ${b.file}${tag}`);
+        for (const s of b.suspects) {
+          lines.push(`    ← ${s}`);
+        }
+      }
+    }
+  }
+
+  lines.push('');
+  if (report.envMutators.length === 0) {
+    lines.push('✓ No env-var leaks detected across isolated runs.');
+  } else {
+    lines.push(
+      `⚠ ${report.envMutators.length} file(s) left process.env mutated:`,
+    );
+    for (const m of report.envMutators) {
+      const parts = [];
+      if (m.envDiff.added.length > 0) {
+        parts.push(`added=[${m.envDiff.added.join(', ')}]`);
+      }
+      if (m.envDiff.removed.length > 0) {
+        parts.push(`removed=[${m.envDiff.removed.join(', ')}]`);
+      }
+      if (m.envDiff.changed.length > 0) {
+        parts.push(`changed=[${m.envDiff.changed.join(', ')}]`);
+      }
+      lines.push(`  ${m.file}`);
+      lines.push(`    ${parts.join(' ')}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Programmatic entry — wired up by the CLI and exported for tests.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]
+ * @param {string} [opts.repoRoot]
+ * @param {(line: string) => void} [opts.onLog]
+ * @returns {Promise<{ exitCode: number, report: import('./lib/test-isolate/runner.js').IsolateReport }>}
+ */
+export async function runTestIsolate({
+  argv = process.argv.slice(2),
+  repoRoot = ROOT,
+  onLog = (s) => process.stdout.write(`${s}\n`),
+} = {}) {
+  const options = parseIsolateArgv(argv);
+  const files = resolveTestFiles({
+    pattern: options.pattern,
+    repoRoot,
+  });
+  if (files.length === 0) {
+    onLog(
+      `[test-isolate] no test files matched pattern: ${options.pattern ?? '<default>'}`,
+    );
+    return { exitCode: 0, report: emptyReport() };
+  }
+
+  if (!options.quiet) {
+    onLog(`[test-isolate] scanning ${files.length} file(s)...`);
+  }
+  const report = await diagnoseIsolation({
+    repoRoot,
+    files,
+    workers: options.workers,
+    suiteConcurrency: options.suiteConcurrency,
+    maxBisectDepth: options.maxBisectDepth,
+    maxBisectTargets: options.maxBisectTargets,
+    onProgress: options.quiet
+      ? undefined
+      : (stage, payload) => {
+          if (stage === 'isolated:start') {
+            onLog(`[test-isolate] isolated phase: ${payload.count} file(s)`);
+          } else if (stage === 'isolated:done') {
+            onLog('[test-isolate] isolated phase: done');
+          } else if (stage === 'suite:start') {
+            onLog(`[test-isolate] suite phase: ${payload.count} file(s)`);
+          } else if (stage === 'suite:done') {
+            onLog('[test-isolate] suite phase: done');
+          } else if (stage === 'bisect:start') {
+            onLog(`[test-isolate] bisecting flipper: ${payload.target}`);
+          } else if (stage === 'bisect:done') {
+            const list = payload.suspects.slice(0, 3).join(', ');
+            const more =
+              payload.suspects.length > 3
+                ? ` (+${payload.suspects.length - 3} more)`
+                : '';
+            onLog(`[test-isolate]   suspects: ${list}${more}`);
+          }
+        },
+  });
+
+  if (options.json) {
+    onLog(JSON.stringify(report, null, 2));
+  } else {
+    onLog(renderReport(report));
+  }
+
+  const exitCode =
+    report.flippers.length === 0 && report.envMutators.length === 0 ? 0 : 1;
+  return { exitCode, report };
+}
+
+function emptyReport() {
+  return {
+    pattern: null,
+    files: [],
+    isolated: [],
+    suite: [],
+    flippers: [],
+    bisections: [],
+    envMutators: [],
+    durationMs: 0,
+  };
+}
+
+runAsCli(
+  import.meta.url,
+  async () => {
+    const { exitCode } = await runTestIsolate();
+    if (exitCode !== 0) process.exit(exitCode);
+  },
+  { source: 'test-isolate' },
+);

package/.agents/scripts/test-wrapper.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * test-wrapper.js — npm-test preflight gate.
+ *
+ * Story #1289 wires the self-healing checks registry in front of
+ * `npm test` so the suite refuses to start in a known-bad state (e.g.
+ * core.bare flipped on the main checkout, missing `.env` / `.mcp.json`
+ * bootstrap files, etc.). The wrapper runs
+ * `runChecks({ scope: 'npm-test', autoFix: true })` against the assembled
+ * state probe; on any surviving blocker it prints a `id · summary ·
+ * fixCommand` table and exits with code 2 (the project-wide "preflight
+ * refused" reservation).
+ *
+ * On a clean preflight npm continues to `.agents/scripts/run-tests.js`, which
+ * execs the underlying Node test runner and cleans test-reserved temp
+ * artefacts afterward. This wrapper itself adds no top-level npm dependencies.
+ *
+ * Wiring: `package.json` points `pretest` at this script. The `test`
+ * script remains the node --test invocation so `npm test` still picks up
+ * `pretest` automatically per npm lifecycle rules. A failed pretest aborts
+ * the lifecycle without invoking the test runner — exit code 2 propagates
+ * out through npm.
+ *
+ * Bypass: set `SKIP_PREFLIGHT=1` to skip the gate entirely (used by the
+ * `coverage` script which manages its own preflight separately, and by
+ * any debugging session that needs the suite to run despite a known
+ * blocker the operator is iterating on).
+ *
+ * Usage:
+ *   node .agents/scripts/test-wrapper.js              # full preflight + test
+ *   SKIP_PREFLIGHT=1 node .agents/scripts/test-wrapper.js  # skip gate
+ */
+
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+import {
+  PREFLIGHT_REFUSED_EXIT_CODE,
+  runPreflight,
+} from './lib/preflight-runner.js';
+
+/** Default Logger adapter — same shape preflight-runner uses. */
+const DEFAULT_LOGGER = {
+  info: (msg) => Logger.info(msg),
+  warn: (msg) => Logger.warn(msg),
+  error: (msg) => Logger.error(msg),
+};
+
+/**
+ * Run the npm-test preflight gate. Exported so unit tests can drive it
+ * directly with an inline registry, without actually spawning the test
+ * runner. Returns `{ status: 'ok' | 'blocked' }` plus the findings/fixed
+ * arrays from the runner.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {object} [opts.probes]   Test-only probe injection.
+ * @param {object} [opts.registry] Test-only inline registry — bypasses
+ *   `loadRegistry()`.
+ * @param {string} [opts.dir]      Test-only fixture directory.
+ * @param {{ info?: Function, warn?: Function, error?: Function }} [opts.logger]
+ * @returns {Promise<{ status: 'ok' | 'blocked', findings: Array, fixed: Array }>}
+ */
+export async function runTestWrapperPreflight({
+  cwd = process.cwd(),
+  probes,
+  registry,
+  dir,
+  logger = DEFAULT_LOGGER,
+} = {}) {
+  logger.info('[npm-test] Running preflight checks (scope=npm-test)...');
+  const preflight = await runPreflight({
+    scope: 'npm-test',
+    autoFix: true,
+    cwd,
+    probes,
+    registry,
+    dir,
+    logger,
+  });
+  return {
+    status: preflight.blocked ? 'blocked' : 'ok',
+    findings: preflight.findings,
+    fixed: preflight.fixed,
+  };
+}
+
+runAsCli(
+  import.meta.url,
+  async () => {
+    // Operator bypass for iterative debugging — see the file header.
+    if (process.env.SKIP_PREFLIGHT === '1') {
+      Logger.warn(
+        '[npm-test] SKIP_PREFLIGHT=1 — bypassing preflight checks (debugging mode).',
+      );
+      return;
+    }
+    const result = await runTestWrapperPreflight();
+    if (result.status === 'blocked') {
+      // The wrapper never spawns the test runner on a blocked preflight.
+      // Exit code 2 propagates out through `npm run pretest` and short-
+      // circuits the `npm test` lifecycle before the test command runs.
+      process.exit(PREFLIGHT_REFUSED_EXIT_CODE);
+    }
+  },
+  { source: 'test-wrapper' },
+);