@theholocron/cli 5.0.0-alpha.18 → 5.0.0-alpha.181

package/dist/index.mjs

@@ -1,14 +1,16 @@
 import { CARDINALITY, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, isMulti } from "./plugin/capabilities.mjs";
 import { AuthError, createResolveToken as createResolveToken$1, createRestClient } from "@theholocron/http-client";
-import { createEnvLookup } from "@theholocron/env-utils";
+import { createEnvLookup, withEnvPrefix } from "@theholocron/env-utils";
 import { Entry, findCredentials } from "@napi-rs/keyring";
-import { readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { readPackageJson } from "@theholocron/pkg-utils";
 import { loadTasksConfig } from "@theholocron/astromech/config";
 import { ConfigFileError, ConfigFileError as ConfigFileError$1, loadConfigFile } from "@theholocron/datapad";
-createEnvLookup();
+import { readGitRemote } from "@theholocron/git-utils";
+//#region src/env/env.ts
+/** Singleton env for simple global lookups throughout the CLI. */
+const env = createEnvLookup();
+withEnvPrefix(env, "HOLOCRON");
 /**
 * Create an injectable env for commands that accept a fake env in tests.
 * Pass `input.env` when available, falls back to `process.env`.
@@ -17,7 +19,7 @@ function makeEnv(source) {
 	return createEnvLookup(source);
 }
 //#endregion
-//#region src/auth/keyring.ts
+//#region src/auth/keyring/keyring.ts
 /**
 * Keyring-backed bootstrap credential store.
 *
@@ -87,7 +89,7 @@ function listStoredProviders() {
 	}
 }
 //#endregion
-//#region src/auth/auth-resolver.ts
+//#region src/auth/auth-resolver/auth-resolver.ts
 /** Wraps `createResolveToken` from `@theholocron/http` and injects the
 *  system keyring so plugins stay at a one-liner call site. */
 function createResolveToken(config) {
@@ -113,7 +115,7 @@ function createFeatureResolver(config) {
 	};
 }
 //#endregion
-//#region src/commands/setup/derived-properties.ts
+//#region src/commands/setup/derived-properties/derived-properties.ts
 /**
 * Repo archetype, in priority order:
 * 1. `*-template` repo name → `template` (independent of package shape).
@@ -184,7 +186,7 @@ function deriveCapabilities(providers) {
 	return Object.keys(providers ?? {}).sort();
 }
 /**
-* `source` + `ci` are the minimal baseline every repo `holocron setup`
+* `source` + `ci` are the minimal baseline every repo `holocron repo setup`
 * touches wires — every `holocron.config.ts` in this org already satisfies
 * this, so `non-compliant` here means drift (a provider manually removed
 * after setup), not an unmet aspirational policy. Deliberately not a richer
@@ -196,6 +198,15 @@ function deriveCompliance(capabilities) {
 	return REQUIRED_BASELINE.every((key) => capabilities.includes(key)) ? "compliant" : "non-compliant";
 }
 /**
+* The Phase B refinement `deriveCompliance()`'s own doc comment names —
+* *why* a repo is non-compliant, not just that it is. `[]` when compliant.
+* Same `REQUIRED_BASELINE` `deriveCompliance()` checks against — one
+* table, not two independently-maintained baselines.
+*/
+function missingCapabilities(capabilities) {
+	return REQUIRED_BASELINE.filter((key) => !capabilities.includes(key));
+}
+/**
 * Reads each workspace package's actual `package.json` content (not just
 * `readWorkspacePackages()`'s `{ slug, name, dir }` — `deriveProfile()`'s
 * `platform` detection needs `bin`, which that helper doesn't carry).
@@ -204,14 +215,14 @@ function deriveCompliance(capabilities) {
 */
 async function readWorkspacePackageJsons(repoRoot, workspacePackages) {
 	const results = [];
-	for (const { slug, dir = "packages" } of workspacePackages) try {
-		const raw = await readFile(join(repoRoot, dir, slug, "package.json"), "utf8");
-		results.push(JSON.parse(raw));
-	} catch {}
+	for (const { slug, dir = "packages" } of workspacePackages) {
+		const pkg = await readPackageJson(join(repoRoot, dir, slug));
+		if (pkg) results.push(pkg);
+	}
 	return results;
 }
 //#endregion
-//#region src/config/config.ts
+//#region src/config/config/config.ts
 var ConfigError = class extends Error {
 	name = "ConfigError";
 };
@@ -315,11 +326,12 @@ function resolveConfig(raw) {
 		docs,
 		env: raw.env,
 		log: raw.log,
-		telemetry: raw.telemetry
+		telemetry: raw.telemetry,
+		eslint: raw.eslint
 	};
 }
 //#endregion
-//#region src/config/compose.ts
+//#region src/config/compose/compose.ts
 function taskName(e) {
 	return typeof e === "string" ? e : e.name;
 }
@@ -407,12 +419,12 @@ function compose(...args) {
 	};
 }
 //#endregion
-//#region src/config/define-config.ts
+//#region src/config/define-config/define-config.ts
 function defineConfig(config) {
 	return config;
 }
 //#endregion
-//#region src/config/load-config.ts
+//#region src/config/load-config/load-config.ts
 /**
 * `holocron.config.{ts,js,mjs,cjs,json}` loader.
 *
@@ -424,34 +436,39 @@ function defineConfig(config) {
 * Probe order is TS-first (`.ts` → `.js` → `.mjs` → `.cjs` → `.json`) —
 * see ADR-0010 / issue #75 / #81.
 */
-const execFileAsync = promisify(execFile);
 /**
-* Read + parse + resolve `holocron.config.*` from the given directory.
+* Read + parse + resolve `holocron.config.*` starting from the given
+* directory, walking up through ancestors to the nearest `.git` boundary
+* when `cwd` itself has no match — every command is usable from any
+* subdirectory of a repo, not only its exact root (see
+* `@theholocron/datapad`'s own doc comment for the stop conditions).
 * Throws {@link ConfigFileError} when nothing is found or a file cannot
-* be loaded, or `ConfigError` when the config is invalid.
+* be loaded, or `ConfigError` when the config fails schema checks.
 */
 async function loadConfig(cwd) {
 	const found = await loadConfigFile({
 		cwd,
-		name: "holocron"
+		name: "holocron",
+		walkUp: true
 	});
 	if (!found) throw new ConfigFileError$1(`no holocron.config.{ts,js,mjs,cjs,json} found in ${cwd}. Create one — see the README for the schema.`);
 	return {
-		resolved: resolveConfig(await deriveDefaults(dirname(found.filepath), found.config)),
+		resolved: resolveConfig(await deriveDefaults(found)),
 		filepath: found.filepath
 	};
 }
-async function deriveDefaults(configDir, raw) {
-	const result = { ...raw };
+async function deriveDefaults(found) {
+	const configDir = dirname(found.filepath);
+	const result = { ...found.config };
 	if (!result.name) result.name = await readPackageJsonName(configDir) ?? basename(configDir);
 	if (result.repo && !result.repo.name) {
-		const repoName = await readGitRemote(configDir);
-		if (repoName) result.repo = {
+		const remote = await readGitRemote(configDir);
+		if (remote?.host === "github.com") result.repo = {
 			...result.repo,
-			name: repoName
+			name: remote.slug
 		};
 	}
-	const manifest = await loadTasksConfig(configDir);
+	const manifest = await loadTasksConfig(configDir, { holocron: found });
 	if (manifest.tasks) result.tasks = manifest.tasks;
 	if (manifest.syncScripts !== void 0) result.syncScripts = manifest.syncScripts;
 	if (manifest.holocronScript !== void 0) result.holocronScript = manifest.holocronScript;
@@ -460,31 +477,8 @@ async function deriveDefaults(configDir, raw) {
 	return result;
 }
 async function readPackageJsonName(dir) {
-	try {
-		const content = await readFile(join(dir, "package.json"), "utf8");
-		const pkg = JSON.parse(content);
-		return typeof pkg.name === "string" ? pkg.name.replace(/^@[^/]+\//, "") : void 0;
-	} catch {
-		return;
-	}
-}
-async function readGitRemote(dir) {
-	try {
-		const { stdout } = await execFileAsync("git", [
-			"remote",
-			"get-url",
-			"origin"
-		], { cwd: dir });
-		return parseGitRemoteUrl(stdout.trim());
-	} catch {
-		return;
-	}
-}
-function parseGitRemoteUrl(url) {
-	const httpsMatch = url.match(/github\.com\/([^/]+\/[^/]+?)(?:\.git)?$/);
-	if (httpsMatch) return httpsMatch[1];
-	const sshMatch = url.match(/github\.com:([^/]+\/[^/]+?)(?:\.git)?$/);
-	if (sshMatch) return sshMatch[1];
+	const name = (await readPackageJson(dir))?.name;
+	return name === void 0 ? void 0 : name.replace(/^@[^/]+\//, "");
 }
 //#endregion
-export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };
+export { AuthError, CARDINALITY, ConfigError, ConfigFileError, ProviderApiError, REQUIRED_CAPABILITIES, WebhookVerificationError, compose, createFeatureResolver, createResolveToken, createRestClient, defineConfig, deleteToken, deriveCapabilities, deriveCompliance, deriveProfile, deriveStack, getToken, isMulti, listStoredProviders, loadConfig, missingCapabilities, readWorkspacePackageJsons, resolveConfig, resolveEntry, resolvePluginPackage, setToken };

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;
@@ -364,9 +339,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 +391,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 +413,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 +536,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 +589,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 +622,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 +658,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 +736,46 @@ 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;
+}
+/** 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;
+}
+/** One channel in a {@link NotificationsLayout}. */
+interface NotificationsChannelLayout {
+  name: string;
+  topic?: string;
+  /**
+   * 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;
+  };
+}
+/** A declared server layout, applied idempotently by `holocron notifications setup`. */
+interface NotificationsLayout {
+  categories?: Array<{
+    name: string;
+    channels?: NotificationsChannelLayout[];
+  }>;
+  roles?: Array<{
+    name: string;
+    mentionable?: boolean;
+  }>;
+}
 interface Notifications extends ProviderIdentity {
   readonly key: "notifications";
   /**
@@ -631,6 +783,31 @@ 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): Promise<EnsuredResource>;
+  ensureChannel?(input: {
+    name: string;
+    category?: string;
+    topic?: string;
+  }): Promise<EnsuredResource>;
+  ensureWebhook?(input: {
+    channel: string;
+    name: string;
+    category?: string;
+  }): Promise<EnsureWebhookResult>;
+  ensureRole?(input: {
+    name: string;
+    mentionable?: boolean;
+  }): Promise<EnsuredResource>;
 }
 interface Analytics extends ProviderIdentity {
   readonly key: "analytics";
@@ -651,18 +828,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,7 +856,7 @@ 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.
@@ -699,12 +864,34 @@ interface Wiki extends ProviderIdentity {
    */
   proxyConfig?(): WikiProxyConfig | null;
 }
+/** Config for `Workers.deployScript()` — an arbitrary Worker, not a generated reverse-proxy. */
+interface DeployScriptConfig {
+  /** The full Worker script source — a single ES module (`export default { fetch(...) {...} }`). */
+  code: string;
+  /**
+   * Secret bindings — `env.<name>` in the deployed Worker. Values are
+   * write-only; the provider never echoes them back, here or anywhere else.
+   */
+  secrets?: Record<string, string>;
+  /**
+   * Route pattern(s) this Worker should serve (e.g.
+   * `"sentinel.theholocron.dev/*"`). Omit for a Worker reached only via
+   * its `*.workers.dev` URL.
+   */
+  routes?: string[];
+}
+interface DeployScriptResult {
+  /** The deployed script's name at the provider. */
+  scriptName: string;
+}
 /**
- * Edge Worker / reverse-proxy management capability.
+ * Edge Worker management capability.
  *
- * Deploys and manages Worker scripts that proxy traffic to a configured
- * target. Used by `setup` to wire wiki custom-domain proxies when the
- * wiki provider requires a Worker in addition to the CNAME.
+ * Deploys and manages Worker scripts. `upsertProxy` is the existing,
+ * narrower case `setup` uses to wire wiki custom-domain reverse-proxies;
+ * `deployScript` is the general case — any Worker, any code, its own
+ * secrets — for a consumer that isn't a reverse-proxy (a webhook
+ * receiver, for instance).
  */
 interface Workers extends ProviderIdentity {
   readonly key: "workers";
@@ -714,6 +901,17 @@ interface Workers extends ProviderIdentity {
    * `config.headers` on each request.
    */
   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;
@@ -731,12 +929,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, 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, NotificationsChannelLayout, NotificationsLayout, 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, WikiProvisionOpts, WikiProxyConfig, Workers, isMulti };

package/dist/plugin/capabilities.mjs

@@ -1,5 +1,5 @@
 import { ProviderApiError } from "@theholocron/http-client";
-//#region src/plugin/capabilities.ts
+//#region src/plugin/capabilities/capabilities.ts
 const CARDINALITY = {
 	source: "single",
 	ci: "single",
@@ -16,6 +16,7 @@ const CARDINALITY = {
 	analytics: "many",
 	errors: "single",
 	logs: "single",
+	monitoring: "single",
 	wiki: "single",
 	workers: "single"
 };