create-universal-ai-context 2.0.0 → 2.1.0

package/lib/index.js

@@ -21,7 +21,7 @@
 const path = require('path');
 const fs = require('fs');
 const chalk = require('chalk');
-const { runPrompts, getDefaults } = require('./prompts');
+const { runPrompts, getDefaults, runDiscoveryPrompts } = require('./prompts');
 const { createSpinner } = require('./spinner');
 const {
   createDirectoryStructure,
@@ -45,6 +45,13 @@ const {
 const { populateAllTemplates } = require('./template-populator');
 const { generateAll: generateAllContexts, getSupportedTools } = require('./ai-context-generator');
 
+// Documentation discovery for existing docs detection
+const {
+  discoverExistingDocs,
+  formatDiscoverySummary,
+  buildMergedValues
+} = require('./doc-discovery');
+
 /**
  * Main entry point
  */
@@ -65,7 +72,12 @@ async function run(options = {}) {
     analyzeOnly = false,
     // Monorepo options
     monorepo = false,
-    federate = false
+    federate = false,
+    // Merge options (new)
+    mode = 'merge',  // 'merge' | 'overwrite' | 'interactive'
+    preserveCustom = true,
+    updateRefs = false,
+    backup = false
   } = options;
 
   // Determine target directory
@@ -76,12 +88,70 @@ async function run(options = {}) {
   const projectNameResolved = projectName || path.basename(targetDir);
   const contextDir = path.join(targetDir, AI_CONTEXT_DIR);
 
-  // Get configuration (prompts or defaults)
+  const spinner = createSpinner();
+
+  // ========================================
+  // Phase 0: Documentation Discovery
+  // ========================================
+  spinner.start('Scanning for existing documentation...');
+  let discovery = null;
+  let mergeStrategy = mode;
+  let discoveredValues = {};
+
+  try {
+    discovery = await discoverExistingDocs(targetDir);
+
+    if (discovery.hasExistingDocs) {
+      spinner.succeed('Found existing documentation');
+
+      if (verbose) {
+        console.log(chalk.gray(formatDiscoverySummary(discovery)));
+      }
+
+      // Handle discovery based on mode and prompts
+      if (!skipPrompts && mode !== 'overwrite') {
+        // Run discovery prompts
+        const discoveryAnswers = await runDiscoveryPrompts(discovery);
+
+        if (discoveryAnswers.existingDocsStrategy === 'skip') {
+          console.log(chalk.yellow('\nInitialization cancelled by user.\n'));
+          return;
+        }
+
+        mergeStrategy = discoveryAnswers.existingDocsStrategy;
+        discoveredValues = buildMergedValues(
+          discovery,
+          mergeStrategy,
+          discoveryAnswers.conflictResolutions || {}
+        );
+      } else if (mode === 'merge') {
+        // Auto-merge without prompts
+        discoveredValues = buildMergedValues(discovery, 'merge', {});
+      }
+
+      // Show what we're doing
+      if (mergeStrategy === 'merge') {
+        const valueCount = Object.keys(discoveredValues).length;
+        console.log(chalk.cyan(`  Preserving ${valueCount} values from existing docs`));
+      } else if (mergeStrategy === 'overwrite') {
+        console.log(chalk.yellow('  Overwrite mode: existing docs will be replaced'));
+      }
+    } else {
+      spinner.succeed('No existing documentation found - starting fresh');
+    }
+  } catch (error) {
+    spinner.warn(`Discovery partial: ${error.message}`);
+    discovery = { hasExistingDocs: false };
+  }
+
+  // ========================================
+  // Phase 1: Configuration (prompts or defaults)
+  // ========================================
   let config;
   if (skipPrompts) {
     config = await getDefaults(targetDir, template);
   } else {
-    config = await runPrompts(targetDir, template);
+    config = await runPrompts(targetDir, template, discovery);
   }
 
   config.projectName = projectNameResolved;
@@ -92,16 +162,28 @@ async function run(options = {}) {
   config.verbose = verbose;
   config.aiTools = aiTools;
   config.monorepo = monorepo;
+  // Add merge config
+  config.mergeStrategy = mergeStrategy;
+  config.preserveCustom = preserveCustom;
+  config.updateRefs = updateRefs;
+  config.backup = backup;
+  config.discoveredValues = discoveredValues;
+  config.discovery = discovery;
 
   if (dryRun) {
     console.log(chalk.yellow('\n--dry-run mode: No changes will be made\n'));
     console.log('Configuration:', JSON.stringify(config, null, 2));
+    if (discovery?.hasExistingDocs) {
+      console.log('\nDiscovery:', JSON.stringify({
+        tools: discovery.tools,
+        extractedValues: discovery.extractedValues,
+        conflicts: discovery.conflicts
+      }, null, 2));
+    }
     return;
   }
 
-  // Phase 1: Create target directory if needed
-  const spinner = createSpinner();
-
+  // Phase 2: Create target directory if needed
   if (projectName && !fs.existsSync(targetDir)) {
     spinner.start('Creating project directory...');
     fs.mkdirSync(targetDir, { recursive: true });

package/lib/placeholder.js

@@ -57,8 +57,14 @@ const KNOWN_PLACEHOLDERS = {
 
 /**
  * Get default placeholder values based on config, tech stack, and analysis
+ * @param {object} config - Configuration from CLI (includes discoveredValues from merge)
+ * @param {object} techStack - Detected tech stack
+ * @param {object} analysis - Codebase analysis results
+ * @returns {object} Placeholder values
  */
 function getDefaultValues(config = {}, techStack = {}, analysis = {}) {
+  // Get discovered values from merge phase (if available)
+  const discoveredValues = config.discoveredValues || {};
   const today = new Date().toISOString().split('T')[0];
   const projectName = config.projectName || 'my-project';
   const projectSlug = projectName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
@@ -147,7 +153,7 @@ function getDefaultValues(config = {}, techStack = {}, analysis = {}) {
   // Entry point count
   const entryPointCount = analysis.entryPoints?.length || techStack.entryPoints?.length || 0;
 
-  return {
+  const defaults = {
     // Project identity
     PROJECT_NAME: projectName,
     PROJECT_SLUG: projectSlug,
@@ -234,6 +240,10 @@ function getDefaultValues(config = {}, techStack = {}, analysis = {}) {
     PRIMARY_FRAMEWORK: techStack.frameworks?.[0] || '',
     DATABASE_TYPE: techStack.databases?.[0] || '',
   };
+
+  // Merge with discovered values - discovered values take precedence
+  // This preserves user customizations from existing documentation
+  return { ...defaults, ...discoveredValues };
 }
 
 /**

package/lib/prompts.js

@@ -1,5 +1,5 @@
 /**
- * Interactive prompts for create-claude-context
+ * Interactive prompts for create-universal-ai-context
  *
  * Uses enquirer for beautiful, user-friendly prompts
  */
@@ -280,8 +280,62 @@ async function getDefaults(targetDir, presetName = null) {
   };
 }
 
+/**
+ * Run discovery prompts for handling existing documentation
+ * @param {object} discovery - Discovery results from doc-discovery.js
+ * @returns {Promise<object>} User's choices for handling existing docs
+ */
+async function runDiscoveryPrompts(discovery) {
+  if (!discovery || !discovery.hasExistingDocs) {
+    return { existingDocsStrategy: 'fresh' };
+  }
+
+  const { generateDiscoveryPrompts } = require('./doc-discovery');
+  const prompts = generateDiscoveryPrompts(discovery);
+
+  if (prompts.length === 0) {
+    return { existingDocsStrategy: 'fresh' };
+  }
+
+  console.log(chalk.gray('\nExisting documentation detected.\n'));
+
+  const answers = await prompt(prompts);
+
+  // Handle conflict resolution if user chose 'ask'
+  if (answers.conflictResolution === 'ask' && discovery.conflicts.length > 0) {
+    const conflictResolutions = {};
+
+    for (const conflict of discovery.conflicts) {
+      const conflictAnswer = await prompt([{
+        type: 'select',
+        name: 'resolution',
+        message: `Conflict for ${chalk.cyan(conflict.key)}:\n  Existing (${conflict.existingSource}): "${truncate(conflict.existingValue, 40)}"\n  New (${conflict.newSource}): "${truncate(conflict.newValue, 40)}"`,
+        choices: [
+          { name: 'existing', message: 'Keep existing value' },
+          { name: 'new', message: 'Use new value' }
+        ]
+      }]);
+      conflictResolutions[conflict.key] = conflictAnswer.resolution;
+    }
+
+    answers.conflictResolutions = conflictResolutions;
+  }
+
+  return answers;
+}
+
+/**
+ * Truncate a string with ellipsis
+ */
+function truncate(str, maxLength) {
+  if (!str) return '';
+  if (str.length <= maxLength) return str;
+  return str.substring(0, maxLength - 3) + '...';
+}
+
 module.exports = {
   runPrompts,
   getDefaults,
+  runDiscoveryPrompts,
   PRESETS
 };