@moku-labs/worker 0.3.1 → 0.5.0

package/dist/cli.mjs

@@ -1,9 +1,379 @@
 import { i as durableObjectsPlugin, n as queuesPlugin, o as d1Plugin, r as kvPlugin, t as storagePlugin, u as createPlugin } from "./storage-COo-F38H.mjs";
-import { brandedSink } from "@moku-labs/common/cli";
+import { brandedSink, createBrandConsole, createBrandPrompts } from "@moku-labs/common/cli";
 import { spawn } from "node:child_process";
-import { readdir, stat, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync, watch } from "node:fs";
 import path from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { readdir, stat, writeFile } from "node:fs/promises";
+//#region src/plugins/deploy/auth/permissions.ts
+/** Permission groups every deploy needs, regardless of resources. */
+const ALWAYS = [{
+	group: "Account · Workers Scripts",
+	scope: "Edit",
+	reason: "deploy",
+	inBaseTemplate: true
+}, {
+	group: "Account · Account Settings",
+	scope: "Read",
+	reason: "account",
+	inBaseTemplate: true
+}];
+/**
+* Per-resource-kind permission group. `do` needs nothing extra (Durable Objects ship with the
+* Worker script, covered by Workers Scripts · Edit). `d1`/`queue` are NOT in the stock template.
+*/
+const BY_KIND = {
+	kv: {
+		group: "Account · Workers KV Storage",
+		scope: "Edit",
+		reason: "kv",
+		inBaseTemplate: true
+	},
+	r2: {
+		group: "Account · Workers R2 Storage",
+		scope: "Edit",
+		reason: "r2",
+		inBaseTemplate: true
+	},
+	d1: {
+		group: "Account · D1",
+		scope: "Edit",
+		reason: "d1",
+		inBaseTemplate: false
+	},
+	queue: {
+		group: "Account · Queues",
+		scope: "Edit",
+		reason: "queue",
+		inBaseTemplate: false
+	},
+	do: void 0
+};
+/**
+* Derive the Cloudflare API token requirement from an app manifest: the full permission set plus
+* the subset that must be ADDED to the stock "Edit Cloudflare Workers" template.
+*
+* @param manifest - The assembled deploy manifest.
+* @returns The token requirement (base template, full required set, and groups to add).
+* @example
+* ```ts
+* const { toAdd } = requiredToken({ name: "w", compatibilityDate: "…", resources: [{ kind: "d1", binding: "DB" }] });
+* // toAdd → [{ group: "Account · D1", scope: "Edit", … }]
+* ```
+*/
+const requiredToken = (manifest) => {
+	const required = [...ALWAYS];
+	const seen = new Set(required.map((permission) => permission.group));
+	for (const resource of manifest.resources) {
+		const permission = BY_KIND[resource.kind];
+		if (permission !== void 0 && !seen.has(permission.group)) {
+			required.push(permission);
+			seen.add(permission.group);
+		}
+	}
+	return {
+		base: "Edit Cloudflare Workers",
+		required,
+		toAdd: required.filter((permission) => !permission.inBaseTemplate)
+	};
+};
+/** Permission every CI/automation redeploy needs: ship the Worker script. */
+const CI_ALWAYS = [{
+	group: "Account · Workers Scripts",
+	scope: "Edit",
+	reason: "deploy",
+	inBaseTemplate: true
+}];
+/**
+* Per-resource-kind permission for the CI/automation token. After a first LOCAL deploy has
+* provisioned everything, CI only needs to LIST existing infra (the idempotent preflight) and
+* ship — so data resources drop to `Read`; R2 stays `Edit` because asset upload writes objects.
+*/
+const CI_BY_KIND = {
+	kv: {
+		group: "Account · Workers KV Storage",
+		scope: "Read",
+		reason: "kv (preflight)",
+		inBaseTemplate: true
+	},
+	r2: {
+		group: "Account · Workers R2 Storage",
+		scope: "Edit",
+		reason: "r2 (asset upload)",
+		inBaseTemplate: true
+	},
+	d1: {
+		group: "Account · D1",
+		scope: "Read",
+		reason: "d1 (preflight)",
+		inBaseTemplate: false
+	},
+	queue: {
+		group: "Account · Queues",
+		scope: "Read",
+		reason: "queue (preflight)",
+		inBaseTemplate: false
+	},
+	do: void 0
+};
+/**
+* Derive the REDUCED Cloudflare API token for CI/automation redeploys, from the same manifest.
+* Assumes a prior LOCAL deploy already provisioned the infra, so CI never creates: data resources
+* need only `Read` (the idempotent preflight lists them), R2 keeps `Edit` for asset upload, and no
+* `Account Settings · Read` is needed because CI pins `CLOUDFLARE_ACCOUNT_ID`. Pure: no network.
+*
+* @param manifest - The assembled deploy manifest.
+* @returns The minimum permission groups for a CI redeploy token (deduped, manifest-scoped).
+* @example
+* ```ts
+* const groups = ciToken({ name: "w", compatibilityDate: "…", resources: [{ kind: "d1", binding: "DB" }] });
+* // → [Workers Scripts·Edit, D1·Read]
+* ```
+*/
+const ciToken = (manifest) => {
+	const groups = [...CI_ALWAYS];
+	const seen = new Set(groups.map((permission) => permission.group));
+	for (const resource of manifest.resources) {
+		const permission = CI_BY_KIND[resource.kind];
+		if (permission !== void 0 && !seen.has(permission.group)) {
+			groups.push(permission);
+			seen.add(permission.group);
+		}
+	}
+	return groups;
+};
+//#endregion
+//#region src/plugins/deploy/auth/setup.ts
+/** Cloudflare's dashboard path for creating API tokens. */
+const TOKENS_URL = "https://dash.cloudflare.com/profile/api-tokens";
+/**
+* Render the FULL local-first token section (the deploy that provisions everything): the permission
+* table flagging template-missing rows, the template + "add these" steps, and the `.env.local` lines.
+*
+* @param requirement - The full token requirement (from requiredToken()).
+* @returns The local-first section lines.
+* @example
+* ```ts
+* const lines = localSection(requiredToken(manifest));
+* ```
+*/
+const localSection = (requirement) => {
+	const permissionRows = requirement.required.map((permission) => {
+		const flag = permission.inBaseTemplate ? "" : "   <- add to template";
+		return `  - ${permission.group} : ${permission.scope}   (${permission.reason})${flag}`;
+	});
+	const step3 = requirement.toAdd.length > 0 ? [`  3. Under Permissions, ADD: ${requirement.toAdd.map((permission) => `${permission.group.replace("Account · ", "")} -> ${permission.scope}`).join(", ")}`, "     (the template omits these; everything else is already included)"] : [`  3. The "${requirement.base}" template covers everything — no changes needed.`];
+	return [
+		"LOCAL — first deploy (provisions infra). A Cloudflare API token with these permissions:",
+		"",
+		...permissionRows,
+		"",
+		"Fastest path:",
+		`  1. ${TOKENS_URL}  ->  Create Token`,
+		`  2. Start from the "${requirement.base}" template.`,
+		...step3,
+		"  4. Account Resources -> Include -> your account.",
+		"  5. Create the token, copy it, then add it to .env.local:",
+		"       CLOUDFLARE_API_TOKEN=<paste your token>",
+		"       CLOUDFLARE_ACCOUNT_ID=<your account id>",
+		"  6. Verify it with `auth` (app.deploy.verifyAuth())."
+	];
+};
+/**
+* Render the REDUCED CI/automation token section (redeploy-only): the scoped permission table plus
+* the CI-secret + account-pin steps.
+*
+* @param groups - The CI permission groups (from ciToken()).
+* @returns The CI section lines.
+* @example
+* ```ts
+* const lines = ciSection(ciToken(manifest));
+* ```
+*/
+const ciSection = (groups) => {
+	return [
+		"CI — automation redeploy (infra already provisioned by a local deploy). A SCOPED token with:",
+		"",
+		...groups.map((permission) => `  - ${permission.group} : ${permission.scope}   (${permission.reason})`),
+		"",
+		`  1. ${TOKENS_URL}  ->  Create Token  ->  Create Custom Token.`,
+		"  2. Add exactly the permissions above (Read, not Edit, on data resources — CI never creates).",
+		"  3. Account Resources -> Include -> your account.",
+		"  4. Store it as the CLOUDFLARE_API_TOKEN secret in CI, and PIN the account so no account",
+		"     lookup (and no Account Settings -> Read) is needed:",
+		"       CLOUDFLARE_ACCOUNT_ID=<your account id>",
+		"  CI reuses the same idempotent pipeline — it lists existing infra and ships. To let CI also",
+		"  CREATE missing infra (self-heal), give it the LOCAL token above instead."
+	];
+};
+/**
+* Render the `auth setup` instructions from the app manifest: the FULL local-first token (provisions
+* everything) followed by the REDUCED CI/automation token (redeploy-only).
+*
+* @param manifest - The assembled deploy manifest.
+* @returns A multi-line instruction string covering both tokens.
+* @example
+* ```ts
+* const text = tokenInstructions(manifest);
+* ```
+*/
+const tokenInstructions = (manifest) => [
+	...localSection(requiredToken(manifest)),
+	"",
+	...ciSection(ciToken(manifest))
+].join("\n");
+//#endregion
+//#region src/plugins/deploy/infra/cloudflare.ts
+/**
+* @file deploy plugin — Cloudflare REST discovery client (infra preflight).
+*
+* Lists what already exists in a Cloudflare account so the deploy pipeline can create only the
+* missing resources (idempotent provisioning) and recover real ids for existing kv/d1 bindings.
+* Authenticated with the `.env` API token (CLOUDFLARE_API_TOKEN) — never an interactive login.
+* Uses the global `fetch`; node-only, never imported by the runtime Worker bundle.
+*/
+const API_BASE = "https://api.cloudflare.com/client/v4";
+/**
+* GET a Cloudflare API path with the bearer token and unwrap the `result`.
+*
+* @param token - The Cloudflare API token (CLOUDFLARE_API_TOKEN).
+* @param path - API path beneath the v4 base (e.g. "/accounts").
+* @returns The unwrapped `result` payload, typed by the caller.
+* @throws {Error} When the HTTP request fails or the API reports `success: false`.
+* @example
+* ```ts
+* const accounts = await cfGet<Array<{ id: string }>>(token, "/accounts");
+* ```
+*/
+const cfGet = async (token, path) => {
+	const response = await fetch(`${API_BASE}${path}`, { headers: {
+		Authorization: `Bearer ${token}`,
+		"Content-Type": "application/json"
+	} });
+	const body = await response.json();
+	if (!response.ok || !body.success) {
+		const detail = body.errors?.map((error) => error.message).join("; ") || `HTTP ${response.status}`;
+		throw new Error(`[moku-worker] Cloudflare API request failed (${path}): ${detail}`);
+	}
+	return body.result;
+};
+/**
+* Resolve the Cloudflare account (id + display name) accessible to the token. Used when the
+* consumer did not pin CLOUDFLARE_ACCOUNT_ID; the first accessible account is chosen.
+*
+* @param token - The Cloudflare API token.
+* @returns The resolved account id and name.
+* @throws {Error} When the token can access no account.
+* @example
+* ```ts
+* const { id, name } = await resolveAccount(token);
+* ```
+*/
+const resolveAccount = async (token) => {
+	const first = (await cfGet(token, "/accounts"))[0];
+	if (!first) throw new Error("[moku-worker] No Cloudflare account is accessible with this API token.");
+	return {
+		id: first.id,
+		name: first.name
+	};
+};
+/**
+* Verify a Cloudflare API token via `GET /user/tokens/verify`. Returns its status (`"active"` for
+* a usable token); throws (via cfGet) when the token is rejected outright (401/invalid).
+*
+* @param token - The Cloudflare API token to verify.
+* @returns The token status string reported by Cloudflare.
+* @throws {Error} When the verify request fails (invalid/expired token).
+* @example
+* ```ts
+* const { status } = await verifyToken(token); // status === "active"
+* ```
+*/
+const verifyToken = async (token) => {
+	return { status: (await cfGet(token, "/user/tokens/verify")).status };
+};
+/**
+* List the resources that already exist in the account, querying ONLY the kinds the app declares
+* (one request per declared kind, in parallel), indexed for the preflight diff. Scoping to the
+* declared kinds keeps the API token minimal — an app with only KV never lists (and so never needs
+* read permission on) D1, R2, or Queues.
+*
+* @param token - The Cloudflare API token.
+* @param accountId - The Cloudflare account id to scope the listings to.
+* @param kinds - The resource kinds present in the manifest (the only kinds queried).
+* @returns The existing resources, indexed by kind (un-queried kinds resolve empty).
+* @throws {Error} When any listing request fails.
+* @example
+* ```ts
+* const existing = await listExisting(token, accountId, new Set(["kv", "d1"]));
+* if (existing.kv.has("SESSIONS")) { ... }
+* ```
+*/
+const listExisting = async (token, accountId, kinds) => {
+	const base = `/accounts/${accountId}`;
+	const [kv, d1, r2, queues] = await Promise.all([
+		kinds.has("kv") ? cfGet(token, `${base}/storage/kv/namespaces`) : Promise.resolve([]),
+		kinds.has("d1") ? cfGet(token, `${base}/d1/database`) : Promise.resolve([]),
+		kinds.has("r2") ? cfGet(token, `${base}/r2/buckets`) : Promise.resolve({}),
+		kinds.has("queue") ? cfGet(token, `${base}/queues`) : Promise.resolve([])
+	]);
+	return {
+		kv: new Map(kv.map((namespace) => [namespace.title, namespace.id])),
+		d1: new Map(d1.map((database) => [database.name, database.uuid])),
+		r2: new Set((r2.buckets ?? []).map((bucket) => bucket.name)),
+		queue: new Set(queues.map((queue) => queue.queue_name))
+	};
+};
+//#endregion
+//#region src/plugins/deploy/auth/verify.ts
+/**
+* @file deploy plugin — `.env` token verification + account resolution.
+*
+* Reads CLOUDFLARE_API_TOKEN via ctx.env, verifies it is active against the Cloudflare API, and
+* resolves the account. Emits auth:verified. Throws a branded, actionable error (pointing at
+* `auth setup`) when the token is absent, invalid, or inactive — never an interactive login.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Branded hint appended to every auth failure so the user knows the next step. */
+const SETUP_HINT = "Run `auth setup` for the exact token to create.";
+/**
+* Verify the `.env` Cloudflare API token and resolve its account.
+*
+* @param ctx - The deploy plugin context (env + emit).
+* @returns The verified auth status (account + id).
+* @throws {Error} When the token is absent, invalid/expired, or not active.
+* @example
+* ```ts
+* const { account, accountId } = await verifyAuth(ctx);
+* ```
+*/
+const verifyAuth = async (ctx) => {
+	const token = ctx.env.get("CLOUDFLARE_API_TOKEN");
+	if (token === void 0 || token === "") throw new Error(`[moku-worker] CLOUDFLARE_API_TOKEN is not set. ${SETUP_HINT}`);
+	let status;
+	try {
+		({status} = await verifyToken(token));
+	} catch (error) {
+		throw new Error(`[moku-worker] Cloudflare API token is invalid or expired. ${SETUP_HINT}`, { cause: error });
+	}
+	if (status !== "active") throw new Error(`[moku-worker] Cloudflare API token is "${status}", not active. ${SETUP_HINT}`);
+	const pinnedAccountId = ctx.env.get("CLOUDFLARE_ACCOUNT_ID");
+	const account = pinnedAccountId === void 0 || pinnedAccountId === "" ? await resolveAccount(token) : {
+		id: pinnedAccountId,
+		name: pinnedAccountId
+	};
+	ctx.emit("auth:verified", {
+		account: account.name,
+		accountId: account.id,
+		scopes: []
+	});
+	return {
+		ok: true,
+		account: account.name,
+		accountId: account.id,
+		scopes: []
+	};
+};
+//#endregion
 //#region src/plugins/deploy/runner.ts
 /**
 * @file deploy plugin — wrangler subprocess wrapper (node:child_process).
@@ -72,31 +442,453 @@ const runWrangler = (args) => new Promise((resolve, reject) => {
 		resolve(args[0] === "deploy" ? extractDeployedUrl(stdout) : stdout);
 	});
 });
+/**
+* Spawn `wrangler` with the given args, inheriting stdio so its output streams live to the user's
+* terminal (used by the generic passthrough and long-lived commands like `tail`).
+*
+* @param args - Wrangler CLI arguments (e.g. ["kv", "namespace", "list"]).
+* @returns Resolves once wrangler exits successfully.
+* @throws {Error} When wrangler cannot be spawned or exits non-zero.
+* @example
+* ```ts
+* await runWranglerInherit(["kv", "namespace", "list"]);
+* ```
+*/
+const runWranglerInherit = (args) => {
+	return new Promise((resolve, reject) => {
+		const child = spawn("wrangler", args, { stdio: "inherit" });
+		child.on("error", (error) => {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] Failed to spawn wrangler.\n  ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`[moku-worker] wrangler exited with code ${String(code)}.`));
+		});
+	});
+};
+//#endregion
+//#region src/plugins/deploy/dev/build.ts
+/**
+* @file deploy plugin — dev site-rebuild resolution.
+*
+* Resolves HOW to rebuild the Moku web site on change: the in-process `webBuild` hook (preferred,
+* fast, typed — passed call-time from the consumer's script or set as a config default) → a
+* `buildCommand` shell string → an auto-detected `scripts/build.ts`. When nothing is configured,
+* dev serves the worker only and says so. Subprocesses inherit the parent env by default.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/** Convention build script auto-detected when no webBuild/buildCommand is configured. */
+const AUTO_DETECT = "scripts/build.ts";
+/**
+* Run a shell build command, resolving on a zero exit and rejecting otherwise.
+*
+* @param command - The shell command to run (the consumer's own configured build).
+* @returns Resolves once the command exits successfully.
+* @throws {Error} When the command fails to start or exits non-zero.
+* @example
+* ```ts
+* await runShellBuild("bun run scripts/build.ts");
+* ```
+*/
+const runShellBuild = (command) => {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, {
+			shell: true,
+			stdio: "inherit"
+		});
+		child.on("error", (error) => {
+			reject(/* @__PURE__ */ new Error(`[moku-worker] site build failed to start.\n  ${error.message}`));
+		});
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`[moku-worker] site build exited with code ${String(code)}.`));
+		});
+	});
+};
+/**
+* Rebuild the Moku web site using the resolved strategy: the call-time `webBuild` hook (the
+* script-driven path), else the `webBuild` config default, else the `buildCommand` shell string,
+* else an auto-detected `scripts/build.ts`. A hook's result is normalized to a `{ files }` count
+* (0 when the hook reports none, and for the shell path where it is unknown).
+*
+* @param ctx - The deploy plugin context (config + emit).
+* @param webBuild - Optional call-time web build hook (takes precedence over `ctx.config.webBuild`).
+* @returns The rebuilt file count (0 for the shell path / a countless hook).
+* @throws {Error} When the resolved shell build fails.
+* @example
+* ```ts
+* const { files } = await buildSite(ctx, () => web.cli.build());
+* ```
+*/
+const buildSite = async (ctx, webBuild) => {
+	const hook = webBuild ?? ctx.config.webBuild;
+	if (hook !== void 0) return { files: (await hook())?.files ?? 0 };
+	const command = ctx.config.buildCommand || (existsSync(AUTO_DETECT) ? `bun run ${AUTO_DETECT}` : "");
+	if (command === "") {
+		ctx.emit("dev:error", { message: "No site build configured (pass webBuild or set buildCommand); serving worker only." });
+		return { files: 0 };
+	}
+	await runShellBuild(command);
+	return { files: 0 };
+};
+//#endregion
+//#region src/plugins/deploy/dev/watch.ts
+/**
+* @file deploy plugin — debounced filesystem watcher for dev.
+*
+* Watches the top-level directories implied by the config globs (recursive) and fires a debounced
+* change callback with the last changed path. Uses node:fs.watch — no extra dependency.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Derive the set of top-level directories to watch from glob patterns.
+*
+* @param globs - Watch globs (e.g. ["src/**\/*.ts", "public/**\/*"]).
+* @returns The distinct top-level directories (e.g. ["src", "public"]).
+* @example
+* ```ts
+* watchDirectories(["src/**\/*.ts", "public/**\/*"]); // ["src", "public"]
+* ```
+*/
+const watchDirectories = (globs) => {
+	const directories = /* @__PURE__ */ new Set();
+	for (const glob of globs) {
+		const globStart = glob.search(/[*?[{]/u);
+		const top = (globStart === -1 ? path.dirname(glob) : glob.slice(0, globStart)).split(/[/\\]/u).find((segment) => segment !== "") ?? ".";
+		directories.add(top);
+	}
+	return [...directories];
+};
+/**
+* Watch the directories implied by `globs` and fire `onChange` (debounced by `debounceMs`) with
+* the last changed path. Missing directories are skipped silently.
+*
+* @param globs - Watch globs.
+* @param debounceMs - Coalesce rapid changes into one callback within this window.
+* @param onChange - Called with the last changed path after the debounce settles.
+* @returns A handle whose close() stops all watchers and cancels any pending callback.
+* @example
+* ```ts
+* const handle = watchPaths(["src/**\/*.ts"], 120, p => rebuild(p));
+* handle.close();
+* ```
+*/
+const watchPaths = (globs, debounceMs, onChange) => {
+	let timer;
+	let lastPath = "";
+	const fire = (changedPath) => {
+		lastPath = changedPath;
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => {
+			onChange(lastPath);
+		}, debounceMs);
+	};
+	const watchers = [];
+	for (const directory of watchDirectories(globs)) {
+		if (!existsSync(directory)) continue;
+		watchers.push(watch(directory, { recursive: true }, (_event, filename) => {
+			if (filename !== null) fire(path.join(directory, filename.toString()));
+		}));
+	}
+	return { close: () => {
+		if (timer !== void 0) clearTimeout(timer);
+		for (const watcher of watchers) watcher.close();
+	} };
+};
+//#endregion
+//#region src/plugins/deploy/dev/runner.ts
+/**
+* @file deploy plugin — dev watch/recompile orchestrator.
+*
+* One long-lived session: cold-build the Moku site, optionally apply local D1 migrations, spawn
+* `wrangler dev --live-reload` ONCE, then watch the site sources and rebuild on change (wrangler's
+* asset server live-reloads the browser). Build failures keep the session serving the last good
+* build. Tears down cleanly on SIGINT. Side-effecting work is injected via DevDeps so the
+* orchestration is unit-testable without real processes, watchers, or signals.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Spawn the long-lived `wrangler dev` child (inherits the parent env; non-blocking).
+*
+* @param args - The `wrangler dev …` arguments.
+* @returns A handle exposing kill().
+* @example
+* ```ts
+* const child = spawnWranglerDev(["dev", "--port", "8787"]);
+* ```
+*/
+const spawnWranglerDev = (args) => {
+	const child = spawn("wrangler", args, { stdio: "inherit" });
+	return { kill: () => child.kill() };
+};
+/**
+* Resolve when the user first interrupts the dev session (SIGINT).
+*
+* @returns A promise that settles on the first SIGINT.
+* @example
+* ```ts
+* await waitForSigint();
+* ```
+*/
+const waitForSigint = () => {
+	return new Promise((resolve) => {
+		process.once("SIGINT", () => {
+			resolve();
+		});
+	});
+};
+/**
+* Wall-clock timestamp in ms (extracted so realDevDeps holds only named references).
+*
+* @returns The current time in milliseconds.
+* @example
+* ```ts
+* const t = nowMs();
+* ```
+*/
+const nowMs = () => Date.now();
+/**
+* Build the real (side-effecting) dev deps used by api.dev(). Subprocesses inherit the parent env.
+*
+* @returns The production DevDeps (real spawn / fs.watch / SIGINT / Date.now).
+* @example
+* ```ts
+* await runDev(ctx, opts, realDevDeps());
+* ```
+*/
+const realDevDeps = () => ({
+	build: buildSite,
+	runWrangler,
+	spawnDev: spawnWranglerDev,
+	watch: watchPaths,
+	untilSignal: waitForSigint,
+	now: nowMs
+});
+/**
+* The d1 binding to migrate locally, when a d1 plugin is present in the app.
+*
+* @param ctx - The deploy plugin context.
+* @returns The d1 binding name, or undefined when no d1 plugin is present.
+* @example
+* ```ts
+* const binding = d1Binding(ctx); // "DB" | undefined
+* ```
+*/
+const d1Binding = (ctx) => ctx.has("d1") ? ctx.require(d1Plugin).deployManifest().binding : void 0;
+/**
+* Rebuild the site once and announce the result. A failed build keeps the session alive (it just
+* emits dev:error and serves the last good build).
+*
+* @param ctx - The deploy plugin context.
+* @param deps - The injected dev deps.
+* @param changedPath - The path that triggered the rebuild.
+* @param webBuild - Optional call-time web build hook threaded into the rebuild.
+* @returns Resolves once the rebuild attempt completes.
+* @example
+* ```ts
+* await rebuild(ctx, deps, "src/app.tsx", () => web.cli.build());
+* ```
+*/
+const rebuild = async (ctx, deps, changedPath, webBuild) => {
+	ctx.emit("dev:phase", {
+		phase: "rebuild",
+		detail: changedPath
+	});
+	const started = deps.now();
+	try {
+		const { files } = await deps.build(ctx, webBuild);
+		ctx.emit("dev:rebuilt", {
+			files,
+			ms: deps.now() - started
+		});
+	} catch (error) {
+		ctx.emit("dev:error", { message: error instanceof Error ? error.message : String(error) });
+	}
+};
+/**
+* Run a long-lived dev session: cold build → (local d1 migrate) → spawn `wrangler dev` →
+* watch + rebuild on change → teardown on signal.
+*
+* @param ctx - The deploy plugin context (config + emit + require/has).
+* @param opts - Optional options.
+* @param opts.port - Local dev port (default 8787).
+* @param opts.webBuild - Web build hook (re)run on cold build + each change (e.g. `() => web.cli.build()`).
+* @param deps - Injected side effects (real ones from realDevDeps in production).
+* @returns Resolves when the session ends (SIGINT).
+* @example
+* ```ts
+* await runDev(ctx, { port: 8787, webBuild: () => web.cli.build() }, realDevDeps());
+* ```
+*/
+const runDev = async (ctx, opts, deps) => {
+	const port = opts?.port ?? 8787;
+	const webBuild = opts?.webBuild;
+	ctx.emit("dev:phase", {
+		phase: "build",
+		detail: "site"
+	});
+	await deps.build(ctx, webBuild);
+	const binding = d1Binding(ctx);
+	if (ctx.config.migrateLocal && binding !== void 0) {
+		ctx.emit("dev:phase", {
+			phase: "migrate",
+			detail: "d1 (local)"
+		});
+		await deps.runWrangler([
+			"d1",
+			"migrations",
+			"apply",
+			binding,
+			"--local"
+		]);
+	}
+	ctx.emit("dev:phase", {
+		phase: "serve",
+		detail: `http://localhost:${String(port)}`
+	});
+	const child = deps.spawnDev([
+		"dev",
+		"--port",
+		String(port),
+		"--config",
+		ctx.config.configFile,
+		"--live-reload"
+	]);
+	const watcher = deps.watch(ctx.config.watch, ctx.config.debounceMs, (changedPath) => rebuild(ctx, deps, changedPath, webBuild));
+	await deps.untilSignal();
+	watcher.close();
+	child.kill();
+	ctx.emit("dev:phase", { phase: "stopped" });
+};
+//#endregion
+//#region src/plugins/deploy/infra/plan.ts
+/**
+* Decide whether a single declared resource already exists in the account, recovering its id
+* (kv/d1) when it does. Durable Objects are config-only (they ship with the script), so they are
+* always treated as "missing" — provisioning them is a no-op that just records the binding.
+*
+* @param resource - The declared resource descriptor.
+* @param existing - The indexed set of resources already in the account.
+* @returns Whether it exists, plus the captured id for kv/d1.
+* @example
+* ```ts
+* checkExisting({ kind: "kv", binding: "SESSIONS" }, existing); // { exists: true, id: "ns123" }
+* ```
+*/
+const checkExisting = (resource, existing) => {
+	switch (resource.kind) {
+		case "kv": {
+			const id = existing.kv.get(resource.binding);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "d1": {
+			const id = existing.d1.get(resource.binding);
+			return id === void 0 ? { exists: false } : {
+				exists: true,
+				id
+			};
+		}
+		case "r2": return { exists: existing.r2.has(resource.bucket) };
+		case "queue": return { exists: resource.producers.every((producer) => existing.queue.has(producer)) };
+		case "do": return { exists: false };
+	}
+};
+/**
+* Run the read-only infra preflight: resolve the account, list existing resources, diff against
+* the manifest, emit `provision:plan`, and return the plan. Writes nothing.
+*
+* @param ctx - The deploy plugin context (env + emit).
+* @param manifest - The assembled (or caller-supplied) deploy manifest.
+* @returns The infra plan: existing (with ids) vs missing resources.
+* @throws {Error} When the token is absent/invalid or a Cloudflare listing fails.
+* @example
+* ```ts
+* const plan = await planInfra(ctx, manifest);
+* ```
+*/
+const planInfra = async (ctx, manifest) => {
+	const token = ctx.env.require("CLOUDFLARE_API_TOKEN");
+	const pinnedAccountId = ctx.env.get("CLOUDFLARE_ACCOUNT_ID");
+	const account = pinnedAccountId ? {
+		id: pinnedAccountId,
+		name: pinnedAccountId
+	} : await resolveAccount(token);
+	const kinds = /* @__PURE__ */ new Set();
+	for (const resource of manifest.resources) if (resource.kind !== "do") kinds.add(resource.kind);
+	const existing = await listExisting(token, account.id, kinds);
+	const exists = [];
+	const missing = [];
+	for (const resource of manifest.resources) {
+		const check = checkExisting(resource, existing);
+		if (check.exists) exists.push(check.id === void 0 ? { resource } : {
+			resource,
+			id: check.id
+		});
+		else missing.push(resource);
+	}
+	ctx.emit("provision:plan", {
+		exists: exists.length,
+		missing: missing.length,
+		account: account.name
+	});
+	return {
+		account: account.name,
+		accountId: account.id,
+		exists,
+		missing
+	};
+};
 //#endregion
 //#region src/plugins/deploy/providers/d1.ts
 /**
 * @file deploy plugin — D1 provisioning adapter.
 *
-* Creates a Cloudflare D1 database via `wrangler d1 create <binding>`.
+* Creates a Cloudflare D1 database via `wrangler d1 create <binding>`, captures the created
+* database id from wrangler's output (so writeWranglerConfig can write a real `database_id`
+* instead of an empty placeholder), and applies migrations when declared.
 * Node-only; never imported by the runtime Worker bundle.
 */
 /**
-* Provision a D1 database via `wrangler d1 create` and apply migrations.
+* Parse the created D1 database id from `wrangler d1 create` output.
+* Wrangler prints the new binding as JSON (`"database_id": "..."`) or TOML
+* (`database_id = "..."`); the leading boundary keeps the match anchored to the field name.
+*
+* @param output - Raw stdout from the wrangler create command.
+* @returns The database id, or undefined when none is found.
+* @example
+* ```ts
+* parseD1DatabaseId('{ "database_id": "uuid-1234" }'); // "uuid-1234"
+* ```
+*/
+const parseD1DatabaseId = (output) => {
+	return /(?:^|[\s,{])"?database_id"?\s*[:=]\s*"([^"]+)"/m.exec(output)?.[1];
+};
+/**
+* Provision a D1 database via `wrangler d1 create`, capture its id, and apply migrations.
 *
 * @param manifest - The D1 resource descriptor.
 * @param _ci - Whether running non-interactively.
-* @returns Resolves once the database is created (and migrations applied when specified).
+* @returns The captured database id when wrangler reported one, else an empty outcome.
 * @example
 * ```ts
-* await provisionD1({ kind: "d1", binding: "DB", migrations: "./migrations" }, false);
+* const { id } = await provisionD1({ kind: "d1", binding: "DB", migrations: "./migrations" }, false);
 * ```
 */
 const provisionD1 = async (manifest, _ci) => {
-	await runWrangler([
+	const id = parseD1DatabaseId(await runWrangler([
 		"d1",
 		"create",
 		manifest.binding
-	]);
+	]));
 	if (manifest.migrations) await runWrangler([
 		"d1",
 		"migrations",
@@ -104,6 +896,7 @@ const provisionD1 = async (manifest, _ci) => {
 		manifest.binding,
 		"--local"
 	]);
+	return id ? { id } : {};
 };
 //#endregion
 //#region src/plugins/deploy/providers/do.ts
@@ -126,27 +919,46 @@ const provisionDurableObject = async (_manifest, _ci) => {};
 /**
 * @file deploy plugin — KV provisioning adapter.
 *
-* Creates a Cloudflare KV namespace via `wrangler kv namespace create <binding>`.
-* Node-only; never imported by the runtime Worker bundle.
+* Creates a Cloudflare KV namespace via `wrangler kv namespace create <binding>` and captures
+* the created namespace id from wrangler's output, so writeWranglerConfig can write a real `id`
+* (not an empty placeholder) into the generated wrangler config — otherwise the binding resolves
+* to nothing at runtime. Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Parse the created KV namespace id from `wrangler kv namespace create` output.
+* Wrangler prints the new binding as JSON (`"id": "..."`) or TOML (`id = "..."`); the leading
+* boundary (start / whitespace / `{` / `,`) keeps the match off a longer identifier such as
+* `kv_namespace_id`.
+*
+* @param output - Raw stdout from the wrangler create command.
+* @returns The namespace id, or undefined when none is found.
+* @example
+* ```ts
+* parseKvNamespaceId('{ "id": "abc123" }'); // "abc123"
+* ```
 */
+const parseKvNamespaceId = (output) => {
+	return /(?:^|[\s,{])"?id"?\s*[:=]\s*"([^"]+)"/m.exec(output)?.[1];
+};
 /**
-* Provision a KV namespace via `wrangler kv namespace create`.
+* Provision a KV namespace via `wrangler kv namespace create` and capture its id.
 *
 * @param manifest - The KV resource descriptor.
 * @param _ci - Whether running non-interactively (passed through; wrangler respects env vars).
-* @returns Resolves once the namespace is created.
+* @returns The captured namespace id when wrangler reported one, else an empty outcome.
 * @example
 * ```ts
-* await provisionKv({ kind: "kv", binding: "CACHE" }, false);
+* const { id } = await provisionKv({ kind: "kv", binding: "CACHE" }, false);
 * ```
 */
 const provisionKv = async (manifest, _ci) => {
-	await runWrangler([
+	const id = parseKvNamespaceId(await runWrangler([
 		"kv",
 		"namespace",
 		"create",
 		manifest.binding
-	]);
+	]));
+	return id ? { id } : {};
 };
 //#endregion
 //#region src/plugins/deploy/providers/queues.ts
@@ -258,33 +1070,48 @@ const uploadDirToR2 = async (bucket, directory) => {
 *
 * @param resource - The resource descriptor to provision.
 * @param ci - Whether running non-interactively.
-* @returns Resolves once the resource is provisioned.
+* @returns The provisioning outcome — `{ id }` for kv/d1, `{}` for r2/queue/do.
 * @example
 * ```ts
-* await provisionResource({ kind: "kv", binding: "CACHE" }, false);
-* await provisionResource({ kind: "r2", bucket: "ASSETS" }, false);
+* const { id } = await provisionResource({ kind: "kv", binding: "CACHE" }, false);
+* await provisionResource({ kind: "r2", bucket: "ASSETS" }, false); // {}
 * ```
 */
 const provisionResource = async (resource, ci) => {
 	switch (resource.kind) {
-		case "kv":
-			await provisionKv(resource, ci);
-			break;
+		case "kv": return provisionKv(resource, ci);
+		case "d1": return provisionD1(resource, ci);
 		case "r2":
 			await provisionR2(resource, ci);
-			break;
-		case "d1":
-			await provisionD1(resource, ci);
-			break;
+			return {};
 		case "queue":
 			await provisionQueue(resource, ci);
-			break;
+			return {};
 		case "do":
 			await provisionDurableObject(resource, ci);
-			break;
+			return {};
 	}
 };
 //#endregion
+//#region src/plugins/deploy/tty.ts
+/**
+* @file deploy plugin — TTY detection (isolated so the guided flow is testable).
+*
+* The guided deploy only prompts on an interactive terminal; in a pipe or CI it must never block
+* on stdin. Kept in its own module so tests can mock it without stubbing `process.stdout`.
+* Node-only; never imported by the runtime Worker bundle.
+*/
+/**
+* Whether stdout is an interactive TTY (so prompts are safe to show).
+*
+* @returns True when stdout is a terminal.
+* @example
+* ```ts
+* if (stdoutIsTty()) await prompts.confirm("Deploy?");
+* ```
+*/
+const stdoutIsTty = () => process.stdout.isTTY === true;
+//#endregion
 //#region src/plugins/deploy/wrangler-config.ts
 /**
 * @file deploy plugin — wrangler config generation + scaffold.
@@ -315,15 +1142,16 @@ const parseJsonc = (source) => {
 * Build the wrangler `kv_namespaces` array from the manifest's kv resources.
 *
 * @param resources - All resource descriptors from the manifest.
-* @returns One wrangler KV namespace entry per kv resource.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `id` is filled from here.
+* @returns One wrangler KV namespace entry per kv resource (real `id` when known, else "").
 * @example
 * ```ts
-* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }]);
+* const kv = buildKvNamespaces([{ kind: "kv", binding: "CACHE" }], { CACHE: "ns123" });
 * ```
 */
-const buildKvNamespaces = (resources) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
+const buildKvNamespaces = (resources, ids) => resources.filter((resource) => resource.kind === "kv").map((resource) => ({
 	binding: resource.binding,
-	id: ""
+	id: ids[resource.binding] ?? ""
 }));
 /**
 * Build the wrangler `r2_buckets` array from the manifest's r2 resources.
@@ -343,17 +1171,18 @@ const buildR2Buckets = (resources) => resources.filter((resource) => resource.ki
 * Build the wrangler `d1_databases` array from the manifest's d1 resources.
 *
 * @param resources - All resource descriptors from the manifest.
+* @param ids - Captured Cloudflare ids keyed by binding; the entry's `database_id` is filled from here.
 * @returns One wrangler D1 database entry per d1 resource (migrations_dir set when present).
 * @example
 * ```ts
-* const d1 = buildD1Databases([{ kind: "d1", binding: "DB" }]);
+* const d1 = buildD1Databases([{ kind: "d1", binding: "DB" }], { DB: "uuid-1234" });
 * ```
 */
-const buildD1Databases = (resources) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
+const buildD1Databases = (resources, ids) => resources.filter((resource) => resource.kind === "d1").map((resource) => {
 	const entry = {
 		binding: resource.binding,
 		database_name: resource.binding.toLowerCase(),
-		database_id: ""
+		database_id: ids[resource.binding] ?? ""
 	};
 	if (resource.migrations) entry.migrations_dir = resource.migrations;
 	return entry;
@@ -402,22 +1231,24 @@ const buildDurableObjects = (resources) => {
 *
 * @param configFile - Path to the wrangler config file.
 * @param manifest - The assembled deploy manifest.
+* @param ids - Captured Cloudflare ids keyed by binding (kv namespace id, d1 database id). Defaults
+*   to an empty map, in which case `id`/`database_id` are written as "" (e.g. the universal path).
 * @returns Resolves once the file is written.
 * @example
 * ```ts
-* await writeWranglerConfig("wrangler.jsonc", manifest);
+* await writeWranglerConfig("wrangler.jsonc", manifest, { CACHE: "ns123", DB: "uuid-1234" });
 * ```
 */
-const writeWranglerConfig = async (configFile, manifest) => {
+const writeWranglerConfig = async (configFile, manifest, ids = {}) => {
 	let existing = {};
 	if (existsSync(configFile)) try {
 		existing = parseJsonc(readFileSync(configFile, "utf8"));
 	} catch {
 		existing = {};
 	}
-	const kvNamespaces = buildKvNamespaces(manifest.resources);
+	const kvNamespaces = buildKvNamespaces(manifest.resources, ids);
 	const r2Buckets = buildR2Buckets(manifest.resources);
-	const d1Databases = buildD1Databases(manifest.resources);
+	const d1Databases = buildD1Databases(manifest.resources, ids);
 	const queues = buildQueues(manifest.resources);
 	const durableObjects = buildDurableObjects(manifest.resources);
 	const updated = {
@@ -456,21 +1287,22 @@ const scaffoldWranglerAndCi = async (configFile, _ci) => {
 //#endregion
 //#region src/plugins/deploy/api.ts
 /**
-* @file deploy plugin — API factory (run, dev, init).
+* @file deploy plugin — API factory (run, dev, init, checkInfra, provisionInfra).
 *
 * Pure ctx-taking factory. Assembles the deploy manifest from each resource plugin's own
-* deployManifest() api (never sibling pluginConfigs — design F6), provisions resources,
-* generates/updates the wrangler config, uploads the R2 upload dir, and runs wrangler deploy.
-* Emits only global events: deploy:phase, deploy:complete, provision:resource.
+* deployManifest() api (never sibling pluginConfigs — design F6), runs an infra preflight
+* (check-before-create + capture real ids), generates/updates the wrangler config, uploads the
+* R2 upload dir, and runs wrangler deploy. Emits only global events: deploy:phase,
+* deploy:complete, provision:resource, provision:plan, provision:skip.
 *
-* Node-only: uses node:child_process (via runner.ts) and node:fs (via wrangler-config.ts).
-* Never called in the deployed Worker runtime.
+* Node-only: uses node:child_process (via runner.ts), node:fs (via wrangler-config.ts), and the
+* Cloudflare REST API (via infra/). Never called in the deployed Worker runtime.
 */
 /**
-* Derive a human-readable name string from a resource descriptor (used in provision:resource).
+* Derive a human-readable name string from a resource descriptor (used in provision events).
 *
 * @param resource - The resource descriptor.
-* @returns A name suitable for the provision:resource event payload.
+* @returns A name suitable for the provision:resource / provision:skip event payload.
 * @example
 * ```ts
 * resourceName({ kind: "kv", binding: "CACHE" }); // "CACHE"
@@ -485,12 +1317,74 @@ const resourceName = (resource) => {
 	}
 };
 /**
-* Create the deploy api. Assembles the manifest from each resource plugin's own
-* deployManifest() (never sibling config), provisions, generates config, uploads,
-* and runs `wrangler deploy`, emitting global deploy events along the way.
+* Assemble the deploy manifest from each present resource plugin's OWN deployManifest() api,
+* gated by ctx.has(name) so absent plugins are skipped — never sibling pluginConfigs (F6).
+*
+* @param ctx - The deploy plugin context.
+* @returns The assembled manifest (name, compatibilityDate, resources).
+* @example
+* ```ts
+* const manifest = assembleManifest(ctx);
+* ```
+*/
+const assembleManifest = (ctx) => ({
+	name: ctx.global.name,
+	compatibilityDate: ctx.global.compatibilityDate,
+	resources: [
+		ctx.has("storage") ? ctx.require(storagePlugin).deployManifest() : void 0,
+		ctx.has("kv") ? ctx.require(kvPlugin).deployManifest() : void 0,
+		ctx.has("d1") ? ctx.require(d1Plugin).deployManifest() : void 0,
+		ctx.has("queues") ? ctx.require(queuesPlugin).deployManifest() : void 0,
+		ctx.has("durableObjects") ? ctx.require(durableObjectsPlugin).deployManifest() : void 0
+	].filter((resource) => resource !== void 0)
+});
+/**
+* Act on an infra plan: skip the resources that already exist (reusing their ids), create only
+* the missing ones (capturing each new id), and announce each via provision:skip / :resource.
+*
+* @param ctx - The deploy plugin context.
+* @param plan - The infra plan from planInfra (existing vs missing).
+* @returns The provisioning result: created, skipped, and the merged binding → id map.
+* @example
+* ```ts
+* const { ids } = await applyPlan(ctx, plan);
+* ```
+*/
+const applyPlan = async (ctx, plan) => {
+	const ids = {};
+	for (const ref of plan.exists) {
+		if (ref.id !== void 0 && (ref.resource.kind === "kv" || ref.resource.kind === "d1")) ids[ref.resource.binding] = ref.id;
+		ctx.emit("provision:skip", {
+			kind: ref.resource.kind,
+			name: resourceName(ref.resource)
+		});
+	}
+	const created = [];
+	for (const resource of plan.missing) {
+		const { id } = await provisionResource(resource, ctx.config.ci);
+		if (id !== void 0 && (resource.kind === "kv" || resource.kind === "d1")) ids[resource.binding] = id;
+		created.push(id === void 0 ? { resource } : {
+			resource,
+			id
+		});
+		ctx.emit("provision:resource", {
+			kind: resource.kind,
+			name: resourceName(resource)
+		});
+	}
+	return {
+		created,
+		skipped: plan.exists,
+		ids
+	};
+};
+/**
+* Create the deploy api. Assembles the manifest from each resource plugin's own deployManifest(),
+* runs an infra preflight (check-before-create + id capture), generates config, uploads, and runs
+* `wrangler deploy`, emitting global deploy events along the way.
 *
-* @param ctx - Plugin context (own config + require + has + emit + global).
-* @returns The app.deploy api: run / dev / init.
+* @param ctx - Plugin context (own config + require + has + emit + global + env).
+* @returns The app.deploy api: run / dev / init / checkInfra / provisionInfra.
 * @example
 * ```ts
 * const api = createDeployApi(ctx);
@@ -499,43 +1393,45 @@ const resourceName = (resource) => {
 */
 const createDeployApi = (ctx) => ({
 	/**
-	* Run the full deploy pipeline: detect → provision → wrangler-config → upload → deploy.
-	* When opts.manifest is supplied, it is used verbatim (universal path).
+	* Run the full deploy pipeline: detect → preflight (check-before-create) → provision (only the
+	* missing) → wrangler-config (with real ids) → upload → deploy. When opts.manifest is supplied
+	* it is used verbatim (universal path).
 	*
 	* @param opts - Optional run options.
-	* @param opts.guided - Enable interactive confirmation steps (skipped when ci=true).
-	* @param opts.yes - Auto-confirm all prompts.
+	* @param opts.guided - Enable interactive confirmation steps (only on a TTY, non-CI).
+	* @param opts.yes - Auto-confirm all prompts (non-interactive / CI).
+	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
 	* @param opts.manifest - Caller-supplied manifest (bypasses deployManifest() assembly).
 	* @returns Resolves once the deploy completes.
 	* @example
 	* ```ts
-	* await api.run({ guided: true });
+	* await api.run({ guided: true, webBuild: () => web.cli.build() });
 	* await api.run({ manifest: { name: "w", compatibilityDate: "2026-06-17", resources: [] } });
 	* ```
 	*/
 	async run(opts) {
+		const confirm = (opts?.guided ?? false) && !ctx.config.ci && !(opts?.yes ?? false) && stdoutIsTty() ? createBrandPrompts().confirm : async (_question) => true;
+		ctx.emit("deploy:phase", { phase: "auth" });
+		await verifyAuth(ctx);
+		const webBuild = opts?.webBuild ?? ctx.config.webBuild;
+		if (webBuild !== void 0) {
+			ctx.emit("deploy:phase", {
+				phase: "build",
+				detail: "web"
+			});
+			await webBuild();
+		}
 		ctx.emit("deploy:phase", { phase: "detect" });
-		const manifest = opts?.manifest ?? {
-			name: ctx.global.name,
-			compatibilityDate: ctx.global.compatibilityDate,
-			resources: [
-				ctx.has("storage") ? ctx.require(storagePlugin).deployManifest() : void 0,
-				ctx.has("kv") ? ctx.require(kvPlugin).deployManifest() : void 0,
-				ctx.has("d1") ? ctx.require(d1Plugin).deployManifest() : void 0,
-				ctx.has("queues") ? ctx.require(queuesPlugin).deployManifest() : void 0,
-				ctx.has("durableObjects") ? ctx.require(durableObjectsPlugin).deployManifest() : void 0
-			].filter((resource) => resource !== void 0)
-		};
+		const manifest = opts?.manifest ?? assembleManifest(ctx);
 		ctx.emit("deploy:phase", { phase: "provision" });
-		for (const resource of manifest.resources) {
-			await provisionResource(resource, ctx.config.ci);
-			ctx.emit("provision:resource", {
-				kind: resource.kind,
-				name: resourceName(resource)
-			});
+		const plan = await planInfra(ctx, manifest);
+		if (plan.missing.length > 0 && !await confirm(`Create ${plan.missing.length} missing resource(s) in "${plan.account}"?`)) {
+			ctx.emit("deploy:phase", { phase: "aborted" });
+			return;
 		}
+		const { ids } = await applyPlan(ctx, plan);
 		ctx.emit("deploy:phase", { phase: "wrangler-config" });
-		await writeWranglerConfig(ctx.config.configFile, manifest);
+		await writeWranglerConfig(ctx.config.configFile, manifest, ids);
 		const r2Resource = manifest.resources.find((resource) => resource.kind === "r2");
 		if (r2Resource?.upload) {
 			const count = await uploadDirToR2(r2Resource.bucket, r2Resource.upload);
@@ -544,6 +1440,10 @@ const createDeployApi = (ctx) => ({
 				detail: `${String(count)} files`
 			});
 		}
+		if (!await confirm(`Deploy "${manifest.name}" to ${ctx.global.stage}?`)) {
+			ctx.emit("deploy:phase", { phase: "aborted" });
+			return;
+		}
 		ctx.emit("deploy:phase", { phase: "deploy" });
 		const url = await runWrangler([
 			"deploy",
@@ -553,25 +1453,20 @@ const createDeployApi = (ctx) => ({
 		ctx.emit("deploy:complete", { url });
 	},
 	/**
-	* Start a local Cloudflare dev session via `wrangler dev`.
+	* Start a long-lived local dev session: cold-build the Moku site, spawn `wrangler dev
+	* --live-reload`, and watch the site sources — rebuilding on change (wrangler live-reloads the
+	* browser). Resolves on SIGINT.
 	*
 	* @param opts - Optional options.
 	* @param opts.port - Local dev port (default 8787).
+	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
 	* @returns Resolves when the dev session ends.
 	* @example
 	* ```ts
-	* await api.dev({ port: 8787 });
+	* await api.dev({ port: 8787, webBuild: () => web.cli.build() });
 	* ```
 	*/
-	dev: async (opts) => {
-		await runWrangler([
-			"dev",
-			"--port",
-			String(opts?.port ?? 8787),
-			"--config",
-			ctx.config.configFile
-		]);
-	},
+	dev: (opts) => runDev(ctx, opts, realDevDeps()),
 	/**
 	* Scaffold a starting wrangler config (and CI files when ci is set).
 	* Idempotent: an existing config file is left untouched.
@@ -586,7 +1481,71 @@ const createDeployApi = (ctx) => ({
 	*/
 	init: async (opts) => {
 		await scaffoldWranglerAndCi(ctx.config.configFile, opts?.ci ?? ctx.config.ci);
-	}
+	},
+	/**
+	* Read-only infra preflight: assemble the manifest, resolve the account, list what exists in
+	* Cloudflare, diff, emit provision:plan, and return the plan. Writes nothing.
+	*
+	* @returns The infra plan (existing vs missing resources, with captured ids).
+	* @example
+	* ```ts
+	* const plan = await api.checkInfra();
+	* ```
+	*/
+	checkInfra: () => planInfra(ctx, assembleManifest(ctx)),
+	/**
+	* Create only the resources missing from the plan (skipping existing), capturing each id.
+	*
+	* @param plan - A plan produced by checkInfra().
+	* @returns The provisioning result: created, skipped, and the merged id map.
+	* @example
+	* ```ts
+	* const { created } = await api.provisionInfra(await api.checkInfra());
+	* ```
+	*/
+	provisionInfra: (plan) => applyPlan(ctx, plan),
+	/**
+	* Verify the `.env` Cloudflare API token (must be active) and resolve its account; emits
+	* auth:verified. Throws a branded error pointing at `auth setup` when absent/invalid/inactive.
+	*
+	* @returns The verified auth status (account + id).
+	* @example
+	* ```ts
+	* const { account } = await api.verifyAuth();
+	* ```
+	*/
+	verifyAuth: () => verifyAuth(ctx),
+	/**
+	* Derive the minimum Cloudflare API token this app needs from its manifest (pure, no network).
+	*
+	* @returns The token requirement (full set + groups to add to the stock template).
+	* @example
+	* ```ts
+	* const { toAdd } = api.requiredToken();
+	* ```
+	*/
+	requiredToken: () => requiredToken(assembleManifest(ctx)),
+	/**
+	* Render the `auth setup` guidance from the derived token requirement (pure, no network).
+	*
+	* @returns The rendered instruction text.
+	* @example
+	* ```ts
+	* const text = api.tokenInstructions();
+	* ```
+	*/
+	tokenInstructions: () => tokenInstructions(assembleManifest(ctx)),
+	/**
+	* Run an arbitrary wrangler command, streaming its output (the branded CLI escape hatch).
+	*
+	* @param args - The wrangler arguments.
+	* @returns Resolves once wrangler exits.
+	* @example
+	* ```ts
+	* await api.wrangler(["kv", "namespace", "list"]);
+	* ```
+	*/
+	wrangler: (args) => runWranglerInherit(args)
 });
 /**
 * Complex tier (node-only) — build-time deploy orchestrator over the five resource plugins.
@@ -603,7 +1562,11 @@ const createDeployApi = (ctx) => ({
 const deployPlugin = createPlugin("deploy", {
 	config: {
 		configFile: "wrangler.jsonc",
-		ci: false
+		ci: false,
+		watch: ["src/**/*.{ts,tsx,css}", "public/**/*"],
+		buildCommand: "",
+		migrateLocal: true,
+		debounceMs: 120
 	},
 	depends: [
 		storagePlugin,
@@ -617,6 +1580,9 @@ const deployPlugin = createPlugin("deploy", {
 //#endregion
 //#region src/plugins/cli/api.ts
 /**
+* @file cli plugin — API factory (dev, deploy, auth, doctor).
+*/
+/**
 * Builds app.cli.* — thin passthroughs to the deploy plugin via ctx.require(deployPlugin).
 * Both verbs forward their opts verbatim; `dev` defaults port to ctx.config.port when no
 * opts are supplied.
@@ -632,37 +1598,137 @@ const deployPlugin = createPlugin("deploy", {
 */
 const createCliApi = (ctx) => ({
 	/**
-	* Run the Worker locally; defaults port to ctx.config.port (8787) when no opts supplied.
+	* Run the Worker locally; defaults port to ctx.config.port (8787) when no opts supplied. A
+	* `webBuild` hook (e.g. `() => webApp.cli.build()`) wires the web build into the dev loop so the
+	* site recompiles on change — this is how an app-side script composes web + worker.
 	*
 	* @param opts - Optional local dev options.
 	* @param opts.port - Local dev port to bind. Defaults to ctx.config.port (8787).
+	* @param opts.webBuild - Rebuild the web site on change (e.g. `() => webApp.cli.build()`).
 	* @returns Resolves when the dev session ends.
 	* @example
 	* ```ts
-	* await api.dev();            // port 8787
-	* await api.dev({ port: 3000 }); // port 3000
+	* await api.dev();                                   // port 8787, worker only
+	* await api.dev({ webBuild: () => web.cli.build() }); // wire the web build in
 	* ```
 	*/
 	dev(opts) {
-		return ctx.require(deployPlugin).dev(opts ?? { port: ctx.config.port });
+		const port = opts?.port ?? ctx.config.port;
+		return ctx.require(deployPlugin).dev(opts?.webBuild ? {
+			port,
+			webBuild: opts.webBuild
+		} : { port });
 	},
 	/**
 	* One-command guided Cloudflare deploy; forwards flags verbatim to deploy.run.
-	* Passes `undefined` when called with no opts (not a default empty object).
+	* Passes `undefined` when called with no opts (not a default empty object). A `webBuild` hook
+	* builds the web site first (before `wrangler deploy`) — how an app-side script ships web + worker.
 	*
 	* @param opts - Optional deploy options.
 	* @param opts.guided - Walk through each step interactively.
 	* @param opts.yes - Skip confirmation prompts (non-interactive / CI).
+	* @param opts.webBuild - Build the web site first (e.g. `() => webApp.cli.build()`), before deploy.
 	* @returns Resolves once the deploy completes.
 	* @example
 	* ```ts
-	* await api.deploy({ guided: true });
+	* await api.deploy({ guided: true, webBuild: () => web.cli.build() });
 	* await api.deploy({ yes: true }); // CI
 	* await api.deploy(); // opts === undefined
 	* ```
 	*/
 	deploy(opts) {
 		return ctx.require(deployPlugin).run(opts);
+	},
+	/**
+	* Verify the `.env` token (no sub) or print the config-derived token guidance (`"setup"`),
+	* rendered in Moku style. `setup` works without a token; verify reports the resolved account.
+	*
+	* @param sub - Pass "setup" to print guidance; omit to verify the current token.
+	* @returns Resolves once the check or guidance render completes.
+	* @example
+	* ```ts
+	* await api.auth("setup"); // print what token to create
+	* await api.auth();        // verify the current token
+	* ```
+	*/
+	async auth(sub) {
+		const deploy = ctx.require(deployPlugin);
+		const ui = createBrandConsole();
+		if (sub === "setup") {
+			for (const line of deploy.tokenInstructions().split("\n")) ui.line(line);
+			return;
+		}
+		try {
+			const status = await deploy.verifyAuth();
+			ui.check(true, "token valid", `account "${status.account}" (${status.accountId})`);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* One-shot preflight report: token + account (verifyAuth) then infra drift (checkInfra),
+	* each as a branded check line. Stops after the token check when auth fails.
+	*
+	* @returns Resolves once the report is printed.
+	* @example
+	* ```ts
+	* await api.doctor();
+	* ```
+	*/
+	async doctor() {
+		const deploy = ctx.require(deployPlugin);
+		const ui = createBrandConsole();
+		ui.heading("doctor");
+		let tokenOk = false;
+		try {
+			const status = await deploy.verifyAuth();
+			tokenOk = true;
+			ui.check(true, "token", `valid · account "${status.account}" (${status.accountId})`);
+		} catch (error) {
+			ui.check(false, "token", error instanceof Error ? error.message : String(error));
+		}
+		if (!tokenOk) {
+			ui.line("Run `auth setup` for the exact token to create.");
+			return;
+		}
+		try {
+			const plan = await deploy.checkInfra();
+			ui.check(true, "infra", `${plan.exists.length} exist, ${plan.missing.length} to create in "${plan.account}"`);
+		} catch (error) {
+			ui.check(false, "infra", error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* Print the resolved Cloudflare account for the current `.env` token.
+	*
+	* @returns Resolves once the account summary is printed.
+	* @example
+	* ```ts
+	* await api.whoami();
+	* ```
+	*/
+	async whoami() {
+		const ui = createBrandConsole();
+		try {
+			const status = await ctx.require(deployPlugin).verifyAuth();
+			ui.check(true, "account", `${status.account} (${status.accountId})`);
+		} catch (error) {
+			ui.error(error instanceof Error ? error.message : String(error));
+		}
+	},
+	/**
+	* Run an arbitrary wrangler command through the branded CLI (escape hatch). Streams its output.
+	*
+	* @param args - The wrangler arguments.
+	* @returns Resolves once wrangler exits.
+	* @example
+	* ```ts
+	* await api.wrangler(["kv", "namespace", "list"]);
+	* ```
+	*/
+	async wrangler(args) {
+		createBrandConsole().heading(`wrangler ${args.join(" ")}`);
+		await ctx.require(deployPlugin).wrangler(args);
 	}
 });
 //#endregion
@@ -699,6 +1765,18 @@ const createCliHooks = (ctx) => ({
 		ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
 	},
 	/**
+	* Log the infra preflight summary: "infra · N exist, M to create · account".
+	*
+	* @param p - The provision:plan event payload.
+	* @example
+	* ```ts
+	* handler({ exists: 2, missing: 1, account: "Play Co" }); // "infra · 2 exist, 1 to create · Play Co"
+	* ```
+	*/
+	"provision:plan"(p) {
+		ctx.log.info(`infra · ${p.exists} exist, ${p.missing} to create · ${p.account}`);
+	},
+	/**
 	* Log one clean line per provisioned resource: "kind name".
 	*
 	* @param p - The provision:resource event payload.
@@ -711,6 +1789,55 @@ const createCliHooks = (ctx) => ({
 		ctx.log.info(`${p.kind} ${p.name}`);
 	},
 	/**
+	* Log one clean line per already-existing resource (skipped): "kind name (exists)".
+	*
+	* @param p - The provision:skip event payload.
+	* @example
+	* ```ts
+	* handler({ kind: "kv", name: "KV" }); // "kv KV (exists)"
+	* ```
+	*/
+	"provision:skip"(p) {
+		ctx.log.info(`${p.kind} ${p.name} (exists)`);
+	},
+	/**
+	* Log one dev-session phase: "phase" or "phase · detail".
+	*
+	* @param p - The dev:phase event payload.
+	* @example
+	* ```ts
+	* handler({ phase: "serve", detail: "http://localhost:8787" }); // "serve · http://localhost:8787"
+	* ```
+	*/
+	"dev:phase"(p) {
+		ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
+	},
+	/**
+	* Log the site rebuild result: "site <n> files · <ms>ms" (omits the count when unknown).
+	*
+	* @param p - The dev:rebuilt event payload.
+	* @example
+	* ```ts
+	* handler({ files: 12, ms: 240 }); // "site 12 files · 240ms"
+	* handler({ files: 0, ms: 240 }); // "site · 240ms"
+	* ```
+	*/
+	"dev:rebuilt"(p) {
+		ctx.log.info(p.files > 0 ? `site ${String(p.files)} files · ${String(p.ms)}ms` : `site · ${String(p.ms)}ms`);
+	},
+	/**
+	* Log a non-fatal dev build failure via warn (the session keeps serving the last good build).
+	*
+	* @param p - The dev:error event payload.
+	* @example
+	* ```ts
+	* handler({ message: "build failed" }); // warn "build failed"
+	* ```
+	*/
+	"dev:error"(p) {
+		ctx.log.warn(p.message);
+	},
+	/**
 	* Log the terminal success line with the deployed URL.
 	*
 	* @param p - The deploy:complete event payload.