@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/release/pack.ts

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { z } from "zod";
+import type { Runner } from "../scripts/ci-wait.ts";
+import { BUN_PACK, PACK_DIR_PREFIX, TAR_MANIFEST, TARBALL_EXTENSION, UNPINNED } from "./release.constants.ts";
+import {
+  PACKED_UNREADABLE,
+  PACK_ARGS,
+  PACK_PREFIX,
+  packCount,
+  packFailed,
+  unpinned,
+} from "./release-messages.constants.ts";
+import { refuse } from "./refuse.ts";
+
+/** Where `repo release pack` runs and prints, and the bun, tar and temp directory it works through. */
+export type PackIo = {
+  cwd: string;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  bun: Runner;
+  tar: Runner;
+  /** The directory the tarball's own directory is made in. */
+  tmp: string;
+  mkdtemp: (prefix: string) => string;
+  /** The names in a directory. */
+  list: (dir: string) => string[];
+};
+/** A tarball and the name and version its package.json carries. */
+export type Packed = { tarball: string; name: string; version: string };
+
+const pins = () => z.record(z.string(), z.string()).default({});
+const packedSchema = () =>
+  z.object({
+    name: z.string(),
+    version: z.string(),
+    dependencies: pins(),
+    devDependencies: pins(),
+    peerDependencies: pins(),
+    optionalDependencies: pins(),
+  });
+
+/** Packs the package in `io.cwd` and checks its package.json; the tarball and its manifest, or the refusal line. */
+export function packTarball(
+  io: Pick<PackIo, "cwd" | "stderr" | "bun" | "tar" | "tmp" | "mkdtemp" | "list">,
+): Packed | string {
+  const dir = io.mkdtemp(path.join(io.tmp, PACK_DIR_PREFIX));
+  const packed = io.bun(BUN_PACK(dir), io.cwd);
+  if (packed.stdout !== "") io.stderr(packed.stdout);
+  if (packed.code !== 0) return packFailed(packed.stderr.trim());
+  const tarballs = io.list(dir).filter((file) => file.endsWith(TARBALL_EXTENSION));
+  const [only] = tarballs;
+  if (only === undefined || tarballs.length > 1) return packCount(tarballs.length, dir);
+  const tarball = path.join(dir, only);
+  let manifest: z.infer<ReturnType<typeof packedSchema>>;
+  try {
+    // By name from its own dir: GNU tar reads an absolute `C:\\…` as `host:path` and tries to connect to the host `C`.
+    manifest = packedSchema().parse(JSON.parse(io.tar(TAR_MANIFEST(only), dir).stdout));
+  } catch {
+    return PACKED_UNREADABLE;
+  }
+  const { name, version, ...fields } = manifest;
+  for (const entries of Object.values(fields)) {
+    const bad = Object.entries(entries).find(([, spec]) => UNPINNED.test(spec));
+    if (bad !== undefined) return unpinned(bad[1], bad[0]);
+  }
+  return { tarball, name, version };
+}
+
+/** `repo release pack`: prints the path of the tarball of this checkout's package, after checking its package.json. */
+export function releasePack(argv: readonly string[], io: PackIo): number {
+  if (argv.length > 0) return refuse(io, PACK_PREFIX, PACK_ARGS);
+  const got = packTarball(io);
+  if (typeof got === "string") return refuse(io, PACK_PREFIX, got);
+  io.stdout(`${got.tarball}\n`);
+  return 0;
+}

package/cli/release/plan.ts

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "../config.ts";
+import { GH_AUTH } from "../scripts/ci-wait.constants.ts";
+import { hasUnreleased } from "./changelog.ts";
+import {
+  commitsSince,
+  commitWithSubject,
+  defaultBranch,
+  divergence,
+  must,
+  read,
+  releaseTag,
+  type Tools,
+} from "./git.ts";
+import { readManifest, type Manifest } from "./manifest.ts";
+import {
+  CHANGELOG_FILE,
+  GIT_BRANCH,
+  GIT_FETCH,
+  GIT_HEAD,
+  GIT_STATUS,
+  PREFIX_SEPARATOR,
+  RELEASE_PACK,
+  RELEASE_SUBJECT,
+  TAG_OF,
+  ZERO_VERSION,
+} from "./release.constants.ts";
+import {
+  DIRTY,
+  EMPTY_UNRELEASED,
+  GH_MISSING,
+  NO_MANIFEST,
+  PACK_OFF,
+  differs,
+  isPrivate,
+  notMain,
+  notSemver,
+  nothing,
+  stableOnly,
+  tagExists,
+} from "./release-messages.constants.ts";
+import { nextVersion, type Mode } from "./version.ts";
+
+/** What a release will do: which version, and whether it writes a commit (`bump`: new version; `fold`: into a pending one). */
+export type Plan = {
+  name: string;
+  from: string;
+  version: string;
+  tag: string;
+  branch: string;
+  action: "bump" | "fold" | "none";
+  /** Commits on the branch origin does not have yet. */
+  ahead: number;
+};
+
+const unreleased = (t: Tools): boolean => {
+  const file = path.join(t.cwd, CHANGELOG_FILE);
+  return fs.existsSync(file) && hasUnreleased(fs.readFileSync(file, "utf8"));
+};
+
+/** The refusal for the config and manifest, or the manifest. */
+async function readRepo(t: Tools): Promise<Manifest | string> {
+  const manifest = readManifest(t.cwd);
+  if (manifest === null) return NO_MANIFEST;
+  const loaded = await loadConfig(t.cwd);
+  if (!loaded.ok) return loaded.errors.join(PREFIX_SEPARATOR);
+  if (!loaded.config.packs.includes(RELEASE_PACK)) return PACK_OFF;
+  return manifest.private ? isPrivate(manifest.name) : manifest;
+}
+
+/** What the pending-release and new-version steps read: the checkout, its manifest, the last tag and the mode. */
+type Release = { t: Tools; manifest: Manifest; lastTag: string | null; mode: Mode };
+
+/** The new version, or the refusal; checks the changelog and the tag it would make. */
+function newVersion({ t, manifest: m, lastTag, mode }: Release): { version: string } | string {
+  const first = lastTag === null && m.version === ZERO_VERSION;
+  const got = nextVersion({ current: m.version, commits: commitsSince(t, lastTag), mode, first });
+  if (!got.ok) {
+    const lines = {
+      nothing: nothing(lastTag),
+      stable: stableOnly(m.name, m.version),
+      version: notSemver(m.name, m.version),
+    };
+    return lines[got.reason];
+  }
+  if (!unreleased(t)) return EMPTY_UNRELEASED;
+  const taken = releaseTag(t, m.name, got.version);
+  return taken === null ? { version: got.version } : tagExists(taken);
+}
+
+/** Where the checkout stands: the branch to release from, commits not pushed, the pending release commit, the last tag. */
+type State = { branch: string; ahead: number; pending: string | null; lastTag: string | null };
+
+/** The state, or the refusal for a dirty tree, another branch, an origin that differs or a gh that is not logged in. */
+function readState(t: Tools, { name, version }: Manifest): State | string {
+  if (read(t, GIT_STATUS) !== "") return DIRTY;
+  const branch = defaultBranch(t);
+  const current = read(t, GIT_BRANCH);
+  if (current !== branch) return notMain(branch, current);
+  must(t, GIT_FETCH);
+  const lastTag = releaseTag(t, name, version);
+  const pending = lastTag === null ? commitWithSubject(t, RELEASE_SUBJECT(TAG_OF(name, version))) : null;
+  const { ahead, behind } = divergence(t, branch);
+  if (behind > 0 || (ahead > 0 && pending === null)) return differs(branch, behind, ahead);
+  return t.gh(GH_AUTH.slice(), t.cwd).code === 0 ? { branch, ahead, pending, lastTag } : GH_MISSING;
+}
+
+/**
+ * The plan for the checkout at `t.cwd`, or the one-line reason it refuses; nothing is written. A version whose release
+ * commit is in history without a tag is pending: a rerun finishes it instead of computing a new one.
+ */
+export async function makePlan(t: Tools, mode: Mode): Promise<Plan | string> {
+  const manifest = await readRepo(t);
+  if (typeof manifest === "string") return manifest;
+  const state = readState(t, manifest);
+  if (typeof state === "string") return state;
+  const { name, version: from } = manifest;
+  const { branch, ahead } = state;
+  if (state.pending !== null) {
+    const action = state.pending !== read(t, GIT_HEAD) && unreleased(t) ? "fold" : "none";
+    return { name, from, version: from, tag: TAG_OF(name, from), branch, ahead, action };
+  }
+  const next = newVersion({ t, manifest, lastTag: state.lastTag, mode });
+  const tag = typeof next === "string" ? "" : TAG_OF(name, next.version);
+  return typeof next === "string" ? next : { name, from, version: next.version, tag, branch, ahead, action: "bump" };
+}

package/cli/release/publish-run.test.ts

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { publish, type Registry } from "../fixtures/publish-world.ts";
+import { removePlanted } from "../fixtures/planted-repo.ts";
+import { gitIn, NAME, world } from "../fixtures/release-world.ts";
+
+afterEach(removePlanted);
+
+const SPEC = `${NAME}@0.1.0`;
+const newVersion = (notServed = 0, offline = 0): Registry => ({ exists: true, listed: false, notServed, offline });
+const PACK_DIR = path.normalize("/tmp/repo-pack-x1");
+const TGZ = path.join(PACK_DIR, "acme-app-0.1.0.tgz");
+
+describe("repo release publish publishes", () => {
+  it("a first publish from your machine through npm, under latest", async () => {
+    const registry: Registry = { exists: false, listed: false, notServed: 0 };
+    const got = await publish(world(), [SPEC], registry, { ci: false });
+    expect(got).toMatchObject({
+      code: 0,
+      out: `repo release publish: packed ${SPEC} · published under latest · tarball served\n`,
+      err: "",
+      npmCalls: [`publish ${TGZ} --access public --ignore-scripts`],
+      bunCalls: [`pm pack --destination ${PACK_DIR} --quiet`],
+    });
+  });
+
+  it("a new version of a package already on npm, in CI", async () => {
+    const got = await publish(world(), [SPEC], newVersion(), { ci: true });
+    expect(got).toMatchObject({ code: 0, npmCalls: [`publish ${TGZ} --access public --ignore-scripts`] });
+  });
+
+  it("a prerelease under next", async () => {
+    const pre = `${NAME}@0.2.0-rc.1`;
+    const w = world({ "package.json": { name: NAME, version: "0.2.0-rc.1" } }, false);
+    gitIn(w.work, "tag", "-a", pre, "-m", "t");
+    const got = await publish(w, [pre], newVersion(), { ci: true });
+    expect(got.out).toBe(`repo release publish: packed ${pre} · published under next · tarball served\n`);
+    expect(got.npmCalls).toEqual([
+      `publish ${path.join(PACK_DIR, "acme-app-0.2.0-rc.1.tgz")} --access public --ignore-scripts --tag next`,
+    ]);
+  });
+});
+
+describe("repo release publish waits and reruns", () => {
+  it("waits for the tarball after publishing", async () => {
+    const got = await publish(world(), [SPEC], newVersion(1));
+    expect(got).toMatchObject({ code: 0, sleeps: [10_000] });
+  });
+
+  it("keeps waiting through a network error", async () => {
+    const got = await publish(world(), [SPEC], newVersion(0, 2));
+    expect(got).toMatchObject({ code: 0, sleeps: [10_000, 10_000] });
+  });
+
+  it("counts an npm failure as published when the version is listed by then", async () => {
+    const got = await publish(world(), [SPEC], newVersion(), { npm: { code: 1, lists: true } });
+    expect(got).toMatchObject({
+      code: 0,
+      out: `repo release publish: packed ${SPEC} · published under latest · tarball served\n`,
+    });
+  });
+});
+
+describe("repo release publish refuses", () => {
+  it("an npm failure that published nothing", async () => {
+    const got = await publish(world(), [SPEC], newVersion(), { npm: { code: 1, lists: false } });
+    expect(got).toMatchObject({
+      code: 1,
+      out: "",
+      err: "repo release publish: npm publish exited 1 and npm does not list 0.1.0; its output is above\n",
+    });
+  });
+
+  it("a tarball that npm never serves after publishing", async () => {
+    const got = await publish(world(), [SPEC], newVersion(Number.MAX_SAFE_INTEGER));
+    expect(got).toMatchObject({
+      code: 1,
+      err: `repo release publish: the tarball of ${SPEC} is not served after 15 minutes; rerun this job\n`,
+    });
+  });
+});
+
+describe("repo release publish refuses a bad pack", () => {
+  it("a package that bun cannot pack", async () => {
+    const bun = () => ({ code: 1, stdout: "", stderr: "boom\n" });
+    const got = await publish(world(), [SPEC], newVersion(), { bun });
+    expect(got).toMatchObject({ code: 1, err: "repo release publish: bun pm pack failed: boom\n", npmCalls: [] });
+  });
+
+  it("a tarball that holds another name or version than the tag", async () => {
+    const got = await publish(world(), [SPEC], newVersion(), { packed: { name: NAME, version: "0.0.9" } });
+    expect(got).toMatchObject({
+      code: 1,
+      err: `repo release publish: the tarball holds ${NAME}@0.0.9 but the tag is ${SPEC}; nothing was published\n`,
+      npmCalls: [],
+    });
+  });
+});

package/cli/release/publish.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { publish, type Registry } from "../fixtures/publish-world.ts";
+import { removePlanted, tempDir } from "../fixtures/planted-repo.ts";
+import { commit, gitIn, NAME, world } from "../fixtures/release-world.ts";
+
+afterEach(removePlanted);
+
+const SPEC = `${NAME}@0.1.0`;
+const GONE: Registry = { exists: false, listed: false, notServed: 0 };
+const LISTED = (notServed = 0): Registry => ({ exists: true, listed: true, notServed });
+const TARBALL = "https://registry.npmjs.org/@acme/app/-/app-0.1.0.tgz";
+const TAG_FORMAT = "repo release publish: name the tag as <name>@<version>, e.g. @workerstack/repo@1.0.0\n";
+
+describe("repo release publish starts from the tag", () => {
+  it("refuses when HEAD is past the tag, without packing or publishing", async () => {
+    const w = world();
+    commit(w, "chore: later", { "later.txt": "x\n" });
+    const got = await publish(w, [SPEC], LISTED());
+    expect(got).toMatchObject({
+      code: 1,
+      out: "",
+      err: `repo release publish: HEAD is not ${SPEC}; check out the tag first\n`,
+      npmCalls: [],
+      bunCalls: [],
+    });
+  });
+
+  it("refuses a tag that does not exist", async () => {
+    expect((await publish(world({}, false), [SPEC], LISTED())).err).toBe(
+      `repo release publish: HEAD is not ${SPEC}; check out the tag first\n`,
+    );
+  });
+
+  it("refuses outside a git checkout", async () => {
+    const got = await publish({ work: tempDir(), remote: "" }, [SPEC], LISTED());
+    expect(got.err).toBe(`repo release publish: HEAD is not ${SPEC}; check out the tag first\n`);
+  });
+
+  it("refuses a missing or malformed argument with the tag format", async () => {
+    expect((await publish(world(), [], LISTED())).err).toBe(TAG_FORMAT);
+    expect((await publish(world(), ["x"], LISTED())).err).toBe(TAG_FORMAT);
+  });
+});
+
+describe("repo release publish skips a version npm serves", () => {
+  it("says so and runs nothing", async () => {
+    const got = await publish(world(), [SPEC], LISTED());
+    expect(got).toMatchObject({
+      code: 0,
+      out: `repo release publish: ${SPEC} is already on npm; nothing to publish\n`,
+      err: "",
+      npmCalls: [],
+      bunCalls: [],
+      urls: ["https://registry.npmjs.org/@acme%2fapp", TARBALL],
+    });
+  });
+
+  it("polls the tarball url every 10 seconds when npm lists the version but does not serve it yet", async () => {
+    const got = await publish(world(), [SPEC], LISTED(2));
+    expect(got).toMatchObject({ code: 0, sleeps: [10_000, 10_000], npmCalls: [] });
+    expect(got.out).toBe(
+      "repo release publish: npm lists 0.1.0 but its tarball is not served yet; waiting…\n" +
+        `repo release publish: ${SPEC} is already on npm; nothing to publish\n`,
+    );
+    expect(got.urls.filter((url) => url === TARBALL)).toHaveLength(3);
+  });
+
+  it("gives up after 15 minutes", async () => {
+    const got = await publish(world(), [SPEC], LISTED(Number.MAX_SAFE_INTEGER));
+    expect(got.code).toBe(1);
+    expect(got.err).toBe(
+      `repo release publish: the tarball of ${SPEC} is not served after 15 minutes; rerun this job\n`,
+    );
+    expect(got.sleeps.reduce((sum, ms) => sum + ms, 0)).toBe(900_000);
+  });
+});
+
+describe("repo release publish for a package that is not on npm", () => {
+  const origin = (url: string) => {
+    const w = world();
+    gitIn(w.work, "remote", "set-url", "origin", url);
+    return publish(w, [SPEC], { ...GONE }, { ci: true });
+  };
+  const bootstrap = (repo: string) =>
+    `repo release publish: ${NAME} is not on npm yet, and npm adds a trusted publisher only to a package that exists;\n` +
+    `  run \`npm login\` and \`bun repo release publish ${SPEC}\` at that tag on your machine, then add the\n` +
+    `  trusted publisher at https://www.npmjs.com/package/${NAME}/access (GitHub Actions, ${repo}, release.yml)\n`;
+
+  it("prints the bootstrap steps in CI and publishes nothing", async () => {
+    const got = await origin("https://github.com/acme/app.git");
+    expect(got).toMatchObject({ code: 1, out: "", err: bootstrap("acme/app"), npmCalls: [], bunCalls: [] });
+  });
+
+  it("names the repository from an ssh remote too", async () => {
+    expect((await origin("git@github.com:acme/app.git")).err).toBe(bootstrap("acme/app"));
+  });
+
+  it("names the repository from a remote with no .git", async () => {
+    expect((await origin("https://github.com/acme/app")).err).toBe(bootstrap("acme/app"));
+  });
+
+  it("leaves a placeholder for a remote that is not on GitHub", async () => {
+    expect((await origin("/some/where.git")).err).toBe(bootstrap("<owner>/<repo>"));
+  });
+});
+
+describe("repo release publish when the registry does not answer", () => {
+  it("asks again every 10 seconds and goes on once it answers", async () => {
+    const got = await publish(world(), [SPEC], { ...LISTED(), docFails: 2 });
+    expect(got).toMatchObject({
+      code: 0,
+      out: `repo release publish: ${SPEC} is already on npm; nothing to publish\n`,
+      sleeps: [10_000, 10_000],
+    });
+  });
+
+  it("does not print the bootstrap steps for a registry that is down, and gives up after 15 minutes", async () => {
+    const got = await publish(world(), [SPEC], { ...GONE, docFails: Number.MAX_SAFE_INTEGER }, { ci: true });
+    expect(got).toMatchObject({
+      code: 1,
+      out: "",
+      err: "repo release publish: registry.npmjs.org did not answer for 15 minutes (HTTP 503); rerun the release job\n",
+      npmCalls: [],
+    });
+    expect(got.sleeps.reduce((sum, ms) => sum + ms, 0)).toBe(900_000);
+  });
+});

package/cli/release/publish.ts

@@ -0,0 +1,125 @@
+import type { Runner } from "../scripts/ci-wait.ts";
+import { packTarball, type PackIo } from "./pack.ts";
+import { refuse } from "./refuse.ts";
+import {
+  ACCESS_URL,
+  GITHUB_REPO,
+  GIT_HEAD,
+  GIT_ORIGIN_URL,
+  GIT_TAG_REF,
+  NPM_PUBLISH,
+  NPM_TAG,
+  RELEASE_WORKFLOW,
+  REPO_PLACEHOLDER,
+  TARBALL_URL,
+  WAIT_GIVE_UP_MINUTES,
+} from "./release.constants.ts";
+import {
+  PUBLISH_PREFIX,
+  WAIT_USAGE,
+  alreadyOnNpm,
+  bootstrap,
+  headNotTag,
+  listedNotServed,
+  npmFailed,
+  publishedLine,
+  registryDown,
+  tarballDiffers,
+  tarballNotServed,
+} from "./release-messages.constants.ts";
+import { listing, poll, registryDoc, splitSpec, type RegistryAnswer, type Spec, type WaitIo } from "./wait.ts";
+
+/** What `repo release publish` works through: pack's tools, git, npm, the registry, the clock and whether it runs in CI. */
+export type PublishIo = PackIo & Pick<WaitIo, "fetch" | "now" | "sleep"> & { git: Runner; npm: Runner; ci: boolean };
+
+const served = async (fetcher: WaitIo["fetch"], url: string): Promise<true | null> => {
+  try {
+    return (await fetcher(url)).ok ? true : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Polls the tarball url of `parts` until npm serves it; `announce` prints one line at the first miss. */
+async function tarballServed(io: PublishIo, parts: Spec, announce: boolean): Promise<boolean> {
+  const url = TARBALL_URL(parts.name, parts.version);
+  let told = false;
+  const probe = async (): Promise<true | null> => {
+    const got = await served(io.fetch, url);
+    if (got === null && announce && !told) {
+      told = true;
+      io.stdout(`${PUBLISH_PREFIX}${listedNotServed(parts.version)}\n`);
+    }
+    return got;
+  };
+  return (await poll(io, probe, io.now())) !== null;
+}
+
+/** The registry's answer for `name`, asked again every 10 seconds while it does not answer; unreachable after 15 minutes. */
+async function settled(io: PublishIo, name: string): Promise<RegistryAnswer> {
+  let why = "";
+  const probe = async (): Promise<RegistryAnswer | null> => {
+    const answer = await registryDoc(io.fetch, name);
+    if (answer.kind === "unreachable") why = answer.why;
+    return answer.kind === "unreachable" ? null : answer;
+  };
+  return (await poll(io, probe, io.now())) ?? { kind: "unreachable", why };
+}
+
+/** `owner/repo` of origin when it is on GitHub, else a placeholder. */
+function ownerRepo(io: PublishIo): string {
+  return GITHUB_REPO.exec(io.git([...GIT_ORIGIN_URL], io.cwd).stdout.trim())?.[1] ?? REPO_PLACEHOLDER;
+}
+
+/** Packs and publishes the tag's package; the exit code. */
+async function publishNew(io: PublishIo, parts: Spec, tag: string): Promise<number> {
+  const packed = packTarball(io);
+  if (typeof packed === "string") return refuse(io, PUBLISH_PREFIX, packed);
+  if (packed.name !== parts.name || packed.version !== parts.version) {
+    return refuse(io, PUBLISH_PREFIX, tarballDiffers(`${packed.name}@${packed.version}`, tag));
+  }
+  const prerelease = parts.version.includes("-");
+  const run = io.npm(NPM_PUBLISH(packed.tarball, prerelease), io.cwd);
+  if (run.code !== 0 && listing(await registryDoc(io.fetch, parts.name), parts.version) === null) {
+    return refuse(io, PUBLISH_PREFIX, npmFailed(run.code, parts.version));
+  }
+  if (!(await tarballServed(io, parts, false))) {
+    return refuse(io, PUBLISH_PREFIX, tarballNotServed(tag, WAIT_GIVE_UP_MINUTES));
+  }
+  io.stdout(`${PUBLISH_PREFIX}${publishedLine(tag, NPM_TAG(prerelease))}\n`);
+  return 0;
+}
+
+/** A version npm lists: waits until it serves the tarball, then reports that there is nothing to publish. */
+async function alreadyThere(io: PublishIo, parts: Spec, tag: string): Promise<number> {
+  if (!(await tarballServed(io, parts, true))) {
+    return refuse(io, PUBLISH_PREFIX, tarballNotServed(tag, WAIT_GIVE_UP_MINUTES));
+  }
+  io.stdout(`${PUBLISH_PREFIX}${alreadyOnNpm(tag)}\n`);
+  return 0;
+}
+
+/** `repo release publish <name>@<version>`: packs the checked-out tag and publishes it, unless npm already serves it. */
+export async function releasePublish(argv: readonly string[], io: PublishIo): Promise<number> {
+  const tag = argv[0] ?? "";
+  const parts = argv.length === 1 ? splitSpec(tag) : null;
+  if (parts === null) return refuse(io, PUBLISH_PREFIX, WAIT_USAGE);
+  const head = io.git([...GIT_HEAD], io.cwd).stdout.trim();
+  if (head === "" || head !== io.git(GIT_TAG_REF(tag), io.cwd).stdout.trim()) {
+    return refuse(io, PUBLISH_PREFIX, headNotTag(tag));
+  }
+  const answer = await settled(io, parts.name);
+  if (answer.kind === "unreachable") {
+    return refuse(io, PUBLISH_PREFIX, registryDown(answer.why, WAIT_GIVE_UP_MINUTES));
+  }
+  if (listing(answer, parts.version) !== null) return alreadyThere(io, parts, tag);
+  if (answer.kind === "missing" && io.ci) {
+    const url = ACCESS_URL(parts.name);
+    return refuse(
+      io,
+      PUBLISH_PREFIX,
+      bootstrap({ name: parts.name, tag, repo: ownerRepo(io), url, workflow: RELEASE_WORKFLOW }),
+    );
+  }
+  return publishNew(io, parts, tag);
+}

package/cli/release/refuse.ts

@@ -0,0 +1,5 @@
+/** Prints `prefix` and `line` to stderr and returns the failing exit code. */
+export function refuse(io: { stderr: (text: string) => void }, prefix: string, line: string): number {
+  io.stderr(`${prefix}${line}\n`);
+  return 1;
+}

package/cli/release/release-messages.constants.ts

@@ -0,0 +1,96 @@
+/** Every refusal and result line of `repo release`, so the words live in one place. */
+export const PREFIX = "repo release: ";
+export const USAGE =
+  "usage: repo release [--stable | --pre <id>] | wait | gate | pack | publish | github <name>@<version>";
+export const DIRTY = "the working tree has changes; commit or stash them first";
+export const GH_MISSING = "gh is not installed or not logged in; run `gh auth login`";
+export const EMPTY_UNRELEASED = "CHANGELOG.md has no entries under ## [Unreleased]; add them first";
+export const PACK_OFF = 'the release pack is off; add "release" to packs in workerstack.config.ts';
+export const NO_MANIFEST = "package.json needs a name and a version";
+export const NOT_CHECKOUT = "run it inside a git checkout";
+export const notMain = (main: string, branch: string): string => `release from ${main}; this checkout is on ${branch}`;
+export const differs = (main: string, behind: number, ahead: number): string =>
+  `${main} and origin/${main} differ (${behind} behind, ${ahead} ahead); pull or push first`;
+export const nothing = (since: string | null): string =>
+  `nothing to release since ${since ?? "the first commit"}: no feat, fix, perf, revert or breaking commit`;
+export const isPrivate = (name: string): string => `${name} is private; set "private": false to publish it`;
+export const stableOnly = (name: string, version: string): string =>
+  `--stable moves a 0.x version to 1.0.0; ${name} is ${version}`;
+export const notSemver = (name: string, version: string): string => `${name} is at ${version}, which is not semver`;
+export const tagExists = (tag: string): string =>
+  `the tag ${tag} already exists; a tag is never moved, so release the next version`;
+export const gitFailed = (command: string, why: string): string => `git ${command} failed: ${why}`;
+export const ciFailed = (short: string): string =>
+  `CI failed on ${short} (jobs above); fix it in a new commit, push, and run bun repo release again`;
+export const ciSuperseded = (short: string): string =>
+  `a newer push cancelled CI on ${short}; pull and run bun repo release again`;
+export const ciNoResult = (short: string, detail: string): string =>
+  `no CI result for ${short} (${detail}); it is pushed and untagged; run bun repo release again`;
+export type Summary = { name: string; move: string; steps: readonly string[]; tag: string };
+export const summary = ({ name, move, steps, tag }: Summary): string =>
+  [`${name} ${move}`, ...steps, "CI passed", `tagged ${tag}`].join(" · ");
+export const WAIT_PREFIX = "repo release wait: ";
+export const WAIT_USAGE = "name the tag as <name>@<version>, e.g. @workerstack/repo@1.0.0";
+export const published = (version: string, tag: string | undefined): string =>
+  tag === undefined ? `published ${version}` : `published ${version} under ${tag}`;
+export const notOnNpm = (spec: string, minutes: number): string =>
+  `${spec} is not on npm after ${minutes} minutes; see gh run list --workflow release`;
+export const HOOKS_REFUSED =
+  "the hooks refused the release commit (output above); nothing was changed, so fix it and run bun repo release again";
+export const GATE_PREFIX = "repo release gate: ";
+export const tagMissing = (tag: string): string => `the tag ${tag} does not exist here; fetch the tags`;
+export const noManifestAt = (short: string): string => `package.json at ${short} needs a name and a version`;
+export const nameDiffers = (tagName: string, short: string, name: string): string =>
+  `the tag names ${tagName} but package.json at ${short} names ${name}`;
+export const versionDiffers = (tagVersion: string, short: string, version: string): string =>
+  `the tag says ${tagVersion} but package.json at ${short} says ${version}; a tag is never moved, so release the next version`;
+export const noSection = (short: string, version: string): string =>
+  `CHANGELOG.md at ${short} has no ## [${version}] section; publish is refused without one`;
+export const notOnBranch = (short: string, branch: string): string =>
+  `${short} is not on ${branch}; tag a commit on ${branch} after its CI passed`;
+export const noDefaultBranch = (why: string): string =>
+  `gh could not read the default branch (${why}); check gh auth status`;
+export const gateOk = (tag: string, short: string, version: string): string =>
+  `${tag} is ${short}, version ${version}, changelog ok`;
+/** The refusal line for a ci wait that did not pass, by how it ended. */
+export const gateCiLines = {
+  failed: (short: string): string =>
+    `CI failed on ${short}; a tag is never moved, so fix it in a new commit and release the next version`,
+  superseded: (short: string): string => `a newer push cancelled CI on ${short}; rerun ci on it, then rerun this job`,
+  error: (short: string, detail: string): string =>
+    `no CI result for ${short} (${detail}); rerun this job once ci has run`,
+};
+export const PACK_PREFIX = "repo release pack: ";
+export const PACK_ARGS = "takes no arguments; it packs the package in this checkout";
+export const packFailed = (why: string): string => `bun pm pack failed: ${why}`;
+export const PACKED_UNREADABLE = "the packed tarball has no readable package.json with a name and a version";
+export const unpinned = (spec: string, dependency: string): string =>
+  `the packed package.json names ${spec} for ${dependency}; pin it before releasing`;
+export const PUBLISH_PREFIX = "repo release publish: ";
+export const headNotTag = (tag: string): string => `HEAD is not ${tag}; check out the tag first`;
+export const alreadyOnNpm = (tag: string): string => `${tag} is already on npm; nothing to publish`;
+export const listedNotServed = (version: string): string =>
+  `npm lists ${version} but its tarball is not served yet; waiting…`;
+export const tarballNotServed = (tag: string, minutes: number): string =>
+  `the tarball of ${tag} is not served after ${minutes} minutes; rerun this job`;
+export type Bootstrap = { name: string; tag: string; repo: string; url: string; workflow: string };
+export const bootstrap = ({ name, tag, repo, url, workflow }: Bootstrap): string =>
+  `${name} is not on npm yet, and npm adds a trusted publisher only to a package that exists;\n` +
+  `  run \`npm login\` and \`bun repo release publish ${tag}\` at that tag on your machine, then add the\n` +
+  `  trusted publisher at ${url} (GitHub Actions, ${repo}, ${workflow})`;
+export const tarballDiffers = (packed: string, tag: string): string =>
+  `the tarball holds ${packed} but the tag is ${tag}; nothing was published`;
+export const npmFailed = (code: number, version: string): string =>
+  `npm publish exited ${code} and npm does not list ${version}; its output is above`;
+export const publishedLine = (tag: string, npmTag: string): string =>
+  `packed ${tag} · published under ${npmTag} · tarball served`;
+export const GITHUB_PREFIX = "repo release github: ";
+export const noNotes = (version: string): string =>
+  `CHANGELOG.md has no ## [${version}] section to make the notes from`;
+export const releaseCreated = (tag: string): string => `created release ${tag} from CHANGELOG.md`;
+export const releaseExists = (tag: string): string => `release ${tag} already exists`;
+export const createFailed = (why: string): string => `gh release create failed: ${why}`;
+export const registryDown = (why: string, minutes: number): string =>
+  `registry.npmjs.org did not answer for ${minutes} minutes (${why}); rerun the release job`;
+export const packCount = (count: number, dir: string): string =>
+  `bun pm pack left ${count} tarballs in ${dir}; expected exactly one`;