@podosoft/podokit 1.5.0 → 1.6.0

package/dist/templates/fullstack/apps/api/src/database/migration-readiness.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { pendingMigrationsCheck } from "./migration-readiness";
+
+const set = {
+  directory: "dist/migrations",
+  compiled: true,
+  files: [
+    { file: "1700000000001-First.js", name: "First1700000000001" },
+    { file: "1700000000002-Second.js", name: "Second1700000000002" },
+  ],
+};
+
+describe("pending migrations readiness", () => {
+  it("is down until every listed migration is applied, then stops querying", async () => {
+    const sql = new SQL(":memory:");
+    try {
+      const check = pendingMigrationsCheck(() => sql, set);
+      await expect(check()).rejects.toThrow();
+      await sql`CREATE TABLE "migrations" ("id" integer PRIMARY KEY, "timestamp" bigint, "name" text)`;
+      await sql`INSERT INTO "migrations" ("timestamp", "name") VALUES (1700000000001, 'First1700000000001')`;
+      await expect(check()).rejects.toThrow("1 migrations are pending; run migrate:all: Second1700000000002");
+      await sql`INSERT INTO "migrations" ("timestamp", "name") VALUES (1700000000002, 'Second1700000000002')`;
+      await expect(check()).resolves.toBeUndefined();
+      await sql`DROP TABLE "migrations"`;
+      await expect(check()).resolves.toBeUndefined();
+    } finally {
+      await sql.close();
+    }
+  });
+
+  it("is up without a query when the build has no migrations", async () => {
+    const check = pendingMigrationsCheck(() => { throw new Error("no database"); }, { ...set, files: [] });
+    await expect(check()).resolves.toBeUndefined();
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/migration-readiness.ts

@@ -0,0 +1,25 @@
+import type { SQL } from "bun";
+import type { ReadinessCheck } from "../health/readiness.service";
+import type { MigrationSet } from "./migration-files";
+
+/** Reported down while the database lacks a migration of this build. */
+export const MIGRATIONS_READINESS_CHECK = "migrations";
+
+/**
+ * Compares the migrations table with the build's list. Once every migration is
+ * applied the check stays up without a query: this process never runs one.
+ */
+export function pendingMigrationsCheck(sql: () => SQL, set: MigrationSet): ReadinessCheck {
+  const expected = set.files.flatMap((entry) => entry.name ? [entry.name] : []);
+  let applied = expected.length === 0;
+  return async (): Promise<void> => {
+    if (applied) return;
+    const rows = await sql()<Array<{ name: string }>>`SELECT "name" FROM "migrations"`;
+    const done = new Set(rows.map((row) => row.name));
+    const pending = expected.filter((name) => !done.has(name));
+    if (pending.length > 0) {
+      throw new Error(`${pending.length} migrations are pending; run migrate:all: ${pending.join(", ")}`);
+    }
+    applied = true;
+  };
+}

package/dist/templates/fullstack/apps/api/src/database/run-migrations.spec.ts

@@ -15,6 +15,8 @@ interface LaunchOptions {
   /** Starts the launcher from the directory above the API, like a repository root. */
   fromParent?: boolean;
   files?: Record<string, string>;
+  /** Arguments after the launcher, such as --list. */
+  args?: string[];
 }
 
 /** Runs the migrate:all launcher in an API layout whose entries print their own path. */
@@ -32,7 +34,8 @@ async function launch(entries: string[], nodeEnv: string, body = "", options: La
       mkdirSync(dirname(join(root, path)), { recursive: true });
       writeFileSync(join(root, path), content);
     }
-    const child = Bun.spawn([process.execPath, options.fromParent ? "api/scripts/run-migrations.mjs" : "scripts/run-migrations.mjs"], {
+    const launcher = options.fromParent ? "api/scripts/run-migrations.mjs" : "scripts/run-migrations.mjs";
+    const child = Bun.spawn([process.execPath, launcher, ...(options.args ?? [])], {
       cwd: options.fromParent ? parent : root,
       env: { ...process.env, NODE_ENV: nodeEnv },
       stdout: "pipe",
@@ -68,6 +71,14 @@ describe("migrate:all launcher", () => {
       .toMatchObject({ code: 0, stdout: "dist/migrate.js" });
   });
 
+  it("lists migrations through the application migrator, which needs no auth", async () => {
+    const body = "console.log(process.argv.slice(2).join(' '));\n";
+    expect(await launch(["src/migrate.ts", "src/database/migrate.ts"], "development", body, { args: ["--list"] }))
+      .toMatchObject({ code: 0, stdout: "src/database/migrate.ts\n--list" });
+    expect(await launch(["dist/migrate.js", "dist/database/migrate.js"], "production", body, { args: ["--list"] }))
+      .toMatchObject({ code: 0, stdout: "dist/database/migrate.js\n--list" });
+  });
+
   it("exits with the migration's status", async () => {
     const result = await launch(["src/database/migrate.ts"], "development", "process.exit(3);\n");
     expect(result.code).toBe(3);

package/dist/templates/fullstack/apps/api/src/database/sqlite-migrator.ts

@@ -1,8 +1,6 @@
 import { Database as SqliteDatabase } from "bun:sqlite";
-import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 import type { MigrationInterface, QueryRunner } from "typeorm";
+import { loadMigrations, migrationSet } from "./migration-files";
 
 export interface SqliteMigrationDefinition {
   timestamp: number;
@@ -15,40 +13,8 @@ interface AppliedMigration {
   name: string;
 }
 
-type MigrationConstructor = new () => MigrationInterface;
-
-function isMigration(value: unknown): value is MigrationConstructor {
-  if (typeof value !== "function") return false;
-  const prototype = (value as { prototype?: unknown }).prototype;
-  if (!prototype || typeof prototype !== "object") return false;
-  const record = prototype as Record<string, unknown>;
-  return typeof record.up === "function" && typeof record.down === "function";
-}
-
 async function discoverMigrations(): Promise<SqliteMigrationDefinition[]> {
-  const compiled = join(process.cwd(), "dist", "migrations");
-  const source = join(process.cwd(), "src", "migrations");
-  const directory = process.env.NODE_ENV === "production" && existsSync(compiled)
-    ? compiled
-    : source;
-  if (!existsSync(directory)) return [];
-  const files = readdirSync(directory)
-    .filter((file) => /^\d+-.+\.(?:js|ts)$/.test(file))
-    .sort();
-  const definitions: SqliteMigrationDefinition[] = [];
-  for (const file of files) {
-    const loaded = await import(pathToFileURL(join(directory, file)).href) as Record<string, unknown>;
-    const constructors = Object.values(loaded).filter(isMigration);
-    if (constructors.length !== 1) {
-      throw new Error(`SQLite migration ${file} must export exactly one migration class`);
-    }
-    const timestamp = Number(file.slice(0, file.indexOf("-")));
-    if (!Number.isSafeInteger(timestamp)) throw new Error(`SQLite migration ${file} has an invalid timestamp`);
-    const Constructor = constructors[0];
-    if (!Constructor) throw new Error(`SQLite migration ${file} has no migration class`);
-    definitions.push({ timestamp, migration: new Constructor() });
-  }
-  return definitions;
+  return loadMigrations(migrationSet());
 }
 
 function queryRunner(database: SqliteDatabase): QueryRunner {

package/dist/templates/fullstack/apps/api/src/main.ts

@@ -10,8 +10,8 @@ const app = createApp({ env, services });
 async function bootstrap(): Promise<void> {
   try {
     await services.start();
-    app.listen({ ...apiServerOptions(env), hostname: "0.0.0.0", port: env.PORT });
-    process.stdout.write(`API listening on http://0.0.0.0:${env.PORT}\n`);
+    app.listen({ ...apiServerOptions(env), hostname: env.HOST, port: env.PORT });
+    process.stdout.write(`API listening on http://${env.HOST}:${env.PORT}\n`);
   } catch (error) {
     await services.close();
     throw error;

package/dist/templates/fullstack/apps/api/tsconfig.json

@@ -6,6 +6,8 @@
     "outDir": "dist",
     "rootDir": "src",
     "declaration": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
     "strict": true,
     "noUnusedLocals": true,
     "noUnusedParameters": true,

package/dist/templates/fullstack/apps/web/package.json

@@ -16,7 +16,7 @@
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
-    "@podosoft/podokit-api-client": "^0.9.0",
+    "@podosoft/podokit-api-client": "^0.9.1",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",

package/dist/templates/fullstack/apps/web/src/app.css

@@ -121,3 +121,6 @@
   color: var(--sidebar-foreground);
   font-weight: 400;
 }
+
+/* Application styles: @source paths, theme overrides, and base styles. */
+@import "./app.extensions.css";

package/dist/templates/fullstack/apps/web/src/app.extensions.css

@@ -0,0 +1,11 @@
+/*
+ * Application-owned styles. The managed app.css imports this file last, so rules
+ * here come after PodoKit's theme variables and base styles. Add `@source` for
+ * packages whose built components use Tailwind classes, override variables in
+ * `:root` and `.dark`, or add `@theme` entries and base styles, for example:
+ *
+ *   @source "../../../node_modules/@example/ui/dist";
+ *   :root { --radius: 0.5rem; }
+ *
+ * PodoKit creates this file once and never overwrites it.
+ */

package/dist/templates/fullstack/apps/web/src/lib/components/site-runtime.svelte

@@ -4,4 +4,6 @@
   import { ModeWatcher } from "mode-watcher";
 </script>
 
-<ModeWatcher />
+<!-- `.light` on <html> in light mode lets component libraries that follow a `.dark`
+     or `.light` class, and fall back to the OS setting otherwise, match the theme. -->
+<ModeWatcher lightClassNames={["light"]} />

package/dist/templates/fullstack/apps/web/src/lib/server/api.test.ts

@@ -9,6 +9,7 @@ type Fetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
 function requestEvent(fetch: Fetch): RequestEvent {
   return {
     request: new Request("http://app.localhost/services", { headers: { cookie: "session=abc" } }),
+    url: new URL("http://app.localhost/services"),
     getClientAddress: () => "203.0.113.9",
     fetch,
   } as unknown as RequestEvent;
@@ -50,6 +51,24 @@ describe("serverApiClient", () => {
     expect(headers?.get("x-forwarded-for")).toBe("203.0.113.9");
   });
 
+  it("forwards the public origin only when CORS_ORIGIN lists it", async () => {
+    let headers: Headers | undefined;
+    const api = serverApiClient(requestEvent(async (_input, init) => {
+      headers = new Headers(init?.headers);
+      return Response.json({ ok: true });
+    }));
+
+    vi.stubEnv("CORS_ORIGIN", "https://example.com, http://app.localhost");
+    await api.get("/site/settings");
+    expect(headers?.get("x-forwarded-host")).toBe("app.localhost");
+    expect(headers?.get("x-forwarded-proto")).toBe("http");
+
+    vi.stubEnv("CORS_ORIGIN", "https://example.com");
+    await api.get("/site/settings");
+    expect(headers?.has("x-forwarded-host")).toBe(false);
+    expect(headers?.has("x-forwarded-proto")).toBe(false);
+  });
+
   it("gives up on a call that outlasts BACKEND_TIMEOUT_MS", async () => {
     vi.stubEnv("BACKEND_TIMEOUT_MS", "20");
     stubHealth(async () => new Response("ok"));

package/dist/templates/fullstack/apps/web/src/lib/server/api.ts

@@ -8,6 +8,7 @@ import {
   reportBackendAnswer,
   reportBackendFailure,
   resolveClientIp,
+  setForwardedOrigin,
 } from "./backend-proxy";
 
 /** Thrown without contacting the API while it is known to be unreachable. */
@@ -19,7 +20,8 @@ export class BackendUnavailableError extends Error {
 }
 
 // Server-side client for load functions and hooks: points at the internal
-// backend URL and forwards the incoming request's cookies. Each call is bounded
+// backend URL and forwards the incoming request's cookies, client address, and
+// public origin as the /api proxy does. Each call is bounded
 // by BACKEND_TIMEOUT_MS, so a page renders its fallbacks instead of waiting for
 // an API that does not answer.
 export function serverApiClient(event: RequestEvent): ApiClient {
@@ -31,6 +33,7 @@ export function serverApiClient(event: RequestEvent): ApiClient {
       const headers = new Headers(init?.headers);
       if (cookie) headers.set("cookie", cookie);
       if (clientIp) headers.set("x-forwarded-for", clientIp);
+      setForwardedOrigin(headers, event.url);
       const outage = backendOutageSignal();
       const signals = [AbortSignal.timeout(backendTimeoutMs()), outage];
       if (init?.signal) signals.push(init.signal);

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.test.ts

@@ -7,6 +7,7 @@ import {
   bodyLimitFor,
   checkBackend,
   checkIdleTimeout,
+  configuredPublicOrigins,
   envMilliseconds,
   IN_MEMORY_RESPONSE_BYTES,
   proxyRequest,
@@ -16,12 +17,14 @@ import {
   resolveClientIp,
   sortedBodyLimits,
   sortedProxyTimeouts,
+  upstreamFetchOptions,
   withAppHeaders,
 } from "./backend-proxy";
 
 describe("backend proxy client address handling", () => {
   afterEach(() => {
     vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
   });
 
   it("returns the normalized address from a trusted proxy chain", () => {
@@ -74,6 +77,48 @@ describe("backend proxy client address handling", () => {
     expect(upstreamHeaders?.get("x-forwarded-for")).toBe("203.0.113.9");
   });
 
+  it("forwards the public origin a request came in on when CORS_ORIGIN lists it", async () => {
+    let upstreamHeaders: Headers | undefined;
+    vi.stubGlobal("fetch", async (_input: RequestInfo | URL, init?: RequestInit) => {
+      upstreamHeaders = new Headers(init?.headers);
+      return new Response(null, { status: 204 });
+    });
+    vi.stubEnv("CORS_ORIGIN", "https://example.com,https://mirror.example.com");
+
+    // The adapter builds the request URL from the gateway's forwarded host and
+    // protocol; a caller's own forwarded headers never reach the API.
+    const request = new Request("https://mirror.example.com/api/mcp/info", {
+      headers: { "x-forwarded-host": "attacker.example", "x-forwarded-proto": "http" },
+    });
+    await proxyRequest(request, "http://api:5002/mcp/info");
+
+    expect(upstreamHeaders?.get("x-forwarded-host")).toBe("mirror.example.com");
+    expect(upstreamHeaders?.get("x-forwarded-proto")).toBe("https");
+  });
+
+  it("forwards no origin that CORS_ORIGIN does not list", async () => {
+    let upstreamHeaders: Headers | undefined;
+    vi.stubGlobal("fetch", async (_input: RequestInfo | URL, init?: RequestInit) => {
+      upstreamHeaders = new Headers(init?.headers);
+      return new Response(null, { status: 204 });
+    });
+    vi.stubEnv("CORS_ORIGIN", "https://example.com");
+
+    const request = new Request("http://attacker.example/api/mcp/info", {
+      headers: { "x-forwarded-host": "example.com", "x-forwarded-proto": "https" },
+    });
+    await proxyRequest(request, "http://api:5002/mcp/info");
+
+    expect(upstreamHeaders?.has("x-forwarded-host")).toBe(false);
+    expect(upstreamHeaders?.has("x-forwarded-proto")).toBe(false);
+  });
+
+  it("reads absolute CORS_ORIGIN entries as origins and skips patterns", () => {
+    expect([...configuredPublicOrigins(" https://example.com/ , *.example.com, not a url, http://localhost:5001")])
+      .toEqual(["https://example.com", "http://localhost:5001"]);
+    expect(configuredPublicOrigins("").size).toBe(0);
+  });
+
   // Not forwarding this does not leave the header unset: fetch substitutes its own
   // default, so the API records "node" for every session and the account page shows
   // that as the device for all of them.
@@ -886,6 +931,40 @@ describe("backend proxy application timeouts", () => {
     expect(checks).toBeGreaterThanOrEqual(3);
   });
 
+  it("turns off Bun's fetch idle timeout on a route without a deadline only", async () => {
+    const proxy = await proxyWithTimeouts([{ pathPrefix: "/api/hosts/:hostId/file-transfers", timeoutMs: null }]);
+    const fetch = stubApi(async () => new Response("ok"), async () => Response.json({ done: true }));
+
+    await proxy(
+      new Request("http://app.localhost/api/hosts/h1/file-transfers/t1/commit", { method: "POST", body: "{}" }),
+      "http://api:5002/hosts/h1/file-transfers/t1/commit",
+    );
+    await proxy(new Request("http://app.localhost/api/hosts/h1/notes"), "http://api:5002/hosts/h1/notes");
+
+    const upstream = fetch.mock.calls.filter(([input]) => !String(input).endsWith("/health"));
+    const [commit, notes] = upstream.map(([, init]) => init as RequestInit & { timeout?: unknown });
+    expect(upstream).toHaveLength(2);
+    expect(commit?.timeout).toBe(false);
+    expect(notes).not.toHaveProperty("timeout");
+  });
+
+  it("turns off Bun's fetch idle timeout for a deadline it would cut first", async () => {
+    expect(upstreamFetchOptions(null)).toEqual({ timeout: false });
+    expect(upstreamFetchOptions(600_000)).toEqual({ timeout: false });
+    expect(upstreamFetchOptions(300_000)).toEqual({ timeout: false });
+    expect(upstreamFetchOptions(299_999)).toEqual({});
+    expect(upstreamFetchOptions(30_000)).toEqual({});
+
+    vi.stubEnv("BACKEND_PROXY_TIMEOUT_MS", "300000");
+    vi.stubEnv("CONNECTION_IDLE_TIMEOUT", "0");
+    const proxy = await proxyWithTimeouts([]);
+    const fetch = stubApi(async () => new Response("ok"), async () => Response.json({ done: true }));
+
+    await proxy(new Request("http://app.localhost/api/report"), "http://api:5002/report");
+
+    expect(fetch.mock.calls[0]?.[1]).toHaveProperty("timeout", false);
+  });
+
   it("waits without a deadline on a route with a path parameter", async () => {
     vi.stubEnv("BACKEND_PROXY_TIMEOUT_MS", "20");
     const proxy = await proxyWithTimeouts([{ pathPrefix: "/api/hosts/:hostId/file-transfers", timeoutMs: null }]);

package/dist/templates/fullstack/apps/web/src/lib/server/backend-proxy.ts

@@ -358,6 +358,23 @@ export function proxyTimeoutFor(
   return entry ? entry.timeoutMs : backendProxyTimeoutMs();
 }
 
+/**
+ * Bun's fetch fails a request whose connection sends nothing for its idle
+ * timeout, 300 seconds unless BUN_CONFIG_HTTP_IDLE_TIMEOUT sets another, even
+ * while the proxy still waits for response headers.
+ */
+const FETCH_IDLE_TIMEOUT_MS = 300_000;
+
+/**
+ * Bun's fetch options for a request that waits up to timeoutMs for response
+ * headers. A wait without a deadline, or one Bun's idle timeout would cut
+ * first, turns that timeout off, so only the deadline, the health checks, and
+ * the browser end it. Shorter waits keep Bun's default.
+ */
+export function upstreamFetchOptions(timeoutMs: number | null): { timeout?: false } {
+  return timeoutMs === null || timeoutMs >= FETCH_IDLE_TIMEOUT_MS ? { timeout: false } : {};
+}
+
 /** Bun closes silent connections on a 4-second tick, up to 4 seconds before their idle timeout. */
 const IDLE_TICK_SECONDS = 4;
 /** The longest idle timeout Bun accepts; 0 turns it off. */
@@ -509,6 +526,40 @@ export function normalizeClientIp(address: string | undefined): string | undefin
   return address;
 }
 
+let publicOriginsSource: string | undefined;
+let publicOrigins: ReadonlySet<string> = new Set();
+
+/**
+ * The public web origins listed in CORS_ORIGIN. Wildcard patterns name no single
+ * origin and are skipped, as are entries that are not absolute URLs.
+ */
+export function configuredPublicOrigins(value = process.env.CORS_ORIGIN): ReadonlySet<string> {
+  if (value !== publicOriginsSource) {
+    publicOriginsSource = value;
+    publicOrigins = new Set(
+      (value ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => !entry.includes("*") && URL.canParse(entry))
+        .map((entry) => new URL(entry).origin),
+    );
+  }
+  return publicOrigins;
+}
+
+/**
+ * Tell the API which public origin a request came in on. SvelteKit resolves the
+ * request URL from the Host header, or from the gateway's forwarded headers that
+ * HOST_HEADER and PROTOCOL_HEADER name, so the value is sent only when that origin
+ * is listed in CORS_ORIGIN. The API can then build links for the origin a browser
+ * used without trusting a header a caller wrote.
+ */
+export function setForwardedOrigin(headers: Headers, url: URL): void {
+  if (!configuredPublicOrigins().has(url.origin)) return;
+  headers.set("x-forwarded-host", url.host);
+  headers.set("x-forwarded-proto", url.protocol.slice(0, -1));
+}
+
 export function resolveClientIp(getClientAddress: () => string): string | undefined {
   try {
     return normalizeClientIp(getClientAddress());
@@ -531,8 +582,10 @@ export async function proxyRequest(
   // Forward the resolved client IP so the API (better-auth) can record it.
   const forwardedIp = normalizeClientIp(clientAddress);
   if (forwardedIp) headers.set("x-forwarded-for", forwardedIp);
+  const requestUrl = new URL(request.url);
+  setForwardedOrigin(headers, requestUrl);
 
-  const { pathname } = new URL(request.url);
+  const { pathname } = requestUrl;
   if (!backendReachable()) {
     request.body?.cancel().catch(() => undefined);
     return backendFailure(pathname, 503);
@@ -578,6 +631,7 @@ export async function proxyRequest(
       // closed EventSource or aborted request keeps its API socket open until Bun's
       // fetch pool is exhausted and the web process stops serving requests.
       signal: AbortSignal.any([request.signal, waiting.signal]),
+      ...upstreamFetchOptions(timeoutMs),
     });
   } catch (cause: unknown) {
     // Nobody waits for an answer to a request the browser abandoned.

package/dist/templates/fullstack/apps/web/src/lib/server/proxy-timeouts.ts

@@ -10,7 +10,8 @@
  * headers before it answers 504 BACKEND_TIMEOUT; null waits as long as the API
  * takes. Either way the proxy answers 503 BACKEND_UNAVAILABLE once the API's
  * GET /health stops answering, and the deadline ends when the response headers
- * arrive.
+ * arrive. For null or 300 seconds and more, the proxy also turns off Bun's fetch
+ * idle timeout, which would otherwise end a silent wait after 300 seconds.
  *
  * Bun closes a silent connection up to 4 seconds before its idle timeout, so a
  * longer wait also needs the API's API_IDLE_TIMEOUT and the web server's

package/dist/templates/fullstack/apps/web/tsconfig.json

@@ -6,5 +6,5 @@
     "esModuleInterop": true,
     "skipLibCheck": true
   },
-  "include": ["src", "vite.config.ts"]
+  "include": ["src", "vite.config.ts", "vite.extensions.ts"]
 }

package/dist/templates/fullstack/apps/web/vite.config.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { webSocketProxy } from "./vite.config.ts";
+
+describe("dev-server WebSocket proxy", () => {
+  it("sends each exact path in .podokit/dev.json to the API", () => {
+    const proxy = webSocketProxy(
+      JSON.stringify({ hostname: "app.localhost", webSocketPaths: ["/events/ws", "/agent.v1/ws"] }),
+      "http://api:5002",
+    );
+
+    expect(proxy).toEqual({
+      "^/events/ws(?:\\?.*)?$": { target: "http://api:5002", ws: true, xfwd: true },
+      "^/agent\\.v1/ws(?:\\?.*)?$": { target: "http://api:5002", ws: true, xfwd: true },
+    });
+    const [events] = Object.keys(proxy).map((key) => new RegExp(key));
+    expect(events?.test("/events/ws")).toBe(true);
+    expect(events?.test("/events/ws?token=1")).toBe(true);
+    expect(events?.test("/events/ws/other")).toBe(false);
+    expect(events?.test("/events/wsx")).toBe(false);
+  });
+
+  it("proxies nothing without the file or its paths", () => {
+    expect(webSocketProxy(null)).toEqual({});
+    expect(webSocketProxy(JSON.stringify({ hostname: "app.localhost" }))).toEqual({});
+  });
+
+  it("rejects a path the gateway would reject", () => {
+    expect(() => webSocketProxy(JSON.stringify({ webSocketPaths: ["events/ws"] }))).toThrow(
+      'invalid path: "events/ws"',
+    );
+    expect(() => webSocketProxy(JSON.stringify({ webSocketPaths: "/events/ws" }))).toThrow("must be an array");
+  });
+});

package/dist/templates/fullstack/apps/web/vite.config.ts

@@ -1,8 +1,10 @@
+import { readFileSync } from "node:fs";
 import adapter from "@sveltejs/adapter-bun";
 import { sveltekit } from "@sveltejs/kit/vite";
 import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
 import tailwindcss from "@tailwindcss/vite";
-import { defineConfig } from "vite";
+import { defineConfig, mergeConfig, type ProxyOptions } from "vite";
+import { appSvelteKitConfig, appViteConfig } from "./vite.extensions.ts";
 
 // Inside the dev container, bind to all interfaces and accept local gateway or
 // HTTPS tunnel hostnames. Vite derives HMR's protocol, host, and port from the
@@ -10,16 +12,56 @@ import { defineConfig } from "vite";
 const inDocker = process.env.VITE_DOCKER === "1";
 const publicOrigin = process.env.PODOKIT_BUILD_ORIGIN;
 
-export default defineConfig({
-  plugins: [
-    tailwindcss(),
-    sveltekit({
-      adapter: adapter(),
-      preprocess: vitePreprocess(),
-      ...(publicOrigin ? { paths: { origin: publicOrigin } } : {}),
+/**
+ * Dev-server proxies for the exact WebSocket paths in `.podokit/dev.json`. A
+ * SvelteKit route cannot answer an upgrade, so `bun run dev` sends these paths to
+ * the API the way the `podo dev` gateway and a deployment's edge do. The API must
+ * authenticate each upgrade itself.
+ */
+export function webSocketProxy(
+  devConfig: string | null,
+  target = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002",
+): Record<string, ProxyOptions> {
+  if (devConfig === null) return {};
+  const { webSocketPaths = [] } = JSON.parse(devConfig) as { webSocketPaths?: unknown };
+  if (!Array.isArray(webSocketPaths)) throw new Error(".podokit/dev.json webSocketPaths must be an array of paths");
+  return Object.fromEntries(
+    webSocketPaths.map((path: unknown) => {
+      if (typeof path !== "string" || !/^\/[A-Za-z0-9._~!$&'()+,;=:@/-]+$/.test(path)) {
+        throw new Error(`.podokit/dev.json webSocketPaths has an invalid path: ${JSON.stringify(path)}`);
+      }
+      const exact = `^${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?:\\?.*)?$`;
+      return [exact, { target, ws: true, xfwd: true }];
     }),
-  ],
-  server: {
-    ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
-  },
-});
+  );
+}
+
+function readDevConfig(): string | null {
+  try {
+    return readFileSync(new URL("../../.podokit/dev.json", import.meta.url), "utf8");
+  } catch (cause) {
+    if ((cause as { code?: unknown }).code === "ENOENT") return null;
+    throw cause;
+  }
+}
+
+export default defineConfig((env) =>
+  mergeConfig(
+    {
+      plugins: [
+        tailwindcss(),
+        sveltekit({
+          adapter: adapter(),
+          preprocess: vitePreprocess(),
+          ...appSvelteKitConfig,
+          ...(publicOrigin ? { paths: { ...appSvelteKitConfig.paths, origin: publicOrigin } } : {}),
+        }),
+      ],
+      server: {
+        ...(inDocker ? { host: true, port: 5001, allowedHosts: true } : {}),
+        ...(env.command === "serve" ? { proxy: webSocketProxy(readDevConfig()) } : {}),
+      },
+    },
+    typeof appViteConfig === "function" ? appViteConfig(env) : appViteConfig,
+  ),
+);

package/dist/templates/fullstack/apps/web/vite.extensions.ts

@@ -0,0 +1,23 @@
+import type { Config as SvelteKitConfig } from "@sveltejs/kit/vite";
+import type { UserConfig, UserConfigFnObject } from "vite";
+
+/**
+ * Application-owned additions to the managed vite.config.ts, combined with Vite's
+ * `mergeConfig`: lists such as `plugins` are appended and objects are merged key
+ * by key. Use it for dev-server warmup, dependency optimization, `define`
+ * constants, extra plugins, or extra allowed hosts instead of editing
+ * vite.config.ts. A function receives Vite's `{ command, mode }`. WebSocket paths
+ * listed in `.podokit/dev.json` already reach the API through the dev server.
+ * PodoKit creates this file once and never overwrites it.
+ */
+export const appViteConfig: UserConfig | UserConfigFnObject = {
+  // Transform the pages most sessions open first as soon as the dev server starts:
+  // server: { warmup: { clientFiles: ["./src/routes/+layout.svelte", "./src/routes/+page.svelte"] } },
+};
+
+/**
+ * Application-owned SvelteKit options, such as `alias`, `csrf`, or `prerender`.
+ * PodoKit sets `adapter` and `preprocess`, and `paths.origin` from
+ * PODOKIT_BUILD_ORIGIN at build time.
+ */
+export const appSvelteKitConfig: SvelteKitConfig = {};