@theholocron/cli 5.0.0-alpha.202 → 5.0.0-alpha.203

package/README.md

@@ -538,18 +538,19 @@ A `notifications` provider can declare a whole server in `holocron.config.ts`
 onboarding, the bot application) and the CLI applies and checks it. The
 commands and the config are provider-neutral; Discord is the first provider.
 
-| Command                                                    | What it does                                                                                                                                                    |
-| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `holocron notifications setup`                             | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches                                                                 |
-| `holocron notifications channel add <name>`                | Creates one channel (optionally with a webhook whose URL is stored as a secret)                                                                                 |
-| `holocron notifications link`                              | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept)                                          |
-| `holocron notifications sync-roles`                        | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one)                                                 |
-| `holocron doctor notifications [--built-only] [--deliver]` | Read-only, step by step: does the server match the layout, and do the secrets exist (`--deliver` also posts a test message through each webhook and removes it) |
+| Command                                                    | What it does                                                                                                                                                                                                                               |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `holocron notifications setup`                             | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches                                                                                                                                            |
+| `holocron notifications channel add <name>`                | Creates one channel (optionally with a webhook whose URL is stored as a secret)                                                                                                                                                            |
+| `holocron notifications link`                              | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept)                                                                                                                     |
+| `holocron notifications sync-roles`                        | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one)                                                                                                                            |
+| `holocron doctor notifications [--built-only] [--deliver]` | Step by step: does the server match the layout, and do the secrets exist. A full run also leaves one `🧪 test:` post in the layout's `testChannel`; `--built-only` posts nothing; `--deliver` posts to every channel and removes each post |
 
 Config shape added for role sync and sign-in (all under the provider's `layout`):
 
 | Field                         | Meaning                                                                                                                                                     |
 | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `testChannel`                 | The channel (it must declare a webhook) the doctor posts its one self-removing test message to.                                                             |
 | `roles[].team`                | A GitHub team slug. The role follows that team: given to linked members, taken from linked people who left. Never touches holders nobody has linked.        |
 | `links.hostedUrl`             | A hosted sign-in service (Sentinel). `link` asks `<hostedUrl>/api/link` and uses it when it answers `{ "service": "link" }`; otherwise it signs in locally. |
 | `links.localPort`             | The port of the local sign-in listener (default `53682`, bound to `127.0.0.1` only).                                                                        |

package/dist/cli.mjs

@@ -3551,7 +3551,7 @@ const shown = (s) => sanitizeDetail(s);
 const WELCOME_TITLE = "welcome screen and onboarding set";
 const APP_TITLE = "bot description, tags, install link and URLs set";
 const AVATAR_TITLE = "webhook names and avatars set";
-const DELIVERY_TITLE = "test message delivered through every webhook";
+const DELIVERY_TITLE = "test message delivered through a webhook";
 const SERVER_TITLE = "server verification, notifications and community set";
 const ACCESS_TITLE = "channel and category access set";
 const ROLE_APPEARANCE_TITLE = "role colour, hoist and permissions set";
@@ -3584,11 +3584,10 @@ async function runDoctorNotifications(input) {
 			problems: []
 		});
 	};
-	let deliverSkipped = false;
 	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) + (deliverSkipped ? 1 : 0)
+		skip: input.builtOnly ? PLANNED_CHECKS.length : 0
 	});
 	const finish = () => {
 		const summary = summarise();
@@ -3985,8 +3984,12 @@ async function runDoctorNotifications(input) {
 		cat,
 		channel
 	})));
-	if (!input.deliver) deliverSkipped = true;
-	else if (withHook.length === 0) checks.push({
+	const testName = layout.testChannel;
+	const mode = input.deliver ? "all" : !input.builtOnly && testName !== void 0 ? "test" : "none";
+	const targets = mode === "all" ? withHook : mode === "test" ? withHook.filter(({ channel }) => same(channel.name, testName)).slice(0, 1) : [];
+	let deliveryNote;
+	if (mode === "none") deliveryNote = !input.builtOnly && testName === void 0 ? "the delivery check needs a test channel: name one in the layout's `testChannel` (a channel with a webhook)" : "the delivery check posts test messages, so --built-only skips it; add --deliver to post to every channel";
+	else if (targets.length === 0) checks.push({
 		id: "post-works",
 		title: DELIVERY_TITLE,
 		status: "pass",
@@ -3997,22 +4000,24 @@ async function runDoctorNotifications(input) {
 	else if (!notifications.checkDelivery) failed("post-works", DELIVERY_TITLE, `the \`${notifications.providerName}\` provider cannot check delivery`);
 	else {
 		const problems = [];
-		for (const { cat, channel } of withHook) {
+		for (const { cat, channel } of targets) {
 			const cfg = channel.webhook === true ? {} : channel.webhook;
+			const keep = mode === "test";
 			try {
 				const result = await notifications.checkDelivery({
 					channel: channel.name,
 					name: cfg.name ?? channel.name,
 					category: cat.name,
-					text: `holocron doctor delivery check for #${channel.name}: safe to ignore, this message removes itself`
+					text: keep ? "🧪 test: `holocron doctor notifications` check for {channel}. This post was a test of the delivery system; it is safe to delete." : "🧪 test: `holocron doctor notifications --deliver` check for {channel}. This post was a test of the delivery system; it removes itself.",
+					...keep ? { keep: true } : {}
 				});
 				for (const problem of result.problems) problems.push(`#${shown(channel.name)}: ${shown(problem)}`);
-				if (result.problems.length === 0 && !(result.posted && result.readBack && result.removed)) problems.push(`#${shown(channel.name)}: the check did not complete`);
+				if (result.problems.length === 0 && !(result.posted && result.readBack && (keep ? result.kept : result.removed))) problems.push(`#${shown(channel.name)}: the check did not complete`);
 			} catch (err) {
 				problems.push(`#${shown(channel.name)}: ${shown(describeProviderError(err))}`);
 			}
 		}
-		add("post-works", DELIVERY_TITLE, problems, `${withHook.length} of ${withHook.length} delivered`);
+		add("post-works", DELIVERY_TITLE, problems, mode === "all" ? `${targets.length} of ${targets.length} delivered` : `delivered through #${shown(targets[0].channel.name)} (left there)`);
 	}
 	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
 		id: planned.id,
@@ -4027,7 +4032,10 @@ async function runDoctorNotifications(input) {
 		print(statusRow(check.status === "pass" ? "ok" : "fail", [check.title.padEnd(width), check.detail]));
 		for (const problem of check.problems) print(`      - ${problem}`);
 	}
-	if (deliverSkipped) print(`  ${style.skip(`${DELIVERY_TITLE}: not run; add --deliver to post a test message to each channel`)}`);
+	if (deliveryNote) {
+		print("");
+		print(`  ${style.skip(`note: ${deliveryNote}`)}`);
+	}
 	const summary = summarise();
 	print("");
 	print(style.header(`${summary.pass} ok, ${summary.fail} fail, ${summary.skip} skipped`));
@@ -4700,12 +4708,18 @@ function accessRoleProblem(layout) {
 function serverLayoutProblem(layout) {
 	const counts = /* @__PURE__ */ new Map();
 	for (const name of (layout.categories ?? []).flatMap((c) => (c.channels ?? []).map((ch) => ch.name.toLowerCase()))) counts.set(name, (counts.get(name) ?? 0) + 1);
+	const declared = (layout.categories ?? []).flatMap((c) => c.channels ?? []);
 	const roles = new Set((layout.roles ?? []).map((r) => r.name.toLowerCase()));
 	const channel = (where, name) => {
 		const count = counts.get(name.toLowerCase()) ?? 0;
 		if (count === 0) return `${where} names the channel \`${name}\`, which is not in the layout's channels`;
 		if (count > 1) return `${where} names \`${name}\`, but more than one channel in the layout has that name`;
 	};
+	if (layout.testChannel !== void 0) {
+		const problem = channel("`testChannel`", layout.testChannel);
+		if (problem) return problem;
+		if (!declared.some((ch) => ch.name.toLowerCase() === layout.testChannel.toLowerCase() && ch.webhook)) return `\`testChannel\` names \`${layout.testChannel}\`, which declares no webhook`;
+	}
 	const roleTeams = roleTeamProblem(layout);
 	if (roleTeams) return roleTeams;
 	const emptyTeam = (layout.roles ?? []).find((r) => r.team !== void 0 && r.team.trim() === "");
@@ -11114,14 +11128,14 @@ const COMMAND_REGISTRY = [
 	},
 	{
 		name: "doctor notifications",
-		description: "Check the layout against the server and the secrets store, step by step (read-only unless --deliver posts test messages)",
+		description: "Check the layout against the server and the secrets store, step by step (a full run leaves one test post in the test channel; --built-only posts nothing unless --deliver)",
 		positionals: [],
 		options: [{
 			key: "deliver",
 			flag: "--deliver",
 			type: "confirm",
 			default: false,
-			message: "Also post a test message through every channel's webhook (it removes itself)?"
+			message: "Post a test message through every channel's webhook (each removes itself)?"
 		}],
 		supportsDryRun: false
 	},
@@ -11982,7 +11996,7 @@ 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 unless --deliver posts test messages)", (y) => y.option("scope", {
+	}).command("notifications", "Check the layout against the server and the secrets store, step by step (a full run leaves one test post in the test channel; --built-only posts nothing unless --deliver)", (y) => y.option("scope", {
 		type: "string",
 		describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
 	}).option("provider", {
@@ -11995,7 +12009,7 @@ try {
 	}).option("deliver", {
 		type: "boolean",
 		default: false,
-		describe: "Also post a test message through every channel's webhook, read it back and remove it"
+		describe: "Post a test message through every channel's webhook, read it back and remove it (works with --built-only)"
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;