@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/context.ts

@@ -0,0 +1,667 @@
+/**
+ * Bootspring Context Command
+ * View, search, and manage project context files
+ *
+ * Commands:
+ *   show              Show context summary (default)
+ *   validate          Validate project setup
+ *   refresh           Regenerate context files
+ *   list              List all context files
+ *   read <type>       Read a context file
+ *   search <query>    Search across context files
+ *   agent <name>      Show context for an agent
+ *   index             Rebuild context index
+ *   types             Show available context types
+ *   agents            Show agent to context mapping
+ *
+ * @package bootspring
+ * @module cli/context
+ */
+
+// Import JS modules with type interfaces
+interface Config {
+  _projectRoot: string;
+}
+
+interface ConfigModule {
+  load(): Config;
+}
+
+interface ContextProject {
+  name: string;
+  version: string;
+  description?: string;
+}
+
+interface ContextStack {
+  framework: string;
+  language: string;
+  database: string;
+  hosting: string;
+}
+
+interface ContextPlugin {
+  provider: string;
+}
+
+interface ContextState {
+  phase: string;
+  health: string;
+  todos: number;
+  lastGenerated?: string;
+}
+
+interface ContextGit {
+  initialized: boolean;
+  branch?: string;
+  hasRemote: boolean;
+}
+
+interface Context {
+  project: ContextProject;
+  stack: ContextStack;
+  plugins: Record<string, ContextPlugin>;
+  state: ContextState;
+  git: ContextGit;
+}
+
+interface ValidationCheck {
+  status: 'pass' | 'fail' | 'warn' | 'info';
+  name: string;
+  message: string;
+}
+
+interface ValidationResult {
+  checks: ValidationCheck[];
+  percentage: number;
+  score: number;
+  maxScore: number;
+  valid: boolean;
+}
+
+interface ContextModule {
+  get(options: { config: Config }): Context;
+  validate(options: { config: Config }): ValidationResult;
+}
+
+interface ContextFile {
+  type: string;
+  exists: boolean;
+  path: string;
+  isDirectory?: boolean;
+  fileCount?: number;
+  size?: number;
+  modifiedRelative?: string;
+  content?: string;
+  metadata?: {
+    size: number;
+    modifiedRelative: string;
+  };
+  files?: Array<{ path: string; size: number }>;
+}
+
+interface SearchMatch {
+  line: number;
+  preview: string;
+}
+
+interface SearchResult {
+  type: string;
+  file: string;
+  matches?: SearchMatch[];
+  matchType?: string;
+}
+
+interface AgentContext {
+  files: Array<ContextFile & { files?: Array<{ path: string }> }>;
+  summary: string[];
+}
+
+interface ContextIndex {
+  files: unknown[];
+  agents: Record<string, unknown>;
+  lastUpdated: string;
+}
+
+interface ContextLoaderModule {
+  list(options: { config: Config }): ContextFile[];
+  load(type: string): ContextFile & { error?: string };
+  search(query: string, options: { limit?: number }): SearchResult[];
+  getAgentContext(agentName: string): AgentContext;
+  getAgentMap(): Record<string, string[]>;
+  buildIndex(): ContextIndex;
+  getLocations(): Record<string, string>;
+}
+
+interface GenerateModule {
+  run(args: string[]): void;
+}
+
+interface ParsedArgs {
+  _: string[];
+  all?: boolean;
+  limit?: string;
+  metadata?: boolean;
+  full?: boolean;
+  agent?: string;
+  preview?: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const config = require('../../core/config') as ConfigModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const context = require('../../core/context') as ContextModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const contextLoader = require('../../core/context-loader') as ContextLoaderModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const utils = require('../../core/utils') as typeof import('../core/utils');
+
+/**
+ * Show project context summary
+ */
+export function showContext(): void {
+  const cfg = config.load();
+  const ctx = context.get({ config: cfg });
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Context${utils.COLORS.reset}
+${utils.COLORS.dim}Project: ${cfg._projectRoot}${utils.COLORS.reset}
+`);
+
+  // Project Info
+  console.log(`${utils.COLORS.bold}Project${utils.COLORS.reset}`);
+  console.log(`  Name: ${ctx.project.name}`);
+  console.log(`  Version: ${ctx.project.version}`);
+  if (ctx.project.description) {
+    console.log(`  Description: ${ctx.project.description}`);
+  }
+  console.log();
+
+  // Stack
+  console.log(`${utils.COLORS.bold}Stack${utils.COLORS.reset}`);
+  console.log(`  Framework: ${utils.COLORS.cyan}${ctx.stack.framework}${utils.COLORS.reset}`);
+  console.log(`  Language: ${ctx.stack.language}`);
+  console.log(`  Database: ${ctx.stack.database}`);
+  console.log(`  Hosting: ${ctx.stack.hosting}`);
+  console.log();
+
+  // Plugins
+  const plugins = Object.keys(ctx.plugins);
+  if (plugins.length > 0) {
+    console.log(`${utils.COLORS.bold}Enabled Plugins${utils.COLORS.reset}`);
+    for (const [name, plugin] of Object.entries(ctx.plugins)) {
+      console.log(`  ${utils.COLORS.green}●${utils.COLORS.reset} ${name} (${plugin.provider})`);
+    }
+    console.log();
+  }
+
+  // State
+  const healthColor = ctx.state.health === 'good' ? utils.COLORS.green :
+    ctx.state.health === 'fair' ? utils.COLORS.yellow :
+      utils.COLORS.red;
+
+  console.log(`${utils.COLORS.bold}State${utils.COLORS.reset}`);
+  console.log(`  Phase: ${ctx.state.phase}`);
+  console.log(`  Health: ${healthColor}${ctx.state.health}${utils.COLORS.reset}`);
+  console.log(`  Open Todos: ${ctx.state.todos}`);
+  if (ctx.state.lastGenerated) {
+    console.log(`  Context Updated: ${utils.formatRelativeTime(new Date(ctx.state.lastGenerated))}`);
+  }
+  console.log();
+
+  // Git
+  if (ctx.git.initialized) {
+    console.log(`${utils.COLORS.bold}Git${utils.COLORS.reset}`);
+    console.log(`  Branch: ${ctx.git.branch || 'unknown'}`);
+    console.log(`  Remote: ${ctx.git.hasRemote ? 'configured' : 'not configured'}`);
+    console.log();
+  }
+}
+
+/**
+ * Validate project context
+ */
+export function validateContext(): void {
+  const cfg = config.load();
+  const validation = context.validate({ config: cfg });
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Context Validation${utils.COLORS.reset}
+`);
+
+  for (const check of validation.checks) {
+    const icon = check.status === 'pass' ? utils.COLORS.green + '✓' :
+      check.status === 'fail' ? utils.COLORS.red + '✗' :
+        check.status === 'warn' ? utils.COLORS.yellow + '⚠' :
+          utils.COLORS.dim + 'ℹ';
+    console.log(`  ${icon}${utils.COLORS.reset} ${check.name}`);
+    console.log(`    ${utils.COLORS.dim}${check.message}${utils.COLORS.reset}`);
+  }
+
+  console.log();
+
+  // Score bar
+  const barWidth = 30;
+  const filled = Math.round((validation.percentage / 100) * barWidth);
+  const empty = barWidth - filled;
+  const scoreColor = validation.percentage >= 80 ? utils.COLORS.green :
+    validation.percentage >= 50 ? utils.COLORS.yellow :
+      utils.COLORS.red;
+
+  console.log(`${utils.COLORS.bold}Score${utils.COLORS.reset}`);
+  console.log(`  ${scoreColor}${'█'.repeat(filled)}${utils.COLORS.dim}${'░'.repeat(empty)}${utils.COLORS.reset} ${validation.percentage}%`);
+  console.log(`  ${validation.score}/${validation.maxScore} checks passed`);
+  console.log();
+
+  if (validation.valid) {
+    utils.print.success('Context validation passed');
+  } else {
+    utils.print.warning('Context needs attention - fix the issues above');
+    utils.print.dim('Run "bootspring generate" to regenerate context');
+  }
+}
+
+/**
+ * Refresh project context
+ */
+export function refreshContext(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Context Refresh${utils.COLORS.reset}
+`);
+
+  utils.print.info('Refreshing context...');
+
+  // This triggers a regeneration
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const generateModule = require('./generate') as GenerateModule;
+  generateModule.run([]);
+}
+
+/**
+ * List all context files
+ */
+export function listContext(args: string[]): void {
+  const parsedArgs = utils.parseArgs(args) as ParsedArgs;
+  utils.print.header('Project Context Files');
+
+  const cfg = config.load();
+  const contextList = contextLoader.list({ config: cfg });
+
+  // Group by category
+  const categories: Record<string, string[]> = {
+    'Root Files': ['seed', 'claude', 'todo', 'readme', 'changelog'],
+    'Planning': ['plan', 'prd', 'architecture', 'decisions', 'roadmap'],
+    'Business': ['business_plan', 'pitch_deck', 'competitive', 'market', 'financial'],
+    'Legal': ['terms', 'privacy', 'legal_checklist'],
+    'Code Context': ['mvp_source', 'mvp_references'],
+    'System': ['logs', 'context_index']
+  };
+
+  for (const [category, types] of Object.entries(categories)) {
+    const categoryItems = contextList.filter(c => types.includes(c.type));
+    const existingCount = categoryItems.filter(c => c.exists).length;
+
+    if (existingCount > 0 || parsedArgs.all) {
+      console.log(`\n${utils.COLORS.bold}${category}${utils.COLORS.reset}`);
+
+      for (const item of categoryItems) {
+        if (item.exists) {
+          const icon = item.isDirectory ? '📁' : '📄';
+          const size = item.isDirectory
+            ? `${item.fileCount} files`
+            : formatSize(item.size || 0);
+          const modified = item.modifiedRelative || '';
+
+          console.log(`  ${utils.COLORS.green}${icon}${utils.COLORS.reset} ${item.type.padEnd(20)} ${item.path}`);
+          console.log(`     ${utils.COLORS.dim}${size}${modified ? ` • ${modified}` : ''}${utils.COLORS.reset}`);
+        } else if (parsedArgs.all) {
+          console.log(`  ${utils.COLORS.dim}○ ${item.type.padEnd(20)} ${item.path} (not found)${utils.COLORS.reset}`);
+        }
+      }
+    }
+  }
+
+  // Summary
+  const total = contextList.length;
+  const existing = contextList.filter(c => c.exists).length;
+  console.log(`\n${utils.COLORS.dim}Found ${existing}/${total} context files${utils.COLORS.reset}`);
+
+  if (!parsedArgs.all) {
+    utils.print.dim('Use --all to show missing files');
+  }
+}
+
+/**
+ * Read a specific context file
+ */
+export function readContext(args: string[]): void {
+  const parsedArgs = utils.parseArgs(args) as ParsedArgs;
+  const contextType = parsedArgs._[0];
+
+  if (!contextType) {
+    utils.print.error('Please specify a context type');
+    utils.print.dim('Example: bootspring context read seed');
+    utils.print.dim('Run "bootspring context types" to see available types');
+    return;
+  }
+
+  const loaded = contextLoader.load(contextType);
+
+  if (!loaded.exists) {
+    if (loaded.error) {
+      utils.print.error(loaded.error);
+    } else {
+      utils.print.warning(`Context "${contextType}" not found at: ${loaded.path}`);
+    }
+    return;
+  }
+
+  utils.print.header(`Context: ${contextType}`);
+  console.log(`${utils.COLORS.dim}Path: ${loaded.path}${utils.COLORS.reset}\n`);
+
+  if (loaded.files) {
+    // Directory listing
+    console.log(`${utils.COLORS.bold}Files (${loaded.fileCount}):${utils.COLORS.reset}\n`);
+
+    const limit = parsedArgs.limit ? parseInt(parsedArgs.limit, 10) : 20;
+    const files = loaded.files.slice(0, limit);
+
+    for (const file of files) {
+      console.log(`  ${file.path} ${utils.COLORS.dim}(${formatSize(file.size)})${utils.COLORS.reset}`);
+    }
+
+    if (loaded.fileCount && loaded.fileCount > limit) {
+      utils.print.dim(`\n... and ${loaded.fileCount - limit} more files`);
+    }
+  } else {
+    // File content
+    if (parsedArgs.metadata && loaded.metadata) {
+      console.log(`${utils.COLORS.bold}Metadata:${utils.COLORS.reset}`);
+      console.log(`  Size: ${formatSize(loaded.metadata.size)}`);
+      console.log(`  Modified: ${loaded.metadata.modifiedRelative}`);
+      console.log('');
+    }
+
+    // Print content (truncate if very long unless --full is passed)
+    const content = loaded.content || '';
+    const maxLines = parsedArgs.full ? Infinity : 100;
+    const lines = content.split('\n');
+
+    if (lines.length > maxLines) {
+      console.log(lines.slice(0, maxLines).join('\n'));
+      utils.print.dim(`\n... truncated (${lines.length - maxLines} more lines)`);
+      utils.print.dim('Use --full to see entire file');
+    } else {
+      console.log(content);
+    }
+  }
+}
+
+/**
+ * Search across context files
+ */
+export function searchContext(args: string[]): void {
+  const parsedArgs = utils.parseArgs(args) as ParsedArgs;
+  const query = parsedArgs._[0];
+
+  if (!query) {
+    utils.print.error('Please specify a search query');
+    utils.print.dim('Example: bootspring context search "authentication"');
+    return;
+  }
+
+  utils.print.header(`Searching for: ${query}`);
+
+  const limit = parsedArgs.limit ? parseInt(parsedArgs.limit, 10) : 20;
+  const results = contextLoader.search(query, { limit });
+
+  if (results.length === 0) {
+    utils.print.warning('No results found');
+    return;
+  }
+
+  console.log(`${utils.COLORS.dim}Found ${results.length} result(s)${utils.COLORS.reset}\n`);
+
+  for (const result of results) {
+    console.log(`${utils.COLORS.bold}${result.type}${utils.COLORS.reset}: ${result.file}`);
+
+    if (result.matches) {
+      for (const match of result.matches) {
+        console.log(`  ${utils.COLORS.dim}L${match.line}:${utils.COLORS.reset} ${highlightMatch(match.preview, query)}`);
+      }
+    } else if (result.matchType === 'filename') {
+      console.log(`  ${utils.COLORS.dim}(filename match)${utils.COLORS.reset}`);
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Show context for a specific agent
+ */
+export function showAgentContext(args: string[]): void {
+  const parsedArgs = utils.parseArgs(args) as ParsedArgs;
+  const agentName = parsedArgs.agent || parsedArgs._[0];
+
+  if (!agentName) {
+    utils.print.error('Please specify an agent name');
+    utils.print.dim('Example: bootspring context agent frontend-expert');
+    utils.print.dim('Run "bootspring context agents" to see agent mappings');
+    return;
+  }
+
+  const agentContext = contextLoader.getAgentContext(agentName);
+
+  if (agentContext.files.length === 0) {
+    utils.print.warning(`No context available for agent: ${agentName}`);
+
+    const agentMap = contextLoader.getAgentMap();
+    if (!agentMap[agentName]) {
+      utils.print.dim('This agent is not in the context mapping.');
+    } else {
+      utils.print.dim('The mapped context files do not exist yet.');
+    }
+    return;
+  }
+
+  utils.print.header(`Context for: ${agentName}`);
+  console.log(`${utils.COLORS.dim}${agentContext.summary.join(' | ')}${utils.COLORS.reset}\n`);
+
+  for (const file of agentContext.files) {
+    if (file.isDirectory) {
+      console.log(`${utils.COLORS.bold}📁 ${file.type}${utils.COLORS.reset} (${file.fileCount} files)`);
+      if (file.files && file.files.length > 0) {
+        for (const f of file.files.slice(0, 5)) {
+          console.log(`   ${utils.COLORS.dim}${f.path}${utils.COLORS.reset}`);
+        }
+        if (file.fileCount && file.fileCount > 5) {
+          console.log(`   ${utils.COLORS.dim}... and ${file.fileCount - 5} more${utils.COLORS.reset}`);
+        }
+      }
+    } else {
+      console.log(`${utils.COLORS.bold}📄 ${file.type}${utils.COLORS.reset}: ${file.path}`);
+      if (file.metadata) {
+        console.log(`   ${utils.COLORS.dim}${formatSize(file.metadata.size)} • ${file.metadata.modifiedRelative}${utils.COLORS.reset}`);
+      }
+
+      // Show preview
+      if (parsedArgs.preview && file.content) {
+        const preview = file.content.split('\n').slice(0, 5).join('\n');
+        console.log(`   ${utils.COLORS.dim}---${utils.COLORS.reset}`);
+        console.log(`   ${preview.split('\n').map(l => utils.COLORS.dim + l + utils.COLORS.reset).join('\n   ')}`);
+      }
+    }
+    console.log('');
+  }
+}
+
+/**
+ * Build/rebuild context index
+ */
+export function buildIndex(): void {
+  const spinner = utils.createSpinner('Building context index...').start();
+
+  try {
+    const index = contextLoader.buildIndex();
+
+    spinner.succeed('Context index built');
+
+    console.log(`\n${utils.COLORS.bold}Index Summary:${utils.COLORS.reset}`);
+    console.log(`  Files indexed: ${index.files.length}`);
+    console.log(`  Agents mapped: ${Object.keys(index.agents).length}`);
+    console.log(`  Last updated: ${index.lastUpdated}`);
+  } catch (error) {
+    spinner.fail(`Failed to build index: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * Show available context types
+ */
+export function showTypes(): void {
+  utils.print.header('Available Context Types');
+
+  const locations = contextLoader.getLocations();
+
+  const headers = ['Type', 'Path'];
+  const rows = Object.entries(locations).map(([type, path]) => [type, path]);
+
+  console.log(utils.createTable(headers, rows));
+}
+
+/**
+ * Show agent to context mapping
+ */
+export function showAgentMap(): void {
+  utils.print.header('Agent Context Mapping');
+
+  const agentMap = contextLoader.getAgentMap();
+
+  for (const [agent, types] of Object.entries(agentMap)) {
+    console.log(`${utils.COLORS.bold}${agent}${utils.COLORS.reset}`);
+    console.log(`  ${utils.COLORS.dim}${types.join(', ')}${utils.COLORS.reset}`);
+  }
+}
+
+/**
+ * Format file size
+ */
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+/**
+ * Highlight search match in text
+ */
+function highlightMatch(text: string, query: string): string {
+  const regex = new RegExp(`(${query})`, 'gi');
+  return text.replace(regex, `${utils.COLORS.yellow}$1${utils.COLORS.reset}`);
+}
+
+/**
+ * Show context help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring Context${utils.COLORS.reset}
+${utils.COLORS.dim}View, search, and manage project context${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring context <command> [options]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}show${utils.COLORS.reset}              Show context summary (default)
+  ${utils.COLORS.cyan}validate${utils.COLORS.reset}          Validate project setup
+  ${utils.COLORS.cyan}refresh${utils.COLORS.reset}           Regenerate context files
+  ${utils.COLORS.cyan}list${utils.COLORS.reset}              List all context files
+  ${utils.COLORS.cyan}read <type>${utils.COLORS.reset}       Read a context file
+  ${utils.COLORS.cyan}search <query>${utils.COLORS.reset}    Search across context files
+  ${utils.COLORS.cyan}agent <name>${utils.COLORS.reset}      Show context for an agent
+  ${utils.COLORS.cyan}index${utils.COLORS.reset}             Rebuild context index
+  ${utils.COLORS.cyan}types${utils.COLORS.reset}             Show available context types
+  ${utils.COLORS.cyan}agents${utils.COLORS.reset}            Show agent to context mapping
+
+${utils.COLORS.bold}Options:${utils.COLORS.reset}
+  --all               Show all files (including missing)
+  --full              Show full file content (no truncation)
+  --preview           Show content preview
+  --limit=<n>         Limit results
+  --metadata          Show file metadata
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring context
+  bootspring context list --all
+  bootspring context read seed
+  bootspring context search "authentication"
+  bootspring context agent frontend-expert
+`);
+}
+
+/**
+ * Run context command
+ */
+export async function run(args: string[]): Promise<void> {
+  const subcommand = args[0] || 'show';
+  const subArgs = args.slice(1);
+
+  switch (subcommand) {
+    case 'show':
+      showContext();
+      break;
+
+    case 'validate':
+    case 'check':
+      validateContext();
+      break;
+
+    case 'refresh':
+    case 'regenerate':
+      refreshContext();
+      break;
+
+    case 'list':
+    case 'ls':
+      listContext(subArgs);
+      break;
+
+    case 'read':
+    case 'cat':
+    case 'get':
+      readContext(subArgs);
+      break;
+
+    case 'search':
+    case 'find':
+      searchContext(subArgs);
+      break;
+
+    case 'agent':
+      showAgentContext(subArgs);
+      break;
+
+    case 'index':
+    case 'reindex':
+      buildIndex();
+      break;
+
+    case 'types':
+      showTypes();
+      break;
+
+    case 'agents':
+      showAgentMap();
+      break;
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      utils.print.error(`Unknown subcommand: ${subcommand}`);
+      showHelp();
+  }
+}