@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/manager.ts

@@ -0,0 +1,878 @@
+/**
+ * Bootspring Manager Command
+ * Overview of all projects without entering each one
+ *
+ * Commands:
+ *   list [--sort] [--type]   List all projects with health scores (default)
+ *   show <name>              Detailed project view
+ *   export                   Export report as markdown
+ *   scan                     Scan for local projects in workspace
+ *
+ * @package bootspring
+ * @command manager
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// Type interfaces for JS modules
+interface Colors {
+  reset: string;
+  bold: string;
+  dim: string;
+  cyan: string;
+  green: string;
+  yellow: string;
+  red: string;
+  magenta: string;
+}
+
+interface PrintModule {
+  error(msg: string): void;
+  dim(msg: string): void;
+  warning(msg: string): void;
+  success(msg: string): void;
+}
+
+interface Spinner {
+  start(): Spinner;
+  stop(): void;
+  succeed(text: string): void;
+  fail(text: string): void;
+}
+
+interface ParsedArgs {
+  _: string[];
+  sort?: string | undefined;
+  type?: string | undefined;
+  json?: boolean | undefined;
+  output?: string | undefined;
+  dir?: string | undefined;
+}
+
+interface UtilsModule {
+  COLORS: Colors;
+  print: PrintModule;
+  parseArgs(args: string[]): ParsedArgs;
+  createSpinner(text: string): Spinner;
+  formatRelativeTime(date: Date): string;
+}
+
+interface SessionProject {
+  name?: string | undefined;
+  path?: string | undefined;
+}
+
+interface SessionModule {
+  getRecentProjects(): SessionProject[] | null;
+  getCurrentProject(): SessionProject | null;
+}
+
+interface GitHubStats {
+  totalCommits: number;
+  openPRs: number;
+  contributors: number;
+  lastCommitMessage?: string | undefined;
+}
+
+interface GitHubInfo {
+  connected: boolean;
+  owner?: string | undefined;
+  repo?: string | undefined;
+  repositoryUrl?: string | undefined;
+  stats?: GitHubStats | undefined;
+}
+
+interface UsageInfo {
+  currentPeriod: string;
+  contextGenerations: number;
+  agentInvocations: number;
+  skillSearches: number;
+  mcpCalls: number;
+}
+
+interface HealthInfo {
+  score?: number | undefined;
+}
+
+interface ProjectStateData {
+  projectType?: string | undefined;
+  autoTagged?: boolean | undefined;
+  github?: GitHubInfo | undefined;
+  usage?: UsageInfo | undefined;
+  health?: HealthInfo | undefined;
+}
+
+interface ProjectStateModule {
+  loadState(projectRoot: string): ProjectStateData | null;
+  getCheckpointProgress(projectRoot: string): CheckpointProgress;
+}
+
+interface CheckpointProgress {
+  percentage: number;
+  completed: number;
+  total: number;
+}
+
+interface Checkpoint {
+  label: string;
+  completed: boolean;
+}
+
+interface CheckpointStatus {
+  exists: boolean;
+  checkpoints?: Checkpoint[] | undefined;
+}
+
+interface CheckpointEngineModule {
+  getColoredProgressBar(percentage: number, width: number): string;
+  getCheckpointStatus(projectRoot: string): CheckpointStatus;
+}
+
+interface TelemetryModule {
+  emitEvent(event: string, data: Record<string, unknown>): void;
+}
+
+const config = require('../core/config');
+const utils = require('../core/utils') as UtilsModule;
+const session = require('../core/session') as SessionModule;
+const projectState = require('../core/project-state') as ProjectStateModule;
+const checkpointEngine = require('../core/checkpoint-engine') as CheckpointEngineModule;
+const telemetry = require('../core/telemetry') as TelemetryModule;
+
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+interface Project {
+  name?: string | undefined;
+  path?: string | undefined;
+  source?: string | undefined;
+}
+
+interface HealthGrade {
+  grade: string;
+  color: string;
+}
+
+interface EnrichedProject extends Project {
+  exists: boolean;
+  health: number;
+  healthGrade?: HealthGrade | undefined;
+  checkpointProgress: CheckpointProgress;
+  projectType: string | null;
+  autoTagged?: boolean | undefined;
+  github: GitHubInfo | null;
+  usage?: UsageInfo | null | undefined;
+  lastActivity: Date | null;
+  stateExists?: boolean | undefined;
+}
+
+interface WorkspaceFile {
+  projects?: string[] | undefined;
+}
+
+interface ListOptions {
+  sort?: string | null | undefined;
+  type?: string | null | undefined;
+  json?: boolean | undefined;
+}
+
+interface ShowOptions {
+  json?: boolean | undefined;
+}
+
+interface ExportOptions {
+  output?: string | null | undefined;
+}
+
+interface ScanOptions {
+  dir?: string | null | undefined;
+}
+
+interface ScanIndicators {
+  config: boolean;
+  planning: boolean;
+  bootspringDir: boolean;
+  packageJson: boolean;
+}
+
+interface ScannedProject {
+  name: string;
+  path: string;
+  indicators: ScanIndicators;
+}
+
+// ============================================================================
+// Project Discovery
+// ============================================================================
+
+/**
+ * Get all known projects
+ * Combines recent projects from session with workspace projects
+ */
+function getKnownProjects(): Project[] {
+  const projects: Project[] = [];
+  const seenPaths = new Set<string>();
+
+  // Get recent projects from session
+  const recentProjects = session.getRecentProjects() || [];
+  for (const project of recentProjects) {
+    if (project.path && !seenPaths.has(project.path)) {
+      seenPaths.add(project.path);
+      projects.push({
+        ...project,
+        source: 'recent'
+      });
+    }
+  }
+
+  // Get current project
+  const currentProject = session.getCurrentProject();
+  if (currentProject?.path && !seenPaths.has(currentProject.path)) {
+    seenPaths.add(currentProject.path);
+    projects.push({
+      ...currentProject,
+      source: 'current'
+    });
+  }
+
+  // Scan workspace file if exists
+  const workspaceFile = path.join(os.homedir(), '.bootspring', 'workspace.json');
+  if (fs.existsSync(workspaceFile)) {
+    try {
+      const workspace = JSON.parse(fs.readFileSync(workspaceFile, 'utf-8')) as WorkspaceFile;
+      for (const projectPath of workspace.projects || []) {
+        if (!seenPaths.has(projectPath)) {
+          seenPaths.add(projectPath);
+          const projectName = path.basename(projectPath);
+          projects.push({
+            name: projectName,
+            path: projectPath,
+            source: 'workspace'
+          });
+        }
+      }
+    } catch {
+      // Ignore workspace read errors
+    }
+  }
+
+  return projects;
+}
+
+/**
+ * Get detailed info for a project
+ */
+function getProjectDetails(project: Project): EnrichedProject {
+  const projectRoot = project.path;
+
+  if (!projectRoot || !fs.existsSync(projectRoot)) {
+    return {
+      ...project,
+      exists: false,
+      health: 0,
+      checkpointProgress: { percentage: 0, completed: 0, total: 0 },
+      projectType: null,
+      github: null,
+      lastActivity: null
+    };
+  }
+
+  // Load state
+  const state = projectState.loadState(projectRoot);
+
+  // Get checkpoint progress
+  let checkpointProgress: CheckpointProgress = { percentage: 0, completed: 0, total: 0 };
+  if (state) {
+    checkpointProgress = projectState.getCheckpointProgress(projectRoot);
+  }
+
+  // Get last activity from git or file timestamps
+  let lastActivity: Date | null = null;
+  try {
+    const gitHeadPath = path.join(projectRoot, '.git', 'HEAD');
+    if (fs.existsSync(gitHeadPath)) {
+      const stats = fs.statSync(gitHeadPath);
+      lastActivity = stats.mtime;
+    }
+  } catch {
+    // Ignore git errors
+  }
+
+  // Calculate health score
+  let health = 0;
+  if (state?.health?.score) {
+    health = state.health.score;
+  } else if (checkpointProgress.percentage > 0) {
+    // Calculate basic health from checkpoint progress
+    health = Math.round(checkpointProgress.percentage * 0.4); // 40% weight
+    if (state?.github?.connected) health += 20;
+    // Check for quality files
+    if (fs.existsSync(path.join(projectRoot, 'tsconfig.json'))) health += 10;
+    if (fs.existsSync(path.join(projectRoot, '.eslintrc')) ||
+        fs.existsSync(path.join(projectRoot, 'eslint.config.js'))) health += 10;
+    if (fs.existsSync(path.join(projectRoot, '__tests__')) ||
+        fs.existsSync(path.join(projectRoot, 'tests'))) health += 10;
+  }
+
+  return {
+    ...project,
+    exists: true,
+    health,
+    healthGrade: getHealthGrade(health),
+    checkpointProgress,
+    projectType: state?.projectType || 'development',
+    autoTagged: state?.autoTagged || false,
+    github: state?.github || null,
+    usage: state?.usage || null,
+    lastActivity,
+    stateExists: !!state
+  };
+}
+
+/**
+ * Get health grade
+ */
+function getHealthGrade(score: number): HealthGrade {
+  if (score >= 90) return { grade: 'A', color: utils.COLORS.green };
+  if (score >= 80) return { grade: 'B', color: utils.COLORS.green };
+  if (score >= 70) return { grade: 'C', color: utils.COLORS.yellow };
+  if (score >= 60) return { grade: 'D', color: utils.COLORS.yellow };
+  return { grade: 'F', color: utils.COLORS.red };
+}
+
+// ============================================================================
+// Command Handlers
+// ============================================================================
+
+/**
+ * Get type badge
+ */
+function getTypeBadge(projectType: string | null): string {
+  const badges: Record<string, string> = {
+    development: `${utils.COLORS.cyan}[DEV]${utils.COLORS.reset}`,
+    content: `${utils.COLORS.magenta}[CONTENT]${utils.COLORS.reset}`,
+    business: `${utils.COLORS.yellow}[BUSINESS]${utils.COLORS.reset}`
+  };
+  return badges[projectType || 'development'] || badges.development || '';
+}
+
+/**
+ * List all projects
+ */
+function handleList(options: ListOptions = {}): void {
+  const projects = getKnownProjects();
+
+  if (projects.length === 0) {
+    console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project Manager${utils.COLORS.reset}
+
+${utils.COLORS.dim}No projects found.${utils.COLORS.reset}
+
+${utils.COLORS.bold}To add projects:${utils.COLORS.reset}
+  1. Use ${utils.COLORS.cyan}bootspring init${utils.COLORS.reset} in a project directory
+  2. Or add to workspace: ${utils.COLORS.cyan}bootspring workspace add <path>${utils.COLORS.reset}
+`);
+    return;
+  }
+
+  // Enhance with details
+  const enrichedProjects = projects.map(getProjectDetails);
+
+  // Filter by type if specified
+  let filteredProjects = enrichedProjects;
+  if (options.type) {
+    filteredProjects = enrichedProjects.filter(p => p.projectType === options.type);
+  }
+
+  // Sort projects
+  if (options.sort === 'health') {
+    filteredProjects.sort((a, b) => b.health - a.health);
+  } else if (options.sort === 'activity') {
+    filteredProjects.sort((a, b) => {
+      if (!a.lastActivity) return 1;
+      if (!b.lastActivity) return -1;
+      return new Date(b.lastActivity).getTime() - new Date(a.lastActivity).getTime();
+    });
+  } else if (options.sort === 'name') {
+    filteredProjects.sort((a, b) => (a.name || '').localeCompare(b.name || ''));
+  }
+
+  // JSON output
+  if (options.json) {
+    console.log(JSON.stringify(filteredProjects, null, 2));
+    return;
+  }
+
+  // Display
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project Manager${utils.COLORS.reset}
+${utils.COLORS.dim}${filteredProjects.length} project(s)${utils.COLORS.reset}
+`);
+
+  // Get current project for highlighting
+  const currentProject = session.getCurrentProject();
+  const currentPath = currentProject?.path;
+
+  for (const project of filteredProjects) {
+    const isCurrent = project.path === currentPath;
+    const marker = isCurrent ? `${utils.COLORS.green}›${utils.COLORS.reset} ` : '  ';
+
+    // Type badge
+    const typeBadge = getTypeBadge(project.projectType);
+
+    // Health indicator
+    const healthGrade = project.healthGrade || getHealthGrade(0);
+    const healthBadge = `${healthGrade.color}${healthGrade.grade}${utils.COLORS.reset}`;
+
+    // Checkpoint progress
+    const progress = project.checkpointProgress;
+    const progressBar = checkpointEngine.getColoredProgressBar(progress.percentage, 10);
+
+    // Name with current indicator
+    const nameStyle = isCurrent ? utils.COLORS.bold : '';
+    const name = project.name || path.basename(project.path || 'Unknown');
+
+    console.log(`${marker}${nameStyle}${name}${utils.COLORS.reset} ${typeBadge}`);
+    console.log(`    Health: ${healthBadge} ${project.health}/100  Checkpoints: ${progressBar} ${progress.completed}/${progress.total}`);
+
+    // GitHub status
+    if (project.github?.connected) {
+      console.log(`    ${utils.COLORS.dim}GitHub: ${project.github.owner}/${project.github.repo}${utils.COLORS.reset}`);
+    }
+
+    // Last activity
+    if (project.lastActivity) {
+      console.log(`    ${utils.COLORS.dim}Last activity: ${utils.formatRelativeTime(project.lastActivity)}${utils.COLORS.reset}`);
+    }
+
+    console.log();
+  }
+
+  // Summary
+  const totalHealth = filteredProjects.reduce((sum, p) => sum + p.health, 0);
+  const avgHealth = filteredProjects.length > 0 ? Math.round(totalHealth / filteredProjects.length) : 0;
+  const connectedCount = filteredProjects.filter(p => p.github?.connected).length;
+
+  console.log(`${utils.COLORS.bold}Summary:${utils.COLORS.reset}`);
+  console.log(`  Average health: ${avgHealth}/100`);
+  console.log(`  GitHub connected: ${connectedCount}/${filteredProjects.length}`);
+  console.log();
+
+  // Emit telemetry
+  telemetry.emitEvent('manager:list', {
+    projectCount: filteredProjects.length,
+    avgHealth,
+    sortBy: options.sort || 'default'
+  });
+}
+
+/**
+ * Show detailed project view
+ */
+function handleShow(nameOrPath: string | undefined, options: ShowOptions = {}): void {
+  if (!nameOrPath) {
+    utils.print.error('Please specify a project name or path.');
+    console.log(`\n${utils.COLORS.bold}Usage:${utils.COLORS.reset} bootspring manager show <name>`);
+    return;
+  }
+
+  const projects = getKnownProjects();
+
+  // Find project by name or path
+  let project: Project | undefined = projects.find(p =>
+    p.name === nameOrPath ||
+    p.path === nameOrPath ||
+    (p.path && path.basename(p.path) === nameOrPath)
+  );
+
+  // Try as absolute path
+  if (!project && fs.existsSync(nameOrPath)) {
+    project = { path: nameOrPath, name: path.basename(nameOrPath) };
+  }
+
+  if (!project) {
+    utils.print.error(`Project not found: ${nameOrPath}`);
+    console.log(`\n${utils.COLORS.bold}Available projects:${utils.COLORS.reset}`);
+    for (const p of projects) {
+      console.log(`  - ${p.name || path.basename(p.path || '')}`);
+    }
+    return;
+  }
+
+  const details = getProjectDetails(project);
+
+  // JSON output
+  if (options.json) {
+    console.log(JSON.stringify(details, null, 2));
+    return;
+  }
+
+  const name = details.name || path.basename(details.path || '');
+  const typeBadge = getTypeBadge(details.projectType);
+  const healthGrade = details.healthGrade || getHealthGrade(0);
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Project: ${name}${utils.COLORS.reset} ${typeBadge}
+${utils.COLORS.dim}${details.path}${utils.COLORS.reset}
+`);
+
+  // Health score
+  console.log(`${utils.COLORS.bold}Health Score${utils.COLORS.reset}`);
+  console.log(`  ${healthGrade.color}${healthGrade.grade}${utils.COLORS.reset} ${details.health}/100`);
+  console.log();
+
+  // Checkpoint progress
+  const progress = details.checkpointProgress;
+  console.log(`${utils.COLORS.bold}Checkpoint Progress${utils.COLORS.reset}`);
+  console.log(`  ${checkpointEngine.getColoredProgressBar(progress.percentage, 30)} ${progress.percentage}%`);
+  console.log(`  ${progress.completed}/${progress.total} complete`);
+  console.log();
+
+  // If we have full state, show checkpoints
+  if (details.stateExists && details.path) {
+    const checkpointStatus = checkpointEngine.getCheckpointStatus(details.path);
+    if (checkpointStatus.exists && checkpointStatus.checkpoints) {
+      console.log(`${utils.COLORS.bold}Checkpoints:${utils.COLORS.reset}`);
+      for (const cp of checkpointStatus.checkpoints) {
+        const icon = cp.completed
+          ? `${utils.COLORS.green}✓${utils.COLORS.reset}`
+          : `${utils.COLORS.dim}○${utils.COLORS.reset}`;
+        console.log(`  ${icon} ${cp.label}`);
+      }
+      console.log();
+    }
+  }
+
+  // GitHub
+  console.log(`${utils.COLORS.bold}GitHub${utils.COLORS.reset}`);
+  if (details.github?.connected) {
+    console.log(`  ${utils.COLORS.green}✓${utils.COLORS.reset} Connected: ${details.github.owner}/${details.github.repo}`);
+    if (details.github.stats) {
+      console.log(`  Commits: ${details.github.stats.totalCommits}`);
+      console.log(`  Open PRs: ${details.github.stats.openPRs}`);
+      console.log(`  Contributors: ${details.github.stats.contributors}`);
+      if (details.github.stats.lastCommitMessage) {
+        console.log(`  Latest: ${details.github.stats.lastCommitMessage}`);
+      }
+    }
+  } else {
+    console.log(`  ${utils.COLORS.dim}Not connected${utils.COLORS.reset}`);
+  }
+  console.log();
+
+  // Usage
+  if (details.usage) {
+    console.log(`${utils.COLORS.bold}Usage (${details.usage.currentPeriod})${utils.COLORS.reset}`);
+    console.log(`  Context generations: ${details.usage.contextGenerations}`);
+    console.log(`  Agent invocations: ${details.usage.agentInvocations}`);
+    console.log(`  Skill searches: ${details.usage.skillSearches}`);
+    console.log(`  MCP calls: ${details.usage.mcpCalls}`);
+    console.log();
+  }
+
+  // Commands
+  console.log(`${utils.COLORS.bold}Commands:${utils.COLORS.reset}`);
+  console.log(`  bootspring switch "${name}"    Switch to this project`);
+  console.log('  bootspring checkpoint          View checkpoints');
+  console.log('  bootspring github status       View GitHub status');
+  console.log();
+
+  // Emit telemetry
+  telemetry.emitEvent('manager:show', {
+    projectName: name,
+    health: details.health
+  });
+}
+
+/**
+ * Export project report as markdown
+ */
+function handleExport(options: ExportOptions = {}): void {
+  const projects = getKnownProjects().map(getProjectDetails);
+
+  if (projects.length === 0) {
+    utils.print.warning('No projects to export.');
+    return;
+  }
+
+  const date = new Date().toISOString().split('T')[0] || '';
+  const lines: string[] = [];
+
+  lines.push('# Project Manager Report');
+  lines.push('');
+  lines.push(`Generated: ${date}`);
+  lines.push(`Projects: ${projects.length}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // Summary table
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Project | Type | Health | Checkpoints | GitHub |');
+  lines.push('|---------|------|--------|-------------|--------|');
+
+  for (const project of projects) {
+    const name = project.name || path.basename(project.path || 'Unknown');
+    const type = project.projectType || 'development';
+    const health = `${project.healthGrade?.grade || '-'} (${project.health})`;
+    const checkpoints = `${project.checkpointProgress.completed}/${project.checkpointProgress.total}`;
+    const github = project.github?.connected ? `${project.github.owner}/${project.github.repo}` : '-';
+
+    lines.push(`| ${name} | ${type} | ${health} | ${checkpoints} | ${github} |`);
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+
+  // Detailed sections
+  lines.push('## Project Details');
+  lines.push('');
+
+  for (const project of projects) {
+    const name = project.name || path.basename(project.path || 'Unknown');
+
+    lines.push(`### ${name}`);
+    lines.push('');
+    lines.push(`- **Type:** ${project.projectType}`);
+    lines.push(`- **Health:** ${project.health}/100 (${project.healthGrade?.grade || '-'})`);
+    lines.push(`- **Checkpoints:** ${project.checkpointProgress.completed}/${project.checkpointProgress.total} (${project.checkpointProgress.percentage}%)`);
+
+    if (project.github?.connected) {
+      lines.push(`- **GitHub:** [${project.github.owner}/${project.github.repo}](${project.github.repositoryUrl})`);
+      if (project.github.stats?.lastCommitMessage) {
+        lines.push(`- **Latest Commit:** ${project.github.stats.lastCommitMessage}`);
+      }
+    }
+
+    if (project.lastActivity) {
+      lines.push(`- **Last Activity:** ${utils.formatRelativeTime(project.lastActivity)}`);
+    }
+
+    lines.push('');
+  }
+
+  // Statistics
+  lines.push('## Statistics');
+  lines.push('');
+
+  const totalHealth = projects.reduce((sum, p) => sum + p.health, 0);
+  const avgHealth = projects.length > 0 ? Math.round(totalHealth / projects.length) : 0;
+  const connectedCount = projects.filter(p => p.github?.connected).length;
+  const byType: Record<string, number> = {};
+  for (const p of projects) {
+    const type = p.projectType || 'development';
+    byType[type] = (byType[type] || 0) + 1;
+  }
+
+  lines.push(`- **Total Projects:** ${projects.length}`);
+  lines.push(`- **Average Health:** ${avgHealth}/100`);
+  lines.push(`- **GitHub Connected:** ${connectedCount}/${projects.length}`);
+  lines.push('');
+  lines.push('**By Type:**');
+  for (const [type, count] of Object.entries(byType)) {
+    lines.push(`- ${type}: ${count}`);
+  }
+  lines.push('');
+
+  lines.push('---');
+  lines.push('');
+  lines.push('*Generated by Bootspring Project Manager*');
+
+  const content = lines.join('\n');
+
+  // Output to file or console
+  if (options.output) {
+    try {
+      fs.writeFileSync(options.output, content, 'utf-8');
+      utils.print.success(`Report exported to: ${options.output}`);
+    } catch (error) {
+      utils.print.error(`Failed to write file: ${(error as Error).message}`);
+    }
+  } else {
+    const defaultPath = path.join(process.cwd(), `project-report-${date}.md`);
+    fs.writeFileSync(defaultPath, content, 'utf-8');
+    utils.print.success(`Report exported to: ${defaultPath}`);
+  }
+
+  // Emit telemetry
+  telemetry.emitEvent('manager:export', {
+    projectCount: projects.length
+  });
+}
+
+/**
+ * Scan for local projects
+ */
+function handleScan(options: ScanOptions = {}): void {
+  const searchDir = options.dir || process.cwd();
+
+  const spinner = utils.createSpinner(`Scanning ${searchDir} for projects...`);
+  spinner.start();
+
+  const found: ScannedProject[] = [];
+
+  try {
+    // Look for directories with bootspring indicators
+    const entries = fs.readdirSync(searchDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.')) continue;
+      if (entry.name === 'node_modules') continue;
+
+      const dirPath = path.join(searchDir, entry.name);
+
+      // Check for bootspring indicators
+      const hasConfig = fs.existsSync(path.join(dirPath, 'bootspring.config.js'));
+      const hasPlanning = fs.existsSync(path.join(dirPath, 'planning'));
+      const hasBootstrapDir = fs.existsSync(path.join(dirPath, '.bootspring'));
+      const hasPackageJson = fs.existsSync(path.join(dirPath, 'package.json'));
+
+      if (hasConfig || hasPlanning || hasBootstrapDir) {
+        found.push({
+          name: entry.name,
+          path: dirPath,
+          indicators: {
+            config: hasConfig,
+            planning: hasPlanning,
+            bootspringDir: hasBootstrapDir,
+            packageJson: hasPackageJson
+          }
+        });
+      }
+    }
+  } catch (error) {
+    spinner.fail(`Scan failed: ${(error as Error).message}`);
+    return;
+  }
+
+  spinner.succeed(`Found ${found.length} project(s)`);
+
+  if (found.length === 0) {
+    console.log(`\n${utils.COLORS.dim}No Bootspring projects found in ${searchDir}${utils.COLORS.reset}`);
+    return;
+  }
+
+  console.log();
+
+  for (const project of found) {
+    console.log(`  ${utils.COLORS.cyan}●${utils.COLORS.reset} ${project.name}`);
+    console.log(`    ${utils.COLORS.dim}${project.path}${utils.COLORS.reset}`);
+  }
+
+  console.log(`
+${utils.COLORS.bold}To add to workspace:${utils.COLORS.reset}
+  bootspring workspace add <path>
+`);
+}
+
+/**
+ * Show help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Manager${utils.COLORS.reset}
+${utils.COLORS.dim}Overview of all projects${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring manager [command] [options]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  list                 List all projects with health scores (default)
+  show <name>          Detailed project view
+  export               Export report as markdown
+  scan                 Scan for local projects
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --sort=<field>       Sort by: health, activity, name
+  --type=<type>        Filter by type: dev, content, business
+  --json               Output as JSON
+  --output=<file>      Export output file path
+  --dir=<path>         Directory to scan
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring manager                       # List all projects
+  bootspring manager --sort=health         # Sort by health score
+  bootspring manager show my-project       # View project details
+  bootspring manager export                # Generate markdown report
+  bootspring manager scan --dir=~/projects # Find projects
+`);
+}
+
+// ============================================================================
+// Main Runner
+// ============================================================================
+
+/**
+ * Run manager command
+ */
+export async function run(args: string[]): Promise<void> {
+  // Parse arguments
+  const parsed = utils.parseArgs(args);
+  const subcommand = parsed._[0] || 'list';
+  const options = {
+    sort: parsed.sort || null,
+    type: parsed.type || null,
+    json: parsed.json || false,
+    output: parsed.output || null,
+    dir: parsed.dir || null
+  };
+
+  switch (subcommand) {
+    case 'list':
+    case 'ls':
+    case 'l':
+      handleList(options);
+      break;
+
+    case 'show':
+    case 'view':
+    case 's':
+      handleShow(parsed._[1], options);
+      break;
+
+    case 'export':
+    case 'report':
+    case 'e':
+      handleExport(options);
+      break;
+
+    case 'scan':
+    case 'find':
+      handleScan(options);
+      break;
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      // If it looks like a project name, treat as show
+      if (!subcommand.startsWith('-')) {
+        handleShow(subcommand, options);
+      } else {
+        utils.print.error(`Unknown subcommand: ${subcommand}`);
+        showHelp();
+      }
+  }
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export {
+  getKnownProjects,
+  getProjectDetails,
+  handleList,
+  handleShow,
+  handleExport,
+  handleScan
+};