@girardmedia/bootspring 2.0.21 → 2.0.23

package/src/cli/mcp.ts

@@ -0,0 +1,275 @@
+/**
+ * Bootspring MCP Command
+ * Control the MCP server
+ *
+ * @package bootspring
+ * @module cli/mcp
+ */
+
+import * as path from 'path';
+
+// Import JS modules with type interfaces
+interface ConfigModule {
+  load(): {
+    _projectRoot: string;
+    _configPath?: string;
+    project?: { name: string };
+  };
+}
+
+interface ContextModule {
+  get(options: { config: unknown }): {
+    state: { phase: string; health: string };
+  };
+}
+
+interface ContextDetectorModule {
+  detectContext(prompt: string): {
+    matches: Array<unknown>;
+    suggestedAgents: string[];
+  };
+}
+
+interface PromptEnhancerModule {
+  enhance(prompt: string, detection: unknown, options: unknown): {
+    category: string;
+  } | null;
+}
+
+// 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 utils = require('../../core/utils') as typeof import('../core/utils');
+
+/**
+ * Start MCP server (for direct invocation by Claude Code)
+ */
+function startServer(): void {
+  // When called directly by MCP, just require the server module
+  // This allows Claude Code to invoke it via stdio
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  require('../../mcp/server.js');
+}
+
+/**
+ * Show MCP status and configuration info
+ */
+function showStatus(): void {
+  const cfg = config.load();
+
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring MCP Server${utils.COLORS.reset}
+${utils.COLORS.dim}Model Context Protocol integration${utils.COLORS.reset}
+
+${utils.COLORS.bold}Status${utils.COLORS.reset}
+  The MCP server runs on-demand when Claude Code invokes it.
+  It does not run as a persistent background service.
+
+${utils.COLORS.bold}Configuration${utils.COLORS.reset}
+  Project Root: ${cfg._projectRoot}
+  Config File: ${cfg._configPath || 'not found'}
+
+${utils.COLORS.bold}Available Tools${utils.COLORS.reset}
+  ${utils.COLORS.cyan}bootspring_context${utils.COLORS.reset}   - Show/validate project context
+  ${utils.COLORS.cyan}bootspring_agent${utils.COLORS.reset}     - Work with specialized agents
+  ${utils.COLORS.cyan}bootspring_todo${utils.COLORS.reset}      - Manage todo items
+  ${utils.COLORS.cyan}bootspring_skill${utils.COLORS.reset}     - Search code patterns
+  ${utils.COLORS.cyan}bootspring_quality${utils.COLORS.reset}   - Run quality gates
+  ${utils.COLORS.cyan}bootspring_generate${utils.COLORS.reset}  - Regenerate context
+  ${utils.COLORS.cyan}bootspring_plugin${utils.COLORS.reset}    - Manage plugins
+  ${utils.COLORS.cyan}bootspring_dashboard${utils.COLORS.reset} - Dashboard info
+
+${utils.COLORS.bold}Resources${utils.COLORS.reset}
+  ${utils.COLORS.dim}bootspring://context/project${utils.COLORS.reset}  - Project context JSON
+  ${utils.COLORS.dim}bootspring://context/claude.md${utils.COLORS.reset} - Generated AI context
+  ${utils.COLORS.dim}bootspring://context/todo.md${utils.COLORS.reset}   - Todo list
+  ${utils.COLORS.dim}bootspring://agents/list${utils.COLORS.reset}       - Available agents
+
+${utils.COLORS.bold}Setup${utils.COLORS.reset}
+  Ensure .mcp.json exists with:
+  ${utils.COLORS.dim}{
+    "mcpServers": {
+      "bootspring": {
+        "command": "npx",
+        "args": ["bootspring", "mcp"],
+        "env": {}
+      }
+    }
+  }${utils.COLORS.reset}
+
+${utils.COLORS.bold}Test${utils.COLORS.reset}
+  Run: ${utils.COLORS.cyan}bootspring mcp test${utils.COLORS.reset}
+`);
+}
+
+/**
+ * Test MCP tools
+ */
+async function testMcp(): Promise<void> {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring MCP Test${utils.COLORS.reset}
+`);
+
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const context = require('../../core/context') as ContextModule;
+
+  // Test config loading
+  const spinner1 = utils.createSpinner('Testing config loader').start();
+  try {
+    const cfg = config.load();
+    if (cfg.project) {
+      spinner1.succeed(`Config loaded: ${cfg.project.name}`);
+    } else {
+      spinner1.warn('Config loaded but missing project info');
+    }
+  } catch (error) {
+    spinner1.fail(`Config error: ${(error as Error).message}`);
+  }
+
+  // Test context
+  const spinner2 = utils.createSpinner('Testing context detector').start();
+  try {
+    const cfg = config.load();
+    const ctx = context.get({ config: cfg });
+    spinner2.succeed(`Context loaded: phase=${ctx.state.phase}, health=${ctx.state.health}`);
+  } catch (error) {
+    spinner2.fail(`Context error: ${(error as Error).message}`);
+  }
+
+  // Test hooks
+  const spinner3 = utils.createSpinner('Testing context detection hooks').start();
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const detector = require('../../hooks/context-detector') as ContextDetectorModule;
+    const result = detector.detectContext('implement user authentication with Clerk');
+    if (result.matches.length > 0) {
+      spinner3.succeed(`Detection works: found ${result.matches.length} matches (${result.suggestedAgents.join(', ')})`);
+    } else {
+      spinner3.warn('Detection works but found no matches');
+    }
+  } catch (error) {
+    spinner3.fail(`Detection error: ${(error as Error).message}`);
+  }
+
+  // Test prompt enhancer
+  const spinner4 = utils.createSpinner('Testing prompt enhancer').start();
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const detector = require('../../hooks/context-detector') as ContextDetectorModule;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const enhancer = require('../../hooks/prompt-enhancer') as PromptEnhancerModule;
+    const detection = detector.detectContext('create a database schema for users');
+    const enhancement = enhancer.enhance('create a database schema', detection, {});
+    if (enhancement) {
+      spinner4.succeed(`Enhancer works: category=${enhancement.category}`);
+    } else {
+      spinner4.warn('Enhancer works but produced no enhancement');
+    }
+  } catch (error) {
+    spinner4.fail(`Enhancer error: ${(error as Error).message}`);
+  }
+
+  console.log(`
+${utils.COLORS.bold}Summary${utils.COLORS.reset}
+  All core MCP components are functional.
+  The server will work when invoked by Claude Code.
+
+${utils.COLORS.dim}Tip: Use the tools via Claude Code for full integration testing${utils.COLORS.reset}
+`);
+}
+
+/**
+ * Generate .mcp.json configuration
+ */
+function generateConfig(): void {
+  const cfg = config.load();
+  const mcpPath = path.join(cfg._projectRoot, '.mcp.json');
+
+  const mcpConfig = {
+    mcpServers: {
+      bootspring: {
+        command: 'npx',
+        args: ['bootspring', 'mcp'],
+        env: {}
+      }
+    }
+  };
+
+  const spinner = utils.createSpinner('Generating .mcp.json').start();
+
+  if (utils.writeFile(mcpPath, JSON.stringify(mcpConfig, null, 2))) {
+    spinner.succeed(`Created ${mcpPath}`);
+    console.log(`
+${utils.COLORS.dim}Contents:${utils.COLORS.reset}
+${JSON.stringify(mcpConfig, null, 2)}
+`);
+  } else {
+    spinner.fail('Failed to create .mcp.json');
+  }
+}
+
+/**
+ * Show MCP help
+ */
+function showHelp(): void {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring MCP${utils.COLORS.reset}
+${utils.COLORS.dim}Model Context Protocol server control${utils.COLORS.reset}
+
+${utils.COLORS.bold}Usage:${utils.COLORS.reset}
+  bootspring mcp [command]
+
+${utils.COLORS.bold}Commands:${utils.COLORS.reset}
+  ${utils.COLORS.cyan}(default)${utils.COLORS.reset}         Start MCP server (used by Claude Code)
+  ${utils.COLORS.cyan}status${utils.COLORS.reset}            Show MCP configuration and tools
+  ${utils.COLORS.cyan}test${utils.COLORS.reset}              Test MCP components
+  ${utils.COLORS.cyan}config${utils.COLORS.reset}            Generate .mcp.json file
+  ${utils.COLORS.cyan}help${utils.COLORS.reset}              Show this help
+
+${utils.COLORS.bold}Examples:${utils.COLORS.reset}
+  bootspring mcp status    # Check configuration
+  bootspring mcp test      # Test components
+  bootspring mcp config    # Generate .mcp.json
+`);
+}
+
+/**
+ * Run MCP command
+ */
+export async function run(args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  // Default: start the MCP server (for Claude Code invocation)
+  if (!subcommand) {
+    startServer();
+    return;
+  }
+
+  switch (subcommand) {
+    case 'status':
+      showStatus();
+      break;
+
+    case 'test':
+      await testMcp();
+      break;
+
+    case 'config':
+    case 'init':
+    case 'setup':
+      generateConfig();
+      break;
+
+    case 'help':
+    case '-h':
+    case '--help':
+      showHelp();
+      break;
+
+    default:
+      utils.print.error(`Unknown subcommand: ${subcommand}`);
+      showHelp();
+  }
+}
+
+export { startServer, showStatus, testMcp };

package/src/cli/memory.ts

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+/**
+ * Bootspring Memory Command
+ * View and manage git-based project memory
+ *
+ * @package bootspring
+ * @module cli/memory
+ */
+
+import * as fs from 'fs';
+
+// Colors
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m'
+};
+
+// Type definitions for git-memory module
+interface Learning {
+  hash: string;
+  summary: string;
+  date: string;
+  details?: string;
+  categories: string[];
+  file?: string;
+}
+
+interface ExtractResult {
+  learnings: Learning[];
+  total: number;
+  error?: string;
+}
+
+interface CategoryConfig {
+  icon: string;
+  label: string;
+  patterns: RegExp[];
+}
+
+interface RepoStats {
+  totalCommits: number;
+  contributors: number;
+  weeklyPace: number;
+  firstCommit: string | null;
+}
+
+interface GitMemoryModule {
+  isGitRepo(): boolean;
+  extractLearnings(options?: { limit?: number; since?: string }): ExtractResult;
+  groupByCategory(learnings: Learning[]): Record<string, Learning[]>;
+  searchLearnings(learnings: Learning[], query: string): Learning[];
+  getLearningsForFiles(files: string[]): Learning[];
+  toMarkdown(learnings: Learning[], options?: { title?: string; maxPerCategory?: number }): string;
+  getRepoStats(): RepoStats | null;
+  MEMORY_CATEGORIES: Record<string, CategoryConfig>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const gitMemory = require('../../intelligence/git-memory') as GitMemoryModule;
+
+interface MemoryOptions {
+  limit?: number;
+  since?: string;
+}
+
+/**
+ * Display learnings summary
+ */
+function showSummary(options: MemoryOptions = {}): void {
+  const { limit = 30, since = '3 months ago' } = options;
+
+  console.log(`\n${c.cyan}${c.bold}⚡ Project Memory${c.reset}\n`);
+
+  if (!gitMemory.isGitRepo()) {
+    console.log(`${c.red}Not a git repository${c.reset}`);
+    return;
+  }
+
+  const result = gitMemory.extractLearnings({ limit, since });
+
+  if (result.error) {
+    console.log(`${c.red}Error: ${result.error}${c.reset}`);
+    return;
+  }
+
+  if (result.learnings.length === 0) {
+    console.log(`${c.yellow}No significant learnings found in recent commits${c.reset}`);
+    console.log(`${c.dim}Try using more descriptive commit messages${c.reset}`);
+    return;
+  }
+
+  // Group by category
+  const grouped = gitMemory.groupByCategory(result.learnings);
+
+  console.log(`${c.dim}Extracted ${result.learnings.length} learnings from ${result.total} commits${c.reset}\n`);
+
+  for (const [category, items] of Object.entries(grouped)) {
+    const config = gitMemory.MEMORY_CATEGORIES[category] || { icon: '📝', label: category };
+
+    console.log(`${c.bold}${config.icon} ${config.label}${c.reset} (${items.length})`);
+
+    for (const item of items.slice(0, 3)) {
+      console.log(`  ${c.dim}[${item.hash}]${c.reset} ${item.summary}`);
+    }
+
+    if (items.length > 3) {
+      console.log(`  ${c.dim}... and ${items.length - 3} more${c.reset}`);
+    }
+
+    console.log('');
+  }
+}
+
+/**
+ * Search learnings
+ */
+function searchMemory(query: string): void {
+  console.log(`\n${c.cyan}${c.bold}⚡ Search Memory${c.reset}\n`);
+
+  if (!query) {
+    console.log(`${c.red}Usage: bootspring memory search <query>${c.reset}`);
+    return;
+  }
+
+  const result = gitMemory.extractLearnings({ limit: 100 });
+  const matches = gitMemory.searchLearnings(result.learnings, query);
+
+  console.log(`${c.dim}Found ${matches.length} matches for "${query}"${c.reset}\n`);
+
+  for (const match of matches.slice(0, 15)) {
+    const icons = match.categories
+      .map(cat => gitMemory.MEMORY_CATEGORIES[cat]?.icon || '📝')
+      .join('');
+
+    console.log(`${icons} ${c.bold}${match.summary}${c.reset}`);
+    console.log(`  ${c.dim}[${match.hash}] ${match.date}${c.reset}`);
+
+    if (match.details) {
+      const firstLine = match.details.split('\n')[0];
+      if (firstLine) {
+        const preview = firstLine.slice(0, 80);
+        console.log(`  ${c.dim}${preview}${c.reset}`);
+      }
+    }
+
+    console.log('');
+  }
+
+  if (matches.length > 15) {
+    console.log(`${c.dim}... and ${matches.length - 15} more matches${c.reset}`);
+  }
+}
+
+/**
+ * Show learnings for specific files
+ */
+function showForFiles(files: string[]): void {
+  console.log(`\n${c.cyan}${c.bold}⚡ File Memory${c.reset}\n`);
+
+  if (!files || files.length === 0) {
+    console.log(`${c.red}Usage: bootspring memory files <file1> [file2...]${c.reset}`);
+    return;
+  }
+
+  const learnings = gitMemory.getLearningsForFiles(files);
+
+  if (learnings.length === 0) {
+    console.log(`${c.yellow}No learnings found for these files${c.reset}`);
+    return;
+  }
+
+  console.log(`${c.dim}Learnings related to: ${files.join(', ')}${c.reset}\n`);
+
+  for (const learning of learnings) {
+    const icons = learning.categories
+      .map(cat => gitMemory.MEMORY_CATEGORIES[cat]?.icon || '📝')
+      .join('');
+
+    console.log(`${icons} ${c.bold}${learning.summary}${c.reset}`);
+    console.log(`  ${c.dim}[${learning.hash}] File: ${learning.file}${c.reset}`);
+    console.log('');
+  }
+}
+
+/**
+ * Export learnings to markdown
+ */
+function exportMarkdown(outputPath?: string): void {
+  const result = gitMemory.extractLearnings({ limit: 50 });
+
+  if (result.error) {
+    console.log(`${c.red}Error: ${result.error}${c.reset}`);
+    return;
+  }
+
+  const markdown = gitMemory.toMarkdown(result.learnings, {
+    title: 'Project Learnings',
+    maxPerCategory: 10
+  });
+
+  if (outputPath) {
+    fs.writeFileSync(outputPath, markdown);
+    console.log(`${c.green}Exported to ${outputPath}${c.reset}`);
+  } else {
+    console.log(markdown);
+  }
+}
+
+/**
+ * Show repo stats
+ */
+function showStats(): void {
+  console.log(`\n${c.cyan}${c.bold}⚡ Repository Stats${c.reset}\n`);
+
+  const stats = gitMemory.getRepoStats();
+
+  if (!stats) {
+    console.log(`${c.red}Not a git repository${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.bold}Total Commits:${c.reset}      ${stats.totalCommits}`);
+  console.log(`  ${c.bold}Contributors:${c.reset}       ${stats.contributors}`);
+  console.log(`  ${c.bold}Weekly Activity:${c.reset}    ${stats.weeklyPace} commits`);
+  console.log(`  ${c.bold}First Commit:${c.reset}       ${stats.firstCommit || 'unknown'}`);
+  console.log('');
+
+  // Show category breakdown
+  const result = gitMemory.extractLearnings({ limit: 100 });
+  const grouped = gitMemory.groupByCategory(result.learnings);
+
+  console.log(`${c.bold}Learning Categories:${c.reset}\n`);
+
+  for (const [category, items] of Object.entries(grouped).sort((a, b) => b[1].length - a[1].length)) {
+    const config = gitMemory.MEMORY_CATEGORIES[category] || { icon: '📝', label: category };
+    const bar = '█'.repeat(Math.min(items.length, 20));
+    console.log(`  ${config.icon} ${config.label.padEnd(20)} ${c.cyan}${bar}${c.reset} ${items.length}`);
+  }
+
+  console.log('');
+}
+
+/**
+ * Show help
+ */
+function showHelp(): void {
+  console.log(`
+${c.bold}Bootspring Memory${c.reset}
+
+Extract and search project learnings from git history.
+
+${c.cyan}Usage:${c.reset}
+  bootspring memory <command> [options]
+
+${c.cyan}Commands:${c.reset}
+  summary              Show categorized learning summary (default)
+  search <query>       Search learnings by keyword
+  files <file...>      Show learnings for specific files
+  export [path]        Export learnings to markdown
+  stats                Show repository statistics
+  categories           List memory categories
+  help                 Show this help
+
+${c.cyan}Options:${c.reset}
+  --limit <n>          Number of commits to analyze (default: 30)
+  --since <date>       How far back to look (default: "3 months ago")
+
+${c.cyan}Examples:${c.reset}
+  bootspring memory summary
+  bootspring memory search "authentication"
+  bootspring memory files src/api/auth.ts
+  bootspring memory export LEARNINGS.md
+  bootspring memory stats
+
+${c.cyan}Categories:${c.reset}
+${Object.entries(gitMemory.MEMORY_CATEGORIES)
+    .map(([key, cfg]) => `  ${cfg.icon} ${key.padEnd(15)} ${cfg.label}`)
+    .join('\n')}
+`);
+}
+
+/**
+ * Main CLI handler
+ */
+export async function run(args: string[]): Promise<void> {
+  const command = args[0] || 'summary';
+
+  // Parse options
+  const options: MemoryOptions = {};
+  for (let i = 0; i < args.length; i++) {
+    const nextArg = args[i + 1];
+    if (args[i] === '--limit' && nextArg) {
+      options.limit = parseInt(nextArg, 10);
+    }
+    if (args[i] === '--since' && nextArg) {
+      options.since = nextArg;
+    }
+  }
+
+  switch (command) {
+    case 'summary':
+    case 'show':
+      showSummary(options);
+      break;
+
+    case 'search':
+      searchMemory(args.slice(1).filter(a => !a.startsWith('--')).join(' '));
+      break;
+
+    case 'files':
+    case 'file':
+      showForFiles(args.slice(1).filter(a => !a.startsWith('--')));
+      break;
+
+    case 'export':
+      exportMarkdown(args[1]);
+      break;
+
+    case 'stats':
+      showStats();
+      break;
+
+    case 'categories':
+      console.log(`\n${c.bold}Memory Categories:${c.reset}\n`);
+      for (const [key, cfg] of Object.entries(gitMemory.MEMORY_CATEGORIES)) {
+        console.log(`  ${cfg.icon} ${key.padEnd(15)} ${c.dim}${cfg.label}${c.reset}`);
+        console.log(`     ${c.dim}Patterns: ${cfg.patterns.slice(0, 3).map(p => p.source).join(', ')}...${c.reset}`);
+      }
+      console.log('');
+      break;
+
+    case 'help':
+    case '--help':
+    case '-h':
+    default:
+      showHelp();
+  }
+}