claude-crap 0.1.2

package/scripts/doctor.mjs

@@ -0,0 +1,320 @@
+// @ts-check
+/**
+ * `claude-crap doctor` — full diagnostic pass.
+ *
+ * Runs every check the install script runs, plus several deeper probes
+ * that make sure the plugin can actually function against the current
+ * workspace:
+ *
+ *   - Node.js runtime ≥ 20
+ *   - Plugin structure sanity (package.json, .claude-plugin/plugin.json,
+ *     .mcp.json, hooks/hooks.json)
+ *   - `dist/index.js` exists (built)
+ *   - Hook scripts are executable
+ *   - tree-sitter runtime WASM is reachable
+ *   - tree-sitter language grammars (c_sharp, javascript, typescript,
+ *     python, java) are all present
+ *   - Dashboard port is free on 127.0.0.1
+ *   - SARIF reports directory is writable in the current workspace
+ *
+ * Exits 0 when all checks pass, 1 when any check fails, and 2 when
+ * there are only warnings. This makes it easy to embed in CI:
+ * `claude-crap doctor && echo ok`.
+ *
+ * @module scripts/doctor
+ */
+
+import { promises as fs, constants as fsConstants } from "node:fs";
+import { createServer } from "node:net";
+import { join, resolve } from "node:path";
+
+import { printBanner, printStep, paint, icons } from "./lib/cli-ui.mjs";
+
+const SUPPORTED_LANGUAGES = /** @type {const} */ ([
+  { id: "c_sharp", wasm: "tree-sitter-c_sharp.wasm" },
+  { id: "javascript", wasm: "tree-sitter-javascript.wasm" },
+  { id: "typescript", wasm: "tree-sitter-typescript.wasm" },
+  { id: "python", wasm: "tree-sitter-python.wasm" },
+  { id: "java", wasm: "tree-sitter-java.wasm" },
+]);
+
+/**
+ * @typedef {Object} CommandContext
+ * @property {string}   pluginRoot
+ * @property {string[]} argv
+ */
+
+/**
+ * Doctor entrypoint.
+ *
+ * @param {CommandContext} ctx
+ * @returns {Promise<number>}
+ */
+export default async function doctor(ctx) {
+  printBanner("claude-crap :: doctor");
+
+  const checks = [];
+  checks.push(await checkNodeVersion());
+  checks.push(await checkPluginStructure(ctx.pluginRoot));
+  checks.push(await checkDist(ctx.pluginRoot));
+  checks.push(await checkHooksExecutable(ctx.pluginRoot));
+  checks.push(await checkTreeSitterRuntime(ctx.pluginRoot));
+  checks.push(...(await checkGrammars(ctx.pluginRoot)));
+  checks.push(await checkDashboardPort());
+  checks.push(await checkReportsWritable(process.cwd()));
+
+  for (const step of checks) printStep(step);
+
+  const fails = checks.filter((c) => c.status === "fail").length;
+  const warns = checks.filter((c) => c.status === "warn").length;
+
+  process.stdout.write(
+    `\n${paint.bold("Summary:")} ${checks.length - fails - warns} ok, ${warns} warn, ${fails} fail\n`,
+  );
+
+  if (fails > 0) {
+    process.stdout.write(
+      `${paint.red(icons.fail)} At least one check failed. Fix the issues above and re-run ${paint.bold("claude-crap doctor")}.\n`,
+    );
+    return 1;
+  }
+  if (warns > 0) {
+    process.stdout.write(
+      `${paint.yellow(icons.warn)} Checks passed with warnings. The plugin should still work.\n`,
+    );
+    return 2;
+  }
+  process.stdout.write(`${paint.green(icons.ok)} All checks passed. claude-crap is ready.\n`);
+  return 0;
+}
+
+/** @returns {Promise<import("./lib/cli-ui.mjs").StepResult>} */
+async function checkNodeVersion() {
+  const raw = process.versions.node;
+  const major = Number(raw.split(".")[0]);
+  if (!Number.isFinite(major) || major < 20) {
+    return {
+      status: "fail",
+      label: `Node.js runtime (${raw})`,
+      detail: `claude-crap requires Node.js ≥ 20.0.0`,
+    };
+  }
+  return { status: "ok", label: `Node.js runtime (${raw})` };
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkPluginStructure(pluginRoot) {
+  const required = [
+    "package.json",
+    "plugin/.claude-plugin/plugin.json",
+    "plugin/.mcp.json",
+    "plugin/CLAUDE.md",
+    "plugin/hooks/hooks.json",
+    "plugin/hooks/pre-tool-use.mjs",
+    "plugin/hooks/post-tool-use.mjs",
+    "plugin/hooks/stop-quality-gate.mjs",
+    "plugin/hooks/session-start.mjs",
+  ];
+  const missing = [];
+  for (const rel of required) {
+    try {
+      await fs.access(join(pluginRoot, rel));
+    } catch {
+      missing.push(rel);
+    }
+  }
+  if (missing.length > 0) {
+    return {
+      status: "fail",
+      label: `Plugin files present`,
+      detail: `Missing: ${missing.join(", ")}`,
+    };
+  }
+  return { status: "ok", label: `Plugin files present (${required.length} checked)` };
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkDist(pluginRoot) {
+  const npmEntry = join(pluginRoot, "dist", "index.js");
+  const gitEntry = join(pluginRoot, "plugin", "bundle", "mcp-server.mjs");
+  
+  let npmOk = false;
+  let gitOk = false;
+  let npmAge, gitAge;
+
+  try {
+    const stat = await fs.stat(npmEntry);
+    npmAge = Math.round((Date.now() - stat.mtimeMs) / (1000 * 60 * 60));
+    npmOk = true;
+  } catch {}
+
+  try {
+    const stat = await fs.stat(gitEntry);
+    gitAge = Math.round((Date.now() - stat.mtimeMs) / (1000 * 60 * 60));
+    gitOk = true;
+  } catch {}
+
+  const details = [];
+  if (npmOk) details.push(`dist/index.js (~${npmAge}h)`);
+  if (gitOk) details.push(`plugin/bundle/mcp-server.mjs (~${gitAge}h)`);
+
+  if (!npmOk && !gitOk) {
+    return {
+      status: "fail",
+      label: `Server entrypoints built`,
+      detail: `Both dist/ and plugin/bundle/ are missing. Run \`npm run build && npm run build:plugin\`.`
+    };
+  }
+
+  return {
+    status: npmOk && gitOk ? "ok" : "warn",
+    label: `Server entrypoints built`,
+    detail: details.join(", ") + (!npmOk || !gitOk ? " (one is missing)" : "")
+  };
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkHooksExecutable(pluginRoot) {
+  const hooks = ["pre-tool-use.mjs", "post-tool-use.mjs", "stop-quality-gate.mjs", "session-start.mjs"];
+  const notExec = [];
+  for (const name of hooks) {
+    const full = join(pluginRoot, "plugin", "hooks", name);
+    try {
+      await fs.access(full, fsConstants.X_OK);
+    } catch {
+      notExec.push(name);
+    }
+  }
+  if (notExec.length > 0) {
+    return {
+      status: "warn",
+      label: `Hooks are executable`,
+      detail:
+        `${notExec.length} hook(s) lack the executable bit: ${notExec.join(", ")}. ` +
+        `Run \`claude-crap install\` to fix.`,
+    };
+  }
+  return { status: "ok", label: `Hooks are executable (4 checked)` };
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkTreeSitterRuntime(pluginRoot) {
+  const runtime = join(pluginRoot, "node_modules", "web-tree-sitter", "tree-sitter.wasm");
+  try {
+    const stat = await fs.stat(runtime);
+    return {
+      status: "ok",
+      label: `tree-sitter runtime WASM present`,
+      detail: `${runtime} (${stat.size} bytes)`,
+    };
+  } catch {
+    return {
+      status: "fail",
+      label: `tree-sitter runtime WASM present`,
+      detail: `Missing ${runtime}. Run \`npm install\` from ${pluginRoot}.`,
+    };
+  }
+}
+
+/**
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult[]>}
+ */
+async function checkGrammars(pluginRoot) {
+  const base = join(pluginRoot, "node_modules", "tree-sitter-wasms", "out");
+  /** @type {import("./lib/cli-ui.mjs").StepResult[]} */
+  const results = [];
+  for (const lang of SUPPORTED_LANGUAGES) {
+    const full = join(base, lang.wasm);
+    try {
+      await fs.access(full);
+      results.push({ status: "ok", label: `Grammar: ${lang.id}` });
+    } catch {
+      results.push({
+        status: "fail",
+        label: `Grammar: ${lang.id}`,
+        detail: `Missing ${full}. Run \`npm install\`.`,
+      });
+    }
+  }
+  return results;
+}
+
+/**
+ * Probe the configured dashboard port on 127.0.0.1. We attempt to
+ * open a TCP listener ourselves — if it succeeds the port is free,
+ * if it fails with EADDRINUSE then something is already holding it.
+ *
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkDashboardPort() {
+  const raw = process.env.CLAUDE_PLUGIN_OPTION_DASHBOARD_PORT;
+  const port = Number(raw ?? 5117);
+  if (!Number.isFinite(port)) {
+    return {
+      status: "warn",
+      label: `Dashboard port configured`,
+      detail: `CLAUDE_PLUGIN_OPTION_DASHBOARD_PORT=${raw} is not a number`,
+    };
+  }
+  return await new Promise((resolvePromise) => {
+    const server = createServer();
+    server.once("error", (err) => {
+      const nodeErr = /** @type {NodeJS.ErrnoException} */ (err);
+      if (nodeErr.code === "EADDRINUSE") {
+        resolvePromise({
+          status: "warn",
+          label: `Dashboard port ${port} is free`,
+          detail:
+            `Port ${port} is already in use. The dashboard will refuse to start ` +
+            `but the MCP server will keep running.`,
+        });
+      } else {
+        resolvePromise({
+          status: "warn",
+          label: `Dashboard port ${port} is free`,
+          detail: nodeErr.message,
+        });
+      }
+    });
+    server.listen({ port, host: "127.0.0.1" }, () => {
+      server.close(() => {
+        resolvePromise({ status: "ok", label: `Dashboard port ${port} is free` });
+      });
+    });
+  });
+}
+
+/**
+ * @param {string} workspace
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkReportsWritable(workspace) {
+  const dir = resolve(workspace, ".claude-crap", "reports");
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    // Try to write a tiny probe file and then immediately unlink it.
+    const probe = join(dir, `.doctor-${process.pid}`);
+    await fs.writeFile(probe, "ok");
+    await fs.unlink(probe);
+    return { status: "ok", label: `SARIF reports directory writable`, detail: dir };
+  } catch (err) {
+    return {
+      status: "fail",
+      label: `SARIF reports directory writable`,
+      detail: `${dir} :: ${/** @type {Error} */ (err).message}`,
+    };
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,192 @@
+// @ts-check
+/**
+ * `claude-crap install` — prepare the workspace and print the Claude
+ * Code registration command.
+ *
+ * This subcommand does every bit of side-effecty work that the plugin
+ * needs to run cleanly AND nothing else. We intentionally do NOT try to
+ * edit Claude Code's own settings file — that surface is owned by
+ * Claude Code's `/plugin install` command, and manipulating it behind
+ * the user's back would be a support nightmare. Instead, we:
+ *
+ *   1. Verify Node.js and the plugin directory look sane.
+ *   2. Ensure `dist/` exists (postinstall should have built it, but we
+ *      still check so a manual clone also works).
+ *   3. `chmod +x` the hook scripts and the bin entrypoint (defensive —
+ *      npm should handle this but tarballs sometimes lose the bits).
+ *   4. Create `.claude-crap/reports/` inside the current workspace so
+ *      the SARIF store can write without a race on its first ingestion.
+ *   5. Print the exact Claude Code command the user needs to run next.
+ *
+ * Exits 0 on success and 1 on any preparation failure.
+ *
+ * @module scripts/install
+ */
+
+import { promises as fs, constants as fsConstants } from "node:fs";
+import { resolve, join } from "node:path";
+
+import { printBanner, printStep, paint, icons } from "./lib/cli-ui.mjs";
+
+/**
+ * @typedef {Object} CommandContext
+ * @property {string}   pluginRoot Absolute path to the plugin root (this dir).
+ * @property {string[]} argv       Remaining CLI arguments after the subcommand name.
+ */
+
+/**
+ * Entrypoint invoked by `bin/claude-crap.mjs`.
+ *
+ * @param {CommandContext} ctx
+ * @returns {Promise<number>} Exit code (0 = success, 1 = failure).
+ */
+export default async function install(ctx) {
+  printBanner("claude-crap :: install");
+
+  const checks = [];
+  checks.push(await checkNodeVersion());
+  checks.push(await checkDistBuilt(ctx.pluginRoot));
+  checks.push(await chmodHooks(ctx.pluginRoot));
+  checks.push(await ensureReportsDir(process.cwd()));
+
+  for (const step of checks) printStep(step);
+
+  const hasFailure = checks.some((c) => c.status === "fail");
+  if (hasFailure) {
+    process.stdout.write(
+      `\n${paint.red(icons.fail)} Installation prerequisites failed. ` +
+        `Run ${paint.bold("claude-crap doctor")} for details.\n`,
+    );
+    return 1;
+  }
+
+  // Success — tell the user exactly what to do next. We print the
+  // Claude Code native command and also mention the marketplace path
+  // for users who cloned the repo from GitHub.
+  const pluginDir = join(ctx.pluginRoot, "plugin");
+  process.stdout.write(
+    [
+      "",
+      `${paint.green(icons.ok)} claude-crap is ready to register with Claude Code.`,
+      "",
+      `  Plugin root: ${paint.cyan(pluginDir)}`,
+      "",
+      paint.bold("  Next steps — pick ONE of the following:"),
+      "",
+      "  1. Native Claude Code install from this directory:",
+      `       ${paint.cyan(`/plugin install ${pluginDir}`)}`,
+      "",
+      "  2. Marketplace install (if the plugin is published to GitHub):",
+      `       ${paint.cyan("/plugin marketplace add ahernandez-developer/claude-crap")}`,
+      `       ${paint.cyan("/plugin install claude-crap")}`,
+      "",
+      paint.dim("  Then open a Claude Code session in this workspace. The"),
+      paint.dim("  PreToolUse gatekeeper, PostToolUse verifier, Stop quality"),
+      paint.dim("  gate, and the local Vue dashboard will all start on their"),
+      paint.dim("  own. Run `claude-crap doctor` any time to re-verify."),
+      "",
+    ].join("\n"),
+  );
+  return 0;
+}
+
+/**
+ * Verify the Node.js major version is at least 20 (matches `engines`
+ * in package.json).
+ *
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkNodeVersion() {
+  const raw = process.versions.node;
+  const major = Number(raw.split(".")[0]);
+  if (!Number.isFinite(major) || major < 20) {
+    return {
+      status: "fail",
+      label: `Node.js runtime`,
+      detail: `Found ${raw}, claude-crap requires ≥ 20.0.0. Install a newer Node.js and retry.`,
+    };
+  }
+  return { status: "ok", label: `Node.js runtime (${raw})` };
+}
+
+/**
+ * Check that the plugin bundle exists (`plugin/bundle/mcp-server.mjs`).
+ * The postinstall hook should have built it automatically; this is a
+ * safety net for users who pulled the repo without running `npm install`.
+ *
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function checkDistBuilt(pluginRoot) {
+  const entry = join(pluginRoot, "plugin", "bundle", "mcp-server.mjs");
+  try {
+    await fs.access(entry);
+    return { status: "ok", label: `MCP server bundle is built`, detail: entry };
+  } catch {
+    return {
+      status: "fail",
+      label: `MCP server bundle is NOT built`,
+      detail: `Expected ${entry}. Run \`npm run build:plugin\` from the plugin root.`,
+    };
+  }
+}
+
+/**
+ * Ensure every hook script is marked executable. npm usually handles
+ * this via the `files` field in package.json, but tarballs extracted
+ * manually or pulled over non-UNIX filesystems sometimes lose the bit.
+ *
+ * @param {string} pluginRoot
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function chmodHooks(pluginRoot) {
+  const hookDir = join(pluginRoot, "plugin", "hooks");
+  const entries = ["pre-tool-use.mjs", "post-tool-use.mjs", "stop-quality-gate.mjs", "session-start.mjs"];
+  const fixed = [];
+  for (const name of entries) {
+    const full = join(hookDir, name);
+    try {
+      await fs.access(full, fsConstants.F_OK);
+      await fs.chmod(full, 0o755);
+      fixed.push(name);
+    } catch {
+      return {
+        status: "fail",
+        label: `Hook scripts are executable`,
+        detail: `Missing ${full}`,
+      };
+    }
+  }
+  return {
+    status: "ok",
+    label: `Hook scripts are executable`,
+    detail: fixed.join(", "),
+  };
+}
+
+/**
+ * Ensure the SARIF reports directory exists inside the current
+ * workspace so the first ingestion doesn't race with a missing dir.
+ * This is a separate directory from the plugin root — it lives in the
+ * user's project, not the plugin's install location.
+ *
+ * @param {string} workspace
+ * @returns {Promise<import("./lib/cli-ui.mjs").StepResult>}
+ */
+async function ensureReportsDir(workspace) {
+  const dir = resolve(workspace, ".claude-crap", "reports");
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    return {
+      status: "ok",
+      label: `SARIF reports directory ready`,
+      detail: dir,
+    };
+  } catch (err) {
+    return {
+      status: "warn",
+      label: `Could not create reports directory`,
+      detail: `${dir} :: ${/** @type {Error} */ (err).message}`,
+    };
+  }
+}

package/scripts/lib/cli-ui.mjs

@@ -0,0 +1,122 @@
+// @ts-check
+/**
+ * Tiny CLI UI helpers shared by every `claude-crap <cmd>` subcommand.
+ *
+ * Provides ANSI color wrappers (with a `NO_COLOR` fallback), a unified
+ * `printStep` formatter for doctor-style checklists, and a handful of
+ * icon constants so the output looks consistent across subcommands.
+ *
+ * Zero runtime dependencies — uses only Node built-ins so it keeps the
+ * CLI startup fast and works in any environment the plugin supports.
+ *
+ * @module scripts/lib/cli-ui
+ */
+
+/**
+ * Check whether the current terminal supports ANSI color escapes. We
+ * follow the `NO_COLOR` env var (https://no-color.org/) and also
+ * respect the conventional `FORCE_COLOR` override for CI environments.
+ */
+const useColor = (() => {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(process.stdout.isTTY);
+})();
+
+/**
+ * Wrap a string in an ANSI color escape when color is enabled. Returns
+ * the plain string otherwise.
+ *
+ * @param {string} code Numeric ANSI color code (e.g. `"32"` for green).
+ * @param {string} text Text to wrap.
+ * @returns {string}
+ */
+function color(code, text) {
+  return useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+
+/**
+ * Color helpers. Each function takes a string and returns a potentially
+ * colored version suitable for direct `process.stdout.write()` output.
+ */
+export const paint = Object.freeze({
+  dim: (s) => color("2", s),
+  bold: (s) => color("1", s),
+  green: (s) => color("32", s),
+  yellow: (s) => color("33", s),
+  red: (s) => color("31", s),
+  cyan: (s) => color("36", s),
+  magenta: (s) => color("35", s),
+});
+
+/**
+ * Icons used by `printStep`. Kept ASCII-safe so the output renders
+ * correctly inside Claude Code's plain-text hook transcript.
+ */
+export const icons = Object.freeze({
+  ok: "✓",
+  warn: "!",
+  fail: "✗",
+  info: "•",
+  step: "▸",
+});
+
+/**
+ * Print a heading banner to stdout. Used once per subcommand to make
+ * the CLI output easy to scan.
+ *
+ * @param {string} title Short heading text (kept under ~40 chars).
+ */
+export function printBanner(title) {
+  const line = "─".repeat(Math.max(1, Math.min(title.length + 4, 76)));
+  process.stdout.write(`\n${paint.cyan(line)}\n`);
+  process.stdout.write(`  ${paint.bold(title)}\n`);
+  process.stdout.write(`${paint.cyan(line)}\n\n`);
+}
+
+/**
+ * Structured result from a diagnostic check, suitable for both
+ * rendering with `printStep` and aggregating into a summary exit code.
+ *
+ * @typedef {"ok" | "warn" | "fail" | "info"} StepStatus
+ *
+ * @typedef {Object} StepResult
+ * @property {StepStatus} status
+ * @property {string}     label
+ * @property {string}     [detail]
+ */
+
+/**
+ * Print a single checklist step.
+ *
+ * @param {StepResult} step
+ */
+export function printStep(step) {
+  const icon =
+    step.status === "ok"
+      ? paint.green(icons.ok)
+      : step.status === "warn"
+        ? paint.yellow(icons.warn)
+        : step.status === "fail"
+          ? paint.red(icons.fail)
+          : paint.dim(icons.info);
+  process.stdout.write(`  ${icon}  ${step.label}\n`);
+  if (step.detail) {
+    for (const line of step.detail.split("\n")) {
+      process.stdout.write(`       ${paint.dim(line)}\n`);
+    }
+  }
+}
+
+/**
+ * Print a key/value pair right-aligned at a fixed label width. Used
+ * by `status` to render the "resolved paths" block.
+ *
+ * @param {string} label
+ * @param {string} value
+ * @param {number} [width]
+ */
+export function printKv(label, value, width = 20) {
+  const padded = label.padEnd(width, " ");
+  process.stdout.write(`  ${paint.dim(padded)} ${value}\n`);
+}