bmad-plus 0.21.0 → 0.23.0

package/tools/build/generate.js

@@ -26,6 +26,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { isDeepStrictEqual } = require('node:util');
 const yaml = require('js-yaml');
+const { validateIntake } = require('./intake-contract');
 
 const REPO_ROOT = path.join(__dirname, '..', '..');
 const DEFAULT_REGISTRY_PATH = path.join(REPO_ROOT, 'registry.yaml');
@@ -39,6 +40,10 @@ const OWNED_COUNT_RE =
   /(?<![\w.-])\d+\+?[\s-]+(?:[A-Za-zÀ-ÿ-]+\s+){0,6}(?:agents?|skills?|workflows?|packs?|frameworks?|languages?|reference files)\b/gi;
 const STANDARD_PREFIX_RE =
   /\b(?:ISO(?:\/IEC)?|IEC|SOC|NIST(?: SP)?|PCI(?: DSS)?|WCAG|Section)\s*$/i;
+const SKILL_ID_RE = /^[a-z][a-z0-9-]*$/;
+const PACKAGE_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const PIPELINE_GATES = ['require_approval', 'notify_only', 'auto'];
 
 function hasOwnedCount(value) {
   return [...value.matchAll(OWNED_COUNT_RE)].some(
@@ -60,13 +65,16 @@ function assertResourcePath(file, where) {
 /** Installed entry points, derived from the same layout used by pack-copy.js. */
 function buildRequiredResources(pack, id = pack.pack_dir) {
   const where = `registry.yaml: pack "${id}"`;
+  const externalSkills = (pack.external_module || {}).skills || [];
   for (const file of [
     ...pack.agents,
     ...(pack.skills || []),
+    ...externalSkills,
     ...(pack.data || []),
     ...((pack.doctor || {}).pack_agents || []),
     ...((pack.doctor || {}).required_resources || []),
     ...(pack.python_entry ? [pack.python_entry] : []),
+    ...(pack.intake ? [pack.intake] : []),
   ]) {
     assertResourcePath(file, where);
   }
@@ -79,6 +87,7 @@ function buildRequiredResources(pack, id = pack.pack_dir) {
     );
   }
   resources.push(...(pack.skills || []).map((id) => `.agents/skills/${id}/SKILL.md`));
+  resources.push(...externalSkills.map((id) => `.agents/skills/${id}/SKILL.md`));
   resources.push(...(pack.data || []).map((file) => `.agents/data/${file}`));
   resources.push(
     ...((pack.doctor || {}).required_resources || []).map(
@@ -86,10 +95,137 @@ function buildRequiredResources(pack, id = pack.pack_dir) {
     )
   );
   if (pack.python_entry) resources.push(`.agents/skills/${pack.pack_dir}/${pack.python_entry}`);
+  if (pack.intake) resources.push(`.agents/skills/${pack.pack_dir}/${pack.intake}`);
   for (const file of resources) assertResourcePath(file, where);
   return [...new Set(resources)];
 }
 
+function assertSkillIds(list, where) {
+  if (
+    !Array.isArray(list) ||
+    list.length === 0 ||
+    list.some((id) => typeof id !== 'string' || !SKILL_ID_RE.test(id)) ||
+    new Set(list).size !== list.length
+  ) {
+    throw new Error(`${where}: must be a non-empty list of distinct skill ids`);
+  }
+}
+
+/** Structural contract of `external_module` (§5.2); the package itself is checked by --check. */
+function validateExternalModule(pack, where) {
+  const module = pack.external_module;
+  if (module === undefined) return;
+  if (
+    !module ||
+    typeof module !== 'object' ||
+    Object.keys(module).some((key) => !['package', 'version', 'skills'].includes(key))
+  ) {
+    throw new Error(`${where}: external_module takes exactly package, version and skills`);
+  }
+  if (typeof module.package !== 'string' || !PACKAGE_NAME_RE.test(module.package)) {
+    throw new Error(`${where}: external_module.package must be an npm package name`);
+  }
+  if (typeof module.version !== 'string' || !EXACT_VERSION_RE.test(module.version)) {
+    throw new Error(`${where}: external_module.version must be an exact version`);
+  }
+  assertSkillIds(module.skills, `${where}: external_module.skills`);
+  for (const id of module.skills) {
+    if ((pack.skills || []).includes(id)) {
+      throw new Error(`${where}: skill ${id} is both shipped in-tree and taken from the module`);
+    }
+  }
+}
+
+/** Structural contract of `pipelines` (§5.3): every step names one real thing of the pack. */
+function validatePipelines(pack, where) {
+  if (pack.pipelines === undefined) return;
+  if (!Array.isArray(pack.pipelines) || pack.pipelines.length === 0) {
+    throw new Error(`${where}: pipelines must be a non-empty list`);
+  }
+  const workflows = new Set([
+    ...(pack.workflows || []),
+    ...(pack.categories || []).flatMap((category) => category.workflows || []),
+  ]);
+  const agents = new Set([...pack.agents, ...(pack.sub_agents || [])]);
+  const ids = new Set();
+  for (const pipeline of pack.pipelines) {
+    if (
+      !pipeline ||
+      typeof pipeline !== 'object' ||
+      Object.keys(pipeline).some((key) => !['id', 'title', 'steps'].includes(key))
+    ) {
+      throw new Error(`${where}: each pipeline takes exactly id, title and steps`);
+    }
+    if (typeof pipeline.id !== 'string' || !SKILL_ID_RE.test(pipeline.id) || ids.has(pipeline.id)) {
+      throw new Error(`${where}: pipeline ids must be distinct lowercase slugs`);
+    }
+    ids.add(pipeline.id);
+    const label = `${where}: pipeline ${pipeline.id}`;
+    if (typeof pipeline.title !== 'string' || !pipeline.title.trim()) {
+      throw new Error(`${label}: needs a title`);
+    }
+    if (!Array.isArray(pipeline.steps) || pipeline.steps.length === 0) {
+      throw new Error(`${label}: needs at least one step`);
+    }
+    pipeline.steps.forEach((step, index) => {
+      const at = `${label}: step ${index + 1}`;
+      if (
+        !step ||
+        typeof step !== 'object' ||
+        Object.keys(step).some((key) => !['workflow', 'agent', 'gate'].includes(key))
+      ) {
+        throw new Error(`${at}: takes workflow or agent, and gate`);
+      }
+      if ((step.workflow === undefined) === (step.agent === undefined)) {
+        throw new Error(`${at}: names exactly one of workflow or agent`);
+      }
+      if (step.workflow !== undefined && !workflows.has(step.workflow)) {
+        throw new Error(`${at}: workflow ${step.workflow} is not declared by the pack`);
+      }
+      if (step.agent !== undefined && !agents.has(step.agent)) {
+        throw new Error(`${at}: agent ${step.agent} is not declared by the pack`);
+      }
+      if (!PIPELINE_GATES.includes(step.gate)) {
+        throw new Error(`${at}: gate must be one of ${PIPELINE_GATES.join('|')}`);
+      }
+    });
+  }
+}
+
+/** `intake` names a file inside the pack directory (§5.4); its content is checked by --check. */
+function validateIntakeField(pack, where) {
+  if (pack.intake === undefined) return;
+  if (typeof pack.intake !== 'string' || !pack.intake) {
+    throw new Error(`${where}: intake must be a file path relative to pack_dir`);
+  }
+  if (!pack.pack_dir) throw new Error(`${where}: intake needs a pack_dir to live in`);
+}
+
+/** Every `uses_skills` id (§5.1) is a skill some pack ships in-tree or through its module. */
+function validateUsesSkills(registry) {
+  const known = new Set();
+  for (const pack of Object.values(registry.packs)) {
+    for (const id of pack.skills || []) known.add(id);
+    for (const id of (pack.external_module || {}).skills || []) known.add(id);
+  }
+  const resolve = (list, where) => {
+    if (list === undefined) return;
+    assertSkillIds(list, where);
+    for (const id of list) {
+      if (!known.has(id)) throw new Error(`${where}: skill ${id} is shipped by no pack`);
+    }
+  };
+  for (const [id, pack] of Object.entries(registry.packs)) {
+    resolve(pack.uses_skills, `registry.yaml: pack "${id}": uses_skills`);
+    for (const persona of pack.personas || []) {
+      resolve(
+        persona.uses_skills,
+        `registry.yaml: pack "${id}": persona ${persona.id}: uses_skills`
+      );
+    }
+  }
+}
+
 /**
  * Validate the minimal contract the generator relies on.
  * Throws with a precise message on the first violation.
@@ -160,6 +296,15 @@ function validateRegistry(registry) {
     ) {
       throw new Error(`${where}: runtime must declare known runtimes`);
     }
+    validateExternalModule(pack, where);
+    validatePipelines(pack, where);
+    validateIntakeField(pack, where);
+    if (
+      pack.cohabitation_warning !== undefined &&
+      (typeof pack.cohabitation_warning !== 'string' || !pack.cohabitation_warning.trim())
+    ) {
+      throw new Error(`${where}: cohabitation_warning must be a non-empty sentence`);
+    }
     buildRequiredResources(pack, id);
     if (pack.personas !== undefined) {
       if (!Array.isArray(pack.personas)) throw new Error(`${where}: personas must be a list`);
@@ -183,6 +328,7 @@ function validateRegistry(registry) {
       }
     }
   }
+  validateUsesSkills(registry);
   const integration = registry.targets?.integration;
   if (
     integration?.execution !== 'host-managed' ||
@@ -242,6 +388,21 @@ function buildPackOrder(registry) {
   return sortedPackEntries(registry).map(([id]) => id);
 }
 
+function externalModuleFacts({ package: name, version, skills }) {
+  return { package: name, version, skills: [...skills] };
+}
+
+function pipelineFacts(pipelines) {
+  return pipelines.map(({ id, title, steps }) => ({
+    id,
+    title,
+    steps: steps.map((step) => ({
+      ...(step.workflow !== undefined ? { workflow: step.workflow } : { agent: step.agent }),
+      gate: step.gate,
+    })),
+  }));
+}
+
 /**
  * Generate the PACKS object with the exact shape of tools/cli/lib/packs.js.
  * Key-presence rules mirror the hand-written module:
@@ -262,10 +423,14 @@ function buildPacks(registry) {
     };
     if ('data' in p) entry.data = [...p.data];
     if (p.external_package) entry.externalPackage = p.external_package;
+    if (p.external_module) entry.externalModule = externalModuleFacts(p.external_module);
     if (p.pack_dir) {
       entry.packDir = p.pack_dir;
       entry.packSrcDir = p.pack_src_dir || 'packs';
     }
+    if (p.uses_skills) entry.usesSkills = [...p.uses_skills];
+    if (p.pipelines) entry.pipelines = pipelineFacts(p.pipelines);
+    if (p.intake) entry.intake = p.intake;
     if (p.required === true) entry.required = true;
     entry.desc = derived.packs[id].desc;
     packs[id] = entry;
@@ -302,6 +467,19 @@ function renderSummary(pack, derived, field = 'summary') {
   });
 }
 
+/**
+ * The package flows of the data-handling doctrine that can leave the machine, with their
+ * consent basis; maintainer services are not installed and stay out. verify-egress.js owns
+ * the doctrine's schema and its agreement with the code.
+ */
+function buildDataHandling(registry) {
+  const doctrine = registry.data_handling || {};
+  const services = new Set((doctrine.services || []).map((service) => service.id));
+  return (doctrine.flows || [])
+    .filter((flow) => flow.egress !== 'none' && !services.has(flow.component))
+    .map((flow) => ({ id: flow.id, component: flow.component, consent: flow.consent?.basis }));
+}
+
 /** The one derivation engine; its JSON result is shipped for runtime consumers. */
 function buildDerived(registry, { sourceRoot = path.join(REPO_ROOT, 'src', 'bmad-plus') } = {}) {
   const packs = {};
@@ -339,13 +517,23 @@ function buildDerived(registry, { sourceRoot = path.join(REPO_ROOT, 'src', 'bmad
       categoryAgentCounts,
       runtimes: [...pack.runtime],
       requiredResources: buildRequiredResources(pack, id),
-      personas: (pack.personas || []).map(({ id, name, role, description, alias }) => ({
-        id,
-        name,
-        role,
-        description,
-        ...(alias ? { alias } : {}),
-      })),
+      personas: (pack.personas || []).map(
+        ({ id, name, role, description, alias, uses_skills }) => ({
+          id,
+          name,
+          role,
+          description,
+          ...(alias ? { alias } : {}),
+          ...(uses_skills ? { usesSkills: [...uses_skills] } : {}),
+        })
+      ),
+      ...(pack.uses_skills ? { usesSkills: [...pack.uses_skills] } : {}),
+      ...(pack.external_module
+        ? { externalModule: externalModuleFacts(pack.external_module) }
+        : {}),
+      ...(pack.pipelines ? { pipelines: pipelineFacts(pack.pipelines) } : {}),
+      ...(pack.intake ? { intake: pack.intake } : {}),
+      ...(pack.cohabitation_warning ? { cohabitationWarning: pack.cohabitation_warning } : {}),
     };
     facts.summary = renderSummary(pack, facts);
     facts.desc = renderSummary(pack, facts, 'description');
@@ -381,6 +569,7 @@ function buildDerived(registry, { sourceRoot = path.join(REPO_ROOT, 'src', 'bmad
     languages: Object.keys(LANGUAGES),
     packs,
     pythonPacks,
+    dataHandling: buildDataHandling(registry),
     diagnostics: {
       schemaVersion: 1,
       processExecution: registry.targets.optional_process_backend || null,
@@ -562,6 +751,88 @@ function checkSourcePaths(packs, packageRoot = REPO_ROOT) {
   return missing;
 }
 
+function resolvePackageManifest(name, packageRoot) {
+  return require.resolve(name + '/package.json', { paths: [packageRoot] });
+}
+
+/**
+ * Every `external_module` is an exact pinned dependency, resolvable from the
+ * repository root at the declared version, and ships each listed skill.
+ */
+function checkExternalModules(
+  registry,
+  { packageRoot = REPO_ROOT, packageJson, resolve = resolvePackageManifest } = {}
+) {
+  const problems = [];
+  const dependencies = (packageJson && packageJson.dependencies) || {};
+  const declared = new Set((registry.data_handling || {}).runtime_dependencies || []);
+  for (const [id, pack] of Object.entries(registry.packs)) {
+    const module = pack.external_module;
+    if (!module) continue;
+    const where = `PACKS.${id}: external_module ${module.package}`;
+    if (dependencies[module.package] !== module.version) {
+      problems.push(
+        `${where}: package.json must pin dependencies["${module.package}"] to exactly "${module.version}" (found ${JSON.stringify(dependencies[module.package])})`
+      );
+    }
+    if (!declared.has(module.package)) {
+      problems.push(`${where}: missing from data_handling.runtime_dependencies`);
+    }
+    let manifestPath;
+    try {
+      manifestPath = resolve(module.package, packageRoot);
+    } catch (error) {
+      problems.push(`${where}: cannot be resolved from the repository root (${error.message})`);
+      continue;
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (error) {
+      problems.push(`${where}: unreadable package.json (${error.message})`);
+      continue;
+    }
+    if (!manifest || manifest.name !== module.package || manifest.version !== module.version) {
+      problems.push(
+        `${where}: installed ${manifest && manifest.name}@${manifest && manifest.version}, declared ${module.version}`
+      );
+    }
+    for (const skill of module.skills) {
+      const file = path.join(path.dirname(manifestPath), 'skills', skill, 'SKILL.md');
+      if (!fs.existsSync(file)) problems.push(`${where}: skills/${skill}/SKILL.md is missing`);
+    }
+  }
+  return problems;
+}
+
+/** Every declared intake file exists in its pack directory and passes the contract. */
+function checkIntakes(registry, { packageRoot = REPO_ROOT } = {}) {
+  const problems = [];
+  for (const [id, pack] of Object.entries(registry.packs)) {
+    if (!pack.intake) continue;
+    const relative = `src/bmad-plus/${pack.pack_src_dir || 'packs'}/${pack.pack_dir}/${pack.intake}`;
+    const file = path.join(packageRoot, ...relative.split('/'));
+    const where = `PACKS.${id}: intake ${relative}`;
+    if (!fs.existsSync(file)) {
+      problems.push(`${where}: file does not exist`);
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = yaml.load(fs.readFileSync(file, 'utf8'), { schema: yaml.JSON_SCHEMA });
+    } catch (error) {
+      problems.push(`${where}: ${error.message}`);
+      continue;
+    }
+    const result = validateIntake(parsed);
+    for (const problem of result.problems) problems.push(`${where}: ${problem}`);
+    if (result.ok && parsed.pack !== id) {
+      problems.push(`${where}: declares pack "${parsed.pack}" instead of "${id}"`);
+    }
+  }
+  return problems;
+}
+
 /**
  * `--check` mode: prove registry.yaml reproduces the live packs.js exactly,
  * and that product.version matches package.json.
@@ -581,6 +852,8 @@ function check({
 
   const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
   mismatches.push(...checkSourcePaths(generated.PACKS));
+  mismatches.push(...checkExternalModules(registry, { packageJson: pkg }));
+  mismatches.push(...checkIntakes(registry));
   const { checkPythonDelivery } = require('./pack-delivery');
   mismatches.push(...checkPythonDelivery(registry, { packageRoot: REPO_ROOT, packageJson: pkg }));
   try {
@@ -666,6 +939,7 @@ module.exports = {
   DEFAULT_PACKS_MODULE_PATH,
   DEFAULT_MODULE_PATH,
   MODULE_TEMPLATE_PATH,
+  PACKAGE_NAME_RE,
   loadRegistry,
   validateRegistry,
   buildPacks,
@@ -678,6 +952,8 @@ module.exports = {
   generatePacksModuleSource,
   check,
   checkSourcePaths,
+  checkExternalModules,
+  checkIntakes,
   main,
 };