devflare 1.0.0-next.15 → 1.0.0-next.17

package/README.md

@@ -22,20 +22,30 @@ For the deeper public contract, caveats, and current feature boundaries, see [`L
 
 ---
 
-## Install
+## Monorepo contributor workflow
 
-For a worker-only project, Devflare works fine with just the Worker toolchain:
+When you are working on `packages/devflare` inside this monorepo, use the repo-root Turbo scripts instead of assembling ad-hoc commands by hand:
 
-```bash
-bun add -d devflare wrangler @cloudflare/workers-types
-```
+- `bun run devflare:dev`
+- `bun run devflare:test:watch`
+- `bun run devflare:build`
+- `bun run devflare:typecheck`
+- `bun run devflare:test`
+- `bun run devflare:types`
+- `bun run devflare:check`
+- `bun run devflare:ci`
+
+These scripts intentionally keep the default shared lane focused on the parts of the workspace that are currently stable in local development and CI. In particular, the shared test lane excludes `@devflare/case5-multi-worker`, and the shared check lane stays centered on `apps/documentation` because `cases/case18` still expects Cloudflare-backed resource resolution outside the default contributor workflow.
+
+---
+
+## Install
 
-If the current package also uses Vite, add Vite and the Cloudflare Vite plugin too:
+For a worker-only project, the smallest install is just Devflare:
 
 ```bash
-bun add -d devflare wrangler @cloudflare/workers-types vite @cloudflare/vite-plugin
+bun add -d devflare vite @cloudflare/vite-plugin
 ```
-
 A local `vite.config.*` opts that package into Vite-backed flows. Without one, Devflare stays in worker-only mode.
 
 ---
@@ -46,7 +56,7 @@ A local `vite.config.*` opts that package into Vite-backed flows. Without one, D
 
 ```ts
 // devflare.config.ts
-import { defineConfig } from 'devflare'
+import { defineConfig } from 'devflare/config'
 
 export default defineConfig({
 	name: 'hello-worker',
@@ -57,19 +67,16 @@ export default defineConfig({
 })
 ```
 
+Use `devflare/config` for config files so Bun only loads the lightweight config helpers instead of the full Node-side Devflare barrel.
+
 ### 2. Add a fetch handler
 
 ```ts
 // src/fetch.ts
 import type { FetchEvent } from 'devflare/runtime'
 
-export async function fetch({ request }: FetchEvent): Promise<Response> {
-	const url = new URL(request.url)
-	return new Response(
-		url.pathname === '/'
-			? 'Hello from Devflare'
-			: `Hello from Devflare: ${url.pathname}`
-	)
+export async function fetch({ url }: FetchEvent): Promise<Response> {
+	return new Response(`Hello from Devflare: ${url.pathname}`)
 }
 ```
 
@@ -79,8 +86,6 @@ export async function fetch({ request }: FetchEvent): Promise<Response> {
 bunx --bun devflare types
 ```
 
-This generates `env.d.ts` so bindings, secrets, and discovered entrypoints stay typed.
-
 ### 4. Start development
 
 ```bash
@@ -115,14 +120,17 @@ Use subpaths intentionally.
 
 | Import | Use for |
 |---|---|
-| `devflare` | main package entrypoint: config helpers, `ref()`, unified `env`, bridge helpers, CLI helpers, decorators |
-| `devflare/runtime` | worker-safe runtime helpers like `env`, `ctx`, `event`, `locals`, event types/getters, middleware helpers |
-| `devflare/test` | `createTestContext`, `cf.*`, mock helpers, bridge test context, skip helpers |
+| `devflare` | main package entrypoint: `defineConfig`, `defineWorker`, `ref()`, the unified `env`/`ctx`/`event`/`locals` proxies, `sequence`, `defineFetchHandler`, decorators |
+| `devflare/config` | lightweight config-only entry for `devflare.config.ts` files (Bun loads only the config helpers, not the full Node-side barrel) |
+| `devflare/runtime` | worker-safe runtime helpers: strict `env`, `ctx`, `event`, `locals`, event types/getters, middleware helpers |
+| `devflare/test` | `createTestContext`, `cf.*`, mock helpers (`createMockKV`/`createMockD1`/`createMockR2`/`createMockEnv`/`createMockTestContext`/`withTestContext`) |
 | `devflare/vite` | Vite integration |
 | `devflare/sveltekit` | SvelteKit integration |
 | `devflare/cloudflare` | Cloudflare account/auth/usage/limits/preferences helpers |
 | `devflare/decorators` | decorators only |
 
+Internal bridge and transform helpers are intentionally not re-exported from bare `'devflare'`. If you previously imported them from the main entry, switch to the matching subpath — see "Public API surface and migration notes" below.
+
 ### Runtime import rule of thumb
 
 - use `import { env } from 'devflare/runtime'` for **strict request-scoped runtime access**
@@ -193,8 +201,8 @@ async function corsHandle(event: FetchEvent, resolve: ResolveFetch): Promise<Res
 	return next
 }
 
-async function appFetch({ request }: FetchEvent): Promise<Response> {
-	return Response.json({ path: new URL(request.url).pathname })
+async function appFetch({ url }: FetchEvent): Promise<Response> {
+	return Response.json({ path: url.pathname })
 }
 
 export const handle = sequence(corsHandle, appFetch)
@@ -299,6 +307,7 @@ The most important top-level keys are:
 - `accountId`
 - `compatibilityDate`
 - `compatibilityFlags`
+- `previews`
 - `files`
 - `bindings`
 - `triggers`
@@ -322,13 +331,14 @@ Keep these separate:
 - `vars` are **string-valued config bindings** that compile into generated Wrangler config
 - `secrets` are **declarations of expected runtime secret bindings**
 
-`loadConfig()` does **not** do dotenv loading by itself.
+`loadConfig()` loads the nearest workspace-root `.env` before evaluating `devflare.config.*`.
 
-When you run the CLI under Bun, Bun may already have loaded `.env` values into `process.env` before your config executes.
+When Devflare finds an ancestor `package.json` with `workspaces`, it uses that directory's `.env` file as the shared config-time source for nested packages. If no workspace root is found, it falls back to the nearest ancestor `.env`. Explicit process env values still win over `.env` entries.
 
 Important boundary:
 
-- `.env*` files are config/build-time inputs only insofar as the surrounding host tool has already populated `process.env`
+- `.env` is treated as a config/build-time input for `devflare.config.*` evaluation
+- Devflare does **not** currently provide first-class semantics for `.env.dev` or `.env.<name>`
 - Devflare does **not** currently provide a first-class `.dev.vars*` loader for worker-only dev mode or `createTestContext()`
 - example files like `.env.example` and `.dev.vars.example` are a team convention, not a Devflare feature
 
@@ -348,14 +358,17 @@ When you select `--env name`, Devflare merges `config.env[name]` into the base c
 
 `bindings.d1` accepts three shapes:
 
-- `'database-id'`
+- `'database-name'`
 - `{ id: 'database-id' }`
 - `{ name: 'database-name' }`
 
-Use `{ name }` when you want `devflare.config.*` to stay the source of truth for stable D1 naming.
+String shorthand is the stable-name form, so `'database-name'` is equivalent to `{ name: 'database-name' }`.
 
-- local dev and tests normalize `{ name }` into a stable local identifier, so you do **not** need Cloudflare auth just to run locally
-- `build`, `deploy`, `devflare/vite`, and `devflare config print` resolve `{ name }` into a real Cloudflare D1 database id before they emit Wrangler-facing config
+Use string shorthand or `{ name }` when you want `devflare.config.*` to stay the source of truth for stable D1 naming.
+
+- local dev and tests normalize string and `{ name }` bindings into a stable local identifier, so you do **not** need Cloudflare auth just to run locally
+- `build`, `deploy`, `devflare/vite`, and `devflare config print` resolve string and `{ name }` bindings into a real Cloudflare D1 database id before they emit Wrangler-facing config
+- `compileConfig()` can only emit Wrangler `d1_databases` from concrete ids, so Node-side automation should call `loadResolvedConfig()` or `resolveConfigResources()` first
 
 That means stable names stay in config, while opaque Cloudflare ids are resolved only for the flows that actually need them.
 
@@ -380,7 +393,7 @@ console.log(config.bindings?.d1?.DB)
 If you need Cloudflare account/resource data while computing config, use an async config with `devflare/cloudflare` helpers:
 
 ```ts
-import { defineConfig } from 'devflare'
+import { defineConfig } from 'devflare/config'
 import { account } from 'devflare/cloudflare'
 
 export default defineConfig(async () => {
@@ -468,12 +481,13 @@ Devflare natively models:
 - KV, D1, R2, Durable Objects, queues, and the core test/runtime flow are the strongest surfaces
 - AI and Vectorize are remote-oriented bindings
 - named service entrypoints are modeled at the Devflare layer, but validate generated deployment output if they are critical to your app
+- browser bindings use a named-map authoring shape such as `browser: { BROWSER: 'browser' }`, but current compile/deploy flows allow exactly one browser binding because Wrangler only supports one
 - `sendEmail` is modeled through config compilation, generated env types, and local runtime/test flows
 - R2 bindings are real in local dev/test/runtime flows, but Devflare does **not** publish a stable browser-facing local bucket URL contract; browser-visible local asset flows should go through your Worker routes
 
-For R2 delivery strategy guidance, see [`R2.md`](./R2.md).
+For R2 delivery strategy guidance, use the `R2 uploads & delivery` page in the documentation site.
 
-For D1, prefer stable config names when you can:
+For D1 and Hyperdrive, prefer stable config names when you can:
 
 ```ts
 export default {
@@ -482,6 +496,10 @@ export default {
 			DB: { name: 'app-db' },
 			AUDIT: { id: 'existing-d1-id' }
 		},
+		hyperdrive: {
+			DB: 'app-postgres',
+				ANALYTICS_DB: { id: 'existing-hyperdrive-id' }
+		},
 		r2: {
 			ASSETS: 'app-assets'
 		}
@@ -489,7 +507,7 @@ export default {
 }
 ```
 
-Use `.env*` and `secrets` for values that are actually secret or genuinely process-specific. Do **not** move stable bucket/database names into env vars just to make other tooling happy.
+Use `.env*` and `secrets` for values that are actually secret or genuinely process-specific. Do **not** move stable bucket/database/Hyperdrive names into env vars just to make other tooling happy.
 
 ---
 
@@ -526,7 +544,226 @@ Short version:
 - in worker-only mode, Devflare now bundles the composed main worker to `.devflare/worker-entrypoints/main.js` via Rolldown before handing it to Miniflare or Wrangler
 - Rolldown still rebuilds Durable Object worker code in unified Vite dev flows where Vite hosts the outer app
 
-For the full contract-level explanation and a concrete Rolldown + Svelte example, see [`LLM.md`](./LLM.md).
+For the full contract-level explanation and a concrete Rolldown + Svelte example, see the generated [`LLM.md`](./LLM.md) handbook entries for workflow modes and Svelte in workers.
+
+---
+
+## Deploys, previews, tokens, and GitHub Actions
+
+### Production deploys vs same-Worker previews
+
+`devflare deploy` publishes production the usual Wrangler way.
+
+`devflare deploy --preview` is different: it uploads a **new version of the same Worker** with `wrangler versions upload` instead of creating a separate Worker environment.
+
+Named preview deploys are now the primary preview model:
+
+- each preview scope deploys its own dedicated Worker (or Worker family)
+- preview-scoped bindings and resources can be assigned only to that scope
+- feature branches and PRs get stable preview URLs from the scope name itself
+
+Preview scope names should still be lowercase and dash-friendly so they map cleanly into Worker names and `workers.dev` URLs.
+
+Useful preview examples:
+
+```bash
+bunx --bun devflare deploy --preview next
+bunx --bun devflare deploy --preview pr-42
+```
+
+When available, Devflare prints the Worker version id and preview URL outputs after the deploy finishes.
+
+### Login and preview scope helpers
+
+`devflare login` is the thin authentication wrapper for Cloudflare.
+
+- by default it reuses existing auth when Devflare can already resolve a Cloudflare API token
+- `devflare login --force` opens `wrangler login` again even when auth is already present
+- after login, Devflare prints the primary account when Cloudflare account discovery succeeds
+
+`devflare previews` is the config-aware preview-scope surface for dedicated preview Workers.
+
+Useful commands:
+
+```bash
+bunx --bun devflare previews
+bunx --bun devflare previews bindings --scope next
+bunx --bun devflare previews cleanup --scope next --apply
+bunx --bun devflare previews cleanup --all --apply
+```
+
+Current behavior:
+
+- `devflare previews` lists stable workers plus discovered dedicated preview scopes for the current worker family using live Cloudflare Worker names
+- `devflare previews bindings` resolves preview-scoped resources for one scope and shows how many deployed workers reference them
+- `devflare previews cleanup` deletes dedicated preview Workers plus preview-scoped KV, D1, R2, Queue, Vectorize, and reusable Hyperdrive resources for one scope or every discovered scope; it is a dry run unless `--apply` is present
+- `devflare deploy` still performs best-effort internal preview metadata synchronization after successful deploys so cleanup flows can remove deleted preview workers cleanly without extra CI glue
+
+### Manage Devflare tokens
+
+`devflare tokens <bootstrap-token>` manages Devflare-owned account API tokens using a bootstrap token that already has Cloudflare API-token-management permission.
+
+The command:
+
+- resolves the effective account id from `--account`, workspace preference, or the bootstrap token's primary account
+- normalizes managed token names to the `devflare-` prefix, so `preview` becomes `devflare-preview` while `devflare-preview` stays unchanged
+- `--new [token-name]` prompts for a token name when it is omitted, then creates a new Devflare-managed account-owned token from the curated Devflare permission set
+- `--new [token-name] --all-flags` uses every reusable account-scoped permission group visible to the bootstrap token except `Account API Tokens*`, because Cloudflare does not allow sub-tokens to inherit token-management permission and account-owned tokens skip incompatible zone/user-scoped groups automatically
+- `--list` lists only the Devflare-managed tokens in the selected account
+- `--delete [token-name]` deletes the matching Devflare-managed token after normalizing the name to the `devflare-` prefix
+- `--delete-all` deletes every Devflare-managed token in the selected account while leaving non-Devflare account tokens untouched
+- prints a new token value once, because Cloudflare only returns the secret a single time
+
+Examples:
+
+```bash
+bunx --bun devflare tokens <bootstrap-token> --new preview
+bunx --bun devflare tokens <bootstrap-token> --new preview --all-flags
+bunx --bun devflare tokens <bootstrap-token> --list
+bunx --bun devflare tokens <bootstrap-token> --delete preview
+bunx --bun devflare tokens <bootstrap-token> --delete-all
+```
+
+### Thin GitHub Action and caller workflows
+
+The repo ships a reusable composite action at [`.github/actions/devflare-deploy`](../../.github/actions/devflare-deploy).
+
+The repo also ships a shared workspace setup action at [`.github/actions/devflare-setup-workspace`](../../.github/actions/devflare-setup-workspace) so one workflow job can install dependencies once and then deploy multiple preview targets from the same checkout.
+
+The repo also ships a GitHub-feedback action at [`.github/actions/devflare-github-feedback`](../../.github/actions/devflare-github-feedback) for publishing deployment results back into GitHub.
+
+The action stays intentionally thin:
+
+- the caller workflow owns the runner, triggers, permissions, and environments
+- Cloudflare credentials must be passed in explicitly
+- by default, the action asks `devflare deploy` to verify Cloudflare control-plane state before the step is considered successful
+- the caller workflow should pass a deterministic `preview-scope`, such as the branch name or `pr-<number>`, for stable dedicated preview Worker naming across PR, push, and manual workflows
+
+The reporting split is also intentional:
+
+- GitHub PR feedback should use a stable PR comment because PRs are issue-backed conversations
+- GitHub branch feedback should use Deployments + deployment statuses because GitHub does not provide first-class branch comments
+- one preview workflow can publish both branch deployment feedback and the shared PR comment in the same run when a pushed branch already belongs to an open pull request
+
+Current action inputs that matter most:
+
+- `working-directory`
+- `environment`
+- `production`
+- `preview-scope`
+- `skip-setup`
+- `skip-install`
+- `verify-deployment` (defaults to `true`)
+- `cloudflare-api-token`
+- `cloudflare-account-id`
+
+When `verify-deployment` is enabled, the action fails if Devflare cannot confirm the uploaded version in Cloudflare, or for non-preview deploys, cannot confirm that a live deployment now references that version.
+
+Action outputs:
+
+- `preview-url`
+- `version-id`
+- `status`
+- `exit-code`
+- `log-excerpt`
+
+Those extra outputs are especially useful when the caller workflow uses `continue-on-error: true` on the deploy step so it can still post a failure comment or deployment status before failing the job.
+
+Minimal preview step:
+
+```yaml
+- id: deploy
+	uses: ./.github/actions/devflare-deploy
+	with:
+		working-directory: apps/documentation
+		preview-scope: ${{ github.head_ref || github.ref_name }}
+		cloudflare-api-token: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+		cloudflare-account-id: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+```
+
+This repository now keeps preview delivery in one shared workflow plus one production workflow:
+
+- [`.github/workflows/preview.yml`](../../.github/workflows/preview.yml) handles documentation + testing previews, push + PR lifecycle triggers, branch + PR targets, and cleanup flows from one place
+- [`.github/workflows/documentation-production.yml`](../../.github/workflows/documentation-production.yml) handles production deploys from the repository default branch plus GitHub deployment statuses
+- [`.github/workflow-examples/branch-preview-cleanup.example.yml`](../../.github/workflow-examples/branch-preview-cleanup.example.yml) remains as a copyable delete-triggered preview-scope cleanup template for downstream repos that want a smaller starting point
+
+The live workflows now rely on the deploy action's control-plane verification for deploy success.
+
+If you want other feedback modes in your own repo, the supported patterns are:
+
+- PR-only preview feedback: `mode: comment`
+- branch-only preview feedback: `mode: deployment`
+- combined branch deployment + PR comment feedback: either `mode: both` with `resolve-pr-from-ref: 'true'`, or separate deployment/comment steps inside one shared preview workflow when you want finer control over grouped PR comments
+
+Repository-specific runtime checks still exist where they are testing app
+behavior rather than deploy success. For example,
+[`preview.yml`](../../.github/workflows/preview.yml)
+deploys testing previews for both branch and PR scopes from one prepared job
+when a pushed branch already belongs to an open pull request, while still
+keeping its deployed-binding verification because it is validating runtime
+bindings and deployment-channel wiring rather than merely asking whether
+Cloudflare accepted the upload.
+
+For branch-scoped real preview deploys such as `apps/testing`, Devflare now
+automatically omits shared queue consumers from the deployed Wrangler config,
+and it omits cron triggers by default, when it detects the branch-preview
+strategy (`--env preview` plus branch scope, without `--preview`). That keeps
+previews from colliding on singleton Cloudflare resources while leaving the
+authoring config itself fully exhaustive for local dev, tests, and production
+deploys.
+
+If a branch-scoped preview really should keep its cron schedule, opt in with:
+
+```ts
+export default defineConfig({
+	previews: {
+		includeCrons: true
+	}
+})
+```
+
+If those previews also need preview-owned Cloudflare resources, use
+`preview.scope()` in the config authoring layer:
+
+```ts
+import { defineConfig, preview } from 'devflare/config'
+
+const pv = preview.scope()
+
+export default defineConfig({
+	bindings: {
+		kv: {
+			CACHE: pv('my-cache-kv')
+		},
+		r2: {
+			ASSETS: pv('my-assets-bucket')
+		}
+	}
+})
+```
+
+Devflare resolves those opaque markers to base names outside preview
+environments, and to preview-scoped names such as `my-cache-kv-preview` (or a
+branch-derived suffix when `DEVFLARE_PREVIEW_BRANCH`, `DEVFLARE_PREVIEW_PR`, or
+`DEVFLARE_PREVIEW_IDENTIFIER` is present) for preview resolution and deploys.
+During `devflare deploy --env preview`, Devflare also provisions missing
+preview-scoped KV, D1, R2, Queue, and Vectorize resources automatically before
+the Wrangler deploy runs. Preview-scoped Hyperdrive names are reused when the
+matching preview config already exists, and otherwise Devflare falls back to the
+base Hyperdrive config because Cloudflare does not expose stored Hyperdrive
+credentials for cloning preview configs automatically. Use
+`devflare previews cleanup --env preview --apply` during PR-close or
+branch-delete cleanup to delete the preview-owned resources again.
+Service bindings created through `ref()` still follow the referenced worker
+names, so branch-scoped worker naming remains the way to isolate preview
+service bindings.
+
+---
+
+## Repo examples
+
+- [`apps/documentation/`](../../apps/documentation/) is the executable SvelteKit example for dev, build, preview deploys, production deploys, workflow automation, and browser validation
+- [`apps/testing/`](../../apps/testing/) is the exhaustive binding-matrix example for the config contract itself, including `preview.scope()`-driven preview resource names, production overrides where bindings differ by deployment channel, and a tiny `src/fetch.ts` smoke Worker exercised by repository integration tests through `devflare/test`
 
 ---
 
@@ -562,33 +799,101 @@ It also auto-detects conventional `src/fetch.ts`, `src/queue.ts`, `src/scheduled
 - `cf.email.send()` invokes the configured email handler in `createTestContext()`-backed tests and otherwise falls back to the local email endpoint; for ingress-fidelity-sensitive flows, validate with a higher-level integration test
 - remote mode is mainly about AI and Vectorize, not “make every binding remote”
 
+### Choosing pure mocks vs Miniflare-backed `createTestContext()`
+
+`devflare/test` ships two complementary lanes. Pick by what you are validating:
+
+- **Pure mocks** (`createMockKV`, `createMockD1`, `createMockR2`, `createMockEnv`, `createMockTestContext`, `withTestContext`):
+	- Fast, in-process, no Miniflare boot
+	- Use when you are unit-testing a function that reads or writes a single binding and you control the inputs
+	- Behavior is approximate: KV is binary-safe, D1 supports `SELECT`/`INSERT` per-table fixtures, R2 stores bytes — anything beyond those primitives will diverge from production
+- **`createTestContext()` (Miniflare-backed)**:
+	- Boots a real Workers runtime locally with your `devflare.config.ts`
+	- Use when you are testing handler dispatch, multi-binding flows, queues/scheduled/email/Durable Objects, route discovery, middleware composition, or anything that needs accurate Workers semantics
+	- Slower per test, so reuse one context per test file when possible
+
+Rule of thumb: if the assertion is "given inputs X, my function returns Y", reach for the mocks. If the assertion is "the worker behaves correctly when this binding/handler/route fires", use `createTestContext()`.
+
+---
+
+## Public API surface and migration notes
+
+Devflare's bare `'devflare'` import is intentionally narrow and only exposes the documented public API. Internal helpers for the bridge, transform, and test runner are reachable from dedicated subpaths instead:
+
+- `devflare` — primary public API (`defineConfig`, `defineWorker`, `sequence`, `defineFetchHandler`, runtime context accessors, etc.)
+- `devflare/test` — `createTestContext`, `cf`, mock factories
+- `devflare/runtime` — runtime accessors (`env`, `ctx`, `event`, `locals`, helpers)
+- `devflare/cloudflare` — Cloudflare API helpers
+- `devflare/sveltekit` — SvelteKit platform glue
+- `devflare/decorators` — `@durableObject` and other decorators
+
+If you previously imported internal helpers (e.g., bridge serialization or transform helpers) from bare `'devflare'`, switch to the matching subpath. The internal modules are not considered stable public API and may change between minor versions.
+
 ---
 
 ## CLI
 
+Every top-level command supports `--help`, and nested command groups support both:
+
+- `bunx --bun devflare <command> --help`
+- `bunx --bun devflare <command> <subcommand> --help`
+- `bunx --bun devflare help <command> [subcommand]`
+
 | Command | What it does |
 |---|---|
 | `devflare init` | scaffold a project using `src/fetch.ts` and explicit `files.fetch` |
 | `devflare dev` | start the worker-only dev server, enabling Vite only when the current package has a local `vite.config.*` |
-| `devflare build` | resolve config, generate `wrangler.jsonc`, and run `vite build` only for Vite-backed packages |
-| `devflare deploy` | build and deploy with Wrangler |
+| `devflare build` | resolve config locally, preserve named bindings in generated build artifacts, and run `vite build` only for Vite-backed packages |
+| `devflare deploy` | build or reuse a prior artifact via `--build`, provision named deploy resources, and deploy with Wrangler, including same-Worker preview uploads via `--preview` |
 | `devflare types` | generate `env.d.ts` |
-| `devflare doctor` | check project configuration and generated artifacts |
+| `devflare doctor` | check project configuration plus generated artifact locations such as `.devflare/wrangler.jsonc`, `.devflare/build/wrangler.jsonc`, and `.wrangler/deploy/config.json` |
 | `devflare config` | print resolved Devflare config or resolved Wrangler JSON |
 | `devflare account` | inspect accounts, resources, usage, and limits |
+| `devflare login` | authenticate with Cloudflare via Wrangler, reusing existing auth unless `--force` is passed |
+| `devflare previews` | inspect and clean dedicated preview Workers plus preview-owned scope resources |
+| `devflare productions` | inspect live production Workers, list recent versions, roll back, or delete a live Worker script |
+| `devflare worker` | run Worker control-plane actions such as remote renaming and local config sync |
+| `devflare tokens` | create, list, and delete Devflare-managed account-owned tokens from a bootstrap token with API-token-management permission |
+| `devflare help` | print the command overview or the detailed help page for a command path |
+| `devflare version` | print the installed Devflare version |
 | `devflare ai` | show Workers AI model pricing info |
 | `devflare remote` | manage remote test mode |
 
+Command defaults:
+
+- `devflare config` defaults to `devflare config print`
+- `devflare previews` defaults to `devflare previews list`
+- `devflare productions` defaults to `devflare productions list`
+
+### Command groups
+
+| Group | Subcommands / operations |
+|---|---|
+| `account` | `info`, `workers`, `kv`, `d1`, `r2`, `vectorize`, `usage`, `limits`, `limits set`, `limits enable`, `limits disable`, `global`, `workspace` |
+| `config` | `print` |
+| `previews` | `list`, `bindings`, `cleanup` |
+| `productions` | `list`, `versions`, `rollback`, `delete` |
+| `remote` | `status`, `enable`, `disable` |
+| `worker` | `rename` |
+| `tokens` | `--list`, `--new`, `--roll`, `--delete`, `--delete-all` (flag-driven operations rather than subcommands) |
+
 Useful flags:
 
 - `build --env <name>`
+- `deploy --build <path>`
 - `deploy --env <name>`
 - `deploy --dry-run`
+- `deploy --preview <name>`
+- `login --force`
+- `previews`
+- `previews cleanup --scope <name> --apply`
 - `config print --json`
 - `config print --format wrangler`
 - `types --output <path>`
 - `doctor --config <path>`
 - `account --account <id>`
+- `tokens <bootstrap-token> --new [name]`
+- `tokens <bootstrap-token> --list`
 
 Recommended invocation style:
 
@@ -596,6 +901,8 @@ Recommended invocation style:
 bunx --bun devflare dev
 bunx --bun devflare types
 bunx --bun devflare build
+bunx --bun devflare help account limits set
+bunx --bun devflare previews cleanup --help
 ```
 
 ---
@@ -604,9 +911,15 @@ bunx --bun devflare build
 
 Treat these as generated output, not source of truth:
 
-- `.devflare/`
+- `.devflare/wrangler.jsonc`
+- `.devflare/build/wrangler.jsonc`
+- `.devflare/worker-entrypoints/main.ts`
+- `.devflare/worker-entrypoints/main.js`
+- `.devflare/vite.config.mjs`
+- `.wrangler/deploy/config.json`
 - `env.d.ts`
-- generated `wrangler.jsonc`
+
+`devflare build` keeps name-based bindings as names in these generated artifacts. `devflare deploy` is the step that resolves or provisions the concrete Cloudflare resources and rewrites the generated Wrangler config with the IDs Wrangler needs.
 
 The source of truth is still:
 
@@ -616,6 +929,29 @@ The source of truth is still:
 
 ---
 
+## Maintainer scripts
+
+These scripts live in `packages/devflare/scripts/` and are intended for Devflare maintainers, not for end-user applications.
+
+### `refresh-permission-groups`
+
+Fetches the live Cloudflare permission-group catalog and rewrites `src/cloudflare/known-permission-group-ids.generated.ts` so the symbolic Devflare permission-group names (`WORKERS_SCRIPTS_WRITE`, etc.) map to verified Cloudflare UUIDs instead of falling back to display-name matching.
+
+```sh
+# from the repo root
+CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ACCOUNT_ID=... bun run --cwd packages/devflare refresh-permission-groups
+```
+
+Flags:
+
+- `--dry-run` — print the would-be generated file to stdout instead of writing to disk; useful for CI drift checks.
+- `--keep-existing` — keep the previously-known UUID for entries missing from the API response, instead of clearing them to `null`.
+- `--output <path>` — override the destination file; defaults to `packages/devflare/src/cloudflare/known-permission-group-ids.generated.ts`.
+
+The API token must have permission to read `/accounts/:id/tokens/permission_groups`. The script never touches `tokens.ts` directly, so the public matcher API and its display-name fallback continue to work even when the generated file ships with all-`null` entries.
+
+---
+
 ## In one sentence
 
 **Devflare helps you build Cloudflare Workers with clearer structure, better local tooling, and a development workflow that stays coherent as the app grows.**

package/bin/devflare.js

@@ -1,14 +1,24 @@
 #!/usr/bin/env bun
-import { runCli } from "../dist/src/cli/index.js";
+import { existsSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 
-// Pass CLI arguments (skip node and script path)
-const args = process.argv.slice(2);
+const currentDir = dirname(fileURLToPath(import.meta.url))
+const sourceCliEntryPath = resolve(currentDir, '../src/cli/index.ts')
+const distCliEntryPath = resolve(currentDir, '../dist/cli/index.js')
+const cliEntryPath = existsSync(sourceCliEntryPath)
+	? sourceCliEntryPath
+	: distCliEntryPath
+
+const { runCli } = await import(pathToFileURL(cliEntryPath).href)
+
+const args = process.argv.slice(2)
 
 runCli(args)
 	.then((result) => {
-		process.exit(result.exitCode);
+		process.exit(result.exitCode)
 	})
 	.catch((error) => {
-		console.error("CLI error:", error);
-		process.exit(1);
-	});
+		console.error('CLI error:', error)
+		process.exit(1)
+	})