@intentius/chant 0.124.12 → 0.124.14

package/dist/pr-forge.js

@@ -0,0 +1,810 @@
+/**
+ * What chant and the products built on it ask of a forge: keep one comment
+ * (a merge request note on GitLab) on a pull request up to date, set a commit
+ * status, keep one tracking issue in the repository, list who approved a pull
+ * request, find the pull request that merged a commit, and open or edit a
+ * pull request (a merge request on GitLab) for a branch.
+ *
+ * The pull-request loop (#3183) uses the note, the status and the review
+ * calls. `reconcilePr`'s `comment` and `issue` finding modes post through the
+ * same clients (#3757), so a finding needs no `gh` on the runner. terragucci
+ * and SQL Yodeler post their own notes, statuses and drift issues through
+ * them too (#3759): bodies stay with each product, the finding by marker and
+ * the forge's REST shapes live here.
+ *
+ * GitHub and Forgejo speak the same REST shapes for most of this, at
+ * different base URLs (`$GITHUB_API_URL` is right on both, #2305); they part
+ * on the commit-to-pull-request lookup, on review states and on page size.
+ * GitLab has its own API for all of it. Each client takes a `fetch`, so the
+ * tests drive them with a recording fake and no network.
+ *
+ * A reviewer is named the way #3163 names a person: `github:<login>`,
+ * `gitlab:<login>`, or `<forge>@<host>:<login>` off the forge's default host.
+ * The apply compares that string with the approval's `resolvedBy`.
+ *
+ * Opening a pull request goes over REST too (#3798): `gh pr` speaks GitHub's
+ * GraphQL, which Forgejo does not serve, so chant's own pull-request paths
+ * open theirs through {@link PrForge.openPullRequest} on Forgejo and GitLab.
+ *
+ * Like `./pr-loop.ts`, this bundles without the TypeScript toolchain (#3421):
+ * it imports nothing but `node:fs`, to read a CI job's event payload.
+ * `./pr-forge-bundle.test.ts` holds it to that.
+ */
+import { readFileSync } from "node:fs";
+export const FORGE_KINDS = ["github", "gitlab", "forgejo"];
+/** Every {@link ForgeStatusState}, for a caller that reads one from its own input. */
+export const FORGE_STATUS_STATES = ["pending", "running", "success", "failed", "failure", "canceled", "error"];
+/**
+ * What each forge is sent for a {@link ForgeStatusState} (#3834). GitHub
+ * keeps `pending`, `success`, `failure` and `error`; Forgejo the same and
+ * `warning`; GitLab `pending`, `running`, `success`, `failed` and `canceled`.
+ * A state the forge lacks becomes its nearest one.
+ */
+const STATUS_STATE = {
+    github: { pending: "pending", running: "pending", success: "success", failed: "failure", failure: "failure", canceled: "error", error: "error" },
+    gitlab: { pending: "pending", running: "running", success: "success", failed: "failed", failure: "failed", canceled: "canceled", error: "failed" },
+};
+/** The state `kind` is sent for `state`. Forgejo takes GitHub's. */
+export function statusStateFor(kind, state) {
+    const mapped = STATUS_STATE[kind === "gitlab" ? "gitlab" : "github"][state];
+    if (mapped === undefined)
+        throw new Error(`a commit status state is one of ${FORGE_STATUS_STATES.join(", ")}, not ${JSON.stringify(state)}`);
+    return mapped;
+}
+/** Statuses a forge answers a refused merge with: not allowed, head moved, conflict, invalid. */
+const MERGE_REFUSED = new Set([405, 406, 409, 422]);
+/** A refused merge as a result, any other failure rethrown. */
+function refusedMerge(err) {
+    if (err instanceof ForgeApiError && MERGE_REFUSED.has(err.status)) {
+        let reason = err.detail;
+        try {
+            const j = JSON.parse(err.detail);
+            const m = j.message ?? j.error;
+            if (typeof m === "string")
+                reason = m;
+        }
+        catch {
+            /* not JSON: the raw text is the reason */
+        }
+        return { merged: false, reason: reason.slice(0, 300) || `the forge refused the merge (${err.status})` };
+    }
+    throw err;
+}
+/** Thrown when a forge answers a call with an error status. */
+export class ForgeApiError extends Error {
+    constructor(method, url, status, detail) {
+        super(`${method} ${url} answered ${status}${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+        this.method = method;
+        this.url = url;
+        this.status = status;
+        this.detail = detail;
+        this.name = "ForgeApiError";
+    }
+}
+const DEFAULT_HOST = { github: "github.com", gitlab: "gitlab.com", forgejo: null };
+/** `<forge>:<login>` on the forge's default host, `<forge>@<host>:<login>` elsewhere, lower-cased (#3163's form). */
+export function forgePrincipalOf(kind, host, login) {
+    const h = host.toLowerCase();
+    const l = login.toLowerCase();
+    return h === DEFAULT_HOST[kind] ? `${kind}:${l}` : `${kind}@${h}:${l}`;
+}
+function transport(base, headers, fetchImpl) {
+    const root = base.replace(/\/+$/, "");
+    const call = async (method, path, body) => {
+        const url = `${root}${path}`;
+        const res = await fetchImpl(url, {
+            method,
+            headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        if (!res.ok)
+            throw new ForgeApiError(method, url, res.status, text);
+        return text ? JSON.parse(text) : null;
+    };
+    return {
+        call,
+        async list(path, pageParams, pageSize) {
+            const out = [];
+            for (let page = 1; page <= 50; page++) {
+                const sep = path.includes("?") ? "&" : "?";
+                const items = await call("GET", `${path}${sep}${pageParams(page)}`);
+                if (!Array.isArray(items))
+                    break;
+                out.push(...items);
+                if (items.length < pageSize)
+                    break;
+            }
+            return out;
+        },
+    };
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const loginOf = (v) => (isObject(v) && isObject(v.user) && typeof v.user.login === "string" ? v.user.login : undefined);
+const str = (v) => (typeof v === "string" ? v : undefined);
+const num = (v) => (typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v) ? Number(v) : undefined);
+const carries = (body, marker, match) => match === "anywhere" ? body.includes(marker) : body.startsWith(marker);
+/** Whether `author` is one of `want`, without case. No `want` (or `""`) takes anyone. */
+const authorIn = (want, author) => {
+    if (want === undefined || want === "")
+        return true;
+    const logins = (typeof want === "string" ? [want] : want).map((l) => l.toLowerCase());
+    return author !== undefined && logins.includes(author.toLowerCase());
+};
+const ownedBy = (marker, opts) => (t) => carries(t.body, marker, opts.match) && authorIn(opts.author, t.author);
+function checkMarker(what, marker, body, match) {
+    if (!marker)
+        throw new Error(`the ${what} needs a marker to be found again`);
+    if (!carries(body, marker, match)) {
+        throw new Error(`the ${what} body ${match === "anywhere" ? "does not carry" : "does not start with"} its marker ${JSON.stringify(marker)}, so the next run could not find it`);
+    }
+}
+/** The oldest comment on `pr` that `opts` takes for the caller's own. */
+async function ownComment(t, pr, marker, opts) {
+    if (!marker)
+        throw new Error("the comment needs a marker to be found");
+    return (await t.comments(pr)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
+}
+async function upsertCommentWith(t, pr, marker, body, opts, check) {
+    if (check)
+        checkMarker("comment", marker, body, opts.match);
+    const mine = await ownComment(t, pr, marker, opts);
+    if (!mine) {
+        const made = await t.addComment(pr, body);
+        return { action: "created", id: made?.id ?? 0, ...(made?.url ? { url: made.url } : {}) };
+    }
+    if (mine.body === body)
+        return { action: "unchanged", id: mine.id, ...(mine.url ? { url: mine.url } : {}) };
+    const edited = await t.editComment(pr, mine.id, body);
+    const url = edited?.url ?? mine.url;
+    return { action: "updated", id: mine.id, ...(url ? { url } : {}) };
+}
+async function trackIssueWith(t, marker, finding, opts, check) {
+    if (finding && check)
+        checkMarker("issue", marker, finding.body, opts.match);
+    const mine = (await t.openIssues(marker)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
+    const at = (i) => i ? { number: i.id, ...(i.url ? { url: i.url } : {}), ...(i.created ? { created: i.created } : {}) } : {};
+    if (finding === null) {
+        if (!mine)
+            return { action: "none" };
+        if (!opts.closeOnClear)
+            return { action: "left", ...at(mine) };
+        await t.closeIssue(mine.id, opts.clearComment);
+        return { action: "closed", ...at(mine) };
+    }
+    if (!mine)
+        return { action: "opened", ...at(await t.openIssue(finding.title, finding.body)) };
+    if (sameIssue({ title: mine.title ?? "", body: mine.body }, finding, opts.sameWhen))
+        return { action: "unchanged", ...at(mine) };
+    const edited = await t.editIssue(mine.id, finding.title, finding.body);
+    return { action: "updated", ...at(mine), ...(edited?.url ? { url: edited.url } : {}) };
+}
+function sameIssue(open, finding, sameWhen) {
+    if (typeof sameWhen === "function")
+        return sameWhen(open, finding);
+    if (open.title !== finding.title)
+        return false;
+    return typeof sameWhen === "string" && sameWhen !== "" ? open.body.includes(sameWhen) : open.body === finding.body;
+}
+/** The recipes every client shares, over its own {@link Threads}. */
+function threadCalls(t) {
+    return {
+        async addComment(pr, body) {
+            const made = await t.addComment(pr, body);
+            return { id: made?.id ?? 0, ...(made?.url ? { url: made.url } : {}) };
+        },
+        async findIssue(marker, opts = {}) {
+            if (!marker)
+                throw new Error("the issue needs a marker to be found");
+            const i = (await t.openIssues(marker)).filter(ownedBy(marker, opts)).sort((a, b) => a.id - b.id)[0];
+            return i ? { number: i.id, title: i.title ?? "", body: i.body, ...(i.created ? { created: i.created } : {}), ...(i.url ? { url: i.url } : {}) } : undefined;
+        },
+        async findComment(pr, marker, opts = {}) {
+            const c = await ownComment(t, pr, marker, opts);
+            return c ? { id: c.id, body: c.body, ...(c.url ? { url: c.url } : {}) } : undefined;
+        },
+        upsertComment: (pr, marker, body, opts = {}) => upsertCommentWith(t, pr, marker, body, opts, true),
+        upsertNote: async (pr, marker, body) => (await upsertCommentWith(t, pr, marker, body, {}, false)).url,
+        trackIssue: (marker, finding, opts = {}) => trackIssueWith(t, marker, finding, opts, true),
+        upsertIssue: async (marker, title, body) => (await trackIssueWith(t, marker, { title, body }, {}, false)).url,
+    };
+}
+/** GitHub keeps a status description to 140 characters; Forgejo follows. */
+const GITHUB_DESCRIPTION = 140;
+/** GitLab keeps a status description to 255 characters. */
+const GITLAB_DESCRIPTION = 255;
+/** Which of the two GitHub-shaped forges a client is talking to. */
+function githubShaped(kind, opts) {
+    const host = (opts.host ?? "github.com").toLowerCase();
+    const api = transport(opts.apiBase, kind === "github"
+        ? { ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}), Accept: "application/vnd.github+json" }
+        : { ...(opts.token ? { Authorization: `token ${opts.token}` } : {}), Accept: "application/json" }, opts.fetch ?? globalThis.fetch);
+    const repo = `/repos/${opts.repo}`;
+    // GitHub pages with per_page (up to 100); Forgejo with limit (capped at 50 by default).
+    const pageSize = kind === "github" ? 100 : 50;
+    const pageParams = (page) => (kind === "github" ? `per_page=100&page=${page}` : `limit=50&page=${page}`);
+    const thread = (v) => {
+        if (!isObject(v))
+            return undefined;
+        const id = num(v.number) ?? num(v.id);
+        if (id === undefined)
+            return undefined;
+        const author = loginOf(v);
+        const url = str(v.html_url);
+        const created = str(v.created_at);
+        return { id, body: str(v.body) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
+    };
+    const threads = (items) => items.map(thread).filter((t) => t !== undefined);
+    const pull = (v) => {
+        if (!isObject(v))
+            return undefined;
+        const number = num(v.number);
+        const head = isObject(v.head) ? str(v.head.ref) : undefined;
+        if (number === undefined)
+            return undefined;
+        const base = isObject(v.base) ? str(v.base.ref) : undefined;
+        const url = str(v.html_url);
+        return { number, title: str(v.title) ?? "", body: str(v.body) ?? "", head: head ?? "", ...(base ? { base } : {}), ...(url ? { url } : {}) };
+    };
+    /** A pull request whose head branch lives in this repository, not a fork. */
+    const fromHere = (v, head) => {
+        if (!isObject(v) || !isObject(v.head) || v.head.ref !== head)
+            return false;
+        const full = isObject(v.head.repo) ? str(v.head.repo.full_name) : undefined;
+        return full === undefined || full.toLowerCase() === opts.repo.toLowerCase();
+    };
+    const t = {
+        comments: async (pr) => threads(await api.list(`${repo}/issues/${pr}/comments`, pageParams, pageSize)),
+        addComment: async (pr, body) => thread(await api.call("POST", `${repo}/issues/${pr}/comments`, { body })),
+        editComment: async (_pr, id, body) => thread(await api.call("PATCH", `${repo}/issues/comments/${id}`, { body })),
+        // Paged in full rather than searched: GitHub's search index lags a
+        // write, so a run straight after another would miss the issue it just
+        // opened, and Forgejo has no `/search/issues` at all. Both list pull
+        // requests among issues; one of those is never ours.
+        openIssues: async () => threads((await api.list(`${repo}/issues?state=open`, pageParams, pageSize)).filter((i) => isObject(i) && !isObject(i.pull_request))),
+        openIssue: async (title, body) => thread(await api.call("POST", `${repo}/issues`, { title, body })),
+        editIssue: async (n, title, body) => thread(await api.call("PATCH", `${repo}/issues/${n}`, { title, body })),
+        async closeIssue(n, comment) {
+            if (comment)
+                await api.call("POST", `${repo}/issues/${n}/comments`, { body: comment });
+            await api.call("PATCH", `${repo}/issues/${n}`, { state: "closed" });
+        },
+    };
+    return {
+        kind,
+        host,
+        ...(opts.runUrl ? { runUrl: opts.runUrl } : {}),
+        principalOf: (login) => forgePrincipalOf(kind, host, login),
+        ...threadCalls(t),
+        async setStatus(sha, status) {
+            await api.call("POST", `${repo}/statuses/${sha}`, {
+                state: statusStateFor(kind, status.state),
+                context: status.context,
+                description: status.description.slice(0, GITHUB_DESCRIPTION),
+                ...(status.url ? { target_url: status.url } : {}),
+            });
+        },
+        async approvers(pr) {
+            // A reviewer's newest deciding review is their standing one. A comment
+            // review decides nothing; a dismissed one (GitHub's state, Forgejo's
+            // flag) no longer approves.
+            const reviews = await api.list(`${repo}/pulls/${pr}/reviews`, pageParams, pageSize);
+            const standing = new Map();
+            for (const r of reviews) {
+                const login = loginOf(r);
+                if (!login || !isObject(r) || typeof r.state !== "string")
+                    continue;
+                const state = r.dismissed === true ? "DISMISSED" : r.state.toUpperCase();
+                if (state === "COMMENTED" || state === "COMMENT" || state === "PENDING")
+                    continue;
+                standing.set(login, state);
+            }
+            return [...standing].filter(([, state]) => state === "APPROVED").map(([login]) => login).sort();
+        },
+        async pullRequestFor(sha) {
+            if (kind === "forgejo") {
+                try {
+                    const pr = await api.call("GET", `${repo}/commits/${sha}/pull`);
+                    return isObject(pr) && typeof pr.number === "number" ? pr.number : null;
+                }
+                catch (err) {
+                    if (err instanceof ForgeApiError && err.status === 404)
+                        return null;
+                    throw err;
+                }
+            }
+            const prs = await api.call("GET", `${repo}/commits/${sha}/pulls`);
+            if (!Array.isArray(prs))
+                return null;
+            const merged = prs.filter((p) => isObject(p) && p.merged_at);
+            const exact = merged.find((p) => isObject(p) && p.merge_commit_sha === sha);
+            const pick = (exact ?? merged[0]);
+            return pick && typeof pick.number === "number" ? pick.number : null;
+        },
+        async openPullRequest(spec) {
+            const base = spec.base ?? (await defaultBranchOf(api, repo, "default_branch"));
+            const title = spec.draft && kind === "forgejo" ? `WIP: ${spec.title}` : spec.title;
+            const made = await api.call("POST", `${repo}/pulls`, {
+                title,
+                body: spec.body,
+                head: spec.head,
+                base,
+                ...(spec.draft && kind === "github" ? { draft: true } : {}),
+            });
+            return pull(made) ?? { number: 0, title, body: spec.body, head: spec.head, base };
+        },
+        async findPullRequest(head) {
+            // GitHub filters by `owner:branch` server-side; Forgejo's list takes no
+            // head filter, so every open page is read and matched here.
+            const owner = opts.repo.split("/")[0];
+            const query = kind === "github" ? `?state=open&head=${encodeURIComponent(`${owner}:${head}`)}` : "?state=open";
+            let listed;
+            try {
+                listed = await api.list(`${repo}/pulls${query}`, pageParams, pageSize);
+            }
+            catch (err) {
+                // Forgejo answers the list with 404 while it still counts the repository
+                // as empty (just after the first push). That is no pull request; a
+                // repository that is really missing 404s on its own read too.
+                if (kind !== "forgejo" || !(err instanceof ForgeApiError) || err.status !== 404)
+                    throw err;
+                await api.call("GET", repo);
+                return undefined;
+            }
+            const open = listed.filter((p) => fromHere(p, head));
+            return open.map(pull).filter((p) => p !== undefined).sort((a, b) => a.number - b.number)[0];
+        },
+        async editPullRequest(pr, change) {
+            return pull(await api.call("PATCH", `${repo}/pulls/${pr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { body: change.body } : {}) }));
+        },
+        async addLabels(pr, labels) {
+            if (labels.length === 0)
+                return;
+            await api.call("POST", `${repo}/issues/${pr}/labels`, { labels: [...labels] });
+        },
+        async mergePullRequest(pr, m) {
+            const method = m.method ?? "merge";
+            let res;
+            try {
+                res =
+                    kind === "github"
+                        ? await api.call("PUT", `${repo}/pulls/${pr}/merge`, {
+                            sha: m.sha,
+                            merge_method: method,
+                            ...(m.title !== undefined ? { commit_title: m.title } : {}),
+                            ...(m.message !== undefined ? { commit_message: m.message } : {}),
+                        })
+                        : await api.call("POST", `${repo}/pulls/${pr}/merge`, {
+                            Do: method,
+                            head_commit_id: m.sha,
+                            ...(m.title !== undefined ? { MergeTitleField: m.title } : {}),
+                            ...(m.message !== undefined ? { MergeMessageField: m.message } : {}),
+                            ...(m.deleteBranch ? { delete_branch_after_merge: true } : {}),
+                        });
+            }
+            catch (err) {
+                return refusedMerge(err);
+            }
+            if (isObject(res) && res.merged === false)
+                return { merged: false, reason: str(res.message) ?? "the forge did not merge it" };
+            // Forgejo answers an empty body, so the merge commit is read back.
+            const after = await api.call("GET", `${repo}/pulls/${pr}`).catch(() => undefined);
+            const sha = (isObject(res) ? str(res.sha) : undefined) ?? (isObject(after) ? str(after.merge_commit_sha) : undefined);
+            if (kind === "github" && m.deleteBranch && isObject(after) && isObject(after.head) && str(after.head.ref) && fromHere(after, str(after.head.ref))) {
+                const ref = str(after.head.ref).split("/").map(encodeURIComponent).join("/");
+                await api.call("DELETE", `${repo}/git/refs/heads/${ref}`).catch(() => undefined);
+            }
+            return { merged: true, ...(sha ? { sha } : {}) };
+        },
+    };
+}
+/** The repository's default branch, from `GET` on the repository (`/repos/{repo}`, `/projects/{id}`). */
+async function defaultBranchOf(api, path, field) {
+    const r = await api.call("GET", path);
+    const branch = isObject(r) ? str(r[field]) : undefined;
+    if (!branch)
+        throw new Error(`${path} names no default branch to open the pull request against; pass base`);
+    return branch;
+}
+/** A GitHub client (github.com or GitHub Enterprise Server). */
+export function githubForge(opts) {
+    return githubShaped("github", opts);
+}
+/** A Forgejo (or Gitea) client. `host` is required: Forgejo has no default host. */
+export function forgejoForge(opts) {
+    return githubShaped("forgejo", opts);
+}
+/**
+ * A GitLab client. Writing notes needs an access token with the `api` scope
+ * on most instances: the job token reaches only the endpoints the instance's
+ * job-token allowlist names.
+ */
+export function gitlabForge(opts) {
+    const host = (opts.host ?? "gitlab.com").toLowerCase();
+    const api = transport(opts.apiBase, opts.token ? { [opts.tokenHeader ?? "PRIVATE-TOKEN"]: opts.token } : {}, opts.fetch ?? globalThis.fetch);
+    const project = `/projects/${encodeURIComponent(decodeURIComponent(opts.project))}`;
+    const pageParams = (page) => `per_page=100&page=${page}`;
+    const authorOf = (v) => (isObject(v.author) ? str(v.author.username) : undefined);
+    const note = (v) => {
+        if (!isObject(v))
+            return undefined;
+        const id = num(v.id);
+        if (id === undefined)
+            return undefined;
+        const author = authorOf(v);
+        return { id, body: str(v.body) ?? "", ...(author ? { author } : {}) };
+    };
+    const issue = (v) => {
+        if (!isObject(v))
+            return undefined;
+        const id = num(v.iid);
+        if (id === undefined)
+            return undefined;
+        const author = authorOf(v);
+        const url = str(v.web_url);
+        const created = str(v.created_at);
+        return { id, body: str(v.description) ?? "", ...(created ? { created } : {}), ...(str(v.title) !== undefined ? { title: str(v.title) } : {}), ...(author ? { author } : {}), ...(url ? { url } : {}) };
+    };
+    const notes = `${project}/merge_requests`;
+    const mergeRequest = (v) => {
+        if (!isObject(v))
+            return undefined;
+        const number = num(v.iid);
+        if (number === undefined)
+            return undefined;
+        const base = str(v.target_branch);
+        const url = str(v.web_url);
+        return { number, title: str(v.title) ?? "", body: str(v.description) ?? "", head: str(v.source_branch) ?? "", ...(base ? { base } : {}), ...(url ? { url } : {}) };
+    };
+    const t = {
+        comments: async (mr) => (await api.list(`${notes}/${mr}/notes`, pageParams, 100))
+            // System notes ("added 1 commit") are the forge's own, never ours.
+            .filter((n) => !(isObject(n) && n.system === true))
+            .map(note)
+            .filter((n) => n !== undefined),
+        addComment: async (mr, body) => note(await api.call("POST", `${notes}/${mr}/notes`, { body })),
+        editComment: async (mr, id, body) => note(await api.call("PUT", `${notes}/${mr}/notes/${id}`, { body })),
+        // `search` narrows the list server-side to issues whose description
+        // carries the marker, as `reconcilePr`'s GitLab issue does (#2292); the
+        // match itself is still decided here.
+        openIssues: async (marker) => (await api.list(`${project}/issues?state=opened&search=${encodeURIComponent(marker)}&in=description`, pageParams, 100))
+            .map(issue)
+            .filter((i) => i !== undefined),
+        openIssue: async (title, body) => issue(await api.call("POST", `${project}/issues`, { title, description: body })),
+        editIssue: async (n, title, body) => issue(await api.call("PUT", `${project}/issues/${n}`, { title, description: body })),
+        async closeIssue(n, comment) {
+            if (comment)
+                await api.call("POST", `${project}/issues/${n}/notes`, { body: comment });
+            await api.call("PUT", `${project}/issues/${n}`, { state_event: "close" });
+        },
+    };
+    return {
+        kind: "gitlab",
+        host,
+        ...(opts.runUrl ? { runUrl: opts.runUrl } : {}),
+        principalOf: (login) => forgePrincipalOf("gitlab", host, login),
+        ...threadCalls(t),
+        async setStatus(sha, status) {
+            try {
+                await api.call("POST", `${project}/statuses/${sha}`, {
+                    state: statusStateFor("gitlab", status.state),
+                    name: status.context,
+                    description: status.description.slice(0, GITLAB_DESCRIPTION),
+                    ...(status.url ? { target_url: status.url } : {}),
+                    ...(status.pipelineId !== undefined ? { pipeline_id: status.pipelineId } : {}),
+                });
+            }
+            catch (err) {
+                // GitLab answers 400 to a status set again to the state it already
+                // has ("Cannot transition status via :success from :success"): the
+                // status is what was asked for.
+                if (err instanceof ForgeApiError && err.status === 400 && /cannot transition status/i.test(err.message))
+                    return;
+                throw err;
+            }
+        },
+        async approvers(mr) {
+            const approvals = await api.call("GET", `${project}/merge_requests/${mr}/approvals`);
+            const by = isObject(approvals) && Array.isArray(approvals.approved_by) ? approvals.approved_by : [];
+            const logins = by
+                .map((a) => (isObject(a) && isObject(a.user) && typeof a.user.username === "string" ? a.user.username : undefined))
+                .filter((l) => l !== undefined);
+            return [...new Set(logins)].sort();
+        },
+        async pullRequestFor(sha) {
+            const mrs = await api.call("GET", `${project}/repository/commits/${sha}/merge_requests`);
+            if (!Array.isArray(mrs))
+                return null;
+            const merged = mrs.find((m) => isObject(m) && m.state === "merged" && (m.merge_commit_sha === sha || m.squash_commit_sha === sha))
+                ?? mrs.find((m) => isObject(m) && m.state === "merged");
+            return isObject(merged) && typeof merged.iid === "number" ? merged.iid : null;
+        },
+        async openPullRequest(spec) {
+            const base = spec.base ?? (await defaultBranchOf(api, project, "default_branch"));
+            const title = spec.draft ? `Draft: ${spec.title}` : spec.title;
+            const made = await api.call("POST", notes, { source_branch: spec.head, target_branch: base, title, description: spec.body });
+            return mergeRequest(made) ?? { number: 0, title, body: spec.body, head: spec.head, base };
+        },
+        async findPullRequest(head) {
+            const open = await api.list(`${notes}?state=opened&source_branch=${encodeURIComponent(head)}`, pageParams, 100);
+            return open
+                // A fork's merge request into this project has another source project.
+                .filter((m) => isObject(m) && m.source_branch === head && (m.source_project_id === undefined || m.source_project_id === m.project_id))
+                .map(mergeRequest)
+                .filter((m) => m !== undefined)
+                .sort((a, b) => a.number - b.number)[0];
+        },
+        async editPullRequest(mr, change) {
+            return mergeRequest(await api.call("PUT", `${notes}/${mr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { description: change.body } : {}) }));
+        },
+        async addLabels(mr, labels) {
+            if (labels.length === 0)
+                return;
+            await api.call("PUT", `${notes}/${mr}`, { add_labels: labels.join(",") });
+        },
+        async mergePullRequest(mr, m) {
+            const method = m.method ?? "merge";
+            if (method === "rebase")
+                throw new Error("GitLab has no one-call rebase merge; use method merge or squash");
+            const text = m.title !== undefined ? (m.message ? `${m.title}\n\n${m.message}` : m.title) : m.message;
+            let res;
+            try {
+                res = await api.call("PUT", `${notes}/${mr}/merge`, {
+                    sha: m.sha,
+                    ...(method === "squash" ? { squash: true, ...(text !== undefined ? { squash_commit_message: text } : {}) } : {}),
+                    ...(text !== undefined ? { merge_commit_message: text } : {}),
+                    ...(m.deleteBranch ? { should_remove_source_branch: true } : {}),
+                });
+            }
+            catch (err) {
+                return refusedMerge(err);
+            }
+            const sha = isObject(res) ? (str(res.merge_commit_sha) ?? str(res.squash_commit_sha)) : undefined;
+            if (isObject(res) && res.state !== undefined && res.state !== "merged")
+                return { merged: false, reason: `the merge request is ${String(res.state)}` };
+            return { merged: true, ...(sha ? { sha } : {}) };
+        },
+    };
+}
+/** Thrown when the environment lacks what a forge client needs. */
+export class ForgeEnvironmentError extends Error {
+    /**
+     * @param kind The forge, or undefined when the environment does not say which.
+     * @param missing What is missing, each naming the variable to set.
+     */
+    constructor(kind, missing) {
+        super(kind
+            ? `--forge ${kind} needs ${missing.join(", ")} in the environment`
+            : "the forge is not known: this is not a GitHub Actions, GitLab CI or Forgejo Actions job, so name the forge");
+        this.kind = kind;
+        this.missing = missing;
+        this.name = "ForgeEnvironmentError";
+    }
+}
+const hostOf = (url) => {
+    if (!url)
+        return undefined;
+    try {
+        return new URL(url).host.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * A client for `kind` from the CI job's environment, as the pull-request
+ * loop reads it. The token is `CHANT_FORGE_TOKEN` when set, else the forge's
+ * own: `GITHUB_TOKEN` (also set on Forgejo Actions) or `GITLAB_TOKEN`.
+ * GitLab's `CI_JOB_TOKEN` cannot write notes, so a GitLab pipeline names a
+ * project access token. {@link forgeTargetFromEnv} is the general reading,
+ * with the finding modes' token order.
+ */
+export function forgeFromEnv(kind, env = process.env, fetchImpl) {
+    const f = fetchImpl ? { fetch: fetchImpl } : {};
+    if (kind === "gitlab") {
+        const token = env.CHANT_FORGE_TOKEN ?? env.GITLAB_TOKEN;
+        const missing = [
+            ...(env.CI_API_V4_URL ? [] : ["CI_API_V4_URL"]),
+            ...(env.CI_PROJECT_ID ? [] : ["CI_PROJECT_ID"]),
+            ...(token ? [] : ["CHANT_FORGE_TOKEN (a token with the api scope)"]),
+        ];
+        if (missing.length > 0)
+            throw new ForgeEnvironmentError(kind, missing);
+        return gitlabForge({
+            apiBase: env.CI_API_V4_URL,
+            project: env.CI_PROJECT_ID,
+            token: token,
+            host: env.CI_SERVER_HOST ?? hostOf(env.CI_SERVER_URL) ?? "gitlab.com",
+            ...(env.CI_PIPELINE_URL ? { runUrl: env.CI_PIPELINE_URL } : {}),
+            ...f,
+        });
+    }
+    const token = env.CHANT_FORGE_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    const host = hostOf(env.GITHUB_SERVER_URL);
+    const missing = [
+        ...(env.GITHUB_REPOSITORY ? [] : ["GITHUB_REPOSITORY"]),
+        ...(token ? [] : ["GITHUB_TOKEN or CHANT_FORGE_TOKEN"]),
+        ...(kind === "forgejo" && !host ? ["GITHUB_SERVER_URL"] : []),
+        ...(kind === "forgejo" && !env.GITHUB_API_URL ? ["GITHUB_API_URL"] : []),
+    ];
+    if (missing.length > 0)
+        throw new ForgeEnvironmentError(kind, missing);
+    const runUrl = env.GITHUB_SERVER_URL && env.GITHUB_RUN_ID
+        ? `${env.GITHUB_SERVER_URL.replace(/\/+$/, "")}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`
+        : undefined;
+    const opts = {
+        apiBase: env.GITHUB_API_URL ?? "https://api.github.com",
+        repo: env.GITHUB_REPOSITORY,
+        token: token,
+        ...(runUrl ? { runUrl } : {}),
+        ...f,
+    };
+    return kind === "forgejo" ? forgejoForge({ ...opts, host: host }) : githubForge({ ...opts, host: host ?? "github.com" });
+}
+const truthy = (v) => v === "true" || v === "1";
+/**
+ * The forge a CI job runs on, from its environment, or undefined outside a
+ * GitHub Actions, GitLab CI or Forgejo Actions job. Forgejo is told apart by
+ * `FORGEJO_ACTIONS` or `GITEA_ACTIONS`, or by a GitHub-style job whose
+ * `GITHUB_API_URL` ends in `/api/v1`, which GitHub never serves.
+ */
+export function detectForge(env = process.env) {
+    if (truthy(env.GITLAB_CI))
+        return "gitlab";
+    if (truthy(env.FORGEJO_ACTIONS) || truthy(env.GITEA_ACTIONS))
+        return "forgejo";
+    if (truthy(env.GITHUB_ACTIONS))
+        return /\/api\/v1\/?$/.test(env.GITHUB_API_URL ?? "") ? "forgejo" : "github";
+    return undefined;
+}
+/**
+ * The token order {@link forgeTargetFromEnv} reads, as guide/ops documents
+ * it: a chant-specific variable first, for posting to an instance other than
+ * the one the job runs on, then what the job already carries (#3802). A
+ * Forgejo job reads `FORGEJO_TOKEN` before the `GITHUB_*` names, and the
+ * GitHub row has its own chant variable rather than the Forgejo one.
+ */
+export const FORGE_TOKEN_ORDER = {
+    github: ["CHANT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
+    forgejo: ["CHANT_FORGEJO_TOKEN", "FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"],
+    gitlab: ["CHANT_GITLAB_TOKEN", "GITLAB_TOKEN", "CI_JOB_TOKEN"],
+};
+/** The pull request and its head from a GitHub-style event payload, or from the ref. */
+function prFromEvent(payload, ref) {
+    const out = {};
+    if (isObject(payload)) {
+        const pr = isObject(payload.pull_request) ? payload.pull_request : undefined;
+        const issue = isObject(payload.issue) ? payload.issue : undefined;
+        const n = num(pr?.number) ?? (issue && isObject(issue.pull_request) ? num(issue.number) : undefined) ?? (pr ? num(payload.number) : undefined);
+        if (n !== undefined && n > 0)
+            out.pr = n;
+        const head = pr && isObject(pr.head) ? str(pr.head.sha) : undefined;
+        if (head)
+            out.sha = head;
+    }
+    if (out.pr === undefined) {
+        const m = /^refs\/pull\/(\d+)\/(?:merge|head)$/.exec(ref ?? "");
+        if (m)
+            out.pr = Number(m[1]);
+    }
+    return out;
+}
+/**
+ * Where a CI job posts, read from its environment: the forge
+ * ({@link detectForge} unless `kind` is given), the repository, the REST
+ * base, the host, the token, and the pull request and its head commit when
+ * the run has them. Throws {@link ForgeEnvironmentError} naming every
+ * missing piece.
+ *
+ * - GitHub Actions: `GITHUB_REPOSITORY`, `GITHUB_API_URL` (default
+ *   `https://api.github.com`), `GITHUB_SERVER_URL`; the pull request from
+ *   the event payload at `GITHUB_EVENT_PATH` or `refs/pull/<n>/` in
+ *   `GITHUB_REF`, its head from the payload, else `GITHUB_SHA`.
+ * - Forgejo Actions: the same, with `FORGEJO_*` read before `GITHUB_*`,
+ *   and the REST base `<server>/api/v1` when no API URL is set.
+ * - GitLab CI: `CI_API_V4_URL` (or `CI_SERVER_URL/api/v4`), the merge
+ *   request's project before the pipeline's (a fork's merge request runs in
+ *   the fork), `CI_MERGE_REQUEST_IID`, `CI_COMMIT_SHA`, `CI_PIPELINE_URL`.
+ *
+ * The token is read in {@link FORGE_TOKEN_ORDER}, or from `tokenEnv` alone.
+ */
+export function forgeTargetFromEnv(env = process.env, opts = {}) {
+    const kind = opts.kind ?? detectForge(env);
+    if (!kind)
+        throw new ForgeEnvironmentError(undefined, []);
+    const pick = (...names) => names.map((n) => env[n]?.trim()).find((v) => v !== undefined && v !== "");
+    const names = opts.tokenEnv ? [opts.tokenEnv] : FORGE_TOKEN_ORDER[kind];
+    const tokenSource = names.find((n) => env[n]?.trim());
+    const token = tokenSource ? env[tokenSource].trim() : undefined;
+    const missing = [];
+    const tokenMissing = `a token (${names.join(", ")})`;
+    if (kind === "gitlab") {
+        const server = pick("CI_SERVER_URL")?.replace(/\/+$/, "");
+        const apiBase = pick("CI_API_V4_URL")?.replace(/\/+$/, "") ?? (server ? `${server}/api/v4` : undefined);
+        const repo = pick("CI_MERGE_REQUEST_PROJECT_ID", "CI_PROJECT_ID", "CI_MERGE_REQUEST_PROJECT_PATH", "CI_PROJECT_PATH");
+        const iid = num(pick("CI_MERGE_REQUEST_IID"));
+        if (!apiBase)
+            missing.push("CI_API_V4_URL");
+        if (!repo)
+            missing.push("CI_PROJECT_ID");
+        if (opts.requirePr && !iid)
+            missing.push("CI_MERGE_REQUEST_IID (a merge request pipeline)");
+        if (!token)
+            missing.push(tokenMissing);
+        if (missing.length > 0)
+            throw new ForgeEnvironmentError(kind, missing);
+        const sha = pick("CI_MERGE_REQUEST_SOURCE_BRANCH_SHA", "CI_COMMIT_SHA");
+        const runUrl = pick("CI_PIPELINE_URL");
+        return {
+            kind,
+            apiBase: apiBase,
+            repo: repo,
+            host: pick("CI_SERVER_HOST")?.toLowerCase() ?? hostOf(server) ?? hostOf(apiBase) ?? "gitlab.com",
+            token: token,
+            tokenSource: tokenSource,
+            tokenHeader: tokenSource === "CI_JOB_TOKEN" ? "JOB-TOKEN" : "PRIVATE-TOKEN",
+            ...(iid ? { pr: iid } : {}),
+            ...(sha ? { sha } : {}),
+            ...(runUrl ? { runUrl } : {}),
+        };
+    }
+    const fj = kind === "forgejo";
+    const read = (name) => (fj ? pick(`FORGEJO_${name}`, `GITHUB_${name}`) : pick(`GITHUB_${name}`));
+    const repo = read("REPOSITORY");
+    const server = read("SERVER_URL")?.replace(/\/+$/, "");
+    const apiBase = read("API_URL")?.replace(/\/+$/, "") ?? (fj ? (server ? `${server}/api/v1` : undefined) : "https://api.github.com");
+    let event;
+    const eventPath = read("EVENT_PATH");
+    if (eventPath) {
+        try {
+            event = JSON.parse((opts.readFile ?? ((p) => readFileSync(p, "utf8")))(eventPath));
+        }
+        catch {
+            // An unreadable payload is not fatal: the ref may still name the pull request.
+            event = undefined;
+        }
+    }
+    const { pr, sha: head } = prFromEvent(event, read("REF"));
+    if (!repo)
+        missing.push(fj ? "FORGEJO_REPOSITORY or GITHUB_REPOSITORY" : "GITHUB_REPOSITORY");
+    if (!apiBase)
+        missing.push("GITHUB_SERVER_URL or GITHUB_API_URL");
+    if (opts.requirePr && !pr)
+        missing.push("a pull request (a pull_request event, or refs/pull/<n>/ in GITHUB_REF)");
+    if (!token)
+        missing.push(tokenMissing);
+    if (missing.length > 0)
+        throw new ForgeEnvironmentError(kind, missing);
+    const sha = head ?? read("SHA");
+    const runId = read("RUN_ID");
+    const runUrl = server && runId ? `${server}/${repo}/actions/runs/${runId}` : undefined;
+    return {
+        kind,
+        apiBase: apiBase,
+        repo: repo,
+        host: hostOf(server) ?? (fj ? hostOf(apiBase) : "github.com"),
+        token: token,
+        tokenSource: tokenSource,
+        ...(pr ? { pr } : {}),
+        ...(sha ? { sha } : {}),
+        ...(runUrl ? { runUrl } : {}),
+    };
+}
+/** The client for a {@link ForgeTarget}, from {@link forgeTargetFromEnv} or built by hand. */
+export function forgeClient(target, fetchImpl) {
+    const f = fetchImpl ? { fetch: fetchImpl } : {};
+    const run = target.runUrl ? { runUrl: target.runUrl } : {};
+    if (target.kind === "gitlab") {
+        return gitlabForge({
+            apiBase: target.apiBase,
+            project: target.repo,
+            token: target.token,
+            host: target.host,
+            ...(target.tokenHeader ? { tokenHeader: target.tokenHeader } : {}),
+            ...run,
+            ...f,
+        });
+    }
+    const opts = { apiBase: target.apiBase, repo: target.repo, token: target.token, host: target.host, ...run, ...f };
+    return target.kind === "forgejo" ? forgejoForge(opts) : githubForge(opts);
+}