@dalzoubi/dev-agents-sync 1.0.26 → 2.0.1

package/tests/claudeMd.test.mjs

@@ -0,0 +1,910 @@
+/**
+ * tests/claudeMd.test.mjs
+ *
+ * Tests for the `claudeMd` helper (packages/dev-agents-sync/src/claudeMd.mjs)
+ * and the CLAUDE.md injection behaviour wired into `init` and `update`.
+ *
+ * ALL tests in this file are intentionally RED until the production helper is
+ * implemented. The import of `../src/claudeMd.mjs` is the first thing that
+ * will fail; `init`/`update` tests will fail because the helper doesn't exist
+ * yet and the commands don't call it.
+ *
+ * Fenced block format (from the slice spec):
+ *   <!-- dev-agents:auto-route:start managed-by: dev-agents-sync vX.Y.Z -->
+ *   ...routing rules content...
+ *   <!-- dev-agents:auto-route:end -->
+ *
+ * The content injected is the body of `.claude/skills/auto-route.md` from the
+ * release at the resolved version.  The version in the start-marker matches
+ * the CLI package version from `packages/dev-agents-sync/package.json`.
+ *
+ * Behaviour contract:
+ *   1. inject into empty file — creates CLAUDE.md and writes fenced block
+ *   2. inject into file with prose — appends fenced block; existing prose untouched
+ *   3. replace stale block — updates block in-place; prose above/below untouched
+ *   4. skip when current — no write when block already matches
+ *   5. dry-run — returns planned diff, no file write
+ *   6. malformed block (start marker present, end marker missing) — warns to
+ *      stderr and skips rather than corrupting the file
+ */
+
+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 { fileURLToPath } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Production module under test — will fail with MODULE_NOT_FOUND until
+// the implement agent creates src/claudeMd.mjs.
+// ---------------------------------------------------------------------------
+
+import {
+  injectClaudeMd,
+  buildFencedBlock,
+  parseExistingBlock,
+  START_MARKER_PREFIX,
+  END_MARKER,
+} from '../src/claudeMd.mjs';
+
+// ---------------------------------------------------------------------------
+// Command-level imports for integration tests
+// ---------------------------------------------------------------------------
+
+import { runInit } from '../src/commands/init.mjs';
+import { runUpdate } from '../src/commands/update.mjs';
+import { writeLockfile } from '../src/lockfile.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const FIXTURE_DIR = path.join(__dirname, 'fixtures', 'release-v1.0.0');
+
+// The version recorded in the fenced start-marker comes from the CLI package.
+const CLI_VERSION = JSON.parse(
+  readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'),
+).version;
+
+// Minimal routing content for test fixtures (does not need to match the real
+// file exactly — we just need deterministic content).
+const SAMPLE_ROUTING_CONTENT = '## Routing\n\nRoute `fix` → `implement`.';
+
+// A well-formed fenced block using the sample content and CLI_VERSION.
+function makeFencedBlock(version = CLI_VERSION, content = SAMPLE_ROUTING_CONTENT) {
+  return [
+    `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v${version} -->`,
+    content,
+    `<!-- dev-agents:auto-route:end -->`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir() {
+  return mkdtempSync(path.join(tmpdir(), 'das-claudemd-test-'));
+}
+
+/**
+ * Captures all output written to process.stderr.write during the execution of
+ * `fn`. Returns the concatenated string.
+ */
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Fixture fetcher helpers (mirrors init.test.mjs / update.test.mjs patterns)
+// ---------------------------------------------------------------------------
+
+import { readdirSync } from 'node:fs';
+
+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']) {
+  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;
+}
+
+/**
+ * A fixture fetcher that also injects a synthetic `skills/auto-route.md` into
+ * the claude target so the CLAUDE.md injection logic has content to pull from.
+ */
+function makeFixtureFetcherWithAutoRoute(routingContent = SAMPLE_ROUTING_CONTENT) {
+  return async (_repo, _tag, _token) => {
+    const base = buildFixtureFileMap(['claude', 'cursor']);
+    // Inject the auto-route skill so claudeMd.mjs can find it.
+    base['claude/skills/auto-route.md'] = routingContent;
+    return base;
+  };
+}
+
+const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0'];
+
+// ===========================================================================
+// Unit tests — claudeMd helper
+// ===========================================================================
+
+// ---------------------------------------------------------------------------
+// buildFencedBlock
+// ---------------------------------------------------------------------------
+
+describe('buildFencedBlock', () => {
+  it('returns a string that starts with the start marker', () => {
+    const block = buildFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    const expectedStart = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v${CLI_VERSION} -->`;
+    assert.ok(
+      block.startsWith(expectedStart),
+      `expected block to start with start marker, got:\n${block}`,
+    );
+  });
+
+  it('returns a string that ends with the end marker', () => {
+    const block = buildFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    assert.ok(
+      block.trimEnd().endsWith('<!-- dev-agents:auto-route:end -->'),
+      `expected block to end with end marker, got:\n${block}`,
+    );
+  });
+
+  it('includes the routing content between the markers', () => {
+    const block = buildFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    assert.ok(
+      block.includes(SAMPLE_ROUTING_CONTENT),
+      `expected routing content to appear in block, got:\n${block}`,
+    );
+  });
+
+  it('embeds the version in the start marker', () => {
+    const block = buildFencedBlock('2.3.4', SAMPLE_ROUTING_CONTENT);
+    assert.ok(
+      block.includes('v2.3.4'),
+      `expected version v2.3.4 in block, got:\n${block}`,
+    );
+  });
+
+  it('exported START_MARKER_PREFIX matches the prefix used in buildFencedBlock output', () => {
+    const block = buildFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    const firstLine = block.split('\n')[0];
+    assert.ok(
+      firstLine.startsWith(START_MARKER_PREFIX),
+      `expected first line to start with START_MARKER_PREFIX "${START_MARKER_PREFIX}", got:\n${firstLine}`,
+    );
+  });
+
+  it('exported END_MARKER matches the trailing marker in buildFencedBlock output', () => {
+    const block = buildFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    const lines = block.split('\n');
+    const lastNonEmpty = [...lines].reverse().find((l) => l.trim().length > 0);
+    assert.equal(
+      lastNonEmpty,
+      END_MARKER,
+      `expected last non-empty line to equal END_MARKER`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseExistingBlock — extracts start-marker version from file content
+// ---------------------------------------------------------------------------
+
+describe('parseExistingBlock', () => {
+  it('returns null when no block is present in the file', () => {
+    const content = '# My CLAUDE.md\n\nSome prose.';
+    assert.equal(parseExistingBlock(content), null);
+  });
+
+  it('returns an object with version and full block text when a well-formed block is present', () => {
+    const block = makeFencedBlock('1.2.3');
+    const content = `# CLAUDE.md\n\n${block}\n\nTrailing prose.`;
+    const result = parseExistingBlock(content);
+    assert.ok(result !== null, 'expected non-null result for a file with a block');
+    assert.equal(result.version, '1.2.3');
+    assert.ok(typeof result.block === 'string', 'expected result.block to be a string');
+  });
+
+  it('returns { malformed: true } when start marker is present but end marker is missing', () => {
+    const startMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v1.0.0 -->`;
+    const content = `# CLAUDE.md\n\n${startMarker}\nContent without end marker.`;
+    const result = parseExistingBlock(content);
+    assert.ok(result !== null, 'expected non-null result for malformed block');
+    assert.equal(result.malformed, true, 'expected result.malformed to be true');
+  });
+
+  it('returns the version from the start marker accurately', () => {
+    const block = makeFencedBlock('9.9.9');
+    const result = parseExistingBlock(block);
+    assert.equal(result?.version, '9.9.9');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// injectClaudeMd — core logic
+// ---------------------------------------------------------------------------
+
+describe('injectClaudeMd — inject into empty/non-existent file', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('creates CLAUDE.md when the file does not exist', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    assert.ok(!existsSync(claudeMdPath), 'precondition: CLAUDE.md must not exist');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    assert.ok(existsSync(claudeMdPath), 'CLAUDE.md must be created');
+  });
+
+  it('written CLAUDE.md contains the fenced block with the correct version', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    const expectedStartMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v${CLI_VERSION} -->`;
+    assert.ok(
+      written.includes(expectedStartMarker),
+      `expected start marker in written CLAUDE.md, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes('<!-- dev-agents:auto-route:end -->'),
+      `expected end marker in written CLAUDE.md, got:\n${written}`,
+    );
+  });
+
+  it('written CLAUDE.md contains the routing content', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    assert.ok(
+      written.includes(SAMPLE_ROUTING_CONTENT),
+      `expected routing content in written CLAUDE.md, got:\n${written}`,
+    );
+  });
+
+  it('creates CLAUDE.md when the file exists but is empty', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    writeFileSync(claudeMdPath, '', 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    assert.ok(
+      written.includes(START_MARKER_PREFIX),
+      `expected start marker after injecting into empty file, got:\n${written}`,
+    );
+  });
+});
+
+describe('injectClaudeMd — inject into file with existing prose', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('preserves existing prose above the injected block', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const originalProse = '# My Project\n\nThis is my CLAUDE.md.';
+    writeFileSync(claudeMdPath, originalProse, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    assert.ok(
+      written.includes('# My Project'),
+      `existing heading must be preserved, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes('This is my CLAUDE.md.'),
+      `existing prose must be preserved, got:\n${written}`,
+    );
+  });
+
+  it('appends the fenced block after the existing prose', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const originalProse = '# My Project\n\nProse here.';
+    writeFileSync(claudeMdPath, originalProse, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    const proseIndex = written.indexOf('Prose here.');
+    const blockIndex = written.indexOf(START_MARKER_PREFIX);
+    assert.ok(proseIndex !== -1, 'prose must be present');
+    assert.ok(blockIndex !== -1, 'fenced block must be present');
+    assert.ok(
+      proseIndex < blockIndex,
+      'existing prose must appear before the injected fenced block',
+    );
+  });
+});
+
+describe('injectClaudeMd — replace stale block', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('replaces a block whose version is older than the current version', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const staleBlock = makeFencedBlock('0.9.0', 'Old routing content.');
+    const originalContent = `# My Project\n\n${staleBlock}\n\nTrailing prose.`;
+    writeFileSync(claudeMdPath, originalContent, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    // New version in start marker
+    const expectedStartMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v${CLI_VERSION} -->`;
+    assert.ok(
+      written.includes(expectedStartMarker),
+      `expected updated start marker, got:\n${written}`,
+    );
+    // Old version removed
+    assert.ok(
+      !written.includes('v0.9.0'),
+      `old version marker must be removed, got:\n${written}`,
+    );
+    // Old routing content replaced
+    assert.ok(
+      !written.includes('Old routing content.'),
+      `old routing content must be replaced, got:\n${written}`,
+    );
+    // New routing content present
+    assert.ok(
+      written.includes(SAMPLE_ROUTING_CONTENT),
+      `new routing content must be present, got:\n${written}`,
+    );
+  });
+
+  it('preserves prose above the block when replacing a stale block', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const staleBlock = makeFencedBlock('0.9.0', 'Old routing content.');
+    const originalContent = `# Header prose\n\nSome text.\n\n${staleBlock}\n`;
+    writeFileSync(claudeMdPath, originalContent, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    assert.ok(
+      written.includes('# Header prose'),
+      `header prose above the block must be preserved, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes('Some text.'),
+      `prose above block must be preserved, got:\n${written}`,
+    );
+  });
+
+  it('preserves prose below the block when replacing a stale block', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const staleBlock = makeFencedBlock('0.9.0', 'Old routing content.');
+    const originalContent = `${staleBlock}\n\nTrailing notes.`;
+    writeFileSync(claudeMdPath, originalContent, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    assert.ok(
+      written.includes('Trailing notes.'),
+      `prose below the block must be preserved, got:\n${written}`,
+    );
+  });
+});
+
+describe('injectClaudeMd — skip when current', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('returns { skipped: true } when the block is already current', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const currentBlock = makeFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    writeFileSync(claudeMdPath, currentBlock, 'utf8');
+
+    const result = injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    assert.ok(
+      result?.skipped === true,
+      `expected { skipped: true } when block is already current, got: ${JSON.stringify(result)}`,
+    );
+  });
+
+  it('does not modify the file when the block is already current', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const currentBlock = makeFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    writeFileSync(claudeMdPath, currentBlock, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const after = readFileSync(claudeMdPath, 'utf8');
+    assert.equal(
+      after,
+      currentBlock,
+      'file must be byte-identical when block is already current',
+    );
+  });
+});
+
+describe('injectClaudeMd — dry-run', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('does not write to disk when dryRun is true (file does not exist)', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT, { dryRun: true });
+
+    assert.ok(
+      !existsSync(claudeMdPath),
+      'CLAUDE.md must not be created in dry-run mode',
+    );
+  });
+
+  it('does not modify disk when dryRun is true and a stale block is present', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const originalContent = makeFencedBlock('0.1.0', 'Old content.');
+    writeFileSync(claudeMdPath, originalContent, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT, { dryRun: true });
+
+    const after = readFileSync(claudeMdPath, 'utf8');
+    assert.equal(
+      after,
+      originalContent,
+      'file must not be modified in dry-run mode even when block is stale',
+    );
+  });
+
+  it('returns a result object with action and planned content in dry-run mode', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+
+    const result = injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT, {
+      dryRun: true,
+    });
+
+    assert.ok(result !== null && typeof result === 'object', 'expected a result object from dry-run');
+    // The result must communicate what would change — accept any reasonable shape.
+    const hasActionableField =
+      result.dryRun === true ||
+      typeof result.action === 'string' ||
+      typeof result.plannedContent === 'string';
+    assert.ok(
+      hasActionableField,
+      `dry-run result must include dryRun:true, action, or plannedContent. Got: ${JSON.stringify(result)}`,
+    );
+  });
+});
+
+describe('injectClaudeMd — malformed block (start marker present, end marker missing)', () => {
+  let tmpDir;
+
+  beforeEach(() => { tmpDir = makeTmpDir(); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('warns to stderr when the start marker is present but the end marker is missing', async () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const startMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v1.0.0 -->`;
+    const malformedContent = `# My CLAUDE.md\n\n${startMarker}\nContent with no end marker.`;
+    writeFileSync(claudeMdPath, malformedContent, 'utf8');
+
+    const stderr = await captureStderr(() => {
+      injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    });
+
+    assert.ok(
+      stderr.length > 0,
+      'expected a warning to stderr for malformed block (start without end)',
+    );
+    assert.ok(
+      /warn|malformed|end marker|missing/i.test(stderr),
+      `expected warning text to describe the malformed block, got:\n${stderr}`,
+    );
+  });
+
+  it('does not modify the file when the block is malformed', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const startMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v1.0.0 -->`;
+    const malformedContent = `# My CLAUDE.md\n\n${startMarker}\nContent with no end marker.`;
+    writeFileSync(claudeMdPath, malformedContent, 'utf8');
+
+    injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    const after = readFileSync(claudeMdPath, 'utf8');
+    assert.equal(
+      after,
+      malformedContent,
+      'file must not be modified when block is malformed — skip to avoid corruption',
+    );
+  });
+
+  it('returns { skipped: true, malformed: true } for a malformed block', () => {
+    const claudeMdPath = path.join(tmpDir, 'CLAUDE.md');
+    const startMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v1.0.0 -->`;
+    writeFileSync(
+      claudeMdPath,
+      `${startMarker}\nOrphaned content with no closing marker.`,
+      'utf8',
+    );
+
+    const result = injectClaudeMd(claudeMdPath, CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+
+    assert.ok(
+      result?.malformed === true,
+      `expected result.malformed === true, got: ${JSON.stringify(result)}`,
+    );
+    assert.ok(
+      result?.skipped === true,
+      `expected result.skipped === true, got: ${JSON.stringify(result)}`,
+    );
+  });
+});
+
+// ===========================================================================
+// Integration tests — init wires up CLAUDE.md injection
+// ===========================================================================
+
+describe('init — CLAUDE.md injection', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  it('creates CLAUDE.md in the consumer root after init when file does not exist', async () => {
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+    assert.ok(!existsSync(claudeMdPath), 'precondition: CLAUDE.md must not exist');
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      existsSync(claudeMdPath),
+      'CLAUDE.md must be created at the consumer root after init',
+    );
+  });
+
+  it('written CLAUDE.md contains the fenced start marker after init', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const written = readFileSync(path.join(consumerDir, 'CLAUDE.md'), 'utf8');
+    assert.ok(
+      written.includes(START_MARKER_PREFIX),
+      `expected fenced start marker prefix in CLAUDE.md, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes(END_MARKER),
+      `expected fenced end marker in CLAUDE.md, got:\n${written}`,
+    );
+  });
+
+  it('written CLAUDE.md contains the routing content from skills/auto-route.md', async () => {
+    const routingContent = '## Routing table\n\nRoute `fix` → `implement`.';
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcherWithAutoRoute(routingContent),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const written = readFileSync(path.join(consumerDir, 'CLAUDE.md'), 'utf8');
+    assert.ok(
+      written.includes('Route `fix` → `implement`.'),
+      `expected routing content in CLAUDE.md, got:\n${written}`,
+    );
+  });
+
+  it('preserves existing prose in CLAUDE.md above the injected block', async () => {
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+    writeFileSync(claudeMdPath, '# My project\n\nExisting prose.', 'utf8');
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const written = readFileSync(claudeMdPath, 'utf8');
+    assert.ok(
+      written.includes('# My project'),
+      `existing heading must be preserved, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes('Existing prose.'),
+      `existing prose must be preserved, got:\n${written}`,
+    );
+  });
+
+  it('--dry-run does not create CLAUDE.md', async () => {
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      dryRun: true,
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    assert.ok(
+      !existsSync(claudeMdPath),
+      'CLAUDE.md must not be created in dry-run mode',
+    );
+  });
+
+  it('--dry-run result includes claudeMd in the planned changes', async () => {
+    const result = await runInit(consumerDir, {
+      targets: ['claude'],
+      dryRun: true,
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    // The result must communicate the planned CLAUDE.md write in some form.
+    const resultStr = JSON.stringify(result);
+    assert.ok(
+      resultStr.includes('CLAUDE.md') || result.claudeMd !== undefined,
+      `dry-run result must reference CLAUDE.md planned change, got: ${resultStr}`,
+    );
+  });
+});
+
+// ===========================================================================
+// Integration tests — update wires up CLAUDE.md injection
+// ===========================================================================
+
+describe('update — CLAUDE.md injection replaces stale block', () => {
+  let consumerDir;
+
+  beforeEach(() => { consumerDir = makeTmpDir(); });
+  afterEach(() => { rmSync(consumerDir, { recursive: true, force: true }); });
+
+  /**
+   * Sets up a consumer that has already run init at v1.0.0 with a CLAUDE.md
+   * containing a stale block from a previous (lower) version.
+   */
+  async function setupConsumerWithStaleClaude(opts = {}) {
+    const { staleVersion = '0.1.0', staleProse = '' } = opts;
+
+    writeLockfile(consumerDir, {
+      source: 'github:dalzoubi/dev-agents',
+      range: '^1',
+      resolvedVersion: '1.0.0',
+      targets: ['claude'],
+      lastUpdated: '2026-04-01T00:00:00Z',
+    });
+
+    // Write managed claude agent file
+    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',
+    );
+
+    // Write CLAUDE.md with a stale fenced block
+    const staleBlock = makeFencedBlock(staleVersion, 'Old routing content.');
+    const claudeContent = staleProse
+      ? `${staleProse}\n\n${staleBlock}`
+      : staleBlock;
+    writeFileSync(path.join(consumerDir, 'CLAUDE.md'), claudeContent, 'utf8');
+  }
+
+  it('replaces a stale fenced block in CLAUDE.md after update', async () => {
+    await setupConsumerWithStaleClaude({ staleVersion: '0.1.0' });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const written = readFileSync(path.join(consumerDir, 'CLAUDE.md'), 'utf8');
+    assert.ok(
+      !written.includes('v0.1.0'),
+      `stale version must be replaced in CLAUDE.md, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes(START_MARKER_PREFIX),
+      `updated block must contain start marker prefix, got:\n${written}`,
+    );
+  });
+
+  it('preserves existing prose above the block in CLAUDE.md after update', async () => {
+    await setupConsumerWithStaleClaude({
+      staleVersion: '0.1.0',
+      staleProse: '# My Project\n\nExisting prose above the block.',
+    });
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const written = readFileSync(path.join(consumerDir, 'CLAUDE.md'), 'utf8');
+    assert.ok(
+      written.includes('# My Project'),
+      `prose above the block must be preserved after update, got:\n${written}`,
+    );
+    assert.ok(
+      written.includes('Existing prose above the block.'),
+      `existing prose must be preserved after update, got:\n${written}`,
+    );
+  });
+
+  it('skips silently when block is already current during update', async () => {
+    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',
+    );
+
+    // Write CLAUDE.md already at the current version — update should skip it.
+    const currentBlock = makeFencedBlock(CLI_VERSION, SAMPLE_ROUTING_CONTENT);
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+    writeFileSync(claudeMdPath, currentBlock, 'utf8');
+    const contentBefore = readFileSync(claudeMdPath, 'utf8');
+
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: ['v1.0.0', 'v1.0.0'],  // same version → upToDate
+    });
+
+    // File must be byte-identical — skip means no write.
+    const contentAfter = readFileSync(claudeMdPath, 'utf8');
+    assert.equal(
+      contentAfter,
+      contentBefore,
+      'CLAUDE.md must not be modified when block is already current',
+    );
+  });
+
+  it('warns to stderr and skips when CLAUDE.md has a malformed block during update', async () => {
+    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',
+    );
+
+    // Write CLAUDE.md with a malformed block (start marker, no end marker).
+    const startMarker = `<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v1.0.0 -->`;
+    const malformedContent = `# CLAUDE.md\n\n${startMarker}\nOrphaned content.`;
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+    writeFileSync(claudeMdPath, malformedContent, 'utf8');
+
+    const stderr = await captureStderr(async () => {
+      await runUpdate(consumerDir, {
+        fetcher: makeFixtureFetcherWithAutoRoute(),
+        availableTags: ['v1.0.0', 'v1.2.0'],
+      });
+    });
+
+    // Must warn
+    assert.ok(
+      /warn|malformed|end marker|missing/i.test(stderr),
+      `expected warning about malformed block during update, got:\n${stderr}`,
+    );
+
+    // Must NOT have corrupted the file
+    const contentAfter = readFileSync(claudeMdPath, 'utf8');
+    assert.equal(
+      contentAfter,
+      malformedContent,
+      'CLAUDE.md must not be modified when block is malformed — skip to preserve user content',
+    );
+  });
+
+  it('--dry-run does not modify CLAUDE.md during update', async () => {
+    await setupConsumerWithStaleClaude({ staleVersion: '0.1.0' });
+    const claudeMdPath = path.join(consumerDir, 'CLAUDE.md');
+    const contentBefore = readFileSync(claudeMdPath, 'utf8');
+
+    await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    const contentAfter = readFileSync(claudeMdPath, 'utf8');
+    assert.equal(
+      contentAfter,
+      contentBefore,
+      'CLAUDE.md must not be modified during a dry-run update',
+    );
+  });
+
+  it('--dry-run result includes claudeMd field when routing content is available', async () => {
+    await setupConsumerWithStaleClaude({ staleVersion: '0.1.0' });
+
+    const result = await runUpdate(consumerDir, {
+      dryRun: true,
+      fetcher: makeFixtureFetcherWithAutoRoute(),
+      availableTags: ['v1.0.0', 'v1.2.0'],
+    });
+
+    assert.ok(
+      result !== null && typeof result === 'object',
+      'expected a result object from update dry-run',
+    );
+    assert.ok(
+      'claudeMd' in result,
+      `update --dry-run result must include a claudeMd field when routing content is present, got: ${JSON.stringify(result)}`,
+    );
+    // The claudeMd value must be non-null (routing content was available via the fetcher).
+    assert.notEqual(
+      result.claudeMd,
+      null,
+      'claudeMd field must be non-null when routing content is available',
+    );
+  });
+});