claude-context 1.2.4

package/README.md

@@ -0,0 +1,121 @@
+# claude-context
+
+CLI tools for managing Claude Context Engineering in your project.
+
+## Installation
+
+```bash
+# Use directly with npx (recommended)
+npx claude-context validate --all
+
+# Or install globally
+npm install -g claude-context
+```
+
+## Prerequisites
+
+Run `npx create-claude-context` first to initialize context engineering in your project.
+
+## Commands
+
+### Validate
+
+Validate your context engineering setup:
+
+```bash
+# Run all validations
+npx claude-context validate --all
+
+# Specific validations
+npx claude-context validate --schema        # JSON schema validation
+npx claude-context validate --links         # Internal link validation
+npx claude-context validate --placeholders  # Check for unreplaced {{PLACEHOLDERS}}
+npx claude-context validate --structure     # Directory structure validation
+npx claude-context validate --lines         # Line number accuracy check
+
+# With options
+npx claude-context validate --all --verbose
+npx claude-context validate --lines --threshold 70
+```
+
+### Sync
+
+Synchronize documentation with code changes:
+
+```bash
+# Check for drift
+npx claude-context sync --check
+
+# Auto-fix line number drift
+npx claude-context sync --fix
+
+# Rebuild CODE_TO_WORKFLOW_MAP
+npx claude-context sync --rebuild-map
+
+# Strict mode (fail on any drift)
+npx claude-context sync --check --strict
+```
+
+### Hooks
+
+Manage git hooks for automatic validation:
+
+```bash
+# Install pre-commit and post-commit hooks
+npx claude-context hooks install
+
+# Uninstall hooks
+npx claude-context hooks uninstall
+
+# Install only pre-commit
+npx claude-context hooks install --pre-commit
+```
+
+### Diagnose
+
+Run diagnostics on your setup:
+
+```bash
+# Run diagnostics
+npx claude-context diagnose
+
+# Auto-fix detected issues
+npx claude-context diagnose --fix
+
+# Verbose output
+npx claude-context diagnose --verbose
+```
+
+### Generate
+
+Generate or regenerate documentation:
+
+```bash
+# Regenerate CODE_TO_WORKFLOW_MAP.md
+npx claude-context generate --code-map
+
+# Rebuild all indexes
+npx claude-context generate --indexes
+
+# Regenerate semantic anchors
+npx claude-context generate --anchors
+```
+
+## CI/CD Integration
+
+Add to your CI pipeline:
+
+```yaml
+# GitHub Actions example
+- name: Validate context engineering
+  run: npx claude-context validate --all --strict
+```
+
+## Related
+
+- [create-claude-context](https://www.npmjs.com/package/create-claude-context) - Initial setup
+- [claude-context-plugin](https://www.npmjs.com/package/claude-context-plugin) - Claude Code plugin
+
+## License
+
+MIT

package/bin/claude-context.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Context CLI
+ *
+ * Ongoing tools for managing Claude Context Engineering in your project.
+ * Use after initial setup with `npx create-claude-context`.
+ */
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs');
+
+const { validate } = require('../lib/validate');
+const { sync } = require('../lib/sync');
+const { hooks } = require('../lib/hooks');
+const { diagnose } = require('../lib/diagnose');
+const { generate } = require('../lib/generate');
+
+const packageJson = require('../package.json');
+
+// Check if we're in a project with .claude directory
+function checkClaudeDir() {
+  const claudeDir = path.join(process.cwd(), '.claude');
+  if (!fs.existsSync(claudeDir)) {
+    console.error(chalk.red('\nError: No .claude directory found in current directory.'));
+    console.error(chalk.yellow('Run `npx create-claude-context` first to initialize.\n'));
+    process.exit(1);
+  }
+  return claudeDir;
+}
+
+program
+  .name('claude-context')
+  .description('CLI tools for Claude Context Engineering')
+  .version(packageJson.version);
+
+// Validate command
+program
+  .command('validate')
+  .description('Validate context engineering setup')
+  .option('-a, --all', 'Run all validations')
+  .option('-s, --schema', 'Validate JSON schemas')
+  .option('-l, --links', 'Validate internal links')
+  .option('-p, --placeholders', 'Check for unreplaced placeholders')
+  .option('-S, --structure', 'Validate directory structure')
+  .option('-L, --lines', 'Check line number accuracy')
+  .option('-t, --threshold <number>', 'Line accuracy threshold (default: 60)', '60')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(async (options) => {
+    checkClaudeDir();
+    try {
+      const result = await validate(process.cwd(), options);
+      process.exit(result.success ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Sync command
+program
+  .command('sync')
+  .description('Synchronize documentation with code')
+  .option('-c, --check', 'Check for drift without fixing')
+  .option('-f, --fix', 'Auto-fix shifted line numbers')
+  .option('--rebuild-map', 'Regenerate CODE_TO_WORKFLOW_MAP')
+  .option('--strict', 'Fail on any drift detected')
+  .action(async (options) => {
+    checkClaudeDir();
+    try {
+      const result = await sync(process.cwd(), options);
+      process.exit(result.success ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Hooks command
+program
+  .command('hooks')
+  .description('Manage git hooks for context engineering')
+  .argument('<action>', 'install or uninstall')
+  .option('--pre-commit', 'Only pre-commit hook')
+  .option('--post-commit', 'Only post-commit hook')
+  .action(async (action, options) => {
+    checkClaudeDir();
+    if (!['install', 'uninstall'].includes(action)) {
+      console.error(chalk.red(`Unknown action: ${action}. Use 'install' or 'uninstall'.`));
+      process.exit(1);
+    }
+    try {
+      const result = await hooks(process.cwd(), action, options);
+      process.exit(result.success ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Diagnose command
+program
+  .command('diagnose')
+  .description('Run diagnostics on context engineering setup')
+  .option('-f, --fix', 'Auto-fix detected issues')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(async (options) => {
+    checkClaudeDir();
+    try {
+      const result = await diagnose(process.cwd(), options);
+      process.exit(result.success ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Generate command
+program
+  .command('generate')
+  .description('Generate or regenerate documentation')
+  .option('--code-map', 'Regenerate CODE_TO_WORKFLOW_MAP.md')
+  .option('--indexes', 'Rebuild all indexes')
+  .option('--anchors', 'Regenerate semantic anchors')
+  .action(async (options) => {
+    checkClaudeDir();
+    try {
+      const result = await generate(process.cwd(), options);
+      process.exit(result.success ? 0 : 1);
+    } catch (error) {
+      console.error(chalk.red(`Error: ${error.message}`));
+      process.exit(1);
+    }
+  });
+
+// Parse and run
+program.parse();
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/lib/diagnose.js

@@ -0,0 +1,337 @@
+/**
+ * Diagnostics module for Claude Context Engineering
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+const chalk = require('chalk');
+
+/**
+ * Run diagnostics on context engineering setup
+ */
+async function diagnose(projectRoot, options = {}) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  const results = {
+    success: true,
+    checks: [],
+    issues: [],
+    fixed: 0
+  };
+
+  console.log(chalk.blue('\n🩺 Running diagnostics...\n'));
+
+  // Check 1: Directory structure
+  const structureCheck = checkStructure(claudeDir);
+  results.checks.push(structureCheck);
+  results.issues.push(...structureCheck.issues);
+
+  // Check 2: CLAUDE.md exists and is valid
+  const claudeMdCheck = checkClaudeMd(projectRoot);
+  results.checks.push(claudeMdCheck);
+  results.issues.push(...claudeMdCheck.issues);
+
+  // Check 3: Settings.json is valid
+  const settingsCheck = checkSettings(claudeDir);
+  results.checks.push(settingsCheck);
+  results.issues.push(...settingsCheck.issues);
+
+  // Check 4: Agent files are valid
+  const agentCheck = await checkAgents(claudeDir);
+  results.checks.push(agentCheck);
+  results.issues.push(...agentCheck.issues);
+
+  // Check 5: Command files are valid
+  const commandCheck = await checkCommands(claudeDir);
+  results.checks.push(commandCheck);
+  results.issues.push(...commandCheck.issues);
+
+  // Check 6: Workflow files exist
+  const workflowCheck = await checkWorkflows(claudeDir);
+  results.checks.push(workflowCheck);
+  results.issues.push(...workflowCheck.issues);
+
+  // Fix issues if requested
+  if (options.fix && results.issues.length > 0) {
+    results.fixed = await fixIssues(claudeDir, projectRoot, results.issues);
+  }
+
+  // Determine success
+  const criticalIssues = results.issues.filter(i => i.severity === 'error');
+  results.success = criticalIssues.length === 0;
+
+  // Print summary
+  printDiagnosticsSummary(results, options);
+
+  return results;
+}
+
+/**
+ * Check directory structure
+ */
+function checkStructure(claudeDir) {
+  const check = { name: 'Directory Structure', passed: true, issues: [] };
+
+  const requiredDirs = ['agents', 'commands', 'context', 'indexes'];
+
+  for (const dir of requiredDirs) {
+    const dirPath = path.join(claudeDir, dir);
+    if (!fs.existsSync(dirPath)) {
+      check.passed = false;
+      check.issues.push({
+        type: 'missing_directory',
+        path: dir,
+        message: `Missing required directory: ${dir}`,
+        severity: 'error',
+        fix: () => fs.mkdirSync(dirPath, { recursive: true })
+      });
+    }
+  }
+
+  console.log(check.passed
+    ? chalk.green('✓ Directory structure: OK')
+    : chalk.red(`✗ Directory structure: ${check.issues.length} issues`));
+
+  return check;
+}
+
+/**
+ * Check CLAUDE.md
+ */
+function checkClaudeMd(projectRoot) {
+  const check = { name: 'CLAUDE.md', passed: true, issues: [] };
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+
+  if (!fs.existsSync(claudeMdPath)) {
+    check.passed = false;
+    check.issues.push({
+      type: 'missing_file',
+      path: 'CLAUDE.md',
+      message: 'Missing CLAUDE.md at project root',
+      severity: 'error'
+    });
+  } else {
+    const content = fs.readFileSync(claudeMdPath, 'utf8');
+
+    // Check for unreplaced placeholders
+    const placeholders = content.match(/\{\{[A-Z_]+\}\}/g);
+    if (placeholders && placeholders.length > 10) {
+      check.passed = false;
+      check.issues.push({
+        type: 'too_many_placeholders',
+        path: 'CLAUDE.md',
+        message: `CLAUDE.md has ${placeholders.length} unreplaced placeholders`,
+        severity: 'warning'
+      });
+    }
+
+    // Check minimum content
+    if (content.length < 500) {
+      check.issues.push({
+        type: 'minimal_content',
+        path: 'CLAUDE.md',
+        message: 'CLAUDE.md seems too short',
+        severity: 'warning'
+      });
+    }
+  }
+
+  console.log(check.passed
+    ? chalk.green('✓ CLAUDE.md: OK')
+    : chalk.yellow(`⚠ CLAUDE.md: ${check.issues.length} issues`));
+
+  return check;
+}
+
+/**
+ * Check settings.json
+ */
+function checkSettings(claudeDir) {
+  const check = { name: 'Settings', passed: true, issues: [] };
+  const settingsPath = path.join(claudeDir, 'settings.json');
+
+  if (!fs.existsSync(settingsPath)) {
+    check.issues.push({
+      type: 'missing_file',
+      path: 'settings.json',
+      message: 'Missing settings.json',
+      severity: 'warning'
+    });
+  } else {
+    try {
+      const content = fs.readFileSync(settingsPath, 'utf8');
+      JSON.parse(content);
+    } catch (e) {
+      check.passed = false;
+      check.issues.push({
+        type: 'invalid_json',
+        path: 'settings.json',
+        message: `Invalid JSON: ${e.message}`,
+        severity: 'error'
+      });
+    }
+  }
+
+  console.log(check.passed
+    ? chalk.green('✓ Settings: OK')
+    : chalk.red(`✗ Settings: ${check.issues.length} issues`));
+
+  return check;
+}
+
+/**
+ * Check agent files
+ */
+async function checkAgents(claudeDir) {
+  const check = { name: 'Agents', passed: true, issues: [] };
+  const agentDir = path.join(claudeDir, 'agents');
+
+  if (!fs.existsSync(agentDir)) {
+    check.issues.push({
+      type: 'missing_directory',
+      path: 'agents',
+      message: 'No agents directory',
+      severity: 'warning'
+    });
+    return check;
+  }
+
+  const agentFiles = await glob('*.md', { cwd: agentDir });
+
+  if (agentFiles.length === 0) {
+    check.issues.push({
+      type: 'no_agents',
+      path: 'agents',
+      message: 'No agent files found',
+      severity: 'warning'
+    });
+  }
+
+  // Check each agent has required sections
+  for (const file of agentFiles) {
+    const content = fs.readFileSync(path.join(agentDir, file), 'utf8');
+
+    if (!content.includes('## Role') && !content.includes('## Purpose')) {
+      check.issues.push({
+        type: 'missing_section',
+        path: `agents/${file}`,
+        message: `Agent ${file} missing Role/Purpose section`,
+        severity: 'warning'
+      });
+    }
+  }
+
+  console.log(check.issues.length === 0
+    ? chalk.green(`✓ Agents: ${agentFiles.length} found`)
+    : chalk.yellow(`⚠ Agents: ${check.issues.length} issues`));
+
+  return check;
+}
+
+/**
+ * Check command files
+ */
+async function checkCommands(claudeDir) {
+  const check = { name: 'Commands', passed: true, issues: [] };
+  const commandDir = path.join(claudeDir, 'commands');
+
+  if (!fs.existsSync(commandDir)) {
+    check.issues.push({
+      type: 'missing_directory',
+      path: 'commands',
+      message: 'No commands directory',
+      severity: 'warning'
+    });
+    return check;
+  }
+
+  const commandFiles = await glob('*.md', { cwd: commandDir });
+
+  if (commandFiles.length === 0) {
+    check.issues.push({
+      type: 'no_commands',
+      path: 'commands',
+      message: 'No command files found',
+      severity: 'warning'
+    });
+  }
+
+  console.log(check.issues.length === 0
+    ? chalk.green(`✓ Commands: ${commandFiles.length} found`)
+    : chalk.yellow(`⚠ Commands: ${check.issues.length} issues`));
+
+  return check;
+}
+
+/**
+ * Check workflow files
+ */
+async function checkWorkflows(claudeDir) {
+  const check = { name: 'Workflows', passed: true, issues: [] };
+  const workflowDir = path.join(claudeDir, 'context', 'workflows');
+
+  if (!fs.existsSync(workflowDir)) {
+    check.issues.push({
+      type: 'missing_directory',
+      path: 'context/workflows',
+      message: 'No workflows directory',
+      severity: 'info'
+    });
+    console.log(chalk.gray('- Workflows: Not configured (run @context-engineer to create)'));
+    return check;
+  }
+
+  const workflowFiles = await glob('*.md', { cwd: workflowDir });
+
+  console.log(workflowFiles.length > 0
+    ? chalk.green(`✓ Workflows: ${workflowFiles.length} found`)
+    : chalk.gray('- Workflows: None yet'));
+
+  return check;
+}
+
+/**
+ * Fix detected issues
+ */
+async function fixIssues(claudeDir, projectRoot, issues) {
+  let fixed = 0;
+
+  for (const issue of issues) {
+    if (issue.fix && typeof issue.fix === 'function') {
+      try {
+        issue.fix();
+        fixed++;
+        console.log(chalk.green(`  ✓ Fixed: ${issue.message}`));
+      } catch (e) {
+        console.log(chalk.red(`  ✗ Failed to fix: ${issue.message}`));
+      }
+    }
+  }
+
+  return fixed;
+}
+
+/**
+ * Print diagnostics summary
+ */
+function printDiagnosticsSummary(results, options) {
+  const errors = results.issues.filter(i => i.severity === 'error').length;
+  const warnings = results.issues.filter(i => i.severity === 'warning').length;
+
+  console.log('\n' + chalk.bold('Diagnostics Summary:'));
+  console.log(`  Checks run: ${results.checks.length}`);
+  console.log(`  Errors: ${errors}`);
+  console.log(`  Warnings: ${warnings}`);
+
+  if (options.fix) {
+    console.log(`  Fixed: ${results.fixed}`);
+  }
+
+  if (results.success) {
+    console.log(chalk.green('\n✓ System healthy!\n'));
+  } else {
+    console.log(chalk.red('\n✗ Issues detected. Run with --fix to auto-repair.\n'));
+  }
+}
+
+module.exports = { diagnose };