devflare 1.0.0-next.16 → 1.0.0-next.17

package/README.md

@@ -76,13 +76,16 @@ Use `devflare/config` for config files so Bun only loads the lightweight config
 import type { FetchEvent } from 'devflare/runtime'
 
 export async function fetch({ url }: FetchEvent): Promise<Response> {
-	return new Response(
-			: `Hello from Devflare: ${url.pathname}`
-	)
+	return new Response(`Hello from Devflare: ${url.pathname}`)
 }
 ```
 
 ### 3. Generate types
+
+```bash
+bunx --bun devflare types
+```
+
 ### 4. Start development
 
 ```bash
@@ -117,14 +120,17 @@ Use subpaths intentionally.
 
 | Import | Use for |
 |---|---|
-| `devflare` | main package entrypoint: config helpers, `ref()`, unified `env`, bridge helpers, CLI helpers, decorators |
-| `devflare/runtime` | worker-safe runtime helpers like `env`, `ctx`, `event`, `locals`, event types/getters, middleware helpers |
-| `devflare/test` | `createTestContext`, `cf.*`, mock helpers, bridge test context, skip helpers |
+| `devflare` | main package entrypoint: `defineConfig`, `defineWorker`, `ref()`, the unified `env`/`ctx`/`event`/`locals` proxies, `sequence`, `defineFetchHandler`, decorators |
+| `devflare/config` | lightweight config-only entry for `devflare.config.ts` files (Bun loads only the config helpers, not the full Node-side barrel) |
+| `devflare/runtime` | worker-safe runtime helpers: strict `env`, `ctx`, `event`, `locals`, event types/getters, middleware helpers |
+| `devflare/test` | `createTestContext`, `cf.*`, mock helpers (`createMockKV`/`createMockD1`/`createMockR2`/`createMockEnv`/`createMockTestContext`/`withTestContext`) |
 | `devflare/vite` | Vite integration |
 | `devflare/sveltekit` | SvelteKit integration |
 | `devflare/cloudflare` | Cloudflare account/auth/usage/limits/preferences helpers |
 | `devflare/decorators` | decorators only |
 
+Internal bridge and transform helpers are intentionally not re-exported from bare `'devflare'`. If you previously imported them from the main entry, switch to the matching subpath — see "Public API surface and migration notes" below.
+
 ### Runtime import rule of thumb
 
 - use `import { env } from 'devflare/runtime'` for **strict request-scoped runtime access**
@@ -793,6 +799,36 @@ It also auto-detects conventional `src/fetch.ts`, `src/queue.ts`, `src/scheduled
 - `cf.email.send()` invokes the configured email handler in `createTestContext()`-backed tests and otherwise falls back to the local email endpoint; for ingress-fidelity-sensitive flows, validate with a higher-level integration test
 - remote mode is mainly about AI and Vectorize, not “make every binding remote”
 
+### Choosing pure mocks vs Miniflare-backed `createTestContext()`
+
+`devflare/test` ships two complementary lanes. Pick by what you are validating:
+
+- **Pure mocks** (`createMockKV`, `createMockD1`, `createMockR2`, `createMockEnv`, `createMockTestContext`, `withTestContext`):
+	- Fast, in-process, no Miniflare boot
+	- Use when you are unit-testing a function that reads or writes a single binding and you control the inputs
+	- Behavior is approximate: KV is binary-safe, D1 supports `SELECT`/`INSERT` per-table fixtures, R2 stores bytes — anything beyond those primitives will diverge from production
+- **`createTestContext()` (Miniflare-backed)**:
+	- Boots a real Workers runtime locally with your `devflare.config.ts`
+	- Use when you are testing handler dispatch, multi-binding flows, queues/scheduled/email/Durable Objects, route discovery, middleware composition, or anything that needs accurate Workers semantics
+	- Slower per test, so reuse one context per test file when possible
+
+Rule of thumb: if the assertion is "given inputs X, my function returns Y", reach for the mocks. If the assertion is "the worker behaves correctly when this binding/handler/route fires", use `createTestContext()`.
+
+---
+
+## Public API surface and migration notes
+
+Devflare's bare `'devflare'` import is intentionally narrow and only exposes the documented public API. Internal helpers for the bridge, transform, and test runner are reachable from dedicated subpaths instead:
+
+- `devflare` — primary public API (`defineConfig`, `defineWorker`, `sequence`, `defineFetchHandler`, runtime context accessors, etc.)
+- `devflare/test` — `createTestContext`, `cf`, mock factories
+- `devflare/runtime` — runtime accessors (`env`, `ctx`, `event`, `locals`, helpers)
+- `devflare/cloudflare` — Cloudflare API helpers
+- `devflare/sveltekit` — SvelteKit platform glue
+- `devflare/decorators` — `@durableObject` and other decorators
+
+If you previously imported internal helpers (e.g., bridge serialization or transform helpers) from bare `'devflare'`, switch to the matching subpath. The internal modules are not considered stable public API and may change between minor versions.
+
 ---
 
 ## CLI
@@ -807,8 +843,8 @@ Every top-level command supports `--help`, and nested command groups support bot
 |---|---|
 | `devflare init` | scaffold a project using `src/fetch.ts` and explicit `files.fetch` |
 | `devflare dev` | start the worker-only dev server, enabling Vite only when the current package has a local `vite.config.*` |
-| `devflare build` | resolve config, generate Devflare/Wrangler build artifacts, and run `vite build` only for Vite-backed packages |
-| `devflare deploy` | build and deploy with Wrangler, including same-Worker preview uploads via `--preview` |
+| `devflare build` | resolve config locally, preserve named bindings in generated build artifacts, and run `vite build` only for Vite-backed packages |
+| `devflare deploy` | build or reuse a prior artifact via `--build`, provision named deploy resources, and deploy with Wrangler, including same-Worker preview uploads via `--preview` |
 | `devflare types` | generate `env.d.ts` |
 | `devflare doctor` | check project configuration plus generated artifact locations such as `.devflare/wrangler.jsonc`, `.devflare/build/wrangler.jsonc`, and `.wrangler/deploy/config.json` |
 | `devflare config` | print resolved Devflare config or resolved Wrangler JSON |
@@ -844,6 +880,7 @@ Command defaults:
 Useful flags:
 
 - `build --env <name>`
+- `deploy --build <path>`
 - `deploy --env <name>`
 - `deploy --dry-run`
 - `deploy --preview <name>`
@@ -882,6 +919,8 @@ Treat these as generated output, not source of truth:
 - `.wrangler/deploy/config.json`
 - `env.d.ts`
 
+`devflare build` keeps name-based bindings as names in these generated artifacts. `devflare deploy` is the step that resolves or provisions the concrete Cloudflare resources and rewrites the generated Wrangler config with the IDs Wrangler needs.
+
 The source of truth is still:
 
 - `devflare.config.ts`
@@ -890,6 +929,29 @@ The source of truth is still:
 
 ---
 
+## Maintainer scripts
+
+These scripts live in `packages/devflare/scripts/` and are intended for Devflare maintainers, not for end-user applications.
+
+### `refresh-permission-groups`
+
+Fetches the live Cloudflare permission-group catalog and rewrites `src/cloudflare/known-permission-group-ids.generated.ts` so the symbolic Devflare permission-group names (`WORKERS_SCRIPTS_WRITE`, etc.) map to verified Cloudflare UUIDs instead of falling back to display-name matching.
+
+```sh
+# from the repo root
+CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ACCOUNT_ID=... bun run --cwd packages/devflare refresh-permission-groups
+```
+
+Flags:
+
+- `--dry-run` — print the would-be generated file to stdout instead of writing to disk; useful for CI drift checks.
+- `--keep-existing` — keep the previously-known UUID for entries missing from the API response, instead of clearing them to `null`.
+- `--output <path>` — override the destination file; defaults to `packages/devflare/src/cloudflare/known-permission-group-ids.generated.ts`.
+
+The API token must have permission to read `/accounts/:id/tokens/permission_groups`. The script never touches `tokens.ts` directly, so the public matcher API and its display-name fallback continue to work even when the generated file ships with all-`null` entries.
+
+---
+
 ## In one sentence
 
 **Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development workflow that stays coherent as the app grows.**

package/bin/devflare.js

@@ -5,7 +5,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 
 const currentDir = dirname(fileURLToPath(import.meta.url))
 const sourceCliEntryPath = resolve(currentDir, '../src/cli/index.ts')
-const distCliEntryPath = resolve(currentDir, '../dist/src/cli/index.js')
+const distCliEntryPath = resolve(currentDir, '../dist/cli/index.js')
 const cliEntryPath = existsSync(sourceCliEntryPath)
 	? sourceCliEntryPath
 	: distCliEntryPath

package/dist/{account-fw8nafav.js → account-0evqkmnc.js}

@@ -1,11 +1,11 @@
 import {
   getConfiguredAccountId
-} from "./index-b8m6883k.js";
+} from "./index-82xn4azv.js";
 import {
   account
-} from "./index-7x0ybbtx.js";
-import"./index-72mve6vh.js";
-import"./index-2jnrqbny.js";
+} from "./index-btrfqp9h.js";
+import"./index-jwvy32xk.js";
+import"./index-8evn52g1.js";
 import {
   bold,
   createCliTheme,
@@ -24,18 +24,18 @@ import {
   DIM,
   RESET
 } from "./index-3t6rypgc.js";
-import"./index-fvsadj32.js";
-import"./index-yzddwp02.js";
+import"./index-6r59wbek.js";
+import"./index-waha3chv.js";
 import {
   getGlobalDefaultAccountId,
   getWorkspaceAccountId,
   setGlobalDefaultAccountId,
   setWorkspaceAccountId
-} from "./index-jb75kwa4.js";
+} from "./index-gba371j7.js";
 import {
   AuthenticationError,
   CloudflareAPIError
-} from "./index-0w826dsr.js";
+} from "./index-abrqnq3e.js";
 import"./index-p296ban8.js";
 import"./index-37x76zdn.js";
 

package/dist/{account-0w8wdzjv.js → account-0v11zbzk.js}

@@ -1,11 +1,11 @@
 import {
   getConfiguredAccountId
-} from "./index-zfhq6s96.js";
+} from "./index-6mg4yvc6.js";
 import {
   account
-} from "./index-e9yw4d6y.js";
-import"./index-72mve6vh.js";
-import"./index-epw1jxz5.js";
+} from "./index-btrfqp9h.js";
+import"./index-jwvy32xk.js";
+import"./index-8evn52g1.js";
 import {
   bold,
   createCliTheme,
@@ -24,19 +24,19 @@ import {
   DIM,
   RESET
 } from "./index-3t6rypgc.js";
-import"./index-7g8zyws4.js";
-import"./index-43dq8yx8.js";
+import"./index-6r59wbek.js";
+import"./index-tmmcf4m6.js";
 import {
   getGlobalDefaultAccountId,
   getWorkspaceAccountId,
   setGlobalDefaultAccountId,
   setWorkspaceAccountId
-} from "./index-xk9djfjp.js";
+} from "./index-gba371j7.js";
 import {
   AuthenticationError,
   CloudflareAPIError
-} from "./index-0w826dsr.js";
-import"./index-6jef5emv.js";
+} from "./index-abrqnq3e.js";
+import"./index-p296ban8.js";
 import"./index-37x76zdn.js";
 
 // src/cli/commands/account.ts

package/dist/{account-eygq6qx7.js → account-2w85efas.js}

@@ -1,11 +1,11 @@
 import {
   getConfiguredAccountId
-} from "./index-v5nmqthy.js";
+} from "./index-pyeycp3f.js";
 import {
   account
-} from "./index-sqrksgb2.js";
-import"./index-72mve6vh.js";
-import"./index-q4kaz181.js";
+} from "./index-8nx4ce3e.js";
+import"./index-f1gsqm54.js";
+import"./index-afjbpgb1.js";
 import {
   bold,
   createCliTheme,
@@ -24,19 +24,19 @@ import {
   DIM,
   RESET
 } from "./index-3t6rypgc.js";
-import"./index-7g8zyws4.js";
-import"./index-6psz1h4c.js";
+import"./index-zxhc6sb0.js";
+import"./index-dmbdj6va.js";
 import {
   getGlobalDefaultAccountId,
   getWorkspaceAccountId,
   setGlobalDefaultAccountId,
   setWorkspaceAccountId
-} from "./index-xk9djfjp.js";
+} from "./index-nte9n8w9.js";
 import {
   AuthenticationError,
   CloudflareAPIError
-} from "./index-0w826dsr.js";
-import"./index-6jef5emv.js";
+} from "./index-z9fjnwa8.js";
+import"./index-p296ban8.js";
 import"./index-37x76zdn.js";
 
 // src/cli/commands/account.ts

package/dist/{account-pzq69nys.js → account-61gw9s7t.js}

@@ -1,11 +1,11 @@
 import {
   getConfiguredAccountId
-} from "./index-na3mnm1k.js";
+} from "./index-hqdr9wdm.js";
 import {
   account
-} from "./index-8t5nb4qx.js";
-import"./index-72mve6vh.js";
-import"./index-htzf0py1.js";
+} from "./index-j2xdxwsz.js";
+import"./index-5m85bd9x.js";
+import"./index-79exzs3q.js";
 import {
   bold,
   createCliTheme,
@@ -24,19 +24,19 @@ import {
   DIM,
   RESET
 } from "./index-3t6rypgc.js";
-import"./index-fvsadj32.js";
-import"./index-0apbm26n.js";
+import"./index-2bmtj21z.js";
+import"./index-7vbjt6ba.js";
 import {
   getGlobalDefaultAccountId,
   getWorkspaceAccountId,
   setGlobalDefaultAccountId,
   setWorkspaceAccountId
-} from "./index-jb75kwa4.js";
+} from "./index-502y7w13.js";
 import {
   AuthenticationError,
   CloudflareAPIError
-} from "./index-0w826dsr.js";
-import"./index-6jef5emv.js";
+} from "./index-2vbzamev.js";
+import"./index-p296ban8.js";
 import"./index-37x76zdn.js";
 
 // src/cli/commands/account.ts