@theholocron/cli 1.0.0 → 1.1.0

package/dist/cli.mjs

@@ -0,0 +1,852 @@
+#!/usr/bin/env -S tsx
+import { t as CARDINALITY } from "./capabilities-QjjhVlDd.mjs";
+import { n as resolveConfig, t as ConfigError } from "./config-DWlIfFZm.mjs";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { spawnSync } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+//#region src/loader.ts
+var LoaderError = class extends Error {
+	name = "LoaderError";
+};
+var PluginLoader = class {
+	config;
+	context;
+	importer;
+	registry = /* @__PURE__ */ new Map();
+	constructor(config, context, importer = defaultImporter) {
+		this.config = config;
+		this.context = context;
+		this.importer = importer;
+	}
+	/** Imports every configured plugin and builds the capability registry. */
+	async load() {
+		const entries = Object.entries(this.config.providers);
+		for (const [key, entry] of entries) {
+			if (!entry) continue;
+			if (entry.cardinality === "single") this.registry.set(key, await this.loadOne(key, entry.tuple));
+			else {
+				const impls = [];
+				for (const tuple of entry.tuples) impls.push(await this.loadOne(key, tuple));
+				this.registry.set(key, impls);
+			}
+		}
+	}
+	/**
+	* Type-safe lookup. Single-cardinality keys return one impl;
+	* many-cardinality keys return an array. `ResolvedCapability<K>`
+	* encodes the split via the `CARDINALITY` map.
+	*/
+	get(key) {
+		const impl = this.registry.get(key);
+		if (impl === void 0) throw new LoaderError(`capability \`${key}\` is not loaded — is it declared in holocron.config.json?`);
+		return impl;
+	}
+	/** Whether a capability has been loaded. */
+	has(key) {
+		return this.registry.has(key);
+	}
+	/** All capability keys currently loaded. Useful for the doctor command. */
+	loadedKeys() {
+		return Array.from(this.registry.keys());
+	}
+	/** Internal — invoke a plugin's capability factory and return the impl. */
+	async loadOne(key, tuple) {
+		const module = await this.importer(tuple.packageName).catch((err) => {
+			throw new LoaderError(`failed to import \`${tuple.packageName}\` for capability \`${key}\`: ${err instanceof Error ? err.message : String(err)}`);
+		});
+		if (typeof module.createPlugin !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not export \`createPlugin(options)\``);
+		const factory = module.createPlugin({
+			...this.context,
+			...tuple.options
+		}).capabilities[key];
+		if (typeof factory !== "function") throw new LoaderError(`\`${tuple.packageName}\` does not implement the \`${key}\` capability`);
+		return factory();
+	}
+};
+/** Default importer — native dynamic import. */
+const defaultImporter = async (pkg) => {
+	return await import(pkg);
+};
+//#endregion
+//#region src/commands/deploy.ts
+async function runDeploy(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	const dryRun = input.context.dryRun ?? false;
+	print(`Holocron deploy — branch=${input.branch}${input.target ? `, target=${input.target}` : " (preview)"}${dryRun ? " (dry-run)" : ""}`);
+	if (!loader.has("deployment")) throw new Error("deployment capability is not configured — add a `deployment` provider to holocron.config.json");
+	const deploy = loader.get("deployment");
+	if (dryRun) {
+		const message = `would: ${deploy.providerName}.triggerDeployment(projectId=${input.projectId}, branch=${input.branch}${input.target ? `, target=${input.target}` : ""})`;
+		print(`  … ${message}`);
+		return {
+			deployment: null,
+			status: "dry-run",
+			message
+		};
+	}
+	try {
+		const record = await deploy.triggerDeployment({
+			projectId: input.projectId,
+			branch: input.branch,
+			...input.target ? { target: input.target } : {}
+		});
+		print(`  ✓ ${record.status} — ${record.url}`);
+		return {
+			deployment: record,
+			status: "ok"
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		print(`  ✗ ${message}`);
+		return {
+			deployment: null,
+			status: "fail",
+			message
+		};
+	}
+}
+//#endregion
+//#region src/commands/doctor.ts
+async function runDoctor(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	const rows = [];
+	const config = input.loaded.resolved;
+	print(`Holocron doctor — ${config.project.name}`);
+	print(`  config: ${input.loaded.filepath}`);
+	print("");
+	for (const key of loader.loadedKeys()) {
+		const cardinality = CARDINALITY[key];
+		const entry = config.providers[key];
+		const providers = entry?.cardinality === "many" ? entry.tuples.map((t) => t.provider) : entry?.cardinality === "single" ? [entry.tuple.provider] : [];
+		if (cardinality === "many") loader.get(key).forEach((_impl, idx) => {
+			rows.push({
+				capability: key,
+				provider: providers[idx] ?? "?",
+				status: "skip",
+				message: "loaded (no smoke check defined for this capability)"
+			});
+		});
+		else {
+			const impl = loader.get(key);
+			const row = await smokeCheck(key, providers[0] ?? "?", impl);
+			rows.push(row);
+		}
+	}
+	for (const row of rows) print(`  ${row.status === "ok" ? "✓" : row.status === "fail" ? "✗" : "·"} ${pad(row.capability, 14)} via ${pad(row.provider, 14)}  ${row.message}`);
+	const summary = rows.reduce((acc, r) => {
+		acc[r.status] += 1;
+		return acc;
+	}, {
+		ok: 0,
+		fail: 0,
+		skip: 0
+	});
+	print("");
+	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped`);
+	return {
+		rows,
+		summary
+	};
+}
+async function smokeCheck(key, provider, impl) {
+	try {
+		switch (key) {
+			case "source": return mk(key, provider, "ok", `whoami: ${(await impl.whoami()).login}`);
+			case "issues": {
+				const report = await impl.doctor();
+				return mk(key, provider, "ok", `${report.authedAs} / ${report.projectLabel} (${countResolvedLifecycle(report)})`);
+			}
+			case "secrets": return mk(key, provider, "ok", `repo secrets: ${(await impl.listSecrets({ kind: "repo" })).length} configured`);
+			case "ci": {
+				const runs = await impl.listRuns({ limit: 1 });
+				return mk(key, provider, "ok", runs.length === 0 ? "no recent runs" : `most recent: ${runs[0].workflowName} (${runs[0].status})`);
+			}
+			case "vault": return mk(key, provider, "ok", `${(await impl.list()).length} keys available`);
+			case "auth": {
+				const desc = await impl.describe();
+				return mk(key, provider, "ok", `provider: ${desc.provider}; env keys: ${desc.envKeys.join(", ")}`);
+			}
+			default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
+		}
+	} catch (err) {
+		return mk(key, provider, "fail", err instanceof Error ? err.message : String(err));
+	}
+}
+function countResolvedLifecycle(report) {
+	return `${report.lifecycle.filter((l) => l.resolved).length}/${report.lifecycle.length} lifecycle slots ready`;
+}
+function mk(capability, provider, status, message) {
+	return {
+		capability,
+		provider,
+		status,
+		message
+	};
+}
+function pad(s, width) {
+	return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+//#endregion
+//#region src/commands/npm-publish-initial.ts
+/**
+* `holocron npm publish-initial` — bottles up the chicken-and-egg
+* bootstrap that every new npm-published holocron monorepo hits.
+*
+* npm requires a package to exist before Trusted Publishing can be
+* configured on it. So the first publish has to happen outside the
+* OIDC flow — using either a browser-auth session (`npm login
+* --auth-type=web`) or an ephemeral automation token. This command
+* runs the publish step + tells you exactly what to do next.
+*
+* Workflow:
+*
+*   $ npm login --auth-type=web          # one-time, browser-based
+*   $ pnpm install --frozen-lockfile
+*   $ pnpm build
+*   $ pnpm exec tsx packages/cli/src/cli.ts npm publish-initial
+*
+* The command itself only handles the publish step + the post-publish
+* Trusted Publisher setup reminder. `pnpm install` + `pnpm build`
+* stay outside the command (no pnpm-inside-pnpm).
+*
+* If `NPM_TOKEN` is detected in env, the command prints a final
+* "revoke this token at <url>" reminder — same pattern as `rando vc
+* setup` for the ephemeral GH admin PAT.
+*/
+const PUBLISHABLE_PACKAGES = [
+	"@theholocron/cli",
+	"@theholocron/holocron-plugin-github",
+	"@theholocron/holocron-plugin-vercel",
+	"@theholocron/holocron-plugin-neon",
+	"@theholocron/holocron-plugin-clerk",
+	"@theholocron/holocron-plugin-1password",
+	"@theholocron/holocron-plugin-postman"
+];
+async function runNpmPublishInitial(input = {}) {
+	const print = input.print ?? ((line) => console.log(line));
+	const cwd = input.cwd ?? process.cwd();
+	const tag = input.tag ?? "alpha";
+	const dryRun = input.dryRun ?? false;
+	const otp = input.otp;
+	const env = input.env ?? process.env;
+	const exec = input.exec ?? defaultExec;
+	const publishArgs = [
+		"-r",
+		"--filter=./packages/*",
+		"--filter=!@theholocron/cli-utils",
+		"publish",
+		"--access",
+		"public",
+		"--no-git-checks",
+		"--tag",
+		tag,
+		...otp ? ["--otp", otp] : []
+	];
+	print(`Holocron npm publish-initial${dryRun ? " (dry-run)" : ""}`);
+	print(`  cwd: ${cwd}`);
+	print(`  tag: ${tag}`);
+	if (otp) print(`  otp: <${otp.length} chars>`);
+	print("");
+	print("  → verifying npm auth (`npm whoami`)…");
+	const whoami = await exec("npm", ["whoami"], { cwd });
+	if (whoami.exitCode !== 0) {
+		const message = "npm is not authenticated. Run `npm login --auth-type=web` (browser flow, no token stored) or `npm login`, then re-run this command.";
+		print(`  ✗ ${message}`);
+		return {
+			status: "fail",
+			message,
+			packageNames: PUBLISHABLE_PACKAGES
+		};
+	}
+	print(`    ✓ authed as ${whoami.stdout.trim() || "<unknown>"}`);
+	if (dryRun) {
+		print("");
+		print("  … (dry-run) skipping actual publish");
+		print(`    would run: pnpm ${publishArgs.join(" ")}`);
+		printNextSteps(print, env);
+		return {
+			status: "dry-run",
+			message: "dry-run — no publish executed",
+			packageNames: PUBLISHABLE_PACKAGES
+		};
+	}
+	print("");
+	print("  → publishing all public @theholocron/* packages…");
+	const publish = await exec("pnpm", publishArgs, { cwd });
+	if (publish.exitCode !== 0) {
+		const message = `publish failed (exit ${publish.exitCode}): ${publish.stderr.trim() || publish.stdout.trim() || "no output"}`;
+		print(`  ✗ ${message}`);
+		if (publish.stdout.includes("EOTP") || publish.stderr.includes("EOTP")) {
+			print("");
+			print("  → hint: your npm account requires 2FA for writes. Re-run with `--otp <code>`:");
+			print(`    pnpm exec tsx packages/cli/src/cli.ts npm publish-initial --otp <6-digit-code>`);
+		}
+		return {
+			status: "fail",
+			message,
+			packageNames: PUBLISHABLE_PACKAGES
+		};
+	}
+	print("    ✓ publish complete");
+	printNextSteps(print, env);
+	return {
+		status: "ok",
+		packageNames: PUBLISHABLE_PACKAGES
+	};
+}
+function printNextSteps(print, env) {
+	print("");
+	print("  → next: configure Trusted Publisher for each package on npm:");
+	for (const name of PUBLISHABLE_PACKAGES) print(`    https://www.npmjs.com/package/${name}/access`);
+	print("    Publisher: GitHub Actions   Org: theholocron   Repo: holocron   Workflow: release.yml");
+	if (env.NPM_TOKEN) {
+		print("");
+		print("  → cleanup: $NPM_TOKEN was used. Revoke it now (no API for self-revoke; UI-only):");
+		print("    https://www.npmjs.com/settings/~/tokens");
+	}
+}
+const defaultExec = async (cmd, args, opts) => {
+	const result = spawnSync(cmd, args, {
+		cwd: opts.cwd,
+		encoding: "utf8",
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		exitCode: result.status ?? -1,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? ""
+	};
+};
+//#endregion
+//#region src/commands/secret-set.ts
+async function runSecretSet(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	const dryRun = input.context.dryRun ?? false;
+	const scope = input.scope ?? { kind: "repo" };
+	if (!loader.has("secrets")) throw new Error("`secrets` capability is not configured — add a `secrets` provider to holocron.config.json");
+	const value = await resolveValue(input);
+	if (!value) throw new Error(`no value for secret \`${input.name}\` — pass it positionally, via --from-stdin, --from-env <NAME>, or set $${input.name} in the environment`);
+	print(`Holocron secret set — ${input.name} (${describeScope(scope)})${dryRun ? " (dry-run)" : ""}`);
+	if (dryRun) {
+		const message = `would: secrets.setSecret(${describeScope(scope)}, ${input.name}, <${value.length} chars>)`;
+		print(`  … ${message}`);
+		return {
+			status: "dry-run",
+			name: input.name,
+			scope,
+			message
+		};
+	}
+	try {
+		const secrets = loader.get("secrets");
+		await secrets.setSecret(scope, input.name, value);
+		print(`  ✓ set ${input.name} via ${secrets.providerName}`);
+		return {
+			status: "ok",
+			name: input.name,
+			scope
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		print(`  ✗ ${message}`);
+		return {
+			status: "fail",
+			name: input.name,
+			scope,
+			message
+		};
+	}
+}
+async function resolveValue(input) {
+	if (input.value) return input.value;
+	if (input.fromStdin) return (await (input.readStdin ?? defaultReadStdin)()).replace(/\r?\n$/, "");
+	const env = process.env;
+	if (input.fromEnv) return env[input.fromEnv];
+	return env[input.name];
+}
+async function defaultReadStdin() {
+	const chunks = [];
+	return new Promise((resolve, reject) => {
+		process.stdin.on("data", (chunk) => chunks.push(chunk));
+		process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		process.stdin.on("error", reject);
+	});
+}
+function describeScope(scope) {
+	if (scope.kind === "repo") return "scope=repo";
+	if (scope.kind === "environment") return `scope=environment:${scope.name}`;
+	return `scope=organization:${scope.name}`;
+}
+//#endregion
+//#region src/commands/secrets-sync.ts
+async function runSecretsSync(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	const dryRun = input.context.dryRun ?? false;
+	const targets = input.targets ?? ["production", "preview"];
+	print(`Holocron secrets sync — environment ${input.environmentId}${dryRun ? " (dry-run)" : ""}`);
+	print(`  vault: ${vaultProviderName(loader)}`);
+	print("");
+	const vault = loader.get("vault");
+	if (!vault.readEnvironment) throw new Error(`vault provider (${vault.providerName}) does not implement readEnvironment — sync needs bulk env reads`);
+	const envVars = await vault.readEnvironment(input.environmentId);
+	const keys = Object.keys(envVars).sort();
+	print(`  → read ${keys.length} keys from vault`);
+	print("");
+	const rows = [];
+	if (loader.has("secrets")) {
+		const secrets = loader.get("secrets");
+		print("  → secrets (repo scope)");
+		for (const key of keys) {
+			rows.push(await runRow(`secrets:${secrets.providerName}`, "scope=repo", key, dryRun, async () => {
+				await secrets.setSecret({ kind: "repo" }, key, envVars[key]);
+			}));
+			print(formatRow(rows[rows.length - 1]));
+		}
+	}
+	if (loader.has("deployment")) {
+		const deploy = loader.get("deployment");
+		if (!input.projectId) {
+			print("  → deployment");
+			const row = {
+				destination: `deployment:${deploy.providerName}`,
+				scope: "no projectId",
+				key: "(all)",
+				status: "skip",
+				message: "projectId required for deployment env-var sync (pass --project-id)"
+			};
+			rows.push(row);
+			print(formatRow(row));
+		} else for (const target of targets) {
+			print(`  → deployment (target=${target})`);
+			for (const key of keys) {
+				rows.push(await runRow(`deployment:${deploy.providerName}`, `target=${target}`, key, dryRun, async () => {
+					await deploy.setEnvVar(input.projectId, target, key, envVars[key]);
+				}));
+				print(formatRow(rows[rows.length - 1]));
+			}
+		}
+	}
+	const summary = rows.reduce((acc, r) => {
+		if (r.status === "ok") acc.ok += 1;
+		else if (r.status === "fail") acc.fail += 1;
+		else if (r.status === "skip") acc.skip += 1;
+		else if (r.status === "dry-run") acc.dryRun += 1;
+		return acc;
+	}, {
+		ok: 0,
+		fail: 0,
+		skip: 0,
+		dryRun: 0
+	});
+	print("");
+	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`);
+	return {
+		rows,
+		summary
+	};
+}
+async function runRow(destination, scope, key, dryRun, body) {
+	if (dryRun) return {
+		destination,
+		scope,
+		key,
+		status: "dry-run"
+	};
+	try {
+		await body();
+		return {
+			destination,
+			scope,
+			key,
+			status: "ok"
+		};
+	} catch (err) {
+		return {
+			destination,
+			scope,
+			key,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+function formatRow(row) {
+	const icon = row.status === "ok" ? "✓" : row.status === "fail" ? "✗" : row.status === "dry-run" ? "…" : "·";
+	const detail = row.message ? `  (${row.message})` : "";
+	return `    ${icon} ${row.key}${detail}`;
+}
+function vaultProviderName(loader) {
+	if (!loader.has("vault")) return "<missing>";
+	return loader.get("vault").providerName;
+}
+//#endregion
+//#region src/commands/setup.ts
+async function runSetup(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	const config = input.loaded.resolved;
+	const dryRun = input.context.dryRun ?? false;
+	const steps = [];
+	print(`Holocron setup — ${config.project.name}${dryRun ? " (dry-run)" : ""}`);
+	print(`  config: ${input.loaded.filepath}`);
+	print("");
+	if (loader.has("source")) {
+		const source = loader.get("source");
+		print("  → source");
+		for (const method of [
+			"enableVulnerabilityAlerts",
+			"enableAutomatedSecurityFixes",
+			"enableSecretScanning",
+			"enablePrivateVulnerabilityReporting"
+		]) {
+			steps.push(await runStep("source", method, dryRun, async () => {
+				await source[method]();
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	if (loader.has("environments")) {
+		const envs = loader.get("environments");
+		print("  → environments");
+		for (const envName of ["staging", "production"]) {
+			steps.push(await runStep("environments", `upsert ${envName}`, dryRun, async () => {
+				await envs.upsertEnvironment({ name: envName });
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	if (loader.has("deployment")) {
+		const deploy = loader.get("deployment");
+		print("  → deployment");
+		steps.push(await runStep("deployment", `ensureProject ${config.project.name}`, dryRun, async () => {
+			await deploy.ensureProject({ name: config.project.name });
+		}));
+		print(formatStep(steps[steps.length - 1]));
+	}
+	if (loader.has("auth")) {
+		const auth = loader.get("auth");
+		print("  → auth");
+		if (auth.ensureWebhookApp) {
+			steps.push(await runStep("auth", "ensureWebhookApp", dryRun, async () => {
+				return `webhook ${(await auth.ensureWebhookApp()).alreadyExists ? "exists" : "created"}`;
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		} else {
+			steps.push({
+				capability: "auth",
+				step: "ensureWebhookApp",
+				status: "skip",
+				message: "provider does not implement ensureWebhookApp"
+			});
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	if (loader.has("vault")) {
+		const vault = loader.get("vault");
+		print("  → vault");
+		try {
+			const keys = await vault.list();
+			steps.push({
+				capability: "vault",
+				step: "list",
+				status: "ok",
+				message: `${keys.length} keys available`
+			});
+		} catch (err) {
+			steps.push({
+				capability: "vault",
+				step: "list",
+				status: "fail",
+				message: err instanceof Error ? err.message : String(err)
+			});
+		}
+		print(formatStep(steps[steps.length - 1]));
+	}
+	if (loader.has("tooling")) {
+		const tools = loader.get("tooling");
+		print("  → tooling");
+		for (const tool of tools) {
+			steps.push(await runStep("tooling", `${tool.providerName}.sync`, dryRun, async () => {
+				await tool.sync();
+			}));
+			print(formatStep(steps[steps.length - 1]));
+		}
+	}
+	const summary = steps.reduce((acc, s) => {
+		if (s.status === "ok") acc.ok += 1;
+		else if (s.status === "fail") acc.fail += 1;
+		else if (s.status === "skip") acc.skip += 1;
+		else if (s.status === "dry-run") acc.dryRun += 1;
+		return acc;
+	}, {
+		ok: 0,
+		fail: 0,
+		skip: 0,
+		dryRun: 0
+	});
+	print("");
+	print(`  ${summary.ok} ok, ${summary.fail} fail, ${summary.skip} skipped${dryRun ? `, ${summary.dryRun} would-do` : ""}`);
+	return {
+		steps,
+		summary
+	};
+}
+async function runStep(capability, step, dryRun, body) {
+	if (dryRun) return {
+		capability,
+		step,
+		status: "dry-run"
+	};
+	try {
+		const note = await body();
+		const result = {
+			capability,
+			step,
+			status: "ok"
+		};
+		if (typeof note === "string") result.message = note;
+		return result;
+	} catch (err) {
+		return {
+			capability,
+			step,
+			status: "fail",
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+function formatStep(step) {
+	const icon = step.status === "ok" ? "✓" : step.status === "fail" ? "✗" : step.status === "dry-run" ? "…" : "·";
+	const detail = step.message ? `  (${step.message})` : "";
+	return `    ${icon} ${step.step}${detail}`;
+}
+//#endregion
+//#region src/load-config.ts
+/**
+* `holocron.config.{json,js,ts}` file loader.
+*
+* v2.0 only documents the JSON form, but the loader looks up all three
+* extensions in priority order (json → js → ts) — that's the schema
+* commitment captured in [`.notes/tech-architecture.spec.md` → Roadmap
+* → Shareable configs] so the JS/TS preset story (issue #75) can land
+* later without a breaking change.
+*
+* The JS/TS forms aren't actually parsed today; they trigger a clear
+* error telling the operator to use JSON for v2.0. The contract is the
+* lookup order, not the interpretation.
+*/
+const CANDIDATE_FILENAMES = [
+	"holocron.config.json",
+	"holocron.config.js",
+	"holocron.config.ts"
+];
+var ConfigFileError = class extends Error {
+	name = "ConfigFileError";
+};
+/**
+* Read + parse + resolve `holocron.config.*` from the given directory.
+* Search order: json → js → ts. Throws `ConfigFileError` if nothing
+* found, or `ConfigError` if the JSON is malformed / invalid.
+*/
+async function loadConfig(cwd) {
+	for (const filename of CANDIDATE_FILENAMES) {
+		const fullPath = join(cwd, filename);
+		if (await fileExists(fullPath)) {
+			if (filename.endsWith(".json")) return {
+				resolved: await loadJson(fullPath),
+				filepath: fullPath
+			};
+			throw new ConfigFileError(`${filename} found, but v2.0 only supports the JSON form. Rename to holocron.config.json. The JS/TS form lands with the preset feature (see issue #75).`);
+		}
+	}
+	throw new ConfigFileError(`no holocron.config.{json,js,ts} found in ${cwd}. Create one — see the README for the schema.`);
+}
+async function loadJson(filepath) {
+	const raw = await readFile(filepath, "utf8");
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new ConfigError(`${filepath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return resolveConfig(parsed);
+}
+async function fileExists(path) {
+	try {
+		return (await stat(path)).isFile();
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/cli.ts
+await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [options]").option("dry-run", {
+	type: "boolean",
+	default: false,
+	describe: "Print what would be mutated without calling capability mutators. Commands branch on this; read-only commands ignore it."
+}).option("token", {
+	type: "string",
+	describe: "Vendor token passed to plugins as `cliToken`, taking precedence over env vars. Unambiguous for single-plugin commands; for multi-plugin flows pass per-vendor env vars instead."
+}).option("cwd", {
+	type: "string",
+	default: process.cwd(),
+	describe: "Directory to search for holocron.config.json"
+}).command("version", "Print the CLI version", () => {}, () => {
+	console.log("holocron 2.0.0-alpha.0");
+}).command("doctor", "Load the config and run a smoke check against every provider", (y) => y.option("repo", {
+	type: "string",
+	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
+}), async (argv) => {
+	if ((await runDoctor({
+		loaded: await loadConfig(argv.cwd),
+		context: {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...argv.repo ? { repo: argv.repo } : {},
+			...argv.token ? { cliToken: argv.token } : {}
+		}
+	})).summary.fail > 0) process.exitCode = 1;
+}).command("setup", "Apply infra setup actions across every configured capability", (y) => y.option("repo", {
+	type: "string",
+	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."
+}), async (argv) => {
+	if ((await runSetup({
+		loaded: await loadConfig(argv.cwd),
+		context: {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...argv.repo ? { repo: argv.repo } : {},
+			...argv.token ? { cliToken: argv.token } : {}
+		}
+	})).summary.fail > 0) process.exitCode = 1;
+}).command("secret set <name> [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
+	type: "string",
+	demandOption: true,
+	describe: "Secret name (e.g., NPM_TOKEN)"
+}).positional("value", {
+	type: "string",
+	describe: "Secret value (positional). If omitted, sources from --from-stdin, --from-env, or env var matching <name>."
+}).option("from-stdin", {
+	type: "boolean",
+	default: false,
+	describe: "Read the secret value from stdin"
+}).option("from-env", {
+	type: "string",
+	describe: "Read the secret value from the named env var (otherwise: env var matching <name>)"
+}).option("scope", {
+	type: "string",
+	default: "repo",
+	describe: "Scope: \"repo\" (default), \"env=<name>\", or \"org=<name>\""
+}), async (argv) => {
+	const scopeArg = argv.scope;
+	const scope = parseScope(scopeArg);
+	if ((await runSecretSet({
+		loaded: await loadConfig(argv.cwd),
+		context: {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...argv.token ? { cliToken: argv.token } : {}
+		},
+		name: argv.name,
+		...argv.value ? { value: argv.value } : {},
+		...argv.fromStdin ? { fromStdin: true } : {},
+		...argv.fromEnv ? { fromEnv: argv.fromEnv } : {},
+		scope
+	})).status === "fail") process.exitCode = 1;
+}).command("secrets sync <environmentId>", "Read a vault environment + fan KEY=VALUEs out to secrets + deployment env vars", (y) => y.positional("environmentId", {
+	type: "string",
+	demandOption: true,
+	describe: "Vault environment id to read (1P Environment id, etc.)"
+}).option("project-id", {
+	type: "string",
+	describe: "Deployment project id (e.g., Vercel prj_*). Required when deployment is loaded."
+}).option("target", {
+	type: "array",
+	default: ["production", "preview"],
+	describe: "Deployment targets to sync to. Defaults to production + preview."
+}), async (argv) => {
+	if ((await runSecretsSync({
+		loaded: await loadConfig(argv.cwd),
+		context: {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...argv.token ? { cliToken: argv.token } : {}
+		},
+		environmentId: argv.environmentId,
+		...argv.projectId ? { projectId: argv.projectId } : {},
+		targets: argv.target
+	})).summary.fail > 0) process.exitCode = 1;
+}).command("deploy <branch>", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
+	type: "string",
+	demandOption: true,
+	describe: "Git branch to deploy"
+}).option("project-id", {
+	type: "string",
+	demandOption: true,
+	describe: "Deployment project id (e.g., Vercel prj_*)"
+}).option("target", {
+	type: "string",
+	choices: ["production", "staging"],
+	describe: "Named environment to deploy into. Omit for a branch preview."
+}), async (argv) => {
+	if ((await runDeploy({
+		loaded: await loadConfig(argv.cwd),
+		context: {
+			repoRoot: argv.cwd,
+			dryRun: argv.dryRun,
+			...argv.token ? { cliToken: argv.token } : {}
+		},
+		projectId: argv.projectId,
+		branch: argv.branch,
+		...argv.target ? { target: argv.target } : {}
+	})).status === "fail") process.exitCode = 1;
+}).command("npm publish-initial", "One-shot bootstrap publish for trusted-publishing-eligible packages", (y) => y.option("tag", {
+	type: "string",
+	default: "alpha",
+	describe: "npm distribution tag (defaults to alpha)"
+}).option("otp", {
+	type: "string",
+	describe: "One-time password from your authenticator (required if npm needs 2FA for writes)"
+}), async (argv) => {
+	if ((await runNpmPublishInitial({
+		cwd: argv.cwd,
+		tag: argv.tag,
+		dryRun: argv.dryRun,
+		...argv.otp ? { otp: argv.otp } : {}
+	})).status === "fail") process.exitCode = 1;
+}).command("config show", "Print the resolved holocron config", () => {}, async (argv) => {
+	const loaded = await loadConfig(argv.cwd);
+	console.log(JSON.stringify(loaded.resolved, null, 2));
+}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().parse();
+/**
+* Parse `--scope` strings: `repo` | `env=NAME` | `org=NAME`.
+*/
+function parseScope(s) {
+	if (s === "repo") return { kind: "repo" };
+	if (s.startsWith("env=")) return {
+		kind: "environment",
+		name: s.slice(4)
+	};
+	if (s.startsWith("org=")) return {
+		kind: "organization",
+		name: s.slice(4)
+	};
+	throw new Error(`invalid --scope "${s}" — expected "repo", "env=<name>", or "org=<name>"`);
+}
+//#endregion
+export {};