@moku-labs/worker 0.7.0 → 0.7.2

package/dist/{cli-C8DdTtzn.cjs → cli-BPnG_JGR.cjs}

@@ -761,7 +761,8 @@ const createQueuesApi = (ctx) => {
 		deployManifest: () => Object.values(ctx.config).map((instance) => ({
 			kind: "queue",
 			name: instance.name,
-			binding: instance.binding
+			binding: instance.binding,
+			...instance.onMessage ? { consumer: true } : {}
 		}))
 	};
 };
@@ -1983,8 +1984,9 @@ const runDev = async (ctx, opts, deps) => {
 //#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.
+* (kv/d1) when it does. Durable Objects are config-only — they ship with the Worker (`wrangler
+* deploy` + the auto-derived DO migration create the namespace), never provisioned via the API — so
+* they are treated as already EXISTING, and the plan never re-offers to "create" them each deploy.
 *
 * @param resource - The declared resource descriptor.
 * @param existing - The indexed set of resources already in the account.
@@ -2012,7 +2014,7 @@ const checkExisting = (resource, existing) => {
 		}
 		case "r2": return { exists: existing.r2.has(resource.name) };
 		case "queue": return { exists: existing.queue.has(resource.name) };
-		case "do": return { exists: false };
+		case "do": return { exists: true };
 	}
 };
 /**
@@ -2527,16 +2529,20 @@ const parseJsonc = (source) => {
 *
 * @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 "").
+* @returns One wrangler KV namespace entry per kv resource — real `id` when known, omitted otherwise
+*   (wrangler rejects an empty `id`, but a local-dev / freshly-generated config validates without one).
 * @example
 * ```ts
 * const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }], { CACHE: "ns123" });
 * ```
 */
-const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
-	binding: resource.binding,
-	id: ids[resource.binding] ?? ""
-}));
+const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => {
+	const id = ids[resource.binding];
+	return id ? {
+		binding: resource.binding,
+		id
+	} : { binding: resource.binding };
+});
 /**
 * Build the wrangler `r2_buckets` array from the manifest's r2 resources.
 *
@@ -2563,31 +2569,41 @@ const buildR2Buckets = (resources) => resources.filter((resource) => resource.ki
 * ```
 */
 const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+	const databaseId = ids[resource.binding];
 	const entry = {
 		binding: resource.binding,
-		database_name: resource.name,
-		database_id: ids[resource.binding] ?? ""
+		database_name: resource.name
 	};
+	if (databaseId) entry.database_id = databaseId;
 	if (resource.migrations) entry.migrations_dir = resource.migrations;
 	return entry;
 });
 /**
-* Build the wrangler `queues` producers section from the manifest's queue resources.
+* Build the wrangler `queues` section (producers + consumers) from the manifest's queue resources.
+* Every queue is a `producer`; a queue flagged `consumer: true` (it declares an `onMessage` handler)
+* is ALSO registered as a `consumer` so wrangler delivers its messages to this Worker's queue()
+* handler — both locally under `wrangler dev` and in production. Without the consumer entry the
+* handler never runs (the bug that silently drops a queue-driven activity feed).
 *
 * @param resources - All resource descriptors from the manifest.
-* @returns The queues section, or undefined when there are no queue resources.
+* @returns The queues section (producers, plus consumers when any), or undefined when there are none.
 * @example
 * ```ts
-* const q = buildQueues([{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }]);
+* const q = buildQueues([{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY", consumer: true }]);
 * ```
 */
 const buildQueues = (resources) => {
 	const queueResources = resources.filter((resource) => resource.kind === "queue");
 	if (queueResources.length === 0) return void 0;
-	return { producers: queueResources.map((resource) => ({
+	const producers = queueResources.map((resource) => ({
 		queue: resource.name,
 		binding: resource.binding
-	})) };
+	}));
+	const consumers = queueResources.filter((resource) => resource.consumer === true).map((resource) => ({ queue: resource.name }));
+	return consumers.length > 0 ? {
+		producers,
+		consumers
+	} : { producers };
 };
 /**
 * Build the wrangler `durable_objects` bindings section from the manifest's do resources.
@@ -2695,7 +2711,8 @@ const wranglerExtra = (config) => {
 * @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).
+*   to an empty map, in which case `id`/`database_id` are OMITTED (not "") so the generated config
+*   still validates for local `dev` (wrangler rejects an empty id); a deploy fills the real ids.
 * @param extra - Extra top-level wrangler keys to merge in (the app's `deploy.wrangler` config).
 * @returns Resolves once the file is written.
 * @example
@@ -3070,6 +3087,32 @@ const guidedUpload = async (ctx, manifest, deps) => {
 	return true;
 };
 /**
+* The final deploy step: confirm the target (guided only), run `wrangler deploy` with interactive
+* retry, then emit deploy:complete. Resolves false when the target gate or a deploy retry is declined.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param stage - The resolved deploy stage (for the confirm prompt).
+* @param deps - Interactivity + the confirm prompt.
+* @returns True once deployed; false when the user declined the gate or a retry (abort).
+* @example
+* ```ts
+* if (!(await guidedDeployStep(ctx, manifest, stage, deps))) return emitAborted(ctx);
+* ```
+*/
+const guidedDeployStep = async (ctx, manifest, stage, deps) => {
+	if (!await deps.confirm(`Deploy "${manifest.name}" to ${stage}?`)) return false;
+	ctx.emit("deploy:phase", { phase: "deploy" });
+	const url = await guidedStep(() => runWrangler([
+		"deploy",
+		"--config",
+		ctx.config.configFile
+	]), HINTS.deploy, deps);
+	if (url === ABORTED) return false;
+	ctx.emit("deploy:complete", { url });
+	return true;
+};
+/**
 * 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.
@@ -3111,10 +3154,9 @@ const createDeployApi = (ctx) => ({
 		const ci = opts?.ci ?? ctx.config.ci;
 		const stage = opts?.stage ?? ctx.global.stage;
 		const interactive = !ci && stdoutIsTty();
-		const confirm = interactive ? (0, _moku_labs_common_cli.createBrandPrompts)().confirm : async (_question) => true;
 		const deps = {
 			interactive,
-			confirm
+			confirm: interactive ? (0, _moku_labs_common_cli.createBrandPrompts)().confirm : async (_question) => true
 		};
 		ctx.emit("deploy:phase", { phase: "auth" });
 		if (!await guidedAuth(ctx, deps)) return emitAborted(ctx);
@@ -3127,15 +3169,7 @@ const createDeployApi = (ctx) => ({
 		ctx.emit("deploy:phase", { phase: "wrangler-config" });
 		await writeWranglerConfig(ctx.config.configFile, manifest, provisioned.ids, wranglerExtra(ctx.config));
 		if (!await guidedUpload(ctx, manifest, deps)) return emitAborted(ctx);
-		if (!await confirm(`Deploy "${manifest.name}" to ${stage}?`)) return emitAborted(ctx);
-		ctx.emit("deploy:phase", { phase: "deploy" });
-		const url = await guidedStep(() => runWrangler([
-			"deploy",
-			"--config",
-			ctx.config.configFile
-		]), HINTS.deploy, deps);
-		if (url === ABORTED) return emitAborted(ctx);
-		ctx.emit("deploy:complete", { url });
+		if (!await guidedDeployStep(ctx, manifest, stage, deps)) return emitAborted(ctx);
 	},
 	/**
 	* Start a long-lived local dev session: cold-build the Moku site, spawn `wrangler dev
@@ -3158,6 +3192,50 @@ const createDeployApi = (ctx) => ({
 		await runDev(ctx, opts, realDevDeps());
 	},
 	/**
+	* Execute a SQL file against a configured D1 database via `wrangler d1 execute` — for seeding dev
+	* data. Local by default (applies that database's migrations first so the file's tables exist);
+	* `opts.remote` seeds Cloudflare (schema is applied by `deploy`). Generates the wrangler config up
+	* front so the binding resolves even on a first run. Streams wrangler's output.
+	*
+	* @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+	* @param opts - Optional options.
+	* @param opts.stage - Stage for the generated config's resource names (defaults to the app stage).
+	* @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+	* @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+	* @returns Resolves once wrangler finishes executing the file.
+	* @example
+	* ```ts
+	* await api.seed("db/seed.sql");                   // local default d1 (migrate, then execute)
+	* await api.seed("db/seed.sql", { remote: true }); // remote d1
+	* ```
+	*/
+	async seed(sqlFile, opts) {
+		if (!ctx.has("d1")) throw new Error("[moku-worker] seed: no d1 database is configured.");
+		const stage = opts?.stage ?? ctx.global.stage;
+		await writeWranglerConfig(ctx.config.configFile, assembleManifest(ctx, stage), {}, wranglerExtra(ctx.config));
+		const databases = ctx.require(d1Plugin).deployManifest();
+		const wanted = opts?.binding;
+		const matched = wanted === void 0 ? databases : databases.filter((database) => database.binding === wanted);
+		const target = matched.length === 1 ? matched[0] : void 0;
+		if (target === void 0) throw new Error(wanted === void 0 ? `[moku-worker] seed: ${String(databases.length)} d1 databases configured — pass { binding } to choose one.` : `[moku-worker] seed: no d1 database is bound to "${wanted}".`);
+		const scope = opts?.remote === true ? "--remote" : "--local";
+		if (scope === "--local" && target.migrations !== void 0) await runWranglerInherit([
+			"d1",
+			"migrations",
+			"apply",
+			target.binding,
+			"--local"
+		]);
+		await runWranglerInherit([
+			"d1",
+			"execute",
+			target.binding,
+			scope,
+			"--file",
+			sqlFile
+		]);
+	},
+	/**
 	* Scaffold a starting wrangler config (and CI files when ci is set).
 	* Idempotent: an existing config file is left untouched.
 	*
@@ -3284,54 +3362,10 @@ const deployPlugin = createPlugin("deploy", {
 /**
 * @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.
+* `deploy`/`dev` resolve the target stage from the command line (`--stage dev`) so a consumer never
+* hardcodes it. The dev PORT is not parsed here — it comes only from the `dev()` argument (no hidden
+* argv/config resolution). Pure: takes an argv array, reads no globals. Node-only tooling.
 */
-/** 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;
-	}
-};
 /**
 * Extract a `--stage` value from a single token (and the token after it, for the spaced form).
 *
@@ -3342,7 +3376,7 @@ const parsePortArg = (argv) => {
 * ```ts
 * stageValueFrom("--stage=dev", undefined); // "dev"
 * stageValueFrom("--stage", "dev");         // "dev"
-* stageValueFrom("--port", "3000");         // undefined
+* stageValueFrom("--other", "x");           // undefined
 * ```
 */
 const stageValueFrom = (token, next) => {
@@ -3392,19 +3426,21 @@ const parseStageArg = (argv) => {
 */
 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.
+	* Run the Worker locally. The dev port comes ONLY from `opts.port` — the consumer passes it (e.g.
+	* parsed from its own CLI flags in scripts/dev.ts); when omitted it defaults to wrangler's 8787.
+	* There is no hidden argv/config port resolution. Prints a branded dev-session banner, then
+	* delegates to deploy.dev; a `webBuild` hook (e.g. `() => webApp.cli.build()`) wires the web build
+	* into the dev loop so the site recompiles on change. A failure renders a branded `✗` line +
+	* non-zero exit, not a stack.
 	*
 	* @param opts - Optional local dev options.
-	* @param opts.port - Local dev port to bind. Overrides the `--port` flag and the default.
+	* @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
 	* @param opts.stage - Stage for the generated wrangler config; falls back to `--stage` then the app stage.
 	* @param opts.webBuild - 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
+	* await api.dev({ port: 7878, webBuild: () => web.cli.build() });
 	* ```
 	*/
 	async dev(opts) {
@@ -3413,11 +3449,10 @@ const createCliApi = (ctx) => ({
 			wordmark: "moku worker",
 			label: "dev session"
 		});
-		const port = opts?.port ?? parsePortArg(process.argv) ?? ctx.config.port;
 		const stage = opts?.stage ?? parseStageArg(process.argv);
 		try {
 			await ctx.require(deployPlugin).dev({
-				port,
+				...opts?.port === void 0 ? {} : { port: opts.port },
 				...stage === void 0 ? {} : { stage },
 				...opts?.webBuild ? { webBuild: opts.webBuild } : {}
 			});
@@ -3457,6 +3492,40 @@ const createCliApi = (ctx) => ({
 		}
 	},
 	/**
+	* Seed a configured D1 database from a SQL file (delegates to deploy.seed). Local by default;
+	* `opts.remote` seeds Cloudflare. The stage is resolved from a `--stage <name>` CLI flag (so
+	* `bun run dev --seed --stage dev` seeds the dev database). A failure renders a branded `✗` line
+	* and sets a non-zero exit code rather than throwing.
+	*
+	* @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+	* @param opts - Optional options.
+	* @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+	* @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+	* @returns Resolves once the seed completes (or after a failure is rendered).
+	* @example
+	* ```ts
+	* await app.cli.seed("db/seed.sql"); // before app.cli.dev(...)
+	* ```
+	*/
+	async seed(sqlFile, opts) {
+		const ui = (0, _moku_labs_common_cli.createBrandConsole)();
+		ui.lockup({
+			wordmark: "moku worker",
+			label: "seed"
+		});
+		const stage = parseStageArg(process.argv);
+		try {
+			await ctx.require(deployPlugin).seed(sqlFile, {
+				...opts,
+				...stage === void 0 ? {} : { stage }
+			});
+			ui.check(true, "seeded", sqlFile);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}
+	},
+	/**
 	* Verify the `.env` token (no sub) or print the config-derived token guidance (`"setup"`),
 	* rendered in Moku style. `setup` works without a token; verify reports the resolved account.
 	*
@@ -3552,6 +3621,25 @@ const createCliApi = (ctx) => ({
 //#region src/plugins/cli/handlers.ts
 /** Divider drawn before the native `wrangler dev` TUI so the moku preamble reads as one section. */
 const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
+/** Deploy phases that are a slow, opaque wait (captured output) — worth a live spinner on a TTY. */
+const SPINNER_PHASES = new Set(["upload", "deploy"]);
+/** Braille spinner glyphs; advance one per tick. */
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** Spinner tick interval (ms). */
+const SPINNER_TICK_MS = 80;
+/** Carriage-return + blanks + carriage-return that wipes the transient spinner line before settling. */
+const SPINNER_CLEAR = `\r${" ".repeat(72)}\r`;
 /**
 * Builds the hook handlers that turn global deploy events into a live progress TUI.
 * Each logs a clean, prefix-free message via `ctx.log`; the branded log sink (installed
@@ -3571,19 +3659,48 @@ const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
 */
 const createCliHooks = (ctx) => {
 	const ui = (0, _moku_labs_common_cli.createBrandConsole)();
+	const { palette } = ui;
+	let spinnerTimer;
+	let spinnerLabel;
+	const stopSpinner = () => {
+		if (spinnerTimer !== void 0) {
+			clearInterval(spinnerTimer);
+			spinnerTimer = void 0;
+		}
+		if (spinnerLabel !== void 0) {
+			process.stdout.write(SPINNER_CLEAR);
+			ctx.log.info(spinnerLabel);
+			spinnerLabel = void 0;
+		}
+	};
+	const startSpinner = (label) => {
+		spinnerLabel = label;
+		let frame = 0;
+		const text = `${label} …`;
+		spinnerTimer = setInterval(() => {
+			const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0];
+			frame += 1;
+			process.stdout.write(`\r  ${palette.pink(glyph)} ${palette.dim(text)}`);
+		}, SPINNER_TICK_MS);
+	};
 	return {
 		/**
-		* Log one clean line per pipeline phase: "phase" or "phase · detail".
+		* Render one pipeline phase. Quick phases print a clean line ("phase" / "phase · detail"); the
+		* slow opaque waits (upload / deploy) animate a branded spinner on a TTY, settling to a line when
+		* the next phase or completion arrives. Off a TTY every phase is a plain line (unchanged).
 		*
 		* @param p - The deploy:phase event payload.
 		* @example
 		* ```ts
 		* handler({ phase: "detect" }); // "detect"
-		* handler({ phase: "upload", detail: "3 files" }); // "upload · 3 files"
+		* handler({ phase: "deploy" }); // spins on a TTY, else "deploy"
 		* ```
 		*/
 		"deploy:phase"(p) {
-			ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
+			stopSpinner();
+			const label = p.detail ? `${p.phase} · ${p.detail}` : p.phase;
+			if (process.stdout.isTTY === true && SPINNER_PHASES.has(p.phase)) startSpinner(label);
+			else ctx.log.info(label);
 		},
 		/**
 		* Log one dev-session phase: "phase" or "phase · detail".
@@ -3633,6 +3750,7 @@ const createCliHooks = (ctx) => {
 		* ```
 		*/
 		"deploy:complete"(p) {
+			stopSpinner();
 			ctx.log.info(`deployed → ${p.url}`);
 		}
 	};
@@ -3651,7 +3769,7 @@ const createCliHooks = (ctx) => {
 */
 const cliPlugin = createPlugin("cli", {
 	depends: [deployPlugin],
-	config: { port: 8787 },
+	config: {},
 	onInit: (ctx) => {
 		ctx.log.clearSinks();
 		ctx.log.addSink((0, _moku_labs_common_cli.brandedSink)("info"));

package/dist/{cli-Bb37rYq_.mjs → cli-D8UmSqh4.mjs}

@@ -738,7 +738,8 @@ const createQueuesApi = (ctx) => {
 		deployManifest: () => Object.values(ctx.config).map((instance) => ({
 			kind: "queue",
 			name: instance.name,
-			binding: instance.binding
+			binding: instance.binding,
+			...instance.onMessage ? { consumer: true } : {}
 		}))
 	};
 };
@@ -1960,8 +1961,9 @@ const runDev = async (ctx, opts, deps) => {
 //#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.
+* (kv/d1) when it does. Durable Objects are config-only — they ship with the Worker (`wrangler
+* deploy` + the auto-derived DO migration create the namespace), never provisioned via the API — so
+* they are treated as already EXISTING, and the plan never re-offers to "create" them each deploy.
 *
 * @param resource - The declared resource descriptor.
 * @param existing - The indexed set of resources already in the account.
@@ -1989,7 +1991,7 @@ const checkExisting = (resource, existing) => {
 		}
 		case "r2": return { exists: existing.r2.has(resource.name) };
 		case "queue": return { exists: existing.queue.has(resource.name) };
-		case "do": return { exists: false };
+		case "do": return { exists: true };
 	}
 };
 /**
@@ -2504,16 +2506,20 @@ const parseJsonc = (source) => {
 *
 * @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 "").
+* @returns One wrangler KV namespace entry per kv resource — real `id` when known, omitted otherwise
+*   (wrangler rejects an empty `id`, but a local-dev / freshly-generated config validates without one).
 * @example
 * ```ts
 * const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }], { CACHE: "ns123" });
 * ```
 */
-const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
-	binding: resource.binding,
-	id: ids[resource.binding] ?? ""
-}));
+const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => {
+	const id = ids[resource.binding];
+	return id ? {
+		binding: resource.binding,
+		id
+	} : { binding: resource.binding };
+});
 /**
 * Build the wrangler `r2_buckets` array from the manifest's r2 resources.
 *
@@ -2540,31 +2546,41 @@ const buildR2Buckets = (resources) => resources.filter((resource) => resource.ki
 * ```
 */
 const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+	const databaseId = ids[resource.binding];
 	const entry = {
 		binding: resource.binding,
-		database_name: resource.name,
-		database_id: ids[resource.binding] ?? ""
+		database_name: resource.name
 	};
+	if (databaseId) entry.database_id = databaseId;
 	if (resource.migrations) entry.migrations_dir = resource.migrations;
 	return entry;
 });
 /**
-* Build the wrangler `queues` producers section from the manifest's queue resources.
+* Build the wrangler `queues` section (producers + consumers) from the manifest's queue resources.
+* Every queue is a `producer`; a queue flagged `consumer: true` (it declares an `onMessage` handler)
+* is ALSO registered as a `consumer` so wrangler delivers its messages to this Worker's queue()
+* handler — both locally under `wrangler dev` and in production. Without the consumer entry the
+* handler never runs (the bug that silently drops a queue-driven activity feed).
 *
 * @param resources - All resource descriptors from the manifest.
-* @returns The queues section, or undefined when there are no queue resources.
+* @returns The queues section (producers, plus consumers when any), or undefined when there are none.
 * @example
 * ```ts
-* const q = buildQueues([{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY" }]);
+* const q = buildQueues([{ kind: "queue", name: "tracker-activity", binding: "ACTIVITY", consumer: true }]);
 * ```
 */
 const buildQueues = (resources) => {
 	const queueResources = resources.filter((resource) => resource.kind === "queue");
 	if (queueResources.length === 0) return void 0;
-	return { producers: queueResources.map((resource) => ({
+	const producers = queueResources.map((resource) => ({
 		queue: resource.name,
 		binding: resource.binding
-	})) };
+	}));
+	const consumers = queueResources.filter((resource) => resource.consumer === true).map((resource) => ({ queue: resource.name }));
+	return consumers.length > 0 ? {
+		producers,
+		consumers
+	} : { producers };
 };
 /**
 * Build the wrangler `durable_objects` bindings section from the manifest's do resources.
@@ -2672,7 +2688,8 @@ const wranglerExtra = (config) => {
 * @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).
+*   to an empty map, in which case `id`/`database_id` are OMITTED (not "") so the generated config
+*   still validates for local `dev` (wrangler rejects an empty id); a deploy fills the real ids.
 * @param extra - Extra top-level wrangler keys to merge in (the app's `deploy.wrangler` config).
 * @returns Resolves once the file is written.
 * @example
@@ -3047,6 +3064,32 @@ const guidedUpload = async (ctx, manifest, deps) => {
 	return true;
 };
 /**
+* The final deploy step: confirm the target (guided only), run `wrangler deploy` with interactive
+* retry, then emit deploy:complete. Resolves false when the target gate or a deploy retry is declined.
+*
+* @param ctx - The deploy plugin context.
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @param stage - The resolved deploy stage (for the confirm prompt).
+* @param deps - Interactivity + the confirm prompt.
+* @returns True once deployed; false when the user declined the gate or a retry (abort).
+* @example
+* ```ts
+* if (!(await guidedDeployStep(ctx, manifest, stage, deps))) return emitAborted(ctx);
+* ```
+*/
+const guidedDeployStep = async (ctx, manifest, stage, deps) => {
+	if (!await deps.confirm(`Deploy "${manifest.name}" to ${stage}?`)) return false;
+	ctx.emit("deploy:phase", { phase: "deploy" });
+	const url = await guidedStep(() => runWrangler([
+		"deploy",
+		"--config",
+		ctx.config.configFile
+	]), HINTS.deploy, deps);
+	if (url === ABORTED) return false;
+	ctx.emit("deploy:complete", { url });
+	return true;
+};
+/**
 * 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.
@@ -3088,10 +3131,9 @@ const createDeployApi = (ctx) => ({
 		const ci = opts?.ci ?? ctx.config.ci;
 		const stage = opts?.stage ?? ctx.global.stage;
 		const interactive = !ci && stdoutIsTty();
-		const confirm = interactive ? createBrandPrompts().confirm : async (_question) => true;
 		const deps = {
 			interactive,
-			confirm
+			confirm: interactive ? createBrandPrompts().confirm : async (_question) => true
 		};
 		ctx.emit("deploy:phase", { phase: "auth" });
 		if (!await guidedAuth(ctx, deps)) return emitAborted(ctx);
@@ -3104,15 +3146,7 @@ const createDeployApi = (ctx) => ({
 		ctx.emit("deploy:phase", { phase: "wrangler-config" });
 		await writeWranglerConfig(ctx.config.configFile, manifest, provisioned.ids, wranglerExtra(ctx.config));
 		if (!await guidedUpload(ctx, manifest, deps)) return emitAborted(ctx);
-		if (!await confirm(`Deploy "${manifest.name}" to ${stage}?`)) return emitAborted(ctx);
-		ctx.emit("deploy:phase", { phase: "deploy" });
-		const url = await guidedStep(() => runWrangler([
-			"deploy",
-			"--config",
-			ctx.config.configFile
-		]), HINTS.deploy, deps);
-		if (url === ABORTED) return emitAborted(ctx);
-		ctx.emit("deploy:complete", { url });
+		if (!await guidedDeployStep(ctx, manifest, stage, deps)) return emitAborted(ctx);
 	},
 	/**
 	* Start a long-lived local dev session: cold-build the Moku site, spawn `wrangler dev
@@ -3135,6 +3169,50 @@ const createDeployApi = (ctx) => ({
 		await runDev(ctx, opts, realDevDeps());
 	},
 	/**
+	* Execute a SQL file against a configured D1 database via `wrangler d1 execute` — for seeding dev
+	* data. Local by default (applies that database's migrations first so the file's tables exist);
+	* `opts.remote` seeds Cloudflare (schema is applied by `deploy`). Generates the wrangler config up
+	* front so the binding resolves even on a first run. Streams wrangler's output.
+	*
+	* @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+	* @param opts - Optional options.
+	* @param opts.stage - Stage for the generated config's resource names (defaults to the app stage).
+	* @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+	* @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+	* @returns Resolves once wrangler finishes executing the file.
+	* @example
+	* ```ts
+	* await api.seed("db/seed.sql");                   // local default d1 (migrate, then execute)
+	* await api.seed("db/seed.sql", { remote: true }); // remote d1
+	* ```
+	*/
+	async seed(sqlFile, opts) {
+		if (!ctx.has("d1")) throw new Error("[moku-worker] seed: no d1 database is configured.");
+		const stage = opts?.stage ?? ctx.global.stage;
+		await writeWranglerConfig(ctx.config.configFile, assembleManifest(ctx, stage), {}, wranglerExtra(ctx.config));
+		const databases = ctx.require(d1Plugin).deployManifest();
+		const wanted = opts?.binding;
+		const matched = wanted === void 0 ? databases : databases.filter((database) => database.binding === wanted);
+		const target = matched.length === 1 ? matched[0] : void 0;
+		if (target === void 0) throw new Error(wanted === void 0 ? `[moku-worker] seed: ${String(databases.length)} d1 databases configured — pass { binding } to choose one.` : `[moku-worker] seed: no d1 database is bound to "${wanted}".`);
+		const scope = opts?.remote === true ? "--remote" : "--local";
+		if (scope === "--local" && target.migrations !== void 0) await runWranglerInherit([
+			"d1",
+			"migrations",
+			"apply",
+			target.binding,
+			"--local"
+		]);
+		await runWranglerInherit([
+			"d1",
+			"execute",
+			target.binding,
+			scope,
+			"--file",
+			sqlFile
+		]);
+	},
+	/**
 	* Scaffold a starting wrangler config (and CI files when ci is set).
 	* Idempotent: an existing config file is left untouched.
 	*
@@ -3261,54 +3339,10 @@ const deployPlugin = createPlugin("deploy", {
 /**
 * @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.
+* `deploy`/`dev` resolve the target stage from the command line (`--stage dev`) so a consumer never
+* hardcodes it. The dev PORT is not parsed here — it comes only from the `dev()` argument (no hidden
+* argv/config resolution). Pure: takes an argv array, reads no globals. Node-only tooling.
 */
-/** 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;
-	}
-};
 /**
 * Extract a `--stage` value from a single token (and the token after it, for the spaced form).
 *
@@ -3319,7 +3353,7 @@ const parsePortArg = (argv) => {
 * ```ts
 * stageValueFrom("--stage=dev", undefined); // "dev"
 * stageValueFrom("--stage", "dev");         // "dev"
-* stageValueFrom("--port", "3000");         // undefined
+* stageValueFrom("--other", "x");           // undefined
 * ```
 */
 const stageValueFrom = (token, next) => {
@@ -3369,19 +3403,21 @@ const parseStageArg = (argv) => {
 */
 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.
+	* Run the Worker locally. The dev port comes ONLY from `opts.port` — the consumer passes it (e.g.
+	* parsed from its own CLI flags in scripts/dev.ts); when omitted it defaults to wrangler's 8787.
+	* There is no hidden argv/config port resolution. Prints a branded dev-session banner, then
+	* delegates to deploy.dev; a `webBuild` hook (e.g. `() => webApp.cli.build()`) wires the web build
+	* into the dev loop so the site recompiles on change. A failure renders a branded `✗` line +
+	* non-zero exit, not a stack.
 	*
 	* @param opts - Optional local dev options.
-	* @param opts.port - Local dev port to bind. Overrides the `--port` flag and the default.
+	* @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
 	* @param opts.stage - Stage for the generated wrangler config; falls back to `--stage` then the app stage.
 	* @param opts.webBuild - 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
+	* await api.dev({ port: 7878, webBuild: () => web.cli.build() });
 	* ```
 	*/
 	async dev(opts) {
@@ -3390,11 +3426,10 @@ const createCliApi = (ctx) => ({
 			wordmark: "moku worker",
 			label: "dev session"
 		});
-		const port = opts?.port ?? parsePortArg(process.argv) ?? ctx.config.port;
 		const stage = opts?.stage ?? parseStageArg(process.argv);
 		try {
 			await ctx.require(deployPlugin).dev({
-				port,
+				...opts?.port === void 0 ? {} : { port: opts.port },
 				...stage === void 0 ? {} : { stage },
 				...opts?.webBuild ? { webBuild: opts.webBuild } : {}
 			});
@@ -3434,6 +3469,40 @@ const createCliApi = (ctx) => ({
 		}
 	},
 	/**
+	* Seed a configured D1 database from a SQL file (delegates to deploy.seed). Local by default;
+	* `opts.remote` seeds Cloudflare. The stage is resolved from a `--stage <name>` CLI flag (so
+	* `bun run dev --seed --stage dev` seeds the dev database). A failure renders a branded `✗` line
+	* and sets a non-zero exit code rather than throwing.
+	*
+	* @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+	* @param opts - Optional options.
+	* @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+	* @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+	* @returns Resolves once the seed completes (or after a failure is rendered).
+	* @example
+	* ```ts
+	* await app.cli.seed("db/seed.sql"); // before app.cli.dev(...)
+	* ```
+	*/
+	async seed(sqlFile, opts) {
+		const ui = createBrandConsole();
+		ui.lockup({
+			wordmark: "moku worker",
+			label: "seed"
+		});
+		const stage = parseStageArg(process.argv);
+		try {
+			await ctx.require(deployPlugin).seed(sqlFile, {
+				...opts,
+				...stage === void 0 ? {} : { stage }
+			});
+			ui.check(true, "seeded", sqlFile);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		}
+	},
+	/**
 	* Verify the `.env` token (no sub) or print the config-derived token guidance (`"setup"`),
 	* rendered in Moku style. `setup` works without a token; verify reports the resolved account.
 	*
@@ -3529,6 +3598,25 @@ const createCliApi = (ctx) => ({
 //#region src/plugins/cli/handlers.ts
 /** Divider drawn before the native `wrangler dev` TUI so the moku preamble reads as one section. */
 const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
+/** Deploy phases that are a slow, opaque wait (captured output) — worth a live spinner on a TTY. */
+const SPINNER_PHASES = new Set(["upload", "deploy"]);
+/** Braille spinner glyphs; advance one per tick. */
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** Spinner tick interval (ms). */
+const SPINNER_TICK_MS = 80;
+/** Carriage-return + blanks + carriage-return that wipes the transient spinner line before settling. */
+const SPINNER_CLEAR = `\r${" ".repeat(72)}\r`;
 /**
 * Builds the hook handlers that turn global deploy events into a live progress TUI.
 * Each logs a clean, prefix-free message via `ctx.log`; the branded log sink (installed
@@ -3548,19 +3636,48 @@ const WRANGLER_DIVIDER = `  ── wrangler ${"─".repeat(48)}`;
 */
 const createCliHooks = (ctx) => {
 	const ui = createBrandConsole();
+	const { palette } = ui;
+	let spinnerTimer;
+	let spinnerLabel;
+	const stopSpinner = () => {
+		if (spinnerTimer !== void 0) {
+			clearInterval(spinnerTimer);
+			spinnerTimer = void 0;
+		}
+		if (spinnerLabel !== void 0) {
+			process.stdout.write(SPINNER_CLEAR);
+			ctx.log.info(spinnerLabel);
+			spinnerLabel = void 0;
+		}
+	};
+	const startSpinner = (label) => {
+		spinnerLabel = label;
+		let frame = 0;
+		const text = `${label} …`;
+		spinnerTimer = setInterval(() => {
+			const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0];
+			frame += 1;
+			process.stdout.write(`\r  ${palette.pink(glyph)} ${palette.dim(text)}`);
+		}, SPINNER_TICK_MS);
+	};
 	return {
 		/**
-		* Log one clean line per pipeline phase: "phase" or "phase · detail".
+		* Render one pipeline phase. Quick phases print a clean line ("phase" / "phase · detail"); the
+		* slow opaque waits (upload / deploy) animate a branded spinner on a TTY, settling to a line when
+		* the next phase or completion arrives. Off a TTY every phase is a plain line (unchanged).
 		*
 		* @param p - The deploy:phase event payload.
 		* @example
 		* ```ts
 		* handler({ phase: "detect" }); // "detect"
-		* handler({ phase: "upload", detail: "3 files" }); // "upload · 3 files"
+		* handler({ phase: "deploy" }); // spins on a TTY, else "deploy"
 		* ```
 		*/
 		"deploy:phase"(p) {
-			ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
+			stopSpinner();
+			const label = p.detail ? `${p.phase} · ${p.detail}` : p.phase;
+			if (process.stdout.isTTY === true && SPINNER_PHASES.has(p.phase)) startSpinner(label);
+			else ctx.log.info(label);
 		},
 		/**
 		* Log one dev-session phase: "phase" or "phase · detail".
@@ -3610,6 +3727,7 @@ const createCliHooks = (ctx) => {
 		* ```
 		*/
 		"deploy:complete"(p) {
+			stopSpinner();
 			ctx.log.info(`deployed → ${p.url}`);
 		}
 	};
@@ -3628,7 +3746,7 @@ const createCliHooks = (ctx) => {
 */
 const cliPlugin = createPlugin("cli", {
 	depends: [deployPlugin],
-	config: { port: 8787 },
+	config: {},
 	onInit: (ctx) => {
 		ctx.log.clearSinks();
 		ctx.log.addSink(brandedSink("info"));

package/dist/cli.cjs

@@ -1,4 +1,4 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_cli = require("./cli-C8DdTtzn.cjs");
+const require_cli = require("./cli-BPnG_JGR.cjs");
 exports.cliPlugin = require_cli.cliPlugin;
 exports.deployPlugin = require_cli.deployPlugin;

package/dist/cli.d.cts

@@ -1,2 +1,2 @@
-import { i as ResourceManifest, n as cliPlugin, r as ExternalManifest, t as deployPlugin } from "./index-BKOUpKtC.cjs";
+import { i as ResourceManifest, n as cliPlugin, r as ExternalManifest, t as deployPlugin } from "./index-DCweBI9s.cjs";
 export { type ExternalManifest, type ResourceManifest, cliPlugin, deployPlugin };

package/dist/cli.d.mts

@@ -1,2 +1,2 @@
-import { i as ResourceManifest, n as cliPlugin, r as ExternalManifest, t as deployPlugin } from "./index-BKOUpKtC.mjs";
+import { i as ResourceManifest, n as cliPlugin, r as ExternalManifest, t as deployPlugin } from "./index-DCweBI9s.mjs";
 export { type ExternalManifest, type ResourceManifest, cliPlugin, deployPlugin };

package/dist/cli.mjs

@@ -1,2 +1,2 @@
-import { n as deployPlugin, t as cliPlugin } from "./cli-Bb37rYq_.mjs";
+import { n as deployPlugin, t as cliPlugin } from "./cli-D8UmSqh4.mjs";
 export { cliPlugin, deployPlugin };

package/dist/{index-BKOUpKtC.d.cts → index-DCweBI9s.d.cts}

@@ -178,6 +178,7 @@ type ResourceManifest = {
   kind: "queue";
   name: string;
   binding: string;
+  consumer?: boolean;
 } | {
   kind: "do";
   binding: string;
@@ -252,34 +253,35 @@ type TokenRequirement = {
 };
 //#endregion
 //#region src/plugins/cli/types.d.ts
-/** Resolved configuration for the cli plugin. Flat; complete defaults so omission never yields undefined. */
-type Config = {
-  /**
-   * Default local dev port forwarded to deploy.dev when dev() gets no port.
-   * Passed through to `wrangler dev --port <n>`.
-   *
-   * @default 8787
-   */
-  readonly port: number;
-};
+/**
+ * Resolved configuration for the cli plugin. The cli surface is configuration-free: the dev port is
+ * NOT set here (it comes only from `dev({ port })`), so there are no keys to set under
+ * `pluginConfigs.cli`.
+ */
+type Config = Record<string, never>;
 /** Public api surface of the cli plugin, mounted at app.cli.*. */
 type Api = {
   /**
-   * Run the Worker locally via Wrangler (delegates to deploy.dev). Resolves the port from
-   * `opts.port`, else a `--port <n>` CLI flag, else the configured default (8787). A failure renders
-   * a branded `✗` line and sets a non-zero exit code rather than throwing a raw stack trace.
+   * Run the Worker locally via Wrangler (delegates to deploy.dev). The dev port comes only from
+   * `opts.port` — the consumer passes it (e.g. parsed from its own CLI flags); it defaults to 8787
+   * when omitted. A failure renders a branded `✗` line and sets a non-zero exit code rather than
+   * throwing a raw stack trace.
    *
-   * @param opts - Optional port override and web build hook.
-   * @param opts.port - Local dev port to bind (overrides the `--port` flag and the default).
+   * @param opts - Optional port, stage, and web build hook.
+   * @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
+   * @param opts.stage - Stage for the generated wrangler config's resource names. Falls back to the
+   *   `--stage` CLI flag, then the app's configured stage. Pass it explicitly from a script for a
+   *   self-documenting `dev({ stage })` instead of relying on the hidden flag.
    * @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
    * @returns Resolves when the dev session ends.
    * @example
    * ```ts
-   * await app.cli.dev({ webBuild: () => web.cli.build() }); // port from --port or 8787
+   * await app.cli.dev({ stage: "dev", port: 7878, webBuild: () => web.cli.build() });
    * ```
    */
   dev(opts?: {
     port?: number;
+    stage?: string;
     webBuild?: WebBuild;
   }): Promise<void>;
   /**
@@ -287,20 +289,44 @@ type Api = {
    * `{ ci: true }` for the automated/non-interactive path (CI). A failure renders a branded `✗`
    * line and sets a non-zero exit code rather than throwing a raw stack trace.
    *
-   * @param opts - Optional ci flag and a web build hook.
+   * @param opts - Optional ci flag, stage, and a web build hook.
    * @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
+   * @param opts.stage - Stage for the generated wrangler config's resource names (e.g. "production",
+   *   "staging"). Falls back to the `--stage` CLI flag, then the app's configured stage. Pass it
+   *   explicitly from a script for a self-documenting `deploy({ stage })` instead of the hidden flag.
    * @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 app.cli.deploy({ webBuild: () => web.cli.build() });           // guided
-   * await app.cli.deploy({ ci: true, webBuild: () => web.cli.build() }); // CI
+   * await app.cli.deploy({ stage: "production", webBuild: () => web.cli.build() }); // guided
+   * await app.cli.deploy({ ci: true, webBuild: () => web.cli.build() });            // CI
    * ```
    */
   deploy(opts?: {
     ci?: boolean;
+    stage?: string;
     webBuild?: WebBuild;
   }): Promise<void>;
+  /**
+   * Seed a configured D1 database from a SQL file (delegates to deploy.seed). Local by default
+   * (applies the database's migrations first so its tables exist, then executes the file);
+   * `opts.remote` seeds Cloudflare. A failure renders a branded `✗` line and sets a non-zero exit
+   * code rather than throwing.
+   *
+   * @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+   * @param opts - Optional options.
+   * @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+   * @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+   * @returns Resolves once the seed completes (or after a failure is rendered).
+   * @example
+   * ```ts
+   * await app.cli.seed("db/seed.sql"); // local; --stage honored
+   * ```
+   */
+  seed(sqlFile: string, opts?: {
+    binding?: string;
+    remote?: boolean;
+  }): Promise<void>;
   /**
    * Verify the `.env` Cloudflare token (no sub), or print the config-derived token-creation
    * guidance (`"setup"`). Delegates to deploy.verifyAuth() / deploy.tokenInstructions().
@@ -389,6 +415,11 @@ declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", C
     stage?: string;
     webBuild?: WebBuild;
   }): Promise<void>;
+  seed(sqlFile: string, opts?: {
+    stage?: string;
+    binding?: string;
+    remote?: boolean;
+  }): Promise<void>;
   init: (opts?: {
     ci?: boolean;
   }) => Promise<void>;

package/dist/{index-BKOUpKtC.d.mts → index-DCweBI9s.d.mts}

@@ -178,6 +178,7 @@ type ResourceManifest = {
   kind: "queue";
   name: string;
   binding: string;
+  consumer?: boolean;
 } | {
   kind: "do";
   binding: string;
@@ -252,34 +253,35 @@ type TokenRequirement = {
 };
 //#endregion
 //#region src/plugins/cli/types.d.ts
-/** Resolved configuration for the cli plugin. Flat; complete defaults so omission never yields undefined. */
-type Config = {
-  /**
-   * Default local dev port forwarded to deploy.dev when dev() gets no port.
-   * Passed through to `wrangler dev --port <n>`.
-   *
-   * @default 8787
-   */
-  readonly port: number;
-};
+/**
+ * Resolved configuration for the cli plugin. The cli surface is configuration-free: the dev port is
+ * NOT set here (it comes only from `dev({ port })`), so there are no keys to set under
+ * `pluginConfigs.cli`.
+ */
+type Config = Record<string, never>;
 /** Public api surface of the cli plugin, mounted at app.cli.*. */
 type Api = {
   /**
-   * Run the Worker locally via Wrangler (delegates to deploy.dev). Resolves the port from
-   * `opts.port`, else a `--port <n>` CLI flag, else the configured default (8787). A failure renders
-   * a branded `✗` line and sets a non-zero exit code rather than throwing a raw stack trace.
+   * Run the Worker locally via Wrangler (delegates to deploy.dev). The dev port comes only from
+   * `opts.port` — the consumer passes it (e.g. parsed from its own CLI flags); it defaults to 8787
+   * when omitted. A failure renders a branded `✗` line and sets a non-zero exit code rather than
+   * throwing a raw stack trace.
    *
-   * @param opts - Optional port override and web build hook.
-   * @param opts.port - Local dev port to bind (overrides the `--port` flag and the default).
+   * @param opts - Optional port, stage, and web build hook.
+   * @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
+   * @param opts.stage - Stage for the generated wrangler config's resource names. Falls back to the
+   *   `--stage` CLI flag, then the app's configured stage. Pass it explicitly from a script for a
+   *   self-documenting `dev({ stage })` instead of relying on the hidden flag.
    * @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
    * @returns Resolves when the dev session ends.
    * @example
    * ```ts
-   * await app.cli.dev({ webBuild: () => web.cli.build() }); // port from --port or 8787
+   * await app.cli.dev({ stage: "dev", port: 7878, webBuild: () => web.cli.build() });
    * ```
    */
   dev(opts?: {
     port?: number;
+    stage?: string;
     webBuild?: WebBuild;
   }): Promise<void>;
   /**
@@ -287,20 +289,44 @@ type Api = {
    * `{ ci: true }` for the automated/non-interactive path (CI). A failure renders a branded `✗`
    * line and sets a non-zero exit code rather than throwing a raw stack trace.
    *
-   * @param opts - Optional ci flag and a web build hook.
+   * @param opts - Optional ci flag, stage, and a web build hook.
    * @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
+   * @param opts.stage - Stage for the generated wrangler config's resource names (e.g. "production",
+   *   "staging"). Falls back to the `--stage` CLI flag, then the app's configured stage. Pass it
+   *   explicitly from a script for a self-documenting `deploy({ stage })` instead of the hidden flag.
    * @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 app.cli.deploy({ webBuild: () => web.cli.build() });           // guided
-   * await app.cli.deploy({ ci: true, webBuild: () => web.cli.build() }); // CI
+   * await app.cli.deploy({ stage: "production", webBuild: () => web.cli.build() }); // guided
+   * await app.cli.deploy({ ci: true, webBuild: () => web.cli.build() });            // CI
    * ```
    */
   deploy(opts?: {
     ci?: boolean;
+    stage?: string;
     webBuild?: WebBuild;
   }): Promise<void>;
+  /**
+   * Seed a configured D1 database from a SQL file (delegates to deploy.seed). Local by default
+   * (applies the database's migrations first so its tables exist, then executes the file);
+   * `opts.remote` seeds Cloudflare. A failure renders a branded `✗` line and sets a non-zero exit
+   * code rather than throwing.
+   *
+   * @param sqlFile - Path to the SQL file to execute (e.g. "db/seed.sql").
+   * @param opts - Optional options.
+   * @param opts.binding - The d1 binding to target when more than one is configured (e.g. "DB").
+   * @param opts.remote - Seed the remote (Cloudflare) D1 instead of the local one.
+   * @returns Resolves once the seed completes (or after a failure is rendered).
+   * @example
+   * ```ts
+   * await app.cli.seed("db/seed.sql"); // local; --stage honored
+   * ```
+   */
+  seed(sqlFile: string, opts?: {
+    binding?: string;
+    remote?: boolean;
+  }): Promise<void>;
   /**
    * Verify the `.env` Cloudflare token (no sub), or print the config-derived token-creation
    * guidance (`"setup"`). Delegates to deploy.verifyAuth() / deploy.tokenInstructions().
@@ -389,6 +415,11 @@ declare const deployPlugin: import("@moku-labs/core").PluginInstance<"deploy", C
     stage?: string;
     webBuild?: WebBuild;
   }): Promise<void>;
+  seed(sqlFile: string, opts?: {
+    stage?: string;
+    binding?: string;
+    remote?: boolean;
+  }): Promise<void>;
   init: (opts?: {
     ci?: boolean;
   }) => Promise<void>;

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_cli = require("./cli-C8DdTtzn.cjs");
+const require_cli = require("./cli-BPnG_JGR.cjs");
 let _moku_labs_common = require("@moku-labs/common");
 //#region src/env-provider.ts
 /**

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { a as WorkerConfig, c as WorkerPluginCtx, i as ResourceManifest, n as cliPlugin, o as WorkerEnv, r as ExternalManifest, s as WorkerEvents, t as deployPlugin } from "./index-BKOUpKtC.cjs";
+import { a as WorkerConfig, c as WorkerPluginCtx, i as ResourceManifest, n as cliPlugin, o as WorkerEnv, r as ExternalManifest, s as WorkerEvents, t as deployPlugin } from "./index-DCweBI9s.cjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
 import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 
@@ -852,12 +852,15 @@ type Api = QueueProducerApi & {
    * Return this plugin's deploy metadata (one entry per configured instance), read by the deploy
    * plugin. Build-time only — takes no env.
    *
-   * @returns One queue deploy descriptor per configured instance.
+   * @returns One queue deploy descriptor per configured instance. `consumer: true` marks an instance
+   *   that declares an `onMessage` handler — the deploy plugin registers those as wrangler
+   *   `consumers` so this Worker actually receives the queue's messages.
    */
   deployManifest(): Array<{
     kind: "queue";
     name: string;
     binding: string;
+    consumer?: boolean;
   }>;
 };
 /**

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as WorkerConfig, c as WorkerPluginCtx, i as ResourceManifest, n as cliPlugin, o as WorkerEnv, r as ExternalManifest, s as WorkerEvents, t as deployPlugin } from "./index-BKOUpKtC.mjs";
+import { a as WorkerConfig, c as WorkerPluginCtx, i as ResourceManifest, n as cliPlugin, o as WorkerEnv, r as ExternalManifest, s as WorkerEvents, t as deployPlugin } from "./index-DCweBI9s.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
 import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 
@@ -852,12 +852,15 @@ type Api = QueueProducerApi & {
    * Return this plugin's deploy metadata (one entry per configured instance), read by the deploy
    * plugin. Build-time only — takes no env.
    *
-   * @returns One queue deploy descriptor per configured instance.
+   * @returns One queue deploy descriptor per configured instance. `consumer: true` marks an instance
+   *   that declares an `onMessage` handler — the deploy plugin registers those as wrangler
+   *   `consumers` so this Worker actually receives the queue's messages.
    */
   deployManifest(): Array<{
     kind: "queue";
     name: string;
     binding: string;
+    consumer?: boolean;
   }>;
 };
 /**

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as kvPlugin, c as d1Plugin, d as createCore, f as createPlugin$1, i as queuesPlugin, l as bindingsPlugin, n as deployPlugin, o as durableObjectsPlugin, p as stagePlugin, r as storagePlugin, s as defineDurableObject, t as cliPlugin, u as coreConfig } from "./cli-Bb37rYq_.mjs";
+import { a as kvPlugin, c as d1Plugin, d as createCore, f as createPlugin$1, i as queuesPlugin, l as bindingsPlugin, n as deployPlugin, o as durableObjectsPlugin, p as stagePlugin, r as storagePlugin, s as defineDurableObject, t as cliPlugin, u as coreConfig } from "./cli-D8UmSqh4.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
 //#region src/env-provider.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/worker",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Cloudflare Worker framework for Moku — Durable Objects, Queues, R2, D1, and KV plugins that compose with Moku Web.",
   "repository": {
     "type": "git",