@theholocron/holocron-plugin-cloudflare 3.24.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-cloudflare`
+
+Cloudflare plugin for [Holocron](../cli). Implements the `dns`
+capability against the [Cloudflare v4 API](https://developers.cloudflare.com/api/).
+
+## Install
+
+<!-- prettier-ignore -->
+```bash
+pnpm add -D @theholocron/holocron-plugin-cloudflare
+
+```
+
+## Auth
+
+Token resolution order:
+
+1. `--token <TOKEN>` flag on the holocron invocation
+2. `HOLOCRON_CLOUDFLARE_TOKEN` env var
+3. `CLOUDFLARE_API_TOKEN` env var (the standard Cloudflare variable name)
+
+Generate a scoped API token at **dash.cloudflare.com/profile/api-tokens**
+with `Zone:Read` and `DNS:Edit` permissions.
+
+## Config
+
+<!-- prettier-ignore -->
+```jsonc
+{
+  "providers": {
+    "dns": ["cloudflare", { "accountId": "optional-account-id" }],
+  },
+}
+
+```
+
+- `accountId` (optional) — Cloudflare account id. Not required for DNS
+  operations; needed only if you extend the plugin to tunnel management.
+
+## What's implemented
+
+| Method         | What it does                                                                                                                                                                                                                        |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `listRecords`  | Lists all DNS records in the zone that contains the given domain. Resolves the zone by walking label-by-label from the full domain to the apex.                                                                                     |
+| `upsertRecord` | Creates a record if none matching `type + name` exists; patches the first match otherwise. When multiple same-type records exist, only the first is updated — use explicit list/delete/create for multi-TXT scenarios (SPF + DKIM). |
+| `deleteRecord` | Deletes a record by id within the zone that contains the given domain.                                                                                                                                                              |
+
+Zone ids are cached per plugin instance for the lifetime of the process.

package/dist/index.d.mts

@@ -0,0 +1,67 @@
+import { AuthError, Dns, DnsRecord, ResolveTokenInput } from "@theholocron/cli";
+import { CloudflareClient, CloudflareClientOptions, createCloudflareClient } from "@theholocron/cloudflare-client";
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/capabilities/dns.d.ts
+declare class CloudflareDns implements Dns {
+  private readonly client;
+  readonly key: "dns";
+  readonly providerName = "cloudflare";
+  private readonly zoneCache;
+  constructor(client: CloudflareClient);
+  listRecords(domain: string): Promise<DnsRecord[]>;
+  upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
+  deleteRecord(domain: string, id: string): Promise<void>;
+  /**
+   * Walk from full domain up to apex to find the Cloudflare zone.
+   * E.g. "api.staging.example.com" tries:
+   *   1. "api.staging.example.com"
+   *   2. "staging.example.com"
+   *   3. "example.com"
+   */
+  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>;
+//#endregion
+//#region src/index.d.ts
+interface CloudflarePluginOptions extends ResolveTokenInput {
+  /**
+   * Cloudflare account id. Optional for DNS operations; required only
+   * for account-scoped endpoints (tunnels, custom nameservers).
+   */
+  accountId?: string;
+  /** Override base URL for tests. */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: CloudflarePluginOptions;
+  client: CloudflareClient;
+}
+declare function createContext(options?: CloudflarePluginOptions): PluginContext;
+declare function dns(ctx: PluginContext): Dns;
+declare function createPlugin(options?: CloudflarePluginOptions): {
+  name: string;
+  capabilities: {
+    dns: () => Dns;
+  };
+};
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, type CloudflareClient, type CloudflareClientOptions, CloudflareDns, CloudflarePluginOptions, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createCloudflareClient, createContext, createPlugin, dns, resolveToken, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,123 @@
+import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
+import { createCloudflareClient } from "@theholocron/cloudflare-client";
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_CLOUDFLARE_TOKEN",
+	vendorEnvName: "CLOUDFLARE_API_TOKEN",
+	keyringService: "cloudflare",
+	errorMessage: "no Cloudflare API token found. Pass --token <TOKEN>, set HOLOCRON_CLOUDFLARE_TOKEN / CLOUDFLARE_API_TOKEN, or run: holocron auth set cloudflare <TOKEN>"
+});
+//#endregion
+//#region src/capabilities/dns.ts
+var CloudflareDns = class {
+	client;
+	key = "dns";
+	providerName = "cloudflare";
+	zoneCache = /* @__PURE__ */ new Map();
+	constructor(client) {
+		this.client = client;
+	}
+	async listRecords(domain) {
+		const zoneId = await this.resolveZone(domain);
+		return (await this.client.dns.list(zoneId)).map(mapRecord);
+	}
+	async upsertRecord(domain, record) {
+		const zoneId = await this.resolveZone(domain);
+		const existing = await this.client.dns.list(zoneId, {
+			type: record.type,
+			name: record.name
+		});
+		if (existing.length > 0) return mapRecord(await this.client.dns.update(zoneId, existing[0].id, {
+			type: record.type,
+			name: record.name,
+			content: record.content,
+			...record.ttl !== void 0 ? { ttl: record.ttl } : {}
+		}));
+		return mapRecord(await this.client.dns.create(zoneId, {
+			type: record.type,
+			name: record.name,
+			content: record.content,
+			...record.ttl !== void 0 ? { ttl: record.ttl } : {}
+		}));
+	}
+	async deleteRecord(domain, id) {
+		const zoneId = await this.resolveZone(domain);
+		await this.client.dns.delete(zoneId, id);
+	}
+	/**
+	* Walk from full domain up to apex to find the Cloudflare zone.
+	* E.g. "api.staging.example.com" tries:
+	*   1. "api.staging.example.com"
+	*   2. "staging.example.com"
+	*   3. "example.com"
+	*/
+	async resolveZone(domain) {
+		const cached = this.zoneCache.get(domain);
+		if (cached) return cached;
+		const parts = domain.split(".");
+		for (let i = 0; i < parts.length - 1; i++) {
+			const candidate = parts.slice(i).join(".");
+			const zones = await this.client.zones.list({ name: candidate });
+			if (zones.length > 0) {
+				this.zoneCache.set(domain, zones[0].id);
+				return zones[0].id;
+			}
+		}
+		throw new ProviderApiError(`No Cloudflare zone found for domain: ${domain}`, 404, void 0);
+	}
+};
+function mapRecord(raw) {
+	return {
+		id: raw.id,
+		type: raw.type,
+		name: raw.name,
+		content: raw.content,
+		ttl: raw.ttl
+	};
+}
+//#endregion
+//#region src/verify-token.ts
+async function verifyToken(token, opts = {}) {
+	const client = createCloudflareClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
+	try {
+		const result = await client.tokens.verify();
+		return {
+			ok: true,
+			subject: `token ${result.id} (${result.status})`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options = {}) {
+	return {
+		options,
+		client: createCloudflareClient({
+			token: resolveToken(options),
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
+	};
+}
+function dns(ctx) {
+	return new CloudflareDns(ctx.client);
+}
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-cloudflare",
+		capabilities: { dns: () => dns(ctx) }
+	};
+}
+const AUTH_HINT = "create an API token at https://dash.cloudflare.com/profile/api-tokens with Zone:Read and DNS:Edit permissions, then run: holocron auth set cloudflare <TOKEN>";
+//#endregion
+export { AUTH_HINT, AuthError, CloudflareDns, createCloudflareClient, createContext, createPlugin, dns, resolveToken, verifyToken };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@theholocron/holocron-plugin-cloudflare",
+  "version": "3.24.3",
+  "description": "Holocron plugin for Cloudflare. Implements the dns capability against Cloudflare's REST API — zone resolution, DNS record management.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-cloudflare#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-cloudflare"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cloudflare-client": "^1.7.1",
+    "@theholocron/cli": "3.24.4"
+  },
+  "peerDependenciesMeta": {
+    "@theholocron/cloudflare-client": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@theholocron/cloudflare-client": "^1.7.1",
+    "@theholocron/eslint-config": "^7.19.1",
+    "@theholocron/tsconfig": "^7.19.1",
+    "@theholocron/tsdown-config": "^7.19.1",
+    "@theholocron/vitest-config": "^7.19.1",
+    "@types/node": "^26",
+    "chalk": "^6.0.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.27",
+    "eslint": "^10.8.1",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.9.0",
+    "tsdown": "^0.22.14",
+    "tsx": "4.22.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@theholocron/cli": "3.24.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  }
+}