@moku-labs/worker 0.8.0 → 0.9.0

package/dist/{cli-DkoPBbJC.cjs → cli-CfgYgnzW.cjs}

@@ -1631,6 +1631,76 @@ const runWranglerInherit = (args) => {
 	});
 };
 //#endregion
+//#region src/plugins/deploy/seed.ts
+/**
+* @file deploy plugin — shared D1 seed helpers (resolve the target db, run a configured seed).
+*
+* Pure orchestration over an INJECTED wrangler runner, so the post-deploy REMOTE seed (api.ts) and
+* the dev-session LOCAL seed (dev/runner.ts) stay in lockstep — same file, same KV-reset semantics,
+* differing only in the `--remote` / `--local` scope. Migrations are NOT applied here: each caller
+* applies the schema first (the deploy's migration step / dev's local-migrate step), then seeds.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Resolve the single configured d1 database (or the one bound to `binding` when several exist) from
+* the d1 plugin's manifest. The shared resolver behind `seed()`, the post-deploy seed, and the dev
+* seed; throws a branded error when the choice is ambiguous (none/several, no binding) or unknown.
+*
+* @param ctx - The deploy plugin context.
+* @param binding - The d1 binding to target when more than one is configured; the sole one otherwise.
+* @returns The resolved d1 resource descriptor (its binding + optional migrations dir).
+* @throws {Error} When no single database resolves (none/several without a binding, or unknown binding).
+* @example
+* ```ts
+* const db = resolveD1(ctx, "DB");
+* ```
+*/
+const resolveD1 = (ctx, binding) => {
+	const databases = ctx.require(d1Plugin).deployManifest();
+	const matched = binding === void 0 ? databases : databases.filter((db) => db.binding === binding);
+	const target = matched.length === 1 ? matched[0] : void 0;
+	if (target === void 0) throw new Error(binding === void 0 ? `[moku-worker] seed: ${String(databases.length)} d1 databases configured — pass { binding } to choose one.` : `[moku-worker] seed: no d1 database is bound to "${binding}".`);
+	return target;
+};
+/**
+* Run a configured seed against one scope: execute the seed SQL against the d1 database, then delete
+* each configured cached KV key so the next read rebuilds it from the freshly-seeded rows. The
+* schema is assumed to exist (the caller applies migrations first), so this never migrates. The
+* wrangler runner is injected so the same orchestration serves the streamed deploy path and the
+* injectable dev path.
+*
+* @param ctx - The deploy plugin context.
+* @param run - The wrangler runner to execute each command through.
+* @param seed - The resolved seed config (SQL file, optional binding, KV keys to reset).
+* @param scope - The wrangler scope: `--remote` (deploy) or `--local` (dev).
+* @returns Resolves once the seed file has executed and every cached KV key is cleared.
+* @throws {Error} When no d1 database is configured, or the seed's binding cannot be resolved.
+* @example
+* ```ts
+* await runConfiguredSeed(ctx, runWranglerInherit, ctx.config.seed, "--remote");
+* ```
+*/
+const runConfiguredSeed = async (ctx, run, seed, scope) => {
+	if (!ctx.has("d1")) throw new Error("[moku-worker] seed: no d1 database is configured.");
+	await run([
+		"d1",
+		"execute",
+		resolveD1(ctx, seed.binding).binding,
+		scope,
+		"--file",
+		seed.file
+	]);
+	for (const entry of seed.resetKv ?? []) await run([
+		"kv",
+		"key",
+		"delete",
+		entry.key,
+		"--binding",
+		entry.binding,
+		scope
+	]);
+};
+//#endregion
 //#region src/plugins/deploy/dev/build.ts
 /**
 * @file deploy plugin — dev site-rebuild resolution.
@@ -1724,7 +1794,8 @@ const buildSite = async (ctx, webBuild) => {
 * @file deploy plugin — debounced filesystem watcher for dev.
 *
 * Watches the top-level directories implied by the config globs (recursive) and fires a debounced
-* change callback with the last changed path. Uses node:fs.watch — no extra dependency.
+* change callback with the SET of paths changed in the window (so a burst of edits coalesces into
+* one rebuild that knows every changed file). Uses node:fs.watch — no extra dependency.
 * Node-only; never imported by the runtime Worker bundle.
 */
 /**
@@ -1747,27 +1818,29 @@ const watchDirectories = (globs) => {
 	return [...directories];
 };
 /**
-* Watch the directories implied by `globs` and fire `onChange` (debounced by `debounceMs`) with
-* the last changed path. Missing directories are skipped silently.
+* Watch the directories implied by `globs` and fire `onChange` (debounced by `debounceMs`) with the
+* distinct set of paths changed within the window. Missing directories are skipped silently.
 *
 * @param globs - Watch globs.
 * @param debounceMs - Coalesce rapid changes into one callback within this window.
-* @param onChange - Called with the last changed path after the debounce settles.
+* @param onChange - Called with the changed paths (snapshot of the window) after the debounce settles.
 * @returns A handle whose close() stops all watchers and cancels any pending callback.
 * @example
 * ```ts
-* const handle = watchPaths(["src/**\/*.ts"], 120, p => rebuild(p));
+* const handle = watchPaths(["src/**\/*.ts"], 120, paths => rebuild(paths));
 * handle.close();
 * ```
 */
 const watchPaths = (globs, debounceMs, onChange) => {
 	let timer;
-	let lastPath = "";
+	const changed = /* @__PURE__ */ new Set();
 	const fire = (changedPath) => {
-		lastPath = changedPath;
+		changed.add(changedPath);
 		if (timer !== void 0) clearTimeout(timer);
 		timer = setTimeout(() => {
-			onChange(lastPath);
+			const batch = [...changed];
+			changed.clear();
+			onChange(batch);
 		}, debounceMs);
 	};
 	const watchers = [];
@@ -1897,27 +1970,50 @@ const realDevDeps = () => ({
 */
 const d1MigrationBindings = (ctx) => ctx.has("d1") ? ctx.require(d1Plugin).deployManifest().filter((manifest) => manifest.migrations !== void 0).map((manifest) => manifest.binding) : [];
 /**
-* Rebuild the site once and announce the result. A failed build keeps the session alive (it just
-* emits dev:error and serves the last good build).
+* One-line description of a changed-path batch for the `dev:phase rebuild` detail: the single path,
+* or the first path plus a `(+N more)` tail. Empty batches (defensive) read as "site".
+*
+* @param paths - The changed paths the watcher coalesced for this rebuild.
+* @returns The detail string for the rebuild phase event.
+* @example
+* ```ts
+* describeChanges(["src/a.ts", "src/b.css"]); // "src/a.ts (+1 more)"
+* ```
+*/
+const describeChanges = (paths) => {
+	const [first, ...rest] = paths;
+	if (first === void 0) return "site";
+	return rest.length === 0 ? first : `${first} (+${String(rest.length)} more)`;
+};
+/**
+* Rebuild the site once for a changed-path batch and announce the result. The FAST path is the
+* incremental `onChange(changedPaths)` hook (e.g. `web.cli.update`) when wired; otherwise it falls
+* back to a full `webBuild()` rebuild (via deps.build) — the prior behavior. A failed rebuild keeps
+* the session alive (it just emits dev:error and serves the last good build). Both paths share one
+* `dev:phase rebuild` → `dev:rebuilt`/`dev:error` envelope so the branded dev TUI is identical.
 *
 * @param ctx - The deploy plugin context.
 * @param deps - The injected dev deps.
-* @param changedPath - The path that triggered the rebuild.
-* @param webBuild - Optional call-time web build hook threaded into the rebuild.
+* @param changedPaths - The paths that triggered the rebuild (the watcher's debounced set).
+* @param hooks - The consumer rebuild hooks.
+* @param hooks.webBuild - Full rebuild (used when `onChange` is absent — the prior behavior).
+* @param hooks.onChange - Incremental rebuild for the changed set (the fast path when wired).
 * @returns Resolves once the rebuild attempt completes.
 * @example
 * ```ts
-* await rebuild(ctx, deps, "src/app.tsx", () => web.cli.build());
+* await rebuild(ctx, deps, ["src/app.tsx"], { onChange: c => web.cli.update(c) });
 * ```
 */
-const rebuild = async (ctx, deps, changedPath, webBuild) => {
+const rebuild = async (ctx, deps, changedPaths, hooks) => {
 	ctx.emit("dev:phase", {
 		phase: "rebuild",
-		detail: changedPath
+		detail: describeChanges(changedPaths)
 	});
 	const started = deps.now();
 	try {
-		const { files } = await deps.build(ctx, webBuild);
+		let files;
+		if (hooks.onChange) files = fileCountOf(await hooks.onChange(changedPaths));
+		else files = (await deps.build(ctx, hooks.webBuild)).files;
 		ctx.emit("dev:rebuilt", {
 			files,
 			ms: deps.now() - started
@@ -1927,29 +2023,58 @@ const rebuild = async (ctx, deps, changedPath, webBuild) => {
 	}
 };
 /**
-* Run a long-lived dev session: cold build → (local d1 migrate) → spawn `wrangler dev` →
-* watch + rebuild on change → teardown on signal.
+* Load the configured seed into the LOCAL D1 for a `dev --seed` session: execute the SQL file, then
+* clear the configured cached KV keys so the app rebuilds them from the freshly-seeded rows. The
+* schema already exists (the migrate step above runs first), so this never migrates — the local
+* analogue of the deploy's remote seed, over the same `pluginConfigs.deploy.seed` config.
+*
+* @param ctx - The deploy plugin context.
+* @param deps - The injected dev deps (for the wrangler runner).
+* @returns Resolves once the seed file has executed and every cached KV key is cleared.
+* @throws {Error} When `--seed` is set but no seed is configured under `pluginConfigs.deploy.seed`.
+* @example
+* ```ts
+* await seedLocal(ctx, realDevDeps());
+* ```
+*/
+const seedLocal = async (ctx, deps) => {
+	const config = ctx.config.seed;
+	if (config === void 0) throw new Error("[moku-worker] dev({ seed: true }) but no seed is configured — set pluginConfigs.deploy.seed.");
+	ctx.emit("dev:phase", {
+		phase: "seed",
+		detail: config.file
+	});
+	await runConfiguredSeed(ctx, deps.runWrangler, config, "--local");
+};
+/**
+* Run a long-lived dev session: cold build → (local d1 migrate) → (local seed) → spawn `wrangler
+* dev` → watch + rebuild on change → teardown on signal.
 *
 * @param ctx - The deploy plugin context (config + emit + require/has).
 * @param opts - Optional options.
 * @param opts.port - Local dev port (default 8787).
-* @param opts.webBuild - Web build hook (re)run on cold build + each change (e.g. `() => web.cli.build()`).
+* @param opts.webBuild - Cold-build hook (also the per-change rebuild when `onChange` is omitted).
+* @param opts.onChange - Incremental per-change rebuild hook (e.g. `c => web.cli.update(c)`); when
+*   set, each debounced change rebuilds only the changed paths instead of a full `webBuild()`.
+* @param opts.seed - Load the configured seed into the LOCAL D1 (+ reset its KV keys) before serving.
 * @param deps - Injected side effects (real ones from realDevDeps in production).
 * @returns Resolves when the session ends (SIGINT).
 * @example
 * ```ts
-* await runDev(ctx, { port: 8787, webBuild: () => web.cli.build() }, realDevDeps());
+* await runDev(ctx, { port: 8787, seed: true, webBuild: () => web.cli.build() }, realDevDeps());
 * ```
 */
 const runDev = async (ctx, opts, deps) => {
 	const port = opts?.port ?? 8787;
 	const webBuild = opts?.webBuild;
+	const onChange = opts?.onChange;
+	const seed = opts?.seed === true;
 	ctx.emit("dev:phase", {
 		phase: "build",
 		detail: "site"
 	});
 	await deps.build(ctx, webBuild);
-	const migrationBindings = ctx.config.migrateLocal ? d1MigrationBindings(ctx) : [];
+	const migrationBindings = ctx.config.migrateLocal || seed ? d1MigrationBindings(ctx) : [];
 	if (migrationBindings.length > 0) {
 		ctx.emit("dev:phase", {
 			phase: "migrate",
@@ -1963,6 +2088,7 @@ const runDev = async (ctx, opts, deps) => {
 			"--local"
 		]);
 	}
+	if (seed) await seedLocal(ctx, deps);
 	ctx.emit("dev:phase", {
 		phase: "serve",
 		detail: `http://localhost:${String(port)}`
@@ -1975,7 +2101,10 @@ const runDev = async (ctx, opts, deps) => {
 		ctx.config.configFile,
 		"--live-reload"
 	]);
-	const watcher = deps.watch(ctx.config.watch, ctx.config.debounceMs, (changedPath) => rebuild(ctx, deps, changedPath, webBuild));
+	const watcher = deps.watch(ctx.config.watch, ctx.config.debounceMs, (changedPaths) => rebuild(ctx, deps, changedPaths, {
+		webBuild,
+		onChange
+	}));
 	await Promise.race([deps.untilSignal(), child.whenExited]);
 	ctx.emit("dev:phase", { phase: "stopping" });
 	watcher.close();
@@ -2942,17 +3071,33 @@ const HINTS = {
 	deploy: "wrangler deploy failed — review the output above, then retry."
 };
 /**
-* Emit the terminal `aborted` phase — the single exit every guided gate/retry funnels through when
-* the user stops the deploy. Factored out so each abort path renders one consistent line.
+* Emit the terminal `aborted` phase AND build the matching {@link DeployReport} — the single exit
+* every guided gate/retry funnels through when the user stops the deploy (or auth was never set up).
+* Centralizing it keeps every abort path emitting one consistent line and returning the same shaped
+* report: `status: "aborted"`, both post-steps `"skipped"`, no errors — so a calling script sees a
+* clean stop, never a half-filled success, and the remote-DB migration/seed are guaranteed unrun.
 *
 * @param ctx - The deploy plugin context.
-* @returns Nothing.
+* @param stage - The resolved deploy stage (echoed into the report).
+* @param startedAt - The run's start timestamp, for the elapsed field.
+* @returns The aborted deploy report.
 * @example
 * ```ts
-* if (declined) return emitAborted(ctx);
+* if (declined) return aborted(ctx, stage, startedAt);
 * ```
 */
-const emitAborted = (ctx) => ctx.emit("deploy:phase", { phase: "aborted" });
+const aborted = (ctx, stage, startedAt) => {
+	ctx.emit("deploy:phase", { phase: "aborted" });
+	return {
+		ok: false,
+		status: "aborted",
+		stage,
+		migration: "skipped",
+		seed: "skipped",
+		elapsedMs: Date.now() - startedAt,
+		errors: []
+	};
+};
 /**
 * The full guided token setup shown after an auth failure on a TTY. Offers to walk the user through
 * it, and when accepted: prints WHERE to create the Cloudflare token (dashboard URL, which template,
@@ -3172,6 +3317,104 @@ const guidedDeployStep = async (ctx, manifest, stage, deps) => {
 	return url;
 };
 /**
+* Apply pending D1 migrations to the REMOTE database for every configured d1 instance that ships a
+* migrations dir — the generic, deploy-owned analogue of `wrangler d1 migrations apply <binding>
+* --remote`. The wrangler config was written earlier in the pipeline, so each binding resolves. The
+* caller runs this only AFTER a successful deploy, so a deploy that never happened never migrates a
+* remote DB. Streams wrangler's output; throws on the first non-zero exit (the caller folds it into
+* the report).
+*
+* @param ctx - The deploy plugin context.
+* @returns Resolves once every configured database's remote migrations have been applied.
+* @example
+* ```ts
+* await applyRemoteMigrations(ctx);
+* ```
+*/
+const applyRemoteMigrations = async (ctx) => {
+	if (!ctx.has("d1")) return;
+	for (const database of ctx.require(d1Plugin).deployManifest()) if (database.migrations !== void 0) await runWranglerInherit([
+		"d1",
+		"migrations",
+		"apply",
+		database.binding,
+		"--remote"
+	]);
+};
+/**
+* Render a post-deploy step's failure as a branded line and capture its message into `errors` —
+* folding the failure into the report instead of throwing, so a deploy that already went live still
+* yields a complete, honest report when a later remote step (migration/seed) fails.
+*
+* @param ui - The branded console to render the error through.
+* @param errors - The accumulator the captured message is pushed into.
+* @param error - The thrown error (or value) to brand and capture.
+* @returns The captured (branded) message.
+* @example
+* ```ts
+* captureFailure(ui, errors, new Error("[moku-worker] seed failed"));
+* ```
+*/
+const captureFailure = (ui, errors, error) => {
+	const message = error instanceof Error ? error.message : String(error);
+	ui.error(message);
+	errors.push(message);
+	return message;
+};
+/**
+* Run the post-deploy remote steps — REACHED ONLY ON A SUCCESSFUL DEPLOY (every gate in `run` returns
+* early before here), so a deploy that never happened never touches a remote DB. Applies remote D1
+* migrations (when requested), then loads the configured seed (when requested) — but skips the seed
+* if the migration it depends on failed. Each step's failure is RENDERED inline and CAPTURED in
+* `errors` (never thrown), so one failed step still yields a complete, honest report.
+*
+* @param ctx - The deploy plugin context.
+* @param want - Which post-steps the caller requested.
+* @param want.migration - Whether to apply pending remote D1 migrations.
+* @param want.seed - Whether to load the configured remote seed (and reset its KV keys).
+* @returns The migration + seed outcomes and any captured branded errors.
+* @example
+* ```ts
+* const post = await runPostDeploy(ctx, { migration: true, seed: true });
+* ```
+*/
+const runPostDeploy = async (ctx, want) => {
+	const ui = (0, _moku_labs_common_cli.createBrandConsole)();
+	const errors = [];
+	let migration = "skipped";
+	if (want.migration) try {
+		await applyRemoteMigrations(ctx);
+		migration = "applied";
+		ui.check(true, "migrated", "remote D1");
+	} catch (error) {
+		migration = "failed";
+		captureFailure(ui, errors, error);
+	}
+	let seed = "skipped";
+	if (want.seed && migration === "failed") {
+		seed = "failed";
+		captureFailure(ui, errors, /* @__PURE__ */ new Error("[moku-worker] seed skipped — the remote migration it depends on failed."));
+	} else if (want.seed) {
+		const config = ctx.config.seed;
+		if (config === void 0) {
+			seed = "failed";
+			captureFailure(ui, errors, /* @__PURE__ */ new Error("[moku-worker] deploy({ seed: true }) but no seed is configured — set pluginConfigs.deploy.seed."));
+		} else try {
+			await runConfiguredSeed(ctx, runWranglerInherit, config, "--remote");
+			seed = "applied";
+			ui.check(true, "seeded", config.file);
+		} catch (error) {
+			seed = "failed";
+			captureFailure(ui, errors, error);
+		}
+	}
+	return {
+		migration,
+		seed,
+		errors
+	};
+};
+/**
 * Create the deploy api. Assembles the manifest from each resource plugin's own deployManifest(),
 * runs an infra preflight (check-before-create + id capture), generates config, uploads, and runs
 * `wrangler deploy`, emitting global deploy events along the way.
@@ -3187,13 +3430,19 @@ const guidedDeployStep = async (ctx, manifest, stage, deps) => {
 const createDeployApi = (ctx) => ({
 	/**
 	* Run the full deploy pipeline: detect → preflight (check-before-create) → provision (only the
-	* missing) → wrangler-config (with real ids) → upload → deploy. When opts.manifest is supplied
-	* it is used verbatim (universal path).
+	* missing) → wrangler-config (with real ids) → upload → deploy, then — ONLY on a successful
+	* deploy — the requested post-deploy remote steps (migration, seed). When opts.manifest is
+	* supplied it is used verbatim (universal path).
 	*
 	* On a TTY the run is GUIDED end to end: each gate is confirmed, and every failure is recovered
-	* interactively rather than thrown — a missing/invalid token offers `auth setup`, and the build,
-	* infra, upload, and `wrangler deploy` steps offer a retry. In CI/pipes it fails fast (no prompt,
-	* the first error propagates to the branded CLI handler).
+	* interactively rather than thrown — a missing/invalid token offers a `.env.local` scaffold, and
+	* the build, infra, upload, and `wrangler deploy` steps offer a retry. In CI/pipes it fails fast
+	* (no prompt, the first error propagates to the branded CLI handler).
+	*
+	* Resolves to a {@link DeployReport}. Every abort path (a declined gate, or auth never set up)
+	* returns `status: "aborted"` BEFORE the post-deploy steps, so `migration`/`seed` run only when
+	* the worker actually went live — a first `deploy --seed` with no token aborts cleanly instead of
+	* falling through to a raw `wrangler … --remote` auth error.
 	*
 	* @param opts - Optional run options.
 	* @param opts.ci - CI/automated mode: never prompts, auto-confirms every gate, fails fast. When
@@ -3202,11 +3451,15 @@ const createDeployApi = (ctx) => ({
 	* @param opts.stage - Target stage; suffixes resource names (`production` = bare). Falls back to the app stage.
 	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
 	* @param opts.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
-	* @returns Resolves once the deploy completes.
+	* @param opts.migration - After a successful deploy, apply pending remote D1 migrations for every
+	*   configured d1 instance that ships migrations. Skipped (not attempted) on an aborted deploy.
+	* @param opts.seed - After a successful deploy (+ migration), load the seed configured under
+	*   `pluginConfigs.deploy.seed` into the remote D1 and reset its cached KV keys. Skipped on abort.
+	* @returns The deploy report (status, url, resource tally, migration/seed outcome, errors).
 	* @example
 	* ```ts
-	* await api.run({ webBuild: () => web.cli.build() }); // guided on a TTY
-	* await api.run({ ci: true, manifest: { name: "w", compatibilityDate: "2026-06-17", resources: [] } });
+	* const report = await api.run({ webBuild: () => web.cli.build(), migration: true, seed: true });
+	* if (!report.ok) process.exitCode = 1; // aborted or a post-step failed
 	* ```
 	*/
 	async run(opts) {
@@ -3219,26 +3472,44 @@ const createDeployApi = (ctx) => ({
 		};
 		const startedAt = Date.now();
 		ctx.emit("deploy:phase", { phase: "auth" });
-		if (!await guidedAuth(ctx, deps)) return emitAborted(ctx);
-		if (!await guidedWebBuild(ctx, opts?.webBuild ?? ctx.config.webBuild, deps)) return emitAborted(ctx);
+		if (!await guidedAuth(ctx, deps)) return aborted(ctx, stage, startedAt);
+		if (!await guidedWebBuild(ctx, opts?.webBuild ?? ctx.config.webBuild, deps)) return aborted(ctx, stage, startedAt);
 		ctx.emit("deploy:phase", { phase: "detect" });
 		const manifest = opts?.manifest ?? assembleManifest(ctx, stage);
 		ctx.emit("deploy:phase", { phase: "provision" });
 		const provisioned = await guidedProvision(ctx, manifest, ci, deps);
-		if (provisioned === ABORTED) return emitAborted(ctx);
+		if (provisioned === ABORTED) return aborted(ctx, stage, startedAt);
 		ctx.emit("deploy:phase", { phase: "wrangler-config" });
 		await writeWranglerConfig(ctx.config.configFile, manifest, provisioned.ids, wranglerExtra(ctx.config));
-		if (!await guidedUpload(ctx, manifest, deps)) return emitAborted(ctx);
+		if (!await guidedUpload(ctx, manifest, deps)) return aborted(ctx, stage, startedAt);
 		const url = await guidedDeployStep(ctx, manifest, stage, deps);
-		if (url === void 0) return emitAborted(ctx);
+		if (url === void 0) return aborted(ctx, stage, startedAt);
+		const resources = {
+			created: provisioned.created.length,
+			exists: provisioned.skipped.length,
+			failed: provisioned.failed.length
+		};
 		renderDeploySummary((0, _moku_labs_common_cli.createBrandConsole)(), {
 			url,
 			stage,
-			created: provisioned.created.length,
-			exists: provisioned.skipped.length,
-			failed: provisioned.failed.length,
+			...resources,
 			elapsedMs: Date.now() - startedAt
 		});
+		const post = await runPostDeploy(ctx, {
+			migration: opts?.migration === true,
+			seed: opts?.seed === true
+		});
+		return {
+			ok: post.errors.length === 0,
+			status: post.errors.length === 0 ? "deployed" : "failed",
+			stage,
+			url,
+			resources,
+			migration: post.migration,
+			seed: post.seed,
+			elapsedMs: Date.now() - startedAt,
+			errors: post.errors
+		};
 	},
 	/**
 	* Start a long-lived local dev session: cold-build the Moku site, spawn `wrangler dev
@@ -3248,11 +3519,15 @@ const createDeployApi = (ctx) => ({
 	* @param opts - Optional options.
 	* @param opts.port - Local dev port (default 8787).
 	* @param opts.stage - Stage for the generated config's resource names (defaults to the app stage).
-	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
+	* @param opts.webBuild - Cold-build the web site (e.g. `() => webApp.cli.build()`); also the
+	*   per-change rebuild when `onChange` is omitted.
+	* @param opts.onChange - Incremental per-change rebuild (e.g. `changes => webApp.cli.update(changes)`).
+	* @param opts.seed - Load the configured seed (`pluginConfigs.deploy.seed`) into the LOCAL D1 and
+	*   reset its cached KV keys before serving — the local analogue of `deploy({ seed: true })`.
 	* @returns Resolves when the dev session ends.
 	* @example
 	* ```ts
-	* await api.dev({ port: 8787, webBuild: () => web.cli.build() });
+	* await api.dev({ port: 8787, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
 	* ```
 	*/
 	async dev(opts) {
@@ -3282,11 +3557,7 @@ const createDeployApi = (ctx) => ({
 		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 target = resolveD1(ctx, opts?.binding);
 		const scope = opts?.remote === true ? "--remote" : "--local";
 		if (scope === "--local" && target.migrations !== void 0) await runWranglerInherit([
 			"d1",
@@ -3505,11 +3776,16 @@ const createCliApi = (ctx) => ({
 	* @param opts - Optional local dev options.
 	* @param opts.port - Local dev port to bind. Defaults to 8787 when omitted.
 	* @param opts.stage - Stage for the generated wrangler config; falls back to `--stage` then the app stage.
-	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
+	* @param opts.webBuild - Cold-build the web site (e.g. `() => webApp.cli.build()`); also the
+	*   per-change rebuild when `onChange` is omitted.
+	* @param opts.onChange - Incremental per-change rebuild (e.g. `changes => webApp.cli.update(changes)`),
+	*   so each change rebuilds only the changed paths instead of a full `webBuild()`.
+	* @param opts.seed - Load the configured seed (`pluginConfigs.deploy.seed`) into the LOCAL D1 and
+	*   reset its cached KV keys before serving — the local analogue of `deploy({ seed: true })`.
 	* @returns Resolves when the dev session ends.
 	* @example
 	* ```ts
-	* await api.dev({ port: 7878, webBuild: () => web.cli.build() });
+	* await api.dev({ port: 7878, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
 	* ```
 	*/
 	async dev(opts) {
@@ -3523,7 +3799,9 @@ const createCliApi = (ctx) => ({
 			await ctx.require(deployPlugin).dev({
 				...opts?.port === void 0 ? {} : { port: opts.port },
 				...stage === void 0 ? {} : { stage },
-				...opts?.webBuild ? { webBuild: opts.webBuild } : {}
+				...opts?.webBuild ? { webBuild: opts.webBuild } : {},
+				...opts?.onChange ? { onChange: opts.onChange } : {},
+				...opts?.seed ? { seed: opts.seed } : {}
 			});
 			ui.check(true, "dev session stopped cleanly");
 		} catch (error) {
@@ -3532,32 +3810,48 @@ const createCliApi = (ctx) => ({
 		}
 	},
 	/**
-	* One-command Cloudflare deploy; forwards opts verbatim to deploy.run. Guided/interactive by
-	* default; `{ ci: true }` runs the automated path (CI). A `webBuild` hook builds the web site
-	* first (before `wrangler deploy`). A failure renders a branded `✗` line + non-zero exit code
-	* (matching cli.auth/doctor), never a raw stack trace.
+	* One-command Cloudflare deploy; forwards opts verbatim to deploy.run, then — only on a successful
+	* deploy — the requested post-deploy migration/seed. Guided/interactive by default; `{ ci: true }`
+	* runs the automated path (CI). A `webBuild` hook builds the web site first (before `wrangler
+	* deploy`). RETURNS the structured {@link DeployReport}; on a failure it also renders a branded `✗`
+	* line + sets a non-zero exit code (matching cli.auth/doctor), never a raw stack trace.
 	*
 	* @param opts - Optional deploy options.
 	* @param opts.ci - Automated mode: never prompts, auto-confirms. Omit/false → guided on a TTY.
 	* @param opts.stage - Target stage (resource-name suffix); falls back to `--stage` then the app stage.
 	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
-	* @returns Resolves once the deploy completes (or after a failure is rendered).
+	* @param opts.migration - Apply pending remote D1 migrations after a successful deploy (skipped on abort).
+	* @param opts.seed - Load the configured remote seed (`pluginConfigs.deploy.seed`) after a
+	*   successful deploy (+ migration); skipped on an aborted deploy.
+	* @returns The deploy report (status, url, resource tally, migration/seed outcome, errors).
 	* @example
 	* ```ts
-	* await api.deploy({ webBuild: () => web.cli.build() });            // guided, app stage
-	* await api.deploy({ ci: true, webBuild: () => web.cli.build() });  // CI; `--stage dev` honored
+	* const report = await api.deploy({ webBuild: () => web.cli.build(), migration: true, seed: true });
+	* if (report.status === "aborted") return; // creds not set up yet — nothing shipped
 	* ```
 	*/
 	async deploy(opts) {
 		const stage = opts?.stage ?? parseStageArg(process.argv);
 		try {
-			await ctx.require(deployPlugin).run({
+			const report = await ctx.require(deployPlugin).run({
 				...opts,
 				...stage === void 0 ? {} : { stage }
 			});
+			if (report.status === "failed") process.exitCode = 1;
+			return report;
 		} catch (error) {
-			(0, _moku_labs_common_cli.createBrandConsole)().error(error instanceof Error ? error.message : String(error));
+			const message = error instanceof Error ? error.message : String(error);
+			(0, _moku_labs_common_cli.createBrandConsole)().error(message);
 			process.exitCode = 1;
+			return {
+				ok: false,
+				status: "failed",
+				stage: stage ?? "production",
+				migration: "skipped",
+				seed: "skipped",
+				elapsedMs: 0,
+				errors: [message]
+			};
 		}
 	},
 	/**