create-claude-context 1.0.0

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,24 @@
+/**
+ * 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');
+
+module.exports = {
+  // Commands
+  init,
+  validate,
+  diagnose,
+
+  // Utilities
+  configLoader,
+  logger,
+  errors,
+};

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

@@ -0,0 +1,192 @@
+/**
+ * Claude Context Engineering - Initialization Module
+ *
+ * Handles initialization of context engineering for a repository.
+ * Includes tech stack detection, workflow discovery, and template population.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { configLoader, findClaudeDir } = require('./config-loader');
+const { logger } = require('./logger');
+const { InitializationError, FileSystemError } = require('./errors');
+const { detectTechStack } = require('./detector');
+const { replacePlaceholders } = require('./placeholder');
+
+/**
+ * Initialize context engineering for a repository
+ */
+async function init(options = {}) {
+  const {
+    config: configPath,
+    interactive = true,
+    resume = false,
+    validateOnly = false,
+    techStack = null,
+    projectName = null,
+  } = options;
+
+  const op = logger.startOperation('init');
+
+  try {
+    console.log(chalk.cyan('\n📦 Initializing Claude Context Engineering...\n'));
+
+    // Find or create .claude directory
+    const claudeDir = findClaudeDir();
+    const projectRoot = path.dirname(claudeDir);
+
+    // Check for existing initialization
+    const progressFile = path.join(claudeDir, 'INIT_PROGRESS.json');
+    let progress = null;
+
+    if (fs.existsSync(progressFile)) {
+      progress = JSON.parse(fs.readFileSync(progressFile, 'utf8'));
+
+      if (!resume && progress.status !== 'COMPLETED') {
+        console.log(chalk.yellow('⚠️  Previous initialization found. Use --resume to continue.'));
+        console.log(chalk.gray(`   Status: ${progress.status}`));
+        console.log(chalk.gray(`   Last phase: ${progress.current_phase}`));
+        return;
+      }
+    }
+
+    // Validate-only mode
+    if (validateOnly) {
+      console.log(chalk.cyan('🔍 Validating existing initialization...\n'));
+      return await validateInitialization(claudeDir);
+    }
+
+    // Resume mode
+    if (resume && progress) {
+      console.log(chalk.cyan(`🔄 Resuming from phase: ${progress.current_phase}\n`));
+      return await resumeInitialization(claudeDir, progress, options);
+    }
+
+    // Start fresh initialization
+    console.log(chalk.white('Phase 1: Repository Analysis'));
+    console.log(chalk.gray('─'.repeat(50)));
+
+    // Detect tech stack
+    console.log('  Detecting technology stack...');
+    const detected = await detectTechStack(projectRoot, { hint: techStack });
+
+    console.log(chalk.green(`  ✓ Tech stack: ${detected.stack}`));
+    console.log(chalk.gray(`    Languages: ${detected.languages.join(', ')}`));
+    console.log(chalk.gray(`    Frameworks: ${detected.frameworks.join(', ')}`));
+    console.log(chalk.gray(`    Files: ${detected.fileCount}`));
+
+    // Create progress file
+    progress = {
+      version: '1.0.0',
+      started_at: new Date().toISOString(),
+      last_updated: new Date().toISOString(),
+      status: 'IN_PROGRESS',
+      current_phase: 'analysis',
+      phases: {
+        analysis: { status: 'COMPLETE', duration_ms: 0 },
+        discovery: { status: 'PENDING' },
+        population: { status: 'PENDING' },
+        validation: { status: 'PENDING' },
+        finalization: { status: 'PENDING' },
+      },
+      detected: {
+        tech_stack: detected.stack,
+        languages: detected.languages,
+        frameworks: detected.frameworks,
+        file_count: detected.fileCount,
+        loc: detected.loc || 0,
+      },
+      project_name: projectName || detected.projectName || path.basename(projectRoot),
+      errors: [],
+    };
+
+    saveProgress(progressFile, progress);
+
+    // Phase 2: Workflow Discovery
+    console.log(chalk.white('\nPhase 2: Workflow Discovery'));
+    console.log(chalk.gray('─'.repeat(50)));
+    console.log(chalk.yellow('  ⚠️  Full workflow discovery requires Claude Code agent.'));
+    console.log(chalk.gray('  Run: @context-engineer "Initialize context engineering"'));
+    console.log(chalk.gray('  The agent will discover 8-15 workflows automatically.\n'));
+
+    progress.current_phase = 'discovery';
+    progress.phases.discovery.status = 'PENDING_AGENT';
+    saveProgress(progressFile, progress);
+
+    // Phase 3: Template Population (partial - placeholders only)
+    console.log(chalk.white('Phase 3: Template Population (Partial)'));
+    console.log(chalk.gray('─'.repeat(50)));
+
+    const placeholderValues = {
+      PROJECT_NAME: progress.project_name,
+      TECH_STACK: detected.stack,
+      DATE: new Date().toISOString().split('T')[0],
+      WORKFLOWS_COUNT: '{{WORKFLOWS_COUNT}}', // To be filled by agent
+      // Add more known values
+    };
+
+    const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+    if (fs.existsSync(claudeMdPath)) {
+      const result = await replacePlaceholders(claudeMdPath, placeholderValues, { dryRun: false });
+      console.log(chalk.green(`  ✓ Replaced ${result.replaced} placeholders in CLAUDE.md`));
+      console.log(chalk.gray(`  Remaining: ${result.remaining} placeholders`));
+    }
+
+    progress.current_phase = 'population';
+    progress.phases.population.status = 'PARTIAL';
+    saveProgress(progressFile, progress);
+
+    // Summary
+    console.log(chalk.white('\n📋 Initialization Summary'));
+    console.log(chalk.gray('─'.repeat(50)));
+    console.log(chalk.green('  ✓ Repository analyzed'));
+    console.log(chalk.green('  ✓ Tech stack detected'));
+    console.log(chalk.yellow('  ⏳ Workflow discovery pending (run agent)'));
+    console.log(chalk.yellow('  ⏳ Template population partial'));
+
+    console.log(chalk.white('\n📌 Next Steps:'));
+    console.log(chalk.cyan('  1. Run: @context-engineer "Initialize context engineering"'));
+    console.log(chalk.gray('     This will discover workflows and complete the setup.'));
+    console.log(chalk.cyan('  2. Review generated workflow documentation'));
+    console.log(chalk.cyan('  3. Run: npx claude-context validate'));
+
+    op.success();
+
+  } catch (error) {
+    op.fail(error);
+    throw error;
+  }
+}
+
+/**
+ * Save initialization progress
+ */
+function saveProgress(filePath, progress) {
+  progress.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(progress, null, 2));
+}
+
+/**
+ * Resume an interrupted initialization
+ */
+async function resumeInitialization(claudeDir, progress, options) {
+  console.log(chalk.cyan(`Resuming from phase: ${progress.current_phase}`));
+  // Implementation would continue from the last phase
+  console.log(chalk.yellow('⚠️  Resume functionality requires full agent support.'));
+  console.log(chalk.gray('  Run: @context-engineer "resume initialization"'));
+}
+
+/**
+ * Validate an existing initialization
+ */
+async function validateInitialization(claudeDir) {
+  const { validate } = require('./validate');
+  return await validate({ all: true, claudeDir });
+}
+
+module.exports = {
+  init,
+  resumeInitialization,
+  validateInitialization,
+};

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

@@ -0,0 +1,230 @@
+/**
+ * Claude Context Engineering - Logger
+ *
+ * Structured logging with levels, file output, and operation tracking.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const LEVEL_COLORS = {
+  debug: chalk.gray,
+  info: chalk.blue,
+  warn: chalk.yellow,
+  error: chalk.red,
+};
+
+const LEVEL_ICONS = {
+  debug: '🔍',
+  info: 'ℹ️ ',
+  warn: '⚠️ ',
+  error: '❌',
+};
+
+/**
+ * Create a logger instance
+ */
+function createLogger(options = {}) {
+  const config = {
+    level: options.level || 'info',
+    file: options.file || null,
+    maxSizeMb: options.maxSizeMb || 10,
+    console: options.console !== false,
+    timestamps: options.timestamps !== false,
+    colors: options.colors !== false,
+  };
+
+  // Ensure log directory exists if file logging enabled
+  if (config.file) {
+    const logDir = path.dirname(config.file);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Check if we should log at this level
+   */
+  function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[config.level];
+  }
+
+  /**
+   * Format a log message
+   */
+  function formatMessage(level, message, meta = {}) {
+    const timestamp = new Date().toISOString();
+    const parts = [];
+
+    if (config.timestamps) {
+      parts.push(`[${timestamp}]`);
+    }
+    parts.push(`[${level.toUpperCase()}]`);
+    parts.push(message);
+
+    if (Object.keys(meta).length > 0) {
+      parts.push(JSON.stringify(meta));
+    }
+
+    return parts.join(' ');
+  }
+
+  /**
+   * Write to console with colors
+   */
+  function writeConsole(level, message, meta) {
+    if (!config.console) return;
+
+    const colorFn = config.colors ? LEVEL_COLORS[level] : (s) => s;
+    const icon = LEVEL_ICONS[level];
+    const timestamp = config.timestamps
+      ? chalk.gray(`[${new Date().toISOString()}] `)
+      : '';
+
+    let output = `${timestamp}${icon} ${colorFn(message)}`;
+
+    if (Object.keys(meta).length > 0) {
+      output += '\n' + chalk.gray(JSON.stringify(meta, null, 2));
+    }
+
+    if (level === 'error') {
+      console.error(output);
+    } else {
+      console.log(output);
+    }
+  }
+
+  /**
+   * Write to file
+   */
+  function writeFile(level, message, meta) {
+    if (!config.file) return;
+
+    try {
+      const formatted = formatMessage(level, message, meta) + '\n';
+      fs.appendFileSync(config.file, formatted);
+
+      // Check file size and rotate if needed
+      const stats = fs.statSync(config.file);
+      const sizeMb = stats.size / (1024 * 1024);
+      if (sizeMb > config.maxSizeMb) {
+        rotateLog();
+      }
+    } catch (error) {
+      // Silently fail file logging
+    }
+  }
+
+  /**
+   * Rotate log file
+   */
+  function rotateLog() {
+    if (!config.file || !fs.existsSync(config.file)) return;
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const rotatedPath = config.file.replace('.log', `-${timestamp}.log`);
+
+    try {
+      fs.renameSync(config.file, rotatedPath);
+    } catch (error) {
+      // Silently fail rotation
+    }
+  }
+
+  /**
+   * Core log function
+   */
+  function log(level, message, meta = {}) {
+    if (!shouldLog(level)) return;
+
+    writeConsole(level, message, meta);
+    writeFile(level, message, meta);
+  }
+
+  /**
+   * Start an operation and return tracking object
+   */
+  function startOperation(name) {
+    const operationId = generateId();
+    const startTime = Date.now();
+
+    log('info', `Operation started: ${name}`, { operation_id: operationId });
+
+    return {
+      id: operationId,
+
+      /**
+       * Log progress
+       */
+      progress: (message, meta = {}) => {
+        log('debug', `[${name}] ${message}`, { operation_id: operationId, ...meta });
+      },
+
+      /**
+       * Mark operation as successful
+       */
+      success: (message = 'completed', meta = {}) => {
+        const duration = Date.now() - startTime;
+        log('info', `Operation completed: ${name} - ${message}`, {
+          operation_id: operationId,
+          duration_ms: duration,
+          ...meta,
+        });
+        return { success: true, duration };
+      },
+
+      /**
+       * Mark operation as failed
+       */
+      fail: (error, meta = {}) => {
+        const duration = Date.now() - startTime;
+        const errorMessage = error instanceof Error ? error.message : error;
+        log('error', `Operation failed: ${name} - ${errorMessage}`, {
+          operation_id: operationId,
+          duration_ms: duration,
+          error: error instanceof Error ? { name: error.name, stack: error.stack } : error,
+          ...meta,
+        });
+        return { success: false, duration, error };
+      },
+    };
+  }
+
+  /**
+   * Generate a short unique ID
+   */
+  function generateId() {
+    return Math.random().toString(36).substring(2, 10);
+  }
+
+  // Return logger interface
+  return {
+    debug: (message, meta) => log('debug', message, meta),
+    info: (message, meta) => log('info', message, meta),
+    warn: (message, meta) => log('warn', message, meta),
+    error: (message, meta) => log('error', message, meta),
+    startOperation,
+    setLevel: (level) => { config.level = level; },
+    getLevel: () => config.level,
+  };
+}
+
+// Default logger instance
+const logger = createLogger({
+  level: process.env.CLAUDE_LOG_LEVEL || 'info',
+  file: process.env.CLAUDE_LOG_FILE || null,
+});
+
+module.exports = {
+  createLogger,
+  logger,
+  LOG_LEVELS,
+};