claude-launchpad 0.2.0 → 0.2.2

package/README.md

@@ -13,14 +13,14 @@ npx claude-launchpad
 ## The Workflow
 
 ```bash
-npx claude-launchpad init        # 1. Auto-detect stack, generate config + hooks
-npx claude-launchpad enhance     # 2. Claude reads your code, completes CLAUDE.md
-npx claude-launchpad             # 3. Check your score (42%)
+npx claude-launchpad init          # 1. Auto-detect stack, generate config + hooks + .claudeignore
+npx claude-launchpad enhance       # 2. Claude reads your code, completes CLAUDE.md
+npx claude-launchpad               # 3. Check your score (42%)
 npx claude-launchpad doctor --fix  # 4. Auto-fix everything (→ 86%)
-npx claude-launchpad             # 5. Confirm the jump
+npx claude-launchpad eval          # 5. Prove your config works (89% eval score)
 ```
 
-> See the [full story on the landing page](https://mboss37.github.io/claude-launchpad/) — a 42% → 86% journey in three commands.
+> See the [full story on the landing page](https://mboss37.github.io/claude-launchpad/) — a 42% → 89% journey.
 
 ## Commands
 
@@ -31,32 +31,32 @@ Runs 7 static analyzers against your `.claude/` directory and `CLAUDE.md`. No AP
 ```
   Instruction Budget     ━━━━━━━━━━━━━━━━━━━━   100%
   CLAUDE.md Quality      ━━━━━━━━━━━━━━━━━━━━   100%
-  Settings               ━━━━━━━━━━━━━━━━━───    85%
+  Settings               ━━━━━━━━━━━━━━━━━━━━   100%
   Hooks                  ━━━━━━━━━━━━━━━━━━━━   100%
-  Rules                  ━━━━━━━━━━━━────────    60%
-  Permissions            ━━━━━━━━━━━━━━━━────    80%
+  Rules                  ━━━━━━━━━━━━━━━━━━━━   100%
+  Permissions            ━━━━━━━━━━━━━━━━━━━━   100%
   MCP Servers            ━━━━━━━━━━──────────    50%
 
-  Overall                ━━━━━━━━━━━━━━━━────    82%
+  Overall                ━━━━━━━━━━━━━━━━━━━─    93%
 
-   MEDIUM  Hooks
-    No .env file protection hook
-    Fix: Add a PreToolUse hook that blocks writes to .env files
-
-   LOW  Permissions
-    No force-push protection hook
-    Fix: Add a PreToolUse hook that warns on `git push --force` commands
+  ✓ No issues found. Your configuration looks solid.
 ```
 
 Running bare `claude-launchpad` with no subcommand auto-detects your config and runs doctor.
 
+**Flags:**
+- `--fix` — Auto-apply deterministic fixes (42% → 86% in one command)
+- `--watch` — Live score that updates every time you save a config file
+- `--json` — JSON output for programmatic use
+- `--min-score <n>` — Exit non-zero if score drops below threshold (for CI)
+
 **What it checks:**
 
 | Analyzer | What it catches |
 |---|---|
 | **Instruction Budget** | Are you over the ~150 instruction limit where Claude starts ignoring rules? |
 | **CLAUDE.md Quality** | Missing essential sections, vague instructions ("write good code"), hardcoded secrets |
-| **Settings** | Plugin config, permission rules, environment variables |
+| **Settings** | Hooks configured, dangerous tool access without safety nets |
 | **Hooks** | Missing auto-format, no .env protection, no PreToolUse security gates |
 | **Rules** | Dead rule files, stale references, empty configs |
 | **Permissions** | Bash auto-allowed without security hooks, no force-push protection |
@@ -80,6 +80,7 @@ claude-launchpad init
   ✓ Generated CLAUDE.md
   ✓ Generated TASKS.md
   ✓ Generated .claude/settings.json (with hooks)
+  ✓ Generated .claudeignore
 ```
 
 **Detects 13 languages:** TypeScript, JavaScript, Python, Go, Ruby, Rust, Dart, PHP, Java, Kotlin, Swift, Elixir, C#
@@ -91,7 +92,8 @@ claude-launchpad init
 **What you get:**
 - `CLAUDE.md` with your detected stack, commands, and essential sections
 - `TASKS.md` for session continuity across Claude sessions
-- `.claude/settings.json` with auto-format hooks and .env file protection
+- `.claude/settings.json` with auto-format hooks and .env file protection (merges with existing)
+- `.claudeignore` with language-specific ignore patterns (node_modules, __pycache__, dist, etc.)
 
 ### `enhance` — Let Claude finish what init started
 
@@ -109,23 +111,30 @@ Claude opens, reads your code, and updates CLAUDE.md with:
 
 You see Claude working in real-time — same experience as running `claude` yourself.
 
-### `eval` — Test your config (coming soon)
+### `eval` — Prove your config works
 
-Runs Claude headless against reproducible scenarios and **scores how well your config actually works**.
+Runs Claude headless against 9 reproducible scenarios using the [Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and **scores how well your config actually drives correct behavior**.
 
 ```bash
-claude-launchpad eval --suite security
+claude-launchpad eval --suite common
 ```
 
 ```
   ✓ security/sql-injection          10/10  PASS
-  ✓ security/env-file-protection    10/10  PASS
-  ✗ conventions/error-handling       7/10  WARN
-  ✗ conventions/file-size            4/10  FAIL
-
-  Config Eval Score        ━━━━━━━━━━━━━━━━────    78%
+  ✓ security/env-protection         10/10  PASS
+  ✓ security/secret-exposure        10/10  PASS
+  ✓ security/input-validation       10/10  PASS
+  ✓ conventions/error-handling      10/10  PASS
+  ✓ conventions/immutability        10/10  PASS
+  ✓ conventions/no-hardcoded-values 10/10  PASS
+  ✓ conventions/file-size           10/10  PASS
+  ✗ workflow/git-conventions         7/10  WARN
+
+  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.
+
 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.
 
 ## Use in CI
@@ -148,7 +157,7 @@ jobs:
       - run: npx claude-launchpad@latest doctor --min-score 80 --json
 ```
 
-Exit code is 1 when score is below the threshold, 0 when it passes. The workflow only triggers when Claude Code config files change.
+Exit code is 1 when score is below the threshold, 0 when it passes.
 
 ## Install as a Plugin
 
@@ -156,7 +165,7 @@ Exit code is 1 when score is below the threshold, 0 when it passes. The workflow
 claude plugin install claude-launchpad
 ```
 
-Then use `/doctor` and `/init` directly inside Claude Code.
+Then use `/launchpad:doctor`, `/launchpad:init`, `/launchpad:enhance`, and `/launchpad:eval` directly inside Claude Code. The plugin also nudges you to re-check your score when you edit config files.
 
 ## Why this exists
 
@@ -174,10 +183,11 @@ Claude Launchpad gives you a number. Fix the issues, re-run, watch the number go
 - **Zero dependencies on third-party Claude plugins.** Generates its own hooks and settings.
 - **Doctor is free.** No API calls, no secrets, works offline and air-gapped.
 - **Enhance uses Claude.** Spawns an interactive session to understand your codebase — costs tokens but produces a CLAUDE.md that actually knows your project.
-- **Eval costs money.** Runs Claude headless against scenarios — proof that your config works.
+- **Eval uses the Agent SDK.** Runs Claude headless in sandboxes with explicit tool permissions — proof that your config works.
 - **Works with any stack.** Auto-detects your project. No fixed menu of supported frameworks.
+- **50 tests.** The tool that tests configs is itself well-tested.
 - **You never clone this repo.** It's a tool you run with `npx`, not a template you fork.
 
 ## License
 
-MIT
+MIT — Built by [McLovin](https://github.com/mboss37) (the AI behind [@mboss37](https://github.com/mboss37))

package/dist/cli.js

@@ -3,7 +3,7 @@
 // src/cli.ts
 import { Command as Command5 } from "commander";
 import { access as access7 } from "fs/promises";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 
 // src/commands/init/index.ts
 import { Command } from "commander";
@@ -947,34 +947,34 @@ async function analyzeSettings(config) {
     });
     return { name: "Settings", issues, score: 40 };
   }
-  const plugins = config.settings.enabledPlugins;
-  if (!plugins || Object.keys(plugins).length === 0) {
+  const hooks = config.settings.hooks;
+  if (!hooks || Object.keys(hooks).length === 0) {
     issues.push({
       analyzer: "Settings",
-      severity: "low",
-      message: "No plugins enabled",
-      fix: "Consider enabling plugins for enhanced capabilities"
+      severity: "medium",
+      message: "settings.json has no hooks configured",
+      fix: "Run `claude-launchpad doctor --fix` to generate hooks"
     });
   }
-  const permissions = config.settings.permissions;
-  if (!permissions) {
+  const plugins = config.settings.enabledPlugins;
+  if (!plugins || Object.keys(plugins).length === 0) {
     issues.push({
       analyzer: "Settings",
-      severity: "low",
-      message: "No permission rules configured",
-      fix: "Add permission rules to control which tools Claude can use automatically"
+      severity: "info",
+      message: "No plugins enabled \u2014 plugins are optional but can add capabilities"
     });
   }
-  const env = config.settings.env;
-  if (!env) {
+  const allowedTools = config.settings.allowedTools;
+  if (allowedTools && allowedTools.length > 0 && config.hooks.length === 0) {
     issues.push({
       analyzer: "Settings",
-      severity: "info",
-      message: "No environment variables defined in settings",
-      fix: "Define env vars in settings.json for consistent development environments"
+      severity: "medium",
+      message: "Tools auto-allowed without any hooks \u2014 no safety net for dangerous operations",
+      fix: "Add PreToolUse hooks for security or remove allowedTools to use interactive prompting"
     });
   }
-  const score = Math.max(0, 100 - issues.length * 15);
+  const actionableCount = issues.filter((i) => i.severity !== "info").length;
+  const score = Math.max(0, 100 - actionableCount * 20);
   return { name: "Settings", issues, score };
 }
 
@@ -1440,9 +1440,93 @@ async function writeSettingsJson(root, settings) {
   await writeFile2(join4(dir, "settings.json"), JSON.stringify(settings, null, 2) + "\n");
 }
 
+// src/commands/doctor/watcher.ts
+import { watch } from "fs";
+import { join as join5 } 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 () => {
+      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 {
+  }
+  try {
+    watch(claudeMd, onChange);
+  } catch {
+  }
+  try {
+    watch(claudeignore, onChange);
+  } catch {
+  }
+  await new Promise(() => {
+  });
+}
+async function runAndDisplay(projectRoot) {
+  console.log("\x1B[36m\x1B[1m  Claude Launchpad\x1B[0m");
+  console.log("\x1B[2m  Scaffold \xB7 Diagnose \xB7 Evaluate\x1B[0m");
+  log.blank();
+  const config = await parseClaudeConfig(projectRoot);
+  if (config.claudeMdContent === null && config.settings === null) {
+    log.error("No Claude Code configuration found.");
+    return;
+  }
+  const results = await Promise.all([
+    analyzeBudget(config),
+    analyzeQuality(config),
+    analyzeSettings(config),
+    analyzeHooks(config),
+    analyzeRules(config),
+    analyzePermissions(config),
+    analyzeMcp(config)
+  ]);
+  const overallScore = Math.round(
+    results.reduce((sum, r) => sum + r.score, 0) / results.length
+  );
+  for (const result of results) {
+    printScoreCard(result.name, result.score);
+  }
+  log.blank();
+  printScoreCard("Overall", overallScore);
+  log.blank();
+  const allIssues = results.flatMap((r) => r.issues);
+  const actionable = allIssues.filter((i) => i.severity !== "info");
+  if (actionable.length === 0) {
+    log.success("No issues found. Your configuration looks solid.");
+    return;
+  }
+  const sorted = [...actionable].sort((a, b) => {
+    const order = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+    return (order[a.severity] ?? 4) - (order[b.severity] ?? 4);
+  });
+  for (const issue of sorted) {
+    printIssue(issue.severity, issue.analyzer, issue.message, issue.fix);
+  }
+  log.info(`${actionable.length} issue(s) found. Fix critical/high first.`);
+}
+
 // src/commands/doctor/index.ts
 function createDoctorCommand() {
-  return new Command2("doctor").description("Diagnose your Claude Code configuration and report issues").option("-p, --path <path>", "Project root path", process.cwd()).option("--json", "Output as JSON").option("--min-score <n>", "Exit non-zero if overall score is below this threshold (for CI)").option("--fix", "Auto-apply deterministic fixes for detected issues").action(async (opts) => {
+  return new Command2("doctor").description("Diagnose your Claude Code configuration and report issues").option("-p, --path <path>", "Project root path", process.cwd()).option("--json", "Output as JSON").option("--min-score <n>", "Exit non-zero if overall score is below this threshold (for CI)").option("--fix", "Auto-apply deterministic fixes for detected issues").option("--watch", "Watch for config changes and re-run automatically").action(async (opts) => {
+    if (opts.watch) {
+      await watchConfig(opts.path);
+      return;
+    }
     printBanner();
     log.step("Scanning Claude Code configuration...");
     log.blank();
@@ -1530,7 +1614,7 @@ 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 join5, resolve as resolve2, dirname } from "path";
+import { join as join6, resolve as resolve2, dirname } from "path";
 import { fileURLToPath } from "url";
 import { parse as parseYaml } from "yaml";
 
@@ -1653,7 +1737,7 @@ async function dirExists(path) {
 async function loadScenarios(options) {
   const { suite, customPath } = options;
   const scenarioDir = customPath ? resolve2(customPath) : await findScenariosDir();
-  const dirs = suite ? [join5(scenarioDir, suite)] : await getSubdirectories(scenarioDir);
+  const dirs = suite ? [join6(scenarioDir, suite)] : await getSubdirectories(scenarioDir);
   const allDirs = [scenarioDir, ...dirs];
   const scenarios = [];
   for (const dir of allDirs) {
@@ -1675,7 +1759,7 @@ async function loadScenarios(options) {
 async function getSubdirectories(dir) {
   try {
     const entries = await readdir2(dir, { withFileTypes: true });
-    return entries.filter((e) => e.isDirectory()).map((e) => join5(dir, e.name));
+    return entries.filter((e) => e.isDirectory()).map((e) => join6(dir, e.name));
   } catch {
     return [];
   }
@@ -1683,7 +1767,7 @@ async function getSubdirectories(dir) {
 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) => join5(dir, e.name));
+    return entries.filter((e) => e.isFile() && (e.name.endsWith(".yaml") || e.name.endsWith(".yml"))).map((e) => join6(dir, e.name));
   } catch {
     return [];
   }
@@ -1691,14 +1775,14 @@ async function listYamlFiles(dir) {
 
 // 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 join6, dirname as dirname2 } from "path";
+import { join as join7, dirname as dirname2 } 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 = join6(tmpdir(), `claude-eval-${randomUUID()}`);
+  const sandboxDir = join7(tmpdir(), `claude-eval-${randomUUID()}`);
   try {
     await setupSandbox(sandboxDir, scenario);
     await runClaudeInSandbox(sandboxDir, scenario.prompt, options.timeout);
@@ -1724,13 +1808,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 = join6(sandboxDir, file.path);
+    const filePath = join7(sandboxDir, file.path);
     await mkdir3(dirname2(filePath), { recursive: true });
     await writeFile3(filePath, file.content);
   }
   if (scenario.setup.instructions) {
     await writeFile3(
-      join6(sandboxDir, "CLAUDE.md"),
+      join7(sandboxDir, "CLAUDE.md"),
       `# Eval Scenario
 
 ${scenario.setup.instructions}
@@ -1843,7 +1927,7 @@ async function evaluateSingleCheck(check, sandboxDir) {
 async function checkGrep(check, sandboxDir) {
   if (!check.pattern) return false;
   try {
-    const content = await readFile7(join6(sandboxDir, check.target), "utf-8");
+    const content = await readFile7(join7(sandboxDir, check.target), "utf-8");
     let found;
     try {
       found = new RegExp(check.pattern).test(content);
@@ -1857,7 +1941,7 @@ async function checkGrep(check, sandboxDir) {
 }
 async function checkFileExists(check, sandboxDir) {
   try {
-    await readFile7(join6(sandboxDir, check.target));
+    await readFile7(join7(sandboxDir, check.target));
     return check.expect === "present";
   } catch {
     return check.expect === "absent";
@@ -1865,7 +1949,7 @@ async function checkFileExists(check, sandboxDir) {
 }
 async function checkFileAbsent(check, sandboxDir) {
   try {
-    await readFile7(join6(sandboxDir, check.target));
+    await readFile7(join7(sandboxDir, check.target));
     return check.expect === "absent";
   } catch {
     return check.expect === "present";
@@ -1874,7 +1958,7 @@ async function checkFileAbsent(check, sandboxDir) {
 async function checkMaxLines(check, sandboxDir) {
   const maxLines = parseInt(check.pattern ?? "800", 10);
   try {
-    const files = await listAllFiles(join6(sandboxDir, check.target));
+    const files = await listAllFiles(join7(sandboxDir, check.target));
     for (const file of files) {
       const content = await readFile7(file, "utf-8");
       if (content.split("\n").length > maxLines) {
@@ -1891,7 +1975,7 @@ async function listAllFiles(dir) {
   try {
     const entries = await readdir3(dir, { withFileTypes: true });
     for (const entry of entries) {
-      const fullPath = join6(dir, entry.name);
+      const fullPath = join7(dir, entry.name);
       if (entry.isDirectory()) {
         results.push(...await listAllFiles(fullPath));
       } else {
@@ -2017,7 +2101,7 @@ 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 join7 } from "path";
+import { join as join8 } 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:
 
@@ -2035,7 +2119,7 @@ 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 = join7(root, "CLAUDE.md");
+    const claudeMdPath = join8(root, "CLAUDE.md");
     try {
       await access6(claudeMdPath);
     } catch {
@@ -2064,8 +2148,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.1.0").action(async () => {
-  const hasConfig = await fileExists3(join8(process.cwd(), "CLAUDE.md")) || await fileExists3(join8(process.cwd(), ".claude", "settings.json"));
+var program = new Command5().name("claude-launchpad").description("CLI toolkit that makes Claude Code setups measurably good").version("0.2.2", "-v, --version").action(async () => {
+  const hasConfig = await fileExists3(join9(process.cwd(), "CLAUDE.md")) || await fileExists3(join9(process.cwd(), ".claude", "settings.json"));
   if (hasConfig) {
     await program.commands.find((c) => c.name() === "doctor")?.parseAsync([], { from: "user" });
   } else {