@theholocron/cli 5.0.0-alpha.24 → 5.0.0-alpha.241

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,19 +1,24 @@
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, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti } from "./plugin/capabilities.mjs";
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";
2
2
  import { AuthError, RequestOptions, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
3
+ import { PackageJson } from "@theholocron/pkg-utils";
3
4
  import { ConfigFileError } from "@theholocron/datapad";
4
- import { WorkspacePackage } from "@theholocron/astromech";
5
5
  import { LogLevel } from "@theholocron/observability/core";
6
- //#region src/auth/auth-resolver.d.ts
6
+ import { WorkspacePackage } from "@theholocron/astromech";
7
+ //#region src/auth/auth-resolver/auth-resolver.type.d.ts
7
8
  type ResolveTokenConfig = Omit<ResolveTokenConfig$1, "getKeyringToken">;
8
- /** Wraps `createResolveToken` from `@theholocron/http` and injects the
9
- * system keyring so plugins stay at a one-liner call site. */
10
- declare function createResolveToken(config: ResolveTokenConfig): (input?: ResolveTokenInput) => string;
11
9
  interface FeatureResolverConfig {
12
10
  /** Env var name for this feature, e.g. `"HOLOCRON_ISSUES_TOKEN"`. */
13
11
  envName: string;
14
12
  /** Keyring account key, e.g. `"github.issues"`. */
15
13
  keyringKey: string;
14
+ /** The vendor named in the "no token" message. Default `GitHub`. */
15
+ vendor?: string;
16
16
  }
17
+ //#endregion
18
+ //#region src/auth/auth-resolver/auth-resolver.d.ts
19
+ /** Wraps `createResolveToken` from `@theholocron/http` and injects the
20
+ * system keyring so plugins stay at a one-liner call site. */
21
+ declare function createResolveToken(config: ResolveTokenConfig): (input?: ResolveTokenInput) => string;
17
22
  /**
18
23
  * Build a strict, single-feature token resolver.
19
24
  *
@@ -23,7 +28,7 @@ interface FeatureResolverConfig {
23
28
  */
24
29
  declare function createFeatureResolver(config: FeatureResolverConfig): (input?: ResolveTokenInput) => string;
25
30
  //#endregion
26
- //#region src/auth/keyring.d.ts
31
+ //#region src/auth/keyring/keyring.d.ts
27
32
  /**
28
33
  * Keyring-backed bootstrap credential store.
29
34
  *
@@ -67,7 +72,20 @@ declare function deleteToken(provider: string): boolean;
67
72
  */
68
73
  declare function listStoredProviders(): string[];
69
74
  //#endregion
70
- //#region src/config/config.d.ts
75
+ //#region src/commands/auth/auth.type.d.ts
76
+ interface VerifyTokenSuccess {
77
+ ok: true;
78
+ /** "workplace: acme" / "user: cnewton@x" — surfaced in success output. */
79
+ subject: string;
80
+ }
81
+ interface VerifyTokenFailure {
82
+ ok: false;
83
+ /** Reason the token was rejected. Surfaces to the operator. */
84
+ message: string;
85
+ }
86
+ type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
87
+ //#endregion
88
+ //#region src/config/config/config.type.d.ts
71
89
  /** Structured-logging config. The Axiom **token** never lives here — only in
72
90
  * env vars or the OS keyring — but the non-secret dataset name may. */
73
91
  interface LogConfig {
@@ -141,7 +159,7 @@ interface DocsConfig {
141
159
  * GitHub Pages build source.
142
160
  * "workflow" → GitHub Actions (PUT { build_type: "workflow" })
143
161
  * "branch" → classic gh-pages branch (PUT { build_type: "legacy", source: { branch: "gh-pages", path: "/" } })
144
- * When absent, Pages is not managed by `holocron setup`.
162
+ * When absent, Pages is not managed by `holocron repo setup`.
145
163
  */
146
164
  build?: "workflow" | "branch";
147
165
  /**
@@ -159,11 +177,44 @@ interface RepoProperties {
159
177
  runtime_environment?: "node" | "browser" | "universal" | "none";
160
178
  uses_external_packages?: boolean;
161
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
+ }
162
198
  interface RepoConfig {
163
199
  /** "owner/name" — the GitHub repository coordinate. Derived from the git remote when absent. */
164
200
  name?: string;
165
201
  /**
166
- * Branch protection preset applied by `holocron setup`. When omitted,
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,
167
218
  * no protection is applied and no `branch_protection_level` property is set.
168
219
  * Required-status-check contexts for `"strict"` are derived from the task
169
220
  * manifest — `{ required: true }` tasks + top-level `extraRequiredChecks`
@@ -171,7 +222,7 @@ interface RepoConfig {
171
222
  */
172
223
  protection?: RepoProtection;
173
224
  /**
174
- * GitHub teams granted repository access. Synced by `holocron setup`, which
225
+ * GitHub teams granted repository access. Synced by `holocron repo setup`, which
175
226
  * also writes `.github/CODEOWNERS` for teams with write-or-higher permission.
176
227
  * String shorthand defaults to `push` (Write).
177
228
  */
@@ -180,6 +231,8 @@ interface RepoConfig {
180
231
  topics?: string[];
181
232
  /** GitHub custom properties synced to the org dashboard. */
182
233
  properties?: RepoProperties;
234
+ /** GitHub Actions variables reconciled by `holocron repo setup`. */
235
+ variables?: RepoVariables;
183
236
  }
184
237
  interface AppConfig {
185
238
  name: string;
@@ -206,7 +259,8 @@ interface EnvConfig {
206
259
  namespaces?: string[];
207
260
  }
208
261
  /**
209
- * A single Chromatic project entry in a monorepo `run-chromatic` config.
262
+ * A single Chromatic project entry in a `verification.visualRegression`
263
+ * task's `chromatic-projects` config.
210
264
  * Each entry produces one matrix job in CI, publishing to a separate Chromatic project.
211
265
  *
212
266
  * The `tokenName` maps to a repository secret named `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
@@ -268,18 +322,17 @@ interface StorybookDeployProject {
268
322
  /**
269
323
  * Typed `with:` inputs for reusable workflows.
270
324
  *
271
- * `run-chromatic` accepts either a plain boolean (single-project) or a
272
- * `ChromaticProjectConfig[]` object (multi-project monorepo).
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.
273
328
  *
274
- * `docs` / `storybook` are high-level deploy shorthand that `holocron setup`
329
+ * `docs` / `storybook` are high-level deploy shorthand that `holocron repo setup`
275
330
  * translates to `type` / `storybook-projects` before writing the thin caller.
276
331
  * They also drive automatic `paths:` derivation so you never need to write
277
332
  * `paths:` manually for deploy entries.
278
333
  */
279
334
  type WorkflowWithConfig = Record<string, unknown> & {
280
- "run-chromatic"?: boolean | {
281
- projects: ChromaticProjectConfig[];
282
- };
335
+ "chromatic-projects"?: ChromaticProjectConfig[];
283
336
  /**
284
337
  * Docs deployment shorthand. `true` uses the org-standard `docs/` directory;
285
338
  * `{ path: "custom" }` uses a custom directory. Both derive a `paths:` entry automatically.
@@ -299,18 +352,37 @@ interface TaskEntryConfig {
299
352
  with?: WorkflowWithConfig;
300
353
  paths?: string[];
301
354
  linters?: string[];
302
- /** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron ci`. Default `true`. */
355
+ /** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron run ci`. Default `true`. */
303
356
  ci?: boolean;
304
357
  /** Write a `package.json` script + let `holocron run <name>` resolve the task. Default `true`. */
305
358
  local?: boolean;
306
- /** The task's CI check context is a required status check + part of `holocron ci`'s default run. */
359
+ /** The task's CI check context is a required status check + part of `holocron run ci`'s default run. */
307
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
+ };
308
380
  }
309
381
  interface HolocronConfig {
310
382
  /** Project name. Derived from package.json when absent. */
311
383
  name?: string;
312
384
  description?: string;
313
- /** Project homepage URL. Synced to package.json#homepage and the GitHub repo's website field by `holocron sync`. */
385
+ /** Project homepage URL. Synced to package.json#homepage and the GitHub repo's website field by `holocron repo sync`. */
314
386
  homepage?: string;
315
387
  /**
316
388
  * Active org name for namespaced keyring lookup. When set, token resolution
@@ -336,20 +408,20 @@ interface HolocronConfig {
336
408
  * The task manifest — what this repo runs. Each entry is a task name
337
409
  * (backed by a reusable workflow in `theholocron/.github`), or the object
338
410
  * form to pass `with:` inputs. `@theholocron/astromech` reads this as the
339
- * single source for `holocron run` / `holocron ci` / the generated CI
411
+ * single source for `holocron run` / `holocron run ci` / the generated CI
340
412
  * workflows / `package.json` scripts.
341
413
  *
342
414
  * Supported values (intent-facing vocabulary — epic #672, D3):
343
- * "verification.unitTests" | "verification.typeSafety" | "verification.performance" |
415
+ * "verification.unitTests" | "verification.visualRegression" | "verification.typeSafety" | "verification.performance" |
344
416
  * "sourceQuality.staticAnalysis" | "sourceQuality.formatting" |
345
417
  * "sourceQuality.structuredDataValidation" | "sourceQuality.deadCodeAnalysis" |
346
418
  * "security.secretDetection" | "security.codeScanning" |
347
419
  * "delivery.build" | "delivery.publish" | "delivery.deploy" | "delivery.bundleSize" |
348
- * "platform.repoSync" | "platform.commitStandards" | "platform.repoValidation" |
420
+ * "platform.repoSync" | "platform.notifyCheck" | "platform.commitStandards" | "platform.repoValidation" |
349
421
  * "knowledge.wiki" | "knowledge.docs" | "knowledge.components" |
350
422
  * "review" | "tag" | "stale" | "greetings" | "dependencies" | "bookkeeping"
351
423
  *
352
- * `holocron setup` writes `.github/workflows/<name>.yml` for each entry,
424
+ * `holocron repo setup` writes `.github/workflows/<name>.yml` for each entry,
353
425
  * calling the corresponding reusable workflow in `theholocron/.github`.
354
426
  * Files are overwritten on each run — they are generated artifacts.
355
427
  *
@@ -384,23 +456,37 @@ interface HolocronConfig {
384
456
  * { name: "delivery.deploy", with: { docs: { path: "packages/site" } } }
385
457
  * ```
386
458
  *
387
- * ### run-chromatic
388
- * For a single-project repo, use `"run-chromatic": true` with a
389
- * `CHROMATIC_PROJECT_TOKEN` repository secret.
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
+ * ```
390
475
  *
391
- * For monorepos with multiple Storybooks, use the object form:
476
+ * For monorepos with multiple Storybooks, list one entry per project:
392
477
  * ```ts
393
- * "run-chromatic": {
394
- * projects: [
395
- * { tokenName: "WEB", workingDir: "apps/web" },
396
- * { tokenName: "UI", workingDir: "packages/ui" },
397
- * ]
478
+ * {
479
+ * name: "verification.visualRegression",
480
+ * with: {
481
+ * "chromatic-projects": [
482
+ * { tokenName: "WEB", workingDir: "apps/web" },
483
+ * { tokenName: "UI", workingDir: "packages/ui" },
484
+ * ],
485
+ * },
398
486
  * }
399
487
  * ```
400
488
  * Each `tokenName` maps to a repository secret named
401
- * `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`. `holocron setup` expands this
402
- * to the flat `run-chromatic: true` + `chromatic-projects: <json>` inputs
403
- * that the reusable workflow accepts.
489
+ * `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
404
490
  *
405
491
  * @example
406
492
  * ["sourceQuality.staticAnalysis", { "name": "delivery.publish", "with": { "run-build": false } }]
@@ -408,26 +494,26 @@ interface HolocronConfig {
408
494
  */
409
495
  tasks?: Array<string | TaskEntryConfig>;
410
496
  /**
411
- * Opt out of `holocron sync`'s `package.json` script writes. Default `true`.
497
+ * Opt out of `holocron repo sync`'s `package.json` script writes. Default `true`.
412
498
  */
413
499
  syncScripts?: boolean;
414
500
  /**
415
501
  * The command the synced `"holocron"` `package.json` script runs. Default
416
502
  * `"holocron"` (the installed bin). This repo overrides it to run its own
417
- * build (`"node packages/cli/dist/cli.mjs"`).
503
+ * build (`"node cli/cli/dist/cli.mjs"`).
418
504
  */
419
505
  holocronScript?: string;
420
506
  /**
421
507
  * Required status-check contexts not backed by a `required` task (codecov
422
- * gates, the bundle-build check, …). `holocron setup` appends these to the
508
+ * gates, the bundle-build check, …). `holocron repo setup` appends these to the
423
509
  * task-derived list from `astromech.requiredChecks()`.
424
510
  */
425
511
  extraRequiredChecks?: string[];
426
512
  /**
427
- * Git hooks `holocron setup` installs. `true` / `{ prePush: true }` writes
428
- * `.husky/pre-push` (runs `holocron ci` before every push); `false` /
513
+ * Git hooks `holocron repo setup` installs. `true` / `{ prePush: true }` writes
514
+ * `.husky/pre-push` (runs `holocron run ci` before every push); `false` /
429
515
  * `{ prePush: false }` opts out. Omitted → on for `protection: "strict"`,
430
- * off otherwise. `--hooks` / `--no-hooks` on `holocron setup` override.
516
+ * off otherwise. `--hooks` / `--no-hooks` on `holocron repo setup` override.
431
517
  */
432
518
  hooks?: boolean | {
433
519
  prePush?: boolean;
@@ -436,7 +522,7 @@ interface HolocronConfig {
436
522
  apps?: AppConfig[];
437
523
  doctor?: DoctorConfig;
438
524
  /**
439
- * Agent runtime that determines where skills are installed by `holocron setup`.
525
+ * Agent runtime that determines where skills are installed by `holocron repo setup`.
440
526
  * Skills are installed to `.agents/skills/<name>/` (canonical) with a
441
527
  * relative symlink at the agent-specific path:
442
528
  * - `"claude"` → `.claude/skills/<name>` → `../../.agents/skills/<name>`
@@ -444,7 +530,7 @@ interface HolocronConfig {
444
530
  */
445
531
  agent?: "claude" | "codex" | "gemini";
446
532
  /**
447
- * Skill names from `@theholocron/skills` to install during `holocron setup`.
533
+ * Skill names from `@theholocron/skills` to install during `holocron repo setup`.
448
534
  * Installed paths are gitignored and managed by setup — do not commit them.
449
535
  *
450
536
  * @example
@@ -452,7 +538,7 @@ interface HolocronConfig {
452
538
  */
453
539
  skills?: string[];
454
540
  /**
455
- * GitHub Pages configuration. When present, `holocron setup` calls the
541
+ * GitHub Pages configuration. When present, `holocron repo setup` calls the
456
542
  * Pages API using `HOLOCRON_DEPLOY_TOKEN` (requires `pages:write` + `repo` scope).
457
543
  * When absent, Pages is left as-is.
458
544
  *
@@ -488,6 +574,29 @@ interface HolocronConfig {
488
574
  * { analytics: "none" }
489
575
  */
490
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[];
491
600
  }
492
601
  interface ResolvedTuple {
493
602
  provider: string;
@@ -527,7 +636,10 @@ interface ResolvedHolocronConfig {
527
636
  env?: EnvConfig;
528
637
  log?: LogConfig;
529
638
  telemetry?: TelemetryConfig;
639
+ eslint?: EslintConfig;
530
640
  }
641
+ //#endregion
642
+ //#region src/config/config/config.d.ts
531
643
  declare class ConfigError extends Error {
532
644
  name: string;
533
645
  }
@@ -540,7 +652,93 @@ declare function resolvePluginPackage(provider: string): string;
540
652
  declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
541
653
  declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
542
654
  //#endregion
543
- //#region src/commands/setup/derived-properties.d.ts
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
+ //#region src/config/define-config/define-config.d.ts
720
+ declare function defineConfig(config: HolocronConfig): HolocronConfig;
721
+ //#endregion
722
+ //#region src/config/load-config/load-config.type.d.ts
723
+ interface LoadedConfig {
724
+ resolved: ResolvedHolocronConfig;
725
+ /** Absolute path to the file the config was read from. */
726
+ filepath: string;
727
+ }
728
+ //#endregion
729
+ //#region src/config/load-config/load-config.d.ts
730
+ /**
731
+ * Read + parse + resolve `holocron.config.*` starting from the given
732
+ * directory, walking up through ancestors to the nearest `.git` boundary
733
+ * when `cwd` itself has no match — every command is usable from any
734
+ * subdirectory of a repo, not only its exact root (see
735
+ * `@theholocron/datapad`'s own doc comment for the stop conditions).
736
+ * Throws {@link ConfigFileError} when nothing is found or a file cannot
737
+ * be loaded, or `ConfigError` when the config fails schema checks.
738
+ */
739
+ declare function loadConfig(cwd: string): Promise<LoadedConfig>;
740
+ //#endregion
741
+ //#region src/commands/setup/derived-properties/derived-properties.type.d.ts
544
742
  /**
545
743
  * Derived custom-properties (#677). Unlike the existing 6 GitHub
546
744
  * custom-properties fields (`lifecycle`, `open_source`, `runtime_environment`,
@@ -552,13 +750,8 @@ declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
552
750
  * definitions (#677)" for the full design.
553
751
  */
554
752
  type HolocronProfile = "library" | "cli" | "plugin" | "template" | "app" | "docs" | "platform";
555
- interface PackageJsonLike {
556
- name?: string;
557
- private?: boolean;
558
- bin?: unknown;
559
- dependencies?: Record<string, string>;
560
- devDependencies?: Record<string, string>;
561
- }
753
+ /** The `package.json` shape profile derivation reads — `@theholocron/pkg-utils`'s `PackageJson`, under the name Sentinel already imports. */
754
+ type PackageJsonLike = PackageJson;
562
755
  interface DeriveProfileInput {
563
756
  rootPackageJson: PackageJsonLike | null;
564
757
  repoName: string;
@@ -566,6 +759,8 @@ interface DeriveProfileInput {
566
759
  /** `packages/*` package.json contents, monorepo repos only — used to find the primary published artifact. */
567
760
  workspacePackageJsons: PackageJsonLike[];
568
761
  }
762
+ //#endregion
763
+ //#region src/commands/setup/derived-properties/derived-properties.d.ts
569
764
  /**
570
765
  * Repo archetype, in priority order:
571
766
  * 1. `*-template` repo name → `template` (independent of package shape).
@@ -616,82 +811,65 @@ declare function missingCapabilities(capabilities: readonly string[]): string[];
616
811
  */
617
812
  declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
618
813
  //#endregion
619
- //#region src/config/compose.d.ts
620
- type TaskEntry = NonNullable<HolocronConfig["tasks"]>[number];
621
- /** A single composable capability fragment. */
622
- interface Capability {
623
- /** Unique identifier — used for deduplication and dependency resolution. */
624
- id: string;
625
- /** Other capability IDs that must be present in the same compose() call. */
626
- requires?: string[];
627
- /** Task entries contributed by this capability. Merged by name; last writer wins. */
628
- tasks?: TaskEntry[];
629
- /** Provider config. Shallow-merged at the top level; later capabilities override per-key. */
630
- providers?: RawProvidersConfig;
631
- /**
632
- * Required status-check contexts **not** backed by a `required` task
633
- * (codecov gates, `Storybook Publish`, …). Unioned across all capabilities
634
- * onto the top-level `extraRequiredChecks`. Task-backed checks come from
635
- * `{ required: true }` task entries via `astromech.requiredChecks()`.
636
- */
637
- extraRequiredChecks?: string[];
638
- /** Repo config fragment. Scalar fields: last writer wins. properties/topics/teams: merged. */
639
- repo?: Partial<Omit<RepoConfig, "name">>;
640
- /** Org name. Last writer wins. */
641
- org?: string;
642
- /** Org canonical domain. Last writer wins. */
643
- domain?: string;
644
- /** Docs site config. Last writer wins. */
645
- docs?: DocsConfig;
814
+ //#region src/plugin/probe/probe.type.d.ts
815
+ /** One line a probe reports: `info` for a fact, `ok` / `fail` for a result, `heading` to title the rows that follow. */
816
+ interface ProbeRow {
817
+ status: "ok" | "fail" | "info" | "heading";
818
+ label: string;
819
+ detail?: string;
646
820
  }
647
- /** The merged result of a compose() call. Spreads into defineConfig(). */
648
- interface ComposedPreset {
649
- tasks: TaskEntry[];
650
- providers: RawProvidersConfig;
651
- repo: Partial<Omit<RepoConfig, "name">>;
652
- /** Non-task required-check contexts, unioned across capabilities. */
653
- extraRequiredChecks: string[];
654
- org?: string;
655
- domain?: string;
656
- docs?: DocsConfig;
821
+ /** What a probe is handed. Everything it prints or changes goes through this, so the runner can enforce the rules. */
822
+ interface ProbeContext {
823
+ /** `--dry-run`: `write` calls are announced and skipped. */
824
+ dryRun: boolean;
825
+ /** Report one line. The text is scrubbed of secrets before it is printed. */
826
+ say(row: ProbeRow): void;
827
+ /**
828
+ * Change something on the provider. The only way to: on `--dry-run` it prints `would <label>` and does not call `fn`,
829
+ * and a probe that did not declare `writes: true` cannot call it.
830
+ */
831
+ write<T>(label: string, fn: () => Promise<T>): Promise<T | undefined>;
832
+ /** Register how to undo something this probe made. Runs in reverse order on success, failure and Ctrl-C. */
833
+ cleanup(label: string, fn: () => Promise<void>): void;
834
+ /** Mark a value (a token, a signing secret) as one that must never be printed. */
835
+ secret(value: string | undefined): void;
657
836
  }
658
- /**
659
- * Merge any number of capability fragments into a single preset object that
660
- * spreads directly into `defineConfig()`.
661
- *
662
- * - Accepts individual capabilities or nested arrays (for bundle presets).
663
- * - Deduplicates by `id` — when the same ID appears more than once, the last
664
- * occurrence wins. This lets callers override bundle defaults by listing an
665
- * explicit capability after the bundle.
666
- * - Validates all `requires` at call time and throws `ConfigError` if any are
667
- * unmet, listing every missing dependency in a single message.
668
- *
669
- * @example
670
- * // docs-only site — no typecheck
671
- * const preset = compose(node(), docs());
672
- *
673
- * // library with docs
674
- * const preset = compose(node(), typecheck(), docs());
675
- *
676
- * // nextjs() is a bundle that returns Capability[]
677
- * const preset = compose(node(), nextjs());
678
- */
679
- declare function compose(...args: (Capability | Capability[])[]): ComposedPreset;
680
- //#endregion
681
- //#region src/config/define-config.d.ts
682
- declare function defineConfig(config: HolocronConfig): HolocronConfig;
837
+ interface Probe {
838
+ /** One sentence for `holocron probe`'s listing. */
839
+ summary: string;
840
+ /** Whether it creates or changes anything on the provider. Asked about first, and needs `--yes` without a terminal. */
841
+ writes: boolean;
842
+ run(ctx: ProbeContext): Promise<void>;
843
+ }
844
+ /** A plugin's probes by name (kebab-case), as returned from `createPlugin` next to `capabilities`. */
845
+ type PluginProbes = Record<string, Probe>;
683
846
  //#endregion
684
- //#region src/config/load-config.d.ts
685
- interface LoadedConfig {
686
- resolved: ResolvedHolocronConfig;
687
- /** Absolute path to the file the config was read from. */
688
- filepath: string;
847
+ //#region src/plugin/connection-probe/connection-probe.d.ts
848
+ interface ConnectionProbeInput {
849
+ /** How the provider is named in output, e.g. `Axiom`. */
850
+ provider: string;
851
+ /** A URL on the provider's API host. Without one, only the token is checked (a provider that has no HTTP API of its own). */
852
+ url?: string;
853
+ /** Finds the token the plugin would use. Throws with a message that says where to put one when there is none. */
854
+ token: () => string | Promise<string>;
855
+ /** The plugin's `verifyToken`: asks the provider who the token belongs to. */
856
+ verify: (token: string) => Promise<VerifyTokenResult>;
857
+ /** Stands in for the network, so with one the name lookup (which cannot be stood in for) is not made. */
858
+ fetch?: typeof fetch;
859
+ /** Resolves a hostname. Defaults to the system resolver, unless `fetch` is given. */
860
+ lookup?: (host: string) => Promise<{
861
+ address: string;
862
+ }>;
863
+ /** Longest to wait for the host to answer. Defaults to 10 s. */
864
+ timeoutMs?: number;
689
865
  }
866
+ /** A network failure in plain words, with what usually causes it. Never includes anything from a request. */
867
+ declare function describeNetworkError(err: unknown, timeoutMs: number): string;
690
868
  /**
691
- * Read + parse + resolve `holocron.config.*` from the given directory.
692
- * Throws {@link ConfigFileError} when nothing is found or a file cannot
693
- * be loaded, or `ConfigError` when the config is invalid.
869
+ * The `connection` probe every provider offers, for telling a network problem from a credential problem: does the name
870
+ * resolve, does the host answer, is there a token, and does the provider accept it. A step that cannot work because an
871
+ * earlier one failed is reported as not tried rather than failing a second time for the same reason.
694
872
  */
695
- declare function loadConfig(cwd: string): Promise<LoadedConfig>;
873
+ declare function connectionProbe(input: ConnectionProbeInput): Probe;
696
874
  //#endregion
697
- export { Analytics, AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, Capability, CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, DeriveProfileInput, Dns, DnsRecord, DnsRecordType, DocsConfig, DoctorConfig, EnsureResult, EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, FeatureResolverConfig, HolocronConfig, HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, LoadedConfig, LogConfig, Logs, MultiEntry, NormalizedAuthUser, Notifications, PackageJsonLike, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, RawProviderEntry, RawProvidersConfig, RepoConfig, RepoProperties, RepoProtection, RepoRef, RepoSettings, type RequestOptions, ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, ResolvedHolocronConfig, ResolvedProviderEntry, ResolvedProvidersConfig, ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, SingleEntry, Source, StatusCategory, Storage, StorageBranch, StorybookDeployProject, TaskEntryConfig, TeamEntry, TeamPermission, TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig, Workers, WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
875
+ export { Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionProbeInput, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, ElevationRequiredError, EnsureRelayInput, EnsureRelayResult, EnsureResult, EnsureWebhookResult, EnsuredResource, type EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, type EslintConfig, type FeatureResolverConfig, type HolocronConfig, type HolocronProfile, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, type LoadedConfig, type LogConfig, Logs, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type PackageJsonLike, PagesConfig, ParseWebhookInput, type PluginProbes, type Probe, type ProbeContext, type ProbeRow, ProviderApiError, ProviderIdentity, type ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, RepoSettings, type RepoVariables, type RequestOptions, type ResolveTokenConfig, type ResolveTokenInput, ResolvedCapability, type ResolvedHolocronConfig, type ResolvedProviderEntry, type ResolvedProvidersConfig, type ResolvedTuple, type RestClient, type RestClientConfig, Ruleset, SecretScope, Secrets, ServerInspection, type SingleEntry, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, type WorkflowWithConfig, compose, connectionProbe, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, describeNetworkError, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };