create-universal-ai-context 2.1.3 → 2.2.1

package/README.md

@@ -67,6 +67,97 @@ npx create-universal-ai-context drift --fix           # Auto-fix issues
 npx create-universal-ai-context drift --strict        # Exit 1 on issues (CI)
 ```
 
+## Cross-Tool Sync
+
+Keep all AI tool contexts synchronized automatically:
+
+```bash
+# Check sync status
+npx create-universal-ai-context sync:check
+
+# Sync all tools from codebase
+npx create-universal-ai-context sync:all
+
+# Propagate from specific tool
+npx create-universal-ai-context sync:from claude --strategy source_wins
+
+# Resolve conflicts
+npx create-universal-ai-context sync:resolve --strategy regenerate_all
+
+# View sync history
+npx create-universal-ai-context sync:history
+
+# Install git hooks for automatic sync
+npx create-universal-ai-context hooks:install
+```
+
+**Conflict Strategies:**
+- `source_wins` - Changed tool's context wins
+- `regenerate_all` - Regenerate all from codebase
+- `newest` - Most recently modified wins
+- `manual` - Require manual resolution
+
+## Automation Scripts
+
+The generated `.ai-context/` directory includes automation that keeps documentation synchronized:
+
+### Generators
+
+**Code Mapper** (`.ai-context/automation/generators/code-mapper.js`)
+- Scans workflow files for file:line references
+- Builds CODE_TO_WORKFLOW_MAP.md (reverse index of code → docs)
+- Shows which workflows reference each file
+- Helps identify what needs updating after code changes
+
+**Index Builder** (`.ai-context/automation/generators/index-builder.js`)
+- Regenerates category indexes automatically
+- Updates navigation indexes with accurate counts
+- Scans workflows, agents, and commands for metadata
+
+### Git Hooks
+
+**Pre-Commit Hook**
+- Validates before allowing commits
+- Warns if code changes might affect documentation
+- Optionally blocks commits if docs are stale
+
+**Post-Commit Hook**
+- Rebuilds CODE_TO_WORKFLOW_MAP.md in background
+- Updates file hashes for change tracking
+- Keeps indexes synchronized
+
+### Install Hooks
+
+```bash
+# Copy hooks to .git/hooks/
+cp .ai-context/automation/hooks/pre-commit.sh .git/hooks/pre-commit
+cp .ai-context/automation/hooks/post-commit.sh .git/hooks/post-commit
+chmod +x .git/hooks/pre-commit .git/hooks/post-commit
+```
+
+### Run Manually
+
+```bash
+# Regenerate code-to-workflow map
+node .ai-context/automation/generators/code-mapper.js
+
+# Rebuild all indexes
+node .ai-context/automation/generators/index-builder.js
+
+# Dry-run to preview
+node .ai-context/automation/generators/code-mapper.js --dry-run
+```
+
+### Configuration
+
+Control automation via `.ai-context/automation/config.json`:
+- Enable/disable generators
+- Configure hook behavior
+- Set drift check sensitivity
+- Toggle blocking on stale documentation
+
+---
+
 ## Existing Documentation Detection
 
 The CLI automatically detects existing AI context files:

package/bin/create-ai-context.js

@@ -31,6 +31,15 @@ const {
   checkDocumentDrift,
   formatDriftReportConsole
 } = require('../lib/drift-checker');
+const {
+  checkSyncStatus,
+  syncAllFromCodebase,
+  propagateContextChange,
+  resolveConflict,
+  formatSyncStatus,
+  getSyncHistory,
+  CONFLICT_STRATEGY
+} = require('../lib/cross-tool-sync');
 const packageJson = require('../package.json');
 
 // ASCII Banner
@@ -492,4 +501,257 @@ function formatDriftReportMarkdown(report) {
   return lines.join('\n');
 }
 
+// Sync subcommands
+program
+  .command('sync:check')
+  .description('Check if AI tool contexts are synchronized')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .option('--json', 'Output as JSON')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+
+    try {
+      const status = checkSyncStatus(projectRoot);
+
+      if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+      } else {
+        console.log(formatSyncStatus(status));
+
+        if (!status.inSync) {
+          console.log(chalk.yellow('\nTo sync all contexts, run:'));
+          console.log(chalk.gray('  npx create-ai-context sync:all'));
+          process.exit(1);
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('sync:all')
+  .description('Synchronize all AI tool contexts from codebase')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .option('--quiet', 'Suppress output')
+  .action(async (options) => {
+    if (!options.quiet) {
+      console.log(banner);
+    }
+
+    const projectRoot = path.resolve(options.path);
+    const spinner = createSpinner();
+
+    try {
+      if (!options.quiet) {
+        spinner.start('Analyzing codebase...');
+      }
+
+      const config = {
+        projectName: path.basename(projectRoot),
+        aiTools: ['claude', 'copilot', 'cline', 'antigravity']
+      };
+
+      const results = await syncAllFromCodebase(projectRoot, config);
+
+      if (!options.quiet) {
+        if (results.errors.length > 0) {
+          spinner.warn('Sync completed with errors');
+
+          console.log(chalk.bold('\nSynced tools:'));
+          for (const tool of results.tools) {
+            console.log(chalk.green(`  ✓ ${tool.tool} (${tool.fileCount} files)`));
+          }
+
+          console.log(chalk.red('\nErrors:'));
+          for (const error of results.errors) {
+            console.error(chalk.red(`  ✖ ${error.message || error.tool}`));
+          }
+          process.exit(1);
+        } else {
+          spinner.succeed(`Synced ${results.tools.length} AI tools`);
+
+          console.log(chalk.bold('\nSynced tools:'));
+          for (const tool of results.tools) {
+            console.log(chalk.green(`  ✓ ${tool.tool} (${tool.fileCount} files)`));
+          }
+        }
+      }
+    } catch (error) {
+      if (!options.quiet) {
+        spinner.fail('Sync failed');
+        console.error(chalk.red('\n✖ Error:'), error.message);
+      }
+      process.exit(1);
+    }
+  });
+
+program
+  .command('sync:from <tool>')
+  .description('Propagate context from a specific tool to all others')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .option('-s, --strategy <strategy>', 'Conflict resolution strategy', 'source_wins')
+  .action(async (sourceTool, options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+    const spinner = createSpinner();
+
+    const validTools = ['claude', 'copilot', 'cline', 'antigravity'];
+    if (!validTools.includes(sourceTool)) {
+      console.error(chalk.red(`\n✖ Error: Invalid tool: ${sourceTool}`));
+      console.error(chalk.gray(`  Valid options: ${validTools.join(', ')}`));
+      process.exit(1);
+    }
+
+    try {
+      spinner.start(`Propagating from ${sourceTool}...`);
+
+      const config = {
+        projectName: path.basename(projectRoot),
+        aiTools: validTools
+      };
+
+      const results = await propagateContextChange(
+        sourceTool,
+        projectRoot,
+        config,
+        options.strategy
+      );
+
+      if (results.errors.length > 0) {
+        spinner.warn('Propagation completed with errors');
+
+        console.log(chalk.bold('\nPropagated to:'));
+        for (const tool of results.propagated) {
+          console.log(chalk.green(`  ✓ ${tool.displayName}`));
+        }
+
+        console.log(chalk.red('\nErrors:'));
+        for (const error of results.errors) {
+          console.error(chalk.red(`  ✖ ${error.tool || error.message}`));
+        }
+        process.exit(1);
+      } else {
+        spinner.succeed(`Propagated to ${results.propagated.length} tools`);
+
+        console.log(chalk.bold('\nPropagated to:'));
+        for (const tool of results.propagated) {
+          console.log(chalk.green(`  ✓ ${tool.displayName}`));
+        }
+      }
+    } catch (error) {
+      spinner.fail('Propagation failed');
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('sync:resolve')
+  .description('Resolve conflicts between AI tool contexts')
+  .option('-s, --strategy <strategy>', 'Strategy: source_wins, regenerate_all, newest, manual', 'regenerate_all')
+  .option('-t, --tool <tool>', 'Preferred tool (for source_wins strategy)')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+    const spinner = createSpinner();
+
+    const validStrategies = Object.values(CONFLICT_STRATEGY);
+    if (!validStrategies.includes(options.strategy)) {
+      console.error(chalk.red(`\n✖ Error: Invalid strategy: ${options.strategy}`));
+      console.error(chalk.gray(`  Valid options: ${validStrategies.join(', ')}`));
+      process.exit(1);
+    }
+
+    try {
+      spinner.start(`Resolving conflicts (${options.strategy})...`);
+
+      const config = {
+        projectName: path.basename(projectRoot),
+        aiTools: ['claude', 'copilot', 'cline', 'antigravity']
+      };
+
+      const result = await resolveConflict(
+        projectRoot,
+        config,
+        options.strategy,
+        options.tool
+      );
+
+      if (result.resolved) {
+        spinner.succeed(result.message);
+      } else {
+        spinner.warn('Unable to resolve');
+        console.log(chalk.yellow(`\n${result.message}`));
+
+        if (result.status) {
+          console.log(formatSyncStatus(result.status));
+        }
+        process.exit(1);
+      }
+    } catch (error) {
+      spinner.fail('Resolution failed');
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('sync:history')
+  .description('Show sync history')
+  .option('-n, --limit <number>', 'Number of entries to show', '10')
+  .option('-p, --path <dir>', 'Project directory (defaults to current)', '.')
+  .action(async (options) => {
+    console.log(banner);
+
+    const projectRoot = path.resolve(options.path);
+
+    try {
+      const history = getSyncHistory(projectRoot, parseInt(options.limit, 10));
+
+      console.log(chalk.bold('\nSync History:\n'));
+
+      if (history.length === 0) {
+        console.log(chalk.gray('  No sync history found\n'));
+      } else {
+        for (const entry of history.reverse()) {
+          const date = new Date(entry.timestamp).toLocaleString();
+          console.log(chalk.cyan(`  ${date}`));
+          console.log(chalk.gray(`    Source: ${entry.source || entry.sourceTool}`));
+          console.log(chalk.gray(`    Strategy: ${entry.strategy}`));
+          console.log(chalk.gray(`    Propagated: ${entry.propagatedCount} tools`));
+
+          if (entry.errorCount > 0) {
+            console.log(chalk.red(`    Errors: ${entry.errorCount}`));
+          }
+          console.log('');
+        }
+      }
+    } catch (error) {
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('hooks:install')
+  .description('Install git hooks for automatic sync')
+  .action(async () => {
+    console.log(banner);
+
+    try {
+      const { installHooks } = require('../lib/install-hooks');
+      installHooks();
+    } catch (error) {
+      console.error(chalk.red('\n✖ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 program.parse();

package/lib/cross-tool-sync/file-watcher.js

@@ -0,0 +1,274 @@
+/**
+ * File Watcher for Cross-Tool Sync
+ *
+ * Monitors AI tool context files for changes and triggers synchronization.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { EventEmitter } = require('events');
+
+/**
+ * Simple file watcher implementation (no chokidar dependency)
+ * Uses polling to detect file changes
+ */
+class FileWatcher extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.watchPaths = new Map();
+    this.fileStates = new Map();
+    this.pollInterval = options.pollInterval || 1000; // 1 second default
+    this.intervalId = null;
+    this.running = false;
+  }
+
+  /**
+   * Add a file or directory to watch
+   */
+  watch(watchPath, projectRoot) {
+    const fullPath = path.isAbsolute(watchPath)
+      ? watchPath
+      : path.join(projectRoot, watchPath);
+
+    const key = fullPath.toLowerCase();
+
+    if (this.watchPaths.has(key)) {
+      return;
+    }
+
+    // Store initial state
+    this.recordFileState(fullPath, key);
+
+    this.watchPaths.set(key, {
+      path: fullPath,
+      projectRoot,
+      isDirectory: this.isDirectory(fullPath)
+    });
+  }
+
+  /**
+   * Record current state of a file/directory
+   */
+  recordFileState(filePath, key) {
+    try {
+      if (fs.existsSync(filePath)) {
+        const stats = fs.statSync(filePath);
+
+        if (stats.isDirectory()) {
+          // For directories, hash all files
+          this.fileStates.set(key, {
+            mtimeMs: stats.mtimeMs,
+            hash: this.hashDirectory(filePath),
+            exists: true
+          });
+        } else {
+          // For files, use content hash
+          const content = fs.readFileSync(filePath, 'utf-8');
+          const crypto = require('crypto');
+          const hash = crypto.createHash('sha256').update(content).digest('hex');
+
+          this.fileStates.set(key, {
+            mtimeMs: stats.mtimeMs,
+            hash,
+            exists: true
+          });
+        }
+      } else {
+        this.fileStates.set(key, { exists: false });
+      }
+    } catch (error) {
+      this.fileStates.set(key, { exists: false, error: error.message });
+    }
+  }
+
+  /**
+   * Check if path is a directory
+   */
+  isDirectory(filePath) {
+    try {
+      return fs.existsSync(filePath) && fs.statSync(filePath).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Hash all files in a directory
+   */
+  hashDirectory(dirPath) {
+    const crypto = require('crypto');
+    const hash = crypto.createHash('sha256');
+    const files = this.getAllFiles(dirPath);
+
+    for (const file of files.sort()) {
+      try {
+        const content = fs.readFileSync(file, 'utf-8');
+        hash.update(content);
+      } catch {
+        // Skip files that can't be read
+      }
+    }
+
+    return hash.digest('hex');
+  }
+
+  /**
+   * Get all files in directory recursively
+   */
+  getAllFiles(dirPath) {
+    const files = [];
+
+    try {
+      const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          files.push(...this.getAllFiles(fullPath));
+        } else {
+          files.push(fullPath);
+        }
+      }
+    } catch {
+      // Skip directories that can't be read
+    }
+
+    return files;
+  }
+
+  /**
+   * Start watching
+   */
+  start() {
+    if (this.running) {
+      return;
+    }
+
+    this.running = true;
+    this.intervalId = setInterval(() => {
+      this.checkForChanges();
+    }, this.pollInterval);
+
+    this.emit('ready');
+  }
+
+  /**
+   * Stop watching
+   */
+  stop() {
+    if (!this.running) {
+      return;
+    }
+
+    this.running = false;
+
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+
+    this.emit('stopped');
+  }
+
+  /**
+   * Check all watched paths for changes
+   */
+  checkForChanges() {
+    for (const [key, watchInfo] of this.watchPaths.entries()) {
+      this.checkPath(key, watchInfo);
+    }
+  }
+
+  /**
+   * Check a single path for changes
+   */
+  checkPath(key, watchInfo) {
+    const { path: filePath } = watchInfo;
+    const oldState = this.fileStates.get(key);
+
+    if (!oldState) {
+      return;
+    }
+
+    // Record new state
+    this.recordFileState(filePath, key);
+    const newState = this.fileStates.get(key);
+
+    // Detect changes
+    if (!oldState.exists && newState.exists) {
+      // File/directory was created
+      this.emit('created', {
+        path: filePath,
+        ...watchInfo
+      });
+    } else if (oldState.exists && !newState.exists) {
+      // File/directory was deleted
+      this.emit('deleted', {
+        path: filePath,
+        ...watchInfo
+      });
+    } else if (oldState.exists && newState.exists) {
+      // Check for modifications
+      if (oldState.hash !== newState.hash) {
+        this.emit('changed', {
+          path: filePath,
+          ...watchInfo,
+          previousHash: oldState.hash,
+          currentHash: newState.hash
+        });
+      }
+    }
+  }
+
+  /**
+   * Get current watch list
+   */
+  getWatchedPaths() {
+    return Array.from(this.watchPaths.values()).map(w => w.path);
+  }
+
+  /**
+   * Unwatch a specific path
+   */
+  unwatch(watchPath) {
+    const fullPath = path.isAbsolute(watchPath)
+      ? watchPath
+      : path.join(process.cwd(), watchPath);
+
+    const key = fullPath.toLowerCase();
+    this.watchPaths.delete(key);
+    this.fileStates.delete(key);
+  }
+
+  /**
+   * Unwatch all paths
+   */
+  unwatchAll() {
+    this.watchPaths.clear();
+    this.fileStates.clear();
+  }
+}
+
+/**
+ * Create a file watcher for AI tool contexts
+ */
+function createToolContextWatcher(projectRoot, options = {}) {
+  const watcher = new FileWatcher(options);
+
+  // Add context files for all tools
+  const { TOOL_CONTEXT_FILES } = require('./sync-manager');
+
+  for (const [toolName, files] of Object.entries(TOOL_CONTEXT_FILES)) {
+    for (const file of files) {
+      watcher.watch(file, projectRoot);
+    }
+  }
+
+  return watcher;
+}
+
+module.exports = {
+  FileWatcher,
+  createToolContextWatcher
+};

package/lib/cross-tool-sync/index.js

@@ -0,0 +1,40 @@
+/**
+ * Cross-Tool Sync Module
+ *
+ * Exports all synchronization functionality for automatic cross-tool
+ * context synchronization.
+ */
+
+const SyncManager = require('./sync-manager');
+const { FileWatcher, createToolContextWatcher } = require('./file-watcher');
+const { SyncService, createSyncService, DEFAULT_CONFIG } = require('./sync-service');
+
+module.exports = {
+  // Sync Manager - Core sync logic
+  ...SyncManager,
+
+  // File Watcher - Change detection
+  FileWatcher,
+  createToolContextWatcher,
+
+  // Sync Service - Background service
+  SyncService,
+  createSyncService,
+  DEFAULT_CONFIG
+};
+
+// Also export individual functions for named imports
+module.exports.detectChangedTool = SyncManager.detectChangedTool;
+module.exports.propagateContextChange = SyncManager.propagateContextChange;
+module.exports.checkSyncStatus = SyncManager.checkSyncStatus;
+module.exports.syncAllFromCodebase = SyncManager.syncAllFromCodebase;
+module.exports.resolveConflict = SyncManager.resolveConflict;
+module.exports.getSyncHistory = SyncManager.getSyncHistory;
+module.exports.initSyncState = SyncManager.initSyncState;
+module.exports.loadSyncState = SyncManager.loadSyncState;
+module.exports.saveSyncState = SyncManager.saveSyncState;
+module.exports.calculateFileHash = SyncManager.calculateFileHash;
+module.exports.getToolContextFiles = SyncManager.getToolContextFiles;
+module.exports.formatSyncStatus = SyncManager.formatSyncStatus;
+module.exports.CONFLICT_STRATEGY = SyncManager.CONFLICT_STRATEGY;
+module.exports.TOOL_CONTEXT_FILES = SyncManager.TOOL_CONTEXT_FILES;