@theholocron/cli 5.0.0-alpha.184 → 5.0.0-alpha.186

package/dist/cli.mjs

@@ -26,7 +26,7 @@ import ora from "ora";
 import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-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 { createHash, randomBytes, randomUUID } from "node:crypto";
 import { generateReadme } from "@theholocron/components-doc/markdown";
 import { getClients, getConfigs, getDocs, getPlugins, getSkills, getThemes, getUtils } from "@theholocron/registry-doc";
 import { createGitHubClient } from "@theholocron/github-client";
@@ -2396,6 +2396,43 @@ async function runDeployFromFiles(input) {
 	}
 }
 //#endregion
+//#region src/ui/provider-error/provider-error.ts
+/** Vendor response bodies land in the terminal — cap their length so one
+*  oversized error can't flood the report, and strip control characters
+*  (newlines and the C1 range, whose 0x9b is an 8-bit CSI) so a crafted body
+*  can't forge extra report lines or inject terminal escape sequences. */
+const MAX_DETAIL_LENGTH = 200;
+function sanitizeDetail(text) {
+	const stripped = text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
+	return stripped.length > MAX_DETAIL_LENGTH ? `${stripped.slice(0, MAX_DETAIL_LENGTH)}…` : stripped;
+}
+/**
+* `errorMessage(err)` alone is just `"<Vendor> <METHOD> <path> → <status>"` —
+* the actual reason (what the vendor's response body said) lives in
+* `ProviderApiError.details`, a raw response-body string (not parsed JSON —
+* see AGENTS.md), and was being silently dropped. Appending it (sanitized
+* and length-capped — see `sanitizeDetail`) turns e.g. a bare "→ 403" into
+* something that actually explains itself, without the vendor text being
+* able to overwhelm or manipulate the terminal.
+*/
+function describeProviderError(err) {
+	if (err instanceof ProviderApiError$1 && err.details) {
+		const detail = sanitizeDetail(String(err.details));
+		if (detail) return `${errorMessage(err)}: ${detail}`;
+	}
+	return errorMessage(err);
+}
+/**
+* What to put in structured logs: the plain message of the underlying error,
+* with no response body. The detail {@link describeProviderError} adds is for the
+* person at the terminal; a provider's raw body has no business in telemetry.
+* Wrapper errors carry the original as `cause`, so look through one level.
+*/
+function logReason(err) {
+	const root = err instanceof Error && err.cause !== void 0 ? err.cause : err;
+	return errorMessage(root);
+}
+//#endregion
 //#region src/commands/doctor/doctor.ts
 /**
 * `holocron doctor` — load the config, instantiate every capability,
@@ -2493,45 +2530,17 @@ async function smokeCheck(key, provider, impl) {
 	try {
 		return await withTimeout(runSmokeCheck(key, provider, impl), SMOKE_CHECK_TIMEOUT_MS);
 	} catch (err) {
-		return mk(key, provider, "fail", smokeCheckErrorMessage(err), errorMessage(err));
-	}
-}
-/** Vendor response bodies land in the terminal — cap their length so one
-*  oversized error can't flood the report, and strip control characters
-*  (newlines and the C1 range, whose 0x9b is an 8-bit CSI) so a crafted body
-*  can't forge extra report lines or inject terminal escape sequences. */
-const MAX_DETAIL_LENGTH = 200;
-function sanitizeDetail(text) {
-	const stripped = text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
-	return stripped.length > MAX_DETAIL_LENGTH ? `${stripped.slice(0, MAX_DETAIL_LENGTH)}…` : stripped;
-}
-/**
-* `errorMessage(err)` alone is just `"<Vendor> <METHOD> <path> → <status>"` —
-* the actual reason (what the vendor's response body said) lives in
-* `ProviderApiError.details`, a raw response-body string (not parsed JSON —
-* see AGENTS.md), and was being silently dropped. Appending it (sanitized
-* and length-capped — see `sanitizeDetail`) turns e.g. a bare "→ 400" into
-* something that actually explains itself, without the vendor text being
-* able to overwhelm or manipulate the terminal report.
-*/
-function smokeCheckErrorMessage(err) {
-	if (err instanceof ProviderApiError$1 && err.details) {
-		const detail = sanitizeDetail(String(err.details));
-		if (detail) return `${errorMessage(err)}: ${detail}`;
+		return mk(key, provider, "fail", describeProviderError(err), errorMessage(err));
 	}
-	return errorMessage(err);
 }
 async function runSmokeCheck(key, provider, impl) {
 	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 "issues": return mk(key, provider, "ok", describeLifecycle(await impl.doctor()));
 		case "secrets": return mk(key, provider, "ok", `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})`);
+			return mk(key, provider, "ok", runs.length === 0 ? "runs: none recent" : `most recent: ${runs[0].workflowName} (${runs[0].status})`);
 		}
 		case "vault": return mk(key, provider, "ok", `keys: ${(await impl.list()).length} visible`);
 		case "deployment": return mk(key, provider, "ok", `projects: ${(await impl.listProjects()).length} visible`);
@@ -2577,7 +2586,7 @@ async function runSmokeCheck(key, provider, impl) {
 			const monitoring = impl;
 			if (monitoring.whoami) {
 				const who = await monitoring.whoami();
-				return mk(key, provider, who.ok ? "ok" : "fail", who.ok ? "token verified" : "token check failed");
+				return mk(key, provider, who.ok ? "ok" : "fail", who.ok ? "token: verified" : "token: check failed");
 			}
 			return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
 		}
@@ -2591,15 +2600,23 @@ async function runSmokeCheck(key, provider, impl) {
 			const wiki = impl;
 			if (wiki.whoami) {
 				const who = await wiki.whoami();
-				return mk(key, provider, who.ok ? "ok" : "fail", who.ok ? "token configured" : "token not configured");
+				return mk(key, provider, who.ok ? "ok" : "fail", who.ok ? "token: configured" : "token: not configured");
 			}
 			return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
 		}
 		default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
 	}
 }
-function countResolvedLifecycle(report) {
-	return `${report.lifecycle.filter((l) => l.resolved).length}/${report.lifecycle.length} lifecycle slots ready`;
+/**
+* What the issues row says: how many lifecycle slots (inProgress, inReview, done)
+* map to something the tracker recognises, and which do not. The token's user and
+* the repo are not repeated -- `source` already names the account, and a slot
+* that is not configured is the part someone has to act on.
+*/
+function describeLifecycle(report) {
+	const unresolved = report.lifecycle.filter((l) => !l.resolved).map((l) => l.slot);
+	const base = `lifecycle: ${report.lifecycle.length - unresolved.length}/${report.lifecycle.length} slots ready`;
+	return unresolved.length > 0 ? `${base} (unresolved: ${unresolved.join(", ")})` : base;
 }
 function mk(capability, provider, status, message, logMessage) {
 	return {
@@ -3232,6 +3249,33 @@ async function runNew(input) {
 function defaultSecretName(channel) {
 	return `HOLOCRON_NOTIFY_WEBHOOK_${channel.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
 }
+/**
+* Prefix of the throwaway secret the preflight writes and removes. Every run adds a
+* random suffix, so it can never overwrite (and then delete) a secret someone already
+* has; layouts may not use any name under this prefix for their own secrets.
+*/
+const PREFLIGHT_PREFIX = "HOLOCRON_NOTIFY_PREFLIGHT";
+/** Whether a secret name is under the preflight's reserved prefix. GitHub secret names are case-insensitive. */
+function isReservedSecret(name) {
+	return name.toUpperCase().startsWith(PREFLIGHT_PREFIX);
+}
+/**
+* Prove the secrets store can be WRITTEN before creating anything that needs it.
+* A webhook's URL is shown once; creating the webhook and then failing to store
+* it leaves an orphan the user has to delete by hand. Listing is not enough --
+* a token can read secrets it cannot write -- so write a throwaway secret and
+* remove it.
+*/
+async function assertSecretsReachable(secrets, scope) {
+	const probe = `${PREFLIGHT_PREFIX}_${randomBytes(4).toString("hex").toUpperCase()}`;
+	try {
+		await secrets.setSecret(scope, probe, "ok");
+		await secrets.deleteSecret(scope, probe);
+	} catch (err) {
+		const where = scope.kind === "organization" ? `organization ${scope.name}` : scope.kind;
+		throw new Error(`cannot write to the secrets store for ${where} (${describeProviderError(err)}) — fix that token before creating webhooks. If a secret named ${probe} was left behind, delete it`, { cause: err });
+	}
+}
 /** Why a capability is not loaded: the plugin's own load error when there is one (e.g. a missing token). */
 function whyMissing(loader, key, fallback) {
 	const failure = loader.loadFailures().find((f) => f.key === key);
@@ -3259,6 +3303,7 @@ async function provisionChannel(deps, spec) {
 	const where = spec.category ? ` in ${spec.category}` : "";
 	if (!notifications.ensureChannel) throw new Error(`\`${notifications.providerName}\` cannot create channels`);
 	if (webhookCfg && !notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
+	if (webhookCfg && isReservedSecret(secretName)) throw new Error(`secret name ${secretName} is reserved for the setup preflight -- choose another`);
 	if (webhookCfg && !dryRun && !secrets) throw new Error("storing a webhook URL needs a `secrets` provider — add one to holocron.config.ts");
 	if (dryRun) {
 		print(`  … would ensure channel ${spec.name}${where}`);
@@ -3290,7 +3335,7 @@ async function provisionChannel(deps, spec) {
 		try {
 			await secrets.setSecret(scope, secretName, hook.url);
 		} catch (err) {
-			throw new Error(`webhook ${webhookName} was ${hook.created ? "created" : "found"} but storing its URL in ${secretName} failed (${errorMessage(err)}) — delete the webhook in the provider and re-run to get a fresh URL`, { cause: err });
+			throw new Error(`webhook ${webhookName} was ${hook.created ? "created" : "found"} but storing its URL in ${secretName} failed (${describeProviderError(err)}) — delete the webhook in the provider and re-run to get a fresh URL`, { cause: err });
 		}
 		print(`  ✓ ${hook.created ? "created" : "found  "} webhook ${webhookName}; URL stored in ${secretName}`);
 		outcome.webhook = {
@@ -3334,6 +3379,7 @@ async function runNotificationsChannelAdd(input) {
 			name: org
 		} : void 0);
 		if (input.withWebhook && !scope && !dryRun) throw new Error("no org to store the webhook secret under — pass --scope or set `org` in holocron.config.ts");
+		if (secrets && scope && !dryRun) await assertSecretsReachable(secrets, scope);
 		const channel = await provisionChannel({
 			notifications,
 			...secrets ? { secrets } : {},
@@ -3369,11 +3415,11 @@ async function runNotificationsChannelAdd(input) {
 			channel
 		};
 	} catch (err) {
-		const message = errorMessage(err);
+		const message = describeProviderError(err);
 		print(`  ✗ ${message}`);
 		logger.warn({
 			channel: input.name,
-			reason: message
+			reason: logReason(err)
 		}, `notifications channel add: ${input.name}`);
 		return {
 			status: "fail",
@@ -3410,9 +3456,9 @@ async function runNotificationsSetup(input) {
 		roles: [],
 		failures: []
 	};
-	const refuse = (message) => {
+	const refuse = (message, reason = message) => {
 		print(`  ✗ ${message}`);
-		logger.warn({ reason: message }, "notifications setup");
+		logger.warn({ reason }, "notifications setup");
 		return {
 			...report,
 			status: "fail",
@@ -3427,10 +3473,10 @@ async function runNotificationsSetup(input) {
 	}
 	const layout = notifications.layout;
 	if (!layout) return refuse(`the \`${notifications.providerName}\` provider declares no layout — add \`layout\` to its options in holocron.config.ts`);
-	const wantsWebhook = (layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.webhook));
+	const wantsSecrets = (layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.webhook)) || (layout.roles ?? []).some((r) => r.secret);
 	let secrets;
-	if (wantsWebhook && !dryRun) {
-		if (!loader.has("secrets")) return refuse(whyMissing(loader, "secrets", "the layout asks for webhooks, which need a `secrets` capability — add a `secrets` provider"));
+	if (wantsSecrets && !dryRun) {
+		if (!loader.has("secrets")) return refuse(whyMissing(loader, "secrets", "the layout stores webhook URLs or role ids, which need a `secrets` capability — add a `secrets` provider"));
 		secrets = loader.get("secrets");
 	}
 	const org = input.context.org;
@@ -3438,21 +3484,36 @@ async function runNotificationsSetup(input) {
 		kind: "organization",
 		name: org
 	} : void 0);
-	if (wantsWebhook && !scope && !dryRun) return refuse("no org to store webhook secrets under — pass --scope or set `org` in holocron.config.ts");
+	if (wantsSecrets && !scope && !dryRun) return refuse("no org to store secrets under — pass --scope or set `org` in holocron.config.ts");
+	if (secrets && scope && !dryRun) try {
+		await assertSecretsReachable(secrets, scope);
+	} catch (err) {
+		return refuse(errorMessage(err), logReason(err));
+	}
 	const taken = /* @__PURE__ */ new Map();
+	const claim = (secret, owner, hint) => {
+		if (isReservedSecret(secret)) return `${owner} would store into ${secret}, a name reserved for the setup preflight — choose another`;
+		const key = secret.toUpperCase();
+		const other = taken.get(key);
+		if (other) return `${other} and ${owner} would both store into ${secret} — ${hint}`;
+		taken.set(key, owner);
+	};
 	for (const category of layout.categories ?? []) for (const channel of category.channels ?? []) {
 		if (!channel.webhook) continue;
-		const secret = channel.webhook !== true && channel.webhook.secret || defaultSecretName(channel.name);
-		const other = taken.get(secret);
-		if (other) return refuse(`channels \`${other}\` and \`${channel.name}\` would both store their webhook in ${secret} — give one a distinct \`webhook.secret\``);
-		taken.set(secret, channel.name);
+		const clash = claim(channel.webhook !== true && channel.webhook.secret || defaultSecretName(channel.name), `channel \`${channel.name}\``, "give one a distinct `webhook.secret`");
+		if (clash) return refuse(clash);
+	}
+	for (const role of layout.roles ?? []) {
+		if (!role.secret) continue;
+		const clash = claim(role.secret, `role \`${role.name}\``, "give one a distinct secret");
+		if (clash) return refuse(clash);
 	}
 	print(`Holocron notifications setup — ${notifications.providerName}${dryRun ? " (dry-run)" : ""}`);
 	const attempt = async (step, fn) => {
 		try {
 			await fn();
 		} catch (err) {
-			const message = errorMessage(err);
+			const message = describeProviderError(err);
 			print(`  ✗ ${step}: ${message}`);
 			report.failures.push({
 				step,
@@ -3496,10 +3557,11 @@ async function runNotificationsSetup(input) {
 	for (const role of layout.roles ?? []) await attempt(`role ${role.name}`, async () => {
 		if (!notifications.ensureRole) throw new Error(`\`${notifications.providerName}\` cannot manage roles`);
 		if (dryRun) {
-			print(`  … would ensure role ${role.name}`);
+			print(`  … would ensure role ${role.name}${role.secret ? ` and store its id in ${role.secret}` : ""}`);
 			report.roles.push({
 				name: role.name,
-				created: false
+				created: false,
+				...role.secret ? { secret: role.secret } : {}
 			});
 			return;
 		}
@@ -3514,6 +3576,12 @@ async function runNotificationsSetup(input) {
 		};
 		report.roles.push(outcome);
 		print(`  ${made.created ? "✓ created" : "· exists "} role ${role.name} (id ${made.id})`);
+		if (role.secret) {
+			await secrets.setSecret(scope, role.secret, made.id);
+			outcome.secret = role.secret;
+			outcome.stored = true;
+			print(`  ✓ stored the id of ${role.name} in ${role.secret}`);
+		}
 	});
 	if (report.failures.length > 0) {
 		report.status = "fail";