@agentplate/cli 1.0.0

package/src/deploy/context.test.ts

@@ -0,0 +1,243 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AGENTPLATE_DIR, DEFAULT_CONFIG } from "../config.ts";
+import { SECRETS_FILE } from "../secrets.ts";
+import type { AgentplateConfig, DeployConfig } from "../types.ts";
+import { buildDeployContext } from "./context.ts";
+import type {
+	AppProfile,
+	DeployContext,
+	DeployResult,
+	DeploySecretStore,
+	DeployTarget,
+	DetectResult,
+	GeneratedConfig,
+	VerifyResult,
+} from "./types.ts";
+
+// A minimal, neutral app profile — context never inspects its contents, it just
+// carries it through, so the exact shape only needs to satisfy the type.
+function profile(): AppProfile {
+	return {
+		language: "bun",
+		framework: null,
+		kind: "service",
+		buildCommand: null,
+		startCommand: "bun start",
+		port: 3000,
+		packageManager: "bun.lock",
+		runtimeEnvKeys: [],
+	};
+}
+
+// Test-local DeployTarget implementing the interface directly (the canonical
+// Agentplate test style — no module mocks). `buildSecretEnv` is parameterized so a
+// single fake can model both "needs a secret" and "needs none". Every other
+// method is a stub that throws if ever called: buildDeployContext must touch
+// only `id` and `buildSecretEnv`.
+function fakeTarget(
+	id: string,
+	build: (store: DeploySecretStore) => Record<string, string>,
+): DeployTarget {
+	const unreached = (m: string) => (): never => {
+		throw new Error(`fakeTarget.${m} should not be called by buildDeployContext`);
+	};
+	return {
+		id,
+		stability: "stable",
+		label: "Fake",
+		description: "test target",
+		caps: {
+			canRollback: true,
+			irreversible: false,
+			environments: ["staging"],
+			requiresCredentials: false,
+		},
+		detect: unreached("detect") as () => Promise<DetectResult>,
+		generateConfig: unreached("generateConfig") as () => Promise<GeneratedConfig>,
+		deploy: unreached("deploy") as () => Promise<DeployResult>,
+		verify: unreached("verify") as () => Promise<VerifyResult>,
+		rollback: unreached("rollback") as () => Promise<DeployResult>,
+		buildSecretEnv: build,
+	};
+}
+
+// Clone DEFAULT_CONFIG and layer in deploy settings for one target id.
+function configWith(root: string, deploy: Partial<DeployConfig>): AgentplateConfig {
+	const base: AgentplateConfig = structuredClone(DEFAULT_CONFIG);
+	base.project.root = root;
+	base.deploy = { ...base.deploy, ...deploy };
+	return base;
+}
+
+describe("buildDeployContext", () => {
+	let root: string;
+
+	beforeEach(async () => {
+		root = await mkdtemp(join(tmpdir(), "agentplate-ctx-"));
+		// Ensure .agentplate exists so the secret store can read the file there.
+		await mkdir(join(root, AGENTPLATE_DIR), { recursive: true });
+	});
+
+	afterEach(async () => {
+		await rm(root, { recursive: true, force: true });
+	});
+
+	function baseArgs(
+		target: DeployTarget,
+		config: AgentplateConfig,
+	): Parameters<typeof buildDeployContext>[0] {
+		return {
+			root,
+			worktreePath: join(root, "wt"),
+			target,
+			environment: "staging",
+			profile: profile(),
+			dryRun: false,
+			runId: "run-123",
+			agentName: "deployer-1",
+			config,
+		};
+	}
+
+	test("populates settings, environment, dryRun, and identity fields", () => {
+		const target = fakeTarget("docker-gha", () => ({}));
+		const config = configWith(root, {
+			default: "docker-gha",
+			targets: {
+				"docker-gha": {
+					settings: { region: "us-east-1", replicas: 2, public: true },
+					secretEnv: {},
+					environments: ["staging", "production"],
+				},
+			},
+		});
+
+		const ctx: DeployContext = buildDeployContext({
+			...baseArgs(target, config),
+			environment: "production",
+			dryRun: true,
+		});
+
+		expect(ctx.target).toBe("docker-gha");
+		expect(ctx.environment).toBe("production");
+		expect(ctx.dryRun).toBe(true);
+		expect(ctx.projectRoot).toBe(root);
+		expect(ctx.worktreePath).toBe(join(root, "wt"));
+		expect(ctx.runId).toBe("run-123");
+		expect(ctx.agentName).toBe("deployer-1");
+		// Non-secret settings come straight from config for this target id.
+		expect(ctx.settings).toEqual({ region: "us-east-1", replicas: 2, public: true });
+	});
+
+	test("settings default to an empty object when the target has no config entry", () => {
+		const target = fakeTarget("docker-gha", () => ({}));
+		// config.deploy.targets is empty → no entry for "docker-gha".
+		const config = configWith(root, { default: "docker-gha", targets: {} });
+
+		const ctx = buildDeployContext(baseArgs(target, config));
+
+		expect(ctx.settings).toEqual({});
+		expect(ctx.target).toBe("docker-gha");
+	});
+
+	test("keys settings by the target's own id, not the config default", () => {
+		const target = fakeTarget("docker-gha", () => ({}));
+		// A different target ("vercel") is the config default and has settings, but
+		// the passed target is "docker-gha" → its (absent) settings win → {}.
+		const config = configWith(root, {
+			default: "vercel",
+			targets: {
+				vercel: { settings: { region: "iad1" }, secretEnv: {}, environments: ["production"] },
+			},
+		});
+
+		const ctx = buildDeployContext(baseArgs(target, config));
+
+		expect(ctx.settings).toEqual({});
+	});
+
+	test("secretEnv is empty when the target requests no secrets", () => {
+		const target = fakeTarget("docker-gha", () => ({}));
+		const config = configWith(root, { default: "docker-gha", targets: {} });
+
+		const ctx = buildDeployContext(baseArgs(target, config));
+
+		expect(ctx.secretEnv).toEqual({});
+	});
+
+	test("secretEnv is empty when a requested secret is absent from file and env", () => {
+		// Target asks for REGISTRY_TOKEN, but neither the secrets file nor env has
+		// it → store.has is false → the target maps nothing.
+		const KEY = "AGENTPLATE_TEST_ABSENT_TOKEN_XYZ";
+		delete process.env[KEY];
+		const target = fakeTarget("docker-gha", (store) => {
+			const env: Record<string, string> = {};
+			if (store.has(KEY)) env[KEY] = store.get(KEY) ?? "";
+			return env;
+		});
+		const config = configWith(root, { default: "docker-gha", targets: {} });
+
+		const ctx = buildDeployContext(baseArgs(target, config));
+
+		expect(ctx.secretEnv).toEqual({});
+	});
+
+	test("secretEnv resolves a value the target asks for from the secrets file", async () => {
+		// Write a real gitignored secrets file; the store reads file-then-env.
+		const KEY = "REGISTRY_TOKEN";
+		await writeFile(join(root, AGENTPLATE_DIR, SECRETS_FILE), `${KEY}: tok-from-file\n`);
+		const target = fakeTarget("docker-gha", (store) => {
+			const v = store.get(KEY);
+			const env: Record<string, string> = {};
+			if (v !== undefined) env[KEY] = v;
+			return env;
+		});
+		const config = configWith(root, { default: "docker-gha", targets: {} });
+
+		const ctx = buildDeployContext(baseArgs(target, config));
+
+		expect(ctx.secretEnv).toEqual({ REGISTRY_TOKEN: "tok-from-file" });
+	});
+
+	test("secretEnv resolves a value from process.env when no file entry exists", () => {
+		const KEY = "AGENTPLATE_TEST_ENV_ONLY_TOKEN";
+		process.env[KEY] = "tok-from-env";
+		try {
+			const target = fakeTarget("docker-gha", (store) => {
+				const v = store.get(KEY);
+				const env: Record<string, string> = {};
+				if (v !== undefined) env[KEY] = v;
+				return env;
+			});
+			const config = configWith(root, { default: "docker-gha", targets: {} });
+
+			const ctx = buildDeployContext(baseArgs(target, config));
+
+			expect(ctx.secretEnv).toEqual({ [KEY]: "tok-from-env" });
+		} finally {
+			delete process.env[KEY];
+		}
+	});
+
+	test("profile is carried through unchanged", () => {
+		const p = profile();
+		const target = fakeTarget("docker-gha", () => ({}));
+		const config = configWith(root, { default: "docker-gha", targets: {} });
+
+		const ctx = buildDeployContext({ ...baseArgs(target, config), profile: p });
+
+		expect(ctx.profile).toBe(p);
+	});
+
+	test("runId may be null", () => {
+		const target = fakeTarget("docker-gha", () => ({}));
+		const config = configWith(root, { default: "docker-gha", targets: {} });
+
+		const ctx = buildDeployContext({ ...baseArgs(target, config), runId: null });
+
+		expect(ctx.runId).toBeNull();
+	});
+});

package/src/deploy/context.ts

@@ -0,0 +1,72 @@
+/**
+ * Deploy context builder.
+ *
+ * Assembles the {@link DeployContext} every target method
+ * (`generateConfig`/`deploy`/`verify`/`rollback`) receives. It is the single
+ * seam where non-secret settings (from `config.deploy.targets[id].settings`)
+ * meet resolved secret values (from the target's own `buildSecretEnv`, fed the
+ * project secret store). Settings come from config; secret *values* are read
+ * here at the moment of use and never persisted or logged — the context object
+ * lives only for the duration of one pipeline step.
+ */
+
+import type { AgentplateConfig } from "../types.ts";
+import { createDeploySecretStore } from "./secrets.ts";
+import type { AppProfile, DeployContext, DeployTarget } from "./types.ts";
+
+/** Inputs for {@link buildDeployContext}. */
+export interface BuildDeployContextArgs {
+	/** Absolute project root (used to resolve the secret store and as `projectRoot`). */
+	root: string;
+	/** Absolute path to the worktree the target operates on. */
+	worktreePath: string;
+	/** Resolved deploy target (its `id` keys into config settings; provides `buildSecretEnv`). */
+	target: DeployTarget;
+	/** Target environment ("preview" | "staging" | "production" | …). */
+	environment: string;
+	/** App profile detected (or supplied) for this deploy. */
+	profile: AppProfile;
+	/** When true: generate + plan only; no outward-facing mutation. */
+	dryRun: boolean;
+	/** Owning run id, or null when run outside a coordinator session. */
+	runId: string | null;
+	/** Name of the agent (or operator) performing the deploy. */
+	agentName: string;
+	/** Loaded Agentplate config (source of per-target non-secret settings). */
+	config: AgentplateConfig;
+}
+
+/**
+ * Build a {@link DeployContext} from a resolved target, environment, profile,
+ * and config.
+ *
+ * Non-secret settings are read from `config.deploy.targets[target.id].settings`
+ * (an empty object when the target has no config entry). Secret env is produced
+ * by `target.buildSecretEnv(...)` given a {@link createDeploySecretStore} bound
+ * to `root`, so each target decides exactly which named env vars it needs and
+ * the values resolve from the gitignored secrets file or `process.env`. When no
+ * secrets are configured the resulting `secretEnv` is simply empty.
+ *
+ * `projectRoot` is set to `root`; the returned object is plain data with no
+ * retained references to the config beyond the shallow `settings` map.
+ */
+export function buildDeployContext(args: BuildDeployContextArgs): DeployContext {
+	const { root, worktreePath, target, environment, profile, dryRun, runId, agentName, config } =
+		args;
+
+	const settings = config.deploy.targets[target.id]?.settings ?? {};
+	const secretEnv = target.buildSecretEnv(createDeploySecretStore(root));
+
+	return {
+		target: target.id,
+		environment,
+		worktreePath,
+		projectRoot: root,
+		profile,
+		secretEnv,
+		settings,
+		dryRun,
+		runId,
+		agentName,
+	};
+}

package/src/deploy/registry.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_CONFIG } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import type { AgentplateConfig } from "../types.ts";
+import { getAllDeployTargets, getDeployTarget, getDeployTargetNames } from "./registry.ts";
+import { DockerGhaTarget } from "./targets/docker-gha.ts";
+
+// Clone DEFAULT_CONFIG and set deploy.default, so tests never mutate the
+// shared default object.
+function configWithDefault(target: string): AgentplateConfig {
+	const config: AgentplateConfig = structuredClone(DEFAULT_CONFIG);
+	config.deploy = { ...config.deploy, default: target };
+	return config;
+}
+
+describe("getDeployTargetNames", () => {
+	test("lists the registered targets in registration order", () => {
+		expect(getDeployTargetNames()).toEqual(["docker-gha"]);
+	});
+});
+
+describe("getAllDeployTargets", () => {
+	test("returns one fresh instance per registered target", () => {
+		const all = getAllDeployTargets();
+		expect(all).toHaveLength(1);
+		expect(all[0]).toBeInstanceOf(DockerGhaTarget);
+	});
+
+	test("returns distinct instances across calls (no shared mutable state)", () => {
+		const first = getAllDeployTargets()[0];
+		const second = getAllDeployTargets()[0];
+		expect(first).not.toBe(second);
+	});
+});
+
+describe("getDeployTarget", () => {
+	test("resolves docker-gha by explicit name", () => {
+		const target = getDeployTarget("docker-gha");
+		expect(target).toBeInstanceOf(DockerGhaTarget);
+		expect(target.id).toBe("docker-gha");
+	});
+
+	test("returns a fresh instance on each call", () => {
+		expect(getDeployTarget("docker-gha")).not.toBe(getDeployTarget("docker-gha"));
+	});
+
+	test("resolves from config.deploy.default when no name is given", () => {
+		const target = getDeployTarget(undefined, configWithDefault("docker-gha"));
+		expect(target).toBeInstanceOf(DockerGhaTarget);
+		expect(target.id).toBe("docker-gha");
+	});
+
+	test("an explicit name takes precedence over config.deploy.default", () => {
+		// Default is an unknown target, but the explicit valid name wins, so this
+		// must resolve rather than throw.
+		const target = getDeployTarget("docker-gha", configWithDefault("vercel"));
+		expect(target).toBeInstanceOf(DockerGhaTarget);
+	});
+
+	test("throws ValidationError listing names when no name and no default are set", () => {
+		// DEFAULT_CONFIG.deploy.default is "" → treated as unset.
+		expect(() => getDeployTarget(undefined, structuredClone(DEFAULT_CONFIG))).toThrow(
+			ValidationError,
+		);
+		try {
+			getDeployTarget(undefined, structuredClone(DEFAULT_CONFIG));
+			throw new Error("expected getDeployTarget to throw");
+		} catch (error) {
+			expect(error).toBeInstanceOf(ValidationError);
+			expect((error as ValidationError).message).toContain("docker-gha");
+		}
+	});
+
+	test("throws ValidationError when called with no name and no config at all", () => {
+		expect(() => getDeployTarget()).toThrow(ValidationError);
+	});
+
+	test("throws ValidationError listing names on an unknown explicit name", () => {
+		expect(() => getDeployTarget("nope")).toThrow(ValidationError);
+		try {
+			getDeployTarget("nope");
+			throw new Error("expected getDeployTarget to throw");
+		} catch (error) {
+			expect(error).toBeInstanceOf(ValidationError);
+			expect((error as ValidationError).message).toContain("nope");
+			expect((error as ValidationError).message).toContain("docker-gha");
+		}
+	});
+
+	test("throws ValidationError on an unknown config default with no explicit name", () => {
+		expect(() => getDeployTarget(undefined, configWithDefault("bogus-target"))).toThrow(
+			ValidationError,
+		);
+		try {
+			getDeployTarget(undefined, configWithDefault("bogus-target"));
+			throw new Error("expected getDeployTarget to throw");
+		} catch (error) {
+			expect((error as ValidationError).message).toContain("bogus-target");
+		}
+	});
+});

package/src/deploy/registry.ts

@@ -0,0 +1,86 @@
+/**
+ * Deploy target registry — the single place that knows about concrete target
+ * classes.
+ *
+ * Everything else resolves a target by name through {@link getDeployTarget} and
+ * then talks only to the {@link DeployTarget} interface, so adding a new target
+ * is a one-line registration here plus its adapter file under `./targets/`.
+ *
+ * Unlike the runtime registry, resolution here has **no silent default
+ * fallback**: a deploy is consequential, so an unset target or a typo must fail
+ * loudly rather than ship somewhere unintended. The name is resolved from the
+ * explicit argument, then `config.deploy.default`; if neither is set, or the
+ * resolved name is unknown, a {@link ValidationError} is thrown listing the
+ * registered names.
+ */
+
+import { ValidationError } from "../errors.ts";
+import type { AgentplateConfig } from "../types.ts";
+import { DockerGhaTarget } from "./targets/docker-gha.ts";
+import type { DeployTarget } from "./types.ts";
+
+/**
+ * Name → factory map. Factories return a *fresh* instance per call so targets
+ * can never accidentally share mutable state between resolutions. Insertion
+ * order here defines the order reported by {@link getDeployTargetNames} and in
+ * error messages.
+ *
+ * Future targets land here as one-liners once their adapter file exists:
+ *   ["vercel",    () => new VercelTarget()],     // ./targets/vercel.ts
+ *   ["aws",       () => new AwsTarget()],         // ./targets/aws.ts
+ *   ["k8s-helm",  () => new K8sHelmTarget()],     // ./targets/k8s-helm.ts
+ *   ["onprem",    () => new OnpremTarget()],      // ./targets/onprem.ts
+ */
+const targets = new Map<string, () => DeployTarget>([["docker-gha", () => new DockerGhaTarget()]]);
+
+/**
+ * Resolve a deploy target by name.
+ *
+ * Lookup order:
+ *   1. explicit `name` (e.g. from `--target`),
+ *   2. `config.deploy.default`.
+ *
+ * There is intentionally **no** built-in default: if neither source yields a
+ * name, a {@link ValidationError} is thrown listing the registered targets so
+ * the operator must choose explicitly. An unknown name throws the same way.
+ *
+ * @param name - Target id to resolve (e.g. "docker-gha"). Omit to use the config default.
+ * @param config - Agentplate config; `config.deploy.default` is the fallback source.
+ * @throws {ValidationError} When no name resolves, or the resolved name is unknown.
+ * @returns A fresh {@link DeployTarget} instance.
+ */
+export function getDeployTarget(name?: string, config?: AgentplateConfig): DeployTarget {
+	const configDefault = config?.deploy?.default;
+	const resolved = name ?? (configDefault !== "" ? configDefault : undefined);
+	if (resolved === undefined || resolved === "") {
+		throw new ValidationError(
+			`No deploy target specified and config.deploy.default is unset. ` +
+				`Pass a target name. Available targets: ${getDeployTargetNames().join(", ")}`,
+		);
+	}
+	const factory = targets.get(resolved);
+	if (!factory) {
+		throw new ValidationError(
+			`Unknown deploy target: "${resolved}". Available targets: ${getDeployTargetNames().join(", ")}`,
+		);
+	}
+	return factory();
+}
+
+/**
+ * Names of all registered deploy targets, in registration order. Used to
+ * validate a user-supplied target name and to render the choices in help /
+ * errors.
+ */
+export function getDeployTargetNames(): string[] {
+	return [...targets.keys()];
+}
+
+/**
+ * Return one fresh instance of every registered deploy target. Used by callers
+ * that need to enumerate all targets (e.g. doctor preflight, auto-selection by
+ * `detect()` confidence).
+ */
+export function getAllDeployTargets(): DeployTarget[] {
+	return [...targets.values()].map((factory) => factory());
+}

package/src/deploy/secrets.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AGENTPLATE_DIR } from "../config.ts";
+import { setSecret } from "../secrets.ts";
+import type { DeployTargetConfig } from "../types.ts";
+import { createDeploySecretStore, missingSecretKeys, resolveTargetSecretEnv } from "./secrets.ts";
+
+let root: string;
+/** Env vars to restore after tests that exercise the process.env fallback. */
+const SAVED_ENV: Record<string, string | undefined> = {};
+
+function saveEnv(key: string): void {
+	if (!(key in SAVED_ENV)) SAVED_ENV[key] = process.env[key];
+}
+
+/** Build a minimal DeployTargetConfig with the given secret bindings. */
+function targetConfig(secretEnv: DeployTargetConfig["secretEnv"]): DeployTargetConfig {
+	return { settings: {}, secretEnv, environments: ["production"] };
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-deploy-secrets-"));
+	// setSecret writes <root>/.agentplate/secrets.local.yaml; the dir must exist.
+	mkdirSync(join(root, AGENTPLATE_DIR), { recursive: true });
+});
+
+afterEach(() => {
+	rmSync(root, { recursive: true, force: true });
+	for (const [key, value] of Object.entries(SAVED_ENV)) {
+		if (value === undefined) delete process.env[key];
+		else process.env[key] = value;
+		delete SAVED_ENV[key];
+	}
+});
+
+describe("createDeploySecretStore", () => {
+	test("get/has resolve a value from the file store", () => {
+		setSecret(root, "FLY_API_TOKEN", "tok-abc");
+		const store = createDeploySecretStore(root);
+		expect(store.get("FLY_API_TOKEN")).toBe("tok-abc");
+		expect(store.has("FLY_API_TOKEN")).toBe(true);
+	});
+
+	test("get returns undefined and has is false for an unknown key", () => {
+		const store = createDeploySecretStore(root);
+		expect(store.get("NOPE")).toBeUndefined();
+		expect(store.has("NOPE")).toBe(false);
+	});
+
+	test("falls back to process.env when the file store lacks the key", () => {
+		saveEnv("DEPLOY_ENV_ONLY");
+		process.env.DEPLOY_ENV_ONLY = "from-env";
+		const store = createDeploySecretStore(root);
+		expect(store.get("DEPLOY_ENV_ONLY")).toBe("from-env");
+		expect(store.has("DEPLOY_ENV_ONLY")).toBe(true);
+	});
+});
+
+describe("resolveTargetSecretEnv", () => {
+	test("maps logical keys to values via fromEnv bindings", () => {
+		setSecret(root, "FLY_API_TOKEN", "tok-abc");
+		setSecret(root, "REGISTRY_PASSWORD", "pw-123");
+		const cfg = targetConfig({
+			apiToken: { fromEnv: "FLY_API_TOKEN" },
+			registryPassword: { fromEnv: "REGISTRY_PASSWORD" },
+		});
+		expect(resolveTargetSecretEnv(root, cfg)).toEqual({
+			apiToken: "tok-abc",
+			registryPassword: "pw-123",
+		});
+	});
+
+	test("omits bindings whose env var is absent", () => {
+		setSecret(root, "PRESENT", "yes");
+		const cfg = targetConfig({
+			present: { fromEnv: "PRESENT" },
+			absent: { fromEnv: "MISSING_ONE" },
+		});
+		const resolved = resolveTargetSecretEnv(root, cfg);
+		expect(resolved).toEqual({ present: "yes" });
+		expect("absent" in resolved).toBe(false);
+	});
+
+	test("returns an empty map when there are no bindings", () => {
+		expect(resolveTargetSecretEnv(root, targetConfig({}))).toEqual({});
+	});
+
+	test("resolves a binding from process.env via the union store", () => {
+		saveEnv("CI_DEPLOY_TOKEN");
+		process.env.CI_DEPLOY_TOKEN = "ci-tok";
+		const cfg = targetConfig({ token: { fromEnv: "CI_DEPLOY_TOKEN" } });
+		expect(resolveTargetSecretEnv(root, cfg)).toEqual({ token: "ci-tok" });
+	});
+
+	test("logical key differs from env-var name (mapping, not pass-through)", () => {
+		setSecret(root, "AWS_SECRET_ACCESS_KEY", "secret-val");
+		const cfg = targetConfig({ secretKey: { fromEnv: "AWS_SECRET_ACCESS_KEY" } });
+		const resolved = resolveTargetSecretEnv(root, cfg);
+		expect(resolved.secretKey).toBe("secret-val");
+		expect("AWS_SECRET_ACCESS_KEY" in resolved).toBe(false);
+	});
+});
+
+describe("missingSecretKeys", () => {
+	test("reports absent env-var names only", () => {
+		setSecret(root, "HAVE_THIS", "v");
+		const missing = missingSecretKeys(root, ["HAVE_THIS", "MISSING_A", "MISSING_B"]);
+		expect(missing).toEqual(["MISSING_A", "MISSING_B"]);
+	});
+
+	test("returns an empty array when every required key is present", () => {
+		setSecret(root, "A", "1");
+		setSecret(root, "B", "2");
+		expect(missingSecretKeys(root, ["A", "B"])).toEqual([]);
+	});
+
+	test("counts a process.env-provided key as present", () => {
+		saveEnv("ENV_PROVIDED");
+		process.env.ENV_PROVIDED = "x";
+		setSecret(root, "FILE_PROVIDED", "y");
+		expect(missingSecretKeys(root, ["FILE_PROVIDED", "ENV_PROVIDED"])).toEqual([]);
+	});
+
+	test("returns an empty array for an empty required list", () => {
+		expect(missingSecretKeys(root, [])).toEqual([]);
+	});
+});