@theholocron/cli 5.0.0-alpha.180 → 5.0.0-alpha.181

package/dist/cli.mjs

@@ -407,6 +407,8 @@ const COMMAND_CONTEXTS = {
 	"repo setup": "workspace",
 	"secrets set": "workspace",
 	"secrets sync": "workspace",
+	"notifications channel add": "workspace",
+	"notifications setup": "workspace",
 	deploy: "workspace",
 	"deploy cleanup-preview": "workspace",
 	"monitoring check": "workspace",
@@ -3198,6 +3200,321 @@ 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, "_")}`;
+}
+/** 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 && !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 (${errorMessage(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");
+		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 = errorMessage(err);
+		print(`  ✗ ${message}`);
+		logger.warn({
+			channel: input.name,
+			reason: message
+		}, `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`
+* provider declares in `holocron.config.ts` (categories, channels, roles, and
+* a webhook secret per channel that asks for one).
+*
+* Idempotent: every step looks things up by name and creates only what is
+* missing, so it is safe to re-run and `--dry-run` previews it. A failing step
+* is reported and the rest still run.
+*
+* Run it from ONE repo per server — a layout is org-level, and putting it in a
+* shared preset would apply it from every repo.
+*/
+async function runNotificationsSetup(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 setup");
+	const dryRun = input.context.dryRun ?? false;
+	const report = {
+		status: "ok",
+		categories: [],
+		channels: [],
+		roles: [],
+		failures: []
+	};
+	const refuse = (message) => {
+		print(`  ✗ ${message}`);
+		logger.warn({ reason: message }, "notifications setup");
+		return {
+			...report,
+			status: "fail",
+			message
+		};
+	};
+	let notifications;
+	try {
+		notifications = pickProvisioner(loader.has("notifications") ? loader.get("notifications") : [], input.provider);
+	} catch (err) {
+		return refuse(errorMessage(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`);
+	const wantsWebhook = (layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.webhook));
+	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"));
+		secrets = loader.get("secrets");
+	}
+	const org = input.context.org;
+	const scope = input.scope ?? (org ? {
+		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");
+	const taken = /* @__PURE__ */ new Map();
+	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);
+	}
+	print(`Holocron notifications setup — ${notifications.providerName}${dryRun ? " (dry-run)" : ""}`);
+	const attempt = async (step, fn) => {
+		try {
+			await fn();
+		} catch (err) {
+			const message = errorMessage(err);
+			print(`  ✗ ${step}: ${message}`);
+			report.failures.push({
+				step,
+				message
+			});
+		}
+	};
+	for (const category of layout.categories ?? []) {
+		print(`\n${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}`);
+				return;
+			}
+			const made = await notifications.ensureCategory(category.name);
+			print(`  ${made.created ? "✓ created" : "· exists "} category ${category.name}`);
+		});
+		for (const channel of category.channels ?? []) await attempt(`channel ${channel.name}`, async () => {
+			const outcome = await provisionChannel({
+				notifications,
+				...secrets ? { secrets } : {},
+				scope: scope ?? { kind: "repo" },
+				dryRun,
+				print
+			}, {
+				name: channel.name,
+				category: category.name,
+				...channel.topic ? { topic: channel.topic } : {},
+				...channel.webhook ? { webhook: channel.webhook === true ? {} : channel.webhook } : {}
+			});
+			report.channels.push(outcome);
+			if (outcome.webhook && !outcome.webhook.stored) report.failures.push({
+				step: `webhook ${outcome.webhook.name}`,
+				message: outcome.webhook.note
+			});
+		});
+	}
+	if ((layout.roles ?? []).length > 0) print("\nRoles");
+	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}`);
+			report.roles.push({
+				name: role.name,
+				created: false
+			});
+			return;
+		}
+		const made = await notifications.ensureRole({
+			name: role.name,
+			...role.mentionable !== void 0 ? { mentionable: role.mentionable } : {}
+		});
+		const outcome = {
+			name: role.name,
+			id: made.id,
+			created: made.created
+		};
+		report.roles.push(outcome);
+		print(`  ${made.created ? "✓ created" : "· exists "} role ${role.name} (id ${made.id})`);
+	});
+	if (report.failures.length > 0) {
+		report.status = "fail";
+		print(`\n${report.failures.length} step(s) need attention`);
+	} else if (dryRun) report.status = "dry-run";
+	logger.info({
+		provider: notifications.providerName,
+		channels: report.channels.length,
+		roles: report.roles.length,
+		failures: report.failures.length,
+		status: report.status
+	}, "notifications setup");
+	return report;
+}
+//#endregion
 //#region src/commands/npm-bump-versions/npm-bump-versions.ts
 async function runNpmBumpVersions(input) {
 	const print = input.print ?? ((line) => console.log(line));
@@ -9324,6 +9641,22 @@ const COMMAND_REGISTRY = [
 		}],
 		supportsDryRun: true
 	},
+	{
+		name: "notifications channel add",
+		description: "Create a notification channel, optionally with a webhook whose URL is stored as a secret",
+		positionals: [{
+			key: "name",
+			message: "Channel name:",
+			type: "input"
+		}],
+		supportsDryRun: true
+	},
+	{
+		name: "notifications setup",
+		description: "Apply the server layout a notifications provider declares in holocron.config.ts",
+		positionals: [],
+		supportsDryRun: true
+	},
 	{
 		name: "deploy",
 		description: "Trigger a deployment via the configured `deployment` capability",
@@ -10804,6 +11137,80 @@ try {
 		})).summary.fail > 0) process.exitCode = 1;
 	}).command("$0", false, () => {}, async (argv) => {
 		await launchGroupMenu("secrets", argv);
+	}), () => {}).command("notifications", "Provision notification channels, webhooks and roles", (g) => g.command("channel", "Manage notification channels", (c) => c.command("add [name]", "Create a channel, optionally with a webhook whose URL is stored as a secret", (y) => y.positional("name", {
+		type: "string",
+		describe: "Channel name (e.g. alerts)"
+	}).option("category", {
+		type: "string",
+		describe: "Put the channel under this category (created if missing)"
+	}).option("topic", {
+		type: "string",
+		describe: "Channel topic"
+	}).option("with-webhook", {
+		type: "boolean",
+		default: false,
+		describe: "Also create a webhook and store its URL as a secret (the URL is never printed)"
+	}).option("webhook-name", {
+		type: "string",
+		describe: "Webhook display name (default: the channel name)"
+	}).option("secret", {
+		type: "string",
+		describe: "Secret to store the URL in (default: HOLOCRON_NOTIFY_WEBHOOK_<CHANNEL>)"
+	}).option("scope", {
+		type: "string",
+		describe: "Secret scope: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
+	}).option("provider", {
+		type: "string",
+		describe: "Which notifications provider, when several can provision"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const [name] = await promptForPositionals(getEntry("notifications channel add"), argv);
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runNotificationsChannelAdd({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			name,
+			...argv.category ? { category: argv.category } : {},
+			...argv.topic ? { topic: argv.topic } : {},
+			...argv.withWebhook ? { withWebhook: true } : {},
+			...argv.webhookName ? { webhookName: argv.webhookName } : {},
+			...argv.secret ? { secret: argv.secret } : {},
+			...argv.scope ? { scope: parseScope(argv.scope) } : {},
+			...argv.provider ? { provider: argv.provider } : {}
+		})).status === "fail") process.exitCode = 1;
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchGroupMenu("notifications channel", argv);
+	}), () => {}).command("setup", "Apply the server layout a notifications provider declares in holocron.config.ts", (y) => y.option("scope", {
+		type: "string",
+		describe: "Webhook secret scope: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
+	}).option("provider", {
+		type: "string",
+		describe: "Which notifications provider, when several can provision"
+	}), async (argv) => {
+		const tokens = tokenContext(argv.token);
+		if (!tokens) return;
+		const loaded = await loadConfig(argv.cwd);
+		applyResolvedConfig(argv, loaded.resolved);
+		if ((await runNotificationsSetup({
+			loaded,
+			context: {
+				repoRoot: argv.cwd,
+				dryRun: argv.dryRun,
+				...tokens,
+				org: resolveOrg(argv, loaded.resolved)
+			},
+			...argv.scope ? { scope: parseScope(argv.scope) } : {},
+			...argv.provider ? { provider: argv.provider } : {}
+		})).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", {
 		type: "string",
 		default: "theholocron/.github",