@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/onboard.ts

@@ -0,0 +1,663 @@
+/**
+ * Bootspring Onboard CLI
+ *
+ * Layer Bootspring onto existing projects with stack detection,
+ * pattern scanning, and configuration generation.
+ *
+ * @package bootspring
+ * @module cli/onboard
+ */
+
+// Import JS modules with type interfaces
+interface ParsedArgs {
+  _: string[];
+  'dry-run'?: boolean | undefined;
+  'skip-optional'?: boolean | undefined;
+  quick?: boolean | undefined;
+  apply?: boolean | undefined;
+}
+
+interface PhaseConfig {
+  name: string;
+  description: string;
+  required: boolean;
+}
+
+interface TechInfo {
+  name: string;
+}
+
+interface StackInfo {
+  framework?: TechInfo | undefined;
+  language?: TechInfo | undefined;
+  database?: TechInfo | undefined;
+  hosting?: TechInfo | undefined;
+  auth?: TechInfo | undefined;
+  payments?: TechInfo | undefined;
+  detected: TechInfo[];
+}
+
+interface StructureStats {
+  totalFiles: number;
+  totalDirs: number;
+}
+
+interface DetectionResult {
+  stack: StackInfo;
+  structure: {
+    stats: StructureStats;
+  };
+}
+
+interface ArchitecturePattern {
+  name: string;
+  confidence: number;
+}
+
+interface PatternResult {
+  architecture: {
+    patterns: ArchitecturePattern[];
+  };
+  features?: Record<string, boolean> | undefined;
+  quickMode?: boolean | undefined;
+}
+
+interface DocInfo {
+  file: string;
+}
+
+interface DocResult {
+  found: DocInfo[];
+  missing: DocInfo[];
+}
+
+interface ConfigResult {
+  files: string[];
+}
+
+interface BaselineResult {
+  timestamp: string;
+}
+
+interface OverallProgress {
+  completed: number;
+  total: number;
+  percentage: number;
+}
+
+interface PhaseProgress {
+  name: string;
+  status: string;
+  required: boolean;
+}
+
+interface WorkflowProgress {
+  overall: OverallProgress;
+  isComplete: boolean;
+  currentPhase?: string | undefined;
+  phases: PhaseProgress[];
+  startedAt?: string | undefined;
+  lastUpdated?: string | undefined;
+  detection?: {
+    stack?: StackInfo | undefined;
+  } | undefined;
+}
+
+interface ResumePoint {
+  phaseName: string;
+}
+
+interface OnboardWorkflowEngineClass {
+  new (projectRoot: string): OnboardWorkflowEngine;
+}
+
+interface OnboardWorkflowEngine {
+  hasWorkflow(): boolean;
+  loadState(): void;
+  initializeWorkflow(): void;
+  getProgress(): WorkflowProgress;
+  getResumePoint(): ResumePoint | null;
+  getNextPhase(): string | null;
+  startPhase(phaseId: string): void;
+  completePhase(phaseId: string, result?: unknown): void;
+  failPhase(phaseId: string, error: string): void;
+  skipPhase(phaseId: string): void;
+  resetWorkflow(): void;
+  applyGeneratedFiles(): void;
+  runDetection(): Promise<DetectionResult>;
+  runPatternScan(): Promise<PatternResult>;
+  runQuickPatternScan(): Promise<PatternResult>;
+  runDocDiscovery(): Promise<DocResult>;
+  runConfigGeneration(): Promise<ConfigResult>;
+  runBaselineCapture(): Promise<BaselineResult>;
+}
+
+interface OnboardWorkflowModule {
+  OnboardWorkflowEngine: OnboardWorkflowEngineClass;
+  ONBOARD_PHASES: Record<string, PhaseConfig>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const utils = require('../../core/utils') as typeof import('../core/utils');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const onboardWorkflowModule = require('../../core/onboard-workflow') as OnboardWorkflowModule;
+
+const { OnboardWorkflowEngine, ONBOARD_PHASES } = onboardWorkflowModule;
+
+// Get project root
+const projectRoot = process.cwd();
+
+/**
+ * Show onboard help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.bold}Bootspring Onboard${utils.COLORS.reset}
+Layer Bootspring onto existing projects
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring onboard              Start interactive onboarding
+  bootspring onboard status       Show progress
+  bootspring onboard resume       Continue from checkpoint
+  bootspring onboard detect       Run detection only
+  bootspring onboard generate     Generate config only
+  bootspring onboard reset        Reset workflow
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --dry-run                       Preview without changes
+  --skip-optional                 Skip optional phases
+  --quick                         Force fast mode (auto for 500+ files)
+  --apply                         Apply generated files
+
+${utils.COLORS.bold}Notes:${utils.COLORS.reset}
+  Large codebases (500+ files) automatically use fast mode to skip
+  heavy dependency analysis. Use --quick to force it on smaller projects.
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring onboard              Auto-detects and adjusts for codebase size
+  bootspring onboard status
+  bootspring onboard --dry-run
+`);
+}
+
+/**
+ * Start onboarding workflow
+ */
+async function onboardStart(args: ParsedArgs): Promise<void> {
+  const workflow = new OnboardWorkflowEngine(projectRoot);
+
+  // Check for existing workflow
+  if (workflow.hasWorkflow()) {
+    workflow.loadState();
+    const progress = workflow.getProgress();
+
+    if (!progress.isComplete) {
+      utils.print.info('Existing onboarding workflow found.');
+      console.log(`  Progress: ${progress.overall.percentage}% complete`);
+      console.log(`  Current phase: ${progress.currentPhase || 'none'}`);
+      console.log('');
+      utils.print.info('Use "bootspring onboard resume" to continue');
+      utils.print.info('Use "bootspring onboard reset" to start fresh');
+      return;
+    }
+  }
+
+  // Initialize new workflow
+  utils.print.header('Bootspring Onboarding');
+  console.log('Analyzing your existing codebase...\n');
+
+  workflow.initializeWorkflow();
+
+  // Run workflow
+  await runWorkflowLoop(workflow, args);
+}
+
+/**
+ * Resume onboarding workflow
+ */
+async function onboardResume(args: ParsedArgs): Promise<void> {
+  const workflow = new OnboardWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.error('No existing workflow found.');
+    utils.print.info('Run "bootspring onboard" to start.');
+    return;
+  }
+
+  workflow.loadState();
+  const resumePoint = workflow.getResumePoint();
+
+  if (!resumePoint) {
+    utils.print.success('Onboarding workflow already complete!');
+    return;
+  }
+
+  utils.print.header('Resuming Onboarding');
+  console.log(`Continuing from: ${resumePoint.phaseName}`);
+  console.log('');
+
+  await runWorkflowLoop(workflow, args);
+}
+
+/**
+ * Run the workflow loop
+ */
+async function runWorkflowLoop(workflow: OnboardWorkflowEngine, args: ParsedArgs): Promise<void> {
+  const dryRun = args['dry-run'] || false;
+  const skipOptional = args['skip-optional'] || false;
+  const quickMode = args.quick || false;
+
+  while (true) {
+    const nextPhaseId = workflow.getNextPhase();
+
+    if (!nextPhaseId) {
+      // Workflow complete
+      break;
+    }
+
+    const phase = ONBOARD_PHASES[nextPhaseId];
+    if (!phase) continue;
+
+    // Skip optional phases if requested
+    if (skipOptional && !phase.required) {
+      workflow.skipPhase(nextPhaseId);
+      utils.print.dim(`Skipping optional phase: ${phase.name}`);
+      continue;
+    }
+
+    // Run the phase
+    workflow.startPhase(nextPhaseId);
+    const spinner = utils.createSpinner(`Running: ${phase.name}`).start();
+
+    try {
+      let result: unknown;
+
+      switch (nextPhaseId) {
+        case 'detection': {
+          const detectionResult = await workflow.runDetection();
+          spinner.succeed(`Detection complete: Found ${detectionResult.stack.detected.length} technologies`);
+          displayDetectionResults(detectionResult);
+          result = detectionResult;
+          break;
+        }
+
+        case 'patterns': {
+          let patternResult: PatternResult;
+          if (quickMode) {
+            // Quick mode: skip heavy dependency analysis, just detect features
+            patternResult = await workflow.runQuickPatternScan();
+            spinner.succeed('Quick pattern scan complete');
+          } else {
+            patternResult = await workflow.runPatternScan();
+            if (patternResult.quickMode) {
+              // Auto-detected large codebase
+              spinner.succeed('Pattern scan complete (large codebase - quick mode)');
+            } else {
+              spinner.succeed(`Pattern scan complete: ${patternResult.architecture.patterns.length} patterns found`);
+            }
+          }
+          displayPatternResults(patternResult);
+          result = patternResult;
+          break;
+        }
+
+        case 'docs': {
+          const docResult = await workflow.runDocDiscovery();
+          spinner.succeed(`Doc discovery complete: ${docResult.found.length} docs found, ${docResult.missing.length} missing`);
+          displayDocResults(docResult);
+          result = docResult;
+          break;
+        }
+
+        case 'config': {
+          const configResult = await workflow.runConfigGeneration();
+          spinner.succeed('Configuration generated');
+          displayConfigResults(configResult, dryRun);
+          result = configResult;
+          break;
+        }
+
+        case 'baseline': {
+          const baselineResult = await workflow.runBaselineCapture();
+          spinner.succeed('Baseline captured');
+          result = baselineResult;
+          break;
+        }
+
+        case 'reverse':
+          // Skip for now - optional
+          spinner.info('Skipping reverse engineering (optional)');
+          workflow.skipPhase(nextPhaseId);
+          continue;
+
+        default:
+          spinner.warn(`Unknown phase: ${nextPhaseId}`);
+          workflow.skipPhase(nextPhaseId);
+          continue;
+      }
+
+      workflow.completePhase(nextPhaseId, result);
+
+    } catch (error) {
+      spinner.fail(`Failed: ${(error as Error).message}`);
+      workflow.failPhase(nextPhaseId, (error as Error).message);
+
+      if (phase.required) {
+        utils.print.error('Required phase failed. Cannot continue.');
+        return;
+      }
+    }
+
+    console.log('');
+  }
+
+  // Workflow complete
+  utils.print.success('Onboarding complete!');
+  console.log('');
+
+  const progress = workflow.getProgress();
+
+  // Apply files if requested
+  const shouldApply = args.apply || false;
+  if (shouldApply && !dryRun) {
+    utils.print.info('Applying generated files...');
+    workflow.applyGeneratedFiles();
+    utils.print.success('bootspring.config.js and CLAUDE.md created');
+  } else if (!dryRun) {
+    utils.print.info('Generated files are in .bootspring/onboard/generated/');
+    utils.print.info('Run with --apply to copy them to project root');
+  }
+
+  // Show summary
+  console.log('');
+  utils.print.header('Summary');
+  console.log(`  Stack: ${formatStack(progress.detection?.stack)}`);
+  console.log(`  Phases completed: ${progress.overall.completed}/${progress.overall.total}`);
+  console.log('');
+  utils.print.info('Next steps:');
+  console.log('  1. Review generated configuration');
+  console.log('  2. Run "bootspring analyze" for deeper insights');
+  console.log('  3. Run "bootspring audit" for quality checks');
+}
+
+/**
+ * Display detection results
+ */
+function displayDetectionResults(result: DetectionResult): void {
+  console.log('');
+
+  if (result.stack.framework) {
+    console.log(`  ${utils.COLORS.cyan}Framework:${utils.COLORS.reset} ${result.stack.framework.name}`);
+  }
+  if (result.stack.language) {
+    console.log(`  ${utils.COLORS.cyan}Language:${utils.COLORS.reset} ${result.stack.language.name}`);
+  }
+  if (result.stack.database) {
+    console.log(`  ${utils.COLORS.cyan}Database:${utils.COLORS.reset} ${result.stack.database.name}`);
+  }
+  if (result.stack.hosting) {
+    console.log(`  ${utils.COLORS.cyan}Hosting:${utils.COLORS.reset} ${result.stack.hosting.name}`);
+  }
+  if (result.stack.auth) {
+    console.log(`  ${utils.COLORS.cyan}Auth:${utils.COLORS.reset} ${result.stack.auth.name}`);
+  }
+  if (result.stack.payments) {
+    console.log(`  ${utils.COLORS.cyan}Payments:${utils.COLORS.reset} ${result.stack.payments.name}`);
+  }
+
+  console.log('');
+  console.log(`  ${utils.COLORS.dim}Files: ${result.structure.stats.totalFiles} | Dirs: ${result.structure.stats.totalDirs}${utils.COLORS.reset}`);
+}
+
+/**
+ * Display pattern results
+ */
+function displayPatternResults(result: PatternResult): void {
+  if (result.architecture.patterns.length > 0) {
+    console.log('');
+    console.log('  Detected patterns:');
+    for (const pattern of result.architecture.patterns.slice(0, 3)) {
+      console.log(`    - ${pattern.name} (${pattern.confidence}%)`);
+    }
+  }
+
+  if (result.features) {
+    const activeFeatures = Object.entries(result.features)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+
+    if (activeFeatures.length > 0) {
+      console.log('');
+      console.log('  Detected features:');
+      console.log(`    ${activeFeatures.join(', ')}`);
+    }
+  }
+}
+
+/**
+ * Display documentation results
+ */
+function displayDocResults(result: DocResult): void {
+  if (result.found.length > 0) {
+    console.log('');
+    console.log('  Found documentation:');
+    for (const doc of result.found.slice(0, 5)) {
+      console.log(`    ${utils.COLORS.green}✓${utils.COLORS.reset} ${doc.file}`);
+    }
+  }
+
+  if (result.missing.length > 0) {
+    console.log('');
+    console.log('  Missing (recommended):');
+    for (const doc of result.missing) {
+      console.log(`    ${utils.COLORS.yellow}○${utils.COLORS.reset} ${doc.file}`);
+    }
+  }
+}
+
+/**
+ * Display config generation results
+ */
+function displayConfigResults(result: ConfigResult, dryRun: boolean): void {
+  console.log('');
+
+  if (dryRun) {
+    console.log(`  ${utils.COLORS.dim}[DRY RUN] Would generate:${utils.COLORS.reset}`);
+  } else {
+    console.log('  Generated:');
+  }
+
+  console.log('    - bootspring.config.js');
+  console.log('    - CLAUDE.md');
+}
+
+/**
+ * Format stack for display
+ */
+function formatStack(stack: StackInfo | undefined): string {
+  if (!stack) return 'Unknown';
+
+  const parts: string[] = [];
+  if (stack.framework) parts.push(stack.framework.name);
+  if (stack.language) parts.push(stack.language.name);
+  if (stack.database) parts.push(stack.database.name);
+
+  return parts.join(' + ') || 'Unknown';
+}
+
+/**
+ * Show onboard status
+ */
+async function onboardStatus(): Promise<void> {
+  const workflow = new OnboardWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.info('No onboarding workflow started.');
+    utils.print.info('Run "bootspring onboard" to begin.');
+    return;
+  }
+
+  workflow.loadState();
+  const progress = workflow.getProgress();
+
+  utils.print.header('Onboarding Status');
+
+  // Overall progress
+  console.log(`Progress: ${progress.overall.percentage}% complete`);
+  console.log(`Started: ${progress.startedAt ? new Date(progress.startedAt).toLocaleString() : 'N/A'}`);
+  console.log(`Last updated: ${progress.lastUpdated ? utils.formatRelativeTime(new Date(progress.lastUpdated)) : 'N/A'}`);
+  console.log('');
+
+  // Phase status
+  console.log('Phases:');
+  for (const phase of progress.phases) {
+    const statusIcon = getStatusIcon(phase.status);
+    const required = phase.required ? '' : ' (optional)';
+    console.log(`  ${statusIcon} ${phase.name}${required}`);
+  }
+
+  console.log('');
+
+  // Detection summary if available
+  if (progress.detection?.stack) {
+    console.log('Detected stack:');
+    console.log(`  ${formatStack(progress.detection.stack)}`);
+  }
+
+  if (!progress.isComplete) {
+    console.log('');
+    utils.print.info('Run "bootspring onboard resume" to continue');
+  }
+}
+
+/**
+ * Run detection only
+ */
+async function onboardDetect(): Promise<void> {
+  const workflow = new OnboardWorkflowEngine(projectRoot);
+  workflow.initializeWorkflow();
+
+  const spinner = utils.createSpinner('Detecting stack...').start();
+
+  try {
+    const result = await workflow.runDetection();
+    spinner.succeed('Detection complete');
+
+    displayDetectionResults(result);
+  } catch (error) {
+    spinner.fail(`Detection failed: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Generate config only
+ */
+async function onboardGenerate(args: ParsedArgs): Promise<void> {
+  const workflow = new OnboardWorkflowEngine(projectRoot);
+
+  // Need detection first
+  if (!workflow.hasWorkflow()) {
+    workflow.initializeWorkflow();
+
+    const spinner = utils.createSpinner('Running detection first...').start();
+    await workflow.runDetection();
+    workflow.completePhase('detection');
+
+    await workflow.runPatternScan();
+    workflow.completePhase('patterns');
+
+    spinner.succeed('Detection complete');
+  } else {
+    workflow.loadState();
+  }
+
+  const spinner = utils.createSpinner('Generating configuration...').start();
+
+  try {
+    const result = await workflow.runConfigGeneration();
+    spinner.succeed('Configuration generated');
+
+    displayConfigResults(result, args['dry-run'] || false);
+
+    if (args.apply) {
+      workflow.applyGeneratedFiles();
+      utils.print.success('Files applied to project root');
+    } else {
+      console.log('');
+      utils.print.info('Files saved to .bootspring/onboard/generated/');
+      utils.print.info('Run with --apply to copy to project root');
+    }
+  } catch (error) {
+    spinner.fail(`Generation failed: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Reset onboard workflow
+ */
+async function onboardReset(): Promise<void> {
+  const workflow = new OnboardWorkflowEngine(projectRoot);
+
+  if (!workflow.hasWorkflow()) {
+    utils.print.info('No workflow to reset.');
+    return;
+  }
+
+  workflow.resetWorkflow();
+  utils.print.success('Onboarding workflow reset.');
+}
+
+/**
+ * Get status icon
+ */
+function getStatusIcon(status: string): string {
+  switch (status) {
+    case 'completed':
+      return `${utils.COLORS.green}✓${utils.COLORS.reset}`;
+    case 'in_progress':
+      return `${utils.COLORS.cyan}●${utils.COLORS.reset}`;
+    case 'failed':
+      return `${utils.COLORS.red}✗${utils.COLORS.reset}`;
+    case 'skipped':
+      return `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+    default:
+      return `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+  }
+}
+
+/**
+ * Main entry point
+ */
+export async function run(args: string[]): Promise<void> {
+  const parsedArgs = utils.parseArgs(args) as ParsedArgs;
+  const subcommand = parsedArgs._[0] || 'start';
+
+  switch (subcommand) {
+    case 'start':
+      return onboardStart(parsedArgs);
+
+    case 'status':
+      return onboardStatus();
+
+    case 'resume':
+      return onboardResume(parsedArgs);
+
+    case 'detect':
+      return onboardDetect();
+
+    case 'generate':
+      return onboardGenerate(parsedArgs);
+
+    case 'reset':
+      return onboardReset();
+
+    case 'help':
+    case '--help':
+    case '-h':
+      return showHelp();
+
+    default:
+      // If no subcommand, start workflow
+      return onboardStart(parsedArgs);
+  }
+}