@moku-labs/worker 0.4.0 → 0.5.0

package/dist/cli.mjs

@@ -1,9 +1,227 @@
 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).
@@ -59,26 +277,44 @@ const resolveAccount = async (token) => {
 	};
 };
 /**
-* List every kv / d1 / r2 / queue resource that already exists in the account (one request per
-* kind, in parallel), indexed for the preflight diff.
+* 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.
-* @returns The existing resources, indexed by kind.
+* @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);
+* const existing = await listExisting(token, accountId, new Set(["kv", "d1"]));
 * if (existing.kv.has("SESSIONS")) { ... }
 * ```
 */
-const listExisting = async (token, accountId) => {
+const listExisting = async (token, accountId, kinds) => {
 	const base = `/accounts/${accountId}`;
 	const [kv, d1, r2, queues] = await Promise.all([
-		cfGet(token, `${base}/storage/kv/namespaces`),
-		cfGet(token, `${base}/d1/database`),
-		cfGet(token, `${base}/r2/buckets`),
-		cfGet(token, `${base}/queues`)
+		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])),
@@ -88,82 +324,53 @@ const listExisting = async (token, accountId) => {
 	};
 };
 //#endregion
-//#region src/plugins/deploy/infra/plan.ts
+//#region src/plugins/deploy/auth/verify.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.
+* @file deploy plugin — `.env` token verification + account resolution.
 *
-* @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" }
-* ```
+* 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.
 */
-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 };
-	}
-};
+/** 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.";
 /**
-* 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.
+* Verify the `.env` Cloudflare API token and resolve its account.
 *
 * @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.
+* @returns The verified auth status (account + id).
+* @throws {Error} When the token is absent, invalid/expired, or not active.
 * @example
 * ```ts
-* const plan = await planInfra(ctx, manifest);
+* const { account, accountId } = await verifyAuth(ctx);
 * ```
 */
-const planInfra = async (ctx, manifest) => {
-	const token = ctx.env.require("CLOUDFLARE_API_TOKEN");
+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 ? {
+	const account = pinnedAccountId === void 0 || pinnedAccountId === "" ? await resolveAccount(token) : {
 		id: pinnedAccountId,
 		name: pinnedAccountId
-	} : await resolveAccount(token);
-	const existing = await listExisting(token, account.id);
-	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
+	};
+	ctx.emit("auth:verified", {
+		account: account.name,
+		accountId: account.id,
+		scopes: []
 	});
 	return {
+		ok: true,
 		account: account.name,
 		accountId: account.id,
-		exists,
-		missing
+		scopes: []
 	};
 };
 //#endregion
@@ -235,6 +442,411 @@ 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
 /**
@@ -481,6 +1093,25 @@ const provisionResource = async (resource, ci) => {
 	}
 };
 //#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.
@@ -767,21 +1398,38 @@ const createDeployApi = (ctx) => ({
 	* it is used verbatim (universal path).
 	*
 	* @param opts - Optional run options.
-	* @param opts.guided - Enable interactive confirmation steps (wired in a later phase).
-	* @param opts.yes - Auto-confirm all prompts (wired in a later phase).
+	* @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 ?? assembleManifest(ctx);
 		ctx.emit("deploy:phase", { phase: "provision" });
-		const { ids } = await applyPlan(ctx, await planInfra(ctx, manifest));
+		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, ids);
 		const r2Resource = manifest.resources.find((resource) => resource.kind === "r2");
@@ -792,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",
@@ -801,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.
@@ -856,7 +1503,49 @@ const createDeployApi = (ctx) => ({
 	* const { created } = await api.provisionInfra(await api.checkInfra());
 	* ```
 	*/
-	provisionInfra: (plan) => applyPlan(ctx, plan)
+	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.
@@ -873,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,
@@ -887,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.
@@ -902,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
@@ -1005,6 +1801,43 @@ const createCliHooks = (ctx) => ({
 		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.