create-universal-ai-context 2.2.2 → 2.4.0

package/bin/create-ai-context.js

@@ -89,6 +89,8 @@ program
   .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')
+  .option('-f, --force', 'Force overwrite of existing custom files (use with caution)')
+  .option('--fail-on-unreplaced', 'Error if any placeholders remain unreplaced')
   .action(async (projectName, options) => {
     console.log(banner);
 
@@ -118,7 +120,10 @@ program
         mode: options.mode,
         preserveCustom: options.preserveCustom,
         updateRefs: options.updateRefs,
-        backup: options.backup
+        backup: options.backup,
+        force: options.force || false,
+        // Placeholder validation
+        failOnUnreplaced: options.failOnUnreplaced || false
       });
     } catch (error) {
       console.error(chalk.red('\n✖ Error:'), error.message);
@@ -137,6 +142,7 @@ program
   .option('-d, --dryRun', 'Show what would be done without making changes')
   .option('-v, --verbose', 'Show detailed output')
   .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .option('-f, --force', 'Force overwrite of existing custom files (use with caution)')
   .action(async (options) => {
     console.log(banner);
 
@@ -169,7 +175,8 @@ program
       const config = {
         projectName: path.basename(projectRoot),
         aiTools,
-        verbose: options.verbose
+        verbose: options.verbose,
+        force: options.force || false
       };
 
       if (options.dryRun) {

package/lib/adapters/aider.js

@@ -0,0 +1,131 @@
+/**
+ * Aider Adapter
+ *
+ * Generates .aider.conf.yml file for Aider AI pair-programmer
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { renderTemplateByName, buildContext } = require('../template-renderer');
+const { isManagedFile } = require('../template-coordination');
+
+/**
+ * Adapter metadata
+ */
+const adapter = {
+  name: 'aider',
+  displayName: 'Aider',
+  description: 'Configuration file for Aider AI pair-programmer',
+  outputType: 'single-file',
+  outputPath: '.aider.conf.yml'
+};
+
+/**
+ * Get output path for Aider config file
+ * @param {string} projectRoot - Project root directory
+ * @returns {string} Output file path
+ */
+function getOutputPath(projectRoot) {
+  return path.join(projectRoot, '.aider.conf.yml');
+}
+
+/**
+ * Check if Aider output already exists
+ * @param {string} projectRoot - Project root directory
+ * @returns {boolean}
+ */
+function exists(projectRoot) {
+  const configPath = getOutputPath(projectRoot);
+  return fs.existsSync(configPath);
+}
+
+/**
+ * Generate Aider config 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 configPath = getOutputPath(projectRoot);
+
+    // Check if file exists and is custom (not managed by us)
+    if (fs.existsSync(configPath) && !config.force) {
+      if (!isManagedFile(configPath)) {
+        result.errors.push({
+          message: '.aider.conf.yml 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, 'aider');
+
+    // Render template
+    const content = renderTemplateByName('aider-config', context);
+
+    // Write output file
+    fs.writeFileSync(configPath, content, 'utf-8');
+
+    result.success = true;
+    result.files.push({
+      path: configPath,
+      relativePath: '.aider.conf.yml',
+      size: content.length
+    });
+  } catch (error) {
+    result.errors.push({
+      message: error.message,
+      stack: error.stack
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Validate Aider output
+ * @param {string} projectRoot - Project root directory
+ * @returns {object} Validation result
+ */
+function validate(projectRoot) {
+  const issues = [];
+  const configPath = getOutputPath(projectRoot);
+
+  if (!fs.existsSync(configPath)) {
+    issues.push({ file: '.aider.conf.yml', error: 'not found' });
+  } else {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const placeholderMatch = content.match(/\{\{[A-Z_]+\}\}/g);
+    if (placeholderMatch && placeholderMatch.length > 0) {
+      issues.push({
+        file: '.aider.conf.yml',
+        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/adapters/antigravity.js

@@ -7,6 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const { renderMultiFileTemplate, buildContext } = require('../template-renderer');
+const { isManagedFile } = require('../template-coordination');
 
 /**
  * Adapter metadata
@@ -53,8 +54,23 @@ async function generate(analysis, config, projectRoot) {
   };
 
   try {
+    const outputDir = getOutputPath(projectRoot);
+
+    // Check if .agent/ directory exists and contains custom files
+    if (fs.existsSync(outputDir) && !config.force) {
+      const hasCustomFiles = checkForCustomFiles(outputDir);
+      if (hasCustomFiles) {
+        result.errors.push({
+          message: '.agent/ directory exists and contains custom files. Use --force to overwrite.',
+          code: 'EXISTS_CUSTOM',
+          severity: 'error'
+        });
+        return result;
+      }
+    }
+
     // Build context from analysis
-    const context = buildContext(analysis, config);
+    const context = buildContext(analysis, config, 'antigravity');
 
     // Get template path
     const templatePath = path.join(__dirname, '..', '..', 'templates', 'handlebars', 'antigravity.hbs');
@@ -63,7 +79,6 @@ async function generate(analysis, config, projectRoot) {
     const files = renderMultiFileTemplate(templatePath, context);
 
     // Create output directory
-    const outputDir = getOutputPath(projectRoot);
     if (!fs.existsSync(outputDir)) {
       fs.mkdirSync(outputDir, { recursive: true });
     }
@@ -99,6 +114,36 @@ async function generate(analysis, config, projectRoot) {
   return result;
 }
 
+/**
+ * Check if directory contains custom (non-managed) files
+ * @param {string} dir - Directory to check
+ * @returns {boolean} True if custom files found
+ */
+function checkForCustomFiles(dir) {
+  const walkDir = (currentDir, depth = 0) => {
+    if (depth > 10) return false;
+
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== '.git') {
+          if (walkDir(path.join(currentDir, entry.name), depth + 1)) {
+            return true;
+          }
+        }
+      } else if (entry.name.endsWith('.md')) {
+        const filePath = path.join(currentDir, entry.name);
+        if (!isManagedFile(filePath)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  };
+
+  return walkDir(dir);
+}
+
 /**
  * Validate Antigravity output
  * @param {string} projectRoot - Project root directory

package/lib/adapters/claude.js

@@ -8,6 +8,8 @@
 const fs = require('fs');
 const path = require('path');
 const { renderTemplateByName, buildContext } = require('../template-renderer');
+const { isManagedFile } = require('../template-coordination');
+const { findCustomContentInClaude, migrateCustomContent } = require('../content-preservation');
 
 /**
  * Adapter metadata
@@ -56,24 +58,51 @@ async function generate(analysis, config, projectRoot) {
   };
 
   try {
-    // 1. Generate AI_CONTEXT.md at project root (existing behavior)
-    const context = buildContext(analysis, config);
-    const content = renderTemplateByName('claude', context);
+    // 1. Generate AI_CONTEXT.md at project root
     const outputPath = getOutputPath(projectRoot);
-    fs.writeFileSync(outputPath, content, 'utf-8');
-    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);
+    // Check if file exists and is custom (not managed by us)
+    if (fs.existsSync(outputPath) && !config.force) {
+      if (!isManagedFile(outputPath)) {
+        result.errors.push({
+          message: 'AI_CONTEXT.md exists and appears to be custom. Use --force to overwrite.',
+          code: 'EXISTS_CUSTOM',
+          severity: 'error'
+        });
+        // Don't return early - still try to generate .claude/ directory
+      } else {
+        // File is managed by us, safe to overwrite
+        const context = buildContext(analysis, config, 'claude');
+        const content = renderTemplateByName('claude', context);
+        fs.writeFileSync(outputPath, content, 'utf-8');
+        result.files.push({
+          path: outputPath,
+          relativePath: 'AI_CONTEXT.md',
+          size: content.length
+        });
+      }
+    } else {
+      // File doesn't exist or force is enabled
+      const context = buildContext(analysis, config, 'claude');
+      const content = renderTemplateByName('claude', context);
+      fs.writeFileSync(outputPath, content, 'utf-8');
+      result.files.push({
+        path: outputPath,
+        relativePath: 'AI_CONTEXT.md',
+        size: content.length
+      });
+    }
+
+    // 2. Generate .claude/ directory structure
+    const context = buildContext(analysis, config, 'claude');
+    const claudeDirResult = await generateClaudeDirectory(projectRoot, context, config, result);
     if (claudeDirResult) {
       result.files.push(...claudeDirResult);
     }
 
-    result.success = result.errors.length === 0 || result.errors.some(e => e.code === 'EXISTS');
+    // Success if no actual errors (warnings and info are OK)
+    result.success = result.errors.length === 0 ||
+      result.errors.every(e => e.code === 'EXISTS' || e.severity === 'info' || e.severity === 'warning');
   } catch (error) {
     result.errors.push({
       message: error.message,
@@ -85,59 +114,101 @@ async function generate(analysis, config, projectRoot) {
 }
 
 /**
- * Generate .claude/ directory with full structure
+ * Generate .claude/ directory with symlinks to .ai-context/
  * @param {string} projectRoot - Project root directory
  * @param {object} context - Template context
+ * @param {object} config - Configuration from CLI
  * @param {object} result - Result object to track files/errors
  * @returns {Array} List of generated files
  */
-async function generateClaudeDirectory(projectRoot, context, result) {
+async function generateClaudeDirectory(projectRoot, context, config, result) {
   const { copyDirectory } = require('../installer');
   const templatesDir = path.join(__dirname, '..', '..', 'templates', 'base');
+  const aiContextDir = path.join(projectRoot, '.ai-context');
   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
-    }];
+  // Check for existing .claude/ directory
+  if (fs.existsSync(claudeDir) && !config.force) {
+    // Check if it has custom files
+    const hasCustomFiles = checkForCustomFiles(claudeDir);
+    if (hasCustomFiles) {
+      // Migrate custom content before skipping
+      const customItems = findCustomContentInClaude(claudeDir);
+      if (customItems.length > 0) {
+        const migrated = migrateCustomContent(claudeDir, aiContextDir, customItems);
+        result.errors.push({
+          message: `Migrated ${migrated.length} custom items from .claude/ to .ai-context/custom/`,
+          code: 'MIGRATED_CUSTOM',
+          severity: 'info',
+          migratedItems: migrated
+        });
+      }
+
+      result.errors.push({
+        message: '.claude/ directory exists and contains custom files. Use --force to overwrite. Skipping directory generation.',
+        code: 'EXISTS_CUSTOM',
+        severity: 'warning'
+      });
+      return [{
+        path: claudeDir,
+        relativePath: '.claude/',
+        size: 0,
+        skipped: true
+      }];
+    }
+    // Directory exists but only has managed files, we can regenerate
   }
 
   try {
     // Create .claude/ directory
     fs.mkdirSync(claudeDir, { recursive: true });
 
-    // Copy relevant subdirectories from templates/base to .claude/
-    const subdirsToCopy = [
+    // Subdirectories to symlink from .ai-context/
+    const subdirsToLink = [
       'agents',
       'commands',
       'indexes',
       'context',
       'schemas',
-      'standards'
+      'standards',
+      'tools'
     ];
 
-    // Only copy tools if explicitly enabled
-    if (context.features?.tools !== false) {
-      subdirsToCopy.push('tools');
-    }
-
+    let linksCreated = 0;
     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;
+
+    for (const subdir of subdirsToLink) {
+      const srcPath = path.join(aiContextDir, subdir);
+      const destPath = path.join(claudeDir, subdir);
+
+      // Skip if source doesn't exist
+      if (!fs.existsSync(srcPath)) {
+        continue;
+      }
+
+      // Try to create symlink, fallback to copy
+      try {
+        // Remove dest if it exists (shouldn't, but safety)
+        if (fs.existsSync(destPath)) {
+          if (fs.lstatSync(destPath).isSymbolicLink()) {
+            fs.unlinkSync(destPath);
+          } else {
+            // Existing directory, skip
+            continue;
+          }
+        }
+
+        // Create symlink
+        fs.symlinkSync(srcPath, destPath, 'junction');
+        linksCreated++;
+      } catch (symlinkError) {
+        // Symlink failed (likely Windows permissions or filesystem limitation)
+        // Fallback: copy directory contents
+        if (!fs.existsSync(destPath)) {
+          fs.mkdirSync(destPath, { recursive: true });
+          const count = await copyDirectory(srcPath, destPath);
+          filesCopied += count;
+        }
       }
     }
 
@@ -145,7 +216,7 @@ async function generateClaudeDirectory(projectRoot, context, result) {
     const settingsPath = path.join(claudeDir, 'settings.json');
     const settings = {
       '$schema': './schemas/settings.schema.json',
-      version: '2.1.0',
+      version: '2.2.2',
       project: {
         name: context.project?.name || 'Project',
         tech_stack: context.project?.tech_stack || 'Not detected'
@@ -170,7 +241,26 @@ async function generateClaudeDirectory(projectRoot, context, result) {
     const readmePath = path.join(claudeDir, 'README.md');
     const readme = `# .claude Configuration - ${context.project?.name || 'Project'}
 
-This directory contains Claude Code-specific context engineering files.
+This directory provides Claude Code with auto-discovered commands, agents, and configuration.
+
+## Architecture
+
+This directory uses **symlinks** to \`../.ai-context/\` for all shared content:
+
+\`\`\`
+.claude/
+├── agents       → ../.ai-context/agents/
+├── commands     → ../.ai-context/commands/
+├── indexes      → ../.ai-context/indexes/
+├── context      → ../.ai-context/context/
+├── schemas      → ../.ai-context/schemas/
+├── standards    → ../.ai-context/standards/
+├── tools        → ../.ai-context/tools/
+├── settings.json (this file - Claude-specific)
+└── README.md (this file)
+\`\`\`
+
+**Single source of truth:** All content lives in \`.ai-context/\`. Edit there, not here.
 
 ## Quick Start
 
@@ -182,22 +272,26 @@ This directory contains Claude Code-specific context engineering files.
 
 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'}*
+*Generated by create-universal-ai-context v${context.version || '2.3.0'}*
 `;
     fs.writeFileSync(readmePath, readme);
     filesCopied++;
 
+    // Add info message about symlink approach
+    if (linksCreated > 0) {
+      result.errors.push({
+        message: `Created ${linksCreated} symlinks from .claude/ to .ai-context/ (single source of truth)`,
+        code: 'SYMLINKS_CREATED',
+        severity: 'info'
+      });
+    }
+
     return [{
       path: claudeDir,
       relativePath: '.claude/',
-      size: filesCopied
+      size: filesCopied,
+      symlinks: linksCreated,
+      details: `${linksCreated} symlinks, ${filesCopied} files`
     }];
 
   } catch (error) {
@@ -209,6 +303,36 @@ See \`AI_CONTEXT.md\` at project root for universal AI context (works with all t
   }
 }
 
+/**
+ * Check if directory contains custom (non-managed) files
+ * @param {string} dir - Directory to check
+ * @returns {boolean} True if custom files found
+ */
+function checkForCustomFiles(dir) {
+  const walkDir = (currentDir, depth = 0) => {
+    if (depth > 10) return false;
+
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (entry.name !== 'node_modules' && entry.name !== '.git') {
+          if (walkDir(path.join(currentDir, entry.name), depth + 1)) {
+            return true;
+          }
+        }
+      } else if (entry.name.endsWith('.md')) {
+        const filePath = path.join(currentDir, entry.name);
+        if (!isManagedFile(filePath)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  };
+
+  return walkDir(dir);
+}
+
 /**
  * Validate Claude output
  * @param {string} projectRoot - Project root directory

package/lib/adapters/cline.js

@@ -7,6 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const { renderTemplateByName, buildContext } = require('../template-renderer');
+const { isManagedFile } = require('../template-coordination');
 
 /**
  * Adapter metadata
@@ -53,14 +54,27 @@ async function generate(analysis, config, projectRoot) {
   };
 
   try {
+    const outputPath = getOutputPath(projectRoot);
+
+    // Check if file exists and is custom (not managed by us)
+    if (fs.existsSync(outputPath) && !config.force) {
+      if (!isManagedFile(outputPath)) {
+        result.errors.push({
+          message: '.clinerules 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);
+    const context = buildContext(analysis, config, 'cline');
 
     // Render template
     const content = renderTemplateByName('cline', context);
 
     // Write output file
-    const outputPath = getOutputPath(projectRoot);
     fs.writeFileSync(outputPath, content, 'utf-8');
 
     result.success = true;