mandrel 1.60.0 → 1.62.0

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

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

@@ -1,372 +0,0 @@
-// lib/cli/__tests__/sync.test.js
-/**
- * Unit tests for lib/cli/sync.js — the `mandrel sync` materializer.
- *
- * Every test drives runSync through injectable seams (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).
- *
- * Coverage contract (per Story #3467 AC):
- *   1. Copies the package .agents/ tree into ./.agents/ as plain files
- *      (no symlinks created — symlinkSync is never called).
- *   2. Re-running is idempotent — a second run leaves ./.agents/
- *      byte-identical.
- *   3. Exits non-zero with an actionable message when mandrel is
- *      not resolvable in node_modules.
- *   4. --dry-run reports planned copies and writes nothing.
- *   5. Module shape: runSync named export + default function export.
- */
-
-import assert from 'node:assert/strict';
-import path from 'node:path';
-import { describe, it } from 'node:test';
-
-import sync, { runSync } from '../sync.js';
-
-// ---------------------------------------------------------------------------
-// In-memory filesystem fake
-// ---------------------------------------------------------------------------
-
-/**
- * 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 so tests
- * can prove the materializer never produces symlinks.
- */
-function makeFs(seed = {}) {
-  // Live store: absolute path → contents. Seeded entries plus anything the
-  // code under test writes via copyFileSync.
-  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;
-      // A directory "exists" if any seeded file lives under it.
-      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');
-
-/** Seed a package payload of two files under <pkg>/.agents/. */
-function seedPackagePayload() {
-  const agentsDir = path.join(PKG_ROOT, '.agents');
-  return {
-    [path.join(agentsDir, 'instructions.md')]: '# instructions\n',
-    [path.join(agentsDir, 'rules', 'security-baseline.md')]: '# security\n',
-  };
-}
-
-const resolveToPkg = () => PKG_ROOT;
-
-// ---------------------------------------------------------------------------
-// Module shape
-// ---------------------------------------------------------------------------
-
-describe('sync module exports', () => {
-  it('exports runSync as a named export', () => {
-    assert.equal(typeof runSync, 'function');
-  });
-
-  it('exports a default function for bin/mandrel.js dispatch', () => {
-    assert.equal(typeof sync, 'function');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC1 — copies the tree as plain files, no symlinks
-// ---------------------------------------------------------------------------
-
-describe('runSync — copies .agents/ payload as plain files', () => {
-  it('copies every package file into ./.agents/', () => {
-    const fs = makeFs(seedPackagePayload());
-    const cap = makeCapture();
-    const result = runSync({
-      argv: [],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-
-    const destInstr = path.join(PROJECT, '.agents', 'instructions.md');
-    const destRule = path.join(
-      PROJECT,
-      '.agents',
-      'rules',
-      'security-baseline.md',
-    );
-    assert.equal(fs.files.get(destInstr), '# instructions\n');
-    assert.equal(fs.files.get(destRule), '# security\n');
-    assert.equal(result.copied, 2);
-    assert.equal(cap.exitCode, null);
-  });
-
-  it('never creates a symlink', () => {
-    const fs = makeFs(seedPackagePayload());
-    const cap = makeCapture();
-    runSync({
-      argv: [],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(fs.symlinkCalls.length, 0);
-  });
-
-  it('reports the materialized file count on stdout', () => {
-    const fs = makeFs(seedPackagePayload());
-    const cap = makeCapture();
-    runSync({
-      argv: [],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.match(cap.out.join(''), /Materialized 2 file\(s\)/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC2 — idempotency
-// ---------------------------------------------------------------------------
-
-describe('runSync — idempotent re-run', () => {
-  it('leaves ./.agents/ byte-identical after a second run', () => {
-    const fs = makeFs(seedPackagePayload());
-    const opts = {
-      argv: [],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: () => {},
-      writeErr: () => {},
-      exit: () => {},
-    };
-
-    runSync(opts);
-    // Snapshot the destination tree after the first run.
-    const destPrefix = path.join(PROJECT, '.agents') + path.sep;
-    const snapshot = JSON.stringify(
-      [...fs.files.entries()].filter(([k]) => k.startsWith(destPrefix)).sort(),
-    );
-
-    runSync(opts);
-    const after = JSON.stringify(
-      [...fs.files.entries()].filter(([k]) => k.startsWith(destPrefix)).sort(),
-    );
-
-    assert.equal(after, snapshot);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC3 — missing package → non-zero exit with actionable message
-// ---------------------------------------------------------------------------
-
-describe('runSync — mandrel not resolvable', () => {
-  function resolveThrows() {
-    const err = new Error("Cannot find module 'mandrel/package.json'");
-    err.code = 'MODULE_NOT_FOUND';
-    throw err;
-  }
-
-  it('exits non-zero', () => {
-    const fs = makeFs();
-    const cap = makeCapture();
-    runSync({
-      argv: [],
-      resolvePackageRoot: resolveThrows,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(cap.exitCode, 1);
-  });
-
-  it('emits an actionable message naming the package and install command', () => {
-    const fs = makeFs();
-    const cap = makeCapture();
-    runSync({
-      argv: [],
-      resolvePackageRoot: resolveThrows,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    const joined = cap.err.join('');
-    assert.match(joined, /mandrel/);
-    assert.match(joined, /npm install mandrel/);
-  });
-
-  it('writes nothing to the destination', () => {
-    const fs = makeFs();
-    const cap = makeCapture();
-    runSync({
-      argv: [],
-      resolvePackageRoot: resolveThrows,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(fs.files.size, 0);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC3b — package resolvable but ships no .agents/ payload
-// ---------------------------------------------------------------------------
-
-describe('runSync — package present but no .agents/ payload', () => {
-  it('exits non-zero with an actionable message', () => {
-    // Seed a package whose only file is its package.json (no .agents/ tree).
-    const fs = makeFs({
-      [path.join(PKG_ROOT, 'package.json')]: '{}',
-    });
-    const cap = makeCapture();
-    runSync({
-      argv: [],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(cap.exitCode, 1);
-    assert.match(cap.err.join(''), /no .agents\/ payload/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// AC4 — --dry-run reports planned copies, writes nothing
-// ---------------------------------------------------------------------------
-
-describe('runSync — --dry-run', () => {
-  it('writes nothing to the destination', () => {
-    const fs = makeFs(seedPackagePayload());
-    const cap = makeCapture();
-    const before = fs.files.size;
-    runSync({
-      argv: ['--dry-run'],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    // No new files written: store size is unchanged from the seed.
-    assert.equal(fs.files.size, before);
-  });
-
-  it('reports the planned copies and a dry-run summary', () => {
-    const fs = makeFs(seedPackagePayload());
-    const cap = makeCapture();
-    const result = runSync({
-      argv: ['--dry-run'],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    const joined = cap.out.join('');
-    assert.match(joined, /would copy/);
-    assert.match(joined, /instructions\.md/);
-    assert.match(joined, /Dry run: 2 file\(s\)/);
-    assert.equal(result.planned, 2);
-    assert.equal(result.copied, 0);
-  });
-
-  it('does not call exit on the dry-run happy path', () => {
-    const fs = makeFs(seedPackagePayload());
-    const cap = makeCapture();
-    runSync({
-      argv: ['--dry-run'],
-      resolvePackageRoot: resolveToPkg,
-      fs,
-      cwd: () => PROJECT,
-      write: cap.write,
-      writeErr: cap.writeErr,
-      exit: cap.exit,
-    });
-    assert.equal(cap.exitCode, null);
-  });
-});