devflare 1.0.0-next.2 → 1.0.0-next.21

package/README.md

@@ -1,605 +1,383 @@
-# Devflare
-
-**Build Cloudflare Workers like an application, not a pile of glue.**
-
-Devflare is a developer-first toolkit for Cloudflare Workers built on top of Miniflare, Bun, Vite, and Wrangler-compatible configuration.
-
-It gives you:
-
-- typed config with `defineConfig()`
-- convention-first file discovery
-- local orchestration for multi-surface Worker apps
-- first-class Durable Object and multi-worker workflows
-- testing APIs that mirror real handler surfaces
-- browser-rendering support in local development
-- Vite and SvelteKit integration
-
-Miniflare gives you a local runtime.
-
-Devflare turns that runtime into a **coherent development system**.
-
-For the exhaustive package-facing guide, including caveats and deeper config semantics, see [`LLM.md`](./LLM.md).
-
----
-
-## What Devflare adds
-
-Devflare does **not** replace Miniflare or Wrangler.
-
-It adds the higher-level workflow around them:
-
-- convention-first file structure
-- config validation and compilation
-- typed cross-worker references via `ref()`
-- unified testing helpers for `fetch`, `queue`, `scheduled`, `email`, and `tail`
-- bridge-backed local development where needed
-- framework-aware integration for Vite and SvelteKit
-
-The result is a Worker app that stays structured as it grows instead of slowly becoming a single-file boss fight.
-
----
-
-## Install
-
-For the recommended full workflow, install Devflare together with Wrangler, Vite, and the Cloudflare Vite plugin:
-
-```bash
-bun add -d devflare wrangler vite @cloudflare/vite-plugin
-```
-
-If you only need the library APIs and not the default Vite-based workflow, you can install fewer packages. The default CLI and diagnostics are built around the Vite + Cloudflare plugin setup.
-
----
-
-## Quick start
-
-### 1. Create a config
-
-```ts
-// devflare.config.ts
-import { defineConfig } from 'devflare'
-
-export default defineConfig({
-	name: 'hello-worker',
-	files: {
-		fetch: 'src/fetch.ts'
-	}
-})
-```
-
-### 2. Add a fetch handler
-
-```ts
-// src/fetch.ts
-export default async function fetch(): Promise<Response> {
-	return new Response('Hello from Devflare')
-}
-```
-
-### 3. Generate types
-
-```bash
-bunx --bun devflare types
-```
-
-This generates `env.d.ts` so bindings, secrets, and discovered entrypoints stay typed.
-
-### 4. Start development
-
-```bash
-bunx --bun devflare dev
-```
-
-### 5. Add a test
-
-```ts
-// tests/worker.test.ts
-import { beforeAll, afterAll, describe, expect, test } from 'bun:test'
-import { createTestContext, cf } from 'devflare/test'
-import { env } from 'devflare'
-
-beforeAll(() => createTestContext())
-afterAll(() => env.dispose())
-
-describe('hello-worker', () => {
-	test('GET / returns text', async () => {
-		const response = await cf.worker.get('/')
-		expect(response.status).toBe(200)
-		expect(await response.text()).toBe('Hello from Devflare')
-	})
-})
-```
-
----
-
-## Package entrypoints
-
-Use subpaths intentionally.
-
-| Import | Use for |
-|---|---|
-| `devflare` | main package entrypoint: config helpers, `ref()`, unified `env`, CLI helpers, bridge helpers, decorators, test helpers, `workerName` |
-| `devflare/runtime` | worker-safe middleware/validation/decorator utilities |
-| `devflare/test` | `createTestContext`, `cf.*`, mock helpers, bridge test context, skip helpers |
-| `devflare/vite` | Vite integration |
-| `devflare/sveltekit` | SvelteKit integration |
-| `devflare/cloudflare` | Cloudflare account/auth/usage/limits/preferences helpers |
-| `devflare/decorators` | decorators only |
-
-### Important runtime note
-
-The published `devflare/runtime` subpath is intentionally smaller than the main package. If you want the unified `env` proxy, import it from `devflare`, not `devflare/runtime`.
-
----
-
-## Config model
-
-### `defineConfig()` is the source of truth
-
-Devflare works best when everything flows from `devflare.config.ts`.
-
-`defineConfig()` supports:
-
-- a plain object
-- a sync function
-- an async function
-
-It also supports a generic parameter for generated entrypoint typing.
-
-### Config file names
-
-Devflare looks for these config filenames:
-
-- `devflare.config.ts`
-- `devflare.config.mts`
-- `devflare.config.js`
-- `devflare.config.mjs`
-
-### Top-level config keys
-
-These are the main config keys Devflare understands today.
-
-| Key | What it means |
-|---|---|
-| `name` | Worker name |
-| `accountId` | Cloudflare account ID |
-| `compatibilityDate` | Workers compatibility date |
-| `compatibilityFlags` | Workers compatibility flags |
-| `files` | handler paths and discovery globs |
-| `bindings` | Cloudflare bindings |
-| `triggers` | cron triggers |
-| `vars` | non-secret runtime bindings |
-| `secrets` | secret declarations |
-| `routes` | deployment routes |
-| `wsRoutes` | local websocket-to-DO proxy rules |
-| `assets` | static assets config |
-| `limits` | worker resource limits |
-| `observability` | worker logs / sampling |
-| `migrations` | Durable Object migrations |
-| `build` | build-related metadata/options |
-| `plugins` | plugin extension point |
-| `env` | environment-specific overrides |
-| `wrangler.passthrough` | escape hatch for Wrangler fields not modeled natively |
-
----
-
-## Env files, `vars`, and `secrets`
-
-This is the most important config nuance to understand.
-
-### The short version
-
-- `loadConfig()` itself does **not** do dotenv loading
-- the Devflare CLI runs under **Bun**, and Bun **does** auto-load `.env` files into `process.env`
-- `vars` are plain config values compiled into generated Wrangler config
-- `secrets` declare expected runtime secret bindings, but do **not** store secret values in config
-
-### The layers to keep separate
-
-| Thing | Used when | Good for secrets? |
-|---|---|---|
-| `process.env` | config evaluation and build tooling | only if your own process handling is secure |
-| `vars` | compile time and runtime | no |
-| `secrets` | declaration + runtime binding expectations | yes |
-| local runtime secret files like `.dev.vars` | local runtime | yes |
-| Cloudflare secret store | deployed runtime | yes |
-
-### What this means in practice
-
-If you run the CLI normally, Bun may populate `process.env` from `.env` before `devflare.config.ts` runs.
-
-That means:
-
-- **CLI under Bun**: `.env` values are often available via `process.env`
-- **programmatic `loadConfig()` elsewhere**: do not assume env files were loaded unless your process already loaded them
-
-### `vars` vs `secrets`
-
-Use `vars` for:
-
-- public base URLs
-- feature flags
-- log levels
-- non-secret IDs and modes
-
-Use `secrets` for:
-
-- API keys
-- tokens
-- passwords
-- signing secrets
-
-Current Devflare behavior matters here:
-
-- `vars` are compiled into generated configuration
-- `secrets` declare names and `required` status, but their values must come from a runtime secret source
-
-### Example
-
-```ts
-import { defineConfig } from 'devflare'
-
-export default defineConfig(() => ({
-	name: 'billing-worker',
-	vars: {
-		PUBLIC_API_BASE: process.env.PUBLIC_API_BASE ?? 'http://localhost:5173',
-		LOG_LEVEL: process.env.LOG_LEVEL ?? 'info'
-	},
-	secrets: {
-		STRIPE_SECRET_KEY: { required: true }
-	}
-}))
-```
-
----
-
-## Environment overrides via `config.env`
-
-`config.env` is a **Devflare merge layer**, not just a raw mirror of Wrangler environment blocks.
-
-When you select an environment with `compileConfig(config, 'name')` or CLI `--env name`, Devflare:
-
-1. starts from the base config
-2. merges `config.env[name]` into it
-3. compiles the resolved result
-
-That means nested values can inherit cleanly from the base config.
-
-This is one of the biggest behavioral differences from thinking in raw Wrangler-only terms.
-
----
-
-## File surfaces and routing
-
-Devflare works best when each concern lives in its own file.
-
-| File / pattern | Purpose |
-|---|---|
-| `src/fetch.ts` | HTTP requests |
-| `src/queue.ts` | queue consumers |
-| `src/scheduled.ts` | cron handlers |
-| `src/email.ts` | incoming email handlers |
-| `src/routes/**` | file-based routing |
-| `do.*.ts` | Durable Objects |
-| `ep.*.ts` | WorkerEntrypoints |
-| `wf.*.ts` | workflows |
-| `src/transport.ts` | custom serialization across boundaries |
-
-### Do not confuse these three
-
-| Key | Meaning |
-|---|---|
-| `files.routes` | file-based HTTP routing inside your app |
-| top-level `routes` | Cloudflare deployment routing |
-| `wsRoutes` | local websocket proxying into Durable Objects during dev |
-
-Use `files.routes` when the HTTP surface is growing beyond a small `fetch.ts` handler.
-
----
-
-## Bindings and multi-worker systems
-
-Devflare natively models these binding categories:
-
-- KV
-- D1
-- R2
-- Durable Objects
-- Queues
-- Services
-- AI
-- Vectorize
-- Hyperdrive
-- Browser Rendering
-- Analytics Engine
-- `sendEmail`
-
-### Core examples
-
-```ts
-bindings: {
-	kv: {
-		CACHE: 'cache-kv-id'
-	},
-	d1: {
-		DB: 'db-id'
-	},
-	durableObjects: {
-		COUNTER: 'Counter'
-	},
-	queues: {
-		producers: {
-			TASK_QUEUE: 'task-queue'
-		}
-	}
-}
-```
-
-### Cross-worker references with `ref()`
-
-Use `ref()` instead of hardcoding worker names and DO script names.
-
-```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')
-		},
-		durableObjects: {
-			AUTH_CACHE: auth.AUTH_CACHE
-		}
-	}
-})
-```
-
-This keeps multi-worker systems typed and centralized.
-
----
-
-## Testing and remote testing
-
-### `devflare/test`
-
-The main testing entrypoint exports:
-
-- `createTestContext`
-- `cf`
-- `email`
-- `queue`
-- `scheduled`
-- `worker`
-- `tail`
-- mock helpers like `createMockKV`, `createMockD1`, `createMockR2`, `createMockQueue`
-- bridge test helpers
-- skip helpers like `shouldSkip`
-
-### Integration-style local tests
-
-Use `createTestContext()` when you want a real local environment backed by Devflare’s orchestration.
-
-`cf` gives you a unified test surface:
-
-- `cf.worker`
-- `cf.queue`
-- `cf.scheduled`
-- `cf.email`
-- `cf.tail`
-
-### Remote-only services
-
-AI and Vectorize are remote-only in practice. Devflare does not pretend they are fully local equivalents of KV or D1.
-
-Use remote mode when you want to run tests against real Cloudflare infrastructure:
-
-```bash
-bunx --bun devflare remote status
-bunx --bun devflare remote enable 30
-bunx --bun devflare remote disable
-```
-
-Remote mode can also be enabled with:
-
-```text
-DEVFLARE_REMOTE=1
-```
-
-Remote mode is stored locally when enabled through the CLI and is intended to be temporary because it may incur real costs.
-
-### Skip helpers
-
-Use `shouldSkip` to gate cost-sensitive or remote-only tests:
-
-```ts
-import { shouldSkip } from 'devflare/test'
-
-describe.skipIf(await shouldSkip.ai)('AI tests', () => {
-	// ...
-})
-```
-
-The skip helpers check remote mode, authentication, account availability, and usage limits.
-
----
-
-## CLI
-
-The Devflare CLI covers the full development loop.
-
-| Command | What it does |
-|---|---|
-| `devflare init` | scaffold a project |
-| `devflare dev` | start the unified local development server |
-| `devflare build` | resolve config, write `wrangler.jsonc`, run `vite build` |
-| `devflare deploy` | build and deploy with Wrangler |
-| `devflare types` | generate `env.d.ts` |
-| `devflare doctor` | check project configuration and common workflow prerequisites |
-| `devflare account` | inspect accounts, resources, usage, and limits |
-| `devflare ai` | show Workers AI model pricing info |
-| `devflare remote` | manage remote test mode |
-
-### Useful CLI notes
-
-- `build` and `deploy` accept `--env <name>` to select `config.env[name]`
-- `doctor` assumes the default Vite-based Devflare workflow and checks for config, package metadata, Vite config, TypeScript config, and generated Wrangler output
-- `account` includes subcommands like `workers`, `kv`, `d1`, `r2`, `vectorize`, `limits`, `usage`, `global`, and `workspace`
-
-Recommended invocation style:
-
-```bash
-bunx --bun devflare dev
-bunx --bun devflare types
-bunx --bun devflare build
-```
-
----
-
-## `devflare/cloudflare`
-
-`devflare/cloudflare` exposes the account helper API for Cloudflare-aware tooling.
-
-```ts
-import { account } from 'devflare/cloudflare'
-
-const isLoggedIn = await account.isAuthenticated()
-const primary = await account.getPrimaryAccount()
-```
-
-It includes helpers for:
-
-- authentication and Wrangler auth inspection
-- listing Workers, KV, D1, R2, Vectorize, and AI resources
-- service status
-- usage tracking
-- limit enforcement
-- test guardrails
-- global and workspace account preference management
-
-### Account preference storage
-
-Current account preference behavior is:
-
-- workspace account: stored in nearest `package.json` as `devflare.accountId`
-- global default: cached locally in `~/.devflare/preferences.json` and synced via Devflare-managed Cloudflare KV when possible
-
-This matters if your repo uses multiple Cloudflare accounts or you want deterministic test behavior across machines.
-
----
-
-## Generated artifacts
-
-Treat these as generated output, not source of truth:
-
-- `.devflare/`
-- `env.d.ts`
-- generated `wrangler.jsonc`
-
-The source of truth is still:
-
-- `devflare.config.ts`
-- your source files under `src/`
-- your test files
-
----
-
-## Caveats and feature maturity
-
-Devflare has a broad surface area, but not every feature is equally mature.
-
-### Strong core areas
-
-- typed config
-- config loading and compilation
-- file conventions
-- `vars`
-- Durable Objects
-- queues
-- `ref()`
-- testing ergonomics
-- unified `env`
-- Vite/SvelteKit integration surfaces
-
-### Important caveats
-
-1. **`vars` are string-only in current Devflare config**
-   - serialize more complex values yourself if needed
-
-2. **`secrets` are declaration-oriented**
-   - secret values are not stored in config and are not compiled into generated Wrangler config
-
-3. **`sendEmail` is lighter than core bindings**
-   - it exists in the schema and examples
-   - but it is not as fully wired as KV/D1/R2/DO/queues/services
-
-4. **named service entrypoints need verification in generated output**
-   - `ref().worker('Entrypoint')` is modeled at the Devflare layer
-   - validate deployment output if named entrypoint wiring is critical to your app
-
-5. **workflows, `build`, and `plugins` are lighter than the most central surfaces**
-   - they exist and matter
-   - but they are not as battle-hardened as the fetch/queue/DO/test path
-
-6. **use `wrangler.passthrough` for unsupported native fields**
-   - if Wrangler supports something Devflare does not model yet, passthrough is the supported escape hatch
-
----
-
-## Deprecations and preferred replacements
-
-Some older APIs still exist for compatibility.
-
-| Older API | Prefer instead |
-|---|---|
-| `createMultiWorkerContext()` | `createTestContext()` |
-| `createEntrypointScript()` | normal worker/entrypoint file patterns |
-| `resolveRef()` | `ref()` |
-| `serviceBinding()` | `ref().worker` or `ref().worker('Entrypoint')` |
-| `isRemoteModeEnabled()` | `shouldSkip.*` for tests and `devflare remote ...` for mode management |
-
----
-
-## A good starter layout
-
-```text
-.
-├── devflare.config.ts
-├── env.d.ts
-├── src/
-│   ├── fetch.ts
-│   ├── queue.ts
-│   ├── scheduled.ts
-│   ├── email.ts
-│   ├── routes/
-│   ├── do.counter.ts
-│   ├── ep.admin.ts
-│   ├── wf.sync.ts
-│   └── transport.ts
-└── tests/
-    └── worker.test.ts
-```
-
-Not every project needs every file, but this layout matches the Devflare mental model well.
-
----
-
-## When to use Devflare
-
-Devflare is especially nice when you want:
-
-- Cloudflare Workers with clean project structure
-- Durable Object-heavy apps
-- multi-worker systems with service bindings
-- local-first development with realistic tests
-- browser rendering in your local workflow
-- Vite or SvelteKit apps that still want a clean Worker model
-
----
-
-## In one sentence
-
-**Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development experience that scales with your app.**
+# Devflare
+
+Devflare is a developer-first toolkit for Cloudflare Workers. It keeps config,
+runtime helpers, local development, testing, preview deploys, and Cloudflare
+operations in one package without pretending Cloudflare boundaries disappear.
+
+The docs app is the authored long-form source. This README is intentionally the
+short package map: install, first Worker, import/API map, config and CLI
+surface, support stances, and links into the deeper docs. `LLM.md` is generated
+from the same docs model and shipped with the package for flattened reading.
+
+## Install
+
+For a worker-only project, install only Devflare:
+
+```bash
+bun add -d devflare
+```
+
+For Vite-backed apps, add Vite. Add the Cloudflare Vite plugin only when your
+own `vite.config.*` calls it directly:
+
+```bash
+bun add -d devflare vite
+```
+
+Assumptions used by the examples: Wrangler 4, Miniflare 4,
+`@cloudflare/workers-types` 4, Bun 1.1+, and Node 20+.
+
+## Cloudflare toolchain support
+
+Devflare targets Wrangler 4, Miniflare 4, and @cloudflare/workers-types 4.
+Devflare does not support Wrangler 3 in new projects. The package manifest pins
+the exact ranges that scaffolds, local runtime behavior, and generated types
+are validated against in CI.
+
+## Quick Start
+
+Create a config:
+
+```ts
+// devflare.config.ts
+import { defineConfig } from 'devflare/config'
+
+export default defineConfig({
+	name: 'hello-worker',
+	compatibilityDate: '2026-03-17',
+	files: {
+		fetch: 'src/fetch.ts'
+	}
+})
+```
+
+Add a fetch handler:
+
+```ts
+// src/fetch.ts
+import type { FetchEvent } from 'devflare/runtime'
+
+export async function fetch(_event: FetchEvent): Promise<Response> {
+	return new Response('Hello from Devflare')
+}
+```
+
+Generate types and start local dev:
+
+```bash
+bunx --bun devflare types
+bunx --bun devflare dev
+```
+
+Add the first runtime-shaped test:
+
+```ts
+// tests/worker.test.ts
+import { afterAll, beforeAll, expect, test } from 'bun:test'
+import { cf, createTestContext, env } from 'devflare/test'
+
+beforeAll(() => createTestContext())
+afterAll(() => env.dispose())
+
+test('GET / returns text', async () => {
+	const response = await cf.worker.get('/')
+
+	expect(response.status).toBe(200)
+	expect(await response.text()).toBe('Hello from Devflare')
+})
+```
+
+Run it:
+
+```bash
+bun test tests/worker.test.ts
+```
+
+## Choose Your Next Path
+
+| Need | Open |
+| --- | --- |
+| Add route files | `/docs/first-route-tree`, then `/docs/http-routing` |
+| Add one binding | `/docs/first-bindings`, then `/docs/binding-chooser` |
+| Pick a test helper | `/docs/test-helper-reference` |
+| Deploy safely | `/docs/deploy-command-recipes` |
+| Check support stance | `/docs/feature-index` |
+| Copy a larger example | `/docs/recipe-packs` or `cases/README.md` |
+
+## Package Entrypoints
+
+| Import | Use |
+| --- | --- |
+| `devflare` | Node-side utilities: `defineConfig`, `preview`, `loadConfig`, `loadResolvedConfig`, `compileConfig`, `stringifyConfig`, `configSchema`, `ref()`, `workerName`, `env`, `durableObject`, `getDurableObjectOptions`, `runCli`, `parseArgs` |
+| `devflare/config` | Config and compiler utilities: `defineConfig`, `preview`, `ref`, `loadConfig`, `loadResolvedConfig`, `compileConfig`, `stringifyConfig`, `configSchema`, `resolveResources`, `writeWranglerConfig`, `readWranglerConfig`, `prepareConfigResourcesForDeploy`, `prepareMaterializedConfigResourcesForDeploy`, `resolveConfigPath`, `resolveConfigForEnvironment`, `resolvePreviewIdentifier`, `materializePreviewScopedConfig`, `materializePreviewScopedString`, `isPreviewScopedName`, `resolveMaterializedConfigResources`, `compileBuildConfig`, `validateServiceBindings`, `collectReferencedServiceNames`, `getLocalKVNamespaceIdentifier`, `getLocalD1DatabaseIdentifier`, `getLocalHyperdriveConfigIdentifier`, `getSingleBrowserBindingName`, `normalizeKVBinding`, `normalizeD1Binding`, `normalizeDOBinding`, `normalizeHyperdriveBinding`, `normalizeMtlsCertificateBinding`, `normalizeDispatchNamespaceBinding`, `normalizeWorkflowBinding`, `normalizePipelineBinding`, `normalizeImagesBinding`, `normalizeMediaBinding`, `normalizeSecretsStoreBinding`, `normalizeArtifactsBinding` |
+| `devflare/runtime` | Worker-safe runtime helpers: `env`, `ctx`, `event`, `locals`, `sequence`, `defineFetchHandler`, `defineQueueHandler`, `defineScheduledHandler`, `markResolveStyle`, `markWorkerStyle`, `createResolveFetch`, `invokeFetchHandler`, `invokeFetchModule`, `matchFetchRoute`, `invokeRouteModules`, `createRouteResolve`, event creators and getters |
+| `devflare/test` | Testing helpers: `createTestContext`, `env`, `cf`, `worker`, `queue`, `scheduled`, `email`, `tail`, `shouldSkip`, `createOfflineEnv`, `createOfflineBindings`, `describeOfflineSupport`, `getOfflineSupportMatrix`, `containers`, `detectContainerEngine`, `getContainerSkipReason`, `stopActiveContainers`, `createMockEnv`, `createMockKV`, `createMockD1`, `createMockR2`, `createMockQueue`, `createMockRateLimit`, `createMockVersionMetadata`, `createMockHyperdrive`, `createMockWorkerLoader`, `createMockMTLSCertificate`, `createMockDispatchNamespace`, `createMockWorkflow`, `createMockPipeline`, `createMockImagesBinding`, `createMockMediaBinding`, `createMockArtifacts`, `createMockAISearchInstance`, `createMockAISearchNamespace`, `createMockTestContext`, `withTestContext`, `resolveServiceBindings`, `resolveDOBindings`, `clearBundleCache` |
+| `devflare/vite` | Vite integration: `devflarePlugin`, `getCloudflareConfig`, `getDevflareConfigs`, `getPluginContext`, `hasInlineViteConfig`, `resolveEffectiveViteProject`, `resolveViteUserConfig`, `writeGeneratedViteConfig` |
+| `devflare/sveltekit` | SvelteKit integration: `createDevflarePlatform`, `createHandle`, `handle`, `getBridgePort`, `isDevflareDev`, `resetPlatform`, `resetConfigCache` |
+| `devflare/cloudflare` | Cloudflare account and preview registry helpers: `account`, `ensurePreviewRegistry`, `cleanupPreviewRegistry`, `getPreviewRegistryContext`, `listTrackedRegistryState`, `listTrackedPreviewRecords`, `listTrackedPreviewScopeRecords`, `listTrackedDeploymentRecords`, `reconcilePreviewRegistry`, `retirePreviewRegistry` |
+| `devflare/decorators` | Durable Object decorators: `durableObject`, `getDurableObjectOptions` |
+
+Runtime import rule of thumb:
+
+- Use `devflare/config` in config files.
+- Use `devflare/runtime` in Worker code.
+- Use `devflare/test` in tests.
+- Use bare `devflare` for Node-side package tooling and the unified env proxy only when that is intentional.
+
+## Config Map
+
+The most important top-level keys are:
+
+- `accountId`
+- `assets`
+- `baseDir`
+- `bindings`
+- `compatibilityDate`
+- `compatibilityFlags`
+- `containers`
+- `env`
+- `files`
+- `findAdditionalModules`
+- `limits`
+- `migrations`
+- `name`
+- `observability`
+- `placement`
+- `preserveFileNames`
+- `previews`
+- `rolldown`
+- `routes`
+- `rules`
+- `secrets`
+- `secretsStoreId`
+- `tailConsumers`
+- `triggers`
+- `vars`
+- `vite`
+- `wrangler.passthrough`
+- `wsRoutes`
+
+Open `/docs/full-config`, `/docs/config-basics`, and `/docs/generated-types`
+for examples with file paths.
+
+## CLI
+
+| Command | Use |
+| --- | --- |
+| `devflare account` | inspect Cloudflare account resources, limits, and usage |
+| `devflare ai` | inspect Workers AI model pricing information |
+| `devflare build` | generate deploy-ready local artifacts |
+| `devflare config` | print resolved Devflare or Wrangler-facing config |
+| `devflare deploy` | deploy explicitly to production or preview |
+| `devflare dev` | start local development |
+| `devflare doctor` | inspect local project health |
+| `devflare help` | print help for root or nested commands |
+| `devflare init` | scaffold a starter project |
+| `devflare login` | authenticate through Wrangler |
+| `devflare previews` | inspect and clean preview scopes |
+| `devflare productions` | inspect or manage production Worker versions |
+| `devflare remote` | manage remote test mode |
+| `devflare secrets` | manage local Secrets Store values |
+| `devflare tokens` | create and manage Devflare-scoped API tokens |
+| `devflare types` | generate `env.d.ts` |
+| `devflare version` | print the installed version |
+| `devflare worker` | run Worker control-plane helpers |
+
+Useful local-first switches:
+
+- `devflare dev --runtime-port 8788` or `DEVFLARE_RUNTIME_PORT=8788` moves the local Miniflare runtime/bridge off the default `127.0.0.1:8787`. `--bridge-port` and `DEVFLARE_BRIDGE_PORT` are aliases for the same runtime port.
+- `devflare doctor --scope local` skips deploy-readiness artifact warnings during a local-only loop.
+- `devflare config --phase local --format wrangler` prints the local-runtime Wrangler shape without Cloudflare account resource lookups.
+- `devflare dev` and `devflare/vite` start `ref()` service-binding workers inside the same local runtime, including their local KV, D1, R2, Queue producer/consumer, vars, Durable Objects, and other Miniflare-backed bindings.
+
+## Support Stance Index
+
+The full support matrix is in `/docs/feature-index`. The short version is:
+offline-first when deterministic local behavior is meaningful, remote-gated
+when Cloudflare owns the product behavior, and explicit skip helpers when CI
+cannot safely run the dependency.
+
+### AutoRAG migration stance
+
+AutoRAG is documented under AI Search. The previous `env.AI.autorag()` binding
+shape should move to native AI Search config. Use `bindings.aiSearchNamespaces`
+or `bindings.aiSearch` so the binding is visible in config, generated types,
+and tests.
+
+### AI Gateway binding methods
+
+AI Gateway does not use a separate Wrangler binding. It is a method surface on
+Workers AI: `env.AI.gateway(id)` exposes `patchLog()`, `getLog()`, `getUrl()`,
+and `run()`.
+
+### Browser Run product boundary
+
+Browser Run is the current product name for Browser Rendering. Devflare runs a
+local browser-rendering shim for the ordinary dev and test loop, but Devflare
+does not manage Live View URLs, Human in the Loop handoff, recordings, browser
+session storage, or Browser Run account-level product state.
+
+### Containers local testing
+
+Devflare supports native top-level `containers` config and local container
+testing helpers. Containers have full local support when Docker or Podman is
+available: Devflare can build local Dockerfile paths, run prebuilt image tags,
+and interact with instances through fetch, logs, state, stop, and cleanup
+helpers. Devflare container tests are offline-first by default when the image
+already exists locally or the Dockerfile can build from cached layers. Set
+`DEVFLARE_CONTAINER_TESTS=1` for container lanes, and gate them with
+`shouldSkip.containers` because GitHub Actions or Cloudflare runners may not
+have Docker/Podman. Cloudflare still owns the deployed Containers control plane,
+managed registry rollout, SSH, scaling, and hosted platform behavior.
+
+### Cloudflare Builds stance
+
+Cloudflare Builds is CI/CD orchestration, not a Worker runtime binding.
+Devflare does not connect Git repositories, manage build hooks, own Cloudflare
+Builds project settings, or replace GitHub Actions workflows.
+
+### Workers for Platforms lifecycle stance
+
+Devflare supports dispatch namespace bindings, not the tenant Worker control
+plane. Devflare does not upload user Workers, manage Worker metadata, own tenant
+routing policy, or provide the Workers for Platforms lifecycle API.
+
+### Hyperdrive local connection stance
+
+Hyperdrive has full local support when a binding has a local database connection
+string. Devflare passes `localConnectionString` or
+`CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>` into Miniflare and
+also exposes `createMockHyperdrive()` for pure tests. Cloudflare still owns
+hosted pooling, placement, production credentials, and account state.
+
+### Worker Loaders local payload stance
+
+Worker Loaders have full local support through Miniflare worker loader bindings
+and explicit pure-test stubs. Devflare does not upload, discover, or lifecycle
+manage hosted dynamic Worker payloads.
+
+### Secrets Store local values stance
+
+Secrets Store has full local support through Miniflare wiring, local
+`devflare secrets --local` values, and explicit fixture values in
+`createOfflineEnv()` or `createMockSecretsStoreSecret()`. The local runtime is
+read-only from Worker code: write values through the CLI, keep config to store
+IDs and secret names, and let dev/test runs seed Miniflare from
+`.devflare/secrets.local.json`. Devflare does not read, provision, or sync
+remote account secret values.
+
+### Workflows local simulation stance
+
+Workflows have full local support through Miniflare wiring, WorkflowEntrypoint
+examples, and deterministic pure mocks. Use deployed or Wrangler-backed tests
+for production Workflow lifecycle behavior, retries, durability, and platform
+scheduling.
+
+### Pipelines source and sink lifecycle stance
+
+Pipelines local tests are useful for producer-code assertions. Devflare does not
+create streams, pipelines, SQL transformations, sinks, or R2 buckets for the
+deployed product lifecycle.
+
+### Images transformation testability stance
+
+Images have full local support for Worker transformation flows through
+Miniflare wiring and deterministic pure mocks. Devflare does not provision
+hosted Images storage, variants, signed URLs, or custom delivery rules.
+
+### Media Transformations local shim stance
+
+Media Transformations have full local support for Worker call chains through
+Miniflare wiring and deterministic pure mocks. Devflare does not configure
+zone-level transformation enablement, source origins, signed URL policy, cache
+behavior, or billing controls.
+
+### Artifacts persistence and deployment stance
+
+Artifacts pure mocks are in-memory and process-local. Devflare does not create
+Artifacts namespaces, persist local Git repositories, or emulate Git-over-HTTPS
+remotes.
+
+### Preview resource lifecycle policy
+
+Devflare preview provisioning is intentionally limited to KV, D1, R2, Queues,
+Vectorize, and the documented Hyperdrive reuse/resolve paths. Preview cleanup
+does not delete Workflows, Pipelines, Images, Media Transformations, Artifacts,
+AI Search, AI Gateway, Browser Run, Containers, Secrets Store, mTLS
+certificates, or dispatch namespace resources.
+
+### Cross-feature implementation decisions
+
+Remote mode decisions are per feature, not global. Generated types are emitted
+only for native binding keys. Test helpers exist when Devflare provides a
+deterministic local mock or useful pure assertion surface. Every native binding
+documented above includes a minimal config and Env usage example. Move from
+`wrangler.passthrough` to native config when a binding appears in the native
+list. Cloudflare dependency CI targets the pinned current Wrangler, Miniflare,
+and workers-types majors documented in Cloudflare toolchain support.
+
+### Offline-first testing support matrix
+
+`createOfflineEnv(config, fixtures)` derives a deterministic pure-test `env`
+from Devflare config. Offline-native means Devflare or Miniflare can run a
+useful local simulator. Offline-fixture means Devflare provides an explicit
+in-memory or handler-backed mock. Remote-boundary means meaningful behavior
+lives in Cloudflare.
+
+Use `shouldSkip.aiSearch`, `shouldSkip.aiGateway`,
+`shouldSkip.mtlsCertificates`, `shouldSkip.artifacts`, and `shouldSkip.builds`
+for remote-boundary lanes. Offline-first tests should not claim to cover real
+Workers AI inference, Vectorize search semantics, AI Search indexing/ranking/
+crawling, final Media Transformations codec fidelity, mTLS certificate
+presentation, Artifacts Git remotes, Browser Run live/HITL/recordings,
+Cloudflare Builds, or the deployed Containers control plane.
+
+## Machine-Checked Support Statements
+
+These statements are intentionally exact because the docs tests use them as
+public stance guards:
+
+- Use `bindings.aiSearchNamespaces` or `bindings.aiSearch`.
+- `env.AI.gateway(id)` exposes `patchLog()`, `getLog()`, `getUrl()`, and `run()`.
+- Devflare does not manage Live View URLs, Human in the Loop handoff.
+- Set `DEVFLARE_CONTAINER_TESTS=1`.
+- Containers have full local support when Docker or Podman is available.
+- Cloudflare still owns the deployed Containers control plane.
+- Devflare does not connect Git repositories, manage build hooks.
+- Devflare supports dispatch namespace bindings, not the tenant Worker control plane.
+- Devflare does not upload user Workers, manage Worker metadata.
+- Hyperdrive has full local support when a binding has a local database connection string.
+- Worker Loaders have full local support through Miniflare worker loader bindings.
+- Secrets Store has full local support through Miniflare wiring, local `devflare secrets --local` values, and explicit fixture values.
+- Workflows have full local support through Miniflare wiring.
+- Use deployed or Wrangler-backed tests for production Workflow lifecycle behavior.
+- Devflare does not create streams, pipelines, SQL transformations, sinks, or R2 buckets.
+- Images have full local support for Worker transformation flows.
+- Devflare does not provision hosted Images storage, variants, signed URLs, or custom delivery rules.
+- Media Transformations have full local support for Worker call chains.
+- Devflare does not configure zone-level transformation enablement, source origins, signed URL policy, cache behavior, or billing controls.
+- Devflare does not create Artifacts namespaces, persist local Git repositories, or emulate Git-over-HTTPS remotes.
+- Devflare preview provisioning is intentionally limited to KV, D1, R2, Queues, Vectorize, and the documented Hyperdrive reuse/resolve paths.
+- Preview cleanup does not delete Workflows, Pipelines, Images, Media Transformations, Artifacts, AI Search, AI Gateway, Browser Run, Containers, Secrets Store, mTLS certificates, or dispatch namespace resources.
+- Generated types are emitted only for native binding keys.
+- Test helpers exist when Devflare provides a deterministic local mock or useful pure assertion surface.
+- Every native binding documented above includes a minimal config and Env usage example.
+- Move from `wrangler.passthrough` to native config when a binding appears in the native list.
+- Cloudflare dependency CI targets the pinned current Wrangler, Miniflare, and workers-types majors documented in Cloudflare toolchain support.
+- `createOfflineEnv(config, fixtures)` derives a deterministic pure-test `env` from Devflare config.
+- Offline-native means Devflare or Miniflare can run a useful local simulator.
+- Offline-fixture means Devflare provides an explicit in-memory or handler-backed mock.
+- Remote-boundary means meaningful behavior lives in Cloudflare.
+- `shouldSkip.aiSearch`, `shouldSkip.aiGateway`, `shouldSkip.mtlsCertificates`, `shouldSkip.artifacts`, and `shouldSkip.builds`.
+- real Workers AI inference, Vectorize search semantics, AI Search indexing/ranking/crawling, final Media Transformations codec fidelity, mTLS certificate presentation, Artifacts Git remotes, Browser Run live/HITL/recordings, Cloudflare Builds, or the deployed Containers control plane.
+
+## Verification
+
+Docs and README drift are covered by:
+
+```bash
+bun run devflare:docs-integrity
+```
+
+The package publish path regenerates `packages/devflare/LLM.md` from the docs
+model through `bun run --cwd packages/devflare llm:generate`.