@brainervirus/workit-core 2.3.0 → 2.5.0

package/src/forge/reruns.ts

@@ -0,0 +1,127 @@
+// The rerun-once record (design §2.1 `ci rerun`): one row per check rerun on
+// a given PR head, so a second rerun of the same check on the same head needs
+// `--force`. Rows use the ledger row shape (`type: "ci.rerun"`) so S13 can
+// fold this file into `ledger.jsonl`.
+//
+// It lives in the git common dir (`<common>/workit/ci-reruns.jsonl`, design
+// §0 #5) so every worktree of the repository shares it and `git clean` does
+// not drop it. Append-only; unreadable lines are skipped.
+import fs from "node:fs";
+import path from "node:path";
+import { gitCommonDir } from "../git/rev";
+
+export type RerunRow = {
+  v: 1;
+  at: string;
+  type: "ci.rerun";
+  forge: string;
+  repo: string;
+  pr: number;
+  head: string;
+  check: string;
+  reason: string;
+  forced: boolean;
+};
+
+export function rerunLogPath(cwd: string): string | null {
+  const common = gitCommonDir(cwd);
+  return common ? path.join(common, "workit", "ci-reruns.jsonl") : null;
+}
+
+const isRow = (value: unknown): value is RerunRow => {
+  const row = value as Partial<RerunRow> | null;
+  return (
+    !!row &&
+    row.type === "ci.rerun" &&
+    typeof row.pr === "number" &&
+    typeof row.head === "string" &&
+    typeof row.check === "string" &&
+    typeof row.repo === "string"
+  );
+};
+
+/** How often each check was rerun on `head` of PR `pr` in `repo`. */
+export function rerunCounts(
+  cwd: string,
+  key: { repo: string; pr: number; head: string },
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  const file = rerunLogPath(cwd);
+  if (!file) return counts;
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return counts;
+  }
+  for (const raw of text.split("\n")) {
+    if (!raw.trim()) continue;
+    let row: unknown;
+    try {
+      row = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (isRow(row) && row.repo === key.repo && row.pr === key.pr && row.head === key.head)
+      counts.set(row.check, (counts.get(row.check) ?? 0) + 1);
+  }
+  return counts;
+}
+
+/** Append rows (one write, O_APPEND). Returns false when the file cannot be written. */
+export function recordReruns(cwd: string, rows: readonly RerunRow[]): boolean {
+  if (rows.length === 0) return true;
+  const file = rerunLogPath(cwd);
+  if (!file) return false;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, rows.map((row) => `${JSON.stringify(row)}\n`).join(""));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const LOCK_WAIT_MS = 2_000;
+const LOCK_STALE_MS = 60_000;
+
+const pause = (ms: number): void => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
+/**
+ * Run `fn` holding `<common>/workit/ci-reruns.lock` (atomic create). Two
+ * concurrent `ci rerun`s therefore cannot both pass the once-per-head check.
+ * A lock older than a minute is from a dead process and is taken over.
+ * Null when the lock stays held past the wait (the caller reports busy).
+ */
+export function withRerunLock<T>(cwd: string, fn: () => T): T | null {
+  const file = rerunLogPath(cwd);
+  if (!file) return fn();
+  const lock = `${file.slice(0, -".jsonl".length)}.lock`;
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+  const until = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      fs.closeSync(fs.openSync(lock, "wx"));
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - fs.statSync(lock).mtimeMs > LOCK_STALE_MS) {
+          fs.rmSync(lock, { force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() >= until) return null;
+      pause(50);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    fs.rmSync(lock, { force: true });
+  }
+}

package/src/forge/resolve.ts

@@ -0,0 +1,240 @@
+// Which forge, which repositories, and which credential (D16, design §0 #6,
+// §2.0 Identity).
+//
+// - The push remote host decides GitHub vs GitLab. A workspace provider that
+//   disagrees is `blocked`, never silently overridden.
+// - PRs/MRs live in the base repository: an `upstream` remote on the same
+//   forge, else the push repo's fork parent, else the push repo itself.
+// - Every API call carries the workspace's credential explicitly, so the
+//   machine-wide active gh/glab account is never switched or relied on:
+//   the workspace `vcs.tokenFile`, else (GitHub) `gh auth token --user
+//   <vcs.account>`, else the CLI's default login. The token is never printed.
+// Config is read, never written.
+import fs from "node:fs";
+import { readVcsConfig } from "../core/vcs-config";
+import { resolveRuntimeWorkspaceVcs } from "../core/workspaces";
+import {
+  deriveForge,
+  forgeConflict,
+  pushForge,
+  pushUrl,
+  remoteNames,
+  type DerivedForge,
+  type ForgeHosts,
+  type SshConfig,
+} from "../git/rev";
+import { FORGE_TIMEOUTS, systemRunner, type ForgeRunner } from "./exec";
+import { createGitHubForge } from "./github";
+import { createGitLabForge } from "./gitlab";
+import { failure, success, type Forge, type ForgeResult, type Identity } from "./types";
+
+export type CredentialSource = "workspace_token_file" | "gh_account_token" | "cli_login";
+
+export type ResolvedForge = {
+  /** Bound to the base repository (where the PR/MR lives). */
+  forge: Forge;
+  /** Push remote name. */
+  remote: string;
+  /** Redacted push URL. */
+  url: string;
+  derived: DerivedForge;
+  workspace: string | null;
+  /** The workspace `vcs.account`, when configured. */
+  expectedAccount: string | null;
+  credential: CredentialSource;
+  /** The push (head) repository; differs from forge.repo for a fork. */
+  headRepo: string;
+  /** GitLab project id of the push repository (MR source project). */
+  headProjectId: number | null;
+  fork: boolean;
+  /** Remote to fetch base commits from (the base repo's remote when one exists). */
+  baseRemote: string;
+  /** Absolute deadline (ms, `now()` clock) every API call is clamped to; null = none. */
+  limits: { deadline: number | null };
+};
+
+export type ResolveOptions = {
+  branch?: string | null;
+  env?: NodeJS.ProcessEnv;
+  /** Replaces the real gh/glab (tests replay recorded API fixtures). */
+  runner?: ForgeRunner;
+  /** Clock for the deadline (tests use a virtual one). */
+  now?: () => number;
+  /** ssh_config for Host aliases (default: the user's ~/.ssh/config). */
+  sshConfig?: string | SshConfig;
+};
+
+const configuredHosts = (): ForgeHosts => {
+  const vcs = readVcsConfig();
+  if (vcs.status !== "valid") return {};
+  const host = (kind: "github" | "gitlab"): string[] => {
+    const value = (vcs.config[kind] as { host?: unknown } | undefined)?.host;
+    return typeof value === "string" && value.trim() ? [value.trim()] : [];
+  };
+  return { github: host("github"), gitlab: host("gitlab") };
+};
+
+const createForge = (derived: DerivedForge, repo: string, runner: ForgeRunner): Forge =>
+  derived.kind === "github"
+    ? createGitHubForge({ apiHost: derived.apiHost, repo, runner })
+    : createGitLabForge({ apiHost: derived.apiHost, repo, runner });
+
+export function resolveForge(
+  cwd: string,
+  options: ResolveOptions = {},
+): ForgeResult<ResolvedForge> {
+  let workspace: ReturnType<typeof resolveRuntimeWorkspaceVcs>;
+  try {
+    workspace = resolveRuntimeWorkspaceVcs(cwd);
+  } catch (error) {
+    return failure(
+      "blocked",
+      error instanceof Error ? error.message : String(error),
+      "fix ~/.config/workit/workspaces.json (workit init → Workspaces)",
+    );
+  }
+  const hosts = configuredHosts();
+  const pushed = pushForge(cwd, { branch: options.branch, hosts, sshConfig: options.sshConfig });
+  if (!pushed.ok) return failure(pushed.code, pushed.error, pushed.unblock);
+  const conflict = forgeConflict(pushed.forge, workspace?.vcs?.provider);
+  if (conflict) return failure("blocked", conflict.error, conflict.unblock);
+  const derived = pushed.forge;
+  const { kind, apiHost } = derived;
+  const base = options.runner ?? systemRunner(kind, apiHost, options.env ?? process.env);
+  const now = options.now ?? Date.now;
+  const expectedAccount = workspace?.vcs?.account ?? null;
+
+  // The credential for every call.
+  let token: string | undefined;
+  let credential: CredentialSource = "cli_login";
+  const tokenFile = (workspace?.vcs as { tokenFile?: unknown } | undefined)?.tokenFile;
+  if (typeof tokenFile === "string" && tokenFile.trim()) {
+    // A stored token goes only to the host it is for: the public forge (also
+    // reached through an ~/.ssh/config alias) or a host configured
+    // explicitly (vcs.json github.host/gitlab.host, workspace vcs.host).
+    // A host merely *named* like a forge (github.evil.com) never gets it.
+    const workspaceHost = (workspace?.vcs as { host?: unknown } | undefined)?.host;
+    const explicit =
+      typeof workspaceHost === "string" &&
+      workspaceHost
+        .trim()
+        .toLowerCase()
+        .replace(/^https?:\/\//u, "")
+        .replace(/\/.*$/u, "") === apiHost;
+    if (derived.via === "host_name" && !explicit)
+      return failure(
+        "blocked",
+        `token_host_unverified: push host ${derived.host} only looks like ${kind}; workspace ${workspace?.name ?? "?"} vcs.tokenFile is not sent to it`,
+        `if ${apiHost} is your ${kind} server, set ${kind}.host in ~/.config/workit/vcs.json (or vcs.host for the workspace); otherwise fix the push remote`,
+      );
+    try {
+      token = fs.readFileSync(tokenFile.trim(), "utf8").trim();
+    } catch {
+      return failure(
+        "blocked",
+        `workspace ${workspace?.name ?? "?"} vcs.tokenFile cannot be read`,
+        "fix vcs.tokenFile in ~/.config/workit/workspaces.json",
+      );
+    }
+    if (!token)
+      return failure(
+        "blocked",
+        `workspace ${workspace?.name ?? "?"} vcs.tokenFile is empty`,
+        "fix vcs.tokenFile in ~/.config/workit/workspaces.json",
+      );
+    credential = "workspace_token_file";
+  } else if (expectedAccount && kind === "github") {
+    const issued = base("gh", ["auth", "token", "--hostname", apiHost, "--user", expectedAccount], {
+      timeoutMs: FORGE_TIMEOUTS.api,
+    });
+    if (issued.missing)
+      return failure(
+        "unavailable",
+        "gh is not installed",
+        "install the GitHub CLI (https://cli.github.com) and run: gh auth login",
+      );
+    token = issued.status === 0 ? issued.stdout.trim() : "";
+    if (!token)
+      return failure(
+        "blocked",
+        `identity_unavailable: gh has no login for ${expectedAccount} on ${apiHost} (workspace ${workspace?.name ?? "?"})`,
+        `gh auth login --hostname ${apiHost}  # sign in as ${expectedAccount}; workit passes that account's token per call and never switches the active account`,
+      );
+    credential = "gh_account_token";
+  }
+
+  const limits: { deadline: number | null } = { deadline: null };
+  const runner: ForgeRunner = (bin, args, callOptions) => {
+    let timeoutMs = callOptions.timeoutMs;
+    if (limits.deadline !== null) {
+      const remaining = limits.deadline - now();
+      if (remaining <= 0)
+        return { status: null, stdout: "", stderr: "", timedOut: true, missing: false };
+      timeoutMs = Math.min(timeoutMs, remaining);
+    }
+    return base(bin, args, { ...callOptions, timeoutMs, ...(token ? { token } : {}) });
+  };
+
+  // Base repository: an `upstream` remote on the same forge, else the fork parent.
+  const headRepo = derived.repo;
+  const probe = createForge(derived, headRepo, runner);
+  const info = probe.repoInfo(headRepo);
+  if (!info.ok && info.code !== "not_found") return info;
+  const headProjectId = info.ok ? info.data.id : null;
+  const remotes = remoteNames(cwd);
+  const repoOfRemote = (name: string): string | null => {
+    const url = pushUrl(cwd, name);
+    const other = url ? deriveForge(url, { hosts, sshConfig: options.sshConfig }) : null;
+    return other && other.kind === kind && other.apiHost === apiHost ? other.repo : null;
+  };
+  const upstream =
+    pushed.remote !== "upstream" && remotes.includes("upstream") ? repoOfRemote("upstream") : null;
+  const baseRepo =
+    upstream && upstream !== headRepo
+      ? upstream
+      : info.ok && info.data.parent
+        ? info.data.parent
+        : headRepo;
+  const baseRemote =
+    baseRepo === headRepo
+      ? pushed.remote
+      : (remotes.find((name) => repoOfRemote(name) === baseRepo) ?? pushed.remote);
+
+  return success({
+    forge: baseRepo === headRepo ? probe : createForge(derived, baseRepo, runner),
+    remote: pushed.remote,
+    url: pushed.url,
+    derived,
+    workspace: workspace?.name ?? null,
+    expectedAccount,
+    credential,
+    headRepo,
+    headProjectId,
+    fork: baseRepo !== headRepo,
+    baseRemote,
+    limits,
+  });
+}
+
+/**
+ * The credential in use must belong to the workspace account. A mismatch is
+ * `blocked` with the fix (never a global account switch); no configured
+ * account passes; a credential that cannot read /user passes with a note.
+ */
+export function checkIdentity(resolved: ResolvedForge): ForgeResult<Identity> {
+  const { forge, expectedAccount } = resolved;
+  const identity = forge.identity(expectedAccount);
+  if (!identity.ok) return identity;
+  if (identity.data.matches === false) {
+    const bin = forge.kind === "github" ? "gh" : "glab";
+    const where = `workspace ${resolved.workspace ?? "?"}`;
+    return failure(
+      "blocked",
+      `identity_mismatch: the ${resolved.credential === "workspace_token_file" ? "vcs.tokenFile token" : `${bin} login`} is ${identity.data.login} but ${where} expects ${expectedAccount}`,
+      resolved.credential === "workspace_token_file"
+        ? `put a token for ${expectedAccount} in the ${where} vcs.tokenFile`
+        : `${bin} auth login --hostname ${forge.apiHost}  # sign in as ${expectedAccount}`,
+    );
+  }
+  return identity;
+}

package/src/forge/types.ts

@@ -0,0 +1,166 @@
+// Forge-neutral shapes for the GitHub and GitLab adapters (design §2.0, S10).
+// Plain TS: the CLI verbs load this on their path.
+import type { ForgeKind } from "../git/rev";
+
+export type { ForgeKind };
+
+export type ForgeErrorCode =
+  | "unavailable"
+  | "not_found"
+  | "failed"
+  | "blocked"
+  | "busy"
+  | "invalid_input";
+
+export type ForgeResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; code: ForgeErrorCode; error: string; unblock?: string };
+
+export const success = <T>(data: T): ForgeResult<T> => ({ ok: true, data });
+
+export const failure = <T = never>(
+  code: ForgeErrorCode,
+  error: string,
+  unblock?: string,
+): ForgeResult<T> => ({ ok: false, code, error, ...(unblock ? { unblock } : {}) });
+
+export type PrState = "open" | "closed" | "merged";
+
+export type PrRef = {
+  number: number;
+  url: string;
+  state: PrState;
+  headBranch: string;
+  headSha: string | null;
+};
+
+/** How a branch-name lookup proves a PR is ours (M5): head owner/project or head sha. */
+export type PrMatch = {
+  /** GitHub: the head repository owner (the push repo's owner). */
+  owner: string | null;
+  /** GitLab: the source project id (the push project). */
+  projectId: number | null;
+  /** A PR whose head is exactly this commit is ours whatever its owner. */
+  sha: string | null;
+};
+
+/** One CI check (GitHub check run / commit status, GitLab job or bridge). */
+export type ForgeCheck = {
+  /** `<workflow> / <job>` on GitHub, `<stage> / <job>` on GitLab, or the status context. */
+  name: string;
+  /** The raw context/job name branch protection refers to. */
+  context: string;
+  state: "failing" | "pending" | "passing" | "skipped";
+  /** The forge's own verdict, lower-cased (failure, timed_out, failed, canceled…). */
+  conclusion: string | null;
+  url: string | null;
+  /** GitHub workflow run id / GitLab pipeline id. */
+  runId: number | null;
+  /** GitHub Actions job id / GitLab job id; null for external statuses and bridges. */
+  jobId: number | null;
+  /** GitLab: the project that owns the pipeline (forks run elsewhere). */
+  scope: string | null;
+  /** Required by branch protection (GitHub isRequired); null when the forge cannot say. */
+  required: boolean | null;
+};
+
+export type ForgeThread = {
+  id: string;
+  path: string | null;
+  line: number | null;
+  author: string | null;
+  isBot: boolean;
+  outdated: boolean;
+  url: string | null;
+  /** First comment, redacted and cut to 300 chars. Untrusted data. */
+  body: string;
+};
+
+export type ForgePrStatus = {
+  number: number;
+  url: string;
+  state: PrState;
+  draft: boolean;
+  base: string;
+  /** The current tip of the base branch, from the API. */
+  baseSha: string | null;
+  head: { branch: string; sha: string };
+  mergeable: "yes" | "no" | "unknown";
+  conflicts: boolean;
+  /** Branch protection requires the head to be up to date and it is not. */
+  rebaseRequired: boolean;
+  /** approved | changes_requested | review_required | null. */
+  reviewDecision: string | null;
+  /** GitHub mergeStateStatus / GitLab detailed_merge_status, lower-cased. */
+  mergeState: string | null;
+  inMergeQueue: boolean;
+  checks: ForgeCheck[];
+  /**
+   * Contexts branch protection requires (GitHub branch protection +
+   * rulesets); null when they could not be read.
+   */
+  requiredContexts: string[] | null;
+  threads: ForgeThread[];
+  /** True when a list was cut at the page cap (the counts are lower bounds). */
+  truncated: boolean;
+};
+
+export type JobRef = { jobId: number; scope: string | null };
+
+export type RerunTarget =
+  | { kind: "failed_in_run"; runId: number; scope: string | null }
+  | { kind: "job"; jobId: number; scope: string | null };
+
+export type Identity = {
+  login: string | null;
+  expected: string | null;
+  matches: boolean | null;
+  /** Why the login could not be checked (e.g. an app token without /user). */
+  note?: string;
+};
+
+export type MergeMethod = "squash" | "merge" | "rebase";
+
+/** What `workit pr create` asks the forge for (S11). */
+export type CreatePrInput = {
+  /** Source branch in the push (head) repository. */
+  head: string;
+  /** owner/name (GitHub) or group/project (GitLab) of the push repository. */
+  headRepo: string;
+  /** GitLab: the push project id (MRs from a fork are opened from it). */
+  headProjectId: number | null;
+  base: string;
+  title: string;
+  body: string;
+  draft: boolean;
+};
+
+export type MergeResult = {
+  /** The merge (or squash/rebase tip) commit the forge reported, when it did. */
+  mergeSha: string | null;
+};
+
+/** A repository as the forge sees it: id and the repo it was forked from. */
+export type RepoInfo = { id: number | null; parent: string | null };
+
+export interface Forge {
+  kind: ForgeKind;
+  apiHost: string;
+  /** The base repository PRs/MRs live in. */
+  repo: string;
+  identity(expected: string | null): ForgeResult<Identity>;
+  repoInfo(repo: string): ForgeResult<RepoInfo>;
+  findPr(head: string, match: PrMatch): ForgeResult<PrRef | null>;
+  prStatus(n: number): ForgeResult<ForgePrStatus>;
+  jobLogTail(job: JobRef, lines: number): ForgeResult<string[]>;
+  rerun(target: RerunTarget): ForgeResult<void>;
+  /** Open a PR/MR; `headSha` is the head the forge reports right after creation. */
+  createPr(input: CreatePrInput): ForgeResult<PrRef>;
+  /**
+   * Merge with the head guard: the forge refuses (`blocked`, head_moved) when
+   * the PR head is no longer `sha`.
+   */
+  merge(n: number, options: { sha: string; method: MergeMethod }): ForgeResult<MergeResult>;
+  /** Retarget a PR/MR to another base branch (S12 stacks). */
+  updateBase(n: number, base: string): ForgeResult<void>;
+}