@workit-dev/core 0.0.1 → 1.0.0

package/src/core/heavy-rules.ts

@@ -0,0 +1,373 @@
+// Host permission rules the heavy-command gate must not override (#325,
+// ruling mvid5onk). A heavy command is wrapped through the lease only when no
+// readable deny/ask rule names it and wrapping does not raise its permission
+// (an allow that covers `workit` but not the command itself). The matcher is
+// conservative: anything it cannot read for sure counts as naming the
+// command, so the gate steps aside and the host decides.
+//
+// Sources, per host:
+//   - Claude Code: managed-settings.json, the user settings
+//     ($CLAUDE_CONFIG_DIR or ~/.claude), <project>/.claude/settings.json and
+//     settings.local.json: permissions.deny/ask/allow `Bash(...)` and `Bash`;
+//   - OpenCode: ~/.config/opencode/opencode.json(c), opencode.json(c) and
+//     .opencode/opencode.json(c) up to the git top, OPENCODE_CONFIG,
+//     OPENCODE_CONFIG_CONTENT: permission.bash / permission.shell and every
+//     agent.*.permission;
+//   - Codex: ~/.codex/rules/*.rules and <project>/.codex/rules/*.rules
+//     (`prefix_rule(pattern=[…], decision=…)`);
+//   - Cursor: ~/.cursor/cli-config.json and <project>/.cursor/cli.json,
+//     permissions.deny/allow `Shell(x)`.
+// Hook-safe: node built-ins only.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** One rule: its pattern (`npx jest:*`, `*`, `` for a bare tool rule). */
+export type Rules = { deny: string[]; allow: string[] };
+/** Rules read from the host, or `unreadable` when any source could not be read for sure. */
+export type RuleRead = Rules | "unreadable";
+
+const EMPTY = (): Rules => ({ deny: [], allow: [] });
+
+const readText = (file: string): string | null => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** JSON with `//` and `/* *\/` comments and trailing commas (opencode.jsonc). */
+export function parseJsonc(text: string): unknown {
+  let out = "";
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '"') {
+      const end = /"(?:[^"\\]|\\.)*"/y;
+      end.lastIndex = index;
+      const match = end.exec(text);
+      if (!match) throw new Error("unterminated string");
+      out += match[0];
+      index += match[0].length - 1;
+    } else if (char === "/" && text[index + 1] === "/") {
+      while (index < text.length && text[index] !== "\n") index += 1;
+      out += "\n";
+    } else if (char === "/" && text[index + 1] === "*") {
+      const close = text.indexOf("*/", index + 2);
+      if (close < 0) throw new Error("unterminated comment");
+      index = close + 1;
+    } else out += char;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/gu, "$1"));
+}
+
+/** The git top of `cwd` (the nearest directory with `.git`), or null. */
+export function gitTop(cwd: string): string | null {
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, ".git"))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+/** `cwd` and its parents up to the git top (or just `cwd` outside git). */
+const projectDirs = (cwd: string): string[] => {
+  const top = gitTop(cwd);
+  const dirs: string[] = [];
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    dirs.push(dir);
+    if (!top || dir === top || path.dirname(dir) === dir) return dirs;
+  }
+};
+
+const homeOf = (env: NodeJS.ProcessEnv) => env.HOME || os.homedir();
+
+// --- Claude Code -----------------------------------------------------------
+
+const CLAUDE_MANAGED: Partial<Record<NodeJS.Platform, string>> = {
+  linux: "/etc/claude-code/managed-settings.json",
+  darwin: "/Library/Application Support/ClaudeCode/managed-settings.json",
+  win32: "C:\\Program Files\\ClaudeCode\\managed-settings.json",
+};
+
+/** The Claude Code settings files the gate reads, most authoritative first. */
+export function claudeSettingsFiles(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  const project = env.CLAUDE_PROJECT_DIR || gitTop(cwd) || cwd;
+  const user = env.CLAUDE_CONFIG_DIR || path.join(homeOf(env), ".claude");
+  return [
+    ...(CLAUDE_MANAGED[platform] ? [CLAUDE_MANAGED[platform]] : []),
+    path.join(user, "settings.json"),
+    path.join(project, ".claude", "settings.json"),
+    path.join(project, ".claude", "settings.local.json"),
+  ];
+}
+
+/** `Bash(x)` → `x`, `Bash` → ``, any other tool → null. */
+const bashPattern = (entry: string): string | null => {
+  const match = /^Bash(?:\((.*)\))?$/su.exec(entry.trim());
+  return match ? (match[1] ?? "") : null;
+};
+
+export function claudeRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    for (const file of claudeSettingsFiles(cwd, env)) {
+      const text = readText(file);
+      if (text === null) continue;
+      const value: unknown = JSON.parse(text);
+      if (!isRecord(value)) return "unreadable";
+      const permissions = value.permissions;
+      if (permissions === undefined) continue;
+      if (!isRecord(permissions)) return "unreadable";
+      for (const [key, bucket] of [
+        ["deny", rules.deny],
+        ["ask", rules.deny],
+        ["allow", rules.allow],
+      ] as const) {
+        const list = permissions[key];
+        if (list === undefined) continue;
+        if (!Array.isArray(list)) return "unreadable";
+        for (const entry of list) {
+          if (typeof entry !== "string") return "unreadable";
+          const pattern = bashPattern(entry);
+          if (pattern !== null) bucket.push(pattern);
+        }
+      }
+    }
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- OpenCode ---------------------------------------------------------------
+
+const OPENCODE_NAMES = ["opencode.json", "opencode.jsonc"];
+
+/** A `permission` block's bash/shell rules into `rules`; false when it cannot be read. */
+const opencodePermission = (permission: unknown, rules: Rules): boolean => {
+  if (permission === undefined) return true;
+  if (typeof permission === "string") {
+    // A blanket permission covers every tool, the shell included.
+    (permission === "allow" ? rules.allow : rules.deny).push("");
+    return ["allow", "ask", "deny"].includes(permission);
+  }
+  if (!isRecord(permission)) return false;
+  for (const key of ["bash", "shell"]) {
+    const value = permission[key];
+    if (value === undefined) continue;
+    if (typeof value === "string") {
+      if (!["allow", "ask", "deny"].includes(value)) return false;
+      (value === "allow" ? rules.allow : rules.deny).push("");
+      continue;
+    }
+    if (!isRecord(value)) return false;
+    for (const [pattern, action] of Object.entries(value)) {
+      if (action !== "allow" && action !== "ask" && action !== "deny") return false;
+      (action === "allow" ? rules.allow : rules.deny).push(pattern);
+    }
+  }
+  return true;
+};
+
+const opencodeConfig = (value: unknown, rules: Rules): boolean => {
+  if (!isRecord(value)) return false;
+  if (!opencodePermission(value.permission, rules)) return false;
+  if (value.agent === undefined) return true;
+  if (!isRecord(value.agent)) return false;
+  return Object.values(value.agent).every(
+    (agent) => isRecord(agent) && opencodePermission(agent.permission, rules),
+  );
+};
+
+export function opencodeRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    const config = env.XDG_CONFIG_HOME || path.join(homeOf(env), ".config");
+    const files = [
+      ...OPENCODE_NAMES.map((name) => path.join(config, "opencode", name)),
+      ...projectDirs(cwd).flatMap((dir) =>
+        OPENCODE_NAMES.flatMap((name) => [path.join(dir, name), path.join(dir, ".opencode", name)]),
+      ),
+      ...(env.OPENCODE_CONFIG ? [env.OPENCODE_CONFIG] : []),
+    ];
+    for (const file of files) {
+      const text = readText(file);
+      if (text !== null && !opencodeConfig(parseJsonc(text), rules)) return "unreadable";
+    }
+    if (
+      env.OPENCODE_CONFIG_CONTENT &&
+      !opencodeConfig(parseJsonc(env.OPENCODE_CONFIG_CONTENT), rules)
+    )
+      return "unreadable";
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- Codex ------------------------------------------------------------------
+
+/**
+ * `prefix_rule(pattern=["npx", "jest"], decision="forbidden")` → its rule
+ * (the words joined), or null when in doubt: no pattern list, a nested
+ * alternatives list, a non-string word, or no known decision.
+ */
+const codexRule = (body: string): { pattern: string; decision: string } | null => {
+  const open = /\bpattern\s*=\s*\[/u.exec(body);
+  if (!open) return null;
+  const words: string[] = [];
+  let index = open.index + open[0].length;
+  for (;;) {
+    while (/[\s,]/u.test(body[index] ?? "")) index += 1;
+    if (body[index] === "]") break;
+    if (body[index] !== '"') return null;
+    const literal = /"((?:[^"\\]|\\.)*)"/y;
+    literal.lastIndex = index;
+    const match = literal.exec(body);
+    if (!match) return null;
+    words.push(JSON.parse(`"${match[1]}"`) as string);
+    index = literal.lastIndex;
+  }
+  const decision = /\bdecision\s*=\s*"(\w+)"/u.exec(body)?.[1];
+  if (!words.length || !decision || !["allow", "prompt", "forbidden"].includes(decision))
+    return null;
+  return { pattern: words.join(" "), decision };
+};
+
+export function codexRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    const home = env.CODEX_HOME || path.join(homeOf(env), ".codex");
+    const top = gitTop(cwd) ?? cwd;
+    for (const dir of [path.join(home, "rules"), path.join(top, ".codex", "rules")]) {
+      let files: string[];
+      try {
+        files = fs.readdirSync(dir).filter((name) => name.endsWith(".rules"));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+        return "unreadable";
+      }
+      for (const name of files) {
+        const text = readText(path.join(dir, name)) ?? "";
+        for (const part of text.split(/\bprefix_rule\s*\(/u).slice(1)) {
+          const rule = codexRule(part);
+          if (!rule) return "unreadable";
+          (rule.decision === "allow" ? rules.allow : rules.deny).push(rule.pattern);
+        }
+      }
+    }
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- Cursor -----------------------------------------------------------------
+
+export function cursorRules(cwd: string, env: NodeJS.ProcessEnv = process.env): RuleRead {
+  const rules = EMPTY();
+  try {
+    const top = gitTop(cwd) ?? cwd;
+    for (const file of [
+      path.join(homeOf(env), ".cursor", "cli-config.json"),
+      path.join(top, ".cursor", "cli.json"),
+    ]) {
+      const text = readText(file);
+      if (text === null) continue;
+      const value: unknown = JSON.parse(text);
+      if (!isRecord(value)) return "unreadable";
+      if (value.permissions === undefined) continue;
+      if (!isRecord(value.permissions)) return "unreadable";
+      for (const [key, bucket] of [
+        ["deny", rules.deny],
+        ["allow", rules.allow],
+      ] as const) {
+        const list = value.permissions[key];
+        if (list === undefined) continue;
+        if (!Array.isArray(list)) return "unreadable";
+        for (const entry of list) {
+          if (typeof entry !== "string") return "unreadable";
+          const match = /^Shell(?:\((.*)\))?$/su.exec(entry.trim());
+          if (match) bucket.push(match[1] ?? "");
+        }
+      }
+    }
+  } catch {
+    return "unreadable";
+  }
+  return rules;
+}
+
+// --- the matcher --------------------------------------------------------------
+
+const baseName = (word: string): string =>
+  (word.split(/[\\/]/u).at(-1) ?? "").toLowerCase().replace(/\.(?:exe|cmd|bat)$/u, "");
+
+/** A pattern's first token: cut at `:` or a space. */
+const firstToken = (pattern: string): string => pattern.trim().split(/[:\s]/u)[0] ?? "";
+
+/** Does a deny/ask `pattern` name a command with these words? */
+export function names(pattern: string, words: readonly string[]): boolean {
+  const token = firstToken(pattern);
+  if (!token || token === "*" || token.includes("*")) return true;
+  const wanted = baseName(token);
+  return words.some((word) => baseName(word) === wanted);
+}
+
+/** A pattern's literal prefix, without a trailing `:*`, ` *` or `*`. */
+const literalPrefix = (pattern: string): string => pattern.trim().replace(/(?::\*| \*|\*)$/u, "");
+
+/**
+ * Could an allow `pattern` cover the wrapper (`workit check --heavy -- …`)?
+ * A bare rule, a first word with a glob, or a literal prefix of the wrapper
+ * (`workit`, `workit check`). `workit git push:*` cannot match it.
+ */
+const coversWrapper = (pattern: string): boolean => {
+  const token = firstToken(pattern);
+  if (!token || token.includes("*")) return true;
+  const words = literalPrefix(pattern).split(/\s+/u);
+  if (baseName(words[0]) !== "workit") return false;
+  return ["check", "--heavy"].slice(0, words.length - 1).every((word, at) => {
+    const given = words[at + 1];
+    return given === word || word.startsWith(given);
+  });
+};
+
+/** Does an allow `pattern` cover `command` by a literal prefix? */
+const coversCommand = (pattern: string, command: string): boolean => {
+  const prefix = literalPrefix(pattern);
+  if (!prefix) return true;
+  return !prefix.includes("*") && command.trim().startsWith(prefix);
+};
+
+export type RuleVerdict = { ok: true } | { ok: false; why: "named" | "allowlisted" };
+
+/**
+ * May the gate wrap a heavy command? Not when a deny/ask rule names a word
+ * of it (`words`), and not when an allow covers `workit` but not `command`
+ * (wrapping would raise its permission; skipped with `bypass`).
+ */
+export function wrapAllowed(
+  read: RuleRead,
+  words: readonly string[],
+  command: string,
+  options: { bypass?: boolean } = {},
+): RuleVerdict {
+  if (read === "unreadable") return { ok: false, why: "named" };
+  if (read.deny.some((pattern) => names(pattern, words))) return { ok: false, why: "named" };
+  if (
+    !options.bypass &&
+    read.allow.some(coversWrapper) &&
+    !read.allow.some((pattern) => coversCommand(pattern, command))
+  )
+    return { ok: false, why: "allowlisted" };
+  return { ok: true };
+}

package/src/core/heavy-scope.ts

@@ -0,0 +1,131 @@
+// The systemd user scope a heavy check runs in (issue #282), and the probe
+// `workit doctor` uses to say whether its limits really apply (#325). Node
+// built-ins only, so the doctor and the install-time doctor load it without
+// the check runner or the hook graph.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const readText = (file: string): string | null => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+export type ScopeSupport = { ok: true } | { ok: false; reason: string };
+
+const onPath = (command: string, env: NodeJS.ProcessEnv): boolean =>
+  (env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .some((dir) => {
+      try {
+        fs.accessSync(path.join(dir, command), fs.constants.X_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+
+/**
+ * Can heavy checks run in their own `systemd-run --user --scope`? Needs Linux,
+ * `systemd-run` on PATH, a running user manager, and the memory and cpu
+ * controllers delegated to it (cgroup v2).
+ */
+export function scopeSupport(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+  read: (file: string) => string | null = readText,
+): ScopeSupport {
+  if (platform !== "linux") return { ok: false, reason: `no systemd scopes on ${platform}` };
+  if (!onPath("systemd-run", env)) return { ok: false, reason: "systemd-run is not on PATH" };
+  const uid = process.getuid?.() ?? 0;
+  const runtime = env.XDG_RUNTIME_DIR || `/run/user/${uid}`;
+  if (!fs.existsSync(path.join(runtime, "systemd", "private")))
+    return { ok: false, reason: "no user systemd manager is running" };
+  const controllers = read(
+    `/sys/fs/cgroup/user.slice/user-${uid}.slice/user@${uid}.service/cgroup.controllers`,
+  );
+  if (controllers === null)
+    return { ok: false, reason: "cgroup v2 is not mounted for the user manager" };
+  const missing = ["memory", "cpu"].filter((name) => !controllers.split(/\s+/u).includes(name));
+  if (missing.length)
+    return { ok: false, reason: `the user manager is not delegated ${missing.join(" and ")}` };
+  return { ok: true };
+}
+
+/** The `systemd-run` prefix that runs a command in its own limited scope. */
+export function scopePrefix(unit: string, settings: { memoryMax: string; cpuQuota: string }) {
+  return [
+    "systemd-run",
+    "--user",
+    "--scope",
+    "--quiet",
+    "--collect",
+    `--unit=${unit}`,
+    "-p",
+    `MemoryMax=${settings.memoryMax}`,
+    "-p",
+    `CPUQuota=${settings.cpuQuota}`,
+    "--",
+  ];
+}
+
+export type ScopeProbe =
+  | { effective: true; memoryMax: string; cpuMax: string; delegate: string | null }
+  | { effective: false; supported: boolean; reason: string; delegate: string | null };
+
+const PROBE_MEMORY = "268435456";
+const PROBE_CPU = "50%";
+const PROBE_SCRIPT =
+  'cg=$(sed -n "s/^0:://p" /proc/self/cgroup); cat "/sys/fs/cgroup$cg/memory.max" "/sys/fs/cgroup$cg/cpu.max"';
+
+/** `Delegate=` and `DelegateControllers=` of the user manager's unit, as systemd reports them. */
+function userManagerDelegate(env: NodeJS.ProcessEnv): string | null {
+  const uid = process.getuid?.() ?? 0;
+  const shown = spawnSync(
+    "systemctl",
+    ["show", `user@${uid}.service`, "-p", "Delegate", "-p", "DelegateControllers"],
+    { env, encoding: "utf8", timeout: 5000 },
+  );
+  const text = shown.status === 0 ? shown.stdout.trim().split(/\n/u).join(", ") : "";
+  return text || null;
+}
+
+/**
+ * Do heavy-check scopes really get their limits here? Starts a throwaway
+ * scope the way a heavy check does (MemoryMax 256 MiB, CPUQuota 50%) and
+ * reads the limits back from its own cgroup, so a manager that accepts the
+ * properties but cannot apply them (no delegation) is told apart.
+ */
+export function probeScope(env: NodeJS.ProcessEnv = process.env): ScopeProbe {
+  const support = scopeSupport(env);
+  const delegate = process.platform === "linux" ? userManagerDelegate(env) : null;
+  if (!support.ok) return { effective: false, supported: false, reason: support.reason, delegate };
+  const unit = `workit-probe-${process.pid}-${Date.now().toString(36)}`;
+  // The same `systemd-run …` prefix a heavy check runs under.
+  const [runner, ...prefix] = scopePrefix(unit, { memoryMax: PROBE_MEMORY, cpuQuota: PROBE_CPU });
+  const probe = spawnSync(runner, [...prefix, "sh", "-c", PROBE_SCRIPT], {
+    env,
+    encoding: "utf8",
+    timeout: 10_000,
+  });
+  if (probe.status !== 0)
+    return {
+      effective: false,
+      supported: true,
+      reason: `systemd-run failed: ${(probe.stderr || probe.error?.message || `exit ${probe.status}`).trim().split("\n")[0]}`,
+      delegate,
+    };
+  const [memoryMax = "", cpuMax = ""] = probe.stdout.trim().split(/\n/u);
+  if (memoryMax.trim() === PROBE_MEMORY && cpuMax.trim().startsWith("50000 "))
+    return { effective: true, memoryMax: memoryMax.trim(), cpuMax: cpuMax.trim(), delegate };
+  return {
+    effective: false,
+    supported: true,
+    reason: `the scope started but its cgroup reads memory.max=${memoryMax.trim() || "?"} cpu.max=${cpuMax.trim() || "?"} (asked ${PROBE_MEMORY} and 50000 100000)`,
+    delegate,
+  };
+}

package/src/core/heavy-words.ts

@@ -0,0 +1,83 @@
+// The hook launchers' pre-check for the heavy-command gate (#325): could
+// this shell command be heavy? A launcher answers light commands before the
+// Workit runtime loads, so this only looks for a catalog word (core/heavy.ts
+// TOOLS plus the runners it looks through) or the first word of a machine or
+// repo pattern, with node built-ins. A false yes only costs a runtime load.
+// packages/workit-claude-code/bin/workit-hook.mjs keeps a copy (it cannot
+// import TypeScript); test/workit-core/heavy-words.test.ts keeps them equal.
+import fs from "node:fs";
+import path from "node:path";
+import { stateDir as workitStateDir } from "./workit-paths.mjs";
+import { repoHeavyCommands } from "../check-config";
+
+export const HEAVY_WORDS: ReadonlySet<string> = new Set(
+  (
+    "npm npx pnpm pnpx yarn bun bunx deno corepack make gmake docker podman nerdctl " +
+    "python python3 py uv poetry pdm pipenv hatch rye bundle rake nx " +
+    "jest vitest mocha ava tap karma jasmine nyc c8 tsc vue-tsc svelte-check eslint stylelint " +
+    "tslint webpack webpack-cli rollup parcel tsup vite next nuxt nuxi astro ng react-scripts " +
+    "playwright cypress wdio testcafe turbo lerna sonar-scanner sonarless sonarless-mcp go " +
+    "golangci-lint gotestsum staticcheck cargo mvn mvnw gradle gradlew ant sbt bazel bazelisk " +
+    "buck2 dotnet msbuild pytest py.test tox nox mypy pyright pylint coverage maturin pip pip3 " +
+    "rspec rails phpunit pest phpstan psalm composer mix swift xcodebuild flutter dart pod cmake " +
+    "ninja meson ctest scons docker-compose buildah earthly"
+  ).split(" "),
+);
+
+const wordsOf = (command: string): string[] =>
+  command
+    .split(/[\s;&|()<>`'"]+/u)
+    .map((word) =>
+      (word.split(/[\\/]/u).at(-1) ?? "").toLowerCase().replace(/\.(?:exe|cmd|bat)$/u, ""),
+    )
+    .filter(Boolean);
+
+export const stateDir = (env: NodeJS.ProcessEnv): string => workitStateDir(env);
+
+const readJson = (file: string): unknown => {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+};
+
+/** First words of the machine and repo patterns; null when one could match anything. */
+const patternWords = (cwd: string, env: NodeJS.ProcessEnv): Set<string> | null => {
+  const patterns: unknown[] = [];
+  const machine = readJson(path.join(stateDir(env), "heavy-commands.json")) as
+    | { patterns?: unknown }
+    | undefined;
+  if (Array.isArray(machine?.patterns)) patterns.push(...machine.patterns);
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, ".git"))) {
+      patterns.push(...repoHeavyCommands(dir));
+      break;
+    }
+    if (path.dirname(dir) === dir) break;
+  }
+  const words = new Set<string>();
+  for (const pattern of patterns) {
+    if (typeof pattern !== "string") continue;
+    const first = wordsOf(pattern)[0];
+    if (!first || first.includes("*")) return null;
+    words.add(first);
+  }
+  return words;
+};
+
+/** Could `command` be heavy? Never throws; a doubt answers yes. */
+export function maybeHeavy(
+  command: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  try {
+    const words = wordsOf(command);
+    if (words.some((word) => HEAVY_WORDS.has(word) || /^python[\d.]*$/u.test(word))) return true;
+    const extra = patternWords(cwd, env);
+    return extra === null || words.some((word) => extra.has(word));
+  } catch {
+    return true;
+  }
+}