@moku-labs/worker 0.5.0 → 0.6.0

package/dist/cli-DgZv5A0G.mjs

@@ -0,0 +1,2888 @@
+import { envPlugin, logPlugin } from "@moku-labs/common";
+import { createCoreConfig, createCorePlugin } from "@moku-labs/core";
+import { brandedSink, createBrandConsole, createBrandPrompts } from "@moku-labs/common/cli";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, watch } from "node:fs";
+import path from "node:path";
+import { readdir, stat, writeFile } from "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 = createCorePlugin("stage", {
+	config: { stage: "production" },
+	/**
+	* Builds the stage accessor surface from the resolved stage.
+	*
+	* @param ctx - Core plugin context (spec/02 §6 — `{ config, state }` only;
+	*   no `global`, `emit`, or `require`). `state` is unused by this plugin.
+	* @param ctx.config - The resolved plugin config containing the deployment stage.
+	* @returns The `ctx.stage` API: `isDev`, `isProduction`, `current`.
+	* @example
+	* ```typescript
+	* const api = stagePlugin.spec.api({ config: { stage: "development" }, state: {} });
+	* api.isDev(); // true
+	* ```
+	*/
+	api: ({ config }) => ({
+		/**
+		* Whether this Worker runs in the development stage.
+		*
+		* @returns True iff `stage === "development"`.
+		* @example
+		* ```typescript
+		* if (ctx.stage.isDev()) return Response.json({ stack: err.stack });
+		* ```
+		*/
+		isDev: () => config.stage === "development",
+		/**
+		* Whether this Worker runs in the production stage. Note: false in "test".
+		*
+		* @returns True iff `stage === "production"`.
+		* @example
+		* ```typescript
+		* const cc = ctx.stage.isProduction() ? "public, max-age=31536000" : "no-store";
+		* ```
+		*/
+		isProduction: () => config.stage === "production",
+		/**
+		* The raw deployment stage, as the literal union (not `string`).
+		*
+		* @returns The resolved stage.
+		* @example
+		* ```typescript
+		* ctx.log.info("startup", { stage: ctx.stage.current() });
+		* ```
+		*/
+		current: () => config.stage
+	})
+});
+const coreConfig = createCoreConfig("moku-worker", {
+	config: {
+		stage: "production",
+		name: "moku-worker",
+		compatibilityDate: ""
+	},
+	plugins: [
+		logPlugin,
+		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 = spawn("wrangler", args, {
+		env: { ...process.env },
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	child.stdout.on("data", (chunk) => {
+		chunks.push(chunk);
+	});
+	child.stderr.on("data", (chunk) => {
+		errChunks.push(chunk);
+	});
+	child.on("error", (err) => {
+		reject(/* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${err.message}`));
+	});
+	child.on("close", (code) => {
+		const stdout = Buffer.concat(chunks).toString("utf8");
+		const stderr = Buffer.concat(errChunks).toString("utf8");
+		if (code !== 0) {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] wrangler exited with code ${String(code)}.\n  ${stderr || stdout}`));
+			return;
+		}
+		resolve(args[0] === "deploy" ? extractDeployedUrl(stdout) : stdout);
+	});
+});
+/**
+* Spawn `wrangler` with the given args, inheriting stdio so its output streams live to the user's
+* terminal (used by the generic passthrough and long-lived commands like `tail`).
+*
+* @param args - Wrangler CLI arguments (e.g. ["kv", "namespace", "list"]).
+* @returns Resolves once wrangler exits successfully.
+* @throws {Error} When wrangler cannot be spawned or exits non-zero.
+* @example
+* ```ts
+* await runWranglerInherit(["kv", "namespace", "list"]);
+* ```
+*/
+const runWranglerInherit = (args) => {
+	return new Promise((resolve, reject) => {
+		const child = spawn("wrangler", args, { stdio: "inherit" });
+		child.on("error", (error) => {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`[moku-worker] wrangler exited with code ${String(code)}.`));
+		});
+	});
+};
+//#endregion
+//#region src/plugins/deploy/dev/build.ts
+/**
+* @file deploy plugin — dev site-rebuild resolution.
+*
+* Resolves HOW to rebuild the Moku web site on change: the in-process `webBuild` hook (preferred,
+* fast, typed — passed call-time from the consumer's script or set as a config default) → a
+* `buildCommand` shell string → an auto-detected `scripts/build.ts`. When nothing is configured,
+* dev serves the worker only and says so. Subprocesses inherit the parent env by default.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Convention build script auto-detected when no webBuild/buildCommand is configured. */
+const AUTO_DETECT = "scripts/build.ts";
+/**
+* Opportunistically read a numeric `files` count off an arbitrary web build result. A real web
+* build returns its own summary shape (the worker framework cannot know it), so anything without a
+* numeric `files` field reports 0.
+*
+* @param result - The resolved value of a {@link WebBuild} hook (any shape).
+* @returns The `files` count when present and numeric, else 0.
+* @example
+* ```ts
+* fileCountOf({ files: 12 }); // 12
+* fileCountOf({ outDir: "dist", pageCount: 4 }); // 0
+* ```
+*/
+const fileCountOf = (result) => {
+	if (typeof result === "object" && result !== null && "files" in result) {
+		const { files } = result;
+		return typeof files === "number" ? files : 0;
+	}
+	return 0;
+};
+/**
+* Run a shell build command, resolving on a zero exit and rejecting otherwise.
+*
+* @param command - The shell command to run (the consumer's own configured build).
+* @returns Resolves once the command exits successfully.
+* @throws {Error} When the command fails to start or exits non-zero.
+* @example
+* ```ts
+* await runShellBuild("bun run scripts/build.ts");
+* ```
+*/
+const runShellBuild = (command) => {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, {
+			shell: true,
+			stdio: "inherit"
+		});
+		child.on("error", (error) => {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] site build failed to start.\n  ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`[moku-worker] site build exited with code ${String(code)}.`));
+		});
+	});
+};
+/**
+* Rebuild the Moku web site using the resolved strategy: the call-time `webBuild` hook (the
+* script-driven path), else the `webBuild` config default, else the `buildCommand` shell string,
+* else an auto-detected `scripts/build.ts`. A hook's result is normalized to a `{ files }` count
+* (0 when the hook reports none, and for the shell path where it is unknown).
+*
+* @param ctx - The deploy plugin context (config + emit).
+* @param webBuild - Optional call-time web build hook (takes precedence over `ctx.config.webBuild`).
+* @returns The rebuilt file count (0 for the shell path / a countless hook).
+* @throws {Error} When the resolved shell build fails.
+* @example
+* ```ts
+* const { files } = await buildSite(ctx, () => web.cli.build());
+* ```
+*/
+const buildSite = async (ctx, webBuild) => {
+	const hook = webBuild ?? ctx.config.webBuild;
+	if (hook !== void 0) return { files: fileCountOf(await hook()) };
+	const command = ctx.config.buildCommand || (existsSync(AUTO_DETECT) ? `bun run ${AUTO_DETECT}` : "");
+	if (command === "") {
+		ctx.emit("dev:error", { message: "No site build configured (pass webBuild or set buildCommand); serving worker only." });
+		return { files: 0 };
+	}
+	await runShellBuild(command);
+	return { files: 0 };
+};
+//#endregion
+//#region src/plugins/deploy/dev/watch.ts
+/**
+* @file deploy plugin — debounced filesystem watcher for dev.
+*
+* Watches the top-level directories implied by the config globs (recursive) and fires a debounced
+* change callback with the 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 ? path.dirname(glob) : glob.slice(0, globStart)).split(/[/\\]/u).find((segment) => segment !== "") ?? ".";
+		directories.add(top);
+	}
+	return [...directories];
+};
+/**
+* Watch the directories implied by `globs` and fire `onChange` (debounced by `debounceMs`) with
+* the 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 (!existsSync(directory)) continue;
+		watchers.push(watch(directory, { recursive: true }, (_event, filename) => {
+			if (filename !== null) fire(path.join(directory, filename.toString()));
+		}));
+	}
+	return { close: () => {
+		if (timer !== void 0) clearTimeout(timer);
+		for (const watcher of watchers) watcher.close();
+	} };
+};
+//#endregion
+//#region src/plugins/deploy/dev/runner.ts
+/**
+* @file deploy plugin — dev watch/recompile orchestrator.
+*
+* One long-lived session: cold-build the Moku site, optionally apply local D1 migrations, spawn
+* `wrangler dev --live-reload` ONCE, then watch the site sources and rebuild on change (wrangler's
+* asset server live-reloads the browser). Build failures keep the session serving the last good
+* build. Tears down cleanly on SIGINT. Side-effecting work is injected via DevDeps so the
+* orchestration is unit-testable without real processes, watchers, or signals.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Grace period (ms) before escalating a hung `wrangler dev` shutdown from SIGINT to SIGKILL. */
+const STOP_GRACE_MS = 4e3;
+/**
+* Spawn the long-lived `wrangler dev` child (inherits the parent env; non-blocking).
+*
+* `whenExited` settles when the child exits OR fails to spawn — the `error` listener is essential:
+* a missing/unexecutable wrangler emits `error` (not `exit`), which is otherwise unhandled (crashes
+* the process) and would leave `whenExited` pending forever, hanging `stop()`. `stop()` shuts
+* wrangler down the way its own Ctrl+C does — a graceful SIGINT, then a SIGKILL escalation if it has
+* not exited within {@link STOP_GRACE_MS} — resolving only once it is gone; a spawn failure is
+* surfaced as a thrown branded error so the caller can render it. Without the wait, the
+* inherited-stdio child can keep the parent alive after the watcher closes ("stuck on stopping").
+*
+* @param args - The `wrangler dev …` arguments.
+* @returns A handle: `whenExited` (settles on exit/spawn-failure) and `stop()` (resolves once gone).
+* @example
+* ```ts
+* const child = spawnWranglerDev(["dev", "--port", "8787"]);
+* await Promise.race([untilSignal(), child.whenExited]);
+* await child.stop();
+* ```
+*/
+const spawnWranglerDev = (args) => {
+	const child = spawn("wrangler", args, { stdio: "inherit" });
+	let spawnError;
+	const whenExited = new Promise((resolve) => {
+		child.once("exit", () => {
+			resolve();
+		});
+		child.once("error", (error) => {
+			spawnError = /* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${error.message}`);
+			resolve();
+		});
+	});
+	const stop = async () => {
+		if (spawnError !== void 0) throw spawnError;
+		if (child.exitCode !== null || child.signalCode !== null || child.pid === void 0) return;
+		child.kill("SIGINT");
+		const forceKill = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+		await whenExited;
+		clearTimeout(forceKill);
+	};
+	return {
+		stop,
+		whenExited
+	};
+};
+/**
+* Resolve when the user first interrupts the dev session (SIGINT).
+*
+* @returns A promise that settles on the first SIGINT.
+* @example
+* ```ts
+* await waitForSigint();
+* ```
+*/
+const waitForSigint = () => {
+	return new Promise((resolve) => {
+		process.once("SIGINT", () => {
+			resolve();
+		});
+	});
+};
+/**
+* Wall-clock timestamp in ms (extracted so realDevDeps holds only named references).
+*
+* @returns The current time in milliseconds.
+* @example
+* ```ts
+* const t = nowMs();
+* ```
+*/
+const nowMs = () => Date.now();
+/**
+* Build the real (side-effecting) dev deps used by api.dev(). Subprocesses inherit the parent env.
+*
+* @returns The production DevDeps (real spawn / fs.watch / SIGINT / Date.now).
+* @example
+* ```ts
+* await runDev(ctx, opts, realDevDeps());
+* ```
+*/
+const realDevDeps = () => ({
+	build: buildSite,
+	runWrangler,
+	spawnDev: spawnWranglerDev,
+	watch: watchPaths,
+	untilSignal: waitForSigint,
+	now: nowMs
+});
+/**
+* The d1 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 readdir(directory);
+	const results = [];
+	for (const entry of entries) {
+		const fullPath = path.join(directory, entry);
+		if ((await stat(fullPath)).isDirectory()) {
+			const nested = await walkDir(fullPath);
+			results.push(...nested);
+		} else results.push(fullPath);
+	}
+	return results;
+};
+/**
+* Upload a directory to an R2 bucket and return the uploaded file count.
+* Each file is uploaded via `wrangler r2 object put <bucket>/<key> --file <path>`.
+*
+* @param bucket - The R2 bucket binding name.
+* @param directory - The directory to upload.
+* @returns The number of files uploaded.
+* @example
+* ```ts
+* const count = await uploadDirToR2("ASSETS", "./public");
+* ```
+*/
+const uploadDirToR2 = async (bucket, directory) => {
+	const files = await walkDir(directory);
+	for (const filePath of files) await runWrangler([
+		"r2",
+		"object",
+		"put",
+		`${bucket}/${path.relative(directory, filePath)}`,
+		"--file",
+		filePath
+	]);
+	return files.length;
+};
+//#endregion
+//#region src/plugins/deploy/providers/index.ts
+/**
+* Dispatch a resource descriptor to the matching provider's provisioning routine.
+*
+* @param resource - The resource descriptor to provision.
+* @param ci - Whether running non-interactively.
+* @returns The provisioning outcome — `{ id }` for kv/d1, `{}` for r2/queue/do.
+* @example
+* ```ts
+* const { id } = await provisionResource({ kind: "kv", binding: "CACHE" }, false);
+* await provisionResource({ kind: "r2", bucket: "ASSETS" }, false); // {}
+* ```
+*/
+const provisionResource = async (resource, ci) => {
+	switch (resource.kind) {
+		case "kv": return provisionKv(resource, ci);
+		case "d1": return provisionD1(resource, ci);
+		case "r2":
+			await provisionR2(resource, ci);
+			return {};
+		case "queue":
+			await provisionQueue(resource, ci);
+			return {};
+		case "do":
+			await provisionDurableObject(resource, ci);
+			return {};
+	}
+};
+//#endregion
+//#region src/plugins/deploy/tty.ts
+/**
+* @file deploy plugin — TTY detection (isolated so the guided flow is testable).
+*
+* The guided deploy only prompts on an interactive terminal; in a pipe or CI it must never block
+* on stdin. Kept in its own module so tests can mock it without stubbing `process.stdout`.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Whether stdout is an interactive TTY (so prompts are safe to show).
+*
+* @returns True when stdout is a terminal.
+* @example
+* ```ts
+* if (stdoutIsTty()) await prompts.confirm("Deploy?");
+* ```
+*/
+const stdoutIsTty = () => process.stdout.isTTY === true;
+//#endregion
+//#region src/plugins/deploy/wrangler-config.ts
+/**
+* @file deploy plugin — wrangler config generation + scaffold.
+*
+* Provides two exports:
+* - `writeWranglerConfig`: generates/updates a wrangler.jsonc file from an ExternalManifest.
+*   Non-destructive: preserves existing top-level keys not managed by deploy.
+* - `scaffoldWranglerAndCi`: creates a minimal starter wrangler config when the file does not
+*   exist yet; idempotent (leaves existing files untouched).
+*
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Strip JSONC line- and block-comments, then JSON.parse the result.
+*
+* @param source - Raw JSONC file contents.
+* @returns The parsed object.
+* @example
+* ```ts
+* const cfg = parseJsonc('{ "name": "w" } // trailing comment');
+* ```
+*/
+const parseJsonc = (source) => {
+	const stripped = source.replaceAll(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/gu, "");
+	return JSON.parse(stripped);
+};
+/**
+* Build the wrangler `kv_namespaces` array from the manifest's kv resources.
+*
+* @param resources - All resource descriptors from the manifest.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `id` is filled from here.
+* @returns One wrangler KV namespace entry per kv resource (real `id` when known, 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 (existsSync(configFile)) try {
+		existing = parseJsonc(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 writeFile(configFile, JSON.stringify(updated, void 0, 2));
+};
+/**
+* Scaffold a starting wrangler config and, when ci is set, CI workflow files.
+* Idempotent: an existing config file is left completely untouched.
+*
+* @param configFile - Path to the wrangler config file.
+* @param _ci - Whether to also scaffold CI workflow files.
+* @returns Resolves once scaffolding is written.
+* @example
+* ```ts
+* await scaffoldWranglerAndCi("wrangler.jsonc", true);
+* ```
+*/
+const scaffoldWranglerAndCi = async (configFile, _ci) => {
+	if (existsSync(configFile)) return;
+	const starter = {
+		name: "my-worker",
+		main: "src/worker.ts",
+		compatibility_date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+	};
+	await writeFile(configFile, JSON.stringify(starter, void 0, 2));
+};
+//#endregion
+//#region src/plugins/deploy/api.ts
+/**
+* @file deploy plugin — API factory (run, dev, init, checkInfra, provisionInfra).
+*
+* Pure ctx-taking factory. Assembles the deploy manifest from each resource plugin's own
+* deployManifest() api (never sibling pluginConfigs — design F6), runs an infra preflight
+* (check-before-create + capture real ids), generates/updates the wrangler config, uploads the
+* R2 upload dir, and runs wrangler deploy. Emits only global events: deploy:phase,
+* deploy:complete, provision:resource, provision:plan, provision:skip.
+*
+* Node-only: uses node:child_process (via runner.ts), node:fs (via wrangler-config.ts), and the
+* Cloudflare REST API (via infra/). Never called in the deployed Worker runtime.
+*/
+/**
+* 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() ? 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 = 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) {
+			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 = 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 = createBrandConsole();
+		ui.heading("doctor");
+		let tokenOk = false;
+		try {
+			const status = await deploy.verifyAuth();
+			tokenOk = true;
+			ui.check(true, "token", `valid · account "${status.account}" (${status.accountId})`);
+		} catch (error) {
+			ui.check(false, "token", error instanceof Error ? error.message : String(error));
+		}
+		if (!tokenOk) {
+			ui.line("Run `auth setup` for the exact token to create.");
+			return;
+		}
+		try {
+			const plan = await deploy.checkInfra();
+			ui.check(true, "infra", `${plan.exists.length} exist, ${plan.missing.length} to create in "${plan.account}"`);
+		} catch (error) {
+			ui.check(false, "infra", error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* Print the resolved Cloudflare account for the current `.env` token.
+	*
+	* @returns Resolves once the account summary is printed.
+	* @example
+	* ```ts
+	* await api.whoami();
+	* ```
+	*/
+	async whoami() {
+		const ui = createBrandConsole();
+		try {
+			const status = await ctx.require(deployPlugin).verifyAuth();
+			ui.check(true, "account", `${status.account} (${status.accountId})`);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* Run an arbitrary wrangler command through the branded CLI (escape hatch). Streams its output.
+	*
+	* @param args - The wrangler arguments.
+	* @returns Resolves once wrangler exits.
+	* @example
+	* ```ts
+	* await api.wrangler(["kv", "namespace", "list"]);
+	* ```
+	*/
+	async wrangler(args) {
+		createBrandConsole().heading(`wrangler ${args.join(" ")}`);
+		await ctx.require(deployPlugin).wrangler(args);
+	}
+});
+//#endregion
+//#region src/plugins/cli/handlers.ts
+/** Divider drawn before the native `wrangler dev` TUI so the moku preamble reads as one section. */
+const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
+/**
+* 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 = 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(brandedSink("info"));
+	},
+	api: (ctx) => createCliApi(ctx),
+	hooks: (ctx) => createCliHooks(ctx)
+});
+//#endregion
+export { kvPlugin as a, d1Plugin as c, createCore as d, createPlugin as f, queuesPlugin as i, bindingsPlugin as l, deployPlugin as n, durableObjectsPlugin as o, stagePlugin as p, storagePlugin as r, defineDurableObject as s, cliPlugin as t, coreConfig as u };