@theholocron/cli 5.0.0-alpha.20 → 5.0.0-alpha.201

package/dist/plugin/capabilities.d.mts

@@ -1,5 +1,5 @@
 import { ProviderApiError } from "@theholocron/http-client";
-//#region src/plugin/capabilities.d.ts
+//#region src/plugin/capabilities/capabilities.type.d.ts
 /**
  * Capability interfaces — the contracts that providers implement.
  *
@@ -12,33 +12,8 @@ import { ProviderApiError } from "@theholocron/http-client";
  * See `docs/wiki/specifications/tech-architecture.spec.md` for the design narrative
  * (issue: #74).
  */
-type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "wiki" | "workers";
+type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "errors" | "logs" | "monitoring" | "wiki" | "workers";
 type Cardinality = "single" | "many";
-declare const CARDINALITY: {
-  readonly source: "single";
-  readonly ci: "single";
-  readonly secrets: "single";
-  readonly environments: "single";
-  readonly issues: "single";
-  readonly deployment: "single";
-  readonly storage: "single";
-  readonly auth: "single";
-  readonly vault: "single";
-  readonly dns: "single";
-  readonly tooling: "many";
-  readonly notifications: "many";
-  readonly analytics: "many";
-  readonly errors: "single";
-  readonly logs: "single";
-  readonly wiki: "single";
-  readonly workers: "single";
-};
-/**
- * No capabilities are strictly required — repos without secrets (e.g. org
- * community health repos) legitimately omit vault. Plugins validate their
- * own requirements at call time.
- */
-declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
 interface ProviderIdentity {
   readonly key: CapabilityKey;
   readonly providerName: string;
@@ -79,6 +54,19 @@ type TeamEntry = string | {
   slug: string;
   permission: TeamPermission;
 };
+/** A member of a team, as {@link Source.teamMembers} reports it. */
+interface SourceTeamMember {
+  /** The provider's stable id for the person; for GitHub, the numeric user id as a string. */
+  id: string;
+  /** What they are called now. Can change; never use it as a key. */
+  login: string;
+}
+/** A file read by {@link Source.readFile}. */
+interface SourceFile {
+  content: string;
+  /** Opaque; hand it back to {@link Source.writeFile} to replace this exact version. */
+  version: string;
+}
 interface Source extends ProviderIdentity {
   readonly key: "source";
   /** Auth sanity-check. Throws ProviderApiError on auth failure. */
@@ -151,6 +139,29 @@ interface Source extends ProviderIdentity {
    * Optional — providers without a team concept omit this.
    */
   syncTeams?(teams: TeamEntry[]): Promise<string>;
+  /**
+   * The members of a team in `org` (default: the repo's organisation), by the provider's own stable id (for GitHub, the
+   * numeric user id, which survives a rename) and current login.
+   * Optional — providers without a team concept omit this.
+   */
+  teamMembers?(teamSlug: string, org?: string): Promise<SourceTeamMember[]>;
+  /**
+   * Read one file from a repository (default: this one), with the `version` a later {@link writeFile} must
+   * hand back. `null` when the file does not exist.
+   * Optional — providers that cannot read file contents omit this.
+   */
+  readFile?(path: string, repo?: string): Promise<SourceFile | null>;
+  /**
+   * Create or replace one file in a single commit. Pass the `version` {@link readFile} returned when
+   * replacing, and leave it out when creating: a write on top of a version that has since changed is
+   * refused (throws a `ProviderApiError` with status 409 or 422), so two writers cannot overwrite each other.
+   * Optional — providers that cannot write file contents omit this.
+   */
+  writeFile?(path: string, content: string, opts: {
+    message: string;
+    version?: string;
+    repo?: string;
+  }): Promise<void>;
   /**
    * Set the repository description.
    * Optional — providers that don't support setting descriptions omit this.
@@ -364,9 +375,35 @@ interface DeploymentRecord {
   target?: DeploymentTrigger;
   status: "queued" | "building" | "ready" | "error" | "cancelled";
   createdAt?: string;
+  /** The provider's own reason when `status` is `"error"` (e.g. Vercel's `Command "npm install" exited with 1`). */
+  errorMessage?: string;
+}
+/** Config for `Deployment.deployFunction()` — source files, not a Git ref. */
+interface DeployFunctionConfig {
+  /**
+   * Files to deploy, keyed by path relative to the project root (e.g.
+   * `"api/webhook.js"`, `"package.json"`). Content is plain text — the
+   * provider handles any wire-format encoding.
+   */
+  files: Record<string, string>;
+  /**
+   * Named deployment target. Omit for a preview deployment — same
+   * semantics as `triggerDeployment`'s `target`.
+   */
+  target?: DeploymentTrigger;
+}
+interface DeployFunctionResult {
+  deploymentId: string;
+  url: string;
 }
 interface Deployment extends ProviderIdentity {
   readonly key: "deployment";
+  /**
+   * Custom domain declared in the deployment provider's configuration.
+   * `holocron repo setup` attaches it to the configured project and hands any
+   * returned verification record to the `dns` capability.
+   */
+  readonly domain?: string;
   listProjects(): Promise<DeploymentProject[]>;
   /** Create if missing, otherwise return existing. Idempotent. */
   ensureProject(input: {
@@ -390,6 +427,16 @@ interface Deployment extends ProviderIdentity {
     target?: DeploymentTrigger;
   }): Promise<DeploymentRecord>;
   getDeployment(deploymentId: string): Promise<DeploymentRecord>;
+  /**
+   * Deploy (or update) a project directly from source files, bypassing
+   * Git entirely — the non-git counterpart to `triggerDeployment`, for a
+   * consumer with no repo to link (a webhook receiver shipped as an npm
+   * package, for instance, rather than deployed from its own Git
+   * history). `projectId` may be a project name for providers that
+   * accept either. Optional — providers without a files-based deploy API
+   * omit this (e.g. Cloudflare Pages, git-source only today).
+   */
+  deployFunction?(projectId: string, config: DeployFunctionConfig): Promise<DeployFunctionResult>;
   /**
    * List preview deployments for a specific branch alias (e.g. "repo-pr-42").
    * Optional — providers that don't support listing by branch omit this.
@@ -402,10 +449,18 @@ interface Deployment extends ProviderIdentity {
   deletePreviewDeployments?(projectId: string, deploymentIds: string[]): Promise<number>;
   /**
    * Add a custom domain (or wildcard) to the project. Idempotent — no-op
-   * when the domain is already present. Optional: providers without a custom
-   * domain API omit this (e.g. Vercel manages domains separately).
+   * when the domain is already present. Optional: providers without a
+   * custom domain API omit this.
+   *
+   * Returns the DNS record needed to finish verification — `null` when
+   * the domain is already verified, or when the provider's API doesn't
+   * surface DNS-challenge details at all (e.g. Cloudflare Pages, whose
+   * custom-domain flow doesn't expose the same per-request verification
+   * handshake Vercel's does). Callers hand a non-null result straight
+   * to `dns.upsertRecord(result.zone, result.record)` — the exact
+   * pattern `setup` already uses for `Wiki.dnsRecord()`.
    */
-  ensureCustomDomain?(projectId: string, hostname: string): Promise<void>;
+  ensureCustomDomain?(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
 }
 interface StorageBranch {
   id: string;
@@ -517,9 +572,6 @@ interface ParseWebhookInput {
   /** The signing secret the auth provider issued for this webhook endpoint. */
   signingSecret: string;
 }
-declare class WebhookVerificationError extends Error {
-  name: string;
-}
 interface EnsureResult {
   /** True when the resource already existed (idempotent no-op). */
   alreadyExists: boolean;
@@ -573,11 +625,31 @@ interface DnsRecord {
   priority?: number;
   proxied?: boolean;
 }
+/**
+ * A DNS record a capability wants created, plus which zone it belongs
+ * to — the shape `Wiki.dnsRecord()` and `Deployment.ensureCustomDomain()`
+ * both hand off to `Dns.upsertRecord()`. Not tied to either capability;
+ * any provider that needs "here's a record, go create it" returns this.
+ */
+interface DnsRecordRequest {
+  /** Zone apex passed as the first argument to `dns.upsertRecord`. */
+  zone: string;
+  record: DnsRecord;
+}
 interface Dns extends ProviderIdentity {
   readonly key: "dns";
   listRecords(domain: string): Promise<DnsRecord[]>;
   upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
   deleteRecord(domain: string, id: string): Promise<void>;
+  /**
+   * A `holocron doctor` smoke check with no specific domain to ask about —
+   * `listRecords` needs one, but doctor doesn't have one on hand. Verifies
+   * the token and reports how many zones it can see.
+   */
+  whoami?(): Promise<{
+    ok: boolean;
+    zones: number;
+  }>;
 }
 interface Errors extends ProviderIdentity {
   readonly key: "errors";
@@ -586,9 +658,17 @@ interface Errors extends ProviderIdentity {
     provider: string;
     envKeys: string[];
   }>;
+  /**
+   * Reachability probe. `null` means the check genuinely can't run right
+   * now on an otherwise-valid configuration (e.g. Sentry's optional `org`
+   * setting is unset — error ingestion still works from the DSN alone,
+   * `org` is only needed for the management-API calls `whoami` makes) —
+   * callers should fall back to `describe()`, not treat it as a failure.
+   * Still throws for a genuine failure (bad token, network error, etc.).
+   */
   whoami?(): Promise<{
     org: string;
-  }>;
+  } | null>;
   ensureProject?(input: {
     name: string;
     platform?: string;
@@ -614,6 +694,74 @@ interface Logs extends ProviderIdentity {
     alreadyExists: boolean;
   }>;
 }
+type MonitoringAssertionSource = "status_code" | "response_time" | "body" | "header";
+type MonitoringAssertionComparison = "equals" | "not_equals" | "contains" | "not_contains" | "greater_than" | "less_than";
+interface MonitoringAssertion {
+  source: MonitoringAssertionSource;
+  comparison: MonitoringAssertionComparison;
+  /** Header name / JSON path — required when `source` needs one (e.g. `"header"`). */
+  property?: string;
+  target?: string;
+}
+type MonitoringHttpMethod = "GET" | "POST" | "PUT" | "HEAD" | "DELETE" | "PATCH";
+interface MonitoringCheckInput {
+  /** Also the idempotency key — `ensureCheck` finds-or-creates by this name. */
+  name: string;
+  url: string;
+  method?: MonitoringHttpMethod;
+  /** Minutes between runs. Adapters round to their own supported values. */
+  frequency?: number;
+  assertions?: MonitoringAssertion[];
+  activated?: boolean;
+  /**
+   * Provider-specific region/datacenter ids to run the check from (e.g.
+   * Checkly's `"us-east-1"`). Required by some providers — there's no
+   * universal default; an account with none configured rejects a check
+   * that omits this entirely.
+   */
+  locations?: string[];
+  /**
+   * Inverts pass/fail: set this when the check's expected-healthy
+   * response is itself an HTTP error status (e.g. asserting a 404/405
+   * on an endpoint that should reject certain requests). Without it,
+   * most providers classify any 4xx/5xx response as a failure at the
+   * platform level *before* evaluating `assertions` at all — a custom
+   * assertion that matches the "expected" error status does not
+   * override that baseline classification on its own.
+   */
+  shouldFail?: boolean;
+  /**
+   * Raw request body to send with the check — e.g. simulating a webhook
+   * delivery to verify signature/auth checking is wired correctly
+   * end-to-end, rather than just confirming the endpoint is reachable.
+   * Omitted entirely by default (no body sent).
+   */
+  body?: string;
+}
+interface MonitoringCheck {
+  id: string;
+  name: string;
+}
+interface Monitoring extends ProviderIdentity {
+  readonly key: "monitoring";
+  /**
+   * Checks this provider is configured to ensure exist — populated from
+   * the provider's own config (`holocron.config.ts`'s provider tuple),
+   * the same place `Deployment.domain` comes from. `holocron repo setup`
+   * loops this list and calls `ensureCheck` for each; empty when none
+   * are configured.
+   */
+  readonly checks: readonly MonitoringCheckInput[];
+  /** Auth sanity-check. Throws ProviderApiError on auth failure. */
+  whoami?(): Promise<{
+    ok: boolean;
+  }>;
+  /** Idempotent find-or-create-or-update by `input.name`. */
+  ensureCheck(input: MonitoringCheckInput): Promise<{
+    check: MonitoringCheck;
+    alreadyExists: boolean;
+  }>;
+}
 interface ToolingDoctorReport {
   ok: boolean;
   message: string;
@@ -624,6 +772,329 @@ interface Tooling extends ProviderIdentity {
   sync(): Promise<void>;
   doctor(): Promise<ToolingDoctorReport>;
 }
+/** What an `ensure*` call found or made. `created: false` means it already existed. */
+interface EnsuredResource {
+  id: string;
+  created: boolean;
+  /** For something that already existed: the settings that disagreed with the layout and were changed. */
+  updated?: string[];
+}
+/** A webhook (or equivalent inbound URL) for a channel. */
+interface EnsureWebhookResult {
+  created: boolean;
+  /**
+   * The posting URL — a credential. Absent when the webhook already existed and
+   * the provider will not reveal it again (Discord returns the token only to
+   * the application that created the webhook, and only on creation).
+   */
+  url?: string;
+  /** For a webhook that already existed, or was just made: the settings that were set (`"avatar"`). */
+  updated?: string[];
+  /** Set when the webhook is fine but setting its avatar failed; the webhook and its `url` are still good. */
+  avatarError?: string;
+}
+/**
+ * Who may see a channel and post in it. Roles are named as in the layout's `roles`.
+ * A channel inherits its category's access; stating `view` or `post` on the channel
+ * replaces that field only.
+ */
+interface NotificationsAccess {
+  /** `"everyone"` (the default), or the roles that can see it: everyone else cannot. */
+  view?: "everyone" | string[];
+  /** `"everyone"` (the default), or the roles that can post; `[]` means only bots and webhooks. */
+  post?: "everyone" | string[];
+}
+/** One channel in a {@link NotificationsLayout}. */
+interface NotificationsChannelLayout {
+  name: string;
+  topic?: string;
+  /** Who may see and post. Overrides the category's, field by field. */
+  access?: NotificationsAccess;
+  /**
+   * Create an inbound webhook for the channel and store its URL in a secret.
+   * `true` uses the defaults; the object form overrides the webhook's display
+   * name and the secret's name.
+   */
+  webhook?: boolean | {
+    name?: string;
+    secret?: string;
+    avatar?: string;
+  };
+}
+/**
+ * Settings of the server itself. Channels are named as in the layout's `categories`; each field
+ * left out is left alone.
+ */
+interface NotificationsServerLayout {
+  /** 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). */
+  verification?: "none" | "low" | "medium" | "high" | "highest";
+  /** Whether members are notified for every message or only when mentioned. */
+  defaultNotifications?: "all" | "mentions";
+  /** Which members' media is scanned: `off`, `noRoles` (members without a role) or `all`. */
+  contentFilter?: "off" | "noRoles" | "all";
+  /** Where the provider posts its own notices (member joins, boosts). */
+  systemChannel?: string;
+  /** The channel holding the server rules; required to turn community features on. */
+  rulesChannel?: string;
+  /** Where the provider sends its notices to the owners; required to turn community features on. */
+  updatesChannel?: string;
+  /** Turn community features (welcome screen, onboarding, discovery) on or off. */
+  community?: boolean;
+  /** The server's public description. Only providers that support one for the server's current state accept it. */
+  description?: string;
+  /** Preferred language, as a locale such as `en-US`. */
+  locale?: string;
+}
+/**
+ * The screen a new member sees on joining: a short text and the channels worth visiting first.
+ * Declaring it describes the whole screen: the text and the channels are set to exactly this, so to
+ * switch it off, state them as well.
+ */
+interface NotificationsWelcomeLayout {
+  /** Whether the screen is shown. Defaults to `true`. */
+  enabled?: boolean;
+  /** A sentence or two about the server (Discord allows up to 140 characters). */
+  description: string;
+  /** The channels it points to, in order (Discord allows up to five). */
+  channels: Array<{
+    /** A channel in the layout. */
+    channel: string;
+    /** Why to visit it (Discord allows up to 50 characters). */
+    description: string;
+    /** A single emoji shown beside it. */
+    emoji?: string;
+  }>;
+}
+/** The questions a new member answers to be shown the channels that fit them. */
+interface NotificationsOnboardingLayout {
+  /** Turn onboarding on or off. Left out, it is left as it is (Discord has requirements for turning it on). */
+  enabled?: boolean;
+  /** Channels every member starts with, by name. */
+  defaultChannels?: string[];
+  prompts?: Array<{
+    title: string;
+    /** One answer only (`true`) or any number. Defaults to `false`. */
+    singleSelect?: boolean;
+    /** The member must answer. Defaults to `false`. */
+    required?: boolean;
+    options: Array<{
+      title: string;
+      description?: string;
+      emoji?: string;
+      /** Channels this answer shows, by name. */
+      channels?: string[];
+      /** Roles this answer gives, by name from the layout's `roles`. */
+      roles?: string[];
+    }>;
+  }>;
+}
+/**
+ * Settings of the bot's own application (for Discord, what the developer portal shows). A field left
+ * out is left alone.
+ */
+interface NotificationsApplicationLayout {
+  /** What the application's page says it is (Discord allows up to 400 characters). */
+  description?: string;
+  /** Short labels, up to five of up to twenty characters each. */
+  tags?: string[];
+  /** The default install link: what the bot is added with. Permissions are named, as in a role's. */
+  install?: {
+    scopes: string[];
+    permissions: string[];
+  };
+  /** `https://` link to the terms of service. */
+  termsUrl?: string;
+  /** `https://` link to the privacy policy. */
+  privacyUrl?: string;
+  /** `https://` link the provider calls to verify linked roles. */
+  roleConnectionsUrl?: string;
+  /**
+   * Privileged intents the bot needs. `members` lets it list who is in the server, which `sync-roles` needs to
+   * find who holds a role. `true` switches it on from code; `false` switches it off.
+   */
+  intents?: {
+    members?: boolean;
+  };
+  /**
+   * OAuth2 redirect URIs that must be registered, for `notifications link`. The provider's API does not allow
+   * setting them, so these are only checked: `setup` and the doctor say what to add and where.
+   */
+  redirectUris?: string[];
+}
+/**
+ * Permissions of everyone on the server (for Discord, the @everyone role). Unlike a role's `permissions`,
+ * these name only what to change: the rest of the set is left as it is.
+ */
+interface NotificationsEveryoneLayout {
+  /** Permissions to grant. */
+  allow?: string[];
+  /** Permissions to take away. */
+  deny?: string[];
+}
+/** Where the person-to-member links live: one file in a repo, written by the sign-in flow and read by `sync-roles`. */
+interface NotificationsLinksLayout {
+  /**
+   * The base URL of the hosted sign-in service (Sentinel), for example `https://sentinel.theholocron.dev`.
+   * `notifications link` asks it for `/api/link`; when it answers, sign-in happens there, and when it does not
+   * (down, out of quota, no route yet) the command signs in on this machine instead.
+   */
+  hostedUrl?: string;
+  /** The port the local sign-in listens on, which must be registered as `http://localhost:<port>/callback`. Defaults to 53682. */
+  localPort?: number;
+  /** `owner/name`. Defaults to `<org>/.github-private`. Keep it private: the file pairs two identities. */
+  repo?: string;
+  /** Defaults to `notifications/<provider>-links.json`. */
+  path?: string;
+}
+/** A declared server layout, applied idempotently by `holocron notifications setup`. */
+interface NotificationsLayout {
+  /** Where `sync-roles` finds which server member is which GitHub account. Only used by roles with a `team`. */
+  links?: NotificationsLinksLayout;
+  /** The bot's own application settings, applied with the server's. */
+  application?: NotificationsApplicationLayout;
+  /** What everyone on the server may do, applied with the server's settings. */
+  everyone?: NotificationsEveryoneLayout;
+  /**
+   * The picture every webhook gets unless its own `webhook.avatar` says otherwise: a path to a PNG,
+   * JPEG or GIF (from where the CLI runs) or an `https://` URL. It is set only on a webhook that has
+   * no picture yet -- a provider cannot say whether the one it holds is the same image.
+   */
+  webhookAvatar?: string;
+  /** What a new member sees on joining, applied after the channels exist. */
+  welcome?: NotificationsWelcomeLayout;
+  /** The questions a new member answers, applied after the channels and roles exist. */
+  onboarding?: NotificationsOnboardingLayout;
+  /** Settings of the server itself, applied after its channels exist. */
+  server?: NotificationsServerLayout;
+  categories?: Array<{
+    name: string;
+    access?: NotificationsAccess;
+    channels?: NotificationsChannelLayout[];
+  }>;
+  roles?: Array<{
+    name: string;
+    mentionable?: boolean;
+    /** `#rrggbb`. Omit to leave the colour alone. */
+    color?: string;
+    /** Show the role's members as their own group in the member list. */
+    hoist?: boolean;
+    /**
+     * The permissions the role holds, by the provider's own names (for Discord, `ViewChannel`,
+     * `SendMessages`, …). The list is exact: a permission not named is not granted.
+     */
+    permissions?: string[];
+    /**
+     * Keep this role's members equal to a team of the `source` provider (for GitHub, a team slug in
+     * the org): `holocron notifications sync-roles` gives the role to every team member who has linked
+     * their account, and takes it from linked people who have left the team.
+     */
+    team?: string;
+    /**
+     * Store the role's id in this secret, so a workflow can ping the role
+     * without anyone copying the id by hand. The id is not sensitive; a secret
+     * is used because the same token that writes the webhook secrets can write
+     * it, with no extra permission.
+     */
+    secret?: string;
+  }>;
+}
+/**
+ * What a provider found on the server, limited to what a {@link NotificationsLayout}
+ * asks about. Read-only: this is what `holocron doctor notifications` compares the
+ * layout against.
+ */
+interface ServerInspection {
+  /** The bot's application as the provider has it, in the layout's terms, when the layout declares `application`. */
+  application?: NotificationsApplicationLayout;
+  /** Set when reading the application failed; `application` is then absent and means nothing. */
+  applicationError?: string;
+  /** What everyone may do, by permission name, when the layout declares `everyone`. */
+  everyone?: {
+    permissions: string[];
+  };
+  /** Set when reading everyone's permissions failed; `everyone` is then absent and means nothing. */
+  everyoneError?: string;
+  /** The welcome screen as the server has it, in the layout's terms, when the layout declares `welcome`. */
+  welcome?: NotificationsWelcomeLayout;
+  /** Set when reading the welcome screen failed; `welcome` is then absent and means nothing. */
+  welcomeError?: string;
+  /** Onboarding as the server has it, in the layout's terms, when the layout declares `onboarding`. */
+  onboarding?: NotificationsOnboardingLayout;
+  /** Set when reading onboarding failed; `onboarding` is then absent and means nothing. */
+  onboardingError?: string;
+  /** The server's own settings, in the layout's terms, when the layout declares `server`. */
+  server?: NotificationsServerLayout;
+  /** Set when reading the server's settings failed; `server` is then absent and means nothing. */
+  serverError?: string;
+  categories: string[];
+  /**
+   * Who can see and post in each category. `"custom"` means its overwrites are not an access the layout
+   * can state (a role-specific deny, a member overwrite, only some of the posting permissions).
+   */
+  categoryAccess?: Record<string, Required<NotificationsAccess> | "custom">;
+  channels: Array<{
+    name: string;
+    /** The category it sits under, if any. */
+    category?: string;
+    topic?: string;
+    /** Names of the webhooks on the channel. Only filled in for channels the layout gives a webhook. */
+    webhooks: string[];
+    /** Which of those webhooks have a picture of their own. */
+    webhookAvatars?: string[];
+    /** Set when listing this channel's webhooks failed; `webhooks` is then empty and means nothing. */
+    webhooksError?: string;
+    /** Who can see and post; `"custom"` as for `categoryAccess`. */
+    access?: Required<NotificationsAccess> | "custom";
+  }>;
+  roles: Array<{
+    name: string;
+    id: string;
+    mentionable: boolean;
+    /** `#rrggbb`, or absent for the default colour. */
+    color?: string;
+    hoist?: boolean;
+    permissions?: string[];
+  }>;
+  /** Set when reading the roles failed; `roles` is then empty and means nothing. Not read at all when the layout declares none. */
+  rolesError?: string;
+}
+/** Who a member turned out to be after signing in with the provider. */
+interface NotificationsSignedIn {
+  /** Their id on the provider; for Discord, the user id. */
+  member: string;
+  name?: string;
+  /** The GitHub account the provider has verified they own; absent when they have none linked. */
+  github?: {
+    id: string;
+    login: string;
+  };
+}
+/** The provider's "sign in" half: build the page a member opens, then learn who they are from the code it sends back. */
+interface NotificationsSignIn {
+  authorizeUrl(input: {
+    redirectUri: string;
+    state: string;
+  }): Promise<string>;
+  /** Trades the one-use `code` for who they are, and discards the token it was given. */
+  complete(input: {
+    redirectUri: string;
+    code: string;
+  }): Promise<NotificationsSignedIn>;
+}
+/** A member of the server, as {@link Notifications.roleMembers} reports it. */
+/** What {@link Notifications.checkDelivery} saw: each step that went wrong is named in `problems`. */
+interface NotificationsDelivery {
+  posted: boolean;
+  readBack: boolean;
+  removed: boolean;
+  problems: string[];
+}
+interface NotificationsMember {
+  /** The provider's id for them; for Discord, the user id. */
+  id: string;
+  /** A display name for reports; absent when the provider does not give one. */
+  name?: string;
+}
 interface Notifications extends ProviderIdentity {
   readonly key: "notifications";
   /**
@@ -631,6 +1102,112 @@ interface Notifications extends ProviderIdentity {
    * Discord webhook url-name, etc.); adapters resolve from config.
    */
   send(channel: string, message: string): Promise<void>;
+  /**
+   * The server layout the owner declared for this provider, if any. Read by
+   * `holocron notifications setup`; the provider just carries it from its options.
+   */
+  readonly layout?: NotificationsLayout;
+  /**
+   * Provisioning. All optional, all idempotent (look up by name, create only
+   * what is missing), and all need provider credentials beyond the posting
+   * URL — so a provider that only posts simply omits them.
+   */
+  ensureCategory?(name: string, opts?: {
+    access?: NotificationsAccess;
+  }): Promise<EnsuredResource>;
+  ensureChannel?(input: {
+    name: string;
+    category?: string;
+    topic?: string;
+    access?: NotificationsAccess;
+  }): Promise<EnsuredResource>;
+  ensureWebhook?(input: {
+    channel: string;
+    name: string;
+    category?: string;
+    /** An image as a `data:` URI, set when the webhook has none. */
+    avatar?: string;
+  }): Promise<EnsureWebhookResult>;
+  /**
+   * Proves a channel's webhook delivers: posts `text` through it, reads the post back from the channel and
+   * removes it again. Never throws for a failed step; the result says which one failed. Posts a visible
+   * message for a moment, so callers ask before using it.
+   */
+  checkDelivery?(input: {
+    channel: string;
+    name: string;
+    category?: string;
+    text: string;
+  }): Promise<NotificationsDelivery>;
+  /**
+   * Who holds a role, by the provider's member id. Needs whatever permission the provider asks for to list
+   * members (for Discord, the privileged Server Members Intent). Throws if the role does not exist.
+   */
+  roleMembers?(roleName: string): Promise<NotificationsMember[]>;
+  /** Give a member the role; one who has it already is left alone. */
+  addRoleMember?(roleName: string, memberId: string): Promise<void>;
+  /** Take the role from a member; one who lacks it is left alone. */
+  removeRoleMember?(roleName: string, memberId: string): Promise<void>;
+  /** Sign-in used to learn which GitHub account a member is. Optional; needs an OAuth client secret. */
+  signIn?(): NotificationsSignIn;
+  ensureRole?(input: {
+    name: string;
+    mentionable?: boolean;
+    color?: string;
+    hoist?: boolean;
+    permissions?: string[];
+  }): Promise<EnsuredResource>;
+  /**
+   * Bring the server's own settings in line with the layout, changing only what differs. Returns the
+   * names of what it changed, empty when the server already matched.
+   */
+  ensureServer?(settings: NotificationsServerLayout): Promise<{
+    updated: string[];
+  }>;
+  /** Bring the welcome screen in line with the layout, changing only what differs. Returns what it changed. */
+  ensureWelcome?(welcome: NotificationsWelcomeLayout): Promise<{
+    updated: string[];
+  }>;
+  /** Bring onboarding in line with the layout, changing only what differs. Returns what it changed. */
+  ensureOnboarding?(onboarding: NotificationsOnboardingLayout): Promise<{
+    updated: string[];
+  }>;
+  /** Bring the bot's application settings in line with the layout, changing only what differs. Returns what it changed. */
+  ensureApplication?(application: NotificationsApplicationLayout): Promise<{
+    updated: string[];
+    todo?: string[];
+  }>;
+  /** Grant or take away the named permissions from everyone, changing only what differs. Returns what it changed. */
+  ensureEveryone?(everyone: NotificationsEveryoneLayout): Promise<{
+    updated: string[];
+  }>;
+  /**
+   * Before anything is created, prove the credentials can do the parts of the layout that need
+   * more than the rest (for Discord, change the server's settings). Throws with the reason and how
+   * to fix it, so `setup` stops before it leaves a half-applied layout. Not called on a dry run.
+   */
+  preflight?(layout: NotificationsLayout): Promise<void>;
+  /**
+   * Check the provider-specific parts of the layout (colours, permission names, …) without
+   * touching the server, so `setup` can refuse a bad layout before it creates anything.
+   * Returns the first problem, or `undefined` when the layout is fine.
+   */
+  validateLayout?(layout: NotificationsLayout): string | undefined;
+  /**
+   * Smoke check for `holocron doctor`: prove the provisioning credentials work
+   * and name what they reach. Returns `null` when there is nothing to check (a
+   * config that only posts has no provisioning credentials), which doctor shows
+   * as "loaded" rather than as a failure. Throws when it is configured to
+   * provision but cannot (missing token, no access).
+   */
+  whoami?(): Promise<{
+    target: string;
+  } | null>;
+  /**
+   * Read what exists on the server, for the parts the layout cares about, without
+   * changing anything. Backs `holocron doctor notifications`.
+   */
+  inspect?(layout: NotificationsLayout): Promise<ServerInspection>;
 }
 interface Analytics extends ProviderIdentity {
   readonly key: "analytics";
@@ -651,18 +1228,6 @@ interface WikiProvisionOpts {
   /** Project display name used in the wiki title (e.g. "Holocron"). */
   name?: string;
 }
-/**
- * DNS record that `setup` should create for a wiki custom domain.
- * Returned by `Wiki.dnsRecord()` when a custom domain is configured.
- */
-interface WikiDnsRecord {
-  /** Zone apex passed as the first argument to `dns.upsertRecord`. */
-  zone: string;
-  /** Full hostname for the CNAME (e.g. "wiki.theholocron.dev"). */
-  cname: string;
-  /** CNAME target (e.g. "holocron.docs.buildwithfern.com"). */
-  target: string;
-}
 /**
  * Reverse-proxy configuration returned by `Wiki.proxyConfig()`.
  * Used by `setup` to deploy a Worker that forwards traffic to the wiki
@@ -691,13 +1256,24 @@ interface Wiki extends ProviderIdentity {
    * Returns null when no custom domain is set.
    * Called by `setup` to provision the CNAME via the `dns` capability.
    */
-  dnsRecord?(): WikiDnsRecord | null;
+  dnsRecord?(): DnsRecordRequest | null;
   /**
    * Reverse-proxy config when the wiki provider requires a Worker-level
    * proxy in addition to the CNAME. Returns null when no proxy is needed.
    * Called by `setup` to deploy the proxy via the `workers` capability.
    */
   proxyConfig?(): WikiProxyConfig | null;
+  /**
+   * Confirms a provider token resolves. Unlike `dns`/`workers`/`monitoring`'s
+   * `whoami()`, this is NOT a live reachability check — Fern (the only
+   * current `wiki` provider) exposes no lightweight endpoint to verify a
+   * token actually works; the only token-consuming operation is a full
+   * `fern generate` (holocron#1079). `ok: true` means "a token was found",
+   * not "the token works".
+   */
+  whoami?(): Promise<{
+    ok: boolean;
+  }>;
 }
 /** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
 interface DeployScriptConfig {
@@ -738,6 +1314,15 @@ interface Workers extends ProviderIdentity {
   upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
   /** Deploy (or update) an arbitrary Worker script, optionally with secrets and routes. */
   deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
+  /**
+   * A `holocron doctor` smoke check — every other method either mutates or
+   * needs a specific script/zone doctor has no way to supply up front.
+   * Reports how many Worker scripts the token can see.
+   */
+  whoami?(): Promise<{
+    ok: boolean;
+    scripts: number;
+  }>;
 }
 interface CapabilityImpls {
   source: Source;
@@ -755,12 +1340,44 @@ interface CapabilityImpls {
   analytics: Analytics;
   errors: Errors;
   logs: Logs;
+  monitoring: Monitoring;
   wiki: Wiki;
   workers: Workers;
 }
 type CardinalityFor<K extends CapabilityKey> = (typeof CARDINALITY)[K];
 /** Resolved runtime shape: single → one impl; many → array. */
 type ResolvedCapability<K extends CapabilityKey> = CardinalityFor<K> extends "many" ? CapabilityImpls[K][] : CapabilityImpls[K];
+//#endregion
+//#region src/plugin/capabilities/capabilities.d.ts
+declare const CARDINALITY: {
+  readonly source: "single";
+  readonly ci: "single";
+  readonly secrets: "single";
+  readonly environments: "single";
+  readonly issues: "single";
+  readonly deployment: "single";
+  readonly storage: "single";
+  readonly auth: "single";
+  readonly vault: "single";
+  readonly dns: "single";
+  readonly tooling: "many";
+  readonly notifications: "many";
+  readonly analytics: "many";
+  readonly errors: "single";
+  readonly logs: "single";
+  readonly monitoring: "single";
+  readonly wiki: "single";
+  readonly workers: "single";
+};
+/**
+ * No capabilities are strictly required — repos without secrets (e.g. org
+ * community health repos) legitimately omit vault. Plugins validate their
+ * own requirements at call time.
+ */
+declare const REQUIRED_CAPABILITIES: readonly CapabilityKey[];
+declare class WebhookVerificationError extends Error {
+  name: string;
+}
 declare function isMulti<K extends CapabilityKey>(key: K): CardinalityFor<K> extends "many" ? true : false;
 //#endregion
-export { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, 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 };
+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, NotificationsApplicationLayout, NotificationsChannelLayout, NotificationsDelivery, NotificationsEveryoneLayout, NotificationsLayout, NotificationsLinksLayout, NotificationsMember, NotificationsOnboardingLayout, 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 };