mandrel 1.57.0

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

@@ -0,0 +1,247 @@
+// 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

@@ -0,0 +1,372 @@
+// 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);
+  });
+});