@dalzoubi/dev-agents-sync 1.0.26 → 2.0.0

package/README.md

@@ -41,18 +41,32 @@ npx --yes @dalzoubi/dev-agents-sync@1 init --targets claude
 This writes managed files into `.claude/` and creates `.dev-agents-sync.json` with the resolved content version.
 Use `--targets cursor` or `--targets claude,cursor` to install Cursor project agents, rules, and slash commands into `.cursor/agents/`, `.cursor/rules/`, and `.cursor/commands/`.
 
+As part of `init`, the CLI injects an auto-routing fenced block into `CLAUDE.md` (creating the file if it does not exist). The block tells Claude Code how to route tasks to the correct agent. It is delimited by:
+
+```html
+<!-- dev-agents:auto-route:start -->
+...auto-generated routing instructions...
+<!-- dev-agents:auto-route:end -->
+```
+
+Do not hand-edit content inside those markers — it will be overwritten on the next `update`.
+
 Update to the latest matching content version:
 
 ```bash
 npx --yes @dalzoubi/dev-agents-sync@1 update
 ```
 
+`update` refreshes managed agent files **and** replaces the `CLAUDE.md` auto-routing block if it is stale, so routing instructions always match the installed content version.
+
 Check whether managed files are in sync:
 
 ```bash
 npx --yes @dalzoubi/dev-agents-sync@1 check
 ```
 
+`check` verifies that managed agent files and the `CLAUDE.md` auto-routing block are both up to date. If the routing block is absent or stale, `check` exits with code 1 and names `CLAUDE.md` in the output. This makes it safe to use in CI to detect drift.
+
 Show the expected diff without writing files:
 
 ```bash

package/eslint.config.mjs

@@ -0,0 +1,9 @@
+export default [
+  {
+    files: ["**/*.mjs"],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: "module",
+    },
+  },
+];

package/package.json

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

package/src/claudeMd.mjs

@@ -0,0 +1,220 @@
+/**
+ * claudeMd.mjs
+ *
+ * Helper for injecting and updating the auto-route fenced block in a
+ * consumer's CLAUDE.md file.
+ *
+ * @internal — not part of the public package API
+ *
+ * Fenced block format:
+ *   <!-- dev-agents:auto-route:start managed-by: dev-agents-sync vX.Y.Z -->
+ *   ...routing rules content...
+ *   <!-- dev-agents:auto-route:end -->
+ *
+ * Design notes:
+ * - The version in the start marker is the CLI package version, not the
+ *   resolved content version. This lets consumers detect that their routing
+ *   rules were written by a specific CLI release.
+ * - We never clobber a malformed block (start present, end missing). Doing so
+ *   would silently destroy user content in the region below the orphaned
+ *   start marker. Warn and skip instead.
+ * - Deterministic output: same inputs → same file content (§9 CONSTITUTION).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Exported constants — load-bearing: tests and callers grep for these exact
+// literal strings, so do not change them without a migration story.
+// ---------------------------------------------------------------------------
+
+export const START_MARKER_PREFIX = '<!-- dev-agents:auto-route:start managed-by: dev-agents-sync v';
+export const END_MARKER = '<!-- dev-agents:auto-route:end -->';
+
+// Regex that matches the full start marker and captures the version.
+// Must stay in sync with START_MARKER_PREFIX above.
+const START_MARKER_RE = /<!--\s*dev-agents:auto-route:start\s+managed-by:\s*dev-agents-sync\s+v([^\s]+)\s*-->/;
+
+// ---------------------------------------------------------------------------
+// buildFencedBlock
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the full fenced block string.
+ *
+ * @param {string} version  CLI package version (e.g. "1.0.25")
+ * @param {string} content  Routing rules content to embed between the markers
+ * @returns {string}
+ */
+export function buildFencedBlock(version, content) {
+  return [
+    `${START_MARKER_PREFIX}${version} -->`,
+    content,
+    END_MARKER,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// parseExistingBlock
+// ---------------------------------------------------------------------------
+
+/**
+ * Scans `fileContent` for an existing auto-route fenced block.
+ *
+ * Returns:
+ *   null                         — no block present (safe to append)
+ *   { version, block }           — well-formed block found; `block` is the
+ *                                  full text from start marker to end marker
+ *                                  (inclusive, with the newline between them)
+ *   { malformed: true }          — start marker found but end marker is absent
+ *
+ * @param {string} fileContent
+ * @returns {null | { version: string, block: string } | { malformed: true }}
+ */
+export function parseExistingBlock(fileContent) {
+  if (!fileContent) return null;
+
+  const startMatch = fileContent.match(START_MARKER_RE);
+  if (!startMatch) return null;
+
+  const startIndex = fileContent.indexOf(startMatch[0]);
+  const version = startMatch[1];
+
+  const endIndex = fileContent.indexOf(END_MARKER, startIndex + startMatch[0].length);
+  if (endIndex === -1) {
+    return { malformed: true };
+  }
+
+  // Include the full block from start marker through end marker (no trailing newline).
+  const block = fileContent.slice(startIndex, endIndex + END_MARKER.length);
+  return { version, block };
+}
+
+// ---------------------------------------------------------------------------
+// injectClaudeMd
+// ---------------------------------------------------------------------------
+
+/**
+ * Injects or replaces the auto-route fenced block in a CLAUDE.md file.
+ *
+ * Behaviour:
+ *  - File does not exist → create it with just the fenced block
+ *  - File exists, no block → append the fenced block (preserving existing prose)
+ *  - File exists, well-formed block, same version+content → skip silently
+ *  - File exists, well-formed block, stale → replace in-place; prose untouched
+ *  - File exists, malformed block (start, no end) → warn stderr, skip
+ *  - dryRun: true → return plan, write nothing
+ *
+ * @param {string} absPath   Absolute path to CLAUDE.md
+ * @param {string} version   CLI package version string
+ * @param {string} content   Routing rules content to embed
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {{ skipped?: boolean, malformed?: boolean, dryRun?: boolean,
+ *             action?: string, plannedContent?: string }}
+ */
+export function injectClaudeMd(absPath, version, content, opts = {}) {
+  const { dryRun = false } = opts;
+
+  const newBlock = buildFencedBlock(version, content);
+
+  // -------------------------------------------------------------------------
+  // Determine current state
+  // -------------------------------------------------------------------------
+
+  let existingContent = null;
+  if (existsSync(absPath)) {
+    existingContent = readFileSync(absPath, 'utf8');
+  }
+
+  // Empty string is treated the same as absent — nothing to preserve.
+  const hasExistingContent = existingContent !== null && existingContent.length > 0;
+
+  let parsed = null;
+  if (hasExistingContent) {
+    parsed = parseExistingBlock(existingContent);
+  }
+
+  // -------------------------------------------------------------------------
+  // Malformed block — warn and skip
+  // -------------------------------------------------------------------------
+
+  if (parsed && parsed.malformed) {
+    process.stderr.write(
+      `warn: dev-agents-sync: CLAUDE.md has a malformed auto-route block ` +
+        `(start marker present but end marker is missing). ` +
+        `Skipping injection to avoid corrupting the file. ` +
+        `Remove or repair the block manually and re-run.\n`,
+    );
+    return { skipped: true, malformed: true };
+  }
+
+  // -------------------------------------------------------------------------
+  // Skip when current — version AND content are identical
+  // -------------------------------------------------------------------------
+
+  if (parsed && parsed.version === version && parsed.block === newBlock) {
+    return { skipped: true };
+  }
+
+  // -------------------------------------------------------------------------
+  // Dry run — compute planned content but do not write
+  // -------------------------------------------------------------------------
+
+  if (dryRun) {
+    const plannedContent = computeNewContent(existingContent, parsed, newBlock);
+    return { dryRun: true, action: parsed ? 'replace' : 'inject', plannedContent };
+  }
+
+  // -------------------------------------------------------------------------
+  // Write
+  // -------------------------------------------------------------------------
+
+  const newContent = computeNewContent(existingContent, parsed, newBlock);
+
+  mkdirSync(path.dirname(absPath), { recursive: true });
+  try {
+    writeFileSync(absPath, newContent, 'utf8');
+  } catch (err) {
+    const wrapped = new Error('Cannot write to CLAUDE.md — check file permissions.');
+    wrapped.cause = err;
+    wrapped.exitCode = 2;
+    throw wrapped;
+  }
+
+  return { action: parsed ? 'replace' : 'inject' };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Computes the new full file content by either:
+ *   - Replacing the existing block in-place (preserving surrounding prose), or
+ *   - Appending the block to whatever content exists (possibly empty/absent)
+ *
+ * @param {string | null} existingContent  Current file content, or null if absent
+ * @param {{ block: string } | null} parsed  parseExistingBlock result (non-malformed)
+ * @param {string} newBlock  The fully-formed fenced block to inject
+ * @returns {string}
+ */
+function computeNewContent(existingContent, parsed, newBlock) {
+  // Case 1: file absent or empty — write just the fenced block
+  if (!existingContent || existingContent.length === 0) {
+    return newBlock + '\n';
+  }
+
+  // Case 2: existing block to replace in-place
+  if (parsed && parsed.block) {
+    // Use the function form of replace to avoid $-sequence corruption
+    // (e.g. `$$`, `$&`, `$1` in newBlock would otherwise be misinterpreted
+    // as replacement patterns by the String.prototype.replace algorithm).
+    return existingContent.replace(parsed.block, () => newBlock);
+  }
+
+  // Case 3: file has prose but no block — append
+  // Ensure a blank line separates the existing prose from the fenced block.
+  const trimmed = existingContent.trimEnd();
+  return trimmed + '\n\n' + newBlock + '\n';
+}

package/src/commands/check.mjs

@@ -7,9 +7,15 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
 
 import { readLockfile } from '../lockfile.mjs';
 import { resolveConsumerPath, normalizeFileMap } from '../writer.mjs';
+import { parseExistingBlock, buildFencedBlock } from '../claudeMd.mjs';
+
+const _require = createRequire(import.meta.url);
+const CLI_VERSION = _require('../../package.json').version;
 
 function filterFileMapByTargets(fileMap, targets) {
   const out = {};
@@ -46,7 +52,8 @@ export async function runCheck(consumerCwd, opts = {}) {
     throw wrapped;
   }
 
-  const scoped = filterFileMapByTargets(normalizeFileMap(fileMap), lock.targets);
+  const normalized = normalizeFileMap(fileMap);
+  const scoped = filterFileMapByTargets(normalized, lock.targets);
 
   const drifted = [];
 
@@ -65,6 +72,64 @@ export async function runCheck(consumerCwd, opts = {}) {
     }
   }
 
+  // -------------------------------------------------------------------------
+  // CLAUDE.md fenced block drift check
+  //
+  // Only applies when the `claude` target is active. We look for the routing
+  // content at `claude/skills/auto-route.md` in the fetched file map and
+  // compare the consumer's CLAUDE.md fenced block against the expected block
+  // built from the current CLI version + that routing content.
+  //
+  // All three problem states are treated as drift (not tooling error):
+  //   - CLAUDE.md absent
+  //   - fenced block absent (CLAUDE.md has prose but no block)
+  //   - fenced block malformed (start marker, no end marker)
+  //   - fenced block stale (version or content differs from expected)
+  // -------------------------------------------------------------------------
+
+  const claudeTargetActive = lock.targets.includes('claude');
+  if (claudeTargetActive) {
+    const routingContent = normalized['claude/skills/auto-route.md'] ?? null;
+
+    if (routingContent === null) {
+      // Skip is intentional when the remote skill is absent — the consumer may
+      // be pinned to a version that predates the auto-route skill file.  This
+      // is not drift (no expected block to compare against), but it should not
+      // be silent either, so we emit a structured warning.
+      process.stderr.write(
+        'warn: CLAUDE.md drift check skipped — claude/skills/auto-route.md not present in fetched content\n',
+      );
+    } else {
+      const claudeMdPath = path.join(consumerCwd, 'CLAUDE.md');
+      const expectedBlock = buildFencedBlock(CLI_VERSION, routingContent);
+
+      let isDrifted = false;
+      if (!existsSync(claudeMdPath)) {
+        // Absence is drift — CLAUDE.md should always carry the routing block
+        // after init/update has run.
+        isDrifted = true;
+      } else {
+        const claudeMdContent = readFileSync(claudeMdPath, 'utf8');
+        const parsed = parseExistingBlock(claudeMdContent);
+
+        if (parsed === null) {
+          // No block present at all.
+          isDrifted = true;
+        } else if (parsed.malformed) {
+          // Start marker with no end marker — treat as drift, not a crash.
+          isDrifted = true;
+        } else if (parsed.block !== expectedBlock) {
+          // Block present but version or content differs.
+          isDrifted = true;
+        }
+      }
+
+      if (isDrifted) {
+        drifted.push('CLAUDE.md');
+      }
+    }
+  }
+
   if (drifted.length === 0) {
     return { inSync: true, resolvedVersion: lock.resolvedVersion };
   }

package/src/commands/init.mjs

@@ -8,11 +8,17 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 import { writeLockfile, DEFAULT_SOURCE } from '../lockfile.mjs';
 import { resolveRange } from '../range.mjs';
 import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
+import { injectClaudeMd } from '../claudeMd.mjs';
+
+const _require = createRequire(import.meta.url);
+const CLI_VERSION = _require('../../package.json').version;
 
 const DEFAULT_RANGE = '^1';
 const ALL_TARGETS = ['claude', 'cursor'];
@@ -114,13 +120,28 @@ export async function runInit(consumerCwd, opts = {}) {
     plannedWrites.push({ relKey, absPath, content, isNew });
   }
 
+  // Extract auto-route content for CLAUDE.md injection (claude target only).
+  // We read from the normalised map so the content is available regardless of
+  // whether the `skills` dir ends up in the consumer's scoped file set.
+  const claudeTargetActive = resolvedTargets.includes('claude');
+  const routingContent = claudeTargetActive
+    ? (normalized['claude/skills/auto-route.md'] ?? null)
+    : null;
+  const claudeMdPath = path.join(consumerCwd, 'CLAUDE.md');
+
   if (dryRun) {
+    // Run inject in dry-run mode to compute the planned change.
+    const claudeMdResult = routingContent
+      ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
+      : null;
+
     return {
       dryRun: true,
       resolvedVersion,
       targets: resolvedTargets,
       plannedWrites: plannedWrites.map(({ relKey, absPath }) => ({ relKey, absPath })),
       files: plannedWrites.map(({ relKey }) => relKey),
+      claudeMd: claudeMdResult,
     };
   }
 
@@ -153,6 +174,11 @@ export async function runInit(consumerCwd, opts = {}) {
     }
   }
 
+  // Inject or update the auto-route fenced block in CLAUDE.md.
+  if (routingContent) {
+    injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent);
+  }
+
   writeLockfile(consumerCwd, {
     source,
     range,

package/src/commands/update.mjs

@@ -6,11 +6,17 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
 
 import { readLockfile, writeLockfile } from '../lockfile.mjs';
 import { resolveRange } from '../range.mjs';
 import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writer.mjs';
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
+import { injectClaudeMd } from '../claudeMd.mjs';
+
+const _require = createRequire(import.meta.url);
+const CLI_VERSION = _require('../../package.json').version;
 
 function filterFileMapByTargets(fileMap, targets) {
   const out = {};
@@ -61,12 +67,25 @@ export async function runUpdate(consumerCwd, opts = {}) {
     plannedWrites.push({ relKey, absPath, content, isNew });
   }
 
+  // Auto-route content for CLAUDE.md injection (claude target only).
+  const claudeTargetActive = lock.targets.includes('claude');
+  const routingContent = claudeTargetActive
+    ? (normalized['claude/skills/auto-route.md'] ?? null)
+    : null;
+  const claudeMdPath = path.join(consumerCwd, 'CLAUDE.md');
+
   if (dryRun) {
+    // Compute the planned CLAUDE.md change so callers can inspect it without
+    // the result shape silently diverging from the init --dry-run contract.
+    const claudeMdResult = routingContent
+      ? injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent, { dryRun: true })
+      : null;
     return {
       dryRun: true,
       resolvedVersion: targetVersion,
       previousVersion: lock.resolvedVersion,
       files: plannedWrites.map(({ relKey }) => relKey),
+      claudeMd: claudeMdResult,
     };
   }
 
@@ -98,6 +117,11 @@ export async function runUpdate(consumerCwd, opts = {}) {
     }
   }
 
+  // Inject or update the auto-route fenced block in CLAUDE.md.
+  if (routingContent) {
+    injectClaudeMd(claudeMdPath, CLI_VERSION, routingContent);
+  }
+
   writeLockfile(consumerCwd, {
     source: lock.source,
     range: lock.range,