mandrel 2.35.0 → 2.37.0

package/lib/cli/migrate.js

@@ -54,6 +54,7 @@
 import {
   migrations as defaultRegistry,
   runMigrations as defaultRunMigrations,
+  selectStepsInRange,
 } from '../migrations/index.js';
 
 /**
@@ -77,36 +78,97 @@ function parseOption(argv, flag) {
 }
 
 /**
- * Parse a dotted semver-ish string into a numeric tuple. Mirrors the runner's
- * own comparator so the dry-run in-range filter matches the live filter
- * exactly.
+ * The envelope shape every `runMigrate` exit returns. Centralised so the four
+ * exits cannot drift in which fields they populate.
  *
- * @param {string} version
- * @returns {[number, number, number]}
+ * @param {object} fields
+ * @returns {object}
  */
-function parseVersion(version) {
-  const [major, minor, patch] = String(version).split('.');
-  return [
-    Number.parseInt(major, 10) || 0,
-    Number.parseInt(minor, 10) || 0,
-    Number.parseInt(patch, 10) || 0,
-  ];
+function migrateResult(fields) {
+  return {
+    ok: false,
+    action: 'usage-error',
+    fromVersion: null,
+    toVersion: null,
+    dryRun: false,
+    applied: [],
+    skipped: [],
+    wouldApply: [],
+    wouldSkip: [],
+    ...fields,
+  };
+}
+
+/**
+ * Both bounds are required: the runner filters `fromVersion < v <= toVersion`,
+ * so an absent bound is ambiguous rather than a sensible default.
+ *
+ * @param {{ writeErr: (s: string) => void, exit: (code: number) => void }} io
+ * @returns {void}
+ */
+function reportUsageError({ writeErr, exit }) {
+  writeErr(
+    'mandrel migrate: both --from <version> and --to <version> are required.\n' +
+      '   → Usage: mandrel migrate --from <version> --to <version> [--dry-run]\n',
+  );
+  exit(1);
 }
 
 /**
- * Compare two version strings (standard `Array.sort` comparator contract).
+ * Report the in-range steps and whether each WOULD apply or be skipped,
+ * probing a throwaway context so no step's `apply` runs and nothing on disk
+ * changes. The ordering comes from `selectStepsInRange`, the same selector the
+ * live run uses, so the preview cannot disagree with what would happen.
  *
- * @param {string} a
- * @param {string} b
- * @returns {number}
+ * @param {{
+ *   registry: Array<object>,
+ *   fromVersion: string,
+ *   toVersion: string,
+ *   write: (s: string) => void,
+ * }} params
+ * @returns {{ wouldApply: string[], wouldSkip: string[] }}
  */
-function compareVersions(a, b) {
-  const pa = parseVersion(a);
-  const pb = parseVersion(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+function previewMigrations({ registry, fromVersion, toVersion, write }) {
+  const inRange = selectStepsInRange({ registry, fromVersion, toVersion });
+  const wouldApply = [];
+  const wouldSkip = [];
+  const probeCtx = {};
+
+  write(`mandrel migrate — dry run v${fromVersion} → v${toVersion}\n`);
+  if (inRange.length === 0) {
+    write('  (no migration steps in range)\n');
   }
-  return 0;
+  for (const step of inRange) {
+    const bucket = step.detect(probeCtx) ? wouldApply : wouldSkip;
+    const verb = bucket === wouldApply ? 'would apply ' : 'would skip  ';
+    bucket.push(step.version);
+    write(`  ${verb} ${step.version}: ${step.description}\n`);
+  }
+  write('Dry run: no migrations applied, nothing written.\n');
+
+  return { wouldApply, wouldSkip };
+}
+
+/**
+ * @param {{
+ *   applied: string[],
+ *   fromVersion: string,
+ *   toVersion: string,
+ *   write: (s: string) => void,
+ * }} params
+ * @returns {void}
+ */
+function reportApplied({ applied, fromVersion, toVersion, write }) {
+  if (applied.length === 0) {
+    write(
+      `mandrel migrate: no migrations to apply for v${fromVersion} → v${toVersion}.\n`,
+    );
+    return;
+  }
+  const plural = applied.length === 1 ? '' : 's';
+  write(
+    `✅  Applied ${applied.length} migration${plural} (v${fromVersion} → v${toVersion}).\n`,
+  );
 }
 
 /**
@@ -146,107 +208,51 @@ export function runMigrate({
   const fromVersion = parseOption(argv, '--from');
   const toVersion = parseOption(argv, '--to');
 
-  // --- Usage validation -----------------------------------------------------
-  // Both bounds are required: the runner filters fromVersion < v <= toVersion,
-  // so an absent bound is ambiguous rather than a sensible default.
   if (!fromVersion || !toVersion) {
-    writeErr(
-      'mandrel migrate: both --from <version> and --to <version> are required.\n' +
-        '   → Usage: mandrel migrate --from <version> --to <version> [--dry-run]\n',
-    );
-    exit(1);
-    return {
-      ok: false,
-      action: 'usage-error',
+    reportUsageError({ writeErr, exit });
+    return migrateResult({
       fromVersion: fromVersion ?? null,
       toVersion: toVersion ?? null,
       dryRun,
-      applied: [],
-      skipped: [],
-      wouldApply: [],
-      wouldSkip: [],
-    };
+    });
   }
 
-  // --- Dry run --------------------------------------------------------------
-  // Report the in-range steps and whether each WOULD apply or be skipped,
-  // probing a throwaway context so no step's apply runs and nothing on disk
-  // changes.
   if (dryRun) {
-    const inRange = registry
-      .filter(
-        (step) =>
-          compareVersions(step.version, fromVersion) > 0 &&
-          compareVersions(step.version, toVersion) <= 0,
-      )
-      .sort((a, b) => compareVersions(a.version, b.version));
-
-    const wouldApply = [];
-    const wouldSkip = [];
-    const probeCtx = {};
-
-    write(`mandrel migrate — dry run v${fromVersion} → v${toVersion}\n`);
-    if (inRange.length === 0) {
-      write('  (no migration steps in range)\n');
-    }
-    for (const step of inRange) {
-      const willApply = step.detect(probeCtx);
-      if (willApply) {
-        wouldApply.push(step.version);
-        write(`  would apply  ${step.version}: ${step.description}\n`);
-      } else {
-        wouldSkip.push(step.version);
-        write(`  would skip   ${step.version}: ${step.description}\n`);
-      }
-    }
-    write('Dry run: no migrations applied, nothing written.\n');
-
-    return {
+    const { wouldApply, wouldSkip } = previewMigrations({
+      registry,
+      fromVersion,
+      toVersion,
+      write,
+    });
+    return migrateResult({
       ok: true,
       action: 'dry-run',
       fromVersion,
       toVersion,
       dryRun: true,
-      applied: [],
-      skipped: [],
       wouldApply,
       wouldSkip,
-    };
+    });
   }
 
-  // --- Live run -------------------------------------------------------------
-  // Delegate to the runner, which owns ordering, range filtering, idempotency,
-  // and the per-step `migrated …` log line.
+  // The runner owns ordering, range filtering, idempotency, and the per-step
+  // `migrated …` log line.
   const { applied, skipped } = runMigrations({
     fromVersion,
     toVersion,
     ctx,
     registry,
   });
+  reportApplied({ applied, fromVersion, toVersion, write });
 
-  if (applied.length === 0) {
-    write(
-      `mandrel migrate: no migrations to apply for v${fromVersion} → v${toVersion}.\n`,
-    );
-  } else {
-    write(
-      `✅  Applied ${applied.length} migration${
-        applied.length === 1 ? '' : 's'
-      } (v${fromVersion} → v${toVersion}).\n`,
-    );
-  }
-
-  return {
+  return migrateResult({
     ok: true,
     action: 'migrated',
     fromVersion,
     toVersion,
-    dryRun: false,
     applied,
     skipped,
-    wouldApply: [],
-    wouldSkip: [],
-  };
+  });
 }
 
 /**

package/lib/migrations/helpers/retire-agentrc-key.js

@@ -0,0 +1,200 @@
+// lib/migrations/helpers/retire-agentrc-key.js
+/**
+ * The shared scaffold behind every "strip a retired `.agentrc.json` key"
+ * migration step.
+ *
+ * Retiring a config key is the framework's most common migration: a key is
+ * dropped from the runtime AJV schema, the block it lived under carries
+ * `additionalProperties: false`, and a consumer whose config still sets it
+ * hits a hard validation failure on upgrade rather than a warning. Every such
+ * step reads the config, decides whether the key is present, deletes it,
+ * prunes whatever containers that emptied, and writes the file back — the
+ * same mechanics each time, previously copy-pasted per step (jscpd recorded
+ * five of them between 48 and 58 percent duplicated).
+ *
+ * Only three things actually vary between steps, so only those three are
+ * declared:
+ *
+ *   - **which config surfaces to sweep** — `.agentrc.json` alone, or that plus
+ *     the gitignored `.agentrc.local.json`. `config-resolver.js` deep-merges
+ *     the overlay over the base *before* the AJV gate runs, so a key surviving
+ *     in the overlay fails exactly as a base one would. A step that swept only
+ *     the base would report "nothing to migrate" and leave that consumer hard
+ *     broken with no self-service remedy.
+ *   - **which key paths are retired** — a step may retire more than one.
+ *   - **how far to prune emptied ancestors** — this is deliberately per-key
+ *     and not a global policy. `planning` is optional, so an emptied
+ *     `planning` block is removed; `project` is required and an empty
+ *     `commands` object is valid against the schema, so pruning it would be a
+ *     cosmetic edit to a config the consumer owns.
+ *
+ * Builtins only, and the `fs` seam stays injectable via `ctx.fs`, because
+ * these steps run during `mandrel update` before third-party packages are
+ * guaranteed to be present.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/** The committed config every consumer has. */
+export const AGENTRC_BASE_FILENAME = '.agentrc.json';
+
+/** The operator-owned, gitignored overlay the resolver merges over the base. */
+const AGENTRC_LOCAL_FILENAME = '.agentrc.local.json';
+
+/**
+ * Both surfaces the resolver reads — the default sweep for a retired key.
+ *
+ * Module-local: a step that wants both surfaces takes the default and names
+ * nothing, so exporting this would ship a symbol with no importer.
+ */
+const AGENTRC_FILENAMES = Object.freeze([
+  AGENTRC_BASE_FILENAME,
+  AGENTRC_LOCAL_FILENAME,
+]);
+
+/**
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @returns {string}
+ */
+function resolveAgentrcPath(ctx, filename) {
+  const projectRoot = ctx?.projectRoot ?? process.cwd();
+  return path.join(projectRoot, filename);
+}
+
+/**
+ * Read and parse one config surface. An absent or unparseable file is the
+ * common case (no overlay, fresh checkout), not an error.
+ *
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @param {typeof nodeFs} fsImpl
+ * @returns {object | null}
+ */
+function readAgentrcConfig(ctx, filename, fsImpl) {
+  try {
+    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx, filename), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk the container chain for a key path, returning every object along it.
+ * Returns `null` as soon as a level is missing or is not a plain object, which
+ * is what makes `hasKey` false for a config that never had the block.
+ *
+ * @param {object | null} config
+ * @param {string[]} keyPath
+ * @returns {object[] | null}
+ */
+function resolveContainers(config, keyPath) {
+  if (!config || typeof config !== 'object') return null;
+  const containers = [config];
+  let cursor = config;
+  for (const segment of keyPath.slice(0, -1)) {
+    const next = cursor[segment];
+    if (!next || typeof next !== 'object') return null;
+    containers.push(next);
+    cursor = next;
+  }
+  return containers;
+}
+
+/**
+ * @param {object | null} config
+ * @param {string[]} keyPath
+ * @returns {boolean}
+ */
+function hasKey(config, keyPath) {
+  const containers = resolveContainers(config, keyPath);
+  if (!containers) return false;
+  const leafOwner = containers[containers.length - 1];
+  return Object.hasOwn(leafOwner, keyPath[keyPath.length - 1]);
+}
+
+/**
+ * Delete the leaf key, then remove up to `pruneDepth` ancestors that the
+ * deletion left empty. `pruneDepth: 0` deletes the key and nothing else.
+ *
+ * @param {object} config
+ * @param {{ path: string[], pruneDepth?: number }} key
+ * @returns {void}
+ */
+function stripKey(config, key) {
+  const keyPath = key.path;
+  const containers = resolveContainers(config, keyPath);
+  if (!containers) return;
+
+  const leafOwner = containers[containers.length - 1];
+  delete leafOwner[keyPath[keyPath.length - 1]];
+
+  const pruneDepth = key.pruneDepth ?? 0;
+  for (let level = 0; level < pruneDepth; level += 1) {
+    const index = containers.length - 1 - level;
+    const emptied = containers[index];
+    const parent = containers[index - 1];
+    if (!parent || Object.keys(emptied).length > 0) break;
+    delete parent[keyPath[index - 1]];
+  }
+}
+
+/**
+ * Build a migration step that strips one or more retired keys from the
+ * consumer's config surfaces.
+ *
+ * `detect` is true when any declared key is present in any swept surface;
+ * `apply` rewrites only the surfaces that actually carry one, which is what
+ * makes a repeat pass a genuine no-op rather than a reformat.
+ *
+ * @param {{
+ *   version: string,
+ *   description: string,
+ *   filenames?: readonly string[],
+ *   keys: Array<{ path: string[], pruneDepth?: number }>,
+ * }} spec
+ * @returns {{
+ *   version: string,
+ *   description: string,
+ *   detect: (ctx?: { projectRoot?: string, fs?: typeof nodeFs }) => boolean,
+ *   apply: (ctx?: { projectRoot?: string, fs?: typeof nodeFs }) => void,
+ * }}
+ */
+export function createRetireAgentrcKeyStep({
+  version,
+  description,
+  filenames = AGENTRC_FILENAMES,
+  keys,
+}) {
+  const carriesRetiredKey = (config) =>
+    keys.some((key) => hasKey(config, key.path));
+
+  return {
+    version,
+    description,
+    detect(ctx) {
+      const fsImpl = ctx?.fs ?? nodeFs;
+      return filenames.some((filename) =>
+        carriesRetiredKey(readAgentrcConfig(ctx, filename, fsImpl)),
+      );
+    },
+    apply(ctx) {
+      const fsImpl = ctx?.fs ?? nodeFs;
+      for (const filename of filenames) {
+        const config = readAgentrcConfig(ctx, filename, fsImpl);
+        if (!carriesRetiredKey(config)) continue;
+
+        for (const key of keys) {
+          if (hasKey(config, key.path)) stripKey(config, key);
+        }
+
+        fsImpl.writeFileSync(
+          resolveAgentrcPath(ctx, filename),
+          `${JSON.stringify(config, null, 2)}\n`,
+        );
+      }
+    },
+  };
+}

package/lib/migrations/index.js

@@ -52,6 +52,7 @@
  * (ascending by version) with an idempotent `detect`/`apply`.
  */
 
+import { compareVersions } from '../cli/version-helpers.js';
 import { retireMiDropKnobs } from './steps/2.1.0-retire-mi-drop-knobs.js';
 import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurrency-cap.js';
 import { retireEpicAcTags } from './steps/2.2.0-retire-epic-ac-tags.js';
@@ -80,38 +81,42 @@ export const migrations = [
 ];
 
 /**
- * Parse a dotted semver-ish string into a numeric tuple for comparison.
- * Non-numeric or missing segments coerce to 0 so a partial version
- * (`'1.4'`) still compares sanely against a full one (`'1.4.0'`).
+ * The version ordering every migration decision uses.
  *
- * @param {string} version
- * @returns {[number, number, number]}
+ * Re-exported from `lib/cli/version-helpers.js` — the dependency-free leaf
+ * that owns the canonical `parseVersion` / `compareVersions` pair (Story
+ * #4048 B3). The runner previously carried its own copy, so an ordering fix
+ * had to be made in three places or the copies drifted apart. Re-exporting
+ * rather than moving keeps this module's public surface intact for the
+ * callers that import `compareVersions` from here.
  */
-function parseVersion(version) {
-  const [major, minor, patch] = String(version).split('.');
-  return [
-    Number.parseInt(major, 10) || 0,
-    Number.parseInt(minor, 10) || 0,
-    Number.parseInt(patch, 10) || 0,
-  ];
-}
+export { compareVersions };
 
 /**
- * Compare two version strings. Returns a negative number when `a < b`, zero
- * when equal, and a positive number when `a > b` — the standard `Array.sort`
- * comparator contract.
+ * The steps that apply for an upgrade, in the order they must run:
+ * `fromVersion < step.version <= toVersion`, ascending.
+ *
+ * Exported because `mandrel migrate --dry-run` has to preview exactly what the
+ * live run would do. That preview previously re-implemented this filter and
+ * carried a comment promising it "mirrors the runner's own comparator" — a
+ * sync obligation nothing enforced, and the reason a third `compareVersions`
+ * copy existed. One selector means the preview cannot drift from the run.
  *
- * @param {string} a
- * @param {string} b
- * @returns {number}
+ * @param {{ registry?: Array<object>, fromVersion: string, toVersion: string }} params
+ * @returns {Array<object>}
  */
-export function compareVersions(a, b) {
-  const pa = parseVersion(a);
-  const pb = parseVersion(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
-  }
-  return 0;
+export function selectStepsInRange({
+  registry = migrations,
+  fromVersion,
+  toVersion,
+}) {
+  return registry
+    .filter(
+      (step) =>
+        compareVersions(step.version, fromVersion) > 0 &&
+        compareVersions(step.version, toVersion) <= 0,
+    )
+    .sort((a, b) => compareVersions(a.version, b.version));
 }
 
 /**
@@ -152,13 +157,7 @@ export function runMigrations({
   log = console.log,
   registry = migrations,
 } = {}) {
-  const inRange = registry
-    .filter(
-      (step) =>
-        compareVersions(step.version, fromVersion) > 0 &&
-        compareVersions(step.version, toVersion) <= 0,
-    )
-    .sort((a, b) => compareVersions(a.version, b.version));
+  const inRange = selectStepsInRange({ registry, fromVersion, toVersion });
 
   const applied = [];
   const skipped = [];

package/lib/migrations/steps/2.1.0-retire-mi-drop-knobs.js

@@ -11,90 +11,31 @@
  * sub-schemas with `additionalProperties: false`, so a consumer whose
  * config still carries either key hits a hard AJV validation failure on
  * upgrade, not a warning. This step strips them before that check runs.
+ *
+ * Unlike the later retire-steps this one sweeps the committed config only:
+ * the knobs were written by the bootstrap script, never hand-pinned in an
+ * operator's `.agentrc.local.json`.
  */
 
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-const AGENTRC_FILENAME = '.agentrc.json';
-
-/**
- * @param {unknown} ctx
- * @returns {string}
- */
-function resolveAgentrcPath(ctx) {
-  const projectRoot = ctx?.projectRoot ?? process.cwd();
-  return path.join(projectRoot, AGENTRC_FILENAME);
-}
-
-/**
- * @param {unknown} ctx
- * @param {typeof nodeFs} fsImpl
- * @returns {object | null}
- */
-function readAgentrcConfig(ctx, fsImpl) {
-  try {
-    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx), 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {object | null} config
- * @returns {boolean}
- */
-function hasRetiredKey(config) {
-  const guardrails = config?.delivery?.quality?.codingGuardrails;
-  const autoRefresh = config?.delivery?.quality?.autoRefresh;
-  return (
-    (Boolean(guardrails) && Object.hasOwn(guardrails, 'miDropMustRefactor')) ||
-    (Boolean(autoRefresh) && Object.hasOwn(autoRefresh, 'miDropCap'))
-  );
-}
+import {
+  AGENTRC_BASE_FILENAME,
+  createRetireAgentrcKeyStep,
+} from '../helpers/retire-agentrc-key.js';
 
-export const retireMiDropKnobs = {
+export const retireMiDropKnobs = createRetireAgentrcKeyStep({
   version: '2.1.0',
   description:
     'strip retired delivery.quality.codingGuardrails.miDropMustRefactor ' +
     'and delivery.quality.autoRefresh.miDropCap from .agentrc.json',
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {boolean}
-   */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    return hasRetiredKey(readAgentrcConfig(ctx, fsImpl));
-  },
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {void}
-   */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    const config = readAgentrcConfig(ctx, fsImpl);
-    if (!config) return;
-
-    const guardrails = config.delivery?.quality?.codingGuardrails;
-    if (guardrails && Object.hasOwn(guardrails, 'miDropMustRefactor')) {
-      delete guardrails.miDropMustRefactor;
-      if (Object.keys(guardrails).length === 0) {
-        delete config.delivery.quality.codingGuardrails;
-      }
-    }
-
-    const autoRefresh = config.delivery?.quality?.autoRefresh;
-    if (autoRefresh && Object.hasOwn(autoRefresh, 'miDropCap')) {
-      delete autoRefresh.miDropCap;
-      if (Object.keys(autoRefresh).length === 0) {
-        delete config.delivery.quality.autoRefresh;
-      }
-    }
-
-    fsImpl.writeFileSync(
-      resolveAgentrcPath(ctx),
-      `${JSON.stringify(config, null, 2)}\n`,
-    );
-  },
-};
+  filenames: [AGENTRC_BASE_FILENAME],
+  keys: [
+    {
+      path: ['delivery', 'quality', 'codingGuardrails', 'miDropMustRefactor'],
+      pruneDepth: 1,
+    },
+    {
+      path: ['delivery', 'quality', 'autoRefresh', 'miDropCap'],
+      pruneDepth: 1,
+    },
+  ],
+});