create-claude-context 1.0.0

package/lib/placeholder.js

@@ -0,0 +1,208 @@
+/**
+ * Claude Context Engineering - Placeholder Replacement Engine
+ *
+ * Finds and replaces {{PLACEHOLDER}} patterns in template files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+
+/**
+ * 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/' },
+
+  // Counts
+  WORKFLOWS_COUNT: { description: 'Number of workflows', example: '12' },
+  AGENTS_COUNT: { description: 'Number of agents', example: '6' },
+  COMMANDS_COUNT: { description: 'Number of commands', example: '8' },
+
+  // Meta
+  DATE: { description: 'Current date', example: '2025-01-24' },
+  AGENT_TABLE_ROWS: { description: 'Agent table rows', example: '| core-architect | System design |' },
+};
+
+/**
+ * Get default placeholder values based on config and tech stack
+ */
+function getDefaultValues(config = {}, techStack = {}) {
+  const today = new Date().toISOString().split('T')[0];
+  const projectName = config.projectName || 'my-project';
+
+  // Determine commands based on tech stack
+  let commands = {
+    install: 'npm install',
+    dev: 'npm run dev',
+    test: 'npm test',
+    migrate: 'npm run migrate'
+  };
+
+  if (techStack.commands) {
+    commands = techStack.commands;
+  } else if (techStack.languages?.includes('python')) {
+    commands = {
+      install: 'pip install -r requirements.txt',
+      dev: 'python main.py',
+      test: 'pytest',
+      migrate: 'alembic upgrade head'
+    };
+  } else if (techStack.languages?.includes('go')) {
+    commands = {
+      install: 'go mod download',
+      dev: 'go run .',
+      test: 'go test ./...',
+      migrate: 'migrate -path migrations up'
+    };
+  } else if (techStack.languages?.includes('rust')) {
+    commands = {
+      install: 'cargo build',
+      dev: 'cargo run',
+      test: 'cargo test',
+      migrate: 'sqlx migrate run'
+    };
+  }
+
+  return {
+    PROJECT_NAME: projectName,
+    PROJECT_DESCRIPTION: `${projectName} application`,
+    TECH_STACK: techStack.summary || techStack.stack || 'Not detected',
+    PRODUCTION_URL: `https://${projectName}.example.com`,
+    PROJECT_STATUS: 'Development',
+    API_URL: `https://api.${projectName}.example.com`,
+    REPO_URL: `https://github.com/user/${projectName}`,
+    DEPLOYMENT_PLATFORM: 'Docker',
+    INSTALL_COMMAND: commands.install,
+    DEV_START_COMMAND: commands.dev,
+    TEST_COMMAND: commands.test,
+    TEST_E2E_COMMAND: `${commands.test} --e2e`,
+    TEST_COVERAGE_COMMAND: `${commands.test} --coverage`,
+    MIGRATION_CREATE_COMMAND: `${commands.migrate}:create`,
+    MIGRATION_RUN_COMMAND: commands.migrate,
+    DEPLOY_COMMAND: 'docker-compose up -d',
+    MODELS_PATH: 'src/models/',
+    MIGRATIONS_PATH: 'src/migrations/',
+    CORE_FILES_LIST: '- src/\n- config/',
+    WORKFLOWS_COUNT: '8',
+    AGENTS_COUNT: '6',
+    COMMANDS_COUNT: '8',
+    DATE: today,
+    AGENT_TABLE_ROWS: '',
+  };
+}
+
+/**
+ * Replace placeholders in all files in a directory
+ */
+async function replacePlaceholders(targetDir, config = {}) {
+  const claudeDir = path.join(targetDir, '.claude');
+  const values = getDefaultValues(config, config.techStack || {});
+
+  // Find all markdown and JSON files
+  const files = await glob('**/*.{md,json}', {
+    cwd: claudeDir,
+    ignore: ['node_modules/**', '.git/**'],
+    nodir: true,
+    absolute: true
+  });
+
+  let totalReplaced = 0;
+
+  for (const filePath of files) {
+    try {
+      let content = fs.readFileSync(filePath, 'utf8');
+      const originalContent = content;
+
+      // Replace all placeholders
+      for (const [key, value] of Object.entries(values)) {
+        const pattern = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+        content = content.replace(pattern, String(value));
+      }
+
+      if (content !== originalContent) {
+        fs.writeFileSync(filePath, content, 'utf8');
+        totalReplaced++;
+      }
+    } catch (error) {
+      // Skip files that can't be read
+    }
+  }
+
+  // Also replace in CLAUDE.md at root
+  const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    try {
+      let content = fs.readFileSync(claudeMdPath, 'utf8');
+      const originalContent = content;
+
+      for (const [key, value] of Object.entries(values)) {
+        const pattern = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+        content = content.replace(pattern, String(value));
+      }
+
+      if (content !== originalContent) {
+        fs.writeFileSync(claudeMdPath, content, 'utf8');
+        totalReplaced++;
+      }
+    } catch (error) {
+      // Skip if can't read
+    }
+  }
+
+  return totalReplaced;
+}
+
+/**
+ * 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;
+}
+
+module.exports = {
+  replacePlaceholders,
+  findPlaceholders,
+  getDefaultValues,
+  KNOWN_PLACEHOLDERS,
+};

package/lib/prompts.js

@@ -0,0 +1,287 @@
+/**
+ * Interactive prompts for create-claude-context
+ *
+ * Uses enquirer for beautiful, user-friendly prompts
+ */
+
+const { prompt } = require('enquirer');
+const path = require('path');
+const chalk = require('chalk');
+const { detectTechStack } = require('./detector');
+
+// Available tech stack presets
+const PRESETS = {
+  'python-fastapi': {
+    name: 'Python + FastAPI + PostgreSQL',
+    stack: 'Python, FastAPI, PostgreSQL',
+    commands: {
+      install: 'pip install -r requirements.txt',
+      dev: 'uvicorn main:app --reload',
+      test: 'pytest',
+      migrate: 'alembic upgrade head'
+    }
+  },
+  'node-express': {
+    name: 'Node.js + Express + MongoDB',
+    stack: 'Node.js, Express, MongoDB',
+    commands: {
+      install: 'npm install',
+      dev: 'npm run dev',
+      test: 'npm test',
+      migrate: 'npm run migrate'
+    }
+  },
+  'typescript-nextjs': {
+    name: 'TypeScript + Next.js + Prisma',
+    stack: 'TypeScript, Next.js, Prisma, PostgreSQL',
+    commands: {
+      install: 'npm install',
+      dev: 'npm run dev',
+      test: 'npm test',
+      migrate: 'npx prisma migrate dev'
+    }
+  },
+  'go-gin': {
+    name: 'Go + Gin + PostgreSQL',
+    stack: 'Go, Gin, PostgreSQL',
+    commands: {
+      install: 'go mod download',
+      dev: 'go run main.go',
+      test: 'go test ./...',
+      migrate: 'migrate -path migrations -database $DATABASE_URL up'
+    }
+  },
+  'rust-actix': {
+    name: 'Rust + Actix + SQLx',
+    stack: 'Rust, Actix-web, SQLx, PostgreSQL',
+    commands: {
+      install: 'cargo build',
+      dev: 'cargo run',
+      test: 'cargo test',
+      migrate: 'sqlx migrate run'
+    }
+  },
+  'ruby-rails': {
+    name: 'Ruby + Rails + PostgreSQL',
+    stack: 'Ruby, Rails, PostgreSQL',
+    commands: {
+      install: 'bundle install',
+      dev: 'rails server',
+      test: 'rails test',
+      migrate: 'rails db:migrate'
+    }
+  },
+  'python-django': {
+    name: 'Python + Django + PostgreSQL',
+    stack: 'Python, Django, PostgreSQL',
+    commands: {
+      install: 'pip install -r requirements.txt',
+      dev: 'python manage.py runserver',
+      test: 'python manage.py test',
+      migrate: 'python manage.py migrate'
+    }
+  },
+  'node-nestjs': {
+    name: 'Node.js + NestJS + TypeORM',
+    stack: 'Node.js, NestJS, TypeORM, PostgreSQL',
+    commands: {
+      install: 'npm install',
+      dev: 'npm run start:dev',
+      test: 'npm run test',
+      migrate: 'npm run migration:run'
+    }
+  },
+  'typescript-remix': {
+    name: 'TypeScript + Remix + Prisma',
+    stack: 'TypeScript, Remix, Prisma, PostgreSQL',
+    commands: {
+      install: 'npm install',
+      dev: 'npm run dev',
+      test: 'npm test',
+      migrate: 'npx prisma migrate dev'
+    }
+  },
+  'java-spring': {
+    name: 'Java + Spring Boot + PostgreSQL',
+    stack: 'Java, Spring Boot, PostgreSQL',
+    commands: {
+      install: 'mvn install',
+      dev: 'mvn spring-boot:run',
+      test: 'mvn test',
+      migrate: 'mvn flyway:migrate'
+    }
+  },
+  'csharp-dotnet': {
+    name: 'C# + .NET Core + Entity Framework',
+    stack: 'C#, .NET Core, Entity Framework, PostgreSQL',
+    commands: {
+      install: 'dotnet restore',
+      dev: 'dotnet run',
+      test: 'dotnet test',
+      migrate: 'dotnet ef database update'
+    }
+  },
+  'php-laravel': {
+    name: 'PHP + Laravel + MySQL',
+    stack: 'PHP, Laravel, MySQL',
+    commands: {
+      install: 'composer install',
+      dev: 'php artisan serve',
+      test: 'php artisan test',
+      migrate: 'php artisan migrate'
+    }
+  }
+};
+
+/**
+ * Run interactive prompts
+ */
+async function runPrompts(targetDir, presetName = null) {
+  // Detect tech stack for auto-suggestion
+  const detected = await detectTechStack(targetDir);
+
+  console.log(chalk.gray('\nLet\'s set up context engineering for your project.\n'));
+
+  const answers = await prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      initial: path.basename(targetDir),
+      validate: (value) => {
+        if (!value.trim()) return 'Project name is required';
+        if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+          return 'Project name can only contain letters, numbers, hyphens, and underscores';
+        }
+        return true;
+      }
+    },
+    {
+      type: 'select',
+      name: 'techStackChoice',
+      message: 'Technology stack:',
+      choices: [
+        {
+          name: 'auto',
+          message: detected.summary
+            ? `Confirm: ${detected.summary}`
+            : 'Auto-detect from project files'
+        },
+        { name: 'preset', message: 'Select from presets' },
+        { name: 'manual', message: 'Enter manually' },
+        { name: 'skip', message: 'Skip (use generic template)' }
+      ],
+      initial: 0
+    },
+    {
+      type: 'select',
+      name: 'preset',
+      message: 'Select a tech stack preset:',
+      choices: Object.entries(PRESETS).map(([key, value]) => ({
+        name: key,
+        message: value.name
+      })),
+      skip() {
+        return this.state.answers.techStackChoice !== 'preset';
+      }
+    },
+    {
+      type: 'input',
+      name: 'manualStack',
+      message: 'Enter your tech stack (e.g., "Python, Django, PostgreSQL"):',
+      skip() {
+        return this.state.answers.techStackChoice !== 'manual';
+      }
+    },
+    {
+      type: 'multiselect',
+      name: 'features',
+      message: 'Features to include:',
+      choices: [
+        { name: 'rpi', message: 'RPI Workflow (Research-Plan-Implement)', value: true },
+        { name: 'agents', message: 'Specialized Agents (6 agents)', value: true },
+        { name: 'validation', message: 'Validation Commands', value: true },
+        { name: 'ci', message: 'CI/CD Templates', value: false },
+        { name: 'team', message: 'Team Collaboration', value: false },
+        { name: 'analytics', message: 'Analytics Dashboard', value: false }
+      ],
+      initial: ['rpi', 'agents', 'validation']
+    },
+    {
+      type: 'confirm',
+      name: 'installPlugin',
+      message: 'Install Claude Code plugin for ongoing commands?',
+      initial: true
+    }
+  ]);
+
+  // Process tech stack choice
+  let techStack = detected;
+  if (answers.techStackChoice === 'preset' && answers.preset) {
+    const preset = PRESETS[answers.preset];
+    techStack = {
+      ...techStack,
+      summary: preset.stack,
+      preset: answers.preset,
+      commands: preset.commands
+    };
+  } else if (answers.techStackChoice === 'manual' && answers.manualStack) {
+    techStack = {
+      ...techStack,
+      summary: answers.manualStack,
+      preset: null
+    };
+  }
+
+  return {
+    projectName: answers.projectName,
+    techStack,
+    features: {
+      rpi: answers.features.includes('rpi'),
+      agents: answers.features.includes('agents'),
+      validation: answers.features.includes('validation'),
+      ci: answers.features.includes('ci'),
+      team: answers.features.includes('team'),
+      analytics: answers.features.includes('analytics')
+    },
+    installPlugin: answers.installPlugin
+  };
+}
+
+/**
+ * Get default configuration (for --yes flag)
+ */
+async function getDefaults(targetDir, presetName = null) {
+  const detected = await detectTechStack(targetDir);
+
+  let techStack = detected;
+  if (presetName && PRESETS[presetName]) {
+    const preset = PRESETS[presetName];
+    techStack = {
+      ...techStack,
+      summary: preset.stack,
+      preset: presetName,
+      commands: preset.commands
+    };
+  }
+
+  return {
+    projectName: path.basename(targetDir),
+    techStack,
+    features: {
+      rpi: true,
+      agents: true,
+      validation: true,
+      ci: false,
+      team: false,
+      analytics: false
+    },
+    installPlugin: true
+  };
+}
+
+module.exports = {
+  runPrompts,
+  getDefaults,
+  PRESETS
+};

package/lib/spinner.js

@@ -0,0 +1,60 @@
+/**
+ * Spinner utilities for create-claude-context
+ *
+ * Provides consistent progress indicators using ora
+ */
+
+const ora = require('ora');
+const chalk = require('chalk');
+
+/**
+ * Create a spinner instance with consistent styling
+ */
+function createSpinner(text = '') {
+  return ora({
+    text,
+    color: 'cyan',
+    spinner: 'dots'
+  });
+}
+
+/**
+ * Run a task with spinner feedback
+ * @param {string} text - Text to display while running
+ * @param {Function} task - Async function to run
+ * @returns {Promise<any>} - Result of the task
+ */
+async function withSpinner(text, task) {
+  const spinner = createSpinner(text);
+  spinner.start();
+
+  try {
+    const result = await task();
+    spinner.succeed();
+    return result;
+  } catch (error) {
+    spinner.fail(chalk.red(error.message));
+    throw error;
+  }
+}
+
+/**
+ * Display a progress list
+ * @param {Array<{text: string, task: Function}>} items - List of tasks
+ */
+async function progressList(items) {
+  const results = [];
+
+  for (const item of items) {
+    const result = await withSpinner(item.text, item.task);
+    results.push(result);
+  }
+
+  return results;
+}
+
+module.exports = {
+  createSpinner,
+  withSpinner,
+  progressList
+};

package/lib/validate.js

@@ -0,0 +1,147 @@
+/**
+ * Claude Context Engineering - Installation Validator
+ *
+ * Validates the installation was successful.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Required files and directories for a valid installation
+ */
+const REQUIRED_STRUCTURE = {
+  directories: [
+    '.claude',
+    '.claude/context',
+    '.claude/research',
+    '.claude/plans',
+  ],
+  files: [
+    'CLAUDE.md',
+    '.claude/README.md',
+    '.claude/settings.json',
+    '.claude/context/WORKFLOW_INDEX.md',
+  ],
+};
+
+/**
+ * Validate the installation
+ */
+async function validateInstallation(targetDir) {
+  const result = {
+    passed: true,
+    warnings: 0,
+    errors: 0,
+    checks: [],
+  };
+
+  // Check required directories
+  for (const dir of REQUIRED_STRUCTURE.directories) {
+    const fullPath = path.join(targetDir, dir);
+    const exists = fs.existsSync(fullPath);
+
+    result.checks.push({
+      type: 'directory',
+      path: dir,
+      status: exists ? 'PASS' : 'FAIL',
+    });
+
+    if (!exists) {
+      result.errors++;
+      result.passed = false;
+    }
+  }
+
+  // Check required files
+  for (const file of REQUIRED_STRUCTURE.files) {
+    const fullPath = path.join(targetDir, file);
+    const exists = fs.existsSync(fullPath);
+
+    result.checks.push({
+      type: 'file',
+      path: file,
+      status: exists ? 'PASS' : 'FAIL',
+    });
+
+    if (!exists) {
+      result.errors++;
+      result.passed = false;
+    }
+  }
+
+  // Check for remaining placeholders in key files
+  const filesToCheck = [
+    'CLAUDE.md',
+    '.claude/README.md',
+    '.claude/settings.json',
+  ];
+
+  for (const file of filesToCheck) {
+    const fullPath = path.join(targetDir, file);
+    if (fs.existsSync(fullPath)) {
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const placeholders = content.match(/\{\{[A-Z_]+\}\}/g) || [];
+
+      if (placeholders.length > 0) {
+        result.checks.push({
+          type: 'placeholders',
+          path: file,
+          status: 'WARN',
+          details: `${placeholders.length} placeholders remaining`,
+        });
+        result.warnings++;
+      }
+    }
+  }
+
+  // Validate settings.json is valid JSON
+  const settingsPath = path.join(targetDir, '.claude', 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      result.checks.push({
+        type: 'json',
+        path: '.claude/settings.json',
+        status: 'PASS',
+      });
+    } catch (e) {
+      result.checks.push({
+        type: 'json',
+        path: '.claude/settings.json',
+        status: 'FAIL',
+        details: 'Invalid JSON',
+      });
+      result.errors++;
+      result.passed = false;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Count files in a directory
+ */
+function countFiles(dir, pattern = '*') {
+  if (!fs.existsSync(dir)) return 0;
+
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isFile()) {
+      count++;
+    } else if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name), pattern);
+    }
+  }
+
+  return count;
+}
+
+module.exports = {
+  validateInstallation,
+  countFiles,
+  REQUIRED_STRUCTURE,
+};