@decohere/ci-tools 0.0.1-dev.121 → 0.0.1-dev.122

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 Typesmiths
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/ci-tools",
-  "version": "0.0.1-dev.121",
+  "version": "0.0.1-dev.122",
   "description": "CI utility scripts for badge generation, coverage reporting, pages artifact assembly, and GitHub API tooling",
   "keywords": [
     "typescript",
@@ -36,6 +36,7 @@
     "./github/publish-verify": "./src/github/publish-verify.mjs",
     "./github/credential-nudge": "./src/github/credential-nudge.mjs",
     "./github/oidc-bootstrap-nudge": "./src/github/oidc-bootstrap-nudge.mjs",
+    "./github/npm-bootstrap": "./src/github/npm-bootstrap.mjs",
     "./github/smoke-create-launcher": "./src/github/smoke-create-launcher.mjs"
   },
   "scripts": {

package/src/github/npm-bootstrap.mjs

@@ -0,0 +1,179 @@
+/**
+ * First-publish a new package name (restricted) and give it its Trusted Publisher,
+ * so `publish.yml` can release it over OIDC from then on.
+ *
+ *   pnpm npm:bootstrap [--otp <code>] [--dry-run] [--channel dev] [<package-name>...]
+ *
+ * Without names: every publishable package whose name is not on npm yet.
+ * Run from the repo root after `npm login` to the org. Each step is skipped when
+ * it is already done (the name exists, the Trusted Publisher is set).
+ *
+ * npm runs on this terminal, so it does its own 2FA: it asks for a code, or
+ * opens the browser for web authentication. `--otp` hands it a code up front
+ * through `NPM_CONFIG_OTP`; `npm trust` takes no `--otp` flag of its own.
+ */
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { listPublishablePackages, npmNameExists } from "./publish-verify.mjs";
+
+/** The Trusted Publisher every package gets: `publish.yml`'s npm job. */
+export const TRUSTED_PUBLISHER = {
+	repo: "typesmiths/decohere",
+	file: "publish.yml",
+	environment: "npm-publish",
+};
+
+/** @param {string | undefined} version */
+export function needsPrereleaseTag(version) {
+	return String(version ?? "").includes("-");
+}
+
+/**
+ * npm arguments for a name-only first publish. Restricted is the scoped default,
+ * so no `--access`. `./` stops npm reading the path as a GitHub `owner/repo`.
+ *
+ * @param {{ dir: string, version?: string }} pkg
+ * @param {string} channel
+ */
+export function publishArgs(pkg, channel) {
+	const tag = needsPrereleaseTag(pkg.version) ? ["--tag", channel] : [];
+	return ["publish", `./projects/${pkg.dir}`, ...tag];
+}
+
+/** @param {string} name */
+export function trustArgs(name) {
+	return [
+		"trust",
+		"github",
+		name,
+		"--file",
+		TRUSTED_PUBLISHER.file,
+		"--repo",
+		TRUSTED_PUBLISHER.repo,
+		"--env",
+		TRUSTED_PUBLISHER.environment,
+		"--allow-publish",
+		"--yes",
+	];
+}
+
+/** @param {string} output `npm trust list <name> --json` */
+export function hasTrustedPublisher(output) {
+	return output.includes(TRUSTED_PUBLISHER.file) && output.includes(TRUSTED_PUBLISHER.repo);
+}
+
+/**
+ * @typedef {{ capture?: boolean, otp?: string }} NpmOptions
+ * `capture` keeps stdout to read it (npm can then not prompt for 2FA);
+ * otherwise npm owns the terminal.
+ */
+
+/**
+ * @param {string[]} args
+ * @param {NpmOptions} [options]
+ * @returns {{ status: number, output: string }}
+ */
+function runNpm(args, { capture = false, otp } = {}) {
+	const result = spawnSync("npm", args, {
+		encoding: "utf8",
+		stdio: capture ? ["inherit", "pipe", "inherit"] : "inherit",
+		env: otp ? { ...process.env, NPM_CONFIG_OTP: otp } : process.env,
+	});
+	return { status: result.status ?? 1, output: result.stdout ?? "" };
+}
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   root?: string,
+ *   io?: {
+ *     npm?: (args: string[], options?: NpmOptions) => { status: number, output: string },
+ *     nameExists?: (name: string) => boolean,
+ *     log?: (line: string) => void,
+ *   },
+ * }} [options]
+ * @returns {Promise<number>} exit code
+ */
+export async function runBootstrap(options = {}) {
+	const { values, positionals } = parseArgs({
+		args: options.argv ?? process.argv.slice(2),
+		options: {
+			otp: { type: "string" },
+			"dry-run": { type: "boolean", default: false },
+			channel: { type: "string", default: "dev" },
+		},
+		allowPositionals: true,
+	});
+	const io = options.io ?? {};
+	const npm = io.npm ?? runNpm;
+	const nameExists = io.nameExists ?? ((name) => npmNameExists(name));
+	const log = io.log ?? ((line) => process.stdout.write(`${line}\n`));
+	const dryRun = values["dry-run"];
+
+	// Even on a dry run: the names are private, so `npm view` 404s without a login
+	// and every package would look unpublished.
+	if (npm(["whoami"]).status !== 0) {
+		log("Not logged in to npm: run `npm login` first.");
+		return 1;
+	}
+
+	const publishable = listPublishablePackages(options.root ?? process.cwd());
+	const unknown = positionals.filter((name) => !publishable.some((pkg) => pkg.name === name));
+	if (unknown.length > 0) {
+		log(`Not a publishable package in projects/: ${unknown.join(", ")}`);
+		return 1;
+	}
+	const packages =
+		positionals.length > 0
+			? publishable.filter((pkg) => positionals.includes(pkg.name))
+			: publishable.filter((pkg) => !nameExists(pkg.name));
+	if (packages.length === 0) {
+		log("Every package name is on npm already. Name one to check its Trusted Publisher.");
+		return 0;
+	}
+
+	// A code npm rejects (they last about 30 seconds) makes npm ask for a new one.
+	/** @param {string[]} args */
+	const change = (args) => {
+		if (dryRun) {
+			log(`[dry run] npm ${args.join(" ")}`);
+			return true;
+		}
+		return npm(args, { otp: values.otp }).status === 0;
+	};
+
+	for (const pkg of packages) {
+		log(`\n${pkg.name} (projects/${pkg.dir}, ${pkg.version})`);
+
+		if (nameExists(pkg.name)) {
+			log("  name is on npm: skip the first publish");
+		} else if (!change(publishArgs(pkg, values.channel))) {
+			log(`  first publish failed: stopping`);
+			return 1;
+		}
+
+		const listed = dryRun
+			? { status: 1, output: "" }
+			: npm(["trust", "list", pkg.name, "--json"], { capture: true, otp: values.otp });
+		if (listed.status === 0 && hasTrustedPublisher(listed.output)) {
+			log("  Trusted Publisher is set: skip");
+		} else if (!change(trustArgs(pkg.name))) {
+			log("  Trusted Publisher failed: stopping");
+			return 1;
+		}
+	}
+
+	log(
+		"\nDone. Approve the waiting npm-oidc-bootstrap deployment on the Publish run, or rerun it: `gh run rerun --failed <run-id>`.",
+	);
+	return 0;
+}
+
+const isCli =
+	process.argv[1] != null && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+
+if (isCli) {
+	process.exit(await runBootstrap());
+}

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

@@ -1,8 +1,11 @@
 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";
@@ -20,13 +23,6 @@ export function parseUnpublished(raw) {
 		.filter(Boolean);
 }
 
-/**
- * @param {string | undefined} version
- */
-export function needsPrereleaseTag(version) {
-	return String(version ?? "").includes("-");
-}
-
 /**
  * @param {{ name: string, dir: string, version?: string }[]} packages
  * @param {string} [channel]
@@ -91,6 +87,14 @@ export function buildDescription(options) {
 		"",
 		"## 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 **restricted** (scoped default — do **not** pass `--access public`). 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",
@@ -101,8 +105,8 @@ export function buildDescription(options) {
 		"",
 		`- Organization: \`${owner ?? "typesmiths"}\``,
 		`- Repository: \`${repoName ?? "decohere"}\``,
-		"- Workflow filename: `publish.yml`",
-		"- Environment: `npm-publish`",
+		`- 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:",

package/tests/github/npm-bootstrap.test.mjs

@@ -0,0 +1,125 @@
+import { vol } from "memfs";
+import { afterEach, describe, expect, it } from "vitest";
+import { runBootstrap } from "../../src/github/npm-bootstrap.mjs";
+
+const root = "/workspace";
+
+function seedWorkspace() {
+	vol.fromJSON({
+		[`${root}/package.json`]: JSON.stringify({ version: "0.0.1-dev.5" }),
+		[`${root}/projects/scribe/scribe/package.json`]: JSON.stringify({
+			name: "@decohere/scribe",
+			version: "0.0.1-dev.5",
+		}),
+		[`${root}/projects/scribe/scribe-console/package.json`]: JSON.stringify({
+			name: "@decohere/scribe-console",
+			version: "0.0.1-dev.5",
+		}),
+	});
+}
+
+/**
+ * A fake registry: `published` names exist, and `trusted` names have a Trusted
+ * Publisher. Each call is recorded as its arguments, plus the code npm would
+ * get through NPM_CONFIG_OTP.
+ */
+function fakeNpm({ published = [], trusted = [], loggedIn = true } = {}) {
+	const calls = [];
+	const npm = (args, { otp } = {}) => {
+		calls.push(`${args.join(" ")}${otp ? ` [otp ${otp}]` : ""}`);
+		if (args[0] === "whoami") {
+			return { status: loggedIn ? 0 : 1, output: "" };
+		}
+		if (args[0] === "trust" && args[1] === "list") {
+			return trusted.includes(args[2])
+				? { status: 0, output: '[{"repository":"typesmiths/decohere","file":"publish.yml"}]' }
+				: { status: 0, output: "[]" };
+		}
+		return { status: 0, output: "" };
+	};
+	return { npm, calls, nameExists: (name) => published.includes(name) };
+}
+
+function run(argv, registry) {
+	const lines = [];
+	return runBootstrap({
+		argv,
+		root,
+		io: {
+			npm: registry.npm,
+			nameExists: registry.nameExists,
+			log: (line) => lines.push(line),
+		},
+	}).then((code) => ({ code, lines }));
+}
+
+afterEach(() => {
+	vol.reset();
+});
+
+describe("npm-bootstrap", () => {
+	it("first-publishes unpublished names restricted, then sets the Trusted Publisher", async () => {
+		seedWorkspace();
+		const registry = fakeNpm({ published: ["@decohere/scribe"] });
+
+		const { code } = await run(["--otp", "123456"], registry);
+
+		expect(code).toBe(0);
+		expect(registry.calls).toEqual([
+			"whoami",
+			"publish ./projects/scribe/scribe-console --tag dev [otp 123456]",
+			"trust list @decohere/scribe-console --json [otp 123456]",
+			"trust github @decohere/scribe-console --file publish.yml --repo typesmiths/decohere --env npm-publish --allow-publish --yes [otp 123456]",
+		]);
+	});
+
+	it("skips the steps that are already done", async () => {
+		seedWorkspace();
+		const registry = fakeNpm({
+			published: ["@decohere/scribe-console"],
+			trusted: ["@decohere/scribe-console"],
+		});
+
+		const { code } = await run(["@decohere/scribe-console"], registry);
+
+		expect(code).toBe(0);
+		expect(registry.calls).toEqual(["whoami", "trust list @decohere/scribe-console --json"]);
+	});
+
+	/** #700 — `npm trust` rejects `--otp`: the code goes through the environment. */
+	it("never passes the code as an argument, and lets npm ask when none is given", async () => {
+		seedWorkspace();
+		const withCode = fakeNpm({ published: ["@decohere/scribe"] });
+		await run(["--otp", "604381"], withCode);
+		expect(withCode.calls.join("\n")).not.toContain("--otp");
+
+		const withoutCode = fakeNpm({ published: ["@decohere/scribe"] });
+		expect((await run([], withoutCode)).code).toBe(0);
+		expect(withoutCode.calls.join("\n")).not.toContain("otp");
+	});
+
+	it("prints the commands on a dry run, calling npm only to check the login", async () => {
+		seedWorkspace();
+		const registry = fakeNpm({ published: ["@decohere/scribe"] });
+
+		const { code, lines } = await run(["--dry-run"], registry);
+
+		expect(code).toBe(0);
+		expect(registry.calls).toEqual(["whoami"]);
+		expect(lines).toContain(
+			"[dry run] npm publish ./projects/scribe/scribe-console --tag dev",
+		);
+	});
+
+	it("stops when not logged in, or for a name that is not a package", async () => {
+		seedWorkspace();
+		const loggedOut = fakeNpm({ loggedIn: false });
+		expect((await run(["--otp", "1"], loggedOut)).code).toBe(1);
+		expect(loggedOut.calls).toEqual(["whoami"]);
+
+		const typo = fakeNpm();
+		const { code, lines } = await run(["@decohere/scribe-consol"], typo);
+		expect(code).toBe(1);
+		expect(lines).toEqual(["Not a publishable package in projects/: @decohere/scribe-consol"]);
+	});
+});

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

@@ -53,6 +53,7 @@ describe("oidc-bootstrap-nudge", () => {
 			"npm publish ./projects/scaffold",
 		]);
 		expect(body).toContain("npm publish ./projects/scaffold --tag dev");
+		expect(body).toContain("pnpm npm:bootstrap --otp <code> @decohere/scaffold");
 		expect(body).not.toMatch(/# @decohere\/scaffold/);
 		expect(body).toContain("do **not** pass `--access public`");
 		expect(firstPublishCommands([pkg], "dev").join("\n")).not.toContain("--access public");