@brainervirus/workit-claude-code 8.45.3 → 8.45.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "workit",
   "displayName": "Workit",
-  "version": "8.45.3",
+  "version": "8.45.5",
   "description": "Workflow rails for agentic coding: task context on every session, branch policy on shell commands, and the workit method skills",
   "author": {
     "name": "BrainerVirus"

package/bin/node-resolve.mjs

@@ -0,0 +1,257 @@
+// Finds a Node that can run a Workit hook when the PATH node is below the
+// package's engines floor (a repo pinned to Node 16/18/22 by a version
+// manager). Plain JavaScript with node: builtins only and no syntax newer than
+// Node 16 supports: the host launchers import it (or carry a byte-equal copy,
+// a test holds them equal) and must start on the very Node they are replacing.
+// Side-effect free: importing it runs nothing; no process is spawned here.
+//
+// Order: (1) $WORKIT_NODE; (2) the node `workit setup`/`upgrade` recorded in
+// <state dir>/node.json; (3) a scan of version-manager installs (fnm, nvm,
+// volta, mise, asdf and the Windows layouts), highest version >= the floor.
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** The Node major the hooks need; a test holds it equal to every package's engines.node. */
+export const HOOK_NODE_FLOOR = [24, 0, 0];
+
+/** Set on the re-executed child so a launcher never re-executes twice. */
+export const HOOK_NODE_REEXEC_ENV = "WORKIT_HOOK_REEXEC";
+
+const MAX_ENTRIES_PER_ROOT = 200;
+
+/** @param {unknown} text @returns {number[] | null} */
+export const parseNodeVersion = (text) => {
+  const found = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(text).trim());
+  return found ? [Number(found[1]), Number(found[2] || 0), Number(found[3] || 0)] : null;
+};
+
+/** @param {number[]} a @param {number[]} b negative when a < b */
+export const compareVersions = (a, b) => {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i];
+  return 0;
+};
+
+/** The `>=X[.Y[.Z]]` minimum of an engines.node range, or null. @param {unknown} range */
+export const floorOfRange = (range) => {
+  const min = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(range === undefined ? "" : range));
+  return min ? [Number(min[1]), Number(min[2] || 0), Number(min[3] || 0)] : null;
+};
+
+/** @param {NodeJS.ProcessEnv} env */
+export const hookStateDir = (env) => {
+  if (env.WORKFLOW_TOOLKIT_STATE) return env.WORKFLOW_TOOLKIT_STATE;
+  if (env.XDG_STATE_HOME) return path.join(env.XDG_STATE_HOME, "workit");
+  const home = env.HOME || os.homedir();
+  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");
+};
+
+/** @param {string} file */
+const isFile = (file) => {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** @param {string} file */
+const readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The version-manager directories that hold one node per child directory:
+ * `{ dir, bin }` where the node is `<dir>/<child>/<bin>`.
+ * @param {NodeJS.ProcessEnv} env @param {string} platform
+ */
+const scanRoots = (env, platform) => {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const win = platform === "win32";
+  const exe = win ? "node.exe" : "node";
+  const bin = win ? exe : path.join("bin", exe);
+  /** @type {Array<{ dir: string, bin: string }>} */
+  const roots = [];
+  const add = (dir, rel) => {
+    if (dir) roots.push({ dir, bin: rel });
+  };
+  // fnm: <dir>/node-versions/<v>/installation/bin/node
+  const fnmDirs = [
+    env.FNM_DIR,
+    win ? path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "fnm") : "",
+    win ? path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "fnm") : "",
+    env.XDG_DATA_HOME ? path.join(env.XDG_DATA_HOME, "fnm") : "",
+    path.join(home, ".local", "share", "fnm"),
+    path.join(home, "Library", "Application Support", "fnm"),
+    path.join(home, ".fnm"),
+  ];
+  for (const dir of fnmDirs)
+    if (dir) add(path.join(dir, "node-versions"), path.join("installation", bin));
+  // nvm: <dir>/versions/node/<v>/bin/node; nvm-windows: <NVM_HOME>/<v>/node.exe
+  for (const dir of [env.NVM_DIR, path.join(home, ".nvm")])
+    if (dir) add(path.join(dir, "versions", "node"), bin);
+  if (env.NVM_HOME) add(env.NVM_HOME, exe);
+  // volta: <dir>/tools/image/node/<v>/bin/node
+  const volta = env.VOLTA_HOME || (win ? "" : path.join(home, ".volta"));
+  if (volta) add(path.join(volta, "tools", "image", "node"), bin);
+  if (win)
+    add(
+      path.join(
+        env.LOCALAPPDATA || path.join(home, "AppData", "Local"),
+        "Volta",
+        "tools",
+        "image",
+        "node",
+      ),
+      bin,
+    );
+  // mise and asdf: <dir>/installs/node[js]/<v>/bin/node
+  const mise = env.MISE_DATA_DIR || path.join(home, ".local", "share", "mise");
+  add(path.join(mise, "installs", "node"), bin);
+  const asdf = env.ASDF_DATA_DIR || path.join(home, ".asdf");
+  add(path.join(asdf, "installs", "nodejs"), bin);
+  return roots;
+};
+
+/**
+ * Every installed node a version manager lists, with its version: directory
+ * listings only, at most MAX_ENTRIES_PER_ROOT per root.
+ * @param {NodeJS.ProcessEnv} env @param {string} [platform]
+ * @returns {Array<{ path: string, version: number[], source: string }>}
+ */
+export const scanInstalledNodes = (env, platform = process.platform) => {
+  /** @type {Array<{ path: string, version: number[], source: string }>} */
+  const found = [];
+  for (const root of scanRoots(env, platform)) {
+    let names;
+    try {
+      names = readdirSync(root.dir).slice(0, MAX_ENTRIES_PER_ROOT);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const version = parseNodeVersion(name);
+      if (!version || !/^v?\d/.test(name)) continue;
+      // volta's layout nests nothing; fnm's, nvm's, mise's and asdf's differ only in `bin`.
+      const candidate = path.join(root.dir, name, root.bin);
+      if (isFile(candidate)) found.push({ path: candidate, version, source: root.dir });
+    }
+  }
+  return found;
+};
+
+/**
+ * The node the hooks should run on, or null. `floor` is [major, minor, patch].
+ * @param {{ env: NodeJS.ProcessEnv, floor: number[], platform?: string }} options
+ * @returns {{ path: string, version: string | null, source: "env" | "recorded" | "scan" } | null}
+ */
+export const resolveHookNode = ({ env, floor, platform = process.platform }) => {
+  if (env.WORKIT_NODE && isFile(env.WORKIT_NODE))
+    return { path: env.WORKIT_NODE, version: null, source: "env" };
+  const recorded = readJson(path.join(hookStateDir(env), "node.json"));
+  if (recorded && typeof recorded.path === "string" && isFile(recorded.path)) {
+    const version = parseNodeVersion(recorded.version);
+    if (version && compareVersions(version, floor) >= 0)
+      return { path: recorded.path, version: String(recorded.version), source: "recorded" };
+  }
+  let best = null;
+  for (const entry of scanInstalledNodes(env, platform))
+    if (
+      compareVersions(entry.version, floor) >= 0 &&
+      (!best || compareVersions(entry.version, best.version) > 0)
+    )
+      best = entry;
+  return best ? { path: best.path, version: best.version.join("."), source: "scan" } : null;
+};
+
+/**
+ * The fail-open line for a node below the floor: null when `found` is at or
+ * above `floor`, or unparseable (an unreadable version never blocks).
+ * @param {string} found @param {number[] | null} floor @param {string} range
+ */
+export const floorMessage = (found, floor, range) => {
+  if (!floor) return null;
+  const have = parseNodeVersion(found);
+  if (!have || compareVersions(have, floor) >= 0) return null;
+  return `needs Node ${range}, found ${found}`;
+};
+
+/** What the agent is told once, at SessionStart, when no Node >= the floor resolves. */
+export const nodeFloorNotice = (found, range) =>
+  `Workit hooks are off: the Node on PATH is ${String(found).replace(/^v/, "")}, below the required ${range}, and no Node 24+ was found. ` +
+  "Install Node 24 (fnm install 24, nvm install 24) or run `workit setup` from a Node 24 shell so Workit can record it; " +
+  "`workit doctor` (check hook_node) shows what the hooks run on.";
+
+/**
+ * Where setup and upgrade record the Node they run on. A no-op for a non-node
+ * binary (bun) or a Node below the floor.
+ * @param {{ env: NodeJS.ProcessEnv, execPath: string, version: string, floor: number[] }} options
+ * @returns {string | null} the file written
+ */
+export const nodeRecord = ({ env, execPath, version, floor }) => {
+  const parsed = parseNodeVersion(version);
+  if (!parsed || compareVersions(parsed, floor) < 0) return null;
+  if (!/^node(?:\.exe)?$/i.test(path.basename(execPath))) return null;
+  return path.join(hookStateDir(env), "node.json");
+};
+
+/**
+ * Run `script args…` on `nodePath` with this process's stdin, stdout and
+ * stderr passed through. The child carries the re-exec guard and a real
+ * version (WORKIT_HOOK_NODE_VERSION, a test seam, is dropped).
+ * @returns {number | null} the child's exit code, or null when it could not start
+ */
+export const reexecOnNode = (nodePath, script, args, env) => {
+  const child = Object.assign({}, env, { [HOOK_NODE_REEXEC_ENV]: "1" });
+  delete child.WORKIT_HOOK_NODE_VERSION;
+  const run = spawnSync(nodePath, [script].concat(args), {
+    stdio: "inherit",
+    env: child,
+    windowsHide: true,
+  });
+  if (run.error) return null;
+  return run.status === null ? 1 : run.status;
+};
+
+/**
+ * What a launcher does on a Node below its floor: re-run itself on a resolved
+ * Node (the child's exit code is returned), else fail open: one stderr line,
+ * and `{}` on stdout, except that a start event answers with `notice(text)` so
+ * the agent is told the hooks are off. Resolves to the exit code.
+ * @param {{ host: string, range: string, floor: number[], found: string, script: string,
+ *   argv: string[], env: NodeJS.ProcessEnv, isStart: (event: unknown) => boolean,
+ *   notice: (text: string) => unknown }} options
+ */
+export const handleBelowFloor = async (options) => {
+  if (!options.env[HOOK_NODE_REEXEC_ENV]) {
+    const hit = resolveHookNode({ env: options.env, floor: options.floor });
+    const code = hit ? reexecOnNode(hit.path, options.script, options.argv, options.env) : null;
+    if (code !== null) return code;
+  }
+  process.stderr.write(
+    `[workit] ${options.host} hook unavailable: needs Node ${options.range}, found ${options.found}\n`,
+  );
+  let early = "";
+  for await (const chunk of process.stdin) early += String(chunk);
+  let event;
+  try {
+    event = JSON.parse(early).hook_event_name;
+  } catch {
+    event = undefined;
+  }
+  process.stdout.write(
+    options.isStart(event)
+      ? `${JSON.stringify(options.notice(nodeFloorNotice(options.found, options.range)))}\n`
+      : "{}\n",
+  );
+  return 0;
+};

package/bin/workit

@@ -4,6 +4,10 @@
 # package: run the bundled dist/workit.js with node.
 # WORKIT_CLAUDE_RUNTIME=source|dist forces one; WORKIT_SHIM_TRACE=1 prints
 # the resolved entry on stderr.
+# When the PATH node is below the floor (24), the dist runs on a Node that is:
+# $WORKIT_NODE, the node `workit setup` recorded in <state dir>/node.json, then
+# the highest fnm/nvm/volta/mise/asdf install (same order as hooks, see
+# bin/node-resolve.mjs; a test holds the floor equal).
 set -e
 here=$(dirname "$0")
 root=$(cd "$here/.." && pwd)
@@ -20,5 +24,53 @@ if [ -n "$entry" ]; then
   [ "${WORKIT_SHIM_TRACE:-}" = "1" ] && echo "workit-shim: source $entry" >&2
   exec bun "$entry" "$@"
 fi
-[ "${WORKIT_SHIM_TRACE:-}" = "1" ] && echo "workit-shim: dist $root/dist/workit.js" >&2
-exec node "$root/dist/workit.js" "$@"
+node_floor=24
+node_bin=node
+node_major=$(node -v 2>/dev/null | sed 's/^v//; s/\..*$//')
+case "$node_major" in
+  ''|*[!0-9]*) node_major=0 ;;
+esac
+if [ "$node_major" -lt "$node_floor" ]; then
+  found=""
+  if [ -n "${WORKIT_NODE:-}" ] && [ -x "$WORKIT_NODE" ]; then
+    found="$WORKIT_NODE"
+  fi
+  if [ -z "$found" ]; then
+    if [ -n "${WORKFLOW_TOOLKIT_STATE:-}" ]; then state="$WORKFLOW_TOOLKIT_STATE"
+    elif [ -n "${XDG_STATE_HOME:-}" ]; then state="$XDG_STATE_HOME/workit"
+    elif [ "$(uname -s 2>/dev/null)" = "Darwin" ]; then state="$HOME/Library/Application Support/workit"
+    else state="$HOME/.local/state/workit"; fi
+    recorded=$(sed -n 's/.*"path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$state/node.json" 2>/dev/null | head -n 1)
+    rv=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"v\{0,1\}\([0-9]*\).*/\1/p' "$state/node.json" 2>/dev/null | head -n 1)
+    if [ -n "$recorded" ] && [ -x "$recorded" ] && [ "${rv:-0}" -ge "$node_floor" ]; then
+      found="$recorded"
+    fi
+  fi
+  if [ -z "$found" ]; then
+    candidates=""
+    for spec in \
+      "${FNM_DIR:-$HOME/.local/share/fnm}/node-versions|installation/bin/node" \
+      "$HOME/Library/Application Support/fnm/node-versions|installation/bin/node" \
+      "${NVM_DIR:-$HOME/.nvm}/versions/node|bin/node" \
+      "${VOLTA_HOME:-$HOME/.volta}/tools/image/node|bin/node" \
+      "${MISE_DATA_DIR:-$HOME/.local/share/mise}/installs/node|bin/node" \
+      "${ASDF_DATA_DIR:-$HOME/.asdf}/installs/nodejs|bin/node"; do
+      base=${spec%%|*}
+      rel=${spec#*|}
+      for dir in "$base"/*; do
+        name=${dir##*/}
+        v=${name#v}
+        major=${v%%.*}
+        case "$major" in ''|*[!0-9]*) continue ;; esac
+        if [ "$major" -ge "$node_floor" ] && [ -x "$dir/$rel" ]; then
+          candidates="$candidates
+$v $dir/$rel"
+        fi
+      done
+    done
+    found=$(printf '%s\n' "$candidates" | sed '/^$/d' | sort -t. -k1,1n -k2,2n -k3,3n | tail -n 1 | sed 's/^[^ ]* //')
+  fi
+  if [ -n "$found" ]; then node_bin="$found"; fi
+fi
+[ "${WORKIT_SHIM_TRACE:-}" = "1" ] && echo "workit-shim: dist $root/dist/workit.js (node $node_bin)" >&2
+exec "$node_bin" "$root/dist/workit.js" "$@"

package/bin/workit-hook.mjs

@@ -17,6 +17,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync }
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { floorMessage, floorOfRange, handleBelowFloor } from "./node-resolve.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const source = path.join(root, "src", "run.ts");
@@ -33,32 +34,42 @@ const failOpen = (reason) => {
   process.stdout.write("{}\n");
 };
 
-// A Node below this package's own engines minimum cannot load dist: fail open
-// with one clear line instead of a syntax error. WORKIT_HOOK_NODE_VERSION
-// stands in for process.versions.node (tests). An unreadable minimum never blocks.
-const nodeFloorMessage = () => {
+// A Node below this package's own engines minimum cannot load dist. The launcher
+// then looks for a Node that can (bin/node-resolve.mjs: $WORKIT_NODE, the node
+// `workit setup` recorded, a version-manager scan) and re-runs itself on it with
+// stdin, stdout, stderr and the exit code passed through; WORKIT_HOOK_REEXEC
+// stops a second hop. With none found it fails open with one clear line, and a
+// SessionStart tells the agent once that the hooks are off.
+// WORKIT_HOOK_NODE_VERSION stands in for process.versions.node (tests). An
+// unreadable minimum never blocks.
+const nodeFloor = () => {
   try {
-    const found = process.env.WORKIT_HOOK_NODE_VERSION || process.versions.node;
     const range = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).engines?.node;
-    const min = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(range ?? ""));
-    if (!min) return null;
-    const need = [min[1], min[2] ?? 0, min[3] ?? 0].map(Number);
-    const have = String(found).replace(/^v/, "").split(".").map(Number);
-    for (let i = 0; i < 3; i++) {
-      const a = have[i] ?? 0;
-      if (Number.isNaN(a)) return null;
-      if (a !== need[i]) return a < need[i] ? `needs Node ${range}, found ${found}` : null;
-    }
-    return null;
+    const floor = floorOfRange(range);
+    return floor ? { range, floor } : null;
   } catch {
     return null;
   }
 };
-const tooOld = nodeFloorMessage();
-if (tooOld) {
-  failOpen(tooOld);
-  process.exit(0);
-}
+const hookNode = nodeFloor();
+const foundNode = process.env.WORKIT_HOOK_NODE_VERSION || process.versions.node;
+const tooOld = hookNode ? floorMessage(foundNode, hookNode.floor, hookNode.range) : null;
+if (tooOld && hookNode)
+  process.exit(
+    await handleBelowFloor({
+      host: "Claude Code",
+      range: hookNode.range,
+      floor: hookNode.floor,
+      found: foundNode,
+      script: fileURLToPath(import.meta.url),
+      argv: process.argv.slice(2),
+      env: process.env,
+      isStart: (event) => event === "SessionStart",
+      notice: (additionalContext) => ({
+        hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+      }),
+    }),
+  );
 
 // Every Bash/PowerShell call and every file edit reaches this hook (branch
 // policy, raw git/forge steering and the before-write gate). Fast paths