create-universal-ai-context 2.0.0 → 2.1.2

package/README.md

@@ -29,36 +29,68 @@ That's it. The CLI automatically:
 
 ```bash
 # Basic usage
-npx create-ai-context                    # Auto-detect and generate for all tools
+npx create-universal-ai-context                    # Auto-detect and generate for all tools
 
 # Select specific AI tools
-npx create-ai-context --ai claude        # Claude Code only
-npx create-ai-context --ai copilot       # GitHub Copilot only
-npx create-ai-context --ai cline         # Cline only
-npx create-ai-context --ai antigravity   # Antigravity only
-npx create-ai-context --ai all           # All tools (default)
+npx create-universal-ai-context --ai claude        # Claude Code only
+npx create-universal-ai-context --ai copilot       # GitHub Copilot only
+npx create-universal-ai-context --ai cline         # Cline only
+npx create-universal-ai-context --ai antigravity   # Antigravity only
+npx create-universal-ai-context --ai all           # All tools (default)
 
 # Analysis modes
-npx create-ai-context --static           # Force static analysis only
-npx create-ai-context --force-ai         # Require Claude Code session
+npx create-universal-ai-context --static           # Force static analysis only
+npx create-universal-ai-context --force-ai         # Require Claude Code session
 
 # Other options
-npx create-ai-context --yes              # Accept all defaults
-npx create-ai-context --dry-run          # Preview without changes
-npx create-ai-context my-project         # Create in new directory
+npx create-universal-ai-context --yes              # Accept all defaults
+npx create-universal-ai-context --dry-run          # Preview without changes
+npx create-universal-ai-context my-project         # Create in new directory
 ```
 
 ## Subcommands
 
 ```bash
 # Generate context for specific tools
-npx create-ai-context generate --ai copilot
+npx create-universal-ai-context generate --ai copilot
 
 # Check installation status
-npx create-ai-context status
+npx create-universal-ai-context status
 
 # Migrate from v1.x
-npx create-ai-context migrate
+npx create-universal-ai-context migrate
+
+# Check documentation drift
+npx create-universal-ai-context drift --all           # Check all docs
+npx create-universal-ai-context drift --file README.md  # Check specific file
+npx create-universal-ai-context drift --fix           # Auto-fix issues
+npx create-universal-ai-context drift --strict        # Exit 1 on issues (CI)
+```
+
+## Existing Documentation Detection
+
+The CLI automatically detects existing AI context files:
+
+```bash
+npx create-universal-ai-context
+
+# Found existing documentation: Claude context (v1), README.md
+# ? How would you like to proceed?
+#   > Merge: Use existing docs as base, add new structure (recommended)
+#     Fresh: Start fresh but import key values
+#     Overwrite: Replace everything with new templates
+#     Skip: Cancel initialization
+```
+
+### Merge Mode Options
+
+```bash
+npx create-universal-ai-context --mode merge          # Preserve customizations (default)
+npx create-universal-ai-context --mode fresh          # New structure, keep values
+npx create-universal-ai-context --mode overwrite      # Replace everything
+npx create-universal-ai-context --preserve-custom     # Keep user customizations
+npx create-universal-ai-context --update-refs         # Auto-fix line numbers
+npx create-universal-ai-context --backup              # Create backup first
 ```
 
 ## What Gets Analyzed
@@ -104,14 +136,14 @@ your-project/
 ## Tech Stack Presets
 
 ```bash
-npx create-ai-context -t python-fastapi
-npx create-ai-context -t python-django
-npx create-ai-context -t node-express
-npx create-ai-context -t node-nestjs
-npx create-ai-context -t typescript-nextjs
-npx create-ai-context -t go-gin
-npx create-ai-context -t rust-actix
-npx create-ai-context -t ruby-rails
+npx create-universal-ai-context -t python-fastapi
+npx create-universal-ai-context -t python-django
+npx create-universal-ai-context -t node-express
+npx create-universal-ai-context -t node-nestjs
+npx create-universal-ai-context -t typescript-nextjs
+npx create-universal-ai-context -t go-gin
+npx create-universal-ai-context -t rust-actix
+npx create-universal-ai-context -t ruby-rails
 ```
 
 ## Features
@@ -134,7 +166,7 @@ npx create-ai-context -t ruby-rails
 If you have an existing `.claude/` directory:
 
 ```bash
-npx create-ai-context migrate
+npx create-universal-ai-context migrate
 ```
 
 This will:

package/bin/create-ai-context.js

@@ -25,6 +25,12 @@ const { migrateV1ToV2, getMigrationStatus } = require('../lib/migrate');
 const { detectTechStack } = require('../lib/detector');
 const { analyzeCodebase } = require('../lib/static-analyzer');
 const { createSpinner } = require('../lib/spinner');
+const {
+  findDocumentationFiles,
+  generateDriftReport,
+  checkDocumentDrift,
+  formatDriftReportConsole
+} = require('../lib/drift-checker');
 const packageJson = require('../package.json');
 
 // ASCII Banner
@@ -70,6 +76,10 @@ program
   .option('--analyze-only', 'Run codebase analysis without installation')
   .option('--monorepo', 'Initialize in monorepo mode with federation support')
   .option('--federate', 'Run federation to generate context for subprojects')
+  .option('--mode <mode>', 'How to handle existing docs: merge, overwrite, interactive', 'merge')
+  .option('--preserve-custom', 'Keep user customizations when merging (default: true)', true)
+  .option('--update-refs', 'Auto-fix drifted line references')
+  .option('--backup', 'Create backup before modifying existing files')
   .action(async (projectName, options) => {
     console.log(banner);
 
@@ -94,7 +104,12 @@ program
         forceStatic: options.static,
         analyzeOnly: options.analyzeOnly,
         monorepo: options.monorepo,
-        federate: options.federate
+        federate: options.federate,
+        // Merge options
+        mode: options.mode,
+        preserveCustom: options.preserveCustom,
+        updateRefs: options.updateRefs,
+        backup: options.backup
       });
     } catch (error) {
       console.error(chalk.red('\n✖ Error:'), error.message);
@@ -334,4 +349,147 @@ program
     }
   });
 
+// Drift subcommand - check documentation drift
+program
+  .command('drift')
+  .description('Check documentation drift against codebase')
+  .option('-f, --file <path>', 'Check specific documentation file')
+  .option('-a, --all', 'Check all documentation files')
+  .option('--fix', 'Show suggested fixes for issues')
+  .option('--strict', 'Exit with error if drift detected')
+  .option('-o, --output <format>', 'Output format: console, json, markdown', 'console')
+  .option('-t, --threshold <percent>', 'Health score threshold for --strict', '70')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+    const spinner = createSpinner();
+
+    try {
+      // Determine which files to check
+      let filesToCheck = [];
+
+      if (options.file) {
+        // Single file mode
+        filesToCheck = [options.file];
+      } else if (options.all) {
+        // All documentation files
+        spinner.start('Finding documentation files...');
+        filesToCheck = await findDocumentationFiles(projectRoot);
+        spinner.succeed(`Found ${filesToCheck.length} documentation files`);
+      } else {
+        // Default: check main context files
+        const defaultFiles = ['CLAUDE.md', 'AI_CONTEXT.md', 'README.md'];
+        filesToCheck = defaultFiles.filter(f =>
+          fs.existsSync(path.join(projectRoot, f))
+        );
+
+        if (filesToCheck.length === 0) {
+          console.log(chalk.yellow('\nNo documentation files found.'));
+          console.log(chalk.gray('Use --all to scan for all markdown files, or --file to check a specific file.'));
+          process.exit(0);
+        }
+      }
+
+      // Generate drift report
+      spinner.start('Checking documentation drift...');
+      const report = generateDriftReport(filesToCheck, projectRoot);
+      spinner.succeed(`Checked ${report.summary.totalDocuments} documents`);
+
+      // Output results
+      if (options.output === 'json') {
+        console.log(JSON.stringify(report, null, 2));
+      } else if (options.output === 'markdown') {
+        console.log(formatDriftReportMarkdown(report));
+      } else {
+        // Console output
+        console.log(formatDriftReportConsole(report));
+      }
+
+      // Show suggested fixes if requested
+      if (options.fix && report.suggestedFixes.length > 0) {
+        console.log(chalk.bold('\nSuggested Fixes:'));
+        for (const fix of report.suggestedFixes) {
+          console.log(chalk.cyan(`\n  ${fix.document}:`));
+          console.log(chalk.red(`    - ${fix.original}`));
+          console.log(chalk.green(`    + ${fix.suggestion}`));
+        }
+      }
+
+      // Strict mode - exit with error if below threshold
+      if (options.strict) {
+        const threshold = parseInt(options.threshold, 10);
+        if (report.summary.overallHealthScore < threshold) {
+          console.log(chalk.red(`\n✖ Health score ${report.summary.overallHealthScore}% is below threshold ${threshold}%`));
+          process.exit(1);
+        } else {
+          console.log(chalk.green(`\n✓ Health score ${report.summary.overallHealthScore}% meets threshold ${threshold}%`));
+        }
+      }
+
+    } catch (error) {
+      spinner.fail('Drift check failed');
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      if (options.verbose) {
+        console.error(chalk.gray(error.stack));
+      }
+      process.exit(1);
+    }
+  });
+
+/**
+ * Format drift report as markdown
+ */
+function formatDriftReportMarkdown(report) {
+  const lines = [
+    '# Documentation Drift Report',
+    '',
+    `**Generated:** ${report.generatedAt}`,
+    `**Overall Health:** ${report.summary.overallHealthScore}%`,
+    '',
+    '## Summary',
+    '',
+    '| Metric | Value |',
+    '|--------|-------|',
+    `| Documents Analyzed | ${report.summary.totalDocuments} |`,
+    `| Healthy | ${report.summary.healthyDocuments} |`,
+    `| With Issues | ${report.summary.documentsWithIssues} |`,
+    `| References Valid | ${report.summary.validReferences}/${report.summary.totalReferences} |`,
+    ''
+  ];
+
+  if (report.documents.length > 0) {
+    lines.push('## Documents', '');
+    for (const doc of report.documents) {
+      const emoji = doc.status === 'healthy' ? '✓' :
+                    doc.status === 'needs_update' ? '⚠' : '✗';
+      lines.push(`### ${doc.document} (${doc.healthScore}% ${emoji})`);
+      lines.push('');
+
+      if (doc.references.invalid.length > 0) {
+        lines.push('**Issues:**', '');
+        for (const issue of doc.references.invalid) {
+          lines.push(`- \`${issue.original}\` - ${issue.issue}`);
+          if (issue.suggestion) {
+            lines.push(`  - Suggestion: ${issue.suggestion}`);
+          }
+        }
+        lines.push('');
+      }
+    }
+  }
+
+  if (report.suggestedFixes.length > 0) {
+    lines.push('## Suggested Fixes', '');
+    for (const fix of report.suggestedFixes) {
+      lines.push(`- **${fix.document}**: \`${fix.original}\``);
+      lines.push(`  - → ${fix.suggestion}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
 program.parse();

package/lib/adapters/claude.js

@@ -1,7 +1,7 @@
 /**
  * Claude Adapter
  *
- * Generates AI_CONTEXT.md and .ai-context/ directory structure.
+ * Generates AI_CONTEXT.md and .claude/ directory structure.
  * This is the primary/universal format.
  */
 
@@ -16,8 +16,8 @@ const adapter = {
   name: 'claude',
   displayName: 'Claude Code',
   description: 'Universal AI context format for Claude Code and other AI assistants',
-  outputType: 'single-file',
-  outputPath: 'AI_CONTEXT.md'
+  outputType: 'multi-file',
+  outputPath: '.claude/'
 };
 
 /**
@@ -35,11 +35,13 @@ function getOutputPath(projectRoot) {
  * @returns {boolean}
  */
 function exists(projectRoot) {
-  return fs.existsSync(getOutputPath(projectRoot));
+  const aiContextPath = getOutputPath(projectRoot);
+  const claudeDir = path.join(projectRoot, '.claude');
+  return fs.existsSync(aiContextPath) || fs.existsSync(claudeDir);
 }
 
 /**
- * Generate Claude context file
+ * Generate Claude context file and .claude/ directory structure
  * @param {object} analysis - Analysis results from static analyzer
  * @param {object} config - Configuration from CLI
  * @param {string} projectRoot - Project root directory
@@ -54,22 +56,24 @@ async function generate(analysis, config, projectRoot) {
   };
 
   try {
-    // Build context from analysis
+    // 1. Generate AI_CONTEXT.md at project root (existing behavior)
     const context = buildContext(analysis, config);
-
-    // Render template
     const content = renderTemplateByName('claude', context);
-
-    // Write output file
     const outputPath = getOutputPath(projectRoot);
     fs.writeFileSync(outputPath, content, 'utf-8');
-
-    result.success = true;
     result.files.push({
       path: outputPath,
       relativePath: 'AI_CONTEXT.md',
       size: content.length
     });
+
+    // 2. Generate .claude/ directory structure (NEW)
+    const claudeDirResult = await generateClaudeDirectory(projectRoot, context, result);
+    if (claudeDirResult) {
+      result.files.push(...claudeDirResult);
+    }
+
+    result.success = result.errors.length === 0 || result.errors.some(e => e.code === 'EXISTS');
   } catch (error) {
     result.errors.push({
       message: error.message,
@@ -80,36 +84,183 @@ async function generate(analysis, config, projectRoot) {
   return result;
 }
 
+/**
+ * Generate .claude/ directory with full structure
+ * @param {string} projectRoot - Project root directory
+ * @param {object} context - Template context
+ * @param {object} result - Result object to track files/errors
+ * @returns {Array} List of generated files
+ */
+async function generateClaudeDirectory(projectRoot, context, result) {
+  const { copyDirectory } = require('../installer');
+  const templatesDir = path.join(__dirname, '..', '..', 'templates', 'base');
+  const claudeDir = path.join(projectRoot, '.claude');
+
+  // Don't overwrite existing .claude/ directory
+  if (fs.existsSync(claudeDir)) {
+    result.errors.push({
+      message: '.claude/ directory already exists, skipping structure generation',
+      code: 'EXISTS',
+      severity: 'warning'
+    });
+    return [{
+      path: claudeDir,
+      relativePath: '.claude/',
+      size: 0,
+      skipped: true
+    }];
+  }
+
+  try {
+    // Create .claude/ directory
+    fs.mkdirSync(claudeDir, { recursive: true });
+
+    // Copy relevant subdirectories from templates/base to .claude/
+    const subdirsToCopy = [
+      'agents',
+      'commands',
+      'indexes',
+      'context',
+      'schemas',
+      'standards'
+    ];
+
+    // Only copy tools if explicitly enabled
+    if (context.features?.tools !== false) {
+      subdirsToCopy.push('tools');
+    }
+
+    let filesCopied = 0;
+    for (const subdir of subdirsToCopy) {
+      const srcPath = path.join(templatesDir, subdir);
+      if (fs.existsSync(srcPath)) {
+        const destPath = path.join(claudeDir, subdir);
+        fs.mkdirSync(destPath, { recursive: true });
+        const count = await copyDirectory(srcPath, destPath);
+        filesCopied += count;
+      }
+    }
+
+    // Create minimal .claude/settings.json
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    const settings = {
+      '$schema': './schemas/settings.schema.json',
+      version: '2.1.0',
+      project: {
+        name: context.project?.name || 'Project',
+        tech_stack: context.project?.tech_stack || 'Not detected'
+      },
+      agents: {
+        context_engineer: 'enabled',
+        core_architect: 'enabled',
+        api_developer: 'enabled',
+        database_ops: 'enabled',
+        integration_hub: 'enabled',
+        deployment_ops: 'enabled'
+      },
+      commands: {
+        rpi_workflow: 'enabled',
+        validation: 'enabled'
+      }
+    };
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    filesCopied++;
+
+    // Create .claude/README.md
+    const readmePath = path.join(claudeDir, 'README.md');
+    const readme = `# .claude Configuration - ${context.project?.name || 'Project'}
+
+This directory contains Claude Code-specific context engineering files.
+
+## Quick Start
+
+1. Load agents: \`@context-engineer\`
+2. Use commands: \`/rpi-research\`, \`/rpi-plan\`, \`/rpi-implement\`
+3. Validate: \`/verify-docs-current\`
+
+## Universal Context
+
+See \`AI_CONTEXT.md\` at project root for universal AI context (works with all tools).
+
+## Claude-Specific Files
+
+- **agents/** - Specialized agents for different tasks
+- **commands/** - Custom slash commands
+- **indexes/** - 3-level navigation system
+- **context/** - Workflow documentation
+
+*Generated by create-universal-ai-context v${context.version || '2.1.0'}*
+`;
+    fs.writeFileSync(readmePath, readme);
+    filesCopied++;
+
+    return [{
+      path: claudeDir,
+      relativePath: '.claude/',
+      size: filesCopied
+    }];
+
+  } catch (error) {
+    result.errors.push({
+      message: `Failed to generate .claude/ directory: ${error.message}`,
+      stack: error.stack
+    });
+    return null;
+  }
+}
+
 /**
  * Validate Claude output
  * @param {string} projectRoot - Project root directory
  * @returns {object} Validation result
  */
 function validate(projectRoot) {
-  const outputPath = getOutputPath(projectRoot);
+  const issues = [];
 
+  // 1. Validate AI_CONTEXT.md
+  const outputPath = getOutputPath(projectRoot);
   if (!fs.existsSync(outputPath)) {
-    return {
-      valid: false,
-      error: 'AI_CONTEXT.md not found'
-    };
+    issues.push({ file: 'AI_CONTEXT.md', error: 'not found' });
+  } else {
+    const content = fs.readFileSync(outputPath, 'utf-8');
+    const placeholderMatch = content.match(/\{\{[A-Z_]+\}\}/g);
+    if (placeholderMatch && placeholderMatch.length > 0) {
+      issues.push({
+        file: 'AI_CONTEXT.md',
+        error: `Found ${placeholderMatch.length} unreplaced placeholders`
+      });
+    }
   }
 
-  const content = fs.readFileSync(outputPath, 'utf-8');
-
-  // Check for unreplaced placeholders
-  const placeholderMatch = content.match(/\{\{[A-Z_]+\}\}/g);
-  if (placeholderMatch && placeholderMatch.length > 0) {
-    return {
-      valid: false,
-      error: `Found ${placeholderMatch.length} unreplaced placeholders`,
-      placeholders: placeholderMatch
-    };
+  // 2. Validate .claude/ directory (optional, warn if missing)
+  const claudeDir = path.join(projectRoot, '.claude');
+  if (!fs.existsSync(claudeDir)) {
+    issues.push({
+      file: '.claude/',
+      error: 'directory not found (optional but recommended)',
+      severity: 'warning'
+    });
+  } else {
+    // Check for critical files
+    const criticalFiles = [
+      'settings.json',
+      'README.md'
+    ];
+    for (const file of criticalFiles) {
+      if (!fs.existsSync(path.join(claudeDir, file))) {
+        issues.push({
+          file: `.claude/${file}`,
+          error: 'missing',
+          severity: 'warning'
+        });
+      }
+    }
   }
 
   return {
-    valid: true,
-    size: content.length
+    valid: issues.filter(i => i.severity !== 'warning').length === 0,
+    issues,
+    warnings: issues.filter(i => i.severity === 'warning').length
   };
 }