mandrel 1.59.0 → 1.60.0

package/lib/cli/__tests__/update-reexec.test.js

@@ -0,0 +1,513 @@
+// lib/cli/__tests__/update-reexec.test.js
+/**
+ * Unit tests for the Story #4034 re-exec fix in lib/cli/update.js.
+ *
+ * After `npm-update` lands the new version, the post-install phases
+ * (sync, migrate, doctor) MUST run from the newly-installed binary rather
+ * than in the still-running old process. The `spawnPhase` seam is the
+ * injectable boundary that makes this fully testable without a real npm
+ * install.
+ *
+ * Coverage contract (Story #4034):
+ *   - When `spawnPhase` is injected, post-install phases run through it
+ *     (re-exec path) instead of the in-process runSync/runMigrations/runDoctor.
+ *   - Phases are spawned in the correct order: sync → migrate → doctor.
+ *   - `mandrel migrate` receives `--from <current>` and `--to <target>`.
+ *   - The new bin path passed to `spawnPhase` is resolved from the cwd's
+ *     `node_modules/.bin/mandrel` (the production path).
+ *   - A failing sync phase throws and exits non-zero (never silently continues).
+ *   - A failing migrate phase throws and exits non-zero.
+ *   - A non-zero doctor phase maps to `action: 'doctor-failed'` + exit 1.
+ *   - `resolveNewBinPath` returns the correct platform path.
+ *   - `defaultSpawnPhase` routes stdout/stderr through the write sinks and
+ *     throws on spawn error.
+ *
+ * Tier: unit (testing-standards § Unit). All seams — including `spawnPhase`
+ * — are injected; no real child process, filesystem, or network call occurs.
+ *
+ * Security (security-baseline § 5 — Data Leakage & Logging): fixtures carry
+ * only version strings and paths; no tokens, credentials, or env values.
+ */
+
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+
+import { defaultSpawnPhase, resolveNewBinPath, runUpdate } from '../update.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Capture stdout/stderr writes and the exit code. */
+function makeCapture() {
+  const out = [];
+  const err = [];
+  let exitCode = null;
+  return {
+    out,
+    err,
+    get exitCode() {
+      return exitCode;
+    },
+    write: (s) => out.push(s),
+    writeErr: (s) => err.push(s),
+    exit: (code) => {
+      exitCode = code;
+    },
+  };
+}
+
+/**
+ * Build a minimal seam set for a minor-ahead non-dry-run run.
+ * `spawnPhase` replaces the in-process runSync/runMigrations/runDoctor.
+ */
+function makeReExecSeams({
+  target = '1.44.0',
+  current = '1.43.0',
+  spawnResults = {},
+} = {}) {
+  const calls = [];
+  return {
+    calls,
+    currentVersion: current,
+    resolveTargetVersion: async () => {
+      calls.push('resolve');
+      return target;
+    },
+    npmUpdate: async (version) => {
+      calls.push(`npm-update:${version}`);
+    },
+    spawnPhase: async (phase, args, opts) => {
+      calls.push({ phase, args, binPath: opts.binPath, cwd: opts.cwd });
+      const result = spawnResults[phase] ?? {
+        ok: true,
+        stdout: '',
+        stderr: '',
+      };
+      return result;
+    },
+    surfaceChangelog: async (version) => {
+      calls.push(`changelog:${version}`);
+    },
+    cwd: () => '/fake/consumer',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AC: spawnPhase is invoked for post-install phases when injected
+// ---------------------------------------------------------------------------
+
+describe('runUpdate — re-exec path via spawnPhase', () => {
+  it('routes post-install phases through spawnPhase, not in-process seams', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({ target: '1.44.0', current: '1.43.0' });
+
+    const result = await runUpdate({
+      argv: [],
+      ...seams,
+      write: cap.write,
+      writeErr: cap.writeErr,
+      exit: cap.exit,
+    });
+
+    // npm-update ran, then all three phases were spawned via spawnPhase.
+    const phaseNames = seams.calls
+      .filter((c) => typeof c === 'object' && c.phase)
+      .map((c) => c.phase);
+    assert.deepEqual(phaseNames, ['sync', 'migrate', 'doctor']);
+
+    // The in-process runSync/runMigrations/runDoctor were NOT invoked directly
+    // (there are no 'runSync' / 'runMigrations' / 'runDoctor' string entries).
+    assert.ok(
+      !seams.calls.some(
+        (c) => c === 'runSync' || c === 'runMigrations' || c === 'runDoctor',
+      ),
+      'in-process seams must NOT be called when spawnPhase is injected',
+    );
+
+    assert.equal(result.ok, true);
+    assert.equal(result.action, 'updated');
+    assert.deepEqual(result.stepsRun, [
+      'npm-update',
+      'runSync',
+      'runMigrations',
+      'doctor',
+    ]);
+    assert.equal(cap.exitCode, null);
+  });
+
+  it('passes correct ordered argv to each phase: sync→migrate(--from,--to)→doctor', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({ target: '1.50.0', current: '1.43.0' });
+
+    await runUpdate({
+      argv: [],
+      ...seams,
+      write: cap.write,
+      writeErr: cap.writeErr,
+      exit: cap.exit,
+    });
+
+    const phases = seams.calls.filter((c) => typeof c === 'object' && c.phase);
+    assert.equal(phases.length, 3);
+
+    assert.equal(phases[0].phase, 'sync');
+    assert.deepEqual(phases[0].args, []);
+
+    assert.equal(phases[1].phase, 'migrate');
+    assert.deepEqual(phases[1].args, ['--from', '1.43.0', '--to', '1.50.0']);
+
+    assert.equal(phases[2].phase, 'doctor');
+    assert.deepEqual(phases[2].args, []);
+  });
+
+  it('resolves new bin path from cwd/node_modules/.bin/mandrel', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({ target: '1.44.0', current: '1.43.0' });
+
+    await runUpdate({
+      argv: [],
+      ...seams,
+      write: cap.write,
+      writeErr: cap.writeErr,
+      exit: cap.exit,
+    });
+
+    const phases = seams.calls.filter((c) => typeof c === 'object' && c.phase);
+    const expectedBin = resolveNewBinPath('/fake/consumer');
+    for (const p of phases) {
+      assert.equal(
+        p.binPath,
+        expectedBin,
+        `phase '${p.phase}' binPath should resolve to new bin`,
+      );
+      assert.equal(p.cwd, '/fake/consumer');
+    }
+  });
+
+  it('throws when sync phase exits non-zero (never silently materialises stale payload)', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({
+      target: '1.44.0',
+      current: '1.43.0',
+      spawnResults: { sync: { ok: false, stdout: '', stderr: 'sync failed' } },
+    });
+
+    await assert.rejects(
+      () =>
+        runUpdate({
+          argv: [],
+          ...seams,
+          write: cap.write,
+          writeErr: cap.writeErr,
+          exit: cap.exit,
+        }),
+      /mandrel sync.*new binary exited non-zero/,
+    );
+
+    // migrate and doctor must NOT have been called after sync failure.
+    const phases = seams.calls.filter((c) => typeof c === 'object' && c.phase);
+    assert.deepEqual(
+      phases.map((p) => p.phase),
+      ['sync'],
+    );
+  });
+
+  it('throws when migrate phase exits non-zero', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({
+      target: '1.44.0',
+      current: '1.43.0',
+      spawnResults: {
+        migrate: { ok: false, stdout: '', stderr: 'migrate failed' },
+      },
+    });
+
+    await assert.rejects(
+      () =>
+        runUpdate({
+          argv: [],
+          ...seams,
+          write: cap.write,
+          writeErr: cap.writeErr,
+          exit: cap.exit,
+        }),
+      /mandrel migrate.*new binary exited non-zero/,
+    );
+
+    // doctor must NOT have been called after migrate failure.
+    const phases = seams.calls.filter((c) => typeof c === 'object' && c.phase);
+    assert.deepEqual(
+      phases.map((p) => p.phase),
+      ['sync', 'migrate'],
+    );
+  });
+
+  it('maps non-zero doctor to doctor-failed + exit 1', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({
+      target: '1.44.0',
+      current: '1.43.0',
+      spawnResults: {
+        doctor: {
+          ok: false,
+          stdout: '',
+          stderr: 'agents-drift: drift detected',
+        },
+      },
+    });
+
+    const result = await runUpdate({
+      argv: [],
+      ...seams,
+      write: cap.write,
+      writeErr: cap.writeErr,
+      exit: cap.exit,
+    });
+
+    assert.equal(result.ok, false);
+    assert.equal(result.action, 'doctor-failed');
+    assert.equal(cap.exitCode, 1);
+    assert.match(cap.err.join(''), /doctor reported failures/);
+  });
+
+  it('still runs the changelog seam after a successful re-exec cycle', async () => {
+    const cap = makeCapture();
+    const seams = makeReExecSeams({ target: '1.44.0', current: '1.43.0' });
+
+    await runUpdate({
+      argv: [],
+      ...seams,
+      write: cap.write,
+      writeErr: cap.writeErr,
+      exit: cap.exit,
+    });
+
+    assert.ok(
+      seams.calls.includes('changelog:1.44.0'),
+      'changelog seam must fire after successful re-exec phases',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC: in-process seams still work when spawnPhase is NOT injected
+// (backward compatibility — pre-Story-#4034 tests must stay green)
+// ---------------------------------------------------------------------------
+
+describe('runUpdate — in-process backward-compat path (no spawnPhase)', () => {
+  it('uses injected runSync/runMigrations/runDoctor when spawnPhase is absent', async () => {
+    const calls = [];
+    const cap = makeCapture();
+
+    const result = await runUpdate({
+      argv: [],
+      currentVersion: '1.43.0',
+      resolveTargetVersion: async () => '1.44.0',
+      npmUpdate: async (v) => {
+        calls.push(`npm-update:${v}`);
+      },
+      runSync: (_opts) => {
+        calls.push('runSync');
+        return {};
+      },
+      runMigrations: ({ fromVersion, toVersion }) => {
+        calls.push(`runMigrations:${fromVersion}->${toVersion}`);
+        return { applied: [], skipped: [] };
+      },
+      runDoctor: async () => {
+        calls.push('runDoctor');
+        return { ok: true, results: [] };
+      },
+      surfaceChangelog: async (v) => {
+        calls.push(`changelog:${v}`);
+      },
+      write: cap.write,
+      writeErr: cap.writeErr,
+      exit: cap.exit,
+    });
+
+    assert.deepEqual(calls, [
+      'npm-update:1.44.0',
+      'runSync',
+      'runMigrations:1.43.0->1.44.0',
+      'runDoctor',
+      'changelog:1.44.0',
+    ]);
+    assert.equal(result.ok, true);
+    assert.equal(result.action, 'updated');
+    assert.equal(cap.exitCode, null);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC: resolveNewBinPath returns the correct platform path
+// ---------------------------------------------------------------------------
+
+describe('resolveNewBinPath', () => {
+  it('returns node_modules/.bin/mandrel on POSIX', () => {
+    // We cannot force-test win32 on non-win32 but we can verify the POSIX shape.
+    if (process.platform !== 'win32') {
+      const p = resolveNewBinPath('/some/project');
+      assert.equal(
+        p,
+        path.join('/some', 'project', 'node_modules', '.bin', 'mandrel'),
+      );
+    }
+  });
+
+  it('returns a path that ends with mandrel or mandrel.cmd', () => {
+    const p = resolveNewBinPath('/project');
+    assert.ok(
+      p.endsWith('mandrel') || p.endsWith('mandrel.cmd'),
+      `expected path to end with mandrel[.cmd], got: ${p}`,
+    );
+  });
+
+  it('contains node_modules/.bin in the path', () => {
+    const p = resolveNewBinPath('/project');
+    assert.ok(
+      p.includes(path.join('node_modules', '.bin')),
+      `expected node_modules/.bin in path, got: ${p}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC: defaultSpawnPhase routes output through write sinks and throws on error
+// ---------------------------------------------------------------------------
+
+describe('defaultSpawnPhase — output routing and error handling', () => {
+  it('routes child stdout through the write sink', () => {
+    const out = [];
+    const err = [];
+    const fakeSpawn = (_bin, _args, _opts) => ({
+      status: 0,
+      stdout: 'Materialized 832 files\n',
+      stderr: '',
+      error: undefined,
+    });
+
+    defaultSpawnPhase('sync', [], {
+      binPath: '/fake/bin/mandrel',
+      cwd: '/project',
+      write: (s) => out.push(s),
+      writeErr: (s) => err.push(s),
+      spawnFn: fakeSpawn,
+    });
+
+    assert.deepEqual(out, ['Materialized 832 files\n']);
+    assert.deepEqual(err, []);
+  });
+
+  it('routes child stderr through the writeErr sink', () => {
+    const out = [];
+    const err = [];
+    const fakeSpawn = () => ({
+      status: 0,
+      stdout: '',
+      stderr: 'warning: something\n',
+      error: undefined,
+    });
+
+    defaultSpawnPhase('doctor', [], {
+      binPath: '/fake/bin/mandrel',
+      cwd: '/project',
+      write: (s) => out.push(s),
+      writeErr: (s) => err.push(s),
+      spawnFn: fakeSpawn,
+    });
+
+    assert.deepEqual(out, []);
+    assert.deepEqual(err, ['warning: something\n']);
+  });
+
+  it('returns ok:false when child exits non-zero', () => {
+    const fakeSpawn = () => ({
+      status: 1,
+      stdout: '',
+      stderr: 'drift detected',
+      error: undefined,
+    });
+
+    const result = defaultSpawnPhase('doctor', [], {
+      binPath: '/fake/bin/mandrel',
+      cwd: '/project',
+      write: () => {},
+      writeErr: () => {},
+      spawnFn: fakeSpawn,
+    });
+
+    assert.equal(result.ok, false);
+  });
+
+  it('returns ok:true when child exits 0', () => {
+    const fakeSpawn = () => ({
+      status: 0,
+      stdout: 'all good',
+      stderr: '',
+      error: undefined,
+    });
+
+    const result = defaultSpawnPhase('sync', [], {
+      binPath: '/fake/bin/mandrel',
+      cwd: '/project',
+      write: () => {},
+      writeErr: () => {},
+      spawnFn: fakeSpawn,
+    });
+
+    assert.equal(result.ok, true);
+  });
+
+  it('throws a descriptive error when the spawn itself fails (ENOENT)', () => {
+    const fakeSpawn = () => ({
+      status: null,
+      stdout: '',
+      stderr: '',
+      error: new Error('spawnSync mandrel ENOENT'),
+    });
+
+    assert.throws(
+      () =>
+        defaultSpawnPhase('sync', [], {
+          binPath: '/fake/bin/mandrel',
+          cwd: '/project',
+          write: () => {},
+          writeErr: () => {},
+          spawnFn: fakeSpawn,
+        }),
+      /failed to spawn.*mandrel sync.*new binary.*ENOENT/,
+    );
+  });
+
+  it('passes the correct argv vector to the spawn function', () => {
+    const calls = [];
+    const fakeSpawn = (bin, args, opts) => {
+      calls.push({ bin, args, opts });
+      return { status: 0, stdout: '', stderr: '', error: undefined };
+    };
+
+    defaultSpawnPhase('migrate', ['--from', '1.43.0', '--to', '1.44.0'], {
+      binPath: '/nm/.bin/mandrel',
+      cwd: '/proj',
+      write: () => {},
+      writeErr: () => {},
+      spawnFn: fakeSpawn,
+    });
+
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0].bin, '/nm/.bin/mandrel');
+    assert.deepEqual(calls[0].args, [
+      'migrate',
+      '--from',
+      '1.43.0',
+      '--to',
+      '1.44.0',
+    ]);
+    assert.equal(calls[0].opts.cwd, '/proj');
+    // Shell flag is win32-gated: true only on Windows.
+    assert.equal(calls[0].opts.shell, process.platform === 'win32');
+  });
+});

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`.
@@ -92,12 +95,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,7 +151,7 @@ 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,
  * }} [opts]
@@ -224,18 +226,18 @@ 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,
@@ -249,7 +251,7 @@ export function planInit({
     };
   }
 
-  // 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,23 +286,23 @@ 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';
 }
 
 /**