@brainervirus/workit-core 2.3.0 → 2.5.0

package/package.json

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

package/src/autonomy.ts

@@ -0,0 +1,135 @@
+// Autonomy grants (D4, D15; design §0 #12, §4.2): the per-workspace ceiling on
+// what an agent may deliver without asking. S11 introduces the reader and the
+// one seam every delivery verb consults, `requireGrant(kind)`; S16 adds
+// `workit grant`, the D4 defaults and the legacy `autoApprove` mapping.
+//
+// Today (S11):
+// - Grants are read only from the matched workspace entry in the user's
+//   `~/.config/workit/workspaces.json` (`"autonomy": {"push": true, "pr": true,
+//   "merge": false | true | "verified", "release": false}`), never from a repo
+//   file, and nothing here writes them (D15: never raised headless).
+// - An explicit value is honored: `false` denies with `grant_required`, `true`
+//   allows, and `merge: "verified"` allows only with an accepted independent
+//   verdict (S13). `merge: true` is the only way to merge without one.
+// - An absent grant is allowed on the host's own authority (`source:
+//   "host_authority"`): the host permission prompt is the ceiling, and a merge
+//   still needs an accepted verdict. S16 replaces that default with the D4
+//   ceiling `{push: true, pr: true, merge: false, release: false}`.
+// - Grants require an account (design §2.0 Identity): a workspace with any
+//   grant but no `vcs.account` cannot push, open or merge through a forge,
+//   so a personal grant never rides a work credential.
+import { resolveRuntimeWorkspaceVcs } from "./core/workspaces";
+
+export type GrantKind = "push" | "pr" | "merge" | "release";
+const GRANT_KINDS: readonly GrantKind[] = ["push", "pr", "merge", "release"];
+
+/** One grant as configured: `"verified"` means allowed with an accepted verdict. */
+export type GrantValue = boolean | "verified";
+
+export type Autonomy = {
+  workspace: string | null;
+  /** Explicitly configured grants; a kind that is absent falls back to host authority. */
+  grants: Partial<Record<GrantKind, GrantValue>>;
+  source: "autonomy" | "host_authority";
+  accountConfigured: boolean;
+};
+
+export type GrantDecision =
+  | {
+      allowed: true;
+      kind: GrantKind;
+      /** Where the permission came from. */
+      source: "autonomy" | "host_authority";
+      /** A merge must also have an accepted independent verdict (S13). */
+      requireVerdict: boolean;
+      workspace: string | null;
+    }
+  | {
+      allowed: false;
+      kind: GrantKind;
+      reason: "grant_required" | "account_required" | "config_invalid";
+      error: string;
+      unblock: string;
+      workspace: string | null;
+    };
+
+const isGrantValue = (value: unknown): value is GrantValue =>
+  value === true || value === false || value === "verified";
+
+/** The grants for the workspace `cwd` belongs to (read-only). */
+export function resolveAutonomy(cwd: string): Autonomy {
+  const workspace = resolveRuntimeWorkspaceVcs(cwd);
+  const raw = (workspace as { autonomy?: unknown } | null)?.autonomy;
+  const grants: Autonomy["grants"] = {};
+  if (raw && typeof raw === "object" && !Array.isArray(raw))
+    for (const kind of GRANT_KINDS) {
+      const value = (raw as Record<string, unknown>)[kind];
+      if (isGrantValue(value)) grants[kind] = value;
+    }
+  return {
+    workspace: workspace?.name ?? null,
+    grants,
+    source: Object.keys(grants).length > 0 ? "autonomy" : "host_authority",
+    accountConfigured: Boolean(workspace?.vcs?.account),
+  };
+}
+
+const grantHint = (workspace: string | null, kind: GrantKind): string =>
+  `ask the user to set "autonomy": {"${kind}": ${kind === "merge" ? '"verified"' : "true"}} for workspace "${workspace ?? "?"}" in ~/.config/workit/workspaces.json (S16: workit grant set ${workspace ?? "<workspace>"} ${kind}=${kind === "merge" ? "verified" : "true"})`;
+
+/**
+ * The seam every delivery verb consults before an external effect. `forge`
+ * says the effect goes through a GitHub/GitLab account (a push to a local
+ * path does not).
+ */
+export function requireGrant(
+  cwd: string,
+  kind: GrantKind,
+  options: { forge?: boolean } = {},
+): GrantDecision {
+  let autonomy: Autonomy;
+  try {
+    autonomy = resolveAutonomy(cwd);
+  } catch (error) {
+    return {
+      allowed: false,
+      kind,
+      reason: "config_invalid",
+      error: `grant_unreadable: ${error instanceof Error ? error.message : String(error)}`,
+      unblock: "fix ~/.config/workit/workspaces.json (workit init → Workspaces)",
+      workspace: null,
+    };
+  }
+  const { workspace } = autonomy;
+  const value = autonomy.grants[kind];
+  if (value === false)
+    return {
+      allowed: false,
+      kind,
+      reason: "grant_required",
+      error: `grant_required: ${kind} is not granted for workspace "${workspace ?? "?"}"`,
+      unblock: grantHint(workspace, kind),
+      workspace,
+    };
+  if (
+    autonomy.source === "autonomy" &&
+    !autonomy.accountConfigured &&
+    options.forge !== false &&
+    kind !== "release"
+  )
+    return {
+      allowed: false,
+      kind,
+      reason: "account_required",
+      error: `account_required: workspace "${workspace ?? "?"}" has autonomy grants but no vcs.account, so the credential cannot be checked`,
+      unblock: `set vcs.account for workspace "${workspace ?? "?"}" in ~/.config/workit/workspaces.json`,
+      workspace,
+    };
+  return {
+    allowed: true,
+    kind,
+    source: value === undefined ? "host_authority" : "autonomy",
+    requireVerdict: kind === "merge" && value !== true,
+    workspace,
+  };
+}

package/src/core/external-action-effects.ts

@@ -57,6 +57,7 @@ import {
 import { normalizeChainSteps } from "./authority";
 import { resolveInside, run as coreRun } from "../core";
 import { hostingApiHostMatches, vcsCliIdentity, vcsConfig } from "./vcs-config";
+import { deleteRemoteBranch } from "../git/ops";
 import { assertProductWriteAllowed, currentWriterOwnsTask } from "./workers";
 import { sameDirectoryIdentity, TaskStore } from "./task-store";
 
@@ -2128,15 +2129,9 @@ export const executeConcreteExternalAction = async (
           outcome: "not_started",
         });
       const branch = request.payload.branch;
-      const result = run(root, [
-        "push",
-        `--force-with-lease=refs/heads/${branch}:${approvedTip}`,
-        "--delete",
-        target,
-        branch,
-      ]);
-      if (result.exitCode === 0) return success(null, null, { branch, deletedTip: approvedTip });
-      return /stale info|cannot lock ref|fetch first|non-fast-forward/i.test(result.stderr)
+      const result = deleteRemoteBranch(root, target, branch, approvedTip);
+      if (result.ok) return success(null, null, { branch, deletedTip: approvedTip });
+      return result.lease
         ? failure("capability_unavailable", "remote branch tip changed before deletion", {
             outcome: "not_started",
           })

package/src/core/pr-create.ts

@@ -5,21 +5,13 @@ import { pathToFileURL } from "node:url";
 import { hostingApiHostMatches, vcsCliIdentity, vcsConfig } from "./vcs-config";
 export { hostingApiHostMatches } from "./vcs-config";
 import { resolveBranchPolicyFor } from "./branch";
+import { buildBody, parseGhIssue, parseGhRepo } from "../forge/pr-body";
 
 // Port of scripts/pr-create.sh — build MR/PR body issue linking + create via glab/gh.
 // Hosted creation is enabled (decision ae03c569): every create path pre-binds
 // the approved source SHA through WORKIT_EXPECTED_* and the shared executor
 // post-verifies the provider PR head before reporting success. The residual
 // non-atomic source-SHA race is accepted.
-function parseGhRepo(remote: string): string | null {
-  remote = (remote || "").trim().replace(/\/+$/, "");
-  if (!remote) return null;
-  if (remote.endsWith(".git")) remote = remote.slice(0, -4);
-  if (remote.includes(":")) remote = remote.split(":").pop() ?? ""; // drop git@host part (scp-style URL)
-  const parts = remote.split("/").filter(Boolean);
-  return parts.length >= 2 ? parts.slice(-2).join("/") : null;
-}
-
 const remoteRepoPath = (
   remote: string,
 ): { host: string; path: string; protocol: string } | null => {
@@ -63,68 +55,6 @@ const cliRepository = (
   return host === "gitlab.com" ? parsed.path : `https://${host}/${parsed.path}`;
 };
 
-function parseGhIssue(value: string): string {
-  const m = /issues\/(\d+)/.exec(value);
-  return m ? m[1] : String(value).trim().replace(/^#/, "");
-}
-
-// RL-03/CA-25/AR-08: a branch-derived numeric issue id must be a bare number at
-// a segment or dash boundary — and never part of a date segment. Year-first
-// (feature/2024-01-15/x) and day-first (feature/15-01-2024/x) dates are both
-// skipped — a complete date anywhere in a segment (release-2024-01-15,
-// v2-2024-01-15-fix) — so no date digit ever closes an issue. Deliberate
-// numeric issue branches (feature/42-title, feature/2024-fix) keep linking.
-function deriveGhIssueFromBranch(branch: string): string {
-  for (const segment of branch.split("/")) {
-    if (/^\d{4}-\d/.test(segment)) continue; // year-first date-like segment (incl. year-month)
-    if (/\d{4}-\d{1,2}-\d{1,2}/.test(segment)) continue; // complete year-first date anywhere
-    if (/\d{1,2}-\d{1,2}-\d{4}/.test(segment)) continue; // complete day-first date anywhere
-    const m = /(?:^|-)(\d+)(?:-|$)/.exec(segment);
-    if (m) return m[1];
-  }
-  return "";
-}
-
-function buildBody(
-  body: string,
-  branch: string,
-  linkIssues: boolean,
-  baseUrl: string,
-  ytIssue: string,
-  ghLinkOnPr: boolean,
-  ghIssue: string,
-  ghRelation: string,
-  ghRepo: string | null,
-): string {
-  let line: string | null = null;
-  if (linkIssues) {
-    let issue = ytIssue;
-    if (!issue && branch) {
-      // anchored prefix + \b boundary, 3+ digits so version-like tokens (POSTGRES-16, HTTP-3) never link
-      const m = /(?:^|\/|-)([A-Z]{2,}-\d{3,})\b/.exec(branch);
-      if (m) issue = m[1];
-    }
-    if (issue && baseUrl) line = `Related to: ${baseUrl.replace(/\/+$/, "")}/issue/${issue}`;
-  } else if (ghLinkOnPr) {
-    let issue = parseGhIssue(ghIssue);
-    if (!issue && branch) {
-      // pure-number issue id (feature/42-title -> 42); digits must be followed by a dash or end-of-string
-      // so version tokens (release/1.2.3, backport/8.0.1, lodash-4.17.21, 2024.1) never link
-      issue = deriveGhIssueFromBranch(branch);
-    }
-    if (issue) {
-      if (ghRelation === "related") {
-        line = `Related to #${issue}`;
-        if (ghRepo) line += ` — https://github.com/${ghRepo}/issues/${issue}`;
-      } else {
-        line = `Closes #${issue}`;
-      }
-    }
-  }
-  if (line === null) return body;
-  return body ? `${body}\n\n${line}` : line;
-}
-
 const truthy = (v: string | undefined): boolean =>
   ["1", "true", "yes"].includes(String(v ?? "").toLowerCase());
 
@@ -714,4 +644,5 @@ export function mergePr(
   };
 }
 
+// Moved to forge/pr-body.ts (S11); re-exported for the managed action path until S16.
 export { buildBody, parseGhRepo, parseGhIssue };

package/src/forge/exec.ts

@@ -0,0 +1,221 @@
+// Bounded gh/glab invocation (design §0 #8: `gh api` / `glab api` only, never
+// porcelain whose flags vary by CLI version). Every call has a timeout, runs
+// with prompts and update checks disabled, and targets the API host derived
+// from the push remote (GH_HOST / GITLAB_HOST). Failures map to the envelope
+// codes; stderr is redacted before it reaches a message.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { ForgeKind } from "../git/rev";
+import { redactText } from "./redact";
+import { failure, type ForgeResult } from "./types";
+
+export type CliBin = "gh" | "glab";
+
+export type CliRun = {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  /** The binary is not on PATH. */
+  missing: boolean;
+};
+
+/** Runs one gh/glab command. Injected in tests to replay recorded API fixtures. */
+export type ForgeRunner = (
+  bin: CliBin,
+  args: readonly string[],
+  options: {
+    timeoutMs: number;
+    /** Credential for this call (GH_TOKEN / GITLAB_TOKEN); never logged. */
+    token?: string;
+  },
+) => CliRun;
+
+/** Default per-call bounds (ms). */
+export const FORGE_TIMEOUTS = { api: 20_000, log: 30_000 } as const;
+
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+/** Locate `bin` on `env.PATH` without running a shell. */
+export function findExecutable(bin: string, env: NodeJS.ProcessEnv): string | null {
+  const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+  // Only real executables: spawning a .cmd/.bat shim would need a shell.
+  const exts = process.platform === "win32" ? [".exe"] : [""];
+  for (const dir of dirs)
+    for (const ext of exts) {
+      const candidate = path.join(dir, `${bin}${ext}`);
+      try {
+        const stat = fs.statSync(candidate);
+        if (stat.isFile()) return candidate;
+      } catch {
+        // not here
+      }
+    }
+  return null;
+}
+
+/** The real gh/glab, bound to one API host. */
+export function systemRunner(
+  kind: ForgeKind,
+  apiHost: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ForgeRunner {
+  const childEnv: NodeJS.ProcessEnv = {
+    ...env,
+    ...(kind === "github" ? { GH_HOST: apiHost } : { GITLAB_HOST: apiHost }),
+    GH_PROMPT_DISABLED: "1",
+    GH_NO_UPDATE_NOTIFIER: "1",
+    GLAB_CHECK_UPDATE: "false",
+    NO_PROMPT: "1",
+    NO_COLOR: "1",
+    GH_PAGER: "",
+    GLAB_PAGER: "",
+    PAGER: "",
+  };
+  return (bin, args, options) => {
+    const exe = findExecutable(bin, env);
+    if (!exe) return { status: null, stdout: "", stderr: "", timedOut: false, missing: true };
+    const token = options.token
+      ? kind === "github"
+        ? { GH_TOKEN: options.token, GH_ENTERPRISE_TOKEN: options.token }
+        : { GITLAB_TOKEN: options.token }
+      : {};
+    const result = spawnSync(exe, [...args], {
+      encoding: "utf8",
+      env: { ...childEnv, ...token },
+      maxBuffer: MAX_BUFFER,
+      timeout: options.timeoutMs,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const error: NodeJS.ErrnoException | undefined = result.error;
+    return {
+      status: result.status,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      timedOut: error?.code === "ETIMEDOUT",
+      missing: error?.code === "ENOENT",
+    };
+  };
+}
+
+export const installHint = (bin: CliBin): string =>
+  bin === "gh"
+    ? "install the GitHub CLI (https://cli.github.com) and run: gh auth login"
+    : "install glab (https://gitlab.com/gitlab-org/cli) and run: glab auth login";
+
+export const loginHint = (bin: CliBin, apiHost: string): string =>
+  `${bin} auth login --hostname ${apiHost}`;
+
+/** Map a failed CLI run to an envelope error. */
+export function cliFailure<T>(
+  bin: CliBin,
+  apiHost: string,
+  run: CliRun,
+  what: string,
+  timeoutMs: number,
+): ForgeResult<T> {
+  if (run.missing) return failure("unavailable", `${bin} is not installed`, installHint(bin));
+  if (run.timedOut)
+    return failure("unavailable", `${bin} api ${what} timed out after ${timeoutMs} ms`);
+  const stderr = redactText(run.stderr).trim();
+  if (
+    /auth login|not logged in|no token|authentication required|bad credentials|\b401\b|unauthorized/iu.test(
+      stderr,
+    )
+  )
+    return failure(
+      "unavailable",
+      `${bin} is not authenticated for ${apiHost}`,
+      loginHint(bin, apiHost),
+    );
+  if (/\b404\b|not found/iu.test(stderr)) return failure("not_found", `${what} was not found`);
+  const first = stderr.split(/\r?\n/u).find((value) => value.trim()) ?? `exit ${run.status}`;
+  return failure("failed", `${bin} api ${what} failed: ${first.slice(0, 200)}`);
+}
+
+/** Run and parse a JSON response. */
+export function apiJson<T>(
+  runner: ForgeRunner,
+  bin: CliBin,
+  apiHost: string,
+  args: readonly string[],
+  what: string,
+  timeoutMs: number = FORGE_TIMEOUTS.api,
+  options: { graphql?: boolean } = {},
+): ForgeResult<T> {
+  const run = runner(bin, args, { timeoutMs });
+  if (run.status !== 0) {
+    // `gh api graphql` exits 1 on GraphQL errors but still prints the
+    // response; the caller reads its `errors` array.
+    if (options.graphql && !run.missing && !run.timedOut)
+      try {
+        const body = JSON.parse(run.stdout) as { errors?: unknown };
+        if (Array.isArray(body.errors)) return { ok: true, data: body as T };
+      } catch {
+        // fall through
+      }
+    return cliFailure(bin, apiHost, run, what, timeoutMs);
+  }
+  try {
+    return { ok: true, data: JSON.parse(run.stdout) as T };
+  } catch {
+    return failure("failed", `${bin} api ${what} returned invalid JSON`);
+  }
+}
+
+/** Run and return raw text (job logs). */
+export function apiText(
+  runner: ForgeRunner,
+  bin: CliBin,
+  apiHost: string,
+  args: readonly string[],
+  what: string,
+  timeoutMs: number = FORGE_TIMEOUTS.log,
+): ForgeResult<string> {
+  const run = runner(bin, args, { timeoutMs });
+  if (run.status !== 0) return cliFailure(bin, apiHost, run, what, timeoutMs);
+  return { ok: true, data: run.stdout };
+}
+
+/**
+ * A forge write (create, merge, retarget). Like apiJson, plus: an HTTP 409 or
+ * a head-moved/SHA-mismatch message is `blocked` (`head_moved`), and 405/406/
+ * 422 refusals are `blocked` with the forge's own reason, so a refused
+ * mutation never reads as a transient failure.
+ */
+export function apiWrite<T>(
+  runner: ForgeRunner,
+  bin: CliBin,
+  apiHost: string,
+  args: readonly string[],
+  what: string,
+  timeoutMs: number = FORGE_TIMEOUTS.api,
+): ForgeResult<T> {
+  const run = runner(bin, args, { timeoutMs });
+  if (run.status !== 0) {
+    const text = redactText(`${run.stderr}\n${run.stdout}`).trim();
+    const reason = (text.split(/\r?\n/u).find((value) => value.trim()) ?? "").slice(0, 200);
+    if (
+      !run.missing &&
+      !run.timedOut &&
+      /\b409\b|head branch was modified|sha does not match|sha.*mismatch/iu.test(text)
+    )
+      return failure(
+        "blocked",
+        `head_moved: ${what} refused because the head changed (${reason})`,
+        "workit pr status  # re-check the new head, then verify it again",
+      );
+    if (!run.missing && !run.timedOut && /\b(405|406|422)\b/u.test(text))
+      return failure("blocked", `${what} refused by the forge: ${reason}`);
+    return cliFailure(bin, apiHost, run, what, timeoutMs);
+  }
+  if (!run.stdout.trim()) return { ok: true, data: {} as T };
+  try {
+    return { ok: true, data: JSON.parse(run.stdout) as T };
+  } catch {
+    return failure("failed", `${bin} api ${what} returned invalid JSON`);
+  }
+}