@theholocron/cli 5.0.0-alpha.13 → 5.0.0-alpha.134

package/README.md

@@ -17,17 +17,25 @@ holocron --help
 ## Interactive mode
 
 Run `holocron` with no command, a parent command with no subcommand
-(`holocron auth`, `holocron skills`, `holocron upgrade`), or a leaf command
-missing a required positional (`holocron deploy`, `holocron secret set`), and
-you get a prompt instead of a `--help` dead end:
-
-```
+(`holocron auth`, `holocron repo`, `holocron repo upgrade`, …), or a leaf command
+missing a required positional (`holocron deploy`, `holocron secrets set`), and
+you get a prompt instead of a `--help` dead end.
+
+The menu mirrors the command tree: each level shows only the next word, and a
+group (marked `›`) opens its own submenu, as deep as the commands nest. Nothing
+is shown as a `<command> <subcommand>` path — `config show` is `config ›` then
+`show`. Every submenu has a `← back` item, and a command that is also a group
+(`repo sync`, `deploy`) has a `(run it)` item at the top of its submenu. Typing
+searches the whole tree — `upgrade` at the top finds the `repo` group — with
+name matches ranked above description matches.
+
+```console
 $ holocron
-? What would you like to do? › dep
-────────────────────────────────────────────────
-❯ deploy   Trigger a deployment via the configured `deployment` capability
-
-? Branch to deploy: › main
+? What would you like to do? › repo
+❯ repo ›
+? repo — choose a subcommand: › upgrade
+? repo upgrade — choose a subcommand: › node
+? Target Node.js major version: › 24
 ```
 
 The picked command spawns as a normal `holocron <command> …` invocation —
@@ -35,15 +43,30 @@ The picked command spawns as a normal `holocron <command> …` invocation —
 through. A non-interactive shell (CI, a script, a pipe) gets the old
 hard-failure message instead of hanging on a prompt.
 
+For a command whose handler honours `--dry-run` (most of them — everything
+except `auth *` and `config show`), the menu always previews it first — a
+dry run doesn't mutate anything, so there's nothing to ask permission for —
+then asks the one real decision:
+
+```console
+...dry-run output...
+? Dry run complete — proceed with the real run? › yes
+```
+
+A preview that reports nothing would actually change (e.g. `clone` finding
+every repo already cloned) skips that question too — there'd be nothing for
+the real run to do either. `--skip-dry-run` opts out of the preview
+entirely, straight to the real run, for when you already know what you want.
+
 ## Execution contexts
 
 Every command is tagged with how much of a repo it needs:
 
-| Context      | Needs                                                    | Examples                                                                                     |
-| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `global`     | just the CLI binary                                      | `version`, `clone`, `new`, `upgrade node`, `auth set` / `check`, `plugin create`, `skills …` |
-| `repo-aware` | `./holocron.config` in cwd, no plugins                   | `run`, `ci`, `config show`, `sync-readme`                                                    |
-| `workspace`  | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `setup`, `sync`, `secrets sync`, `deploy`                                          |
+| Context      | Needs                                                    | Examples                                                                                                                          |
+| ------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `global`     | the CLI binary alone                                     | `version`, `clone`, `new repo` / `plugin`, `repo upgrade …`, `auth set` / `check`, `package …`, `run lint commit-msg`, `skills …` |
+| `repo-aware` | `./holocron.config`, walking up from cwd, no plugins     | `run`, `run ci`, `config show`, `repo sync readme`, `deploy on-release`                                                           |
+| `workspace`  | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `repo setup`, `repo sync`, `secrets …`, `deploy`, `sync github`                                                         |
 
 A `workspace` command run from a bare global install (no plugins next to the
 CLI) fails with one actionable line — install the plugins as devDependencies or
@@ -51,6 +74,21 @@ use `pnpm exec holocron <cmd>`. `auth check` degrades to "token present,
 verification skipped" instead. `holocron --help` prints the grouping; see
 [Execution Contexts](https://theholocron.github.io/holocron/execution-contexts).
 
+### Viewing the resolved config
+
+`holocron config show` prints the resolved config. On a TTY it opens a foldable
+tree by default; piped or redirected, it always emits plain, valid JSON
+(`holocron config show | jq`).
+
+```console
+holocron config show                  # TTY: foldable tree (↑↓ move, →/⏎ expand, ← collapse, E/C all, q quit)
+holocron config show --depth 2        # static coloured tree, anything nested deeper than 2 levels collapsed
+holocron config show --no-interactive # static coloured tree, fully expanded
+```
+
+Passing `--interactive` explicitly needs a TTY on stdin and stdout and fails
+with a one-line message otherwise; the default falls back to static output. It has no extra dependencies — nothing to install.
+
 ## Config file
 
 Holocron reads `holocron.config.{json,js,ts}` from the project root
@@ -103,18 +141,18 @@ A minimal config — for repos with a `package.json` and a GitHub remote
 
 ### repo options
 
-Additional `repo` fields recognised by `holocron setup`:
+Additional `repo` fields recognised by `holocron repo setup`:
 
-| Field             | Type                                    | Description                                                                                                                                                                |
-| ----------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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`. |
-| `repo.topics`     | `string[]`                              | GitHub topics set on the repository.                                                                                                                                       |
-| `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.                           |
-| `repo.properties` | `RepoProperties`                        | Org-level custom property values synced to the GitHub dashboard.                                                                                                           |
+| Field             | Type                                    | Description                                                                                                                                                                     |
+| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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`. |
+| `repo.topics`     | `string[]`                              | GitHub topics set on the repository.                                                                                                                                            |
+| `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.                           |
+| `repo.properties` | `RepoProperties`                        | Org-level custom property values synced to the GitHub dashboard.                                                                                                                |
 
 ### Custom properties synced to GitHub
 
-`holocron setup` and `holocron sync` both call `syncProperties()` with two
+`holocron repo setup` and `holocron repo sync` both call `syncProperties()` with two
 kinds of fields — always one-way (`holocron.config.ts` → resolved →
 properties; properties are never a second editable source of truth):
 
@@ -142,9 +180,25 @@ Field definitions and derivation heuristics:
 `.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
 definitions (#677)".
 
+The four derived fields' pure computation —
+`deriveProfile()`/`deriveStack()`/`deriveCapabilities()`/`deriveCompliance()`
+(plus their `HolocronProfile`/`DeriveProfileInput`/`PackageJsonLike` types)
+— is exported from this package's public entry point, separate from the
+local-filesystem reads (`readWorkspacePackageJsons()`) that gather their
+inputs here. `@theholocron/sentinel`'s `syncPropertiesFromConfig()` reuses
+these functions unchanged, gathering the same inputs over the GitHub API
+instead (D8 — one derivation, two input sources, not two
+implementations).
+
+`missingCapabilities(capabilities)` is `deriveCompliance()`'s sibling —
+same `REQUIRED_BASELINE` table, but returns _which_ required capabilities
+are absent rather than whether any are. `@theholocron/sentinel`'s
+`postCheckRun()` uses it to name what's missing on the check run it
+posts, instead of reporting pass/fail.
+
 ### Required status checks (`protection: "strict"`)
 
-`holocron setup` builds the branch-protection required-check list from the
+`holocron repo setup` builds the branch-protection required-check list from the
 manifest, not a hand-maintained array:
 
 - `"DCO"` (hard-prepended), then
@@ -170,12 +224,32 @@ The generated ruleset also sets `require_extra_approval_for_unattributed_changes
 false` — with `required_approving_review_count: 0` and a single maintainer, the
 GitHub default (`true`) is an unsatisfiable block on any PR with an
 unverified/unattributed commit. Repository-admin bypass still covers the real
-risk. And the `codecov.yml` `holocron setup` writes carries `if_not_found:
+risk. And the `codecov.yml` `holocron repo setup` writes carries `if_not_found:
 success` on every status default, so an infra-only PR (dep bump, config,
 lockfile — no coverable change) passes instead of hanging on a `codecov/*`
-required check that never posts. A re-run of `holocron setup` backfills both into
+required check that never posts. A re-run of `holocron repo setup` backfills both into
 an existing repo.
 
+### Default branch (`repo.defaultBranch`)
+
+```ts
+export default defineConfig({
+  repo: { protection: "strict", defaultBranch: "alpha" },
+  providers: { source: "github" },
+});
+```
+
+`holocron repo setup` syncs GitHub's repo-level default branch (`HEAD`) — what a
+fresh clone checks out, what `gh pr create`/the compare UI target by default,
+and what Sentinel's `validateConfig()` reads (it only ever reads config from
+the repo's default branch, never a PR ref — a deliberate security boundary).
+Omit this field to leave GitHub's current setting untouched; most repos never
+need it. It exists for a repo using a `main`/`alpha` prerelease-channel split
+where active development happens on a non-`main` branch: set this to that
+branch so Sentinel validates against what's actually being developed, then
+change it back once that branch merges to `main` for a stable cut and stops
+being the active branch.
+
 ### Git hooks
 
 ```ts
@@ -186,7 +260,7 @@ export default defineConfig({
 });
 ```
 
-`holocron setup` writes `.husky/pre-push` (runs `holocron ci` before every
+`holocron repo setup` writes `.husky/pre-push` (runs `holocron run ci` before every
 push) and `.husky/pre-commit` (runs `gitleaks protect --staged` + `lint-staged`
 before every commit — scoped to staged changes, not the whole history, so a
 past false positive can't permanently block future commits) and sets
@@ -197,7 +271,7 @@ setup --hooks` / `--no-hooks` override per run. Bypass one push with `git push
 
 ### Task scripts
 
-`holocron sync` reconciles `package.json#scripts` from the `tasks` manifest
+`holocron repo sync` reconciles `package.json#scripts` from the `tasks` manifest
 (merge, never clobber — only the managed keys are touched):
 
 ```ts
@@ -232,8 +306,8 @@ export default defineConfig({
 `@theholocron/astromech`'s `loadTasksConfig` merges it over
 `holocron.config`'s `tasks` — **task arrays concatenate**
 (`holocron.config` first), the dedicated file **wins on scalars**,
-`extraRequiredChecks` concatenate. `holocron run` / `holocron ci` /
-`holocron setup` / `holocron sync` all read the merged result, so the
+`extraRequiredChecks` concatenate. `holocron run` / `holocron run ci` /
+`holocron repo setup` / `holocron repo sync` all read the merged result, so the
 split is transparent. Useful for keeping the capability/provider config
 and the "what this repo runs" manifest in separate files (this repo does).
 
@@ -260,10 +334,27 @@ job execute the same thing — at a turbo root both are
 `turbo run test -- --coverage` (the registry's org-default flags flow through
 turbo's `--`).
 
-### `holocron ci`
+### `holocron deploy on-release`
+
+```bash
+holocron deploy on-release [--channel <alpha|main>] [--from <commit>] [--to <commit>] [--dry-run]
+```
+
+Deploys every workspace package whose own `holocron.config` declares
+`{ name: "delivery.deploy", with: { on: "release" } }` (holocron#930), when the
+release (`--channel`: its prerelease identifier, or `main`/empty for a stable
+release) is on the task's `channel` (default `main`, the stable release) and changes the package or one of its
+`workspace:*` dependencies between `--from` (the previous release's commit,
+omitted when there is none) and `--to` (default `HEAD`). It waits for npm to
+serve the release's new dependency versions, then runs `pnpm --filter <pkg>
+delivery.deploy`. A package that doesn't apply is skipped; a failed deploy
+exits non-zero. The shared `delivery.publish` workflow runs it as its own
+`deploy` job after the release job (opt in with `deploy-on-release: true`).
+
+### `holocron run ci`
 
 ```bash
-holocron ci [--all] [--filter <pkg>] [--dry-run]
+holocron run ci [--all] [--filter <pkg>] [--dry-run]
 ```
 
 Runs the merge-gating checks locally, in CI order, exiting non-zero on the
@@ -277,6 +368,23 @@ Order comes from the `CI_ORDER` constant in `@theholocron/astromech`
 expands into its sub-jobs (each under its own `audit / …` check context)
 unless the repo ships its own `"audit"` script.
 
+### `holocron deploy`
+
+`holocron deploy <branch>` (a Git-linked deployment) and `holocron deploy
+--files <dir>` (a directory of build output, no linked repo) both trigger a
+deployment through the configured `deployment` capability, then **wait for
+it to finish**. The command reports success, exit code 0, only when the
+deployment reaches `ready`. A deployment that ends `error` or `cancelled`,
+or is still building after 10 minutes, is a failure: the exit code is
+non-zero and the output includes the provider's own reason
+(`DeploymentRecord.errorMessage`, e.g. Vercel's `Command "npm install"
+exited with 1`). Providers build asynchronously, so accepting a deployment
+isn't the same as it going live (holocron#911).
+
+Provider plugins support this through the `Deployment` capability's
+existing `getDeployment(id)`. They should set `errorMessage` on the
+returned `DeploymentRecord` whenever the provider exposes one.
+
 ### Lint parity
 
 The `lint` task takes an optional `linters` array — one list that drives
@@ -294,7 +402,7 @@ export default defineConfig({
 
 ### Skills installer
 
-`holocron setup` can install shared skills from `@theholocron/skills` into the local repo:
+`holocron repo setup` can install shared skills from `@theholocron/skills` into the local repo:
 
 ```ts
 export default defineConfig({
@@ -357,16 +465,16 @@ export default acmeConfig;
 
 ## Upgrading
 
-- **`holocron upgrade node <to>`** — patches every Node.js version pin
+- **`holocron repo upgrade node <to>`** — patches every Node.js version pin
   (`engines.node`, `.nvmrc`, `.node-version`, `.github/workflows/*`,
   `Dockerfile`, `.tool-versions`) to a new major.
-- **`holocron upgrade deps`** — bumps every `@theholocron/*` pin in
+- **`holocron repo upgrade deps`** — bumps every `@theholocron/*` pin in
   `pnpm-workspace.yaml` (`catalog:` and every named `catalogs.*`) to its latest
   published version, then migrates `holocron.config.ts` from the 7.x preset
   shape (`const { repo, workflows } = node()` + `repo.requiredChecks` +
   `workflows:`) to the current composed-preset API (`const preset = node()` +
   `...preset` + `tasks:` + `extraRequiredChecks:`). Mechanical transforms only —
-  review the result, then `pnpm install && holocron ci`. `--pins-only` skips
+  review the result, then `pnpm install && holocron run ci`. `--pins-only` skips
   the config migration; `--dry-run` prints without writing.
 
 ## Auth — fine-grained tokens
@@ -385,7 +493,7 @@ holocron auth set github.admin    ghp_xxx  # setup, secrets, environments
 
 The resolution chain per capability is:
 
-```
+```text
 --token flag → HOLOCRON_<FEATURE>_TOKEN env var → keyring("github.<feature>")
 ```
 
@@ -402,16 +510,21 @@ holocron auth list                # show all stored providers
 ## Logging
 
 Operational output goes through `@theholocron/observability/logger` — separate
-from the user-facing `print` surface. Global flags:
+from the user-facing `print` surface. Local/interactive runs are quiet by
+default: no colorized or raw structured console output, regardless of the
+resolved level (Axiom shipping, when configured, is unaffected). CI is
+untouched — its existing stdout output still appears. Global flags:
 
 ```sh
-holocron doctor --verbose   # log level → debug (full structured output)
-holocron doctor --quiet     # log level → error (suppress info + warn)
+holocron doctor --log debug # show console output at this level (opt back in)
+holocron doctor --verbose   # log level → debug, and shows console output
+holocron doctor --quiet     # log level → error, and shows console output
 holocron doctor --debug     # print "Run ID: <uuid>" at command end for Axiom lookup
 ```
 
-Level resolution (highest priority first): `--verbose` / `--quiet` →
-`HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` → `"info"`.
+Level resolution (highest priority first): `--log <level>` → `--verbose` /
+`--quiet` → `HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` →
+`"info"`.
 
 ```ts
 export default defineConfig({
@@ -423,7 +536,16 @@ Axiom shipping activates when a token (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`
 → OS keyring `axiom.<org>` → `axiom`) **and** a dataset
 (`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` → `log.axiom.dataset` in
 `holocron.config`) both resolve; env vars win. The token is never read from a
-config file. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
+config file.
+
+The dataset side of that resolution is **execution-context-aware** (ADR-0012):
+a `global`-context command (`clone`, `new`, `auth set`, `upgrade node`, `plugin
+create`, …) always ships to holocron's own dataset regardless of `$PWD` — it
+isn't "about" any repo, so routing it through whichever repo's `.envrc`
+happens to be active would be wrong. `repo-aware` / `workspace` commands
+(`doctor`, `deploy`, `sync`, …) keep the env-var/config chain above, so a
+per-repo `HOLOCRON_AXIOM_DATASET` — e.g. via a `.envrc` + `direnv` — separates
+each consuming repo's logs. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
 
 ### Telemetry
 
@@ -457,10 +579,35 @@ holds the orchestration + the Holocron-specific credential resolution
 (`telemetry/resolve.ts`). See the
 [telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
 
+### ESLint bundle options
+
+Most repos need nothing here — `@theholocron/eslint-config`'s `library()`
+bundle resolves with zero committed file (Bucket A: `eslint --config
+<shared path>`, no per-repo `eslint.config.ts` needed). A package with a
+genuine, deliberate exception — e.g. Web Crypto globals a Node-targeted
+package still needs, exempted via `library()`'s own `browserPackages`
+option in that package's own `eslint.config.ts` — should also declare the
+same paths in `holocron.config`'s `eslint.browserPackages`:
+
+```ts
+export default defineConfig({
+  eslint: {
+    browserPackages: ["packages/github-client/src/app-auth"],
+  },
+});
+```
+
+This doesn't replace the package's own `eslint.config.ts` (local/CI linting
+still resolves that file directly) — it's the signal Sentinel's centralized
+static-analysis check (holocron#849/#858) reads instead, since that check
+never reads a PR's own committed config files. Without it, Sentinel flags a
+false-positive `eslint-plugin-n` node-builtins finding on exactly the files
+the local override exists to exempt.
+
 ## What's in here
 
-- `src/capabilities/` — the 14 capability interfaces that providers
-  implement
+- `src/plugin/capabilities.ts` — the 18 capability interfaces that
+  providers implement
 - `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
   `CapabilityConfigPackage`
 - `src/config/load-config.ts` — `loadConfig` — reads `holocron.config.*`
@@ -472,14 +619,14 @@ holds the orchestration + the Holocron-specific credential resolution
   capability config packages, builds the capability registry
 - `src/cli.ts` — yargs entry, dispatches subcommands. `holocron run` / `ci` are
   delegated to [`@theholocron/astromech`](../astromech) (`createAstromech`).
-  `holocron sync` / `holocron setup` write each repo's `.github/workflows/*.yml`
-  thin callers from `astromech.thinCallers()`; `holocron sync-github` pushes the
+  `holocron repo sync` / `holocron repo setup` write each repo's `.github/workflows/*.yml`
+  thin callers from `astromech.thinCallers()`; `holocron sync github` pushes the
   reusable `workflow_call` implementations + composite actions from
   `astromech.reusableTemplates()` to `theholocron/.github` (a pure sync target —
   never hand-edit its `.github/workflows/*`).
-- `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
-  `secrets sync`, `publish`, `bump-versions`, `sync-github`, `upgrade node`,
-  `upgrade deps`, `plugin create`, `auth`
+- `src/commands/` — `repo setup`, `repo sync`, `doctor`, `deploy`, `secrets set`,
+  `secrets sync`, `package publish`, `package bump-versions`, `sync github`,
+  `repo upgrade node`, `repo upgrade deps`, `new plugin`, `auth`
 - `src/interactive-menu.ts` — the interactive fallback: `COMMAND_REGISTRY`,
   `launchMenu` (Layers 1–2, picks + spawns a fresh `holocron <command>`),
   `promptForPositionals` (Layer 3, called inline from each leaf command's