@dalzoubi/dev-agents-sync 1.0.14 → 1.0.16

package/tests/first-sync-notice.test.mjs

@@ -0,0 +1,459 @@
+/**
+ * tests/first-sync-notice.test.mjs
+ *
+ * Tests for the first-sync notice emitted to stderr when a root-targeted file
+ * (e.g. CONSTITUTION.md) is written for the first time.
+ *
+ * Expected notice format (single line, newline-terminated):
+ *   info: dev-agents-sync: created <path> (new in v<resolvedTag>; see release notes)\n
+ *
+ * where:
+ *   <path>         — consumer-relative path (e.g. "CONSTITUTION.md")
+ *   <resolvedTag>  — resolved tag string without leading `v` prefix prepended;
+ *                    resolveRange returns e.g. "1.0.0" so the notice reads "v1.0.0"
+ *
+ * Rules under test:
+ *   1. Root file created for first time → notice emitted to stderr
+ *   2. Root file already exists (update run) → no notice
+ *   3. --dry-run → no notice (file not written, no notice)
+ *   4. Non-root file (e.g. .claude/agents/define.md) → no notice
+ *   5. Notice format exactly matches the spec
+ */
+
+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';
+
+// ---------------------------------------------------------------------------
+// Fixture helpers
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+function collectFiles(baseDir, currentDir, map, prefix) {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    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');
+    }
+  }
+}
+
+function buildFixtureFileMap(targets = ['claude', 'cursor', 'root']) {
+  const map = {};
+  for (const t of targets) {
+    const targetDir = path.join(FIXTURE_DIR, t);
+    if (!existsSync(targetDir)) continue;
+    collectFiles(targetDir, targetDir, map, t);
+  }
+  return map;
+}
+
+/** Fetcher that returns all targets at v1.0.0 */
+function makeFullFetcher() {
+  return async () => buildFixtureFileMap(['claude', 'cursor', 'root']);
+}
+
+/**
+ * Fetcher that returns a file map where all marker versions are bumped to v1.1.0,
+ * simulating an upgrade. Used for update-path tests.
+ */
+function makeV110Fetcher() {
+  return async () => {
+    const base = buildFixtureFileMap(['claude', 'cursor', 'root']);
+    const out = {};
+    for (const [key, content] of Object.entries(base)) {
+      out[key] = content.replace(/v1\.0\.0/g, 'v1.1.0');
+    }
+    return out;
+  };
+}
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-notice-test-'));
+}
+
+/**
+ * Captures all output written to process.stderr.write during the execution of
+ * `fn`. Returns the concatenated string.
+ *
+ * Matches the same capture pattern used in root-target.test.mjs.
+ */
+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;
+}
+
+// ---------------------------------------------------------------------------
+// 1. Root file created for the first time → notice emitted on stderr
+// ---------------------------------------------------------------------------
+
+describe('first-sync notice — init: root file created for first time', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('emits a notice to stderr when CONSTITUTION.md is created for the first time via init', async () => {
+    // CONSTITUTION.md must NOT exist before the run
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+      }),
+    );
+
+    assert.ok(
+      stderr.includes('info: dev-agents-sync: created CONSTITUTION.md'),
+      `expected notice for CONSTITUTION.md in stderr, got:\n${stderr}`,
+    );
+  });
+
+  it('emits a notice to stderr when CONSTITUTION.md is created for the first time via update', async () => {
+    // Set up lockfile but deliberately do NOT write CONSTITUTION.md
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+    // Write the claude agent file so update has a managed file to work with
+    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',
+    );
+
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        fetcher: makeV110Fetcher(),
+        availableTags: ['v1.0.0', 'v1.1.0'],
+      }),
+    );
+
+    assert.ok(
+      stderr.includes('info: dev-agents-sync: created CONSTITUTION.md'),
+      `expected notice for CONSTITUTION.md in stderr on update, got:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Root file already exists → no notice on subsequent runs
+// ---------------------------------------------------------------------------
+
+describe('first-sync notice — no notice when root file already exists', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('does not emit a notice when CONSTITUTION.md already exists (init with managed file)', async () => {
+    // Pre-write CONSTITUTION.md with a managed-by marker on the first line
+    writeFileSync(
+      path.join(consumerDir, 'CONSTITUTION.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'root', 'CONSTITUTION.md'), 'utf8'),
+      'utf8',
+    );
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+      }),
+    );
+
+    assert.ok(
+      !stderr.includes('info: dev-agents-sync: created CONSTITUTION.md'),
+      `expected no first-sync notice when file already existed, got:\n${stderr}`,
+    );
+  });
+
+  it('does not emit a notice when CONSTITUTION.md already exists (update run)', async () => {
+    // Set up a fully initialized consumer with CONSTITUTION.md present
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+    writeFileSync(
+      path.join(consumerDir, 'CONSTITUTION.md'),
+      readFileSync(path.join(FIXTURE_DIR, 'root', 'CONSTITUTION.md'), 'utf8'),
+      'utf8',
+    );
+    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',
+    );
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        fetcher: makeV110Fetcher(),
+        availableTags: ['v1.0.0', 'v1.1.0'],
+      }),
+    );
+
+    assert.ok(
+      !stderr.includes('info: dev-agents-sync: created CONSTITUTION.md'),
+      `expected no first-sync notice when file already existed on update, got:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. --dry-run → no notice
+// ---------------------------------------------------------------------------
+
+describe('first-sync notice — suppressed on --dry-run', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('does not emit a notice during a dry-run init even when file would be new', async () => {
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+        dryRun: true,
+      }),
+    );
+
+    assert.ok(
+      !stderr.includes('info: dev-agents-sync: created CONSTITUTION.md'),
+      `expected no notice on dry-run, got:\n${stderr}`,
+    );
+  });
+
+  it('does not write CONSTITUTION.md during dry-run (verifying dry-run is genuine)', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFullFetcher(),
+      availableTags: ['v1.0.0'],
+      dryRun: true,
+    });
+
+    assert.ok(
+      !existsSync(path.join(consumerDir, 'CONSTITUTION.md')),
+      'dry-run must not write any files',
+    );
+  });
+
+  it('does not emit a notice during a dry-run update even when file would be new', async () => {
+    // Lockfile exists but CONSTITUTION.md does not
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        fetcher: makeV110Fetcher(),
+        availableTags: ['v1.0.0', 'v1.1.0'],
+        dryRun: true,
+      }),
+    );
+
+    assert.ok(
+      !stderr.includes('info: dev-agents-sync: created CONSTITUTION.md'),
+      `expected no notice on dry-run update, got:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Non-root file → no notice
+// ---------------------------------------------------------------------------
+
+describe('first-sync notice — not emitted for non-root files', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('does not emit a notice when only .claude/agents/define.md is newly created', async () => {
+    // Use a fetcher that only returns claude/ files (no root/)
+    const claudeOnlyFetcher = async () => buildFixtureFileMap(['claude']);
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: claudeOnlyFetcher,
+        availableTags: ['v1.0.0'],
+      }),
+    );
+
+    assert.ok(
+      !stderr.includes('info: dev-agents-sync: created'),
+      `expected no first-sync notice for non-root files, got:\n${stderr}`,
+    );
+  });
+
+  it('does not emit a notice for .cursor/ files newly created during init', async () => {
+    const cursorOnlyFetcher = async () => buildFixtureFileMap(['cursor']);
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['cursor'],
+        fetcher: cursorOnlyFetcher,
+        availableTags: ['v1.0.0'],
+      }),
+    );
+
+    assert.ok(
+      !stderr.includes('info: dev-agents-sync: created'),
+      `expected no first-sync notice for cursor/ files, got:\n${stderr}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Exact notice format
+// ---------------------------------------------------------------------------
+
+describe('first-sync notice — exact format', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('notice matches exact format: info: dev-agents-sync: created <path> (new in v<resolvedTag>; see release notes)', async () => {
+    // resolveRange(['v1.0.0'], '^1') returns '1.0.0' (no leading v)
+    // so the notice must contain "v1.0.0" (the `v` is prepended in the message)
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+      }),
+    );
+
+    const expectedNotice =
+      'info: dev-agents-sync: created CONSTITUTION.md (new in v1.0.0; see release notes)\n';
+
+    assert.ok(
+      stderr.includes(expectedNotice),
+      `notice format mismatch.\nExpected to find:\n  ${JSON.stringify(expectedNotice)}\nIn stderr:\n  ${JSON.stringify(stderr)}`,
+    );
+  });
+
+  it('notice uses the consumer-relative path (not the relKey root/ prefix, not the abs path)', async () => {
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runInit(consumerDir, {
+        targets: ['claude'],
+        fetcher: makeFullFetcher(),
+        availableTags: ['v1.0.0'],
+      }),
+    );
+
+    // Must NOT contain the internal relKey prefix
+    assert.ok(
+      !stderr.includes('root/CONSTITUTION.md'),
+      `notice must not expose internal relKey format "root/CONSTITUTION.md", got:\n${stderr}`,
+    );
+
+    // Must NOT contain an absolute path
+    assert.ok(
+      !stderr.includes(consumerDir),
+      `notice must not expose absolute path, got:\n${stderr}`,
+    );
+
+    // Must contain the bare consumer-relative path
+    assert.ok(
+      stderr.includes('CONSTITUTION.md'),
+      `notice must include consumer-relative path "CONSTITUTION.md", got:\n${stderr}`,
+    );
+  });
+
+  it('notice includes the resolved tag version with v prefix for update path', async () => {
+    // Update from 1.0.0 → 1.1.0; CONSTITUTION.md does not exist yet
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00: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',
+    );
+
+    assert.ok(!existsSync(path.join(consumerDir, 'CONSTITUTION.md')), 'precondition: file must not exist');
+
+    const stderr = await captureStderr(() =>
+      runUpdate(consumerDir, {
+        fetcher: makeV110Fetcher(),
+        availableTags: ['v1.0.0', 'v1.1.0'],
+      }),
+    );
+
+    // resolveRange(['v1.0.0', 'v1.1.0'], '^1') → '1.1.0'
+    const expectedNotice =
+      'info: dev-agents-sync: created CONSTITUTION.md (new in v1.1.0; see release notes)\n';
+
+    assert.ok(
+      stderr.includes(expectedNotice),
+      `notice must show resolved tag v1.1.0.\nExpected:\n  ${JSON.stringify(expectedNotice)}\nGot:\n  ${JSON.stringify(stderr)}`,
+    );
+  });
+});

package/tests/fixtures/release-v1.0.0/root/CONSTITUTION.md

@@ -0,0 +1,117 @@
+<!-- managed-by: dev-agents-sync v1.0.0 -->
+# Constitution
+Constitution version: v1
+
+These 14 principles are binding across all agents and all consumer repos.
+
+---
+
+## §1 — Spec before code
+
+**Rule:** No non-trivial change ships without a written spec.
+
+**Rationale:** Reviewing intent before code is cheaper than reviewing code without intent.
+
+---
+
+## §2 — Smallest reviewable change
+
+**Rule:** Prefer the smallest diff that proves the behavior; split anything larger into ordered slices.
+
+**Rationale:** Small diffs review faster and revert cleanly.
+
+---
+
+## §3 — Reuse before invention
+
+**Rule:** Before adding a new component, pattern, or utility, search for an existing one and prefer extending it.
+
+**Rationale:** Duplication is the most expensive consistency bug.
+
+---
+
+## §4 — Explicit over implicit
+
+**Rule:** Name what's happening instead of relying on convention or inference.
+
+**Rationale:** Clever inference is fragile across humans, agents, and refactors.
+
+---
+
+## §5 — Fail loud, recover gracefully
+
+**Rule:** Detect failure at the boundary, log with structured context, surface a generic actionable message to the user, and never swallow the error silently.
+
+**Rationale:** Silent failure is the longest-running production bug.
+
+---
+
+## §6 — Observability is a feature
+
+**Rule:** Every meaningful path emits a structured log with a correlation ID.
+
+**Rationale:** Logs without structure or correlation are an archive, not a tool.
+
+---
+
+## §7 — Tests prove behavior, not coverage
+
+**Rule:** Write tests that fail when the behavior breaks; coverage percentage is a proxy, not the goal.
+
+**Rationale:** Coverage-chasing produces brittle tests that survive bugs.
+
+---
+
+## §8 — Backward compatibility is load-bearing
+
+**Rule:** Changes to lockfile schemas, marker formats, public APIs, and DB migrations are versioned, additive when possible, and reversible.
+
+**Rationale:** Breaking it without a migration story breaks every consumer at once.
+
+---
+
+## §9 — Determinism over cleverness
+
+**Rule:** Same inputs, same outputs — no timestamps, random ordering, or environment-dependent state in generated artifacts.
+
+**Rationale:** Determinism makes diffs reviewable and drift detectable.
+
+---
+
+## §10 — Boring tools, sharp edges where it matters
+
+**Rule:** Default to the well-understood library or pattern; reserve novelty for the place where it actually pays for its complexity.
+
+**Rationale:** Novelty everywhere is a velocity tax.
+
+---
+
+## §11 — User data is sacred
+
+**Rule:** Collect the minimum, store it briefly, log it never, and have a written deletion plan from day one.
+
+**Rationale:** Privacy is a one-way ratchet.
+
+---
+
+## §12 — Errors are UX
+
+**Rule:** Every user-facing error has a generic translated message, a stable error code, and a clear next action; raw stacks never reach the user.
+
+**Rationale:** A bad error message is a product bug.
+
+---
+
+## §13 — Comments explain why
+
+**Rule:** Code says what; comments say why, especially for non-obvious tradeoffs and load-bearing constraints.
+
+**Rationale:** "What" decays under refactor; "why" is what the next maintainer actually needs.
+
+---
+
+## §14 — Disagreement is part of the job
+
+**Rule:** When a requirement is weak, ambiguous, or wrong, say so plainly and propose the alternative; do not rubber-stamp.
+
+**Rationale:** Agreement-by-default produces specs that fail in implementation.