mandrel 1.60.0 → 1.62.0

package/bin/mandrel.js

@@ -2,35 +2,252 @@
 // bin/mandrel.js — mandrel CLI entry point
 
 /**
- * Convention-based subcommand dispatcher.
+ * Allowlist-based subcommand dispatcher.
  *
- * Resolves `process.argv[2]` to `lib/cli/<name>.js` and dynamically
- * imports it so the subcommand surface can grow without touching this
- * file. Each subcommand module must export a default function `run(argv)`.
+ * Only modules listed in SUBCOMMANDS are dispatchable. Each entry declares the
+ * name, a one-line description for help output, and the set of known flags so
+ * the dispatcher can reject unknown flags before loading the subcommand.
+ *
+ * Supported top-level flags:
+ *   --help / -h    Print subcommand list and exit 0.
+ *   --version      Print installed version and exit 0.
+ *
+ * Each subcommand module must export a default function `run(argv)`.
  */
 
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-function usage(badSub) {
-  if (badSub) {
-    process.stderr.write(
-      `mandrel: unknown subcommand '${badSub}'\n\nUsage: mandrel <subcommand> [args]\n`,
-    );
-  } else {
-    process.stderr.write('Usage: mandrel <subcommand> [args]\n');
+// ---------------------------------------------------------------------------
+// Subcommand registry — the ONLY allowed dispatch targets
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ description: string, knownFlags: Set<string> }} SubcommandMeta
+ * @type {Map<string, SubcommandMeta>}
+ */
+const SUBCOMMANDS = new Map([
+  [
+    'init',
+    {
+      description: 'install and configure mandrel in the current project',
+      knownFlags: new Set([
+        '--assume-yes',
+        '--skip-github',
+        '--owner',
+        '--repo',
+        '--base-branch',
+        '--project-number',
+        '--operator-handle',
+        '--dry-run',
+      ]),
+    },
+  ],
+  [
+    'sync',
+    {
+      description: 'materialize .agents/ payload from installed package',
+      knownFlags: new Set(['--dry-run']),
+    },
+  ],
+  [
+    'sync-commands',
+    {
+      description: 'regenerate .claude/commands/ from .agents/workflows/',
+      knownFlags: new Set(['--dry-run']),
+    },
+  ],
+  [
+    'doctor',
+    {
+      description: 'run readiness checks and report remedies',
+      knownFlags: new Set([]),
+    },
+  ],
+  [
+    'update',
+    {
+      description: 'upgrade mandrel to the newest published version',
+      knownFlags: new Set(['--dry-run', '--install-cmd']),
+    },
+  ],
+  [
+    'migrate',
+    {
+      description: 'apply version-keyed migrations for a version range',
+      knownFlags: new Set(['--from', '--to', '--dry-run']),
+    },
+  ],
+  [
+    'explain',
+    {
+      description: 'print resolved config values and their sources',
+      knownFlags: new Set(['--json']),
+    },
+  ],
+  [
+    'uninstall',
+    {
+      description: 'reverse a recorded install using the install ledger',
+      knownFlags: new Set(['--include-github', '--dry-run']),
+    },
+  ],
+]);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the installed mandrel version from the root package.json.
+ *
+ * @returns {string}
+ */
+function installedVersion() {
+  const req = createRequire(import.meta.url);
+  const manifest = req('../package.json');
+  return String(manifest.version);
+}
+
+/**
+ * Print the help screen listing all subcommands with descriptions.
+ *
+ * @param {(s: string) => void} [write]
+ */
+function printHelp(write = (s) => process.stdout.write(s)) {
+  const lines = ['Usage: mandrel <subcommand> [args]\n', '\nSubcommands:\n'];
+  for (const [name, meta] of SUBCOMMANDS) {
+    const pad = ' '.repeat(Math.max(1, 16 - name.length));
+    lines.push(`  ${name}${pad}${meta.description}\n`);
+  }
+  lines.push(
+    '\nFlags:\n',
+    '  --help, -h    Print this help message\n',
+    '  --version     Print the installed version\n',
+    '\nRun `mandrel <subcommand> --help` for subcommand-specific flags.\n',
+  );
+  write(lines.join(''));
+}
+
+/**
+ * Suggest the closest known subcommand name for a typo (Levenshtein-1).
+ *
+ * @param {string} input
+ * @returns {string | undefined}
+ */
+function suggest(input) {
+  for (const name of SUBCOMMANDS.keys()) {
+    if (levenshtein(input, name) <= 2) return name;
+  }
+  return undefined;
+}
+
+/**
+ * Compute Levenshtein edit distance between two strings (capped at 3 for
+ * performance — we only care about small distances).
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (Math.abs(a.length - b.length) > 3) return 4;
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const curr = [i + 1];
+    for (let j = 0; j < b.length; j++) {
+      curr[j + 1] = Math.min(
+        curr[j] + 1,
+        prev[j + 1] + 1,
+        prev[j] + (a[i] === b[j] ? 0 : 1),
+      );
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+
+/**
+ * Universal flags that all subcommands accept and that bypass per-subcommand
+ * flag validation. Subcommands may handle these themselves internally.
+ */
+const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
+
+/**
+ * Validate the argv array against the known flags for a subcommand.
+ * Returns null when all flags are known; an error message string when an
+ * unknown flag is detected. Values following `=` or the next positional are
+ * allowed — only the flag name prefix is checked.
+ *
+ * Universal flags (--help, -h) are always allowed and bypass this check.
+ *
+ * @param {string} subName
+ * @param {Set<string>} knownFlags
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+function findUnknownFlag(subName, knownFlags, argv) {
+  for (const arg of argv) {
+    if (!arg.startsWith('-')) continue;
+    // Strip value portion for `--flag=value` form.
+    const flagName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+    if (UNIVERSAL_FLAGS.has(flagName)) continue;
+    if (!knownFlags.has(flagName)) {
+      const names = [...knownFlags].sort().join(', ');
+      const hint = names.length > 0 ? `  Known flags: ${names}\n` : '';
+      return (
+        `mandrel: unknown flag '${flagName}' for subcommand '${subName}'\n` +
+        hint
+      );
+    }
   }
+  return null;
 }
 
-const sub = process.argv[2];
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const sub = args[0];
+
+// --- Top-level flags (no subcommand) ---
+if (!sub || sub === '--help' || sub === '-h') {
+  printHelp();
+  process.exit(0);
+}
 
-if (!sub) {
-  usage();
+if (sub === '--version') {
+  process.stdout.write(`${installedVersion()}\n`);
+  process.exit(0);
+}
+
+// --- Subcommand lookup ---
+const meta = SUBCOMMANDS.get(sub);
+if (!meta) {
+  const subcommandList = [...SUBCOMMANDS.keys()].join(', ');
+  const hint = suggest(sub);
+  const didYouMean = hint ? `\n  Did you mean '${hint}'?` : '';
+  process.stderr.write(
+    `mandrel: unknown subcommand '${sub}'${didYouMean}\n` +
+      `  Available subcommands: ${subcommandList}\n`,
+  );
+  process.exit(1);
+}
+
+// --- Unknown-flag rejection ---
+const subArgv = args.slice(1);
+const unknownFlagError = findUnknownFlag(sub, meta.knownFlags, subArgv);
+if (unknownFlagError) {
+  process.stderr.write(unknownFlagError);
   process.exit(1);
 }
 
+// --- Load and dispatch ---
 const subFile = path.resolve(__dirname, '..', 'lib', 'cli', `${sub}.js`);
 const subFileUrl = pathToFileURL(subFile).href;
 
@@ -39,7 +256,9 @@ try {
   mod = await import(subFileUrl);
 } catch (err) {
   if (err.code === 'ERR_MODULE_NOT_FOUND' && err.message.includes(subFile)) {
-    usage(sub);
+    process.stderr.write(
+      `mandrel: subcommand '${sub}' module not found — this is a bug\n`,
+    );
     process.exit(1);
   }
   // Re-throw broken-module errors so they are visible rather than masked.
@@ -53,4 +272,4 @@ if (typeof mod.default !== 'function') {
   process.exit(1);
 }
 
-await mod.default(process.argv.slice(3));
+await mod.default(subArgv);

package/docs/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.62.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.61.0...mandrel-v1.62.0) (2026-06-12)
+
+
+### Added
+
+* /deliver composes a sequential segment plan over mixed Epic and standalone-Story ID sets (refs [#4062](https://github.com/dsj1984/mandrel/issues/4062)) ([#4063](https://github.com/dsj1984/mandrel/issues/4063)) ([a83d29e](https://github.com/dsj1984/mandrel/commit/a83d29e032b7f6b6846d7988f071d6b6416df2f9))
+
+
+### Fixed
+
+* make mandrel update no-op short-circuit drift-aware (refs [#4065](https://github.com/dsj1984/mandrel/issues/4065)) ([#4066](https://github.com/dsj1984/mandrel/issues/4066)) ([693f1cf](https://github.com/dsj1984/mandrel/commit/693f1cf5bf8fd7d29fed910659708ffceb7a54cb))
+
+## [1.61.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.60.0...mandrel-v1.61.0) (2026-06-12)
+
+
+### ⚠ BREAKING CHANGES
+
+* mandrel update no longer refuses major version bumps and the --major flag is removed; major upgrades apply like any other update.
+
+### Added
+
+* **init:** fold onboarding into mandrel init, retire /onboard (refs [#4045](https://github.com/dsj1984/mandrel/issues/4045)) ([#4050](https://github.com/dsj1984/mandrel/issues/4050)) ([2b2c115](https://github.com/dsj1984/mandrel/commit/2b2c115ad4f5394cefb2ecfcc72ddbd0dae6683a))
+* make the CLI behave like a CLI: dispatcher, help, flag rejection, TS peer, engines floor ([#4047](https://github.com/dsj1984/mandrel/issues/4047)) ([#4053](https://github.com/dsj1984/mandrel/issues/4053)) ([c625573](https://github.com/dsj1984/mandrel/commit/c625573c9feb0908d897bb0f2778c2b22ee28b04))
+* one implementation per concept: install-surface dead-code deletion and helper unification ([#4048](https://github.com/dsj1984/mandrel/issues/4048)) ([#4054](https://github.com/dsj1984/mandrel/issues/4054)) ([ffb5dc7](https://github.com/dsj1984/mandrel/commit/ffb5dc72f25fedc70829dd70c64e14e3dfa18c72))
+* remediate documentation audit, remove the major-upgrade gate, and retire stranded consumer runbooks ([#4061](https://github.com/dsj1984/mandrel/issues/4061)) ([fa429e4](https://github.com/dsj1984/mandrel/commit/fa429e490b7d410938eeec24ef44ffc7857cf470))
+* **update:** make upgrade loop truthful — cache bypass, sync prune, cwd anchoring (refs [#4046](https://github.com/dsj1984/mandrel/issues/4046)) ([#4051](https://github.com/dsj1984/mandrel/issues/4051)) ([1a89a7c](https://github.com/dsj1984/mandrel/commit/1a89a7cc1150f26d87a93f58e2fd940670604381))
+
+
+### Fixed
+
+* close the 9 post-merge review findings on the install/bootstrap batch ([#4060](https://github.com/dsj1984/mandrel/issues/4060)) ([4e76441](https://github.com/dsj1984/mandrel/commit/4e76441c1620481e49ac33e4884e604dc8366f48))
+* packaging and CI prove the install contract; retire the install-bootstrap review doc ([#4049](https://github.com/dsj1984/mandrel/issues/4049)) ([#4057](https://github.com/dsj1984/mandrel/issues/4057)) ([1051ed1](https://github.com/dsj1984/mandrel/commit/1051ed130f5720edcb3ca8e4cfe898ec00495eb5))
+* **tests:** add shell:true to spawnSync for Windows npm.cmd compat (refs [#4049](https://github.com/dsj1984/mandrel/issues/4049)) ([#4059](https://github.com/dsj1984/mandrel/issues/4059)) ([f5abcd5](https://github.com/dsj1984/mandrel/commit/f5abcd550e7e4110372b35c56abe55931ce3058a))
+* **transpile:** add typescript to devDependencies so Windows CI finds it ([#4055](https://github.com/dsj1984/mandrel/issues/4055)) ([8f0a6bd](https://github.com/dsj1984/mandrel/commit/8f0a6bdf6681286d8b691e1b9163639613ce8f9f))
+* **transpile:** use pathToFileURL for ESM import on Windows ([#4056](https://github.com/dsj1984/mandrel/issues/4056)) ([2e3d210](https://github.com/dsj1984/mandrel/commit/2e3d210b8e351e8b23ae4e5272ff7d950792b29b))
+
 ## [1.60.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.59.0...mandrel-v1.60.0) (2026-06-11)
 
 

package/lib/cli/doctor.js

@@ -17,11 +17,15 @@
  * Exit code 0 = all pass, 1 = any fail.
  *
  * Injectable seams (used by tests):
- *   - `checks`  — replaces the default registry array
- *   - `write`   — replaces process.stdout.write
- *   - `exit`    — replaces process.exit
+ *   - `checks`           — replaces the default registry array
+ *   - `write`            — replaces process.stdout.write
+ *   - `exit`             — replaces process.exit
+ *   - `writeResultCache` — replaces the temp/doctor-result.json writer
  */
 
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
 import { registry } from './registry.js';
 
 // ---------------------------------------------------------------------------
@@ -74,6 +78,40 @@ function formatSummary(passed, total) {
   return `❌  Not ready (${failed}/${total} checks failed)\n`;
 }
 
+// ---------------------------------------------------------------------------
+// Result cache
+// ---------------------------------------------------------------------------
+
+/**
+ * Best-effort write of the doctor verdict to `temp/doctor-result.json` under
+ * the consumer root so downstream workflows (e.g. the `/plan` first-run
+ * preflight) can read the last recorded verdict without re-running doctor.
+ * `temp/` is the gitignored scratch root, so neither git nor the sync prune
+ * pass ever sees the cache. Any write failure is swallowed — the cache is
+ * advisory, never a gate.
+ *
+ * Exported for testing.
+ *
+ * @param {'ready'|'unready'} verdict
+ * @param {{ fs?: typeof nodeFs, cwd?: () => string }} [opts]
+ * @returns {void}
+ */
+export function writeDoctorResultCache(
+  verdict,
+  { fs = nodeFs, cwd = process.cwd } = {},
+) {
+  try {
+    const dir = path.join(cwd(), 'temp');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, 'doctor-result.json'),
+      `${JSON.stringify({ verdict, checkedAt: new Date().toISOString() }, null, 2)}\n`,
+    );
+  } catch {
+    // Best-effort only — an unwritable temp/ must never fail the doctor run.
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Doctor runner (exported for testing)
 // ---------------------------------------------------------------------------
@@ -85,6 +123,7 @@ function formatSummary(passed, total) {
  *   checks?: Array<{ name: string, run(opts?: unknown): { ok: boolean, detail: string, remedy?: string } }>,
  *   write?: (s: string) => void,
  *   exit?: (code: number) => void,
+ *   writeResultCache?: (verdict: 'ready'|'unready') => void,
  * }} [opts]
  * @returns {void}
  */
@@ -92,6 +131,7 @@ export async function runDoctor({
   checks = registry,
   write = (s) => process.stdout.write(s),
   exit = (code) => process.exit(code),
+  writeResultCache = writeDoctorResultCache,
 } = {}) {
   let passed = 0;
 
@@ -104,6 +144,8 @@ export async function runDoctor({
   const total = checks.length;
   write(formatSummary(passed, total));
 
+  writeResultCache(passed === total ? 'ready' : 'unready');
+
   if (passed < total) {
     exit(1);
   }

package/lib/cli/init.js

@@ -66,6 +66,30 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// Lazily resolved at runtime so cold-start `npx mandrel init` (where
+// `.agents/` is absent) does not try to import from a directory that does not
+// exist yet. The import is performed after bootstrap succeeds and `.agents/`
+// is guaranteed to be materialised.
+let _runInitTail = null;
+async function getRunInitTail(projectRoot) {
+  if (_runInitTail) return _runInitTail;
+  const tailPath = path.join(
+    projectRoot,
+    '.agents',
+    'scripts',
+    'lib',
+    'onboard',
+    'init-tail.js',
+  );
+  // pathToFileURL handles Windows drive letters correctly (a raw
+  // `file://C:\…` template treats the drive letter as a URL host — same
+  // fix as commit 2e3d210b in lib/transpile.js).
+  const mod = await import(pathToFileURL(tailPath).href);
+  _runInitTail = mod.runInitTail;
+  return _runInitTail;
+}
 
 /**
  * Hardcoded build-time package name. NEVER read from argv or env — cold-start
@@ -154,21 +178,23 @@ function buildBootstrapArgs(argv, assumeYes) {
  *   confirm?: () => boolean,
  *   stdout?: (s: string) => void,
  *   isTTY?: boolean,
+ *   afterBootstrap?: (root: string) => Promise<{ ok?: boolean } | void> | { ok?: boolean } | void,
  * }} [opts]
- * @returns {{
+ * @returns {Promise<{
  *   installed: boolean,
  *   ranBootstrap: boolean,
  *   steps: Array<{ cmd: string, args: string[] }>,
  *   exitCode: number,
- * }}
+ * }>}
  */
-export function planInit({
+export async function planInit({
   argv = [],
   exists,
   runStep,
   confirm,
   stdout = (s) => process.stdout.write(s),
   isTTY,
+  afterBootstrap,
 } = {}) {
   const steps = [];
 
@@ -243,11 +269,37 @@ export function planInit({
       BOOTSTRAP_SCRIPT,
       ...bootstrapArgs,
     ]);
+    if (bootstrapStatus !== 0) {
+      return {
+        installed,
+        ranBootstrap: true,
+        steps,
+        exitCode: bootstrapStatus,
+      };
+    }
+
+    // Bootstrap succeeded — run the onboarding tail: stack detection, docs
+    // scaffolding offer, doctor gate, and /plan handoff. A tail that reports
+    // `ok: false` (the doctor gate failed) makes the whole init exit
+    // non-zero; the tail already printed its own remediation message, and the
+    // earlier install/sync/bootstrap phases' results stand as completed.
+    if (afterBootstrap) {
+      const tail = await afterBootstrap(process.cwd());
+      if (tail && tail.ok === false) {
+        return {
+          installed,
+          ranBootstrap: true,
+          steps,
+          exitCode: 1,
+        };
+      }
+    }
+
     return {
       installed,
       ranBootstrap: true,
       steps,
-      exitCode: bootstrapStatus,
+      exitCode: 0,
     };
   }
 
@@ -309,9 +361,9 @@ function defaultConfirm() {
  * Default export consumed by `bin/mandrel.js`.
  *
  * @param {string[]} [argv] - Subcommand arguments (after `mandrel init`).
- * @returns {void}
+ * @returns {Promise<void>}
  */
-export default function run(argv = []) {
+export default async function run(argv = []) {
   if (argv.includes('--help') || argv.includes('-h')) {
     process.stdout.write(
       'Usage: mandrel init [bootstrap flags]\n\n' +
@@ -324,12 +376,19 @@ export default function run(argv = []) {
     return;
   }
 
-  const result = planInit({
+  const result = await planInit({
     argv,
     exists: defaultExists,
     runStep: defaultRunStep,
     confirm: defaultConfirm,
     isTTY: Boolean(process.stdin.isTTY),
+    afterBootstrap: async (projectRoot) => {
+      const runInitTail = await getRunInitTail(projectRoot);
+      return runInitTail({
+        root: projectRoot,
+        isTTY: Boolean(process.stdin.isTTY),
+      });
+    },
   });
 
   if (result.exitCode !== 0) {