@theholocron/cli 5.0.0-alpha.272 → 5.0.0-alpha.273

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
@@ -550,6 +550,7 @@ commands and the config are provider-neutral; Discord is the first provider.
550
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
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
552
  | `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 |
553
+ | `holocron doctor monitoring` | Do the checks the `monitoring` provider declares exist in its account, matched by name, with the URL, method and (when stated) frequency, locations, activated, should-fail, body and assertions the config sets? One row. A check in the account that is not declared is never a problem. A provider that cannot list its checks, failed to load or has no token is a skip |
553
554
  | `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 |
554
555
  | `holocron doctor tokens` | For every token a configured plugin lists (every plugin that resolves one: GitHub's nine, Discord's three, Sentry's two, ...), looked up as the plugin does (its env var, the vendor's, 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 |
555
556
  | `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 |
@@ -774,7 +775,7 @@ the local override exists to exempt.
774
775
  `package bump-versions`, `sync github`, `repo upgrade node`,
775
776
  `repo upgrade deps`, `new plugin`, `auth`, `notifications setup`,
776
777
  `notifications channel add`, `notifications link`,
777
- `notifications sync-roles`, `doctor environments`, `doctor notifications`, `doctor secrets`, `doctor tokens`, `doctor variables`
778
+ `notifications sync-roles`, `doctor environments`, `doctor monitoring`, `doctor notifications`, `doctor secrets`, `doctor tokens`, `doctor variables`
778
779
  - `src/commands/doctor-checks/` and `src/commands/deep-checks/` — the shared row
779
780
  renderer and `declaredVsActual` helper, and `DEEP_CHECKS`, the registry every
780
781
  `doctor <capability>` is listed in
package/dist/cli.mjs CHANGED
@@ -223,6 +223,7 @@ const COMMAND_CONTEXTS = {
223
223
  "doctor environments": "workspace",
224
224
  "doctor secrets": "workspace",
225
225
  "doctor tokens": "workspace",
226
+ "doctor monitoring": "workspace",
226
227
  "doctor variables": "workspace",
227
228
  probe: "workspace",
228
229
  deploy: "workspace",
@@ -1429,6 +1430,13 @@ const doctorEnvironmentsEntry = {
1429
1430
  positionals: [],
1430
1431
  supportsDryRun: false
1431
1432
  };
1433
+ // src/commands/doctor-monitoring/doctor-monitoring.entry.ts
1434
+ const doctorMonitoringEntry = {
1435
+ name: "doctor monitoring",
1436
+ description: "Check the monitoring checks the config declares against the ones the provider holds (read-only)",
1437
+ positionals: [],
1438
+ supportsDryRun: false
1439
+ };
1432
1440
  // src/commands/doctor-notifications/doctor-notifications.entry.ts
1433
1441
  const doctorNotificationsEntry = {
1434
1442
  name: "doctor notifications",
@@ -1667,6 +1675,7 @@ const COMMAND_REGISTRY = [
1667
1675
  supportsDryRun: true
1668
1676
  },
1669
1677
  notificationsChannelAddEntry,
1678
+ doctorMonitoringEntry,
1670
1679
  doctorNotificationsEntry,
1671
1680
  doctorEnvironmentsEntry,
1672
1681
  doctorSecretsEntry,
@@ -4440,8 +4449,8 @@ const SETUP_ENVIRONMENTS = ["staging", "production"];
4440
4449
  * set on one that exists. An environment that exists but is not expected is never a problem. With no provider and
4441
4450
  * nothing named, nothing is declared; with no provider but some named, the row is a skip with the reason.
4442
4451
  */
4443
- const ID = "environments";
4444
- const TITLE = "environments exist";
4452
+ const ID$1 = "environments";
4453
+ const TITLE$1 = "environments exist";
4445
4454
  async function runDoctorEnvironments(input) {
4446
4455
  const print = input.print ?? ((line) => console.log(line));
4447
4456
  const logger = input.logger ?? getLogger();
@@ -4465,8 +4474,8 @@ async function runDoctorEnvironments(input) {
4465
4474
  }
4466
4475
  async function checkEnvironments(loader, named) {
4467
4476
  const make = (status, detail, problems = []) => ({
4468
- id: ID,
4469
- title: TITLE,
4477
+ id: ID$1,
4478
+ title: TITLE$1,
4470
4479
  status,
4471
4480
  detail,
4472
4481
  problems
@@ -4503,6 +4512,160 @@ const doctorEnvironmentsCommand = {
4503
4512
  })).status === "fail") process.exitCode = 1;
4504
4513
  }
4505
4514
  };
4515
+ // src/commands/doctor-monitoring/doctor-monitoring.ts
4516
+ /**
4517
+ * `holocron doctor monitoring` — do the checks the `monitoring` provider declares exist in its account, as declared?
4518
+ *
4519
+ * Read-only. One row for the declared checks: each must exist by name, and what the config sets on it (URL, method,
4520
+ * frequency, locations, activated, should-fail, body, assertions) must be what the provider holds. A setting the
4521
+ * config leaves out is not compared, and a check in the account that is not declared is never a problem, since the
4522
+ * account may hold checks made by hand or by another tool. A provider that cannot list its checks, a missing
4523
+ * provider that failed to load, or a missing token is a skip with the reason, not a failure.
4524
+ *
4525
+ * Out of scope: the alert channel and its subscriptions (the notification layout declares those, see
4526
+ * `doctor notifications`) and any check that a message really arrives.
4527
+ */
4528
+ const ID = "monitoring-checks";
4529
+ const TITLE = "monitoring checks match";
4530
+ async function runDoctorMonitoring(input) {
4531
+ const print = input.print ?? ((line) => console.log(line));
4532
+ const logger = input.logger ?? getLogger();
4533
+ const loader = input.loader ?? new PluginLoader(input.loaded.resolved, input.context);
4534
+ await loader.load();
4535
+ assertPluginsResolvable(loader, "doctor monitoring");
4536
+ const rows = [await checkRow(loader)];
4537
+ printCheckRows(rows, print);
4538
+ const summary = summariseChecks(rows);
4539
+ printCheckSummary(summary, print);
4540
+ const status = summary.fail > 0 ? "fail" : summary.ok === 0 ? "skip" : "ok";
4541
+ logger.info({
4542
+ ...summary,
4543
+ status
4544
+ }, "doctor monitoring");
4545
+ return {
4546
+ status,
4547
+ rows,
4548
+ summary,
4549
+ ...status === "skip" ? { reason: rows.map((r) => r.detail).join("; ") } : {}
4550
+ };
4551
+ }
4552
+ async function checkRow(loader) {
4553
+ const skip = (detail) => ({
4554
+ id: ID,
4555
+ title: TITLE,
4556
+ status: "skip",
4557
+ detail,
4558
+ problems: []
4559
+ });
4560
+ if (!loader.has("monitoring")) {
4561
+ if (loader.loadFailures().some((f) => f.key === "monitoring")) return skip(whyMissing(loader, "monitoring", "no `monitoring` provider is available"));
4562
+ return {
4563
+ id: ID,
4564
+ title: TITLE,
4565
+ status: "ok",
4566
+ detail: "none declared",
4567
+ problems: []
4568
+ };
4569
+ }
4570
+ const monitoring = loader.get("monitoring");
4571
+ if (monitoring.checks.length === 0) return {
4572
+ id: ID,
4573
+ title: TITLE,
4574
+ status: "ok",
4575
+ detail: "none declared",
4576
+ problems: []
4577
+ };
4578
+ if (!monitoring.listChecks) return skip("provider does not implement listChecks");
4579
+ try {
4580
+ const problems = compareChecks(monitoring.checks, await monitoring.listChecks());
4581
+ if (problems.length > 0) return {
4582
+ id: ID,
4583
+ title: TITLE,
4584
+ status: "fail",
4585
+ detail: `${problems.length} problem(s)`,
4586
+ problems
4587
+ };
4588
+ const n = monitoring.checks.length;
4589
+ return {
4590
+ id: ID,
4591
+ title: TITLE,
4592
+ status: "ok",
4593
+ detail: `${n} of ${n} match`,
4594
+ problems: []
4595
+ };
4596
+ } catch (err) {
4597
+ if (err instanceof MissingTokenError) return skip(err.message);
4598
+ return {
4599
+ id: ID,
4600
+ title: TITLE,
4601
+ status: "fail",
4602
+ detail: errorMessage(err),
4603
+ problems: []
4604
+ };
4605
+ }
4606
+ }
4607
+ /** One assertion as a line: `status_code equals 405`, `header[x-a] contains b`. */
4608
+ function showAssertion(a) {
4609
+ return [
4610
+ a.property === void 0 ? a.source : `${a.source}[${a.property}]`,
4611
+ a.comparison,
4612
+ ...a.target === void 0 ? [] : [a.target]
4613
+ ].join(" ");
4614
+ }
4615
+ /** The settings of a check the config states, as comparable text; a setting it leaves out is not in the map. */
4616
+ function settings(check, declared) {
4617
+ const out = /* @__PURE__ */ new Map();
4618
+ const set = (key, value, present) => {
4619
+ if (present) out.set(key, value === void 0 ? "none" : String(value));
4620
+ };
4621
+ set("url", check.url, true);
4622
+ set("method", check.method ?? "GET", true);
4623
+ set("frequency", check.frequency, !declared || check.frequency !== void 0);
4624
+ set("activated", check.activated, !declared || check.activated !== void 0);
4625
+ set("shouldFail", check.shouldFail, !declared || check.shouldFail !== void 0);
4626
+ set("body", check.body, !declared || check.body !== void 0);
4627
+ set("locations", [...check.locations ?? []].sort().join(", "), !declared || check.locations !== void 0);
4628
+ set("assertions", (check.assertions ?? []).map(showAssertion).sort().join("; "), !declared || check.assertions !== void 0);
4629
+ return out;
4630
+ }
4631
+ function compareChecks(declared, have) {
4632
+ const byName = new Map(have.map((c) => [c.name, c]));
4633
+ const problems = declaredVsActual(new Map(declared.map((c) => [c.name, c])), byName, {
4634
+ noun: "check",
4635
+ flagExtra: false,
4636
+ equal: () => true
4637
+ });
4638
+ for (const want of declared) {
4639
+ const found = byName.get(want.name);
4640
+ if (!found) continue;
4641
+ const wanted = settings(want, true);
4642
+ const actual = new Map([...settings(found, false)].filter(([key]) => wanted.has(key)));
4643
+ problems.push(...declaredVsActual(wanted, actual, {
4644
+ noun: `check ${want.name}`,
4645
+ flagExtra: false,
4646
+ show: (value) => value === "" ? "none" : value
4647
+ }));
4648
+ }
4649
+ return problems;
4650
+ }
4651
+ // src/commands/doctor-monitoring/doctor-monitoring.command.ts
4652
+ const doctorMonitoringCommand = {
4653
+ command: "monitoring",
4654
+ describe: "Check the monitoring checks the config declares against the ones the provider holds (read-only)",
4655
+ handler: async (argv) => {
4656
+ const tokens = tokenContext(argv.token);
4657
+ if (!tokens) return;
4658
+ const loaded = await loadConfig(argv.cwd);
4659
+ applyResolvedConfig(argv, loaded.resolved);
4660
+ if ((await runDoctorMonitoring({
4661
+ loaded,
4662
+ context: {
4663
+ repoRoot: argv.cwd,
4664
+ ...tokens
4665
+ }
4666
+ })).status === "fail") process.exitCode = 1;
4667
+ }
4668
+ };
4506
4669
  // src/commands/doctor-notifications/doctor-notifications.args.ts
4507
4670
  const doctorNotificationsArgs = (y) => y.option("scope", {
4508
4671
  type: "string",
@@ -6208,6 +6371,19 @@ const DEEP_CHECKS = [
6208
6371
  };
6209
6372
  }
6210
6373
  },
6374
+ {
6375
+ name: "monitoring",
6376
+ capability: "monitoring",
6377
+ command: doctorMonitoringCommand,
6378
+ async run(input) {
6379
+ const report = await runDoctorMonitoring(input);
6380
+ return {
6381
+ status: report.status,
6382
+ summary: report.summary,
6383
+ ...report.reason ? { reason: report.reason } : {}
6384
+ };
6385
+ }
6386
+ },
6211
6387
  {
6212
6388
  name: "secrets",
6213
6389
  capability: "secrets",