mandrel 1.59.0 → 1.61.0

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

@@ -20,13 +20,15 @@
  *      `init` goes straight to the prompt — the one subcommand is idempotent
  *      across both the cold-start and post-install entry points.
  *
- *   2. **Two-option prompt.** Ask whether to configure now (option 1 → run
- *      `node .agents/scripts/bootstrap.js`, forwarding every passthrough flag
- *      unchanged) or stop at "just the files" (option 2 → print a re-run hint
- *      and exit 0). `--assume-yes` skips the prompt and configures (the flag is
- *      also forwarded to bootstrap for its own non-interactive run). A non-TTY
- *      stdin without `--assume-yes` defaults to option 2 (files-only) so the
- *      side-effecting GitHub provisioning never runs unattended.
+ *   2. **Yes/no prompt.** Ask whether to begin the interactive setup now
+ *      (yes → run `node .agents/scripts/bootstrap.js`, forwarding every
+ *      passthrough flag unchanged) or stop at "just the files" (no → print a
+ *      re-run hint and exit 0). Yes is the default, so a bare Enter configures
+ *      (mirrors the `[Y/n]` convention in bootstrap.js). `--assume-yes` skips
+ *      the prompt and configures (the flag is also forwarded to bootstrap for
+ *      its own non-interactive run). A non-TTY stdin without `--assume-yes`
+ *      defaults to no (files-only) so the side-effecting GitHub provisioning
+ *      never runs unattended.
  *
  * ## Cold-start provenance
  *
@@ -48,8 +50,9 @@
  *                  for `./.agents/` in the cwd
  *   - `runStep`  — `(cmd, args) => { status }`; runs one install/sync/bootstrap
  *                  step. Defaults to a `spawnSync` runner with `stdio: inherit`.
- *   - `confirm`  — `() => '1' | '2'`; reads the operator's numbered choice.
- *                  Defaults to a synchronous stdin readline prompt.
+ *   - `confirm`  — `() => boolean`; reads the operator's yes/no answer (true =
+ *                  configure now). Defaults to a synchronous stdin readline
+ *                  prompt with yes as the default.
  *   - `stdout`   — `(s) => void`; defaults to `process.stdout.write`.
  *   - `isTTY`    — boolean; defaults to `process.stdin.isTTY`.
  *   - `exit`     — `(code) => void`; defaults to `process.exit`.
@@ -63,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
@@ -92,12 +119,11 @@ const BOOTSTRAP_SCRIPT = path.join('.agents', 'scripts', 'bootstrap.js');
 const SYNC_BIN = path.join('node_modules', PACKAGE_NAME, 'bin', 'mandrel.js');
 
 const PROMPT_TEXT =
-  'Mandrel is installed. What next?\n' +
-  '  1) Configure my environment now (creates the GitHub repo + Projects board)\n' +
-  "  2) Just the files — I'll configure later\n" +
-  'Choice [1/2]: ';
+  'The Mandrel .agents package has been copied to your directory.\n' +
+  'Would you like to begin the interactive process to setup your local and ' +
+  'github environments now? [Y/n]: ';
 
-const FILES_ONLY_HINT = 'Configure any time with: mandrel init\n';
+const FILES_ONLY_HINT = 'Configure any time with: npx mandrel init\n';
 
 // On win32, `npm` resolves to a `.cmd` shim that Node refuses to spawn without
 // a shell after the CVE-2024-27980 hardening; mirror update.js and set
@@ -149,24 +175,26 @@ function buildBootstrapArgs(argv, assumeYes) {
  *   argv?: string[],
  *   exists?: (relPath: string) => boolean,
  *   runStep?: (cmd: string, args: string[]) => { status: number | null },
- *   confirm?: () => '1' | '2',
+ *   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 = [];
 
@@ -224,32 +252,58 @@ export function planInit({
   // Decide the outcome: configure (run bootstrap) vs. files-only.
   // - `--assume-yes` → configure, prompt skipped entirely.
   // - non-TTY without `--assume-yes` → files-only (never provision unattended).
-  // - TTY → consult the confirm seam for the numbered choice.
-  let choice;
+  // - TTY → consult the confirm seam for the yes/no answer (yes = configure).
+  let proceed;
   if (assumeYes) {
-    choice = '1';
+    proceed = true;
   } else if (!isTTY) {
-    choice = '2';
+    proceed = false;
   } else {
     stdout(PROMPT_TEXT);
-    choice = confirm();
+    proceed = confirm();
   }
 
-  if (choice === '1') {
+  if (proceed) {
     const bootstrapArgs = buildBootstrapArgs(argv, assumeYes);
     const bootstrapStatus = step(process.execPath, [
       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,
     };
   }
 
-  // Option 2 (files-only): print the re-run hint and exit cleanly.
+  // Declined (files-only): print the re-run hint and exit cleanly.
   stdout(FILES_ONLY_HINT);
   return { installed, ranBootstrap: false, steps, exitCode: 0 };
 }
@@ -284,32 +338,32 @@ function defaultRunStep(cmd, args) {
 }
 
 /**
- * Default `confirm` seam — synchronous numbered-choice prompt. Reads one line
- * from stdin and normalizes it to `'1'` or `'2'`; any input other than `'2'`
- * (including bare Enter) defaults to `'1'` (configure), matching the
- * `Choice [1/2]:` convention where the first option is the default.
+ * Default `confirm` seam — synchronous yes/no prompt. Reads one line from stdin
+ * and normalizes it to a boolean; any input other than an explicit "no"
+ * (`n`/`no`, case-insensitive) — including bare Enter — defaults to `true`
+ * (configure), matching the `[Y/n]` convention where yes is the default.
  *
- * @returns {'1' | '2'}
+ * @returns {boolean}
  */
 function defaultConfirm() {
   let answer = '';
   try {
     const buf = fs.readFileSync(0, 'utf8');
-    answer = buf.split('\n', 1)[0].trim();
+    answer = buf.split('\n', 1)[0].trim().toLowerCase();
   } catch {
     // No readable line (e.g. stdin closed) → fall through to the default.
     answer = '';
   }
-  return answer === '2' ? '2' : '1';
+  return answer !== 'n' && answer !== 'no';
 }
 
 /**
  * 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' +
@@ -322,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) {

package/lib/cli/registry.js

@@ -26,7 +26,17 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import {
+  REQUIRED_NODE_CEILING_MAJOR,
+  REQUIRED_NODE_FLOOR,
+  satisfiesNodeEngine,
+} from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
+import {
+  defaultResolvePackageRoot,
+  listFiles as listPayloadFiles,
+} from './sync.js';
 import { readCache } from './version-check.js';
+import { compareVersions as compareSemver } from './version-helpers.js';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -53,32 +63,6 @@ function spawn(cmd, args) {
 // check: node-version
 // ---------------------------------------------------------------------------
 
-/**
- * The minimum Node version the framework requires (`engines.node`).
- * Mirrors `lib/bootstrap/project-bootstrap.js#REQUIRED_NODE_FLOOR`.
- */
-const REQUIRED_NODE_FLOOR = '22.22.1';
-const REQUIRED_NODE_CEILING_MAJOR = 25;
-
-/**
- * Return true when `version` satisfies `>=22.22.1 <25`.
- *
- * @param {string} version
- * @returns {boolean}
- */
-function satisfiesNodeEngine(version) {
-  const [majorRaw, minorRaw, patchRaw] = String(version).split('.');
-  const major = Number.parseInt(majorRaw, 10) || 0;
-  const minor = Number.parseInt(minorRaw, 10) || 0;
-  const patch = Number.parseInt(patchRaw, 10) || 0;
-  if (major >= REQUIRED_NODE_CEILING_MAJOR) return false;
-  if (major > 22) return true;
-  if (major < 22) return false;
-  if (minor > 22) return true;
-  if (minor < 22) return false;
-  return patch >= 1;
-}
-
 /**
  * @param {{ nodeVersion?: string }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -235,19 +219,6 @@ function runGhAuth({ runner = spawn, env = process.env } = {}) {
 // check: commands-in-sync
 // ---------------------------------------------------------------------------
 
-/**
- * Resolve the project root — the directory that contains `.agents/` and
- * `.claude/`. Walks up from this file's own location.
- *
- * @returns {string}
- */
-function resolveProjectRoot() {
-  // lib/cli/registry.js lives at <root>/lib/cli/registry.js, so walk up two
-  // levels from __dirname to reach the project root.
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', '..');
-}
-
 /**
  * Dry-run the sync-claude-commands logic: compare `.agents/workflows/*.md`
  * sources to the generated flat command tree `.claude/commands/*.md`
@@ -324,6 +295,14 @@ function runCommandsInSync({ projectRoot, cwd, readDir } = {}) {
  * Verify that the framework's required runtime dependencies are resolvable
  * from the project's node_modules.
  *
+ * `projectRoot` defaults to `process.cwd()` (the consumer project root) so
+ * the manifest path and the require-resolution context mirror the context in
+ * which the framework scripts actually run (Story #4046 A2). Using
+ * `resolveProjectRoot()` (the package root inside `node_modules/mandrel/`)
+ * breaks the check under pnpm isolated-mode layouts where the consumer's
+ * node_modules are hoisted above `node_modules/mandrel/` and are invisible
+ * from the package root's resolver.
+ *
  * Injectable seams:
  * - `resolve(dep)` — replaces the real `require.resolve`; throws when a dep
  *   is missing.
@@ -338,10 +317,15 @@ function runRuntimeDeps({
   resolve: resolveSeam,
   manifestRequired,
 } = {}) {
+  // Anchor at process.cwd() (the consumer root), not resolveProjectRoot() (the
+  // package root). Under pnpm isolated-mode the consumer's node_modules are not
+  // visible from inside node_modules/mandrel/, so the old anchor produced false
+  // "missing" reports on a clean install (Story #4046 A2).
+  const root = projectRoot ?? process.cwd();
+
   let required = manifestRequired;
   if (!required) {
     try {
-      const root = projectRoot ?? resolveProjectRoot();
       const manifestPath = path.join(root, '.agents', 'runtime-deps.json');
       const raw = fs.readFileSync(manifestPath, 'utf8');
       const parsed = JSON.parse(raw);
@@ -366,9 +350,11 @@ function runRuntimeDeps({
       }
     }
   } else {
-    // Anchor resolution to the project root so it mirrors the context in which
-    // the framework scripts run (they free-ride on the consumer's node_modules).
-    const root = projectRoot ?? resolveProjectRoot();
+    // Anchor resolution to the consumer project root so it mirrors the context
+    // in which the framework scripts run (they free-ride on the consumer's
+    // node_modules). Under pnpm isolated-mode the consumer's node_modules are
+    // not reachable from inside node_modules/mandrel/; anchoring at process.cwd()
+    // finds them correctly.
     const req = createRequire(path.join(root, 'package.json'));
     for (const dep of required) {
       try {
@@ -467,68 +453,9 @@ function runAgentsMaterialized({ cwd, existsSync, resolvePackage } = {}) {
 // check: agents-drift
 // ---------------------------------------------------------------------------
 
-/**
- * Package name whose `.agents/` payload is the drift baseline. Mirrors
- * `lib/cli/sync.js#PACKAGE_NAME`.
- */
-const PACKAGE_NAME = 'mandrel';
-
-/**
- * Top-level directory name (relative to `.agents/`) reserved as the
- * sync-exempt local-additions zone (Story #3498, f-drift-local-zone).
- *
- * `.agents/local/` is consumer-owned space that `mandrel sync` never
- * materializes nor prunes, so it is excluded from the drift comparison —
- * a hand-authored file under `.agents/local/` is sanctioned, not drift.
- * Mirrors `lib/cli/sync.js#LOCAL_ZONE_DIR`.
- */
-const LOCAL_ZONE_DIR = 'local';
-
-/**
- * Default resolver: locate the installed `mandrel` package root by
- * resolving its `package.json` and returning the directory that contains it.
- * Mirrors `lib/cli/sync.js#defaultResolvePackageRoot` so the drift baseline
- * is exactly the payload that `mandrel sync` would copy.
- *
- * @param {string} fromDir - Directory to resolve from (the consumer project).
- * @returns {string} Absolute path to the package root.
- */
-function defaultResolvePackageRoot(fromDir) {
-  const requireFrom = createRequire(path.join(fromDir, 'noop.js'));
-  const pkgJsonPath = requireFrom.resolve(`${PACKAGE_NAME}/package.json`);
-  return path.dirname(pkgJsonPath);
-}
-
-/**
- * Recursively enumerate every regular file under `dir`, returning paths
- * relative to `dir` using OS separators. The top-level `local/` subtree is
- * skipped entirely — it is the consumer-owned local-additions zone and is
- * never part of the package payload (Story #3498). Mirrors
- * `lib/cli/sync.js#listFiles` so source enumeration matches the materializer.
- *
- * @param {string} dir - Absolute directory to walk.
- * @param {typeof fs} fsImpl
- * @param {string} [prefix] - Accumulated relative prefix (internal).
- * @returns {string[]} Relative file paths.
- */
-function listPayloadFiles(dir, fsImpl, prefix = '') {
-  const out = [];
-  for (const ent of fsImpl.readdirSync(dir, { withFileTypes: true })) {
-    // Scope the local-zone skip to the top-level `.agents/local/` only; a
-    // deeper directory that happens to be named `local` stays in scope.
-    if (prefix === '' && ent.name === LOCAL_ZONE_DIR && ent.isDirectory()) {
-      continue;
-    }
-    const rel = prefix ? path.join(prefix, ent.name) : ent.name;
-    const abs = path.join(dir, ent.name);
-    if (ent.isDirectory()) {
-      out.push(...listPayloadFiles(abs, fsImpl, rel));
-    } else {
-      out.push(rel);
-    }
-  }
-  return out;
-}
+// defaultResolvePackageRoot and listPayloadFiles (re-exported as `listFiles`
+// from sync.js) are imported from `lib/cli/sync.js` at the top of this file
+// (Story #4048 B3 — no mirror copies).
 
 /**
  * Compare the consumer's materialized `./.agents/<f>` bytes against the
@@ -630,39 +557,9 @@ function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
 // check: version-current
 // ---------------------------------------------------------------------------
 
-/**
- * Parse a dotted semver-ish string into a numeric tuple. Non-numeric or
- * missing segments coerce to 0 so a partial version still compares sanely.
- * Mirrors `lib/cli/update.js#parseVersion`.
- *
- * @param {string} version
- * @returns {[number, number, number]}
- */
-function parseVersionTuple(version) {
-  const [major, minor, patch] = String(version).split('.');
-  return [
-    Number.parseInt(major, 10) || 0,
-    Number.parseInt(minor, 10) || 0,
-    Number.parseInt(patch, 10) || 0,
-  ];
-}
-
-/**
- * Compare two version strings. Negative when `a < b`, zero when equal,
- * positive when `a > b`. Mirrors `lib/cli/update.js#compareVersions`.
- *
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-function compareSemver(a, b) {
-  const pa = parseVersionTuple(a);
-  const pb = parseVersionTuple(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
-  }
-  return 0;
-}
+// parseVersion and compareVersions are imported from `lib/cli/version-helpers.js`
+// at the top of this file (Story #4048 B3 — no mirror copies). `compareSemver`
+// is the registry-local alias for the imported `compareVersions`.
 
 /**
  * Resolve the installed `mandrel` version from this package's own
@@ -685,17 +582,16 @@ function defaultInstalledVersion(fsImpl) {
 const DEFAULT_VERSION_CACHE_FILENAME = 'version-check.json';
 
 /**
- * Default cache path: `<projectRoot>/temp/version-check.json`, the same daily
- * freshness cache that `lib/cli/version-check.js` reads and refreshes.
+ * Default cache path: `<consumerRoot>/temp/version-check.json`, anchored at
+ * `process.cwd()` (the consumer project root) so the cache file survives
+ * npm/pnpm reinstalls that may replace `node_modules/` entirely (Story #4046
+ * A2). Mirrors `commands-in-sync` / `agents-materialized` / `agents-drift`
+ * which all anchor at `process.cwd()`.
  *
  * @returns {string}
  */
 function defaultVersionCachePath() {
-  return path.join(
-    resolveProjectRoot(),
-    'temp',
-    DEFAULT_VERSION_CACHE_FILENAME,
-  );
+  return path.join(process.cwd(), 'temp', DEFAULT_VERSION_CACHE_FILENAME);
 }
 
 /**