ruvnet-kb-first 5.0.0

package/src/commands/init.js

@@ -0,0 +1,315 @@
+/**
+ * KB-First Init Command
+ *
+ * Initializes KB-First structure in the current project.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { existsSync, mkdirSync, writeFileSync, copyFileSync, readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import inquirer from 'inquirer';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Project structure template
+const PROJECT_STRUCTURE = {
+  directories: [
+    '.ruvector',
+    '.ruvector/hooks',
+    '.ruvector/domain',
+    'src',
+    'src/kb',
+    'docs',
+    'phases',
+    'scripts',
+    'templates'
+  ],
+  files: {
+    '.ruvector/config.json': {
+      kbFirst: {
+        version: '5.0.0',
+        initialized: new Date().toISOString(),
+        namespace: '',
+        minConfidence: 0.5,
+        gapLogging: true
+      },
+      hooks: {
+        enabled: true,
+        preToolUse: true,
+        postToolUse: true,
+        sessionEnd: true
+      },
+      phases: {
+        current: 0,
+        completed: []
+      }
+    }
+  }
+};
+
+export async function initCommand(options) {
+  const cwd = process.cwd();
+  const projectName = cwd.split('/').pop().toLowerCase().replace(/[^a-z0-9]/g, '_');
+
+  console.log('');
+  console.log(chalk.cyan('Initializing KB-First project structure...'));
+  console.log('');
+
+  // Check if already initialized
+  const configPath = join(cwd, '.ruvector', 'config.json');
+  if (existsSync(configPath) && !options.force) {
+    console.log(chalk.yellow('Project already initialized.'));
+    console.log(chalk.gray('Use --force to reinitialize.'));
+    return;
+  }
+
+  // Interactive prompts if not forcing
+  let config = { ...PROJECT_STRUCTURE.files['.ruvector/config.json'] };
+
+  if (!options.force) {
+    const answers = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'namespace',
+        message: 'KB namespace (leave empty for project name):',
+        default: projectName
+      },
+      {
+        type: 'confirm',
+        name: 'installHooks',
+        message: 'Install KB-First hooks?',
+        default: options.hooks !== false
+      },
+      {
+        type: 'list',
+        name: 'template',
+        message: 'Project template:',
+        choices: [
+          { name: 'Basic - Simple KB structure', value: 'basic' },
+          { name: 'API - REST API with KB search', value: 'api' },
+          { name: 'Fullstack - Complete web application', value: 'fullstack' }
+        ],
+        default: options.template || 'basic'
+      }
+    ]);
+
+    config.kbFirst.namespace = answers.namespace || projectName;
+    config.hooks.enabled = answers.installHooks;
+  } else {
+    config.kbFirst.namespace = projectName;
+  }
+
+  // Create directories
+  const spinner = ora('Creating directory structure...').start();
+
+  for (const dir of PROJECT_STRUCTURE.directories) {
+    const dirPath = join(cwd, dir);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+  }
+
+  spinner.succeed('Directory structure created');
+
+  // Write config
+  spinner.start('Writing configuration...');
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+  spinner.succeed('Configuration written');
+
+  // Copy phase documentation
+  spinner.start('Copying phase documentation...');
+  const phasesSource = join(__dirname, '..', '..', 'phases');
+  const phasesTarget = join(cwd, 'phases');
+
+  if (existsSync(phasesSource)) {
+    const { globSync } = await import('glob');
+    const phaseFiles = globSync('*.md', { cwd: phasesSource });
+
+    for (const file of phaseFiles) {
+      const source = join(phasesSource, file);
+      const target = join(phasesTarget, file);
+      if (!existsSync(target)) {
+        copyFileSync(source, target);
+      }
+    }
+    spinner.succeed(`Copied ${phaseFiles.length} phase documents`);
+  } else {
+    spinner.warn('Phase documentation not found - skipping');
+  }
+
+  // Copy verification scripts
+  spinner.start('Copying verification scripts...');
+  const scriptsSource = join(__dirname, '..', '..', 'scripts');
+  const scriptsTarget = join(cwd, 'scripts');
+
+  if (existsSync(scriptsSource)) {
+    const { globSync } = await import('glob');
+    const scriptFiles = globSync('*.sh', { cwd: scriptsSource });
+
+    for (const file of scriptFiles) {
+      const source = join(scriptsSource, file);
+      const target = join(scriptsTarget, file);
+      if (!existsSync(target)) {
+        copyFileSync(source, target);
+      }
+    }
+    spinner.succeed(`Copied ${scriptFiles.length} verification scripts`);
+  } else {
+    spinner.warn('Verification scripts not found - skipping');
+  }
+
+  // Install hooks if requested
+  if (config.hooks.enabled && options.hooks !== false) {
+    spinner.start('Installing KB-First hooks...');
+    await installHooks(cwd);
+    spinner.succeed('Hooks installed');
+  }
+
+  // Create .gitignore entries
+  spinner.start('Updating .gitignore...');
+  const gitignorePath = join(cwd, '.gitignore');
+  const gitignoreEntries = [
+    '',
+    '# KB-First',
+    '.ruvector/domain/',
+    '.ruvector/cache/',
+    '*.embedding',
+    ''
+  ].join('\n');
+
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (!content.includes('# KB-First')) {
+      writeFileSync(gitignorePath, content + gitignoreEntries);
+    }
+  } else {
+    writeFileSync(gitignorePath, gitignoreEntries);
+  }
+  spinner.succeed('.gitignore updated');
+
+  // Summary
+  console.log('');
+  console.log(chalk.green('KB-First project initialized successfully!'));
+  console.log('');
+  console.log(chalk.white('Project structure:'));
+  console.log(chalk.gray('  .ruvector/         - KB configuration and hooks'));
+  console.log(chalk.gray('  src/kb/            - Knowledge base modules'));
+  console.log(chalk.gray('  phases/            - Build phase documentation'));
+  console.log(chalk.gray('  scripts/           - Verification scripts'));
+  console.log('');
+  console.log(chalk.white('Next steps:'));
+  console.log(chalk.cyan('  1. Run: kb-first status'));
+  console.log(chalk.cyan('  2. Start Phase 0: kb-first phase 0'));
+  console.log(chalk.cyan('  3. Build your KB in src/kb/'));
+  console.log('');
+}
+
+async function installHooks(projectDir) {
+  const hooksDir = join(projectDir, '.ruvector', 'hooks');
+
+  // PreToolUse hook
+  const preToolUseHook = `#!/usr/bin/env python3
+"""
+KB-First PreToolUse Hook
+Intercepts Write operations to enforce KB-First patterns.
+"""
+
+import json
+import sys
+import os
+
+def check_kb_first(tool_input):
+    """Check if Write operation follows KB-First principles."""
+    if tool_input.get('tool_name') != 'Write':
+        return {'decision': 'approve'}
+
+    file_path = tool_input.get('tool_input', {}).get('file_path', '')
+    content = tool_input.get('tool_input', {}).get('content', '')
+
+    # Check if it's a code file
+    code_extensions = ['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java']
+    is_code_file = any(file_path.endswith(ext) for ext in code_extensions)
+
+    if not is_code_file:
+        return {'decision': 'approve'}
+
+    # Check for KB citation header
+    has_kb_citation = 'KB-Generated:' in content or 'Sources:' in content
+
+    if not has_kb_citation:
+        return {
+            'decision': 'block',
+            'message': 'KB-First Violation: Code files must include KB citation header. Use kb_code_gen first.'
+        }
+
+    return {'decision': 'approve'}
+
+if __name__ == '__main__':
+    try:
+        input_data = json.loads(sys.stdin.read())
+        result = check_kb_first(input_data)
+        print(json.dumps(result))
+    except Exception as e:
+        print(json.dumps({'decision': 'approve', 'error': str(e)}))
+`;
+
+  // PostToolUse hook
+  const postToolUseHook = `#!/usr/bin/env python3
+"""
+KB-First PostToolUse Hook
+Tracks KB usage and logs gaps.
+"""
+
+import json
+import sys
+import os
+from datetime import datetime
+
+def track_kb_usage(tool_result):
+    """Track KB search results and log gaps."""
+    tool_name = tool_result.get('tool_name', '')
+
+    # Track KB searches
+    if 'kb_search' in tool_name or 'kb_code_gen' in tool_name:
+        result = tool_result.get('tool_result', {})
+        coverage = result.get('kb_coverage', 'unknown')
+
+        if coverage == 'gap':
+            log_gap(tool_result)
+
+    return {'status': 'ok'}
+
+def log_gap(tool_result):
+    """Log KB gap for future improvement."""
+    gap_log = os.path.join(os.getcwd(), '.ruvector', 'gaps.jsonl')
+
+    gap_entry = {
+        'timestamp': datetime.now().isoformat(),
+        'query': tool_result.get('tool_input', {}).get('query', ''),
+        'description': tool_result.get('tool_input', {}).get('description', ''),
+        'file_path': tool_result.get('tool_input', {}).get('file_path', '')
+    }
+
+    with open(gap_log, 'a') as f:
+        f.write(json.dumps(gap_entry) + '\\n')
+
+if __name__ == '__main__':
+    try:
+        input_data = json.loads(sys.stdin.read())
+        result = track_kb_usage(input_data)
+        print(json.dumps(result))
+    except Exception as e:
+        print(json.dumps({'status': 'error', 'error': str(e)}))
+`;
+
+  writeFileSync(join(hooksDir, 'pre-tool-use.py'), preToolUseHook);
+  writeFileSync(join(hooksDir, 'post-tool-use.py'), postToolUseHook);
+
+  // Make executable
+  const { chmodSync } = await import('fs');
+  chmodSync(join(hooksDir, 'pre-tool-use.py'), 0o755);
+  chmodSync(join(hooksDir, 'post-tool-use.py'), 0o755);
+}

package/src/commands/phase.js

@@ -0,0 +1,372 @@
+/**
+ * KB-First Phase Command
+ *
+ * Runs or shows information about a specific build phase.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { existsSync, readFileSync, writeFileSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { execFileSync } from 'child_process';
+
+const PHASES = {
+  0: {
+    name: 'Assessment',
+    description: 'Evaluate if KB-First is appropriate for your project',
+    subphases: [
+      '0.1 Project Analysis',
+      '0.2 Domain Complexity',
+      '0.3 KB-First Suitability',
+      '0.4 Resource Estimation',
+      '0.5 Go/No-Go Decision'
+    ],
+    gate: 'Decision documented and approved'
+  },
+  1: {
+    name: 'KB Design',
+    description: 'Design the knowledge base structure',
+    subphases: [
+      '1.1 Domain Mapping',
+      '1.2 Taxonomy Design',
+      '1.3 Relationship Model',
+      '1.4 Query Patterns',
+      '1.5 Design Review'
+    ],
+    gate: 'KB schema designed and documented'
+  },
+  1.5: {
+    name: 'Hooks Setup',
+    description: 'Install and configure KB-First enforcement hooks',
+    subphases: [
+      '1.5.1 Hook Installation',
+      '1.5.2 Hook Configuration',
+      '1.5.3 Pattern Training',
+      '1.5.4 Hook Verification'
+    ],
+    gate: 'All hooks passing verification',
+    script: '1.5-hooks-verify.sh'
+  },
+  2: {
+    name: 'Schema Definition',
+    description: 'Define the database schema for KB storage',
+    subphases: [
+      '2.1 Table Design',
+      '2.2 Vector Columns',
+      '2.3 Index Strategy',
+      '2.4 Migration Scripts'
+    ],
+    gate: 'Schema created and migrations applied'
+  },
+  3: {
+    name: 'KB Population',
+    description: 'Populate the knowledge base with content',
+    subphases: [
+      '3.1 Content Collection',
+      '3.2 Content Processing',
+      '3.3 Embedding Generation',
+      '3.4 Import Validation',
+      '3.5 Initial Testing'
+    ],
+    gate: 'KB populated with initial content'
+  },
+  4: {
+    name: 'Scoring & Gaps',
+    description: 'Score KB quality and identify gaps',
+    subphases: [
+      '4.1 Coverage Analysis',
+      '4.2 Quality Scoring',
+      '4.3 Gap Identification',
+      '4.4 Priority Ranking',
+      '4.5 Remediation Plan'
+    ],
+    gate: 'KB score >= 80, gaps documented'
+  },
+  5: {
+    name: 'Integration',
+    description: 'Integrate KB into application code',
+    subphases: [
+      '5.1 Search API',
+      '5.2 Code Generation',
+      '5.3 Citation System',
+      '5.4 Gap Logging'
+    ],
+    gate: 'KB integrated and accessible'
+  },
+  6: {
+    name: 'Testing',
+    description: 'Test KB functionality and accuracy',
+    subphases: [
+      '6.1 Unit Tests',
+      '6.2 Integration Tests',
+      '6.3 Accuracy Tests',
+      '6.4 Performance Tests',
+      '6.5 Edge Cases'
+    ],
+    gate: 'All tests passing'
+  },
+  7: {
+    name: 'Optimization',
+    description: 'Optimize KB performance',
+    subphases: [
+      '7.1 Query Optimization',
+      '7.2 Index Tuning',
+      '7.3 Caching Strategy',
+      '7.4 Benchmark Validation'
+    ],
+    gate: 'Performance targets met'
+  },
+  8: {
+    name: 'Verification',
+    description: 'Comprehensive KB-First verification',
+    subphases: [
+      '8.1 Code Scan',
+      '8.2 Import Check',
+      '8.3 Source Returns',
+      '8.4 Startup Verify',
+      '8.5 Fallback Check',
+      '8.6 Attribution',
+      '8.7 Confidence',
+      '8.8 Gap Logging'
+    ],
+    gate: 'All 8 verification scripts pass',
+    scripts: [
+      '8.1-code-scan.sh',
+      '8.2-import-check.sh',
+      '8.3-source-returns.sh',
+      '8.4-startup-verify.sh',
+      '8.5-fallback-check.sh',
+      '8.6-attribution.sh',
+      '8.7-confidence.sh',
+      '8.8-gap-logging.sh'
+    ]
+  },
+  9: {
+    name: 'Security',
+    description: 'Security audit and hardening',
+    subphases: [
+      '9.1 Dependency Audit',
+      '9.2 OWASP Top 10',
+      '9.3 SQL Injection',
+      '9.4 Authentication',
+      '9.5 Secrets Management',
+      '9.6 API Security'
+    ],
+    gate: 'Security audit passed',
+    script: '9-security-audit.sh'
+  },
+  10: {
+    name: 'Documentation',
+    description: 'Complete project documentation',
+    subphases: [
+      '10.1 README',
+      '10.2 API Documentation',
+      '10.3 KB Schema Docs',
+      '10.4 Architecture Docs',
+      '10.5 Operator Guide',
+      '10.6 Versioning'
+    ],
+    gate: 'All documentation complete'
+  },
+  11: {
+    name: 'Deployment',
+    description: 'Deploy to production',
+    subphases: [
+      '11.1 Infrastructure',
+      '11.2 Environment Config',
+      '11.3 CI/CD Pipeline',
+      '11.4 Database Migration',
+      '11.5 Monitoring',
+      '11.6 Go-Live'
+    ],
+    gate: 'Application deployed and accessible'
+  }
+};
+
+export async function phaseCommand(phaseNum, options) {
+  const cwd = process.cwd();
+
+  // Parse phase number
+  const phase = parseFloat(phaseNum);
+  const phaseInfo = PHASES[phase];
+
+  if (!phaseInfo) {
+    console.log(chalk.red(`Unknown phase: ${phaseNum}`));
+    console.log(chalk.gray('Valid phases: 0, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11'));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.cyan('╔═══════════════════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan('║') + chalk.bold.white(`  Phase ${phase}: ${phaseInfo.name}`.padEnd(62)) + chalk.cyan('║'));
+  console.log(chalk.cyan('╚═══════════════════════════════════════════════════════════════╝'));
+  console.log('');
+  console.log(chalk.gray(`  ${phaseInfo.description}`));
+  console.log('');
+
+  // Show subphases
+  console.log(chalk.white('  Sub-phases:'));
+  for (const sub of phaseInfo.subphases) {
+    console.log(chalk.gray(`    • ${sub}`));
+  }
+  console.log('');
+
+  // Show quality gate
+  console.log(chalk.white('  Quality Gate:'));
+  console.log(chalk.yellow(`    ${phaseInfo.gate}`));
+  console.log('');
+
+  // Run specific sub-phase if specified
+  if (options.sub) {
+    await runSubphase(cwd, phase, options.sub);
+    return;
+  }
+
+  // Run verification scripts if available
+  if (phaseInfo.scripts || phaseInfo.script) {
+    const scripts = phaseInfo.scripts || [phaseInfo.script];
+    console.log(chalk.white('  Running verification scripts...'));
+    console.log('');
+
+    await runPhaseScripts(cwd, scripts, options.skipGate);
+  } else {
+    // Show phase documentation
+    const phaseDocPath = join(cwd, 'phases', `${String(phase).replace('.', '')}-${phaseInfo.name.toLowerCase().replace(/\s+/g, '-')}.md`);
+    const altPhaseDocPath = join(cwd, 'phases', `0${String(phase).replace('.', '')}-${phaseInfo.name.toLowerCase().replace(/\s+/g, '-')}.md`);
+
+    if (existsSync(phaseDocPath)) {
+      console.log(chalk.gray(`  Documentation: phases/${phaseDocPath.split('/').pop()}`));
+    } else if (existsSync(altPhaseDocPath)) {
+      console.log(chalk.gray(`  Documentation: phases/${altPhaseDocPath.split('/').pop()}`));
+    }
+
+    console.log('');
+    console.log(chalk.white('  Manual Phase'));
+    console.log(chalk.gray('  This phase requires manual completion. Review the documentation'));
+    console.log(chalk.gray('  and complete all sub-phases before marking as complete.'));
+    console.log('');
+    console.log(chalk.cyan('  Mark complete: kb-first phase ' + phase + ' --complete'));
+  }
+
+  // Show next step
+  console.log('');
+  console.log(chalk.gray('─────────────────────────────────────────────────────────────────'));
+  const nextPhase = getNextPhase(phase);
+  if (nextPhase !== null) {
+    console.log(chalk.gray(`  Next: kb-first phase ${nextPhase}`));
+  } else {
+    console.log(chalk.green('  This is the final phase!'));
+  }
+}
+
+async function runPhaseScripts(cwd, scripts, skipGate) {
+  const scriptsDir = join(cwd, 'scripts');
+  let passed = 0;
+  let failed = 0;
+
+  for (const script of scripts) {
+    const scriptPath = join(scriptsDir, script);
+
+    if (!existsSync(scriptPath)) {
+      console.log(chalk.yellow(`    Skip: ${script} (not found)`));
+      continue;
+    }
+
+    const spinner = ora(`  Running ${script}...`).start();
+
+    try {
+      chmodSync(scriptPath, 0o755);
+      execFileSync('/bin/bash', [scriptPath], {
+        cwd,
+        stdio: 'pipe',
+        timeout: 120000,
+        encoding: 'utf-8'
+      });
+
+      spinner.succeed(`  ${script}`);
+      passed++;
+    } catch (error) {
+      spinner.fail(`  ${script}`);
+      failed++;
+    }
+  }
+
+  console.log('');
+
+  if (failed === 0) {
+    console.log(chalk.green('  ✅ All verification scripts passed'));
+
+    // Update phase in config
+    await markPhaseComplete(cwd);
+  } else {
+    console.log(chalk.red(`  ❌ ${failed} script(s) failed`));
+
+    if (!skipGate) {
+      console.log(chalk.yellow('  Quality gate NOT passed. Fix failures before proceeding.'));
+    } else {
+      console.log(chalk.yellow('  Warning: --skip-gate used. Proceeding despite failures.'));
+    }
+  }
+}
+
+async function runSubphase(cwd, phase, subNum) {
+  const phaseInfo = PHASES[phase];
+  const subIndex = parseInt(subNum) - 1;
+
+  if (subIndex < 0 || subIndex >= phaseInfo.subphases.length) {
+    console.log(chalk.red(`Invalid sub-phase: ${subNum}`));
+    console.log(chalk.gray(`Valid sub-phases: 1-${phaseInfo.subphases.length}`));
+    return;
+  }
+
+  const subphase = phaseInfo.subphases[subIndex];
+  console.log(chalk.white(`Running: ${subphase}`));
+  console.log('');
+
+  // Check for specific script
+  const scripts = phaseInfo.scripts || (phaseInfo.script ? [phaseInfo.script] : []);
+  const matchingScript = scripts.find(s => s.startsWith(`${phase}.${subNum}`));
+
+  if (matchingScript) {
+    await runPhaseScripts(cwd, [matchingScript], false);
+  } else {
+    console.log(chalk.gray('  No automated script for this sub-phase.'));
+    console.log(chalk.gray('  Complete manually and proceed to next sub-phase.'));
+  }
+}
+
+async function markPhaseComplete(cwd) {
+  const configPath = join(cwd, '.ruvector', 'config.json');
+
+  if (!existsSync(configPath)) return;
+
+  const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  const currentPhase = config.phases?.current || 0;
+
+  if (!config.phases) {
+    config.phases = { current: 0, completed: [] };
+  }
+
+  if (!config.phases.completed.includes(currentPhase)) {
+    config.phases.completed.push(currentPhase);
+  }
+
+  // Move to next phase
+  const nextPhase = getNextPhase(currentPhase);
+  if (nextPhase !== null) {
+    config.phases.current = nextPhase;
+  }
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2));
+}
+
+function getNextPhase(current) {
+  const phases = [0, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+  const currentIndex = phases.indexOf(current);
+
+  if (currentIndex === -1 || currentIndex === phases.length - 1) {
+    return null;
+  }
+
+  return phases[currentIndex + 1];
+}