@theholocron/cli 5.0.0-alpha.278 → 5.0.0-alpha.279

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.
@@ -12,41 +12,70 @@ import { ProviderApiError } from "@theholocron/http-client";
12
12
  * (issue: #74).
13
13
  */
14
14
  type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "monitoring" | "wiki" | "workers";
15
+ /** How many providers a capability resolves to: one (`"single"`) or several at once (`"many"`). */
15
16
  type Cardinality = "single" | "many";
17
+ /** What every capability implementation carries: which capability it is and which provider backs it. */
16
18
  interface ProviderIdentity {
19
+ /** The capability this implementation provides. */
17
20
  readonly key: CapabilityKey;
21
+ /** The provider's name, e.g. `github` or `vercel`. */
18
22
  readonly providerName: string;
19
23
  }
24
+ /** A repository ruleset as {@link Source.listRulesets} reports it. */
20
25
  interface Ruleset {
26
+ /** The provider's numeric id for the ruleset. */
21
27
  id: number;
28
+ /** The ruleset's name. */
22
29
  name: string;
30
+ /** Whether the ruleset is enforced (`active`), only logged (`evaluate`) or off (`disabled`). */
23
31
  enforcement: "active" | "evaluate" | "disabled";
32
+ /** What the ruleset applies to, e.g. `branch`; `undefined` when the provider does not say. */
24
33
  target?: string;
25
34
  }
35
+ /** The repository settings {@link Source.updateRepoSettings} can change; a field left out is left alone. */
26
36
  interface RepoSettings {
37
+ /** Allow merging a pull request by squashing its commits. */
27
38
  allow_squash_merge?: boolean;
39
+ /** Allow merging a pull request with a merge commit. */
28
40
  allow_merge_commit?: boolean;
41
+ /** Allow merging a pull request by rebasing its commits. */
29
42
  allow_rebase_merge?: boolean;
43
+ /** Allow a pull request to be set to merge itself once its checks pass. */
30
44
  allow_auto_merge?: boolean;
31
45
  /** Always suggest updating PR branches when the base branch has new commits. */
32
46
  allow_update_branch?: boolean;
47
+ /** Delete a pull request's head branch once it is merged. */
33
48
  delete_branch_on_merge?: boolean;
49
+ /** The branch a fresh clone checks out. */
34
50
  default_branch?: string;
51
+ /** Whether the repository has an issue tracker. */
35
52
  has_issues?: boolean;
53
+ /** Whether the repository has discussions. */
36
54
  has_discussions?: boolean;
55
+ /** Whether the repository has project boards. */
37
56
  has_projects?: boolean;
57
+ /** Whether the repository has a wiki. */
38
58
  has_wiki?: boolean;
39
59
  }
60
+ /** The repository a {@link Source} provider is scoped to. */
40
61
  interface RepoRef {
62
+ /** The account or organization that owns the repository. */
41
63
  owner: string;
64
+ /** The repository's name, without the owner. */
42
65
  name: string;
66
+ /** The branch a fresh clone checks out. */
43
67
  defaultBranch: string;
44
68
  }
69
+ /** A repository label as the canonical set passed to {@link Source.syncLabels} defines it. */
45
70
  interface LabelDef {
71
+ /** The label's name. */
46
72
  readonly name: string;
73
+ /** The label's colour as a hex string. */
47
74
  readonly color: string;
75
+ /** What the label is for; an empty string when it has none. */
48
76
  readonly description: string;
49
77
  }
78
+ /** The access level a team can hold on a repository, from least (`pull`) to most (`admin`). */
50
79
  type TeamPermission = "pull" | "triage" | "push" | "maintain" | "admin";
51
80
  /** Shorthand `"slug"` defaults to `push` permission. */
52
81
  type TeamEntry = string | {
@@ -101,29 +130,41 @@ interface SourceTeamMember {
101
130
  }
102
131
  /** A file read by {@link Source.readFile}. */
103
132
  interface SourceFile {
133
+ /** The file's text. */
104
134
  content: string;
105
135
  /** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
106
136
  version: string;
107
137
  }
138
+ /** Source hosting: the repository, its rulesets, settings, security features, workflow files and pull requests. */
108
139
  interface Source extends ProviderIdentity {
140
+ /** Identifies this provider as the `source` capability. */
109
141
  readonly key: "source";
110
142
  /** Auth sanity-check. Throws ProviderApiError on auth failure. */
111
143
  whoami(): Promise<{
112
144
  login: string;
113
145
  }>;
146
+ /** The repository this provider is scoped to: its owner, name and default branch. */
114
147
  getRepo(): Promise<RepoRef>;
148
+ /** Every ruleset on the repository. */
115
149
  listRulesets(): Promise<Ruleset[]>;
150
+ /** Create a ruleset from the provider's own payload shape and return it. */
116
151
  createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
152
+ /** Replace the ruleset with the given id using the provider's own payload shape. */
117
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. */
118
155
  updateRepoSettings(settings: RepoSettings): Promise<void>;
119
156
  /**
120
157
  * Classic branch protection — fallback for private repos on free plans
121
158
  * where the Rulesets API (requires Team+) returns 403.
122
159
  */
123
160
  protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
161
+ /** Turn on vulnerability alerts (dependency advisories) for the repository. */
124
162
  enableVulnerabilityAlerts(): Promise<void>;
163
+ /** Turn on automated security updates, which open pull requests for vulnerable dependencies. */
125
164
  enableAutomatedSecurityFixes(): Promise<void>;
165
+ /** Turn on secret scanning, and push protection with it. */
126
166
  enableSecretScanning(): Promise<void>;
167
+ /** Turn on private vulnerability reporting, so people can report a vulnerability to the maintainers privately. */
127
168
  enablePrivateVulnerabilityReporting(): Promise<void>;
128
169
  /**
129
170
  * Enables the dependency graph and automatic dependency snapshot
@@ -145,9 +186,13 @@ interface Source extends ProviderIdentity {
145
186
  * while default setup is active.
146
187
  */
147
188
  disableDefaultCodeScanning(): Promise<void>;
189
+ /** The file names in the workflow directory, sorted; empty when the directory does not exist. */
148
190
  listWorkflowFiles(): Promise<string[]>;
191
+ /** The contents of one workflow file, or `null` when it does not exist. */
149
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. */
150
194
  writeWorkflowFile(name: string, contents: string): Promise<void>;
195
+ /** Delete one workflow file; one that is already gone is not an error. */
151
196
  removeWorkflowFile(name: string): Promise<void>;
152
197
  /**
153
198
  * Write an arbitrary file relative to the repo root. Used for
@@ -318,6 +363,7 @@ interface Source extends ProviderIdentity {
318
363
  */
319
364
  configurePages?(config: PagesConfig, token: string): Promise<void>;
320
365
  }
366
+ /** How GitHub Pages is set up for a repository, as {@link Source.configurePages} takes it. */
321
367
  interface PagesConfig {
322
368
  /** GitHub Pages build source. */
323
369
  build: "workflow" | "branch";
@@ -337,8 +383,11 @@ interface SourceBranch {
337
383
  /** The commit the branch points at. */
338
384
  sha: string;
339
385
  }
386
+ /** A pull request as {@link Source.getPullRequest} and {@link Source.listPullRequests} report it. */
340
387
  interface PullRequest {
388
+ /** The pull request's number within the repository. */
341
389
  number: number;
390
+ /** The pull request's title. */
342
391
  title: string;
343
392
  /** "open" | "closed" — GitHub marks merged PRs as "closed". */
344
393
  state: "open" | "closed";
@@ -348,29 +397,49 @@ interface PullRequest {
348
397
  branch: string;
349
398
  /** The commit the head branch pointed at when the PR was last read. */
350
399
  headSha?: string;
400
+ /** The address of the pull request's page. */
351
401
  url: string;
352
402
  }
403
+ /** Where a workflow run is in its life; a finished run carries its outcome (`success`, `failure`, ...). */
353
404
  type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
405
+ /** One run of a CI workflow. */
354
406
  interface CiRun {
407
+ /** The provider's id for the run. */
355
408
  id: string | number;
409
+ /** The workflow's name, falling back to the run's display title. */
356
410
  workflowName: string;
411
+ /** The branch the run was triggered on. */
357
412
  branch: string;
413
+ /** The commit the run was for. */
358
414
  sha: string;
415
+ /** Where the run is, or how it ended once finished. */
359
416
  status: CiRunStatus;
417
+ /** The address of the run's page. */
360
418
  url: string;
419
+ /** When the run started, as an ISO timestamp. */
361
420
  startedAt: string;
421
+ /** When the run finished, as an ISO timestamp; `undefined` while it is still going. */
362
422
  completedAt?: string;
363
423
  }
424
+ /** What {@link Ci.listRuns} narrows its result by; a field left out does not filter. */
364
425
  interface CiRunFilter {
426
+ /** Only runs on this branch. */
365
427
  branch?: string;
428
+ /** Only runs in this state. */
366
429
  status?: CiRunStatus;
430
+ /** The most runs to return. */
367
431
  limit?: number;
368
432
  }
433
+ /** CI history: lists workflow runs and reads one back, with no way to start or change one. */
369
434
  interface Ci extends ProviderIdentity {
435
+ /** Identifies this provider as the `ci` capability. */
370
436
  readonly key: "ci";
437
+ /** Recent workflow runs, narrowed by `filter` when given. */
371
438
  listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
439
+ /** One workflow run by its id. */
372
440
  getRun(id: string | number): Promise<CiRun>;
373
441
  }
442
+ /** Where a secret lives: the repository, one of its environments, or the organization. */
374
443
  type SecretScope = {
375
444
  kind: "repo";
376
445
  } | {
@@ -380,51 +449,81 @@ type SecretScope = {
380
449
  kind: "organization";
381
450
  name: string;
382
451
  };
452
+ /** A destination for secrets (CI or platform secrets) that `holocron secrets sync` writes into. */
383
453
  interface Secrets extends ProviderIdentity {
454
+ /** Identifies this provider as the `secrets` capability. */
384
455
  readonly key: "secrets";
385
456
  /** List secret NAMES (not values) at the given scope. */
386
457
  listSecrets(scope: SecretScope): Promise<string[]>;
387
458
  /** Idempotent upsert. Adapter handles encryption. */
388
459
  setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
460
+ /** Remove a secret at the given scope. */
389
461
  deleteSecret(scope: SecretScope, name: string): Promise<void>;
390
462
  }
463
+ /** Someone whose approval a deployment to an environment needs. */
391
464
  interface EnvironmentReviewer {
465
+ /** Whether the reviewer is a person (`User`) or a team (`Team`). */
392
466
  type: "User" | "Team";
393
467
  /** Numeric id — GitHub's reviewer API silently ignores login strings. */
394
468
  id: number;
395
469
  }
470
+ /** A named deployment environment and the protection rules on it. */
396
471
  interface Environment {
472
+ /** The environment's name, e.g. `production`. */
397
473
  name: string;
474
+ /** Who must approve a deployment to the environment. */
398
475
  reviewers?: EnvironmentReviewer[];
476
+ /** Minutes a deployment waits before it proceeds. */
399
477
  waitTimer?: number;
478
+ /** Whether the person who started a deployment is barred from approving it. */
400
479
  preventSelfReview?: boolean;
401
480
  }
481
+ /** Named deployment environments and their protection rules. */
402
482
  interface Environments extends ProviderIdentity {
483
+ /** Identifies this provider as the `environments` capability. */
403
484
  readonly key: "environments";
485
+ /** Every environment on the repository. */
404
486
  listEnvironments(): Promise<Environment[]>;
487
+ /** Create the environment, or bring an existing one of that name in line with `env`. */
405
488
  upsertEnvironment(env: Environment): Promise<void>;
489
+ /** Delete the environment with the given name. */
406
490
  deleteEnvironment(name: string): Promise<void>;
407
491
  }
492
+ /** A step in an issue's life that {@link Issues.transition} can move it to. */
408
493
  type LifecycleSlot = "inProgress" | "inReview" | "done";
494
+ /** The tracker-neutral group a provider's own status names fall into. */
409
495
  type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
496
+ /** A person in the issue tracker. */
410
497
  interface TrackerUser {
498
+ /** The tracker's id for the person. */
411
499
  id: string;
500
+ /** The name shown for the person. */
412
501
  displayName: string;
502
+ /** Their email address, when the tracker shares it. */
413
503
  emailAddress?: string;
414
504
  }
505
+ /** An issue in the tracker, in a shape that does not depend on the provider. */
415
506
  interface Issue {
416
507
  /** Human-readable key — "#42" for GitHub, "RANDO-42" for Jira. */
417
508
  key: string;
418
509
  /** Internal opaque id. */
419
510
  id: string;
511
+ /** The issue's title. */
420
512
  summary: string;
513
+ /** The issue's description; `undefined` when the provider did not return one. */
421
514
  body?: string;
515
+ /** The provider's own status name. */
422
516
  status: string;
517
+ /** The group the status falls into. */
423
518
  statusCategory: StatusCategory;
519
+ /** Who the issue is assigned to; `null` when nobody. */
424
520
  assignee: TrackerUser | null;
521
+ /** When the issue last changed, as an ISO timestamp. */
425
522
  updated: string;
523
+ /** The address of the issue's page, when the provider gives one. */
426
524
  url?: string;
427
525
  }
526
+ /** What {@link Issues.search} narrows its result by; a field left out does not filter. */
428
527
  interface IssueSearchFilter {
429
528
  /** Restrict to issues assigned to a specific id, or 'currentUser'. */
430
529
  assignee?: string | "currentUser";
@@ -433,6 +532,7 @@ interface IssueSearchFilter {
433
532
  /** Max number of issues to return. Adapters apply a sensible default. */
434
533
  limit?: number;
435
534
  }
535
+ /** What {@link Issues.transition} did. */
436
536
  interface LifecycleResult {
437
537
  /** False when no API write happened (already at target state). */
438
538
  transitioned: boolean;
@@ -441,6 +541,7 @@ interface LifecycleResult {
441
541
  /** Adapter-specific note (e.g., "label set" / "closed (completed)"). */
442
542
  via?: string;
443
543
  }
544
+ /** What {@link Issues.doctor} found about the tracker connection, for `holocron doctor` to print. */
444
545
  interface TrackerDoctorReport {
445
546
  /** "Authenticated as ..." subject for the spinner. */
446
547
  authedAs: string;
@@ -463,12 +564,17 @@ interface TrackerDoctorReport {
463
564
  note: string;
464
565
  }>;
465
566
  }
567
+ /** An issue tracker: finds, reads, creates, moves and comments on issues. */
466
568
  interface Issues extends ProviderIdentity {
569
+ /** Identifies this provider as the `issues` capability. */
467
570
  readonly key: "issues";
468
571
  /** Currently-authenticated user. */
469
572
  getMyself(): Promise<TrackerUser>;
573
+ /** Issues matching `filter`. */
470
574
  search(filter: IssueSearchFilter): Promise<Issue[]>;
575
+ /** One issue by its human-readable key (e.g. `#42`). */
471
576
  get(key: string): Promise<Issue>;
577
+ /** Open a new issue and return its key. */
472
578
  create(input: {
473
579
  summary: string;
474
580
  body?: string;
@@ -480,7 +586,9 @@ interface Issues extends ProviderIdentity {
480
586
  }>;
481
587
  /** Idempotent — `transitioned: false` if the issue is already at the target. */
482
588
  transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
589
+ /** Add a comment to the issue. */
483
590
  comment(key: string, body: string): Promise<void>;
591
+ /** Check the tracker connection and how the lifecycle slots map onto the tracker's statuses. */
484
592
  doctor(): Promise<TrackerDoctorReport>;
485
593
  }
486
594
  /** Env-var scope on the deploy platform. */
@@ -490,28 +598,40 @@ type DeploymentTarget = "development" | "preview" | "production";
490
598
  * preview (no named environment).
491
599
  */
492
600
  type DeploymentTrigger = "production" | "staging";
601
+ /** A project on the deployment platform. */
493
602
  interface DeploymentProject {
603
+ /** The platform's id for the project. */
494
604
  id: string;
605
+ /** The project's name. */
495
606
  name: string;
607
+ /** The framework preset the project uses, when the platform reports one. */
496
608
  framework?: string;
497
609
  /** True when the project is linked to a Git provider. */
498
610
  gitLinked?: boolean;
611
+ /** The directory in the repository the project builds from; `null` or `undefined` for the repository root. */
499
612
  rootDirectory?: string | null;
500
613
  }
614
+ /** The project settings {@link Deployment.updateProjectSettings} can change; a field left out is left alone. */
501
615
  interface DeploymentProjectSettings {
616
+ /** Turn off preview deployments for the project. */
502
617
  previewDeploymentsDisabled?: boolean;
503
618
  /** Vercel-specific: whether the GitHub integration creates deployments
504
619
  * for every push (false → only on-demand triggers). */
505
620
  gitProviderCreateDeployments?: boolean;
506
621
  }
622
+ /** One deployment on the platform. */
507
623
  interface DeploymentRecord {
624
+ /** The platform's id for the deployment. */
508
625
  id: string;
626
+ /** The address the deployment is served at. */
509
627
  url: string;
510
628
  /** Branch this deployment was made from (null if not git-sourced). */
511
629
  branch: string | null;
512
630
  /** Named environment if one was targeted; undefined for branch previews. */
513
631
  target?: DeploymentTrigger;
632
+ /** Where the deployment is in its build. */
514
633
  status: "queued" | "building" | "ready" | "error" | "cancelled";
634
+ /** When the deployment was created, as an ISO timestamp. */
515
635
  createdAt?: string;
516
636
  /** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
517
637
  errorMessage?: string;
@@ -530,11 +650,16 @@ interface DeployFunctionConfig {
530
650
  */
531
651
  target?: DeploymentTrigger;
532
652
  }
653
+ /** What {@link Deployment.deployFunction} made. */
533
654
  interface DeployFunctionResult {
655
+ /** The platform's id for the new deployment. */
534
656
  deploymentId: string;
657
+ /** The address the deployment is served at. */
535
658
  url: string;
536
659
  }
660
+ /** A deployment platform: projects, environment variables and deployments. */
537
661
  interface Deployment extends ProviderIdentity {
662
+ /** Identifies this provider as the `deployment` capability. */
538
663
  readonly key: "deployment";
539
664
  /**
540
665
  * Custom domain declared in the deployment provider's configuration.
@@ -542,6 +667,7 @@ interface Deployment extends ProviderIdentity {
542
667
  * returned verification record to the `dns` capability.
543
668
  */
544
669
  readonly domain?: string;
670
+ /** Every project the account can see. */
545
671
  listProjects(): Promise<DeploymentProject[]>;
546
672
  /** Create if missing, otherwise return existing. Idempotent. */
547
673
  ensureProject(input: {
@@ -551,8 +677,11 @@ interface Deployment extends ProviderIdentity {
551
677
  repo?: string;
552
678
  rootDirectory?: string;
553
679
  }): Promise<DeploymentProject>;
680
+ /** Change the project's settings; only the fields given are changed. Returns the project afterwards. */
554
681
  updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
682
+ /** The names (not values) of the environment variables set on the project for `target`. */
555
683
  listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
684
+ /** Set an environment variable on the project for `target`, replacing any existing value. */
556
685
  setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
557
686
  /**
558
687
  * Kick off a deployment of the given branch. Omit `target` for a
@@ -564,6 +693,7 @@ interface Deployment extends ProviderIdentity {
564
693
  branch: string;
565
694
  target?: DeploymentTrigger;
566
695
  }): Promise<DeploymentRecord>;
696
+ /** One deployment by its id. */
567
697
  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
568
698
  /**
569
699
  * Deploy (or update) a project directly from source files, bypassing
@@ -600,18 +730,25 @@ interface Deployment extends ProviderIdentity {
600
730
  */
601
731
  ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
602
732
  }
733
+ /** A branch of a database or other store, as {@link Storage.listBranches} reports it. */
603
734
  interface StorageBranch {
735
+ /** The provider's id for the branch. */
604
736
  id: string;
737
+ /** The branch's name. */
605
738
  name: string;
606
739
  /** Parent branch id; null for the root/main branch. */
607
740
  parentId: string | null;
741
+ /** When the branch was created, as an ISO timestamp. */
608
742
  createdAt: string;
609
743
  }
744
+ /** Options for {@link Storage.getConnectionString}. */
610
745
  interface ConnectionStringOptions {
611
746
  /** Use the pooled (PgBouncer) URL when available. Defaults to false. */
612
747
  pooled?: boolean;
613
748
  }
749
+ /** A database or file store: connection strings and, for providers that have them, branches. */
614
750
  interface Storage extends ProviderIdentity {
751
+ /** Identifies this provider as the `storage` capability. */
615
752
  readonly key: "storage";
616
753
  /**
617
754
  * Connection string for the given scope. Scope is provider-specific:
@@ -624,11 +761,14 @@ interface Storage extends ProviderIdentity {
624
761
  * a scope; the storage plugin doesn't own that mapping.
625
762
  */
626
763
  getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
764
+ /** Every branch of the store. */
627
765
  listBranches?(): Promise<StorageBranch[]>;
766
+ /** Create a branch named `name`, copied from the `from` branch when given. */
628
767
  createBranch?(input: {
629
768
  name: string;
630
769
  from?: string;
631
770
  }): Promise<StorageBranch>;
771
+ /** Delete the branch (by name or id). */
632
772
  destroyBranch?(branch: string): Promise<void>;
633
773
  /** Restore one branch to match another (e.g., reset preview → main). */
634
774
  resetBranch?(input: {
@@ -644,30 +784,46 @@ interface Storage extends ProviderIdentity {
644
784
  extension: string;
645
785
  }): Promise<void>;
646
786
  }
787
+ /** What the auth provider needs the app to be given at runtime. */
647
788
  interface AuthDescription {
789
+ /** The provider's name. */
648
790
  provider: string;
649
791
  /** Env-var names the app needs at runtime (CLERK_PUBLISHABLE_KEY, etc.). */
650
792
  envKeys: string[];
651
793
  }
794
+ /** What {@link Auth.whoami} found out about the configured credentials. */
652
795
  interface AuthIdentity {
796
+ /** The provider's name. */
653
797
  provider: string;
654
798
  /** Provider-specific health signal (user count, role, account name, etc.). */
655
799
  details?: Record<string, unknown>;
656
800
  }
801
+ /** A user in the auth provider. */
657
802
  interface AuthUser {
803
+ /** The provider's id for the user. */
658
804
  id: string;
805
+ /** The user's email address. */
659
806
  email: string;
660
807
  }
808
+ /** What {@link Auth.createUser} needs to make a user. */
661
809
  interface CreateAuthUserInput {
810
+ /** The new user's email address. */
662
811
  email: string;
812
+ /** The new user's password. */
663
813
  password: string;
814
+ /** The new user's first name. */
664
815
  firstName?: string;
816
+ /** The new user's last name. */
665
817
  lastName?: string;
666
818
  }
819
+ /** Where to configure the auth provider's webhooks. */
667
820
  interface WebhookDashboardInfo {
821
+ /** The address of the provider's webhook settings page. */
668
822
  url: string;
669
823
  }
824
+ /** An identity provider: describes what an app needs from it, proves the credentials work and, where the provider allows, manages users and webhooks. */
670
825
  interface Auth extends ProviderIdentity {
826
+ /** Identifies this provider as the `auth` capability. */
671
827
  readonly key: "auth";
672
828
  /** Env-var keys the runtime app needs. */
673
829
  describe(): Promise<AuthDescription>;
@@ -687,21 +843,31 @@ interface Auth extends ProviderIdentity {
687
843
  secretRef: string;
688
844
  }): Promise<void>;
689
845
  }
846
+ /** What happened to a user, in a form that does not depend on the auth provider. */
690
847
  type AuthEventType = "user.created" | "user.updated" | "user.deleted";
848
+ /** A user as a webhook event reports it, in a form that does not depend on the auth provider. */
691
849
  interface NormalizedAuthUser {
850
+ /** The provider's id for the user. */
692
851
  id: string;
852
+ /** The user's email address. */
693
853
  email: string;
854
+ /** The user's first name; `null` or `undefined` when none is set. */
694
855
  firstName?: string | null;
856
+ /** The user's last name; `null` or `undefined` when none is set. */
695
857
  lastName?: string | null;
696
858
  /** Provider-native fields preserved verbatim for consumers that need them. */
697
859
  raw?: Record<string, unknown>;
698
860
  }
861
+ /** A webhook event from the auth provider, in a form that does not depend on the provider. */
699
862
  interface AuthEvent {
863
+ /** What happened to the user. */
700
864
  type: AuthEventType;
865
+ /** The user the event is about. */
701
866
  user: NormalizedAuthUser;
702
867
  /** ISO timestamp of when the event occurred. */
703
868
  occurredAt: string;
704
869
  }
870
+ /** What a plugin's `parseWebhook` needs to verify and translate an incoming webhook request. */
705
871
  interface ParseWebhookInput {
706
872
  /** Raw request body (string or Buffer). */
707
873
  body: string | Buffer;
@@ -710,11 +876,14 @@ interface ParseWebhookInput {
710
876
  /** The signing secret the auth provider issued for this webhook endpoint. */
711
877
  signingSecret: string;
712
878
  }
879
+ /** The outcome of an idempotent `ensure*` call that creates a container. */
713
880
  interface EnsureResult {
714
881
  /** True when the resource already existed (idempotent no-op). */
715
882
  alreadyExists: boolean;
716
883
  }
884
+ /** A secret store, the source of truth that `holocron secrets sync` reads from. */
717
885
  interface Vault extends ProviderIdentity {
886
+ /** Identifies this provider as the `vault` capability. */
718
887
  readonly key: "vault";
719
888
  /**
720
889
  * Read a secret by reference. The reference format is
@@ -758,14 +927,23 @@ interface Vault extends ProviderIdentity {
758
927
  */
759
928
  ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
760
929
  }
930
+ /** The DNS record types a provider can manage. */
761
931
  type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
932
+ /** A DNS record. */
762
933
  interface DnsRecord {
934
+ /** The provider's id for the record; absent on a record not yet created. */
763
935
  id?: string;
936
+ /** The record's type. */
764
937
  type: DnsRecordType;
938
+ /** The record's name (the host it answers for). */
765
939
  name: string;
940
+ /** The record's value, e.g. an address for `A` or a target host for `CNAME`. */
766
941
  content: string;
942
+ /** Time to live in seconds; the provider's default when absent. */
767
943
  ttl?: number;
944
+ /** Priority, for the record types that have one (`MX`, `SRV`). */
768
945
  priority?: number;
946
+ /** Whether traffic goes through the provider's proxy; only providers that offer one use it. */
769
947
  proxied?: boolean;
770
948
  }
771
949
  /**
@@ -777,12 +955,18 @@ interface DnsRecord {
777
955
  interface DnsRecordRequest {
778
956
  /** Zone apex passed as the first argument to `dns.upsertRecord`. */
779
957
  zone: string;
958
+ /** The record to create or update. */
780
959
  record: DnsRecord;
781
960
  }
961
+ /** DNS record management for a domain. */
782
962
  interface Dns extends ProviderIdentity {
963
+ /** Identifies this provider as the `dns` capability. */
783
964
  readonly key: "dns";
965
+ /** Every record in the domain's zone. */
784
966
  listRecords(domain: string): Promise<DnsRecord[]>;
967
+ /** Create the record, or update the existing one that matches it, and return the result. */
785
968
  upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
969
+ /** Delete the record with the given id from the domain's zone. */
786
970
  deleteRecord(domain: string, id: string): Promise<void>;
787
971
  /**
788
972
  * A `holocron doctor` smoke check with no specific domain to ask about —
@@ -794,7 +978,9 @@ interface Dns extends ProviderIdentity {
794
978
  zones: number;
795
979
  }>;
796
980
  }
981
+ /** Error tracking: describes what an app needs at runtime and, where the provider allows, creates projects and relays alerts. */
797
982
  interface Errors extends ProviderIdentity {
983
+ /** Identifies this provider as the `errors` capability. */
798
984
  readonly key: "errors";
799
985
  /** Returns the env var names the app reads at runtime for this provider. */
800
986
  describe(): Promise<{
@@ -812,6 +998,7 @@ interface Errors extends ProviderIdentity {
812
998
  whoami?(): Promise<{
813
999
  org: string;
814
1000
  } | null>;
1001
+ /** Create the project if it is missing and return its DSN; `alreadyExists` is true when it was already there. */
815
1002
  ensureProject?(input: {
816
1003
  name: string;
817
1004
  platform?: string;
@@ -834,6 +1021,7 @@ interface Errors extends ProviderIdentity {
834
1021
  */
835
1022
  inspectRelay?(input: InspectRelayInput): Promise<RelayState>;
836
1023
  }
1024
+ /** What {@link Errors.ensureRelay} sets up at the error tracker. */
837
1025
  interface EnsureRelayInput {
838
1026
  /** The integration's name at the provider (also how an existing one is found). */
839
1027
  name: string;
@@ -843,7 +1031,9 @@ interface EnsureRelayInput {
843
1031
  projects: string[];
844
1032
  /** The alert rule: its name, and the minutes between two notifications for one issue (default 5). */
845
1033
  rule: {
1034
+ /** The alert rule's name at the provider (also how an existing one is found). */
846
1035
  name: string;
1036
+ /** Minutes between two notifications for one issue; 5 when absent. */
847
1037
  frequency?: number;
848
1038
  };
849
1039
  }
@@ -879,18 +1069,28 @@ interface RelayState {
879
1069
  sends: boolean;
880
1070
  }>;
881
1071
  }
1072
+ /** What {@link Errors.ensureRelay} did. */
882
1073
  interface EnsureRelayResult {
1074
+ /** The integration that posts to the relay. */
883
1075
  integration: {
1076
+ /** Whether it was made now rather than adopted. */
884
1077
  created: boolean;
1078
+ /** For one adopted, the settings that differed and were changed. */
885
1079
  updated: string[];
886
1080
  };
1081
+ /** The alert rule that sends through the integration. */
887
1082
  rule: {
1083
+ /** Whether it was made now rather than adopted. */
888
1084
  created: boolean;
1085
+ /** For one adopted, the settings that differed and were changed. */
889
1086
  updated: string[];
890
1087
  };
1088
+ /** The integration's signing secret, for the relay to verify alerts with. A credential: never print or store it. */
891
1089
  clientSecret?: string;
892
1090
  }
1091
+ /** Log aggregation: describes what an app needs at runtime and, where the provider allows, creates the dataset. */
893
1092
  interface Logs extends ProviderIdentity {
1093
+ /** Identifies this provider as the `logs` capability. */
894
1094
  readonly key: "logs";
895
1095
  /** Returns the env var names the app reads at runtime for this provider. */
896
1096
  describe(): Promise<{
@@ -907,24 +1107,36 @@ interface Logs extends ProviderIdentity {
907
1107
  alreadyExists: boolean;
908
1108
  }>;
909
1109
  }
1110
+ /** What part of a response a {@link MonitoringAssertion} looks at. */
910
1111
  type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
1112
+ /** How a {@link MonitoringAssertion} compares the part of the response with its target. */
911
1113
  type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
1114
+ /** A condition a monitoring check's response must meet to pass. */
912
1115
  interface MonitoringAssertion {
1116
+ /** The part of the response to look at. */
913
1117
  source: MonitoringAssertionSource;
1118
+ /** How to compare it with `target`. */
914
1119
  comparison: MonitoringAssertionComparison;
915
1120
  /** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
916
1121
  property?: string;
1122
+ /** The value to compare against. */
917
1123
  target?: string;
918
1124
  }
1125
+ /** The HTTP methods a monitoring check can use. */
919
1126
  type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
1127
+ /** A monitoring check, in a form that does not depend on the provider. */
920
1128
  interface MonitoringCheckInput {
921
1129
  /** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
922
1130
  name: string;
1131
+ /** The address to request. */
923
1132
  url: string;
1133
+ /** The HTTP method; the provider's default when absent. */
924
1134
  method?: MonitoringHttpMethod;
925
1135
  /** Minutes between runs. Adapters round to their own supported values. */
926
1136
  frequency?: number;
1137
+ /** Conditions the response must meet; the provider's default check when absent. */
927
1138
  assertions?: MonitoringAssertion[];
1139
+ /** Whether the check runs; the provider's default when absent. */
928
1140
  activated?: boolean;
929
1141
  /**
930
1142
  * Provider-specific region/datacenter ids to run the check from (e.g.
@@ -951,8 +1163,11 @@ interface MonitoringCheckInput {
951
1163
  */
952
1164
  body?: string;
953
1165
  }
1166
+ /** A check as the provider holds it. */
954
1167
  interface MonitoringCheck {
1168
+ /** The provider's id for the check. */
955
1169
  id: string;
1170
+ /** The check's name. */
956
1171
  name: string;
957
1172
  }
958
1173
  /** A place the monitoring provider sends its alerts: a webhook that posts into a chat channel. */
@@ -968,7 +1183,9 @@ interface MonitoringAlertChannelInput {
968
1183
  */
969
1184
  url?: string;
970
1185
  }
1186
+ /** What {@link Monitoring.ensureAlertChannel} did. */
971
1187
  interface MonitoringAlertChannelResult {
1188
+ /** Whether the channel was made now rather than already existing. */
972
1189
  created: boolean;
973
1190
  /** For an existing channel, what was brought in line (`"url"`, `"subscriptions"`). */
974
1191
  updated: string[];
@@ -991,7 +1208,9 @@ interface MonitoringAlertChannelState {
991
1208
  /** Names of the checks the channel is subscribed to but has switched off. */
992
1209
  deactivated: string[];
993
1210
  }
1211
+ /** External uptime and synthetic checks run from the provider's infrastructure against a deployed URL. */
994
1212
  interface Monitoring extends ProviderIdentity {
1213
+ /** Identifies this provider as the `monitoring` capability. */
995
1214
  readonly key: "monitoring";
996
1215
  /**
997
1216
  * Checks this provider is configured to ensure exist — populated from
@@ -1006,7 +1225,9 @@ interface Monitoring extends ProviderIdentity {
1006
1225
  * image itself as a `data:` URI for when that cannot be reached. Used when the config names no picture of its own.
1007
1226
  */
1008
1227
  readonly icon?: {
1228
+ /** Where to fetch the picture. */
1009
1229
  url?: string;
1230
+ /** The picture itself as a `data:` URI, for when `url` cannot be reached. */
1010
1231
  dataUri?: string;
1011
1232
  };
1012
1233
  /** Auth sanity-check. Throws ProviderApiError on auth failure. */
@@ -1036,25 +1257,34 @@ interface Monitoring extends ProviderIdentity {
1036
1257
  */
1037
1258
  inspectAlertChannel?(name: string): Promise<MonitoringAlertChannelState>;
1038
1259
  }
1260
+ /** What {@link Tooling.doctor} found. */
1039
1261
  interface ToolingDoctorReport {
1262
+ /** Whether the tool is in a good state. */
1040
1263
  ok: boolean;
1264
+ /** What to show the person: what was found, or what is wrong. */
1041
1265
  message: string;
1042
1266
  }
1267
+ /** A developer tool kept in step with the repo; several can be active at once. */
1043
1268
  interface Tooling extends ProviderIdentity {
1269
+ /** Identifies this provider as the `tooling` capability. */
1044
1270
  readonly key: "tooling";
1045
1271
  /** Sync the tool's authoritative state from the repo. */
1046
1272
  sync(): Promise<void>;
1273
+ /** Check the tool is set up and working, and report what was found. */
1047
1274
  doctor(): Promise<ToolingDoctorReport>;
1048
1275
  }
1049
1276
  /** What an `ensure*` call found or made. `created: false` means it already existed. */
1050
1277
  interface EnsuredResource {
1278
+ /** The provider's id for the resource. */
1051
1279
  id: string;
1280
+ /** Whether the resource was made now rather than already existing. */
1052
1281
  created: boolean;
1053
1282
  /** For something that already existed: the settings that disagreed with the layout and were changed. */
1054
1283
  updated?: string[];
1055
1284
  }
1056
1285
  /** A webhook (or equivalent inbound URL) for a channel. */
1057
1286
  interface EnsureWebhookResult {
1287
+ /** Whether the webhook was made now rather than already existing. */
1058
1288
  created: boolean;
1059
1289
  /**
1060
1290
  * The posting URL — a credential. Absent when the webhook already existed and
@@ -1080,7 +1310,9 @@ interface NotificationsAccess {
1080
1310
  }
1081
1311
  /** One channel in a {@link NotificationsLayout}. */
1082
1312
  interface NotificationsChannelLayout {
1313
+ /** The channel's name. */
1083
1314
  name: string;
1315
+ /** The channel's topic text. */
1084
1316
  topic?: string;
1085
1317
  /** Who may see and post. Overrides the category's, field by field. */
1086
1318
  access?: NotificationsAccess;
@@ -1185,6 +1417,7 @@ interface NotificationsOnboardingLayout {
1185
1417
  enabled?: boolean;
1186
1418
  /** Channels every member starts with, by name. */
1187
1419
  defaultChannels?: string[];
1420
+ /** The questions asked, in order. */
1188
1421
  prompts?: Array<{
1189
1422
  title: string;
1190
1423
  /** One answer only (`true`) or any number. Defaults to `false`. */
@@ -1213,7 +1446,9 @@ interface NotificationsApplicationLayout {
1213
1446
  tags?: string[];
1214
1447
  /** The default install link: what the bot is added with. Permissions are named, as in a role's. */
1215
1448
  install?: {
1449
+ /** The OAuth2 scopes the install link asks for. */
1216
1450
  scopes: string[];
1451
+ /** The permissions the bot is added with, named as in a role's. */
1217
1452
  permissions: string[];
1218
1453
  };
1219
1454
  /** `https://` link to the terms of service. */
@@ -1227,6 +1462,7 @@ interface NotificationsApplicationLayout {
1227
1462
  * find who holds a role. `true` switches it on from code; `false` switches it off.
1228
1463
  */
1229
1464
  intents?: {
1465
+ /** The server members intent: lets the bot list who is in the server. */
1230
1466
  members?: boolean;
1231
1467
  };
1232
1468
  /**
@@ -1300,9 +1536,13 @@ interface NotificationsLayout {
1300
1536
  * `Errors to Discord (Comlink)`) and throttle in minutes (default 5). Left out, nothing is done at the tracker.
1301
1537
  */
1302
1538
  errors?: {
1539
+ /** The tracker projects whose issues are sent. */
1303
1540
  projects: string[];
1541
+ /** The integration's name at the tracker; `Comlink` when absent. */
1304
1542
  integration?: string;
1543
+ /** The alert rule's name; `Errors to Discord (Comlink)` when absent. */
1305
1544
  rule?: string;
1545
+ /** Minutes between two notifications for one issue; 5 when absent. */
1306
1546
  frequency?: number;
1307
1547
  };
1308
1548
  };
@@ -1317,11 +1557,13 @@ interface NotificationsLayout {
1317
1557
  pinned?: NotificationsPinnedLayout[];
1318
1558
  /** Settings of the server itself, applied after its channels exist. */
1319
1559
  server?: NotificationsServerLayout;
1560
+ /** The categories to create, each with the channels under it. */
1320
1561
  categories?: Array<{
1321
1562
  name: string;
1322
1563
  access?: NotificationsAccess;
1323
1564
  channels?: NotificationsChannelLayout[];
1324
1565
  }>;
1566
+ /** The roles to create. */
1325
1567
  roles?: Array<{
1326
1568
  name: string;
1327
1569
  mentionable?: boolean;
@@ -1361,6 +1603,7 @@ interface ServerInspection {
1361
1603
  applicationError?: string;
1362
1604
  /** What everyone may do, by permission name, when the layout declares `everyone`. */
1363
1605
  everyone?: {
1606
+ /** The permissions everyone holds now, by name. */
1364
1607
  permissions: string[];
1365
1608
  };
1366
1609
  /** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
@@ -1384,12 +1627,14 @@ interface ServerInspection {
1384
1627
  server?: NotificationsServerLayout;
1385
1628
  /** Set when reading the server's settings failed; `server` is then absent and means nothing. */
1386
1629
  serverError?: string;
1630
+ /** Names of the categories on the server. */
1387
1631
  categories: string[];
1388
1632
  /**
1389
1633
  * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
1390
1634
  * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
1391
1635
  */
1392
1636
  categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
1637
+ /** The channels the layout asks about, as the server has them. */
1393
1638
  channels: Array<{
1394
1639
  name: string;
1395
1640
  /** The category it sits under, if any. */
@@ -1406,6 +1651,7 @@ interface ServerInspection {
1406
1651
  /** Who can see and post; `"custom"` as for `categoryAccess`. */
1407
1652
  access?: Required<NotificationsAccess> | "custom";
1408
1653
  }>;
1654
+ /** The roles on the server. */
1409
1655
  roles: Array<{
1410
1656
  name: string;
1411
1657
  id: string;
@@ -1422,15 +1668,19 @@ interface ServerInspection {
1422
1668
  interface NotificationsSignedIn {
1423
1669
  /** Their id on the provider; for Discord, the user id. */
1424
1670
  member: string;
1671
+ /** Their name on the provider, when it gives one. */
1425
1672
  name?: string;
1426
1673
  /** The GitHub account the provider has verified they own; absent when they have none linked. */
1427
1674
  github?: {
1675
+ /** The GitHub user id, as a string. */
1428
1676
  id: string;
1677
+ /** The GitHub login. */
1429
1678
  login: string;
1430
1679
  };
1431
1680
  }
1432
1681
  /** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
1433
1682
  interface NotificationsSignIn {
1683
+ /** The address of the provider's sign-in page, carrying the redirect address and state given. */
1434
1684
  authorizeUrl(input: {
1435
1685
  redirectUri: string;
1436
1686
  state: string;
@@ -1441,23 +1691,29 @@ interface NotificationsSignIn {
1441
1691
  code: string;
1442
1692
  }): Promise<NotificationsSignedIn>;
1443
1693
  }
1444
- /** A member of the server, as {@link Notifications.roleMembers} reports it. */
1445
1694
  /** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
1446
1695
  interface NotificationsDelivery {
1696
+ /** The message was posted through the channel's webhook. */
1447
1697
  posted: boolean;
1698
+ /** The message was found in the channel afterwards. */
1448
1699
  readBack: boolean;
1700
+ /** The message was deleted again. */
1449
1701
  removed: boolean;
1450
1702
  /** Set when the message was deliberately left in the channel (`keep`), so `removed` is false on purpose. */
1451
1703
  kept?: boolean;
1704
+ /** What went wrong at each failed step; empty when delivery worked. */
1452
1705
  problems: string[];
1453
1706
  }
1707
+ /** A member of the server, as {@link Notifications.roleMembers} reports it. */
1454
1708
  interface NotificationsMember {
1455
1709
  /** The provider's id for them; for Discord, the user id. */
1456
1710
  id: string;
1457
1711
  /** A display name for reports; absent when the provider does not give one. */
1458
1712
  name?: string;
1459
1713
  }
1714
+ /** Chat notifications: posts messages and, where the provider allows, builds the server a layout describes. */
1460
1715
  interface Notifications extends ProviderIdentity {
1716
+ /** Identifies this provider as the `notifications` capability. */
1461
1717
  readonly key: "notifications";
1462
1718
  /**
1463
1719
  * Send a message. `channel` is provider-specific (Slack channel id,
@@ -1477,12 +1733,14 @@ interface Notifications extends ProviderIdentity {
1477
1733
  ensureCategory?(name: string, opts?: {
1478
1734
  access?: NotificationsAccess;
1479
1735
  }): Promise<EnsuredResource>;
1736
+ /** Find or create a channel, under its category when named, with its topic and access. */
1480
1737
  ensureChannel?(input: {
1481
1738
  name: string;
1482
1739
  category?: string;
1483
1740
  topic?: string;
1484
1741
  access?: NotificationsAccess;
1485
1742
  }): Promise<EnsuredResource>;
1743
+ /** Find or create a webhook named `name` on the channel, creating the channel first if it is missing. */
1486
1744
  ensureWebhook?(input: {
1487
1745
  channel: string;
1488
1746
  name: string;
@@ -1539,6 +1797,7 @@ interface Notifications extends ProviderIdentity {
1539
1797
  removeRoleMember?(roleName: string, memberId: string): Promise<void>;
1540
1798
  /** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
1541
1799
  signIn?(): NotificationsSignIn;
1800
+ /** Find or create a role; one that exists has its settings brought in line. */
1542
1801
  ensureRole?(input: {
1543
1802
  name: string;
1544
1803
  mentionable?: boolean;
@@ -1604,21 +1863,26 @@ interface Notifications extends ProviderIdentity {
1604
1863
  */
1605
1864
  inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
1606
1865
  }
1866
+ /** Product analytics: describes what an app needs at runtime and, where the provider allows, creates projects. */
1607
1867
  interface Analytics extends ProviderIdentity {
1868
+ /** Identifies this provider as the `analytics` capability. */
1608
1869
  readonly key: "analytics";
1609
1870
  /** Returns the env var names the app reads at runtime for this provider. */
1610
1871
  describe(): Promise<{
1611
1872
  provider: string;
1612
1873
  envKeys: string[];
1613
1874
  }>;
1875
+ /** Reachability probe: proves the credentials work and names the organization they belong to. */
1614
1876
  whoami?(): Promise<{
1615
1877
  org: string;
1616
1878
  }>;
1879
+ /** Create the project if it is missing and return its ingestion token; `alreadyExists` is true when it was there. */
1617
1880
  ensureProject?(name: string): Promise<{
1618
1881
  token: string;
1619
1882
  alreadyExists: boolean;
1620
1883
  }>;
1621
1884
  }
1885
+ /** Options for {@link Wiki.provision}. */
1622
1886
  interface WikiProvisionOpts {
1623
1887
  /** Project display name used in the wiki title (e.g. "Holocron"). */
1624
1888
  name?: string;
@@ -1643,6 +1907,7 @@ interface WikiProxyConfig {
1643
1907
  * providers (github) make API calls.
1644
1908
  */
1645
1909
  interface Wiki extends ProviderIdentity {
1910
+ /** Identifies this provider as the `wiki` capability. */
1646
1911
  readonly key: "wiki";
1647
1912
  /** Provision the wiki — write config files or call the provider API. */
1648
1913
  provision(opts?: WikiProvisionOpts): Promise<string>;
@@ -1695,6 +1960,7 @@ interface WorkerScriptState {
1695
1960
  /** The names of the secrets bound to the script. */
1696
1961
  bindingNames: string[];
1697
1962
  }
1963
+ /** What {@link Workers.deployScript} made. */
1698
1964
  interface DeployScriptResult {
1699
1965
  /** The deployed script's name at the provider. */
1700
1966
  scriptName: string;
@@ -1709,6 +1975,7 @@ interface DeployScriptResult {
1709
1975
  * receiver, for instance).
1710
1976
  */
1711
1977
  interface Workers extends ProviderIdentity {
1978
+ /** Identifies this provider as the `workers` capability. */
1712
1979
  readonly key: "workers";
1713
1980
  /**
1714
1981
  * Deploy (or update) a reverse-proxy Worker for `hostname`.
@@ -1741,47 +2008,86 @@ interface Workers extends ProviderIdentity {
1741
2008
  scripts: number;
1742
2009
  }>;
1743
2010
  }
2011
+ /** Maps each capability key to the interface its provider implements. */
1744
2012
  interface CapabilityImpls {
2013
+ /** The `source` provider. */
1745
2014
  source: Source;
2015
+ /** The `ci` provider. */
1746
2016
  ci: Ci;
2017
+ /** The `secrets` provider. */
1747
2018
  secrets: Secrets;
2019
+ /** The `environments` provider. */
1748
2020
  environments: Environments;
2021
+ /** The `issues` provider. */
1749
2022
  issues: Issues;
2023
+ /** The `deployment` provider. */
1750
2024
  deployment: Deployment;
2025
+ /** The `storage` provider. */
1751
2026
  storage: Storage;
2027
+ /** The `auth` provider. */
1752
2028
  auth: Auth;
2029
+ /** The `vault` provider. */
1753
2030
  vault: Vault;
2031
+ /** The `dns` provider. */
1754
2032
  dns: Dns;
2033
+ /** The `tooling` provider. */
1755
2034
  tooling: Tooling;
2035
+ /** The `notifications` provider. */
1756
2036
  notifications: Notifications;
2037
+ /** The `analytics` provider. */
1757
2038
  analytics: Analytics;
2039
+ /** The `errors` provider. */
1758
2040
  errors: Errors;
2041
+ /** The `logs` provider. */
1759
2042
  logs: Logs;
2043
+ /** The `monitoring` provider. */
1760
2044
  monitoring: Monitoring;
2045
+ /** The `wiki` provider. */
1761
2046
  wiki: Wiki;
2047
+ /** The `workers` provider. */
1762
2048
  workers: Workers;
1763
2049
  }
2050
+ /** The cardinality (`"single"` or `"many"`) of the capability `K`. */
1764
2051
  type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
1765
2052
  /** Resolved runtime shape: single → one impl; many → array. */
1766
2053
  type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
2054
+ /** How many providers each capability resolves to: one (`"single"`) or several active at once (`"many"`). */
1767
2055
  declare const CARDINALITY: {
2056
+ /** `source` has exactly one provider. */
1768
2057
  readonly source: "single";
2058
+ /** `ci` has exactly one provider. */
1769
2059
  readonly ci: "single";
2060
+ /** `secrets` has exactly one provider. */
1770
2061
  readonly secrets: "single";
2062
+ /** `environments` has exactly one provider. */
1771
2063
  readonly environments: "single";
2064
+ /** `issues` has exactly one provider. */
1772
2065
  readonly issues: "single";
2066
+ /** `deployment` has exactly one provider. */
1773
2067
  readonly deployment: "single";
2068
+ /** `storage` has exactly one provider. */
1774
2069
  readonly storage: "single";
2070
+ /** `auth` has exactly one provider. */
1775
2071
  readonly auth: "single";
2072
+ /** `vault` has exactly one provider. */
1776
2073
  readonly vault: "single";
2074
+ /** `dns` has exactly one provider. */
1777
2075
  readonly dns: "single";
2076
+ /** `tooling` can have several providers active at once. */
1778
2077
  readonly tooling: "many";
2078
+ /** `notifications` can have several providers active at once. */
1779
2079
  readonly notifications: "many";
2080
+ /** `analytics` can have several providers active at once. */
1780
2081
  readonly analytics: "many";
2082
+ /** `errors` has exactly one provider. */
1781
2083
  readonly errors: "single";
2084
+ /** `logs` has exactly one provider. */
1782
2085
  readonly logs: "single";
2086
+ /** `monitoring` has exactly one provider. */
1783
2087
  readonly monitoring: "single";
2088
+ /** `wiki` has exactly one provider. */
1784
2089
  readonly wiki: "single";
2090
+ /** `workers` has exactly one provider. */
1785
2091
  readonly workers: "single";
1786
2092
  };
1787
2093
  /**
@@ -1795,6 +2101,7 @@ declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
1795
2101
  * needs to give it for one run and take it away again, so `setup` can walk them through it.
1796
2102
  */
1797
2103
  declare class ElevationRequiredError extends Error {
2104
+ /** What a person must approve to give the permission for one run and to take it away again. */
1798
2105
  readonly elevation: {
1799
2106
  /** The permission, in the provider's own name for it. */
1800
2107
  permission: string;
@@ -1809,8 +2116,11 @@ declare class ElevationRequiredError extends Error {
1809
2116
  /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
1810
2117
  applied?: string[];
1811
2118
  };
2119
+ /** Lets a caller tell this error from any other by name, across package copies. */
1812
2120
  name: string;
1813
- constructor(message: string, elevation: {
2121
+ constructor(message: string,
2122
+ /** What a person must approve to give the permission for one run and to take it away again. */
2123
+ elevation: {
1814
2124
  /** The permission, in the provider's own name for it. */
1815
2125
  permission: string;
1816
2126
  /** Where to approve giving it; absent when the provider could not build one. */
@@ -1833,8 +2143,11 @@ declare class MissingTokenError extends Error {
1833
2143
  /** Lets a caller tell this error from any other by name, across package copies. */
1834
2144
  name: string;
1835
2145
  }
2146
+ /** A webhook payload failed signature verification, so it must not be trusted. */
1836
2147
  declare class WebhookVerificationError extends Error {
2148
+ /** Lets a caller tell this error from any other by name, across package copies. */
1837
2149
  name: string;
1838
2150
  }
2151
+ /** Whether `key` is a capability that can have several providers active at once. */
1839
2152
  declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
1840
2153
  export { LifecycleResult as $, ToolingDoctorReport as $t, DeploymentProject as A, ProviderIdentity as At, EnsureRelayResult as B, Source as Bt, ConnectionStringOptions as C, NotificationsPinnedLayout as Ct, DeployScriptConfig as D, NotificationsWelcomeLayout as Dt, DeployFunctionResult as E, NotificationsSignedIn as Et, Dns as F, ResolvedCapability as Ft, EnvironmentReviewer as G, SourceSecurity as Gt, EnsureWebhookResult as H, SourceFile as Ht, DnsRecord as I, Ruleset as It, InspectRelayInput as J, Storage as Jt, Environments as K, SourceTeamMember as Kt, DnsRecordRequest as L, SecretScope as Lt, DeploymentRecord as M, RelayState as Mt, DeploymentTarget as N, RepoRef as Nt, DeployScriptResult as O, PagesConfig as Ot, DeploymentTrigger as P, RepoSettings as Pt, LabelDef as Q, Tooling as Qt, DnsRecordType as R, Secrets as Rt, CiRunStatus as S, NotificationsOnboardingLayout as St, DeployFunctionConfig as T, NotificationsSignIn as Tt, EnsuredResource as U, SourceRepoInfo as Ut, EnsureResult as V, SourceBranch as Vt, Environment as W, SourceRulesetDetail as Wt, IssueSearchFilter as X, TeamEntry as Xt, Issue as Y, StorageBranch as Yt, Issues as Z, TeamPermission as Zt, Cardinality as _, NotificationsDelivery as _t, REQUIRED_CAPABILITIES as a, WikiProvisionOpts as an, MonitoringAlertChannelState as at, CiRun as b, NotificationsLinksLayout as bt, Analytics as c, Workers as cn, MonitoringAssertionSource as ct, AuthEvent as d, MonitoringHttpMethod as dt, TrackerDoctorReport as en, LifecycleSlot as et, AuthEventType as f, NormalizedAuthUser as ft, CapabilityKey as g, NotificationsChannelLayout as gt, CapabilityImpls as h, NotificationsApplicationLayout as ht, ProviderApiError as i, Wiki as in, MonitoringAlertChannelResult as it, DeploymentProjectSettings as j, PullRequest as jt, Deployment as k, ParseWebhookInput as kt, Auth as l, MonitoringCheck as lt, AuthUser as m, NotificationsAccess as mt, ElevationRequiredError as n, Vault as nn, Monitoring as nt, WebhookVerificationError as o, WikiProxyConfig as on, MonitoringAssertion as ot, AuthIdentity as p, Notifications as pt, Errors as q, StatusCategory as qt, MissingTokenError as r, WebhookDashboardInfo as rn, MonitoringAlertChannelInput as rt, isMulti as s, WorkerScriptState as sn, MonitoringAssertionComparison as st, CARDINALITY as t, TrackerUser as tn, Logs as tt, AuthDescription as u, MonitoringCheckInput as ut, CardinalityFor as v, NotificationsEveryoneLayout as vt, CreateAuthUserInput as w, NotificationsServerLayout as wt, CiRunFilter as x, NotificationsMember as xt, Ci as y, NotificationsLayout as yt, EnsureRelayInput as z, ServerInspection as zt };