create-universal-ai-context 2.3.0 → 2.4.0

package/lib/adapters/windsurf.js

@@ -0,0 +1,138 @@
+/**
+ * Windsurf IDE Adapter
+ *
+ * Generates .windsurf/rules.md file for Windsurf IDE Cascade AI
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { renderTemplateByName, buildContext } = require('../template-renderer');
+const { isManagedFile } = require('../template-coordination');
+
+/**
+ * Adapter metadata
+ */
+const adapter = {
+  name: 'windsurf',
+  displayName: 'Windsurf IDE',
+  description: 'Project rules for Windsurf IDE Cascade AI',
+  outputType: 'single-file',
+  outputPath: '.windsurf/rules.md'
+};
+
+/**
+ * Get output path for Windsurf rules file
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Output file path
+ */
+function getOutputPath(projectRoot) {
+  return path.join(projectRoot, '.windsurf', 'rules.md');
+}
+
+/**
+ * Check if Windsurf output already exists
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean}
+ */
+function exists(projectRoot) {
+  const rulesPath = getOutputPath(projectRoot);
+  const windsurfDir = path.join(projectRoot, '.windsurf');
+  return fs.existsSync(rulesPath) || fs.existsSync(windsurfDir);
+}
+
+/**
+ * Generate Windsurf rules file
+ * @param {object} analysis - Analysis results from static analyzer
+ * @param {object} config - Configuration from CLI
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Generation result
+ */
+async function generate(analysis, config, projectRoot) {
+  const result = {
+    success: false,
+    adapter: adapter.name,
+    files: [],
+    errors: []
+  };
+
+  try {
+    const rulesPath = getOutputPath(projectRoot);
+
+    // Check if file exists and is custom (not managed by us)
+    if (fs.existsSync(rulesPath) && !config.force) {
+      if (!isManagedFile(rulesPath)) {
+        result.errors.push({
+          message: '.windsurf/rules.md exists and appears to be custom. Use --force to overwrite.',
+          code: 'EXISTS_CUSTOM',
+          severity: 'error'
+        });
+        return result;
+      }
+    }
+
+    // Build context from analysis
+    const context = buildContext(analysis, config, 'windsurf');
+
+    // Render template
+    const content = renderTemplateByName('windsurf-rules', context);
+
+    // Create .windsurf directory if it doesn't exist
+    const windsurfDir = path.dirname(rulesPath);
+    if (!fs.existsSync(windsurfDir)) {
+      fs.mkdirSync(windsurfDir, { recursive: true });
+    }
+
+    // Write output file
+    fs.writeFileSync(rulesPath, content, 'utf-8');
+
+    result.success = true;
+    result.files.push({
+      path: rulesPath,
+      relativePath: '.windsurf/rules.md',
+      size: content.length
+    });
+  } catch (error) {
+    result.errors.push({
+      message: error.message,
+      stack: error.stack
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Validate Windsurf output
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Validation result
+ */
+function validate(projectRoot) {
+  const issues = [];
+  const rulesPath = getOutputPath(projectRoot);
+
+  if (!fs.existsSync(rulesPath)) {
+    issues.push({ file: '.windsurf/rules.md', error: 'not found' });
+  } else {
+    const content = fs.readFileSync(rulesPath, 'utf-8');
+    const placeholderMatch = content.match(/\{\{[A-Z_]+\}\}/g);
+    if (placeholderMatch && placeholderMatch.length > 0) {
+      issues.push({
+        file: '.windsurf/rules.md',
+        error: `Found ${placeholderMatch.length} unreplaced placeholders`
+      });
+    }
+  }
+
+  return {
+    valid: issues.filter(i => i.severity !== 'warning').length === 0,
+    issues
+  };
+}
+
+module.exports = {
+  ...adapter,
+  getOutputPath,
+  exists,
+  generate,
+  validate
+};

package/lib/ai-orchestrator.js

@@ -303,7 +303,8 @@ function getPackageVersion() {
     const pkgPath = path.join(__dirname, '..', 'package.json');
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     return pkg.version || '1.0.0';
-  } catch {
+  } catch (error) {
+    // Silently fall back to default version
     return '1.0.0';
   }
 }

package/lib/content-preservation.js

@@ -0,0 +1,243 @@
+/**
+ * Content Preservation Module
+ * Handles migration and preservation of custom content during context generation
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Find custom content in .claude/ directory
+ * Custom content = files without "MANAGED BY" header
+ * @param {string} claudeDir - Path to .claude/ directory
+ * @returns {Array} List of custom content items
+ */
+function findCustomContentInClaude(claudeDir) {
+  const custom = [];
+
+  const walkDir = (dir, depth = 0) => {
+    // Limit depth to avoid infinite recursion
+    if (depth > 10) return;
+
+    if (!fs.existsSync(dir)) {
+      return;
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        // Skip node_modules and other common dirs
+        if (entry.name === 'node_modules' || entry.name === '.git') {
+          continue;
+        }
+        walkDir(path.join(dir, entry.name), depth + 1);
+      } else if (entry.name.endsWith('.md')) {
+        const filePath = path.join(dir, entry.name);
+        try {
+          const content = fs.readFileSync(filePath, 'utf-8');
+
+          // Check if file has managed header
+          if (!content.includes('MANAGED BY CREATE-AI-CONTEXT') &&
+              !content.includes('Auto-generated by AI Context Engineering')) {
+            const relPath = path.relative(claudeDir, filePath);
+            custom.push({
+              path: relPath,
+              type: determineContentType(relPath),
+              content: content
+            });
+          }
+        } catch (err) {
+          // Skip unreadable files
+        }
+      }
+    }
+  };
+
+  walkDir(claudeDir);
+  return custom;
+}
+
+/**
+ * Determine content type from path
+ * @param {string} relPath - Relative path from .claude/
+ * @returns {string} Content type
+ */
+function determineContentType(relPath) {
+  // Normalize path separators to forward slashes for cross-platform compatibility
+  const normalizedPath = relPath.replace(/\\/g, '/');
+
+  if (normalizedPath.startsWith('agents/')) return 'agent';
+  if (normalizedPath.startsWith('commands/')) return 'command';
+  if (normalizedPath.startsWith('context/')) return 'context';
+  if (normalizedPath.startsWith('workflows/')) return 'workflow';
+  if (normalizedPath.startsWith('schemas/')) return 'schema';
+  if (normalizedPath.startsWith('standards/')) return 'standard';
+  return 'other';
+}
+
+/**
+ * Migrate custom content to .ai-context/custom/
+ * @param {string} claudeDir - Source .claude/ directory
+ * @param {string} aiContextDir - Destination .ai-context/ directory
+ * @param {Array} customItems - Items to migrate
+ * @returns {Array} List of migrated items with paths
+ */
+function migrateCustomContent(claudeDir, aiContextDir, customItems) {
+  const customDir = path.join(aiContextDir, 'custom');
+  fs.mkdirSync(customDir, { recursive: true });
+
+  const migrated = [];
+
+  for (const item of customItems) {
+    const destPath = path.join(customDir, item.path);
+    const destDir = path.dirname(destPath);
+
+    try {
+      fs.mkdirSync(destDir, { recursive: true });
+
+      // Add preservation header
+      const preservedHeader = `<!--
+PRESERVED FROM .claude/${item.path}
+This file was migrated from .claude/ to .ai-context/custom/ to preserve custom content.
+Original migration date: ${new Date().toISOString()}
+-->
+`;
+
+      fs.writeFileSync(destPath, preservedHeader + item.content);
+
+      migrated.push({
+        original: `.claude/${item.path}`,
+        destination: `.ai-context/custom/${item.path}`,
+        type: item.type
+      });
+    } catch (err) {
+      // Log error but continue with other files
+      console.warn(`Failed to migrate ${item.path}: ${err.message}`);
+    }
+  }
+
+  return migrated;
+}
+
+/**
+ * Detect custom content markers in a file
+ * @param {string} content - File content
+ * @returns {boolean} True if content has custom markers
+ */
+function detectCustomContent(content) {
+  // Check for absence of managed marker
+  if (!content || content.length === 0) {
+    return false;
+  }
+
+  const hasManagedMarker = content.includes('MANAGED BY CREATE-AI-CONTEXT') ||
+                          content.includes('Auto-generated by AI Context Engineering') ||
+                          content.includes('Managed by create-ai-context') ||
+                          content.includes('CREATE-AI-CONTEXT');
+
+  if (!hasManagedMarker) {
+    return true;
+  }
+
+  // Check for custom edit markers
+  if (content.includes('<!-- CUSTOM EDIT -->') ||
+      content.includes('# CUSTOM EDIT') ||
+      content.includes('<!-- USER CUSTOM -->')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Find custom files in .agent/ directory
+ * @param {string} agentDir - Path to .agent/ directory
+ * @returns {Array} List of custom file paths (relative)
+ */
+function findCustomFilesInAgent(agentDir) {
+  const custom = [];
+
+  if (!fs.existsSync(agentDir)) {
+    return custom;
+  }
+
+  const walkDir = (dir, depth = 0) => {
+    if (depth > 10) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== '.git') {
+          walkDir(path.join(dir, entry.name), depth + 1);
+        }
+      } else if (entry.name.endsWith('.md')) {
+        const filePath = path.join(dir, entry.name);
+        try {
+          const content = fs.readFileSync(filePath, 'utf-8');
+
+          if (!content.includes('Auto-generated by AI Context Engineering') &&
+              !content.includes('Auto-generated by AI Context Engineering v2')) {
+            const relPath = path.relative(agentDir, filePath);
+            custom.push(relPath);
+          }
+        } catch (err) {
+          // Skip unreadable files
+        }
+      }
+    }
+  };
+
+  walkDir(agentDir);
+  return custom;
+}
+
+/**
+ * Backup existing files before migration
+ * @param {string} filePath - File to backup
+ * @returns {string} Backup file path
+ */
+function backupFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const backupPath = filePath + '.backup.' + Date.now();
+  try {
+    fs.copyFileSync(filePath, backupPath);
+    return backupPath;
+  } catch (err) {
+    console.warn(`Failed to create backup of ${filePath}: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Restore from backup
+ * @param {string} backupPath - Backup file path
+ * @returns {boolean} True if restored successfully
+ */
+function restoreFromBackup(backupPath) {
+  if (!fs.existsSync(backupPath)) {
+    return false;
+  }
+
+  const originalPath = backupPath.replace(/\.backup\.\d+$/, '');
+  try {
+    fs.copyFileSync(backupPath, originalPath);
+    fs.unlinkSync(backupPath);
+    return true;
+  } catch (err) {
+    console.warn(`Failed to restore from backup ${backupPath}: ${err.message}`);
+    return false;
+  }
+}
+
+module.exports = {
+  findCustomContentInClaude,
+  migrateCustomContent,
+  detectCustomContent,
+  findCustomFilesInAgent,
+  determineContentType,
+  backupFile,
+  restoreFromBackup
+};

package/lib/index.js

@@ -77,7 +77,11 @@ async function run(options = {}) {
     mode = 'merge',  // 'merge' | 'overwrite' | 'interactive'
     preserveCustom = true,
     updateRefs = false,
-    backup = false
+    backup = false,
+    // Force flag
+    force = false,
+    // Placeholder validation
+    failOnUnreplaced = false
   } = options;
 
   // Determine target directory
@@ -267,9 +271,11 @@ async function run(options = {}) {
   const placeholdersReplaced = await replacePlaceholders(targetDir, {
     ...config,
     techStack,
-    analysis
+    analysis,
+    failOnUnreplaced: config.failOnUnreplaced,
+    verbose: config.verbose
   });
-  spinner.succeed(`Replaced ${placeholdersReplaced} placeholders`);
+  spinner.succeed(`Replaced ${placeholdersReplaced.totalReplaced} placeholders`);
 
   // Phase 10: AI Orchestration (if in Claude Code environment)
   if (env.mode === 'full-ai' || env.mode === 'hybrid') {
@@ -289,7 +295,8 @@ async function run(options = {}) {
   try {
     generationResults = await generateAllContexts(analysis, config, targetDir, {
       aiTools: config.aiTools,
-      verbose: config.verbose
+      verbose: config.verbose,
+      force: config.force || false
     });
     const toolsGenerated = generationResults.generated.map(g => g.adapter).join(', ');
     if (generationResults.success) {

package/lib/placeholder.js

@@ -7,6 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const { glob } = require('glob');
+const chalk = require('chalk');
 
 /**
  * Context directory and file names
@@ -463,7 +464,16 @@ function capitalize(str) {
 /**
  * Replace placeholders in all files in a directory
  */
+/**
+ * Replace all placeholders in all files
+ * @param {string} targetDir - Target directory
+ * @param {object} config - Configuration options
+ * @param {boolean} config.failOnUnreplaced - Throw if placeholders remain
+ * @param {boolean} config.verbose - Log warnings for unreplaced placeholders
+ * @returns {object} Results { totalReplaced: number, unreplaced: Array, unreplacedCount: number }
+ */
 async function replacePlaceholders(targetDir, config = {}) {
+  const { failOnUnreplaced = false, verbose = false } = config;
   const contextDir = path.join(targetDir, AI_CONTEXT_DIR);
   const values = getDefaultValues(config, config.techStack || {}, config.analysis || {});
 
@@ -476,6 +486,7 @@ async function replacePlaceholders(targetDir, config = {}) {
   });
 
   let totalReplaced = 0;
+  const unreplacedDetails = [];
 
   for (const filePath of files) {
     try {
@@ -492,6 +503,10 @@ async function replacePlaceholders(targetDir, config = {}) {
         fs.writeFileSync(filePath, content, 'utf8');
         totalReplaced++;
       }
+
+      // Check for remaining placeholders
+      const remaining = findPlaceholdersInContent(content, filePath);
+      unreplacedDetails.push(...remaining);
     } catch (error) {
       // Skip files that can't be read
     }
@@ -513,12 +528,78 @@ async function replacePlaceholders(targetDir, config = {}) {
         fs.writeFileSync(aiContextPath, content, 'utf8');
         totalReplaced++;
       }
+
+      // Check for remaining placeholders
+      const remaining = findPlaceholdersInContent(content, aiContextPath);
+      unreplacedDetails.push(...remaining);
     } catch (error) {
       // Skip if can't read
     }
   }
 
-  return totalReplaced;
+  // Deduplicate unreplaced items
+  const uniqueUnreplaced = deduplicateUnreplaced(unreplacedDetails);
+  const unreplacedCount = uniqueUnreplaced.length;
+
+  // Handle unreplaced placeholders
+  if (unreplacedCount > 0) {
+    const placeholders = uniqueUnreplaced.map(u => u.placeholder).join(', ');
+    const message = `${unreplacedCount} placeholder${unreplacedCount > 1 ? 's' : ''} not replaced: ${placeholders}`;
+
+    if (verbose) {
+      console.warn(chalk.yellow(`⚠ ${message}`));
+      uniqueUnreplaced.forEach(u => {
+        console.warn(chalk.gray(`  - ${u.placeholder} in ${u.file}`));
+      });
+    }
+
+    if (failOnUnreplaced) {
+      throw new Error(message);
+    }
+  }
+
+  return { totalReplaced, unreplaced: uniqueUnreplaced, unreplacedCount };
+}
+
+/**
+ * Find placeholders in content (helper for replacePlaceholders)
+ * @param {string} content - File content
+ * @param {string} filePath - File path
+ * @returns {Array} List of unreplaced placeholder info
+ */
+function findPlaceholdersInContent(content, filePath) {
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+  const found = [];
+  let match;
+
+  while ((match = placeholderPattern.exec(content)) !== null) {
+    found.push({
+      placeholder: match[0],
+      name: match[1],
+      file: path.relative(process.cwd(), filePath),
+      index: match.index,
+      known: KNOWN_PLACEHOLDERS.hasOwnProperty(match[1])
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Deduplicate unreplaced placeholder list
+ * @param {Array} unreplaced - List of unreplaced items
+ * @returns {Array} Deduplicated list
+ */
+function deduplicateUnreplaced(unreplaced) {
+  const seen = new Set();
+  return unreplaced.filter(item => {
+    const key = `${item.placeholder}:${item.file}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
 }
 
 /**

package/lib/template-coordination.js

@@ -0,0 +1,148 @@
+/**
+ * Tool Coordination Module
+ * Helpers for adding tool awareness to generated content
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Get tool coordination header
+ * @param {string} toolName - Name of the tool (claude, copilot, cline, antigravity)
+ * @param {string} version - Version of create-ai-context
+ * @returns {string} Header comment for the tool
+ */
+function getToolCoordinationHeader(toolName, version) {
+  version = version || '2.3.0';
+
+  const newline = '\n';
+  const htmlHeaderBase = '<!-- ========================================= -->';
+  const htmlFooterBase = '<!-- ========================================= -->';
+  const hashHeaderBase = '# ==========================================';
+  const hashFooterBase = '# ==========================================';
+
+  const headers = {
+    claude: [
+      htmlHeaderBase,
+      '<!-- WARNING: CLAUDE CODE CONTEXT -->',
+      '<!-- Managed by create-ai-context v' + version + ' -->',
+      '<!-- Source: .ai-context/ directory -->',
+      htmlFooterBase
+    ].join(newline),
+
+    copilot: [
+      htmlHeaderBase,
+      '<!-- WARNING: GITHUB COPILOT INSTRUCTIONS -->',
+      '<!-- Managed by create-ai-context v' + version + ' -->',
+      '<!-- Source: .ai-context/ directory -->',
+      htmlFooterBase
+    ].join(newline),
+
+    cline: [
+      hashHeaderBase,
+      '# WARNING: CLINE RULES',
+      '# Managed by create-ai-context v' + version,
+      '# Source: .ai-context/ directory',
+      hashFooterBase
+    ].join(newline),
+
+    antigravity: [
+      htmlHeaderBase,
+      '<!-- WARNING: ANTIGRAVITY CONTEXT -->',
+      '<!-- Managed by create-ai-context v' + version + ' -->',
+      '<!-- Source: .ai-context/ directory -->',
+      htmlFooterBase
+    ].join(newline)
+  };
+
+  return headers[toolName] || '';
+}
+
+/**
+ * Get tool coordination footer
+ * @param {string} toolName - Name of the tool
+ * @returns {string} Footer content with cross-tool references
+ */
+function getToolCoordinationFooter(toolName) {
+  const footer = '---\n' +
+    '## Universal Context Directory\n\n' +
+    'This project uses **AI Context Engineering** for coordinated documentation across all AI tools.\n\n' +
+    '**Universal Source:** .ai-context/\n\n' +
+    '**Related Tool Contexts:**\n' +
+    '- Claude Code: `AI_CONTEXT.md`\n' +
+    '- GitHub Copilot: `.github/copilot-instructions.md`\n' +
+    '- Cline: `.clinerules`\n' +
+    '- Antigravity: `.agent/`\n\n' +
+    '**Regeneration Command:**\n' +
+    '```bash\n' +
+    'npx create-ai-context generate --ai ' + toolName + '\n```\n\n' +
+    '**To Modify Documentation:**\n' +
+    'Edit source files in .ai-context/ then regenerate.\n';
+
+  return footer;
+}
+
+/**
+ * Check if file is managed by create-ai-context
+ * @param {string} filePath - Path to file to check
+ * @returns {boolean} True if file is managed by create-ai-context
+ */
+function isManagedFile(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return false;
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return content.includes('Managed by create-ai-context') ||
+           content.includes('CREATE-AI-CONTEXT') ||
+           content.includes('Auto-generated by AI Context Engineering');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get universal context reference for templates
+ * @returns {object} Object with context directory info
+ */
+function getUniversalContextReference() {
+  return {
+    directory: '.ai-context',
+    description: 'Universal AI Context Engineering directory',
+    subdirectories: {
+      agents: '.ai-context/agents/',
+      commands: '.ai-context/commands/',
+      context: '.ai-context/context/',
+      indexes: '.ai-context/indexes/',
+      custom: '.ai-context/custom/',
+      tools: '.ai-context/tools/'
+    },
+    mainFile: 'AI_CONTEXT.md',
+    workflowIndex: '.ai-context/context/WORKFLOW_INDEX.md',
+    rpiPlan: '.ai-context/RPI_WORKFLOW_PLAN.md'
+  };
+}
+
+/**
+ * Format tool coordination message for CLI output
+ * @param {string} toolName - Name of the tool
+ * @returns {string} Formatted message
+ */
+function formatCoordinationMessage(toolName) {
+  const messages = {
+    claude: 'Claude Code context generated. Symlinks created from .ai-context/',
+    copilot: 'Copilot instructions generated from .ai-context/ universal context',
+    cline: 'Cline rules generated from .ai-context/ universal context',
+    antigravity: 'Antigravity context generated from .ai-context/ universal context'
+  };
+
+  return messages[toolName] || toolName + ' context generated';
+}
+
+module.exports = {
+  getToolCoordinationHeader,
+  getToolCoordinationFooter,
+  isManagedFile,
+  getUniversalContextReference,
+  formatCoordinationMessage
+};