@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.12 → 5.0.0-alpha.121

package/README.md

@@ -2,8 +2,9 @@
 
 # `@theholocron/holocron-plugin-cloudflare`
 
-Cloudflare plugin for [Holocron](../cli). Implements the `dns` and `deployment`
-capabilities against the [Cloudflare v4 API](https://developers.cloudflare.com/api/).
+Cloudflare plugin for [Holocron](../cli). Implements the `dns`, `deployment`,
+and `workers` capabilities against the
+[Cloudflare v4 API](https://developers.cloudflare.com/api/).
 
 ## Install
 
@@ -40,12 +41,15 @@ Generate a scoped API token at **dash.cloudflare.com/profile/api-tokens**.
     // Cloudflare Pages deployments (requires accountId)
     // accountId falls back to CLOUDFLARE_ACCOUNT_ID env var when omitted
     "deployment": "cloudflare",
+
+    // Workers deployment (also requires accountId)
+    "workers": "cloudflare",
   },
 }
 
 ```
 
-Both capabilities can be enabled together:
+Any combination of capabilities can be enabled together:
 
 <!-- prettier-ignore -->
 ```jsonc
@@ -53,12 +57,15 @@ Both capabilities can be enabled together:
   "providers": {
     "dns": "cloudflare",
     "deployment": "cloudflare",
+    "workers": "cloudflare",
   },
 }
 
 ```
 
-The `deployment` capability is only exposed when `accountId` is resolvable — either passed explicitly in options or set via the `CLOUDFLARE_ACCOUNT_ID` env var.
+The `deployment` and `workers` capabilities are only exposed when `accountId`
+is resolvable — either passed explicitly in options or set via the
+`CLOUDFLARE_ACCOUNT_ID` env var.
 
 ## `dns` capability
 
@@ -83,6 +90,20 @@ Manages [Cloudflare Pages](https://developers.cloudflare.com/pages/) projects. U
 | `triggerDeployment`     | Triggers a new Pages deployment from the latest production branch commit.                                               |
 | `updateProjectSettings` | Updates project-level settings (currently a no-op; CF Pages REST API has no direct settings endpoint for these fields). |
 
+## `workers` capability
+
+Deploys and manages [Workers](https://developers.cloudflare.com/workers/) scripts.
+
+| Method         | What it does                                                                                                                                                                                                                      |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `upsertProxy`  | Deploys a generated reverse-proxy Worker forwarding `hostname/*` to `config.target`, injecting `config.headers`. Used by `setup` to wire wiki custom-domain proxies when the wiki provider requires one in addition to the CNAME. |
+| `deployScript` | Deploys (or updates) an arbitrary Worker script — the caller's own code, not a generated proxy — with optional secret bindings and route patterns. For a consumer that isn't a reverse-proxy, e.g. a webhook receiver.            |
+
+Both methods are idempotent: re-running with the same inputs makes no
+route-write call when nothing changed. Zone ids are cached per plugin
+instance for the lifetime of the process — the `workers` capability's own
+cache, separate from `dns`'s.
+
 ### Preview deployment setup
 
 When `preview: true` (or `preview: { project, domain }`) is set in a repo's deploy config, `holocron setup` calls:

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AuthError, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, ResolveTokenInput, WikiProxyConfig, Workers } from "@theholocron/cli";
-import { CloudflareClient, CloudflareClientOptions, CloudflareClientOptions as CloudflareClientOptions$1, createCloudflareClient } from "@theholocron/cloudflare-client";
+import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, WikiProxyConfig, Workers } from "@theholocron/cli";
+import { CloudflareClient, CloudflareClient as CloudflareClient$1, CloudflareClientOptions, createCloudflareClient } from "@theholocron/cloudflare-client";
 //#region src/auth.d.ts
 declare const resolveToken: (input?: ResolveTokenInput) => string;
 //#endregion
@@ -28,7 +28,7 @@ declare class CloudflareDeployment implements Deployment {
   getDeployment(deploymentId: string): Promise<DeploymentRecord>;
   listPreviewDeployments(projectId: string, branch: string): Promise<DeploymentRecord[]>;
   deletePreviewDeployments(projectId: string, deploymentIds: string[]): Promise<number>;
-  ensureCustomDomain(projectId: string, hostname: string): Promise<void>;
+  ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
   private getProjectByName;
 }
 //#endregion
@@ -53,51 +53,26 @@ declare class CloudflareDns implements Dns {
 }
 //#endregion
 //#region src/capabilities/workers.d.ts
-interface ZonesClient {
-  list(query?: {
-    name?: string;
-    per_page?: number;
-  }): Promise<Array<{
-    id: string;
-  }>>;
-}
 declare class CloudflareWorkers implements Workers {
-  private readonly zones;
+  private readonly client;
   private readonly accountId;
   readonly key: "workers";
   readonly providerName = "cloudflare";
   private readonly zoneCache;
-  private readonly baseUrl;
-  private readonly fetchImpl;
-  /** Memoized token thunk — resolved on the first authenticated request. */
-  private readonly token;
-  constructor(zones: () => ZonesClient, accountId: string, opts: {
-    token: () => string;
-  } & Pick<CloudflareClientOptions$1, "baseUrl" | "fetch">);
+  constructor(client: () => Pick<CloudflareClient$1, "workers" | "zones">, accountId: string);
   upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
-  private putScript;
-  private listRoutes;
-  private createRoute;
-  private updateRoute;
-  private cfRequest;
+  deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
+  /** Idempotent create-or-update for one route pattern — shared by both public methods. */
+  private upsertRoute;
   private resolveZone;
 }
 //#endregion
 //#region src/verify-token.d.ts
-interface VerifyTokenSuccess {
-  ok: true;
-  subject: string;
-}
-interface VerifyTokenFailure {
-  ok: false;
-  message: string;
-}
-type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
 interface VerifyTokenOptions {
   baseUrl?: string;
   fetch?: typeof fetch;
 }
-declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
 //#endregion
 //#region src/index.d.ts
 interface CloudflarePluginOptions extends ResolveTokenInput {

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
 import { createCloudflareClient } from "@theholocron/cloudflare-client";
+import { errorMessage } from "@theholocron/misc-utils";
 //#region src/auth.ts
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_CLOUDFLARE_TOKEN",
@@ -74,8 +75,9 @@ var CloudflareDeployment = class {
 		return deploymentIds.length;
 	}
 	async ensureCustomDomain(projectId, hostname) {
-		if ((await this.client().pages.listDomains(this.accountId, projectId)).some((d) => d.name === hostname)) return;
+		if ((await this.client().pages.listDomains(this.accountId, projectId)).some((d) => d.name === hostname)) return null;
 		await this.client().pages.addDomain(this.accountId, projectId, hostname);
+		return null;
 	}
 	async getProjectByName(name) {
 		try {
@@ -187,87 +189,35 @@ function mapRecord(raw) {
 //#endregion
 //#region src/capabilities/workers.ts
 var CloudflareWorkers = class {
-	zones;
+	client;
 	accountId;
 	key = "workers";
 	providerName = "cloudflare";
 	zoneCache = /* @__PURE__ */ new Map();
-	baseUrl;
-	fetchImpl;
-	/** Memoized token thunk — resolved on the first authenticated request. */
-	token;
-	constructor(zones, accountId, opts) {
-		this.zones = zones;
+	constructor(client, accountId) {
+		this.client = client;
 		this.accountId = accountId;
-		this.token = opts.token;
-		this.baseUrl = opts.baseUrl ?? "https://api.cloudflare.com/client/v4";
-		this.fetchImpl = opts.fetch ?? globalThis.fetch;
 	}
 	async upsertProxy(hostname, config) {
 		const scriptName = hostnameToScriptName(hostname);
 		const script = generateProxyScript(config);
-		await this.putScript(scriptName, script);
-		const zoneId = await this.resolveZone(hostname);
-		const pattern = `${hostname}/*`;
-		const existing = (await this.listRoutes(zoneId)).find((r) => r.pattern === pattern);
-		if (existing) {
-			if (existing.script !== scriptName) await this.updateRoute(zoneId, existing.id, pattern, scriptName);
-		} else await this.createRoute(zoneId, pattern, scriptName);
-	}
-	async putScript(scriptName, script) {
-		const form = new FormData();
-		form.append("metadata", new Blob([JSON.stringify({
-			main_module: "index.js",
-			compatibility_date: "2025-08-31"
-		})], { type: "application/json" }));
-		form.append("index.js", new Blob([script], { type: "application/javascript+module" }), "index.js");
-		const path = `/accounts/${this.accountId}/workers/scripts/${encodeURIComponent(scriptName)}`;
-		const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
-			method: "PUT",
-			headers: { authorization: `Bearer ${this.token()}` },
-			body: form
-		});
-		if (!res.ok) {
-			const body = await res.text().catch(() => "");
-			throw new ProviderApiError(`Cloudflare PUT ${path} → ${res.status}`, res.status, body);
-		}
-	}
-	listRoutes(zoneId) {
-		return this.cfRequest("GET", `/zones/${zoneId}/workers/routes`);
-	}
-	createRoute(zoneId, pattern, script) {
-		return this.cfRequest("POST", `/zones/${zoneId}/workers/routes`, {
-			pattern,
-			script
-		});
+		await this.client().workers.putScript(this.accountId, scriptName, script);
+		await this.upsertRoute(`${hostname}/*`, scriptName);
 	}
-	updateRoute(zoneId, routeId, pattern, script) {
-		return this.cfRequest("PUT", `/zones/${zoneId}/workers/routes/${routeId}`, {
-			pattern,
-			script
-		});
+	async deployScript(name, config) {
+		await this.client().workers.putScript(this.accountId, name, config.code);
+		for (const [secretName, value] of Object.entries(config.secrets ?? {})) await this.client().workers.putSecret(this.accountId, name, secretName, value);
+		for (const pattern of config.routes ?? []) await this.upsertRoute(pattern, name);
+		return { scriptName: name };
 	}
-	async cfRequest(method, path, body) {
-		const headers = {
-			authorization: `Bearer ${this.token()}`,
-			accept: "application/json"
-		};
-		const init = {
-			method,
-			headers
-		};
-		if (body !== void 0) {
-			headers["content-type"] = "application/json";
-			init.body = JSON.stringify(body);
-		}
-		const res = await this.fetchImpl(`${this.baseUrl}${path}`, init);
-		if (!res.ok) {
-			const text = await res.text().catch(() => "");
-			throw new ProviderApiError(`Cloudflare ${method} ${path} → ${res.status}`, res.status, text);
-		}
-		const envelope = await res.json();
-		if (!envelope.success) throw new ProviderApiError(`Cloudflare ${method} ${path} returned success:false`, 0, JSON.stringify(envelope.errors));
-		return envelope.result;
+	/** Idempotent create-or-update for one route pattern — shared by both public methods. */
+	async upsertRoute(pattern, scriptName) {
+		const hostname = pattern.split("/")[0];
+		const zoneId = await this.resolveZone(hostname);
+		const existing = (await this.client().workers.listRoutes(zoneId)).find((r) => r.pattern === pattern);
+		if (existing) {
+			if (existing.script !== scriptName) await this.client().workers.updateRoute(zoneId, existing.id, pattern, scriptName);
+		} else await this.client().workers.createRoute(zoneId, pattern, scriptName);
 	}
 	async resolveZone(domain) {
 		const cached = this.zoneCache.get(domain);
@@ -275,7 +225,7 @@ var CloudflareWorkers = class {
 		const parts = domain.split(".");
 		for (let i = 0; i < parts.length - 1; i++) {
 			const candidate = parts.slice(i).join(".");
-			const zones = await this.zones().list({ name: candidate });
+			const zones = await this.client().zones.list({ name: candidate });
 			if (zones.length > 0) {
 				this.zoneCache.set(domain, zones[0].id);
 				return zones[0].id;
@@ -325,7 +275,7 @@ async function verifyToken(token, opts = {}) {
 	} catch (err) {
 		return {
 			ok: false,
-			message: err instanceof Error ? err.message : String(err)
+			message: errorMessage(err)
 		};
 	}
 }
@@ -359,11 +309,7 @@ function deployment(ctx) {
 }
 function workersCapability(ctx) {
 	if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Workers — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
-	return new CloudflareWorkers(() => ctx.client().zones, ctx.options.accountId, {
-		token: ctx.token,
-		baseUrl: ctx.options.baseUrl,
-		fetch: ctx.options.fetch
-	});
+	return new CloudflareWorkers(ctx.client, ctx.options.accountId);
 }
 function createPlugin(options = {}) {
 	const ctx = createContext(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-cloudflare",
-  "version": "5.0.0-alpha.12",
+  "version": "5.0.0-alpha.121",
   "description": "Holocron plugin for Cloudflare. Implements the dns capability against Cloudflare's REST API — zone resolution, DNS record management.",
   "keywords": [
     "cloudflare",
@@ -30,11 +30,13 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/cloudflare-client": "^1.14.2",
-    "@theholocron/eslint-config": "^8.0.0",
-    "@theholocron/tsconfig": "^8.0.0",
-    "@theholocron/tsdown-config": "^8.0.0",
-    "@theholocron/vitest-config": "^8.0.0",
+    "@theholocron/cloudflare-client": "^1.38.0",
+    "@theholocron/eslint-config": "^8.7.0",
+    "@theholocron/http-client": "^1.38.0",
+    "@theholocron/misc-utils": "^1.9.2",
+    "@theholocron/tsconfig": "^8.7.0",
+    "@theholocron/tsdown-config": "^8.7.0",
+    "@theholocron/vitest-config": "^8.7.0",
     "@types/node": "^26",
     "@vitest/coverage-v8": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",
@@ -46,11 +48,12 @@
     "tsx": "4.23.12",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@theholocron/cli": "5.0.0-alpha.12"
+    "@theholocron/cli": "5.0.0-alpha.121"
   },
   "peerDependencies": {
-    "@theholocron/cloudflare-client": "^1.14.2",
-    "@theholocron/cli": "5.0.0-alpha.12"
+    "@theholocron/cloudflare-client": "^1.38.0",
+    "@theholocron/misc-utils": "^1.9.2",
+    "@theholocron/cli": "5.0.0-alpha.121"
   },
   "peerDependenciesMeta": {
     "@theholocron/cloudflare-client": {}