@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 +3 -1
- package/dist/cli.mjs +113 -12
- package/dist/cli.mjs.map +1 -1
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +2 -2
- package/dist/plugin/capabilities.d.mts +61 -1
- package/dist/plugin/capabilities.mjs +13 -1
- package/package.json +3 -3
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
|
-
|
|
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
|
}
|