mandrel 1.60.0 → 1.62.0

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

@@ -1,696 +0,0 @@
-// lib/cli/__tests__/update.test.js
-/**
- * Unit tests for lib/cli/update.js — the `mandrel update` orchestrator.
- *
- * Every test drives runUpdate through injectable seams (currentVersion,
- * resolveTargetVersion, npmUpdate, runSync, runMigrations, runDoctor,
- * surfaceChangelog, write, writeErr, exit). No real npm process, no real
- * filesystem I/O, and no real network call occur (testing-standards § Unit:
- * all external network / filesystem I/O MUST be mocked).
- *
- * Coverage contract (Story #3503 AC — non-major paths):
- *   - Module shape: runUpdate named export + default function export.
- *   - Happy path: a minor-ahead target drives the ordered steps
- *     npm-update → runSync → runMigrations → doctor and reports success only
- *     when the injected doctor result is all-pass.
- *   - --dry-run prints the planned target + step plan and invokes no
- *     effectful seam.
- *   - A failing doctor result downgrades the run to a non-zero exit even
- *     after the bump applied.
- *   - up-to-date short-circuit performs no steps.
- *
- * The major-gate AC has its own file: update-major.test.js.
- */
-
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-
-import { runInstallCommand } from '../../../.agents/scripts/lib/install-cmd-parser.js';
-import update, {
-  defaultNpmUpdate,
-  defaultVersionRunner,
-  detectPackageManager,
-  resolveInstallCmd,
-  runUpdate,
-} from '../update.js';
-
-/**
- * Build an in-memory `node:fs` fake whose `existsSync` reports the given
- * basenames as present — enough surface for `detectPackageManager` to probe
- * lockfiles without touching the real filesystem (testing-standards § Unit:
- * mock all filesystem I/O).
- *
- * @param {string[]} present - lockfile basenames to report as present.
- */
-function makeLockFs(present = []) {
-  const set = new Set(present);
-  return { existsSync: (p) => set.has(path.basename(String(p))) };
-}
-
-// ---------------------------------------------------------------------------
-// Capture + seam 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 the recording seam set for a happy-path run. `doctorOk` toggles the
- * injected doctor verdict so the all-pass / failure branches are both
- * exercised through the same harness.
- */
-function makeSeams({ target = '1.44.0', doctorOk = true } = {}) {
-  const calls = [];
-  return {
-    calls,
-    currentVersion: '1.43.0',
-    resolveTargetVersion: async () => {
-      calls.push('resolveTargetVersion');
-      return target;
-    },
-    npmUpdate: async (version) => {
-      calls.push(`npmUpdate:${version}`);
-    },
-    runSync: (_opts) => {
-      calls.push('runSync');
-      return { copied: 0, planned: 0, dryRun: false };
-    },
-    runMigrations: ({ fromVersion, toVersion }) => {
-      calls.push(`runMigrations:${fromVersion}->${toVersion}`);
-      return { applied: [], skipped: [] };
-    },
-    runDoctor: async () => {
-      calls.push('runDoctor');
-      return {
-        ok: doctorOk,
-        results: [
-          { name: 'node-version', ok: true },
-          { name: 'agents-materialized', ok: doctorOk },
-        ],
-      };
-    },
-    surfaceChangelog: async (version) => {
-      calls.push(`surfaceChangelog:${version}`);
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Module shape
-// ---------------------------------------------------------------------------
-
-describe('update module exports', () => {
-  it('exports runUpdate as a named export', () => {
-    assert.equal(typeof runUpdate, 'function');
-  });
-
-  it('exports a default function for bin/mandrel.js dispatch', () => {
-    assert.equal(typeof update, 'function');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — ordered cycle drives npm-update → runSync → runMigrations → doctor
-// ---------------------------------------------------------------------------
-
-describe('runUpdate — non-major happy path', () => {
-  it('drives the steps in order and reports success on an all-pass doctor', async () => {
-    const seams = makeSeams({ target: '1.44.0', doctorOk: true });
-    const cap = makeCapture();
-
-    const result = await runUpdate({
-      argv: [],
-      ...seams,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    // Ordered seam invocation: resolve → npm-update → sync → migrate → doctor.
-    assert.deepEqual(seams.calls, [
-      'resolveTargetVersion',
-      'npmUpdate:1.44.0',
-      'runSync',
-      'runMigrations:1.43.0->1.44.0',
-      'runDoctor',
-      'surfaceChangelog:1.44.0',
-    ]);
-    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('threads the resolved target into the npm-update and migration seams', async () => {
-    const seams = makeSeams({ target: '1.50.2' });
-    const cap = makeCapture();
-
-    await runUpdate({
-      argv: [],
-      ...seams,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.ok(seams.calls.includes('npmUpdate:1.50.2'));
-    assert.ok(seams.calls.includes('runMigrations:1.43.0->1.50.2'));
-  });
-
-  it('does not report success when doctor reports a failure', async () => {
-    const seams = makeSeams({ target: '1.44.0', doctorOk: false });
-    const cap = makeCapture();
-
-    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');
-    // The bump still applied — all four steps ran before doctor failed.
-    assert.deepEqual(result.stepsRun, [
-      'npm-update',
-      'runSync',
-      'runMigrations',
-      'doctor',
-    ]);
-    assert.equal(cap.exitCode, 1);
-    assert.match(cap.err.join(''), /doctor reported failures/);
-    assert.match(cap.err.join(''), /agents-materialized/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — --dry-run prints the plan and writes nothing / invokes no seam
-// ---------------------------------------------------------------------------
-
-describe('runUpdate — --dry-run', () => {
-  it('prints the planned target version and step plan', async () => {
-    const seams = makeSeams({ target: '1.44.0' });
-    const cap = makeCapture();
-
-    const result = await runUpdate({
-      argv: ['--dry-run'],
-      ...seams,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    const joined = cap.out.join('');
-    assert.match(joined, /1\.43\.0 → v1\.44\.0/);
-    assert.match(joined, /npm-update/);
-    assert.match(joined, /runSync/);
-    assert.match(joined, /runMigrations/);
-    assert.match(joined, /doctor/);
-    assert.match(joined, /Dry run: no files written/);
-    assert.equal(result.action, 'dry-run');
-    assert.equal(result.dryRun, true);
-  });
-
-  it('invokes no effectful seam and never calls exit', async () => {
-    const seams = makeSeams({ target: '1.44.0' });
-    const cap = makeCapture();
-
-    await runUpdate({
-      argv: ['--dry-run'],
-      ...seams,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    // resolveTargetVersion runs (the plan needs the target); nothing else.
-    assert.deepEqual(seams.calls, ['resolveTargetVersion']);
-    assert.equal(cap.exitCode, null);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// up-to-date short-circuit
-// ---------------------------------------------------------------------------
-
-describe('runUpdate — already on the newest version', () => {
-  it('performs no steps and reports up-to-date', async () => {
-    const seams = makeSeams({ target: '1.43.0' });
-    const cap = makeCapture();
-
-    const result = await runUpdate({
-      argv: [],
-      ...seams,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.equal(result.ok, true);
-    assert.equal(result.action, 'up-to-date');
-    assert.deepEqual(result.stepsRun, []);
-    assert.deepEqual(seams.calls, ['resolveTargetVersion']);
-    assert.match(cap.out.join(''), /Already up to date/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Seam-required guards
-// ---------------------------------------------------------------------------
-
-describe('runUpdate — missing required seams', () => {
-  it('throws when resolveTargetVersion is absent', async () => {
-    await assert.rejects(
-      () => runUpdate({ argv: [], currentVersion: '1.43.0' }),
-      /resolveTargetVersion seam is required/,
-    );
-  });
-
-  it('throws when npmUpdate is absent on a live (non-dry-run) bump', async () => {
-    await assert.rejects(
-      () =>
-        runUpdate({
-          argv: [],
-          currentVersion: '1.43.0',
-          resolveTargetVersion: async () => '1.44.0',
-          write: () => {},
-          writeErr: () => {},
-          exit: () => {},
-        }),
-      /npmUpdate seam is required/,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — win32 shell:true spawn shape (CVE-2024-27980) for the version probe
-// ---------------------------------------------------------------------------
-
-describe('defaultVersionRunner — win32 spawn shape', () => {
-  it('passes shell matching the platform to spawnSync (CVE-2024-27980)', () => {
-    const calls = [];
-    const fakeSpawn = (cmd, args, opts) => {
-      calls.push({ cmd, args, opts });
-      return { status: 0, stdout: '1.46.0\n', stderr: '' };
-    };
-
-    const version = defaultVersionRunner({ spawnSync: fakeSpawn });
-
-    assert.equal(version, '1.46.0');
-    assert.equal(calls.length, 1);
-    // Fixed argv vector — the package name is a constant, never operator text.
-    assert.equal(calls[0].cmd, 'npm');
-    assert.deepEqual(calls[0].args, ['view', 'mandrel', 'version']);
-    // The shell flag is win32-gated: true on Windows, false elsewhere.
-    assert.equal(calls[0].opts.shell, process.platform === 'win32');
-  });
-
-  it('throws a descriptive error when the probe spawn errors (ENOENT)', () => {
-    const fakeSpawn = () => ({
-      status: null,
-      stdout: '',
-      stderr: '',
-      error: new Error('spawnSync npm ENOENT'),
-    });
-
-    assert.throws(
-      () => defaultVersionRunner({ spawnSync: fakeSpawn }),
-      /failed to probe newest mandrel version: spawnSync npm ENOENT/,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — win32 shell:true spawn shape for the install (via runInstallCommand)
-// ---------------------------------------------------------------------------
-
-describe('defaultNpmUpdate — win32 install spawn shape', () => {
-  it('routes the install through runInstallCommand with the win32 shell flag', () => {
-    const calls = [];
-    const fakeSpawn = (bin, args, opts) => {
-      calls.push({ bin, args, opts });
-      return { status: 0, stderr: '' };
-    };
-    // Wire the real shared helper so the win32 shell handling under test is the
-    // production tokenizer/spawner, not a re-implementation.
-    const runInstall = (cmd, cwd) =>
-      runInstallCommand(cmd, cwd, { spawnSync: fakeSpawn });
-
-    defaultNpmUpdate('1.46.0', { runInstall, cwd: '/repo' });
-
-    assert.equal(calls.length, 1);
-    assert.equal(calls[0].bin, 'npm');
-    assert.deepEqual(calls[0].args, ['install', 'mandrel@1.46.0']);
-    assert.equal(calls[0].opts.cwd, '/repo');
-    assert.equal(calls[0].opts.shell, process.platform === 'win32');
-  });
-
-  it('throws when the install command exits non-zero', () => {
-    const runInstall = () => ({ status: 1, stderr: 'boom' });
-    assert.throws(
-      () => defaultNpmUpdate('1.46.0', { runInstall }),
-      /install command `npm install mandrel@1\.46\.0` exited 1: boom/,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — --install-cmd override (default vs overridden argv)
-// ---------------------------------------------------------------------------
-
-describe('resolveInstallCmd — default vs override', () => {
-  it('defaults to npm install mandrel@<target> when no override', () => {
-    assert.equal(resolveInstallCmd('1.46.0'), 'npm install mandrel@1.46.0');
-  });
-
-  it('uses the operator override verbatim when supplied', () => {
-    assert.equal(
-      resolveInstallCmd('1.46.0', 'pnpm add mandrel@latest'),
-      'pnpm add mandrel@latest',
-    );
-  });
-
-  it('falls back to the default when the override is blank', () => {
-    assert.equal(
-      resolveInstallCmd('1.46.0', '   '),
-      'npm install mandrel@1.46.0',
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC-1/AC-2 — package-manager detection from the project lockfile
-// ---------------------------------------------------------------------------
-
-describe('detectPackageManager — lockfile probe', () => {
-  it('detects pnpm and the workspace root from pnpm-lock.yaml + pnpm-workspace.yaml', () => {
-    const fs = makeLockFs(['pnpm-lock.yaml', 'pnpm-workspace.yaml']);
-    assert.deepEqual(detectPackageManager('/ws', fs), {
-      packageManager: 'pnpm',
-      workspaceRoot: true,
-    });
-  });
-
-  it('detects pnpm without -w when no pnpm-workspace.yaml is present', () => {
-    const fs = makeLockFs(['pnpm-lock.yaml']);
-    assert.deepEqual(detectPackageManager('/proj', fs), {
-      packageManager: 'pnpm',
-      workspaceRoot: false,
-    });
-  });
-
-  it('detects yarn from yarn.lock', () => {
-    const fs = makeLockFs(['yarn.lock']);
-    assert.deepEqual(detectPackageManager('/proj', fs), {
-      packageManager: 'yarn',
-      workspaceRoot: false,
-    });
-  });
-
-  it('falls back to npm when only package-lock.json (or nothing) is present', () => {
-    assert.deepEqual(
-      detectPackageManager('/proj', makeLockFs(['package-lock.json'])),
-      {
-        packageManager: 'npm',
-        workspaceRoot: false,
-      },
-    );
-    assert.deepEqual(detectPackageManager('/proj', makeLockFs([])), {
-      packageManager: 'npm',
-      workspaceRoot: false,
-    });
-  });
-
-  it('prefers pnpm over yarn when both lockfiles exist', () => {
-    const fs = makeLockFs(['pnpm-lock.yaml', 'yarn.lock']);
-    assert.equal(detectPackageManager('/proj', fs).packageManager, 'pnpm');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC-1/AC-2/AC-3 — resolveInstallCmd builds the PM-aware command
-// ---------------------------------------------------------------------------
-
-describe('resolveInstallCmd — package-manager aware', () => {
-  it('builds `pnpm add -D … -w` at a workspace root (AC-1)', () => {
-    assert.equal(
-      resolveInstallCmd('1.48.0', undefined, {
-        packageManager: 'pnpm',
-        workspaceRoot: true,
-      }),
-      'pnpm add -D mandrel@1.48.0 -w',
-    );
-  });
-
-  it('omits -w for a non-root pnpm project', () => {
-    assert.equal(
-      resolveInstallCmd('1.48.0', undefined, { packageManager: 'pnpm' }),
-      'pnpm add -D mandrel@1.48.0',
-    );
-  });
-
-  it('builds `yarn add -D …` for a yarn project (AC-2)', () => {
-    assert.equal(
-      resolveInstallCmd('1.48.0', undefined, { packageManager: 'yarn' }),
-      'yarn add -D mandrel@1.48.0',
-    );
-  });
-
-  it('substitutes a {target} placeholder in an override (AC-3)', () => {
-    assert.equal(
-      resolveInstallCmd('1.48.0', 'pnpm add -D mandrel@{target} -w'),
-      'pnpm add -D mandrel@1.48.0 -w',
-    );
-  });
-
-  it('uses a placeholder-free override verbatim', () => {
-    assert.equal(
-      resolveInstallCmd('1.48.0', 'pnpm add mandrel@latest'),
-      'pnpm add mandrel@latest',
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC-1/AC-2 — defaultNpmUpdate resolves the command from the detected PM
-// ---------------------------------------------------------------------------
-
-describe('defaultNpmUpdate — package-manager detection', () => {
-  it('runs `pnpm add -D … -w` in a pnpm workspace root (AC-1)', () => {
-    const fs = makeLockFs(['pnpm-lock.yaml', 'pnpm-workspace.yaml']);
-    const calls = [];
-    const runInstall = (cmd, cwd) => {
-      calls.push({ cmd, cwd });
-      return { status: 0, stderr: '' };
-    };
-
-    defaultNpmUpdate('1.48.0', { runInstall, cwd: '/ws', fs });
-
-    assert.equal(calls.length, 1);
-    assert.equal(calls[0].cmd, 'pnpm add -D mandrel@1.48.0 -w');
-    assert.equal(calls[0].cwd, '/ws');
-  });
-
-  it('runs `yarn add -D …` when yarn.lock is present (AC-2)', () => {
-    const fs = makeLockFs(['yarn.lock']);
-    const calls = [];
-    const runInstall = (cmd) => {
-      calls.push(cmd);
-      return { status: 0, stderr: '' };
-    };
-
-    defaultNpmUpdate('1.48.0', { runInstall, cwd: '/proj', fs });
-
-    assert.deepEqual(calls, ['yarn add -D mandrel@1.48.0']);
-  });
-
-  it('keeps `npm install …` unchanged for an npm repo (AC-2)', () => {
-    const fs = makeLockFs(['package-lock.json']);
-    const calls = [];
-    const runInstall = (cmd) => {
-      calls.push(cmd);
-      return { status: 0, stderr: '' };
-    };
-
-    defaultNpmUpdate('1.48.0', { runInstall, cwd: '/proj', fs });
-
-    assert.deepEqual(calls, ['npm install mandrel@1.48.0']);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC-4 — install failure surfaces a PM-specific node_modules repair hint
-// ---------------------------------------------------------------------------
-
-describe('defaultNpmUpdate — repair hint on failure (AC-4)', () => {
-  it('names the detected package manager when the install exits non-zero', () => {
-    const fs = makeLockFs(['pnpm-lock.yaml']);
-    const runInstall = () => ({ status: 1, stderr: 'boom' });
-
-    assert.throws(
-      () => defaultNpmUpdate('1.48.0', { runInstall, cwd: '/ws', fs }),
-      /exited 1: boom[\s\S]*run `pnpm install`/,
-    );
-  });
-
-  it('includes the repair hint when the install spawn throws', () => {
-    const fs = makeLockFs(['yarn.lock']);
-    const runInstall = () => {
-      throw new Error('ENOENT');
-    };
-
-    assert.throws(
-      () => defaultNpmUpdate('1.48.0', { runInstall, cwd: '/ws', fs }),
-      /failed to spawn: ENOENT[\s\S]*run `yarn install`/,
-    );
-  });
-});
-
-describe('runUpdate — --install-cmd flag threading', () => {
-  it('threads no installCmd into npmUpdate by default', async () => {
-    const seen = [];
-    const cap = makeCapture();
-    await runUpdate({
-      argv: [],
-      currentVersion: '1.43.0',
-      resolveTargetVersion: async () => '1.44.0',
-      npmUpdate: async (_target, opts) => {
-        seen.push(opts);
-      },
-      runSync: () => ({}),
-      runMigrations: () => ({}),
-      runDoctor: async () => ({ ok: true, results: [] }),
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(seen.length, 1);
-    assert.equal(seen[0].installCmd, undefined);
-  });
-
-  it('threads the --install-cmd value into npmUpdate', async () => {
-    const seen = [];
-    const cap = makeCapture();
-    await runUpdate({
-      argv: ['--install-cmd', 'pnpm add mandrel@1.44.0'],
-      currentVersion: '1.43.0',
-      resolveTargetVersion: async () => '1.44.0',
-      npmUpdate: async (_target, opts) => {
-        seen.push(opts);
-      },
-      runSync: () => ({}),
-      runMigrations: () => ({}),
-      runDoctor: async () => ({ ok: true, results: [] }),
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(seen.length, 1);
-    assert.equal(seen[0].installCmd, 'pnpm add mandrel@1.44.0');
-  });
-
-  it('accepts the --install-cmd=<value> form', async () => {
-    const seen = [];
-    const cap = makeCapture();
-    await runUpdate({
-      argv: ['--install-cmd=yarn up mandrel@1.44.0'],
-      currentVersion: '1.43.0',
-      resolveTargetVersion: async () => '1.44.0',
-      npmUpdate: async (_target, opts) => {
-        seen.push(opts);
-      },
-      runSync: () => ({}),
-      runMigrations: () => ({}),
-      runDoctor: async () => ({ ok: true, results: [] }),
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(seen[0].installCmd, 'yarn up mandrel@1.44.0');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — default export wiring threads installCmd + runInstall (no real I/O)
-// ---------------------------------------------------------------------------
-
-describe('update default export — install routing', () => {
-  // An in-memory fs that reports "no cache present" so isStale always invokes
-  // the injected versionRunner and the cache refresh write goes nowhere real.
-  function makeMemoryFs() {
-    return {
-      readFileSync: () => {
-        const err = new Error('ENOENT');
-        err.code = 'ENOENT';
-        throw err;
-      },
-      writeFileSync: () => {},
-      mkdirSync: () => {},
-      existsSync: () => false,
-    };
-  }
-
-  it('runs the overridden install command through the injected runInstall seam', async () => {
-    const installs = [];
-    await update(['--install-cmd', 'pnpm add mandrel@1.44.0'], {
-      currentVersion: '1.43.0',
-      fs: makeMemoryFs(),
-      versionRunner: () => '1.44.0',
-      runInstall: (cmd, cwd) => {
-        installs.push({ cmd, cwd });
-        return { status: 0, stderr: '' };
-      },
-      runSync: () => ({}),
-      runMigrations: () => ({}),
-      runDoctor: async () => ({ ok: true, results: [] }),
-      write: () => {},
-      writeErr: () => {},
-      exit: () => {},
-    });
-    assert.equal(installs.length, 1);
-    assert.equal(installs[0].cmd, 'pnpm add mandrel@1.44.0');
-  });
-
-  it('runs the default npm install command when no override is given', async () => {
-    const installs = [];
-    await update([], {
-      currentVersion: '1.43.0',
-      fs: makeMemoryFs(),
-      versionRunner: () => '1.44.0',
-      runInstall: (cmd) => {
-        installs.push(cmd);
-        return { status: 0, stderr: '' };
-      },
-      runSync: () => ({}),
-      runMigrations: () => ({}),
-      runDoctor: async () => ({ ok: true, results: [] }),
-      write: () => {},
-      writeErr: () => {},
-      exit: () => {},
-    });
-    assert.deepEqual(installs, ['npm install mandrel@1.44.0']);
-  });
-});