@theholocron/cli 5.0.0-alpha.141 → 5.0.0-alpha.142

package/README.md

@@ -347,8 +347,8 @@ release) is on the task's `channel` (default `main`, the stable release) and cha
 `workspace:*` dependencies between `--from` (the previous release's commit,
 omitted when there is none) and `--to` (default `HEAD`). It waits for npm to
 serve the release's new dependency versions, then runs `pnpm --filter <pkg>
-delivery.deploy`. A package that doesn't apply is skipped; a failed deploy
-exits non-zero. The shared `delivery.publish` workflow runs it as its own
+delivery.deploy`. A package that doesn't apply is skipped; a deploy that
+doesn't succeed exits non-zero. The shared `delivery.publish` workflow runs it as its own
 `deploy` job after the release job (opt in with `deploy-on-release: true`).
 
 ### `holocron run ci`
@@ -385,6 +385,29 @@ Provider plugins support this through the `Deployment` capability's
 existing `getDeployment(id)`. They should set `errorMessage` on the
 returned `DeploymentRecord` whenever the provider exposes one.
 
+### `holocron monitoring check <url>`
+
+Runs every configured `monitoring` check against `<url>` instead of each
+check's own configured `url` — no vendor API call, only a plain HTTP
+request evaluated locally against the exact same `assertions` already in
+`holocron.config.ts`. Built for CI: the `delivery.previewCheck` task runs
+this against a PR's Vercel preview deployment (triggered by
+`deployment_status`, not `push`/`pull_request`), reusing the production
+check definitions to catch a breaking change before merge instead of
+after (holocron#1010).
+
+```ts
+export default defineConfig({
+  tasks: ["delivery.previewCheck"],
+  providers: {
+    monitoring: ["checkly", { accountId: "...", checks: [/* ... */] }],
+  },
+});
+```
+
+Exits non-zero if any check fails — the job's own pass/fail is what
+posts as the GitHub check, no separate reporting step needed.
+
 ### Lint parity
 
 The `lint` task takes an optional `linters` array — one list that drives
@@ -624,9 +647,10 @@ the local override exists to exempt.
   reusable `workflow_call` implementations + composite actions from
   `astromech.reusableTemplates()` to `theholocron/.github` (a pure sync target —
   never hand-edit its `.github/workflows/*`).
-- `src/commands/` — `repo setup`, `repo sync`, `doctor`, `deploy`, `secrets set`,
-  `secrets sync`, `package publish`, `package bump-versions`, `sync github`,
-  `repo upgrade node`, `repo upgrade deps`, `new plugin`, `auth`
+- `src/commands/` — `repo setup`, `repo sync`, `doctor`, `deploy`,
+  `monitoring check`, `secrets set`, `secrets sync`, `package publish`,
+  `package bump-versions`, `sync github`, `repo upgrade node`,
+  `repo upgrade deps`, `new plugin`, `auth`
 - `src/interactive-menu.ts` — the interactive fallback: `COMMAND_REGISTRY`,
   `launchMenu` (Layers 1–2, picks + spawns a fresh `holocron <command>`),
   `promptForPositionals` (Layer 3, called inline from each leaf command's

package/dist/cli.mjs

@@ -343,6 +343,7 @@ const COMMAND_CONTEXTS = {
 	"secrets sync": "workspace",
 	deploy: "workspace",
 	"deploy cleanup-preview": "workspace",
+	"monitoring check": "workspace",
 	"repo sync": "workspace",
 	"sync github": "workspace"
 };
@@ -1820,6 +1821,171 @@ function mk(capability, provider, status, message) {
 	};
 }
 //#endregion
+//#region src/plugin/run-check.ts
+async function runCheckAgainstUrl(input, opts = {}) {
+	const doFetch = opts.fetch ?? fetch;
+	const url = resolveUrl(input.url, opts.url);
+	const method = input.method ?? "GET";
+	const hasBody = input.body !== void 0 && method !== "GET" && method !== "HEAD";
+	const needsBody = (input.assertions ?? []).some((a) => a.source === "body");
+	const start = Date.now();
+	let response;
+	let bodyText = "";
+	try {
+		response = await doFetch(url, {
+			method,
+			...hasBody ? { body: input.body } : {},
+			redirect: "manual",
+			signal: AbortSignal.timeout(opts.timeoutMs ?? 1e4)
+		});
+		if (needsBody) bodyText = await readBodyCapped(response, opts.maxBodyBytes ?? 1e6);
+	} catch (err) {
+		return {
+			passed: false,
+			failures: [],
+			requestError: requestErrorMessage(err)
+		};
+	}
+	const responseTimeMs = Date.now() - start;
+	const failures = [];
+	if (!input.shouldFail && response.status >= 400) failures.push(`HTTP ${response.status} (>= 400 counts as a failure unless \`shouldFail\` is set)`);
+	for (const assertion of input.assertions ?? []) {
+		const actual = extractActual(assertion, {
+			response,
+			bodyText,
+			responseTimeMs
+		});
+		if (!evaluate(assertion.comparison, actual, assertion.target)) failures.push(`${assertion.source} ${assertion.comparison} "${assertion.target ?? ""}" — got "${truncate(actual)}"`);
+	}
+	return {
+		passed: failures.length === 0,
+		status: response.status,
+		responseTimeMs,
+		failures
+	};
+}
+/** Swaps in `overrideUrl`'s origin, keeping `originalUrl`'s own path + query. */
+function resolveUrl(originalUrl, overrideUrl) {
+	if (!overrideUrl) return originalUrl;
+	const original = new URL(originalUrl);
+	const resolved = new URL(overrideUrl);
+	resolved.pathname = original.pathname;
+	resolved.search = original.search;
+	return resolved.toString();
+}
+function requestErrorMessage(err) {
+	if (err instanceof Error) return err.name === "TimeoutError" ? `request timed out: ${err.message}` : err.message;
+	return String(err);
+}
+/** Reads up to `maxBytes` of the response body, discarding the rest — a large/unending body can't exhaust memory. */
+async function readBodyCapped(response, maxBytes) {
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			const remaining = maxBytes - total;
+			if (remaining <= 0) break;
+			const stored = value.length > remaining ? value.slice(0, remaining) : value;
+			chunks.push(stored);
+			total += stored.length;
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8");
+}
+/** Keeps a failure message readable when `actual` is a full HTML/JSON response body. */
+function truncate(value, max = 200) {
+	return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+function extractActual(assertion, ctx) {
+	switch (assertion.source) {
+		case "status_code": return String(ctx.response.status);
+		case "response_time": return String(ctx.responseTimeMs);
+		case "body": return ctx.bodyText;
+		case "header": {
+			const name = assertion.property ?? "";
+			return name ? ctx.response.headers.get(name) ?? "" : "";
+		}
+	}
+}
+function evaluate(comparison, actual, target) {
+	const t = target ?? "";
+	switch (comparison) {
+		case "equals": return actual === t;
+		case "not_equals": return actual !== t;
+		case "contains": return actual.includes(t);
+		case "not_contains": return !actual.includes(t);
+		case "greater_than": return Number(actual) > Number(t);
+		case "less_than": return Number(actual) < Number(t);
+	}
+}
+//#endregion
+//#region src/commands/monitoring-check.ts
+async function runMonitoringCheck(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "monitoring check");
+	const monitoring = loader.get("monitoring");
+	const run = input.runCheck ?? runCheckAgainstUrl;
+	print(`Holocron monitoring check — against ${input.url}`);
+	if (monitoring.checks.length === 0) {
+		print(`✗ no monitoring checks configured — nothing to validate`);
+		logger.warn({ url: input.url }, "monitoring check: no checks configured");
+		return {
+			status: "fail",
+			checks: []
+		};
+	}
+	const checks = [];
+	for (const checkInput of monitoring.checks) {
+		const result = await run(checkInput, { url: input.url });
+		if (result.requestError) {
+			print(`  ✗ ${checkInput.name}  (request failed: ${result.requestError})`);
+			checks.push({
+				name: checkInput.name,
+				passed: false,
+				failures: [],
+				requestError: result.requestError
+			});
+		} else if (result.passed) {
+			print(`  ✓ ${checkInput.name}`);
+			checks.push({
+				name: checkInput.name,
+				passed: true,
+				failures: []
+			});
+		} else {
+			print(`  ✗ ${checkInput.name}`);
+			for (const failure of result.failures) print(`      ${failure}`);
+			checks.push({
+				name: checkInput.name,
+				passed: false,
+				failures: result.failures
+			});
+		}
+	}
+	const failCount = checks.filter((c) => !c.passed).length;
+	const status = failCount === 0 ? "ok" : "fail";
+	print(`${status === "ok" ? "✓" : "✗"} ${checks.length - failCount} passed, ${failCount} failed`);
+	logger.info({
+		url: input.url,
+		total: checks.length,
+		failed: failCount,
+		status
+	}, "monitoring check: done");
+	return {
+		status,
+		checks
+	};
+}
+//#endregion
 //#region src/commands/new.ts
 /**
 * `holocron new repo <type> <name>` — create a GitHub repo from a template and
@@ -8417,6 +8583,16 @@ const COMMAND_REGISTRY = [
 		positionals: [],
 		supportsDryRun: true
 	},
+	{
+		name: "monitoring check",
+		description: "Run every configured `monitoring` check against a given URL instead of its own configured url",
+		positionals: [{
+			key: "url",
+			message: "URL to test against:",
+			type: "input"
+		}],
+		supportsDryRun: false
+	},
 	{
 		name: "package bump-versions",
 		description: "Bump all non-private package versions in lockstep (semantic-release prepareCmd)",
@@ -10229,7 +10405,28 @@ try {
 			branch,
 			...argv.target ? { target: argv.target } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).strict().help().epilogue(`Execution contexts:
+	}).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)"
+	}), 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);
+		if ((await runMonitoringCheck({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			url
+		})).status === "fail") process.exitCode = 1;
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("monitoring", argv);
+	}), () => {}).strict().help().epilogue(`Execution contexts:
   global      works from a bare 'npm i -g': ${commandsInContext("global").join(", ")}\n  repo-aware  needs ./holocron.config in cwd: ${commandsInContext("repo-aware").join(", ")}\n  workspace   also needs the plugin packages: ${commandsInContext("workspace").join(", ")}\n  https://theholocron.github.io/holocron/execution-contexts`).fail((msg, err) => {
 		if (err instanceof Error && USER_FACING_ERRORS.has(err.name)) {
 			captureException(err);