@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.27 → 5.0.0-alpha.271

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -79,7 +79,7 @@ Zone ids are cached per plugin instance for the lifetime of the process.
79
79
 
80
80
  ## `deployment` capability
81
81
 
82
- Manages [Cloudflare Pages](https://developers.cloudflare.com/pages/) projects. Used by `holocron setup` to provision per-PR preview deployments.
82
+ Manages [Cloudflare Pages](https://developers.cloudflare.com/pages/) projects. Used by `holocron repo setup` to provision per-PR preview deployments.
83
83
 
84
84
  | Method | What it does |
85
85
  | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
@@ -106,7 +106,7 @@ cache, separate from `dns`'s.
106
106
 
107
107
  ### Preview deployment setup
108
108
 
109
- When `preview: true` (or `preview: { project, domain }`) is set in a repo's deploy config, `holocron setup` calls:
109
+ When `preview: true` (or `preview: { project, domain }`) is set in a repo's deploy config, `holocron repo setup` calls:
110
110
 
111
111
  1. `ensureProject` — creates `<org>-preview` if it doesn't exist
112
112
  2. `ensureCustomDomain` — attaches `*.<domain>` to the project
package/dist/index.d.mts CHANGED
@@ -1,10 +1,9 @@
1
- import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, ResolveTokenInput, WikiProxyConfig, Workers } from "@theholocron/cli";
1
+ import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, WikiProxyConfig, Workers } from "@theholocron/cli";
2
2
  import { CloudflareClient, CloudflareClient as CloudflareClient$1, CloudflareClientOptions, createCloudflareClient } from "@theholocron/cloudflare-client";
3
- //#region src/auth.d.ts
4
- declare const resolveToken: (input?: ResolveTokenInput) => string;
5
- //#endregion
6
- //#region src/capabilities/deployment.d.ts
7
- declare class CloudflareDeployment implements Deployment {
3
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
4
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
5
+ export declare const tokens: PluginToken[];
6
+ export declare class CloudflareDeployment implements Deployment {
8
7
  private readonly client;
9
8
  private readonly accountId;
10
9
  readonly key: "deployment";
@@ -28,12 +27,10 @@ declare class CloudflareDeployment implements Deployment {
28
27
  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
29
28
  listPreviewDeployments(projectId: string, branch: string): Promise<DeploymentRecord[]>;
30
29
  deletePreviewDeployments(projectId: string, deploymentIds: string[]): Promise<number>;
31
- ensureCustomDomain(projectId: string, hostname: string): Promise<void>;
30
+ ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
32
31
  private getProjectByName;
33
32
  }
34
- //#endregion
35
- //#region src/capabilities/dns.d.ts
36
- declare class CloudflareDns implements Dns {
33
+ export declare class CloudflareDns implements Dns {
37
34
  private readonly client;
38
35
  readonly key: "dns";
39
36
  readonly providerName = "cloudflare";
@@ -42,6 +39,11 @@ declare class CloudflareDns implements Dns {
42
39
  listRecords(domain: string): Promise<DnsRecord[]>;
43
40
  upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
44
41
  deleteRecord(domain: string, id: string): Promise<void>;
42
+ /** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
43
+ whoami(): Promise<{
44
+ ok: boolean;
45
+ zones: number;
46
+ }>;
45
47
  /**
46
48
  * Walk from full domain up to apex to find the Cloudflare zone.
47
49
  * E.g. "api.staging.example.com" tries:
@@ -51,9 +53,7 @@ declare class CloudflareDns implements Dns {
51
53
  */
52
54
  private resolveZone;
53
55
  }
54
- //#endregion
55
- //#region src/capabilities/workers.d.ts
56
- declare class CloudflareWorkers implements Workers {
56
+ export declare class CloudflareWorkers implements Workers {
57
57
  private readonly client;
58
58
  private readonly accountId;
59
59
  readonly key: "workers";
@@ -61,30 +61,24 @@ declare class CloudflareWorkers implements Workers {
61
61
  private readonly zoneCache;
62
62
  constructor(client: () => Pick<CloudflareClient$1, "workers" | "zones">, accountId: string);
63
63
  upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
64
+ /** `holocron doctor` has no specific script to check — lists every script the token can see instead. */
65
+ whoami(): Promise<{
66
+ ok: boolean;
67
+ scripts: number;
68
+ }>;
64
69
  deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
70
+ setSecret(script: string, name: string, value: string): Promise<void>;
71
+ secretNames(script: string): Promise<string[]>;
65
72
  /** Idempotent create-or-update for one route pattern — shared by both public methods. */
66
73
  private upsertRoute;
67
74
  private resolveZone;
68
75
  }
69
- //#endregion
70
- //#region src/verify-token.d.ts
71
- interface VerifyTokenSuccess {
72
- ok: true;
73
- subject: string;
74
- }
75
- interface VerifyTokenFailure {
76
- ok: false;
77
- message: string;
78
- }
79
- type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
80
76
  interface VerifyTokenOptions {
81
77
  baseUrl?: string;
82
78
  fetch?: typeof fetch;
83
79
  }
84
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
85
- //#endregion
86
- //#region src/index.d.ts
87
- interface CloudflarePluginOptions extends ResolveTokenInput {
80
+ export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
81
+ export interface CloudflarePluginOptions extends ResolveTokenInput {
88
82
  /**
89
83
  * Cloudflare account ID. Required for Pages (deployment) operations;
90
84
  * optional for DNS-only use.
@@ -94,25 +88,27 @@ interface CloudflarePluginOptions extends ResolveTokenInput {
94
88
  baseUrl?: string;
95
89
  fetch?: typeof fetch;
96
90
  }
97
- interface PluginContext {
91
+ export interface PluginContext {
98
92
  options: CloudflarePluginOptions;
99
93
  /** Memoized client — the token is resolved on first use, not at plugin load. */
100
94
  client: () => CloudflareClient;
101
95
  /** Memoized token resolver — shared by the client and the Workers capability. */
102
96
  token: () => string;
103
97
  }
104
- declare function createContext(options?: CloudflarePluginOptions): PluginContext;
105
- declare function dns(ctx: PluginContext): Dns;
106
- declare function deployment(ctx: PluginContext): Deployment;
107
- declare function workersCapability(ctx: PluginContext): Workers;
108
- declare function createPlugin(options?: CloudflarePluginOptions): {
98
+ export declare function createContext(options?: CloudflarePluginOptions): PluginContext;
99
+ export declare function dns(ctx: PluginContext): Dns;
100
+ export declare function deployment(ctx: PluginContext): Deployment;
101
+ export declare function workersCapability(ctx: PluginContext): Workers;
102
+ export declare function createPlugin(options?: CloudflarePluginOptions): {
109
103
  name: string;
104
+ probes: {
105
+ connection: import("@theholocron/cli").Probe;
106
+ };
110
107
  capabilities: {
111
108
  deployment?: (() => Deployment) | undefined;
112
109
  workers?: (() => Workers) | undefined;
113
110
  dns: () => Dns;
114
111
  };
115
112
  };
116
- declare const AUTH_HINT: string;
117
- //#endregion
118
- export { AUTH_HINT, AuthError, type CloudflareClient, type CloudflareClientOptions, CloudflareDeployment, CloudflareDns, CloudflarePluginOptions, CloudflareWorkers, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, verifyToken, workersCapability };
113
+ export declare const AUTH_HINT: string;
114
+ export { AuthError, type CloudflareClient, type CloudflareClientOptions, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createCloudflareClient };
package/dist/index.mjs CHANGED
@@ -1,14 +1,16 @@
1
- import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken } from "@theholocron/cli";
2
2
  import { createCloudflareClient } from "@theholocron/cloudflare-client";
3
- //#region src/auth.ts
3
+ import { errorMessage } from "@theholocron/misc-utils";
4
+ // src/auth.ts
4
5
  const resolveToken = createResolveToken({
5
6
  envName: "HOLOCRON_CLOUDFLARE_TOKEN",
6
7
  vendorEnvName: "CLOUDFLARE_API_TOKEN",
7
8
  keyringService: "cloudflare",
8
9
  errorMessage: "no Cloudflare API token found. Pass --token <TOKEN>, set HOLOCRON_CLOUDFLARE_TOKEN / CLOUDFLARE_API_TOKEN, or run: holocron auth set cloudflare <TOKEN>"
9
10
  });
10
- //#endregion
11
- //#region src/capabilities/deployment.ts
11
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
12
+ const tokens = [resolveToken.token];
13
+ // src/capabilities/deployment.ts
12
14
  var CloudflareDeployment = class {
13
15
  client;
14
16
  accountId;
@@ -74,8 +76,9 @@ var CloudflareDeployment = class {
74
76
  return deploymentIds.length;
75
77
  }
76
78
  async ensureCustomDomain(projectId, hostname) {
77
- if ((await this.client().pages.listDomains(this.accountId, projectId)).some((d) => d.name === hostname)) return;
79
+ if ((await this.client().pages.listDomains(this.accountId, projectId)).some((d) => d.name === hostname)) return null;
78
80
  await this.client().pages.addDomain(this.accountId, projectId, hostname);
81
+ return null;
79
82
  }
80
83
  async getProjectByName(name) {
81
84
  try {
@@ -113,8 +116,7 @@ function normalizeStatus(status) {
113
116
  default: return "error";
114
117
  }
115
118
  }
116
- //#endregion
117
- //#region src/capabilities/dns.ts
119
+ // src/capabilities/dns.ts
118
120
  var CloudflareDns = class {
119
121
  client;
120
122
  key = "dns";
@@ -153,6 +155,13 @@ var CloudflareDns = class {
153
155
  const zoneId = await this.resolveZone(domain);
154
156
  await this.client().dns.delete(zoneId, id);
155
157
  }
158
+ /** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
159
+ async whoami() {
160
+ return {
161
+ ok: true,
162
+ zones: (await this.client().zones.list()).length
163
+ };
164
+ }
156
165
  /**
157
166
  * Walk from full domain up to apex to find the Cloudflare zone.
158
167
  * E.g. "api.staging.example.com" tries:
@@ -184,8 +193,7 @@ function mapRecord(raw) {
184
193
  ttl: raw.ttl
185
194
  };
186
195
  }
187
- //#endregion
188
- //#region src/capabilities/workers.ts
196
+ // src/capabilities/workers.ts
189
197
  var CloudflareWorkers = class {
190
198
  client;
191
199
  accountId;
@@ -202,12 +210,25 @@ var CloudflareWorkers = class {
202
210
  await this.client().workers.putScript(this.accountId, scriptName, script);
203
211
  await this.upsertRoute(`${hostname}/*`, scriptName);
204
212
  }
213
+ /** `holocron doctor` has no specific script to check — lists every script the token can see instead. */
214
+ async whoami() {
215
+ return {
216
+ ok: true,
217
+ scripts: (await this.client().workers.listScripts(this.accountId)).length
218
+ };
219
+ }
205
220
  async deployScript(name, config) {
206
221
  await this.client().workers.putScript(this.accountId, name, config.code);
207
222
  for (const [secretName, value] of Object.entries(config.secrets ?? {})) await this.client().workers.putSecret(this.accountId, name, secretName, value);
208
223
  for (const pattern of config.routes ?? []) await this.upsertRoute(pattern, name);
209
224
  return { scriptName: name };
210
225
  }
226
+ async setSecret(script, name, value) {
227
+ await this.client().workers.putSecret(this.accountId, script, name, value);
228
+ }
229
+ async secretNames(script) {
230
+ return (await this.client().workers.listSecrets(this.accountId, script)).map((secret) => secret.name);
231
+ }
211
232
  /** Idempotent create-or-update for one route pattern — shared by both public methods. */
212
233
  async upsertRoute(pattern, scriptName) {
213
234
  const hostname = pattern.split("/")[0];
@@ -250,8 +271,7 @@ function generateProxyScript(config) {
250
271
  `};`
251
272
  ].join("\n");
252
273
  }
253
- //#endregion
254
- //#region src/verify-token.ts
274
+ // src/verify-token.ts
255
275
  async function verifyToken(token, opts = {}) {
256
276
  const client = createCloudflareClient({
257
277
  token,
@@ -266,19 +286,23 @@ async function verifyToken(token, opts = {}) {
266
286
  };
267
287
  } catch {}
268
288
  try {
289
+ const names = (await client.zones.list()).map((z) => z.name);
290
+ if (names.length === 0) return {
291
+ ok: true,
292
+ subject: "no zones visible"
293
+ };
269
294
  return {
270
295
  ok: true,
271
- subject: `zone: ${(await client.zones.list({ per_page: 1 }))[0]?.name ?? "unknown"}`
296
+ subject: `zones: ${names.length <= 5 ? names.join(", ") : `${names.slice(0, 5).join(", ")} (+${names.length - 5} more)`}`
272
297
  };
273
298
  } catch (err) {
274
299
  return {
275
300
  ok: false,
276
- message: err instanceof Error ? err.message : String(err)
301
+ message: errorMessage(err)
277
302
  };
278
303
  }
279
304
  }
280
- //#endregion
281
- //#region src/index.ts
305
+ // src/index.ts
282
306
  function createContext(options = {}) {
283
307
  const accountId = options.accountId ?? process.env.CLOUDFLARE_ACCOUNT_ID;
284
308
  const opts = {
@@ -313,6 +337,16 @@ function createPlugin(options = {}) {
313
337
  const ctx = createContext(options);
314
338
  return {
315
339
  name: "@theholocron/holocron-plugin-cloudflare",
340
+ probes: { connection: connectionProbe({
341
+ provider: "Cloudflare",
342
+ url: options.baseUrl ?? "https://api.cloudflare.com",
343
+ fetch: options.fetch,
344
+ token: () => resolveToken(options),
345
+ verify: (token) => verifyToken(token, {
346
+ baseUrl: options.baseUrl,
347
+ fetch: options.fetch
348
+ })
349
+ }) },
316
350
  capabilities: {
317
351
  dns: () => dns(ctx),
318
352
  ...ctx.options.accountId ? {
@@ -323,5 +357,4 @@ function createPlugin(options = {}) {
323
357
  };
324
358
  }
325
359
  const AUTH_HINT = "create an API token at https://dash.cloudflare.com/profile/api-tokens with Zone:Read, DNS:Edit, Cloudflare Pages:Edit, Workers Scripts:Edit (account-level), and Workers Routes:Edit (zone-level) permissions, then run: holocron auth set cloudflare <TOKEN>";
326
- //#endregion
327
- export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, verifyToken, workersCapability };
360
+ export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, tokens, verifyToken, workersCapability };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-cloudflare",
3
- "version": "5.0.0-alpha.27",
3
+ "version": "5.0.0-alpha.271",
4
4
  "description": "Holocron plugin for Cloudflare. Implements the dns capability against Cloudflare's REST API — zone resolution, DNS record management.",
5
5
  "keywords": [
6
6
  "cloudflare",
@@ -8,12 +8,12 @@
8
8
  "holocron",
9
9
  "plugin"
10
10
  ],
11
- "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-cloudflare#readme",
11
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/cloudflare/",
12
12
  "bugs": "https://github.com/theholocron/holocron/issues",
13
13
  "repository": {
14
14
  "type": "git",
15
15
  "url": "git+https://github.com/theholocron/holocron.git",
16
- "directory": "packages/holocron-plugin-cloudflare"
16
+ "directory": "plugins/holocron-plugin-cloudflare"
17
17
  },
18
18
  "license": "MIT",
19
19
  "author": "Newton Koumantzelis",
@@ -30,28 +30,30 @@
30
30
  "dist"
31
31
  ],
32
32
  "devDependencies": {
33
- "@theholocron/cloudflare-client": "^1.23.0",
34
- "@theholocron/eslint-config": "^8.0.0",
35
- "@theholocron/http-client": "^1.23.0",
36
- "@theholocron/tsconfig": "^8.0.0",
37
- "@theholocron/tsdown-config": "^8.0.0",
38
- "@theholocron/vitest-config": "^8.0.0",
39
33
  "@types/node": "^26",
40
- "@vitest/coverage-v8": "^4.1.11",
34
+ "@vitest/coverage-v8": "^5.0.5",
41
35
  "@vitest/eslint-plugin": "^1.6.27",
42
36
  "chalk": "^6.0.0",
43
37
  "eslint": "^10.8.1",
44
38
  "eslint-plugin-n": "^18.3.0",
45
39
  "globals": "^17.11.0",
46
- "tsdown": "^0.22.14",
47
- "tsx": "4.23.12",
40
+ "tsdown": "^0.23.3",
41
+ "tsx": "4.23.15",
48
42
  "typescript": "^5.9.3",
49
- "vitest": "^4.1.11",
50
- "@theholocron/cli": "5.0.0-alpha.27"
43
+ "vitest": "^5.0.5",
44
+ "@theholocron/cloudflare-client": "^1.58.0-alpha.2",
45
+ "@theholocron/cli": "5.0.0-alpha.271",
46
+ "@theholocron/eslint-config": "^8.9.0-alpha.3",
47
+ "@theholocron/http-client": "^1.58.0-alpha.2",
48
+ "@theholocron/misc-utils": "^1.16.1-alpha.1",
49
+ "@theholocron/tsconfig": "^8.9.0-alpha.3",
50
+ "@theholocron/tsdown-config": "^8.9.0-alpha.3",
51
+ "@theholocron/vitest-config": "^8.9.0-alpha.3"
51
52
  },
52
53
  "peerDependencies": {
53
- "@theholocron/cloudflare-client": "^1.23.0",
54
- "@theholocron/cli": "5.0.0-alpha.27"
54
+ "@theholocron/cloudflare-client": "^1.53.1",
55
+ "@theholocron/misc-utils": "^1.16.0",
56
+ "@theholocron/cli": "5.0.0-alpha.271"
55
57
  },
56
58
  "peerDependenciesMeta": {
57
59
  "@theholocron/cloudflare-client": {}
@@ -64,10 +66,10 @@
64
66
  },
65
67
  "scripts": {
66
68
  "delivery.build": "tsdown",
67
- "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
69
+ "sourceQuality.staticAnalysis": "eslint .",
68
70
  "test:watch": "vitest",
69
71
  "validate": "tsx scripts/validate.mjs",
70
- "verification.typeSafety": "holocron run verification.typeSafety --",
71
- "verification.unitTests": "holocron run verification.unitTests --"
72
+ "verification.typeSafety": "tsc --noEmit",
73
+ "verification.unitTests": "vitest run"
72
74
  }
73
75
  }