@theholocron/cli 5.0.0-alpha.159 → 5.0.0-alpha.160

package/dist/cli.mjs

@@ -24,8 +24,8 @@ import search from "@inquirer/search";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import ora from "ora";
 import { findRootSync, walkFilesSync } from "@theholocron/fs-utils";
-import { stringifyJson } from "@theholocron/json-utils";
 import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { stringifyJson } from "@theholocron/json-utils";
 import { createHash, randomUUID } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
 import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getUtils } from "@theholocron/registry-doc";
@@ -410,6 +410,8 @@ const COMMAND_CONTEXTS = {
 	deploy: "workspace",
 	"deploy cleanup-preview": "workspace",
 	"monitoring check": "workspace",
+	"monitoring resolve-checks": "workspace",
+	"monitoring run-resolved": "global",
 	"repo sync": "workspace",
 	"sync github": "workspace"
 };
@@ -1142,6 +1144,7 @@ async function runCheckAgainstUrl(input, opts = {}) {
 		response = await doFetch(url, {
 			method,
 			...hasBody ? { body: input.body } : {},
+			...opts.headers ? { headers: opts.headers } : {},
 			redirect: "manual",
 			signal: AbortSignal.timeout(opts.timeoutMs ?? 1e4)
 		});
@@ -1232,6 +1235,42 @@ function evaluate(comparison, actual, target) {
 	}
 }
 //#endregion
+//#region src/plugin/verify-vercel-project/verify-vercel-project.ts
+/**
+* `true` only when Vercel's API confirms `url` resolves to a deployment
+* whose `projectId` matches `expectedProjectId` exactly. `false` for any
+* other outcome — a non-matching project, a non-2xx response, a
+* malformed body, or a transport failure — never throws, since every one
+* of those outcomes means the same thing to a caller: don't attach the
+* credential.
+*/
+async function verifyVercelDeploymentProject(url, expectedProjectId, token, opts = {}) {
+	const doFetch = opts.fetch ?? fetch;
+	const baseUrl = opts.baseUrl ?? "https://api.vercel.com";
+	let host;
+	try {
+		host = new URL(url).host;
+	} catch {
+		return false;
+	}
+	const params = new URLSearchParams({ url: host });
+	if (opts.teamId) params.set("teamId", opts.teamId);
+	let response;
+	try {
+		response = await doFetch(`${baseUrl}/v13/deployments/get?${params}`, { headers: { Authorization: `Bearer ${token}` } });
+	} catch {
+		return false;
+	}
+	if (!response.ok) return false;
+	let body;
+	try {
+		body = await response.json();
+	} catch {
+		return false;
+	}
+	return (typeof body === "object" && body !== null && "projectId" in body ? body.projectId : void 0) === expectedProjectId;
+}
+//#endregion
 //#region src/plugin/workspace/workspace.ts
 /**
 * The `workspace`-context guard.
@@ -2313,16 +2352,57 @@ function mk(capability, provider, status, message) {
 }
 //#endregion
 //#region src/commands/monitoring-check/monitoring-check.ts
-async function runMonitoringCheck(input) {
-	const print = input.print ?? ((line) => console.log(line));
-	const logger = input.logger ?? getLogger();
+/**
+* `holocron monitoring check <url>` — runs every configured `monitoring`
+* check against an arbitrary URL instead of each check's own configured
+* one (holocron#1010).
+*
+* Built for CI: the `delivery.previewCheck` task runs this against a
+* PR's Vercel preview deployment, reusing the exact same check
+* definitions already in `holocron.config.ts` for production — no
+* vendor API call, no separate checks-as-code file to keep in sync.
+*
+* Split into two pieces (holocron#1030/#1032 review) so a caller that
+* needs to attach a credential to the request (e.g. Vercel's Deployment
+* Protection bypass header) can do so in a process that never loads a
+* PR's own `holocron.config.ts` at all:
+*   - {@link resolveMonitoringChecks} — loads config/plugins, returns the
+*     configured `MonitoringCheckInput[]`. Untrusted: this executes
+*     whatever code a PR's own config file contains. Never give this
+*     process a credential worth protecting.
+*   - {@link reportChecks} — takes an already-resolved check list (no
+*     config loading at all) and runs/report them against a URL. Safe
+*     to run with a credential present, since nothing here executes
+*     PR-authored code.
+* `runMonitoringCheck` composes both, unchanged, for every caller that
+* doesn't need the split (the plain CLI invocation, tests, anywhere a
+* credential isn't in play).
+*/
+/**
+* Loads config/plugins and returns the configured `monitoring` checks —
+* the untrusted half of `monitoring check`. Executes a PR's own
+* `holocron.config.ts` (and whatever it imports); never run this with a
+* credential in the process environment that a malicious config could
+* read and exfiltrate.
+*/
+async function resolveMonitoringChecks(input) {
 	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
 	await loader.load();
 	assertPluginsResolvable(loader, "monitoring check");
-	const monitoring = loader.get("monitoring");
+	return [...loader.get("monitoring").checks];
+}
+/**
+* Runs an already-resolved check list against `url` and reports
+* pass/fail — the trusted half of `monitoring check`. Takes plain data,
+* never touches `holocron.config.ts` or any plugin: safe to run with a
+* credential (in `headers` or elsewhere in the process env) present.
+*/
+async function reportChecks(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
 	const run = input.runCheck ?? runCheckAgainstUrl;
 	print(`Holocron monitoring check — against ${input.url}`);
-	if (monitoring.checks.length === 0) {
+	if (input.checks.length === 0) {
 		print(`✗ no monitoring checks configured — nothing to validate`);
 		logger.warn({ url: input.url }, "monitoring check: no checks configured");
 		return {
@@ -2331,8 +2411,11 @@ async function runMonitoringCheck(input) {
 		};
 	}
 	const checks = [];
-	for (const checkInput of monitoring.checks) {
-		const result = await run(checkInput, { url: input.url });
+	for (const checkInput of input.checks) {
+		const result = await run(checkInput, {
+			url: input.url,
+			...input.headers ? { headers: input.headers } : {}
+		});
 		if (result.requestError) {
 			print(`  ✗ ${checkInput.name}  (request failed: ${result.requestError})`);
 			checks.push({
@@ -2372,6 +2455,110 @@ async function runMonitoringCheck(input) {
 		checks
 	};
 }
+/**
+* `resolveMonitoringChecks` + `reportChecks` in one call — the plain CLI
+* contract, unchanged. Only safe to run with a credential present when
+* the config being loaded is trusted (no PR in the loop); CI's
+* `delivery.previewCheck` uses the two halves separately instead.
+*/
+async function runMonitoringCheck(input) {
+	return reportChecks({
+		checks: await resolveMonitoringChecks({
+			loaded: input.loaded,
+			context: input.context,
+			loader: input.loader
+		}),
+		url: input.url,
+		...input.headers ? { headers: input.headers } : {},
+		...input.print ? { print: input.print } : {},
+		...input.logger ? { logger: input.logger } : {},
+		...input.runCheck ? { runCheck: input.runCheck } : {}
+	});
+}
+//#endregion
+//#region src/commands/monitoring-resolve-checks/monitoring-resolve-checks.ts
+/**
+* `holocron monitoring resolve-checks` — loads config/plugins and writes
+* the configured `monitoring` checks to a file as JSON (holocron#1030/
+* #1032 review).
+*
+* The untrusted half of the `delivery.previewCheck` split: this process
+* executes a PR's own `holocron.config.ts`, so it must never run with a
+* credential worth protecting (e.g. a Deployment Protection bypass
+* secret) present in its environment. `monitoring run-resolved` is the
+* trusted half — it reads this command's output file and performs the
+* actual authenticated request, with no config loading at all.
+*/
+async function runMonitoringResolveChecks(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const checks = await resolveMonitoringChecks({
+		loaded: input.loaded,
+		context: input.context,
+		loader: input.loader
+	});
+	await writeFile(input.outFile, JSON.stringify(checks), "utf8");
+	print(`Resolved ${checks.length} monitoring check(s) → ${input.outFile}`);
+}
+//#endregion
+//#region src/commands/monitoring-run-resolved/monitoring-run-resolved.ts
+/**
+* `holocron monitoring run-resolved <url>` — runs an already-resolved
+* check list (no `holocron.config.ts` loading at all) against `url`
+* (holocron#1030/#1032 review).
+*
+* The trusted half of the `delivery.previewCheck` split, paired with
+* `monitoring resolve-checks` (the untrusted half, which loads config).
+* Safe to run with a credential present, since nothing here executes
+* PR-authored code — but a credential is only ever attached after
+* `verifyVercelDeploymentProject` confirms `url` actually belongs to
+* `vercelProject`: a URL merely ending in `.vercel.app` proves nothing,
+* since anyone can register their own Vercel project (sourcery review
+* on holocron#1032). No `vercelProject` given at all → the credential
+* is never attached, regardless of whether one is configured.
+*/
+/**
+* The shared gate every caller that might attach the Deployment
+* Protection bypass header goes through — `monitoring check`'s direct
+* CLI invocation included (sourcery review on holocron#1032 called this
+* out explicitly: verifying only in `delivery.previewCheck`'s own split
+* commands and not here would leave the exact same unverified-host
+* problem reachable by hand). No `vercelProject` → never attach
+* anything, regardless of whether a `bypassSecret` happens to be
+* configured. `vercelProject` given but verification fails or no token
+* is available → `undefined` AND a printed reason, never a thrown
+* error — callers decide for themselves whether that's fatal.
+*/
+async function resolveVercelBypassHeaders(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	if (!input.vercelProject) return { verified: true };
+	if (!input.vercelToken) {
+		print(`✗ --vercel-project was given but no Vercel token is available to verify deployment ownership`);
+		return { verified: false };
+	}
+	if (!await (input.verify ?? verifyVercelDeploymentProject)(input.url, input.vercelProject, input.vercelToken, { ...input.vercelTeamId ? { teamId: input.vercelTeamId } : {} })) {
+		print(`✗ ${input.url} does not resolve to a deployment of Vercel project "${input.vercelProject}" — refusing to attach the Deployment Protection bypass credential or run checks against an unverified URL`);
+		return { verified: false };
+	}
+	return input.bypassSecret ? {
+		verified: true,
+		headers: { "x-vercel-protection-bypass": input.bypassSecret }
+	} : { verified: true };
+}
+async function runMonitoringRunResolved(input) {
+	const { headers, verified } = await resolveVercelBypassHeaders(input);
+	if (!verified) return {
+		status: "fail",
+		checks: []
+	};
+	return reportChecks({
+		checks: input.checks,
+		url: input.url,
+		...headers ? { headers } : {},
+		...input.print ? { print: input.print } : {},
+		...input.logger ? { logger: input.logger } : {},
+		...input.runCheck ? { runCheck: input.runCheck } : {}
+	});
+}
 //#endregion
 //#region src/commands/new/new.ts
 /**
@@ -10111,12 +10298,22 @@ try {
 	}).command("monitoring", "Run monitoring checks ad hoc, outside the configured provider", (g) => g.command("check <url>", "Run every configured `monitoring` check against a given URL instead of its own configured url", (y) => y.positional("url", {
 		type: "string",
 		describe: "URL to test every configured check against (e.g. a PR's preview deployment)"
+	}).option("vercel-project", {
+		type: "string",
+		describe: "Expected Vercel project id/name `url` must resolve to before the Deployment Protection bypass header (VERCEL_PROTECTION_BYPASS_SECRET) is attached. Omitted → the header is never attached, regardless of that env var."
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
 		const [url] = await promptForPositionals(getEntry("monitoring check"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
+		const { headers } = await resolveVercelBypassHeaders({
+			url,
+			...argv.vercelProject ? { vercelProject: argv.vercelProject } : {},
+			...process.env["VERCEL_TOKEN"] ? { vercelToken: process.env["VERCEL_TOKEN"] } : {},
+			...process.env["VERCEL_TEAM_ID"] ? { vercelTeamId: process.env["VERCEL_TEAM_ID"] } : {},
+			...process.env["VERCEL_PROTECTION_BYPASS_SECRET"] ? { bypassSecret: process.env["VERCEL_PROTECTION_BYPASS_SECRET"] } : {}
+		});
 		if ((await runMonitoringCheck({
 			loaded,
 			context: {
@@ -10125,7 +10322,46 @@ try {
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			url
+			url,
+			...headers ? { headers } : {}
+		})).status === "fail") process.exitCode = 1;
+	}).command("resolve-checks", "Load config/plugins and write the configured `monitoring` checks to a file as JSON — the untrusted half of the delivery.previewCheck split (holocron#1030/#1032)", (y) => y.option("out", {
+		type: "string",
+		demandOption: true,
+		describe: "File path to write the resolved checks to"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		await runMonitoringResolveChecks({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			outFile: argv.out
+		});
+	}).command("run-resolved <url>", "Run an already-resolved check list (from `monitoring resolve-checks`) against a URL — no config/plugin loading at all, the trusted half of the delivery.previewCheck split (holocron#1030/#1032)", (y) => y.positional("url", {
+		type: "string",
+		describe: "URL to run every resolved check against"
+	}).option("checks-file", {
+		type: "string",
+		demandOption: true,
+		describe: "File path to read the resolved checks from (written by `monitoring resolve-checks`)"
+	}).option("vercel-project", {
+		type: "string",
+		describe: "Expected Vercel project id/name `url` must resolve to before the Deployment Protection bypass header (VERCEL_PROTECTION_BYPASS_SECRET) is attached. Omitted → the header is never attached."
+	}), async (argv) => {
+		if ((await runMonitoringRunResolved({
+			checks: JSON.parse(readFileSync(argv.checksFile, "utf8")),
+			url: argv.url,
+			...argv.vercelProject ? { vercelProject: argv.vercelProject } : {},
+			...process.env["VERCEL_TOKEN"] ? { vercelToken: process.env["VERCEL_TOKEN"] } : {},
+			...process.env["VERCEL_TEAM_ID"] ? { vercelTeamId: process.env["VERCEL_TEAM_ID"] } : {},
+			...process.env["VERCEL_PROTECTION_BYPASS_SECRET"] ? { bypassSecret: process.env["VERCEL_PROTECTION_BYPASS_SECRET"] } : {}
 		})).status === "fail") process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
 		await launchGroupMenu("monitoring", argv);