@theholocron/cli 5.0.0-alpha.22 → 5.0.0-alpha.220

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
@@ -17,33 +17,101 @@ holocron --help
17
17
  ## Interactive mode
18
18
 
19
19
  Run `holocron` with no command, a parent command with no subcommand
20
- (`holocron auth`, `holocron skills`, `holocron upgrade`), or a leaf command
21
- missing a required positional (`holocron deploy`, `holocron secret set`), and
22
- you get a prompt instead of a `--help` dead end:
20
+ (`holocron auth`, `holocron repo`, `holocron repo upgrade`, …), or a leaf command
21
+ missing a required positional (`holocron deploy`, `holocron secrets set`), and
22
+ you get a prompt instead of a `--help` dead end.
23
+
24
+ The menu mirrors the command tree: each level shows only the next word, and a
25
+ group (marked `›`) opens its own submenu, as deep as the commands nest. Nothing
26
+ is shown as a `<command> <subcommand>` path — `config show` is `config ›` then
27
+ `show`. Every submenu has a `← back` item, and a command that is also a group
28
+ (`repo sync`, `deploy`) has a `(run it)` item at the top of its submenu. Typing
29
+ searches the whole tree — `upgrade` at the top finds the `repo` group — with
30
+ name matches ranked above description matches.
31
+
32
+ ```console
33
+ $ holocron
34
+ ? What would you like to do? › repo
35
+ ❯ repo ›
36
+ ? repo — choose a subcommand: › upgrade
37
+ ? repo upgrade — choose a subcommand: › node
38
+ ? Target Node.js major version: › 24
39
+ ```
23
40
 
41
+ For a command that declares options (so far: `package publish` — more are
42
+ rolled out one command group at a time), it also offers those: any required
43
+ option is prompted like a positional, and everything else goes through one
44
+ "Set any options?" checkbox, prompting only what you picked:
45
+
46
+ ```console
47
+ ? Set any options? (space to select, enter to skip) › ◉ npm dist-tag ◯ One-time password (2FA)
48
+ ? npm dist-tag (blank = latest): › beta
24
49
  ```
25
- $ holocron
26
- ? What would you like to do? › dep
27
- ────────────────────────────────────────────────
28
- ❯ deploy Trigger a deployment via the configured `deployment` capability
29
50
 
30
- ? Branch to deploy: › main
51
+ `package publish` specifically has three workflows that don't mix — a
52
+ steady-state publish, a one-shot `--initial` bootstrap, and a `--sync-trust`
53
+ maintenance run — so it asks which one first, then only offers that
54
+ workflow's own options; nothing from a different workflow is ever shown:
55
+
56
+ ```console
57
+ ? What would you like to do? › Initial publish (--initial)
58
+ ? Set any options? (space to select, enter to skip) › ◉ One-time password (2FA)
59
+ ...dry-run output...
60
+ ? Dry run complete — proceed with the real run? › yes
61
+ ? One-time password (2FA), if npm requires it for this publish: › ***
31
62
  ```
32
63
 
64
+ Each workflow's label ends with its real flag in parentheses when it has
65
+ one, and a longer caveat ("use only for a package's very first publish")
66
+ shows as helper text under the highlighted choice rather than bloating the
67
+ label itself.
68
+
69
+ A secret option (`--otp`) is masked as you type and delivered to the spawned
70
+ command through its environment, never its argv — `ps` and shell history
71
+ both expose a child's argv, never its env. A time-sensitive one like `--otp`
72
+ is checked off early but not actually typed until right before the real run
73
+ — after the dry-run preview and the "proceed?" question, never before —
74
+ since a dry run never checks it anyway and a code typed any earlier risks
75
+ going stale while something else is still being answered.
76
+
77
+ Whether an option is _checkbox-optional vs. always included_ and _collected
78
+ upfront vs. collected last_ are independent choices. `package publish`'s
79
+ `--otp` is always collected last, but whether it's checkbox-optional depends
80
+ on `HOLOCRON_NPM_ENFORCE_2FA`: unset (the default), it's opt-in like any other
81
+ checkbox pick; set in your own shell profile (never checked into the repo),
82
+ it's always included — for an operator whose own npm account enforces 2FA
83
+ on every publish, so the box doesn't need re-checking every single run.
84
+ Setting it has no effect on anyone else publishing from the same repo.
85
+
33
86
  The picked command spawns as a normal `holocron <command> …` invocation —
34
87
  `--token`, `--org`, `--cwd`, and `--dry-run` on the original invocation carry
35
88
  through. A non-interactive shell (CI, a script, a pipe) gets the old
36
89
  hard-failure message instead of hanging on a prompt.
37
90
 
91
+ For a command whose handler honours `--dry-run` (most of them — everything
92
+ except `auth *` and `config show`), the menu always previews it first — a
93
+ dry run doesn't mutate anything, so there's nothing to ask permission for —
94
+ then asks the one real decision:
95
+
96
+ ```console
97
+ ...dry-run output...
98
+ ? Dry run complete — proceed with the real run? › yes
99
+ ```
100
+
101
+ A preview that reports nothing would actually change (e.g. `clone` finding
102
+ every repo already cloned) skips that question too — there'd be nothing for
103
+ the real run to do either. `--skip-dry-run` opts out of the preview
104
+ entirely, straight to the real run, for when you already know what you want.
105
+
38
106
  ## Execution contexts
39
107
 
40
108
  Every command is tagged with how much of a repo it needs:
41
109
 
42
- | Context | Needs | Examples |
43
- | ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
44
- | `global` | just the CLI binary | `version`, `clone`, `new`, `upgrade node`, `auth set` / `check`, `plugin create`, `skills …` |
45
- | `repo-aware` | `./holocron.config` in cwd, no plugins | `run`, `ci`, `config show`, `sync-readme` |
46
- | `workspace` | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `setup`, `sync`, `secrets sync`, `deploy` |
110
+ | Context | Needs | Examples |
111
+ | ------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
112
+ | `global` | the CLI binary alone | `version`, `clone`, `new repo` / `plugin`, `repo upgrade …`, `auth set` / `check`, `package …`, `run lint commit-msg`, `skills …` |
113
+ | `repo-aware` | `./holocron.config`, walking up from cwd, no plugins | `run`, `run ci`, `config show`, `repo sync readme`, `deploy on-release` |
114
+ | `workspace` | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `repo setup`, `repo sync`, `secrets …`, `deploy`, `sync github` |
47
115
 
48
116
  A `workspace` command run from a bare global install (no plugins next to the
49
117
  CLI) fails with one actionable line — install the plugins as devDependencies or
@@ -51,6 +119,21 @@ use `pnpm exec holocron <cmd>`. `auth check` degrades to "token present,
51
119
  verification skipped" instead. `holocron --help` prints the grouping; see
52
120
  [Execution Contexts](https://theholocron.github.io/holocron/execution-contexts).
53
121
 
122
+ ### Viewing the resolved config
123
+
124
+ `holocron config show` prints the resolved config. On a TTY it opens a foldable
125
+ tree by default; piped or redirected, it always emits plain, valid JSON
126
+ (`holocron config show | jq`).
127
+
128
+ ```console
129
+ holocron config show # TTY: foldable tree (↑↓ move, →/⏎ expand, ← collapse, E/C all, q quit)
130
+ holocron config show --depth 2 # static coloured tree, anything nested deeper than 2 levels collapsed
131
+ holocron config show --no-interactive # static coloured tree, fully expanded
132
+ ```
133
+
134
+ Passing `--interactive` explicitly needs a TTY on stdin and stdout and fails
135
+ with a one-line message otherwise; the default falls back to static output. It has no extra dependencies — nothing to install.
136
+
54
137
  ## Config file
55
138
 
56
139
  Holocron reads `holocron.config.{json,js,ts}` from the project root
@@ -103,18 +186,19 @@ A minimal config — for repos with a `package.json` and a GitHub remote
103
186
 
104
187
  ### repo options
105
188
 
106
- Additional `repo` fields recognised by `holocron setup`:
189
+ Additional `repo` fields recognised by `holocron repo setup`:
107
190
 
108
- | Field | Type | Description |
109
- | ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
- | `repo.teams` | `Array<string \| { slug, permission }>` | GitHub teams granted repo access. String shorthand defaults to `push` (Write). `holocron setup` also writes `.github/CODEOWNERS` for teams with `push`/`maintain`/`admin`. |
111
- | `repo.topics` | `string[]` | GitHub topics set on the repository. |
112
- | `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. |
113
- | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
191
+ | Field | Type | Description |
192
+ | ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
193
+ | `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`. |
194
+ | `repo.topics` | `string[]` | GitHub topics set on the repository. |
195
+ | `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. |
196
+ | `repo.properties` | `RepoProperties` | Org-level custom property values synced to the GitHub dashboard. |
197
+ | `repo.variables` | `{ repo?, org?, prune? }` | GitHub Actions variables created and updated by `holocron repo setup`. Undeclared ones are left alone unless `prune` is on. |
114
198
 
115
199
  ### Custom properties synced to GitHub
116
200
 
117
- `holocron setup` and `holocron sync` both call `syncProperties()` with two
201
+ `holocron repo setup` and `holocron repo sync` both call `syncProperties()` with two
118
202
  kinds of fields — always one-way (`holocron.config.ts` → resolved →
119
203
  properties; properties are never a second editable source of truth):
120
204
 
@@ -160,7 +244,7 @@ posts, instead of reporting pass/fail.
160
244
 
161
245
  ### Required status checks (`protection: "strict"`)
162
246
 
163
- `holocron setup` builds the branch-protection required-check list from the
247
+ `holocron repo setup` builds the branch-protection required-check list from the
164
248
  manifest, not a hand-maintained array:
165
249
 
166
250
  - `"DCO"` (hard-prepended), then
@@ -186,12 +270,32 @@ The generated ruleset also sets `require_extra_approval_for_unattributed_changes
186
270
  false` — with `required_approving_review_count: 0` and a single maintainer, the
187
271
  GitHub default (`true`) is an unsatisfiable block on any PR with an
188
272
  unverified/unattributed commit. Repository-admin bypass still covers the real
189
- risk. And the `codecov.yml` `holocron setup` writes carries `if_not_found:
273
+ risk. And the `codecov.yml` `holocron repo setup` writes carries `if_not_found:
190
274
  success` on every status default, so an infra-only PR (dep bump, config,
191
275
  lockfile — no coverable change) passes instead of hanging on a `codecov/*`
192
- required check that never posts. A re-run of `holocron setup` backfills both into
276
+ required check that never posts. A re-run of `holocron repo setup` backfills both into
193
277
  an existing repo.
194
278
 
279
+ ### Default branch (`repo.defaultBranch`)
280
+
281
+ ```ts
282
+ export default defineConfig({
283
+ repo: { protection: "strict", defaultBranch: "alpha" },
284
+ providers: { source: "github" },
285
+ });
286
+ ```
287
+
288
+ `holocron repo setup` syncs GitHub's repo-level default branch (`HEAD`) — what a
289
+ fresh clone checks out, what `gh pr create`/the compare UI target by default,
290
+ and what Sentinel's `validateConfig()` reads (it only ever reads config from
291
+ the repo's default branch, never a PR ref — a deliberate security boundary).
292
+ Omit this field to leave GitHub's current setting untouched; most repos never
293
+ need it. It exists for a repo using a `main`/`alpha` prerelease-channel split
294
+ where active development happens on a non-`main` branch: set this to that
295
+ branch so Sentinel validates against what's actually being developed, then
296
+ change it back once that branch merges to `main` for a stable cut and stops
297
+ being the active branch.
298
+
195
299
  ### Git hooks
196
300
 
197
301
  ```ts
@@ -202,7 +306,7 @@ export default defineConfig({
202
306
  });
203
307
  ```
204
308
 
205
- `holocron setup` writes `.husky/pre-push` (runs `holocron ci` before every
309
+ `holocron repo setup` writes `.husky/pre-push` (runs `holocron run ci` before every
206
310
  push) and `.husky/pre-commit` (runs `gitleaks protect --staged` + `lint-staged`
207
311
  before every commit — scoped to staged changes, not the whole history, so a
208
312
  past false positive can't permanently block future commits) and sets
@@ -213,7 +317,7 @@ setup --hooks` / `--no-hooks` override per run. Bypass one push with `git push
213
317
 
214
318
  ### Task scripts
215
319
 
216
- `holocron sync` reconciles `package.json#scripts` from the `tasks` manifest
320
+ `holocron repo sync` reconciles `package.json#scripts` from the `tasks` manifest
217
321
  (merge, never clobber — only the managed keys are touched):
218
322
 
219
323
  ```ts
@@ -248,8 +352,8 @@ export default defineConfig({
248
352
  `@theholocron/astromech`'s `loadTasksConfig` merges it over
249
353
  `holocron.config`'s `tasks` — **task arrays concatenate**
250
354
  (`holocron.config` first), the dedicated file **wins on scalars**,
251
- `extraRequiredChecks` concatenate. `holocron run` / `holocron ci` /
252
- `holocron setup` / `holocron sync` all read the merged result, so the
355
+ `extraRequiredChecks` concatenate. `holocron run` / `holocron run ci` /
356
+ `holocron repo setup` / `holocron repo sync` all read the merged result, so the
253
357
  split is transparent. Useful for keeping the capability/provider config
254
358
  and the "what this repo runs" manifest in separate files (this repo does).
255
359
 
@@ -276,10 +380,27 @@ job execute the same thing — at a turbo root both are
276
380
  `turbo run test -- --coverage` (the registry's org-default flags flow through
277
381
  turbo's `--`).
278
382
 
279
- ### `holocron ci`
383
+ ### `holocron deploy on-release`
280
384
 
281
385
  ```bash
282
- holocron ci [--all] [--filter <pkg>] [--dry-run]
386
+ holocron deploy on-release [--channel <alpha|main>] [--from <commit>] [--to <commit>] [--dry-run]
387
+ ```
388
+
389
+ Deploys every workspace package whose own `holocron.config` declares
390
+ `{ name: "delivery.deploy", with: { on: "release" } }` (holocron#930), when the
391
+ release (`--channel`: its prerelease identifier, or `main`/empty for a stable
392
+ release) is on the task's `channel` (default `main`, the stable release) and changes the package or one of its
393
+ `workspace:*` dependencies between `--from` (the previous release's commit,
394
+ omitted when there is none) and `--to` (default `HEAD`). It waits for npm to
395
+ serve the release's new dependency versions, then runs `pnpm --filter <pkg>
396
+ delivery.deploy`. A package that doesn't apply is skipped; a deploy that
397
+ doesn't succeed exits non-zero. The shared `delivery.publish` workflow runs it as its own
398
+ `deploy` job after the release job (opt in with `deploy-on-release: true`).
399
+
400
+ ### `holocron run ci`
401
+
402
+ ```bash
403
+ holocron run ci [--all] [--filter <pkg>] [--dry-run]
283
404
  ```
284
405
 
285
406
  Runs the merge-gating checks locally, in CI order, exiting non-zero on the
@@ -293,6 +414,46 @@ Order comes from the `CI_ORDER` constant in `@theholocron/astromech`
293
414
  expands into its sub-jobs (each under its own `audit / …` check context)
294
415
  unless the repo ships its own `"audit"` script.
295
416
 
417
+ ### `holocron deploy`
418
+
419
+ `holocron deploy <branch>` (a Git-linked deployment) and `holocron deploy
420
+ --files <dir>` (a directory of build output, no linked repo) both trigger a
421
+ deployment through the configured `deployment` capability, then **wait for
422
+ it to finish**. The command reports success, exit code 0, only when the
423
+ deployment reaches `ready`. A deployment that ends `error` or `cancelled`,
424
+ or is still building after 10 minutes, is a failure: the exit code is
425
+ non-zero and the output includes the provider's own reason
426
+ (`DeploymentRecord.errorMessage`, e.g. Vercel's `Command "npm install"
427
+ exited with 1`). Providers build asynchronously, so accepting a deployment
428
+ isn't the same as it going live (holocron#911).
429
+
430
+ Provider plugins support this through the `Deployment` capability's
431
+ existing `getDeployment(id)`. They should set `errorMessage` on the
432
+ returned `DeploymentRecord` whenever the provider exposes one.
433
+
434
+ ### `holocron monitoring check <url>`
435
+
436
+ Runs every configured `monitoring` check against `<url>` instead of each
437
+ check's own configured `url` — no vendor API call, only a plain HTTP
438
+ request evaluated locally against the exact same `assertions` already in
439
+ `holocron.config.ts`. Built for CI: the `delivery.previewCheck` task runs
440
+ this against a PR's Vercel preview deployment (triggered by
441
+ `deployment_status`, not `push`/`pull_request`), reusing the production
442
+ check definitions to catch a breaking change before merge instead of
443
+ after (holocron#1010).
444
+
445
+ ```ts
446
+ export default defineConfig({
447
+ tasks: ["delivery.previewCheck"],
448
+ providers: {
449
+ monitoring: ["checkly", { accountId: "...", checks: [/* ... */] }],
450
+ },
451
+ });
452
+ ```
453
+
454
+ Exits non-zero if any check fails — the job's own pass/fail is what
455
+ posts as the GitHub check, no separate reporting step needed.
456
+
296
457
  ### Lint parity
297
458
 
298
459
  The `lint` task takes an optional `linters` array — one list that drives
@@ -310,7 +471,7 @@ export default defineConfig({
310
471
 
311
472
  ### Skills installer
312
473
 
313
- `holocron setup` can install shared skills from `@theholocron/skills` into the local repo:
474
+ `holocron repo setup` can install shared skills from `@theholocron/skills` into the local repo:
314
475
 
315
476
  ```ts
316
477
  export default defineConfig({
@@ -371,18 +532,72 @@ export default acmeConfig;
371
532
 
372
533
  ```
373
534
 
535
+ ## Notifications — server as code
536
+
537
+ A `notifications` provider can declare a whole server in `holocron.config.ts`
538
+ (`layout`: categories, channels, roles, access, server settings, welcome screen,
539
+ pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
540
+ commands and the config are provider-neutral; Discord is the first provider.
541
+
542
+ | Command | What it does |
543
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
544
+ | `holocron notifications setup` | Applies the layout; looks everything up by name first, so a re-run changes nothing that matches |
545
+ | `holocron notifications channel add <name>` | Creates one channel (optionally with a webhook whose URL is stored as a secret) |
546
+ | `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) |
547
+ | `holocron notifications link` | Links your account on the provider to your GitHub account by signing in with the provider (OAuth, nothing secret kept) |
548
+ | `holocron notifications sync-roles` | Makes who holds a role match a GitHub team, through the links file (`--keep` only adds; `--provider` picks one) |
549
+ | `holocron doctor notifications [--built-only] [--deliver]` | Step by step: does the server match the layout, do the secrets exist, and does a person (not the bot) own it. A full run also leaves one `🧪 test:` post in the layout's `testChannel`; `--built-only` posts nothing; `--deliver` posts to every channel and removes each post |
550
+
551
+ Channels fed by another service are declared with `feeds` on the channel: `{ name: "uptime", webhook: true, feeds: { monitoring: true } }` (the object form `{ name?, webhook?, avatar? }` overrides the alert channel's name, default `Message to #<channel>`, the dedicated webhook's name, default the provider's, and gives that webhook a picture, a file path or `https://` URL, or `{ url, image }` (the URL is tried first, the file in the repo is the fallback), else the provider's own icon (`Monitoring.icon`, a URL and an embedded `data:` image; Checkly provides one), else the layout's `webhookAvatar`, else the layout's `webhookAvatar`). `setup` gives the channel a dedicated webhook and hands its URL straight to the `monitoring` provider through `Monitoring.ensureAlertChannel({ name, format: "discord", url? })`, which finds an alert channel of that name or creates one and subscribes every check; the URL is never stored as a secret. It needs a `monitoring` provider that implements `ensureAlertChannel` (Checkly does). Two feeds may not share an alert channel name, and a feed's webhook may not share the channel's own webhook name (compared without regard to case).
552
+
553
+ 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. Needs `errors`, `workers` and `dns`; only one channel may be fed.
554
+
555
+ Pinned messages are declared under the provider's `layout` as `pinned: [{ channel, content }]` (`channel` is a channel in the layout, `content` up to 2000 characters); the layout is the whole set of messages the bot has pinned in those channels.
556
+
557
+ Config shape added for role sync and sign-in (all under the provider's `layout`):
558
+
559
+ | Field | Meaning |
560
+ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
561
+ | `testChannel` | The channel (it must declare a webhook) the doctor posts its one self-removing test message to. |
562
+ | `roles[].team` | A GitHub team slug. The role follows that team: given to linked members, taken from linked people who left. Never touches holders nobody has linked. |
563
+ | `links.hostedUrl` | A hosted sign-in service (Sentinel). `link` asks `<hostedUrl>/api/link` and uses it when it answers `{ "service": "link" }`; otherwise it signs in locally. |
564
+ | `links.localPort` | The port of the local sign-in listener (default `53682`, bound to `127.0.0.1` only). |
565
+ | `links.repo` / `links.path` | Where the links file lives (default `<org>/.github-private` and `notifications/<provider>-links.json`). |
566
+ | `application.intents.members` | Switches the Server Members Intent on or off (needed to list who holds a role). |
567
+ | `application.redirectUris` | Redirect URIs that must be registered. Check-only: the API cannot set them, so `setup` and the doctor say what to add in the developer portal. |
568
+
569
+ The links file is `{ "version": 1, "links": [{ "github": "<id>", "login": "<login>", "member": "<id>" }] }`: two public ids per person.
570
+ It is read and written through the `source` capability with the `github.user-sync` token (fine-grained, **only** the
571
+ private config repo, Contents read and write), so no other token needs Contents on other repositories.
572
+
573
+ Capability surface behind it (all optional, so providers without the concept omit them):
574
+
575
+ - `Source.teamMembers(teamSlug, org?)`, `Source.readFile(path, repo?)` (returns the `version` a later write must present),
576
+ `Source.writeFile(path, content, { message, version?, repo? })` (a changed `version` is refused: a real conflict check).
577
+ - `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.
578
+ - `Notifications.roleMembers(role)`, `addRoleMember(role, memberId)`, `removeRoleMember(role, memberId)`.
579
+ - `Notifications.checkDelivery({ channel, name, category?, text })`: posts through a channel's webhook, reads the post back and removes it, and says which step failed.
580
+ - `Notifications.signIn()` returning `{ authorizeUrl, complete }`: the provider-neutral shape of "prove which account you own".
581
+ - `Notifications.ensureApplication` returns `{ updated, todo? }`; each `todo` is a step only a person can do (a portal setting
582
+ the API ignores) and is reported as a failure until done.
583
+
584
+ Provider credentials for Discord: `discord.holonet` is the **bot token** (Bot → Reset Token), `discord.holonet.oauth` is the
585
+ **OAuth client secret** (OAuth2 → Reset Secret). They are different values; the API can create or read neither.
586
+
587
+ See the [command pages](https://theholocron.dev/holocron/commands/notifications-setup/) for each command's options.
588
+
374
589
  ## Upgrading
375
590
 
376
- - **`holocron upgrade node <to>`** — patches every Node.js version pin
591
+ - **`holocron repo upgrade node <to>`** — patches every Node.js version pin
377
592
  (`engines.node`, `.nvmrc`, `.node-version`, `.github/workflows/*`,
378
593
  `Dockerfile`, `.tool-versions`) to a new major.
379
- - **`holocron upgrade deps`** — bumps every `@theholocron/*` pin in
594
+ - **`holocron repo upgrade deps`** — bumps every `@theholocron/*` pin in
380
595
  `pnpm-workspace.yaml` (`catalog:` and every named `catalogs.*`) to its latest
381
596
  published version, then migrates `holocron.config.ts` from the 7.x preset
382
597
  shape (`const { repo, workflows } = node()` + `repo.requiredChecks` +
383
598
  `workflows:`) to the current composed-preset API (`const preset = node()` +
384
599
  `...preset` + `tasks:` + `extraRequiredChecks:`). Mechanical transforms only —
385
- review the result, then `pnpm install && holocron ci`. `--pins-only` skips
600
+ review the result, then `pnpm install && holocron run ci`. `--pins-only` skips
386
601
  the config migration; `--dry-run` prints without writing.
387
602
 
388
603
  ## Auth — fine-grained tokens
@@ -397,11 +612,12 @@ holocron auth set github.issues ghp_xxx # issue management
397
612
  holocron auth set github.sync ghp_xxx # sync-github workflow templates
398
613
  holocron auth set github.release ghp_xxx # semantic-release
399
614
  holocron auth set github.admin ghp_xxx # setup, secrets, environments
615
+ holocron auth set github.user-sync ghp_xxx # the files that link GitHub accounts to other services' members
400
616
  ```
401
617
 
402
618
  The resolution chain per capability is:
403
619
 
404
- ```
620
+ ```text
405
621
  --token flag → HOLOCRON_<FEATURE>_TOKEN env var → keyring("github.<feature>")
406
622
  ```
407
623
 
@@ -418,16 +634,21 @@ holocron auth list # show all stored providers
418
634
  ## Logging
419
635
 
420
636
  Operational output goes through `@theholocron/observability/logger` — separate
421
- from the user-facing `print` surface. Global flags:
637
+ from the user-facing `print` surface. Local/interactive runs are quiet by
638
+ default: no colorized or raw structured console output, regardless of the
639
+ resolved level (Axiom shipping, when configured, is unaffected). CI is
640
+ untouched — its existing stdout output still appears. Global flags:
422
641
 
423
642
  ```sh
424
- holocron doctor --verbose # log level → debug (full structured output)
425
- holocron doctor --quiet # log level → error (suppress info + warn)
643
+ holocron doctor --log debug # show console output at this level (opt back in)
644
+ holocron doctor --verbose # log level → debug, and shows console output
645
+ holocron doctor --quiet # log level → error, and shows console output
426
646
  holocron doctor --debug # print "Run ID: <uuid>" at command end for Axiom lookup
427
647
  ```
428
648
 
429
- Level resolution (highest priority first): `--verbose` / `--quiet` →
430
- `HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` → `"info"`.
649
+ Level resolution (highest priority first): `--log <level>` → `--verbose` /
650
+ `--quiet` → `HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` →
651
+ `"info"`.
431
652
 
432
653
  ```ts
433
654
  export default defineConfig({
@@ -439,7 +660,16 @@ Axiom shipping activates when a token (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`
439
660
  → OS keyring `axiom.<org>` → `axiom`) **and** a dataset
440
661
  (`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` → `log.axiom.dataset` in
441
662
  `holocron.config`) both resolve; env vars win. The token is never read from a
442
- config file. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
663
+ config file.
664
+
665
+ The dataset side of that resolution is **execution-context-aware** (ADR-0012):
666
+ a `global`-context command (`clone`, `new`, `auth set`, `upgrade node`, `plugin
667
+ create`, …) always ships to holocron's own dataset regardless of `$PWD` — it
668
+ isn't "about" any repo, so routing it through whichever repo's `.envrc`
669
+ happens to be active would be wrong. `repo-aware` / `workspace` commands
670
+ (`doctor`, `deploy`, `sync`, …) keep the env-var/config chain above, so a
671
+ per-repo `HOLOCRON_AXIOM_DATASET` — e.g. via a `.envrc` + `direnv` — separates
672
+ each consuming repo's logs. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
443
673
 
444
674
  ### Telemetry
445
675
 
@@ -468,38 +698,69 @@ export default defineConfig({
468
698
 
469
699
  Each SDK sits behind an interface from `@theholocron/observability` —
470
700
  `ErrorSink` (Sentry) / `AnalyticsSink` (PostHog); the adapters, and the only
471
- `@sentry/node` / `posthog-node` imports, live in that package. `telemetry.ts`
701
+ `@sentry/node` / `posthog-node` imports, live in that package. `observability/telemetry.ts`
472
702
  holds the orchestration + the Holocron-specific credential resolution
473
- (`telemetry/resolve.ts`). See the
703
+ (`observability/resolve-telemetry.ts`). See the
474
704
  [telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
475
705
 
706
+ ### ESLint bundle options
707
+
708
+ Most repos need nothing here — `@theholocron/eslint-config`'s `library()`
709
+ bundle resolves with zero committed file (Bucket A: `eslint --config
710
+ <shared path>`, no per-repo `eslint.config.ts` needed). A package with a
711
+ genuine, deliberate exception — e.g. Web Crypto globals a Node-targeted
712
+ package still needs, exempted via `library()`'s own `browserPackages`
713
+ option in that package's own `eslint.config.ts` — should also declare the
714
+ same paths in `holocron.config`'s `eslint.browserPackages`:
715
+
716
+ ```ts
717
+ export default defineConfig({
718
+ eslint: {
719
+ browserPackages: ["packages/github-client/src/app-auth"],
720
+ },
721
+ });
722
+ ```
723
+
724
+ This doesn't replace the package's own `eslint.config.ts` (local/CI linting
725
+ still resolves that file directly) — it's the signal Sentinel's centralized
726
+ static-analysis check (holocron#849/#858) reads instead, since that check
727
+ never reads a PR's own committed config files. Without it, Sentinel flags a
728
+ false-positive `eslint-plugin-n` node-builtins finding on exactly the files
729
+ the local override exists to exempt.
730
+
476
731
  ## What's in here
477
732
 
478
- - `src/capabilities/` — the 14 capability interfaces that providers
479
- implement
733
+ - `src/plugin/capabilities.ts` — the 18 capability interfaces that
734
+ providers implement
480
735
  - `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
481
736
  `CapabilityConfigPackage`
482
737
  - `src/config/load-config.ts` — `loadConfig` — reads `holocron.config.*`
483
738
  (file discovery via [`@theholocron/datapad`](../datapad))
484
739
  - `src/define-config.ts` — `defineConfig` typed pass-through
485
- - `src/logger.ts` — CLI-side `@theholocron/observability/logger` wiring
740
+ - `src/observability/logger.ts` — CLI-side `@theholocron/observability/logger` wiring
486
741
  (`buildCliLogger`, `resolveLogLevel`)
487
742
  - `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
488
743
  capability config packages, builds the capability registry
489
744
  - `src/cli.ts` — yargs entry, dispatches subcommands. `holocron run` / `ci` are
490
745
  delegated to [`@theholocron/astromech`](../astromech) (`createAstromech`).
491
- `holocron sync` / `holocron setup` write each repo's `.github/workflows/*.yml`
492
- thin callers from `astromech.thinCallers()`; `holocron sync-github` pushes the
746
+ `holocron repo sync` / `holocron repo setup` write each repo's `.github/workflows/*.yml`
747
+ thin callers from `astromech.thinCallers()`; `holocron sync github` pushes the
493
748
  reusable `workflow_call` implementations + composite actions from
494
749
  `astromech.reusableTemplates()` to `theholocron/.github` (a pure sync target —
495
750
  never hand-edit its `.github/workflows/*`).
496
- - `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
497
- `secrets sync`, `publish`, `bump-versions`, `sync-github`, `upgrade node`,
498
- `upgrade deps`, `plugin create`, `auth`
499
- - `src/interactive-menu.ts` — the interactive fallback: `COMMAND_REGISTRY`,
500
- `launchMenu` (Layers 1–2, picks + spawns a fresh `holocron <command>`),
501
- `promptForPositionals` (Layer 3, called inline from each leaf command's
502
- `cli.ts` handler)
751
+ - `src/commands/` — `repo setup`, `repo sync`, `doctor`, `deploy`,
752
+ `monitoring check`, `secrets set`, `secrets sync`, `package publish`,
753
+ `package bump-versions`, `sync github`, `repo upgrade node`,
754
+ `repo upgrade deps`, `new plugin`, `auth`, `notifications setup`,
755
+ `notifications channel add`, `notifications link`,
756
+ `notifications sync-roles`, `doctor notifications`
757
+ - `src/interactive-menu/` — the interactive fallback: `command-registry`
758
+ (`COMMAND_REGISTRY`, each entry's `positionals`/`options`), `launch-menu`
759
+ (Layers 1–2, picks + spawns a fresh `holocron <command>`), `child-argv`
760
+ (builds the spawned argv + secret env), `menu-items`, `run-menu-entries`.
761
+ The generic prompting pieces it calls — `promptForPositionals`,
762
+ `promptForOptions` (Layer 3) — live in `src/ui/`, which has no knowledge
763
+ of commands.
503
764
 
504
765
  ## Status
505
766