@decohere/ci-tools 0.0.1-dev.20 → 0.0.1-dev.20261105.54

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

@@ -0,0 +1,214 @@
+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/src/github/publish-verify.mjs

@@ -0,0 +1,206 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { listProjectDirs } from "../lib/workspace-packages.mjs";
+
+/**
+ * Workspace packages that `forge publish` will upload (not `"private": true`), including
+ * grouped ones such as `projects/data/data-typeorm`.
+ * @param {string} root
+ */
+export function listPublishablePackages(root) {
+	const packages = [];
+	for (const projectDir of listProjectDirs(root)) {
+		const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
+		if (typeof pkg.name !== "string" || pkg.private === true) {
+			continue;
+		}
+		packages.push({
+			name: pkg.name,
+			version: pkg.version,
+			dir: relative(join(root, "projects"), projectDir),
+		});
+	}
+	return packages.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function dockerRepositories(root) {
+	const create = JSON.parse(readFileSync(join(root, "projects/create/package.json"), "utf8"));
+	const devcontainer = JSON.parse(
+		readFileSync(join(root, "projects/devcontainer/package.json"), "utf8"),
+	);
+	return {
+		create: create.decohere?.dockerImageRepository ?? "ghcr.io/typesmiths/decohere/create",
+		devcontainer:
+			devcontainer.decohere?.dockerImageRepository ??
+			"ghcr.io/typesmiths/decohere/devcontainer",
+		createVersion: create.version,
+		workspaceVersion: JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version,
+	};
+}
+
+/**
+ * @param {string} spec package or package@version
+ * @param {{ spawnSync?: typeof spawnSync }} [io]
+ */
+export function npmNameExists(spec, io = {}) {
+	const spawn = io.spawnSync ?? spawnSync;
+	const result = spawn("npm", ["view", spec, "name"], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	return result.status === 0;
+}
+
+/**
+ * @param {string} spec package@version
+ * @param {{ spawnSync?: typeof spawnSync }} [io]
+ */
+export function npmVersionExists(spec, io = {}) {
+	const spawn = io.spawnSync ?? spawnSync;
+	const result = spawn("npm", ["view", spec, "version"], {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	return result.status === 0;
+}
+
+/**
+ * Parse `ghcr.io/org/name/image` into GitHub packages API coordinates.
+ * @param {string} repository
+ */
+export function parseGhcrRepository(repository) {
+	const withoutHost = repository.replace(/^ghcr\.io\//, "");
+	const slash = withoutHost.indexOf("/");
+	if (slash < 0) {
+		throw new Error(`Not a GHCR repository: ${repository}`);
+	}
+	return {
+		org: withoutHost.slice(0, slash),
+		packageName: withoutHost.slice(slash + 1),
+	};
+}
+
+/**
+ * @param {string} repository ghcr.io/org/pkg
+ * @param {string} tag
+ * @param {{ token: string, fetch?: typeof fetch }} io
+ */
+export async function ghcrTagExists(repository, tag, io) {
+	const { org, packageName } = parseGhcrRepository(repository);
+	const encoded = encodeURIComponent(packageName);
+	const headers = {
+		Authorization: `Bearer ${io.token}`,
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28",
+	};
+	const fetchImpl = io.fetch ?? fetch;
+	for (let page = 1; page <= 20; page += 1) {
+		const url = `https://api.github.com/orgs/${org}/packages/container/${encoded}/versions?per_page=100&page=${page}`;
+		const response = await fetchImpl(url, { headers });
+		if (response.status === 404) {
+			return false;
+		}
+		if (!response.ok) {
+			throw new Error(`GHCR versions ${response.status} for ${repository}`);
+		}
+		const versions = await response.json();
+		if (!Array.isArray(versions) || versions.length === 0) {
+			return false;
+		}
+		for (const version of versions) {
+			const tags = version.metadata?.container?.tags ?? [];
+			if (tags.includes(tag)) {
+				return true;
+			}
+		}
+		if (versions.length < 100) {
+			return false;
+		}
+	}
+	return false;
+}
+
+/**
+ * @param {{
+ *   root: string,
+ *   spawnSync?: typeof spawnSync,
+ *   fetch?: typeof fetch,
+ *   githubToken?: string,
+ * }} options
+ */
+export async function collectPublishVerify(options) {
+	const packages = listPublishablePackages(options.root);
+	const unpublished = [];
+	let publishedVersions = 0;
+	for (const pkg of packages) {
+		if (!npmNameExists(pkg.name, options)) {
+			unpublished.push(pkg.name);
+			continue;
+		}
+		if (npmVersionExists(`${pkg.name}@${pkg.version}`, options)) {
+			publishedVersions += 1;
+		}
+	}
+
+	const images = dockerRepositories(options.root);
+	const token = options.githubToken ?? "";
+	let skipDocker = false;
+	if (token) {
+		const createExists = await ghcrTagExists(images.create, images.workspaceVersion, {
+			token,
+			fetch: options.fetch,
+		});
+		const devExists = await ghcrTagExists(images.devcontainer, images.workspaceVersion, {
+			token,
+			fetch: options.fetch,
+		});
+		skipDocker = createExists && devExists;
+	}
+
+	return {
+		unpublished,
+		skipNpm: packages.length > 0 && publishedVersions === packages.length,
+		skipDocker,
+		imageTag: images.workspaceVersion,
+		createVersion: images.createVersion,
+		repository: images.create,
+		devcontainerRepository: images.devcontainer,
+		packageCount: packages.length,
+		publishedVersions,
+	};
+}
+
+export function formatGithubOutput(result) {
+	return [
+		`unpublished=${result.unpublished.join(" ")}`,
+		`skip_npm=${result.skipNpm ? "true" : "false"}`,
+		`skip_docker=${result.skipDocker ? "true" : "false"}`,
+		`image_tag=${result.imageTag}`,
+		`create_version=${result.createVersion}`,
+		`repository=${result.repository}`,
+		`devcontainer_repository=${result.devcontainerRepository}`,
+	].join("\n");
+}
+
+const isCli =
+	process.argv[1] != null && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+
+if (isCli) {
+	const result = await collectPublishVerify({
+		root: process.cwd(),
+		githubToken: process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN,
+	});
+	const body = formatGithubOutput(result);
+	process.stdout.write(`${body}\n`);
+	if (process.env.GITHUB_OUTPUT) {
+		const { appendFileSync } = await import("node:fs");
+		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`,
+		);
+	}
+}

package/src/github/smoke-create-launcher.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Run `npx @decohere/create@version --help` from an empty temp directory.
+ * Must not use the repo cwd — after `@decohere/cli` is pinned, pnpm installs
+ * `@decohere/create` into the workspace tree and npm's npx misses the bin.
+ * No token: the packages are public, so this installs the launcher the way a user does.
+ * Anonymous reads go through npm's cache, which can lag minutes behind a publish, so it
+ * first waits until npm serves the version (`attempts` tries, `intervalMs` apart).
+ *
+ * @param {{
+ *   createVersion: string,
+ *   attempts?: number,
+ *   intervalMs?: number,
+ *   sleep?: (ms: number) => void,
+ *   mkdtempSync?: typeof mkdtempSync,
+ *   writeFileSync?: typeof writeFileSync,
+ *   spawnSync?: typeof spawnSync,
+ *   tmpdir?: () => string,
+ *   stdio?: import("node:child_process").StdioOptions,
+ * }} options
+ */
+export function runCreateLauncherSmoke(options) {
+	const version = options.createVersion?.trim() ?? "";
+	if (!version) {
+		throw new Error("CREATE_VERSION is required");
+	}
+
+	const mkdtemp = options.mkdtempSync ?? mkdtempSync;
+	const writeFile = options.writeFileSync ?? writeFileSync;
+	const spawn = options.spawnSync ?? spawnSync;
+	const tmp = options.tmpdir ?? tmpdir;
+	const sleep = options.sleep ?? sleepSync;
+	const attempts = options.attempts ?? 20;
+	const intervalMs = options.intervalMs ?? 15_000;
+
+	const workDir = mkdtemp(join(tmp(), "decohere-create-smoke-"));
+	const npmrc = join(workDir, ".npmrc");
+	writeFile(npmrc, "@decohere:registry=https://registry.npmjs.org/\n");
+
+	const env = { ...process.env, NPM_CONFIG_USERCONFIG: npmrc };
+	const spec = `@decohere/create@${version}`;
+
+	for (let attempt = 1; ; attempt++) {
+		const view = spawn("npm", ["view", spec, "version"], { cwd: workDir, env, stdio: "pipe" });
+		if (view.status === 0) break;
+		if (attempt >= attempts) {
+			console.error(`${spec} is still not served by npm after ${attempts} tries`);
+			return { workDir, status: 1 };
+		}
+		console.log(`${spec} not served by npm yet (try ${attempt} of ${attempts}); waiting`);
+		sleep(intervalMs);
+	}
+
+	const result = spawn("npx", ["--yes", spec, "--help"], {
+		cwd: workDir,
+		env,
+		stdio: options.stdio ?? "inherit",
+	});
+
+	return {
+		workDir,
+		status: result.status ?? 1,
+	};
+}
+
+/** @param {number} ms */
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+const isCli =
+	process.argv[1] != null && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+
+if (isCli) {
+	const { status } = runCreateLauncherSmoke({
+		createVersion: process.env.CREATE_VERSION ?? "",
+	});
+	process.exit(status);
+}

package/src/lib/github-issue.mjs

@@ -0,0 +1,75 @@
+/**
+ * One GitHub issue per subject, found again by its exact title and updated in place: CI files
+ * a reminder once and keeps it current instead of opening a new issue every run. Needs `gh` and
+ * GH_TOKEN (or GITHUB_TOKEN) with issues: write.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * @param {string[]} args
+ * @param {string} [input]
+ */
+export function gh(args, input) {
+	const result = spawnSync("gh", args, { encoding: "utf8", input, env: process.env });
+	if (result.status !== 0) {
+		throw new Error(result.stderr || result.stdout || `gh ${args.join(" ")} failed`);
+	}
+	return result.stdout;
+}
+
+/**
+ * The issue titled exactly `title`, preferring an open one over a closed one.
+ *
+ * @param {{ number: number, title: string, state: string, url: string }[]} issues
+ * @param {string} title
+ */
+export function pickIssue(issues, title) {
+	const matches = issues.filter((issue) => issue.title === title);
+	return matches.find((issue) => issue.state === "OPEN") ?? matches[0] ?? null;
+}
+
+/**
+ * @param {{ title: string, body: string, assignees?: string[], repo?: string }} options
+ * @param {typeof gh} [run]
+ * @returns {{ number: number, url: string, created: boolean }}
+ */
+export function upsertIssue(options, run = gh) {
+	const { title, body, assignees = [] } = options;
+	const repo = options.repo ? ["--repo", options.repo] : [];
+	const issues = JSON.parse(
+		run([
+			"issue",
+			"list",
+			...repo,
+			"--state",
+			"all",
+			"--limit",
+			"200",
+			"--search",
+			// Quoted: GitHub's search can't match a title like `security(ci): …` unquoted.
+			// The exact-title match in pickIssue still decides.
+			`"${title.replaceAll('"', "")}" in:title`,
+			"--json",
+			"number,title,state,url",
+		]),
+	);
+	const assign = assignees.flatMap((login) => ["--add-assignee", login]);
+	const existing = pickIssue(issues, title);
+	if (existing != null) {
+		if (existing.state !== "OPEN") {
+			run(["issue", "reopen", String(existing.number), ...repo]);
+		}
+		run(
+			["issue", "edit", String(existing.number), ...repo, "--body-file", "-", ...assign],
+			body,
+		);
+		return { number: existing.number, url: existing.url, created: false };
+	}
+	const url = run(
+		["issue", "create", ...repo, "--title", title, "--body-file", "-", ...assign],
+		body,
+	).trim();
+	const number = Number(url.split("/").pop());
+	return { number, url, created: true };
+}

package/src/lib/lcov.mjs

@@ -13,7 +13,7 @@ function normalizePath(filePath) {
 
 /**
  * Extracts the top-level project name from a source path like
- * `/workspace/projects/hearth/src/foo.ts` → `"hearth"`.
+ * `/workspace/projects/core/src/foo.ts` → `"core"`.
  * @param {string} sourcePath
  * @returns {string | undefined}
  */

package/src/lib/workspace-packages.mjs

@@ -0,0 +1,30 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+// The same rule as WorkspaceDefaults in @decohere/workspace (`projects/**/package.json`, minus these
+// folders, and a package.json inside another project is not a project). CI scripts run on plain
+// Node before any install, so they can't import the workspace package itself.
+const SKIP = new Set(["node_modules", "__fixtures__", "dist"]);
+
+/**
+ * Every project directory under `<root>/projects`, at any depth (`projects/cli`,
+ * `projects/data/data-typeorm`).
+ * @param {string} root
+ * @returns {string[]} absolute paths
+ */
+export function listProjectDirs(root) {
+	const found = [];
+	const walk = (dir) => {
+		if (existsSync(join(dir, "package.json"))) {
+			found.push(dir);
+			return;
+		}
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			if (entry.isDirectory() && !SKIP.has(entry.name) && !entry.name.startsWith(".")) {
+				walk(join(dir, entry.name));
+			}
+		}
+	};
+	walk(join(root, "projects"));
+	return found;
+}