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

package/README.md

@@ -538,13 +538,13 @@ 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]` | Read-only, step by step: does the server match the layout, and do the secrets exist                                    |
+| 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) |
 
 Config shape added for role sync and sign-in (all under the provider's `layout`):
 
@@ -566,6 +566,7 @@ Capability surface behind it (all optional, so providers without the concept omi
 - `Source.teamMembers(teamSlug, org?)`, `Source.readFile(path, repo?)` (returns the `version` a later write must present),
   `Source.writeFile(path, content, { message, version?, repo? })` (a changed `version` is refused: a real conflict check).
 - `Notifications.roleMembers(role)`, `addRoleMember(role, memberId)`, `removeRoleMember(role, memberId)`.
+- `Notifications.checkDelivery({ channel, name, category?, text })`: posts through a channel's webhook, reads the post back and removes it, and says which step failed.
 - `Notifications.signIn()` returning `{ authorizeUrl, complete }`: the provider-neutral shape of "prove which account you own".
 - `Notifications.ensureApplication` returns `{ updated, todo? }`; each `todo` is a step only a person can do (a portal setting
   the API ignores) and is reported as a failure until done.

package/dist/cli.mjs

@@ -3527,10 +3527,6 @@ async function runNotificationsLink(input) {
 */
 /** 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: 15,
-	id: "post-works",
-	title: "test post reached every channel (platform.notifyCheck)"
-}, {
 	step: 16,
 	id: "server-creation",
 	title: "server created from config"
@@ -3555,6 +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 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";
@@ -3587,10 +3584,11 @@ 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
+		skip: (input.builtOnly ? PLANNED_CHECKS.length : 0) + (deliverSkipped ? 1 : 0)
 	});
 	const finish = () => {
 		const summary = summarise();
@@ -3983,6 +3981,39 @@ async function runDoctorNotifications(input) {
 			failed("role-members", ROLE_MEMBERS_TITLE, shown(describeProviderError(err)));
 		}
 	}
+	const withHook = (layout.categories ?? []).flatMap((cat) => (cat.channels ?? []).filter((c) => c.webhook).map((channel) => ({
+		cat,
+		channel
+	})));
+	if (!input.deliver) deliverSkipped = true;
+	else if (withHook.length === 0) checks.push({
+		id: "post-works",
+		title: DELIVERY_TITLE,
+		status: "pass",
+		detail: "none declared",
+		problems: [],
+		step: 15
+	});
+	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) {
+			const cfg = channel.webhook === true ? {} : channel.webhook;
+			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`
+				});
+				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`);
+			} catch (err) {
+				problems.push(`#${shown(channel.name)}: ${shown(describeProviderError(err))}`);
+			}
+		}
+		add("post-works", DELIVERY_TITLE, problems, `${withHook.length} of ${withHook.length} delivered`);
+	}
 	if (!input.builtOnly) for (const planned of PLANNED_CHECKS) checks.push({
 		id: planned.id,
 		title: planned.title,
@@ -3996,6 +4027,7 @@ 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`)}`);
 	const summary = summarise();
 	print("");
 	print(style.header(`${summary.pass} ok, ${summary.fail} fail, ${summary.skip} skipped`));
@@ -11082,8 +11114,15 @@ const COMMAND_REGISTRY = [
 	},
 	{
 		name: "doctor notifications",
-		description: "Check the layout against the server and the secrets store, step by step (read-only)",
+		description: "Check the layout against the server and the secrets store, step by step (read-only unless --deliver posts test messages)",
 		positionals: [],
+		options: [{
+			key: "deliver",
+			flag: "--deliver",
+			type: "confirm",
+			default: false,
+			message: "Also post a test message through every channel's webhook (it removes itself)?"
+		}],
 		supportsDryRun: false
 	},
 	{
@@ -11943,7 +11982,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)", (y) => y.option("scope", {
+	}).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", {
 		type: "string",
 		describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
 	}).option("provider", {
@@ -11953,6 +11992,10 @@ try {
 		type: "boolean",
 		default: false,
 		describe: "Leave out the features that are not built yet (a routine drift check)"
+	}).option("deliver", {
+		type: "boolean",
+		default: false,
+		describe: "Also post a test message through every channel's webhook, read it back and remove it"
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
@@ -11967,7 +12010,8 @@ try {
 			},
 			...argv.scope ? { scope: parseScope(argv.scope) } : {},
 			...argv.provider ? { provider: argv.provider } : {},
-			...argv.builtOnly ? { builtOnly: true } : {}
+			...argv.builtOnly ? { builtOnly: true } : {},
+			...argv.deliver ? { deliver: true } : {}
 		})).status === "fail") process.exitCode = 1;
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);