create-universal-ai-context 2.0.0

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, 'AI_CONTEXT.md');
+    if (fs.existsSync(claudeMdPath)) {
+      const result = await replacePlaceholders(claudeMdPath, placeholderValues, { dryRun: false });
+      console.log(chalk.green(`  ✓ Replaced ${result.replaced} placeholders in AI_CONTEXT.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,
+};

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

@@ -0,0 +1,201 @@
+/**
+ * Claude Context Engineering - Placeholder Replacement Engine
+ *
+ * Finds and replaces {{PLACEHOLDER}} patterns in template files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logger } = require('./logger');
+
+/**
+ * Known placeholders with their descriptions
+ */
+const KNOWN_PLACEHOLDERS = {
+  // Project identity
+  PROJECT_NAME: { description: 'Project name', example: 'my-awesome-app' },
+  PROJECT_DESCRIPTION: { description: 'Brief project description', example: 'A web application for...' },
+  TECH_STACK: { description: 'Technologies used', example: 'Python 3.11, FastAPI, PostgreSQL' },
+  PRODUCTION_URL: { description: 'Production URL', example: 'https://api.example.com' },
+  PROJECT_STATUS: { description: 'Project status', example: 'Production' },
+
+  // URLs
+  API_URL: { description: 'API base URL', example: 'https://api.example.com/v1' },
+  REPO_URL: { description: 'Repository URL', example: 'https://github.com/user/repo' },
+  DEPLOYMENT_PLATFORM: { description: 'Where deployed', example: 'AWS ECS' },
+
+  // Commands
+  INSTALL_COMMAND: { description: 'Install dependencies command', example: 'npm install' },
+  DEV_START_COMMAND: { description: 'Start dev server command', example: 'npm run dev' },
+  TEST_COMMAND: { description: 'Run tests command', example: 'npm test' },
+  TEST_E2E_COMMAND: { description: 'Run E2E tests command', example: 'npm run test:e2e' },
+  TEST_COVERAGE_COMMAND: { description: 'Run coverage command', example: 'npm run coverage' },
+  MIGRATION_CREATE_COMMAND: { description: 'Create migration command', example: 'npm run db:migrate:create' },
+  MIGRATION_RUN_COMMAND: { description: 'Run migrations command', example: 'npm run db:migrate' },
+  DEPLOY_COMMAND: { description: 'Deploy command', example: 'npm run deploy' },
+
+  // Paths
+  MODELS_PATH: { description: 'Models directory path', example: 'src/models/' },
+  MIGRATIONS_PATH: { description: 'Migrations directory path', example: 'src/migrations/' },
+  CORE_FILES_LIST: { description: 'List of core files', example: '- src/services/\n- src/models/' },
+
+  // Patterns
+  CONFIG_SEARCH_PATTERN: { description: 'Config search grep pattern', example: 'grep -r "process.env" src/' },
+  URL_SEARCH_PATTERN: { description: 'URL search grep pattern', example: 'grep -rE "https?://" src/' },
+
+  // Architecture
+  ARCHITECTURE_DIAGRAM: { description: 'ASCII architecture diagram', example: '```\nClient → API → DB\n```' },
+  EXTERNAL_INTEGRATIONS_LIST: { description: 'List of external integrations', example: '- Stripe: payments\n- SendGrid: email' },
+
+  // Counts
+  WORKFLOWS_COUNT: { description: 'Number of workflows', example: '12' },
+  WORKFLOW_DOMAINS_COUNT: { description: 'Number of workflow domains', example: '5' },
+  CODE_DOMAINS_COUNT: { description: 'Number of code domains', example: '4' },
+  AGENTS_COUNT: { description: 'Number of agents', example: '6' },
+  COMMANDS_COUNT: { description: 'Number of commands', example: '5' },
+  INDEX_FILES_COUNT: { description: 'Number of index files', example: '25' },
+
+  // Meta
+  DATE: { description: 'Current date', example: '2025-12-06' },
+
+  // Quick references
+  DEBUGGING_QUICK_REFS: { description: 'Quick debug references', example: '[logs.md], [errors.md]' },
+  CRITICAL_URLS: { description: 'Critical URLs list', example: '- API: https://...\n- Admin: https://...' },
+  BUSINESS_CONSTANTS: { description: 'Business constants', example: '- MAX_USERS: 1000' },
+
+  // Gotchas
+  GOTCHA_CATEGORY_1: { description: 'First gotcha category', example: 'Authentication' },
+  GOTCHA_1_ITEMS: { description: 'First gotcha items', example: '- Token expiry: 24h' },
+  GOTCHA_CATEGORY_2: { description: 'Second gotcha category', example: 'Database' },
+  GOTCHA_2_ITEMS: { description: 'Second gotcha items', example: '- Connection pooling required' },
+
+  // Agent/command routing
+  AGENT_ROUTING_TABLE: { description: 'Agent routing reference', example: '| Task | Agent |\n|---|---|' },
+  COMMAND_LIST: { description: 'Command list', example: '/rpi-research, /rpi-plan' },
+
+  // Tasks
+  EXAMPLE_REFACTOR_TASK: { description: 'Example refactor task', example: 'Refactor authentication flow' },
+  EXAMPLE_LOWLEVEL_TASK: { description: 'Example low-level task', example: 'Fix hardcoded API URL' },
+  EXAMPLE_FEATURE_TASK: { description: 'Example feature task', example: 'Add user profile page' },
+
+  // Production
+  PRODUCTION_PLATFORM: { description: 'Production platform', example: 'AWS' },
+  PRODUCTION_SERVICES: { description: 'Production services', example: 'ECS, RDS, ElastiCache' },
+  MONITORING_COMMANDS: { description: 'Monitoring commands', example: 'kubectl logs, aws logs' },
+
+  // Constraints
+  MIGRATION_CONSTRAINTS: { description: 'Migration constraints', example: 'Always backup first' },
+  TESTING_CONSTRAINTS: { description: 'Testing constraints', example: 'Must pass CI before merge' },
+  SECURITY_CONSTRAINTS: { description: 'Security constraints', example: 'No secrets in code' },
+
+  // Contact
+  CONTACT_INFO: { description: 'Contact information', example: 'team@example.com' },
+};
+
+/**
+ * Replace placeholders in a file
+ */
+async function replacePlaceholders(filePath, values, options = {}) {
+  const { dryRun = false, backup = true } = options;
+
+  const result = {
+    file: filePath,
+    replaced: 0,
+    remaining: 0,
+    replacements: [],
+  };
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+
+  // Find all placeholders
+  const found = new Set();
+  let match;
+  while ((match = placeholderPattern.exec(content)) !== null) {
+    found.add(match[1]);
+  }
+
+  // Replace placeholders with provided values
+  for (const placeholder of found) {
+    const value = values[placeholder];
+
+    if (value !== undefined && value !== `{{${placeholder}}}`) {
+      const pattern = new RegExp(`\\{\\{${placeholder}\\}\\}`, 'g');
+      const before = content;
+      content = content.replace(pattern, value);
+
+      if (content !== before) {
+        result.replaced++;
+        result.replacements.push({
+          placeholder,
+          value: value.substring(0, 50) + (value.length > 50 ? '...' : ''),
+        });
+      }
+    } else {
+      result.remaining++;
+    }
+  }
+
+  // Write changes
+  if (!dryRun && result.replaced > 0) {
+    if (backup) {
+      const backupPath = filePath + '.bak';
+      fs.copyFileSync(filePath, backupPath);
+    }
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+
+  return result;
+}
+
+/**
+ * Find all placeholders in a file
+ */
+function findPlaceholders(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+
+  const found = [];
+  let match;
+
+  while ((match = placeholderPattern.exec(content)) !== null) {
+    found.push({
+      placeholder: match[0],
+      name: match[1],
+      index: match.index,
+      known: KNOWN_PLACEHOLDERS.hasOwnProperty(match[1]),
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Get placeholder information
+ */
+function getPlaceholderInfo(name) {
+  return KNOWN_PLACEHOLDERS[name] || null;
+}
+
+/**
+ * List all known placeholders
+ */
+function listKnownPlaceholders() {
+  return Object.entries(KNOWN_PLACEHOLDERS).map(([name, info]) => ({
+    name,
+    placeholder: `{{${name}}}`,
+    ...info,
+  }));
+}
+
+module.exports = {
+  replacePlaceholders,
+  findPlaceholders,
+  getPlaceholderInfo,
+  listKnownPlaceholders,
+  KNOWN_PLACEHOLDERS,
+};