convoke-agents 2.0.0

package/scripts/update/lib/migration-runner.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const yaml = require('js-yaml');
+const { findProjectRoot, getPackageVersion } = require('./utils');
+const backupManager = require('./backup-manager');
+const configMerger = require('./config-merger');
+const validator = require('./validator');
+const { refreshInstallation } = require('./refresh-installation');
+const registry = require('../migrations/registry');
+const { WORKFLOW_NAMES } = require('./agent-registry');
+
+/**
+ * Migration Runner for Convoke
+ * Core orchestration: executes migration deltas, refreshes installation, handles backups and rollback.
+ */
+
+/**
+ * Run migrations from current version to the current package version.
+ * @param {string} fromVersion - Current installed version
+ * @param {object} options - Options { dryRun, verbose }
+ * @returns {Promise<object>} Migration result
+ */
+async function runMigrations(fromVersion, options = {}) {
+  const { dryRun = false, verbose = false } = options;
+  const toVersion = getPackageVersion();
+
+  // Resolve project root
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error('Not in a Convoke project. Could not find _bmad/ directory.');
+  }
+
+  console.log('');
+  if (dryRun) {
+    console.log(chalk.yellow.bold('═══ DRY RUN MODE ═══'));
+    console.log(chalk.yellow('No changes will be made to your installation'));
+    console.log('');
+  }
+
+  // 1. Get applicable migration deltas
+  const migrations = registry.getMigrationsFor(fromVersion);
+
+  if (migrations.length === 0) {
+    console.log(chalk.yellow('No migrations needed'));
+    return { success: true, migrations: [], skipped: true };
+  }
+
+  console.log(chalk.cyan(`Found ${migrations.length} migration(s) to apply:`));
+  migrations.forEach((m, i) => {
+    const icon = m.breaking ? chalk.red('⚠') : chalk.green('✓');
+    console.log(`  ${i + 1}. ${icon} ${m.name} - ${m.description}`);
+  });
+  console.log('');
+
+  // If dry run, just preview
+  if (dryRun) {
+    return await previewMigrations(migrations);
+  }
+
+  // 2. Acquire migration lock
+  await acquireMigrationLock(projectRoot);
+
+  let backupMetadata = null;
+  const results = [];
+
+  try {
+    // 3. Create backup
+    console.log(chalk.cyan('[1/5] Creating backup...'));
+    backupMetadata = await backupManager.createBackup(fromVersion, projectRoot);
+    console.log(chalk.green(`✓ Backup created: ${path.basename(backupMetadata.backup_dir)}`));
+    console.log('');
+
+    // 4. Execute migration deltas sequentially
+    console.log(chalk.cyan('[2/5] Running migration deltas...'));
+    for (let i = 0; i < migrations.length; i++) {
+      const migration = migrations[i];
+      console.log(chalk.cyan(`\nMigration ${i + 1}/${migrations.length}: ${migration.name}`));
+
+      try {
+        const changes = await executeMigration(migration, projectRoot, { verbose });
+        results.push({
+          name: migration.name,
+          success: true,
+          changes
+        });
+
+        console.log(chalk.green(`✓ ${migration.name} completed`));
+      } catch (error) {
+        console.error(chalk.red(`✗ ${migration.name} failed: ${error.message}`));
+        throw new MigrationError(migration.name, error);
+      }
+    }
+    console.log('');
+    console.log(chalk.green('✓ All migration deltas completed'));
+    console.log('');
+
+    // 5. Refresh installation (copy latest files from package)
+    console.log(chalk.cyan('[3/5] Refreshing installation files...'));
+    const refreshChanges = await refreshInstallation(projectRoot);
+    results.push({
+      name: 'refresh-installation',
+      success: true,
+      changes: refreshChanges
+    });
+    console.log(chalk.green('✓ Installation refreshed'));
+    console.log('');
+
+    // 6. Update migration history in config.yaml
+    console.log(chalk.cyan('[4/5] Updating configuration...'));
+    await updateMigrationHistory(projectRoot, fromVersion, toVersion, results);
+    console.log(chalk.green('✓ Migration history updated'));
+    console.log('');
+
+    // 7. Validate installation
+    console.log(chalk.cyan('[5/5] Validating installation...'));
+    const validationResult = await validator.validateInstallation(backupMetadata, projectRoot);
+
+    validationResult.checks.forEach(check => {
+      if (check.passed) {
+        console.log(chalk.green(`  ✓ ${check.name}`));
+        if (check.info || check.warning) {
+          console.log(chalk.gray(`    ${check.info || check.warning}`));
+        }
+      } else {
+        console.log(chalk.red(`  ✗ ${check.name}`));
+        if (check.error) {
+          console.log(chalk.red(`    Error: ${check.error}`));
+        }
+      }
+    });
+    console.log('');
+
+    if (!validationResult.valid) {
+      throw new Error('Installation validation failed');
+    }
+
+    console.log(chalk.green('✓ Installation validated'));
+    console.log('');
+
+    // 8. Cleanup old backups
+    const deletedCount = await backupManager.cleanupOldBackups(5, projectRoot);
+    if (deletedCount > 0) {
+      console.log(chalk.green(`✓ Cleaned up ${deletedCount} old backup(s)`));
+    }
+
+    // Release lock
+    await releaseMigrationLock(projectRoot);
+
+    // Create migration log
+    await createMigrationLog(projectRoot, fromVersion, toVersion, results, backupMetadata);
+
+    return {
+      success: true,
+      fromVersion,
+      toVersion,
+      results,
+      backupMetadata
+    };
+
+  } catch (error) {
+    console.error('');
+    console.error(chalk.red.bold('✗ Migration failed!'));
+    console.error('');
+    console.error(chalk.red(error.message));
+    console.error('');
+
+    // Rollback if we have a backup
+    if (backupMetadata) {
+      console.log(chalk.yellow('Restoring from backup...'));
+      try {
+        await backupManager.restoreBackup(backupMetadata, projectRoot);
+        console.log(chalk.green('✓ Installation restored from backup'));
+        console.log('');
+      } catch (restoreError) {
+        console.error(chalk.red('✗ Restore failed!'));
+        console.error(chalk.red(restoreError.message));
+        console.error('');
+        console.error(chalk.yellow(`Manual restore may be needed from: ${backupMetadata.backup_dir}`));
+        console.error('');
+      }
+    }
+
+    // Release lock
+    await releaseMigrationLock(projectRoot);
+
+    // Create error log
+    await createErrorLog(projectRoot, fromVersion, toVersion, error, backupMetadata);
+
+    throw error;
+  }
+}
+
+/**
+ * Preview migrations without applying
+ */
+async function previewMigrations(migrations) {
+  const previews = [];
+
+  for (const migration of migrations) {
+    console.log(chalk.cyan(`\n${migration.name}:`));
+    console.log(chalk.gray(migration.description));
+
+    if (migration.module && migration.module.preview) {
+      const preview = await migration.module.preview();
+      console.log('');
+      console.log(chalk.white('Actions:'));
+      preview.actions.forEach(action => {
+        console.log(chalk.gray(`  - ${action}`));
+      });
+      previews.push({ name: migration.name, preview });
+    }
+  }
+
+  console.log('');
+  console.log(chalk.white('After deltas, installation will be refreshed:'));
+  console.log(chalk.gray('  - Refresh agent files'));
+  console.log(chalk.gray(`  - Refresh ${WORKFLOW_NAMES.length} workflow directories`));
+  console.log(chalk.gray('  - Update config.yaml (preserving user preferences)'));
+  console.log(chalk.gray('  - Update user guides (with .bak backup)'));
+  console.log('');
+  console.log(chalk.green('To apply these changes, run:'));
+  console.log(chalk.cyan('  npx convoke-update'));
+  console.log('');
+
+  return { success: true, dryRun: true, previews };
+}
+
+/**
+ * Execute a single migration delta
+ */
+async function executeMigration(migration, projectRoot, options = {}) {
+  const { verbose = false } = options;
+
+  if (!migration.module || !migration.module.apply) {
+    throw new Error(`Migration ${migration.name} has no apply function`);
+  }
+
+  const changes = await migration.module.apply(projectRoot);
+
+  if (verbose) {
+    changes.forEach(change => {
+      console.log(chalk.gray(`    - ${change}`));
+    });
+  }
+
+  return changes;
+}
+
+/**
+ * Update migration history in config.yaml
+ */
+async function updateMigrationHistory(projectRoot, fromVersion, toVersion, results) {
+  const configPath = path.join(projectRoot, '_bmad/bme/_vortex/config.yaml');
+
+  if (!fs.existsSync(configPath)) {
+    throw new Error('config.yaml not found after refresh');
+  }
+
+  const configContent = fs.readFileSync(configPath, 'utf8');
+  const config = yaml.load(configContent);
+
+  const migrationsApplied = results
+    .filter(r => r.name !== 'refresh-installation')
+    .map(r => r.name);
+
+  const updatedConfig = configMerger.addMigrationHistory(
+    config, fromVersion, toVersion, migrationsApplied
+  );
+
+  await configMerger.writeConfig(configPath, updatedConfig);
+}
+
+async function acquireMigrationLock(projectRoot) {
+  const lockFile = path.join(projectRoot, '_bmad-output/.migration-lock');
+
+  if (fs.existsSync(lockFile)) {
+    const lock = await fs.readJson(lockFile);
+    const age = Date.now() - lock.timestamp;
+
+    if (age > 5 * 60 * 1000) {
+      console.log(chalk.yellow('Removing stale migration lock'));
+      await fs.remove(lockFile);
+    } else {
+      throw new Error('Migration already in progress. Please wait and try again.');
+    }
+  }
+
+  await fs.ensureDir(path.join(projectRoot, '_bmad-output'));
+  await fs.writeJson(lockFile, { timestamp: Date.now(), pid: process.pid });
+}
+
+async function releaseMigrationLock(projectRoot) {
+  const lockFile = path.join(projectRoot, '_bmad-output/.migration-lock');
+  if (fs.existsSync(lockFile)) {
+    await fs.remove(lockFile);
+  }
+}
+
+async function createMigrationLog(projectRoot, fromVersion, toVersion, results, backupMetadata) {
+  const logsDir = path.join(projectRoot, '_bmad-output/.logs');
+  await fs.ensureDir(logsDir);
+
+  const logFile = path.join(logsDir, `migration-${Date.now()}.log`);
+  const logContent = [
+    `Convoke Migration Log`,
+    `Date: ${new Date().toISOString()}`,
+    `From Version: ${fromVersion}`,
+    `To Version: ${toVersion}`,
+    '',
+    'Migrations Applied:',
+    ...results.map(r => `  - ${r.name}`),
+    '',
+    'Changes:',
+    ...results.flatMap(r => r.changes.map(c => `  - ${c}`)),
+    '',
+    `Backup: ${backupMetadata.backup_dir}`,
+    '',
+    'Status: SUCCESS'
+  ].join('\n');
+
+  await fs.writeFile(logFile, logContent, 'utf8');
+}
+
+async function createErrorLog(projectRoot, fromVersion, toVersion, error, backupMetadata) {
+  const logsDir = path.join(projectRoot, '_bmad-output/.logs');
+  await fs.ensureDir(logsDir);
+
+  const logFile = path.join(logsDir, `migration-error-${Date.now()}.log`);
+  const logContent = [
+    `Convoke Migration Error Log`,
+    `Date: ${new Date().toISOString()}`,
+    `From Version: ${fromVersion}`,
+    `To Version: ${toVersion}`,
+    '',
+    `Error: ${error.message}`,
+    '',
+    'Stack Trace:',
+    error.stack,
+    '',
+    backupMetadata ? `Backup: ${backupMetadata.backup_dir}` : 'No backup created',
+    backupMetadata ? 'Status: ROLLED BACK' : 'Status: FAILED (no backup)',
+    '',
+    'Please report this issue at: https://github.com/amalik/convoke-agents/issues'
+  ].join('\n');
+
+  await fs.writeFile(logFile, logContent, 'utf8');
+  console.log(chalk.gray(`Migration log: ${logFile}`));
+}
+
+class MigrationError extends Error {
+  constructor(migrationName, originalError) {
+    super(`Migration ${migrationName} failed: ${originalError.message}`);
+    this.name = 'MigrationError';
+    this.migrationName = migrationName;
+    this.originalError = originalError;
+  }
+}
+
+module.exports = {
+  runMigrations,
+  previewMigrations,
+  executeMigration,
+  MigrationError
+};

package/scripts/update/lib/refresh-installation.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const { getPackageVersion } = require('./utils');
+const configMerger = require('./config-merger');
+const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES } = require('./agent-registry');
+
+/**
+ * Refresh Installation for Convoke
+ *
+ * Copies latest agent files, workflows, config, and user guides from the
+ * package to the project. Called ONCE after all migration deltas have run,
+ * or directly by the install script.
+ */
+
+/**
+ * Refresh all installation files from the package to the project.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {object} options
+ * @param {boolean} options.backupGuides - Create .bak of user guides before overwriting (default: true)
+ * @param {boolean} options.verbose - Log each action (default: true)
+ * @returns {Promise<Array<string>>} List of changes made
+ */
+async function refreshInstallation(projectRoot, options = {}) {
+  const { backupGuides = true, verbose = true } = options;
+  const changes = [];
+  const packageRoot = path.join(__dirname, '..', '..', '..');
+  const packageVortex = path.join(packageRoot, '_bmad', 'bme', '_vortex');
+  const targetVortex = path.join(projectRoot, '_bmad', 'bme', '_vortex');
+  const version = getPackageVersion();
+
+  // When running from the package's own directory (dev environment),
+  // source and destination are identical — skip file copies.
+  const isSameRoot = path.resolve(packageRoot) === path.resolve(projectRoot);
+
+  // 1. Copy agent files
+  const agentsSource = path.join(packageVortex, 'agents');
+  const agentsTarget = path.join(targetVortex, 'agents');
+  await fs.ensureDir(agentsTarget);
+
+  if (!isSameRoot) {
+    for (const file of AGENT_FILES) {
+      const src = path.join(agentsSource, file);
+      if (fs.existsSync(src)) {
+        await fs.copy(src, path.join(agentsTarget, file), { overwrite: true });
+        changes.push(`Refreshed agent: ${file}`);
+        if (verbose) console.log(`    Refreshed agent: ${file}`);
+      }
+    }
+  } else {
+    changes.push('Skipped agent copy (dev environment — files already in place)');
+    if (verbose) console.log('    Skipped agent copy (dev environment)');
+  }
+
+  // Remove deprecated agent files if still present
+  const deprecatedAgents = ['empathy-mapper.md', 'wireframe-designer.md'];
+  for (const file of deprecatedAgents) {
+    const agentPath = path.join(agentsTarget, file);
+    if (fs.existsSync(agentPath)) {
+      await fs.remove(agentPath);
+      changes.push(`Removed deprecated agent: ${file}`);
+      if (verbose) console.log(`    Removed deprecated agent: ${file}`);
+    }
+  }
+
+  // 2. Copy workflow directories
+  const workflowsSource = path.join(packageVortex, 'workflows');
+  const workflowsTarget = path.join(targetVortex, 'workflows');
+  await fs.ensureDir(workflowsTarget);
+
+  if (!isSameRoot) {
+    for (const wf of WORKFLOW_NAMES) {
+      const src = path.join(workflowsSource, wf);
+      if (fs.existsSync(src)) {
+        await fs.copy(src, path.join(workflowsTarget, wf), { overwrite: true });
+        changes.push(`Refreshed workflow: ${wf}`);
+        if (verbose) console.log(`    Refreshed workflow: ${wf}`);
+      }
+    }
+  } else {
+    changes.push('Skipped workflow copy (dev environment — files already in place)');
+    if (verbose) console.log('    Skipped workflow copy (dev environment)');
+  }
+
+  // 3. Update config.yaml (merge, preserving user prefs)
+  const configPath = path.join(targetVortex, 'config.yaml');
+  await fs.ensureDir(path.dirname(configPath));
+
+  const updates = {
+    agents: AGENT_IDS,
+    workflows: WORKFLOW_NAMES
+  };
+
+  const merged = await configMerger.mergeConfig(configPath, version, updates);
+  await configMerger.writeConfig(configPath, merged);
+  changes.push(`Updated config.yaml to v${version}`);
+  if (verbose) console.log(`    Updated config.yaml to v${version}`);
+
+  // 4. Regenerate agent manifest — replace only bme rows, preserve other modules
+  const manifestPath = path.join(projectRoot, '_bmad', '_config', 'agent-manifest.csv');
+  await fs.ensureDir(path.dirname(manifestPath));
+
+  function csvEscape(value) {
+    return `"${String(value).replace(/"/g, '""')}"`;
+  }
+
+  const header = '"agent_id","name","title","icon","role","identity","communication_style","expertise","submodule","path"';
+
+  // Read existing non-bme rows to preserve them
+  let preservedRows = [];
+  if (fs.existsSync(manifestPath)) {
+    const existing = (await fs.readFile(manifestPath, 'utf8')).trim().split('\n');
+    // Skip header, keep rows where submodule is NOT bme
+    preservedRows = existing.slice(1).filter(row => {
+      // submodule is the 9th field (index 8) in the CSV
+      const fields = row.match(/"([^"]*(?:""[^"]*)*)"/g);
+      if (!fields || fields.length < 9) return true; // keep unrecognised rows
+      const submodule = fields[8].replace(/^"|"$/g, '');
+      return submodule !== 'bme';
+    });
+  }
+
+  // Build fresh bme rows from registry
+  const bmeRows = AGENTS.map(a => {
+    const p = a.persona;
+    return [
+      a.id, a.name, a.title, a.icon,
+      p.role, p.identity, p.communication_style, p.expertise,
+      'bme', `_bmad/bme/_vortex/agents/${a.id}.md`,
+    ].map(csvEscape).join(',');
+  });
+
+  const allRows = [...preservedRows, ...bmeRows].join('\n') + '\n';
+  await fs.writeFile(manifestPath, header + '\n' + allRows, 'utf8');
+  changes.push('Regenerated agent-manifest.csv (bme rows updated, other modules preserved)');
+  if (verbose) console.log('    Regenerated agent-manifest.csv (bme rows updated, other modules preserved)');
+
+  // 5. Copy user guides (with optional backup)
+  const guidesSource = path.join(packageRoot, '_bmad', 'bme', '_vortex', 'guides');
+  const guidesTarget = path.join(projectRoot, '_bmad', 'bme', '_vortex', 'guides');
+  await fs.ensureDir(guidesTarget);
+
+  if (!isSameRoot) {
+    for (const guide of USER_GUIDES) {
+      const src = path.join(guidesSource, guide);
+      const dest = path.join(guidesTarget, guide);
+
+      if (fs.existsSync(src)) {
+        // Backup existing guide before overwriting
+        if (backupGuides && fs.existsSync(dest)) {
+          await fs.copy(dest, dest + '.bak', { overwrite: true });
+          changes.push(`Backed up ${guide} → ${guide}.bak`);
+          if (verbose) console.log(`    Backed up ${guide} → ${guide}.bak`);
+        }
+
+        await fs.copy(src, dest, { overwrite: true });
+        changes.push(`Refreshed guide: ${guide}`);
+        if (verbose) console.log(`    Refreshed guide: ${guide}`);
+      }
+    }
+  } else {
+    changes.push('Skipped guide copy (dev environment — files already in place)');
+    if (verbose) console.log('    Skipped guide copy (dev environment)');
+  }
+
+  return changes;
+}
+
+module.exports = { refreshInstallation };

package/scripts/update/lib/utils.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Shared utilities for the Convoke update system.
+ * Single source of truth for version, comparison, project detection.
+ */
+
+/**
+ * Get the package version at runtime from package.json.
+ * This is the SINGLE SOURCE OF TRUTH for version - never hardcode versions elsewhere.
+ * @returns {string} e.g. "1.3.8"
+ */
+function getPackageVersion() {
+  const pkg = require('../../../package.json');
+  return pkg.version;
+}
+
+/**
+ * Compare two semantic version strings.
+ * @param {string} v1
+ * @param {string} v2
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+function compareVersions(v1, v2) {
+  const parts1 = v1.split('.').map(Number);
+  const parts2 = v2.split('.').map(Number);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+
+  return 0;
+}
+
+/**
+ * Count user data files in _bmad-output/ (excluding .backups, .logs).
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<number>}
+ */
+async function countUserDataFiles(projectRoot) {
+  const outputDir = path.join(projectRoot, '_bmad-output');
+
+  if (!fs.existsSync(outputDir)) {
+    return 0;
+  }
+
+  let count = 0;
+
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === '.backups' || entry.name === '.logs') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile()) {
+        count++;
+      }
+    }
+  }
+
+  await walk(outputDir);
+  return count;
+}
+
+/**
+ * Find the project root by walking up from cwd looking for _bmad/ directory.
+ * @returns {string|null} Absolute path to project root, or null if not found
+ */
+function findProjectRoot() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+
+  while (true) {
+    if (fs.existsSync(path.join(dir, '_bmad'))) {
+      return dir;
+    }
+    if (dir === root) break;
+    dir = path.dirname(dir);
+  }
+
+  return null;
+}
+
+module.exports = {
+  getPackageVersion,
+  compareVersions,
+  countUserDataFiles,
+  findProjectRoot
+};