@theholocron/holocron-plugin-cloudflare 5.0.0-alpha.36 → 5.0.0-alpha.360

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
@@ -3,7 +3,7 @@
3
3
  # `@theholocron/holocron-plugin-cloudflare`
4
4
 
5
5
  Cloudflare plugin for [Holocron](../cli). Implements the `dns`, `deployment`,
6
- and `workers` capabilities against the
6
+ `workers` and `tunnels` capabilities against the
7
7
  [Cloudflare v4 API](https://developers.cloudflare.com/api/).
8
8
 
9
9
  ## Install
@@ -63,9 +63,10 @@ Any combination of capabilities can be enabled together:
63
63
 
64
64
  ```
65
65
 
66
- The `deployment` and `workers` capabilities are only exposed when `accountId`
67
- is resolvable — either passed explicitly in options or set via the
68
- `CLOUDFLARE_ACCOUNT_ID` env var.
66
+ The `deployment`, `workers` and `tunnels` capabilities are only exposed when `accountId`
67
+ is resolvable — either passed explicitly in options or set as the
68
+ `CLOUDFLARE_ACCOUNT_ID` env var or in a `credentials` provider's Environment (the option wins, then the
69
+ environment, then the provider).
69
70
 
70
71
  ## `dns` capability
71
72
 
@@ -79,7 +80,7 @@ Zone ids are cached per plugin instance for the lifetime of the process.
79
80
 
80
81
  ## `deployment` capability
81
82
 
82
- Manages [Cloudflare Pages](https://developers.cloudflare.com/pages/) projects. Used by `holocron setup` to provision per-PR preview deployments.
83
+ Manages [Cloudflare Pages](https://developers.cloudflare.com/pages/) projects. Used by `holocron repo setup` to provision per-PR preview deployments.
83
84
 
84
85
  | Method | What it does |
85
86
  | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
@@ -104,9 +105,24 @@ route-write call when nothing changed. Zone ids are cached per plugin
104
105
  instance for the lifetime of the process — the `workers` capability's own
105
106
  cache, separate from `dns`'s.
106
107
 
108
+ ## `tunnels` capability
109
+
110
+ Named [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/): a stable
111
+ public hostname that reaches a port on this machine, for a webhook that has to find a development instance. It needs a
112
+ token with **Cloudflare Tunnel: Edit** (account).
113
+
114
+ | Method | What it does |
115
+ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
116
+ | `ensureTunnel` | Finds the tunnel by name or makes it, and makes its configuration serve `hostname` at `service`. Other hostnames' rules are kept and the catch-all (`http_status:404`) stays last. Returns the tunnel id and the `CNAME` target (`<id>.cfargotunnel.com`). |
117
+ | `tunnelToken` | The token `cloudflared` runs the tunnel with. A credential: never printed or stored. |
118
+ | `whoami` | How many tunnels the token can see, for `holocron doctor`. |
119
+
120
+ `ensureTunnel` is idempotent: a tunnel that already serves the hostname is not rewritten. The DNS record for the
121
+ hostname is the `dns` provider's job.
122
+
107
123
  ### Preview deployment setup
108
124
 
109
- When `preview: true` (or `preview: { project, domain }`) is set in a repo's deploy config, `holocron setup` calls:
125
+ When `preview: true` (or `preview: { project, domain }`) is set in a repo's deploy config, `holocron repo setup` calls:
110
126
 
111
127
  1. `ensureProject` — creates `<org>-preview` if it doesn't exist
112
128
  2. `ensureCustomDomain` — attaches `*.<domain>` to the project
package/dist/index.d.mts CHANGED
@@ -1,15 +1,19 @@
1
- import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, ResolveTokenInput, WikiProxyConfig, Workers } from "@theholocron/cli";
1
+ import { AuthError, DeployScriptConfig, DeployScriptResult, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordRequest, EnsuredTunnel, PluginToken, ResolveTokenInput, TunnelRoute, Tunnels, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess, WikiProxyConfig, WorkerScriptState, 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
+ /** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
4
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
5
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
6
+ export declare const tokens: PluginToken[];
7
+ /** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
8
+ export declare class CloudflareDeployment implements Deployment {
8
9
  private readonly client;
9
10
  private readonly accountId;
11
+ /** The capability this class provides, always `"deployment"`. */
10
12
  readonly key: "deployment";
13
+ /** The provider name, `"cloudflare"`. */
11
14
  readonly providerName = "cloudflare";
12
15
  constructor(client: () => CloudflareClient, accountId: string);
16
+ /** Lists the account's Pages projects. */
13
17
  listProjects(): Promise<DeploymentProject[]>;
14
18
  ensureProject(input: {
15
19
  name: string;
@@ -17,31 +21,44 @@ declare class CloudflareDeployment implements Deployment {
17
21
  repo?: string;
18
22
  rootDirectory?: string;
19
23
  }): Promise<DeploymentProject>;
24
+ /** Returns the project as it is now; Pages has no REST setting for the requested options, so `settings` is ignored. */
20
25
  updateProjectSettings(projectId: string, settings: DeploymentProjectSettings): Promise<DeploymentProject>;
26
+ /** Lists the names of the environment variables set for the production or preview target. */
21
27
  listEnvVars(projectId: string, target: DeploymentTarget): Promise<string[]>;
28
+ /** Sets a plain-text environment variable on the production or preview target, keeping the others. */
22
29
  setEnvVar(projectId: string, target: DeploymentTarget, name: string, value: string): Promise<void>;
23
30
  triggerDeployment(input: {
24
31
  projectId: string;
25
32
  branch: string;
26
33
  target?: DeploymentTrigger;
27
34
  }): Promise<DeploymentRecord>;
35
+ /** Fetches a deployment by an id of the form `projectName:deploymentId`; throws a 400 `ProviderApiError` for any other form. */
28
36
  getDeployment(deploymentId: string): Promise<DeploymentRecord>;
29
37
  listPreviewDeployments(projectId: string, branch: string): Promise<DeploymentRecord[]>;
30
38
  deletePreviewDeployments(projectId: string, deploymentIds: string[]): Promise<number>;
31
39
  ensureCustomDomain(projectId: string, hostname: string): Promise<DnsRecordRequest | null>;
32
40
  private getProjectByName;
33
41
  }
34
- //#endregion
35
- //#region src/capabilities/dns.d.ts
36
- declare class CloudflareDns implements Dns {
42
+ /** The Cloudflare implementation of the `dns` capability; finds a domain's zone by walking from the domain up to its apex. */
43
+ export declare class CloudflareDns implements Dns {
37
44
  private readonly client;
45
+ /** The capability this class provides, always `"dns"`. */
38
46
  readonly key: "dns";
47
+ /** The provider name, `"cloudflare"`. */
39
48
  readonly providerName = "cloudflare";
40
49
  private readonly zoneCache;
41
50
  constructor(client: () => CloudflareClient);
51
+ /** Lists the DNS records in the zone that holds the domain. */
42
52
  listRecords(domain: string): Promise<DnsRecord[]>;
53
+ /** Updates the first record of the same type and name, or creates the record when there is none; returns the stored record. */
43
54
  upsertRecord(domain: string, record: DnsRecord): Promise<DnsRecord>;
55
+ /** Deletes the DNS record with this id from the zone that holds the domain. */
44
56
  deleteRecord(domain: string, id: string): Promise<void>;
57
+ /** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
58
+ whoami(): Promise<{
59
+ ok: boolean;
60
+ zones: number;
61
+ }>;
45
62
  /**
46
63
  * Walk from full domain up to apex to find the Cloudflare zone.
47
64
  * E.g. "api.staging.example.com" tries:
@@ -51,40 +68,61 @@ declare class CloudflareDns implements Dns {
51
68
  */
52
69
  private resolveZone;
53
70
  }
54
- //#endregion
55
- //#region src/capabilities/workers.d.ts
56
- declare class CloudflareWorkers implements Workers {
71
+ /** The Cloudflare implementation of the `tunnels` capability, backed by Cloudflare Tunnel in one account. */
72
+ export declare class CloudflareTunnels implements Tunnels {
57
73
  private readonly client;
58
74
  private readonly accountId;
75
+ /** The capability this class provides, always `"tunnels"`. */
76
+ readonly key: "tunnels";
77
+ /** The provider name, `"cloudflare"`. */
78
+ readonly providerName = "cloudflare";
79
+ constructor(client: () => Pick<CloudflareClient$1, "tunnels">, accountId: string);
80
+ /** Finds the tunnel by name or makes it, then rewrites its routes only when they do not already serve the hostname. */
81
+ ensureTunnel(route: TunnelRoute): Promise<EnsuredTunnel>;
82
+ /** The token `cloudflared` runs the tunnel with. */
83
+ tunnelToken(tunnelId: string): Promise<string>;
84
+ /** `holocron doctor` has no specific tunnel to check: lists the ones the token can see. */
85
+ whoami(): Promise<{
86
+ ok: boolean;
87
+ tunnels: number;
88
+ }>;
89
+ }
90
+ /** The Cloudflare implementation of the `workers` capability, backed by Workers scripts and routes in one account. */
91
+ export declare class CloudflareWorkers implements Workers {
92
+ private readonly client;
93
+ private readonly accountId;
94
+ /** The capability this class provides, always `"workers"`. */
59
95
  readonly key: "workers";
96
+ /** The provider name, `"cloudflare"`. */
60
97
  readonly providerName = "cloudflare";
61
98
  private readonly zoneCache;
62
99
  constructor(client: () => Pick<CloudflareClient$1, "workers" | "zones">, accountId: string);
63
100
  upsertProxy(hostname: string, config: WikiProxyConfig): Promise<void>;
101
+ /** `holocron doctor` has no specific script to check — lists every script the token can see instead. */
102
+ whoami(): Promise<{
103
+ ok: boolean;
104
+ scripts: number;
105
+ }>;
64
106
  deployScript(name: string, config: DeployScriptConfig): Promise<DeployScriptResult>;
107
+ setSecret(script: string, name: string, value: string): Promise<void>;
108
+ secretNames(script: string): Promise<string[]>;
109
+ /**
110
+ * Whether the script exists, which routes in the zone of `host` point at it, and the names of its secrets. Reads
111
+ * only, and asks Cloudflare for names, so no value is ever fetched.
112
+ */
113
+ inspectScript(name: string, host: string): Promise<WorkerScriptState>;
65
114
  /** Idempotent create-or-update for one route pattern — shared by both public methods. */
66
115
  private upsertRoute;
67
116
  private resolveZone;
68
117
  }
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
118
  interface VerifyTokenOptions {
81
119
  baseUrl?: string;
82
120
  fetch?: typeof fetch;
83
121
  }
84
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
85
- //#endregion
86
- //#region src/index.d.ts
87
- interface CloudflarePluginOptions extends ResolveTokenInput {
122
+ /** Checks a Cloudflare API token, first by the token-verify endpoint and otherwise by listing zones; resolves to a description of what it found, or the failure message. */
123
+ export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
124
+ /** Options for the Cloudflare plugin: how the API token is resolved, the account, and test overrides. */
125
+ export interface CloudflarePluginOptions extends ResolveTokenInput {
88
126
  /**
89
127
  * Cloudflare account ID. Required for Pages (deployment) operations;
90
128
  * optional for DNS-only use.
@@ -92,27 +130,41 @@ interface CloudflarePluginOptions extends ResolveTokenInput {
92
130
  accountId?: string;
93
131
  /** Override base URL for tests. */
94
132
  baseUrl?: string;
133
+ /** The `fetch` to use instead of the global one, for tests. */
95
134
  fetch?: typeof fetch;
96
135
  }
97
- interface PluginContext {
136
+ /** The shared state the Cloudflare plugin's capabilities and probes are built from. */
137
+ export interface PluginContext {
138
+ /** The options the plugin was created with, with `accountId` falling back to `CLOUDFLARE_ACCOUNT_ID` in the environment, then in the `credentials` providers' variables. */
98
139
  options: CloudflarePluginOptions;
99
140
  /** Memoized client — the token is resolved on first use, not at plugin load. */
100
141
  client: () => CloudflareClient;
101
142
  /** Memoized token resolver — shared by the client and the Workers capability. */
102
143
  token: () => string;
103
144
  }
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): {
145
+ /** Builds the plugin context from its options; the API token is resolved lazily on the first client use. */
146
+ export declare function createContext(options?: CloudflarePluginOptions): PluginContext;
147
+ /** Builds the `dns` capability for a context. */
148
+ export declare function dns(ctx: PluginContext): Dns;
149
+ /** Builds the `deployment` capability for a context; throws when no account id is set. */
150
+ export declare function deployment(ctx: PluginContext): Deployment;
151
+ /** Builds the `workers` capability for a context; throws when no account id is set. */
152
+ export declare function workersCapability(ctx: PluginContext): Workers;
153
+ /** Builds the `tunnels` capability for a context; throws when no account id is set. */
154
+ export declare function tunnelsCapability(ctx: PluginContext): Tunnels;
155
+ /** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and a `connection` probe. */
156
+ export declare function createPlugin(options?: CloudflarePluginOptions): {
109
157
  name: string;
158
+ probes: {
159
+ connection: import("@theholocron/cli").Probe;
160
+ };
110
161
  capabilities: {
111
162
  deployment?: (() => Deployment) | undefined;
112
163
  workers?: (() => Workers) | undefined;
164
+ tunnels?: (() => Tunnels) | undefined;
113
165
  dns: () => Dns;
114
166
  };
115
167
  };
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 };
168
+ /** One-line hint printed by `holocron auth set cloudflare` when no token is supplied or the supplied one is rejected. */
169
+ export declare const AUTH_HINT: string;
170
+ export { AuthError, type CloudflareClient, type CloudflareClientOptions, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createCloudflareClient };
package/dist/index.mjs CHANGED
@@ -1,23 +1,30 @@
1
- import { AuthError, ProviderApiError, createResolveToken } from "@theholocron/cli";
1
+ import { AuthError, ProviderApiError, connectionProbe, createResolveToken, resolveValue } 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
5
+ /** Resolves the Cloudflare API token from `--token`, `HOLOCRON_CLOUDFLARE_TOKEN`, `CLOUDFLARE_API_TOKEN` or the keyring, and throws an `AuthError` when none is set. */
4
6
  const resolveToken = createResolveToken({
5
7
  envName: "HOLOCRON_CLOUDFLARE_TOKEN",
6
8
  vendorEnvName: "CLOUDFLARE_API_TOKEN",
7
9
  keyringService: "cloudflare",
8
10
  errorMessage: "no Cloudflare API token found. Pass --token <TOKEN>, set HOLOCRON_CLOUDFLARE_TOKEN / CLOUDFLARE_API_TOKEN, or run: holocron auth set cloudflare <TOKEN>"
9
11
  });
10
- //#endregion
11
- //#region src/capabilities/deployment.ts
12
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
13
+ const tokens = [resolveToken.token];
14
+ // src/capabilities/deployment.ts
15
+ /** The Cloudflare implementation of the `deployment` capability, backed by Cloudflare Pages projects in one account. */
12
16
  var CloudflareDeployment = class {
13
17
  client;
14
18
  accountId;
19
+ /** The capability this class provides, always `"deployment"`. */
15
20
  key = "deployment";
21
+ /** The provider name, `"cloudflare"`. */
16
22
  providerName = "cloudflare";
17
23
  constructor(client, accountId) {
18
24
  this.client = client;
19
25
  this.accountId = accountId;
20
26
  }
27
+ /** Lists the account's Pages projects. */
21
28
  async listProjects() {
22
29
  return (await this.client().pages.listProjects(this.accountId)).map(mapProject);
23
30
  }
@@ -29,14 +36,17 @@ var CloudflareDeployment = class {
29
36
  production_branch: "main"
30
37
  }));
31
38
  }
39
+ /** Returns the project as it is now; Pages has no REST setting for the requested options, so `settings` is ignored. */
32
40
  async updateProjectSettings(projectId, settings) {
33
41
  return mapProject(await this.client().pages.getProject(this.accountId, projectId));
34
42
  }
43
+ /** Lists the names of the environment variables set for the production or preview target. */
35
44
  async listEnvVars(projectId, target) {
36
45
  const project = await this.client().pages.getProject(this.accountId, projectId);
37
46
  const envConfig = target === "production" ? project.deployment_configs.production : project.deployment_configs.preview;
38
47
  return Object.keys(envConfig.env_vars);
39
48
  }
49
+ /** Sets a plain-text environment variable on the production or preview target, keeping the others. */
40
50
  async setEnvVar(projectId, target, name, value) {
41
51
  const cfg = (await this.client().pages.getProject(this.accountId, projectId)).deployment_configs;
42
52
  const scope = target === "production" ? "production" : "preview";
@@ -55,6 +65,7 @@ var CloudflareDeployment = class {
55
65
  async triggerDeployment(input) {
56
66
  return mapDeployment(await this.client().pages.createDeployment(this.accountId, input.projectId, input.branch), input.projectId, input.branch, input.target);
57
67
  }
68
+ /** Fetches a deployment by an id of the form `projectName:deploymentId`; throws a 400 `ProviderApiError` for any other form. */
58
69
  async getDeployment(deploymentId) {
59
70
  const sep = deploymentId.indexOf(":");
60
71
  if (sep === -1) throw new ProviderApiError(`Invalid Cloudflare Pages deployment id "${deploymentId}" — expected "projectName:deploymentId"`, 400, void 0);
@@ -114,20 +125,24 @@ function normalizeStatus(status) {
114
125
  default: return "error";
115
126
  }
116
127
  }
117
- //#endregion
118
- //#region src/capabilities/dns.ts
128
+ // src/capabilities/dns.ts
129
+ /** The Cloudflare implementation of the `dns` capability; finds a domain's zone by walking from the domain up to its apex. */
119
130
  var CloudflareDns = class {
120
131
  client;
132
+ /** The capability this class provides, always `"dns"`. */
121
133
  key = "dns";
134
+ /** The provider name, `"cloudflare"`. */
122
135
  providerName = "cloudflare";
123
136
  zoneCache = /* @__PURE__ */ new Map();
124
137
  constructor(client) {
125
138
  this.client = client;
126
139
  }
140
+ /** Lists the DNS records in the zone that holds the domain. */
127
141
  async listRecords(domain) {
128
142
  const zoneId = await this.resolveZone(domain);
129
143
  return (await this.client().dns.list(zoneId)).map(mapRecord);
130
144
  }
145
+ /** Updates the first record of the same type and name, or creates the record when there is none; returns the stored record. */
131
146
  async upsertRecord(domain, record) {
132
147
  const client = this.client();
133
148
  const zoneId = await this.resolveZone(domain);
@@ -150,10 +165,18 @@ var CloudflareDns = class {
150
165
  ...record.proxied !== void 0 ? { proxied: record.proxied } : {}
151
166
  }));
152
167
  }
168
+ /** Deletes the DNS record with this id from the zone that holds the domain. */
153
169
  async deleteRecord(domain, id) {
154
170
  const zoneId = await this.resolveZone(domain);
155
171
  await this.client().dns.delete(zoneId, id);
156
172
  }
173
+ /** `holocron doctor` has no specific domain to check — lists every zone the token can see instead. */
174
+ async whoami() {
175
+ return {
176
+ ok: true,
177
+ zones: (await this.client().zones.list()).length
178
+ };
179
+ }
157
180
  /**
158
181
  * Walk from full domain up to apex to find the Cloudflare zone.
159
182
  * E.g. "api.staging.example.com" tries:
@@ -182,15 +205,75 @@ function mapRecord(raw) {
182
205
  type: raw.type,
183
206
  name: raw.name,
184
207
  content: raw.content,
185
- ttl: raw.ttl
208
+ ttl: raw.ttl,
209
+ ...raw.proxied !== void 0 ? { proxied: raw.proxied } : {}
210
+ };
211
+ }
212
+ // src/capabilities/tunnels.ts
213
+ /** The rule a tunnel needs last: anything no other rule matches is answered with a 404 by the connector itself. */
214
+ const CATCH_ALL = { service: "http_status:404" };
215
+ /**
216
+ * The ingress rules with `hostname` served at `service`: the rule for the hostname is replaced where it is or added
217
+ * after the others, every other hostname's rule is kept, and the rule without a hostname closes the list.
218
+ */
219
+ function withRoute(current, hostname, service) {
220
+ const rule = {
221
+ hostname,
222
+ service
186
223
  };
224
+ const named = current.filter((r) => r.hostname !== void 0);
225
+ const at = named.findIndex((r) => r.hostname === hostname);
226
+ return [...at === -1 ? [...named, rule] : named.map((r, i) => i === at ? rule : r), current.find((r) => r.hostname === void 0) ?? CATCH_ALL];
187
227
  }
188
- //#endregion
189
- //#region src/capabilities/workers.ts
228
+ /** The Cloudflare implementation of the `tunnels` capability, backed by Cloudflare Tunnel in one account. */
229
+ var CloudflareTunnels = class {
230
+ client;
231
+ accountId;
232
+ /** The capability this class provides, always `"tunnels"`. */
233
+ key = "tunnels";
234
+ /** The provider name, `"cloudflare"`. */
235
+ providerName = "cloudflare";
236
+ constructor(client, accountId) {
237
+ this.client = client;
238
+ this.accountId = accountId;
239
+ }
240
+ /** Finds the tunnel by name or makes it, then rewrites its routes only when they do not already serve the hostname. */
241
+ async ensureTunnel(route) {
242
+ const { tunnels } = this.client();
243
+ const found = (await tunnels.list(this.accountId)).find((t) => t.name === route.name);
244
+ const tunnel = found ?? await tunnels.create(this.accountId, { name: route.name });
245
+ const current = (await tunnels.getConfig(this.accountId, tunnel.id)).config?.ingress ?? [];
246
+ const wanted = withRoute(current, route.hostname, route.service);
247
+ const configured = JSON.stringify(wanted) !== JSON.stringify(current);
248
+ if (configured) await tunnels.putConfig(this.accountId, tunnel.id, { ingress: wanted });
249
+ return {
250
+ id: tunnel.id,
251
+ name: tunnel.name,
252
+ created: found === void 0,
253
+ configured,
254
+ target: `${tunnel.id}.cfargotunnel.com`
255
+ };
256
+ }
257
+ /** The token `cloudflared` runs the tunnel with. */
258
+ tunnelToken(tunnelId) {
259
+ return this.client().tunnels.token(this.accountId, tunnelId);
260
+ }
261
+ /** `holocron doctor` has no specific tunnel to check: lists the ones the token can see. */
262
+ async whoami() {
263
+ return {
264
+ ok: true,
265
+ tunnels: (await this.client().tunnels.list(this.accountId)).length
266
+ };
267
+ }
268
+ };
269
+ // src/capabilities/workers.ts
270
+ /** The Cloudflare implementation of the `workers` capability, backed by Workers scripts and routes in one account. */
190
271
  var CloudflareWorkers = class {
191
272
  client;
192
273
  accountId;
274
+ /** The capability this class provides, always `"workers"`. */
193
275
  key = "workers";
276
+ /** The provider name, `"cloudflare"`. */
194
277
  providerName = "cloudflare";
195
278
  zoneCache = /* @__PURE__ */ new Map();
196
279
  constructor(client, accountId) {
@@ -203,12 +286,45 @@ var CloudflareWorkers = class {
203
286
  await this.client().workers.putScript(this.accountId, scriptName, script);
204
287
  await this.upsertRoute(`${hostname}/*`, scriptName);
205
288
  }
289
+ /** `holocron doctor` has no specific script to check — lists every script the token can see instead. */
290
+ async whoami() {
291
+ return {
292
+ ok: true,
293
+ scripts: (await this.client().workers.listScripts(this.accountId)).length
294
+ };
295
+ }
206
296
  async deployScript(name, config) {
207
297
  await this.client().workers.putScript(this.accountId, name, config.code);
208
298
  for (const [secretName, value] of Object.entries(config.secrets ?? {})) await this.client().workers.putSecret(this.accountId, name, secretName, value);
209
299
  for (const pattern of config.routes ?? []) await this.upsertRoute(pattern, name);
210
300
  return { scriptName: name };
211
301
  }
302
+ async setSecret(script, name, value) {
303
+ await this.client().workers.putSecret(this.accountId, script, name, value);
304
+ }
305
+ async secretNames(script) {
306
+ return (await this.client().workers.listSecrets(this.accountId, script)).map((secret) => secret.name);
307
+ }
308
+ /**
309
+ * Whether the script exists, which routes in the zone of `host` point at it, and the names of its secrets. Reads
310
+ * only, and asks Cloudflare for names, so no value is ever fetched.
311
+ */
312
+ async inspectScript(name, host) {
313
+ const client = this.client();
314
+ if (!(await client.workers.listScripts(this.accountId)).some((s) => s.id === name)) return {
315
+ exists: false,
316
+ routes: [],
317
+ bindingNames: []
318
+ };
319
+ const zoneId = await this.resolveZone(host);
320
+ const routes = await client.workers.listRoutes(zoneId);
321
+ const secrets = await client.workers.listSecrets(this.accountId, name);
322
+ return {
323
+ exists: true,
324
+ routes: routes.filter((r) => r.script === name).map((r) => r.pattern),
325
+ bindingNames: secrets.map((secret) => secret.name)
326
+ };
327
+ }
212
328
  /** Idempotent create-or-update for one route pattern — shared by both public methods. */
213
329
  async upsertRoute(pattern, scriptName) {
214
330
  const hostname = pattern.split("/")[0];
@@ -251,8 +367,8 @@ function generateProxyScript(config) {
251
367
  `};`
252
368
  ].join("\n");
253
369
  }
254
- //#endregion
255
- //#region src/verify-token.ts
370
+ // src/verify-token.ts
371
+ /** Checks a Cloudflare API token, first by the token-verify endpoint and otherwise by listing zones; resolves to a description of what it found, or the failure message. */
256
372
  async function verifyToken(token, opts = {}) {
257
373
  const client = createCloudflareClient({
258
374
  token,
@@ -267,21 +383,26 @@ async function verifyToken(token, opts = {}) {
267
383
  };
268
384
  } catch {}
269
385
  try {
386
+ const names = (await client.zones.list()).map((z) => z.name);
387
+ if (names.length === 0) return {
388
+ ok: true,
389
+ subject: "no zones visible"
390
+ };
270
391
  return {
271
392
  ok: true,
272
- subject: `zone: ${(await client.zones.list({ per_page: 1 }))[0]?.name ?? "unknown"}`
393
+ subject: `zones: ${names.length <= 5 ? names.join(", ") : `${names.slice(0, 5).join(", ")} (+${names.length - 5} more)`}`
273
394
  };
274
395
  } catch (err) {
275
396
  return {
276
397
  ok: false,
277
- message: err instanceof Error ? err.message : String(err)
398
+ message: errorMessage(err)
278
399
  };
279
400
  }
280
401
  }
281
- //#endregion
282
- //#region src/index.ts
402
+ // src/index.ts
403
+ /** Builds the plugin context from its options; the API token is resolved lazily on the first client use. */
283
404
  function createContext(options = {}) {
284
- const accountId = options.accountId ?? process.env.CLOUDFLARE_ACCOUNT_ID;
405
+ const accountId = options.accountId ?? resolveValue(["CLOUDFLARE_ACCOUNT_ID"], options.env);
285
406
  const opts = {
286
407
  ...options,
287
408
  accountId
@@ -299,30 +420,50 @@ function createContext(options = {}) {
299
420
  })
300
421
  };
301
422
  }
423
+ /** Builds the `dns` capability for a context. */
302
424
  function dns(ctx) {
303
425
  return new CloudflareDns(ctx.client);
304
426
  }
427
+ /** Builds the `deployment` capability for a context; throws when no account id is set. */
305
428
  function deployment(ctx) {
306
429
  if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Pages deployments — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
307
430
  return new CloudflareDeployment(ctx.client, ctx.options.accountId);
308
431
  }
432
+ /** Builds the `workers` capability for a context; throws when no account id is set. */
309
433
  function workersCapability(ctx) {
310
434
  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");
311
435
  return new CloudflareWorkers(ctx.client, ctx.options.accountId);
312
436
  }
437
+ /** Builds the `tunnels` capability for a context; throws when no account id is set. */
438
+ function tunnelsCapability(ctx) {
439
+ if (!ctx.options.accountId) throw new Error("Cloudflare accountId is required for Tunnels — set accountId in the plugin options or CLOUDFLARE_ACCOUNT_ID env var");
440
+ return new CloudflareTunnels(ctx.client, ctx.options.accountId);
441
+ }
442
+ /** Creates the Cloudflare plugin: `dns` always, plus `deployment`, `workers` and `tunnels` when an account id is set, and a `connection` probe. */
313
443
  function createPlugin(options = {}) {
314
444
  const ctx = createContext(options);
315
445
  return {
316
446
  name: "@theholocron/holocron-plugin-cloudflare",
447
+ probes: { connection: connectionProbe({
448
+ provider: "Cloudflare",
449
+ url: options.baseUrl ?? "https://api.cloudflare.com",
450
+ fetch: options.fetch,
451
+ token: () => resolveToken(options),
452
+ verify: (token) => verifyToken(token, {
453
+ baseUrl: options.baseUrl,
454
+ fetch: options.fetch
455
+ })
456
+ }) },
317
457
  capabilities: {
318
458
  dns: () => dns(ctx),
319
459
  ...ctx.options.accountId ? {
320
460
  deployment: () => deployment(ctx),
321
- workers: () => workersCapability(ctx)
461
+ workers: () => workersCapability(ctx),
462
+ tunnels: () => tunnelsCapability(ctx)
322
463
  } : {}
323
464
  }
324
465
  };
325
466
  }
326
- 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>";
327
- //#endregion
328
- export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, verifyToken, workersCapability };
467
+ /** One-line hint printed by `holocron auth set cloudflare` when no token is supplied or the supplied one is rejected. */
468
+ 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), Workers Routes:Edit (zone-level) and, for tunnels, Cloudflare Tunnel:Edit (account-level) permissions, then run: holocron auth set cloudflare <TOKEN>";
469
+ export { AUTH_HINT, AuthError, CloudflareDeployment, CloudflareDns, CloudflareTunnels, CloudflareWorkers, createCloudflareClient, createContext, createPlugin, deployment, dns, resolveToken, tokens, tunnelsCapability, 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.36",
3
+ "version": "5.0.0-alpha.360",
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,31 @@
30
30
  "dist"
31
31
  ],
32
32
  "devDependencies": {
33
- "@theholocron/cloudflare-client": "^1.24.0",
34
- "@theholocron/eslint-config": "^8.0.0",
35
- "@theholocron/http-client": "^1.24.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",
41
- "@vitest/eslint-plugin": "^1.6.27",
42
- "chalk": "^6.0.0",
43
- "eslint": "^10.8.1",
44
- "eslint-plugin-n": "^18.3.0",
45
- "globals": "^17.11.0",
46
- "tsdown": "^0.22.14",
47
- "tsx": "4.23.12",
34
+ "@vitest/coverage-v8": "^5.0.5",
35
+ "@vitest/eslint-plugin": "^1.6.28",
36
+ "chalk": "^6.0.1",
37
+ "eslint": "^10.14.0",
38
+ "eslint-plugin-n": "^18.5.0",
39
+ "globals": "^17.14.0",
40
+ "tsdown": "^0.23.4",
41
+ "tsx": "4.23.15",
48
42
  "typescript": "^5.9.3",
49
- "vitest": "^4.1.11",
50
- "@theholocron/cli": "5.0.0-alpha.36"
43
+ "vitest": "^5.0.5",
44
+ "@theholocron/cloudflare-client": "^1.58.0-alpha.14",
45
+ "@theholocron/http-client": "^1.58.0-alpha.14",
46
+ "@theholocron/eslint-config": "^8.9.0-alpha.9",
47
+ "@theholocron/cli": "5.0.0-alpha.360",
48
+ "@theholocron/kyber": "5.0.0-alpha.360",
49
+ "@theholocron/misc-utils": "^1.17.0-alpha.1",
50
+ "@theholocron/tsconfig": "^8.9.0-alpha.9",
51
+ "@theholocron/tsdown-config": "^8.9.0-alpha.9",
52
+ "@theholocron/vitest-config": "^8.9.0-alpha.9"
51
53
  },
52
54
  "peerDependencies": {
53
- "@theholocron/cloudflare-client": "^1.24.0",
54
- "@theholocron/cli": "5.0.0-alpha.36"
55
+ "@theholocron/cloudflare-client": "^1.53.1",
56
+ "@theholocron/misc-utils": "^1.16.0",
57
+ "@theholocron/cli": "5.0.0-alpha.360"
55
58
  },
56
59
  "peerDependenciesMeta": {
57
60
  "@theholocron/cloudflare-client": {}
@@ -63,11 +66,11 @@
63
66
  "access": "public"
64
67
  },
65
68
  "scripts": {
66
- "delivery.build": "tsdown",
67
- "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
69
+ "build": "tsdown",
70
+ "lint:code": "eslint .",
71
+ "test:unit": "vitest run --coverage",
68
72
  "test:watch": "vitest",
69
- "validate": "tsx scripts/validate.mjs",
70
- "verification.typeSafety": "holocron run verification.typeSafety --",
71
- "verification.unitTests": "holocron run verification.unitTests --"
73
+ "typecheck": "tsc --noEmit",
74
+ "validate:plugin": "tsx scripts/validate.mjs"
72
75
  }
73
76
  }