@theholocron/cli 5.0.0-alpha.40 → 5.0.0-alpha.401

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.
@@ -0,0 +1,2966 @@
1
+ import { ProviderApiError } from "@theholocron/http-client";
2
+ /**
3
+ * Capability interfaces — the contracts that providers implement.
4
+ *
5
+ * Each capability has a stable key (`'source'`, `'ci'`, …) and a
6
+ * cardinality (`'single'` = one provider; `'many'` = several active
7
+ * at once). The cardinality is part of the type contract via
8
+ * `CardinalityFor<K>` so config resolution + command code can branch
9
+ * statically.
10
+ *
11
+ * See `docs/wiki/specifications/tech-architecture.spec.md` for the design narrative
12
+ * (issue: #74).
13
+ */
14
+ type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "monitoring" | "wiki" | "workers" | "tunnels" | "credentials" | "projects" | "ideas";
15
+ /** How many providers a capability resolves to: one (`"single"`) or several at once (`"many"`). */
16
+ type Cardinality = "single" | "many";
17
+ /** What every capability implementation carries: which capability it is and which provider backs it. */
18
+ interface ProviderIdentity {
19
+ /** The capability this implementation provides. */
20
+ readonly key: CapabilityKey;
21
+ /** The provider's name, e.g. `github` or `vercel`. */
22
+ readonly providerName: string;
23
+ }
24
+ /** A repository ruleset as {@link Source.listRulesets} reports it. */
25
+ interface Ruleset {
26
+ /** The provider's numeric id for the ruleset. */
27
+ id: number;
28
+ /** The ruleset's name. */
29
+ name: string;
30
+ /** Whether the ruleset is enforced (`active`), only logged (`evaluate`) or off (`disabled`). */
31
+ enforcement: "active" | "evaluate" | "disabled";
32
+ /** What the ruleset applies to, e.g. `branch`; `undefined` when the provider does not say. */
33
+ target?: string;
34
+ }
35
+ /** The repository settings {@link Source.updateRepoSettings} can change; a field left out is left alone. */
36
+ interface RepoSettings {
37
+ /** Allow merging a pull request by squashing its commits. */
38
+ allow_squash_merge?: boolean;
39
+ /** Allow merging a pull request with a merge commit. */
40
+ allow_merge_commit?: boolean;
41
+ /** Allow merging a pull request by rebasing its commits. */
42
+ allow_rebase_merge?: boolean;
43
+ /** Allow a pull request to be set to merge itself once its checks pass. */
44
+ allow_auto_merge?: boolean;
45
+ /** Always suggest updating PR branches when the base branch has new commits. */
46
+ allow_update_branch?: boolean;
47
+ /** Delete a pull request's head branch once it is merged. */
48
+ delete_branch_on_merge?: boolean;
49
+ /** The branch a fresh clone checks out. */
50
+ default_branch?: string;
51
+ /** Whether the repository has an issue tracker. */
52
+ has_issues?: boolean;
53
+ /** Whether the repository has discussions. */
54
+ has_discussions?: boolean;
55
+ /** Whether the repository has project boards. */
56
+ has_projects?: boolean;
57
+ /** Whether the repository has a wiki. */
58
+ has_wiki?: boolean;
59
+ }
60
+ /** The repository a {@link Source} provider is scoped to. */
61
+ interface RepoRef {
62
+ /** The account or organization that owns the repository. */
63
+ owner: string;
64
+ /** The repository's name, without the owner. */
65
+ name: string;
66
+ /** The branch a fresh clone checks out. */
67
+ defaultBranch: string;
68
+ }
69
+ /** A repository label as the canonical set passed to {@link Source.syncLabels} defines it. */
70
+ interface LabelDef {
71
+ /** The label's name. */
72
+ readonly name: string;
73
+ /** The label's colour as a hex string. */
74
+ readonly color: string;
75
+ /** What the label is for; an empty string when it has none. */
76
+ readonly description: string;
77
+ }
78
+ /** The access level a team can hold on a repository, from least (`pull`) to most (`admin`). */
79
+ type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
80
+ /** Shorthand `"slug"` defaults to `push` permission. */
81
+ type TeamEntry = string | {
82
+ slug: string;
83
+ permission: TeamPermission;
84
+ };
85
+ /** The repository's own settings, as {@link Source.getRepoInfo} reports them. */
86
+ interface SourceRepoInfo {
87
+ /** `null` when none is set. */
88
+ description: string | null;
89
+ /** `null` when none is set. */
90
+ homepage: string | null;
91
+ /** The branch a fresh clone checks out. */
92
+ defaultBranch: string;
93
+ /** The topics set on the repository. */
94
+ topics: string[];
95
+ /** The merge and feature settings the provider reports; one it does not report is left out. */
96
+ settings: RepoSettings;
97
+ }
98
+ /** A ruleset in full, as {@link Source.getRulesetDetail} reports it. */
99
+ interface SourceRulesetDetail {
100
+ /** The ruleset's name. */
101
+ name: string;
102
+ /** Whether the ruleset is enforced. */
103
+ enforcement: Ruleset["enforcement"];
104
+ /** The `type` of each rule, e.g. `deletion`, `pull_request`. */
105
+ ruleTypes: string[];
106
+ /** The status check contexts the ruleset requires. */
107
+ requiredChecks: string[];
108
+ }
109
+ /** Which security features are on, as {@link Source.getSecurity} reports them. A feature left out was not reported. */
110
+ interface SourceSecurity {
111
+ /** Vulnerability alerts are on. */
112
+ vulnerabilityAlerts?: boolean;
113
+ /** Automated security updates are on. */
114
+ automatedSecurityFixes?: boolean;
115
+ /** Secret scanning is on. */
116
+ secretScanning?: boolean;
117
+ /** Secret scanning push protection is on. */
118
+ secretScanningPushProtection?: boolean;
119
+ /** Private vulnerability reporting is on. */
120
+ privateVulnerabilityReporting?: boolean;
121
+ /** Whether CodeQL default setup is configured. */
122
+ codeScanningDefaultSetup?: boolean;
123
+ }
124
+ /** A member of a team, as {@link Source.teamMembers} reports it. */
125
+ interface SourceTeamMember {
126
+ /** The provider's stable id for the person; for GitHub, the numeric user id as a string. */
127
+ id: string;
128
+ /** What they are called now. Can change; never use it as a key. */
129
+ login: string;
130
+ }
131
+ /** A file read by {@link Source.readFile}. */
132
+ interface SourceFile {
133
+ /** The file's text. */
134
+ content: string;
135
+ /** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
136
+ version: string;
137
+ }
138
+ /** Source hosting: the repository, its rulesets, settings, security features, workflow files and pull requests. */
139
+ interface Source extends ProviderIdentity {
140
+ /** Identifies this provider as the `source` capability. */
141
+ readonly key: "source";
142
+ /** Auth sanity-check. Throws ProviderApiError on auth failure. */
143
+ whoami(): Promise<{
144
+ login: string;
145
+ }>;
146
+ /** The repository this provider is scoped to: its owner, name and default branch. */
147
+ getRepo(): Promise<RepoRef>;
148
+ /** Every ruleset on the repository. */
149
+ listRulesets(): Promise<Ruleset[]>;
150
+ /** Create a ruleset from the provider's own payload shape and return it. */
151
+ createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
152
+ /** Replace the ruleset with the given id using the provider's own payload shape. */
153
+ updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
154
+ /** Change the repository's merge and feature settings; only the fields given are changed. */
155
+ updateRepoSettings(settings: RepoSettings): Promise<void>;
156
+ /**
157
+ * Classic branch protection — fallback for private repos on free plans
158
+ * where the Rulesets API (requires Team+) returns 403.
159
+ */
160
+ protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
161
+ /** Turn on vulnerability alerts (dependency advisories) for the repository. */
162
+ enableVulnerabilityAlerts(): Promise<void>;
163
+ /** Turn on automated security updates, which open pull requests for vulnerable dependencies. */
164
+ enableAutomatedSecurityFixes(): Promise<void>;
165
+ /** Turn on secret scanning, and push protection with it. */
166
+ enableSecretScanning(): Promise<void>;
167
+ /** Turn on private vulnerability reporting, so people can report a vulnerability to the maintainers privately. */
168
+ enablePrivateVulnerabilityReporting(): Promise<void>;
169
+ /**
170
+ * Enables the dependency graph and automatic dependency snapshot
171
+ * submission. Also enables secret-scanning validity checks and
172
+ * non-provider pattern detection — these require GitHub Advanced
173
+ * Security at the org level; the call is accepted but may be a no-op
174
+ * until that is configured.
175
+ */
176
+ enableDependencyGraph(): Promise<void>;
177
+ /**
178
+ * Enables CodeQL default setup with the extended query suite and
179
+ * `threat_model: all` (scans both remote and local exploit paths).
180
+ * Triggers a new analysis run; returns the run id.
181
+ */
182
+ enableCodeScanning(): Promise<string>;
183
+ /**
184
+ * Disables CodeQL default setup. Required when the repo uses an advanced
185
+ * CodeQL workflow instead — GitHub rejects SARIF from advanced workflows
186
+ * while default setup is active.
187
+ */
188
+ disableDefaultCodeScanning(): Promise<void>;
189
+ /** The file names in the workflow directory, sorted; empty when the directory does not exist. */
190
+ listWorkflowFiles(): Promise<string[]>;
191
+ /** The contents of one workflow file, or `null` when it does not exist. */
192
+ readWorkflowFile(name: string): Promise<string | null>;
193
+ /** Write one workflow file, creating the workflow directory if needed and replacing a file of that name. */
194
+ writeWorkflowFile(name: string, contents: string): Promise<void>;
195
+ /** Delete one workflow file; one that is already gone is not an error. */
196
+ removeWorkflowFile(name: string): Promise<void>;
197
+ /**
198
+ * Write an arbitrary file relative to the repo root. Used for
199
+ * provisioning config files that live outside `.github/workflows/`
200
+ * (e.g. `.github/dependabot.yml`).
201
+ */
202
+ writeRepoFile(path: string, contents: string): Promise<void>;
203
+ /**
204
+ * Idempotently sync repo labels to a canonical set. Creates missing
205
+ * labels, patches color/description drift, deletes stale labels.
206
+ * Optional — providers that have no label concept omit this.
207
+ */
208
+ syncLabels?(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
209
+ /**
210
+ * Set org-level custom property values on the repo. `string[]` for
211
+ * `multi_select` properties, plain `string` for everything else.
212
+ * Optional — providers that don't support custom properties omit this.
213
+ */
214
+ syncProperties?(values: Record<string, string | string[]>): Promise<string>;
215
+ /**
216
+ * Replace the repo's topic set with the supplied list.
217
+ * Optional — providers that don't support topics omit this.
218
+ */
219
+ syncTopics?(topics: string[]): Promise<string>;
220
+ /**
221
+ * Bring the repository's Actions variables in line with the declared ones: create what is missing, update what
222
+ * differs, leave the rest. With `prune`, also delete the ones the declaration does not name. With `dryRun`, read the current
223
+ * state and report what would change without writing. Returns a summary.
224
+ * Optional — providers without Actions variables omit this.
225
+ */
226
+ syncVariables?(variables: Record<string, string>, opts?: {
227
+ prune?: boolean;
228
+ dryRun?: boolean;
229
+ }): Promise<string>;
230
+ /**
231
+ * The same for the organization's variables, each with the repositories that can read it (`all` or `private`).
232
+ * Optional — providers without organization variables omit this.
233
+ */
234
+ syncOrgVariables?(org: string, variables: Record<string, {
235
+ value: string;
236
+ visibility: "all" | "private";
237
+ }>, opts?: {
238
+ prune?: boolean;
239
+ dryRun?: boolean;
240
+ }): Promise<string>;
241
+ /**
242
+ * The repository's Actions variables as they are now, by name, with their values. Read-only.
243
+ * Optional — providers without Actions variables omit this.
244
+ */
245
+ listVariables?(): Promise<Record<string, string>>;
246
+ /**
247
+ * The organization's Actions variables as they are now, by name, with each value and the repositories that can read
248
+ * it (`selected` is a list this interface does not manage). Read-only. Throws {@link MissingTokenError} when the
249
+ * provider has no token that can read them.
250
+ * Optional — providers without organization variables omit this.
251
+ */
252
+ listOrgVariables?(org: string): Promise<Record<string, {
253
+ value: string;
254
+ visibility: "all" | "private" | "selected";
255
+ }>>;
256
+ /**
257
+ * The repository's description, homepage, default branch, topics and merge/feature settings as they are now.
258
+ * Read-only. Optional — providers that cannot report them omit this.
259
+ */
260
+ getRepoInfo?(): Promise<SourceRepoInfo>;
261
+ /**
262
+ * The repository's custom property values as they are now, by property name. A property that is not set is left out.
263
+ * Read-only. Optional — providers without custom properties omit this.
264
+ */
265
+ getProperties?(): Promise<Record<string, string | string[]>>;
266
+ /**
267
+ * What is wrong with `values` when compared with the organization's custom property definitions: one sentence per
268
+ * value a `single_select` or `multi_select` property does not allow, per property the organization does not
269
+ * define, or per `true_false` property that is not `true` or `false`. Empty when every value is allowed, and
270
+ * `undefined` when the definitions cannot be read (the token lacks the organization's custom properties
271
+ * permission). Read-only. Optional — providers without custom properties omit this.
272
+ */
273
+ checkPropertyValues?(values: Record<string, string | string[]>): Promise<string[] | undefined>;
274
+ /**
275
+ * The values the organization's `single_select` or `multi_select` custom property `name` allows, or `undefined` when
276
+ * the definitions cannot be read, the property does not exist or it takes any value. Read-only. Optional.
277
+ */
278
+ getOrgPropertyValues?(name: string): Promise<string[] | undefined>;
279
+ /**
280
+ * Adds the values the organization's custom property `name` does not allow yet and returns the ones it added. Never
281
+ * removes or reorders a value, and keeps the rest of the definition as it is. Rejects when the property does not
282
+ * exist or the token cannot write it (the organization's Custom properties: admin). Optional.
283
+ */
284
+ addOrgPropertyValues?(name: string, values: string[]): Promise<string[]>;
285
+ /**
286
+ * The repository's labels as they are now. Read-only.
287
+ * Optional — providers without labels omit this.
288
+ */
289
+ listLabels?(): Promise<LabelDef[]>;
290
+ /**
291
+ * The teams that have access to the repository, with each team's permission. Read-only.
292
+ * Optional — providers without a team concept omit this.
293
+ */
294
+ listTeamAccess?(): Promise<Array<{
295
+ slug: string;
296
+ permission: TeamPermission;
297
+ }>>;
298
+ /**
299
+ * One ruleset in full: its enforcement, the types of its rules and the status checks it requires. Read-only.
300
+ * Optional — providers without rulesets omit this.
301
+ */
302
+ getRulesetDetail?(id: number): Promise<SourceRulesetDetail>;
303
+ /**
304
+ * Which security features are on. A feature the provider cannot report (the token cannot see it, the plan lacks it)
305
+ * is left out rather than reported as off. Read-only.
306
+ * Optional — providers without security toggles omit this.
307
+ */
308
+ getSecurity?(): Promise<SourceSecurity>;
309
+ /**
310
+ * Sync GitHub team repository access. String shorthand defaults to `push`.
311
+ * Optional — providers without a team concept omit this.
312
+ */
313
+ syncTeams?(teams: TeamEntry[]): Promise<string>;
314
+ /**
315
+ * The members of a team in `org` (default: the repo's organisation), by the provider's own stable id (for GitHub, the
316
+ * numeric user id, which survives a rename) and current login.
317
+ * Optional — providers without a team concept omit this.
318
+ */
319
+ teamMembers?(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
320
+ /**
321
+ * Read one file from a repository (default: this one), with the `version` a later {@link writeFile} must
322
+ * hand back. `null` when the file does not exist.
323
+ * Optional — providers that cannot read file contents omit this.
324
+ */
325
+ readFile?(path: string, repo?: string): Promise<SourceFile | null>;
326
+ /**
327
+ * Create or replace one file in a single commit. Pass the `version` {@link readFile} returned when
328
+ * replacing, and leave it out when creating: a write on top of a version that has since changed is
329
+ * refused (throws a `ProviderApiError` with status 409 or 422), so two writers cannot overwrite each other.
330
+ * Optional — providers that cannot write file contents omit this.
331
+ */
332
+ writeFile?(path: string, content: string, opts: {
333
+ message: string;
334
+ version?: string;
335
+ repo?: string;
336
+ }): Promise<void>;
337
+ /**
338
+ * Set the repository description.
339
+ * Optional — providers that don't support setting descriptions omit this.
340
+ */
341
+ syncDescription?(description: string): Promise<string>;
342
+ /**
343
+ * Set the repository homepage URL (the "Website" field on the repo landing page).
344
+ * Optional — providers that don't support setting a homepage omit this.
345
+ */
346
+ syncHomepage?(homepage: string): Promise<string>;
347
+ /**
348
+ * Fetch a pull request by number. The `repo` override lets callers look up
349
+ * a PR in a different repo than the one the plugin is scoped to — useful
350
+ * when the cleanup command targets another repo's PR (e.g. docs PR from
351
+ * the holocron repo context).
352
+ * Optional — providers without a PR concept omit this.
353
+ */
354
+ getPullRequest?(number: number, repo?: string): Promise<PullRequest>;
355
+ /**
356
+ * Every pull request in one state, newest first. `closed` includes the merged ones (`merged` tells them
357
+ * apart). Optional — providers without a PR concept omit this.
358
+ */
359
+ listPullRequests?(state: "open" | "closed", repo?: string): Promise<PullRequest[]>;
360
+ /**
361
+ * The commit SHAs of one pull request, in commit order. A squash-merged branch is not an ancestor of the
362
+ * base, so this is how a local tip is matched to a PR whose head commit is not in the checkout.
363
+ * Optional — providers without a PR concept omit this.
364
+ */
365
+ listPullRequestCommits?(number: number, repo?: string): Promise<string[]>;
366
+ /**
367
+ * Every branch on the remote, with the commit each points at.
368
+ * Optional — providers without branches omit this.
369
+ */
370
+ listBranches?(repo?: string): Promise<SourceBranch[]>;
371
+ /**
372
+ * Delete one branch on the remote. Idempotent: a branch that is already gone is success, not an error.
373
+ * Optional — providers that cannot delete a branch omit this.
374
+ */
375
+ deleteBranch?(name: string, repo?: string): Promise<void>;
376
+ /**
377
+ * Enable or update GitHub Pages for the repository.
378
+ * Idempotent: POST to create, PUT to update existing settings.
379
+ * Requires HOLOCRON_DEPLOY_TOKEN (pages:write + repo scope) — passed
380
+ * explicitly because it is a different PAT from the main admin token.
381
+ * Optional — providers without a Pages concept omit this.
382
+ */
383
+ configurePages?(config: PagesConfig, token: string): Promise<void>;
384
+ }
385
+ /** How GitHub Pages is set up for a repository, as {@link Source.configurePages} takes it. */
386
+ interface PagesConfig {
387
+ /** GitHub Pages build source. */
388
+ build: "workflow" | "branch";
389
+ /**
390
+ * Custom domain / CNAME (e.g. "docs.theholocron.dev").
391
+ * When set and `homepage` is absent in holocron.config, setup derives
392
+ * homepage as `https://{domain}/`.
393
+ */
394
+ domain?: string;
395
+ /** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
396
+ https?: boolean;
397
+ }
398
+ /** A branch on the remote and the commit it points at. */
399
+ interface SourceBranch {
400
+ /** The branch name, e.g. `fix/my-change`. */
401
+ name: string;
402
+ /** The commit the branch points at. */
403
+ sha: string;
404
+ }
405
+ /** A pull request as {@link Source.getPullRequest} and {@link Source.listPullRequests} report it. */
406
+ interface PullRequest {
407
+ /** The pull request's number within the repository. */
408
+ number: number;
409
+ /** The pull request's title. */
410
+ title: string;
411
+ /** "open" | "closed" — GitHub marks merged PRs as "closed". */
412
+ state: "open" | "closed";
413
+ /** True when the PR was merged (as opposed to closed without merging). */
414
+ merged: boolean;
415
+ /** The head branch name (e.g. "fix/my-change"). */
416
+ branch: string;
417
+ /** The commit the head branch pointed at when the PR was last read. */
418
+ headSha?: string;
419
+ /** The address of the pull request's page. */
420
+ url: string;
421
+ }
422
+ /** Where a workflow run is in its life; a finished run carries its outcome (`success`, `failure`, ...). */
423
+ type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
424
+ /** One run of a CI workflow. */
425
+ interface CiRun {
426
+ /** The provider's id for the run. */
427
+ id: string | number;
428
+ /** The workflow's name, falling back to the run's display title. */
429
+ workflowName: string;
430
+ /** The branch the run was triggered on. */
431
+ branch: string;
432
+ /** The commit the run was for. */
433
+ sha: string;
434
+ /** Where the run is, or how it ended once finished. */
435
+ status: CiRunStatus;
436
+ /** The address of the run's page. */
437
+ url: string;
438
+ /** When the run started, as an ISO timestamp. */
439
+ startedAt: string;
440
+ /** When the run finished, as an ISO timestamp; `undefined` while it is still going. */
441
+ completedAt?: string;
442
+ }
443
+ /** What {@link Ci.listRuns} narrows its result by; a field left out does not filter. */
444
+ interface CiRunFilter {
445
+ /** Only runs on this branch. */
446
+ branch?: string;
447
+ /** Only runs in this state. */
448
+ status?: CiRunStatus;
449
+ /** The most runs to return. */
450
+ limit?: number;
451
+ }
452
+ /** CI history: lists workflow runs and reads one back, with no way to start or change one. */
453
+ interface Ci extends ProviderIdentity {
454
+ /** Identifies this provider as the `ci` capability. */
455
+ readonly key: "ci";
456
+ /** Recent workflow runs, narrowed by `filter` when given. */
457
+ listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
458
+ /** One workflow run by its id. */
459
+ getRun(id: string | number): Promise<CiRun>;
460
+ }
461
+ /** Where a secret lives: the repository, one of its environments, or the organization. */
462
+ type SecretScope = {
463
+ kind: "repo";
464
+ } | {
465
+ kind: "environment";
466
+ name: string;
467
+ } | {
468
+ kind: "organization";
469
+ name: string;
470
+ };
471
+ /** A destination for secrets (CI or platform secrets) that `holocron secrets sync` writes into. */
472
+ interface Secrets extends ProviderIdentity {
473
+ /** Identifies this provider as the `secrets` capability. */
474
+ readonly key: "secrets";
475
+ /** List secret NAMES (not values) at the given scope. */
476
+ listSecrets(scope: SecretScope): Promise<string[]>;
477
+ /** Idempotent upsert. Adapter handles encryption. */
478
+ setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
479
+ /** Remove a secret at the given scope. */
480
+ deleteSecret(scope: SecretScope, name: string): Promise<void>;
481
+ }
482
+ /** Someone whose approval a deployment to an environment needs. */
483
+ interface EnvironmentReviewer {
484
+ /** Whether the reviewer is a person (`User`) or a team (`Team`). */
485
+ type: "User" | "Team";
486
+ /** Numeric id — GitHub's reviewer API silently ignores login strings. */
487
+ id: number;
488
+ }
489
+ /** A named deployment environment and the protection rules on it. */
490
+ interface Environment {
491
+ /** The environment's name, e.g. `production`. */
492
+ name: string;
493
+ /** Who must approve a deployment to the environment. */
494
+ reviewers?: EnvironmentReviewer[];
495
+ /** Minutes a deployment waits before it proceeds. */
496
+ waitTimer?: number;
497
+ /** Whether the person who started a deployment is barred from approving it. */
498
+ preventSelfReview?: boolean;
499
+ }
500
+ /** Named deployment environments and their protection rules. */
501
+ interface Environments extends ProviderIdentity {
502
+ /** Identifies this provider as the `environments` capability. */
503
+ readonly key: "environments";
504
+ /** Every environment on the repository. */
505
+ listEnvironments(): Promise<Environment[]>;
506
+ /** Create the environment, or bring an existing one of that name in line with `env`. */
507
+ upsertEnvironment(env: Environment): Promise<void>;
508
+ /** Delete the environment with the given name. */
509
+ deleteEnvironment(name: string): Promise<void>;
510
+ }
511
+ /** A step in an issue's life that {@link Issues.transition} can move it to. */
512
+ type LifecycleSlot = "inProgress" | "inReview" | "done";
513
+ /** The tracker-neutral group a provider's own status names fall into. */
514
+ type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
515
+ /** A person in the issue tracker. */
516
+ interface TrackerUser {
517
+ /** The tracker's id for the person. */
518
+ id: string;
519
+ /** The name shown for the person. */
520
+ displayName: string;
521
+ /** Their email address, when the tracker shares it. */
522
+ emailAddress?: string;
523
+ }
524
+ /** An issue in the tracker, in a shape that does not depend on the provider. */
525
+ interface Issue {
526
+ /** Human-readable key — "#42" for GitHub, "RANDO-42" for Jira. */
527
+ key: string;
528
+ /** Internal opaque id. */
529
+ id: string;
530
+ /** The issue's title. */
531
+ summary: string;
532
+ /** The issue's description; `undefined` when the provider did not return one. */
533
+ body?: string;
534
+ /** The provider's own status name. */
535
+ status: string;
536
+ /** The group the status falls into. */
537
+ statusCategory: StatusCategory;
538
+ /** Who the issue is assigned to; `null` when nobody. */
539
+ assignee: TrackerUser | null;
540
+ /** When the issue last changed, as an ISO timestamp. */
541
+ updated: string;
542
+ /** The address of the issue's page, when the provider gives one. */
543
+ url?: string;
544
+ }
545
+ /** What {@link Issues.search} narrows its result by; a field left out does not filter. */
546
+ interface IssueSearchFilter {
547
+ /** Restrict to issues assigned to a specific id, or 'currentUser'. */
548
+ assignee?: string | "currentUser";
549
+ /** Exclude issues in the `done` category. */
550
+ openOnly?: boolean;
551
+ /** Max number of issues to return. Adapters apply a sensible default. */
552
+ limit?: number;
553
+ /**
554
+ * Only issues whose title or body contains this text, compared without regard to case. The text is matched
555
+ * literally, markup such as an HTML comment included. Left out, nothing is filtered by text.
556
+ */
557
+ text?: string;
558
+ }
559
+ /** What {@link Issues.transition} did. */
560
+ interface LifecycleResult {
561
+ /** False when no API write happened (already at target state). */
562
+ transitioned: boolean;
563
+ /** Status name the issue is in after this call. */
564
+ status: string;
565
+ /** Adapter-specific note (e.g., "label set" / "closed (completed)"). */
566
+ via?: string;
567
+ }
568
+ /** What {@link Issues.doctor} found about the tracker connection, for `holocron doctor` to print. */
569
+ interface TrackerDoctorReport {
570
+ /** "Authenticated as ..." subject for the spinner. */
571
+ authedAs: string;
572
+ /** Free-form "Project: RANDO" / "Repo: rando-id/rando" identifier. */
573
+ projectLabel: string;
574
+ /** Status values the adapter exposes. */
575
+ statuses: Array<{
576
+ name: string;
577
+ category: StatusCategory;
578
+ }>;
579
+ /**
580
+ * Per-lifecycle-slot readiness check. `resolved` indicates whether
581
+ * the configured value actually maps to something the tracker
582
+ * recognizes; the `note` is the rendered explanation.
583
+ */
584
+ lifecycle: Array<{
585
+ slot: LifecycleSlot;
586
+ value: string | null;
587
+ resolved: boolean;
588
+ note: string;
589
+ }>;
590
+ }
591
+ /** How urgent an issue is, in words no tracker owns. Linear has all five natively; GitHub holds it in a project field. */
592
+ type IssuePriority = "none" | "urgent" | "high" | "medium" | "low";
593
+ /** A comment on an issue, as a migration carries it. */
594
+ interface IssueComment {
595
+ /** Who wrote it, as a display name; the target cannot post as them, so it is named in the text. */
596
+ author?: string;
597
+ /** The comment's text. */
598
+ body: string;
599
+ /** When it was written, as an ISO timestamp. */
600
+ createdAt: string;
601
+ }
602
+ /**
603
+ * An issue with everything a migration can carry, in a shape that does not depend on the provider. `export` produces
604
+ * it and `import` consumes it, so a move between two trackers is one provider's `export` into the other's `import`.
605
+ */
606
+ interface IssueRecord {
607
+ /** The key in the tracker it was read from (`#42`, `ENG-42`). */
608
+ key: string;
609
+ /** The address of the issue's page, which the target records so a second run finds what a first one made. */
610
+ url: string;
611
+ /** The issue's title. */
612
+ title: string;
613
+ /** The issue's description. */
614
+ body?: string;
615
+ /** The provider's own status name, e.g. `In Progress`. */
616
+ status?: string;
617
+ /** The group the status falls into. */
618
+ statusCategory: StatusCategory;
619
+ /** Whether the issue is finished (done or canceled). */
620
+ closed: boolean;
621
+ /** How urgent it is; `undefined` when the source does not hold one. */
622
+ priority?: IssuePriority;
623
+ /** Label names. */
624
+ labels: string[];
625
+ /** Who it is assigned to. */
626
+ assignee?: TrackerUser;
627
+ /** The milestone (GitHub) or project (Linear) it belongs to, by name. */
628
+ milestone?: string;
629
+ /** The key of its parent issue, in the source tracker. */
630
+ parent?: string;
631
+ /** Keys, in the source tracker, of the issues that block it. */
632
+ blockedBy: string[];
633
+ /** Its comments, oldest first. */
634
+ comments: IssueComment[];
635
+ /** When it was created, as an ISO timestamp. */
636
+ createdAt: string;
637
+ /** When it last changed, as an ISO timestamp. */
638
+ updatedAt: string;
639
+ /**
640
+ * The source address this issue itself carries because a migration or a sync made it from another tracker (the
641
+ * `holocron:migrated-from` marker on GitHub, the `Migrated from` attachment on Linear). A sync skips such an issue,
642
+ * which is what keeps two one-way syncs from echoing each other's work.
643
+ */
644
+ migratedFrom?: string;
645
+ }
646
+ /** Which issues {@link Issues.export} reads. Set one of `keys`, `milestone` or `all`. */
647
+ interface IssueSelector {
648
+ /** Exactly these issues. */
649
+ keys?: string[];
650
+ /** Every issue of this milestone (GitHub) or project (Linear), by name. */
651
+ milestone?: string;
652
+ /** Every issue the provider is configured for. */
653
+ all?: boolean;
654
+ /** Leave out closed issues. */
655
+ openOnly?: boolean;
656
+ /** Leave out issues last changed before this moment, as an ISO timestamp. */
657
+ since?: string;
658
+ /**
659
+ * Read at most this many issues, a positive integer, counted after `openOnly`, `since` and the skipping of pull
660
+ * requests, so those filters never use up the budget. Which ones is decided by `order`. Without it, every issue the
661
+ * rest of the selector names is read.
662
+ */
663
+ limit?: number;
664
+ /**
665
+ * With `limit`, which end of the creation order is kept: `oldest` (the default) the first created, `newest` the last
666
+ * created. The records come back oldest first either way. Without `limit` it has no effect.
667
+ */
668
+ order?: IssueOrder;
669
+ }
670
+ /** Which end of the creation order a limited {@link Issues.export} keeps: the first-created or the last-created issues. */
671
+ type IssueOrder = "oldest" | "newest";
672
+ /** What {@link Issues.export} reports back about the selection, through its optional second argument. */
673
+ interface ExportInfo {
674
+ /** How many issues the selection matched before `limit` cut it, when the provider knows; for a list of keys, how many keys. */
675
+ matched?: number;
676
+ /**
677
+ * Called after each issue is read, with how many are done and how many are about to be read (after `limit` and the
678
+ * filters where the provider knows, else the number of keys or listed issues). Optional; a provider must never let it
679
+ * throw into the read, and it changes no result. The command uses it for a progress counter on a terminal.
680
+ */
681
+ onProgress?: (done: number, total: number) => void;
682
+ }
683
+ /** What {@link Issues.import} needs besides the records. */
684
+ interface ImportOptions {
685
+ /** Put every imported issue in this milestone (GitHub) or project (Linear), by name; made if missing. */
686
+ milestone?: string;
687
+ /** Change nothing; report what would be made. */
688
+ dryRun?: boolean;
689
+ /**
690
+ * Called after each record is handled (written, or found already there), with how many are done and the number of
691
+ * records. Optional; a provider must never let it throw into the write, and it changes no result. The command uses it
692
+ * for a progress counter on a terminal.
693
+ */
694
+ onProgress?: (done: number, total: number) => void;
695
+ }
696
+ /** What {@link Issues.import} did with one record. */
697
+ interface ImportResult {
698
+ /** The key of the record in the source tracker. */
699
+ source: string;
700
+ /** The key it has in the target, or undefined on a dry run of an issue that does not exist yet. */
701
+ key?: string;
702
+ /** Whether it was made now; false when an earlier run had already made it. */
703
+ created: boolean;
704
+ /** What the target cannot hold of this record and so left out, e.g. `assignee (no matching user)`. */
705
+ dropped: string[];
706
+ }
707
+ /** What {@link Issues.sync} did with one record: an {@link ImportResult} plus what it changed on an issue it already had. */
708
+ interface SyncResult extends ImportResult {
709
+ /** Whether an issue an earlier run made was changed now (or, on a dry run, would be). */
710
+ updated: boolean;
711
+ /** The fields that differed from the source and were set: `title`, `description`, `state`, `priority`, `labels`, `assignee`, `comments`. */
712
+ changes: string[];
713
+ }
714
+ /** An issue tracker: finds, reads, creates, moves and comments on issues. */
715
+ interface Issues extends ProviderIdentity {
716
+ /** Identifies this provider as the `issues` capability. */
717
+ readonly key: "issues";
718
+ /** Currently-authenticated user. */
719
+ getMyself(): Promise<TrackerUser>;
720
+ /** Issues matching `filter`. */
721
+ search(filter: IssueSearchFilter): Promise<Issue[]>;
722
+ /** One issue by its human-readable key (e.g. `#42`). */
723
+ get(key: string): Promise<Issue>;
724
+ /** Open a new issue and return its key. */
725
+ create(input: {
726
+ summary: string;
727
+ body?: string;
728
+ labels?: string[];
729
+ /** Numeric id or exact title (case-insensitive). */
730
+ milestone?: string;
731
+ }): Promise<{
732
+ key: string;
733
+ }>;
734
+ /** Idempotent — `transitioned: false` if the issue is already at the target. */
735
+ transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
736
+ /** Add a comment to the issue. */
737
+ comment(key: string, body: string): Promise<void>;
738
+ /** Check the tracker connection and how the lifecycle slots map onto the tracker's statuses. */
739
+ doctor(): Promise<TrackerDoctorReport>;
740
+ /** Read issues with everything a migration carries. Optional: a provider that cannot be migrated from leaves it out. */
741
+ export?(selector: IssueSelector, info?: ExportInfo): Promise<IssueRecord[]>;
742
+ /**
743
+ * Make the records in this tracker, with their comments, labels, priority and state, and record each one's source
744
+ * address so a second run skips what exists. Two passes: every record is made first, then the `parent` and
745
+ * `blockedBy` links are set, because they point at records made in the same call. Optional.
746
+ */
747
+ import?(records: IssueRecord[], options?: ImportOptions): Promise<ImportResult[]>;
748
+ /**
749
+ * Like `import`, and it also brings up to date what an earlier import or sync made: title, description, state,
750
+ * priority, labels and assignee when they differ from the record, and the comments the issue lacks, oldest first
751
+ * (a comment is never edited or deleted). An issue is changed only when its recorded source address says a
752
+ * migration or sync made it. A rate limit stops the run cleanly: the results returned are the records done, and
753
+ * the caller counts the rest as left. A write that failed is not repeated. Optional: a provider without it cannot
754
+ * be a sync target.
755
+ */
756
+ sync?(records: IssueRecord[], options?: ImportOptions): Promise<SyncResult[]>;
757
+ }
758
+ /** Env-var scope on the deploy platform. */
759
+ type DeploymentTarget = "development" | "preview" | "production";
760
+ /**
761
+ * Named deployment trigger target — `undefined` means a branch
762
+ * preview (no named environment).
763
+ */
764
+ type DeploymentTrigger = "production" | "staging";
765
+ /** A project on the deployment platform. */
766
+ interface DeploymentProject {
767
+ /** The platform's id for the project. */
768
+ id: string;
769
+ /** The project's name. */
770
+ name: string;
771
+ /** The framework preset the project uses, when the platform reports one. */
772
+ framework?: string;
773
+ /** True when the project is linked to a Git provider. */
774
+ gitLinked?: boolean;
775
+ /** The directory in the repository the project builds from; `null` or `undefined` for the repository root. */
776
+ rootDirectory?: string | null;
777
+ }
778
+ /** The project settings {@link Deployment.updateProjectSettings} can change; a field left out is left alone. */
779
+ interface DeploymentProjectSettings {
780
+ /** Turn off preview deployments for the project. */
781
+ previewDeploymentsDisabled?: boolean;
782
+ /** Vercel-specific: whether the GitHub integration creates deployments
783
+ * for every push (false → only on-demand triggers). */
784
+ gitProviderCreateDeployments?: boolean;
785
+ }
786
+ /** One deployment on the platform. */
787
+ interface DeploymentRecord {
788
+ /** The platform's id for the deployment. */
789
+ id: string;
790
+ /** The address the deployment is served at. */
791
+ url: string;
792
+ /** Branch this deployment was made from (null if not git-sourced). */
793
+ branch: string | null;
794
+ /** Named environment if one was targeted; undefined for branch previews. */
795
+ target?: DeploymentTrigger;
796
+ /** Where the deployment is in its build. */
797
+ status: "queued" | "building" | "ready" | "error" | "cancelled";
798
+ /** When the deployment was created, as an ISO timestamp. */
799
+ createdAt?: string;
800
+ /** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
801
+ errorMessage?: string;
802
+ }
803
+ /** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
804
+ interface DeployFunctionConfig {
805
+ /**
806
+ * Files to deploy, keyed by path relative to the project root (e.g.
807
+ * `"api/webhook.js"`, `"package.json"`). Content is plain text — the
808
+ * provider handles any wire-format encoding.
809
+ */
810
+ files: Record<string, string>;
811
+ /**
812
+ * Named deployment target. Omit for a preview deployment — same
813
+ * semantics as `triggerDeployment`'s `target`.
814
+ */
815
+ target?: DeploymentTrigger;
816
+ }
817
+ /** What {@link Deployment.deployFunction} made. */
818
+ interface DeployFunctionResult {
819
+ /** The platform's id for the new deployment. */
820
+ deploymentId: string;
821
+ /** The address the deployment is served at. */
822
+ url: string;
823
+ }
824
+ /** A deployment platform: projects, environment variables and deployments. */
825
+ interface Deployment extends ProviderIdentity {
826
+ /** Identifies this provider as the `deployment` capability. */
827
+ readonly key: "deployment";
828
+ /**
829
+ * Custom domain declared in the deployment provider's configuration.
830
+ * `holocron repo setup` attaches it to the configured project and hands any
831
+ * returned verification record to the `dns` capability.
832
+ */
833
+ readonly domain?: string;
834
+ /** Every project the account can see. */
835
+ listProjects(): Promise<DeploymentProject[]>;
836
+ /** Create if missing, otherwise return existing. Idempotent. */
837
+ ensureProject(input: {
838
+ name: string;
839
+ framework?: string;
840
+ /** "owner/repo" — passed when linking to a Git provider. */
841
+ repo?: string;
842
+ rootDirectory?: string;
843
+ }): Promise<DeploymentProject>;
844
+ /** Change the project's settings; only the fields given are changed. Returns the project afterwards. */
845
+ updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
846
+ /** The names (not values) of the environment variables set on the project for `target`. */
847
+ listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
848
+ /** Set an environment variable on the project for `target`, replacing any existing value. */
849
+ setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
850
+ /**
851
+ * Kick off a deployment of the given branch. Omit `target` for a
852
+ * branch preview; pass `'production'` / `'staging'` to deploy into
853
+ * a named environment.
854
+ */
855
+ triggerDeployment(input: {
856
+ projectId: string;
857
+ branch: string;
858
+ target?: DeploymentTrigger;
859
+ }): Promise<DeploymentRecord>;
860
+ /** One deployment by its id. */
861
+ getDeployment(deploymentId: string): Promise<DeploymentRecord>;
862
+ /**
863
+ * Deploy (or update) a project directly from source files, bypassing
864
+ * Git entirely — the non-git counterpart to `triggerDeployment`, for a
865
+ * consumer with no repo to link (a webhook receiver shipped as an npm
866
+ * package, for instance, rather than deployed from its own Git
867
+ * history). `projectId` may be a project name for providers that
868
+ * accept either. Optional — providers without a files-based deploy API
869
+ * omit this (e.g. Cloudflare Pages, git-source only today).
870
+ */
871
+ deployFunction?(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
872
+ /**
873
+ * List preview deployments for a specific branch alias (e.g. "repo-pr-42").
874
+ * Optional — providers that don't support listing by branch omit this.
875
+ */
876
+ listPreviewDeployments?(projectId: string, branch: string): Promise<DeploymentRecord[]>;
877
+ /**
878
+ * Delete specific preview deployments by id. Returns the count deleted.
879
+ * Optional — providers that don't support deletion omit this.
880
+ */
881
+ deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
882
+ /**
883
+ * Add a custom domain (or wildcard) to the project. Idempotent — no-op
884
+ * when the domain is already present. Optional: providers without a
885
+ * custom domain API omit this.
886
+ *
887
+ * Returns the DNS record needed to finish verification — `null` when
888
+ * the domain is already verified, or when the provider's API doesn't
889
+ * surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
890
+ * custom-domain flow doesn't expose the same per-request verification
891
+ * handshake Vercel's does). Callers hand a non-null result straight
892
+ * to `dns.upsertRecord(result.zone, result.record)` — the exact
893
+ * pattern `setup` already uses for `Wiki.dnsRecord()`.
894
+ */
895
+ ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
896
+ /**
897
+ * The DNS record that points `hostname` at the project, read without changing anything: the read-only half of
898
+ * {@link Deployment.ensureCustomDomain}, which attaches the domain. Unlike `ensureCustomDomain` it returns the
899
+ * record even when the domain already resolves, so `holocron doctor dns` can compare it with the zone. `null`
900
+ * when the provider has no record to recommend. Optional: a provider that cannot be asked omits it.
901
+ */
902
+ expectedDomainRecord?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
903
+ }
904
+ /** A branch of a database or other store, as {@link Storage.listBranches} reports it. */
905
+ interface StorageBranch {
906
+ /** The provider's id for the branch. */
907
+ id: string;
908
+ /** The branch's name. */
909
+ name: string;
910
+ /** Parent branch id; null for the root/main branch. */
911
+ parentId: string | null;
912
+ /** When the branch was created, as an ISO timestamp. */
913
+ createdAt: string;
914
+ }
915
+ /** Options for {@link Storage.getConnectionString}. */
916
+ interface ConnectionStringOptions {
917
+ /** Use the pooled (PgBouncer) URL when available. Defaults to false. */
918
+ pooled?: boolean;
919
+ }
920
+ /** A database or file store: connection strings and, for providers that have them, branches. */
921
+ interface Storage extends ProviderIdentity {
922
+ /** Identifies this provider as the `storage` capability. */
923
+ readonly key: "storage";
924
+ /**
925
+ * Connection string for the given scope. Scope is provider-specific:
926
+ *
927
+ * - branch-based providers (Neon, PlanetScale): scope = branch
928
+ * name or id
929
+ * - flat providers (single Postgres instance): scope is ignored
930
+ *
931
+ * Callers (or the orchestrator) decide how a deploy target maps to
932
+ * a scope; the storage plugin doesn't own that mapping.
933
+ */
934
+ getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
935
+ /** Every branch of the store. */
936
+ listBranches?(): Promise<StorageBranch[]>;
937
+ /** Create a branch named `name`, copied from the `from` branch when given. */
938
+ createBranch?(input: {
939
+ name: string;
940
+ from?: string;
941
+ }): Promise<StorageBranch>;
942
+ /** Delete the branch (by name or id). */
943
+ destroyBranch?(branch: string): Promise<void>;
944
+ /** Restore one branch to match another (e.g., reset preview → main). */
945
+ resetBranch?(input: {
946
+ branch: string;
947
+ from: string;
948
+ }): Promise<void>;
949
+ /**
950
+ * Provider-specific feature toggle. For Postgres providers this is
951
+ * `CREATE EXTENSION IF NOT EXISTS ...` per branch.
952
+ */
953
+ enableExtension?(input: {
954
+ branch: string;
955
+ extension: string;
956
+ }): Promise<void>;
957
+ }
958
+ /** What the auth provider needs the app to be given at runtime. */
959
+ interface AuthDescription {
960
+ /** The provider's name. */
961
+ provider: string;
962
+ /** Env-var names the app needs at runtime (CLERK_PUBLISHABLE_KEY, etc.). */
963
+ envKeys: string[];
964
+ }
965
+ /** What {@link Auth.whoami} found out about the configured credentials. */
966
+ interface AuthIdentity {
967
+ /** The provider's name. */
968
+ provider: string;
969
+ /** Provider-specific health signal (user count, role, account name, etc.). */
970
+ details?: Record<string, unknown>;
971
+ }
972
+ /** A user in the auth provider. */
973
+ interface AuthUser {
974
+ /** The provider's id for the user. */
975
+ id: string;
976
+ /** The user's email address. */
977
+ email: string;
978
+ }
979
+ /** What {@link Auth.createUser} needs to make a user. */
980
+ interface CreateAuthUserInput {
981
+ /** The new user's email address. */
982
+ email: string;
983
+ /** The new user's password. */
984
+ password: string;
985
+ /** The new user's first name. */
986
+ firstName?: string;
987
+ /** The new user's last name. */
988
+ lastName?: string;
989
+ }
990
+ /** Where to configure the auth provider's webhooks. */
991
+ interface WebhookDashboardInfo {
992
+ /** The address of the provider's webhook settings page. */
993
+ url: string;
994
+ }
995
+ /** An identity provider: describes what an app needs from it, proves the credentials work and, where the provider allows, manages users and webhooks. */
996
+ interface Auth extends ProviderIdentity {
997
+ /** Identifies this provider as the `auth` capability. */
998
+ readonly key: "auth";
999
+ /** Env-var keys the runtime app needs. */
1000
+ describe(): Promise<AuthDescription>;
1001
+ /** Reachability probe — proves the configured key works. */
1002
+ whoami(): Promise<AuthIdentity>;
1003
+ /** Idempotent webhook backend provisioning (Clerk: Svix app). */
1004
+ ensureWebhookApp?(): Promise<{
1005
+ alreadyExists: boolean;
1006
+ }>;
1007
+ /** Deep-link to the provider's webhook config dashboard. */
1008
+ getWebhookDashboardUrl?(): Promise<WebhookDashboardInfo>;
1009
+ /** Seed a user (test fixtures, admin bootstrap). */
1010
+ createUser?(input: CreateAuthUserInput): Promise<AuthUser>;
1011
+ /** Wire the auth provider's webhook into the project's repo. */
1012
+ syncWebhook?(input: {
1013
+ repo: string;
1014
+ secretRef: string;
1015
+ }): Promise<void>;
1016
+ }
1017
+ /** What happened to a user, in a form that does not depend on the auth provider. */
1018
+ type AuthEventType = "user.created" | "user.updated" | "user.deleted";
1019
+ /** A user as a webhook event reports it, in a form that does not depend on the auth provider. */
1020
+ interface NormalizedAuthUser {
1021
+ /** The provider's id for the user. */
1022
+ id: string;
1023
+ /** The user's email address. */
1024
+ email: string;
1025
+ /** The user's first name; `null` or `undefined` when none is set. */
1026
+ firstName?: string | null;
1027
+ /** The user's last name; `null` or `undefined` when none is set. */
1028
+ lastName?: string | null;
1029
+ /** Provider-native fields preserved verbatim for consumers that need them. */
1030
+ raw?: Record<string, unknown>;
1031
+ }
1032
+ /** A webhook event from the auth provider, in a form that does not depend on the provider. */
1033
+ interface AuthEvent {
1034
+ /** What happened to the user. */
1035
+ type: AuthEventType;
1036
+ /** The user the event is about. */
1037
+ user: NormalizedAuthUser;
1038
+ /** ISO timestamp of when the event occurred. */
1039
+ occurredAt: string;
1040
+ }
1041
+ /** What a plugin's `parseWebhook` needs to verify and translate an incoming webhook request. */
1042
+ interface ParseWebhookInput {
1043
+ /** Raw request body (string or Buffer). */
1044
+ body: string | Buffer;
1045
+ /** Incoming HTTP headers — needed for signature verification. */
1046
+ headers: Record<string, string | string[] | undefined>;
1047
+ /** The signing secret the auth provider issued for this webhook endpoint. */
1048
+ signingSecret: string;
1049
+ }
1050
+ /** The outcome of an idempotent `ensure*` call that creates a container. */
1051
+ interface EnsureResult {
1052
+ /** True when the resource already existed (idempotent no-op). */
1053
+ alreadyExists: boolean;
1054
+ }
1055
+ /** A secret store, the source of truth that `holocron secrets sync` reads from. */
1056
+ interface Vault extends ProviderIdentity {
1057
+ /** Identifies this provider as the `vault` capability. */
1058
+ readonly key: "vault";
1059
+ /**
1060
+ * Read a secret by reference. The reference format is
1061
+ * provider-specific (1P: "op://Vault/Item/field"; HashiCorp Vault:
1062
+ * "kv/path#field"; etc.). Adapters validate the reference shape.
1063
+ */
1064
+ read(reference: string): Promise<string>;
1065
+ /**
1066
+ * Optional — read a secret by its bare name from the project and config this vault was set up with, instead of by a
1067
+ * full reference. For a provider whose references name the project and config the options already carry (Doppler).
1068
+ */
1069
+ readSecret?(name: string): Promise<string>;
1070
+ /** Write or update a secret. */
1071
+ write(reference: string, value: string): Promise<void>;
1072
+ /** List secret keys available to the project. */
1073
+ list(): Promise<string[]>;
1074
+ /**
1075
+ * Optional environment notion within the vault (e.g., 1P
1076
+ * Environments — named KEY=VALUE bundles). Adapters without
1077
+ * environments return [].
1078
+ */
1079
+ environments?(): Promise<string[]>;
1080
+ /**
1081
+ * Optional bulk read of an environment's KEY=VALUE pairs. Powers
1082
+ * the `holocron secrets sync` flow where the orchestrator pulls a
1083
+ * whole environment from the vault then fans the values out to
1084
+ * destinations (CI secrets, deployment env vars, local .env).
1085
+ */
1086
+ readEnvironment?(environmentId: string): Promise<Record<string, string>>;
1087
+ /**
1088
+ * Optional — create the top-level project container in the vault
1089
+ * if it does not exist. Idempotent: `alreadyExists: true` when the
1090
+ * project was already there. Providers whose data model has no
1091
+ * project notion (or that gate this behind a paid tier) omit this.
1092
+ */
1093
+ ensureProject?(name: string): Promise<EnsureResult>;
1094
+ /**
1095
+ * Optional — create a named environment/config inside a project
1096
+ * (e.g., Doppler config `dev` / `stg` / `prd`). Idempotent.
1097
+ * Providers whose data model has a single flat namespace omit this.
1098
+ */
1099
+ ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
1100
+ }
1101
+ /** The DNS record types a provider can manage. */
1102
+ type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
1103
+ /** A DNS record. */
1104
+ interface DnsRecord {
1105
+ /** The provider's id for the record; absent on a record not yet created. */
1106
+ id?: string;
1107
+ /** The record's type. */
1108
+ type: DnsRecordType;
1109
+ /** The record's name (the host it answers for). */
1110
+ name: string;
1111
+ /** The record's value, e.g. an address for `A` or a target host for `CNAME`. */
1112
+ content: string;
1113
+ /** Time to live in seconds; the provider's default when absent. */
1114
+ ttl?: number;
1115
+ /** Priority, for the record types that have one (`MX`, `SRV`). */
1116
+ priority?: number;
1117
+ /** Whether traffic goes through the provider's proxy; only providers that offer one use it. */
1118
+ proxied?: boolean;
1119
+ }
1120
+ /**
1121
+ * A DNS record a capability wants created, plus which zone it belongs
1122
+ * to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
1123
+ * both hand off to `Dns.upsertRecord()`. Not tied to either capability;
1124
+ * any provider that needs "here's a record, go create it" returns this.
1125
+ */
1126
+ interface DnsRecordRequest {
1127
+ /** Zone apex passed as the first argument to `dns.upsertRecord`. */
1128
+ zone: string;
1129
+ /** The record to create or update. */
1130
+ record: DnsRecord;
1131
+ }
1132
+ /** DNS record management for a domain. */
1133
+ interface Dns extends ProviderIdentity {
1134
+ /** Identifies this provider as the `dns` capability. */
1135
+ readonly key: "dns";
1136
+ /** Every record in the domain's zone. */
1137
+ listRecords(domain: string): Promise<DnsRecord[]>;
1138
+ /** Create the record, or update the existing one that matches it, and return the result. */
1139
+ upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
1140
+ /** Delete the record with the given id from the domain's zone. */
1141
+ deleteRecord(domain: string, id: string): Promise<void>;
1142
+ /**
1143
+ * A `holocron doctor` smoke check with no specific domain to ask about —
1144
+ * `listRecords` needs one, but doctor doesn't have one on hand. Verifies
1145
+ * the token and reports how many zones it can see.
1146
+ */
1147
+ whoami?(): Promise<{
1148
+ ok: boolean;
1149
+ zones: number;
1150
+ }>;
1151
+ }
1152
+ /** Error tracking: describes what an app needs at runtime and, where the provider allows, creates projects and relays alerts. */
1153
+ interface Errors extends ProviderIdentity {
1154
+ /** Identifies this provider as the `errors` capability. */
1155
+ readonly key: "errors";
1156
+ /** Returns the env var names the app reads at runtime for this provider. */
1157
+ describe(): Promise<{
1158
+ provider: string;
1159
+ envKeys: string[];
1160
+ }>;
1161
+ /**
1162
+ * Reachability probe. `null` means the check genuinely can't run right
1163
+ * now on an otherwise-valid configuration (e.g. Sentry's optional `org`
1164
+ * setting is unset — error ingestion still works from the DSN alone,
1165
+ * `org` is only needed for the management-API calls `whoami` makes) —
1166
+ * callers should fall back to `describe()`, not treat it as a failure.
1167
+ * Still throws for a genuine failure (bad token, network error, etc.).
1168
+ */
1169
+ whoami?(): Promise<{
1170
+ org: string;
1171
+ } | null>;
1172
+ /** Create the project if it is missing and return its DSN; `alreadyExists` is true when it was already there. */
1173
+ ensureProject?(input: {
1174
+ name: string;
1175
+ platform?: string;
1176
+ }): Promise<{
1177
+ dsn: string;
1178
+ alreadyExists: boolean;
1179
+ }>;
1180
+ /**
1181
+ * Make the tracker send its alerts to a relay (the Comlink Worker): an integration that posts to `webhookUrl`, and
1182
+ * an alert rule on each project that uses it. Idempotent: an integration or rule with the same name is adopted and
1183
+ * only what differs is changed. `clientSecret` is the integration's signing secret, handed to the caller to give
1184
+ * the relay; it is a credential and must not be printed or stored anywhere but there. It is absent when the
1185
+ * provider did not give it (some show it only when the integration is made).
1186
+ */
1187
+ ensureRelay?(input: EnsureRelayInput): Promise<EnsureRelayResult>;
1188
+ /**
1189
+ * Read back what `ensureRelay` makes without changing anything: the integration and, for each project, whether the
1190
+ * alert rule is on it, enabled and sends through the integration. Never reads the signing secret.
1191
+ * Optional — a provider with no relay omits it.
1192
+ */
1193
+ inspectRelay?(input: InspectRelayInput): Promise<RelayState>;
1194
+ }
1195
+ /** What {@link Errors.ensureRelay} sets up at the error tracker. */
1196
+ interface EnsureRelayInput {
1197
+ /** The integration's name at the provider (also how an existing one is found). */
1198
+ name: string;
1199
+ /** Where the provider posts its alerts, e.g. `https://comlink.theholocron.dev/sentry`. */
1200
+ webhookUrl: string;
1201
+ /** The projects whose issues are sent. */
1202
+ projects: string[];
1203
+ /** The alert rule: its name, and the minutes between two notifications for one issue (default 5). */
1204
+ rule: {
1205
+ /** The alert rule's name at the provider (also how an existing one is found). */
1206
+ name: string;
1207
+ /** Minutes between two notifications for one issue; 5 when absent. */
1208
+ frequency?: number;
1209
+ };
1210
+ }
1211
+ /** Which integration and alert rule to read back: the names `ensureRelay` was given, without the parts that write. */
1212
+ interface InspectRelayInput {
1213
+ /** The integration's name at the provider. */
1214
+ name: string;
1215
+ /** The projects whose issues are sent. */
1216
+ projects: string[];
1217
+ /** The alert rule to look for. */
1218
+ rule: {
1219
+ /** Its name at the provider. */
1220
+ name: string;
1221
+ };
1222
+ }
1223
+ /**
1224
+ * The tracker's side of a relay as the provider holds it. Never carries the integration's signing secret: the read
1225
+ * does not ask for it.
1226
+ */
1227
+ interface RelayState {
1228
+ /** The integration, or undefined when none has that name. */
1229
+ integration?: {
1230
+ /** Where it posts alerts, or null when it has no webhook. */
1231
+ webhookUrl: string | null;
1232
+ /** Whether it is offered as an alert action. */
1233
+ alertAction: boolean;
1234
+ };
1235
+ /** One entry per requested project the rule is attached to; a project missing here has no such rule. */
1236
+ rules: Array<{
1237
+ project: string;
1238
+ enabled: boolean;
1239
+ /** Whether the rule sends through the integration. */
1240
+ sends: boolean;
1241
+ }>;
1242
+ }
1243
+ /** What {@link Errors.ensureRelay} did. */
1244
+ interface EnsureRelayResult {
1245
+ /** The integration that posts to the relay. */
1246
+ integration: {
1247
+ /** Whether it was made now rather than adopted. */
1248
+ created: boolean;
1249
+ /** For one adopted, the settings that differed and were changed. */
1250
+ updated: string[];
1251
+ };
1252
+ /** The alert rule that sends through the integration. */
1253
+ rule: {
1254
+ /** Whether it was made now rather than adopted. */
1255
+ created: boolean;
1256
+ /** For one adopted, the settings that differed and were changed. */
1257
+ updated: string[];
1258
+ };
1259
+ /** The integration's signing secret, for the relay to verify alerts with. A credential: never print or store it. */
1260
+ clientSecret?: string;
1261
+ }
1262
+ /** Log aggregation: describes what an app needs at runtime and, where the provider allows, creates the dataset. */
1263
+ interface Logs extends ProviderIdentity {
1264
+ /** Identifies this provider as the `logs` capability. */
1265
+ readonly key: "logs";
1266
+ /** Returns the env var names the app reads at runtime for this provider. */
1267
+ describe(): Promise<{
1268
+ provider: string;
1269
+ envKeys: string[];
1270
+ }>;
1271
+ /** Verify the token by fetching the target dataset's info. */
1272
+ whoami?(): Promise<{
1273
+ ok: boolean;
1274
+ dataset: string;
1275
+ }>;
1276
+ /** Create the aggregation dataset if it does not already exist. Idempotent. */
1277
+ ensureDataset?(name: string): Promise<{
1278
+ alreadyExists: boolean;
1279
+ }>;
1280
+ /**
1281
+ * Read a dataset without changing anything (`holocron doctor logs`). A dataset that is not there is `exists: false`,
1282
+ * not an error; any other failure throws.
1283
+ */
1284
+ readDataset?(name: string): Promise<LogsDataset>;
1285
+ /**
1286
+ * Ask the provider whether it accepts the token, without needing any particular dataset. `ok: false` only when the
1287
+ * provider refused it; an error that says nothing about the token (a network failure, a missing token) throws.
1288
+ */
1289
+ checkToken?(): Promise<{
1290
+ ok: boolean;
1291
+ reason?: string;
1292
+ }>;
1293
+ }
1294
+ /** What {@link Logs.readDataset} found. */
1295
+ interface LogsDataset {
1296
+ /** Whether the dataset exists. */
1297
+ exists: boolean;
1298
+ /** Days the provider keeps data in the dataset, when it reports one. One setting for the whole dataset. */
1299
+ retentionDays?: number;
1300
+ }
1301
+ /** What part of a response a {@link MonitoringAssertion} looks at. */
1302
+ type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
1303
+ /** How a {@link MonitoringAssertion} compares the part of the response with its target. */
1304
+ type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
1305
+ /** A condition a monitoring check's response must meet to pass. */
1306
+ interface MonitoringAssertion {
1307
+ /** The part of the response to look at. */
1308
+ source: MonitoringAssertionSource;
1309
+ /** How to compare it with `target`. */
1310
+ comparison: MonitoringAssertionComparison;
1311
+ /** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
1312
+ property?: string;
1313
+ /** The value to compare against. */
1314
+ target?: string;
1315
+ }
1316
+ /** The HTTP methods a monitoring check can use. */
1317
+ type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
1318
+ /** A monitoring check, in a form that does not depend on the provider. */
1319
+ interface MonitoringCheckInput {
1320
+ /** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
1321
+ name: string;
1322
+ /** The address to request. */
1323
+ url: string;
1324
+ /** The HTTP method; the provider's default when absent. */
1325
+ method?: MonitoringHttpMethod;
1326
+ /** Minutes between runs. Adapters round to their own supported values. */
1327
+ frequency?: number;
1328
+ /** Conditions the response must meet; the provider's default check when absent. */
1329
+ assertions?: MonitoringAssertion[];
1330
+ /** Whether the check runs; the provider's default when absent. */
1331
+ activated?: boolean;
1332
+ /**
1333
+ * Provider-specific region/datacenter ids to run the check from (e.g.
1334
+ * Checkly's `"us-east-1"`). Required by some providers — there's no
1335
+ * universal default; an account with none configured rejects a check
1336
+ * that omits this entirely.
1337
+ */
1338
+ locations?: string[];
1339
+ /**
1340
+ * Inverts pass/fail: set this when the check's expected-healthy
1341
+ * response is itself an HTTP error status (e.g. asserting a 404/405
1342
+ * on an endpoint that should reject certain requests). Without it,
1343
+ * most providers classify any 4xx/5xx response as a failure at the
1344
+ * platform level *before* evaluating `assertions` at all — a custom
1345
+ * assertion that matches the "expected" error status does not
1346
+ * override that baseline classification on its own.
1347
+ */
1348
+ shouldFail?: boolean;
1349
+ /**
1350
+ * Raw request body to send with the check — e.g. simulating a webhook
1351
+ * delivery to verify signature/auth checking is wired correctly
1352
+ * end-to-end, rather than just confirming the endpoint is reachable.
1353
+ * Omitted entirely by default (no body sent).
1354
+ */
1355
+ body?: string;
1356
+ /**
1357
+ * Route this check to specific alert channels, by their names (the `feeds.monitoring` name of a notifications channel,
1358
+ * `Message to #uptime` by default). Absent, the check alerts through every alert channel; given, only through the
1359
+ * ones named. A name no alert channel carries is refused by `notifications setup`.
1360
+ */
1361
+ alertChannels?: string[];
1362
+ }
1363
+ /** A check as the provider holds it. */
1364
+ interface MonitoringCheck {
1365
+ /** The provider's id for the check. */
1366
+ id: string;
1367
+ /** The check's name. */
1368
+ name: string;
1369
+ }
1370
+ /**
1371
+ * What an alert channel alerts about. A field left out is left alone on an existing channel and, on a new one, takes
1372
+ * the default: `failure`, `recovery` and `degraded` on, `sslExpiry` off.
1373
+ */
1374
+ interface MonitoringAlertSettings {
1375
+ /** Alert when a check fails. */
1376
+ failure?: boolean;
1377
+ /** Alert when a failing check recovers. */
1378
+ recovery?: boolean;
1379
+ /** Alert when a check turns degraded (slower than its degraded threshold). */
1380
+ degraded?: boolean;
1381
+ /** Alert before a certificate expires. */
1382
+ sslExpiry?: boolean;
1383
+ /** Days before expiry that `sslExpiry` alerts at. */
1384
+ sslExpiryThreshold?: number;
1385
+ }
1386
+ /** A place the monitoring provider sends its alerts: a webhook that posts into a chat channel. */
1387
+ interface MonitoringAlertChannelInput {
1388
+ /** Also the idempotency key: an existing channel with this name is adopted and brought in line. */
1389
+ name: string;
1390
+ /** The chat service the message is formatted for. */
1391
+ format: "discord";
1392
+ /**
1393
+ * Where alerts post: a credential, because anyone holding it can post to the channel. Absent when the webhook already
1394
+ * existed and cannot be read back, in which case an existing alert channel keeps the URL it has and a missing one
1395
+ * cannot be created.
1396
+ */
1397
+ url?: string;
1398
+ /** What the channel alerts about; see {@link MonitoringAlertSettings}. */
1399
+ alerts?: MonitoringAlertSettings;
1400
+ }
1401
+ /** What {@link Monitoring.ensureAlertChannel} did. */
1402
+ interface MonitoringAlertChannelResult {
1403
+ /** Whether the channel was made now rather than already existing. */
1404
+ created: boolean;
1405
+ /** For an existing channel, what was brought in line (`"url"`, `"alerts"`, `"subscriptions"`). */
1406
+ updated: string[];
1407
+ /** How many checks the channel is subscribed to afterwards. */
1408
+ subscribed: number;
1409
+ }
1410
+ /**
1411
+ * An alert channel as the provider holds it, for `doctor notifications`. The URL it posts to is a credential and is not
1412
+ * returned: `webhookId` is the public part of a Discord webhook's URL, enough to tell which webhook it posts through.
1413
+ */
1414
+ interface MonitoringAlertChannelState {
1415
+ /** Whether a webhook alert channel with that name exists. */
1416
+ exists: boolean;
1417
+ /** Whether the provider formats its message for Discord. Absent when the channel does not exist. */
1418
+ discord?: boolean;
1419
+ /** The id of the Discord webhook the channel posts through, read from its URL. Absent when the URL is not one. */
1420
+ webhookId?: string;
1421
+ /** What the channel alerts about now. Absent when the channel does not exist. */
1422
+ alerts?: Required<MonitoringAlertSettings>;
1423
+ /** Names of the checks routed to the channel (all of them, unless a check names its `alertChannels`) that it is not subscribed to. */
1424
+ unsubscribed: string[];
1425
+ /** Names of the checks routed away from the channel (by their `alertChannels`) that it is still subscribed to. */
1426
+ misrouted: string[];
1427
+ /**
1428
+ * How many check groups the channel is subscribed to (and has switched on), reported only when some check is routed
1429
+ * away from the channel. A group's subscription alerts for every check in the group, including one routed elsewhere,
1430
+ * and which checks a group holds cannot be read, so these are named for a person to check.
1431
+ */
1432
+ groupSubscriptions?: number;
1433
+ /** Names of the checks the channel is subscribed to but has switched off. */
1434
+ deactivated: string[];
1435
+ }
1436
+ /** External uptime and synthetic checks run from the provider's infrastructure against a deployed URL. */
1437
+ interface Monitoring extends ProviderIdentity {
1438
+ /** Identifies this provider as the `monitoring` capability. */
1439
+ readonly key: "monitoring";
1440
+ /**
1441
+ * Checks this provider is configured to ensure exist — populated from
1442
+ * the provider's own config (`holocron.config.ts`'s provider tuple),
1443
+ * the same place `Deployment.domain` comes from. `holocron repo setup`
1444
+ * loops this list and calls `ensureCheck` for each; empty when none
1445
+ * are configured.
1446
+ */
1447
+ readonly checks: readonly MonitoringCheckInput[];
1448
+ /**
1449
+ * The service's own picture, for the webhook it posts through (see `feeds.monitoring`): where to fetch it, and the
1450
+ * image itself as a `data:` URI for when that cannot be reached. Used when the config names no picture of its own.
1451
+ */
1452
+ readonly icon?: {
1453
+ /** Where to fetch the picture. */
1454
+ url?: string;
1455
+ /** The picture itself as a `data:` URI, for when `url` cannot be reached. */
1456
+ dataUri?: string;
1457
+ };
1458
+ /** Auth sanity-check. Throws ProviderApiError on auth failure. */
1459
+ whoami?(): Promise<{
1460
+ ok: boolean;
1461
+ }>;
1462
+ /** Idempotent find-or-create-or-update by `input.name`. */
1463
+ ensureCheck(input: MonitoringCheckInput): Promise<{
1464
+ check: MonitoringCheck;
1465
+ alreadyExists: boolean;
1466
+ }>;
1467
+ /**
1468
+ * Every check the provider's account holds now, in the same shape `checks` declares them, so the two can be
1469
+ * compared. Read-only. Settings the provider cannot return are left out of each entry.
1470
+ * Optional — a provider that cannot list its checks omits it.
1471
+ */
1472
+ listChecks?(): Promise<MonitoringCheckInput[]>;
1473
+ /**
1474
+ * Find-or-create-or-update an alert channel by name, apply the alert settings `input.alerts` states, and subscribe the
1475
+ * checks routed to it: every check the provider has, except a configured check whose `alertChannels` names others.
1476
+ * Checks made through an API are never subscribed automatically, so a later run subscribes the ones added since.
1477
+ * Subscriptions are only added, never removed.
1478
+ * Optional — a provider with no alert channels omits it.
1479
+ */
1480
+ ensureAlertChannel?(input: MonitoringAlertChannelInput): Promise<MonitoringAlertChannelResult>;
1481
+ /**
1482
+ * Read the alert channel named `name` and which of the account's checks it alerts for. Read-only, and never returns
1483
+ * the URL it posts to. Optional — a provider with no alert channels omits it.
1484
+ */
1485
+ inspectAlertChannel?(name: string): Promise<MonitoringAlertChannelState>;
1486
+ }
1487
+ /** What {@link Tooling.doctor} found. */
1488
+ interface ToolingDoctorReport {
1489
+ /** Whether the tool is in a good state. */
1490
+ ok: boolean;
1491
+ /** What to show the person: what was found, or what is wrong. */
1492
+ message: string;
1493
+ }
1494
+ /** A developer tool kept in step with the repo; several can be active at once. */
1495
+ interface Tooling extends ProviderIdentity {
1496
+ /** Identifies this provider as the `tooling` capability. */
1497
+ readonly key: "tooling";
1498
+ /** Sync the tool's authoritative state from the repo. */
1499
+ sync(): Promise<void>;
1500
+ /** Check the tool is set up and working, and report what was found. */
1501
+ doctor(): Promise<ToolingDoctorReport>;
1502
+ }
1503
+ /** What an `ensure*` call found or made. `created: false` means it already existed. */
1504
+ interface EnsuredResource {
1505
+ /** The provider's id for the resource. */
1506
+ id: string;
1507
+ /** Whether the resource was made now rather than already existing. */
1508
+ created: boolean;
1509
+ /** For something that already existed: the settings that disagreed with the layout and were changed. */
1510
+ updated?: string[];
1511
+ }
1512
+ /**
1513
+ * A conversation about one document (an ADR or a spec) in a forum channel, as the provider has it. `key` identifies
1514
+ * the document, the repo-relative path of its file; the provider records it on the post so the post can be found again.
1515
+ */
1516
+ interface DiscussionPost {
1517
+ /** The post's address, for the document's `discussion.url`. */
1518
+ url: string;
1519
+ /** The post's title as it is now; `undefined` when the provider does not say. */
1520
+ title?: string;
1521
+ /** The key the post records: the path of the document it was made for, which is not the document's path now when the file moved. */
1522
+ key?: string;
1523
+ /**
1524
+ * The post's state: the name of the one tag it carries. `undefined` when it carries none, or more than one, so there
1525
+ * is no single state to read.
1526
+ */
1527
+ state?: string;
1528
+ /** The state the post was last in step with the document, as the post records it; `undefined` when it records none. */
1529
+ synced?: string;
1530
+ /** The line of the post's first message that names the pull request (`PR: [#1538](<address>)`); `undefined` when it names none. */
1531
+ prLine?: string;
1532
+ /**
1533
+ * The first line of the post's first message, which names the document: its id (`SPEC-0007`), or the id as a link to
1534
+ * the file (`[SPEC-0007](<address>)`); `undefined` when the message does not start with an id.
1535
+ */
1536
+ idLine?: string;
1537
+ /** Whether the post is closed: finished with, and locked so that only people who manage it can reply or reopen it. Absent when it is open. */
1538
+ closed?: boolean;
1539
+ }
1540
+ /** What {@link Notifications.ensureDiscussion} takes. */
1541
+ interface EnsureDiscussionInput {
1542
+ /** The forum channel's name, as in the layout. */
1543
+ channel: string;
1544
+ /** Identifies the document: its repo-relative path. */
1545
+ key: string;
1546
+ /** The post's title. */
1547
+ title: string;
1548
+ /** The post's first message, without the line the provider adds to record `key` and the synced state. */
1549
+ body: string;
1550
+ /** The state to open the post in: the name of one of the forum's tags. It is also recorded as the state last synced. */
1551
+ state: string;
1552
+ /** Post without notifying anyone, as a backfill of many posts should. */
1553
+ quiet?: boolean;
1554
+ /** Close the post as it is made, for a document that is already finished with. */
1555
+ closed?: boolean;
1556
+ /**
1557
+ * The address the document already records for its post. A post is found by `key`; when none has it, the one this
1558
+ * address names is the document's, moved, and its key is changed to `key` instead of a second post being made.
1559
+ */
1560
+ url?: string;
1561
+ }
1562
+ /** What {@link Notifications.ensureDiscussion} found or made. */
1563
+ interface EnsuredDiscussion {
1564
+ /** The post, as it is now. */
1565
+ post: DiscussionPost;
1566
+ /** Whether the post was made now rather than already existing. */
1567
+ created: boolean;
1568
+ /** Whether the post was found under the path the document had before it moved, and now records the new one. */
1569
+ rekeyed?: boolean;
1570
+ }
1571
+ /** What {@link Notifications.updateDiscussion} changes; a field left out is left alone. */
1572
+ interface DiscussionPatch {
1573
+ /** A new key: the document moved, and the post records its new path. */
1574
+ key?: string;
1575
+ /** A new title. */
1576
+ title?: string;
1577
+ /** A new state: the name of one of the forum's tags. It replaces the post's tags. */
1578
+ state?: string;
1579
+ /** The state the post and the document now agree on. */
1580
+ synced?: string;
1581
+ /**
1582
+ * The line that names the pull request in the post's first message. The provider rewrites that line and keeps the rest
1583
+ * of the message, the synced line above all; an empty string takes the line out. For repairing posts made under an
1584
+ * older rule, not for every sync.
1585
+ */
1586
+ prLine?: string;
1587
+ /**
1588
+ * The line that names the document in the post's first message (its first line): the id, plain or as a link to the
1589
+ * file. The provider rewrites that line and keeps the rest of the message, the synced line above all; it must not be
1590
+ * empty. A message that does not start with an id is refused. For following a file that moved and for repairing posts
1591
+ * made under an older rule, not for every sync.
1592
+ */
1593
+ idLine?: string;
1594
+ /**
1595
+ * The text of the post's first message, replacing what is there. The provider keeps its footer (`-# sync: <key> |
1596
+ * <synced>`) and cuts the text to fit the message limit. A `prLine` or `idLine` in the same patch is applied to the new
1597
+ * text.
1598
+ */
1599
+ body?: string;
1600
+ /** Close the post (archive and lock it) or reopen it (unlock and unarchive it). */
1601
+ closed?: boolean;
1602
+ }
1603
+ /** A webhook (or equivalent inbound URL) for a channel. */
1604
+ interface EnsureWebhookResult {
1605
+ /** Whether the webhook was made now rather than already existing. */
1606
+ created: boolean;
1607
+ /**
1608
+ * The posting URL — a credential. Absent when the webhook already existed and
1609
+ * the provider will not reveal it again (Discord returns the token only to
1610
+ * the application that created the webhook, and only on creation).
1611
+ */
1612
+ url?: string;
1613
+ /** For a webhook that already existed, or was just made: the settings that were set (`"avatar"`). */
1614
+ updated?: string[];
1615
+ /** Set when the webhook is fine but setting its avatar failed; the webhook and its `url` are still good. */
1616
+ avatarError?: string;
1617
+ }
1618
+ /**
1619
+ * Who may see a channel and post in it. Roles are named as in the layout's `roles`.
1620
+ * A channel inherits its category's access; stating `view` or `post` on the channel
1621
+ * replaces that field only.
1622
+ */
1623
+ interface NotificationsAccess {
1624
+ /** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
1625
+ view?: "everyone" | string[];
1626
+ /** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
1627
+ post?: "everyone" | string[];
1628
+ }
1629
+ /** A tag a post in a forum channel can carry. */
1630
+ interface NotificationsForumTag {
1631
+ /** The tag's name, up to 20 characters. */
1632
+ name: string;
1633
+ /** An emoji shown beside the name, such as `💬`. */
1634
+ emoji?: string;
1635
+ /** Whether only members who can manage threads (and the provider's own bot) may apply the tag. Defaults to `false`. */
1636
+ moderated?: boolean;
1637
+ }
1638
+ /**
1639
+ * A picture (PNG, JPEG or GIF) as a layout writes it: a file path (relative to the repository root) or an `https://` URL, or
1640
+ * `{ url, image }`, where the `url` is tried first and the `image`, a file in the repo, is the fallback.
1641
+ */
1642
+ type NotificationsPicture = string | {
1643
+ url?: string;
1644
+ image?: string;
1645
+ };
1646
+ /** The object form of a channel's `feeds.monitoring`: the names, picture and alert settings of its monitoring feed. */
1647
+ interface NotificationsMonitoringFeed {
1648
+ /** The alert channel's name; default `Message to #<channel>`. */
1649
+ name?: string;
1650
+ /** The dedicated webhook's name; default the provider's name, capitalised. */
1651
+ webhook?: string;
1652
+ /** A picture for that webhook: a path or `https://` URL, or `{ url, image }`. */
1653
+ avatar?: NotificationsPicture;
1654
+ /** What the alert channel alerts about: `failure`, `recovery`, `degraded`, `sslExpiry`, `sslExpiryThreshold`. */
1655
+ alerts?: MonitoringAlertSettings;
1656
+ }
1657
+ /** One channel in a {@link NotificationsLayout}. */
1658
+ interface NotificationsChannelLayout {
1659
+ /** The channel's name. */
1660
+ name: string;
1661
+ /** The channel's topic text. For a forum, this is the guidelines shown above its posts. */
1662
+ topic?: string;
1663
+ /**
1664
+ * What kind of channel it is: `"text"` (the default) or `"forum"`, where every conversation is a post of its own
1665
+ * and cannot take a webhook post. A text channel cannot be turned into a forum or back: if the other kind already
1666
+ * has this name, `setup` stops and says to delete it first. A forum takes no `webhook` and only the `prs` feed.
1667
+ */
1668
+ kind?: "text" | "forum";
1669
+ /**
1670
+ * The tags a forum's posts can carry, each with an emoji. Only for `kind: "forum"`. `setup` adds the ones that are
1671
+ * missing and fixes the emoji and `moderated` of the ones that differ, and never removes a tag the layout does not
1672
+ * list, so a post keeps the tags it has.
1673
+ */
1674
+ tags?: NotificationsForumTag[];
1675
+ /**
1676
+ * The emoji Discord offers as the first reaction on every post of a forum (Get Started: "Set a default reaction
1677
+ * for posts"). Only for `kind: "forum"`. Discord allows exactly one per forum, so the rest of a set go in
1678
+ * {@link NotificationsChannelLayout.starterReactions}. A Unicode emoji (`"👍"`); custom emoji are not supported.
1679
+ */
1680
+ defaultReaction?: string;
1681
+ /**
1682
+ * Reactions the bot adds to the first message of each post it makes, so a conversation starts with the ways to
1683
+ * answer already there (`["✅", "❌", "❓"]` for approve, disapprove, question). Only for `kind: "forum"`. Posts that
1684
+ * exist are left alone. Reacting needs the Add Reactions permission.
1685
+ */
1686
+ starterReactions?: string[];
1687
+ /** Who may see and post. Overrides the category's, field by field. */
1688
+ access?: NotificationsAccess;
1689
+ /**
1690
+ * Create an inbound webhook for the channel and store its URL in a secret.
1691
+ * `true` uses the defaults; the object form overrides the webhook's display
1692
+ * name and the secret's name.
1693
+ */
1694
+ webhook?: boolean | {
1695
+ name?: string;
1696
+ secret?: string;
1697
+ avatar?: NotificationsPicture;
1698
+ };
1699
+ /**
1700
+ * Other services that post into this channel through a webhook of their own. Each gets a dedicated webhook, whose
1701
+ * URL goes straight to that service and is never stored as a secret, so revoking one service leaves the rest alone.
1702
+ */
1703
+ feeds?: {
1704
+ /**
1705
+ * The monitoring provider's alerts. `true` uses the defaults; the object form overrides the alert channel's name
1706
+ * (default `Message to #<channel>`) and the dedicated webhook's name (default the provider's name, capitalised), and
1707
+ * `avatar` gives that webhook a picture (PNG, JPEG or GIF; see {@link NotificationsPicture}: a path or URL, or
1708
+ * `{ url, image }` with a fallback) in the provider's list of integrations. Left out, it wears the layout's `webhookAvatar`, as every webhook does. A picture is set only on a
1709
+ * webhook that has none; the posts carry the service's own name and icon either way.
1710
+ */
1711
+ monitoring?: boolean | NotificationsMonitoringFeed;
1712
+ /**
1713
+ * The error tracker's alerts, carried in by the relay Worker (see `relay`). The channel gets a dedicated webhook
1714
+ * (default the `errors` provider's name, capitalised) whose URL goes to the Worker as a secret and nowhere else.
1715
+ * `avatar` is as for `monitoring`.
1716
+ */
1717
+ errors?: boolean | {
1718
+ webhook?: string;
1719
+ avatar?: NotificationsPicture;
1720
+ };
1721
+ /**
1722
+ * The pull-request feed: Sentinel keeps one post in this forum for each pull request, tagged with its state
1723
+ * (spec `tech-sentinel-pr-feed`). Only for `kind: "forum"`, and the forum's `tags` must hold all eight state tags:
1724
+ * `draft`, `conflicts`, `failing`, `changes requested`, `ready`, `waiting`, `merged` and `closed`. `true` follows every
1725
+ * pull request; the object form leaves out the pull requests of some repositories (`owner/name`) or authors (logins).
1726
+ * Needs no webhook: the bot makes and tags the posts, so it must be able to post in the forum and manage its threads.
1727
+ * The forum's messages carry no link previews (the posts are links to pull requests, and the previews bury the status).
1728
+ */
1729
+ prs?: boolean | NotificationsPrsFeed;
1730
+ };
1731
+ }
1732
+ /** The object form of a forum's `feeds.prs`: what the pull-request feed leaves out. */
1733
+ interface NotificationsPrsFeed {
1734
+ /** Pull requests not to follow. */
1735
+ exclude?: {
1736
+ /** Repositories, as `owner/name`. */
1737
+ repos?: string[];
1738
+ /** Authors, by GitHub login. */
1739
+ authors?: string[];
1740
+ };
1741
+ }
1742
+ /**
1743
+ * Settings of the server itself. Channels are named as in the layout's `categories`; each field
1744
+ * left out is left alone.
1745
+ */
1746
+ interface NotificationsServerLayout {
1747
+ /** How established an account must be to talk: `none`, `low` (verified email), `medium` (5 minutes old), `high` (10 minutes in the server), `highest` (verified phone). */
1748
+ verification?: "none" | "low" | "medium" | "high" | "highest";
1749
+ /** Whether members are notified for every message or only when mentioned. */
1750
+ defaultNotifications?: "all" | "mentions";
1751
+ /** Which members' media is scanned: `off`, `noRoles` (members without a role) or `all`. */
1752
+ contentFilter?: "off" | "noRoles" | "all";
1753
+ /** Where the provider posts its own notices (member joins, boosts). */
1754
+ systemChannel?: string;
1755
+ /** The channel holding the server rules; required to turn community features on. */
1756
+ rulesChannel?: string;
1757
+ /** Where the provider sends its notices to the owners; required to turn community features on. */
1758
+ updatesChannel?: string;
1759
+ /** Turn community features (welcome screen, onboarding, discovery) on or off. */
1760
+ community?: boolean;
1761
+ /** The server's public description. Only providers that support one for the server's current state accept it. */
1762
+ description?: string;
1763
+ /** Preferred language, as a locale such as `en-US`. */
1764
+ locale?: string;
1765
+ }
1766
+ /**
1767
+ * A message the provider posts in a channel and pins, so it stays at the top. Give the text as `content`, or as
1768
+ * a `file` in the repository that is its source of truth (never both). The CLI reads the file before it calls the
1769
+ * provider, so a provider only ever sees `content`.
1770
+ */
1771
+ interface NotificationsPinnedLayout {
1772
+ /** A channel in the layout. */
1773
+ channel: string;
1774
+ /** The message text (Discord allows up to 2000 characters). Absent when the text comes from `file`. */
1775
+ content?: string;
1776
+ /**
1777
+ * A text file in the repository, relative to its root, whose contents are the message, such as `.holocron/pinned/rules.md`. The
1778
+ * file wins: a hand edit of the pinned message is replaced on the next `setup`, and `doctor` reports it until then.
1779
+ */
1780
+ file?: string;
1781
+ }
1782
+ /**
1783
+ * The screen a new member sees on joining: a short text and the channels worth visiting first.
1784
+ * Declaring it describes the whole screen: the text and the channels are set to exactly this, so to
1785
+ * switch it off, state them as well.
1786
+ */
1787
+ interface NotificationsWelcomeLayout {
1788
+ /** Whether the screen is shown. Defaults to `true`. */
1789
+ enabled?: boolean;
1790
+ /** A sentence or two about the server (Discord allows up to 140 characters). */
1791
+ description: string;
1792
+ /** The channels it points to, in order (Discord allows up to five). */
1793
+ channels: Array<{
1794
+ /** A channel in the layout. */
1795
+ channel: string;
1796
+ /** Why to visit it (Discord allows up to 50 characters). */
1797
+ description: string;
1798
+ /** A single emoji shown beside it. */
1799
+ emoji?: string;
1800
+ }>;
1801
+ }
1802
+ /** The questions a new member answers to be shown the channels that fit them. */
1803
+ interface NotificationsOnboardingLayout {
1804
+ /** Turn onboarding on or off. Left out, it is left as it is (Discord has requirements for turning it on). */
1805
+ enabled?: boolean;
1806
+ /** Channels every member starts with, by name. */
1807
+ defaultChannels?: string[];
1808
+ /** The questions asked, in order. */
1809
+ prompts?: Array<{
1810
+ title: string;
1811
+ /** One answer only (`true`) or any number. Defaults to `false`. */
1812
+ singleSelect?: boolean;
1813
+ /** The member must answer. Defaults to `false`. */
1814
+ required?: boolean;
1815
+ options: Array<{
1816
+ title: string;
1817
+ description?: string;
1818
+ emoji?: string;
1819
+ /** Channels this answer shows, by name. */
1820
+ channels?: string[];
1821
+ /** Roles this answer gives, by name from the layout's `roles`. */
1822
+ roles?: string[];
1823
+ }>;
1824
+ }>;
1825
+ }
1826
+ /**
1827
+ * Settings of the bot's own application (for Discord, what the developer portal shows). A field left
1828
+ * out is left alone.
1829
+ */
1830
+ interface NotificationsApplicationLayout {
1831
+ /** What the application's page says it is (Discord allows up to 400 characters). */
1832
+ description?: string;
1833
+ /** Short labels, up to five of up to twenty characters each. */
1834
+ tags?: string[];
1835
+ /** The default install link: what the bot is added with. Permissions are named, as in a role's. */
1836
+ install?: {
1837
+ /** The OAuth2 scopes the install link asks for. */
1838
+ scopes: string[];
1839
+ /** The permissions the bot is added with, named as in a role's. */
1840
+ permissions: string[];
1841
+ };
1842
+ /** `https://` link to the terms of service. */
1843
+ termsUrl?: string;
1844
+ /** `https://` link to the privacy policy. */
1845
+ privacyUrl?: string;
1846
+ /** `https://` link the provider calls to verify linked roles. */
1847
+ roleConnectionsUrl?: string;
1848
+ /**
1849
+ * Privileged intents the bot needs. `members` lets it list who is in the server, which `sync-roles` needs to
1850
+ * find who holds a role. `true` switches it on from code; `false` switches it off.
1851
+ */
1852
+ intents?: {
1853
+ /** The server members intent: lets the bot list who is in the server. */
1854
+ members?: boolean;
1855
+ };
1856
+ /**
1857
+ * OAuth2 redirect URIs that must be registered, for `notifications link`. The provider's API does not allow
1858
+ * setting them, so these are only checked: `setup` and the doctor say what to add and where.
1859
+ */
1860
+ redirectUris?: string[];
1861
+ }
1862
+ /**
1863
+ * Permissions of everyone on the server (for Discord, the @everyone role). Unlike a role's `permissions`,
1864
+ * these name only what to change: the rest of the set is left as it is.
1865
+ */
1866
+ interface NotificationsEveryoneLayout {
1867
+ /** Permissions to grant. */
1868
+ allow?: string[];
1869
+ /** Permissions to take away. */
1870
+ deny?: string[];
1871
+ }
1872
+ /** Where the person-to-member links live: one file in a repo, written by the sign-in flow and read by `sync-roles`. */
1873
+ interface NotificationsLinksLayout {
1874
+ /**
1875
+ * The base URL of the hosted sign-in service (Sentinel), for example `https://sentinel.theholocron.dev`.
1876
+ * `notifications link` asks it for `/api/link`; when it answers, sign-in happens there, and when it does not
1877
+ * (down, out of quota, no route yet) the command signs in on this machine instead.
1878
+ */
1879
+ hostedUrl?: string;
1880
+ /** The port the local sign-in listens on, which must be registered as `http://localhost:<port>/callback`. Defaults to 53682. */
1881
+ localPort?: number;
1882
+ /** `owner/name`. Defaults to `<org>/.github-private`. Keep it private: the file pairs two identities. */
1883
+ repo?: string;
1884
+ /** Defaults to `notifications/<provider>-links.json`. */
1885
+ path?: string;
1886
+ }
1887
+ /** A declared server layout, applied idempotently by `holocron notifications setup`. */
1888
+ interface NotificationsLayout {
1889
+ /**
1890
+ * The channel set aside for test posts, by name. It must declare a webhook. `holocron doctor notifications`
1891
+ * leaves one labelled test message there through its webhook (read back to prove delivery works) for a
1892
+ * person to look at; the real channels are never given one unless `--deliver` posts and removes it.
1893
+ */
1894
+ testChannel?: string;
1895
+ /** Where `sync-roles` finds which server member is which GitHub account. Only used by roles with a `team`. */
1896
+ links?: NotificationsLinksLayout;
1897
+ /** The bot's own application settings, applied with the server's. */
1898
+ application?: NotificationsApplicationLayout;
1899
+ /** What everyone on the server may do, applied with the server's settings. */
1900
+ everyone?: NotificationsEveryoneLayout;
1901
+ /**
1902
+ * The picture every webhook gets unless its own `webhook.avatar` says otherwise: a path to a PNG,
1903
+ * JPEG or GIF (a path is relative to the repository root) or an `https://` URL, or `{ url, image }` (see
1904
+ * {@link NotificationsPicture}), where the `url` is tried first and the `image`, a file in the repo, is the fallback.
1905
+ * It is set only on a webhook that has no picture yet -- a provider cannot say whether the one it holds is the same image.
1906
+ */
1907
+ webhookAvatar?: NotificationsPicture;
1908
+ /**
1909
+ * The Worker that carries other services' alerts into the channels with a `feeds.errors`: built beforehand
1910
+ * (`apps/comlink`), deployed by `notifications setup` with each channel's webhook URL as a secret, and served at
1911
+ * `host`. Secrets set some other way (the service's signing secret) are kept across deploys.
1912
+ */
1913
+ relay?: {
1914
+ /** Where the Worker answers, e.g. `comlink.theholocron.dev`. Its DNS record and route are managed. */
1915
+ host: string;
1916
+ /** The DNS zone the host is in. Default: found by the `dns` provider from the host itself, so rarely needed. */
1917
+ zone?: string;
1918
+ /** The Worker's name at the provider. Default `comlink`. */
1919
+ script?: string;
1920
+ /** The built Worker, relative to the repo root. Default `apps/comlink/dist/worker.js`. */
1921
+ code?: string;
1922
+ /**
1923
+ * The error tracker's side, when its provider can manage it (`Errors.ensureRelay`): the projects whose issues
1924
+ * are sent, the integration's name (default `Comlink`) and the alert rule's name (default
1925
+ * `Errors to Discord (Comlink)`) and throttle in minutes (default 5). Left out, nothing is done at the tracker.
1926
+ */
1927
+ errors?: {
1928
+ /** The tracker projects whose issues are sent. */
1929
+ projects: string[];
1930
+ /** The integration's name at the tracker; `Comlink` when absent. */
1931
+ integration?: string;
1932
+ /** The alert rule's name; `Errors to Discord (Comlink)` when absent. */
1933
+ rule?: string;
1934
+ /** Minutes between two notifications for one issue; 5 when absent. */
1935
+ frequency?: number;
1936
+ };
1937
+ };
1938
+ /** What a new member sees on joining, applied after the channels exist. */
1939
+ welcome?: NotificationsWelcomeLayout;
1940
+ /** The questions a new member answers, applied after the channels and roles exist. */
1941
+ onboarding?: NotificationsOnboardingLayout;
1942
+ /**
1943
+ * Messages the provider posts and pins, applied after the channels exist. One that already says exactly this
1944
+ * (posted by the provider and still pinned) is left alone; one that says something else is replaced.
1945
+ */
1946
+ pinned?: NotificationsPinnedLayout[];
1947
+ /** Settings of the server itself, applied after its channels exist. */
1948
+ server?: NotificationsServerLayout;
1949
+ /** The categories to create, each with the channels under it. */
1950
+ categories?: Array<{
1951
+ name: string;
1952
+ access?: NotificationsAccess;
1953
+ channels?: NotificationsChannelLayout[];
1954
+ }>;
1955
+ /** The roles to create. */
1956
+ roles?: Array<{
1957
+ name: string;
1958
+ mentionable?: boolean;
1959
+ /** `#rrggbb`. Omit to leave the colour alone. */
1960
+ color?: string;
1961
+ /** Show the role's members as their own group in the member list. */
1962
+ hoist?: boolean;
1963
+ /**
1964
+ * The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
1965
+ * `SendMessages`, …). The list is exact: a permission not named is not granted.
1966
+ */
1967
+ permissions?: string[];
1968
+ /**
1969
+ * Keep this role's members equal to a team of the `source` provider (for GitHub, a team slug in
1970
+ * the org): `holocron notifications sync-roles` gives the role to every team member who has linked
1971
+ * their account, and takes it from linked people who have left the team.
1972
+ */
1973
+ team?: string;
1974
+ /**
1975
+ * Store the role's id in this secret, so a workflow can ping the role
1976
+ * without anyone copying the id by hand. The id is not sensitive; a secret
1977
+ * is used because the same token that writes the webhook secrets can write
1978
+ * it, with no extra permission.
1979
+ */
1980
+ secret?: string;
1981
+ }>;
1982
+ }
1983
+ /**
1984
+ * What a provider found on the server, limited to what a {@link NotificationsLayout}
1985
+ * asks about. Read-only: this is what `holocron doctor notifications` compares the
1986
+ * layout against.
1987
+ */
1988
+ interface ServerInspection {
1989
+ /** The bot's application as the provider has it, in the layout's terms, when the layout declares `application`. */
1990
+ application?: NotificationsApplicationLayout;
1991
+ /** Set when reading the application failed; `application` is then absent and means nothing. */
1992
+ applicationError?: string;
1993
+ /** What everyone may do, by permission name, when the layout declares `everyone`. */
1994
+ everyone?: {
1995
+ /** The permissions everyone holds now, by name. */
1996
+ permissions: string[];
1997
+ };
1998
+ /** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
1999
+ everyoneError?: string;
2000
+ /** The welcome screen as the server has it, in the layout's terms, when the layout declares `welcome`. */
2001
+ welcome?: NotificationsWelcomeLayout;
2002
+ /** Set when reading the welcome screen failed; `welcome` is then absent and means nothing. */
2003
+ welcomeError?: string;
2004
+ /** Whether each pinned message the layout declares is in place, in the layout's order. */
2005
+ pinned?: Array<{
2006
+ channel: string;
2007
+ state: "ok" | "missing" | "different";
2008
+ }>;
2009
+ /** Set when reading the pinned messages failed; `pinned` is then absent and means nothing. */
2010
+ pinnedError?: string;
2011
+ /** Onboarding as the server has it, in the layout's terms, when the layout declares `onboarding`. */
2012
+ onboarding?: NotificationsOnboardingLayout;
2013
+ /** Set when reading onboarding failed; `onboarding` is then absent and means nothing. */
2014
+ onboardingError?: string;
2015
+ /** The server's own settings, in the layout's terms, when the layout declares `server`. */
2016
+ server?: NotificationsServerLayout;
2017
+ /** Set when reading the server's settings failed; `server` is then absent and means nothing. */
2018
+ serverError?: string;
2019
+ /**
2020
+ * Which of the permissions the provider's bot needs its roles do not give it server-wide, in plain words
2021
+ * ("Manage Threads"; empty when none is missing, and always empty for the owner or an Administrator), with the link
2022
+ * that invites the bot again asking for them when some are missing. Channel overwrites are not looked at. The link
2023
+ * is not a credential.
2024
+ */
2025
+ botPermissions?: {
2026
+ /** The permissions that are missing, in plain words; empty when the bot holds everything it needs. */
2027
+ missing: string[];
2028
+ /** The link that invites the bot again asking for the full set; only present when something is missing. */
2029
+ inviteUrl?: string;
2030
+ };
2031
+ /** Set when reading the bot's roles failed; `botPermissions` is then absent and means nothing. */
2032
+ botPermissionsError?: string;
2033
+ /** Names of the categories on the server. */
2034
+ categories: string[];
2035
+ /**
2036
+ * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
2037
+ * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
2038
+ */
2039
+ categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
2040
+ /** The channels the layout asks about, as the server has them. */
2041
+ channels: Array<{
2042
+ name: string;
2043
+ /** The category it sits under, if any. */
2044
+ category?: string;
2045
+ topic?: string;
2046
+ /** `"forum"` for a forum channel; absent for a text channel. */
2047
+ kind?: "text" | "forum";
2048
+ /** The tags of a forum, in the layout's terms. Absent for a text channel. */
2049
+ tags?: NotificationsForumTag[];
2050
+ /** The default reaction of a forum, as the layout would spell it. Absent when none is set or for a text channel. */
2051
+ defaultReaction?: string;
2052
+ /** Names of the webhooks on the channel. Only filled in for channels the layout gives a webhook or a feed. */
2053
+ webhooks: string[];
2054
+ /** Which of those webhooks have a picture of their own. */
2055
+ webhookAvatars?: string[];
2056
+ /** The id of each of those webhooks, by lower-cased name: the public part of its URL, never the token. */
2057
+ webhookIds?: Record<string, string>;
2058
+ /** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
2059
+ webhooksError?: string;
2060
+ /** Who can see and post; `"custom"` as for `categoryAccess`. */
2061
+ access?: Required<NotificationsAccess> | "custom";
2062
+ /**
2063
+ * Whether the bot itself can start posts and reply in this forum (`post`) and manage its threads (`manage`: tag and
2064
+ * close them), after the channel's own overwrites. Only filled in for a forum the layout gives a `feeds.prs`.
2065
+ */
2066
+ botThreads?: {
2067
+ post: boolean;
2068
+ manage: boolean;
2069
+ };
2070
+ /** Set when working out `botThreads` failed; it is then absent and means nothing. */
2071
+ botThreadsError?: string;
2072
+ }>;
2073
+ /** The roles on the server. */
2074
+ roles: Array<{
2075
+ name: string;
2076
+ id: string;
2077
+ mentionable: boolean;
2078
+ /** `#rrggbb`, or absent for the default colour. */
2079
+ color?: string;
2080
+ hoist?: boolean;
2081
+ permissions?: string[];
2082
+ }>;
2083
+ /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
2084
+ rolesError?: string;
2085
+ }
2086
+ /** Who a member turned out to be after signing in with the provider. */
2087
+ interface NotificationsSignedIn {
2088
+ /** Their id on the provider; for Discord, the user id. */
2089
+ member: string;
2090
+ /** Their name on the provider, when it gives one. */
2091
+ name?: string;
2092
+ /** The GitHub account the provider has verified they own; absent when they have none linked. */
2093
+ github?: {
2094
+ /** The GitHub user id, as a string. */
2095
+ id: string;
2096
+ /** The GitHub login. */
2097
+ login: string;
2098
+ };
2099
+ }
2100
+ /** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
2101
+ interface NotificationsSignIn {
2102
+ /** The address of the provider's sign-in page, carrying the redirect address and state given. */
2103
+ authorizeUrl(input: {
2104
+ redirectUri: string;
2105
+ state: string;
2106
+ }): Promise<string>;
2107
+ /** Trades the one-use `code` for who they are, and discards the token it was given. */
2108
+ complete(input: {
2109
+ redirectUri: string;
2110
+ code: string;
2111
+ }): Promise<NotificationsSignedIn>;
2112
+ }
2113
+ /** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
2114
+ interface NotificationsDelivery {
2115
+ /** The message was posted through the channel's webhook. */
2116
+ posted: boolean;
2117
+ /** The message was found in the channel afterwards. */
2118
+ readBack: boolean;
2119
+ /** The message was deleted again. */
2120
+ removed: boolean;
2121
+ /** Set when the message was deliberately left in the channel (`keep`), so `removed` is false on purpose. */
2122
+ kept?: boolean;
2123
+ /** What went wrong at each failed step; empty when delivery worked. */
2124
+ problems: string[];
2125
+ }
2126
+ /** A member of the server, as {@link Notifications.roleMembers} reports it. */
2127
+ interface NotificationsMember {
2128
+ /** The provider's id for them; for Discord, the user id. */
2129
+ id: string;
2130
+ /** A display name for reports; absent when the provider does not give one. */
2131
+ name?: string;
2132
+ }
2133
+ /** Chat notifications: posts messages and, where the provider allows, builds the server a layout describes. */
2134
+ interface Notifications extends ProviderIdentity {
2135
+ /** Identifies this provider as the `notifications` capability. */
2136
+ readonly key: "notifications";
2137
+ /**
2138
+ * Send a message. `channel` is provider-specific (Slack channel id,
2139
+ * Discord webhook url-name, etc.); adapters resolve from config.
2140
+ */
2141
+ send(channel: string, message: string): Promise<void>;
2142
+ /**
2143
+ * The server layout the owner declared for this provider, if any. Read by
2144
+ * `holocron notifications setup`; the provider just carries it from its options.
2145
+ */
2146
+ readonly layout?: NotificationsLayout;
2147
+ /**
2148
+ * Provisioning. All optional, all idempotent (look up by name, create only
2149
+ * what is missing), and all need provider credentials beyond the posting
2150
+ * URL — so a provider that only posts simply omits them.
2151
+ */
2152
+ ensureCategory?(name: string, opts?: {
2153
+ access?: NotificationsAccess;
2154
+ }): Promise<EnsuredResource>;
2155
+ /** Find or create a channel, under its category when named, with its topic and access. */
2156
+ ensureChannel?(input: {
2157
+ name: string;
2158
+ category?: string;
2159
+ topic?: string;
2160
+ access?: NotificationsAccess;
2161
+ /** `"forum"` for a forum channel; a text channel when absent. */
2162
+ kind?: "text" | "forum";
2163
+ /** The tags of a forum; see {@link NotificationsChannelLayout.tags}. */
2164
+ tags?: NotificationsForumTag[];
2165
+ /** The default reaction of a forum; see {@link NotificationsChannelLayout.defaultReaction}. */
2166
+ defaultReaction?: string;
2167
+ }): Promise<EnsuredResource>;
2168
+ /** Find or create a webhook named `name` on the channel, creating the channel first if it is missing. */
2169
+ ensureWebhook?(input: {
2170
+ channel: string;
2171
+ name: string;
2172
+ category?: string;
2173
+ /** An image as a `data:` URI, set when the webhook has none. */
2174
+ avatar?: string;
2175
+ }): Promise<EnsureWebhookResult>;
2176
+ /**
2177
+ * Proves a channel's webhook delivers: posts `text` through it, reads the post back from the channel and
2178
+ * removes it again, unless `keep` is true, in which case the post is left in the channel (and the result
2179
+ * has `kept` instead of `removed`). Never throws for a failed step; the result says which one failed.
2180
+ * Posts a visible message, so callers choose the channel with care.
2181
+ */
2182
+ checkDelivery?(input: {
2183
+ channel: string;
2184
+ name: string;
2185
+ category?: string;
2186
+ /** The message. The provider may format it (Discord renders markdown) and replaces `{channel}` with its link to the channel. */
2187
+ text: string;
2188
+ /** Leave the message in the channel instead of removing it, so a person can see it. */
2189
+ keep?: boolean;
2190
+ }): Promise<NotificationsDelivery>;
2191
+ /**
2192
+ * Creates the server the layout describes, empty, owned by the provider's own bot, and makes it the server
2193
+ * every other call in this run works on. Refuses when the config already names a server unless `force`.
2194
+ */
2195
+ createServer?(input: {
2196
+ name: string;
2197
+ force?: boolean;
2198
+ }): Promise<{
2199
+ id: string;
2200
+ name: string;
2201
+ }>;
2202
+ /** A single-use link, valid for a day, that lets one person join the server through the named channel. */
2203
+ inviteLink?(channel: string): Promise<string>;
2204
+ /** Whether a person is in the server. */
2205
+ hasMember?(memberId: string): Promise<boolean>;
2206
+ /** Hands the server to a member who has joined, so the bot no longer owns it. */
2207
+ transferServer?(memberId: string): Promise<void>;
2208
+ /** Who owns the server, and whether that is the provider's own bot. */
2209
+ serverOwner?(): Promise<{
2210
+ id: string;
2211
+ isBot: boolean;
2212
+ name?: string;
2213
+ }>;
2214
+ /**
2215
+ * Who holds a role, by the provider's member id. Needs whatever permission the provider asks for to list
2216
+ * members (for Discord, the privileged Server Members Intent). Throws if the role does not exist.
2217
+ */
2218
+ roleMembers?(roleName: string): Promise<NotificationsMember[]>;
2219
+ /** Give a member the role; one who has it already is left alone. */
2220
+ addRoleMember?(roleName: string, memberId: string): Promise<void>;
2221
+ /** Take the role from a member; one who lacks it is left alone. */
2222
+ removeRoleMember?(roleName: string, memberId: string): Promise<void>;
2223
+ /** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
2224
+ signIn?(): NotificationsSignIn;
2225
+ /** Find or create a role; one that exists has its settings brought in line. */
2226
+ ensureRole?(input: {
2227
+ name: string;
2228
+ mentionable?: boolean;
2229
+ color?: string;
2230
+ hoist?: boolean;
2231
+ permissions?: string[];
2232
+ }): Promise<EnsuredResource>;
2233
+ /**
2234
+ * Bring the server's own settings in line with the layout, changing only what differs. Returns the
2235
+ * names of what it changed, empty when the server already matched.
2236
+ */
2237
+ ensureServer?(settings: NotificationsServerLayout): Promise<{
2238
+ updated: string[];
2239
+ }>;
2240
+ /** Bring the welcome screen in line with the layout, changing only what differs. Returns what it changed. */
2241
+ ensureWelcome?(welcome: NotificationsWelcomeLayout): Promise<{
2242
+ updated: string[];
2243
+ }>;
2244
+ /**
2245
+ * Posts `content` in a channel of the layout as the provider's own bot, mentioning no one. For a result a person
2246
+ * asked to share (`doctor notifications --post`); a notification goes through a webhook (`send`).
2247
+ */
2248
+ postMessage?(channel: string, content: string): Promise<void>;
2249
+ /** Post and pin the layout's messages, replacing any that differ. Returns the channels it changed. */
2250
+ ensurePinned?(pinned: NotificationsPinnedLayout[]): Promise<{
2251
+ updated: string[];
2252
+ }>;
2253
+ /**
2254
+ * Find the discussion post for `key` in a forum channel, or make it. Never changes a post that exists: its state and
2255
+ * its text are the caller's to reconcile through {@link Notifications.readDiscussion} and
2256
+ * {@link Notifications.updateDiscussion}. Idempotent, and the lookup reads archived posts too.
2257
+ */
2258
+ ensureDiscussion?(input: EnsureDiscussionInput): Promise<EnsuredDiscussion>;
2259
+ /**
2260
+ * The discussion post for `key` in a forum channel, or `undefined` when there is none. When none has `key`, the one the
2261
+ * document's recorded address (`url`) names is it, moved; its `key` then differs from the one asked for.
2262
+ */
2263
+ readDiscussion?(channel: string, key: string, url?: string): Promise<DiscussionPost | undefined>;
2264
+ /** Change the discussion post for `key`: its title, its state (the tag), the state last synced, the first message's text, the pull request line and the id line. Throws when there is no post. */
2265
+ updateDiscussion?(channel: string, key: string, patch: DiscussionPatch): Promise<void>;
2266
+ /**
2267
+ * Append a message to the discussion post for `key`, mentioning no one; `quiet` posts it without notifying anyone. A post
2268
+ * that is archived or locked is unarchived and unlocked, written to, and put back as it was. Throws when there is no post.
2269
+ */
2270
+ postDiscussionMessage?(channel: string, key: string, content: string, opts?: {
2271
+ quiet?: boolean;
2272
+ }): Promise<void>;
2273
+ /**
2274
+ * The text of the post for `key`'s recent messages, newest first (`limit` of them, 50 by default, at most 100); the
2275
+ * first message, with its footer, is the oldest. Reads archived posts too. Empty when there is no post.
2276
+ */
2277
+ readDiscussionMessages?(channel: string, key: string, limit?: number): Promise<string[]>;
2278
+ /**
2279
+ * When more than one post carries `key`, keep the oldest and delete the rest. Returns how many it deleted (0 when there
2280
+ * is one post or none).
2281
+ */
2282
+ dedupeDiscussion?(channel: string, key: string): Promise<number>;
2283
+ /** Whether the bot holds the permission right now (the owner holds every one). Used to prove an elevation was taken back. */
2284
+ holdsPermission?(permission: string): Promise<boolean>;
2285
+ /** Bring onboarding in line with the layout, changing only what differs. Returns what it changed. */
2286
+ ensureOnboarding?(onboarding: NotificationsOnboardingLayout): Promise<{
2287
+ updated: string[];
2288
+ }>;
2289
+ /** Bring the bot's application settings in line with the layout, changing only what differs. Returns what it changed. */
2290
+ ensureApplication?(application: NotificationsApplicationLayout): Promise<{
2291
+ updated: string[];
2292
+ todo?: string[];
2293
+ }>;
2294
+ /** Grant or take away the named permissions from everyone, changing only what differs. Returns what it changed. */
2295
+ ensureEveryone?(everyone: NotificationsEveryoneLayout): Promise<{
2296
+ updated: string[];
2297
+ }>;
2298
+ /**
2299
+ * Before anything is created, prove the credentials can do the parts of the layout that need
2300
+ * more than the rest (for Discord, change the server's settings). Throws with the reason and how
2301
+ * to fix it, so `setup` stops before it leaves a half-applied layout. Not called on a dry run.
2302
+ */
2303
+ preflight?(layout: NotificationsLayout): Promise<void>;
2304
+ /**
2305
+ * Check the provider-specific parts of the layout (colours, permission names, …) without
2306
+ * touching the server, so `setup` can refuse a bad layout before it creates anything.
2307
+ * Returns the first problem, or `undefined` when the layout is fine.
2308
+ */
2309
+ validateLayout?(layout: NotificationsLayout): string | undefined;
2310
+ /**
2311
+ * Smoke check for `holocron doctor`: prove the provisioning credentials work
2312
+ * and name what they reach. Returns `null` when there is nothing to check (a
2313
+ * config that only posts has no provisioning credentials), which doctor shows
2314
+ * as "loaded" rather than as a failure. Throws when it is configured to
2315
+ * provision but cannot (missing token, no access).
2316
+ */
2317
+ whoami?(): Promise<{
2318
+ target: string;
2319
+ } | null>;
2320
+ /**
2321
+ * Read what exists on the server, for the parts the layout cares about, without
2322
+ * changing anything. Backs `holocron doctor notifications`.
2323
+ */
2324
+ inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
2325
+ }
2326
+ /** Product analytics: describes what an app needs at runtime and, where the provider allows, creates projects. */
2327
+ interface Analytics extends ProviderIdentity {
2328
+ /** Identifies this provider as the `analytics` capability. */
2329
+ readonly key: "analytics";
2330
+ /** Returns the env var names the app reads at runtime for this provider. */
2331
+ describe(): Promise<{
2332
+ provider: string;
2333
+ envKeys: string[];
2334
+ }>;
2335
+ /** Reachability probe: proves the credentials work and names the organization they belong to. */
2336
+ whoami?(): Promise<{
2337
+ org: string;
2338
+ }>;
2339
+ /** Create the project if it is missing and return its ingestion token; `alreadyExists` is true when it was there. */
2340
+ ensureProject?(name: string): Promise<{
2341
+ token: string;
2342
+ alreadyExists: boolean;
2343
+ }>;
2344
+ }
2345
+ /** Options for {@link Wiki.provision}. */
2346
+ interface WikiProvisionOpts {
2347
+ /** Project display name used in the wiki title (e.g. "Holocron"). */
2348
+ name?: string;
2349
+ }
2350
+ /**
2351
+ * Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
2352
+ * Used by `setup` to deploy a Worker that forwards traffic to the wiki
2353
+ * provider's ingress with the required headers injected.
2354
+ */
2355
+ interface WikiProxyConfig {
2356
+ /** Proxy target URL (e.g. "https://app.buildwithfern.com"). */
2357
+ target: string;
2358
+ /** Headers injected on every proxied request. */
2359
+ headers: Record<string, string>;
2360
+ }
2361
+ /**
2362
+ * Engineering wiki provider.
2363
+ *
2364
+ * A swappable provider for publishing the `docs/decisions/` and
2365
+ * `docs/engineering/` surfaces as a browsable, access-controlled site.
2366
+ * Local-only providers (fern, mintlify) write config files; remote
2367
+ * providers (github) make API calls.
2368
+ */
2369
+ interface Wiki extends ProviderIdentity {
2370
+ /** Identifies this provider as the `wiki` capability. */
2371
+ readonly key: "wiki";
2372
+ /** Provision the wiki — write config files or call the provider API. */
2373
+ provision(opts?: WikiProvisionOpts): Promise<string>;
2374
+ /**
2375
+ * DNS record needed for the custom domain, when one is configured.
2376
+ * Returns null when no custom domain is set.
2377
+ * Called by `setup` to provision the CNAME via the `dns` capability.
2378
+ */
2379
+ dnsRecord?(): DnsRecordRequest | null;
2380
+ /**
2381
+ * Reverse-proxy config when the wiki provider requires a Worker-level
2382
+ * proxy in addition to the CNAME. Returns null when no proxy is needed.
2383
+ * Called by `setup` to deploy the proxy via the `workers` capability.
2384
+ */
2385
+ proxyConfig?(): WikiProxyConfig | null;
2386
+ /**
2387
+ * Confirms a provider token resolves. Unlike `dns`/`workers`/`monitoring`'s
2388
+ * `whoami()`, this is NOT a live reachability check — Fern (the only
2389
+ * current `wiki` provider) exposes no lightweight endpoint to verify a
2390
+ * token actually works; the only token-consuming operation is a full
2391
+ * `fern generate` (holocron#1079). `ok: true` means "a token was found",
2392
+ * not "the token works".
2393
+ */
2394
+ whoami?(): Promise<{
2395
+ ok: boolean;
2396
+ }>;
2397
+ }
2398
+ /** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
2399
+ interface DeployScriptConfig {
2400
+ /** The full Worker script source — a single ES module (`export default { fetch(...) {...} }`). */
2401
+ code: string;
2402
+ /**
2403
+ * Secret bindings — `env.<name>` in the deployed Worker. Values are
2404
+ * write-only; the provider never echoes them back, here or anywhere else.
2405
+ */
2406
+ secrets?: Record<string, string>;
2407
+ /**
2408
+ * Route pattern(s) this Worker should serve (e.g.
2409
+ * `"sentinel.theholocron.dev/*"`). Omit for a Worker reached only via
2410
+ * its `*.workers.dev` URL.
2411
+ */
2412
+ routes?: string[];
2413
+ }
2414
+ /** A deployed Worker as the provider holds it, for `doctor notifications`. Binding names only: a value is never read. */
2415
+ interface WorkerScriptState {
2416
+ /** Whether a script with that name is deployed. */
2417
+ exists: boolean;
2418
+ /** The route patterns that serve the script in the zone of the host asked about. */
2419
+ routes: string[];
2420
+ /** The names of the secrets bound to the script. */
2421
+ bindingNames: string[];
2422
+ }
2423
+ /** What {@link Workers.deployScript} made. */
2424
+ interface DeployScriptResult {
2425
+ /** The deployed script's name at the provider. */
2426
+ scriptName: string;
2427
+ }
2428
+ /**
2429
+ * Edge Worker management capability.
2430
+ *
2431
+ * Deploys and manages Worker scripts. `upsertProxy` is the existing,
2432
+ * narrower case `setup` uses to wire wiki custom-domain reverse-proxies;
2433
+ * `deployScript` is the general case — any Worker, any code, its own
2434
+ * secrets — for a consumer that isn't a reverse-proxy (a webhook
2435
+ * receiver, for instance).
2436
+ */
2437
+ interface Workers extends ProviderIdentity {
2438
+ /** Identifies this provider as the `workers` capability. */
2439
+ readonly key: "workers";
2440
+ /**
2441
+ * Deploy (or update) a reverse-proxy Worker for `hostname`.
2442
+ * Forwards all `hostname/*` requests to `config.target`, injecting
2443
+ * `config.headers` on each request.
2444
+ */
2445
+ upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
2446
+ /** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
2447
+ deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
2448
+ /**
2449
+ * Set one secret binding on a script that is already deployed, leaving its code and every other binding alone.
2450
+ * The value is write-only. `holocron secrets sync --worker` uses it to fan a vault out to a Worker.
2451
+ */
2452
+ setSecret?(script: string, name: string, value: string): Promise<void>;
2453
+ /** The names (never the values) of the secrets bound to a deployed script. `holocron probe` uses it to see what a Worker has. */
2454
+ secretNames?(script: string): Promise<string[]>;
2455
+ /**
2456
+ * Read a deployed script without changing it: whether it exists, which route patterns serve it in the zone `host`
2457
+ * is in, and the names of its bindings. Read-only; `holocron doctor notifications` uses it to check the relay.
2458
+ * Optional — a provider that cannot read its scripts omits it.
2459
+ */
2460
+ inspectScript?(name: string, host: string): Promise<WorkerScriptState>;
2461
+ /**
2462
+ * A `holocron doctor` smoke check — every other method either mutates or
2463
+ * needs a specific script/zone doctor has no way to supply up front.
2464
+ * Reports how many Worker scripts the token can see.
2465
+ */
2466
+ whoami?(): Promise<{
2467
+ ok: boolean;
2468
+ scripts: number;
2469
+ }>;
2470
+ }
2471
+ /** Where a tunnel should send the requests for a hostname. */
2472
+ interface TunnelRoute {
2473
+ /** The tunnel's name. The tunnel is found by it, so a second call finds the first one's tunnel. */
2474
+ name: string;
2475
+ /** The public hostname the tunnel serves, e.g. `sentinel-dev.example.dev`. */
2476
+ hostname: string;
2477
+ /** The origin the requests are sent to, e.g. `http://localhost:3000`. */
2478
+ service: string;
2479
+ }
2480
+ /** What {@link Tunnels.ensureTunnel} found or made. */
2481
+ interface EnsuredTunnel {
2482
+ /** The tunnel's id at the provider. */
2483
+ id: string;
2484
+ /** The tunnel's name. */
2485
+ name: string;
2486
+ /** Whether the tunnel did not exist and was made. */
2487
+ created: boolean;
2488
+ /** Whether the tunnel's routes were changed to serve the hostname. */
2489
+ configured: boolean;
2490
+ /** The host a `CNAME` for the hostname points at, so the `dns` provider can finish the job. */
2491
+ target: string;
2492
+ }
2493
+ /**
2494
+ * Named tunnels: a stable public hostname that reaches a port on this machine, for a webhook that has to find a
2495
+ * development instance. A quick tunnel changes its address on every run, which a GitHub App's webhook URL cannot.
2496
+ * The provider makes the tunnel and its routes; the DNS record for the hostname is the `dns` provider's.
2497
+ */
2498
+ interface Tunnels extends ProviderIdentity {
2499
+ /** Identifies this provider as the `tunnels` capability. */
2500
+ readonly key: "tunnels";
2501
+ /**
2502
+ * Find the tunnel by name or make it, and make it serve `route.hostname` at `route.service`. Routes for other
2503
+ * hostnames are kept. Idempotent: a tunnel that already serves the hostname is left alone.
2504
+ */
2505
+ ensureTunnel(route: TunnelRoute): Promise<EnsuredTunnel>;
2506
+ /** The token the tunnel's connector runs with. A credential: never print or store it. */
2507
+ tunnelToken(tunnelId: string): Promise<string>;
2508
+ /** A `holocron doctor` smoke check: reports how many tunnels the token can see. */
2509
+ whoami?(): Promise<{
2510
+ ok: boolean;
2511
+ tunnels: number;
2512
+ }>;
2513
+ }
2514
+ /**
2515
+ * A place this machine reads its own tokens from, as named variables (`HOLOCRON_ORG_TOKEN`, ...).
2516
+ *
2517
+ * Not the same job as {@link Vault}, the source of truth `holocron secrets sync` fans out to other services. A
2518
+ * credentials provider answers a plugin asking "where do I get my token?" before it can talk to anything, so it must
2519
+ * authenticate without a token of its own: 1Password does (the desktop app and Touch ID on a laptop, a service
2520
+ * account in CI). A provider that needs a stored token to be read cannot be one.
2521
+ *
2522
+ * `holocron.config` names the environment with `credentials.environment`. Several providers can be configured and
2523
+ * are tried in order. A token the process environment or a `.env` file already has wins over all of them.
2524
+ */
2525
+ interface Credentials extends ProviderIdentity {
2526
+ /** Identifies this provider as the `credentials` capability. */
2527
+ readonly key: "credentials";
2528
+ /**
2529
+ * Every variable of the environment `environment`, by name. The CLI reads it once per process and looks each
2530
+ * token up in the result, so a provider that prompts (Touch ID) prompts once for all of them.
2531
+ * Rejects when the environment cannot be read; the CLI then falls through to the next source.
2532
+ */
2533
+ read(environment: string): Promise<Record<string, string>>;
2534
+ /**
2535
+ * Which environment `environment` really is and the names of its variables, without reading any value. Used by
2536
+ * `holocron doctor credentials`. Optional: a provider that cannot list names without values leaves it out and
2537
+ * the check is skipped for it. Rejects when the environment cannot be found.
2538
+ */
2539
+ inspect?(environment: string): Promise<CredentialsInspection>;
2540
+ }
2541
+ /** What {@link Credentials.inspect} found: the environment as the provider spells it, and its variable names. */
2542
+ interface CredentialsInspection {
2543
+ /** The environment's name as the provider matched it, which can differ in case from the configured one. */
2544
+ environment: string;
2545
+ /** The names of its variables, never their values. */
2546
+ names: string[];
2547
+ }
2548
+ /**
2549
+ * What a status means, whatever the board calls it. A provider maps a category to its own states (Jira groups
2550
+ * statuses into To Do, In Progress and Done), and the doctor, `reconcile` and `move` read the category, so "closed and
2551
+ * not done" never depends on an option being spelled `Done`. It is not the `issues` capability's {@link StatusCategory}: a board
2552
+ * tells a backlog idea from planned work and shows a blocked item, which an issue's own status does not.
2553
+ */
2554
+ type BoardStatusCategory = "backlog" | "planned" | "active" | "blocked" | "done";
2555
+ /** One status a board offers, with the category that says what it means. */
2556
+ interface BoardStatus {
2557
+ /** The status as the board shows it, e.g. `In Progress`. */
2558
+ name: string;
2559
+ /** What the status means. */
2560
+ category: BoardStatusCategory;
2561
+ /** A colour name for the status, e.g. `GRAY`. A provider without colours ignores it. */
2562
+ color?: string;
2563
+ /** A line saying when to use the status. */
2564
+ description?: string;
2565
+ }
2566
+ /** The kinds of field a board can hold besides its status. */
2567
+ type BoardFieldType = "single_select" | "text" | "number" | "date" | "iteration";
2568
+ /** A field of a board besides its status. */
2569
+ interface BoardField {
2570
+ /** The field's name, e.g. `Priority`. */
2571
+ name: string;
2572
+ /** What the field holds. */
2573
+ type: BoardFieldType;
2574
+ /** The choices of a `single_select` field, in order. */
2575
+ options?: string[];
2576
+ }
2577
+ /** A saved way of looking at a board. */
2578
+ interface BoardView {
2579
+ /** The view's name, shown on its tab. */
2580
+ name: string;
2581
+ /** `board` is columns by status, `table` is rows. */
2582
+ layout: "board" | "table";
2583
+ /** A filter expression in the provider's syntax, e.g. `-status:Done`. */
2584
+ filter?: string;
2585
+ /** The name of a field to group by. */
2586
+ groupBy?: string;
2587
+ /** Whether this view opens first. The first view wins when several are set. */
2588
+ default?: boolean;
2589
+ }
2590
+ /**
2591
+ * What a board should look like, whole: the resolved form of a template. `setup` applies it, `doctor project` compares
2592
+ * it with the live board and `create` makes a board from it.
2593
+ */
2594
+ interface BoardTemplate {
2595
+ /** The template's name, e.g. `roadmap`. */
2596
+ name: string;
2597
+ /** The statuses, in the order the board shows them. */
2598
+ statuses: BoardStatus[];
2599
+ /** The other fields. */
2600
+ fields: BoardField[];
2601
+ /** The views. */
2602
+ views: BoardView[];
2603
+ /** The automation rules that should be on, as the provider names them. A provider that cannot create one reports it. */
2604
+ rules?: string[];
2605
+ /** A board to copy when this one is created, which carries its automation rules. A provider without a copy ignores it. */
2606
+ source?: string;
2607
+ }
2608
+ /**
2609
+ * What a template file holds. With `extends` it names a template to start from and adds to it; without, it is a whole
2610
+ * template and the three lists are required. `resolveTemplate()` turns one into a {@link BoardTemplate}.
2611
+ */
2612
+ interface BoardTemplateFile {
2613
+ /** The template's name. Defaults to the file's name. */
2614
+ name?: string;
2615
+ /** A template to inherit the statuses, fields, views and rules of. */
2616
+ extends?: string;
2617
+ /** The statuses; with `extends`, added to the inherited ones. */
2618
+ statuses?: BoardStatus[];
2619
+ /** The fields; with `extends`, added to the inherited ones. */
2620
+ fields?: BoardField[];
2621
+ /** The views; with `extends`, added to the inherited ones. */
2622
+ views?: BoardView[];
2623
+ /** The automation rules that should be on. */
2624
+ rules?: string[];
2625
+ /** A board to copy when this one is created. */
2626
+ source?: string;
2627
+ }
2628
+ /** A board as `list` and `find` return it. */
2629
+ interface BoardSummary {
2630
+ /** The provider's id for the board. Opaque: only the provider reads it. */
2631
+ id: string;
2632
+ /** The board's number where the provider has one (a GitHub project). */
2633
+ number?: number;
2634
+ /** The board's name, which is how it is found. */
2635
+ name: string;
2636
+ /** Where to open it. */
2637
+ url: string;
2638
+ /** Whether the board is closed. */
2639
+ closed: boolean;
2640
+ }
2641
+ /** An automation rule of a board and whether it is on. */
2642
+ interface BoardRule {
2643
+ /** The rule's name as the provider spells it. */
2644
+ name: string;
2645
+ /** Whether it is on. */
2646
+ enabled: boolean;
2647
+ }
2648
+ /** The live board, read for `setup` to compare with a template and for `doctor project`. */
2649
+ interface BoardState {
2650
+ /** The board. */
2651
+ board: BoardSummary;
2652
+ /** The status names, in order. */
2653
+ statuses: string[];
2654
+ /** The other fields, in order. */
2655
+ fields: BoardField[];
2656
+ /** The views. */
2657
+ views: BoardView[];
2658
+ /** The automation rules. */
2659
+ rules: BoardRule[];
2660
+ }
2661
+ /** One item of a board: an issue or a pull request, named by its `issues` key. */
2662
+ interface BoardItem {
2663
+ /** The item's key, the one the `issues` capability uses (`#42`, or `owner/repo#42` from another repository). */
2664
+ key: string;
2665
+ /** The item's title. */
2666
+ title: string;
2667
+ /** Whether the issue or pull request is open. Closed and merged ones are not. */
2668
+ open: boolean;
2669
+ /** The item's status, or undefined when it has none. */
2670
+ status?: string;
2671
+ /** The category of that status, when the template knows it. */
2672
+ category?: BoardStatusCategory;
2673
+ /** The keys of the open issues this one is blocked by. */
2674
+ blockedBy: string[];
2675
+ /** The item's priority, when the board holds one. */
2676
+ priority?: IssuePriority;
2677
+ }
2678
+ /** What {@link Projects.ensure} did to bring a board in line with a template. */
2679
+ interface EnsureReport {
2680
+ /** Whether the board did not exist and was made. */
2681
+ created: boolean;
2682
+ /** What was changed, one line each, e.g. `status Blocked added`. */
2683
+ changes: string[];
2684
+ /** What the provider cannot do and a person must, one line each, e.g. `turn on the rule "Item closed"`. */
2685
+ todos: string[];
2686
+ }
2687
+ /** One issue to put on a board with {@link Projects.addItems}, with the values it should start with. */
2688
+ interface BoardItemInput {
2689
+ /** The issue's key in the provider's own tracker (`#42`). */
2690
+ key: string;
2691
+ /** The status the issue had where it came from, by name; used when the board has an option of that name. */
2692
+ status?: string;
2693
+ /** The category that status falls into; used to find the board's own status when no option has the name. */
2694
+ category?: BoardStatusCategory;
2695
+ /** How urgent the issue is. `none` sets nothing. */
2696
+ priority?: IssuePriority;
2697
+ }
2698
+ /** What {@link Projects.addItems} did with one issue. */
2699
+ interface AddedItem {
2700
+ /** The issue's key, as it was given. */
2701
+ key: string;
2702
+ /** Whether it was put on the board now; false when it was already there. */
2703
+ added: boolean;
2704
+ /** The values the board has no option for and so were left unset, e.g. `priority urgent (no matching option on the board)`. */
2705
+ dropped: string[];
2706
+ }
2707
+ /** What {@link Projects.move} did between two boards. */
2708
+ interface MoveReport {
2709
+ /** Keys of the open items put on the target board. */
2710
+ moved: string[];
2711
+ /** Keys of the open items that were already on the target and kept its values. */
2712
+ kept: string[];
2713
+ /** Keys of closed items left on the source, with the status they were set to where it was wrong. */
2714
+ left: string[];
2715
+ }
2716
+ /**
2717
+ * Project management: boards that plan work, in a vocabulary no tracker owns (board, item, status with a category,
2718
+ * blocker, rule, template). `issues` is one issue; `projects` is the surface that holds them. A GitHub project, a Jira
2719
+ * board or a Linear view is one provider, so a change of tracker is a provider entry and a plugin and nothing else.
2720
+ *
2721
+ * `owner` is whoever the boards belong to: a GitHub organization, a Jira site. A board is found by its name among the
2722
+ * open boards, and an item is an `issues` key, so nothing here knows what a node id is.
2723
+ */
2724
+ interface Projects extends ProviderIdentity {
2725
+ /** Identifies this provider as the `projects` capability. */
2726
+ readonly key: "projects";
2727
+ /** Every board of the owner, open and closed. */
2728
+ list(owner: string): Promise<BoardSummary[]>;
2729
+ /** The open board with exactly this name, or undefined. */
2730
+ find(owner: string, name: string): Promise<BoardSummary | undefined>;
2731
+ /** Make a board from the template (copying `template.source` where the provider can) and return it. */
2732
+ create(owner: string, name: string, template: BoardTemplate): Promise<BoardSummary>;
2733
+ /** Close a board. Reversible. */
2734
+ close(owner: string, board: BoardSummary): Promise<void>;
2735
+ /** The live board, for `setup` to diff and `doctor project` to compare. */
2736
+ read(owner: string, board: BoardSummary): Promise<BoardState>;
2737
+ /**
2738
+ * Bring the board in line with the template and report what changed and what only a person can do. Never deletes a
2739
+ * field, option or view the template does not mention, and never clears an item's value. Optional: a provider may
2740
+ * only list and close.
2741
+ */
2742
+ ensure?(owner: string, board: BoardSummary, template: BoardTemplate): Promise<EnsureReport>;
2743
+ /** The board's items with their status, whether their issue is open and their open blockers. Optional. */
2744
+ items?(owner: string, board: BoardSummary, template: BoardTemplate): Promise<BoardItem[]>;
2745
+ /**
2746
+ * Put an item in a status. Idempotent: `transitioned` is false when it is already there. A provider that works
2747
+ * through a workflow (Jira) can refuse, and says why in `via`. Optional.
2748
+ */
2749
+ setStatus?(owner: string, board: BoardSummary, key: string, status: string): Promise<LifecycleResult>;
2750
+ /**
2751
+ * Put issues on the board and give each the status and priority of its input, where the board has an option for it.
2752
+ * An issue already on the board keeps its place and its values, and a value is only set where the item has none, so
2753
+ * a second run changes nothing. A value with no matching option is reported in `dropped`, never created. Optional.
2754
+ */
2755
+ addItems?(owner: string, board: BoardSummary, items: BoardItemInput[], template: BoardTemplate): Promise<AddedItem[]>;
2756
+ /**
2757
+ * Put the open items of one board on another, with their status and priority; leave closed ones behind. An item
2758
+ * already on the target keeps its values. Optional.
2759
+ */
2760
+ move?(owner: string, from: BoardSummary, to: BoardSummary, template: BoardTemplate): Promise<MoveReport>;
2761
+ /** A `holocron doctor` smoke check: reports how many boards the token can see. */
2762
+ whoami?(): Promise<{
2763
+ ok: boolean;
2764
+ boards: number;
2765
+ }>;
2766
+ }
2767
+ /** One idea as a provider holds it, in a shape no provider owns. */
2768
+ interface IdeaRecord {
2769
+ /** The provider's address for the idea (a path, for Obsidian). Opaque to the CLI; the hidden issue marker carries it. */
2770
+ key: string;
2771
+ /** The idea's title. */
2772
+ title: string;
2773
+ /** The idea's text, which becomes the body of the issue. */
2774
+ body: string;
2775
+ /** The idea's state, in the repo's own words (`seed`, `in-progress`, ...); empty when it has none. */
2776
+ status: string;
2777
+ /** The issue the idea was filed as, in the tracker's own syntax; absent when it is not filed. */
2778
+ issue?: string;
2779
+ /**
2780
+ * What the provider cannot put in an issue body (an embedded image or file, another note). The command reports an
2781
+ * idea that has any and does not file it.
2782
+ */
2783
+ attachments: string[];
2784
+ /**
2785
+ * Set when the provider could not read the idea; the other fields are then empty. The command reports it as a
2786
+ * failing row and goes on with the rest.
2787
+ */
2788
+ error?: string;
2789
+ }
2790
+ /**
2791
+ * Where ideas are kept before they are issues: an inbox the process starts from (`idea -> issue -> spec -> ...`). A
2792
+ * folder of notes, a forum or a database is one provider, so `holocron ideas sync` reads through this and files through
2793
+ * `issues`, and a change of place is a provider entry and a plugin and nothing else. Optional: a repo with no `ideas`
2794
+ * provider is not affected.
2795
+ */
2796
+ interface Ideas extends ProviderIdentity {
2797
+ /** Identifies this provider as the `ideas` capability. */
2798
+ readonly key: "ideas";
2799
+ /** Every idea the provider holds, in a provider-neutral shape. Throws when the provider cannot reach its store. */
2800
+ list(): Promise<IdeaRecord[]>;
2801
+ /** Moves an idea to a state. */
2802
+ setStatus(key: string, status: string): Promise<void>;
2803
+ /** Records the issue an idea was filed as, so the step runs once. */
2804
+ markFiled(key: string, issue: string): Promise<void>;
2805
+ /** Takes a filed idea out of the inbox. Optional: the CLI never deletes, so a provider may leave it to an app. */
2806
+ retire?(key: string): Promise<void>;
2807
+ }
2808
+ /** Maps each capability key to the interface its provider implements. */
2809
+ interface CapabilityImpls {
2810
+ /** The `source` provider. */
2811
+ source: Source;
2812
+ /** The `ci` provider. */
2813
+ ci: Ci;
2814
+ /** The `secrets` provider. */
2815
+ secrets: Secrets;
2816
+ /** The `environments` provider. */
2817
+ environments: Environments;
2818
+ /** The `issues` provider. */
2819
+ issues: Issues;
2820
+ /** The `deployment` provider. */
2821
+ deployment: Deployment;
2822
+ /** The `storage` provider. */
2823
+ storage: Storage;
2824
+ /** The `auth` provider. */
2825
+ auth: Auth;
2826
+ /** The `vault` provider. */
2827
+ vault: Vault;
2828
+ /** The `dns` provider. */
2829
+ dns: Dns;
2830
+ /** The `tooling` provider. */
2831
+ tooling: Tooling;
2832
+ /** The `notifications` provider. */
2833
+ notifications: Notifications;
2834
+ /** The `analytics` provider. */
2835
+ analytics: Analytics;
2836
+ /** The `errors` provider. */
2837
+ errors: Errors;
2838
+ /** The `logs` provider. */
2839
+ logs: Logs;
2840
+ /** The `monitoring` provider. */
2841
+ monitoring: Monitoring;
2842
+ /** The `wiki` provider. */
2843
+ wiki: Wiki;
2844
+ /** The `workers` provider. */
2845
+ workers: Workers;
2846
+ /** The `tunnels` provider. */
2847
+ tunnels: Tunnels;
2848
+ /** The `credentials` providers. */
2849
+ credentials: Credentials;
2850
+ /** The `projects` provider. */
2851
+ projects: Projects;
2852
+ /** The `ideas` provider. */
2853
+ ideas: Ideas;
2854
+ }
2855
+ /** The cardinality (`"single"` or `"many"`) of the capability `K`. */
2856
+ type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
2857
+ /** Resolved runtime shape: single → one impl; many → array. */
2858
+ type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
2859
+ /** How many providers each capability resolves to: one (`"single"`) or several active at once (`"many"`). */
2860
+ declare const CARDINALITY: {
2861
+ /** `source` has exactly one provider. */
2862
+ readonly source: "single";
2863
+ /** `ci` has exactly one provider. */
2864
+ readonly ci: "single";
2865
+ /** `secrets` has exactly one provider. */
2866
+ readonly secrets: "single";
2867
+ /** `environments` has exactly one provider. */
2868
+ readonly environments: "single";
2869
+ /** `issues` has exactly one provider. */
2870
+ readonly issues: "single";
2871
+ /** `deployment` has exactly one provider. */
2872
+ readonly deployment: "single";
2873
+ /** `storage` has exactly one provider. */
2874
+ readonly storage: "single";
2875
+ /** `auth` has exactly one provider. */
2876
+ readonly auth: "single";
2877
+ /** `vault` has exactly one provider. */
2878
+ readonly vault: "single";
2879
+ /** `dns` has exactly one provider. */
2880
+ readonly dns: "single";
2881
+ /** `tooling` can have several providers active at once. */
2882
+ readonly tooling: "many";
2883
+ /** `notifications` can have several providers active at once. */
2884
+ readonly notifications: "many";
2885
+ /** `analytics` can have several providers active at once. */
2886
+ readonly analytics: "many";
2887
+ /** `errors` has exactly one provider. */
2888
+ readonly errors: "single";
2889
+ /** `logs` has exactly one provider. */
2890
+ readonly logs: "single";
2891
+ /** `monitoring` has exactly one provider. */
2892
+ readonly monitoring: "single";
2893
+ /** `wiki` has exactly one provider. */
2894
+ readonly wiki: "single";
2895
+ /** `workers` has exactly one provider. */
2896
+ readonly workers: "single";
2897
+ /** `tunnels` has exactly one provider. */
2898
+ readonly tunnels: "single";
2899
+ /** `projects` has exactly one provider. */
2900
+ readonly projects: "single";
2901
+ /** `ideas` has exactly one provider. Optional: no repo has to declare it. */
2902
+ readonly ideas: "single";
2903
+ /** `credentials` can have several providers, tried in order. */
2904
+ readonly credentials: "many";
2905
+ };
2906
+ /**
2907
+ * No capabilities are strictly required — repos without secrets (e.g. org
2908
+ * community health repos) legitimately omit vault. Plugins validate their
2909
+ * own requirements at call time.
2910
+ */
2911
+ declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
2912
+ /**
2913
+ * A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
2914
+ * needs to give it for one run and take it away again, so `setup` can walk them through it.
2915
+ */
2916
+ declare class ElevationRequiredError extends Error {
2917
+ /** What a person must approve to give the permission for one run and to take it away again. */
2918
+ readonly elevation: {
2919
+ /** The permission, in the provider's own name for it. */
2920
+ permission: string;
2921
+ /** Where to approve giving it; absent when the provider could not build one. */
2922
+ grantUrl?: string;
2923
+ /** Where to approve taking it away again; absent when the provider could not build one. */
2924
+ revokeUrl?: string;
2925
+ /** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
2926
+ label?: string;
2927
+ /** The permission is meant to stay once given: there is nothing to take away afterwards. */
2928
+ keep?: boolean;
2929
+ /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
2930
+ applied?: string[];
2931
+ };
2932
+ /** Lets a caller tell this error from any other by name, across package copies. */
2933
+ name: string;
2934
+ constructor(message: string,
2935
+ /** What a person must approve to give the permission for one run and to take it away again. */
2936
+ elevation: {
2937
+ /** The permission, in the provider's own name for it. */
2938
+ permission: string;
2939
+ /** Where to approve giving it; absent when the provider could not build one. */
2940
+ grantUrl?: string;
2941
+ /** Where to approve taking it away again; absent when the provider could not build one. */
2942
+ revokeUrl?: string;
2943
+ /** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
2944
+ label?: string;
2945
+ /** The permission is meant to stay once given: there is nothing to take away afterwards. */
2946
+ keep?: boolean;
2947
+ /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
2948
+ applied?: string[];
2949
+ }, options?: ErrorOptions);
2950
+ }
2951
+ /**
2952
+ * A provider cannot do a read because it has no token for it. A check that meets this skips with the message instead
2953
+ * of failing: the token is missing, not wrong.
2954
+ */
2955
+ declare class MissingTokenError extends Error {
2956
+ /** Lets a caller tell this error from any other by name, across package copies. */
2957
+ name: string;
2958
+ }
2959
+ /** A webhook payload failed signature verification, so it must not be trusted. */
2960
+ declare class WebhookVerificationError extends Error {
2961
+ /** Lets a caller tell this error from any other by name, across package copies. */
2962
+ name: string;
2963
+ }
2964
+ /** Whether `key` is a capability that can have several providers active at once. */
2965
+ declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
2966
+ export { DnsRecord as $, NotificationsForumTag as $t, Cardinality as A, SourceSecurity as An, LifecycleResult as At, DeployFunctionConfig as B, TrackerDoctorReport as Bn, MonitoringAssertionComparison as Bt, BoardStatusCategory as C, Secrets as Cn, IssueOrder as Ct, BoardView as D, SourceFile as Dn, IssueSelector as Dt, BoardTemplateFile as E, SourceBranch as En, IssueSearchFilter as Et, CiRunStatus as F, SyncResult as Fn, MonitoringAlertChannelInput as Ft, DeploymentProject as G, WebhookDashboardInfo as Gn, MoveReport as Gt, DeployScriptConfig as H, TunnelRoute as Hn, MonitoringCheck as Ht, ConnectionStringOptions as I, TeamEntry as In, MonitoringAlertChannelResult as It, DeploymentTarget as J, WikiProxyConfig as Jn, NotificationsAccess as Jt, DeploymentProjectSettings as K, Wiki as Kn, NormalizedAuthUser as Kt, CreateAuthUserInput as L, TeamPermission as Ln, MonitoringAlertChannelState as Lt, Ci as M, StatusCategory as Mn, Logs as Mt, CiRun as N, Storage as Nn, LogsDataset as Nt, CapabilityImpls as O, SourceRepoInfo as On, Issues as Ot, CiRunFilter as P, StorageBranch as Pn, Monitoring as Pt, Dns as Q, NotificationsEveryoneLayout as Qt, Credentials as R, Tooling as Rn, MonitoringAlertSettings as Rt, BoardStatus as S, SecretScope as Sn, IssueComment as St, BoardTemplate as T, Source as Tn, IssueRecord as Tt, DeployScriptResult as U, Tunnels as Un, MonitoringCheckInput as Ut, DeployFunctionResult as V, TrackerUser as Vn, MonitoringAssertionSource as Vt, Deployment as W, Vault as Wn, MonitoringHttpMethod as Wt, DiscussionPatch as X, Workers as Xn, NotificationsChannelLayout as Xt, DeploymentTrigger as Y, WorkerScriptState as Yn, NotificationsApplicationLayout as Yt, DiscussionPost as Z, NotificationsDelivery as Zt, BoardFieldType as _, RelayState as _n, Ideas as _t, REQUIRED_CAPABILITIES as a, NotificationsPicture as an, EnsureReport as at, BoardRule as b, ResolvedCapability as bn, InspectRelayInput as bt, AddedItem as c, NotificationsServerLayout as cn, EnsuredDiscussion as ct, AuthDescription as d, NotificationsWelcomeLayout as dn, Environment as dt, NotificationsLayout as en, DnsRecordRequest as et, AuthEvent as f, PagesConfig as fn, EnvironmentReviewer as ft, BoardField as g, PullRequest as gn, IdeaRecord as gt, AuthUser as h, ProviderIdentity as hn, ExportInfo as ht, ProviderApiError as i, NotificationsOnboardingLayout as in, EnsureRelayResult as it, CardinalityFor as j, SourceTeamMember as jn, LifecycleSlot as jt, CapabilityKey as k, SourceRulesetDetail as kn, LabelDef as kt, Analytics as l, NotificationsSignIn as ln, EnsuredResource as lt, AuthIdentity as m, Projects as mn, Errors as mt, ElevationRequiredError as n, NotificationsMember as nn, EnsureDiscussionInput as nt, WebhookVerificationError as o, NotificationsPinnedLayout as on, EnsureResult as ot, AuthEventType as p, ParseWebhookInput as pn, Environments as pt, DeploymentRecord as q, WikiProvisionOpts as qn, Notifications as qt, MissingTokenError as r, NotificationsMonitoringFeed as rn, EnsureRelayInput as rt, isMulti as s, NotificationsPrsFeed as sn, EnsureWebhookResult as st, CARDINALITY as t, NotificationsLinksLayout as tn, DnsRecordType as tt, Auth as u, NotificationsSignedIn as un, EnsuredTunnel as ut, BoardItem as v, RepoRef as vn, ImportOptions as vt, BoardSummary as w, ServerInspection as wn, IssuePriority as wt, BoardState as x, Ruleset as xn, Issue as xt, BoardItemInput as y, RepoSettings as yn, ImportResult as yt, CredentialsInspection as z, ToolingDoctorReport as zn, MonitoringAssertion as zt };