@shortlink-org/portolan 0.1.0

package/scripts/diff.test.mjs

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+
+import { changesHref, globToRegExp, locate, parseArgs, render, renderJson, renderSarif } from "./diff.mjs";
+
+describe("globToRegExp", () => {
+  // The manifest's own patterns, which is the whole reason this exists: the
+  // working tree's side is globbed by `fs.glob` and the ref's side by this, so
+  // the two must agree about which files are sources.
+  it("matches what the manifest means by one star", () => {
+    const re = globToRegExp("examples/*/portolan/*.json");
+
+    expect(re.test("examples/auth/portolan/domain.json")).toBe(true);
+    expect(re.test("examples/shop/oms/portolan/domain.json")).toBe(false);
+    expect(re.test("examples/auth/portolan/domain.json.bak")).toBe(false);
+  });
+
+  it("lets two stars cross a slash", () => {
+    const re = globToRegExp("examples/**/portolan/*.json");
+
+    expect(re.test("examples/shop/oms/portolan/domain.json")).toBe(true);
+    expect(re.test("examples/auth/portolan/domain.json")).toBe(true);
+  });
+
+  it("anchors at both ends", () => {
+    const re = globToRegExp("data/*.json");
+
+    expect(re.test("data/adr.json")).toBe(true);
+    expect(re.test("vendor/data/adr.json")).toBe(false);
+    expect(re.test("data/adr/0001.md")).toBe(false);
+  });
+
+  // A dot is a dot. Left unescaped, `data/*.json` would also match a file
+  // called `data/adrxjson`, which is not a thing anybody has but is exactly
+  // the kind of quiet wrongness a source list should not have.
+  it("takes a dot literally", () => {
+    expect(globToRegExp("data/*.json").test("data/adrxjson")).toBe(false);
+  });
+});
+
+describe("render", () => {
+  it("says so plainly when nothing moved", () => {
+    expect(render("main", [])).toBe("No architectural change against `main`.\n");
+  });
+
+  it("groups by severity, breaking first", () => {
+    const out = render("main", [
+      { kind: "event.removed", severity: "breaking", where: "a", summary: "A is gone" },
+      { kind: "event.added", severity: "addition", where: "b", summary: "B is new" },
+      { kind: "owner.added", severity: "change", where: "c", summary: "C changed hands" },
+    ]);
+
+    expect(out).toContain("3 changes.");
+    expect(out.indexOf("Breaking")).toBeLessThan(out.indexOf("Added"));
+    expect(out.indexOf("Added")).toBeLessThan(out.indexOf("Changed"));
+    expect(out).toContain("- A is gone");
+  });
+
+  it("leaves out a severity nothing landed in", () => {
+    const out = render("main", [
+      { kind: "event.added", severity: "addition", where: "b", summary: "B is new" },
+    ]);
+
+    expect(out).toContain("1 change.");
+    expect(out).not.toContain("Breaking");
+  });
+
+  // The list is for the review; the page is for understanding it. The link
+  // is the last line, only when there is a site to link to, and only when
+  // there is something to look at.
+  it("ends with a link into the Changes page when it knows the site", () => {
+    const changes = [{ kind: "event.added", severity: "addition", where: "b", summary: "B is new" }];
+
+    expect(render("origin/main", changes, { site: "https://acme.github.io/shop/", head: "feat/x" }))
+      .toMatch(/\[Open in Changes\]\(https:\/\/acme\.github\.io\/shop\/changes\?base=main&head=feat%2Fx\)\n$/);
+    expect(render("origin/main", changes)).not.toContain("Open in Changes");
+    expect(render("origin/main", [], { site: "https://acme.github.io/shop" })).not.toContain("Open in Changes");
+  });
+});
+
+describe("changesHref", () => {
+  it("spells the base the way the site names a branch, and leaves out an unknown head", () => {
+    expect(changesHref("https://acme.github.io/shop", "origin/main", "")).toBe("https://acme.github.io/shop/changes?base=main");
+    expect(changesHref("", "main", "x")).toBe("");
+  });
+});
+
+describe("locate", () => {
+  const files = [
+    { path: "data/adr.json", text: '{\n  "adrs": [\n    { "id": "portolan.0001" }\n  ]\n}\n' },
+    { path: "examples/shop/portolan/domain.json", text: '{"contexts":[{"id":"shop","services":[{"id":"shop.order"}]}]}' },
+  ];
+
+  it("finds the fragment and line that declares the id", () => {
+    expect(locate("shop.order", files)).toEqual({ uri: "examples/shop/portolan/domain.json", line: 1 });
+    expect(locate("portolan.0001", files)).toEqual({ uri: "data/adr.json", line: 3 });
+  });
+
+  // `shop.order` must not match `shop-order` or `shop.orders`: the id is a
+  // whole string, and its dots are dots.
+  it("takes the id whole", () => {
+    expect(locate("shop.orde", files)).toEqual({ uri: "portolan.json", line: 1 });
+    expect(locate("shop_order", files)).toEqual({ uri: "portolan.json", line: 1 });
+  });
+
+  it("falls back to the manifest for what no working-tree source declares", () => {
+    expect(locate("gone.service", files)).toEqual({ uri: "portolan.json", line: 1 });
+  });
+});
+
+describe("machine formats", () => {
+  const changes = [
+    { kind: "event.removed", severity: "breaking", where: "shop.order", summary: "event is gone" },
+    { kind: "owner.added", severity: "change", where: "shop.cart", summary: "owner changed" },
+  ];
+
+  it("parses a ref, format and output in either option spelling", () => {
+    expect(parseArgs(["main", "--format=json", "--output", "report.json"])).toEqual({
+      ref: "main", format: "json", output: "report.json", site: "", head: "",
+    });
+    expect(parseArgs(["--site", "https://acme.github.io/shop", "--head=feat/x"])).toMatchObject({
+      site: "https://acme.github.io/shop", head: "feat/x",
+    });
+    expect(() => parseArgs(["--site"])).toThrow("--site needs a value");
+  });
+
+  it("anchors every SARIF result at the fragment that declares it", () => {
+    const files = [{ path: "examples/shop/portolan/domain.json", text: '{\n  "id": "shop.cart"\n}' }];
+    const report = JSON.parse(renderSarif("main", changes, files));
+    const [gone, owned] = report.runs[0].results;
+
+    expect(gone.locations[0].physicalLocation).toEqual({
+      artifactLocation: { uri: "portolan.json", uriBaseId: "%SRCROOT%" },
+      region: { startLine: 1, startColumn: 1 },
+    });
+    expect(owned.locations[0].physicalLocation.artifactLocation.uri).toBe("examples/shop/portolan/domain.json");
+    expect(owned.locations[0].physicalLocation.region.startLine).toBe(2);
+  });
+
+  it("exports a versioned JSON report with counts", () => {
+    const report = JSON.parse(renderJson("main", changes));
+    expect(report).toMatchObject({ version: 1, base: "main", counts: { breaking: 1, change: 1, addition: 0 } });
+    expect(report.changes).toEqual(changes);
+  });
+
+  it("maps breaking changes to SARIF errors", () => {
+    const report = JSON.parse(renderSarif("main", changes));
+    expect(report.version).toBe("2.1.0");
+    expect(report.runs[0].results[0]).toMatchObject({ ruleId: "event.removed", level: "error" });
+    expect(report.runs[0].results[0].properties.where).toBe("shop.order");
+  });
+});

package/scripts/forge-comment.mjs

@@ -0,0 +1,144 @@
+// Puts the architecture diff on the pull request it describes.
+//
+//   node scripts/forge-comment.mjs <markdown file>
+//
+// One comment per pull request, updated in place: the body starts with a
+// marker only this script writes, and the next run finds that comment and
+// replaces it rather than adding another, so a PR pushed to twenty times has
+// one report and it is the current one.
+//
+// Which forge and with what token is `forge.mjs`'s to say. GitHub Actions
+// hands over the event (GITHUB_EVENT_PATH) that names the pull request;
+// GitLab CI hands over the merge request's iid. Anything else, or no pull
+// request at all, and this says so on stderr and exits 0: the diff describes
+// a change and never fails one, and neither does the step that posts it. A
+// refusal by the forge (a fork's read-only token) is the same silence; any
+// other failed request is an error, because a broken configuration should be
+// seen once, by whoever set it up.
+
+import { readFileSync } from "node:fs";
+
+import { detectForge, failure, headers, projectUrl, refused } from "./forge.mjs";
+
+export const MARKER = "<!-- portolan:architecture-diff -->";
+
+const PAGE = 100;
+
+/**
+ * Which forge, which pull request, and with what - or the reason there is
+ * none. `event` is the parsed GitHub event payload when there is one.
+ */
+export function forgeFromEnv(env, event = null) {
+  const forge = detectForge(env);
+  if (!forge.provider) return forge;
+
+  if (forge.provider === "github") {
+    const number =
+      event?.pull_request?.number ??
+      Number(/^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? "")?.[1]);
+    if (!number) return { reason: "not a pull request" };
+    if (!forge.token) return { reason: "GITHUB_TOKEN is not set" };
+
+    return { ...forge, number };
+  }
+
+  if (!env.CI_MERGE_REQUEST_IID) return { reason: "not a merge request pipeline" };
+  if (!forge.token) return { reason: "PORTOLAN_TOKEN is not set" };
+
+  return { ...forge, number: Number(env.CI_MERGE_REQUEST_IID) };
+}
+
+/** The comment's body: the marker first, so the next run can find it. */
+export function body(markdown) {
+  return MARKER + "\n" + markdown.trimEnd() + "\n";
+}
+
+/** The comment this script wrote last time, if any. */
+export function findOwn(comments) {
+  return comments.find((comment) => (comment.body ?? "").startsWith(MARKER)) ?? null;
+}
+
+/** The requests each forge answers: list, create, update. */
+function routes(forge) {
+  const project = projectUrl(forge);
+  if (forge.provider === "github") {
+    const base = `${project}/issues/${forge.number}/comments`;
+
+    return {
+      list: (page) => `${base}?per_page=${PAGE}&page=${page}`,
+      create: { method: "POST", url: base },
+      update: (id) => ({ method: "PATCH", url: `${project}/issues/comments/${id}` }),
+    };
+  }
+
+  const base = `${project}/merge_requests/${forge.number}/notes`;
+
+  return {
+    list: (page) => `${base}?per_page=${PAGE}&page=${page}`,
+    create: { method: "POST", url: base },
+    update: (id) => ({ method: "PUT", url: `${base}/${id}` }),
+  };
+}
+
+/**
+ * Writes the comment, updating the one from last time when there is one.
+ * Answers what it did: `created`, `updated`, or `refused` with the status
+ * when the forge would not let this token write here.
+ */
+export async function upsert(forge, markdown, fetchImpl = fetch) {
+  const auth = headers(forge);
+  const { list, create, update } = routes(forge);
+
+  const own = await (async () => {
+    for (let page = 1; ; page++) {
+      const res = await fetchImpl(list(page), { headers: auth });
+      if (!res.ok) throw await failure("list comments", res);
+      const comments = await res.json();
+      const found = findOwn(comments);
+      if (found) return found;
+      if (comments.length < PAGE) return null;
+    }
+  })();
+
+  const { method, url } = own ? update(own.id) : create;
+  const res = await fetchImpl(url, {
+    method,
+    headers: { ...auth, "content-type": "application/json" },
+    body: JSON.stringify({ body: body(markdown) }),
+  });
+  if (refused(res)) return { outcome: "refused", status: res.status };
+  if (!res.ok) throw await failure(own ? "update comment" : "create comment", res);
+
+  return { outcome: own ? "updated" : "created", url: (await res.json()).html_url ?? url };
+}
+
+async function main() {
+  const file = process.argv[2];
+  if (!file) throw new Error("usage: forge-comment.mjs <markdown file>");
+  const markdown = readFileSync(file, "utf8");
+
+  const event = process.env.GITHUB_EVENT_PATH
+    ? JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"))
+    : null;
+  const forge = forgeFromEnv(process.env, event);
+  if (!forge.provider) {
+    console.error(`forge-comment: nothing to post to (${forge.reason})`);
+
+    return;
+  }
+
+  const done = await upsert(forge, markdown);
+  if (done.outcome === "refused") {
+    console.error(`forge-comment: the forge refused (${done.status}); a fork's token cannot write comments`);
+
+    return;
+  }
+  console.log(`forge-comment: ${done.outcome} ${done.url}`);
+}
+
+if (import.meta.main) {
+  main().catch((cause) => {
+    console.error("forge-comment: " + cause.message);
+    process.exit(1);
+  });
+}

package/scripts/forge-comment.test.mjs

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+
+import { MARKER, body, findOwn, forgeFromEnv, upsert } from "./forge-comment.mjs";
+
+describe("forgeFromEnv", () => {
+  it("reads a GitHub pull request off the event payload", () => {
+    const forge = forgeFromEnv(
+      { GITHUB_ACTIONS: "true", GITHUB_REPOSITORY: "acme/shop", GITHUB_TOKEN: "t" },
+      { pull_request: { number: 42 } },
+    );
+
+    expect(forge).toEqual({
+      provider: "github", api: "https://api.github.com", repo: "acme/shop", number: 42, token: "t",
+    });
+  });
+
+  // A workflow_run or a re-run has no event body worth reading, but the ref
+  // of a pull request checkout still names it.
+  it("falls back to the merge ref when there is no event", () => {
+    const forge = forgeFromEnv({
+      GITHUB_REPOSITORY: "acme/shop", GITHUB_TOKEN: "t", GITHUB_REF: "refs/pull/7/merge",
+      GITHUB_API_URL: "https://ghe.example.com/api/v3/",
+    });
+
+    expect(forge).toMatchObject({ provider: "github", number: 7, api: "https://ghe.example.com/api/v3" });
+  });
+
+  it("says why when a push is not a pull request, or the token is missing", () => {
+    expect(forgeFromEnv({ GITHUB_ACTIONS: "true", GITHUB_REF: "refs/heads/main" })).toEqual({ reason: "not a pull request" });
+    expect(forgeFromEnv({ GITHUB_ACTIONS: "true" }, { pull_request: { number: 1 } })).toEqual({ reason: "GITHUB_TOKEN is not set" });
+  });
+
+  it("reads a GitLab merge request, with the project token rather than the job's", () => {
+    const forge = forgeFromEnv({
+      GITLAB_CI: "true", CI_API_V4_URL: "https://gitlab.example.com/api/v4", CI_PROJECT_ID: "12",
+      CI_MERGE_REQUEST_IID: "9", CI_JOB_TOKEN: "job", PORTOLAN_TOKEN: "p",
+    });
+
+    expect(forge).toEqual({
+      provider: "gitlab", api: "https://gitlab.example.com/api/v4", project: "12", number: 9, token: "p",
+    });
+    expect(forgeFromEnv({ GITLAB_CI: "true", CI_API_V4_URL: "x", CI_MERGE_REQUEST_IID: "9" })).toEqual({ reason: "PORTOLAN_TOKEN is not set" });
+    expect(forgeFromEnv({ GITLAB_CI: "true", CI_API_V4_URL: "x" })).toEqual({ reason: "not a merge request pipeline" });
+  });
+
+  it("has nothing to say on a laptop", () => {
+    expect(forgeFromEnv({})).toEqual({ reason: "not running under GitHub Actions or GitLab CI" });
+  });
+});
+
+describe("the comment", () => {
+  it("starts with the marker and is found by it", () => {
+    const text = body("### Architecture\n\n1 change.\n");
+
+    expect(text.startsWith(MARKER + "\n")).toBe(true);
+    expect(findOwn([{ id: 1, body: "lgtm" }, { id: 2, body: text }])).toMatchObject({ id: 2 });
+    expect(findOwn([{ id: 1, body: "lgtm" }])).toBeNull();
+  });
+});
+
+describe("upsert", () => {
+  const github = { provider: "github", api: "https://api.github.com", repo: "acme/shop", number: 42, token: "t" };
+  const gitlab = { provider: "gitlab", api: "https://gitlab.example.com/api/v4", project: "grp/shop", number: 9, token: "p" };
+
+  /** A fetch that answers from a script and records what it was asked. */
+  function fake(answers) {
+    const calls = [];
+    const fetchImpl = async (url, init = {}) => {
+      calls.push({ url, method: init.method ?? "GET", body: init.body ? JSON.parse(init.body) : undefined, headers: init.headers });
+      const answer = answers.shift();
+
+      return {
+        ok: answer.status < 400, status: answer.status, statusText: "",
+        json: async () => answer.json, text: async () => "",
+      };
+    };
+
+    return { fetchImpl, calls };
+  }
+
+  it("creates a comment when it has not written one", async () => {
+    const { fetchImpl, calls } = fake([
+      { status: 200, json: [{ id: 1, body: "lgtm" }] },
+      { status: 201, json: { html_url: "https://github.com/acme/shop/pull/42#issuecomment-5" } },
+    ]);
+
+    const done = await upsert(github, "report", fetchImpl);
+
+    expect(done).toEqual({ outcome: "created", url: "https://github.com/acme/shop/pull/42#issuecomment-5" });
+    expect(calls[1]).toMatchObject({
+      method: "POST",
+      url: "https://api.github.com/repos/acme/shop/issues/42/comments",
+      body: { body: MARKER + "\nreport\n" },
+    });
+    expect(calls[1].headers.authorization).toBe("Bearer t");
+  });
+
+  it("updates the comment it wrote last time, on the comment's own route", async () => {
+    const { fetchImpl, calls } = fake([
+      { status: 200, json: [{ id: 3, body: MARKER + "\nold\n" }] },
+      { status: 200, json: { html_url: "u" } },
+    ]);
+
+    const done = await upsert(github, "new", fetchImpl);
+
+    expect(done.outcome).toBe("updated");
+    expect(calls[1]).toMatchObject({ method: "PATCH", url: "https://api.github.com/repos/acme/shop/issues/comments/3" });
+  });
+
+  it("keeps listing past a full page before deciding there is none", async () => {
+    const page = Array.from({ length: 100 }, (_, i) => ({ id: i, body: "x" }));
+    const { fetchImpl, calls } = fake([
+      { status: 200, json: page },
+      { status: 200, json: [{ id: 200, body: MARKER + "\nold\n" }] },
+      { status: 200, json: {} },
+    ]);
+
+    await upsert(github, "new", fetchImpl);
+
+    expect(calls[0].url).toContain("page=1");
+    expect(calls[1].url).toContain("page=2");
+    expect(calls[2]).toMatchObject({ method: "PATCH" });
+  });
+
+  it("speaks GitLab notes with the project path encoded", async () => {
+    const { fetchImpl, calls } = fake([
+      { status: 200, json: [{ id: 8, body: MARKER + "\nold\n" }] },
+      { status: 200, json: {} },
+    ]);
+
+    await upsert(gitlab, "new", fetchImpl);
+
+    expect(calls[0].url).toBe("https://gitlab.example.com/api/v4/projects/grp%2Fshop/merge_requests/9/notes?per_page=100&page=1");
+    expect(calls[0].headers["private-token"]).toBe("p");
+    expect(calls[1]).toMatchObject({ method: "PUT", url: "https://gitlab.example.com/api/v4/projects/grp%2Fshop/merge_requests/9/notes/8" });
+  });
+
+  // A fork's GITHUB_TOKEN can read the comments and not write one. That is
+  // the forge's policy, not a broken setup, and the step stays green.
+  it("reports a refusal rather than throwing", async () => {
+    const { fetchImpl } = fake([{ status: 200, json: [] }, { status: 403, json: {} }]);
+
+    expect(await upsert(github, "r", fetchImpl)).toEqual({ outcome: "refused", status: 403 });
+  });
+
+  it("throws on any other failure", async () => {
+    const { fetchImpl } = fake([{ status: 500, json: {} }]);
+
+    await expect(upsert(github, "r", fetchImpl)).rejects.toThrow("list comments: 500");
+  });
+});

package/scripts/forge-release.mjs

@@ -0,0 +1,138 @@
+// Puts the architecture diff into the release it describes.
+//
+//   node scripts/forge-release.mjs <markdown file> [tag]
+//
+// A release body is somebody's text - a changelog, the forge's generated
+// notes - and this owns one section of it: what sits between two markers only
+// this script writes. The section is replaced when it is there and appended
+// when it is not, so the rest of the body is left as it was, and a second run
+// for the same tag changes nothing but the section.
+//
+// A tag with no release yet gets one, named after the tag, with the section
+// as its whole body; a release already drafted keeps its draft status.
+// Without a tag, or a token, this says so on stderr and exits 0, the way the
+// diff never fails what it describes. A refusal by the forge is the same
+// silence; any other failed request is an error.
+
+import { readFileSync } from "node:fs";
+
+import { detectForge, failure, headers, projectUrl, refused } from "./forge.mjs";
+
+export const OPEN = "<!-- portolan:architecture -->";
+export const CLOSE = "<!-- /portolan:architecture -->";
+
+/** The forge, the tag, and the token - or why there is nothing to write to. */
+export function forgeFromEnv(env, tag = "") {
+  const forge = detectForge(env);
+  if (!forge.provider) return forge;
+
+  const name = tag || (forge.provider === "github"
+    ? (env.GITHUB_REF_TYPE === "tag" ? env.GITHUB_REF_NAME : /^refs\/tags\/(.+)$/.exec(env.GITHUB_REF ?? "")?.[1])
+    : env.CI_COMMIT_TAG);
+  if (!name) return { reason: "not a tag" };
+  if (!forge.token) return { reason: forge.provider === "github" ? "GITHUB_TOKEN is not set" : "PORTOLAN_TOKEN is not set" };
+
+  return { ...forge, tag: name };
+}
+
+/** The body with this script's section replaced, or appended when absent. */
+export function splice(existing, markdown) {
+  const section = OPEN + "\n" + markdown.trimEnd() + "\n" + CLOSE;
+  const from = existing.indexOf(OPEN);
+  const to = existing.indexOf(CLOSE, from);
+  if (from !== -1 && to !== -1) {
+    return existing.slice(0, from) + section + existing.slice(to + CLOSE.length);
+  }
+  const rest = existing.trimEnd();
+
+  return rest ? rest + "\n\n" + section + "\n" : section + "\n";
+}
+
+/** The requests each forge answers: read the release by tag, create, update. */
+function routes(forge) {
+  const project = projectUrl(forge);
+  if (forge.provider === "github") {
+    return {
+      read: `${project}/releases/tags/${encodeURIComponent(forge.tag)}`,
+      body: (release) => release.body ?? "",
+      create: (text) => ({
+        method: "POST", url: `${project}/releases`,
+        payload: { tag_name: forge.tag, name: forge.tag, body: text },
+      }),
+      update: (release, text) => ({
+        method: "PATCH", url: `${project}/releases/${release.id}`, payload: { body: text },
+      }),
+      link: (release) => release.html_url,
+    };
+  }
+
+  const tag = encodeURIComponent(forge.tag);
+
+  return {
+    read: `${project}/releases/${tag}`,
+    body: (release) => release.description ?? "",
+    create: (text) => ({
+      method: "POST", url: `${project}/releases`,
+      payload: { tag_name: forge.tag, name: forge.tag, description: text },
+    }),
+    update: (release, text) => ({
+      method: "PUT", url: `${project}/releases/${tag}`, payload: { description: text },
+    }),
+    link: (release) => release._links?.self,
+  };
+}
+
+/**
+ * Writes the section. Answers `created`, `updated`, or `refused` with the
+ * status when the forge would not let this token write here.
+ */
+export async function upsert(forge, markdown, fetchImpl = fetch) {
+  const auth = headers(forge);
+  const { read, body, create, update, link } = routes(forge);
+
+  const found = await fetchImpl(read, { headers: auth });
+  if (refused(found)) return { outcome: "refused", status: found.status };
+  if (!found.ok && found.status !== 404) throw await failure("read release", found);
+  const release = found.status === 404 ? null : await found.json();
+
+  const { method, url, payload } = release
+    ? update(release, splice(body(release), markdown))
+    : create(splice("", markdown));
+  const res = await fetchImpl(url, {
+    method,
+    headers: { ...auth, "content-type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (refused(res)) return { outcome: "refused", status: res.status };
+  if (!res.ok) throw await failure(release ? "update release" : "create release", res);
+
+  return { outcome: release ? "updated" : "created", url: link(await res.json()) ?? url };
+}
+
+async function main() {
+  const [file, tag] = process.argv.slice(2);
+  if (!file) throw new Error("usage: forge-release.mjs <markdown file> [tag]");
+  const markdown = readFileSync(file, "utf8");
+
+  const forge = forgeFromEnv(process.env, tag);
+  if (!forge.provider) {
+    console.error(`forge-release: nothing to write to (${forge.reason})`);
+
+    return;
+  }
+
+  const done = await upsert(forge, markdown);
+  if (done.outcome === "refused") {
+    console.error(`forge-release: the forge refused (${done.status}); the token cannot write releases`);
+
+    return;
+  }
+  console.log(`forge-release: ${done.outcome} ${done.url}`);
+}
+
+if (import.meta.main) {
+  main().catch((cause) => {
+    console.error("forge-release: " + cause.message);
+    process.exit(1);
+  });
+}