@guren/plugin-cloudflare 0.12.3 → 0.13.1

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
@@ -18,40 +18,49 @@ bunx wrangler deploy
18
18
 
19
19
  `cloudflare:build` runs your app's `build` script, then assembles a `.cloudflare/` directory containing the worker entry, static assets for Workers Static Assets, and flattened D1 migrations. It is generated output — add it to `.gitignore` and rebuild before every deploy.
20
20
 
21
+ `bunx guren cloudflare:deploy` does the build, the D1 creation, the migrations and the deploy in one run, through the app's Wrangler (4.129 or later). It never writes `wrangler.jsonc`: the ids it resolves go into `.cloudflare/wrangler.deploy.json`, which it deploys with `wrangler deploy -c … --x-provision=false`. The plan and its checks are the ones described below for the cf CLI.
22
+
21
23
  Before the app build it runs the deploy-runtime checks `guren doctor` reports and warns, without failing, when sessions or OAuth state would sit in process memory, a Bun-only password hasher (`Argon2Hasher`, `hasher: 'argon2'`, or `new Hash({ algorithm: 'argon2' })`) is selected, or providers are discovered from the filesystem. Each works locally and breaks on Workers, and the warning prints where you are still reading rather than after the Vite output.
22
24
 
23
25
  `bunx guren cloudflare:size` (or `cloudflare:build --report-size`) measures the bundle a deploy would upload through wrangler's dry run and lists its largest sources by package. The platform limit is 64 MiB uncompressed on every plan; the report warns from half of it.
24
26
 
27
+ ## Deploying with the cf CLI (beta)
28
+
29
+ `bunx guren cloudflare:init` writes `cloudflare.config.ts`, `wrangler.config.ts` and `config/cloudflare.ts`, carrying over the D1 name and `OAUTH_KV` from an existing `wrangler.jsonc`, naming any Durable Object class no agent registers, and raising `cf` and `wrangler` in `package.json`; `--plan` then plans a deploy. When the app has a `cloudflare.config.ts` and declares the `cf` package, `cloudflare:build` assembles into `.guren/cloudflare/` and writes `guren-worker.json` there instead of scaffolding `wrangler.jsonc`. `@guren/plugin-cloudflare/config` turns that manifest into `cf` configuration: spread `await gurenWorker({ name })` into `defineConfig({ worker })`, and pass `gurenWranglerBundle()` to `defineWranglerConfig()` in `wrangler.config.ts`. `cf` loads both files with Node 22.18 or later, and needs Wrangler 4.136 or later to bundle. The Cloudflare guide has the full setup.
30
+
31
+ Guren's deploy settings live in `config/cloudflare.ts` (`defineCloudflareConfig({ mcpOAuth, mcpPath, resourceNames })`, from the same subpath), which the build and the deploy read and the running app does not; on this path it replaces the `--mcp-oauth` and `--mcp-path` flags.
32
+
33
+ `bunx guren cloudflare:deploy --plan` builds, evaluates `cloudflare.config.ts`, and resolves every D1 and KV binding against the account (existing, adopt, or create), exiting 1 on a conflict, a missing resource the run may not create, a listing it could not read, a pending destructive migration no marker acknowledges, or a production variable no secret provides. Without `--plan` it asks once, then creates what is missing, records the resolved ids in the ignored manifest, applies the pending migrations after a Time Travel bookmark, and runs `cf deploy --prebuilt --no-provision`. It never deletes; a failure lists the commands that undo what the run did. `--yes` or `--ci` replace the prompt in CI.
34
+
25
35
  ## API
26
36
 
27
37
  - **`createWorkersHandler(app)`** — wraps a Guren `Application` in a Workers module handler. Boot is lazy and deduplicated on the first request, because `boot()` performs I/O that workerd forbids in global scope. The handler deduplicates boot itself, so boot-once holds for anything matching `WorkersAppLike`, not only Guren's `Application`. It also exposes `boot(env)`, for an entrypoint that holds `env` but no request — an agent Durable Object woken by an alarm. The latch behind both is `bootWorkersApp(app, env)` / `bootAndFetch(app, request, env, ctx)`, keyed on the app.
28
38
  - **Durable agents** — when the app has a `config/agents.ts` (see `@guren/plugin-agents`), `cloudflare:build` appends a named export per registered class to the generated worker, verifies the committed `wrangler.jsonc` hosts each one as a SQLite-backed Durable Object (failing with the exact JSON to add), and mounts `/agents/*` deny-all behind the registry's `routing.authorize`.
29
- - **`getWorkersEnv<Env>()`** and **`isWorkersRuntime()`** — from `@guren/plugin-cloudflare/env`, an import-free subpath, so `config/*.ts` does not drag the deploy generator into every boot. `getWorkersEnv` exposes the first request's bindings to boot-time config through a write-once holder; `isWorkersRuntime()` is the workerd check the snippets below branch on. workerd can also expose bindings at module scope via `cloudflare:workers`, but importing that from shared config would break every other runtime (Bun, Lambda, Vercel) — the holder keeps `config/*.ts` portable. Use it to hand a D1 binding to the ORM:
39
+ - **`getWorkersEnv<Env>()`** and **`isWorkersRuntime()`** — from `@guren/plugin-cloudflare/env`, an import-free subpath, so `config/*.ts` does not drag the deploy generator into every boot. `getWorkersEnv` exposes the first request's bindings to boot-time config through a write-once holder; `isWorkersRuntime()` is the workerd check the snippets below branch on. workerd can also expose bindings at module scope via `cloudflare:workers`, but importing that from shared config would break every other runtime (Bun, Lambda, Vercel) — the holder keeps `config/*.ts` portable. A D1 or R2 binding can be given by name, which is read from that holder at the first use:
30
40
 
31
41
  ```typescript
32
42
  import { createD1Database } from '@guren/core'
33
- import { getWorkersEnv } from '@guren/plugin-cloudflare/env'
34
43
 
35
44
  const database = createD1Database({
36
- binding: () => getWorkersEnv<{ DB: unknown }>().DB,
45
+ binding: 'DB',
37
46
  })
38
47
  ```
39
48
 
40
- The binding is a resolver, not a value — it must be read lazily.
49
+ A closure such as `() => getWorkersEnv<Env>().DB` still works, but only a name shows in the introspected app.
41
50
 
42
- - **`R2Driver`** — a storage driver over the R2 bucket binding, for `StorageManager.registerDisk()`. Same lazy `binding` contract as D1; no credentials and no AWS SDK in the bundle:
51
+ - **`R2Driver`** — a storage driver over the R2 bucket binding, for `StorageManager.registerDisk()`. Same `binding` contract as D1; no credentials and no AWS SDK in the bundle:
43
52
 
44
53
  ```typescript
45
54
  import { createStorageManager, LocalStorageDriver } from '@guren/core'
46
- import { getWorkersEnv, isWorkersRuntime } from '@guren/plugin-cloudflare/env'
47
- import { R2Driver } from '@guren/plugin-cloudflare'
55
+ import { isWorkersRuntime } from '@guren/plugin-cloudflare/env'
56
+ import { r2Disk } from '@guren/plugin-cloudflare'
48
57
 
49
58
  const storage = createStorageManager({ default: 'media' })
50
- storage.registerDisk('media', () =>
51
- isWorkersRuntime()
52
- ? new R2Driver({ binding: () => getWorkersEnv<{ MEDIA: unknown }>().MEDIA, publicUrl: 'https://media.example.com' })
53
- : new LocalStorageDriver({ root: './storage/app/public', url: '/storage' }),
54
- )
59
+ if (isWorkersRuntime()) {
60
+ storage.registerDisk('media', ...r2Disk({ binding: 'MEDIA', publicUrl: 'https://media.example.com' }))
61
+ } else {
62
+ storage.registerDisk('media', () => new LocalStorageDriver({ root: './storage/app/public', url: '/storage' }))
63
+ }
55
64
  ```
56
65
 
57
66
  with `"r2_buckets": [{ "binding": "MEDIA", "bucket_name": "my-app-media" }]` in `wrangler.jsonc`. Three methods differ from the S3 driver, because the binding differs from S3: `url()` needs `publicUrl` (a custom domain or the r2.dev subdomain — R2 has no derivable public URL); `temporaryUrl()` needs the optional `presign` credentials, and throws with guidance otherwise (bindings cannot sign URLs); `setVisibility()` / `put({ visibility })` throw when asked for the opposite of the bucket's declared `visibility`, because R2 has no per-object ACL to honour the request with. `putFile()` throws — Workers has no filesystem.