@workit-dev/cursor 0.0.1 → 1.0.0

package/hooks/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/hooks/workit-paths.mjs

@@ -0,0 +1,242 @@
+// The one resolver for every Workit file location (docs/agents/file-locations.md).
+// Kinds: config, state, data, cache and runtime. Linux and macOS follow the
+// XDG Base Directory spec; Windows uses %APPDATA% (config, roaming) and
+// %LOCALAPPDATA% (state, data, cache). An absolute XDG_*_HOME wins on every
+// platform; a relative one is ignored, as the spec says.
+//
+// Plain JavaScript with node: builtins only and no syntax newer than Node 16:
+// TypeScript imports it, and the hook launchers carry a byte-equal copy
+// (claude-code bin/, codex bin/, cursor hooks/; a test holds them equal). The
+// POSIX shell launchers embed the *_SH functions below verbatim, and a test
+// runs them against the JavaScript for the same environment.
+// Side-effect free on import; only migrateLegacyDirs touches the disk.
+import { existsSync, lstatSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Every location kind the resolver knows. */
+export const WORKIT_DIR_KINDS = ["config", "state", "data", "cache", "runtime"];
+
+/** Environment overrides per kind, first non-empty wins; each names the directory itself. */
+export const WORKIT_DIR_OVERRIDES = {
+  config: ["WORKIT_CONFIG", "WORKIT_CONFIG_DIR"],
+  state: ["WORKIT_STATE_DIR"],
+  data: [],
+  cache: [],
+  runtime: [],
+};
+
+/** The XDG base variable each kind follows (`<base>/workit`). */
+export const WORKIT_DIR_XDG = {
+  config: "XDG_CONFIG_HOME",
+  state: "XDG_STATE_HOME",
+  data: "XDG_DATA_HOME",
+  cache: "XDG_CACHE_HOME",
+  runtime: "XDG_RUNTIME_DIR",
+};
+
+/** The XDG defaults under $HOME when the base variable is unset. */
+const XDG_DEFAULTS = {
+  config: [".config"],
+  state: [".local", "state"],
+  data: [".local", "share"],
+  cache: [".cache"],
+};
+
+/**
+ * The user's home: $HOME, else %USERPROFILE%, else the OS record.
+ * @param {NodeJS.ProcessEnv} env
+ */
+export const userHome = (env) => env.HOME || env.USERPROFILE || os.homedir();
+
+/**
+ * The kind's XDG base when set to an absolute path (the spec ignores a relative one).
+ * @param {string} kind @param {NodeJS.ProcessEnv} env
+ */
+const xdgBase = (kind, env) => {
+  const base = env[WORKIT_DIR_XDG[kind]];
+  return base && path.isAbsolute(base) ? base : "";
+};
+
+/**
+ * Where one kind of Workit file lives.
+ * @param {"config" | "state" | "data" | "cache" | "runtime"} kind
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [platform]
+ * @returns {string}
+ */
+export const workitDir = (kind, env = process.env, platform = process.platform) => {
+  for (const name of WORKIT_DIR_OVERRIDES[kind]) if (env[name]) return String(env[name]);
+  const base = xdgBase(kind, env);
+  if (base) return path.join(base, "workit");
+  if (kind === "runtime") {
+    if (platform === "win32") return path.join(env.TEMP || env.TMP || os.tmpdir(), "workit");
+    const uid = typeof process.getuid === "function" ? process.getuid() : os.userInfo().username;
+    return path.join(env.TMPDIR || os.tmpdir(), `workit-${uid}`);
+  }
+  const home = userHome(env);
+  if (platform !== "win32") return path.join(home, ...XDG_DEFAULTS[kind], "workit");
+  if (kind === "config")
+    return path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "workit");
+  const local = path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "workit");
+  return kind === "cache" ? path.join(local, "cache") : local;
+};
+
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const configDir = (env, platform) => workitDir("config", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const stateDir = (env, platform) => workitDir("state", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const dataDir = (env, platform) => workitDir("data", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const cacheDir = (env, platform) => workitDir("cache", env, platform);
+/** @param {NodeJS.ProcessEnv} [env] @param {string} [platform] */
+export const runtimeDir = (env, platform) => workitDir("runtime", env, platform);
+
+/**
+ * Where Workit keeps the worktrees it manages: `<state>/worktrees/<repo>/<slug>`.
+ * State, not cache: a worktree holds uncommitted work.
+ * @param {NodeJS.ProcessEnv} [env] @param {string} [platform]
+ */
+export const worktreesDir = (env, platform) => path.join(stateDir(env, platform), "worktrees");
+
+/**
+ * The managed worktree root before it moved to worktreesDir:
+ * `$XDG_CACHE_HOME/workit-wt`, else `~/.cache/workit-wt` (on every platform).
+ * Never moved (a session may be using a worktree there); cleanup still sweeps it.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export const legacyWorktreesDir = (env = process.env) =>
+  path.join(xdgBase("cache", env) || path.join(userHome(env), ".cache"), "workit-wt");
+
+/**
+ * The POSIX shell form of stateDir, embedded verbatim by the shell launchers
+ * (claude-code bin/workit, the owned launcher `workit upgrade` writes).
+ */
+export const STATE_DIR_SH = `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
+}`;
+
+/** The POSIX shell form of configDir, embedded verbatim by scripts/lib/config-dir.sh. */
+export const CONFIG_DIR_SH = `workit_config_dir() {
+  if [ -n "\${WORKIT_CONFIG:-}" ]; then printf '%s\\n' "$WORKIT_CONFIG"; return; fi
+  if [ -n "\${WORKIT_CONFIG_DIR:-}" ]; then printf '%s\\n' "$WORKIT_CONFIG_DIR"; return; fi
+  case "\${XDG_CONFIG_HOME:-}" in /*) printf '%s\\n' "$XDG_CONFIG_HOME/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\\n' "\${APPDATA:-$HOME/AppData/Roaming}/workit" ;;
+    *) printf '%s\\n' "$HOME/.config/workit" ;;
+  esac
+}`;
+
+/** The POSIX shell form of dataDir, embedded verbatim by scripts/lib/config-dir.sh. */
+export const DATA_DIR_SH = `workit_data_dir() {
+  case "\${XDG_DATA_HOME:-}" in /*) printf '%s\\n' "$XDG_DATA_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/share/workit" ;;
+  esac
+}`;
+
+/**
+ * The POSIX shell form of runtimeDir, embedded verbatim by scripts/lib/config-dir.sh.
+ * `os.tmpdir()` drops a trailing slash from TMPDIR; so does this.
+ */
+export const RUNTIME_DIR_SH = `workit_runtime_dir() {
+  case "\${XDG_RUNTIME_DIR:-}" in /*) printf '%s\\n' "$XDG_RUNTIME_DIR/workit"; return ;; esac
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*) printf '%s\\n' "\${TEMP:-\${TMP:-/tmp}}/workit" ;;
+    *) set -- "\${TMPDIR:-/tmp}"; printf '%s\\n' "\${1%/}/workit-$(id -u)" ;;
+  esac
+}`;
+
+/**
+ * Locations older Workit versions used, per kind, that migrateLegacyDirs moves
+ * to the resolver's default: macOS state lived in ~/Library/Application
+ * Support/workit, Windows config in ~\.config\workit. Only while the kind has
+ * no override or XDG variable (then the default is in use).
+ * @param {NodeJS.ProcessEnv} [env] @param {string} [platform]
+ * @returns {Array<{ kind: "config" | "state", legacy: string, target: string }>}
+ */
+export const legacyDirs = (env = process.env, platform = process.platform) => {
+  const home = userHome(env);
+  /** @type {Array<{ kind: "config" | "state", legacy: string }>} */
+  const old = [];
+  if (platform === "darwin")
+    old.push({
+      kind: "state",
+      legacy: path.join(home, "Library", "Application Support", "workit"),
+    });
+  if (platform === "win32")
+    old.push({ kind: "config", legacy: path.join(home, ".config", "workit") });
+  return old
+    .filter(
+      (entry) =>
+        !WORKIT_DIR_OVERRIDES[entry.kind].some((name) => env[name]) && !xdgBase(entry.kind, env),
+    )
+    .map((entry) => ({
+      kind: entry.kind,
+      legacy: entry.legacy,
+      target: workitDir(entry.kind, env, platform),
+    }));
+};
+
+/** The marker a move leaves beside the old location: `<legacy>.moved-<stamp>`. */
+export const LEGACY_MARKER_INFIX = ".moved-";
+
+/**
+ * A real directory, never a symlink to one: a migration must not move a link
+ * the user made (the data behind it would stay where the link pointed).
+ * @param {string} file
+ */
+export const isRealDir = (file) => {
+  try {
+    return lstatSync(file).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * One-time move of each legacy location whose new location does not exist yet.
+ * Leaves `<legacy>.moved-<UTC stamp>` naming the new location; a second run
+ * finds no legacy directory and does nothing. Never throws: a failed move
+ * leaves both places as they were, and `workit doctor` (legacy_dirs) names the
+ * command that finishes it.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: string, now?: Date }} [options]
+ * @returns {Array<{ kind: string, legacy: string, target: string, marker: string }>}
+ */
+export const migrateLegacyDirs = (options = {}) => {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const stamp = (options.now || new Date())
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*$/, "Z");
+  /** @type {Array<{ kind: string, legacy: string, target: string, marker: string }>} */
+  const moved = [];
+  for (const entry of legacyDirs(env, platform)) {
+    if (!isRealDir(entry.legacy) || existsSync(entry.target)) continue;
+    const marker = `${entry.legacy}${LEGACY_MARKER_INFIX}${stamp}`;
+    try {
+      mkdirSync(path.dirname(entry.target), { recursive: true });
+      renameSync(entry.legacy, entry.target);
+    } catch {
+      continue;
+    }
+    try {
+      writeFileSync(
+        marker,
+        `Workit moved this ${entry.kind} directory to ${entry.target} at ${stamp}.\n`,
+      );
+    } catch {
+      // the move is done; a missing marker only loses the note
+    }
+    moved.push({ kind: entry.kind, legacy: entry.legacy, target: entry.target, marker });
+  }
+  return moved;
+};

package/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "workit": {
+      "command": "npx",
+      "args": ["-y", "--prefer-online", "--min-release-age=0", "--package=@workit-dev/cursor@latest", "workit-cursor-mcp", "${workspaceFolder}"]
+    }
+  }
+}

package/package.json

@@ -1,10 +1,58 @@
 {
   "name": "@workit-dev/cursor",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @workit-dev/cursor",
+  "version": "1.0.0",
+  "private": false,
+  "description": "Workit Cursor plugin — shared MCP transport, native hooks, and sixteen method skills",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "agentic-coding",
+    "ai-agents",
+    "cursor",
+    "mcp",
+    "model-context-protocol",
+    "plugin",
+    "workflow"
+  ],
+  "homepage": "https://github.com/BrainerVirus/workit#readme",
+  "bugs": {
+    "url": "https://github.com/BrainerVirus/workit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrainerVirus/workit.git",
+    "directory": "packages/workit-cursor"
+  },
+  "bin": {
+    "workit-cursor-hook": "./dist/workit-hook.js",
+    "workit-cursor-mcp": "./dist/mcp-server.js",
+    "workit-cursor-session-start": "./dist/cursor-session-start.js"
+  },
+  "files": [
+    "dist/",
+    "assets/",
+    "mcp.json",
+    ".cursor-plugin/",
+    "rules/workit-contract.mdc",
+    "skills/",
+    "commands/",
+    "hooks/hooks-cursor.json",
+    "hooks/launch.mjs",
+    "hooks/launch-runtime.mjs",
+    "hooks/node-resolve.mjs",
+    "hooks/workit-paths.mjs"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts"
+  },
+  "devDependencies": {
+    "@workit-dev/core": "^1.0.0",
+    "@workit-dev/mcp": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
 }

package/rules/workit-contract.mdc

@@ -0,0 +1,38 @@
+---
+description: Workit coordination boundaries and truthful Cursor capabilities
+alwaysApply: true
+---
+
+Workit is an optional coordinator, not a permission system. Ordinary questions,
+investigation, and reversible edits need no Workit task, assessment,
+reviewer, or close call; follow Cursor's native permissions. When a step has one
+right answer, run the `workit` CLI verb for it (`workit check`, `workit git …`,
+`workit pr …`, `workit ledger …`). Use one compact
+Workit record when handoff, dependent steps, concurrent actors, or important
+decisions make durable continuity useful. Do not duplicate a shared task per
+host or merge distinct intents because their titles look similar.
+
+Workit policy may narrow an action, but it never grants host access or overrides
+a host deny. Check the actual target checkout, configured account, branch and
+commit conventions, protected refs, and expected remote state before a delivery
+verb; merge and release need a workspace grant (`workit grant show`). Report unsupported shell coverage honestly.
+
+Cursor hooks provide evidence only where their documented input and blocking
+behavior support it. AskQuestion answers are policy-only; `sessionStart` and
+`preCompact` cannot block; `subagentStop` has no stable child identity; arbitrary
+shell writes and Tab edits are unavailable. Never invent a caller
+identity or cross-process caller channel. For native subagents in tracked
+Workit work, begin the task payload with exactly one assigned role marker:
+`[workit-role: implementer]`, `[workit-role: reviewer]`, or
+`[workit-role: investigator]`.
+
+Cursor cannot attribute subagent writes, so Workit never enforces a
+subagent's write scope here. Fanout writers (workit-fanout) are agent-guided:
+each runs in its own git worktree with a fixed brief, and its file scope is
+checked at fan-in with `git diff --name-only <base>...<branch>`, not enforced
+while it works. Verifiers and reviewers stay read-only and record
+`workit ledger verdict` under a session the lead assigns
+(`WORKIT_SESSION_ID=<lead>:verifier-<random hex>` in the brief, a fresh
+suffix per verifier: Cursor's shell carries no session id, so this declared
+child id is the verifier's session), never the
+author's.

package/skills/workit-architecture/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workit-architecture
+description: Rank cited deepening refactors from churn and ledger friction; never applied unapproved. Use for architecture.
+disable-model-invocation: true
+---
+
+# Architecture: deepen the modules that cause friction
+
+User-invoked: offer it, never start it yourself. It proposes and grills; it
+never refactors without the user's approval. Use the words in
+`references/vocabulary.md` exactly and the domain words in `GLOSSARY.md`.
+
+## Deepening
+
+1. **Scope by YAGNI.** A direction the user names wins. Otherwise find hot
+   spots: churn (`git log --since=6.months --name-only --format=`, counted per
+   file, skipping lockfiles, version-bump manifests, generated files, docs and
+   `chore(release)` commits), friction in `workit ledger list --last 200`
+   (failed checks and verdicts, rulings, `retro:` decisions) and
+   `workit test-audit <paths> --json`. State the window and paths in one line.
+2. **Settled decisions stand.** Read `GLOSSARY.md`, `CODING_STANDARDS.md` and
+   ADRs when present. Never re-litigate an ADR without new evidence.
+3. **Explore organically.** A read-only explorer (Claude Code: Explore; or
+   you) walks the hot spots under the limits in `references/vocabulary.md`
+   and returns cited friction. Run the deletion test on every suspect.
+4. **Report 3-5 ranked candidates, then stop and wait for approval.** Each:
+   - files and modules;
+   - the friction, with **2 or more cited occurrences** (commit, ledger row,
+     PR, test-audit finding); a one-off is not a candidate;
+   - an interface sketch: what callers see, what moves behind the seam;
+   - what gets simpler and what becomes testable through that interface;
+   - **merge danger**: one-way or two-way door, plus blast radius (callers,
+     packages, public surface).
+   The text list is primary; offer an HTML report only if the host renders one.
+5. **Grill the chosen one**: numbered questions, each with a recommended
+   answer; challenge a weak premise with evidence first. Settle the interface,
+   the seam, the tests to replace and the migration order; a module named for
+   a new concept gets its glossary entry (read the `workit-shape` skill's SKILL.md and follow it).
+6. **Hand off on approval.** Several slices go into a plan for
+   `workit fanout plan <plan.json>`, with scopes and dependencies
+   (read the `workit-fanout` skill's SKILL.md and follow it). One slice goes to a build (read the `workit-implement` skill's SKILL.md and follow it). Record the
+   choice with `workit ledger decision "architecture: <id>" --why "<why>"`;
+   offer an ADR for a lasting rejection so the next run does not repeat it.
+
+## Instruction files
+
+Restructure AGENTS.md or CLAUDE.md in three escalating passes, **each its own
+commit in one PR**, so the user can drop the later ones: remove no-ops;
+progressive disclosure into topic files; coding rules to `CODING_STANDARDS.md`
+and mechanical rules to checks. No commit adds a `workit knowledge lint`
+finding. Never scaffold an empty file (`references/instruction-files.md`).
+
+## Test sweep
+
+Run `workit test-audit <paths> --json` over the suite or one hot spot and
+report findings by module, worst first. On approval, the bad tests are
+replaced (read the `workit-test-audit` skill's SKILL.md and follow it).
+
+## Example
+
+Bad: "The CLI is messy, so I split router.ts in five." Uncited, unapproved.
+
+Good: "1. Check runner (check.ts, evidence.ts), 3 occurrences: commits a1b2c3
+and d4e5f6 edit both for one fix; ledger row 41 is a `check` red on a hidden
+timeout. Sketch: `runCheck(spec)` returns evidence, the timeout behind it, so
+timeouts test without a shell. Two-way door, 2 callers in one package."
+
+## Check
+
+```sh
+workit knowledge lint   # no new finding after each instruction-files commit
+```