@theholocron/cli 5.0.0-alpha.267 โ†’ 5.0.0-alpha.268

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
@@ -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 --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 |
554
- | `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, 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 |
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
- return function resolveFeatureToken(input = {}) {
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,96 @@ const doctorSecretsCommand = {
5715
5729
  })).status === "fail") process.exitCode = 1;
5716
5730
  }
5717
5731
  };
5732
+ // src/commands/doctor-tokens/doctor-tokens.ts
5733
+ /**
5734
+ * `holocron doctor tokens` โ€” is each token a configured plugin takes set, and still accepted?
5735
+ *
5736
+ * Read-only. For every token a configured plugin lists (its `tokens` export), the token is looked up the way the
5737
+ * plugin does it (the environment variable, then the OS keyring) and the plugin's `verifyToken` is asked whether it
5738
+ * 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.
5740
+ *
5741
+ * What a token may do is not checked: GitHub does not return a fine-grained token's permissions.
5742
+ */
5743
+ async function runDoctorTokens(input) {
5744
+ const print = input.print ?? ((line) => console.log(line));
5745
+ const logger = input.logger ?? getLogger();
5746
+ const importer = input.importer ?? defaultImporter;
5747
+ const env = makeEnv(input.env);
5748
+ const keyring = input.keyring ?? getToken;
5749
+ const rows = [];
5750
+ for (const pkg of configuredPackages(input)) {
5751
+ let module;
5752
+ try {
5753
+ module = await importer(pkg);
5754
+ } catch (err) {
5755
+ rows.push(row$1(pkg, "skip", `cannot load the plugin: ${errorMessage(err)}`));
5756
+ continue;
5757
+ }
5758
+ for (const token of module.tokens ?? []) rows.push(await checkToken(token, module, env.get(token.envName), keyring));
5759
+ }
5760
+ if (rows.length === 0) rows.push(row$1("tokens", "skip", "no configured plugin lists the tokens it takes"));
5761
+ printCheckRows(rows, print);
5762
+ const summary = summariseChecks(rows);
5763
+ printCheckSummary(summary, print);
5764
+ const status = summary.fail > 0 ? "fail" : summary.ok === 0 ? "skip" : "ok";
5765
+ logger.info({
5766
+ ...summary,
5767
+ status
5768
+ }, "doctor tokens");
5769
+ return {
5770
+ status,
5771
+ rows,
5772
+ summary,
5773
+ ...status === "skip" ? { reason: [...new Set(rows.map((r) => r.detail))].join("; ") } : {}
5774
+ };
5775
+ }
5776
+ /** The package of every provider the config names, once each. */
5777
+ function configuredPackages(input) {
5778
+ const packages = Object.values(input.loaded.resolved.providers).flatMap((entry) => entry.cardinality === "single" ? [entry.tuple.packageName] : entry.tuples.map((t) => t.packageName));
5779
+ return [...new Set(packages)];
5780
+ }
5781
+ function row$1(id, status, detail) {
5782
+ return {
5783
+ id,
5784
+ title: id,
5785
+ status,
5786
+ detail,
5787
+ problems: []
5788
+ };
5789
+ }
5790
+ async function checkToken(token, module, fromEnv, keyring) {
5791
+ const { keyringKey, envName } = token;
5792
+ const value = fromEnv || keyring(keyringKey);
5793
+ if (!value) return row$1(keyringKey, "skip", `not set (${envName}, or \`holocron auth set ${keyringKey}\`)`);
5794
+ if (!module.verifyToken) return row$1(keyringKey, "skip", "set, but its plugin cannot verify it");
5795
+ const from = fromEnv ? envName : "keyring";
5796
+ try {
5797
+ const verified = await module.verifyToken(value);
5798
+ return verified.ok ? row$1(keyringKey, "ok", `${verified.subject} (${from})`) : row$1(keyringKey, "fail", `rejected (${from}): ${verified.message}`);
5799
+ } catch (err) {
5800
+ return row$1(keyringKey, "fail", `could not be verified (${from}): ${errorMessage(err)}`);
5801
+ }
5802
+ }
5803
+ // src/commands/doctor-tokens/doctor-tokens.command.ts
5804
+ const doctorTokensCommand = {
5805
+ command: "tokens",
5806
+ describe: "Check that each token a configured plugin takes is set and still accepted (read-only; no token is printed)",
5807
+ handler: async (argv) => {
5808
+ const tokens = tokenContext(argv.token);
5809
+ if (!tokens) return;
5810
+ const loaded = await loadConfig(argv.cwd);
5811
+ applyResolvedConfig(argv, loaded.resolved);
5812
+ if ((await runDoctorTokens({
5813
+ loaded,
5814
+ context: {
5815
+ repoRoot: argv.cwd,
5816
+ ...tokens,
5817
+ org: resolveOrg(argv, loaded.resolved)
5818
+ }
5819
+ })).status === "fail") process.exitCode = 1;
5820
+ }
5821
+ };
5718
5822
  // src/commands/doctor-variables/doctor-variables.ts
5719
5823
  /**
5720
5824
  * `holocron doctor variables` โ€” do the Actions variables `repo.variables` declares exist, with those values?
@@ -5907,6 +6011,19 @@ const DEEP_CHECKS = [
5907
6011
  };
5908
6012
  }
5909
6013
  },
6014
+ {
6015
+ name: "tokens",
6016
+ capability: "source",
6017
+ command: doctorTokensCommand,
6018
+ async run(input) {
6019
+ const report = await runDoctorTokens(input);
6020
+ return {
6021
+ status: report.status,
6022
+ summary: report.summary,
6023
+ ...report.reason ? { reason: report.reason } : {}
6024
+ };
6025
+ }
6026
+ },
5910
6027
  {
5911
6028
  name: "variables",
5912
6029
  capability: "source",