@theholocron/cli 5.0.0-alpha.219 → 5.0.0-alpha.220

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
@@ -550,6 +550,8 @@ commands and the config are provider-neutral; Discord is the first provider.
550
550
 
551
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?, avatar? }` overrides the alert channel's name, default `Message to #<channel>`, the dedicated webhook's name, default the provider's, and gives that webhook a picture, a file path or `https://` URL, or `{ url, image }` (the URL is tried first, the file in the repo is the fallback), else the provider's own icon (`Monitoring.icon`, a URL and an embedded `data:` image; Checkly provides one), else the layout's `webhookAvatar`, else the layout's `webhookAvatar`). `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
552
 
553
+ Channels fed by the error tracker add `feeds: { errors: true }` and a layout `relay: { host, zone?, script?, code? }`: `setup` makes a dedicated webhook, points `host` at the Comlink Worker (a proxied DNS record via `dns`), and deploys it via `workers.deployScript` with the webhook URL as `COMLINK_<SOURCE>_WEBHOOK`. The URL never leaves the Worker's secret; other secrets on the script are kept. Needs `errors`, `workers` and `dns`; only one channel may be fed.
554
+
553
555
  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.
554
556
 
555
557
  Config shape added for role sync and sign-in (all under the provider's `layout`):
package/dist/cli.mjs CHANGED
@@ -2861,6 +2861,8 @@ async function provisionChannel(deps, spec) {
2861
2861
  if (!notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
2862
2862
  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`);
2863
2863
  }
2864
+ const relay = spec.feeds?.errors;
2865
+ if (relay && !notifications.ensureWebhook) throw new Error(`\`${notifications.providerName}\` cannot create webhooks`);
2864
2866
  if (dryRun) {
2865
2867
  print(` ${style.skip(`would ensure channel ${spec.name}${where}`)}`);
2866
2868
  if (tally) tally.skip += webhookCfg ? 2 : 1;
@@ -2869,6 +2871,10 @@ async function provisionChannel(deps, spec) {
2869
2871
  print(` ${style.skip(`would ensure webhook ${feed.webhook} and alert channel ${feed.name} (monitoring)`)}`);
2870
2872
  if (tally) tally.skip += 2;
2871
2873
  }
2874
+ if (relay) {
2875
+ print(` ${style.skip(`would ensure webhook ${relay.webhook} for the relay Worker (errors)`)}`);
2876
+ if (tally) tally.skip++;
2877
+ }
2872
2878
  return {
2873
2879
  name: spec.name,
2874
2880
  ...spec.category ? { category: spec.category } : {},
@@ -2894,6 +2900,7 @@ async function provisionChannel(deps, spec) {
2894
2900
  };
2895
2901
  if (!webhookCfg) {
2896
2902
  if (feed) await provisionFeed(deps, spec, feed, outcome);
2903
+ if (relay) await provisionRelayFeed(deps, spec, relay, outcome);
2897
2904
  return outcome;
2898
2905
  }
2899
2906
  const hook = await notifications.ensureWebhook({
@@ -2936,9 +2943,39 @@ async function provisionChannel(deps, spec) {
2936
2943
  }
2937
2944
  if (hook.avatarError) throw new Error(`webhook ${webhookName} is ready but setting its avatar failed (${hook.avatarError})`);
2938
2945
  if (feed) await provisionFeed(deps, spec, feed, outcome);
2946
+ if (relay) await provisionRelayFeed(deps, spec, relay, outcome);
2939
2947
  return outcome;
2940
2948
  }
2941
2949
  /**
2950
+ * A dedicated webhook for the relay Worker. Its URL goes to the caller (which hands it to the Worker as a secret) and
2951
+ * nowhere else. The bot's own webhook hands its URL out on every read, so a re-run gets it again; one made by a
2952
+ * person does not, and is reported rather than guessed at.
2953
+ */
2954
+ async function provisionRelayFeed(deps, spec, feed, outcome) {
2955
+ const { notifications, print, tally } = deps;
2956
+ const hook = await notifications.ensureWebhook({
2957
+ channel: spec.name,
2958
+ name: feed.webhook,
2959
+ ...spec.category ? { category: spec.category } : {},
2960
+ ...feed.avatar ? { avatar: feed.avatar } : {}
2961
+ });
2962
+ const avatarSet = hook.updated?.includes("avatar") ?? false;
2963
+ print(` ${(hook.created || avatarSet ? style.success : style.skip)(`${hook.created ? "created" : "found "} webhook ${feed.webhook} for the relay${avatarSet ? " (avatar set)" : ""}`)}`);
2964
+ if (tally) {
2965
+ const done = Number(hook.created) + Number(avatarSet);
2966
+ if (done > 0) tally.ok += done;
2967
+ else tally.skip++;
2968
+ }
2969
+ outcome.relayWebhook = {
2970
+ name: feed.webhook,
2971
+ created: hook.created,
2972
+ ...avatarSet ? { updated: ["avatar"] } : {}
2973
+ };
2974
+ if (!hook.url) throw new Error(`webhook ${feed.webhook} already exists and its URL cannot be read back, so the relay cannot post through it — delete it in the provider and re-run`);
2975
+ deps.onRelayWebhook?.(hook.url);
2976
+ if (hook.avatarError) throw new Error(`webhook ${feed.webhook} is ready but setting its avatar failed (${hook.avatarError})`);
2977
+ }
2978
+ /**
2942
2979
  * A dedicated webhook for the monitoring provider, handed to it as an alert channel. Its URL goes to the provider and
2943
2980
  * nowhere else: it is shown once and no secret holds it. When the webhook already exists the URL cannot be read back, so
2944
2981
  * an existing alert channel keeps the one it has and only its subscriptions are brought in line.
@@ -4841,6 +4878,88 @@ async function lockConfig(filepath) {
4841
4878
  };
4842
4879
  }
4843
4880
  //#endregion
4881
+ //#region src/commands/notifications-setup/avatar-problem.ts
4882
+ /** The first reason a feed's `avatar` cannot work, or undefined. `feed` names the key for the message (`monitoring`, `errors`). */
4883
+ function avatarProblem(channel, feed, picture) {
4884
+ if (typeof picture !== "object") return void 0;
4885
+ if (!picture.url && !picture.image) return `channel \`${channel}\`: \`feeds.${feed}.avatar\` needs a \`url\`, an \`image\`, or both`;
4886
+ if (picture.url && !/^https:\/\//i.test(picture.url)) return `channel \`${channel}\`: \`feeds.${feed}.avatar.url\` must be an https:// URL`;
4887
+ if (picture.image && /^https?:\/\//i.test(picture.image)) return `channel \`${channel}\`: \`feeds.${feed}.avatar.image\` must be a file in the repo, not a URL`;
4888
+ }
4889
+ /** The webhook name a channel's error feed uses: its own, else the provider's name, capitalised (`Sentry`). */
4890
+ function errorsFeedWebhook(feed, errors) {
4891
+ return (typeof feed === "object" ? feed.webhook : void 0) ?? capitalised(errors.providerName);
4892
+ }
4893
+ const capitalised = (name) => name.charAt(0).toUpperCase() + name.slice(1);
4894
+ /** The Worker binding that holds the webhook URL for a source (the contract `apps/comlink` reads). */
4895
+ const relayWebhookBinding = (source) => `COMLINK_${source.toUpperCase()}_WEBHOOK`;
4896
+ /** Whether any channel in the layout is fed by the error tracker. */
4897
+ function wantsRelay(layout) {
4898
+ return (layout.categories ?? []).some((c) => (c.channels ?? []).some((ch) => ch.feeds?.errors));
4899
+ }
4900
+ /**
4901
+ * The first reason the relay cannot be deployed, or undefined. One source has one webhook, so only one channel can be
4902
+ * fed by it; and the Worker needs somewhere to answer.
4903
+ */
4904
+ function relayProblem(layout, errors, monitoring) {
4905
+ const fed = (layout.categories ?? []).flatMap((c) => c.channels ?? []).filter((ch) => ch.feeds?.errors);
4906
+ if (fed.length === 0) return void 0;
4907
+ if (!layout.relay?.host) return `channel \`${fed[0].name}\` is fed by the error tracker, which needs \`relay.host\` — where the relay Worker answers`;
4908
+ if (fed.length > 1) return `channels ${fed.map((c) => `\`${c.name}\``).join(" and ")} are all fed by the error tracker, but its relay posts to one channel — feed one`;
4909
+ const channel = fed[0];
4910
+ const errorsFeed = channel.feeds.errors;
4911
+ const picture = typeof errorsFeed === "object" ? errorsFeed.avatar : void 0;
4912
+ const pictureProblem = avatarProblem(channel.name, "errors", picture);
4913
+ if (pictureProblem) return pictureProblem;
4914
+ if (errors) {
4915
+ const feed = errorsFeedWebhook(errorsFeed, errors).toLowerCase();
4916
+ const own = (typeof channel.webhook === "object" ? channel.webhook.name : void 0) ?? channel.name;
4917
+ if (channel.webhook && feed === own.toLowerCase()) return `channel \`${channel.name}\`: the relay webhook and the channel's own webhook are both named ${own} — rename one`;
4918
+ const monitoringFeed = channel.feeds.monitoring;
4919
+ if (monitoring && monitoringFeed) {
4920
+ const other = (typeof monitoringFeed === "object" ? monitoringFeed.webhook : void 0) ?? capitalised(monitoring.providerName);
4921
+ if (feed === other.toLowerCase()) return `channel \`${channel.name}\`: the relay webhook and the monitoring webhook are both named ${other} — rename one`;
4922
+ }
4923
+ }
4924
+ }
4925
+ /**
4926
+ * What to hand the `dns` capability as the zone: the layout's, else the host itself. The provider looks a name up from
4927
+ * the full name towards the apex until it finds a zone it holds, so this is right for any suffix (`example.co.uk`).
4928
+ */
4929
+ const relayZone = (relay) => relay.zone ?? relay.host;
4930
+ /**
4931
+ * Deploy the Worker with its webhook secret and its route, then point the host at it with a proxied placeholder record
4932
+ * (the Worker answers before any origin is asked). The built file is read first and the DNS record comes last, so a
4933
+ * missing build or a failed deploy leaves the host untouched.
4934
+ */
4935
+ async function deployRelay(input) {
4936
+ const { relay, workers, dns } = input;
4937
+ const path = join(input.repoRoot, relay.code ?? "apps/comlink/dist/worker.js");
4938
+ let code;
4939
+ try {
4940
+ code = await (input.readCode ?? ((p) => readFile(p, "utf8")))(path);
4941
+ } catch {
4942
+ throw new Error(`the relay Worker is not built (${relay.code ?? "apps/comlink/dist/worker.js"}) — run \`pnpm --filter @theholocron/comlink run delivery.build\``);
4943
+ }
4944
+ const script = relay.script ?? "comlink";
4945
+ await workers.deployScript(script, {
4946
+ code,
4947
+ secrets: { [relayWebhookBinding(input.source)]: input.webhook },
4948
+ routes: [`${relay.host}/*`]
4949
+ });
4950
+ await dns.upsertRecord(relayZone(relay), {
4951
+ type: "AAAA",
4952
+ name: relay.host,
4953
+ content: "100::",
4954
+ ttl: 1,
4955
+ proxied: true
4956
+ });
4957
+ return {
4958
+ host: relay.host,
4959
+ script
4960
+ };
4961
+ }
4962
+ //#endregion
4844
4963
  //#region src/commands/notifications-setup/with-elevation.ts
4845
4964
  /**
4846
4965
  * Runs an edit that may need a permission the bot should not keep. When the provider says it does
@@ -4949,11 +5068,8 @@ function feedProblem(layout, monitoring) {
4949
5068
  if (!channel.feeds?.monitoring) continue;
4950
5069
  if (!monitoring.ensureAlertChannel) return `channel \`${channel.name}\` is fed by monitoring, but the \`${monitoring.providerName}\` provider cannot manage alert channels`;
4951
5070
  const picture = typeof channel.feeds.monitoring === "object" ? channel.feeds.monitoring.avatar : void 0;
4952
- if (typeof picture === "object") {
4953
- if (!picture.url && !picture.image) return `channel \`${channel.name}\`: \`feeds.monitoring.avatar\` needs a \`url\`, an \`image\`, or both`;
4954
- if (picture.url && !/^https:\/\//i.test(picture.url)) return `channel \`${channel.name}\`: \`feeds.monitoring.avatar.url\` must be an https:// URL`;
4955
- if (picture.image && /^https?:\/\//i.test(picture.image)) return `channel \`${channel.name}\`: \`feeds.monitoring.avatar.image\` must be a file in the repo, not a URL`;
4956
- }
5071
+ const pictureProblem = avatarProblem(channel.name, "monitoring", picture);
5072
+ if (pictureProblem) return pictureProblem;
4957
5073
  const feed = monitoringFeed(channel.name, channel.feeds.monitoring, monitoring);
4958
5074
  const own = (typeof channel.webhook === "object" ? channel.webhook.name : void 0) ?? channel.name;
4959
5075
  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`;
@@ -5114,7 +5230,25 @@ async function runNotificationsSetup(input$1) {
5114
5230
  const problem = feedProblem(layout, monitoring);
5115
5231
  if (problem) return refuse(problem);
5116
5232
  }
5233
+ let errors;
5234
+ let workers;
5235
+ let dns;
5236
+ if (wantsRelay(layout)) {
5237
+ const early = relayProblem(layout);
5238
+ if (early) return refuse(early);
5239
+ for (const [key, what] of [
5240
+ ["errors", "an `errors` provider (the tracker whose alerts it carries)"],
5241
+ ["workers", "a `workers` provider (where it runs)"],
5242
+ ["dns", "a `dns` provider (for its host)"]
5243
+ ]) if (!loader.has(key)) return refuse(whyMissing(loader, key, `a channel is fed by the error tracker, which needs ${what} — add one`));
5244
+ errors = loader.get("errors");
5245
+ workers = loader.get("workers");
5246
+ dns = loader.get("dns");
5247
+ const clash = relayProblem(layout, errors, monitoring);
5248
+ if (clash) return refuse(clash);
5249
+ }
5117
5250
  const feedAvatarsOf = (channel) => channel.feeds?.monitoring ? feedAvatarOf(layout, channel.feeds.monitoring, monitoring) : [];
5251
+ const errorsAvatarsOf = (channel) => channel.feeds?.errors ? feedAvatarOf(layout, channel.feeds.errors) : [];
5118
5252
  const avatars = /* @__PURE__ */ new Map();
5119
5253
  const read = input$1.loadAvatar ?? ((source) => loadAvatar(source, input$1.context.repoRoot));
5120
5254
  for (const channel of (layout.categories ?? []).flatMap((c) => c.channels ?? [])) {
@@ -5124,12 +5258,13 @@ async function runNotificationsSetup(input$1) {
5124
5258
  } catch (err) {
5125
5259
  return refuse(`webhook avatar \`${describeAvatarSource(own)}\`: ${errorMessage(err)}`);
5126
5260
  }
5127
- const feedSources = feedAvatarsOf(channel);
5128
- const feedKey = JSON.stringify(feedSources);
5129
- if (feedSources.length > 0 && !avatars.has(feedKey)) try {
5130
- avatars.set(feedKey, await loadFirstAvatar(feedSources, read, (source, reason, moreToTry) => print(` ${style.skip(`avatar ${describeAvatarSource(source)} could not be read (${reason})${moreToTry ? "; trying the next" : ""}`)}`)));
5131
- } catch (err) {
5132
- return refuse(`webhook avatar ${errorMessage(err)}`);
5261
+ for (const feedSources of [feedAvatarsOf(channel), errorsAvatarsOf(channel)]) {
5262
+ const feedKey = JSON.stringify(feedSources);
5263
+ if (feedSources.length > 0 && !avatars.has(feedKey)) try {
5264
+ avatars.set(feedKey, await loadFirstAvatar(feedSources, read, (source, reason, moreToTry) => print(` ${style.skip(`avatar ${describeAvatarSource(source)} could not be read (${reason})${moreToTry ? "; trying the next" : ""}`)}`)));
5265
+ } catch (err) {
5266
+ return refuse(`webhook avatar ${errorMessage(err)}`);
5267
+ }
5133
5268
  }
5134
5269
  }
5135
5270
  if (secrets && scope && !dryRun) try {
@@ -5158,6 +5293,7 @@ async function runNotificationsSetup(input$1) {
5158
5293
  } catch (err) {
5159
5294
  return refuse(describeProviderError(err), logReason(err));
5160
5295
  }
5296
+ let relayWebhook;
5161
5297
  const tally = {
5162
5298
  ok: 0,
5163
5299
  skip: 0
@@ -5249,6 +5385,7 @@ async function runNotificationsSetup(input$1) {
5249
5385
  notifications,
5250
5386
  ...secrets ? { secrets } : {},
5251
5387
  ...monitoring ? { monitoring } : {},
5388
+ onRelayWebhook: (url) => void (relayWebhook = url),
5252
5389
  scope: scope ?? { kind: "repo" },
5253
5390
  dryRun,
5254
5391
  print,
@@ -5259,10 +5396,16 @@ async function runNotificationsSetup(input$1) {
5259
5396
  ...channel.topic ? { topic: channel.topic } : {},
5260
5397
  ...effectiveAccess(category.access, channel.access) ? { access: effectiveAccess(category.access, channel.access) } : {},
5261
5398
  ...webhook ? { webhook } : {},
5262
- ...channel.feeds?.monitoring ? { feeds: { monitoring: {
5263
- ...monitoringFeed(channel.name, channel.feeds.monitoring, monitoring),
5264
- ...feedAvatarsOf(channel).length > 0 ? { avatar: avatars.get(JSON.stringify(feedAvatarsOf(channel))) } : {}
5265
- } } } : {}
5399
+ ...channel.feeds?.monitoring || channel.feeds?.errors ? { feeds: {
5400
+ ...channel.feeds.monitoring ? { monitoring: {
5401
+ ...monitoringFeed(channel.name, channel.feeds.monitoring, monitoring),
5402
+ ...feedAvatarsOf(channel).length > 0 ? { avatar: avatars.get(JSON.stringify(feedAvatarsOf(channel))) } : {}
5403
+ } } : {},
5404
+ ...channel.feeds.errors ? { errors: {
5405
+ webhook: errorsFeedWebhook(channel.feeds.errors, errors),
5406
+ ...errorsAvatarsOf(channel).length > 0 ? { avatar: avatars.get(JSON.stringify(errorsAvatarsOf(channel))) } : {}
5407
+ } } : {}
5408
+ } } : {}
5266
5409
  });
5267
5410
  report.channels.push(outcome);
5268
5411
  if (outcome.webhook && !outcome.webhook.stored) report.failures.push({
@@ -5271,6 +5414,28 @@ async function runNotificationsSetup(input$1) {
5271
5414
  });
5272
5415
  });
5273
5416
  }
5417
+ if (errors && workers && dns && wantsRelay(layout)) {
5418
+ print(`\n${style.header("Relay")}`);
5419
+ await attempt(`relay ${layout.relay.host}`, async () => {
5420
+ if (dryRun) {
5421
+ print(` ${style.skip(`would deploy the relay Worker at ${layout.relay.host}`)}`);
5422
+ tally.skip++;
5423
+ return;
5424
+ }
5425
+ if (!relayWebhook) throw new Error("no relay webhook to give the Worker (its channel failed above)");
5426
+ const deployed = await deployRelay({
5427
+ relay: layout.relay,
5428
+ source: errors.providerName,
5429
+ webhook: relayWebhook,
5430
+ repoRoot: input$1.context.repoRoot,
5431
+ workers,
5432
+ dns,
5433
+ ...input$1.readRelayCode ? { readCode: input$1.readRelayCode } : {}
5434
+ });
5435
+ print(` ${style.success(`deployed ${deployed.script} at ${deployed.host}`)}`);
5436
+ tally.ok++;
5437
+ });
5438
+ }
5274
5439
  if (layout.server || layout.welcome || layout.onboarding || (layout.pinned?.length ?? 0) > 0 || layout.application || layout.everyone) {
5275
5440
  print(`\n${style.header("Server")}`);
5276
5441
  const apply = async (label, declared, run) => {