@podosoft/podokit 1.4.2 → 1.6.0

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.routes.spec.ts

@@ -11,8 +11,6 @@ const config = {
   authTtlSeconds: 60,
   authLimit: 20,
   runtimeLimit: 1000,
-  trustedProxyHops: 0,
-  proxyHeader: "x-forwarded-for",
   storageTimeoutMs: 100,
   unavailableRetryAfterSeconds: 1,
 };
@@ -25,7 +23,7 @@ function context(path: string, method = "GET"): { value: RequestGuardContext; he
     headers,
     value: {
       request: new Request(`http://localhost${path}`, { method }),
-      remoteAddress: "127.0.0.1",
+      clientAddress: "127.0.0.1",
       setHeader: (name, value) => { headers[name.toLowerCase()] = value; },
     },
   };
@@ -50,11 +48,49 @@ describe("RateLimitRoutes", () => {
     expect(routes.resolve("GET", "/other")).toBeUndefined();
   });
 
+  test("matches a :name parameter against exactly one non-empty segment", () => {
+    const routes = new RateLimitRoutes(60);
+    const transfers = { name: "file-transfers", limit: 600 };
+    routes.register({ pathPrefix: "/hosts/:hostId/file-transfers", profile: transfers });
+
+    expect(routes.resolve("PUT", "/hosts/h1/file-transfers/t1/chunks/3")).toMatchObject(transfers);
+    expect(routes.resolve("GET", "/hosts/h1/file-transfers")).toMatchObject(transfers);
+    expect(routes.resolve("GET", "/hosts/h1/file-transfers/")).toMatchObject(transfers);
+    expect(routes.resolve("GET", "/hosts/h1/file-transfers-old")).toBeUndefined();
+    expect(routes.resolve("GET", "/hosts/file-transfers")).toBeUndefined();
+    expect(routes.resolve("GET", "/hosts//file-transfers")).toBeUndefined();
+    expect(routes.resolve("GET", "/hosts/h1/h2/file-transfers")).toBeUndefined();
+  });
+
+  test("prefers more segments, then a literal segment over a parameter from the left", () => {
+    const routes = new RateLimitRoutes(60);
+    routes.register({ pathPrefix: "/hosts/:hostId/:section/:id", profile: { name: "deep", limit: 1 } });
+    routes.register({ pathPrefix: "/hosts/:hostId/files", profile: { name: "files", limit: 2 } });
+    routes.register({ pathPrefix: "/hosts/local/:section", profile: { name: "local", limit: 3 } });
+    routes.register({ pathPrefix: "/hosts", profile: { name: "hosts", limit: 4 } });
+
+    expect(routes.resolve("GET", "/hosts/local/files/1")).toMatchObject({ name: "deep" });
+    expect(routes.resolve("GET", "/hosts/local/files")).toMatchObject({ name: "local" });
+    expect(routes.resolve("GET", "/hosts/h2/files")).toMatchObject({ name: "files" });
+    expect(routes.resolve("GET", "/hosts/h2/logs")).toMatchObject({ name: "hosts" });
+
+    // Equal specificity falls back to the method, then the latest registration.
+    routes.register({ method: "GET", pathPrefix: "/hosts/:a/logs", profile: "exempt" });
+    routes.register({ pathPrefix: "/hosts/:b/logs", profile: { name: "logs", limit: 5 } });
+    expect(routes.resolve("GET", "/hosts/h2/logs")).toBe("exempt");
+    expect(routes.resolve("POST", "/hosts/h2/logs")).toMatchObject({ name: "logs" });
+  });
+
   test("rejects invalid routes and conflicting budgets under one name", () => {
     const routes = new RateLimitRoutes(60);
     expect(() => routes.register({ pathPrefix: "uploads", profile: "exempt" })).toThrow("absolute path");
     expect(() => routes.register({ pathPrefix: "/a?b", profile: "exempt" })).toThrow("absolute path");
     expect(() => routes.register({ pathPrefix: "/a//b", profile: "exempt" })).toThrow("absolute path");
+    expect(() => routes.register({ pathPrefix: "/a/../b", profile: "exempt" })).toThrow('".." segments');
+    expect(() => routes.register({ pathPrefix: "/a/*", profile: "exempt" })).toThrow("not wildcards");
+    for (const parameter of [":", ":1st", ":host-id", ":a:b"]) {
+      expect(() => routes.register({ pathPrefix: `/hosts/${parameter}/x`, profile: "exempt" })).toThrow("parameter");
+    }
     expect(() => routes.register({ method: "GET /", pathPrefix: "/a", profile: "exempt" })).toThrow("method");
     expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a:b", limit: 1 } })).toThrow("name");
     expect(() => routes.register({ pathPrefix: "/a", profile: { name: "a", limit: 0 } })).toThrow("limit");
@@ -83,6 +119,28 @@ describe("RateLimitRoutes", () => {
 });
 
 describe("RateLimiter route profiles", () => {
+  test("advertises the built-in budget of each default route", async () => {
+    const limiter = new RateLimiter(
+      config,
+      { resolve: async () => "session:test" } as unknown as RateLimitIdentity,
+      { increment: async () => ({ count: 1, retryAfterSeconds: 60 }) },
+    );
+    const ceiling = async (path: string, method = "GET"): Promise<string | undefined> => {
+      const request = context(path, method);
+      await limiter.enforce(request.value);
+      return request.headers["ratelimit-limit"];
+    };
+
+    expect(await ceiling("/api/auth/get-session")).toBe("1000");
+    expect(await ceiling("/site/settings")).toBe("1000");
+    expect(await ceiling("/api/auth/admin/list-users")).toBe("300");
+    expect(await ceiling("/api/auth/admin/ban-user", "POST")).toBe("20");
+    expect(await ceiling("/api/auth/sign-out", "POST")).toBe("20");
+    expect(await ceiling("/api/auth/sign-in/email", "POST")).toBe("20");
+    expect(await ceiling("/site/settings", "PUT")).toBe("300");
+    expect(await ceiling("/account/capabilities")).toBe("300");
+  });
+
   test("counts a registered route in its own bucket and skips exempt routes", async () => {
     const increment = mock(async (_key: string, _ttlSeconds: number) => ({ count: 1, retryAfterSeconds: 30 }));
     const limiter = new RateLimiter(

package/dist/templates/modules/rate-limit/files/apps/api/src/rate-limit/rate-limit.routes.ts

@@ -8,14 +8,18 @@ import type { RateLimitConfig } from "./rate-limit.config";
 /** A budget with its window resolved, or "exempt". */
 export type ResolvedRateLimitProfile = Required<RateLimitProfile> | "exempt";
 
+/** A literal path segment, or null for a `:name` parameter. */
+type Segment = string | null;
+
 interface RouteEntry {
   method?: string;
-  prefix: string;
+  segments: Segment[];
   profile: ResolvedRateLimitProfile;
 }
 
 const PROFILE_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const METHOD = /^[A-Z]+$/;
+const PARAMETER = /^:[A-Za-z_][A-Za-z0-9_]*$/;
 
 function positiveInteger(value: number | undefined, label: string): void {
   if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
@@ -23,15 +27,47 @@ function positiveInteger(value: number | undefined, label: string): void {
   }
 }
 
-function normalizePrefix(prefix: string): string {
+function parsePrefix(prefix: string): Segment[] {
   if (!prefix.startsWith("/") || /[?#\s]/.test(prefix) || prefix.includes("//")) {
     throw new Error(`Rate limit path prefix must be an absolute path: ${prefix}`);
   }
-  return prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  if (prefix.includes("*")) {
+    throw new Error(`Rate limit path prefix takes ":name" parameters, not wildcards: ${prefix}`);
+  }
+  const base = prefix.length > 1 && prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  return base === "/"
+    ? []
+    : base.slice(1).split("/").map((segment) => {
+        if (segment === "." || segment === "..") {
+          throw new Error(`Rate limit path prefix must not contain "." or ".." segments: ${prefix}`);
+        }
+        if (!segment.startsWith(":")) return segment;
+        if (!PARAMETER.test(segment)) {
+          throw new Error(`Rate limit path parameter must be ":" and a name such as ":hostId": ${prefix}`);
+        }
+        return null;
+      });
+}
+
+/** Whole-segment prefix match; a parameter matches one non-empty segment. */
+function covers(segments: Segment[], path: string[]): boolean {
+  return (
+    path.length >= segments.length &&
+    segments.every((segment, index) => (segment === null ? path[index] !== "" : segment === path[index]))
+  );
 }
 
-function covers(prefix: string, path: string): boolean {
-  return prefix === "/" || path === prefix || path.startsWith(`${prefix}/`);
+/**
+ * Below zero when `a` is more specific: more segments, then, from the left, a
+ * literal segment before a parameter.
+ */
+function compareSpecificity(a: Segment[], b: Segment[]): number {
+  if (a.length !== b.length) return b.length - a.length;
+  for (let index = 0; index < a.length; index += 1) {
+    const literalA = a[index] !== null;
+    if (literalA !== (b[index] !== null)) return literalA ? -1 : 1;
+  }
+  return 0;
 }
 
 /**
@@ -50,24 +86,21 @@ export class RateLimitRoutes implements RateLimitRouteRegistry {
     if (method !== undefined && !METHOD.test(method)) {
       throw new Error(`Rate limit route method is invalid: ${route.method}`);
     }
-    const prefix = normalizePrefix(route.pathPrefix);
+    const segments = parsePrefix(route.pathPrefix);
     const profile = route.profile === "exempt" ? "exempt" : this.budget(route.profile);
-    this.entries.push({ ...(method ? { method } : {}), prefix, profile });
+    this.entries.push({ ...(method ? { method } : {}), segments, profile });
   }
 
   /** The most specific registered profile for a request, if any route matches. */
   resolve(method: string, path: string): ResolvedRateLimitProfile | undefined {
+    const pathSegments = path.split("/").slice(1);
     let best: RouteEntry | undefined;
     for (const entry of this.entries) {
       if (entry.method !== undefined && entry.method !== method) continue;
-      if (!covers(entry.prefix, path)) continue;
-      // The longer prefix wins, then a route with a method, then the later one.
-      if (
-        !best ||
-        entry.prefix.length > best.prefix.length ||
-        (entry.prefix.length === best.prefix.length &&
-          (entry.method !== undefined || best.method === undefined))
-      ) {
+      if (!covers(entry.segments, pathSegments)) continue;
+      // The more specific prefix wins, then a route with a method, then the later one.
+      const order = best ? compareSpecificity(entry.segments, best.segments) : -1;
+      if (order < 0 || (order === 0 && (entry.method !== undefined || best?.method === undefined))) {
         best = entry;
       }
     }

package/dist/templates/modules/rate-limit/files/tests/api/rate-limit.api.spec.ts

@@ -1,4 +1,10 @@
-import { expect, test, type APIResponse } from "@playwright/test";
+import {
+  expect,
+  test,
+  type APIRequestContext,
+  type APIResponse,
+  type PlaywrightWorkerArgs,
+} from "@playwright/test";
 
 const base = process.env.E2E_BASE_URL ?? "http://localhost:5001";
 const origin = { origin: base };
@@ -19,20 +25,42 @@ const limit = Number(process.env.RATE_LIMIT_MAX ?? 300);
 const authLimit = Number(process.env.RATE_LIMIT_AUTH_MAX ?? 20);
 const runtimeLimit = Number(process.env.RATE_LIMIT_RUNTIME_MAX ?? 1000);
 
-async function session(
-  playwright: import("@playwright/test").PlaywrightWorkerArgs["playwright"],
-) {
-  const ctx = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  const signup = await ctx.post("/api/auth/sign-up/email", {
-    data: {
-      email,
-      password: "Podokit3e-Str0ng!pw",
-      name: "Rate Limit",
-    },
+type Playwright = PlaywrightWorkerArgs["playwright"];
+const password = "Podokit3e-Str0ng!pw";
+
+function uniqueEmail(): string {
+  return `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
+}
+
+// Sign-ups and sign-ins are authentication writes. From an anonymous client the
+// limiter counts them against the per-address budget that the setup project's
+// and every other spec's sign-ins share. Only this worker's first one is
+// anonymous: the later ones carry its session cookie, so the limiter counts them
+// against that session instead.
+let carrier: string | undefined;
+
+/** Run one authentication write and return a context holding the session it set. */
+async function authenticated(
+  playwright: Playwright,
+  path: "/api/auth/sign-up/email" | "/api/auth/sign-in/email",
+  data: Record<string, string>,
+): Promise<APIRequestContext> {
+  const writer = await playwright.request.newContext({
+    baseURL: base,
+    extraHTTPHeaders: { ...origin, ...(carrier ? { cookie: carrier } : {}) },
   });
-  expect(signup.ok()).toBeTruthy();
-  return ctx;
+  const response = await writer.post(path, { data });
+  expect(response.ok(), `${path}: ${response.status()}`).toBeTruthy();
+  const storageState = await writer.storageState();
+  await writer.dispose();
+  const token = storageState.cookies.find((cookie) => cookie.name.endsWith("session_token"));
+  carrier ??= token ? `${token.name}=${token.value}` : undefined;
+  return playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin, storageState });
+}
+
+/** A new account, signed in. */
+async function session(playwright: Playwright, email = uniqueEmail()): Promise<APIRequestContext> {
+  return authenticated(playwright, "/api/auth/sign-up/email", { email, password, name: "Rate Limit" });
 }
 
 test("rate limit: health probes stay available while ordinary routes return 429 @smoke", async ({
@@ -70,32 +98,39 @@ test("rate limit: health probes stay available while ordinary routes return 429
   await ctx.dispose();
 });
 
-test("rate limit: each signed session has its own counter and forged sessions do not", async ({
+test("rate limit: a user's sessions share one counter and forged sessions do not get one", async ({
   playwright,
 }) => {
-  const email = `rate-limit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@example.com`;
-  const password = "Podokit3e-Str0ng!pw";
-  const first = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await first.post("/api/auth/sign-up/email", { data: { email, password, name: "Rate Limit" } })).ok()).toBeTruthy();
+  const email = uniqueEmail();
+  const first = await session(playwright, email);
   const probe = await first.get("/api/cache/rate-limit-probe");
   test.skip(probe.status() >= 500, "throttler storage (redis) not reachable");
   const remaining = (response: APIResponse): number => Number(response.headers()["ratelimit-remaining"]);
   const ceiling = Number(probe.headers()["ratelimit-limit"]);
-  expect(remaining(probe)).toBe(ceiling - 1);
 
-  // The signed bearer form of the same session shares its counter.
+  // A second sign-in of the same user, and the signed bearer form of the first
+  // session. The probe requires a session, so each request below resolves it; a
+  // session counts under its user from the request after the API first resolves
+  // it (or from that request when authentication runs before the limiter).
+  const second = await authenticated(playwright, "/api/auth/sign-in/email", { email, password });
   const cookie = (await first.storageState()).cookies.find((c) => c.name.endsWith("session_token"));
   expect(cookie, "sign-up set a session cookie").toBeTruthy();
   const bearer = await playwright.request.newContext({
     baseURL: base,
     extraHTTPHeaders: { ...origin, authorization: `Bearer ${cookie?.value ?? ""}` },
   });
-  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 2);
+  await second.get("/api/cache/rate-limit-probe");
+
+  // Both sessions now draw from one budget: each request lowers what the next
+  // one, from either session, has left.
+  const fromFirst = remaining(await first.get("/api/cache/rate-limit-probe"));
+  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 1);
+  expect(remaining(await bearer.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 2);
+  expect(remaining(await first.get("/api/cache/rate-limit-probe"))).toBe(fromFirst - 3);
 
-  // Counters follow the session, not the user: signing in again starts a new one.
-  const second = await playwright.request.newContext({ baseURL: base, extraHTTPHeaders: origin });
-  expect((await second.post("/api/auth/sign-in/email", { data: { email, password } })).ok()).toBeTruthy();
-  expect(remaining(await second.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
+  // Another user has a budget of their own.
+  const other = await session(playwright);
+  expect(remaining(await other.get("/api/cache/rate-limit-probe"))).toBe(ceiling - 1);
 
   // A session cookie without a valid signature is counted with anonymous traffic
   // from the same client address instead of receiving a fresh counter. The cache
@@ -113,12 +148,13 @@ test("rate limit: each signed session has its own counter and forged sessions do
     expect(remaining(after)).toBeLessThan(remaining(before));
   }).toPass({ timeout: 10_000 });
 
-  for (const context of [first, bearer, second, forged, anonymous]) await context.dispose();
+  for (const context of [first, second, bearer, other, forged, anonymous]) await context.dispose();
 });
 
 test("rate limit: session reads do not consume the strict authentication budget", async ({
   playwright,
 }) => {
+  test.skip(authLimit > 1000, "the authentication budget is too large to exhaust here");
   const ctx = await session(playwright);
   for (let i = 0; i < authLimit + 5; i++) {
     const response = await ctx.get("/api/auth/get-session");

package/dist/templates/modules/rate-limit/module.manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "rate-limit",
   "manifestVersion": 3,
-  "description": "Provider-neutral Elysia request limiting by validated API key, signed-in session, or trusted-proxy client address.",
+  "description": "Provider-neutral Elysia request limiting by validated API key, signed-in user, or trusted-proxy client address.",
   "requires": ["api-key-auth"],
   "requiresCapabilities": ["cache"],
   "targetApp": "api",
@@ -19,9 +19,6 @@
     "RATE_LIMIT_AUTH_MAX=20",
     "# higher ceiling for SSR runtime settings and session reads",
     "RATE_LIMIT_RUNTIME_MAX=1000",
-    "# trust no proxy hop by default; set the exact production proxy depth",
-    "RATE_LIMIT_TRUSTED_PROXY_HOPS=0",
-    "RATE_LIMIT_PROXY_HEADER=x-forwarded-for",
     "RATE_LIMIT_STORAGE_TIMEOUT_MS=1000",
     "RATE_LIMIT_UNAVAILABLE_RETRY_AFTER=1"
   ],
@@ -40,20 +37,20 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### rate-limit\n- Every request counts against a per-caller budget (general, `/api/auth`, or runtime reads); exceeded limits return 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`.\n- Give routes that legitimately send many requests, such as upload chunks, their own budget instead of raising `RATE_LIMIT_MAX`: `services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method: \"PUT\", pathPrefix: \"/uploads\", profile: { name: \"uploads\", limit: 3000 } })` (`RATE_LIMIT_ROUTES` from `@podosoft/podokit-runtime`). Register from a module's `plugin` factory or `configureServices()` in `app.extensions.ts`; the most specific prefix wins, and `profile: \"exempt\"` skips limiting.\n- Prefixes are API paths (`/uploads`, not the web proxy's `/api/uploads`); Better Auth routes keep `/api/auth`.\n"
+      "text": "### rate-limit\n- Every request counts against a per-caller budget (general, `/api/auth`, or runtime reads), keyed by API key, then signed-in user, then client address; exceeded limits return 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`. A user's sessions share one budget once the API has resolved them for a request.\n- Give routes that legitimately send many requests, such as upload chunks, their own budget instead of raising `RATE_LIMIT_MAX`: `services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method: \"PUT\", pathPrefix: \"/uploads\", profile: { name: \"uploads\", limit: 3000 } })` (`RATE_LIMIT_ROUTES` from `@podosoft/podokit-runtime`). Register from a module's `plugin` factory or `configureServices()` in `app.extensions.ts`; the most specific prefix wins (more segments, then a literal segment over a `:name` parameter), and `profile: \"exempt\"` skips limiting.\n- Prefixes are API paths (`/uploads`, not the web proxy's `/api/uploads`); Better Auth routes keep `/api/auth`. A `:name` segment matches one path segment, as in `/hosts/:hostId/file-transfers`.\n"
     }
   ],
   "instructions": [
     "Configure the selected cache provider before enabling request limits.",
     "Tune the general, authentication, and runtime limits in .env.",
     "Give each deployment that shares Redis a distinct RATE_LIMIT_KEY_PREFIX.",
-    "Set RATE_LIMIT_TRUSTED_PROXY_HOPS to the exact number of trusted reverse proxies; keep 0 for direct API access.",
-    "Validated X-API-Key clients and signed-in sessions receive independent opaque counters; other traffic uses the trusted client address.",
-    "Sessions are recognized by verifying the Better Auth cookie or bearer signature with BETTER_AUTH_SECRET, without a database read, so limits apply per session rather than per user.",
+    "Requests without a validated API key or session count by the client address the API resolves from TRUSTED_PROXY_HOPS and TRUSTED_PROXY_HEADER, which audit entries and Better Auth sessions use too.",
+    "Validated X-API-Key clients and signed-in users receive independent opaque counters; other traffic uses the resolved client address.",
+    "Sessions are recognized by verifying the Better Auth cookie or bearer signature with BETTER_AUTH_SECRET, without a database read, and count under their user once the API has resolved them for a request, so limits apply per user.",
     "Exceeded limits return RATE_LIMIT_EXCEEDED with HTTP 429 and Retry-After. Cache failures return RATE_LIMIT_UNAVAILABLE with HTTP 503.",
     "Register a RateLimitIdentityExtension under RATE_LIMIT_IDENTITY_EXTENSION in app.extensions.ts for another validated machine-key source.",
     "GET /health and GET /health/ready bypass request quotas so orchestrator probes remain reliable.",
-    "Give a route its own budget or exempt it with services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method, pathPrefix, profile }) from a module's plugin factory or configureServices() in app.extensions.ts; the most specific prefix wins.",
+    "Give a route its own budget or exempt it with services.tryResolve(RATE_LIMIT_ROUTES)?.register({ method, pathPrefix, profile }) from a module's plugin factory or configureServices() in app.extensions.ts; a :name segment matches one path segment, and the most specific prefix wins.",
     "Redis counters are shared across replicas; memory counters require one API replica."
   ]
 }

package/dist/templates/modules/sse/files/tests/api/events.api.spec.ts

@@ -6,7 +6,7 @@ const origin = { origin: base };
 // The administrator seeded by the admin-dashboard Playwright setup. Inlined so this
 // spec also compiles in apps that do not install that module.
 const admin = {
-  email: "admin@example.com",
+  email: process.env.E2E_ADMIN_EMAIL || "admin@example.com",
   password: process.env.E2E_ADMIN_PASSWORD || "Podokit3e-Str0ng!pw",
 };
 

package/dist/templates/todo/AGENTS.md

@@ -10,8 +10,9 @@ A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 
 - `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + `{{databaseProvider}}`, merged OpenAPI at `/api-docs`.
 - `apps/web` — **SvelteKit** frontend (`{{projectName}}-web`), Tailwind v4 + shadcn-svelte + typesafe-i18n.
-- `infra/` — Docker Compose references for external services and example k3s manifests.
-- `.podokit/` — generation metadata plus application-owned development and deployment profiles.
+- `infra/` — provider-aware Docker Compose and example k3s manifests.
+- `.podokit/` — PodoKit generation metadata plus application-owned development and
+  deployment profiles (see "PodoKit tooling" below).
 - **Todo example**: `apps/api/src/todos/` (Elysia plugin, Bun.SQL repository, and migration) and the todo UI in `apps/web/src/routes/` show the end-to-end patterns to follow.
 
 ## Setup & commands
@@ -49,7 +50,32 @@ Merge added module settings from `.env.example` into an existing `.env`.
   managed lists. Cap a route's request body in the app-owned
   `apps/web/src/lib/server/body-limits.ts` (`APP_BODY_LIMITS`, 413
   `PAYLOAD_TOO_LARGE`). `BODY_SIZE_LIMIT` is the ceiling for every web route, so
-  uploads larger than it must use a direct API path (`apiPaths`) instead.
+  uploads larger than it must use a direct API path (`apiPaths`) instead. Give a
+  route a longer, shorter, or no response deadline in the app-owned
+  `apps/web/src/lib/server/proxy-timeouts.ts` (`APP_PROXY_TIMEOUTS`, `null` for
+  none); never edit the managed deadline. Both lists take path prefixes with
+  `:name` parameters, such as `/api/hosts/:hostId/file-transfers`, and the most
+  specific prefix wins.
+- Server-side API calls (`serverApiClient`) give up after `BACKEND_TIMEOUT_MS`
+  (2000), and the proxy answers 504 `BACKEND_TIMEOUT` when the API sends no
+  response headers within `BACKEND_PROXY_TIMEOUT_MS` (30000). Once the API's
+  `GET /health` stops answering too, calls throw `BackendUnavailableError` and the
+  proxy answers 503 `BACKEND_UNAVAILABLE` at once until it answers again. Handle
+  any non-`ApiError` failure in a load function as a temporary outage. The API
+  (`API_IDLE_TIMEOUT`) and the built web server (`CONNECTION_IDLE_TIMEOUT`) close
+  a connection that sends nothing for that many seconds (35 each): raise both
+  with any longer `BACKEND_PROXY_TIMEOUT_MS` or `APP_PROXY_TIMEOUTS` entry, more
+  than 4 above it, or set `0` when a route has no deadline. The proxy refuses to
+  load when `CONNECTION_IDLE_TIMEOUT` cannot cover a deadline.
+- Read a caller's address in the API with `clientAddressOf(request.headers)` from
+  `apps/api/src/core/client-address.ts`, never from `X-Forwarded-For` directly. The
+  API resolves it once per request from `TRUSTED_PROXY_HOPS` (1: the web proxy) and
+  `TRUSTED_PROXY_HEADER`; Better Auth sessions, audit entries, and rate limits use
+  the same address.
+- `GET /healthz` (`apps/web/src/routes/healthz/+server.ts`) is the web server's own
+  health route for the Kubernetes probes, the Compose healthcheck, and the image
+  `HEALTHCHECK`. Keep it free of API calls, so an API outage does not take the web
+  out of service.
 - When the root layout or a server hook fails, such as with 503 while the API is
   down, SvelteKit serves the app-owned `apps/web/src/error.html`. It is plain HTML
   with inline styles: no components, app CSS, scripts, or assets, and only the
@@ -61,7 +87,11 @@ Merge added module settings from `.env.example` into an existing `.env`.
   Better Auth schema before the application migrations. `{{apiRun}} migration:run` runs
   only the application migrations and never creates Better Auth tables;
   `{{apiRun}} migration:revert` reverts the latest application migration.
-- e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
+- e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`. Run the whole suite on more
+  workers with `E2E_WORKERS=2`, never `--workers`. Tag a test `{ tag: "@exclusive" }` when
+  it changes state other tests rely on (a server-wide setting, a seeded account's profile);
+  tagged tests run alone after the rest. Give each test its own mail and SMS recipients and
+  never empty the shared Mailpit inbox or SMS sink. See `tests/README.md`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,
   builds, and unit tests run on Bun.
@@ -96,15 +126,25 @@ changes need an e2e/unit test.
 This project is managed by the `podo` CLI. Files have an ownership tier recorded
 in `.podokit/files.lock` — respect it:
 
-- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations.
+- **owned** (your code: `apps/web/src/routes/**`, your components/services, `apps/api/src/app.extensions.ts`, and this `AGENTS.md`) — edit freely. Add application-owned services or module descriptors through `app.extensions.ts` instead of changing toolkit registrations. Set Bun server options (`maxRequestBodySize`, `idleTimeout`) with its `apiServerOptions` export rather than editing `main.ts`; `API_MAX_REQUEST_BODY_SIZE` and `API_IDLE_TIMEOUT` apply when the export leaves them out.
 - **assembled** (e.g. `apps/api/src/app.ts`, `auth.ts`) — contain `// podokit:begin:… / …:end` fenced regions that the toolkit recomputes. Edit outside the fences only; **never hand-edit inside the fences**.
 - **managed** (bootstrap/config like `main.ts`) — the toolkit may update these; avoid gratuitous edits.
 
 Useful commands:
 
-- `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, storage, events, and jobs; set previews by default.
+- `podo dev watch|up|ps|logs|exec|down` — run container development through the
+  shared loopback gateway. `.podokit/dev.json` owns the local/public hosts and the
+  exact API WebSocket allowlist; never use a prefix or wildcard for that allowlist.
+  `podo dev up` rebuilds the images from the current source so a recreated
+  container never runs code older than the files Compose Watch synced.
+  `podo dev down` also stops this project's running `podo dev watch`; do not
+  kill Compose processes by hand.
+  The containers read the untracked `.env.docker`; `podo dev` creates it from the
+  committed `.env.docker.example` with generated secrets when it is missing. Never
+  commit `.env.docker` or put secrets in the example.
 - `podo add <module>` — add a feature (auth, admin-dashboard, redis, bullmq, …). It wires itself into the app; run `podo add` with no argument to list modules.
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
+- `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, object storage, events, and jobs. Set is dry-run by default and never migrates or deletes provider data. Local providers require one API process.
 - `podo status` / `podo diff` — see your local edits vs. what PodoKit generated.
 - `podo update` — pull in template/module improvements (3-way merges your edits; never touches owned files).
 - `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist, and API routes that take bodies above the web server's `BODY_SIZE_LIMIT` (file uploads) in `exposure.apiPaths` (and `.podokit/dev.json` `apiPaths` for `podo dev`; `podo add` and `podo deploy init` fill in the paths modules declare), which reach the API without the web proxy, so the API must check their size, session, and `Origin` itself; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.

package/dist/templates/todo/README.md

@@ -55,8 +55,9 @@ cp .env.example .env
 ```
 
 Open the URL printed by the command; a new project defaults to
-**http://{{projectName}}.localhost**. The committed `.podokit/dev.json` is the
-source of truth if you change the hostname. The first running PodoKit project starts
+**http://{{devHostname}}**. The committed `.podokit/dev.json` is the
+source of truth if you change the hostname: `podo dev` sets `CORS_ORIGIN` and
+`BETTER_AUTH_URL` for the web and API containers from it. The first running PodoKit project starts
 one user-level Traefik gateway on `127.0.0.1:80`; additional projects reuse it and
 route by that hostname. Even a single app uses
 the same topology, with one route and no project-specific host port.
@@ -164,5 +165,6 @@ PodoKit [deployment guide](https://github.com/podosoft-dev/podokit/blob/main/doc
 For a Docker Compose deployment with API WebSockets, list their exact paths under
 `exposure.webSocketPaths`. The driver keeps one published port, routes those paths
 to API, and sends every other request to web. Large-upload routes listed under
-`exposure.apiPaths` reach the API the same way, with `/api` removed. If an external reverse proxy supplies
-forwarding headers, list only its direct CIDR blocks in `exposure.trustedProxyCidrs`.
+`exposure.apiPaths` reach the API the same way, with `/api` removed. Set `exposure.edgeProxies` to the
+number of reverse proxies in front of the deployment, and with the gateway list only their direct CIDR
+blocks in `exposure.trustedProxyCidrs`.

package/dist/text-diff.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Line-based unified diff for `podo diff <path>`. It is dependency-free and
+ * meant for source files of a few thousand lines; above `MAX_CELLS` it reports
+ * the whole file as replaced instead of building the LCS table.
+ */
+export interface UnifiedDiffOptions {
+    fromLabel: string;
+    toLabel: string;
+    context?: number;
+}
+/** Unified diff from `from` to `to`, or an empty string when they are equal. */
+export declare function unifiedDiff(from: string, to: string, options: UnifiedDiffOptions): string;

package/dist/text-diff.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Line-based unified diff for `podo diff <path>`. It is dependency-free and
+ * meant for source files of a few thousand lines; above `MAX_CELLS` it reports
+ * the whole file as replaced instead of building the LCS table.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unifiedDiff = unifiedDiff;
+const MAX_CELLS = 25_000_000;
+function splitLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function operations(a, b) {
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start += 1;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA -= 1;
+        endB -= 1;
+    }
+    const head = a.slice(0, start).map((line) => ({ kind: " ", line }));
+    const tail = a.slice(endA).map((line) => ({ kind: " ", line }));
+    const midA = a.slice(start, endA);
+    const midB = b.slice(start, endB);
+    const m = midA.length;
+    const n = midB.length;
+    const middle = [];
+    if ((m + 1) * (n + 1) > MAX_CELLS) {
+        middle.push(...midA.map((line) => ({ kind: "-", line })));
+        middle.push(...midB.map((line) => ({ kind: "+", line })));
+        return [...head, ...middle, ...tail];
+    }
+    const width = n + 1;
+    const table = new Uint32Array((m + 1) * width);
+    for (let i = m - 1; i >= 0; i -= 1) {
+        for (let j = n - 1; j >= 0; j -= 1) {
+            table[i * width + j] = midA[i] === midB[j]
+                ? table[(i + 1) * width + j + 1] + 1
+                : Math.max(table[(i + 1) * width + j], table[i * width + j + 1]);
+        }
+    }
+    let i = 0;
+    let j = 0;
+    while (i < m || j < n) {
+        if (i < m && j < n && midA[i] === midB[j]) {
+            middle.push({ kind: " ", line: midA[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (i < m && (j === n || table[(i + 1) * width + j] >= table[i * width + j + 1])) {
+            middle.push({ kind: "-", line: midA[i] });
+            i += 1;
+        }
+        else {
+            middle.push({ kind: "+", line: midB[j] });
+            j += 1;
+        }
+    }
+    return [...head, ...middle, ...tail];
+}
+function range(start, count) {
+    if (count === 0)
+        return `${start},0`;
+    return count === 1 ? `${start + 1}` : `${start + 1},${count}`;
+}
+/** Unified diff from `from` to `to`, or an empty string when they are equal. */
+function unifiedDiff(from, to, options) {
+    if (from === to)
+        return "";
+    const context = options.context ?? 3;
+    const ops = operations(splitLines(from), splitLines(to));
+    const changed = ops.flatMap((op, index) => (op.kind === " " ? [] : [index]));
+    const out = [`--- ${options.fromLabel}`, `+++ ${options.toLabel}`];
+    if (!changed.length) {
+        // Only the trailing newline differs.
+        out.push(from.endsWith("\n") ? "\\ the template ends with a newline" : "\\ the template has no newline at end of file", to.endsWith("\n") ? "\\ the file ends with a newline" : "\\ the file has no newline at end of file");
+        return `${out.join("\n")}\n`;
+    }
+    let hunkStart = 0;
+    while (hunkStart < changed.length) {
+        let hunkEnd = hunkStart;
+        while (hunkEnd + 1 < changed.length &&
+            changed[hunkEnd + 1] - changed[hunkEnd] <= context * 2 + 1) {
+            hunkEnd += 1;
+        }
+        const first = Math.max(0, changed[hunkStart] - context);
+        const last = Math.min(ops.length - 1, changed[hunkEnd] + context);
+        let fromLine = 0;
+        let toLine = 0;
+        for (let index = 0; index < first; index += 1) {
+            if (ops[index].kind !== "+")
+                fromLine += 1;
+            if (ops[index].kind !== "-")
+                toLine += 1;
+        }
+        const body = ops.slice(first, last + 1);
+        const fromCount = body.filter((op) => op.kind !== "+").length;
+        const toCount = body.filter((op) => op.kind !== "-").length;
+        out.push(`@@ -${range(fromLine, fromCount)} +${range(toLine, toCount)} @@`);
+        out.push(...body.map((op) => `${op.kind}${op.line}`));
+        hunkStart = hunkEnd + 1;
+    }
+    return `${out.join("\n")}\n`;
+}