@moku-labs/worker 0.7.0 → 0.7.1

package/dist/{cli-C8DdTtzn.cjs → cli-BBO_YNVC.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 } : {}
 		}))
 	};
 };
@@ -2527,16 +2528,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 +2568,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 +2710,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
@@ -3158,6 +3174,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 +3344,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 +3358,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 +3408,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 +3431,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 +3474,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.
 	*
@@ -3651,7 +3702,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-D67ea3Lu.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 } : {}
 		}))
 	};
 };
@@ -2504,16 +2505,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 +2545,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 +2687,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
@@ -3135,6 +3151,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 +3321,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 +3335,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 +3385,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 +3408,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 +3451,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.
 	*
@@ -3628,7 +3679,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-BBO_YNVC.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-Dse6wZJH.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-Dse6wZJH.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-D67ea3Lu.mjs";
 export { cliPlugin, deployPlugin };

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

@@ -178,6 +178,7 @@ type ResourceManifest = {
   kind: "queue";
   name: string;
   binding: string;
+  consumer?: boolean;
 } | {
   kind: "do";
   binding: string;
@@ -252,30 +253,27 @@ 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 and web build hook.
+   * @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
    * @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({ port: 7878, webBuild: () => web.cli.build() });
    * ```
    */
   dev(opts?: {
@@ -301,6 +299,26 @@ type Api = {
     ci?: boolean;
     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 +407,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-Dse6wZJH.d.mts}

@@ -178,6 +178,7 @@ type ResourceManifest = {
   kind: "queue";
   name: string;
   binding: string;
+  consumer?: boolean;
 } | {
   kind: "do";
   binding: string;
@@ -252,30 +253,27 @@ 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 and web build hook.
+   * @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
    * @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({ port: 7878, webBuild: () => web.cli.build() });
    * ```
    */
   dev(opts?: {
@@ -301,6 +299,26 @@ type Api = {
     ci?: boolean;
     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 +407,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-BBO_YNVC.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-Dse6wZJH.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-Dse6wZJH.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-D67ea3Lu.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.1",
   "description": "Cloudflare Worker framework for Moku — Durable Objects, Queues, R2, D1, and KV plugins that compose with Moku Web.",
   "repository": {
     "type": "git",