@cldmv/gh-broker 0.7.0 → 0.8.0

package/tests/install-args.test.vitest.mts

@@ -0,0 +1,152 @@
+import { describe, it, expect } from "vitest";
+import { parseArgs, envSecretKey } from "../deploy/lib/install-args.mjs";
+
+describe("parseArgs", () => {
+	it("defaults", () => {
+		expect(parseArgs([])).toEqual({ positional: [], nonInteractive: false, createAgentUser: false, npm: false, npmScopes: [], npmOrgs: [], cliSecrets: {} });
+	});
+
+	it("reads every flag", () => {
+		const o = parseArgs([
+			"repo",
+			"-h",
+			"-y",
+			"--create-agent-user",
+			"--agent-user",
+			"agent",
+			"--secrets-provider",
+			"file",
+			"--secrets-file",
+			"/x/s.json",
+			"--npm",
+			"--npm-scope",
+			"@cldmv",
+			"--npm-scope",
+			"@other",
+			"--npm-org",
+			"cldmv",
+			"--npm-token-days",
+			"30"
+		]);
+		expect(o).toEqual({
+			positional: ["repo"],
+			help: true,
+			nonInteractive: true,
+			createAgentUser: true,
+			agentUser: "agent",
+			provider: "file",
+			secretsFile: "/x/s.json",
+			npm: true,
+			npmScopes: ["@cldmv", "@other"],
+			npmOrgs: ["cldmv"],
+			npmTokenDays: 30,
+			cliSecrets: {}
+		});
+		expect(parseArgs(["--help", "--non-interactive"])).toMatchObject({ help: true, nonInteractive: true });
+	});
+
+	it("parses every config flag", () => {
+		const o = parseArgs([
+			"--config", "/etc/x.json",
+			"--owner", "acme", "--owner", "beta",
+			"--installation-id", "acme=42",
+			"--default-owner", "acme",
+			"--listen", "unix:/run/x.sock",
+			"--upstream", "https://example.test/mcp",
+			"--app-id", "77",
+			"--app-private-key", "cred:my-key",
+			"--secrets-path", "/etc/s.json",
+			"--npm", "--npm-registry", "https://registry.example.test",
+			"--ghcr-owner", "acme", "--ghcr-username", "Me-1",
+			"--ghcr-image", "app", "--ghcr-image", "app-*", "--ghcr-image", "team/svc",
+			"--ghcr-drop-dir", "/srv/x/drop",
+			"--ghcr-max-archive-bytes", "1048576",
+			"--no-protect-release-tags"
+		]);
+		expect(o).toMatchObject({
+			configFile: "/etc/x.json",
+			owners: ["acme", "beta"],
+			installationIds: { acme: 42 },
+			defaultOwner: "acme",
+			listen: "unix:/run/x.sock",
+			upstream: "https://example.test/mcp",
+			appId: 77,
+			appPrivateKey: "my-key",
+			secretsPath: "/etc/s.json",
+			npmRegistry: "https://registry.example.test",
+			ghcrOwner: "acme",
+			ghcrUsername: "Me-1",
+			ghcrImages: ["app", "app-*", "team/svc"],
+			ghcrDropDir: "/srv/x/drop",
+			ghcrMaxArchiveBytes: 1048576,
+			protectReleaseTags: false
+		});
+		expect(parseArgs(["--protect-release-tags"]).protectReleaseTags).toBe(true);
+		expect(parseArgs(["--app-id", "5"]).appPrivateKey).toBeUndefined();
+	});
+
+	it("leaves the config fields unset when no config flag is given", () => {
+		const o = parseArgs(["--agent-user", "a"]);
+		for (const k of ["configFile", "owners", "defaultOwner", "listen", "upstream", "appId", "ghcrOwner", "protectReleaseTags"]) expect(o[k]).toBeUndefined();
+	});
+
+	it("collects --secret name=token pairs, keeping any = inside the token", () => {
+		const o = parseArgs(["--secret", "cldmv-read=ghp_abc", "--secret", "npm-token=npm_x=y==", "--secret", "cldmv-read=ghp_new"]);
+		expect(o.cliSecrets).toEqual({ "cldmv-read": "ghp_new", "npm-token": "npm_x=y==" });
+	});
+
+	it.each([
+		[["--secret"], /--secret requires a value/],
+		[["--secret", "novalue"], /--secret takes <cred-name>=<token>/],
+		[["--secret", "=tok"], /--secret takes <cred-name>=<token>/],
+		[["--secret", "name="], /--secret takes <cred-name>=<token>/],
+		[["--secret", "../x=tok"], /unsafe credential name/],
+		[["--agent-user", "--secrets-provider", "file"], /--agent-user requires a value/],
+		[["--secrets-provider", "vault"], /--secrets-provider must be "systemd-creds" or "file"/],
+		[["--npm-scope", "cldmv"], /--npm-scope must be a lowercase npm scope/],
+		[["--npm-org", "@cldmv"], /--npm-org must be a lowercase npm org name/],
+		[["--npm-token-days", "0"], /--npm-token-days must be a whole number of days/],
+		[["--npm-token-days", "1.5"], /--npm-token-days must be a whole number of days/],
+		[["--config"], /--config requires a value/],
+		[["--config", "--owner"], /--config requires a value/],
+		[["--owner", "Acme"], /--owner must be a lowercase GitHub owner name/],
+		[["--owner", "-x"], /--owner requires a value/],
+		[["--installation-id", "acme"], /--installation-id takes <owner>=<numeric id>/],
+		[["--installation-id", "Acme=1"], /--installation-id takes/],
+		[["--installation-id", "acme=0"], /--installation-id takes/],
+		[["--installation-id", "=5"], /--installation-id takes/],
+		[["--default-owner", "A_B"], /--default-owner must be a lowercase GitHub owner name/],
+		[["--listen", "/run/x.sock"], /--listen must be a "unix:<absolute path>"/],
+		[["--upstream", "ftp://x"], /--upstream must be an http\(s\) URL/],
+		[["--app-id", "abc"], /--app-id must be the numeric GitHub App id/],
+		[["--app-private-key", "k"], /--app-private-key needs --app-id/],
+		[["--app-id", "1", "--app-private-key", "../k"], /unsafe credential name/],
+		[["--secrets-path", "rel.json"], /--secrets-path must be an absolute path/],
+		[["--npm-registry", "https://r"], /--npm-registry only applies together with --npm/],
+		[["--npm", "--npm-registry", "http://r"], /--npm-registry must be an https URL/],
+		[["--ghcr-owner", "Acme"], /--ghcr-owner must be a lowercase GitHub owner name/],
+		[["--ghcr-owner", "acme"], /--ghcr-owner needs --ghcr-username and at least one --ghcr-image/],
+		[["--ghcr-owner", "acme", "--ghcr-username", "me"], /--ghcr-owner needs --ghcr-username/],
+		[["--ghcr-owner", "acme", "--ghcr-image", "app"], /--ghcr-owner needs --ghcr-username/],
+		[["--ghcr-username", "me"], /need --ghcr-owner/],
+		[["--ghcr-image", "app"], /need --ghcr-owner/],
+		[["--ghcr-username", "-bad"], /--ghcr-username requires a value/],
+		[["--ghcr-username", "bad_name"], /--ghcr-username must be a GitHub login/],
+		[["--ghcr-image", "Bad/IMG"], /--ghcr-image must be a lowercase image name/],
+		[["--ghcr-image", "a".repeat(256)], /--ghcr-image must be a lowercase image name/],
+		[["--ghcr-drop-dir", "drop"], /--ghcr-drop-dir must be an absolute path/],
+		[["--ghcr-max-archive-bytes", "0"], /--ghcr-max-archive-bytes must be a positive whole number/],
+		[["--ghcr-max-archive-bytes", "9999999999999999"], /--ghcr-max-archive-bytes must be a positive whole number/],
+		[["--ghcr-max-archive-bytes", "1.5"], /--ghcr-max-archive-bytes must be a positive whole number/],
+		[["--bogus"], /unknown flag: --bogus/]
+	] as Array<[string[], RegExp]>)("refuses %j", (argv, msg) => {
+		expect(() => parseArgs(argv)).toThrow(msg);
+	});
+});
+
+describe("envSecretKey", () => {
+	it("upper-cases and replaces non-alphanumerics", () => {
+		expect(envSecretKey("npm-token")).toBe("GH_BROKER_SECRET_NPM_TOKEN");
+		expect(envSecretKey("cldmv.read")).toBe("GH_BROKER_SECRET_CLDMV_READ");
+	});
+});

package/tests/issue-labels.test.vitest.mts

@@ -245,6 +245,21 @@ describe("issueLabels", () => {
 			expect(gh.issue).toEqual(["type: bug"]);
 		});
 
+		it("reports a set as applied when only building the result fails", async () => {
+			// The PUT succeeds but answers with a label that has no name, which the result builder cannot lowercase.
+			const g = fakeGitHub(REPO, ["type: bug"]);
+			const inner = g.request.getMockImplementation()!;
+			g.request.mockImplementation(async (route: string, p: any) => (route.startsWith("PUT") ? { data: [{}] } : inner(route, p)));
+			const err = await issueLabels(g.octokit, { ...base, set: ["type: bug"] }).catch((e) => e);
+			expect(err.message).toMatch(/failed part-way on cldmv\/gh-broker#117: .*Applied: set \[type: bug\]\. Not applied: nothing\.$/);
+		});
+
+		it("treats label lists that are not arrays as empty", async () => {
+			const request = vi.fn(async (route: string) => (route.startsWith("POST /repos/{owner}/{repo}/issues") ? { data: null } : route.startsWith("GET /repos/{owner}/{repo}/issues") ? { data: {} } : { data: { name: "x" } }));
+			const out = await issueLabels({ request } as any, { ...base, add: "x" });
+			expect(out.labels).toEqual([]);
+		});
+
 		it("a failing first read or label lookup writes nothing and is passed through unchanged", async () => {
 			gh = fakeGitHub(REPO, ["type: bug"], { fail: (route) => (route === "GET /repos/{owner}/{repo}/labels/{name}" ? httpError(500, "Server Error") : undefined) });
 			await expect(issueLabels(gh.octokit, { ...base, add: "area: auth" })).rejects.toThrow(/^Server Error$/);

package/tests/npm-scaffold.test.vitest.mts

@@ -0,0 +1,479 @@
+import { describe, it, expect, vi } from "vitest";
+import { gunzipSync } from "node:zlib";
+import { createHash } from "node:crypto";
+import { npmScaffold, placeholderDocument, NPM_SCAFFOLD_SCHEMA, PLACEHOLDER_VERSION, SCAFFOLD_MARKER } from "../src/verbs/npm_scaffold.ts";
+import { NpmRegistry, NpmOtpRequired, NpmHttpError, escapePackageName, type FetchLike } from "../src/verbs/npm-registry.ts";
+import { buildTarball, tarballDigests } from "../src/verbs/npm-tarball.ts";
+
+const TOKEN = "npm_SECRETTOKENVALUE";
+const OTP = "123456";
+const OTP2 = "654321";
+const PKG = "@cldmv/new-thing";
+
+/** Read the ustar entries back out of a gzipped tarball. */
+function untar(tgz: Buffer): Record<string, string> {
+	const tar = gunzipSync(tgz);
+	const out: Record<string, string> = {};
+	for (let off = 0; off + 512 <= tar.length; ) {
+		const head = tar.subarray(off, off + 512);
+		if (head.every((b) => b === 0)) break;
+		const name = head.subarray(0, 100).toString("ascii").replace(/\0.*$/, "");
+		const size = parseInt(head.subarray(124, 136).toString("ascii").replace(/\0.*$/, ""), 8);
+		const stored = parseInt(head.subarray(148, 156).toString("ascii").replace(/[\0 ].*$/, ""), 8);
+		const copy = Buffer.from(head);
+		copy.fill(0x20, 148, 156);
+		expect(copy.reduce((s, b) => s + b, 0)).toBe(stored);
+		out[name] = tar.subarray(off + 512, off + 512 + size).toString("utf8");
+		off += 512 + Math.ceil(size / 512) * 512;
+	}
+	return out;
+}
+
+type RegistryOpts = {
+	existing?: Record<string, unknown>;
+	/** Codes the registry accepts; each works once. */
+	otps?: string[];
+	trustStatus?: number;
+	publishStatus?: number;
+	lookupStatus?: number;
+	/** Trusted publishers already on the package: a POST then answers 409. */
+	existingTrust?: any[];
+	/** GET of the trust list wants an OTP (it is behind otplease in the npm CLI). */
+	trustListNeedsOtp?: boolean;
+	/** POST-trust reply body instead of the created configs (e.g. one without an id). */
+	trustCreatedBody?: string;
+	/** Raw GET-trust reply instead of the list. */
+	trustListReply?: { status: number; body: string };
+};
+
+function fakeRegistry(opts: RegistryOpts = {}) {
+	const packages = new Map<string, any>(Object.entries(opts.existing ?? {}));
+	const valid = [...(opts.otps ?? [OTP])];
+	const trust: any[] = [...(opts.existingTrust ?? [])];
+	const calls: Array<{ method: string; url: string; headers: Record<string, string>; body?: any }> = [];
+	const otpRefused = () => ({ status: 401, headers: { get: (n: string) => (n === "www-authenticate" ? "OTP" : null) }, text: async () => '{"error":"You must provide a one-time pass."}' });
+	const reply = (status: number, body: unknown) => ({ status, headers: { get: () => null }, text: async () => (typeof body === "string" ? body : JSON.stringify(body)) });
+	const fetch = vi.fn<FetchLike>(async (url, init) => {
+		calls.push({ method: init.method, url, headers: init.headers, ...(init.body ? { body: JSON.parse(init.body) } : {}) });
+		expect(init.headers.authorization).toBe(`Bearer ${TOKEN}`);
+		const path = new URL(url).pathname;
+		const useOtp = () => {
+			const code = init.headers["npm-otp"];
+			const at = code ? valid.indexOf(code) : -1;
+			if (at === -1) return false;
+			valid.splice(at, 1);
+			return true;
+		};
+		if (init.method === "GET" && path === `/${escapePackageName(PKG)}`) {
+			// Read from the primary, not a cache, as npm does before a write.
+			expect(new URL(url).searchParams.get("write")).toBe("true");
+			if (opts.lookupStatus) return reply(opts.lookupStatus, { error: "boom" });
+			const p = packages.get(PKG);
+			return p ? reply(200, p) : reply(404, { error: "Not found" });
+		}
+		if (init.method === "PUT" && path === `/${escapePackageName(PKG)}`) {
+			if (!useOtp()) return otpRefused();
+			if (opts.publishStatus) return reply(opts.publishStatus, { error: "You do not have permission to publish" });
+			const doc = JSON.parse(init.body!);
+			packages.set(PKG, { name: doc.name, versions: doc.versions, "dist-tags": doc["dist-tags"] });
+			return reply(200, { ok: true });
+		}
+		if (init.method === "POST" && path === `/-/package/${escapePackageName(PKG)}/trust`) {
+			if (!useOtp()) return otpRefused();
+			if (opts.trustStatus) return reply(opts.trustStatus, { error: "bad request" });
+			if (trust.length) return reply(409, { error: "a trusted publisher already exists" });
+			const body = JSON.parse(init.body!);
+			trust.push(...body);
+			if (opts.trustCreatedBody !== undefined) return reply(201, opts.trustCreatedBody);
+			return reply(201, body.map((b: any, i: number) => ({ ...b, id: `trust-${i + 1}` })));
+		}
+		if (init.method === "GET" && path === `/-/package/${escapePackageName(PKG)}/trust`) {
+			if (opts.trustListNeedsOtp && !useOtp()) return otpRefused();
+			if (opts.trustListReply) return reply(opts.trustListReply.status, opts.trustListReply.body);
+			return reply(200, trust);
+		}
+		throw new Error(`unexpected ${init.method} ${url}`);
+	});
+	return { registry: new NpmRegistry({ token: TOKEN, fetch }), fetch, calls, packages, trust };
+}
+
+type RepoOpts = { private?: boolean; archived?: boolean; pkg?: unknown; pkgRaw?: string; workflow?: boolean; missing?: boolean; pkgIsDir?: boolean; plainEncoding?: boolean; bareRepo?: boolean };
+
+function fakeGitHub(o: RepoOpts = {}) {
+	const notFound = () => Object.assign(new Error("Not Found"), { status: 404 });
+	const file = (s: string) => (o.plainEncoding ? { data: { type: "file", encoding: "utf-8", content: s } } : { data: { type: "file", encoding: "base64", content: Buffer.from(s).toString("base64") } });
+	const request = vi.fn(async (route: string, p: any) => {
+		if (route === "GET /repos/{owner}/{repo}") {
+			if (o.missing) throw notFound();
+			if (o.bareRepo) return { data: { private: false } };
+			return { data: { full_name: "CLDMV/new-thing", private: o.private ?? false, archived: o.archived ?? false, default_branch: "master" } };
+		}
+		if (route === "GET /repos/{owner}/{repo}/contents/{path}") {
+			expect(p.ref).toBe(o.bareRepo ? "HEAD" : "master");
+			if (p.path === "package.json") {
+				if (o.pkgIsDir) return { data: [{ type: "file", name: "x" }] };
+				if (o.pkg === undefined && o.pkgRaw === undefined) return file(JSON.stringify({ name: PKG, license: "Apache-2.0", description: "A new thing." }));
+				if (o.pkg === null) throw notFound();
+				return file(o.pkgRaw ?? JSON.stringify(o.pkg));
+			}
+			if (p.path === ".github/workflows/publish.yml" || p.path === ".github/workflows/release.yaml") {
+				if (o.workflow === false) throw notFound();
+				return file("name: publish\n");
+			}
+			throw notFound();
+		}
+		throw new Error(`unexpected route ${route}`);
+	});
+	return { octokit: { request } as any, request };
+}
+
+const args = (extra: Record<string, unknown> = {}) => ({ owner: "cldmv", repo: "new-thing", package: PKG, otp: OTP, ...extra });
+const deps = (gh: ReturnType<typeof fakeGitHub>, reg: ReturnType<typeof fakeRegistry>, scopes = ["@cldmv"]) => ({ octokit: gh.octokit, registry: reg.registry, scopes });
+
+describe("buildTarball", () => {
+	it("writes package/-prefixed ustar entries with valid checksums, gzipped", () => {
+		const files = untar(buildTarball([{ path: "package.json", content: '{"name":"x"}' }, { path: "README.md", content: "# x\n".repeat(200) }]));
+		expect(Object.keys(files)).toEqual(["package/package.json", "package/README.md"]);
+		expect(files["package/package.json"]).toBe('{"name":"x"}');
+		expect(files["package/README.md"]).toBe("# x\n".repeat(200));
+	});
+
+	it("is reproducible (fixed mtime)", () => {
+		const f = [{ path: "a.txt", content: "a" }];
+		expect(buildTarball(f).equals(buildTarball(f))).toBe(true);
+	});
+
+	it("refuses paths it cannot store", () => {
+		expect(() => buildTarball([{ path: "x".repeat(100), content: "" }])).toThrow(/unsupported path/);
+		expect(() => buildTarball([{ path: "naïve.txt", content: "" }])).toThrow(/unsupported path/);
+	});
+
+	it("computes the sha512 integrity and sha1 shasum of the tarball", () => {
+		const tgz = buildTarball([{ path: "a", content: "a" }]);
+		const d = tarballDigests(tgz);
+		expect(d.integrity).toBe(`sha512-${createHash("sha512").update(tgz).digest("base64")}`);
+		expect(d.shasum).toBe(createHash("sha1").update(tgz).digest("hex"));
+	});
+});
+
+describe("placeholderDocument", () => {
+	it("builds the first-publish document with a marked placeholder manifest and matching tarball", () => {
+		const doc = placeholderDocument(PKG, { repository: "CLDMV/new-thing", isPrivate: false, license: "Apache-2.0" }, "public", "https://registry.npmjs.org");
+		expect(doc["dist-tags"]).toEqual({ latest: PLACEHOLDER_VERSION });
+		expect(doc.access).toBe("public");
+		const v = doc.versions[PLACEHOLDER_VERSION]!;
+		expect(v.scaffoldedBy).toBe(SCAFFOLD_MARKER);
+		expect(v.license).toBe("Apache-2.0");
+		expect(v.repository).toEqual({ type: "git", url: "git+https://github.com/CLDMV/new-thing.git" });
+		expect(v.dist.tarball).toBe(`https://registry.npmjs.org/${PKG}/-/new-thing-${PLACEHOLDER_VERSION}.tgz`);
+		const att = doc._attachments[`${PKG}-${PLACEHOLDER_VERSION}.tgz`]!;
+		const tgz = Buffer.from(att.data, "base64");
+		expect(att.length).toBe(tgz.length);
+		expect(v.dist.integrity).toBe(tarballDigests(tgz).integrity);
+		const files = untar(tgz);
+		expect(JSON.parse(files["package/package.json"]!)).toMatchObject({ name: PKG, version: PLACEHOLDER_VERSION, scaffoldedBy: SCAFFOLD_MARKER });
+		expect(files["package/README.md"]).toContain("https://github.com/CLDMV/new-thing");
+		// Only the two broker-built files: nothing else ships.
+		expect(Object.keys(files)).toEqual(["package/package.json", "package/README.md"]);
+	});
+
+	it("falls back to UNLICENSED when the repo names no license", () => {
+		const doc = placeholderDocument(PKG, { repository: "CLDMV/new-thing", isPrivate: true }, "restricted", "https://registry.npmjs.org");
+		expect(doc.versions[PLACEHOLDER_VERSION]!.license).toBe("UNLICENSED");
+		expect(doc.access).toBe("restricted");
+	});
+});
+
+describe("npm_scaffold", () => {
+	it("advertises a strict schema", () => {
+		expect(NPM_SCAFFOLD_SCHEMA.required).toEqual(["owner", "repo", "package", "otp"]);
+		expect(NPM_SCAFFOLD_SCHEMA.additionalProperties).toBe(false);
+	});
+
+	it("publishes the placeholder, then adds the trusted publisher on a second call with the next code", async () => {
+		const reg = fakeRegistry({ otps: [OTP, OTP2] });
+		const first = await npmScaffold(args(), deps(fakeGitHub(), reg));
+		expect(first).toMatchObject({ status: "needs_otp", done: ["publish"], remaining: ["trust"], access: "public", repository: "CLDMV/new-thing", version: PLACEHOLDER_VERSION });
+		expect(first.message).toMatch(/needs its own one-time password/);
+		// The spent code is never sent again: no trust request on the first call.
+		expect(reg.calls.filter((c) => c.url.endsWith("/trust"))).toHaveLength(0);
+		const put = reg.calls.find((c) => c.method === "PUT")!;
+		expect(put.headers["npm-otp"]).toBe(OTP);
+		expect(put.body.access).toBe("public");
+
+		const second = await npmScaffold(args({ otp: OTP2 }), deps(fakeGitHub(), reg));
+		expect(second).toMatchObject({ status: "done", done: ["trust"], skipped: ["publish"], workflow: "publish.yml", trustId: "trust-1" });
+		expect(second.url).toBe(`https://www.npmjs.com/package/${PKG}`);
+		expect(reg.trust).toEqual([{ type: "github", claims: { repository: "CLDMV/new-thing", workflow_ref: { file: "publish.yml" } }, permissions: ["createPackage"] }]);
+		expect(reg.calls.find((c) => c.url.endsWith("/trust"))!.headers["npm-otp"]).toBe(OTP2);
+		expect(reg.calls.filter((c) => c.method === "PUT")).toHaveLength(1);
+	});
+
+	it("uses restricted access for a private repo", async () => {
+		const reg = fakeRegistry({ otps: [OTP] });
+		const out = await npmScaffold(args(), deps(fakeGitHub({ private: true }), reg));
+		expect(out.access).toBe("restricted");
+		expect(reg.calls.find((c) => c.method === "PUT")!.body.access).toBe("restricted");
+	});
+
+	it("returns needs_otp when the trust code is refused, and finishes with a new one", async () => {
+		const reg = fakeRegistry({ otps: [OTP, OTP2] });
+		await npmScaffold(args(), deps(fakeGitHub(), reg));
+		const refused = await npmScaffold(args({ otp: "999999" }), deps(fakeGitHub(), reg));
+		expect(refused).toMatchObject({ status: "needs_otp", done: [], skipped: ["publish"], remaining: ["trust"] });
+		expect(refused.message).toMatch(/refused the one-time password for the trusted publisher/);
+		const done = await npmScaffold(args({ otp: OTP2 }), deps(fakeGitHub(), reg));
+		expect(done).toMatchObject({ status: "done", done: ["trust"] });
+	});
+
+	it("returns needs_otp with nothing written when the code is refused before publishing", async () => {
+		const reg = fakeRegistry({ otps: [] });
+		const out = await npmScaffold(args(), deps(fakeGitHub(), reg));
+		expect(out).toMatchObject({ status: "needs_otp", done: [], remaining: ["publish", "trust"] });
+		expect(reg.packages.size).toBe(0);
+	});
+
+	const placeholderFor = (repository: string) => ({ name: PKG, versions: placeholderDocument(PKG, { repository, isPrivate: false }, "public", "https://registry.npmjs.org").versions });
+	const trustFor = (repository: string, file = "publish.yml") => ({ id: "t-old", type: "github", claims: { repository, workflow_ref: { file } }, permissions: ["createPackage"] });
+
+	it("treats the same trusted publisher already being configured as done", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, existingTrust: [trustFor("cldmv/NEW-thing")] });
+		const out = await npmScaffold(args(), deps(fakeGitHub(), reg));
+		expect(out).toMatchObject({ status: "done", done: [], skipped: ["publish", "trust"], trustId: "t-old" });
+		// The list was read without sending the code again.
+		expect(reg.calls.find((c) => c.method === "GET" && c.url.endsWith("/trust"))!.headers["npm-otp"]).toBeUndefined();
+	});
+
+	it.each([
+		["another repo", trustFor("CLDMV/other")],
+		["another workflow", trustFor("CLDMV/new-thing", "release.yml")],
+		["another provider", { ...trustFor("CLDMV/new-thing"), type: "gitlab" }]
+	])("refuses when a different trusted publisher exists (%s)", async (_, existing) => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, existingTrust: [existing] });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/already has a different trusted publisher: .*Change it at https:\/\/www\.npmjs\.com\/package\/@cldmv\/new-thing\/access/);
+	});
+
+	it("describes an existing trust entry that has no claims", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, existingTrust: [{ id: "t", type: "github" }] });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/different trusted publisher: github undefined \(undefined\)/);
+	});
+
+	it("finishes without a trust id when npm's reply carries none", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, trustCreatedBody: "[{}]" });
+		const out = await npmScaffold(args(), deps(fakeGitHub(), reg));
+		expect(out).toMatchObject({ status: "done", done: ["trust"] });
+		expect(out).not.toHaveProperty("trustId");
+	});
+
+	it("refuses when npm wants another code to show the existing trusted publisher", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, existingTrust: [trustFor("CLDMV/new-thing")], trustListNeedsOtp: true });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/already has a trusted publisher, and npm needs another one-time password to show which/);
+	});
+
+	it("passes a trust-list failure other than an OTP request through", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, existingTrust: [trustFor("CLDMV/new-thing")], trustListReply: { status: 500, body: "" } });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/trusted publisher lookup failed \(HTTP 500\)/);
+	});
+
+	it("names an unreadable existing configuration rather than failing obscurely", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/new-thing") }, existingTrust: [trustFor("x")], trustListReply: { status: 200, body: "[]" } });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/already has a different trusted publisher: unreadable/);
+	});
+
+	it("refuses to add a trusted publisher for a different repo than the placeholder was made for", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: placeholderFor("CLDMV/other-repo") } });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/placeholder was published for git\+https:\/\/github\.com\/CLDMV\/other-repo\.git, not CLDMV\/new-thing/);
+		expect(reg.calls.some((c) => c.url.endsWith("/trust"))).toBe(false);
+	});
+
+	it("refuses a placeholder with no recorded repository", async () => {
+		const doc = placeholderFor("CLDMV/new-thing");
+		delete (doc.versions[PLACEHOLDER_VERSION] as any).repository;
+		await expect(npmScaffold(args(), deps(fakeGitHub(), fakeRegistry({ existing: { [PKG]: doc } })))).rejects.toThrow(/published for an unrecorded repository/);
+	});
+
+	it("refuses a repo that GitHub redirects to another owner or name", async () => {
+		const gh = fakeGitHub();
+		const real = gh.request.getMockImplementation()!;
+		gh.request.mockImplementation(async (r: string, p: any) => (r === "GET /repos/{owner}/{repo}" ? { data: { full_name: "someone/new-thing", private: false, default_branch: "master" } } : real(r, p)));
+		const reg = fakeRegistry();
+		await expect(npmScaffold(args(), deps(gh, reg))).rejects.toThrow(/cldmv\/new-thing redirects to someone\/new-thing \(renamed or transferred\)/);
+		expect(reg.fetch).not.toHaveBeenCalled();
+	});
+
+	it("refuses a package that already exists and was not created by npm_scaffold", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: { name: PKG, versions: { "1.0.0": {}, "1.1.0": {} } } } });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/already exists on the registry \(2 version\(s\)\) and was not created by npm_scaffold/);
+		expect(reg.calls.every((c) => c.method === "GET")).toBe(true);
+	});
+
+	it("refuses an existing single 0.0.0-stage version that lacks the scaffold marker", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: { name: PKG, versions: { [PLACEHOLDER_VERSION]: { name: PKG } } } } });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/was not created by npm_scaffold/);
+	});
+
+	it("refuses a scope that is not configured, before any request", async () => {
+		const gh = fakeGitHub();
+		const reg = fakeRegistry();
+		await expect(npmScaffold(args({ package: "@other/new-thing" }), deps(gh, reg))).rejects.toThrow(/scope @other is not in config\.npm\.scopes/);
+		expect(gh.request).not.toHaveBeenCalled();
+		expect(reg.fetch).not.toHaveBeenCalled();
+	});
+
+	it.each([
+		[{ missing: true }, /repository cldmv\/new-thing not found/],
+		[{ archived: true }, /is archived/],
+		[{ pkg: null }, /has no package\.json on master/],
+		[{ pkgRaw: "{nope" }, /is not valid JSON/],
+		[{ pkg: { name: "@cldmv/other" } }, /names "@cldmv\/other", not "@cldmv\/new-thing"/],
+		[{ pkg: { name: PKG, private: true } }, /marked "private": true/],
+		[{ workflow: false }, /has no \.github\/workflows\/publish\.yml/]
+	] as Array<[RepoOpts, RegExp]>)("refuses when the repo does not match (%o) without touching npm", async (repo, msg) => {
+		const reg = fakeRegistry();
+		await expect(npmScaffold(args(), deps(fakeGitHub(repo), reg))).rejects.toThrow(msg);
+		expect(reg.fetch).not.toHaveBeenCalled();
+	});
+
+	it("treats a package.json that is not a file as missing", async () => {
+		await expect(npmScaffold(args(), deps(fakeGitHub({ pkgIsDir: true }), fakeRegistry()))).rejects.toThrow(/has no package\.json/);
+	});
+
+	it("reads repo files that are not base64-encoded", async () => {
+		const out = await npmScaffold(args(), deps(fakeGitHub({ plainEncoding: true }), fakeRegistry()));
+		expect(out).toMatchObject({ status: "needs_otp", done: ["publish"] });
+	});
+
+	it("falls back to owner/repo and HEAD when GitHub omits full_name and default_branch, and to no license or description", async () => {
+		const reg = fakeRegistry();
+		const gh = fakeGitHub({ bareRepo: true, pkg: { name: PKG } });
+		const out = await npmScaffold(args(), deps(gh, reg));
+		expect(out.repository).toBe("cldmv/new-thing");
+		const v = reg.calls.find((c) => c.method === "PUT")!.body.versions[PLACEHOLDER_VERSION];
+		expect(v.license).toBe("UNLICENSED");
+		expect(v.readme).not.toContain("undefined");
+	});
+
+	it("refuses an existing package document that lists no versions", async () => {
+		const reg = fakeRegistry({ existing: { [PKG]: { name: PKG } } });
+		await expect(npmScaffold(args(), deps(fakeGitHub(), reg))).rejects.toThrow(/\(0 version\(s\)\) and was not created by npm_scaffold/);
+	});
+
+	it("honours a custom workflow file name", async () => {
+		const reg = fakeRegistry({ otps: [OTP, OTP2] });
+		await npmScaffold(args({ workflow: "release.yaml" }), deps(fakeGitHub(), reg));
+		const out = await npmScaffold(args({ workflow: "release.yaml", otp: OTP2 }), deps(fakeGitHub(), reg));
+		expect(out.workflow).toBe("release.yaml");
+		expect(reg.trust[0].claims.workflow_ref.file).toBe("release.yaml");
+	});
+
+	it.each([
+		[null, /arguments must be an object/],
+		[{ ...args(), extra: 1 }, /unknown argument\(s\): extra/],
+		[{ ...args(), owner: "bad/owner" }, /"owner"/],
+		[{ ...args(), repo: "../x" }, /"repo"/],
+		[{ ...args(), package: "unscoped" }, /"package"/],
+		[{ ...args(), package: "@CLDMV/Upper" }, /"package"/],
+		[{ ...args(), otp: "12ab56" }, /"otp"/],
+		[{ ...args(), otp: 123456 }, /"otp"/],
+		[{ ...args(), workflow: "../publish.yml" }, /"workflow"/],
+		[{ ...args(), workflow: "publish.sh" }, /"workflow"/]
+	] as Array<[unknown, RegExp]>)("validates arguments strictly (%#)", async (input, msg) => {
+		const gh = fakeGitHub();
+		await expect(npmScaffold(input, deps(gh, fakeRegistry()))).rejects.toThrow(msg);
+		expect(gh.request).not.toHaveBeenCalled();
+	});
+
+	it("never puts the OTP or the token in a result or an error", async () => {
+		const ok = await npmScaffold(args(), deps(fakeGitHub(), fakeRegistry({ otps: [OTP] })));
+		const needs = await npmScaffold(args(), deps(fakeGitHub(), fakeRegistry({ otps: [] })));
+		const errors: string[] = [];
+		for (const reg of [fakeRegistry({ publishStatus: 403 }), fakeRegistry({ lookupStatus: 500 })]) {
+			await npmScaffold(args(), deps(fakeGitHub(), reg)).catch((e: Error) => errors.push(e.message));
+		}
+		await npmScaffold({ ...args(), otp: "12345x" }, deps(fakeGitHub(), fakeRegistry())).catch((e: Error) => errors.push(e.message));
+		expect(errors).toHaveLength(3);
+		for (const text of [JSON.stringify(ok), JSON.stringify(needs), ...errors]) {
+			expect(text).not.toContain(OTP);
+			expect(text).not.toContain("12345x");
+			expect(text).not.toContain(TOKEN);
+		}
+	});
+
+	it("passes GitHub errors other than 404 through unchanged", async () => {
+		const boom = Object.assign(new Error("rate limited"), { status: 403 });
+		for (const route of ["GET /repos/{owner}/{repo}", "GET /repos/{owner}/{repo}/contents/{path}"]) {
+			const gh = fakeGitHub();
+			const real = gh.request.getMockImplementation()!;
+			gh.request.mockImplementation(async (r: string, p: any) => {
+				if (r === route) throw boom;
+				return real(r, p);
+			});
+			await expect(npmScaffold(args(), deps(gh, fakeRegistry()))).rejects.toBe(boom);
+		}
+	});
+
+	it("passes a trust failure that is not an OTP refusal through, after the publish", async () => {
+		const reg = fakeRegistry({ otps: [OTP, OTP2], trustStatus: 400 });
+		await npmScaffold(args(), deps(fakeGitHub(), reg));
+		await expect(npmScaffold(args({ otp: OTP2 }), deps(fakeGitHub(), reg))).rejects.toThrow(/trusted publisher setup failed \(HTTP 400\)/);
+		expect(reg.packages.has(PKG)).toBe(true);
+	});
+
+	it("surfaces a registry refusal as an HTTP error with npm's message", async () => {
+		await expect(npmScaffold(args(), deps(fakeGitHub(), fakeRegistry({ publishStatus: 403 })))).rejects.toThrow(/npm: publish failed \(HTTP 403\): You do not have permission to publish/);
+	});
+});
+
+describe("NpmRegistry", () => {
+	const res = (status: number, body: string, headers: Record<string, string> = {}) => ({ status, headers: { get: (n: string) => headers[n] ?? null }, text: async () => body });
+
+	it("detects an OTP refusal from the body when the header does not say so", async () => {
+		const reg = new NpmRegistry({ token: TOKEN, fetch: async () => res(401, "This operation requires a one-time password") });
+		await expect(reg.publish({}, PKG, OTP)).rejects.toBeInstanceOf(NpmOtpRequired);
+	});
+
+	it("treats a plain 401 as an HTTP error, not an OTP request", async () => {
+		const reg = new NpmRegistry({ token: TOKEN, fetch: async () => res(401, '{"error":"bad token"}') });
+		await expect(reg.publish({}, PKG, OTP)).rejects.toBeInstanceOf(NpmHttpError);
+	});
+
+	it("trims a trailing slash from the registry and reports a non-JSON error body", async () => {
+		const seen: string[] = [];
+		const reg = new NpmRegistry({ token: TOKEN, registry: "https://npm.example.test/", fetch: async (url) => (seen.push(url), res(502, "Bad Gateway")) });
+		await expect(reg.packument(PKG)).rejects.toThrow(/package lookup failed \(HTTP 502\): Bad Gateway/);
+		expect(seen).toEqual([`https://npm.example.test/${escapePackageName(PKG)}?write=true`]);
+		expect(reg.registry).toBe("https://npm.example.test");
+	});
+
+	it("reads a trust list that is a single object, and refuses one that is not JSON", async () => {
+		const one = new NpmRegistry({ token: TOKEN, fetch: async () => res(200, '{"id":"t1","type":"github"}') });
+		await expect(one.listTrust(PKG, OTP)).resolves.toEqual([{ id: "t1", type: "github" }]);
+		const bad = new NpmRegistry({ token: TOKEN, fetch: async () => res(200, "<html>") });
+		await expect(bad.listTrust(PKG)).rejects.toThrow(/trusted publisher lookup failed \(HTTP 200\): response is not JSON/);
+	});
+
+	it("accepts a trust response that is not JSON", async () => {
+		const reg = new NpmRegistry({ token: TOKEN, fetch: async () => res(204, "") });
+		await expect(reg.addGithubTrust(PKG, { repository: "CLDMV/x", file: "publish.yml" }, OTP)).resolves.toEqual({ conflict: false });
+	});
+
+	it("reports an HTTP error with an empty body by status alone", async () => {
+		const reg = new NpmRegistry({ token: TOKEN, fetch: async () => res(500, "") });
+		await expect(reg.packument(PKG)).rejects.toThrow(/^npm: package lookup failed \(HTTP 500\)$/);
+	});
+
+	it("takes the trust config from an object response, and none from an empty or non-object one", async () => {
+		const claims = { repository: "CLDMV/x", file: "publish.yml" };
+		const one = new NpmRegistry({ token: TOKEN, fetch: async () => res(201, '{"id":"t-9","type":"github"}') });
+		await expect(one.addGithubTrust(PKG, claims, OTP)).resolves.toEqual({ config: { id: "t-9", type: "github" }, conflict: false });
+		for (const body of ["[]", '"ok"']) {
+			const reg = new NpmRegistry({ token: TOKEN, fetch: async () => res(201, body) });
+			await expect(reg.addGithubTrust(PKG, claims, OTP)).resolves.toEqual({ config: undefined, conflict: false });
+		}
+	});
+
+	it("fails a trust setup the registry rejects", async () => {
+		const reg = new NpmRegistry({ token: TOKEN, fetch: async () => res(400, '{"message":"workflow not found"}') });
+		await expect(reg.addGithubTrust(PKG, { repository: "CLDMV/x", file: "publish.yml" }, OTP)).rejects.toThrow(/trusted publisher setup failed \(HTTP 400\): workflow not found/);
+	});
+});