@dalzoubi/dev-agents-sync 2.0.28 → 2.2.0

package/tests/hooks-summary-line.test.mjs

@@ -0,0 +1,595 @@
+/**
+ * tests/hooks-summary-line.test.mjs
+ *
+ * Spec: docs/specs/260805-hooks-wave-2/ — AC-8 (UX notes):
+ *
+ *   "`init`/`update` extend the existing hooks summary line to the new count —
+ *    `hooks/ installed (8 scripts)` after this wave, with the number derived
+ *    from the installed set, never a hard-coded literal — and the existing
+ *    wiring line; `--dry-run` and exit-code contracts unchanged."
+ *
+ * Behavior anchors (§7) — each would fail if the behavior broke:
+ *
+ *  A1. init emits a hooks summary line whose count equals the number of hook
+ *      scripts that run installed.
+ *  A2. update emits the same line, same derivation.
+ *  A3. The count TRACKS THE INSTALLED SET: three different fetchers shipping
+ *      different hook counts produce three different numbers. This is the test
+ *      that fails if anyone re-pins a literal into the line.
+ *  A4. Singular is handled — one installed script reads "1 script", not
+ *      "1 scripts".
+ *  A5. A run that installs no hook scripts emits no hooks summary line.
+ *  A6. The wiring line reports the settings.json merge, with a registration
+ *      count derived from the CLI's own registration table (a script the table
+ *      does not know about is installed but not counted as registered).
+ *  A7. --no-hooks-wiring reports the SKIP instead of claiming a merge.
+ *  A8. --dry-run emits neither line (planning is not doing) and still returns
+ *      the plan — the dry-run contract is unchanged.
+ *  A9. Neither line changes an exit code: the summary is informational only and
+ *      a failing run still throws with its own exitCode.
+ *
+ * The lines go to stderr, the same stream as the sibling `steering/ …` and
+ * `pruned N retired hook registration(s)` lines, so stdout stays parseable.
+ *
+ * All tests use isolated tmp dirs and never touch the real repo.
+ */
+
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runInit } from '../src/commands/init.mjs';
+import { runUpdate } from '../src/commands/update.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+import { DEFAULT_HOOK_SCRIPTS } from '../src/settings.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(baseDir, full, map, prefix);
+    } else {
+      const rel = path.relative(baseDir, full).replace(/\\/g, '/');
+      map[`${prefix}/${rel}`] = readFileSync(full, 'utf8');
+    }
+  }
+}
+
+/** Every hook script name the CLI's registration table knows about. */
+const REGISTERED_HOOK_NAMES = DEFAULT_HOOK_SCRIPTS.map((h) => path.basename(h.command));
+
+function hookBody(name) {
+  return `#!/bin/sh\n# managed-by: dev-agents-sync v9.9.9\n# ${name}\nexit 0\n`;
+}
+
+/**
+ * Builds a claude-target FileMap carrying exactly `hookNames` hook scripts.
+ * The hook set is a PARAMETER so the tests can vary it — that is what proves
+ * the reported count is derived rather than pinned.
+ */
+function fileMapWithHooks(hookNames) {
+  const map = {};
+  const targetDir = path.join(FIXTURE_DIR, 'claude');
+  if (existsSync(targetDir)) collectFiles(targetDir, targetDir, map, 'claude');
+  for (const name of hookNames) {
+    map[`claude/hooks/${name}`] = hookBody(name);
+  }
+  return map;
+}
+
+function fetcherWithHooks(hookNames) {
+  return async () => fileMapWithHooks(hookNames);
+}
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-hooks-summary-'));
+}
+
+/** Seeds a pre-initialized consumer repo so `update` has a lockfile to read. */
+function setupInitializedRepo(consumerDir, { resolvedVersion = '1.0.0' } = {}) {
+  writeLockfile(consumerDir, {
+    source: 'github:dalzoubi/dev-agents',
+    range: '^1',
+    resolvedVersion,
+    targets: ['claude'],
+    lastUpdated: '2026-08-05T00:00:00Z',
+  });
+  const agentsDir = path.join(consumerDir, '.claude', 'agents');
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(
+    path.join(agentsDir, 'define.md'),
+    readFileSync(path.join(FIXTURE_DIR, 'claude', 'agents', 'define.md'), 'utf8'),
+    'utf8',
+  );
+}
+
+/** Captures everything written to stderr while `fn` runs. */
+async function captureStderr(fn) {
+  const origWrite = process.stderr.write.bind(process.stderr);
+  let captured = '';
+  process.stderr.write = (chunk) => {
+    captured += typeof chunk === 'string' ? chunk : chunk.toString();
+    return true;
+  };
+  try {
+    await fn();
+  } finally {
+    process.stderr.write = origWrite;
+  }
+  return captured;
+}
+
+/**
+ * Pulls the installed-count out of the hooks summary line, or null when the
+ * line is absent. Matching the number generically (not against an expected
+ * literal) is deliberate: the assertions compare it to a count the test
+ * DERIVES, so a wrong number fails with the real number in the message.
+ */
+function installedCountFrom(stderr) {
+  const m = /hooks\/ installed \((\d+) scripts?\)/.exec(stderr);
+  return m ? Number(m[1]) : null;
+}
+
+// ---------------------------------------------------------------------------
+// A1 / A2 — the line exists and its count equals the installed set
+// ---------------------------------------------------------------------------
+
+describe('AC-8 hooks summary line — count equals the installed set', () => {
+  let consumerDir;
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('A1: init reports exactly the number of hook scripts it installed', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    const onDisk = readdirSync(path.join(consumerDir, '.claude', 'hooks'))
+      .filter((f) => f.endsWith('.sh'));
+    assert.equal(
+      installedCountFrom(stderr),
+      onDisk.length,
+      `init's hooks summary must report the number of scripts it wrote to ` +
+        `.claude/hooks/ (${onDisk.length}); stderr was:\n${stderr}`,
+    );
+  });
+
+  it('A2: update reports exactly the number of hook scripts it installed', async () => {
+    setupInitializedRepo(consumerDir);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    const onDisk = readdirSync(path.join(consumerDir, '.claude', 'hooks'))
+      .filter((f) => f.endsWith('.sh'));
+    assert.equal(
+      installedCountFrom(stderr),
+      onDisk.length,
+      `update's hooks summary must report the number of scripts it wrote to ` +
+        `.claude/hooks/ (${onDisk.length}); stderr was:\n${stderr}`,
+    );
+  });
+
+  it('A2b: the reported count equals the lockfile-recorded hooks list', async () => {
+    // Second derivation of the same truth: the lockfile records the installed
+    // hook paths, so the summary and the lockfile must agree by construction.
+    setupInitializedRepo(consumerDir);
+    let result;
+    const stderr = await captureStderr(async () => {
+      result = await runUpdate(consumerDir, {
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      });
+    });
+
+    assert.equal(
+      installedCountFrom(stderr),
+      result.hooks.length,
+      `summary count must equal the installed hook path list the run recorded; ` +
+        `stderr was:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// A3 — the count is DERIVED: vary the shipped set, the number follows
+// ---------------------------------------------------------------------------
+
+describe('AC-8 hooks summary line — count is derived, never a literal', () => {
+  let consumerDir;
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  // Three shipped sets of DIFFERENT sizes. Any implementation that prints a
+  // pinned number fails at least two of these — which is the whole point: this
+  // wave already burned three fixes on hard-coded hook counts.
+  const shippedSets = [
+    REGISTERED_HOOK_NAMES.slice(0, 2),
+    REGISTERED_HOOK_NAMES.slice(0, 4),
+    REGISTERED_HOOK_NAMES,
+  ];
+
+  for (const hookNames of shippedSets) {
+    it(`A3: a version shipping ${hookNames.length} hook scripts reports ${hookNames.length}`, async () => {
+      const stderr = await captureStderr(() =>
+        runInit(consumerDir, {
+          targets: ['claude'],
+          fetcher: fetcherWithHooks(hookNames),
+          availableTags: AVAILABLE_TAGS,
+        }),
+      );
+
+      assert.equal(
+        installedCountFrom(stderr),
+        hookNames.length,
+        `the summary count must follow the shipped hook set, not a pinned ` +
+          `literal; stderr was:\n${stderr}`,
+      );
+    });
+  }
+
+  it('A3b: a hook script the registration table does not know about still counts as installed', async () => {
+    // The count comes from what was INSTALLED, not from the registration table.
+    const hookNames = [...REGISTERED_HOOK_NAMES, 'future-unregistered-hook.sh'];
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks(hookNames),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.equal(
+      installedCountFrom(stderr),
+      hookNames.length,
+      `installed count must be derived from the installed scripts, not from ` +
+        `DEFAULT_HOOK_SCRIPTS; stderr was:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// A4 / A5 — singular, and silence when nothing was installed
+// ---------------------------------------------------------------------------
+
+describe('AC-8 hooks summary line — singular and empty cases', () => {
+  let consumerDir;
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('A4: one installed script reads "1 script", not "1 scripts"', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks([REGISTERED_HOOK_NAMES[0]]),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.match(
+      stderr,
+      /hooks\/ installed \(1 script\)/,
+      `singular must be handled; stderr was:\n${stderr}`,
+    );
+  });
+
+  it('A5: a run that installs no hook scripts emits no hooks summary line', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks([]),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.equal(
+      installedCountFrom(stderr),
+      null,
+      `with no hook scripts shipped there is nothing to summarize; ` +
+        `stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !/hooks\/ (wired|settings\.json wiring skipped|nothing to wire)/.test(stderr),
+      `the wiring line is paired with the summary and must stay silent too; ` +
+        `stderr was:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// A6 / A7 — the wiring line
+// ---------------------------------------------------------------------------
+
+describe('AC-8 wiring line', () => {
+  let consumerDir;
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('A6: init reports the settings.json merge with a derived registration count', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.ok(
+      existsSync(path.join(consumerDir, '.claude', 'settings.json')),
+      'precondition: the wiring line only makes sense if settings.json was written',
+    );
+    assert.match(
+      stderr,
+      new RegExp(
+        `hooks/ wired into \\.claude/settings\\.json \\(${REGISTERED_HOOK_NAMES.length} registrations\\)`,
+      ),
+      `wiring line must report the registrations the CLI actually made ` +
+        `(${REGISTERED_HOOK_NAMES.length}); stderr was:\n${stderr}`,
+    );
+  });
+
+  it('A6b: an unregistered script is installed but not counted as a registration', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks([...REGISTERED_HOOK_NAMES, 'future-unregistered-hook.sh']),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    // Installed count includes it; registration count does not.
+    assert.equal(installedCountFrom(stderr), REGISTERED_HOOK_NAMES.length + 1);
+    assert.match(
+      stderr,
+      new RegExp(
+        `hooks/ wired into \\.claude/settings\\.json \\(${REGISTERED_HOOK_NAMES.length} registrations\\)`,
+      ),
+      `registration count must come from the CLI's own table, so it can never ` +
+        `claim a registration the merge did not make; stderr was:\n${stderr}`,
+    );
+  });
+
+  it('A6c: scripts the registration table knows nothing about report "nothing to wire"', async () => {
+    // A content tag can ship a hook the installed CLI predates. The scripts land,
+    // but the CLI registers nothing — and must not claim otherwise.
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks(['future-unregistered-hook.sh']),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.equal(installedCountFrom(stderr), 1, `stderr was:\n${stderr}`);
+    assert.match(
+      stderr,
+      /hooks\/ nothing to wire into \.claude\/settings\.json/,
+      `with no registrable script the wiring line must say so rather than ` +
+        `report a merge; stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !/hooks\/ wired into/.test(stderr),
+      `must not claim a merge it did not make; stderr was:\n${stderr}`,
+    );
+  });
+
+  it('A7: --no-hooks-wiring reports the skip instead of claiming a merge', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        noHooksWiring: true,
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.match(
+      stderr,
+      /hooks\/ settings\.json wiring skipped \(--no-hooks-wiring\)/,
+      `--no-hooks-wiring must be reported, so a consumer knows the scripts are ` +
+        `on disk but inert; stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !/hooks\/ wired into/.test(stderr),
+      `a skipped merge must never be reported as wired; stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !existsSync(path.join(consumerDir, '.claude', 'settings.json')),
+      '--no-hooks-wiring must not create settings.json',
+    );
+    // The install half still happened and is still reported.
+    assert.equal(installedCountFrom(stderr), REGISTERED_HOOK_NAMES.length);
+  });
+
+  it('A7b: update --no-hooks-wiring reports the skip too', async () => {
+    setupInitializedRepo(consumerDir);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        noHooksWiring: true,
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.match(
+      stderr,
+      /hooks\/ settings\.json wiring skipped \(--no-hooks-wiring\)/,
+      `update must report the skip as well as init; stderr was:\n${stderr}`,
+    );
+    assert.ok(!/hooks\/ wired into/.test(stderr));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// A8 / A9 — --dry-run and exit-code contracts unchanged
+// ---------------------------------------------------------------------------
+
+describe('AC-8 — --dry-run and exit-code contracts unchanged', () => {
+  let consumerDir;
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('A8: init --dry-run emits neither line and still returns the plan', async () => {
+    let result;
+    const stderr = await captureStderr(async () => {
+      result = await runInit(consumerDir, {
+        targets: ['claude'],
+        dryRun: true,
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      });
+    });
+
+    assert.equal(
+      installedCountFrom(stderr),
+      null,
+      `--dry-run installs nothing, so it must not report an install ` +
+        `(planning is not doing); stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !/hooks\/ (wired into|settings\.json wiring skipped|nothing to wire)/.test(stderr),
+      `--dry-run must not report a wiring outcome; stderr was:\n${stderr}`,
+    );
+    assert.equal(result.dryRun, true, 'the dry-run result contract is unchanged');
+    assert.ok(
+      result.files.some((k) => k.startsWith('claude/hooks/')),
+      'the dry-run plan still lists the hook scripts it would install',
+    );
+    assert.ok(
+      !existsSync(path.join(consumerDir, '.claude', 'hooks')),
+      '--dry-run must write nothing',
+    );
+  });
+
+  it('A8b: update --dry-run emits neither line and still returns the plan', async () => {
+    setupInitializedRepo(consumerDir);
+
+    let result;
+    const stderr = await captureStderr(async () => {
+      result = await runUpdate(consumerDir, {
+        dryRun: true,
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      });
+    });
+
+    assert.equal(installedCountFrom(stderr), null, `stderr was:\n${stderr}`);
+    assert.ok(
+      !/hooks\/ (wired into|settings\.json wiring skipped|nothing to wire)/.test(stderr),
+      `stderr was:\n${stderr}`,
+    );
+    assert.equal(result.dryRun, true, 'the dry-run result contract is unchanged');
+    assert.ok(
+      !existsSync(path.join(consumerDir, '.claude', 'hooks')),
+      '--dry-run must write nothing',
+    );
+  });
+
+  it('A9: the summary lines are informational — a refused overwrite still fails with exit code 1', async () => {
+    // An unmanaged collision must still abort with its documented exitCode, and
+    // must abort BEFORE any hooks summary is printed (nothing was installed).
+    const hooksDir = path.join(consumerDir, '.claude', 'hooks');
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(
+      path.join(hooksDir, REGISTERED_HOOK_NAMES[0]),
+      '#!/bin/sh\n# consumer-authored, no marker\nexit 0\n',
+      'utf8',
+    );
+
+    let thrown = null;
+    const stderr = await captureStderr(async () => {
+      try {
+        await runInit(consumerDir, {
+          targets: ['claude'],
+          fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+          availableTags: AVAILABLE_TAGS,
+        });
+      } catch (err) {
+        thrown = err;
+      }
+    });
+
+    assert.ok(thrown, 'an unmanaged collision must still throw');
+    assert.equal(thrown.exitCode, 1, 'the documented exit code is unchanged');
+    assert.equal(
+      installedCountFrom(stderr),
+      null,
+      `a run that aborted before writing must not claim an install; ` +
+        `stderr was:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Stream discipline — the lines share the sibling informational stream
+// ---------------------------------------------------------------------------
+
+describe('AC-8 — summary lines go to stderr alongside their siblings', () => {
+  let consumerDir;
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('both lines use the `info: dev-agents-sync:` stderr prefix, like steering/ and the prune line', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    const lines = stderr.split('\n');
+    const summaryLine = lines.find((l) => l.includes('hooks/ installed ('));
+    const wiringLine = lines.find((l) => l.includes('hooks/ wired into'));
+
+    assert.ok(summaryLine, `expected a hooks summary line; stderr was:\n${stderr}`);
+    assert.ok(wiringLine, `expected a hooks wiring line; stderr was:\n${stderr}`);
+    assert.match(summaryLine, /^info: dev-agents-sync: /);
+    assert.match(wiringLine, /^info: dev-agents-sync: /);
+    // Sanity: the sibling steering line shares the same prefix and stream.
+    assert.match(stderr, /^info: dev-agents-sync: steering\//m);
+  });
+
+  it('the install line precedes the wiring line (reported in the order it happened)', async () => {
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: fetcherWithHooks(REGISTERED_HOOK_NAMES),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.ok(
+      stderr.indexOf('hooks/ installed (') < stderr.indexOf('hooks/ wired into'),
+      `scripts land on disk before they are registered; stderr was:\n${stderr}`,
+    );
+  });
+});