mandrel 1.57.0

package/lib/cli/version-check.js

@@ -0,0 +1,206 @@
+// lib/cli/version-check.js
+/**
+ * Daily-cached version freshness check (Story #3500, Epic #3437 — Auto-Update
+ * & Version Lifecycle).
+ *
+ * Detects a stale install ("f-notify-stale") via a daily on-disk JSON cache so
+ * callers learn that a newer version exists **without** issuing a network call
+ * on every command. The cache lives under the project's temp root as a small
+ * JSON document:
+ *
+ *   { "latestVersion": "<semver>", "checkedAt": "<ISO-8601 timestamp>" }
+ *
+ * `isStale` reads that cache and only invokes the injected network `runner`
+ * seam when the cached `checkedAt` is older than 24h. A fresh cache short-
+ * circuits with zero network I/O; a missing, unreadable, or stale cache
+ * triggers exactly one `runner` call and a cache refresh.
+ *
+ * Security (security-baseline § 5 — Data Leakage & Logging):
+ *   - Logs only version strings and filesystem paths. Never logs tokens,
+ *     credentials, environment values, or raw file contents.
+ *   - Performs no shell-string interpolation; the network probe is delegated
+ *     to the injected `runner` seam so the host owns transport and auth.
+ *
+ * Injectable seams (used by lib/cli/__tests__/version-check.test.js):
+ *   - `cachePath` — absolute path to the daily cache JSON file
+ *   - `now`       — Date provider (defaults to `new Date()`)
+ *   - `runner`    — async network seam returning the latest version string
+ *   - `fs`        — node:fs surface (readFileSync / writeFileSync / mkdirSync)
+ *   - `log`       — structured logger seam (defaults to a no-op)
+ *
+ * Following the lib/cli/*.js convention: Node built-ins only, every effectful
+ * dependency is an injectable seam, and the default export is the seam-free
+ * production wiring.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/** Cache freshness window in milliseconds (24 hours). */
+export const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+
+/** Default cache filename under the temp root. */
+export const DEFAULT_CACHE_FILENAME = 'version-check.json';
+
+/**
+ * Read and parse the daily cache JSON.
+ *
+ * Returns `null` when the file is absent, unreadable, malformed, or missing
+ * the required `checkedAt` / `latestVersion` fields — every one of those is a
+ * "treat as no cache" condition for `isStale`, so callers never have to
+ * distinguish them.
+ *
+ * Never throws: a corrupt or missing cache must degrade to a refresh, not a
+ * crash.
+ *
+ * @param {{
+ *   cachePath: string,
+ *   fs?: typeof import('node:fs'),
+ * }} opts
+ * @returns {{ latestVersion: string, checkedAt: string } | null}
+ */
+export function readCache({ cachePath, fs = nodeFs }) {
+  if (!cachePath) return null;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(cachePath, 'utf8');
+  } catch {
+    // Missing or unreadable file → no cache.
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // Malformed JSON → no cache.
+    return null;
+  }
+
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    typeof parsed.latestVersion !== 'string' ||
+    typeof parsed.checkedAt !== 'string'
+  ) {
+    return null;
+  }
+
+  return { latestVersion: parsed.latestVersion, checkedAt: parsed.checkedAt };
+}
+
+/**
+ * Persist `{ latestVersion, checkedAt }` JSON to the cache path, creating the
+ * parent directory (the temp root) when needed.
+ *
+ * Logs only the version string and the cache path — never the raw payload.
+ *
+ * @param {{
+ *   cachePath: string,
+ *   latestVersion: string,
+ *   now?: Date,
+ *   fs?: typeof import('node:fs'),
+ *   log?: (msg: string) => void,
+ * }} opts
+ * @returns {{ latestVersion: string, checkedAt: string }} The persisted record.
+ */
+export function refreshCache({
+  cachePath,
+  latestVersion,
+  now = new Date(),
+  fs = nodeFs,
+  log = () => {},
+}) {
+  const record = {
+    latestVersion,
+    checkedAt: now.toISOString(),
+  };
+
+  const dir = path.dirname(cachePath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(cachePath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
+
+  // Safe to log: version string + path only (security-baseline § 5).
+  log(`version-check: cached latestVersion=${latestVersion} at ${cachePath}`);
+
+  return record;
+}
+
+/**
+ * Decide whether the cached freshness check is stale and, when it is, refresh
+ * it through the network `runner` seam.
+ *
+ * Behaviour:
+ *   - **Fresh cache** (`checkedAt` within 24h): returns immediately with the
+ *     cached version. The `runner` seam is **never** invoked — no per-command
+ *     network call.
+ *   - **Missing / corrupt / stale cache**: invokes `runner` exactly once to
+ *     fetch the latest version, persists the result via `refreshCache`, and
+ *     returns the refreshed record.
+ *
+ * The freshness comparison uses `>=` so an exactly-24h-old cache counts as
+ * stale (the boundary is treated as "due for refresh").
+ *
+ * @param {{
+ *   cachePath: string,
+ *   now?: Date,
+ *   runner: () => (string | Promise<string>),
+ *   fs?: typeof import('node:fs'),
+ *   log?: (msg: string) => void,
+ * }} opts
+ * @returns {Promise<{
+ *   stale: boolean,
+ *   refreshed: boolean,
+ *   latestVersion: string | null,
+ *   checkedAt: string | null,
+ * }>}
+ */
+export async function isStale({
+  cachePath,
+  now = new Date(),
+  runner,
+  fs = nodeFs,
+  log = () => {},
+}) {
+  const cached = readCache({ cachePath, fs });
+
+  if (cached) {
+    const ageMs = now.getTime() - new Date(cached.checkedAt).getTime();
+    const cacheIsFresh =
+      Number.isFinite(ageMs) && ageMs >= 0 && ageMs < STALE_AFTER_MS;
+
+    if (cacheIsFresh) {
+      // Fresh cache → no network call.
+      log(
+        `version-check: cache fresh latestVersion=${cached.latestVersion} (no network)`,
+      );
+      return {
+        stale: false,
+        refreshed: false,
+        latestVersion: cached.latestVersion,
+        checkedAt: cached.checkedAt,
+      };
+    }
+  }
+
+  // Missing, corrupt, or stale cache → one network probe + refresh.
+  if (typeof runner !== 'function') {
+    throw new Error(
+      'version-check: runner seam is required to refresh a stale cache',
+    );
+  }
+
+  log(
+    `version-check: cache stale or absent at ${cachePath} — probing for latest version`,
+  );
+  const latestVersion = await runner();
+  const record = refreshCache({ cachePath, latestVersion, now, fs, log });
+
+  return {
+    stale: true,
+    refreshed: true,
+    latestVersion: record.latestVersion,
+    checkedAt: record.checkedAt,
+  };
+}

package/lib/migrations/README.md

@@ -0,0 +1,69 @@
+# Version-keyed migrations
+
+The migration runner applies one-time, version-gated transformations to a
+consumer project's on-disk state when they upgrade `mandrel` across a
+version boundary that changed a contract.
+
+The engine lives in [`index.js`](./index.js). It owns ordering, version
+filtering, idempotency enforcement, and the actionable per-step log line. The
+`migrations` array is the single source of truth for which steps exist and in
+what order they run.
+
+> The registry currently ships **empty**. The project sits on the 1.x line
+> under release-please `always-bump-minor`, and no real contract break has
+> landed yet. The machinery is exercised by fixture steps in
+> [`__tests__/index.test.js`](./__tests__/index.test.js). Add the first real
+> step here when the first contract cutover lands.
+
+## Step shape
+
+Each entry in the `migrations` registry is an object:
+
+```js
+{
+  version: '1.4.0',                  // semver the step graduates the tree to
+  description: 'rename foo to bar',  // short, operator-facing summary
+  detect(ctx) { return boolean },    // true ⇒ this step still needs applying
+  apply(ctx) { /* perform the change */ },
+}
+```
+
+| Field         | Type                          | Meaning                                                                 |
+| ------------- | ----------------------------- | ----------------------------------------------------------------------- |
+| `version`     | `string` (semver)             | The version this step graduates the tree **to**. Drives range filtering and ordering. |
+| `description` | `string`                      | Short, operator-facing summary printed in the `migrated …` log line.    |
+| `detect`      | `(ctx) => boolean`            | Returns `true` when the change is **not yet** present (step still needs applying). |
+| `apply`       | `(ctx) => void`               | Performs the change against `ctx`.                                      |
+
+Keep the `migrations` array sorted ascending by `version`.
+
+## Version filtering
+
+`runMigrations({ fromVersion, toVersion, ctx })` applies only steps whose
+`version` is **strictly greater than `fromVersion`** and **less than or equal
+to `toVersion`**, in ascending version order:
+
+- A step at exactly `fromVersion` is already in the tree (the consumer was on
+  that version) and is **skipped**.
+- A step at exactly `toVersion` is the upgrade target and **runs**.
+
+Each step that actually applies prints `migrated <version>: <description>`
+through an injected `log` seam (defaults to `console.log`).
+
+`runMigrations` returns `{ applied, skipped }` — the versions that applied and
+the in-range versions skipped because `detect` returned `false`.
+
+## Idempotency contract
+
+**`detect(ctx)` MUST return `false` once `apply(ctx)` has run against the same
+context.**
+
+The runner consults `detect` before every `apply`, so a step whose change is
+already present is skipped. This makes a second `runMigrations` pass over the
+same context a no-op — re-running an upgrade, or running it after a partial
+failure, never double-applies a step. A migration whose `detect` keeps
+returning `true` after `apply` is a bug: it will re-fire on every pass.
+
+When authoring a step, write `detect` to probe for the *post-condition* of
+`apply` (the renamed key exists, the moved file is in place, …) and return the
+negation. The unit tests assert this property with fixture steps.

package/lib/migrations/__tests__/index.test.js

@@ -0,0 +1,216 @@
+// lib/migrations/__tests__/index.test.js
+/**
+ * Unit tests for lib/migrations/index.js — the version-keyed migration runner.
+ *
+ * All tests drive runMigrations through injected seams (a `log` capture and a
+ * fixture `registry`) over an in-memory plain-object context, so no real
+ * stdout write and no real filesystem I/O occur (testing-standards § Unit).
+ *
+ * Coverage contract (Story #3501 AC):
+ *   - Module shape: runMigrations named export + ordered `migrations` registry
+ *     array (which ships empty).
+ *   - Version filtering: only steps with fromVersion < version <= toVersion
+ *     apply, in ascending version order.
+ *   - Idempotency: a second pass over the same context applies nothing
+ *     (detect() returns false post-apply).
+ *   - Log seam: each applied step prints `migrated <version>: <description>`.
+ */
+
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import runMigrations, { compareVersions, migrations } from '../index.js';
+
+// ---------------------------------------------------------------------------
+// Fixture steps
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a fixture step keyed on a context flag. `detect` returns true only
+ * while the flag is unset; `apply` sets it. This satisfies the idempotency
+ * contract: once applied, detect returns false.
+ *
+ * @param {string} version
+ * @param {string} flag - ctx property the step toggles.
+ * @returns {{ version: string, description: string, detect: Function, apply: Function }}
+ */
+function makeStep(version, flag) {
+  return {
+    version,
+    description: `set ${flag}`,
+    detect: (ctx) => ctx[flag] !== true,
+    apply: (ctx) => {
+      ctx[flag] = true;
+    },
+  };
+}
+
+/** A deliberately out-of-order registry to prove the runner sorts ascending. */
+function fixtureRegistry() {
+  return [
+    makeStep('1.4.0', 'a140'),
+    makeStep('1.2.0', 'a120'),
+    makeStep('1.3.0', 'a130'),
+    makeStep('1.5.0', 'a150'),
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Module shape
+// ---------------------------------------------------------------------------
+
+describe('migrations module exports', () => {
+  it('exports runMigrations as the default function', () => {
+    assert.equal(typeof runMigrations, 'function');
+  });
+
+  it('exports an ordered `migrations` registry array', () => {
+    assert.ok(Array.isArray(migrations));
+  });
+
+  it('ships an empty registry (no real contract break yet)', () => {
+    assert.equal(migrations.length, 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// compareVersions
+// ---------------------------------------------------------------------------
+
+describe('compareVersions', () => {
+  it('orders by major, then minor, then patch', () => {
+    assert.ok(compareVersions('1.2.0', '1.3.0') < 0);
+    assert.ok(compareVersions('2.0.0', '1.9.9') > 0);
+    assert.equal(compareVersions('1.4.0', '1.4.0'), 0);
+    assert.ok(compareVersions('1.4.1', '1.4.0') > 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC — version filtering + ascending order
+// ---------------------------------------------------------------------------
+
+describe('runMigrations — version filtering and ordering', () => {
+  it('applies only steps with fromVersion < version <= toVersion, ascending', () => {
+    const ctx = {};
+    const order = [];
+    const log = (msg) => order.push(msg);
+
+    const result = runMigrations({
+      fromVersion: '1.2.0',
+      toVersion: '1.4.0',
+      ctx,
+      log,
+      registry: fixtureRegistry(),
+    });
+
+    // 1.2.0 == fromVersion → excluded (already in the tree).
+    // 1.5.0 > toVersion → excluded.
+    // 1.3.0 and 1.4.0 apply, in ascending order.
+    assert.deepEqual(result.applied, ['1.3.0', '1.4.0']);
+    assert.deepEqual(order, [
+      'migrated 1.3.0: set a130',
+      'migrated 1.4.0: set a140',
+    ]);
+    assert.equal(ctx.a120, undefined);
+    assert.equal(ctx.a130, true);
+    assert.equal(ctx.a140, true);
+    assert.equal(ctx.a150, undefined);
+  });
+
+  it('includes the step at exactly toVersion (inclusive upper bound)', () => {
+    const ctx = {};
+    const result = runMigrations({
+      fromVersion: '1.2.0',
+      toVersion: '1.5.0',
+      ctx,
+      log: () => {},
+      registry: fixtureRegistry(),
+    });
+    assert.deepEqual(result.applied, ['1.3.0', '1.4.0', '1.5.0']);
+  });
+
+  it('excludes the step at exactly fromVersion (exclusive lower bound)', () => {
+    const ctx = {};
+    const result = runMigrations({
+      fromVersion: '1.3.0',
+      toVersion: '1.5.0',
+      ctx,
+      log: () => {},
+      registry: fixtureRegistry(),
+    });
+    assert.deepEqual(result.applied, ['1.4.0', '1.5.0']);
+    // 1.2.0 and 1.3.0 never ran.
+    assert.equal(ctx.a120, undefined);
+    assert.equal(ctx.a130, undefined);
+  });
+
+  it('applies nothing when the range is empty', () => {
+    const ctx = {};
+    const result = runMigrations({
+      fromVersion: '1.5.0',
+      toVersion: '1.5.0',
+      ctx,
+      log: () => {},
+      registry: fixtureRegistry(),
+    });
+    assert.deepEqual(result.applied, []);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC — idempotency
+// ---------------------------------------------------------------------------
+
+describe('runMigrations — idempotency', () => {
+  it('applies nothing on a second pass over the same context', () => {
+    const ctx = {};
+    const registry = fixtureRegistry();
+    const range = { fromVersion: '1.2.0', toVersion: '1.5.0', ctx, registry };
+
+    const first = runMigrations({ ...range, log: () => {} });
+    assert.deepEqual(first.applied, ['1.3.0', '1.4.0', '1.5.0']);
+
+    const secondLog = [];
+    const second = runMigrations({
+      ...range,
+      log: (msg) => secondLog.push(msg),
+    });
+
+    // Second pass: every in-range step is skipped because detect() now
+    // returns false post-apply.
+    assert.deepEqual(second.applied, []);
+    assert.deepEqual(second.skipped, ['1.3.0', '1.4.0', '1.5.0']);
+    assert.equal(secondLog.length, 0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// AC — log seam
+// ---------------------------------------------------------------------------
+
+describe('runMigrations — log seam', () => {
+  it('prints `migrated <version>: <description>` for each applied step', () => {
+    const lines = [];
+    runMigrations({
+      fromVersion: '1.0.0',
+      toVersion: '1.3.0',
+      ctx: {},
+      log: (msg) => lines.push(msg),
+      registry: [makeStep('1.3.0', 'a130')],
+    });
+    assert.deepEqual(lines, ['migrated 1.3.0: set a130']);
+  });
+
+  it('does not log a step that detect skips', () => {
+    const lines = [];
+    runMigrations({
+      fromVersion: '1.0.0',
+      toVersion: '1.3.0',
+      ctx: { a130: true }, // already applied
+      log: (msg) => lines.push(msg),
+      registry: [makeStep('1.3.0', 'a130')],
+    });
+    assert.deepEqual(lines, []);
+  });
+});

package/lib/migrations/index.js

@@ -0,0 +1,164 @@
+// lib/migrations/index.js
+/**
+ * Version-keyed migration runner.
+ *
+ * A migration is a one-time, version-gated transformation of a consumer
+ * project's on-disk state (config shape, baseline layout, materialized
+ * `.agents/` tree, …). When a consumer upgrades `mandrel` across a
+ * version boundary that changed a contract (see
+ * `.agents/rules/git-conventions.md` § Contract Cutovers), the upgrade path
+ * runs every migration whose `version` falls inside the upgrade range so the
+ * consumer's working tree matches the new release.
+ *
+ * The engine here is deliberately content-free: it owns ordering, version
+ * filtering, idempotency enforcement, and the actionable log line. The
+ * `migrations` registry is the single source of truth for which steps exist
+ * and in what order they run.
+ *
+ * ## Step shape
+ *
+ * Each entry in `migrations` is:
+ *
+ * ```js
+ * {
+ *   version: '1.4.0',                  // semver the step graduates the tree to
+ *   description: 'rename foo to bar',  // short, operator-facing summary
+ *   detect(ctx) { return boolean },    // true ⇒ this step still needs applying
+ *   apply(ctx) { ... },                // perform the change (mutates ctx state)
+ * }
+ * ```
+ *
+ * ## Idempotency contract
+ *
+ * `detect(ctx)` MUST return `false` once `apply(ctx)` has run against the same
+ * context. The runner consults `detect` before every `apply`, so a step whose
+ * change is already present is skipped. This makes a second `runMigrations`
+ * pass over the same context a no-op — the property the unit test asserts.
+ *
+ * ## Version filtering
+ *
+ * `runMigrations({ fromVersion, toVersion, ctx })` applies only steps whose
+ * `version` is strictly greater than `fromVersion` and less than or equal to
+ * `toVersion`, in ascending version order. A step at exactly `fromVersion` is
+ * already in the tree (the consumer was on that version) and is skipped; a
+ * step at exactly `toVersion` is the target and runs.
+ *
+ * The registry currently ships empty: the project sits on the 1.x line under
+ * release-please `always-bump-minor`, and no real config break has landed yet.
+ * The machinery is proven by the fixture steps in
+ * `__tests__/index.test.js`. When the first real contract cutover lands, add
+ * its step here (ascending by version) with an idempotent `detect`/`apply`.
+ */
+
+/**
+ * Ordered registry of migration steps. MUST stay sorted ascending by
+ * `version`. Empty until the first real contract cutover graduates a step
+ * here.
+ *
+ * @type {Array<{
+ *   version: string,
+ *   description: string,
+ *   detect: (ctx: unknown) => boolean,
+ *   apply: (ctx: unknown) => void,
+ * }>}
+ */
+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'`).
+ *
+ * @param {string} version
+ * @returns {[number, number, number]}
+ */
+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,
+  ];
+}
+
+/**
+ * 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.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+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;
+}
+
+/**
+ * Run the version-keyed migrations between two versions.
+ *
+ * Steps are filtered to `fromVersion < version <= toVersion`, sorted ascending
+ * by version, and applied in order. Before each `apply`, the step's `detect`
+ * is consulted: a step whose change is already present (detect returns false)
+ * is skipped, which is what makes a repeat pass a no-op. Every step that
+ * actually applies prints `migrated <version>: <description>` through the
+ * injected `log` seam.
+ *
+ * @param {object} params
+ * @param {string} params.fromVersion - Version the tree is currently on
+ *   (exclusive lower bound).
+ * @param {string} params.toVersion - Version the tree is upgrading to
+ *   (inclusive upper bound).
+ * @param {unknown} params.ctx - Opaque context threaded to each step's
+ *   `detect`/`apply`. Migrations mutate this to record their change.
+ * @param {(message: string) => void} [params.log] - Log seam for the
+ *   actionable per-step line. Defaults to `console.log`. Injected by tests so
+ *   no real stdout write occurs.
+ * @param {Array<{
+ *   version: string,
+ *   description: string,
+ *   detect: (ctx: unknown) => boolean,
+ *   apply: (ctx: unknown) => void,
+ * }>} [params.registry] - Step registry. Defaults to the module `migrations`
+ *   array; injected by tests with fixture steps.
+ * @returns {{ applied: string[], skipped: string[] }} The versions that
+ *   applied and those that were in-range but skipped because `detect` returned
+ *   false.
+ */
+export function runMigrations({
+  fromVersion,
+  toVersion,
+  ctx,
+  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 applied = [];
+  const skipped = [];
+
+  for (const step of inRange) {
+    if (!step.detect(ctx)) {
+      skipped.push(step.version);
+      continue;
+    }
+    step.apply(ctx);
+    log(`migrated ${step.version}: ${step.description}`);
+    applied.push(step.version);
+  }
+
+  return { applied, skipped };
+}
+
+export default runMigrations;