bosia 0.9.7 → 0.9.9

package/src/core/server.ts

@@ -1,12 +1,11 @@
-import { Elysia } from "elysia";
-
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
+import { Elysia, type ElysiaAdapter } from "elysia";
 
 import { findMatch, compileRoutes, canonicalPathname } from "./matcher.ts";
 import { resolveApiMatch } from "./apiResolver.ts";
 import { apiRoutes, serverRoutes } from "bosia:routes";
 import { loadPlugins } from "./config.ts";
+import { readArtifact } from "./artifacts.ts";
+import { getPlatform, warmingUp } from "./platform.ts";
 import type { RouteManifest } from "./types.ts";
 
 // Pre-compile route patterns into RegExp at startup (shared by renderer.ts via module reference)
@@ -21,17 +20,15 @@ import type { CsrfConfig } from "./csrf.ts";
 import { applyCorsVary, getCorsHeaders, handlePreflight } from "./cors.ts";
 import type { CorsConfig } from "./cors.ts";
 import { buildCspHeader, CSP_DIRECTIVES_TEMPLATE, CSP_ENABLED, generateNonce } from "./csp.ts";
-import { isDev, compress, isStaticPath, distManifest } from "./html.ts";
+import { isDev, compress, isStaticPath, distManifest, PRECOMPRESSED } from "./html.ts";
 import { dev500WithPlugins } from "./dev-500.ts";
 import { OUT_DIR } from "./paths.ts";
 import { stripBase, withBase } from "./basePath.ts";
 import { currentBase } from "./appBase.ts";
-import { pidsOnPort } from "./port.ts";
 import { buildPrerenderManifest, buildStaticManifest, lookupStatic } from "./staticManifest.ts";
 import { dedup } from "./dedup.ts";
 import {
 	CACHE_ENABLED,
-	CACHE_KEYS,
 	CACHE_MAX_BODY_BYTES,
 	buildCompressedVariants,
 	cacheGet,
@@ -52,35 +49,11 @@ import {
 import { getServerTime } from "../lib/utils.ts";
 
 // ─── User Hooks ──────────────────────────────────────────
-// Load user hooks. Production prefers the pre-bundled `${OUT_DIR}/hooks.server.js`
-// emitted by the build (single-file, all relative imports inlined, npm deps left
-// external) so production images can ship only `dist/` + `node_modules/` without
-// the `src/` tree. Dev (and any environment lacking the artifact) falls back to
-// importing `src/hooks.server.ts` directly so edits hot-reload without a build.
+// Set by createApp(). Each runtime entry finds `src/hooks.server.ts` its own
+// way: server.bun.ts imports it off disk, server.workers.ts statically.
 
 let userHandle: Handle | null = null;
 
-const prebuiltHooksPath = join(process.cwd(), OUT_DIR, "hooks.server.js");
-const srcHooksPath = join(process.cwd(), "src", "hooks.server.ts");
-const hooksPath = existsSync(prebuiltHooksPath)
-	? prebuiltHooksPath
-	: existsSync(srcHooksPath)
-		? srcHooksPath
-		: null;
-if (hooksPath) {
-	try {
-		const mod = await import(hooksPath);
-		if (typeof mod.handle === "function") {
-			userHandle = mod.handle as Handle;
-			console.log(
-				`🪝 Loaded ${hooksPath === prebuiltHooksPath ? "dist/hooks.server.js" : "src/hooks.server.ts"}`,
-			);
-		}
-	} catch (err) {
-		console.warn("⚠️  Failed to load hooks.server:", err);
-	}
-}
-
 // ─── Env Helpers ─────────────────────────────────────────
 
 // Headers that must not be baked into a cache entry. Content-Length is
@@ -452,6 +425,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 	const apiMaybe = resolveApiMatch(apiRoutes, path);
 	const apiMatch = apiMaybe instanceof Promise ? await apiMaybe : apiMaybe;
 	if (apiMatch) {
+		if (warmingUp) return new Response(null, { status: 404 });
 		// INVARIANT: once set, releaseApiMiss must fire exactly once — a missed
 		// release() hangs coalesced waiters for the process lifetime. The cache
 		// write path hands it off to its microtask by nulling it first.
@@ -506,6 +480,7 @@ async function resolve(event: RequestEvent): Promise<Response> {
 				// An API route is reached through its own URL, never through the
 				// client router's data endpoint.
 				isDataRequest: false,
+				platform: event.platform,
 			});
 
 			// Redirect returned (not thrown) — convert to a 303 Response.
@@ -937,6 +912,13 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		url.pathname = appPath;
 	}
 
+	// Bun.serve enforces maxRequestBodySize itself; Workers has no such knob, so
+	// check the declared length here. A chunked upload without Content-Length
+	// falls back to the host's own request cap (Cloudflare: 100MB on free).
+	if (BODY_SIZE_LIMIT > 0 && Number(request.headers.get("content-length")) > BODY_SIZE_LIMIT) {
+		return new Response("Payload Too Large", { status: 413 });
+	}
+
 	// Reject new non-health requests during shutdown
 	if (shuttingDown && url.pathname !== "/_health") {
 		return new Response("Service Unavailable", {
@@ -997,8 +979,10 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 			params: {},
 			cookies: cookieJar,
 			isDataRequest: dataReq !== null,
+			platform: getPlatform(),
 		};
-		let response = userHandle ? await userHandle({ event, resolve }) : await resolve(event);
+		let response =
+			userHandle && !warmingUp ? await userHandle({ event, resolve }) : await resolve(event);
 
 		// A hook that short-circuits a data request with a redirect is answering
 		// the client router, which speaks JSON — an unconverted 3xx is followed by
@@ -1048,6 +1032,10 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 		// Apply any Set-Cookie headers accumulated during the request
 		for (const cookie of cookieJar.outgoing) headers.append("Set-Cookie", cookie);
 		return new Response(response.body, {
+			// A Content-Encoding here means the body is already compressed (cache
+			// hit, compress()); rebuilding drops that flag and Workers would
+			// compress it again.
+			...(headers.has("content-encoding") ? PRECOMPRESSED : {}),
 			status: response.status,
 			statusText: response.statusText,
 			headers,
@@ -1063,7 +1051,8 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 					? // Shape-identical to the loader conversion below, so the
 						// router has one payload contract regardless of who redirected.
 						Response.json({ redirect: err.location, status: err.status })
-					: Response.redirect(err.location, err.status)
+					: // Not Response.redirect(): it rejects relative URLs on Workers.
+						new Response(null, { status: err.status, headers: { Location: err.location } })
 				: dataReq
 					? Response.json(
 							{
@@ -1085,7 +1074,7 @@ async function handleRequest(request: Request, url: URL): Promise<Response> {
 							nonce,
 						);
 			// A hook that expires the session before throwing must not lose the
-			// Set-Cookie that does it — `Response.redirect` builds a fresh Response,
+			// Set-Cookie that does it — the redirect above is a fresh Response,
 			// so the jar is re-applied by hand here.
 			if (cookieJar) {
 				for (const cookie of cookieJar.outgoing) out.headers.append("Set-Cookie", cookie);
@@ -1196,27 +1185,32 @@ if (Number.isFinite(MAX_INFLIGHT)) {
 }
 
 // ─── Graceful Shutdown State ──────────────────────────────
+// Drained by the Bun entry on SIGTERM/SIGINT. Never set on Workers, where an
+// isolate has no shutdown to announce.
 
 let shuttingDown = false;
-let firstSignalAt = 0;
 let inFlight = 0;
 let drainResolve: (() => void) | null = null;
 
-// ─── Plugin Loading ───────────────────────────────────────
+/** Stop taking new requests; resolves once in-flight ones have finished. */
+export function beginShutdown(): Promise<void> {
+	shuttingDown = true;
+	if (inFlight === 0) return Promise.resolve();
+	return new Promise<void>((r) => {
+		drainResolve = r;
+	});
+}
 
-const plugins = await loadPlugins(process.cwd());
-if (plugins.length > 0) {
-	console.log(`🔌 Loaded ${plugins.length} plugin(s): ${plugins.map((p) => p.name).join(", ")}`);
+export function inFlightCount(): number {
+	return inFlight;
 }
 
+// ─── Elysia App ───────────────────────────────────────────
+
 // Read the build-time route manifest so plugins.backend.after can introspect routes.
 function loadBuiltManifest(): RouteManifest {
-	const path = `${OUT_DIR}/route-manifest.json`;
-	if (existsSync(path)) {
-		try {
-			return JSON.parse(readFileSync(path, "utf-8"));
-		} catch {}
-	}
+	const built = readArtifact<RouteManifest>("route-manifest.json");
+	if (built) return built;
 	// Fallback: synthesize from runtime arrays (no file paths, just patterns).
 	return {
 		pages: serverRoutes.map((r: any) => ({
@@ -1229,176 +1223,108 @@ function loadBuiltManifest(): RouteManifest {
 			errorPages: [],
 			trailingSlash: r.trailingSlash,
 			cache: r.cache ?? null,
+			prerender: false,
 		})),
 		apis: apiRoutes.map((r: any) => ({ pattern: r.pattern, server: "" })),
 		errorPage: null,
 	};
 }
 
-const routeManifest = loadBuiltManifest();
+export type CreateAppOptions = {
+	/** `handle` from the user's `src/hooks.server.ts`. */
+	handle?: Handle | null;
+	/** Elysia adapter. Omitted → Bun (`Bun.serve`). */
+	adapter?: ElysiaAdapter;
+};
 
-// ─── Elysia App ───────────────────────────────────────────
+/** Build the Elysia app: plugins, the framework's catch-all routes, error handling. */
+export async function createApp(options: CreateAppOptions = {}): Promise<Elysia> {
+	userHandle = options.handle ?? null;
 
-const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : isDev ? 9001 : 9000;
-
-// Elysia's chained generics drift when plugins add routes — track the app as a
-// loose `Elysia` so plugin-extended types stay assignable.
-let app: Elysia = new Elysia({
-	serve: {
-		maxRequestBodySize: BODY_SIZE_LIMIT,
-		idleTimeout: IDLE_TIMEOUT,
-		// Elysia's Bun adapter defaults reusePort:true — SO_REUSEPORT lets a second
-		// server silently join the port and the kernel splits traffic between two
-		// different builds. Opt in only for deliberate N-worker clustering.
-		reusePort: process.env.BOSIA_REUSE_PORT === "1",
-	},
-}) as unknown as Elysia;
-
-// Plugins.backend.before — runs before framework middleware/routes.
-// Plugin-registered routes here BYPASS the framework (CSRF, hooks, etc.).
-// Plugins register their own `.onError()` handlers here. Elysia fires onError
-// handlers in registration order; plugin handlers run first and (when they
-// return undefined) fall through to the base 500 responder chained after this
-// loop. Registering the base responder before the loop would short-circuit
-// every plugin handler.
-for (const plugin of plugins) {
-	if (plugin.backend?.before) {
-		try {
-			app = (await plugin.backend.before(app)) ?? app;
-		} catch (err) {
-			console.error(`❌ Plugin "${plugin.name}" backend.before failed:`, err);
-			throw err;
-		}
+	const plugins = await loadPlugins(process.cwd());
+	if (plugins.length > 0) {
+		console.log(`🔌 Loaded ${plugins.length} plugin(s): ${plugins.map((p) => p.name).join(", ")}`);
 	}
-}
 
-app = app.onError(({ error }) => {
-	if (isDev) console.error("Uncaught server error:", error);
-	else console.error("Uncaught server error:", (error as Error)?.message ?? error);
-	return Response.json({ error: "Internal Server Error" }, { status: 500 });
-}) as unknown as Elysia;
-
-app = app
-	// Static files are served by resolve() with path traversal protection and security headers
-	// SSR pages
-	.get("*", ({ request }: { request: Request }) => {
-		const url = new URL(request.url);
-		return handleRequest(request, url);
-	})
-	// Non-GET catch-alls route every method through handleRequest()
-	.post("*", ({ request }: { request: Request }) => {
-		const url = new URL(request.url);
-		return handleRequest(request, url);
-	})
-	.put("*", ({ request }: { request: Request }) => {
-		const url = new URL(request.url);
-		return handleRequest(request, url);
-	})
-	.patch("*", ({ request }: { request: Request }) => {
-		const url = new URL(request.url);
-		return handleRequest(request, url);
-	})
-	.delete("*", ({ request }: { request: Request }) => {
-		const url = new URL(request.url);
-		return handleRequest(request, url);
-	})
-	.options("*", ({ request }: { request: Request }) => {
-		const url = new URL(request.url);
-		return handleRequest(request, url);
-	}) as unknown as Elysia;
-
-// Plugins.backend.after — runs after framework routes; receives the route manifest.
-for (const plugin of plugins) {
-	if (plugin.backend?.after) {
-		try {
-			app = (await plugin.backend.after(app, { manifest: routeManifest })) ?? app;
-		} catch (err) {
-			console.error(`❌ Plugin "${plugin.name}" backend.after failed:`, err);
-			throw err;
+	// Elysia's chained generics drift when plugins add routes — track the app as a
+	// loose `Elysia` so plugin-extended types stay assignable.
+	let app: Elysia = (options.adapter
+		? new Elysia({ adapter: options.adapter })
+		: new Elysia({
+				serve: {
+					maxRequestBodySize: BODY_SIZE_LIMIT,
+					idleTimeout: IDLE_TIMEOUT,
+					// Elysia's Bun adapter defaults reusePort:true — SO_REUSEPORT lets a second
+					// server silently join the port and the kernel splits traffic between two
+					// different builds. Opt in only for deliberate N-worker clustering.
+					reusePort: process.env.BOSIA_REUSE_PORT === "1",
+				},
+			})) as unknown as Elysia;
+
+	// Plugins.backend.before — runs before framework middleware/routes.
+	// Plugin-registered routes here BYPASS the framework (CSRF, hooks, etc.).
+	// Plugins register their own `.onError()` handlers here. Elysia fires onError
+	// handlers in registration order; plugin handlers run first and (when they
+	// return undefined) fall through to the base 500 responder chained after this
+	// loop. Registering the base responder before the loop would short-circuit
+	// every plugin handler.
+	for (const plugin of plugins) {
+		if (plugin.backend?.before) {
+			try {
+				app = (await plugin.backend.before(app)) ?? app;
+			} catch (err) {
+				console.error(`❌ Plugin "${plugin.name}" backend.before failed:`, err);
+				throw err;
+			}
 		}
 	}
-}
 
-try {
-	app.listen(PORT, () => {
-		// In dev mode the proxy owns the user-facing port — don't print the internal port
-		if (!isDev) console.log(`⬡ Bosia server running at http://localhost:${PORT}`);
-		// Last line of startup on purpose — the cache identity contract is the one
-		// config mistake that leaks one user's page to another, so it stays visible.
-		if (CACHE_ENABLED) {
-			console.log(
-				`\n🔑 Response cache tells users apart ONLY by these cookies/headers: [${CACHE_KEYS.join(", ")}]\n` +
-					`   Using a different session cookie or auth header? Add its name to CACHE_KEYS,\n` +
-					`   or one user's personalised page can be served to another. Routes personalised\n` +
-					`   by anything else should set \`export const cache = false\`.\n` +
-					`   Note: the runtime auto-warns only on uncovered *cookie* reads — it CANNOT\n` +
-					`   detect header-based personalisation, so custom auth headers (X-Api-Key,\n` +
-					`   X-Auth-Token, …) must be added to CACHE_KEYS by hand.\n`,
-			);
-		}
-	});
-} catch (err) {
-	// Bun.serve runs inline inside .listen(), so a failed bind lands here.
-	if ((err as { code?: string })?.code !== "EADDRINUSE") throw err;
-	const [pid] = await pidsOnPort(PORT);
-	console.error(
-		`\n❌ Port ${PORT} is already serving${pid ? ` (pid ${pid})` : ""}.\n` +
-			`   Stop it or set PORT to a free port.\n`,
-	);
-	process.exit(1);
-}
-
-async function shutdown() {
-	if (shuttingDown) {
-		// One ^C arrives multiple times (process group + `bun run` forwarding
-		// to its child) — only a genuinely later signal is a second ^C.
-		if (Date.now() - firstSignalAt > 200) process.exit(130); // second ^C = force quit
-		return;
-	}
-	shuttingDown = true;
-	firstSignalAt = Date.now();
-	// Dev: nothing worth draining — exit instantly so ^C feels immediate.
-	if (isDev) process.exit(0);
-	console.log("⏳ Shutting down — draining in-flight requests...");
-
-	if (inFlight > 0) {
-		await Promise.race([
-			new Promise<void>((r) => {
-				drainResolve = r;
-			}),
-			Bun.sleep(10_000),
-		]);
-	}
+	app = app.onError(({ error }) => {
+		if (isDev) console.error("Uncaught server error:", error);
+		else console.error("Uncaught server error:", (error as Error)?.message ?? error);
+		return Response.json({ error: "Internal Server Error" }, { status: 500 });
+	}) as unknown as Elysia;
 
-	if (inFlight > 0) {
-		console.warn(`⚠️  Force shutdown with ${inFlight} request(s) still in flight`);
-	} else {
-		console.log("✅ All requests drained");
+	app = app
+		// Static files are served by resolve() with path traversal protection and security headers
+		// SSR pages
+		.get("*", ({ request }: { request: Request }) => {
+			const url = new URL(request.url);
+			return handleRequest(request, url);
+		})
+		// Non-GET catch-alls route every method through handleRequest()
+		.post("*", ({ request }: { request: Request }) => {
+			const url = new URL(request.url);
+			return handleRequest(request, url);
+		})
+		.put("*", ({ request }: { request: Request }) => {
+			const url = new URL(request.url);
+			return handleRequest(request, url);
+		})
+		.patch("*", ({ request }: { request: Request }) => {
+			const url = new URL(request.url);
+			return handleRequest(request, url);
+		})
+		.delete("*", ({ request }: { request: Request }) => {
+			const url = new URL(request.url);
+			return handleRequest(request, url);
+		})
+		.options("*", ({ request }: { request: Request }) => {
+			const url = new URL(request.url);
+			return handleRequest(request, url);
+		}) as unknown as Elysia;
+
+	// Plugins.backend.after — runs after framework routes; receives the route manifest.
+	for (const plugin of plugins) {
+		if (plugin.backend?.after) {
+			try {
+				app = (await plugin.backend.after(app, { manifest: loadBuiltManifest() })) ?? app;
+			} catch (err) {
+				console.error(`❌ Plugin "${plugin.name}" backend.after failed:`, err);
+				throw err;
+			}
+		}
 	}
 
-	app.stop(true).then(() => process.exit(0));
-	setTimeout(() => process.exit(1), 2_000);
-}
-
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
-
-// Prod-only fatal handlers. The dev inspector plugin installs its own
-// uncaughtException/unhandledRejection listeners that route errors into the
-// overlay and let the dev runner's crash-backoff restart the process. In prod
-// there's no inspector — without these handlers an unhandled rejection from a
-// background timer or plugin hook orphans the process with no log context.
-// Log + exit(1) lets the orchestrator (Podman/k8s) restart cleanly.
-if (!isDev) {
-	process.on("uncaughtException", (err: Error) => {
-		console.error("[FATAL] uncaughtException:", err?.stack ?? err);
-		process.exit(1);
-	});
-	process.on("unhandledRejection", (reason: unknown) => {
-		const e = reason as Error | undefined;
-		console.error("[FATAL] unhandledRejection:", e?.stack ?? reason);
-		process.exit(1);
-	});
+	return app;
 }
-
-export { app };

package/src/core/server.workers.ts

@@ -0,0 +1,47 @@
+// Cloudflare Workers entry. Same app as server.bun.ts, minus what an isolate
+// doesn't have: no port to bind, no signals, no filesystem. User hooks and
+// config arrive as static imports (workersCodegen.ts), static files are served
+// by Workers Static Assets before the worker runs.
+
+import { CloudflareAdapter } from "elysia/adapter/cloudflare-worker";
+import { config, handle } from "bosia:workers-runtime";
+import { twMerge } from "tailwind-merge";
+
+import { setBosiaConfig } from "./config.ts";
+import type { PlatformEnv } from "./hooks.ts";
+import { disableCompression } from "./html.ts";
+import { getPlatform, setPlatform, setWarmingUp } from "./platform.ts";
+import { createApp } from "./server.ts";
+
+setBosiaConfig(config);
+disableCompression();
+// tailwind-merge builds its class map on the first cn() call (~5ms). Pay it at
+// isolate startup, which has its own CPU budget, not in the first request.
+twMerge("");
+
+const app = (await createApp({ handle, adapter: CloudflareAdapter })).compile();
+
+// The first request in an isolate paid ~5ms of V8 compiling the render path, on a
+// 10ms CPU budget. Render `/` once now instead — startup CPU is budgeted apart.
+// The page renders before fetch() resolves; its body is never read, since
+// startup can't do stream I/O. Any failure only means less is warm, so it's
+// swallowed, and console is muted so it doesn't look like a real request.
+const quiet = { log: console.log, warn: console.warn, error: console.error };
+console.log = console.warn = console.error = () => {};
+setWarmingUp(true);
+try {
+	await app.fetch(new Request("http://localhost/"));
+} catch {
+	// best effort
+} finally {
+	setWarmingUp(false);
+	Object.assign(console, quiet);
+}
+
+export default {
+	fetch(request: Request, env: PlatformEnv): Response | Promise<Response> {
+		// Bindings are one object per isolate — capture on the first request.
+		if (!getPlatform()) setPlatform({ env });
+		return app.fetch(request);
+	},
+};

package/src/core/types/plugin.ts

@@ -10,6 +10,9 @@ type MaybePromise<T> = T | Promise<T>;
 
 export type BuildTarget = "browser" | "bun";
 
+/** Where the production server runs. Not a BuildTarget — that one means client vs server bundle. */
+export type RuntimeTarget = "bun" | "workers";
+
 export interface BuildContext {
 	mode: "production" | "development";
 	cwd: string;
@@ -92,6 +95,8 @@ export type StrictImportsOption =
 export interface BosiaConfig {
 	plugins?: (BosiaPlugin | false | null | undefined)[];
 	strictImports?: StrictImportsOption;
+	/** Production runtime. `"workers"` also emits a Cloudflare Worker + wrangler.jsonc. Default: `"bun"`. */
+	target?: RuntimeTarget;
 }
 
 /** Identity helper for type inference in `bosia.config.ts`. */

package/src/core/types.ts

@@ -34,6 +34,8 @@ export interface PageRoute {
 	 *   `null`  — a `cache` export exists but isn't a literal `false` (dynamic) → import at runtime
 	 */
 	cache: boolean | null;
+	/** `export const prerender = true` in +page.server.ts — its data is a static file at runtime. */
+	prerender: boolean;
 }
 
 /** An API route discovered from the file system */

package/src/core/workersCodegen.ts

@@ -0,0 +1,110 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, join } from "path";
+
+import { readArtifact } from "./artifacts.ts";
+import { findConfigPath } from "./config.ts";
+import { OUT_DIR, toPosix } from "./paths.ts";
+
+// ─── Workers Codegen ─────────────────────────────────────
+// Cloudflare Workers has no filesystem and no dynamic `import(<path>)`, so
+// everything the Bun server reads or imports off disk at boot is generated
+// into `.bosia/` as static code the worker bundle can inline.
+
+// Build artifacts the runtime reads at boot. Keep in sync with readArtifact() callers.
+export const RUNTIME_ARTIFACTS = ["manifest.json", "app-html.json", "route-manifest.json"];
+
+const HEADER = "// Auto-generated by Bosia. Do not edit.\n";
+
+function writeBosiaFile(cwd: string, name: string, code: string): string {
+	const target = join(cwd, ".bosia", name);
+	mkdirSync(join(cwd, ".bosia"), { recursive: true });
+	writeFileSync(target, HEADER + code);
+	return target;
+}
+
+/**
+ * Write `.bosia/artifacts.ts` — a filesystem-free drop-in for artifacts.ts with
+ * every runtime artifact inlined. Call after the build has written them.
+ */
+export function generateArtifactsModule(outDir: string = OUT_DIR, cwd = process.cwd()): string {
+	const files: Record<string, unknown> = {};
+	for (const name of RUNTIME_ARTIFACTS) {
+		const value = readArtifact(name, outDir);
+		if (value !== undefined) files[name] = value;
+	}
+	return writeBosiaFile(
+		cwd,
+		"artifacts.ts",
+		`const files: Record<string, unknown> = ${JSON.stringify(files)};\n\n` +
+			"export function readArtifact<T>(name: string, _dir?: string): T | undefined {\n" +
+			"\treturn files[name] as T | undefined;\n" +
+			"}\n",
+	);
+}
+
+/**
+ * Write `.bosia/runtime.workers.ts` (`bosia:workers-runtime`) — static imports
+ * of the app's `src/hooks.server.ts` and `bosia.config.*`, which the Bun server
+ * loads with a dynamic `import()` of an absolute path.
+ */
+export function generateWorkersRuntime(cwd = process.cwd()): string {
+	const hooksPath = join(cwd, "src", "hooks.server.ts");
+	const configPath = findConfigPath(cwd);
+	const lines: string[] = [];
+	if (existsSync(hooksPath)) {
+		lines.push(`import * as hooks from ${JSON.stringify(toPosix(hooksPath))};`);
+		lines.push(`export const handle = typeof hooks.handle === "function" ? hooks.handle : null;`);
+	} else {
+		lines.push("export const handle = null;");
+	}
+	if (configPath) {
+		lines.push(`export { default as config } from ${JSON.stringify(toPosix(configPath))};`);
+	} else {
+		lines.push("export const config = {};");
+	}
+	return writeBosiaFile(cwd, "runtime.workers.ts", lines.join("\n") + "\n");
+}
+
+/**
+ * Write `wrangler.jsonc` at the app root, unless one exists — it's where the
+ * user adds bindings (D1, KV, vars), so a rebuild must never overwrite it.
+ * Returns the path when written, null when left alone.
+ */
+export function generateWranglerConfig(
+	cwd = process.cwd(),
+	outDir: string = OUT_DIR,
+): string | null {
+	const target = join(cwd, "wrangler.jsonc");
+	if (
+		existsSync(target) ||
+		existsSync(join(cwd, "wrangler.json")) ||
+		existsSync(join(cwd, "wrangler.toml"))
+	)
+		return null;
+	let name = basename(cwd);
+	try {
+		name = JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8")).name || name;
+	} catch {}
+	// Worker names: lowercase letters, digits and dashes. Drops an npm @scope/.
+	name =
+		name
+			.replace(/^@[^/]+\//, "")
+			.toLowerCase()
+			.replace(/[^a-z0-9-]+/g, "-") || "bosia-app";
+	const dir = toPosix(outDir).replace(/^\.\//, "");
+	const config = {
+		name,
+		main: `./${dir}/worker/index.js`,
+		compatibility_date: "2025-09-01",
+		compatibility_flags: ["nodejs_compat"],
+		// Served before the worker runs; misses fall through to it.
+		assets: { directory: `./${dir}/static` },
+	};
+	writeFileSync(
+		target,
+		"// Generated once by `bosia build --target=workers`. Yours to edit — add bindings here.\n" +
+			JSON.stringify(config, null, "\t") +
+			"\n",
+	);
+	return target;
+}