claude-flow-novice 2.2.4 → 2.2.5

package/scripts/migration/migrate-hooks.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+/**
+ * Migration script to update Claude Flow settings.json to new hooks format
+ * Compatible with Claude Code 1.0.51+
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function migrateSettingsFile(settingsPath) {
+  try {
+    // Read existing settings
+    const content = await fs.readFile(settingsPath, 'utf8');
+    const settings = JSON.parse(content);
+    
+    // Check if hooks already in new format
+    if (settings.hooks && settings.hooks.PreToolUse) {
+      console.log('✅ Hooks already in new format, no migration needed');
+      return;
+    }
+    
+    // Backup original file
+    const backupPath = settingsPath + '.backup-' + Date.now();
+    await fs.writeFile(backupPath, content);
+    console.log(`📦 Backed up original settings to: ${backupPath}`);
+    
+    // Convert old hooks format to new format
+    const newHooks = {
+      PreToolUse: [],
+      PostToolUse: [],
+      Stop: []
+    };
+    
+    // Convert preCommandHook
+    if (settings.hooks?.preCommandHook) {
+      newHooks.PreToolUse.push({
+        matcher: "Bash",
+        hooks: [{
+          type: "command",
+          command: `npx claude-flow@alpha hooks pre-command --command "\${command}" --validate-safety true --prepare-resources true`
+        }]
+      });
+    }
+    
+    // Convert preEditHook
+    if (settings.hooks?.preEditHook) {
+      newHooks.PreToolUse.push({
+        matcher: "Write|Edit|MultiEdit",
+        hooks: [{
+          type: "command",
+          command: `npx claude-flow@alpha hooks pre-edit --file "\${file}" --auto-assign-agents true --load-context true`
+        }]
+      });
+    }
+    
+    // Convert postCommandHook
+    if (settings.hooks?.postCommandHook) {
+      newHooks.PostToolUse.push({
+        matcher: "Bash",
+        hooks: [{
+          type: "command",
+          command: `npx claude-flow@alpha hooks post-command --command "\${command}" --track-metrics true --store-results true`
+        }]
+      });
+    }
+    
+    // Convert postEditHook
+    if (settings.hooks?.postEditHook) {
+      newHooks.PostToolUse.push({
+        matcher: "Write|Edit|MultiEdit",
+        hooks: [{
+          type: "command",
+          command: `npx claude-flow@alpha hooks post-edit --file "\${file}" --format true --update-memory true --train-neural true`
+        }]
+      });
+    }
+    
+    // Convert sessionEndHook
+    if (settings.hooks?.sessionEndHook) {
+      newHooks.Stop.push({
+        hooks: [{
+          type: "command",
+          command: `npx claude-flow@alpha hooks session-end --generate-summary true --persist-state true --export-metrics true`
+        }]
+      });
+    }
+    
+    // Update settings with new hooks format
+    settings.hooks = newHooks;
+    
+    // Remove unrecognized fields for Claude Code 1.0.51+
+    delete settings.mcpServers;
+    delete settings.features;
+    delete settings.performance;
+    
+    // Write updated settings
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    console.log('✅ Successfully migrated settings.json to new hooks format');
+    
+    // Show removed fields
+    console.log('\n📝 Note: The following fields were removed (not supported by Claude Code 1.0.51+):');
+    console.log('   - mcpServers (use "claude mcp add" command instead)');
+    console.log('   - features');
+    console.log('   - performance');
+    
+  } catch (error) {
+    console.error('❌ Error migrating settings:', error.message);
+    process.exit(1);
+  }
+}
+
+async function findSettingsFiles() {
+  const locations = [
+    path.join(process.cwd(), '.claude', 'settings.json'),
+    path.join(process.cwd(), 'settings.json'),
+    path.join(process.env.HOME || '', '.claude', 'settings.json')
+  ];
+  
+  const found = [];
+  for (const location of locations) {
+    try {
+      await fs.access(location);
+      found.push(location);
+    } catch {
+      // File doesn't exist, skip
+    }
+  }
+  
+  return found;
+}
+
+async function main() {
+  console.log('🔄 Claude Flow Hooks Migration Script\n');
+  
+  // Check if specific file provided
+  const args = process.argv.slice(2);
+  if (args.length > 0) {
+    const targetFile = args[0];
+    console.log(`Migrating specific file: ${targetFile}`);
+    await migrateSettingsFile(targetFile);
+  } else {
+    // Find and migrate all settings files
+    const files = await findSettingsFiles();
+    
+    if (files.length === 0) {
+      console.log('❌ No settings.json files found to migrate');
+      console.log('\nSearched locations:');
+      console.log('  - .claude/settings.json');
+      console.log('  - settings.json');
+      console.log('  - ~/.claude/settings.json');
+      return;
+    }
+    
+    console.log(`Found ${files.length} settings file(s) to migrate:\n`);
+    
+    for (const file of files) {
+      console.log(`\n📍 Migrating: ${file}`);
+      await migrateSettingsFile(file);
+    }
+  }
+  
+  console.log('\n✨ Migration complete!');
+  console.log('\nNext steps:');
+  console.log('1. Restart Claude Code to apply changes');
+  console.log('2. Run "claude mcp add claude-flow npx claude-flow@alpha mcp start" to add MCP server');
+  console.log('3. Check /doctor in Claude Code to verify settings are valid');
+}
+
+main().catch(console.error);

package/scripts/migration/migration-examples.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * Migration Examples and Usage Scenarios
+ * Demonstrates different migration scenarios and best practices
+ */
+
+import * as chalk from 'chalk';
+import * as path from 'path';
+import { MigrationRunner } from '../src/migration/migration-runner';
+import { MigrationAnalyzer } from '../src/migration/migration-analyzer';
+import { RollbackManager } from '../src/migration/rollback-manager';
+
+// Example 1: Basic Project Migration
+async function basicMigration() {
+  console.log(chalk.bold('\n🔄 Example 1: Basic Project Migration'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  const projectPath = path.join(__dirname, '../examples/basic-project');
+  
+  // Step 1: Analyze the project
+  console.log('\n1. Analyzing project...');
+  const analyzer = new MigrationAnalyzer();
+  const analysis = await analyzer.analyze(projectPath);
+  
+  if (analysis.hasClaudeFolder) {
+    console.log(chalk.green('   ✓ Found existing .claude folder'));
+  } else {
+    console.log(chalk.yellow('   ! No .claude folder found - fresh installation'));
+  }
+  
+  // Step 2: Run migration
+  console.log('\n2. Running migration...');
+  const runner = new MigrationRunner({
+    projectPath,
+    strategy: 'selective',
+    preserveCustom: true,
+    dryRun: true // Safe mode for example
+  });
+  
+  const result = await runner.run();
+  
+  if (result.success) {
+    console.log(chalk.green('   ✓ Migration completed successfully'));
+  } else {
+    console.log(chalk.red('   ✗ Migration failed'));
+    result.errors.forEach(error => console.log(`     ${error.error}`));
+  }
+}
+
+// Example 2: Complex Project with Custom Commands
+async function complexProjectMigration() {
+  console.log(chalk.bold('\n🔧 Example 2: Complex Project Migration'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  const projectPath = path.join(__dirname, '../examples/complex-project');
+  
+  console.log('\n1. Analyzing complex project...');
+  const analyzer = new MigrationAnalyzer();
+  const analysis = await analyzer.analyze(projectPath);
+  
+  console.log(`   Custom commands found: ${analysis.customCommands.length}`);
+  console.log(`   Conflicting files: ${analysis.conflictingFiles.length}`);
+  
+  // Show recommended strategy
+  const strategy = analysis.customCommands.length > 0 ? 'merge' : 'selective';
+  console.log(`   Recommended strategy: ${chalk.cyan(strategy)}`);
+  
+  console.log('\n2. Creating backup...');
+  const rollbackManager = new RollbackManager(projectPath);
+  const backup = await rollbackManager.createBackup({
+    type: 'pre-migration',
+    scenario: 'complex-project-example'
+  });
+  
+  console.log(`   ✓ Backup created: ${backup.metadata.backupId}`);
+  
+  console.log('\n3. Running merge migration...');
+  const runner = new MigrationRunner({
+    projectPath,
+    strategy: 'merge',
+    preserveCustom: true,
+    dryRun: true
+  });
+  
+  await runner.run();
+}
+
+// Example 3: Rollback Scenario
+async function rollbackExample() {
+  console.log(chalk.bold('\n↩️  Example 3: Rollback Scenario'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  const projectPath = path.join(__dirname, '../examples/rollback-test');
+  const rollbackManager = new RollbackManager(projectPath);
+  
+  console.log('\n1. Listing available backups...');
+  const backups = await rollbackManager.listBackups();
+  rollbackManager.printBackupSummary(backups);
+  
+  if (backups.length > 0) {
+    console.log('\n2. Rolling back to latest backup...');
+    const latestBackup = backups[0];
+    
+    // In a real scenario, this would prompt for confirmation
+    console.log(`   Would rollback to: ${latestBackup.timestamp.toLocaleString()}`);
+    console.log(`   Files to restore: ${latestBackup.files.length}`);
+  } else {
+    console.log(chalk.yellow('   No backups available for rollback'));
+  }
+}
+
+// Example 4: Migration Validation
+async function validationExample() {
+  console.log(chalk.bold('\n✅ Example 4: Migration Validation'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  const projectPath = path.join(__dirname, '../examples/validation-test');
+  
+  console.log('\n1. Running post-migration validation...');
+  const runner = new MigrationRunner({
+    projectPath,
+    strategy: 'selective'
+  });
+  
+  const isValid = await runner.validate(true);
+  
+  if (isValid) {
+    console.log(chalk.green('   ✓ All validation checks passed'));
+  } else {
+    console.log(chalk.red('   ✗ Validation failed'));
+  }
+}
+
+// Example 5: Batch Migration for Multiple Projects
+async function batchMigrationExample() {
+  console.log(chalk.bold('\n📦 Example 5: Batch Migration'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  const projects = [
+    path.join(__dirname, '../examples/project-1'),
+    path.join(__dirname, '../examples/project-2'),
+    path.join(__dirname, '../examples/project-3')
+  ];
+  
+  console.log(`\n1. Migrating ${projects.length} projects...`);
+  
+  for (const [index, projectPath] of projects.entries()) {
+    console.log(`\n   Project ${index + 1}: ${path.basename(projectPath)}`);
+    
+    try {
+      // Analyze first
+      const analyzer = new MigrationAnalyzer();
+      const analysis = await analyzer.analyze(projectPath);
+      
+      // Choose strategy based on analysis
+      const strategy = analysis.customCommands.length > 0 ? 'merge' : 'selective';
+      
+      // Run migration
+      const runner = new MigrationRunner({
+        projectPath,
+        strategy,
+        preserveCustom: true,
+        force: true, // Non-interactive for batch
+        dryRun: true
+      });
+      
+      const result = await runner.run();
+      
+      if (result.success) {
+        console.log(chalk.green(`     ✓ Migration successful`));
+      } else {
+        console.log(chalk.red(`     ✗ Migration failed`));
+      }
+      
+    } catch (error) {
+      console.log(chalk.red(`     ✗ Error: ${error.message}`));
+    }
+  }
+}
+
+// Example 6: Migration Conflict Resolution
+async function conflictResolutionExample() {
+  console.log(chalk.bold('\n⚠️  Example 6: Conflict Resolution'));
+  console.log(chalk.gray('─'.repeat(50)));
+  
+  const projectPath = path.join(__dirname, '../examples/conflict-project');
+  
+  console.log('\n1. Analyzing project for conflicts...');
+  const analyzer = new MigrationAnalyzer();
+  const analysis = await analyzer.analyze(projectPath);
+  
+  if (analysis.conflictingFiles.length > 0) {
+    console.log(chalk.yellow(`   Found ${analysis.conflictingFiles.length} conflicting files:`));
+    analysis.conflictingFiles.forEach(file => {
+      console.log(`     • ${file}`);
+    });
+    
+    console.log('\n2. Resolution strategies:');
+    console.log('     a) Merge strategy - Preserves custom content');
+    console.log('     b) Selective strategy - Skip conflicting files');
+    console.log('     c) Full strategy - Replace all files (with backup)');
+    
+    console.log('\n3. Recommended approach:');
+    console.log(chalk.cyan('     Use merge strategy with manual review'));
+    
+  } else {
+    console.log(chalk.green('   ✓ No conflicts detected'));
+  }
+}
+
+// Usage scenarios documentation
+function printUsageScenarios() {
+  console.log(chalk.bold('\n📚 Migration Usage Scenarios'));
+  console.log(chalk.gray('═'.repeat(70)));
+  
+  const scenarios = [
+    {
+      title: 'New Project Setup',
+      command: 'claude-flow migrate --strategy full',
+      description: 'Clean installation of optimized prompts'
+    },
+    {
+      title: 'Existing Project with Custom Commands',
+      command: 'claude-flow migrate --strategy merge --preserve-custom',
+      description: 'Preserve customizations while upgrading'
+    },
+    {
+      title: 'Safe Migration with Preview',
+      command: 'claude-flow migrate --dry-run --verbose',
+      description: 'See what would change before migrating'
+    },
+    {
+      title: 'Analysis Only',
+      command: 'claude-flow migrate analyze --detailed',
+      description: 'Understand project state before migration'
+    },
+    {
+      title: 'Rollback After Issues',
+      command: 'claude-flow migrate rollback',
+      description: 'Restore previous configuration'
+    },
+    {
+      title: 'Batch Operation',
+      command: 'find . -name ".claude" -exec claude-flow migrate {} \\;',
+      description: 'Migrate multiple projects at once'
+    }
+  ];
+  
+  scenarios.forEach((scenario, index) => {
+    console.log(`\n${chalk.bold(`${index + 1}. ${scenario.title}`)}`);
+    console.log(`   ${chalk.cyan(scenario.command)}`);
+    console.log(`   ${chalk.gray(scenario.description)}`);
+  });
+  
+  console.log(chalk.gray('\n' + '═'.repeat(70)));
+}
+
+// Best practices guide
+function printBestPractices() {
+  console.log(chalk.bold('\n💡 Migration Best Practices'));
+  console.log(chalk.gray('═'.repeat(70)));
+  
+  const practices = [
+    'Always analyze projects before migration',
+    'Use --dry-run flag to preview changes',
+    'Create backups before major migrations',
+    'Use selective or merge strategies for projects with customizations',
+    'Validate migrations after completion',
+    'Keep backups for rollback scenarios',
+    'Test functionality after migration',
+    'Document custom modifications for future reference'
+  ];
+  
+  practices.forEach((practice, index) => {
+    console.log(`${chalk.green(`${index + 1}.`)} ${practice}`);
+  });
+  
+  console.log(chalk.gray('\n' + '═'.repeat(70)));
+}
+
+// Main execution
+async function main() {
+  console.log(chalk.bold.blue('\n🚀 Claude-Flow Migration Examples\n'));
+  
+  try {
+    // Run examples (in dry-run mode for safety)
+    await basicMigration();
+    await complexProjectMigration();
+    await rollbackExample();
+    await validationExample();
+    await batchMigrationExample();
+    await conflictResolutionExample();
+    
+    // Print documentation
+    printUsageScenarios();
+    printBestPractices();
+    
+    console.log(chalk.bold.green('\n✅ All examples completed successfully!\n'));
+    
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Example failed: ${error.message}\n`));
+    process.exit(1);
+  }
+}
+
+// Run examples if called directly
+if (require.main === module) {
+  main();
+}
+
+export {
+  basicMigration,
+  complexProjectMigration,
+  rollbackExample,
+  validationExample,
+  batchMigrationExample,
+  conflictResolutionExample
+};