claude-crap 0.3.1 → 0.3.4

package/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crap-plugin",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "private": true,
   "description": "Runtime dependencies for the claude-crap plugin bundle",
   "type": "module",
@@ -14,5 +14,9 @@
   },
   "engines": {
     "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.2.0"
   }
 }

package/scripts/bundle-plugin.mjs

@@ -1,6 +1,7 @@
 // scripts/bundle-plugin.mjs
 import { build } from "esbuild";
 import { cp, mkdir, rm } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -66,6 +67,35 @@ async function main() {
     resolve(BUNDLE_DIR, "dashboard/public"),
     { recursive: true },
   );
+
+  // 4. Copy the launcher wrapper into the bundle directory.
+  //    launcher.mjs is the .mcp.json entry point and is hand-written
+  //    (not bundled by esbuild). It ensures node_modules/ exist before
+  //    dynamically importing the real MCP server.
+  await cp(
+    resolve(ROOT, "plugin/launcher.mjs"),
+    resolve(BUNDLE_DIR, "launcher.mjs"),
+  );
+
+  // 5. Generate plugin/package-lock.json for deterministic installs.
+  //    This lockfile ships with the plugin so that the launcher's
+  //    `npm install --omit=dev` resolves the exact same versions on
+  //    every developer's machine. `--package-lock-only` does NOT
+  //    create node_modules/, keeping the repo light.
+  try {
+    execFileSync("npm", [
+      "install",
+      "--package-lock-only",
+      "--omit=dev",
+    ], {
+      cwd: resolve(ROOT, "plugin"),
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+  } catch (err) {
+    process.stderr.write(
+      `warning: could not generate plugin/package-lock.json: ${err.message}\n`,
+    );
+  }
 }
 
 main().catch((err) => {

package/src/dashboard/server.ts

@@ -25,6 +25,7 @@
  */
 
 import { promises as fs } from "node:fs";
+import { createServer as createTcpServer } from "node:net";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -94,13 +95,12 @@ export async function startDashboard(options: StartDashboardOptions): Promise<Da
   await fastify.register(fastifyStatic, {
     root: publicRoot,
     prefix: "/",
-    decorateReply: false,
   });
 
   // ------------------------------------------------------------------
   // /api/health — liveness probe
   // ------------------------------------------------------------------
-  fastify.get("/api/health", async () => ({ status: "ok", server: "claude-crap", version: "0.1.0" }));
+  fastify.get("/api/health", async () => ({ status: "ok", server: "claude-crap", version: "0.3.4" }));
 
   // ------------------------------------------------------------------
   // /api/score — live project score
@@ -117,11 +117,31 @@ export async function startDashboard(options: StartDashboardOptions): Promise<Da
   fastify.get("/api/sarif", async () => sarifStore.toSarifDocument());
 
   // ------------------------------------------------------------------
-  // / — static SPA fallback (Fastify-static handles index.html)
+  // / — explicit SPA fallback for index.html
   // ------------------------------------------------------------------
+  // @fastify/static sometimes doesn't serve index.html on GET / when
+  // API routes are registered on the same prefix. Explicit fallback
+  // ensures the dashboard always loads.
+  fastify.get("/", async (_request, reply) => {
+    return reply.sendFile("index.html");
+  });
+
+  // Find a free port. The configured port is tried first, then up to
+  // MAX_PORT_RETRIES consecutive neighbors. This handles the common
+  // case where a previous Claude Code session left a stale MCP server
+  // process holding the default port.
+  const MAX_PORT_RETRIES = 4;
+  const boundPort = await findFreePort(config.dashboardPort, MAX_PORT_RETRIES, logger);
 
-  await fastify.listen({ port: config.dashboardPort, host: "127.0.0.1" });
-  const url = `http://127.0.0.1:${config.dashboardPort}`;
+  await fastify.listen({ port: boundPort, host: "127.0.0.1" });
+
+  const url = `http://127.0.0.1:${boundPort}`;
+  if (boundPort !== config.dashboardPort) {
+    logger.warn(
+      { url, configuredPort: config.dashboardPort, actualPort: boundPort },
+      "claude-crap dashboard bound to fallback port (configured port was in use)",
+    );
+  }
   logger.info({ url, publicRoot }, "claude-crap dashboard listening");
 
   return {
@@ -183,6 +203,56 @@ function urlOf(fastify: FastifyInstance, config: CrapConfig): string {
   return `http://127.0.0.1:${config.dashboardPort}`;
 }
 
+/**
+ * Probe a sequence of TCP ports starting at `startPort` and return the
+ * first one that is free. Uses a raw `net.createServer()` probe that
+ * opens and immediately closes to avoid interfering with Fastify's own
+ * listen lifecycle (Fastify instances cannot re-listen after close).
+ *
+ * @param startPort     The preferred port.
+ * @param maxRetries    How many consecutive ports to try after the first.
+ * @param logger        Pino logger for diagnostics.
+ * @returns             The first free port found.
+ * @throws              When all candidate ports are occupied.
+ */
+async function findFreePort(
+  startPort: number,
+  maxRetries: number,
+  logger: Logger,
+): Promise<number> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const candidatePort = startPort + attempt;
+    const isFree = await new Promise<boolean>((resolvePromise) => {
+      const probe = createTcpServer();
+      probe.once("error", (err: NodeJS.ErrnoException) => {
+        if (err.code === "EADDRINUSE") {
+          resolvePromise(false);
+        } else {
+          // Unexpected error (permission denied, etc.) — treat as unavailable.
+          resolvePromise(false);
+        }
+      });
+      probe.listen({ port: candidatePort, host: "127.0.0.1" }, () => {
+        probe.close(() => resolvePromise(true));
+      });
+    });
+
+    if (isFree) return candidatePort;
+
+    if (attempt < maxRetries) {
+      logger.info(
+        { port: candidatePort, nextPort: candidatePort + 1 },
+        "dashboard port in use, trying next",
+      );
+    }
+  }
+
+  // All ports exhausted — throw so startDashboard rejects gracefully.
+  throw new Error(
+    `[claude-crap] dashboard: all ports ${startPort}–${startPort + maxRetries} are in use`,
+  );
+}
+
 /**
  * Wrap {@link computeProjectScore} so the dashboard endpoint can call
  * it with the live store and provide consistent location metadata.

package/src/scanner/auto-scan.ts

@@ -19,6 +19,8 @@
  * @module scanner/auto-scan
  */
 
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import type { Logger } from "pino";
 import { detectScanners, type ScannerDetection } from "./detector.js";
 import { runScanner, type ScannerRunResult } from "./runner.js";
@@ -106,6 +108,32 @@ export async function autoScan(
     "auto-scan: detection complete",
   );
 
+  // If ESLint is detected (e.g. in package.json) but has no config file,
+  // bootstrap will create one before we try to scan.
+  const eslintConfigFiles = [
+    "eslint.config.js", "eslint.config.mjs", "eslint.config.cjs",
+    "eslint.config.ts", "eslint.config.mts", "eslint.config.cts",
+    ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.yaml",
+    ".eslintrc.yml", ".eslintrc.json",
+  ];
+  const eslintDetected = available.some((d) => d.scanner === "eslint");
+  const hasEslintConfig = eslintConfigFiles.some((f) => existsSync(join(workspaceRoot, f)));
+
+  if (eslintDetected && !hasEslintConfig) {
+    logger.info("auto-scan: ESLint detected but no config — running 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 config creation failed",
+      );
+    }
+  }
+
   if (available.length === 0) {
     // No scanners configured — try to bootstrap one automatically.
     logger.info("auto-scan: no scanners found, attempting bootstrap");

package/src/scanner/bootstrap.ts

@@ -137,7 +137,14 @@ export default tseslint.config(
   js.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ["dist/", "node_modules/", "coverage/"],
+    ignores: [
+      "dist/",
+      "node_modules/",
+      "coverage/",
+      "**/bundle/",
+      "**/vendor/",
+      "**/*.min.js",
+    ],
   },
 );
 `;
@@ -148,7 +155,14 @@ export default tseslint.config(
 export default [
   js.configs.recommended,
   {
-    ignores: ["dist/", "node_modules/", "coverage/"],
+    ignores: [
+      "dist/",
+      "node_modules/",
+      "coverage/",
+      "**/bundle/",
+      "**/vendor/",
+      "**/*.min.js",
+    ],
   },
 ];
 `;
@@ -292,7 +306,12 @@ export async function bootstrapScanner(
   const detections = await detectScanners(workspaceRoot);
   const available = detections.filter((d) => d.available);
 
-  if (available.length > 0) {
+  // A scanner is truly "configured" only if it also has a config
+  // file. ESLint in package.json without eslint.config.mjs will crash.
+  const eslintNeedsConfig = available.some((d) => d.scanner === "eslint")
+    && !detections.some((d) => d.scanner === "eslint" && d.configPath);
+
+  if (available.length > 0 && !eslintNeedsConfig) {
     const existingScanners = available.map((d) => d.scanner);
     logger.info(
       { existingScanners },
@@ -319,21 +338,32 @@ export async function bootstrapScanner(
     "bootstrap: detected project type",
   );
 
-  // 3. Install scanner
+  // 3. Install scanner (skip npm install if already in package.json)
   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);
+    const eslintAlreadyInstalled = available.some((d) => d.scanner === "eslint");
+
+    if (!eslintAlreadyInstalled) {
+      const packages = isTypeScript
+        ? ["eslint", "@eslint/js", "typescript-eslint"]
+        : ["eslint", "@eslint/js"];
+      const installStep = await npmInstall(workspaceRoot, packages);
+      steps.push(installStep);
+      if (!installStep.success) {
+        // npm install failed — skip config creation, fall through to result
+        return buildResult(projectType, steps, null);
+      }
+    } else {
+      steps.push({
+        action: "npm install eslint",
+        success: true,
+        detail: "eslint already in package.json — skipped install",
+      });
     }
+
+    // Always create config if missing
+    const configStep = writeEslintConfigFile(workspaceRoot, isTypeScript);
+    steps.push(configStep);
   } else {
     // Python / Java / C# / Unknown: return instructions
     steps.push({
@@ -409,18 +439,31 @@ export async function bootstrapScanner(
   }
 
   // 5. Build result
+  return buildResult(projectType, steps, autoScanResult, recommendation);
+}
+
+/**
+ * Build a BootstrapResult from the collected steps and optional scan result.
+ */
+function buildResult(
+  projectType: ProjectType,
+  steps: BootstrapStep[],
+  autoScanResult: AutoScanResult | null,
+  recommendation?: { scanner: KnownScanner; canAutoInstall: boolean; installInstructions: string },
+): BootstrapResult {
+  const success = steps.every((s) => s.success);
   const findings = autoScanResult?.totalFindings ?? 0;
-  const scannerInstalled = recommendation.canAutoInstall && installSucceeded;
+  const scanner = recommendation?.scanner ?? "unknown";
 
   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}`;
+  if (success && autoScanResult) {
+    summary = `Configured ${scanner} for ${projectType} project. Scan found ${findings} finding(s).`;
+  } else if (success && recommendation && !recommendation.canAutoInstall) {
+    summary = `Detected ${projectType} project. Install ${scanner} manually: ${recommendation.installInstructions}`;
+  } else if (success) {
+    summary = `Configured ${scanner} for ${projectType} project.`;
   } else {
-    summary = `Failed to install ${recommendation.scanner}. Check the error details in the steps.`;
+    summary = `Failed to configure ${scanner}. Check the error details in the steps.`;
   }
 
   return {
@@ -429,7 +472,7 @@ export async function bootstrapScanner(
     existingScanners: [],
     steps,
     autoScanResult,
-    success: installSucceeded,
+    success,
     summary,
   };
 }

package/src/scanner/runner.ts

@@ -124,8 +124,14 @@ export function runScanner(
         const durationMs = Date.now() - start;
 
         // For scanners where non-zero exit means "findings exist",
-        // we still have valid output in stdout.
-        if (err && !cmd.nonZeroIsNormal) {
+        // we still have valid output in stdout. But if the scanner
+        // crashed (e.g. ESLint with no config file), treat it as a
+        // real failure even when nonZeroIsNormal is set.
+        const isFatalError = cmd.nonZeroIsNormal
+          && err
+          && (!stdout?.trim() || stderr?.includes("Oops!") || stderr?.includes("couldn't find"));
+
+        if (err && (!cmd.nonZeroIsNormal || isFatalError)) {
           // Stryker: check if the output file was written despite the error
           if (cmd.outputFile && existsSync(cmd.outputFile)) {
             try {