@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.
- package/README.md +258 -55
- package/dist/cli.mjs +5406 -2206
- package/dist/cli.mjs.map +1 -1
- package/dist/index.d.mts +222 -127
- package/dist/index.mjs +39 -54
- package/dist/plugin/capabilities.d.mts +431 -52
- package/dist/plugin/capabilities.mjs +2 -1
- package/package.json +19 -13
|
@@ -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
|
|
406
|
-
* domain API omit this
|
|
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<
|
|
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?():
|
|
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
|
|
1037
|
+
* Edge Worker management capability.
|
|
704
1038
|
*
|
|
705
|
-
* Deploys and manages Worker scripts
|
|
706
|
-
*
|
|
707
|
-
*
|
|
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,
|
|
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
|
};
|