create-universal-ai-context 2.0.0

package/lib/ai-orchestrator.js

@@ -0,0 +1,431 @@
+/**
+ * AI Context Engineering - 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');
+
+/**
+ * Context directory and file names
+ */
+const AI_CONTEXT_DIR = '.ai-context';
+const AI_CONTEXT_FILE = 'AI_CONTEXT.md';
+
+/**
+ * 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} contextDir - .ai-context directory path
+ * @param {object} config - Configuration from CLI
+ * @returns {object} Request object
+ */
+function createInitializationRequest(contextDir, config) {
+  const request = {
+    version: '2.0.0',
+    createdAt: new Date().toISOString(),
+    projectName: config.projectName || path.basename(path.dirname(contextDir)),
+    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(contextDir, INIT_MARKER);
+  fs.writeFileSync(markerPath, JSON.stringify(request, null, 2));
+
+  return request;
+}
+
+/**
+ * Generate agent instruction file with pre-analysis results
+ * @param {string} contextDir - .ai-context directory path
+ * @param {object} analysis - Pre-analysis results from static analyzer
+ * @param {object} config - Configuration from CLI
+ */
+function generateAgentInstructions(contextDir, analysis, config) {
+  const projectName = config.projectName || path.basename(path.dirname(contextDir));
+  const pkgVersion = getPackageVersion();
+
+  const instructions = `# Context Engineering Initialization Request
+
+> **Auto-generated by \`create-ai-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 AI_CONTEXT.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 |
+| \`../AI_CONTEXT.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-ai-context v${pkgVersion}*
+`;
+
+  const instructionPath = path.join(contextDir, 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} contextDir - .ai-context directory path
+ * @returns {object}
+ */
+function checkInitializationStatus(contextDir) {
+  const markerPath = path.join(contextDir, 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} contextDir - .ai-context 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(contextDir, phaseId, status, progress = 0) {
+  const markerPath = path.join(contextDir, 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} contextDir - .ai-context directory path
+ * @param {boolean} removeMarker - Whether to remove the marker file
+ */
+function completeInitialization(contextDir, removeMarker = true) {
+  const markerPath = path.join(contextDir, INIT_MARKER);
+  const instructionPath = path.join(contextDir, 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(contextDir, 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} contextDir - .ai-context directory path
+ * @returns {boolean}
+ */
+function isInitializationPending(contextDir) {
+  const markerPath = path.join(contextDir, INIT_MARKER);
+  return fs.existsSync(markerPath);
+}
+
+module.exports = {
+  createInitializationRequest,
+  generateAgentInstructions,
+  checkInitializationStatus,
+  updateInitializationProgress,
+  completeInitialization,
+  isInitializationPending,
+  INIT_MARKER,
+  INIT_REQUEST_FILE,
+  PROGRESS_FILE,
+  AI_CONTEXT_DIR,
+  AI_CONTEXT_FILE
+};