create-universal-ai-context 2.0.0

package/templates/base/tools/lib/drift-detector.js

@@ -0,0 +1,373 @@
+/**
+ * Drift Detector - Detects documentation drift from code
+ *
+ * Compares documentation references against current code state
+ * to identify outdated line numbers, renamed functions, etc.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { resolveAnchor, buildFileAnchors, loadAnchors } = require('./anchor-resolver');
+
+const SYNC_DIR = path.join(__dirname, '..', '..', 'sync');
+const HASHES_PATH = path.join(SYNC_DIR, 'hashes.json');
+const STALENESS_PATH = path.join(SYNC_DIR, 'staleness.json');
+
+/**
+ * Drift severity levels
+ */
+const DRIFT_LEVEL = {
+  NONE: 'none',
+  LOW: 'low',         // Line number shifted slightly
+  MEDIUM: 'medium',   // Function renamed or moved
+  HIGH: 'high',       // Logic changed significantly
+  CRITICAL: 'critical' // File deleted or major restructure
+};
+
+/**
+ * Calculate file hash
+ */
+function hashFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return crypto.createHash('md5').update(content).digest('hex');
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Load stored hashes
+ */
+function loadHashes() {
+  try {
+    if (fs.existsSync(HASHES_PATH)) {
+      const content = fs.readFileSync(HASHES_PATH, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error('Failed to load hashes:', error.message);
+  }
+  return { version: '1.0.0', files: {} };
+}
+
+/**
+ * Save hashes
+ */
+function saveHashes(data) {
+  try {
+    if (!fs.existsSync(SYNC_DIR)) {
+      fs.mkdirSync(SYNC_DIR, { recursive: true });
+    }
+    data.generatedAt = new Date().toISOString();
+    fs.writeFileSync(HASHES_PATH, JSON.stringify(data, null, 2));
+    return true;
+  } catch (error) {
+    console.error('Failed to save hashes:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Load staleness tracking
+ */
+function loadStaleness() {
+  try {
+    if (fs.existsSync(STALENESS_PATH)) {
+      const content = fs.readFileSync(STALENESS_PATH, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error('Failed to load staleness:', error.message);
+  }
+  return { version: '1.0.0', workflows: {}, thresholds: { warningDays: 30, staleDays: 90 } };
+}
+
+/**
+ * Save staleness tracking
+ */
+function saveStaleness(data) {
+  try {
+    if (!fs.existsSync(SYNC_DIR)) {
+      fs.mkdirSync(SYNC_DIR, { recursive: true });
+    }
+    fs.writeFileSync(STALENESS_PATH, JSON.stringify(data, null, 2));
+    return true;
+  } catch (error) {
+    console.error('Failed to save staleness:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Check if a file has changed since last recorded
+ */
+function checkFileChange(filePath, projectRoot = process.cwd()) {
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+  const stored = loadHashes();
+
+  if (!fs.existsSync(fullPath)) {
+    return {
+      changed: true,
+      level: DRIFT_LEVEL.CRITICAL,
+      reason: 'File not found'
+    };
+  }
+
+  const currentHash = hashFile(fullPath);
+  const storedData = stored.files[filePath];
+
+  if (!storedData) {
+    return {
+      changed: true,
+      level: DRIFT_LEVEL.LOW,
+      reason: 'File not previously tracked'
+    };
+  }
+
+  if (storedData.hash !== currentHash) {
+    return {
+      changed: true,
+      level: DRIFT_LEVEL.MEDIUM,
+      reason: 'File content changed',
+      previousHash: storedData.hash,
+      currentHash
+    };
+  }
+
+  return {
+    changed: false,
+    level: DRIFT_LEVEL.NONE
+  };
+}
+
+/**
+ * Extract line references from markdown content
+ */
+function extractLineReferences(content) {
+  const references = [];
+
+  // file:123 format
+  const linePattern = /([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+):(\d+)/g;
+  let match;
+  while ((match = linePattern.exec(content)) !== null) {
+    references.push({
+      file: match[1],
+      line: parseInt(match[2]),
+      type: 'line',
+      original: match[0]
+    });
+  }
+
+  // file::function() format
+  const anchorPattern = /([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+)::(\w+)\(\)/g;
+  while ((match = anchorPattern.exec(content)) !== null) {
+    references.push({
+      file: match[1],
+      anchor: match[2],
+      type: 'anchor',
+      original: match[0]
+    });
+  }
+
+  return references;
+}
+
+/**
+ * Check drift for a workflow file
+ */
+function checkWorkflowDrift(workflowPath, projectRoot = process.cwd()) {
+  const fullPath = path.isAbsolute(workflowPath)
+    ? workflowPath
+    : path.join(projectRoot, '.claude', workflowPath);
+
+  if (!fs.existsSync(fullPath)) {
+    return {
+      workflow: workflowPath,
+      status: 'error',
+      error: 'Workflow file not found'
+    };
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const references = extractLineReferences(content);
+  const issues = [];
+
+  for (const ref of references) {
+    if (ref.type === 'line') {
+      // Check if file exists and line is valid
+      const filePath = path.join(projectRoot, ref.file);
+
+      if (!fs.existsSync(filePath)) {
+        issues.push({
+          ...ref,
+          level: DRIFT_LEVEL.CRITICAL,
+          issue: 'Referenced file not found'
+        });
+        continue;
+      }
+
+      const fileContent = fs.readFileSync(filePath, 'utf-8');
+      const lines = fileContent.split('\n');
+
+      if (ref.line > lines.length) {
+        issues.push({
+          ...ref,
+          level: DRIFT_LEVEL.HIGH,
+          issue: `Line ${ref.line} exceeds file length (${lines.length} lines)`
+        });
+      }
+
+      // Check if file has changed
+      const changeResult = checkFileChange(ref.file, projectRoot);
+      if (changeResult.changed && changeResult.level !== DRIFT_LEVEL.NONE) {
+        issues.push({
+          ...ref,
+          level: changeResult.level,
+          issue: changeResult.reason
+        });
+      }
+    } else if (ref.type === 'anchor') {
+      // Resolve semantic anchor
+      const result = resolveAnchor(`${ref.file}::${ref.anchor}()`, projectRoot);
+      if (!result.success) {
+        issues.push({
+          ...ref,
+          level: DRIFT_LEVEL.HIGH,
+          issue: result.error,
+          availableSymbols: result.availableSymbols
+        });
+      }
+    }
+  }
+
+  // Determine overall status
+  let status = 'healthy';
+  let maxLevel = DRIFT_LEVEL.NONE;
+
+  for (const issue of issues) {
+    if (issue.level === DRIFT_LEVEL.CRITICAL) {
+      status = 'critical';
+      maxLevel = DRIFT_LEVEL.CRITICAL;
+    } else if (issue.level === DRIFT_LEVEL.HIGH && maxLevel !== DRIFT_LEVEL.CRITICAL) {
+      status = 'stale';
+      maxLevel = DRIFT_LEVEL.HIGH;
+    } else if (issue.level === DRIFT_LEVEL.MEDIUM && maxLevel === DRIFT_LEVEL.NONE) {
+      status = 'needs_update';
+      maxLevel = DRIFT_LEVEL.MEDIUM;
+    }
+  }
+
+  return {
+    workflow: workflowPath,
+    status,
+    level: maxLevel,
+    totalReferences: references.length,
+    issues,
+    checkedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Update file hashes for tracking
+ */
+function updateFileHashes(filePaths, projectRoot = process.cwd()) {
+  const stored = loadHashes();
+
+  for (const filePath of filePaths) {
+    const fullPath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+    const hash = hashFile(fullPath);
+
+    if (hash) {
+      stored.files[filePath] = {
+        hash,
+        updatedAt: new Date().toISOString()
+      };
+    }
+  }
+
+  saveHashes(stored);
+  return stored;
+}
+
+/**
+ * Mark workflow as verified
+ */
+function markWorkflowVerified(workflowPath) {
+  const staleness = loadStaleness();
+
+  staleness.workflows[workflowPath] = {
+    lastVerified: new Date().toISOString(),
+    status: 'verified'
+  };
+
+  saveStaleness(staleness);
+}
+
+/**
+ * Check staleness of all workflows
+ */
+function checkStaleness() {
+  const staleness = loadStaleness();
+  const now = Date.now();
+  const results = [];
+
+  for (const [workflow, data] of Object.entries(staleness.workflows)) {
+    const lastVerified = new Date(data.lastVerified).getTime();
+    const daysSince = (now - lastVerified) / (1000 * 60 * 60 * 24);
+
+    let status = 'fresh';
+    if (daysSince > staleness.thresholds.staleDays) {
+      status = 'stale';
+    } else if (daysSince > staleness.thresholds.warningDays) {
+      status = 'warning';
+    }
+
+    results.push({
+      workflow,
+      lastVerified: data.lastVerified,
+      daysSince: Math.round(daysSince),
+      status
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Generate drift report
+ */
+function generateReport(workflowPaths, projectRoot = process.cwd()) {
+  const results = [];
+
+  for (const workflow of workflowPaths) {
+    const result = checkWorkflowDrift(workflow, projectRoot);
+    results.push(result);
+  }
+
+  // Summary
+  const summary = {
+    total: results.length,
+    healthy: results.filter(r => r.status === 'healthy').length,
+    needsUpdate: results.filter(r => r.status === 'needs_update').length,
+    stale: results.filter(r => r.status === 'stale').length,
+    critical: results.filter(r => r.status === 'critical').length,
+    generatedAt: new Date().toISOString()
+  };
+
+  return { summary, results };
+}
+
+module.exports = {
+  checkFileChange,
+  checkWorkflowDrift,
+  updateFileHashes,
+  markWorkflowVerified,
+  checkStaleness,
+  generateReport,
+  extractLineReferences,
+  loadHashes,
+  saveHashes,
+  DRIFT_LEVEL
+};

package/templates/base/tools/lib/errors.js

@@ -0,0 +1,199 @@
+/**
+ * Claude Context Engineering - Error Classes
+ *
+ * Structured error handling for the context engineering system.
+ * All errors are categorized and include recovery information.
+ */
+
+/**
+ * Base error class for all Claude Context errors
+ */
+class ClaudeContextError extends Error {
+  constructor(message, code, recoverable = true, details = {}) {
+    super(message);
+    this.name = 'ClaudeContextError';
+    this.code = code;
+    this.recoverable = recoverable;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+
+    // Capture stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      recoverable: this.recoverable,
+      details: this.details,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+/**
+ * Configuration-related errors
+ */
+class ConfigurationError extends ClaudeContextError {
+  constructor(message, details = {}) {
+    super(message, ConfigurationError.codes[details.type] || 'E001', true, details);
+    this.name = 'ConfigurationError';
+  }
+
+  static codes = {
+    MISSING: 'E001',
+    INVALID: 'E002',
+    SCHEMA_VIOLATION: 'E003',
+    MERGE_CONFLICT: 'E004',
+  };
+}
+
+/**
+ * Validation-related errors
+ */
+class ValidationError extends ClaudeContextError {
+  constructor(message, details = {}) {
+    super(message, ValidationError.codes[details.type] || 'E010', true, details);
+    this.name = 'ValidationError';
+  }
+
+  static codes = {
+    SCHEMA: 'E010',
+    LINK_BROKEN: 'E011',
+    PLACEHOLDER_REMAINING: 'E012',
+    LINE_NUMBER_STALE: 'E013',
+    STRUCTURE: 'E014',
+  };
+}
+
+/**
+ * File system-related errors
+ */
+class FileSystemError extends ClaudeContextError {
+  constructor(message, details = {}) {
+    super(message, FileSystemError.codes[details.type] || 'E020', true, details);
+    this.name = 'FileSystemError';
+  }
+
+  static codes = {
+    NOT_FOUND: 'E020',
+    PERMISSION_DENIED: 'E021',
+    READ_ERROR: 'E022',
+    WRITE_ERROR: 'E023',
+    DIRECTORY_ERROR: 'E024',
+  };
+}
+
+/**
+ * Initialization-related errors
+ */
+class InitializationError extends ClaudeContextError {
+  constructor(message, details = {}) {
+    super(message, InitializationError.codes[details.type] || 'E030', true, details);
+    this.name = 'InitializationError';
+  }
+
+  static codes = {
+    INCOMPLETE: 'E030',
+    TECH_STACK_UNKNOWN: 'E031',
+    WORKFLOW_DISCOVERY_FAILED: 'E032',
+    PLACEHOLDER_REPLACEMENT_FAILED: 'E033',
+    ALREADY_INITIALIZED: 'E034',
+  };
+}
+
+/**
+ * Agent/Command execution errors
+ */
+class ExecutionError extends ClaudeContextError {
+  constructor(message, details = {}) {
+    super(message, ExecutionError.codes[details.type] || 'E040', details.recoverable ?? true, details);
+    this.name = 'ExecutionError';
+  }
+
+  static codes = {
+    AGENT_NOT_FOUND: 'E040',
+    COMMAND_NOT_FOUND: 'E041',
+    TIMEOUT: 'E042',
+    CONTEXT_EXCEEDED: 'E043',
+    DEPENDENCY_MISSING: 'E044',
+  };
+}
+
+/**
+ * Error code reference table
+ */
+const ERROR_CODES = {
+  // Configuration (E001-E009)
+  E001: { name: 'CONFIG_MISSING', description: 'Configuration file not found' },
+  E002: { name: 'CONFIG_INVALID', description: 'Configuration file is invalid JSON' },
+  E003: { name: 'SCHEMA_VIOLATION', description: 'Configuration does not match schema' },
+  E004: { name: 'MERGE_CONFLICT', description: 'Configuration merge conflict' },
+
+  // Validation (E010-E019)
+  E010: { name: 'SCHEMA_ERROR', description: 'JSON schema validation failed' },
+  E011: { name: 'LINK_BROKEN', description: 'Markdown link does not resolve' },
+  E012: { name: 'PLACEHOLDER_REMAINING', description: 'Unresolved {{PLACEHOLDER}} found' },
+  E013: { name: 'LINE_NUMBER_STALE', description: 'Line number reference is outdated' },
+  E014: { name: 'STRUCTURE_ERROR', description: 'Required file or directory missing' },
+
+  // File System (E020-E029)
+  E020: { name: 'FILE_NOT_FOUND', description: 'File does not exist' },
+  E021: { name: 'PERMISSION_DENIED', description: 'Insufficient permissions' },
+  E022: { name: 'READ_ERROR', description: 'Failed to read file' },
+  E023: { name: 'WRITE_ERROR', description: 'Failed to write file' },
+  E024: { name: 'DIRECTORY_ERROR', description: 'Directory operation failed' },
+
+  // Initialization (E030-E039)
+  E030: { name: 'INIT_INCOMPLETE', description: 'Initialization did not complete' },
+  E031: { name: 'TECH_STACK_UNKNOWN', description: 'Could not detect technology stack' },
+  E032: { name: 'WORKFLOW_DISCOVERY_FAILED', description: 'Failed to discover workflows' },
+  E033: { name: 'PLACEHOLDER_REPLACEMENT_FAILED', description: 'Failed to replace placeholders' },
+  E034: { name: 'ALREADY_INITIALIZED', description: 'System already initialized' },
+
+  // Execution (E040-E049)
+  E040: { name: 'AGENT_NOT_FOUND', description: 'Agent not found' },
+  E041: { name: 'COMMAND_NOT_FOUND', description: 'Command not found' },
+  E042: { name: 'TIMEOUT', description: 'Operation timed out' },
+  E043: { name: 'CONTEXT_EXCEEDED', description: 'Context budget exceeded' },
+  E044: { name: 'DEPENDENCY_MISSING', description: 'Required dependency not available' },
+};
+
+/**
+ * Get error details by code
+ */
+function getErrorInfo(code) {
+  return ERROR_CODES[code] || { name: 'UNKNOWN', description: 'Unknown error' };
+}
+
+/**
+ * Format error for display
+ */
+function formatError(error) {
+  if (error instanceof ClaudeContextError) {
+    const info = getErrorInfo(error.code);
+    return `[${error.code}] ${error.name}: ${error.message}\n` +
+           `  Type: ${info.name}\n` +
+           `  Recoverable: ${error.recoverable ? 'Yes' : 'No'}\n` +
+           (Object.keys(error.details).length > 0
+             ? `  Details: ${JSON.stringify(error.details, null, 2)}\n`
+             : '');
+  }
+  return error.toString();
+}
+
+module.exports = {
+  ClaudeContextError,
+  ConfigurationError,
+  ValidationError,
+  FileSystemError,
+  InitializationError,
+  ExecutionError,
+  ERROR_CODES,
+  getErrorInfo,
+  formatError,
+};

package/templates/base/tools/lib/index.js

@@ -0,0 +1,36 @@
+/**
+ * Claude Context Engineering Tools - Main Entry
+ *
+ * Exports all public APIs from the tools library.
+ */
+
+const { init } = require('./init');
+const { validate } = require('./validate');
+const { diagnose } = require('./diagnose');
+const { configLoader } = require('./config-loader');
+const { logger } = require('./logger');
+const errors = require('./errors');
+
+// Self-sustaining automation modules
+const sessionManager = require('./session-manager');
+const anchorResolver = require('./anchor-resolver');
+const driftDetector = require('./drift-detector');
+
+module.exports = {
+  // Commands
+  init,
+  validate,
+  diagnose,
+
+  // Utilities
+  configLoader,
+  logger,
+  errors,
+
+  // Session Management
+  sessionManager,
+
+  // Synchronization
+  anchorResolver,
+  driftDetector,
+};