@intentius/sql-yodeler 0.1.0 → 0.3.0

package/dist/notify/index.js

@@ -0,0 +1,210 @@
+/**
+ * Webhook events (#61). `notify` in yodel.config.ts names the environment
+ * variables that hold a webhook's URL and its signing key (never the values
+ * themselves); `yodel apply`, `yodel plan` and `yodel drift` post an event
+ * when an environment is waiting for approval, when a run was refused or
+ * failed, and when drift is found:
+ *
+ * ```ts
+ * notify: { webhook: "YODEL_WEBHOOK_URL", key: "YODEL_WEBHOOK_KEY", slack: "SLACK_WEBHOOK_URL" }
+ * ```
+ *
+ * The webhook gets the event as JSON, signed (`./verify.ts`); a Slack
+ * incoming webhook, when `slack` names one, gets a line of text. A delivery
+ * that fails is reported on stderr and never changes the command's exit
+ * code: the event is news about the run, not part of it.
+ */
+import { randomUUID } from "node:crypto";
+import { DELIVERY_HEADER, EVENT_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER, signWebhook } from "./verify.js";
+export * from "./verify.js";
+export const NOTIFY_EVENTS = ["waiting", "refused", "failed", "drift"];
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Checks `notify` in yodel.config.ts; returns a message for the first problem, or undefined. */
+export function notifyConfigProblem(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return "notify: expected { webhook, key, slack?, events? }";
+    const v = value;
+    for (const k of Object.keys(v))
+        if (!["webhook", "key", "slack", "events"].includes(k))
+            return `notify.${k}: unknown setting (expected webhook, key, slack, events)`;
+    for (const k of ["webhook", "key", "slack"]) {
+        const n = v[k];
+        if (n === undefined)
+            continue;
+        if (typeof n !== "string" || n.includes("://") || !NAME.test(n)) {
+            return `notify.${k}: the name of the environment variable that holds the ${k === "key" ? "signing key" : "URL"} (such as ${k === "key" ? "YODEL_WEBHOOK_KEY" : k === "slack" ? "SLACK_WEBHOOK_URL" : "YODEL_WEBHOOK_URL"}), never the ${k === "key" ? "key" : "URL"} itself`;
+        }
+    }
+    if (v.webhook !== undefined && v.key === undefined)
+        return "notify.key: a webhook needs a signing key; name the variable that holds it";
+    if (v.key !== undefined && v.webhook === undefined)
+        return "notify.webhook: a key is for a webhook; name the variable that holds its URL";
+    if (v.webhook === undefined && v.slack === undefined)
+        return "notify: name a webhook (with its key) or a slack URL variable";
+    if (v.events !== undefined && !(Array.isArray(v.events) && v.events.every((e) => NOTIFY_EVENTS.includes(e)))) {
+        return `notify.events: a list of ${NOTIFY_EVENTS.join(", ")}`;
+    }
+    return undefined;
+}
+/** Where the CI run is, when yodel runs in one. */
+export function ciContext(env) {
+    const out = {};
+    if (env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY && env.GITHUB_RUN_ID)
+        out.runUrl = `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}`;
+    else if (env.CI_JOB_URL)
+        out.runUrl = env.CI_JOB_URL;
+    else if (env.CI_PIPELINE_URL)
+        out.runUrl = env.CI_PIPELINE_URL;
+    const repository = env.GITHUB_REPOSITORY ?? env.CI_PROJECT_PATH;
+    if (repository)
+        out.repository = repository;
+    const commit = env.GITHUB_SHA ?? env.CI_COMMIT_SHA;
+    if (commit)
+        out.commit = commit;
+    return out;
+}
+const ids = (list) => (Array.isArray(list) ? list.flatMap((p) => (typeof p === "object" && p !== null && typeof p.id === "string" ? [p.id] : [])) : []);
+const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+const firstLine = (s) => s.split("\n")[0] ?? s;
+/**
+ * The event for what `yodel apply --json` (or `yodel plan --json`) printed,
+ * or undefined when the outcome is not one an event is sent for.
+ */
+export function eventFromRun(command, doc) {
+    const status = str(doc.status) ?? (doc.refusal ? "refused" : undefined);
+    const environment = str(doc.environment) ?? "";
+    const migrations = ids(doc.pending);
+    const digest = str(doc.gatePlanDigest) ?? str(doc.planDigest);
+    const base = { environment, command, migrations, ...(digest ? { digest } : {}) };
+    const refusal = doc.refusal?.message;
+    const deniedRules = Array.isArray(doc.policy) ? doc.policy.filter((r) => r.outcome === "denied").map((r) => r.id ?? "") : [];
+    if (status === "gated") {
+        const approve = str(doc.approve);
+        return { ...base, event: "waiting", status, summary: `${environment} is waiting for approval of ${digest ?? "its plan"} (${String(migrations.length)} migration${migrations.length === 1 ? "" : "s"})`, ...(approve ? { approve } : {}) };
+    }
+    if (status === "refused" || status === "denied" || (command === "plan" && (refusal !== undefined || deniedRules.length > 0))) {
+        const reason = typeof refusal === "string" ? refusal : deniedRules.length > 0 ? `policy rule ${deniedRules.join(", ")} denies the plan` : status === "refused" ? "refused" : "denied by policy";
+        return { ...base, event: "refused", status: status ?? (refusal !== undefined ? "refused" : "denied"), summary: `${command} in ${environment} was refused: ${firstLine(reason)}`, reason };
+    }
+    if (status === "failed" || status === "incomplete") {
+        const code = typeof doc.exitCode === "number" ? doc.exitCode : undefined;
+        const reason = `${command} ${status}${code !== undefined ? ` (exit ${String(code)})` : ""}`;
+        return { ...base, event: "failed", status, summary: `${command} in ${environment} ${status}${code !== undefined ? ` with exit ${String(code)}` : ""}`, reason };
+    }
+    return undefined;
+}
+/** The event for what `yodel drift --json` printed, or undefined when nothing drifted. */
+export function eventFromDrift(doc) {
+    if (!doc.drifted)
+        return undefined;
+    const changed = (doc.changed ?? []).map((c) => c.name);
+    const missing = doc.missing ?? [];
+    const environment = doc.environment ?? "";
+    return {
+        event: "drift",
+        environment,
+        command: "drift",
+        status: "drifted",
+        migrations: [],
+        summary: `${environment} drifted: ${[changed.length > 0 ? `${changed.join(", ")} changed` : "", missing.length > 0 ? `${missing.join(", ")} missing` : ""].filter(Boolean).join("; ")}`,
+        drift: { changed, missing, ...(doc.fingerprint ? { fingerprint: doc.fingerprint } : {}) },
+    };
+}
+/** A whole event: the fields, with its id, time and the CI run. */
+export function makeEvent(fields, env = process.env, now = new Date()) {
+    return { version: 1, id: randomUUID(), at: now.toISOString(), ...fields, ...ciContext(env) };
+}
+/** The Slack message for an event: one line of text, with the approve command and the run on `waiting`. */
+export function slackMessage(e) {
+    const lines = [`yodel ${e.event}: ${e.summary}`];
+    if (e.approve)
+        lines.push(`Approve with: \`${e.approve}\``);
+    if (e.runUrl)
+        lines.push(`Run: ${e.runUrl}`);
+    return { text: lines.join("\n") };
+}
+/** The request that delivers `event` to the webhook, signed with `key`. */
+export function webhookRequest(event, key, now = Math.floor(Date.now() / 1000)) {
+    const body = JSON.stringify(event);
+    return {
+        body,
+        headers: {
+            "content-type": "application/json",
+            "user-agent": "sql-yodeler",
+            [EVENT_HEADER]: event.event,
+            [DELIVERY_HEADER]: event.id,
+            [TIMESTAMP_HEADER]: String(now),
+            [SIGNATURE_HEADER]: signWebhook(key, now, body),
+        },
+    };
+}
+async function post(fetchFn, url, request, attempts) {
+    let last = "";
+    for (let i = 0; i < attempts; i++) {
+        if (i > 0)
+            await new Promise((r) => setTimeout(r, 500 * i));
+        try {
+            const res = await fetchFn(url, { method: "POST", ...request, signal: AbortSignal.timeout(10_000) });
+            if (res.ok)
+                return undefined;
+            last = `HTTP ${String(res.status)}`;
+            // A 4xx will not change on a retry: the receiver refused the event (a signature it does not accept, say).
+            if (res.status < 500)
+                return last;
+        }
+        catch (e) {
+            last = e instanceof Error ? e.message : String(e);
+        }
+    }
+    return last;
+}
+/**
+ * Sends the event to what `config` names. Reads the URLs and the key from
+ * `env` at send time. Never throws: each delivery's outcome is returned and
+ * a failed one is written to `io.err`.
+ */
+export async function sendEvent(config, fields, options) {
+    if (!config || !fields)
+        return [];
+    if (config.events && !config.events.includes(fields.event))
+        return [];
+    const env = options.env ?? process.env;
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    const attempts = options.attempts ?? 3;
+    const event = makeEvent(fields, env);
+    const out = [];
+    const warn = (d) => {
+        options.io.err(`yodel ${options.verb}: notify: the ${fields.event} event was not delivered to the ${d.target}: ${d.detail}\n`);
+    };
+    if (config.webhook) {
+        const url = env[config.webhook];
+        const key = config.key ? env[config.key] : undefined;
+        let d;
+        if (!url)
+            d = { target: "webhook", ok: false, detail: `${config.webhook} is not set` };
+        else if (!key)
+            d = { target: "webhook", ok: false, detail: `${config.key ?? "the key variable"} is not set, and yodel does not send an unsigned event` };
+        else {
+            const failed = await post(fetchFn, url, webhookRequest(event, key), attempts);
+            d = { target: "webhook", ok: failed === undefined, detail: failed ?? "delivered" };
+        }
+        if (!d.ok)
+            warn(d);
+        out.push(d);
+    }
+    if (config.slack) {
+        const url = env[config.slack];
+        let d;
+        if (!url)
+            d = { target: "slack", ok: false, detail: `${config.slack} is not set` };
+        else {
+            const failed = await post(fetchFn, url, { headers: { "content-type": "application/json" }, body: JSON.stringify(slackMessage(event)) }, attempts);
+            d = { target: "slack", ok: failed === undefined, detail: failed ?? "delivered" };
+        }
+        if (!d.ok)
+            warn(d);
+        out.push(d);
+    }
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/notify/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/notify/index.ts"],"names":[],"mappings":"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"}

package/dist/notify/verify.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Signing and checking a yodel webhook event (#61). This module needs only
+ * node:crypto, so a receiver can import it alone:
+ *
+ * ```ts
+ * import { verifyWebhook } from "@intentius/sql-yodeler/webhook";
+ *
+ * const checked = verifyWebhook({ body, headers: req.headers, key: process.env.YODEL_WEBHOOK_KEY });
+ * if (!checked.ok) return reply(401, checked.reason);
+ * handle(checked.event);
+ * ```
+ *
+ * The signature is HMAC-SHA256, keyed with the secret, over
+ * `<timestamp>.<body>`: the `x-yodel-timestamp` header (seconds since the
+ * epoch), a dot, and the request body exactly as sent. It travels as
+ * `x-yodel-signature: sha256=<hex>`. Signing the timestamp with the body
+ * lets a receiver refuse a delivery replayed later; {@link verifyWebhook}
+ * refuses one older than five minutes by default.
+ */
+export declare const SIGNATURE_HEADER = "x-yodel-signature";
+export declare const TIMESTAMP_HEADER = "x-yodel-timestamp";
+export declare const EVENT_HEADER = "x-yodel-event";
+export declare const DELIVERY_HEADER = "x-yodel-delivery";
+/** How old a delivery {@link verifyWebhook} still accepts, in seconds. */
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/** `sha256=<hex>` of `<timestamp>.<body>`, keyed with `key`. */
+export declare function signWebhook(key: string, timestamp: number | string, body: string): string;
+export type WebhookHeaders = Record<string, string | readonly string[] | undefined> | Headers;
+export interface VerifyInput {
+    /** The request body exactly as received, before any JSON parsing. */
+    body: string | Uint8Array;
+    /** The request's headers; names are matched without regard to case. */
+    headers: WebhookHeaders;
+    /** The shared secret. An empty or missing key never verifies. */
+    key: string | undefined;
+    /** Now, in seconds since the epoch. Default: the clock. */
+    now?: number;
+    /** How old a delivery may be, in seconds. Default {@link DEFAULT_TOLERANCE_SECONDS}. */
+    toleranceSeconds?: number;
+}
+export type VerifyResult = {
+    ok: true;
+    event: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether a delivery was signed with `key` and is recent: the signature
+ * header matches (compared in constant time) and the timestamp is within the
+ * tolerance either side of now. On success, the parsed event.
+ */
+export declare function verifyWebhook(input: VerifyInput): VerifyResult;

package/dist/notify/verify.js

@@ -0,0 +1,71 @@
+/**
+ * Signing and checking a yodel webhook event (#61). This module needs only
+ * node:crypto, so a receiver can import it alone:
+ *
+ * ```ts
+ * import { verifyWebhook } from "@intentius/sql-yodeler/webhook";
+ *
+ * const checked = verifyWebhook({ body, headers: req.headers, key: process.env.YODEL_WEBHOOK_KEY });
+ * if (!checked.ok) return reply(401, checked.reason);
+ * handle(checked.event);
+ * ```
+ *
+ * The signature is HMAC-SHA256, keyed with the secret, over
+ * `<timestamp>.<body>`: the `x-yodel-timestamp` header (seconds since the
+ * epoch), a dot, and the request body exactly as sent. It travels as
+ * `x-yodel-signature: sha256=<hex>`. Signing the timestamp with the body
+ * lets a receiver refuse a delivery replayed later; {@link verifyWebhook}
+ * refuses one older than five minutes by default.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const SIGNATURE_HEADER = "x-yodel-signature";
+export const TIMESTAMP_HEADER = "x-yodel-timestamp";
+export const EVENT_HEADER = "x-yodel-event";
+export const DELIVERY_HEADER = "x-yodel-delivery";
+/** How old a delivery {@link verifyWebhook} still accepts, in seconds. */
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+/** `sha256=<hex>` of `<timestamp>.<body>`, keyed with `key`. */
+export function signWebhook(key, timestamp, body) {
+    return `sha256=${createHmac("sha256", key).update(`${String(timestamp)}.${body}`, "utf8").digest("hex")}`;
+}
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? undefined;
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() !== name)
+            continue;
+        return Array.isArray(v) ? v[0] : v;
+    }
+    return undefined;
+}
+/**
+ * Whether a delivery was signed with `key` and is recent: the signature
+ * header matches (compared in constant time) and the timestamp is within the
+ * tolerance either side of now. On success, the parsed event.
+ */
+export function verifyWebhook(input) {
+    if (!input.key)
+        return { ok: false, reason: "no key to verify with" };
+    const body = typeof input.body === "string" ? input.body : Buffer.from(input.body).toString("utf8");
+    const signature = header(input.headers, SIGNATURE_HEADER);
+    const timestamp = header(input.headers, TIMESTAMP_HEADER);
+    if (!signature)
+        return { ok: false, reason: `no ${SIGNATURE_HEADER} header` };
+    if (!timestamp || !/^\d+$/.test(timestamp))
+        return { ok: false, reason: `no ${TIMESTAMP_HEADER} header, or not a number of seconds` };
+    const expected = Buffer.from(signWebhook(input.key, timestamp, body));
+    const given = Buffer.from(signature);
+    if (given.length !== expected.length || !timingSafeEqual(given, expected))
+        return { ok: false, reason: "the signature does not match" };
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    if (Math.abs(now - Number(timestamp)) > tolerance)
+        return { ok: false, reason: `the timestamp is more than ${String(tolerance)}s from now` };
+    try {
+        return { ok: true, event: JSON.parse(body) };
+    }
+    catch {
+        return { ok: false, reason: "the body is not JSON" };
+    }
+}
+//# sourceMappingURL=verify.js.map

package/dist/notify/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/notify/verify.ts"],"names":[],"mappings":"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"}

package/dist/pr/forge.d.ts

@@ -46,5 +46,9 @@ export interface ForgeFlags {
 export declare function detectForge(env: NodeJS.ProcessEnv): ForgeKind | undefined;
 /** The PR number from a GitHub-style event payload, or from the ref. */
 export declare function prFromEvent(eventPath: string | undefined, ref: string | undefined): number | undefined;
+/** Where a job writes on its forge, without a pull request: the repository, the API and the token. */
+export type ForgeRepo = Omit<ForgeTarget, "pr">;
 /** Resolves the target from flags and the environment, or says what is missing. */
 export declare function resolveForgeTarget(flags: ForgeFlags, env: NodeJS.ProcessEnv): ForgeTarget;
+/** The repository a job writes to (`yodel drift --issue`), from flags and the environment, or says what is missing. */
+export declare function resolveForgeRepo(flags: Omit<ForgeFlags, "pr">, env: NodeJS.ProcessEnv, what?: string): ForgeRepo;

package/dist/pr/forge.js

@@ -56,13 +56,17 @@ const DEFAULT_TOKEN_ENV = {
     gitlab: ["GITLAB_TOKEN"],
     forgejo: ["FORGEJO_TOKEN", "GITHUB_TOKEN"],
 };
-/** Resolves the target from flags and the environment, or says what is missing. */
-export function resolveForgeTarget(flags, env) {
+/**
+ * Resolves the repository, API and token from flags and the environment;
+ * `pr` also the pull (merge) request. `what` names the option that needs
+ * them, for messages (`--comment`, `--issue`).
+ */
+function resolve(flags, env, what, withPr) {
     if (flags.forge !== undefined && !FORGES.includes(flags.forge))
         throw new YodelError(`--forge must be one of ${FORGES.join(", ")}, got ${JSON.stringify(flags.forge)}`);
     const forge = flags.forge ?? detectForge(env);
     if (!forge)
-        throw new YodelError("--comment cannot tell the forge: not a GitHub Actions, GitLab CI or Forgejo Actions job; pass --forge github|gitlab|forgejo with --repo, --pr and --api-url");
+        throw new YodelError(`${what} cannot tell the forge: not a GitHub Actions, GitLab CI or Forgejo Actions job; pass --forge github|gitlab|forgejo with --repo${withPr ? ", --pr" : ""} and --api-url`);
     const pick = (...names) => names.map((n) => env[n]).find((v) => v !== undefined && v !== "");
     let repo = flags.repo;
     let pr = flags.pr !== undefined ? Number(flags.pr) : undefined;
@@ -75,7 +79,8 @@ export function resolveForgeTarget(flags, env) {
     else {
         const p = forge === "forgejo" ? "FORGEJO_" : "GITHUB_";
         repo ??= pick(`${p}REPOSITORY`, "GITHUB_REPOSITORY");
-        pr ??= prFromEvent(pick(`${p}EVENT_PATH`, "GITHUB_EVENT_PATH"), pick(`${p}REF`, "GITHUB_REF"));
+        if (withPr)
+            pr ??= prFromEvent(pick(`${p}EVENT_PATH`, "GITHUB_EVENT_PATH"), pick(`${p}REF`, "GITHUB_REF"));
         apiUrl ??= pick(`${p}API_URL`, "GITHUB_API_URL");
         if (!apiUrl && forge === "forgejo") {
             const server = pick("FORGEJO_SERVER_URL", "GITHUB_SERVER_URL");
@@ -88,7 +93,7 @@ export function resolveForgeTarget(flags, env) {
     const missing = [];
     if (!repo)
         missing.push(forge === "gitlab" ? "the project (--repo, or CI_PROJECT_ID)" : "the repository (--repo owner/name, or GITHUB_REPOSITORY)");
-    if (pr === undefined || !Number.isInteger(pr) || pr <= 0) {
+    if (withPr && (pr === undefined || !Number.isInteger(pr) || pr <= 0)) {
         missing.push(forge === "gitlab" ? "the merge request (--pr, or CI_MERGE_REQUEST_IID in a merge request pipeline)" : "the pull request (--pr, or a pull_request event)");
     }
     if (!apiUrl)
@@ -99,7 +104,16 @@ export function resolveForgeTarget(flags, env) {
     if (!token)
         missing.push(`a token (${names.join(" or ")} is not set${flags.tokenEnv ? "" : "; name another variable with --token-env"})`);
     if (missing.length > 0)
-        throw new YodelError(`--comment on ${forge} needs ${missing.join(", ")}`);
-    return { forge, repo: repo, pr: pr, apiUrl: apiUrl.replace(/\/+$/, ""), token, tokenEnv };
+        throw new YodelError(`${what} on ${forge} needs ${missing.join(", ")}`);
+    const base = { forge, repo: repo, apiUrl: apiUrl.replace(/\/+$/, ""), token, tokenEnv };
+    return withPr ? { ...base, pr: pr } : base;
+}
+/** Resolves the target from flags and the environment, or says what is missing. */
+export function resolveForgeTarget(flags, env) {
+    return resolve(flags, env, "--comment", true);
+}
+/** The repository a job writes to (`yodel drift --issue`), from flags and the environment, or says what is missing. */
+export function resolveForgeRepo(flags, env, what = "--issue") {
+    return resolve(flags, env, what, false);
 }
 //# sourceMappingURL=forge.js.map

package/dist/pr/forge.js.map

@@ -1 +1 @@
-{"version":3,"file":"forge.js","sourceRoot":"","sources":["../../src/pr/forge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"forge.js","sourceRoot":"","sources":["../../src/pr/forge.ts"],"names":[],"mappings":"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"}

package/dist/pr/issue.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The drift watch's tracking issue (#49): one open issue per project and
+ * environment, found by its marker, opened when drift is found, updated
+ * while it lasts, and closed, with a comment, when it is gone. The three
+ * forges' REST APIs:
+ *
+ *   GitHub   GET/POST {api}/repos/{owner}/{repo}/issues            (open ones; pull requests left out)
+ *            PATCH    {api}/repos/{owner}/{repo}/issues/{n}         body, or state closed
+ *            POST     {api}/repos/{owner}/{repo}/issues/{n}/comments
+ *   GitLab   GET/POST {api}/projects/{id}/issues                   (state opened)
+ *            PUT      {api}/projects/{id}/issues/{iid}              description, or state_event close
+ *            POST     {api}/projects/{id}/issues/{iid}/notes
+ *   Forgejo  as GitHub, under /api/v1, with type=issues and limit
+ *
+ * The client lists only open issues, so a closed one is never reopened:
+ * drift found again after a close opens a new issue.
+ */
+import type { ForgeRepo } from "./forge.js";
+export interface ForgeIssue {
+    number: number;
+    title: string;
+    body: string;
+    url?: string | undefined;
+}
+export interface IssueClient {
+    /** The open issues (not pull requests). */
+    open(): Promise<ForgeIssue[]>;
+    create(title: string, body: string): Promise<ForgeIssue>;
+    update(n: number, title: string, body: string): Promise<ForgeIssue>;
+    /** Comments `comment` on the issue, then closes it. */
+    close(n: number, comment: string): Promise<void>;
+}
+type Fetch = typeof fetch;
+export declare function issueClient(t: ForgeRepo, f?: Fetch): IssueClient;
+/**
+ * The marker an environment's tracking issue carries, so the next run finds
+ * it. Keyed by the project's directory in its repository (`.` at the root),
+ * so two projects in one repository keep their own issues.
+ */
+export declare function driftIssueMarker(project: string, environment: string): string;
+/** What the run found, as the tracking issue needs it. */
+export type DriftOutcome = {
+    kind: "drift";
+    title: string;
+    body: string;
+    fingerprint: string;
+} | {
+    kind: "clean";
+    comment: string;
+}
+/** The drift could not be read, or part of the environment could not: the issue is left as it is. */
+ | {
+    kind: "unknown";
+    why: string;
+};
+export type IssueAction = {
+    action: "opened" | "updated" | "unchanged" | "closed";
+    issue: ForgeIssue;
+} | {
+    action: "none";
+} | {
+    action: "left";
+    why: string;
+    issue?: ForgeIssue;
+};
+/** Brings the environment's tracking issue in line with the outcome; see the module comment. */
+export declare function trackDrift(client: IssueClient, marker: string, outcome: DriftOutcome): Promise<IssueAction>;
+export {};

package/dist/pr/issue.js

@@ -0,0 +1,107 @@
+/**
+ * The drift watch's tracking issue (#49): one open issue per project and
+ * environment, found by its marker, opened when drift is found, updated
+ * while it lasts, and closed, with a comment, when it is gone. The three
+ * forges' REST APIs:
+ *
+ *   GitHub   GET/POST {api}/repos/{owner}/{repo}/issues            (open ones; pull requests left out)
+ *            PATCH    {api}/repos/{owner}/{repo}/issues/{n}         body, or state closed
+ *            POST     {api}/repos/{owner}/{repo}/issues/{n}/comments
+ *   GitLab   GET/POST {api}/projects/{id}/issues                   (state opened)
+ *            PUT      {api}/projects/{id}/issues/{iid}              description, or state_event close
+ *            POST     {api}/projects/{id}/issues/{iid}/notes
+ *   Forgejo  as GitHub, under /api/v1, with type=issues and limit
+ *
+ * The client lists only open issues, so a closed one is never reopened:
+ * drift found again after a close opens a new issue.
+ */
+import { YodelError } from "../project.js";
+const PAGE = 100;
+const MAX_PAGES = 20;
+const repoPath = (repo) => repo.split("/").map(encodeURIComponent).join("/");
+export function issueClient(t, f = fetch) {
+    const gitlab = t.forge === "gitlab";
+    const headers = gitlab
+        ? { "PRIVATE-TOKEN": t.token, Accept: "application/json" }
+        : t.forge === "forgejo"
+            ? { Authorization: `token ${t.token}`, Accept: "application/json" }
+            : { Authorization: `Bearer ${t.token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" };
+    const base = gitlab ? `${t.apiUrl}/projects/${encodeURIComponent(t.repo)}/issues` : `${t.apiUrl}/repos/${repoPath(t.repo)}/issues`;
+    const call = async (method, url, body) => {
+        let res;
+        try {
+            res = await f(url, { method, headers: { ...headers, ...(body ? { "Content-Type": "application/json" } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) });
+        }
+        catch (e) {
+            throw new YodelError(`${t.forge}: ${method} ${url} failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const text = await res.text();
+        if (!res.ok)
+            throw new YodelError(`${t.forge}: ${method} ${url} answered ${String(res.status)}: ${text.slice(0, 300).replaceAll(t.token, "[token]")}`);
+        return text ? JSON.parse(text) : {};
+    };
+    const toIssue = (r) => ({
+        number: Number(gitlab ? r.iid : r.number),
+        title: typeof r.title === "string" ? r.title : "",
+        body: typeof (gitlab ? r.description : r.body) === "string" ? String(gitlab ? r.description : r.body) : "",
+        url: typeof r.html_url === "string" ? r.html_url : typeof r.web_url === "string" ? r.web_url : undefined,
+    });
+    const list = (page) => gitlab
+        ? `${base}?state=opened&per_page=${String(PAGE)}&page=${String(page)}`
+        : t.forge === "forgejo"
+            ? `${base}?state=open&type=issues&limit=${String(PAGE)}&page=${String(page)}`
+            : `${base}?state=open&per_page=${String(PAGE)}&page=${String(page)}`;
+    return {
+        async open() {
+            const all = [];
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const got = (await call("GET", list(page)));
+                if (!Array.isArray(got))
+                    throw new YodelError(`${t.forge}: listing issues did not return a list`);
+                all.push(...got.filter((r) => r.pull_request === undefined || r.pull_request === null).map(toIssue));
+                if (got.length < PAGE)
+                    break;
+            }
+            return all;
+        },
+        async create(title, body) {
+            return toIssue((await call("POST", base, gitlab ? { title, description: body } : { title, body })));
+        },
+        async update(n, title, body) {
+            return toIssue((await call(gitlab ? "PUT" : "PATCH", `${base}/${String(n)}`, gitlab ? { title, description: body } : { title, body })));
+        },
+        async close(n, comment) {
+            await call("POST", `${base}/${String(n)}/${gitlab ? "notes" : "comments"}`, { body: comment });
+            await call(gitlab ? "PUT" : "PATCH", `${base}/${String(n)}`, gitlab ? { state_event: "close" } : { state: "closed" });
+        },
+    };
+}
+/**
+ * The marker an environment's tracking issue carries, so the next run finds
+ * it. Keyed by the project's directory in its repository (`.` at the root),
+ * so two projects in one repository keep their own issues.
+ */
+export function driftIssueMarker(project, environment) {
+    const clean = (s) => s.replace(/\s+/g, "_").replace(/-->/g, "");
+    return `<!-- yodel:drift project=${clean(project || ".")} env=${clean(environment)} -->`;
+}
+/** Brings the environment's tracking issue in line with the outcome; see the module comment. */
+export async function trackDrift(client, marker, outcome) {
+    const found = (await client.open()).filter((i) => i.body.includes(marker)).sort((a, b) => a.number - b.number);
+    const issue = found[0];
+    if (outcome.kind === "unknown")
+        return { action: "left", why: outcome.why, ...(issue ? { issue } : {}) };
+    if (outcome.kind === "clean") {
+        if (!issue)
+            return { action: "none" };
+        await client.close(issue.number, outcome.comment);
+        return { action: "closed", issue };
+    }
+    const body = `${marker}\n${outcome.body}`;
+    if (!issue)
+        return { action: "opened", issue: await client.create(outcome.title, body) };
+    if (issue.body.includes(outcome.fingerprint) && issue.title === outcome.title)
+        return { action: "unchanged", issue };
+    return { action: "updated", issue: await client.update(issue.number, outcome.title, body) };
+}
+//# sourceMappingURL=issue.js.map