@theholocron/cli 5.0.0-alpha.23 → 5.0.0-alpha.231

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.
@@ -1,5 +1,5 @@
1
1
  import { ProviderApiError } from "@theholocron/http-client";
2
- //#region src/plugin/capabilities.d.ts
2
+ //#region src/plugin/capabilities/capabilities.type.d.ts
3
3
  /**
4
4
  * Capability interfaces — the contracts that providers implement.
5
5
  *
@@ -12,33 +12,8 @@ import { ProviderApiError } from "@theholocron/http-client";
12
12
  * See `docs/wiki/specifications/tech-architecture.spec.md` for the design narrative
13
13
  * (issue: #74).
14
14
  */
15
- type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "wiki" | "workers";
15
+ type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "monitoring" | "wiki" | "workers";
16
16
  type Cardinality = "single" | "many";
17
- declare const CARDINALITY: {
18
- readonly source: "single";
19
- readonly ci: "single";
20
- readonly secrets: "single";
21
- readonly environments: "single";
22
- readonly issues: "single";
23
- readonly deployment: "single";
24
- readonly storage: "single";
25
- readonly auth: "single";
26
- readonly vault: "single";
27
- readonly dns: "single";
28
- readonly tooling: "many";
29
- readonly notifications: "many";
30
- readonly analytics: "many";
31
- readonly errors: "single";
32
- readonly logs: "single";
33
- readonly wiki: "single";
34
- readonly workers: "single";
35
- };
36
- /**
37
- * No capabilities are strictly required — repos without secrets (e.g. org
38
- * community health repos) legitimately omit vault. Plugins validate their
39
- * own requirements at call time.
40
- */
41
- declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
42
17
  interface ProviderIdentity {
43
18
  readonly key: CapabilityKey;
44
19
  readonly providerName: string;
@@ -79,6 +54,19 @@ type TeamEntry = string | {
79
54
  slug: string;
80
55
  permission: TeamPermission;
81
56
  };
57
+ /** A member of a team, as {@link Source.teamMembers} reports it. */
58
+ interface SourceTeamMember {
59
+ /** The provider's stable id for the person; for GitHub, the numeric user id as a string. */
60
+ id: string;
61
+ /** What they are called now. Can change; never use it as a key. */
62
+ login: string;
63
+ }
64
+ /** A file read by {@link Source.readFile}. */
65
+ interface SourceFile {
66
+ content: string;
67
+ /** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
68
+ version: string;
69
+ }
82
70
  interface Source extends ProviderIdentity {
83
71
  readonly key: "source";
84
72
  /** Auth sanity-check. Throws ProviderApiError on auth failure. */
@@ -146,11 +134,55 @@ interface Source extends ProviderIdentity {
146
134
  * Optional — providers that don't support topics omit this.
147
135
  */
148
136
  syncTopics?(topics: string[]): Promise<string>;
137
+ /**
138
+ * Bring the repository's Actions variables in line with the declared ones: create what is missing, update what
139
+ * differs, leave the rest. With `prune`, also delete the ones the declaration does not name. With `dryRun`, read the current
140
+ * state and report what would change without writing. Returns a summary.
141
+ * Optional — providers without Actions variables omit this.
142
+ */
143
+ syncVariables?(variables: Record<string, string>, opts?: {
144
+ prune?: boolean;
145
+ dryRun?: boolean;
146
+ }): Promise<string>;
147
+ /**
148
+ * The same for the organization's variables, each with the repositories that can read it (`all` or `private`).
149
+ * Optional — providers without organization variables omit this.
150
+ */
151
+ syncOrgVariables?(org: string, variables: Record<string, {
152
+ value: string;
153
+ visibility: "all" | "private";
154
+ }>, opts?: {
155
+ prune?: boolean;
156
+ dryRun?: boolean;
157
+ }): Promise<string>;
149
158
  /**
150
159
  * Sync GitHub team repository access. String shorthand defaults to `push`.
151
160
  * Optional — providers without a team concept omit this.
152
161
  */
153
162
  syncTeams?(teams: TeamEntry[]): Promise<string>;
163
+ /**
164
+ * The members of a team in `org` (default: the repo's organisation), by the provider's own stable id (for GitHub, the
165
+ * numeric user id, which survives a rename) and current login.
166
+ * Optional — providers without a team concept omit this.
167
+ */
168
+ teamMembers?(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
169
+ /**
170
+ * Read one file from a repository (default: this one), with the `version` a later {@link writeFile} must
171
+ * hand back. `null` when the file does not exist.
172
+ * Optional — providers that cannot read file contents omit this.
173
+ */
174
+ readFile?(path: string, repo?: string): Promise<SourceFile | null>;
175
+ /**
176
+ * Create or replace one file in a single commit. Pass the `version` {@link readFile} returned when
177
+ * replacing, and leave it out when creating: a write on top of a version that has since changed is
178
+ * refused (throws a `ProviderApiError` with status 409 or 422), so two writers cannot overwrite each other.
179
+ * Optional — providers that cannot write file contents omit this.
180
+ */
181
+ writeFile?(path: string, content: string, opts: {
182
+ message: string;
183
+ version?: string;
184
+ repo?: string;
185
+ }): Promise<void>;
154
186
  /**
155
187
  * Set the repository description.
156
188
  * Optional — providers that don't support setting descriptions omit this.
@@ -364,6 +396,8 @@ interface DeploymentRecord {
364
396
  target?: DeploymentTrigger;
365
397
  status: "queued" | "building" | "ready" | "error" | "cancelled";
366
398
  createdAt?: string;
399
+ /** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
400
+ errorMessage?: string;
367
401
  }
368
402
  /** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
369
403
  interface DeployFunctionConfig {
@@ -385,6 +419,12 @@ interface DeployFunctionResult {
385
419
  }
386
420
  interface Deployment extends ProviderIdentity {
387
421
  readonly key: "deployment";
422
+ /**
423
+ * Custom domain declared in the deployment provider's configuration.
424
+ * `holocron repo setup` attaches it to the configured project and hands any
425
+ * returned verification record to the `dns` capability.
426
+ */
427
+ readonly domain?: string;
388
428
  listProjects(): Promise<DeploymentProject[]>;
389
429
  /** Create if missing, otherwise return existing. Idempotent. */
390
430
  ensureProject(input: {
@@ -430,10 +470,18 @@ interface Deployment extends ProviderIdentity {
430
470
  deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
431
471
  /**
432
472
  * Add a custom domain (or wildcard) to the project. Idempotent — no-op
433
- * when the domain is already present. Optional: providers without a custom
434
- * domain API omit this (e.g. Vercel manages domains separately).
473
+ * when the domain is already present. Optional: providers without a
474
+ * custom domain API omit this.
475
+ *
476
+ * Returns the DNS record needed to finish verification — `null` when
477
+ * the domain is already verified, or when the provider's API doesn't
478
+ * surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
479
+ * custom-domain flow doesn't expose the same per-request verification
480
+ * handshake Vercel's does). Callers hand a non-null result straight
481
+ * to `dns.upsertRecord(result.zone, result.record)` — the exact
482
+ * pattern `setup` already uses for `Wiki.dnsRecord()`.
435
483
  */
436
- ensureCustomDomain?(projectId: string, hostname: string): Promise<void>;
484
+ ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
437
485
  }
438
486
  interface StorageBranch {
439
487
  id: string;
@@ -545,9 +593,6 @@ interface ParseWebhookInput {
545
593
  /** The signing secret the auth provider issued for this webhook endpoint. */
546
594
  signingSecret: string;
547
595
  }
548
- declare class WebhookVerificationError extends Error {
549
- name: string;
550
- }
551
596
  interface EnsureResult {
552
597
  /** True when the resource already existed (idempotent no-op). */
553
598
  alreadyExists: boolean;
@@ -601,11 +646,31 @@ interface DnsRecord {
601
646
  priority?: number;
602
647
  proxied?: boolean;
603
648
  }
649
+ /**
650
+ * A DNS record a capability wants created, plus which zone it belongs
651
+ * to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
652
+ * both hand off to `Dns.upsertRecord()`. Not tied to either capability;
653
+ * any provider that needs "here's a record, go create it" returns this.
654
+ */
655
+ interface DnsRecordRequest {
656
+ /** Zone apex passed as the first argument to `dns.upsertRecord`. */
657
+ zone: string;
658
+ record: DnsRecord;
659
+ }
604
660
  interface Dns extends ProviderIdentity {
605
661
  readonly key: "dns";
606
662
  listRecords(domain: string): Promise<DnsRecord[]>;
607
663
  upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
608
664
  deleteRecord(domain: string, id: string): Promise<void>;
665
+ /**
666
+ * A `holocron doctor` smoke check with no specific domain to ask about —
667
+ * `listRecords` needs one, but doctor doesn't have one on hand. Verifies
668
+ * the token and reports how many zones it can see.
669
+ */
670
+ whoami?(): Promise<{
671
+ ok: boolean;
672
+ zones: number;
673
+ }>;
609
674
  }
610
675
  interface Errors extends ProviderIdentity {
611
676
  readonly key: "errors";
@@ -614,9 +679,17 @@ interface Errors extends ProviderIdentity {
614
679
  provider: string;
615
680
  envKeys: string[];
616
681
  }>;
682
+ /**
683
+ * Reachability probe. `null` means the check genuinely can't run right
684
+ * now on an otherwise-valid configuration (e.g. Sentry's optional `org`
685
+ * setting is unset — error ingestion still works from the DSN alone,
686
+ * `org` is only needed for the management-API calls `whoami` makes) —
687
+ * callers should fall back to `describe()`, not treat it as a failure.
688
+ * Still throws for a genuine failure (bad token, network error, etc.).
689
+ */
617
690
  whoami?(): Promise<{
618
691
  org: string;
619
- }>;
692
+ } | null>;
620
693
  ensureProject?(input: {
621
694
  name: string;
622
695
  platform?: string;
@@ -624,6 +697,38 @@ interface Errors extends ProviderIdentity {
624
697
  dsn: string;
625
698
  alreadyExists: boolean;
626
699
  }>;
700
+ /**
701
+ * Make the tracker send its alerts to a relay (the Comlink Worker): an integration that posts to `webhookUrl`, and
702
+ * an alert rule on each project that uses it. Idempotent: an integration or rule with the same name is adopted and
703
+ * only what differs is changed. `clientSecret` is the integration's signing secret, handed to the caller to give
704
+ * the relay; it is a credential and must not be printed or stored anywhere but there. It is absent when the
705
+ * provider did not give it (some show it only when the integration is made).
706
+ */
707
+ ensureRelay?(input: EnsureRelayInput): Promise<EnsureRelayResult>;
708
+ }
709
+ interface EnsureRelayInput {
710
+ /** The integration's name at the provider (also how an existing one is found). */
711
+ name: string;
712
+ /** Where the provider posts its alerts, e.g. `https://comlink.theholocron.dev/sentry`. */
713
+ webhookUrl: string;
714
+ /** The projects whose issues are sent. */
715
+ projects: string[];
716
+ /** The alert rule: its name, and the minutes between two notifications for one issue (default 5). */
717
+ rule: {
718
+ name: string;
719
+ frequency?: number;
720
+ };
721
+ }
722
+ interface EnsureRelayResult {
723
+ integration: {
724
+ created: boolean;
725
+ updated: string[];
726
+ };
727
+ rule: {
728
+ created: boolean;
729
+ updated: string[];
730
+ };
731
+ clientSecret?: string;
627
732
  }
628
733
  interface Logs extends ProviderIdentity {
629
734
  readonly key: "logs";
@@ -642,6 +747,108 @@ interface Logs extends ProviderIdentity {
642
747
  alreadyExists: boolean;
643
748
  }>;
644
749
  }
750
+ type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
751
+ type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
752
+ interface MonitoringAssertion {
753
+ source: MonitoringAssertionSource;
754
+ comparison: MonitoringAssertionComparison;
755
+ /** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
756
+ property?: string;
757
+ target?: string;
758
+ }
759
+ type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
760
+ interface MonitoringCheckInput {
761
+ /** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
762
+ name: string;
763
+ url: string;
764
+ method?: MonitoringHttpMethod;
765
+ /** Minutes between runs. Adapters round to their own supported values. */
766
+ frequency?: number;
767
+ assertions?: MonitoringAssertion[];
768
+ activated?: boolean;
769
+ /**
770
+ * Provider-specific region/datacenter ids to run the check from (e.g.
771
+ * Checkly's `"us-east-1"`). Required by some providers — there's no
772
+ * universal default; an account with none configured rejects a check
773
+ * that omits this entirely.
774
+ */
775
+ locations?: string[];
776
+ /**
777
+ * Inverts pass/fail: set this when the check's expected-healthy
778
+ * response is itself an HTTP error status (e.g. asserting a 404/405
779
+ * on an endpoint that should reject certain requests). Without it,
780
+ * most providers classify any 4xx/5xx response as a failure at the
781
+ * platform level *before* evaluating `assertions` at all — a custom
782
+ * assertion that matches the "expected" error status does not
783
+ * override that baseline classification on its own.
784
+ */
785
+ shouldFail?: boolean;
786
+ /**
787
+ * Raw request body to send with the check — e.g. simulating a webhook
788
+ * delivery to verify signature/auth checking is wired correctly
789
+ * end-to-end, rather than just confirming the endpoint is reachable.
790
+ * Omitted entirely by default (no body sent).
791
+ */
792
+ body?: string;
793
+ }
794
+ interface MonitoringCheck {
795
+ id: string;
796
+ name: string;
797
+ }
798
+ /** A place the monitoring provider sends its alerts: a webhook that posts into a chat channel. */
799
+ interface MonitoringAlertChannelInput {
800
+ /** Also the idempotency key: an existing channel with this name is adopted and brought in line. */
801
+ name: string;
802
+ /** The chat service the message is formatted for. */
803
+ format: "discord";
804
+ /**
805
+ * Where alerts post: a credential, because anyone holding it can post to the channel. Absent when the webhook already
806
+ * existed and cannot be read back, in which case an existing alert channel keeps the URL it has and a missing one
807
+ * cannot be created.
808
+ */
809
+ url?: string;
810
+ }
811
+ interface MonitoringAlertChannelResult {
812
+ created: boolean;
813
+ /** For an existing channel, what was brought in line (`"url"`, `"subscriptions"`). */
814
+ updated: string[];
815
+ /** How many checks the channel is subscribed to afterwards. */
816
+ subscribed: number;
817
+ }
818
+ interface Monitoring extends ProviderIdentity {
819
+ readonly key: "monitoring";
820
+ /**
821
+ * Checks this provider is configured to ensure exist — populated from
822
+ * the provider's own config (`holocron.config.ts`'s provider tuple),
823
+ * the same place `Deployment.domain` comes from. `holocron repo setup`
824
+ * loops this list and calls `ensureCheck` for each; empty when none
825
+ * are configured.
826
+ */
827
+ readonly checks: readonly MonitoringCheckInput[];
828
+ /**
829
+ * The service's own picture, for the webhook it posts through (see `feeds.monitoring`): where to fetch it, and the
830
+ * image itself as a `data:` URI for when that cannot be reached. Used when the config names no picture of its own.
831
+ */
832
+ readonly icon?: {
833
+ url?: string;
834
+ dataUri?: string;
835
+ };
836
+ /** Auth sanity-check. Throws ProviderApiError on auth failure. */
837
+ whoami?(): Promise<{
838
+ ok: boolean;
839
+ }>;
840
+ /** Idempotent find-or-create-or-update by `input.name`. */
841
+ ensureCheck(input: MonitoringCheckInput): Promise<{
842
+ check: MonitoringCheck;
843
+ alreadyExists: boolean;
844
+ }>;
845
+ /**
846
+ * Find-or-create-or-update an alert channel by name and subscribe every check the provider has to it. Checks made
847
+ * through an API are never subscribed automatically, so a later run subscribes the ones added since.
848
+ * Optional — a provider with no alert channels omits it.
849
+ */
850
+ ensureAlertChannel?(input: MonitoringAlertChannelInput): Promise<MonitoringAlertChannelResult>;
851
+ }
645
852
  interface ToolingDoctorReport {
646
853
  ok: boolean;
647
854
  message: string;
@@ -652,6 +859,415 @@ interface Tooling extends ProviderIdentity {
652
859
  sync(): Promise<void>;
653
860
  doctor(): Promise<ToolingDoctorReport>;
654
861
  }
862
+ /** What an `ensure*` call found or made. `created: false` means it already existed. */
863
+ interface EnsuredResource {
864
+ id: string;
865
+ created: boolean;
866
+ /** For something that already existed: the settings that disagreed with the layout and were changed. */
867
+ updated?: string[];
868
+ }
869
+ /** A webhook (or equivalent inbound URL) for a channel. */
870
+ interface EnsureWebhookResult {
871
+ created: boolean;
872
+ /**
873
+ * The posting URL — a credential. Absent when the webhook already existed and
874
+ * the provider will not reveal it again (Discord returns the token only to
875
+ * the application that created the webhook, and only on creation).
876
+ */
877
+ url?: string;
878
+ /** For a webhook that already existed, or was just made: the settings that were set (`"avatar"`). */
879
+ updated?: string[];
880
+ /** Set when the webhook is fine but setting its avatar failed; the webhook and its `url` are still good. */
881
+ avatarError?: string;
882
+ }
883
+ /**
884
+ * Who may see a channel and post in it. Roles are named as in the layout's `roles`.
885
+ * A channel inherits its category's access; stating `view` or `post` on the channel
886
+ * replaces that field only.
887
+ */
888
+ interface NotificationsAccess {
889
+ /** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
890
+ view?: "everyone" | string[];
891
+ /** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
892
+ post?: "everyone" | string[];
893
+ }
894
+ /** One channel in a {@link NotificationsLayout}. */
895
+ interface NotificationsChannelLayout {
896
+ name: string;
897
+ topic?: string;
898
+ /** Who may see and post. Overrides the category's, field by field. */
899
+ access?: NotificationsAccess;
900
+ /**
901
+ * Create an inbound webhook for the channel and store its URL in a secret.
902
+ * `true` uses the defaults; the object form overrides the webhook's display
903
+ * name and the secret's name.
904
+ */
905
+ webhook?: boolean | {
906
+ name?: string;
907
+ secret?: string;
908
+ avatar?: string;
909
+ };
910
+ /**
911
+ * Other services that post into this channel through a webhook of their own. Each gets a dedicated webhook, whose
912
+ * URL goes straight to that service and is never stored as a secret, so revoking one service leaves the rest alone.
913
+ */
914
+ feeds?: {
915
+ /**
916
+ * The monitoring provider's alerts. `true` uses the defaults; the object form overrides the alert channel's name
917
+ * (default `Message to #<channel>`) and the dedicated webhook's name (default the provider's name, capitalised), and
918
+ * `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
919
+ * integrations. Left out, it wears the layout's `webhookAvatar`, as every webhook does. A picture is set only on a
920
+ * webhook that has none; the posts carry the service's own name and icon either way.
921
+ */
922
+ monitoring?: boolean | {
923
+ name?: string;
924
+ webhook?: string;
925
+ avatar?: string | {
926
+ url?: string;
927
+ image?: string;
928
+ };
929
+ };
930
+ /**
931
+ * The error tracker's alerts, carried in by the relay Worker (see `relay`). The channel gets a dedicated webhook
932
+ * (default the `errors` provider's name, capitalised) whose URL goes to the Worker as a secret and nowhere else.
933
+ * `avatar` is as for `monitoring`.
934
+ */
935
+ errors?: boolean | {
936
+ webhook?: string;
937
+ avatar?: string | {
938
+ url?: string;
939
+ image?: string;
940
+ };
941
+ };
942
+ };
943
+ }
944
+ /**
945
+ * Settings of the server itself. Channels are named as in the layout's `categories`; each field
946
+ * left out is left alone.
947
+ */
948
+ interface NotificationsServerLayout {
949
+ /** 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). */
950
+ verification?: "none" | "low" | "medium" | "high" | "highest";
951
+ /** Whether members are notified for every message or only when mentioned. */
952
+ defaultNotifications?: "all" | "mentions";
953
+ /** Which members' media is scanned: `off`, `noRoles` (members without a role) or `all`. */
954
+ contentFilter?: "off" | "noRoles" | "all";
955
+ /** Where the provider posts its own notices (member joins, boosts). */
956
+ systemChannel?: string;
957
+ /** The channel holding the server rules; required to turn community features on. */
958
+ rulesChannel?: string;
959
+ /** Where the provider sends its notices to the owners; required to turn community features on. */
960
+ updatesChannel?: string;
961
+ /** Turn community features (welcome screen, onboarding, discovery) on or off. */
962
+ community?: boolean;
963
+ /** The server's public description. Only providers that support one for the server's current state accept it. */
964
+ description?: string;
965
+ /** Preferred language, as a locale such as `en-US`. */
966
+ locale?: string;
967
+ }
968
+ /** A message the provider posts in a channel and pins, so it stays at the top. */
969
+ interface NotificationsPinnedLayout {
970
+ /** A channel in the layout. */
971
+ channel: string;
972
+ /** The message text (Discord allows up to 2000 characters). */
973
+ content: string;
974
+ }
975
+ /**
976
+ * The screen a new member sees on joining: a short text and the channels worth visiting first.
977
+ * Declaring it describes the whole screen: the text and the channels are set to exactly this, so to
978
+ * switch it off, state them as well.
979
+ */
980
+ interface NotificationsWelcomeLayout {
981
+ /** Whether the screen is shown. Defaults to `true`. */
982
+ enabled?: boolean;
983
+ /** A sentence or two about the server (Discord allows up to 140 characters). */
984
+ description: string;
985
+ /** The channels it points to, in order (Discord allows up to five). */
986
+ channels: Array<{
987
+ /** A channel in the layout. */
988
+ channel: string;
989
+ /** Why to visit it (Discord allows up to 50 characters). */
990
+ description: string;
991
+ /** A single emoji shown beside it. */
992
+ emoji?: string;
993
+ }>;
994
+ }
995
+ /** The questions a new member answers to be shown the channels that fit them. */
996
+ interface NotificationsOnboardingLayout {
997
+ /** Turn onboarding on or off. Left out, it is left as it is (Discord has requirements for turning it on). */
998
+ enabled?: boolean;
999
+ /** Channels every member starts with, by name. */
1000
+ defaultChannels?: string[];
1001
+ prompts?: Array<{
1002
+ title: string;
1003
+ /** One answer only (`true`) or any number. Defaults to `false`. */
1004
+ singleSelect?: boolean;
1005
+ /** The member must answer. Defaults to `false`. */
1006
+ required?: boolean;
1007
+ options: Array<{
1008
+ title: string;
1009
+ description?: string;
1010
+ emoji?: string;
1011
+ /** Channels this answer shows, by name. */
1012
+ channels?: string[];
1013
+ /** Roles this answer gives, by name from the layout's `roles`. */
1014
+ roles?: string[];
1015
+ }>;
1016
+ }>;
1017
+ }
1018
+ /**
1019
+ * Settings of the bot's own application (for Discord, what the developer portal shows). A field left
1020
+ * out is left alone.
1021
+ */
1022
+ interface NotificationsApplicationLayout {
1023
+ /** What the application's page says it is (Discord allows up to 400 characters). */
1024
+ description?: string;
1025
+ /** Short labels, up to five of up to twenty characters each. */
1026
+ tags?: string[];
1027
+ /** The default install link: what the bot is added with. Permissions are named, as in a role's. */
1028
+ install?: {
1029
+ scopes: string[];
1030
+ permissions: string[];
1031
+ };
1032
+ /** `https://` link to the terms of service. */
1033
+ termsUrl?: string;
1034
+ /** `https://` link to the privacy policy. */
1035
+ privacyUrl?: string;
1036
+ /** `https://` link the provider calls to verify linked roles. */
1037
+ roleConnectionsUrl?: string;
1038
+ /**
1039
+ * Privileged intents the bot needs. `members` lets it list who is in the server, which `sync-roles` needs to
1040
+ * find who holds a role. `true` switches it on from code; `false` switches it off.
1041
+ */
1042
+ intents?: {
1043
+ members?: boolean;
1044
+ };
1045
+ /**
1046
+ * OAuth2 redirect URIs that must be registered, for `notifications link`. The provider's API does not allow
1047
+ * setting them, so these are only checked: `setup` and the doctor say what to add and where.
1048
+ */
1049
+ redirectUris?: string[];
1050
+ }
1051
+ /**
1052
+ * Permissions of everyone on the server (for Discord, the @everyone role). Unlike a role's `permissions`,
1053
+ * these name only what to change: the rest of the set is left as it is.
1054
+ */
1055
+ interface NotificationsEveryoneLayout {
1056
+ /** Permissions to grant. */
1057
+ allow?: string[];
1058
+ /** Permissions to take away. */
1059
+ deny?: string[];
1060
+ }
1061
+ /** Where the person-to-member links live: one file in a repo, written by the sign-in flow and read by `sync-roles`. */
1062
+ interface NotificationsLinksLayout {
1063
+ /**
1064
+ * The base URL of the hosted sign-in service (Sentinel), for example `https://sentinel.theholocron.dev`.
1065
+ * `notifications link` asks it for `/api/link`; when it answers, sign-in happens there, and when it does not
1066
+ * (down, out of quota, no route yet) the command signs in on this machine instead.
1067
+ */
1068
+ hostedUrl?: string;
1069
+ /** The port the local sign-in listens on, which must be registered as `http://localhost:<port>/callback`. Defaults to 53682. */
1070
+ localPort?: number;
1071
+ /** `owner/name`. Defaults to `<org>/.github-private`. Keep it private: the file pairs two identities. */
1072
+ repo?: string;
1073
+ /** Defaults to `notifications/<provider>-links.json`. */
1074
+ path?: string;
1075
+ }
1076
+ /** A declared server layout, applied idempotently by `holocron notifications setup`. */
1077
+ interface NotificationsLayout {
1078
+ /**
1079
+ * The channel set aside for test posts, by name. It must declare a webhook. `holocron doctor notifications`
1080
+ * leaves one labelled test message there through its webhook (read back to prove delivery works) for a
1081
+ * person to look at; the real channels are never given one unless `--deliver` posts and removes it.
1082
+ */
1083
+ testChannel?: string;
1084
+ /** Where `sync-roles` finds which server member is which GitHub account. Only used by roles with a `team`. */
1085
+ links?: NotificationsLinksLayout;
1086
+ /** The bot's own application settings, applied with the server's. */
1087
+ application?: NotificationsApplicationLayout;
1088
+ /** What everyone on the server may do, applied with the server's settings. */
1089
+ everyone?: NotificationsEveryoneLayout;
1090
+ /**
1091
+ * The picture every webhook gets unless its own `webhook.avatar` says otherwise: a path to a PNG,
1092
+ * JPEG or GIF (from where the CLI runs) or an `https://` URL. It is set only on a webhook that has
1093
+ * no picture yet -- a provider cannot say whether the one it holds is the same image.
1094
+ */
1095
+ webhookAvatar?: string;
1096
+ /**
1097
+ * The Worker that carries other services' alerts into the channels with a `feeds.errors`: built beforehand
1098
+ * (`apps/comlink`), deployed by `notifications setup` with each channel's webhook URL as a secret, and served at
1099
+ * `host`. Secrets set some other way (the service's signing secret) are kept across deploys.
1100
+ */
1101
+ relay?: {
1102
+ /** Where the Worker answers, e.g. `comlink.theholocron.dev`. Its DNS record and route are managed. */
1103
+ host: string;
1104
+ /** The DNS zone the host is in. Default: found by the `dns` provider from the host itself, so rarely needed. */
1105
+ zone?: string;
1106
+ /** The Worker's name at the provider. Default `comlink`. */
1107
+ script?: string;
1108
+ /** The built Worker, relative to the repo root. Default `apps/comlink/dist/worker.js`. */
1109
+ code?: string;
1110
+ /**
1111
+ * The error tracker's side, when its provider can manage it (`Errors.ensureRelay`): the projects whose issues
1112
+ * are sent, the integration's name (default `Comlink`) and the alert rule's name (default
1113
+ * `Errors to Discord (Comlink)`) and throttle in minutes (default 5). Left out, nothing is done at the tracker.
1114
+ */
1115
+ errors?: {
1116
+ projects: string[];
1117
+ integration?: string;
1118
+ rule?: string;
1119
+ frequency?: number;
1120
+ };
1121
+ };
1122
+ /** What a new member sees on joining, applied after the channels exist. */
1123
+ welcome?: NotificationsWelcomeLayout;
1124
+ /** The questions a new member answers, applied after the channels and roles exist. */
1125
+ onboarding?: NotificationsOnboardingLayout;
1126
+ /**
1127
+ * Messages the provider posts and pins, applied after the channels exist. One that already says exactly this
1128
+ * (posted by the provider and still pinned) is left alone; one that says something else is replaced.
1129
+ */
1130
+ pinned?: NotificationsPinnedLayout[];
1131
+ /** Settings of the server itself, applied after its channels exist. */
1132
+ server?: NotificationsServerLayout;
1133
+ categories?: Array<{
1134
+ name: string;
1135
+ access?: NotificationsAccess;
1136
+ channels?: NotificationsChannelLayout[];
1137
+ }>;
1138
+ roles?: Array<{
1139
+ name: string;
1140
+ mentionable?: boolean;
1141
+ /** `#rrggbb`. Omit to leave the colour alone. */
1142
+ color?: string;
1143
+ /** Show the role's members as their own group in the member list. */
1144
+ hoist?: boolean;
1145
+ /**
1146
+ * The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
1147
+ * `SendMessages`, …). The list is exact: a permission not named is not granted.
1148
+ */
1149
+ permissions?: string[];
1150
+ /**
1151
+ * Keep this role's members equal to a team of the `source` provider (for GitHub, a team slug in
1152
+ * the org): `holocron notifications sync-roles` gives the role to every team member who has linked
1153
+ * their account, and takes it from linked people who have left the team.
1154
+ */
1155
+ team?: string;
1156
+ /**
1157
+ * Store the role's id in this secret, so a workflow can ping the role
1158
+ * without anyone copying the id by hand. The id is not sensitive; a secret
1159
+ * is used because the same token that writes the webhook secrets can write
1160
+ * it, with no extra permission.
1161
+ */
1162
+ secret?: string;
1163
+ }>;
1164
+ }
1165
+ /**
1166
+ * What a provider found on the server, limited to what a {@link NotificationsLayout}
1167
+ * asks about. Read-only: this is what `holocron doctor notifications` compares the
1168
+ * layout against.
1169
+ */
1170
+ interface ServerInspection {
1171
+ /** The bot's application as the provider has it, in the layout's terms, when the layout declares `application`. */
1172
+ application?: NotificationsApplicationLayout;
1173
+ /** Set when reading the application failed; `application` is then absent and means nothing. */
1174
+ applicationError?: string;
1175
+ /** What everyone may do, by permission name, when the layout declares `everyone`. */
1176
+ everyone?: {
1177
+ permissions: string[];
1178
+ };
1179
+ /** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
1180
+ everyoneError?: string;
1181
+ /** The welcome screen as the server has it, in the layout's terms, when the layout declares `welcome`. */
1182
+ welcome?: NotificationsWelcomeLayout;
1183
+ /** Set when reading the welcome screen failed; `welcome` is then absent and means nothing. */
1184
+ welcomeError?: string;
1185
+ /** Whether each pinned message the layout declares is in place, in the layout's order. */
1186
+ pinned?: Array<{
1187
+ channel: string;
1188
+ state: "ok" | "missing" | "different";
1189
+ }>;
1190
+ /** Set when reading the pinned messages failed; `pinned` is then absent and means nothing. */
1191
+ pinnedError?: string;
1192
+ /** Onboarding as the server has it, in the layout's terms, when the layout declares `onboarding`. */
1193
+ onboarding?: NotificationsOnboardingLayout;
1194
+ /** Set when reading onboarding failed; `onboarding` is then absent and means nothing. */
1195
+ onboardingError?: string;
1196
+ /** The server's own settings, in the layout's terms, when the layout declares `server`. */
1197
+ server?: NotificationsServerLayout;
1198
+ /** Set when reading the server's settings failed; `server` is then absent and means nothing. */
1199
+ serverError?: string;
1200
+ categories: string[];
1201
+ /**
1202
+ * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
1203
+ * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
1204
+ */
1205
+ categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
1206
+ channels: Array<{
1207
+ name: string;
1208
+ /** The category it sits under, if any. */
1209
+ category?: string;
1210
+ topic?: string;
1211
+ /** Names of the webhooks on the channel. Only filled in for channels the layout gives a webhook. */
1212
+ webhooks: string[];
1213
+ /** Which of those webhooks have a picture of their own. */
1214
+ webhookAvatars?: string[];
1215
+ /** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
1216
+ webhooksError?: string;
1217
+ /** Who can see and post; `"custom"` as for `categoryAccess`. */
1218
+ access?: Required<NotificationsAccess> | "custom";
1219
+ }>;
1220
+ roles: Array<{
1221
+ name: string;
1222
+ id: string;
1223
+ mentionable: boolean;
1224
+ /** `#rrggbb`, or absent for the default colour. */
1225
+ color?: string;
1226
+ hoist?: boolean;
1227
+ permissions?: string[];
1228
+ }>;
1229
+ /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
1230
+ rolesError?: string;
1231
+ }
1232
+ /** Who a member turned out to be after signing in with the provider. */
1233
+ interface NotificationsSignedIn {
1234
+ /** Their id on the provider; for Discord, the user id. */
1235
+ member: string;
1236
+ name?: string;
1237
+ /** The GitHub account the provider has verified they own; absent when they have none linked. */
1238
+ github?: {
1239
+ id: string;
1240
+ login: string;
1241
+ };
1242
+ }
1243
+ /** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
1244
+ interface NotificationsSignIn {
1245
+ authorizeUrl(input: {
1246
+ redirectUri: string;
1247
+ state: string;
1248
+ }): Promise<string>;
1249
+ /** Trades the one-use `code` for who they are, and discards the token it was given. */
1250
+ complete(input: {
1251
+ redirectUri: string;
1252
+ code: string;
1253
+ }): Promise<NotificationsSignedIn>;
1254
+ }
1255
+ /** A member of the server, as {@link Notifications.roleMembers} reports it. */
1256
+ /** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
1257
+ interface NotificationsDelivery {
1258
+ posted: boolean;
1259
+ readBack: boolean;
1260
+ removed: boolean;
1261
+ /** Set when the message was deliberately left in the channel (`keep`), so `removed` is false on purpose. */
1262
+ kept?: boolean;
1263
+ problems: string[];
1264
+ }
1265
+ interface NotificationsMember {
1266
+ /** The provider's id for them; for Discord, the user id. */
1267
+ id: string;
1268
+ /** A display name for reports; absent when the provider does not give one. */
1269
+ name?: string;
1270
+ }
655
1271
  interface Notifications extends ProviderIdentity {
656
1272
  readonly key: "notifications";
657
1273
  /**
@@ -659,6 +1275,145 @@ interface Notifications extends ProviderIdentity {
659
1275
  * Discord webhook url-name, etc.); adapters resolve from config.
660
1276
  */
661
1277
  send(channel: string, message: string): Promise<void>;
1278
+ /**
1279
+ * The server layout the owner declared for this provider, if any. Read by
1280
+ * `holocron notifications setup`; the provider just carries it from its options.
1281
+ */
1282
+ readonly layout?: NotificationsLayout;
1283
+ /**
1284
+ * Provisioning. All optional, all idempotent (look up by name, create only
1285
+ * what is missing), and all need provider credentials beyond the posting
1286
+ * URL — so a provider that only posts simply omits them.
1287
+ */
1288
+ ensureCategory?(name: string, opts?: {
1289
+ access?: NotificationsAccess;
1290
+ }): Promise<EnsuredResource>;
1291
+ ensureChannel?(input: {
1292
+ name: string;
1293
+ category?: string;
1294
+ topic?: string;
1295
+ access?: NotificationsAccess;
1296
+ }): Promise<EnsuredResource>;
1297
+ ensureWebhook?(input: {
1298
+ channel: string;
1299
+ name: string;
1300
+ category?: string;
1301
+ /** An image as a `data:` URI, set when the webhook has none. */
1302
+ avatar?: string;
1303
+ }): Promise<EnsureWebhookResult>;
1304
+ /**
1305
+ * Proves a channel's webhook delivers: posts `text` through it, reads the post back from the channel and
1306
+ * removes it again, unless `keep` is true, in which case the post is left in the channel (and the result
1307
+ * has `kept` instead of `removed`). Never throws for a failed step; the result says which one failed.
1308
+ * Posts a visible message, so callers choose the channel with care.
1309
+ */
1310
+ checkDelivery?(input: {
1311
+ channel: string;
1312
+ name: string;
1313
+ category?: string;
1314
+ /** The message. The provider may format it (Discord renders markdown) and replaces `{channel}` with its link to the channel. */
1315
+ text: string;
1316
+ /** Leave the message in the channel instead of removing it, so a person can see it. */
1317
+ keep?: boolean;
1318
+ }): Promise<NotificationsDelivery>;
1319
+ /**
1320
+ * Creates the server the layout describes, empty, owned by the provider's own bot, and makes it the server
1321
+ * every other call in this run works on. Refuses when the config already names a server unless `force`.
1322
+ */
1323
+ createServer?(input: {
1324
+ name: string;
1325
+ force?: boolean;
1326
+ }): Promise<{
1327
+ id: string;
1328
+ name: string;
1329
+ }>;
1330
+ /** A single-use link, valid for a day, that lets one person join the server through the named channel. */
1331
+ inviteLink?(channel: string): Promise<string>;
1332
+ /** Whether a person is in the server. */
1333
+ hasMember?(memberId: string): Promise<boolean>;
1334
+ /** Hands the server to a member who has joined, so the bot no longer owns it. */
1335
+ transferServer?(memberId: string): Promise<void>;
1336
+ /** Who owns the server, and whether that is the provider's own bot. */
1337
+ serverOwner?(): Promise<{
1338
+ id: string;
1339
+ isBot: boolean;
1340
+ name?: string;
1341
+ }>;
1342
+ /**
1343
+ * Who holds a role, by the provider's member id. Needs whatever permission the provider asks for to list
1344
+ * members (for Discord, the privileged Server Members Intent). Throws if the role does not exist.
1345
+ */
1346
+ roleMembers?(roleName: string): Promise<NotificationsMember[]>;
1347
+ /** Give a member the role; one who has it already is left alone. */
1348
+ addRoleMember?(roleName: string, memberId: string): Promise<void>;
1349
+ /** Take the role from a member; one who lacks it is left alone. */
1350
+ removeRoleMember?(roleName: string, memberId: string): Promise<void>;
1351
+ /** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
1352
+ signIn?(): NotificationsSignIn;
1353
+ ensureRole?(input: {
1354
+ name: string;
1355
+ mentionable?: boolean;
1356
+ color?: string;
1357
+ hoist?: boolean;
1358
+ permissions?: string[];
1359
+ }): Promise<EnsuredResource>;
1360
+ /**
1361
+ * Bring the server's own settings in line with the layout, changing only what differs. Returns the
1362
+ * names of what it changed, empty when the server already matched.
1363
+ */
1364
+ ensureServer?(settings: NotificationsServerLayout): Promise<{
1365
+ updated: string[];
1366
+ }>;
1367
+ /** Bring the welcome screen in line with the layout, changing only what differs. Returns what it changed. */
1368
+ ensureWelcome?(welcome: NotificationsWelcomeLayout): Promise<{
1369
+ updated: string[];
1370
+ }>;
1371
+ /** Post and pin the layout's messages, replacing any that differ. Returns the channels it changed. */
1372
+ ensurePinned?(pinned: NotificationsPinnedLayout[]): Promise<{
1373
+ updated: string[];
1374
+ }>;
1375
+ /** Whether the bot holds the permission right now (the owner holds every one). Used to prove an elevation was taken back. */
1376
+ holdsPermission?(permission: string): Promise<boolean>;
1377
+ /** Bring onboarding in line with the layout, changing only what differs. Returns what it changed. */
1378
+ ensureOnboarding?(onboarding: NotificationsOnboardingLayout): Promise<{
1379
+ updated: string[];
1380
+ }>;
1381
+ /** Bring the bot's application settings in line with the layout, changing only what differs. Returns what it changed. */
1382
+ ensureApplication?(application: NotificationsApplicationLayout): Promise<{
1383
+ updated: string[];
1384
+ todo?: string[];
1385
+ }>;
1386
+ /** Grant or take away the named permissions from everyone, changing only what differs. Returns what it changed. */
1387
+ ensureEveryone?(everyone: NotificationsEveryoneLayout): Promise<{
1388
+ updated: string[];
1389
+ }>;
1390
+ /**
1391
+ * Before anything is created, prove the credentials can do the parts of the layout that need
1392
+ * more than the rest (for Discord, change the server's settings). Throws with the reason and how
1393
+ * to fix it, so `setup` stops before it leaves a half-applied layout. Not called on a dry run.
1394
+ */
1395
+ preflight?(layout: NotificationsLayout): Promise<void>;
1396
+ /**
1397
+ * Check the provider-specific parts of the layout (colours, permission names, …) without
1398
+ * touching the server, so `setup` can refuse a bad layout before it creates anything.
1399
+ * Returns the first problem, or `undefined` when the layout is fine.
1400
+ */
1401
+ validateLayout?(layout: NotificationsLayout): string | undefined;
1402
+ /**
1403
+ * Smoke check for `holocron doctor`: prove the provisioning credentials work
1404
+ * and name what they reach. Returns `null` when there is nothing to check (a
1405
+ * config that only posts has no provisioning credentials), which doctor shows
1406
+ * as "loaded" rather than as a failure. Throws when it is configured to
1407
+ * provision but cannot (missing token, no access).
1408
+ */
1409
+ whoami?(): Promise<{
1410
+ target: string;
1411
+ } | null>;
1412
+ /**
1413
+ * Read what exists on the server, for the parts the layout cares about, without
1414
+ * changing anything. Backs `holocron doctor notifications`.
1415
+ */
1416
+ inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
662
1417
  }
663
1418
  interface Analytics extends ProviderIdentity {
664
1419
  readonly key: "analytics";
@@ -679,18 +1434,6 @@ interface WikiProvisionOpts {
679
1434
  /** Project display name used in the wiki title (e.g. "Holocron"). */
680
1435
  name?: string;
681
1436
  }
682
- /**
683
- * DNS record that `setup` should create for a wiki custom domain.
684
- * Returned by `Wiki.dnsRecord()` when a custom domain is configured.
685
- */
686
- interface WikiDnsRecord {
687
- /** Zone apex passed as the first argument to `dns.upsertRecord`. */
688
- zone: string;
689
- /** Full hostname for the CNAME (e.g. "wiki.theholocron.dev"). */
690
- cname: string;
691
- /** CNAME target (e.g. "holocron.docs.buildwithfern.com"). */
692
- target: string;
693
- }
694
1437
  /**
695
1438
  * Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
696
1439
  * Used by `setup` to deploy a Worker that forwards traffic to the wiki
@@ -719,13 +1462,24 @@ interface Wiki extends ProviderIdentity {
719
1462
  * Returns null when no custom domain is set.
720
1463
  * Called by `setup` to provision the CNAME via the `dns` capability.
721
1464
  */
722
- dnsRecord?(): WikiDnsRecord | null;
1465
+ dnsRecord?(): DnsRecordRequest | null;
723
1466
  /**
724
1467
  * Reverse-proxy config when the wiki provider requires a Worker-level
725
1468
  * proxy in addition to the CNAME. Returns null when no proxy is needed.
726
1469
  * Called by `setup` to deploy the proxy via the `workers` capability.
727
1470
  */
728
1471
  proxyConfig?(): WikiProxyConfig | null;
1472
+ /**
1473
+ * Confirms a provider token resolves. Unlike `dns`/`workers`/`monitoring`'s
1474
+ * `whoami()`, this is NOT a live reachability check — Fern (the only
1475
+ * current `wiki` provider) exposes no lightweight endpoint to verify a
1476
+ * token actually works; the only token-consuming operation is a full
1477
+ * `fern generate` (holocron#1079). `ok: true` means "a token was found",
1478
+ * not "the token works".
1479
+ */
1480
+ whoami?(): Promise<{
1481
+ ok: boolean;
1482
+ }>;
729
1483
  }
730
1484
  /** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
731
1485
  interface DeployScriptConfig {
@@ -766,6 +1520,22 @@ interface Workers extends ProviderIdentity {
766
1520
  upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
767
1521
  /** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
768
1522
  deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
1523
+ /**
1524
+ * Set one secret binding on a script that is already deployed, leaving its code and every other binding alone.
1525
+ * The value is write-only. `holocron secrets sync --worker` uses it to fan a vault out to a Worker.
1526
+ */
1527
+ setSecret?(script: string, name: string, value: string): Promise<void>;
1528
+ /** The names (never the values) of the secrets bound to a deployed script. `holocron probe` uses it to see what a Worker has. */
1529
+ secretNames?(script: string): Promise<string[]>;
1530
+ /**
1531
+ * A `holocron doctor` smoke check — every other method either mutates or
1532
+ * needs a specific script/zone doctor has no way to supply up front.
1533
+ * Reports how many Worker scripts the token can see.
1534
+ */
1535
+ whoami?(): Promise<{
1536
+ ok: boolean;
1537
+ scripts: number;
1538
+ }>;
769
1539
  }
770
1540
  interface CapabilityImpls {
771
1541
  source: Source;
@@ -783,12 +1553,79 @@ interface CapabilityImpls {
783
1553
  analytics: Analytics;
784
1554
  errors: Errors;
785
1555
  logs: Logs;
1556
+ monitoring: Monitoring;
786
1557
  wiki: Wiki;
787
1558
  workers: Workers;
788
1559
  }
789
1560
  type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
790
1561
  /** Resolved runtime shape: single → one impl; many → array. */
791
1562
  type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
1563
+ //#endregion
1564
+ //#region src/plugin/capabilities/capabilities.d.ts
1565
+ declare const CARDINALITY: {
1566
+ readonly source: "single";
1567
+ readonly ci: "single";
1568
+ readonly secrets: "single";
1569
+ readonly environments: "single";
1570
+ readonly issues: "single";
1571
+ readonly deployment: "single";
1572
+ readonly storage: "single";
1573
+ readonly auth: "single";
1574
+ readonly vault: "single";
1575
+ readonly dns: "single";
1576
+ readonly tooling: "many";
1577
+ readonly notifications: "many";
1578
+ readonly analytics: "many";
1579
+ readonly errors: "single";
1580
+ readonly logs: "single";
1581
+ readonly monitoring: "single";
1582
+ readonly wiki: "single";
1583
+ readonly workers: "single";
1584
+ };
1585
+ /**
1586
+ * No capabilities are strictly required — repos without secrets (e.g. org
1587
+ * community health repos) legitimately omit vault. Plugins validate their
1588
+ * own requirements at call time.
1589
+ */
1590
+ declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
1591
+ /**
1592
+ * A provider could not finish an edit because the bot lacks a permission it should not keep. Carries what a person
1593
+ * needs to give it for one run and take it away again, so `setup` can walk them through it.
1594
+ */
1595
+ declare class ElevationRequiredError extends Error {
1596
+ readonly elevation: {
1597
+ /** The permission, in the provider's own name for it. */
1598
+ permission: string;
1599
+ /** Where to approve giving it; absent when the provider could not build one. */
1600
+ grantUrl?: string;
1601
+ /** Where to approve taking it away again; absent when the provider could not build one. */
1602
+ revokeUrl?: string;
1603
+ /** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
1604
+ label?: string;
1605
+ /** The permission is meant to stay once given: there is nothing to take away afterwards. */
1606
+ keep?: boolean;
1607
+ /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
1608
+ applied?: string[];
1609
+ };
1610
+ name: string;
1611
+ constructor(message: string, elevation: {
1612
+ /** The permission, in the provider's own name for it. */
1613
+ permission: string;
1614
+ /** Where to approve giving it; absent when the provider could not build one. */
1615
+ grantUrl?: string;
1616
+ /** Where to approve taking it away again; absent when the provider could not build one. */
1617
+ revokeUrl?: string;
1618
+ /** A name for the permission a person would recognise, when {@link permission} is the provider's code for it. */
1619
+ label?: string;
1620
+ /** The permission is meant to stay once given: there is nothing to take away afterwards. */
1621
+ keep?: boolean;
1622
+ /** What the edit had already changed before it was refused, so a retry does not hide it from the summary. */
1623
+ applied?: string[];
1624
+ }, options?: ErrorOptions);
1625
+ }
1626
+ declare class WebhookVerificationError extends Error {
1627
+ name: string;
1628
+ }
792
1629
  declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
793
1630
  //#endregion
794
- export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, NormalizedAuthUser, Notifications, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiDnsRecord, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };
1631
+ export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, DeployFunctionConfig, DeployFunctionResult, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, DnsRecordType, ElevationRequiredError, EnsureRelayInput, EnsureRelayResult, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAlertChannelInput, MonitoringAlertChannelResult, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, NotificationsPinnedLayout, NotificationsServerLayout, NotificationsSignIn, NotificationsSignedIn, NotificationsWelcomeLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, SourceFile, SourceTeamMember, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };