@theholocron/cli 5.0.0-alpha.429 → 5.0.0-alpha.430
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 +27 -32
- package/dist/cli.mjs +1344 -1110
- package/dist/cli.mjs.map +1 -1
- package/dist/{config-system-b3wXHmZF.mjs → config-system-CijVTCFk.mjs} +1 -1
- package/dist/{index-4MVAtJs5.d.mts → index-BFrWaQ3Y.d.mts} +12 -7
- package/dist/index.d.mts +8 -8
- package/dist/index.mjs +4 -4
- package/dist/plugin/capabilities.d.mts +1 -1
- package/dist/presets.d.mts +1 -1
- package/dist/presets.mjs +1 -1
- package/package.json +9 -9
package/README.md
CHANGED
|
@@ -264,7 +264,7 @@ Additional `repo` fields recognised by `holocron setup`:
|
|
|
264
264
|
| `repo.topics` | `string[]` | GitHub topics set on the repository. |
|
|
265
265
|
| `repo.protection` | `"balanced" \| "strict" \| "none"` | Branch-protection preset applied by `holocron setup`. For `"strict"`, the required status checks are derived from the task manifest — see below. |
|
|
266
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 setup`. Undeclared ones are left alone unless `prune` is on. `sync: [{ environment, keys, scope?, visibility? }]` names the vault environment `holocron sync secrets` fills Actions variables from (a separate environment from the secrets one; names only, a blank value is skipped, `doctor
|
|
267
|
+
| `repo.variables` | `{ repo?, org?, sync?, prune? }` | GitHub Actions variables created and updated by `holocron setup`. Undeclared ones are left alone unless `prune` is on. `sync: [{ environment, keys, scope?, visibility? }]` names the vault environment `holocron sync secrets` fills Actions variables from (a separate environment from the secrets one; names only, a blank value is skipped, `doctor secrets` expects the names). A name given as a literal and in `sync`, or `prune` with `sync`, is a config error. |
|
|
268
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 `sync secrets` fills from (it follows these entries, one step per scope, unless `--github-secret` is given; the `local` and `dev` layers are never synced (a `ConfigError`, and an entry naming them does not load); an environment with no entry and no `--github-secret` is a `ConfigError` before the vault is read, #2104; 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
|
|
@@ -622,40 +622,35 @@ 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
|
|
626
|
-
|
|
|
627
|
-
| `holocron setup notifications`
|
|
628
|
-
| `holocron new channel <name>`
|
|
629
|
-
| `holocron new server --name <n> --owner <id>`
|
|
630
|
-
| `holocron link account`
|
|
631
|
-
| `holocron sync roles`
|
|
632
|
-
| `holocron reconcile project [board]`
|
|
633
|
-
| `holocron doctor notifications [--built-only] [--deliver] [--post]`
|
|
634
|
-
| `holocron doctor
|
|
635
|
-
| `holocron doctor
|
|
636
|
-
| `holocron doctor
|
|
637
|
-
| `holocron doctor
|
|
638
|
-
| `holocron doctor
|
|
639
|
-
| `holocron doctor
|
|
640
|
-
| `holocron doctor
|
|
641
|
-
| `holocron doctor
|
|
642
|
-
| `holocron doctor
|
|
643
|
-
| `holocron doctor
|
|
644
|
-
| `holocron doctor
|
|
645
|
-
| `holocron
|
|
646
|
-
| `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 |
|
|
647
|
-
| `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 |
|
|
648
|
-
| `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 |
|
|
649
|
-
| `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 |
|
|
650
|
-
| `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 setup notifications` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
|
|
628
|
+
| `holocron new channel <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
|
|
629
|
+
| `holocron new 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 link account` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
|
|
631
|
+
| `holocron sync roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
|
|
632
|
+
| `holocron reconcile project [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 `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 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 |
|
|
635
|
+
| `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 |
|
|
636
|
+
| `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 |
|
|
637
|
+
| `holocron doctor environments` | Do the deployment environments exist? The ones `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 |
|
|
638
|
+
| `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 `reconcile project` 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. |
|
|
639
|
+
| `holocron doctor repo` | Do the repository settings `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 |
|
|
640
|
+
| `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 |
|
|
641
|
+
| `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 |
|
|
642
|
+
| `holocron doctor secrets [--env <list>] [--only-secrets \| --only-variables] [--strict] [--name <name>] [--verify] [--shared [--allow NAME]...]` | Prints a matrix of every secret and variable by place (1Password Environments, GitHub, deployments; names only, cells `ok`, `n/a`, `MISSING`, `extra`, `?`) and checks the declared ones. `MISSING` fails; `extra` is info (`--strict` fails; `doctor.manualSecrets` is left out); `--name` explains one name and exits 0 (this and `extra` replace `doctor variable-owners`). `--shared` compares the layers named by `--env` (two or more of `local`, `dev`, `ci`, `prod`; all four by default) for a secret that holds the same value in two of them: it reads each Environment in memory, compares the concealed entries by a salted hash made fresh per run, and prints names only, one row per pair of layers (`info`, shown as skipped; `--strict` fails), plus `info` rows for `ci` variables missing from or different in `dev`; `doctor.sharedVariables` and `--allow` leave out names shared on purpose (the old `doctor secrets`). `--verify` also asks each vendor whether the tokens the plugins take are still accepted (online; fails a rejected token or one with 7 days or fewer left; the old `doctor tokens`). It also checks `repo.variables` (the old `doctor variables`). 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. `--env` takes a comma-separated or repeated list of `local`, `dev`, `ci`, `test`, `prod` and checks only those (`ci` the GitHub secrets, `prod` the deploy destinations; `local`, `dev` and `test` are a skipped row that says why). A scope that cannot be read is a skip |
|
|
643
|
+
| `holocron doctor --all` | Runs every deep check (`doctor notifications`, `doctor secrets`, ...) 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 |
|
|
644
|
+
| `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 |
|
|
645
|
+
| `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 |
|
|
651
646
|
|
|
652
647
|
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).
|
|
653
648
|
|
|
654
649
|
Channels fed by the error tracker add `feeds: { errors: true }` and a layout `relay: { host, zone?, script?, code? }`: `setup` makes a dedicated webhook, points `host` at the Comlink Worker (a proxied DNS record via `dns`), and deploys it via `workers.deployScript` with the webhook URL as `COMLINK_<SOURCE>_WEBHOOK`. The URL never leaves the Worker's secret; other secrets on the script are kept. With `relay.errors: { projects, integration?, rule?, frequency? }` it also ensures the tracker's integration and alert rule (`errors.ensureRelay`) and deploys the Worker with the integration's signing secret. Needs `errors`, `workers` and `dns`; only one channel may be fed.
|
|
655
650
|
|
|
656
|
-
`holocron sync secrets <
|
|
651
|
+
`holocron sync secrets --env <environment> --worker <script>` also sets every key of the vault environment on a deployed Worker as a secret, through the optional `Workers.setSecret(script, name, value)` (write-only; the Cloudflare plugin implements it). The Worker must already exist. Sync only adds and updates: it never removes a binding, because a Worker also holds secrets that are not in the vault (for Comlink, the `COMLINK_<SOURCE>_WEBHOOK` that `setup notifications` sets), so a key deleted from the vault must be deleted from the Worker separately. Keys are written one at a time and each is reported; if one fails, the exit code is 1 and re-running finishes the rest, since every write is idempotent.
|
|
657
652
|
|
|
658
|
-
`holocron sync secrets <
|
|
653
|
+
`holocron sync secrets --env <environment>` 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 secrets` checks that the names exist at their scope.
|
|
659
654
|
|
|
660
655
|
`holocron list secrets [--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`.
|
|
661
656
|
|
|
@@ -783,7 +778,7 @@ The resolution chain per capability is:
|
|
|
783
778
|
See [`docs/tokens.md`](../../docs/tokens.md) for required PAT scopes per feature.
|
|
784
779
|
|
|
785
780
|
A plugin lists the tokens it takes in a `tokens: PluginToken[]` export (each resolver exposes its own as `.token`), as
|
|
786
|
-
`{ envName, vendorEnvName?, keyringKey, verifiable?, optional? }`, so `holocron doctor
|
|
781
|
+
`{ envName, vendorEnvName?, keyringKey, verifiable?, optional? }`, so `holocron doctor secrets` (the `local` and `dev` columns, and `--verify`) and
|
|
787
782
|
`export tokens` can find them. Set `optional: true` on a token the plugin only falls back to, such as the Discord
|
|
788
783
|
webhook a post uses when it names no channel: the checks that expect every listed token do not expect it, and
|
|
789
784
|
`export tokens` marks it `(optional)` when it has no value. `verifiable: false` marks a token `verifyToken` does not
|
|
@@ -936,8 +931,8 @@ the local override exists to exempt.
|
|
|
936
931
|
`publish bump-versions`, `publish tag`, `sync github`, `upgrade node`,
|
|
937
932
|
`upgrade deps`, `new plugin`, `check token`, `export tokens`, `setup notifications`,
|
|
938
933
|
`new channel`, `link account`,
|
|
939
|
-
`sync roles`, `doctor ci`, `doctor
|
|
940
|
-
`sync roles`, `reconcile project`, `doctor ci`, `doctor
|
|
934
|
+
`sync roles`, `doctor ci`, `doctor dns`, `doctor environments`, `doctor monitoring`, `doctor notifications`, `doctor project`, `doctor repo`, `doctor secrets`
|
|
935
|
+
`sync roles`, `reconcile project`, `doctor ci`, `doctor dns`, `doctor environments`, `doctor monitoring`, `doctor notifications`, `doctor repo`, `doctor secrets`
|
|
941
936
|
- `src/commands/deep-checks/` — `DEEP_CHECKS`, the registry every `doctor <capability>` is
|
|
942
937
|
listed in; the shared row renderer and `declaredVsActual` helper are in `@theholocron/kyber/ui`
|
|
943
938
|
- `src/interactive-menu/` — the interactive fallback's Holocron data: `command-catalog`
|