@dalzoubi/dev-agents-sync 2.2.6 → 2.2.8

package/README.md

@@ -140,6 +140,8 @@ A blocking hook runs on `PreToolUse`, where exiting 2 denies the tool call and t
 
 **A blocker denies only on a positive match, and fails open on everything else.** An unreadable payload, an unextractable path, or JSON it cannot parse with confidence produces at most one stderr note (for example `warning: handoff-state-guard stood down — <reason>`) and exit 0. A hook is never the reason a session breaks.
 
+**Failing open is never silent.** There is a difference between "the payload said nothing worth denying" and "this gate could not run at all" — a missing `awk`, a payload a hook cannot decode unambiguously. Both exit 0, but the second is a blocker that has quietly stopped blocking, so it always prints one stderr line naming what did not happen and what to do about it. If a blocking hook says nothing, it checked and found nothing wrong.
+
 #### Bypassing a blocking hook
 
 Set `DEV_AGENTS_HOOKS_BYPASS` to a comma-separated list of **exact** hook names to stand those blockers down for the run:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.2.6",
+  "version": "2.2.8",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/tests/e2e/deliver-status-sync.test.mjs

@@ -0,0 +1,433 @@
+/**
+ * tests/e2e/deliver-status-sync.test.mjs
+ *
+ * Slice S5 — Docs + consumer surface.
+ * Spec: docs/specs/260813-deliver-progress-clarity/  (T019, claims AC-20)
+ *
+ * WHAT THIS PROVES (and what it deliberately does not)
+ *
+ * AC-20 has two halves. The content repo's unit suite
+ * (tests/deliver-status-skill.test.mjs) proves the EMISSION half: that
+ * `.agents/skills/deliver-status.md` builds into all four targets. This file
+ * proves the SYNC half: that a consumer running the CLI against that release
+ * actually receives the skill, at each target's own discovery path, with the
+ * managed marker intact and with drift-free `check` afterwards. A skill that
+ * emits but never reaches a consumer ships as nothing.
+ *
+ * DERIVED, NOT PINNED
+ *
+ * The release file map is produced by running the real `scripts/build.mjs`
+ * into a throwaway dist dir and keying every emitted file exactly the way
+ * `fetcher.mjs` keys a release tarball (strip the leading `dist/`). So the
+ * fixture IS the release: if the build ever stops emitting deliver-status to a
+ * target, the map lacks it and this file goes red at the consumer boundary
+ * rather than passing vacuously over a hand-written stand-in. Likewise the
+ * content sentinels are extracted from the canonical skill by regex, and the
+ * Codex bundle is located by scanning every emitted `SKILL.md` — which agent
+ * bundles deliver-status is an implementation decision this test refuses to
+ * pin (the unit suite makes the same refusal, for the same reason).
+ *
+ * The ONE intentional pin is TARGET_DIR below: the release-prefix → consumer-
+ * directory mapping is the CLI's published contract, restated here rather than
+ * imported from writer.mjs so that a silent change to `TARGET_PREFIX` fails
+ * this test instead of being rubber-stamped by it.
+ *
+ * Runs from the monorepo: it reads the content repo at the repo root. If those
+ * sources are absent the test FAILS with a pointer — it never skips, because a
+ * skipped assertion is an assertion that cannot fail.
+ *
+ * Test runner: `npm run test:e2e` (node --test tests/e2e/*.test.mjs)
+ * i18n/accessibility: N/A — CLI-only, no translated strings, no UI surface.
+ */
+
+import { describe, it, before, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  readFileSync,
+  existsSync,
+  rmSync,
+  readdirSync,
+  statSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runInit } from '../../src/commands/init.mjs';
+import { runCheck } from '../../src/commands/check.mjs';
+import { hasMarker } from '../../src/marker.mjs';
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+const BUILD_SCRIPT = path.join(REPO_ROOT, 'scripts', 'build.mjs');
+const CANONICAL_SKILL = path.join(REPO_ROOT, '.agents', 'skills', 'deliver-status.md');
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
+
+/**
+ * Release-key prefix → directory inside the consumer repo. The CLI's published
+ * contract (see writer.mjs TARGET_PREFIX and the README target table); `codex`
+ * keys already carry a repo-root-relative path, so they resolve against ''.
+ */
+const TARGET_DIR = {
+  claude: '.claude',
+  cursor: '.cursor',
+  copilot: '.github',
+  codex: '',
+};
+
+const SYNC_TARGETS = Object.keys(TARGET_DIR);
+
+// ---------------------------------------------------------------------------
+// Release map — built from the real content build, keyed like a release tarball
+// ---------------------------------------------------------------------------
+
+let RELEASE_MAP = null;
+let SENTINELS = null;
+let DELIVER_STATUS_KEYS = null;
+
+function collectInto(map, baseDir, currentDir) {
+  for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+    const full = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      collectInto(map, baseDir, full);
+      continue;
+    }
+    const rel = path.relative(baseDir, full).split(path.sep).join('/');
+    map[rel] = readFileSync(full, 'utf8');
+  }
+}
+
+/**
+ * Runs scripts/build.mjs into a throwaway dist dir and returns the FileMap the
+ * fetcher would hand the CLI for that release. `--no-mirror-root` keeps the
+ * build from touching this repo's worktree.
+ *
+ * Keys outside the four sync targets (`root/`, `steering/`) are kept out of the
+ * map: production drops or re-seeds them elsewhere, and their presence here
+ * would only add stderr noise to an assertion about deliver-status.
+ */
+function buildReleaseMap() {
+  assert.ok(
+    existsSync(BUILD_SCRIPT),
+    `expected the content build at ${BUILD_SCRIPT}.\n` +
+    'This e2e reads the monorepo content sources; run it from a full checkout.',
+  );
+
+  const distDir = mkdtempSync(path.join(tmpdir(), 'das-e2e-deliver-status-dist-'));
+  try {
+    const res = spawnSync(
+      process.execPath,
+      [BUILD_SCRIPT, '--dist-dir', distDir, '--no-mirror-root'],
+      { cwd: REPO_ROOT, encoding: 'utf8' },
+    );
+    assert.equal(
+      res.status,
+      0,
+      'scripts/build.mjs must succeed to produce the release this sync test consumes ' +
+      '(run `npm ci` at the repo root if dependencies are missing).\n' +
+      `stderr:\n${res.stderr ?? ''}`,
+    );
+
+    const all = {};
+    collectInto(all, distDir, distDir);
+
+    const map = {};
+    for (const [key, content] of Object.entries(all)) {
+      if (SYNC_TARGETS.includes(key.split('/')[0])) map[key] = content;
+    }
+    return map;
+  } finally {
+    rmSync(distDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Content sentinels extracted from the canonical skill: the progress-marker
+ * template, the boundary header's remaining-work line, and the artifact path.
+ * Extracted rather than transcribed so a reworded skill updates them for free
+ * and a gutted skill cannot satisfy them.
+ */
+function deriveSentinels() {
+  assert.ok(
+    existsSync(CANONICAL_SKILL),
+    `expected the canonical skill at ${CANONICAL_SKILL}`,
+  );
+  const raw = readFileSync(CANONICAL_SKILL, 'utf8');
+
+  const markerTemplate = raw.match(/^▸ \[<slice-index>.*$/m)?.[0];
+  const remainingLine = raw.match(/^\s*Remaining after this:.*$/m)?.[0]?.trim();
+  const artifactPath = raw.match(/docs\/specs\/<YYMMDD-slug>\/delivery-status\.md/)?.[0];
+
+  assert.ok(markerTemplate, 'canonical skill must define the "▸ [<slice-index>…" marker template');
+  assert.ok(remainingLine, 'canonical skill must define the "Remaining after this:" header line');
+  assert.ok(artifactPath, 'canonical skill must name docs/specs/<YYMMDD-slug>/delivery-status.md');
+
+  return [markerTemplate, remainingLine, artifactPath];
+}
+
+/**
+ * Locates the deliver-status carrier in the release, per target.
+ *
+ * claude/cursor/copilot each emit a standalone `deliver-status.*` file; codex
+ * inlines the skill into some agent's `SKILL.md` bundle. Both are found by
+ * inspection, so neither the file extension nor the bundling agent is pinned.
+ */
+function findDeliverStatusKeys(releaseMap, sentinels) {
+  const byTarget = {};
+  for (const target of SYNC_TARGETS) {
+    const keys = Object.keys(releaseMap)
+      .filter((k) => k.split('/')[0] === target)
+      .filter((k) =>
+        target === 'codex'
+          ? k.endsWith('/SKILL.md') && sentinels.every((s) => releaseMap[k].includes(s))
+          : path.basename(k).startsWith('deliver-status.'),
+      )
+      .sort();
+    byTarget[target] = keys;
+  }
+  return byTarget;
+}
+
+/**
+ * The release keys carrying deliver-status for `target`, asserted non-empty.
+ *
+ * Every loop below goes through this: an empty list would make its enclosing
+ * `for` body vacuous, and a loop that runs zero times is an assertion that
+ * cannot fail. D1 owns the same claim per target; this keeps D2/D3 from
+ * quietly passing on D1's failure.
+ */
+function keysFor(target) {
+  const keys = DELIVER_STATUS_KEYS?.[target] ?? [];
+  assert.ok(
+    keys.length >= 1,
+    `no deliver-status carrier in the built release for target "${target}" — see D1`,
+  );
+  return keys;
+}
+
+/** Maps a release key to its absolute path inside a consumer repo. */
+function consumerPathFor(consumerDir, releaseKey) {
+  const [target, ...rest] = releaseKey.split('/');
+  return path.join(consumerDir, TARGET_DIR[target], ...rest);
+}
+
+function makeFetcher() {
+  return async () => ({ ...RELEASE_MAP });
+}
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-e2e-deliver-status-'));
+}
+
+before(() => {
+  RELEASE_MAP = buildReleaseMap();
+  SENTINELS = deriveSentinels();
+  DELIVER_STATUS_KEYS = findDeliverStatusKeys(RELEASE_MAP, SENTINELS);
+});
+
+// ---------------------------------------------------------------------------
+// D1 — the release the consumer syncs carries deliver-status for every target
+// ---------------------------------------------------------------------------
+
+describe('S5 D1 — deliver-status is present in the built release for all four targets', () => {
+  for (const target of SYNC_TARGETS) {
+    it(`D1 (${target}): the release carries a deliver-status carrier for ${target}`, () => {
+      const keys = DELIVER_STATUS_KEYS[target];
+      assert.ok(
+        keys.length >= 1,
+        `the built release must carry deliver-status for the "${target}" target (AC-20).\n` +
+        `No ${target} release key matched. Keys for this target:\n` +
+        Object.keys(RELEASE_MAP)
+          .filter((k) => k.split('/')[0] === target)
+          .sort()
+          .join('\n'),
+      );
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// D2 — a consumer syncing that release receives it, intact, at each path
+// ---------------------------------------------------------------------------
+
+describe('S5 D2 — init delivers deliver-status into a synced consumer repo', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('D2a: every target\'s deliver-status carrier lands at its consumer discovery path', async () => {
+    await runInit(consumerDir, {
+      targets: [...SYNC_TARGETS],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const target of SYNC_TARGETS) {
+      for (const key of keysFor(target)) {
+        const dest = consumerPathFor(consumerDir, key);
+        assert.ok(
+          existsSync(dest),
+          `init must write the ${target} deliver-status carrier "${key}" to ${dest}`,
+        );
+        assert.ok(
+          statSync(dest).isFile(),
+          `${dest} must be a file`,
+        );
+      }
+    }
+  });
+
+  it('D2b: the delivered bytes are identical to the release entry (no truncation in transit)', async () => {
+    await runInit(consumerDir, {
+      targets: [...SYNC_TARGETS],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const target of SYNC_TARGETS) {
+      for (const key of keysFor(target)) {
+        const dest = consumerPathFor(consumerDir, key);
+        assert.equal(
+          readFileSync(dest, 'utf8'),
+          RELEASE_MAP[key],
+          `${dest} must be byte-identical to release entry "${key}"`,
+        );
+      }
+    }
+  });
+
+  it('D2c: the delivered file carries the managed-by marker (so update manages it, not orphans it)', async () => {
+    await runInit(consumerDir, {
+      targets: [...SYNC_TARGETS],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const target of SYNC_TARGETS) {
+      for (const key of keysFor(target)) {
+        const dest = consumerPathFor(consumerDir, key);
+        assert.ok(
+          hasMarker(readFileSync(dest, 'utf8')),
+          `${dest} must carry the managed-by marker — an unmarked file is consumer-owned ` +
+          'and would never be updated by a later sync',
+        );
+      }
+    }
+  });
+
+  it('D2d: the skill\'s actual content arrives — marker template, boundary header, artifact path', async () => {
+    await runInit(consumerDir, {
+      targets: [...SYNC_TARGETS],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const target of SYNC_TARGETS) {
+      for (const key of keysFor(target)) {
+        const delivered = readFileSync(consumerPathFor(consumerDir, key), 'utf8');
+        for (const sentinel of SENTINELS) {
+          assert.ok(
+            delivered.includes(sentinel),
+            `the ${target} consumer copy of "${key}" must contain the canonical skill's ` +
+            `content, missing: ${JSON.stringify(sentinel)}`,
+          );
+        }
+      }
+    }
+  });
+
+  it('D2e: init reports each deliver-status key among the files it wrote', async () => {
+    const result = await runInit(consumerDir, {
+      targets: [...SYNC_TARGETS],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const written = new Set(result.files ?? []);
+    for (const target of SYNC_TARGETS) {
+      for (const key of keysFor(target)) {
+        assert.ok(
+          written.has(key),
+          `init's reported file list must include "${key}" (reported ${written.size} files)`,
+        );
+      }
+    }
+  });
+
+  it('D2f: check exits 0 on the synced tree (the delivered skill is drift-free)', async () => {
+    await runInit(consumerDir, {
+      targets: [...SYNC_TARGETS],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    let exitCode = 0;
+    try {
+      await runCheck(consumerDir, {
+        fetcher: makeFetcher(),
+        availableTags: ['v2.0.0'],
+      });
+    } catch (err) {
+      exitCode = err.exitCode ?? 1;
+    }
+
+    assert.equal(
+      exitCode,
+      0,
+      'check must exit 0 immediately after init — a freshly synced deliver-status must not read as drift',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// D3 — target scoping: a single-target consumer gets its copy and only its copy
+// ---------------------------------------------------------------------------
+
+describe('S5 D3 — deliver-status respects target scoping', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('D3a: --targets claude delivers the claude copy and none of the other targets\' copies', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    for (const key of keysFor('claude')) {
+      assert.ok(
+        existsSync(consumerPathFor(consumerDir, key)),
+        `a claude-only consumer must receive "${key}"`,
+      );
+    }
+
+    for (const target of SYNC_TARGETS.filter((t) => t !== 'claude')) {
+      for (const key of keysFor(target)) {
+        assert.ok(
+          !existsSync(consumerPathFor(consumerDir, key)),
+          `a claude-only consumer must NOT receive the ${target} copy "${key}"`,
+        );
+      }
+    }
+  });
+});