convoke-agents 2.3.1 → 3.0.0

package/scripts/update/lib/validator.js

@@ -44,6 +44,9 @@ async function validateInstallation(preMigrationData = {}, projectRoot) {
   // 7. Workflow step structure validation (P17 count + P20 filenames)
   checks.push(await validateWorkflowStepStructure(projectRoot));
 
+  // 8. Enhance module validation (optional — passes if not installed)
+  checks.push(await validateEnhanceModule(projectRoot));
+
   const allPassed = checks.every(c => c.passed);
 
   return {
@@ -348,6 +351,278 @@ async function validateWorkflowStepStructure(projectRoot) {
   return check;
 }
 
+/**
+ * Validate Enhance module installation (optional — passes if not installed)
+ * Performs 5-point verification: directory, entry point, menu patch, config, filesystem consistency
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateEnhanceModule(projectRoot) {
+  const check = {
+    name: 'Enhance module',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const enhanceDir = path.join(projectRoot, '_bmad/bme/_enhance');
+
+    // Check 1: Directory exists — if not, Enhance is simply not installed (optional)
+    if (!fs.existsSync(enhanceDir)) {
+      check.passed = true;
+      check.info = 'Enhance module not installed (optional)';
+      return check;
+    }
+
+    const failures = [];
+
+    // Check 4 (first — needed by checks 2, 3, 5): Config valid
+    const configPath = path.join(enhanceDir, 'config.yaml');
+    let config = null;
+
+    if (!fs.existsSync(configPath)) {
+      failures.push('config.yaml not found');
+    } else {
+      try {
+        config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+      } catch (err) {
+        failures.push(`config.yaml parse error: ${err.message}`);
+      }
+
+      if (config) {
+        const missing = [];
+        if (!config.name) missing.push('name');
+        if (!config.version) missing.push('version');
+        if (!config.description) missing.push('description');
+        if (!Array.isArray(config.workflows) || config.workflows.length === 0) {
+          missing.push('workflows (must be non-empty array)');
+        } else {
+          config.workflows.forEach((wf, i) => {
+            const wfMissing = [];
+            if (!wf.name) wfMissing.push('name');
+            if (!wf.entry) wfMissing.push('entry');
+            if (!wf.target_agent) wfMissing.push('target_agent');
+            if (!wf.menu_patch_name) wfMissing.push('menu_patch_name');
+            if (wfMissing.length > 0) {
+              missing.push(`workflows[${i}] missing: ${wfMissing.join(', ')}`);
+            }
+          });
+        }
+        if (missing.length > 0) {
+          failures.push(`config missing fields: ${missing.join('; ')}`);
+        }
+      }
+    }
+
+    // Checks 2, 3, 5 require a valid config with workflows
+    if (config && Array.isArray(config.workflows)) {
+      for (const wf of config.workflows) {
+        // Check 2: Workflow entry point resolves
+        if (wf.entry) {
+          const entryPath = path.join(enhanceDir, wf.entry);
+          if (!fs.existsSync(entryPath)) {
+            failures.push(`workflow entry point not found: ${wf.entry}`);
+          }
+        }
+
+        // Check 3: Menu patch present in target agent
+        if (wf.target_agent) {
+          const agentPath = path.join(projectRoot, '_bmad', wf.target_agent);
+          if (fs.existsSync(agentPath)) {
+            const agentContent = fs.readFileSync(agentPath, 'utf8');
+            const patchName = wf.menu_patch_name || wf.name;
+            if (!agentContent.includes(patchName)) {
+              failures.push(`menu patch "${patchName}" not found in ${wf.target_agent}`);
+            }
+          }
+          // If agent file doesn't exist, that's already caught by agent validation — not an Enhance-specific failure
+        }
+
+        // Check 5: Config-to-filesystem consistency — workflow directory exists
+        if (wf.name) {
+          const wfDir = path.join(enhanceDir, 'workflows', wf.name);
+          if (!fs.existsSync(wfDir)) {
+            failures.push(`workflow directory not found for registered workflow: ${wf.name}`);
+          }
+        }
+
+        // Check 6: Skill wrapper exists for workflow
+        if (wf.name) {
+          const skillWrapperPath = path.join(projectRoot, '.claude', 'skills', `bmad-enhance-${wf.name}`, 'SKILL.md');
+          if (!fs.existsSync(skillWrapperPath)) {
+            failures.push(`skill wrapper not found: .claude/skills/bmad-enhance-${wf.name}/SKILL.md`);
+          }
+        }
+      }
+    }
+
+    if (failures.length > 0) {
+      check.error = `Enhance: ${failures.join('; ')}`;
+    } else {
+      check.passed = true;
+    }
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
+/**
+ * Validate a SKILL.md file has required frontmatter fields
+ * @param {string} skillMdPath - Absolute path to SKILL.md file
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateSkillMd(skillMdPath) {
+  const errors = [];
+
+  if (!fs.existsSync(skillMdPath)) {
+    errors.push(`SKILL.md not found: ${skillMdPath}`);
+    return { valid: false, errors };
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf8');
+
+  // Extract YAML frontmatter between --- delimiters
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    errors.push('SKILL.md missing YAML frontmatter (--- delimiters)');
+    return { valid: false, errors };
+  }
+
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(fmMatch[1]);
+  } catch (err) {
+    errors.push(`SKILL.md frontmatter parse error: ${err.message}`);
+    return { valid: false, errors };
+  }
+
+  if (!frontmatter || typeof frontmatter !== 'object') {
+    errors.push('SKILL.md frontmatter is empty or not an object');
+    return { valid: false, errors };
+  }
+
+  if (!frontmatter.name || typeof frontmatter.name !== 'string') {
+    errors.push('SKILL.md missing required field: name');
+  }
+
+  if (!frontmatter.description || typeof frontmatter.description !== 'string') {
+    errors.push('SKILL.md missing required field: description');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate step files in a skill directory follow sequential numbering
+ * @param {string} skillDir - Absolute path to skill directory
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateStepFiles(skillDir) {
+  const errors = [];
+
+  if (!fs.existsSync(skillDir)) {
+    errors.push(`Skill directory not found: ${skillDir}`);
+    return { valid: false, errors };
+  }
+
+  // Collect step files from skill dir and steps/ subdirectory
+  const stepFiles = [];
+  const entries = fs.readdirSync(skillDir);
+
+  for (const entry of entries) {
+    if (/^step-\d+-/.test(entry) && entry.endsWith('.md')) {
+      stepFiles.push(entry);
+    }
+  }
+
+  const stepsSubdir = path.join(skillDir, 'steps');
+  if (fs.existsSync(stepsSubdir)) {
+    const subEntries = fs.readdirSync(stepsSubdir);
+    for (const entry of subEntries) {
+      if (/^step-\d+-/.test(entry) && entry.endsWith('.md')) {
+        stepFiles.push(entry);
+      }
+    }
+  }
+
+  if (stepFiles.length === 0) {
+    // No step files is valid — some skills are single-file (agent-activation type)
+    return { valid: true, errors };
+  }
+
+  // Extract step numbers and check for sequential numbering
+  const stepNumbers = stepFiles
+    .map(f => {
+      const match = f.match(/^step-(\d+)-/);
+      return match ? parseInt(match[1], 10) : null;
+    })
+    .filter(n => n !== null)
+    .sort((a, b) => a - b);
+
+  // Remove duplicates (same step number in root and steps/)
+  const uniqueSteps = [...new Set(stepNumbers)];
+
+  // Check for gaps in sequence
+  for (let i = 0; i < uniqueSteps.length - 1; i++) {
+    if (uniqueSteps[i + 1] - uniqueSteps[i] > 1) {
+      errors.push(
+        `Step numbering gap: step-${String(uniqueSteps[i]).padStart(2, '0')} to step-${String(uniqueSteps[i + 1]).padStart(2, '0')} (missing step-${String(uniqueSteps[i] + 1).padStart(2, '0')})`
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate skill cohesion — workflow.md exists if step files exist
+ * @param {string} skillDir - Absolute path to skill directory
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateSkillCohesion(skillDir) {
+  const errors = [];
+
+  if (!fs.existsSync(skillDir)) {
+    errors.push(`Skill directory not found: ${skillDir}`);
+    return { valid: false, errors };
+  }
+
+  const entries = fs.readdirSync(skillDir);
+  const hasStepFiles = entries.some(e => /^step-\d+-/.test(e) && e.endsWith('.md'));
+  const hasStepsSubdir = fs.existsSync(path.join(skillDir, 'steps'));
+  const hasWorkflow = entries.includes('workflow.md');
+
+  // If step files or steps/ subdirectory exist, workflow.md should too
+  if ((hasStepFiles || hasStepsSubdir) && !hasWorkflow) {
+    errors.push('Skill has step files but no workflow.md');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Validate a complete skill package (SKILL.md + step files + cohesion)
+ * @param {string} skillDir - Absolute path to skill directory
+ * @returns {Promise<object>} Validation result { valid, errors }
+ */
+async function validateSkill(skillDir) {
+  const allErrors = [];
+
+  const skillMdPath = path.join(skillDir, 'SKILL.md');
+  const skillMdResult = await validateSkillMd(skillMdPath);
+  allErrors.push(...skillMdResult.errors);
+
+  const stepResult = await validateStepFiles(skillDir);
+  allErrors.push(...stepResult.errors);
+
+  const cohesionResult = await validateSkillCohesion(skillDir);
+  allErrors.push(...cohesionResult.errors);
+
+  return { valid: allErrors.length === 0, errors: allErrors };
+}
+
 module.exports = {
   validateInstallation,
   validateConfigStructure,
@@ -356,5 +631,10 @@ module.exports = {
   validateManifest,
   validateUserDataIntegrity,
   validateDeprecatedWorkflows,
-  validateWorkflowStepStructure
+  validateWorkflowStepStructure,
+  validateEnhanceModule,
+  validateSkillMd,
+  validateStepFiles,
+  validateSkillCohesion,
+  validateSkill
 };