@workit-dev/core 0.0.1 → 1.0.0

package/src/forge/gitlab.ts

@@ -0,0 +1,906 @@
+// GitLab adapter: `glab api` REST only (design §2.0 GitLab endpoints): the MR
+// (`detailed_merge_status`, `has_conflicts`, `head_pipeline`), pipeline jobs,
+// job traces, discussions, and pipeline/job retry.
+import { apiJson, apiText, apiWrite, FORGE_TIMEOUTS, type ForgeRunner } from "./exec";
+import { logTail, redactText, shortBody } from "./redact";
+import {
+  failure,
+  success,
+  type Forge,
+  type ForgeCheck,
+  type ForgePrStatus,
+  type ForgeResult,
+  type ForgeThread,
+  type PrMeta,
+  type PrState,
+} from "./types";
+
+/** Page cap for jobs and discussions (100 per page). */
+export const GITLAB_MAX_PAGES = 10;
+const PER_PAGE = 100;
+/** Merge requests per findPr page (paged until a short page). */
+const FIND_PER_PAGE = 20;
+
+type GlUser = { username?: string; bot?: boolean } | null;
+
+type GlMr = {
+  iid: number;
+  title?: string;
+  reviewers?: Array<{ id: number }>;
+  web_url: string;
+  state: string;
+  draft?: boolean;
+  work_in_progress?: boolean;
+  detailed_merge_status?: string;
+  has_conflicts?: boolean;
+  target_branch: string;
+  source_branch: string;
+  sha: string;
+  diff_refs?: { base_sha?: string | null } | null;
+  source_project_id?: number;
+  target_project_id?: number;
+  author?: { username?: string } | null;
+  head_pipeline?: {
+    id: number;
+    sha: string;
+    /** Merged-results / merge-train pipelines run on a merge ref; this is the MR head. */
+    source_sha?: string | null;
+    /** `refs/merge-requests/<iid>/merge` (merged results) or `/train` (merge train). */
+    ref?: string;
+    project_id: number;
+    status: string;
+    web_url?: string;
+  } | null;
+};
+
+type GlBridge = {
+  id: number;
+  name: string;
+  stage: string;
+  status: string;
+  allow_failure?: boolean;
+  web_url?: string;
+  downstream_pipeline?: {
+    id: number;
+    status: string;
+    project_id?: number;
+    web_url?: string;
+  } | null;
+};
+
+type GlJob = {
+  id: number;
+  name: string;
+  stage: string;
+  status: string;
+  allow_failure?: boolean;
+  web_url?: string;
+};
+
+type GlNote = {
+  id: number;
+  body: string;
+  author: GlUser;
+  system?: boolean;
+  resolvable?: boolean;
+  resolved?: boolean;
+  position?: {
+    new_path?: string | null;
+    new_line?: number | null;
+    old_path?: string | null;
+  } | null;
+};
+
+type GlDiscussion = { id: string; notes: GlNote[] };
+
+const mrState = (value: string): PrState =>
+  value === "merged" ? "merged" : value === "opened" ? "open" : "closed";
+
+const PENDING = new Set([
+  "created",
+  "pending",
+  "running",
+  "waiting_for_resource",
+  "waiting_for_callback",
+  "preparing",
+  "scheduled",
+]);
+
+const stateOf = (status: string, allowFailure: boolean): ForgeCheck["state"] => {
+  const failed = status === "failed" || status === "canceled";
+  return PENDING.has(status)
+    ? "pending"
+    : failed
+      ? allowFailure
+        ? "passing"
+        : "failing"
+      : status === "success"
+        ? "passing"
+        : "skipped";
+};
+
+/** A trigger/bridge job: its state is the downstream pipeline's. */
+export function checkFromBridge(bridge: GlBridge, pipelineId: number, scope: string): ForgeCheck {
+  const status = bridge.downstream_pipeline?.status ?? bridge.status;
+  const allow = bridge.allow_failure === true;
+  const failed = status === "failed" || status === "canceled";
+  return {
+    name: `${bridge.stage} / ${bridge.name}`,
+    context: bridge.name,
+    state: stateOf(status, allow),
+    conclusion: failed && allow ? "allowed_failure" : `downstream_${status}`,
+    url: safeUrl(bridge.downstream_pipeline?.web_url ?? bridge.web_url ?? null),
+    runId: pipelineId,
+    // Not a log-bearing job; rerun it on the downstream pipeline.
+    jobId: null,
+    scope,
+    required: !allow,
+  };
+}
+
+export function checkFromJob(job: GlJob, pipelineId: number, scope: string): ForgeCheck {
+  const failed = job.status === "failed" || job.status === "canceled";
+  return {
+    name: `${job.stage} / ${job.name}`,
+    context: job.name,
+    state: stateOf(job.status, job.allow_failure === true),
+    conclusion: failed && job.allow_failure ? "allowed_failure" : job.status,
+    url: safeUrl(job.web_url ?? null),
+    runId: pipelineId,
+    jobId: job.id,
+    scope,
+    // Every job that may not fail gates the pipeline, which gates the MR.
+    required: job.allow_failure !== true,
+  };
+}
+
+/** A pipeline-level check when no job explains the pipeline's state. */
+const pipelineCheck = (
+  state: ForgeCheck["state"],
+  conclusion: string,
+  pipeline: { id: number; project_id: number; web_url?: string } | null,
+): ForgeCheck => ({
+  name: "pipeline",
+  context: "pipeline",
+  state,
+  conclusion,
+  url: safeUrl(pipeline?.web_url ?? null),
+  runId: pipeline?.id ?? null,
+  jobId: null,
+  scope: pipeline ? String(pipeline.project_id) : null,
+  required: true,
+});
+
+const safeUrl = (value: string | null): string | null => (value ? redactText(value) : null);
+
+const isBot = (author: GlUser): boolean =>
+  author?.bot === true || /(?:^project_\d+_bot|bot$|\[bot\]$)/iu.test(author?.username ?? "");
+
+/** GitLab's draft markers at the start of an MR title. */
+const DRAFT_PREFIX = /^(?:\s*(?:\[draft\]|\(draft\)|draft:)\s*)+/iu;
+
+/**
+ * `title` with GitLab's draft markers (`Draft:`, `[Draft]`, `(Draft)`,
+ * repeated) replaced by one `Draft: ` or removed (GitLab keeps draft in the
+ * title). Null when nothing but markers is left.
+ */
+const draftTitle = (title: string, draft: boolean): string | null => {
+  const bare = title.replace(DRAFT_PREFIX, "").trim();
+  if (!bare) return null;
+  return draft ? `Draft: ${bare}` : bare;
+};
+
+// Statuses where GitLab has not finished computing mergeability.
+const UNSETTLED = new Set(["checking", "unchecked", "preparing", "approvals_syncing"]);
+
+export function createGitLabForge(options: {
+  apiHost: string;
+  repo: string;
+  runner: ForgeRunner;
+  maxPages?: number;
+}): Forge {
+  const { apiHost, repo, runner } = options;
+  const maxPages = options.maxPages ?? GITLAB_MAX_PAGES;
+  const project = `projects/${encodeURIComponent(repo)}`;
+
+  const api = (endpoint: string): string[] => ["api", endpoint];
+
+  /** Every page of a list endpoint, up to the cap. */
+  const pages = (
+    endpoint: string,
+    what: string,
+  ): ForgeResult<{ items: unknown[]; truncated: boolean }> => {
+    const items: unknown[] = [];
+    const sep = endpoint.includes("?") ? "&" : "?";
+    for (let page = 1; page <= maxPages; page += 1) {
+      const chunk = apiJson<unknown>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${endpoint}${sep}per_page=${PER_PAGE}&page=${page}`),
+        what,
+      );
+      if (!chunk.ok) return chunk;
+      if (!Array.isArray(chunk.data)) return failure("failed", `${what}: expected a list`);
+      items.push(...chunk.data);
+      if (chunk.data.length < PER_PAGE) return success({ items, truncated: false });
+    }
+    return success({ items, truncated: true });
+  };
+
+  /** True when merge commit `sha` (in project `scope`) has `head` as a parent. */
+  const mergeCommitTests = (scope: number, sha: string, head: string): boolean => {
+    const commit = apiJson<{ parent_ids?: string[] }>(
+      runner,
+      "glab",
+      apiHost,
+      api(`projects/${scope}/repository/commits/${sha}`),
+      `commit ${sha.slice(0, 12)}`,
+    );
+    return (
+      commit.ok && Array.isArray(commit.data.parent_ids) && commit.data.parent_ids.includes(head)
+    );
+  };
+
+  /** The current tip of the target branch (diff_refs.base_sha is the merge base). */
+  const baseTip = (branch: string): string | null => {
+    const tip = apiJson<{ commit?: { id?: string } }>(
+      runner,
+      "glab",
+      apiHost,
+      api(`${project}/repository/branches/${encodeURIComponent(branch)}`),
+      `branch ${branch}`,
+    );
+    return tip.ok && typeof tip.data.commit?.id === "string" ? tip.data.commit.id : null;
+  };
+
+  const getMr = (iid: number): ForgeResult<GlMr> =>
+    apiJson<GlMr>(
+      runner,
+      "glab",
+      apiHost,
+      api(`${project}/merge_requests/${iid}`),
+      `merge request !${iid}`,
+    );
+
+  const putMr = (iid: number, fields: string[], what: string): ForgeResult<void> => {
+    const updated = apiWrite<unknown>(
+      runner,
+      "glab",
+      apiHost,
+      ["api", "-X", "PUT", `${project}/merge_requests/${iid}`, ...fields],
+      `${what} of merge request !${iid}`,
+    );
+    return updated.ok ? success(undefined) : updated;
+  };
+
+  return {
+    kind: "gitlab",
+    apiHost,
+    repo,
+
+    identity(expected) {
+      const user = apiJson<{ username?: unknown }>(runner, "glab", apiHost, api("user"), "user");
+      // CI job tokens cannot read /user; reads still work, so skip the check.
+      if (!user.ok && user.code === "failed" && /\b403\b|forbidden/iu.test(user.error))
+        return success({
+          login: null,
+          expected,
+          matches: null,
+          note: "the credential cannot read /user (job or project token); identity not checked",
+        });
+      if (!user.ok) return user;
+      const login = typeof user.data.username === "string" ? user.data.username : "";
+      if (!login) return failure("failed", "glab api user returned no username");
+      return success({
+        login,
+        expected,
+        matches: expected ? login.toLowerCase() === expected.toLowerCase() : null,
+      });
+    },
+
+    repoInfo(target) {
+      const info = apiJson<{ id?: number; forked_from_project?: { path_with_namespace?: string } }>(
+        runner,
+        "glab",
+        apiHost,
+        api(`projects/${encodeURIComponent(target)}`),
+        `project ${target}`,
+      );
+      if (!info.ok) return info;
+      return success({
+        id: typeof info.data.id === "number" ? info.data.id : null,
+        parent: info.data.forked_from_project?.path_with_namespace ?? null,
+      });
+    },
+
+    findPr(head, match) {
+      // Every page (#284 N5): an open MR past the first 20 would read as
+      // "none" and pr create would open a duplicate.
+      const listed: GlMr[] = [];
+      const endpoint = `${project}/merge_requests?source_branch=${encodeURIComponent(head)}&order_by=created_at&sort=desc&per_page=${FIND_PER_PAGE}`;
+      for (let page = 1; page <= maxPages; page += 1) {
+        const list = apiJson<GlMr[]>(
+          runner,
+          "glab",
+          apiHost,
+          api(page === 1 ? endpoint : `${endpoint}&page=${page}`),
+          `merge requests for ${head}`,
+        );
+        if (!list.ok) return list;
+        if (!Array.isArray(list.data)) return failure("failed", "merge request list is not a list");
+        listed.push(...list.data);
+        if (list.data.length < FIND_PER_PAGE) break;
+      }
+      // Same-named branches in other forks are not ours: match the source
+      // project or the exact head sha.
+      const matches = listed.filter(
+        (mr) =>
+          mr.source_branch === head &&
+          (!match.base || mr.target_branch === undefined || mr.target_branch === match.base) &&
+          ((match.projectId !== null && mr.source_project_id === match.projectId) ||
+            (match.sha !== null && mr.sha === match.sha)),
+      );
+      const open = matches.filter((mr) => mr.state === "opened");
+      if (!match.base && new Set(open.map((mr) => mr.target_branch)).size > 1)
+        return failure(
+          "blocked",
+          `ambiguous_pr: ${head} has open merge requests ${open.map((mr) => `!${mr.iid} -> ${mr.target_branch}`).join(", ")}`,
+          `pass --pr <n>, e.g. --pr ${open[0].iid}`,
+        );
+      const pick = open[0] ?? matches[0];
+      return success(
+        pick
+          ? {
+              number: pick.iid,
+              url: pick.web_url,
+              state: mrState(pick.state),
+              headBranch: pick.source_branch,
+              headSha: pick.sha ?? null,
+            }
+          : null,
+      );
+    },
+
+    prStatus(iid) {
+      const mr = apiJson<GlMr>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${project}/merge_requests/${iid}`),
+        `merge request !${iid}`,
+      );
+      if (!mr.ok) return mr;
+      const value = mr.data;
+      let truncated = false;
+      let checks: ForgeCheck[] = [];
+      const pipeline = value.head_pipeline ?? null;
+      const open = value.state === "opened";
+      // Merged-results and merge-train pipelines run on a merge ref whose sha
+      // is a merge commit, not the MR head. They test the current head when
+      // source_sha says so or, when the response has no source_sha, when the
+      // merge commit's parents include the head (GET …/repository/commits/:sha).
+      const current =
+        pipeline !== null &&
+        (pipeline.sha === value.sha ||
+          pipeline.source_sha === value.sha ||
+          (!pipeline.source_sha &&
+            new RegExp(`^refs/merge-requests/${value.iid}/(?:merge|train)$`, "u").test(
+              pipeline.ref ?? "",
+            ) &&
+            mergeCommitTests(pipeline.project_id, pipeline.sha, value.sha)));
+      if (pipeline && current) {
+        const scope = String(pipeline.project_id);
+        const jobs = pages(
+          `projects/${scope}/pipelines/${pipeline.id}/jobs`,
+          `pipeline ${pipeline.id} jobs`,
+        );
+        if (!jobs.ok) return jobs;
+        const bridges = pages(
+          `projects/${scope}/pipelines/${pipeline.id}/bridges`,
+          `pipeline ${pipeline.id} bridges`,
+        );
+        if (!bridges.ok) return bridges;
+        truncated ||= jobs.data.truncated || bridges.data.truncated;
+        checks = [
+          ...(jobs.data.items as GlJob[]).map((job) => checkFromJob(job, pipeline.id, scope)),
+          ...(bridges.data.items as GlBridge[]).map((bridge) =>
+            checkFromBridge(bridge, pipeline.id, scope),
+          ),
+        ];
+        // The pipeline status is a floor: a failed pipeline is never green,
+        // and a running one is never done, whatever the visible jobs say.
+        const pipelineState = stateOf(pipeline.status, false);
+        if (pipelineState === "failing" && !checks.some((check) => check.state === "failing"))
+          checks.push(pipelineCheck("failing", pipeline.status, pipeline));
+        if (pipelineState === "pending" && !checks.some((check) => check.state === "pending"))
+          checks.push(pipelineCheck("pending", pipeline.status, pipeline));
+      } else if (open && pipeline) {
+        // The head pipeline belongs to an older head: CI for this head has
+        // not reported yet. Pending, never "no checks".
+        checks = [pipelineCheck("pending", "awaiting_pipeline_for_head", null)];
+      }
+      // #284 N16: GitLab has no per-job required checks; "Pipelines must
+      // succeed" (only_allow_merge_if_pipeline_succeeds) makes every job that
+      // may not fail required. Read only when a failing check makes it matter:
+      // with the setting off, failing jobs are optional (a waiver may pass
+      // them). Unreadable keeps every such job required.
+      if (open && checks.some((check) => check.state === "failing")) {
+        const settings = apiJson<{ only_allow_merge_if_pipeline_succeeds?: unknown }>(
+          runner,
+          "glab",
+          apiHost,
+          api(project),
+          `project ${repo}`,
+        );
+        if (settings.ok && settings.data.only_allow_merge_if_pipeline_succeeds === false)
+          checks = checks.map((check) => ({ ...check, required: false }));
+      }
+      const discussions = pages(
+        `${project}/merge_requests/${iid}/discussions`,
+        `merge request !${iid} discussions`,
+      );
+      if (!discussions.ok) return discussions;
+      truncated ||= discussions.data.truncated;
+      const threads: ForgeThread[] = (discussions.data.items as GlDiscussion[])
+        .filter((discussion) =>
+          discussion.notes.some((note) => note.resolvable === true && note.resolved !== true),
+        )
+        .map((discussion) => {
+          const note = discussion.notes[0];
+          return {
+            id: discussion.id,
+            path: note.position?.new_path ?? note.position?.old_path ?? null,
+            line: note.position?.new_line ?? null,
+            author: note.author?.username ?? null,
+            isBot: isBot(note.author),
+            outdated: false,
+            url: safeUrl(`${value.web_url}#note_${note.id}`),
+            body: shortBody(note.body ?? ""),
+          };
+        });
+      const detailed = value.detailed_merge_status ?? "unchecked";
+      const conflicts = value.has_conflicts === true || detailed === "conflict";
+      const status: ForgePrStatus = {
+        number: value.iid,
+        url: value.web_url,
+        state: mrState(value.state),
+        draft: value.draft ?? value.work_in_progress ?? false,
+        base: value.target_branch,
+        baseSha: open ? baseTip(value.target_branch) : null,
+        head: { branch: value.source_branch, sha: value.sha },
+        mergeable: conflicts ? "no" : UNSETTLED.has(detailed) ? "unknown" : "yes",
+        conflicts,
+        rebaseRequired: detailed === "need_rebase",
+        reviewDecision:
+          detailed === "not_approved"
+            ? "review_required"
+            : detailed === "requested_changes"
+              ? "changes_requested"
+              : null,
+        mergeState: detailed,
+        inMergeQueue: false,
+        checks,
+        // GitLab gates on the whole pipeline: the jobs that may not fail
+        // when the project requires a green pipeline, none otherwise.
+        requiredContexts: [
+          ...new Set(
+            checks.filter((check) => check.required === true).map((check) => check.context),
+          ),
+        ],
+        threads,
+        truncated,
+      };
+      return success(status);
+    },
+
+    branchChecks(branch) {
+      const tip = baseTip(branch);
+      if (!tip) return failure("not_found", `branch ${branch} was not found`);
+      const latest = apiJson<
+        Array<{ id: number; project_id?: number; status: string; web_url?: string }>
+      >(
+        runner,
+        "glab",
+        apiHost,
+        api(
+          `${project}/pipelines?ref=${encodeURIComponent(branch)}&sha=${tip}&order_by=id&sort=desc&per_page=1`,
+        ),
+        `pipelines on ${branch}`,
+      );
+      if (!latest.ok) return latest;
+      const pipeline = Array.isArray(latest.data) ? latest.data[0] : undefined;
+      if (!pipeline) return success({ sha: tip, checks: [], requiredKnown: true });
+      const scope = String(pipeline.project_id ?? encodeURIComponent(repo));
+      const jobs = pages(
+        `projects/${scope}/pipelines/${pipeline.id}/jobs`,
+        `pipeline ${pipeline.id} jobs`,
+      );
+      if (!jobs.ok) return jobs;
+      const bridges = pages(
+        `projects/${scope}/pipelines/${pipeline.id}/bridges`,
+        `pipeline ${pipeline.id} bridges`,
+      );
+      if (!bridges.ok) return bridges;
+      const checks = [
+        ...(jobs.data.items as GlJob[]).map((job) => checkFromJob(job, pipeline.id, scope)),
+        ...(bridges.data.items as GlBridge[]).map((bridge) =>
+          checkFromBridge(bridge, pipeline.id, scope),
+        ),
+      ];
+      if (
+        stateOf(pipeline.status, false) === "failing" &&
+        !checks.some((check) => check.state === "failing")
+      )
+        checks.push(
+          pipelineCheck("failing", pipeline.status, {
+            id: pipeline.id,
+            project_id: pipeline.project_id ?? 0,
+            web_url: pipeline.web_url,
+          }),
+        );
+      return success({ sha: tip, checks, requiredKnown: true });
+    },
+
+    jobLogTail(job, lines) {
+      const scope = job.scope ?? encodeURIComponent(repo);
+      const text = apiText(
+        runner,
+        "glab",
+        apiHost,
+        ["api", `projects/${scope}/jobs/${job.jobId}/trace`],
+        `job ${job.jobId} trace`,
+        FORGE_TIMEOUTS.log,
+      );
+      return text.ok ? success(logTail(text.data, lines)) : text;
+    },
+
+    rerun(target) {
+      const scope = target.scope ?? encodeURIComponent(repo);
+      const endpoint =
+        target.kind === "failed_in_run"
+          ? `projects/${scope}/pipelines/${target.runId}/retry`
+          : `projects/${scope}/jobs/${target.jobId}/retry`;
+      const what =
+        target.kind === "failed_in_run"
+          ? `retry of pipeline ${target.runId}`
+          : `retry of job ${target.jobId}`;
+      const run = apiText(
+        runner,
+        "glab",
+        apiHost,
+        ["api", "-X", "POST", endpoint],
+        what,
+        FORGE_TIMEOUTS.api,
+      );
+      return run.ok ? success(undefined) : run;
+    },
+
+    createPr(input) {
+      // An MR from a fork is created in the source project and targets ours.
+      const fromFork = input.headRepo !== repo;
+      let source = project;
+      const extra: string[] = [];
+      if (fromFork) {
+        const target = apiJson<{ id?: number }>(
+          runner,
+          "glab",
+          apiHost,
+          api(project),
+          `project ${repo}`,
+        );
+        if (!target.ok) return target;
+        if (input.headProjectId === null || typeof target.data.id !== "number")
+          return failure(
+            "failed",
+            `cannot resolve the project ids for an MR from ${input.headRepo}`,
+          );
+        source = `projects/${input.headProjectId}`;
+        extra.push("-F", `target_project_id=${target.data.id}`);
+      }
+      const title =
+        input.draft && !/^draft:/iu.test(input.title) ? `Draft: ${input.title}` : input.title;
+      const created = apiWrite<GlMr>(
+        runner,
+        "glab",
+        apiHost,
+        [
+          "api",
+          "-X",
+          "POST",
+          `${source}/merge_requests`,
+          "-f",
+          `source_branch=${input.head}`,
+          "-f",
+          `target_branch=${input.base}`,
+          "-f",
+          `title=${title}`,
+          "-f",
+          `description=${input.body}`,
+          ...extra,
+        ],
+        `merge request for ${input.head}`,
+      );
+      if (!created.ok) return created;
+      const value = created.data;
+      if (typeof value.iid !== "number" || typeof value.web_url !== "string")
+        return failure("failed", "glab api merge_requests returned no merge request iid");
+      return success({
+        number: value.iid,
+        url: value.web_url,
+        state: mrState(value.state),
+        headBranch: value.source_branch ?? input.head,
+        headSha: value.sha ?? null,
+      });
+    },
+
+    merge(iid, mergeOptions) {
+      const squash = mergeOptions.method === "squash" ? mergeOptions.squashMessage : undefined;
+      // GitLab's merge method is a project setting; squash is per request.
+      if (mergeOptions.method === "rebase")
+        return failure(
+          "invalid_input",
+          "GitLab merges with the project's merge method; pass --method squash or merge",
+        );
+      const merged = apiWrite<
+        GlMr & { merge_commit_sha?: string | null; squash_commit_sha?: string | null }
+      >(
+        runner,
+        "glab",
+        apiHost,
+        [
+          "api",
+          "-X",
+          "PUT",
+          `${project}/merge_requests/${iid}/merge`,
+          ...(squash
+            ? ["--input", "-"]
+            : [
+                "-f",
+                `sha=${mergeOptions.sha}`,
+                "-F",
+                `squash=${mergeOptions.method === "squash" ? "true" : "false"}`,
+              ]),
+        ],
+        `merge of merge request !${iid}`,
+        undefined,
+        // The squash message rides stdin: argv has a size limit (E2BIG).
+        squash
+          ? JSON.stringify({
+              sha: mergeOptions.sha,
+              squash: true,
+              squash_commit_message: squash.body
+                ? `${squash.subject}\n\n${squash.body}`
+                : squash.subject,
+            })
+          : undefined,
+      );
+      if (!merged.ok) return merged;
+      const value = merged.data;
+      return success({
+        mergeSha: value.merge_commit_sha ?? value.squash_commit_sha ?? null,
+      });
+    },
+
+    updateBase(iid, base) {
+      const updated = apiWrite<unknown>(
+        runner,
+        "glab",
+        apiHost,
+        ["api", "-X", "PUT", `${project}/merge_requests/${iid}`, "-f", `target_branch=${base}`],
+        `retarget of merge request !${iid}`,
+      );
+      return updated.ok ? success(undefined) : updated;
+    },
+
+    prMeta(iid) {
+      const mr = getMr(iid);
+      if (!mr.ok) return mr;
+      const value = mr.data;
+      const meta: PrMeta = {
+        number: value.iid,
+        url: value.web_url,
+        state: mrState(value.state),
+        draft: value.draft ?? value.work_in_progress ?? false,
+        title: value.title ?? "",
+        base: value.target_branch,
+        headBranch: value.source_branch,
+        author: value.author?.username ?? null,
+        fork:
+          value.source_project_id === undefined || value.target_project_id === undefined
+            ? null
+            : value.source_project_id !== value.target_project_id,
+      };
+      return success(meta);
+    },
+
+    openPrsInto(branch) {
+      const list = apiJson<GlMr[]>(
+        runner,
+        "glab",
+        apiHost,
+        api(
+          `${project}/merge_requests?state=opened&target_branch=${encodeURIComponent(branch)}&per_page=100`,
+        ),
+        `open merge requests into ${branch}`,
+      );
+      if (!list.ok) return list;
+      if (!Array.isArray(list.data)) return failure("failed", "merge request list is not a list");
+      return success(list.data.map((mr) => mr.iid));
+    },
+
+    setDraft(iid, draft) {
+      const mr = getMr(iid);
+      if (!mr.ok) return mr;
+      const title = draftTitle(mr.data.title ?? "", draft);
+      if (title === null)
+        return failure(
+          "invalid_input",
+          `merge request !${iid} has no title besides its draft marker`,
+        );
+      return putMr(iid, ["-f", `title=${title}`], `draft state`);
+    },
+
+    editPr(iid, edit) {
+      const mr = getMr(iid);
+      if (!mr.ok) return mr;
+      const fields: string[] = [];
+      // A new title keeps the MR's draft state (it lives in the title).
+      if (edit.title !== undefined) {
+        const title = draftTitle(edit.title, mr.data.draft ?? mr.data.work_in_progress ?? false);
+        if (title === null)
+          return failure("invalid_input", "--title must have text besides a draft marker");
+        fields.push("-f", `title=${title}`);
+      }
+      if (edit.body !== undefined) fields.push("-f", `description=${edit.body}`);
+      if (edit.base !== undefined) fields.push("-f", `target_branch=${edit.base}`);
+      if (edit.addLabels.length) fields.push("-f", `add_labels=${edit.addLabels.join(",")}`);
+      if (edit.removeLabels.length)
+        fields.push("-f", `remove_labels=${edit.removeLabels.join(",")}`);
+      if (edit.addReviewers.length) {
+        // reviewer_ids replaces the list: keep the current reviewers.
+        const ids = new Set((mr.data.reviewers ?? []).map((reviewer) => reviewer.id));
+        for (const username of edit.addReviewers) {
+          const users = apiJson<Array<{ id?: number; username?: string }>>(
+            runner,
+            "glab",
+            apiHost,
+            api(`users?username=${encodeURIComponent(username)}`),
+            `user ${username}`,
+          );
+          if (!users.ok) return users;
+          const user = Array.isArray(users.data)
+            ? users.data.find((entry) => entry.username?.toLowerCase() === username.toLowerCase())
+            : undefined;
+          if (typeof user?.id !== "number")
+            return failure("not_found", `GitLab user ${username} was not found`);
+          ids.add(user.id);
+        }
+        // One JSON array: glab rejects `reviewer_ids[]=` keys in a JSON body.
+        fields.push("-F", `reviewer_ids=${JSON.stringify([...ids])}`);
+      }
+      return fields.length ? putMr(iid, fields, "edit") : success(undefined);
+    },
+
+    replyThread(iid, thread, body) {
+      const note = apiWrite<{ id?: number }>(
+        runner,
+        "glab",
+        apiHost,
+        [
+          "api",
+          "-X",
+          "POST",
+          `${project}/merge_requests/${iid}/discussions/${encodeURIComponent(thread)}/notes`,
+          "-f",
+          `body=${body}`,
+        ],
+        `reply on merge request !${iid}`,
+      );
+      if (!note.ok) return note;
+      return success({ url: null });
+    },
+
+    resolveThread(iid, thread) {
+      const resolved = apiWrite<{ notes?: GlNote[] }>(
+        runner,
+        "glab",
+        apiHost,
+        [
+          "api",
+          "-X",
+          "PUT",
+          `${project}/merge_requests/${iid}/discussions/${encodeURIComponent(thread)}`,
+          "-F",
+          "resolved=true",
+        ],
+        `resolve on merge request !${iid}`,
+      );
+      if (!resolved.ok) return resolved;
+      const open = (resolved.data.notes ?? []).some(
+        (note) => note.resolvable === true && note.resolved !== true,
+      );
+      return open
+        ? failure("failed", `discussion ${thread} on merge request !${iid} is still unresolved`)
+        : success(undefined);
+    },
+
+    threadState(iid, thread) {
+      const discussion = apiJson<GlDiscussion>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${project}/merge_requests/${iid}/discussions/${encodeURIComponent(thread)}`),
+        `discussion ${thread}`,
+      );
+      if (!discussion.ok) return discussion.code === "not_found" ? success(null) : discussion;
+      const notes = Array.isArray(discussion.data.notes) ? discussion.data.notes : [];
+      if (!notes.some((note) => note.resolvable === true)) return success(null);
+      return success(
+        notes.some((note) => note.resolvable === true && note.resolved !== true)
+          ? "open"
+          : "resolved",
+      );
+    },
+
+    findRelease(tag) {
+      const found = apiJson<{ tag_name?: string; _links?: { self?: string } }>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${project}/releases/${encodeURIComponent(tag)}`),
+        `release ${tag}`,
+      );
+      if (!found.ok) return found.code === "not_found" ? success(null) : found;
+      return success({
+        tag: found.data.tag_name ?? tag,
+        url: safeUrl(found.data["_links"]?.self ?? null),
+      });
+    },
+
+    createRelease(input) {
+      // The notes ride stdin: argv has a size limit (E2BIG).
+      const created = apiWrite<{ tag_name?: string; _links?: { self?: string } }>(
+        runner,
+        "glab",
+        apiHost,
+        ["api", "-X", "POST", `${project}/releases`, "--input", "-"],
+        `release ${input.tag}`,
+        undefined,
+        JSON.stringify({ tag_name: input.tag, name: input.name, description: input.body }),
+      );
+      if (!created.ok) return created;
+      return success({
+        tag: created.data.tag_name ?? input.tag,
+        url: safeUrl(created.data["_links"]?.self ?? null),
+      });
+    },
+
+    issueComments(iid) {
+      const listed = apiJson<Array<{ body?: unknown }>>(
+        runner,
+        "glab",
+        apiHost,
+        api(`${project}/issues/${iid}/notes?per_page=100`),
+        `notes on issue #${iid}`,
+      );
+      if (!listed.ok) return listed;
+      if (!Array.isArray(listed.data))
+        return failure("failed", `glab api issue #${iid} notes returned no list`);
+      return success(
+        listed.data.flatMap((note) => (typeof note.body === "string" ? [note.body] : [])),
+      );
+    },
+
+    commentIssue(iid, body) {
+      const posted = apiWrite<unknown>(
+        runner,
+        "glab",
+        apiHost,
+        ["api", "-X", "POST", `${project}/issues/${iid}/notes`, "-f", `body=${body}`],
+        `note on issue #${iid}`,
+      );
+      return posted.ok ? success(undefined) : posted;
+    },
+  };
+}