mandrel 1.59.0 → 1.61.0

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);
-  });
-});

package/lib/cli/__tests__/sync-local-zone.test.js

@@ -1,247 +0,0 @@
-// lib/cli/__tests__/sync-local-zone.test.js
-/**
- * Unit tests for the `.agents/local/` sync-exempt local-additions zone
- * (Story #3498, f-drift-local-zone).
- *
- * Contract under test (Story #3498 AC):
- *   1. runSync skips any path under `.agents/local/` when copying the
- *      package payload — proven by pre-populating a consumer-authored
- *      `.agents/local/custom.md` in the destination via an injected fs
- *      seam and asserting it is left byte-identical after a sync.
- *   2. `mandrel sync` writes no file into `.agents/local/` from the package
- *      payload — proven by seeding a (hypothetical) payload file under the
- *      source `.agents/local/` and asserting it is never enumerated, never
- *      copied, and never appears in the dry-run plan.
- *
- * Every test drives runSync through the same injectable seams used by
- * sync.test.js (resolvePackageRoot, fs, cwd, write, writeErr, exit) backed
- * by an in-memory filesystem fake, so no real package resolution and no
- * real disk I/O occur (testing-standards § Unit: all filesystem I/O MUST
- * be mocked; sync.js injectable-seam style — no real child processes).
- */
-
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-
-import { runSync } from '../sync.js';
-
-// ---------------------------------------------------------------------------
-// In-memory filesystem fake (mirrors sync.test.js)
-// ---------------------------------------------------------------------------
-
-/**
- * Build an in-memory fs whose `seed` maps absolute file paths → contents.
- * Directories are inferred from the seeded file paths.
- *
- * Tracks writes (copyFileSync) and guards against symlink creation.
- */
-function makeFs(seed = {}) {
-  const files = new Map(Object.entries(seed));
-  const symlinkCalls = [];
-
-  function dirEntries(dir) {
-    const norm = dir.endsWith(path.sep) ? dir.slice(0, -1) : dir;
-    const children = new Map(); // name → isDir
-    for (const abs of files.keys()) {
-      if (!abs.startsWith(norm + path.sep)) continue;
-      const rest = abs.slice(norm.length + 1);
-      const segments = rest.split(path.sep);
-      const name = segments[0];
-      children.set(name, segments.length > 1);
-    }
-    return [...children.entries()].map(([name, isDir]) => ({
-      name,
-      isDirectory: () => isDir,
-    }));
-  }
-
-  return {
-    files,
-    symlinkCalls,
-    readdirSync(dir, _opts) {
-      return dirEntries(dir);
-    },
-    existsSync(p) {
-      const norm = p.endsWith(path.sep) ? p.slice(0, -1) : p;
-      if (files.has(norm)) return true;
-      for (const abs of files.keys()) {
-        if (abs.startsWith(norm + path.sep)) return true;
-      }
-      return false;
-    },
-    mkdirSync(_dir, _opts) {
-      // No-op: directories are implied by file paths in this fake.
-    },
-    copyFileSync(src, dest) {
-      if (!files.has(src)) {
-        throw new Error(`copyFileSync: source missing ${src}`);
-      }
-      files.set(dest, files.get(src));
-    },
-    symlinkSync(target, p) {
-      symlinkCalls.push({ target, path: p });
-    },
-  };
-}
-
-/** 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;
-    },
-  };
-}
-
-const PROJECT = path.join(path.sep, 'proj');
-const PKG_ROOT = path.join(PROJECT, 'node_modules', 'mandrel');
-const SRC_AGENTS = path.join(PKG_ROOT, '.agents');
-const resolveToPkg = () => PKG_ROOT;
-
-/** Seed a normal package payload of two non-local files under <pkg>/.agents/. */
-function seedPackagePayload() {
-  return {
-    [path.join(SRC_AGENTS, 'instructions.md')]: '# instructions\n',
-    [path.join(SRC_AGENTS, 'rules', 'security-baseline.md')]: '# security\n',
-  };
-}
-
-const baseOpts = (fs, cap) => ({
-  argv: [],
-  resolvePackageRoot: resolveToPkg,
-  fs,
-  cwd: () => PROJECT,
-  write: cap.write,
-  writeErr: cap.writeErr,
-  exit: cap.exit,
-});
-
-// ---------------------------------------------------------------------------
-// AC1 — pre-existing consumer .agents/local/ additions survive sync
-// ---------------------------------------------------------------------------
-
-describe('runSync — .agents/local/ consumer additions survive', () => {
-  it('leaves a pre-existing .agents/local/custom.md untouched', () => {
-    // Arrange: a normal payload plus a consumer-authored file already living
-    // in the destination's local zone.
-    const localAddition = path.join(PROJECT, '.agents', 'local', 'custom.md');
-    const fs = makeFs({
-      ...seedPackagePayload(),
-      [localAddition]: '# my custom local note\n',
-    });
-    const cap = makeCapture();
-
-    // Act
-    const result = runSync(baseOpts(fs, cap));
-
-    // Assert: the local addition is byte-identical and the regular payload
-    // still materialized.
-    assert.equal(fs.files.get(localAddition), '# my custom local note\n');
-    assert.equal(
-      fs.files.get(path.join(PROJECT, '.agents', 'instructions.md')),
-      '# instructions\n',
-    );
-    assert.equal(result.copied, 2);
-    assert.equal(cap.exitCode, null);
-  });
-
-  it('never writes into the destination .agents/local/ subtree', () => {
-    const localAddition = path.join(PROJECT, '.agents', 'local', 'custom.md');
-    const fs = makeFs({
-      ...seedPackagePayload(),
-      [localAddition]: '# my custom local note\n',
-    });
-    const cap = makeCapture();
-
-    runSync(baseOpts(fs, cap));
-
-    // The only destination file under .agents/local/ is the one the consumer
-    // authored; sync added nothing there.
-    const localPrefix = path.join(PROJECT, '.agents', 'local') + path.sep;
-    const localDestFiles = [...fs.files.keys()].filter((k) =>
-      k.startsWith(localPrefix),
-    );
-    assert.deepEqual(localDestFiles, [localAddition]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC2 — a payload file under .agents/local/ is never materialized
-// ---------------------------------------------------------------------------
-
-describe('runSync — payload .agents/local/ is skipped on copy', () => {
-  it('does not copy a source .agents/local/ file into the destination', () => {
-    // Arrange: a payload that (hypothetically) ships a file under local/.
-    // The published payload ships none, but the skip must hold defensively.
-    const srcLocal = path.join(SRC_AGENTS, 'local', 'should-not-copy.md');
-    const fs = makeFs({
-      ...seedPackagePayload(),
-      [srcLocal]: '# payload local file\n',
-    });
-    const cap = makeCapture();
-
-    // Act
-    const result = runSync(baseOpts(fs, cap));
-
-    // Assert: the local payload file was never copied to the destination.
-    const destLocal = path.join(
-      PROJECT,
-      '.agents',
-      'local',
-      'should-not-copy.md',
-    );
-    assert.equal(fs.files.has(destLocal), false);
-    // Only the two non-local payload files were materialized.
-    assert.equal(result.copied, 2);
-  });
-
-  it('omits .agents/local/ paths from the --dry-run plan', () => {
-    const srcLocal = path.join(SRC_AGENTS, 'local', 'should-not-copy.md');
-    const fs = makeFs({
-      ...seedPackagePayload(),
-      [srcLocal]: '# payload local file\n',
-    });
-    const cap = makeCapture();
-
-    const result = runSync({ ...baseOpts(fs, cap), argv: ['--dry-run'] });
-
-    const joined = cap.out.join('');
-    assert.doesNotMatch(joined, /local/);
-    assert.match(joined, /Dry run: 2 file\(s\)/);
-    assert.equal(result.planned, 2);
-  });
-
-  it('still materializes a deeper non-top-level directory named local', () => {
-    // The skip is scoped to the top-level .agents/local/ only — a nested
-    // rules/local/ must still copy.
-    const nestedLocal = path.join(SRC_AGENTS, 'rules', 'local', 'note.md');
-    const fs = makeFs({
-      ...seedPackagePayload(),
-      [nestedLocal]: '# nested local note\n',
-    });
-    const cap = makeCapture();
-
-    const result = runSync(baseOpts(fs, cap));
-
-    const destNested = path.join(
-      PROJECT,
-      '.agents',
-      'rules',
-      'local',
-      'note.md',
-    );
-    assert.equal(fs.files.get(destNested), '# nested local note\n');
-    assert.equal(result.copied, 3);
-  });
-});