claude-crap 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.4] - 2026-04-12
+
+### Fixed
+
+- **Out-of-the-box MCP server startup** — added `launcher.mjs` bootstrap
+  wrapper that auto-installs runtime dependencies on first run. Fresh
+  git-based installs no longer fail with `ERR_MODULE_NOT_FOUND`.
+- **Dashboard port conflict across sessions** — when port 5117 is
+  occupied by a stale process, the dashboard now probes up to 4
+  consecutive fallback ports (5118–5121) before giving up.
+- **Deterministic installs** — `plugin/package-lock.json` is now
+  generated during `build:plugin` so all users resolve identical
+  dependency versions.
+
+### Changed
+
+- MCP server entry point in `.mcp.json` changed from `mcp-server.mjs`
+  to `launcher.mjs` (the launcher dynamically imports `mcp-server.mjs`
+  after ensuring dependencies exist).
+
 ## [0.3.3] - 2026-04-12
 
 ### Fixed

package/README.md

@@ -81,7 +81,7 @@ task close — no further setup required.
 > **Two install channels are live:**
 >
 > - **npm** — `npx claude-crap install` (direct, works anywhere `npx` does)
-> - **Claude Code marketplace** — `/plugin marketplace add https://github.com/ahernandez-developer/claude-crap` followed by `/plugin install claude-crap@herz`. Claude Code resolves the marketplace entry's `source` to `claude-crap@0.1.0` on the npm registry, so both routes unpack the **same tarball** and get the same SHA.
+> - **Claude Code marketplace** — `/plugin marketplace add https://github.com/ahernandez-developer/claude-crap` followed by `/plugin install claude-crap@herz`. Claude Code resolves the marketplace entry's `source` to `claude-crap@0.3.4` on the npm registry, so both routes unpack the **same tarball** and get the same SHA.
 
 ### Marketplace cache troubleshooting
 

package/dist/dashboard/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/dashboard/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,sBAAsB,EAAE,sBAAsB,CAAC;IACxD,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0D7F"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/dashboard/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,sBAAsB,EAAE,sBAAsB,CAAC;IACxD,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAwE7F"}

package/dist/dashboard/server.js

@@ -24,6 +24,7 @@
  * @module dashboard/server
  */
 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";
 import Fastify from "fastify";
@@ -54,7 +55,7 @@ export async function startDashboard(options) {
     // ------------------------------------------------------------------
     // /api/health — liveness probe
     // ------------------------------------------------------------------
-    fastify.get("/api/health", async () => ({ status: "ok", server: "claude-crap", version: "0.3.2" }));
+    fastify.get("/api/health", async () => ({ status: "ok", server: "claude-crap", version: "0.3.4" }));
     // ------------------------------------------------------------------
     // /api/score — live project score
     // ------------------------------------------------------------------
@@ -76,8 +77,17 @@ export async function startDashboard(options) {
     fastify.get("/", async (_request, reply) => {
         return reply.sendFile("index.html");
     });
-    await fastify.listen({ port: config.dashboardPort, host: "127.0.0.1" });
-    const url = `http://127.0.0.1:${config.dashboardPort}`;
+    // 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: 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 {
         url,
@@ -134,6 +144,45 @@ function urlOf(fastify, config) {
     }
     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, maxRetries, logger) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const candidatePort = startPort + attempt;
+        const isFree = await new Promise((resolvePromise) => {
+            const probe = createTcpServer();
+            probe.once("error", (err) => {
+                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/dist/dashboard/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/dashboard/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/dashboard/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crap",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Deterministic QA plugin for Claude Code — CRAP index, Technical Debt Ratio, tree-sitter AST, SARIF 2.1.0, hooks, and a local Vue dashboard.",
   "keywords": [
     "claude-code",
@@ -128,10 +128,14 @@
     "web-tree-sitter": "^0.24.4"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^22.10.2",
     "esbuild": "^0.28.0",
+    "eslint": "^10.2.0",
+    "globals": "^17.5.0",
     "np": "^11.0.2",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.58.1"
   }
 }

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://code.claude.com/schemas/plugin.json",
   "name": "claude-crap",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Deterministic Quality Assurance plugin for Claude Code. Wraps every Write / Edit / Bash tool call with a PreToolUse gatekeeper, a PostToolUse verifier, and a Stop quality gate backed by CRAP index, Technical Debt Ratio, tree-sitter AST metrics, and SARIF 2.1.0 reports. Forbids the agent from writing functional code before a test safety net exists.",
   "author": {
     "name": "Alan Hernandez",

package/plugin/.mcp.json

@@ -5,7 +5,7 @@
       "type": "stdio",
       "command": "node",
       "args": [
-        "${CLAUDE_PLUGIN_ROOT}/bundle/mcp-server.mjs",
+        "${CLAUDE_PLUGIN_ROOT}/bundle/launcher.mjs",
         "--transport",
         "stdio"
       ],

package/plugin/bundle/launcher.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * claude-crap :: MCP server launcher — zero-dependency bootstrap wrapper.
+ *
+ * This file is the actual entry point declared in `.mcp.json`. It
+ * ensures the MCP server's runtime dependencies (fastify, pino,
+ * tree-sitter, etc.) are installed before the server's static ESM
+ * `import` statements fire. Without this guard, a clean install from
+ * git would fail with ERR_MODULE_NOT_FOUND because `node_modules/`
+ * is not committed to the repository.
+ *
+ * Design constraints:
+ *
+ *   - ZERO external dependencies — only Node.js builtins.
+ *   - Synchronous check + install so the control flow is linear.
+ *   - All output goes to stderr (fd 2) to preserve the MCP JSON-RPC
+ *     channel on stdout.
+ *   - Must work on macOS, Linux, and Windows.
+ *
+ * After dependencies are guaranteed to exist, this module dynamically
+ * imports `./mcp-server.mjs` which handles the rest of the startup.
+ *
+ * @module launcher
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The plugin root is one level above `bundle/`. This is where
+ * `package.json` lives and where `npm install` must run.
+ *
+ * In the deployed layout:
+ *   ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/
+ *     ├── package.json          ← PLUGIN_ROOT
+ *     ├── node_modules/         ← created by ensureDependencies()
+ *     └── bundle/
+ *         ├── launcher.mjs      ← this file
+ *         └── mcp-server.mjs    ← the real entry point
+ */
+const PLUGIN_ROOT = resolve(__dirname, "..");
+
+/**
+ * Check whether all runtime dependencies are installed. When they are
+ * not, run `npm install --omit=dev` synchronously and verify success.
+ *
+ * The check is deliberately simple: if the `node_modules/` directory
+ * exists we assume all packages are present. A more thorough check
+ * would resolve every external, but the cost of a false-positive skip
+ * is a cryptic ERR_MODULE_NOT_FOUND — vs. a ~5s npm install on first
+ * run. Speed wins.
+ */
+function ensureDependencies() {
+  const nodeModulesPath = join(PLUGIN_ROOT, "node_modules");
+  if (existsSync(nodeModulesPath)) return; // fast path — already installed
+
+  // ── Report what we're about to install ────────────────────────────
+  let depsSummary = "(unable to read package.json)";
+  try {
+    const pkgPath = join(PLUGIN_ROOT, "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const deps = Object.entries(pkg.dependencies || {});
+    depsSummary = deps.map(([n, v]) => `${n}@${v}`).join(", ");
+  } catch {
+    /* proceed anyway — the install itself will surface any real error */
+  }
+
+  process.stderr.write(
+    `[claude-crap] node_modules/ not found — installing runtime dependencies...\n` +
+      `[claude-crap] deps: ${depsSummary}\n`,
+  );
+
+  // ── Run npm install synchronously ─────────────────────────────────
+  try {
+    execFileSync("npm", [
+      "install",
+      "--omit=dev",
+      "--no-audit",
+      "--no-fund",
+      "--no-progress",
+      "--loglevel=error",
+    ], {
+      cwd: PLUGIN_ROOT,
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 120_000, // 2 minutes — generous for slow networks
+      env: { ...process.env, NODE_ENV: "production" },
+    });
+    process.stderr.write("[claude-crap] dependencies installed successfully.\n");
+  } catch (err) {
+    const stderr = /** @type {any} */ (err).stderr?.toString?.() ?? "";
+    const lastLines = stderr.split("\n").filter(Boolean).slice(-20).join("\n");
+    process.stderr.write(
+      `[claude-crap] FATAL: npm install failed (exit ${/** @type {any} */ (err).status ?? "unknown"}).\n` +
+        (lastLines ? `${lastLines}\n` : "") +
+        `[claude-crap] Try manually: cd "${PLUGIN_ROOT}" && npm install --omit=dev\n`,
+    );
+    process.exit(1);
+  }
+}
+
+// ── Bootstrap ─────────────────────────────────────────────────────────
+ensureDependencies();
+
+// Now that node_modules/ exists, the static ESM imports inside
+// mcp-server.mjs can resolve. Dynamic import avoids top-level
+// resolution failures.
+await import("./mcp-server.mjs");

package/plugin/bundle/mcp-server.mjs

@@ -7236,6 +7236,7 @@ function loadConfig() {
 
 // src/dashboard/server.ts
 import { promises as fs2 } from "node:fs";
+import { createServer as createTcpServer } from "node:net";
 import { dirname as dirname2, resolve as resolve2 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import Fastify from "fastify";
@@ -7416,7 +7417,7 @@ async function startDashboard(options) {
     root: publicRoot,
     prefix: "/"
   });
-  fastify.get("/api/health", async () => ({ status: "ok", server: "claude-crap", version: "0.3.2" }));
+  fastify.get("/api/health", async () => ({ status: "ok", server: "claude-crap", version: "0.3.4" }));
   fastify.get("/api/score", async () => {
     const stats = await workspaceStatsProvider();
     const score = await buildScore(config, sarifStore, stats, urlOf(fastify, config));
@@ -7426,8 +7427,16 @@ async function startDashboard(options) {
   fastify.get("/", async (_request, reply) => {
     return reply.sendFile("index.html");
   });
-  await fastify.listen({ port: config.dashboardPort, host: "127.0.0.1" });
-  const url = `http://127.0.0.1:${config.dashboardPort}`;
+  const MAX_PORT_RETRIES = 4;
+  const boundPort = await findFreePort(config.dashboardPort, MAX_PORT_RETRIES, logger2);
+  await fastify.listen({ port: boundPort, host: "127.0.0.1" });
+  const url = `http://127.0.0.1:${boundPort}`;
+  if (boundPort !== config.dashboardPort) {
+    logger2.warn(
+      { url, configuredPort: config.dashboardPort, actualPort: boundPort },
+      "claude-crap dashboard bound to fallback port (configured port was in use)"
+    );
+  }
   logger2.info({ url, publicRoot }, "claude-crap dashboard listening");
   return {
     url,
@@ -7471,6 +7480,34 @@ function urlOf(fastify, config) {
   }
   return `http://127.0.0.1:${config.dashboardPort}`;
 }
+async function findFreePort(startPort, maxRetries, logger2) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const candidatePort = startPort + attempt;
+    const isFree = await new Promise((resolvePromise) => {
+      const probe = createTcpServer();
+      probe.once("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+          resolvePromise(false);
+        } else {
+          resolvePromise(false);
+        }
+      });
+      probe.listen({ port: candidatePort, host: "127.0.0.1" }, () => {
+        probe.close(() => resolvePromise(true));
+      });
+    });
+    if (isFree) return candidatePort;
+    if (attempt < maxRetries) {
+      logger2.info(
+        { port: candidatePort, nextPort: candidatePort + 1 },
+        "dashboard port in use, trying next"
+      );
+    }
+  }
+  throw new Error(
+    `[claude-crap] dashboard: all ports ${startPort}\u2013${startPort + maxRetries} are in use`
+  );
+}
 async function buildScore(config, sarifStore, workspace, dashboardUrl) {
   return computeProjectScore({
     workspaceRoot: config.pluginRoot,