@decohere/ci-tools 0.0.1-dev.20261105.76 → 0.0.1-dev.20261105.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/ci-tools",
-  "version": "0.0.1-dev.20261105.76",
+  "version": "0.0.1-dev.20261105.83",
   "description": "CI utility scripts for badge generation, coverage reporting, pages artifact assembly, and GitHub API tooling",
   "keywords": [
     "typescript",
@@ -43,7 +43,7 @@
     "./github/ensure-metadata": "./src/github/ensure-metadata.mjs",
     "./github/create-or-update-pr": "./src/github/create-or-update-pr.mjs",
     "./github/publish-verify": "./src/github/publish-verify.mjs",
-    "./github/oidc-bootstrap-nudge": "./src/github/oidc-bootstrap-nudge.mjs",
+    "./github/first-publish-check": "./src/github/first-publish-check.mjs",
     "./github/npm-bootstrap": "./src/github/npm-bootstrap.mjs",
     "./github/smoke-create-launcher": "./src/github/smoke-create-launcher.mjs"
   },

package/src/github/first-publish-check.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Finds packages in this workspace that aren't on npm yet. A first publish needs an owner's npm
+ * login, so CI can't do it. On a PR that's only a notice, so a contributor can propose a package
+ * with no npm access. In the merge queue it fails, because Publish could not upload that package.
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { listPublishablePackages } from "./publish-verify.mjs";
+
+const REGISTRY = "https://registry.npmjs.org";
+
+/**
+ * @param {{
+ *   packages: string[],
+ *   blocking: boolean,
+ *   fetch: typeof globalThis.fetch,
+ *   log?: (message: string) => void,
+ * }} options
+ * @returns {Promise<number>} exit code
+ */
+export async function checkFirstPublish(options) {
+	const { packages, blocking, fetch } = options;
+	const log = options.log ?? console.log;
+
+	const results = await Promise.all(
+		packages.map(async (name) => {
+			// Not /-/package/<name>/dist-tags: for a name that does not exist it answers 401, not 404.
+			const url = `${REGISTRY}/${name.replace("/", "%2f")}`;
+			const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+			// Anything else, like an outage, says nothing about whether the name exists.
+			if (!response.ok && response.status !== 404) {
+				throw new Error(`Could not check ${name} on npm: ${response.status}`);
+			}
+			return { name, missing: response.status === 404 };
+		}),
+	);
+
+	const missing = results.filter((result) => result.missing).map((result) => result.name);
+	if (missing.length === 0) {
+		log(`All ${packages.length} packages are on npm.`);
+		return 0;
+	}
+	const names = missing.join(" ");
+	if (blocking) {
+		log(
+			`::error::Not on npm yet: ${names}. An owner runs \`pnpm npm:bootstrap --otp <code> ${names}\`, ` +
+				"then adds this PR to the merge queue again.",
+		);
+		return 1;
+	}
+	log(
+		`::notice::New package, not on npm yet: ${names}. Contributors have nothing to do: a maintainer ` +
+			`runs \`pnpm npm:bootstrap --otp <code> ${names}\` before this merges.`,
+	);
+	return 0;
+}
+
+if (
+	process.argv[1] != null &&
+	import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+	process.exit(
+		await checkFirstPublish({
+			packages: listPublishablePackages(process.cwd()).map((pkg) => pkg.name),
+			blocking: process.env.GITHUB_EVENT_NAME === "merge_group",
+			fetch: globalThis.fetch,
+		}),
+	);
+}

package/src/github/npm-bootstrap.mjs

@@ -169,7 +169,7 @@ export async function runBootstrap(options = {}) {
 		"\nFor each new package, also run `pnpm npm:trust-promote --otp <code>`, so Promote to latest can move its tag.",
 	);
 	log(
-		"\nDone. Approve the waiting npm-oidc-bootstrap deployment on the Publish run, or rerun it: `gh run rerun --failed <run-id>`.",
+		"\nDone. Add the PR to the merge queue. If Publish already failed on this, rerun it: `gh run rerun --failed <run-id>`.",
 	);
 	return 0;
 }

package/src/github/publish-verify.mjs

@@ -199,8 +199,6 @@ if (isCli) {
 		appendFileSync(process.env.GITHUB_OUTPUT, `${body}\n`);
 	}
 	if (result.unpublished.length) {
-		process.stderr.write(
-			`Never-published packages (bootstrap OIDC before PUT): ${result.unpublished.join(", ")}\n`,
-		);
+		process.stderr.write(`Not on npm yet: ${result.unpublished.join(", ")}\n`);
 	}
 }

package/tests/github/first-publish-check.test.mjs

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { checkFirstPublish } from "../../src/github/first-publish-check.mjs";
+
+function fakeRegistry(statusByName) {
+	return async (url) => {
+		const name = decodeURIComponent(new URL(url).pathname.slice(1));
+		return new Response("{}", { status: statusByName[name] ?? 200 });
+	};
+}
+
+async function check(statusByName, blocking) {
+	const messages = [];
+	const code = await checkFirstPublish({
+		packages: ["@decohere/cli", "@decohere/shiny"],
+		blocking,
+		fetch: fakeRegistry(statusByName),
+		log: (message) => messages.push(message),
+	});
+	return { code, output: messages.join("\n") };
+}
+
+describe("checkFirstPublish", () => {
+	it("passes when every package is on npm", async () => {
+		const { code, output } = await check({}, true);
+
+		expect(code).toBe(0);
+		expect(output).toContain("All 2 packages are on npm");
+	});
+
+	it("only leaves a notice on a PR, so a contributor can propose a package", async () => {
+		const { code, output } = await check({ "@decohere/shiny": 404 }, false);
+
+		expect(code).toBe(0);
+		expect(output).toContain("::notice::");
+		expect(output).toContain("pnpm npm:bootstrap --otp <code> @decohere/shiny");
+	});
+
+	it("fails in the merge queue, naming the package and the command", async () => {
+		const { code, output } = await check({ "@decohere/shiny": 404 }, true);
+
+		expect(code).toBe(1);
+		expect(output).toContain("::error::");
+		expect(output).toContain("pnpm npm:bootstrap --otp <code> @decohere/shiny");
+	});
+
+	it("doesn't mistake an npm outage for a new package", async () => {
+		await expect(check({ "@decohere/shiny": 503 }, false)).rejects.toThrow(
+			"Could not check @decohere/shiny on npm: 503",
+		);
+	});
+});

package/src/github/oidc-bootstrap-nudge.mjs

@@ -1,214 +0,0 @@
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { upsertIssue } from "../lib/github-issue.mjs";
-import { needsPrereleaseTag, TRUSTED_PUBLISHER } from "./npm-bootstrap.mjs";
-import { listPublishablePackages } from "./publish-verify.mjs";
-
-export { needsPrereleaseTag } from "./npm-bootstrap.mjs";
-
-const GITHUB_API = process.env.GITHUB_API_URL ?? "https://api.github.com";
-const ISSUE_TITLE = "deploy(publish): OIDC bootstrap unpublished packages";
-const BOOTSTRAP_ENV = "npm-oidc-bootstrap";
-const DEFAULT_REPO = "typesmiths/decohere";
-
-export function issueTitle() {
-	return ISSUE_TITLE;
-}
-
-/** @param {string | undefined} raw */
-export function parseUnpublished(raw) {
-	return String(raw ?? "")
-		.split(/\s+/)
-		.map((name) => name.trim())
-		.filter(Boolean);
-}
-
-/**
- * @param {{ name: string, dir: string, version?: string }[]} packages
- * @param {string} [channel]
- */
-export function firstPublishCommands(packages, channel = "dev") {
-	if (packages.length === 0) {
-		return [`npm publish ./<package-dir> --tag ${channel}`];
-	}
-	return packages.map((pkg) => {
-		const tag = needsPrereleaseTag(pkg.version) ? ` --tag ${channel}` : "";
-		return `npm publish ./projects/${pkg.dir} --access public${tag}`;
-	});
-}
-
-/**
- * @param {unknown} environment
- * @returns {string[]}
- */
-export function extractGitHubReviewerLogins(environment) {
-	const rules =
-		environment && typeof environment === "object" ? environment.protection_rules : null;
-	if (!Array.isArray(rules)) {
-		return [];
-	}
-	const logins = [];
-	for (const rule of rules) {
-		const reviewers = rule?.reviewers;
-		if (!Array.isArray(reviewers)) {
-			continue;
-		}
-		for (const entry of reviewers) {
-			const login = entry?.reviewer?.login;
-			if (typeof login === "string" && login.length > 0 && entry?.type !== "Team") {
-				logins.push(login);
-			}
-		}
-	}
-	return [...new Set(logins)];
-}
-
-/**
- * @param {{
- *   unpublished: string[],
- *   packages: { name: string, dir: string, version?: string }[],
- *   repo?: string,
- *   runUrl?: string,
- *   channel?: string,
- * }} options
- */
-export function buildDescription(options) {
-	const repo = options.repo || DEFAULT_REPO;
-	const names = options.unpublished;
-	const channel = options.channel || "dev";
-	const packages = options.packages.filter((pkg) => names.includes(pkg.name));
-	const [owner, repoName] = repo.split("/");
-	return [
-		"## Summary",
-		"",
-		"These package names are not on npm yet, so OIDC `npm publish` cannot run until each name exists and has a Trusted Publisher:",
-		"",
-		...names.map((name) => `- \`${name}\``),
-		"",
-		"## What to do",
-		"",
-		"From a trusted machine, `npm login` to the org, then from the **repo root** (`--otp` is optional: npm asks for a code, or the browser login, whenever it needs one):",
-		"",
-		"```bash",
-		`pnpm npm:bootstrap --otp <code> ${names.join(" ")}`,
-		"```",
-		"",
-		"That does steps 1 and 2 below, skipping what is already done. To do them by hand instead:",
-		"",
-		"1. First-publish each name **public** (`--access public`: scoped names default to restricted). From a trusted machine, `npm login` to the org, then from the **repo root**. Use `./` so npm does not treat the path as a GitHub `owner/repo`. `--tag` is required for prerelease versions (`x.y.z-dev.N`). Missing `bin`/`es6` warnings are OK for this name-only bootstrap; CI `forge publish` ships the built tarball later:",
-		"",
-		"```bash",
-		...firstPublishCommands(packages, channel),
-		"```",
-		"",
-		"2. npm → package settings → Trusted Publisher → GitHub Actions:",
-		"",
-		`- Organization: \`${owner ?? "typesmiths"}\``,
-		`- Repository: \`${repoName ?? "decohere"}\``,
-		`- Workflow filename: \`${TRUSTED_PUBLISHER.file}\``,
-		`- Environment: \`${TRUSTED_PUBLISHER.environment}\``,
-		"- Allowed action: `npm publish` (not staged-only)",
-		"",
-		"3. Approve the waiting **npm-oidc-bootstrap** deployment on this Publish run. The job re-checks that the names exist, then npm + Docker + tag continue. If reviewers were not configured and the job already failed:",
-		"",
-		"```bash",
-		`gh run list --repo ${repo} --workflow Publish --limit 5`,
-		`gh run rerun --failed <run-id> --repo ${repo}`,
-		"```",
-		"",
-		options.runUrl ? `- Workflow run: ${options.runUrl}` : null,
-	]
-		.filter((line) => line != null)
-		.join("\n");
-}
-
-function runUrl() {
-	if (
-		process.env.GITHUB_SERVER_URL &&
-		process.env.GITHUB_REPOSITORY &&
-		process.env.GITHUB_RUN_ID
-	) {
-		return `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`;
-	}
-	return "";
-}
-
-/**
- * @param {{ fetch?: typeof fetch, token?: string, repo?: string, environment?: string }} options
- */
-export async function githubEnvironmentReviewerLogins(options = {}) {
-	const token = options.token ?? process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? "";
-	const repo = options.repo ?? process.env.GITHUB_REPOSITORY ?? "";
-	const environment = options.environment ?? BOOTSTRAP_ENV;
-	const fetchFn = options.fetch ?? fetch;
-	if (!token || !repo) {
-		return [];
-	}
-	const response = await fetchFn(
-		`${GITHUB_API}/repos/${repo}/environments/${encodeURIComponent(environment)}`,
-		{
-			headers: {
-				Authorization: `Bearer ${token}`,
-				Accept: "application/vnd.github+json",
-				"X-GitHub-Api-Version": "2022-11-28",
-			},
-		},
-	);
-	if (!response.ok) {
-		process.stderr.write(
-			`Could not list ${environment} reviewers (${response.status}); the issue will have no assignees\n`,
-		);
-		return [];
-	}
-	return extractGitHubReviewerLogins(await response.json());
-}
-
-export async function runNudge(env = process.env, io = {}) {
-	const unpublished = parseUnpublished(env.UNPUBLISHED);
-	if (unpublished.length === 0) {
-		process.stdout.write("No unpublished package names; skipping OIDC bootstrap issue\n");
-		return 0;
-	}
-
-	const root = io.root ?? process.cwd();
-	const packages = (io.listPackages ?? listPublishablePackages)(root);
-	const assignees = await (io.githubReviewers ?? githubEnvironmentReviewerLogins)({
-		token: env.GITHUB_TOKEN ?? env.GH_TOKEN,
-		repo: env.GITHUB_REPOSITORY,
-	});
-	const repo = env.GITHUB_REPOSITORY || DEFAULT_REPO;
-
-	const result = (io.upsert ?? upsertIssue)({
-		title: issueTitle(),
-		body: buildDescription({
-			unpublished,
-			packages,
-			repo,
-			runUrl: io.runUrl ?? runUrl(),
-			channel: env.PUBLISH_CHANNEL || env.CHANNEL || "dev",
-		}),
-		assignees,
-	});
-	process.stdout.write(
-		`${result.created ? "Opened" : "Updated"} issue #${result.number} ${result.url}\n`,
-	);
-	if (assignees.length > 0) {
-		process.stdout.write(`Assigned ${assignees.join(", ")}\n`);
-	} else {
-		process.stdout.write(
-			`No assignees (add required reviewers on the ${BOOTSTRAP_ENV} environment)\n`,
-		);
-	}
-	if (env.GITHUB_OUTPUT) {
-		const { appendFileSync } = await import("node:fs");
-		appendFileSync(env.GITHUB_OUTPUT, `issue_url=${result.url}\n`);
-	}
-	return 0;
-}
-
-const isCli =
-	process.argv[1] != null && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
-
-if (isCli) {
-	process.exit(await runNudge());
-}

package/tests/github/oidc-bootstrap-nudge.test.mjs

@@ -1,89 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-	buildDescription,
-	extractGitHubReviewerLogins,
-	firstPublishCommands,
-	issueTitle,
-	needsPrereleaseTag,
-	parseUnpublished,
-	runNudge,
-} from "../../src/github/oidc-bootstrap-nudge.mjs";
-
-describe("oidc-bootstrap-nudge", () => {
-	it("parses unpublished names", () => {
-		expect(parseUnpublished(" @decohere/scaffold  @decohere/cli ")).toEqual([
-			"@decohere/scaffold",
-			"@decohere/cli",
-		]);
-		expect(issueTitle()).toBe("deploy(publish): OIDC bootstrap unpublished packages");
-	});
-
-	it("extracts GitHub user reviewers and skips teams", () => {
-		expect(
-			extractGitHubReviewerLogins({
-				protection_rules: [
-					{ type: "branch_policy", reviewers: [] },
-					{
-						type: "required_reviewers",
-						reviewers: [
-							{ type: "User", reviewer: { login: "das974" } },
-							{ type: "Team", reviewer: { slug: "publishers", login: "should-skip" } },
-						],
-					},
-				],
-			}),
-		).toEqual(["das974"]);
-	});
-
-	it("puts first-publish commands and Trusted Publisher fields in the task body", () => {
-		const pkg = { name: "@decohere/scaffold", dir: "scaffold", version: "0.0.1-dev.18" };
-		const body = buildDescription({
-			unpublished: ["@decohere/scaffold"],
-			packages: [pkg],
-			repo: "typesmiths/decohere",
-			runUrl: "https://github.com/typesmiths/decohere/actions/runs/9",
-			channel: "dev",
-		});
-		expect(needsPrereleaseTag("0.0.1-dev.18")).toBe(true);
-		expect(needsPrereleaseTag("1.2.3")).toBe(false);
-		expect(firstPublishCommands([pkg], "dev")).toEqual([
-			"npm publish ./projects/scaffold --access public --tag dev",
-		]);
-		expect(firstPublishCommands([{ ...pkg, version: "1.0.0" }], "dev")).toEqual([
-			"npm publish ./projects/scaffold --access public",
-		]);
-		expect(body).toContain("npm publish ./projects/scaffold --access public --tag dev");
-		expect(body).toContain("pnpm npm:bootstrap --otp <code> @decohere/scaffold");
-		expect(body).not.toMatch(/# @decohere\/scaffold/);
-		expect(body).toContain("First-publish each name **public**");
-		expect(body).toContain("Workflow filename: `publish.yml`");
-		expect(body).toContain("Environment: `npm-publish`");
-		expect(body).toContain("gh run rerun --failed");
-		expect(body).toContain("https://github.com/typesmiths/decohere/actions/runs/9");
-	});
-
-	it("assigns the bootstrap environment's reviewers to the issue", async () => {
-		/** @type {object[]} */
-		const upserts = [];
-		const code = await runNudge(
-			{ UNPUBLISHED: "@decohere/scaffold", GITHUB_REPOSITORY: "typesmiths/decohere" },
-			{
-				listPackages: () => [{ name: "@decohere/scaffold", dir: "scaffold" }],
-				githubReviewers: async () => ["das974"],
-				upsert: (options) => {
-					upserts.push(options);
-					return {
-						number: 5,
-						url: "https://github.com/typesmiths/decohere/issues/5",
-						created: true,
-					};
-				},
-				runUrl: "https://github.com/typesmiths/decohere/actions/runs/1",
-			},
-		);
-		expect(code).toBe(0);
-		expect(upserts[0].title).toBe(issueTitle());
-		expect(upserts[0].assignees).toEqual(["das974"]);
-		expect(upserts[0].body).toContain("`@decohere/scaffold`");
-	});
-});