@brainervirus/workit-cursor 8.3.0 → 8.4.1

package/hooks/hooks-cursor.json

@@ -3,36 +3,38 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "npx -y --prefer-online --min-release-age=0 --package=@brainervirus/workit-cursor@latest workit-cursor-session-start"
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs\" workit-cursor-session-start"
       }
     ],
     "preToolUse": [
       {
-        "command": "npx -y --prefer-online --min-release-age=0 --package=@brainervirus/workit-cursor@latest workit-cursor-hook",
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs\" workit-cursor-hook",
         "matcher": "Write|Edit|Delete|Shell|Remove|ApplyPatch|Apply_Patch|Patch|Rename|Mkdir|Mv|Cp|Touch",
-        "failClosed": true
+        "failClosed": false
       }
     ],
     "beforeShellExecution": [
       {
-        "command": "npx -y --prefer-online --min-release-age=0 --package=@brainervirus/workit-cursor@latest workit-cursor-hook",
-        "failClosed": true
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs\" workit-cursor-hook",
+        "failClosed": false
       }
     ],
     "subagentStart": [
       {
-        "command": "npx -y --prefer-online --min-release-age=0 --package=@brainervirus/workit-cursor@latest workit-cursor-hook",
-        "failClosed": true
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs\" workit-cursor-hook",
+        "failClosed": false
       }
     ],
     "subagentStop": [
       {
-        "command": "npx -y --prefer-online --min-release-age=0 --package=@brainervirus/workit-cursor@latest workit-cursor-hook"
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs\" workit-cursor-hook",
+        "failClosed": false
       }
     ],
     "preCompact": [
       {
-        "command": "npx -y --prefer-online --min-release-age=0 --package=@brainervirus/workit-cursor@latest workit-cursor-hook"
+        "command": "node \"${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs\" workit-cursor-hook",
+        "failClosed": false
       }
     ]
   }

package/hooks/launch-runtime.mjs

@@ -0,0 +1,248 @@
+// Cursor hook launch resolution and fail-open runner, shared by the launcher
+// (launch.mjs, including its `--probe` mode for `workit doctor`). Side-effect
+// free: importing it runs nothing.
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CURSOR_HOOK_PACKAGE = "@brainervirus/workit-cursor";
+
+/** npm bin name -> bundled entry under dist/. */
+const CURSOR_HOOK_BINS = {
+  "workit-cursor-hook": "workit-hook.js",
+  "workit-cursor-session-start": "cursor-session-start.js",
+};
+
+const LOCAL_TIMEOUT_MS = 20_000;
+const NPX_TIMEOUT_MS = 30_000;
+// A deny can carry a long agent message; spawnSync's 1 MiB default would turn
+// an oversized answer into a launcher failure (and fail open).
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+/** @param {string} root */
+const pluginVersion = (root) => {
+  try {
+    const version = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).version;
+    return typeof version === "string" && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)
+      ? version
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The workit-cursor version a global bin belongs to (its package.json), if any.
+ *  @param {string} bin */
+const globalBinVersion = (bin) => {
+  try {
+    for (let dir = path.dirname(realpathSync(bin)); ; dir = path.dirname(dir)) {
+      const pkg = path.join(dir, "package.json");
+      if (existsSync(pkg)) {
+        const parsed = JSON.parse(readFileSync(pkg, "utf8"));
+        return parsed.name === CURSOR_HOOK_PACKAGE ? pluginVersion(dir) : null;
+      }
+      if (path.dirname(dir) === dir) return null;
+    }
+  } catch {
+    return null;
+  }
+};
+
+/** @param {string} name @param {NodeJS.ProcessEnv} env */
+const onPath = (name, env) => {
+  const names = process.platform === "win32" ? [`${name}.cmd`, `${name}.exe`, name] : [name];
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    // Relative entries (`.`, `node_modules/.bin`) resolve against the
+    // workspace Cursor runs the hook in: never trust them.
+    if (!dir || !path.isAbsolute(dir)) continue;
+    for (const candidate of names.map((n) => path.join(dir, n))) {
+      try {
+        const st = statSync(candidate);
+        if (st.isFile() && (process.platform === "win32" || (st.mode & 0o111) !== 0))
+          return candidate;
+      } catch {
+        /* keep scanning */
+      }
+    }
+  }
+  return null;
+};
+
+/**
+ * @typedef {{ mode: "local" | "npx-pinned", source: string, version: string | null,
+ *   command: string, args: string[], verbatim?: boolean, timeoutMs: number }} LaunchCandidate
+ */
+
+// cmd.exe metacharacters, escaped with `^` (ported from workit-core's
+// checks.ts, which this plain-JS launcher cannot import).
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+
+/** One argument for a `cmd /d /s /c "…"` line; `double` for node_modules/.bin
+ *  shims, which re-parse their arguments.
+ *  @param {string} arg @param {boolean} double */
+const cmdArgument = (arg, double) => {
+  let out = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  out = `"${out}"`.replace(CMD_META, "^$1");
+  return double ? out.replace(CMD_META, "^$1") : out;
+};
+
+/**
+ * How to spawn `file args…`. Node cannot spawn a Windows `.cmd`/`.bat` shim
+ * directly, so it runs as `cmd.exe /d /s /c "<line>"` with every metacharacter
+ * escaped and the line passed verbatim: a path such as `C:\A&B\x.cmd` must
+ * never split into a second command.
+ * @param {string} file @param {string[]} args @param {NodeJS.ProcessEnv} env
+ * @returns {{ command: string, args: string[], verbatim: boolean }}
+ */
+export const cursorSpawnPlan = (file, args, env) => {
+  if (!/\.(?:cmd|bat)$/i.test(file)) return { command: file, args, verbatim: false };
+  const double = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i.test(file);
+  const line = [
+    path.win32.normalize(file).replace(CMD_META, "^$1"),
+    ...args.map((arg) => cmdArgument(arg, double)),
+  ].join(" ");
+  return {
+    command: env.ComSpec ?? env.COMSPEC ?? "cmd.exe",
+    args: ["/d", "/s", "/c", `"${line}"`],
+    verbatim: true,
+  };
+};
+
+/**
+ * Ordered launch candidates for `bin`; an empty list means "missing".
+ * @param {{ root: string, bin: string, env: NodeJS.ProcessEnv, node?: string }} options
+ * @returns {LaunchCandidate[]}
+ */
+export const resolveCursorHookLaunch = ({ root, bin, env, node = process.execPath }) => {
+  /** @type {LaunchCandidate[]} */
+  const candidates = [];
+  const entry = Object.hasOwn(CURSOR_HOOK_BINS, bin)
+    ? CURSOR_HOOK_BINS[/** @type {keyof typeof CURSOR_HOOK_BINS} */ (bin)]
+    : null;
+  if (!entry) return candidates;
+  const version = pluginVersion(root);
+  const bundled = path.join(root, "dist", entry);
+  if (existsSync(bundled))
+    candidates.push({
+      mode: "local",
+      source: bundled,
+      version,
+      command: node,
+      args: [bundled],
+      timeoutMs: LOCAL_TIMEOUT_MS,
+    });
+  const global = onPath(bin, env);
+  if (global)
+    candidates.push({
+      mode: "local",
+      source: global,
+      version: globalBinVersion(global),
+      ...cursorSpawnPlan(global, [], env),
+      timeoutMs: LOCAL_TIMEOUT_MS,
+    });
+  const npx = onPath("npx", env);
+  if (version && npx)
+    candidates.push({
+      mode: "npx-pinned",
+      source: `${CURSOR_HOOK_PACKAGE}@${version}`,
+      version,
+      // WORKIT_CURSOR_HOOK_NPX_OFFLINE=1 (the doctor's probe) never downloads.
+      ...cursorSpawnPlan(
+        npx,
+        [
+          "-y",
+          env.WORKIT_CURSOR_HOOK_NPX_OFFLINE === "1" ? "--offline" : "--prefer-offline",
+          `--package=${CURSOR_HOOK_PACKAGE}@${version}`,
+          bin,
+        ],
+        env,
+      ),
+      timeoutMs: NPX_TIMEOUT_MS,
+    });
+  return candidates;
+};
+
+/**
+ * Run the first launchable candidate with `payload` on stdin.
+ * @param {{ candidates: LaunchCandidate[], payload: string, env: NodeJS.ProcessEnv,
+ *   spawn?: typeof spawnSync }} options
+ * @returns {{ stdout: string, exitCode: number, warning: string | null }}
+ */
+export const runCursorHookLaunch = ({ candidates, payload, env, spawn = spawnSync }) => {
+  const failOpen = (/** @type {string} */ reason) => ({
+    stdout: "{}\n",
+    exitCode: 0,
+    warning: `[workit] Cursor hook unavailable: ${reason}`,
+  });
+  if (candidates.length === 0)
+    return failOpen("no local workit-cursor runtime and no npx to fetch the pinned one");
+  const timeoutMs = Number(env.WORKIT_CURSOR_HOOK_TIMEOUT_MS) || null;
+  const errors = [];
+  for (const candidate of candidates) {
+    const run = spawn(candidate.command, candidate.args, {
+      input: payload,
+      encoding: "utf8",
+      env,
+      stdio: ["pipe", "pipe", "inherit"],
+      timeout: timeoutMs ?? candidate.timeoutMs,
+      maxBuffer: MAX_OUTPUT_BYTES,
+      windowsHide: true,
+      windowsVerbatimArguments: candidate.verbatim === true,
+    });
+    const code = /** @type {{ code?: string } | undefined} */ (run.error)?.code;
+    // The process never started: try the next candidate on the same payload.
+    if (run.error && (code === "ENOENT" || code === "EACCES")) {
+      errors.push(`${candidate.source}: ${run.error.message}`);
+      continue;
+    }
+    // EPIPE only means the hook exited without reading all of stdin; its exit
+    // status still stands.
+    if (run.error && !(code === "EPIPE" && typeof run.status === "number"))
+      return failOpen(`${candidate.source}: ${run.error.message}`);
+    // 0 = the hook's answer; 2 = the hook's own policy deny (Cursor's channel).
+    if (run.status === 0 || run.status === 2)
+      return { stdout: String(run.stdout ?? ""), exitCode: run.status, warning: null };
+    return failOpen(`${candidate.source} exited ${run.status ?? `on ${run.signal ?? "a signal"}`}`);
+  }
+  return failOpen(errors.join("; "));
+};
+
+/** Workit's state dir, as core's resolveStateDir computes it.
+ *  @param {NodeJS.ProcessEnv} env */
+export const workitStateDir = (env) => {
+  if (env.WORKFLOW_TOOLKIT_STATE) return env.WORKFLOW_TOOLKIT_STATE;
+  const home = env.HOME || os.homedir();
+  if (env.XDG_STATE_HOME) return path.join(env.XDG_STATE_HOME, "workit");
+  if (process.platform === "darwin")
+    return path.join(home, "Library", "Application Support", "workit");
+  if (process.platform === "win32")
+    return path.join(env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "workit");
+  return path.join(home, ".local", "state", "workit");
+};
+
+/** File the launcher touches on every run, so `workit doctor` can tell when
+ *  Cursor started sessions but never ran a Workit hook. */
+export const CURSOR_HOOK_HEARTBEAT = "cursor-hook-last-run";
+
+/** Best-effort heartbeat; a read-only state dir never blocks a hook.
+ *  @param {NodeJS.ProcessEnv} env @param {string} bin */
+export const touchCursorHookHeartbeat = (env, bin) => {
+  try {
+    const dir = workitStateDir(env);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      path.join(dir, CURSOR_HOOK_HEARTBEAT),
+      `${JSON.stringify({ at: new Date().toISOString(), bin })}\n`,
+    );
+  } catch {
+    /* heartbeat is diagnostic only */
+  }
+};

package/hooks/launch.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// Cursor hook launcher. hooks-cursor.json runs
+// `node "${CURSOR_PLUGIN_ROOT}/hooks/launch.mjs" <bin>` for every event. This
+// file is committed plain JavaScript, so it runs from a Marketplace git checkout
+// (no build, no dependencies) as well as from an installed plugin copy.
+//
+// Resolution order (first match wins; no step ever resolves `@latest`):
+//   1. local: the plugin's own bundled hook, <plugin>/dist/<entry>.js;
+//   2. local: `<bin>` on PATH (a global `@brainervirus/workit-cursor` install);
+//   3. npx-pinned: `npx -y --prefer-offline --package=<pkg>@<plugin version>`,
+//      the version read from this plugin's package.json;
+//   4. missing: nothing runnable.
+//
+// Fail-open: a launcher or infrastructure failure (nothing to run, spawn
+// failure, npx network error, timeout, a crash) prints `{}`, exits 0 and
+// writes one `[workit] Cursor hook unavailable: …` line on stderr. Only a
+// policy deny from the hook itself (exit 2 with Cursor's deny JSON) blocks.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  resolveCursorHookLaunch,
+  runCursorHookLaunch,
+  touchCursorHookHeartbeat,
+} from "./launch-runtime.mjs";
+
+const pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// `--probe <bin>` (for `workit doctor`): run one no-op preCompact through
+// the candidate Cursor would use and print which one it was and how it went.
+if (process.argv[2] === "--probe") {
+  const candidates = resolveCursorHookLaunch({
+    root: pluginRoot,
+    bin: process.argv[3] ?? "",
+    env: process.env,
+  });
+  const run = runCursorHookLaunch({
+    candidates: candidates.slice(0, 1),
+    payload: JSON.stringify({ hook_event_name: "preCompact", workspace_roots: [] }),
+    env: process.env,
+  });
+  const first = candidates[0];
+  process.stdout.write(
+    `${JSON.stringify({ mode: first?.mode ?? "missing", source: first?.source ?? null, version: first?.version ?? null, error: run.warning })}\n`,
+  );
+  process.exit(0);
+}
+
+const bin = process.argv[2] ?? "";
+touchCursorHookHeartbeat(process.env, bin);
+let payload = "";
+for await (const chunk of process.stdin) payload += String(chunk);
+let result;
+try {
+  result = runCursorHookLaunch({
+    candidates: resolveCursorHookLaunch({ root: pluginRoot, bin, env: process.env }),
+    payload,
+    env: process.env,
+  });
+} catch (error) {
+  result = {
+    stdout: "{}\n",
+    exitCode: 0,
+    warning: `[workit] Cursor hook unavailable: ${error instanceof Error ? error.message : String(error)}`,
+  };
+}
+if (result.warning) process.stderr.write(`${result.warning}\n`);
+process.stdout.write(result.stdout);
+process.exitCode = result.exitCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-cursor",
-  "version": "8.3.0",
+  "version": "8.4.1",
   "private": false,
   "description": "Workit Cursor plugin — shared MCP transport, native hooks, and sixteen method skills",
   "keywords": [
@@ -34,7 +34,9 @@
     "rules/workit-contract.mdc",
     "skills/",
     "commands/",
-    "hooks/hooks-cursor.json"
+    "hooks/hooks-cursor.json",
+    "hooks/launch.mjs",
+    "hooks/launch-runtime.mjs"
   ],
   "type": "module",
   "publishConfig": {
@@ -44,8 +46,8 @@
     "build": "bun scripts/build.ts"
   },
   "dependencies": {
-    "@brainervirus/workit-core": "^8.3.0",
-    "@brainervirus/workit-mcp": "^8.3.0"
+    "@brainervirus/workit-core": "^8.4.1",
+    "@brainervirus/workit-mcp": "^8.4.1"
   },
   "engines": {
     "node": ">=24"

package/skills/workit-implement/SKILL.md

@@ -11,9 +11,9 @@ description: Build a requested change in small verified steps - follow local pat
    neighbour that already does something similar. Copy its patterns, names and
    error handling. Repo rules (AGENTS.md, CLAUDE.md, lint config) win.
 2. On the default branch? Branch first: `workit git branch --kind feature --slug <s>`.
-   Tracking it? Judge once: `workit policy assess --judge risk=normal
-   behavior=yes product-choice=no plan=no` (trivial and no for a mechanical
-   fix); Workit derives what close needs.
+   Tracking it? Judge once: `workit policy assess --judge risk=normal behavior=yes
+   product-choice=no plan=no` (trivial and no for a mechanical fix). Already
+   judged? Cite the plan with `--ref <path>` or record the decision; don't re-judge.
 3. Small steps that each leave the tree green. Behavior change: write the
    acceptance as Given/When/Then and see a test fail first (read the `workit-bdd` skill's SKILL.md and follow it).
    Mechanical change: the existing checks are enough. No tautological tests: