devflare 1.0.0-next.3 → 1.0.0-next.5

package/LLM.md

@@ -520,7 +520,7 @@ Bindings are the heart of the runtime contract.
 |---|---|---|---|
 | `kv` | `Record<string, string>` | Yes | binding name → KV namespace ID |
 | `d1` | `Record<string, string>` | Yes | binding name → D1 database ID |
-| `r2` | `Record<string, string>` | Yes | binding name → bucket name |
+| `r2` | `Record<string, string>` | Yes | binding name → bucket name, not a delivery/auth strategy |
 | `durableObjects` | `Record<string, string | { className, scriptName? }>` | Yes | string shorthand or object form, including cross-worker refs |
 | `queues.producers` | `Record<string, string>` | Yes | binding name → queue name |
 | `queues.consumers` | array of consumer objects | Yes | batch size, retries, timeout, DLQ, concurrency, retry delay |
@@ -550,6 +550,15 @@ bindings: {
 }
 ```
 
+An R2 binding declaration only makes the bucket available as a runtime `env` binding.
+
+It does **not** by itself decide:
+
+- how uploads should be authorized
+- whether objects are public or private
+- which URL shape should be stored in your database
+- whether files should be served through a custom domain, presigned URL, Access, WAF token auth, or a Worker
+
 ### Durable Objects
 
 Durable Object bindings support both shorthand and object form.
@@ -688,6 +697,199 @@ However, this binding is currently **not wired through the compiler/types/runtim
 
 ---
 
+## R2 workflow: uploads, delivery, local development, and preview mindset
+
+For a shorter strategy guide focused specifically on Cloudflare R2 delivery patterns, see `R2.md`.
+
+This section explains how R2 fits into the **public Devflare mental model**.
+
+### `bindings.r2` gives you storage access, not a complete delivery policy
+
+When you configure:
+
+```ts
+bindings: {
+	r2: {
+		FILES: 'files-bucket'
+	}
+}
+```
+
+Devflare is saying:
+
+- your Worker should receive an `env.FILES` R2 binding
+- local development can simulate that binding
+- build/deploy compilation can emit the corresponding Wrangler binding declaration
+
+Devflare is **not** automatically saying:
+
+- uploads should come from the browser directly
+- objects should be public
+- objects should be private
+- your app should store full URLs instead of object keys
+- local dev URLs should look like production URLs
+
+Those choices still belong to your application architecture.
+
+### Store object keys, not full URLs
+
+This is the safest default rule for R2-backed applications:
+
+- store the **object key** as the durable identifier
+- optionally store metadata such as content type, size, owner, visibility, or logical folder/prefix
+- derive the actual viewing or download URL per environment and per access policy
+
+Example durable record shape:
+
+```ts
+{
+	key: 'users/42/avatar/8d8b7f2a.png',
+	contentType: 'image/png',
+	visibility: 'private'
+}
+```
+
+Why this is better than storing full URLs:
+
+- local preview URLs can change without breaking your data model
+- staging and production can use different delivery strategies for the same object key
+- you do not couple persistent data to `localhost`, temporary signed URLs, or a specific CDN hostname
+- you can move a file from private delivery to public delivery without rewriting the canonical identifier
+
+### Recommended upload and serving models
+
+These are the recommended patterns to pair with a Devflare R2 binding.
+
+#### Direct user uploads
+
+For normal browser uploads, the safest default is:
+
+1. your frontend asks your app for upload permission
+2. your Worker authenticates the user and validates file type, size, and target key
+3. your Worker returns a short-lived presigned `PUT` URL
+4. the browser uploads directly to R2
+5. your app stores the resulting object key and metadata
+
+This keeps large uploads out of your application request path while preserving control over authorization and naming.
+
+#### Worker-generated or server-generated content
+
+If the file is produced by your Worker, by Workers AI, or by another trusted backend process, it is normal for the Worker itself to write directly to R2.
+
+That is different from browser-driven uploads, where presigned URLs are usually the cleaner fit.
+
+#### Public files
+
+For avatars, blog images, product images, and other content that anyone may read:
+
+- use a public bucket or public custom-domain access pattern
+- prefer a custom domain for stable production URLs and caching behavior
+- do not treat `r2.dev` as the production answer
+
+#### Private or authenticated files
+
+For invoices, receipts, paid media, tenant-scoped files, or other user-specific objects:
+
+- keep the bucket private
+- store only object keys in durable data
+- serve reads through a Worker that checks session, tenant, or authorization state before reading from R2
+
+#### Temporary direct reads
+
+Presigned `GET` URLs are useful when you need short-lived direct access.
+
+Important caveats:
+
+- they are bearer tokens
+- they work on the R2 S3 endpoint, not on custom domains
+- they are great for temporary access, but not the right long-term answer for polished custom-domain delivery
+
+#### Team-only or org-only buckets
+
+If the audience is your teammates or internal users, Cloudflare Access on a custom domain is often a better fit than inventing your own mini auth protocol.
+
+#### Custom-domain expiring links
+
+If you want URLs like `https://cdn.example.com/files/...` with time-limited access, use:
+
+- a Worker-controlled token/signature layer, or
+- Cloudflare WAF token authentication / HMAC validation
+
+Do **not** confuse that with R2 presigned URLs. They solve different problems.
+
+### Local development vs production
+
+#### Local development
+
+In local development, the correct default assumption is:
+
+- your Worker code runs locally
+- your R2 binding is simulated locally unless you intentionally opt into remote resources
+
+This is good. It gives you fast feedback, zero surprise cloud writes, and predictable local iteration.
+
+When you run `devflare dev --persist`, local Miniflare-backed state is persisted under `.devflare/data/`, including R2 object state under `.devflare/data/r2/`.
+
+#### Remote bindings change the risk profile
+
+If you connect development to remote resources, remember:
+
+- reads and writes touch **real buckets**
+- operations can incur **real cost**
+- local experiments can now interact with non-local data
+
+So the recommended pattern is:
+
+- use local simulated R2 for normal development
+- use separate dev or staging buckets when you need higher-fidelity integration testing
+- avoid pointing local development at production user uploads unless you truly mean to
+
+#### Production
+
+Production is where you make the real delivery choice:
+
+- public custom-domain access for public files
+- Worker-gated reads for private/authenticated files
+- Access for org-only content
+- Worker/WAF token validation for custom-domain expiring links
+
+That is why `R2.md` exists. It is the short operational guide for those production choices.
+
+### Local preview and internal route guidance
+
+Devflare already uses internal `/_devflare/*` routes during local development for gateway and bridge behavior.
+
+Treat those routes as **internal dev-server implementation details**, not as part of your application’s public URL contract.
+
+Important current rule:
+
+- do **not** assume there is a stable public `/_devflare/r2/...` contract for browser-facing local file delivery
+- do **not** persist `/_devflare/*` URLs in your database
+- do **not** design production delivery around the hope that local preview URLs and production URLs will be the same
+
+If you build custom local preview tooling or if Devflare gains a future R2 inspector surface, the safest mental model is:
+
+- it is a **dev-only convenience or inspector URL**
+- it should be treated as **read-only**
+- it should help you inspect objects, not redefine your production delivery architecture
+- the canonical identifier should still be the object key, not the preview URL
+
+Also remember that R2 is object storage, not a real filesystem. Prefix browsing can be useful in tooling, but those “folders” are naming conventions, not first-class directories.
+
+### Benefits of this model
+
+This local-first but production-explicit R2 model has real benefits.
+
+- **Faster local iteration:** you can develop upload and media flows against local simulated R2 without waiting on cloud round-trips
+- **Safer production posture:** public, private, org-only, and expiring-link delivery can be chosen intentionally instead of collapsing into one accidental URL model
+- **Better data durability:** storing keys instead of URLs keeps your database portable across local, staging, and production environments
+- **Cleaner security boundaries:** auth policy stays where it belongs, in Workers, Access, or token validation, rather than being smuggled into a fragile client-side convention
+- **Better debugging ergonomics:** local preview or inspector tooling can exist as a convenience layer without becoming the source of truth
+- **Less environment coupling:** your app does not become dependent on `localhost`, temporary presigned URLs, or an implementation-specific dev route shape
+- **Better media realism:** you can use local development for quick feedback, then use staging for production-like checks such as custom-domain caching, token auth, and large-media behavior
+
+---
+
 ## `vars`, `secrets`, and generated types
 
 ### `vars`
@@ -1285,6 +1487,34 @@ Recommended invocation style:
 bunx --bun devflare <command>
 ```
 
+### Global flags
+
+These flags are parsed at the CLI entrypoint level.
+
+| Flag | Meaning | Where it actually matters | Notes |
+|---|---|---|---|
+| `-h`, `--help` | show help text and exit | all invocations | short-circuits immediately to the help command |
+| `-v`, `--version` | show the CLI/package version and exit | all invocations | short-circuits immediately to the version command |
+| `--config <path>` | choose a config file instead of nearest default discovery | `dev`, `build`, `deploy`, `types` | currently not consumed by `doctor`, `account`, `ai`, or `remote` |
+| `--debug` | enable debug-oriented output | `dev`, `build`, `deploy`, `types` | in `dev`, this also implies verbose logging; in `build`/`deploy`/`types`, it mainly controls stack-trace output on failure |
+
+There is also a current internal/testing-oriented `--cwd` path override used by the `dev` command implementation. Treat that as an unsupported internal hook rather than part of the stable public CLI contract.
+
+### `init`
+
+Usage:
+
+```text
+devflare init [name] [--template <template>]
+```
+
+Arguments and flags:
+
+| Argument or flag | Meaning | Notes |
+|---|---|---|
+| `[name]` | project directory name | defaults to `my-devflare-app` |
+| `--template <template>` | choose a starter template | current built-in templates are `minimal` and `api`; default is `minimal` |
+
 ### `dev`
 
 `devflare dev` is not “just run Miniflare”.
@@ -1299,23 +1529,30 @@ It is a combined local development system that includes:
 - browser-shim behavior for browser rendering
 - local migration handling when relevant resources are configured
 
-Dev command flags include:
+Usage:
 
-- `--port`
-- `--persist`
-- `--verbose`
-- `--log`
-- `--log-temp`
+```text
+devflare dev [--config <path>] [--debug] [--port <port>] [--persist] [--verbose] [--log] [--log-temp]
+```
 
-### Config path and environment selection in CLI commands
+Flags:
 
-For the current build and deploy flows:
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific `devflare.config.*` file | otherwise config is loaded from the current working directory |
+| `--debug` | enable debug mode | equivalent effect to setting `DEVFLARE_DEBUG=true` for the dev command and also implies verbose logging |
+| `--port <port>` | set the preferred Vite port | only matters when the current package has a local `vite.config.*` and Devflare actually starts Vite |
+| `--persist` | persist Miniflare storage across restarts | opt-in in the current CLI; persists KV, R2, D1, and Durable Object state under `.devflare/data/` |
+| `--verbose` | increase logging verbosity | debug mode also turns this on |
+| `--log` | tee log output to both terminal and a timestamped file | file name shape is `.log-YYYY-MM-DD_HH-MM-SS` in the project root |
+| `--log-temp` | tee log output to both terminal and `.log` | `.log` is overwritten each run; if both `--log` and `--log-temp` are passed, temp-log mode wins |
 
-- config is loaded from the current working directory unless you pass `--config <file>`
-- `--env <name>` selects `config.env.<name>` during Devflare compilation
-- on `deploy`, the same `--env <name>` is also forwarded to `wrangler deploy`
+Important current CLI behavior:
 
-So `--env` on `deploy` affects both the Devflare-side resolution step **and** Wrangler’s deploy command.
+- Devflare starts in **worker-only mode** unless the current package has a local `vite.config.ts`, `vite.config.js`, `vite.config.mts`, or `vite.config.mjs`
+- `--port` does not force Vite on by itself; it only affects startup if Vite is already enabled by local package structure
+- there is no public `--env` flag on the current `dev` command
+- without `--persist`, local Miniflare-backed state is ephemeral for that dev session
 
 ### `build`
 
@@ -1331,6 +1568,20 @@ The build subprocess receives `DEVFLARE_BUILD=true` in its environment.
 
 That means project build code can branch on “Devflare build mode” if it needs to.
 
+Usage:
+
+```text
+devflare build [--config <path>] [--env <name>] [--debug]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific config file | otherwise uses config discovery from the current working directory |
+| `--env <name>` | select `config.env.<name>` before compilation | this affects the resolved config written to generated output |
+| `--debug` | show stack traces on failure | mainly useful when config loading, compilation, or the Vite build subprocess fails |
+
 ### `deploy`
 
 `devflare deploy` performs the same config-resolution step, then builds and runs Wrangler deploy.
@@ -1343,10 +1594,39 @@ Important nuances:
 
 So do not assume build-time code sees identical environment flags under `build` and `deploy`.
 
+Usage:
+
+```text
+devflare deploy [--config <path>] [--env <name>] [--dry-run] [--debug]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific config file | otherwise uses config discovery from the current working directory |
+| `--env <name>` | select `config.env.<name>` during Devflare compilation and forward the same env to `wrangler deploy` | this is the most important CLI env flag to understand |
+| `--dry-run` | print the resolved compiled Wrangler config and exit | current implementation exits before writing `wrangler.jsonc`, running `vite build`, or calling Wrangler |
+| `--debug` | show stack traces on failure | useful for config/build/deploy debugging |
+
 ### `types`
 
 `devflare types` generates `env.d.ts`, which is a key part of the typed Devflare workflow.
 
+Usage:
+
+```text
+devflare types [--config <path>] [--output <path>] [--debug]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--config <path>` | load a specific config file | otherwise defaults to the current project’s normal config discovery |
+| `--output <path>` | choose the output path for generated types | defaults to `env.d.ts` |
+| `--debug` | show stack traces on failure | useful when discovery or generation fails |
+
 ### `doctor`
 
 `devflare doctor` is a project diagnostics command.
@@ -1363,12 +1643,113 @@ It currently checks for things such as:
 
 Use it as a quick environment sanity check, not as a proof that every runtime behavior is correct.
 
+Usage:
+
+```text
+devflare doctor
+```
+
+Current flag behavior:
+
+- there are no command-specific public flags documented for `doctor` right now
+- current implementation checks Vite-related files only when the current package appears to opt into Vite integration
+- do not assume `--config <path>` currently redirects `doctor` in the same way it does for `build`, `deploy`, `dev`, or `types`
+
+### `account`
+
+Usage:
+
+```text
+devflare account [subcommand] [--account <accountId>]
+```
+
+Flags:
+
+| Flag | Meaning | Notes |
+|---|---|---|
+| `--account <accountId>` | inspect or mutate a specific Cloudflare account instead of the primary account | most useful for `info`, `workers`, `kv`, `d1`, `r2`, `vectorize`, `limits`, and `usage`; the interactive `global` and `workspace` selectors do not depend on it |
+
+Subcommands:
+
+| Subcommand | Meaning | Notes |
+|---|---|---|
+| `info` | show account overview | default when no subcommand is provided |
+| `workers` | list Workers scripts | requires Cloudflare auth |
+| `kv` | list KV namespaces | requires Cloudflare auth |
+| `d1` | list D1 databases | requires Cloudflare auth |
+| `r2` | list R2 buckets | requires Cloudflare auth |
+| `vectorize` | list Vectorize indexes | requires Cloudflare auth |
+| `limits` | show current Devflare-managed usage limits | supports nested actions described below |
+| `usage` | show current usage summary | requires Cloudflare auth |
+| `global` | interactively choose the global default account | stores selection under `~/.devflare/preferences.json` and may sync to cloud KV |
+| `workspace` | interactively choose the workspace account | writes nearest `package.json` |
+
+Nested `limits` actions:
+
+```text
+devflare account limits
+devflare account limits enable
+devflare account limits disable
+devflare account limits set <limit-name> <value>
+```
+
+Valid current limit names are:
+
+- `ai-requests`
+- `ai-tokens`
+- `vectorize-ops`
+
+### `ai`
+
+Usage:
+
+```text
+devflare ai
+```
+
+This command currently has no command-specific public flags. It prints Workers AI pricing/reference data.
+
+### `remote`
+
+Usage:
+
+```text
+devflare remote [status]
+devflare remote enable [minutes]
+devflare remote disable
+```
+
+This command currently has no command-specific flags. It is driven by subcommands and an optional positional minutes value.
+
+Important current behavior:
+
+- `status` is the default when you run `devflare remote` with no subcommand
+- `enable [minutes]` defaults to `30` when minutes are omitted or invalid
+- CLI enablement clamps duration into the current supported range of `1` to `1440` minutes
+- `disable` removes stored CLI remote-mode state, but does **not** unset `DEVFLARE_REMOTE`
+
+### `help` and `version`
+
+Usage:
+
+```text
+devflare help
+devflare version
+devflare --help
+devflare --version
+devflare -h
+devflare -v
+```
+
+The command forms and flag forms are equivalent public entrypoints.
+
 ### Generated artifacts
 
 Treat these as generated output:
 
 - project-root `wrangler.jsonc` written by build/deploy flows
 - `.devflare/` generated output used by the Vite/plugin side of the toolchain
+- `.devflare/data/` local persisted Miniflare state when you run `devflare dev --persist`
 - `.devflare/wrangler.jsonc` generated by the Vite plugin integration
 - generated `env.d.ts`
 
@@ -1610,7 +1991,12 @@ These are core Devflare strengths today:
 	 - the default build/deploy commands still center on Vite output
 	 - verify actual project behavior when relying on these fields
 
-14. **native config intentionally models only part of Wrangler’s total surface**
+14. **there is no stable public local-R2 browser URL contract today**
+	 - Devflare uses internal `/_devflare/*` routes for dev-server behavior
+	 - treat those as implementation details rather than app-facing URLs
+	 - if you build local preview tooling, keep object keys as the durable identifier and treat preview URLs as disposable
+
+15. **native config intentionally models only part of Wrangler’s total surface**
 	 - for unsupported or not-yet-modeled Wrangler keys, use `wrangler.passthrough`
 
 This is the right way to think about Devflare:
@@ -1748,4 +2134,6 @@ If you only remember a few things, remember these:
 10. `createTestContext()` is caller-relative and not every test helper behaves the same way around `waitUntil()`
 11. `devflare/test` plus unified `env` is a major part of the package’s value
 12. use `ref()` for multi-worker composition instead of magic strings
-13. when native config does not cover a Wrangler feature, use `wrangler.passthrough`
+13. store R2 object keys as the durable identifier instead of storing full delivery URLs
+14. treat local preview or inspector URLs as dev conveniences, not as the production file-delivery contract
+15. when native config does not cover a Wrangler feature, use `wrangler.passthrough`

package/R2.md

@@ -0,0 +1,170 @@
+# R2
+
+A short guide for handling uploads and file delivery with Cloudflare R2.
+
+---
+
+## Quick rules
+
+- Use **presigned `PUT` URLs** for direct user uploads to R2
+- Use a **public bucket on a custom domain** for truly public assets
+- Use a **private bucket + Worker authorization** for authenticated/private assets
+- Use **Cloudflare Access** for teammate/org-only buckets
+- Use **WAF token auth / HMAC validation** or a **Worker** for expiring custom-domain media links
+- Do **not** use `r2.dev` for production delivery
+- If you protect a custom-domain bucket with Access or WAF, **disable `r2.dev`** or the bucket may still be reachable there
+
+---
+
+## Uploads
+
+The usual safe upload flow is:
+
+1. frontend asks your app for upload permission
+2. your Worker/app authenticates the user and validates file type, size, and target key
+3. your backend returns a short-lived **presigned `PUT` URL**
+4. the browser uploads **directly to R2**
+5. your app stores the **object key + metadata**, not the presigned URL
+
+Good practice:
+
+- generate keys server-side, for example `users/<userId>/<uuid>.jpg`
+- restrict `Content-Type` when signing uploads
+- keep upload URLs short-lived
+- configure bucket **CORS** if the browser uploads directly
+
+Cloudflare docs:
+
+- [Presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+- [Configure CORS](https://developers.cloudflare.com/r2/buckets/cors/)
+- [Storing user generated content](https://developers.cloudflare.com/reference-architecture/diagrams/storage/storing-user-generated-content/)
+
+---
+
+## Viewing / serving files
+
+### Public files
+
+For public images, media, and assets:
+
+- use a **public bucket**
+- attach a **custom domain**
+- serve stable URLs from that domain
+- let Cloudflare cache them
+
+This is the best fit for avatars, product images, blog images, and other content that anyone may view.
+
+Cloudflare docs:
+
+- [Public buckets](https://developers.cloudflare.com/r2/buckets/public-buckets/)
+
+### Private or authenticated files
+
+For invoices, receipts, private user uploads, paid content, or tenant-scoped assets:
+
+- keep the bucket **private**
+- store only the object key in your database
+- serve through a **Worker** that checks session/JWT/permissions before reading from R2
+
+This is usually the best default when access depends on the current user.
+
+Cloudflare docs:
+
+- [Use R2 from Workers](https://developers.cloudflare.com/r2/api/workers/workers-api-usage/)
+
+### Time-limited direct access
+
+You can also mint a **presigned `GET` URL** for temporary direct viewing or download.
+
+Important caveat:
+
+- presigned URLs work on the **R2 S3 endpoint**
+- they **do not work with custom domains**
+- treat them as **bearer tokens**
+
+So they are good for short-lived direct access, but not for polished custom-domain media delivery.
+
+Cloudflare docs:
+
+- [Presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+
+### Team-only / org-only files
+
+If access should be limited to employees or teammates, protect the R2 custom domain with **Cloudflare Access**.
+
+Cloudflare docs:
+
+- [Protect an R2 Bucket with Cloudflare Access](https://developers.cloudflare.com/r2/tutorials/cloudflare-access/)
+
+### Signed links on a custom domain
+
+If you want expiring links on `https://cdn.example.com/...`, R2 presigned URLs are not the right tool.
+
+Instead use:
+
+- a **Worker** that signs and verifies access tokens, or
+- **Cloudflare WAF token authentication / HMAC validation** on the custom domain
+
+Cloudflare docs:
+
+- [Configure token authentication](https://developers.cloudflare.com/waf/custom-rules/use-cases/configure-token-authentication/)
+- [HMAC validation function](https://developers.cloudflare.com/ruleset-engine/rules-language/functions/#hmac-validation)
+- [Workers request signing example](https://developers.cloudflare.com/workers/examples/signing-requests/)
+
+---
+
+## Development vs production
+
+### Development
+
+By default, local Worker development uses **local simulated bindings**, including local R2-style storage.
+
+Use this for normal development.
+
+Only connect to real remote buckets when you intentionally need integration testing, and prefer **separate dev/staging buckets** instead of production buckets.
+
+Important remote-dev reality:
+
+- remote bindings touch **real data**
+- remote bindings incur **real costs**
+- avoid pointing local development at production uploads unless absolutely necessary
+
+Cloudflare docs:
+
+- [Workers development & testing](https://developers.cloudflare.com/workers/development-testing/)
+- [Remote bindings](https://developers.cloudflare.com/workers/development-testing/#remote-bindings)
+
+### Production
+
+For production:
+
+- use a **custom domain**, not `r2.dev`
+- choose public vs private intentionally per bucket or per content class
+- keep sensitive content private behind a Worker, Access, or token validation
+- configure **CORS** intentionally for browser upload/download flows
+- use separate **dev**, **staging**, and **prod** buckets
+
+Optional performance feature:
+
+- if users upload from many regions, consider **Local Uploads** for better upload performance
+
+Cloudflare docs:
+
+- [Public buckets](https://developers.cloudflare.com/r2/buckets/public-buckets/)
+- [Local uploads](https://developers.cloudflare.com/r2/buckets/local-uploads/)
+
+---
+
+## Recommended defaults
+
+If you need a sane default architecture:
+
+- **public assets** → public bucket + custom domain
+- **user uploads** → presigned `PUT` upload + object key stored in DB
+- **private assets** → private bucket + Worker-gated reads
+- **internal assets** → custom domain + Cloudflare Access
+- **custom-domain expiring links** → Worker token auth or WAF HMAC validation
+
+If you only remember one rule, remember this:
+
+> Use **presigned URLs** for short-lived direct R2 access, but use a **Worker/custom domain auth layer** for polished private media delivery.

package/dist/{dev-pa8dhm20.js → dev-b9dmrj7b.js}

@@ -21,7 +21,7 @@ import { createConsola } from "consola";
 import { resolve as resolve3 } from "pathe";
 
 // src/dev-server/server.ts
-import { resolve as resolve2 } from "pathe";
+import { dirname as dirname2, resolve as resolve2 } from "pathe";
 
 // src/bundler/do-bundler.ts
 import { resolve, dirname, relative } from "pathe";
@@ -1093,8 +1093,60 @@ async function checkRemoteBindingRequirements(config) {
 }
 
 // src/dev-server/server.ts
-function getGatewayScript(wsRoutes = [], debug = false) {
+var DEFAULT_FETCH_ENTRY_FILES = [
+  "src/fetch.ts",
+  "src/fetch.js",
+  "src/fetch.mts",
+  "src/fetch.mjs"
+];
+var INTERNAL_APP_SERVICE_BINDING = "__DEVFLARE_APP";
+async function resolveMainWorkerScriptPath(cwd, config) {
+  if (config.files?.fetch === false) {
+    return null;
+  }
+  const fs = await import("node:fs/promises");
+  const candidates = new Set;
+  if (typeof config.files?.fetch === "string" && config.files.fetch) {
+    candidates.add(config.files.fetch);
+  }
+  for (const defaultEntry of DEFAULT_FETCH_ENTRY_FILES) {
+    candidates.add(defaultEntry);
+  }
+  for (const candidate of candidates) {
+    const absolutePath = resolve2(cwd, candidate);
+    try {
+      await fs.access(absolutePath);
+      return absolutePath;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function collectWorkerWatchRoots(cwd, config, mainWorkerScriptPath) {
+  const roots = new Set;
+  const addFileParent = (filePath) => {
+    if (typeof filePath !== "string" || !filePath) {
+      return;
+    }
+    roots.add(dirname2(resolve2(cwd, filePath)));
+  };
+  if (mainWorkerScriptPath) {
+    roots.add(dirname2(mainWorkerScriptPath));
+  }
+  addFileParent(config.files?.fetch);
+  addFileParent(config.files?.queue);
+  addFileParent(config.files?.scheduled);
+  addFileParent(config.files?.email);
+  addFileParent(config.files?.transport);
+  if (config.files?.routes && typeof config.files.routes === "object") {
+    roots.add(resolve2(cwd, config.files.routes.dir));
+  }
+  return [...roots];
+}
+function getGatewayScript(wsRoutes = [], debug = false, appServiceBindingName = null) {
   const wsRoutesJson = JSON.stringify(wsRoutes);
+  const appServiceBindingJson = JSON.stringify(appServiceBindingName);
   return `
 // Bridge Gateway Worker — RPC Handler
 // Handles all binding operations via WebSocket RPC
@@ -1109,6 +1161,7 @@ const incomingStreams = new Map()
 
 // WebSocket routes configuration (injected at build time)
 const WS_ROUTES = ${wsRoutesJson}
+const APP_SERVICE_BINDING = ${appServiceBindingJson}
 
 export default {
 	async fetch(request, env, ctx) {
@@ -1149,6 +1202,13 @@ export default {
 			}), { headers: { 'Content-Type': 'application/json' } })
 		}
 
+		if (APP_SERVICE_BINDING) {
+			const appWorker = env[APP_SERVICE_BINDING]
+			if (appWorker && typeof appWorker.fetch === 'function') {
+				return appWorker.fetch(request)
+			}
+		}
+
 		return new Response('Devflare Bridge Gateway', { status: 200 })
 	}
 }
@@ -1676,15 +1736,63 @@ function createDevServer(options) {
   } = options;
   let miniflare = null;
   let doBundler = null;
+  let workerSourceWatcher = null;
   let viteProcess = null;
   let config = null;
   let browserShim = null;
   let browserShimPort = 8788;
+  let mainWorkerScriptPath = null;
+  let bundledMainWorkerScriptPath = null;
+  let currentDoResult = null;
+  let reloadChain = Promise.resolve();
+  async function bundleMainWorker() {
+    if (!mainWorkerScriptPath) {
+      bundledMainWorkerScriptPath = null;
+      return;
+    }
+    if (typeof Bun === "undefined" || typeof Bun.build !== "function") {
+      throw new Error("Worker-only dev mode requires the Bun runtime for main worker bundling");
+    }
+    const fs = await import("node:fs/promises");
+    const outDir = resolve2(cwd, ".devflare", "worker-bundles");
+    await fs.rm(outDir, { recursive: true, force: true });
+    await fs.mkdir(outDir, { recursive: true });
+    const result = await Bun.build({
+      entrypoints: [mainWorkerScriptPath],
+      outdir: outDir,
+      target: "browser",
+      format: "esm",
+      minify: false,
+      splitting: false,
+      external: ["cloudflare:workers", "cloudflare:*"]
+    });
+    if (!result.success || result.outputs.length === 0) {
+      const logs = result.logs.map((log) => ("message" in log) ? log.message : String(log)).join(`
+`);
+      throw new Error(`Failed to bundle main worker:
+${logs}`);
+    }
+    bundledMainWorkerScriptPath = result.outputs[0].path;
+    logger?.debug(`Bundled main worker → ${bundledMainWorkerScriptPath}`);
+  }
   function buildMiniflareConfig(doResult) {
     if (!config)
       throw new Error("Config not loaded");
-    const bindings = config.bindings ?? {};
+    const loadedConfig = config;
+    const bindings = loadedConfig.bindings ?? {};
     const persistPath = resolve2(cwd, ".devflare/data");
+    const appWorkerName = loadedConfig.name;
+    const shouldRunMainWorker = !enableVite && !!mainWorkerScriptPath;
+    const queueProducers = (() => {
+      if (!bindings.queues?.producers) {
+        return;
+      }
+      const producers = {};
+      for (const [bindingName, queueName] of Object.entries(bindings.queues.producers)) {
+        producers[bindingName] = { queueName };
+      }
+      return producers;
+    })();
     const sharedOptions = {
       port: miniflarePort,
       host: "127.0.0.1",
@@ -1693,19 +1801,67 @@ function createDevServer(options) {
       d1Persist: persist ? `${persistPath}/d1` : undefined,
       durableObjectsPersist: persist ? `${persistPath}/do` : undefined
     };
-    const gatewayWorker = {
-      name: "gateway",
-      modules: true,
-      script: getGatewayScript(config.wsRoutes, debug),
-      compatibilityDate: config.compatibilityDate,
-      compatibilityFlags: config.compatibilityFlags ?? [],
-      routes: ["*"],
-      kvNamespaces: bindings.kv ? bindings.kv : undefined,
-      r2Buckets: bindings.r2 ? bindings.r2 : undefined,
-      d1Databases: bindings.d1 ? bindings.d1 : undefined,
-      bindings: config.vars
+    const createServiceBindings = (extraBindings = {}) => {
+      const serviceBindings = {};
+      if (bindings.services) {
+        for (const [bindingName, serviceConfig] of Object.entries(bindings.services)) {
+          serviceBindings[bindingName] = {
+            name: serviceConfig.service,
+            ...serviceConfig.entrypoint && { entrypoint: serviceConfig.entrypoint }
+          };
+        }
+      }
+      for (const [bindingName, target] of Object.entries(extraBindings)) {
+        serviceBindings[bindingName] = target;
+      }
+      return Object.keys(serviceBindings).length > 0 ? serviceBindings : undefined;
+    };
+    const createWorkerConfig = (options2) => {
+      const baseFlags = loadedConfig.compatibilityFlags ?? [];
+      const compatFlags = baseFlags.includes("nodejs_compat") ? baseFlags : [...baseFlags, "nodejs_compat"];
+      const workerConfig = {
+        name: options2.name,
+        modules: true,
+        compatibilityDate: loadedConfig.compatibilityDate,
+        compatibilityFlags: compatFlags,
+        ...bindings.kv && { kvNamespaces: bindings.kv },
+        ...bindings.r2 && { r2Buckets: bindings.r2 },
+        ...bindings.d1 && { d1Databases: bindings.d1 },
+        ...loadedConfig.vars && Object.keys(loadedConfig.vars).length > 0 && { bindings: loadedConfig.vars },
+        ...queueProducers && { queueProducers }
+      };
+      if (options2.scriptPath) {
+        workerConfig.scriptPath = options2.scriptPath;
+        workerConfig.modulesRoot = cwd;
+        workerConfig.modulesRules = [
+          { type: "ESModule", include: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.mjs"] },
+          { type: "CommonJS", include: ["**/*.js", "**/*.cjs"] },
+          { type: "ESModule", include: ["**/*.jsx"] }
+        ];
+      }
+      if (options2.script) {
+        workerConfig.script = options2.script;
+      }
+      if (options2.durableObjects && Object.keys(options2.durableObjects).length > 0) {
+        workerConfig.durableObjects = options2.durableObjects;
+      }
+      if (options2.serviceBindings && Object.keys(options2.serviceBindings).length > 0) {
+        workerConfig.serviceBindings = options2.serviceBindings;
+      }
+      return workerConfig;
     };
-    if (!doResult || doResult.bundles.size === 0) {
+    const gatewayWorker = createWorkerConfig({
+      name: "gateway",
+      script: getGatewayScript(loadedConfig.wsRoutes, debug, shouldRunMainWorker ? INTERNAL_APP_SERVICE_BINDING : null),
+      serviceBindings: shouldRunMainWorker ? createServiceBindings({
+        [INTERNAL_APP_SERVICE_BINDING]: { name: appWorkerName }
+      }) : createServiceBindings()
+    });
+    gatewayWorker.routes = ["*"];
+    const hasDurableObjectBundles = !!doResult && doResult.bundles.size > 0;
+    const browserBindingName = bindings.browser?.binding;
+    const needsBrowserWorker = Boolean(browserBindingName && (hasDurableObjectBundles || shouldRunMainWorker));
+    if (!shouldRunMainWorker && !hasDurableObjectBundles && !needsBrowserWorker) {
       return {
         ...sharedOptions,
         ...gatewayWorker
@@ -1714,56 +1870,62 @@ function createDevServer(options) {
     const workers = [];
     const durableObjects = {};
     const browserShimUrl = `http://127.0.0.1:${browserShimPort}`;
-    const browserBindingName = bindings.browser?.binding;
     const browserWorkerName = "browser-binding";
-    for (const [bindingName, bundlePath] of doResult.bundles) {
-      const className = doResult.classes.get(bindingName);
-      if (!className)
-        continue;
-      const workerName = `do-${bindingName.toLowerCase()}`;
-      const baseFlags = config.compatibilityFlags ?? [];
-      const compatFlags = baseFlags.includes("nodejs_compat") ? baseFlags : [...baseFlags, "nodejs_compat"];
-      const workerConfig = {
-        name: workerName,
-        modules: true,
-        modulesRoot: cwd,
-        modulesRules: [
-          { type: "CommonJS", include: ["**/*.js", "**/*.cjs"] },
-          { type: "ESModule", include: ["**/*.mjs"] }
-        ],
-        scriptPath: bundlePath,
-        compatibilityDate: config.compatibilityDate,
-        compatibilityFlags: compatFlags,
-        durableObjects: {
-          [bindingName]: className
+    if (shouldRunMainWorker && mainWorkerScriptPath) {
+      const mainWorkerServiceBindings = createServiceBindings(browserBindingName ? {
+        [browserBindingName]: { name: browserWorkerName }
+      } : {});
+      const mainWorkerConfig = createWorkerConfig({
+        name: appWorkerName,
+        scriptPath: bundledMainWorkerScriptPath ?? mainWorkerScriptPath,
+        serviceBindings: mainWorkerServiceBindings
+      });
+      workers.push(mainWorkerConfig);
+    }
+    if (doResult) {
+      for (const [bindingName, bundlePath] of doResult.bundles) {
+        const className = doResult.classes.get(bindingName);
+        if (!className)
+          continue;
+        const workerName = `do-${bindingName.toLowerCase()}`;
+        const workerConfig = createWorkerConfig({
+          name: workerName,
+          scriptPath: bundlePath,
+          durableObjects: {
+            [bindingName]: className
+          },
+          serviceBindings: createServiceBindings(browserBindingName ? {
+            [browserBindingName]: { name: browserWorkerName }
+          } : {})
+        });
+        if (browserBindingName) {
+          logger?.debug(`DO ${workerName} has browser service binding: ${browserBindingName} → ${browserWorkerName}`);
         }
-      };
-      if (browserBindingName) {
-        workerConfig.serviceBindings = {
-          ...workerConfig.serviceBindings,
-          [browserBindingName]: browserWorkerName
+        logger?.debug(`DO ${workerName} config:`, JSON.stringify(workerConfig, null, 2));
+        workers.push(workerConfig);
+        durableObjects[bindingName] = {
+          className,
+          scriptName: workerName
         };
-        logger?.debug(`DO ${workerName} has browser service binding: ${browserBindingName} → ${browserWorkerName}`);
       }
-      logger?.debug(`DO ${workerName} config:`, JSON.stringify(workerConfig, null, 2));
-      workers.push(workerConfig);
-      durableObjects[bindingName] = {
-        className,
-        scriptName: workerName
-      };
     }
-    if (browserBindingName) {
-      const browserWorker = {
+    if (needsBrowserWorker) {
+      const browserWorker = createWorkerConfig({
         name: browserWorkerName,
-        modules: true,
-        script: getBrowserBindingScript(browserShimUrl, debug),
-        compatibilityDate: config.compatibilityDate,
-        compatibilityFlags: config.compatibilityFlags ?? []
-      };
+        script: getBrowserBindingScript(browserShimUrl, debug)
+      });
       workers.push(browserWorker);
       logger?.info(`Browser binding worker configured: ${browserBindingName} → ${browserShimUrl}`);
     }
-    gatewayWorker.durableObjects = durableObjects;
+    if (Object.keys(durableObjects).length > 0) {
+      gatewayWorker.durableObjects = durableObjects;
+      if (shouldRunMainWorker) {
+        const mainWorker = workers.find((worker) => worker.name === appWorkerName);
+        if (mainWorker) {
+          mainWorker.durableObjects = durableObjects;
+        }
+      }
+    }
     return {
       ...sharedOptions,
       workers: [gatewayWorker, ...workers]
@@ -1817,14 +1979,93 @@ function createDevServer(options) {
     }
   }
   async function reloadMiniflare(doResult) {
-    if (!miniflare)
+    currentDoResult = doResult;
+    const queuedReload = reloadChain.then(async () => {
+      if (!miniflare)
+        return;
+      const { Log, LogLevel } = await import("miniflare");
+      const mfConfig = buildMiniflareConfig(currentDoResult);
+      mfConfig.log = new Log(LogLevel.DEBUG);
+      logger?.info("Reloading Miniflare...");
+      await miniflare.setOptions(mfConfig);
+      logger?.success("Miniflare reloaded");
+    });
+    reloadChain = queuedReload.catch(() => {});
+    await queuedReload;
+  }
+  async function startWorkerSourceWatcher() {
+    if (enableVite || !config || !mainWorkerScriptPath) {
       return;
-    const { Log, LogLevel } = await import("miniflare");
-    const mfConfig = buildMiniflareConfig(doResult);
-    mfConfig.log = new Log(LogLevel.DEBUG);
-    logger?.info("Reloading Miniflare with updated DOs...");
-    await miniflare.setOptions(mfConfig);
-    logger?.success("Miniflare reloaded");
+    }
+    const watchRoots = collectWorkerWatchRoots(cwd, config, mainWorkerScriptPath);
+    if (watchRoots.length === 0) {
+      return;
+    }
+    const chokidar = await import("chokidar");
+    const isWindows = process.platform === "win32";
+    const ignoredSegments = ["/node_modules/", "/.git/", "/.devflare/", "/dist/"];
+    const normalizePath = (filePath) => filePath.replace(/\\/g, "/");
+    const isIgnoredPath = (filePath) => {
+      const normalizedPath = normalizePath(filePath);
+      return ignoredSegments.some((segment) => normalizedPath.includes(segment));
+    };
+    let reloadTimeout = null;
+    let reloadInProgress = false;
+    let pendingReloadPath = null;
+    const triggerReload = async (filePath) => {
+      if (reloadInProgress) {
+        pendingReloadPath = filePath;
+        return;
+      }
+      reloadInProgress = true;
+      try {
+        logger?.info(`Worker source changed: ${filePath}`);
+        await bundleMainWorker();
+        await reloadMiniflare(currentDoResult);
+      } catch (error) {
+        logger?.error("Worker source reload failed:", error);
+      } finally {
+        reloadInProgress = false;
+        if (pendingReloadPath) {
+          const nextPath = pendingReloadPath;
+          pendingReloadPath = null;
+          await triggerReload(nextPath);
+        }
+      }
+    };
+    const scheduleReload = (filePath) => {
+      if (reloadTimeout) {
+        clearTimeout(reloadTimeout);
+      }
+      reloadTimeout = setTimeout(() => {
+        triggerReload(filePath);
+      }, 150);
+    };
+    workerSourceWatcher = chokidar.watch(watchRoots, {
+      ignoreInitial: true,
+      usePolling: isWindows,
+      interval: isWindows ? 300 : undefined,
+      awaitWriteFinish: {
+        stabilityThreshold: 100,
+        pollInterval: 50
+      },
+      ignored: (filePath) => isIgnoredPath(filePath)
+    });
+    const onFileEvent = (filePath) => {
+      if (isIgnoredPath(filePath)) {
+        return;
+      }
+      scheduleReload(filePath);
+    };
+    workerSourceWatcher.on("change", onFileEvent);
+    workerSourceWatcher.on("add", onFileEvent);
+    workerSourceWatcher.on("unlink", onFileEvent);
+    workerSourceWatcher.on("ready", () => {
+      logger?.info(`Worker source watcher ready (${watchRoots.length} root(s))`);
+    });
+    workerSourceWatcher.on("error", (error) => {
+      logger?.error("Worker source watcher error:", error);
+    });
   }
   async function runD1Migrations() {
     if (!miniflare || !config?.bindings?.d1)
@@ -1911,6 +2152,13 @@ function createDevServer(options) {
     logger?.info("Starting unified dev server...");
     config = await loadConfig({ cwd, configFile: configPath });
     logger?.debug("Loaded config:", config.name);
+    mainWorkerScriptPath = await resolveMainWorkerScriptPath(cwd, config);
+    if (!enableVite && mainWorkerScriptPath) {
+      logger?.info(`Worker entry detected: ${mainWorkerScriptPath}`);
+      await bundleMainWorker();
+    } else if (!enableVite) {
+      logger?.warn("No local fetch worker entry was found for worker-only mode");
+    }
     const remoteCheck = await checkRemoteBindingRequirements(config);
     if (remoteCheck.hasRemoteBindings) {
       logger?.info("");
@@ -1961,9 +2209,12 @@ function createDevServer(options) {
         }
       });
       doResult = await doBundler.build();
+      currentDoResult = doResult;
       await doBundler.watch();
     }
+    currentDoResult = doResult;
     await startMiniflare(doResult);
+    await startWorkerSourceWatcher();
     if (enableVite) {
       await startVite();
     } else {
@@ -1977,6 +2228,10 @@ function createDevServer(options) {
       await doBundler.close();
       doBundler = null;
     }
+    if (workerSourceWatcher) {
+      await workerSourceWatcher.close();
+      workerSourceWatcher = null;
+    }
     if (miniflare) {
       await miniflare.dispose();
       miniflare = null;

package/dist/dev-server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/dev-server/server.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,WAAW,CAAA;AAc3D,MAAM,WAAW,gBAAgB;IAChC,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sBAAsB;IACtB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,SAAS;IACzB,2BAA2B;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,0BAA0B;IAC1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,yCAAyC;IACzC,YAAY,IAAI,aAAa,GAAG,IAAI,CAAA;CACpC;AA2kBD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA4epE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/dev-server/server.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,WAAW,CAAA;AAc3D,MAAM,WAAW,gBAAgB;IAChC,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sBAAsB;IACtB,MAAM,CAAC,EAAE,eAAe,CAAA;IACxB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,SAAS;IACzB,2BAA2B;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,0BAA0B;IAC1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,yCAAyC;IACzC,YAAY,IAAI,aAAa,GAAG,IAAI,CAAA;CACpC;AAmqBD,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAkuBpE"}

package/dist/index.js

@@ -216,7 +216,7 @@ async function runInit(parsed, logger, options) {
   return runInitCommand(parsed, logger, options);
 }
 async function runDev(parsed, logger, options) {
-  const { runDevCommand } = await import("./dev-pa8dhm20.js");
+  const { runDevCommand } = await import("./dev-b9dmrj7b.js");
   return runDevCommand(parsed, logger, options);
 }
 async function runBuild(parsed, logger, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "devflare",
-	"version": "1.0.0-next.3",
+	"version": "1.0.0-next.5",
 	"description": "Devflare is a developer-first toolkit for Cloudflare Workers that sits on top of Miniflare and Wrangler-compatible config",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -48,7 +48,8 @@
 	"files": [
 		"dist",
 		"bin",
-		"LLM.md"
+		"LLM.md",
+		"R2.md"
 	],
 	"scripts": {
 		"prebuild": "node -e \"require('fs').rmSync('./dist', { recursive: true, force: true })\"",