@cldmv/gh-broker 0.7.0 → 0.8.0

package/tests/config-merge.test.vitest.mts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { mergeConfig } from "../deploy/lib/config-merge.mjs";
+import { mergeConfig, layerConfig, overlayFromFlags, readOperatorConfig, buildConfig, secretsBlock, DEFAULT_GHCR_DROP_DIR } from "../deploy/lib/config-merge.mjs";
 
 const example = {
 	listen: "unix:/run/gh-broker/gh-broker.sock",
@@ -8,8 +8,8 @@ const example = {
 		{ name: "get_me", mode: "read" },
 		{ name: "list_issues", mode: "read" }
 	],
-	owners: { cldmv: { read: "cred:cldmv-read", write: "cred:cldmv-write" } },
-	defaultOwner: "cldmv"
+	owners: { acme: { read: "cred:acme-read", write: "cred:acme-write" } },
+	defaultOwner: "acme"
 };
 
 describe("mergeConfig", () => {
@@ -25,17 +25,17 @@ describe("mergeConfig", () => {
 	});
 
 	it("preserves current owner data and adds example-only owners on upgrade", () => {
-		const current = { ...example, owners: { cldmv: { read: "cred:cldmv-read", write: "cred:cldmv-write", installationId: 123 } } };
+		const current = { ...example, owners: { acme: { read: "cred:acme-read", write: "cred:acme-write", installationId: 123 } } };
 		const example2 = {
 			...example,
 			owners: {
-				cldmv: { read: "cred:cldmv-read", write: "cred:cldmv-write" },
-				acme: { read: "cred:acme-read", write: "cred:acme-write" }
+				acme: { read: "cred:acme-read", write: "cred:acme-write" },
+				beta: { read: "cred:beta-read", write: "cred:beta-write" }
 			}
 		};
 		const merged = mergeConfig(example2, current);
-		expect(merged.owners.cldmv.installationId).toBe(123); // current wins
-		expect(merged.owners.acme).toBeDefined(); // new example owner appears
+		expect(merged.owners.acme.installationId).toBe(123); // current wins
+		expect(merged.owners.beta).toBeDefined(); // new example owner appears
 	});
 
 	it("lets current win for listen/upstream/defaultOwner/app/secrets", () => {
@@ -45,6 +45,18 @@ describe("mergeConfig", () => {
 		expect(merged.app).toEqual({ appId: 1, privateKey: "cred:k" });
 	});
 
+	it("keeps the current npm block on upgrade (the example has none)", () => {
+		const npm = { token: "cred:npm-token", scopes: ["@cldmv"] };
+		expect(mergeConfig(example, { ...example, npm }).npm).toEqual(npm);
+		expect(mergeConfig(example, { ...example }).npm).toBeUndefined();
+	});
+
+	it("keeps the example's scalars when current omits them, and tolerates configs with no owners", () => {
+		const merged = mergeConfig({ tools: [], listen: "unix:/a" }, { tools: [] });
+		expect(merged.listen).toBe("unix:/a");
+		expect(merged.owners).toEqual({});
+	});
+
 	it("does not mutate its inputs", () => {
 		const ex = structuredClone(example);
 		mergeConfig(ex, { ...example, listen: "unix:/z" });
@@ -55,4 +67,259 @@ describe("mergeConfig", () => {
 		expect(() => mergeConfig([], null)).toThrow(/example config must be an object/);
 		expect(() => mergeConfig(example, [])).toThrow(/current config must be an object/);
 	});
+
+	describe("ghcr", () => {
+		const ghcr = { dropDir: "/srv/gh-broker/ghcr-drop", owners: { cldmv: { username: "u", credential: "cred:p", images: ["hoot"] } } };
+
+		it("keeps the deployed ghcr block (operator data); the example ships none", () => {
+			expect(mergeConfig(example, { ...example, ghcr }).ghcr).toEqual(ghcr);
+			expect(mergeConfig(example, { ...example }).ghcr).toBeUndefined();
+		});
+
+		it("lets the deployed ghcr win over one the example carries", () => {
+			const edited = { ...ghcr, dropDir: "/srv/other/drop" };
+			expect(mergeConfig({ ...example, ghcr }, { ...example, ghcr: edited }).ghcr).toEqual(edited);
+			expect(mergeConfig({ ...example, ghcr }, example).ghcr).toEqual(ghcr);
+		});
+	});
+});
+
+const shipped = {
+	listen: "unix:/run/gh-broker/gh-broker.sock",
+	upstream: "https://api.githubcopilot.com/mcp/x/all",
+	tools: [{ name: "get_me", mode: "read" }]
+};
+const noOpts = {};
+const ask = async () => {
+	throw new Error("unexpected prompt");
+};
+
+describe("layerConfig", () => {
+	it("replaces scalars and merges owners per owner and per field", () => {
+		const base = { listen: "unix:/a", upstream: "https://a", owners: { acme: { read: "cred:acme-read", write: "cred:acme-write", installationId: 7 } } };
+		const out = layerConfig(base, { listen: "unix:/b", defaultOwner: "acme", owners: { acme: { write: "cred:w2" }, beta: { read: "cred:r", write: "cred:w" } } });
+		expect(out.listen).toBe("unix:/b");
+		expect(out.upstream).toBe("https://a");
+		expect(out.defaultOwner).toBe("acme");
+		expect(out.owners.acme).toEqual({ read: "cred:acme-read", write: "cred:w2", installationId: 7 });
+		expect(out.owners.beta).toEqual({ read: "cred:r", write: "cred:w" });
+		expect(base.owners.acme.write).toBe("cred:acme-write"); // input untouched
+	});
+
+	it("merges app/secrets/npm per field and creates them when absent", () => {
+		const out = layerConfig({ npm: { token: "cred:t", scopes: ["@a"] } }, { npm: { registry: "https://r" }, secrets: { path: "/p" }, app: { appId: 1, privateKey: "cred:k" } });
+		expect(out.npm).toEqual({ token: "cred:t", scopes: ["@a"], registry: "https://r" });
+		expect(out.secrets).toEqual({ path: "/p" });
+		expect(out.app).toEqual({ appId: 1, privateKey: "cred:k" });
+	});
+
+	it("merges ghcr scalars and ghcr owners per owner", () => {
+		const base = { owners: {}, ghcr: { dropDir: "/srv/a/b", owners: { acme: { username: "u", credential: "cred:acme-packages", images: ["x"] } } } };
+		const out = layerConfig(base, { ghcr: { protectReleaseTags: false, owners: { acme: { images: ["y"] }, beta: { username: "b", credential: "cred:beta-packages", images: ["z"] } } } });
+		expect(out.ghcr.dropDir).toBe("/srv/a/b");
+		expect(out.ghcr.protectReleaseTags).toBe(false);
+		expect(out.ghcr.owners.acme).toEqual({ username: "u", credential: "cred:acme-packages", images: ["y"] });
+		expect(Object.keys(out.ghcr.owners)).toEqual(["acme", "beta"]);
+		expect(layerConfig({}, { ghcr: { dropDir: "/srv/a/b" } }).ghcr).toEqual({ dropDir: "/srv/a/b" });
+	});
+
+	it("leaves a base without overlay data alone", () => {
+		expect(layerConfig({ listen: "unix:/a" }, {})).toEqual({ listen: "unix:/a" });
+	});
+});
+
+describe("overlayFromFlags", () => {
+	it("is empty with no flags", () => {
+		expect(overlayFromFlags(noOpts)).toEqual({});
+	});
+
+	it("maps every flag to its config field", () => {
+		const o = overlayFromFlags({
+			listen: "unix:/x.sock",
+			upstream: "https://u",
+			defaultOwner: "acme",
+			owners: ["acme", "beta"],
+			installationIds: { acme: 42, gamma: 9 },
+			appId: 5,
+			appPrivateKey: "my-key",
+			secretsPath: "/s.json",
+			ghcrOwner: "acme",
+			ghcrUsername: "me",
+			ghcrImages: ["app", "app-*"],
+			ghcrDropDir: "/srv/x/drop",
+			ghcrMaxArchiveBytes: 1024,
+			protectReleaseTags: false
+		});
+		expect(o).toEqual({
+			listen: "unix:/x.sock",
+			upstream: "https://u",
+			defaultOwner: "acme",
+			owners: {
+				acme: { read: "cred:acme-read", write: "cred:acme-write", installationId: 42 },
+				beta: { read: "cred:beta-read", write: "cred:beta-write" },
+				gamma: { installationId: 9 }
+			},
+			app: { appId: 5, privateKey: "cred:my-key" },
+			secrets: { path: "/s.json" },
+			ghcr: {
+				dropDir: "/srv/x/drop",
+				maxArchiveBytes: 1024,
+				protectReleaseTags: false,
+				owners: { acme: { username: "me", credential: "cred:acme-packages", images: ["app", "app-*"] } }
+			}
+		});
+	});
+
+	it("derives the App key name when only --app-id is given and handles --protect-release-tags", () => {
+		expect(overlayFromFlags({ appId: 5 }).app).toEqual({ appId: 5, privateKey: "cred:gh-app-key" });
+		expect(overlayFromFlags({ protectReleaseTags: true }).ghcr).toEqual({ protectReleaseTags: true });
+	});
+});
+
+describe("readOperatorConfig", () => {
+	const read = (text: string) => () => text;
+
+	it("returns a valid operator config", () => {
+		const cfg = { listen: "unix:/a", owners: { acme: { read: "cred:acme-read", write: "cred:acme-write" } } };
+		expect(readOperatorConfig("/c.json", read(JSON.stringify(cfg)))).toEqual(cfg);
+	});
+
+	it("reports an unreadable file and bad JSON", () => {
+		expect(() =>
+			readOperatorConfig("/missing.json", () => {
+				throw new Error("ENOENT: no such file");
+			})
+		).toThrow(/--config: cannot read\/parse \/missing.json: ENOENT/);
+		expect(() => readOperatorConfig("/c.json", read("{ nope"))).toThrow(/--config: cannot read\/parse/);
+	});
+
+	it("refuses a non-object root, tools, and unknown keys", () => {
+		expect(() => readOperatorConfig("/c.json", read("[]"))).toThrow(/must be a JSON object/);
+		expect(() => readOperatorConfig("/c.json", read("null"))).toThrow(/must be a JSON object/);
+		expect(() => readOperatorConfig("/c.json", read('{"tools":[]}'))).toThrow(/`tools` is the shipped allowlist/);
+		expect(() => readOperatorConfig("/c.json", read('{"lisen":"x","owners":{}}'))).toThrow(/unknown key\(s\) lisen/);
+	});
+
+	it.each([
+		["a classic PAT", { owners: { acme: { read: "ghp_" + "a".repeat(36), write: "cred:w" } } }, "owners.acme.read"],
+		["a fine-grained PAT", { ghcr: { owners: { a: { images: ["github_pat_" + "A1".repeat(20)] } } } }, "ghcr.owners.a.images[0]"],
+		["an npm token", { npm: { token: "npm_" + "b".repeat(36), scopes: [] } }, "npm.token"],
+		["a token as a list entry", { npm: { scopes: ["ok", "ghs_" + "c".repeat(30)] } }, "npm.scopes[1]"]
+	])("refuses %s", (_name, cfg, where) => {
+		expect(() => readOperatorConfig("/c.json", read(JSON.stringify(cfg)))).toThrow(new RegExp(`--config: ${where.replace(/[[\]]/g, "\\$&")} looks like a token`));
+	});
+
+	it("accepts cred refs, numbers and booleans alongside strings", () => {
+		const cfg = { app: { appId: 1, privateKey: "cred:gh-app-key" }, ghcr: { protectReleaseTags: true } };
+		expect(readOperatorConfig("/c.json", read(JSON.stringify(cfg)))).toEqual(cfg);
+	});
+});
+
+describe("buildConfig", () => {
+	const acme = { read: "cred:acme-read", write: "cred:acme-write" };
+	const build = (o: Record<string, unknown>) => buildConfig({ example: shipped, current: null, file: undefined, opts: noOpts, nonInteractive: true, ask, ...o } as never);
+
+	it("a first install takes owners from flags, defaults defaultOwner and sets ghcr.dropDir", async () => {
+		const { config, notes } = await build({
+			opts: { owners: ["acme"], ghcrOwner: "acme", ghcrUsername: "me", ghcrImages: ["app"] }
+		});
+		expect(config.tools).toEqual(shipped.tools);
+		expect(config.owners).toEqual({ acme });
+		expect(config.defaultOwner).toBe("acme");
+		expect(config.ghcr).toEqual({ dropDir: DEFAULT_GHCR_DROP_DIR, owners: { acme: { username: "me", credential: "cred:acme-packages", images: ["app"] } } });
+		expect(notes).toHaveLength(2);
+	});
+
+	it("does not pick a defaultOwner with several owners, or when one is set", async () => {
+		expect((await build({ opts: { owners: ["acme", "beta"] } })).config.defaultOwner).toBeUndefined();
+		expect((await build({ opts: { owners: ["acme", "beta"], defaultOwner: "beta" } })).config.defaultOwner).toBe("beta");
+	});
+
+	it("layers example < deployed < --config < flags", async () => {
+		const current = { ...shipped, listen: "unix:/deployed", upstream: "https://deployed", owners: { acme }, defaultOwner: "acme" };
+		const file = { listen: "unix:/file", upstream: "https://file" };
+		const flags = { listen: "unix:/flag" };
+		const { config } = await build({ current, file, opts: flags });
+		expect(config.listen).toBe("unix:/flag"); // flag beats file
+		expect(config.upstream).toBe("https://file"); // file beats deployed
+		const deployedOnly = await build({ current });
+		expect(deployedOnly.config.listen).toBe("unix:/deployed"); // deployed beats example
+		expect(deployedOnly.config.upstream).toBe("https://deployed");
+		expect((await build({ current: { tools: [], owners: { acme } } })).config.listen).toBe(shipped.listen); // example fills gaps
+	});
+
+	it("keeps the deployed owners, ghcr and tools on an upgrade with no flags", async () => {
+		const ghcr = { dropDir: "/srv/old/drop", protectReleaseTags: false, maxArchiveBytes: 5, owners: { acme: { username: "me", credential: "cred:acme-packages", images: ["x"] } } };
+		const current = { ...shipped, tools: [{ name: "gone", mode: "write" }], owners: { acme: { ...acme, installationId: 3 } }, ghcr };
+		const { config, notes } = await build({ current });
+		expect(config.owners).toEqual({ acme: { ...acme, installationId: 3 } });
+		expect(config.ghcr).toEqual(ghcr);
+		expect(config.tools).toEqual(shipped.tools); // allowlist from the example
+		expect(config.defaultOwner).toBeUndefined();
+		expect(notes).toEqual([]);
+	});
+
+	it("adds an owner on top of a deployed one without losing it", async () => {
+		const { config } = await build({ current: { ...shipped, owners: { acme: { ...acme, installationId: 3 } } }, opts: { owners: ["acme", "beta"] } });
+		expect(config.owners.acme.installationId).toBe(3);
+		expect(config.owners.beta).toEqual({ read: "cred:beta-read", write: "cred:beta-write" });
+	});
+
+	it("takes owners, ghcr and defaultOwner from a --config file", async () => {
+		const file = { owners: { acme }, defaultOwner: "acme", ghcr: { dropDir: "/srv/f/drop", owners: { acme: { username: "me", credential: "cred:acme-packages", images: ["a"] } } } };
+		const { config } = await build({ file });
+		expect(config.owners).toEqual({ acme });
+		expect(config.ghcr.dropDir).toBe("/srv/f/drop");
+	});
+
+	it("fails non-interactively when no owner exists anywhere, naming --owner and --config", async () => {
+		await expect(build({})).rejects.toThrow(/--owner <org>.*--config/);
+		await expect(build({ current: { ...shipped } })).rejects.toThrow(/no GitHub owner configured/);
+	});
+
+	it("asks for the owner on an interactive first install", async () => {
+		const asked: string[] = [];
+		const { config } = await build({
+			nonInteractive: false,
+			ask: async (q: string) => {
+				asked.push(q);
+				return "  Acme-Corp \n";
+			}
+		});
+		expect(asked).toHaveLength(1);
+		expect(config.owners).toEqual({ "acme-corp": { read: "cred:acme-corp-read", write: "cred:acme-corp-write" } });
+		expect(config.defaultOwner).toBe("acme-corp");
+	});
+
+	it("rejects an invalid owner typed at the prompt", async () => {
+		await expect(build({ nonInteractive: false, ask: async () => "not an org!" })).rejects.toThrow(/not a valid GitHub owner name/);
+		await expect(build({ nonInteractive: false, ask: async () => "" })).rejects.toThrow(/not a valid GitHub owner name/);
+	});
+
+	it("does not prompt when owners are already configured", async () => {
+		const { config } = await build({ nonInteractive: false, current: { ...shipped, owners: { acme } } });
+		expect(Object.keys(config.owners)).toEqual(["acme"]);
+	});
+
+	it("refuses an owner that has no credentials (e.g. --installation-id for an unknown owner)", async () => {
+		await expect(build({ opts: { owners: ["acme"], installationIds: { gamma: 9 } } })).rejects.toThrow(/owner "gamma" has no credentials.*--owner gamma/);
+	});
+
+	it("keeps an explicit ghcr.dropDir instead of the default", async () => {
+		const { config, notes } = await build({ opts: { owners: ["acme"], ghcrOwner: "acme", ghcrUsername: "me", ghcrImages: ["a"], ghcrDropDir: "/srv/mine/drop" } });
+		expect(config.ghcr.dropDir).toBe("/srv/mine/drop");
+		expect(notes.some((n: string) => n.includes("dropDir"))).toBe(false);
+	});
+});
+
+describe("secretsBlock", () => {
+	it("returns just the provider, keeping a path only for the file provider", () => {
+		expect(secretsBlock("systemd-creds", undefined)).toEqual({ provider: "systemd-creds" });
+		expect(secretsBlock("file", { path: "/s.json" })).toEqual({ provider: "file", path: "/s.json" });
+		expect(secretsBlock("file", {})).toEqual({ provider: "file" });
+	});
+
+	it("refuses a path with the systemd-creds provider", () => {
+		expect(() => secretsBlock("systemd-creds", { path: "/s.json" })).toThrow(/only used by the "file" provider/);
+	});
 });

package/tests/config.test.vitest.mts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from "vitest";
-import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdirSync, writeFileSync, rmSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, indexTools } from "../src/config.ts";
 
@@ -263,6 +263,16 @@ describe("loadConfig — secrets", () => {
 		expect(out.secrets).toEqual({ provider: "file", path: "/etc/gh-broker/secrets.json" });
 	});
 
+	it("carries an empty secrets block, and a provider without a path, through", () => {
+		const c = baseConfig();
+		c.secrets = {};
+		expect(loadConfig(writeConfig(c)).secrets).toEqual({});
+		c.secrets = { provider: "file" };
+		expect(loadConfig(writeConfig(c)).secrets).toEqual({ provider: "file" });
+		c.secrets = { provider: "systemd-creds" };
+		expect(loadConfig(writeConfig(c)).secrets).toEqual({ provider: "systemd-creds" });
+	});
+
 	it("rejects a path without the file provider (omitted → systemd-creds default)", () => {
 		const c = baseConfig();
 		c.secrets = { path: "/etc/gh-broker/secrets.json" };
@@ -312,3 +322,67 @@ describe("indexTools", () => {
 		expect(map.get("missing")).toBeUndefined();
 	});
 });
+
+describe("loadConfig — npm", () => {
+	it("is absent unless configured", () => {
+		expect(loadConfig(writeConfig(baseConfig())).npm).toBeUndefined();
+	});
+
+	it("leaves registry out when it is not set", () => {
+		expect(loadConfig(writeConfig({ ...baseConfig(), npm: { token: "cred:npm-token", scopes: ["@cldmv"] } })).npm).toEqual({ token: "cred:npm-token", scopes: ["@cldmv"] });
+	});
+
+	it("accepts a token ref, scopes, an https registry and token orgs", () => {
+		const npm = { token: "cred:npm-token", scopes: ["@cldmv"], registry: "https://registry.npmjs.org", tokenOrgs: ["cldmv"] };
+		expect(loadConfig(writeConfig({ ...baseConfig(), npm })).npm).toEqual(npm);
+	});
+
+	it.each([
+		[[], /config.npm: must be an object/],
+		[{ scopes: ["@cldmv"] }, /config.npm.token/],
+		[{ token: "npm_inline_secret", scopes: ["@cldmv"] }, /config.npm.token/],
+		[{ token: "cred:npm-token" }, /config.npm.scopes: must be a non-empty array/],
+		[{ token: "cred:npm-token", scopes: [] }, /config.npm.scopes: must be a non-empty array/],
+		[{ token: "cred:npm-token", scopes: ["cldmv"] }, /config.npm.scopes\[0\]/],
+		[{ token: "cred:npm-token", scopes: ["@CLDMV"] }, /config.npm.scopes\[0\]/],
+		[{ token: "cred:npm-token", scopes: ["@cldmv"], registry: "http://registry.npmjs.org" }, /config.npm.registry: must be an https URL/],
+		[{ token: "cred:npm-token", scopes: ["@cldmv"], tokenOrgs: "cldmv" }, /config.npm.tokenOrgs/],
+		[{ token: "cred:npm-token", scopes: ["@cldmv"], tokenOrgs: ["@cldmv"] }, /config.npm.tokenOrgs/]
+	] as Array<[unknown, RegExp]>)("rejects an invalid npm block (%#)", (npm, msg) => {
+		expect(() => loadConfig(writeConfig({ ...baseConfig(), npm }))).toThrow(msg);
+	});
+});
+
+describe("loadConfig — ghcr", () => {
+	const ghcr = { dropDir: "/srv/gh-broker/ghcr-drop", owners: { cldmv: { username: "Shinrai", credential: "cred:cldmv-packages", images: ["hoot"] } } };
+
+	it("parses a ghcr block", () => {
+		const c = loadConfig(writeConfig({ ...baseConfig(), ghcr }));
+		expect(c.ghcr?.owners.cldmv?.credential).toBe("cred:cldmv-packages");
+		expect(c.ghcr?.protectReleaseTags).toBe(true);
+	});
+
+	it("omits ghcr when absent and rejects a malformed block", () => {
+		expect(loadConfig(writeConfig(baseConfig())).ghcr).toBeUndefined();
+		expect(() => loadConfig(writeConfig({ ...baseConfig(), ghcr: { ...ghcr, dropDir: "/etc/x/y" } }))).toThrow(/config.ghcr.dropDir: may not be under \/etc/);
+	});
+
+	it("ships no owner-specific data in config.example.json, and it loads once an owner is added", () => {
+		const raw = JSON.parse(readFileSync(join(process.cwd(), "config.example.json"), "utf8"));
+		expect(Object.keys(raw).sort()).toEqual(["listen", "tools", "upstream"]);
+		const c = loadConfig(writeConfig({ ...raw, owners: { acme: { read: "cred:acme-read", write: "cred:acme-write" } } }));
+		expect(c.tools.filter((t) => t.name.startsWith("ghcr_")).map((t) => [t.name, t.mode, t.custom])).toEqual([
+			["ghcr_push", "write", true],
+			["ghcr_push_status", "read", true],
+			["ghcr_tags", "read", true]
+		]);
+	});
+
+	it("accepts the documentation-only config.sample.json merged onto the example tools", () => {
+		const raw = JSON.parse(readFileSync(join(process.cwd(), "config.example.json"), "utf8"));
+		const sample = JSON.parse(readFileSync(join(process.cwd(), "config.sample.json"), "utf8"));
+		const c = loadConfig(writeConfig({ ...sample, tools: raw.tools }));
+		expect(c.ghcr?.dropDir).toBe("/srv/gh-broker/ghcr-drop");
+		expect(c.defaultOwner).toBe("your-org");
+	});
+});

package/tests/credentials.test.vitest.mts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi } from "vitest";
+import { credentialPlan } from "../deploy/lib/credentials.mjs";
+
+type Opts = Parameters<typeof credentialPlan>[0];
+
+function plan(over: Partial<Opts> = {}, answers: string[] = []) {
+	const logs: string[] = [];
+	const promptHidden = vi.fn(async () => answers.shift() ?? "");
+	const mint = vi.fn(async () => "npm_MINTED");
+	const p = credentialPlan({
+		needed: ["cldmv-read", "cldmv-write", "npm-token"],
+		optional: new Set(["npm-token"]),
+		cliSecrets: {},
+		imported: {},
+		env: {},
+		existingFile: {},
+		decrypt: () => undefined,
+		mints: () => false,
+		mint,
+		appKeyName: undefined,
+		nonInteractive: false,
+		promptHidden,
+		log: (m: string) => logs.push(m),
+		...over
+	});
+	return { p, logs, promptHidden, mint };
+}
+
+/** A fake systemd-creds store: which .cred files exist, and what was encrypted. */
+function creds(existing: string[] = []) {
+	const files = new Set(existing);
+	const written: Record<string, string> = {};
+	return {
+		written,
+		io: {
+			exists: (n: string) => files.has(n),
+			encrypt: (n: string, v: string) => {
+				files.add(n);
+				written[n] = v;
+			}
+		}
+	};
+}
+
+describe("credentialPlan", () => {
+	it("refuses a --secret name the config does not use", () => {
+		expect(() => plan({ cliSecrets: { "cldmv-raed": "x" } })).toThrow(/--secret names no credential this config uses: cldmv-raed \(it uses: cldmv-read, cldmv-write, npm-token\)/);
+	});
+
+	it("takes an explicit value from --secret, then --secrets-file, then env", () => {
+		const env = { GH_BROKER_SECRET_CLDMV_READ: "from-env" };
+		expect(plan({ env }).p.explicit("cldmv-read")).toBe("from-env");
+		expect(plan({ env, imported: { "cldmv-read": "from-file" } }).p.explicit("cldmv-read")).toBe("from-file");
+		expect(plan({ env, imported: { "cldmv-read": "from-file" }, cliSecrets: { "cldmv-read": "from-cli" } }).p.explicit("cldmv-read")).toBe("from-cli");
+		expect(plan({ imported: { "cldmv-read": "" }, env: { GH_BROKER_SECRET_CLDMV_READ: "" } }).p.explicit("cldmv-read")).toBeUndefined();
+	});
+
+	it("resolves explicit → stored file → decrypt → prompt", async () => {
+		expect(await plan({ cliSecrets: { "cldmv-read": "cli" }, existingFile: { "cldmv-read": "old" } }).p.resolve("cldmv-read")).toBe("cli");
+		expect(await plan({ existingFile: { "cldmv-read": "old" }, decrypt: () => "dec" }).p.resolve("cldmv-read")).toBe("old");
+		const d = plan({ decrypt: () => "dec" });
+		expect(await d.p.resolve("cldmv-read")).toBe("dec");
+		expect(d.logs).toContain("  cldmv-read: migrated from systemd-creds");
+		const prompted = plan({}, ["typed"]);
+		expect(await prompted.p.resolve("cldmv-read")).toBe("typed");
+		expect(prompted.promptHidden).toHaveBeenCalledWith("  cldmv-read (input hidden): ");
+	});
+
+	it("fails a required credential that is missing or left empty", async () => {
+		await expect(plan({ nonInteractive: true }).p.resolve("cldmv-read")).rejects.toThrow(/missing credential "cldmv-read" — provide via --secret, --secrets-file or env GH_BROKER_SECRET_CLDMV_READ/);
+		await expect(plan({}, [""]).p.resolve("cldmv-read")).rejects.toThrow(/empty value for "cldmv-read"/);
+		await expect(plan({ appKeyName: "gh-app-key", needed: ["gh-app-key"] }).p.resolve("gh-app-key")).rejects.toThrow(/GitHub App private key/);
+	});
+
+	it("lets an optional credential be skipped, never failing", async () => {
+		expect(await plan({ nonInteractive: true }).p.resolve("npm-token")).toBeUndefined();
+		const i = plan({}, [""]);
+		expect(await i.p.resolve("npm-token")).toBeUndefined();
+		expect(i.promptHidden).toHaveBeenCalledWith(expect.stringMatching(/Enter to skip/));
+		expect(await plan({}, ["npm_typed"]).p.resolve("npm-token")).toBe("npm_typed");
+	});
+
+	it("creates the npm token when this run mints it, unless one is supplied", async () => {
+		const m = plan({ mints: (n) => n === "npm-token" });
+		expect(await m.p.resolve("npm-token")).toBe("npm_MINTED");
+		expect(m.p.replaces("npm-token")).toBe(true);
+		const given = plan({ mints: (n) => n === "npm-token", cliSecrets: { "npm-token": "npm_given" } });
+		expect(await given.p.resolve("npm-token")).toBe("npm_given");
+		expect(given.mint).not.toHaveBeenCalled();
+		await expect(plan({ mints: () => true, nonInteractive: true }).p.resolve("npm-token")).rejects.toThrow(/needs a browser login/);
+	});
+
+	describe("storeSystemd", () => {
+		it("keeps existing creds, encrypts new ones, and lists only what is stored", async () => {
+			const c = creds(["cldmv-read"]);
+			const { p, logs } = plan({}, ["write-typed", ""]);
+			const stored = await p.storeSystemd(c.io);
+			expect(stored).toEqual(["cldmv-read", "cldmv-write"]);
+			expect(c.written).toEqual({ "cldmv-write": "write-typed" });
+			expect(logs).toEqual(["  cldmv-read: existing systemd-creds kept", "  cldmv-write: encrypted (systemd-creds)", "  npm-token: not stored — its tools stay hidden until it is (re-run the installer to add it)"]);
+		});
+
+		it("rotates on an explicit value or a plaintext entry, and notes a replaced npm token", async () => {
+			const c = creds(["cldmv-read", "cldmv-write", "npm-token"]);
+			const { p, logs } = plan({ cliSecrets: { "cldmv-read": "new-read" }, existingFile: { "cldmv-write": "file-write" }, mints: (n) => n === "npm-token" });
+			expect(await p.storeSystemd(c.io)).toEqual(["cldmv-read", "cldmv-write", "npm-token"]);
+			expect(c.written).toEqual({ "cldmv-read": "new-read", "cldmv-write": "file-write", "npm-token": "npm_MINTED" });
+			expect(logs).toContain("  cldmv-read: rotated (systemd-creds)");
+			expect(logs.some((l) => /previous npm-token is still valid/.test(l))).toBe(true);
+			expect(logs.filter((l) => /previous/.test(l))).toHaveLength(1);
+		});
+	});
+
+	describe("storeFile", () => {
+		it("keeps stored values, fills missing ones, rotates on an explicit value, and skips an optional one", async () => {
+			const { p, logs } = plan({ needed: ["cldmv-read", "cldmv-write", "cldmv-new", "npm-token"], existingFile: { "cldmv-read": "old-read", "cldmv-write": "old-write" }, cliSecrets: { "cldmv-write": "new-write", "cldmv-new": "fresh" }, nonInteractive: true });
+			expect(await p.storeFile()).toEqual({ "cldmv-read": "old-read", "cldmv-write": "new-write", "cldmv-new": "fresh" });
+			expect(logs).toEqual(["  npm-token: not stored — its tools stay hidden until it is (re-run the installer to add it)"]);
+		});
+
+		it("replaces a stored npm token with a newly created one and says the old one is still live", async () => {
+			const { p, logs } = plan({ existingFile: { "cldmv-read": "r", "cldmv-write": "w", "npm-token": "npm_old" }, mints: (n) => n === "npm-token" });
+			expect(await p.storeFile()).toEqual({ "cldmv-read": "r", "cldmv-write": "w", "npm-token": "npm_MINTED" });
+			expect(logs.some((l) => /previous npm-token is still valid/.test(l))).toBe(true);
+		});
+	});
+});