@theholocron/cli 5.0.0-alpha.19 → 5.0.0-alpha.191

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;
@@ -364,9 +339,35 @@ interface DeploymentRecord {
364
339
  target?: DeploymentTrigger;
365
340
  status: "queued" | "building" | "ready" | "error" | "cancelled";
366
341
  createdAt?: string;
342
+ /** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
343
+ errorMessage?: string;
344
+ }
345
+ /** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
346
+ interface DeployFunctionConfig {
347
+ /**
348
+ * Files to deploy, keyed by path relative to the project root (e.g.
349
+ * `"api/webhook.js"`, `"package.json"`). Content is plain text — the
350
+ * provider handles any wire-format encoding.
351
+ */
352
+ files: Record<string, string>;
353
+ /**
354
+ * Named deployment target. Omit for a preview deployment — same
355
+ * semantics as `triggerDeployment`'s `target`.
356
+ */
357
+ target?: DeploymentTrigger;
358
+ }
359
+ interface DeployFunctionResult {
360
+ deploymentId: string;
361
+ url: string;
367
362
  }
368
363
  interface Deployment extends ProviderIdentity {
369
364
  readonly key: "deployment";
365
+ /**
366
+ * Custom domain declared in the deployment provider's configuration.
367
+ * `holocron repo setup` attaches it to the configured project and hands any
368
+ * returned verification record to the `dns` capability.
369
+ */
370
+ readonly domain?: string;
370
371
  listProjects(): Promise<DeploymentProject[]>;
371
372
  /** Create if missing, otherwise return existing. Idempotent. */
372
373
  ensureProject(input: {
@@ -390,6 +391,16 @@ interface Deployment extends ProviderIdentity {
390
391
  target?: DeploymentTrigger;
391
392
  }): Promise<DeploymentRecord>;
392
393
  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
394
+ /**
395
+ * Deploy (or update) a project directly from source files, bypassing
396
+ * Git entirely — the non-git counterpart to `triggerDeployment`, for a
397
+ * consumer with no repo to link (a webhook receiver shipped as an npm
398
+ * package, for instance, rather than deployed from its own Git
399
+ * history). `projectId` may be a project name for providers that
400
+ * accept either. Optional — providers without a files-based deploy API
401
+ * omit this (e.g. Cloudflare Pages, git-source only today).
402
+ */
403
+ deployFunction?(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
393
404
  /**
394
405
  * List preview deployments for a specific branch alias (e.g. "repo-pr-42").
395
406
  * Optional — providers that don't support listing by branch omit this.
@@ -402,10 +413,18 @@ interface Deployment extends ProviderIdentity {
402
413
  deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
403
414
  /**
404
415
  * Add a custom domain (or wildcard) to the project. Idempotent — no-op
405
- * when the domain is already present. Optional: providers without a custom
406
- * domain API omit this (e.g. Vercel manages domains separately).
416
+ * when the domain is already present. Optional: providers without a
417
+ * custom domain API omit this.
418
+ *
419
+ * Returns the DNS record needed to finish verification — `null` when
420
+ * the domain is already verified, or when the provider's API doesn't
421
+ * surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
422
+ * custom-domain flow doesn't expose the same per-request verification
423
+ * handshake Vercel's does). Callers hand a non-null result straight
424
+ * to `dns.upsertRecord(result.zone, result.record)` — the exact
425
+ * pattern `setup` already uses for `Wiki.dnsRecord()`.
407
426
  */
408
- ensureCustomDomain?(projectId: string, hostname: string): Promise<void>;
427
+ ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
409
428
  }
410
429
  interface StorageBranch {
411
430
  id: string;
@@ -517,9 +536,6 @@ interface ParseWebhookInput {
517
536
  /** The signing secret the auth provider issued for this webhook endpoint. */
518
537
  signingSecret: string;
519
538
  }
520
- declare class WebhookVerificationError extends Error {
521
- name: string;
522
- }
523
539
  interface EnsureResult {
524
540
  /** True when the resource already existed (idempotent no-op). */
525
541
  alreadyExists: boolean;
@@ -573,11 +589,31 @@ interface DnsRecord {
573
589
  priority?: number;
574
590
  proxied?: boolean;
575
591
  }
592
+ /**
593
+ * A DNS record a capability wants created, plus which zone it belongs
594
+ * to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
595
+ * both hand off to `Dns.upsertRecord()`. Not tied to either capability;
596
+ * any provider that needs "here's a record, go create it" returns this.
597
+ */
598
+ interface DnsRecordRequest {
599
+ /** Zone apex passed as the first argument to `dns.upsertRecord`. */
600
+ zone: string;
601
+ record: DnsRecord;
602
+ }
576
603
  interface Dns extends ProviderIdentity {
577
604
  readonly key: "dns";
578
605
  listRecords(domain: string): Promise<DnsRecord[]>;
579
606
  upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
580
607
  deleteRecord(domain: string, id: string): Promise<void>;
608
+ /**
609
+ * A `holocron doctor` smoke check with no specific domain to ask about —
610
+ * `listRecords` needs one, but doctor doesn't have one on hand. Verifies
611
+ * the token and reports how many zones it can see.
612
+ */
613
+ whoami?(): Promise<{
614
+ ok: boolean;
615
+ zones: number;
616
+ }>;
581
617
  }
582
618
  interface Errors extends ProviderIdentity {
583
619
  readonly key: "errors";
@@ -586,9 +622,17 @@ interface Errors extends ProviderIdentity {
586
622
  provider: string;
587
623
  envKeys: string[];
588
624
  }>;
625
+ /**
626
+ * Reachability probe. `null` means the check genuinely can't run right
627
+ * now on an otherwise-valid configuration (e.g. Sentry's optional `org`
628
+ * setting is unset — error ingestion still works from the DSN alone,
629
+ * `org` is only needed for the management-API calls `whoami` makes) —
630
+ * callers should fall back to `describe()`, not treat it as a failure.
631
+ * Still throws for a genuine failure (bad token, network error, etc.).
632
+ */
589
633
  whoami?(): Promise<{
590
634
  org: string;
591
- }>;
635
+ } | null>;
592
636
  ensureProject?(input: {
593
637
  name: string;
594
638
  platform?: string;
@@ -614,6 +658,74 @@ interface Logs extends ProviderIdentity {
614
658
  alreadyExists: boolean;
615
659
  }>;
616
660
  }
661
+ type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
662
+ type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
663
+ interface MonitoringAssertion {
664
+ source: MonitoringAssertionSource;
665
+ comparison: MonitoringAssertionComparison;
666
+ /** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
667
+ property?: string;
668
+ target?: string;
669
+ }
670
+ type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
671
+ interface MonitoringCheckInput {
672
+ /** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
673
+ name: string;
674
+ url: string;
675
+ method?: MonitoringHttpMethod;
676
+ /** Minutes between runs. Adapters round to their own supported values. */
677
+ frequency?: number;
678
+ assertions?: MonitoringAssertion[];
679
+ activated?: boolean;
680
+ /**
681
+ * Provider-specific region/datacenter ids to run the check from (e.g.
682
+ * Checkly's `"us-east-1"`). Required by some providers — there's no
683
+ * universal default; an account with none configured rejects a check
684
+ * that omits this entirely.
685
+ */
686
+ locations?: string[];
687
+ /**
688
+ * Inverts pass/fail: set this when the check's expected-healthy
689
+ * response is itself an HTTP error status (e.g. asserting a 404/405
690
+ * on an endpoint that should reject certain requests). Without it,
691
+ * most providers classify any 4xx/5xx response as a failure at the
692
+ * platform level *before* evaluating `assertions` at all — a custom
693
+ * assertion that matches the "expected" error status does not
694
+ * override that baseline classification on its own.
695
+ */
696
+ shouldFail?: boolean;
697
+ /**
698
+ * Raw request body to send with the check — e.g. simulating a webhook
699
+ * delivery to verify signature/auth checking is wired correctly
700
+ * end-to-end, rather than just confirming the endpoint is reachable.
701
+ * Omitted entirely by default (no body sent).
702
+ */
703
+ body?: string;
704
+ }
705
+ interface MonitoringCheck {
706
+ id: string;
707
+ name: string;
708
+ }
709
+ interface Monitoring extends ProviderIdentity {
710
+ readonly key: "monitoring";
711
+ /**
712
+ * Checks this provider is configured to ensure exist — populated from
713
+ * the provider's own config (`holocron.config.ts`'s provider tuple),
714
+ * the same place `Deployment.domain` comes from. `holocron repo setup`
715
+ * loops this list and calls `ensureCheck` for each; empty when none
716
+ * are configured.
717
+ */
718
+ readonly checks: readonly MonitoringCheckInput[];
719
+ /** Auth sanity-check. Throws ProviderApiError on auth failure. */
720
+ whoami?(): Promise<{
721
+ ok: boolean;
722
+ }>;
723
+ /** Idempotent find-or-create-or-update by `input.name`. */
724
+ ensureCheck(input: MonitoringCheckInput): Promise<{
725
+ check: MonitoringCheck;
726
+ alreadyExists: boolean;
727
+ }>;
728
+ }
617
729
  interface ToolingDoctorReport {
618
730
  ok: boolean;
619
731
  message: string;
@@ -624,6 +736,144 @@ interface Tooling extends ProviderIdentity {
624
736
  sync(): Promise<void>;
625
737
  doctor(): Promise<ToolingDoctorReport>;
626
738
  }
739
+ /** What an `ensure*` call found or made. `created: false` means it already existed. */
740
+ interface EnsuredResource {
741
+ id: string;
742
+ created: boolean;
743
+ /** For something that already existed: the settings that disagreed with the layout and were changed. */
744
+ updated?: string[];
745
+ }
746
+ /** A webhook (or equivalent inbound URL) for a channel. */
747
+ interface EnsureWebhookResult {
748
+ created: boolean;
749
+ /**
750
+ * The posting URL — a credential. Absent when the webhook already existed and
751
+ * the provider will not reveal it again (Discord returns the token only to
752
+ * the application that created the webhook, and only on creation).
753
+ */
754
+ url?: string;
755
+ }
756
+ /**
757
+ * Who may see a channel and post in it. Roles are named as in the layout's `roles`.
758
+ * A channel inherits its category's access; stating `view` or `post` on the channel
759
+ * replaces that field only.
760
+ */
761
+ interface NotificationsAccess {
762
+ /** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
763
+ view?: "everyone" | string[];
764
+ /** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
765
+ post?: "everyone" | string[];
766
+ }
767
+ /** One channel in a {@link NotificationsLayout}. */
768
+ interface NotificationsChannelLayout {
769
+ name: string;
770
+ topic?: string;
771
+ /** Who may see and post. Overrides the category's, field by field. */
772
+ access?: NotificationsAccess;
773
+ /**
774
+ * Create an inbound webhook for the channel and store its URL in a secret.
775
+ * `true` uses the defaults; the object form overrides the webhook's display
776
+ * name and the secret's name.
777
+ */
778
+ webhook?: boolean | {
779
+ name?: string;
780
+ secret?: string;
781
+ };
782
+ }
783
+ /**
784
+ * Settings of the server itself. Channels are named as in the layout's `categories`; each field
785
+ * left out is left alone.
786
+ */
787
+ interface NotificationsServerLayout {
788
+ /** 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). */
789
+ verification?: "none" | "low" | "medium" | "high" | "highest";
790
+ /** Whether members are notified for every message or only when mentioned. */
791
+ defaultNotifications?: "all" | "mentions";
792
+ /** Which members' media is scanned: `off`, `noRoles` (members without a role) or `all`. */
793
+ contentFilter?: "off" | "noRoles" | "all";
794
+ /** Where the provider posts its own notices (member joins, boosts). */
795
+ systemChannel?: string;
796
+ /** The channel holding the server rules; required to turn community features on. */
797
+ rulesChannel?: string;
798
+ /** Where the provider sends its notices to the owners; required to turn community features on. */
799
+ updatesChannel?: string;
800
+ /** Turn community features (welcome screen, onboarding, discovery) on or off. */
801
+ community?: boolean;
802
+ /** The server's public description. Only providers that support one for the server's current state accept it. */
803
+ description?: string;
804
+ /** Preferred language, as a locale such as `en-US`. */
805
+ locale?: string;
806
+ }
807
+ /** A declared server layout, applied idempotently by `holocron notifications setup`. */
808
+ interface NotificationsLayout {
809
+ /** Settings of the server itself, applied after its channels exist. */
810
+ server?: NotificationsServerLayout;
811
+ categories?: Array<{
812
+ name: string;
813
+ access?: NotificationsAccess;
814
+ channels?: NotificationsChannelLayout[];
815
+ }>;
816
+ roles?: Array<{
817
+ name: string;
818
+ mentionable?: boolean;
819
+ /** `#rrggbb`. Omit to leave the colour alone. */
820
+ color?: string;
821
+ /** Show the role's members as their own group in the member list. */
822
+ hoist?: boolean;
823
+ /**
824
+ * The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
825
+ * `SendMessages`, …). The list is exact: a permission not named is not granted.
826
+ */
827
+ permissions?: string[];
828
+ /**
829
+ * Store the role's id in this secret, so a workflow can ping the role
830
+ * without anyone copying the id by hand. The id is not sensitive; a secret
831
+ * is used because the same token that writes the webhook secrets can write
832
+ * it, with no extra permission.
833
+ */
834
+ secret?: string;
835
+ }>;
836
+ }
837
+ /**
838
+ * What a provider found on the server, limited to what a {@link NotificationsLayout}
839
+ * asks about. Read-only: this is what `holocron doctor notifications` compares the
840
+ * layout against.
841
+ */
842
+ interface ServerInspection {
843
+ /** The server's own settings, in the layout's terms, when the layout declares `server`. */
844
+ server?: NotificationsServerLayout;
845
+ /** Set when reading the server's settings failed; `server` is then absent and means nothing. */
846
+ serverError?: string;
847
+ categories: string[];
848
+ /**
849
+ * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
850
+ * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
851
+ */
852
+ categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
853
+ channels: Array<{
854
+ name: string;
855
+ /** The category it sits under, if any. */
856
+ category?: string;
857
+ topic?: string;
858
+ /** Names of the webhooks on the channel. Only filled in for channels the layout gives a webhook. */
859
+ webhooks: string[];
860
+ /** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
861
+ webhooksError?: string;
862
+ /** Who can see and post; `"custom"` as for `categoryAccess`. */
863
+ access?: Required<NotificationsAccess> | "custom";
864
+ }>;
865
+ roles: Array<{
866
+ name: string;
867
+ id: string;
868
+ mentionable: boolean;
869
+ /** `#rrggbb`, or absent for the default colour. */
870
+ color?: string;
871
+ hoist?: boolean;
872
+ permissions?: string[];
873
+ }>;
874
+ /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
875
+ rolesError?: string;
876
+ }
627
877
  interface Notifications extends ProviderIdentity {
628
878
  readonly key: "notifications";
629
879
  /**
@@ -631,6 +881,71 @@ interface Notifications extends ProviderIdentity {
631
881
  * Discord webhook url-name, etc.); adapters resolve from config.
632
882
  */
633
883
  send(channel: string, message: string): Promise<void>;
884
+ /**
885
+ * The server layout the owner declared for this provider, if any. Read by
886
+ * `holocron notifications setup`; the provider just carries it from its options.
887
+ */
888
+ readonly layout?: NotificationsLayout;
889
+ /**
890
+ * Provisioning. All optional, all idempotent (look up by name, create only
891
+ * what is missing), and all need provider credentials beyond the posting
892
+ * URL — so a provider that only posts simply omits them.
893
+ */
894
+ ensureCategory?(name: string, opts?: {
895
+ access?: NotificationsAccess;
896
+ }): Promise<EnsuredResource>;
897
+ ensureChannel?(input: {
898
+ name: string;
899
+ category?: string;
900
+ topic?: string;
901
+ access?: NotificationsAccess;
902
+ }): Promise<EnsuredResource>;
903
+ ensureWebhook?(input: {
904
+ channel: string;
905
+ name: string;
906
+ category?: string;
907
+ }): Promise<EnsureWebhookResult>;
908
+ ensureRole?(input: {
909
+ name: string;
910
+ mentionable?: boolean;
911
+ color?: string;
912
+ hoist?: boolean;
913
+ permissions?: string[];
914
+ }): Promise<EnsuredResource>;
915
+ /**
916
+ * Bring the server's own settings in line with the layout, changing only what differs. Returns the
917
+ * names of what it changed, empty when the server already matched.
918
+ */
919
+ ensureServer?(settings: NotificationsServerLayout): Promise<{
920
+ updated: string[];
921
+ }>;
922
+ /**
923
+ * Before anything is created, prove the credentials can do the parts of the layout that need
924
+ * more than the rest (for Discord, change the server's settings). Throws with the reason and how
925
+ * to fix it, so `setup` stops before it leaves a half-applied layout. Not called on a dry run.
926
+ */
927
+ preflight?(layout: NotificationsLayout): Promise<void>;
928
+ /**
929
+ * Check the provider-specific parts of the layout (colours, permission names, …) without
930
+ * touching the server, so `setup` can refuse a bad layout before it creates anything.
931
+ * Returns the first problem, or `undefined` when the layout is fine.
932
+ */
933
+ validateLayout?(layout: NotificationsLayout): string | undefined;
934
+ /**
935
+ * Smoke check for `holocron doctor`: prove the provisioning credentials work
936
+ * and name what they reach. Returns `null` when there is nothing to check (a
937
+ * config that only posts has no provisioning credentials), which doctor shows
938
+ * as "loaded" rather than as a failure. Throws when it is configured to
939
+ * provision but cannot (missing token, no access).
940
+ */
941
+ whoami?(): Promise<{
942
+ target: string;
943
+ } | null>;
944
+ /**
945
+ * Read what exists on the server, for the parts the layout cares about, without
946
+ * changing anything. Backs `holocron doctor notifications`.
947
+ */
948
+ inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
634
949
  }
635
950
  interface Analytics extends ProviderIdentity {
636
951
  readonly key: "analytics";
@@ -651,18 +966,6 @@ interface WikiProvisionOpts {
651
966
  /** Project display name used in the wiki title (e.g. "Holocron"). */
652
967
  name?: string;
653
968
  }
654
- /**
655
- * DNS record that `setup` should create for a wiki custom domain.
656
- * Returned by `Wiki.dnsRecord()` when a custom domain is configured.
657
- */
658
- interface WikiDnsRecord {
659
- /** Zone apex passed as the first argument to `dns.upsertRecord`. */
660
- zone: string;
661
- /** Full hostname for the CNAME (e.g. "wiki.theholocron.dev"). */
662
- cname: string;
663
- /** CNAME target (e.g. "holocron.docs.buildwithfern.com"). */
664
- target: string;
665
- }
666
969
  /**
667
970
  * Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
668
971
  * Used by `setup` to deploy a Worker that forwards traffic to the wiki
@@ -691,20 +994,53 @@ interface Wiki extends ProviderIdentity {
691
994
  * Returns null when no custom domain is set.
692
995
  * Called by `setup` to provision the CNAME via the `dns` capability.
693
996
  */
694
- dnsRecord?(): WikiDnsRecord | null;
997
+ dnsRecord?(): DnsRecordRequest | null;
695
998
  /**
696
999
  * Reverse-proxy config when the wiki provider requires a Worker-level
697
1000
  * proxy in addition to the CNAME. Returns null when no proxy is needed.
698
1001
  * Called by `setup` to deploy the proxy via the `workers` capability.
699
1002
  */
700
1003
  proxyConfig?(): WikiProxyConfig | null;
1004
+ /**
1005
+ * Confirms a provider token resolves. Unlike `dns`/`workers`/`monitoring`'s
1006
+ * `whoami()`, this is NOT a live reachability check — Fern (the only
1007
+ * current `wiki` provider) exposes no lightweight endpoint to verify a
1008
+ * token actually works; the only token-consuming operation is a full
1009
+ * `fern generate` (holocron#1079). `ok: true` means "a token was found",
1010
+ * not "the token works".
1011
+ */
1012
+ whoami?(): Promise<{
1013
+ ok: boolean;
1014
+ }>;
1015
+ }
1016
+ /** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
1017
+ interface DeployScriptConfig {
1018
+ /** The full Worker script source — a single ES module (`export default { fetch(...) {...} }`). */
1019
+ code: string;
1020
+ /**
1021
+ * Secret bindings — `env.<name>` in the deployed Worker. Values are
1022
+ * write-only; the provider never echoes them back, here or anywhere else.
1023
+ */
1024
+ secrets?: Record<string, string>;
1025
+ /**
1026
+ * Route pattern(s) this Worker should serve (e.g.
1027
+ * `"sentinel.theholocron.dev/*"`). Omit for a Worker reached only via
1028
+ * its `*.workers.dev` URL.
1029
+ */
1030
+ routes?: string[];
1031
+ }
1032
+ interface DeployScriptResult {
1033
+ /** The deployed script's name at the provider. */
1034
+ scriptName: string;
701
1035
  }
702
1036
  /**
703
- * Edge Worker / reverse-proxy management capability.
1037
+ * Edge Worker management capability.
704
1038
  *
705
- * Deploys and manages Worker scripts that proxy traffic to a configured
706
- * target. Used by `setup` to wire wiki custom-domain proxies when the
707
- * wiki provider requires a Worker in addition to the CNAME.
1039
+ * Deploys and manages Worker scripts. `upsertProxy` is the existing,
1040
+ * narrower case `setup` uses to wire wiki custom-domain reverse-proxies;
1041
+ * `deployScript` is the general case — any Worker, any code, its own
1042
+ * secrets — for a consumer that isn't a reverse-proxy (a webhook
1043
+ * receiver, for instance).
708
1044
  */
709
1045
  interface Workers extends ProviderIdentity {
710
1046
  readonly key: "workers";
@@ -714,6 +1050,17 @@ interface Workers extends ProviderIdentity {
714
1050
  * `config.headers` on each request.
715
1051
  */
716
1052
  upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
1053
+ /** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
1054
+ deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
1055
+ /**
1056
+ * A `holocron doctor` smoke check — every other method either mutates or
1057
+ * needs a specific script/zone doctor has no way to supply up front.
1058
+ * Reports how many Worker scripts the token can see.
1059
+ */
1060
+ whoami?(): Promise<{
1061
+ ok: boolean;
1062
+ scripts: number;
1063
+ }>;
717
1064
  }
718
1065
  interface CapabilityImpls {
719
1066
  source: Source;
@@ -731,12 +1078,44 @@ interface CapabilityImpls {
731
1078
  analytics: Analytics;
732
1079
  errors: Errors;
733
1080
  logs: Logs;
1081
+ monitoring: Monitoring;
734
1082
  wiki: Wiki;
735
1083
  workers: Workers;
736
1084
  }
737
1085
  type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
738
1086
  /** Resolved runtime shape: single → one impl; many → array. */
739
1087
  type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
1088
+ //#endregion
1089
+ //#region src/plugin/capabilities/capabilities.d.ts
1090
+ declare const CARDINALITY: {
1091
+ readonly source: "single";
1092
+ readonly ci: "single";
1093
+ readonly secrets: "single";
1094
+ readonly environments: "single";
1095
+ readonly issues: "single";
1096
+ readonly deployment: "single";
1097
+ readonly storage: "single";
1098
+ readonly auth: "single";
1099
+ readonly vault: "single";
1100
+ readonly dns: "single";
1101
+ readonly tooling: "many";
1102
+ readonly notifications: "many";
1103
+ readonly analytics: "many";
1104
+ readonly errors: "single";
1105
+ readonly logs: "single";
1106
+ readonly monitoring: "single";
1107
+ readonly wiki: "single";
1108
+ readonly workers: "single";
1109
+ };
1110
+ /**
1111
+ * No capabilities are strictly required — repos without secrets (e.g. org
1112
+ * community health repos) legitimately omit vault. Plugins validate their
1113
+ * own requirements at call time.
1114
+ */
1115
+ declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
1116
+ declare class WebhookVerificationError extends Error {
1117
+ name: string;
1118
+ }
740
1119
  declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
741
1120
  //#endregion
742
- export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, 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 };
1121
+ 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, EnsureResult, EnsureWebhookResult, EnsuredResource, Environment, EnvironmentReviewer, Environments, Errors, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, Logs, Monitoring, MonitoringAssertion, MonitoringAssertionComparison, MonitoringAssertionSource, MonitoringCheck, MonitoringCheckInput, MonitoringHttpMethod, NormalizedAuthUser, Notifications, NotificationsAccess, NotificationsChannelLayout, NotificationsLayout, NotificationsServerLayout, PagesConfig, ParseWebhookInput, ProviderApiError, ProviderIdentity, PullRequest, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, ServerInspection, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, Wiki, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };
@@ -1,5 +1,5 @@
1
1
  import { ProviderApiError } from "@theholocron/http-client";
2
- //#region src/plugin/capabilities.ts
2
+ //#region src/plugin/capabilities/capabilities.ts
3
3
  const CARDINALITY = {
4
4
  source: "single",
5
5
  ci: "single",
@@ -16,6 +16,7 @@ const CARDINALITY = {
16
16
  analytics: "many",
17
17
  errors: "single",
18
18
  logs: "single",
19
+ monitoring: "single",
19
20
  wiki: "single",
20
21
  workers: "single"
21
22
  };