@theholocron/cli 5.0.0-alpha.358 → 5.0.0-alpha.359

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
@@ -617,27 +617,27 @@ A `notifications` provider can declare a whole server in `holocron.config.ts`
617
617
  pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
618
618
  commands and the config are provider-neutral; Discord is the first provider.
619
619
 
620
- | Command | What it does |
621
- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
622
- | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
623
- | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
624
- | `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) |
625
- | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
626
- | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
627
- | `holocron project reconcile [board]` | Sets item statuses where a rule says so: an open blocker means `blocked`, no blocker left means `planned`, closed means `done` (status only; `--dry-run` previews; an open item with no status is reported). Runs hourly from `platform.projectReconcile.yml`, which `repo setup` writes when `providers.projects` declares boards |
628
- | `holocron doctor notifications [--built-only] [--deliver] [--post]` | 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; `--post [channel]` posts the result as the bot (the failures, or only the summary when none failed). It also reads the Checkly feed (webhook, alert channel, subscriptions), the Comlink relay (Worker, route, bindings, the tracker's integration and rule) and the Notifications workflow (the file, and the secrets it reads), posting nothing, so `--built-only` keeps those steps |
629
- | `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. A `repo.variables.sync` entry adds one row that checks its names exist (no value is read or shown). An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
630
- | `holocron doctor ci` | Has the repo moved to the flat task vocabulary? One row each for the `tasks:` entries (a deprecated alias, with the id that replaces it), the generated callers (file, workflow and job name equal the task id), the `ci` aggregate's `expected` list (no id missing or stale) and where the callers point (`theholocron/.github` or holocron `ci-v1`). Read-only, no provider needed; exits 1 on a failure. The ruleset's checks are `doctor repo`'s |
631
- | `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 |
632
- | `holocron doctor project [--post [channel]]` | Does each board `providers.projects.boards` declares exist and match its template? One row per board, status list, field, view and automation rule; the board's extras and the items `project reconcile` would fix (no status, closed but not done, open blocker but not blocked, blocked without a blocker) are `info` rows, never a failure. A template file that does not read fails, naming the file. Read-only; `--post` shares the failing rows through the `notifications` bot. |
633
- | `holocron doctor credentials` | Does the credentials environment exist, and does it hold every variable the configured plugins take? One row per variable and provider (`ok`, `fail` when missing, `skip` for an optional one not set), listing names only: it never reads a value, and says which spelling of the environment's name matched. |
634
- | `holocron doctor repo` | Do the repository settings `repo setup` writes match the config? One row per group the config declares: description and homepage, default branch and merge settings, topics, custom properties, team access, branch protection; labels and security settings are always checked. Read-only. Reads through optional `Source` methods (`getRepoInfo`, `getProperties`, `listLabels`, `listTeamAccess`, `getRulesetDetail`, `getSecurity`); a group that cannot be read is a skip, not a failure |
635
- | `holocron doctor dns` | Do the DNS records the config makes setup write exist, pointing where they should? The preview domain's apex and wildcard CNAMEs (Cloudflare), the docs host a wiki provider asks for, and the relay Worker's proxied placeholder; one row per zone. A missing record, another target or a missing proxy fails; an extra record never does. A record `ensureCustomDomain()` returns is not checked, because asking for it creates the domain |
636
- | `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 |
637
- | `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 |
638
- | `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 |
639
- | `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 |
640
- | `holocron probe [<provider> [<probe>]] [--dry-run] [--yes] [--lcov <path>]` | 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 |
620
+ | Command | What it does |
621
+ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
622
+ | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
623
+ | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
624
+ | `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) |
625
+ | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
626
+ | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
627
+ | `holocron project reconcile [board]` | Sets item statuses where a rule says so: an open blocker means `blocked`, no blocker left means `planned`, closed means `done` (status only; `--dry-run` previews; an open item with no status is reported). Runs hourly from `platform.projectReconcile.yml`, which `repo setup` writes when `providers.projects` declares boards |
628
+ | `holocron doctor notifications [--built-only] [--deliver] [--post]` | 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; `--post [channel]` posts the result as the bot (the failures, or only the summary when none failed). It also reads the Checkly feed (webhook, alert channel, subscriptions), the Comlink relay (Worker, route, bindings, the tracker's integration and rule) and the Notifications workflow (the file, and the secrets it reads), posting nothing, so `--built-only` keeps those steps. The `bot-permissions` row compares what the bot's roles hold server-wide with the permissions it needs (`ServerInspection` `botPermissions`; the owner and Administrator hold all, channel overwrites are left to the forum row) and, when some are missing, fails naming them in plain words with the invite link that asks for them again (not a credential); it is skipped, with the reason, when the roles could not be read |
629
+ | `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. A `repo.variables.sync` entry adds one row that checks its names exist (no value is read or shown). An undeclared variable counts only with `prune`; a scope that cannot be read (no provider, no org token) is a skip, not a failure |
630
+ | `holocron doctor ci` | Has the repo moved to the flat task vocabulary? One row each for the `tasks:` entries (a deprecated alias, with the id that replaces it), the generated callers (file, workflow and job name equal the task id), the `ci` aggregate's `expected` list (no id missing or stale) and where the callers point (`theholocron/.github` or holocron `ci-v1`). Read-only, no provider needed; exits 1 on a failure. The ruleset's checks are `doctor repo`'s |
631
+ | `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 |
632
+ | `holocron doctor project [--post [channel]]` | Does each board `providers.projects.boards` declares exist and match its template? One row per board, status list, field, view and automation rule; the board's extras and the items `project reconcile` would fix (no status, closed but not done, open blocker but not blocked, blocked without a blocker) are `info` rows, never a failure. A template file that does not read fails, naming the file. Read-only; `--post` shares the failing rows through the `notifications` bot. |
633
+ | `holocron doctor credentials` | Does the credentials environment exist, and does it hold every variable the configured plugins take? One row per variable and provider (`ok`, `fail` when missing, `skip` for an optional one not set), listing names only: it never reads a value, and says which spelling of the environment's name matched. |
634
+ | `holocron doctor repo` | Do the repository settings `repo setup` writes match the config? One row per group the config declares: description and homepage, default branch and merge settings, topics, custom properties, team access, branch protection; labels and security settings are always checked. Read-only. Reads through optional `Source` methods (`getRepoInfo`, `getProperties`, `listLabels`, `listTeamAccess`, `getRulesetDetail`, `getSecurity`); a group that cannot be read is a skip, not a failure |
635
+ | `holocron doctor dns` | Do the DNS records the config makes setup write exist, pointing where they should? The preview domain's apex and wildcard CNAMEs (Cloudflare), the docs host a wiki provider asks for, and the relay Worker's proxied placeholder; one row per zone. A missing record, another target or a missing proxy fails; an extra record never does. A record `ensureCustomDomain()` returns is not checked, because asking for it creates the domain |
636
+ | `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 |
637
+ | `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 |
638
+ | `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 |
639
+ | `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 |
640
+ | `holocron probe [<provider> [<probe>]] [--dry-run] [--yes] [--lcov <path>]` | 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 |
641
641
 
642
642
  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?, alerts? }` 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`). A channel's own `webhook.avatar` and the layout's `webhookAvatar` take the same forms, a path or `https://` URL, or `{ url, image }` (the URL first, the file in the repo as the fallback); a relative path is read from the repository root. `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). `alerts: { failure?, recovery?, degraded?, sslExpiry?, sslExpiryThreshold? }` (`MonitoringAlertSettings`, passed as `ensureAlertChannel({ ..., alerts })`) sets what the alert channel alerts about: a new channel defaults to failure, recovery and degraded on and `sslExpiry` off, and on an existing channel a setting left out is left alone. A check in the `monitoring` provider's `checks` can route itself with `alertChannels: ["Message to #uptime"]` (`MonitoringCheckInput.alertChannels`, the alert channel names): it is then subscribed to those channels only, and a name no feed declares is refused by `setup`. `inspectAlertChannel` returns the channel's `alerts` and the `misrouted` checks that `doctor notifications` reports. 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).
643
643
 
package/dist/cli.mjs CHANGED
@@ -5551,7 +5551,7 @@ const SETUP_ENVIRONMENTS = ["staging", "production"];
5551
5551
  * nothing named, nothing is declared; with no provider but some named, the row is a skip with the reason.
5552
5552
  */
5553
5553
  const ID$2 = "environments";
5554
- const TITLE$1 = "environments exist";
5554
+ const TITLE$2 = "environments exist";
5555
5555
  async function runDoctorEnvironments(input) {
5556
5556
  const print = input.print ?? ((line) => console.log(line));
5557
5557
  const logger = input.logger ?? getLogger();
@@ -5576,7 +5576,7 @@ async function runDoctorEnvironments(input) {
5576
5576
  async function checkEnvironments(loader, named) {
5577
5577
  const make = (status, detail, problems = []) => ({
5578
5578
  id: ID$2,
5579
- title: TITLE$1,
5579
+ title: TITLE$2,
5580
5580
  status,
5581
5581
  detail,
5582
5582
  problems
@@ -5628,7 +5628,7 @@ const doctorEnvironmentsCommand = {
5628
5628
  * `doctor notifications`) and any check that a message really arrives.
5629
5629
  */
5630
5630
  const ID$1 = "monitoring-checks";
5631
- const TITLE = "monitoring checks match";
5631
+ const TITLE$1 = "monitoring checks match";
5632
5632
  async function runDoctorMonitoring(input) {
5633
5633
  const print = input.print ?? ((line) => console.log(line));
5634
5634
  const logger = input.logger ?? getLogger();
@@ -5654,7 +5654,7 @@ async function runDoctorMonitoring(input) {
5654
5654
  async function checkRow(loader) {
5655
5655
  const skip = (detail) => ({
5656
5656
  id: ID$1,
5657
- title: TITLE,
5657
+ title: TITLE$1,
5658
5658
  status: "skip",
5659
5659
  detail,
5660
5660
  problems: []
@@ -5663,7 +5663,7 @@ async function checkRow(loader) {
5663
5663
  if (loader.loadFailures().some((f) => f.key === "monitoring")) return skip(whyMissing(loader, "monitoring", "no `monitoring` provider is available"));
5664
5664
  return {
5665
5665
  id: ID$1,
5666
- title: TITLE,
5666
+ title: TITLE$1,
5667
5667
  status: "ok",
5668
5668
  detail: "none declared",
5669
5669
  problems: []
@@ -5672,7 +5672,7 @@ async function checkRow(loader) {
5672
5672
  const monitoring = loader.get("monitoring");
5673
5673
  if (monitoring.checks.length === 0) return {
5674
5674
  id: ID$1,
5675
- title: TITLE,
5675
+ title: TITLE$1,
5676
5676
  status: "ok",
5677
5677
  detail: "none declared",
5678
5678
  problems: []
@@ -5682,7 +5682,7 @@ async function checkRow(loader) {
5682
5682
  const problems = compareChecks(monitoring.checks, await monitoring.listChecks());
5683
5683
  if (problems.length > 0) return {
5684
5684
  id: ID$1,
5685
- title: TITLE,
5685
+ title: TITLE$1,
5686
5686
  status: "fail",
5687
5687
  detail: `${problems.length} problem(s)`,
5688
5688
  problems
@@ -5690,7 +5690,7 @@ async function checkRow(loader) {
5690
5690
  const n = monitoring.checks.length;
5691
5691
  return {
5692
5692
  id: ID$1,
5693
- title: TITLE,
5693
+ title: TITLE$1,
5694
5694
  status: "ok",
5695
5695
  detail: `${n} of ${n} match`,
5696
5696
  problems: []
@@ -5700,7 +5700,7 @@ async function checkRow(loader) {
5700
5700
  if (noToken !== void 0) return skip(noToken);
5701
5701
  return {
5702
5702
  id: ID$1,
5703
- title: TITLE,
5703
+ title: TITLE$1,
5704
5704
  status: "fail",
5705
5705
  detail: errorMessage(err),
5706
5706
  problems: []
@@ -5823,6 +5823,24 @@ function resultRow(id, title, problems, ok) {
5823
5823
  problems
5824
5824
  };
5825
5825
  }
5826
+ // src/commands/bot-permission-checks/bot-permission-checks.ts
5827
+ const TITLE = "bot holds the server-wide permissions it needs";
5828
+ /**
5829
+ * The step of `doctor notifications` for the bot's own role: the permissions the provider says it needs (read from
5830
+ * `inspect`, server-wide, before any channel overwrite) are all held. A failure names the missing ones and carries the
5831
+ * link that invites the bot again asking for them, which updates its role in place. Read-only. No row when the provider
5832
+ * reports nothing about its bot; a skip when the server or the bot's roles could not be read.
5833
+ */
5834
+ function botPermissionChecks(input) {
5835
+ const { found } = input;
5836
+ if (!found) return [skipRow("bot-permissions", TITLE, "not checked: could not read the server")];
5837
+ if (found.botPermissionsError) return [skipRow("bot-permissions", TITLE, `not checked: could not read the bot's roles (${sanitizeDetail(found.botPermissionsError)})`)];
5838
+ const { botPermissions } = found;
5839
+ if (!botPermissions) return [];
5840
+ const { missing, inviteUrl } = botPermissions;
5841
+ const problems = missing.length === 0 ? [] : [`missing: ${missing.map((m) => sanitizeDetail(m)).join(", ")}`, ...inviteUrl ? [`invite the bot again with them (updates its role in place): ${inviteUrl}`] : []];
5842
+ return [resultRow("bot-permissions", TITLE, problems, "every permission it needs")];
5843
+ }
5826
5844
  // src/commands/notifications-setup/layout-picture-problem/layout-picture-problem.ts
5827
5845
  /** The first reason a picture in the layout (`webhookAvatar`, a channel's `webhook.avatar`) cannot work, or undefined. */
5828
5846
  function layoutPictureProblem(layout) {
@@ -8037,6 +8055,7 @@ async function runDoctorNotifications(input) {
8037
8055
  missingReason: whyMissing(loader, "monitoring", "no `monitoring` provider is configured"),
8038
8056
  found
8039
8057
  }));
8058
+ checks.push(...botPermissionChecks({ found }));
8040
8059
  checks.push(...prFeedChecks({
8041
8060
  layout,
8042
8061
  found