bmad-method 6.0.3 → 6.0.5-next.0

package/tools/cli/installers/lib/core/manifest-generator.js

@@ -5,6 +5,12 @@ const crypto = require('node:crypto');
 const csv = require('csv-parse/sync');
 const { getSourcePath, getModulePath } = require('../../../lib/project-root');
 const prompts = require('../../../lib/prompts');
+const {
+  loadSkillManifest: loadSkillManifestShared,
+  getCanonicalId: getCanonicalIdShared,
+  getArtifactType: getArtifactTypeShared,
+  getInstallToBmad: getInstallToBmadShared,
+} = require('../ide/shared/skill-manifest');
 
 // Load package.json for version info
 const packageJson = require('../../../../../package.json');
@@ -15,6 +21,7 @@ const packageJson = require('../../../../../package.json');
 class ManifestGenerator {
   constructor() {
     this.workflows = [];
+    this.skills = [];
     this.agents = [];
     this.tasks = [];
     this.tools = [];
@@ -23,17 +30,35 @@ class ManifestGenerator {
     this.selectedIdes = [];
   }
 
+  /** Delegate to shared skill-manifest module */
+  async loadSkillManifest(dirPath) {
+    return loadSkillManifestShared(dirPath);
+  }
+
+  /** Delegate to shared skill-manifest module */
+  getCanonicalId(manifest, filename) {
+    return getCanonicalIdShared(manifest, filename);
+  }
+
+  /** Delegate to shared skill-manifest module */
+  getArtifactType(manifest, filename) {
+    return getArtifactTypeShared(manifest, filename);
+  }
+
+  /** Delegate to shared skill-manifest module */
+  getInstallToBmad(manifest, filename) {
+    return getInstallToBmadShared(manifest, filename);
+  }
+
   /**
-   * Clean text for CSV output by normalizing whitespace and escaping quotes
+   * Clean text for CSV output by normalizing whitespace.
+   * Note: Quote escaping is handled by escapeCsv() at write time.
    * @param {string} text - Text to clean
-   * @returns {string} Cleaned text safe for CSV
+   * @returns {string} Cleaned text
    */
   cleanForCSV(text) {
     if (!text) return '';
-    return text
-      .trim()
-      .replaceAll(/\s+/g, ' ') // Normalize all whitespace (including newlines) to single space
-      .replaceAll('"', '""'); // Escape quotes for CSV
+    return text.trim().replaceAll(/\s+/g, ' '); // Normalize all whitespace (including newlines) to single space
   }
 
   /**
@@ -80,6 +105,12 @@ class ManifestGenerator {
     // Filter out any undefined/null values from IDE list
     this.selectedIdes = resolvedIdes.filter((ide) => ide && typeof ide === 'string');
 
+    // Reset files list (defensive: prevent stale data if instance is reused)
+    this.files = [];
+
+    // Collect skills first (populates skillClaimedDirs before legacy collectors run)
+    await this.collectSkills();
+
     // Collect workflow data
     await this.collectWorkflows(selectedModules);
 
@@ -96,6 +127,7 @@ class ManifestGenerator {
     const manifestFiles = [
       await this.writeMainManifest(cfgDir),
       await this.writeWorkflowManifest(cfgDir),
+      await this.writeSkillManifest(cfgDir),
       await this.writeAgentManifest(cfgDir),
       await this.writeTaskManifest(cfgDir),
       await this.writeToolManifest(cfgDir),
@@ -103,6 +135,7 @@ class ManifestGenerator {
     ];
 
     return {
+      skills: this.skills.length,
       workflows: this.workflows.length,
       agents: this.agents.length,
       tasks: this.tasks.length,
@@ -112,6 +145,169 @@ class ManifestGenerator {
     };
   }
 
+  /**
+   * Recursively walk a module directory tree, collecting skill directories.
+   * A skill directory is one that contains both a bmad-skill-manifest.yaml with
+   * type: skill AND a SKILL.md file with name/description frontmatter.
+   * Populates this.skills[] and this.skillClaimedDirs (Set of absolute paths).
+   */
+  async collectSkills() {
+    this.skills = [];
+    this.skillClaimedDirs = new Set();
+    const debug = process.env.BMAD_DEBUG_MANIFEST === 'true';
+
+    for (const moduleName of this.updatedModules) {
+      const modulePath = path.join(this.bmadDir, moduleName);
+      if (!(await fs.pathExists(modulePath))) continue;
+
+      // Recursive walk skipping . and _ prefixed dirs
+      const walk = async (dir) => {
+        let entries;
+        try {
+          entries = await fs.readdir(dir, { withFileTypes: true });
+        } catch {
+          return;
+        }
+
+        // Check this directory for skill manifest
+        const manifest = await this.loadSkillManifest(dir);
+
+        // Determine if this directory is a skill (type: skill in manifest)
+        const skillFile = 'SKILL.md';
+        const artifactType = this.getArtifactType(manifest, skillFile);
+
+        if (artifactType === 'skill') {
+          const skillMdPath = path.join(dir, 'SKILL.md');
+          const dirName = path.basename(dir);
+
+          // Validate and parse SKILL.md
+          const skillMeta = await this.parseSkillMd(skillMdPath, dir, dirName, debug);
+
+          if (skillMeta) {
+            // Build path relative from module root (points to SKILL.md — the permanent entrypoint)
+            const relativePath = path.relative(modulePath, dir).split(path.sep).join('/');
+            const installPath = relativePath
+              ? `${this.bmadFolderName}/${moduleName}/${relativePath}/${skillFile}`
+              : `${this.bmadFolderName}/${moduleName}/${skillFile}`;
+
+            // Skills derive canonicalId from directory name — never from manifest
+            if (manifest && manifest.__single && manifest.__single.canonicalId) {
+              console.warn(
+                `Warning: Skill manifest at ${dir}/bmad-skill-manifest.yaml contains canonicalId — this field is ignored for skills (directory name is the canonical ID)`,
+              );
+            }
+            const canonicalId = dirName;
+
+            this.skills.push({
+              name: skillMeta.name,
+              description: this.cleanForCSV(skillMeta.description),
+              module: moduleName,
+              path: installPath,
+              canonicalId,
+              install_to_bmad: this.getInstallToBmad(manifest, skillFile),
+            });
+
+            // Add to files list
+            this.files.push({
+              type: 'skill',
+              name: skillMeta.name,
+              module: moduleName,
+              path: installPath,
+            });
+
+            this.skillClaimedDirs.add(dir);
+
+            if (debug) {
+              console.log(`[DEBUG] collectSkills: claimed skill "${skillMeta.name}" as ${canonicalId} at ${dir}`);
+            }
+          }
+        }
+
+        // Warn if manifest says type:skill but directory was not claimed
+        if (manifest && !this.skillClaimedDirs.has(dir)) {
+          let hasSkillType = false;
+          if (manifest.__single) {
+            hasSkillType = manifest.__single.type === 'skill';
+          } else {
+            for (const key of Object.keys(manifest)) {
+              if (manifest[key]?.type === 'skill') {
+                hasSkillType = true;
+                break;
+              }
+            }
+          }
+          if (hasSkillType && debug) {
+            console.log(`[DEBUG] collectSkills: dir has type:skill manifest but failed validation: ${dir}`);
+          }
+        }
+
+        // Recurse into subdirectories
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+          await walk(path.join(dir, entry.name));
+        }
+      };
+
+      await walk(modulePath);
+    }
+
+    if (debug) {
+      console.log(`[DEBUG] collectSkills: total skills found: ${this.skills.length}, claimed dirs: ${this.skillClaimedDirs.size}`);
+    }
+  }
+
+  /**
+   * Parse and validate SKILL.md for a skill directory.
+   * Returns parsed frontmatter object with name/description, or null if invalid.
+   * @param {string} skillMdPath - Absolute path to SKILL.md
+   * @param {string} dir - Skill directory path (for error messages)
+   * @param {string} dirName - Expected name (must match frontmatter name)
+   * @param {boolean} debug - Whether to emit debug-level messages
+   * @returns {Promise<Object|null>} Parsed frontmatter or null
+   */
+  async parseSkillMd(skillMdPath, dir, dirName, debug = false) {
+    if (!(await fs.pathExists(skillMdPath))) {
+      if (debug) console.log(`[DEBUG] parseSkillMd: "${dir}" is missing SKILL.md — skipping`);
+      return null;
+    }
+
+    try {
+      const rawContent = await fs.readFile(skillMdPath, 'utf8');
+      const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+
+      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      if (frontmatterMatch) {
+        const skillMeta = yaml.parse(frontmatterMatch[1]);
+
+        if (
+          !skillMeta ||
+          typeof skillMeta !== 'object' ||
+          typeof skillMeta.name !== 'string' ||
+          typeof skillMeta.description !== 'string' ||
+          !skillMeta.name ||
+          !skillMeta.description
+        ) {
+          if (debug) console.log(`[DEBUG] parseSkillMd: SKILL.md in "${dir}" is missing name or description (or wrong type) — skipping`);
+          return null;
+        }
+
+        if (skillMeta.name !== dirName) {
+          console.error(`Error: SKILL.md name "${skillMeta.name}" does not match directory name "${dirName}" — skipping`);
+          return null;
+        }
+
+        return skillMeta;
+      }
+
+      if (debug) console.log(`[DEBUG] parseSkillMd: SKILL.md in "${dir}" has no frontmatter — skipping`);
+      return null;
+    } catch (error) {
+      if (debug) console.log(`[DEBUG] parseSkillMd: failed to parse SKILL.md in "${dir}": ${error.message} — skipping`);
+      return null;
+    }
+  }
+
   /**
    * Collect all workflows from core and selected modules
    * Scans the INSTALLED bmad directory, not the source
@@ -126,16 +322,20 @@ class ManifestGenerator {
       if (await fs.pathExists(modulePath)) {
         const moduleWorkflows = await this.getWorkflowsFromPath(modulePath, moduleName);
         this.workflows.push(...moduleWorkflows);
+
+        // Also scan tasks/ for type:skill entries (skills can live anywhere)
+        const tasksSkills = await this.getWorkflowsFromPath(modulePath, moduleName, 'tasks');
+        this.workflows.push(...tasksSkills);
       }
     }
   }
 
   /**
-   * Recursively find and parse workflow.yaml and workflow.md files
+   * Recursively find and parse workflow.md files
    */
-  async getWorkflowsFromPath(basePath, moduleName) {
+  async getWorkflowsFromPath(basePath, moduleName, subDir = 'workflows') {
     const workflows = [];
-    const workflowsPath = path.join(basePath, 'workflows');
+    const workflowsPath = path.join(basePath, subDir);
     const debug = process.env.BMAD_DEBUG_MANIFEST === 'true';
 
     if (debug) {
@@ -149,22 +349,25 @@ class ManifestGenerator {
       return workflows;
     }
 
-    // Recursively find workflow.yaml files
+    // Recursively find workflow.md files
     const findWorkflows = async (dir, relativePath = '') => {
+      // Skip directories already claimed as skills
+      if (this.skillClaimedDirs && this.skillClaimedDirs.has(dir)) return;
+
       const entries = await fs.readdir(dir, { withFileTypes: true });
+      // Load skill manifest for this directory (if present)
+      const skillManifest = await this.loadSkillManifest(dir);
 
       for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
 
         if (entry.isDirectory()) {
+          // Skip directories claimed by collectSkills
+          if (this.skillClaimedDirs && this.skillClaimedDirs.has(fullPath)) continue;
           // Recurse into subdirectories
           const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
           await findWorkflows(fullPath, newRelativePath);
-        } else if (
-          entry.name === 'workflow.yaml' ||
-          entry.name === 'workflow.md' ||
-          (entry.name.startsWith('workflow-') && entry.name.endsWith('.md'))
-        ) {
+        } else if (entry.name === 'workflow.md' || (entry.name.startsWith('workflow-') && entry.name.endsWith('.md'))) {
           // Parse workflow file (both YAML and MD formats)
           if (debug) {
             console.log(`[DEBUG] Found workflow file: ${fullPath}`);
@@ -174,21 +377,15 @@ class ManifestGenerator {
             const rawContent = await fs.readFile(fullPath, 'utf8');
             const content = rawContent.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
 
-            let workflow;
-            if (entry.name === 'workflow.yaml') {
-              // Parse YAML workflow
-              workflow = yaml.parse(content);
-            } else {
-              // Parse MD workflow with YAML frontmatter
-              const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-              if (!frontmatterMatch) {
-                if (debug) {
-                  console.log(`[DEBUG] Skipped (no frontmatter): ${fullPath}`);
-                }
-                continue; // Skip MD files without frontmatter
+            // Parse MD workflow with YAML frontmatter
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+            if (!frontmatterMatch) {
+              if (debug) {
+                console.log(`[DEBUG] Skipped (no frontmatter): ${fullPath}`);
               }
-              workflow = yaml.parse(frontmatterMatch[1]);
+              continue; // Skip MD files without frontmatter
             }
+            const workflow = yaml.parse(frontmatterMatch[1]);
 
             if (debug) {
               console.log(`[DEBUG] Parsed: name="${workflow.name}", description=${workflow.description ? 'OK' : 'MISSING'}`);
@@ -214,8 +411,8 @@ class ManifestGenerator {
               // Build relative path for installation
               const installPath =
                 moduleName === 'core'
-                  ? `${this.bmadFolderName}/core/workflows/${relativePath}/${entry.name}`
-                  : `${this.bmadFolderName}/${moduleName}/workflows/${relativePath}/${entry.name}`;
+                  ? `${this.bmadFolderName}/core/${subDir}/${relativePath}/${entry.name}`
+                  : `${this.bmadFolderName}/${moduleName}/${subDir}/${relativePath}/${entry.name}`;
 
               // Workflows with standalone: false are filtered out above
               workflows.push({
@@ -223,6 +420,7 @@ class ManifestGenerator {
                 description: this.cleanForCSV(workflow.description),
                 module: moduleName,
                 path: installPath,
+                canonicalId: this.getCanonicalId(skillManifest, entry.name),
               });
 
               // Add to files list
@@ -294,13 +492,19 @@ class ManifestGenerator {
    * Only includes compiled .md files (not .agent.yaml source files)
    */
   async getAgentsFromDir(dirPath, moduleName, relativePath = '') {
+    // Skip directories claimed by collectSkills
+    if (this.skillClaimedDirs && this.skillClaimedDirs.has(dirPath)) return [];
     const agents = [];
     const entries = await fs.readdir(dirPath, { withFileTypes: true });
+    // Load skill manifest for this directory (if present)
+    const skillManifest = await this.loadSkillManifest(dirPath);
 
     for (const entry of entries) {
       const fullPath = path.join(dirPath, entry.name);
 
       if (entry.isDirectory()) {
+        // Skip directories claimed by collectSkills
+        if (this.skillClaimedDirs && this.skillClaimedDirs.has(fullPath)) continue;
         // Recurse into subdirectories
         const newRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
         const subDirAgents = await this.getAgentsFromDir(fullPath, moduleName, newRelativePath);
@@ -351,6 +555,7 @@ class ManifestGenerator {
           principles: principlesMatch ? this.cleanForCSV(principlesMatch[1]) : '',
           module: moduleName,
           path: installPath,
+          canonicalId: this.getCanonicalId(skillManifest, entry.name),
         });
 
         // Add to files list
@@ -388,8 +593,12 @@ class ManifestGenerator {
    * Get tasks from a directory
    */
   async getTasksFromDir(dirPath, moduleName) {
+    // Skip directories claimed by collectSkills
+    if (this.skillClaimedDirs && this.skillClaimedDirs.has(dirPath)) return [];
     const tasks = [];
     const files = await fs.readdir(dirPath);
+    // Load skill manifest for this directory (if present)
+    const skillManifest = await this.loadSkillManifest(dirPath);
 
     for (const file of files) {
       // Check for both .xml and .md files
@@ -449,6 +658,7 @@ class ManifestGenerator {
           module: moduleName,
           path: installPath,
           standalone: standalone,
+          canonicalId: this.getCanonicalId(skillManifest, file),
         });
 
         // Add to files list
@@ -486,8 +696,12 @@ class ManifestGenerator {
    * Get tools from a directory
    */
   async getToolsFromDir(dirPath, moduleName) {
+    // Skip directories claimed by collectSkills
+    if (this.skillClaimedDirs && this.skillClaimedDirs.has(dirPath)) return [];
     const tools = [];
     const files = await fs.readdir(dirPath);
+    // Load skill manifest for this directory (if present)
+    const skillManifest = await this.loadSkillManifest(dirPath);
 
     for (const file of files) {
       // Check for both .xml and .md files
@@ -547,6 +761,7 @@ class ManifestGenerator {
           module: moduleName,
           path: installPath,
           standalone: standalone,
+          canonicalId: this.getCanonicalId(skillManifest, file),
         });
 
         // Add to files list
@@ -737,8 +952,8 @@ class ManifestGenerator {
     const csvPath = path.join(cfgDir, 'workflow-manifest.csv');
     const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`;
 
-    // Create CSV header - standalone column removed, everything is canonicalized to 4 columns
-    let csv = 'name,description,module,path\n';
+    // Create CSV header - standalone column removed, canonicalId added as optional column
+    let csv = 'name,description,module,path,canonicalId\n';
 
     // Build workflows map from discovered workflows only
     // Old entries are NOT preserved - the manifest reflects what actually exists on disk
@@ -752,12 +967,19 @@ class ManifestGenerator {
         description: workflow.description,
         module: workflow.module,
         path: workflow.path,
+        canonicalId: workflow.canonicalId || '',
       });
     }
 
     // Write all workflows
     for (const [, value] of allWorkflows) {
-      const row = [escapeCsv(value.name), escapeCsv(value.description), escapeCsv(value.module), escapeCsv(value.path)].join(',');
+      const row = [
+        escapeCsv(value.name),
+        escapeCsv(value.description),
+        escapeCsv(value.module),
+        escapeCsv(value.path),
+        escapeCsv(value.canonicalId),
+      ].join(',');
       csv += row + '\n';
     }
 
@@ -765,6 +987,32 @@ class ManifestGenerator {
     return csvPath;
   }
 
+  /**
+   * Write skill manifest CSV
+   * @returns {string} Path to the manifest file
+   */
+  async writeSkillManifest(cfgDir) {
+    const csvPath = path.join(cfgDir, 'skill-manifest.csv');
+    const escapeCsv = (value) => `"${String(value ?? '').replaceAll('"', '""')}"`;
+
+    let csvContent = 'canonicalId,name,description,module,path,install_to_bmad\n';
+
+    for (const skill of this.skills) {
+      const row = [
+        escapeCsv(skill.canonicalId),
+        escapeCsv(skill.name),
+        escapeCsv(skill.description),
+        escapeCsv(skill.module),
+        escapeCsv(skill.path),
+        escapeCsv(skill.install_to_bmad),
+      ].join(',');
+      csvContent += row + '\n';
+    }
+
+    await fs.writeFile(csvPath, csvContent);
+    return csvPath;
+  }
+
   /**
    * Write agent manifest CSV
    * @returns {string} Path to the manifest file
@@ -786,8 +1034,8 @@ class ManifestGenerator {
       }
     }
 
-    // Create CSV header with persona fields
-    let csvContent = 'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path\n';
+    // Create CSV header with persona fields and canonicalId
+    let csvContent = 'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path,canonicalId\n';
 
     // Combine existing and new agents, preferring new data for duplicates
     const allAgents = new Map();
@@ -812,6 +1060,7 @@ class ManifestGenerator {
         principles: agent.principles,
         module: agent.module,
         path: agent.path,
+        canonicalId: agent.canonicalId || '',
       });
     }
 
@@ -829,6 +1078,7 @@ class ManifestGenerator {
         escapeCsv(record.principles),
         escapeCsv(record.module),
         escapeCsv(record.path),
+        escapeCsv(record.canonicalId),
       ].join(',');
       csvContent += row + '\n';
     }
@@ -858,8 +1108,8 @@ class ManifestGenerator {
       }
     }
 
-    // Create CSV header with standalone column
-    let csvContent = 'name,displayName,description,module,path,standalone\n';
+    // Create CSV header with standalone and canonicalId columns
+    let csvContent = 'name,displayName,description,module,path,standalone,canonicalId\n';
 
     // Combine existing and new tasks
     const allTasks = new Map();
@@ -879,6 +1129,7 @@ class ManifestGenerator {
         module: task.module,
         path: task.path,
         standalone: task.standalone,
+        canonicalId: task.canonicalId || '',
       });
     }
 
@@ -891,6 +1142,7 @@ class ManifestGenerator {
         escapeCsv(record.module),
         escapeCsv(record.path),
         escapeCsv(record.standalone),
+        escapeCsv(record.canonicalId),
       ].join(',');
       csvContent += row + '\n';
     }
@@ -920,8 +1172,8 @@ class ManifestGenerator {
       }
     }
 
-    // Create CSV header with standalone column
-    let csvContent = 'name,displayName,description,module,path,standalone\n';
+    // Create CSV header with standalone and canonicalId columns
+    let csvContent = 'name,displayName,description,module,path,standalone,canonicalId\n';
 
     // Combine existing and new tools
     const allTools = new Map();
@@ -941,6 +1193,7 @@ class ManifestGenerator {
         module: tool.module,
         path: tool.path,
         standalone: tool.standalone,
+        canonicalId: tool.canonicalId || '',
       });
     }
 
@@ -953,6 +1206,7 @@ class ManifestGenerator {
         escapeCsv(record.module),
         escapeCsv(record.path),
         escapeCsv(record.standalone),
+        escapeCsv(record.canonicalId),
       ].join(',');
       csvContent += row + '\n';
     }
@@ -1067,8 +1321,14 @@ class ManifestGenerator {
         const hasTasks = await fs.pathExists(path.join(modulePath, 'tasks'));
         const hasTools = await fs.pathExists(path.join(modulePath, 'tools'));
 
-        // If it has any of these directories, it's likely a module
-        if (hasAgents || hasWorkflows || hasTasks || hasTools) {
+        // Check for skill-only modules: recursive scan for bmad-skill-manifest.yaml with type: skill
+        let hasSkills = false;
+        if (!hasAgents && !hasWorkflows && !hasTasks && !hasTools) {
+          hasSkills = await this._hasSkillManifestRecursive(modulePath);
+        }
+
+        // If it has any of these directories or skill manifests, it's likely a module
+        if (hasAgents || hasWorkflows || hasTasks || hasTools || hasSkills) {
           modules.push(entry.name);
         }
       }
@@ -1078,6 +1338,37 @@ class ManifestGenerator {
 
     return modules;
   }
+
+  /**
+   * Recursively check if a directory tree contains a bmad-skill-manifest.yaml with type: skill.
+   * Skips directories starting with . or _.
+   * @param {string} dir - Directory to search
+   * @returns {boolean} True if a skill manifest is found
+   */
+  async _hasSkillManifestRecursive(dir) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+
+    // Check for manifest in this directory
+    const manifest = await this.loadSkillManifest(dir);
+    if (manifest) {
+      const type = this.getArtifactType(manifest, 'workflow.md');
+      if (type === 'skill') return true;
+    }
+
+    // Recurse into subdirectories
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+      if (await this._hasSkillManifestRecursive(path.join(dir, entry.name))) return true;
+    }
+
+    return false;
+  }
 }
 
 module.exports = { ManifestGenerator };