@theholocron/cli 5.0.0-alpha.21 → 5.0.0-alpha.211
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +312 -55
- package/dist/cli.mjs +7245 -2579
- package/dist/cli.mjs.map +1 -1
- package/dist/index.d.mts +242 -127
- package/dist/index.mjs +54 -57
- package/dist/plugin/capabilities.d.mts +781 -48
- package/dist/plugin/capabilities.mjs +15 -2
- package/package.json +19 -13
package/dist/index.d.mts
CHANGED
|
@@ -1,19 +1,22 @@
|
|
|
1
|
-
import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, 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,
|
|
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, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, 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
|
-
|
|
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;
|
|
16
14
|
}
|
|
15
|
+
//#endregion
|
|
16
|
+
//#region src/auth/auth-resolver/auth-resolver.d.ts
|
|
17
|
+
/** Wraps `createResolveToken` from `@theholocron/http` and injects the
|
|
18
|
+
* system keyring so plugins stay at a one-liner call site. */
|
|
19
|
+
declare function createResolveToken(config: ResolveTokenConfig): (input?: ResolveTokenInput) => string;
|
|
17
20
|
/**
|
|
18
21
|
* Build a strict, single-feature token resolver.
|
|
19
22
|
*
|
|
@@ -23,7 +26,7 @@ interface FeatureResolverConfig {
|
|
|
23
26
|
*/
|
|
24
27
|
declare function createFeatureResolver(config: FeatureResolverConfig): (input?: ResolveTokenInput) => string;
|
|
25
28
|
//#endregion
|
|
26
|
-
//#region src/auth/keyring.d.ts
|
|
29
|
+
//#region src/auth/keyring/keyring.d.ts
|
|
27
30
|
/**
|
|
28
31
|
* Keyring-backed bootstrap credential store.
|
|
29
32
|
*
|
|
@@ -67,7 +70,20 @@ declare function deleteToken(provider: string): boolean;
|
|
|
67
70
|
*/
|
|
68
71
|
declare function listStoredProviders(): string[];
|
|
69
72
|
//#endregion
|
|
70
|
-
//#region src/
|
|
73
|
+
//#region src/commands/auth/auth.type.d.ts
|
|
74
|
+
interface VerifyTokenSuccess {
|
|
75
|
+
ok: true;
|
|
76
|
+
/** "workplace: acme" / "user: cnewton@x" — surfaced in success output. */
|
|
77
|
+
subject: string;
|
|
78
|
+
}
|
|
79
|
+
interface VerifyTokenFailure {
|
|
80
|
+
ok: false;
|
|
81
|
+
/** Reason the token was rejected. Surfaces to the operator. */
|
|
82
|
+
message: string;
|
|
83
|
+
}
|
|
84
|
+
type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
|
|
85
|
+
//#endregion
|
|
86
|
+
//#region src/config/config/config.type.d.ts
|
|
71
87
|
/** Structured-logging config. The Axiom **token** never lives here — only in
|
|
72
88
|
* env vars or the OS keyring — but the non-secret dataset name may. */
|
|
73
89
|
interface LogConfig {
|
|
@@ -141,7 +157,7 @@ interface DocsConfig {
|
|
|
141
157
|
* GitHub Pages build source.
|
|
142
158
|
* "workflow" → GitHub Actions (PUT { build_type: "workflow" })
|
|
143
159
|
* "branch" → classic gh-pages branch (PUT { build_type: "legacy", source: { branch: "gh-pages", path: "/" } })
|
|
144
|
-
* When absent, Pages is not managed by `holocron setup`.
|
|
160
|
+
* When absent, Pages is not managed by `holocron repo setup`.
|
|
145
161
|
*/
|
|
146
162
|
build?: "workflow" | "branch";
|
|
147
163
|
/**
|
|
@@ -159,11 +175,44 @@ interface RepoProperties {
|
|
|
159
175
|
runtime_environment?: "node" | "browser" | "universal" | "none";
|
|
160
176
|
uses_external_packages?: boolean;
|
|
161
177
|
}
|
|
178
|
+
/**
|
|
179
|
+
* GitHub Actions variables, declared so a workflow that reads `vars.NAME` finds it. Values are plain text, so
|
|
180
|
+
* never put a secret here; secrets go through the `secrets` capability.
|
|
181
|
+
*/
|
|
182
|
+
interface RepoVariables {
|
|
183
|
+
/** Repository-level variables. */
|
|
184
|
+
repo?: Record<string, string>;
|
|
185
|
+
/**
|
|
186
|
+
* Organization-level variables. A bare string is visible to every repository; `visibility: "private"` limits it
|
|
187
|
+
* to private ones. Declare these in one repo only (the one that owns the org's configuration).
|
|
188
|
+
*/
|
|
189
|
+
org?: Record<string, string | {
|
|
190
|
+
value: string;
|
|
191
|
+
visibility?: "all" | "private";
|
|
192
|
+
}>;
|
|
193
|
+
/** Delete variables that exist but are not declared here. Off by default: they are left alone. */
|
|
194
|
+
prune?: boolean;
|
|
195
|
+
}
|
|
162
196
|
interface RepoConfig {
|
|
163
197
|
/** "owner/name" — the GitHub repository coordinate. Derived from the git remote when absent. */
|
|
164
198
|
name?: string;
|
|
165
199
|
/**
|
|
166
|
-
*
|
|
200
|
+
* GitHub's repo-level default branch (`HEAD`) — what a fresh clone checks
|
|
201
|
+
* out, what `gh pr create`/the compare UI target by default, and what
|
|
202
|
+
* Sentinel's `validateConfig()` reads (D6: the App only ever reads config
|
|
203
|
+
* from the repo's default branch, never a PR ref, as a security boundary
|
|
204
|
+
* — never widen that to read PR branches instead of fixing this field).
|
|
205
|
+
* Synced by `holocron repo setup`. Omit to leave GitHub's current setting
|
|
206
|
+
* untouched — most repos never need this. Exists for a repo using a
|
|
207
|
+
* `main`/`alpha` prerelease-channel split (CLAUDE.md's Releases section)
|
|
208
|
+
* where active development happens on a non-`main` branch: set this to
|
|
209
|
+
* that branch so Sentinel validates against what's actually being
|
|
210
|
+
* developed, then change it back once that branch merges to `main` for a
|
|
211
|
+
* stable cut and stops being the active branch.
|
|
212
|
+
*/
|
|
213
|
+
defaultBranch?: string;
|
|
214
|
+
/**
|
|
215
|
+
* Branch protection preset applied by `holocron repo setup`. When omitted,
|
|
167
216
|
* no protection is applied and no `branch_protection_level` property is set.
|
|
168
217
|
* Required-status-check contexts for `"strict"` are derived from the task
|
|
169
218
|
* manifest — `{ required: true }` tasks + top-level `extraRequiredChecks`
|
|
@@ -171,7 +220,7 @@ interface RepoConfig {
|
|
|
171
220
|
*/
|
|
172
221
|
protection?: RepoProtection;
|
|
173
222
|
/**
|
|
174
|
-
* GitHub teams granted repository access. Synced by `holocron setup`, which
|
|
223
|
+
* GitHub teams granted repository access. Synced by `holocron repo setup`, which
|
|
175
224
|
* also writes `.github/CODEOWNERS` for teams with write-or-higher permission.
|
|
176
225
|
* String shorthand defaults to `push` (Write).
|
|
177
226
|
*/
|
|
@@ -180,6 +229,8 @@ interface RepoConfig {
|
|
|
180
229
|
topics?: string[];
|
|
181
230
|
/** GitHub custom properties synced to the org dashboard. */
|
|
182
231
|
properties?: RepoProperties;
|
|
232
|
+
/** GitHub Actions variables reconciled by `holocron repo setup`. */
|
|
233
|
+
variables?: RepoVariables;
|
|
183
234
|
}
|
|
184
235
|
interface AppConfig {
|
|
185
236
|
name: string;
|
|
@@ -206,7 +257,8 @@ interface EnvConfig {
|
|
|
206
257
|
namespaces?: string[];
|
|
207
258
|
}
|
|
208
259
|
/**
|
|
209
|
-
* A single Chromatic project entry in a
|
|
260
|
+
* A single Chromatic project entry in a `verification.visualRegression`
|
|
261
|
+
* task's `chromatic-projects` config.
|
|
210
262
|
* Each entry produces one matrix job in CI, publishing to a separate Chromatic project.
|
|
211
263
|
*
|
|
212
264
|
* The `tokenName` maps to a repository secret named `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
|
|
@@ -268,18 +320,17 @@ interface StorybookDeployProject {
|
|
|
268
320
|
/**
|
|
269
321
|
* Typed `with:` inputs for reusable workflows.
|
|
270
322
|
*
|
|
271
|
-
* `
|
|
272
|
-
* `ChromaticProjectConfig[]`
|
|
323
|
+
* `chromatic-projects` (on the `verification.visualRegression` task) takes a
|
|
324
|
+
* `ChromaticProjectConfig[]` directly; each entry's `untraced` glob list may
|
|
325
|
+
* be authored as an array and is newline-joined for you.
|
|
273
326
|
*
|
|
274
|
-
* `docs` / `storybook` are high-level deploy shorthand that `holocron setup`
|
|
327
|
+
* `docs` / `storybook` are high-level deploy shorthand that `holocron repo setup`
|
|
275
328
|
* translates to `type` / `storybook-projects` before writing the thin caller.
|
|
276
329
|
* They also drive automatic `paths:` derivation so you never need to write
|
|
277
330
|
* `paths:` manually for deploy entries.
|
|
278
331
|
*/
|
|
279
332
|
type WorkflowWithConfig = Record<string, unknown> & {
|
|
280
|
-
"
|
|
281
|
-
projects: ChromaticProjectConfig[];
|
|
282
|
-
};
|
|
333
|
+
"chromatic-projects"?: ChromaticProjectConfig[];
|
|
283
334
|
/**
|
|
284
335
|
* Docs deployment shorthand. `true` uses the org-standard `docs/` directory;
|
|
285
336
|
* `{ path: "custom" }` uses a custom directory. Both derive a `paths:` entry automatically.
|
|
@@ -299,18 +350,37 @@ interface TaskEntryConfig {
|
|
|
299
350
|
with?: WorkflowWithConfig;
|
|
300
351
|
paths?: string[];
|
|
301
352
|
linters?: string[];
|
|
302
|
-
/** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron ci`. Default `true`. */
|
|
353
|
+
/** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron run ci`. Default `true`. */
|
|
303
354
|
ci?: boolean;
|
|
304
355
|
/** Write a `package.json` script + let `holocron run <name>` resolve the task. Default `true`. */
|
|
305
356
|
local?: boolean;
|
|
306
|
-
/** The task's CI check context is a required status check + part of `holocron ci`'s default run. */
|
|
357
|
+
/** The task's CI check context is a required status check + part of `holocron run ci`'s default run. */
|
|
307
358
|
required?: boolean;
|
|
359
|
+
/**
|
|
360
|
+
* Per-repo additions to this task's generated `turbo.json` entry —
|
|
361
|
+
* a separate channel from `with:` (that's the reusable *workflow's*
|
|
362
|
+
* inputs; this is local turbo cache config, unrelated). No-op for a
|
|
363
|
+
* task with no turbo fan-out config in the registry. Mirrors
|
|
364
|
+
* astromech's own `TaskEntry["turbo"]` — kept in sync by hand, since
|
|
365
|
+
* this package doesn't depend on astromech directly.
|
|
366
|
+
*/
|
|
367
|
+
turbo?: {
|
|
368
|
+
/** Extra env vars turbo hashes into this task's cache key, appended to the registry default. */
|
|
369
|
+
passThroughEnv?: string[];
|
|
370
|
+
/**
|
|
371
|
+
* Extra input globs appended to the registry default's `inputs`
|
|
372
|
+
* (holocron#845) — for a package whose layout the registry
|
|
373
|
+
* default doesn't cover (e.g. a flat-layout package with no
|
|
374
|
+
* `src/` directory at all).
|
|
375
|
+
*/
|
|
376
|
+
inputs?: string[];
|
|
377
|
+
};
|
|
308
378
|
}
|
|
309
379
|
interface HolocronConfig {
|
|
310
380
|
/** Project name. Derived from package.json when absent. */
|
|
311
381
|
name?: string;
|
|
312
382
|
description?: string;
|
|
313
|
-
/** Project homepage URL. Synced to package.json#homepage and the GitHub repo's website field by `holocron sync`. */
|
|
383
|
+
/** Project homepage URL. Synced to package.json#homepage and the GitHub repo's website field by `holocron repo sync`. */
|
|
314
384
|
homepage?: string;
|
|
315
385
|
/**
|
|
316
386
|
* Active org name for namespaced keyring lookup. When set, token resolution
|
|
@@ -336,20 +406,20 @@ interface HolocronConfig {
|
|
|
336
406
|
* The task manifest — what this repo runs. Each entry is a task name
|
|
337
407
|
* (backed by a reusable workflow in `theholocron/.github`), or the object
|
|
338
408
|
* form to pass `with:` inputs. `@theholocron/astromech` reads this as the
|
|
339
|
-
* single source for `holocron run` / `holocron ci` / the generated CI
|
|
409
|
+
* single source for `holocron run` / `holocron run ci` / the generated CI
|
|
340
410
|
* workflows / `package.json` scripts.
|
|
341
411
|
*
|
|
342
412
|
* Supported values (intent-facing vocabulary — epic #672, D3):
|
|
343
|
-
* "verification.unitTests" | "verification.typeSafety" | "verification.performance" |
|
|
413
|
+
* "verification.unitTests" | "verification.visualRegression" | "verification.typeSafety" | "verification.performance" |
|
|
344
414
|
* "sourceQuality.staticAnalysis" | "sourceQuality.formatting" |
|
|
345
415
|
* "sourceQuality.structuredDataValidation" | "sourceQuality.deadCodeAnalysis" |
|
|
346
416
|
* "security.secretDetection" | "security.codeScanning" |
|
|
347
417
|
* "delivery.build" | "delivery.publish" | "delivery.deploy" | "delivery.bundleSize" |
|
|
348
|
-
* "platform.repoSync" | "platform.commitStandards" | "platform.repoValidation" |
|
|
418
|
+
* "platform.repoSync" | "platform.notifyCheck" | "platform.commitStandards" | "platform.repoValidation" |
|
|
349
419
|
* "knowledge.wiki" | "knowledge.docs" | "knowledge.components" |
|
|
350
420
|
* "review" | "tag" | "stale" | "greetings" | "dependencies" | "bookkeeping"
|
|
351
421
|
*
|
|
352
|
-
* `holocron setup` writes `.github/workflows/<name>.yml` for each entry,
|
|
422
|
+
* `holocron repo setup` writes `.github/workflows/<name>.yml` for each entry,
|
|
353
423
|
* calling the corresponding reusable workflow in `theholocron/.github`.
|
|
354
424
|
* Files are overwritten on each run — they are generated artifacts.
|
|
355
425
|
*
|
|
@@ -384,23 +454,37 @@ interface HolocronConfig {
|
|
|
384
454
|
* { name: "delivery.deploy", with: { docs: { path: "packages/site" } } }
|
|
385
455
|
* ```
|
|
386
456
|
*
|
|
387
|
-
* ###
|
|
388
|
-
*
|
|
389
|
-
* `
|
|
457
|
+
* ### verification.visualRegression
|
|
458
|
+
* Its own task, not a `verification.unitTests` sub-job (holocron#394/#1062)
|
|
459
|
+
* — GitHub evaluates a job's `if:` before expanding its `strategy.matrix`,
|
|
460
|
+
* so no `chromatic-projects` default can make a *disabled* Chromatic job
|
|
461
|
+
* disappear from PR checks; only not generating the job at all does. Omit
|
|
462
|
+
* this task entirely for a repo that doesn't use Chromatic — no workflow,
|
|
463
|
+
* no job, no check, not even a skipped one.
|
|
464
|
+
*
|
|
465
|
+
* For a single-project repo, use a `CHROMATIC_PROJECT_TOKEN` repository
|
|
466
|
+
* secret with `tokenName: "default"`:
|
|
467
|
+
* ```ts
|
|
468
|
+
* {
|
|
469
|
+
* name: "verification.visualRegression",
|
|
470
|
+
* with: { "chromatic-projects": [{ tokenName: "default", workingDir: "." }] },
|
|
471
|
+
* }
|
|
472
|
+
* ```
|
|
390
473
|
*
|
|
391
|
-
* For monorepos with multiple Storybooks,
|
|
474
|
+
* For monorepos with multiple Storybooks, list one entry per project:
|
|
392
475
|
* ```ts
|
|
393
|
-
*
|
|
394
|
-
*
|
|
395
|
-
*
|
|
396
|
-
*
|
|
397
|
-
*
|
|
476
|
+
* {
|
|
477
|
+
* name: "verification.visualRegression",
|
|
478
|
+
* with: {
|
|
479
|
+
* "chromatic-projects": [
|
|
480
|
+
* { tokenName: "WEB", workingDir: "apps/web" },
|
|
481
|
+
* { tokenName: "UI", workingDir: "packages/ui" },
|
|
482
|
+
* ],
|
|
483
|
+
* },
|
|
398
484
|
* }
|
|
399
485
|
* ```
|
|
400
486
|
* Each `tokenName` maps to a repository secret named
|
|
401
|
-
* `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
|
|
402
|
-
* to the flat `run-chromatic: true` + `chromatic-projects: <json>` inputs
|
|
403
|
-
* that the reusable workflow accepts.
|
|
487
|
+
* `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
|
|
404
488
|
*
|
|
405
489
|
* @example
|
|
406
490
|
* ["sourceQuality.staticAnalysis", { "name": "delivery.publish", "with": { "run-build": false } }]
|
|
@@ -408,7 +492,7 @@ interface HolocronConfig {
|
|
|
408
492
|
*/
|
|
409
493
|
tasks?: Array<string | TaskEntryConfig>;
|
|
410
494
|
/**
|
|
411
|
-
* Opt out of `holocron sync`'s `package.json` script writes. Default `true`.
|
|
495
|
+
* Opt out of `holocron repo sync`'s `package.json` script writes. Default `true`.
|
|
412
496
|
*/
|
|
413
497
|
syncScripts?: boolean;
|
|
414
498
|
/**
|
|
@@ -419,15 +503,15 @@ interface HolocronConfig {
|
|
|
419
503
|
holocronScript?: string;
|
|
420
504
|
/**
|
|
421
505
|
* Required status-check contexts not backed by a `required` task (codecov
|
|
422
|
-
* gates, the bundle-build check, …). `holocron setup` appends these to the
|
|
506
|
+
* gates, the bundle-build check, …). `holocron repo setup` appends these to the
|
|
423
507
|
* task-derived list from `astromech.requiredChecks()`.
|
|
424
508
|
*/
|
|
425
509
|
extraRequiredChecks?: string[];
|
|
426
510
|
/**
|
|
427
|
-
* Git hooks `holocron setup` installs. `true` / `{ prePush: true }` writes
|
|
428
|
-
* `.husky/pre-push` (runs `holocron ci` before every push); `false` /
|
|
511
|
+
* Git hooks `holocron repo setup` installs. `true` / `{ prePush: true }` writes
|
|
512
|
+
* `.husky/pre-push` (runs `holocron run ci` before every push); `false` /
|
|
429
513
|
* `{ prePush: false }` opts out. Omitted → on for `protection: "strict"`,
|
|
430
|
-
* off otherwise. `--hooks` / `--no-hooks` on `holocron setup` override.
|
|
514
|
+
* off otherwise. `--hooks` / `--no-hooks` on `holocron repo setup` override.
|
|
431
515
|
*/
|
|
432
516
|
hooks?: boolean | {
|
|
433
517
|
prePush?: boolean;
|
|
@@ -436,7 +520,7 @@ interface HolocronConfig {
|
|
|
436
520
|
apps?: AppConfig[];
|
|
437
521
|
doctor?: DoctorConfig;
|
|
438
522
|
/**
|
|
439
|
-
* Agent runtime that determines where skills are installed by `holocron setup`.
|
|
523
|
+
* Agent runtime that determines where skills are installed by `holocron repo setup`.
|
|
440
524
|
* Skills are installed to `.agents/skills/<name>/` (canonical) with a
|
|
441
525
|
* relative symlink at the agent-specific path:
|
|
442
526
|
* - `"claude"` → `.claude/skills/<name>` → `../../.agents/skills/<name>`
|
|
@@ -444,7 +528,7 @@ interface HolocronConfig {
|
|
|
444
528
|
*/
|
|
445
529
|
agent?: "claude" | "codex" | "gemini";
|
|
446
530
|
/**
|
|
447
|
-
* Skill names from `@theholocron/skills` to install during `holocron setup`.
|
|
531
|
+
* Skill names from `@theholocron/skills` to install during `holocron repo setup`.
|
|
448
532
|
* Installed paths are gitignored and managed by setup — do not commit them.
|
|
449
533
|
*
|
|
450
534
|
* @example
|
|
@@ -452,7 +536,7 @@ interface HolocronConfig {
|
|
|
452
536
|
*/
|
|
453
537
|
skills?: string[];
|
|
454
538
|
/**
|
|
455
|
-
* GitHub Pages configuration. When present, `holocron setup` calls the
|
|
539
|
+
* GitHub Pages configuration. When present, `holocron repo setup` calls the
|
|
456
540
|
* Pages API using `HOLOCRON_DEPLOY_TOKEN` (requires `pages:write` + `repo` scope).
|
|
457
541
|
* When absent, Pages is left as-is.
|
|
458
542
|
*
|
|
@@ -488,6 +572,29 @@ interface HolocronConfig {
|
|
|
488
572
|
* { analytics: "none" }
|
|
489
573
|
*/
|
|
490
574
|
telemetry?: TelemetryConfig;
|
|
575
|
+
/**
|
|
576
|
+
* ESLint bundle option overrides that Sentinel's centralized static-
|
|
577
|
+
* analysis check (holocron#849) can't otherwise see. Bucket 1 checks
|
|
578
|
+
* never read a PR's own committed files for config — this is the
|
|
579
|
+
* declared source of truth Sentinel reads instead, so its check stays
|
|
580
|
+
* in sync with what each package's own `eslint.config.ts` already
|
|
581
|
+
* enforces locally and in CI.
|
|
582
|
+
*/
|
|
583
|
+
eslint?: EslintConfig;
|
|
584
|
+
}
|
|
585
|
+
/**
|
|
586
|
+
* Repo-root-relative directories treated as browser-targeted for eslint's
|
|
587
|
+
* node-builtins compatibility checks — mirrors
|
|
588
|
+
* `@theholocron/eslint-config`'s `library({ browserPackages })` option.
|
|
589
|
+
* Only needed for a package whose own `eslint.config.ts` already declares
|
|
590
|
+
* `browserPackages` (a deliberate outlier, not the norm — see that
|
|
591
|
+
* package's own config file for why).
|
|
592
|
+
*
|
|
593
|
+
* @example
|
|
594
|
+
* { browserPackages: ["packages/github-client/src/app-auth"] }
|
|
595
|
+
*/
|
|
596
|
+
interface EslintConfig {
|
|
597
|
+
browserPackages?: string[];
|
|
491
598
|
}
|
|
492
599
|
interface ResolvedTuple {
|
|
493
600
|
provider: string;
|
|
@@ -527,7 +634,10 @@ interface ResolvedHolocronConfig {
|
|
|
527
634
|
env?: EnvConfig;
|
|
528
635
|
log?: LogConfig;
|
|
529
636
|
telemetry?: TelemetryConfig;
|
|
637
|
+
eslint?: EslintConfig;
|
|
530
638
|
}
|
|
639
|
+
//#endregion
|
|
640
|
+
//#region src/config/config/config.d.ts
|
|
531
641
|
declare class ConfigError extends Error {
|
|
532
642
|
name: string;
|
|
533
643
|
}
|
|
@@ -540,83 +650,7 @@ declare function resolvePluginPackage(provider: string): string;
|
|
|
540
650
|
declare function resolveEntry(key: CapabilityKey, raw: RawProviderEntry): ResolvedProviderEntry;
|
|
541
651
|
declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
|
|
542
652
|
//#endregion
|
|
543
|
-
//#region src/
|
|
544
|
-
/**
|
|
545
|
-
* Derived custom-properties (#677). Unlike the existing 6 GitHub
|
|
546
|
-
* custom-properties fields (`lifecycle`, `open_source`, `runtime_environment`,
|
|
547
|
-
* `uses_external_packages`, `monorepo`, `branch_protection_level`) — which
|
|
548
|
-
* mirror what `holocron.config.ts` already states explicitly — these four are
|
|
549
|
-
* *derived*: signal that isn't an explicit config field today (framework
|
|
550
|
-
* choice, repo archetype, capability drift). See
|
|
551
|
-
* `.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
|
|
552
|
-
* definitions (#677)" for the full design.
|
|
553
|
-
*/
|
|
554
|
-
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
|
-
}
|
|
562
|
-
interface DeriveProfileInput {
|
|
563
|
-
rootPackageJson: PackageJsonLike | null;
|
|
564
|
-
repoName: string;
|
|
565
|
-
isMonorepo: boolean;
|
|
566
|
-
/** `packages/*` package.json contents, monorepo repos only — used to find the primary published artifact. */
|
|
567
|
-
workspacePackageJsons: PackageJsonLike[];
|
|
568
|
-
}
|
|
569
|
-
/**
|
|
570
|
-
* Repo archetype, in priority order:
|
|
571
|
-
* 1. `*-template` repo name → `template` (independent of package shape).
|
|
572
|
-
* 2. Monorepo whose primary published artifact is a CLI (some workspace
|
|
573
|
-
* package has `bin`) → `platform` — matches `holocron` itself: the CLI is
|
|
574
|
-
* the deliverable, the plugin packages are supporting infrastructure for
|
|
575
|
-
* it, not separate products.
|
|
576
|
-
* 3. Monorepo with no CLI but at least one non-private workspace package →
|
|
577
|
-
* `library` — matches `clients`/`configs`/`utils`/`themes`/
|
|
578
|
-
* `observability`: a family of published packages, none of them a CLI.
|
|
579
|
-
* Checked *before* falling into the root-package branch below, because
|
|
580
|
-
* these repos' own root `package.json` is private and often carries
|
|
581
|
-
* `@theholocron/astro-config` for a docs site built from the monorepo
|
|
582
|
-
* root — without this check they'd wrongly resolve to `docs` off that
|
|
583
|
-
* root-level signal alone, when the docs site is a secondary concern of
|
|
584
|
-
* a library collection, not what the repo fundamentally is.
|
|
585
|
-
* 4. Single-package repo with `package.json#bin` → `cli`.
|
|
586
|
-
* 5. Docs-only site (astro/starlight present, root package private, no
|
|
587
|
-
* publishable exports) → `docs`.
|
|
588
|
-
* 6. Private, non-publishable, non-docs → `app`.
|
|
589
|
-
* 7. Otherwise, a single publishable package → `library`.
|
|
590
|
-
*/
|
|
591
|
-
declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
|
|
592
|
-
/**
|
|
593
|
-
* Detected build/framework tooling — the literal "does this repo need
|
|
594
|
-
* next/vite/tsdown" signal `holocron.config.ts` has no field for today
|
|
595
|
-
* (framework choice isn't a config concept, unlike `providers`/`tasks`).
|
|
596
|
-
* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
|
|
597
|
-
* frameworks show up rather than trying to detect anything on npm.
|
|
598
|
-
*/
|
|
599
|
-
declare function deriveStack(pkg: PackageJsonLike | null): string[];
|
|
600
|
-
/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
|
|
601
|
-
declare function deriveCapabilities(providers: ResolvedProvidersConfig | undefined): string[];
|
|
602
|
-
declare function deriveCompliance(capabilities: readonly string[]): "compliant" | "non-compliant";
|
|
603
|
-
/**
|
|
604
|
-
* The Phase B refinement `deriveCompliance()`'s own doc comment names —
|
|
605
|
-
* *why* a repo is non-compliant, not just that it is. `[]` when compliant.
|
|
606
|
-
* Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
|
|
607
|
-
* table, not two independently-maintained baselines.
|
|
608
|
-
*/
|
|
609
|
-
declare function missingCapabilities(capabilities: readonly string[]): string[];
|
|
610
|
-
/**
|
|
611
|
-
* Reads each workspace package's actual `package.json` content (not just
|
|
612
|
-
* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
|
|
613
|
-
* `platform` detection needs `bin`, which that helper doesn't carry).
|
|
614
|
-
* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
|
|
615
|
-
* own soft-fail behavior.
|
|
616
|
-
*/
|
|
617
|
-
declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
|
|
618
|
-
//#endregion
|
|
619
|
-
//#region src/config/compose.d.ts
|
|
653
|
+
//#region src/config/compose/compose.type.d.ts
|
|
620
654
|
type TaskEntry = NonNullable<HolocronConfig["tasks"]>[number];
|
|
621
655
|
/** A single composable capability fragment. */
|
|
622
656
|
interface Capability {
|
|
@@ -655,6 +689,8 @@ interface ComposedPreset {
|
|
|
655
689
|
domain?: string;
|
|
656
690
|
docs?: DocsConfig;
|
|
657
691
|
}
|
|
692
|
+
//#endregion
|
|
693
|
+
//#region src/config/compose/compose.d.ts
|
|
658
694
|
/**
|
|
659
695
|
* Merge any number of capability fragments into a single preset object that
|
|
660
696
|
* spreads directly into `defineConfig()`.
|
|
@@ -678,20 +714,99 @@ interface ComposedPreset {
|
|
|
678
714
|
*/
|
|
679
715
|
declare function compose(...args: (Capability | Capability[])[]): ComposedPreset;
|
|
680
716
|
//#endregion
|
|
681
|
-
//#region src/config/define-config.d.ts
|
|
717
|
+
//#region src/config/define-config/define-config.d.ts
|
|
682
718
|
declare function defineConfig(config: HolocronConfig): HolocronConfig;
|
|
683
719
|
//#endregion
|
|
684
|
-
//#region src/config/load-config.d.ts
|
|
720
|
+
//#region src/config/load-config/load-config.type.d.ts
|
|
685
721
|
interface LoadedConfig {
|
|
686
722
|
resolved: ResolvedHolocronConfig;
|
|
687
723
|
/** Absolute path to the file the config was read from. */
|
|
688
724
|
filepath: string;
|
|
689
725
|
}
|
|
726
|
+
//#endregion
|
|
727
|
+
//#region src/config/load-config/load-config.d.ts
|
|
690
728
|
/**
|
|
691
|
-
* Read + parse + resolve `holocron.config.*` from the given
|
|
729
|
+
* Read + parse + resolve `holocron.config.*` starting from the given
|
|
730
|
+
* directory, walking up through ancestors to the nearest `.git` boundary
|
|
731
|
+
* when `cwd` itself has no match — every command is usable from any
|
|
732
|
+
* subdirectory of a repo, not only its exact root (see
|
|
733
|
+
* `@theholocron/datapad`'s own doc comment for the stop conditions).
|
|
692
734
|
* Throws {@link ConfigFileError} when nothing is found or a file cannot
|
|
693
|
-
* be loaded, or `ConfigError` when the config
|
|
735
|
+
* be loaded, or `ConfigError` when the config fails schema checks.
|
|
694
736
|
*/
|
|
695
737
|
declare function loadConfig(cwd: string): Promise<LoadedConfig>;
|
|
696
738
|
//#endregion
|
|
697
|
-
|
|
739
|
+
//#region src/commands/setup/derived-properties/derived-properties.type.d.ts
|
|
740
|
+
/**
|
|
741
|
+
* Derived custom-properties (#677). Unlike the existing 6 GitHub
|
|
742
|
+
* custom-properties fields (`lifecycle`, `open_source`, `runtime_environment`,
|
|
743
|
+
* `uses_external_packages`, `monorepo`, `branch_protection_level`) — which
|
|
744
|
+
* mirror what `holocron.config.ts` already states explicitly — these four are
|
|
745
|
+
* *derived*: signal that isn't an explicit config field today (framework
|
|
746
|
+
* choice, repo archetype, capability drift). See
|
|
747
|
+
* `.notes/tech-holocron-platform.spec.md` → "Custom-properties sync — field
|
|
748
|
+
* definitions (#677)" for the full design.
|
|
749
|
+
*/
|
|
750
|
+
type HolocronProfile = "library" | "cli" | "plugin" | "template" | "app" | "docs" | "platform";
|
|
751
|
+
/** The `package.json` shape profile derivation reads — `@theholocron/pkg-utils`'s `PackageJson`, under the name Sentinel already imports. */
|
|
752
|
+
type PackageJsonLike = PackageJson;
|
|
753
|
+
interface DeriveProfileInput {
|
|
754
|
+
rootPackageJson: PackageJsonLike | null;
|
|
755
|
+
repoName: string;
|
|
756
|
+
isMonorepo: boolean;
|
|
757
|
+
/** `packages/*` package.json contents, monorepo repos only — used to find the primary published artifact. */
|
|
758
|
+
workspacePackageJsons: PackageJsonLike[];
|
|
759
|
+
}
|
|
760
|
+
//#endregion
|
|
761
|
+
//#region src/commands/setup/derived-properties/derived-properties.d.ts
|
|
762
|
+
/**
|
|
763
|
+
* Repo archetype, in priority order:
|
|
764
|
+
* 1. `*-template` repo name → `template` (independent of package shape).
|
|
765
|
+
* 2. Monorepo whose primary published artifact is a CLI (some workspace
|
|
766
|
+
* package has `bin`) → `platform` — matches `holocron` itself: the CLI is
|
|
767
|
+
* the deliverable, the plugin packages are supporting infrastructure for
|
|
768
|
+
* it, not separate products.
|
|
769
|
+
* 3. Monorepo with no CLI but at least one non-private workspace package →
|
|
770
|
+
* `library` — matches `clients`/`configs`/`utils`/`themes`/
|
|
771
|
+
* `observability`: a family of published packages, none of them a CLI.
|
|
772
|
+
* Checked *before* falling into the root-package branch below, because
|
|
773
|
+
* these repos' own root `package.json` is private and often carries
|
|
774
|
+
* `@theholocron/astro-config` for a docs site built from the monorepo
|
|
775
|
+
* root — without this check they'd wrongly resolve to `docs` off that
|
|
776
|
+
* root-level signal alone, when the docs site is a secondary concern of
|
|
777
|
+
* a library collection, not what the repo fundamentally is.
|
|
778
|
+
* 4. Single-package repo with `package.json#bin` → `cli`.
|
|
779
|
+
* 5. Docs-only site (astro/starlight present, root package private, no
|
|
780
|
+
* publishable exports) → `docs`.
|
|
781
|
+
* 6. Private, non-publishable, non-docs → `app`.
|
|
782
|
+
* 7. Otherwise, a single publishable package → `library`.
|
|
783
|
+
*/
|
|
784
|
+
declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
|
|
785
|
+
/**
|
|
786
|
+
* Detected build/framework tooling — the literal "does this repo need
|
|
787
|
+
* next/vite/tsdown" signal `holocron.config.ts` has no field for today
|
|
788
|
+
* (framework choice isn't a config concept, unlike `providers`/`tasks`).
|
|
789
|
+
* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
|
|
790
|
+
* frameworks show up rather than trying to detect anything on npm.
|
|
791
|
+
*/
|
|
792
|
+
declare function deriveStack(pkg: PackageJsonLike | null): string[];
|
|
793
|
+
/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
|
|
794
|
+
declare function deriveCapabilities(providers: ResolvedProvidersConfig | undefined): string[];
|
|
795
|
+
declare function deriveCompliance(capabilities: readonly string[]): "compliant" | "non-compliant";
|
|
796
|
+
/**
|
|
797
|
+
* The Phase B refinement `deriveCompliance()`'s own doc comment names —
|
|
798
|
+
* *why* a repo is non-compliant, not just that it is. `[]` when compliant.
|
|
799
|
+
* Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
|
|
800
|
+
* table, not two independently-maintained baselines.
|
|
801
|
+
*/
|
|
802
|
+
declare function missingCapabilities(capabilities: readonly string[]): string[];
|
|
803
|
+
/**
|
|
804
|
+
* Reads each workspace package's actual `package.json` content (not just
|
|
805
|
+
* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
|
|
806
|
+
* `platform` detection needs `bin`, which that helper doesn't carry).
|
|
807
|
+
* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
|
|
808
|
+
* own soft-fail behavior.
|
|
809
|
+
*/
|
|
810
|
+
declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
|
|
811
|
+
//#endregion
|
|
812
|
+
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, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, ElevationRequiredError, 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, 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, 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, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
|