convoke-agents 2.0.0

package/scripts/update/lib/validator.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const configMerger = require('./config-merger');
+const { countUserDataFiles } = require('./utils');
+const { AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, WAVE3_WORKFLOW_NAMES } = require('./agent-registry');
+
+/**
+ * Validator for Convoke
+ * Verifies installation integrity post-migration
+ */
+
+/**
+ * Validate entire installation
+ * @param {object} preMigrationData - Data from before migration for comparison
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation result
+ */
+async function validateInstallation(preMigrationData = {}, projectRoot) {
+  const checks = [];
+
+  // 1. Config structure validation
+  checks.push(await validateConfigStructure(projectRoot));
+
+  // 2. Agent files validation
+  checks.push(await validateAgentFiles(projectRoot));
+
+  // 3. Workflow files validation
+  checks.push(await validateWorkflows(projectRoot));
+
+  // 4. Manifest consistency validation
+  checks.push(await validateManifest(projectRoot));
+
+  // 5. User data integrity validation
+  if (preMigrationData.user_data_count) {
+    checks.push(await validateUserDataIntegrity(preMigrationData.user_data_count, projectRoot));
+  }
+
+  // 6. Deprecated workflows validation (if applicable)
+  checks.push(await validateDeprecatedWorkflows(projectRoot));
+
+  // 7. Workflow step structure validation (P17 count + P20 filenames)
+  checks.push(await validateWorkflowStepStructure(projectRoot));
+
+  const allPassed = checks.every(c => c.passed);
+
+  return {
+    valid: allPassed,
+    checks
+  };
+}
+
+/**
+ * Validate config.yaml structure
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateConfigStructure(projectRoot) {
+  const check = {
+    name: 'Config structure',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const configPath = path.join(projectRoot, '_bmad/bme/_vortex/config.yaml');
+
+    if (!fs.existsSync(configPath)) {
+      check.error = 'config.yaml not found';
+      return check;
+    }
+
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = yaml.load(configContent);
+
+    // Validate using config-merger
+    const validation = configMerger.validateConfig(config);
+
+    if (!validation.valid) {
+      check.error = validation.errors.join(', ');
+      return check;
+    }
+
+    check.passed = true;
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
+/**
+ * Validate agent files exist
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateAgentFiles(projectRoot) {
+  const check = {
+    name: 'Agent files',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const agentsDir = path.join(projectRoot, '_bmad/bme/_vortex/agents');
+    const requiredAgents = AGENT_FILES;
+
+    if (!fs.existsSync(agentsDir)) {
+      check.error = 'agents/ directory not found';
+      return check;
+    }
+
+    const missingAgents = [];
+    for (const agent of requiredAgents) {
+      const agentPath = path.join(agentsDir, agent);
+      if (!fs.existsSync(agentPath)) {
+        missingAgents.push(agent);
+      }
+    }
+
+    if (missingAgents.length > 0) {
+      check.error = `Missing agent files: ${missingAgents.join(', ')}`;
+      return check;
+    }
+
+    check.passed = true;
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
+/**
+ * Validate workflow files exist
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateWorkflows(projectRoot) {
+  const check = {
+    name: 'Workflow files',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const workflowsDir = path.join(projectRoot, '_bmad/bme/_vortex/workflows');
+    const requiredWorkflows = WORKFLOW_NAMES;
+
+    if (!fs.existsSync(workflowsDir)) {
+      check.error = 'workflows/ directory not found';
+      return check;
+    }
+
+    const missingWorkflows = [];
+    for (const workflow of requiredWorkflows) {
+      const workflowFile = path.join(workflowsDir, workflow, 'workflow.md');
+      if (!fs.existsSync(workflowFile)) {
+        missingWorkflows.push(workflow);
+      }
+    }
+
+    if (missingWorkflows.length > 0) {
+      check.error = `Missing workflows: ${missingWorkflows.join(', ')}`;
+      return check;
+    }
+
+    check.passed = true;
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
+/**
+ * Validate agent manifest consistency
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateManifest(projectRoot) {
+  const check = {
+    name: 'Agent manifest',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const manifestPath = path.join(projectRoot, '_bmad/_config/agent-manifest.csv');
+
+    if (!fs.existsSync(manifestPath)) {
+      // Manifest is optional, so this is not a failure
+      check.passed = true;
+      check.warning = 'agent-manifest.csv not found (optional)';
+      return check;
+    }
+
+    const manifestContent = fs.readFileSync(manifestPath, 'utf8');
+
+    // Check for all Convoke agents
+    const missingFromManifest = AGENT_IDS.filter(id => !manifestContent.includes(id));
+
+    if (missingFromManifest.length > 0) {
+      check.error = `Agent manifest missing: ${missingFromManifest.join(', ')}`;
+      return check;
+    }
+
+    check.passed = true;
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
+/**
+ * Validate user data integrity
+ * @param {number} expectedCount - Expected file count
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateUserDataIntegrity(expectedCount, projectRoot) {
+  const check = {
+    name: 'User data preserved',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const outputDir = path.join(projectRoot, '_bmad-output');
+
+    if (!fs.existsSync(outputDir)) {
+      check.error = '_bmad-output/ directory not found';
+      return check;
+    }
+
+    const currentCount = await countUserDataFiles(projectRoot);
+
+    // Allow for slight variation (user guides may have been updated)
+    if (currentCount >= expectedCount - 2) {
+      check.passed = true;
+      check.info = `Files: ${currentCount} (expected: ${expectedCount})`;
+    } else {
+      check.error = `User data count mismatch: ${currentCount} (expected: ${expectedCount})`;
+    }
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
+/**
+ * Validate deprecated workflows structure
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateDeprecatedWorkflows(projectRoot) {
+  const check = {
+    name: 'Deprecated workflows',
+    passed: true, // Not required, so pass by default
+    error: null
+  };
+
+  try {
+    const deprecatedDir = path.join(projectRoot, '_bmad/bme/_vortex/workflows/_deprecated');
+
+    if (!fs.existsSync(deprecatedDir)) {
+      check.info = 'No deprecated workflows (fresh installation)';
+      return check;
+    }
+
+    // If deprecated dir exists, check for expected workflows
+    const empathyMapDir = path.join(deprecatedDir, 'empathy-map');
+    const wireframeDir = path.join(deprecatedDir, 'wireframe');
+
+    if (!fs.existsSync(empathyMapDir) && !fs.existsSync(wireframeDir)) {
+      check.warning = '_deprecated/ directory exists but is empty';
+    } else {
+      check.info = 'Deprecated workflows preserved in _deprecated/';
+    }
+
+    check.passed = true;
+  } catch (error) {
+    check.error = error.message;
+    check.passed = false;
+  }
+
+  return check;
+}
+
+/**
+ * Validate workflow step structure (P17 count + P20 filenames)
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateWorkflowStepStructure(projectRoot) {
+  const check = {
+    name: 'Workflow step structure',
+    passed: true,
+    error: null
+  };
+
+  try {
+    const workflowsDir = path.join(projectRoot, '_bmad/bme/_vortex/workflows');
+    const issues = [];
+
+    for (const workflow of WORKFLOW_NAMES) {
+      const stepsDir = path.join(workflowsDir, workflow, 'steps');
+
+      if (!fs.existsSync(stepsDir)) {
+        continue; // Placeholder workflows without steps/ are valid
+      }
+
+      const files = fs.readdirSync(stepsDir).filter(f => f.endsWith('.md'));
+
+      // P17: step count must be 4-6
+      if (files.length < 4 || files.length > 6) {
+        issues.push(`${workflow}: ${files.length} step files (expected 4-6)`);
+        continue;
+      }
+
+      // P20: standardized filenames (Wave 3 workflows only)
+      if (WAVE3_WORKFLOW_NAMES.has(workflow)) {
+        if (!files.includes('step-01-setup.md')) {
+          issues.push(`${workflow}: missing step-01-setup.md`);
+        }
+        if (!files.includes('step-02-context.md')) {
+          issues.push(`${workflow}: missing step-02-context.md`);
+        }
+        if (!files.some(f => f.endsWith('-synthesize.md'))) {
+          issues.push(`${workflow}: missing *-synthesize.md final step`);
+        }
+      }
+    }
+
+    if (issues.length > 0) {
+      check.passed = false;
+      check.error = `Step structure issues: ${issues.join('; ')}`;
+    }
+  } catch (error) {
+    check.error = error.message;
+    check.passed = false;
+  }
+
+  return check;
+}
+
+module.exports = {
+  validateInstallation,
+  validateConfigStructure,
+  validateAgentFiles,
+  validateWorkflows,
+  validateManifest,
+  validateUserDataIntegrity,
+  validateDeprecatedWorkflows,
+  validateWorkflowStepStructure
+};

package/scripts/update/lib/version-detector.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const { findProjectRoot, compareVersions, getPackageVersion } = require('./utils');
+
+/**
+ * Version Detector for Convoke
+ * Reliably detects current installed version and determines migration path
+ */
+
+/**
+ * Get current installed version from config.yaml
+ * @param {string} [projectRoot] - Project root (auto-detected if omitted)
+ * @returns {string|null} Version string or null if not found
+ */
+function getCurrentVersion(projectRoot) {
+  if (!projectRoot) {
+    projectRoot = findProjectRoot();
+  }
+  if (!projectRoot) {
+    return null; // Not in a BMAD project
+  }
+
+  try {
+    const configPath = path.join(projectRoot, '_bmad/bme/_vortex/config.yaml');
+
+    if (!fs.existsSync(configPath)) {
+      return null; // No config = fresh install
+    }
+
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = yaml.load(configContent);
+
+    if (config && config.version) {
+      return config.version;
+    }
+
+    // Fallback: Check for deprecated folder structure to guess version
+    console.warn('Warning: config.yaml exists but has no version field');
+    return guessVersionFromFileStructure(projectRoot);
+
+  } catch (error) {
+    console.warn('Warning: Could not read config.yaml:', error.message);
+    return guessVersionFromFileStructure(projectRoot);
+  }
+}
+
+/**
+ * Guess version from file structure (fallback method)
+ * @param {string} [projectRoot] - Project root (auto-detected if omitted)
+ * @returns {string|null} Guessed version or null
+ */
+function guessVersionFromFileStructure(projectRoot) {
+  if (!projectRoot) {
+    projectRoot = findProjectRoot();
+  }
+  if (!projectRoot) {
+    return null;
+  }
+
+  const vortexDir = path.join(projectRoot, '_bmad/bme/_vortex');
+
+  if (!fs.existsSync(vortexDir)) {
+    return null; // No installation
+  }
+
+  // Check for deprecated folder (exists in v1.1.0+)
+  const deprecatedDir = path.join(vortexDir, 'workflows/_deprecated');
+  if (fs.existsSync(deprecatedDir)) {
+    return '1.1.0'; // Has deprecated folder = v1.1.0+
+  }
+
+  // Check for old empathy-map workflow (v1.0.0)
+  const empathyMapDir = path.join(vortexDir, 'workflows/empathy-map');
+  if (fs.existsSync(empathyMapDir)) {
+    return '1.0.0'; // Has empathy-map in workflows = v1.0.0
+  }
+
+  // Has vortex dir but can't determine version - return null instead of guessing
+  return null;
+}
+
+/**
+ * Get target version from package.json
+ * @returns {string} Target version
+ */
+function getTargetVersion() {
+  return getPackageVersion();
+}
+
+/**
+ * Determine migration path based on versions
+ * @param {string|null} currentVersion - Current installed version
+ * @param {string} targetVersion - Target version from package
+ * @returns {object} Migration path info
+ */
+function getMigrationPath(currentVersion, targetVersion) {
+  // Fresh install (no current version)
+  if (!currentVersion) {
+    return {
+      type: 'fresh-install',
+      needsMigration: false,
+      breaking: false
+    };
+  }
+
+  // Already up to date
+  if (currentVersion === targetVersion) {
+    return {
+      type: 'up-to-date',
+      needsMigration: false,
+      breaking: false
+    };
+  }
+
+  // Downgrade attempt (not supported)
+  if (compareVersions(currentVersion, targetVersion) > 0) {
+    return {
+      type: 'downgrade',
+      needsMigration: false,
+      breaking: false,
+      fromVersion: currentVersion,
+      toVersion: targetVersion
+    };
+  }
+
+  // Upgrade needed
+  const breaking = isBreakingChange(currentVersion, targetVersion);
+
+  return {
+    type: 'upgrade-needed',
+    needsMigration: true,
+    breaking,
+    fromVersion: currentVersion,
+    toVersion: targetVersion
+  };
+}
+
+/**
+ * Detect installation scenario
+ * @param {string} [projectRoot] - Project root (auto-detected if omitted)
+ * @returns {string} Scenario: 'fresh' | 'partial' | 'complete' | 'corrupted'
+ */
+function detectInstallationScenario(projectRoot) {
+  if (!projectRoot) {
+    projectRoot = findProjectRoot();
+  }
+  if (!projectRoot) {
+    return 'fresh';
+  }
+
+  const vortexDir = path.join(projectRoot, '_bmad/bme/_vortex');
+  const configPath = path.join(vortexDir, 'config.yaml');
+  const agentsDir = path.join(vortexDir, 'agents');
+  const workflowsDir = path.join(vortexDir, 'workflows');
+
+  // No vortex directory = fresh install
+  if (!fs.existsSync(vortexDir)) {
+    return 'fresh';
+  }
+
+  // No config.yaml = partial installation
+  if (!fs.existsSync(configPath)) {
+    return 'partial';
+  }
+
+  // Check agent files
+  const requiredAgents = [
+    'contextualization-expert.md',
+    'lean-experiments-specialist.md'
+  ];
+
+  if (!fs.existsSync(agentsDir)) {
+    return 'corrupted';
+  }
+
+  const missingAgents = requiredAgents.filter(agent =>
+    !fs.existsSync(path.join(agentsDir, agent))
+  );
+
+  if (missingAgents.length > 0) {
+    return 'corrupted';
+  }
+
+  // Check workflows directory
+  if (!fs.existsSync(workflowsDir)) {
+    return 'corrupted';
+  }
+
+  return 'complete';
+}
+
+/**
+ * Determine if upgrade involves breaking changes
+ * @param {string} fromVersion - Current version
+ * @param {string} toVersion - Target version
+ * @returns {boolean} True if breaking changes exist
+ */
+function isBreakingChange(fromVersion, toVersion) {
+  // v1.0.x → any later version = breaking (empathy-map removed)
+  if (fromVersion.startsWith('1.0.')) {
+    return true;
+  }
+
+  // v1.1.x → v1.2.0 = not breaking (just updates)
+  if (fromVersion.startsWith('1.1.') && toVersion.startsWith('1.2.')) {
+    return false;
+  }
+
+  // Major version change = breaking
+  const fromMajor = parseInt(fromVersion.split('.')[0]);
+  const toMajor = parseInt(toVersion.split('.')[0]);
+
+  if (fromMajor < toMajor) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get version range pattern for migrations (e.g., "1.0.x")
+ * @param {string} version - Full version string
+ * @returns {string} Version range pattern
+ */
+function getVersionRange(version) {
+  const parts = version.split('.');
+  return `${parts[0]}.${parts[1]}.x`;
+}
+
+module.exports = {
+  getCurrentVersion,
+  getTargetVersion,
+  getMigrationPath,
+  detectInstallationScenario,
+  isBreakingChange,
+  getVersionRange,
+  guessVersionFromFileStructure
+};