@moku-labs/worker 0.5.1 → 0.6.0

package/dist/cli-Dc0q0hIy.cjs

@@ -0,0 +1,2988 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let _moku_labs_common = require("@moku-labs/common");
+let _moku_labs_core = require("@moku-labs/core");
+let _moku_labs_common_cli = require("@moku-labs/common/cli");
+let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+let node_fs_promises = require("node:fs/promises");
+/**
+* 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.
+*
+* @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 = (0, _moku_labs_core.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 = (0, _moku_labs_core.createCoreConfig)("moku-worker", {
+	config: {
+		stage: "production",
+		name: "moku-worker",
+		compatibilityDate: ""
+	},
+	plugins: [
+		_moku_labs_common.logPlugin,
+		_moku_labs_common.envPlugin,
+		stagePlugin
+	]
+});
+const { createPlugin, 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("bindings", {
+	config: { required: [] },
+	api: createBindingsApi
+});
+//#endregion
+//#region src/plugins/d1/api.ts
+/**
+* Create the d1 api. Each method resolves the D1Database off the request
+* `env` via the bindings plugin, then forwards to the native D1 call. The
+* binding is never cached, so concurrent requests stay isolated (SB4).
+*
+* 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 (own config + require).
+* @returns {object} The d1 public api (query, first, run, batch, prepare, deployManifest).
+* @example
+* ```typescript
+* const api = createD1Api(ctx);
+* const { results } = await api.query<Product>(env, "SELECT * FROM products");
+* ```
+*/
+const createD1Api = (ctx) => {
+	const db = (env) => ctx.require(bindingsPlugin).require(env, ctx.config.binding);
+	return {
+		/**
+		* Run a statement and return all rows. Forwards the call-site generic to
+		* `all<T>()` so the result type is not widened to `unknown`.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {string} sql - SQL text with `?` placeholders.
+		* @param {unknown[]} params - Bind parameters, in placeholder order.
+		* @returns {Promise<D1Result<T>>} All rows (`.results` is `T[]`).
+		* @example
+		* ```typescript
+		* const { results } = await api.query<Product>(env, "SELECT * FROM products WHERE active = ?", 1);
+		* ```
+		*/
+		query: (env, sql, ...params) => db(env).prepare(sql).bind(...params).all(),
+		/**
+		* Run a statement and return the first row, or `null` if there are none.
+		* Forwards the call-site generic to `first<T>()`.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {string} sql - SQL text with `?` placeholders.
+		* @param {unknown[]} params - Bind parameters, in placeholder order.
+		* @returns {Promise<T | null>} The first row, or `null` if none matched.
+		* @example
+		* ```typescript
+		* const row = await api.first<Product>(env, "SELECT * FROM products WHERE id = ?", id);
+		* ```
+		*/
+		first: (env, sql, ...params) => db(env).prepare(sql).bind(...params).first(),
+		/**
+		* Run a write/DDL statement (INSERT/UPDATE/DELETE/DDL) and return the
+		* D1 result carrying `.meta` (e.g. `rows_written`, `last_row_id`).
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {string} sql - SQL text with `?` placeholders.
+		* @param {unknown[]} params - Bind parameters, in placeholder order.
+		* @returns {Promise<D1Result>} Result carrying `.meta`.
+		* @example
+		* ```typescript
+		* const res = await api.run(env, "INSERT INTO products (name) VALUES (?)", name);
+		* const id = res.meta.last_row_id;
+		* ```
+		*/
+		run: (env, sql, ...params) => db(env).prepare(sql).bind(...params).run(),
+		/**
+		* Execute caller-built prepared statements atomically in one round-trip,
+		* returning one result per statement in order.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @param {D1PreparedStatement[]} stmts - Statements built from prepare(env).
+		* @returns {Promise<D1Result[]>} One result per statement, order preserved.
+		* @example
+		* ```typescript
+		* const handle = api.prepare(env);
+		* await api.batch(env, [handle.prepare("INSERT INTO a VALUES (1)").bind()]);
+		* ```
+		*/
+		batch: (env, stmts) => db(env).batch(stmts),
+		/**
+		* Resolve the request-scoped D1Database so callers can build prepared
+		* statements for batch(). Issues no query itself.
+		*
+		* @param {WorkerEnv} env - Per-request Cloudflare bindings object.
+		* @returns {D1Database} The request-resolved database handle.
+		* @example
+		* ```typescript
+		* const handle = api.prepare(env);
+		* const stmt = handle.prepare("SELECT * FROM t").bind();
+		* ```
+		*/
+		prepare: (env) => db(env),
+		/**
+		* Return this plugin's deploy metadata for the deploy plugin to read.
+		* Build-time only — takes no `env`. The return is typed `DeployManifest`
+		* (from types.ts), which pins `kind` to the literal `"d1"` without an
+		* inline `as` assertion.
+		*
+		* @returns {DeployManifest} Deploy manifest entry `{ kind: "d1", binding, migrations }`.
+		* @example
+		* ```typescript
+		* const m = api.deployManifest();
+		* // => { kind: "d1", binding: "DB", migrations: "./migrations" }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "d1",
+			binding: ctx.config.binding,
+			migrations: ctx.config.migrations
+		})
+	};
+};
+/**
+* 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("d1", {
+	depends: [bindingsPlugin],
+	config: {
+		binding: "DB",
+		migrations: ""
+	},
+	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 config bindings map is frozen and read-only. No state
+* is held on the plugin between calls (stateless — `Record<string, never>`).
+*
+* @param ctx - Plugin context with `config.bindings`, `require(bindingsPlugin)`, and core APIs.
+* @returns The durableObjects API: `{ get, deployManifest }`.
+* @example
+* ```typescript
+* const api = createDoApi(ctx);
+* const stub = api.get(env, "counter", "room-42");
+* const manifest = api.deployManifest(); // { kind: "do", bindings: { counter: "COUNTER" } }
+* ```
+*/
+const createDoApi = (ctx) => ({
+	/**
+	* Resolves a `DurableObjectStub` off the per-request env.
+	*
+	* Maps `logicalName` → `config.bindings[logicalName]` (falling back to `logicalName`
+	* itself when unmapped), derives a deterministic id via `namespace.idFromName(idName)`,
+	* and returns the addressed stub. Synchronous — returns a stub, not a Promise.
+	* Throws (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 name used in code (e.g. `"counter"`).
+	* @param idName - Stable id name passed to `idFromName` (e.g. `"room-42"`).
+	* @returns The addressed `DurableObjectStub`.
+	* @throws {Error} With `[moku-worker]` prefix when the binding is not bound on `env`.
+	* @example
+	* ```typescript
+	* const stub = app.durableObjects.get(env, "counter", "room-42");
+	* const res = await stub.fetch("https://do/increment");
+	* ```
+	*/
+	get: (env, logicalName, idName) => {
+		const binding = ctx.config.bindings[logicalName] ?? logicalName;
+		const ns = ctx.require(bindingsPlugin).require(env, binding);
+		return ns.get(ns.idFromName(idName));
+	},
+	/**
+	* Returns this plugin's deploy metadata — read by the `deploy` plugin via
+	* `ctx.require(durableObjectsPlugin)`. Never reads sibling `pluginConfigs` (F6;
+	* spec/08 §5, §7). Pure synchronous read of `ctx.config.bindings`.
+	*
+	* @returns `{ kind: "do", bindings }` reflecting the frozen plugin config.
+	* @example
+	* ```typescript
+	* const manifest = app.durableObjects.deployManifest();
+	* // → { kind: "do", bindings: { counter: "COUNTER" } }
+	* ```
+	*/
+	deployManifest: () => ({
+		kind: "do",
+		bindings: ctx.config.bindings
+	})
+});
+//#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). 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, "counter", params.room!);
+* const res = await stub.fetch("https://do/increment");
+* // Consumer DO class:
+* export class Counter extends defineDurableObject("Counter") {
+*   async fetch(): Promise<Response> { return new Response("ok"); }
+* }
+* ```
+* @see README.md
+*/
+const durableObjectsPlugin = createPlugin("durableObjects", {
+	depends: [bindingsPlugin],
+	config: { bindings: {} },
+	api: createDoApi,
+	helpers: { defineDurableObject }
+});
+//#endregion
+//#region src/plugins/kv/api.ts
+/**
+* Builds the app.kv.* api. Resolves the KV namespace off the REQUEST-SUPPLIED env
+* on every call — env is threaded, never stored (design §1a / SB4).
+*
+* @param ctx - The kv plugin context (own config + merged events).
+* @returns The app.kv api: get / put / delete / list / deployManifest.
+* @example
+* ```typescript
+* const api = createKvApi(ctx);
+* const value = await api.get(env, "key");
+* ```
+*/
+const createKvApi = (ctx) => {
+	const ns = (env) => ctx.require(bindingsPlugin).require(env, ctx.config.binding);
+	return {
+		/**
+		* Reads a value by key from the KV namespace. Returns null when absent.
+		*
+		* @param env - The per-request Cloudflare env (threaded, never stored).
+		* @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),
+		/**
+		* Writes 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),
+		/**
+		* Removes a key from the 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),
+		/**
+		* Lists keys in the namespace, optionally filtered/paginated via opts.
+		*
+		* @param env - The per-request Cloudflare env.
+		* @param opts - Optional prefix / cursor / limit.
+		* @returns The list result from the KV namespace.
+		* @example
+		* ```typescript
+		* const { keys } = await api.list(env, { prefix: "session:" });
+		* ```
+		*/
+		list: async (env, opts) => ns(env).list(opts),
+		/**
+		* Returns this plugin's own deploy metadata, read by the deploy plugin via
+		* require (design §6 / F6). Build-time only — takes no env.
+		*
+		* @returns The kv deploy descriptor with kind literal and binding name.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest(); // { kind: "kv", binding: "KV" }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "kv",
+			binding: ctx.config.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("kv", {
+	depends: [bindingsPlugin],
+	config: { binding: "KV" },
+	api: createKvApi
+});
+//#endregion
+//#region src/plugins/queues/api.ts
+/**
+* @file queues plugin — API factory (send, sendBatch, consume, deployManifest).
+*
+* All binding-resolving methods take the per-request `env` as the first argument
+* and resolve the `Queue` via `ctx.require(bindingsPlugin).require<Queue>(env, name)`.
+* The `env` is never stored (SB4 / design §1a) — resolved fresh on every call.
+*/
+/**
+* Builds app.queues.* — read by worker.ts queue() delegation (design §1d; spec/02 §7).
+*
+* Resolves Queue bindings off the request env per call (never stored — SB4).
+* Emits `queue:message` for observability after each consumed message (F8).
+*
+* @param ctx - Plugin context (own config + require + emit).
+* @returns The queues API surface: send, sendBatch, consume, deployManifest.
+* @example
+* ```ts
+* // Worker entry (design §1d)
+* export default {
+*   queue: (b, e, c) => app.queues.consume(b, e, c),
+* };
+* ```
+*/
+const createQueuesApi = (ctx) => {
+	/**
+	* Resolves a named Queue binding from the per-request env.
+	* Throws a [moku-worker]-prefixed error when the binding is absent.
+	*
+	* @param env - Per-request Cloudflare bindings.
+	* @param name - Queue binding name.
+	* @returns The resolved Queue instance.
+	* @example
+	* ```ts
+	* const q = queue(env, "ORDERS");
+	* ```
+	*/
+	const queue = (env, name) => ctx.require(bindingsPlugin).require(env, name);
+	return {
+		/**
+		* Enqueue a single message onto the named queue.
+		*
+		* Resolves the Queue binding fresh from `env` on every call (SB4).
+		* Request/response work → api method, never emit (F8).
+		*
+		* @param env - Per-request Cloudflare bindings object.
+		* @param q - Target queue binding name in `env`.
+		* @param body - Message body to enqueue.
+		* @returns Resolves once the message is enqueued.
+		* @throws {Error} With a `[moku-worker]` prefix if the binding is missing.
+		* @example
+		* ```ts
+		* await app.queues.send(env, "ORDERS", { orderId: "123" });
+		* ```
+		*/
+		send: async (env, q, body) => {
+			await queue(env, q).send(body);
+		},
+		/**
+		* Enqueue many messages in one call; each element becomes one message.
+		*
+		* Maps each body to `{ body }` before calling `Queue.sendBatch` (design §4.3).
+		*
+		* @param env - Per-request Cloudflare bindings object.
+		* @param q - Target queue binding name in `env`.
+		* @param bodies - Array of message bodies; each becomes one message.
+		* @returns Resolves once all messages are enqueued.
+		* @throws {Error} With a `[moku-worker]` prefix if the binding is missing.
+		* @example
+		* ```ts
+		* await app.queues.sendBatch(env, "ORDERS", orders);
+		* ```
+		*/
+		sendBatch: async (env, q, bodies) => {
+			await queue(env, q).sendBatch(bodies.map((body) => ({ body })));
+		},
+		/**
+		* Consumer dispatch — the Worker's `queue()` export delegates here.
+		*
+		* Iterates `batch.messages`, **awaits** `config.onMessage(message, env)` per message
+		* (so Cloudflare gets a settled promise and the handler controls ack/retry; F8,
+		* spec/07 §3 — never emit for awaited work), then fire-and-forget emits `queue:message`
+		* for observability. Returns a promise the Worker **must** await so the isolate is not
+		* killed mid-batch.
+		*
+		* @param batch - The incoming message batch from Cloudflare.
+		* @param env - Per-request Cloudflare bindings object.
+		* @param _exec - waitUntil / passThroughOnException (reserved for future use).
+		* @returns Resolves after all messages in the batch are processed.
+		* @throws {Error} Re-throws any error from `config.onMessage` so Cloudflare can retry.
+		* @example
+		* ```ts
+		* // Worker entry
+		* queue: (b, e, c) => app.queues.consume(b, e, c),
+		* ```
+		*/
+		consume: async (batch, env, _exec) => {
+			for (const m of batch.messages) {
+				await ctx.config.onMessage(m, env);
+				ctx.emit("queue:message", {
+					queue: batch.queue,
+					messageId: m.id
+				});
+			}
+		},
+		/**
+		* Returns this plugin's deploy metadata, read by the deploy plugin via
+		* `ctx.require(queuesPlugin).deployManifest()` (F6 — never reads sibling config).
+		*
+		* @returns Deploy manifest entry `{ kind: "queue", producers }`.
+		* @example
+		* ```ts
+		* const manifest = ctx.require(queuesPlugin).deployManifest();
+		* // → { kind: "queue", producers: ["orders"] }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "queue",
+			producers: ctx.config.producers
+		})
+	};
+};
+/**
+* Standard tier — Cloudflare Queues producer + consumer dispatch.
+*
+* `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("queues", {
+	events: (register) => register.map({ "queue:message": "A queue message was processed" }),
+	depends: [bindingsPlugin],
+	config: {
+		producers: [],
+		onMessage: async () => {}
+	},
+	api: (ctx) => createQueuesApi(ctx)
+});
+//#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 env-first storage API. Each runtime method resolves the bucket
+* provider fresh from the per-request `env` — nothing is stored, so concurrent
+* requests stay isolated (worker-api-design SB4; spec/08 §6,§7).
+*
+* The `deployManifest()` method is build-time only: it reads from `ctx.config`
+* and never touches `env` or R2.
+*
+* @param ctx - Plugin context (config + require for bindings resolution).
+* @returns {StorageApi} The env-first storage API surface.
+* @example
+* ```typescript
+* const api = createStorageApi(ctx);
+* const body = await api.get(env, "my-object");
+* ```
+*/
+const createStorageApi = (ctx) => {
+	/**
+	* Resolve the StorageProvider for the given per-request env. Called on every
+	* method invocation — the bucket binding is never cached across calls.
+	*
+	* @param env - The per-request Cloudflare bindings object.
+	* @returns {StorageProvider} A StorageProvider delegating to the resolved R2Bucket.
+	* @example
+	* ```typescript
+	* const p = provider(env);
+	* const body = await p.get("key");
+	* ```
+	*/
+	const provider = (env) => resolveR2Provider(ctx.require(bindingsPlugin), env, ctx.config.bucket);
+	return {
+		/**
+		* Read an object from the bucket; resolves null when the key is absent.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param key - Object key.
+		* @returns {Promise<R2ObjectBody | null>} The R2ObjectBody, or null.
+		* @example
+		* ```typescript
+		* const body = await api.get(env, "assets/logo.png");
+		* ```
+		*/
+		get: (env, key) => provider(env).get(key),
+		/**
+		* Write an object to the bucket.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param key - Object key.
+		* @param value - Object contents (ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null).
+		* @returns {Promise<R2Object>} The R2Object metadata for the written object.
+		* @example
+		* ```typescript
+		* const obj = await api.put(env, "assets/logo.png", buffer);
+		* ```
+		*/
+		put: (env, key, value) => provider(env).put(key, value),
+		/**
+		* Remove an object (or array of keys) from the bucket. No-op when absent.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param key - Object key or array of keys.
+		* @returns {Promise<void>} Resolves once removed.
+		* @example
+		* ```typescript
+		* await api.delete(env, "assets/old.png");
+		* ```
+		*/
+		delete: (env, key) => provider(env).delete(key),
+		/**
+		* List objects, optionally filtered by R2ListOptions.
+		*
+		* @param env - Per-request Cloudflare bindings.
+		* @param opts - Optional R2ListOptions (prefix, limit, cursor, delimiter).
+		* @returns {Promise<R2Objects>} The R2Objects list result.
+		* @example
+		* ```typescript
+		* const { objects } = await api.list(env, { prefix: "images/" });
+		* ```
+		*/
+		list: (env, opts) => provider(env).list(opts),
+		/**
+		* Return this plugin's deploy metadata. Build-time only — does not touch
+		* `env` or R2. The deploy plugin reads this via `ctx.require(storagePlugin).deployManifest()`.
+		*
+		* @returns {StorageManifest} Deploy manifest entry `{ kind: "r2", bucket, upload }`.
+		* @example
+		* ```typescript
+		* const manifest = api.deployManifest();
+		* // { kind: "r2", bucket: "ASSETS", upload: "./public" }
+		* ```
+		*/
+		deployManifest: () => ({
+			kind: "r2",
+			bucket: ctx.config.bucket,
+			upload: ctx.config.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("storage", {
+	depends: [bindingsPlugin],
+	config: {
+		upload: "",
+		bucket: "ASSETS"
+	},
+	api: createStorageApi
+});
+//#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/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");
+//#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/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 = (0, node_child_process.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 = (0, node_child_process.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/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 = (0, node_child_process.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 || ((0, node_fs.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 last changed path. 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 ? node_path.default.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 last changed path. 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 last changed path 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, p => rebuild(p));
+* handle.close();
+* ```
+*/
+const watchPaths = (globs, debounceMs, onChange) => {
+	let timer;
+	let lastPath = "";
+	const fire = (changedPath) => {
+		lastPath = changedPath;
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			onChange(lastPath);
+		}, debounceMs);
+	};
+	const watchers = [];
+	for (const directory of watchDirectories(globs)) {
+		if (!(0, node_fs.existsSync)(directory)) continue;
+		watchers.push((0, node_fs.watch)(directory, { recursive: true }, (_event, filename) => {
+			if (filename !== null) fire(node_path.default.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 = (0, node_child_process.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 binding to migrate locally, when a d1 plugin is present in the app.
+*
+* @param ctx - The deploy plugin context.
+* @returns The d1 binding name, or undefined when no d1 plugin is present.
+* @example
+* ```ts
+* const binding = d1Binding(ctx); // "DB" | undefined
+* ```
+*/
+const d1Binding = (ctx) => ctx.has("d1") ? ctx.require(d1Plugin).deployManifest().binding : void 0;
+/**
+* Rebuild the site once and announce the result. A failed build keeps the session alive (it just
+* emits dev:error and serves the last good build).
+*
+* @param ctx - The deploy plugin context.
+* @param deps - The injected dev deps.
+* @param changedPath - The path that triggered the rebuild.
+* @param webBuild - Optional call-time web build hook threaded into the rebuild.
+* @returns Resolves once the rebuild attempt completes.
+* @example
+* ```ts
+* await rebuild(ctx, deps, "src/app.tsx", () => web.cli.build());
+* ```
+*/
+const rebuild = async (ctx, deps, changedPath, webBuild) => {
+	ctx.emit("dev:phase", {
+		phase: "rebuild",
+		detail: changedPath
+	});
+	const started = deps.now();
+	try {
+		const { files } = await deps.build(ctx, webBuild);
+		ctx.emit("dev:rebuilt", {
+			files,
+			ms: deps.now() - started
+		});
+	} catch (error) {
+		ctx.emit("dev:error", { message: error instanceof Error ? error.message : String(error) });
+	}
+};
+/**
+* Run a long-lived dev session: cold build → (local d1 migrate) → 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 - Web build hook (re)run on cold build + each change (e.g. `() => web.cli.build()`).
+* @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, webBuild: () => web.cli.build() }, realDevDeps());
+* ```
+*/
+const runDev = async (ctx, opts, deps) => {
+	const port = opts?.port ?? 8787;
+	const webBuild = opts?.webBuild;
+	ctx.emit("dev:phase", {
+		phase: "build",
+		detail: "site"
+	});
+	await deps.build(ctx, webBuild);
+	const binding = d1Binding(ctx);
+	if (ctx.config.migrateLocal && binding !== void 0) {
+		ctx.emit("dev:phase", {
+			phase: "migrate",
+			detail: "d1 (local)"
+		});
+		await deps.runWrangler([
+			"d1",
+			"migrations",
+			"apply",
+			binding,
+			"--local"
+		]);
+	}
+	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, (changedPath) => rebuild(ctx, deps, changedPath, webBuild));
+	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 declared resource already exists in the account, recovering its id
+* (kv/d1) when it does. Durable Objects are config-only (they ship with the script), so they are
+* always treated as "missing" — provisioning them is a no-op that just records the binding.
+*
+* @param resource - The declared 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.binding);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "d1": {
+			const id = existing.d1.get(resource.binding);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "r2": return { exists: existing.r2.has(resource.bucket) };
+		case "queue": return { exists: resource.producers.every((producer) => existing.queue.has(producer)) };
+		case "do": return { exists: false };
+	}
+};
+/**
+* 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 resources.
+* @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 = [];
+	for (const resource of manifest.resources) {
+		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,
+		account: account.name
+	});
+	return {
+		account: account.name,
+		accountId: account.id,
+		exists,
+		missing
+	};
+};
+//#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.binding
+	]));
+	if (manifest.migrations) await runWrangler([
+		"d1",
+		"migrations",
+		"apply",
+		manifest.binding,
+		"--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.binding
+	]));
+	return id ? { id } : {};
+};
+//#endregion
+//#region src/plugins/deploy/providers/queues.ts
+/**
+* @file deploy plugin — Queues provisioning adapter.
+*
+* Creates Cloudflare Queues via `wrangler queues create <name>` for each producer.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Provision queues via `wrangler queues create` for each declared producer.
+*
+* @param manifest - The queue resource descriptor.
+* @param _ci - Whether running non-interactively.
+* @returns Resolves once all queues are created.
+* @example
+* ```ts
+* await provisionQueue({ kind: "queue", producers: ["orders"] }, false);
+* ```
+*/
+const provisionQueue = async (manifest, _ci) => {
+	for (const producer of manifest.producers) await runWrangler([
+		"queues",
+		"create",
+		producer
+	]);
+};
+//#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", bucket: "ASSETS" }, false);
+* ```
+*/
+const provisionR2 = async (manifest, _ci) => {
+	await runWrangler([
+		"r2",
+		"bucket",
+		"create",
+		manifest.bucket
+	]);
+};
+/**
+* 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 (0, node_fs_promises.readdir)(directory);
+	const results = [];
+	for (const entry of entries) {
+		const fullPath = node_path.default.join(directory, entry);
+		if ((await (0, node_fs_promises.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}/${node_path.default.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, else "").
+* @example
+* ```ts
+* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }], { CACHE: "ns123" });
+* ```
+*/
+const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
+	binding: resource.binding,
+	id: ids[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", bucket: "ASSETS" }]);
+* ```
+*/
+const buildR2Buckets = (resources) => resources.filter((resource) => resource.kind === "r2").map((resource) => ({
+	binding: resource.bucket,
+	bucket_name: resource.bucket.toLowerCase()
+}));
+/**
+* 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", binding: "DB" }], { DB: "uuid-1234" });
+* ```
+*/
+const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+	const entry = {
+		binding: resource.binding,
+		database_name: resource.binding.toLowerCase(),
+		database_id: ids[resource.binding] ?? ""
+	};
+	if (resource.migrations) entry.migrations_dir = resource.migrations;
+	return entry;
+});
+/**
+* Build the wrangler `queues` producers section from the manifest's queue resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @returns The queues section, or undefined when there are no queue resources.
+* @example
+* ```ts
+* const q = buildQueues([{ kind: "queue", producers: ["jobs"] }]);
+* ```
+*/
+const buildQueues = (resources) => {
+	const queueResources = resources.filter((resource) => resource.kind === "queue");
+	if (queueResources.length === 0) return void 0;
+	return { producers: queueResources.flatMap((resource) => resource.producers.map((producer) => ({
+		queue: producer,
+		binding: producer.toUpperCase()
+	}))) };
+};
+/**
+* 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", bindings: { Counter: "COUNTER" } }]);
+* ```
+*/
+const buildDurableObjects = (resources) => {
+	const doResources = resources.filter((resource) => resource.kind === "do");
+	if (doResources.length === 0) return void 0;
+	return { bindings: doResources.flatMap((resource) => Object.entries(resource.bindings).map(([className, bindingName]) => ({
+		name: bindingName,
+		class_name: className
+	}))) };
+};
+/**
+* Generate/update the wrangler config file from a manifest (non-destructive merge).
+* If the file exists, its top-level keys are preserved and only deploy-managed keys
+* (name, compatibility_date, kv_namespaces, r2_buckets, d1_databases, queues,
+* durable_objects) are updated.
+*
+* @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 written as "" (e.g. the universal path).
+* @returns Resolves once the file is written.
+* @example
+* ```ts
+* await writeWranglerConfig("wrangler.jsonc", manifest, { CACHE: "ns123", DB: "uuid-1234" });
+* ```
+*/
+const writeWranglerConfig = async (configFile, manifest, ids = {}) => {
+	let existing = {};
+	if ((0, node_fs.existsSync)(configFile)) try {
+		existing = parseJsonc((0, node_fs.readFileSync)(configFile, "utf8"));
+	} catch {
+		existing = {};
+	}
+	const kvNamespaces = buildKvNamespaces(manifest.resources, ids);
+	const r2Buckets = buildR2Buckets(manifest.resources);
+	const d1Databases = buildD1Databases(manifest.resources, ids);
+	const queues = buildQueues(manifest.resources);
+	const durableObjects = buildDurableObjects(manifest.resources);
+	const updated = {
+		...existing,
+		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;
+	await (0, node_fs_promises.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 ((0, node_fs.existsSync)(configFile)) return;
+	const starter = {
+		name: "my-worker",
+		main: "src/worker.ts",
+		compatibility_date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+	};
+	await (0, node_fs_promises.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.
+*/
+/**
+* Derive a human-readable name string from a resource descriptor (used in provision events).
+*
+* @param resource - The resource descriptor.
+* @returns A name suitable for the provision:resource / provision:skip event payload.
+* @example
+* ```ts
+* resourceName({ kind: "kv", binding: "CACHE" }); // "CACHE"
+* ```
+*/
+const resourceName = (resource) => {
+	switch (resource.kind) {
+		case "r2": return resource.bucket;
+		case "do": return Object.values(resource.bindings).join(",");
+		case "queue": return resource.producers.join(",");
+		default: return resource.binding;
+	}
+};
+/**
+* Assemble the deploy manifest from each present resource plugin's OWN deployManifest() api,
+* gated by ctx.has(name) so absent plugins are skipped — never sibling pluginConfigs (F6).
+*
+* @param ctx - The deploy plugin context.
+* @returns The assembled manifest (name, compatibilityDate, resources).
+* @example
+* ```ts
+* const manifest = assembleManifest(ctx);
+* ```
+*/
+const assembleManifest = (ctx) => ({
+	name: ctx.global.name,
+	compatibilityDate: ctx.global.compatibilityDate,
+	resources: [
+		ctx.has("storage") ? ctx.require(storagePlugin).deployManifest() : void 0,
+		ctx.has("kv") ? ctx.require(kvPlugin).deployManifest() : void 0,
+		ctx.has("d1") ? ctx.require(d1Plugin).deployManifest() : void 0,
+		ctx.has("queues") ? ctx.require(queuesPlugin).deployManifest() : void 0,
+		ctx.has("durableObjects") ? ctx.require(durableObjectsPlugin).deployManifest() : void 0
+	].filter((resource) => resource !== void 0)
+});
+/**
+* Act on an infra plan: skip the resources that already exist (reusing their ids), create only
+* the missing ones (capturing each new id), and announce each via provision:skip / :resource.
+*
+* @param ctx - The deploy plugin context.
+* @param plan - The infra plan from planInfra (existing vs missing).
+* @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
+* @returns The provisioning result: created, skipped, and the merged binding → id map.
+* @example
+* ```ts
+* const { ids } = 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)
+		});
+	}
+	const created = [];
+	for (const resource of plan.missing) {
+		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)
+		});
+	}
+	return {
+		created,
+		skipped: plan.exists,
+		ids
+	};
+};
+/**
+* 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. When opts.manifest is supplied
+	* it is used verbatim (universal path).
+	*
+	* @param opts - Optional run options.
+	* @param opts.ci - CI/automated mode: never prompts, auto-confirms every gate. When false (the
+	*   default) and stdout is a TTY, the deploy is guided — each gate is confirmed interactively.
+	*   Falls back to ctx.config.ci when omitted.
+	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+	* @param opts.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
+	* @returns Resolves once the deploy completes.
+	* @example
+	* ```ts
+	* await api.run({ webBuild: () => web.cli.build() }); // guided on a TTY
+	* await api.run({ ci: true, manifest: { name: "w", compatibilityDate: "2026-06-17", resources: [] } });
+	* ```
+	*/
+	async run(opts) {
+		const ci = opts?.ci ?? ctx.config.ci;
+		const confirm = !ci && stdoutIsTty() ? (0, _moku_labs_common_cli.createBrandPrompts)().confirm : async (_question) => true;
+		ctx.emit("deploy:phase", { phase: "auth" });
+		await verifyAuth(ctx);
+		const webBuild = opts?.webBuild ?? ctx.config.webBuild;
+		if (webBuild !== void 0) {
+			ctx.emit("deploy:phase", {
+				phase: "build",
+				detail: "web"
+			});
+			await webBuild();
+		}
+		ctx.emit("deploy:phase", { phase: "detect" });
+		const manifest = opts?.manifest ?? assembleManifest(ctx);
+		ctx.emit("deploy:phase", { phase: "provision" });
+		const plan = await planInfra(ctx, manifest);
+		if (plan.missing.length > 0 && !await confirm(`Create ${plan.missing.length} missing resource(s) in "${plan.account}"?`)) {
+			ctx.emit("deploy:phase", { phase: "aborted" });
+			return;
+		}
+		const { ids } = await applyPlan(ctx, plan, ci);
+		ctx.emit("deploy:phase", { phase: "wrangler-config" });
+		await writeWranglerConfig(ctx.config.configFile, manifest, ids);
+		const r2Resource = manifest.resources.find((resource) => resource.kind === "r2");
+		if (r2Resource?.upload) {
+			const count = await uploadDirToR2(r2Resource.bucket, r2Resource.upload);
+			ctx.emit("deploy:phase", {
+				phase: "upload",
+				detail: `${String(count)} files`
+			});
+		}
+		if (!await confirm(`Deploy "${manifest.name}" to ${ctx.global.stage}?`)) {
+			ctx.emit("deploy:phase", { phase: "aborted" });
+			return;
+		}
+		ctx.emit("deploy:phase", { phase: "deploy" });
+		const url = await runWrangler([
+			"deploy",
+			"--config",
+			ctx.config.configFile
+		]);
+		ctx.emit("deploy:complete", { url });
+	},
+	/**
+	* 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.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
+	* @returns Resolves when the dev session ends.
+	* @example
+	* ```ts
+	* await api.dev({ port: 8787, webBuild: () => web.cli.build() });
+	* ```
+	*/
+	dev: (opts) => runDev(ctx, opts, realDevDeps()),
+	/**
+	* 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)),
+	/**
+	* 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)),
+	/**
+	* 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)),
+	/**
+	* 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("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).
+*
+* `dev` resolves its port from the command line (`bun scripts/dev.ts --port 3000`) so a consumer
+* never hardcodes it in the app. Pure: takes an argv array, reads no globals. Node-only tooling.
+*/
+/** The valid TCP port range a `--port` value must fall within to be accepted. */
+const MAX_PORT = 65535;
+/**
+* Extract a `--port`/`-p` 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 `--port 3000` spaced form).
+* @returns The raw string value when this token is a port flag, else undefined.
+* @example
+* ```ts
+* portValueFrom("--port=3000", undefined); // "3000"
+* portValueFrom("--port", "3000");         // "3000"
+* portValueFrom("--config", "x");          // undefined
+* ```
+*/
+const portValueFrom = (token, next) => {
+	const inline = /^(?:--port|-p)=(.+)$/u.exec(token);
+	if (inline) return inline[1];
+	if (token === "--port" || token === "-p") return next;
+};
+/**
+* Parse a `--port <n>` / `--port=<n>` / `-p <n>` flag out of an argv array.
+*
+* Returns the first valid port (a positive integer ≤ 65535) found, or undefined when the flag is
+* absent or its value is not a usable port — letting the caller fall back to a default.
+*
+* @param argv - The argv array to scan (the caller passes the process argv).
+* @returns The parsed port number, or undefined when no valid `--port`/`-p` flag is present.
+* @example
+* ```ts
+* parsePortArg(["bun", "scripts/dev.ts", "--port", "3000"]); // 3000
+* parsePortArg(["bun", "scripts/dev.ts", "--port=3000"]);    // 3000
+* parsePortArg(["bun", "scripts/dev.ts"]);                   // undefined
+* ```
+*/
+const parsePortArg = (argv) => {
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index];
+		if (token === void 0) continue;
+		const raw = portValueFrom(token, argv[index + 1]);
+		if (raw === void 0) continue;
+		const port = Number(raw);
+		if (Number.isInteger(port) && port > 0 && port <= MAX_PORT) return port;
+	}
+};
+//#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. Resolves the port from `opts.port`, else a `--port <n>` CLI flag, else
+	* `ctx.config.port` (8787). 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. Overrides the `--port` flag and the default.
+	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
+	* @returns Resolves when the dev session ends.
+	* @example
+	* ```ts
+	* await api.dev({ webBuild: () => web.cli.build() }); // port from --port or 8787
+	* ```
+	*/
+	async dev(opts) {
+		const ui = (0, _moku_labs_common_cli.createBrandConsole)();
+		ui.lockup({
+			wordmark: "moku worker",
+			label: "dev session"
+		});
+		const port = opts?.port ?? parsePortArg(process.argv) ?? ctx.config.port;
+		try {
+			await ctx.require(deployPlugin).dev(opts?.webBuild ? {
+				port,
+				webBuild: opts.webBuild
+			} : { port });
+			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. Guided/interactive by
+	* default; `{ ci: true }` runs the automated path (CI). A `webBuild` hook builds the web site
+	* first (before `wrangler deploy`). A failure renders a branded `✗` line + 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.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
+	* @returns Resolves once the deploy completes (or after a failure is rendered).
+	* @example
+	* ```ts
+	* await api.deploy({ webBuild: () => web.cli.build() });           // guided
+	* await api.deploy({ ci: true, webBuild: () => web.cli.build() }); // CI
+	* ```
+	*/
+	async deploy(opts) {
+		try {
+			await ctx.require(deployPlugin).run(opts);
+		} catch (error) {
+			(0, _moku_labs_common_cli.createBrandConsole)().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 = (0, _moku_labs_common_cli.createBrandConsole)();
+		if (sub === "setup") {
+			for (const line of deploy.tokenInstructions().split("\n")) ui.line(line);
+			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 = (0, _moku_labs_common_cli.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 = (0, _moku_labs_common_cli.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) {
+		(0, _moku_labs_common_cli.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)}`;
+/**
+* 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 three global deploy events.
+* @example
+* ```ts
+* const hooks = createCliHooks(ctx);
+* hooks["deploy:phase"]({ phase: "detect" }); // logs "detect" → renders "  › detect"
+* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "kv KV" → "  › kv KV"
+* hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // "deployed → https://x.workers.dev"
+* ```
+*/
+const createCliHooks = (ctx) => {
+	const ui = (0, _moku_labs_common_cli.createBrandConsole)();
+	return {
+		/**
+		* Log one clean line per pipeline phase: "phase" or "phase · detail".
+		*
+		* @param p - The deploy:phase event payload.
+		* @example
+		* ```ts
+		* handler({ phase: "detect" }); // "detect"
+		* handler({ phase: "upload", detail: "3 files" }); // "upload · 3 files"
+		* ```
+		*/
+		"deploy:phase"(p) {
+			ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
+		},
+		/**
+		* Log the infra preflight summary: "infra · N exist, M to create · account".
+		*
+		* @param p - The provision:plan event payload.
+		* @example
+		* ```ts
+		* handler({ exists: 2, missing: 1, account: "Play Co" }); // "infra · 2 exist, 1 to create · Play Co"
+		* ```
+		*/
+		"provision:plan"(p) {
+			ctx.log.info(`infra · ${p.exists} exist, ${p.missing} to create · ${p.account}`);
+		},
+		/**
+		* Log one clean line per provisioned resource: "kind name".
+		*
+		* @param p - The provision:resource event payload.
+		* @example
+		* ```ts
+		* handler({ kind: "kv", name: "KV" }); // "kv KV"
+		* ```
+		*/
+		"provision:resource"(p) {
+			ctx.log.info(`${p.kind} ${p.name}`);
+		},
+		/**
+		* Log one clean line per already-existing resource (skipped): "kind name (exists)".
+		*
+		* @param p - The provision:skip event payload.
+		* @example
+		* ```ts
+		* handler({ kind: "kv", name: "KV" }); // "kv KV (exists)"
+		* ```
+		*/
+		"provision:skip"(p) {
+			ctx.log.info(`${p.kind} ${p.name} (exists)`);
+		},
+		/**
+		* 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);
+		},
+		/**
+		* Log the terminal success line with the deployed URL.
+		*
+		* @param p - The deploy:complete event payload.
+		* @example
+		* ```ts
+		* handler({ url: "https://my-worker.workers.dev" }); // "deployed → https://my-worker.workers.dev"
+		* ```
+		*/
+		"deploy:complete"(p) {
+			ctx.log.info(`deployed → ${p.url}`);
+		}
+	};
+};
+/**
+* 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("cli", {
+	depends: [deployPlugin],
+	config: { port: 8787 },
+	onInit: (ctx) => {
+		ctx.log.clearSinks();
+		ctx.log.addSink((0, _moku_labs_common_cli.brandedSink)("info"));
+	},
+	api: (ctx) => createCliApi(ctx),
+	hooks: (ctx) => createCliHooks(ctx)
+});
+//#endregion
+Object.defineProperty(exports, "bindingsPlugin", {
+	enumerable: true,
+	get: function() {
+		return bindingsPlugin;
+	}
+});
+Object.defineProperty(exports, "cliPlugin", {
+	enumerable: true,
+	get: function() {
+		return cliPlugin;
+	}
+});
+Object.defineProperty(exports, "coreConfig", {
+	enumerable: true,
+	get: function() {
+		return coreConfig;
+	}
+});
+Object.defineProperty(exports, "createCore", {
+	enumerable: true,
+	get: function() {
+		return createCore;
+	}
+});
+Object.defineProperty(exports, "createPlugin", {
+	enumerable: true,
+	get: function() {
+		return createPlugin;
+	}
+});
+Object.defineProperty(exports, "d1Plugin", {
+	enumerable: true,
+	get: function() {
+		return d1Plugin;
+	}
+});
+Object.defineProperty(exports, "defineDurableObject", {
+	enumerable: true,
+	get: function() {
+		return defineDurableObject;
+	}
+});
+Object.defineProperty(exports, "deployPlugin", {
+	enumerable: true,
+	get: function() {
+		return deployPlugin;
+	}
+});
+Object.defineProperty(exports, "durableObjectsPlugin", {
+	enumerable: true,
+	get: function() {
+		return durableObjectsPlugin;
+	}
+});
+Object.defineProperty(exports, "kvPlugin", {
+	enumerable: true,
+	get: function() {
+		return kvPlugin;
+	}
+});
+Object.defineProperty(exports, "queuesPlugin", {
+	enumerable: true,
+	get: function() {
+		return queuesPlugin;
+	}
+});
+Object.defineProperty(exports, "stagePlugin", {
+	enumerable: true,
+	get: function() {
+		return stagePlugin;
+	}
+});
+Object.defineProperty(exports, "storagePlugin", {
+	enumerable: true,
+	get: function() {
+		return storagePlugin;
+	}
+});