@brainervirus/workit-core 8.12.1 → 8.12.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.12.1",
+  "version": "8.12.3",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/autonomy.ts

@@ -14,7 +14,7 @@
 //   a process that drives a pseudo-terminal or edits the file directly can
 //   still defeat it; the host's permission prompt is the hard boundary.
 // - `release` gates `workit git push --release`: pushing the git-flow
-//   production and develop branches (fast-forward only) and `v*` tags whose
+//   production and develop branches (fast-forward only) and release tags (`v*` or git-flow's prefix) whose
 //   commit already landed (a tag never moves). Outside git-flow it pushes
 //   tags only. It needs `push` too.
 // - Defaults (D4) when a kind is absent: push, pr and rerun are allowed;

package/src/core/route-intent.ts

@@ -1,7 +1,13 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { inWorkitWorkspace, rawInvocations } from "../hooks/raw-git";
+import {
+  expandGitAliases,
+  inWorkitWorkspace,
+  pushAction,
+  rawInvocations,
+  type RawInvocation,
+} from "../hooks/raw-git";
 import type { ShellDialect } from "../hooks/shell-words";
 import { validateBranchNameFor, type BranchNamePolicyCheck } from "./branch";
 
@@ -11,6 +17,7 @@ const UNKNOWABLE = /[$`*?[\]{}~]/u;
 const SWITCH_CREATE = new Set(["-c", "--create", "-C", "--force-create", "--orphan"]);
 const CHECKOUT_CREATE = new Set(["-b", "-B", "--orphan"]);
 const WORKTREE_CREATE = new Set(["-b", "-B"]);
+const SUBTREE_CREATE = new Set(["-b", "--branch"]);
 /** `git branch` options that list, delete or configure: no branch is created. */
 const BRANCH_NO_CREATE = new Set(
   ["-d", "-D", "--delete", "-l", "--list", "-a", "--all", "-r", "--remotes", "--show-current"]
@@ -21,16 +28,37 @@ const BRANCH_NO_CREATE = new Set(
 /** `git branch -m|-c [<old>] <new>`: a rename or copy creates `<new>`. */
 const BRANCH_RENAME = new Set(["-m", "-M", "--move", "-c", "-C", "--copy"]);
 
-/** The value of `flag` in `args` (`-c x`, `-cx`, `--create=x`), or null. */
+/** `--name` matches a long option in `flags`, whole or by git's unambiguous-prefix rule (`--cre`). */
+const longOption = (name: string, flags: ReadonlySet<string>): boolean =>
+  flags.has(name) ||
+  (name.length >= 3 && [...flags].some((flag) => flag.startsWith("--") && flag.startsWith(name)));
+
+/** The short options of `flags` (`-c` → `c`). */
+const shortsOf = (flags: ReadonlySet<string>): string =>
+  [...flags]
+    .filter((flag) => /^-[^-]$/u.test(flag))
+    .join("")
+    .replaceAll("-", "");
+
+/**
+ * The value of `flag` in `args`: `-c x`, `-cx`, a short cluster (`-fc x`),
+ * `--create=x`, `--create x` or an abbreviation (`--cre x`). Null when absent.
+ */
 const flagValue = (args: readonly string[], flags: ReadonlySet<string>): string | null => {
+  const shorts = shortsOf(flags);
   for (let index = 1; index < args.length; index++) {
     const arg = args[index];
     if (arg === "--") return null;
-    if (flags.has(arg)) return args[index + 1] ?? null;
-    const eq = arg.indexOf("=");
-    if (arg.startsWith("--") && eq > 0 && flags.has(arg.slice(0, eq))) return arg.slice(eq + 1);
-    // An attached short value: `-cchore/x`.
-    if (!arg.startsWith("--") && arg.length > 2 && flags.has(arg.slice(0, 2))) return arg.slice(2);
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (!longOption(eq > 0 ? arg.slice(0, eq) : arg, flags)) continue;
+      return eq > 0 ? arg.slice(eq + 1) : (args[index + 1] ?? null);
+    }
+    if (!arg.startsWith("-") || arg.length < 2) continue;
+    // A cluster of short switches; the creating one takes the rest or the next word.
+    for (let at = 1; at < arg.length; at++)
+      if (shorts.includes(arg[at]))
+        return at + 1 < arg.length ? arg.slice(at + 1) : (args[index + 1] ?? null);
   }
   return null;
 };
@@ -68,34 +96,134 @@ const branchCommandTarget = (args: readonly string[]): string | null => {
       positionals.push(...args.slice(index + 1));
       break;
     }
-    const flag = arg.split("=", 1)[0];
-    if (BRANCH_NO_CREATE.has(flag)) return null;
-    if (BRANCH_RENAME.has(flag)) rename = true;
-    else if (!arg.startsWith("-")) positionals.push(arg);
+    if (arg.startsWith("--")) {
+      const flag = arg.split("=", 1)[0];
+      if (longOption(flag, BRANCH_NO_CREATE)) return null;
+      if (longOption(flag, BRANCH_RENAME)) rename = true;
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      // A short cluster: `-fm`, `-vv`, `-dr`.
+      const shorts = arg.slice(1).split("");
+      if (shorts.some((short) => BRANCH_NO_CREATE.has(`-${short}`))) return null;
+      if (shorts.some((short) => BRANCH_RENAME.has(`-${short}`))) rename = true;
+    } else positionals.push(arg);
   }
   if (positionals.length < 1 || positionals.length > 2) return null;
   return rename ? (positionals.at(-1) ?? null) : positionals[0];
 };
 
+/** Positional words after `skip` leading words, past options; `values` take the next word. */
+const positionalsOf = (
+  args: readonly string[],
+  skip: number,
+  values: ReadonlySet<string> = new Set(),
+): string[] => {
+  const found: string[] = [];
+  for (let index = skip; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--") return [...found, ...args.slice(index + 1)];
+    if (values.has(arg)) index++;
+    else if (!arg.startsWith("-") || arg === "-") found.push(arg);
+  }
+  return found;
+};
+
+const localHead = (ref: string): string | null =>
+  ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : null;
+
+/** `git update-ref refs/heads/<b> <sha>` and `--stdin` `create|update refs/heads/<b>` lines. */
+const updateRefTargets = (args: readonly string[], stdin: string | undefined): string[] => {
+  if (args.some((arg) => arg === "-d" || arg === "--delete")) return [];
+  if (args.includes("--stdin"))
+    return (stdin ?? "")
+      .split(/[\n\0]/u)
+      .map((line) => /^\s*(?:create|update)\s+(\S+)/u.exec(line)?.[1] ?? "")
+      .map(localHead)
+      .filter((name): name is string => name !== null);
+  const [ref] = positionalsOf(args, 1, new Set(["-m"]));
+  const name = ref ? localHead(ref) : null;
+  return name ? [name] : [];
+};
+
+/** `git symbolic-ref HEAD refs/heads/<b>`: the next commit creates `<b>`. */
+const symbolicRefTarget = (args: readonly string[]): string | null => {
+  if (args.some((arg) => arg === "-d" || arg === "--delete")) return null;
+  const [, ref] = positionalsOf(args, 1, new Set(["-m"]));
+  return ref ? localHead(ref) : null;
+};
+
+/** git fetch/pull options that take a value. */
+const FETCH_VALUES = new Set(
+  ["--depth", "--deepen", "--shallow-since", "--shallow-exclude", "--refmap", "-j", "--jobs"]
+    .concat(["--upload-pack", "-o", "--server-option", "--negotiation-tip", "--filter"])
+    .concat(["--recurse-submodules-default", "--submodule-prefix", "-s", "--strategy", "-X"])
+    .concat(["--strategy-option"]),
+);
+
+/**
+ * `git fetch|pull <remote> <src>:<dst>` writes the local branch `<dst>`
+ * (`refs/heads/<dst>` or a bare name); `--stdin` reads the refspecs. A
+ * glob destination mirrors names the remote already has.
+ */
+const fetchTargets = (args: readonly string[], stdin: string | undefined): string[] => {
+  if (args.includes("--all") || args.includes("--multiple")) return [];
+  const specs = args.includes("--stdin")
+    ? (stdin ?? "").split(/\s+/u).filter(Boolean)
+    : positionalsOf(args, 1, FETCH_VALUES).slice(1);
+  const names: string[] = [];
+  for (const raw of specs) {
+    const colon = raw.indexOf(":");
+    const destination = colon >= 0 ? raw.slice(colon + 1) : "";
+    if (!destination || destination.includes("*")) continue;
+    const name = destination.startsWith("refs/") ? localHead(destination) : destination;
+    if (name) names.push(name);
+  }
+  return names;
+};
+
+/** `git push . <src>:<dst>` writes the local branch `<dst>`. */
+const localPushTargets = (args: string[]): string[] => {
+  const action = pushAction(args);
+  if (action?.kind !== "push" || action.remote !== "." || action.deletes) return [];
+  return action.targets.filter((name): name is string => name !== null);
+};
+
 /**
- * The branch one git invocation creates: `switch -c|-C|--create <b>`,
- * `checkout -b|-B <b>`, `branch [-m|-c] <b> [start]` and `worktree add -b|-B
- * <b>`, wherever the option stands. `args` start at the subcommand (after
- * git's global options). Null when it creates none.
+ * The branches one git invocation creates: `switch -c|-C|--create <b>`,
+ * `checkout -b|-B <b>`, `branch [-m|-c] <b> [start]`, `worktree add -b|-B
+ * <b>`, `stash branch <b>`, `update-ref refs/heads/<b>`, `symbolic-ref HEAD
+ * refs/heads/<b>`, `fetch|pull <remote> <src>:<b>`, `push . <src>:<b>` and
+ * `subtree split -b <b>`, wherever the option stands. `args` start at the
+ * subcommand (after git's global options). Names a shell settles only when
+ * it runs (`$X`) are left out.
  */
-export const gitBranchCreation = (args: readonly string[]): string | null => {
+export const gitBranchCreations = (args: string[], stdin?: string): string[] => {
   const [sub, second] = args;
-  const target =
+  const targets: Array<string | null> =
     sub === "switch"
-      ? flagValue(args, SWITCH_CREATE)
+      ? [flagValue(args, SWITCH_CREATE)]
       : sub === "checkout"
-        ? flagValue(args, CHECKOUT_CREATE)
+        ? [flagValue(args, CHECKOUT_CREATE)]
         : sub === "branch"
-          ? branchCommandTarget(args)
+          ? [branchCommandTarget(args)]
           : sub === "worktree" && second === "add"
-            ? worktreeTarget(args.slice(1))
-            : null;
-  return target && !target.startsWith("-") && !UNKNOWABLE.test(target) ? target : null;
+            ? [worktreeTarget(args.slice(1))]
+            : sub === "stash" && second === "branch"
+              ? positionalsOf(args, 2).slice(0, 1)
+              : sub === "update-ref"
+                ? updateRefTargets(args, stdin)
+                : sub === "symbolic-ref"
+                  ? [symbolicRefTarget(args)]
+                  : sub === "fetch" || sub === "pull"
+                    ? fetchTargets(args, stdin)
+                    : sub === "push"
+                      ? localPushTargets(args)
+                      : sub === "subtree" && second === "split"
+                        ? [flagValue(args.slice(1), SUBTREE_CREATE)]
+                        : [];
+  return targets.filter(
+    (target): target is string =>
+      target !== null && target !== "" && !target.startsWith("-") && !UNKNOWABLE.test(target),
+  );
 };
 
 export type ShellBranchTarget = {
@@ -104,24 +232,26 @@ export type ShellBranchTarget = {
   dir: string | null | undefined;
 };
 
+const targetsOf = (invocations: readonly RawInvocation[]): ShellBranchTarget[] =>
+  invocations.flatMap((invocation) =>
+    invocation.tool === "git"
+      ? gitBranchCreations(invocation.args, invocation.stdin).map((branch) => ({
+          branch,
+          dir: invocation.dir,
+        }))
+      : [],
+  );
+
 /**
  * Every branch a shell command creates, through the raw-git tokenizer: `&&`,
  * `;` and `|` chains, `cd`/`pushd` and `git -C`, env prefixes and wrappers,
- * quoted names and `bash -c` scripts.
+ * quoted names, compound commands and nested scripts (git aliases need the
+ * repository: see shellBranchPolicyViolation).
  */
 export const shellBranchTargets = (
   command: string,
   dialect: ShellDialect = "posix",
-): ShellBranchTarget[] => {
-  if (!/\bgit\b/u.test(command)) return [];
-  const found: ShellBranchTarget[] = [];
-  for (const invocation of rawInvocations(command, dialect)) {
-    if (invocation.tool !== "git") continue;
-    const branch = gitBranchCreation(invocation.args);
-    if (branch) found.push({ branch, dir: invocation.dir });
-  }
-  return found;
-};
+): ShellBranchTarget[] => targetsOf(rawInvocations(command, dialect));
 
 /** The first branch a shell command creates, or null. */
 export const shellBranchTarget = (command: string): string | null =>
@@ -135,6 +265,14 @@ const localBranchExists = (dir: string, branch: string): boolean =>
     timeout: 5_000,
   }).status === 0;
 
+/** The directory a command judged from `root` runs git in, or null when not this policy's business. */
+const judgedDir = (root: string, dir: string | null | undefined): string | null => {
+  if (dir === undefined) return null;
+  if (dir === null) return root;
+  const resolved = path.resolve(root, dir);
+  return existsSync(resolved) && inWorkitWorkspace(resolved) ? resolved : null;
+};
+
 /**
  * The branch policy verdict for every new branch a shell command creates,
  * each checked in the directory git runs in (a linked worktree resolves to
@@ -142,9 +280,9 @@ const localBranchExists = (dir: string, branch: string): boolean =>
  * judged there. One that changes directory is judged only when that
  * directory is known, already exists and is in a Workit workspace: a scratch
  * repository (`cd "$(mktemp -d)"`, `git init x && cd x`, a fresh clone) is
- * not the cwd workspace's business. A name that already exists locally is
- * skipped (`git branch -f legacy HEAD`). Null when no new branch is judged;
- * the first violation otherwise.
+ * not the cwd workspace's business. A git alias is resolved there first. A
+ * name that already exists locally is skipped (`git branch -f legacy HEAD`).
+ * Null when no new branch is judged; the first violation otherwise.
  */
 export const shellBranchPolicyViolation = (
   root: string,
@@ -152,14 +290,16 @@ export const shellBranchPolicyViolation = (
   dialect: ShellDialect = "posix",
 ): BranchNamePolicyCheck | null => {
   let judged = false;
-  for (const target of shellBranchTargets(command, dialect)) {
-    if (target.dir === undefined) continue;
-    const dir = target.dir === null ? root : path.resolve(root, target.dir);
-    if (target.dir !== null && (!existsSync(dir) || !inWorkitWorkspace(dir))) continue;
-    if (localBranchExists(dir, target.branch)) continue;
-    judged = true;
-    const check = validateBranchNameFor(dir, target.branch);
-    if (!check.ok) return check;
+  const cache = new Map();
+  for (const raw of rawInvocations(command, dialect)) {
+    if (raw.tool !== "git" || judgedDir(root, raw.dir) === null) continue;
+    for (const target of targetsOf(expandGitAliases(root, raw, cache))) {
+      const dir = judgedDir(root, target.dir);
+      if (dir === null || localBranchExists(dir, target.branch)) continue;
+      judged = true;
+      const check = validateBranchNameFor(dir, target.branch);
+      if (!check.ok) return check;
+    }
   }
   return judged ? { ok: true } : null;
 };

package/src/git/ops.ts

@@ -1138,12 +1138,22 @@ export type ReleasePushPlan = Omit<PushPlan, "branch" | "sha"> & {
   production: string | null;
 };
 
-/** A release tag: `v` and a digit (`v4.1.0`, `v2`). */
-const RELEASE_TAG = /^v\d/u;
+/**
+ * The release tag prefix: git-flow's own `gitflow.prefix.versiontag` when the
+ * repository sets it (an empty value means bare `4.1.0` tags), else `v`.
+ */
+const releaseTagPrefix = (cwd: string): string => {
+  const configured = git(cwd, ["config", "--get", "gitflow.prefix.versiontag"]);
+  return configured.ok ? configured.stdout.trim() : "v";
+};
+
+/** A release tag: the prefix and a digit (`v4.1.0`, `v2`, or `4.1.0` with an empty prefix). */
+const isReleaseTag = (name: string, prefix: string): boolean =>
+  name.startsWith(prefix) && /^\d/u.test(name.slice(prefix.length));
 
 /**
  * What `workit git push --release` may push: the git-flow production and
- * develop branches and `v*` tags, nothing else, each by its local ref. Everything else stays on the feature-branch
+ * develop branches and release tags (`v*`, or git-flow's configured prefix), nothing else, each by its local ref. Everything else stays on the feature-branch
  * path (`workit git push`, `workit pr create`).
  */
 export function releasePushPreflight(
@@ -1172,11 +1182,12 @@ export function releasePushPreflight(
         `workit git push --release refs/heads/${raw}  # or refs/tags/${raw}`,
       );
     if (tag) {
-      if (!RELEASE_TAG.test(tagName))
+      const prefix = releaseTagPrefix(cwd);
+      if (!isReleaseTag(tagName, prefix))
         return failure(
           "blocked",
-          `release_push_refused: tag ${tagName} is not a release tag (v<version>)`,
-          "git tag -a v<version> -m <message>  # then: workit git push --release v<version>",
+          `release_push_refused: tag ${tagName} is not a release tag (${prefix}<version>, from ${prefix === "v" ? "the default" : "gitflow.prefix.versiontag"})`,
+          `git tag -a ${prefix}<version> -m <message>  # then: workit git push --release ${prefix}<version>`,
         );
       refs.push({ kind: "tag", name: tagName, ref: `refs/tags/${tagName}`, sha: tag });
       continue;

package/src/hooks/hosts/cursor.ts

@@ -63,7 +63,9 @@ export const CURSOR_DESCRIPTOR: HostDescriptor = {
     // `loop_limit: 1`, so the continuation's own stop never runs the hook.
     stop: { support: "native", native: "stop" },
   },
-  shellPolicy: { deny: "native", channel: "exit2+json", failClosed: true },
+  // Fails open like every host: a payload Workit cannot parse (a renamed
+  // field in a Cursor release) must not block every shell command.
+  shellPolicy: { deny: "native", channel: "exit2+json", failClosed: false },
   context: {
     sessionStart: "native",
     perTurn: "none",

package/src/hooks/policy.ts

@@ -1,19 +1,28 @@
 import { shellBranchPolicyViolation } from "../core/route-intent";
 import type { HookDecision } from "./protocol";
-import type { ShellDialect } from "./shell-words";
+import { analysisDenial } from "./raw-git";
+import { ShellAnalysisError, type ShellDialect } from "./shell-words";
 
 /**
  * Branch policy for one shell command: a raw branch creation (`git switch -c`,
  * `checkout -b`, `branch`, `worktree add -b`, in any chain, directory or
  * wrapper) onto a noncompliant name is denied. Every other command keeps the
  * host's own permission decision. The reason carries the policy's correction.
+ * A command the hook cannot analyze is denied with how to split it; any other
+ * failure propagates to the host's fail policy.
  */
 export const shellPolicy = (
   cwd: string,
   command: string,
   dialect: ShellDialect = "posix",
 ): HookDecision => {
-  const policy = shellBranchPolicyViolation(cwd, command, dialect);
+  let policy: ReturnType<typeof shellBranchPolicyViolation>;
+  try {
+    policy = shellBranchPolicyViolation(cwd, command, dialect);
+  } catch (error) {
+    if (error instanceof ShellAnalysisError) return analysisDenial(error);
+    throw error;
+  }
   return policy && !policy.ok
     ? { kind: "deny", reason: `branch_policy_denied: ${policy.error}`, unblock: null }
     : { kind: "none" };