@moku-labs/worker 0.8.1 → 0.9.1

package/dist/{cli-l-AOWzhR.cjs → cli-imQGo0tc.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.
@@ -1953,8 +2023,32 @@ const rebuild = async (ctx, deps, changedPaths, hooks) => {
 	}
 };
 /**
-* 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.
@@ -1962,23 +2056,25 @@ const rebuild = async (ctx, deps, changedPaths, hooks) => {
 * @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(), onChange: c => web.cli.update(c) }, 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",
@@ -1992,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)}`
@@ -2016,12 +2113,12 @@ const runDev = async (ctx, opts, deps) => {
 //#endregion
 //#region src/plugins/deploy/infra/plan.ts
 /**
-* Decide whether a single declared resource already exists in the account, recovering its id
-* (kv/d1) when it does. Durable Objects are config-only — they ship with the 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.
+* Decide whether a single API-provisioned resource already exists in the account, recovering its id
+* (kv/d1) when it does. Durable Objects are NOT handled here — they ship with the Worker (`wrangler
+* deploy` + the auto-derived DO migration create the namespace), are never provisioned via the API,
+* and are partitioned into the plan's `ships` bucket by {@link planInfra} before this is ever called.
 *
-* @param resource - The declared resource descriptor.
+* @param resource - The declared (provisionable) resource descriptor.
 * @param existing - The indexed set of resources already in the account.
 * @returns Whether it exists, plus the captured id for kv/d1.
 * @example
@@ -2047,7 +2144,6 @@ 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: true };
 	}
 };
 /**
@@ -2056,7 +2152,7 @@ const checkExisting = (resource, existing) => {
 *
 * @param ctx - The deploy plugin context (env + emit).
 * @param manifest - The assembled (or caller-supplied) deploy manifest.
-* @returns The infra plan: existing (with ids) vs missing resources.
+* @returns The infra plan: existing (with ids) vs missing vs ships-with-Worker (Durable Objects).
 * @throws {Error} When the token is absent/invalid or a Cloudflare listing fails.
 * @example
 * ```ts
@@ -2075,7 +2171,12 @@ const planInfra = async (ctx, manifest) => {
 	const existing = await listExisting(token, account.id, kinds);
 	const exists = [];
 	const missing = [];
+	const ships = [];
 	for (const resource of manifest.resources) {
+		if (resource.kind === "do") {
+			ships.push(resource);
+			continue;
+		}
 		const check = checkExisting(resource, existing);
 		if (check.exists) exists.push(check.id === void 0 ? { resource } : {
 			resource,
@@ -2086,13 +2187,15 @@ const planInfra = async (ctx, manifest) => {
 	ctx.emit("provision:plan", {
 		exists: exists.length,
 		missing: missing.length,
+		ships: ships.length,
 		account: account.name
 	});
 	return {
 		account: account.name,
 		accountId: account.id,
 		exists,
-		missing
+		missing,
+		ships
 	};
 };
 //#endregion
@@ -2123,6 +2226,12 @@ const resourceName = (resource) => resource.kind === "do" ? resource.className :
 */
 const cell = (kind, name) => `${kind.padEnd(6)}${name}`;
 /**
+* Row tag for a Durable Object — it ships with the Worker (`wrangler deploy` creates the namespace),
+* so it is NEVER labelled `(exists)` (the planner never queried the account for it). Shared by the
+* plan and provision-result panels so the two always read the same.
+*/
+const SHIPS_WITH_WORKER = "(ships with worker)";
+/**
 * ANSI SGR matcher — built from `String.fromCharCode(27)` (the ESC byte) so no control character
 * appears in a regex literal (which both linters reject).
 */
@@ -2183,10 +2292,11 @@ const wrapText = (text, width) => {
 /**
 * Render the infra preflight plan as a branded panel: a dim summary line (counts + account) then one
 * row per declared resource — a pink `+` for those to create, a dim `~ (exists)` for those already
-* present. When nothing needs creating it still renders, so the user sees the full picture.
+* present, and a dim `~ (ships with worker)` for Durable Objects (created by `wrangler deploy`, never
+* pre-provisioned). When nothing needs creating it still renders, so the user sees the full picture.
 *
 * @param ui - The branded console to render through.
-* @param plan - The infra plan (existing vs missing) from checkInfra()/planInfra().
+* @param plan - The infra plan (existing vs missing vs ships-with-Worker) from checkInfra()/planInfra().
 * @example
 * ```ts
 * renderPlan(ui, await planInfra(ctx, manifest));
@@ -2194,22 +2304,27 @@ const wrapText = (text, width) => {
 */
 const renderPlan = (ui, plan) => {
 	const { palette } = ui;
-	const summary = palette.dim(`${String(plan.missing.length)} to create · ${String(plan.exists.length)} exist · ${plan.account}`);
-	const existsRows = plan.exists.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const counts = [`${String(plan.missing.length)} to create`, `${String(plan.exists.length)} exist`];
+	if (plan.ships.length > 0) counts.push(`${String(plan.ships.length)} with worker`);
+	const summary = palette.dim(`${counts.join(" · ")} · ${plan.account}`);
 	const createRows = plan.missing.map((resource) => `${palette.pink("+")} ${cell(resource.kind, resourceName(resource))}`);
+	const existsRows = plan.exists.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const shipsRows = plan.ships.map((resource) => `${palette.dim("~")} ${cell(resource.kind, resourceName(resource))} ${palette.dim(SHIPS_WITH_WORKER)}`);
 	ui.heading("Infra plan");
 	ui.box([
 		summary,
 		"",
 		...createRows,
-		...existsRows
+		...existsRows,
+		...shipsRows
 	]);
 };
 /**
 * Render the provision result as a branded panel — a green `✓` per created resource, a dim `~` per
-* skipped, a red `✗` per failure, then a summary line (failed count red when non-zero) — followed,
-* when anything failed, by a detail block printing each failure's FULL reason (ANSI-stripped and
-* word-wrapped) so it is actually readable instead of truncated inside the box.
+* skipped, a dim `~ (ships with worker)` per Durable Object, a red `✗` per failure, then a summary
+* line (failed count red when non-zero) — followed, when anything failed, by a detail block printing
+* each failure's FULL reason (ANSI-stripped and word-wrapped) so it is actually readable instead of
+* truncated inside the box.
 *
 * @param ui - The branded console to render through.
 * @param result - The provision result from provisionInfra()/the deploy pipeline.
@@ -2222,13 +2337,17 @@ const renderProvisionResult = (ui, result) => {
 	const { palette } = ui;
 	const createdRows = result.created.map((ref) => `${palette.green("✓")} ${cell(ref.resource.kind, resourceName(ref.resource))}`);
 	const skippedRows = result.skipped.map((ref) => `${palette.dim("~")} ${cell(ref.resource.kind, resourceName(ref.resource))} ${palette.dim("(exists)")}`);
+	const bundledRows = result.bundled.map((resource) => `${palette.dim("~")} ${cell(resource.kind, resourceName(resource))} ${palette.dim(SHIPS_WITH_WORKER)}`);
 	const failedRows = result.failed.map((failure) => `${palette.red("✗")} ${cell(failure.resource.kind, resourceName(failure.resource))}`);
 	const failedCount = result.failed.length > 0 ? palette.red(`${String(result.failed.length)} failed`) : "0 failed";
-	const summary = `${String(result.created.length)} created · ${String(result.skipped.length)} exist · ${failedCount}`;
+	const counts = [`${String(result.created.length)} created`, `${String(result.skipped.length)} exist`];
+	if (result.bundled.length > 0) counts.push(`${String(result.bundled.length)} with worker`);
+	const summary = `${counts.join(" · ")} · ${failedCount}`;
 	ui.heading("Provisioned");
 	ui.box([
 		...createdRows,
 		...skippedRows,
+		...bundledRows,
 		...failedRows,
 		"",
 		summary
@@ -2271,16 +2390,19 @@ const formatDuration = (ms) => {
 * @param summary.stage - The target stage the worker deployed to.
 * @param summary.created - How many resources were created this run.
 * @param summary.exists - How many resources already existed (skipped).
+* @param summary.bundled - How many Durable Objects shipped with the Worker.
 * @param summary.failed - How many resources failed to provision.
 * @param summary.elapsedMs - The wall-clock deploy duration in milliseconds.
 * @example
 * ```ts
-* renderDeploySummary(ui, { url, stage: "production", created: 0, exists: 5, failed: 0, elapsedMs: 4234 });
+* renderDeploySummary(ui, { url, stage: "production", created: 0, exists: 5, bundled: 1, failed: 0, elapsedMs: 4234 });
 * ```
 */
 const renderDeploySummary = (ui, summary) => {
 	const { palette } = ui;
-	const tally = `${String(summary.exists)} exist · ${String(summary.created)} created`;
+	const parts = [`${String(summary.exists)} exist`, `${String(summary.created)} created`];
+	if (summary.bundled > 0) parts.push(`${String(summary.bundled)} with worker`);
+	const tally = parts.join(" · ");
 	const failedLabel = palette.red(`${String(summary.failed)} failed`);
 	const resources = summary.failed > 0 ? `${tally} · ${failedLabel}` : tally;
 	ui.heading("Deployed");
@@ -2912,32 +3034,25 @@ const assembleManifest = (ctx, stage) => {
 	};
 };
 /**
-* Act on an infra plan: skip the resources that already exist (reusing their ids), create the
-* missing ones (capturing each new id), and announce each via provision:skip / :resource. Resilient
-* — a single resource that fails to create is CAPTURED in `failed` (not thrown), so one bad resource
-* (e.g. an invalid bucket name) never aborts the whole run and the caller can report a clear result.
+* Create the still-missing resources one at a time: provision each, fold its captured id (kv/d1) into
+* the shared `ids` map, and announce it via provision:resource. Resilient — a single failure is
+* CAPTURED (not thrown), so one bad resource never aborts the rest. Extracted from {@link applyPlan}
+* so that orchestrator stays flat (skip existing, skip DOs, create missing).
 *
 * @param ctx - The deploy plugin context.
-* @param plan - The infra plan from planInfra (existing vs missing).
+* @param missing - The resources the plan flagged as not-yet-existing.
 * @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
-* @returns The provisioning result: created, skipped, failed, and the merged binding → id map.
+* @param ids - The binding → Cloudflare id map, mutated in place with each created kv/d1 id.
+* @returns The created refs and any captured per-resource failures.
 * @example
 * ```ts
-* const { created, failed } = await applyPlan(ctx, plan, false);
+* const { created, failed } = await provisionMissing(ctx, plan.missing, false, ids);
 * ```
 */
-const applyPlan = async (ctx, plan, ci) => {
-	const ids = {};
-	for (const ref of plan.exists) {
-		if (ref.id !== void 0 && (ref.resource.kind === "kv" || ref.resource.kind === "d1")) ids[ref.resource.binding] = ref.id;
-		ctx.emit("provision:skip", {
-			kind: ref.resource.kind,
-			name: resourceName(ref.resource)
-		});
-	}
+const provisionMissing = async (ctx, missing, ci, ids) => {
 	const created = [];
 	const failed = [];
-	for (const resource of plan.missing) try {
+	for (const resource of missing) try {
 		const { id } = await provisionResource(resource, ci);
 		if (id !== void 0 && (resource.kind === "kv" || resource.kind === "d1")) ids[resource.binding] = id;
 		created.push(id === void 0 ? { resource } : {
@@ -2954,9 +3069,45 @@ const applyPlan = async (ctx, plan, ci) => {
 			error: error instanceof Error ? error.message : String(error)
 		});
 	}
+	return {
+		created,
+		failed
+	};
+};
+/**
+* Act on an infra plan: skip the resources that already exist (reusing their ids), skip the Durable
+* Objects that ship with the Worker, create the missing ones (capturing each new id), and announce
+* each via provision:skip / :resource. Resilient — a single resource that fails to create is CAPTURED
+* in `failed` (not thrown), so one bad resource (e.g. an invalid bucket name) never aborts the whole
+* run and the caller can report a clear result.
+*
+* @param ctx - The deploy plugin context.
+* @param plan - The infra plan from planInfra (existing vs missing vs ships-with-Worker).
+* @param ci - Whether provisioning runs non-interactively (forwarded to each provider).
+* @returns The provisioning result: created, skipped, bundled, failed, and the merged binding → id map.
+* @example
+* ```ts
+* const { created, failed } = await applyPlan(ctx, plan, false);
+* ```
+*/
+const applyPlan = async (ctx, plan, ci) => {
+	const ids = {};
+	for (const ref of plan.exists) {
+		if (ref.id !== void 0 && (ref.resource.kind === "kv" || ref.resource.kind === "d1")) ids[ref.resource.binding] = ref.id;
+		ctx.emit("provision:skip", {
+			kind: ref.resource.kind,
+			name: resourceName(ref.resource)
+		});
+	}
+	for (const resource of plan.ships) ctx.emit("provision:skip", {
+		kind: resource.kind,
+		name: resourceName(resource)
+	});
+	const { created, failed } = await provisionMissing(ctx, plan.missing, ci, ids);
 	return {
 		created,
 		skipped: plan.exists,
+		bundled: plan.ships,
 		failed,
 		ids
 	};
@@ -2974,17 +3125,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,
@@ -3204,6 +3371,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.
@@ -3219,13 +3484,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
@@ -3234,11 +3505,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) {
@@ -3251,26 +3526,45 @@ 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,
+			bundled: provisioned.bundled.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
@@ -3283,10 +3577,12 @@ const createDeployApi = (ctx) => ({
 	* @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(), onChange: c => web.cli.update(c) });
+	* await api.dev({ port: 8787, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
 	* ```
 	*/
 	async dev(opts) {
@@ -3316,11 +3612,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",
@@ -3543,10 +3835,12 @@ const createCliApi = (ctx) => ({
 	*   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(), onChange: c => web.cli.update(c) });
+	* await api.dev({ port: 7878, seed: true, webBuild: () => web.cli.build(), onChange: c => web.cli.update(c) });
 	* ```
 	*/
 	async dev(opts) {
@@ -3561,7 +3855,8 @@ const createCliApi = (ctx) => ({
 				...opts?.port === void 0 ? {} : { port: opts.port },
 				...stage === void 0 ? {} : { stage },
 				...opts?.webBuild ? { webBuild: opts.webBuild } : {},
-				...opts?.onChange ? { onChange: opts.onChange } : {}
+				...opts?.onChange ? { onChange: opts.onChange } : {},
+				...opts?.seed ? { seed: opts.seed } : {}
 			});
 			ui.check(true, "dev session stopped cleanly");
 		} catch (error) {
@@ -3570,32 +3865,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]
+			};
 		}
 	},
 	/**