@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/gfm.js

@@ -0,0 +1,244 @@
+// GFM tables on commonmark.js: the parse the web app renders pages from
+// (packages/ui/src/markdown.ts), and search's text snippets read (`plainText` in
+// search.ts), so a snippet holds exactly the words the page shows.
+import { Node, Parser } from "commonmark";
+/**
+ * Whether a line, indented as it was, starts a block of its own: CommonMark's own grammar,
+ * by parsing the line alone. A table row is a paragraph; a list item, indented code or an
+ * HTML tag isn't, and in GFM it ends the table.
+ */
+function startsBlock(line, indent) {
+    const first = new Parser().parse(" ".repeat(indent) + line).firstChild;
+    return first !== null && first.type !== "paragraph";
+}
+/** A row's cells: outer pipes optional, `\|` is a pipe inside a cell (in code too, as GFM). */
+function cellsOf(line) {
+    let s = line.trim();
+    if (s.startsWith("|"))
+        s = s.slice(1);
+    if (s.endsWith("|") && !s.endsWith("\\|"))
+        s = s.slice(0, -1);
+    return s.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, "|"));
+}
+/** The alignments a delimiter row (`| :--- | ---: |`) sets, or null if the line isn't one. */
+function delimiterRow(line) {
+    if (!line.includes("|"))
+        return null;
+    const cells = cellsOf(line);
+    if (!cells.every((c) => /^:?-+:?$/.test(c)))
+        return null;
+    return cells.map((c) => (c.startsWith(":") ? (c.endsWith(":") ? "center" : "left") : c.endsWith(":") ? "right" : null));
+}
+/** A node that renders as the given fixed tags around its children. Blocks get their own line. */
+function custom(type, onEnter, onExit) {
+    const n = new Node(type);
+    n.onEnter = onEnter;
+    n.onExit = onExit;
+    return n;
+}
+/**
+ * Replace `block` (a paragraph, or a setext heading with its `underline`) with the table its
+ * text holds, if it holds one. `info[i]` is what line i was.
+ */
+function rebuildTable(block, text, info, underline, budget, inlines, blocks) {
+    const lines = text.replace(/\n$/, "").split("\n");
+    const endsTable = (i) => info[i]?.lazy || startsBlock(lines[i], info[i]?.indent ?? 0);
+    for (let h = 0; h + 1 < lines.length; h++) {
+        if (info[h]?.lazy || info[h + 1]?.lazy)
+            continue;
+        const align = delimiterRow(lines[h + 1]);
+        if (!align || cellsOf(lines[h]).length !== align.length)
+            continue;
+        let end = h + 2;
+        while (end < lines.length && !endsTable(end))
+            end++;
+        const setext = block.type === "heading";
+        const rule = setext && /^-{3,}$/.test(underline);
+        const early = end < lines.length;
+        const bodyLines = [...lines.slice(h + 2, end), ...(setext && !rule && !early ? [underline] : [])];
+        // Padding a short row costs no input, so a table's cells could outgrow the page by far
+        // (800 header cells and 800 one-cell rows). A table past the page's budget stays text.
+        const cells = align.length * (1 + bodyLines.length);
+        if (cells > budget.cells)
+            return;
+        budget.cells -= cells;
+        const row = (line, tag) => {
+            const tr = custom("custom_block", "<tr>", "</tr>");
+            const cells = cellsOf(line);
+            align.forEach((a, i) => {
+                const cell = custom("custom_inline", a ? `<${tag} class="dw-align-${a}">` : `<${tag}>`, `</${tag}>`);
+                const content = inlines(cells[i] ?? "");
+                while (content.firstChild)
+                    cell.appendChild(content.firstChild);
+                tr.appendChild(cell);
+            });
+            return tr;
+        };
+        const table = custom("custom_block", '<div class="dw-table-scroll"><table>', "</table></div>");
+        const head = custom("custom_block", "<thead>", "</thead>");
+        head.appendChild(row(lines[h], "th"));
+        table.appendChild(head);
+        if (bodyLines.length > 0) {
+            const body = custom("custom_block", "<tbody>", "</tbody>");
+            for (const line of bodyLines)
+                body.appendChild(row(line, "td"));
+            table.appendChild(body);
+        }
+        if (h > 0)
+            block.insertBefore(inlines(lines.slice(0, h).join("\n")));
+        block.insertBefore(table);
+        if (early) {
+            // The lines after the table, indented as they were, read as blocks again.
+            const rest = blocks(lines.slice(end).map((line, i) => " ".repeat(info[end + i]?.indent ?? 0) + line).join("\n"));
+            while (rest.firstChild)
+                block.insertBefore(rest.firstChild);
+        }
+        if (rule)
+            block.insertBefore(new Node("thematic_break"));
+        else if (setext && early)
+            block.insertBefore(inlines(underline));
+        block.unlink();
+        return;
+    }
+}
+/**
+ * commonmark.js's tree, with GFM tables as tables. `refmap`: link definitions from the page
+ * this text was cut from (the blocks after a table), which its own may add to. `budget.left`:
+ * how many more characters may be parsed again after tables, for the whole page. Tables chained
+ * in one paragraph (each ended by a line that can't interrupt it) re-parse ever shorter tails,
+ * which is quadratic, and nests a parse per table; page text is untrusted, so past eight
+ * times the page's length, or 16 tables deep, the tail is read as plain CommonMark instead
+ * (its tables as text). Real pages chain a table or two.
+ */
+function parse(markdown, refmap, budget = { left: 8 * markdown.length, cells: markdown.length }, depth = 0) {
+    const parser = new Parser();
+    const internals = parser;
+    const inline = internals.inlineParser;
+    const { addLine, processInlines } = internals;
+    if (typeof inline?.parse !== "function" || typeof addLine !== "function" || typeof processInlines !== "function")
+        return parser.parse(markdown);
+    internals.processInlines = function (block) {
+        // The tail's own definitions win: GitHub links a label defined again after a table to
+        // that later definition.
+        this.refmap = { ...refmap, ...this.refmap };
+        processInlines.call(this, block);
+    };
+    // Each line a paragraph is given: whether it came lazily (its containers unmatched), and its
+    // indent. Keyed by the paragraph's sourcepos array: commonmark.js updates it in place, and a
+    // setext heading made from the paragraph is given the same array.
+    const lineInfo = new WeakMap();
+    internals.addLine = function () {
+        const key = this.tip.sourcepos;
+        if (this.tip.type === "paragraph" && key) {
+            let lines = lineInfo.get(key);
+            if (!lines)
+                lineInfo.set(key, (lines = []));
+            lines.push({ lazy: !this.allClosed, indent: this.indent });
+        }
+        addLine.call(this);
+    };
+    // The placeholder is never a link definition: redacted, `[term](page.md): word` reads
+    // `[restricted page]: word`, which CommonMark would take as one and drop from the page.
+    const { parseReference } = inline;
+    if (typeof parseReference === "function")
+        inline.parseReference = (s, refmap) => (PLACEHOLDER_DEFINITION.test(s) ? 0 : parseReference.call(inline, s, refmap));
+    const parseInlines = inline.parse.bind(inline);
+    const raw = new Map();
+    inline.parse = (block) => {
+        const text = block._string_content;
+        if ((block.type === "paragraph" || block.type === "heading") && text?.includes("|"))
+            raw.set(block, text);
+        parseInlines(block);
+    };
+    const doc = parser.parse(markdown);
+    const inlines = (text) => {
+        const p = new Node("paragraph");
+        p._string_content = text;
+        parseInlines(p);
+        return p;
+    };
+    const source = markdown.split(/\r\n|\n|\r/);
+    for (const [block, text] of raw) {
+        // Reference definitions are taken from the front of a paragraph: its last lines are the text's.
+        const lines = text.replace(/\n$/, "").split("\n").length;
+        // A setext heading ends on its underline's line, at the underline's last character.
+        const [endLine = 0, endCol = 0] = block.sourcepos?.[1] ?? [];
+        const underline = block.type === "heading" ? (/([=-]+)\s*$/.exec(source[endLine - 1]?.slice(0, endCol) ?? "")?.[1] ?? "") : "";
+        const blocks = (rest) => {
+            if (rest.length > budget.left || depth >= 16)
+                return new Parser().parse(rest);
+            budget.left -= rest.length;
+            return parse(rest, internals.refmap, budget, depth + 1);
+        };
+        rebuildTable(block, text, ((block.sourcepos && lineInfo.get(block.sourcepos)) || []).slice(-lines), underline, budget, inlines, blocks);
+    }
+    return doc;
+}
+/**
+ * `[restricted page]` (`RESTRICTED`, src/core/acl.ts): the placeholder redaction leaves for a
+ * link to a page the caller can't see. Not imported: acl.ts would bring its dependencies into
+ * the web app.
+ */
+const PLACEHOLDER = "[restricted page]";
+const MAX_NESTING = 32;
+const PLACEHOLDER_DEFINITION = /^\[\s*restricted\s+page\s*\]:/i;
+/**
+ * commonmark.js's tree for `markdown`, with GFM tables as tables (see above). The placeholder
+ * is never a link or an image, whatever a page writes around it: a definition for it, a
+ * `(target)` or `[label]` right after the link redaction replaced, or a link around it. A
+ * link or image labelled "restricted page" becomes the placeholder's text, and one whose
+ * label holds the placeholder becomes its label's text.
+ */
+export function parseGfm(markdown) {
+    const doc = parse(markdown);
+    // Links and images nested deeper than MAX_NESTING are read as their text. Each check below
+    // walks what's inside a link, so unbounded nesting would make it quadratic (page text is
+    // untrusted); 32 levels is far past anything a page means.
+    const deep = [];
+    let nesting = 0;
+    const outer = doc.walker();
+    for (let e = outer.next(); e; e = outer.next()) {
+        if (e.node.type !== "link" && e.node.type !== "image")
+            continue;
+        if (!e.entering)
+            nesting--;
+        else if (++nesting > MAX_NESTING)
+            deep.push(e.node);
+    }
+    for (const n of deep) {
+        while (n.firstChild)
+            n.insertBefore(n.firstChild);
+        n.unlink();
+    }
+    // Innermost first: a link is judged by its label once what's inside it is replaced, so an
+    // image inside a link that becomes the placeholder takes the link's target away too.
+    const links = [];
+    const walker = doc.walker();
+    for (let e = walker.next(); e; e = walker.next())
+        if (!e.entering && (e.node.type === "link" || e.node.type === "image"))
+            links.push(e.node);
+    for (const n of links) {
+        const label = textIn(n).replace(/\s+/g, " ").trim();
+        const literal = `[${label.toLowerCase()}]` === PLACEHOLDER ? PLACEHOLDER : label.toLowerCase().includes(PLACEHOLDER) ? label : null;
+        if (literal === null)
+            continue;
+        const text = new Node("text");
+        text.literal = literal;
+        n.insertBefore(text);
+        n.unlink();
+    }
+    return doc;
+}
+/** The text and code inside `node`: a link's or image's label, as the reader sees it. */
+export function textIn(node) {
+    let out = "";
+    const walker = node.walker();
+    for (let e = walker.next(); e; e = walker.next())
+        if (e.entering && (e.node.type === "text" || e.node.type === "code"))
+            out += e.node.literal ?? "";
+    return out;
+}
+/** A table cell (`th` or `td`) in a tree from `parseGfm`; its children are the cell's content. */
+export function isTableCell(node) {
+    return node.type === "custom_inline" && /^<t[hd][\s>]/.test(node.onEnter ?? "");
+}

package/dist/core/github.d.ts

@@ -0,0 +1,152 @@
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+export declare class GitHubError extends Error {
+    /** The HTTP status; 0 when GitHub didn't answer (a network error or a timeout). */
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    /** Response headers, e.g. `x-github-sso` on a 403 from an SSO-enforcing org. */
+    readonly headers: Headers | null;
+    /** GitHub's rate limits: a 429, or a 403 that says so (primary or secondary limit). */
+    readonly rateLimited: boolean;
+    /** Seconds GitHub asked to wait (`retry-after`, or until `x-ratelimit-reset`), if it said. */
+    readonly retryAfter: number | null;
+    constructor(
+    /** The HTTP status; 0 when GitHub didn't answer (a network error or a timeout). */
+    status: number, method: string, path: string, message: string, 
+    /** Response headers, e.g. `x-github-sso` on a 403 from an SSO-enforcing org. */
+    headers?: Headers | null, now?: number);
+}
+export interface RepoInfo {
+    full_name: string;
+    default_branch: string;
+    private: boolean;
+    permissions?: {
+        admin?: boolean;
+        push?: boolean;
+        pull?: boolean;
+    };
+    owner?: {
+        login: string;
+        id: number;
+    };
+}
+export interface TeamInfo {
+    slug: string;
+    organization: {
+        login: string;
+    };
+}
+export interface ContentFile {
+    sha: string;
+    content: string;
+    encoding: string;
+    path: string;
+}
+export interface PullInfo {
+    number: number;
+    html_url: string;
+    head: {
+        ref: string;
+    };
+    base: {
+        ref: string;
+    };
+}
+export declare class GitHubClient {
+    private readonly token;
+    private readonly fetch;
+    private readonly baseUrl;
+    private readonly sleep;
+    private readonly now;
+    private readonly timeoutMs;
+    constructor(token: string, opts?: {
+        fetch?: FetchLike;
+        baseUrl?: string;
+        sleep?: (ms: number) => Promise<void>;
+        now?: () => number;
+        timeoutMs?: number;
+    });
+    request<T>(method: string, path: string, body?: unknown, accept?: string): Promise<{
+        data: T;
+        headers: Headers;
+    }>;
+    private get;
+    /** Follow `Link: rel="next"` pagination; `onHeaders` sees every page's headers. */
+    paginate<T>(path: string, onHeaders?: (h: Headers) => void): Promise<T[]>;
+    getUser(): Promise<{
+        login: string;
+    }>;
+    getRepo(repo: string): Promise<RepoInfo>;
+    /**
+     * The caller's teams, and the ids of orgs GitHub left out because the token isn't
+     * authorized for their SAML SSO (`x-github-sso: partial-results; organizations=…`).
+     */
+    listMyTeams(): Promise<{
+        teams: TeamInfo[];
+        ssoWithheldOrgIds: string[];
+    }>;
+    /** Logins of a team's members (needs read:org, or members:read on a fine-grained token). */
+    listTeamMembers(org: string, team: string): Promise<string[]>;
+    /**
+     * Does a team have write access to a repo? GitHub ignores a CODEOWNERS team without it.
+     * true/false when GitHub shows the permission; null on a 404, which GitHub gives both
+     * for "no access" and for a team this caller can't see, so it proves nothing.
+     */
+    teamCanPush(org: string, team: string, repo: string): Promise<boolean | null>;
+    /** A user's permission on a repo: admin, maintain, write, triage, read or none. */
+    getUserPermission(repo: string, login: string): Promise<string>;
+    /** Ruleset rules that apply to a branch (readable with read access). */
+    getBranchRules(repo: string, branch: string): Promise<{
+        type: string;
+        parameters?: Record<string, unknown>;
+        ruleset_id?: number;
+    }[]>;
+    /** A ruleset, with `bypass_actors` when this token may see them (admins). */
+    getRuleset(repo: string, id: number): Promise<{
+        bypass_actors?: {
+            actor_type: string;
+            bypass_mode?: string;
+        }[];
+    }>;
+    /** Classic branch protection (GitHub answers 403/404 to callers without admin). */
+    getBranchProtection(repo: string, branch: string): Promise<{
+        required_pull_request_reviews?: {
+            require_code_owner_reviews?: boolean;
+            bypass_pull_request_allowances?: {
+                users?: unknown[];
+                teams?: unknown[];
+                apps?: unknown[];
+            };
+        };
+        enforce_admins?: {
+            enabled?: boolean;
+        };
+    }>;
+    getFile(repo: string, path: string, ref: string): Promise<ContentFile>;
+    getBranchSha(repo: string, branch: string): Promise<string>;
+    createBranch(repo: string, branch: string, sha: string): Promise<void>;
+    deleteBranch(repo: string, branch: string): Promise<void>;
+    /** Always pass `branch`: omitting it makes GitHub write to the default branch. */
+    putFile(repo: string, path: string, args: {
+        message: string;
+        content: string;
+        sha: string | undefined;
+        branch: string;
+    }): Promise<void>;
+    /** An open PR from `branch` into `base` in the same repo, if one exists. */
+    findPull(repo: string, branch: string, base: string): Promise<PullInfo | null>;
+    createPull(repo: string, args: {
+        title: string;
+        head: string;
+        base: string;
+        body: string;
+        draft?: boolean;
+    }): Promise<PullInfo>;
+}
+/** `required; url=https://…` or `partial-results; organizations=1,2`. */
+export declare function parseSsoHeader(value: string | null): {
+    required: boolean;
+    url: string | null;
+    organizations: string[];
+};
+export declare function decodeContent(file: ContentFile): string;

package/dist/core/github.js

@@ -0,0 +1,234 @@
+// Minimal GitHub REST client over fetch. Deliberately small: every call the server makes
+// is listed here, which keeps the write path reviewable and lets tests inject a fake.
+import { insecureUrl, urlForError } from "./url.js";
+export class GitHubError extends Error {
+    status;
+    method;
+    path;
+    headers;
+    /** GitHub's rate limits: a 429, or a 403 that says so (primary or secondary limit). */
+    rateLimited;
+    /** Seconds GitHub asked to wait (`retry-after`, or until `x-ratelimit-reset`), if it said. */
+    retryAfter;
+    constructor(
+    /** The HTTP status; 0 when GitHub didn't answer (a network error or a timeout). */
+    status, method, path, message, 
+    /** Response headers, e.g. `x-github-sso` on a 403 from an SSO-enforcing org. */
+    headers = null, now = Date.now()) {
+        const limited = status === 429 ||
+            // GitHub's secondary limits come as a 403 (or 429) with `retry-after`, its primary
+            // limit with `x-ratelimit-remaining: 0`; the message says so too.
+            (status === 403 && (headers?.get("x-ratelimit-remaining") === "0" || Boolean(headers?.has("retry-after")) || /rate limit/i.test(message)));
+        const after = Number(headers?.get("retry-after"));
+        const reset = Number(headers?.get("x-ratelimit-reset"));
+        const wait = Number.isFinite(after) && headers?.has("retry-after") ? after : limited && Number.isFinite(reset) && reset > 0 ? Math.max(0, Math.ceil(reset - now / 1000)) : null;
+        super(`GitHub ${method} ${path} → ${status || "no answer"}: ${message}${limited ? ` (rate limited${wait !== null ? `; retry in ${wait} s` : ""})` : ""}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.headers = headers;
+        this.rateLimited = limited;
+        this.retryAfter = wait;
+    }
+}
+// Reads are retried on what passes (no answer, a 5xx, a rate limit GitHub says lifts
+// within a few seconds); writes never are, since a retried POST could open a second PR.
+const ATTEMPTS = 3;
+const BACKOFF_MS = [500, 1500];
+const MAX_WAIT_S = 10;
+const TIMEOUT_MS = 30_000;
+export class GitHubClient {
+    token;
+    fetch;
+    baseUrl;
+    sleep;
+    now;
+    timeoutMs;
+    constructor(token, opts = {}) {
+        this.token = token;
+        this.fetch = opts.fetch ?? ((url, init) => fetch(url, init));
+        this.baseUrl = (opts.baseUrl ?? "https://api.github.com").replace(/\/$/, "");
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.now = opts.now ?? Date.now;
+        this.timeoutMs = opts.timeoutMs ?? TIMEOUT_MS;
+        // Also reached from DOCSWORTH_GITHUB_API_URL, which no config schema sees.
+        const why = insecureUrl(this.baseUrl);
+        if (why)
+            throw new Error(`the GitHub API URL (${urlForError(this.baseUrl)}) ${why}`);
+    }
+    async request(method, path, body, accept = "application/vnd.github+json") {
+        const read = method === "GET" || method === "HEAD";
+        // Serialized once, outside the retry: a body that can't be (a fault here) throws as is.
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        for (let attempt = 1;; attempt++) {
+            let res;
+            let text;
+            try {
+                res = await this.fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${this.token}`,
+                        accept,
+                        "x-github-api-version": "2022-11-28",
+                        "user-agent": "docsworth",
+                        ...(body === undefined ? {} : { "content-type": "application/json" }),
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+                text = await res.text();
+            }
+            catch (cause) {
+                // No answer: the connection failed (fetch's TypeError, or undici's "terminated" when
+                // it drops while the body is read), or nothing came within the timeout. Anything
+                // else is a fault here, not GitHub's, and isn't retried.
+                const timedOut = cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
+                if (!timedOut && !(cause instanceof TypeError))
+                    throw cause;
+                const err = new GitHubError(0, method, path, timedOut ? `no answer within ${this.timeoutMs / 1000} s` : `network error (${cause.message})`, null, this.now());
+                if (read && attempt < ATTEMPTS) {
+                    await this.sleep(BACKOFF_MS[attempt - 1]);
+                    continue;
+                }
+                throw err;
+            }
+            if (!res.ok) {
+                let message = text.slice(0, 300);
+                try {
+                    message = JSON.parse(text).message ?? message;
+                }
+                catch {
+                    /* non-JSON error body */
+                }
+                const err = new GitHubError(res.status, method, path, message, res.headers, this.now());
+                // A 5xx is retried on the backoff. A rate limit only when GitHub says it lifts
+                // within 10 s: without a time, retrying soon prolongs it (GitHub asks for a minute).
+                const wait = err.rateLimited ? (err.retryAfter !== null && err.retryAfter <= MAX_WAIT_S ? err.retryAfter * 1000 : null) : res.status >= 500 ? BACKOFF_MS[attempt - 1] : null;
+                if (read && wait !== null && attempt < ATTEMPTS) {
+                    await this.sleep(wait);
+                    continue;
+                }
+                throw err;
+            }
+            return { data: (text ? JSON.parse(text) : null), headers: res.headers };
+        }
+    }
+    async get(path) {
+        return (await this.request("GET", path)).data;
+    }
+    /** Follow `Link: rel="next"` pagination; `onHeaders` sees every page's headers. */
+    async paginate(path, onHeaders) {
+        const out = [];
+        let next = `${path}${path.includes("?") ? "&" : "?"}per_page=100`;
+        while (next) {
+            const { data, headers } = await this.request("GET", next);
+            onHeaders?.(headers);
+            out.push(...data);
+            const link = /<([^>]+)>;\s*rel="next"/.exec(headers.get("link") ?? "");
+            next = link ? link[1].replace(this.baseUrl, "") : null;
+        }
+        return out;
+    }
+    getUser() {
+        return this.get("/user");
+    }
+    getRepo(repo) {
+        return this.get(`/repos/${repo}`);
+    }
+    /**
+     * The caller's teams, and the ids of orgs GitHub left out because the token isn't
+     * authorized for their SAML SSO (`x-github-sso: partial-results; organizations=…`).
+     */
+    async listMyTeams() {
+        const withheld = new Set();
+        const teams = await this.paginate("/user/teams", (h) => {
+            for (const id of parseSsoHeader(h.get("x-github-sso")).organizations)
+                withheld.add(id);
+        });
+        return { teams, ssoWithheldOrgIds: [...withheld] };
+    }
+    /** Logins of a team's members (needs read:org, or members:read on a fine-grained token). */
+    async listTeamMembers(org, team) {
+        return (await this.paginate(`/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(team)}/members`)).map((m) => m.login);
+    }
+    /**
+     * Does a team have write access to a repo? GitHub ignores a CODEOWNERS team without it.
+     * true/false when GitHub shows the permission; null on a 404, which GitHub gives both
+     * for "no access" and for a team this caller can't see, so it proves nothing.
+     */
+    async teamCanPush(org, team, repo) {
+        try {
+            const { data } = await this.request("GET", `/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(team)}/repos/${repo}`, undefined, "application/vnd.github.v3.repository+json");
+            return Boolean(data?.permissions?.push);
+        }
+        catch (err) {
+            if (err instanceof GitHubError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /** A user's permission on a repo: admin, maintain, write, triage, read or none. */
+    async getUserPermission(repo, login) {
+        return (await this.get(`/repos/${repo}/collaborators/${encodeURIComponent(login)}/permission`)).permission;
+    }
+    /** Ruleset rules that apply to a branch (readable with read access). */
+    getBranchRules(repo, branch) {
+        return this.get(`/repos/${repo}/rules/branches/${encodePath(branch)}`);
+    }
+    /** A ruleset, with `bypass_actors` when this token may see them (admins). */
+    getRuleset(repo, id) {
+        return this.get(`/repos/${repo}/rulesets/${id}`);
+    }
+    /** Classic branch protection (GitHub answers 403/404 to callers without admin). */
+    getBranchProtection(repo, branch) {
+        return this.get(`/repos/${repo}/branches/${encodePath(branch)}/protection`);
+    }
+    getFile(repo, path, ref) {
+        return this.get(`/repos/${repo}/contents/${encodePath(path)}?ref=${encodeURIComponent(ref)}`);
+    }
+    async getBranchSha(repo, branch) {
+        return (await this.get(`/repos/${repo}/git/ref/heads/${encodePath(branch)}`)).object.sha;
+    }
+    async createBranch(repo, branch, sha) {
+        await this.request("POST", `/repos/${repo}/git/refs`, { ref: `refs/heads/${branch}`, sha });
+    }
+    async deleteBranch(repo, branch) {
+        await this.request("DELETE", `/repos/${repo}/git/refs/heads/${encodePath(branch)}`);
+    }
+    /** Always pass `branch`: omitting it makes GitHub write to the default branch. */
+    async putFile(repo, path, args) {
+        await this.request("PUT", `/repos/${repo}/contents/${encodePath(path)}`, {
+            message: args.message,
+            content: Buffer.from(args.content, "utf8").toString("base64"),
+            sha: args.sha,
+            branch: args.branch,
+        });
+    }
+    /** An open PR from `branch` into `base` in the same repo, if one exists. */
+    async findPull(repo, branch, base) {
+        const owner = repo.split("/")[0];
+        const q = `head=${encodeURIComponent(`${owner}:${branch}`)}&base=${encodeURIComponent(base)}&state=open`;
+        return (await this.get(`/repos/${repo}/pulls?${q}`))[0] ?? null;
+    }
+    async createPull(repo, args) {
+        return (await this.request("POST", `/repos/${repo}/pulls`, args)).data;
+    }
+}
+/** `required; url=https://…` or `partial-results; organizations=1,2`. */
+export function parseSsoHeader(value) {
+    if (!value)
+        return { required: false, url: null, organizations: [] };
+    const parts = value.split(";").map((p) => p.trim());
+    const field = (k) => parts.find((p) => p.startsWith(`${k}=`))?.slice(k.length + 1) ?? null;
+    return {
+        required: parts[0] === "required",
+        url: field("url"),
+        organizations: (field("organizations") ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+    };
+}
+function encodePath(p) {
+    return p.split("/").map(encodeURIComponent).join("/");
+}
+export function decodeContent(file) {
+    return Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8").toString("utf8");
+}