@ivannikov-pro/ai-context-surgeon 1.0.0

package/bin/cli.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+/** Category: Tool — AI-native CLI entry point | COMMANDS: catalog, role, strategy, skill, prompt, template, checklist, knowledge, radar, godfiles, circular, context-weight, sourcemaps, init | DEPS: @clack/prompts, commander, ./catalog.js, ./prompts.js */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+import { intro, outro, select, spinner, text, isCancel, cancel } from "@clack/prompts";
+import pc from "picocolors";
+import { program } from "commander";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const sourceDir = path.resolve(__dirname, "..");
+
+// Read version from package.json
+const pkg = JSON.parse(fs.readFileSync(path.join(sourceDir, "package.json"), "utf8"));
+
+function runScript(scriptPath, args = []) {
+  return new Promise((resolve, reject) => {
+    const fullPath = path.join(sourceDir, scriptPath);
+    const child = spawn("bash", [fullPath, ...args], {
+      stdio: "inherit",
+      cwd: process.cwd(),
+    });
+    child.on("close", (code) => {
+      if (code !== 0) reject(new Error(`Script exited with code ${code}`));
+      else resolve();
+    });
+    child.on("error", (err) => reject(err));
+  });
+}
+
+program
+  .name("ai-context-surgeon")
+  .description("AI Context Surgeon — AI-native Knowledge API for monorepo optimization.\nAll content accessible on-demand. No install needed for tools.")
+  .version(pkg.version);
+
+// ─── Tier 1: Discovery ─────────────────────────────────────────────
+
+program
+  .command("catalog")
+  .description("List all available content: tools, roles, strategies, prompts, skills, templates, checklists, knowledge")
+  .action(async () => {
+    const { CATALOG, listCategory } = await import("./catalog.js");
+
+    const icons = {
+      tools: "🔧",
+      roles: "🎭",
+      strategies: "📖",
+      prompts: "💡",
+      skills: "🧩",
+      templates: "📝",
+      checklists: "📋",
+      knowledge: "🧠",
+    };
+
+    console.log(pc.cyan(`\n📋 ai-context-surgeon v${pkg.version} — AI Context Optimization Toolkit\n`));
+
+    // Tools
+    console.log(pc.bold(`${icons.tools} TOOLS (run directly):`));
+    for (const item of listCategory("tools")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    // Roles
+    console.log(pc.bold(`\n${icons.roles} ROLES (agent prompts):`));
+    for (const item of listCategory("roles")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    // Strategies
+    console.log(pc.bold(`\n${icons.strategies} STRATEGIES (reference docs):`));
+    for (const item of listCategory("strategies")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    // Prompts
+    console.log(pc.bold(`\n${icons.prompts} PROMPTS (condensed task instructions):`));
+    const { listPrompts } = await import("./prompts.js");
+    for (const item of listPrompts()) {
+      console.log(`  ${pc.green(item.value.padEnd(22))} ${item.label}`);
+    }
+
+    // Skills
+    console.log(pc.bold(`\n${icons.skills} SKILLS (reusable procedures):`));
+    for (const item of listCategory("skills")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    // Templates
+    console.log(pc.bold(`\n${icons.templates} TEMPLATES (file seeds):`));
+    for (const item of listCategory("templates")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    // Checklists
+    console.log(pc.bold(`\n${icons.checklists} CHECKLISTS (phase tasks):`));
+    for (const item of listCategory("checklists")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    // Knowledge
+    console.log(pc.bold(`\n${icons.knowledge} KNOWLEDGE (reference items):`));
+    for (const item of listCategory("knowledge")) {
+      console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+    }
+
+    console.log(pc.dim(`\nUsage: npx @ivannikov-pro/ai-context-surgeon@latest <category> <name>\n`));
+  });
+
+// ─── Tier 2: Content Access ────────────────────────────────────────
+
+function registerContentCommand(cmdName, categoryKey, description) {
+  program
+    .command(`${cmdName} [name]`)
+    .description(description)
+    .option("-o, --output <path>", "Save output to a file instead of stdout")
+    .action(async (name, options) => {
+      const { getContent, listCategory } = await import("./catalog.js");
+
+      if (!name) {
+        console.log(pc.cyan(`\nAvailable ${cmdName}s:\n`));
+        for (const item of listCategory(categoryKey)) {
+          console.log(`  ${pc.green(item.key.padEnd(22))} ${item.description}`);
+        }
+        console.log(pc.dim(`\nUsage: npx @ivannikov-pro/ai-context-surgeon@latest ${cmdName} <name>\n`));
+        console.log(pc.dim(`  Add --output <path> to save to a file (e.g. --output .agents/${cmdName}-<name>.md)\n`));
+        return;
+      }
+
+      const content = getContent(categoryKey, name);
+      if (!content) {
+        console.error(pc.red(`\n❌ Unknown ${cmdName}: "${name}"\n`));
+        const items = listCategory(categoryKey);
+        console.log("Available:", items.map((i) => i.key).join(", "));
+        process.exit(1);
+      }
+
+      // Save to file or output to stdout
+      if (options.output) {
+        const outputPath = path.resolve(process.cwd(), options.output);
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+          fs.mkdirSync(outputDir, { recursive: true });
+        }
+        fs.writeFileSync(outputPath, content);
+        console.log(pc.green(`✅ Saved ${cmdName} "${name}" → ${options.output}`));
+      } else {
+        console.log(content);
+      }
+    });
+}
+
+registerContentCommand("role", "roles", "Get an agent role prompt (scout, architect, surgeon, librarian, tuner, inspector)");
+registerContentCommand("strategy", "strategies", "Get a strategy document (fnh, monorepo, jsdoc, package-json, context-exclusion, bash, context-weight)");
+registerContentCommand("skill", "skills", "Get a skill procedure (annotate-jsdoc, prompt-engineering)");
+registerContentCommand("template", "templates", "Get a file template (agents, readme, package-json, workflow, skill, knowledge, ...)");
+registerContentCommand("checklist", "checklists", "Get a phase checklist (1-5)");
+registerContentCommand("knowledge", "knowledge", "Get a knowledge item (agent-context, vulnerabilities, power-words)");
+
+// Prompt command — uses the condensed prompt library
+program
+  .command("prompt [task]")
+  .description("Get a ready-to-use prompt for a task (fnh, jsdoc, readme, agent-rules, context-exclusion, god-file)")
+  .option("-l, --list", "List all available prompts")
+  .option("-o, --output <path>", "Save output to a file instead of stdout")
+  .action(async (task, options) => {
+    const { PROMPTS, listPrompts, getPrompt } = await import("./prompts.js");
+
+    if (options.list || !task) {
+      console.log(pc.cyan("\n💡 Available prompts:\n"));
+      for (const item of listPrompts()) {
+        console.log(`  ${pc.bold(pc.green(item.value.padEnd(22)))} ${item.label}`);
+      }
+      console.log(pc.dim(`\nUsage: npx @ivannikov-pro/ai-context-surgeon@latest prompt <task>\n`));
+      console.log(pc.dim(`  Add --output <path> to save to a file (e.g. --output .agents/prompt-fnh.md)\n`));
+      return;
+    }
+
+    const prompt = getPrompt(task);
+    if (!prompt) {
+      console.error(pc.red(`\n❌ Unknown prompt: "${task}"\n`));
+      console.log("Available:", Object.keys(PROMPTS).join(", "));
+      process.exit(1);
+    }
+
+    if (options.output) {
+      const outputPath = path.resolve(process.cwd(), options.output);
+      const outputDir = path.dirname(outputPath);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+      }
+      fs.writeFileSync(outputPath, prompt.prompt);
+      console.log(pc.green(`✅ Saved prompt "${task}" → ${options.output}`));
+    } else {
+      console.log(prompt.prompt);
+    }
+  });
+
+// ─── Tier 3: Tool Execution ────────────────────────────────────────
+
+program
+  .command("radar")
+  .description("Run Radar Scan — generate semantic FNH map of the repository")
+  .option("-d, --depth <level>", "Limit scan depth (e.g. 1, 2, all)")
+  .option("--no-legend", "Output pure text map without format legend")
+  .action(async (options) => {
+    const args = ["."];
+    if (options.depth) args.push(`--depth=${options.depth}`);
+    if (!options.legend) args.push("--no-legend");
+    await runScript("tools/scan-fnh.sh", args);
+  });
+
+program
+  .command("godfiles")
+  .description("Find excessively large files (detect-god-files.sh)")
+  .action(async () => await runScript("tools/detect-god-files.sh", ["."]));
+
+program
+  .command("circular")
+  .description("Detect circular dependencies")
+  .action(async () => await runScript("tools/detect-circular-deps.sh", ["."]));
+
+program
+  .command("sourcemaps")
+  .description("Generate AI-friendly source maps")
+  .action(async () => await runScript("tools/generate-source-map.sh", ["."]));
+
+program
+  .command("context-weight")
+  .description("Identify files with high Context Weight (LOC + import penalties)")
+  .option("--internal-scope <scopes>", "Treat these scopes as local imports (comma-separated)")
+  .action(async (options) => {
+    const args = ["."];
+    if (options.internalScope) args.push(`--internal-scope=${options.internalScope}`);
+    await runScript("tools/validate-context-weight.sh", args);
+  });
+
+// ─── Tier 4: Lightweight Init ──────────────────────────────────────
+
+program
+  .command("init")
+  .description("Lightweight setup — create AGENTS.md, .antigravityignore, and CI scripts (no file copying)")
+  .action(async () => {
+    const { initProject } = await import("./installer.js");
+    initProject();
+  });
+
+// ─── Interactive Wizard (no args) ──────────────────────────────────
+
+if (process.argv.length === 2) {
+  (async () => {
+    console.clear();
+    intro(pc.bgCyan(pc.black(" ❤️ ai-context-surgeon ")));
+
+    const action = await select({
+      message: "What would you like to do?",
+      options: [
+        { value: "catalog", label: "📋 Browse full catalog (tools, roles, strategies, prompts, ...)" },
+        { value: "radar", label: "🗺️  Run Radar Scan (scan-fnh)" },
+        { value: "role", label: "🎭 Read a role prompt" },
+        { value: "strategy", label: "📖 Read a strategy document" },
+        { value: "prompt", label: "💡 Get a condensed prompt for a task" },
+        { value: "skill", label: "🧩 Read a skill procedure" },
+        { value: "godfiles", label: "⚔️  Detect God Files" },
+        { value: "context-weight", label: "⚖️  Analyze Context Weight" },
+        { value: "circular", label: "🔄 Detect Circular Dependencies" },
+        { value: "init", label: "🚀 Init project (AGENTS.md + CI scripts)" },
+        { value: "help", label: "📖 Help / About" },
+        { value: "quit", label: "❌ Exit" },
+      ],
+    });
+
+    if (isCancel(action) || action === "quit") {
+      cancel("Operation cancelled.");
+      process.exit(0);
+    }
+
+    try {
+      if (action === "catalog") {
+        // Re-run with catalog command
+        program.parse(["node", "cli.js", "catalog"]);
+      } else if (action === "role") {
+        const { listCategory, getContent } = await import("./catalog.js");
+        const items = listCategory("roles");
+        const selected = await select({
+          message: "Which role?",
+          options: items.map((i) => ({ value: i.key, label: `${i.name} — ${i.description}` })),
+        });
+        if (isCancel(selected)) { cancel("Cancelled"); process.exit(0); }
+        outro(pc.blue(`\n--- Role: ${selected} ---\n`));
+        console.log(getContent("roles", selected));
+      } else if (action === "strategy") {
+        const { listCategory, getContent } = await import("./catalog.js");
+        const items = listCategory("strategies");
+        const selected = await select({
+          message: "Which strategy?",
+          options: items.map((i) => ({ value: i.key, label: `${i.name} — ${i.description}` })),
+        });
+        if (isCancel(selected)) { cancel("Cancelled"); process.exit(0); }
+        outro(pc.blue(`\n--- Strategy: ${selected} ---\n`));
+        console.log(getContent("strategies", selected));
+      } else if (action === "prompt") {
+        const { listPrompts, getPrompt } = await import("./prompts.js");
+        const items = listPrompts();
+        const selected = await select({
+          message: "Which prompt?",
+          options: items.map((p) => ({ value: p.value, label: p.label })),
+        });
+        if (isCancel(selected)) { cancel("Cancelled"); process.exit(0); }
+        const prompt = getPrompt(selected);
+        outro(pc.blue(`\n--- Prompt: ${prompt.name} ---\n`));
+        console.log(prompt.prompt);
+      } else if (action === "skill") {
+        const { listCategory, getContent } = await import("./catalog.js");
+        const items = listCategory("skills");
+        const selected = await select({
+          message: "Which skill?",
+          options: items.map((i) => ({ value: i.key, label: `${i.name} — ${i.description}` })),
+        });
+        if (isCancel(selected)) { cancel("Cancelled"); process.exit(0); }
+        outro(pc.blue(`\n--- Skill: ${selected} ---\n`));
+        console.log(getContent("skills", selected));
+      } else if (action === "init") {
+        const s = spinner();
+        s.start("Initializing ai-context-surgeon...");
+        const { initProject } = await import("./installer.js");
+        initProject();
+        s.stop("Initialization complete!");
+        outro(pc.green("Project configured. Run 'catalog' to see what's available."));
+      } else if (action === "help") {
+        outro(
+          pc.cyan(`📖 ai-context-surgeon — AI-native Knowledge API for monorepo optimization\n
+${pc.bold("catalog")}           — Browse all available content
+${pc.bold("role <name>")}       — Read an agent role prompt (scout, architect, ...)
+${pc.bold("strategy <name>")}   — Read a strategy document (fnh, monorepo, ...)
+${pc.bold("prompt <task>")}     — Get a condensed task prompt (fnh, jsdoc, ...)
+${pc.bold("skill <name>")}      — Read a skill procedure (annotate-jsdoc, ...)
+${pc.bold("template <name>")}   — Get a file template (agents, readme, ...)
+${pc.bold("checklist <n>")}     — Get a phase checklist (1-5)
+${pc.bold("knowledge <name>")}  — Read a knowledge item (agent-context, ...)
+${pc.bold("radar")}             — Quick repo map via FNH headers
+${pc.bold("godfiles")}          — Find files > 300 LOC
+${pc.bold("context-weight")}    — Find high cognitive-load files
+${pc.bold("circular")}          — Detect inter-package cycles
+${pc.bold("init")}              — Lightweight project setup (AGENTS.md + CI)
+
+All content runs from npm cache — always latest version, no install needed.
+Usage: npx -y @ivannikov-pro/ai-context-surgeon@latest <command>`),
+        );
+      } else if (action === "radar") {
+        const depth = await text({
+          message: 'Depth limit (optional, e.g., 1, 2) or Enter for "all"',
+          placeholder: "all",
+        });
+        if (isCancel(depth)) { cancel("Cancelled"); process.exit(0); }
+        const args = ["."];
+        if (depth && depth.trim() !== "all") args.push(`--depth=${depth.trim()}`);
+        outro(pc.blue(`Running scan-fnh.sh ...\n`));
+        await runScript("tools/scan-fnh.sh", args);
+      } else if (action === "godfiles") {
+        outro(pc.blue(`Running detect-god-files.sh ...\n`));
+        await runScript("tools/detect-god-files.sh", ["."]);
+      } else if (action === "circular") {
+        outro(pc.blue(`Running detect-circular-deps.sh ...\n`));
+        await runScript("tools/detect-circular-deps.sh", ["."]);
+      } else if (action === "context-weight") {
+        outro(pc.blue(`Running validate-context-weight.sh ...\n`));
+        await runScript("tools/validate-context-weight.sh", ["."]);
+      }
+    } catch (err) {
+      cancel(pc.red(`Execution failed: ${err.message}`));
+      process.exit(1);
+    }
+  })();
+} else {
+  program.parse(process.argv);
+}

package/bin/installer.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/** Category: Tool — Lightweight project initializer | EXPORTS: initProject | DEPS: fs, path */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const sourceDir = path.resolve(__dirname, "..");
+const targetDir = process.cwd();
+
+/**
+ * Lightweight project initialization.
+ * Only creates essential config files — NO file copying.
+ * Tools, roles, strategies run from npm cache via `npx`.
+ */
+export function initProject() {
+  console.log("❤️ Initializing ai-context-surgeon for your project...\n");
+
+  const created = [];
+  const skipped = [];
+
+  // 1. Create .agents/ directory
+  const agentsDir = path.join(targetDir, ".agents");
+  if (!fs.existsSync(agentsDir)) {
+    fs.mkdirSync(agentsDir, { recursive: true });
+  }
+
+  // 2. Create AGENTS.md from template
+  const agentsFile = path.join(agentsDir, "AGENTS.md");
+  const templatePath = path.join(sourceDir, "templates", "AGENTS.md.template");
+  if (!fs.existsSync(agentsFile) && fs.existsSync(templatePath)) {
+    const template = fs.readFileSync(templatePath, "utf8");
+    const content = template + `
+## AI Context Surgeon
+
+This project uses [ai-context-surgeon](https://github.com/ivannikov-pro/ai-context-surgeon) for context optimization.
+
+All tools, roles, and strategies are available on-demand via:
+\`\`\`bash
+npx @ivannikov-pro/ai-context-surgeon@latest catalog    # See everything available
+npx @ivannikov-pro/ai-context-surgeon@latest role scout  # Get a role prompt
+npx @ivannikov-pro/ai-context-surgeon@latest prompt fnh  # Get task instructions
+npx @ivannikov-pro/ai-context-surgeon@latest radar       # Run analysis tools
+\`\`\`
+`;
+    fs.writeFileSync(agentsFile, content);
+    created.push(".agents/AGENTS.md");
+  } else {
+    skipped.push(".agents/AGENTS.md (already exists)");
+  }
+
+  // 3. Create .antigravityignore from template
+  const ignoreFile = path.join(targetDir, ".antigravityignore");
+  const ignoreTemplate = path.join(sourceDir, "templates", "antigravityignore.template");
+  if (!fs.existsSync(ignoreFile) && fs.existsSync(ignoreTemplate)) {
+    fs.copyFileSync(ignoreTemplate, ignoreFile);
+    created.push(".antigravityignore");
+  } else {
+    skipped.push(".antigravityignore (already exists)");
+  }
+
+  // 4. Create .cursorrules / .windsurfrules from template
+  const cursorTemplate = path.join(sourceDir, "templates", "cursorrules.template");
+  if (fs.existsSync(cursorTemplate)) {
+    const rulesContent = fs.readFileSync(cursorTemplate, "utf8");
+
+    for (const filename of [".cursorrules", ".windsurfrules"]) {
+      const rulesPath = path.join(targetDir, filename);
+      if (!fs.existsSync(rulesPath)) {
+        fs.writeFileSync(rulesPath, rulesContent);
+        created.push(filename);
+      } else {
+        skipped.push(`${filename} (already exists)`);
+      }
+    }
+  }
+
+  // 5. Inject CI scripts into package.json (if Node.js project)
+  const packageJsonPath = path.join(targetDir, "package.json");
+  if (fs.existsSync(packageJsonPath)) {
+    try {
+      const pkgContent = fs.readFileSync(packageJsonPath, "utf8");
+      const pkg = JSON.parse(pkgContent);
+
+      if (!pkg.scripts) pkg.scripts = {};
+
+      let modified = false;
+
+      // CI scripts use npx to run tools — no local install needed
+      const ciScripts = {
+        "check:hygiene": "npx @ivannikov-pro/ai-context-surgeon@latest radar --no-legend",
+        "check:god-files": "npx @ivannikov-pro/ai-context-surgeon@latest godfiles",
+      };
+
+      for (const [name, cmd] of Object.entries(ciScripts)) {
+        if (!pkg.scripts[name]) {
+          pkg.scripts[name] = cmd;
+          modified = true;
+        }
+      }
+
+      if (modified) {
+        fs.writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+        created.push("package.json CI scripts (check:hygiene, check:god-files)");
+      } else {
+        skipped.push("package.json CI scripts (already exist)");
+      }
+    } catch (err) {
+      console.error(`⚠️  Failed to update package.json: ${err.message}`);
+    }
+  }
+
+  // Summary
+  console.log("✅ Created:");
+  for (const item of created) console.log(`   ${item}`);
+
+  if (skipped.length) {
+    console.log("\nℹ️  Skipped:");
+    for (const item of skipped) console.log(`   ${item}`);
+  }
+
+  console.log(`
+🎯 Next steps:
+   1. Fill {{PLACEHOLDER}} values in .agents/AGENTS.md
+   2. Run: npx @ivannikov-pro/ai-context-surgeon@latest catalog
+   3. Run: npx @ivannikov-pro/ai-context-surgeon@latest radar
+`);
+}
+
+// Allow direct execution
+if (process.argv[1] === __filename) {
+  initProject();
+}