create-claude-context 1.2.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # create-claude-context
 
-Set up Claude Context Engineering for any project with a single command.
+Set up Claude Context Engineering for any project with a single command. **Automatically analyzes your codebase** and generates real documentation.
 
 ## Quick Start
 
@@ -16,12 +16,22 @@ npm init claude-context
 
 ## What It Does
 
-This CLI tool sets up a complete context engineering system for your codebase:
+This CLI tool performs **real codebase analysis** and creates a complete context engineering system:
 
-1. **Creates `.claude/` directory** - Context engineering documentation
-2. **Creates `CLAUDE.md`** - Entry point for Claude Code
-3. **Detects tech stack** - Auto-configures for your project
-4. **Installs plugin** - Adds ongoing commands (optional)
+1. **Analyzes codebase** - Discovers entry points, workflows, architecture
+2. **Creates `.claude/` directory** - Populated with real project data
+3. **Creates `CLAUDE.md`** - Entry point with actual file references
+4. **Detects tech stack** - Auto-configures for your project
+5. **AI handoff** - Creates instructions for `@context-engineer` (when in Claude Code)
+
+### Automatic Analysis
+
+| What's Detected | Description |
+|-----------------|-------------|
+| Entry Points | API routes, CLI handlers, event listeners |
+| Workflows | Authentication, payments, data processing patterns |
+| Architecture | Directory structure, layers, dependencies |
+| Tech Stack | Languages, frameworks, package managers |
 
 ## Options
 
@@ -34,11 +44,24 @@ Options:
   -t, --template     Use a tech stack preset
   --no-git           Skip git initialization
   --dry-run          Show what would be done
+  --ai               Force AI mode (requires Claude Code)
+  --static           Force static-only analysis
+  --analyze-only     Run analysis without installation
   -v, --verbose      Show detailed output
   -V, --version      Output version number
   -h, --help         Display help
 ```
 
+## Execution Modes
+
+| Mode | Condition | Capabilities |
+|------|-----------|--------------|
+| **full-ai** | Claude Code + API key | Complete AI-enhanced analysis |
+| **hybrid** | Claude Code (no API) | Static analysis + AI handoff |
+| **standalone** | No Claude Code | Static analysis only |
+
+In hybrid mode, `INIT_REQUEST.md` is created for `@context-engineer` to complete setup.
+
 ## Tech Stack Presets
 
 ```bash

package/bin/create-claude-context.js

@@ -36,9 +36,19 @@ program
   .option('--no-git', 'Skip git initialization')
   .option('--dry-run', 'Show what would be done without making changes')
   .option('-v, --verbose', 'Show detailed output')
+  // New options for context engineering initialization
+  .option('--ai', 'Force AI mode (creates INIT_REQUEST.md for @context-engineer)')
+  .option('--static', 'Force standalone mode (static analysis only, no AI setup)')
+  .option('--analyze-only', 'Run codebase analysis without installation')
   .action(async (projectName, options) => {
     console.log(banner);
 
+    // Validate mutually exclusive options
+    if (options.ai && options.static) {
+      console.error(chalk.red('\n✖ Error: --ai and --static are mutually exclusive'));
+      process.exit(1);
+    }
+
     try {
       await run({
         projectName,
@@ -47,7 +57,11 @@ program
         template: options.template,
         initGit: options.git !== false,
         dryRun: options.dryRun,
-        verbose: options.verbose
+        verbose: options.verbose,
+        // New options
+        forceAi: options.ai,
+        forceStatic: options.static,
+        analyzeOnly: options.analyzeOnly
       });
     } catch (error) {
       console.error(chalk.red('\n✖ Error:'), error.message);

package/lib/ai-orchestrator.js

@@ -0,0 +1,423 @@
+/**
+ * AI Orchestrator
+ *
+ * Coordinates with @context-engineer agent for full AI-powered analysis.
+ * Creates initialization requests and generates agent instructions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Marker file for pending initialization
+ */
+const INIT_MARKER = '.init-pending';
+
+/**
+ * Instruction file for agent
+ */
+const INIT_REQUEST_FILE = 'INIT_REQUEST.md';
+
+/**
+ * Progress tracking file
+ */
+const PROGRESS_FILE = 'INIT_PROGRESS.json';
+
+/**
+ * Create an initialization request marker
+ * @param {string} claudeDir - .claude directory path
+ * @param {object} config - Configuration from CLI
+ * @returns {object} Request object
+ */
+function createInitializationRequest(claudeDir, config) {
+  const request = {
+    version: '1.0.0',
+    createdAt: new Date().toISOString(),
+    projectName: config.projectName || path.basename(path.dirname(claudeDir)),
+    config: {
+      techStack: config.techStack,
+      features: config.features,
+      installPlugin: config.installPlugin
+    },
+    phases: [
+      { id: 'repository-analysis', name: 'Repository Analysis', status: 'pending', progress: 0 },
+      { id: 'workflow-discovery', name: 'Workflow Discovery', status: 'pending', progress: 0 },
+      { id: 'template-population', name: 'Template Population', status: 'pending', progress: 0 },
+      { id: 'index-generation', name: 'Index Generation', status: 'pending', progress: 0 },
+      { id: 'validation', name: 'Validation', status: 'pending', progress: 0 },
+      { id: 'finalization', name: 'Finalization', status: 'pending', progress: 0 }
+    ],
+    status: 'pending',
+    completedAt: null
+  };
+
+  const markerPath = path.join(claudeDir, INIT_MARKER);
+  fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
+
+  return request;
+}
+
+/**
+ * Generate agent instruction file with pre-analysis results
+ * @param {string} claudeDir - .claude directory path
+ * @param {object} analysis - Pre-analysis results from static analyzer
+ * @param {object} config - Configuration from CLI
+ */
+function generateAgentInstructions(claudeDir, analysis, config) {
+  const projectName = config.projectName || path.basename(path.dirname(claudeDir));
+  const pkgVersion = getPackageVersion();
+
+  const instructions = `# Context Engineering Initialization Request
+
+> **Auto-generated by \`create-claude-context\` v${pkgVersion}**
+> Generated: ${new Date().toISOString()}
+
+## Status: Awaiting AI Completion
+
+The CLI has performed static pre-analysis and prepared the template structure.
+Full AI-powered context engineering is requested to complete initialization.
+
+---
+
+## Project Overview
+
+| Property | Value |
+|----------|-------|
+| **Project Name** | ${projectName} |
+| **Tech Stack** | ${analysis.techStack?.summary || 'Detected during analysis'} |
+| **Source Files** | ${analysis.sourceFiles || 'TBD'} |
+| **Lines of Code** | ${analysis.linesOfCode?.total || 'TBD'} |
+
+---
+
+## Pre-Analysis Results
+
+### Entry Points Discovered (${analysis.entryPoints?.length || 0})
+
+${formatEntryPoints(analysis.entryPoints)}
+
+### Workflow Candidates (${analysis.workflows?.length || 0})
+
+${formatWorkflows(analysis.workflows)}
+
+### Architecture Layers
+
+${formatLayers(analysis.architecture?.layers)}
+
+### Dependencies (${analysis.dependencies?.length || 0})
+
+${formatDependencies(analysis.dependencies)}
+
+---
+
+## Requested Actions
+
+Please complete the context engineering initialization by:
+
+### Phase 1: Verify Pre-Analysis
+- [ ] Review discovered entry points for accuracy
+- [ ] Confirm workflow candidates are valid
+- [ ] Identify any missed entry points or workflows
+
+### Phase 2: Deep Workflow Discovery
+- [ ] Trace call chains for each workflow (3 levels deep)
+- [ ] Identify database operations per workflow
+- [ ] Map external API calls per workflow
+- [ ] Document error handling patterns
+
+### Phase 3: Template Population
+- [ ] Fill ARCHITECTURE_SNAPSHOT.md with real architecture
+- [ ] Create individual workflow files (8-15 total)
+- [ ] Populate CODE_TO_WORKFLOW_MAP.md with file references
+- [ ] Update WORKFLOW_INDEX.md with all workflows
+
+### Phase 4: Index Generation
+- [ ] Generate proper category indexes
+- [ ] Create semantic anchors for key functions
+- [ ] Build reverse lookup indexes
+
+### Phase 5: Validation
+- [ ] Verify line number accuracy (target: 60%+)
+- [ ] Check all internal links
+- [ ] Confirm no placeholder values remain
+
+### Phase 6: Finalization
+- [ ] Generate summary report
+- [ ] Update CLAUDE.md with project-specific info
+- [ ] Create maintenance schedule
+
+---
+
+## Quick Start Command
+
+\`\`\`bash
+@context-engineer "Complete initialization for ${projectName} using the pre-analysis in INIT_REQUEST.md"
+\`\`\`
+
+Or use the dedicated command:
+
+\`\`\`bash
+/rpi-research "Complete context engineering initialization"
+\`\`\`
+
+---
+
+## Files to Update
+
+| File | Action |
+|------|--------|
+| \`context/ARCHITECTURE_SNAPSHOT.md\` | Populate with real architecture |
+| \`context/WORKFLOW_INDEX.md\` | Add all discovered workflows |
+| \`context/CODE_TO_WORKFLOW_MAP.md\` | Map files to workflows |
+| \`context/workflows/*.md\` | Create individual workflow docs |
+| \`indexes/workflows/CATEGORY_INDEX.md\` | Generate category index |
+| \`../CLAUDE.md\` | Finalize with project info |
+
+---
+
+## Pre-Analysis Data
+
+The following JSON contains the full pre-analysis for programmatic use:
+
+\`\`\`json
+${JSON.stringify(analysis.summary || {}, null, 2)}
+\`\`\`
+
+---
+
+*This file will be deleted automatically after successful initialization.*
+*Generated by create-claude-context v${pkgVersion}*
+`;
+
+  const instructionPath = path.join(claudeDir, INIT_REQUEST_FILE);
+  fs.writeFileSync(instructionPath, instructions);
+
+  return instructionPath;
+}
+
+/**
+ * Format entry points for markdown
+ * @param {object[]} entryPoints - Entry points array
+ * @returns {string}
+ */
+function formatEntryPoints(entryPoints) {
+  if (!entryPoints || entryPoints.length === 0) {
+    return '*No entry points discovered during pre-analysis. AI analysis will discover them.*\n';
+  }
+
+  const limited = entryPoints.slice(0, 15);
+  let output = '| File | Line | Route | Method |\n|------|------|-------|--------|\n';
+
+  for (const ep of limited) {
+    output += `| \`${ep.file}\` | ${ep.line} | ${ep.route || '-'} | ${ep.method || '-'} |\n`;
+  }
+
+  if (entryPoints.length > 15) {
+    output += `\n*...and ${entryPoints.length - 15} more entry points*\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Format workflows for markdown
+ * @param {object[]} workflows - Workflows array
+ * @returns {string}
+ */
+function formatWorkflows(workflows) {
+  if (!workflows || workflows.length === 0) {
+    return '*No workflows discovered during pre-analysis. AI analysis will discover them.*\n';
+  }
+
+  let output = '| Workflow | Category | Complexity | Files | Confidence |\n|----------|----------|------------|-------|------------|\n';
+
+  for (const wf of workflows) {
+    output += `| **${wf.name}** | ${wf.category} | ${wf.complexity} | ${wf.fileCount || wf.files?.length || 0} | ${wf.confidence || '-'}% |\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Format architecture layers for markdown
+ * @param {object[]} layers - Layers array
+ * @returns {string}
+ */
+function formatLayers(layers) {
+  if (!layers || layers.length === 0) {
+    return '*Architecture layers will be determined during AI analysis.*\n';
+  }
+
+  let output = '| Layer | Directories | Purpose |\n|-------|-------------|----------|\n';
+
+  for (const layer of layers) {
+    output += `| **${layer.name}** | ${layer.directories?.join(', ') || '-'} | ${layer.purpose || '-'} |\n`;
+  }
+
+  return output;
+}
+
+/**
+ * Format dependencies for markdown
+ * @param {object[]} dependencies - Dependencies array
+ * @returns {string}
+ */
+function formatDependencies(dependencies) {
+  if (!dependencies || dependencies.length === 0) {
+    return '*No dependencies detected.*\n';
+  }
+
+  // Group by ecosystem
+  const byEcosystem = {};
+  for (const dep of dependencies) {
+    const eco = dep.ecosystem || 'unknown';
+    if (!byEcosystem[eco]) byEcosystem[eco] = [];
+    byEcosystem[eco].push(dep);
+  }
+
+  let output = '';
+  for (const [ecosystem, deps] of Object.entries(byEcosystem)) {
+    output += `\n**${ecosystem.toUpperCase()}** (${deps.length}):\n`;
+    const topDeps = deps.slice(0, 10);
+    output += topDeps.map(d => `- ${d.name}@${d.version}`).join('\n') + '\n';
+    if (deps.length > 10) {
+      output += `- *...and ${deps.length - 10} more*\n`;
+    }
+  }
+
+  return output;
+}
+
+/**
+ * Get package version
+ * @returns {string}
+ */
+function getPackageVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version || '1.0.0';
+  } catch {
+    return '1.0.0';
+  }
+}
+
+/**
+ * Check initialization status
+ * @param {string} claudeDir - .claude directory path
+ * @returns {object}
+ */
+function checkInitializationStatus(claudeDir) {
+  const markerPath = path.join(claudeDir, INIT_MARKER);
+
+  if (!fs.existsSync(markerPath)) {
+    return { status: 'not-started', request: null };
+  }
+
+  try {
+    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+    const completedPhases = request.phases.filter(p => p.status === 'completed').length;
+    const totalPhases = request.phases.length;
+
+    return {
+      status: completedPhases === totalPhases ? 'completed' : 'in-progress',
+      progress: Math.round((completedPhases / totalPhases) * 100),
+      completedPhases,
+      totalPhases,
+      request
+    };
+  } catch {
+    return { status: 'error', request: null };
+  }
+}
+
+/**
+ * Update initialization progress
+ * @param {string} claudeDir - .claude directory path
+ * @param {string} phaseId - Phase ID to update
+ * @param {string} status - New status ('in-progress', 'completed', 'failed')
+ * @param {number} progress - Progress percentage (0-100)
+ */
+function updateInitializationProgress(claudeDir, phaseId, status, progress = 0) {
+  const markerPath = path.join(claudeDir, INIT_MARKER);
+
+  if (!fs.existsSync(markerPath)) {
+    return false;
+  }
+
+  try {
+    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+    const phase = request.phases.find(p => p.id === phaseId);
+
+    if (phase) {
+      phase.status = status;
+      phase.progress = progress;
+      phase.updatedAt = new Date().toISOString();
+    }
+
+    // Check if all phases are completed
+    const allCompleted = request.phases.every(p => p.status === 'completed');
+    if (allCompleted) {
+      request.status = 'completed';
+      request.completedAt = new Date().toISOString();
+    } else {
+      request.status = 'in-progress';
+    }
+
+    fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark initialization as complete and clean up
+ * @param {string} claudeDir - .claude directory path
+ * @param {boolean} removeMarker - Whether to remove the marker file
+ */
+function completeInitialization(claudeDir, removeMarker = true) {
+  const markerPath = path.join(claudeDir, INIT_MARKER);
+  const instructionPath = path.join(claudeDir, INIT_REQUEST_FILE);
+
+  if (fs.existsSync(markerPath)) {
+    const request = JSON.parse(fs.readFileSync(markerPath, 'utf-8'));
+    request.status = 'completed';
+    request.completedAt = new Date().toISOString();
+
+    // Archive to progress file
+    const progressPath = path.join(claudeDir, PROGRESS_FILE);
+    fs.writeFileSync(progressPath, JSON.stringify(request, null, 2));
+
+    if (removeMarker) {
+      fs.unlinkSync(markerPath);
+    }
+  }
+
+  // Remove instruction file
+  if (removeMarker && fs.existsSync(instructionPath)) {
+    fs.unlinkSync(instructionPath);
+  }
+}
+
+/**
+ * Check if initialization is pending
+ * @param {string} claudeDir - .claude directory path
+ * @returns {boolean}
+ */
+function isInitializationPending(claudeDir) {
+  const markerPath = path.join(claudeDir, INIT_MARKER);
+  return fs.existsSync(markerPath);
+}
+
+module.exports = {
+  createInitializationRequest,
+  generateAgentInstructions,
+  checkInitializationStatus,
+  updateInitializationProgress,
+  completeInitialization,
+  isInitializationPending,
+  INIT_MARKER,
+  INIT_REQUEST_FILE,
+  PROGRESS_FILE
+};