bmad-plus 0.12.2 → 0.13.0

package/tools/build/generate-adapters.js

@@ -27,6 +27,9 @@
  *   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 --target <dir>  # user spine + adapters
+ *     [--packs core,memory] [--tools claude-code,cursor] [--user-name Alice]
+ *     [--language English] [--force]                     # explicit foreign overwrite
  *   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
@@ -39,12 +42,13 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { loadRegistry, DEFAULT_REGISTRY_PATH } = require('./generate');
-const { PROJECT_INSTRUCTIONS } = require('./adapters.config');
+const { loadRegistry, buildDerived, DEFAULT_REGISTRY_PATH } = require('./generate');
+const { PROJECT_INSTRUCTIONS, MEMORY_INSTRUCTIONS, UPDATE_INSTRUCTIONS, TOOL_METADATA } = 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';
+const USER_CONFIG_MARKER = 'BMAD+ installed project configuration';
 
 /** Per-tool invocation notes. Unknown tools fall back to buildDefaultNotes(). */
 const TOOL_NOTES = {
@@ -99,6 +103,7 @@ function validateTargets(registry) {
   if (typeof t.spine !== 'string' || t.spine === '') {
     throw new Error('registry.yaml: targets.spine must be a non-empty string');
   }
+  validateRelativeFile(t.spine);
   if (!Array.isArray(t.adapters) || t.adapters.length === 0) {
     throw new Error('registry.yaml: targets.adapters must be a non-empty list');
   }
@@ -106,58 +111,55 @@ function validateTargets(registry) {
     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"`);
     }
+    validateRelativeFile(a.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,
+/** Convert the canonical derivation into the adapter presentation shape. */
+function factsFromDerived(derived, packs = derived.packOrder) {
+  const selected = packs.map(id => {
+    const pack = derived.packs[id];
+    return {
+      id, name: pack.name, displayName: pack.displayName, desc: pack.desc,
+      required: pack.required, agentCount: pack.installerAgentCount,
+      categoryAgentCount: pack.categoryAgentCount, subAgentCount: pack.subAgentCount,
+      workflowCount: pack.workflowCount, frameworkCount: pack.frameworkCount,
+      personas: pack.personas,
     };
-    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,
+    product: derived.product,
+    spine: derived.targets.spine,
+    modelsSupported: derived.targets.models_supported,
+    packCount: selected.length,
+    installerAgentCount: packs.length === derived.packOrder.length
+      ? derived.installerAgents
+      : selected.reduce((total, pack) => total + pack.agentCount, 0),
+    packs: selected,
   };
 }
 
+/** Counts are calculated only by buildDerived, never from raw lists here. */
+function buildRegistryFacts(registry) {
+  return factsFromDerived(buildDerived(registry));
+}
+
+/** Render registry-owned persona metadata for the selected packs. */
+function renderRoster(facts) {
+  const lines = ['## Agents', '', 'To activate an agent, say its name or persona:', ''];
+  for (const pack of facts.packs) {
+    for (const persona of pack.personas || []) {
+      const identity = persona.alias
+        ? '(' + persona.alias + ') — ' + persona.role
+        : '(' + persona.role + ')';
+      lines.push('- **' + persona.name + '** ' + identity + ' — ' + persona.description +
+        (pack.required ? '' : ' (' + pack.name + ')'));
+    }
+  }
+  return lines;
+}
+
 /** Group targets.adapters[] by output file → [{ file, tools: [tool, ...] }]. */
 function groupAdaptersByFile(registry) {
   const byFile = new Map();
@@ -209,6 +211,8 @@ function renderProjectInstructions(facts) {
     '<!-- Hand-authored project instructions — single source: tools/build/adapters.config.js. -->',
     '<!-- Edit the config, then regenerate; never edit this file directly. -->',
     '',
+    ...renderRoster(facts),
+    '',
     ...PROJECT_INSTRUCTIONS,
   ];
 }
@@ -339,18 +343,167 @@ function generateAllFiles(registry) {
   return [spine, ...generateAllAdapters(registry)];
 }
 
+/** Installable tools and paths come from the registry; only detection is local. */
+function buildIDEConfigs(derived) {
+  validateTargets({ targets: derived.targets });
+  return Object.fromEntries(derived.targets.adapters.map(({ tool, file }) => [
+    tool, { name: TOOL_METADATA[tool]?.name || tool, configFile: file,
+      detect: [...(TOOL_METADATA[tool]?.detect || [])] },
+  ]));
+}
+
+function selectedPacks(derived, packs) {
+  if (packs !== undefined && !Array.isArray(packs)) throw new Error('packs must be an array of pack IDs');
+  const selected = new Set(packs === undefined ? derived.packOrder : packs);
+  for (const id of selected) {
+    if (!Object.hasOwn(derived.packs, id)) throw new Error('Unknown pack: ' + id);
+  }
+  for (const id of derived.packOrder) if (derived.packs[id].required) selected.add(id);
+  return derived.packOrder.filter(id => selected.has(id));
+}
+
+function renderUserSections(derived, { packs, userName = 'Developer', language = 'English' } = {}) {
+  const ids = selectedPacks(derived, packs);
+  const facts = factsFromDerived(derived, ids);
+  const lines = [
+    '## 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.',
+    '', ...renderRoster(facts), '',
+    '## Skills', '',
+    '- Load skills from `.agents/skills/`.',
+    '- Each agent has a SKILL.md with capabilities, activation protocol, and role-switching rules.',
+    '- Auto-activation triggers: `.agents/data/role-triggers.yaml`.',
+    '', '## Communication', '',
+    '- User name: ' + String(userName).replace(/[\r\n]/g, ' '),
+    '- Default language: ' + String(language).replace(/[\r\n]/g, ' ') + ' for user-facing content, English for code and technical docs.',
+  ];
+  if (ids.includes('memory')) lines.push('', ...MEMORY_INSTRUCTIONS);
+  lines.push('', ...UPDATE_INSTRUCTIONS, '', ...renderFactsSection(facts), '', ...renderKeyCommands());
+  return lines;
+}
+
+function userMarkerLines() {
+  return [
+    '<!-- ' + GENERATED_MARKER + ' — DO NOT EDIT. -->',
+    '<!-- ' + USER_CONFIG_MARKER + ' -->',
+    '<!-- Refresh installed adapters with: npx bmad-plus update -->',
+  ];
+}
+
+/** Pure user spine renderer; DERIVED also ships in the npm package. */
+function renderUserConfig(derived, options = {}) {
+  validateTargets({ targets: derived.targets });
+  return [
+    ...userMarkerLines(), '',
+    '# ' + derived.product.displayName + ' — Agent Spine', '',
+    'This file is the common project instruction spine for the installed ' + derived.product.displayName + ' tools.', '',
+    ...renderUserSections(derived, options), '',
+  ].join('\n');
+}
+
+/** Pure render of the common spine and every selected registry adapter. */
+function generateUserFiles(derived, options = {}) {
+  validateTargets({ targets: derived.targets });
+  const available = derived.targets.adapters.map(adapter => adapter.tool);
+  const requested = options.tools === undefined ? available : options.tools;
+  if (!Array.isArray(requested)) throw new Error('tools must be an array of tool IDs');
+  for (const tool of requested) {
+    if (!available.includes(tool)) throw new Error('Unknown tool: ' + tool);
+  }
+  const targets = { ...derived.targets,
+    adapters: derived.targets.adapters.filter(adapter => requested.includes(adapter.tool)) };
+  const files = [{ file: targets.spine, tools: ['spine'], spine: true,
+    content: renderUserConfig(derived, options) }];
+  for (const { file, tools } of groupAdaptersByFile({ targets })) {
+    if (file === targets.spine) continue;
+    const reference = path.posix.relative(path.posix.dirname(file), targets.spine);
+    const lines = [];
+    if (file.endsWith('.mdc')) lines.push('---',
+      'description: "' + derived.product.displayName + ' agents adapter"', 'alwaysApply: true', '---', '');
+    lines.push(...userMarkerLines(), '',
+      '# ' + derived.product.displayName + ' — Adapter for ' + tools.join(' + '), '',
+      'Read the project spine first: [' + targets.spine + '](' + reference + ').',
+      'Paths in the shared project instructions below are relative to the project root.', '');
+    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('');
+    }
+    lines.push(...renderUserSections(derived, options), '');
+    files.push({ file, tools, content: lines.join('\n') });
+  }
+  return files;
+}
+
+/** Refuse portable-path escapes even when generated input has been modified. */
+function validateRelativeFile(file) {
+  if (typeof file !== 'string' || !file || /[\\:]/.test(file) || file.includes('\0') ||
+      path.posix.isAbsolute(file) || file.split('/').some(part => !part || part === '.' || part === '..')) {
+    throw new Error('Adapter file must be a relative project path: ' + file);
+  }
+}
+
+/** Check existing ancestors before any write; Windows junctions are symlinks here. */
+function safeTarget(outDir, file) {
+  validateRelativeFile(file);
+  const root = path.resolve(outDir);
+  const target = path.resolve(root, file);
+  const relative = path.relative(root, target);
+  if (!relative || relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    throw new Error('Adapter path escapes the target project: ' + file);
+  }
+  let current = path.parse(target).root;
+  for (const part of target.slice(current.length).split(path.sep)) {
+    current = path.join(current, part);
+    let stat;
+    try { stat = fs.lstatSync(current); } catch (error) {
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) throw new Error('Adapter path contains a symlink or junction: ' + current);
+    if (current === target && !stat.isFile()) throw new Error('Adapter target is not a regular file: ' + current);
+    if (current !== target && !stat.isDirectory()) throw new Error('Adapter parent is not a directory: ' + current);
+  }
+  return target;
+}
+
+/** Preflight the whole batch to avoid partial writes on a later unsafe path. */
+function writeFiles(outDir, files) {
+  for (const { file } of files) safeTarget(outDir, file);
+  return files.map(({ file, content }) => {
+    const target = safeTarget(outDir, file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    safeTarget(outDir, file);
+    fs.writeFileSync(target, content, 'utf8');
+    return target;
+  });
+}
+
+function writeUserAdapters({ outDir, derived = require('../cli/lib/packs').DERIVED,
+  packs, userName, language, tools, force = false } = {}) {
+  if (!outDir) throw new Error('A target project directory is required');
+  const files = generateUserFiles(derived, { packs, userName, language, tools });
+  const blockers = listAdoptionBlockers(outDir, files, USER_CONFIG_MARKER);
+  if (blockers.length && !force) {
+    throw new Error('REFUSING to overwrite files not owned by this user configuration: ' +
+      blockers.join(', ') + '. Review them and use --force to replace them explicitly.');
+  }
+  return writeFiles(outDir, files);
+}
+
 /**
  * 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) {
+function listAdoptionBlockers(outDir, files, marker = GENERATED_MARKER) {
   const blockers = [];
   for (const { file } of files) {
-    const target = path.join(outDir, file);
+    const target = safeTarget(outDir, file);
     if (!fs.existsSync(target)) continue;
     const current = fs.readFileSync(target, 'utf8');
-    if (!current.includes(GENERATED_MARKER)) blockers.push(file);
+    if (!current.includes(GENERATED_MARKER) || !current.includes(marker)) blockers.push(file);
   }
   return blockers;
 }
@@ -358,14 +511,7 @@ function listAdoptionBlockers(outDir, files) {
 /** 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;
+  return writeFiles(outDir, files);
 }
 
 /**
@@ -398,13 +544,20 @@ function check({ registryPath = DEFAULT_REGISTRY_PATH, outDir = DEFAULT_OUT_DIR
 
 function parseOutDir(args) {
   const idx = args.indexOf('--out-dir');
+  const targetIdx = args.indexOf('--target');
+  if (targetIdx !== -1) {
+    if (args.includes('--adopt') || idx !== -1) throw new Error('--target, --adopt and --out-dir are mutually exclusive');
+    const value = args[targetIdx + 1];
+    if (!value || value.startsWith('--')) throw new Error('--target requires a directory path');
+    return path.resolve(value);
+  }
   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');
+  if (!value || value.startsWith('--')) throw new Error('--out-dir requires a directory path');
   return path.resolve(value);
 }
 
@@ -417,6 +570,42 @@ function main(argv) {
     console.error(err.message);
     return 1;
   }
+  if (args.includes('--target')) {
+    try {
+      const option = (name) => {
+        const index = args.indexOf(name);
+        if (index === -1) return undefined;
+        const value = args[index + 1];
+        if (!value || value.startsWith('--')) throw new Error(name + ' requires a value');
+        return value;
+      };
+      const packs = option('--packs');
+      const tools = option('--tools');
+      const options = { packs: !packs || packs === 'all' ? undefined : packs.split(',').map(value => value.trim()),
+        tools: !tools || tools === 'all' ? undefined : tools === 'none' ? [] : tools.split(',').map(value => value.trim()),
+        userName: option('--user-name'), language: option('--language') };
+      const derived = require('../cli/lib/packs').DERIVED;
+      const files = generateUserFiles(derived, options);
+      if (args.includes('--print')) {
+        for (const { file, content } of files) console.log(file + '\n' + content);
+        return 0;
+      }
+      if (args.includes('--check')) {
+        const mismatches = files.filter(({ file, content }) => {
+          const target = safeTarget(outDir, file);
+          return !fs.existsSync(target) || normalizeEol(fs.readFileSync(target, 'utf8')) !== normalizeEol(content);
+        });
+        if (mismatches.length) console.error('User adapter drift: ' + mismatches.map(entry => entry.file).join(', '));
+        return mismatches.length ? 1 : 0;
+      }
+      const written = writeUserAdapters({ outDir, derived, ...options, force: args.includes('--force') });
+      for (const target of written) console.log('Generated ' + target);
+      return 0;
+    } catch (error) {
+      console.error(error.message);
+      return 1;
+    }
+  }
   const adopting = args.includes('--adopt');
   const label = adopting ? 'root adapters + spine' : 'adapters';
 
@@ -467,6 +656,13 @@ module.exports = {
   DEFAULT_OUT_DIR,
   REPO_ROOT,
   GENERATED_MARKER,
+  USER_CONFIG_MARKER,
+  buildIDEConfigs,
+  get IDE_CONFIGS() { return buildIDEConfigs(require('../cli/lib/packs').DERIVED); },
+  renderUserConfig,
+  generateUserFiles,
+  writeUserAdapters,
+  safeTarget,
   TOOL_NOTES,
   validateTargets,
   buildRegistryFacts,