@girardmedia/bootspring 1.1.0

package/cli/loop.js

@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+
+/**
+ * Bootspring Loop CLI
+ *
+ * Autonomous task execution loop - spawns fresh AI instances
+ * iteratively until all PRD stories are complete.
+ *
+ * @package bootspring
+ * @module cli/loop
+ */
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const prd = require('../intelligence/prd');
+
+// 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'
+};
+
+/**
+ * Check if a tool is available
+ */
+function toolAvailable(tool) {
+  try {
+    execSync(`which ${tool}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect available AI tool
+ */
+function detectTool() {
+  if (toolAvailable('claude')) return 'claude';
+  if (toolAvailable('amp')) return 'amp';
+  return null;
+}
+
+/**
+ * Run the loop via shell script
+ */
+function runLoop(options = {}) {
+  const scriptPath = path.join(__dirname, '..', 'scripts', 'loop.sh');
+
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`${c.red}Loop script not found: ${scriptPath}${c.reset}`);
+    process.exit(1);
+  }
+
+  const args = [
+    options.iterations || '10',
+    '--tool', options.tool || 'claude'
+  ];
+
+  if (options.prd) {
+    args.push('--prd', options.prd);
+  }
+
+  console.log(`${c.cyan}Starting autonomous loop...${c.reset}`);
+  console.log(`${c.dim}Tool: ${options.tool || 'claude'} | Iterations: ${options.iterations || 10}${c.reset}\n`);
+
+  const child = spawn('bash', [scriptPath, ...args], {
+    stdio: 'inherit',
+    cwd: process.cwd()
+  });
+
+  child.on('close', (code) => {
+    process.exit(code);
+  });
+}
+
+/**
+ * Create a new PRD from template or markdown
+ */
+function createPRD(name, options = {}) {
+  const prdDir = prd.DEFAULT_PRD_DIR;
+
+  if (!fs.existsSync(prdDir)) {
+    fs.mkdirSync(prdDir, { recursive: true });
+  }
+
+  // Check if markdown file provided
+  if (options.from && fs.existsSync(options.from)) {
+    const markdown = fs.readFileSync(options.from, 'utf-8');
+    const parsed = prd.parseMarkdownPRD(markdown);
+    parsed.name = name || parsed.name;
+
+    const outPath = prd.savePRD(parsed);
+    console.log(`${c.green}Created PRD from markdown: ${outPath}${c.reset}`);
+    console.log(`Stories: ${parsed.stories.length}`);
+    return;
+  }
+
+  // Interactive template
+  const template = prd.createPRD(
+    name || 'new-feature',
+    'Describe your feature here',
+    [
+      {
+        title: 'Setup and configuration',
+        description: 'Initial setup required for the feature',
+        acceptance: ['Configuration file created', 'Dependencies installed']
+      },
+      {
+        title: 'Core implementation',
+        description: 'Main functionality implementation',
+        acceptance: ['Feature works as specified', 'Tests pass']
+      },
+      {
+        title: 'Documentation and cleanup',
+        description: 'Final polish and documentation',
+        acceptance: ['README updated', 'No lint errors']
+      }
+    ]
+  );
+
+  const outPath = prd.savePRD(template);
+  console.log(`${c.green}Created PRD template: ${outPath}${c.reset}`);
+  console.log(`${c.dim}Edit the file to define your stories, then run: bootspring loop start${c.reset}`);
+}
+
+/**
+ * Show PRD status
+ */
+function showStatus(prdPath) {
+  const filePath = prdPath || path.join(prd.DEFAULT_PRD_DIR, prd.DEFAULT_PRD_FILE);
+  const data = prd.loadPRD(filePath);
+
+  if (!data) {
+    console.log(`${c.yellow}No PRD found at ${filePath}${c.reset}`);
+    console.log(`Create one with: bootspring loop prd <name>`);
+    return;
+  }
+
+  const progress = prd.getProgress(data);
+
+  console.log(`\n${c.cyan}+--------------------------------------------------------+${c.reset}`);
+  console.log(`${c.cyan}|${c.reset}${c.bold}  PRD: ${data.name.padEnd(47)}${c.reset}${c.cyan}|${c.reset}`);
+  console.log(`${c.cyan}+--------------------------------------------------------+${c.reset}\n`);
+
+  // Progress bar
+  const barWidth = 40;
+  const filled = Math.round((progress.percent / 100) * barWidth);
+  const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+  console.log(`  Progress: [${c.green}${bar}${c.reset}] ${progress.percent}%`);
+  console.log(`  Complete: ${progress.complete}/${progress.total} | Pending: ${progress.pending} | Blocked: ${progress.blocked}\n`);
+
+  // Stories
+  console.log(`${c.bold}Stories:${c.reset}\n`);
+
+  for (const story of data.stories) {
+    let icon, color;
+    switch (story.status) {
+      case 'complete':
+        icon = '✓';
+        color = c.green;
+        break;
+      case 'blocked':
+        icon = '!';
+        color = c.red;
+        break;
+      case 'in_progress':
+        icon = '→';
+        color = c.yellow;
+        break;
+      default:
+        icon = ' ';
+        color = c.dim;
+    }
+
+    console.log(`  ${color}[${icon}]${c.reset} ${story.title}`);
+    if (story.status === 'blocked') {
+      console.log(`      ${c.red}Blocked${c.reset}`);
+    }
+  }
+
+  // Next up
+  const next = prd.getNextStory(data);
+  if (next) {
+    console.log(`\n${c.bold}Next:${c.reset} ${next.title}`);
+  } else if (progress.percent === 100) {
+    console.log(`\n${c.green}All stories complete!${c.reset}`);
+  }
+
+  console.log('');
+}
+
+/**
+ * Generate PRD skill for Claude Code
+ */
+function generateSkill() {
+  const skillDir = path.join(__dirname, '..', '.claude-plugin', 'skills');
+
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+
+  // PRD skill
+  const prdSkill = `# /prd - Generate Product Requirements Document
+
+Generate a detailed PRD with right-sized user stories for autonomous execution.
+
+## Instructions
+
+When the user invokes /prd <feature-name>:
+
+1. Ask clarifying questions about the feature
+2. Generate a detailed PRD with 3-7 user stories
+3. Each story should be:
+   - Completable in a single AI context window
+   - Have clear acceptance criteria
+   - Be independently testable
+
+## Output Format
+
+Create a file at \`tasks/prd-<feature-name>.md\` with this structure:
+
+\`\`\`markdown
+# <Feature Name>
+
+<Brief description>
+
+## Story 1: <Title>
+
+<Description of what needs to be done>
+
+### Acceptance Criteria
+- [ ] Criteria 1
+- [ ] Criteria 2
+
+## Story 2: <Title>
+...
+\`\`\`
+
+## Right-Sizing Guidelines
+
+Stories should be small enough to complete in one session:
+- Adding a database column + migration
+- Creating a single API endpoint
+- Building one UI component
+- Writing tests for one module
+
+Stories that are TOO LARGE:
+- "Build the authentication system"
+- "Implement payment processing"
+- "Create the admin dashboard"
+
+Break large features into multiple stories.
+
+## After Generation
+
+Tell the user:
+1. Review the PRD in \`tasks/prd-<feature-name>.md\`
+2. Convert to JSON: \`bootspring loop prd --from tasks/prd-<feature-name>.md\`
+3. Start the loop: \`bootspring loop start\`
+`;
+
+  fs.writeFileSync(path.join(skillDir, 'prd.md'), prdSkill);
+
+  // Loop skill
+  const loopSkill = `# /loop - Autonomous Task Loop
+
+Start an autonomous execution loop that iterates through PRD stories.
+
+## Prerequisites
+
+- A \`tasks/prd.json\` file with defined stories
+- Either \`claude\` or \`amp\` CLI installed
+
+## Usage
+
+/loop [iterations] [--tool claude|amp]
+
+## What Happens
+
+1. The loop reads the next incomplete story from \`tasks/prd.json\`
+2. A fresh AI instance works on that single story
+3. Quality gates run (tests, lint, typecheck)
+4. On success: commit + mark story complete
+5. Repeat until all stories done or max iterations reached
+
+## Memory Model
+
+Context persists through:
+- Git commits (what changed)
+- CLAUDE.md (project knowledge)
+- prd.json (task status)
+
+Each iteration starts with fresh context to avoid degradation.
+
+## Commands
+
+\`\`\`bash
+bootspring loop start           # Start the loop
+bootspring loop status          # Check PRD progress
+bootspring loop prd <name>      # Create new PRD
+\`\`\`
+`;
+
+  fs.writeFileSync(path.join(skillDir, 'loop.md'), loopSkill);
+
+  // Plugin manifest
+  const manifest = {
+    name: 'bootspring',
+    version: '1.0.0',
+    description: 'Intelligent scaffolding and autonomous task execution',
+    skills: ['prd', 'loop']
+  };
+
+  const manifestPath = path.join(__dirname, '..', '.claude-plugin', 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  console.log(`${c.green}Generated Claude Code plugin:${c.reset}`);
+  console.log(`  .claude-plugin/manifest.json`);
+  console.log(`  .claude-plugin/skills/prd.md`);
+  console.log(`  .claude-plugin/skills/loop.md`);
+  console.log(`\n${c.dim}Users can install with: /plugin add bootspring${c.reset}`);
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  console.log(`
+${c.bold}Bootspring Autonomous Loop${c.reset}
+
+${c.cyan}Usage:${c.reset}
+  bootspring loop <command> [options]
+
+${c.cyan}Commands:${c.reset}
+  start [n] [--tool]    Start loop (n iterations, default 10)
+  status                Show PRD progress
+  prd <name>            Create new PRD template
+  prd --from <file>     Create PRD from markdown
+  skill                 Generate Claude Code plugin skills
+
+${c.cyan}Options:${c.reset}
+  --tool <claude|amp>   AI tool to use (default: claude)
+  --prd <path>          Path to prd.json
+
+${c.cyan}Examples:${c.reset}
+  bootspring loop prd user-auth
+  bootspring loop start 20 --tool claude
+  bootspring loop status
+
+${c.cyan}Workflow:${c.reset}
+  1. Create PRD:    bootspring loop prd my-feature
+  2. Edit stories:  Edit tasks/prd.json
+  3. Start loop:    bootspring loop start
+  4. Monitor:       bootspring loop status
+`);
+}
+
+/**
+ * Main CLI handler
+ */
+function main(args) {
+  const command = args[0] || 'help';
+
+  switch (command) {
+    case 'start': {
+      const tool = detectTool();
+      if (!tool) {
+        console.error(`${c.red}No AI tool found. Install claude or amp CLI.${c.reset}`);
+        process.exit(1);
+      }
+
+      const iterations = args.find(a => /^\d+$/.test(a)) || '10';
+      const toolArg = args.includes('--tool') ?
+        args[args.indexOf('--tool') + 1] : tool;
+      const prdArg = args.includes('--prd') ?
+        args[args.indexOf('--prd') + 1] : null;
+
+      runLoop({ iterations, tool: toolArg, prd: prdArg });
+      break;
+    }
+
+    case 'status':
+      showStatus(args[1]);
+      break;
+
+    case 'prd': {
+      // Skip the 'prd' command itself, find the feature name
+      const prdArgs = args.slice(1);
+      const name = prdArgs.find(a => !a.startsWith('--'));
+      const fromFile = prdArgs.includes('--from') ?
+        prdArgs[prdArgs.indexOf('--from') + 1] : null;
+
+      createPRD(name, { from: fromFile });
+      break;
+    }
+
+    case 'skill':
+    case 'skills':
+      generateSkill();
+      break;
+
+    case 'help':
+    default:
+      showHelp();
+  }
+}
+
+// CLI execution
+if (require.main === module) {
+  main(process.argv.slice(2));
+}
+
+module.exports = { main, runLoop, createPRD, showStatus };

package/cli/mcp.js

@@ -0,0 +1,241 @@
+/**
+ * Bootspring MCP Command
+ * Control the MCP server
+ *
+ * @package bootspring
+ * @command mcp
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const config = require('../core/config');
+const utils = require('../core/utils');
+
+/**
+ * Start MCP server (for direct invocation by Claude Code)
+ */
+function startServer() {
+  // When called directly by MCP, just require the server module
+  // This allows Claude Code to invoke it via stdio
+  require('../mcp/server.js');
+}
+
+/**
+ * Show MCP status and configuration info
+ */
+function showStatus() {
+  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() {
+  console.log(`
+${utils.COLORS.cyan}${utils.COLORS.bold}⚡ Bootspring MCP Test${utils.COLORS.reset}
+`);
+
+  const config = require('../core/config');
+  const context = require('../core/context');
+
+  // 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.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.message}`);
+  }
+
+  // Test hooks
+  const spinner3 = utils.createSpinner('Testing context detection hooks').start();
+  try {
+    const detector = require('../hooks/context-detector');
+    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.message}`);
+  }
+
+  // Test prompt enhancer
+  const spinner4 = utils.createSpinner('Testing prompt enhancer').start();
+  try {
+    const detector = require('../hooks/context-detector');
+    const enhancer = require('../hooks/prompt-enhancer');
+    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.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() {
+  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() {
+  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
+ */
+async function run(args) {
+  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();
+  }
+}
+
+module.exports = { run, startServer, showStatus, testMcp };