@theholocron/cli 5.0.0-alpha.27 → 5.0.0-alpha.271

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,1685 @@
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";
15
+ type Cardinality = "single" | "many";
16
+ interface ProviderIdentity {
17
+ readonly key: CapabilityKey;
18
+ readonly providerName: string;
19
+ }
20
+ interface Ruleset {
21
+ id: number;
22
+ name: string;
23
+ enforcement: "active" | "evaluate" | "disabled";
24
+ target?: string;
25
+ }
26
+ interface RepoSettings {
27
+ allow_squash_merge?: boolean;
28
+ allow_merge_commit?: boolean;
29
+ allow_rebase_merge?: boolean;
30
+ allow_auto_merge?: boolean;
31
+ /** Always suggest updating PR branches when the base branch has new commits. */
32
+ allow_update_branch?: boolean;
33
+ delete_branch_on_merge?: boolean;
34
+ default_branch?: string;
35
+ has_issues?: boolean;
36
+ has_discussions?: boolean;
37
+ has_projects?: boolean;
38
+ has_wiki?: boolean;
39
+ }
40
+ interface RepoRef {
41
+ owner: string;
42
+ name: string;
43
+ defaultBranch: string;
44
+ }
45
+ interface LabelDef {
46
+ readonly name: string;
47
+ readonly color: string;
48
+ readonly description: string;
49
+ }
50
+ type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
51
+ /** Shorthand `"slug"` defaults to `push` permission. */
52
+ type TeamEntry = string | {
53
+ slug: string;
54
+ permission: TeamPermission;
55
+ };
56
+ /** A member of a team, as {@link Source.teamMembers} reports it. */
57
+ interface SourceTeamMember {
58
+ /** The provider's stable id for the person; for GitHub, the numeric user id as a string. */
59
+ id: string;
60
+ /** What they are called now. Can change; never use it as a key. */
61
+ login: string;
62
+ }
63
+ /** A file read by {@link Source.readFile}. */
64
+ interface SourceFile {
65
+ content: string;
66
+ /** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
67
+ version: string;
68
+ }
69
+ interface Source extends ProviderIdentity {
70
+ readonly key: "source";
71
+ /** Auth sanity-check. Throws ProviderApiError on auth failure. */
72
+ whoami(): Promise<{
73
+ login: string;
74
+ }>;
75
+ getRepo(): Promise<RepoRef>;
76
+ listRulesets(): Promise<Ruleset[]>;
77
+ createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
78
+ updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
79
+ updateRepoSettings(settings: RepoSettings): Promise<void>;
80
+ /**
81
+ * Classic branch protection — fallback for private repos on free plans
82
+ * where the Rulesets API (requires Team+) returns 403.
83
+ */
84
+ protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
85
+ enableVulnerabilityAlerts(): Promise<void>;
86
+ enableAutomatedSecurityFixes(): Promise<void>;
87
+ enableSecretScanning(): Promise<void>;
88
+ enablePrivateVulnerabilityReporting(): Promise<void>;
89
+ /**
90
+ * Enables the dependency graph and automatic dependency snapshot
91
+ * submission. Also enables secret-scanning validity checks and
92
+ * non-provider pattern detection — these require GitHub Advanced
93
+ * Security at the org level; the call is accepted but may be a no-op
94
+ * until that is configured.
95
+ */
96
+ enableDependencyGraph(): Promise<void>;
97
+ /**
98
+ * Enables CodeQL default setup with the extended query suite and
99
+ * `threat_model: all` (scans both remote and local exploit paths).
100
+ * Triggers a new analysis run; returns the run id.
101
+ */
102
+ enableCodeScanning(): Promise<string>;
103
+ /**
104
+ * Disables CodeQL default setup. Required when the repo uses an advanced
105
+ * CodeQL workflow instead — GitHub rejects SARIF from advanced workflows
106
+ * while default setup is active.
107
+ */
108
+ disableDefaultCodeScanning(): Promise<void>;
109
+ listWorkflowFiles(): Promise<string[]>;
110
+ readWorkflowFile(name: string): Promise<string | null>;
111
+ writeWorkflowFile(name: string, contents: string): Promise<void>;
112
+ removeWorkflowFile(name: string): Promise<void>;
113
+ /**
114
+ * Write an arbitrary file relative to the repo root. Used for
115
+ * provisioning config files that live outside `.github/workflows/`
116
+ * (e.g. `.github/dependabot.yml`).
117
+ */
118
+ writeRepoFile(path: string, contents: string): Promise<void>;
119
+ /**
120
+ * Idempotently sync repo labels to a canonical set. Creates missing
121
+ * labels, patches color/description drift, deletes stale labels.
122
+ * Optional — providers that have no label concept omit this.
123
+ */
124
+ syncLabels?(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
125
+ /**
126
+ * Set org-level custom property values on the repo. `string[]` for
127
+ * `multi_select` properties, plain `string` for everything else.
128
+ * Optional — providers that don't support custom properties omit this.
129
+ */
130
+ syncProperties?(values: Record<string, string | string[]>): Promise<string>;
131
+ /**
132
+ * Replace the repo's topic set with the supplied list.
133
+ * Optional — providers that don't support topics omit this.
134
+ */
135
+ syncTopics?(topics: string[]): Promise<string>;
136
+ /**
137
+ * Bring the repository's Actions variables in line with the declared ones: create what is missing, update what
138
+ * differs, leave the rest. With `prune`, also delete the ones the declaration does not name. With `dryRun`, read the current
139
+ * state and report what would change without writing. Returns a summary.
140
+ * Optional — providers without Actions variables omit this.
141
+ */
142
+ syncVariables?(variables: Record<string, string>, opts?: {
143
+ prune?: boolean;
144
+ dryRun?: boolean;
145
+ }): Promise<string>;
146
+ /**
147
+ * The same for the organization's variables, each with the repositories that can read it (`all` or `private`).
148
+ * Optional — providers without organization variables omit this.
149
+ */
150
+ syncOrgVariables?(org: string, variables: Record<string, {
151
+ value: string;
152
+ visibility: "all" | "private";
153
+ }>, opts?: {
154
+ prune?: boolean;
155
+ dryRun?: boolean;
156
+ }): Promise<string>;
157
+ /**
158
+ * The repository's Actions variables as they are now, by name, with their values. Read-only.
159
+ * Optional — providers without Actions variables omit this.
160
+ */
161
+ listVariables?(): Promise<Record<string, string>>;
162
+ /**
163
+ * The organization's Actions variables as they are now, by name, with each value and the repositories that can read
164
+ * it (`selected` is a list this interface does not manage). Read-only. Throws {@link MissingTokenError} when the
165
+ * provider has no token that can read them.
166
+ * Optional — providers without organization variables omit this.
167
+ */
168
+ listOrgVariables?(org: string): Promise<Record<string, {
169
+ value: string;
170
+ visibility: "all" | "private" | "selected";
171
+ }>>;
172
+ /**
173
+ * Sync GitHub team repository access. String shorthand defaults to `push`.
174
+ * Optional — providers without a team concept omit this.
175
+ */
176
+ syncTeams?(teams: TeamEntry[]): Promise<string>;
177
+ /**
178
+ * The members of a team in `org` (default: the repo's organisation), by the provider's own stable id (for GitHub, the
179
+ * numeric user id, which survives a rename) and current login.
180
+ * Optional — providers without a team concept omit this.
181
+ */
182
+ teamMembers?(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
183
+ /**
184
+ * Read one file from a repository (default: this one), with the `version` a later {@link writeFile} must
185
+ * hand back. `null` when the file does not exist.
186
+ * Optional — providers that cannot read file contents omit this.
187
+ */
188
+ readFile?(path: string, repo?: string): Promise<SourceFile | null>;
189
+ /**
190
+ * Create or replace one file in a single commit. Pass the `version` {@link readFile} returned when
191
+ * replacing, and leave it out when creating: a write on top of a version that has since changed is
192
+ * refused (throws a `ProviderApiError` with status 409 or 422), so two writers cannot overwrite each other.
193
+ * Optional — providers that cannot write file contents omit this.
194
+ */
195
+ writeFile?(path: string, content: string, opts: {
196
+ message: string;
197
+ version?: string;
198
+ repo?: string;
199
+ }): Promise<void>;
200
+ /**
201
+ * Set the repository description.
202
+ * Optional — providers that don't support setting descriptions omit this.
203
+ */
204
+ syncDescription?(description: string): Promise<string>;
205
+ /**
206
+ * Set the repository homepage URL (the "Website" field on the repo landing page).
207
+ * Optional — providers that don't support setting a homepage omit this.
208
+ */
209
+ syncHomepage?(homepage: string): Promise<string>;
210
+ /**
211
+ * Fetch a pull request by number. The `repo` override lets callers look up
212
+ * a PR in a different repo than the one the plugin is scoped to — useful
213
+ * when the cleanup command targets another repo's PR (e.g. docs PR from
214
+ * the holocron repo context).
215
+ * Optional — providers without a PR concept omit this.
216
+ */
217
+ getPullRequest?(number: number, repo?: string): Promise<PullRequest>;
218
+ /**
219
+ * Every pull request in one state, newest first. `closed` includes the merged ones (`merged` tells them
220
+ * apart). Optional — providers without a PR concept omit this.
221
+ */
222
+ listPullRequests?(state: "open" | "closed", repo?: string): Promise<PullRequest[]>;
223
+ /**
224
+ * The commit SHAs of one pull request, in commit order. A squash-merged branch is not an ancestor of the
225
+ * base, so this is how a local tip is matched to a PR whose head commit is not in the checkout.
226
+ * Optional — providers without a PR concept omit this.
227
+ */
228
+ listPullRequestCommits?(number: number, repo?: string): Promise<string[]>;
229
+ /**
230
+ * Every branch on the remote, with the commit each points at.
231
+ * Optional — providers without branches omit this.
232
+ */
233
+ listBranches?(repo?: string): Promise<SourceBranch[]>;
234
+ /**
235
+ * Delete one branch on the remote. Idempotent: a branch that is already gone is success, not an error.
236
+ * Optional — providers that cannot delete a branch omit this.
237
+ */
238
+ deleteBranch?(name: string, repo?: string): Promise<void>;
239
+ /**
240
+ * Enable or update GitHub Pages for the repository.
241
+ * Idempotent: POST to create, PUT to update existing settings.
242
+ * Requires HOLOCRON_DEPLOY_TOKEN (pages:write + repo scope) — passed
243
+ * explicitly because it is a different PAT from the main admin token.
244
+ * Optional — providers without a Pages concept omit this.
245
+ */
246
+ configurePages?(config: PagesConfig, token: string): Promise<void>;
247
+ }
248
+ interface PagesConfig {
249
+ /** GitHub Pages build source. */
250
+ build: "workflow" | "branch";
251
+ /**
252
+ * Custom domain / CNAME (e.g. "docs.theholocron.dev").
253
+ * When set and `homepage` is absent in holocron.config, setup derives
254
+ * homepage as `https://{domain}/`.
255
+ */
256
+ domain?: string;
257
+ /** Enforce HTTPS. Only effective once the custom domain is DNS-verified. */
258
+ https?: boolean;
259
+ }
260
+ /** A branch on the remote and the commit it points at. */
261
+ interface SourceBranch {
262
+ /** The branch name, e.g. `fix/my-change`. */
263
+ name: string;
264
+ /** The commit the branch points at. */
265
+ sha: string;
266
+ }
267
+ interface PullRequest {
268
+ number: number;
269
+ title: string;
270
+ /** "open" | "closed" — GitHub marks merged PRs as "closed". */
271
+ state: "open" | "closed";
272
+ /** True when the PR was merged (as opposed to closed without merging). */
273
+ merged: boolean;
274
+ /** The head branch name (e.g. "fix/my-change"). */
275
+ branch: string;
276
+ /** The commit the head branch pointed at when the PR was last read. */
277
+ headSha?: string;
278
+ url: string;
279
+ }
280
+ type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
281
+ interface CiRun {
282
+ id: string | number;
283
+ workflowName: string;
284
+ branch: string;
285
+ sha: string;
286
+ status: CiRunStatus;
287
+ url: string;
288
+ startedAt: string;
289
+ completedAt?: string;
290
+ }
291
+ interface CiRunFilter {
292
+ branch?: string;
293
+ status?: CiRunStatus;
294
+ limit?: number;
295
+ }
296
+ interface Ci extends ProviderIdentity {
297
+ readonly key: "ci";
298
+ listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
299
+ getRun(id: string | number): Promise<CiRun>;
300
+ }
301
+ type SecretScope = {
302
+ kind: "repo";
303
+ } | {
304
+ kind: "environment";
305
+ name: string;
306
+ } | {
307
+ kind: "organization";
308
+ name: string;
309
+ };
310
+ interface Secrets extends ProviderIdentity {
311
+ readonly key: "secrets";
312
+ /** List secret NAMES (not values) at the given scope. */
313
+ listSecrets(scope: SecretScope): Promise<string[]>;
314
+ /** Idempotent upsert. Adapter handles encryption. */
315
+ setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
316
+ deleteSecret(scope: SecretScope, name: string): Promise<void>;
317
+ }
318
+ interface EnvironmentReviewer {
319
+ type: "User" | "Team";
320
+ /** Numeric id — GitHub's reviewer API silently ignores login strings. */
321
+ id: number;
322
+ }
323
+ interface Environment {
324
+ name: string;
325
+ reviewers?: EnvironmentReviewer[];
326
+ waitTimer?: number;
327
+ preventSelfReview?: boolean;
328
+ }
329
+ interface Environments extends ProviderIdentity {
330
+ readonly key: "environments";
331
+ listEnvironments(): Promise<Environment[]>;
332
+ upsertEnvironment(env: Environment): Promise<void>;
333
+ deleteEnvironment(name: string): Promise<void>;
334
+ }
335
+ type LifecycleSlot = "inProgress" | "inReview" | "done";
336
+ type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
337
+ interface TrackerUser {
338
+ id: string;
339
+ displayName: string;
340
+ emailAddress?: string;
341
+ }
342
+ interface Issue {
343
+ /** Human-readable key — "#42" for GitHub, "RANDO-42" for Jira. */
344
+ key: string;
345
+ /** Internal opaque id. */
346
+ id: string;
347
+ summary: string;
348
+ body?: string;
349
+ status: string;
350
+ statusCategory: StatusCategory;
351
+ assignee: TrackerUser | null;
352
+ updated: string;
353
+ url?: string;
354
+ }
355
+ interface IssueSearchFilter {
356
+ /** Restrict to issues assigned to a specific id, or 'currentUser'. */
357
+ assignee?: string | "currentUser";
358
+ /** Exclude issues in the `done` category. */
359
+ openOnly?: boolean;
360
+ /** Max number of issues to return. Adapters apply a sensible default. */
361
+ limit?: number;
362
+ }
363
+ interface LifecycleResult {
364
+ /** False when no API write happened (already at target state). */
365
+ transitioned: boolean;
366
+ /** Status name the issue is in after this call. */
367
+ status: string;
368
+ /** Adapter-specific note (e.g., "label set" / "closed (completed)"). */
369
+ via?: string;
370
+ }
371
+ interface TrackerDoctorReport {
372
+ /** "Authenticated as ..." subject for the spinner. */
373
+ authedAs: string;
374
+ /** Free-form "Project: RANDO" / "Repo: rando-id/rando" identifier. */
375
+ projectLabel: string;
376
+ /** Status values the adapter exposes. */
377
+ statuses: Array<{
378
+ name: string;
379
+ category: StatusCategory;
380
+ }>;
381
+ /**
382
+ * Per-lifecycle-slot readiness check. `resolved` indicates whether
383
+ * the configured value actually maps to something the tracker
384
+ * recognizes; the `note` is the rendered explanation.
385
+ */
386
+ lifecycle: Array<{
387
+ slot: LifecycleSlot;
388
+ value: string | null;
389
+ resolved: boolean;
390
+ note: string;
391
+ }>;
392
+ }
393
+ interface Issues extends ProviderIdentity {
394
+ readonly key: "issues";
395
+ /** Currently-authenticated user. */
396
+ getMyself(): Promise<TrackerUser>;
397
+ search(filter: IssueSearchFilter): Promise<Issue[]>;
398
+ get(key: string): Promise<Issue>;
399
+ create(input: {
400
+ summary: string;
401
+ body?: string;
402
+ labels?: string[];
403
+ /** Numeric id or exact title (case-insensitive). */
404
+ milestone?: string;
405
+ }): Promise<{
406
+ key: string;
407
+ }>;
408
+ /** Idempotent — `transitioned: false` if the issue is already at the target. */
409
+ transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
410
+ comment(key: string, body: string): Promise<void>;
411
+ doctor(): Promise<TrackerDoctorReport>;
412
+ }
413
+ /** Env-var scope on the deploy platform. */
414
+ type DeploymentTarget = "development" | "preview" | "production";
415
+ /**
416
+ * Named deployment trigger target — `undefined` means a branch
417
+ * preview (no named environment).
418
+ */
419
+ type DeploymentTrigger = "production" | "staging";
420
+ interface DeploymentProject {
421
+ id: string;
422
+ name: string;
423
+ framework?: string;
424
+ /** True when the project is linked to a Git provider. */
425
+ gitLinked?: boolean;
426
+ rootDirectory?: string | null;
427
+ }
428
+ interface DeploymentProjectSettings {
429
+ previewDeploymentsDisabled?: boolean;
430
+ /** Vercel-specific: whether the GitHub integration creates deployments
431
+ * for every push (false → only on-demand triggers). */
432
+ gitProviderCreateDeployments?: boolean;
433
+ }
434
+ interface DeploymentRecord {
435
+ id: string;
436
+ url: string;
437
+ /** Branch this deployment was made from (null if not git-sourced). */
438
+ branch: string | null;
439
+ /** Named environment if one was targeted; undefined for branch previews. */
440
+ target?: DeploymentTrigger;
441
+ status: "queued" | "building" | "ready" | "error" | "cancelled";
442
+ createdAt?: string;
443
+ /** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
444
+ errorMessage?: string;
445
+ }
446
+ /** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
447
+ interface DeployFunctionConfig {
448
+ /**
449
+ * Files to deploy, keyed by path relative to the project root (e.g.
450
+ * `"api/webhook.js"`, `"package.json"`). Content is plain text — the
451
+ * provider handles any wire-format encoding.
452
+ */
453
+ files: Record<string, string>;
454
+ /**
455
+ * Named deployment target. Omit for a preview deployment — same
456
+ * semantics as `triggerDeployment`'s `target`.
457
+ */
458
+ target?: DeploymentTrigger;
459
+ }
460
+ interface DeployFunctionResult {
461
+ deploymentId: string;
462
+ url: string;
463
+ }
464
+ interface Deployment extends ProviderIdentity {
465
+ readonly key: "deployment";
466
+ /**
467
+ * Custom domain declared in the deployment provider's configuration.
468
+ * `holocron repo setup` attaches it to the configured project and hands any
469
+ * returned verification record to the `dns` capability.
470
+ */
471
+ readonly domain?: string;
472
+ listProjects(): Promise<DeploymentProject[]>;
473
+ /** Create if missing, otherwise return existing. Idempotent. */
474
+ ensureProject(input: {
475
+ name: string;
476
+ framework?: string;
477
+ /** "owner/repo" — passed when linking to a Git provider. */
478
+ repo?: string;
479
+ rootDirectory?: string;
480
+ }): Promise<DeploymentProject>;
481
+ updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
482
+ listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
483
+ setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
484
+ /**
485
+ * Kick off a deployment of the given branch. Omit `target` for a
486
+ * branch preview; pass `'production'` / `'staging'` to deploy into
487
+ * a named environment.
488
+ */
489
+ triggerDeployment(input: {
490
+ projectId: string;
491
+ branch: string;
492
+ target?: DeploymentTrigger;
493
+ }): Promise<DeploymentRecord>;
494
+ getDeployment(deploymentId: string): Promise<DeploymentRecord>;
495
+ /**
496
+ * Deploy (or update) a project directly from source files, bypassing
497
+ * Git entirely — the non-git counterpart to `triggerDeployment`, for a
498
+ * consumer with no repo to link (a webhook receiver shipped as an npm
499
+ * package, for instance, rather than deployed from its own Git
500
+ * history). `projectId` may be a project name for providers that
501
+ * accept either. Optional — providers without a files-based deploy API
502
+ * omit this (e.g. Cloudflare Pages, git-source only today).
503
+ */
504
+ deployFunction?(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
505
+ /**
506
+ * List preview deployments for a specific branch alias (e.g. "repo-pr-42").
507
+ * Optional — providers that don't support listing by branch omit this.
508
+ */
509
+ listPreviewDeployments?(projectId: string, branch: string): Promise<DeploymentRecord[]>;
510
+ /**
511
+ * Delete specific preview deployments by id. Returns the count deleted.
512
+ * Optional — providers that don't support deletion omit this.
513
+ */
514
+ deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
515
+ /**
516
+ * Add a custom domain (or wildcard) to the project. Idempotent — no-op
517
+ * when the domain is already present. Optional: providers without a
518
+ * custom domain API omit this.
519
+ *
520
+ * Returns the DNS record needed to finish verification — `null` when
521
+ * the domain is already verified, or when the provider's API doesn't
522
+ * surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
523
+ * custom-domain flow doesn't expose the same per-request verification
524
+ * handshake Vercel's does). Callers hand a non-null result straight
525
+ * to `dns.upsertRecord(result.zone, result.record)` — the exact
526
+ * pattern `setup` already uses for `Wiki.dnsRecord()`.
527
+ */
528
+ ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
529
+ }
530
+ interface StorageBranch {
531
+ id: string;
532
+ name: string;
533
+ /** Parent branch id; null for the root/main branch. */
534
+ parentId: string | null;
535
+ createdAt: string;
536
+ }
537
+ interface ConnectionStringOptions {
538
+ /** Use the pooled (PgBouncer) URL when available. Defaults to false. */
539
+ pooled?: boolean;
540
+ }
541
+ interface Storage extends ProviderIdentity {
542
+ readonly key: "storage";
543
+ /**
544
+ * Connection string for the given scope. Scope is provider-specific:
545
+ *
546
+ * - branch-based providers (Neon, PlanetScale): scope = branch
547
+ * name or id
548
+ * - flat providers (single Postgres instance): scope is ignored
549
+ *
550
+ * Callers (or the orchestrator) decide how a deploy target maps to
551
+ * a scope; the storage plugin doesn't own that mapping.
552
+ */
553
+ getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
554
+ listBranches?(): Promise<StorageBranch[]>;
555
+ createBranch?(input: {
556
+ name: string;
557
+ from?: string;
558
+ }): Promise<StorageBranch>;
559
+ destroyBranch?(branch: string): Promise<void>;
560
+ /** Restore one branch to match another (e.g., reset preview → main). */
561
+ resetBranch?(input: {
562
+ branch: string;
563
+ from: string;
564
+ }): Promise<void>;
565
+ /**
566
+ * Provider-specific feature toggle. For Postgres providers this is
567
+ * `CREATE EXTENSION IF NOT EXISTS ...` per branch.
568
+ */
569
+ enableExtension?(input: {
570
+ branch: string;
571
+ extension: string;
572
+ }): Promise<void>;
573
+ }
574
+ interface AuthDescription {
575
+ provider: string;
576
+ /** Env-var names the app needs at runtime (CLERK_PUBLISHABLE_KEY, etc.). */
577
+ envKeys: string[];
578
+ }
579
+ interface AuthIdentity {
580
+ provider: string;
581
+ /** Provider-specific health signal (user count, role, account name, etc.). */
582
+ details?: Record<string, unknown>;
583
+ }
584
+ interface AuthUser {
585
+ id: string;
586
+ email: string;
587
+ }
588
+ interface CreateAuthUserInput {
589
+ email: string;
590
+ password: string;
591
+ firstName?: string;
592
+ lastName?: string;
593
+ }
594
+ interface WebhookDashboardInfo {
595
+ url: string;
596
+ }
597
+ interface Auth extends ProviderIdentity {
598
+ readonly key: "auth";
599
+ /** Env-var keys the runtime app needs. */
600
+ describe(): Promise<AuthDescription>;
601
+ /** Reachability probe — proves the configured key works. */
602
+ whoami(): Promise<AuthIdentity>;
603
+ /** Idempotent webhook backend provisioning (Clerk: Svix app). */
604
+ ensureWebhookApp?(): Promise<{
605
+ alreadyExists: boolean;
606
+ }>;
607
+ /** Deep-link to the provider's webhook config dashboard. */
608
+ getWebhookDashboardUrl?(): Promise<WebhookDashboardInfo>;
609
+ /** Seed a user (test fixtures, admin bootstrap). */
610
+ createUser?(input: CreateAuthUserInput): Promise<AuthUser>;
611
+ /** Wire the auth provider's webhook into the project's repo. */
612
+ syncWebhook?(input: {
613
+ repo: string;
614
+ secretRef: string;
615
+ }): Promise<void>;
616
+ }
617
+ type AuthEventType = "user.created" | "user.updated" | "user.deleted";
618
+ interface NormalizedAuthUser {
619
+ id: string;
620
+ email: string;
621
+ firstName?: string | null;
622
+ lastName?: string | null;
623
+ /** Provider-native fields preserved verbatim for consumers that need them. */
624
+ raw?: Record<string, unknown>;
625
+ }
626
+ interface AuthEvent {
627
+ type: AuthEventType;
628
+ user: NormalizedAuthUser;
629
+ /** ISO timestamp of when the event occurred. */
630
+ occurredAt: string;
631
+ }
632
+ interface ParseWebhookInput {
633
+ /** Raw request body (string or Buffer). */
634
+ body: string | Buffer;
635
+ /** Incoming HTTP headers — needed for signature verification. */
636
+ headers: Record<string, string | string[] | undefined>;
637
+ /** The signing secret the auth provider issued for this webhook endpoint. */
638
+ signingSecret: string;
639
+ }
640
+ interface EnsureResult {
641
+ /** True when the resource already existed (idempotent no-op). */
642
+ alreadyExists: boolean;
643
+ }
644
+ interface Vault extends ProviderIdentity {
645
+ readonly key: "vault";
646
+ /**
647
+ * Read a secret by reference. The reference format is
648
+ * provider-specific (1P: "op://Vault/Item/field"; HashiCorp Vault:
649
+ * "kv/path#field"; etc.). Adapters validate the reference shape.
650
+ */
651
+ read(reference: string): Promise<string>;
652
+ /**
653
+ * Optional — read a secret by its bare name from the project and config this vault was set up with, instead of by a
654
+ * full reference. For a provider whose references name the project and config the options already carry (Doppler).
655
+ */
656
+ readSecret?(name: string): Promise<string>;
657
+ /** Write or update a secret. */
658
+ write(reference: string, value: string): Promise<void>;
659
+ /** List secret keys available to the project. */
660
+ list(): Promise<string[]>;
661
+ /**
662
+ * Optional environment notion within the vault (e.g., 1P
663
+ * Environments — named KEY=VALUE bundles). Adapters without
664
+ * environments return [].
665
+ */
666
+ environments?(): Promise<string[]>;
667
+ /**
668
+ * Optional bulk read of an environment's KEY=VALUE pairs. Powers
669
+ * the `holocron secrets sync` flow where the orchestrator pulls a
670
+ * whole environment from the vault then fans the values out to
671
+ * destinations (CI secrets, deployment env vars, local .env).
672
+ */
673
+ readEnvironment?(environmentId: string): Promise<Record<string, string>>;
674
+ /**
675
+ * Optional — create the top-level project container in the vault
676
+ * if it does not exist. Idempotent: `alreadyExists: true` when the
677
+ * project was already there. Providers whose data model has no
678
+ * project notion (or that gate this behind a paid tier) omit this.
679
+ */
680
+ ensureProject?(name: string): Promise<EnsureResult>;
681
+ /**
682
+ * Optional — create a named environment/config inside a project
683
+ * (e.g., Doppler config `dev` / `stg` / `prd`). Idempotent.
684
+ * Providers whose data model has a single flat namespace omit this.
685
+ */
686
+ ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
687
+ }
688
+ type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
689
+ interface DnsRecord {
690
+ id?: string;
691
+ type: DnsRecordType;
692
+ name: string;
693
+ content: string;
694
+ ttl?: number;
695
+ priority?: number;
696
+ proxied?: boolean;
697
+ }
698
+ /**
699
+ * A DNS record a capability wants created, plus which zone it belongs
700
+ * to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
701
+ * both hand off to `Dns.upsertRecord()`. Not tied to either capability;
702
+ * any provider that needs "here's a record, go create it" returns this.
703
+ */
704
+ interface DnsRecordRequest {
705
+ /** Zone apex passed as the first argument to `dns.upsertRecord`. */
706
+ zone: string;
707
+ record: DnsRecord;
708
+ }
709
+ interface Dns extends ProviderIdentity {
710
+ readonly key: "dns";
711
+ listRecords(domain: string): Promise<DnsRecord[]>;
712
+ upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
713
+ deleteRecord(domain: string, id: string): Promise<void>;
714
+ /**
715
+ * A `holocron doctor` smoke check with no specific domain to ask about —
716
+ * `listRecords` needs one, but doctor doesn't have one on hand. Verifies
717
+ * the token and reports how many zones it can see.
718
+ */
719
+ whoami?(): Promise<{
720
+ ok: boolean;
721
+ zones: number;
722
+ }>;
723
+ }
724
+ interface Errors extends ProviderIdentity {
725
+ readonly key: "errors";
726
+ /** Returns the env var names the app reads at runtime for this provider. */
727
+ describe(): Promise<{
728
+ provider: string;
729
+ envKeys: string[];
730
+ }>;
731
+ /**
732
+ * Reachability probe. `null` means the check genuinely can't run right
733
+ * now on an otherwise-valid configuration (e.g. Sentry's optional `org`
734
+ * setting is unset — error ingestion still works from the DSN alone,
735
+ * `org` is only needed for the management-API calls `whoami` makes) —
736
+ * callers should fall back to `describe()`, not treat it as a failure.
737
+ * Still throws for a genuine failure (bad token, network error, etc.).
738
+ */
739
+ whoami?(): Promise<{
740
+ org: string;
741
+ } | null>;
742
+ ensureProject?(input: {
743
+ name: string;
744
+ platform?: string;
745
+ }): Promise<{
746
+ dsn: string;
747
+ alreadyExists: boolean;
748
+ }>;
749
+ /**
750
+ * Make the tracker send its alerts to a relay (the Comlink Worker): an integration that posts to `webhookUrl`, and
751
+ * an alert rule on each project that uses it. Idempotent: an integration or rule with the same name is adopted and
752
+ * only what differs is changed. `clientSecret` is the integration's signing secret, handed to the caller to give
753
+ * the relay; it is a credential and must not be printed or stored anywhere but there. It is absent when the
754
+ * provider did not give it (some show it only when the integration is made).
755
+ */
756
+ ensureRelay?(input: EnsureRelayInput): Promise<EnsureRelayResult>;
757
+ }
758
+ interface EnsureRelayInput {
759
+ /** The integration's name at the provider (also how an existing one is found). */
760
+ name: string;
761
+ /** Where the provider posts its alerts, e.g. `https://comlink.theholocron.dev/sentry`. */
762
+ webhookUrl: string;
763
+ /** The projects whose issues are sent. */
764
+ projects: string[];
765
+ /** The alert rule: its name, and the minutes between two notifications for one issue (default 5). */
766
+ rule: {
767
+ name: string;
768
+ frequency?: number;
769
+ };
770
+ }
771
+ interface EnsureRelayResult {
772
+ integration: {
773
+ created: boolean;
774
+ updated: string[];
775
+ };
776
+ rule: {
777
+ created: boolean;
778
+ updated: string[];
779
+ };
780
+ clientSecret?: string;
781
+ }
782
+ interface Logs extends ProviderIdentity {
783
+ readonly key: "logs";
784
+ /** Returns the env var names the app reads at runtime for this provider. */
785
+ describe(): Promise<{
786
+ provider: string;
787
+ envKeys: string[];
788
+ }>;
789
+ /** Verify the token by fetching the target dataset's info. */
790
+ whoami?(): Promise<{
791
+ ok: boolean;
792
+ dataset: string;
793
+ }>;
794
+ /** Create the aggregation dataset if it does not already exist. Idempotent. */
795
+ ensureDataset?(name: string): Promise<{
796
+ alreadyExists: boolean;
797
+ }>;
798
+ }
799
+ type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
800
+ type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
801
+ interface MonitoringAssertion {
802
+ source: MonitoringAssertionSource;
803
+ comparison: MonitoringAssertionComparison;
804
+ /** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
805
+ property?: string;
806
+ target?: string;
807
+ }
808
+ type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
809
+ interface MonitoringCheckInput {
810
+ /** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
811
+ name: string;
812
+ url: string;
813
+ method?: MonitoringHttpMethod;
814
+ /** Minutes between runs. Adapters round to their own supported values. */
815
+ frequency?: number;
816
+ assertions?: MonitoringAssertion[];
817
+ activated?: boolean;
818
+ /**
819
+ * Provider-specific region/datacenter ids to run the check from (e.g.
820
+ * Checkly's `"us-east-1"`). Required by some providers — there's no
821
+ * universal default; an account with none configured rejects a check
822
+ * that omits this entirely.
823
+ */
824
+ locations?: string[];
825
+ /**
826
+ * Inverts pass/fail: set this when the check's expected-healthy
827
+ * response is itself an HTTP error status (e.g. asserting a 404/405
828
+ * on an endpoint that should reject certain requests). Without it,
829
+ * most providers classify any 4xx/5xx response as a failure at the
830
+ * platform level *before* evaluating `assertions` at all — a custom
831
+ * assertion that matches the "expected" error status does not
832
+ * override that baseline classification on its own.
833
+ */
834
+ shouldFail?: boolean;
835
+ /**
836
+ * Raw request body to send with the check — e.g. simulating a webhook
837
+ * delivery to verify signature/auth checking is wired correctly
838
+ * end-to-end, rather than just confirming the endpoint is reachable.
839
+ * Omitted entirely by default (no body sent).
840
+ */
841
+ body?: string;
842
+ }
843
+ interface MonitoringCheck {
844
+ id: string;
845
+ name: string;
846
+ }
847
+ /** A place the monitoring provider sends its alerts: a webhook that posts into a chat channel. */
848
+ interface MonitoringAlertChannelInput {
849
+ /** Also the idempotency key: an existing channel with this name is adopted and brought in line. */
850
+ name: string;
851
+ /** The chat service the message is formatted for. */
852
+ format: "discord";
853
+ /**
854
+ * Where alerts post: a credential, because anyone holding it can post to the channel. Absent when the webhook already
855
+ * existed and cannot be read back, in which case an existing alert channel keeps the URL it has and a missing one
856
+ * cannot be created.
857
+ */
858
+ url?: string;
859
+ }
860
+ interface MonitoringAlertChannelResult {
861
+ created: boolean;
862
+ /** For an existing channel, what was brought in line (`"url"`, `"subscriptions"`). */
863
+ updated: string[];
864
+ /** How many checks the channel is subscribed to afterwards. */
865
+ subscribed: number;
866
+ }
867
+ interface Monitoring extends ProviderIdentity {
868
+ readonly key: "monitoring";
869
+ /**
870
+ * Checks this provider is configured to ensure exist — populated from
871
+ * the provider's own config (`holocron.config.ts`'s provider tuple),
872
+ * the same place `Deployment.domain` comes from. `holocron repo setup`
873
+ * loops this list and calls `ensureCheck` for each; empty when none
874
+ * are configured.
875
+ */
876
+ readonly checks: readonly MonitoringCheckInput[];
877
+ /**
878
+ * The service's own picture, for the webhook it posts through (see `feeds.monitoring`): where to fetch it, and the
879
+ * image itself as a `data:` URI for when that cannot be reached. Used when the config names no picture of its own.
880
+ */
881
+ readonly icon?: {
882
+ url?: string;
883
+ dataUri?: string;
884
+ };
885
+ /** Auth sanity-check. Throws ProviderApiError on auth failure. */
886
+ whoami?(): Promise<{
887
+ ok: boolean;
888
+ }>;
889
+ /** Idempotent find-or-create-or-update by `input.name`. */
890
+ ensureCheck(input: MonitoringCheckInput): Promise<{
891
+ check: MonitoringCheck;
892
+ alreadyExists: boolean;
893
+ }>;
894
+ /**
895
+ * Find-or-create-or-update an alert channel by name and subscribe every check the provider has to it. Checks made
896
+ * through an API are never subscribed automatically, so a later run subscribes the ones added since.
897
+ * Optional — a provider with no alert channels omits it.
898
+ */
899
+ ensureAlertChannel?(input: MonitoringAlertChannelInput): Promise<MonitoringAlertChannelResult>;
900
+ }
901
+ interface ToolingDoctorReport {
902
+ ok: boolean;
903
+ message: string;
904
+ }
905
+ interface Tooling extends ProviderIdentity {
906
+ readonly key: "tooling";
907
+ /** Sync the tool's authoritative state from the repo. */
908
+ sync(): Promise<void>;
909
+ doctor(): Promise<ToolingDoctorReport>;
910
+ }
911
+ /** What an `ensure*` call found or made. `created: false` means it already existed. */
912
+ interface EnsuredResource {
913
+ id: string;
914
+ created: boolean;
915
+ /** For something that already existed: the settings that disagreed with the layout and were changed. */
916
+ updated?: string[];
917
+ }
918
+ /** A webhook (or equivalent inbound URL) for a channel. */
919
+ interface EnsureWebhookResult {
920
+ created: boolean;
921
+ /**
922
+ * The posting URL — a credential. Absent when the webhook already existed and
923
+ * the provider will not reveal it again (Discord returns the token only to
924
+ * the application that created the webhook, and only on creation).
925
+ */
926
+ url?: string;
927
+ /** For a webhook that already existed, or was just made: the settings that were set (`"avatar"`). */
928
+ updated?: string[];
929
+ /** Set when the webhook is fine but setting its avatar failed; the webhook and its `url` are still good. */
930
+ avatarError?: string;
931
+ }
932
+ /**
933
+ * Who may see a channel and post in it. Roles are named as in the layout's `roles`.
934
+ * A channel inherits its category's access; stating `view` or `post` on the channel
935
+ * replaces that field only.
936
+ */
937
+ interface NotificationsAccess {
938
+ /** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
939
+ view?: "everyone" | string[];
940
+ /** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
941
+ post?: "everyone" | string[];
942
+ }
943
+ /** One channel in a {@link NotificationsLayout}. */
944
+ interface NotificationsChannelLayout {
945
+ name: string;
946
+ topic?: string;
947
+ /** Who may see and post. Overrides the category's, field by field. */
948
+ access?: NotificationsAccess;
949
+ /**
950
+ * Create an inbound webhook for the channel and store its URL in a secret.
951
+ * `true` uses the defaults; the object form overrides the webhook's display
952
+ * name and the secret's name.
953
+ */
954
+ webhook?: boolean | {
955
+ name?: string;
956
+ secret?: string;
957
+ avatar?: string;
958
+ };
959
+ /**
960
+ * Other services that post into this channel through a webhook of their own. Each gets a dedicated webhook, whose
961
+ * URL goes straight to that service and is never stored as a secret, so revoking one service leaves the rest alone.
962
+ */
963
+ feeds?: {
964
+ /**
965
+ * The monitoring provider's alerts. `true` uses the defaults; the object form overrides the alert channel's name
966
+ * (default `Message to #<channel>`) and the dedicated webhook's name (default the provider's name, capitalised), and
967
+ * `avatar` gives that webhook a picture (PNG, JPEG or GIF): a file path or `https://` URL, or `{ url, image }`, where the `url` is tried first and the `image`, a file in the repo, is the fallback) in the provider's list of
968
+ * integrations. Left out, it wears the layout's `webhookAvatar`, as every webhook does. A picture is set only on a
969
+ * webhook that has none; the posts carry the service's own name and icon either way.
970
+ */
971
+ monitoring?: boolean | {
972
+ name?: string;
973
+ webhook?: string;
974
+ avatar?: string | {
975
+ url?: string;
976
+ image?: string;
977
+ };
978
+ };
979
+ /**
980
+ * The error tracker's alerts, carried in by the relay Worker (see `relay`). The channel gets a dedicated webhook
981
+ * (default the `errors` provider's name, capitalised) whose URL goes to the Worker as a secret and nowhere else.
982
+ * `avatar` is as for `monitoring`.
983
+ */
984
+ errors?: boolean | {
985
+ webhook?: string;
986
+ avatar?: string | {
987
+ url?: string;
988
+ image?: string;
989
+ };
990
+ };
991
+ };
992
+ }
993
+ /**
994
+ * Settings of the server itself. Channels are named as in the layout's `categories`; each field
995
+ * left out is left alone.
996
+ */
997
+ interface NotificationsServerLayout {
998
+ /** 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). */
999
+ verification?: "none" | "low" | "medium" | "high" | "highest";
1000
+ /** Whether members are notified for every message or only when mentioned. */
1001
+ defaultNotifications?: "all" | "mentions";
1002
+ /** Which members' media is scanned: `off`, `noRoles` (members without a role) or `all`. */
1003
+ contentFilter?: "off" | "noRoles" | "all";
1004
+ /** Where the provider posts its own notices (member joins, boosts). */
1005
+ systemChannel?: string;
1006
+ /** The channel holding the server rules; required to turn community features on. */
1007
+ rulesChannel?: string;
1008
+ /** Where the provider sends its notices to the owners; required to turn community features on. */
1009
+ updatesChannel?: string;
1010
+ /** Turn community features (welcome screen, onboarding, discovery) on or off. */
1011
+ community?: boolean;
1012
+ /** The server's public description. Only providers that support one for the server's current state accept it. */
1013
+ description?: string;
1014
+ /** Preferred language, as a locale such as `en-US`. */
1015
+ locale?: string;
1016
+ }
1017
+ /** A message the provider posts in a channel and pins, so it stays at the top. */
1018
+ interface NotificationsPinnedLayout {
1019
+ /** A channel in the layout. */
1020
+ channel: string;
1021
+ /** The message text (Discord allows up to 2000 characters). */
1022
+ content: string;
1023
+ }
1024
+ /**
1025
+ * The screen a new member sees on joining: a short text and the channels worth visiting first.
1026
+ * Declaring it describes the whole screen: the text and the channels are set to exactly this, so to
1027
+ * switch it off, state them as well.
1028
+ */
1029
+ interface NotificationsWelcomeLayout {
1030
+ /** Whether the screen is shown. Defaults to `true`. */
1031
+ enabled?: boolean;
1032
+ /** A sentence or two about the server (Discord allows up to 140 characters). */
1033
+ description: string;
1034
+ /** The channels it points to, in order (Discord allows up to five). */
1035
+ channels: Array<{
1036
+ /** A channel in the layout. */
1037
+ channel: string;
1038
+ /** Why to visit it (Discord allows up to 50 characters). */
1039
+ description: string;
1040
+ /** A single emoji shown beside it. */
1041
+ emoji?: string;
1042
+ }>;
1043
+ }
1044
+ /** The questions a new member answers to be shown the channels that fit them. */
1045
+ interface NotificationsOnboardingLayout {
1046
+ /** Turn onboarding on or off. Left out, it is left as it is (Discord has requirements for turning it on). */
1047
+ enabled?: boolean;
1048
+ /** Channels every member starts with, by name. */
1049
+ defaultChannels?: string[];
1050
+ prompts?: Array<{
1051
+ title: string;
1052
+ /** One answer only (`true`) or any number. Defaults to `false`. */
1053
+ singleSelect?: boolean;
1054
+ /** The member must answer. Defaults to `false`. */
1055
+ required?: boolean;
1056
+ options: Array<{
1057
+ title: string;
1058
+ description?: string;
1059
+ emoji?: string;
1060
+ /** Channels this answer shows, by name. */
1061
+ channels?: string[];
1062
+ /** Roles this answer gives, by name from the layout's `roles`. */
1063
+ roles?: string[];
1064
+ }>;
1065
+ }>;
1066
+ }
1067
+ /**
1068
+ * Settings of the bot's own application (for Discord, what the developer portal shows). A field left
1069
+ * out is left alone.
1070
+ */
1071
+ interface NotificationsApplicationLayout {
1072
+ /** What the application's page says it is (Discord allows up to 400 characters). */
1073
+ description?: string;
1074
+ /** Short labels, up to five of up to twenty characters each. */
1075
+ tags?: string[];
1076
+ /** The default install link: what the bot is added with. Permissions are named, as in a role's. */
1077
+ install?: {
1078
+ scopes: string[];
1079
+ permissions: string[];
1080
+ };
1081
+ /** `https://` link to the terms of service. */
1082
+ termsUrl?: string;
1083
+ /** `https://` link to the privacy policy. */
1084
+ privacyUrl?: string;
1085
+ /** `https://` link the provider calls to verify linked roles. */
1086
+ roleConnectionsUrl?: string;
1087
+ /**
1088
+ * Privileged intents the bot needs. `members` lets it list who is in the server, which `sync-roles` needs to
1089
+ * find who holds a role. `true` switches it on from code; `false` switches it off.
1090
+ */
1091
+ intents?: {
1092
+ members?: boolean;
1093
+ };
1094
+ /**
1095
+ * OAuth2 redirect URIs that must be registered, for `notifications link`. The provider's API does not allow
1096
+ * setting them, so these are only checked: `setup` and the doctor say what to add and where.
1097
+ */
1098
+ redirectUris?: string[];
1099
+ }
1100
+ /**
1101
+ * Permissions of everyone on the server (for Discord, the @everyone role). Unlike a role's `permissions`,
1102
+ * these name only what to change: the rest of the set is left as it is.
1103
+ */
1104
+ interface NotificationsEveryoneLayout {
1105
+ /** Permissions to grant. */
1106
+ allow?: string[];
1107
+ /** Permissions to take away. */
1108
+ deny?: string[];
1109
+ }
1110
+ /** Where the person-to-member links live: one file in a repo, written by the sign-in flow and read by `sync-roles`. */
1111
+ interface NotificationsLinksLayout {
1112
+ /**
1113
+ * The base URL of the hosted sign-in service (Sentinel), for example `https://sentinel.theholocron.dev`.
1114
+ * `notifications link` asks it for `/api/link`; when it answers, sign-in happens there, and when it does not
1115
+ * (down, out of quota, no route yet) the command signs in on this machine instead.
1116
+ */
1117
+ hostedUrl?: string;
1118
+ /** The port the local sign-in listens on, which must be registered as `http://localhost:<port>/callback`. Defaults to 53682. */
1119
+ localPort?: number;
1120
+ /** `owner/name`. Defaults to `<org>/.github-private`. Keep it private: the file pairs two identities. */
1121
+ repo?: string;
1122
+ /** Defaults to `notifications/<provider>-links.json`. */
1123
+ path?: string;
1124
+ }
1125
+ /** A declared server layout, applied idempotently by `holocron notifications setup`. */
1126
+ interface NotificationsLayout {
1127
+ /**
1128
+ * The channel set aside for test posts, by name. It must declare a webhook. `holocron doctor notifications`
1129
+ * leaves one labelled test message there through its webhook (read back to prove delivery works) for a
1130
+ * person to look at; the real channels are never given one unless `--deliver` posts and removes it.
1131
+ */
1132
+ testChannel?: string;
1133
+ /** Where `sync-roles` finds which server member is which GitHub account. Only used by roles with a `team`. */
1134
+ links?: NotificationsLinksLayout;
1135
+ /** The bot's own application settings, applied with the server's. */
1136
+ application?: NotificationsApplicationLayout;
1137
+ /** What everyone on the server may do, applied with the server's settings. */
1138
+ everyone?: NotificationsEveryoneLayout;
1139
+ /**
1140
+ * The picture every webhook gets unless its own `webhook.avatar` says otherwise: a path to a PNG,
1141
+ * JPEG or GIF (from where the CLI runs) or an `https://` URL. It is set only on a webhook that has
1142
+ * no picture yet -- a provider cannot say whether the one it holds is the same image.
1143
+ */
1144
+ webhookAvatar?: string;
1145
+ /**
1146
+ * The Worker that carries other services' alerts into the channels with a `feeds.errors`: built beforehand
1147
+ * (`apps/comlink`), deployed by `notifications setup` with each channel's webhook URL as a secret, and served at
1148
+ * `host`. Secrets set some other way (the service's signing secret) are kept across deploys.
1149
+ */
1150
+ relay?: {
1151
+ /** Where the Worker answers, e.g. `comlink.theholocron.dev`. Its DNS record and route are managed. */
1152
+ host: string;
1153
+ /** The DNS zone the host is in. Default: found by the `dns` provider from the host itself, so rarely needed. */
1154
+ zone?: string;
1155
+ /** The Worker's name at the provider. Default `comlink`. */
1156
+ script?: string;
1157
+ /** The built Worker, relative to the repo root. Default `apps/comlink/dist/worker.js`. */
1158
+ code?: string;
1159
+ /**
1160
+ * The error tracker's side, when its provider can manage it (`Errors.ensureRelay`): the projects whose issues
1161
+ * are sent, the integration's name (default `Comlink`) and the alert rule's name (default
1162
+ * `Errors to Discord (Comlink)`) and throttle in minutes (default 5). Left out, nothing is done at the tracker.
1163
+ */
1164
+ errors?: {
1165
+ projects: string[];
1166
+ integration?: string;
1167
+ rule?: string;
1168
+ frequency?: number;
1169
+ };
1170
+ };
1171
+ /** What a new member sees on joining, applied after the channels exist. */
1172
+ welcome?: NotificationsWelcomeLayout;
1173
+ /** The questions a new member answers, applied after the channels and roles exist. */
1174
+ onboarding?: NotificationsOnboardingLayout;
1175
+ /**
1176
+ * Messages the provider posts and pins, applied after the channels exist. One that already says exactly this
1177
+ * (posted by the provider and still pinned) is left alone; one that says something else is replaced.
1178
+ */
1179
+ pinned?: NotificationsPinnedLayout[];
1180
+ /** Settings of the server itself, applied after its channels exist. */
1181
+ server?: NotificationsServerLayout;
1182
+ categories?: Array<{
1183
+ name: string;
1184
+ access?: NotificationsAccess;
1185
+ channels?: NotificationsChannelLayout[];
1186
+ }>;
1187
+ roles?: Array<{
1188
+ name: string;
1189
+ mentionable?: boolean;
1190
+ /** `#rrggbb`. Omit to leave the colour alone. */
1191
+ color?: string;
1192
+ /** Show the role's members as their own group in the member list. */
1193
+ hoist?: boolean;
1194
+ /**
1195
+ * The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
1196
+ * `SendMessages`, …). The list is exact: a permission not named is not granted.
1197
+ */
1198
+ permissions?: string[];
1199
+ /**
1200
+ * Keep this role's members equal to a team of the `source` provider (for GitHub, a team slug in
1201
+ * the org): `holocron notifications sync-roles` gives the role to every team member who has linked
1202
+ * their account, and takes it from linked people who have left the team.
1203
+ */
1204
+ team?: string;
1205
+ /**
1206
+ * Store the role's id in this secret, so a workflow can ping the role
1207
+ * without anyone copying the id by hand. The id is not sensitive; a secret
1208
+ * is used because the same token that writes the webhook secrets can write
1209
+ * it, with no extra permission.
1210
+ */
1211
+ secret?: string;
1212
+ }>;
1213
+ }
1214
+ /**
1215
+ * What a provider found on the server, limited to what a {@link NotificationsLayout}
1216
+ * asks about. Read-only: this is what `holocron doctor notifications` compares the
1217
+ * layout against.
1218
+ */
1219
+ interface ServerInspection {
1220
+ /** The bot's application as the provider has it, in the layout's terms, when the layout declares `application`. */
1221
+ application?: NotificationsApplicationLayout;
1222
+ /** Set when reading the application failed; `application` is then absent and means nothing. */
1223
+ applicationError?: string;
1224
+ /** What everyone may do, by permission name, when the layout declares `everyone`. */
1225
+ everyone?: {
1226
+ permissions: string[];
1227
+ };
1228
+ /** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
1229
+ everyoneError?: string;
1230
+ /** The welcome screen as the server has it, in the layout's terms, when the layout declares `welcome`. */
1231
+ welcome?: NotificationsWelcomeLayout;
1232
+ /** Set when reading the welcome screen failed; `welcome` is then absent and means nothing. */
1233
+ welcomeError?: string;
1234
+ /** Whether each pinned message the layout declares is in place, in the layout's order. */
1235
+ pinned?: Array<{
1236
+ channel: string;
1237
+ state: "ok" | "missing" | "different";
1238
+ }>;
1239
+ /** Set when reading the pinned messages failed; `pinned` is then absent and means nothing. */
1240
+ pinnedError?: string;
1241
+ /** Onboarding as the server has it, in the layout's terms, when the layout declares `onboarding`. */
1242
+ onboarding?: NotificationsOnboardingLayout;
1243
+ /** Set when reading onboarding failed; `onboarding` is then absent and means nothing. */
1244
+ onboardingError?: string;
1245
+ /** The server's own settings, in the layout's terms, when the layout declares `server`. */
1246
+ server?: NotificationsServerLayout;
1247
+ /** Set when reading the server's settings failed; `server` is then absent and means nothing. */
1248
+ serverError?: string;
1249
+ categories: string[];
1250
+ /**
1251
+ * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
1252
+ * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
1253
+ */
1254
+ categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
1255
+ channels: Array<{
1256
+ name: string;
1257
+ /** The category it sits under, if any. */
1258
+ category?: string;
1259
+ topic?: string;
1260
+ /** Names of the webhooks on the channel. Only filled in for channels the layout gives a webhook. */
1261
+ webhooks: string[];
1262
+ /** Which of those webhooks have a picture of their own. */
1263
+ webhookAvatars?: string[];
1264
+ /** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
1265
+ webhooksError?: string;
1266
+ /** Who can see and post; `"custom"` as for `categoryAccess`. */
1267
+ access?: Required<NotificationsAccess> | "custom";
1268
+ }>;
1269
+ roles: Array<{
1270
+ name: string;
1271
+ id: string;
1272
+ mentionable: boolean;
1273
+ /** `#rrggbb`, or absent for the default colour. */
1274
+ color?: string;
1275
+ hoist?: boolean;
1276
+ permissions?: string[];
1277
+ }>;
1278
+ /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
1279
+ rolesError?: string;
1280
+ }
1281
+ /** Who a member turned out to be after signing in with the provider. */
1282
+ interface NotificationsSignedIn {
1283
+ /** Their id on the provider; for Discord, the user id. */
1284
+ member: string;
1285
+ name?: string;
1286
+ /** The GitHub account the provider has verified they own; absent when they have none linked. */
1287
+ github?: {
1288
+ id: string;
1289
+ login: string;
1290
+ };
1291
+ }
1292
+ /** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
1293
+ interface NotificationsSignIn {
1294
+ authorizeUrl(input: {
1295
+ redirectUri: string;
1296
+ state: string;
1297
+ }): Promise<string>;
1298
+ /** Trades the one-use `code` for who they are, and discards the token it was given. */
1299
+ complete(input: {
1300
+ redirectUri: string;
1301
+ code: string;
1302
+ }): Promise<NotificationsSignedIn>;
1303
+ }
1304
+ /** A member of the server, as {@link Notifications.roleMembers} reports it. */
1305
+ /** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
1306
+ interface NotificationsDelivery {
1307
+ posted: boolean;
1308
+ readBack: boolean;
1309
+ removed: boolean;
1310
+ /** Set when the message was deliberately left in the channel (`keep`), so `removed` is false on purpose. */
1311
+ kept?: boolean;
1312
+ problems: string[];
1313
+ }
1314
+ interface NotificationsMember {
1315
+ /** The provider's id for them; for Discord, the user id. */
1316
+ id: string;
1317
+ /** A display name for reports; absent when the provider does not give one. */
1318
+ name?: string;
1319
+ }
1320
+ interface Notifications extends ProviderIdentity {
1321
+ readonly key: "notifications";
1322
+ /**
1323
+ * Send a message. `channel` is provider-specific (Slack channel id,
1324
+ * Discord webhook url-name, etc.); adapters resolve from config.
1325
+ */
1326
+ send(channel: string, message: string): Promise<void>;
1327
+ /**
1328
+ * The server layout the owner declared for this provider, if any. Read by
1329
+ * `holocron notifications setup`; the provider just carries it from its options.
1330
+ */
1331
+ readonly layout?: NotificationsLayout;
1332
+ /**
1333
+ * Provisioning. All optional, all idempotent (look up by name, create only
1334
+ * what is missing), and all need provider credentials beyond the posting
1335
+ * URL — so a provider that only posts simply omits them.
1336
+ */
1337
+ ensureCategory?(name: string, opts?: {
1338
+ access?: NotificationsAccess;
1339
+ }): Promise<EnsuredResource>;
1340
+ ensureChannel?(input: {
1341
+ name: string;
1342
+ category?: string;
1343
+ topic?: string;
1344
+ access?: NotificationsAccess;
1345
+ }): Promise<EnsuredResource>;
1346
+ ensureWebhook?(input: {
1347
+ channel: string;
1348
+ name: string;
1349
+ category?: string;
1350
+ /** An image as a `data:` URI, set when the webhook has none. */
1351
+ avatar?: string;
1352
+ }): Promise<EnsureWebhookResult>;
1353
+ /**
1354
+ * Proves a channel's webhook delivers: posts `text` through it, reads the post back from the channel and
1355
+ * removes it again, unless `keep` is true, in which case the post is left in the channel (and the result
1356
+ * has `kept` instead of `removed`). Never throws for a failed step; the result says which one failed.
1357
+ * Posts a visible message, so callers choose the channel with care.
1358
+ */
1359
+ checkDelivery?(input: {
1360
+ channel: string;
1361
+ name: string;
1362
+ category?: string;
1363
+ /** The message. The provider may format it (Discord renders markdown) and replaces `{channel}` with its link to the channel. */
1364
+ text: string;
1365
+ /** Leave the message in the channel instead of removing it, so a person can see it. */
1366
+ keep?: boolean;
1367
+ }): Promise<NotificationsDelivery>;
1368
+ /**
1369
+ * Creates the server the layout describes, empty, owned by the provider's own bot, and makes it the server
1370
+ * every other call in this run works on. Refuses when the config already names a server unless `force`.
1371
+ */
1372
+ createServer?(input: {
1373
+ name: string;
1374
+ force?: boolean;
1375
+ }): Promise<{
1376
+ id: string;
1377
+ name: string;
1378
+ }>;
1379
+ /** A single-use link, valid for a day, that lets one person join the server through the named channel. */
1380
+ inviteLink?(channel: string): Promise<string>;
1381
+ /** Whether a person is in the server. */
1382
+ hasMember?(memberId: string): Promise<boolean>;
1383
+ /** Hands the server to a member who has joined, so the bot no longer owns it. */
1384
+ transferServer?(memberId: string): Promise<void>;
1385
+ /** Who owns the server, and whether that is the provider's own bot. */
1386
+ serverOwner?(): Promise<{
1387
+ id: string;
1388
+ isBot: boolean;
1389
+ name?: string;
1390
+ }>;
1391
+ /**
1392
+ * Who holds a role, by the provider's member id. Needs whatever permission the provider asks for to list
1393
+ * members (for Discord, the privileged Server Members Intent). Throws if the role does not exist.
1394
+ */
1395
+ roleMembers?(roleName: string): Promise<NotificationsMember[]>;
1396
+ /** Give a member the role; one who has it already is left alone. */
1397
+ addRoleMember?(roleName: string, memberId: string): Promise<void>;
1398
+ /** Take the role from a member; one who lacks it is left alone. */
1399
+ removeRoleMember?(roleName: string, memberId: string): Promise<void>;
1400
+ /** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
1401
+ signIn?(): NotificationsSignIn;
1402
+ ensureRole?(input: {
1403
+ name: string;
1404
+ mentionable?: boolean;
1405
+ color?: string;
1406
+ hoist?: boolean;
1407
+ permissions?: string[];
1408
+ }): Promise<EnsuredResource>;
1409
+ /**
1410
+ * Bring the server's own settings in line with the layout, changing only what differs. Returns the
1411
+ * names of what it changed, empty when the server already matched.
1412
+ */
1413
+ ensureServer?(settings: NotificationsServerLayout): Promise<{
1414
+ updated: string[];
1415
+ }>;
1416
+ /** Bring the welcome screen in line with the layout, changing only what differs. Returns what it changed. */
1417
+ ensureWelcome?(welcome: NotificationsWelcomeLayout): Promise<{
1418
+ updated: string[];
1419
+ }>;
1420
+ /** Post and pin the layout's messages, replacing any that differ. Returns the channels it changed. */
1421
+ ensurePinned?(pinned: NotificationsPinnedLayout[]): Promise<{
1422
+ updated: string[];
1423
+ }>;
1424
+ /** Whether the bot holds the permission right now (the owner holds every one). Used to prove an elevation was taken back. */
1425
+ holdsPermission?(permission: string): Promise<boolean>;
1426
+ /** Bring onboarding in line with the layout, changing only what differs. Returns what it changed. */
1427
+ ensureOnboarding?(onboarding: NotificationsOnboardingLayout): Promise<{
1428
+ updated: string[];
1429
+ }>;
1430
+ /** Bring the bot's application settings in line with the layout, changing only what differs. Returns what it changed. */
1431
+ ensureApplication?(application: NotificationsApplicationLayout): Promise<{
1432
+ updated: string[];
1433
+ todo?: string[];
1434
+ }>;
1435
+ /** Grant or take away the named permissions from everyone, changing only what differs. Returns what it changed. */
1436
+ ensureEveryone?(everyone: NotificationsEveryoneLayout): Promise<{
1437
+ updated: string[];
1438
+ }>;
1439
+ /**
1440
+ * Before anything is created, prove the credentials can do the parts of the layout that need
1441
+ * more than the rest (for Discord, change the server's settings). Throws with the reason and how
1442
+ * to fix it, so `setup` stops before it leaves a half-applied layout. Not called on a dry run.
1443
+ */
1444
+ preflight?(layout: NotificationsLayout): Promise<void>;
1445
+ /**
1446
+ * Check the provider-specific parts of the layout (colours, permission names, …) without
1447
+ * touching the server, so `setup` can refuse a bad layout before it creates anything.
1448
+ * Returns the first problem, or `undefined` when the layout is fine.
1449
+ */
1450
+ validateLayout?(layout: NotificationsLayout): string | undefined;
1451
+ /**
1452
+ * Smoke check for `holocron doctor`: prove the provisioning credentials work
1453
+ * and name what they reach. Returns `null` when there is nothing to check (a
1454
+ * config that only posts has no provisioning credentials), which doctor shows
1455
+ * as "loaded" rather than as a failure. Throws when it is configured to
1456
+ * provision but cannot (missing token, no access).
1457
+ */
1458
+ whoami?(): Promise<{
1459
+ target: string;
1460
+ } | null>;
1461
+ /**
1462
+ * Read what exists on the server, for the parts the layout cares about, without
1463
+ * changing anything. Backs `holocron doctor notifications`.
1464
+ */
1465
+ inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
1466
+ }
1467
+ interface Analytics extends ProviderIdentity {
1468
+ readonly key: "analytics";
1469
+ /** Returns the env var names the app reads at runtime for this provider. */
1470
+ describe(): Promise<{
1471
+ provider: string;
1472
+ envKeys: string[];
1473
+ }>;
1474
+ whoami?(): Promise<{
1475
+ org: string;
1476
+ }>;
1477
+ ensureProject?(name: string): Promise<{
1478
+ token: string;
1479
+ alreadyExists: boolean;
1480
+ }>;
1481
+ }
1482
+ interface WikiProvisionOpts {
1483
+ /** Project display name used in the wiki title (e.g. "Holocron"). */
1484
+ name?: string;
1485
+ }
1486
+ /**
1487
+ * Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
1488
+ * Used by `setup` to deploy a Worker that forwards traffic to the wiki
1489
+ * provider's ingress with the required headers injected.
1490
+ */
1491
+ interface WikiProxyConfig {
1492
+ /** Proxy target URL (e.g. "https://app.buildwithfern.com"). */
1493
+ target: string;
1494
+ /** Headers injected on every proxied request. */
1495
+ headers: Record<string, string>;
1496
+ }
1497
+ /**
1498
+ * Engineering wiki provider.
1499
+ *
1500
+ * A swappable provider for publishing the `docs/decisions/` and
1501
+ * `docs/engineering/` surfaces as a browsable, access-controlled site.
1502
+ * Local-only providers (fern, mintlify) write config files; remote
1503
+ * providers (github) make API calls.
1504
+ */
1505
+ interface Wiki extends ProviderIdentity {
1506
+ readonly key: "wiki";
1507
+ /** Provision the wiki — write config files or call the provider API. */
1508
+ provision(opts?: WikiProvisionOpts): Promise<string>;
1509
+ /**
1510
+ * DNS record needed for the custom domain, when one is configured.
1511
+ * Returns null when no custom domain is set.
1512
+ * Called by `setup` to provision the CNAME via the `dns` capability.
1513
+ */
1514
+ dnsRecord?(): DnsRecordRequest | null;
1515
+ /**
1516
+ * Reverse-proxy config when the wiki provider requires a Worker-level
1517
+ * proxy in addition to the CNAME. Returns null when no proxy is needed.
1518
+ * Called by `setup` to deploy the proxy via the `workers` capability.
1519
+ */
1520
+ proxyConfig?(): WikiProxyConfig | null;
1521
+ /**
1522
+ * Confirms a provider token resolves. Unlike `dns`/`workers`/`monitoring`'s
1523
+ * `whoami()`, this is NOT a live reachability check — Fern (the only
1524
+ * current `wiki` provider) exposes no lightweight endpoint to verify a
1525
+ * token actually works; the only token-consuming operation is a full
1526
+ * `fern generate` (holocron#1079). `ok: true` means "a token was found",
1527
+ * not "the token works".
1528
+ */
1529
+ whoami?(): Promise<{
1530
+ ok: boolean;
1531
+ }>;
1532
+ }
1533
+ /** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
1534
+ interface DeployScriptConfig {
1535
+ /** The full Worker script source — a single ES module (`export default { fetch(...) {...} }`). */
1536
+ code: string;
1537
+ /**
1538
+ * Secret bindings — `env.<name>` in the deployed Worker. Values are
1539
+ * write-only; the provider never echoes them back, here or anywhere else.
1540
+ */
1541
+ secrets?: Record<string, string>;
1542
+ /**
1543
+ * Route pattern(s) this Worker should serve (e.g.
1544
+ * `"sentinel.theholocron.dev/*"`). Omit for a Worker reached only via
1545
+ * its `*.workers.dev` URL.
1546
+ */
1547
+ routes?: string[];
1548
+ }
1549
+ interface DeployScriptResult {
1550
+ /** The deployed script's name at the provider. */
1551
+ scriptName: string;
1552
+ }
1553
+ /**
1554
+ * Edge Worker management capability.
1555
+ *
1556
+ * Deploys and manages Worker scripts. `upsertProxy` is the existing,
1557
+ * narrower case `setup` uses to wire wiki custom-domain reverse-proxies;
1558
+ * `deployScript` is the general case — any Worker, any code, its own
1559
+ * secrets — for a consumer that isn't a reverse-proxy (a webhook
1560
+ * receiver, for instance).
1561
+ */
1562
+ interface Workers extends ProviderIdentity {
1563
+ readonly key: "workers";
1564
+ /**
1565
+ * Deploy (or update) a reverse-proxy Worker for `hostname`.
1566
+ * Forwards all `hostname/*` requests to `config.target`, injecting
1567
+ * `config.headers` on each request.
1568
+ */
1569
+ upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
1570
+ /** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
1571
+ deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
1572
+ /**
1573
+ * Set one secret binding on a script that is already deployed, leaving its code and every other binding alone.
1574
+ * The value is write-only. `holocron secrets sync --worker` uses it to fan a vault out to a Worker.
1575
+ */
1576
+ setSecret?(script: string, name: string, value: string): Promise<void>;
1577
+ /** The names (never the values) of the secrets bound to a deployed script. `holocron probe` uses it to see what a Worker has. */
1578
+ secretNames?(script: string): Promise<string[]>;
1579
+ /**
1580
+ * A `holocron doctor` smoke check — every other method either mutates or
1581
+ * needs a specific script/zone doctor has no way to supply up front.
1582
+ * Reports how many Worker scripts the token can see.
1583
+ */
1584
+ whoami?(): Promise<{
1585
+ ok: boolean;
1586
+ scripts: number;
1587
+ }>;
1588
+ }
1589
+ interface CapabilityImpls {
1590
+ source: Source;
1591
+ ci: Ci;
1592
+ secrets: Secrets;
1593
+ environments: Environments;
1594
+ issues: Issues;
1595
+ deployment: Deployment;
1596
+ storage: Storage;
1597
+ auth: Auth;
1598
+ vault: Vault;
1599
+ dns: Dns;
1600
+ tooling: Tooling;
1601
+ notifications: Notifications;
1602
+ analytics: Analytics;
1603
+ errors: Errors;
1604
+ logs: Logs;
1605
+ monitoring: Monitoring;
1606
+ wiki: Wiki;
1607
+ workers: Workers;
1608
+ }
1609
+ type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
1610
+ /** Resolved runtime shape: single → one impl; many → array. */
1611
+ type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
1612
+ declare const CARDINALITY: {
1613
+ readonly source: "single";
1614
+ readonly ci: "single";
1615
+ readonly secrets: "single";
1616
+ readonly environments: "single";
1617
+ readonly issues: "single";
1618
+ readonly deployment: "single";
1619
+ readonly storage: "single";
1620
+ readonly auth: "single";
1621
+ readonly vault: "single";
1622
+ readonly dns: "single";
1623
+ readonly tooling: "many";
1624
+ readonly notifications: "many";
1625
+ readonly analytics: "many";
1626
+ readonly errors: "single";
1627
+ readonly logs: "single";
1628
+ readonly monitoring: "single";
1629
+ readonly wiki: "single";
1630
+ readonly workers: "single";
1631
+ };
1632
+ /**
1633
+ * No capabilities are strictly required — repos without secrets (e.g. org
1634
+ * community health repos) legitimately omit vault. Plugins validate their
1635
+ * own requirements at call time.
1636
+ */
1637
+ declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
1638
+ /**
1639
+ * A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
1640
+ * needs to give it for one run and take it away again, so `setup` can walk them through it.
1641
+ */
1642
+ declare class ElevationRequiredError extends Error {
1643
+ readonly elevation: {
1644
+ /** The permission, in the provider's own name for it. */
1645
+ permission: string;
1646
+ /** Where to approve giving it; absent when the provider could not build one. */
1647
+ grantUrl?: string;
1648
+ /** Where to approve taking it away again; absent when the provider could not build one. */
1649
+ revokeUrl?: string;
1650
+ /** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
1651
+ label?: string;
1652
+ /** The permission is meant to stay once given: there is nothing to take away afterwards. */
1653
+ keep?: boolean;
1654
+ /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
1655
+ applied?: string[];
1656
+ };
1657
+ name: string;
1658
+ constructor(message: string, elevation: {
1659
+ /** The permission, in the provider's own name for it. */
1660
+ permission: string;
1661
+ /** Where to approve giving it; absent when the provider could not build one. */
1662
+ grantUrl?: string;
1663
+ /** Where to approve taking it away again; absent when the provider could not build one. */
1664
+ revokeUrl?: string;
1665
+ /** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
1666
+ label?: string;
1667
+ /** The permission is meant to stay once given: there is nothing to take away afterwards. */
1668
+ keep?: boolean;
1669
+ /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
1670
+ applied?: string[];
1671
+ }, options?: ErrorOptions);
1672
+ }
1673
+ /**
1674
+ * A provider cannot do a read because it has no token for it. A check that meets this skips with the message instead
1675
+ * of failing: the token is missing, not wrong.
1676
+ */
1677
+ declare class MissingTokenError extends Error {
1678
+ /** Lets a caller tell this error from any other by name, across package copies. */
1679
+ name: string;
1680
+ }
1681
+ declare class WebhookVerificationError extends Error {
1682
+ name: string;
1683
+ }
1684
+ declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
1685
+ export { LifecycleSlot as $, WikiProvisionOpts as $t, DeploymentProject as A, RepoRef as At, EnsureRelayResult as B, SourceTeamMember as Bt, ConnectionStringOptions as C, NotificationsSignIn as Ct, DeployScriptConfig as D, ParseWebhookInput as Dt, DeployFunctionResult as E, PagesConfig as Et, Dns as F, Secrets as Ft, EnvironmentReviewer as G, TeamPermission as Gt, EnsureWebhookResult as H, Storage as Ht, DnsRecord as I, ServerInspection as It, Issue as J, TrackerDoctorReport as Jt, Environments as K, Tooling as Kt, DnsRecordRequest as L, Source as Lt, DeploymentRecord as M, ResolvedCapability as Mt, DeploymentTarget as N, Ruleset as Nt, DeployScriptResult as O, ProviderIdentity as Ot, DeploymentTrigger as P, SecretScope as Pt, LifecycleResult as Q, Wiki as Qt, DnsRecordType as R, SourceBranch as Rt, CiRunStatus as S, NotificationsServerLayout as St, DeployFunctionConfig as T, NotificationsWelcomeLayout as Tt, EnsuredResource as U, StorageBranch as Ut, EnsureResult as V, StatusCategory as Vt, Environment as W, TeamEntry as Wt, Issues as X, Vault as Xt, IssueSearchFilter as Y, TrackerUser as Yt, LabelDef as Z, WebhookDashboardInfo as Zt, Cardinality as _, NotificationsLayout as _t, REQUIRED_CAPABILITIES as a, MonitoringAssertionComparison as at, CiRun as b, NotificationsOnboardingLayout as bt, Analytics as c, MonitoringCheckInput as ct, AuthEvent as d, Notifications as dt, WikiProxyConfig as en, Logs as et, AuthEventType as f, NotificationsAccess as ft, CapabilityKey as g, NotificationsEveryoneLayout as gt, CapabilityImpls as h, NotificationsDelivery as ht, ProviderApiError as i, MonitoringAssertion as it, DeploymentProjectSettings as j, RepoSettings as jt, Deployment as k, PullRequest as kt, Auth as l, MonitoringHttpMethod as lt, AuthUser as m, NotificationsChannelLayout as mt, ElevationRequiredError as n, MonitoringAlertChannelInput as nt, WebhookVerificationError as o, MonitoringAssertionSource as ot, AuthIdentity as p, NotificationsApplicationLayout as pt, Errors as q, ToolingDoctorReport as qt, MissingTokenError as r, MonitoringAlertChannelResult as rt, isMulti as s, MonitoringCheck as st, CARDINALITY as t, Workers as tn, Monitoring as tt, AuthDescription as u, NormalizedAuthUser as ut, CardinalityFor as v, NotificationsLinksLayout as vt, CreateAuthUserInput as w, NotificationsSignedIn as wt, CiRunFilter as x, NotificationsPinnedLayout as xt, Ci as y, NotificationsMember as yt, EnsureRelayInput as z, SourceFile as zt };