@theholocron/cli 5.0.0-alpha.268 โ 5.0.0-alpha.269
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 +13 -13
- package/dist/cli.mjs +36 -4
- package/dist/cli.mjs.map +1 -1
- package/dist/{index-DbuSPIGf.d.mts โ index-CL7nYbMl.d.mts} +1 -1
- package/dist/index.d.mts +3 -1
- package/dist/presets.d.mts +1 -1
- package/package.json +9 -9
package/README.md
CHANGED
|
@@ -540,19 +540,19 @@ A `notifications` provider can declare a whole server in `holocron.config.ts`
|
|
|
540
540
|
pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
|
|
541
541
|
commands and the config are provider-neutral; Discord is the first provider.
|
|
542
542
|
|
|
543
|
-
| Command | What it does
|
|
544
|
-
| -------------------------------------------------------------- |
|
|
545
|
-
| `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches
|
|
546
|
-
| `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret)
|
|
547
|
-
| `holocron notifications create-server --name <n> --owner <id>` | Creates the server the layout describes, writes its id into the config, applies the layout, invites the owner, waits for them to join and hands the server over (`--resume` finishes an interrupted hand-over; `--force` allows a second server)
|
|
548
|
-
| `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept)
|
|
549
|
-
| `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one)
|
|
550
|
-
| `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
|
|
551
|
-
| `holocron doctor variables` | Do the Actions variables `repo.variables` declares exist, with those values (and, for the organization's, that visibility)? One row for the repository and one for the organization, each only when declared. Read-only. An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure
|
|
552
|
-
| `holocron doctor secrets` | Do the secrets the config says must exist (`repo.secrets`, plus the notification layout's webhook and role secrets and the Chromatic token) exist? One row for the repository, the organization and each environment, each only when something is expected there. Names only; an undeclared secret is never a problem. A scope that cannot be read is a skip
|
|
553
|
-
| `holocron doctor tokens` | For every token a configured plugin lists (the GitHub plugin's nine), looked up as the plugin does (env var, then keyring) and verified with its `verifyToken`: set and accepted is ok, set and rejected fails, not set is a skip. No token is printed. What a token may do is not checked, because GitHub does not return a fine-grained token's permissions |
|
|
554
|
-
| `holocron doctor --all` | Runs every deep check (`doctor notifications`, `doctor variables`, ...) and prints one row each, then `N ok, N fail, N skipped` counted in checks. Exits 1 when any check failed. A check that cannot run (no provider, no token) is a skip with the reason. Read-only: notifications runs as `--built-only`, so it posts nothing
|
|
555
|
-
| `holocron probe [<provider> [<probe>]] [--dry-run] [--yes]` | Poke a live provider on purpose: list the probes, inspect something, or run a proof that cleans up after itself. Plugins offer the probes; nothing secret is printed; one that changes things asks first
|
|
543
|
+
| Command | What it does |
|
|
544
|
+
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
545
|
+
| `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
|
|
546
|
+
| `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
|
|
547
|
+
| `holocron notifications create-server --name <n> --owner <id>` | Creates the server the layout describes, writes its id into the config, applies the layout, invites the owner, waits for them to join and hands the server over (`--resume` finishes an interrupted hand-over; `--force` allows a second server) |
|
|
548
|
+
| `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
|
|
549
|
+
| `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
|
|
550
|
+
| `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 |
|
|
551
|
+
| `holocron doctor variables` | Do the Actions variables `repo.variables` declares exist, with those values (and, for the organization's, that visibility)? One row for the repository and one for the organization, each only when declared. Read-only. An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
|
|
552
|
+
| `holocron doctor secrets` | Do the secrets the config says must exist (`repo.secrets`, plus the notification layout's webhook and role secrets and the Chromatic token) exist? One row for the repository, the organization and each environment, each only when something is expected there. Names only; an undeclared secret is never a problem. A scope that cannot be read is a skip |
|
|
553
|
+
| `holocron doctor tokens` | For every token a configured plugin lists (the GitHub plugin's nine), looked up as the plugin does (env var, then keyring) and verified with its `verifyToken`: set and accepted is ok (with how long is left, when the token expires), set and rejected fails, a token with 7 days or fewer left fails with `expires in N days: renew it`, not set is a skip. No token is printed. What a token may do is not checked, because GitHub does not return a fine-grained token's permissions |
|
|
554
|
+
| `holocron doctor --all` | Runs every deep check (`doctor notifications`, `doctor variables`, ...) and prints one row each, then `N ok, N fail, N skipped` counted in checks. Exits 1 when any check failed. A check that cannot run (no provider, no token) is a skip with the reason. Read-only: notifications runs as `--built-only`, so it posts nothing |
|
|
555
|
+
| `holocron probe [<provider> [<probe>]] [--dry-run] [--yes]` | Poke a live provider on purpose: list the probes, inspect something, or run a proof that cleans up after itself. Plugins offer the probes; nothing secret is printed; one that changes things asks first |
|
|
556
556
|
|
|
557
557
|
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).
|
|
558
558
|
|
package/dist/cli.mjs
CHANGED
|
@@ -5729,6 +5729,29 @@ const doctorSecretsCommand = {
|
|
|
5729
5729
|
})).status === "fail") process.exitCode = 1;
|
|
5730
5730
|
}
|
|
5731
5731
|
};
|
|
5732
|
+
const DAY_MS = 864e5;
|
|
5733
|
+
/**
|
|
5734
|
+
* How long a token has left, as `expires in 12 days`, and whether that is inside the warning window.
|
|
5735
|
+
* A time that cannot be read is reported as no expiry rather than guessed at.
|
|
5736
|
+
*/
|
|
5737
|
+
function describeExpiry(expiresAt, now) {
|
|
5738
|
+
const left = Date.parse(expiresAt) - now.getTime();
|
|
5739
|
+
if (Number.isNaN(left)) return void 0;
|
|
5740
|
+
const soon = left <= 7 * DAY_MS;
|
|
5741
|
+
const days = Math.floor(left / DAY_MS);
|
|
5742
|
+
if (left <= 0) return {
|
|
5743
|
+
text: "expired",
|
|
5744
|
+
soon
|
|
5745
|
+
};
|
|
5746
|
+
if (days < 1) return {
|
|
5747
|
+
text: "expires in less than a day",
|
|
5748
|
+
soon
|
|
5749
|
+
};
|
|
5750
|
+
return {
|
|
5751
|
+
text: `expires in ${days} ${days === 1 ? "day" : "days"}`,
|
|
5752
|
+
soon
|
|
5753
|
+
};
|
|
5754
|
+
}
|
|
5732
5755
|
// src/commands/doctor-tokens/doctor-tokens.ts
|
|
5733
5756
|
/**
|
|
5734
5757
|
* `holocron doctor tokens` โ is each token a configured plugin takes set, and still accepted?
|
|
@@ -5736,7 +5759,9 @@ const doctorSecretsCommand = {
|
|
|
5736
5759
|
* Read-only. For every token a configured plugin lists (its `tokens` export), the token is looked up the way the
|
|
5737
5760
|
* plugin does it (the environment variable, then the OS keyring) and the plugin's `verifyToken` is asked whether it
|
|
5738
5761
|
* is still accepted. A token is never printed. One that is not set is a skip, not a failure: whether it is needed
|
|
5739
|
-
* depends on what is run. One that is set and rejected (expired, revoked, malformed) fails
|
|
5762
|
+
* depends on what is run. One that is set and rejected (expired, revoked, malformed) fails, and so does one that
|
|
5763
|
+
* the plugin reports will expire within `TOKEN_EXPIRY_WARN_DAYS` days (a warning is a fail: the check has no third
|
|
5764
|
+
* status). A token with no expiry shows nothing extra.
|
|
5740
5765
|
*
|
|
5741
5766
|
* What a token may do is not checked: GitHub does not return a fine-grained token's permissions.
|
|
5742
5767
|
*/
|
|
@@ -5746,6 +5771,7 @@ async function runDoctorTokens(input) {
|
|
|
5746
5771
|
const importer = input.importer ?? defaultImporter;
|
|
5747
5772
|
const env = makeEnv(input.env);
|
|
5748
5773
|
const keyring = input.keyring ?? getToken;
|
|
5774
|
+
const now = input.now ?? (() => /* @__PURE__ */ new Date());
|
|
5749
5775
|
const rows = [];
|
|
5750
5776
|
for (const pkg of configuredPackages(input)) {
|
|
5751
5777
|
let module;
|
|
@@ -5755,7 +5781,7 @@ async function runDoctorTokens(input) {
|
|
|
5755
5781
|
rows.push(row$1(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
|
|
5756
5782
|
continue;
|
|
5757
5783
|
}
|
|
5758
|
-
for (const token of module.tokens ?? []) rows.push(await checkToken(token, module, env.get(token.envName), keyring));
|
|
5784
|
+
for (const token of module.tokens ?? []) rows.push(await checkToken(token, module, env.get(token.envName), keyring, now()));
|
|
5759
5785
|
}
|
|
5760
5786
|
if (rows.length === 0) rows.push(row$1("tokens", "skip", "no configured plugin lists the tokens it takes"));
|
|
5761
5787
|
printCheckRows(rows, print);
|
|
@@ -5787,7 +5813,7 @@ function row$1(id, status, detail) {
|
|
|
5787
5813
|
problems: []
|
|
5788
5814
|
};
|
|
5789
5815
|
}
|
|
5790
|
-
async function checkToken(token, module, fromEnv, keyring) {
|
|
5816
|
+
async function checkToken(token, module, fromEnv, keyring, now) {
|
|
5791
5817
|
const { keyringKey, envName } = token;
|
|
5792
5818
|
const value = fromEnv || keyring(keyringKey);
|
|
5793
5819
|
if (!value) return row$1(keyringKey, "skip", `not set (${envName}, or \`holocron auth set ${keyringKey}\`)`);
|
|
@@ -5795,7 +5821,13 @@ async function checkToken(token, module, fromEnv, keyring) {
|
|
|
5795
5821
|
const from = fromEnv ? envName : "keyring";
|
|
5796
5822
|
try {
|
|
5797
5823
|
const verified = await module.verifyToken(value);
|
|
5798
|
-
|
|
5824
|
+
if (!verified.ok) return row$1(keyringKey, "fail", `rejected (${from}): ${verified.message}`);
|
|
5825
|
+
const expiry = verified.expiresAt ? describeExpiry(verified.expiresAt, now) : void 0;
|
|
5826
|
+
if (!expiry) return row$1(keyringKey, "ok", `${verified.subject} (${from})`);
|
|
5827
|
+
return expiry.soon ? {
|
|
5828
|
+
...row$1(keyringKey, "fail", `${verified.subject} (${from}), ${expiry.text}`),
|
|
5829
|
+
problems: [`${expiry.text}: renew it`]
|
|
5830
|
+
} : row$1(keyringKey, "ok", `${verified.subject} (${from}), ${expiry.text}`);
|
|
5799
5831
|
} catch (err) {
|
|
5800
5832
|
return row$1(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
|
|
5801
5833
|
}
|