session-orchestrator 3.16.0

package/scripts/lib/rules-sync.mjs

@@ -0,0 +1,439 @@
+/**
+ * rules-sync.mjs — #191
+ * Syncs canonical rules from the plugin's rules/ library into a consumer repo's .claude/rules/.
+ *
+ * Stdlib-only, cross-platform, no Zod, no third-party parsers. ESM module.
+ * Preserves local rules (files without the plugin source header).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateRuleContent } from './validate-vendored-rules.mjs';
+
+// Exported (issue #722 Epic A Wave 2) for external consumers (e.g. tests).
+// NOT imported by validate-vendored-rules.mjs — that module imports
+// validateRuleContent FROM this file (see the pre-write gate below), so
+// importing this constant back would create a module-load cycle; it keeps
+// its own textually-identical copy instead.
+export const PLUGIN_HEADER_PREFIX = '<!-- source: session-orchestrator plugin';
+
+/**
+ * Parses the _index.md file and returns an array of entries for each
+ * requested category. Each entry's `relPath` is relative to pluginRoot.
+ *
+ * Supports the optional trailing `[archetypes: a, b]` tag (issue #722 Epic A
+ * Wave 3) on a bullet line:
+ *
+ *   - `opt-in-stack/foo.md` — description [archetypes: nextjs-minimal, node-minimal]
+ *
+ * A bullet without the tag resolves to `archetypes: null` (universal —
+ * vendored to every consumer repo, matching pre-Wave-3 behavior exactly).
+ * Archetype values are lower-cased at parse time so downstream comparison is
+ * always case-insensitive.
+ *
+ * @param {string} indexContent - raw content of rules/_index.md
+ * @param {string[]} categories - e.g. ['always-on']
+ * @returns {Array<{relPath: string, archetypes: string[]|null}>} entries like
+ *   { relPath: 'rules/always-on/parallel-sessions.md', archetypes: null }
+ */
+function parseIndex(indexContent, categories) {
+  const entries = [];
+
+  for (const category of categories) {
+    // Match the section header for this category
+    const sectionRe = new RegExp(`^##\\s+${escapeRegex(category)}[^\\n]*$`, 'm');
+    const sectionMatch = sectionRe.exec(indexContent);
+    if (!sectionMatch) continue;
+
+    const sectionStart = sectionMatch.index + sectionMatch[0].length;
+    // Everything until the next ## heading (or end of file)
+    const nextSectionMatch = /^##\s+/m.exec(indexContent.slice(sectionStart));
+    const sectionEnd =
+      nextSectionMatch !== null
+        ? sectionStart + nextSectionMatch.index
+        : indexContent.length;
+
+    const sectionBody = indexContent.slice(sectionStart, sectionEnd);
+
+    // Extract bullet items: - `always-on/some-file.md` — description [archetypes: a, b]
+    const bulletRe = /^-\s+`([^`]+\.md)`([^\n]*)$/gm;
+    let match;
+    while ((match = bulletRe.exec(sectionBody)) !== null) {
+      const relPath = `rules/${match[1]}`;
+      const rest = match[2] ?? '';
+      const archetypeMatch = /\[archetypes:\s*([^\]]+)\]/i.exec(rest);
+      const archetypes = archetypeMatch
+        ? archetypeMatch[1]
+            .split(',')
+            .map((s) => s.trim().toLowerCase())
+            .filter(Boolean)
+        : null;
+      entries.push({ relPath, archetypes });
+    }
+  }
+
+  return entries;
+}
+
+function listManifestCategories(indexContent) {
+  const categories = [];
+  const headingRe = /^##\s+([^\n]+)$/gm;
+  let headingMatch;
+  while ((headingMatch = headingRe.exec(indexContent)) !== null) {
+    const headingText = headingMatch[1].trim();
+    const category = headingText.split(/\s+/)[0];
+    const sectionStart = headingMatch.index + headingMatch[0].length;
+    const nextSectionMatch = /^##\s+/m.exec(indexContent.slice(sectionStart));
+    const sectionEnd =
+      nextSectionMatch !== null
+        ? sectionStart + nextSectionMatch.index
+        : indexContent.length;
+    const sectionBody = indexContent.slice(sectionStart, sectionEnd);
+    const bulletRe = /^-\s+`([^`]+\.md)`/gm;
+    let bulletMatch;
+    while ((bulletMatch = bulletRe.exec(sectionBody)) !== null) {
+      const rel = bulletMatch[1];
+      if (rel.includes('<')) continue;
+      categories.push(category);
+      break;
+    }
+  }
+  return categories;
+}
+
+/**
+ * Resolves the target repo's archetype (issue #722 Epic A Wave 3).
+ *
+ * Precedence: explicit `archetype` argument (CLI `--archetype` / caller
+ * override) beats `.orchestrator/bootstrap.lock` resolution. When neither is
+ * available, or the lock file's `archetype:` value is absent/`null`, the
+ * archetype is "unknown" — archetype-scoped entries are skipped, universal
+ * entries still vendor.
+ *
+ * @param {string} repoRoot
+ * @param {string|null} explicitArchetype
+ * @returns {{archetype: string|null, known: boolean}}
+ */
+function resolveArchetype(repoRoot, explicitArchetype) {
+  if (explicitArchetype) {
+    return { archetype: explicitArchetype.trim().toLowerCase(), known: true };
+  }
+
+  const lockPath = join(repoRoot, '.orchestrator', 'bootstrap.lock');
+  if (!existsSync(lockPath)) {
+    return { archetype: null, known: false };
+  }
+
+  let lockContent;
+  try {
+    lockContent = readFileSync(lockPath, 'utf8');
+  } catch {
+    return { archetype: null, known: false };
+  }
+
+  const m = /^archetype:\s*(.+?)\s*$/m.exec(lockContent);
+  if (!m) return { archetype: null, known: false };
+
+  let value = m[1].replace(/\s+#.*$/, '').trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1).trim();
+  }
+  if (!value || value.toLowerCase() === 'null') {
+    return { archetype: null, known: false };
+  }
+
+  return { archetype: value.toLowerCase(), known: true };
+}
+
+/**
+ * Escapes a string for use in a RegExp.
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Syncs canonical rules from the plugin's rules/ library into a consumer repo.
+ *
+ * When `validate` is true (the default — issue #722 Epic A Wave 2),
+ * validateRuleContent() runs as a pre-write gate on every source file before
+ * it is copied. A file with any error-severity violation (paths-frontmatter,
+ * missing provenance header, unfilled placeholder) is recorded in `errors[]`
+ * and its write is skipped entirely — it is never added to
+ * written/skipped/preserved. Warn-severity violations (zero-match-globs,
+ * foreign-glob) do NOT block the write; they are collected into the
+ * additive `warnings[]` array instead. `requireProvenance` (default `true`)
+ * is forwarded to that gate call — pass `false` only for test fixtures that
+ * intentionally exercise unprovenanced content.
+ *
+ * Archetype filtering (issue #722 Epic A Wave 3): an `_index.md` entry may
+ * carry a trailing `[archetypes: a, b]` tag (see `rules/_index.md` § Entry
+ * syntax). When present, the entry is vendored ONLY when it matches the
+ * target repo's resolved archetype — explicit `archetype` argument first,
+ * falling back to `<repoRoot>/.orchestrator/bootstrap.lock`'s `archetype:`
+ * line. A mismatch is recorded in `skipped[]` as
+ * `{ file, reason: 'archetype-mismatch' }`; an unresolvable target archetype
+ * is recorded as `{ file, reason: 'archetype-unknown' }`. Untagged
+ * (universal) entries always vendor, unaffected by archetype resolution —
+ * this preserves full backward compatibility with pre-Wave-3 `_index.md`
+ * files and callers that never pass `archetype`.
+ *
+ * When `categories` is null/omitted, sync every `_index.md` category that has
+ * at least one concrete bullet entry. This keeps `/bootstrap --sync-rules`
+ * ready for future opt-in categories without requiring CLI changes.
+ *
+ * @param {{
+ *   pluginRoot: string,
+ *   repoRoot: string,
+ *   categories?: string[]|null,
+ *   dryRun?: boolean,
+ *   validate?: boolean,
+ *   requireProvenance?: boolean,
+ *   archetype?: string|null
+ * }} opts
+ * @returns {{
+ *   written: string[],
+ *   skipped: Array<string|{file: string, reason: string}>,
+ *   preserved: string[],
+ *   errors: Array<{file: string, reason: string}>,
+ *   warnings: Array<{file: string, reason: string}>
+ * }}
+ */
+export function syncRules({
+  pluginRoot,
+  repoRoot,
+  categories = null,
+  dryRun = false,
+  validate = true,
+  requireProvenance = true,
+  archetype = null,
+} = {}) {
+  const written = [];
+  const skipped = [];
+  const preserved = [];
+  const errors = [];
+  const warnings = [];
+
+  if (!pluginRoot || typeof pluginRoot !== 'string') {
+    errors.push({ file: '_index.md', reason: 'pluginRoot not provided' });
+    return { written, skipped, preserved, errors, warnings };
+  }
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    errors.push({ file: '_index.md', reason: 'repoRoot not provided' });
+    return { written, skipped, preserved, errors, warnings };
+  }
+
+  const indexPath = join(pluginRoot, 'rules', '_index.md');
+  if (!existsSync(indexPath)) {
+    errors.push({ file: '_index.md', reason: `_index.md not found at ${indexPath}` });
+    return { written, skipped, preserved, errors, warnings };
+  }
+
+  let indexContent;
+  try {
+    indexContent = readFileSync(indexPath, 'utf8');
+  } catch (err) {
+    errors.push({ file: '_index.md', reason: `failed to read _index.md: ${err.message}` });
+    return { written, skipped, preserved, errors, warnings };
+  }
+
+  const selectedCategories = Array.isArray(categories)
+    ? categories
+    : listManifestCategories(indexContent);
+  const entries = parseIndex(indexContent, selectedCategories);
+
+  if (entries.length === 0) {
+    // No sources resolved — could be empty categories or malformed index
+    for (const cat of selectedCategories.length > 0 ? selectedCategories : ['<none>']) {
+      errors.push({
+        file: `rules/${cat}/*.md`,
+        reason: `no sources resolved for category '${cat}' in _index.md`,
+      });
+    }
+    return { written, skipped, preserved, errors, warnings };
+  }
+
+  const targetDir = join(repoRoot, '.claude', 'rules');
+  const resolvedArchetype = resolveArchetype(repoRoot, archetype);
+  const targetBasenames = new Map();
+
+  for (const entry of entries) {
+    const { relPath, archetypes } = entry;
+
+    // Archetype filter (issue #722 Epic A Wave 3) — evaluated before any
+    // file IO, so a skip never triggers a spurious "source file not found".
+    if (archetypes !== null) {
+      if (!resolvedArchetype.known) {
+        skipped.push({ file: relPath, reason: 'archetype-unknown' });
+        continue;
+      }
+      if (!archetypes.includes(resolvedArchetype.archetype)) {
+        skipped.push({ file: relPath, reason: 'archetype-mismatch' });
+        continue;
+      }
+    }
+
+    const srcPath = join(pluginRoot, relPath);
+    const fileName = basename(relPath);
+    const targetPath = join(targetDir, fileName);
+    if (targetBasenames.has(fileName)) {
+      errors.push({
+        file: relPath,
+        reason: `duplicate target filename '${fileName}' also used by ${targetBasenames.get(fileName)}`,
+      });
+      continue;
+    }
+    targetBasenames.set(fileName, relPath);
+
+    if (!existsSync(srcPath)) {
+      errors.push({ file: relPath, reason: `source file not found: ${srcPath}` });
+      continue;
+    }
+
+    let srcContent;
+    try {
+      srcContent = readFileSync(srcPath, 'utf8');
+    } catch (err) {
+      errors.push({ file: relPath, reason: `failed to read source: ${err.message}` });
+      continue;
+    }
+
+    // Pre-write validation gate (issue #722 Epic A Wave 2). Runs BEFORE the
+    // existsSync(targetPath) write-decision branch below, so a validation
+    // failure skips the write regardless of whether the target already
+    // exists, is stale, or is missing.
+    if (validate) {
+      const validation = validateRuleContent({
+        content: srcContent,
+        relPath,
+        requireProvenance,
+        targetRoot: repoRoot,
+      });
+      const errorViolations = validation.violations.filter((v) => v.severity === 'error');
+      if (errorViolations.length > 0) {
+        errors.push({
+          file: relPath,
+          reason: `validation-failed: ${errorViolations.map((v) => v.rule).join(', ')}`,
+        });
+        continue;
+      }
+      const warnViolations = validation.violations.filter((v) => v.severity === 'warn');
+      for (const v of warnViolations) {
+        warnings.push({ file: relPath, reason: `${v.rule}: ${v.message}` });
+      }
+    }
+
+    if (existsSync(targetPath)) {
+      let targetContent;
+      try {
+        targetContent = readFileSync(targetPath, 'utf8');
+      } catch (err) {
+        errors.push({ file: targetPath, reason: `failed to read target: ${err.message}` });
+        continue;
+      }
+
+      const firstLine = targetContent.split('\n')[0] ?? '';
+      if (!firstLine.startsWith(PLUGIN_HEADER_PREFIX)) {
+        // Local file — preserve it
+        preserved.push(fileName);
+        continue;
+      }
+
+      if (targetContent === srcContent) {
+        // Already up to date
+        skipped.push(fileName);
+        continue;
+      }
+
+      // Plugin-owned file with stale content — overwrite
+      if (!dryRun) {
+        try {
+          writeFileSync(targetPath, srcContent, 'utf8');
+        } catch (err) {
+          errors.push({ file: targetPath, reason: `failed to write: ${err.message}` });
+          continue;
+        }
+      }
+      written.push(fileName);
+    } else {
+      // Target does not exist — write it
+      if (!dryRun) {
+        try {
+          mkdirSync(targetDir, { recursive: true });
+          writeFileSync(targetPath, srcContent, 'utf8');
+        } catch (err) {
+          errors.push({ file: targetPath, reason: `failed to write: ${err.message}` });
+          continue;
+        }
+      }
+      written.push(fileName);
+    }
+  }
+
+  return { written, skipped, preserved, errors, warnings };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Detect direct execution: node scripts/lib/rules-sync.mjs
+const isMain =
+  typeof process !== 'undefined' &&
+  process.argv[1] !== null &&
+  process.argv[1] !== undefined &&
+  resolve(process.argv[1]) === resolve(__filename);
+
+if (isMain) {
+  const args = process.argv.slice(2);
+
+  function getArg(name) {
+    const idx = args.indexOf(name);
+    return idx !== -1 ? args[idx + 1] : undefined;
+  }
+
+  function getAllArgs(name) {
+    const values = [];
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === name && args[i + 1]) values.push(args[i + 1]);
+    }
+    return values;
+  }
+
+  const repoRoot = getArg('--repo-root');
+  const dryRun = args.includes('--dry-run');
+  // Explicit archetype override (issue #722 Epic A Wave 3) — beats
+  // .orchestrator/bootstrap.lock resolution inside syncRules().
+  const archetype = getArg('--archetype') ?? null;
+  const categoryArgs = [
+    ...getAllArgs('--category'),
+    ...(getArg('--categories') ?? '').split(','),
+  ]
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const categories = categoryArgs.length > 0 ? categoryArgs : null;
+
+  if (!repoRoot) {
+    process.stderr.write('rules-sync: error: --repo-root <path> is required\n');
+    process.exit(1);
+  }
+
+  // Plugin root is two directories up from scripts/lib/
+  const pluginRoot = resolve(__dirname, '..', '..');
+
+  const result = syncRules({ pluginRoot, repoRoot, dryRun, archetype, categories });
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+
+  if (result.errors.length > 0) {
+    process.exit(1);
+  }
+  process.exit(0);
+}