claude-crap 0.2.0 → 0.3.1

package/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crap-plugin",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": true,
   "description": "Runtime dependencies for the claude-crap plugin bundle",
   "type": "module",

package/src/index.ts

@@ -58,8 +58,10 @@ import { loadCrapConfig, CrapConfigError } from "./crap-config.js";
 import { findTestFile } from "./tools/test-harness.js";
 import { resolveWithinWorkspace } from "./workspace-guard.js";
 import { autoScan } from "./scanner/auto-scan.js";
+import { bootstrapScanner } from "./scanner/bootstrap.js";
 import {
   autoScanSchema,
+  bootstrapScannerSchema,
   computeCrapSchema,
   computeTdrSchema,
   analyzeFileAstSchema,
@@ -213,6 +215,12 @@ async function main(): Promise<void> {
           "Auto-detect available scanners (ESLint, Semgrep, Bandit, Stryker) in the workspace, run them, and ingest findings into the SARIF store.",
         inputSchema: autoScanSchema,
       },
+      {
+        name: "bootstrap_scanner",
+        description:
+          "Detect project type, install the right scanner (ESLint for JS/TS, Bandit for Python, Semgrep for Java/C#), create minimal config, and run auto_scan to verify.",
+        inputSchema: bootstrapScannerSchema,
+      },
     ],
   }));
 
@@ -540,6 +548,36 @@ async function main(): Promise<void> {
         }
       }
 
+      case "bootstrap_scanner": {
+        logger.info({ tool: "bootstrap_scanner" }, "Tool call received");
+        try {
+          const result = await bootstrapScanner(config.pluginRoot, sarifStore, logger);
+          const markdown = renderBootstrapMarkdown(result);
+          return {
+            content: [
+              { type: "text", text: markdown },
+              { type: "text", text: JSON.stringify(result, null, 2) },
+            ],
+            isError: !result.success,
+          };
+        } catch (err) {
+          logger.error({ err }, "bootstrap_scanner failed");
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  { tool: "bootstrap_scanner", status: "error", message: (err as Error).message },
+                  null,
+                  2,
+                ),
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
       case "auto_scan": {
         logger.info({ tool: "auto_scan" }, "Tool call received");
         try {
@@ -653,6 +691,46 @@ async function main(): Promise<void> {
     });
 }
 
+/**
+ * Render a human-readable Markdown summary of a bootstrap result.
+ */
+function renderBootstrapMarkdown(result: import("./scanner/bootstrap.js").BootstrapResult): string {
+  const lines: string[] = ["## claude-crap :: bootstrap scanner\n"];
+
+  lines.push(`**Project type:** ${result.projectType}`);
+
+  if (result.alreadyConfigured) {
+    lines.push(`**Status:** Scanner(s) already configured: ${result.existingScanners.join(", ")}`);
+    lines.push("\nNo installation needed. Run `auto_scan` to ingest findings.");
+    return lines.join("\n");
+  }
+
+  lines.push("");
+
+  if (result.steps.length > 0) {
+    lines.push("### Steps\n");
+    lines.push("| Action | Status | Detail |");
+    lines.push("| ------ | :----: | ------ |");
+    for (const s of result.steps) {
+      const status = s.success ? "ok" : "failed";
+      lines.push(`| ${s.action} | ${status} | ${s.detail} |`);
+    }
+    lines.push("");
+  }
+
+  if (result.autoScanResult) {
+    const r = result.autoScanResult;
+    const scanners = r.results.filter((s) => s.success).map((s) => s.scanner);
+    lines.push(
+      `**Auto-scan:** ${r.totalFindings} finding(s) ingested from ${scanners.join(", ") || "no scanners"} in ${(r.totalDurationMs / 1000).toFixed(1)}s`,
+    );
+    lines.push("");
+  }
+
+  lines.push(`**Summary:** ${result.summary}`);
+  return lines.join("\n");
+}
+
 /**
  * Render a human-readable Markdown summary of an auto-scan result.
  */

package/src/scanner/auto-scan.ts

@@ -22,6 +22,7 @@
 import type { Logger } from "pino";
 import { detectScanners, type ScannerDetection } from "./detector.js";
 import { runScanner, type ScannerRunResult } from "./runner.js";
+import { bootstrapScanner } from "./bootstrap.js";
 import { adaptScannerOutput, type KnownScanner } from "../adapters/index.js";
 import type { SarifStore } from "../sarif/sarif-store.js";
 
@@ -106,6 +107,20 @@ export async function autoScan(
   );
 
   if (available.length === 0) {
+    // No scanners configured — try to bootstrap one automatically.
+    logger.info("auto-scan: no scanners found, attempting bootstrap");
+    try {
+      const bootstrapResult = await bootstrapScanner(workspaceRoot, sarifStore, logger);
+      if (bootstrapResult.autoScanResult) {
+        return bootstrapResult.autoScanResult;
+      }
+    } catch (err) {
+      logger.warn(
+        { err: (err as Error).message },
+        "auto-scan: bootstrap failed — continuing with empty results",
+      );
+    }
+
     return {
       detected,
       results: [],

package/src/scanner/bootstrap.ts

@@ -0,0 +1,435 @@
+/**
+ * Bootstrap a scanner for projects that don't have one configured.
+ *
+ * Detects the project type from workspace signals (package.json,
+ * tsconfig.json, pyproject.toml, pom.xml, *.csproj, etc.), installs
+ * the appropriate scanner, creates a minimal config file, and runs
+ * `autoScan()` to verify and ingest findings immediately.
+ *
+ * Coverage maps to the five languages the tree-sitter engine supports:
+ *
+ *   - JavaScript / TypeScript → ESLint (npm install + flat config)
+ *   - Python → Bandit (install instructions only — virtualenv boundary)
+ *   - Java → Semgrep (install instructions)
+ *   - C# → Semgrep (install instructions)
+ *   - Unknown → Semgrep (polyglot fallback)
+ *
+ * For JS/TS projects the tool runs `npm install --save-dev` and writes
+ * an `eslint.config.mjs`. For all other languages it returns manual
+ * install instructions rather than executing package managers whose
+ * environment assumptions may not hold.
+ *
+ * @module scanner/bootstrap
+ */
+
+import { existsSync, writeFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import type { Logger } from "pino";
+import type { KnownScanner } from "../adapters/common.js";
+import { adaptScannerOutput } from "../adapters/index.js";
+import { detectScanners } from "./detector.js";
+import { runScanner } from "./runner.js";
+import type { AutoScanResult, ScannerResult } from "./auto-scan.js";
+import type { SarifStore } from "../sarif/sarif-store.js";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+/**
+ * Detected project type, aligned with tree-sitter supported languages.
+ */
+export type ProjectType =
+  | "javascript"
+  | "typescript"
+  | "python"
+  | "java"
+  | "csharp"
+  | "unknown";
+
+/**
+ * A single step in the bootstrap process.
+ */
+export interface BootstrapStep {
+  /** What was attempted (e.g. "install eslint", "create eslint.config.mjs"). */
+  action: string;
+  /** Whether the step completed successfully. */
+  success: boolean;
+  /** Human-readable detail (command output, error message, or instruction). */
+  detail: string;
+}
+
+/**
+ * Complete result of a bootstrap_scanner invocation.
+ */
+export interface BootstrapResult {
+  /** Detected project type based on workspace signals. */
+  projectType: ProjectType;
+  /** Whether a scanner was already configured (detected by detector.ts). */
+  alreadyConfigured: boolean;
+  /** Which scanners were already available, if any. */
+  existingScanners: string[];
+  /** Steps executed (or instructions returned) during bootstrap. */
+  steps: BootstrapStep[];
+  /** The auto-scan result after installation (null if skipped). */
+  autoScanResult: AutoScanResult | null;
+  /** Whether the overall bootstrap succeeded. */
+  success: boolean;
+  /** Summary message suitable for display. */
+  summary: string;
+}
+
+// ── Project type detection ─────────────────────────────────────────
+
+/**
+ * Detect the project type from workspace signals.
+ *
+ * Checks in priority order: TypeScript, JavaScript, Python, Java,
+ * C#, then unknown. TypeScript wins over plain JavaScript because
+ * `tsconfig.json` implies a superset.
+ */
+export function detectProjectType(workspaceRoot: string): ProjectType {
+  const has = (file: string) => existsSync(join(workspaceRoot, file));
+
+  // JS/TS detection — package.json is the anchor
+  if (has("package.json")) {
+    if (has("tsconfig.json")) return "typescript";
+    return "javascript";
+  }
+
+  // Python detection
+  if (has("pyproject.toml") || has("setup.py") || has("requirements.txt")) {
+    return "python";
+  }
+
+  // Java detection
+  if (has("pom.xml") || has("build.gradle") || has("build.gradle.kts")) {
+    return "java";
+  }
+
+  // C# detection
+  if (has("Directory.Build.props")) return "csharp";
+  try {
+    const entries = readdirSync(workspaceRoot);
+    if (entries.some((e) => e.endsWith(".csproj") || e.endsWith(".sln"))) {
+      return "csharp";
+    }
+  } catch {
+    // readdirSync can fail on permissions — fall through
+  }
+
+  return "unknown";
+}
+
+// ── ESLint config generation ───────────────────────────────────────
+
+/**
+ * Generate a minimal ESLint flat config (ESLint 9+).
+ *
+ * @param isTypeScript Include typescript-eslint when true.
+ * @returns The config file content as a string.
+ */
+export function generateEslintConfig(isTypeScript: boolean): string {
+  if (isTypeScript) {
+    return `import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    ignores: ["dist/", "node_modules/", "coverage/"],
+  },
+);
+`;
+  }
+
+  return `import js from "@eslint/js";
+
+export default [
+  js.configs.recommended,
+  {
+    ignores: ["dist/", "node_modules/", "coverage/"],
+  },
+];
+`;
+}
+
+// ── Installation helpers ───────────────────────────────────────────
+
+/**
+ * Run `npm install --save-dev` for the given packages.
+ */
+function npmInstall(
+  workspaceRoot: string,
+  packages: string[],
+): Promise<BootstrapStep> {
+  return new Promise((resolve) => {
+    execFile(
+      "npm",
+      ["install", "--save-dev", ...packages],
+      {
+        cwd: workspaceRoot,
+        timeout: 120_000,
+        env: { ...process.env, FORCE_COLOR: "0" },
+      },
+      (err, stdout, stderr) => {
+        if (err) {
+          resolve({
+            action: `npm install --save-dev ${packages.join(" ")}`,
+            success: false,
+            detail: stderr || (err as Error).message,
+          });
+          return;
+        }
+        resolve({
+          action: `npm install --save-dev ${packages.join(" ")}`,
+          success: true,
+          detail: `installed ${packages.join(", ")}`,
+        });
+      },
+    );
+  });
+}
+
+/**
+ * Write the ESLint config file to the workspace root.
+ * Returns failure if the file already exists.
+ */
+function writeEslintConfigFile(
+  workspaceRoot: string,
+  isTypeScript: boolean,
+): BootstrapStep {
+  const configPath = join(workspaceRoot, "eslint.config.mjs");
+  if (existsSync(configPath)) {
+    return {
+      action: "create eslint.config.mjs",
+      success: true,
+      detail: "eslint.config.mjs already exists — skipped",
+    };
+  }
+
+  try {
+    writeFileSync(configPath, generateEslintConfig(isTypeScript), "utf-8");
+    return {
+      action: "create eslint.config.mjs",
+      success: true,
+      detail: `created eslint.config.mjs (${isTypeScript ? "TypeScript" : "JavaScript"} template)`,
+    };
+  } catch (err) {
+    return {
+      action: "create eslint.config.mjs",
+      success: false,
+      detail: (err as Error).message,
+    };
+  }
+}
+
+// ── Scanner-to-language mapping ────────────────────────────────────
+
+/**
+ * Map project type → recommended scanner and install instructions.
+ */
+interface ScannerRecommendation {
+  scanner: KnownScanner;
+  canAutoInstall: boolean;
+  installInstructions: string;
+}
+
+function getRecommendation(projectType: ProjectType): ScannerRecommendation {
+  switch (projectType) {
+    case "javascript":
+    case "typescript":
+      return {
+        scanner: "eslint",
+        canAutoInstall: true,
+        installInstructions: "npm install --save-dev eslint @eslint/js",
+      };
+    case "python":
+      return {
+        scanner: "bandit",
+        canAutoInstall: false,
+        installInstructions:
+          "pip install bandit  (or: pipx install bandit, poetry add --group dev bandit)",
+      };
+    case "java":
+    case "csharp":
+      return {
+        scanner: "semgrep",
+        canAutoInstall: false,
+        installInstructions:
+          "brew install semgrep  (or: pip install semgrep, pipx install semgrep)",
+      };
+    case "unknown":
+      return {
+        scanner: "semgrep",
+        canAutoInstall: false,
+        installInstructions:
+          "brew install semgrep  (or: pip install semgrep, pipx install semgrep)",
+      };
+  }
+}
+
+// ── Main orchestrator ──────────────────────────────────────────────
+
+/**
+ * Bootstrap a scanner for the current workspace.
+ *
+ * 1. Check if a scanner is already configured (short-circuit if so)
+ * 2. Detect the project type
+ * 3. Install the recommended scanner (or return instructions)
+ * 4. Run auto_scan to verify and ingest findings
+ *
+ * @param workspaceRoot Absolute path to the project root.
+ * @param sarifStore    Live SARIF store for auto-scan ingestion.
+ * @param logger        Pino logger for progress reporting.
+ */
+export async function bootstrapScanner(
+  workspaceRoot: string,
+  sarifStore: SarifStore,
+  logger: Logger,
+): Promise<BootstrapResult> {
+  // 1. Check existing scanners
+  const detections = await detectScanners(workspaceRoot);
+  const available = detections.filter((d) => d.available);
+
+  if (available.length > 0) {
+    const existingScanners = available.map((d) => d.scanner);
+    logger.info(
+      { existingScanners },
+      "bootstrap: scanner(s) already configured — skipping",
+    );
+    return {
+      projectType: detectProjectType(workspaceRoot),
+      alreadyConfigured: true,
+      existingScanners,
+      steps: [],
+      autoScanResult: null,
+      success: true,
+      summary: `Scanner(s) already configured: ${existingScanners.join(", ")}. Run auto_scan to ingest findings.`,
+    };
+  }
+
+  // 2. Detect project type
+  const projectType = detectProjectType(workspaceRoot);
+  const recommendation = getRecommendation(projectType);
+  const steps: BootstrapStep[] = [];
+
+  logger.info(
+    { projectType, scanner: recommendation.scanner },
+    "bootstrap: detected project type",
+  );
+
+  // 3. Install scanner
+  if (recommendation.canAutoInstall) {
+    // JS/TS: auto-install ESLint
+    const isTypeScript = projectType === "typescript";
+    const packages = isTypeScript
+      ? ["eslint", "@eslint/js", "typescript-eslint"]
+      : ["eslint", "@eslint/js"];
+
+    const installStep = await npmInstall(workspaceRoot, packages);
+    steps.push(installStep);
+
+    if (installStep.success) {
+      const configStep = writeEslintConfigFile(workspaceRoot, isTypeScript);
+      steps.push(configStep);
+    }
+  } else {
+    // Python / Java / C# / Unknown: return instructions
+    steps.push({
+      action: `suggest ${recommendation.scanner} install`,
+      success: true,
+      detail: recommendation.installInstructions,
+    });
+  }
+
+  // 4. Run scanner directly if installation succeeded (inline scan
+  //    to avoid circular dependency — autoScan calls bootstrapScanner)
+  const installSucceeded = steps.every((s) => s.success);
+  let autoScanResult: AutoScanResult | null = null;
+
+  if (installSucceeded && recommendation.canAutoInstall) {
+    try {
+      const scanStart = Date.now();
+      const postDetections = await detectScanners(workspaceRoot);
+      const postAvailable = postDetections.filter((d) => d.available);
+      const scanResults: ScannerResult[] = [];
+      let scanFindings = 0;
+
+      const settled = await Promise.allSettled(
+        postAvailable.map((d) => runScanner(d.scanner, workspaceRoot)),
+      );
+
+      for (let i = 0; i < postAvailable.length; i++) {
+        const det = postAvailable[i]!;
+        const res = settled[i]!;
+
+        if (res.status === "rejected" || !res.value.success) {
+          scanResults.push({
+            scanner: det.scanner,
+            success: false,
+            findingsIngested: 0,
+            durationMs: res.status === "fulfilled" ? res.value.durationMs : 0,
+            error: res.status === "rejected"
+              ? String(res.reason)
+              : res.value.error ?? "unknown error",
+          });
+          continue;
+        }
+
+        const runResult = res.value;
+        let parsed: unknown;
+        try { parsed = JSON.parse(runResult.rawOutput); } catch { parsed = runResult.rawOutput; }
+        const adapted = adaptScannerOutput(runResult.scanner, parsed);
+        const stats = sarifStore.ingestRun(adapted.document, adapted.sourceTool);
+        scanFindings += stats.accepted;
+
+        scanResults.push({
+          scanner: runResult.scanner,
+          success: true,
+          findingsIngested: stats.accepted,
+          durationMs: runResult.durationMs,
+        });
+      }
+
+      if (scanFindings > 0) await sarifStore.persist();
+
+      autoScanResult = {
+        detected: postDetections,
+        results: scanResults,
+        totalFindings: scanFindings,
+        totalDurationMs: Date.now() - scanStart,
+      };
+    } catch (err) {
+      logger.warn(
+        { err: (err as Error).message },
+        "bootstrap: scan after install failed",
+      );
+    }
+  }
+
+  // 5. Build result
+  const findings = autoScanResult?.totalFindings ?? 0;
+  const scannerInstalled = recommendation.canAutoInstall && installSucceeded;
+
+  let summary: string;
+  if (scannerInstalled && autoScanResult) {
+    summary = `Installed ${recommendation.scanner} for ${projectType} project. Auto-scan found ${findings} finding(s).`;
+  } else if (scannerInstalled) {
+    summary = `Installed ${recommendation.scanner} for ${projectType} project. Auto-scan did not run.`;
+  } else if (!recommendation.canAutoInstall) {
+    summary = `Detected ${projectType} project. Install ${recommendation.scanner} manually: ${recommendation.installInstructions}`;
+  } else {
+    summary = `Failed to install ${recommendation.scanner}. Check the error details in the steps.`;
+  }
+
+  return {
+    projectType,
+    alreadyConfigured: false,
+    existingScanners: [],
+    steps,
+    autoScanResult,
+    success: installSucceeded,
+    summary,
+  };
+}

package/src/scanner/index.ts

@@ -20,3 +20,11 @@
 export { detectScanners, type ScannerDetection } from "./detector.js";
 export { runScanner, type ScannerRunResult } from "./runner.js";
 export { autoScan, type AutoScanResult, type ScannerResult } from "./auto-scan.js";
+export {
+  bootstrapScanner,
+  detectProjectType,
+  generateEslintConfig,
+  type BootstrapResult,
+  type BootstrapStep,
+  type ProjectType,
+} from "./bootstrap.js";

package/src/schemas/tool-schemas.ts

@@ -203,6 +203,20 @@ export const ingestScannerOutputSchema = {
  * Schema for the `auto_scan` tool. Auto-detects available scanners
  * in the workspace, runs them, and ingests findings into the SARIF store.
  */
+/**
+ * Schema for the `bootstrap_scanner` tool. Detects project type,
+ * installs the appropriate scanner, creates config files, and runs
+ * auto_scan to verify.
+ */
+export const bootstrapScannerSchema = {
+  type: "object",
+  description:
+    "Detect the project type (JavaScript, TypeScript, Python, Java, C#), install the appropriate scanner (ESLint for JS/TS, Bandit for Python, Semgrep for Java/C#), create a minimal config file, and run auto_scan to verify. Skips installation if a scanner is already configured. Use this when auto_scan finds no scanners and quality grades are vacuously A.",
+  properties: {},
+  required: [],
+  additionalProperties: false,
+} as const;
+
 export const autoScanSchema = {
   type: "object",
   description:

package/src/tests/integration/mcp-server.integration.test.ts

@@ -232,7 +232,7 @@ describe("MCP server integration", { skip: !serverBuilt }, () => {
     assert.ok(child && !child.killed, "server child should be running");
   });
 
-  it("exposes all eight tools via tools/list", async () => {
+  it("exposes all nine tools via tools/list", async () => {
     const response = await client!.request<{ result?: { tools?: Array<{ name: string }> } }>(
       "tools/list",
     );
@@ -240,6 +240,7 @@ describe("MCP server integration", { skip: !serverBuilt }, () => {
     assert.deepEqual(names, [
       "analyze_file_ast",
       "auto_scan",
+      "bootstrap_scanner",
       "compute_crap",
       "compute_tdr",
       "ingest_sarif",