@dalzoubi/dev-agents-sync 2.0.27 → 2.1.0

package/tests/update-uptodate-wiring.test.mjs

@@ -0,0 +1,484 @@
+/**
+ * tests/update-uptodate-wiring.test.mjs
+ *
+ * Finding M5 (gate-3 re-run, hooks wave 2): `update`'s up-to-date short-circuit
+ * deliberately performs the settings.json hook merge (so hook adoption is not
+ * gated on a version bump) but reported NOTHING — for a consumer already pinned
+ * to the latest tag who had never had hooks wired, that is a genuine first-time
+ * write to consumer-owned state with zero output, contradicting hooks.mjs's own
+ * "wiring edits consumer-owned state, so it is never silent (§6)".
+ *
+ * Behavior anchors (§7) — each would fail if the behavior broke:
+ *
+ *  U1.  A first-time wiring on the up-to-date path reports the wiring line, and
+ *       the registration count is DERIVED from the hook scripts on disk.
+ *  U1b. Vary the scripts on disk, the number follows (never a pinned literal).
+ *  U1c. The branch does NOT claim an install: it installs nothing, so
+ *       `hooks/ installed (N scripts)` must stay absent (AC-8).
+ *  U2.  A repeat `update` on the same path is an idempotent no-op and stays
+ *       SILENT — the line reports what this run actually did, not standing state.
+ *  U2b. Nothing on disk and nothing to prune → no write, no line.
+ *  U3.  --dry-run emits nothing and writes nothing (planning is not doing).
+ *  U4.  --no-hooks-wiring performs no merge on this path, so it claims nothing;
+ *  U4b. and the install path still reports the skip (unchanged).
+ *  U5.  Exit-code contracts unchanged: the happy path returns `upToDate` without
+ *       throwing, and a malformed settings.json still fails loud with
+ *       ESETTINGS_PARSE / exitCode 1, byte-identical file, no wiring line.
+ *  U6.  The short-circuit still performs no fetch.
+ *
+ * No assertion pins a hook COUNT: every expected number is derived from
+ * DEFAULT_HOOK_SCRIPTS and the scripts the test itself seeded (AC-8).
+ *
+ * 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 } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { runUpdate } from '../src/commands/update.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+import { DEFAULT_HOOK_SCRIPTS } from '../src/settings.mjs';
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+// The version `^1` resolves to out of AVAILABLE_TAGS. Pinning the lockfile here
+// is what puts `update` on the up-to-date short-circuit instead of a fetch.
+const LATEST_IN_RANGE = '1.2.0';
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-uptodate-wiring-'));
+}
+
+/**
+ * A fetcher that fails the test if it is ever called. The short-circuit's whole
+ * point is to avoid a fetch, so this doubles as the U6 anchor.
+ */
+function noFetchFetcher() {
+  return async () => {
+    throw new Error('the up-to-date short-circuit must not fetch');
+  };
+}
+
+/** Minimal claude-target FileMap carrying only hook scripts, for the install path. */
+function fetcherWithHooks(registrations) {
+  return async () => {
+    const map = {};
+    for (const { command } of registrations) {
+      map[command.replace(/^\.claude\//, 'claude/')] = hookBody(path.basename(command));
+    }
+    return map;
+  };
+}
+
+function hookBody(name) {
+  return `#!/bin/sh\n# managed-by: dev-agents-sync v9.9.9\n# ${name}\nexit 0\n`;
+}
+
+/** Seeds a lockfile already pinned to `resolvedVersion` (default: the latest in range). */
+function setupPinnedRepo(consumerDir, { resolvedVersion = LATEST_IN_RANGE } = {}) {
+  writeLockfile(consumerDir, {
+    source: 'github:dalzoubi/dev-agents',
+    range: '^1',
+    resolvedVersion,
+    targets: ['claude'],
+    lastUpdated: '2026-08-05T00:00:00Z',
+  });
+}
+
+/**
+ * Writes the hook scripts for `registrations` into .claude/hooks/ — simulating a
+ * consumer whose scripts an earlier `update` already installed but whose
+ * settings.json was never wired.
+ *
+ * Returns the number of registrations the CLI's own table yields for the scripts
+ * now on disk. DERIVED from DEFAULT_HOOK_SCRIPTS, never a literal (AC-8): one
+ * command registered under two events would count twice, and the expected number
+ * follows the table the moment a hook is added or retired.
+ */
+function seedHookScripts(consumerDir, registrations) {
+  const commands = new Set(registrations.map((h) => h.command));
+  for (const command of commands) {
+    const abs = path.join(consumerDir, command);
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, hookBody(path.basename(command)), 'utf8');
+  }
+  return DEFAULT_HOOK_SCRIPTS.filter((h) => commands.has(h.command)).length;
+}
+
+/** 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 registration count out of the wiring line, or null when the line is
+ * absent. Matched generically so a wrong number fails with the real number.
+ */
+function wiredCountFrom(stderr) {
+  const m = /hooks\/ wired into \.claude\/settings\.json \((\d+) registrations?\)/.exec(stderr);
+  return m ? Number(m[1]) : null;
+}
+
+function settingsPathIn(consumerDir) {
+  return path.join(consumerDir, '.claude', 'settings.json');
+}
+
+// ---------------------------------------------------------------------------
+// U1 — a first-time wiring on the up-to-date path is reported
+// ---------------------------------------------------------------------------
+
+describe('M5 — update up-to-date path: a first-time settings.json wiring is never silent', () => {
+  let consumerDir;
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('U1: an up-to-date consumer whose hooks were never wired gets the wiring reported', async () => {
+    setupPinnedRepo(consumerDir);
+    const expected = seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+    assert.ok(
+      !existsSync(settingsPathIn(consumerDir)),
+      'precondition: this consumer has never had hooks wired',
+    );
+
+    let result;
+    const stderr = await captureStderr(async () => {
+      result = await runUpdate(consumerDir, {
+        fetcher: noFetchFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    });
+
+    assert.equal(
+      result.upToDate,
+      true,
+      `this test must exercise the up-to-date short-circuit; got: ${JSON.stringify(result)}`,
+    );
+    assert.ok(
+      existsSync(settingsPathIn(consumerDir)),
+      'the short-circuit performed a real first-time write to settings.json',
+    );
+    assert.equal(
+      wiredCountFrom(stderr),
+      expected,
+      `a genuine first-time write to consumer-owned state must be reported (§6), with the ` +
+        `registration count derived from the scripts on disk (${expected}); stderr was:\n${stderr}`,
+    );
+  });
+
+  it('U1b: the reported registration count follows the scripts on disk, never a literal', async () => {
+    // A consumer who only ever installed a subset (e.g. an older content tag).
+    const subset = DEFAULT_HOOK_SCRIPTS.slice(0, 2);
+    setupPinnedRepo(consumerDir);
+    const expected = seedHookScripts(consumerDir, subset);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: noFetchFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    assert.equal(
+      wiredCountFrom(stderr),
+      expected,
+      `the count must follow the hook scripts present on disk, not the full table and not a ` +
+        `pinned number; stderr was:\n${stderr}`,
+    );
+    assert.notEqual(
+      expected,
+      DEFAULT_HOOK_SCRIPTS.length,
+      'precondition: the subset must differ from the full table for this test to bite',
+    );
+  });
+
+  it('U1c: the branch reports the wiring but never claims an install', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: noFetchFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    assert.ok(wiredCountFrom(stderr) !== null, `expected a wiring line; stderr was:\n${stderr}`);
+    assert.ok(
+      !/hooks\/ installed \(/.test(stderr),
+      `this branch installs nothing — claiming "hooks/ installed (N scripts)" for scripts an ` +
+        `earlier run wrote would be a count this run did not earn; stderr was:\n${stderr}`,
+    );
+  });
+
+  it('U1d: the wiring line shares the info: dev-agents-sync: stderr prefix of its siblings', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: noFetchFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    const wiringLine = stderr.split('\n').find((l) => l.includes('hooks/ wired into'));
+    assert.ok(wiringLine, `expected a wiring line; stderr was:\n${stderr}`);
+    assert.match(wiringLine, /^info: dev-agents-sync: /);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// U2 — a repeat no-op run stays silent
+// ---------------------------------------------------------------------------
+
+describe('M5 — update up-to-date path: an idempotent no-op stays silent', () => {
+  let consumerDir;
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('U2: a second up-to-date update writes nothing and reports no wiring', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    const firstStderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: noFetchFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+    assert.ok(
+      wiredCountFrom(firstStderr) !== null,
+      `precondition: the first run must report the wiring; stderr was:\n${firstStderr}`,
+    );
+    const afterFirst = readFileSync(settingsPathIn(consumerDir), 'utf8');
+
+    const secondStderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: noFetchFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    assert.equal(
+      wiredCountFrom(secondStderr),
+      null,
+      `the merge is idempotent, so a repeat run changed nothing and must say nothing — the ` +
+        `line reports what THIS run did, not standing state; stderr was:\n${secondStderr}`,
+    );
+    assert.equal(
+      readFileSync(settingsPathIn(consumerDir), 'utf8'),
+      afterFirst,
+      'a repeat run must leave settings.json byte-identical',
+    );
+  });
+
+  it('U2b: an up-to-date consumer with no hook scripts and nothing to prune stays silent', async () => {
+    setupPinnedRepo(consumerDir);
+    mkdirSync(path.join(consumerDir, '.claude', 'hooks'), { recursive: true });
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, { fetcher: noFetchFetcher(), availableTags: AVAILABLE_TAGS }),
+    );
+
+    assert.ok(
+      !/hooks\/ (wired into|nothing to wire|settings\.json wiring skipped)/.test(stderr),
+      `nothing was written, so nothing is reported (no spurious line on every run); ` +
+        `stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !existsSync(settingsPathIn(consumerDir)),
+      'a no-op merge must not create settings.json',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// U3 / U4 — --dry-run and --no-hooks-wiring
+// ---------------------------------------------------------------------------
+
+describe('M5 — update up-to-date path: --dry-run and --no-hooks-wiring contracts', () => {
+  let consumerDir;
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('U3: --dry-run on a never-wired consumer emits nothing and writes nothing', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    let result;
+    const stderr = await captureStderr(async () => {
+      result = await runUpdate(consumerDir, {
+        dryRun: true,
+        fetcher: noFetchFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      });
+    });
+
+    assert.ok(
+      !/hooks\/ (wired into|nothing to wire|settings\.json wiring skipped)/.test(stderr),
+      `--dry-run wires nothing, so it must report no wiring outcome (planning is not doing); ` +
+        `stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !existsSync(settingsPathIn(consumerDir)),
+      '--dry-run must not create settings.json',
+    );
+    assert.equal(result.upToDate, true, 'the up-to-date result contract is unchanged');
+  });
+
+  it('U3b: --dry-run leaves an already-present settings.json byte-identical', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+    const before = JSON.stringify({ env: { EXAMPLE: '1' } }, null, 2) + '\n';
+    writeFileSync(settingsPathIn(consumerDir), before, 'utf8');
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        dryRun: true,
+        fetcher: noFetchFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.equal(
+      readFileSync(settingsPathIn(consumerDir), 'utf8'),
+      before,
+      '--dry-run must never write to settings.json',
+    );
+    assert.equal(wiredCountFrom(stderr), null, `stderr was:\n${stderr}`);
+  });
+
+  it('U4: --no-hooks-wiring on this path merges nothing and claims nothing', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        noHooksWiring: true,
+        fetcher: noFetchFetcher(),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.ok(
+      !/hooks\/ (wired into|nothing to wire)/.test(stderr),
+      `an opted-out run must never be reported as wired; stderr was:\n${stderr}`,
+    );
+    assert.ok(
+      !existsSync(settingsPathIn(consumerDir)),
+      '--no-hooks-wiring must not create settings.json',
+    );
+  });
+
+  it('U4b: --no-hooks-wiring still reports the skip on the install path', async () => {
+    // Regression guard for the sibling branch: the install path installs scripts
+    // that are left inert, which the consumer must be told about.
+    setupPinnedRepo(consumerDir, { resolvedVersion: '1.0.0' });
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        noHooksWiring: true,
+        fetcher: fetcherWithHooks(DEFAULT_HOOK_SCRIPTS),
+        availableTags: AVAILABLE_TAGS,
+      }),
+    );
+
+    assert.match(
+      stderr,
+      /hooks\/ settings\.json wiring skipped \(--no-hooks-wiring\)/,
+      `scripts landed on disk but inert — the consumer must be told; stderr was:\n${stderr}`,
+    );
+    assert.ok(!/hooks\/ wired into/.test(stderr), `stderr was:\n${stderr}`);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// U5 / U6 — exit codes and the no-fetch guarantee
+// ---------------------------------------------------------------------------
+
+describe('M5 — update up-to-date path: exit codes and no-fetch unchanged', () => {
+  let consumerDir;
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('U5: a wiring run still resolves with the up-to-date result (no exit-code change)', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    const result = await runUpdate(consumerDir, {
+      fetcher: noFetchFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.equal(result.upToDate, true);
+    assert.equal(result.resolvedVersion, LATEST_IN_RANGE);
+    assert.deepEqual(result.prunedRetired, [], 'nothing retired was present to prune');
+    assert.match(result.message, /already up to date/);
+  });
+
+  it('U5b: a malformed settings.json still fails loud with ESETTINGS_PARSE and no wiring line', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+    mkdirSync(path.join(consumerDir, '.claude'), { recursive: true });
+    const malformed = '{ not json';
+    writeFileSync(settingsPathIn(consumerDir), malformed, 'utf8');
+
+    let thrown = null;
+    const stderr = await captureStderr(async () => {
+      try {
+        await runUpdate(consumerDir, {
+          fetcher: noFetchFetcher(),
+          availableTags: AVAILABLE_TAGS,
+        });
+      } catch (err) {
+        thrown = err;
+      }
+    });
+
+    assert.ok(thrown, 'a malformed settings.json must still throw on this path');
+    assert.equal(thrown.code, 'ESETTINGS_PARSE', 'the stable error code is unchanged');
+    assert.equal(thrown.exitCode, 1, 'the documented exit code is unchanged');
+    assert.equal(
+      readFileSync(settingsPathIn(consumerDir), 'utf8'),
+      malformed,
+      'the consumer file is left byte-identical (no partial write)',
+    );
+    assert.equal(
+      wiredCountFrom(stderr),
+      null,
+      `a run that wrote nothing must not claim a wiring; stderr was:\n${stderr}`,
+    );
+  });
+
+  it('U6: the short-circuit performs no fetch', async () => {
+    setupPinnedRepo(consumerDir);
+    seedHookScripts(consumerDir, DEFAULT_HOOK_SCRIPTS);
+
+    let fetched = false;
+    const result = await runUpdate(consumerDir, {
+      fetcher: async () => {
+        fetched = true;
+        return {};
+      },
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.equal(result.upToDate, true);
+    assert.equal(fetched, false, 'the up-to-date branch must not fetch to wire hooks');
+  });
+});