@theholocron/cli 5.0.0-alpha.245 → 5.0.0-alpha.246

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/dist/index.d.mts CHANGED
@@ -1,8 +1,9 @@
1
- import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, ElevationRequiredError, EnsureRelayInput, EnsureRelayResult, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti } from "./plugin/capabilities.mjs";
1
+ import { $ as Logs, $t as Workers, A as DeploymentProjectSettings, At as RepoSettings, B as EnsureResult, Bt as Storage, C as CreateAuthUserInput, Ct as NotificationsSignedIn, D as DeployScriptResult, Dt as ProviderIdentity, E as DeployScriptConfig, Et as ParseWebhookInput, F as DnsRecord, Ft as ServerInspection, G as Environments, Gt as ToolingDoctorReport, H as EnsuredResource, Ht as TeamEntry, I as DnsRecordRequest, It as Source, J as IssueSearchFilter, Jt as Vault, K as Errors, Kt as TrackerDoctorReport, L as DnsRecordType, Lt as SourceFile, M as DeploymentTarget, Mt as Ruleset, N as DeploymentTrigger, Nt as SecretScope, O as Deployment, Ot as PullRequest, P as Dns, Pt as Secrets, Q as LifecycleSlot, Qt as WikiProxyConfig, R as EnsureRelayInput, Rt as SourceTeamMember, S as ConnectionStringOptions, St as NotificationsSignIn, T as DeployFunctionResult, Tt as PagesConfig, U as Environment, Ut as TeamPermission, V as EnsureWebhookResult, Vt as StorageBranch, W as EnvironmentReviewer, Wt as Tooling, X as LabelDef, Xt as Wiki, Y as Issues, Yt as WebhookDashboardInfo, Z as LifecycleResult, Zt as WikiProvisionOpts, _ as CardinalityFor, _t as NotificationsLinksLayout, a as WebhookVerificationError, at as MonitoringAssertionSource, b as CiRunFilter, bt as NotificationsPinnedLayout, c as Auth, ct as MonitoringHttpMethod, d as AuthEventType, dt as NotificationsAccess, et as Monitoring, f as AuthIdentity, ft as NotificationsApplicationLayout, g as Cardinality, gt as NotificationsLayout, h as CapabilityKey, ht as NotificationsEveryoneLayout, i as REQUIRED_CAPABILITIES, it as MonitoringAssertionComparison, j as DeploymentRecord, jt as ResolvedCapability, k as DeploymentProject, kt as RepoRef, l as AuthDescription, lt as NormalizedAuthUser, m as CapabilityImpls, mt as NotificationsDelivery, n as ElevationRequiredError, nt as MonitoringAlertChannelResult, o as isMulti, ot as MonitoringCheck, p as AuthUser, pt as NotificationsChannelLayout, q as Issue, qt as TrackerUser, r as ProviderApiError, rt as MonitoringAssertion, s as Analytics, st as MonitoringCheckInput, t as CARDINALITY, tt as MonitoringAlertChannelInput, u as AuthEvent, ut as Notifications, v as Ci, vt as NotificationsMember, w as DeployFunctionConfig, wt as NotificationsWelcomeLayout, x as CiRunStatus, xt as NotificationsServerLayout, y as CiRun, yt as NotificationsOnboardingLayout, z as EnsureRelayResult, zt as StatusCategory } from "./index-DvQb3PcL.mjs";
2
+ import { A as SingleEntry, C as RepoProperties, D as ResolvedProviderEntry, E as ResolvedHolocronConfig, M as TaskEntryConfig, N as TelemetryConfig, O as ResolvedProvidersConfig, P as WorkflowWithConfig, S as RepoConfig, T as RepoVariables, _ as LogConfig, a as ConfigError, b as RawProviderEntry, c as resolvePluginPackage, d as ChromaticProjectConfig, f as DocsConfig, g as HolocronConfig, h as EslintConfig, i as TaskEntry, j as StorybookDeployProject, k as ResolvedTuple, l as AppConfig, m as EnvConfig, n as Capability, o as resolveConfig, p as DoctorConfig, r as ComposedPreset, s as resolveEntry, t as compose, u as CapabilityConfigPackage, v as MultiEntry, w as RepoProtection, x as RawProvidersConfig, y as ProviderOptions } from "./index-Cd_9v4b8.mjs";
2
3
  import { AuthError, RequestOptions, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
3
4
  import { PackageJson } from "@theholocron/pkg-utils";
4
5
  import { ConfigFileError } from "@theholocron/datapad";
5
- import { LogLevel } from "@theholocron/observability/core";
6
+ import "@theholocron/observability/core";
6
7
  import { WorkspacePackage } from "@theholocron/astromech";
7
8
  //#region src/auth/auth-resolver/auth-resolver.type.d.ts
8
9
  type ResolveTokenConfig = Omit<ResolveTokenConfig$1, "getKeyringToken">;
@@ -85,637 +86,6 @@ interface VerifyTokenFailure {
85
86
  }
86
87
  type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
87
88
  //#endregion
88
- //#region src/config/config/config.type.d.ts
89
- /** Structured-logging config. The Axiom **token** never lives here — only in
90
- * env vars or the OS keyring — but the non-secret dataset name may. */
91
- interface LogConfig {
92
- /**
93
- * Default log level. The lowest-priority level source: `--verbose` /
94
- * `--quiet` and `HOLOCRON_LOG_LEVEL` both outrank it.
95
- */
96
- level?: LogLevel;
97
- /**
98
- * Axiom log-shipping. Set `axiom.dataset` to opt local runs into Axiom
99
- * without exporting `HOLOCRON_AXIOM_DATASET` — the CLI then pairs it with
100
- * the token from `HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN` or the OS keyring
101
- * (`holocron auth set axiom[.<org>] <TOKEN>`). Env vars still win. In CI,
102
- * prefer the `HOLOCRON_AXIOM_DATASET` variable.
103
- */
104
- axiom?: {
105
- /** Target Axiom dataset, e.g. `"holocron-local"`. */
106
- dataset?: string;
107
- };
108
- }
109
- /**
110
- * CLI self-telemetry config — the committed, reviewable override layer over the
111
- * env-var + shipped-fallback activation (ADR-0007 / ADR-0008). No secret lives
112
- * here; the Sentry DSN and PostHog key come from env vars or ship as fallbacks.
113
- *
114
- * Precedence: `HOLOCRON_TELEMETRY=false` (env) → `telemetry.enabled` (this) →
115
- * default on. `enabled` never *re-enables* what the env var turned off.
116
- */
117
- interface TelemetryConfig {
118
- /**
119
- * Repo-level opt-out — the committed peer of `HOLOCRON_TELEMETRY=false`.
120
- * `false` installs the no-op sinks for the whole run. Default on.
121
- */
122
- enabled?: boolean;
123
- /**
124
- * Usage-analytics provider. `"none"` disables PostHog usage analytics while
125
- * leaving error reporting (Sentry) untouched. Default `"posthog"`.
126
- */
127
- analytics?: "posthog" | "none";
128
- }
129
- type ProviderOptions = Record<string, unknown>;
130
- /**
131
- * The shape a capability config package's default export must satisfy.
132
- * Config packages let teams share a pre-bundled provider + options across
133
- * repos (Level 1 of the shareable-configs story, issue #75).
134
- *
135
- * @example
136
- * // @acme/holocron-vault/index.ts
137
- * import type { CapabilityConfigPackage } from '@theholocron/cli'
138
- * export default {
139
- * provider: '1password',
140
- * options: { vault: 'acme-app' },
141
- * } satisfies CapabilityConfigPackage
142
- */
143
- interface CapabilityConfigPackage {
144
- provider: string;
145
- options?: ProviderOptions;
146
- }
147
- type SingleEntry = string | [provider: string, options: ProviderOptions];
148
- type MultiEntry = Array<string | [provider: string, options: ProviderOptions]>;
149
- type RawProviderEntry = SingleEntry | MultiEntry;
150
- type RawProvidersConfig = Partial<Record<CapabilityKey, RawProviderEntry>>;
151
- type RepoProtection = "balanced" | "strict" | "none";
152
- /**
153
- * Raw `docs` config as written by the user. `build` is optional so the
154
- * field can be declared without committing to a build type yet; setup
155
- * will error if `docs` is present but `build` is absent.
156
- */
157
- interface DocsConfig {
158
- /**
159
- * GitHub Pages build source.
160
- * "workflow" → GitHub Actions (PUT { build_type: "workflow" })
161
- * "branch" → classic gh-pages branch (PUT { build_type: "legacy", source: { branch: "gh-pages", path: "/" } })
162
- * When absent, Pages is not managed by `holocron repo setup`.
163
- */
164
- build?: "workflow" | "branch";
165
- /**
166
- * Custom domain / CNAME (e.g. "docs.theholocron.dev").
167
- * When set and `homepage` is not explicitly provided, setup derives
168
- * `homepage` as `https://{domain}/` for package.json and the repo website field.
169
- */
170
- domain?: string;
171
- /** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
172
- https?: boolean;
173
- }
174
- interface RepoProperties {
175
- lifecycle?: "active" | "experimental" | "deprecated";
176
- open_source?: boolean;
177
- runtime_environment?: "node" | "browser" | "universal" | "none";
178
- uses_external_packages?: boolean;
179
- }
180
- /**
181
- * GitHub Actions variables, declared so a workflow that reads `vars.NAME` finds it. Values are plain text, so
182
- * never put a secret here; secrets go through the `secrets` capability.
183
- */
184
- interface RepoVariables {
185
- /** Repository-level variables. */
186
- repo?: Record<string, string>;
187
- /**
188
- * Organization-level variables. A bare string is visible to every repository; `visibility: "private"` limits it
189
- * to private ones. Declare these in one repo only (the one that owns the org's configuration).
190
- */
191
- org?: Record<string, string | {
192
- value: string;
193
- visibility?: "all" | "private";
194
- }>;
195
- /** Delete variables that exist but are not declared here. Off by default: they are left alone. */
196
- prune?: boolean;
197
- }
198
- interface RepoConfig {
199
- /** "owner/name" — the GitHub repository coordinate. Derived from the git remote when absent. */
200
- name?: string;
201
- /**
202
- * GitHub's repo-level default branch (`HEAD`) — what a fresh clone checks
203
- * out, what `gh pr create`/the compare UI target by default, and what
204
- * Sentinel's `validateConfig()` reads (D6: the App only ever reads config
205
- * from the repo's default branch, never a PR ref, as a security boundary
206
- * — never widen that to read PR branches instead of fixing this field).
207
- * Synced by `holocron repo setup`. Omit to leave GitHub's current setting
208
- * untouched — most repos never need this. Exists for a repo using a
209
- * `main`/`alpha` prerelease-channel split (CLAUDE.md's Releases section)
210
- * where active development happens on a non-`main` branch: set this to
211
- * that branch so Sentinel validates against what's actually being
212
- * developed, then change it back once that branch merges to `main` for a
213
- * stable cut and stops being the active branch.
214
- */
215
- defaultBranch?: string;
216
- /**
217
- * Branch protection preset applied by `holocron repo setup`. When omitted,
218
- * no protection is applied and no `branch_protection_level` property is set.
219
- * Required-status-check contexts for `"strict"` are derived from the task
220
- * manifest — `{ required: true }` tasks + top-level `extraRequiredChecks`
221
- * (see `astromech.requiredChecks()`).
222
- */
223
- protection?: RepoProtection;
224
- /**
225
- * GitHub teams granted repository access. Synced by `holocron repo setup`, which
226
- * also writes `.github/CODEOWNERS` for teams with write-or-higher permission.
227
- * String shorthand defaults to `push` (Write).
228
- */
229
- teams?: TeamEntry[];
230
- /** GitHub topics set on the repository. */
231
- topics?: string[];
232
- /** GitHub custom properties synced to the org dashboard. */
233
- properties?: RepoProperties;
234
- /** GitHub Actions variables reconciled by `holocron repo setup`. */
235
- variables?: RepoVariables;
236
- }
237
- interface AppConfig {
238
- name: string;
239
- path: string;
240
- kind?: string;
241
- }
242
- interface DoctorConfig {
243
- checks?: string[];
244
- }
245
- interface EnvConfig {
246
- /**
247
- * Namespace prefixes used by this project's env vars.
248
- * Listed from least- to most-specific (cascade model — last wins).
249
- * Tooling reads this to generate `.env.example`, validate required
250
- * vars, and produce documentation.
251
- *
252
- * @example
253
- * // Project-only prefix
254
- * namespaces: ["CLI_TEMPLATE"]
255
- *
256
- * // Org-wide defaults + project-specific overrides
257
- * namespaces: ["HOLOCRON", "MY_CLI"]
258
- */
259
- namespaces?: string[];
260
- }
261
- /**
262
- * A single Chromatic project entry in a `verification.visualRegression`
263
- * task's `chromatic-projects` config.
264
- * Each entry produces one matrix job in CI, publishing to a separate Chromatic project.
265
- *
266
- * The `tokenName` maps to a repository secret named `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
267
- * Additional fields correspond to chromaui/action inputs and are passed through directly.
268
- *
269
- * @see https://www.chromatic.com/docs/monorepos/
270
- */
271
- interface ChromaticProjectConfig {
272
- /**
273
- * Secret suffix. The CI job reads `CHROMATIC_PROJECT_TOKEN_<tokenName>`.
274
- * Must be uppercase (e.g. `"WEB"`, `"UI"`).
275
- */
276
- tokenName: string;
277
- /**
278
- * Path to run the Chromatic build from, relative to the repo root.
279
- * Typically the package directory (e.g. `"apps/web"`, `"packages/ui"`).
280
- */
281
- workingDir: string;
282
- /**
283
- * Script name to build Storybook. Defaults to `"build:storybook"`.
284
- * Must accept `--output-dir` pass-through (use `turbo run … --` at root).
285
- */
286
- buildScript?: string;
287
- /**
288
- * Path to the Storybook folder relative to `workingDir`, for TurboSnap.
289
- * Tells Chromatic where to find `.storybook/` when the Storybook config
290
- * is in a subdirectory. Corresponds to `--storybook-base-dir`.
291
- */
292
- storybookBaseDir?: string;
293
- /**
294
- * Glob patterns of files/dirs that should NOT trigger a TurboSnap bailout
295
- * when changed. Useful for ignoring non-UI changes in a monorepo
296
- * (e.g. `"./packages/!(ui)/**"` to focus TurboSnap on the UI package).
297
- * Corresponds to `--untraced`. Accepts a single glob string or array.
298
- */
299
- untraced?: string | string[];
300
- /**
301
- * Glob patterns matching story files to snapshot. When set, only matching
302
- * stories are captured. Corresponds to `--only-story-files`.
303
- * Cannot be combined with `onlyStoryNames`.
304
- */
305
- onlyStoryFiles?: string;
306
- /**
307
- * Exit with code 0 even when visual changes are detected.
308
- * Useful during initial setup before baselines are approved.
309
- * Corresponds to `--exit-zero-on-changes`.
310
- */
311
- exitZeroOnChanges?: boolean;
312
- }
313
- /**
314
- * A single Storybook app in a deploy workflow config.
315
- * `name` becomes the sandbox sub-path (`_site/sandbox/<name>/`).
316
- * `path` is the working directory relative to the repo root; defaults to `"."` (repo root) when omitted.
317
- */
318
- interface StorybookDeployProject {
319
- name?: string;
320
- path?: string;
321
- }
322
- /**
323
- * Typed `with:` inputs for reusable workflows.
324
- *
325
- * `chromatic-projects` (on the `verification.visualRegression` task) takes a
326
- * `ChromaticProjectConfig[]` directly; each entry's `untraced` glob list may
327
- * be authored as an array and is newline-joined for you.
328
- *
329
- * `docs` / `storybook` are high-level deploy shorthand that `holocron repo setup`
330
- * translates to `type` / `storybook-projects` before writing the thin caller.
331
- * They also drive automatic `paths:` derivation so you never need to write
332
- * `paths:` manually for deploy entries.
333
- */
334
- type WorkflowWithConfig = Record<string, unknown> & {
335
- "chromatic-projects"?: ChromaticProjectConfig[];
336
- /**
337
- * Docs deployment shorthand. `true` uses the org-standard `docs/` directory;
338
- * `{ path: "custom" }` uses a custom directory. Both derive a `paths:` entry automatically.
339
- */
340
- docs?: true | {
341
- path: string;
342
- };
343
- /** Storybook apps to deploy alongside docs. Each entry's `path` is appended to `paths:`. */
344
- storybook?: StorybookDeployProject[];
345
- };
346
- /**
347
- * A `tasks` manifest entry in object form. A bare string entry is shorthand
348
- * for `{ name, ci: true, local: true }`.
349
- */
350
- interface TaskEntryConfig {
351
- name: string;
352
- with?: WorkflowWithConfig;
353
- paths?: string[];
354
- linters?: string[];
355
- /** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron run ci`. Default `true`. */
356
- ci?: boolean;
357
- /** Write a `package.json` script + let `holocron run <name>` resolve the task. Default `true`. */
358
- local?: boolean;
359
- /** The task's CI check context is a required status check + part of `holocron run ci`'s default run. */
360
- required?: boolean;
361
- /**
362
- * Per-repo additions to this task's generated `turbo.json` entry —
363
- * a separate channel from `with:` (that's the reusable *workflow's*
364
- * inputs; this is local turbo cache config, unrelated). No-op for a
365
- * task with no turbo fan-out config in the registry. Mirrors
366
- * astromech's own `TaskEntry["turbo"]` — kept in sync by hand, since
367
- * this package doesn't depend on astromech directly.
368
- */
369
- turbo?: {
370
- /** Extra env vars turbo hashes into this task's cache key, appended to the registry default. */
371
- passThroughEnv?: string[];
372
- /**
373
- * Extra input globs appended to the registry default's `inputs`
374
- * (holocron#845) — for a package whose layout the registry
375
- * default doesn't cover (e.g. a flat-layout package with no
376
- * `src/` directory at all).
377
- */
378
- inputs?: string[];
379
- };
380
- }
381
- interface HolocronConfig {
382
- /** Project name. Derived from package.json when absent. */
383
- name?: string;
384
- description?: string;
385
- /** Project homepage URL. Synced to package.json#homepage and the GitHub repo's website field by `holocron repo sync`. */
386
- homepage?: string;
387
- /**
388
- * Active org name for namespaced keyring lookup. When set, token resolution
389
- * tries `<service>.<org>` before the unnamespaced `<service>` fallback, so
390
- * a single machine can hold credentials for multiple GitHub orgs without
391
- * collision. Overridden by `--org` CLI flag or `HOLOCRON_ORG` env var.
392
- */
393
- org?: string;
394
- /**
395
- * Org canonical domain (e.g. `"theholocron.dev"`). Subdomains are derived
396
- * from this — `preview: true` on a deploy workflow resolves the preview base
397
- * domain as `preview.<domain>`, giving URLs like `<repo>-pr-<n>.<domain>`.
398
- */
399
- domain?: string;
400
- /**
401
- * Repository identity and metadata. When set, `PluginLoader` injects
402
- * `repo.name` into every plugin's `RuntimeContext.repo` so plugins that
403
- * need a repo (github, etc.) don't require `--repo` on every invocation.
404
- * `--repo` on the command line still overrides.
405
- */
406
- repo?: RepoConfig;
407
- /**
408
- * The task manifest — what this repo runs. Each entry is a task name
409
- * (backed by a reusable workflow in `theholocron/.github`), or the object
410
- * form to pass `with:` inputs. `@theholocron/astromech` reads this as the
411
- * single source for `holocron run` / `holocron run ci` / the generated CI
412
- * workflows / `package.json` scripts.
413
- *
414
- * Supported values (intent-facing vocabulary — epic #672, D3):
415
- * "verification.unitTests" | "verification.visualRegression" | "verification.typeSafety" | "verification.performance" |
416
- * "sourceQuality.staticAnalysis" | "sourceQuality.formatting" |
417
- * "sourceQuality.structuredDataValidation" | "sourceQuality.deadCodeAnalysis" |
418
- * "security.secretDetection" | "security.codeScanning" |
419
- * "delivery.build" | "delivery.publish" | "delivery.deploy" | "delivery.bundleSize" |
420
- * "platform.repoSync" | "platform.notifyCheck" | "platform.commitStandards" | "platform.repoValidation" |
421
- * "knowledge.wiki" | "knowledge.docs" | "knowledge.components" |
422
- * "review" | "tag" | "stale" | "greetings" | "dependencies" | "bookkeeping"
423
- *
424
- * `holocron repo setup` writes `.github/workflows/<name>.yml` for each entry,
425
- * calling the corresponding reusable workflow in `theholocron/.github`.
426
- * Files are overwritten on each run — they are generated artifacts.
427
- *
428
- * ### delivery.deploy / knowledge.docs / knowledge.components
429
- * `delivery.deploy` uses `docs` and/or `storybook` in `with:` — setup
430
- * derives `paths:` automatically. `docs: true` uses the org-standard
431
- * `docs/` directory; `docs: { path: "custom" }` overrides it.
432
- * `knowledge.docs` / `knowledge.components` are the same underlying
433
- * mechanism, each dedicated to exactly one type — they imply the
434
- * corresponding shorthand, so a repo using them never has to spell out
435
- * `docs: true` / `storybook: […]` itself.
436
- *
437
- * ```ts
438
- * // Docs only (standard layout)
439
- * { name: "delivery.deploy", with: { docs: true } }
440
- * // …or equivalently, the dedicated task:
441
- * "knowledge.docs"
442
- *
443
- * // Docs + monorepo storybooks
444
- * {
445
- * name: "delivery.deploy",
446
- * with: {
447
- * docs: true,
448
- * storybook: [
449
- * { name: "web", path: "apps/web" },
450
- * { name: "ui", path: "packages/ui" },
451
- * ],
452
- * },
453
- * }
454
- *
455
- * // Non-standard docs location
456
- * { name: "delivery.deploy", with: { docs: { path: "packages/site" } } }
457
- * ```
458
- *
459
- * ### verification.visualRegression
460
- * Its own task, not a `verification.unitTests` sub-job (holocron#394/#1062)
461
- * — GitHub evaluates a job's `if:` before expanding its `strategy.matrix`,
462
- * so no `chromatic-projects` default can make a *disabled* Chromatic job
463
- * disappear from PR checks; only not generating the job at all does. Omit
464
- * this task entirely for a repo that doesn't use Chromatic — no workflow,
465
- * no job, no check, not even a skipped one.
466
- *
467
- * For a single-project repo, use a `CHROMATIC_PROJECT_TOKEN` repository
468
- * secret with `tokenName: "default"`:
469
- * ```ts
470
- * {
471
- * name: "verification.visualRegression",
472
- * with: { "chromatic-projects": [{ tokenName: "default", workingDir: "." }] },
473
- * }
474
- * ```
475
- *
476
- * For monorepos with multiple Storybooks, list one entry per project:
477
- * ```ts
478
- * {
479
- * name: "verification.visualRegression",
480
- * with: {
481
- * "chromatic-projects": [
482
- * { tokenName: "WEB", workingDir: "apps/web" },
483
- * { tokenName: "UI", workingDir: "packages/ui" },
484
- * ],
485
- * },
486
- * }
487
- * ```
488
- * Each `tokenName` maps to a repository secret named
489
- * `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
490
- *
491
- * @example
492
- * ["sourceQuality.staticAnalysis", { "name": "delivery.publish", "with": { "run-build": false } }]
493
- * { "name": "delivery.deploy", "with": { "docs": true } }
494
- */
495
- tasks?: Array<string | TaskEntryConfig>;
496
- /**
497
- * Opt out of `holocron repo sync`'s `package.json` script writes. Default `true`.
498
- */
499
- syncScripts?: boolean;
500
- /**
501
- * The command the synced `"holocron"` `package.json` script runs. Default
502
- * `"holocron"` (the installed bin). This repo overrides it to run its own
503
- * build (`"node cli/cli/dist/cli.mjs"`).
504
- */
505
- holocronScript?: string;
506
- /**
507
- * Required status-check contexts not backed by a `required` task (codecov
508
- * gates, the bundle-build check, …). `holocron repo setup` appends these to the
509
- * task-derived list from `astromech.requiredChecks()`.
510
- */
511
- extraRequiredChecks?: string[];
512
- /**
513
- * Git hooks `holocron repo setup` installs. `true` / `{ prePush: true }` writes
514
- * `.husky/pre-push` (runs `holocron run ci` before every push); `false` /
515
- * `{ prePush: false }` opts out. Omitted → on for `protection: "strict"`,
516
- * off otherwise. `--hooks` / `--no-hooks` on `holocron repo setup` override.
517
- */
518
- hooks?: boolean | {
519
- prePush?: boolean;
520
- };
521
- providers: RawProvidersConfig;
522
- apps?: AppConfig[];
523
- doctor?: DoctorConfig;
524
- /**
525
- * Agent runtime that determines where skills are installed by `holocron repo setup`.
526
- * Skills are installed to `.agents/skills/<name>/` (canonical) with a
527
- * relative symlink at the agent-specific path:
528
- * - `"claude"` → `.claude/skills/<name>` → `../../.agents/skills/<name>`
529
- * - `"codex"` | `"gemini"` → logged as unsupported; skipped gracefully.
530
- */
531
- agent?: "claude" | "codex" | "gemini";
532
- /**
533
- * Skill names from `@theholocron/skills` to install during `holocron repo setup`.
534
- * Installed paths are gitignored and managed by setup — do not commit them.
535
- *
536
- * @example
537
- * ["git-safety", "pr-workflow", "commit-standards"]
538
- */
539
- skills?: string[];
540
- /**
541
- * GitHub Pages configuration. When present, `holocron repo setup` calls the
542
- * Pages API using `HOLOCRON_DEPLOY_TOKEN` (requires `pages:write` + `repo` scope).
543
- * When absent, Pages is left as-is.
544
- *
545
- * @example
546
- * { build: "workflow", domain: "docs.theholocron.dev", https: true }
547
- */
548
- docs?: DocsConfig;
549
- /**
550
- * Environment variable namespace configuration.
551
- * Declares the prefix(es) this project uses for its env vars so that
552
- * tooling can generate `.env.example`, validate required vars, and
553
- * produce accurate documentation without hard-coding prefix strings.
554
- *
555
- * @example
556
- * { namespaces: ["HOLOCRON", "MY_CLI"] }
557
- */
558
- env?: EnvConfig;
559
- /**
560
- * Structured-logging config. Only the level belongs here — Axiom
561
- * credentials come from env vars, never a committed file.
562
- *
563
- * @example
564
- * { level: "debug" }
565
- */
566
- log?: LogConfig;
567
- /**
568
- * CLI self-telemetry override layer. Env var (`HOLOCRON_TELEMETRY=false`)
569
- * still wins; this is the committed way to opt a repo out or drop usage
570
- * analytics while keeping error reporting.
571
- *
572
- * @example
573
- * { enabled: false }
574
- * { analytics: "none" }
575
- */
576
- telemetry?: TelemetryConfig;
577
- /**
578
- * ESLint bundle option overrides that Sentinel's centralized static-
579
- * analysis check (holocron#849) can't otherwise see. Bucket 1 checks
580
- * never read a PR's own committed files for config — this is the
581
- * declared source of truth Sentinel reads instead, so its check stays
582
- * in sync with what each package's own `eslint.config.ts` already
583
- * enforces locally and in CI.
584
- */
585
- eslint?: EslintConfig;
586
- }
587
- /**
588
- * Repo-root-relative directories treated as browser-targeted for eslint's
589
- * node-builtins compatibility checks — mirrors
590
- * `@theholocron/eslint-config`'s `library({ browserPackages })` option.
591
- * Only needed for a package whose own `eslint.config.ts` already declares
592
- * `browserPackages` (a deliberate outlier, not the norm — see that
593
- * package's own config file for why).
594
- *
595
- * @example
596
- * { browserPackages: ["packages/github-client/src/app-auth"] }
597
- */
598
- interface EslintConfig {
599
- browserPackages?: string[];
600
- }
601
- interface ResolvedTuple {
602
- provider: string;
603
- /** Resolved package name (`@theholocron/holocron-plugin-<provider>` for short refs). */
604
- packageName: string;
605
- options: ProviderOptions;
606
- }
607
- type ResolvedProviderEntry = {
608
- cardinality: "single";
609
- tuple: ResolvedTuple;
610
- } | {
611
- cardinality: "many";
612
- tuples: ResolvedTuple[];
613
- };
614
- type ResolvedProvidersConfig = Partial<Record<CapabilityKey, ResolvedProviderEntry>>;
615
- interface ResolvedHolocronConfig {
616
- name: string;
617
- description?: string;
618
- homepage?: string;
619
- org?: string;
620
- domain?: string;
621
- repo?: RepoConfig;
622
- tasks?: Array<string | TaskEntryConfig>;
623
- syncScripts?: boolean;
624
- holocronScript?: string;
625
- extraRequiredChecks?: string[];
626
- hooks?: boolean | {
627
- prePush?: boolean;
628
- };
629
- providers: ResolvedProvidersConfig;
630
- apps: AppConfig[];
631
- doctor: DoctorConfig;
632
- agent?: "claude" | "codex" | "gemini";
633
- skills?: string[];
634
- /** Resolved Pages config. `build` is guaranteed present when this field exists. */
635
- docs?: PagesConfig;
636
- env?: EnvConfig;
637
- log?: LogConfig;
638
- telemetry?: TelemetryConfig;
639
- eslint?: EslintConfig;
640
- }
641
- //#endregion
642
- //#region src/config/config/config.d.ts
643
- declare class ConfigError extends Error {
644
- name: string;
645
- }
646
- /**
647
- * Resolve `"github"` → `"@theholocron/holocron-plugin-github"`.
648
- * Fully-qualified names (scoped or not) are honored verbatim, which
649
- * is how third-party plugins published outside the org work.
650
- */
651
- declare function resolvePluginPackage(provider: string): string;
652
- declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
653
- declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
654
- //#endregion
655
- //#region src/config/compose/compose.type.d.ts
656
- type TaskEntry = NonNullable<HolocronConfig["tasks"]>[number];
657
- /** A single composable capability fragment. */
658
- interface Capability {
659
- /** Unique identifier — used for deduplication and dependency resolution. */
660
- id: string;
661
- /** Other capability IDs that must be present in the same compose() call. */
662
- requires?: string[];
663
- /** Task entries contributed by this capability. Merged by name; last writer wins. */
664
- tasks?: TaskEntry[];
665
- /** Provider config. Shallow-merged at the top level; later capabilities override per-key. */
666
- providers?: RawProvidersConfig;
667
- /**
668
- * Required status-check contexts **not** backed by a `required` task
669
- * (codecov gates, `Storybook Publish`, …). Unioned across all capabilities
670
- * onto the top-level `extraRequiredChecks`. Task-backed checks come from
671
- * `{ required: true }` task entries via `astromech.requiredChecks()`.
672
- */
673
- extraRequiredChecks?: string[];
674
- /** Repo config fragment. Scalar fields: last writer wins. properties/topics/teams: merged. */
675
- repo?: Partial<Omit<RepoConfig, "name">>;
676
- /** Org name. Last writer wins. */
677
- org?: string;
678
- /** Org canonical domain. Last writer wins. */
679
- domain?: string;
680
- /** Docs site config. Last writer wins. */
681
- docs?: DocsConfig;
682
- }
683
- /** The merged result of a compose() call. Spreads into defineConfig(). */
684
- interface ComposedPreset {
685
- tasks: TaskEntry[];
686
- providers: RawProvidersConfig;
687
- repo: Partial<Omit<RepoConfig, "name">>;
688
- /** Non-task required-check contexts, unioned across capabilities. */
689
- extraRequiredChecks: string[];
690
- org?: string;
691
- domain?: string;
692
- docs?: DocsConfig;
693
- }
694
- //#endregion
695
- //#region src/config/compose/compose.d.ts
696
- /**
697
- * Merge any number of capability fragments into a single preset object that
698
- * spreads directly into `defineConfig()`.
699
- *
700
- * - Accepts individual capabilities or nested arrays (for bundle presets).
701
- * - Deduplicates by `id` — when the same ID appears more than once, the last
702
- * occurrence wins. This lets callers override bundle defaults by listing an
703
- * explicit capability after the bundle.
704
- * - Validates all `requires` at call time and throws `ConfigError` if any are
705
- * unmet, listing every missing dependency in a single message.
706
- *
707
- * @example
708
- * // docs-only site — no typecheck
709
- * const preset = compose(node(), docs());
710
- *
711
- * // library with docs
712
- * const preset = compose(node(), typecheck(), docs());
713
- *
714
- * // nextjs() is a bundle that returns Capability[]
715
- * const preset = compose(node(), nextjs());
716
- */
717
- declare function compose(...args: (Capability | Capability[])[]): ComposedPreset;
718
- //#endregion
719
89
  //#region src/config/define-config/define-config.d.ts
720
90
  declare function defineConfig(config: HolocronConfig): HolocronConfig;
721
91
  //#endregion