@theholocron/cli 5.0.0-alpha.45 → 5.0.0-alpha.451
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 +566 -106
- package/dist/cli.mjs +27687 -8357
- package/dist/cli.mjs.map +1 -1
- package/dist/config-system-CAYb1d4M.mjs +814 -0
- package/dist/index-DMoGsKv2.d.mts +4263 -0
- package/dist/index.d.mts +479 -632
- package/dist/index.mjs +577 -348
- package/dist/plugin/capabilities.d.mts +2 -807
- package/dist/plugin/capabilities.mjs +59 -4
- package/dist/presets.d.mts +221 -0
- package/dist/presets.mjs +439 -0
- package/package.json +49 -36
package/README.md
CHANGED
|
@@ -17,39 +17,122 @@ holocron --help
|
|
|
17
17
|
## Interactive mode
|
|
18
18
|
|
|
19
19
|
Run `holocron` with no command, a parent command with no subcommand
|
|
20
|
-
(`holocron
|
|
21
|
-
missing a required positional (`holocron deploy`, `holocron secret
|
|
22
|
-
you get a prompt instead of a `--help` dead end
|
|
20
|
+
(`holocron check`, `holocron repo`, `holocron upgrade`, …), or a leaf command
|
|
21
|
+
missing a required positional (`holocron deploy`, `holocron new secret`), 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 — `show config` is `show ›` then
|
|
27
|
+
`config`. Every submenu has a `← back` item, and a command that is also a group
|
|
28
|
+
(`sync`, `deploy`) has a `(run it)` item at the top of its submenu. Typing
|
|
29
|
+
searches the whole tree, 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
|
+
? upgrade — choose a subcommand: › node
|
|
38
|
+
? Target Node.js major version: › 24
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
For a command that declares options (so far: `publish package` — 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:
|
|
23
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
|
-
|
|
51
|
+
`publish package` 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. `publish package`'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 the token commands and `show config`), 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` |
|
|
45
|
-
| `repo-aware` | `./holocron.config
|
|
46
|
-
| `workspace` | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `setup`, `sync`, `
|
|
110
|
+
| Context | Needs | Examples |
|
|
111
|
+
| ------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
112
|
+
| `global` | the CLI binary alone | `version`, `clone`, `new repo` / `plugin` / `token` / `github-app`, `upgrade …`, `check token` / `resolved`, `remove token` / `skill`, `list tokens` / `skills`, `publish …`, `install skills`, `update skills`, `run lint commit-msg` |
|
|
113
|
+
| `repo-aware` | `./holocron.config`, walking up from cwd, no plugins | `run`, `run ci`, `show config`, `sync readme`, `deploy on-release` |
|
|
114
|
+
| `workspace` | the `@theholocron/holocron-plugin-*` packages resolvable | `doctor`, `setup`, `sync`, `cleanup branches`, `sync secrets`, `deploy`, `sync github`, `sync issues`, `sync ideas`, `sync tooling`, `export requests` |
|
|
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
|
|
50
|
-
use `pnpm exec holocron <cmd>`. `
|
|
118
|
+
use `pnpm exec holocron <cmd>`. `check token` degrades to "token present,
|
|
51
119
|
verification skipped" instead. `holocron --help` prints the grouping; see
|
|
52
|
-
[Execution Contexts](https://theholocron.
|
|
120
|
+
[Execution Contexts](https://docs.theholocron.dev/holocron/execution-contexts).
|
|
121
|
+
|
|
122
|
+
### Viewing the resolved config
|
|
123
|
+
|
|
124
|
+
`holocron show config` 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 show config | jq`).
|
|
127
|
+
|
|
128
|
+
```console
|
|
129
|
+
holocron show config # TTY: foldable tree (↑↓ move, →/⏎ expand, ← collapse, E/C all, q quit)
|
|
130
|
+
holocron show config --depth 2 # static coloured tree, anything nested deeper than 2 levels collapsed
|
|
131
|
+
holocron show config --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.
|
|
53
136
|
|
|
54
137
|
## Config file
|
|
55
138
|
|
|
@@ -101,16 +184,88 @@ in at load time:
|
|
|
101
184
|
A minimal config — for repos with a `package.json` and a GitHub remote
|
|
102
185
|
— only needs `providers`:
|
|
103
186
|
|
|
187
|
+
### The `.holocron/` directory
|
|
188
|
+
|
|
189
|
+
A big declaration can live in a file next to the config instead of inline, so `holocron.config.ts` stays a short index
|
|
190
|
+
of choices. `.holocron/<area>.{ts,js,mjs,cjs,json}` is read by name, and the areas are a closed list (a file not on
|
|
191
|
+
the list is never read):
|
|
192
|
+
|
|
193
|
+
| File | Where it lands |
|
|
194
|
+
| --------------------------- | ---------------------------------------------------------------------------------- |
|
|
195
|
+
| `.holocron/notifications.*` | the `layout` option of the `providers.notifications` entry (which keeps `guildId`) |
|
|
196
|
+
| `.holocron/repo.*` | keys of `repo` (`defaultBranch` stays inline: Sentinel needs it first) |
|
|
197
|
+
| `.holocron/org.*` | provider options the config leaves out (`teamId`, `accountId`), see below |
|
|
198
|
+
|
|
199
|
+
The file's default export is the value (`.ts` keeps its comments; `.json` needs no `import`, for repos with no
|
|
200
|
+
`package.json`). If both exist for one area, `.ts` wins over `.json`. A missing directory changes nothing. Setting the
|
|
201
|
+
same thing inline and in a file is an error that names both (`the notifications layout is set in providers.notifications
|
|
202
|
+
and in .holocron/notifications.ts`, `repo.topics is set in the config and in .holocron/repo.json`): there is no merge and
|
|
203
|
+
no precedence. An area file may `import` a sibling in `.holocron/`. Never put a secret in the directory: it is public in
|
|
204
|
+
a public repo.
|
|
205
|
+
|
|
206
|
+
To type the layout, import the type and use `satisfies` (there is no `defineLayout()` helper; the type-only import keeps
|
|
207
|
+
runtime code out of a file Sentinel evaluates from the default branch):
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
import type { NotificationsLayout } from "@theholocron/cli";
|
|
211
|
+
|
|
212
|
+
export default {
|
|
213
|
+
// comments stay
|
|
214
|
+
testChannel: "holonet",
|
|
215
|
+
} satisfies NotificationsLayout;
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
This repo's own Discord layout lives in `.holocron/notifications.ts`; `holocron.config.ts` keeps only `guildId`.
|
|
219
|
+
|
|
220
|
+
`RULES.md` and the webhook avatar live in `.holocron/` too (`.holocron/pinned/rules.md`, `.holocron/media/webhook-avatar.png`),
|
|
221
|
+
but they are not areas: the layout names them with an explicit repo-relative path (`pinned: [{ channel, file }]`,
|
|
222
|
+
`webhookAvatar`). `.holocron/projects/<name>.json` is the project-board template folder (SPEC-0020), read by its own
|
|
223
|
+
default and not placed into the config.
|
|
224
|
+
|
|
225
|
+
**Sentinel** reads the directory too, so its PR config check, property sync and role sync see the same merged config as
|
|
226
|
+
the CLI. It lists `.holocron/` at the config's ref and fetches the whole tree (any depth, so an area may import a
|
|
227
|
+
sibling), within caps: 50 files, 100 KB per file, 512 KB in all. Past a cap, or on an area file that does not load,
|
|
228
|
+
the check reports a load error. Only what the config or an area file imports is evaluated. The design and the decisions
|
|
229
|
+
are in `docs/wiki/specifications/tech-holocron-directory.spec.md` (SPEC-0069).
|
|
230
|
+
|
|
231
|
+
**Keys that never move out of `holocron.config.ts`.** `repo.defaultBranch`, because the config is the one file read
|
|
232
|
+
before the directory, and the default branch is what says which branch holds `.holocron/` and the config. Every other
|
|
233
|
+
top-level key (`name`, `org`, `domain`, `providers`, `tasks`) also stays, but only because the closed list of areas has
|
|
234
|
+
no entry for it: Sentinel's `validateConfig()` reads none of them before it fetches `.holocron/` (it needs the config
|
|
235
|
+
file's path and the `ref`, nothing from inside it). Keys that a preset spreads into `repo` (`protection`, `properties`,
|
|
236
|
+
which `syncPropertiesFromConfig()` reads) stay inline too, since a key set both inline and in the file is an error. There
|
|
237
|
+
is no per-key precedence: the loader does not let an inline key win, it refuses the duplicate and names both places. This
|
|
238
|
+
repo's `.holocron/repo.ts` holds `teams`, `topics`, `variables` and `secrets`, names and identifiers only, typed with
|
|
239
|
+
`satisfies RepoConfig` (a type-only import).
|
|
240
|
+
|
|
241
|
+
**The `org` area** (#1820). The organization's constants that are provider options and that CI does not need:
|
|
242
|
+
`.holocron/org.ts` is `{ domain, cloudflare: { accountId }, vercel: { teamId }, checkly: { accountId }, sentry: { org } }` (typed with
|
|
243
|
+
`satisfies OrgConfig`). `domain` is the org's DNS zone: the loader sets `domain` on a config that leaves it out (set in
|
|
244
|
+
both is an error), and a file that builds a hostname while it is evaluated imports it (`import org from "./org.js"`). The loader fills each of these into every provider entry of that name that leaves the option
|
|
245
|
+
out, so the config can say `deployment: ["vercel", { domain }]`, `monitoring: "checkly"` and `errors: "sentry"`. The same option set inline
|
|
246
|
+
and in the file is an error that names both (`vercel.teamId is set in providers.deployment and in
|
|
247
|
+
.holocron/org.ts`), with no merge and no precedence. A provider key or an option the area does not know is an error; a
|
|
248
|
+
provider the config does not use is ignored. The org area is shared: a config in a subdirectory (`apps/sentinel`)
|
|
249
|
+
also reads the repository root's `.holocron/org.ts` (the nearest ancestor with a `.git`), and its own
|
|
250
|
+
`.holocron/org.ts` wins for a key set in both, option by option; that is not an error, so an identifier written in the
|
|
251
|
+
root file needs no copy in the app. The other areas (`repo`, `notifications`) describe the repository and are not
|
|
252
|
+
shared. Anything CI needs (`HOLOCRON_CLOUDFLARE_ACCOUNT_ID`,
|
|
253
|
+
`HOLOCRON_TURBO_TEAM`, `HOLOCRON_AXIOM_DATASET`) stays out: it lives in 1Password and syncs to a GitHub variable (`repo.variables.sync`),
|
|
254
|
+
and nothing else carries a copy. `.holocron/org.md` (the agent contract the CLI embeds) is not an area: only
|
|
255
|
+
`.ts`, `.js`, `.mjs`, `.cjs` and `.json` are read.
|
|
256
|
+
|
|
104
257
|
### repo options
|
|
105
258
|
|
|
106
259
|
Additional `repo` fields recognised by `holocron setup`:
|
|
107
260
|
|
|
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.
|
|
261
|
+
| Field | Type | Description |
|
|
262
|
+
| ----------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
263
|
+
| `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`. |
|
|
264
|
+
| `repo.topics` | `string[]` | GitHub topics set on the repository. |
|
|
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
|
+
| `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 secrets` expects the names). A name given as a literal and in `sync`, or `prune` with `sync`, is a config error. |
|
|
268
|
+
| `repo.secrets` | `{ repo?, org?, environments?, sync? }` | Names of the secrets that must exist, checked (never written) by `holocron doctor secrets`. Names only. The notification layout's secrets and a Chromatic project token are expected without being listed. `sync: [{ environment, keys?, scope?, repos? }]` declares the vault environments `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. |
|
|
114
269
|
|
|
115
270
|
### Custom properties synced to GitHub
|
|
116
271
|
|
|
@@ -139,7 +294,7 @@ properties; properties are never a second editable source of truth):
|
|
|
139
294
|
| `holocron_compliance` | `"compliant" \| "non-compliant"` against a minimal `source` + `ci` baseline |
|
|
140
295
|
|
|
141
296
|
Field definitions and derivation heuristics:
|
|
142
|
-
|
|
297
|
+
`docs/wiki/specifications/tech-holocron-platform.spec.md` → "Custom-properties sync — field
|
|
143
298
|
definitions (#677)".
|
|
144
299
|
|
|
145
300
|
The four derived fields' pure computation —
|
|
@@ -152,6 +307,10 @@ these functions unchanged, gathering the same inputs over the GitHub API
|
|
|
152
307
|
instead (D8 — one derivation, two input sources, not two
|
|
153
308
|
implementations).
|
|
154
309
|
|
|
310
|
+
A provider's `Errors.describe()` returns `envKeys` (always pushed to repo secrets by `holocron setup`) and an optional
|
|
311
|
+
`frameworkEnvKeys` (`{ next: ["NEXT_PUBLIC_SENTRY_DSN"] }`), keyed by a `StackName` from `deriveStack()` and pushed only when
|
|
312
|
+
the root or a workspace package depends on that framework.
|
|
313
|
+
|
|
155
314
|
`missingCapabilities(capabilities)` is `deriveCompliance()`'s sibling —
|
|
156
315
|
same `REQUIRED_BASELINE` table, but returns _which_ required capabilities
|
|
157
316
|
are absent rather than whether any are. `@theholocron/sentinel`'s
|
|
@@ -163,17 +322,24 @@ posts, instead of reporting pass/fail.
|
|
|
163
322
|
`holocron setup` builds the branch-protection required-check list from the
|
|
164
323
|
manifest, not a hand-maintained array:
|
|
165
324
|
|
|
166
|
-
|
|
325
|
+
In the repo that holds the reusable workflows (holocron itself) the list is `ci / Required checks` and `DCO`. That is the aggregate
|
|
326
|
+
check (`ci/workflows/ci.yml`, written by `setup` / `sync` as `.github/workflows/ci.ci.yml`): it waits on
|
|
327
|
+
every `{ required: true }` task, the hand-written checks in `extraRequiredChecks` and its `codecov/*` statuses, and its
|
|
328
|
+
job summary lists each of them with a link, failing ones first. `DCO` stays its own required context. In any other
|
|
329
|
+
repo, which has no `ci` caller yet, the list is:
|
|
330
|
+
|
|
331
|
+
- `"DCO"`, then
|
|
167
332
|
- every `{ required: true }` task's workflow check context (`Lint / Conclusion`,
|
|
168
|
-
`Test / Conclusion`, `Typecheck / Conclusion
|
|
333
|
+
`Test / Conclusion`, `Typecheck / Conclusion` while the repo is on the frozen reusables; `test:unit / Conclusion`,
|
|
334
|
+
`typecheck / Run tsc --noEmit`, … once it moves to the flat ones), walked
|
|
169
335
|
in CI order, then
|
|
170
336
|
- the top-level `extraRequiredChecks` (codecov gates, a bundle-build check, …).
|
|
171
337
|
|
|
172
338
|
```ts
|
|
173
339
|
export default defineConfig({
|
|
174
340
|
tasks: [
|
|
175
|
-
{ name: "lint", required: true },
|
|
176
|
-
{ name: "test", required: true },
|
|
341
|
+
{ name: "lint:code", required: true },
|
|
342
|
+
{ name: "test:unit", required: true },
|
|
177
343
|
{ name: "typecheck", required: true },
|
|
178
344
|
],
|
|
179
345
|
extraRequiredChecks: ["codecov/patch", "codecov/project"],
|
|
@@ -189,8 +355,42 @@ unverified/unattributed commit. Repository-admin bypass still covers the real
|
|
|
189
355
|
risk. And the `codecov.yml` `holocron setup` writes carries `if_not_found:
|
|
190
356
|
success` on every status default, so an infra-only PR (dep bump, config,
|
|
191
357
|
lockfile — no coverable change) passes instead of hanging on a `codecov/*`
|
|
192
|
-
required check that never posts.
|
|
193
|
-
an
|
|
358
|
+
required check that never posts. It also ignores `**/*.mdx`, so a docs-only PR that
|
|
359
|
+
adds pages is not judged to change testable files and left with an empty upload.
|
|
360
|
+
A re-run of `holocron setup` backfills all of these into an existing repo.
|
|
361
|
+
|
|
362
|
+
### Default branch (`repo.defaultBranch`)
|
|
363
|
+
|
|
364
|
+
```ts
|
|
365
|
+
export default defineConfig({
|
|
366
|
+
repo: { protection: "strict", defaultBranch: "alpha" },
|
|
367
|
+
providers: { source: "github" },
|
|
368
|
+
});
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
`holocron setup` syncs GitHub's repo-level default branch (`HEAD`) — what a
|
|
372
|
+
fresh clone checks out, what `gh pr create`/the compare UI target by default,
|
|
373
|
+
and what Sentinel's `validateConfig()` reads (it only ever reads config from
|
|
374
|
+
the repo's default branch, never a PR ref — a deliberate security boundary).
|
|
375
|
+
Omit this field to leave GitHub's current setting untouched; most repos never
|
|
376
|
+
need it. It exists for a repo using a `main`/`alpha` prerelease-channel split
|
|
377
|
+
where active development happens on a non-`main` branch: set this to that
|
|
378
|
+
branch so Sentinel validates against what's actually being developed, then
|
|
379
|
+
change it back once that branch merges to `main` for a stable cut and stops
|
|
380
|
+
being the active branch.
|
|
381
|
+
|
|
382
|
+
### Doc-comment coverage
|
|
383
|
+
|
|
384
|
+
```ts
|
|
385
|
+
export default defineConfig({
|
|
386
|
+
repoValidation: { docsCoverage: "required" }, // "off" (default) | "warn" | "required"
|
|
387
|
+
});
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Controls `holocron probe docs patch` (skipped, reports without failing, or fails for an export a PR adds or changes
|
|
391
|
+
without a doc comment) and whether `holocron setup` adds the `documentation` flag and its statuses to
|
|
392
|
+
`codecov.yml`, informational for `"warn"`. It never touches the required checks. See the
|
|
393
|
+
[config docs](https://docs.theholocron.dev/holocron/config/#doc-comment-coverage).
|
|
194
394
|
|
|
195
395
|
### Git hooks
|
|
196
396
|
|
|
@@ -202,7 +402,7 @@ export default defineConfig({
|
|
|
202
402
|
});
|
|
203
403
|
```
|
|
204
404
|
|
|
205
|
-
`holocron setup` writes `.husky/pre-push` (runs `holocron ci` before every
|
|
405
|
+
`holocron setup` writes `.husky/pre-push` (runs `holocron run ci` before every
|
|
206
406
|
push) and `.husky/pre-commit` (runs `gitleaks protect --staged` + `lint-staged`
|
|
207
407
|
before every commit — scoped to staged changes, not the whole history, so a
|
|
208
408
|
past false positive can't permanently block future commits) and sets
|
|
@@ -218,15 +418,17 @@ setup --hooks` / `--no-hooks` override per run. Bypass one push with `git push
|
|
|
218
418
|
|
|
219
419
|
```ts
|
|
220
420
|
export default defineConfig({
|
|
221
|
-
tasks: ["test", "lint", "typecheck"],
|
|
421
|
+
tasks: ["test:unit", "lint:code", "typecheck"],
|
|
222
422
|
// syncScripts: false, // disable the step
|
|
223
|
-
// holocronScript: "node
|
|
423
|
+
// holocronScript: "node cli/cli/dist/cli.mjs", // override the "holocron" entry
|
|
224
424
|
providers: { source: "github" },
|
|
225
425
|
});
|
|
226
426
|
```
|
|
227
427
|
|
|
228
|
-
Writes `"holocron": "<holocronScript ?? 'holocron'>"` plus one
|
|
229
|
-
`
|
|
428
|
+
Writes `"holocron": "<holocronScript ?? 'holocron'>"` plus one script per runnable task, named by the task id
|
|
429
|
+
(`test:unit`) and one per suite (`test`, `lint`, `scan`): `turbo run <task>` in a pnpm workspace with a `turbo.json`
|
|
430
|
+
(or the tool's own command for a task that runs once at the root), `holocron run <task> --` in a single package.
|
|
431
|
+
`holocron probe generated check` fails on a root script that differs from what is generated. `syncScripts: false`
|
|
230
432
|
opts out entirely.
|
|
231
433
|
|
|
232
434
|
### Splitting the task manifest — `astromech.config.ts`
|
|
@@ -240,7 +442,7 @@ The `tasks` key (plus `syncScripts` / `holocronScript` / `hooks` /
|
|
|
240
442
|
import { defineConfig } from "@theholocron/astromech/config";
|
|
241
443
|
|
|
242
444
|
export default defineConfig({
|
|
243
|
-
tasks: [{ name: "
|
|
445
|
+
tasks: [{ name: "lint:unused", required: true }, "publish-wiki"],
|
|
244
446
|
syncScripts: false,
|
|
245
447
|
});
|
|
246
448
|
```
|
|
@@ -248,7 +450,7 @@ export default defineConfig({
|
|
|
248
450
|
`@theholocron/astromech`'s `loadTasksConfig` merges it over
|
|
249
451
|
`holocron.config`'s `tasks` — **task arrays concatenate**
|
|
250
452
|
(`holocron.config` first), the dedicated file **wins on scalars**,
|
|
251
|
-
`extraRequiredChecks` concatenate. `holocron run` / `holocron ci` /
|
|
453
|
+
`extraRequiredChecks` concatenate. `holocron run` / `holocron run ci` /
|
|
252
454
|
`holocron setup` / `holocron sync` all read the merged result, so the
|
|
253
455
|
split is transparent. Useful for keeping the capability/provider config
|
|
254
456
|
and the "what this repo runs" manifest in separate files (this repo does).
|
|
@@ -256,30 +458,48 @@ and the "what this repo runs" manifest in separate files (this repo does).
|
|
|
256
458
|
### `holocron run`
|
|
257
459
|
|
|
258
460
|
```bash
|
|
259
|
-
holocron run <task> [job] [--required] [--filter <pkg>] [--dry-run] [-- <passthrough>]
|
|
461
|
+
holocron run <task | suite> [qualifier | job] [--check] [--required] [--filter <pkg>] [--dry-run] [-- <passthrough>]
|
|
260
462
|
```
|
|
261
463
|
|
|
262
|
-
Runs one task locally — resolving turbo vs the package manager vs the tool
|
|
263
|
-
itself.
|
|
264
|
-
run
|
|
265
|
-
`holocron run
|
|
266
|
-
|
|
267
|
-
(`
|
|
268
|
-
a task with no sub-jobs the `job` slot is the first passthrough arg
|
|
269
|
-
(`holocron run build src/`).
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
464
|
+
Runs one task, or a suite, locally — resolving turbo vs the package manager vs the tool
|
|
465
|
+
itself. Ids are flat and verb-first: `typecheck`, `build`, `test:unit`, `lint:code`.
|
|
466
|
+
`holocron run test` runs the `test` suite (every `test:*` leaf the repo lists, in registry order, each reported),
|
|
467
|
+
`holocron run test unit` and `holocron run test:unit` run one leaf. The words are joined with `:` and the longest match
|
|
468
|
+
wins, so `deploy preview` is `deploy-preview`; the rest is the `job` argument. A `job` targets a sub-job of the tasks
|
|
469
|
+
that have them (`holocron run lint commit-msg <file>`). A leaf whose tool isn't installed, or that has no local
|
|
470
|
+
equivalent, is skipped with a note — `--required` makes that a failure. For a task with no sub-jobs the `job` slot is the first passthrough arg
|
|
471
|
+
(`holocron run build src/`). `holocron run format` writes (prettier), `holocron run format --check` is read-only.
|
|
472
|
+
`holocron run --help` lists the tasks grouped under the six intent groups. The old dotted names
|
|
473
|
+
(`verification.unitTests`, `sourceQuality.formatting`, …) still work and print a deprecation notice on stderr. <!-- holocron-allow-old-name -->
|
|
474
|
+
|
|
475
|
+
**CI runs the identical command.** The reusable workflows (`typecheck`, `test-unit`,
|
|
476
|
+
`lint-code`, …) call the `holocron` composite action
|
|
273
477
|
(`theholocron/.github/.github/actions/holocron@main`), whose body is
|
|
274
|
-
`holocron run <task> [job]`. So `holocron run test` locally and the `
|
|
478
|
+
`holocron run <task> [job]`. So `holocron run test:unit` locally and the `test:unit` CI
|
|
275
479
|
job execute the same thing — at a turbo root both are
|
|
276
|
-
`turbo run test
|
|
277
|
-
|
|
480
|
+
`turbo run <task>`. `test:unit` always runs with coverage (`vitest run --coverage`); there is no `--coverage` flag.
|
|
481
|
+
|
|
482
|
+
### `holocron deploy on-release`
|
|
483
|
+
|
|
484
|
+
```bash
|
|
485
|
+
holocron deploy on-release [--channel <alpha|main>] [--from <commit>] [--to <commit>] [--dry-run]
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
Deploys every workspace package whose own `holocron.config` declares
|
|
489
|
+
`{ name: "deploy", with: { on: "release" } }` (holocron#930), when the
|
|
490
|
+
release (`--channel`: its prerelease identifier, or `main`/empty for a stable
|
|
491
|
+
release) is on the task's `channel` (default `main`, the stable release) and changes the package or one of its
|
|
492
|
+
`workspace:*` dependencies between `--from` (the previous release's commit,
|
|
493
|
+
omitted when there is none) and `--to` (default `HEAD`). It waits for npm to
|
|
494
|
+
serve the release's new dependency versions, then runs `pnpm --filter <pkg>
|
|
495
|
+
deploy`. A package that doesn't apply is skipped; a deploy that
|
|
496
|
+
doesn't succeed exits non-zero. The shared `release` workflow runs it as its own
|
|
497
|
+
`deploy` job after the release job (opt in with `deploy-on-release: true`).
|
|
278
498
|
|
|
279
|
-
### `holocron ci`
|
|
499
|
+
### `holocron run ci`
|
|
280
500
|
|
|
281
501
|
```bash
|
|
282
|
-
holocron ci [--all] [--filter <pkg>] [--dry-run]
|
|
502
|
+
holocron run ci [--all] [--filter <pkg>] [--dry-run]
|
|
283
503
|
```
|
|
284
504
|
|
|
285
505
|
Runs the merge-gating checks locally, in CI order, exiting non-zero on the
|
|
@@ -288,26 +508,50 @@ first failure — the "will my PR be green?" pre-flight, and what the
|
|
|
288
508
|
(falling back to every `ci: true` task when nothing is marked required).
|
|
289
509
|
`--all` forces the full set; `--filter` is a `turbo --filter=` passthrough.
|
|
290
510
|
Order comes from the `CI_ORDER` constant in `@theholocron/astromech`
|
|
291
|
-
(`typecheck → lint → test → build → …`). Tasks with no local equivalent
|
|
292
|
-
(`
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
511
|
+
(`typecheck → lint:code → … → test:unit → build → …`). Tasks with no local equivalent
|
|
512
|
+
(`scan:code`, `deploy`) are reported as enforced-in-CI, never failures. `format` runs in its
|
|
513
|
+
read-only `--check` form.
|
|
514
|
+
|
|
515
|
+
### `holocron deploy`
|
|
516
|
+
|
|
517
|
+
`holocron deploy <branch>` (a Git-linked deployment) and `holocron deploy
|
|
518
|
+
--files <dir>` (a directory of build output, no linked repo) both trigger a
|
|
519
|
+
deployment through the configured `deployment` capability, then **wait for
|
|
520
|
+
it to finish**. The command reports success, exit code 0, only when the
|
|
521
|
+
deployment reaches `ready`. A deployment that ends `error` or `cancelled`,
|
|
522
|
+
or is still building after 10 minutes, is a failure: the exit code is
|
|
523
|
+
non-zero and the output includes the provider's own reason
|
|
524
|
+
(`DeploymentRecord.errorMessage`, e.g. Vercel's `Command "npm install"
|
|
525
|
+
exited with 1`). Providers build asynchronously, so accepting a deployment
|
|
526
|
+
isn't the same as it going live (holocron#911).
|
|
527
|
+
|
|
528
|
+
Provider plugins support this through the `Deployment` capability's
|
|
529
|
+
existing `getDeployment(id)`. They should set `errorMessage` on the
|
|
530
|
+
returned `DeploymentRecord` whenever the provider exposes one.
|
|
531
|
+
|
|
532
|
+
### `holocron check monitor <url>`
|
|
533
|
+
|
|
534
|
+
Runs every configured `monitoring` check against `<url>` instead of each
|
|
535
|
+
check's own configured `url` — no vendor API call, only a plain HTTP
|
|
536
|
+
request evaluated locally against the exact same `assertions` already in
|
|
537
|
+
`holocron.config.ts`. Built for CI: the `check-preview` task runs
|
|
538
|
+
this against a PR's Vercel preview deployment (triggered by
|
|
539
|
+
`deployment_status`, not `push`/`pull_request`), reusing the production
|
|
540
|
+
check definitions to catch a breaking change before merge instead of
|
|
541
|
+
after (holocron#1010).
|
|
303
542
|
|
|
304
543
|
```ts
|
|
305
544
|
export default defineConfig({
|
|
306
|
-
tasks: [
|
|
307
|
-
providers: {
|
|
545
|
+
tasks: ["check-preview"],
|
|
546
|
+
providers: {
|
|
547
|
+
monitoring: ["checkly", { accountId: "...", checks: [/* ... */] }],
|
|
548
|
+
},
|
|
308
549
|
});
|
|
309
550
|
```
|
|
310
551
|
|
|
552
|
+
Exits non-zero if any check fails — the job's own pass/fail is what
|
|
553
|
+
posts as the GitHub check, no separate reporting step needed.
|
|
554
|
+
|
|
311
555
|
### Skills installer
|
|
312
556
|
|
|
313
557
|
`holocron setup` can install shared skills from `@theholocron/skills` into the local repo:
|
|
@@ -371,18 +615,154 @@ export default acmeConfig;
|
|
|
371
615
|
|
|
372
616
|
```
|
|
373
617
|
|
|
618
|
+
## Notifications — server as code
|
|
619
|
+
|
|
620
|
+
A `notifications` provider can declare a whole server in `holocron.config.ts`
|
|
621
|
+
(`layout`: categories, channels, roles, access, server settings, welcome screen,
|
|
622
|
+
pinned messages, onboarding, the bot application) and the CLI applies and checks it. The
|
|
623
|
+
commands and the config are provider-neutral; Discord is the first provider.
|
|
624
|
+
|
|
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 tokens` | Does every token a plugin declares for a layer carry the permissions the declaration says, and is it fresh? For each layer (`local`, `dev`, `ci`, `prod`) and each token a configured plugin declares for it (`PluginToken.expect`, read by `tokenExpectations()`), reads that layer's Environment in memory and runs the provider's `token` probe against the token it holds (`environmentTokens()`, `runProbe()`: the same flow as `probe <provider> token --environment <layer>`). One row per token per layer: fails for a permission it must not have, one it lacks, a token the layer should hold and does not, or a token past its rotation age or near its expiry. A provider with no declared layers or no `token` probe is a skip. Names, counts and dates only; never a token. Goes online. Read-only (not the old `doctor tokens`, which `doctor secrets --verify` replaced: that asked whether one resolved token is still accepted) |
|
|
644
|
+
| `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 |
|
|
645
|
+
| `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 |
|
|
646
|
+
| `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 |
|
|
647
|
+
|
|
648
|
+
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).
|
|
649
|
+
|
|
650
|
+
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.
|
|
651
|
+
|
|
652
|
+
`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.
|
|
653
|
+
|
|
654
|
+
`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.
|
|
655
|
+
|
|
656
|
+
`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`.
|
|
657
|
+
|
|
658
|
+
A channel with `kind: "forum"` is a forum, with `tags` (each a `name`, an `emoji` and whether it is `moderated`); `setup` adds and corrects the tags but never removes one, and a text channel of the same name must be deleted first, since neither kind can become the other. A forum takes no `webhook` and none of the webhook feeds (`monitoring`, `errors`); its one feed is `feeds: { prs: true }`, the pull-request feed, where Sentinel keeps one post per pull request tagged with its state. The object form `feeds: { prs: { exclude: { repos?: ["owner/name"], authors?: ["login"] } } }` leaves some pull requests out. `feeds.prs` belongs to a forum (a text channel with it is refused) and the forum's `tags` must hold all eight states, `draft`, `conflicts`, `failing`, `changes requested`, `ready`, `waiting`, `merged` and `closed`, or `setup` refuses the layout. `setup` does nothing more for it; `doctor notifications` checks that the forum exists, has those tags and that the bot can start posts and manage threads in it (`ServerInspection` `botThreads`, filled in by the Discord provider after the forum's own permission overwrites). `defaultReaction` is the emoji Discord offers on every post (its Get Started step "Set a default reaction for posts"); Discord allows only one, so `starterReactions` lists more (`["👍", "👎", "❓"]` for approve, disapprove, question) that the bot adds to the first message of each post `sync specs` makes. Existing posts are left alone, a reaction the bot cannot add is skipped, and `doctor notifications` checks `defaultReaction`. Unicode emoji only.
|
|
659
|
+
|
|
660
|
+
`holocron sync specs [--channel <forum>] [--files <paths...>] [--pr <number>] [--refresh] [--refresh-origin] [--refresh-titles] [--withdraw] [--notify]` keeps one forum post per ADR and spec in step with the files: it makes the post (titled with the document's own title, tagged with the file's status), writes its address into the file as `discussion.url`, and turns a gatekeeper's retag into an edit of the file's `status:` line in the working tree for a pull request. `--files` syncs only those files and `--pr` names a pull request on their posts, for a pull request that is still open. `--refresh-origin` is a one-off repair: it rewrites the `PR:` line of existing posts to the one the current rule names (the optional `prLine` of `DiscussionPatch`, and of `DiscussionPost`), and nothing else in them. `--refresh-titles` is the same kind of one-off repair for the title: it renames each existing post whose title differs from the current rule's (the optional `title` of `DiscussionPatch`, and of `DiscussionPost`) and changes nothing else; a rate limit stops it cleanly, reports how many documents are left, and the next run continues. The id that opens a post is a link to the file on the default branch (`repo.defaultBranch`, else `HEAD`) once the file is there, and plain text while `--pr` names an open pull request; the normal sync rewrites a post's id line (and only that line) whenever it is not the one the rule gives and no `--pr` is given, which covers a file that moved and a post made while its pull request was open, so it needs no extra request when every post is right and `--refresh` is no longer needed for it. `--refresh` runs the `PR:`, title and id-link repairs in one pass (the id link is the optional `idLine` of `DiscussionPatch`, and of `DiscussionPost`, which changes only the message's first line); `--refresh-origin` and `--refresh-titles` still do only their own. `--withdraw` (with `--files`, on the base branch) tags the posts of a pull request closed unmerged `withdrawn` and closes them; `withdrawn` is a tag only, never a file `status:`, and the next sync puts the file's own status back. It cannot be combined with `--refresh`, `--refresh-origin` or `--refresh-titles`. `--dry-run` previews it. The posts behind it are also usable for other keys, such as a pull request (`owner/repo#123`, the state a tag name): `DiscussionPatch.body` replaces the first message's text (the provider keeps its footer), and the optional `Notifications` methods `postDiscussionMessage(channel, key, content, { quiet })` (a closed post is unarchived, written to and closed again), `readDiscussionMessages(channel, key, limit)` (text, newest first, 50 by default) and `dedupeDiscussion(channel, key)` (keeps the oldest post of the key, deletes the rest, returns how many) append to, read and repair a post, and `duplicateDiscussions(channel)` lists the keys with more than one post without deleting: `holocron cleanup posts [channel] [--provider <name>] [--yes]` uses the two to clear duplicates that are already there (the forum with `feeds.prs` by default; `--dry-run` previews it). See the [`sync specs` page](https://docs.theholocron.dev/holocron/commands/sync-specs/).
|
|
661
|
+
|
|
662
|
+
Pinned messages are declared under the provider's `layout` as `pinned: [{ channel, content }]` or `pinned: [{ channel, file }]` (`channel` is a channel in the layout, `content` up to 2000 characters, `file` a text file in the repository, such as `.holocron/pinned/rules.md`, whose contents are the message and win over a hand edit; `doctor notifications` reports the drift); the layout is the whole set of messages the bot has pinned in those channels.
|
|
663
|
+
|
|
664
|
+
Config shape added for role sync and sign-in (all under the provider's `layout`):
|
|
665
|
+
|
|
666
|
+
| Field | Meaning |
|
|
667
|
+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
668
|
+
| `testChannel` | The channel (it must declare a webhook) the doctor posts its one self-removing test message to. |
|
|
669
|
+
| `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. |
|
|
670
|
+
| `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. |
|
|
671
|
+
| `links.localPort` | The port of the local sign-in listener (default `53682`, bound to `127.0.0.1` only). |
|
|
672
|
+
| `links.repo` / `links.path` | Where the links file lives (default `<org>/.github-private` and `notifications/<provider>-links.json`). |
|
|
673
|
+
| `application.intents.members` | Switches the Server Members Intent on or off (needed to list who holds a role). |
|
|
674
|
+
| `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. |
|
|
675
|
+
|
|
676
|
+
The links file is `{ "version": 1, "links": [{ "github": "<id>", "login": "<login>", "member": "<id>" }] }`: two public ids per person.
|
|
677
|
+
It is read and written through the `source` capability with the `github.user-sync` token (fine-grained, **only** the
|
|
678
|
+
private config repo, Contents read and write), so no other token needs Contents on other repositories.
|
|
679
|
+
|
|
680
|
+
Capability surface behind it (all optional, so providers without the concept omit them):
|
|
681
|
+
|
|
682
|
+
- `Source.teamMembers(teamSlug, org?)`, `Source.readFile(path, repo?)` (returns the `version` a later write must present),
|
|
683
|
+
`Source.writeFile(path, content, { message, version?, repo? })` (a changed `version` is refused: a real conflict check).
|
|
684
|
+
- `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.
|
|
685
|
+
- `Notifications.roleMembers(role)`, `addRoleMember(role, memberId)`, `removeRoleMember(role, memberId)`.
|
|
686
|
+
- `Notifications.checkDelivery({ channel, name, category?, text })`: posts through a channel's webhook, reads the post back and removes it, and says which step fails.
|
|
687
|
+
- `Notifications.signIn()` returning `{ authorizeUrl, complete }`: the provider-neutral shape of "prove which account you own".
|
|
688
|
+
- `Notifications.ensureApplication` returns `{ updated, todo? }`; each `todo` is a step only a person can do (a portal setting
|
|
689
|
+
the API ignores) and is reported as a failure until done.
|
|
690
|
+
|
|
691
|
+
Provider credentials for Discord: `discord.holonet` is the **bot token** (Bot → Reset Token), `discord.holonet.oauth` is the
|
|
692
|
+
**OAuth client secret** (OAuth2 → Reset Secret). They are different values; the API can create or read neither.
|
|
693
|
+
|
|
694
|
+
See the [command pages](https://theholocron.dev/holocron/commands/setup-notifications/) for each command's options.
|
|
695
|
+
|
|
696
|
+
## Ideas
|
|
697
|
+
|
|
698
|
+
- **`holocron sync ideas [--dry-run] [--yes]`** — files the ideas that are ready: it reads them through the `ideas`
|
|
699
|
+
provider (`providers.ideas: ["obsidian", { dir }]`, an Obsidian vault; `HOLOCRON_IDEAS_DIR` overrides `dir`; the older
|
|
700
|
+
`ideas.dir` is deprecated and read as that entry when `providers.ideas` is absent) and, for each one whose status is
|
|
701
|
+
the filing state (`ideas.states.file`, default `in-progress`) with no issue, creates an issue through the `issues`
|
|
702
|
+
provider (title the first `#` heading, body the note plus `Filed from idea: <title>`) and records it with
|
|
703
|
+
`Ideas.markFiled` (an `issue:` property, for Obsidian). Ideas with attachments are skipped. It never deletes, asks first
|
|
704
|
+
unless `--dry-run` or `--yes`, and a second run changes nothing.
|
|
705
|
+
- **`holocron new spec <issue> [--name <topic>] [--dry-run] [--yes]`** — the spec-time step: reads the issue through the
|
|
706
|
+
`issues` provider (`#1234`, `1234` or a Linear key) and writes `.notes/<name>.spec.md` (`tech-` and the title in
|
|
707
|
+
kebab-case, or `--name` as the whole name) with `status: draft`, `issue:`, `blocked-by: []`, no `id`, and the issue's text
|
|
708
|
+
under `## Problem` less the `Filed from idea:` line and the marker. It never overwrites a file, never edits the issue or
|
|
709
|
+
touches the vault, and asks first unless `--dry-run` or `--yes`.
|
|
710
|
+
- **`holocron new issue <title> [--body <text>] [--label <name>]... [--milestone <value>] [--dry-run] [--yes]`** — files an
|
|
711
|
+
issue through the `issues` provider (`Issues.create`: GitHub or Linear) and prints its key. It asks first unless
|
|
712
|
+
`--dry-run` or `--yes` (without a terminal it refuses instead) and does not look for a duplicate.
|
|
713
|
+
|
|
714
|
+
## Syncing tooling
|
|
715
|
+
|
|
716
|
+
<!--alex ignore postman-postwoman-->
|
|
717
|
+
|
|
718
|
+
- **`holocron sync tooling [--dry-run]`** — runs each `tooling` provider's `sync()` (the Postman plugin pushing a
|
|
719
|
+
workspace, its collections and environments) without `setup`'s other steps. It loads only the `tooling` providers and the
|
|
720
|
+
`credentials` provider their tokens may come from, so an unreachable vault or DNS provider cannot fail it. One row per
|
|
721
|
+
provider, a throwing provider is a failing row and the others still run, `--dry-run` calls none, and there is no
|
|
722
|
+
confirmation (like `setup`). Run it with `--cwd <app>` for an app's own config.
|
|
723
|
+
|
|
724
|
+
## Syncing issues
|
|
725
|
+
|
|
726
|
+
- **`holocron sync issues --from <a> --to <b> [--since <time>] [--yes]`** — one direction of an issue sync between two
|
|
727
|
+
trackers (`github`, `linear:team=ENG`); swap the ends for the other direction. Unlike `holocron migrate` it updates what
|
|
728
|
+
it made: it creates a missing issue, sets title, description, state, priority, labels and assignee when they differ, and
|
|
729
|
+
adds the comments the target lacks (oldest first, never edited or deleted). It writes nothing to the source, and changes
|
|
730
|
+
a target issue only when a migrate or sync made it (the recorded `holocron:migrated-from` marker or attachment). A source
|
|
731
|
+
issue that itself carries such an address is skipped, which stops the two directions echoing each other. The report
|
|
732
|
+
counts created, updated, unchanged, skipped (guard) and left, and ends with the `not carried across` list. A rate limit
|
|
733
|
+
stops the run with a `left` count. A target needs the optional `Issues.sync`; GitHub and Linear have it. `--limit <n>` and
|
|
734
|
+
`--order <oldest|newest>` (also on `migrate issues` and `migrate project`) read only that many issues from the source,
|
|
735
|
+
from the first-created or the last-created end, for a trial run; the source's `Issues.export` honours
|
|
736
|
+
`IssueSelector.limit` and `order`, and the run prints `limited to N of M`. On a terminal, `migrate` and `sync issues` show a spinner with a counter for the read and the write (`Reading issues from github… 12 of 40`, `Writing to linear… 3 of 20`); piped, in CI or with `--quiet` they print nothing extra. A provider feeds it through the optional `onProgress(done, total)` of `ExportInfo` and `ImportOptions`.
|
|
737
|
+
|
|
738
|
+
## Cleaning up
|
|
739
|
+
|
|
740
|
+
- **`holocron apply properties [--yes]`** — adds the capabilities the organization's `holocron_capabilities`
|
|
741
|
+
custom property does not allow yet (`holocron doctor repo` names them). The allowed values are organization-wide, so it
|
|
742
|
+
asks first (`--yes` skips the question; `--dry-run` only reads). It only adds values: nothing is removed or reordered
|
|
743
|
+
and the rest of the definition is kept. It needs a token with the organization's Custom properties: admin.
|
|
744
|
+
- **`holocron cleanup branches [--local | --remote]`** — lists the branches whose pull request is merged,
|
|
745
|
+
grouped, each saying whether it lives locally, on the remote or both; then asks, and offers a checklist with the
|
|
746
|
+
proven-merged ones ticked. Proven merged means an ancestor of `origin/alpha` or `origin/main`, or the head (or an
|
|
747
|
+
ancestor, or one of the commits) of a merged pull request. Branches with more commits than their merged PR, with
|
|
748
|
+
an open PR, checked out (here or in a worktree), or never merged are listed unticked. `--dry-run` only lists;
|
|
749
|
+
`--yes` deletes every proven-merged branch without asking. Pull requests and remote branches come from the
|
|
750
|
+
`source` provider (`Source.listPullRequests`, `listPullRequestCommits`, `listBranches`, `deleteBranch`).
|
|
751
|
+
|
|
374
752
|
## Upgrading
|
|
375
753
|
|
|
376
754
|
- **`holocron upgrade node <to>`** — patches every Node.js version pin
|
|
377
755
|
(`engines.node`, `.nvmrc`, `.node-version`, `.github/workflows/*`,
|
|
378
|
-
`Dockerfile`, `.tool-versions`) to a new major.
|
|
756
|
+
`Dockerfile`, `.tool-versions`) to a new major. The rewrite is
|
|
757
|
+
`runUpgradeNode()` in `@theholocron/astromech/upgrade`; the command only
|
|
758
|
+
binds the logger and reads `upgrade.node.extra`.
|
|
379
759
|
- **`holocron upgrade deps`** — bumps every `@theholocron/*` pin in
|
|
380
760
|
`pnpm-workspace.yaml` (`catalog:` and every named `catalogs.*`) to its latest
|
|
381
761
|
published version, then migrates `holocron.config.ts` from the 7.x preset
|
|
382
762
|
shape (`const { repo, workflows } = node()` + `repo.requiredChecks` +
|
|
383
763
|
`workflows:`) to the current composed-preset API (`const preset = node()` +
|
|
384
764
|
`...preset` + `tasks:` + `extraRequiredChecks:`). Mechanical transforms only —
|
|
385
|
-
review the result, then `pnpm install && holocron ci`. `--pins-only` skips
|
|
765
|
+
review the result, then `pnpm install && holocron run ci`. `--pins-only` skips
|
|
386
766
|
the config migration; `--dry-run` prints without writing.
|
|
387
767
|
|
|
388
768
|
## Auth — fine-grained tokens
|
|
@@ -392,42 +772,70 @@ credential only affects that feature. Store them once in the OS keyring
|
|
|
392
772
|
(macOS Keychain, Windows Credential Manager, libsecret on Linux):
|
|
393
773
|
|
|
394
774
|
```sh
|
|
395
|
-
holocron
|
|
396
|
-
holocron
|
|
397
|
-
holocron
|
|
398
|
-
holocron
|
|
399
|
-
holocron
|
|
775
|
+
holocron new token github.read ghp_xxx # clone + CI run listing
|
|
776
|
+
holocron new token github.issues ghp_xxx # issue management
|
|
777
|
+
holocron new token github.sync ghp_xxx # sync-github workflow templates
|
|
778
|
+
holocron new token github.release ghp_xxx # semantic-release
|
|
779
|
+
holocron new token github.admin ghp_xxx # setup, secrets, environments
|
|
780
|
+
holocron new token github.user-sync ghp_xxx # the files that link GitHub accounts to other services' members
|
|
400
781
|
```
|
|
401
782
|
|
|
402
783
|
The resolution chain per capability is:
|
|
403
784
|
|
|
404
|
-
```
|
|
785
|
+
```text
|
|
405
786
|
--token flag → HOLOCRON_<FEATURE>_TOKEN env var → keyring("github.<feature>")
|
|
406
787
|
```
|
|
407
788
|
|
|
408
789
|
See [`docs/tokens.md`](../../docs/tokens.md) for required PAT scopes per feature.
|
|
409
790
|
|
|
410
|
-
|
|
791
|
+
A plugin lists the tokens it takes in a `tokens: PluginToken[]` export (each resolver exposes its own as `.token`), as
|
|
792
|
+
`{ envName, vendorEnvName?, keyringKey, verifiable?, optional? }`, so `holocron doctor secrets` (the `local` and `dev` columns, and `--verify`) and
|
|
793
|
+
`export tokens` can find them. Set `optional: true` on a token the plugin only falls back to, such as the Discord
|
|
794
|
+
webhook a post uses when it names no channel: the checks that expect every listed token do not expect it, and
|
|
795
|
+
`export tokens` marks it `(optional)` when it has no value. `verifiable: false` marks a token `verifyToken` does not
|
|
796
|
+
apply to.
|
|
797
|
+
|
|
798
|
+
The token commands:
|
|
411
799
|
|
|
412
800
|
```sh
|
|
413
|
-
holocron
|
|
414
|
-
holocron
|
|
415
|
-
holocron
|
|
801
|
+
holocron check token github.read # re-verify a stored token
|
|
802
|
+
holocron remove token github.read # remove a stored token
|
|
803
|
+
holocron list tokens # show all stored providers
|
|
804
|
+
holocron list skills # the skills installed in .agents/skills/
|
|
805
|
+
holocron remove skill --all # remove every installed skill (or name some; a bare call asks on a terminal)
|
|
806
|
+
holocron export tokens # tokens as NAME=value lines in a private .credentials, to import into a credentials environment
|
|
807
|
+
holocron export tokens --only HOLOCRON_SENTRY_TOKEN # one token, to the clipboard
|
|
808
|
+
holocron export requests --dry-run # convert the repo's request collections for each tooling provider that can export, writing nothing
|
|
809
|
+
holocron export requests --to bruno --yes # write requests/.export/bruno/ (ignored by version control; never inside the source folder)
|
|
810
|
+
holocron export tokens --blank --vendor-names --file --only VERCEL_TOKEN --only HOLOCRON_RELEASE_TOKEN # the stored ones filled, the rest empty
|
|
811
|
+
holocron new github-app --name "My App - dev" --webhook-url https://<tunnel>/api/webhook --manifest apps/sentinel/github-app.manifest.json # a GitHub App from a manifest (the flow is in @theholocron/dagobah); its id, key and webhook secret to a private .credentials
|
|
812
|
+
holocron new tunnel --name sentinel-dev --hostname sentinel-dev.example.dev --port 3000 --run # a named tunnel with a stable hostname to a local port
|
|
813
|
+
holocron list projects # the org's project boards (also: create [template], close <number-or-name>, setup)
|
|
814
|
+
holocron migrate project v5 --from github --to github:repo=acme/new --dry-run # preview putting a board's issues on a board of the same name in the target (GitHub; --template picks the template a missing board is made from, default roadmap); a target without boards (Linear) gets a project of that name instead
|
|
815
|
+
holocron migrate issues --all --from github --to linear:team=ENG --limit 20 --order newest --dry-run # a trial run: read only the 20 last-created issues (--order oldest, the default, reads the first created); prints `limited to 20 of M`, and a second run with the same limit selects the same issues (`migrate issues` and `migrate project`, and `sync issues`; not `migrate issue`)
|
|
816
|
+
holocron move issues v4 v5 --dry-run # preview carrying the open items of one project board to another; without --dry-run it asks first (--yes skips)
|
|
817
|
+
holocron doctor project # does each declared board match its template? (read-only; --post shares the failures)
|
|
818
|
+
holocron dev # the app, its vault variables and the tunnel, in one command (settings: `dev` in holocron.config)
|
|
416
819
|
```
|
|
417
820
|
|
|
418
821
|
## Logging
|
|
419
822
|
|
|
420
823
|
Operational output goes through `@theholocron/observability/logger` — separate
|
|
421
|
-
from the user-facing `print` surface.
|
|
824
|
+
from the user-facing `print` surface. Local/interactive runs are quiet by
|
|
825
|
+
default: no colorized or raw structured console output, regardless of the
|
|
826
|
+
resolved level (Axiom shipping, when configured, is unaffected). CI is
|
|
827
|
+
untouched — its existing stdout output still appears. Global flags:
|
|
422
828
|
|
|
423
829
|
```sh
|
|
424
|
-
holocron doctor --
|
|
425
|
-
holocron doctor --
|
|
830
|
+
holocron doctor --log debug # show console output at this level (opt back in)
|
|
831
|
+
holocron doctor --verbose # log level → debug, and shows console output
|
|
832
|
+
holocron doctor --quiet # log level → error, and shows console output
|
|
426
833
|
holocron doctor --debug # print "Run ID: <uuid>" at command end for Axiom lookup
|
|
427
834
|
```
|
|
428
835
|
|
|
429
|
-
Level resolution (highest priority first): `--
|
|
430
|
-
`HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` →
|
|
836
|
+
Level resolution (highest priority first): `--log <level>` → `--verbose` /
|
|
837
|
+
`--quiet` → `HOLOCRON_LOG_LEVEL` → `log.level` in `holocron.config` →
|
|
838
|
+
`"info"`.
|
|
431
839
|
|
|
432
840
|
```ts
|
|
433
841
|
export default defineConfig({
|
|
@@ -438,8 +846,18 @@ export default defineConfig({
|
|
|
438
846
|
Axiom shipping activates when a token (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN`
|
|
439
847
|
→ OS keyring `axiom.<org>` → `axiom`) **and** a dataset
|
|
440
848
|
(`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET` → `log.axiom.dataset` in
|
|
441
|
-
`holocron.config`
|
|
442
|
-
|
|
849
|
+
`holocron.config` → the credential chain, where the 1Password-synced
|
|
850
|
+
`AXIOM_DATASET` lives) both resolve; env vars win. The token is never read from a
|
|
851
|
+
config file.
|
|
852
|
+
|
|
853
|
+
Each service has one dataset for all its environments (ADR-0019; the CLI's is `holocron`); each line carries `env`
|
|
854
|
+
(`local`, `development`, `ci`, `test`, `production`), so a query filters by it.
|
|
855
|
+
`log.axiom.dataset` is only a per-repo override. The dataset side of the
|
|
856
|
+
resolution is **execution-context-aware** (ADR-0012): a `global`-context command
|
|
857
|
+
(`clone`, `new`, `new token`, `upgrade node`, `plugin create`, …) is not "about"
|
|
858
|
+
any repo, so it skips the repo's `log.axiom.dataset` and uses the CLI's dataset
|
|
859
|
+
from the environment or credential chain. `repo-aware` / `workspace` commands
|
|
860
|
+
(`doctor`, `deploy`, `sync`, …) keep the full chain above. See the [logging guide](https://docs.theholocron.dev/holocron/logging/).
|
|
443
861
|
|
|
444
862
|
### Telemetry
|
|
445
863
|
|
|
@@ -468,38 +886,80 @@ export default defineConfig({
|
|
|
468
886
|
|
|
469
887
|
Each SDK sits behind an interface from `@theholocron/observability` —
|
|
470
888
|
`ErrorSink` (Sentry) / `AnalyticsSink` (PostHog); the adapters, and the only
|
|
471
|
-
`@sentry/node` / `posthog-node` imports, live in that package. `
|
|
472
|
-
|
|
473
|
-
(`
|
|
889
|
+
`@sentry/node` / `posthog-node` imports, live in that package. the orchestration is `createCliTelemetry` in `@theholocron/kyber/observability`;
|
|
890
|
+
`observability/telemetry.ts` binds it to the Holocron-specific credential resolution
|
|
891
|
+
(`observability/resolve-telemetry.ts`). See the
|
|
474
892
|
[telemetry guide](https://docs.theholocron.dev/holocron/telemetry/).
|
|
475
893
|
|
|
894
|
+
### ESLint bundle options
|
|
895
|
+
|
|
896
|
+
Most repos need nothing here — `@theholocron/eslint-config`'s `library()`
|
|
897
|
+
bundle resolves with zero committed file (Bucket A: `eslint --config
|
|
898
|
+
<shared path>`, no per-repo `eslint.config.ts` needed). A package with a
|
|
899
|
+
genuine, deliberate exception — e.g. Web Crypto globals a Node-targeted
|
|
900
|
+
package still needs, exempted via `library()`'s own `browserPackages`
|
|
901
|
+
option in that package's own `eslint.config.ts` — should also declare the
|
|
902
|
+
same paths in `holocron.config`'s `eslint.browserPackages`:
|
|
903
|
+
|
|
904
|
+
```ts
|
|
905
|
+
export default defineConfig({
|
|
906
|
+
eslint: {
|
|
907
|
+
browserPackages: ["clients/github-client/src/app-auth"],
|
|
908
|
+
},
|
|
909
|
+
});
|
|
910
|
+
```
|
|
911
|
+
|
|
912
|
+
This doesn't replace the package's own `eslint.config.ts` (local/CI linting
|
|
913
|
+
still resolves that file directly) — it's the signal Sentinel's centralized
|
|
914
|
+
static-analysis check (holocron#849/#858) reads instead, since that check
|
|
915
|
+
never reads a PR's own committed config files. Without it, Sentinel flags a
|
|
916
|
+
false-positive `eslint-plugin-n` node-builtins finding on exactly the files
|
|
917
|
+
the local override exists to exempt.
|
|
918
|
+
|
|
476
919
|
## What's in here
|
|
477
920
|
|
|
478
|
-
- `src/capabilities
|
|
479
|
-
implement
|
|
921
|
+
- `src/plugin/capabilities.ts` — the 24 capability interfaces that
|
|
922
|
+
providers implement
|
|
480
923
|
- `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
|
|
481
924
|
`CapabilityConfigPackage`
|
|
482
|
-
- `src/config/
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
925
|
+
- `src/config/config-system.ts` — `defineConfig`, `loadConfig` (reads `holocron.config.*`;
|
|
926
|
+
file discovery via [`@theholocron/datapad`](../datapad)) and `compose`, all built from
|
|
927
|
+
kyber's `createConfigSystem`; Holocron's own rules sit beside it in `config/config`,
|
|
928
|
+
`compose/{merge-*,task-name}` and `load-config/{derive-defaults,read-package-json-name}`
|
|
929
|
+
- `src/observability/logger.ts` — CLI-side `@theholocron/observability/logger` wiring
|
|
486
930
|
(`buildCliLogger`, `resolveLogLevel`)
|
|
487
|
-
- `src/loader.ts` — `PluginLoader
|
|
488
|
-
|
|
489
|
-
|
|
931
|
+
- `src/plugin/loader/loader.ts` — `PluginLoader`, a binding of kyber's `createPluginSystem`
|
|
932
|
+
(`@theholocron/kyber/plugins`: dynamic-imports plugins, resolves capability config packages,
|
|
933
|
+
builds the capability registry); Holocron's prefix, plugin options and the credentials / `.env`
|
|
934
|
+
step are passed in
|
|
935
|
+
- `src/cli/cli.ts` — yargs entry, dispatches subcommands. `holocron run` / `ci` are
|
|
490
936
|
delegated to [`@theholocron/astromech`](../astromech) (`createAstromech`).
|
|
491
937
|
`holocron sync` / `holocron setup` write each repo's `.github/workflows/*.yml`
|
|
492
|
-
thin callers from `astromech.thinCallers()`; `holocron sync
|
|
938
|
+
thin callers from `astromech.thinCallers()`; `holocron sync github` pushes the
|
|
493
939
|
reusable `workflow_call` implementations + composite actions from
|
|
494
|
-
`astromech.reusableTemplates()` to `theholocron/.github` (a pure sync target —
|
|
940
|
+
`astromech.reusableTemplates()` (written in `ci/`) to `theholocron/.github` (a pure sync target —
|
|
495
941
|
never hand-edit its `.github/workflows/*`).
|
|
496
|
-
- `src/commands/` — `setup`, `sync`, `doctor`, `deploy`,
|
|
497
|
-
`
|
|
498
|
-
`
|
|
499
|
-
|
|
500
|
-
`
|
|
501
|
-
`
|
|
502
|
-
`
|
|
942
|
+
- `src/commands/` — `setup`, `sync`, `doctor`, `deploy`,
|
|
943
|
+
`check monitor`, `list secrets`, `new secret`, `sync secrets`, `publish package`,
|
|
944
|
+
`publish bump-versions`, `publish tag`, `sync github`, `upgrade node`,
|
|
945
|
+
`upgrade deps`, `new plugin`, `check token`, `export tokens`, `export requests`, `setup notifications`,
|
|
946
|
+
`new channel`, `link account`,
|
|
947
|
+
`sync roles`, `doctor ci`, `doctor dns`, `doctor environments`, `doctor monitoring`, `doctor notifications`, `doctor project`, `doctor repo`, `doctor secrets`
|
|
948
|
+
`sync roles`, `reconcile project`, `doctor ci`, `doctor dns`, `doctor environments`, `doctor monitoring`, `doctor notifications`, `doctor repo`, `doctor secrets`
|
|
949
|
+
- `src/commands/deep-checks/` — `DEEP_CHECKS`, the registry every `doctor <capability>` is
|
|
950
|
+
listed in; the shared row renderer and `declaredVsActual` helper are in `@theholocron/kyber/ui`
|
|
951
|
+
- `src/interactive-menu/` — the interactive fallback's Holocron data: `command-catalog`
|
|
952
|
+
(`COMMAND_REGISTRY`, built with kyber's `createCommandRegistry`; each entry's `positionals`/`options`), `run-menu-entries`
|
|
953
|
+
and `probe-menu-entries` (menu entries built at run time), and `menu.ts`,
|
|
954
|
+
kyber's `createMenu` bound to the `holocron` bin and `HOLOCRON_` env prefix.
|
|
955
|
+
The engine itself (the picker, argv and secret env, the dry-run preview, the spawn)
|
|
956
|
+
and the prompting pieces — `promptForPositionals`, `promptForOptions` — live in
|
|
957
|
+
`@theholocron/kyber` (`/menu`, `/prompts`), which has no knowledge of commands.
|
|
958
|
+
- `src/plugin/probes/connection-probe/` — the `connectionProbe` a plugin offers, kyber's `connectionProbe` (`@theholocron/kyber/checks`)
|
|
959
|
+
typed as the plugin system's `Probe` with `verify` returning `VerifyTokenResult`; `check monitor` runs its checks
|
|
960
|
+
with kyber's `runCheckAgainstUrl`.
|
|
961
|
+
- `src/commands/move-tag/` — the `publish tag` yargs command, the registry entry and `runMoveTag`, which adds the
|
|
962
|
+
command-bound logger to kyber's `moveMajorTag` (`@theholocron/kyber/git`).
|
|
503
963
|
|
|
504
964
|
## Status
|
|
505
965
|
|