@moku-labs/worker 0.9.2 → 0.11.0

package/dist/index.mjs

@@ -1,34 +1,765 @@
-import { a as kvPlugin, c as d1Plugin, d as createCore, f as createPlugin$1, i as queuesPlugin, l as bindingsPlugin, n as deployPlugin, o as durableObjectsPlugin, p as stagePlugin, r as storagePlugin, s as defineDurableObject, t as cliPlugin, u as coreConfig } from "./cli--EPl98vG.mjs";
-import { envPlugin, logPlugin } from "@moku-labs/common";
-//#region src/env-provider.ts
+import { envPlugin, envPlugin as envPlugin$1, logPlugin, logPlugin as logPlugin$1 } from "@moku-labs/common";
+import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
+import { brandedSink, createBrandConsole, createBrandPrompts } from "@moku-labs/common/cli";
+import { access, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, watch } from "node:fs";
 /**
-* Build the default env provider: a shallow copy of `process.env` when a `process` global exists,
-* else an empty record. Safe to evaluate at Worker cold start — it never throws on a missing
-* `process` (typeof of an undeclared identifier is the string "undefined", not a ReferenceError).
+* stage core plugin — deployment-stage / dev-mode detection, flat-injected on
+* every regular plugin's context as `ctx.stage` (spec/02 §6). No state, no
+* events, no depends, no lifecycle hooks.
 *
-* @returns An {@link EnvProvider} named `worker-process-env`.
+* @see README.md
+* @example
+* ```typescript
+* // Inside any regular plugin's api factory:
+* api: (ctx) => ({
+*   errorBody: (e: Error) =>
+*     ctx.stage.isDev() ? e.stack ?? e.message : "Internal Error",
+* })
+* ```
+*/
+const stagePlugin = createCorePlugin("stage", {
+	config: { stage: "production" },
+	/**
+	* Builds the stage accessor surface from the resolved stage.
+	*
+	* @param ctx - Core plugin context (spec/02 §6 — `{ config, state }` only;
+	*   no `global`, `emit`, or `require`). `state` is unused by this plugin.
+	* @param ctx.config - The resolved plugin config containing the deployment stage.
+	* @returns The `ctx.stage` API: `isDev`, `isProduction`, `current`.
+	* @example
+	* ```typescript
+	* const api = stagePlugin.spec.api({ config: { stage: "development" }, state: {} });
+	* api.isDev(); // true
+	* ```
+	*/
+	api: ({ config }) => ({
+		/**
+		* Whether this Worker runs in the development stage.
+		*
+		* @returns True iff `stage === "development"`.
+		* @example
+		* ```typescript
+		* if (ctx.stage.isDev()) return Response.json({ stack: err.stack });
+		* ```
+		*/
+		isDev: () => config.stage === "development",
+		/**
+		* Whether this Worker runs in the production stage. Note: false in "test".
+		*
+		* @returns True iff `stage === "production"`.
+		* @example
+		* ```typescript
+		* const cc = ctx.stage.isProduction() ? "public, max-age=31536000" : "no-store";
+		* ```
+		*/
+		isProduction: () => config.stage === "production",
+		/**
+		* The raw deployment stage, as the literal union (not `string`).
+		*
+		* @returns The resolved stage.
+		* @example
+		* ```typescript
+		* ctx.log.info("startup", { stage: ctx.stage.current() });
+		* ```
+		*/
+		current: () => config.stage
+	})
+});
+const coreConfig = createCoreConfig("moku-worker", {
+	config: {
+		stage: "production",
+		name: "moku-worker",
+		compatibilityDate: ""
+	},
+	plugins: [
+		logPlugin$1,
+		envPlugin$1,
+		stagePlugin
+	]
+});
+const { createPlugin: createPlugin$1, createCore } = coreConfig;
+//#endregion
+//#region src/plugins/bindings/api.ts
+/**
+* Checks whether a value read from an env object is nullish (null or undefined).
+* Cloudflare supplies either form when a binding is absent, so both must be caught.
+*
+* @param value - The value read from the env object.
+* @returns True when the value is null or undefined.
+* @example
+* ```typescript
+* isNullish(undefined); // true
+* isNullish(0);         // false — falsy but bound
+* ```
+*/
+const isNullish = (value) => value === void 0 || value === null;
+/**
+* Resolves binding `name` off a request-supplied env object, narrowed to T.
+* Throws a `[moku-worker]`-prefixed error when the binding is nullish.
+* The env argument is read but never retained.
+*
+* @param env - The Cloudflare request env object passed to fetch/scheduled/queue.
+* @param name - The binding name to resolve.
+* @returns The binding value narrowed to T.
+* @throws {Error} With a `[moku-worker]` prefix when the binding is null or undefined.
+* @example
+* ```typescript
+* const kv = requireBinding<KVNamespace>(env, "MY_KV");
+* ```
+*/
+const requireBinding = (env, name) => {
+	const value = env[name];
+	if (isNullish(value)) throw new Error(`[moku-worker] binding "${name}" is not bound.\n  Declare it in wrangler config and pass it in via the request env.`);
+	return value;
+};
+/**
+* Returns true when `name` resolves to a non-nullish value on the request env.
+* Never throws. Use for optional-binding branching without forcing an error.
+*
+* @param env - The Cloudflare request env object passed to fetch/scheduled/queue.
+* @param name - The binding name to check.
+* @returns Whether the binding is present and non-nullish.
+* @example
+* ```typescript
+* const ok = hasBinding(env, "DB"); // false if DB is not bound
+* ```
+*/
+const hasBinding = (env, name) => !isNullish(env[name]);
+/**
+* Builds the app.bindings API surface. The factory receives a context but does
+* not use it — bindings holds no state (F4) and all resolution is argument-local.
+*
+* @param _ctx - Plugin context (unused; bindings is stateless — F4).
+* @returns BindingsApi with `require` and `has` methods.
+* @example
+* ```typescript
+* const api = createBindingsApi(ctx);
+* const kv = api.require<KVNamespace>(env, "MY_KV");
+* ```
+*/
+const createBindingsApi = (_ctx) => ({
+	require: requireBinding,
+	has: hasBinding
+});
+/**
+* Standard-tier stateless resolver — the binding-family dependency root.
+*
+* Exposes `require<T>(env, name)` and `has(env, name)` off a per-request env
+* object. Regular plugin so downstream binding plugins can declare
+* `depends: [bindingsPlugin]` and reach it via `ctx.require(bindingsPlugin)`.
+*
+* @see README.md
+*/
+const bindingsPlugin = createPlugin$1("bindings", {
+	config: { required: [] },
+	api: createBindingsApi
+});
+//#endregion
+//#region src/plugins/bindings/instances.ts
+/**
+* Resolve the default instance key from a keyed-map config: the sole entry, or the one flagged
+* `default: true`. Throws a branded error when there are no instances, or several without (or with
+* more than one) `default: true`.
+*
+* @param instances - The keyed-map config (`Record<key, instance>`).
+* @param kind - The resource kind, for the error message (e.g. "kv", "d1").
+* @returns The default instance's key.
+* @throws {Error} With a `[moku-worker]` prefix when no single default can be resolved.
 * @example
 * ```ts
-* // wired by createApp so `ctx.env.get("CLOUDFLARE_API_TOKEN")` resolves under Bun/Node
-* const provider = workerSafeProcessEnv();
-* provider.load().CLOUDFLARE_API_TOKEN;
+* defaultInstanceKey({ main: { name: "db", binding: "DB" } }, "d1"); // "main"
 * ```
 */
-const workerSafeProcessEnv = () => ({
-	name: "worker-process-env",
+const defaultInstanceKey = (instances, kind) => {
+	const keys = Object.keys(instances);
+	if (keys.length === 0) throw new Error(`[moku-worker] No ${kind} instance is configured.`);
+	if (keys.length === 1) return keys[0];
+	const flagged = keys.filter((key) => instances[key]?.default === true);
+	if (flagged.length === 1) return flagged[0];
+	throw new Error(`[moku-worker] ${kind} has ${String(keys.length)} instances — mark exactly one with \`default: true\`.`);
+};
+/**
+* Look up a resource instance by key, with a branded error listing the configured keys when absent.
+*
+* @param instances - The keyed-map config (`Record<key, instance>`).
+* @param key - The instance key to resolve (the `use(key)` selector).
+* @param kind - The resource kind, for the error message.
+* @returns The instance at `key`.
+* @throws {Error} With a `[moku-worker]` prefix when `key` is not configured.
+* @example
+* ```ts
+* pickInstance(cfg, "analytics", "d1");
+* ```
+*/
+const pickInstance = (instances, key, kind) => {
+	const instance = instances[key];
+	if (instance === void 0) {
+		const configured = Object.keys(instances).join(", ") || "(none)";
+		throw new Error(`[moku-worker] No ${kind} instance "${key}". Configured: ${configured}.`);
+	}
+	return instance;
+};
+//#endregion
+//#region src/plugins/d1/api.ts
+/**
+* Create the d1 api over a keyed map of database instances. The default-database methods and
+* `use(key)` both resolve the `D1Database` off the REQUEST-SUPPLIED env on every call — env is
+* threaded, never stored (SB4), so concurrent requests stay isolated — and the instance key is
+* resolved lazily by binding-getter so an unconfigured-but-present plugin only errors when actually
+* called.
+*
+* The return is intentionally NOT annotated `: Api`. Annotating it would
+* collapse the per-method call-site generic `<T>` on `query`/`first` to
+* `unknown`; instead the implementation forwards `<T>` to `all<T>()` /
+* `first<T>()` and `types.ts#Api` remains the public-surface source of truth.
+*
+* @param {D1Ctx} ctx - Plugin context (keyed-map config + require).
+* @returns {object} The d1 public api (query, first, run, batch, prepare, use, deployManifest).
+* @example
+* ```typescript
+* const api = createD1Api(ctx);
+* const { results } = await api.query<Product>(env, "SELECT * FROM products");
+* await api.use("analytics").run(env, "INSERT INTO events (name) VALUES (?)", "click");
+* ```
+*/
+const createD1Api = (ctx) => {
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const db = (env) => bindings.require(env, binding());
+		return {
+			/**
+			* Run a statement against this database and return all rows.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param sql - SQL with `?` placeholders.
+			* @param params - Bind parameters for the placeholders.
+			* @returns All rows in a D1 result.
+			* @example
+			* ```typescript
+			* const { results } = await api.query<Product>(env, "SELECT * FROM products");
+			* ```
+			*/
+			query: (env, sql, ...params) => db(env).prepare(sql).bind(...params).all(),
+			/**
+			* Run a statement against this database and return the first row, or null when none.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param sql - SQL with `?` placeholders.
+			* @param params - Bind parameters for the placeholders.
+			* @returns The first row, or null if none.
+			* @example
+			* ```typescript
+			* const product = await api.first<Product>(env, "SELECT * FROM products WHERE id = ?", 1);
+			* ```
+			*/
+			first: (env, sql, ...params) => db(env).prepare(sql).bind(...params).first(),
+			/**
+			* Run a write/DDL statement against this database and return its result meta.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param sql - SQL with `?` placeholders.
+			* @param params - Bind parameters for the placeholders.
+			* @returns Result carrying `.meta`.
+			* @example
+			* ```typescript
+			* await api.run(env, "INSERT INTO events (name) VALUES (?)", "click");
+			* ```
+			*/
+			run: (env, sql, ...params) => db(env).prepare(sql).bind(...params).run(),
+			/**
+			* Execute caller-built prepared statements atomically in one round-trip.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param stmts - Caller-built prepared statements.
+			* @returns One result per statement, order preserved.
+			* @example
+			* ```typescript
+			* await api.batch(env, [api.prepare(env).prepare("INSERT INTO t (id) VALUES (1)")]);
+			* ```
+			*/
+			batch: (env, stmts) => db(env).batch(stmts),
+			/**
+			* Resolve the request `D1Database` so callers can build statements for `batch()`.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @returns The request-resolved database handle.
+			* @example
+			* ```typescript
+			* const stmt = api.prepare(env).prepare("SELECT * FROM products");
+			* ```
+			*/
+			prepare: (env) => db(env)
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "d1"), "d1").binding;
+	return {
+		...surface(defaultBinding),
+		/**
+		* Select a specific D1 database instance by its config key.
+		*
+		* @param key - The instance key (as configured under `pluginConfigs.d1`).
+		* @returns The SQL surface bound to that database.
+		* @example
+		* ```typescript
+		* await api.use("analytics").run(env, "INSERT INTO events (name) VALUES (?)", "click");
+		* ```
+		*/
+		use: (key) => surface(() => pickInstance(ctx.config, key, "d1").binding),
+		/**
+		* Return this plugin's deploy metadata — one descriptor per configured database.
+		*
+		* @returns One d1 deploy descriptor per instance.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest(); // [{ kind: "d1", name: "tracker-db", binding: "DB" }]
+		* ```
+		*/
+		deployManifest: () => Object.values(ctx.config).map((instance) => {
+			const entry = {
+				kind: "d1",
+				name: instance.name,
+				binding: instance.binding
+			};
+			if (instance.migrations !== void 0) entry.migrations = instance.migrations;
+			return entry;
+		})
+	};
+};
+/**
+* Standard tier — Cloudflare D1 SQL access (thin typed wrappers, not an ORM).
+*
+* Exposes `query`, `first`, `run`, `batch`, `prepare`, and `deployManifest`.
+* Resolves the D1 binding off the per-request `env` via the bindings plugin.
+* No state, no events, no lifecycle hooks (request-scoped, spec/06 §3).
+*
+* @see README.md
+*/
+const d1Plugin = createPlugin$1("d1", {
+	depends: [bindingsPlugin],
+	config: {},
+	api: (ctx) => createD1Api(ctx)
+});
+//#endregion
+//#region src/plugins/durable-objects/api.ts
+/**
+* Builds the `app.durableObjects` API surface — `get` and `deployManifest`.
+*
+* All namespace resolution uses the per-call `env` argument: `env` is threaded, never
+* stored (SB4 / design §1a). The keyed-map config is frozen and read-only. No state
+* is held on the plugin between calls (stateless — `Record<string, never>`).
+*
+* @param ctx - Plugin context with the keyed-map `config`, `require(bindingsPlugin)`, and core APIs.
+* @returns The durableObjects API: `{ get, deployManifest }`.
+* @example
+* ```typescript
+* const api = createDoApi(ctx);
+* const stub = api.get(env, "board", "room-42");
+* const manifest = api.deployManifest(); // [{ kind: "do", binding: "BOARD", className: "BoardChannel" }]
+* ```
+*/
+const createDoApi = (ctx) => ({
 	/**
-	* Read a shallow copy of `process.env`, or `{}` when there is no `process` global (workerd
-	* without nodejs_compat). Never throws at cold start.
+	* Resolves a `DurableObjectStub` off the per-request env.
 	*
-	* @returns The current environment as a flat record (empty when `process` is absent).
+	* Selects the configured instance by `logicalName` (the config key) via `pickInstance`, resolves
+	* its `binding` off `env`, derives a deterministic id via `namespace.idFromName(idName)`, and
+	* returns the addressed stub. Synchronous — returns a stub, not a Promise. Throws (branded) when
+	* `logicalName` is not configured, or (via the bindings resolver) when the binding is not present
+	* on `env`.
+	*
+	* @param env - Per-request Cloudflare bindings object (Worker fetch/queue/scheduled env).
+	* @param logicalName - Logical DO key (selects the configured instance, e.g. `"board"`).
+	* @param idName - Stable id name passed to `idFromName` (e.g. `"room-42"`).
+	* @returns The addressed `DurableObjectStub`.
+	* @throws {Error} With `[moku-worker]` prefix when `logicalName` is not configured, or when the
+	*   binding is not bound on `env`.
 	* @example
-	* ```ts
-	* workerSafeProcessEnv().load();
+	* ```typescript
+	* const stub = app.durableObjects.get(env, "board", "room-42");
+	* const res = await stub.fetch("https://do/increment");
 	* ```
 	*/
-	load() {
-		return typeof process === "undefined" ? {} : { ...process.env };
+	get: (env, logicalName, idName) => {
+		const binding = pickInstance(ctx.config, logicalName, "durableObjects").binding;
+		const ns = ctx.require(bindingsPlugin).require(env, binding);
+		return ns.get(ns.idFromName(idName));
+	},
+	/**
+	* Returns this plugin's deploy metadata — one entry per configured instance, read by the `deploy`
+	* plugin via `ctx.require(durableObjectsPlugin)`. Never reads sibling `pluginConfigs` (F6;
+	* spec/08 §5, §7). Pure synchronous read of `ctx.config`.
+	*
+	* @returns One `{ kind: "do", binding, className }` per configured instance.
+	* @example
+	* ```typescript
+	* const manifest = app.durableObjects.deployManifest();
+	* // → [{ kind: "do", binding: "BOARD", className: "BoardChannel" }]
+	* ```
+	*/
+	deployManifest: () => Object.values(ctx.config).map((instance) => ({
+		kind: "do",
+		binding: instance.binding,
+		className: instance.className
+	}))
+});
+//#endregion
+//#region src/plugins/durable-objects/helpers.ts
+/**
+* Returns a base class the consumer extends and exports from `worker.ts`.
+*
+* PURE (spec/03 §1): takes no `ctx`, has no side effects, and may be called before
+* `createApp`. The static `doName` property captures `name` for diagnostics and
+* binding correlation. The constructor stores `(state, env)` as `this.ctx` / `this.env`,
+* satisfying the Cloudflare Durable Object constructor contract. The plugin NEVER
+* generates the final exported class — the consumer owns that class.
+*
+* @param name - Logical DO name; captured as `static doName` for diagnostics.
+* @returns A base class (constructor) the consumer extends.
+* @example
+* ```typescript
+* // src/counter.ts
+* import { defineDurableObject } from "@moku-labs/worker";
+*
+* export class Counter extends defineDurableObject("Counter") {
+*   async fetch(): Promise<Response> {
+*     const n = ((await this.ctx.storage.get<number>("n")) ?? 0) + 1;
+*     await this.ctx.storage.put("n", n);
+*     return Response.json({ n });
+*   }
+* }
+* ```
+*/
+const defineDurableObject = (name) => {
+	/**
+	* Base implementation of the Cloudflare Durable Object constructor contract.
+	* Stores `(ctx, env)` as readonly properties for consumer subclasses to use.
+	*/
+	class DurableObjectBaseImpl {
+		/**
+		* Cloudflare per-object storage/alarm context (DurableObjectState).
+		* Use `this.ctx.storage` to read/write durable storage and `this.ctx.id` to inspect the DO id.
+		*/
+		ctx;
+		/**
+		* Per-object Cloudflare bindings (per-request WorkerEnv).
+		* Mirrors the env passed at construction time; never cached across requests.
+		*/
+		env;
+		/**
+		* Logical DO name captured from `defineDurableObject(name)`.
+		* Used for diagnostics and binding correlation.
+		*/
+		static doName = name;
+		/**
+		* Constructs the base Durable Object with Cloudflare's required signature.
+		*
+		* @param ctx - Cloudflare DurableObjectState (storage, id, blockConcurrencyWhile, …).
+		* @param env - Per-request Cloudflare bindings object (WorkerEnv).
+		* @example
+		* ```typescript
+		* class Counter extends Base {
+		*   constructor(ctx: DurableObjectState, env: WorkerEnv) { super(ctx, env); }
+		* }
+		* ```
+		*/
+		constructor(ctx, env) {
+			this.ctx = ctx;
+			this.env = env;
+		}
 	}
+	return DurableObjectBaseImpl;
+};
+/**
+* Cloudflare Durable Objects plugin — Standard tier.
+*
+* Exposes `get(env, logicalName, idName)` (synchronous stub accessor, threaded env) and
+* `deployManifest()` (build-time metadata, one entry per configured instance). Depends on
+* `bindingsPlugin` for namespace resolution. The `defineDurableObject` helper is mounted under
+* `helpers` and re-exported at the top level for consumer use.
+*
+* @example
+* ```typescript
+* // Consumer endpoint handler:
+* const stub = app.durableObjects.get(env, "board", params.room!);
+* const res = await stub.fetch("https://do/increment");
+* // Consumer DO class (the EXPORTED className referenced by the "board" instance):
+* export class BoardChannel extends defineDurableObject("BoardChannel") {
+*   async fetch(): Promise<Response> { return new Response("ok"); }
+* }
+* ```
+* @see README.md
+*/
+const durableObjectsPlugin = createPlugin$1("durableObjects", {
+	depends: [bindingsPlugin],
+	config: {},
+	api: createDoApi,
+	helpers: { defineDurableObject }
+});
+//#endregion
+//#region src/plugins/kv/api.ts
+/**
+* Builds the app.kv.* api over a keyed map of namespace instances. The default-namespace methods and
+* `use(key)` both resolve the namespace off the REQUEST-SUPPLIED env on every call — env is threaded,
+* never stored (design §1a / SB4) — and the instance key is resolved lazily so an unconfigured-but-
+* present plugin only errors when actually called.
+*
+* @param ctx - The kv plugin context (keyed-map config + merged events).
+* @returns The app.kv api: get / put / delete / list / use / deployManifest.
+* @example
+* ```typescript
+* const api = createKvApi(ctx);
+* const value = await api.get(env, "key");
+* await api.use("sessions").put(env, "s:1", "data");
+* ```
+*/
+const createKvApi = (ctx) => {
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const ns = (env) => bindings.require(env, binding());
+		return {
+			/**
+			* Read a value by key from this namespace. Returns null when absent.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The key to read.
+			* @returns The stored value, or null when absent.
+			* @example
+			* ```typescript
+			* const value = await api.get(env, "feature-flags");
+			* ```
+			*/
+			get: async (env, key) => ns(env).get(key),
+			/**
+			* Write a string value under a key, optionally with KV put options.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The key to write.
+			* @param value - The string value to store.
+			* @param opts - Optional expiration / metadata.
+			* @returns Resolves once the write is acknowledged.
+			* @example
+			* ```typescript
+			* await api.put(env, "session:1", "data", { expirationTtl: 3600 });
+			* ```
+			*/
+			put: async (env, key, value, opts) => ns(env).put(key, value, opts),
+			/**
+			* Remove a key from this namespace (no-op if absent).
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The key to delete.
+			* @returns Resolves once the delete is acknowledged.
+			* @example
+			* ```typescript
+			* await api.delete(env, "session:expired");
+			* ```
+			*/
+			delete: async (env, key) => ns(env).delete(key),
+			/**
+			* List keys in this namespace, optionally filtered/paginated.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param opts - Optional prefix / cursor / limit.
+			* @returns The list result.
+			* @example
+			* ```typescript
+			* const { keys } = await api.list(env, { prefix: "session:" });
+			* ```
+			*/
+			list: async (env, opts) => ns(env).list(opts)
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "kv"), "kv").binding;
+	return {
+		...surface(defaultBinding),
+		/**
+		* Select a specific KV namespace instance by its config key.
+		*
+		* @param key - The instance key (as configured under `pluginConfigs.kv`).
+		* @returns The key/value surface bound to that namespace.
+		* @example
+		* ```typescript
+		* await api.use("sessions").get(env, "s:1");
+		* ```
+		*/
+		use: (key) => surface(() => pickInstance(ctx.config, key, "kv").binding),
+		/**
+		* Return this plugin's deploy metadata — one descriptor per configured namespace.
+		*
+		* @returns One kv deploy descriptor per instance.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest(); // [{ kind: "kv", name: "tracker-cache", binding: "CACHE" }]
+		* ```
+		*/
+		deployManifest: () => Object.values(ctx.config).map((instance) => ({
+			kind: "kv",
+			name: instance.name,
+			binding: instance.binding
+		}))
+	};
+};
+/**
+* Micro tier — thin env-first wrapper over a Cloudflare KV namespace.
+*
+* Resolves the KV namespace per request via `ctx.require(bindingsPlugin)`;
+* never stores env in state (design §1a / SB4). No lifecycle hooks —
+* request-scoped; nothing to open or close.
+*
+* @see README.md
+*/
+const kvPlugin = createPlugin$1("kv", {
+	depends: [bindingsPlugin],
+	config: {},
+	api: createKvApi
+});
+//#endregion
+//#region src/plugins/queues/api.ts
+/**
+* Resolve the instance a consumed batch belongs to. With a single instance, that instance always
+* matches. With several, match the instance whose `name` equals `batch.queue` OR whose stage-suffixed
+* form (`${name}-`) prefixes it (tolerant of the deploy stage suffix, e.g. `tracker-activity-dev`);
+* fall back to the default instance when nothing matches.
+*
+* @param config - The keyed-map queues config.
+* @param queueName - The CF queue name from `batch.queue`.
+* @returns The matched `QueueInstance` (its `onMessage` is what `consume` awaits).
+* @example
+* ```ts
+* routeInstance(cfg, "tracker-activity-dev"); // → the `activity` instance
+* ```
+*/
+const routeInstance = (config, queueName) => {
+	const keys = Object.keys(config);
+	if (keys.length === 1) return pickInstance(config, keys[0], "queues");
+	return Object.values(config).find((instance) => instance.name === queueName || queueName.startsWith(`${instance.name}-`)) ?? pickInstance(config, defaultInstanceKey(config, "queues"), "queues");
+};
+/**
+* Builds app.queues.* over a keyed map of Queue instances — read by worker.ts queue() delegation
+* (design §1d; spec/02 §7). The default-instance producer methods and `use(key)` both resolve the
+* Queue off the REQUEST-SUPPLIED env on every call (env is threaded, never stored — SB4); the
+* instance key is resolved lazily. Emits `queue:message` for observability after each consumed
+* message (F8).
+*
+* @param ctx - Plugin context (keyed-map config + require + emit).
+* @returns The queues API surface: send, sendBatch, use, consume, deployManifest.
+* @example
+* ```ts
+* const api = createQueuesApi(ctx);
+* await api.send(env, { orderId: "1" });            // default instance
+* await api.use("activity").send(env, { id: 2 });   // a named instance
+* // Worker entry (design §1d): queue: (b, e, c) => app.queues.consume(b, e, c)
+* ```
+*/
+const createQueuesApi = (ctx) => {
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const queue = (env) => bindings.require(env, binding());
+		return {
+			/**
+			* Enqueue a single message onto this instance's queue.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param body - The message body to enqueue.
+			* @returns Resolves once the message is enqueued.
+			* @example
+			* ```typescript
+			* await api.send(env, { userId: "u1" });
+			* ```
+			*/
+			send: async (env, body) => {
+				await queue(env).send(body);
+			},
+			/**
+			* Enqueue many messages onto this instance's queue; each element becomes one message.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param bodies - Array of message bodies; each becomes one message.
+			* @returns Resolves once all messages are enqueued.
+			* @example
+			* ```typescript
+			* await api.sendBatch(env, [{ id: 1 }, { id: 2 }]);
+			* ```
+			*/
+			sendBatch: async (env, bodies) => {
+				await queue(env).sendBatch(bodies.map((body) => ({ body })));
+			}
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "queues"), "queues").binding;
+	return {
+		...surface(defaultBinding),
+		/**
+		* Select a specific Queue instance by its config key.
+		*
+		* @param key - The instance key (as configured under `pluginConfigs.queues`).
+		* @returns The producer surface bound to that instance.
+		* @example
+		* ```typescript
+		* await api.use("activity").send(env, { id: 2 });
+		* ```
+		*/
+		use: (key) => surface(() => pickInstance(ctx.config, key, "queues").binding),
+		/**
+		* Consumer dispatch — the Worker's `queue()` export delegates here. Routes the batch to the
+		* matching instance's `onMessage` and emits `queue:message` per message.
+		*
+		* @param batch - The incoming message batch.
+		* @param env - The per-request Cloudflare env.
+		* @param _ctx - The execution context (waitUntil / passThroughOnException); unused.
+		* @returns Resolves after all messages settle.
+		* @example
+		* ```typescript
+		* // Worker entry (design §1d): queue: (b, e, c) => app.queues.consume(b, e, c)
+		* ```
+		*/
+		consume: async (batch, env, _ctx) => {
+			const instance = routeInstance(ctx.config, batch.queue);
+			for (const m of batch.messages) {
+				if (instance.onMessage) await instance.onMessage(m, env);
+				ctx.emit("queue:message", {
+					queue: batch.queue,
+					messageId: m.id
+				});
+			}
+		},
+		/**
+		* Return this plugin's deploy metadata — one descriptor per configured instance.
+		*
+		* @returns One queue deploy descriptor per instance.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest(); // [{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }]
+		* ```
+		*/
+		deployManifest: () => Object.values(ctx.config).map((instance) => ({
+			kind: "queue",
+			name: instance.name,
+			binding: instance.binding,
+			...instance.onMessage ? { consumer: true } : {},
+			...instance.maxBatchTimeout === void 0 ? {} : { maxBatchTimeout: instance.maxBatchTimeout }
+		}))
+	};
+};
+/**
+* Standard tier — Cloudflare Queues producer + per-instance consumer dispatch over a keyed map of
+* instances.
+*
+* `events` is declared first and via `register.map<QueueEvents>` so the plugin's own events infer
+* into the factory context; the api wiring is therefore arrow-wrapped (contextually typed).
+*
+* Emits the plugin-local `queue:message` event after each consumed message.
+*
+* @see README.md
+*/
+const queuesPlugin = createPlugin$1("queues", {
+	events: (register) => register.map({ "queue:message": "A queue message was processed" }),
+	depends: [bindingsPlugin],
+	config: {},
+	api: (ctx) => createQueuesApi(ctx)
 });
 //#endregion
 //#region src/plugins/server/api.ts
@@ -513,6 +1244,3618 @@ const serverPlugin = createPlugin$1("server", {
 	helpers: { endpoint }
 });
 //#endregion
+//#region src/plugins/storage/providers/r2.ts
+/**
+* Build a StorageProvider backed by the real R2Bucket resolved off the
+* per-request env via the bindings plugin. The bucket is resolved fresh on
+* EVERY method call — never cached, so concurrent requests stay isolated
+* (worker-api-design SB4; spec/08 §6).
+*
+* Each method is `async` so that synchronous throws from `bindings.require`
+* (e.g. missing binding) are automatically wrapped in rejected Promises —
+* callers can always use `await` / `.catch` instead of `try/catch`.
+*
+* @param bindings - The bindings plugin API (provides `require<T>`).
+* @param env - The per-request Cloudflare bindings object.
+* @param bucket - The R2 bucket binding name (e.g. "ASSETS").
+* @returns {StorageProvider} A provider that delegates to the resolved R2Bucket.
+* @example
+* ```typescript
+* const provider = resolveR2Provider(ctx.require(bindingsPlugin), env, ctx.config.bucket);
+* const body = await provider.get("my-object");
+* ```
+*/
+const resolveR2Provider = (bindings, env, bucket) => {
+	/**
+	* Resolve the R2Bucket for this request's env. Throws on missing binding.
+	*
+	* @returns {R2Bucket} The resolved R2Bucket binding.
+	* @example
+	* ```typescript
+	* const bucket = b();
+	* ```
+	*/
+	const b = () => bindings.require(env, bucket);
+	return {
+		/**
+		* Read an object from the bucket.
+		*
+		* @param key - The object key.
+		* @returns {Promise<R2ObjectBody | null>} The R2ObjectBody, or null if the key is absent.
+		* @example
+		* ```typescript
+		* const body = await provider.get("assets/logo.png");
+		* ```
+		*/
+		async get(key) {
+			return b().get(key);
+		},
+		/**
+		* Write an object to the bucket.
+		*
+		* @param key - The object key.
+		* @param value - The object contents (any R2-accepted type).
+		* @returns {Promise<R2Object>} The R2Object metadata for the written object.
+		* @example
+		* ```typescript
+		* const obj = await provider.put("assets/logo.png", buffer);
+		* ```
+		*/
+		async put(key, value) {
+			return b().put(key, value);
+		},
+		/**
+		* Remove one or more objects from the bucket. No-op when a key is absent.
+		*
+		* @param key - A single key or array of keys to remove.
+		* @returns {Promise<void>} Resolves once removed.
+		* @example
+		* ```typescript
+		* await provider.delete("assets/old.png");
+		* ```
+		*/
+		async delete(key) {
+			return b().delete(key);
+		},
+		/**
+		* List objects, optionally filtered by R2ListOptions.
+		*
+		* @param opts - Optional list options (prefix, limit, cursor, delimiter).
+		* @returns {Promise<R2Objects>} The R2Objects list result.
+		* @example
+		* ```typescript
+		* const { objects } = await provider.list({ prefix: "images/" });
+		* ```
+		*/
+		async list(opts) {
+			return b().list(opts);
+		}
+	};
+};
+//#endregion
+//#region src/plugins/storage/api.ts
+/**
+* Build the app.storage.* api over a keyed map of R2 bucket instances. The default-bucket methods and
+* `use(key)` both resolve the bucket off the REQUEST-SUPPLIED env on every call — env is threaded,
+* never stored (worker-api-design SB4; spec/08 §6,§7) — and the instance key is resolved lazily so an
+* unconfigured-but-present plugin only errors when actually called.
+*
+* The `deployManifest()` method is build-time only: it reads from `ctx.config`
+* and never touches `env` or R2.
+*
+* @param ctx - Plugin context (keyed-map config + require for bindings resolution).
+* @returns {StorageApi} The app.storage api: get / put / delete / list / use / deployManifest.
+* @example
+* ```typescript
+* const api = createStorageApi(ctx);
+* const body = await api.get(env, "my-object");
+* await api.use("uploads").put(env, "avatar.png", buffer);
+* ```
+*/
+const createStorageApi = (ctx) => {
+	const bindings = ctx.require(bindingsPlugin);
+	const surface = (binding) => {
+		const provider = (env) => resolveR2Provider(bindings, env, binding());
+		return {
+			/**
+			* Read an object from this bucket; resolves null when the key is absent.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The object key to read.
+			* @returns The object body, or null.
+			* @example
+			* ```typescript
+			* const body = await api.get(env, "assets/logo.png");
+			* ```
+			*/
+			get: (env, key) => provider(env).get(key),
+			/**
+			* Write an object to this bucket.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The object key to write.
+			* @param value - The object contents.
+			* @returns The written object metadata.
+			* @example
+			* ```typescript
+			* await api.put(env, "avatar.png", buffer);
+			* ```
+			*/
+			put: (env, key, value) => provider(env).put(key, value),
+			/**
+			* Remove an object (or keys) from this bucket. No-op when absent.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param key - The object key or keys to delete.
+			* @returns Resolves once removed.
+			* @example
+			* ```typescript
+			* await api.delete(env, "assets/old-logo.png");
+			* ```
+			*/
+			delete: (env, key) => provider(env).delete(key),
+			/**
+			* List objects in this bucket, optionally filtered by R2ListOptions.
+			*
+			* @param env - The per-request Cloudflare env.
+			* @param opts - Optional prefix / limit / cursor / delimiter.
+			* @returns The list result.
+			* @example
+			* ```typescript
+			* const { objects } = await api.list(env, { prefix: "assets/" });
+			* ```
+			*/
+			list: (env, opts) => provider(env).list(opts)
+		};
+	};
+	const defaultBinding = () => pickInstance(ctx.config, defaultInstanceKey(ctx.config, "r2"), "r2").binding;
+	return {
+		...surface(defaultBinding),
+		/**
+		* Select a specific R2 bucket instance by its config key.
+		*
+		* @param key - The instance key (as configured under `pluginConfigs.storage`).
+		* @returns The object surface bound to that bucket.
+		* @example
+		* ```typescript
+		* await api.use("uploads").put(env, "avatar.png", buffer);
+		* ```
+		*/
+		use: (key) => surface(() => pickInstance(ctx.config, key, "r2").binding),
+		/**
+		* Return this plugin's deploy metadata — one descriptor per configured bucket.
+		*
+		* @returns One r2 deploy descriptor per instance.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest(); // [{ kind: "r2", name: "tracker-files", binding: "FILES" }]
+		* ```
+		*/
+		deployManifest: () => Object.values(ctx.config).map((instance) => ({
+			kind: "r2",
+			name: instance.name,
+			binding: instance.binding,
+			...instance.upload === void 0 ? {} : { upload: instance.upload }
+		}))
+	};
+};
+/**
+* Complex tier — Cloudflare R2 object storage behind a provider adapter seam.
+*
+* Exposes `get`, `put`, `delete`, `list` (all env-first) and `deployManifest()`
+* (build-time). Depends on `bindingsPlugin` to resolve the `R2Bucket` binding
+* per request. No state, no events, no lifecycle hooks.
+*
+* @see README.md
+*/
+const storagePlugin = createPlugin$1("storage", {
+	depends: [bindingsPlugin],
+	config: {},
+	api: createStorageApi
+});
+//#endregion
+//#region src/plugins/stage/env-provider.ts
+/**
+* Build the default env provider: a shallow copy of `process.env` when a `process` global exists,
+* else an empty record. Safe to evaluate at Worker cold start — it never throws on a missing
+* `process` (typeof of an undeclared identifier is the string "undefined", not a ReferenceError).
+*
+* @returns An {@link EnvProvider} named `worker-process-env`.
+* @example
+* ```ts
+* // wired by createApp so `ctx.env.get("CLOUDFLARE_API_TOKEN")` resolves under Bun/Node
+* const provider = workerSafeProcessEnv();
+* provider.load().CLOUDFLARE_API_TOKEN;
+* ```
+*/
+const workerSafeProcessEnv = () => ({
+	name: "worker-process-env",
+	/**
+	* Read a shallow copy of `process.env`, or `{}` when there is no `process` global (workerd
+	* without nodejs_compat). Never throws at cold start.
+	*
+	* @returns The current environment as a flat record (empty when `process` is absent).
+	* @example
+	* ```ts
+	* workerSafeProcessEnv().load();
+	* ```
+	*/
+	load() {
+		return typeof process === "undefined" ? {} : { ...process.env };
+	}
+});
+//#endregion
+//#region src/plugins/deploy/auth/env-file.ts
+/**
+* @file deploy plugin — `.env.local` scaffolder (node:fs).
+*
+* Writes a ready-to-fill `.env.local` so the guided deploy can hand the user a real file to paste
+* their Cloudflare token into — NEVER clobbering an existing one (it may already hold real secrets).
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Create `<dir>/.env.local` with the given contents, unless it already exists. Existing files are
+* left untouched (they may hold real secrets) — the caller tells the user to fill that one in.
+*
+* @param dir - Directory to create the file in (usually `process.cwd()`).
+* @param content - The file contents to write when absent (e.g. `envLocalScaffold(manifest)`).
+* @returns Whether the file was created (false when it already existed) and its path.
+* @example
+* ```ts
+* const { created, path } = await ensureEnvLocal(process.cwd(), envLocalScaffold(manifest));
+* ```
+*/
+const ensureEnvLocal = async (dir, content) => {
+	const filePath = path.join(dir, ".env.local");
+	try {
+		await access(filePath);
+		return {
+			created: false,
+			path: filePath
+		};
+	} catch {
+		await writeFile(filePath, content, "utf8");
+		return {
+			created: true,
+			path: filePath
+		};
+	}
+};
+//#endregion
+//#region src/plugins/deploy/auth/permissions.ts
+/** Permission groups every deploy needs, regardless of resources. */
+const ALWAYS = [{
+	group: "Account · Workers Scripts",
+	scope: "Edit",
+	reason: "deploy",
+	inBaseTemplate: true
+}, {
+	group: "Account · Account Settings",
+	scope: "Read",
+	reason: "account",
+	inBaseTemplate: true
+}];
+/**
+* Per-resource-kind permission group. `do` needs nothing extra (Durable Objects ship with the
+* Worker script, covered by Workers Scripts · Edit). `d1`/`queue` are NOT in the stock template.
+*/
+const BY_KIND = {
+	kv: {
+		group: "Account · Workers KV Storage",
+		scope: "Edit",
+		reason: "kv",
+		inBaseTemplate: true
+	},
+	r2: {
+		group: "Account · Workers R2 Storage",
+		scope: "Edit",
+		reason: "r2",
+		inBaseTemplate: true
+	},
+	d1: {
+		group: "Account · D1",
+		scope: "Edit",
+		reason: "d1",
+		inBaseTemplate: false
+	},
+	queue: {
+		group: "Account · Queues",
+		scope: "Edit",
+		reason: "queue",
+		inBaseTemplate: false
+	},
+	do: void 0
+};
+/**
+* Derive the Cloudflare API token requirement from an app manifest: the full permission set plus
+* the subset that must be ADDED to the stock "Edit Cloudflare Workers" template.
+*
+* @param manifest - The assembled deploy manifest.
+* @returns The token requirement (base template, full required set, and groups to add).
+* @example
+* ```ts
+* const { toAdd } = requiredToken({ name: "w", compatibilityDate: "…", resources: [{ kind: "d1", binding: "DB" }] });
+* // toAdd → [{ group: "Account · D1", scope: "Edit", … }]
+* ```
+*/
+const requiredToken = (manifest) => {
+	const required = [...ALWAYS];
+	const seen = new Set(required.map((permission) => permission.group));
+	for (const resource of manifest.resources) {
+		const permission = BY_KIND[resource.kind];
+		if (permission !== void 0 && !seen.has(permission.group)) {
+			required.push(permission);
+			seen.add(permission.group);
+		}
+	}
+	return {
+		base: "Edit Cloudflare Workers",
+		required,
+		toAdd: required.filter((permission) => !permission.inBaseTemplate)
+	};
+};
+/** Permission every CI/automation redeploy needs: ship the Worker script. */
+const CI_ALWAYS = [{
+	group: "Account · Workers Scripts",
+	scope: "Edit",
+	reason: "deploy",
+	inBaseTemplate: true
+}];
+/**
+* Per-resource-kind permission for the CI/automation token. After a first LOCAL deploy has
+* provisioned everything, CI only needs to LIST existing infra (the idempotent preflight) and
+* ship — so data resources drop to `Read`; R2 stays `Edit` because asset upload writes objects.
+*/
+const CI_BY_KIND = {
+	kv: {
+		group: "Account · Workers KV Storage",
+		scope: "Read",
+		reason: "kv (preflight)",
+		inBaseTemplate: true
+	},
+	r2: {
+		group: "Account · Workers R2 Storage",
+		scope: "Edit",
+		reason: "r2 (asset upload)",
+		inBaseTemplate: true
+	},
+	d1: {
+		group: "Account · D1",
+		scope: "Read",
+		reason: "d1 (preflight)",
+		inBaseTemplate: false
+	},
+	queue: {
+		group: "Account · Queues",
+		scope: "Read",
+		reason: "queue (preflight)",
+		inBaseTemplate: false
+	},
+	do: void 0
+};
+/**
+* Derive the REDUCED Cloudflare API token for CI/automation redeploys, from the same manifest.
+* Assumes a prior LOCAL deploy already provisioned the infra, so CI never creates: data resources
+* need only `Read` (the idempotent preflight lists them), R2 keeps `Edit` for asset upload, and no
+* `Account Settings · Read` is needed because CI pins `CLOUDFLARE_ACCOUNT_ID`. Pure: no network.
+*
+* @param manifest - The assembled deploy manifest.
+* @returns The minimum permission groups for a CI redeploy token (deduped, manifest-scoped).
+* @example
+* ```ts
+* const groups = ciToken({ name: "w", compatibilityDate: "…", resources: [{ kind: "d1", binding: "DB" }] });
+* // → [Workers Scripts·Edit, D1·Read]
+* ```
+*/
+const ciToken = (manifest) => {
+	const groups = [...CI_ALWAYS];
+	const seen = new Set(groups.map((permission) => permission.group));
+	for (const resource of manifest.resources) {
+		const permission = CI_BY_KIND[resource.kind];
+		if (permission !== void 0 && !seen.has(permission.group)) {
+			groups.push(permission);
+			seen.add(permission.group);
+		}
+	}
+	return groups;
+};
+//#endregion
+//#region src/plugins/deploy/auth/render.ts
+/** Cloudflare's dashboard path for creating API tokens. */
+const TOKENS_URL$1 = "https://dash.cloudflare.com/profile/api-tokens";
+/**
+* Render one permission as a framed row. With the template flag on (the LOCAL panel) a green `✓`
+* marks a permission the stock template already includes and a pink `+ ← add to template` marks one
+* the user must add; with it off (the CI panel) every row is a neutral bullet. Scope bold, reason dim.
+*
+* @param ui - The branded console (for its palette).
+* @param permission - The permission group to render.
+* @param showTemplateFlag - Whether to mark template-vs-add (LOCAL) or use a neutral bullet (CI).
+* @returns The rendered (colorized) row, ready to drop into a box.
+* @example
+* ```ts
+* permissionRow(ui, { group: "Account · D1", scope: "Edit", reason: "d1", inBaseTemplate: false }, true);
+* ```
+*/
+const permissionRow = (ui, permission, showTemplateFlag) => {
+	const { palette } = ui;
+	const templateMark = permission.inBaseTemplate ? palette.green("✓") : palette.pink("+");
+	const mark = showTemplateFlag ? templateMark : palette.dim("•");
+	const flag = showTemplateFlag && !permission.inBaseTemplate ? palette.pink("  ← add to template") : "";
+	const reason = palette.dim(`(${permission.reason})`);
+	return `${mark} ${permission.group} : ${palette.bold(permission.scope)}  ${reason}${flag}`;
+};
+/**
+* Render the LOCAL (first deploy) token panel: the full permission set with template/add markers,
+* then the numbered create-token steps (URL cyan, template + `.env.local` bold).
+*
+* @param ui - The branded console to render through.
+* @param requirement - The LOCAL token requirement (from requiredToken()).
+* @example
+* ```ts
+* localPanel(ui, requiredToken(manifest));
+* ```
+*/
+const localPanel = (ui, requirement) => {
+	const { palette } = ui;
+	const adds = requirement.toAdd.map((permission) => `${permission.group.replace("Account · ", "")} → ${permission.scope}`).join(", ");
+	const coversAll = palette.dim(`The "${requirement.base}" template covers everything.`);
+	const addStep = requirement.toAdd.length > 0 ? `  3. ADD ${palette.pink(adds)}` : `  3. ${coversAll}`;
+	const template = palette.bold(`"${requirement.base}"`);
+	ui.box([
+		palette.bold("LOCAL — first deploy (creates your infra)"),
+		"",
+		...requirement.required.map((permission) => permissionRow(ui, permission, true)),
+		"",
+		`  1. ${palette.cyan(TOKENS_URL$1)}`,
+		`  2. Create Token → start from the ${template} template.`,
+		addStep,
+		"  4. Account Resources → Include → your account.",
+		`  5. Create it, copy it, then paste into ${palette.bold(".env.local")} (below).`
+	]);
+};
+/**
+* Render the compact CI (automation redeploy) token panel: the reduced, read-mostly permission set
+* for a later Custom Token. No template markers — CI builds a token from scratch, not the template.
+*
+* @param ui - The branded console to render through.
+* @param groups - The CI token permission groups (from ciToken()).
+* @example
+* ```ts
+* ciPanel(ui, ciToken(manifest));
+* ```
+*/
+const ciPanel = (ui, groups) => {
+	const { palette } = ui;
+	ui.box([
+		palette.bold("CI — automation redeploy (optional, later)"),
+		"",
+		...groups.map((permission) => permissionRow(ui, permission, false)),
+		"",
+		palette.dim("Create a Custom Token with exactly these (Read, not Edit, on data)."),
+		palette.dim("Store as the CLOUDFLARE_API_TOKEN secret; pin CLOUDFLARE_ACCOUNT_ID.")
+	]);
+};
+/**
+* Render the full branded `auth setup` guidance: a heading, the LOCAL token panel (what to create
+* now), and — when `opts.ci` is supplied — the compact CI panel; otherwise a one-line pointer to
+* `auth setup` for the CI token (so the guided deploy stays focused on the immediate next step).
+*
+* @param ui - The branded console to render through.
+* @param requirement - The LOCAL token requirement (from requiredToken()).
+* @param opts - Optional rendering options.
+* @param opts.ci - The CI token permission groups (from ciToken()); omit to show a pointer instead.
+* @example
+* ```ts
+* renderAuthSetup(ui, requiredToken(manifest));                     // guided deploy (LOCAL only)
+* renderAuthSetup(ui, requiredToken(manifest), { ci: ciToken(m) }); // `auth setup` (LOCAL + CI)
+* ```
+*/
+const renderAuthSetup = (ui, requirement, opts) => {
+	ui.heading("Cloudflare API token");
+	localPanel(ui, requirement);
+	if (opts?.ci) ciPanel(ui, opts.ci);
+	else ui.line(ui.palette.dim("  Need a CI token later? Run `auth setup` for the reduced set."));
+};
+//#endregion
+//#region src/plugins/deploy/auth/setup.ts
+/** Cloudflare's dashboard path for creating API tokens. */
+const TOKENS_URL = "https://dash.cloudflare.com/profile/api-tokens";
+/**
+* Render the FULL local-first token section (the deploy that provisions everything): the permission
+* table flagging template-missing rows, the template + "add these" steps, and the `.env.local` lines.
+*
+* @param requirement - The full token requirement (from requiredToken()).
+* @returns The local-first section lines.
+* @example
+* ```ts
+* const lines = localSection(requiredToken(manifest));
+* ```
+*/
+const localSection = (requirement) => {
+	const permissionRows = requirement.required.map((permission) => {
+		const flag = permission.inBaseTemplate ? "" : "   <- add to template";
+		return `  - ${permission.group} : ${permission.scope}   (${permission.reason})${flag}`;
+	});
+	const step3 = requirement.toAdd.length > 0 ? [`  3. Under Permissions, ADD: ${requirement.toAdd.map((permission) => `${permission.group.replace("Account · ", "")} -> ${permission.scope}`).join(", ")}`, "     (the template omits these; everything else is already included)"] : [`  3. The "${requirement.base}" template covers everything — no changes needed.`];
+	return [
+		"LOCAL — first deploy (provisions infra). A Cloudflare API token with these permissions:",
+		"",
+		...permissionRows,
+		"",
+		"Fastest path:",
+		`  1. ${TOKENS_URL}  ->  Create Token`,
+		`  2. Start from the "${requirement.base}" template.`,
+		...step3,
+		"  4. Account Resources -> Include -> your account.",
+		"  5. Create the token, copy it, then add it to .env.local:",
+		"       CLOUDFLARE_API_TOKEN=<paste your token>",
+		"       CLOUDFLARE_ACCOUNT_ID=<your account id>",
+		"  6. Verify it with `auth` (app.deploy.verifyAuth())."
+	];
+};
+/**
+* Render the REDUCED CI/automation token section (redeploy-only): the scoped permission table plus
+* the CI-secret + account-pin steps.
+*
+* @param groups - The CI permission groups (from ciToken()).
+* @returns The CI section lines.
+* @example
+* ```ts
+* const lines = ciSection(ciToken(manifest));
+* ```
+*/
+const ciSection = (groups) => {
+	return [
+		"CI — automation redeploy (infra already provisioned by a local deploy). A SCOPED token with:",
+		"",
+		...groups.map((permission) => `  - ${permission.group} : ${permission.scope}   (${permission.reason})`),
+		"",
+		`  1. ${TOKENS_URL}  ->  Create Token  ->  Create Custom Token.`,
+		"  2. Add exactly the permissions above (Read, not Edit, on data resources — CI never creates).",
+		"  3. Account Resources -> Include -> your account.",
+		"  4. Store it as the CLOUDFLARE_API_TOKEN secret in CI, and PIN the account so no account",
+		"     lookup (and no Account Settings -> Read) is needed:",
+		"       CLOUDFLARE_ACCOUNT_ID=<your account id>",
+		"  CI reuses the same idempotent pipeline — it lists existing infra and ships. To let CI also",
+		"  CREATE missing infra (self-heal), give it the LOCAL token above instead."
+	];
+};
+/**
+* Render the `auth setup` instructions from the app manifest: the FULL local-first token (provisions
+* everything) followed by the REDUCED CI/automation token (redeploy-only).
+*
+* @param manifest - The assembled deploy manifest.
+* @returns A multi-line instruction string covering both tokens.
+* @example
+* ```ts
+* const text = tokenInstructions(manifest);
+* ```
+*/
+const tokenInstructions = (manifest) => [
+	...localSection(requiredToken(manifest)),
+	"",
+	...ciSection(ciToken(manifest))
+].join("\n");
+/**
+* Render a ready-to-fill `.env.local` for the guided deploy: the two Cloudflare credential keys
+* (left blank to paste into) preceded by a comment block derived from the manifest — where to
+* create the token, which template to start from, exactly which permissions to add, and how to find
+* the account id. The same guidance {@link tokenInstructions} prints, but PERSISTED in the file the
+* user edits (so it survives the terminal scrolling away). Pure: no fs, no network.
+*
+* @param manifest - The assembled deploy manifest.
+* @returns The `.env.local` file contents (trailing newline included).
+* @example
+* ```ts
+* await writeFile(".env.local", envLocalScaffold(manifest));
+* ```
+*/
+const envLocalScaffold = (manifest) => {
+	const requirement = requiredToken(manifest);
+	const addStep = requirement.toAdd.length > 0 ? `#   3. Under Permissions, ADD: ${requirement.toAdd.map((permission) => `${permission.group.replace("Account · ", "")} -> ${permission.scope}`).join(", ")}` : `#   3. The "${requirement.base}" template covers everything — no changes needed.`;
+	return `${[
+		"# Cloudflare credentials for the moku deploy — fill in the two values below, then re-run deploy.",
+		"# Local-only: keep this file out of git (.env.local is gitignored by convention).",
+		"#",
+		"# Create the API token:",
+		`#   1. ${TOKENS_URL}  ->  Create Token`,
+		`#   2. Start from the "${requirement.base}" template.`,
+		addStep,
+		"#   4. Account Resources -> Include -> your account.",
+		"#   5. Create the token, copy it, and paste it after CLOUDFLARE_API_TOKEN= below.",
+		"#",
+		"# Account id: open https://dash.cloudflare.com — it is the id in the URL",
+		"# (dash.cloudflare.com/<account-id>) or in the right sidebar of any domain's overview.",
+		"",
+		"CLOUDFLARE_API_TOKEN=",
+		"CLOUDFLARE_ACCOUNT_ID="
+	].join("\n")}\n`;
+};
+//#endregion
+//#region src/plugins/deploy/infra/cloudflare.ts
+/**
+* @file deploy plugin — Cloudflare REST discovery client (infra preflight).
+*
+* Lists what already exists in a Cloudflare account so the deploy pipeline can create only the
+* missing resources (idempotent provisioning) and recover real ids for existing kv/d1 bindings.
+* Authenticated with the `.env` API token (CLOUDFLARE_API_TOKEN) — never an interactive login.
+* Uses the global `fetch`; node-only, never imported by the runtime Worker bundle.
+*/
+const API_BASE = "https://api.cloudflare.com/client/v4";
+/**
+* GET a Cloudflare API path with the bearer token and unwrap the `result`.
+*
+* @param token - The Cloudflare API token (CLOUDFLARE_API_TOKEN).
+* @param path - API path beneath the v4 base (e.g. "/accounts").
+* @returns The unwrapped `result` payload, typed by the caller.
+* @throws {Error} When the HTTP request fails or the API reports `success: false`.
+* @example
+* ```ts
+* const accounts = await cfGet<Array<{ id: string }>>(token, "/accounts");
+* ```
+*/
+const cfGet = async (token, path) => {
+	const response = await fetch(`${API_BASE}${path}`, { headers: {
+		Authorization: `Bearer ${token}`,
+		"Content-Type": "application/json"
+	} });
+	const body = await response.json();
+	if (!response.ok || !body.success) {
+		const detail = body.errors?.map((error) => error.message).join("; ") || `HTTP ${response.status}`;
+		throw new Error(`[moku-worker] Cloudflare API request failed (${path}): ${detail}`);
+	}
+	return body.result;
+};
+/**
+* Resolve the Cloudflare account (id + display name) accessible to the token. Used when the
+* consumer did not pin CLOUDFLARE_ACCOUNT_ID; the first accessible account is chosen.
+*
+* @param token - The Cloudflare API token.
+* @returns The resolved account id and name.
+* @throws {Error} When the token can access no account.
+* @example
+* ```ts
+* const { id, name } = await resolveAccount(token);
+* ```
+*/
+const resolveAccount = async (token) => {
+	const first = (await cfGet(token, "/accounts"))[0];
+	if (!first) throw new Error("[moku-worker] No Cloudflare account is accessible with this API token.");
+	return {
+		id: first.id,
+		name: first.name
+	};
+};
+/**
+* Verify a Cloudflare API token via `GET /user/tokens/verify`. Returns its status (`"active"` for
+* a usable token); throws (via cfGet) when the token is rejected outright (401/invalid).
+*
+* @param token - The Cloudflare API token to verify.
+* @returns The token status string reported by Cloudflare.
+* @throws {Error} When the verify request fails (invalid/expired token).
+* @example
+* ```ts
+* const { status } = await verifyToken(token); // status === "active"
+* ```
+*/
+const verifyToken = async (token) => {
+	return { status: (await cfGet(token, "/user/tokens/verify")).status };
+};
+/**
+* List the resources that already exist in the account, querying ONLY the kinds the app declares
+* (one request per declared kind, in parallel), indexed for the preflight diff. Scoping to the
+* declared kinds keeps the API token minimal — an app with only KV never lists (and so never needs
+* read permission on) D1, R2, or Queues.
+*
+* @param token - The Cloudflare API token.
+* @param accountId - The Cloudflare account id to scope the listings to.
+* @param kinds - The resource kinds present in the manifest (the only kinds queried).
+* @returns The existing resources, indexed by kind (un-queried kinds resolve empty).
+* @throws {Error} When any listing request fails.
+* @example
+* ```ts
+* const existing = await listExisting(token, accountId, new Set(["kv", "d1"]));
+* if (existing.kv.has("SESSIONS")) { ... }
+* ```
+*/
+const listExisting = async (token, accountId, kinds) => {
+	const base = `/accounts/${accountId}`;
+	const [kv, d1, r2, queues] = await Promise.all([
+		kinds.has("kv") ? cfGet(token, `${base}/storage/kv/namespaces`) : Promise.resolve([]),
+		kinds.has("d1") ? cfGet(token, `${base}/d1/database`) : Promise.resolve([]),
+		kinds.has("r2") ? cfGet(token, `${base}/r2/buckets`) : Promise.resolve({}),
+		kinds.has("queue") ? cfGet(token, `${base}/queues`) : Promise.resolve([])
+	]);
+	return {
+		kv: new Map(kv.map((namespace) => [namespace.title, namespace.id])),
+		d1: new Map(d1.map((database) => [database.name, database.uuid])),
+		r2: new Set((r2.buckets ?? []).map((bucket) => bucket.name)),
+		queue: new Set(queues.map((queue) => queue.queue_name))
+	};
+};
+//#endregion
+//#region src/plugins/deploy/auth/verify.ts
+/**
+* @file deploy plugin — `.env` token verification + account resolution.
+*
+* Reads CLOUDFLARE_API_TOKEN via ctx.env, verifies it is active against the Cloudflare API, and
+* resolves the account. Emits auth:verified. Throws a branded, actionable error (pointing at
+* `auth setup`) when the token is absent, invalid, or inactive — never an interactive login.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Branded hint appended to every auth failure so the user knows the next step. */
+const SETUP_HINT = "Run `auth setup` for the exact token to create.";
+/**
+* Verify the `.env` Cloudflare API token and resolve its account.
+*
+* @param ctx - The deploy plugin context (env + emit).
+* @returns The verified auth status (account + id).
+* @throws {Error} When the token is absent, invalid/expired, or not active.
+* @example
+* ```ts
+* const { account, accountId } = await verifyAuth(ctx);
+* ```
+*/
+const verifyAuth = async (ctx) => {
+	const token = ctx.env.get("CLOUDFLARE_API_TOKEN");
+	if (token === void 0 || token === "") throw new Error(`[moku-worker] CLOUDFLARE_API_TOKEN is not set. ${SETUP_HINT}`);
+	let status;
+	try {
+		({status} = await verifyToken(token));
+	} catch (error) {
+		throw new Error(`[moku-worker] Cloudflare API token is invalid or expired. ${SETUP_HINT}`, { cause: error });
+	}
+	if (status !== "active") throw new Error(`[moku-worker] Cloudflare API token is "${status}", not active. ${SETUP_HINT}`);
+	const pinnedAccountId = ctx.env.get("CLOUDFLARE_ACCOUNT_ID");
+	const account = pinnedAccountId === void 0 || pinnedAccountId === "" ? await resolveAccount(token) : {
+		id: pinnedAccountId,
+		name: pinnedAccountId
+	};
+	ctx.emit("auth:verified", {
+		account: account.name,
+		accountId: account.id,
+		scopes: []
+	});
+	return {
+		ok: true,
+		account: account.name,
+		accountId: account.id,
+		scopes: []
+	};
+};
+//#endregion
+//#region src/plugins/deploy/infra/render.ts
+/**
+* Derive a human-readable name from a resource descriptor: the Cloudflare resource `name` for the
+* provisioned kinds (kv/r2/d1/queue), or the exported `className` for a Durable Object (which has no
+* provisioned name). Used in both the provision events and the branded panels so the two agree.
+*
+* @param resource - The resource descriptor.
+* @returns A short name identifying the resource.
+* @example
+* ```ts
+* resourceName({ kind: "kv", name: "tracker-cache", binding: "CACHE" }); // "tracker-cache"
+* ```
+*/
+const resourceName = (resource) => resource.kind === "do" ? resource.className : resource.name;
+/**
+* Format a `kind name` cell, padding the kind so the names line up in a column.
+*
+* @param kind - The resource kind (kv / r2 / d1 / queue / do).
+* @param name - The resource name.
+* @returns The aligned `kind  name` cell.
+* @example
+* ```ts
+* cell("kv", "CACHE"); // "kv     CACHE"
+* ```
+*/
+const cell = (kind, name) => `${kind.padEnd(6)}${name}`;
+/**
+* Row tag for a Durable Object — it ships with the Worker (`wrangler deploy` creates the namespace),
+* so it is NEVER labelled `(exists)` (the planner never queried the account for it). Shared by the
+* plan and provision-result panels so the two always read the same.
+*/
+const SHIPS_WITH_WORKER = "(ships with worker)";
+/**
+* ANSI SGR matcher — built from `String.fromCharCode(27)` (the ESC byte) so no control character
+* appears in a regex literal (which both linters reject).
+*/
+const ANSI_SGR = new RegExp(String.raw`${String.fromCodePoint(27)}\[[0-9;]*m`, "gu");
+/**
+* Strip ANSI SGR escape sequences so a captured (colorized) error renders as plain, readable text.
+*
+* @param text - The (possibly colorized) text.
+* @returns The text with ANSI color codes removed.
+* @example
+* ```ts
+* stripAnsi(`${String.fromCharCode(27)}[31mX${String.fromCharCode(27)}[0m`); // "X"
+* ```
+*/
+const stripAnsi = (text) => text.replaceAll(ANSI_SGR, "");
+/**
+* Clean a captured (colorized, multi-line, wrapper-wrapped) provision error down to its meaningful
+* text: strip ANSI, drop the wrapper lines (the branded prefix, wrangler's log-file pointer), strip
+* each `✘ [ERROR]` marker, and join what's left. Returns the FULL message (the caller word-wraps it)
+* so the user reads the actual reason — never a truncated `…`.
+*
+* @param message - The captured error message.
+* @returns The full, plain failure reason.
+* @example
+* ```ts
+* cleanError("[moku-worker] wrangler exited…\n  ✘ [ERROR] The bucket name is invalid.");
+* // "The bucket name is invalid."
+* ```
+*/
+const cleanError = (message) => {
+	const cleaned = stripAnsi(message).split("\n").map((line) => line.trim()).filter((line) => line.length > 0).filter((line) => !/^\[moku-worker\]/u.test(line)).filter((line) => !/logs were written to/iu.test(line)).map((line) => line.replace(/^✘\s*/u, "").replace(/^\[error\]\s*/iu, "")).join(" ");
+	return cleaned.length > 0 ? cleaned : stripAnsi(message).trim();
+};
+/**
+* Word-wrap text to `width` columns (never splitting inside a word), so a long failure reason reads
+* as a tidy indented block instead of forcing the box wide or scrolling off the edge.
+*
+* @param text - The text to wrap.
+* @param width - The maximum column width per line.
+* @returns The wrapped lines.
+* @example
+* ```ts
+* wrapText("a long sentence to wrap", 10); // ["a long", "sentence", "to wrap"]
+* ```
+*/
+const wrapText = (text, width) => {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/u).filter(Boolean)) if (line.length === 0) line = word;
+	else if (line.length + 1 + word.length <= width) line += ` ${word}`;
+	else {
+		lines.push(line);
+		line = word;
+	}
+	if (line.length > 0) lines.push(line);
+	return lines;
+};
+/**
+* Render the infra preflight plan as a branded panel: a dim summary line (counts + account) then one
+* row per declared resource — a pink `+` for those to create, a dim `~ (exists)` for those already
+* present, and a dim `~ (ships with worker)` for Durable Objects (created by `wrangler deploy`, never
+* pre-provisioned). When nothing needs creating it still renders, so the user sees the full picture.
+*
+* @param ui - The branded console to render through.
+* @param plan - The infra plan (existing vs missing vs ships-with-Worker) from checkInfra()/planInfra().
+* @example
+* ```ts
+* renderPlan(ui, await planInfra(ctx, manifest));
+* ```
+*/
+const renderPlan = (ui, plan) => {
+	const { palette } = ui;
+	const counts = [`${String(plan.missing.length)} to create`, `${String(plan.exists.length)} exist`];
+	if (plan.ships.length > 0) counts.push(`${String(plan.ships.length)} with worker`);
+	const summary = palette.dim(`${counts.join(" · ")} · ${plan.account}`);
+	const createRows = plan.missing.map((resource) => `${palette.pink("+")} ${cell(resource.kind, resourceName(resource))}`);
+	const existsRows = plan.exists.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const shipsRows = plan.ships.map((resource) => `${palette.dim("~")} ${cell(resource.kind, resourceName(resource))} ${palette.dim(SHIPS_WITH_WORKER)}`);
+	ui.heading("Infra plan");
+	ui.box([
+		summary,
+		"",
+		...createRows,
+		...existsRows,
+		...shipsRows
+	]);
+};
+/**
+* Render the provision result as a branded panel — a green `✓` per created resource, a dim `~` per
+* skipped, a dim `~ (ships with worker)` per Durable Object, a red `✗` per failure, then a summary
+* line (failed count red when non-zero) — followed, when anything failed, by a detail block printing
+* each failure's FULL reason (ANSI-stripped and word-wrapped) so it is actually readable instead of
+* truncated inside the box.
+*
+* @param ui - The branded console to render through.
+* @param result - The provision result from provisionInfra()/the deploy pipeline.
+* @example
+* ```ts
+* renderProvisionResult(ui, await provisionInfra(plan));
+* ```
+*/
+const renderProvisionResult = (ui, result) => {
+	const { palette } = ui;
+	const createdRows = result.created.map((ref) => `${palette.green("✓")} ${cell(ref.resource.kind, resourceName(ref.resource))}`);
+	const skippedRows = result.skipped.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const bundledRows = result.bundled.map((resource) => `${palette.dim("~")} ${cell(resource.kind, resourceName(resource))} ${palette.dim(SHIPS_WITH_WORKER)}`);
+	const failedRows = result.failed.map((failure) => `${palette.red("✗")} ${cell(failure.resource.kind, resourceName(failure.resource))}`);
+	const failedCount = result.failed.length > 0 ? palette.red(`${String(result.failed.length)} failed`) : "0 failed";
+	const counts = [`${String(result.created.length)} created`, `${String(result.skipped.length)} exist`];
+	if (result.bundled.length > 0) counts.push(`${String(result.bundled.length)} with worker`);
+	const summary = `${counts.join(" · ")} · ${failedCount}`;
+	ui.heading("Provisioned");
+	ui.box([
+		...createdRows,
+		...skippedRows,
+		...bundledRows,
+		...failedRows,
+		"",
+		summary
+	]);
+	if (result.failed.length > 0) {
+		ui.line();
+		for (const failure of result.failed) {
+			ui.line(`  ${palette.red("✗")} ${cell(failure.resource.kind, resourceName(failure.resource))}`);
+			for (const wrapped of wrapText(cleanError(failure.error), ui.width - 4)) ui.line(palette.dim(`    ${wrapped}`));
+		}
+	}
+};
+/**
+* Format an elapsed duration compactly: sub-second as `820ms`, otherwise one-decimal seconds (`4.2s`),
+* and minutes once it crosses 60s (`1m04s`) so a long deploy stays readable.
+*
+* @param ms - The elapsed milliseconds.
+* @returns The compact duration string.
+* @example
+* ```ts
+* formatDuration(4234); // "4.2s"
+* ```
+*/
+const formatDuration = (ms) => {
+	if (ms < 1e3) return `${String(ms)}ms`;
+	const seconds = ms / 1e3;
+	if (seconds < 60) return `${seconds.toFixed(1)}s`;
+	const whole = Math.floor(seconds);
+	return `${String(Math.floor(whole / 60))}m${String(whole % 60).padStart(2, "0")}s`;
+};
+/**
+* Render the terminal deploy summary as a branded panel — the headline the user actually wants. The
+* live URL leads on its own line (pink, so it is the first thing the eye lands on), then a dim
+* key/value block: the target stage, the resource tally (with a red `failed` count when non-zero),
+* and the wall-clock time the whole deploy took. Replaces the prior single `deployed → url` line.
+*
+* @param ui - The branded console to render through.
+* @param summary - The deploy summary fields.
+* @param summary.url - The live deployed URL (the panel headline).
+* @param summary.stage - The target stage the worker deployed to.
+* @param summary.created - How many resources were created this run.
+* @param summary.exists - How many resources already existed (skipped).
+* @param summary.bundled - How many Durable Objects shipped with the Worker.
+* @param summary.failed - How many resources failed to provision.
+* @param summary.elapsedMs - The wall-clock deploy duration in milliseconds.
+* @example
+* ```ts
+* renderDeploySummary(ui, { url, stage: "production", created: 0, exists: 5, bundled: 1, failed: 0, elapsedMs: 4234 });
+* ```
+*/
+const renderDeploySummary = (ui, summary) => {
+	const { palette } = ui;
+	const parts = [`${String(summary.exists)} exist`, `${String(summary.created)} created`];
+	if (summary.bundled > 0) parts.push(`${String(summary.bundled)} with worker`);
+	const tally = parts.join(" · ");
+	const failedLabel = palette.red(`${String(summary.failed)} failed`);
+	const resources = summary.failed > 0 ? `${tally} · ${failedLabel}` : tally;
+	ui.heading("Deployed");
+	ui.box([
+		palette.pink(summary.url),
+		"",
+		`${palette.dim("stage".padEnd(10))}${summary.stage}`,
+		`${palette.dim("resources".padEnd(10))}${resources}`,
+		`${palette.dim("took".padEnd(10))}${formatDuration(summary.elapsedMs)}`
+	]);
+};
+/**
+* Render the D1 migration outcome as a branded panel — the readable replacement for wrangler's raw
+* `d1 migrations apply` TUI. One row per database: the `d1 <binding>` cell plus a pink `N applied`
+* count (or a dim `up to date` when nothing was pending), with each applied migration filename listed
+* beneath as a green `✓`. A dim scope footer (`remote` / `local`) names which database was touched.
+* The caller renders this only when at least one database actually ran migrations.
+*
+* @param ui - The branded console to render through.
+* @param outcomes - The per-database migration outcomes (one per d1 instance that declares migrations).
+* @param scope - Which database the migrations ran against: `remote` (Cloudflare) or `local` (dev).
+* @example
+* ```ts
+* renderMigrateSummary(ui, [{ binding: "DB", applied: ["0003_x.sql"], upToDate: false }], "remote");
+* ```
+*/
+const renderMigrateSummary = (ui, outcomes, scope) => {
+	const { palette } = ui;
+	const rows = [];
+	for (const outcome of outcomes) {
+		const count = outcome.applied.length;
+		const appliedLabel = palette.pink(count > 0 ? `${String(count)} applied` : "applied");
+		const status = outcome.upToDate ? palette.dim("up to date") : appliedLabel;
+		rows.push(`${cell("d1", outcome.binding)}  ${status}`);
+		for (const name of outcome.applied) rows.push(`  ${palette.green("✓")} ${palette.dim(name)}`);
+	}
+	ui.heading("Migrated");
+	ui.box([
+		...rows,
+		"",
+		palette.dim(scope)
+	]);
+};
+/**
+* Render the seed outcome as a branded panel — the readable replacement for wrangler's raw
+* `d1 execute` / `kv key delete` TUI. Leads with the loaded `file → binding` (pink file), an optional
+* dim stats line (rows written / statements, only the parts wrangler reported), then — when the seed
+* cleared cached KV keys — a `KV reset` block listing each `~ binding key` so the user sees exactly
+* what was dropped. A dim scope footer (`remote` / `local`) names which database was seeded.
+*
+* @param ui - The branded console to render through.
+* @param outcome - The seed outcome (file, target binding, best-effort counts, the KV keys reset).
+* @param scope - Which database the seed ran against: `remote` (Cloudflare) or `local` (dev).
+* @example
+* ```ts
+* renderSeedSummary(ui, { file: "db/seed.sql", binding: "DB", rowsWritten: 18, resetKv: [] }, "remote");
+* ```
+*/
+const renderSeedSummary = (ui, outcome, scope) => {
+	const { palette } = ui;
+	const lines = [`${palette.pink(outcome.file)} ${palette.dim("→")} ${outcome.binding}`];
+	const stats = [];
+	if (outcome.rowsWritten !== void 0) stats.push(`${String(outcome.rowsWritten)} rows written`);
+	if (outcome.statements !== void 0) stats.push(`${String(outcome.statements)} statements`);
+	if (stats.length > 0) lines.push(palette.dim(stats.join(" · ")));
+	if (outcome.resetKv.length > 0) {
+		lines.push("", palette.dim("KV reset"));
+		for (const entry of outcome.resetKv) lines.push(`${palette.dim("~")} ${entry.binding}  ${palette.dim(entry.key)}`);
+	}
+	ui.heading("Seeded");
+	ui.box([
+		...lines,
+		"",
+		palette.dim(scope)
+	]);
+};
+//#endregion
+//#region src/plugins/deploy/runner.ts
+/**
+* @file deploy plugin — wrangler subprocess wrapper (node:child_process).
+*
+* Spawns `wrangler` with the given args and resolves the deployed URL
+* (extracted from stdout for `wrangler deploy`), or the full stdout for other verbs.
+* This module is node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Extract the deployed URL from `wrangler deploy` stdout.
+* Wrangler prints a line like: "Published my-worker (1.23 sec)  https://..."
+* or "Deployed my-worker (1.23 sec) https://...".
+*
+* @param output - The combined stdout from wrangler deploy.
+* @returns The deployed URL, or empty string when not found.
+* @example
+* ```ts
+* extractDeployedUrl("Deployed my-worker (0.5 sec) https://my-worker.workers.dev");
+* // "https://my-worker.workers.dev"
+* ```
+*/
+const extractDeployedUrl = (output) => {
+	return /https:\/\/[^\s]+\.workers\.dev[^\s]*/u.exec(output)?.[0] ?? "";
+};
+/**
+* Spawn `wrangler` with the given args and resolve the output string.
+* For `wrangler deploy`, the resolved value is the deployed URL parsed from stdout.
+* For all other verbs (dev, kv namespace create, etc.), the resolved value is stdout.
+*
+* @param args - Wrangler CLI arguments (e.g. ["deploy", "--config", "wrangler.jsonc"]).
+* @returns Resolves with the deployed URL (deploy verb) or full stdout (other verbs).
+* @throws {Error} When wrangler exits with a non-zero code.
+* @example
+* ```ts
+* const url = await runWrangler(["deploy", "--config", "wrangler.jsonc"]);
+* await runWrangler(["kv", "namespace", "create", "CACHE"]);
+* ```
+*/
+const runWrangler = (args) => new Promise((resolve, reject) => {
+	const chunks = [];
+	const errChunks = [];
+	const child = spawn("wrangler", args, {
+		env: { ...process.env },
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	child.stdout.on("data", (chunk) => {
+		chunks.push(chunk);
+	});
+	child.stderr.on("data", (chunk) => {
+		errChunks.push(chunk);
+	});
+	child.on("error", (err) => {
+		reject(/* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${err.message}`));
+	});
+	child.on("close", (code) => {
+		const stdout = Buffer.concat(chunks).toString("utf8");
+		const stderr = Buffer.concat(errChunks).toString("utf8");
+		if (code !== 0) {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] wrangler exited with code ${String(code)}.\n  ${stderr || stdout}`));
+			return;
+		}
+		resolve(args[0] === "deploy" ? extractDeployedUrl(stdout) : stdout);
+	});
+});
+/**
+* Spawn `wrangler` with the given args, inheriting stdio so its output streams live to the user's
+* terminal (used by the generic passthrough and long-lived commands like `tail`).
+*
+* @param args - Wrangler CLI arguments (e.g. ["kv", "namespace", "list"]).
+* @returns Resolves once wrangler exits successfully.
+* @throws {Error} When wrangler cannot be spawned or exits non-zero.
+* @example
+* ```ts
+* await runWranglerInherit(["kv", "namespace", "list"]);
+* ```
+*/
+const runWranglerInherit = (args) => {
+	return new Promise((resolve, reject) => {
+		const child = spawn("wrangler", args, { stdio: "inherit" });
+		child.on("error", (error) => {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`[moku-worker] wrangler exited with code ${String(code)}.`));
+		});
+	});
+};
+//#endregion
+//#region src/plugins/deploy/seed.ts
+/**
+* @file deploy plugin — shared D1 seed helpers (resolve the target db, run a configured seed).
+*
+* Pure orchestration over an INJECTED wrangler runner, so the post-deploy REMOTE seed (api.ts) and
+* the dev-session LOCAL seed (dev/runner.ts) stay in lockstep — same file, same KV-reset semantics,
+* differing only in the `--remote` / `--local` scope. Migrations are NOT applied here: each caller
+* applies the schema first (the deploy's migration step / dev's local-migrate step), then seeds.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Parse the best-effort row/statement counts from wrangler's `d1 execute` output so the branded seed
+* panel can report them — degrading gracefully (each field simply omitted) when wrangler's format
+* differs or the runner streamed instead of captured. Wrangler prints lines like "🚣 18 commands
+* executed" and a rows-written total; both are matched loosely (case-insensitive).
+*
+* @param output - The captured stdout from `wrangler d1 execute` (empty when the runner streamed).
+* @returns The parsed counts — each field present only when found.
+* @example
+* ```ts
+* parseSeedStats("🚣 18 commands executed (30 rows written)"); // { statements: 18, rowsWritten: 30 }
+* ```
+*/
+const parseSeedStats = (output) => {
+	const rows = /(\d{1,12}) rows? written/iu.exec(output);
+	const commands = /(\d{1,12}) commands? executed/iu.exec(output) ?? /executed (\d{1,12}) commands?/iu.exec(output);
+	const result = {};
+	if (commands?.[1] !== void 0) result.statements = Number(commands[1]);
+	if (rows?.[1] !== void 0) result.rowsWritten = Number(rows[1]);
+	return result;
+};
+/**
+* Parse which migrations wrangler applied from its captured `d1 migrations apply` output, so the
+* branded migrate panel can name them instead of dumping wrangler's raw migration TUI. `upToDate` is
+* true when wrangler reported nothing pending ("No migrations to apply"); otherwise every
+* `NNNN_name.sql` filename token in the output is collected in order (de-duplicated). Degrades
+* safely — an unrecognized format yields no names, and the panel falls back to a generic "applied".
+* Lives here (not in api.ts) so both the deploy path and the dev path parse it without a cycle.
+*
+* @param output - The captured stdout from `wrangler d1 migrations apply`.
+* @returns The applied migration filenames and whether the database was already up to date.
+* @example
+* ```ts
+* parseMigrationsApplied("Applied 0003_x.sql\n0004_y.sql"); // { applied: ["0003_x.sql", "0004_y.sql"], upToDate: false }
+* ```
+*/
+const parseMigrationsApplied = (output) => {
+	if (/no migrations to apply/iu.test(output)) return {
+		applied: [],
+		upToDate: true
+	};
+	const applied = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const match of output.matchAll(/\b\d{3,}_[A-Za-z0-9_-]+\.sql\b/gu)) {
+		const name = match[0];
+		if (!seen.has(name)) {
+			seen.add(name);
+			applied.push(name);
+		}
+	}
+	return {
+		applied,
+		upToDate: false
+	};
+};
+/**
+* Resolve the single configured d1 database (or the one bound to `binding` when several exist) from
+* the d1 plugin's manifest. The shared resolver behind `seed()`, the post-deploy seed, and the dev
+* seed; throws a branded error when the choice is ambiguous (none/several, no binding) or unknown.
+*
+* @param ctx - The deploy plugin context.
+* @param binding - The d1 binding to target when more than one is configured; the sole one otherwise.
+* @returns The resolved d1 resource descriptor (its binding + optional migrations dir).
+* @throws {Error} When no single database resolves (none/several without a binding, or unknown binding).
+* @example
+* ```ts
+* const db = resolveD1(ctx, "DB");
+* ```
+*/
+const resolveD1 = (ctx, binding) => {
+	const databases = ctx.require(d1Plugin).deployManifest();
+	const matched = binding === void 0 ? databases : databases.filter((db) => db.binding === binding);
+	const target = matched.length === 1 ? matched[0] : void 0;
+	if (target === void 0) throw new Error(binding === void 0 ? `[moku-worker] seed: ${String(databases.length)} d1 databases configured — pass { binding } to choose one.` : `[moku-worker] seed: no d1 database is bound to "${binding}".`);
+	return target;
+};
+/**
+* Run a configured seed against one scope: execute the seed SQL against the d1 database, then delete
+* each configured cached KV key so the next read rebuilds it from the freshly-seeded rows. The
+* schema is assumed to exist (the caller applies migrations first), so this never migrates. The
+* wrangler runner is injected so the same orchestration serves the streamed deploy path and the
+* injectable dev path.
+*
+* @param ctx - The deploy plugin context.
+* @param run - The wrangler runner to execute each command through (a CAPTURING runner lets the
+*   returned outcome report row/statement counts; a streaming one still works, just without them).
+* @param seed - The resolved seed config (SQL file, optional binding, KV keys to reset).
+* @param scope - The wrangler scope: `--remote` (deploy) or `--local` (dev).
+* @returns The seed outcome (file, target binding, best-effort counts, and the KV keys that were reset).
+* @throws {Error} When no d1 database is configured, or the seed's binding cannot be resolved.
+* @example
+* ```ts
+* const outcome = await runConfiguredSeed(ctx, runWrangler, ctx.config.seed, "--remote");
+* ```
+*/
+const runConfiguredSeed = async (ctx, run, seed, scope) => {
+	if (!ctx.has("d1")) throw new Error("[moku-worker] seed: no d1 database is configured.");
+	const database = resolveD1(ctx, seed.binding);
+	const executed = await run([
+		"d1",
+		"execute",
+		database.binding,
+		scope,
+		"--file",
+		seed.file
+	]);
+	const resetKv = seed.resetKv ?? [];
+	for (const entry of resetKv) await run([
+		"kv",
+		"key",
+		"delete",
+		entry.key,
+		"--binding",
+		entry.binding,
+		scope
+	]);
+	return {
+		file: seed.file,
+		binding: database.binding,
+		resetKv,
+		...parseSeedStats(typeof executed === "string" ? executed : "")
+	};
+};
+//#endregion
+//#region src/plugins/deploy/dev/build.ts
+/**
+* @file deploy plugin — dev site-rebuild resolution.
+*
+* Resolves HOW to rebuild the Moku web site on change: the in-process `webBuild` hook (preferred,
+* fast, typed — passed call-time from the consumer's script or set as a config default) → a
+* `buildCommand` shell string → an auto-detected `scripts/build.ts`. When nothing is configured,
+* dev serves the worker only and says so. Subprocesses inherit the parent env by default.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Convention build script auto-detected when no webBuild/buildCommand is configured. */
+const AUTO_DETECT = "scripts/build.ts";
+/**
+* Opportunistically read a numeric `files` count off an arbitrary web build result. A real web
+* build returns its own summary shape (the worker framework cannot know it), so anything without a
+* numeric `files` field reports 0.
+*
+* @param result - The resolved value of a {@link WebBuild} hook (any shape).
+* @returns The `files` count when present and numeric, else 0.
+* @example
+* ```ts
+* fileCountOf({ files: 12 }); // 12
+* fileCountOf({ outDir: "dist", pageCount: 4 }); // 0
+* ```
+*/
+const fileCountOf = (result) => {
+	if (typeof result === "object" && result !== null && "files" in result) {
+		const { files } = result;
+		return typeof files === "number" ? files : 0;
+	}
+	return 0;
+};
+/**
+* Run a shell build command, resolving on a zero exit and rejecting otherwise.
+*
+* @param command - The shell command to run (the consumer's own configured build).
+* @returns Resolves once the command exits successfully.
+* @throws {Error} When the command fails to start or exits non-zero.
+* @example
+* ```ts
+* await runShellBuild("bun run scripts/build.ts");
+* ```
+*/
+const runShellBuild = (command) => {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, {
+			shell: true,
+			stdio: "inherit"
+		});
+		child.on("error", (error) => {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] site build failed to start.\n  ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`[moku-worker] site build exited with code ${String(code)}.`));
+		});
+	});
+};
+/**
+* Rebuild the Moku web site using the resolved strategy: the call-time `webBuild` hook (the
+* script-driven path), else the `webBuild` config default, else the `buildCommand` shell string,
+* else an auto-detected `scripts/build.ts`. A hook's result is normalized to a `{ files }` count
+* (0 when the hook reports none, and for the shell path where it is unknown).
+*
+* @param ctx - The deploy plugin context (config + emit).
+* @param webBuild - Optional call-time web build hook (takes precedence over `ctx.config.webBuild`).
+* @returns The rebuilt file count (0 for the shell path / a countless hook).
+* @throws {Error} When the resolved shell build fails.
+* @example
+* ```ts
+* const { files } = await buildSite(ctx, () => web.cli.build());
+* ```
+*/
+const buildSite = async (ctx, webBuild) => {
+	const hook = webBuild ?? ctx.config.webBuild;
+	if (hook !== void 0) return { files: fileCountOf(await hook()) };
+	const command = ctx.config.buildCommand || (existsSync(AUTO_DETECT) ? `bun run ${AUTO_DETECT}` : "");
+	if (command === "") {
+		ctx.emit("dev:error", { message: "No site build configured (pass webBuild or set buildCommand); serving worker only." });
+		return { files: 0 };
+	}
+	await runShellBuild(command);
+	return { files: 0 };
+};
+//#endregion
+//#region src/plugins/deploy/dev/watch.ts
+/**
+* @file deploy plugin — debounced filesystem watcher for dev.
+*
+* Watches the top-level directories implied by the config globs (recursive) and fires a debounced
+* change callback with the SET of paths changed in the window (so a burst of edits coalesces into
+* one rebuild that knows every changed file). Uses node:fs.watch — no extra dependency.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Derive the set of top-level directories to watch from glob patterns.
+*
+* @param globs - Watch globs (e.g. ["src/**\/*.ts", "public/**\/*"]).
+* @returns The distinct top-level directories (e.g. ["src", "public"]).
+* @example
+* ```ts
+* watchDirectories(["src/**\/*.ts", "public/**\/*"]); // ["src", "public"]
+* ```
+*/
+const watchDirectories = (globs) => {
+	const directories = /* @__PURE__ */ new Set();
+	for (const glob of globs) {
+		const globStart = glob.search(/[*?[{]/u);
+		const top = (globStart === -1 ? path.dirname(glob) : glob.slice(0, globStart)).split(/[/\\]/u).find((segment) => segment !== "") ?? ".";
+		directories.add(top);
+	}
+	return [...directories];
+};
+/**
+* Watch the directories implied by `globs` and fire `onChange` (debounced by `debounceMs`) with the
+* distinct set of paths changed within the window. Missing directories are skipped silently.
+*
+* @param globs - Watch globs.
+* @param debounceMs - Coalesce rapid changes into one callback within this window.
+* @param onChange - Called with the changed paths (snapshot of the window) after the debounce settles.
+* @returns A handle whose close() stops all watchers and cancels any pending callback.
+* @example
+* ```ts
+* const handle = watchPaths(["src/**\/*.ts"], 120, paths => rebuild(paths));
+* handle.close();
+* ```
+*/
+const watchPaths = (globs, debounceMs, onChange) => {
+	let timer;
+	const changed = /* @__PURE__ */ new Set();
+	const fire = (changedPath) => {
+		changed.add(changedPath);
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			const batch = [...changed];
+			changed.clear();
+			onChange(batch);
+		}, debounceMs);
+	};
+	const watchers = [];
+	for (const directory of watchDirectories(globs)) {
+		if (!existsSync(directory)) continue;
+		watchers.push(watch(directory, { recursive: true }, (_event, filename) => {
+			if (filename !== null) fire(path.join(directory, filename.toString()));
+		}));
+	}
+	return { close: () => {
+		if (timer !== void 0) clearTimeout(timer);
+		for (const watcher of watchers) watcher.close();
+	} };
+};
+//#endregion
+//#region src/plugins/deploy/dev/runner.ts
+/**
+* @file deploy plugin — dev watch/recompile orchestrator.
+*
+* One long-lived session: cold-build the Moku site, optionally apply local D1 migrations, spawn
+* `wrangler dev --live-reload` ONCE, then watch the site sources and rebuild on change (wrangler's
+* asset server live-reloads the browser). Build failures keep the session serving the last good
+* build. Tears down cleanly on SIGINT. Side-effecting work is injected via DevDeps so the
+* orchestration is unit-testable without real processes, watchers, or signals.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Grace period (ms) before escalating a hung `wrangler dev` shutdown from SIGINT to SIGKILL. */
+const STOP_GRACE_MS = 4e3;
+/**
+* Spawn the long-lived `wrangler dev` child (inherits the parent env; non-blocking).
+*
+* `whenExited` settles when the child exits OR fails to spawn — the `error` listener is essential:
+* a missing/unexecutable wrangler emits `error` (not `exit`), which is otherwise unhandled (crashes
+* the process) and would leave `whenExited` pending forever, hanging `stop()`. `stop()` shuts
+* wrangler down the way its own Ctrl+C does — a graceful SIGINT, then a SIGKILL escalation if it has
+* not exited within {@link STOP_GRACE_MS} — resolving only once it is gone; a spawn failure is
+* surfaced as a thrown branded error so the caller can render it. Without the wait, the
+* inherited-stdio child can keep the parent alive after the watcher closes ("stuck on stopping").
+*
+* @param args - The `wrangler dev …` arguments.
+* @returns A handle: `whenExited` (settles on exit/spawn-failure) and `stop()` (resolves once gone).
+* @example
+* ```ts
+* const child = spawnWranglerDev(["dev", "--port", "8787"]);
+* await Promise.race([untilSignal(), child.whenExited]);
+* await child.stop();
+* ```
+*/
+const spawnWranglerDev = (args) => {
+	const child = spawn("wrangler", args, { stdio: "inherit" });
+	let spawnError;
+	const whenExited = new Promise((resolve) => {
+		child.once("exit", () => {
+			resolve();
+		});
+		child.once("error", (error) => {
+			spawnError = /* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${error.message}`);
+			resolve();
+		});
+	});
+	const stop = async () => {
+		if (spawnError !== void 0) throw spawnError;
+		if (child.exitCode !== null || child.signalCode !== null || child.pid === void 0) return;
+		child.kill("SIGINT");
+		const forceKill = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+		await whenExited;
+		clearTimeout(forceKill);
+	};
+	return {
+		stop,
+		whenExited
+	};
+};
+/**
+* Resolve when the user first interrupts the dev session (SIGINT).
+*
+* @returns A promise that settles on the first SIGINT.
+* @example
+* ```ts
+* await waitForSigint();
+* ```
+*/
+const waitForSigint = () => {
+	return new Promise((resolve) => {
+		process.once("SIGINT", () => {
+			resolve();
+		});
+	});
+};
+/**
+* Wall-clock timestamp in ms (extracted so realDevDeps holds only named references).
+*
+* @returns The current time in milliseconds.
+* @example
+* ```ts
+* const t = nowMs();
+* ```
+*/
+const nowMs = () => Date.now();
+/**
+* Build the real (side-effecting) dev deps used by api.dev(). Subprocesses inherit the parent env.
+*
+* @returns The production DevDeps (real spawn / fs.watch / SIGINT / Date.now).
+* @example
+* ```ts
+* await runDev(ctx, opts, realDevDeps());
+* ```
+*/
+const realDevDeps = () => ({
+	build: buildSite,
+	runWrangler,
+	spawnDev: spawnWranglerDev,
+	watch: watchPaths,
+	untilSignal: waitForSigint,
+	now: nowMs
+});
+/**
+* The d1 bindings to migrate locally — one per configured d1 instance that declares a migrations
+* directory (empty when no d1 plugin is present, or none declares migrations).
+*
+* @param ctx - The deploy plugin context.
+* @returns The d1 binding names with migrations (e.g. `["DB"]`).
+* @example
+* ```ts
+* const bindings = d1MigrationBindings(ctx); // ["DB"]
+* ```
+*/
+const d1MigrationBindings = (ctx) => ctx.has("d1") ? ctx.require(d1Plugin).deployManifest().filter((manifest) => manifest.migrations !== void 0).map((manifest) => manifest.binding) : [];
+/**
+* One-line description of a changed-path batch for the `dev:phase rebuild` detail: the single path,
+* or the first path plus a `(+N more)` tail. Empty batches (defensive) read as "site".
+*
+* @param paths - The changed paths the watcher coalesced for this rebuild.
+* @returns The detail string for the rebuild phase event.
+* @example
+* ```ts
+* describeChanges(["src/a.ts", "src/b.css"]); // "src/a.ts (+1 more)"
+* ```
+*/
+const describeChanges = (paths) => {
+	const [first, ...rest] = paths;
+	if (first === void 0) return "site";
+	return rest.length === 0 ? first : `${first} (+${String(rest.length)} more)`;
+};
+/**
+* Rebuild the site once for a changed-path batch and announce the result. The FAST path is the
+* incremental `onChange(changedPaths)` hook (e.g. `web.cli.update`) when wired; otherwise it falls
+* back to a full `webBuild()` rebuild (via deps.build) — the prior behavior. A failed rebuild keeps
+* the session alive (it just emits dev:error and serves the last good build). Both paths share one
+* `dev:phase rebuild` → `dev:rebuilt`/`dev:error` envelope so the branded dev TUI is identical.
+*
+* @param ctx - The deploy plugin context.
+* @param deps - The injected dev deps.
+* @param changedPaths - The paths that triggered the rebuild (the watcher's debounced set).
+* @param hooks - The consumer rebuild hooks.
+* @param hooks.webBuild - Full rebuild (used when `onChange` is absent — the prior behavior).
+* @param hooks.onChange - Incremental rebuild for the changed set (the fast path when wired).
+* @returns Resolves once the rebuild attempt completes.
+* @example
+* ```ts
+* await rebuild(ctx, deps, ["src/app.tsx"], { onChange: c => web.cli.update(c) });
+* ```
+*/
+const rebuild = async (ctx, deps, changedPaths, hooks) => {
+	ctx.emit("dev:phase", {
+		phase: "rebuild",
+		detail: describeChanges(changedPaths)
+	});
+	const started = deps.now();
+	try {
+		let files;
+		if (hooks.onChange) files = fileCountOf(await hooks.onChange(changedPaths));
+		else files = (await deps.build(ctx, hooks.webBuild)).files;
+		ctx.emit("dev:rebuilt", {
+			files,
+			ms: deps.now() - started
+		});
+	} catch (error) {
+		ctx.emit("dev:error", { message: error instanceof Error ? error.message : String(error) });
+	}
+};
+/**
+* Load the configured seed into the LOCAL D1 for a `dev --seed` session: execute the SQL file, then
+* clear the configured cached KV keys so the app rebuilds them from the freshly-seeded rows. The
+* schema already exists (the migrate step above runs first), so this never migrates — the local
+* analogue of the deploy's remote seed, over the same `pluginConfigs.deploy.seed` config.
+*
+* @param ctx - The deploy plugin context.
+* @param deps - The injected dev deps (for the wrangler runner).
+* @returns Resolves once the seed file has executed and every cached KV key is cleared.
+* @throws {Error} When `--seed` is set but no seed is configured under `pluginConfigs.deploy.seed`.
+* @example
+* ```ts
+* await seedLocal(ctx, realDevDeps());
+* ```
+*/
+const seedLocal = async (ctx, deps) => {
+	const config = ctx.config.seed;
+	if (config === void 0) throw new Error("[moku-worker] dev({ seed: true }) but no seed is configured — set pluginConfigs.deploy.seed.");
+	ctx.emit("dev:phase", {
+		phase: "seed",
+		detail: config.file
+	});
+	const outcome = await runConfiguredSeed(ctx, deps.runWrangler, config, "--local");
+	renderSeedSummary(createBrandConsole(), outcome, "local");
+};
+/**
+* Run a long-lived dev session: cold build → (local d1 migrate) → (local seed) → spawn `wrangler
+* dev` → watch + rebuild on change → teardown on signal.
+*
+* @param ctx - The deploy plugin context (config + emit + require/has).
+* @param opts - Optional options.
+* @param opts.port - Local dev port (default 8787).
+* @param opts.webBuild - Cold-build hook (also the per-change rebuild when `onChange` is omitted).
+* @param opts.onChange - Incremental per-change rebuild hook (e.g. `c => web.cli.update(c)`); when
+*   set, each debounced change rebuilds only the changed paths instead of a full `webBuild()`.
+* @param opts.seed - Load the configured seed into the LOCAL D1 (+ reset its KV keys) before serving.
+* @param deps - Injected side effects (real ones from realDevDeps in production).
+* @returns Resolves when the session ends (SIGINT).
+* @example
+* ```ts
+* await runDev(ctx, { port: 8787, seed: true, webBuild: () => web.cli.build() }, realDevDeps());
+* ```
+*/
+const runDev = async (ctx, opts, deps) => {
+	const port = opts?.port ?? 8787;
+	const webBuild = opts?.webBuild;
+	const onChange = opts?.onChange;
+	const seed = opts?.seed === true;
+	ctx.emit("dev:phase", {
+		phase: "build",
+		detail: "site"
+	});
+	await deps.build(ctx, webBuild);
+	const migrationBindings = ctx.config.migrateLocal || seed ? d1MigrationBindings(ctx) : [];
+	if (migrationBindings.length > 0) {
+		ctx.emit("dev:phase", {
+			phase: "migrate",
+			detail: "d1 (local)"
+		});
+		const outcomes = [];
+		for (const binding of migrationBindings) {
+			const output = await deps.runWrangler([
+				"d1",
+				"migrations",
+				"apply",
+				binding,
+				"--local"
+			]);
+			outcomes.push({
+				binding,
+				...parseMigrationsApplied(output)
+			});
+		}
+		renderMigrateSummary(createBrandConsole(), outcomes, "local");
+	}
+	if (seed) await seedLocal(ctx, deps);
+	ctx.emit("dev:phase", {
+		phase: "serve",
+		detail: `http://localhost:${String(port)}`
+	});
+	const child = deps.spawnDev([
+		"dev",
+		"--port",
+		String(port),
+		"--config",
+		ctx.config.configFile,
+		"--live-reload"
+	]);
+	const watcher = deps.watch(ctx.config.watch, ctx.config.debounceMs, (changedPaths) => rebuild(ctx, deps, changedPaths, {
+		webBuild,
+		onChange
+	}));
+	await Promise.race([deps.untilSignal(), child.whenExited]);
+	ctx.emit("dev:phase", { phase: "stopping" });
+	watcher.close();
+	await child.stop();
+};
+//#endregion
+//#region src/plugins/deploy/infra/plan.ts
+/**
+* Decide whether a single API-provisioned resource already exists in the account, recovering its id
+* (kv/d1) when it does. Durable Objects are NOT handled here — they ship with the Worker (`wrangler
+* deploy` + the auto-derived DO migration create the namespace), are never provisioned via the API,
+* and are partitioned into the plan's `ships` bucket by {@link planInfra} before this is ever called.
+*
+* @param resource - The declared (provisionable) resource descriptor.
+* @param existing - The indexed set of resources already in the account.
+* @returns Whether it exists, plus the captured id for kv/d1.
+* @example
+* ```ts
+* checkExisting({ kind: "kv", binding: "SESSIONS" }, existing); // { exists: true, id: "ns123" }
+* ```
+*/
+const checkExisting = (resource, existing) => {
+	switch (resource.kind) {
+		case "kv": {
+			const id = existing.kv.get(resource.name);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "d1": {
+			const id = existing.d1.get(resource.name);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "r2": return { exists: existing.r2.has(resource.name) };
+		case "queue": return { exists: existing.queue.has(resource.name) };
+	}
+};
+/**
+* Run the read-only infra preflight: resolve the account, list existing resources, diff against
+* the manifest, emit `provision:plan`, and return the plan. Writes nothing.
+*
+* @param ctx - The deploy plugin context (env + emit).
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @returns The infra plan: existing (with ids) vs missing vs ships-with-Worker (Durable Objects).
+* @throws {Error} When the token is absent/invalid or a Cloudflare listing fails.
+* @example
+* ```ts
+* const plan = await planInfra(ctx, manifest);
+* ```
+*/
+const planInfra = async (ctx, manifest) => {
+	const token = ctx.env.require("CLOUDFLARE_API_TOKEN");
+	const pinnedAccountId = ctx.env.get("CLOUDFLARE_ACCOUNT_ID");
+	const account = pinnedAccountId ? {
+		id: pinnedAccountId,
+		name: pinnedAccountId
+	} : await resolveAccount(token);
+	const kinds = /* @__PURE__ */ new Set();
+	for (const resource of manifest.resources) if (resource.kind !== "do") kinds.add(resource.kind);
+	const existing = await listExisting(token, account.id, kinds);
+	const exists = [];
+	const missing = [];
+	const ships = [];
+	for (const resource of manifest.resources) {
+		if (resource.kind === "do") {
+			ships.push(resource);
+			continue;
+		}
+		const check = checkExisting(resource, existing);
+		if (check.exists) exists.push(check.id === void 0 ? { resource } : {
+			resource,
+			id: check.id
+		});
+		else missing.push(resource);
+	}
+	ctx.emit("provision:plan", {
+		exists: exists.length,
+		missing: missing.length,
+		ships: ships.length,
+		account: account.name
+	});
+	return {
+		account: account.name,
+		accountId: account.id,
+		exists,
+		missing,
+		ships
+	};
+};
+//#endregion
+//#region src/plugins/deploy/naming.ts
+/**
+* @file deploy plugin — stage-aware resource naming.
+*
+* One source of truth for turning a base Cloudflare resource name into its stage variant, so the
+* worker name, the provisioners, the infra existence diff, and the generated wrangler config all
+* agree. Production keeps the base name; every other stage gets a `-${stage}` suffix. Node-only;
+* never imported by the runtime Worker bundle.
+*/
+/**
+* Apply the deploy stage to a base Cloudflare resource name: the base name in `production`, else
+* `${base}-${stage}` (e.g. dev → `tracker-db-dev`). Env bindings + DO class names never get the
+* suffix — only provisioned resource names (and the worker name) are stage-qualified.
+*
+* @param base - The base resource name (e.g. "tracker-db").
+* @param stage - The deploy stage (e.g. "production", "development", "dev").
+* @returns The stage-qualified name.
+* @example
+* ```ts
+* stageName("tracker-db", "production"); // "tracker-db"
+* stageName("tracker-db", "dev");        // "tracker-db-dev"
+* ```
+*/
+const stageName = (base, stage) => stage === "production" ? base : `${base}-${stage}`;
+//#endregion
+//#region src/plugins/deploy/providers/d1.ts
+/**
+* @file deploy plugin — D1 provisioning adapter.
+*
+* Creates a Cloudflare D1 database via `wrangler d1 create <binding>`, captures the created
+* database id from wrangler's output (so writeWranglerConfig can write a real `database_id`
+* instead of an empty placeholder), and applies migrations when declared.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Parse the created D1 database id from `wrangler d1 create` output.
+* Wrangler prints the new binding as JSON (`"database_id": "..."`) or TOML
+* (`database_id = "..."`); the leading boundary keeps the match anchored to the field name.
+*
+* @param output - Raw stdout from the wrangler create command.
+* @returns The database id, or undefined when none is found.
+* @example
+* ```ts
+* parseD1DatabaseId('{ "database_id": "uuid-1234" }'); // "uuid-1234"
+* ```
+*/
+const parseD1DatabaseId = (output) => {
+	return /(?:^|[\s,{])"?database_id"?\s*[:=]\s*"([^"]+)"/m.exec(output)?.[1];
+};
+/**
+* Provision a D1 database via `wrangler d1 create`, capture its id, and apply migrations.
+*
+* @param manifest - The D1 resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns The captured database id when wrangler reported one, else an empty outcome.
+* @example
+* ```ts
+* const { id } = await provisionD1({ kind: "d1", binding: "DB", migrations: "./migrations" }, false);
+* ```
+*/
+const provisionD1 = async (manifest, _ci) => {
+	const id = parseD1DatabaseId(await runWrangler([
+		"d1",
+		"create",
+		manifest.name
+	]));
+	if (manifest.migrations) await runWrangler([
+		"d1",
+		"migrations",
+		"apply",
+		manifest.name,
+		"--local"
+	]);
+	return id ? { id } : {};
+};
+//#endregion
+//#region src/plugins/deploy/providers/do.ts
+/**
+* Provision Durable Object bindings. DOs are config-driven (no `wrangler do create` command
+* exists) — the actual binding entries are written by writeWranglerConfig. This function is
+* a resolved no-op for the dispatch step.
+*
+* @param _manifest - The Durable Objects resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves immediately (DOs are config-only provisioning).
+* @example
+* ```ts
+* await provisionDurableObject({ kind: "do", bindings: { counter: "COUNTER" } }, false);
+* ```
+*/
+const provisionDurableObject = async (_manifest, _ci) => {};
+//#endregion
+//#region src/plugins/deploy/providers/kv.ts
+/**
+* @file deploy plugin — KV provisioning adapter.
+*
+* Creates a Cloudflare KV namespace via `wrangler kv namespace create <binding>` and captures
+* the created namespace id from wrangler's output, so writeWranglerConfig can write a real `id`
+* (not an empty placeholder) into the generated wrangler config — otherwise the binding resolves
+* to nothing at runtime. Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Parse the created KV namespace id from `wrangler kv namespace create` output.
+* Wrangler prints the new binding as JSON (`"id": "..."`) or TOML (`id = "..."`); the leading
+* boundary (start / whitespace / `{` / `,`) keeps the match off a longer identifier such as
+* `kv_namespace_id`.
+*
+* @param output - Raw stdout from the wrangler create command.
+* @returns The namespace id, or undefined when none is found.
+* @example
+* ```ts
+* parseKvNamespaceId('{ "id": "abc123" }'); // "abc123"
+* ```
+*/
+const parseKvNamespaceId = (output) => {
+	return /(?:^|[\s,{])"?id"?\s*[:=]\s*"([^"]+)"/m.exec(output)?.[1];
+};
+/**
+* Provision a KV namespace via `wrangler kv namespace create` and capture its id.
+*
+* @param manifest - The KV resource descriptor.
+* @param _ci - Whether running non-interactively (passed through; wrangler respects env vars).
+* @returns The captured namespace id when wrangler reported one, else an empty outcome.
+* @example
+* ```ts
+* const { id } = await provisionKv({ kind: "kv", binding: "CACHE" }, false);
+* ```
+*/
+const provisionKv = async (manifest, _ci) => {
+	const id = parseKvNamespaceId(await runWrangler([
+		"kv",
+		"namespace",
+		"create",
+		manifest.name
+	]));
+	return id ? { id } : {};
+};
+//#endregion
+//#region src/plugins/deploy/providers/queues.ts
+/**
+* @file deploy plugin — Queues provisioning adapter.
+*
+* Creates one Cloudflare Queue via `wrangler queues create <name>` per queue instance.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Provision the queue via `wrangler queues create <name>`.
+*
+* @param manifest - The queue resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves once the queue is created.
+* @example
+* ```ts
+* await provisionQueue({ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }, false);
+* ```
+*/
+const provisionQueue = async (manifest, _ci) => {
+	await runWrangler([
+		"queues",
+		"create",
+		manifest.name
+	]);
+};
+//#endregion
+//#region src/plugins/deploy/providers/r2.ts
+/**
+* @file deploy plugin — R2 provisioning + asset upload adapter.
+*
+* Provides two exports:
+* - `provisionR2`: creates an R2 bucket via `wrangler r2 bucket create`.
+* - `uploadDirToR2`: walks a directory recursively and uploads each file via
+*   `wrangler r2 object put`, returning the uploaded file count.
+*
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Provision an R2 bucket via `wrangler r2 bucket create`.
+*
+* @param manifest - The R2 resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves once the bucket is created.
+* @example
+* ```ts
+* await provisionR2({ kind: "r2", name: "tracker-files", binding: "FILES" }, false);
+* ```
+*/
+const provisionR2 = async (manifest, _ci) => {
+	await runWrangler([
+		"r2",
+		"bucket",
+		"create",
+		manifest.name
+	]);
+};
+/**
+* Walk a directory recursively and return all file paths (absolute).
+*
+* @param directory - Directory path to walk.
+* @returns All file paths found under the directory.
+* @example
+* ```ts
+* const files = await walkDir("./public");
+* ```
+*/
+const walkDir = async (directory) => {
+	const entries = await readdir(directory);
+	const results = [];
+	for (const entry of entries) {
+		const fullPath = path.join(directory, entry);
+		if ((await stat(fullPath)).isDirectory()) {
+			const nested = await walkDir(fullPath);
+			results.push(...nested);
+		} else results.push(fullPath);
+	}
+	return results;
+};
+/**
+* Upload a directory to an R2 bucket and return the uploaded file count.
+* Each file is uploaded via `wrangler r2 object put <bucket>/<key> --file <path>`.
+*
+* @param bucket - The R2 bucket binding name.
+* @param directory - The directory to upload.
+* @returns The number of files uploaded.
+* @example
+* ```ts
+* const count = await uploadDirToR2("ASSETS", "./public");
+* ```
+*/
+const uploadDirToR2 = async (bucket, directory) => {
+	const files = await walkDir(directory);
+	for (const filePath of files) await runWrangler([
+		"r2",
+		"object",
+		"put",
+		`${bucket}/${path.relative(directory, filePath)}`,
+		"--file",
+		filePath
+	]);
+	return files.length;
+};
+//#endregion
+//#region src/plugins/deploy/providers/index.ts
+/**
+* Dispatch a resource descriptor to the matching provider's provisioning routine.
+*
+* @param resource - The resource descriptor to provision.
+* @param ci - Whether running non-interactively.
+* @returns The provisioning outcome — `{ id }` for kv/d1, `{}` for r2/queue/do.
+* @example
+* ```ts
+* const { id } = await provisionResource({ kind: "kv", binding: "CACHE" }, false);
+* await provisionResource({ kind: "r2", bucket: "ASSETS" }, false); // {}
+* ```
+*/
+const provisionResource = async (resource, ci) => {
+	switch (resource.kind) {
+		case "kv": return provisionKv(resource, ci);
+		case "d1": return provisionD1(resource, ci);
+		case "r2":
+			await provisionR2(resource, ci);
+			return {};
+		case "queue":
+			await provisionQueue(resource, ci);
+			return {};
+		case "do":
+			await provisionDurableObject(resource, ci);
+			return {};
+	}
+};
+//#endregion
+//#region src/plugins/deploy/tty.ts
+/**
+* @file deploy plugin — TTY detection (isolated so the guided flow is testable).
+*
+* The guided deploy only prompts on an interactive terminal; in a pipe or CI it must never block
+* on stdin. Kept in its own module so tests can mock it without stubbing `process.stdout`.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Whether stdout is an interactive TTY (so prompts are safe to show).
+*
+* @returns True when stdout is a terminal.
+* @example
+* ```ts
+* if (stdoutIsTty()) await prompts.confirm("Deploy?");
+* ```
+*/
+const stdoutIsTty = () => process.stdout.isTTY === true;
+//#endregion
+//#region src/plugins/deploy/wrangler-config.ts
+/**
+* @file deploy plugin — wrangler config generation + scaffold.
+*
+* Provides two exports:
+* - `writeWranglerConfig`: generates/updates a wrangler.jsonc file from an ExternalManifest.
+*   Non-destructive: preserves existing top-level keys not managed by deploy.
+* - `scaffoldWranglerAndCi`: creates a minimal starter wrangler config when the file does not
+*   exist yet; idempotent (leaves existing files untouched).
+*
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Strip JSONC line- and block-comments, then JSON.parse the result.
+*
+* @param source - Raw JSONC file contents.
+* @returns The parsed object.
+* @example
+* ```ts
+* const cfg = parseJsonc('{ "name": "w" } // trailing comment');
+* ```
+*/
+const parseJsonc = (source) => {
+	const stripped = source.replaceAll(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/gu, "");
+	return JSON.parse(stripped);
+};
+/**
+* Build the wrangler `kv_namespaces` array from the manifest's kv resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `id` is filled from here.
+* @returns One wrangler KV namespace entry per kv resource — real `id` when known, omitted otherwise
+*   (wrangler rejects an empty `id`, but a local-dev / freshly-generated config validates without one).
+* @example
+* ```ts
+* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }], { CACHE: "ns123" });
+* ```
+*/
+const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => {
+	const id = ids[resource.binding];
+	return id ? {
+		binding: resource.binding,
+		id
+	} : { binding: resource.binding };
+});
+/**
+* Build the wrangler `r2_buckets` array from the manifest's r2 resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns One wrangler R2 bucket entry per r2 resource.
+* @example
+* ```ts
+* const r2 = buildR2Buckets([{ kind: "r2", name: "tracker-files", binding: "FILES" }]);
+* ```
+*/
+const buildR2Buckets = (resources) => resources.filter((resource) => resource.kind === "r2").map((resource) => ({
+	binding: resource.binding,
+	bucket_name: resource.name
+}));
+/**
+* Build the wrangler `d1_databases` array from the manifest's d1 resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `database_id` is filled from here.
+* @returns One wrangler D1 database entry per d1 resource (migrations_dir set when present).
+* @example
+* ```ts
+* const d1 = buildD1Databases([{ kind: "d1", name: "tracker-db", binding: "DB" }], { DB: "uuid-1234" });
+* ```
+*/
+const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+	const databaseId = ids[resource.binding];
+	const entry = {
+		binding: resource.binding,
+		database_name: resource.name
+	};
+	if (databaseId) entry.database_id = databaseId;
+	if (resource.migrations) entry.migrations_dir = resource.migrations;
+	return entry;
+});
+/**
+* Build the wrangler `queues` section (producers + consumers) from the manifest's queue resources.
+* Every queue is a `producer`; a queue flagged `consumer: true` (it declares an `onMessage` handler)
+* is ALSO registered as a `consumer` so wrangler delivers its messages to this Worker's queue()
+* handler — both locally under `wrangler dev` and in production. Without the consumer entry the
+* handler never runs (the bug that silently drops a queue-driven activity feed). A consumer that
+* sets `maxBatchTimeout` carries it through as wrangler's `max_batch_timeout` (lower delivery latency).
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns The queues section (producers, plus consumers when any), or undefined when there are none.
+* @example
+* ```ts
+* const q = buildQueues([{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY", consumer: true, maxBatchTimeout: 1 }]);
+* ```
+*/
+const buildQueues = (resources) => {
+	const queueResources = resources.filter((resource) => resource.kind === "queue");
+	if (queueResources.length === 0) return void 0;
+	const producers = queueResources.map((resource) => ({
+		queue: resource.name,
+		binding: resource.binding
+	}));
+	const consumers = queueResources.filter((resource) => resource.consumer === true).map((resource) => {
+		const entry = { queue: resource.name };
+		if (resource.maxBatchTimeout !== void 0) entry.max_batch_timeout = resource.maxBatchTimeout;
+		return entry;
+	});
+	return consumers.length > 0 ? {
+		producers,
+		consumers
+	} : { producers };
+};
+/**
+* Build the wrangler `durable_objects` bindings section from the manifest's do resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns The durable_objects section, or undefined when there are no do resources.
+* @example
+* ```ts
+* const dobj = buildDurableObjects([{ kind: "do", binding: "COUNTER", className: "Counter" }]);
+* ```
+*/
+const buildDurableObjects = (resources) => {
+	const doResources = resources.filter((resource) => resource.kind === "do");
+	if (doResources.length === 0) return void 0;
+	return { bindings: doResources.map((resource) => ({
+		name: resource.binding,
+		class_name: resource.className
+	})) };
+};
+/**
+* Build the auto Durable Object `migrations` from the manifest's do classes. wrangler REQUIRES a
+* migration for every DO class, so this derives a single `v1` migration registering each class as
+* SQLite-backed (the modern default) — the exact section wrangler prompts for when it is missing.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns A single-entry migrations array, or undefined when there are no do resources.
+* @example
+* ```ts
+* buildMigrations([{ kind: "do", binding: "BOARD", className: "BoardChannel" }]);
+* // [{ tag: "v1", new_sqlite_classes: ["BoardChannel"] }]
+* ```
+*/
+const buildMigrations = (resources) => {
+	const classes = resources.filter((resource) => resource.kind === "do").map((resource) => resource.className);
+	return classes.length > 0 ? [{
+		tag: "v1",
+		new_sqlite_classes: classes
+	}] : void 0;
+};
+/**
+* Extract the already-captured Cloudflare ids (kv namespace `id`, d1 `database_id`) from an existing
+* parsed wrangler config, keyed by binding — so a regeneration (e.g. on `dev`) can preserve ids it
+* isn't handed. Tolerant of a malformed/hand-edited file (skips non-object / non-string entries).
+*
+* @param existing - The parsed existing wrangler config (or `{}`).
+* @returns A binding → id map (empty when the file has none).
+* @example
+* ```ts
+* extractExistingIds({ kv_namespaces: [{ binding: "CACHE", id: "ns1" }] }); // { CACHE: "ns1" }
+* ```
+*/
+const extractExistingIds = (existing) => {
+	const ids = {};
+	const collect = (list, idKey) => {
+		if (!Array.isArray(list)) return;
+		for (const raw of list) {
+			if (raw === null || typeof raw !== "object") continue;
+			const entry = raw;
+			const binding = entry.binding;
+			const id = entry[idKey];
+			if (typeof binding === "string" && typeof id === "string" && id.length > 0) ids[binding] = id;
+		}
+	};
+	collect(existing.kv_namespaces, "id");
+	collect(existing.d1_databases, "database_id");
+	return ids;
+};
+/**
+* Build the extra top-level wrangler keys from the typed deploy config: `entry` → `main`,
+* `nodeCompat` → `compatibility_flags: ["nodejs_compat"]`, `assets` → the wrangler `assets` block
+* (SPA fallback when `spa`), then the raw `wrangler` passthrough last (the escape hatch wins / adds
+* anything else). Pass the result as the `extra` argument to {@link writeWranglerConfig}.
+*
+* @param config - The deploy plugin config.
+* @returns The merged extra wrangler keys.
+* @example
+* ```ts
+* await writeWranglerConfig(file, manifest, ids, wranglerExtra(ctx.config));
+* ```
+*/
+const wranglerExtra = (config) => {
+	const extra = {};
+	if (config.entry !== void 0) extra.main = config.entry;
+	if (config.nodeCompat === true) extra.compatibility_flags = ["nodejs_compat"];
+	if (config.assets !== void 0) extra.assets = {
+		directory: config.assets.directory,
+		binding: config.assets.binding,
+		...config.assets.spa === true ? { not_found_handling: "single-page-application" } : {}
+	};
+	return {
+		...extra,
+		...config.wrangler
+	};
+};
+/**
+* Generate/update the wrangler config file from a manifest (non-destructive merge).
+*
+* Layering (last wins): existing file keys → the `extra` passthrough (the app's `wrangler` config:
+* `main`, `compatibility_flags`, `assets`, `vars`, …) → the deploy-managed keys (name,
+* compatibility_date, kv_namespaces, r2_buckets, d1_databases, queues, durable_objects). So the
+* framework always owns the resource sections, the app supplies what the manifest can't derive, and
+* any other hand-written keys survive. Durable Object `migrations` are auto-derived for every DO
+* class (the section wrangler requires) UNLESS the file/passthrough already defines `migrations`.
+*
+* @param configFile - Path to the wrangler config file.
+* @param manifest - The assembled deploy manifest.
+* @param ids - Captured Cloudflare ids keyed by binding (kv namespace id, d1 database id). Defaults
+*   to an empty map, in which case `id`/`database_id` are OMITTED (not "") so the generated config
+*   still validates for local `dev` (wrangler rejects an empty id); a deploy fills the real ids.
+* @param extra - Extra top-level wrangler keys to merge in (the app's `deploy.wrangler` config).
+* @returns Resolves once the file is written.
+* @example
+* ```ts
+* await writeWranglerConfig("wrangler.jsonc", manifest, { CACHE: "ns123" }, {
+*   main: "src/cloudflare/worker.ts",
+*   compatibility_flags: ["nodejs_compat"],
+*   assets: { directory: "dist/client", binding: "ASSETS" }
+* });
+* ```
+*/
+const writeWranglerConfig = async (configFile, manifest, ids = {}, extra = {}) => {
+	let existing = {};
+	if (existsSync(configFile)) try {
+		existing = parseJsonc(readFileSync(configFile, "utf8"));
+	} catch {
+		existing = {};
+	}
+	const effectiveIds = {
+		...extractExistingIds(existing),
+		...ids
+	};
+	const kvNamespaces = buildKvNamespaces(manifest.resources, effectiveIds);
+	const r2Buckets = buildR2Buckets(manifest.resources);
+	const d1Databases = buildD1Databases(manifest.resources, effectiveIds);
+	const queues = buildQueues(manifest.resources);
+	const durableObjects = buildDurableObjects(manifest.resources);
+	const updated = {
+		...existing,
+		...extra,
+		name: manifest.name,
+		compatibility_date: manifest.compatibilityDate
+	};
+	if (kvNamespaces.length > 0) updated.kv_namespaces = kvNamespaces;
+	if (r2Buckets.length > 0) updated.r2_buckets = r2Buckets;
+	if (d1Databases.length > 0) updated.d1_databases = d1Databases;
+	if (queues !== void 0) updated.queues = queues;
+	if (durableObjects !== void 0) updated.durable_objects = durableObjects;
+	const migrations = buildMigrations(manifest.resources);
+	if (migrations !== void 0 && updated.migrations === void 0) updated.migrations = migrations;
+	await writeFile(configFile, JSON.stringify(updated, void 0, 2));
+};
+/**
+* Scaffold a starting wrangler config and, when ci is set, CI workflow files.
+* Idempotent: an existing config file is left completely untouched.
+*
+* @param configFile - Path to the wrangler config file.
+* @param _ci - Whether to also scaffold CI workflow files.
+* @returns Resolves once scaffolding is written.
+* @example
+* ```ts
+* await scaffoldWranglerAndCi("wrangler.jsonc", true);
+* ```
+*/
+const scaffoldWranglerAndCi = async (configFile, _ci) => {
+	if (existsSync(configFile)) return;
+	const starter = {
+		name: "my-worker",
+		main: "src/worker.ts",
+		compatibility_date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+	};
+	await writeFile(configFile, JSON.stringify(starter, void 0, 2));
+};
+//#endregion
+//#region src/plugins/deploy/api.ts
+/**
+* @file deploy plugin — API factory (run, dev, init, checkInfra, provisionInfra).
+*
+* Pure ctx-taking factory. Assembles the deploy manifest from each resource plugin's own
+* deployManifest() api (never sibling pluginConfigs — design F6), runs an infra preflight
+* (check-before-create + capture real ids), generates/updates the wrangler config, uploads the
+* R2 upload dir, and runs wrangler deploy. Emits only global events: deploy:phase,
+* deploy:complete, provision:resource, provision:plan, provision:skip.
+*
+* Node-only: uses node:child_process (via runner.ts), node:fs (via wrangler-config.ts), and the
+* Cloudflare REST API (via infra/). Never called in the deployed Worker runtime.
+*/
+/**
+* Assemble the deploy manifest from each present resource plugin's OWN deployManifest() api (each
+* returns one entry PER configured instance), gated by ctx.has(name) so absent plugins are skipped —
+* never sibling pluginConfigs (F6). The single place the deploy stage is baked into names: the worker
+* name and every provisioned resource `name` are run through {@link stageName} (bindings/DO class
+* names are never suffixed), so provisioning, the existence diff, and the generated config all agree.
+*
+* @param ctx - The deploy plugin context.
+* @param stage - The deploy stage (e.g. "production", "dev") applied to every resource name.
+* @returns The assembled manifest (stage-qualified name, compatibilityDate, per-instance resources).
+* @example
+* ```ts
+* const manifest = assembleManifest(ctx, "production");
+* ```
+*/
+const assembleManifest = (ctx, stage) => {
+	const resources = [
+		ctx.has("storage") ? ctx.require(storagePlugin).deployManifest() : [],
+		ctx.has("kv") ? ctx.require(kvPlugin).deployManifest() : [],
+		ctx.has("d1") ? ctx.require(d1Plugin).deployManifest() : [],
+		ctx.has("queues") ? ctx.require(queuesPlugin).deployManifest() : [],
+		ctx.has("durableObjects") ? ctx.require(durableObjectsPlugin).deployManifest() : []
+	].flat();
+	return {
+		name: stageName(ctx.global.name, stage),
+		compatibilityDate: ctx.global.compatibilityDate,
+		resources: resources.map((resource) => "name" in resource ? {
+			...resource,
+			name: stageName(resource.name, stage)
+		} : resource)
+	};
+};
+/**
+* Create the still-missing resources one at a time: provision each, fold its captured id (kv/d1) into
+* the shared `ids` map, and announce it via provision:resource. Resilient — a single failure is
+* CAPTURED (not thrown), so one bad resource never aborts the rest. Extracted from {@link applyPlan}
+* so that orchestrator stays flat (skip existing, skip DOs, create missing).
+*
+* @param ctx - The deploy plugin context.
+* @param missing - The resources the plan flagged as not-yet-existing.
+* @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
+* @param ids - The binding → Cloudflare id map, mutated in place with each created kv/d1 id.
+* @returns The created refs and any captured per-resource failures.
+* @example
+* ```ts
+* const { created, failed } = await provisionMissing(ctx, plan.missing, false, ids);
+* ```
+*/
+const provisionMissing = async (ctx, missing, ci, ids) => {
+	const created = [];
+	const failed = [];
+	for (const resource of missing) try {
+		const { id } = await provisionResource(resource, ci);
+		if (id !== void 0 && (resource.kind === "kv" || resource.kind === "d1")) ids[resource.binding] = id;
+		created.push(id === void 0 ? { resource } : {
+			resource,
+			id
+		});
+		ctx.emit("provision:resource", {
+			kind: resource.kind,
+			name: resourceName(resource)
+		});
+	} catch (error) {
+		failed.push({
+			resource,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
+	return {
+		created,
+		failed
+	};
+};
+/**
+* Act on an infra plan: skip the resources that already exist (reusing their ids), skip the Durable
+* Objects that ship with the Worker, create the missing ones (capturing each new id), and announce
+* each via provision:skip / :resource. Resilient — a single resource that fails to create is CAPTURED
+* in `failed` (not thrown), so one bad resource (e.g. an invalid bucket name) never aborts the whole
+* run and the caller can report a clear result.
+*
+* @param ctx - The deploy plugin context.
+* @param plan - The infra plan from planInfra (existing vs missing vs ships-with-Worker).
+* @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
+* @returns The provisioning result: created, skipped, bundled, failed, and the merged binding → id map.
+* @example
+* ```ts
+* const { created, failed } = await applyPlan(ctx, plan, false);
+* ```
+*/
+const applyPlan = async (ctx, plan, ci) => {
+	const ids = {};
+	for (const ref of plan.exists) {
+		if (ref.id !== void 0 && (ref.resource.kind === "kv" || ref.resource.kind === "d1")) ids[ref.resource.binding] = ref.id;
+		ctx.emit("provision:skip", {
+			kind: ref.resource.kind,
+			name: resourceName(ref.resource)
+		});
+	}
+	for (const resource of plan.ships) ctx.emit("provision:skip", {
+		kind: resource.kind,
+		name: resourceName(resource)
+	});
+	const { created, failed } = await provisionMissing(ctx, plan.missing, ci, ids);
+	return {
+		created,
+		skipped: plan.exists,
+		bundled: plan.ships,
+		failed,
+		ids
+	};
+};
+/**
+* Sentinel a guided helper resolves to when the user declined recovery — a clean abort the caller
+* turns into a `deploy:phase aborted` + early return, never a thrown (and re-rendered) error.
+*/
+const ABORTED = Symbol("deploy:aborted");
+/** Retry guidance shown beneath each step's failure, before the "Retry?" prompt. */
+const HINTS = {
+	build: "Web build failed — fix the error above, then retry.",
+	provision: "Verify your token's account scopes and Cloudflare's status, then retry.",
+	upload: "R2 upload failed — check the bucket and your token's R2 scope, then retry.",
+	deploy: "wrangler deploy failed — review the output above, then retry."
+};
+/**
+* Emit the terminal `aborted` phase AND build the matching {@link DeployReport} — the single exit
+* every guided gate/retry funnels through when the user stops the deploy (or auth was never set up).
+* Centralizing it keeps every abort path emitting one consistent line and returning the same shaped
+* report: `status: "aborted"`, both post-steps `"skipped"`, no errors — so a calling script sees a
+* clean stop, never a half-filled success, and the remote-DB migration/seed are guaranteed unrun.
+*
+* @param ctx - The deploy plugin context.
+* @param stage - The resolved deploy stage (echoed into the report).
+* @param startedAt - The run's start timestamp, for the elapsed field.
+* @returns The aborted deploy report.
+* @example
+* ```ts
+* if (declined) return aborted(ctx, stage, startedAt);
+* ```
+*/
+const aborted = (ctx, stage, startedAt) => {
+	ctx.emit("deploy:phase", { phase: "aborted" });
+	return {
+		ok: false,
+		status: "aborted",
+		stage,
+		migration: "skipped",
+		seed: "skipped",
+		elapsedMs: Date.now() - startedAt,
+		errors: []
+	};
+};
+/**
+* The full guided token setup shown after an auth failure on a TTY. Offers to walk the user through
+* it, and when accepted: prints WHERE to create the Cloudflare token (dashboard URL, which template,
+* the exact permissions to add) AND scaffolds a ready-to-fill `.env.local` — the same guidance baked
+* in as comments — for the user to paste the token + account id into (never clobbering an existing
+* file). Always ends pointing at the re-run.
+*
+* @param ctx - The deploy plugin context.
+* @param ui - The branded console to render the guidance through.
+* @param confirm - The yes/no prompt.
+* @returns Resolves once the guidance (and optional `.env.local` scaffold) has been rendered.
+* @example
+* ```ts
+* await guidedTokenSetup(ctx, createBrandConsole(), confirm);
+* ```
+*/
+const guidedTokenSetup = async (ctx, ui, confirm) => {
+	if (!await confirm("Set up Cloudflare credentials now? (guided)")) {
+		ui.info("Set CLOUDFLARE_API_TOKEN in .env.local, then run `deploy` again.");
+		return;
+	}
+	const manifest = assembleManifest(ctx, ctx.global.stage);
+	renderAuthSetup(ui, requiredToken(manifest));
+	const { created, path } = await ensureEnvLocal(process.cwd(), envLocalScaffold(manifest));
+	ui.info(created ? `Created ${path} — paste your token + account id there, then run \`deploy\` again.` : `${path} already exists — fill in CLOUDFLARE_API_TOKEN there, then run \`deploy\` again.`);
+};
+/**
+* Verify the `.env` token, turning a missing/invalid token into a guided recovery on a TTY: surface
+* WHY auth failed, then walk the user through {@link guidedTokenSetup} (where to create the token +
+* scaffold a `.env.local`). The env is snapshotted at app start, so a freshly-pasted token only
+* takes effect on a NEW run. In CI/pipes the branded error re-throws (fail-fast).
+*
+* @param ctx - The deploy plugin context.
+* @param deps - Interactivity + the confirm prompt.
+* @returns True when the token verified; false when the user must set it up and re-run.
+* @throws {Error} Re-throws the branded auth error in CI / non-interactive runs.
+* @example
+* ```ts
+* if (!(await guidedAuth(ctx, { interactive, confirm }))) return;
+* ```
+*/
+const guidedAuth = async (ctx, deps) => {
+	try {
+		await verifyAuth(ctx);
+		return true;
+	} catch (error) {
+		if (!deps.interactive) throw error;
+		const ui = createBrandConsole();
+		ui.error(error instanceof Error ? error.message : String(error));
+		await guidedTokenSetup(ctx, ui, deps.confirm);
+		return false;
+	}
+};
+/**
+* Run one external pipeline step with interactive recovery: on failure, render the branded error +
+* an actionable hint, then offer to retry — looping until the step succeeds or the user declines.
+* A decline resolves to {@link ABORTED} (a clean abort the caller surfaces), so the error is shown
+* once, not re-rendered downstream. In CI/pipes the first failure re-throws (fail-fast). The step
+* MUST be safe to re-run (idempotent).
+*
+* @param step - The async step to run (e.g. the web build, the R2 upload, `wrangler deploy`).
+* @param hint - One-line guidance shown beneath the error before the retry prompt.
+* @param deps - Interactivity + the confirm prompt.
+* @returns The step's resolved value once it succeeds, or {@link ABORTED} when a retry is declined.
+* @throws {Error} Re-throws the step's error in CI / non-interactive runs.
+* @example
+* ```ts
+* const url = await guidedStep(() => runWrangler(args), "wrangler deploy failed …", deps);
+* if (url === ABORTED) return;
+* ```
+*/
+const guidedStep = async (step, hint, deps) => {
+	for (;;) try {
+		return await step();
+	} catch (error) {
+		if (!deps.interactive) throw error;
+		const ui = createBrandConsole();
+		ui.error(error instanceof Error ? error.message : String(error));
+		ui.info(hint);
+		if (!await deps.confirm("Retry?")) return ABORTED;
+	}
+};
+/**
+* Run the read-only infra preflight with interactive recovery: a network/scope failure fails fast in
+* CI, or (on a TTY) renders the error + hint and offers a retry. Resolves the plan, or {@link ABORTED}
+* when the user declines the retry.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param deps - Interactivity + the confirm prompt.
+* @returns The infra plan, or {@link ABORTED} when a preflight retry is declined.
+* @throws {Error} Re-throws the preflight error in CI / non-interactive runs.
+* @example
+* ```ts
+* const plan = await guidedPlan(ctx, manifest, deps);
+* if (plan === ABORTED) return;
+* ```
+*/
+const guidedPlan = async (ctx, manifest, deps) => {
+	for (;;) try {
+		return await planInfra(ctx, manifest);
+	} catch (error) {
+		if (!deps.interactive) throw error;
+		const ui = createBrandConsole();
+		ui.error(error instanceof Error ? error.message : String(error));
+		ui.info(HINTS.provision);
+		if (!await deps.confirm("Retry?")) return ABORTED;
+	}
+};
+/**
+* Plan + provision the infra with branded panels and interactive recovery. Each attempt RE-PLANS
+* (a resource created by a prior attempt is seen as existing and skipped — retries stay idempotent),
+* renders the plan panel (what will be created vs already exists), confirms the create gate, creates
+* the resources, then renders the result panel (created / skipped / failed). When some resources
+* FAIL it offers to retry just those (interactive) or fails fast (CI). Resolves to {@link ABORTED}
+* when the user declines the gate or a retry.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
+* @param deps - Interactivity + the confirm prompt.
+* @returns The provisioning result (all created/skipped), or {@link ABORTED} when the user declined.
+* @throws {Error} Re-throws a plan error, or throws on a provision failure, in CI / non-interactive runs.
+* @example
+* ```ts
+* const provisioned = await guidedProvision(ctx, manifest, ci, deps);
+* if (provisioned === ABORTED) return;
+* ```
+*/
+const guidedProvision = async (ctx, manifest, ci, deps) => {
+	for (;;) {
+		const plan = await guidedPlan(ctx, manifest, deps);
+		if (plan === ABORTED) return ABORTED;
+		const ui = createBrandConsole();
+		renderPlan(ui, plan);
+		if (plan.missing.length > 0 && !await deps.confirm(`Create ${String(plan.missing.length)} missing resource(s) in "${plan.account}"?`)) return ABORTED;
+		const result = await applyPlan(ctx, plan, ci);
+		renderProvisionResult(ui, result);
+		if (result.failed.length === 0) return result;
+		if (!deps.interactive) throw new Error(`[moku-worker] ${String(result.failed.length)} resource(s) failed to provision.`);
+		if (!await deps.confirm("Retry the failed resource(s)?")) return ABORTED;
+	}
+};
+/**
+* Build the web site first (when a hook is wired in), so its assets exist before the R2 upload and
+* `wrangler deploy`. Emits the `build · web` phase, then runs the build with interactive retry.
+*
+* @param ctx - The deploy plugin context.
+* @param webBuild - The web build hook, or undefined when none is wired (then this is a no-op).
+* @param deps - Interactivity + the confirm prompt.
+* @returns True to continue the pipeline; false when the user declined a build retry (abort).
+* @example
+* ```ts
+* if (!(await guidedWebBuild(ctx, webBuild, deps))) return emitAborted(ctx);
+* ```
+*/
+const guidedWebBuild = async (ctx, webBuild, deps) => {
+	if (webBuild === void 0) return true;
+	ctx.emit("deploy:phase", {
+		phase: "build",
+		detail: "web"
+	});
+	return await guidedStep(() => webBuild(), HINTS.build, deps) !== ABORTED;
+};
+/**
+* Upload the R2 directory when a bucket declares an upload source, with interactive retry. Emits the
+* `upload · N files` phase on success; a no-op (and emits nothing) when no bucket declares an upload.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param deps - Interactivity + the confirm prompt.
+* @returns True to continue the pipeline; false when the user declined an upload retry (abort).
+* @example
+* ```ts
+* if (!(await guidedUpload(ctx, manifest, deps))) return emitAborted(ctx);
+* ```
+*/
+const guidedUpload = async (ctx, manifest, deps) => {
+	const r2 = manifest.resources.find((resource) => resource.kind === "r2");
+	if (!r2?.upload) return true;
+	const bucket = r2.name;
+	const uploadDir = r2.upload;
+	const count = await guidedStep(() => uploadDirToR2(bucket, uploadDir), HINTS.upload, deps);
+	if (count === ABORTED) return false;
+	ctx.emit("deploy:phase", {
+		phase: "upload",
+		detail: `${String(count)} files`
+	});
+	return true;
+};
+/**
+* The final deploy step: confirm the target (guided only), run `wrangler deploy` with interactive
+* retry, then emit deploy:complete. Returns the deployed URL, or undefined when the target gate or a
+* deploy retry is declined (so the caller renders the summary panel only on a real success).
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param stage - The resolved deploy stage (for the confirm prompt).
+* @param deps - Interactivity + the confirm prompt.
+* @returns The deployed URL once live; undefined when the user declined the gate or a retry (abort).
+* @example
+* ```ts
+* const url = await guidedDeployStep(ctx, manifest, stage, deps);
+* if (url === undefined) return emitAborted(ctx);
+* ```
+*/
+const guidedDeployStep = async (ctx, manifest, stage, deps) => {
+	if (!await deps.confirm(`Deploy "${manifest.name}" to ${stage}?`)) return void 0;
+	ctx.emit("deploy:phase", { phase: "deploy" });
+	const url = await guidedStep(() => runWrangler([
+		"deploy",
+		"--config",
+		ctx.config.configFile
+	]), HINTS.deploy, deps);
+	if (url === ABORTED) return void 0;
+	ctx.emit("deploy:complete", { url });
+	return url;
+};
+/**
+* Apply pending D1 migrations to the REMOTE database for every configured d1 instance that ships a
+* migrations dir — the generic, deploy-owned analogue of `wrangler d1 migrations apply <binding>
+* --remote`. The wrangler config was written earlier in the pipeline, so each binding resolves. The
+* caller runs this only AFTER a successful deploy, so a deploy that never happened never migrates a
+* remote DB. CAPTURES wrangler's output (the raw TUI is hidden; {@link parseMigrationsApplied} turns
+* it into the branded panel's facts); throws on the first non-zero exit (the caller folds it into the
+* report, where the captured error is still surfaced).
+*
+* @param ctx - The deploy plugin context.
+* @returns The per-database migration outcomes (one per d1 instance that declares migrations).
+* @example
+* ```ts
+* const outcomes = await applyRemoteMigrations(ctx);
+* ```
+*/
+const applyRemoteMigrations = async (ctx) => {
+	if (!ctx.has("d1")) return [];
+	const outcomes = [];
+	for (const database of ctx.require(d1Plugin).deployManifest()) if (database.migrations !== void 0) {
+		const output = await runWrangler([
+			"d1",
+			"migrations",
+			"apply",
+			database.binding,
+			"--remote"
+		]);
+		outcomes.push({
+			binding: database.binding,
+			...parseMigrationsApplied(output)
+		});
+	}
+	return outcomes;
+};
+/**
+* Render a post-deploy step's failure as a branded line and capture its message into `errors` —
+* folding the failure into the report instead of throwing, so a deploy that already went live still
+* yields a complete, honest report when a later remote step (migration/seed) fails.
+*
+* @param ui - The branded console to render the error through.
+* @param errors - The accumulator the captured message is pushed into.
+* @param error - The thrown error (or value) to brand and capture.
+* @returns The captured (branded) message.
+* @example
+* ```ts
+* captureFailure(ui, errors, new Error("[moku-worker] seed failed"));
+* ```
+*/
+const captureFailure = (ui, errors, error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	ui.error(message);
+	errors.push(message);
+	return message;
+};
+/**
+* Run the post-deploy remote steps — REACHED ONLY ON A SUCCESSFUL DEPLOY (every gate in `run` returns
+* early before here), so a deploy that never happened never touches a remote DB. Applies remote D1
+* migrations (when requested), then loads the configured seed (when requested) — but skips the seed
+* if the migration it depends on failed. Each step's failure is RENDERED inline and CAPTURED in
+* `errors` (never thrown), so one failed step still yields a complete, honest report.
+*
+* @param ctx - The deploy plugin context.
+* @param want - Which post-steps the caller requested.
+* @param want.migration - Whether to apply pending remote D1 migrations.
+* @param want.seed - Whether to load the configured remote seed (and reset its KV keys).
+* @returns The migration + seed outcomes and any captured branded errors.
+* @example
+* ```ts
+* const post = await runPostDeploy(ctx, { migration: true, seed: true });
+* ```
+*/
+const runPostDeploy = async (ctx, want) => {
+	const ui = createBrandConsole();
+	const errors = [];
+	let migration = "skipped";
+	if (want.migration) try {
+		ctx.emit("deploy:phase", {
+			phase: "migrate",
+			detail: "remote D1"
+		});
+		const outcomes = await applyRemoteMigrations(ctx);
+		migration = "applied";
+		if (outcomes.length > 0) renderMigrateSummary(ui, outcomes, "remote");
+	} catch (error) {
+		migration = "failed";
+		captureFailure(ui, errors, error);
+	}
+	let seed = "skipped";
+	if (want.seed && migration === "failed") {
+		seed = "failed";
+		captureFailure(ui, errors, /* @__PURE__ */ new Error("[moku-worker] seed skipped — the remote migration it depends on failed."));
+	} else if (want.seed) {
+		const config = ctx.config.seed;
+		if (config === void 0) {
+			seed = "failed";
+			captureFailure(ui, errors, /* @__PURE__ */ new Error("[moku-worker] deploy({ seed: true }) but no seed is configured — set pluginConfigs.deploy.seed."));
+		} else try {
+			ctx.emit("deploy:phase", {
+				phase: "seed",
+				detail: config.file
+			});
+			const outcome = await runConfiguredSeed(ctx, runWrangler, config, "--remote");
+			seed = "applied";
+			renderSeedSummary(ui, outcome, "remote");
+		} catch (error) {
+			seed = "failed";
+			captureFailure(ui, errors, error);
+		}
+	}
+	return {
+		migration,
+		seed,
+		errors
+	};
+};
+/**
+* Create the deploy api. Assembles the manifest from each resource plugin's own deployManifest(),
+* runs an infra preflight (check-before-create + id capture), generates config, uploads, and runs
+* `wrangler deploy`, emitting global deploy events along the way.
+*
+* @param ctx - Plugin context (own config + require + has + emit + global + env).
+* @returns The app.deploy api: run / dev / init / checkInfra / provisionInfra.
+* @example
+* ```ts
+* const api = createDeployApi(ctx);
+* await api.run();
+* ```
+*/
+const createDeployApi = (ctx) => ({
+	/**
+	* Run the full deploy pipeline: detect → preflight (check-before-create) → provision (only the
+	* missing) → wrangler-config (with real ids) → upload → deploy, then — ONLY on a successful
+	* deploy — the requested post-deploy remote steps (migration, seed). When opts.manifest is
+	* supplied it is used verbatim (universal path).
+	*
+	* On a TTY the run is GUIDED end to end: each gate is confirmed, and every failure is recovered
+	* interactively rather than thrown — a missing/invalid token offers a `.env.local` scaffold, and
+	* the build, infra, upload, and `wrangler deploy` steps offer a retry. In CI/pipes it fails fast
+	* (no prompt, the first error propagates to the branded CLI handler).
+	*
+	* Resolves to a {@link DeployReport}. Every abort path (a declined gate, or auth never set up)
+	* returns `status: "aborted"` BEFORE the post-deploy steps, so `migration`/`seed` run only when
+	* the worker actually went live — a first `deploy --seed` with no token aborts cleanly instead of
+	* falling through to a raw `wrangler … --remote` auth error.
+	*
+	* @param opts - Optional run options.
+	* @param opts.ci - CI/automated mode: never prompts, auto-confirms every gate, fails fast. When
+	*   false (the default) and stdout is a TTY, the deploy is guided — each gate is confirmed and
+	*   failures are recovered interactively. Falls back to ctx.config.ci when omitted.
+	* @param opts.stage - Target stage; suffixes resource names (`production` = bare). Falls back to the app stage.
+	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+	* @param opts.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
+	* @param opts.migration - After a successful deploy, apply pending remote D1 migrations for every
+	*   configured d1 instance that ships migrations. Skipped (not attempted) on an aborted deploy.
+	* @param opts.seed - After a successful deploy (+ migration), load the seed configured under
+	*   `pluginConfigs.deploy.seed` into the remote D1 and reset its cached KV keys. Skipped on abort.
+	* @returns The deploy report (status, url, resource tally, migration/seed outcome, errors).
+	* @example
+	* ```ts
+	* const report = await api.run({ webBuild: () => web.cli.build(), migration: true, seed: true });
+	* if (!report.ok) process.exitCode = 1; // aborted or a post-step failed
+	* ```
+	*/
+	async run(opts) {
+		const ci = opts?.ci ?? ctx.config.ci;
+		const stage = opts?.stage ?? ctx.global.stage;
+		const interactive = !ci && stdoutIsTty();
+		const deps = {
+			interactive,
+			confirm: interactive ? createBrandPrompts().confirm : async (_question) => true
+		};
+		const startedAt = Date.now();
+		ctx.emit("deploy:phase", { phase: "auth" });
+		if (!await guidedAuth(ctx, deps)) return aborted(ctx, stage, startedAt);
+		if (!await guidedWebBuild(ctx, opts?.webBuild ?? ctx.config.webBuild, deps)) return aborted(ctx, stage, startedAt);
+		ctx.emit("deploy:phase", { phase: "detect" });
+		const manifest = opts?.manifest ?? assembleManifest(ctx, stage);
+		ctx.emit("deploy:phase", { phase: "provision" });
+		const provisioned = await guidedProvision(ctx, manifest, ci, deps);
+		if (provisioned === ABORTED) return aborted(ctx, stage, startedAt);
+		ctx.emit("deploy:phase", { phase: "wrangler-config" });
+		await writeWranglerConfig(ctx.config.configFile, manifest, provisioned.ids, wranglerExtra(ctx.config));
+		if (!await guidedUpload(ctx, manifest, deps)) return aborted(ctx, stage, startedAt);
+		const url = await guidedDeployStep(ctx, manifest, stage, deps);
+		if (url === void 0) return aborted(ctx, stage, startedAt);
+		const resources = {
+			created: provisioned.created.length,
+			exists: provisioned.skipped.length,
+			bundled: provisioned.bundled.length,
+			failed: provisioned.failed.length
+		};
+		renderDeploySummary(createBrandConsole(), {
+			url,
+			stage,
+			...resources,
+			elapsedMs: Date.now() - startedAt
+		});
+		const post = await runPostDeploy(ctx, {
+			migration: opts?.migration === true,
+			seed: opts?.seed === true
+		});
+		return {
+			ok: post.errors.length === 0,
+			status: post.errors.length === 0 ? "deployed" : "failed",
+			stage,
+			url,
+			resources,
+			migration: post.migration,
+			seed: post.seed,
+			elapsedMs: Date.now() - startedAt,
+			errors: post.errors
+		};
+	},
+	/**
+	* Start a long-lived local dev session: cold-build the Moku site, spawn `wrangler dev
+	* --live-reload`, and watch the site sources — rebuilding on change (wrangler live-reloads the
+	* browser). Resolves on SIGINT.
+	*
+	* @param opts - Optional options.
+	* @param opts.port - Local dev port (default 8787).
+	* @param opts.stage - Stage for the generated config's resource names (defaults to the app stage).
+	* @param opts.webBuild - Cold-build the web site (e.g. `() => webApp.cli.build()`); also the
+	*   per-change rebuild when `onChange` is omitted.
+	* @param opts.onChange - Incremental per-change rebuild (e.g. `changes => webApp.cli.update(changes)`).
+	* @param opts.seed - Load the configured seed (`pluginConfigs.deploy.seed`) into the LOCAL D1 and
+	*   reset its cached KV keys before serving — the local analogue of `deploy({ seed: true })`.
+	* @returns Resolves when the dev session ends.
+	* @example
+	* ```ts
+	* await api.dev({ port: 8787, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
+	* ```
+	*/
+	async dev(opts) {
+		const manifest = assembleManifest(ctx, opts?.stage ?? ctx.global.stage);
+		await writeWranglerConfig(ctx.config.configFile, manifest, {}, wranglerExtra(ctx.config));
+		await runDev(ctx, opts, realDevDeps());
+	},
+	/**
+	* Execute a SQL file against a configured D1 database via `wrangler d1 execute` — for seeding dev
+	* data. Local by default (applies that database's migrations first so the file's tables exist);
+	* `opts.remote` seeds Cloudflare (schema is applied by `deploy`). Generates the wrangler config up
+	* front so the binding resolves even on a first run. CAPTURES wrangler's output and renders a
+	* branded "Migrated" / "Seeded" summary (the raw migration/execute TUI is hidden) so the command
+	* reads the same as the rest of the deploy UX; a failure still surfaces the real wrangler error.
+	*
+	* @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+	* @param opts - Optional options.
+	* @param opts.stage - Stage for the generated config's resource names (defaults to the app stage).
+	* @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+	* @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+	* @returns Resolves once wrangler finishes executing the file and the summary is rendered.
+	* @example
+	* ```ts
+	* await api.seed("db/seed.sql");                   // local default d1 (migrate, then execute)
+	* await api.seed("db/seed.sql", { remote: true }); // remote d1
+	* ```
+	*/
+	async seed(sqlFile, opts) {
+		if (!ctx.has("d1")) throw new Error("[moku-worker] seed: no d1 database is configured.");
+		const stage = opts?.stage ?? ctx.global.stage;
+		await writeWranglerConfig(ctx.config.configFile, assembleManifest(ctx, stage), {}, wranglerExtra(ctx.config));
+		const target = resolveD1(ctx, opts?.binding);
+		const scope = opts?.remote === true ? "--remote" : "--local";
+		const where = opts?.remote === true ? "remote" : "local";
+		const ui = createBrandConsole();
+		if (scope === "--local" && target.migrations !== void 0) {
+			const migrated = await runWrangler([
+				"d1",
+				"migrations",
+				"apply",
+				target.binding,
+				"--local"
+			]);
+			renderMigrateSummary(ui, [{
+				binding: target.binding,
+				...parseMigrationsApplied(migrated)
+			}], where);
+		}
+		const executed = await runWrangler([
+			"d1",
+			"execute",
+			target.binding,
+			scope,
+			"--file",
+			sqlFile
+		]);
+		renderSeedSummary(ui, {
+			file: sqlFile,
+			binding: target.binding,
+			resetKv: [],
+			...parseSeedStats(executed)
+		}, where);
+	},
+	/**
+	* Scaffold a starting wrangler config (and CI files when ci is set).
+	* Idempotent: an existing config file is left untouched.
+	*
+	* @param opts - Optional options.
+	* @param opts.ci - Also scaffold CI workflow files.
+	* @returns Resolves once scaffolding is written.
+	* @example
+	* ```ts
+	* await api.init({ ci: true });
+	* ```
+	*/
+	init: async (opts) => {
+		await scaffoldWranglerAndCi(ctx.config.configFile, opts?.ci ?? ctx.config.ci);
+	},
+	/**
+	* Read-only infra preflight: assemble the manifest, resolve the account, list what exists in
+	* Cloudflare, diff, emit provision:plan, and return the plan. Writes nothing.
+	*
+	* @returns The infra plan (existing vs missing resources, with captured ids).
+	* @example
+	* ```ts
+	* const plan = await api.checkInfra();
+	* ```
+	*/
+	checkInfra: () => planInfra(ctx, assembleManifest(ctx, ctx.global.stage)),
+	/**
+	* Create only the resources missing from the plan (skipping existing), capturing each id.
+	*
+	* @param plan - A plan produced by checkInfra().
+	* @returns The provisioning result: created, skipped, and the merged id map.
+	* @example
+	* ```ts
+	* const { created } = await api.provisionInfra(await api.checkInfra());
+	* ```
+	*/
+	provisionInfra: (plan) => applyPlan(ctx, plan, ctx.config.ci),
+	/**
+	* Verify the `.env` Cloudflare API token (must be active) and resolve its account; emits
+	* auth:verified. Throws a branded error pointing at `auth setup` when absent/invalid/inactive.
+	*
+	* @returns The verified auth status (account + id).
+	* @example
+	* ```ts
+	* const { account } = await api.verifyAuth();
+	* ```
+	*/
+	verifyAuth: () => verifyAuth(ctx),
+	/**
+	* Derive the minimum Cloudflare API token this app needs from its manifest (pure, no network).
+	*
+	* @returns The token requirement (full set + groups to add to the stock template).
+	* @example
+	* ```ts
+	* const { toAdd } = api.requiredToken();
+	* ```
+	*/
+	requiredToken: () => requiredToken(assembleManifest(ctx, ctx.global.stage)),
+	/**
+	* Derive the REDUCED CI/automation redeploy token permission groups from the manifest (pure, no
+	* network). Used by the branded `auth setup` renderer to show the scoped CI token alongside the
+	* full LOCAL one.
+	*
+	* @returns The CI token permission groups (read-mostly, manifest-scoped).
+	* @example
+	* ```ts
+	* const groups = api.ciToken();
+	* ```
+	*/
+	ciToken: () => ciToken(assembleManifest(ctx, ctx.global.stage)),
+	/**
+	* Render the `auth setup` guidance from the derived token requirement (pure, no network).
+	*
+	* @returns The rendered instruction text.
+	* @example
+	* ```ts
+	* const text = api.tokenInstructions();
+	* ```
+	*/
+	tokenInstructions: () => tokenInstructions(assembleManifest(ctx, ctx.global.stage)),
+	/**
+	* Run an arbitrary wrangler command, streaming its output (the branded CLI escape hatch).
+	*
+	* @param args - The wrangler arguments.
+	* @returns Resolves once wrangler exits.
+	* @example
+	* ```ts
+	* await api.wrangler(["kv", "namespace", "list"]);
+	* ```
+	*/
+	wrangler: (args) => runWranglerInherit(args)
+});
+/**
+* Complex tier (node-only) — build-time deploy orchestrator over the five resource plugins.
+*
+* Assembles each resource plugin's deployManifest() via ctx.require, provisions resources,
+* generates/updates wrangler config, uploads the R2 upload dir, and runs wrangler deploy.
+* Also supports a universal path: run({ manifest }) uses a caller-supplied manifest verbatim.
+*
+* Emits only the global events `deploy:phase`, `deploy:complete`, and `provision:resource`
+* (declared in WorkerEvents — no per-plugin events block).
+*
+* @see README.md
+*/
+const deployPlugin = createPlugin$1("deploy", {
+	config: {
+		configFile: "wrangler.jsonc",
+		ci: false,
+		watch: ["src/**/*.{ts,tsx,css}", "public/**/*"],
+		buildCommand: "",
+		migrateLocal: true,
+		debounceMs: 120
+	},
+	depends: [
+		storagePlugin,
+		kvPlugin,
+		d1Plugin,
+		queuesPlugin,
+		durableObjectsPlugin
+	],
+	api: (ctx) => createDeployApi(ctx)
+});
+//#endregion
+//#region src/plugins/cli/args.ts
+/**
+* @file cli plugin — argv parsing helpers (isolated so they unit-test without a real process).
+*
+* `deploy`/`dev` resolve the target stage from the command line (`--stage dev`) so a consumer never
+* hardcodes it. The dev PORT is not parsed here — it comes only from the `dev()` argument (no hidden
+* argv/config resolution). Pure: takes an argv array, reads no globals. Node-only tooling.
+*/
+/**
+* Extract a `--stage` value from a single token (and the token after it, for the spaced form).
+*
+* @param token - The current argv token.
+* @param next - The following argv token (the value, for the `--stage dev` spaced form).
+* @returns The raw string value when this token is a stage flag, else undefined.
+* @example
+* ```ts
+* stageValueFrom("--stage=dev", undefined); // "dev"
+* stageValueFrom("--stage", "dev");         // "dev"
+* stageValueFrom("--other", "x");           // undefined
+* ```
+*/
+const stageValueFrom = (token, next) => {
+	const inline = /^--stage=(.+)$/u.exec(token);
+	if (inline) return inline[1];
+	if (token === "--stage") return next;
+};
+/**
+* Parse a `--stage <name>` / `--stage=<name>` flag out of an argv array — the deploy/dev stage that
+* drives the resource-name suffix (e.g. `tracker-db-dev`). Returns the first non-empty value, or
+* undefined so the caller can fall back to the app's configured stage.
+*
+* @param argv - The argv array to scan (the caller passes the process argv).
+* @returns The parsed stage string, or undefined when no `--stage` flag is present.
+* @example
+* ```ts
+* parseStageArg(["bun", "scripts/deploy.ts", "--stage", "dev"]); // "dev"
+* parseStageArg(["bun", "scripts/deploy.ts"]);                    // undefined
+* ```
+*/
+const parseStageArg = (argv) => {
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		if (token === void 0) continue;
+		const raw = stageValueFrom(token, argv[index + 1]);
+		if (raw !== void 0 && raw.length > 0) return raw;
+	}
+};
+//#endregion
+//#region src/plugins/cli/api.ts
+/**
+* @file cli plugin — API factory (dev, deploy, auth, doctor).
+*/
+/**
+* Builds app.cli.* over the deploy plugin (via ctx.require(deployPlugin)). `dev`/`deploy` resolve
+* their args (port from `--port`; guided unless `ci`) then delegate, catching any failure into a
+* branded `✗` line + non-zero exit; the read-only verbs (auth/doctor/whoami) render in Moku style.
+*
+* @param ctx - CLI plugin context (own config + typed require to deployPlugin).
+* @returns The cli API object (dev, deploy, auth, doctor, whoami, wrangler).
+* @example
+* ```ts
+* const api = createCliApi(ctx);
+* await api.dev({ webBuild: () => web.cli.build() }); // → deploy.dev({ port })
+* await api.deploy({ ci: true });                     // → deploy.run({ ci: true })
+* ```
+*/
+const createCliApi = (ctx) => ({
+	/**
+	* Run the Worker locally. The dev port comes ONLY from `opts.port` — the consumer passes it (e.g.
+	* parsed from its own CLI flags in scripts/dev.ts); when omitted it defaults to wrangler's 8787.
+	* There is no hidden argv/config port resolution. Prints a branded dev-session banner, then
+	* delegates to deploy.dev; a `webBuild` hook (e.g. `() => webApp.cli.build()`) wires the web build
+	* into the dev loop so the site recompiles on change. A failure renders a branded `✗` line +
+	* non-zero exit, not a stack.
+	*
+	* @param opts - Optional local dev options.
+	* @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
+	* @param opts.stage - Stage for the generated wrangler config; falls back to `--stage` then the app stage.
+	* @param opts.webBuild - Cold-build the web site (e.g. `() => webApp.cli.build()`); also the
+	*   per-change rebuild when `onChange` is omitted.
+	* @param opts.onChange - Incremental per-change rebuild (e.g. `changes => webApp.cli.update(changes)`),
+	*   so each change rebuilds only the changed paths instead of a full `webBuild()`.
+	* @param opts.seed - Load the configured seed (`pluginConfigs.deploy.seed`) into the LOCAL D1 and
+	*   reset its cached KV keys before serving — the local analogue of `deploy({ seed: true })`.
+	* @returns Resolves when the dev session ends.
+	* @example
+	* ```ts
+	* await api.dev({ port: 7878, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
+	* ```
+	*/
+	async dev(opts) {
+		const ui = createBrandConsole();
+		ui.lockup({
+			wordmark: "moku worker",
+			label: "dev session"
+		});
+		const stage = opts?.stage ?? parseStageArg(process.argv);
+		try {
+			await ctx.require(deployPlugin).dev({
+				...opts?.port === void 0 ? {} : { port: opts.port },
+				...stage === void 0 ? {} : { stage },
+				...opts?.webBuild ? { webBuild: opts.webBuild } : {},
+				...opts?.onChange ? { onChange: opts.onChange } : {},
+				...opts?.seed ? { seed: opts.seed } : {}
+			});
+			ui.check(true, "dev session stopped cleanly");
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}
+	},
+	/**
+	* One-command Cloudflare deploy; forwards opts verbatim to deploy.run, then — only on a successful
+	* deploy — the requested post-deploy migration/seed. Guided/interactive by default; `{ ci: true }`
+	* runs the automated path (CI). A `webBuild` hook builds the web site first (before `wrangler
+	* deploy`). RETURNS the structured {@link DeployReport}; on a failure it also renders a branded `✗`
+	* line + sets a non-zero exit code (matching cli.auth/doctor), never a raw stack trace.
+	*
+	* @param opts - Optional deploy options.
+	* @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
+	* @param opts.stage - Target stage (resource-name suffix); falls back to `--stage` then the app stage.
+	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+	* @param opts.migration - Apply pending remote D1 migrations after a successful deploy (skipped on abort).
+	* @param opts.seed - Load the configured remote seed (`pluginConfigs.deploy.seed`) after a
+	*   successful deploy (+ migration); skipped on an aborted deploy.
+	* @returns The deploy report (status, url, resource tally, migration/seed outcome, errors).
+	* @example
+	* ```ts
+	* const report = await api.deploy({ webBuild: () => web.cli.build(), migration: true, seed: true });
+	* if (report.status === "aborted") return; // creds not set up yet — nothing shipped
+	* ```
+	*/
+	async deploy(opts) {
+		const stage = opts?.stage ?? parseStageArg(process.argv);
+		try {
+			const report = await ctx.require(deployPlugin).run({
+				...opts,
+				...stage === void 0 ? {} : { stage }
+			});
+			if (report.status === "failed") process.exitCode = 1;
+			return report;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			createBrandConsole().error(message);
+			process.exitCode = 1;
+			return {
+				ok: false,
+				status: "failed",
+				stage: stage ?? "production",
+				migration: "skipped",
+				seed: "skipped",
+				elapsedMs: 0,
+				errors: [message]
+			};
+		}
+	},
+	/**
+	* Seed a configured D1 database from a SQL file (delegates to deploy.seed). Local by default;
+	* `opts.remote` seeds Cloudflare. The stage is resolved from a `--stage <name>` CLI flag (so
+	* `bun run dev --seed --stage dev` seeds the dev database). A failure renders a branded `✗` line
+	* and sets a non-zero exit code rather than throwing.
+	*
+	* @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+	* @param opts - Optional options.
+	* @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+	* @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+	* @returns Resolves once the seed completes (or after a failure is rendered).
+	* @example
+	* ```ts
+	* await app.cli.seed("db/seed.sql"); // before app.cli.dev(...)
+	* ```
+	*/
+	async seed(sqlFile, opts) {
+		const ui = createBrandConsole();
+		ui.lockup({
+			wordmark: "moku worker",
+			label: "seed"
+		});
+		const stage = parseStageArg(process.argv);
+		try {
+			await ctx.require(deployPlugin).seed(sqlFile, {
+				...opts,
+				...stage === void 0 ? {} : { stage }
+			});
+			ui.check(true, "seeded", sqlFile);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}
+	},
+	/**
+	* Verify the `.env` token (no sub) or print the config-derived token guidance (`"setup"`),
+	* rendered in Moku style. `setup` works without a token; verify reports the resolved account.
+	*
+	* @param sub - Pass "setup" to print guidance; omit to verify the current token.
+	* @returns Resolves once the check or guidance render completes.
+	* @example
+	* ```ts
+	* await api.auth("setup"); // print what token to create
+	* await api.auth();        // verify the current token
+	* ```
+	*/
+	async auth(sub) {
+		const deploy = ctx.require(deployPlugin);
+		const ui = createBrandConsole();
+		if (sub === "setup") {
+			renderAuthSetup(ui, deploy.requiredToken(), { ci: deploy.ciToken() });
+			return;
+		}
+		try {
+			const status = await deploy.verifyAuth();
+			ui.check(true, "token valid", `account "${status.account}" (${status.accountId})`);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* One-shot preflight report: token + account (verifyAuth) then infra drift (checkInfra),
+	* each as a branded check line. Stops after the token check when auth fails.
+	*
+	* @returns Resolves once the report is printed.
+	* @example
+	* ```ts
+	* await api.doctor();
+	* ```
+	*/
+	async doctor() {
+		const deploy = ctx.require(deployPlugin);
+		const ui = createBrandConsole();
+		ui.heading("doctor");
+		let tokenOk = false;
+		try {
+			const status = await deploy.verifyAuth();
+			tokenOk = true;
+			ui.check(true, "token", `valid · account "${status.account}" (${status.accountId})`);
+		} catch (error) {
+			ui.check(false, "token", error instanceof Error ? error.message : String(error));
+		}
+		if (!tokenOk) {
+			ui.line("Run `auth setup` for the exact token to create.");
+			return;
+		}
+		try {
+			const plan = await deploy.checkInfra();
+			ui.check(true, "infra", `${plan.exists.length} exist, ${plan.missing.length} to create in "${plan.account}"`);
+		} catch (error) {
+			ui.check(false, "infra", error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* Print the resolved Cloudflare account for the current `.env` token.
+	*
+	* @returns Resolves once the account summary is printed.
+	* @example
+	* ```ts
+	* await api.whoami();
+	* ```
+	*/
+	async whoami() {
+		const ui = createBrandConsole();
+		try {
+			const status = await ctx.require(deployPlugin).verifyAuth();
+			ui.check(true, "account", `${status.account} (${status.accountId})`);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* Run an arbitrary wrangler command through the branded CLI (escape hatch). Streams its output.
+	*
+	* @param args - The wrangler arguments.
+	* @returns Resolves once wrangler exits.
+	* @example
+	* ```ts
+	* await api.wrangler(["kv", "namespace", "list"]);
+	* ```
+	*/
+	async wrangler(args) {
+		createBrandConsole().heading(`wrangler ${args.join(" ")}`);
+		await ctx.require(deployPlugin).wrangler(args);
+	}
+});
+//#endregion
+//#region src/plugins/cli/handlers.ts
+/** Divider drawn before the native `wrangler dev` TUI so the moku preamble reads as one section. */
+const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
+/** Deploy phases that are a slow, opaque wait (captured output) — worth a live spinner on a TTY. */
+const SPINNER_PHASES = new Set(["upload", "deploy"]);
+/** Braille spinner glyphs; advance one per tick. */
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** Spinner tick interval (ms). */
+const SPINNER_TICK_MS = 80;
+/** Carriage-return + blanks + carriage-return that wipes the transient spinner line before settling. */
+const SPINNER_CLEAR = `\r${" ".repeat(72)}\r`;
+/**
+* Builds the hook handlers that turn global deploy events into a live progress TUI.
+* Each logs a clean, prefix-free message via `ctx.log`; the branded log sink (installed
+* by the cli plugin's onInit from `@moku-labs/common/cli`) adds the `›` marker, brand
+* color, and stderr routing. Pure observers — print and return; never mutate state,
+* never block the deploy pipeline (fire-and-forget, spec/07 §3,§4).
+*
+* @param ctx - CLI plugin context with injected log core API.
+* @returns Hook map for the deploy/dev phase + completion events (provision detail is panel-rendered).
+* @example
+* ```ts
+* const hooks = createCliHooks(ctx);
+* hooks["deploy:phase"]({ phase: "detect" }); // logs "detect" → renders "  › detect"
+* hooks["dev:phase"]({ phase: "serve", detail: "http://localhost:8787" }); // "serve · …"
+* hooks["deploy:complete"](); // settles the deploy spinner; the "Deployed" panel renders separately
+* ```
+*/
+const createCliHooks = (ctx) => {
+	const ui = createBrandConsole();
+	const { palette } = ui;
+	let spinnerTimer;
+	let spinnerLabel;
+	const stopSpinner = () => {
+		if (spinnerTimer !== void 0) {
+			clearInterval(spinnerTimer);
+			spinnerTimer = void 0;
+		}
+		if (spinnerLabel !== void 0) {
+			process.stdout.write(SPINNER_CLEAR);
+			ctx.log.info(spinnerLabel);
+			spinnerLabel = void 0;
+		}
+	};
+	const startSpinner = (label) => {
+		spinnerLabel = label;
+		let frame = 0;
+		const text = `${label} …`;
+		spinnerTimer = setInterval(() => {
+			const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0];
+			frame += 1;
+			process.stdout.write(`\r  ${palette.pink(glyph)} ${palette.dim(text)}`);
+		}, SPINNER_TICK_MS);
+	};
+	return {
+		/**
+		* Render one pipeline phase. Quick phases print a clean line ("phase" / "phase · detail"); the
+		* slow opaque waits (upload / deploy) animate a branded spinner on a TTY, settling to a line when
+		* the next phase or completion arrives. Off a TTY every phase is a plain line (unchanged).
+		*
+		* @param p - The deploy:phase event payload.
+		* @example
+		* ```ts
+		* handler({ phase: "detect" }); // "detect"
+		* handler({ phase: "deploy" }); // spins on a TTY, else "deploy"
+		* ```
+		*/
+		"deploy:phase"(p) {
+			stopSpinner();
+			const label = p.detail ? `${p.phase} · ${p.detail}` : p.phase;
+			if (process.stdout.isTTY === true && SPINNER_PHASES.has(p.phase)) startSpinner(label);
+			else ctx.log.info(label);
+		},
+		/**
+		* Log one dev-session phase: "phase" or "phase · detail".
+		*
+		* @param p - The dev:phase event payload.
+		* @example
+		* ```ts
+		* handler({ phase: "serve", detail: "http://localhost:8787" }); // "serve · http://localhost:8787"
+		* ```
+		*/
+		"dev:phase"(p) {
+			ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
+			if (p.phase === "serve") ui.line(WRANGLER_DIVIDER);
+		},
+		/**
+		* Log the site rebuild result: "site <n> files · <ms>ms" (omits the count when unknown).
+		*
+		* @param p - The dev:rebuilt event payload.
+		* @example
+		* ```ts
+		* handler({ files: 12, ms: 240 }); // "site 12 files · 240ms"
+		* handler({ files: 0, ms: 240 }); // "site · 240ms"
+		* ```
+		*/
+		"dev:rebuilt"(p) {
+			ctx.log.info(p.files > 0 ? `site ${String(p.files)} files · ${String(p.ms)}ms` : `site · ${String(p.ms)}ms`);
+		},
+		/**
+		* Log a non-fatal dev build failure via warn (the session keeps serving the last good build).
+		*
+		* @param p - The dev:error event payload.
+		* @example
+		* ```ts
+		* handler({ message: "build failed" }); // warn "build failed"
+		* ```
+		*/
+		"dev:error"(p) {
+			ctx.log.warn(p.message);
+		},
+		/**
+		* Settle the final deploy spinner. The deployed URL + summary now render as a branded panel (the
+		* deploy plugin's renderDeploySummary), so the cli no longer logs a duplicate `deployed → url`.
+		*
+		* @example
+		* ```ts
+		* handler(); // clears the `deploy` spinner; the "Deployed" panel follows from the deploy plugin
+		* ```
+		*/
+		"deploy:complete"() {
+			stopSpinner();
+		}
+	};
+};
+/**
+* Standard tier (node-only) — developer-facing CLI surface.
+*
+* Mounts `app.cli.dev()` and `app.cli.deploy()` as thin passthroughs to deployPlugin.
+* Hooks subscribe to the global deploy:phase / provision:resource / deploy:complete events
+* and print a live progress TUI via the injected ctx.log core API.
+*
+* Inline lambdas on `api`/`hooks` preserve event-name inference so the hook map keys
+* are constrained to `WorkerEvents` keys (spec/15 §5).
+*
+* @see README.md
+*/
+const cliPlugin = createPlugin$1("cli", {
+	depends: [deployPlugin],
+	config: {},
+	onInit: (ctx) => {
+		ctx.log.clearSinks();
+		ctx.log.addSink(brandedSink("info"));
+	},
+	api: (ctx) => createCliApi(ctx),
+	hooks: (ctx) => createCliHooks(ctx)
+});
+//#endregion
 //#region src/index.ts
 const framework = createCore(coreConfig, { plugins: [bindingsPlugin, serverPlugin] });
 const { createPlugin } = framework;