@theholocron/cli 5.0.0-alpha.404 → 5.0.0-alpha.405

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.
@@ -1,4 +1,1039 @@
1
1
  import { ProviderApiError } from "@theholocron/http-client";
2
+ import { ConfigError as ConfigError$1, ConfigFileError } from "@theholocron/kyber/config";
3
+ import { PackageJson } from "@theholocron/pkg-utils";
4
+ import { DocsCoverageMode, WorkspacePackage } from "@theholocron/astromech";
5
+ import { LogLevel } from "@theholocron/observability/core";
6
+ /** Structured-logging config. The Axiom **token** never lives here — only in
7
+ * env vars or the OS keyring — but the non-secret dataset name may. */
8
+ interface LogConfig {
9
+ /**
10
+ * Default log level. The lowest-priority level source: `--verbose` /
11
+ * `--quiet` and `HOLOCRON_LOG_LEVEL` both outrank it.
12
+ */
13
+ level?: LogLevel;
14
+ /**
15
+ * Axiom log-shipping. The CLI has one dataset for all its environments, told apart by
16
+ * the `env` field on each line, and that dataset normally comes from the
17
+ * `HOLOCRON_AXIOM_DATASET` variable (`holocron`, synced from 1Password) with no config at all.
18
+ * Set `axiom.dataset` only for a repo that keeps its own dataset: the CLI
19
+ * pairs it with the token from `HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN` or the
20
+ * OS keyring (`holocron auth set axiom[.<org>] <TOKEN>`). Env vars still
21
+ * win, and a `global`-context command ignores it.
22
+ */
23
+ axiom?: {
24
+ /** Target Axiom dataset for this repo, e.g. `"my-repo"`. */
25
+ dataset?: string;
26
+ };
27
+ }
28
+ /**
29
+ * CLI self-telemetry config — the committed, reviewable override layer over the
30
+ * env-var + shipped-fallback activation (ADR-0007 / ADR-0008). No secret lives
31
+ * here; the Sentry DSN and PostHog key come from env vars or ship as fallbacks.
32
+ *
33
+ * Precedence: `HOLOCRON_TELEMETRY=false` (env) → `telemetry.enabled` (this) →
34
+ * default on. `enabled` never *re-enables* what the env var turned off.
35
+ */
36
+ interface TelemetryConfig {
37
+ /**
38
+ * Repo-level opt-out — the committed peer of `HOLOCRON_TELEMETRY=false`.
39
+ * `false` installs the no-op sinks for the whole run. Default on.
40
+ */
41
+ enabled?: boolean;
42
+ /**
43
+ * Usage-analytics provider. `"none"` disables PostHog usage analytics while
44
+ * leaving error reporting (Sentry) untouched. Default `"posthog"`.
45
+ */
46
+ analytics?: "posthog" | "none";
47
+ }
48
+ /** Options a provider plugin receives; their shape is the plugin's own. */
49
+ type ProviderOptions = Record<string, unknown>;
50
+ /**
51
+ * The shape a capability config package's default export must satisfy.
52
+ * Config packages let teams share a pre-bundled provider + options across
53
+ * repos (Level 1 of the shareable-configs story, issue #75).
54
+ *
55
+ * @example
56
+ * // @acme/holocron-vault/index.ts
57
+ * import type { CapabilityConfigPackage } from '@theholocron/cli'
58
+ * export default {
59
+ * provider: '1password',
60
+ * options: { vault: 'acme-app' },
61
+ * } satisfies CapabilityConfigPackage
62
+ */
63
+ interface CapabilityConfigPackage {
64
+ /** The provider's short name or package. */
65
+ provider: string;
66
+ /** Options passed to the provider. */
67
+ options?: ProviderOptions;
68
+ }
69
+ /** A single provider: a name, or a `[provider, options]` tuple. */
70
+ type SingleEntry = string | [provider: string, options: ProviderOptions];
71
+ /** Several providers: a list of names or `[provider, options]` tuples. */
72
+ type MultiEntry = Array<string | [provider: string, options: ProviderOptions]>;
73
+ /** A capability's provider entry as written in the config. */
74
+ type RawProviderEntry = SingleEntry | MultiEntry;
75
+ /** The `providers` block as written in the config. */
76
+ type RawProvidersConfig = Partial<Record<CapabilityKey, RawProviderEntry>>;
77
+ /** A branch-protection preset: `balanced`, `strict` or `none`. */
78
+ type RepoProtection = "balanced" | "strict" | "none";
79
+ /**
80
+ * Raw `docs` config as written by the user. `build` is optional so the
81
+ * field can be declared without committing to a build type yet; setup
82
+ * will error if `docs` is present but `build` is absent.
83
+ */
84
+ interface DocsConfig {
85
+ /**
86
+ * GitHub Pages build source.
87
+ * "workflow" → GitHub Actions (PUT { build_type: "workflow" })
88
+ * "branch" → classic gh-pages branch (PUT { build_type: "legacy", source: { branch: "gh-pages", path: "/" } })
89
+ * When absent, Pages is not managed by `holocron repo setup`.
90
+ */
91
+ build?: "workflow" | "branch";
92
+ /**
93
+ * Custom domain / CNAME (e.g. "docs.theholocron.dev").
94
+ * When set and `homepage` is not explicitly provided, setup derives
95
+ * `homepage` as `https://{domain}/` for package.json and the repo website field.
96
+ */
97
+ domain?: string;
98
+ /** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
99
+ https?: boolean;
100
+ }
101
+ /** GitHub custom properties synced to the org dashboard. */
102
+ interface RepoProperties {
103
+ /** The repo's lifecycle stage. */
104
+ lifecycle?: "active" | "experimental" | "deprecated";
105
+ /** Whether the repo is open source. */
106
+ open_source?: boolean;
107
+ /** Where the code runs. */
108
+ runtime_environment?: "node" | "browser" | "universal" | "none";
109
+ /** Whether the repo depends on external packages. */
110
+ uses_external_packages?: boolean;
111
+ }
112
+ /**
113
+ * GitHub Actions variables, declared so a workflow that reads `vars.NAME` finds it. Values are plain text, so
114
+ * never put a secret here; secrets go through the `secrets` capability.
115
+ */
116
+ interface RepoVariables {
117
+ /** Repository-level variables. */
118
+ repo?: Record<string, string>;
119
+ /**
120
+ * Organization-level variables. A bare string is visible to every repository; `visibility: "private"` limits it
121
+ * to private ones. Declare these in one repo only (the one that owns the org's configuration).
122
+ */
123
+ org?: Record<string, string | {
124
+ value: string;
125
+ visibility?: "all" | "private";
126
+ }>;
127
+ /**
128
+ * The vault environments `holocron secrets sync` fills variables from, so one 1Password Environment is the only
129
+ * place they are edited. Names only. A name here must not also be a literal value in `repo` or `org`, and `prune`
130
+ * cannot be combined with it; either is a config error.
131
+ */
132
+ sync?: RepoVariablesSync[];
133
+ /** Delete variables that exist but are not declared here. Off by default: they are left alone. */
134
+ prune?: boolean;
135
+ }
136
+ /**
137
+ * One vault environment that `holocron secrets sync` pushes into GitHub Actions variables. Not secrets: a variable is
138
+ * readable in GitHub afterwards, so keep it in an environment of its own, apart from the one that fills secrets.
139
+ */
140
+ interface RepoVariablesSync {
141
+ /** The vault environment id, as given to `holocron secrets sync <environmentId>`. */
142
+ environment: string;
143
+ /** The vault keys written as variables, by name. Required: a key the environment gains by mistake is never published. */
144
+ keys: string[];
145
+ /** Where the variables land: `"repo"` (the default) or `"org=<name>"`. */
146
+ scope?: string;
147
+ /** Organization variables only: which repositories can read them. `"all"` by default. */
148
+ visibility?: "all" | "private";
149
+ }
150
+ /**
151
+ * The names of the secrets that must exist for this repository's workflows to work, so `holocron doctor secrets`
152
+ * can say which are missing. Only names go here, never values; `holocron secrets set` and `secrets sync` write
153
+ * them. The secrets the config already implies (the notification layout's webhooks and roles, a Chromatic project
154
+ * token) are expected without being listed again. A secret that exists but is not listed is never a problem.
155
+ */
156
+ interface RepoSecrets {
157
+ /** Repository secrets. */
158
+ repo?: string[];
159
+ /** Organization secrets. Declare these in one repo only (the one that owns the org's configuration). */
160
+ org?: string[];
161
+ /** Environment secrets, by environment name. */
162
+ environments?: Record<string, string[]>;
163
+ /**
164
+ * The vault environments `holocron secrets sync` fills secrets from. `holocron doctor secrets` expects the
165
+ * keys each one holds (or lists) at its scope. Names only; the doctor never reads or prints a value.
166
+ */
167
+ sync?: RepoSecretsSync[];
168
+ }
169
+ /** One vault environment that `holocron secrets sync` pushes into GitHub secrets, declared so the doctor can check them. */
170
+ interface RepoSecretsSync {
171
+ /** The vault environment id, as given to `holocron secrets sync <environmentId>`. */
172
+ environment: string;
173
+ /**
174
+ * The vault keys pushed to GitHub (the `--github-secret` allowlist). Omit it for every key the vault
175
+ * environment holds, which the doctor then asks the `vault` provider to list.
176
+ */
177
+ keys?: string[];
178
+ /** Where the secrets land, as `--github-secret-scope` words it: `"repo"` (the default), `"env=<name>"` or `"org=<name>"`. */
179
+ scope?: string;
180
+ }
181
+ /** Per-repo switches for the repo-validation checks (spec `tech-api-docs`, #1368). */
182
+ interface RepoValidationConfig {
183
+ /**
184
+ * How strictly this repo enforces doc-comment coverage of its public API (`holocron probe docs patch` and
185
+ * the `documentation` Codecov flag). `"off"` (the default) does nothing; `"warn"`
186
+ * reports without failing and posts informational Codecov statuses; `"required"` fails the check and posts statuses
187
+ * that are not informational. It never adds a status to the branch-protection required checks: that stays in
188
+ * `extraRequiredChecks`.
189
+ */
190
+ docsCoverage?: DocsCoverageMode;
191
+ }
192
+ /**
193
+ * The `.holocron/org.*` area: the organization's non-CI constants that are provider options. The loader fills an
194
+ * option a provider entry leaves out from here; the same option set inline and here is a `ConfigError`. Identifiers
195
+ * only, never a secret, and nothing CI needs (those live in 1Password and sync to a GitHub variable). A key a provider
196
+ * does not use is ignored; a provider or option not listed here is an error.
197
+ */
198
+ interface OrgConfig {
199
+ /**
200
+ * The organization's DNS zone (`theholocron.dev`). The loader sets `domain` on a config that leaves it out; a
201
+ * config that sets it too is a `ConfigError`. A file that must build a hostname before the loader runs imports
202
+ * this area file instead (`import org from "./org.js"`).
203
+ */
204
+ domain?: string;
205
+ /** Options filled into every `cloudflare` provider entry. */
206
+ cloudflare?: {
207
+ /** The Cloudflare account id (an identifier, not a credential). */
208
+ accountId?: string;
209
+ };
210
+ /** Options filled into every `vercel` provider entry. */
211
+ vercel?: {
212
+ /** The Vercel team id (an identifier, not a credential). */
213
+ teamId?: string;
214
+ };
215
+ /** Options filled into every `checkly` provider entry. */
216
+ checkly?: {
217
+ /** The Checkly account id (an identifier, not a credential). */
218
+ accountId?: string;
219
+ };
220
+ /** Options filled into every `sentry` provider entry. */
221
+ sentry?: {
222
+ /** The Sentry organization slug (an identifier, not a credential). */
223
+ org?: string;
224
+ };
225
+ }
226
+ /** The `repo` block: how the GitHub repository is set up and kept in sync by `holocron repo setup`. */
227
+ interface RepoConfig {
228
+ /** "owner/name" — the GitHub repository coordinate. Derived from the git remote when absent. */
229
+ name?: string;
230
+ /**
231
+ * GitHub's repo-level default branch (`HEAD`) — what a fresh clone checks
232
+ * out, what `gh pr create`/the compare UI target by default, and what
233
+ * Sentinel's `validateConfig()` reads (D6: the App only ever reads config
234
+ * from the repo's default branch, never a PR ref, as a security boundary
235
+ * — never widen that to read PR branches instead of fixing this field).
236
+ * Synced by `holocron repo setup`. Omit to leave GitHub's current setting
237
+ * untouched — most repos never need this. Exists for a repo using a
238
+ * `main`/`alpha` prerelease-channel split (CLAUDE.md's Releases section)
239
+ * where active development happens on a non-`main` branch: set this to
240
+ * that branch so Sentinel validates against what's actually being
241
+ * developed, then change it back once that branch merges to `main` for a
242
+ * stable cut and stops being the active branch.
243
+ */
244
+ defaultBranch?: string;
245
+ /**
246
+ * Branch protection preset applied by `holocron repo setup`. When omitted,
247
+ * no protection is applied and no `branch_protection_level` property is set.
248
+ * Required-status-check contexts for `"strict"` are derived from the task
249
+ * manifest — `{ required: true }` tasks + top-level `extraRequiredChecks`
250
+ * (see `astromech.requiredChecks()`).
251
+ */
252
+ protection?: RepoProtection;
253
+ /**
254
+ * GitHub teams granted repository access. Synced by `holocron repo setup`, which
255
+ * also writes `.github/CODEOWNERS` for teams with write-or-higher permission.
256
+ * String shorthand defaults to `push` (Write).
257
+ */
258
+ teams?: TeamEntry[];
259
+ /** GitHub topics set on the repository. */
260
+ topics?: string[];
261
+ /** GitHub custom properties synced to the org dashboard. */
262
+ properties?: RepoProperties;
263
+ /** GitHub Actions variables reconciled by `holocron repo setup`. */
264
+ variables?: RepoVariables;
265
+ /** The secrets that must exist, checked by `holocron doctor secrets`. Names only; nothing writes them. */
266
+ secrets?: RepoSecrets;
267
+ }
268
+ /** An application in the repo. */
269
+ interface AppConfig {
270
+ /** The application's name. */
271
+ name: string;
272
+ /** The application's directory. */
273
+ path: string;
274
+ /** What kind of application it is. */
275
+ kind?: string;
276
+ }
277
+ /** The `doctor` block. */
278
+ interface DoctorConfig {
279
+ /** Names of the checks `doctor` runs. */
280
+ checks?: string[];
281
+ /**
282
+ * The mail provider that serves the apex of `domain`. `holocron doctor dns` then expects that provider's MX and SPF
283
+ * records in the zone, so a change that would break mail is caught. Nothing writes them; they are set up by hand.
284
+ */
285
+ mail?: "icloud";
286
+ }
287
+ /** The `credentials` block: which environment the `credentials` providers read this machine's tokens from. */
288
+ interface CredentialsConfig {
289
+ /**
290
+ * The name of the environment the `credentials` providers read (a 1Password Environment, for 1Password), for
291
+ * every provider that does not give its own with an `environment` option
292
+ * (`credentials: ["1password", { environment: "Holocron" }]`). It is a name, not a secret, so it is committed. A provider that matches names exactly may be tried with other
293
+ * letter cases of it; see the provider's page.
294
+ */
295
+ environment: string;
296
+ }
297
+ /** One entry of `githubApps`: a registered GitHub App instance `holocron doctor github-app` compares with its manifest. */
298
+ interface GitHubAppConfig {
299
+ /** The instance's name in the report, e.g. `"Sentinel - dev"`. */
300
+ name: string;
301
+ /**
302
+ * The App manifest file, relative to the directory: `default_permissions` (name to `read`, `write` or
303
+ * `admin`) and `default_events` (names), as in `apps/sentinel/github-app.manifest.json`.
304
+ */
305
+ manifest: string;
306
+ /**
307
+ * The vault environment (a 1Password Environment) that holds the instance's `SENTINEL_GITHUB_APP_ID` and
308
+ * `SENTINEL_GITHUB_APP_PRIVATE_KEY` (or the older bare `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`). A name, not a secret, so it is committed.
309
+ */
310
+ environment: string;
311
+ }
312
+ /**
313
+ * The `ideas` block: the state that files an idea as an issue. Where the ideas are kept is the `ideas` provider's
314
+ * (`providers.ideas: ["obsidian", { dir }]`), not this block's.
315
+ */
316
+ interface IdeasConfig {
317
+ /**
318
+ * The folder of Markdown notes (an Obsidian vault). May start with `~` for the home folder. `HOLOCRON_IDEAS_DIR`
319
+ * overrides it, since the path differs per machine.
320
+ *
321
+ * @deprecated Set `dir` on the provider instead: `providers: { ideas: ["obsidian", { dir }] }`. Read only when
322
+ * `providers.ideas` is absent, as if it were `["obsidian", { dir }]`; `providers.ideas` wins when both are set.
323
+ */
324
+ dir?: string;
325
+ /** The names of the note states, so a repo can use its own words. */
326
+ states?: {
327
+ /** The `status:` that means "file this idea" (default `in-progress`). */
328
+ file?: string;
329
+ };
330
+ }
331
+ /** The `dev` block: how `holocron dev` runs this directory's application locally behind a development tunnel. */
332
+ interface DevConfig {
333
+ /**
334
+ * The vault environment whose variables the application runs with, e.g. `"Sentinel - dev"`. A name, not a
335
+ * secret, so it is committed.
336
+ */
337
+ environment?: string;
338
+ /** The named tunnel to the application: its name, and the public hostname it serves (not a secret). */
339
+ tunnel?: {
340
+ /** The tunnel's name. A second run finds the first one's tunnel by it. */
341
+ name: string;
342
+ /** The public hostname, e.g. `sentinel-dev.theholocron.dev`. One level under a zone the DNS provider manages. */
343
+ hostname: string;
344
+ };
345
+ /** The port the application listens on, and the tunnel sends requests to. Defaults to 3000. */
346
+ port?: number;
347
+ /** The application's command and arguments, e.g. `["pnpm", "run", "serve"]`. */
348
+ command?: string[];
349
+ /**
350
+ * A web-standard handler for `holocron dev` to serve itself, in place of `command`: the application is then
351
+ * `holocron dev serve`, which loads the handler and serves it on `PORT`. `command` and a command after `--` win.
352
+ */
353
+ serve?: DevServeConfig;
354
+ }
355
+ /** The `dev.serve` block: the handler `holocron dev` serves, and the variables it needs. */
356
+ interface DevServeConfig {
357
+ /** The module that exports the handler, relative to the directory, e.g. `./src/handler/index.ts`. TypeScript is loaded as is. */
358
+ handler: string;
359
+ /** The name of the handler's export. Defaults to `default`. */
360
+ export?: string;
361
+ /** The variables the handler cannot run without. Missing ones are named; nothing starts. */
362
+ required?: string[];
363
+ /** The variables holding the Axiom ingest token and dataset, to say where this run's logs go. */
364
+ logging?: {
365
+ /** The variable holding the Axiom ingest token. Only its presence is reported, never its value. */
366
+ tokenVar: string;
367
+ /** The variable holding the Axiom dataset the app's logs go to. */
368
+ datasetVar: string;
369
+ };
370
+ }
371
+ /** The `env` block: how the project's environment variables are named and documented. */
372
+ interface EnvConfig {
373
+ /**
374
+ * Namespace prefixes used by this project's env vars.
375
+ * Listed from least- to most-specific (cascade model — last wins).
376
+ * Tooling reads this to generate `.env.example`, validate required
377
+ * vars, and produce documentation.
378
+ *
379
+ * @example
380
+ * // Project-only prefix
381
+ * namespaces: ["CLI_TEMPLATE"]
382
+ *
383
+ * // Org-wide defaults + project-specific overrides
384
+ * namespaces: ["HOLOCRON", "MY_CLI"]
385
+ */
386
+ namespaces?: string[];
387
+ }
388
+ /**
389
+ * A single Chromatic project entry in a `verification.visualRegression`
390
+ * task's `chromatic-projects` config.
391
+ * Each entry produces one matrix job in CI, publishing to a separate Chromatic project.
392
+ *
393
+ * The `tokenName` maps to a repository secret named `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
394
+ * Additional fields correspond to chromaui/action inputs and are passed through directly.
395
+ *
396
+ * @see https://www.chromatic.com/docs/monorepos/
397
+ */
398
+ interface ChromaticProjectConfig {
399
+ /**
400
+ * Secret suffix. The CI job reads `CHROMATIC_PROJECT_TOKEN_<tokenName>`.
401
+ * Must be uppercase (e.g. `"WEB"`, `"UI"`).
402
+ */
403
+ tokenName: string;
404
+ /**
405
+ * Path to run the Chromatic build from, relative to the repo root.
406
+ * Typically the package directory (e.g. `"apps/web"`, `"packages/ui"`).
407
+ */
408
+ workingDir: string;
409
+ /**
410
+ * Script name to build Storybook. Defaults to `"build:storybook"`.
411
+ * Must accept `--output-dir` pass-through (use `turbo run … --` at root).
412
+ */
413
+ buildScript?: string;
414
+ /**
415
+ * Path to the Storybook folder relative to `workingDir`, for TurboSnap.
416
+ * Tells Chromatic where to find `.storybook/` when the Storybook config
417
+ * is in a subdirectory. Corresponds to `--storybook-base-dir`.
418
+ */
419
+ storybookBaseDir?: string;
420
+ /**
421
+ * Glob patterns of files/dirs that should NOT trigger a TurboSnap bailout
422
+ * when changed. Useful for ignoring non-UI changes in a monorepo
423
+ * (e.g. `"./packages/!(ui)/**"` to focus TurboSnap on the UI package).
424
+ * Corresponds to `--untraced`. Accepts a single glob string or array.
425
+ */
426
+ untraced?: string | string[];
427
+ /**
428
+ * Glob patterns matching story files to snapshot. When set, only matching
429
+ * stories are captured. Corresponds to `--only-story-files`.
430
+ * Cannot be combined with `onlyStoryNames`.
431
+ */
432
+ onlyStoryFiles?: string;
433
+ /**
434
+ * Exit with code 0 even when visual changes are detected.
435
+ * Useful during initial setup before baselines are approved.
436
+ * Corresponds to `--exit-zero-on-changes`.
437
+ */
438
+ exitZeroOnChanges?: boolean;
439
+ }
440
+ /**
441
+ * A single Storybook app in a deploy workflow config.
442
+ * `name` becomes the sandbox sub-path (`_site/sandbox/<name>/`).
443
+ * `path` is the working directory relative to the repo root; defaults to `"."` (repo root) when omitted.
444
+ */
445
+ interface StorybookDeployProject {
446
+ /** The sub-path under `_site/sandbox/` the Storybook app is published to. */
447
+ name?: string;
448
+ /** The app's working directory relative to the repo root; defaults to `"."`. */
449
+ path?: string;
450
+ }
451
+ /**
452
+ * Typed `with:` inputs for reusable workflows.
453
+ *
454
+ * `chromatic-projects` (on the `verification.visualRegression` task) takes a
455
+ * `ChromaticProjectConfig[]` directly; each entry's `untraced` glob list may
456
+ * be authored as an array and is newline-joined for you.
457
+ *
458
+ * `docs` / `storybook` are high-level deploy shorthand that `holocron repo setup`
459
+ * translates to `type` / `storybook-projects` before writing the thin caller.
460
+ * They also drive automatic `paths:` derivation so you never need to write
461
+ * `paths:` manually for deploy entries.
462
+ */
463
+ type WorkflowWithConfig = Record<string, unknown> & {
464
+ "chromatic-projects"?: ChromaticProjectConfig[];
465
+ /**
466
+ * Docs deployment shorthand. `true` uses the org-standard `docs/` directory;
467
+ * `{ path: "custom" }` uses a custom directory. Both derive a `paths:` entry automatically.
468
+ */
469
+ docs?: true | {
470
+ path: string;
471
+ };
472
+ /** Storybook apps to deploy alongside docs. Each entry's `path` is appended to `paths:`. */
473
+ storybook?: StorybookDeployProject[];
474
+ };
475
+ /**
476
+ * A `tasks` manifest entry in object form. A bare string entry is shorthand
477
+ * for `{ name, ci: true, local: true }`.
478
+ */
479
+ interface TaskEntryConfig {
480
+ /** The task's name. */
481
+ name: string;
482
+ /** Inputs passed to the task's reusable workflow. */
483
+ with?: WorkflowWithConfig;
484
+ /** Path filters for the generated workflow's triggers. */
485
+ paths?: string[];
486
+ /** Linters this task runs. */
487
+ linters?: string[];
488
+ /** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron run ci`. Default `true`. */
489
+ ci?: boolean;
490
+ /** Write a `package.json` script + let `holocron run <name>` resolve the task. Default `true`. */
491
+ local?: boolean;
492
+ /** The task's CI check context is a required status check + part of `holocron run ci`'s default run. */
493
+ required?: boolean;
494
+ /**
495
+ * Per-repo additions to this task's generated `turbo.json` entry —
496
+ * a separate channel from `with:` (that's the reusable *workflow's*
497
+ * inputs; this is local turbo cache config, unrelated). No-op for a
498
+ * task with no turbo fan-out config in the registry. Mirrors
499
+ * astromech's own `TaskEntry["turbo"]` — kept in sync by hand, since
500
+ * this package doesn't depend on astromech directly.
501
+ */
502
+ turbo?: {
503
+ /** Extra env vars turbo hashes into this task's cache key, appended to the registry default. */
504
+ passThroughEnv?: string[];
505
+ /**
506
+ * Extra input globs appended to the registry default's `inputs`
507
+ * (holocron#845) — for a package whose layout the registry
508
+ * default doesn't cover (e.g. a flat-layout package with no
509
+ * `src/` directory at all).
510
+ */
511
+ inputs?: string[];
512
+ /** Extra tasks this one waits for, appended to the registry default's `dependsOn` (turbo syntax: `"<package>#<task>"`). */
513
+ dependsOn?: string[];
514
+ };
515
+ }
516
+ /** A `holocron.config` as a user writes it; `defineConfig` types it. */
517
+ interface HolocronConfig {
518
+ /** Project name. Derived from package.json when absent. */
519
+ name?: string;
520
+ /** A one-line description of the project. */
521
+ description?: string;
522
+ /** Project homepage URL. Synced to package.json#homepage and the GitHub repo's website field by `holocron repo sync`. */
523
+ homepage?: string;
524
+ /**
525
+ * Active org name for namespaced keyring lookup. When set, token resolution
526
+ * tries `<service>.<org>` before the unnamespaced `<service>` fallback, so
527
+ * a single machine can hold credentials for multiple GitHub orgs without
528
+ * collision. Overridden by `--org` CLI flag or `HOLOCRON_ORG` env var.
529
+ */
530
+ org?: string;
531
+ /**
532
+ * Org canonical domain (e.g. `"theholocron.dev"`). Subdomains are derived
533
+ * from this — `preview: true` on a deploy workflow resolves the preview base
534
+ * domain as `preview.<domain>`, giving URLs like `<repo>-pr-<n>.<domain>`.
535
+ */
536
+ domain?: string;
537
+ /**
538
+ * Repository identity and metadata. When set, `PluginLoader` injects
539
+ * `repo.name` into every plugin's `RuntimeContext.repo` so plugins that
540
+ * need a repo (github, etc.) don't require `--repo` on every invocation.
541
+ * `--repo` on the command line still overrides.
542
+ */
543
+ repo?: RepoConfig;
544
+ /** Per-repo switches for the repo-validation checks. */
545
+ repoValidation?: RepoValidationConfig;
546
+ /**
547
+ * The task manifest — what this repo runs. Each entry is a task name
548
+ * (backed by a reusable workflow in `theholocron/.github`), or the object
549
+ * form to pass `with:` inputs. `@theholocron/astromech` reads this as the
550
+ * single source for `holocron run` / `holocron run ci` / the generated CI
551
+ * workflows / `package.json` scripts.
552
+ *
553
+ * Supported values (intent-facing vocabulary — epic #672, D3):
554
+ * "verification.unitTests" | "verification.visualRegression" | "verification.typeSafety" | "verification.performance" |
555
+ * "sourceQuality.staticAnalysis" | "sourceQuality.formatting" |
556
+ * "sourceQuality.structuredDataValidation" | "sourceQuality.deadCodeAnalysis" |
557
+ * "security.secretDetection" | "security.codeScanning" | "security.tokenExpiry" |
558
+ * "delivery.build" | "delivery.publish" | "delivery.deploy" | "delivery.bundleSize" |
559
+ * "platform.repoSync" | "platform.notifyCheck" | "platform.commitStandards" | "platform.repoValidation" |
560
+ * "knowledge.wiki" | "knowledge.docs" | "knowledge.components" |
561
+ * "review" | "tag" | "stale" | "greetings" | "dependencies" | "bookkeeping"
562
+ *
563
+ * `holocron repo setup` writes `.github/workflows/<name>.yml` for each entry,
564
+ * calling the corresponding reusable workflow in `theholocron/.github`.
565
+ * Files are overwritten on each run — they are generated artifacts.
566
+ *
567
+ * ### delivery.deploy / knowledge.docs / knowledge.components
568
+ * `delivery.deploy` uses `docs` and/or `storybook` in `with:` — setup
569
+ * derives `paths:` automatically. `docs: true` uses the org-standard
570
+ * `docs/` directory; `docs: { path: "custom" }` overrides it.
571
+ * `knowledge.docs` / `knowledge.components` are the same underlying
572
+ * mechanism, each dedicated to exactly one type — they imply the
573
+ * corresponding shorthand, so a repo using them never has to spell out
574
+ * `docs: true` / `storybook: […]` itself.
575
+ *
576
+ * ```ts
577
+ * // Docs only (standard layout)
578
+ * { name: "delivery.deploy", with: { docs: true } }
579
+ * // …or equivalently, the dedicated task:
580
+ * "knowledge.docs"
581
+ *
582
+ * // Docs + monorepo storybooks
583
+ * {
584
+ * name: "delivery.deploy",
585
+ * with: {
586
+ * docs: true,
587
+ * storybook: [
588
+ * { name: "web", path: "apps/web" },
589
+ * { name: "ui", path: "packages/ui" },
590
+ * ],
591
+ * },
592
+ * }
593
+ *
594
+ * // Non-standard docs location
595
+ * { name: "delivery.deploy", with: { docs: { path: "packages/site" } } }
596
+ * ```
597
+ *
598
+ * ### verification.visualRegression
599
+ * Its own task, not a `verification.unitTests` sub-job (holocron#394/#1062)
600
+ * — GitHub evaluates a job's `if:` before expanding its `strategy.matrix`,
601
+ * so no `chromatic-projects` default can make a *disabled* Chromatic job
602
+ * disappear from PR checks; only not generating the job at all does. Omit
603
+ * this task entirely for a repo that doesn't use Chromatic — no workflow,
604
+ * no job, no check, not even a skipped one.
605
+ *
606
+ * For a single-project repo, use a `CHROMATIC_PROJECT_TOKEN` repository
607
+ * secret with `tokenName: "default"`:
608
+ * ```ts
609
+ * {
610
+ * name: "verification.visualRegression",
611
+ * with: { "chromatic-projects": [{ tokenName: "default", workingDir: "." }] },
612
+ * }
613
+ * ```
614
+ *
615
+ * For monorepos with multiple Storybooks, list one entry per project:
616
+ * ```ts
617
+ * {
618
+ * name: "verification.visualRegression",
619
+ * with: {
620
+ * "chromatic-projects": [
621
+ * { tokenName: "WEB", workingDir: "apps/web" },
622
+ * { tokenName: "UI", workingDir: "packages/ui" },
623
+ * ],
624
+ * },
625
+ * }
626
+ * ```
627
+ * Each `tokenName` maps to a repository secret named
628
+ * `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
629
+ *
630
+ * @example
631
+ * ["sourceQuality.staticAnalysis", { "name": "delivery.publish", "with": { "run-build": false } }]
632
+ * { "name": "delivery.deploy", "with": { "docs": true } }
633
+ */
634
+ tasks?: Array<string | TaskEntryConfig>;
635
+ /**
636
+ * Opt out of `holocron repo sync`'s `package.json` script writes. Default `true`.
637
+ */
638
+ syncScripts?: boolean;
639
+ /**
640
+ * The command the synced `"holocron"` `package.json` script runs. Default
641
+ * `"holocron"` (the installed bin). This repo overrides it to run its own
642
+ * build (`"node cli/cli/dist/cli.mjs"`).
643
+ */
644
+ holocronScript?: string;
645
+ /**
646
+ * Required status-check contexts not backed by a `required` task (codecov
647
+ * gates, the bundle-build check, …). `holocron repo setup` appends these to the
648
+ * task-derived list from `astromech.requiredChecks()`.
649
+ */
650
+ extraRequiredChecks?: string[];
651
+ /**
652
+ * Git hooks `holocron repo setup` installs. `true` / `{ prePush: true }` writes
653
+ * `.husky/pre-push` (runs `holocron run ci` before every push); `false` /
654
+ * `{ prePush: false }` opts out. Omitted → on for `protection: "strict"`,
655
+ * off otherwise. `--hooks` / `--no-hooks` on `holocron repo setup` override.
656
+ */
657
+ hooks?: boolean | {
658
+ prePush?: boolean;
659
+ };
660
+ /** Which provider backs each capability. */
661
+ providers: RawProvidersConfig;
662
+ /** Applications in the repo. */
663
+ apps?: AppConfig[];
664
+ /** Settings for `holocron doctor`. */
665
+ doctor?: DoctorConfig;
666
+ /**
667
+ * Agent runtime that determines where skills are installed by `holocron repo setup`.
668
+ * Skills are installed to `.agents/skills/<name>/` (canonical) with a
669
+ * relative symlink at the agent-specific path:
670
+ * - `"claude"` → `.claude/skills/<name>` → `../../.agents/skills/<name>`
671
+ * - `"codex"` | `"gemini"` → logged as unsupported; skipped gracefully.
672
+ */
673
+ agent?: "claude" | "codex" | "gemini";
674
+ /**
675
+ * Skill names from `@theholocron/skills` to install during `holocron repo setup`.
676
+ * Installed paths are gitignored and managed by setup — do not commit them.
677
+ *
678
+ * @example
679
+ * ["git-safety", "pr-workflow", "commit-standards"]
680
+ */
681
+ skills?: string[];
682
+ /**
683
+ * GitHub Pages configuration. When present, `holocron repo setup` calls the
684
+ * Pages API using `HOLOCRON_DEPLOY_TOKEN` (requires `pages:write` + `repo` scope).
685
+ * When absent, Pages is left as-is.
686
+ *
687
+ * @example
688
+ * { build: "workflow", domain: "docs.theholocron.dev", https: true }
689
+ */
690
+ docs?: DocsConfig;
691
+ /**
692
+ * Environment variable namespace configuration.
693
+ * Declares the prefix(es) this project uses for its env vars so that
694
+ * tooling can generate `.env.example`, validate required vars, and
695
+ * produce accurate documentation without hard-coding prefix strings.
696
+ *
697
+ * @example
698
+ * { namespaces: ["HOLOCRON", "MY_CLI"] }
699
+ */
700
+ env?: EnvConfig;
701
+ /**
702
+ * Which environment the `credentials` providers (`providers.credentials`) read this machine's tokens from.
703
+ * The default for every provider; one provider can name its own with an `environment` option in its
704
+ * `providers.credentials` entry, which wins. The plugin never stores the name: the CLI passes it to `read`.
705
+ * Each provider needs one or the other when `providers.credentials` is set.
706
+ *
707
+ * @example
708
+ * { environment: "Holocron" }
709
+ */
710
+ credentials?: CredentialsConfig;
711
+ /**
712
+ * How `holocron dev` runs this directory's application locally behind a development tunnel: the vault
713
+ * environment its variables come from, the tunnel's name and hostname, the port and the command. Every field is
714
+ * optional here and can be given as a flag instead (a flag wins); `holocron dev` says which one is missing.
715
+ *
716
+ * @example
717
+ * { environment: "Sentinel - dev", tunnel: { name: "sentinel-dev", hostname: "sentinel-dev.theholocron.dev" } }
718
+ */
719
+ dev?: DevConfig;
720
+ /**
721
+ * The registered GitHub App instances `holocron doctor github-app` checks: GitHub cannot change an existing App's
722
+ * permissions or event subscriptions, so each instance is changed by hand and compared with its manifest here.
723
+ *
724
+ * @example
725
+ * [{ name: "Sentinel", manifest: "apps/sentinel/github-app.manifest.json", environment: "Sentinel" }]
726
+ */
727
+ githubApps?: GitHubAppConfig[];
728
+ /**
729
+ * The state that files an idea as an issue, for `holocron ideas sync`. Where the ideas are kept is
730
+ * `providers.ideas`; the older `ideas.dir` is deprecated and still read when `providers.ideas` is absent.
731
+ *
732
+ * @example
733
+ * { states: { file: "in-progress" } }
734
+ */
735
+ ideas?: IdeasConfig;
736
+ /**
737
+ * Structured-logging config. Only the level belongs here — Axiom
738
+ * credentials come from env vars, never a committed file.
739
+ *
740
+ * @example
741
+ * { level: "debug" }
742
+ */
743
+ log?: LogConfig;
744
+ /**
745
+ * CLI self-telemetry override layer. Env var (`HOLOCRON_TELEMETRY=false`)
746
+ * still wins; this is the committed way to opt a repo out or drop usage
747
+ * analytics while keeping error reporting.
748
+ *
749
+ * @example
750
+ * { enabled: false }
751
+ * { analytics: "none" }
752
+ */
753
+ telemetry?: TelemetryConfig;
754
+ /**
755
+ * ESLint bundle option overrides that Sentinel's centralized static-
756
+ * analysis check (holocron#849) can't otherwise see. Bucket 1 checks
757
+ * never read a PR's own committed files for config — this is the
758
+ * declared source of truth Sentinel reads instead, so its check stays
759
+ * in sync with what each package's own `eslint.config.ts` already
760
+ * enforces locally and in CI.
761
+ */
762
+ eslint?: EslintConfig;
763
+ }
764
+ /**
765
+ * Repo-root-relative directories treated as browser-targeted for eslint's
766
+ * node-builtins compatibility checks — mirrors
767
+ * `@theholocron/eslint-config`'s `library({ browserPackages })` option.
768
+ * Only needed for a package whose own `eslint.config.ts` already declares
769
+ * `browserPackages` (a deliberate outlier, not the norm — see that
770
+ * package's own config file for why).
771
+ *
772
+ * @example
773
+ * { browserPackages: ["packages/github-client/src/app-auth"] }
774
+ */
775
+ interface EslintConfig {
776
+ /** Repo-root-relative directories treated as browser-targeted. */
777
+ browserPackages?: string[];
778
+ }
779
+ /** A provider with its plugin package resolved. */
780
+ interface ResolvedTuple {
781
+ /** The provider's short name, e.g. `github`. */
782
+ provider: string;
783
+ /** Resolved package name (`@theholocron/holocron-plugin-<provider>` for short refs). */
784
+ packageName: string;
785
+ /** Options passed to the plugin. */
786
+ options: ProviderOptions;
787
+ }
788
+ /** A capability's resolved entry: one provider, or a list of providers. */
789
+ type ResolvedProviderEntry = {
790
+ cardinality: "single";
791
+ tuple: ResolvedTuple;
792
+ } | {
793
+ cardinality: "many";
794
+ tuples: ResolvedTuple[];
795
+ };
796
+ /** Resolved entries by capability. */
797
+ type ResolvedProvidersConfig = Partial<Record<CapabilityKey, ResolvedProviderEntry>>;
798
+ /** A `holocron.config` after `resolveConfig`: defaults applied and provider entries resolved. */
799
+ interface ResolvedHolocronConfig {
800
+ /** Project name. */
801
+ name: string;
802
+ /** A one-line description of the project. */
803
+ description?: string;
804
+ /** Project homepage URL. */
805
+ homepage?: string;
806
+ /** Org name. */
807
+ org?: string;
808
+ /** Org canonical domain. */
809
+ domain?: string;
810
+ /** Repository settings. */
811
+ repo?: RepoConfig;
812
+ /** Which repo-wide checks this repo turns on (`docsCoverage`), validated by `resolveConfig`. */
813
+ repoValidation?: RepoValidationConfig;
814
+ /** The task manifest. */
815
+ tasks?: Array<string | TaskEntryConfig>;
816
+ /** Whether to sync the generated `package.json` scripts. */
817
+ syncScripts?: boolean;
818
+ /** The script used to invoke the `holocron` binary. */
819
+ holocronScript?: string;
820
+ /** Required status checks not backed by a task. */
821
+ extraRequiredChecks?: string[];
822
+ /** Git hooks `holocron repo setup` installs. */
823
+ hooks?: boolean | {
824
+ prePush?: boolean;
825
+ };
826
+ /** Resolved provider entries by capability. */
827
+ providers: ResolvedProvidersConfig;
828
+ /** Applications in the repo; empty when none are declared. */
829
+ apps: AppConfig[];
830
+ /** Settings for `holocron doctor`; empty when none are declared. */
831
+ doctor: DoctorConfig;
832
+ /** The agent runtime skills are installed for. */
833
+ agent?: "claude" | "codex" | "gemini";
834
+ /** Names of the agent skills to install. */
835
+ skills?: string[];
836
+ /** Resolved Pages config. `build` is guaranteed present when this field exists. */
837
+ docs?: PagesConfig;
838
+ /** Environment-variable settings. */
839
+ env?: EnvConfig;
840
+ /** The environment the `credentials` providers read, validated by `resolveConfig`. */
841
+ credentials?: CredentialsConfig;
842
+ /** How `holocron dev` runs the application, validated by `resolveConfig`. */
843
+ dev?: DevConfig;
844
+ /** The GitHub App instances `doctor github-app` checks, validated by `resolveConfig`. */
845
+ githubApps?: GitHubAppConfig[];
846
+ /** The idea notes folder and filing state, validated by `resolveConfig`. */
847
+ ideas?: IdeasConfig;
848
+ /** Logging settings. */
849
+ log?: LogConfig;
850
+ /** Telemetry settings. */
851
+ telemetry?: TelemetryConfig;
852
+ /** ESLint settings. */
853
+ eslint?: EslintConfig;
854
+ }
855
+ /**
856
+ * Resolve `"github"` → `"@theholocron/holocron-plugin-github"`.
857
+ * Fully-qualified names (scoped or not) are honored verbatim, which
858
+ * is how third-party plugins published outside the org work.
859
+ */
860
+ declare function resolvePluginPackage(provider: string): string;
861
+ /** Resolves one capability's raw provider entry into single or multiple resolved tuples, checking it against the capability's cardinality. */
862
+ declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
863
+ /**
864
+ * The environment a `credentials` provider reads: its own `environment` option when it has one, else the shared
865
+ * `credentials.environment`, else `undefined`. The option lets each of several providers name its own (a 1Password
866
+ * Environment and an AWS secret are not called the same thing) without the plugin storing the name.
867
+ */
868
+ declare function credentialsEnvironment(tuple: ResolvedTuple, config: {
869
+ credentials?: CredentialsConfig;
870
+ }): string | undefined;
871
+ /** Validates a raw `holocron.config` and resolves its provider entries; throws `ConfigError` when `name` or `providers` is missing or an entry is malformed. */
872
+ declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
873
+ /** One entry of the `tasks` manifest: a task name or the object form. */
874
+ type TaskEntry = NonNullable<HolocronConfig["tasks"]>[number];
875
+ /** A single composable capability fragment. */
876
+ interface Capability {
877
+ /** Unique identifier — used for deduplication and dependency resolution. */
878
+ id: string;
879
+ /** Other capability IDs that must be present in the same compose() call. */
880
+ requires?: string[];
881
+ /** Task entries contributed by this capability. Merged by name; last writer wins. */
882
+ tasks?: TaskEntry[];
883
+ /** Provider config. Shallow-merged at the top level; later capabilities override per-key. */
884
+ providers?: RawProvidersConfig;
885
+ /**
886
+ * Required status-check contexts **not** backed by a `required` task
887
+ * (codecov gates, `Storybook Publish`, …). Unioned across all capabilities
888
+ * onto the top-level `extraRequiredChecks`. Task-backed checks come from
889
+ * `{ required: true }` task entries via `astromech.requiredChecks()`.
890
+ */
891
+ extraRequiredChecks?: string[];
892
+ /** Repo config fragment. Scalar fields: last writer wins. properties/topics/teams: merged. */
893
+ repo?: Partial<Omit<RepoConfig, "name">>;
894
+ /** Org name. Last writer wins. */
895
+ org?: string;
896
+ /** Org canonical domain. Last writer wins. */
897
+ domain?: string;
898
+ /** Docs site config. Last writer wins. */
899
+ docs?: DocsConfig;
900
+ }
901
+ /** The merged result of a compose() call. Spreads into defineConfig(). */
902
+ interface ComposedPreset {
903
+ /** Task entries merged from every capability, by name. */
904
+ tasks: TaskEntry[];
905
+ /** Provider config merged from every capability. */
906
+ providers: RawProvidersConfig;
907
+ /** Repo config merged from every capability. */
908
+ repo: Partial<Omit<RepoConfig, "name">>;
909
+ /** Non-task required-check contexts, unioned across capabilities. */
910
+ extraRequiredChecks: string[];
911
+ /** Org name; the last capability that sets it wins. */
912
+ org?: string;
913
+ /** Org canonical domain; the last capability that sets it wins. */
914
+ domain?: string;
915
+ /** Docs site config; the last capability that sets it wins. */
916
+ docs?: DocsConfig;
917
+ }
918
+ /** A loaded and resolved `holocron.config`. */
919
+ interface LoadedConfig {
920
+ /** The config after `resolveConfig`. */
921
+ resolved: ResolvedHolocronConfig;
922
+ /** Absolute path to the file the config was read from. */
923
+ filepath: string;
924
+ }
925
+ /** Returns the config unchanged; it exists to type and autocomplete a `holocron.config.ts`. */
926
+ declare const defineConfig: (config: HolocronConfig) => HolocronConfig;
927
+ /**
928
+ * Read + parse + resolve `holocron.config.*` starting from the given
929
+ * directory, walking up through ancestors to the nearest `.git` boundary
930
+ * when `cwd` itself has no match — every command is usable from any
931
+ * subdirectory of a repo, not only its exact root (see
932
+ * `@theholocron/datapad`'s own doc comment for the stop conditions).
933
+ * Throws `ConfigFileError` when nothing is found or a file cannot
934
+ * be loaded, or `ConfigError` when the config fails schema checks.
935
+ */
936
+ declare const loadConfig: (cwd: string) => Promise<LoadedConfig>;
937
+ /**
938
+ * Merge any number of capability fragments into a single preset object that
939
+ * spreads directly into `defineConfig()`.
940
+ *
941
+ * - Accepts individual capabilities or nested arrays (for bundle presets).
942
+ * - Deduplicates by `id` — when the same ID appears more than once, the last
943
+ * occurrence wins. This lets callers override bundle defaults by listing an
944
+ * explicit capability after the bundle.
945
+ * - Validates all `requires` at call time and throws `ConfigError` if any are
946
+ * unmet, listing every missing dependency in a single message.
947
+ *
948
+ * @example
949
+ * // docs-only site — no typecheck
950
+ * const preset = compose(node(), docs());
951
+ *
952
+ * // library with docs
953
+ * const preset = compose(node(), typecheck(), docs());
954
+ *
955
+ * // nextjs() is a bundle that returns Capability[]
956
+ * const preset = compose(node(), nextjs());
957
+ */
958
+ declare const compose: (...args: (Capability | Capability[])[]) => ComposedPreset;
959
+ /**
960
+ * Derived custom-properties (#677). Unlike the existing 6 GitHub
961
+ * custom-properties fields (`lifecycle`, `open_source`, `runtime_environment`,
962
+ * `uses_external_packages`, `monorepo`, `branch_protection_level`) — which
963
+ * mirror what `holocron.config.ts` already states explicitly — these four are
964
+ * *derived*: signal that isn't an explicit config field today (framework
965
+ * choice, repo archetype, capability drift). See
966
+ * `docs/wiki/specifications/tech-holocron-platform.spec.md` → "Custom-properties sync — field
967
+ * definitions (#677)" for the full design.
968
+ */
969
+ type HolocronProfile = "library" | "cli" | "plugin" | "template" | "app" | "docs" | "platform";
970
+ /** The `package.json` shape profile derivation reads — `@theholocron/pkg-utils`'s `PackageJson`, under the name Sentinel already imports. */
971
+ type PackageJsonLike = PackageJson;
972
+ /** What profile derivation reads to decide a repo's archetype. */
973
+ interface DeriveProfileInput {
974
+ /** The repo's root `package.json`, or `null` when it has none. */
975
+ rootPackageJson: PackageJsonLike | null;
976
+ /** The repository name, without the owner. */
977
+ repoName: string;
978
+ /** Whether the repo is a monorepo with several workspace packages. */
979
+ isMonorepo: boolean;
980
+ /** `packages/*` package.json contents, monorepo repos only — used to find the primary published artifact. */
981
+ workspacePackageJsons: PackageJsonLike[];
982
+ }
983
+ /** One of the framework and build-tool names `deriveStack()` detects (`next`, `vite`, ...), derived from `KNOWN_STACK_DEPS`. */
984
+ type StackName = (typeof KNOWN_STACK_DEPS)[number];
985
+ /**
986
+ * Repo archetype, in priority order:
987
+ * 1. `*-template` repo name → `template` (independent of package shape).
988
+ * 2. Monorepo whose primary published artifact is a CLI (some workspace
989
+ * package has `bin`) → `platform` — matches `holocron` itself: the CLI is
990
+ * the deliverable, the plugin packages are supporting infrastructure for
991
+ * it, not separate products.
992
+ * 3. Monorepo with no CLI but at least one non-private workspace package →
993
+ * `library` — matches `clients`/`configs`/`utils`/`themes`/
994
+ * `observability`: a family of published packages, none of them a CLI.
995
+ * Checked *before* falling into the root-package branch below, because
996
+ * these repos' own root `package.json` is private and often carries
997
+ * `@theholocron/astro-config` for a docs site built from the monorepo
998
+ * root — without this check they'd wrongly resolve to `docs` off that
999
+ * root-level signal alone, when the docs site is a secondary concern of
1000
+ * a library collection, not what the repo fundamentally is.
1001
+ * 4. Single-package repo with `package.json#bin` → `cli`.
1002
+ * 5. Docs-only site (astro/starlight present, root package private, no
1003
+ * publishable exports) → `docs`.
1004
+ * 6. Private, non-publishable, non-docs → `app`.
1005
+ * 7. Otherwise, a single publishable package → `library`.
1006
+ */
1007
+ declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
1008
+ /** The framework and build-tool names `deriveStack()` can detect, in the order it lists them; `StackName` is derived from it. */
1009
+ declare const KNOWN_STACK_DEPS: readonly ["next", "vite", "astro", "tsdown", "rollup", "webpack", "storybook", "vitest", "playwright", "turbo"];
1010
+ /**
1011
+ * Detected build/framework tooling — the literal "does this repo need
1012
+ * next/vite/tsdown" signal `holocron.config.ts` has no field for today
1013
+ * (framework choice isn't a config concept, unlike `providers`/`tasks`).
1014
+ * Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
1015
+ * frameworks show up rather than trying to detect anything on npm.
1016
+ */
1017
+ declare function deriveStack(pkg: PackageJsonLike | null): StackName[];
1018
+ /** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
1019
+ declare function deriveCapabilities(providers: ResolvedProvidersConfig | undefined): string[];
1020
+ /** Whether a repo's capabilities include the required baseline (`source` and `ci`); `non-compliant` means drift. */
1021
+ declare function deriveCompliance(capabilities: readonly string[]): "compliant" | "non-compliant";
1022
+ /**
1023
+ * The Phase B refinement `deriveCompliance()`'s own doc comment names —
1024
+ * *why* a repo is non-compliant, not just that it is. `[]` when compliant.
1025
+ * Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
1026
+ * table, not two independently-maintained baselines.
1027
+ */
1028
+ declare function missingCapabilities(capabilities: readonly string[]): string[];
1029
+ /**
1030
+ * Reads each workspace package's actual `package.json` content (not just
1031
+ * `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
1032
+ * `platform` detection needs `bin`, which that helper doesn't carry).
1033
+ * Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
1034
+ * own soft-fail behavior.
1035
+ */
1036
+ declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
2
1037
  /**
3
1038
  * Capability interfaces — the contracts that providers implement.
4
1039
  *
@@ -1153,10 +2188,17 @@ interface Dns extends ProviderIdentity {
1153
2188
  interface Errors extends ProviderIdentity {
1154
2189
  /** Identifies this provider as the `errors` capability. */
1155
2190
  readonly key: "errors";
1156
- /** Returns the env var names the app reads at runtime for this provider. */
2191
+ /**
2192
+ * Returns the env var names the app reads at runtime for this provider.
2193
+ * `envKeys` are always pushed; the optional `frameworkEnvKeys` maps a
2194
+ * framework name, as `deriveStack()` spells it (`next`), to the extra keys
2195
+ * pushed only when that framework is in the repo's detected stack (the root
2196
+ * `package.json` and every workspace package's).
2197
+ */
1157
2198
  describe(): Promise<{
1158
2199
  provider: string;
1159
2200
  envKeys: string[];
2201
+ frameworkEnvKeys?: Partial<Record<StackName, string[]>>;
1160
2202
  }>;
1161
2203
  /**
1162
2204
  * Reachability probe. `null` means the check genuinely can't run right
@@ -2967,4 +4009,4 @@ declare class WebhookVerificationError extends Error {
2967
4009
  }
2968
4010
  /** Whether `key` is a capability that can have several providers active at once. */
2969
4011
  declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
2970
- export { DnsRecord as $, NotificationsForumTag as $t, Cardinality as A, SourceSecurity as An, LifecycleResult as At, DeployFunctionConfig as B, TrackerDoctorReport as Bn, MonitoringAssertionComparison as Bt, BoardStatusCategory as C, Secrets as Cn, IssueOrder as Ct, BoardView as D, SourceFile as Dn, IssueSelector as Dt, BoardTemplateFile as E, SourceBranch as En, IssueSearchFilter as Et, CiRunStatus as F, SyncResult as Fn, MonitoringAlertChannelInput as Ft, DeploymentProject as G, WebhookDashboardInfo as Gn, MoveReport as Gt, DeployScriptConfig as H, TunnelRoute as Hn, MonitoringCheck as Ht, ConnectionStringOptions as I, TeamEntry as In, MonitoringAlertChannelResult as It, DeploymentTarget as J, WikiProxyConfig as Jn, NotificationsAccess as Jt, DeploymentProjectSettings as K, Wiki as Kn, NormalizedAuthUser as Kt, CreateAuthUserInput as L, TeamPermission as Ln, MonitoringAlertChannelState as Lt, Ci as M, StatusCategory as Mn, Logs as Mt, CiRun as N, Storage as Nn, LogsDataset as Nt, CapabilityImpls as O, SourceRepoInfo as On, Issues as Ot, CiRunFilter as P, StorageBranch as Pn, Monitoring as Pt, Dns as Q, NotificationsEveryoneLayout as Qt, Credentials as R, Tooling as Rn, MonitoringAlertSettings as Rt, BoardStatus as S, SecretScope as Sn, IssueComment as St, BoardTemplate as T, Source as Tn, IssueRecord as Tt, DeployScriptResult as U, Tunnels as Un, MonitoringCheckInput as Ut, DeployFunctionResult as V, TrackerUser as Vn, MonitoringAssertionSource as Vt, Deployment as W, Vault as Wn, MonitoringHttpMethod as Wt, DiscussionPatch as X, Workers as Xn, NotificationsChannelLayout as Xt, DeploymentTrigger as Y, WorkerScriptState as Yn, NotificationsApplicationLayout as Yt, DiscussionPost as Z, NotificationsDelivery as Zt, BoardFieldType as _, RelayState as _n, Ideas as _t, REQUIRED_CAPABILITIES as a, NotificationsPicture as an, EnsureReport as at, BoardRule as b, ResolvedCapability as bn, InspectRelayInput as bt, AddedItem as c, NotificationsServerLayout as cn, EnsuredDiscussion as ct, AuthDescription as d, NotificationsWelcomeLayout as dn, Environment as dt, NotificationsLayout as en, DnsRecordRequest as et, AuthEvent as f, PagesConfig as fn, EnvironmentReviewer as ft, BoardField as g, PullRequest as gn, IdeaRecord as gt, AuthUser as h, ProviderIdentity as hn, ExportInfo as ht, ProviderApiError as i, NotificationsOnboardingLayout as in, EnsureRelayResult as it, CardinalityFor as j, SourceTeamMember as jn, LifecycleSlot as jt, CapabilityKey as k, SourceRulesetDetail as kn, LabelDef as kt, Analytics as l, NotificationsSignIn as ln, EnsuredResource as lt, AuthIdentity as m, Projects as mn, Errors as mt, ElevationRequiredError as n, NotificationsMember as nn, EnsureDiscussionInput as nt, WebhookVerificationError as o, NotificationsPinnedLayout as on, EnsureResult as ot, AuthEventType as p, ParseWebhookInput as pn, Environments as pt, DeploymentRecord as q, WikiProvisionOpts as qn, Notifications as qt, MissingTokenError as r, NotificationsMonitoringFeed as rn, EnsureRelayInput as rt, isMulti as s, NotificationsPrsFeed as sn, EnsureWebhookResult as st, CARDINALITY as t, NotificationsLinksLayout as tn, DnsRecordType as tt, Auth as u, NotificationsSignedIn as un, EnsuredTunnel as ut, BoardItem as v, RepoRef as vn, ImportOptions as vt, BoardSummary as w, ServerInspection as wn, IssuePriority as wt, BoardState as x, Ruleset as xn, Issue as xt, BoardItemInput as y, RepoSettings as yn, ImportResult as yt, CredentialsInspection as z, ToolingDoctorReport as zn, MonitoringAssertion as zt };
4012
+ export { DnsRecord as $, deriveCompliance as $n, StorybookDeployProject as $r, NotificationsForumTag as $t, Cardinality as A, SourceSecurity as An, EslintConfig as Ar, LifecycleResult as At, DeployFunctionConfig as B, TrackerDoctorReport as Bn, RepoConfig as Br, MonitoringAssertionComparison as Bt, BoardStatusCategory as C, Secrets as Cn, ChromaticProjectConfig as Cr, IssueOrder as Ct, BoardView as D, SourceFile as Dn, DocsConfig as Dr, IssueSelector as Dt, BoardTemplateFile as E, SourceBranch as En, DevServeConfig as Er, IssueSearchFilter as Et, CiRunStatus as F, SyncResult as Fn, MultiEntry as Fr, MonitoringAlertChannelInput as Ft, DeploymentProject as G, WebhookDashboardInfo as Gn, RepoValidationConfig as Gr, MoveReport as Gt, DeployScriptConfig as H, TunnelRoute as Hn, RepoProtection as Hr, MonitoringCheck as Ht, ConnectionStringOptions as I, TeamEntry as In, OrgConfig as Ir, MonitoringAlertChannelResult as It, DeploymentTarget as J, WikiProxyConfig as Jn, ResolvedHolocronConfig as Jr, NotificationsAccess as Jt, DeploymentProjectSettings as K, Wiki as Kn, RepoVariables as Kr, NormalizedAuthUser as Kt, CreateAuthUserInput as L, TeamPermission as Ln, ProviderOptions as Lr, MonitoringAlertChannelState as Lt, Ci as M, StatusCategory as Mn, HolocronConfig as Mr, Logs as Mt, CiRun as N, Storage as Nn, IdeasConfig as Nr, LogsDataset as Nt, CapabilityImpls as O, SourceRepoInfo as On, DoctorConfig as Or, Issues as Ot, CiRunFilter as P, StorageBranch as Pn, LogConfig as Pr, Monitoring as Pt, Dns as Q, deriveCapabilities as Qn, SingleEntry as Qr, NotificationsEveryoneLayout as Qt, Credentials as R, Tooling as Rn, RawProviderEntry as Rr, MonitoringAlertSettings as Rt, BoardStatus as S, SecretScope as Sn, CapabilityConfigPackage as Sr, IssueComment as St, BoardTemplate as T, Source as Tn, DevConfig as Tr, IssueRecord as Tt, DeployScriptResult as U, Tunnels as Un, RepoSecrets as Ur, MonitoringCheckInput as Ut, DeployFunctionResult as V, TrackerUser as Vn, RepoProperties as Vr, MonitoringAssertionSource as Vt, Deployment as W, Vault as Wn, RepoSecretsSync as Wr, MonitoringHttpMethod as Wt, DiscussionPatch as X, Workers as Xn, ResolvedProvidersConfig as Xr, NotificationsChannelLayout as Xt, DeploymentTrigger as Y, WorkerScriptState as Yn, ResolvedProviderEntry as Yr, NotificationsApplicationLayout as Yt, DiscussionPost as Z, KNOWN_STACK_DEPS as Zn, ResolvedTuple as Zr, NotificationsDelivery as Zt, BoardFieldType as _, RelayState as _n, credentialsEnvironment as _r, Ideas as _t, REQUIRED_CAPABILITIES as a, NotificationsPicture as an, HolocronProfile as ar, EnsureReport as at, BoardRule as b, ResolvedCapability as bn, resolvePluginPackage as br, InspectRelayInput as bt, AddedItem as c, NotificationsServerLayout as cn, ConfigFileError as cr, EnsuredDiscussion as ct, AuthDescription as d, NotificationsWelcomeLayout as dn, loadConfig as dr, Environment as dt, TaskEntryConfig as ei, NotificationsLayout as en, deriveProfile as er, DnsRecordRequest as et, AuthEvent as f, PagesConfig as fn, LoadedConfig as fr, EnvironmentReviewer as ft, BoardField as g, PullRequest as gn, ConfigError$1 as gr, IdeaRecord as gt, AuthUser as h, ProviderIdentity as hn, TaskEntry as hr, ExportInfo as ht, ProviderApiError as i, NotificationsOnboardingLayout as in, DeriveProfileInput as ir, EnsureRelayResult as it, CardinalityFor as j, SourceTeamMember as jn, GitHubAppConfig as jr, LifecycleSlot as jt, CapabilityKey as k, SourceRulesetDetail as kn, EnvConfig as kr, LabelDef as kt, Analytics as l, NotificationsSignIn as ln, compose as lr, EnsuredResource as lt, AuthIdentity as m, Projects as mn, ComposedPreset as mr, Errors as mt, ElevationRequiredError as n, WorkflowWithConfig as ni, NotificationsMember as nn, missingCapabilities as nr, EnsureDiscussionInput as nt, WebhookVerificationError as o, NotificationsPinnedLayout as on, PackageJsonLike as or, EnsureResult as ot, AuthEventType as p, ParseWebhookInput as pn, Capability as pr, Environments as pt, DeploymentRecord as q, WikiProvisionOpts as qn, RepoVariablesSync as qr, Notifications as qt, MissingTokenError as r, NotificationsMonitoringFeed as rn, readWorkspacePackageJsons as rr, EnsureRelayInput as rt, isMulti as s, NotificationsPrsFeed as sn, StackName as sr, EnsureWebhookResult as st, CARDINALITY as t, TelemetryConfig as ti, NotificationsLinksLayout as tn, deriveStack as tr, DnsRecordType as tt, Auth as u, NotificationsSignedIn as un, defineConfig as ur, EnsuredTunnel as ut, BoardItem as v, RepoRef as vn, resolveConfig as vr, ImportOptions as vt, BoardSummary as w, ServerInspection as wn, CredentialsConfig as wr, IssuePriority as wt, BoardState as x, Ruleset as xn, AppConfig as xr, Issue as xt, BoardItemInput as y, RepoSettings as yn, resolveEntry as yr, ImportResult as yt, CredentialsInspection as z, ToolingDoctorReport as zn, RawProvidersConfig as zr, MonitoringAssertion as zt };