@theholocron/cli 5.0.0-alpha.269 โ†’ 5.0.0-alpha.270

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
@@ -553,6 +553,20 @@ commands and the config are provider-neutral; Discord is the first provider.
553
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
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
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
+ | Command | What it does |
557
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
558
+ | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
559
+ | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
560
+ | `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) |
561
+ | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
562
+ | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
563
+ | `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 |
564
+ | `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 |
565
+ | `holocron doctor environments` | Do the deployment environments exist? The ones `repo setup` creates (`staging`, `production`, when an `environments` provider is configured) plus every environment `repo.secrets.environments` names. One row. A missing one fails; an extra one is never a problem; no provider with some named is a skip |
566
+ | `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 |
567
+ | `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 |
568
+ | `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 |
569
+ | `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
570
 
557
571
  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
572
 
@@ -773,7 +787,7 @@ the local override exists to exempt.
773
787
  `package bump-versions`, `sync github`, `repo upgrade node`,
774
788
  `repo upgrade deps`, `new plugin`, `auth`, `notifications setup`,
775
789
  `notifications channel add`, `notifications link`,
776
- `notifications sync-roles`, `doctor notifications`, `doctor secrets`, `doctor tokens`, `doctor variables`
790
+ `notifications sync-roles`, `doctor environments`, `doctor notifications`, `doctor secrets`, `doctor tokens`, `doctor variables`
777
791
  - `src/commands/doctor-checks/` and `src/commands/deep-checks/` โ€” the shared row
778
792
  renderer and `declaredVsActual` helper, and `DEEP_CHECKS`, the registry every
779
793
  `doctor <capability>` is listed in
package/dist/cli.mjs CHANGED
@@ -220,6 +220,7 @@ const COMMAND_CONTEXTS = {
220
220
  "notifications sync-roles": "workspace",
221
221
  "doctor all": "workspace",
222
222
  "doctor notifications": "workspace",
223
+ "doctor environments": "workspace",
223
224
  "doctor secrets": "workspace",
224
225
  "doctor tokens": "workspace",
225
226
  "doctor variables": "workspace",
@@ -1421,6 +1422,13 @@ const doctorAllEntry = {
1421
1422
  supportsDryRun: false,
1422
1423
  spawnArgs: ["doctor", "--all"]
1423
1424
  };
1425
+ // src/commands/doctor-environments/doctor-environments.entry.ts
1426
+ const doctorEnvironmentsEntry = {
1427
+ name: "doctor environments",
1428
+ description: "Check that the deployment environments the config relies on exist (read-only)",
1429
+ positionals: [],
1430
+ supportsDryRun: false
1431
+ };
1424
1432
  // src/commands/doctor-notifications/doctor-notifications.entry.ts
1425
1433
  const doctorNotificationsEntry = {
1426
1434
  name: "doctor notifications",
@@ -1660,6 +1668,7 @@ const COMMAND_REGISTRY = [
1660
1668
  },
1661
1669
  notificationsChannelAddEntry,
1662
1670
  doctorNotificationsEntry,
1671
+ doctorEnvironmentsEntry,
1663
1672
  doctorSecretsEntry,
1664
1673
  doctorTokensEntry,
1665
1674
  doctorVariablesEntry,
@@ -3883,63 +3892,6 @@ const deployCommand = {
3883
3892
  })).status === "fail") process.exitCode = 1;
3884
3893
  }
3885
3894
  };
3886
- // src/commands/doctor-notifications/doctor-notifications.args.ts
3887
- const doctorNotificationsArgs = (y) => y.option("scope", {
3888
- type: "string",
3889
- describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
3890
- }).option("provider", {
3891
- type: "string",
3892
- describe: "Which notifications provider, when several can inspect"
3893
- }).option("built-only", {
3894
- type: "boolean",
3895
- default: false,
3896
- describe: "Leave out the features that are not built yet (a routine drift check)"
3897
- }).option("deliver", {
3898
- type: "boolean",
3899
- default: false,
3900
- describe: "Post a test message through every channel's webhook, read it back and remove it (works with --built-only)"
3901
- });
3902
- // src/ui/provider-error/provider-error.ts
3903
- /** Vendor response bodies land in the terminal โ€” cap their length so one
3904
- * oversized error can't flood the report, and strip control characters
3905
- * (newlines and the C1 range, whose 0x9b is an 8-bit CSI) so a crafted body
3906
- * can't forge extra report lines or inject terminal escape sequences. */
3907
- const MAX_DETAIL_LENGTH = 200;
3908
- /** Control characters (newlines and the C1 range included) turned into spaces, whitespace collapsed, no length cap. */
3909
- function stripControl(text) {
3910
- return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
3911
- }
3912
- function sanitizeDetail(text) {
3913
- const stripped = stripControl(text);
3914
- return stripped.length > MAX_DETAIL_LENGTH ? `${stripped.slice(0, MAX_DETAIL_LENGTH)}โ€ฆ` : stripped;
3915
- }
3916
- /**
3917
- * `errorMessage(err)` alone is just `"<Vendor> <METHOD> <path> โ†’ <status>"` โ€”
3918
- * the actual reason (what the vendor's response body said) lives in
3919
- * `ProviderApiError.details`, a raw response-body string (not parsed JSON โ€”
3920
- * see AGENTS.md), and was being silently dropped. Appending it (sanitized
3921
- * and length-capped โ€” see `sanitizeDetail`) turns e.g. a bare "โ†’ 403" into
3922
- * something that actually explains itself, without the vendor text being
3923
- * able to overwhelm or manipulate the terminal.
3924
- */
3925
- function describeProviderError(err) {
3926
- const base = stripControl(errorMessage(err));
3927
- if (err instanceof ProviderApiError$1 && err.details) {
3928
- const detail = sanitizeDetail(String(err.details));
3929
- if (detail) return `${base}: ${detail}`;
3930
- }
3931
- return base;
3932
- }
3933
- /**
3934
- * What to put in structured logs: the plain message of the underlying error,
3935
- * with no response body. The detail {@link describeProviderError} adds is for the
3936
- * person at the terminal; a provider's raw body has no business in telemetry.
3937
- * Wrapper errors carry the original as `cause`, so look through one level.
3938
- */
3939
- function logReason(err) {
3940
- const root = err instanceof Error && err.cause !== void 0 ? err.cause : err;
3941
- return errorMessage(root);
3942
- }
3943
3895
  // src/commands/doctor-checks/declared-vs-actual.ts
3944
3896
  /**
3945
3897
  * Compares what the config declares with what exists, both as maps by key, and returns one problem line per
@@ -4072,6 +4024,47 @@ async function loadAvatar(source, baseDir = process.cwd(), fetchImpl = fetch) {
4072
4024
  if (!type) throw new Error("it is not a PNG, JPEG or GIF image, which are the formats providers accept");
4073
4025
  return `data:${type};base64,${bytes.toString("base64")}`;
4074
4026
  }
4027
+ // src/ui/provider-error/provider-error.ts
4028
+ /** Vendor response bodies land in the terminal โ€” cap their length so one
4029
+ * oversized error can't flood the report, and strip control characters
4030
+ * (newlines and the C1 range, whose 0x9b is an 8-bit CSI) so a crafted body
4031
+ * can't forge extra report lines or inject terminal escape sequences. */
4032
+ const MAX_DETAIL_LENGTH = 200;
4033
+ /** Control characters (newlines and the C1 range included) turned into spaces, whitespace collapsed, no length cap. */
4034
+ function stripControl(text) {
4035
+ return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
4036
+ }
4037
+ function sanitizeDetail(text) {
4038
+ const stripped = stripControl(text);
4039
+ return stripped.length > MAX_DETAIL_LENGTH ? `${stripped.slice(0, MAX_DETAIL_LENGTH)}โ€ฆ` : stripped;
4040
+ }
4041
+ /**
4042
+ * `errorMessage(err)` alone is just `"<Vendor> <METHOD> <path> โ†’ <status>"` โ€”
4043
+ * the actual reason (what the vendor's response body said) lives in
4044
+ * `ProviderApiError.details`, a raw response-body string (not parsed JSON โ€”
4045
+ * see AGENTS.md), and was being silently dropped. Appending it (sanitized
4046
+ * and length-capped โ€” see `sanitizeDetail`) turns e.g. a bare "โ†’ 403" into
4047
+ * something that actually explains itself, without the vendor text being
4048
+ * able to overwhelm or manipulate the terminal.
4049
+ */
4050
+ function describeProviderError(err) {
4051
+ const base = stripControl(errorMessage(err));
4052
+ if (err instanceof ProviderApiError$1 && err.details) {
4053
+ const detail = sanitizeDetail(String(err.details));
4054
+ if (detail) return `${base}: ${detail}`;
4055
+ }
4056
+ return base;
4057
+ }
4058
+ /**
4059
+ * What to put in structured logs: the plain message of the underlying error,
4060
+ * with no response body. The detail {@link describeProviderError} adds is for the
4061
+ * person at the terminal; a provider's raw body has no business in telemetry.
4062
+ * Wrapper errors carry the original as `cause`, so look through one level.
4063
+ */
4064
+ function logReason(err) {
4065
+ const root = err instanceof Error && err.cause !== void 0 ? err.cause : err;
4066
+ return errorMessage(root);
4067
+ }
4075
4068
  // src/commands/notifications-channel-add/notifications-channel-add.ts
4076
4069
  /**
4077
4070
  * `holocron notifications channel add` โ€” create one channel (and, with
@@ -4435,6 +4428,97 @@ function layoutSecretNames(layout) {
4435
4428
  const fromRoles = (layout.roles ?? []).flatMap((role) => role.secret ? [role.secret] : []);
4436
4429
  return [...fromChannels, ...fromRoles];
4437
4430
  }
4431
+ // src/commands/setup/setup-environments.ts
4432
+ /** The deployment environments `holocron repo setup` creates when an `environments` provider is configured. */
4433
+ const SETUP_ENVIRONMENTS = ["staging", "production"];
4434
+ // src/commands/doctor-environments/doctor-environments.ts
4435
+ /**
4436
+ * `holocron doctor environments` โ€” do the deployment environments the config relies on exist?
4437
+ *
4438
+ * Read-only. The environments that must exist are the ones `repo setup` creates (when an `environments`
4439
+ * provider is configured) and every environment `repo.secrets.environments` names, since a secret can only be
4440
+ * set on one that exists. An environment that exists but is not expected is never a problem. With no provider and
4441
+ * nothing named, nothing is declared; with no provider but some named, the row is a skip with the reason.
4442
+ */
4443
+ const ID = "environments";
4444
+ const TITLE = "environments exist";
4445
+ async function runDoctorEnvironments(input) {
4446
+ const print = input.print ?? ((line) => console.log(line));
4447
+ const logger = input.logger ?? getLogger();
4448
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
4449
+ await loader.load();
4450
+ assertPluginsResolvable(loader, "doctor environments");
4451
+ const row = await checkEnvironments(loader, Object.keys(input.loaded.resolved.repo?.secrets?.environments ?? {}));
4452
+ printCheckRows([row], print);
4453
+ const summary = summariseChecks([row]);
4454
+ printCheckSummary(summary, print);
4455
+ logger.info({
4456
+ ...summary,
4457
+ status: row.status
4458
+ }, "doctor environments");
4459
+ return {
4460
+ status: row.status,
4461
+ rows: [row],
4462
+ summary,
4463
+ ...row.status === "skip" ? { reason: row.detail } : {}
4464
+ };
4465
+ }
4466
+ async function checkEnvironments(loader, named) {
4467
+ const make = (status, detail, problems = []) => ({
4468
+ id: ID,
4469
+ title: TITLE,
4470
+ status,
4471
+ detail,
4472
+ problems
4473
+ });
4474
+ if (!loader.has("environments")) return named.length === 0 ? make("ok", "none declared") : make("skip", whyMissing(loader, "environments", "no `environments` provider to check them with"));
4475
+ const names = [...new Set([...SETUP_ENVIRONMENTS, ...named].map((n) => n.toLowerCase()))];
4476
+ try {
4477
+ const have = await loader.get("environments").listEnvironments();
4478
+ const problems = declaredVsActual(new Map(names.map((name) => [name, true])), new Map(have.map((env) => [env.name.toLowerCase(), true])), {
4479
+ noun: "environment",
4480
+ flagExtra: false
4481
+ });
4482
+ return problems.length > 0 ? make("fail", `${problems.length} problem(s)`, problems) : make("ok", `${names.length} of ${names.length} exist`);
4483
+ } catch (err) {
4484
+ return err instanceof MissingTokenError ? make("skip", err.message) : make("fail", errorMessage(err));
4485
+ }
4486
+ }
4487
+ // src/commands/doctor-environments/doctor-environments.command.ts
4488
+ const doctorEnvironmentsCommand = {
4489
+ command: "environments",
4490
+ describe: "Check that the deployment environments the config relies on exist (read-only)",
4491
+ handler: async (argv) => {
4492
+ const tokens = tokenContext(argv.token);
4493
+ if (!tokens) return;
4494
+ const loaded = await loadConfig(argv.cwd);
4495
+ applyResolvedConfig(argv, loaded.resolved);
4496
+ if ((await runDoctorEnvironments({
4497
+ loaded,
4498
+ context: {
4499
+ repoRoot: argv.cwd,
4500
+ ...tokens,
4501
+ org: resolveOrg(argv, loaded.resolved)
4502
+ }
4503
+ })).status === "fail") process.exitCode = 1;
4504
+ }
4505
+ };
4506
+ // src/commands/doctor-notifications/doctor-notifications.args.ts
4507
+ const doctorNotificationsArgs = (y) => y.option("scope", {
4508
+ type: "string",
4509
+ describe: "Where the layout's secrets live: \"repo\", \"env=<name>\" or \"org=<name>\" (default: the org)"
4510
+ }).option("provider", {
4511
+ type: "string",
4512
+ describe: "Which notifications provider, when several can inspect"
4513
+ }).option("built-only", {
4514
+ type: "boolean",
4515
+ default: false,
4516
+ describe: "Leave out the features that are not built yet (a routine drift check)"
4517
+ }).option("deliver", {
4518
+ type: "boolean",
4519
+ default: false,
4520
+ describe: "Post a test message through every channel's webhook, read it back and remove it (works with --built-only)"
4521
+ });
4438
4522
  const localRedirectUri = (port) => `http://localhost:${port}/callback`;
4439
4523
  /**
4440
4524
  * The hosted service answers `GET <hostedUrl>/api/link` with `{ "service": "link" }`. Anything else (a 402 for
@@ -6030,6 +6114,19 @@ const DEEP_CHECKS = [
6030
6114
  };
6031
6115
  }
6032
6116
  },
6117
+ {
6118
+ name: "environments",
6119
+ capability: "environments",
6120
+ command: doctorEnvironmentsCommand,
6121
+ async run(input) {
6122
+ const report = await runDoctorEnvironments(input);
6123
+ return {
6124
+ status: report.status,
6125
+ summary: report.summary,
6126
+ ...report.reason ? { reason: report.reason } : {}
6127
+ };
6128
+ }
6129
+ },
6033
6130
  {
6034
6131
  name: "secrets",
6035
6132
  capability: "secrets",
@@ -13503,7 +13600,7 @@ async function runSetup(input) {
13503
13600
  if (loader.has("environments")) {
13504
13601
  const envs = loader.get("environments");
13505
13602
  print(style.step("environments"));
13506
- for (const envName of ["staging", "production"]) {
13603
+ for (const envName of SETUP_ENVIRONMENTS) {
13507
13604
  steps.push(await runStep("environments", `upsert ${envName}`, dryRun, async () => {
13508
13605
  await envs.upsertEnvironment({ name: envName });
13509
13606
  }));