mandrel 1.59.0 → 1.60.0

package/lib/cli/update.js

@@ -25,11 +25,37 @@
  *      the resolved version so an override can still consume the auto-probed
  *      newest. The registry probe in step 1 always stays on `npm view` (a
  *      PM-agnostic registry query).
- *   5. runSync        — re-materialize ./.agents/ from the new payload
- *   6. runMigrations  — apply version-keyed steps for the crossed range
- *   7. doctor         — run the check registry; success ⇒ all checks pass
+ *   5. runSync        — re-materialize ./.agents/ **from the newly-installed
+ *      binary** so the materialized payload is always the target version's.
+ *   6. runMigrations  — apply version-keyed steps for the crossed range,
+ *      **from the newly-installed binary**.
+ *   7. doctor         — run the check registry **from the newly-installed
+ *      binary** so `agents-drift` is never a false-green against stale payload.
  *   8. surface the changelog for the target version
  *
+ * ## Re-exec of post-install phases (Story #4034)
+ *
+ * Steps 5–7 execute as **child processes spawned from the newly-installed
+ * binary** (`<cwd>/node_modules/.bin/mandrel`) rather than in the running
+ * process. Node cannot hot-swap a `require`d module mid-process, so without
+ * re-exec, the still-running old binary's `runSync`/`runMigrations`/`runDoctor`
+ * code would materialise the old payload even though the package on disk has
+ * already been updated. This produced the silent stale-`.agents/`
+ * materialization and `doctor` false-green observed in the v1.58.0 → v1.59.0
+ * consumer upgrade.
+ *
+ * The orchestration (progress messages, step tracking, changelog surface, exit
+ * code) stays in the parent process; only the version-sensitive phases run from
+ * the new bin. The `spawnPhase` seam makes the child-process boundary fully
+ * injectable so tests can verify the re-exec path without a real npm install.
+ *
+ * Backward compatibility: when `runSync`, `runMigrations`, or `runDoctor`
+ * are explicitly injected (the historical test-seam pattern) and `spawnPhase`
+ * is NOT injected, the in-process seams are used unchanged (old tests stay
+ * green). When `spawnPhase` IS injected, it takes priority over the in-process
+ * seams for the live phases — so new tests targeting the re-exec boundary can
+ * inject `spawnPhase` without touching the old seam interface.
+ *
  * ## No git mutation
  *
  * The npm dependency bump rewrites `package.json` / `package-lock.json` in the
@@ -55,6 +81,20 @@
  *   - **with `--major`**: apply the major target and print the runbook inline.
  * Routine minor/patch bumps within the 1.x line are never gated.
  *
+ * ## Changelog surface
+ *
+ * `defaultSurfaceChangelog` prints the `docs/CHANGELOG.md` section(s) for the
+ * applied range `(current, target]`. It resolves the file against the target
+ * version's install directory (the freshly bumped `node_modules/mandrel/`),
+ * where the changelog is now included in the published tarball
+ * (`docs/CHANGELOG.md` in the `files` allowlist — Story #4035).
+ *
+ * When the packaged file is absent (e.g. an older installed version predating
+ * Story #4035), the seam attempts a one-shot HTTP GET of the raw file from
+ * GitHub via the injectable `fetchChangelog` seam. If that fetch also fails,
+ * the seam degrades gracefully — never throwing — and emits an actionable
+ * message directing the operator to the GitHub Releases page.
+ *
  * ## Injectable seams (used by lib/cli/__tests__/update*.test.js)
  *
  *   - `argv`                — subcommand args (after `mandrel update`)
@@ -62,12 +102,24 @@
  *   - `resolveTargetVersion`— async, returns the newest published version
  *   - `npmUpdate`           — async, performs the dependency bump (no git);
  *                             receives `(target, { installCmd })`
- *   - `runSync`             — re-materializes ./.agents/ (lib/cli/sync.js)
- *   - `runMigrations`       — version-keyed migration runner (lib/migrations)
- *   - `runDoctor`           — async, returns { ok, results } from the registry
+ *   - `spawnPhase`          — async, spawns a post-install phase from the new
+ *                             binary; receives `(phase, args, { binPath, cwd })`
+ *                             and returns `{ ok, stdout, stderr }`. When
+ *                             injected, it takes priority over `runSync`,
+ *                             `runMigrations`, and `runDoctor` for the live
+ *                             phases. See § Re-exec of post-install phases.
+ *   - `runSync`             — re-materializes ./.agents/ (lib/cli/sync.js).
+ *                             Used when `spawnPhase` is NOT injected (backward
+ *                             compat for tests that pre-date Story #4034).
+ *   - `runMigrations`       — version-keyed migration runner (lib/migrations).
+ *                             Used when `spawnPhase` is NOT injected.
+ *   - `runDoctor`           — async, returns { ok, results } from the registry.
+ *                             Used when `spawnPhase` is NOT injected.
  *   - `surfaceChangelog`    — emits the target changelog section
  *   - `write` / `writeErr`  — stdout / stderr sinks
  *   - `exit`                — process.exit replacement
+ *   - `cwd`                 — process.cwd() replacement (used to resolve the
+ *                             new binary path when `spawnPhase` is absent)
  *
  * Security (security-baseline § 5 — Data Leakage & Logging): logs only version
  * strings, step names, and the runbook path. No tokens, credentials, or env
@@ -86,10 +138,17 @@
  * the install argv is a tokenized list whose only variable segment is a
  * resolved semver string — see `lib/install-cmd-parser.js` for the shared
  * tokenize-and-spawn rationale this module reuses (no duplicated workaround).
+ *
+ * The `spawnPhase` default (Story #4034) similarly uses `shell: true` only on
+ * Windows: the new binary resolves from `node_modules/.bin/mandrel` (a fixed,
+ * non-operator-supplied path) and the per-phase argv vector is a constant
+ * fixed list (e.g. `['sync']`, `['migrate', '--from', v, '--to', v]`,
+ * `['doctor']`) with no injection risk regardless of the shell flag.
  */
 
 import { spawnSync } from 'node:child_process';
 import nodeFs from 'node:fs';
+import nodeHttps from 'node:https';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -105,6 +164,19 @@ const RUNBOOK_PATH = 'docs/upgrade-major.md';
 /** The published package whose newest version `mandrel update` advances to. */
 const PACKAGE_NAME = 'mandrel';
 
+/**
+ * GitHub raw-file base URL for fetching `docs/CHANGELOG.md` when the packaged
+ * file is absent (Story #4035 — GitHub fallback). Resolves to the tagged
+ * release, e.g. `.../mandrel-v1.59.0/docs/CHANGELOG.md`.
+ */
+const GITHUB_RAW_BASE = 'https://raw.githubusercontent.com/dsj1984/mandrel/';
+
+/**
+ * Human-readable GitHub Releases page — surfaced in the actionable fallback
+ * message when neither the packaged file nor the GitHub fetch succeeds.
+ */
+const GITHUB_RELEASES_URL = 'https://github.com/dsj1984/mandrel/releases';
+
 /** Default freshness-cache filename — mirrors version-check.js. */
 const DEFAULT_CACHE_FILENAME = 'version-check.json';
 
@@ -408,6 +480,72 @@ export function defaultNpmUpdate(
   }
 }
 
+/**
+ * Fetch `docs/CHANGELOG.md` for a specific mandrel tag from GitHub's raw
+ * content endpoint. This is the fallback when the packaged file is absent
+ * (e.g. an older install predating Story #4035 which added the file to the
+ * npm `files` allowlist).
+ *
+ * Injectable via the `fetchChangelog` seam so tests can verify the fallback
+ * path without issuing real network calls.
+ *
+ * The tag shape follows the `mandrel-vX.Y.Z` namespace (namespaced at
+ * `mandrel-v1.44.0`; bare `vX.Y.Z` for earlier releases). This function
+ * tries the namespaced tag first, then the bare-tag form, so it covers both
+ * tag series without forcing callers to know the boundary.
+ *
+ * Security (security-baseline § Transport & Headers): the URL is constructed
+ * from a constant base and a semver string — no user input, no shell
+ * interpolation. The GET is a read-only fetch with no credentials.
+ *
+ * @param {string} version - The target semver string (e.g. `"1.59.0"`).
+ * @param {{
+ *   https?: typeof nodeHttps,
+ * }} [deps]
+ * @returns {Promise<string>} The raw changelog text.
+ * @throws {Error} When both tag forms return a non-2xx response or the request
+ *   errors out — the caller handles this gracefully.
+ */
+export async function fetchChangelogFromGitHub(
+  version,
+  { https: httpsImpl = nodeHttps } = {},
+) {
+  const tags = [`mandrel-v${version}`, `v${version}`];
+
+  /**
+   * @param {string} url
+   * @returns {Promise<{ status: number, body: string }>}
+   */
+  const httpGet = (url) =>
+    new Promise((resolve, reject) => {
+      httpsImpl
+        .get(url, (res) => {
+          const chunks = [];
+          res.on('data', (d) => chunks.push(d));
+          res.on('end', () =>
+            resolve({
+              status: res.statusCode ?? 0,
+              body: Buffer.concat(chunks).toString('utf8'),
+            }),
+          );
+        })
+        .on('error', reject);
+    });
+
+  for (const tag of tags) {
+    const url = `${GITHUB_RAW_BASE}${tag}/docs/CHANGELOG.md`;
+    // eslint-disable-next-line no-await-in-loop
+    const { status, body } = await httpGet(url);
+    if (status >= 200 && status < 300) {
+      return body;
+    }
+  }
+
+  throw new Error(
+    `mandrel update: GitHub fetch for mandrel v${version} docs/CHANGELOG.md returned non-2xx for all tag forms (tried: ${tags.join(', ')})`,
+  );
+}
+
 /**
  * Default `surfaceChangelog` seam: print the `docs/CHANGELOG.md` section(s)
  * covering the applied version range `(current, target]`. The changelog is
@@ -415,38 +553,61 @@ export function defaultNpmUpdate(
  * prints every section whose version is newer than `current` and no newer than
  * `target`.
  *
- * Degrades gracefully (warns, never throws) when the file is absent or no
- * matching section is found — surfacing the changelog is best-effort and must
- * never fail an otherwise-successful upgrade.
+ * Resolution order (Story #4035):
+ *   1. Read `docs/CHANGELOG.md` from the target version's install directory
+ *      (`node_modules/mandrel/docs/CHANGELOG.md` — now in the published
+ *      tarball since `package.json` lists `docs/CHANGELOG.md` in `files`).
+ *   2. When the packaged file is absent (older install), fetch it from GitHub
+ *      via the injectable `fetchChangelog` seam.
+ *   3. When both sources fail, emit an actionable warning with a link to the
+ *      GitHub Releases page — never a bare "not found … skipping".
+ *
+ * Degrades gracefully (warns, never throws) — surfacing the changelog is
+ * best-effort and must never fail an otherwise-successful upgrade.
  *
  * @param {string} target - The applied target version.
  * @param {{
  *   current?: string,
  *   changelogPath?: string,
  *   fs?: typeof nodeFs,
+ *   fetchChangelog?: (version: string) => Promise<string>,
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  * }} [opts]
- * @returns {void}
+ * @returns {Promise<void>}
  */
-function defaultSurfaceChangelog(
+async function defaultSurfaceChangelog(
   target,
   {
     current,
     changelogPath = path.join(resolveProjectRoot(), 'docs', 'CHANGELOG.md'),
     fs = nodeFs,
+    fetchChangelog = fetchChangelogFromGitHub,
     write = (s) => process.stdout.write(s),
     writeErr = (s) => process.stderr.write(s),
   } = {},
 ) {
   let raw;
+
+  // 1. Try the packaged file (present in installs since Story #4035).
   try {
     raw = fs.readFileSync(changelogPath, 'utf8');
   } catch {
-    writeErr(
-      `mandrel update: changelog not found at ${changelogPath} — skipping changelog surface.\n`,
-    );
-    return;
+    // File absent — fall through to GitHub fetch.
+  }
+
+  // 2. Packaged file absent: attempt a GitHub fetch for the target tag.
+  if (raw === undefined) {
+    try {
+      raw = await fetchChangelog(target);
+    } catch {
+      // Both sources unavailable — emit an actionable message and return.
+      writeErr(
+        `mandrel update: changelog not available for v${target} — ` +
+          `view the release notes at ${GITHUB_RELEASES_URL}\n`,
+      );
+      return;
+    }
   }
 
   const sections = parseChangelogSections(raw);
@@ -458,7 +619,8 @@ function defaultSurfaceChangelog(
 
   if (relevant.length === 0) {
     writeErr(
-      `mandrel update: no CHANGELOG section found for v${target} — skipping changelog surface.\n`,
+      `mandrel update: no CHANGELOG section found for v${target} — ` +
+        `view the release notes at ${GITHUB_RELEASES_URL}\n`,
     );
     return;
   }
@@ -509,6 +671,8 @@ function parseChangelogSections(raw) {
  * report whether all passed. Mirrors lib/cli/doctor.js's pass accounting
  * without the formatted report (the orchestrator owns its own output).
  *
+ * This is used only when `spawnPhase` is NOT injected (backward-compat path).
+ *
  * @param {{ checks?: typeof registry }} [opts]
  * @returns {Promise<{ ok: boolean, results: Array<{ name: string, ok: boolean }> }>}
  */
@@ -521,6 +685,69 @@ async function defaultRunDoctor({ checks = registry } = {}) {
   return { ok: results.every((r) => r.ok), results };
 }
 
+/**
+ * Resolve the path to the `mandrel` binary inside `node_modules/.bin/` for the
+ * given project root. On Windows the binary is a `.cmd` shim; on POSIX it is a
+ * plain executable. The resolved path is used as the target for the post-install
+ * phase re-exec (Story #4034).
+ *
+ * @param {string} projectRoot - Absolute path to the consumer project.
+ * @returns {string} Absolute path to the new binary.
+ */
+export function resolveNewBinPath(projectRoot) {
+  const binName = process.platform === 'win32' ? 'mandrel.cmd' : 'mandrel';
+  return path.join(projectRoot, 'node_modules', '.bin', binName);
+}
+
+/**
+ * Default `spawnPhase` seam (Story #4034): spawn a post-install phase from the
+ * newly-installed `mandrel` binary and stream its stdout/stderr through the
+ * parent's write sinks. Each phase runs as an isolated child process so the
+ * newly-installed module code (not the currently-loaded old module) executes.
+ *
+ * The spawn uses `shell: true` only on Windows where the binary is a `.cmd`
+ * shim (CVE-2024-27980 parity). The argv vector is a fixed constant list
+ * per phase — no operator-supplied data enters the vector, so the shell flag
+ * carries no injection risk (security-baseline § Output & Rendering).
+ *
+ * Throws when the child exits non-zero so the orchestrator can surface the
+ * failure to the operator.
+ *
+ * @param {string} phase - The mandrel sub-command to run (e.g. `'sync'`).
+ * @param {string[]} args - Additional arguments for the sub-command.
+ * @param {{
+ *   binPath: string,
+ *   cwd: string,
+ *   write: (s: string) => void,
+ *   writeErr: (s: string) => void,
+ *   spawnFn?: typeof spawnSync,
+ * }} opts
+ * @returns {{ ok: boolean, stdout: string, stderr: string }}
+ */
+export function defaultSpawnPhase(
+  phase,
+  args,
+  { binPath, cwd, write, writeErr, spawnFn = spawnSync },
+) {
+  const argv = [phase, ...args];
+  const r = spawnFn(binPath, argv, {
+    cwd,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  const stdout = typeof r.stdout === 'string' ? r.stdout : '';
+  const stderr = typeof r.stderr === 'string' ? r.stderr : '';
+  if (stdout) write(stdout);
+  if (stderr) writeErr(stderr);
+  if (r.error) {
+    throw new Error(
+      `mandrel update: failed to spawn \`mandrel ${phase}\` from new binary: ${r.error.message}`,
+    );
+  }
+  const ok = r.status === 0;
+  return { ok, stdout, stderr };
+}
+
 /**
  * The ordered step names the orchestrator drives on a non-major bump. Shared
  * by the live path and the `--dry-run` plan printout so the two never drift.
@@ -576,6 +803,7 @@ function emitMajorRefusal(target, writeErr) {
  *   currentVersion?: string | (() => string),
  *   resolveTargetVersion?: () => (string | Promise<string>),
  *   npmUpdate?: (version: string, opts: { installCmd?: string }) => unknown | Promise<unknown>,
+ *   spawnPhase?: (phase: string, args: string[], opts: { binPath: string, cwd: string, write: (s: string) => void, writeErr: (s: string) => void }) => Promise<{ ok: boolean, stdout: string, stderr: string }> | { ok: boolean, stdout: string, stderr: string },
  *   runSync?: typeof defaultRunSync,
  *   runMigrations?: typeof defaultRunMigrations,
  *   runDoctor?: typeof defaultRunDoctor,
@@ -583,6 +811,7 @@ function emitMajorRefusal(target, writeErr) {
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
+ *   cwd?: () => string,
  * }} [opts]
  * @returns {Promise<{
  *   ok: boolean,
@@ -599,6 +828,7 @@ export async function runUpdate({
   currentVersion,
   resolveTargetVersion,
   npmUpdate,
+  spawnPhase,
   runSync = defaultRunSync,
   runMigrations = defaultRunMigrations,
   runDoctor = defaultRunDoctor,
@@ -606,6 +836,7 @@ export async function runUpdate({
   write = (s) => process.stdout.write(s),
   writeErr = (s) => process.stderr.write(s),
   exit = (code) => process.exit(code),
+  cwd = () => process.cwd(),
 } = {}) {
   const dryRun = argv.includes('--dry-run');
   const allowMajor = argv.includes('--major');
@@ -703,40 +934,136 @@ export async function runUpdate({
   await npmUpdate(target, { installCmd });
   stepsRun.push('npm-update');
 
-  // 2. runSync — re-materialize ./.agents/ from the freshly installed payload.
-  runSync({ argv: [] });
-  stepsRun.push('runSync');
+  // Decide whether to use the re-exec path (spawnPhase) or the in-process
+  // backward-compat seams (runSync / runMigrations / runDoctor).
+  //
+  // spawnPhase injected → re-exec path: all post-install phases run from the
+  //   newly-installed binary. This is the production path and is what fixes
+  //   the stale-materialization bug (Story #4034).
+  //
+  // spawnPhase NOT injected → in-process path: the original pre-Story-#4034
+  //   behaviour. Tests that pre-date this change inject runSync/runMigrations/
+  //   runDoctor and rely on the in-process path; they stay green without any
+  //   modification.
+  const useReExec = typeof spawnPhase === 'function';
 
-  // 3. runMigrations — apply version-keyed steps for the crossed range.
-  runMigrations({ fromVersion: current, toVersion: target, ctx: {} });
-  stepsRun.push('runMigrations');
+  if (useReExec) {
+    // Re-exec path: post-install phases run from the new binary.
+    const projectRoot = cwd();
+    const binPath = resolveNewBinPath(projectRoot);
 
-  // 4. doctor — verify the resulting install.
-  const doctor = await runDoctor();
-  stepsRun.push('doctor');
-
-  // 5. surface the target changelog (best-effort; optional seam).
-  if (typeof surfaceChangelog === 'function') {
-    await surfaceChangelog(target);
-  }
+    // 2. runSync from new bin — re-materialize ./.agents/ from the freshly
+    //    installed payload. Running from the new bin ensures the copied files
+    //    come from the new package's .agents/ tree, not the old loaded module.
+    const syncResult = await spawnPhase('sync', [], {
+      binPath,
+      cwd: projectRoot,
+      write,
+      writeErr,
+    });
+    if (!syncResult.ok) {
+      throw new Error(
+        `mandrel update: \`mandrel sync\` from new binary exited non-zero — ` +
+          'the .agents/ materialization may be incomplete. ' +
+          'Run `mandrel sync` manually to restore.',
+      );
+    }
+    stepsRun.push('runSync');
 
-  if (!doctor.ok) {
-    const failed = doctor.results.filter((r) => !r.ok).map((r) => r.name);
-    writeErr(
-      `mandrel update: upgraded to v${target} but doctor reported failures: ` +
-        `${failed.join(', ')}\n` +
-        '   → Run `mandrel doctor` for remedies.\n',
+    // 3. runMigrations from new bin — apply version-keyed steps for the
+    //    crossed range. The new binary's migration registry contains any steps
+    //    added in the target version; the old process's registry does not.
+    const migrateResult = await spawnPhase(
+      'migrate',
+      ['--from', current, '--to', target],
+      { binPath, cwd: projectRoot, write, writeErr },
     );
-    exit(1);
-    return {
-      ok: false,
-      action: 'doctor-failed',
-      currentVersion: current,
-      targetVersion: target,
-      major,
-      stepsRun,
-      dryRun: false,
-    };
+    if (!migrateResult.ok) {
+      throw new Error(
+        `mandrel update: \`mandrel migrate\` from new binary exited non-zero — ` +
+          `some migrations for v${current} → v${target} may not have applied. ` +
+          `Run \`mandrel migrate --from ${current} --to ${target}\` manually to retry.`,
+      );
+    }
+    stepsRun.push('runMigrations');
+
+    // 4. doctor from new bin — verify the resulting install. Running from the
+    //    new bin is critical: the agents-drift check compares the materialized
+    //    .agents/ against the installed package payload. When the old process
+    //    runs this check, it resolves the package root to its own (old) install
+    //    dir, so drift against the new payload is invisible. The new binary
+    //    resolves the package root to the now-installed new version, producing
+    //    an accurate result.
+    const doctorResult = await spawnPhase('doctor', [], {
+      binPath,
+      cwd: projectRoot,
+      write,
+      writeErr,
+    });
+    stepsRun.push('doctor');
+
+    // 5. surface the target changelog (best-effort; optional seam).
+    if (typeof surfaceChangelog === 'function') {
+      await surfaceChangelog(target);
+    }
+
+    if (!doctorResult.ok) {
+      writeErr(
+        `mandrel update: upgraded to v${target} but doctor reported failures.\n` +
+          '   → Run `mandrel doctor` for remedies.\n',
+      );
+      exit(1);
+      return {
+        ok: false,
+        action: 'doctor-failed',
+        currentVersion: current,
+        targetVersion: target,
+        major,
+        stepsRun,
+        dryRun: false,
+      };
+    }
+  } else {
+    // In-process backward-compat path (pre-Story-#4034 behaviour).
+    // Used when no `spawnPhase` seam is injected — preserves full backward
+    // compatibility with existing tests that inject runSync/runMigrations/
+    // runDoctor directly.
+
+    // 2. runSync — re-materialize ./.agents/ from the new payload.
+    runSync({ argv: [] });
+    stepsRun.push('runSync');
+
+    // 3. runMigrations — apply version-keyed steps for the crossed range.
+    runMigrations({ fromVersion: current, toVersion: target, ctx: {} });
+    stepsRun.push('runMigrations');
+
+    // 4. doctor — verify the resulting install.
+    const doctor = await runDoctor();
+    stepsRun.push('doctor');
+
+    // 5. surface the target changelog (best-effort; optional seam).
+    if (typeof surfaceChangelog === 'function') {
+      await surfaceChangelog(target);
+    }
+
+    if (!doctor.ok) {
+      const failed = doctor.results.filter((r) => !r.ok).map((r) => r.name);
+      writeErr(
+        `mandrel update: upgraded to v${target} but doctor reported failures: ` +
+          `${failed.join(', ')}\n` +
+          '   → Run `mandrel doctor` for remedies.\n',
+      );
+      exit(1);
+      return {
+        ok: false,
+        action: 'doctor-failed',
+        currentVersion: current,
+        targetVersion: target,
+        major,
+        stepsRun,
+        dryRun: false,
+      };
+    }
   }
 
   write(`✅  Updated to v${target}. The lockfile bump is staged for review.\n`);
@@ -763,8 +1090,17 @@ export async function runUpdate({
  *     lockfile (`pnpm`/`yarn`/`npm`), or the `--install-cmd` override —
  *     through the shared `runInstallCommand` helper — no git mutation;
  *     lockfile left staged.
+ *   - `spawnPhase` is wired to `defaultSpawnPhase`, which spawns each
+ *     post-install phase (sync, migrate, doctor) from the newly-installed
+ *     binary (`node_modules/.bin/mandrel`). This is the Story #4034 fix:
+ *     the new bin loads the new package's module code and resolves paths
+ *     against the new install dir, so sync/migrate/doctor can never observe
+ *     the old payload.
  *   - `surfaceChangelog` prints the relevant `docs/CHANGELOG.md` section(s)
- *     for the applied range, degrading gracefully when the file is absent.
+ *     for the applied range. Reads from the packaged file first; falls back to
+ *     a GitHub raw-content fetch via the injectable `fetchChangelog` seam when
+ *     the packaged file is absent; emits an actionable link to the GitHub
+ *     Releases page when both sources fail (Story #4035).
  *
  * Every seam stays injectable on `runUpdate`; these are merely the
  * no-seam-provided fallbacks, so the existing seam-driven tests stay green.
@@ -773,8 +1109,9 @@ export async function runUpdate({
  *
  * The second `deps` argument exposes the **process boundaries** the production
  * defaults shell out across (`versionRunner` = `npm view`, `runInstall` =
- * the install spawn) plus `fs` / `cachePath` / `now`, so the entrypoint can be
- * driven end-to-end with the network/npm boundary stubbed and no real I/O.
+ * the install spawn, `spawnFn` = the phase-spawn boundary) plus `fs` /
+ * `cachePath` / `now`, so the entrypoint can be driven end-to-end with the
+ * network/npm boundary stubbed and no real I/O.
  * `bin/mandrel.js` calls `run(argv)` with no `deps`, getting the production
  * wiring; tests pass fakes. The `deps` surface is NOT part of the public
  * subcommand contract — `bin/mandrel.js` only ever supplies `argv`.
@@ -787,7 +1124,9 @@ export async function runUpdate({
  *   now?: Date,
  *   versionRunner?: () => string,
  *   runInstall?: (installCmd: string, cwd: string) => { status: number, stderr: string },
+ *   spawnFn?: typeof spawnSync,
  *   changelogPath?: string,
+ *   fetchChangelog?: (version: string) => Promise<string>,
  *   runUpdate?: typeof runUpdate,
  *   runSync?: typeof defaultRunSync,
  *   runMigrations?: typeof defaultRunMigrations,
@@ -806,7 +1145,9 @@ export default async function run(argv = [], deps = {}) {
     now,
     versionRunner,
     runInstall,
+    spawnFn,
     changelogPath,
+    fetchChangelog,
     runUpdate: runUpdateImpl = runUpdate,
     runSync,
     runMigrations,
@@ -819,6 +1160,16 @@ export default async function run(argv = [], deps = {}) {
 
   const current = deps.currentVersion ?? defaultCurrentVersion(fs);
 
+  // The production spawnPhase default: spawn each post-install phase from
+  // node_modules/.bin/mandrel (the newly-installed binary). spawnFn is
+  // injectable so tests can stub the spawn boundary without running a real
+  // child process.
+  const productionSpawnPhase = (phase, args, opts) =>
+    defaultSpawnPhase(phase, args, {
+      ...opts,
+      ...(spawnFn ? { spawnFn } : {}),
+    });
+
   await runUpdateImpl({
     argv,
     currentVersion: current,
@@ -836,17 +1187,27 @@ export default async function run(argv = [], deps = {}) {
         ...(runInstall ? { runInstall } : {}),
         fs,
       }),
+    // In the production default export, always wire spawnPhase unless the
+    // caller injects the old-style in-process seams (runSync/runMigrations/
+    // runDoctor). When any old-style seam is present, fall back to in-process
+    // behavior to preserve the full backward-compat surface that the
+    // entrypoint test (update-entrypoint.test.js) relies on.
+    ...(runSync || runMigrations || runDoctor
+      ? {
+          ...(runSync ? { runSync } : {}),
+          ...(runMigrations ? { runMigrations } : {}),
+          ...(runDoctor ? { runDoctor } : {}),
+        }
+      : { spawnPhase: productionSpawnPhase }),
     surfaceChangelog: (target) =>
       defaultSurfaceChangelog(target, {
         current,
         fs,
         ...(changelogPath ? { changelogPath } : {}),
+        ...(fetchChangelog ? { fetchChangelog } : {}),
         ...(write ? { write } : {}),
         ...(writeErr ? { writeErr } : {}),
       }),
-    ...(runSync ? { runSync } : {}),
-    ...(runMigrations ? { runMigrations } : {}),
-    ...(runDoctor ? { runDoctor } : {}),
     ...(write ? { write } : {}),
     ...(writeErr ? { writeErr } : {}),
     ...(exit ? { exit } : {}),

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "mandrel",
-  "version": "1.59.0",
+  "version": "1.60.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "main": "index.js",
   "files": [
     ".agents/",
     "bin/",
+    "docs/CHANGELOG.md",
     "lib/"
   ],
   "publishConfig": {