claude-launchpad 0.2.1 → 0.3.0

package/README.md

@@ -133,10 +133,31 @@ claude-launchpad eval --suite common
   Config Eval Score      ━━━━━━━━━━━━━━━━━━──    89%
 ```
 
-Each scenario creates an isolated sandbox, runs Claude with explicit tool permissions, and verifies the output with grep/file assertions. [Write your own scenarios](scenarios/CONTRIBUTING.md) in YAML.
+Each scenario is a YAML file. [Write your own](scenarios/CONTRIBUTING.md).
 
 This is the part nobody else has built. Template repos scaffold. Audit tools diagnose. **Nobody tests whether your config actually makes Claude better.** Until now.
 
+## How It Works Under the Hood
+
+### doctor
+Reads your `CLAUDE.md`, `.claude/settings.json`, `.claude/rules/`, and `.claudeignore`. Runs 7 analyzers that check instruction count, section completeness, hook configuration, rule validity, permission safety, and MCP server configs. Pure static analysis — no API calls, no network, no cost.
+
+### init
+Scans the project root for manifest files (`package.json`, `go.mod`, `pyproject.toml`, `Gemfile`, `Cargo.toml`, `composer.json`, etc.). Detects language, framework, package manager, and available scripts. Generates config files with stack-appropriate hooks (prettier for TypeScript, gofmt for Go, ruff for Python, etc.). Merges with existing `settings.json` if one exists.
+
+### enhance
+Spawns `claude "prompt"` as an interactive child process with `stdio: "inherit"` — you see Claude's full UI. The prompt instructs Claude to read the codebase and fill in CLAUDE.md sections. No data passes through the launchpad — it just launches Claude with a pre-loaded task.
+
+### eval
+1. Creates a temp directory (`/tmp/claude-eval-<uuid>/`)
+2. Writes seed files from the scenario YAML (e.g., a `src/db.ts` with a TODO)
+3. Writes a `CLAUDE.md` with the scenario's instructions
+4. Initializes a git repo (Claude Code expects one)
+5. Runs Claude via the [Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) with `allowedTools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]` and `permissionMode: "dontAsk"` — or falls back to `claude -p` if the SDK isn't installed
+6. After Claude finishes, runs grep/file assertions against the modified files
+7. Scores: each check has points, total determines pass/fail
+8. Cleans up the temp directory (or preserves it with `--debug`)
+
 ## Use in CI
 
 Add this workflow to block PRs that degrade Claude Code config quality:

package/dist/cli.js

@@ -2,8 +2,8 @@
 
 // src/cli.ts
 import { Command as Command5 } from "commander";
-import { access as access7 } from "fs/promises";
-import { join as join9 } from "path";
+import { access as access8 } from "fs/promises";
+import { join as join10 } from "path";
 
 // src/commands/init/index.ts
 import { Command } from "commander";
@@ -324,9 +324,9 @@ async function fileExists(path) {
   }
 }
 async function globExists(dir, pattern) {
-  const { readdir: readdir4 } = await import("fs/promises");
+  const { readdir: readdir5 } = await import("fs/promises");
   try {
-    const entries = await readdir4(dir);
+    const entries = await readdir5(dir);
     return entries.some((e) => e.endsWith(pattern.replace("*", "")));
   } catch {
     return false;
@@ -1028,10 +1028,20 @@ async function analyzeHooks(config) {
 }
 
 // src/commands/doctor/analyzers/rules.ts
-import { readFile as readFile4 } from "fs/promises";
-import { basename as basename2 } from "path";
+import { readFile as readFile4, access as access3 } from "fs/promises";
+import { basename as basename2, join as join4, dirname } from "path";
 async function analyzeRules(config) {
   const issues = [];
+  const projectRoot = config.claudeMdPath ? dirname(config.claudeMdPath) : process.cwd();
+  const hasClaudeignore = await fileExists3(join4(projectRoot, ".claudeignore"));
+  if (!hasClaudeignore) {
+    issues.push({
+      analyzer: "Rules",
+      severity: "low",
+      message: "No .claudeignore found \u2014 Claude may read noise files (node_modules, dist, lockfiles)",
+      fix: "Run `claude-launchpad init` or `doctor --fix` to generate one"
+    });
+  }
   if (config.rules.length === 0) {
     issues.push({
       analyzer: "Rules",
@@ -1070,6 +1080,14 @@ async function analyzeRules(config) {
   const score = Math.max(0, 100 - issues.length * 10);
   return { name: "Rules", issues, score };
 }
+async function fileExists3(path) {
+  try {
+    await access3(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // src/commands/doctor/analyzers/permissions.ts
 async function analyzePermissions(config) {
@@ -1116,7 +1134,7 @@ async function analyzePermissions(config) {
 }
 
 // src/commands/doctor/analyzers/mcp.ts
-import { access as access3 } from "fs/promises";
+import { access as access4 } from "fs/promises";
 async function analyzeMcp(config) {
   const issues = [];
   const servers = config.mcpServers;
@@ -1124,8 +1142,7 @@ async function analyzeMcp(config) {
     issues.push({
       analyzer: "MCP",
       severity: "info",
-      message: "No MCP servers configured \u2014 Claude can't connect to external tools",
-      fix: "Add MCP servers in .claude/settings.json for GitHub, database, docs, etc."
+      message: "No MCP servers configured. Run `claude-launchpad enhance` to get stack-specific recommendations."
     });
     return { name: "MCP Servers", issues, score: 50 };
   }
@@ -1150,13 +1167,13 @@ async function analyzeMcp(config) {
       const executable = server.command.split(" ")[0];
       if (executable.startsWith("/") || executable.startsWith("./")) {
         try {
-          await access3(executable);
+          await access4(executable);
         } catch {
           issues.push({
             analyzer: "MCP",
             severity: "medium",
             message: `MCP server "${server.name}" command not found: ${executable}`,
-            fix: `Verify the path exists or install the required package`
+            fix: "Verify the path exists or install the required package"
           });
         }
       }
@@ -1168,7 +1185,7 @@ async function analyzeMcp(config) {
 
 // src/commands/doctor/analyzers/quality.ts
 var ESSENTIAL_SECTIONS = [
-  { pattern: /^##\s+Stack/m, name: "Stack", why: "Claude performs worse without knowing the tech stack" },
+  { pattern: /^##\s+(Tech )?Stack/m, name: "Stack", why: "Claude performs worse without knowing the tech stack" },
   { pattern: /^##\s+Commands/m, name: "Commands", why: "Claude guesses wrong without explicit dev/build/test commands" },
   { pattern: /^##\s+Session Start/m, name: "Session Start", why: "Without this, Claude won't read TASKS.md or maintain continuity" },
   { pattern: /^##\s+Off.?Limits/m, name: "Off-Limits", why: "Without guardrails, Claude has no boundaries beyond defaults" },
@@ -1249,8 +1266,8 @@ async function analyzeQuality(config) {
 }
 
 // src/commands/doctor/fixer.ts
-import { readFile as readFile5, writeFile as writeFile2, mkdir as mkdir2, access as access4 } from "fs/promises";
-import { join as join4 } from "path";
+import { readFile as readFile5, writeFile as writeFile2, mkdir as mkdir2, access as access5 } from "fs/promises";
+import { join as join5 } from "path";
 async function applyFixes(issues, projectRoot) {
   const detected = await detectProject(projectRoot);
   let fixed = 0;
@@ -1299,6 +1316,9 @@ async function tryFix(issue, root, detected) {
   if (issue.analyzer === "Quality" && issue.message.includes("Session Start")) {
     return addClaudeMdSection(root, "## Session Start", "- ALWAYS read @TASKS.md first \u2014 it tracks progress across sessions\n- Update TASKS.md as you complete work");
   }
+  if (issue.analyzer === "Rules" && issue.message.includes("No .claudeignore")) {
+    return createClaudeignore(root, detected);
+  }
   if (issue.analyzer === "Rules" && issue.message.includes("No .claude/rules/")) {
     return createStarterRules(root);
   }
@@ -1384,7 +1404,7 @@ async function addForcePushProtection(root) {
   return true;
 }
 async function addClaudeMdSection(root, heading, content) {
-  const claudeMdPath = join4(root, "CLAUDE.md");
+  const claudeMdPath = join5(root, "CLAUDE.md");
   let existing;
   try {
     existing = await readFile5(claudeMdPath, "utf-8");
@@ -1404,16 +1424,28 @@ ${content}
   log.success(`Added "${heading}" section to CLAUDE.md`);
   return true;
 }
+async function createClaudeignore(root, detected) {
+  const ignorePath = join5(root, ".claudeignore");
+  try {
+    await access5(ignorePath);
+    return false;
+  } catch {
+  }
+  const content = generateClaudeignore(detected);
+  await writeFile2(ignorePath, content);
+  log.success("Generated .claudeignore with language-specific ignore patterns");
+  return true;
+}
 async function createStarterRules(root) {
-  const rulesDir = join4(root, ".claude", "rules");
+  const rulesDir = join5(root, ".claude", "rules");
   try {
-    await access4(rulesDir);
+    await access5(rulesDir);
     return false;
   } catch {
   }
   await mkdir2(rulesDir, { recursive: true });
   await writeFile2(
-    join4(rulesDir, "conventions.md"),
+    join5(rulesDir, "conventions.md"),
     `# Project Conventions
 
 - Use conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)
@@ -1426,7 +1458,7 @@ async function createStarterRules(root) {
   return true;
 }
 async function readSettingsJson(root) {
-  const path = join4(root, ".claude", "settings.json");
+  const path = join5(root, ".claude", "settings.json");
   try {
     const content = await readFile5(path, "utf-8");
     return JSON.parse(content);
@@ -1435,47 +1467,60 @@ async function readSettingsJson(root) {
   }
 }
 async function writeSettingsJson(root, settings) {
-  const dir = join4(root, ".claude");
+  const dir = join5(root, ".claude");
   await mkdir2(dir, { recursive: true });
-  await writeFile2(join4(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
+  await writeFile2(join5(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
 }
 
 // src/commands/doctor/watcher.ts
-import { watch } from "fs";
-import { join as join5 } from "path";
+import { readdir as readdir2, stat } from "fs/promises";
+import { join as join6 } from "path";
 async function watchConfig(projectRoot) {
-  const claudeDir = join5(projectRoot, ".claude");
-  const claudeMd = join5(projectRoot, "CLAUDE.md");
-  const claudeignore = join5(projectRoot, ".claudeignore");
   await runAndDisplay(projectRoot);
   log.blank();
   log.info("Watching for changes... (Ctrl+C to stop)");
   log.blank();
-  let debounce = null;
-  const onChange = () => {
-    if (debounce) clearTimeout(debounce);
-    debounce = setTimeout(async () => {
+  let lastSnapshot = await getFileSnapshot(projectRoot);
+  setInterval(async () => {
+    const currentSnapshot = await getFileSnapshot(projectRoot);
+    if (currentSnapshot !== lastSnapshot) {
+      lastSnapshot = currentSnapshot;
       console.clear();
       await runAndDisplay(projectRoot);
       log.blank();
       log.info("Watching for changes... (Ctrl+C to stop)");
       log.blank();
-    }, 300);
-  };
-  try {
-    watch(claudeDir, { recursive: true }, onChange);
-  } catch {
-  }
+    }
+  }, 1e3);
+  await new Promise(() => {
+  });
+}
+async function getFileSnapshot(projectRoot) {
+  const files = [
+    join6(projectRoot, "CLAUDE.md"),
+    join6(projectRoot, ".claudeignore")
+  ];
+  const claudeDir = join6(projectRoot, ".claude");
   try {
-    watch(claudeMd, onChange);
+    const entries = await readdir2(claudeDir, { withFileTypes: true, recursive: true });
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        const parentPath = entry.parentPath ?? claudeDir;
+        files.push(join6(parentPath, entry.name));
+      }
+    }
   } catch {
   }
-  try {
-    watch(claudeignore, onChange);
-  } catch {
+  const mtimes = [];
+  for (const file of files) {
+    try {
+      const s = await stat(file);
+      mtimes.push(`${file}:${s.mtimeMs}`);
+    } catch {
+      mtimes.push(`${file}:missing`);
+    }
   }
-  await new Promise(() => {
-  });
+  return mtimes.join("|");
 }
 async function runAndDisplay(projectRoot) {
   console.log("\x1B[36m\x1B[1m  Claude Launchpad\x1B[0m");
@@ -1613,8 +1658,8 @@ import ora from "ora";
 import chalk2 from "chalk";
 
 // src/commands/eval/loader.ts
-import { readFile as readFile6, readdir as readdir2, access as access5 } from "fs/promises";
-import { join as join6, resolve as resolve2, dirname } from "path";
+import { readFile as readFile6, readdir as readdir3, access as access6 } from "fs/promises";
+import { join as join7, resolve as resolve2, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 import { parse as parseYaml } from "yaml";
 
@@ -1717,7 +1762,7 @@ var ScenarioError = class extends Error {
 
 // src/commands/eval/loader.ts
 async function findScenariosDir() {
-  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const thisDir = dirname2(fileURLToPath(import.meta.url));
   const devPath = resolve2(thisDir, "../../../scenarios");
   if (await dirExists(devPath)) return devPath;
   const bundledPath = resolve2(thisDir, "../scenarios");
@@ -1728,7 +1773,7 @@ async function findScenariosDir() {
 }
 async function dirExists(path) {
   try {
-    await access5(path);
+    await access6(path);
     return true;
   } catch {
     return false;
@@ -1737,7 +1782,7 @@ async function dirExists(path) {
 async function loadScenarios(options) {
   const { suite, customPath } = options;
   const scenarioDir = customPath ? resolve2(customPath) : await findScenariosDir();
-  const dirs = suite ? [join6(scenarioDir, suite)] : await getSubdirectories(scenarioDir);
+  const dirs = suite ? [join7(scenarioDir, suite)] : await getSubdirectories(scenarioDir);
   const allDirs = [scenarioDir, ...dirs];
   const scenarios = [];
   for (const dir of allDirs) {
@@ -1758,31 +1803,31 @@ async function loadScenarios(options) {
 }
 async function getSubdirectories(dir) {
   try {
-    const entries = await readdir2(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => join6(dir, e.name));
+    const entries = await readdir3(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => join7(dir, e.name));
   } catch {
     return [];
   }
 }
 async function listYamlFiles(dir) {
   try {
-    const entries = await readdir2(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml"))).map((e) => join6(dir, e.name));
+    const entries = await readdir3(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml"))).map((e) => join7(dir, e.name));
   } catch {
     return [];
   }
 }
 
 // src/commands/eval/runner.ts
-import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile7, readdir as readdir3, rm } from "fs/promises";
-import { join as join7, dirname as dirname2 } from "path";
+import { mkdir as mkdir3, writeFile as writeFile3, readFile as readFile7, readdir as readdir4, rm } from "fs/promises";
+import { join as join8, dirname as dirname3 } from "path";
 import { tmpdir } from "os";
 import { randomUUID } from "crypto";
 import { execFile } from "child_process";
 import { promisify } from "util";
 var exec = promisify(execFile);
 async function runScenario(scenario, options) {
-  const sandboxDir = join7(tmpdir(), `claude-eval-${randomUUID()}`);
+  const sandboxDir = join8(tmpdir(), `claude-eval-${randomUUID()}`);
   try {
     await setupSandbox(sandboxDir, scenario);
     await runClaudeInSandbox(sandboxDir, scenario.prompt, options.timeout);
@@ -1808,13 +1853,13 @@ async function runScenarioWithRetries(scenario, options) {
 async function setupSandbox(sandboxDir, scenario) {
   await mkdir3(sandboxDir, { recursive: true });
   for (const file of scenario.setup.files) {
-    const filePath = join7(sandboxDir, file.path);
-    await mkdir3(dirname2(filePath), { recursive: true });
+    const filePath = join8(sandboxDir, file.path);
+    await mkdir3(dirname3(filePath), { recursive: true });
     await writeFile3(filePath, file.content);
   }
   if (scenario.setup.instructions) {
     await writeFile3(
-      join7(sandboxDir, "CLAUDE.md"),
+      join8(sandboxDir, "CLAUDE.md"),
       `# Eval Scenario
 
 ${scenario.setup.instructions}
@@ -1927,7 +1972,7 @@ async function evaluateSingleCheck(check, sandboxDir) {
 async function checkGrep(check, sandboxDir) {
   if (!check.pattern) return false;
   try {
-    const content = await readFile7(join7(sandboxDir, check.target), "utf-8");
+    const content = await readFile7(join8(sandboxDir, check.target), "utf-8");
     let found;
     try {
       found = new RegExp(check.pattern).test(content);
@@ -1941,7 +1986,7 @@ async function checkGrep(check, sandboxDir) {
 }
 async function checkFileExists(check, sandboxDir) {
   try {
-    await readFile7(join7(sandboxDir, check.target));
+    await readFile7(join8(sandboxDir, check.target));
     return check.expect === "present";
   } catch {
     return check.expect === "absent";
@@ -1949,7 +1994,7 @@ async function checkFileExists(check, sandboxDir) {
 }
 async function checkFileAbsent(check, sandboxDir) {
   try {
-    await readFile7(join7(sandboxDir, check.target));
+    await readFile7(join8(sandboxDir, check.target));
     return check.expect === "absent";
   } catch {
     return check.expect === "present";
@@ -1958,7 +2003,7 @@ async function checkFileAbsent(check, sandboxDir) {
 async function checkMaxLines(check, sandboxDir) {
   const maxLines = parseInt(check.pattern ?? "800", 10);
   try {
-    const files = await listAllFiles(join7(sandboxDir, check.target));
+    const files = await listAllFiles(join8(sandboxDir, check.target));
     for (const file of files) {
       const content = await readFile7(file, "utf-8");
       if (content.split("\n").length > maxLines) {
@@ -1973,9 +2018,9 @@ async function checkMaxLines(check, sandboxDir) {
 async function listAllFiles(dir) {
   const results = [];
   try {
-    const entries = await readdir3(dir, { withFileTypes: true });
+    const entries = await readdir4(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join7(dir, entry.name);
+      const fullPath = join8(dir, entry.name);
       if (entry.isDirectory()) {
         results.push(...await listAllFiles(fullPath));
       } else {
@@ -2100,28 +2145,37 @@ async function checkClaudeCli() {
 import { Command as Command4 } from "commander";
 import { spawn, execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
-import { access as access6 } from "fs/promises";
-import { join as join8 } from "path";
+import { access as access7 } from "fs/promises";
+import { join as join9 } from "path";
 var execAsync = promisify2(execFile2);
-var ENHANCE_PROMPT = `Read CLAUDE.md and the project's codebase, then update CLAUDE.md to fill in missing or incomplete sections:
+var ENHANCE_PROMPT = `Read CLAUDE.md and the project's codebase, then update CLAUDE.md to fill in missing or incomplete sections.
+
+CRITICAL BUDGET RULE: CLAUDE.md must stay UNDER 120 lines of actionable content (not counting headings, blank lines, or comments). Claude Code starts ignoring rules past ~150 instructions. If you need more detail, create .claude/rules/ files instead:
+- Create .claude/rules/conventions.md for detailed coding patterns
+- Create .claude/rules/architecture.md for detailed structure docs
+- Keep CLAUDE.md to HIGH-LEVEL summaries only (3-5 bullets per section max)
 
-1. **## Architecture** or **## Project Structure** \u2014 describe the actual codebase structure (directories, key files, data flow)
-2. **## Conventions** \u2014 add project-specific patterns you observe (naming, imports, state management, API patterns)
-3. **## Off-Limits** \u2014 add guardrails based on what you see (protected files, patterns to avoid, things that should never change)
-4. **## Key Decisions** \u2014 document any architectural decisions visible in the code
+Sections to fill in or preserve (DO NOT remove any existing section):
+1. **## Stack** \u2014 if missing or incomplete, detect and add language, framework, package manager
+2. **## Architecture** \u2014 3-5 bullet points describing the codebase shape (not a full directory tree)
+3. **## Conventions** \u2014 max 8 key patterns. Move detailed rules to .claude/rules/conventions.md
+4. **## Off-Limits** \u2014 max 8 guardrails specific to this project
+5. **## Key Decisions** \u2014 only decisions that affect how Claude should work in this codebase
+6. **MCP server suggestions** \u2014 look at what external services the project uses (databases, APIs, storage). If you spot Postgres, Redis, Stripe, GitHub API, or similar, suggest relevant MCP servers the user could add. Print these as suggestions at the end, not in CLAUDE.md.
 
 Rules:
-- Keep CLAUDE.md under 150 instructions (lines of actionable content)
 - Don't remove existing content \u2014 only add or improve
 - Be specific to THIS project, not generic advice
-- Use bullet points, not paragraphs`;
+- Use bullet points, not paragraphs
+- If a section would exceed 8 bullets, split into a .claude/rules/ file and reference it
+- After editing, count the actionable lines. If over 120, move content to rules files until under`;
 function createEnhanceCommand() {
   return new Command4("enhance").description("Use Claude to analyze your codebase and complete CLAUDE.md").option("-p, --path <path>", "Project root path", process.cwd()).action(async (opts) => {
     printBanner();
     const root = opts.path;
-    const claudeMdPath = join8(root, "CLAUDE.md");
+    const claudeMdPath = join9(root, "CLAUDE.md");
     try {
-      await access6(claudeMdPath);
+      await access7(claudeMdPath);
     } catch {
       log.error("No CLAUDE.md found. Run `claude-launchpad init` first.");
       process.exit(1);
@@ -2148,8 +2202,8 @@ function createEnhanceCommand() {
 }
 
 // src/cli.ts
-var program = new Command5().name("claude-launchpad").description("CLI toolkit that makes Claude Code setups measurably good").version("0.2.1").action(async () => {
-  const hasConfig = await fileExists3(join9(process.cwd(), "CLAUDE.md")) || await fileExists3(join9(process.cwd(), ".claude", "settings.json"));
+var program = new Command5().name("claude-launchpad").description("CLI toolkit that makes Claude Code setups measurably good").version("0.3.0", "-v, --version").action(async () => {
+  const hasConfig = await fileExists4(join10(process.cwd(), "CLAUDE.md")) || await fileExists4(join10(process.cwd(), ".claude", "settings.json"));
   if (hasConfig) {
     await program.commands.find((c) => c.name() === "doctor")?.parseAsync([], { from: "user" });
   } else {
@@ -2167,9 +2221,9 @@ program.addCommand(createDoctorCommand());
 program.addCommand(createEnhanceCommand());
 program.addCommand(createEvalCommand());
 program.parse();
-async function fileExists3(path) {
+async function fileExists4(path) {
   try {
-    await access7(path);
+    await access8(path);
     return true;
   } catch {
     return false;