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

package/dist/cli.mjs

@@ -24,9 +24,9 @@ import search from "@inquirer/search";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import ora from "ora";
 import { findRootSync, isWorkspaceRoot, walkFilesSync } from "@theholocron/fs-utils";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { stringifyJson } from "@theholocron/json-utils";
-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";
@@ -409,6 +409,7 @@ const COMMAND_CONTEXTS = {
 	"secrets sync": "workspace",
 	"notifications channel add": "workspace",
 	"notifications setup": "workspace",
+	"doctor notifications": "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,
@@ -2604,28 +2610,557 @@ async function runSmokeCheck(key, provider, impl) {
 			}
 			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)");
+		default: return mk(key, provider, "skip", "loaded (no smoke check defined for this capability)");
+	}
+}
+/**
+* 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 {
+		capability,
+		provider,
+		status,
+		message,
+		...logMessage !== void 0 ? { logMessage } : {}
+	};
+}
+//#endregion
+//#region src/commands/notifications-channel-add/notifications-channel-add.ts
+/**
+* `holocron notifications channel add` — create one channel (and, with
+* `--with-webhook`, an inbound webhook whose URL goes straight into a secret).
+*
+* Provider-neutral: it drives the `notifications` capability's `ensure*`
+* methods, so any provider that implements them works. Idempotent — an
+* existing channel or webhook is left alone, and a webhook URL is never
+* printed, only stored.
+*/
+/**
+* `HOLOCRON_NOTIFY_WEBHOOK_SYNC` for channel `sync`. Named after the job, not the
+* provider, so changing providers means re-pointing the same secrets at new
+* webhook URLs, with no workflow edits.
+*/
+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);
+	return failure ? `${fallback} (\`${failure.provider}\` failed to load: ${describeProviderError(failure.error)})` : fallback;
+}
+/** 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 ${verb.gerund} \`notifications\` provider named \`${wanted}\` (have: ${names(capable)})`);
+		return match;
+	}
+	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, tally } = deps;
+	const webhookCfg = spec.webhook || void 0;
+	const secretName = webhookCfg?.secret ?? defaultSecretName(spec.name);
+	const webhookName = webhookCfg?.name ?? spec.name;
+	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(`  ${style.skip(`would ensure channel ${spec.name}${where}`)}`);
+		if (tally) tally.skip += webhookCfg ? 2 : 1;
+		if (webhookCfg) print(`  ${style.skip(`would ensure webhook ${webhookName} and store its URL in ${secretName}`)}`);
+		return {
+			name: spec.name,
+			...spec.category ? { category: spec.category } : {},
+			created: false
+		};
+	}
+	const channel = await notifications.ensureChannel({
+		name: spec.name,
+		...spec.category ? { category: spec.category } : {},
+		...spec.topic ? { topic: spec.topic } : {}
+	});
+	print(`  ${(channel.created ? style.success : style.skip)(`${channel.created ? "created" : "exists "} channel ${spec.name}${where}`)}`);
+	if (tally) tally[channel.created ? "ok" : "skip"]++;
+	const outcome = {
+		name: spec.name,
+		...spec.category ? { category: spec.category } : {},
+		created: channel.created
+	};
+	if (!webhookCfg) return outcome;
+	const hook = await notifications.ensureWebhook({
+		channel: spec.name,
+		name: webhookName,
+		...spec.category ? { category: spec.category } : {}
+	});
+	if (hook.url) {
+		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 (${describeProviderError(err)}) — delete the webhook in the provider and re-run to get a fresh URL`, { cause: err });
+		}
+		print(`  ${style.success(`${hook.created ? "created" : "found  "} webhook ${webhookName}; URL stored in ${secretName}`)}`);
+		if (tally) tally.ok++;
+		outcome.webhook = {
+			name: webhookName,
+			created: hook.created,
+			secret: secretName,
+			stored: true
+		};
+	} else {
+		const note = `webhook ${webhookName} already exists and its URL cannot be read back — delete it in the provider and re-run, or set ${secretName} yourself`;
+		print(`  ${style.warn(note)}`);
+		outcome.webhook = {
+			name: webhookName,
+			created: hook.created,
+			secret: secretName,
+			stored: false,
+			note
+		};
+	}
+	return outcome;
+}
+async function runNotificationsChannelAdd(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 channel add");
+	const dryRun = input.context.dryRun ?? false;
+	print(`Holocron notifications channel add — ${input.name}${dryRun ? " (dry-run)" : ""}`);
+	try {
+		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"));
+			secrets = loader.get("secrets");
+		}
+		const org = input.context.org;
+		const scope = input.scope ?? (org ? {
+			kind: "organization",
+			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 } : {},
+			scope: scope ?? { kind: "repo" },
+			dryRun,
+			print
+		}, {
+			name: input.name,
+			...input.category ? { category: input.category } : {},
+			...input.topic ? { topic: input.topic } : {},
+			...input.withWebhook ? { webhook: {
+				...input.webhookName ? { name: input.webhookName } : {},
+				...input.secret ? { secret: input.secret } : {}
+			} } : {}
+		});
+		logger.info({
+			channel: input.name,
+			created: channel.created,
+			provider: notifications.providerName,
+			status: "ok"
+		}, `notifications channel add: ${input.name}`);
+		if (channel.webhook && !channel.webhook.stored && !dryRun) {
+			const message = channel.webhook.note;
+			print(`  ${style.fail(message)}`);
+			return {
+				status: "fail",
+				channel,
+				message
+			};
+		}
+		return {
+			status: dryRun ? "dry-run" : "ok",
+			channel
+		};
+	} catch (err) {
+		const message = describeProviderError(err);
+		print(`  ${style.fail(message)}`);
+		logger.warn({
+			channel: input.name,
+			reason: logReason(err)
+		}, `notifications channel add: ${input.name}`);
+		return {
+			status: "fail",
+			message
+		};
+	}
+}
+//#endregion
+//#region src/commands/doctor-notifications/doctor-notifications.ts
+/**
+* `holocron doctor notifications` -- 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 plain failing steps, 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 set"
+	},
+	{
+		step: 10,
+		id: "server-settings",
+		title: "server verification, notifications and system channels set"
+	},
+	{
+		step: 11,
+		id: "welcome",
+		title: "welcome screen and onboarding set"
+	},
+	{
+		step: 12,
+		id: "webhook-appearance",
+		title: "webhook names and avatars set"
+	},
+	{
+		step: 13,
+		id: "app-settings",
+		title: "bot description, tags, install link and URLs set"
+	},
+	{
+		step: 14,
+		id: "role-assignment",
+		title: "role assigned to team members"
+	},
+	{
+		step: 15,
+		id: "post-works",
+		title: "test post reached every channel (platform.notifyCheck)"
+	},
+	{
+		step: 16,
+		id: "server-creation",
+		title: "server created from config"
+	}
+];
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+const shown = (s) => sanitizeDetail(s);
+const ROLE_APPEARANCE_TITLE = "role colour, hoist and permissions set";
+const SECRETS_TITLE = "webhook URLs and role id stored as secrets";
+async function runDoctorNotifications(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, "doctor notifications");
+	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,
+		skip: input.builtOnly ? PLANNED_CHECKS.length : 0
+	});
+	const finish = () => {
+		const summary = summarise();
+		const report = {
+			status: summary.fail > 0 ? "fail" : "ok",
+			checks,
+			summary
+		};
+		logger.info({
+			...summary,
+			status: report.status,
+			checks: checks.map((c) => `${c.id}:${c.status}`)
+		}, "doctor notifications");
+		return report;
+	};
+	const refuse = (message, reason = message) => {
+		print(`  ${style.fail(message)}`);
+		print("");
+		print(style.header("0 ok, 1 fail, 0 skipped"));
+		logger.warn({ reason }, "doctor notifications");
+		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`);
+	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 reachable",
+			status: "pass",
+			detail: shown(who.target),
+			problems: []
+		});
+		else failed("server", "server reachable", "no server configured (the provider's whoami has nothing to check)");
+	} catch (err) {
+		failed("server", "server reachable", describeProviderError(err));
+	}
+	else if (found) checks.push({
+		id: "server",
+		title: "server reachable",
+		status: "pass",
+		detail: "readable (the provider has no whoami)",
+		problems: []
+	});
+	else failed("server", "server reachable", 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 exist"],
+			["channels", "channels in their category, with topics"],
+			["webhooks", "webhooks on their channels"],
+			["roles", "roles exist and are mentionable"],
+			["role-appearance", ROLE_APPEARANCE_TITLE]
+		]) failed(id, title, "not checked: could not read the server");
+	} else {
+		const inspected = found;
+		const categories = layout.categories ?? [];
+		add("categories", "categories exist", 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 in their category, with topics", 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 on their channels", 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 named = inspected.roles.filter((r) => same(r.name, role.name));
+			const actual = named[0];
+			if (named.length > 1) roleProblems.push(`${shown(role.name)}: ${named.length} roles have this name; setup cannot tell which to manage`);
+			else 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 exist and are mentionable", roleProblems, roles.length === 0 ? "none declared" : `${roles.length} of ${roles.length} as declared`);
+		const appearance = [];
+		if (!inspected.rolesError) for (const role of roles) {
+			const actual = inspected.roles.find((r) => same(r.name, role.name));
+			if (!actual) {
+				appearance.push(`${shown(role.name)}: not checked, the role is missing`);
+				continue;
+			}
+			if (role.color !== void 0 && (actual.color ?? "").toLowerCase() !== role.color.toLowerCase()) appearance.push(`${shown(role.name)}: colour is ${shown(actual.color ?? "default")} but the layout says ${shown(role.color)}`);
+			if (role.hoist !== void 0 && (actual.hoist ?? false) !== role.hoist) appearance.push(`${shown(role.name)}: hoist is ${actual.hoist ?? false} but the layout says ${role.hoist}`);
+			const reported = actual.permissions;
+			if (role.permissions !== void 0) {
+				if (reported === void 0) appearance.push(`${shown(role.name)}: the provider did not report its permissions`);
+				else {
+					const have = new Set(reported.map((n) => n.toLowerCase()));
+					const want = new Set(role.permissions.map((n) => n.toLowerCase()));
+					const missing = role.permissions.filter((n) => !have.has(n.toLowerCase()));
+					const extra = reported.filter((n) => !want.has(n.toLowerCase()));
+					if (missing.length > 0) appearance.push(`${shown(role.name)}: missing permissions ${missing.map(shown).join(", ")}`);
+					if (extra.length > 0) appearance.push(`${shown(role.name)}: has extra permissions ${extra.map(shown).join(", ")}`);
+				}
+			}
+		}
+		const styled = roles.filter((r) => r.color !== void 0 || r.hoist !== void 0 || r.permissions !== void 0);
+		add("role-appearance", ROLE_APPEARANCE_TITLE, inspected.rolesError ? [`not checked: could not read the roles`] : appearance, styled.length === 0 ? "none declared" : `${styled.length} of ${styled.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_TITLE,
+		status: "pass",
+		detail: "none declared",
+		problems: []
+	});
+	else if (!loader.has("secrets")) failed("secrets", SECRETS_TITLE, 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_TITLE, "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_TITLE, [...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_TITLE, describeProviderError(err));
+		}
 	}
-}
-/**
-* 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 {
-		capability,
-		provider,
-		status,
-		message,
-		...logMessage !== void 0 ? { logMessage } : {}
-	};
+	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
+		id: planned.id,
+		title: planned.title,
+		status: "fail",
+		detail: `not built yet (#1098, step ${planned.step})`,
+		problems: [],
+		step: planned.step
+	});
+	const width = Math.max(...checks.map((c) => c.title.length));
+	for (const check of checks) {
+		print(statusRow(check.status === "pass" ? "ok" : "fail", [check.title.padEnd(width), check.detail]));
+		for (const problem of check.problems) print(`      - ${problem}`);
+	}
+	const summary = summarise();
+	print("");
+	print(style.header(`${summary.pass} ok, ${summary.fail} fail, ${summary.skip} skipped`));
+	return finish();
 }
 //#endregion
 //#region src/commands/monitoring-check/monitoring-check.ts
@@ -3231,203 +3766,6 @@ async function runNew(input) {
 	};
 }
 //#endregion
-//#region src/commands/notifications-channel-add/notifications-channel-add.ts
-/**
-* `holocron notifications channel add` — create one channel (and, with
-* `--with-webhook`, an inbound webhook whose URL goes straight into a secret).
-*
-* Provider-neutral: it drives the `notifications` capability's `ensure*`
-* methods, so any provider that implements them works. Idempotent — an
-* existing channel or webhook is left alone, and a webhook URL is never
-* printed, only stored.
-*/
-/**
-* `HOLOCRON_NOTIFY_WEBHOOK_SYNC` for channel `sync`. Named after the job, not the
-* provider, so changing providers means re-pointing the same secrets at new
-* webhook URLs, with no workflow edits.
-*/
-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);
-	return failure ? `${fallback} (\`${failure.provider}\` failed to load: ${failure.error.message})` : 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");
-	if (wanted) {
-		const match = capable.find((p) => p.providerName === wanted);
-		if (!match) throw new Error(`no provisioning \`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>`);
-	return capable[0];
-}
-const names = (ps) => ps.map((p) => p.providerName).join(", ");
-/** 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;
-	const webhookCfg = spec.webhook || void 0;
-	const secretName = webhookCfg?.secret ?? defaultSecretName(spec.name);
-	const webhookName = webhookCfg?.name ?? spec.name;
-	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}`);
-		if (webhookCfg) print(`  … would ensure webhook ${webhookName} and store its URL in ${secretName}`);
-		return {
-			name: spec.name,
-			...spec.category ? { category: spec.category } : {},
-			created: false
-		};
-	}
-	const channel = await notifications.ensureChannel({
-		name: spec.name,
-		...spec.category ? { category: spec.category } : {},
-		...spec.topic ? { topic: spec.topic } : {}
-	});
-	print(`  ${channel.created ? "✓ created" : "· exists "} channel ${spec.name}${where}`);
-	const outcome = {
-		name: spec.name,
-		...spec.category ? { category: spec.category } : {},
-		created: channel.created
-	};
-	if (!webhookCfg) return outcome;
-	const hook = await notifications.ensureWebhook({
-		channel: spec.name,
-		name: webhookName,
-		...spec.category ? { category: spec.category } : {}
-	});
-	if (hook.url) {
-		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 (${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 = {
-			name: webhookName,
-			created: hook.created,
-			secret: secretName,
-			stored: true
-		};
-	} else {
-		const note = `webhook ${webhookName} already exists and its URL cannot be read back — delete it in the provider and re-run, or set ${secretName} yourself`;
-		print(`  ! ${note}`);
-		outcome.webhook = {
-			name: webhookName,
-			created: hook.created,
-			secret: secretName,
-			stored: false,
-			note
-		};
-	}
-	return outcome;
-}
-async function runNotificationsChannelAdd(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 channel add");
-	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);
-		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"));
-			secrets = loader.get("secrets");
-		}
-		const org = input.context.org;
-		const scope = input.scope ?? (org ? {
-			kind: "organization",
-			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 } : {},
-			scope: scope ?? { kind: "repo" },
-			dryRun,
-			print
-		}, {
-			name: input.name,
-			...input.category ? { category: input.category } : {},
-			...input.topic ? { topic: input.topic } : {},
-			...input.withWebhook ? { webhook: {
-				...input.webhookName ? { name: input.webhookName } : {},
-				...input.secret ? { secret: input.secret } : {}
-			} } : {}
-		});
-		logger.info({
-			channel: input.name,
-			created: channel.created,
-			provider: notifications.providerName,
-			status: "ok"
-		}, `notifications channel add: ${input.name}`);
-		if (channel.webhook && !channel.webhook.stored && !dryRun) {
-			const message = channel.webhook.note;
-			print(`  ✗ ${message}`);
-			return {
-				status: "fail",
-				channel,
-				message
-			};
-		}
-		return {
-			status: dryRun ? "dry-run" : "ok",
-			channel
-		};
-	} catch (err) {
-		const message = describeProviderError(err);
-		print(`  ✗ ${message}`);
-		logger.warn({
-			channel: input.name,
-			reason: logReason(err)
-		}, `notifications channel add: ${input.name}`);
-		return {
-			status: "fail",
-			message
-		};
-	}
-}
-//#endregion
 //#region src/commands/notifications-setup/notifications-setup.ts
 /**
 * `holocron notifications setup` — apply the server layout a `notifications`
@@ -3457,7 +3795,9 @@ async function runNotificationsSetup(input) {
 		failures: []
 	};
 	const refuse = (message, reason = message) => {
-		print(`  ✗ ${message}`);
+		print(`  ${style.fail(message)}`);
+		print("");
+		print(style.header("0 ok, 1 fail, 0 skipped"));
 		logger.warn({ reason }, "notifications setup");
 		return {
 			...report,
@@ -3467,7 +3807,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,31 +3830,21 @@ 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);
+	const secretProblem = layoutSecretProblem(layout);
+	if (secretProblem) return refuse(secretProblem);
+	const providerProblem = notifications.validateLayout?.(layout);
+	if (providerProblem) return refuse(providerProblem);
+	const tally = {
+		ok: 0,
+		skip: 0
 	};
-	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);
-	}
-	print(`Holocron notifications setup — ${notifications.providerName}${dryRun ? " (dry-run)" : ""}`);
+	const made = (created) => void (created ? tally.ok++ : tally.skip++);
 	const attempt = async (step, fn) => {
 		try {
 			await fn();
 		} catch (err) {
 			const message = describeProviderError(err);
-			print(`  ✗ ${step}: ${message}`);
+			print(`  ${style.fail(`${step}: ${message}`)}`);
 			report.failures.push({
 				step,
 				message
@@ -3522,16 +3852,18 @@ async function runNotificationsSetup(input) {
 		}
 	};
 	for (const category of layout.categories ?? []) {
-		print(`\n${category.name}`);
+		print(`\n${style.header(category.name)}`);
 		report.categories.push(category.name);
 		await attempt(`category ${category.name}`, async () => {
 			if (!notifications.ensureCategory) return;
 			if (dryRun) {
-				print(`  … would ensure category ${category.name}`);
+				print(`  ${style.skip(`would ensure category ${category.name}`)}`);
+				tally.skip++;
 				return;
 			}
-			const made = await notifications.ensureCategory(category.name);
-			print(`  ${made.created ? "✓ created" : "· exists "} category ${category.name}`);
+			const result = await notifications.ensureCategory(category.name);
+			print(`  ${(result.created ? style.success : style.skip)(`${result.created ? "created" : "exists "} category ${category.name}`)}`);
+			made(result.created);
 		});
 		for (const channel of category.channels ?? []) await attempt(`channel ${channel.name}`, async () => {
 			const outcome = await provisionChannel({
@@ -3539,7 +3871,8 @@ async function runNotificationsSetup(input) {
 				...secrets ? { secrets } : {},
 				scope: scope ?? { kind: "repo" },
 				dryRun,
-				print
+				print,
+				tally
 			}, {
 				name: channel.name,
 				category: category.name,
@@ -3553,11 +3886,12 @@ async function runNotificationsSetup(input) {
 			});
 		});
 	}
-	if ((layout.roles ?? []).length > 0) print("\nRoles");
+	if ((layout.roles ?? []).length > 0) print(`\n${style.header("Roles")}`);
 	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}${role.secret ? ` and store its id in ${role.secret}` : ""}`);
+			print(`  ${style.skip(`would ensure role ${role.name}${role.secret ? ` and store its id in ${role.secret}` : ""}`)}`);
+			tally.skip++;
 			report.roles.push({
 				name: role.name,
 				created: false,
@@ -3565,28 +3899,36 @@ async function runNotificationsSetup(input) {
 			});
 			return;
 		}
-		const made = await notifications.ensureRole({
+		const result = await notifications.ensureRole({
 			name: role.name,
-			...role.mentionable !== void 0 ? { mentionable: role.mentionable } : {}
+			...role.mentionable !== void 0 ? { mentionable: role.mentionable } : {},
+			...role.color !== void 0 ? { color: role.color } : {},
+			...role.hoist !== void 0 ? { hoist: role.hoist } : {},
+			...role.permissions !== void 0 ? { permissions: role.permissions } : {}
 		});
 		const outcome = {
 			name: role.name,
-			id: made.id,
-			created: made.created
+			id: result.id,
+			created: result.created,
+			...result.updated?.length ? { updated: result.updated } : {}
 		};
 		report.roles.push(outcome);
-		print(`  ${made.created ? "✓ created" : "· exists "} role ${role.name} (id ${made.id})`);
+		const changed = result.created || (result.updated?.length ?? 0) > 0;
+		const verb = result.created ? "created" : changed ? "updated" : "exists ";
+		print(`  ${(changed ? style.success : style.skip)(`${verb} role ${role.name} (id ${result.id})${result.updated?.length ? `: ${result.updated.join(", ")}` : ""}`)}`);
+		made(changed);
 		if (role.secret) {
-			await secrets.setSecret(scope, role.secret, made.id);
+			await secrets.setSecret(scope, role.secret, result.id);
 			outcome.secret = role.secret;
 			outcome.stored = true;
-			print(`  ✓ stored the id of ${role.name} in ${role.secret}`);
+			print(`  ${style.success(`stored the id of ${role.name} in ${role.secret}`)}`);
+			tally.ok++;
 		}
 	});
-	if (report.failures.length > 0) {
-		report.status = "fail";
-		print(`\n${report.failures.length} step(s) need attention`);
-	} else if (dryRun) report.status = "dry-run";
+	if (report.failures.length > 0) report.status = "fail";
+	else if (dryRun) report.status = "dry-run";
+	print("");
+	print(style.header(`${tally.ok} ok, ${report.failures.length} fail, ${tally.skip} skipped`));
 	logger.info({
 		provider: notifications.providerName,
 		channels: report.channels.length,
@@ -9733,6 +10075,12 @@ const COMMAND_REGISTRY = [
 		}],
 		supportsDryRun: true
 	},
+	{
+		name: "doctor notifications",
+		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",
@@ -10560,6 +10908,32 @@ try {
 	}).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."
+	}).command("notifications", "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 runDoctorNotifications({
+			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;
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;