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

package/dist/cli.mjs

@@ -409,6 +409,7 @@ const COMMAND_CONTEXTS = {
 	"secrets sync": "workspace",
 	"notifications channel add": "workspace",
 	"notifications setup": "workspace",
+	"notifications verify": "workspace",
 	deploy: "workspace",
 	"deploy cleanup-preview": "workspace",
 	"monitoring check": "workspace",
@@ -2402,8 +2403,12 @@ async function runDeployFromFiles(input) {
 *  (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;
+/** Control characters (newlines and the C1 range included) turned into spaces, whitespace collapsed, no length cap. */
+function stripControl(text) {
+	return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
+}
 function sanitizeDetail(text) {
-	const stripped = text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
+	const stripped = stripControl(text);
 	return stripped.length > MAX_DETAIL_LENGTH ? `${stripped.slice(0, MAX_DETAIL_LENGTH)}…` : stripped;
 }
 /**
@@ -2416,11 +2421,12 @@ function sanitizeDetail(text) {
 * able to overwhelm or manipulate the terminal.
 */
 function describeProviderError(err) {
+	const base = stripControl(errorMessage(err));
 	if (err instanceof ProviderApiError$1 && err.details) {
 		const detail = sanitizeDetail(String(err.details));
-		if (detail) return `${errorMessage(err)}: ${detail}`;
+		if (detail) return `${base}: ${detail}`;
 	}
-	return errorMessage(err);
+	return base;
 }
 /**
 * What to put in structured logs: the plain message of the underlying error,
@@ -3279,21 +3285,66 @@ async function assertSecretsReachable(secrets, scope) {
 /** 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);
-	return failure ? `${fallback} (\`${failure.provider}\` failed to load: ${failure.error.message})` : fallback;
+	return failure ? `${fallback} (\`${failure.provider}\` failed to load: ${describeProviderError(failure.error)})` : fallback;
 }
-/** Pick the provider that can provision; with several, `--provider` decides. */
-function pickProvisioner(providers, wanted) {
-	const capable = providers.filter((p) => typeof p.ensureChannel === "function" || typeof p.ensureCategory === "function" || typeof p.ensureRole === "function");
-	if (capable.length === 0) throw new Error("no `notifications` provider can provision — add one that implements it (for example discord) to holocron.config.ts");
+/** The configured `notifications` providers, or an error that says why there are none (including a plugin that failed to load). */
+function notificationProviders(loader) {
+	const providers = loader.has("notifications") ? loader.get("notifications") : [];
+	if (providers.length === 0) throw new Error(whyMissing(loader, "notifications", "no `notifications` provider is available — add one to holocron.config.ts"));
+	return providers;
+}
+/**
+* Pick the provider that can do what the command needs; with several, `--provider`
+* decides. `can` says what "able" means (a command that only reads needs `inspect`, not
+* provisioning), and `verb` words the errors.
+*/
+function pickProvider(providers, wanted, can, verb) {
+	const capable = providers.filter(can);
+	if (capable.length === 0) throw new Error(`no \`notifications\` provider can ${verb.infinitive} — add one that implements it (for example discord) to holocron.config.ts`);
 	if (wanted) {
 		const match = capable.find((p) => p.providerName === wanted);
-		if (!match) throw new Error(`no provisioning \`notifications\` provider named \`${wanted}\` (have: ${names(capable)})`);
+		if (!match) throw new Error(`no ${verb.gerund} \`notifications\` provider named \`${wanted}\` (have: ${names(capable)})`);
 		return match;
 	}
-	if (capable.length > 1) throw new Error(`several \`notifications\` providers can provision (${names(capable)}) — pass --provider <name>`);
+	if (capable.length > 1) throw new Error(`several \`notifications\` providers can ${verb.infinitive} (${names(capable)}) — pass --provider <name>`);
 	return capable[0];
 }
+/** Pick the provider that can provision. Any ensure* method counts: a role-only layout needs no channel support. */
+function pickProvisioner(providers, wanted) {
+	return pickProvider(providers, wanted, (p) => typeof p.ensureChannel === "function" || typeof p.ensureCategory === "function" || typeof p.ensureRole === "function", {
+		infinitive: "provision",
+		gerund: "provisioning"
+	});
+}
 const names = (ps) => ps.map((p) => p.providerName).join(", ");
+/**
+* The first reason the layout's secret names cannot work, or undefined. Two things
+* cannot share one secret: the second write would overwrite the first and callers
+* would read the wrong value. Punctuation normalising (release-notes vs
+* release_notes) makes that easy to hit by accident, GitHub secret names are
+* case-insensitive, and the preflight's own prefix is reserved. Shared by `setup`
+* (which refuses) and `verify` (which reports it).
+*/
+function layoutSecretProblem(layout) {
+	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 clash = claim(channel.webhook !== true && channel.webhook.secret || defaultSecretName(channel.name), `channel \`${channel.name}\``, "give one a distinct `webhook.secret`");
+		if (clash) return 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 clash;
+	}
+}
 /** Ensure one channel and, if asked, its webhook + secret. Shared with `notifications setup`. */
 async function provisionChannel(deps, spec) {
 	const { notifications, secrets, scope, dryRun, print } = deps;
@@ -3367,7 +3418,7 @@ async function runNotificationsChannelAdd(input) {
 	const dryRun = input.context.dryRun ?? false;
 	print(`Holocron notifications channel add — ${input.name}${dryRun ? " (dry-run)" : ""}`);
 	try {
-		const notifications = pickProvisioner(loader.has("notifications") ? loader.get("notifications") : [], input.provider);
+		const notifications = pickProvisioner(notificationProviders(loader), input.provider);
 		let secrets;
 		if (input.withWebhook && !dryRun) {
 			if (!loader.has("secrets")) throw new Error(whyMissing(loader, "secrets", "`--with-webhook` needs a `secrets` capability — add a `secrets` provider to holocron.config.ts"));
@@ -3467,7 +3518,7 @@ async function runNotificationsSetup(input) {
 	};
 	let notifications;
 	try {
-		notifications = pickProvisioner(loader.has("notifications") ? loader.get("notifications") : [], input.provider);
+		notifications = pickProvisioner(notificationProviders(loader), input.provider);
 	} catch (err) {
 		return refuse(errorMessage(err));
 	}
@@ -3490,24 +3541,8 @@ async function runNotificationsSetup(input) {
 	} 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 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);
-	}
+	const secretProblem = layoutSecretProblem(layout);
+	if (secretProblem) return refuse(secretProblem);
 	print(`Holocron notifications setup — ${notifications.providerName}${dryRun ? " (dry-run)" : ""}`);
 	const attempt = async (step, fn) => {
 		try {
@@ -3597,6 +3632,270 @@ async function runNotificationsSetup(input) {
 	return report;
 }
 //#endregion
+//#region src/commands/notifications-verify/notifications-verify.ts
+/**
+* `holocron notifications verify` -- read-only: compare the layout a provider
+* declares in `holocron.config.ts` with what is actually on the server and in the
+* secrets store, step by step.
+*
+* It is the end-to-end check for `notifications setup`, and stays useful after
+* as a drift check. Everything the layout and `setup` cannot do yet is listed
+* too, as a failing "not built" step, so the command is red until the last
+* feature lands and each feature built turns exactly one step green. The list
+* is {@link PLANNED_CHECKS}; the numbers match the table in holocron#1098.
+*/
+/** Features not built yet, in the order of the table in holocron#1098. Move an entry into a real check when it lands. */
+const PLANNED_CHECKS = [
+	{
+		step: 8,
+		id: "permissions",
+		title: "channel and category permissions"
+	},
+	{
+		step: 9,
+		id: "role-appearance",
+		title: "role colour, hoist and permissions"
+	},
+	{
+		step: 10,
+		id: "server-settings",
+		title: "server settings (verification, notifications, system channels)"
+	},
+	{
+		step: 11,
+		id: "welcome",
+		title: "welcome and onboarding content"
+	},
+	{
+		step: 12,
+		id: "webhook-appearance",
+		title: "webhook names and avatars"
+	},
+	{
+		step: 13,
+		id: "app-settings",
+		title: "bot application settings (description, tags, install, links)"
+	},
+	{
+		step: 14,
+		id: "role-assignment",
+		title: "role assigned to team members"
+	},
+	{
+		step: 15,
+		id: "post-works",
+		title: "a test post reached every channel (platform.notifyCheck)"
+	},
+	{
+		step: 16,
+		id: "server-creation",
+		title: "the server itself created from config"
+	}
+];
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+const shown = (s) => sanitizeDetail(s);
+async function runNotificationsVerify(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const logger = input.logger ?? getLogger();
+	/* v8 ignore next -- the real loader is only built outside tests, which always inject one */
+	const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
+	await loader.load();
+	assertPluginsResolvable(loader, "notifications verify");
+	const checks = [];
+	const add = (id, title, problems, pass) => {
+		checks.push({
+			id,
+			title,
+			status: problems.length === 0 ? "pass" : "fail",
+			detail: problems.length === 0 ? pass : `${problems.length} problem(s)`,
+			problems
+		});
+	};
+	const byId = (id) => checks.find((c) => c.id === id);
+	const failed = (id, title, reason) => {
+		checks.push({
+			id,
+			title,
+			status: "fail",
+			detail: reason,
+			problems: []
+		});
+	};
+	const summarise = () => ({
+		pass: checks.filter((c) => c.status === "pass").length,
+		fail: checks.filter((c) => c.status === "fail").length,
+		planned: checks.filter((c) => c.status === "planned").length
+	});
+	const finish = () => {
+		const summary = summarise();
+		const report = {
+			status: summary.fail + summary.planned > 0 ? "fail" : "ok",
+			checks,
+			summary
+		};
+		logger.info({
+			...summary,
+			status: report.status,
+			checks: checks.map((c) => `${c.id}:${c.status}`)
+		}, "notifications verify");
+		return report;
+	};
+	const refuse = (message, reason = message) => {
+		print(`  ✗ ${message}`);
+		logger.warn({ reason }, "notifications verify");
+		return {
+			status: "fail",
+			checks,
+			summary: summarise(),
+			message
+		};
+	};
+	let notifications;
+	try {
+		notifications = pickProvider(notificationProviders(loader), input.provider, (p) => typeof p.inspect === "function", {
+			infinitive: "inspect a server",
+			gerund: "inspecting"
+		});
+	} catch (err) {
+		return refuse(describeProviderError(err));
+	}
+	const layout = notifications.layout;
+	if (!layout) return refuse(`the \`${notifications.providerName}\` provider declares no layout — add \`layout\` to its options in holocron.config.ts`);
+	print(`Holocron notifications verify — ${notifications.providerName}\n`);
+	let found;
+	let readError = "";
+	try {
+		found = await notifications.inspect(layout);
+	} catch (err) {
+		readError = describeProviderError(err);
+	}
+	if (notifications.whoami) try {
+		const who = await notifications.whoami();
+		if (who) checks.push({
+			id: "server",
+			title: "server",
+			status: "pass",
+			detail: shown(who.target),
+			problems: []
+		});
+		else failed("server", "server", "no server configured (the provider's whoami has nothing to check)");
+	} catch (err) {
+		failed("server", "server", describeProviderError(err));
+	}
+	else if (found) checks.push({
+		id: "server",
+		title: "server",
+		status: "pass",
+		detail: "readable (the provider has no whoami)",
+		problems: []
+	});
+	else failed("server", "server", readError);
+	const declaredChannels = (layout.categories ?? []).flatMap((cat) => (cat.channels ?? []).map((channel) => ({
+		cat: cat.name,
+		channel
+	})));
+	const pick = (name, category) => {
+		const named = found.channels.filter((c) => same(c.name, name));
+		return {
+			named,
+			match: named.find((c) => c.category !== void 0 && same(c.category, category))
+		};
+	};
+	if (!found) {
+		if (byId("server")?.status !== "fail") failed("read", "read server", readError);
+		for (const [id, title] of [
+			["categories", "categories"],
+			["channels", "channels"],
+			["webhooks", "webhooks"],
+			["roles", "roles"]
+		]) failed(id, title, "not checked: could not read the server");
+	} else {
+		const inspected = found;
+		const categories = layout.categories ?? [];
+		add("categories", "categories", categories.filter((cat) => !inspected.categories.some((name) => same(name, cat.name))).map((cat) => `${shown(cat.name)}: missing`), categories.length === 0 ? "none declared" : `${categories.length} of ${categories.length} exist`);
+		const channelProblems = [];
+		for (const { cat, channel } of declaredChannels) {
+			const { named, match } = pick(channel.name, cat);
+			if (named.length === 0) {
+				channelProblems.push(`#${shown(channel.name)}: missing`);
+				continue;
+			}
+			if (!match) {
+				const where = named.map((c) => c.category ?? "no category").join(", ");
+				channelProblems.push(`#${shown(channel.name)}: exists, but under ${shown(where)} and not ${shown(cat)}`);
+				continue;
+			}
+			if (channel.topic && (match.topic ?? "") !== channel.topic) channelProblems.push(`#${shown(channel.name)}: topic is "${shown(match.topic ?? "")}" but the layout says "${shown(channel.topic)}"`);
+		}
+		add("channels", "channels", channelProblems, declaredChannels.length === 0 ? "none declared" : `${declaredChannels.length} of ${declaredChannels.length} as declared`);
+		const withWebhook = declaredChannels.filter(({ channel }) => channel.webhook);
+		const webhookProblems = [];
+		for (const { cat, channel } of withWebhook) {
+			const name = (channel.webhook === true ? {} : channel.webhook).name ?? channel.name;
+			const { match } = pick(channel.name, cat);
+			if (!match) webhookProblems.push(`#${shown(channel.name)}: no channel to hold the webhook`);
+			else if (match.webhooksError) webhookProblems.push(`#${shown(channel.name)}: could not list its webhooks (${shown(match.webhooksError)})`);
+			else if (!match.webhooks.some((w) => same(w, name))) webhookProblems.push(`#${shown(channel.name)}: no webhook named ${shown(name)}`);
+		}
+		add("webhooks", "webhooks", webhookProblems, withWebhook.length === 0 ? "none declared" : `${withWebhook.length} of ${withWebhook.length} exist`);
+		const roles = layout.roles ?? [];
+		const roleProblems = [];
+		if (inspected.rolesError) roleProblems.push(`could not read the roles (${shown(inspected.rolesError)})`);
+		for (const role of inspected.rolesError ? [] : roles) {
+			const actual = inspected.roles.find((r) => same(r.name, role.name));
+			if (!actual) roleProblems.push(`${shown(role.name)}: missing`);
+			else if (role.mentionable !== void 0 && actual.mentionable !== role.mentionable) roleProblems.push(`${shown(role.name)}: mentionable is ${actual.mentionable} but the layout says ${role.mentionable}`);
+		}
+		add("roles", "roles", roleProblems, roles.length === 0 ? "none declared" : `${roles.length} of ${roles.length} as declared`);
+	}
+	const wanted = [...declaredChannels.filter(({ channel }) => channel.webhook).map(({ channel }) => channel.webhook !== true && channel.webhook && channel.webhook.secret ? channel.webhook.secret : defaultSecretName(channel.name)), ...(layout.roles ?? []).flatMap((r) => r.secret ? [r.secret] : [])];
+	if (wanted.length === 0) checks.push({
+		id: "secrets",
+		title: "secrets",
+		status: "pass",
+		detail: "none declared",
+		problems: []
+	});
+	else if (!loader.has("secrets")) failed("secrets", "secrets", whyMissing(loader, "secrets", "no `secrets` provider to check them with"));
+	else {
+		const org = input.context.org;
+		const scope = input.scope ?? (org ? {
+			kind: "organization",
+			name: org
+		} : void 0);
+		if (!scope) failed("secrets", "secrets", "no org to look under — pass --scope or set `org` in holocron.config.ts");
+		else try {
+			const have = new Set((await loader.get("secrets").listSecrets(scope)).map((n) => n.toUpperCase()));
+			const clash = layoutSecretProblem(layout);
+			add("secrets", "secrets", [...clash ? [shown(clash)] : [], ...wanted.filter((n) => !have.has(n.toUpperCase())).map((n) => `${shown(n)}: missing`)], `${wanted.length} of ${wanted.length} exist`);
+		} catch (err) {
+			failed("secrets", "secrets", describeProviderError(err));
+		}
+	}
+	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
+		id: planned.id,
+		title: planned.title,
+		status: "planned",
+		detail: `not built yet (#1098, step ${planned.step})`,
+		problems: [],
+		step: planned.step
+	});
+	const built = checks.filter((c) => c.status !== "planned");
+	const width = Math.max(...built.map((c) => c.title.length));
+	for (const check of built) {
+		print(`  ${check.status === "pass" ? "✓" : "✗"} ${check.title.padEnd(width)}  ${check.detail}`);
+		for (const problem of check.problems) print(`      - ${problem}`);
+	}
+	const planned = checks.filter((c) => c.status === "planned");
+	if (planned.length > 0) {
+		print("\nNot built yet (each fails until it lands, see #1098):");
+		for (const check of planned) print(`  ✗ ${String(check.step).padStart(2)}  ${check.title}`);
+	}
+	const summary = summarise();
+	print(`\n${summary.pass} passed, ${summary.fail} failed${input.builtOnly ? "" : `, ${summary.planned} not built`}`);
+	return finish();
+}
+//#endregion
 //#region src/commands/npm-bump-versions/npm-bump-versions.ts
 async function runNpmBumpVersions(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -9733,6 +10032,12 @@ const COMMAND_REGISTRY = [
 		}],
 		supportsDryRun: true
 	},
+	{
+		name: "notifications verify",
+		description: "Check the layout against the server and the secrets store, step by step (read-only)",
+		positionals: [],
+		supportsDryRun: false
+	},
 	{
 		name: "notifications setup",
 		description: "Apply the server layout a notifications provider declares in holocron.config.ts",
@@ -11291,6 +11596,32 @@ try {
 			...argv.scope ? { scope: parseScope(argv.scope) } : {},
 			...argv.provider ? { provider: argv.provider } : {}
 		})).status === "fail") process.exitCode = 1;
+	}).command("verify", "Check the layout against the server and the secrets store, step by step (read-only)", (y) => y.option("scope", {
+		type: "string",
+		describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
+	}).option("provider", {
+		type: "string",
+		describe: "Which notifications provider, when several can inspect"
+	}).option("built-only", {
+		type: "boolean",
+		default: false,
+		describe: "Leave out the features that are not built yet (a routine drift check)"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runNotificationsVerify({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			...argv.scope ? { scope: parseScope(argv.scope) } : {},
+			...argv.provider ? { provider: argv.provider } : {},
+			...argv.builtOnly ? { builtOnly: true } : {}
+		})).status === "fail") process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
 		await launchGroupMenu("notifications", argv);
 	}), () => {}).command("sync", "Sync generated files to other repos", (g) => g.command("github", "Sync workflow templates and composite actions to theholocron/.github", (y) => y.option("repo", {