@theholocron/cli 5.0.0-alpha.34 → 5.0.0-alpha.341
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 +418 -97
- package/dist/cli.mjs +21693 -7654
- package/dist/cli.mjs.map +1 -1
- package/dist/compose-BucaYv2k.mjs +319 -0
- package/dist/index-BfArEnkX.d.mts +829 -0
- package/dist/index-XBpiD6Sx.d.mts +2635 -0
- package/dist/index.d.mts +262 -605
- package/dist/index.mjs +412 -358
- package/dist/plugin/capabilities.d.mts +2 -807
- package/dist/plugin/capabilities.mjs +53 -4
- package/dist/presets.d.mts +223 -0
- package/dist/presets.mjs +423 -0
- package/package.json +41 -34
package/dist/index.d.mts
CHANGED
|
@@ -1,546 +1,282 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
1
|
+
import { $ as DnsRecordType, $t as ParseWebhookInput, A as Ci, An as WebhookDashboardInfo, At as MonitoringCheckInput, B as DeployScriptConfig, Bt as NotificationsForumTag, C as BoardTemplate, Cn as Tooling, Ct as MonitoringAlertChannelResult, D as CapabilityKey, Dn as TunnelRoute, Dt as MonitoringAssertionComparison, E as CapabilityImpls, En as TrackerUser, Et as MonitoringAssertion, F as CreateAuthUserInput, Fn as Workers, Ft as NotificationsAccess, G as DeploymentRecord, Gt as NotificationsOnboardingLayout, H as Deployment, Ht as NotificationsLinksLayout, I as Credentials, It as NotificationsApplicationLayout, J as DiscussionPatch, Jt as NotificationsServerLayout, K as DeploymentTarget, Kt as NotificationsPicture, L as CredentialsInspection, Lt as NotificationsChannelLayout, M as CiRunFilter, Mn as WikiProvisionOpts, Mt as MoveReport, N as CiRunStatus, Nn as WikiProxyConfig, Nt as NormalizedAuthUser, O as Cardinality, On as Tunnels, Ot as MonitoringAssertionSource, P as ConnectionStringOptions, Pn as WorkerScriptState, Pt as Notifications, Q as DnsRecordRequest, Qt as PagesConfig, R as DeployFunctionConfig, Rt as NotificationsDelivery, S as BoardSummary, Sn as TeamPermission, St as MonitoringAlertChannelInput, T as BoardView, Tn as TrackerDoctorReport, Tt as MonitoringAlertSettings, U as DeploymentProject, Ut as NotificationsMember, V as DeployScriptResult, Vt as NotificationsLayout, W as DeploymentProjectSettings, Wt as NotificationsMonitoringFeed, X as Dns, Xt as NotificationsSignedIn, Y as DiscussionPost, Yt as NotificationsSignIn, Z as DnsRecord, Zt as NotificationsWelcomeLayout, _ as BoardItem, _n as SourceTeamMember, _t as LabelDef, a as REQUIRED_CAPABILITIES, an as RepoSettings, at as EnsureWebhookResult, b as BoardStatus, bn as StorageBranch, bt as Logs, c as Analytics, cn as SecretScope, ct as EnsuredTunnel, d as AuthEvent, dn as Source, dt as Environments, en as Projects, et as EnsureDiscussionInput, f as AuthEventType, fn as SourceBranch, ft as Errors, g as BoardFieldType, gn as SourceSecurity, gt as Issues, h as BoardField, hn as SourceRulesetDetail, ht as IssueSearchFilter, i as ProviderApiError, in as RepoRef, it as EnsureResult, j as CiRun, jn as Wiki, jt as MonitoringHttpMethod, k as CardinalityFor, kn as Vault, kt as MonitoringCheck, l as Auth, ln as Secrets, lt as Environment, m as AuthUser, mn as SourceRepoInfo, mt as Issue, n as ElevationRequiredError, nn as PullRequest, nt as EnsureRelayResult, o as WebhookVerificationError, on as ResolvedCapability, ot as EnsuredDiscussion, p as AuthIdentity, pn as SourceFile, pt as InspectRelayInput, q as DeploymentTrigger, qt as NotificationsPinnedLayout, r as MissingTokenError, rn as RelayState, rt as EnsureReport, s as isMulti, sn as Ruleset, st as EnsuredResource, t as CARDINALITY, tn as ProviderIdentity, tt as EnsureRelayInput, u as AuthDescription, un as ServerInspection, ut as EnvironmentReviewer, v as BoardRule, vn as StatusCategory, vt as LifecycleResult, w as BoardTemplateFile, wn as ToolingDoctorReport, wt as MonitoringAlertChannelState, x as BoardStatusCategory, xn as TeamEntry, xt as Monitoring, y as BoardState, yn as Storage, yt as LifecycleSlot, z as DeployFunctionResult, zt as NotificationsEveryoneLayout } from "./index-XBpiD6Sx.mjs";
|
|
2
|
+
import { A as RepoSecretsSync, B as TelemetryConfig, C as ProviderOptions, D as RepoProperties, E as RepoConfig, F as ResolvedProvidersConfig, I as ResolvedTuple, L as SingleEntry, M as RepoVariables, N as ResolvedHolocronConfig, O as RepoProtection, P as ResolvedProviderEntry, R as StorybookDeployProject, S as MultiEntry, T as RawProvidersConfig, V as WorkflowWithConfig, _ as DoctorConfig, a as ConfigError, b as HolocronConfig, c as resolveEntry, d as CapabilityConfigPackage, f as ChromaticProjectConfig, g as DocsConfig, h as DevServeConfig, i as TaskEntry, j as RepoValidationConfig, k as RepoSecrets, l as resolvePluginPackage, m as DevConfig, n as Capability, o as credentialsEnvironment, p as CredentialsConfig, r as ComposedPreset, s as resolveConfig, t as compose, u as AppConfig, v as EnvConfig, w as RawProviderEntry, x as LogConfig, y as EslintConfig, z as TaskEntryConfig } from "./index-BfArEnkX.mjs";
|
|
3
|
+
import { AuthError, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, ResolveTokenInput as ResolveTokenInput$1 } from "@theholocron/kyber/secrets";
|
|
4
|
+
import { RequestOptions, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
|
|
5
|
+
import { ConfigFileError } from "@theholocron/kyber/config";
|
|
6
|
+
import { PackageJson } from "@theholocron/pkg-utils";
|
|
4
7
|
import { WorkspacePackage } from "@theholocron/astromech";
|
|
5
|
-
import
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
/**
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
/**
|
|
8
|
+
import "@theholocron/observability/core";
|
|
9
|
+
/** A plugin's `verifyToken` result when the provider accepted the token. */
|
|
10
|
+
interface VerifyTokenSuccess {
|
|
11
|
+
/** Always `true` for an accepted token. */
|
|
12
|
+
ok: true;
|
|
13
|
+
/** "workplace: acme" / "user: cnewton@x" — surfaced in success output. */
|
|
14
|
+
subject: string;
|
|
15
|
+
/** When the token stops working, ISO 8601 in UTC, for a provider that reports it. Absent when unknown or never. */
|
|
16
|
+
expiresAt?: string;
|
|
17
|
+
}
|
|
18
|
+
/** A plugin's `verifyToken` result when the provider rejected the token. */
|
|
19
|
+
interface VerifyTokenFailure {
|
|
20
|
+
/** Always `false` for a rejected token. */
|
|
21
|
+
ok: false;
|
|
22
|
+
/** Reason the token was rejected. Surfaces to the operator. */
|
|
23
|
+
message: string;
|
|
24
|
+
}
|
|
25
|
+
/** What a plugin's `verifyToken` returns: the token was accepted, or it was rejected with a reason. */
|
|
26
|
+
type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
|
|
27
|
+
/** One token a plugin takes, and where it is looked up. */
|
|
28
|
+
interface PluginToken {
|
|
29
|
+
/** The plugin's own environment variable, e.g. `HOLOCRON_ADMIN_TOKEN`. */
|
|
13
30
|
envName: string;
|
|
14
|
-
/**
|
|
31
|
+
/** The vendor's own environment variable, e.g. `CLOUDFLARE_API_TOKEN`; read after `envName` and before the keyring. */
|
|
32
|
+
vendorEnvName?: string;
|
|
33
|
+
/** The OS keyring entry, e.g. `github.admin`. */
|
|
15
34
|
keyringKey: string;
|
|
16
|
-
}
|
|
17
|
-
/**
|
|
18
|
-
* Build a strict, single-feature token resolver.
|
|
19
|
-
*
|
|
20
|
-
* Resolution chain: `--token flag → envName env var → keyring(keyringKey)`.
|
|
21
|
-
* No broad-token fallback — if the feature-specific token is absent the
|
|
22
|
-
* operation fails with a message naming the exact env var to set.
|
|
23
|
-
*/
|
|
24
|
-
declare function createFeatureResolver(config: FeatureResolverConfig): (input?: ResolveTokenInput) => string;
|
|
25
|
-
//#endregion
|
|
26
|
-
//#region src/auth/keyring.d.ts
|
|
27
|
-
/**
|
|
28
|
-
* Keyring-backed bootstrap credential store.
|
|
29
|
-
*
|
|
30
|
-
* Every holocron plugin's bootstrap token (the one it needs before it
|
|
31
|
-
* can talk to its vendor's API) can be stored in the OS keyring under
|
|
32
|
-
* a single reverse-DNS service scope. Managed via `holocron auth`
|
|
33
|
-
* subcommands; consulted at position 4 in every plugin's auth
|
|
34
|
-
* precedence chain (after --token / HOLOCRON_<X>_TOKEN / <native>_TOKEN).
|
|
35
|
-
*
|
|
36
|
-
* See `docs/wiki/specifications/tech-auth-bootstrap.spec.md` for the design rationale.
|
|
37
|
-
*
|
|
38
|
-
* Failure model: keyring access is best-effort. Platforms without a
|
|
39
|
-
* supported credential store (some Linux CI images, sandboxed
|
|
40
|
-
* environments) will throw from the underlying library. Every export
|
|
41
|
-
* here catches and returns a null/empty result rather than propagating
|
|
42
|
-
* — the plugin's precedence chain then falls through to
|
|
43
|
-
* env-var-only paths, which is exactly how CI is meant to work.
|
|
44
|
-
*/
|
|
45
|
-
/**
|
|
46
|
-
* Store or overwrite a bootstrap token for a provider. Returns true on
|
|
47
|
-
* success, false when the underlying keyring is unsupported or errored.
|
|
48
|
-
*/
|
|
49
|
-
declare function setToken(provider: string, token: string): boolean;
|
|
50
|
-
/**
|
|
51
|
-
* Read the bootstrap token for a provider. Returns `null` for both
|
|
52
|
-
* "not stored" and "keyring unavailable" — callers can treat them the
|
|
53
|
-
* same way (fall through to env-var precedence).
|
|
54
|
-
*/
|
|
55
|
-
declare function getToken(provider: string): string | null;
|
|
56
|
-
/**
|
|
57
|
-
* Delete a stored token. Returns true when a token was removed, false
|
|
58
|
-
* when there was nothing to delete or the keyring is unavailable.
|
|
59
|
-
* Distinguishing the two cases isn't worth the surface area — the
|
|
60
|
-
* command output makes the situation clear either way.
|
|
61
|
-
*/
|
|
62
|
-
declare function deleteToken(provider: string): boolean;
|
|
63
|
-
/**
|
|
64
|
-
* List provider slugs with a stored token in this service scope.
|
|
65
|
-
* Uses the library's `findCredentials(service)` — supported on all
|
|
66
|
-
* platforms the underlying credential store supports.
|
|
67
|
-
*/
|
|
68
|
-
declare function listStoredProviders(): string[];
|
|
69
|
-
//#endregion
|
|
70
|
-
//#region src/config/config.d.ts
|
|
71
|
-
/** Structured-logging config. The Axiom **token** never lives here — only in
|
|
72
|
-
* env vars or the OS keyring — but the non-secret dataset name may. */
|
|
73
|
-
interface LogConfig {
|
|
74
35
|
/**
|
|
75
|
-
*
|
|
76
|
-
*
|
|
36
|
+
* `false` when the plugin's `verifyToken` does not apply to this token (it checks a different credential, such as
|
|
37
|
+
* a webhook URL), so `holocron doctor tokens` reports it as set without calling the plugin. Default `true`.
|
|
77
38
|
*/
|
|
78
|
-
|
|
39
|
+
verifiable?: boolean;
|
|
79
40
|
/**
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
* prefer the `HOLOCRON_AXIOM_DATASET` variable.
|
|
41
|
+
* `true` when the plugin only falls back to this token: nothing needs it unless a call names no better source (the
|
|
42
|
+
* Discord webhook a post uses when it names no channel). The checks that expect every token a plugin lists, such as
|
|
43
|
+
* `holocron doctor credentials`, do not expect it, and `holocron auth export` marks it as optional when it has none.
|
|
44
|
+
* Default `false`.
|
|
85
45
|
*/
|
|
86
|
-
|
|
87
|
-
/** Target Axiom dataset, e.g. `"holocron-local"`. */
|
|
88
|
-
dataset?: string;
|
|
89
|
-
};
|
|
46
|
+
optional?: boolean;
|
|
90
47
|
}
|
|
48
|
+
/** Options for a token resolver, without the keyring lookup, which the CLI supplies itself. */
|
|
49
|
+
type ResolveTokenConfig = Omit<ResolveTokenConfig$1, "keyring" | "orgEnvName">;
|
|
50
|
+
/** Settings for a feature-specific token resolver: which env var and keyring entry it reads. */
|
|
51
|
+
interface FeatureResolverConfig {
|
|
52
|
+
/** Env var name for this feature, e.g. `"HOLOCRON_ISSUES_TOKEN"`. */
|
|
53
|
+
envName: string;
|
|
54
|
+
/** Keyring account key, e.g. `"github.issues"`. */
|
|
55
|
+
keyringKey: string;
|
|
56
|
+
/** The vendor named in the "no token" message. Default `GitHub`. */
|
|
57
|
+
vendor?: string;
|
|
58
|
+
}
|
|
59
|
+
/** A resolver from `createFeatureResolver`: call it for the token, or read `token` to see where it looks. */
|
|
60
|
+
type FeatureResolver = ((input?: ResolveTokenInput$1) => string) & {
|
|
61
|
+
/** The environment variable and keyring entry this resolver reads, for `holocron doctor tokens`. */
|
|
62
|
+
readonly token: PluginToken;
|
|
63
|
+
};
|
|
64
|
+
/** A resolver from `createResolveToken`: call it for the token, or read `token` to see where it looks. */
|
|
65
|
+
type TokenResolver = ((input?: ResolveTokenInput$1) => string) & {
|
|
66
|
+
/** The environment variables and keyring entry this resolver reads, for `holocron doctor tokens`. */
|
|
67
|
+
readonly token: PluginToken;
|
|
68
|
+
};
|
|
91
69
|
/**
|
|
92
|
-
*
|
|
93
|
-
* env-var
|
|
94
|
-
*
|
|
95
|
-
*
|
|
96
|
-
* Precedence: `HOLOCRON_TELEMETRY=false` (env) → `telemetry.enabled` (this) →
|
|
97
|
-
* default on. `enabled` never *re-enables* what the env var turned off.
|
|
70
|
+
* The holocron keyring: `get` answers `null` for "not stored" and for "keyring unavailable" alike, so callers fall
|
|
71
|
+
* through to env-var precedence, and remembers the answer for the process (`clearCache` forgets it); `set` and `delete`
|
|
72
|
+
* answer whether they did anything; `list` names the stored providers; `isAvailable` tells an outage from an empty keyring.
|
|
98
73
|
*/
|
|
99
|
-
|
|
100
|
-
/**
|
|
101
|
-
* Repo-level opt-out — the committed peer of `HOLOCRON_TELEMETRY=false`.
|
|
102
|
-
* `false` installs the no-op sinks for the whole run. Default on.
|
|
103
|
-
*/
|
|
104
|
-
enabled?: boolean;
|
|
105
|
-
/**
|
|
106
|
-
* Usage-analytics provider. `"none"` disables PostHog usage analytics while
|
|
107
|
-
* leaving error reporting (Sentry) untouched. Default `"posthog"`.
|
|
108
|
-
*/
|
|
109
|
-
analytics?: "posthog" | "none";
|
|
110
|
-
}
|
|
111
|
-
type ProviderOptions = Record<string, unknown>;
|
|
74
|
+
export declare const keyring: import("@theholocron/kyber/secrets").Keyring;
|
|
112
75
|
/**
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
* @example
|
|
118
|
-
* // @acme/holocron-vault/index.ts
|
|
119
|
-
* import type { CapabilityConfigPackage } from '@theholocron/cli'
|
|
120
|
-
* export default {
|
|
121
|
-
* provider: '1password',
|
|
122
|
-
* options: { vault: 'acme-app' },
|
|
123
|
-
* } satisfies CapabilityConfigPackage
|
|
76
|
+
* Kyber's `createResolveToken` with the keyring, the `HOLOCRON_ORG` variable and the `token` description
|
|
77
|
+
* `holocron doctor tokens` reads filled in, so a plugin stays at a one-liner call site. The chain is the flag, the
|
|
78
|
+
* plugin's variable, the vendor's variable, the `credentials` providers' variables, the keyring.
|
|
124
79
|
*/
|
|
125
|
-
|
|
126
|
-
provider: string;
|
|
127
|
-
options?: ProviderOptions;
|
|
128
|
-
}
|
|
129
|
-
type SingleEntry = string | [provider: string, options: ProviderOptions];
|
|
130
|
-
type MultiEntry = Array<string | [provider: string, options: ProviderOptions]>;
|
|
131
|
-
type RawProviderEntry = SingleEntry | MultiEntry;
|
|
132
|
-
type RawProvidersConfig = Partial<Record<CapabilityKey, RawProviderEntry>>;
|
|
133
|
-
type RepoProtection = "balanced" | "strict" | "none";
|
|
80
|
+
export declare function createResolveToken(config: ResolveTokenConfig): TokenResolver;
|
|
134
81
|
/**
|
|
135
|
-
*
|
|
136
|
-
*
|
|
137
|
-
*
|
|
82
|
+
* Kyber's `createFeatureResolver` for a strict, single-feature token: the flag, the feature's variable, the
|
|
83
|
+
* `credentials` providers' variable of that name, the keyring. No broad-token fallback; if the feature's token is absent
|
|
84
|
+
* the operation fails with a message naming the exact variable to set and `holocron auth set`.
|
|
138
85
|
*/
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
* Custom domain / CNAME (e.g. "docs.theholocron.dev").
|
|
149
|
-
* When set and `homepage` is not explicitly provided, setup derives
|
|
150
|
-
* `homepage` as `https://{domain}/` for package.json and the repo website field.
|
|
151
|
-
*/
|
|
152
|
-
domain?: string;
|
|
153
|
-
/** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
|
|
154
|
-
https?: boolean;
|
|
86
|
+
export declare function createFeatureResolver(config: FeatureResolverConfig): FeatureResolver;
|
|
87
|
+
/** One line a probe reports: `info` for a fact, `ok` / `fail` for a result, `heading` to title the rows that follow. */
|
|
88
|
+
interface ProbeRow {
|
|
89
|
+
/** `ok` or `fail` for a result, `info` for a fact, `heading` to title the rows that follow. */
|
|
90
|
+
status: "ok" | "fail" | "info" | "heading";
|
|
91
|
+
/** The row's short title. */
|
|
92
|
+
label: string;
|
|
93
|
+
/** Further detail, when there is some. */
|
|
94
|
+
detail?: string;
|
|
155
95
|
}
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
96
|
+
/** What a probe is handed. Everything it prints or changes goes through this, so the runner can enforce the rules. */
|
|
97
|
+
interface ProbeContext {
|
|
98
|
+
/** What the person typed after the probe name (`probe deps who vitest` hands `["vitest"]`). */
|
|
99
|
+
args?: readonly string[];
|
|
100
|
+
/**
|
|
101
|
+
* `--lcov <path>`: where a probe that measures coverage also writes an lcov report, on top of the rows it prints.
|
|
102
|
+
* Relative to the repo root. Unset when the flag was not given.
|
|
103
|
+
*/
|
|
104
|
+
lcov?: string;
|
|
105
|
+
/** `--dry-run`: `write` calls are announced and skipped. */
|
|
106
|
+
dryRun: boolean;
|
|
107
|
+
/** Report one line. The text is scrubbed of secrets before it is printed. */
|
|
108
|
+
say(row: ProbeRow): void;
|
|
109
|
+
/**
|
|
110
|
+
* Change something on the provider. The only way to: on `--dry-run` it prints `would <label>` and does not call `fn`,
|
|
111
|
+
* and a probe that did not declare `writes: true` cannot call it.
|
|
112
|
+
*/
|
|
113
|
+
write<T>(label: string, fn: () => Promise<T>): Promise<T | undefined>;
|
|
114
|
+
/** Register how to undo something this probe made. Runs in reverse order on success, failure and Ctrl-C. */
|
|
115
|
+
cleanup(label: string, fn: () => Promise<void>): void;
|
|
116
|
+
/** Mark a value (a token, a signing secret) as one that must never be printed. */
|
|
117
|
+
secret(value: string | undefined): void;
|
|
161
118
|
}
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
* (see `astromech.requiredChecks()`).
|
|
171
|
-
*/
|
|
172
|
-
protection?: RepoProtection;
|
|
173
|
-
/**
|
|
174
|
-
* GitHub teams granted repository access. Synced by `holocron setup`, which
|
|
175
|
-
* also writes `.github/CODEOWNERS` for teams with write-or-higher permission.
|
|
176
|
-
* String shorthand defaults to `push` (Write).
|
|
177
|
-
*/
|
|
178
|
-
teams?: TeamEntry[];
|
|
179
|
-
/** GitHub topics set on the repository. */
|
|
180
|
-
topics?: string[];
|
|
181
|
-
/** GitHub custom properties synced to the org dashboard. */
|
|
182
|
-
properties?: RepoProperties;
|
|
183
|
-
}
|
|
184
|
-
interface AppConfig {
|
|
185
|
-
name: string;
|
|
186
|
-
path: string;
|
|
187
|
-
kind?: string;
|
|
119
|
+
/** A named, on-demand poke at a live provider. */
|
|
120
|
+
interface Probe {
|
|
121
|
+
/** One sentence for `holocron probe`'s listing. */
|
|
122
|
+
summary: string;
|
|
123
|
+
/** Whether it creates or changes anything on the provider. Asked about first, and needs `--yes` without a terminal. */
|
|
124
|
+
writes: boolean;
|
|
125
|
+
/** Runs the probe, reporting and changing things only through `ctx`. */
|
|
126
|
+
run(ctx: ProbeContext): Promise<void>;
|
|
188
127
|
}
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
interface
|
|
193
|
-
/**
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
128
|
+
/** A plugin's probes by name (kebab-case), as returned from `createPlugin` next to `capabilities`. */
|
|
129
|
+
type PluginProbes = Record<string, Probe>;
|
|
130
|
+
/** What a connection probe needs to check a provider's host and token. */
|
|
131
|
+
export interface ConnectionProbeInput {
|
|
132
|
+
/** How the provider is named in output, e.g. `Axiom`. */
|
|
133
|
+
provider: string;
|
|
134
|
+
/** 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). */
|
|
135
|
+
url?: string;
|
|
136
|
+
/** Finds the token the plugin would use. Throws with a message that says where to put one when there is none. */
|
|
137
|
+
token: () => string | Promise<string>;
|
|
138
|
+
/** The plugin's `verifyToken`: asks the provider who the token belongs to. */
|
|
139
|
+
verify: (token: string) => Promise<VerifyTokenResult>;
|
|
140
|
+
/** Stands in for the network, so with one the name lookup (which cannot be stood in for) is not made. */
|
|
141
|
+
fetch?: typeof fetch;
|
|
142
|
+
/** Resolves a hostname. Defaults to the system resolver, unless `fetch` is given. */
|
|
143
|
+
lookup?: (host: string) => Promise<{
|
|
144
|
+
address: string;
|
|
145
|
+
}>;
|
|
146
|
+
/** Longest to wait for the host to answer. Defaults to 10 s. */
|
|
147
|
+
timeoutMs?: number;
|
|
207
148
|
}
|
|
149
|
+
/** A network failure in plain words, with what usually causes it. Never includes anything from a request. */
|
|
150
|
+
export declare function describeNetworkError(err: unknown, timeoutMs: number): string;
|
|
208
151
|
/**
|
|
209
|
-
*
|
|
210
|
-
*
|
|
211
|
-
*
|
|
212
|
-
* The `tokenName` maps to a repository secret named `CHROMATIC_PROJECT_TOKEN_<TOKENNAME>`.
|
|
213
|
-
* Additional fields correspond to chromaui/action inputs and are passed through directly.
|
|
214
|
-
*
|
|
215
|
-
* @see https://www.chromatic.com/docs/monorepos/
|
|
152
|
+
* The `connection` probe every provider offers, for telling a network problem from a credential problem: does the name
|
|
153
|
+
* resolve, does the host answer, is there a token, and does the provider accept it. A step that cannot work because an
|
|
154
|
+
* earlier one failed is reported as not tried rather than failing a second time for the same reason.
|
|
216
155
|
*/
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
*/
|
|
227
|
-
workingDir: string;
|
|
228
|
-
/**
|
|
229
|
-
* Script name to build Storybook. Defaults to `"build:storybook"`.
|
|
230
|
-
* Must accept `--output-dir` pass-through (use `turbo run … --` at root).
|
|
231
|
-
*/
|
|
232
|
-
buildScript?: string;
|
|
233
|
-
/**
|
|
234
|
-
* Path to the Storybook folder relative to `workingDir`, for TurboSnap.
|
|
235
|
-
* Tells Chromatic where to find `.storybook/` when the Storybook config
|
|
236
|
-
* is in a subdirectory. Corresponds to `--storybook-base-dir`.
|
|
237
|
-
*/
|
|
238
|
-
storybookBaseDir?: string;
|
|
239
|
-
/**
|
|
240
|
-
* Glob patterns of files/dirs that should NOT trigger a TurboSnap bailout
|
|
241
|
-
* when changed. Useful for ignoring non-UI changes in a monorepo
|
|
242
|
-
* (e.g. `"./packages/!(ui)/**"` to focus TurboSnap on the UI package).
|
|
243
|
-
* Corresponds to `--untraced`. Accepts a single glob string or array.
|
|
244
|
-
*/
|
|
245
|
-
untraced?: string | string[];
|
|
246
|
-
/**
|
|
247
|
-
* Glob patterns matching story files to snapshot. When set, only matching
|
|
248
|
-
* stories are captured. Corresponds to `--only-story-files`.
|
|
249
|
-
* Cannot be combined with `onlyStoryNames`.
|
|
250
|
-
*/
|
|
251
|
-
onlyStoryFiles?: string;
|
|
252
|
-
/**
|
|
253
|
-
* Exit with code 0 even when visual changes are detected.
|
|
254
|
-
* Useful during initial setup before baselines are approved.
|
|
255
|
-
* Corresponds to `--exit-zero-on-changes`.
|
|
256
|
-
*/
|
|
257
|
-
exitZeroOnChanges?: boolean;
|
|
156
|
+
export declare function connectionProbe(input: ConnectionProbeInput): Probe;
|
|
157
|
+
/** Returns the config unchanged; it exists to type and autocomplete a `holocron.config.ts`. */
|
|
158
|
+
export declare function defineConfig(config: HolocronConfig): HolocronConfig;
|
|
159
|
+
/** A loaded and resolved `holocron.config`. */
|
|
160
|
+
interface LoadedConfig {
|
|
161
|
+
/** The config after `resolveConfig`. */
|
|
162
|
+
resolved: ResolvedHolocronConfig;
|
|
163
|
+
/** Absolute path to the file the config was read from. */
|
|
164
|
+
filepath: string;
|
|
258
165
|
}
|
|
259
166
|
/**
|
|
260
|
-
*
|
|
261
|
-
*
|
|
262
|
-
* `
|
|
167
|
+
* Read + parse + resolve `holocron.config.*` starting from the given
|
|
168
|
+
* directory, walking up through ancestors to the nearest `.git` boundary
|
|
169
|
+
* when `cwd` itself has no match — every command is usable from any
|
|
170
|
+
* subdirectory of a repo, not only its exact root (see
|
|
171
|
+
* `@theholocron/datapad`'s own doc comment for the stop conditions).
|
|
172
|
+
* Throws `ConfigFileError` when nothing is found or a file cannot
|
|
173
|
+
* be loaded, or `ConfigError` when the config fails schema checks.
|
|
263
174
|
*/
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
175
|
+
export declare function loadConfig(cwd: string): Promise<LoadedConfig>;
|
|
176
|
+
interface RoleSyncOutcome {
|
|
177
|
+
role: string;
|
|
178
|
+
team: string;
|
|
179
|
+
plan: RoleSyncPlan;
|
|
180
|
+
/** Members the role was given to (empty on a dry run). */
|
|
181
|
+
added: string[];
|
|
182
|
+
/** Members the role was taken from (empty on a dry run or with `keep`). */
|
|
183
|
+
removed: string[];
|
|
267
184
|
}
|
|
268
|
-
/**
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
* They also drive automatic `paths:` derivation so you never need to write
|
|
277
|
-
* `paths:` manually for deploy entries.
|
|
278
|
-
*/
|
|
279
|
-
type WorkflowWithConfig = Record<string, unknown> & {
|
|
280
|
-
"run-chromatic"?: boolean | {
|
|
281
|
-
projects: ChromaticProjectConfig[];
|
|
282
|
-
};
|
|
283
|
-
/**
|
|
284
|
-
* Docs deployment shorthand. `true` uses the org-standard `docs/` directory;
|
|
285
|
-
* `{ path: "custom" }` uses a custom directory. Both derive a `paths:` entry automatically.
|
|
286
|
-
*/
|
|
287
|
-
docs?: true | {
|
|
288
|
-
path: string;
|
|
289
|
-
};
|
|
290
|
-
/** Storybook apps to deploy alongside docs. Each entry's `path` is appended to `paths:`. */
|
|
291
|
-
storybook?: StorybookDeployProject[];
|
|
292
|
-
};
|
|
293
|
-
/**
|
|
294
|
-
* A `tasks` manifest entry in object form. A bare string entry is shorthand
|
|
295
|
-
* for `{ name, ci: true, local: true }`.
|
|
296
|
-
*/
|
|
297
|
-
interface TaskEntryConfig {
|
|
298
|
-
name: string;
|
|
299
|
-
with?: WorkflowWithConfig;
|
|
300
|
-
paths?: string[];
|
|
301
|
-
linters?: string[];
|
|
302
|
-
/** Emit a `.github/workflows/<name>.yml` thin caller + include in `holocron ci`. Default `true`. */
|
|
303
|
-
ci?: boolean;
|
|
304
|
-
/** Write a `package.json` script + let `holocron run <name>` resolve the task. Default `true`. */
|
|
305
|
-
local?: boolean;
|
|
306
|
-
/** The task's CI check context is a required status check + part of `holocron ci`'s default run. */
|
|
307
|
-
required?: boolean;
|
|
185
|
+
/** One person: their GitHub account and their member id on the notifications provider. */
|
|
186
|
+
interface MemberLink {
|
|
187
|
+
/** The GitHub user id, as a string. It survives a rename; the login does not. */
|
|
188
|
+
github: string;
|
|
189
|
+
/** The GitHub login when the link was made; for reports only. */
|
|
190
|
+
login: string;
|
|
191
|
+
/** The member's id on the notifications provider (for Discord, the user id). */
|
|
192
|
+
member: string;
|
|
308
193
|
}
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
/**
|
|
314
|
-
|
|
315
|
-
/**
|
|
316
|
-
* Active org name for namespaced keyring lookup. When set, token resolution
|
|
317
|
-
* tries `<service>.<org>` before the unnamespaced `<service>` fallback, so
|
|
318
|
-
* a single machine can hold credentials for multiple GitHub orgs without
|
|
319
|
-
* collision. Overridden by `--org` CLI flag or `HOLOCRON_ORG` env var.
|
|
320
|
-
*/
|
|
321
|
-
org?: string;
|
|
322
|
-
/**
|
|
323
|
-
* Org canonical domain (e.g. `"theholocron.dev"`). Subdomains are derived
|
|
324
|
-
* from this — `preview: true` on a deploy workflow resolves the preview base
|
|
325
|
-
* domain as `preview.<domain>`, giving URLs like `<repo>-pr-<n>.<domain>`.
|
|
326
|
-
*/
|
|
327
|
-
domain?: string;
|
|
328
|
-
/**
|
|
329
|
-
* Repository identity and metadata. When set, `PluginLoader` injects
|
|
330
|
-
* `repo.name` into every plugin's `RuntimeContext.repo` so plugins that
|
|
331
|
-
* need a repo (github, etc.) don't require `--repo` on every invocation.
|
|
332
|
-
* `--repo` on the command line still overrides.
|
|
333
|
-
*/
|
|
334
|
-
repo?: RepoConfig;
|
|
335
|
-
/**
|
|
336
|
-
* The task manifest — what this repo runs. Each entry is a task name
|
|
337
|
-
* (backed by a reusable workflow in `theholocron/.github`), or the object
|
|
338
|
-
* form to pass `with:` inputs. `@theholocron/astromech` reads this as the
|
|
339
|
-
* single source for `holocron run` / `holocron ci` / the generated CI
|
|
340
|
-
* workflows / `package.json` scripts.
|
|
341
|
-
*
|
|
342
|
-
* Supported values (intent-facing vocabulary — epic #672, D3):
|
|
343
|
-
* "verification.unitTests" | "verification.typeSafety" | "verification.performance" |
|
|
344
|
-
* "sourceQuality.staticAnalysis" | "sourceQuality.formatting" |
|
|
345
|
-
* "sourceQuality.structuredDataValidation" | "sourceQuality.deadCodeAnalysis" |
|
|
346
|
-
* "security.secretDetection" | "security.codeScanning" |
|
|
347
|
-
* "delivery.build" | "delivery.publish" | "delivery.deploy" | "delivery.bundleSize" |
|
|
348
|
-
* "platform.repoSync" | "platform.commitStandards" | "platform.repoValidation" |
|
|
349
|
-
* "knowledge.wiki" | "knowledge.docs" | "knowledge.components" |
|
|
350
|
-
* "review" | "tag" | "stale" | "greetings" | "dependencies" | "bookkeeping"
|
|
351
|
-
*
|
|
352
|
-
* `holocron setup` writes `.github/workflows/<name>.yml` for each entry,
|
|
353
|
-
* calling the corresponding reusable workflow in `theholocron/.github`.
|
|
354
|
-
* Files are overwritten on each run — they are generated artifacts.
|
|
355
|
-
*
|
|
356
|
-
* ### delivery.deploy / knowledge.docs / knowledge.components
|
|
357
|
-
* `delivery.deploy` uses `docs` and/or `storybook` in `with:` — setup
|
|
358
|
-
* derives `paths:` automatically. `docs: true` uses the org-standard
|
|
359
|
-
* `docs/` directory; `docs: { path: "custom" }` overrides it.
|
|
360
|
-
* `knowledge.docs` / `knowledge.components` are the same underlying
|
|
361
|
-
* mechanism, each dedicated to exactly one type — they imply the
|
|
362
|
-
* corresponding shorthand, so a repo using them never has to spell out
|
|
363
|
-
* `docs: true` / `storybook: […]` itself.
|
|
364
|
-
*
|
|
365
|
-
* ```ts
|
|
366
|
-
* // Docs only (standard layout)
|
|
367
|
-
* { name: "delivery.deploy", with: { docs: true } }
|
|
368
|
-
* // …or equivalently, the dedicated task:
|
|
369
|
-
* "knowledge.docs"
|
|
370
|
-
*
|
|
371
|
-
* // Docs + monorepo storybooks
|
|
372
|
-
* {
|
|
373
|
-
* name: "delivery.deploy",
|
|
374
|
-
* with: {
|
|
375
|
-
* docs: true,
|
|
376
|
-
* storybook: [
|
|
377
|
-
* { name: "web", path: "apps/web" },
|
|
378
|
-
* { name: "ui", path: "packages/ui" },
|
|
379
|
-
* ],
|
|
380
|
-
* },
|
|
381
|
-
* }
|
|
382
|
-
*
|
|
383
|
-
* // Non-standard docs location
|
|
384
|
-
* { name: "delivery.deploy", with: { docs: { path: "packages/site" } } }
|
|
385
|
-
* ```
|
|
386
|
-
*
|
|
387
|
-
* ### run-chromatic
|
|
388
|
-
* For a single-project repo, use `"run-chromatic": true` with a
|
|
389
|
-
* `CHROMATIC_PROJECT_TOKEN` repository secret.
|
|
390
|
-
*
|
|
391
|
-
* For monorepos with multiple Storybooks, use the object form:
|
|
392
|
-
* ```ts
|
|
393
|
-
* "run-chromatic": {
|
|
394
|
-
* projects: [
|
|
395
|
-
* { tokenName: "WEB", workingDir: "apps/web" },
|
|
396
|
-
* { tokenName: "UI", workingDir: "packages/ui" },
|
|
397
|
-
* ]
|
|
398
|
-
* }
|
|
399
|
-
* ```
|
|
400
|
-
* 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.
|
|
404
|
-
*
|
|
405
|
-
* @example
|
|
406
|
-
* ["sourceQuality.staticAnalysis", { "name": "delivery.publish", "with": { "run-build": false } }]
|
|
407
|
-
* { "name": "delivery.deploy", "with": { "docs": true } }
|
|
408
|
-
*/
|
|
409
|
-
tasks?: Array<string | TaskEntryConfig>;
|
|
410
|
-
/**
|
|
411
|
-
* Opt out of `holocron sync`'s `package.json` script writes. Default `true`.
|
|
412
|
-
*/
|
|
413
|
-
syncScripts?: boolean;
|
|
414
|
-
/**
|
|
415
|
-
* The command the synced `"holocron"` `package.json` script runs. Default
|
|
416
|
-
* `"holocron"` (the installed bin). This repo overrides it to run its own
|
|
417
|
-
* build (`"node packages/cli/dist/cli.mjs"`).
|
|
418
|
-
*/
|
|
419
|
-
holocronScript?: string;
|
|
420
|
-
/**
|
|
421
|
-
* Required status-check contexts not backed by a `required` task (codecov
|
|
422
|
-
* gates, the bundle-build check, …). `holocron setup` appends these to the
|
|
423
|
-
* task-derived list from `astromech.requiredChecks()`.
|
|
424
|
-
*/
|
|
425
|
-
extraRequiredChecks?: string[];
|
|
426
|
-
/**
|
|
427
|
-
* Git hooks `holocron setup` installs. `true` / `{ prePush: true }` writes
|
|
428
|
-
* `.husky/pre-push` (runs `holocron ci` before every push); `false` /
|
|
429
|
-
* `{ prePush: false }` opts out. Omitted → on for `protection: "strict"`,
|
|
430
|
-
* off otherwise. `--hooks` / `--no-hooks` on `holocron setup` override.
|
|
431
|
-
*/
|
|
432
|
-
hooks?: boolean | {
|
|
433
|
-
prePush?: boolean;
|
|
434
|
-
};
|
|
435
|
-
providers: RawProvidersConfig;
|
|
436
|
-
apps?: AppConfig[];
|
|
437
|
-
doctor?: DoctorConfig;
|
|
438
|
-
/**
|
|
439
|
-
* Agent runtime that determines where skills are installed by `holocron setup`.
|
|
440
|
-
* Skills are installed to `.agents/skills/<name>/` (canonical) with a
|
|
441
|
-
* relative symlink at the agent-specific path:
|
|
442
|
-
* - `"claude"` → `.claude/skills/<name>` → `../../.agents/skills/<name>`
|
|
443
|
-
* - `"codex"` | `"gemini"` → logged as unsupported; skipped gracefully.
|
|
444
|
-
*/
|
|
445
|
-
agent?: "claude" | "codex" | "gemini";
|
|
446
|
-
/**
|
|
447
|
-
* Skill names from `@theholocron/skills` to install during `holocron setup`.
|
|
448
|
-
* Installed paths are gitignored and managed by setup — do not commit them.
|
|
449
|
-
*
|
|
450
|
-
* @example
|
|
451
|
-
* ["git-safety", "pr-workflow", "commit-standards"]
|
|
452
|
-
*/
|
|
453
|
-
skills?: string[];
|
|
454
|
-
/**
|
|
455
|
-
* GitHub Pages configuration. When present, `holocron setup` calls the
|
|
456
|
-
* Pages API using `HOLOCRON_DEPLOY_TOKEN` (requires `pages:write` + `repo` scope).
|
|
457
|
-
* When absent, Pages is left as-is.
|
|
458
|
-
*
|
|
459
|
-
* @example
|
|
460
|
-
* { build: "workflow", domain: "docs.theholocron.dev", https: true }
|
|
461
|
-
*/
|
|
462
|
-
docs?: DocsConfig;
|
|
463
|
-
/**
|
|
464
|
-
* Environment variable namespace configuration.
|
|
465
|
-
* Declares the prefix(es) this project uses for its env vars so that
|
|
466
|
-
* tooling can generate `.env.example`, validate required vars, and
|
|
467
|
-
* produce accurate documentation without hard-coding prefix strings.
|
|
468
|
-
*
|
|
469
|
-
* @example
|
|
470
|
-
* { namespaces: ["HOLOCRON", "MY_CLI"] }
|
|
471
|
-
*/
|
|
472
|
-
env?: EnvConfig;
|
|
473
|
-
/**
|
|
474
|
-
* Structured-logging config. Only the level belongs here — Axiom
|
|
475
|
-
* credentials come from env vars, never a committed file.
|
|
476
|
-
*
|
|
477
|
-
* @example
|
|
478
|
-
* { level: "debug" }
|
|
479
|
-
*/
|
|
480
|
-
log?: LogConfig;
|
|
481
|
-
/**
|
|
482
|
-
* CLI self-telemetry override layer. Env var (`HOLOCRON_TELEMETRY=false`)
|
|
483
|
-
* still wins; this is the committed way to opt a repo out or drop usage
|
|
484
|
-
* analytics while keeping error reporting.
|
|
485
|
-
*
|
|
486
|
-
* @example
|
|
487
|
-
* { enabled: false }
|
|
488
|
-
* { analytics: "none" }
|
|
489
|
-
*/
|
|
490
|
-
telemetry?: TelemetryConfig;
|
|
194
|
+
/** The file that says which server member is which GitHub account. */
|
|
195
|
+
interface LinksFile {
|
|
196
|
+
/** The file format version. */
|
|
197
|
+
version: 1;
|
|
198
|
+
/** One entry per linked person. */
|
|
199
|
+
links: MemberLink[];
|
|
491
200
|
}
|
|
492
|
-
interface
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
201
|
+
interface RoleSyncPlan {
|
|
202
|
+
/** Team members who are linked and do not hold the role: give it to them. */
|
|
203
|
+
add: Array<{
|
|
204
|
+
member: string;
|
|
205
|
+
login: string;
|
|
206
|
+
}>;
|
|
207
|
+
/** Holders linked to a GitHub account that is no longer on the team: take it away. */
|
|
208
|
+
remove: Array<{
|
|
209
|
+
member: string;
|
|
210
|
+
login: string;
|
|
211
|
+
}>;
|
|
212
|
+
/** Team members with no link: the role cannot reach them until they link their account. */
|
|
213
|
+
unlinked: SourceTeamMember[];
|
|
214
|
+
/** Holders with no link at all. Left alone, because nothing says they should not have it. */
|
|
215
|
+
unknownHolders: Array<{
|
|
216
|
+
member: string;
|
|
217
|
+
name?: string;
|
|
218
|
+
}>;
|
|
219
|
+
/** Linked team members who already hold the role. */
|
|
220
|
+
inSync: number;
|
|
497
221
|
}
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
222
|
+
/** What {@link syncRoles} needs: the providers, the links, and the roles to keep equal to their teams. */
|
|
223
|
+
interface SyncRolesInput {
|
|
224
|
+
/** The provider that lists and changes who holds a role. */
|
|
225
|
+
notifications: Notifications;
|
|
226
|
+
/** The provider that lists a team's members. */
|
|
227
|
+
source: Source;
|
|
228
|
+
/** Who is which person, from the links file. */
|
|
229
|
+
links: LinksFile;
|
|
230
|
+
/** Each role and the team it follows. */
|
|
231
|
+
roles: ReadonlyArray<{
|
|
232
|
+
name: string;
|
|
233
|
+
team: string;
|
|
234
|
+
}>;
|
|
235
|
+
/** The organisation the teams are in; defaults to the source's own. */
|
|
510
236
|
org?: string;
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
hooks?: boolean | {
|
|
518
|
-
prePush?: boolean;
|
|
519
|
-
};
|
|
520
|
-
providers: ResolvedProvidersConfig;
|
|
521
|
-
apps: AppConfig[];
|
|
522
|
-
doctor: DoctorConfig;
|
|
523
|
-
agent?: "claude" | "codex" | "gemini";
|
|
524
|
-
skills?: string[];
|
|
525
|
-
/** Resolved Pages config. `build` is guaranteed present when this field exists. */
|
|
526
|
-
docs?: PagesConfig;
|
|
527
|
-
env?: EnvConfig;
|
|
528
|
-
log?: LogConfig;
|
|
529
|
-
telemetry?: TelemetryConfig;
|
|
237
|
+
/** Report what would change without changing anything. */
|
|
238
|
+
dryRun?: boolean;
|
|
239
|
+
/** Give the role to new team members but do not take it from people who left. */
|
|
240
|
+
keep?: boolean;
|
|
241
|
+
/** Where progress lines go; nowhere when left out. */
|
|
242
|
+
print?: (line: string) => void;
|
|
530
243
|
}
|
|
531
|
-
|
|
532
|
-
|
|
244
|
+
/** What {@link syncRoles} did. */
|
|
245
|
+
interface SyncRolesResult {
|
|
246
|
+
/** One entry per role whose plan could be made. */
|
|
247
|
+
roles: RoleSyncOutcome[];
|
|
248
|
+
/** Steps that failed; the run carried on past each. */
|
|
249
|
+
failures: Array<{
|
|
250
|
+
step: string;
|
|
251
|
+
message: string;
|
|
252
|
+
}>;
|
|
253
|
+
/** Roles given or taken. */
|
|
254
|
+
ok: number;
|
|
255
|
+
/** Already in sync, left alone, or only previewed. */
|
|
256
|
+
skipped: number;
|
|
533
257
|
}
|
|
258
|
+
/** What a source provider needs to be able to do to feed a role sync, or the reason it cannot. */
|
|
259
|
+
export declare function sourceProblem(source: Source | undefined): string | undefined;
|
|
260
|
+
/** Reads the links file; a file that does not exist yet is an empty one, a damaged one throws. */
|
|
261
|
+
export declare function readLinks(source: Source, layout: NotificationsLayout, org: string | undefined, provider: string): Promise<LinksFile>;
|
|
534
262
|
/**
|
|
535
|
-
*
|
|
536
|
-
*
|
|
537
|
-
* is how third-party plugins published outside the org work.
|
|
263
|
+
* The first role the layout declares for two different teams, or undefined. Names compare ignoring case, as
|
|
264
|
+
* the server does; the role would be synced against one team and then the other, so the last would win.
|
|
538
265
|
*/
|
|
539
|
-
declare function
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
266
|
+
export declare function roleTeamProblem(layout: {
|
|
267
|
+
roles?: ReadonlyArray<{
|
|
268
|
+
name: string;
|
|
269
|
+
team?: string;
|
|
270
|
+
}>;
|
|
271
|
+
}): string | undefined;
|
|
272
|
+
/**
|
|
273
|
+
* Makes each role's holders equal its team, one role after another. This is the sync itself, with no setup in
|
|
274
|
+
* front of it: the caller has already picked the providers, read the links and checked the layout. `holocron
|
|
275
|
+
* notifications sync-roles` and Sentinel's role sync are two callers of it. A step that fails is recorded and the
|
|
276
|
+
* run goes on; nothing here throws for a provider error. Idempotent: a role that already matches changes nothing.
|
|
277
|
+
* Lines go to `input.print` when it is given, and nowhere otherwise.
|
|
278
|
+
*/
|
|
279
|
+
export declare function syncRoles(input: SyncRolesInput): Promise<SyncRolesResult>;
|
|
544
280
|
/**
|
|
545
281
|
* Derived custom-properties (#677). Unlike the existing 6 GitHub
|
|
546
282
|
* custom-properties fields (`lifecycle`, `open_source`, `runtime_environment`,
|
|
@@ -548,20 +284,19 @@ declare function resolveConfig(raw: HolocronConfig): ResolvedHolocronConfig;
|
|
|
548
284
|
* mirror what `holocron.config.ts` already states explicitly — these four are
|
|
549
285
|
* *derived*: signal that isn't an explicit config field today (framework
|
|
550
286
|
* choice, repo archetype, capability drift). See
|
|
551
|
-
*
|
|
287
|
+
* `docs/wiki/specifications/tech-holocron-platform.spec.md` → "Custom-properties sync — field
|
|
552
288
|
* definitions (#677)" for the full design.
|
|
553
289
|
*/
|
|
554
290
|
type HolocronProfile = "library" | "cli" | "plugin" | "template" | "app" | "docs" | "platform";
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
bin?: unknown;
|
|
559
|
-
dependencies?: Record<string, string>;
|
|
560
|
-
devDependencies?: Record<string, string>;
|
|
561
|
-
}
|
|
291
|
+
/** The `package.json` shape profile derivation reads — `@theholocron/pkg-utils`'s `PackageJson`, under the name Sentinel already imports. */
|
|
292
|
+
type PackageJsonLike = PackageJson;
|
|
293
|
+
/** What profile derivation reads to decide a repo's archetype. */
|
|
562
294
|
interface DeriveProfileInput {
|
|
295
|
+
/** The repo's root `package.json`, or `null` when it has none. */
|
|
563
296
|
rootPackageJson: PackageJsonLike | null;
|
|
297
|
+
/** The repository name, without the owner. */
|
|
564
298
|
repoName: string;
|
|
299
|
+
/** Whether the repo is a monorepo with several workspace packages. */
|
|
565
300
|
isMonorepo: boolean;
|
|
566
301
|
/** `packages/*` package.json contents, monorepo repos only — used to find the primary published artifact. */
|
|
567
302
|
workspacePackageJsons: PackageJsonLike[];
|
|
@@ -588,7 +323,7 @@ interface DeriveProfileInput {
|
|
|
588
323
|
* 6. Private, non-publishable, non-docs → `app`.
|
|
589
324
|
* 7. Otherwise, a single publishable package → `library`.
|
|
590
325
|
*/
|
|
591
|
-
declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
|
|
326
|
+
export declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
|
|
592
327
|
/**
|
|
593
328
|
* Detected build/framework tooling — the literal "does this repo need
|
|
594
329
|
* next/vite/tsdown" signal `holocron.config.ts` has no field for today
|
|
@@ -596,17 +331,18 @@ declare function deriveProfile(input: DeriveProfileInput): HolocronProfile;
|
|
|
596
331
|
* Curated table, not exhaustive by design — add to `KNOWN_STACK_DEPS` as new
|
|
597
332
|
* frameworks show up rather than trying to detect anything on npm.
|
|
598
333
|
*/
|
|
599
|
-
declare function deriveStack(pkg: PackageJsonLike | null): string[];
|
|
334
|
+
export declare function deriveStack(pkg: PackageJsonLike | null): string[];
|
|
600
335
|
/** The provider capability keys actually wired in `providers: {}` — zero heuristics. */
|
|
601
|
-
declare function deriveCapabilities(providers: ResolvedProvidersConfig | undefined): string[];
|
|
602
|
-
|
|
336
|
+
export declare function deriveCapabilities(providers: ResolvedProvidersConfig | undefined): string[];
|
|
337
|
+
/** Whether a repo's capabilities include the required baseline (`source` and `ci`); `non-compliant` means drift. */
|
|
338
|
+
export declare function deriveCompliance(capabilities: readonly string[]): "compliant" | "non-compliant";
|
|
603
339
|
/**
|
|
604
340
|
* The Phase B refinement `deriveCompliance()`'s own doc comment names —
|
|
605
341
|
* *why* a repo is non-compliant, not just that it is. `[]` when compliant.
|
|
606
342
|
* Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
|
|
607
343
|
* table, not two independently-maintained baselines.
|
|
608
344
|
*/
|
|
609
|
-
declare function missingCapabilities(capabilities: readonly string[]): string[];
|
|
345
|
+
export declare function missingCapabilities(capabilities: readonly string[]): string[];
|
|
610
346
|
/**
|
|
611
347
|
* Reads each workspace package's actual `package.json` content (not just
|
|
612
348
|
* `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
|
|
@@ -614,84 +350,5 @@ declare function missingCapabilities(capabilities: readonly string[]): string[];
|
|
|
614
350
|
* Missing/invalid files are skipped, matching `readWorkspacePackages()`'s
|
|
615
351
|
* own soft-fail behavior.
|
|
616
352
|
*/
|
|
617
|
-
declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
|
|
618
|
-
|
|
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;
|
|
646
|
-
}
|
|
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;
|
|
657
|
-
}
|
|
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;
|
|
683
|
-
//#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;
|
|
689
|
-
}
|
|
690
|
-
/**
|
|
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.
|
|
694
|
-
*/
|
|
695
|
-
declare function loadConfig(cwd: string): Promise<LoadedConfig>;
|
|
696
|
-
//#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, DnsRecordRequest, 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, WikiProvisionOpts, WikiProxyConfig, Workers, WorkflowWithConfig, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
|
|
353
|
+
export declare function readWorkspacePackageJsons(repoRoot: string, workspacePackages: readonly WorkspacePackage[]): Promise<PackageJsonLike[]>;
|
|
354
|
+
export { Analytics, type AppConfig, Auth, AuthDescription, AuthError, AuthEvent, AuthEventType, AuthIdentity, AuthUser, BoardField, BoardFieldType, BoardItem, BoardRule, BoardState, BoardStatus, BoardStatusCategory, BoardSummary, BoardTemplate, BoardTemplateFile, BoardView, CARDINALITY, type Capability, type CapabilityConfigPackage, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, type ChromaticProjectConfig, Ci, CiRun, CiRunFilter, CiRunStatus, type ComposedPreset, ConfigError, ConfigFileError, ConnectionStringOptions, CreateAuthUserInput, Credentials, type CredentialsConfig, CredentialsInspection, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, type DeriveProfileInput, type DevConfig, type DevServeConfig, DiscussionPatch, DiscussionPost, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, type DocsConfig, type DoctorConfig, ElevationRequiredError, EnsureDiscussionInput, EnsureRelayInput, EnsureRelayResult, EnsureReport, EnsureResult, EnsureWebhookResult, EnsuredDiscussion, EnsuredResource, EnsuredTunnel, type EnvConfig, Environment, EnvironmentReviewer, Environments, Errors, type EslintConfig, type FeatureResolver, type FeatureResolverConfig, type HolocronConfig, type HolocronProfile, InspectRelayInput, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, type LinksFile, type LoadedConfig, type LogConfig, Logs, type MemberLink, MissingTokenError, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAlertChannelState, MonitoringAlertSettings, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, MoveReport, type MultiEntry, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsForumTag, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsMonitoringFeed, NotificationsOnboardingLayout, NotificationsPicture, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, type PackageJsonLike, PagesConfig, ParseWebhookInput, type PluginProbes, type PluginToken, type Probe, type ProbeContext, type ProbeRow, Projects, ProviderApiError, ProviderIdentity, type ProviderOptions, PullRequest, REQUIRED_CAPABILITIES, type RawProviderEntry, type RawProvidersConfig, RelayState, type RepoConfig, type RepoProperties, type RepoProtection, RepoRef, type RepoSecrets, type RepoSecretsSync, RepoSettings, type RepoValidationConfig, 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, SourceBranch, SourceFile, SourceRepoInfo, SourceRulesetDetail, SourceSecurity, SourceTeamMember, StatusCategory, Storage, StorageBranch, type StorybookDeployProject, type SyncRolesInput, type SyncRolesResult, type TaskEntry, type TaskEntryConfig, TeamEntry, TeamPermission, type TelemetryConfig, type TokenResolver, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, TunnelRoute, Tunnels, Vault, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, WorkerScriptState, Workers, type WorkflowWithConfig, compose, createRestClient, credentialsEnvironment, isMulti, resolveConfig, resolveEntry, resolvePluginPackage };
|