@workit-dev/claude-code 0.0.1 → 1.0.0

package/bin/node-resolve.mjs

@@ -0,0 +1,249 @@
+// 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 (workit-paths.mjs); (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";
+import { stateDir } from "./workit-paths.mjs";
+
+/** 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;
+};
+
+/** Workit's state dir (workit-paths.mjs, the one resolver). @param {NodeJS.ProcessEnv} env */
+export const hookStateDir = (env) => stateDir(env);
+
+/** @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

@@ -0,0 +1,82 @@
+#!/bin/sh
+# `workit` on the Claude Code Bash tool's PATH (Claude adds a plugin's bin/).
+# Local pin: run the CLI from the monorepo sources with bun. Installed
+# 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
+# The state dir as core/workit-paths.mjs resolves it (STATE_DIR_SH; a test holds it verbatim).
+workit_state_dir() {
+  if [ -n "${WORKIT_STATE_DIR:-}" ]; then printf '%s\n' "$WORKIT_STATE_DIR"; return; fi
+  case "${XDG_STATE_HOME:-}" in /*) printf '%s\n' "$XDG_STATE_HOME/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\n' "${LOCALAPPDATA:-$HOME/AppData/Local}/workit" ;;
+    *) printf '%s\n' "$HOME/.local/state/workit" ;;
+  esac
+}
+here=$(dirname "$0")
+root=$(cd "$here/.." && pwd)
+main="$root/../workit-cli/src/main.ts"
+entry=""
+if [ "${WORKIT_CLAUDE_RUNTIME:-}" != "dist" ] && [ -f "$root/../workit-core/src/core.ts" ] && [ -f "$main" ]; then
+  entry="$main"
+fi
+if [ "${WORKIT_CLAUDE_RUNTIME:-}" = "source" ] && [ -z "$entry" ]; then
+  echo "workit: WORKIT_CLAUDE_RUNTIME=source but no monorepo CLI source next to $root" >&2
+  exit 1
+fi
+if [ -n "$entry" ]; then
+  [ "${WORKIT_SHIM_TRACE:-}" = "1" ] && echo "workit-shim: source $entry" >&2
+  exec bun "$entry" "$@"
+fi
+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
+    state=$(workit_state_dir)
+    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" "$@"