@theholocron/cli 5.0.0-alpha.11 → 5.0.0-alpha.110

package/README.md

@@ -21,7 +21,7 @@ Run `holocron` with no command, a parent command with no subcommand
 missing a required positional (`holocron deploy`, `holocron secret set`), and
 you get a prompt instead of a `--help` dead end:
 
-```
+```console
 $ holocron
 ? What would you like to do? › dep
 ────────────────────────────────────────────────
@@ -112,6 +112,52 @@ Additional `repo` fields recognised by `holocron setup`:
 | `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.                                                                                                           |
 
+### Custom properties synced to GitHub
+
+`holocron setup` and `holocron 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):
+
+**Manual** — `repo.properties` states these explicitly:
+
+| Property                 | Value                                          |
+| ------------------------ | ---------------------------------------------- |
+| `lifecycle`              | `"active" \| "experimental" \| "deprecated"`   |
+| `open_source`            | `boolean`                                      |
+| `runtime_environment`    | `"node" \| "browser" \| "universal" \| "none"` |
+| `uses_external_packages` | `boolean`                                      |
+
+**Derived** — computed from resolved config + `package.json`, not a config field:
+
+| Property                           | Value                                                                                    |
+| ---------------------------------- | ---------------------------------------------------------------------------------------- |
+| `monorepo`                         | `boolean` — whether `pnpm-workspace.yaml` exists                                         |
+| `holocron_branch_protection_level` | the active `repo.protection` preset                                                      |
+| `holocron_profile`                 | repo archetype: `library` / `cli` / `plugin` / `template` / `app` / `docs` / `platform`  |
+| `holocron_capabilities`            | provider capability keys actually wired in `providers: {}` (`multi_select`)              |
+| `holocron_stack`                   | detected build/framework tooling — `next`, `vite`, `astro`, `tsdown`, … (`multi_select`) |
+| `holocron_compliance`              | `"compliant" \| "non-compliant"` against a minimal `source` + `ci` baseline              |
+
+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
@@ -146,6 +192,26 @@ 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
 an existing repo.
 
+### Default branch (`repo.defaultBranch`)
+
+```ts
+export default defineConfig({
+  repo: { protection: "strict", defaultBranch: "alpha" },
+  providers: { source: "github" },
+});
+```
+
+`holocron 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
@@ -230,6 +296,23 @@ 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 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 ci`
 
 ```bash
@@ -247,6 +330,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
@@ -355,7 +455,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>")
 ```
 
@@ -427,6 +527,31 @@ 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