@theholocron/cli 5.0.0-alpha.211 → 5.0.0-alpha.213

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -548,6 +548,8 @@ commands and the config are provider-neutral; Discord is the first provider.
548
548
  | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
549
549
  | `holocron doctor notifications [--built-only] [--deliver]` | Step by step: does the server match the layout, do the secrets exist, and does a person (not the bot) own it. 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 |
550
550
 
551
+ Channels fed by another service are declared with `feeds` on the channel: `{ name: "uptime", webhook: true, feeds: { monitoring: true } }` (the object form `{ name?, webhook? }` overrides the alert channel's name, default `Discord #<channel>`, and the dedicated webhook's name, default the provider's). `setup` gives the channel a dedicated webhook and hands its URL straight to the `monitoring` provider through `Monitoring.ensureAlertChannel({ name, format: "discord", url? })`, which finds an alert channel of that name or creates one and subscribes every check; the URL is never stored as a secret. It needs a `monitoring` provider that implements `ensureAlertChannel` (Checkly does). Two feeds may not share an alert channel name, and a feed's webhook may not share the channel's own webhook name (compared without regard to case).
552
+
551
553
  Pinned messages are declared under the provider's `layout` as `pinned: [{ channel, content }]` (`channel` is a channel in the layout, `content` up to 2000 characters); the layout is the whole set of messages the bot has pinned in those channels.
552
554
 
553
555
  Config shape added for role sync and sign-in (all under the provider's `layout`):
package/dist/cli.mjs CHANGED
@@ -2822,10 +2822,20 @@ async function provisionChannel(deps, spec) {
2822
2822
  if (webhookCfg && !notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
2823
2823
  if (webhookCfg && isReservedSecret(secretName)) throw new Error(`secret name ${secretName} is reserved for the setup preflight -- choose another`);
2824
2824
  if (webhookCfg && !dryRun && !secrets) throw new Error("storing a webhook URL needs a `secrets` provider — add one to holocron.config.ts");
2825
+ const feed = spec.feeds?.monitoring;
2826
+ if (feed) {
2827
+ if (!deps.monitoring?.ensureAlertChannel) throw new Error(`channel ${spec.name} is fed by monitoring, which needs a \`monitoring\` provider that manages alert channels — add one to holocron.config.ts`);
2828
+ if (!notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
2829
+ if (webhookCfg && feed.webhook.toLowerCase() === webhookName.toLowerCase()) throw new Error(`channel ${spec.name}: the monitoring webhook and the channel's own webhook are both named ${webhookName} — rename one`);
2830
+ }
2825
2831
  if (dryRun) {
2826
2832
  print(` ${style.skip(`would ensure channel ${spec.name}${where}`)}`);
2827
2833
  if (tally) tally.skip += webhookCfg ? 2 : 1;
2828
2834
  if (webhookCfg) print(` ${style.skip(`would ensure webhook ${webhookName} and store its URL in ${secretName}`)}`);
2835
+ if (feed) {
2836
+ print(` ${style.skip(`would ensure webhook ${feed.webhook} and alert channel ${feed.name} (monitoring)`)}`);
2837
+ if (tally) tally.skip += 2;
2838
+ }
2829
2839
  return {
2830
2840
  name: spec.name,
2831
2841
  ...spec.category ? { category: spec.category } : {},
@@ -2849,7 +2859,10 @@ async function provisionChannel(deps, spec) {
2849
2859
  created: channel.created,
2850
2860
  ...channel.updated?.length ? { updated: channel.updated } : {}
2851
2861
  };
2852
- if (!webhookCfg) return outcome;
2862
+ if (!webhookCfg) {
2863
+ if (feed) await provisionFeed(deps, spec, feed, outcome);
2864
+ return outcome;
2865
+ }
2853
2866
  const hook = await notifications.ensureWebhook({
2854
2867
  channel: spec.name,
2855
2868
  name: webhookName,
@@ -2889,8 +2902,44 @@ async function provisionChannel(deps, spec) {
2889
2902
  if (tally) tally.ok++;
2890
2903
  }
2891
2904
  if (hook.avatarError) throw new Error(`webhook ${webhookName} is ready but setting its avatar failed (${hook.avatarError})`);
2905
+ if (feed) await provisionFeed(deps, spec, feed, outcome);
2892
2906
  return outcome;
2893
2907
  }
2908
+ /**
2909
+ * A dedicated webhook for the monitoring provider, handed to it as an alert channel. Its URL goes to the provider and
2910
+ * nowhere else: it is shown once and no secret holds it. When the webhook already exists the URL cannot be read back, so
2911
+ * an existing alert channel keeps the one it has and only its subscriptions are brought in line.
2912
+ */
2913
+ async function provisionFeed(deps, spec, feed, outcome) {
2914
+ const { notifications, monitoring, print, tally } = deps;
2915
+ const hook = await notifications.ensureWebhook({
2916
+ channel: spec.name,
2917
+ name: feed.webhook,
2918
+ ...spec.category ? { category: spec.category } : {}
2919
+ });
2920
+ let result;
2921
+ try {
2922
+ result = await monitoring.ensureAlertChannel({
2923
+ name: feed.name,
2924
+ format: "discord",
2925
+ ...hook.url ? { url: hook.url } : {}
2926
+ });
2927
+ } catch (err) {
2928
+ if (!hook.url) throw err;
2929
+ throw new Error(`webhook ${feed.webhook} was created but handing its URL to ${monitoring.providerName} failed (${describeProviderError(err)}) — delete the webhook in ${notifications.providerName} and re-run to get a fresh URL`, { cause: err });
2930
+ }
2931
+ const changed = result.created || result.updated.length > 0;
2932
+ const verb = result.created ? "created" : changed ? "updated" : "exists ";
2933
+ const what = result.updated.length > 0 ? `: ${result.updated.join(", ")}` : "";
2934
+ print(` ${(changed ? style.success : style.skip)(`${verb} alert channel ${feed.name} via webhook ${feed.webhook}${what} (${result.subscribed} checks)`)}`);
2935
+ if (tally) tally[changed ? "ok" : "skip"]++;
2936
+ outcome.alertChannel = {
2937
+ name: feed.name,
2938
+ created: result.created,
2939
+ updated: result.updated,
2940
+ subscribed: result.subscribed
2941
+ };
2942
+ }
2894
2943
  async function runNotificationsChannelAdd(input) {
2895
2944
  const print = input.print ?? ((line) => console.log(line));
2896
2945
  const logger = input.logger ?? getLogger();
@@ -4823,6 +4872,33 @@ async function withElevation(run, deps) {
4823
4872
  function webhookAvatarOf(layout, webhook) {
4824
4873
  return (typeof webhook === "object" ? webhook.avatar : void 0) ?? layout.webhookAvatar;
4825
4874
  }
4875
+ /** The names a channel's monitoring feed uses: the alert channel (`Discord #uptime`) and its dedicated webhook (`Checkly`). */
4876
+ function monitoringFeed(channel, feed, monitoring) {
4877
+ const own = typeof feed === "object" ? feed : {};
4878
+ const provider = monitoring.providerName;
4879
+ return {
4880
+ name: own.name ?? `Discord #${channel}`,
4881
+ webhook: own.webhook ?? provider.charAt(0).toUpperCase() + provider.slice(1)
4882
+ };
4883
+ }
4884
+ /**
4885
+ * The first reason the layout's monitoring feeds cannot work, or undefined. Checked before anything is created: two feeds
4886
+ * sharing an alert channel name would redirect each other's alerts, and a feed webhook named like the channel's own
4887
+ * (Discord matches names without regard to case) would share its URL, so revoking one revokes the other.
4888
+ */
4889
+ function feedProblem(layout, monitoring) {
4890
+ const alertNames = /* @__PURE__ */ new Map();
4891
+ for (const category of layout.categories ?? []) for (const channel of category.channels ?? []) {
4892
+ if (!channel.feeds?.monitoring) continue;
4893
+ if (!monitoring.ensureAlertChannel) return `channel \`${channel.name}\` is fed by monitoring, but the \`${monitoring.providerName}\` provider cannot manage alert channels`;
4894
+ const feed = monitoringFeed(channel.name, channel.feeds.monitoring, monitoring);
4895
+ const own = (typeof channel.webhook === "object" ? channel.webhook.name : void 0) ?? channel.name;
4896
+ if (channel.webhook && feed.webhook.toLowerCase() === own.toLowerCase()) return `channel \`${channel.name}\`: the monitoring webhook and the channel's own webhook are both named ${own} — rename one`;
4897
+ const other = alertNames.get(feed.name.toLowerCase());
4898
+ if (other) return `channels \`${other}\` and \`${channel.name}\` would both use the alert channel ${feed.name} — give one a distinct \`feeds.monitoring.name\``;
4899
+ alertNames.set(feed.name.toLowerCase(), channel.name);
4900
+ }
4901
+ }
4826
4902
  function effectiveAccess(category, channel) {
4827
4903
  if (!category && !channel) return void 0;
4828
4904
  return {
@@ -4968,6 +5044,13 @@ async function runNotificationsSetup(input$1) {
4968
5044
  name: org
4969
5045
  } : void 0);
4970
5046
  if (wantsSecrets && !scope && !dryRun) return refuse("no org to store secrets under — pass --scope or set `org` in holocron.config.ts");
5047
+ let monitoring;
5048
+ if ((layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.feeds?.monitoring))) {
5049
+ if (!loader.has("monitoring")) return refuse(whyMissing(loader, "monitoring", "a channel is fed by monitoring, which needs a `monitoring` capability — add a `monitoring` provider"));
5050
+ monitoring = loader.get("monitoring");
5051
+ const problem = feedProblem(layout, monitoring);
5052
+ if (problem) return refuse(problem);
5053
+ }
4971
5054
  const avatars = /* @__PURE__ */ new Map();
4972
5055
  const read = input$1.loadAvatar ?? loadAvatar;
4973
5056
  for (const channel of (layout.categories ?? []).flatMap((c) => c.channels ?? [])) {
@@ -5095,6 +5178,7 @@ async function runNotificationsSetup(input$1) {
5095
5178
  const outcome = await provisionChannel({
5096
5179
  notifications,
5097
5180
  ...secrets ? { secrets } : {},
5181
+ ...monitoring ? { monitoring } : {},
5098
5182
  scope: scope ?? { kind: "repo" },
5099
5183
  dryRun,
5100
5184
  print,
@@ -5104,7 +5188,8 @@ async function runNotificationsSetup(input$1) {
5104
5188
  category: category.name,
5105
5189
  ...channel.topic ? { topic: channel.topic } : {},
5106
5190
  ...effectiveAccess(category.access, channel.access) ? { access: effectiveAccess(category.access, channel.access) } : {},
5107
- ...webhook ? { webhook } : {}
5191
+ ...webhook ? { webhook } : {},
5192
+ ...channel.feeds?.monitoring ? { feeds: { monitoring: monitoringFeed(channel.name, channel.feeds.monitoring, monitoring) } } : {}
5108
5193
  });
5109
5194
  report.channels.push(outcome);
5110
5195
  if (outcome.webhook && !outcome.webhook.stored) report.failures.push({
@@ -8956,6 +9041,7 @@ async function runSetup(input) {
8956
9041
  logger
8957
9042
  });
8958
9043
  const content = astromechTurbo.turboConfig();
9044
+ const firstStep = steps.length;
8959
9045
  if (content === null) steps.push({
8960
9046
  capability: "source",
8961
9047
  step: "write turbo.json",
@@ -8966,7 +9052,6 @@ async function runSetup(input) {
8966
9052
  steps.push(await runStep("source", "write turbo.json", dryRun, async () => {
8967
9053
  await source.writeRepoFile("turbo.json", content);
8968
9054
  }));
8969
- print(formatStep(steps[steps.length - 1]));
8970
9055
  const rootPkgRaw = await readFile(join(input.context.repoRoot, "package.json"), "utf8").catch(() => null);
8971
9056
  const rootPkg = rootPkgRaw ? JSON.parse(rootPkgRaw) : null;
8972
9057
  const workspaceYaml = await readFile(join(input.context.repoRoot, "pnpm-workspace.yaml"), "utf8").catch(() => "");
@@ -8982,7 +9067,7 @@ async function runSetup(input) {
8982
9067
  }));
8983
9068
  }
8984
9069
  }
8985
- print(formatStep(steps[steps.length - 1]));
9070
+ for (const step of steps.slice(firstStep)) print(formatStep(step));
8986
9071
  }
8987
9072
  if (source.syncLabels) {
8988
9073
  steps.push(await runStep("source", "sync labels", dryRun, async () => {
@@ -9424,21 +9509,38 @@ async function runSetup(input) {
9424
9509
  print(style.hint(" · Administration — read and write"));
9425
9510
  print(style.hint(" · Code scanning alerts — read and write"));
9426
9511
  print(style.hint(" · Contents — read and write"));
9512
+ print(style.hint(" · Custom properties — read and write"));
9513
+ print(style.hint(" · Environments — read and write"));
9514
+ print(style.hint(" · Issues — read and write (labels)"));
9427
9515
  print(style.hint(" · Secret scanning alerts — read and write"));
9516
+ print(style.hint(" · Secrets — read and write"));
9517
+ print(style.hint(" · Variables — read and write (Actions variables)"));
9428
9518
  print(style.hint(" · Workflows — read and write"));
9429
9519
  print(style.hint(" · Metadata — read (added automatically)"));
9430
9520
  print("");
9431
- print(style.hint(" Org-scoped operations (teams, custom properties) require"));
9521
+ print(style.hint(" Org-scoped operations (teams, organization Actions variables) require"));
9432
9522
  print(style.hint(" HOLOCRON_ORG_TOKEN — a fine-grained PAT with resource owner set to the org:"));
9433
9523
  print("");
9434
9524
  print(style.hint(" · Administration — read and write (repository permission)"));
9435
9525
  print(style.hint(" · Members — read (organization permission)"));
9436
- print(style.hint(" · Organization custom properties — read and write (organization permission)"));
9526
+ print(style.hint(" · Variables — read and write (organization permission)"));
9437
9527
  print(style.hint(" · Metadata — read (repository permission, auto-included)"));
9438
9528
  print("");
9529
+ if (steps.some((s) => s.reason === "permissions" && /GitHub Pages/.test(s.step))) {
9530
+ print("");
9531
+ print(style.hint(" GitHub Pages uses HOLOCRON_DEPLOY_TOKEN (keyring key github.deploy):"));
9532
+ print("");
9533
+ print(style.hint(" · Pages — read and write"));
9534
+ print(style.hint(" · Administration — read and write"));
9535
+ print(style.hint(" · Metadata — read (added automatically)"));
9536
+ }
9537
+ print("");
9439
9538
  print(style.hint(" Create tokens at: https://github.com/settings/personal-access-tokens/new"));
9440
- print(style.hint(" Then re-run: holocron repo setup --token <your-admin-pat>"));
9441
- print(style.hint(" Store org token: HOLOCRON_ORG_TOKEN env var or keyring key github.org"));
9539
+ print(style.hint(" Store them: HOLOCRON_ADMIN_TOKEN / HOLOCRON_ORG_TOKEN / HOLOCRON_DEPLOY_TOKEN env vars,"));
9540
+ print(style.hint(" or keyring keys github.admin / github.org / github.deploy"));
9541
+ print(style.hint(" Then re-run: holocron repo setup"));
9542
+ print(style.hint(" (--token <pat> overrides every token, the org one included; use it only when one"));
9543
+ print(style.hint(" token covers everything.)"));
9442
9544
  }
9443
9545
  return {
9444
9546
  steps,