@theholocron/cli 5.0.0-alpha.205 โ†’ 5.0.0-alpha.206

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
@@ -535,7 +535,7 @@ export default acmeConfig;
535
535
 
536
536
  A `notifications` provider can declare a whole server in `holocron.config.ts`
537
537
  (`layout`: categories, channels, roles, access, server settings, welcome screen,
538
- onboarding, the bot application) and the CLI applies and checks it. The
538
+ pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
539
539
  commands and the config are provider-neutral; Discord is the first provider.
540
540
 
541
541
  | Command | What it does |
@@ -547,6 +547,8 @@ commands and the config are provider-neutral; Discord is the first provider.
547
547
  | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
548
548
  | `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 |
549
549
 
550
+ 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.
551
+
550
552
  Config shape added for role sync and sign-in (all under the provider's `layout`):
551
553
 
552
554
  | Field | Meaning |
package/dist/cli.mjs CHANGED
@@ -204,6 +204,18 @@ const CARDINALITY = {
204
204
  * own requirements at call time.
205
205
  */
206
206
  const REQUIRED_CAPABILITIES = [];
207
+ /**
208
+ * A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
209
+ * needs to give it for one run and take it away again, so `setup` can walk them through it.
210
+ */
211
+ var ElevationRequiredError = class extends Error {
212
+ elevation;
213
+ name = "ElevationRequiredError";
214
+ constructor(message, elevation, options) {
215
+ super(message, options);
216
+ this.elevation = elevation;
217
+ }
218
+ };
207
219
  //#endregion
208
220
  //#region src/config/config/config.ts
209
221
  var ConfigError = class extends Error {
@@ -3541,6 +3553,7 @@ const promptKey = (p) => JSON.stringify([
3541
3553
  const accessText = (v) => v === "everyone" ? "everyone" : v.length === 0 ? "nobody (bots and webhooks only)" : v.join(", ");
3542
3554
  const shown = (s) => sanitizeDetail(s);
3543
3555
  const WELCOME_TITLE = "welcome screen and onboarding set";
3556
+ const PINNED_TITLE = "pinned messages in place";
3544
3557
  const APP_TITLE = "bot description, tags, install link and URLs set";
3545
3558
  const AVATAR_TITLE = "webhook names and avatars set";
3546
3559
  const DELIVERY_TITLE = "test message delivered through a webhook";
@@ -3670,6 +3683,7 @@ async function runDoctorNotifications(input) {
3670
3683
  ["access", ACCESS_TITLE],
3671
3684
  ["server-settings", SERVER_TITLE],
3672
3685
  ["welcome-onboarding", WELCOME_TITLE],
3686
+ ["pinned", PINNED_TITLE],
3673
3687
  ["app-settings", APP_TITLE]
3674
3688
  ]) failed(id, title, "not checked: could not read the server");
3675
3689
  } else {
@@ -3876,6 +3890,19 @@ async function runDoctorNotifications(input) {
3876
3890
  }
3877
3891
  const welcomeParts = (wantWelcome ? 1 : 0) + (wantOnboarding ? 1 : 0);
3878
3892
  add("welcome-onboarding", WELCOME_TITLE, [...welcomeProblems, ...onboardingProblems], welcomeParts === 0 ? "none declared" : `${welcomeParts} of ${welcomeParts} as declared`);
3893
+ const wantPinned = layout.pinned ?? [];
3894
+ const pinnedProblems = [];
3895
+ if (wantPinned.length > 0) {
3896
+ if (inspected.pinnedError) pinnedProblems.push(`not checked: could not read the pinned messages (${shown(inspected.pinnedError)})`);
3897
+ else if (!inspected.pinned) pinnedProblems.push("the provider did not report the pinned messages");
3898
+ else wantPinned.forEach((want, i) => {
3899
+ const have = inspected.pinned[i];
3900
+ if (!have) pinnedProblems.push(`#${shown(want.channel)}: not checked (the provider gave no answer)`);
3901
+ else if (have.state === "missing") pinnedProblems.push(`#${shown(have.channel)}: no pinned message from the bot`);
3902
+ else if (have.state === "different") pinnedProblems.push(`#${shown(have.channel)}: the pinned messages differ from the layout`);
3903
+ });
3904
+ }
3905
+ add("pinned", PINNED_TITLE, pinnedProblems, wantPinned.length === 0 ? "none declared" : `${wantPinned.length} of ${wantPinned.length} in place`);
3879
3906
  const wantApp = layout.application;
3880
3907
  const appProblems = [];
3881
3908
  if (wantApp) {
@@ -4723,6 +4750,59 @@ async function lockConfig(filepath) {
4723
4750
  };
4724
4751
  }
4725
4752
  //#endregion
4753
+ //#region src/commands/notifications-setup/with-elevation.ts
4754
+ /**
4755
+ * Runs an edit that may need a permission the bot should not keep. When the provider says it does
4756
+ * ({@link ElevationRequiredError}) and a person is there to answer, walks them through it: the link that gives the
4757
+ * permission, then a retry; and afterwards the link that takes it away, then a check that it really is gone. The
4758
+ * consent clicks stay theirs; the ordering and the "forgot to take it away" mistake do not.
4759
+ *
4760
+ * Taking it away is attempted whatever the retry does, and anything that stops it being done or proven is a `todo`
4761
+ * (reported as a failure) or, when the retry itself failed, a printed failure beside the error.
4762
+ *
4763
+ * Without someone to answer (`pause` absent) the error is passed on unchanged, so a script still gets the
4764
+ * explanation it always did.
4765
+ */
4766
+ async function withElevation(run, deps) {
4767
+ try {
4768
+ return await run();
4769
+ } catch (err) {
4770
+ const { notifications, pause, print } = deps;
4771
+ if (!(err instanceof ElevationRequiredError) || !pause || !err.elevation.grantUrl) throw err;
4772
+ const { permission, grantUrl, revokeUrl, applied } = err.elevation;
4773
+ if (await notifications.holdsPermission?.(permission).catch(() => false)) throw err;
4774
+ print(` ${style.skip(`${deps.label} needs ${permission} for this one edit`)}`);
4775
+ print(` 1. approve it: ${grantUrl}`);
4776
+ await pause(`Press Enter once ${permission} is approved to try again`);
4777
+ let result;
4778
+ let failure;
4779
+ try {
4780
+ result = await run();
4781
+ } catch (retryErr) {
4782
+ failure = retryErr;
4783
+ }
4784
+ let leftover;
4785
+ if (!revokeUrl) leftover = `no link could be built to take ${permission} away; remove it from ${notifications.providerName}'s role by hand, then run \`holocron doctor notifications\``;
4786
+ else {
4787
+ print(` 2. take it away again: ${revokeUrl}`);
4788
+ await pause(`Press Enter once ${permission} is taken away to check it`);
4789
+ const holdsNow = await notifications.holdsPermission?.(permission).catch(() => void 0);
4790
+ if (holdsNow === void 0) leftover = `could not check that ${permission} is gone; confirm it in ${notifications.providerName}'s role, then run \`holocron doctor notifications\``;
4791
+ else if (holdsNow) leftover = `${notifications.providerName} still holds ${permission}; use the link above to take it away, then run \`holocron doctor notifications\` to check`;
4792
+ else print(` ${style.success(`${permission} is gone again`)}`);
4793
+ }
4794
+ if (failure !== void 0) {
4795
+ if (leftover) print(` ${style.fail(leftover)}`);
4796
+ throw failure;
4797
+ }
4798
+ return {
4799
+ ...result,
4800
+ updated: [.../* @__PURE__ */ new Set([...applied ?? [], ...result.updated])],
4801
+ todo: [...result.todo ?? [], ...leftover ? [leftover] : []]
4802
+ };
4803
+ }
4804
+ }
4805
+ //#endregion
4726
4806
  //#region src/commands/notifications-setup/notifications-setup.ts
4727
4807
  /**
4728
4808
  * `holocron notifications setup` โ€” apply the server layout a `notifications`
@@ -4822,6 +4902,11 @@ function serverLayoutProblem(layout) {
4822
4902
  const problem = channel("welcome:", entry.channel);
4823
4903
  if (problem) return problem;
4824
4904
  }
4905
+ for (const pin of layout.pinned ?? []) {
4906
+ const problem = channel("pinned:", pin.channel);
4907
+ if (problem) return problem;
4908
+ if (pin.content.trim() === "") return `pinned: the message for \`${pin.channel}\` is empty`;
4909
+ }
4825
4910
  const onboarding = layout.onboarding;
4826
4911
  for (const name of onboarding?.defaultChannels ?? []) {
4827
4912
  const problem = channel("onboarding: `defaultChannels`", name);
@@ -4835,14 +4920,14 @@ function serverLayoutProblem(layout) {
4835
4920
  for (const role of option.roles ?? []) if (!roles.has(role.toLowerCase())) return `onboarding: the option \`${option.title}\` gives the role \`${role}\`, which is not in the layout's roles`;
4836
4921
  }
4837
4922
  }
4838
- async function runNotificationsSetup(input) {
4839
- const print = input.print ?? ((line) => console.log(line));
4840
- const logger = input.logger ?? getLogger();
4923
+ async function runNotificationsSetup(input$1) {
4924
+ const print = input$1.print ?? ((line) => console.log(line));
4925
+ const logger = input$1.logger ?? getLogger();
4841
4926
  /* v8 ignore next -- the real loader is only built outside tests, which always inject one */
4842
- const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
4843
- if (!input.preloaded) await loader.load();
4927
+ const loader = input$1.loader ?? new PluginLoader(input$1.loaded.resolved, input$1.context);
4928
+ if (!input$1.preloaded) await loader.load();
4844
4929
  assertPluginsResolvable(loader, "notifications setup");
4845
- const dryRun = input.context.dryRun ?? false;
4930
+ const dryRun = input$1.context.dryRun ?? false;
4846
4931
  const report = {
4847
4932
  status: "ok",
4848
4933
  categories: [],
@@ -4863,7 +4948,7 @@ async function runNotificationsSetup(input) {
4863
4948
  };
4864
4949
  let notifications;
4865
4950
  try {
4866
- notifications = pickProvisioner(notificationProviders(loader), input.provider);
4951
+ notifications = pickProvisioner(notificationProviders(loader), input$1.provider);
4867
4952
  } catch (err) {
4868
4953
  return refuse(errorMessage(err));
4869
4954
  }
@@ -4875,14 +4960,14 @@ async function runNotificationsSetup(input) {
4875
4960
  if (!loader.has("secrets")) return refuse(whyMissing(loader, "secrets", "the layout stores webhook URLs or role ids, which need a `secrets` capability โ€” add a `secrets` provider"));
4876
4961
  secrets = loader.get("secrets");
4877
4962
  }
4878
- const org = input.context.org;
4879
- const scope = input.scope ?? (org ? {
4963
+ const org = input$1.context.org;
4964
+ const scope = input$1.scope ?? (org ? {
4880
4965
  kind: "organization",
4881
4966
  name: org
4882
4967
  } : void 0);
4883
4968
  if (wantsSecrets && !scope && !dryRun) return refuse("no org to store secrets under โ€” pass --scope or set `org` in holocron.config.ts");
4884
4969
  const avatars = /* @__PURE__ */ new Map();
4885
- const read = input.loadAvatar ?? loadAvatar;
4970
+ const read = input$1.loadAvatar ?? loadAvatar;
4886
4971
  for (const channel of (layout.categories ?? []).flatMap((c) => c.channels ?? [])) {
4887
4972
  const source = channel.webhook ? webhookAvatarOf(layout, channel.webhook) : void 0;
4888
4973
  if (source === void 0 || avatars.has(source)) continue;
@@ -4906,6 +4991,7 @@ async function runNotificationsSetup(input) {
4906
4991
  if (layout.server && !notifications.ensureServer) return refuse(`the layout declares \`server\` settings, but the \`${notifications.providerName}\` provider cannot manage them`);
4907
4992
  if (layout.welcome && !notifications.ensureWelcome) return refuse(`the layout declares a \`welcome\` screen, but the \`${notifications.providerName}\` provider cannot manage one`);
4908
4993
  if (layout.onboarding && !notifications.ensureOnboarding) return refuse(`the layout declares \`onboarding\`, but the \`${notifications.providerName}\` provider cannot manage it`);
4994
+ if ((layout.pinned?.length ?? 0) > 0 && !notifications.ensurePinned) return refuse(`the layout declares \`pinned\` messages, but the \`${notifications.providerName}\` provider cannot manage them`);
4909
4995
  if (layout.application && !notifications.ensureApplication) return refuse(`the layout declares \`application\` settings, but the \`${notifications.providerName}\` provider cannot manage them`);
4910
4996
  if (layout.everyone && !notifications.ensureEveryone) return refuse(`the layout declares \`everyone\` permissions, but the \`${notifications.providerName}\` provider cannot manage them`);
4911
4997
  const needsCategories = (layout.categories ?? []).find((c) => c.access);
@@ -5025,7 +5111,7 @@ async function runNotificationsSetup(input) {
5025
5111
  });
5026
5112
  });
5027
5113
  }
5028
- if (layout.server || layout.welcome || layout.onboarding || layout.application || layout.everyone) {
5114
+ if (layout.server || layout.welcome || layout.onboarding || (layout.pinned?.length ?? 0) > 0 || layout.application || layout.everyone) {
5029
5115
  print(`\n${style.header("Server")}`);
5030
5116
  const apply = async (label, declared, run) => {
5031
5117
  if (!declared) return;
@@ -5049,8 +5135,16 @@ async function runNotificationsSetup(input) {
5049
5135
  });
5050
5136
  };
5051
5137
  await apply("@everyone permissions", !!layout.everyone, () => notifications.ensureEveryone(layout.everyone));
5052
- await apply("server settings", !!layout.server, () => notifications.ensureServer(layout.server));
5138
+ /* v8 ignore next 4 -- the real prompt only runs with a terminal attached; tests pass their own */
5139
+ const pause = input$1.pause === false ? void 0 : input$1.pause ?? (process.stdin.isTTY && process.stdout.isTTY ? async (message) => void await input({ message }) : void 0);
5140
+ await apply("server settings", !!layout.server, () => withElevation(() => notifications.ensureServer(layout.server), {
5141
+ label: "server settings",
5142
+ notifications,
5143
+ ...pause ? { pause } : {},
5144
+ print
5145
+ }));
5053
5146
  await apply("welcome screen", !!layout.welcome, () => notifications.ensureWelcome(layout.welcome));
5147
+ await apply("pinned messages", (layout.pinned?.length ?? 0) > 0, () => notifications.ensurePinned(layout.pinned));
5054
5148
  await apply("onboarding", !!layout.onboarding, () => notifications.ensureOnboarding(layout.onboarding));
5055
5149
  await apply("bot application", !!layout.application, () => notifications.ensureApplication(layout.application));
5056
5150
  }