bmad-plus 0.9.2 → 0.12.0

package/tools/build/generate-adapters.js

@@ -0,0 +1,485 @@
+#!/usr/bin/env node
+/**
+ * BMAD+ Build — registry.yaml → multi-CLI adapter generator (Pillar 5)
+ *
+ * Reads the root registry.yaml (the single source of truth) and, for each
+ * targets.adapters[] entry, emits a THIN adapter file that:
+ *   - points every tool at the AGENTS.md spine (targets.spine),
+ *   - adds tool-specific invocation notes,
+ *   - lists agent/pack facts COMPUTED from the registry (counts are derived,
+ *     never typed by a human → adapters cannot drift or lie).
+ *
+ * Adapters sharing one on-disk file (e.g. gemini-cli + antigravity → GEMINI.md)
+ * are grouped into a single generated file with one notes block per tool.
+ *
+ * ADOPTED (load-bearing since v0.11.0): the repo-root adapter files
+ * (CLAUDE.md, GEMINI.md, .cursor/rules/bmad-plus.mdc, .codex/AGENTS.md,
+ * .opencode/AGENTS.md, CONVENTIONS.md) AND the spine itself (AGENTS.md) are
+ * GENERATED by this script — never hand-edited. Hand-authored project
+ * instructions live in tools/build/adapters.config.js and are injected into
+ * every generated file, so no tool loses instructions it used to have.
+ *
+ * Usage:
+ *   node tools/build/generate-adapters.js                 # write previews to
+ *                                                         # tools/build/generated-adapters/
+ *   node tools/build/generate-adapters.js --adopt         # write the REAL repo-root
+ *                                                         # adapters + spine
+ *   node tools/build/generate-adapters.js --adopt --force # overwrite root files that
+ *                                                         # lack the AUTO-GENERATED marker
+ *   node tools/build/generate-adapters.js --out-dir <dir> # write to <dir>
+ *   node tools/build/generate-adapters.js --print         # print all adapters to stdout
+ *   node tools/build/generate-adapters.js --check         # verify preview adapters match
+ *   node tools/build/generate-adapters.js --check --adopt # verify ROOT adapters + spine
+ *                                                         # match (exit 1 on drift)
+ *
+ * Author: Laurent Rochetta
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadRegistry, DEFAULT_REGISTRY_PATH } = require('./generate');
+const { PROJECT_INSTRUCTIONS } = require('./adapters.config');
+
+const DEFAULT_OUT_DIR = path.join(__dirname, 'generated-adapters');
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const GENERATED_MARKER = 'AUTO-GENERATED by tools/build/generate-adapters.js';
+
+/** Per-tool invocation notes. Unknown tools fall back to buildDefaultNotes(). */
+const TOOL_NOTES = {
+  'claude-code': [
+    'Claude Code loads `CLAUDE.md` from the project root automatically.',
+    'Activate an agent by saying its name (see the spine for the full roster).',
+    'Skills are loaded from `.agents/skills/`; auto-activation triggers live in `.agents/data/role-triggers.yaml`.',
+  ],
+  'gemini-cli': [
+    'Gemini CLI loads `GEMINI.md` from the project root automatically.',
+    'Activate an agent by saying its name (see the spine for the full roster).',
+  ],
+  antigravity: [
+    'Antigravity reads the same `GEMINI.md` file (detected via `.gemini/antigravity`).',
+    'Concurrency rule: coordinate with other agentic CLIs before writing — never edit the same files simultaneously.',
+  ],
+  cursor: [
+    'Cursor loads this rule from `.cursor/rules/` (`alwaysApply: true` in the frontmatter).',
+    'Treat the spine as the single source of truth; this rule only adds Cursor-specific notes.',
+  ],
+  'codex-cli': [
+    'Codex CLI follows the AGENTS.md open standard (https://agents.md/).',
+    'This file relays to the repo-root spine; prefer reading the spine directly when both exist.',
+  ],
+  opencode: [
+    'OpenCode follows the AGENTS.md open standard (https://agents.md/).',
+    'This file relays to the repo-root spine; prefer reading the spine directly when both exist.',
+  ],
+  aider: [
+    'Aider does not auto-load convention files: add `read: CONVENTIONS.md` to `.aider.conf.yml` or run `/read CONVENTIONS.md`.',
+    'Treat the spine as the single source of truth; this file only adds Aider-specific notes.',
+  ],
+};
+
+/** Fallback notes for adapter tools added to the registry later. */
+function buildDefaultNotes(tool, file) {
+  return [
+    `${tool} reads \`${file}\`.`,
+    'Treat the spine as the single source of truth; this file only adds tool-specific notes.',
+  ];
+}
+
+/**
+ * Validate the targets contract this generator relies on.
+ * (loadRegistry validates packs; targets are validated here.)
+ */
+function validateTargets(registry) {
+  const t = registry.targets;
+  if (!t || typeof t !== 'object') {
+    throw new Error('registry.yaml: missing top-level "targets" mapping');
+  }
+  if (typeof t.spine !== 'string' || t.spine === '') {
+    throw new Error('registry.yaml: targets.spine must be a non-empty string');
+  }
+  if (!Array.isArray(t.adapters) || t.adapters.length === 0) {
+    throw new Error('registry.yaml: targets.adapters must be a non-empty list');
+  }
+  t.adapters.forEach((a, i) => {
+    if (!a || typeof a.tool !== 'string' || a.tool === '' || typeof a.file !== 'string' || a.file === '') {
+      throw new Error(`registry.yaml: targets.adapters[${i}] must have string "tool" and "file"`);
+    }
+  });
+  return registry;
+}
+
+/** Sum of list lengths for a given key across a pack's categories. */
+function sumCategories(pack, key) {
+  if (!Array.isArray(pack.categories)) return 0;
+  return pack.categories.reduce((n, c) => n + (Array.isArray(c[key]) ? c[key].length : 0), 0);
+}
+
+/**
+ * Facts DERIVED from the registry — every number here is computed from the
+ * declared lists, so adapters can never contradict registry.yaml.
+ */
+function buildRegistryFacts(registry) {
+  const packEntries = Object.entries(registry.packs).sort((a, b) => a[1].order - b[1].order);
+  const packs = packEntries.map(([id, p]) => {
+    const fact = {
+      id,
+      name: p.cli.name,
+      displayName: p.display_name || p.cli.name,
+      desc: p.cli.desc,
+      agentCount: p.agents.length,
+      required: p.required === true,
+    };
+    const categoryAgents = sumCategories(p, 'agents');
+    const categoryWorkflows = sumCategories(p, 'workflows');
+    if (categoryAgents > 0) fact.categoryAgentCount = categoryAgents;
+    if (Array.isArray(p.sub_agents)) fact.subAgentCount = p.sub_agents.length;
+    if (Array.isArray(p.workflows)) fact.workflowCount = p.workflows.length;
+    if (categoryWorkflows > 0) fact.workflowCount = (fact.workflowCount || 0) + categoryWorkflows;
+    if (Array.isArray(p.compliance_tags) && p.compliance_tags.length > 0) {
+      fact.frameworkCount = p.compliance_tags.length;
+    }
+    return fact;
+  });
+
+  return {
+    product: {
+      code: registry.product.code,
+      displayName: registry.product.display_name,
+      version: registry.product.version,
+      derivedFrom: registry.product.derived_from,
+    },
+    spine: registry.targets.spine,
+    modelsSupported: [...(registry.targets.models_supported || [])],
+    packCount: packs.length,
+    installerAgentCount: packs.reduce((n, p) => n + p.agentCount, 0),
+    packs,
+  };
+}
+
+/** Group targets.adapters[] by output file → [{ file, tools: [tool, ...] }]. */
+function groupAdaptersByFile(registry) {
+  const byFile = new Map();
+  for (const { tool, file } of registry.targets.adapters) {
+    if (!byFile.has(file)) byFile.set(file, []);
+    const tools = byFile.get(file);
+    if (!tools.includes(tool)) tools.push(tool);
+  }
+  return [...byFile.entries()].map(([file, tools]) => ({ file, tools }));
+}
+
+/** Render the computed-facts section shared by every adapter. */
+function renderFactsSection(facts) {
+  const lines = [
+    '## Registry facts (computed from registry.yaml — never hand-typed)',
+    '',
+    `- Product: ${facts.product.displayName} v${facts.product.version} (derived from ${facts.product.derivedFrom})`,
+    `- Models supported: ${facts.modelsSupported.join(', ')} (model-agnostic by contract)`,
+    `- Packs (${facts.packCount}): ${facts.packs.map((p) => p.name).join(', ')}`,
+    `- Installer agents (${facts.installerAgentCount} across all packs):`,
+  ];
+  for (const p of facts.packs) {
+    const extras = [];
+    if (p.subAgentCount) extras.push(`${p.subAgentCount} sub-agents`);
+    if (p.categoryAgentCount) extras.push(`${p.categoryAgentCount} specialized agents`);
+    if (p.workflowCount) extras.push(`${p.workflowCount} workflows`);
+    if (p.frameworkCount) extras.push(`${p.frameworkCount} compliance frameworks`);
+    const suffix = extras.length > 0 ? ` — ${extras.join(', ')}` : '';
+    lines.push(
+      `  - ${p.name}${p.required ? ' (required)' : ''}: ${p.agentCount} installer agent${p.agentCount === 1 ? '' : 's'} — ${p.desc}${suffix}`
+    );
+  }
+  return lines;
+}
+
+/**
+ * Render the project-context + hand-authored instruction block shared by the
+ * spine and every adapter. The context sentence is DERIVED from registry
+ * facts (product name / upstream), the instruction sections come verbatim
+ * from tools/build/adapters.config.js (the one hand-authored source).
+ */
+function renderProjectInstructions(facts) {
+  return [
+    '## Project Context',
+    '',
+    `This project uses ${facts.product.displayName}, an augmented AI-driven development framework.`,
+    `Based on ${facts.product.derivedFrom} with multi-role agents, autopilot mode, and parallel execution.`,
+    '',
+    '<!-- Hand-authored project instructions — single source: tools/build/adapters.config.js. -->',
+    '<!-- Edit the config, then regenerate; never edit this file directly. -->',
+    '',
+    ...PROJECT_INSTRUCTIONS,
+  ];
+}
+
+/** Render the shared key-commands footer. */
+function renderKeyCommands() {
+  return [
+    '## Key commands',
+    '',
+    '- `bmad-help` — Show all available agents and skills',
+    '- `autopilot` — Launch the orchestrator (Nexus) in full pipeline mode',
+    '- `parallel` — Enable parallel multi-agent execution',
+  ];
+}
+
+/**
+ * Render ONE adapter file body (pure — no clock, no randomness, no I/O).
+ *
+ * @param {object} facts - buildRegistryFacts() output
+ * @param {string} file  - adapter file path as declared in the registry
+ * @param {string[]} tools - tools consuming this file
+ * @returns {string} full file content
+ */
+function renderAdapterContent(facts, file, tools) {
+  const spine = facts.spine;
+  const toolLabel = tools.join(' + ');
+  const lines = [];
+
+  if (file.endsWith('.mdc')) {
+    lines.push(
+      '---',
+      `description: "${facts.product.displayName} agents adapter (generated from registry.yaml)"`,
+      'alwaysApply: true',
+      '---',
+      ''
+    );
+  }
+
+  lines.push(
+    `<!-- AUTO-GENERATED by tools/build/generate-adapters.js — DO NOT EDIT. -->`,
+    `<!-- Source of truth: registry.yaml → spine ${spine}. Regenerate: node tools/build/generate-adapters.js -->`,
+    '',
+    `# ${facts.product.displayName} — Adapter for ${toolLabel}`,
+    '',
+    `This file is a THIN adapter. The single source of truth for agents, packs,`,
+    `skills, and workflows is the spine file: **${spine}** (project root).`,
+    `Read ${spine} first; this adapter only adds tool-specific invocation notes.`,
+    ''
+  );
+
+  for (const tool of tools) {
+    lines.push(`## Tool notes — ${tool}`, '');
+    for (const note of TOOL_NOTES[tool] || buildDefaultNotes(tool, file)) {
+      lines.push(`- ${note}`);
+    }
+    lines.push('');
+  }
+
+  // Full project instructions are inlined in EVERY adapter (not only the
+  // spine) because most tools auto-load only their own file — a thin pointer
+  // would silently lose behavior for tools that never open the spine.
+  lines.push(...renderProjectInstructions(facts), '');
+
+  lines.push(...renderFactsSection(facts));
+
+  lines.push('', ...renderKeyCommands(), '');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render the SPINE file (targets.spine, i.e. AGENTS.md) — the single source
+ * of truth document following the AGENTS.md open standard (https://agents.md/).
+ * Pure: derived facts from the registry + hand-authored config sections.
+ */
+function renderSpineContent(facts) {
+  const lines = [
+    `<!-- AUTO-GENERATED by tools/build/generate-adapters.js — DO NOT EDIT. -->`,
+    `<!-- Sources of truth: registry.yaml (facts) + tools/build/adapters.config.js (hand-authored sections). -->`,
+    `<!-- Regenerate: node tools/build/generate-adapters.js --adopt -->`,
+    '',
+    `# ${facts.product.displayName} — Agent Spine`,
+    '',
+    `This file is the SPINE: the single source of truth for agents, packs, skills,`,
+    `and workflows, following the AGENTS.md open standard (https://agents.md/).`,
+    `Tool-specific adapter files (CLAUDE.md, GEMINI.md, .cursor/rules/, .codex/,`,
+    `.opencode/, CONVENTIONS.md) are generated from the same registry and only add`,
+    `tool-specific invocation notes.`,
+    '',
+    ...renderProjectInstructions(facts),
+    '',
+    ...renderFactsSection(facts),
+    '',
+    ...renderKeyCommands(),
+    '',
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Generate every adapter from a loaded registry.
+ * @returns {Array<{ file: string, tools: string[], content: string }>}
+ */
+function generateAllAdapters(registry) {
+  validateTargets(registry);
+  const facts = buildRegistryFacts(registry);
+  return groupAdaptersByFile(registry).map(({ file, tools }) => ({
+    file,
+    tools,
+    content: renderAdapterContent(facts, file, tools),
+  }));
+}
+
+/**
+ * Generate the FULL file set: the spine (targets.spine) + every adapter.
+ * This is what adoption/preview/check operate on.
+ * @returns {Array<{ file: string, tools: string[], spine?: true, content: string }>}
+ */
+function generateAllFiles(registry) {
+  validateTargets(registry);
+  const facts = buildRegistryFacts(registry);
+  const spine = {
+    file: registry.targets.spine,
+    tools: ['spine'],
+    spine: true,
+    content: renderSpineContent(facts),
+  };
+  return [spine, ...generateAllAdapters(registry)];
+}
+
+/**
+ * Adoption guard: list on-disk targets under outDir that exist but do NOT
+ * carry the AUTO-GENERATED marker (i.e. hand-authored files that would be
+ * clobbered). Overwriting them requires an explicit --force.
+ */
+function listAdoptionBlockers(outDir, files) {
+  const blockers = [];
+  for (const { file } of files) {
+    const target = path.join(outDir, file);
+    if (!fs.existsSync(target)) continue;
+    const current = fs.readFileSync(target, 'utf8');
+    if (!current.includes(GENERATED_MARKER)) blockers.push(file);
+  }
+  return blockers;
+}
+
+/** Write generated spine + adapters under outDir, preserving relative paths. */
+function writeAdapters({ registryPath = DEFAULT_REGISTRY_PATH, outDir = DEFAULT_OUT_DIR } = {}) {
+  const files = generateAllFiles(loadRegistry(registryPath));
+  const written = [];
+  for (const { file, content } of files) {
+    const target = path.join(outDir, file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf8');
+    written.push(target);
+  }
+  return written;
+}
+
+/**
+ * `--check` mode: prove on-disk adapter files under outDir match what the
+ * registry generates. Returns { ok, mismatches } — never throws on drift.
+ */
+// Compare content ignoring line-ending style: git may rewrite LF→CRLF on
+// checkout (Windows), so a byte comparison would false-positive "drift" on a
+// fresh clone even when the content is identical.
+const normalizeEol = (s) => s.replace(/\r\n/g, '\n');
+
+function check({ registryPath = DEFAULT_REGISTRY_PATH, outDir = DEFAULT_OUT_DIR } = {}) {
+  const files = generateAllFiles(loadRegistry(registryPath));
+  const mismatches = [];
+  for (const { file, content } of files) {
+    const target = path.join(outDir, file);
+    if (!fs.existsSync(target)) {
+      mismatches.push(`${file}: missing on disk (expected at ${target})`);
+      continue;
+    }
+    const current = fs.readFileSync(target, 'utf8');
+    if (normalizeEol(current) !== normalizeEol(content)) {
+      mismatches.push(`${file}: content differs from what registry.yaml generates`);
+    }
+  }
+  return { ok: mismatches.length === 0, mismatches };
+}
+
+/* ── CLI ────────────────────────────────────────────────────────────────── */
+
+function parseOutDir(args) {
+  const idx = args.indexOf('--out-dir');
+  if (args.includes('--adopt')) {
+    if (idx !== -1) throw new Error('--adopt and --out-dir are mutually exclusive (--adopt targets the repo root)');
+    return REPO_ROOT;
+  }
+  if (idx === -1) return DEFAULT_OUT_DIR;
+  const value = args[idx + 1];
+  if (!value) throw new Error('--out-dir requires a directory path');
+  return path.resolve(value);
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  let outDir;
+  try {
+    outDir = parseOutDir(args);
+  } catch (err) {
+    console.error(err.message);
+    return 1;
+  }
+  const adopting = args.includes('--adopt');
+  const label = adopting ? 'root adapters + spine' : 'adapters';
+
+  if (args.includes('--check')) {
+    const result = check({ outDir });
+    if (result.ok) {
+      console.log(`OK — ${label} under ${outDir} match registry.yaml exactly (no drift).`);
+      return 0;
+    }
+    console.error(`DRIFT DETECTED between registry.yaml and ${label} under ${outDir}:`);
+    for (const m of result.mismatches) console.error(`  - ${m}`);
+    console.error(
+      'Fix: node tools/build/generate-adapters.js' +
+        (adopting ? ' --adopt' : outDir === DEFAULT_OUT_DIR ? '' : ` --out-dir ${outDir}`)
+    );
+    return 1;
+  }
+
+  if (args.includes('--print')) {
+    for (const { file, content } of generateAllFiles(loadRegistry())) {
+      console.log(`──── ${file} ────`);
+      console.log(content);
+    }
+    return 0;
+  }
+
+  if (adopting && !args.includes('--force')) {
+    const blockers = listAdoptionBlockers(outDir, generateAllFiles(loadRegistry()));
+    if (blockers.length > 0) {
+      console.error('REFUSING to overwrite hand-authored root files (no AUTO-GENERATED marker):');
+      for (const b of blockers) console.error(`  - ${b}`);
+      console.error('Fold their content into tools/build/adapters.config.js (or registry.yaml),');
+      console.error('then re-run with: node tools/build/generate-adapters.js --adopt --force');
+      return 1;
+    }
+  }
+
+  const written = writeAdapters({ outDir });
+  for (const target of written) console.log(`Generated ${target}`);
+  return 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv);
+}
+
+module.exports = {
+  DEFAULT_OUT_DIR,
+  REPO_ROOT,
+  GENERATED_MARKER,
+  TOOL_NOTES,
+  validateTargets,
+  buildRegistryFacts,
+  groupAdaptersByFile,
+  renderFactsSection,
+  renderProjectInstructions,
+  renderKeyCommands,
+  renderAdapterContent,
+  renderSpineContent,
+  generateAllAdapters,
+  generateAllFiles,
+  listAdoptionBlockers,
+  writeAdapters,
+  check,
+  main,
+};