@theholocron/cli 2.0.0-alpha.5 → 2.0.0-alpha.50

package/README.md

@@ -1,3 +1,5 @@
+<!-- editorconfig-checker-disable-file -->
+
 # `@theholocron/cli`
 
 The Holocron CLI — a pluggable, capability-based orchestrator for
@@ -5,24 +7,106 @@ spinning up and operating software projects.
 
 ## Install
 
+<!-- prettier-ignore -->
 ```bash
 npm i -g @theholocron/cli@alpha
 holocron --help
+
+```
+
+## Config file
+
+Holocron reads `holocron.config.{json,js,ts}` from the project root
+(priority: json → js → ts).
+
+**JSON** (simplest):
+
+<!-- prettier-ignore -->
+```jsonc
+// holocron.config.json
+{
+  "project": { "name": "my-app" },
+  "providers": {
+    "vault": ["1password", { "vault": "my-app" }],
+    "source": "github",
+  },
+}
+
+```
+
+**JS/TS** — use `defineConfig` for autocomplete and type-checking:
+
+<!-- prettier-ignore -->
+```ts
+// holocron.config.ts
+import { defineConfig } from "@theholocron/cli";
+
+export default defineConfig({
+  project: { name: "my-app" },
+  providers: {
+    vault: ["1password", { vault: "my-app" }],
+    source: "github",
+  },
+});
+
+```
+
+### Shareable configs
+
+**Level 1 — per-capability config packages.** Reference a published
+package in any provider slot and Holocron resolves its bundled
+`{ provider, options }` automatically. Per-project options merge on
+top (project wins):
+
+<!-- prettier-ignore -->
+```ts
+providers: {
+  vault: '@acme/holocron-vault',                     // preset only
+  source: ['@acme/holocron-github', { repo: 'x' }], // preset + override
+}
+
+```
+
+A capability config package exports a `CapabilityConfigPackage` default:
+
+<!-- prettier-ignore -->
+```ts
+import type { CapabilityConfigPackage } from "@theholocron/cli";
+export default {
+  provider: "1password",
+  options: { vault: "acme-app" },
+} satisfies CapabilityConfigPackage;
+
+```
+
+**Level 2 — whole-config presets.** Because the config file can be
+JS/TS, a shared base is just an import:
+
+<!-- prettier-ignore -->
+```ts
+// holocron.config.ts
+import { acmeConfig } from "@acme/holocron-config";
+export default acmeConfig;
+
 ```
 
 ## What's in here
 
 - `src/capabilities/` — the 14 capability interfaces that providers
-	implement
-- `src/config.ts` — `holocron.config.json` parser + plugin resolution
+  implement
+- `src/config.ts` — config schema, `defineConfig`, `resolveConfig`,
+  `CapabilityConfigPackage`
+- `src/load-config.ts` — `loadConfig` — reads JSON/JS/TS config files
+- `src/define-config.ts` — `defineConfig` typed pass-through
+- `src/loader.ts` — `PluginLoader` — dynamic-imports plugins, resolves
+  capability config packages, builds the capability registry
 - `src/cli.ts` — yargs entry, dispatches subcommands
-- `src/commands/` — `setup`, `doctor`, `deploy`, `secret set`,
-	`secrets sync`, `npm publish-initial`
+- `src/commands/` — `setup`, `sync`, `doctor`, `deploy`, `secret set`,
+  `secrets sync`, `npm publish-initial`, `sync-github`, `upgrade node`,
+  `plugin create`, `auth`
 
 ## Status
 
-**`v2.0.0-alpha.0`** — published on npm under the `alpha` dist-tag.
-[Release notes](https://github.com/theholocron/holocron/releases/tag/v2.0.0-alpha.0).
-Design in
-[`.notes/tech-architecture.spec.md`](../../.notes/tech-architecture.spec.md).
-APIs may still shift before stable v2.0.0.
+Published on npm under the `alpha` dist-tag. APIs may still shift before
+stable v2.0.0. Design in
+[`.notes/archive/tech-architecture.spec.md`](../../.notes/archive/tech-architecture.spec.md).

package/dist/capabilities/index.d.mts

@@ -1,2 +1,552 @@
-import { $ as StorageBranch, A as EnvironmentReviewer, B as ParseWebhookInput, C as DeploymentTarget, D as DnsRecordType, E as DnsRecord, F as LifecycleResult, G as RepoSettings, H as ProviderIdentity, I as LifecycleSlot, J as SecretScope, K as ResolvedCapability, L as NormalizedAuthUser, M as Issue, N as IssueSearchFilter, O as EnsureResult, P as Issues, Q as Storage, R as Notifications, S as DeploymentRecord, T as Dns, U as REQUIRED_CAPABILITIES, V as ProviderApiError, W as RepoRef, X as Source, Y as Secrets, Z as StatusCategory, _ as ConnectionStringOptions, a as AuthEventType, at as WebhookDashboardInfo, b as DeploymentProject, c as CARDINALITY, d as Cardinality, et as Tooling, f as CardinalityFor, g as CiRunStatus, h as CiRunFilter, i as AuthEvent, it as Vault, j as Environments, k as Environment, l as CapabilityImpls, m as CiRun, n as Auth, nt as TrackerDoctorReport, o as AuthIdentity, ot as WebhookVerificationError, p as Ci, q as Ruleset, r as AuthDescription, rt as TrackerUser, s as AuthUser, st as isMulti, t as Analytics, tt as ToolingDoctorReport, u as CapabilityKey, v as CreateAuthUserInput, w as DeploymentTrigger, x as DeploymentProjectSettings, y as Deployment, z as Observability } from "../index-jxPVFH7-.mjs";
-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, Issue, IssueSearchFilter, Issues, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti };
+import { ProviderApiError } from "@theholocron/http-client";
+
+//#region src/capabilities/index.d.ts
+/**
+ * Capability interfaces — the contracts that providers implement.
+ *
+ * Each capability has a stable key (`'source'`, `'ci'`, …) and a
+ * cardinality (`'single'` = one provider; `'many'` = several active
+ * at once). The cardinality is part of the type contract via
+ * `CardinalityFor<K>` so config resolution + command code can branch
+ * statically.
+ *
+ * See `.notes/tech-architecture.spec.md` for the design narrative
+ * (status: proposed, issue: #74).
+ */
+type CapabilityKey = "source" | "ci" | "secrets" | "environments" | "issues" | "deployment" | "storage" | "auth" | "vault" | "dns" | "tooling" | "notifications" | "analytics" | "observability";
+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 observability: "many";
+};
+/**
+ * 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;
+}
+interface Ruleset {
+  id: number;
+  name: string;
+  enforcement: "active" | "evaluate" | "disabled";
+  target?: string;
+}
+interface RepoSettings {
+  allow_squash_merge?: boolean;
+  allow_merge_commit?: boolean;
+  allow_rebase_merge?: boolean;
+  allow_auto_merge?: boolean;
+  /** Always suggest updating PR branches when the base branch has new commits. */
+  allow_update_branch?: boolean;
+  delete_branch_on_merge?: boolean;
+  default_branch?: string;
+  has_issues?: boolean;
+  has_discussions?: boolean;
+  has_projects?: boolean;
+  has_wiki?: boolean;
+}
+interface RepoRef {
+  owner: string;
+  name: string;
+  defaultBranch: string;
+}
+interface LabelDef {
+  readonly name: string;
+  readonly color: string;
+  readonly description: string;
+}
+interface Source extends ProviderIdentity {
+  readonly key: "source";
+  /** Auth sanity-check. Throws ProviderApiError on auth failure. */
+  whoami(): Promise<{
+    login: string;
+  }>;
+  getRepo(): Promise<RepoRef>;
+  listRulesets(): Promise<Ruleset[]>;
+  createRuleset(payload: Record<string, unknown>): Promise<Ruleset>;
+  updateRuleset(id: number, payload: Record<string, unknown>): Promise<Ruleset>;
+  updateRepoSettings(settings: RepoSettings): Promise<void>;
+  /**
+   * Classic branch protection — fallback for private repos on free plans
+   * where the Rulesets API (requires Team+) returns 403.
+   */
+  protectBranch(branch: string, payload: Record<string, unknown>): Promise<void>;
+  enableVulnerabilityAlerts(): Promise<void>;
+  enableAutomatedSecurityFixes(): Promise<void>;
+  enableSecretScanning(): Promise<void>;
+  enablePrivateVulnerabilityReporting(): Promise<void>;
+  /**
+   * Enables the dependency graph and automatic dependency snapshot
+   * submission. Also enables secret-scanning validity checks and
+   * non-provider pattern detection — these require GitHub Advanced
+   * Security at the org level; the call is accepted but may be a no-op
+   * until that is configured.
+   */
+  enableDependencyGraph(): Promise<void>;
+  /**
+   * Enables CodeQL default setup with the extended query suite and
+   * `threat_model: all` (scans both remote and local exploit paths).
+   * Triggers a new analysis run; returns the run id.
+   */
+  enableCodeScanning(): Promise<string>;
+  /**
+   * Disables CodeQL default setup. Required when the repo uses an advanced
+   * CodeQL workflow instead — GitHub rejects SARIF from advanced workflows
+   * while default setup is active.
+   */
+  disableDefaultCodeScanning(): Promise<void>;
+  listWorkflowFiles(): Promise<string[]>;
+  readWorkflowFile(name: string): Promise<string | null>;
+  writeWorkflowFile(name: string, contents: string): Promise<void>;
+  removeWorkflowFile(name: string): Promise<void>;
+  /**
+   * Write an arbitrary file relative to the repo root. Used for
+   * provisioning config files that live outside `.github/workflows/`
+   * (e.g. `.github/dependabot.yml`).
+   */
+  writeRepoFile(path: string, contents: string): Promise<void>;
+  /**
+   * Idempotently sync repo labels to a canonical set. Creates missing
+   * labels, patches color/description drift, deletes stale labels.
+   * Optional — providers that have no label concept omit this.
+   */
+  syncLabels?(canonical: ReadonlyArray<LabelDef>, stale: ReadonlyArray<string>): Promise<string>;
+  /**
+   * Set org-level custom property values on the repo.
+   * Optional — providers that don't support custom properties omit this.
+   */
+  syncProperties?(values: Record<string, string>): Promise<string>;
+  /**
+   * Replace the repo's topic set with the supplied list.
+   * Optional — providers that don't support topics omit this.
+   */
+  syncTopics?(topics: string[]): Promise<string>;
+}
+type CiRunStatus = "queued" | "in_progress" | "completed" | "cancelled" | "failure" | "success" | "skipped";
+interface CiRun {
+  id: string | number;
+  workflowName: string;
+  branch: string;
+  sha: string;
+  status: CiRunStatus;
+  url: string;
+  startedAt: string;
+  completedAt?: string;
+}
+interface CiRunFilter {
+  branch?: string;
+  status?: CiRunStatus;
+  limit?: number;
+}
+interface Ci extends ProviderIdentity {
+  readonly key: "ci";
+  listRuns(filter?: CiRunFilter): Promise<CiRun[]>;
+  getRun(id: string | number): Promise<CiRun>;
+}
+type SecretScope = {
+  kind: "repo";
+} | {
+  kind: "environment";
+  name: string;
+} | {
+  kind: "organization";
+  name: string;
+};
+interface Secrets extends ProviderIdentity {
+  readonly key: "secrets";
+  /** List secret NAMES (not values) at the given scope. */
+  listSecrets(scope: SecretScope): Promise<string[]>;
+  /** Idempotent upsert. Adapter handles encryption. */
+  setSecret(scope: SecretScope, name: string, value: string): Promise<void>;
+  deleteSecret(scope: SecretScope, name: string): Promise<void>;
+}
+interface EnvironmentReviewer {
+  type: "User" | "Team";
+  /** Numeric id — GitHub's reviewer API silently ignores login strings. */
+  id: number;
+}
+interface Environment {
+  name: string;
+  reviewers?: EnvironmentReviewer[];
+  waitTimer?: number;
+  preventSelfReview?: boolean;
+}
+interface Environments extends ProviderIdentity {
+  readonly key: "environments";
+  listEnvironments(): Promise<Environment[]>;
+  upsertEnvironment(env: Environment): Promise<void>;
+  deleteEnvironment(name: string): Promise<void>;
+}
+type LifecycleSlot = "inProgress" | "inReview" | "done";
+type StatusCategory = "open" | "in-progress" | "in-review" | "done" | "other";
+interface TrackerUser {
+  id: string;
+  displayName: string;
+  emailAddress?: string;
+}
+interface Issue {
+  /** Human-readable key — "#42" for GitHub, "RANDO-42" for Jira. */
+  key: string;
+  /** Internal opaque id. */
+  id: string;
+  summary: string;
+  body?: string;
+  status: string;
+  statusCategory: StatusCategory;
+  assignee: TrackerUser | null;
+  updated: string;
+  url?: string;
+}
+interface IssueSearchFilter {
+  /** Restrict to issues assigned to a specific id, or 'currentUser'. */
+  assignee?: string | "currentUser";
+  /** Exclude issues in the `done` category. */
+  openOnly?: boolean;
+  /** Max number of issues to return. Adapters apply a sensible default. */
+  limit?: number;
+}
+interface LifecycleResult {
+  /** False when no API write happened (already at target state). */
+  transitioned: boolean;
+  /** Status name the issue is in after this call. */
+  status: string;
+  /** Adapter-specific note (e.g., "label set" / "closed (completed)"). */
+  via?: string;
+}
+interface TrackerDoctorReport {
+  /** "Authenticated as ..." subject for the spinner. */
+  authedAs: string;
+  /** Free-form "Project: RANDO" / "Repo: rando-id/rando" identifier. */
+  projectLabel: string;
+  /** Status values the adapter exposes. */
+  statuses: Array<{
+    name: string;
+    category: StatusCategory;
+  }>;
+  /**
+   * Per-lifecycle-slot readiness check. `resolved` indicates whether
+   * the configured value actually maps to something the tracker
+   * recognizes; the `note` is the rendered explanation.
+   */
+  lifecycle: Array<{
+    slot: LifecycleSlot;
+    value: string | null;
+    resolved: boolean;
+    note: string;
+  }>;
+}
+interface Issues extends ProviderIdentity {
+  readonly key: "issues";
+  /** Currently-authenticated user. */
+  getMyself(): Promise<TrackerUser>;
+  search(filter: IssueSearchFilter): Promise<Issue[]>;
+  get(key: string): Promise<Issue>;
+  create(input: {
+    summary: string;
+    body?: string;
+    labels?: string[]; /** Numeric id or exact title (case-insensitive). */
+    milestone?: string;
+  }): Promise<{
+    key: string;
+  }>;
+  /** Idempotent — `transitioned: false` if the issue is already at the target. */
+  transition(key: string, slot: LifecycleSlot): Promise<LifecycleResult>;
+  comment(key: string, body: string): Promise<void>;
+  doctor(): Promise<TrackerDoctorReport>;
+}
+/** Env-var scope on the deploy platform. */
+type DeploymentTarget = "development" | "preview" | "production";
+/**
+ * Named deployment trigger target — `undefined` means a branch
+ * preview (no named environment).
+ */
+type DeploymentTrigger = "production" | "staging";
+interface DeploymentProject {
+  id: string;
+  name: string;
+  framework?: string;
+  /** True when the project is linked to a Git provider. */
+  gitLinked?: boolean;
+  rootDirectory?: string | null;
+}
+interface DeploymentProjectSettings {
+  previewDeploymentsDisabled?: boolean;
+  /** Vercel-specific: whether the GitHub integration creates deployments
+   * for every push (false → only on-demand triggers). */
+  gitProviderCreateDeployments?: boolean;
+}
+interface DeploymentRecord {
+  id: string;
+  url: string;
+  /** Branch this deployment was made from (null if not git-sourced). */
+  branch: string | null;
+  /** Named environment if one was targeted; undefined for branch previews. */
+  target?: DeploymentTrigger;
+  status: "queued" | "building" | "ready" | "error" | "cancelled";
+}
+interface Deployment extends ProviderIdentity {
+  readonly key: "deployment";
+  listProjects(): Promise<DeploymentProject[]>;
+  /** Create if missing, otherwise return existing. Idempotent. */
+  ensureProject(input: {
+    name: string;
+    framework?: string; /** "owner/repo" — passed when linking to a Git provider. */
+    repo?: string;
+    rootDirectory?: string;
+  }): Promise<DeploymentProject>;
+  updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
+  listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
+  setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
+  /**
+   * Kick off a deployment of the given branch. Omit `target` for a
+   * branch preview; pass `'production'` / `'staging'` to deploy into
+   * a named environment.
+   */
+  triggerDeployment(input: {
+    projectId: string;
+    branch: string;
+    target?: DeploymentTrigger;
+  }): Promise<DeploymentRecord>;
+  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
+}
+interface StorageBranch {
+  id: string;
+  name: string;
+  /** Parent branch id; null for the root/main branch. */
+  parentId: string | null;
+  createdAt: string;
+}
+interface ConnectionStringOptions {
+  /** Use the pooled (PgBouncer) URL when available. Defaults to false. */
+  pooled?: boolean;
+}
+interface Storage extends ProviderIdentity {
+  readonly key: "storage";
+  /**
+   * Connection string for the given scope. Scope is provider-specific:
+   *
+   *   - branch-based providers (Neon, PlanetScale): scope = branch
+   *     name or id
+   *   - flat providers (single Postgres instance): scope is ignored
+   *
+   * Callers (or the orchestrator) decide how a deploy target maps to
+   * a scope; the storage plugin doesn't own that mapping.
+   */
+  getConnectionString(scope: string, options?: ConnectionStringOptions): Promise<string>;
+  listBranches?(): Promise<StorageBranch[]>;
+  createBranch?(input: {
+    name: string;
+    from?: string;
+  }): Promise<StorageBranch>;
+  destroyBranch?(branch: string): Promise<void>;
+  /** Restore one branch to match another (e.g., reset preview → main). */
+  resetBranch?(input: {
+    branch: string;
+    from: string;
+  }): Promise<void>;
+  /**
+   * Provider-specific feature toggle. For Postgres providers this is
+   * `CREATE EXTENSION IF NOT EXISTS ...` per branch.
+   */
+  enableExtension?(input: {
+    branch: string;
+    extension: string;
+  }): Promise<void>;
+}
+interface AuthDescription {
+  provider: string;
+  /** Env-var names the app needs at runtime (CLERK_PUBLISHABLE_KEY, etc.). */
+  envKeys: string[];
+}
+interface AuthIdentity {
+  provider: string;
+  /** Provider-specific health signal (user count, role, account name, etc.). */
+  details?: Record<string, unknown>;
+}
+interface AuthUser {
+  id: string;
+  email: string;
+}
+interface CreateAuthUserInput {
+  email: string;
+  password: string;
+  firstName?: string;
+  lastName?: string;
+}
+interface WebhookDashboardInfo {
+  url: string;
+}
+interface Auth extends ProviderIdentity {
+  readonly key: "auth";
+  /** Env-var keys the runtime app needs. */
+  describe(): Promise<AuthDescription>;
+  /** Reachability probe — proves the configured key works. */
+  whoami(): Promise<AuthIdentity>;
+  /** Idempotent webhook backend provisioning (Clerk: Svix app). */
+  ensureWebhookApp?(): Promise<{
+    alreadyExists: boolean;
+  }>;
+  /** Deep-link to the provider's webhook config dashboard. */
+  getWebhookDashboardUrl?(): Promise<WebhookDashboardInfo>;
+  /** Seed a user (test fixtures, admin bootstrap). */
+  createUser?(input: CreateAuthUserInput): Promise<AuthUser>;
+  /** Wire the auth provider's webhook into the project's repo. */
+  syncWebhook?(input: {
+    repo: string;
+    secretRef: string;
+  }): Promise<void>;
+}
+type AuthEventType = "user.created" | "user.updated" | "user.deleted";
+interface NormalizedAuthUser {
+  id: string;
+  email: string;
+  firstName?: string | null;
+  lastName?: string | null;
+  /** Provider-native fields preserved verbatim for consumers that need them. */
+  raw?: Record<string, unknown>;
+}
+interface AuthEvent {
+  type: AuthEventType;
+  user: NormalizedAuthUser;
+  /** ISO timestamp of when the event occurred. */
+  occurredAt: string;
+}
+interface ParseWebhookInput {
+  /** Raw request body (string or Buffer). */
+  body: string | Buffer;
+  /** Incoming HTTP headers — needed for signature verification. */
+  headers: Record<string, string | string[] | undefined>;
+  /** 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;
+}
+interface Vault extends ProviderIdentity {
+  readonly key: "vault";
+  /**
+   * Read a secret by reference. The reference format is
+   * provider-specific (1P: "op://Vault/Item/field"; HashiCorp Vault:
+   * "kv/path#field"; etc.). Adapters validate the reference shape.
+   */
+  read(reference: string): Promise<string>;
+  /** Write or update a secret. */
+  write(reference: string, value: string): Promise<void>;
+  /** List secret keys available to the project. */
+  list(): Promise<string[]>;
+  /**
+   * Optional environment notion within the vault (e.g., 1P
+   * Environments — named KEY=VALUE bundles). Adapters without
+   * environments return [].
+   */
+  environments?(): Promise<string[]>;
+  /**
+   * Optional bulk read of an environment's KEY=VALUE pairs. Powers
+   * the `holocron secrets sync` flow where the orchestrator pulls a
+   * whole environment from the vault then fans the values out to
+   * destinations (CI secrets, deployment env vars, local .env).
+   */
+  readEnvironment?(environmentId: string): Promise<Record<string, string>>;
+  /**
+   * Optional — create the top-level project container in the vault
+   * if it does not exist. Idempotent: `alreadyExists: true` when the
+   * project was already there. Providers whose data model has no
+   * project notion (or that gate this behind a paid tier) omit this.
+   */
+  ensureProject?(name: string): Promise<EnsureResult>;
+  /**
+   * Optional — create a named environment/config inside a project
+   * (e.g., Doppler config `dev` / `stg` / `prd`). Idempotent.
+   * Providers whose data model has a single flat namespace omit this.
+   */
+  ensureEnvironment?(project: string, name: string): Promise<EnsureResult>;
+}
+type DnsRecordType = "A" | "AAAA" | "CNAME" | "TXT" | "MX" | "NS" | "SRV" | "CAA";
+interface DnsRecord {
+  id?: string;
+  type: DnsRecordType;
+  name: string;
+  content: string;
+  ttl?: number;
+  priority?: number;
+}
+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>;
+}
+interface ToolingDoctorReport {
+  ok: boolean;
+  message: string;
+}
+interface Tooling extends ProviderIdentity {
+  readonly key: "tooling";
+  /** Sync the tool's authoritative state from the repo. */
+  sync(): Promise<void>;
+  doctor(): Promise<ToolingDoctorReport>;
+}
+interface Notifications extends ProviderIdentity {
+  readonly key: "notifications";
+  /**
+   * Send a message. `channel` is provider-specific (Slack channel id,
+   * Discord webhook url-name, etc.); adapters resolve from config.
+   */
+  send(channel: string, message: string): Promise<void>;
+}
+interface Analytics extends ProviderIdentity {
+  readonly key: "analytics";
+  describe(): Promise<{
+    provider: string;
+    dsnEnvKey: string;
+  }>;
+}
+interface Observability extends ProviderIdentity {
+  readonly key: "observability";
+  describe(): Promise<{
+    provider: string;
+    dsnEnvKey: string;
+  }>;
+}
+interface CapabilityImpls {
+  source: Source;
+  ci: Ci;
+  secrets: Secrets;
+  environments: Environments;
+  issues: Issues;
+  deployment: Deployment;
+  storage: Storage;
+  auth: Auth;
+  vault: Vault;
+  dns: Dns;
+  tooling: Tooling;
+  notifications: Notifications;
+  analytics: Analytics;
+  observability: Observability;
+}
+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];
+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, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti };