context-engineer 1.1.0

package/README.md

@@ -0,0 +1,88 @@
+# context-engineer
+
+Structured context management for AI coding agents. Install the `.context/` system into any project with a single command.
+
+## Quick Start
+
+```bash
+npx context-engineer init
+```
+
+This installs the context engineering system into your current project directory. Then open Claude Code and run:
+
+```
+/bootstrap-context
+```
+
+This analyzes your codebase and populates the context files with your project's specifics.
+
+## What Gets Installed
+
+| Component | Contents | Default |
+|-----------|----------|---------|
+| **Core** | `.context/` directory, `scripts/`, `AGENTS.md` | Always |
+| **Claude Code** | `.claude/` (skills, rules, hooks), `CLAUDE.md` | Yes |
+| **Cursor** | `.cursor/rules/`, `.cursorrules` | Optional |
+| **GitHub** | Copilot instructions, CI drift detection workflow | Optional |
+
+## Usage
+
+### Interactive Install
+
+```bash
+npx context-engineer init
+```
+
+Prompts you to select which AI tool integrations to install.
+
+### Preset Install
+
+```bash
+# Core + Claude Code (most common)
+npx context-engineer init --preset claude
+
+# Everything
+npx context-engineer init --preset all
+
+# Core only (no tool integrations)
+npx context-engineer init --preset core
+
+# Core + Cursor
+npx context-engineer init --preset cursor
+```
+
+### Options
+
+```bash
+npx context-engineer init --force        # Overwrite existing files
+npx context-engineer init --dry-run      # Preview without writing
+npx context-engineer init --dir ./myapp  # Install to a specific directory
+```
+
+### Update Templates
+
+```bash
+npx context-engineer update          # Update to latest templates
+npx context-engineer update --check  # Check for updates without applying
+```
+
+## After Installation
+
+1. **Claude Code**: Run `/bootstrap-context` to populate templates from your codebase
+2. **Cursor**: The `.cursor/rules/` files activate automatically
+3. **GitHub Copilot**: The `.github/copilot-instructions.md` activates automatically
+4. **All tools**: Read `AGENTS.md` for the universal entry point
+
+## How It Works
+
+The context system provides AI coding agents with structured project knowledge:
+
+- **`.context/constitution.md`** — Project identity, principles, and a route table that tells agents what to load
+- **`.context/architecture/`** — Tech stack, data models, API surface, module graph
+- **`.context/conventions/`** — Code style, patterns, testing, error handling
+- **`.context/experience/`** — Lessons learned, debugging solutions, performance insights
+- **`scripts/`** — Drift detection, context sync, structure extraction
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import { resolve } from 'path';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkgPath = join(__dirname, '..', 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--preset' && args[i + 1]) {
+      flags.preset = args[++i];
+    } else if (arg === '--dir' && args[i + 1]) {
+      flags.dir = resolve(args[++i]);
+    } else if (arg === '--force') {
+      flags.force = true;
+    } else if (arg === '--dry-run') {
+      flags.dryRun = true;
+    } else if (arg === '--check') {
+      flags.check = true;
+    }
+  }
+  return flags;
+}
+
+function printHelp() {
+  console.log(`
+  context-engineer v${pkg.version}
+  Structured context management for AI coding agents
+
+  Usage:
+    context-engineer init [options]     Install context system into current project
+    context-engineer update [options]   Update templates to latest version
+
+  Init options:
+    --preset <name>   Skip prompts (all, claude, cursor, core)
+    --dir <path>      Target directory (default: current directory)
+    --force           Overwrite existing files without asking
+    --dry-run         Show what would be installed without writing
+
+  Update options:
+    --check           Only check for updates, don't apply
+    --force           Overwrite all files including customized ones
+
+  Examples:
+    npx context-engineer init
+    npx context-engineer init --preset claude
+    npx context-engineer init --preset all --dry-run
+    npx context-engineer update --check
+`);
+}
+
+async function main() {
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(pkg.version);
+    return;
+  }
+
+  if (args.includes('--help') || args.includes('-h') || !command) {
+    printHelp();
+    return;
+  }
+
+  const flags = parseFlags(args);
+
+  if (command === 'init') {
+    const { runInit } = await import('../lib/init.mjs');
+    await runInit(flags);
+  } else if (command === 'update') {
+    const { runUpdate } = await import('../lib/update.mjs');
+    await runUpdate(flags);
+  } else {
+    console.error(`  Unknown command: ${command}\n`);
+    printHelp();
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('\n  Error:', err.message);
+  process.exit(1);
+});

package/lib/copy.mjs

@@ -0,0 +1,102 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, readdirSync, statSync } from 'fs';
+import { join, dirname, relative } from 'path';
+import { createHash } from 'crypto';
+
+/**
+ * Recursively list all files in a directory (relative paths).
+ */
+export function walkDir(dir, base = dir) {
+  const results = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) {
+      results.push(...walkDir(full, base));
+    } else {
+      results.push(relative(base, full));
+    }
+  }
+  return results;
+}
+
+/**
+ * Compute SHA-256 hash of a file's contents.
+ */
+export function fileHash(filePath) {
+  const content = readFileSync(filePath);
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Copy a template group to the target directory.
+ *
+ * @param {string} templateDir - Absolute path to the group's template directory
+ * @param {string} targetDir - Absolute path to the target project directory
+ * @param {object} options
+ * @param {boolean} options.force - Overwrite without asking
+ * @param {boolean} options.dryRun - Don't actually write files
+ * @param {function} options.onConflict - async (relPath) => 'skip' | 'overwrite'
+ * @param {object} options.replacements - key-value pairs to replace in file contents
+ * @returns {{ created: string[], skipped: string[], overwritten: string[] }}
+ */
+export async function copyTemplateGroup(templateDir, targetDir, options = {}) {
+  const { force = false, dryRun = false, onConflict, replacements = {} } = options;
+  const report = { created: [], skipped: [], overwritten: [] };
+
+  if (!existsSync(templateDir)) {
+    return report;
+  }
+
+  const files = walkDir(templateDir);
+  const isWindows = process.platform === 'win32';
+
+  for (const relPath of files) {
+    const srcPath = join(templateDir, relPath);
+    const destPath = join(targetDir, relPath);
+
+    // Read source file as binary buffer
+    let content = readFileSync(srcPath);
+
+    // Apply replacements (only for text files)
+    if (Object.keys(replacements).length > 0) {
+      let text = content.toString('utf8');
+      for (const [key, value] of Object.entries(replacements)) {
+        text = text.split(key).join(value);
+      }
+      content = Buffer.from(text, 'utf8');
+    }
+
+    const destExists = existsSync(destPath);
+
+    if (destExists) {
+      if (force) {
+        // Overwrite
+      } else if (onConflict) {
+        const action = await onConflict(relPath);
+        if (action === 'skip') {
+          report.skipped.push(relPath);
+          continue;
+        }
+      } else {
+        report.skipped.push(relPath);
+        continue;
+      }
+      report.overwritten.push(relPath);
+    } else {
+      report.created.push(relPath);
+    }
+
+    if (!dryRun) {
+      mkdirSync(dirname(destPath), { recursive: true });
+      // Write in binary mode to preserve LF line endings
+      writeFileSync(destPath, content);
+
+      // Set executable permission on scripts (POSIX only)
+      if (!isWindows && relPath.startsWith('scripts/') && relPath.endsWith('.sh')) {
+        chmodSync(destPath, 0o755);
+      }
+    }
+  }
+
+  return report;
+}

package/lib/init.mjs

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { copyTemplateGroup, walkDir, fileHash } from './copy.mjs';
+import { multiSelect, conflictStrategy, askFileConflict } from './prompts.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const PKG = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const GROUPS = [
+  {
+    id: 'core',
+    label: 'Core (.context/ + scripts/ + AGENTS.md)',
+    checked: true,
+    required: true,
+  },
+  {
+    id: 'claude',
+    label: 'Claude Code (.claude/ + CLAUDE.md)',
+    checked: true,
+    required: false,
+  },
+  {
+    id: 'cursor',
+    label: 'Cursor (.cursor/ + .cursorrules)',
+    checked: false,
+    required: false,
+  },
+  {
+    id: 'github',
+    label: 'GitHub (Copilot instructions + CI drift check)',
+    checked: false,
+    required: false,
+  },
+];
+
+const PRESETS = {
+  all: ['core', 'claude', 'cursor', 'github'],
+  claude: ['core', 'claude'],
+  cursor: ['core', 'cursor'],
+  core: ['core'],
+};
+
+export async function runInit(flags) {
+  const targetDir = flags.dir || process.cwd();
+  const { force = false, dryRun = false } = flags;
+
+  console.log(`\n  context-engineer v${PKG.version}`);
+  console.log('  Structured context for AI coding agents\n');
+
+  // Determine selected groups
+  let selectedIds;
+  if (flags.preset) {
+    selectedIds = PRESETS[flags.preset];
+    if (!selectedIds) {
+      console.error(`  Unknown preset: ${flags.preset}`);
+      console.error(`  Available: ${Object.keys(PRESETS).join(', ')}`);
+      process.exit(1);
+    }
+    console.log(`  Using preset: ${flags.preset}`);
+  } else {
+    selectedIds = await multiSelect('Which AI tool integrations?', GROUPS);
+  }
+
+  console.log(`  Target: ${targetDir}`);
+  if (dryRun) console.log('  Mode: dry run (no files will be written)\n');
+  else console.log('');
+
+  // Scan for conflicts across all selected groups
+  let totalConflicts = 0;
+  const allConflicts = [];
+  for (const groupId of selectedIds) {
+    const groupDir = join(TEMPLATES_DIR, groupId);
+    if (!existsSync(groupDir)) continue;
+    for (const relPath of walkDir(groupDir)) {
+      if (existsSync(join(targetDir, relPath))) {
+        allConflicts.push(relPath);
+        totalConflicts++;
+      }
+    }
+  }
+
+  // Determine conflict strategy
+  let strategy = 'skip';
+  if (totalConflicts > 0 && !force) {
+    strategy = await conflictStrategy(totalConflicts);
+  } else if (force) {
+    strategy = 'overwrite';
+  }
+
+  // Copy each group
+  const totals = { created: [], skipped: [], overwritten: [] };
+
+  for (const groupId of selectedIds) {
+    const groupDir = join(TEMPLATES_DIR, groupId);
+
+    const onConflict =
+      strategy === 'overwrite'
+        ? () => 'overwrite'
+        : strategy === 'ask'
+          ? (relPath) => askFileConflict(relPath)
+          : () => 'skip';
+
+    const report = await copyTemplateGroup(groupDir, targetDir, {
+      force: strategy === 'overwrite',
+      dryRun,
+      onConflict: strategy !== 'overwrite' ? onConflict : undefined,
+      replacements: {
+        __CE_VERSION__: PKG.version,
+      },
+    });
+
+    totals.created.push(...report.created);
+    totals.skipped.push(...report.skipped);
+    totals.overwritten.push(...report.overwritten);
+  }
+
+  // Save installed checksums for future update diffing
+  if (!dryRun) {
+    const installedChecksums = {};
+    for (const groupId of selectedIds) {
+      const groupDir = join(TEMPLATES_DIR, groupId);
+      if (!existsSync(groupDir)) continue;
+      for (const relPath of walkDir(groupDir)) {
+        const destPath = join(targetDir, relPath);
+        if (existsSync(destPath)) {
+          installedChecksums[relPath] = fileHash(destPath);
+        }
+      }
+    }
+    const ceMetaDir = join(targetDir, '.context', '_meta');
+    mkdirSync(ceMetaDir, { recursive: true });
+    writeFileSync(
+      join(ceMetaDir, '.ce-checksums.json'),
+      JSON.stringify(installedChecksums, null, 2) + '\n'
+    );
+  }
+
+  // Print summary
+  const prefix = dryRun ? 'Would install' : 'Installed';
+  console.log(`  ${prefix}: ${totals.created.length} new file(s)`);
+  if (totals.overwritten.length > 0) {
+    console.log(`  Overwritten: ${totals.overwritten.length} file(s)`);
+  }
+  if (totals.skipped.length > 0) {
+    console.log(`  Skipped: ${totals.skipped.length} existing file(s)`);
+  }
+
+  // Next steps
+  if (!dryRun) {
+    console.log('\n  Next steps:');
+    if (selectedIds.includes('claude')) {
+      console.log('    1. Open Claude Code in this project');
+      console.log('    2. Run /bootstrap-context to populate templates');
+    } else {
+      console.log('    1. Fill in the template placeholders in .context/ files');
+      console.log('    2. Edit AGENTS.md with your project details');
+    }
+    console.log(`    ${selectedIds.includes('claude') ? '3' : '3'}. Commit: git add .context ${selectedIds.includes('claude') ? '.claude ' : ''}AGENTS.md && git commit -m "Add context engineering system"`);
+  }
+
+  console.log('');
+}

package/lib/prompts.mjs

@@ -0,0 +1,144 @@
+import { createInterface } from 'readline';
+
+function createRL() {
+  return createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+/**
+ * Ask a yes/no question. Returns true for yes.
+ */
+export async function confirm(message, defaultYes = true) {
+  const rl = createRL();
+  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+  return new Promise((resolve) => {
+    rl.question(`  ${message} ${suffix} `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      if (a === '') resolve(defaultYes);
+      else resolve(a === 'y' || a === 'yes');
+    });
+  });
+}
+
+/**
+ * Multi-select checkbox prompt.
+ * Returns array of selected item ids.
+ *
+ * @param {string} message
+ * @param {{ id: string, label: string, checked: boolean, required?: boolean }[]} items
+ */
+export async function multiSelect(message, items) {
+  // In non-TTY environments (piped input), return defaults
+  if (!process.stdin.isTTY) {
+    return items.filter((i) => i.checked).map((i) => i.id);
+  }
+
+  const state = items.map((item) => ({ ...item }));
+  let cursor = 0;
+
+  function render() {
+    // Move cursor up to re-render (except first render)
+    const lines = [];
+    lines.push(`  ${message} (space=toggle, enter=confirm)\n`);
+    for (let i = 0; i < state.length; i++) {
+      const item = state[i];
+      const pointer = i === cursor ? '>' : ' ';
+      const check = item.checked ? 'x' : ' ';
+      const suffix = item.required ? ' (required)' : '';
+      lines.push(`  ${pointer} [${check}] ${item.label}${suffix}`);
+    }
+    return lines.join('\n');
+  }
+
+  return new Promise((resolve) => {
+    process.stdout.write(render());
+
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    const onKey = (key) => {
+      // Ctrl+C
+      if (key === '\u0003') {
+        stdin.setRawMode(false);
+        stdin.removeListener('data', onKey);
+        process.stdout.write('\n');
+        process.exit(0);
+      }
+
+      // Enter
+      if (key === '\r' || key === '\n') {
+        stdin.setRawMode(false);
+        stdin.removeListener('data', onKey);
+        process.stdout.write('\n\n');
+        resolve(state.filter((i) => i.checked).map((i) => i.id));
+        return;
+      }
+
+      // Space - toggle
+      if (key === ' ') {
+        if (!state[cursor].required) {
+          state[cursor].checked = !state[cursor].checked;
+        }
+      }
+
+      // Arrow up / k
+      if (key === '\u001b[A' || key === 'k') {
+        cursor = (cursor - 1 + state.length) % state.length;
+      }
+
+      // Arrow down / j
+      if (key === '\u001b[B' || key === 'j') {
+        cursor = (cursor + 1) % state.length;
+      }
+
+      // Re-render
+      // Clear previous render
+      const lineCount = state.length + 1;
+      process.stdout.write(`\u001b[${lineCount}A\u001b[0J`);
+      process.stdout.write(render());
+    };
+
+    stdin.on('data', onKey);
+  });
+}
+
+/**
+ * Ask how to handle file conflicts.
+ * Returns 'skip' | 'overwrite' | 'ask'
+ */
+export async function conflictStrategy(conflictCount) {
+  const rl = createRL();
+  return new Promise((resolve) => {
+    console.log(`\n  ${conflictCount} existing file(s) detected. How to handle?`);
+    console.log('  1) Skip existing files (safe default)');
+    console.log('  2) Overwrite all');
+    console.log('  3) Ask for each file');
+    rl.question('  Choice [1]: ', (answer) => {
+      rl.close();
+      const a = answer.trim();
+      if (a === '2') resolve('overwrite');
+      else if (a === '3') resolve('ask');
+      else resolve('skip');
+    });
+  });
+}
+
+/**
+ * Ask about a single file conflict.
+ * Returns 'skip' | 'overwrite'
+ */
+export async function askFileConflict(relPath) {
+  const rl = createRL();
+  return new Promise((resolve) => {
+    rl.question(`  Overwrite ${relPath}? [y/N] `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === 'y' || a === 'yes' ? 'overwrite' : 'skip');
+    });
+  });
+}