@theholocron/cli 5.0.0-alpha.267 โ 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 +14 -13
- package/dist/cli.mjs +150 -1
- package/dist/cli.mjs.map +1 -1
- package/dist/{index-DbuSPIGf.d.mts โ index-CL7nYbMl.d.mts} +1 -1
- package/dist/index.d.mts +21 -4
- package/dist/index.mjs +5 -1
- package/dist/presets.d.mts +1 -1
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -540,18 +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
|
|
554
|
-
| `holocron
|
|
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 |
|
|
555
556
|
|
|
556
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).
|
|
557
558
|
|
|
@@ -772,7 +773,7 @@ the local override exists to exempt.
|
|
|
772
773
|
`package bump-versions`, `sync github`, `repo upgrade node`,
|
|
773
774
|
`repo upgrade deps`, `new plugin`, `auth`, `notifications setup`,
|
|
774
775
|
`notifications channel add`, `notifications link`,
|
|
775
|
-
`notifications sync-roles`, `doctor notifications`, `doctor secrets`, `doctor variables`
|
|
776
|
+
`notifications sync-roles`, `doctor notifications`, `doctor secrets`, `doctor tokens`, `doctor variables`
|
|
776
777
|
- `src/commands/doctor-checks/` and `src/commands/deep-checks/` โ the shared row
|
|
777
778
|
renderer and `declaredVsActual` helper, and `DEEP_CHECKS`, the registry every
|
|
778
779
|
`doctor <capability>` is listed in
|
package/dist/cli.mjs
CHANGED
|
@@ -126,13 +126,17 @@ function listStoredProviders() {
|
|
|
126
126
|
* operation fails with a message naming the exact env var to set.
|
|
127
127
|
*/
|
|
128
128
|
function createFeatureResolver(config) {
|
|
129
|
-
|
|
129
|
+
const resolveFeatureToken = (input = {}) => {
|
|
130
130
|
const env = makeEnv(input.env);
|
|
131
131
|
const keyring = input.keyring ?? getToken;
|
|
132
132
|
const token = input.cliToken || env.get(config.envName) || keyring(config.keyringKey);
|
|
133
133
|
if (!token) throw new AuthError(`no ${config.vendor ?? "GitHub"} token found for this operation. Pass --token <token>, set ${config.envName}, or run: holocron auth set ${config.keyringKey} <token>`);
|
|
134
134
|
return token;
|
|
135
135
|
};
|
|
136
|
+
return Object.assign(resolveFeatureToken, { token: {
|
|
137
|
+
envName: config.envName,
|
|
138
|
+
keyringKey: config.keyringKey
|
|
139
|
+
} });
|
|
136
140
|
}
|
|
137
141
|
// src/auth/token-args/token-args.ts
|
|
138
142
|
var TokenParseError = class extends Error {
|
|
@@ -217,6 +221,7 @@ const COMMAND_CONTEXTS = {
|
|
|
217
221
|
"doctor all": "workspace",
|
|
218
222
|
"doctor notifications": "workspace",
|
|
219
223
|
"doctor secrets": "workspace",
|
|
224
|
+
"doctor tokens": "workspace",
|
|
220
225
|
"doctor variables": "workspace",
|
|
221
226
|
probe: "workspace",
|
|
222
227
|
deploy: "workspace",
|
|
@@ -1437,6 +1442,13 @@ const doctorSecretsEntry = {
|
|
|
1437
1442
|
positionals: [],
|
|
1438
1443
|
supportsDryRun: false
|
|
1439
1444
|
};
|
|
1445
|
+
// src/commands/doctor-tokens/doctor-tokens.entry.ts
|
|
1446
|
+
const doctorTokensEntry = {
|
|
1447
|
+
name: "doctor tokens",
|
|
1448
|
+
description: "Check that each token a configured plugin takes is set and still accepted (read-only; no token is printed)",
|
|
1449
|
+
positionals: [],
|
|
1450
|
+
supportsDryRun: false
|
|
1451
|
+
};
|
|
1440
1452
|
// src/commands/doctor-variables/doctor-variables.entry.ts
|
|
1441
1453
|
const doctorVariablesEntry = {
|
|
1442
1454
|
name: "doctor variables",
|
|
@@ -1649,6 +1661,7 @@ const COMMAND_REGISTRY = [
|
|
|
1649
1661
|
notificationsChannelAddEntry,
|
|
1650
1662
|
doctorNotificationsEntry,
|
|
1651
1663
|
doctorSecretsEntry,
|
|
1664
|
+
doctorTokensEntry,
|
|
1652
1665
|
doctorVariablesEntry,
|
|
1653
1666
|
notificationsSetupEntry,
|
|
1654
1667
|
notificationsCreateServerEntry,
|
|
@@ -2778,6 +2791,7 @@ function assertPluginsResolvable(loader, command) {
|
|
|
2778
2791
|
* don't export `verifyToken` can still store โ with a warning โ because
|
|
2779
2792
|
* "no verify path" shouldn't block credential storage.
|
|
2780
2793
|
*/
|
|
2794
|
+
/** Loads a plugin package for its module-level exports (`verifyToken`, `tokens`), from the working directory first. */
|
|
2781
2795
|
const defaultImporter = async (pkg) => {
|
|
2782
2796
|
try {
|
|
2783
2797
|
const resolved = createRequire(process.cwd() + "/").resolve(pkg);
|
|
@@ -5715,6 +5729,128 @@ const doctorSecretsCommand = {
|
|
|
5715
5729
|
})).status === "fail") process.exitCode = 1;
|
|
5716
5730
|
}
|
|
5717
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
|
+
}
|
|
5755
|
+
// src/commands/doctor-tokens/doctor-tokens.ts
|
|
5756
|
+
/**
|
|
5757
|
+
* `holocron doctor tokens` โ is each token a configured plugin takes set, and still accepted?
|
|
5758
|
+
*
|
|
5759
|
+
* Read-only. For every token a configured plugin lists (its `tokens` export), the token is looked up the way the
|
|
5760
|
+
* plugin does it (the environment variable, then the OS keyring) and the plugin's `verifyToken` is asked whether it
|
|
5761
|
+
* is still accepted. A token is never printed. One that is not set is a skip, not a failure: whether it is needed
|
|
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.
|
|
5765
|
+
*
|
|
5766
|
+
* What a token may do is not checked: GitHub does not return a fine-grained token's permissions.
|
|
5767
|
+
*/
|
|
5768
|
+
async function runDoctorTokens(input) {
|
|
5769
|
+
const print = input.print ?? ((line) => console.log(line));
|
|
5770
|
+
const logger = input.logger ?? getLogger();
|
|
5771
|
+
const importer = input.importer ?? defaultImporter;
|
|
5772
|
+
const env = makeEnv(input.env);
|
|
5773
|
+
const keyring = input.keyring ?? getToken;
|
|
5774
|
+
const now = input.now ?? (() => /* @__PURE__ */ new Date());
|
|
5775
|
+
const rows = [];
|
|
5776
|
+
for (const pkg of configuredPackages(input)) {
|
|
5777
|
+
let module;
|
|
5778
|
+
try {
|
|
5779
|
+
module = await importer(pkg);
|
|
5780
|
+
} catch (err) {
|
|
5781
|
+
rows.push(row$1(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
|
|
5782
|
+
continue;
|
|
5783
|
+
}
|
|
5784
|
+
for (const token of module.tokens ?? []) rows.push(await checkToken(token, module, env.get(token.envName), keyring, now()));
|
|
5785
|
+
}
|
|
5786
|
+
if (rows.length === 0) rows.push(row$1("tokens", "skip", "no configured plugin lists the tokens it takes"));
|
|
5787
|
+
printCheckRows(rows, print);
|
|
5788
|
+
const summary = summariseChecks(rows);
|
|
5789
|
+
printCheckSummary(summary, print);
|
|
5790
|
+
const status = summary.fail > 0 ? "fail" : summary.ok === 0 ? "skip" : "ok";
|
|
5791
|
+
logger.info({
|
|
5792
|
+
...summary,
|
|
5793
|
+
status
|
|
5794
|
+
}, "doctor tokens");
|
|
5795
|
+
return {
|
|
5796
|
+
status,
|
|
5797
|
+
rows,
|
|
5798
|
+
summary,
|
|
5799
|
+
...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
|
|
5800
|
+
};
|
|
5801
|
+
}
|
|
5802
|
+
/** The package of every provider the config names, once each. */
|
|
5803
|
+
function configuredPackages(input) {
|
|
5804
|
+
const packages = Object.values(input.loaded.resolved.providers).flatMap((entry) => entry.cardinality === "single" ? [entry.tuple.packageName] : entry.tuples.map((t) => t.packageName));
|
|
5805
|
+
return [...new Set(packages)];
|
|
5806
|
+
}
|
|
5807
|
+
function row$1(id, status, detail) {
|
|
5808
|
+
return {
|
|
5809
|
+
id,
|
|
5810
|
+
title: id,
|
|
5811
|
+
status,
|
|
5812
|
+
detail,
|
|
5813
|
+
problems: []
|
|
5814
|
+
};
|
|
5815
|
+
}
|
|
5816
|
+
async function checkToken(token, module, fromEnv, keyring, now) {
|
|
5817
|
+
const { keyringKey, envName } = token;
|
|
5818
|
+
const value = fromEnv || keyring(keyringKey);
|
|
5819
|
+
if (!value) return row$1(keyringKey, "skip", `not set (${envName}, or \`holocron auth set ${keyringKey}\`)`);
|
|
5820
|
+
if (!module.verifyToken) return row$1(keyringKey, "skip", "set, but its plugin cannot verify it");
|
|
5821
|
+
const from = fromEnv ? envName : "keyring";
|
|
5822
|
+
try {
|
|
5823
|
+
const verified = await module.verifyToken(value);
|
|
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}`);
|
|
5831
|
+
} catch (err) {
|
|
5832
|
+
return row$1(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
|
|
5833
|
+
}
|
|
5834
|
+
}
|
|
5835
|
+
// src/commands/doctor-tokens/doctor-tokens.command.ts
|
|
5836
|
+
const doctorTokensCommand = {
|
|
5837
|
+
command: "tokens",
|
|
5838
|
+
describe: "Check that each token a configured plugin takes is set and still accepted (read-only; no token is printed)",
|
|
5839
|
+
handler: async (argv) => {
|
|
5840
|
+
const tokens = tokenContext(argv.token);
|
|
5841
|
+
if (!tokens) return;
|
|
5842
|
+
const loaded = await loadConfig(argv.cwd);
|
|
5843
|
+
applyResolvedConfig(argv, loaded.resolved);
|
|
5844
|
+
if ((await runDoctorTokens({
|
|
5845
|
+
loaded,
|
|
5846
|
+
context: {
|
|
5847
|
+
repoRoot: argv.cwd,
|
|
5848
|
+
...tokens,
|
|
5849
|
+
org: resolveOrg(argv, loaded.resolved)
|
|
5850
|
+
}
|
|
5851
|
+
})).status === "fail") process.exitCode = 1;
|
|
5852
|
+
}
|
|
5853
|
+
};
|
|
5718
5854
|
// src/commands/doctor-variables/doctor-variables.ts
|
|
5719
5855
|
/**
|
|
5720
5856
|
* `holocron doctor variables` โ do the Actions variables `repo.variables` declares exist, with those values?
|
|
@@ -5907,6 +6043,19 @@ const DEEP_CHECKS = [
|
|
|
5907
6043
|
};
|
|
5908
6044
|
}
|
|
5909
6045
|
},
|
|
6046
|
+
{
|
|
6047
|
+
name: "tokens",
|
|
6048
|
+
capability: "source",
|
|
6049
|
+
command: doctorTokensCommand,
|
|
6050
|
+
async run(input) {
|
|
6051
|
+
const report = await runDoctorTokens(input);
|
|
6052
|
+
return {
|
|
6053
|
+
status: report.status,
|
|
6054
|
+
summary: report.summary,
|
|
6055
|
+
...report.reason ? { reason: report.reason } : {}
|
|
6056
|
+
};
|
|
6057
|
+
}
|
|
6058
|
+
},
|
|
5910
6059
|
{
|
|
5911
6060
|
name: "variables",
|
|
5912
6061
|
capability: "source",
|