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

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,61 @@ 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
+ * A permission the bot is meant to keep ({@link ElevationRequiredError} `keep`) is only given: there is no take-away.
4761
+ * Otherwise taking it away is attempted whatever the retry does, and anything that stops it being done or proven is a `todo`
4762
+ * (reported as a failure) or, when the retry itself failed, a printed failure beside the error.
4763
+ *
4764
+ * Without someone to answer (`pause` absent) the error is passed on unchanged, so a script still gets the
4765
+ * explanation it always did.
4766
+ */
4767
+ async function withElevation(run, deps) {
4768
+ try {
4769
+ return await run();
4770
+ } catch (err) {
4771
+ const { notifications, pause, print } = deps;
4772
+ if (!(err instanceof ElevationRequiredError) || !pause || !err.elevation.grantUrl) throw err;
4773
+ const { permission, grantUrl, revokeUrl, applied, keep } = err.elevation;
4774
+ const name = err.elevation.label ?? permission;
4775
+ if (await notifications.holdsPermission?.(permission).catch(() => false)) throw err;
4776
+ print(` ${style.skip(`${deps.label} needs ${name}${keep ? "" : " for this one edit"}`)}`);
4777
+ print(` 1. approve it: ${grantUrl}`);
4778
+ await pause(`Press Enter once ${name} is approved to try again`);
4779
+ let result;
4780
+ let failure;
4781
+ try {
4782
+ result = await run();
4783
+ } catch (retryErr) {
4784
+ failure = retryErr;
4785
+ }
4786
+ let leftover;
4787
+ if (keep) {} else 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\``;
4788
+ else {
4789
+ print(` 2. take it away again: ${revokeUrl}`);
4790
+ await pause(`Press Enter once ${permission} is taken away to check it`);
4791
+ const holdsNow = await notifications.holdsPermission?.(permission).catch(() => void 0);
4792
+ if (holdsNow === void 0) leftover = `could not check that ${permission} is gone; confirm it in ${notifications.providerName}'s role, then run \`holocron doctor notifications\``;
4793
+ else if (holdsNow) leftover = `${notifications.providerName} still holds ${permission}; use the link above to take it away, then run \`holocron doctor notifications\` to check`;
4794
+ else print(` ${style.success(`${permission} is gone again`)}`);
4795
+ }
4796
+ if (failure !== void 0) {
4797
+ if (leftover) print(` ${style.fail(leftover)}`);
4798
+ throw failure;
4799
+ }
4800
+ return {
4801
+ ...result,
4802
+ updated: [.../* @__PURE__ */ new Set([...applied ?? [], ...result.updated])],
4803
+ todo: [...result.todo ?? [], ...leftover ? [leftover] : []]
4804
+ };
4805
+ }
4806
+ }
4807
+ //#endregion
4726
4808
  //#region src/commands/notifications-setup/notifications-setup.ts
4727
4809
  /**
4728
4810
  * `holocron notifications setup` โ€” apply the server layout a `notifications`
@@ -4822,6 +4904,11 @@ function serverLayoutProblem(layout) {
4822
4904
  const problem = channel("welcome:", entry.channel);
4823
4905
  if (problem) return problem;
4824
4906
  }
4907
+ for (const pin of layout.pinned ?? []) {
4908
+ const problem = channel("pinned:", pin.channel);
4909
+ if (problem) return problem;
4910
+ if (pin.content.trim() === "") return `pinned: the message for \`${pin.channel}\` is empty`;
4911
+ }
4825
4912
  const onboarding = layout.onboarding;
4826
4913
  for (const name of onboarding?.defaultChannels ?? []) {
4827
4914
  const problem = channel("onboarding: `defaultChannels`", name);
@@ -4835,14 +4922,14 @@ function serverLayoutProblem(layout) {
4835
4922
  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
4923
  }
4837
4924
  }
4838
- async function runNotificationsSetup(input) {
4839
- const print = input.print ?? ((line) => console.log(line));
4840
- const logger = input.logger ?? getLogger();
4925
+ async function runNotificationsSetup(input$1) {
4926
+ const print = input$1.print ?? ((line) => console.log(line));
4927
+ const logger = input$1.logger ?? getLogger();
4841
4928
  /* 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();
4929
+ const loader = input$1.loader ?? new PluginLoader(input$1.loaded.resolved, input$1.context);
4930
+ if (!input$1.preloaded) await loader.load();
4844
4931
  assertPluginsResolvable(loader, "notifications setup");
4845
- const dryRun = input.context.dryRun ?? false;
4932
+ const dryRun = input$1.context.dryRun ?? false;
4846
4933
  const report = {
4847
4934
  status: "ok",
4848
4935
  categories: [],
@@ -4863,7 +4950,7 @@ async function runNotificationsSetup(input) {
4863
4950
  };
4864
4951
  let notifications;
4865
4952
  try {
4866
- notifications = pickProvisioner(notificationProviders(loader), input.provider);
4953
+ notifications = pickProvisioner(notificationProviders(loader), input$1.provider);
4867
4954
  } catch (err) {
4868
4955
  return refuse(errorMessage(err));
4869
4956
  }
@@ -4875,14 +4962,14 @@ async function runNotificationsSetup(input) {
4875
4962
  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
4963
  secrets = loader.get("secrets");
4877
4964
  }
4878
- const org = input.context.org;
4879
- const scope = input.scope ?? (org ? {
4965
+ const org = input$1.context.org;
4966
+ const scope = input$1.scope ?? (org ? {
4880
4967
  kind: "organization",
4881
4968
  name: org
4882
4969
  } : void 0);
4883
4970
  if (wantsSecrets && !scope && !dryRun) return refuse("no org to store secrets under โ€” pass --scope or set `org` in holocron.config.ts");
4884
4971
  const avatars = /* @__PURE__ */ new Map();
4885
- const read = input.loadAvatar ?? loadAvatar;
4972
+ const read = input$1.loadAvatar ?? loadAvatar;
4886
4973
  for (const channel of (layout.categories ?? []).flatMap((c) => c.channels ?? [])) {
4887
4974
  const source = channel.webhook ? webhookAvatarOf(layout, channel.webhook) : void 0;
4888
4975
  if (source === void 0 || avatars.has(source)) continue;
@@ -4906,6 +4993,7 @@ async function runNotificationsSetup(input) {
4906
4993
  if (layout.server && !notifications.ensureServer) return refuse(`the layout declares \`server\` settings, but the \`${notifications.providerName}\` provider cannot manage them`);
4907
4994
  if (layout.welcome && !notifications.ensureWelcome) return refuse(`the layout declares a \`welcome\` screen, but the \`${notifications.providerName}\` provider cannot manage one`);
4908
4995
  if (layout.onboarding && !notifications.ensureOnboarding) return refuse(`the layout declares \`onboarding\`, but the \`${notifications.providerName}\` provider cannot manage it`);
4996
+ if ((layout.pinned?.length ?? 0) > 0 && !notifications.ensurePinned) return refuse(`the layout declares \`pinned\` messages, but the \`${notifications.providerName}\` provider cannot manage them`);
4909
4997
  if (layout.application && !notifications.ensureApplication) return refuse(`the layout declares \`application\` settings, but the \`${notifications.providerName}\` provider cannot manage them`);
4910
4998
  if (layout.everyone && !notifications.ensureEveryone) return refuse(`the layout declares \`everyone\` permissions, but the \`${notifications.providerName}\` provider cannot manage them`);
4911
4999
  const needsCategories = (layout.categories ?? []).find((c) => c.access);
@@ -5025,7 +5113,7 @@ async function runNotificationsSetup(input) {
5025
5113
  });
5026
5114
  });
5027
5115
  }
5028
- if (layout.server || layout.welcome || layout.onboarding || layout.application || layout.everyone) {
5116
+ if (layout.server || layout.welcome || layout.onboarding || (layout.pinned?.length ?? 0) > 0 || layout.application || layout.everyone) {
5029
5117
  print(`\n${style.header("Server")}`);
5030
5118
  const apply = async (label, declared, run) => {
5031
5119
  if (!declared) return;
@@ -5049,8 +5137,21 @@ async function runNotificationsSetup(input) {
5049
5137
  });
5050
5138
  };
5051
5139
  await apply("@everyone permissions", !!layout.everyone, () => notifications.ensureEveryone(layout.everyone));
5052
- await apply("server settings", !!layout.server, () => notifications.ensureServer(layout.server));
5140
+ /* v8 ignore next 4 -- the real prompt only runs with a terminal attached; tests pass their own */
5141
+ 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);
5142
+ await apply("server settings", !!layout.server, () => withElevation(() => notifications.ensureServer(layout.server), {
5143
+ label: "server settings",
5144
+ notifications,
5145
+ ...pause ? { pause } : {},
5146
+ print
5147
+ }));
5053
5148
  await apply("welcome screen", !!layout.welcome, () => notifications.ensureWelcome(layout.welcome));
5149
+ await apply("pinned messages", (layout.pinned?.length ?? 0) > 0, () => withElevation(() => notifications.ensurePinned(layout.pinned), {
5150
+ label: "pinned messages",
5151
+ notifications,
5152
+ ...pause ? { pause } : {},
5153
+ print
5154
+ }));
5054
5155
  await apply("onboarding", !!layout.onboarding, () => notifications.ensureOnboarding(layout.onboarding));
5055
5156
  await apply("bot application", !!layout.application, () => notifications.ensureApplication(layout.application));
5056
5157
  }