@theholocron/cli 5.0.0-alpha.417 → 5.0.0-alpha.419

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
@@ -258,14 +258,14 @@ and nothing else carries a copy. `.holocron/org.md` (the agent contract the CLI
258
258
 
259
259
  Additional `repo` fields recognised by `holocron repo setup`:
260
260
 
261
- | Field | Type | Description |
262
- | ----------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
263
- | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron repo setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
264
- | `repo.topics` | `string[]` | GitHub topics set on the repository. |
265
- | `repo.protection` | `"balanced" \| "strict" \| "none"` | Branch-protection preset applied by `holocron repo setup`. For `"strict"`, the required status checks are derived from the task manifest — see below. |
266
- | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
267
- | `repo.variables` | `{ repo?, org?, sync?, prune? }` | GitHub Actions variables created and updated by `holocron repo setup`. Undeclared ones are left alone unless `prune` is on. `sync: [{ environment, keys, scope?, visibility? }]` names the vault environment `holocron secrets sync` fills Actions variables from (a separate environment from the secrets one; names only, a blank value is skipped, `doctor variables` expects the names). A name given as a literal and in `sync`, or `prune` with `sync`, is a config error. |
268
- | `repo.secrets` | `{ repo?, org?, environments?, sync? }` | Names of the secrets that must exist, checked (never written) by `holocron doctor secrets`. Names only. The notification layout's secrets and a Chromatic project token are expected without being listed. `sync: [{ environment, keys?, scope? }]` declares the vault environments `secrets sync` fills from (it follows these entries, one step per scope, unless `--github-secret` is given; a blank value is skipped); the doctor expects their keys (every key the `vault` provider lists when `keys` is omitted, names only) at the `scope` (`repo`, `env=<name>`, `org=<name>`). |
261
+ | Field | Type | Description |
262
+ | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
263
+ | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron repo setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
264
+ | `repo.topics` | `string[]` | GitHub topics set on the repository. |
265
+ | `repo.protection` | `"balanced" \| "strict" \| "none"` | Branch-protection preset applied by `holocron repo setup`. For `"strict"`, the required status checks are derived from the task manifest — see below. |
266
+ | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
267
+ | `repo.variables` | `{ repo?, org?, sync?, prune? }` | GitHub Actions variables created and updated by `holocron repo setup`. Undeclared ones are left alone unless `prune` is on. `sync: [{ environment, keys, scope?, visibility? }]` names the vault environment `holocron secrets sync` fills Actions variables from (a separate environment from the secrets one; names only, a blank value is skipped, `doctor variables` expects the names). A name given as a literal and in `sync`, or `prune` with `sync`, is a config error. |
268
+ | `repo.secrets` | `{ repo?, org?, environments?, sync? }` | Names of the secrets that must exist, checked (never written) by `holocron doctor secrets`. Names only. The notification layout's secrets and a Chromatic project token are expected without being listed. `sync: [{ environment, keys?, scope?, repos? }]` declares the vault environments `secrets sync` fills from (it follows these entries, one step per scope, unless `--github-secret` is given; a blank value is skipped); the doctor expects their keys (every key the `vault` provider lists when `keys` is omitted, names only) at the `scope` (`repo`, `env=<name>`, `org=<name>`). An `org=` scope requires `repos`, the repositories that can read the secrets (visibility `selected`, never `all`); without it the config does not load. `doctor secrets` flags a secret readable by more repositories than its entry lists, and a name held at both repository and organization level. |
269
269
 
270
270
  ### Custom properties synced to GitHub
271
271
 
@@ -622,31 +622,31 @@ A `notifications` provider can declare a whole server in `holocron.config.ts`
622
622
  pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
623
623
  commands and the config are provider-neutral; Discord is the first provider.
624
624
 
625
- | Command | What it does |
626
- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
627
- | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
628
- | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
629
- | `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) |
630
- | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
631
- | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
632
- | `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 |
633
- | `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 |
634
- | `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 |
635
- | `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 |
636
- | `holocron doctor github-app` | Does each GitHub App instance in `githubApps` (`{ name, manifest, environment }`) have what its manifest file (`default_permissions`, `default_events`) declares? Reads the App's id and key from the vault `environment` in memory (never printed), calls `GET /app` and `GET /app/installations` with the App's JWT. Rows per instance: `reachable`, `events` (all subscribed), `permissions` (each granted at least at the manifest's level, `read < write < admin`), `installations` (none lags the App, a pending update fails). Extras on the App are `info` in a row's detail, never a failure. A gap ends with the App's settings page (user- or organization-owned) and, for an installation, its own page. Credentials that cannot be read are a skip; an unreadable manifest or a rejected JWT fails. Read-only |
637
- | `holocron doctor logs` | Does each Axiom dataset the setup ships logs to exist, and does the token reach it? Rows: `token is accepted` (a 401 fails), one `dataset for <service>` for the CLI (`HOLOCRON_AXIOM_DATASET`, resolved by the logger's own chain), Sentinel (`SENTINEL_AXIOM_DATASET`) and any other `dev.serve.logging.datasetVar` (a 404 fails and names the fix), `organization` (`HOLOCRON_AXIOM_ORG`, then `AXIOM_ORG`), and an `info` row per dataset with the `retentionDays` Axiom reports (or says it reported none). Reads through the optional `Logs.readDataset` / `Logs.checkToken`; never creates a dataset or prints a token. A name or token that cannot be read is a skip. Read-only |
638
- | `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 |
639
- | `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. |
640
- | `holocron doctor variable-owners` | Does a variable name live in more than one place? Reads the names (never a value) of the 1Password Environments the config names and of the GitHub Actions secrets and variables, and fails for a name two places hold, unless a `repo.secrets.sync` / `repo.variables.sync` entry made the copy, `doctor.sharedVariables` lists it, or both places are instances of one `githubApps` App. A bare name beside its prefixed one (`X`, `HOLOCRON_X`) is an `info` row; a place that cannot be read is a skip. Read-only |
641
- | `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. |
642
- | `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 |
643
- | `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 |
644
- | `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 |
645
- | `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 |
646
- | `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, the repo's `.env` and the `credentials` providers, then keyring; a `credentials` provider that cannot be read is a failing row) 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 |
647
- | `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 |
648
- | `holocron provider [<name> [setup\|doctor]] [--with <file or key=value>]... [--dry-run] [--yes]` | Set up or check what only one provider has (a Linear team's labels, project and auto-close/auto-archive), from that provider's own block of `holocron.config`, or, for a provider the config does not name, from `--with` (repeatable: `team=ENG`, or a `.json`/`.ts`/`.js` file holding the provider's options object; it goes over the config entry's options where there is one, never writes the config, and the token still comes from `--token` or the usual chain). A plugin offers it by returning `setup` / `doctor` from `createPlugin`; `doctor` is read-only, `setup` is idempotent, never deletes, supports `--dry-run` and asks first unless `--yes`. Rows are the shared `printCheckRows` ones; nothing secret is printed |
649
- | `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 |
625
+ | Command | What it does |
626
+ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
627
+ | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
628
+ | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
629
+ | `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) |
630
+ | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
631
+ | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
632
+ | `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 |
633
+ | `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 fail). 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 |
634
+ | `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 |
635
+ | `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 |
636
+ | `holocron doctor github-app` | Does each GitHub App instance in `githubApps` (`{ name, manifest, environment }`) have what its manifest file (`default_permissions`, `default_events`) declares? Reads the App's id and key from the vault `environment` in memory (never printed), calls `GET /app` and `GET /app/installations` with the App's JWT. Rows per instance: `reachable`, `events` (all subscribed), `permissions` (each granted at least at the manifest's level, `read < write < admin`), `installations` (none lags the App, a pending update fails). Extras on the App are `info` in a row's detail, never a failure. A gap ends with the App's settings page (user- or organization-owned) and, for an installation, its own page. Credentials that cannot be read are a skip; an unreadable manifest or a rejected JWT fails. Read-only |
637
+ | `holocron doctor logs` | Does each Axiom dataset the setup ships logs to exist, and does the token reach it? Rows: `token is accepted` (a 401 fails), one `dataset for <service>` for the CLI (`HOLOCRON_AXIOM_DATASET`, resolved by the logger's own chain), Sentinel (`SENTINEL_AXIOM_DATASET`) and any other `dev.serve.logging.datasetVar` (a 404 fails and names the fix), `organization` (`HOLOCRON_AXIOM_ORG`, then `AXIOM_ORG`), and an `info` row per dataset with the `retentionDays` Axiom reports (or says it reported none). Reads through the optional `Logs.readDataset` / `Logs.checkToken`; never creates a dataset or prints a token. A name or token that cannot be read is a skip. Read-only |
638
+ | `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 |
639
+ | `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. |
640
+ | `holocron doctor variable-owners` | Does a variable name live in more than one place? Reads the names (never a value) of the 1Password Environments the config names and of the GitHub Actions secrets and variables, and fails for a name two places hold, unless a `repo.secrets.sync` / `repo.variables.sync` entry made the copy, `doctor.sharedVariables` lists it, or both places are instances of one `githubApps` App. A bare name beside its prefixed one (`X`, `HOLOCRON_X`) is an `info` row; a place that cannot be read is a skip. Read-only |
641
+ | `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. |
642
+ | `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 |
643
+ | `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 site 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 |
644
+ | `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, could not load or has no token is a skip |
645
+ | `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 |
646
+ | `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, the repo's `.env` and the `credentials` providers, then keyring; a `credentials` provider that cannot be read is a failing row) 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 |
647
+ | `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 fails. 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 |
648
+ | `holocron provider [<name> [setup\|doctor]] [--with <file or key=value>]... [--dry-run] [--yes]` | Set up or check what only one provider has (a Linear team's labels, project and auto-close/auto-archive), from that provider's own block of `holocron.config`, or, for a provider the config does not name, from `--with` (repeatable: `team=ENG`, or a `.json`/`.ts`/`.js` file holding the provider's options object; it goes over the config entry's options where there is one, never writes the config, and the token still comes from `--token` or the usual chain). A plugin offers it by returning `setup` / `doctor` from `createPlugin`; `doctor` is read-only, `setup` is idempotent, never deletes, supports `--dry-run` and asks first unless `--yes`. Rows are the shared `printCheckRows` ones; nothing secret is printed |
649
+ | `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 |
650
650
 
651
651
  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).
652
652
 
@@ -656,7 +656,7 @@ Channels fed by the error tracker add `feeds: { errors: true }` and a layout `re
656
656
 
657
657
  `holocron secrets sync <env>` also writes GitHub Actions **variables** when `repo.variables.sync` has an entry for that environment: each key goes through the `source` provider's `syncVariables` (repo scope) or `syncOrgVariables` (`org=<name>`), one call per key and never pruning, so a name the vault lacks or holds blank is skipped and GitHub keeps its value. Keep these in a vault environment of their own (a vault does not tell a visible value from a secret one, and a variable is readable afterwards). An environment declared only by variable entries pushes nothing to `secrets` or `deployment`. Values are never printed. `doctor variables` checks that the names exist at their scope.
658
658
 
659
- `holocron secrets list [--scope repo|environment|organization] [--env <name>] [--json]` prints the names (never the values; GitHub does not return them) of the secrets at each scope, sorted, under a heading per scope. With no `--scope` it lists the repository, plus the organization (`--org`, `HOLOCRON_ORG` or the config's `org`) and the `--env` environment when they are known; `--scope` lists one. A scope that cannot be listed is reported under its heading and the rest are still listed; the exit code is 1 if any failed. `--json` prints `[{ scope, names, error? }]`. It is read-only, so `--dry-run` does not apply. Comparing the names with what the config expects is `doctor secrets`, which also covers the keys of the vault environments declared in `repo.secrets.sync`.
659
+ `holocron secrets list [--scope repo|environment|organization] [--env <name>] [--json]` prints the names (never the values; GitHub does not return them) of the secrets at each scope, sorted, under a heading per scope. With no `--scope` it lists the repository, plus the organization (`--org`, `HOLOCRON_ORG` or the config's `org`) and the `--env` environment when they are known; `--scope` lists one. A scope that cannot be listed is reported under its heading and the rest are still listed; the exit code is 1 if any fails. `--json` prints `[{ scope, names, error? }]`. It is read-only, so `--dry-run` does not apply. Comparing the names with what the config expects is `doctor secrets`, which also covers the keys of the vault environments declared in `repo.secrets.sync`.
660
660
 
661
661
  A channel with `kind: "forum"` is a forum, with `tags` (each a `name`, an `emoji` and whether it is `moderated`); `setup` adds and corrects the tags but never removes one, and a text channel of the same name must be deleted first, since neither kind can become the other. A forum takes no `webhook` and none of the webhook feeds (`monitoring`, `errors`); its one feed is `feeds: { prs: true }`, the pull-request feed, where Sentinel keeps one post per pull request tagged with its state. The object form `feeds: { prs: { exclude: { repos?: ["owner/name"], authors?: ["login"] } } }` leaves some pull requests out. `feeds.prs` belongs to a forum (a text channel with it is refused) and the forum's `tags` must hold all eight states, `draft`, `conflicts`, `failing`, `changes requested`, `ready`, `waiting`, `merged` and `closed`, or `setup` refuses the layout. `setup` does nothing more for it; `doctor notifications` checks that the forum exists, has those tags and that the bot can start posts and manage threads in it (`ServerInspection` `botThreads`, filled in by the Discord provider after the forum's own permission overwrites). `defaultReaction` is the emoji Discord offers on every post (its Get Started step "Set a default reaction for posts"); Discord allows only one, so `starterReactions` lists more (`["👍", "👎", "❓"]` for approve, disapprove, question) that the bot adds to the first message of each post `specs sync` makes. Existing posts are left alone, a reaction the bot cannot add is skipped, and `doctor notifications` checks `defaultReaction`. Unicode emoji only.
662
662
 
@@ -686,7 +686,7 @@ Capability surface behind it (all optional, so providers without the concept omi
686
686
  `Source.writeFile(path, content, { message, version?, repo? })` (a changed `version` is refused: a real conflict check).
687
687
  - `Notifications.createServer({ name, force? })`, `inviteLink(channel)`, `hasMember(id)`, `transferServer(id)` and `serverOwner()`: create a server, invite its owner, check they joined, hand it over, and say who owns it.
688
688
  - `Notifications.roleMembers(role)`, `addRoleMember(role, memberId)`, `removeRoleMember(role, memberId)`.
689
- - `Notifications.checkDelivery({ channel, name, category?, text })`: posts through a channel's webhook, reads the post back and removes it, and says which step failed.
689
+ - `Notifications.checkDelivery({ channel, name, category?, text })`: posts through a channel's webhook, reads the post back and removes it, and says which step fails.
690
690
  - `Notifications.signIn()` returning `{ authorizeUrl, complete }`: the provider-neutral shape of "prove which account you own".
691
691
  - `Notifications.ensureApplication` returns `{ updated, todo? }`; each `todo` is a step only a person can do (a portal setting
692
692
  the API ignores) and is reported as a failure until done.
package/dist/cli.mjs CHANGED
@@ -188,13 +188,43 @@ function validateSecretsDeploy(secrets) {
188
188
  // src/config/validate-secrets-sync/validate-secrets-sync.ts
189
189
  /**
190
190
  * Check `repo.secrets.sync`: each entry names its vault environment one way, a literal `environment` or a `layer`
191
- * (spec `tech-environment-layers`, #2069).
191
+ * (spec `tech-environment-layers`, #2069). An organization
192
+ * scope must say who can read the secrets: `visibility: "selected"` (or left out) and a non-empty `repos` list. A
193
+ * concealed value is never readable by every repository, so `visibility: "all"` and `"private"` are errors, and an
194
+ * entry with no list does not load (spec `tech-org-secret-visibility`, #2062). `repos` and `visibility` mean nothing
195
+ * on another scope, so they are errors there. A repository name is `name` or `<org>/name` of the scope's own
196
+ * organization, and one key may not be given two different reader lists at the same organization.
192
197
  *
193
198
  * @param secrets - `repo.secrets`, if the config has it.
194
199
  * @throws {ConfigError} Naming the first problem found.
195
200
  */
196
201
  function validateSecretsSync(secrets) {
197
- for (const entry of secrets?.sync ?? []) validateEnvironmentChoice(entry, "a `repo.secrets.sync` entry");
202
+ const readers = /* @__PURE__ */ new Map();
203
+ for (const entry of secrets?.sync ?? []) {
204
+ const named = validateEnvironmentChoice(entry, "a `repo.secrets.sync` entry");
205
+ const label = `\`repo.secrets.sync\` entry for ${JSON.stringify(named)}`;
206
+ const scope = entry.scope ?? "repo";
207
+ if (!scope.startsWith("org=")) {
208
+ if (entry.visibility !== void 0 || entry.repos !== void 0) throw new ConfigError(`${label} sets \`visibility\` or \`repos\` on scope ${JSON.stringify(scope)}: only an organization scope ("org=<name>") has readers to name`);
209
+ continue;
210
+ }
211
+ const org = scope.slice(4);
212
+ if (entry.visibility !== void 0 && entry.visibility !== "selected") throw new ConfigError(`${label} has visibility ${JSON.stringify(entry.visibility)}: a secret is never readable by every repository, so use "selected" with \`repos\``);
213
+ const { repos } = entry;
214
+ if (!Array.isArray(repos) || repos.length === 0 || repos.some((r) => typeof r !== "string" || !/^(?:[^/]+\/)?[^/]+$/.test(r))) throw new ConfigError(`${label} needs \`repos\`, a non-empty list of the repositories (\`name\` or \`<org>/name\`) that can read the secrets: an organization secret is never readable by every repository`);
215
+ const names = repos.map((r) => {
216
+ const slash = r.indexOf("/");
217
+ if ((slash < 0 ? org : r.slice(0, slash)) !== org) throw new ConfigError(`${label} lists repository ${JSON.stringify(r)}: use a name in ${JSON.stringify(org)}, such as "holocron"`);
218
+ return r.slice(slash + 1);
219
+ });
220
+ const list = [...new Set(names)].sort().join(", ");
221
+ for (const key of entry.keys ?? []) {
222
+ const id = `${org}/${key.toUpperCase()}`;
223
+ const seen = readers.get(id);
224
+ if (seen !== void 0 && seen !== list) throw new ConfigError(`${label} lists ${key}, which another \`repo.secrets.sync\` entry at org=${org} gives different readers [${seen}]: a secret has one reader list`);
225
+ readers.set(id, list);
226
+ }
227
+ }
198
228
  }
199
229
  // src/config/validate-variables-sync/validate-variables-sync.ts
200
230
  /** GitHub treats variable names as case-insensitive, so every comparison goes through this. */
@@ -10673,6 +10703,158 @@ const doctorRepoCommand = {
10673
10703
  })).status === "fail") process.exitCode = 1;
10674
10704
  }
10675
10705
  };
10706
+ // src/commands/secrets-sync/access-note/access-note.ts
10707
+ /** `selected [a, b]` or `all`: who can read, names only, repositories sorted. */
10708
+ function describeAccess(access) {
10709
+ return access.visibility === "selected" ? `selected [${[...access.repos ?? []].sort().join(", ")}]` : access.visibility;
10710
+ }
10711
+ /**
10712
+ * What a write does to who can read one organization secret, for its row: `new, readers selected [...]` when it does not
10713
+ * exist yet, `readers unchanged (...)` when it is as declared, `readers all -> selected [...]` when GitHub will replace
10714
+ * them (every write sets visibility, so the dry run can say it first). `current` is `undefined` for a secret that is
10715
+ * not there; `known` is false when the organization's secrets could not be read, so only the new readers are named.
10716
+ * Names only: a value is never read.
10717
+ *
10718
+ * @param wanted - The readers the entry declares.
10719
+ * @param current - The readers GitHub reports now, if the secret exists.
10720
+ * @param known - Whether the organization's secrets were read.
10721
+ */
10722
+ function accessNote(wanted, current, known) {
10723
+ const to = describeAccess(wanted);
10724
+ if (!known) return `readers -> ${to}`;
10725
+ if (!current) return `new, readers ${to}`;
10726
+ const from = describeAccess(current);
10727
+ return from === to ? `readers unchanged (${to})` : `readers ${from} -> ${to}`;
10728
+ }
10729
+ // src/commands/doctor-secrets/access-rows.ts
10730
+ /** The problems with who can read one secret, or none: names only. */
10731
+ function readerProblems(name, wanted, actual) {
10732
+ const to = `selected [${wanted.join(", ")}]`;
10733
+ if (actual.visibility !== "selected") return [`${name} is readable by ${actual.visibility === "all" ? "every repository" : "every private repository"} (visibility ${actual.visibility}); its entry says ${to}`];
10734
+ const have = new Set(actual.repos ?? []);
10735
+ const extra = [...have].filter((r) => !wanted.includes(r)).sort();
10736
+ const missing = wanted.filter((r) => !have.has(r));
10737
+ return [...extra.length > 0 ? [`${name} is also readable by ${extra.join(", ")}; its entry says ${to}`] : [], ...missing.length > 0 ? [`${name} is not readable by ${missing.join(", ")}; its entry says ${to}`] : []];
10738
+ }
10739
+ /**
10740
+ * Who can read the synced organization secrets, by name (spec `tech-org-secret-visibility`, #2062): one row for the
10741
+ * organization. It fails for a secret readable by more repositories than its entry says (visibility `all` or `private`,
10742
+ * or `selected` with an extra repository) or by fewer; a secret that does not exist is the "exist" row's finding, not
10743
+ * this one's. An ok row says how many secrets sit at each reader list. It is skipped, with the reason, when the provider
10744
+ * cannot report access or the token cannot read it. GitHub returns no value, and none is read.
10745
+ *
10746
+ * @param secrets - The `secrets` provider.
10747
+ * @param readers - The organization and its declared readers.
10748
+ * @param isOwn - Whether the organization is the one the run is in (its row id has no suffix).
10749
+ */
10750
+ async function accessRow(secrets, readers, isOwn) {
10751
+ const id = isOwn ? "org-secret-access" : `org-secret-access-${readers.org}`;
10752
+ const title = `${readers.org} organization secrets are readable only by their entries' repositories`;
10753
+ if (!secrets.listSecretAccess) return {
10754
+ id,
10755
+ title,
10756
+ status: "skip",
10757
+ detail: `secrets provider (${secrets.providerName}) cannot report who can read a secret`,
10758
+ problems: []
10759
+ };
10760
+ try {
10761
+ const found = new Map(Object.entries(await secrets.listSecretAccess({
10762
+ kind: "organization",
10763
+ name: readers.org
10764
+ })).map(([name, access]) => [name.toUpperCase(), access]));
10765
+ const problems = [];
10766
+ const groups = /* @__PURE__ */ new Map();
10767
+ for (const [name, wanted] of readers.declared) {
10768
+ const actual = found.get(name.toUpperCase());
10769
+ if (!actual) continue;
10770
+ problems.push(...readerProblems(name, wanted, actual));
10771
+ const label = describeAccess(actual);
10772
+ groups.set(label, (groups.get(label) ?? 0) + 1);
10773
+ }
10774
+ if (problems.length > 0) return {
10775
+ id,
10776
+ title,
10777
+ status: "fail",
10778
+ detail: `${problems.length} problem(s)`,
10779
+ problems
10780
+ };
10781
+ const summary = [...groups].map(([label, count]) => `${count} ${label}`).join("; ");
10782
+ return summary === "" ? {
10783
+ id,
10784
+ title,
10785
+ status: "skip",
10786
+ detail: "none of the synced secrets exist yet",
10787
+ problems: []
10788
+ } : {
10789
+ id,
10790
+ title,
10791
+ status: "ok",
10792
+ detail: summary,
10793
+ problems: []
10794
+ };
10795
+ } catch (err) {
10796
+ const noToken = missingTokenReason(err);
10797
+ if (noToken !== void 0) return {
10798
+ id,
10799
+ title,
10800
+ status: "skip",
10801
+ detail: noToken,
10802
+ problems: []
10803
+ };
10804
+ return {
10805
+ id,
10806
+ title,
10807
+ status: "fail",
10808
+ detail: errorMessage(err),
10809
+ problems: []
10810
+ };
10811
+ }
10812
+ }
10813
+ /**
10814
+ * A name that exists at both repository and organization level: the repository secret overrides the organization one,
10815
+ * so a stale copy keeps its old value after a rotation. The sync never deletes, so this is how the copy is found.
10816
+ * Skipped, with the reason, when the repository's secrets cannot be listed.
10817
+ *
10818
+ * @param secrets - The `secrets` provider.
10819
+ * @param orgNames - The organization secret names the config expects.
10820
+ */
10821
+ async function shadowRow(secrets, orgNames) {
10822
+ const id = "org-secret-shadowed";
10823
+ const title = "no organization secret is overridden by a repository secret of the same name";
10824
+ try {
10825
+ const repo = new Set((await secrets.listSecrets({ kind: "repo" })).map((n) => n.toUpperCase()));
10826
+ const problems = orgNames.filter((name) => repo.has(name.toUpperCase())).map((name) => `${name} exists at repository and organization level: the repository secret overrides it`);
10827
+ return problems.length > 0 ? {
10828
+ id,
10829
+ title,
10830
+ status: "fail",
10831
+ detail: `${problems.length} problem(s)`,
10832
+ problems
10833
+ } : {
10834
+ id,
10835
+ title,
10836
+ status: "ok",
10837
+ detail: `${orgNames.length} checked`,
10838
+ problems: []
10839
+ };
10840
+ } catch (err) {
10841
+ const noToken = missingTokenReason(err);
10842
+ if (noToken !== void 0) return {
10843
+ id,
10844
+ title,
10845
+ status: "skip",
10846
+ detail: noToken,
10847
+ problems: []
10848
+ };
10849
+ return {
10850
+ id,
10851
+ title,
10852
+ status: "fail",
10853
+ detail: errorMessage(err),
10854
+ problems: []
10855
+ };
10856
+ }
10857
+ }
10676
10858
  // src/commands/secrets-sync/deploy-filter/deploy-filter.ts
10677
10859
  /**
10678
10860
  * What `repo.secrets.deploy` lets one vault environment send to a deployment or a Worker: every entry naming it adds
@@ -10777,6 +10959,11 @@ function expectedSecrets(config, layouts) {
10777
10959
  environments: Object.fromEntries(Object.entries(declared?.environments ?? {}).map(([env, names]) => [env, uniqueNames(names)]))
10778
10960
  };
10779
10961
  }
10962
+ // src/commands/secrets-sync/repo-name/repo-name.ts
10963
+ /** `holocron` from `holocron` or `theholocron/holocron`: the config accepts both, the provider takes the name. */
10964
+ function repoName(repo) {
10965
+ return repo.slice(repo.indexOf("/") + 1);
10966
+ }
10780
10967
  // src/commands/doctor-secrets/synced-secrets.ts
10781
10968
  /**
10782
10969
  * The secrets `holocron secrets sync` fills from a vault, as `repo.secrets.sync` declares them: which names land at
@@ -10808,10 +10995,12 @@ async function syncedSecrets(entries, vault) {
10808
10995
  });
10809
10996
  continue;
10810
10997
  }
10998
+ const repos = entry.repos ? { repos: entry.repos.map(repoName) } : {};
10811
10999
  if (entry.keys) {
10812
11000
  scopes.push({
10813
11001
  scope,
10814
- names: entry.keys
11002
+ names: entry.keys,
11003
+ ...repos
10815
11004
  });
10816
11005
  continue;
10817
11006
  }
@@ -10827,7 +11016,8 @@ async function syncedSecrets(entries, vault) {
10827
11016
  else try {
10828
11017
  scopes.push({
10829
11018
  scope,
10830
- names: Object.keys(await vault.readEnvironment(environment))
11019
+ names: Object.keys(await vault.readEnvironment(environment)),
11020
+ ...repos
10831
11021
  });
10832
11022
  } catch (err) {
10833
11023
  skip(missingTokenReason(err) ?? `could not read vault environment ${environment}: ${describeError(err)}`);
@@ -10923,6 +11113,18 @@ async function runDoctorSecrets(input) {
10923
11113
  } else {
10924
11114
  const secrets = loader.get("secrets");
10925
11115
  for (const check of checks) rows.push(await checkScope(secrets, check));
11116
+ const readers = /* @__PURE__ */ new Map();
11117
+ for (const { scope, names, repos } of synced.scopes) {
11118
+ if (scope.kind !== "organization" || !repos) continue;
11119
+ const entry = readers.get(scope.name) ?? {
11120
+ org: scope.name,
11121
+ declared: /* @__PURE__ */ new Map()
11122
+ };
11123
+ for (const name of names) entry.declared.set(name, [...new Set(repos)].sort());
11124
+ readers.set(scope.name, entry);
11125
+ }
11126
+ for (const entry of readers.values()) rows.push(await accessRow(secrets, entry, entry.org === org));
11127
+ if (expected.org.length > 0) rows.push(await shadowRow(secrets, expected.org));
10926
11128
  }
10927
11129
  rows.push(...synced.rows, ...deployRows);
10928
11130
  printCheckRows(rows, print);
@@ -24519,17 +24721,25 @@ async function resolveEnvironmentId(id, input) {
24519
24721
  /**
24520
24722
  * The routes into `secrets` that `repo.secrets.sync` declares for one vault environment: every entry naming it gives
24521
24723
  * its keys (all of them when omitted) and the scope they land at (`repo` when omitted). An environment no entry names
24522
- * has no routes, which leaves `secrets sync` to its own flags.
24724
+ * has no routes, which leaves `secrets sync` to its own flags. An organization scope also carries
24725
+ * `visibility: "selected"` and its `repos`, as names in the organization (spec `tech-org-secret-visibility`, #2062).
24523
24726
  *
24524
24727
  * @param entries - `repo.secrets.sync`, if the config has it.
24525
24728
  * @param environmentId - The vault environment being synced.
24526
24729
  * @throws When an entry's `scope` is not `repo`, `env=<name>` or `org=<name>`.
24527
24730
  */
24528
24731
  function secretRoutes(entries, environmentId) {
24529
- return (entries ?? []).filter((entry) => entry.environment === environmentId).map((entry) => ({
24530
- scope: parseScope(entry.scope ?? "repo"),
24531
- ...entry.keys ? { keys: entry.keys } : {}
24532
- }));
24732
+ return (entries ?? []).filter((entry) => entry.environment === environmentId).map((entry) => {
24733
+ const scope = parseScope(entry.scope ?? "repo");
24734
+ return {
24735
+ scope: scope.kind === "organization" && entry.repos ? {
24736
+ ...scope,
24737
+ visibility: "selected",
24738
+ repos: entry.repos.map(repoName)
24739
+ } : scope,
24740
+ ...entry.keys ? { keys: entry.keys } : {}
24741
+ };
24742
+ });
24533
24743
  }
24534
24744
  // src/commands/secrets-sync/github-name/github-name.ts
24535
24745
  /**
@@ -24633,6 +24843,7 @@ async function runSecretsSync(input) {
24633
24843
  const dryRun = input.context.dryRun ?? false;
24634
24844
  const variablesOnly = (input.variableRoutes?.length ?? 0) > 0 && input.secretRoutes?.length === 0 && !input.projectId;
24635
24845
  if ((loader.has("deployment") && !variablesOnly && Boolean(input.projectId) || input.workerScript) && !input.deployFilter) throw new ConfigError(`no \`repo.secrets.deploy\` entry for environment ${JSON.stringify(input.environmentId)}: a deployment or a Worker receives only the keys named by \`keys\` or \`prefix\`, never every key. Add { environment: ${JSON.stringify(input.environmentId)}, prefix: "<PREFIX>_" } (or keys: [...]) to repo.secrets.deploy`);
24846
+ for (const route of input.secretRoutes ?? [{ scope: input.githubSecretScope ?? { kind: "repo" } }]) if (route.scope.kind === "organization" && !route.scope.repos?.length) throw new ConfigError(`organization secrets (org=${route.scope.name}) need an explicit reader list: declare them in \`repo.secrets.sync\` with \`repos: [...]\` (visibility "selected"), never "all"`);
24636
24847
  const targets = input.targets ?? ["production", "preview"];
24637
24848
  print(style.header(`Holocron secrets sync — environment ${input.environmentId}${dryRun ? " (dry-run)" : ""}`));
24638
24849
  print(style.dim(` vault: ${vaultProviderName(loader)}`));
@@ -24670,11 +24881,17 @@ async function runSecretsSync(input) {
24670
24881
  }];
24671
24882
  for (const route of routes) {
24672
24883
  print(style.step(routes.length > 1 ? `secrets (${scopeLabel(route.scope)})` : "secrets"));
24884
+ const access = await readAccess(secrets, route.scope, print);
24673
24885
  for (const key of route.keys ?? keys) {
24674
- rows.push(await pushRow(`secrets:${secrets.providerName}`, scopeLabel(route.scope), key, envVars, dryRun, async (value) => {
24886
+ const row = await pushRow(`secrets:${secrets.providerName}`, scopeLabel(route.scope), key, envVars, dryRun, async (value) => {
24675
24887
  await secrets.setSecret(route.scope, key, value);
24676
- }, nameCheck(secrets.providerName)));
24677
- print(formatRow(rows[rows.length - 1]));
24888
+ }, nameCheck(secrets.providerName));
24889
+ if (access && (row.status === "ok" || row.status === "dry-run")) row.message = accessNote({
24890
+ visibility: "selected",
24891
+ repos: access.wanted
24892
+ }, access.current?.get(key.toUpperCase()), access.current !== void 0);
24893
+ rows.push(row);
24894
+ print(formatRow(row));
24678
24895
  }
24679
24896
  }
24680
24897
  }
@@ -24777,6 +24994,26 @@ function reportFiltered(destination, scope, filtered, filter, rows, print) {
24777
24994
  });
24778
24995
  if (filtered.length > 0) print(style.dim(` · not sent (${filtered.length}, outside ${allowed}): ${filtered.join(", ")}`));
24779
24996
  }
24997
+ /**
24998
+ * For an organization scope: the readers the entry declares and, when the provider can report them, who can read each
24999
+ * secret now (by upper-cased name, since GitHub treats names as case-insensitive). A listing that fails is said once
25000
+ * and the write goes on without the difference. `undefined` for any other scope.
25001
+ */
25002
+ async function readAccess(secrets, scope, print) {
25003
+ if (scope.kind !== "organization") return void 0;
25004
+ const wanted = scope.repos;
25005
+ if (!secrets.listSecretAccess) return { wanted };
25006
+ try {
25007
+ const found = await secrets.listSecretAccess(scope);
25008
+ return {
25009
+ wanted,
25010
+ current: new Map(Object.entries(found).map(([name, a]) => [name.toUpperCase(), a]))
25011
+ };
25012
+ } catch (err) {
25013
+ print(style.dim(` · could not read who can read the organization's secrets (${describeError(err)})`));
25014
+ return { wanted };
25015
+ }
25016
+ }
24780
25017
  /** Log every row, then print and log the summary. Shared by a finished run and one that stopped at the vault. */
24781
25018
  function summarise(rows, logger, print, dryRun) {
24782
25019
  for (const r of rows) logger[r.status === "fail" ? "warn" : "info"]({