@workit-dev/core 0.0.1 → 1.0.0

package/src/forge/issue-ops.ts

@@ -0,0 +1,314 @@
+// `workit issue view|comment|close|create` (#439, retro W2.11): issue writes
+// through Workit, so an agent never needs a raw `gh issue close` the host's
+// permission mode blocks.
+//
+// Where: `--repo` (another repository on this forge host), else the
+// workspace tracker (`issues.provider` github or gitlab, its `issues.repo`)
+// when it is on this checkout's forge host, else the forge's own base
+// repository. YouTrack and another host are refused: no account is
+// verified there. Every write needs the `pr` grant (the forge-write grant
+// `pr edit|reply` use) and leaves an `issue.*` ledger row.
+import { createHash } from "node:crypto";
+import { requireGrant } from "../autonomy";
+import { forgeTarget } from "../core/remotes";
+import { vcsConfig, type IssueTracker } from "../core/vcs-config";
+import { currentBranch, headSha } from "../git/rev";
+import { appendObserved, readLedger, type LedgerActor } from "../ledger";
+import {
+  githubIssues,
+  gitlabIssues,
+  type ForgeIssue,
+  type IssueApi,
+  type IssueCloseReason,
+} from "./issue-forge";
+import type { ResolvedForge } from "./resolve";
+import { failure, success, type ForgeErrorCode, type ForgeResult } from "./types";
+
+const same = (left: string, right: string): boolean => left.toLowerCase() === right.toLowerCase();
+
+function trackerOf(cwd: string): IssueTracker | null {
+  const resolved = vcsConfig("resolve", cwd);
+  if (resolved.ok === false) return null;
+  return (resolved.issue_tracker as IssueTracker | null | undefined) ?? null;
+}
+
+/** The issue API for this checkout: the workspace tracker's repository, else the forge's. */
+export function issueTarget(
+  cwd: string,
+  resolved: ResolvedForge,
+  options: { repo?: string | null; tracker?: IssueTracker | null } = {},
+): ForgeResult<IssueApi> {
+  const { kind, apiHost } = resolved.forge;
+  const make = (repo: string) => {
+    const api = { apiHost, repo, runner: resolved.runner };
+    return success(kind === "github" ? githubIssues(api) : gitlabIssues(api));
+  };
+  // `--repo`: another repository on this forge host, under the same verified account.
+  if (options.repo) {
+    // The owner has no dot, so a host (`gitlab.com/o/r`) is never read as one.
+    if (!/^[\w-]+(?:\/\w[\w.-]*)+$/u.test(options.repo))
+      return failure(
+        "invalid_input",
+        `--repo is owner/name or group/project on this forge host, without the host: not "${options.repo}"`,
+      );
+    return make(options.repo);
+  }
+  const tracker = options.tracker === undefined ? trackerOf(cwd) : options.tracker;
+  if (tracker?.provider === "youtrack")
+    return failure(
+      "blocked",
+      "issues.provider is youtrack: workit issue drives GitHub and GitLab issues",
+      "workit youtrack note <ID> --text <t>",
+    );
+  if (tracker && tracker.provider !== kind)
+    return failure(
+      "blocked",
+      `issues.provider is ${tracker.provider} but this checkout's forge is ${kind}: no account is verified there`,
+    );
+  if (tracker?.host && !same(tracker.host, apiHost))
+    return failure(
+      "blocked",
+      `issues.host ${tracker.host} is not this checkout's forge host ${apiHost}: no account is verified there`,
+    );
+  return make(tracker?.repo ?? resolved.forge.repo);
+}
+
+const grant = (cwd: string, api: IssueApi): ForgeResult<void> => {
+  const decision = requireGrant(cwd, "pr", {
+    target: forgeTarget(api.apiHost, api.repo),
+  });
+  return decision.allowed
+    ? success(undefined)
+    : failure("blocked", decision.error, decision.unblock);
+};
+
+export type Recorded = { id: string } | { error: string };
+
+const record = (
+  cwd: string,
+  api: IssueApi,
+  actor: LedgerActor,
+  row: Record<string, unknown> & { type: string },
+): Recorded => {
+  const written = appendObserved(cwd, {
+    ...row,
+    actor,
+    branch: currentBranch(cwd),
+    head: headSha(cwd),
+    forge: api.kind,
+    repo: api.repo,
+  });
+  return written.ok ? { id: String(written.value.id) } : { error: written.error };
+};
+
+/** The issue, refused when it is closed and the caller needs it open. */
+const openIssue = (api: IssueApi, n: number, alternative: string): ForgeResult<ForgeIssue> => {
+  const issue = api.view(n);
+  if (!issue.ok) return issue;
+  if (issue.data.state === "closed")
+    return failure("blocked", `closed: issue #${n} is closed`, alternative);
+  return issue;
+};
+
+/** Post a comment; its URL, or (GitLab) the issue URL with the note's anchor. */
+const postComment = (
+  api: IssueApi,
+  issue: ForgeIssue,
+  body: string,
+): ForgeResult<{ url: string | null }> => {
+  const posted = api.comment(issue.number, body);
+  if (!posted.ok) return posted;
+  const { url, id } = posted.data;
+  return success({ url: url ?? (issue.url && id ? `${issue.url}#note_${id}` : null) });
+};
+
+const bodyHash = (body: string): string =>
+  createHash("sha256").update(body.trim()).digest("hex").slice(0, 32);
+
+const recordComment = (
+  cwd: string,
+  api: IssueApi,
+  actor: LedgerActor,
+  issue: number,
+  body: string,
+  url: string | null,
+): Recorded =>
+  record(cwd, api, actor, { type: "issue.commented", issue, url, bodyHash: bodyHash(body) });
+
+/**
+ * The URL of the same comment this session already posted on the issue
+ * (an `issue.commented` row), so a retried close never posts it twice;
+ * undefined when there is none or the session is unknown.
+ */
+function postedBefore(
+  cwd: string,
+  api: IssueApi,
+  actor: LedgerActor,
+  issue: number,
+  body: string,
+): { url: string | null } | undefined {
+  if (!actor.session) return undefined;
+  const ledger = readLedger(cwd);
+  if (!ledger.ok) return undefined;
+  const hash = bodyHash(body);
+  const row = ledger.value.rows.findLast((candidate) => {
+    const value = candidate as unknown as Record<string, unknown>;
+    return (
+      value.type === "issue.commented" &&
+      value.forge === api.kind &&
+      value.repo === api.repo &&
+      value.issue === issue &&
+      value.bodyHash === hash &&
+      candidate.actor.session === actor.session
+    );
+  }) as unknown as Record<string, unknown> | undefined;
+  if (!row) return undefined;
+  return { url: typeof row.url === "string" ? row.url : null };
+}
+
+export type CommentOutcome = {
+  number: number;
+  url: string | null;
+  recorded: Recorded;
+};
+
+/**
+ * Comment on issue `n`. With `requireOpen` a closed issue is refused and
+ * that text is the unblock (the queue path: file a new issue instead).
+ */
+export function commentOnIssue(
+  cwd: string,
+  api: IssueApi,
+  input: {
+    number: number;
+    body: string;
+    actor: LedgerActor;
+    requireOpen?: string;
+  },
+): ForgeResult<CommentOutcome> {
+  const allowed = grant(cwd, api);
+  if (!allowed.ok) return allowed;
+  const issue =
+    input.requireOpen === undefined
+      ? api.view(input.number)
+      : openIssue(api, input.number, input.requireOpen);
+  if (!issue.ok) return issue;
+  const posted = postComment(api, issue.data, input.body);
+  if (!posted.ok) return posted;
+  const { url } = posted.data;
+  const recorded = recordComment(cwd, api, input.actor, input.number, input.body, url);
+  return success({ number: input.number, url, recorded });
+}
+
+export type CloseOutcome = {
+  number: number;
+  url: string | null;
+  reason: IssueCloseReason;
+  /** False when the issue was already closed: nothing was posted. */
+  changed: boolean;
+  commentUrl: string | null;
+  /** posted now, already posted by this session (a retry), or none asked. */
+  comment: "posted" | "already_posted" | "none";
+  recorded: Recorded | null;
+};
+
+/** Close issue `n` with a reason and an optional comment posted first; verified after. */
+export function closeIssue(
+  cwd: string,
+  api: IssueApi,
+  input: {
+    number: number;
+    reason: IssueCloseReason;
+    comment: string | null;
+    actor: LedgerActor;
+  },
+): ForgeResult<CloseOutcome> {
+  const allowed = grant(cwd, api);
+  if (!allowed.ok) return allowed;
+  const issue = api.view(input.number);
+  if (!issue.ok) return issue;
+  const base = {
+    number: input.number,
+    url: issue.data.url,
+    reason: input.reason,
+  };
+  if (issue.data.state === "closed")
+    return success({
+      ...base,
+      changed: false,
+      commentUrl: null,
+      comment: "none",
+      recorded: null,
+    });
+  let commentUrl: string | null = null;
+  let comment: CloseOutcome["comment"] = "none";
+  if (input.comment !== null) {
+    const before = postedBefore(cwd, api, input.actor, input.number, input.comment);
+    if (before) {
+      commentUrl = before.url;
+      comment = "already_posted";
+    } else {
+      const posted = postComment(api, issue.data, input.comment);
+      if (!posted.ok) return posted;
+      commentUrl = posted.data.url;
+      comment = "posted";
+      // Recorded at once: a failed close below must not lose it, and a retry reads it.
+      recordComment(cwd, api, input.actor, input.number, input.comment, commentUrl);
+    }
+  }
+  // After a posted comment, a failure says so and the retry needs no --comment.
+  const stillOpen = (code: ForgeErrorCode, error: string): ForgeResult<CloseOutcome> =>
+    comment === "none"
+      ? failure(code, error, `workit issue view ${input.number}`)
+      : failure(
+          code,
+          `${error}; the comment is posted${commentUrl ? ` (${commentUrl})` : ""} and issue #${input.number} is still open`,
+          `workit issue close ${input.number} --reason ${input.reason}  # no --comment: it is posted; or workit issue view ${input.number}`,
+        );
+  const closed = api.close(input.number, input.reason);
+  if (!closed.ok) return stillOpen(closed.code, closed.error);
+  const after = api.view(input.number);
+  if (!after.ok) return after;
+  if (after.data.state !== "closed")
+    return stillOpen(
+      "failed",
+      `close_unverified: the forge accepted the close but issue #${input.number} still reads open`,
+    );
+  const recorded = record(cwd, api, input.actor, {
+    type: "issue.closed",
+    issue: input.number,
+    url: issue.data.url,
+    reason: input.reason,
+    commentUrl,
+  });
+  return success({ ...base, changed: true, commentUrl, comment, recorded });
+}
+
+export type CreateOutcome = {
+  number: number;
+  url: string | null;
+  recorded: Recorded;
+};
+
+export function createIssue(
+  cwd: string,
+  api: IssueApi,
+  input: { title: string; body: string; labels: string[]; actor: LedgerActor },
+): ForgeResult<CreateOutcome> {
+  if (!input.title.trim()) return failure("invalid_input", "an issue needs a title");
+  const allowed = grant(cwd, api);
+  if (!allowed.ok) return allowed;
+  const created = api.create({
+    title: input.title,
+    body: input.body,
+    labels: input.labels,
+  });
+  if (!created.ok) return created;
+  const recorded = record(cwd, api, input.actor, {
+    type: "issue.created",
+    issue: created.data.number,
+    url: created.data.url,
+    labels: input.labels,
+  });
+  return success({ ...created.data, recorded });
+}

package/src/forge/merge-gate-base-red.ts

@@ -0,0 +1,72 @@
+import type { ResolvedForge } from "./resolve";
+import { failure, type ForgeCheck, type ForgeResult, type RefChecks } from "./types";
+
+/**
+ * Why the base is red, judged against the run before it: `flaky` when every
+ * failing check passed on the previous base commit, `broken` when one of them
+ * failed there too, `unknown` when the previous run could not tell.
+ */
+export type BaseRedCause =
+  | { kind: "flaky"; checks: ForgeCheck[] }
+  | { kind: "broken"; checks: ForgeCheck[] }
+  | { kind: "unknown"; note: string };
+
+export function classifyBaseRed(
+  failing: readonly ForgeCheck[],
+  previous: ForgeResult<RefChecks>,
+): BaseRedCause {
+  if (!previous.ok)
+    return { kind: "unknown", note: `the previous run could not be read (${previous.error})` };
+  const before = new Map(previous.data.checks.map((check) => [check.name, check.state]));
+  const broken = failing.filter((check) => before.get(check.name) === "failing");
+  if (broken.length) return { kind: "broken", checks: broken };
+  if (failing.every((check) => before.get(check.name) === "passing"))
+    return { kind: "flaky", checks: [...failing] };
+  return {
+    kind: "unknown",
+    note: "the previous run did not report every failing check, so a flake cannot be told apart",
+  };
+}
+
+/**
+ * The checks of the base commit before the head (`<base>~1`), the previous
+ * run on a squash-merged base. GitHub resolves the revision expression; GitLab
+ * reads pipelines by branch name only, so it reports no previous run.
+ */
+export function previousBaseChecks(resolved: ResolvedForge, base: string): ForgeResult<RefChecks> {
+  if (resolved.forge.kind !== "github")
+    return failure("unavailable", `${resolved.forge.kind} has no previous-run read`);
+  // Advisory only: a read that throws must never change the base_red refusal.
+  try {
+    return resolved.forge.branchChecks(`${base}~1`);
+  } catch (error) {
+    return failure("failed", `the previous ${base} run read threw (${String(error)})`);
+  }
+}
+
+const quote = (name: string): string => `"${name.replaceAll('"', '\\"')}"`;
+
+const named = (checks: readonly ForgeCheck[]): string =>
+  checks.map((check) => (check.url ? `${check.name} (${check.url})` : check.name)).join(", ");
+
+/** The sentence the refusal adds and the next step it hands the lead. */
+export function baseRedNextStep(
+  base: string,
+  cause: BaseRedCause,
+  override: string,
+): { detail: string; unblock: string } {
+  if (cause.kind === "flaky")
+    return {
+      detail: `likely flaky: ${named(cause.checks)} passed on the previous ${base} run`,
+      unblock: `workit ci rerun --ref ${base} ${cause.checks.map((check) => `--check ${quote(check.name)}`).join(" ")} --reason flake  # then merge once ${base} is green`,
+    };
+  if (cause.kind === "broken")
+    return {
+      detail: `${base} is broken: ${named(cause.checks)} also failed on the previous ${base} run, so a rerun will not help`,
+      unblock: `fix ${base} first; or, if the user accepts it: ${override}`,
+    };
+  return {
+    detail: `flake or not is unknown: ${cause.note}`,
+    unblock: `workit ci rerun --ref ${base} --failed --reason flake  # a flake on ${base}: merge once it is green; a real failure: fix ${base} first, or, if the user accepts it: ${override}`,
+  };
+}

package/src/forge/pr-body.ts

@@ -0,0 +1,100 @@
+// PR/MR body issue linking (port of scripts/pr-create.sh --build-body), shared
+// by the managed `hosting.pull_request` action (core/pr-create.ts re-exports
+// these until S16) and `workit pr create` (S11), which passes typed input
+// instead of environment variables.
+import { vcsConfig } from "../core/vcs-config";
+
+export 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;
+}
+
+export 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.
+export 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 "";
+}
+
+/** A YouTrack id in the branch (feature/IRPT-740-x); anchored, 3+ digits so POSTGRES-16 or HTTP-3 never link. */
+export function deriveYouTrackIssueFromBranch(branch: string): string {
+  return /(?:^|\/|-)([A-Z]{2,}-\d{3,})\b/.exec(branch)?.[1] ?? "";
+}
+
+export 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) {
+    const issue = ytIssue || deriveYouTrackIssueFromBranch(branch);
+    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;
+}
+
+/**
+ * The body `workit pr create` sends: the agent's text plus the workspace's
+ * issue link (YouTrack `link_issues`, or GitHub `issues.link_on_pr` with the
+ * issue number derived from the branch). Reads config, never writes it.
+ */
+export function prBodyFor(
+  cwd: string,
+  input: { body: string; branch: string; repo: string | null },
+): string {
+  const resolved = vcsConfig("resolve", cwd);
+  if (resolved.ok === false) return input.body;
+  return buildBody(
+    input.body,
+    input.branch,
+    resolved.link_issues === true,
+    typeof resolved.youtrack_base_url === "string" ? resolved.youtrack_base_url : "",
+    "",
+    resolved.link_on_pr === true,
+    "",
+    "closes",
+    input.repo,
+  );
+}