@decohere/ci-tools 0.0.1-dev.126 → 0.0.1-dev.13

package/src/github/credential-nudge.mjs

@@ -1,226 +0,0 @@
-import { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { upsertIssue } from "../lib/github-issue.mjs";
-
-const WARN_DAYS = 14;
-const MS_PER_DAY = 86_400_000;
-const DEFAULT_REPO = "typesmiths/decohere";
-
-/**
- * One profile per credential (repo secret + repo variable). Date math, GitHub issue
- * upsert, and fail-closed live below.
- *
- * @typedef {{
- *   id: string,
- *   secret: string,
- *   expiresVar: string,
- *   mint: string,
- *   failImpact: string,
- *   rejectedWhy: string,
- *   revokeUrl: string,
- * }} CredentialProfile
- */
-
-/** @type {Record<string, CredentialProfile>} */
-export const CREDENTIALS = {
-	npm: {
-		id: "npm",
-		secret: "NODE_AUTH_TOKEN",
-		expiresVar: "NODE_AUTH_TOKEN_EXPIRES_AT",
-		mint: "Create an npm **read** token (granular/classic) at https://www.npmjs.com/settings/~/tokens — Publish PUTs are OIDC; this token is only for private `npm view` and create smoke.",
-		failImpact:
-			"Verify cannot see private packages, so skipIfPublished and create smoke are unsafe. Publish **fails closed** before OIDC/Docker. After you rotate, re-run the failed Publish jobs.",
-		rejectedWhy: "`npm whoami` failed (expired, revoked, or missing `NODE_AUTH_TOKEN`).",
-		revokeUrl: "https://www.npmjs.com/settings/~/tokens",
-	},
-};
-
-export function utcDayMs(date) {
-	return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
-}
-
-/** @param {string | undefined} raw */
-export function parseExpiresAt(raw) {
-	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(raw ?? "").trim());
-	if (!match) {
-		return null;
-	}
-	return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
-}
-
-/**
- * @param {{ now?: number, expiresAtMs: number | null, warnDays?: number }} options
- * @returns {{ kind: "missing" | "ok" | "warn" | "expired", daysLeft: number | null }}
- */
-export function assessTokenLifetime(options) {
-	const { expiresAtMs, warnDays = WARN_DAYS } = options;
-	if (expiresAtMs == null) {
-		return { kind: "missing", daysLeft: null };
-	}
-	const today = utcDayMs(new Date(options.now ?? Date.now()));
-	const daysLeft = Math.round((expiresAtMs - today) / MS_PER_DAY);
-	if (daysLeft <= 0) {
-		return { kind: "expired", daysLeft };
-	}
-	if (daysLeft <= warnDays) {
-		return { kind: "warn", daysLeft };
-	}
-	return { kind: "ok", daysLeft };
-}
-
-/** @param {CredentialProfile} credential */
-export function resolveRepo() {
-	return process.env.GITHUB_REPOSITORY?.trim() || DEFAULT_REPO;
-}
-
-/** @param {string} id */
-export function credentialProfile(id) {
-	const credential = CREDENTIALS[id];
-	if (!credential) {
-		throw new Error(
-			`Unknown NUDGE_CREDENTIAL=${id}. Expected one of: ${Object.keys(CREDENTIALS).join(", ")}`,
-		);
-	}
-	return credential;
-}
-
-/** @param {CredentialProfile} credential */
-export function issueTitle(credential, expiresYmd) {
-	return `chore(security): rotate ${credential.secret} (expires ${expiresYmd})`;
-}
-
-/** @param {CredentialProfile} credential */
-export function rotationCommands(credential, nextExpiresYmd, repo = resolveRepo()) {
-	const next = nextExpiresYmd ?? "YYYY-MM-DD";
-	return [
-		credential.mint,
-		"",
-		"Then from a trusted machine (do not paste the token into Actions or this issue):",
-		"",
-		"```bash",
-		`gh secret set ${credential.secret} --repo ${repo}`,
-		`gh variable set ${credential.expiresVar} --repo ${repo} --body ${next}`,
-		"```",
-		"",
-		`Revoke the old token: ${credential.revokeUrl}`,
-		"Close this issue, then retry Publish:",
-		"",
-		"```bash",
-		`gh run list --repo ${repo} --workflow Publish --limit 5`,
-		`gh run rerun --failed <run-id> --repo ${repo}`,
-		"```",
-	].join("\n");
-}
-
-export function suggestedNextExpiry(fromMs, days = 90) {
-	const start = utcDayMs(new Date(fromMs));
-	const next = new Date(start + days * MS_PER_DAY);
-	const y = next.getUTCFullYear();
-	const m = String(next.getUTCMonth() + 1).padStart(2, "0");
-	const d = String(next.getUTCDate()).padStart(2, "0");
-	return `${y}-${m}-${d}`;
-}
-
-/** @param {CredentialProfile} credential */
-export function buildDescription(credential, options) {
-	const { kind, expiresYmd, daysLeft, rejected, runUrl } = options;
-	const next = suggestedNextExpiry(Date.now());
-	const why = rejected
-		? credential.rejectedWhy
-		: kind === "expired"
-			? `${credential.expiresVar} (${expiresYmd}) is today or in the past. Rotate ${credential.secret} and this date before Publish can continue.`
-			: `${credential.secret} expires on ${expiresYmd} (${daysLeft} day(s) left). Rotate before that date so Publish does not fail closed.`;
-	return [
-		"## Summary",
-		"",
-		why,
-		"",
-		"## If this is not done in time",
-		"",
-		credential.failImpact,
-		"",
-		"## Commands",
-		"",
-		rotationCommands(credential, next),
-		"",
-		runUrl ? `- Workflow run: ${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 {CredentialProfile} credential */
-export function upsertRotationIssue(credential, options, upsert = upsertIssue) {
-	const { expiresYmd, kind, daysLeft, rejected } = options;
-	return upsert({
-		title: issueTitle(credential, expiresYmd ?? "unknown"),
-		body: buildDescription(credential, {
-			kind,
-			expiresYmd,
-			daysLeft,
-			rejected,
-			runUrl: runUrl(),
-		}),
-	});
-}
-
-export async function runNudge(env = process.env, upsert = upsertIssue) {
-	const credential = credentialProfile(String(env.NUDGE_CREDENTIAL ?? "").trim());
-	const rejected = env.NUDGE_REJECTED === "1";
-	const expiresYmd = String(env[credential.expiresVar] ?? "").trim();
-	const expiresAtMs = parseExpiresAt(expiresYmd);
-	const assessment = assessTokenLifetime({ expiresAtMs });
-	const repo = env.GITHUB_REPOSITORY?.trim() || DEFAULT_REPO;
-
-	if (assessment.kind === "missing" && !rejected) {
-		process.stderr.write(
-			`repository variable ${credential.expiresVar}=YYYY-MM-DD is required\n` +
-				`  gh variable set ${credential.expiresVar} --repo ${repo} --body YYYY-MM-DD\n`,
-		);
-		return 1;
-	}
-
-	if (rejected || assessment.kind === "warn" || assessment.kind === "expired") {
-		const result = upsertRotationIssue(
-			credential,
-			{
-				expiresYmd: expiresYmd || "unknown",
-				kind: assessment.kind,
-				daysLeft: assessment.daysLeft,
-				rejected,
-			},
-			upsert,
-		);
-		process.stdout.write(
-			`${result.created ? "Opened" : "Updated"} issue #${result.number} ${result.url}\n`,
-		);
-	}
-
-	if (rejected || assessment.kind === "expired" || assessment.kind === "missing") {
-		if (assessment.kind === "expired") {
-			process.stderr.write(
-				`${credential.secret} calendar expiry ${expiresYmd} has been reached — refusing to continue\n`,
-			);
-		}
-		return 1;
-	}
-	return 0;
-}
-
-const isCli =
-	process.argv[1] != null && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
-
-if (isCli) {
-	process.exit(await runNudge());
-}

package/src/github/npm-bootstrap.mjs

@@ -1,179 +0,0 @@
-/**
- * First-publish a new package name (public) 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. Scoped names default to restricted,
- * so `--access public`. `./` 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}`, "--access", "public", ...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,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());
-}