mandrel 1.60.0 → 1.62.0

package/lib/cli/version-helpers.js

@@ -0,0 +1,59 @@
+// lib/cli/version-helpers.js
+/**
+ * Shared semver-ish parse and compare helpers used by both
+ * `lib/cli/update.js` and `lib/cli/registry.js`.
+ *
+ * Both files previously defined local copies of `parseVersion` and
+ * `compareVersions`; this module is the single authoritative
+ * implementation (Story #4048 B3 — multiplied helpers).
+ *
+ * Builtins only — this module is imported from both the CLI surface
+ * (`lib/cli/`) and the doctor registry which runs before third-party
+ * packages are guaranteed to be present.
+ */
+
+/**
+ * Parse a dotted semver-ish string into a numeric tuple. Non-numeric or
+ * missing segments coerce to 0 so a partial version still compares sanely.
+ *
+ * @param {string} version
+ * @returns {[number, number, number]}
+ */
+export 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. Negative when `a < b`, zero when equal,
+ * positive 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;
+}
+
+/**
+ * True when `target`'s major axis is strictly greater than `current`'s —
+ * the gated "crosses a major boundary" condition used by the update
+ * orchestrator.
+ *
+ * @param {string} current
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function crossesMajor(current, target) {
+  return parseVersion(target)[0] > parseVersion(current)[0];
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "mandrel",
-  "version": "1.60.0",
+  "version": "1.62.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/"
+    "lib/",
+    "!lib/**/__tests__"
   ],
   "publishConfig": {
     "access": "public",
@@ -84,7 +84,8 @@
     "knip": "^6.14.0",
     "lint-staged": "^17.0.4",
     "markdownlint-cli2": "^0.18.1",
-    "memfs": "^4.57.2"
+    "memfs": "^4.57.2",
+    "typescript": ">=5.0.0"
   },
   "dependencies": {
     "ajv": "^8.20.0",
@@ -93,7 +94,6 @@
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
     "string-argv": "^0.3.2",
-    "typescript": ">=5.0.0",
     "typhonjs-escomplex": "^0.1.0"
   },
   "peerDependencies": {
@@ -101,7 +101,7 @@
   },
   "peerDependenciesMeta": {
     "typescript": {
-      "optional": false
+      "optional": true
     }
   }
 }

package/.agents/workflows/onboard.md

@@ -1,208 +0,0 @@
----
-description: >-
-  Guided first-run onboarding for a freshly installed Mandrel. Detects the
-  consumer stack, offers to scaffold any missing docsContextFiles, runs
-  `mandrel doctor` as a readiness gate, and hands off to a started /plan.
-  The whole path is designed to take about 15 minutes from a clean checkout to
-  a planned Epic.
----
-
-# /onboard
-
-## Role
-
-Onboarding guide. You walk a first-time operator from a freshly installed
-Mandrel to their first planned Epic, composing the building blocks shipped by
-the guided-onboard Feature (#3514): stack detection, docs scaffolding, the
-`mandrel doctor` readiness check, and a started `/plan` handoff.
-
-## Overview
-
-`/onboard` is the **guided first-successful-run path**. It sequences four
-phases that each lean on an already-shipped, independently tested building
-block, then hands the operator off to planning:
-
-```text
-/onboard
-  → Phase 1 — Detect stack          (lib/onboard/detect-stack.js#detectStack)
-  → Phase 2 — Offer docs scaffolding (lib/onboard/scaffold-docs.js#scaffoldDocs)
-  → Phase 3 — Readiness gate         (mandrel doctor → lib/cli/doctor.js)
-  → Phase 4 — Handoff to /plan  (started, not auto-run)
-```
-
-Each phase is **advisory and resumable**: re-running `/onboard` on an
-already-onboarded project re-detects, re-checks, and offers the same handoff
-without duplicating any scaffolding (the scaffolder only writes files that are
-genuinely missing, and `mandrel doctor` is read-only).
-
-### When to use `/onboard`
-
-| Scenario | Command |
-| --- | --- |
-| First run after installing Mandrel into a project | `/onboard` |
-| Plan a new Epic once onboarded | `/plan <epicId>` or `/plan --idea "<seed>"` |
-| Deliver Epic-attached Stories | `/deliver <epicId>` |
-
-## Prerequisites
-
-1. Mandrel installed and bootstrapped into the project. The zero-to-installed
-   path is `npx mandrel init`, which installs the `mandrel`
-   package (when absent), runs `mandrel sync` to materialize the `.agents/`
-   bundle, and then — on the **configure now** prompt option — execs
-   `.agents/scripts/bootstrap.js` to provision the project (labels,
-   board, `.agentrc.json` seed). `/onboard` runs **after** that bootstrap
-   completes — it does not invoke `bootstrap.js` itself, so the coupling is
-   indirect: bootstrap owns first-time provisioning, `/onboard` owns the
-   guided first-successful-run. By the time you reach `/onboard`, the
-   `.agents/` bundle is present and `mandrel` resolves on the `PATH`.
-2. `GITHUB_TOKEN` available in the project's `.env` (Phase 3 checks this; the
-   token value is never echoed).
-
-## The ~15-minute first-successful-run path
-
-`/onboard` is tuned so a brand-new operator can go from a clean checkout to a
-planned Epic in roughly **15 minutes**. The budget breaks down as:
-
-| Step | Phase | Rough budget |
-| --- | --- | --- |
-| Detect the stack and confirm the report | Phase 1 | ~1 min |
-| Review the missing-docs offer and accept the scaffold | Phase 2 | ~3 min |
-| Run `mandrel doctor` and clear any ✘ checks | Phase 3 | ~5 min |
-| Start `/plan` and describe the first Epic idea | Phase 4 | ~6 min |
-
-If any single phase blows its budget — most often a Phase 3 remedy such as
-authenticating `gh` or installing runtime deps — clear that one check and
-re-run `/onboard`; the earlier phases are cheap and idempotent, so re-running
-costs seconds.
-
-### Sample-repo pointer
-
-If you do not have a project to onboard yet and just want to see the path
-end-to-end, point `/onboard` at the **stack-detection sample-repo fixture**
-that ships with the framework. `detectStack` is fixture-driven by design (its
-filesystem facade reads a real directory), and the unit suite exercises it
-against an on-disk sample repo — see
-[`tests/onboard/detect-stack.test.js`](../../tests/onboard/detect-stack.test.js),
-which builds a sample repo with a lockfile, a `package.json`, and source files
-and asserts the detected package manager, test runner, and primary language.
-Use that fixture (or any small throwaway repo with a `package.json` and a few
-source files) as the target for a dry first run before onboarding a real
-project.
-
-## Phase 1 — Detect the stack
-
-Inspect the consumer repository root and report what Mandrel inferred before
-touching anything. Use the detection helper shipped by Story #3520:
-
-```bash
-node -e "import('./.agents/scripts/lib/onboard/detect-stack.js').then(m => console.log(JSON.stringify(m.detectStack(process.cwd()), null, 2)))"
-```
-
-`detectStack(root)` returns `{ packageManager, testRunner, primaryLanguage }`,
-each inferred from on-disk signals (lockfiles, `package.json`, source-file
-extensions) and `null` when no signal is found. Relay the report to the
-operator so they can confirm Mandrel understood the project. Detection is
-**read-only** — it never writes to disk — so a wrong guess is harmless and the
-operator can simply correct course in their `.agentrc.json` later.
-
-## Phase 2 — Offer to scaffold missing `docsContextFiles`
-
-Mandrel agents perform a **mandatory read** of every file listed in
-`project.docsContextFiles` before each task; a missing entry degrades every
-downstream run. Detect which are absent and offer to scaffold stubs, using the
-helper shipped by Story #3519:
-
-1. **Preview (no writes).** Detect the missing set first:
-
-   ```bash
-   node -e "import('./.agents/scripts/lib/onboard/scaffold-docs.js').then(m => console.log(JSON.stringify(m.scaffoldDocs({ write: false }), null, 2)))"
-   ```
-
-   `scaffoldDocs({ write: false })` returns `{ docsRoot, docsContextFiles,
-   missing, present, created }` without creating any files.
-
-2. **Offer.** Show the operator the `missing` list and ask whether to scaffold
-   stubs. If the list is empty, report "all docsContextFiles present" and skip
-   to Phase 3.
-
-3. **Scaffold (on acceptance).** When the operator accepts, write the stubs:
-
-   ```bash
-   node -e "import('./.agents/scripts/lib/onboard/scaffold-docs.js').then(m => console.log(JSON.stringify(m.scaffoldDocs({ write: true }), null, 2)))"
-   ```
-
-   Each missing file is seeded from a dedicated template under
-   `.agents/templates/docs/<name>` when one ships, otherwise from a generic
-   placeholder stub. The operator replaces the stub content with real docs
-   later; the point of the scaffold is that the mandatory-read never resolves
-   to a missing file.
-
-This phase is **idempotent**: the scaffolder only writes files that are
-actually absent, so re-running `/onboard` after a partial scaffold creates
-only the still-missing stubs.
-
-## Phase 3 — Readiness gate (`mandrel doctor`)
-
-Run the doctor as a **readiness gate** before handing off to planning:
-
-```bash
-mandrel doctor
-```
-
-`mandrel doctor` (see [`lib/cli/doctor.js`](../../lib/cli/doctor.js)) runs
-every check in the registry in order — `node-version`, `git-available`,
-`gh-available`, `github-token`, `gh-auth`, `commands-in-sync`, `runtime-deps`,
-`agents-materialized`, `agents-drift`, `version-current` — and prints a
-`✔`/`✘` line per check. Every failing check prints a `→ <remedy>` line, and
-the command exits:
-
-- **0** with `✅  Ready (N/N checks passed)` — proceed to Phase 4.
-- **non-zero** with `❌  Not ready (M/N checks failed)` — **stop**. Work
-  through the `→` remedies (e.g. authenticate `gh`, set `GITHUB_TOKEN`,
-  install runtime deps), then re-run `mandrel doctor` until it is green.
-
-Do **not** hand off to `/plan` while the doctor is red — planning needs a
-working `gh` / `GITHUB_TOKEN` and a materialized `.agents/` bundle, exactly
-what the gate verifies. The `github-token` check never echoes the token value
-(security baseline § Secrets Management).
-
-## Phase 4 — Handoff to a started `/plan`
-
-With a green readiness gate, hand the operator off to planning. `/onboard`
-**starts** the handoff — it surfaces the entry point and the idea-refinement
-path — but does **not** auto-run `/plan`, because Epic planning authors
-GitHub artifacts and must stay under explicit operator control.
-
-Present the operator with the two `/plan` entry shapes:
-
-- **From an idea** (no Epic exists yet):
-
-  ```text
-  /plan --idea "<one-line description of the first thing to build>"
-  ```
-
-  This enters [`/plan`](helpers/plan-epic.md) at Phase 1 (Idea Refinement),
-  which refines the seed into a PRD, Tech Spec, and a decomposed
-  Epic → Story backlog.
-
-- **From an existing Epic** (a `type::epic` issue already exists):
-
-  ```text
-  /plan <epicId>
-  ```
-
-Stop here and let the operator invoke `/plan` themselves. Once they have
-a planned Epic, the natural next step is `/deliver <epicId>` to execute
-it — but that is beyond the onboarding path.
-
-## Constraints
-
-- **Read-before-write.** Phases 1 and 3 are read-only; Phase 2 writes only
-  files that are genuinely missing and only on explicit operator acceptance.
-- **Do not auto-run `/plan`.** Phase 4 starts the handoff; the operator
-  invokes planning. Planning authors GitHub artifacts and stays under human
-  control.
-- **Never echo secrets.** The `github-token` check and any token-related
-  remedy must not print the token value.
-- **Stop on a red doctor.** A non-zero `mandrel doctor` exit blocks the
-  handoff until the operator clears the failing checks.

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

@@ -1,268 +0,0 @@
-// lib/cli/__tests__/migrate.test.js
-/**
- * Unit tests for lib/cli/migrate.js — the standalone `mandrel migrate`
- * subcommand (Story #3505, Epic #3437).
- *
- * Every test drives runMigrate through injectable seams (argv, runMigrations,
- * registry, ctx, write, writeErr, exit). No real filesystem I/O, no real
- * network call, and no shared mutable module state occur (testing-standards
- * § Unit: all external I/O MUST be mocked; pure-logic assertions only).
- *
- * Coverage contract (Story #3505 AC):
- *   - Module shape: runMigrate named export + default function export.
- *   - A live run parses --from/--to out of argv and forwards them to
- *     runMigrations.
- *   - --dry-run reports the steps that WOULD run and invokes no step's apply
- *     and no runMigrations call (writes nothing to disk).
- *   - Missing --from or --to is a usage error (non-zero exit).
- */
-
-import assert from 'node:assert/strict';
-import { describe, it } from 'node:test';
-
-import migrate, { runMigrate } from '../migrate.js';
-
-// ---------------------------------------------------------------------------
-// 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 a fixture registry with `detect`/`apply` recorders so the dry-run
- * (detect only, no apply) and live (detect → apply) paths are both
- * observable. `appliedNeeded` lists the versions whose detect returns true
- * (still needs applying); every other step is treated as already-present.
- */
-function makeFixtureRegistry({ appliedNeeded = ['1.4.0', '1.5.0'] } = {}) {
-  const calls = [];
-  const registry = [
-    { version: '1.3.0', description: 'pre-range step' },
-    { version: '1.4.0', description: 'rename foo to bar' },
-    { version: '1.5.0', description: 'move baseline file' },
-    { version: '1.6.0', description: 'post-range step' },
-  ].map((step) => ({
-    ...step,
-    detect: (_ctx) => {
-      calls.push(`detect:${step.version}`);
-      return appliedNeeded.includes(step.version);
-    },
-    apply: (_ctx) => {
-      calls.push(`apply:${step.version}`);
-    },
-  }));
-  return { registry, calls };
-}
-
-// ---------------------------------------------------------------------------
-// Module shape
-// ---------------------------------------------------------------------------
-
-describe('migrate module exports', () => {
-  it('exports runMigrate as a named export', () => {
-    assert.equal(typeof runMigrate, 'function');
-  });
-
-  it('exports a default function for bin/mandrel.js dispatch', () => {
-    assert.equal(typeof migrate, 'function');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — live run forwards parsed --from/--to to runMigrations
-// ---------------------------------------------------------------------------
-
-describe('runMigrate — live run', () => {
-  it('parses --from/--to and forwards them to runMigrations', () => {
-    const cap = makeCapture();
-    const calls = [];
-    const runMigrations = ({ fromVersion, toVersion }) => {
-      calls.push(`runMigrations:${fromVersion}->${toVersion}`);
-      return { applied: ['1.4.0'], skipped: [] };
-    };
-
-    const result = runMigrate({
-      argv: ['--from', '1.3.0', '--to', '1.5.0'],
-      runMigrations,
-      registry: [],
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.deepEqual(calls, ['runMigrations:1.3.0->1.5.0']);
-    assert.equal(result.ok, true);
-    assert.equal(result.action, 'migrated');
-    assert.deepEqual(result.applied, ['1.4.0']);
-    assert.equal(cap.exitCode, null);
-    assert.match(cap.out.join(''), /Applied 1 migration/);
-  });
-
-  it('accepts the --from=value / --to=value spelling', () => {
-    const cap = makeCapture();
-    const calls = [];
-    const runMigrations = ({ fromVersion, toVersion }) => {
-      calls.push(`runMigrations:${fromVersion}->${toVersion}`);
-      return { applied: [], skipped: [] };
-    };
-
-    runMigrate({
-      argv: ['--from=1.2.0', '--to=1.9.0'],
-      runMigrations,
-      registry: [],
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.deepEqual(calls, ['runMigrations:1.2.0->1.9.0']);
-  });
-
-  it('reports a no-op when no migrations applied', () => {
-    const cap = makeCapture();
-    const runMigrations = () => ({ applied: [], skipped: ['1.4.0'] });
-
-    const result = runMigrate({
-      argv: ['--from', '1.3.0', '--to', '1.5.0'],
-      runMigrations,
-      registry: [],
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.equal(result.ok, true);
-    assert.deepEqual(result.applied, []);
-    assert.match(cap.out.join(''), /no migrations to apply/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — --dry-run reports the plan, invokes no apply, writes nothing
-// ---------------------------------------------------------------------------
-
-describe('runMigrate — --dry-run', () => {
-  it('reports the in-range steps that would apply / be skipped and never applies', () => {
-    const cap = makeCapture();
-    const { registry, calls } = makeFixtureRegistry({
-      // 1.5.0 is in range but already present (detect → false ⇒ would skip).
-      appliedNeeded: ['1.4.0'],
-    });
-    let runnerCalled = false;
-
-    const result = runMigrate({
-      argv: ['--from', '1.3.0', '--to', '1.5.0', '--dry-run'],
-      runMigrations: () => {
-        runnerCalled = true;
-        return { applied: [], skipped: [] };
-      },
-      registry,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    // Range filter is fromVersion < v <= toVersion → only 1.4.0 and 1.5.0.
-    assert.deepEqual(result.wouldApply, ['1.4.0']);
-    assert.deepEqual(result.wouldSkip, ['1.5.0']);
-    assert.equal(result.action, 'dry-run');
-    assert.equal(result.ok, true);
-
-    // Dry-run probes detect on in-range steps only — never apply, never the
-    // live runner.
-    assert.deepEqual(calls, ['detect:1.4.0', 'detect:1.5.0']);
-    assert.equal(runnerCalled, false);
-    assert.ok(!calls.some((c) => c.startsWith('apply:')));
-
-    // Operator-facing plan output.
-    const stdout = cap.out.join('');
-    assert.match(stdout, /dry run v1\.3\.0 → v1\.5\.0/);
-    assert.match(stdout, /would apply {2}1\.4\.0: rename foo to bar/);
-    assert.match(stdout, /would skip {3}1\.5\.0: move baseline file/);
-    assert.match(stdout, /no migrations applied, nothing written/);
-    assert.equal(cap.exitCode, null);
-  });
-
-  it('reports an empty plan when no steps fall in range', () => {
-    const cap = makeCapture();
-    const { registry, calls } = makeFixtureRegistry();
-
-    const result = runMigrate({
-      // 1.6.0 < v <= 1.6.0 leaves only the 1.6.0 step out (exclusive lower);
-      // 9.9.0 → 9.9.0 range catches nothing.
-      argv: ['--from', '9.9.0', '--to', '9.9.0', '--dry-run'],
-      runMigrations: () => ({ applied: [], skipped: [] }),
-      registry,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.deepEqual(result.wouldApply, []);
-    assert.deepEqual(result.wouldSkip, []);
-    assert.deepEqual(calls, []);
-    assert.match(cap.out.join(''), /no migration steps in range/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC — missing bounds are a usage error
-// ---------------------------------------------------------------------------
-
-describe('runMigrate — usage validation', () => {
-  it('exits non-zero when --to is missing', () => {
-    const cap = makeCapture();
-    let runnerCalled = false;
-
-    const result = runMigrate({
-      argv: ['--from', '1.3.0'],
-      runMigrations: () => {
-        runnerCalled = true;
-        return { applied: [], skipped: [] };
-      },
-      registry: [],
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.equal(result.ok, false);
-    assert.equal(result.action, 'usage-error');
-    assert.equal(cap.exitCode, 1);
-    assert.equal(runnerCalled, false);
-    assert.match(cap.err.join(''), /both --from .* and --to .* are required/);
-  });
-
-  it('exits non-zero when --from is missing', () => {
-    const cap = makeCapture();
-
-    const result = runMigrate({
-      argv: ['--to', '1.5.0'],
-      runMigrations: () => ({ applied: [], skipped: [] }),
-      registry: [],
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    assert.equal(result.action, 'usage-error');
-    assert.equal(cap.exitCode, 1);
-  });
-});