devflare 1.0.0-next.0 → 1.0.0-next.10

package/LLM.md

@@ -0,0 +1,1114 @@
+# Devflare
+
+This file is the truth-first contract for `devflare` as implemented today.
+
+Use it when you are:
+
+- generating code
+- reviewing code
+- updating docs
+
+Use `Quick start` for the safest defaults, `Trust map` when similar layers are getting mixed together, and `Sharp edges` before documenting advanced behavior. If an example and the implementation disagree, trust the implementation and update the docs.
+
+---
+
+## Quick start: safest supported path
+
+Prefer this shape unless you have a concrete reason not to:
+
+- explicit `files.fetch`
+- `src/fetch.ts` as the main HTTP entry
+- a named event-first `fetch(event)` or `handle(event)` export
+- request-wide middleware via `sequence(...)`
+- explicit bindings in config
+- `createTestContext()` for core integration tests
+- `ref()` for cross-worker composition
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'hello-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
+})
+```
+
+```ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function fetch(event: FetchEvent): Promise<Response> {
+	return Response.json({
+		path: new URL(event.request.url).pathname
+	})
+}
+```
+
+---
+
+## Trust map
+
+### Layers that are easy to confuse
+
+Keep these layers separate until you have a reason to connect them:
+
+1. config-time `process.env`
+2. `devflare.config.ts`
+3. generated `wrangler.jsonc`
+4. runtime Worker `env` bindings
+5. local dev/test helpers
+
+The classic mixups are:
+
+- `files.routes` vs top-level `routes`
+- `vars` vs `secrets`
+- Bun `.env` loading vs runtime secret loading
+- Devflare `config.env` overrides vs Wrangler environment blocks
+- main-entry `env` vs runtime `env`
+
+### Source of truth vs generated output
+
+Treat these as generated output, not authoring input:
+
+- `.devflare/`
+- `env.d.ts`
+- generated `wrangler.jsonc`
+
+The source of truth is still:
+
+- `devflare.config.ts`
+- your source files under `src/`
+- your tests
+
+If generated output looks wrong, fix the source and regenerate it. Do not hand-edit generated artifacts.
+
+---
+
+## What Devflare is
+
+Devflare is a developer-first layer on top of Cloudflare Workers tooling.
+
+It composes existing tools instead of replacing them:
+
+- **Miniflare** supplies the local Workers runtime
+- **Wrangler** supplies deployment config and deploy workflows
+- **Vite** participates when the current package opts into Vite-backed mode
+- **Bun** is the CLI runtime and affects process-level `.env` loading
+- **Devflare** ties those pieces into one authoring model
+
+Core public capabilities today:
+
+- typed config via `defineConfig()`
+- compilation from Devflare config into Wrangler-compatible output
+- event-first runtime helpers
+- request-scoped proxies and per-surface getters
+- typed multi-worker references via `ref()`
+- local orchestration around Miniflare, Vite, and test helpers
+- framework-aware Vite and SvelteKit integration
+
+Devflare is not a replacement runtime. It is a higher-level developer system that sits on top of the Cloudflare ecosystem.
+
+### Authoring model
+
+A **surface** is a distinct handler or entry file that Devflare treats as its own concern. The common surfaces are:
+
+- HTTP via `src/fetch.ts`
+- queue consumers via `src/queue.ts`
+- scheduled handlers via `src/scheduled.ts`
+- incoming email via `src/email.ts`
+- Durable Objects via `do.*.ts`
+- WorkerEntrypoints via `ep.*.ts`
+- workflows via `wf.*.ts`
+- custom transport definitions via `src/transport.ts`
+
+Prefer one responsibility per file unless you have a strong reason to combine surfaces. That keeps runtime behavior, testing, and multi-worker composition easier to reason about.
+
+---
+
+## Package entrypoints
+
+Use the narrowest import path that matches where the code runs.
+
+| Import | Use it for | Practical rule |
+|---|---|---|
+| `devflare` | main package entrypoint | config helpers, `ref()`, `workerName`, the main-entry `env`, and selected Node-side helpers |
+| `devflare/runtime` | handler/runtime code | event types, middleware, strict `env` / `ctx` / `event` / `locals`, and per-surface getters |
+| `devflare/test` | tests | `createTestContext()`, `cf.*`, and test helpers |
+| `devflare/vite` | Vite integration | explicit Vite-side helpers |
+| `devflare/sveltekit` | SvelteKit integration | SvelteKit-facing helpers |
+| `devflare/cloudflare` | Cloudflare account and resource helpers | account/resource/usage helpers |
+| `devflare/decorators` | decorators only | `durableObject()` and related decorator utilities |
+
+### `devflare` vs `devflare/runtime`
+
+Default rule:
+
+1. use handler parameters first
+2. use `devflare/runtime` in helpers that run inside a live handler trail
+3. use the main `devflare` entry when you specifically want the fallback-friendly `env`
+
+`import { env } from 'devflare/runtime'` is strict request-scoped access. It works only while Devflare has established an active handler context.
+
+`import { env } from 'devflare'` is the main-entry proxy. It prefers active handler context and can also fall back to test or bridge-backed context when no live request is active.
+
+Practical example:
+
+```ts
+// worker code
+import { env, locals, type FetchEvent } from 'devflare/runtime'
+
+export async function fetch(event: FetchEvent<DevflareEnv>): Promise<Response> {
+	const pathname = new URL(event.request.url).pathname
+	locals.startedAt = Date.now()
+
+	const cached = await env.CACHE.get(pathname)
+	if (cached) {
+		return new Response(cached, {
+			headers: {
+				'x-cache': 'hit'
+			}
+		})
+	}
+
+	return new Response(`miss:${pathname}`)
+}
+```
+
+```ts
+// test or bridge code
+import { env } from 'devflare'
+import { createTestContext } from 'devflare/test'
+
+await createTestContext()
+await env.CACHE.put('health', 'ok')
+```
+
+### Worker-safe caveat for the main entry
+
+`devflare/runtime` is the explicit worker-safe runtime entry and should be the default teaching path for worker code.
+
+The main `devflare` entry can also resolve to a worker-safe bundle when the resolver selects the package `browser` condition. Treat that as a compatibility detail, not as a signal that the main entry is the best place to import runtime helpers.
+
+In that worker-safe main bundle:
+
+- the browser-safe subset of the main entry remains usable
+- Node-side APIs such as config loading, CLI helpers, Miniflare orchestration, and test-context setup are not available and intentionally throw if called
+
+If you need `ctx`, `event`, `locals`, middleware, or per-surface getters, import them from `devflare/runtime`.
+
+---
+
+## Runtime and HTTP model
+
+### Event-first handlers are the public story
+
+Fresh Devflare code should be event-first. Use shapes like:
+
+- `fetch(event: FetchEvent)`
+- `queue(event: QueueEvent)`
+- `scheduled(event: ScheduledEvent)`
+- `email(event: EmailEvent)`
+- `tail(event: TailEvent)` when you are wiring a tail surface
+- Durable Object handlers with their matching event types
+
+These event types augment native Cloudflare inputs rather than replacing them with unrelated wrappers.
+
+| Event type | Also behaves like | Convenience fields |
+|---|---|---|
+| `FetchEvent` | `Request` | `request`, `env`, `ctx`, `params`, `locals`, `type` |
+| `QueueEvent` | `MessageBatch<T>` | `batch`, `env`, `ctx`, `locals`, `type` |
+| `ScheduledEvent` | `ScheduledController` | `controller`, `env`, `ctx`, `locals`, `type` |
+| `EmailEvent` | `ForwardableEmailMessage` | `message`, `env`, `ctx`, `locals`, `type` |
+| `TailEvent` | `TraceItem[]` | `events`, `env`, `ctx`, `locals`, `type` |
+| `DurableObjectFetchEvent` | `Request` | `request`, `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectAlarmEvent` | event object only | `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectWebSocketMessageEvent` | `WebSocket` | `ws`, `message`, `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectWebSocketCloseEvent` | `WebSocket` | `ws`, `code`, `reason`, `wasClean`, `env`, `ctx`, `state`, `locals`, `type` |
+| `DurableObjectWebSocketErrorEvent` | `WebSocket` | `ws`, `error`, `env`, `ctx`, `state`, `locals`, `type` |
+
+On worker surfaces, `event.ctx` is the current `ExecutionContext`.
+
+On Durable Object surfaces, `event.ctx` is the current `DurableObjectState`, and Devflare also exposes it as `event.state` for clarity.
+
+### Runtime access: parameters, getters, and proxies
+
+Prefer runtime access in this order:
+
+1. handler parameters such as `fetch(event: FetchEvent)`
+2. per-surface getters when a deeper helper needs the current concrete surface
+3. generic runtime proxies when surface-agnostic access is enough
+
+Devflare carries the active event through the current handler call trail, so deeper helpers can recover the current surface without manually threading arguments.
+
+Proxy semantics:
+
+- `env`, `ctx`, and `event` from `devflare/runtime` are readonly
+- `locals` is the mutable request-scoped storage object
+- `event.locals` and `locals` point at the same underlying object
+- strict runtime helpers throw when there is no active Devflare-managed context
+
+Per-surface getters:
+
+- worker surfaces: `getFetchEvent()`, `getQueueEvent()`, `getScheduledEvent()`, `getEmailEvent()`, `getTailEvent()`
+- Durable Object surfaces: `getDurableObjectEvent()`, `getDurableObjectFetchEvent()`, `getDurableObjectAlarmEvent()`
+- Durable Object WebSocket surfaces: `getDurableObjectWebSocketMessageEvent()`, `getDurableObjectWebSocketCloseEvent()`, `getDurableObjectWebSocketErrorEvent()`
+
+Every getter also exposes `.safe()`, which returns `null` instead of throwing.
+
+Practical example:
+
+```ts
+import { getFetchEvent, locals, type FetchEvent } from 'devflare/runtime'
+
+function currentPath(): string {
+	return new URL(getFetchEvent().request.url).pathname
+}
+
+export async function fetch(event: FetchEvent): Promise<Response> {
+	locals.requestId = crypto.randomUUID()
+
+	return Response.json({
+		path: currentPath(),
+		requestId: String(locals.requestId),
+		requestUrl: getFetchEvent.safe()?.request.url ?? null,
+		method: event.request.method
+	})
+}
+```
+
+### Manual context helpers are advanced/internal
+
+Normal Devflare application code should **not** need `runWithEventContext()` or `runWithContext()`.
+
+Devflare establishes the active event/context automatically before invoking user code in the flows developers normally use:
+
+- generated worker entrypoints for `fetch`, `queue`, `scheduled`, and `email`
+- Durable Object wrappers
+- HTTP middleware and route resolution
+- `createTestContext()` helpers such as `cf.worker`, `cf.queue`, `cf.scheduled`, `cf.email`, and `cf.tail`
+
+That means getters like `getQueueEvent()`, `getScheduledEvent()`, `getEmailEvent()`, and `getDurableObjectFetchEvent()` should work inside ordinary handlers without manual wrapping.
+
+Keep these helpers in the "advanced escape hatch" bucket:
+
+- `runWithEventContext(event, fn)` preserves the exact event you provide
+- `runWithContext(env, ctx, request, fn, type)` is a lower-level compatibility helper
+
+Important difference:
+
+- `runWithContext()` only synthesizes rich augmented events for `fetch` and `durable-object-fetch` when a `Request` is available
+- if you are manually constructing a non-fetch surface and truly need per-surface getters outside normal Devflare-managed entrypoints, `runWithEventContext()` is the correct low-level helper
+
+### HTTP entry, middleware, and method handlers
+
+Think of the built-in HTTP path today as:
+
+`src/fetch.ts` request-wide entry → same-module method handlers → matched `src/routes/**` leaf module
+
+When the HTTP surface matters to build or deploy output, prefer making it explicit in config:
+
+```ts
+files: {
+	fetch: 'src/fetch.ts'
+}
+```
+
+The file router is enabled automatically when a `src/routes` directory exists, unless you set `files.routes: false`.
+Use `files.routes` when you want to change the route root or mount it under a prefix.
+
+Supported primary entry shapes today:
+
+- `export async function fetch(...) { ... }`
+- `export const fetch = ...`
+- `export const handle = ...`
+- `export default async function (...) { ... }`
+- `export default { fetch(...) { ... } }`
+- `export default { handle(...) { ... } }`
+
+`fetch` and `handle` are aliases for the same primary HTTP entry. Export one or the other, not both.
+
+When this document says a `handle` export here, it means the primary fetch export name, not the legacy `handle(...handlers)` helper.
+
+Request-wide middleware belongs in `src/fetch.ts` and composes with `sequence(...)`.
+
+```ts
+import { sequence } from 'devflare/runtime'
+import type { FetchEvent, ResolveFetch } from 'devflare/runtime'
+
+async function authHandle(event: FetchEvent, resolve: ResolveFetch): Promise<Response> {
+	if (!event.request.headers.get('authorization')) {
+		return new Response('Unauthorized', { status: 401 })
+	}
+
+	return resolve(event)
+}
+
+async function appFetch({ request }: FetchEvent): Promise<Response> {
+	return new Response(new URL(request.url).pathname)
+}
+
+export const handle = sequence(authHandle, appFetch)
+```
+
+`sequence(...)` uses the usual nested middleware flow:
+
+1. outer middleware before `resolve(event)`
+2. inner middleware before `resolve(event)`
+3. downstream leaf handler
+4. inner middleware after `resolve(event)`
+5. outer middleware after `resolve(event)`
+
+Same-module method exports are real runtime behavior:
+
+- method handlers such as `GET`, `POST`, and `ALL` are supported in the fetch module
+- if `HEAD` is not exported, it falls back to `GET` with an empty body
+- this is same-module dispatch, not file-system routing
+- if a module exports a primary `fetch` or `handle` entry and also exports method handlers, the method handlers are the downstream leaf handlers reached through `resolve(event)`
+- if no primary `fetch` or `handle` exists, Devflare can still dispatch directly to same-module method handlers
+
+### Routing today
+
+`src/routes/**` is now a real built-in router.
+
+Default behavior:
+
+- if `src/routes` exists, Devflare discovers it automatically
+- `files.routes.dir` changes the route root
+- `files.routes.prefix` mounts the discovered routes under a fixed prefix such as `/api`
+- `files.routes: false` disables file-route discovery
+
+Filename conventions:
+
+- `index.ts` → directory root
+- `[id].ts` → single dynamic segment
+- `[...slug].ts` → rest segment, one or more path parts
+- `[[...slug]].ts` → optional rest segment, including the directory root
+- files or directories beginning with `_` are ignored so route-local helpers can live beside handlers
+
+Dispatch semantics:
+
+- route params are populated on `event.params`
+- route modules use the same handler forms as fetch modules: HTTP method exports, primary `fetch`, or primary `handle`
+- if `src/fetch.ts` exports same-module `GET` / `POST` / `ALL` handlers, those run before the file router for matching methods
+- for route-tree apps, keep `src/fetch.ts` focused on request-wide middleware and whole-app concerns
+- `resolve(event)` from the primary fetch module falls through to the matched route module when no same-module method handler responded
+
+| Key | What it means today | What it does not do |
+|---|---|---|
+| `files.routes` | built-in file router configuration for `src/routes/**` discovery, custom route roots, and optional prefixes | it does not replace top-level Cloudflare deployment `routes` |
+| top-level `routes` | Cloudflare deployment route patterns such as `example.com/*`, compiled into generated Wrangler config | it does not choose handlers inside your app |
+| `wsRoutes` | dev-only WebSocket proxy rules that forward matching local upgrade requests to Durable Objects | it does not replace deployment `routes` or act as general HTTP app routing |
+
+Practical route-tree example:
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'api-worker',
+	files: {
+		fetch: 'src/fetch.ts',
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		}
+	}
+})
+```
+
+```ts
+// src/fetch.ts
+import { sequence } from 'devflare/runtime'
+
+export const handle = sequence(async (event, resolve) => {
+	const response = await resolve(event)
+	const next = new Response(response.body, response)
+	next.headers.set('x-user-id', event.params.id ?? 'none')
+	return next
+})
+```
+
+```ts
+// src/routes/users/[id].ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function GET({ params }: FetchEvent): Promise<Response> {
+	return Response.json({ id: params.id })
+}
+```
+
+```ts
+// GET /api/users/123
+// -> { "id": "123" }
+// and x-user-id: 123
+```
+
+---
+
+## Configuration and compilation
+
+### Stable config flow
+
+This is the stable public flow for Devflare config:
+
+1. write `devflare.config.*` and export it with `defineConfig()`
+2. Devflare loads the base config
+3. if you select an environment, Devflare merges `config.env[name]` into the base config
+4. Devflare compiles the resolved config into Wrangler-compatible output
+5. commands such as `dev`, `build`, `deploy`, and `types` use that resolved config for their own work
+
+Current implementation note: Devflare validates config against its schema before compilation, and some commands write generated `wrangler.jsonc` files as build artifacts. Treat generated Wrangler config as output, not source of truth.
+
+### Supported config files and `defineConfig()`
+
+Supported config filenames:
+
+- `devflare.config.ts`
+- `devflare.config.mts`
+- `devflare.config.js`
+- `devflare.config.mjs`
+
+Use a plain object when your config is static. Use a sync or async function when you need to compute values from `process.env`, the selected environment, or project state.
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'api-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		APP_NAME: 'api-worker'
+	}
+})
+```
+
+TypeScript note: `defineConfig<T>()` is an advanced typing helper. It is mainly useful when you want stronger `ref()` and entrypoint inference after `env.d.ts` exists.
+
+### Top-level keys
+
+Most projects only need a small set of config keys at first. Start with `name`, `compatibilityDate`, `files`, and the `bindings`, `vars`, `secrets`, `triggers`, `routes`, or `env` your worker actually needs.
+
+Current defaults worth knowing:
+
+- `compatibilityDate` defaults to the current date when omitted
+- current default compatibility flags include `nodejs_compat` and `nodejs_als`
+
+Common keys:
+
+| Key | Use it for |
+|---|---|
+| `name` | Worker name |
+| `compatibilityDate` | Workers compatibility date |
+| `compatibilityFlags` | Workers compatibility flags |
+| `files` | explicit handler paths and discovery globs |
+| `bindings` | Cloudflare bindings |
+| `triggers` | scheduled trigger config |
+| `vars` | non-secret string bindings |
+| `secrets` | secret binding declarations |
+| `routes` | Cloudflare deployment routes |
+| `env` | environment overrides merged before compile |
+
+Secondary keys:
+
+| Key | Use it for |
+|---|---|
+| `accountId` | account selection for remote and deploy flows |
+| `observability` | Workers observability settings |
+| `migrations` | Durable Object migrations |
+| `assets` | static asset config |
+| `limits` | worker limits |
+| `wsRoutes` | local WebSocket proxy rules for dev |
+| `vite` | Devflare Vite metadata |
+| `rolldown` | worker-only bundler options |
+| `wrangler.passthrough` | raw Wrangler overrides after compile |
+
+### Native config coverage vs `wrangler.passthrough`
+
+Devflare natively models the common Worker config it actively composes around. It does **not** try to mirror every Wrangler field one-by-one as a first-class Devflare schema key.
+
+Use `wrangler.passthrough` for unsupported Wrangler options.
+
+Current merge order is:
+
+1. compile native Devflare config
+2. shallow-merge `wrangler.passthrough` on top
+3. if the same key exists in both places, the passthrough value wins
+
+Practical example:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'advanced-worker',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	wrangler: {
+		passthrough: {
+			placement: {
+				mode: 'smart'
+			}
+		}
+	}
+})
+```
+
+Two practical rules:
+
+- if you want Devflare-managed entry composition, keep using `files.fetch`, `files.routes`, and related surface config, and do **not** set `wrangler.passthrough.main`
+- if you want total control of the Worker `main` entry, set `wrangler.passthrough.main` and own that entry file yourself
+
+### `files`
+
+`files` tells Devflare where your surfaces live. Use explicit paths for any surface that matters to build or deploy output, especially `files.fetch`.
+
+| Key | Shape | Default convention | Meaning |
+|---|---|---|---|
+| `fetch` | <code>string &#124; false</code> | `src/fetch.ts` | main HTTP handler |
+| `queue` | <code>string &#124; false</code> | `src/queue.ts` | queue consumer handler |
+| `scheduled` | <code>string &#124; false</code> | `src/scheduled.ts` | scheduled handler |
+| `email` | <code>string &#124; false</code> | `src/email.ts` | incoming email handler |
+| `durableObjects` | <code>string &#124; false</code> | `**/do.*.{ts,js}` | Durable Object discovery glob |
+| `entrypoints` | <code>string &#124; false</code> | `**/ep.*.{ts,js}` | WorkerEntrypoint discovery glob |
+| `workflows` | <code>string &#124; false</code> | `**/wf.*.{ts,js}` | workflow discovery glob |
+| `routes` | <code>{ dir, prefix? } &#124; false</code> | `src/routes` when that directory exists | built-in file router configuration |
+| `transport` | `string` | none | custom transport definition file |
+
+Discovery does not behave identically in every subsystem:
+
+- local dev and `createTestContext()` can fall back to conventional handler files when present
+- local dev, `createTestContext()`, and higher-level worker-entry generation also auto-discover `src/routes/**` unless `files.routes` is `false`
+- type generation and discovery use default globs for Durable Objects, entrypoints, and workflows
+- `compileConfig()` only writes Wrangler `main` when `files.fetch` is explicit
+- higher-level `build`, `deploy`, and `devflare/vite` flows may still generate a composed `.devflare/worker-entrypoints/main.ts`, including route trees
+- `wrangler.passthrough.main` disables that composed-entry generation path
+
+Safe rule: if a surface matters to build or deploy output, declare it explicitly even if another subsystem can discover it by convention.
+
+Practical example:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'multi-surface-worker',
+	files: {
+		fetch: 'src/fetch.ts',
+		queue: 'src/queue.ts',
+		scheduled: 'src/scheduled.ts',
+		email: 'src/email.ts',
+		routes: {
+			dir: 'src/routes',
+			prefix: '/api'
+		},
+		durableObjects: 'src/do/**/*.ts',
+		entrypoints: 'src/rpc/**/*.ts',
+		workflows: 'src/workflows/**/*.ts'
+	}
+})
+```
+
+`files.transport` is opt-in. Devflare only loads it when `files.transport` is explicitly set, and the file must export a named `transport` object.
+
+There is no public `files.tail` config key today.
+
+### `.env`, `vars`, `secrets`, and `config.env`
+
+Keep these layers separate:
+
+| Layer | Holds values? | Compiled into generated config? | Use it for |
+|---|---|---|---|
+| `.env` / `process.env` | yes | indirectly, only when your config reads from it | local process-time inputs |
+| `vars` | yes | yes | non-secret string bindings |
+| `secrets` | no, declaration only | no | required/optional runtime secret bindings |
+| `config.env` | yes, as config overlays | yes after merge | environment-specific config overrides |
+
+#### `.env` and process env
+
+`loadConfig()` does not do dotenv loading by itself. The Devflare CLI runs under Bun, and Bun may auto-load `.env` files into `process.env`.
+
+#### `vars`
+
+Use `vars` for non-secret runtime values that can safely appear in generated config, such as public URLs, modes, IDs, and feature flags.
+
+In the current native Devflare schema, `vars` is:
+
+```ts
+Record<string, string>
+```
+
+#### `secrets`
+
+`secrets` is a declaration layer. Use it to say which secret bindings your worker expects and whether they are required. Do not put secret values here.
+
+In the current schema, each secret has the shape:
+
+```ts
+{ required?: boolean }
+```
+
+`required` defaults to `true`, so this:
+
+```ts
+secrets: {
+	API_KEY: {}
+}
+```
+
+means “`API_KEY` is a required runtime secret,” not “optional secret with no requirements.”
+
+#### `devflare types`
+
+`devflare types` generates `env.d.ts` from the resolved config plus discovered surfaces. The stable public result is typed `DevflareEnv` coverage for bindings such as `vars`, `secrets`, services, Durable Objects, and discovered entrypoints.
+
+Import-path behavior stays the same as described earlier: the main-entry `env` is the broader typed access story, while `devflare/runtime` is the strict request-scoped runtime helper.
+
+#### `config.env`
+
+`config.env` is Devflare’s environment override layer. When you pass `--env <name>` or call `compileConfig(config, name)`, Devflare starts from the base config, merges `config.env[name]` into it, and compiles the resolved result.
+
+Current merge behavior uses deep merge semantics:
+
+- scalar fields override base values
+- nested objects inherit omitted keys
+- arrays append instead of replacing
+- `null` and `undefined` do not delete base values
+
+If you need full replacement behavior, compute the final value in `defineConfig()` instead of relying on `config.env`.
+
+Example:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'api',
+	files: {
+		fetch: 'src/fetch.ts'
+	},
+	vars: {
+		APP_ENV: 'development',
+		API_ORIGIN: 'http://localhost:3000'
+	},
+	bindings: {
+		kv: {
+			CACHE: 'api-cache-dev'
+		}
+	},
+	env: {
+		production: {
+			vars: {
+				APP_ENV: 'production',
+				API_ORIGIN: 'https://api.example.com'
+			},
+			bindings: {
+				kv: {
+					CACHE: 'api-cache'
+				}
+			}
+		}
+	}
+})
+```
+
+With `--env production`, the resolved config keeps `files.fetch`, overrides the `vars`, and overrides `bindings.kv.CACHE`.
+
+Current limitation: `accountId` and `wsRoutes` are not supported inside `config.env`. Compute those in the outer `defineConfig()` function when you need environment-specific values.
+
+---
+
+## Bindings and multi-worker composition
+
+### Binding groups
+
+| Group | Members | Coverage wording | Safe promise |
+|---|---|---|---|
+| Core bindings | `kv`, `d1`, `r2`, `durableObjects`, `queues.producers`, `queues.consumers` | well-covered | safest public binding path today across config, generated types, and local dev/test |
+| Services and `ref()` | `services` | well-covered with a named-entrypoint caveat | worker-to-worker composition is solid; validate generated output when a named entrypoint matters |
+| Remote-oriented bindings | `ai`, `vectorize` | remote-dependent | supported and typed, but not full local equivalents of KV or D1 |
+| Narrower bindings | `hyperdrive`, `analyticsEngine`, `browser` | supported, narrower-scope | real public surfaces, but less central than the core storage/runtime path |
+| Outbound email binding | `sendEmail` | supported public surface | real outbound email binding; keep it separate from inbound email handling |
+
+### Core bindings
+
+KV, D1, R2, Durable Objects, and queues have the clearest end-to-end story today across config, generated types, and local dev/test flows.
+
+### R2 browser access and public URLs
+
+`bindings.r2` gives you real R2 binding access in local dev, tests, generated types, and compiled config.
+
+What Devflare does **not** currently expose as a public contract is a stable browser-facing local bucket URL.
+
+If you need browser-visible local asset flows:
+
+- serve them through your Worker routes or app endpoints
+- test real public/custom-domain URL behavior against an intentional staging bucket
+- do not hard-code frontend assumptions about a magic local bucket origin
+
+For delivery patterns and production recommendations, see [`R2.md`](./R2.md).
+
+Practical example:
+
+```ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'orders-worker',
+	bindings: {
+		kv: {
+			CACHE: 'orders-cache'
+		},
+		d1: {
+			DB: 'orders-db'
+		},
+		durableObjects: {
+			COUNTER: 'Counter'
+		},
+		queues: {
+			producers: {
+				TASK_QUEUE: 'orders-tasks'
+			}
+		}
+	}
+})
+```
+
+```ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function POST({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	const status = await env.DB.prepare('select 1 as ok').first()
+	await env.CACHE.put('health', JSON.stringify(status))
+	await env.TASK_QUEUE.send({ type: 'reindex-orders' })
+	return Response.json({ ok: true })
+}
+```
+
+### Services and named entrypoints
+
+Service bindings can be written directly or via `ref()`.
+
+```ts
+import { defineConfig, ref } from 'devflare'
+
+const auth = ref(() => import('../auth/devflare.config'))
+
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			AUTH: auth.worker,
+			ADMIN: auth.worker('AdminEntrypoint')
+		}
+	}
+})
+```
+
+Direct worker-to-worker service composition is a strong public path. Named service entrypoints are typed and configurable, but if a specific entrypoint matters at deployment time, validate the generated output in your project.
+
+Practical example:
+
+```ts
+// gateway/devflare.config.ts
+import { defineConfig, ref } from 'devflare'
+
+const auth = ref(() => import('../auth/devflare.config'))
+
+export default defineConfig({
+	name: 'gateway',
+	bindings: {
+		services: {
+			ADMIN: auth.worker('AdminEntrypoint')
+		}
+	}
+})
+```
+
+```ts
+// gateway/src/fetch.ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function GET({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	const stats = await env.ADMIN.getStats()
+	return Response.json(stats)
+}
+```
+
+### Remote-oriented and narrower bindings
+
+`ai` and `vectorize` are remote-dependent bindings. Devflare supports their config and typing, but they should not be documented as full local equivalents of KV or D1.
+
+`hyperdrive`, `analyticsEngine`, and `browser` are supported narrower-scope surfaces. `browser` also sits closer to the dev-orchestration layer than to the core fetch/queue path.
+
+### `sendEmail` and inbound email
+
+`sendEmail` is the outbound email binding surface. It is supported across config, generated types, and local development flows.
+
+Incoming email is a separate worker surface:
+
+- `files.email`
+- `src/email.ts`
+- `EmailEvent`
+
+Keep outbound `sendEmail` and inbound email handling separate in docs and examples.
+
+Practical example:
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare'
+
+export default defineConfig({
+	name: 'mail-worker',
+	files: {
+		fetch: 'src/fetch.ts',
+		email: 'src/email.ts'
+	},
+	bindings: {
+		sendEmail: {
+			EMAIL: {
+				destinationAddress: 'team@example.com'
+			}
+		}
+	}
+})
+```
+
+```ts
+// src/fetch.ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function POST({ env }: FetchEvent<DevflareEnv>): Promise<Response> {
+	await env.EMAIL.send({
+		from: 'noreply@example.com',
+		to: 'team@example.com',
+		subject: 'Welcome',
+		text: 'Hello from Devflare'
+	})
+
+	return new Response('sent')
+}
+```
+
+```ts
+// src/email.ts
+import type { EmailEvent } from 'devflare/runtime'
+
+export async function email({ message }: EmailEvent<DevflareEnv>): Promise<void> {
+	await message.forward('ops@example.com')
+}
+```
+
+### `ref()` and multi-worker composition
+
+Use `ref()` when one worker depends on another worker config.
+
+Main public story:
+
+- `ref(...).worker` for a default service binding backed by `src/worker.ts` or `src/worker.js`
+- `ref(...).worker('EntrypointName')` for a named service entrypoint
+- typed cross-worker Durable Object handles
+
+```ts
+const auth = ref(() => import('../auth/devflare.config'))
+```
+
+```ts
+const auth = ref('custom-auth-name', () => import('../auth/devflare.config'))
+```
+
+Why `ref()` matters:
+
+- worker names stay centralized
+- cross-worker Durable Object bindings stay typed
+- entrypoint names can be typed from generated `Entrypoints`
+- multi-worker systems avoid scattered magic strings
+
+Advanced members such as `.name`, `.config`, `.configPath`, and `.resolve()` are real, but secondary to the main composition story.
+
+---
+
+## Development workflows
+
+### Operational decision rules
+
+Use these rules in order:
+
+1. a local `vite.config.*` in the current package decides whether `dev`, `build`, and `deploy` run in Vite-backed mode or worker-only mode
+2. `devflare/vite` is an explicit helper layer, not a separate CLI mode
+3. worker-only mode is a supported first-class path; no local `vite.config.*` means Devflare does not start Vite
+4. raw Vite config belongs in `vite.config.*`; `config.vite` is Devflare metadata, not full Vite config
+5. treat `.devflare/*`, `env.d.ts`, and generated Wrangler config as outputs, not authoring inputs
+6. remote mode is mainly for remote-oriented services such as AI and Vectorize, not a blanket “make everything remote” switch
+
+### Daily development loop
+
+Use the same CLI loop for both worker-only and Vite-backed packages. The presence of a local `vite.config.*` changes the mode automatically.
+
+```bash
+bunx --bun devflare dev
+bunx --bun devflare types
+bunx --bun devflare doctor
+bunx --bun devflare build --env staging
+bunx --bun devflare deploy --dry-run --env staging
+```
+
+Use `--env <name>` on build and deploy when you want Devflare to resolve a named config environment before compilation.
+
+### CLI reference
+
+| Command | What it does | Important note |
+|---|---|---|
+| `devflare init` | scaffold a project | current templates generate `src/fetch.ts` and explicit `files.fetch` |
+| `devflare dev` | start local development | worker-only by default, Vite-backed only when the current package has a local `vite.config.*` |
+| `devflare build` | build from resolved config | skips Vite for worker-only packages |
+| `devflare deploy` | build and deploy | supports `--env` and `--dry-run` |
+| `devflare types` | generate `env.d.ts` | supports `--output` |
+| `devflare doctor` | check project configuration | supports `--config` |
+| `devflare account` | inspect accounts, resources, usage, and limits | `global` and `workspace` are account-selection flows, not resource-reporting subcommands |
+| `devflare ai` | show Workers AI model pricing | informational command |
+| `devflare remote` | manage remote test mode | helper flow for remote-oriented services |
+| `devflare help` | show help | direct command and flag form both work |
+| `devflare version` | show package version | sourced from installed package metadata |
+
+### `doctor`
+
+Current `doctor` behavior:
+
+- it checks for supported Devflare config filenames
+- it can inspect an explicit config path via `--config`
+- it accepts project-root `wrangler.jsonc`
+- Vite-backed flows may instead generate `.devflare/wrangler.jsonc`
+
+---
+
+## Testing model
+
+Use `devflare/test`.
+
+The default pairing is:
+
+```ts
+import { beforeAll, afterAll } from 'bun:test'
+import { createTestContext } from 'devflare/test'
+import { env } from 'devflare'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+```
+
+`createTestContext()` is the recommended default for most integration-style tests.
+
+Current behavior:
+
+- it can auto-discover the nearest supported config file by walking upward from the calling test file
+- it sets up the main-entry test env used by `import { env } from 'devflare'`
+- it resolves service bindings and cross-worker Durable Object references
+- it can infer conventional fetch, queue, scheduled, and email handler files when present
+- it also auto-detects `src/tail.ts` when present, even though there is no public `files.tail` config key
+- `files.transport` is opt-in rather than auto-loaded by filename convention
+
+Practical example:
+
+```ts
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { cf, createTestContext } from 'devflare/test'
+import { env } from 'devflare'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+describe('users routes', () => {
+	test('GET /users/123 uses the built-in file router', async () => {
+		const response = await cf.worker.get('/users/123')
+		expect(response.status).toBe(200)
+		expect(await response.json()).toEqual({ id: '123' })
+	})
+
+	test('queue side effects can be asserted with real bindings', async () => {
+		await cf.queue.trigger([
+			{ type: 'reindex', id: 'job-1' }
+		])
+
+		expect(await env.RESULTS.get('job-1')).toBe('done')
+	})
+})
+```
+
+### Helper behavior
+
+Do not assume every `cf.*` helper behaves the same way.
+
+| Helper | What it does | Waits for `waitUntil()`? | Important nuance |
+|---|---|---|---|
+| `cf.worker.fetch()` | invokes the configured HTTP surface, including built-in file routes | No | returns when the handler resolves |
+| `cf.queue.trigger()` | invokes the configured queue consumer | Yes | drains queued background work before returning |
+| `cf.scheduled.trigger()` | invokes the configured scheduled handler | Yes | drains queued background work before returning |
+| `cf.email.send()` | sends a raw email through the helper | Yes on the direct-handler path; fallback endpoint behavior is runtime-driven | when `createTestContext()` has wired an email handler, it imports and invokes that handler directly; otherwise it falls back to the local email endpoint |
+| `cf.tail.trigger()` | directly invokes a tail handler | Yes | `createTestContext()` auto-detects `src/tail.ts` when present, but there is still no public `files.tail` config key |
+
+Two important consequences:
+
+- `cf.worker.fetch()` is not a “wait for all background work” helper
+- helper availability does not mean every helper replays the full Cloudflare dispatch path in the same way
+
+### Email testing
+
+Email testing has two directions:
+
+- incoming email helper dispatch via `cf.email.send()` / `email.send()`
+- outgoing email observation via helper state
+
+When `createTestContext()` has wired an email handler, the helper imports that handler directly, creates an `EmailEvent`, and waits for queued `waitUntil()` work.
+
+If no email handler has been wired, the helper falls back to posting the raw email to the local email endpoint.
+
+That makes the helper useful for handler-level tests, but ingress-fidelity-sensitive flows should still use higher-level integration testing.
+
+### Tail testing
+
+Tail helpers are exported publicly, and `createTestContext()` auto-detects `src/tail.ts` when present.
+
+So the truthful public statement is:
+
+- `cf.tail.trigger()` is exported
+- `createTestContext()` wires it automatically when `src/tail.ts` exists
+- `cf.tail.trigger()` directly imports and invokes that handler and waits for `waitUntil()`
+- there is no public `files.tail` config key to advertise today
+
+### Remote mode in tests
+
+Remote mode is mainly about AI and Vectorize. Use `shouldSkip` for cost-sensitive or remote-only test gating. Do not treat remote mode as a blanket “make every binding remote” switch.
+
+---
+
+## Sharp edges
+
+Keep these caveats explicit:
+
+- `files.routes` configures the built-in file router; it is not the same thing as Cloudflare deployment `routes`
+- route trees are real now, but `src/fetch.ts` same-module method handlers still take precedence over file routes for matching methods
+- route files that normalize to the same pattern are rejected as conflicts
+- `_`-prefixed files and directories inside the route tree are ignored
+- `vars` values are strings in the current native schema
+- `secrets` declares runtime secret bindings; it does not store secret values
+- `wrangler.passthrough` is the escape hatch for unsupported Wrangler keys and is merged after native compilation
+- named service entrypoints need deployment-time validation if they are critical to your app
+- local R2 binding support is real, but there is still no stable public/browser local bucket URL contract to document as public API
+- `sendEmail` is a supported outbound binding, while inbound email is a separate worker surface
+- email and tail helpers have real, useful test paths, but they should not be described as identical to full Cloudflare ingress or tail replay
+- Vite and Rolldown are different systems and should not be blurred together
+- higher-level flows may generate composed main worker entries more aggressively than older docs implied
+
+---
+
+## Summary
+
+Prefer explicit config over discovery, separated surfaces over a monolithic Worker file, and generated output as output rather than source. The safest public path today is explicit `files.fetch`, event-first handlers, explicit bindings, `createTestContext()` for core tests, and `ref()` for cross-worker composition.