@podosoft/podokit 1.3.0 → 1.4.0

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.spec.ts

@@ -38,6 +38,22 @@ function user(userId: string, roles: string[] = [], organizationId?: string): Ev
   return { userId, roles, ...(organizationId ? { organizationId } : {}) };
 }
 
+/** A memory bus that can report a transport interruption, as the Redis bus does after reconnecting. */
+class InterruptibleBus extends MemoryEventBus {
+  readonly listeners = new Set<() => void>();
+
+  onInterruption(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  interrupt(): void {
+    for (const listener of this.listeners) listener();
+  }
+}
+
 const services: EventsService[] = [];
 
 async function service(
@@ -268,6 +284,23 @@ describe("per-connection safety", () => {
     expect(decoded(await stream.next())).toEqual({ topic: "t", data: 6 });
   });
 
+  it("tells every open stream to resync after a transport interruption", async () => {
+    const bus = new InterruptibleBus();
+    const events = await service({}, bus);
+    const topical = await open(events, user("a"), ["t"]);
+    const everything = await open(events, user("b"));
+    await events.publishAsync({ topic: "t", data: 1 });
+
+    bus.interrupt();
+    expect(await topical.next()).toEqual({ kind: "resync" });
+    expect(await everything.next()).toEqual({ kind: "resync" });
+    await events.publishAsync({ topic: "t", data: 2 });
+    expect(decoded(await topical.next())).toEqual({ topic: "t", data: 2 });
+
+    await events.close();
+    expect(bus.listeners.size).toBe(0);
+  });
+
   it("reuses one heartbeat timer per connection and releases it on disconnect", async () => {
     const scheduler = fakeScheduler();
     const events = await service({ scheduler });

package/dist/templates/modules/sse/files/apps/api/src/events/events.service.ts

@@ -44,6 +44,7 @@ export class EventsService {
   private readonly everyTopic = new Set<EventStream>();
   private unregisterReadiness?: () => void;
   private unsubscribe?: Unsubscribe;
+  private stopResync?: () => void;
 
   constructor(
     private readonly transport: EventBus,
@@ -74,6 +75,11 @@ export class EventsService {
       }
       this.deliver(envelope);
     });
+    // Events published while the transport was down never arrive, so open
+    // streams are told to reload once it is back.
+    this.stopResync = this.transport.onInterruption?.(() => {
+      for (const stream of this.streams) stream.resync();
+    });
     this.unregisterReadiness = this.readiness.register("events", () => this.transport.ready());
   }
 
@@ -133,6 +139,7 @@ export class EventsService {
 
   async close(): Promise<void> {
     this.unregisterReadiness?.();
+    this.stopResync?.();
     await this.unsubscribe?.();
     for (const stream of [...this.streams]) stream.close();
   }

package/dist/templates/todo/AGENTS.md

@@ -42,6 +42,14 @@ Merge added module settings from `.env.example` into an existing `.env`.
 
 - **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
   SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
+- The proxy (`apps/web/src/lib/server/backend-proxy.ts`) is managed and passes only
+  allowlisted headers. List extra request and response header names in the
+  app-owned `apps/web/src/lib/server/proxy-headers.ts`
+  (`APP_FORWARDED_REQUEST_HEADERS`, `APP_RELAYED_RESPONSE_HEADERS`); never edit the
+  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.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
 - Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
@@ -92,7 +100,7 @@ Useful commands:
 - `podo remove <module>` — un-apply a module (inverse of add; refuses if another module needs it, keeps files you edited).
 - `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; 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`.
+- `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`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions

package/dist/templates/todo/README.md

@@ -63,8 +63,17 @@ the same topology, with one route and no project-specific host port.
 
 When the API exposes WebSocket endpoints, add their exact paths to
 `.podokit/dev.json` under `webSocketPaths`. The shared gateway sends only those paths
-directly to the API and leaves every other path on the web app. Add `publicUrl` to the
-same file when an HTTPS tunnel preserves its public `Host` header.
+directly to the API and leaves every other path on the web app. Routes that accept
+bodies larger than the web server's `BODY_SIZE_LIMIT`, such as file uploads, go under
+`apiPaths` as prefixes like `/api/files/uploads/`; the gateway removes `/api` and
+sends them to the API without the web proxy. `podo add` adds the paths a module
+declares, such as `file-upload`'s, to this file and to every deployment profile. Add `publicUrl` to the same file when
+an HTTPS tunnel preserves its public `Host` header.
+
+The containers read `.env.docker`, which Git ignores. `dev` commands create it from
+the committed `.env.docker.example` when it is missing, as in a fresh clone, and fill
+each empty `*_SECRET` value with a random one; `dev env` does only that. Keep shared
+defaults in the example and credentials only in `.env.docker`.
 
 In a second terminal, apply the included Todo migration and use the lifecycle helpers:
 
@@ -80,7 +89,9 @@ In a second terminal, apply the included Todo migration and use the lifecycle he
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
 `storage`, and `queue` when installed modules require Redis, Silo, or a worker.
 `dev up` uses the same shared gateway and module profiles without keeping Compose
-Watch attached.
+Watch attached. It rebuilds the images from the current source first, because Compose
+Watch syncs edits into running containers only: a container recreated from an older
+image would lose them. Pass `--no-build` to start from the existing images.
 You can still activate an additional Compose profile explicitly:
 
 ```bash
@@ -88,7 +99,8 @@ You can still activate an additional Compose profile explicitly:
 ```
 
 Explicit profile flags are preserved for other lifecycle commands. `dev down`
-activates all profiles while removing this project's stack and route. If it is
+first stops this project's running `dev watch`, so the next `dev watch` starts
+cleanly, then activates all profiles while removing this project's stack and route. If it is
 the final registered
 project, it also removes the shared gateway and network. Source changes are synced
 through Compose Watch, including Vite HMR on the same portless browser origin.
@@ -149,5 +161,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. If an external reverse proxy supplies
+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`.

package/dist/update.d.ts

@@ -2,6 +2,7 @@ import { type TemplateVars } from "@podosoft/podokit-template-engine";
 import { type Tier } from "./lockfile";
 import type { ProviderCapability } from "@podosoft/podokit-runtime";
 import type { Toolchain } from "./toolchain";
+import { type ApiPathResult } from "./module-api-paths";
 /**
  * `podo update` planner. For now it produces a dry-run plan only: it assembles
  * the new-version tree from the installed CLI's templates and compares it to the
@@ -36,6 +37,8 @@ export interface UpdatePlan {
     /** Modules the update adds, ordered ahead of the modules that need them. */
     addedModules: AddedModule[];
     changes: FileChange[];
+    /** Direct API paths that modules newly declare, per configuration file. */
+    apiPaths: ApiPathResult;
 }
 /**
  * Build the update plan. `templatesDir` is the installed CLI's template set (the
@@ -77,6 +80,8 @@ export interface ApplyResult {
     merged: string[];
     /** Files written with conflict markers for manual resolution. */
     conflicts: string[];
+    /** Direct API paths added to `.podokit/dev.json` and deployment profiles. */
+    apiPaths: ApiPathResult;
 }
 /**
  * Apply an update to the working copy. Clean updates and additions are written,

package/dist/update.js

@@ -14,6 +14,7 @@ const lockfile_1 = require("./lockfile");
 const inspect_1 = require("./inspect");
 const add_1 = require("./add");
 const module_migrations_1 = require("./module-migrations");
+const module_api_paths_1 = require("./module-api-paths");
 function treeText(tree, path) {
     const file = tree.get(path);
     if (!file)
@@ -90,6 +91,18 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
     }
     return { modules: ordered, added };
 }
+function targetApiPaths(projectRoot, templatesDir, modules) {
+    const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
+    const declared = new Map();
+    const pending = [];
+    for (const module of modules) {
+        const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
+        const paths = resolved ? ((0, add_1.readModuleManifest)(resolved.dir).apiPaths ?? []) : [];
+        declared.set(module.name, paths);
+        pending.push(...(0, module_api_paths_1.pendingApiPaths)(module, paths));
+    }
+    return { declared, pending };
+}
 function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
     const overrides = new Set(current);
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
@@ -222,6 +235,16 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
             note: edited ? "you edited this; update would need a merge" : "clean update",
         });
     }
+    // A configuration file the update creates, such as a missing
+    // .podokit/dev.json, receives the paths after it is written.
+    const created = new Set(changes.filter((change) => change.action === "add").map((change) => change.path));
+    const apiPaths = options.onlyPaths
+        ? { changed: [], skipped: [] }
+        : (0, module_api_paths_1.addApiPaths)(projectRoot, targetApiPaths(projectRoot, templatesDir, modules).pending, {
+            dryRun: true,
+            read: (file) => diskContent(projectRoot, file)?.toString("utf8")
+                ?? (created.has(file) ? treeText(newTree, file) : null),
+        });
     return {
         fromVersion: manifest.podokitVersion,
         toVersion: (0, lockfile_1.podokitVersion)(),
@@ -229,6 +252,7 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
         modules: modules.map((module) => module.name),
         addedModules: added,
         changes,
+        apiPaths,
     };
 }
 function assertRecordedExternalModules(moduleRoot, templatesDir, modules) {
@@ -420,6 +444,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         removed: [],
         merged: [],
         conflicts: [],
+        apiPaths: { changed: [], skipped: [] },
     };
     for (const change of plan.changes) {
         const newText = treeText(newTree, change.path);
@@ -447,6 +472,9 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
                 result.merged.push(change.path);
         }
     }
+    const apiPaths = options.onlyPaths ? undefined : targetApiPaths(projectRoot, templatesDir, modules);
+    if (apiPaths)
+        result.apiPaths = (0, module_api_paths_1.addApiPaths)(projectRoot, apiPaths.pending);
     // Keep the assembled target as the managed baseline. A merged working file
     // intentionally remains drifted so a future update performs another 3-way
     // merge instead of treating the user's lines as clean generated output.
@@ -466,6 +494,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
                 ...(appliedMigrations.get(module.name) ?? []),
             ]),
         ];
+        const appliedApiPaths = [
+            ...new Set([
+                ...(module.appliedApiPaths ?? []),
+                ...(apiPaths?.declared.get(module.name) ?? []),
+            ]),
+        ];
         return {
             ...module,
             ...(resolved?.packageName
@@ -475,6 +509,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
                 }
                 : {}),
             ...(applied.length ? { appliedMigrations: applied } : {}),
+            ...(appliedApiPaths.length ? { appliedApiPaths } : {}),
         };
     });
     (0, lockfile_1.writeManifest)(projectRoot, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-runtime": "^0.3.0",
+    "@podosoft/podokit-runtime": "^0.4.0",
     "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }

package/dist/templates/modules/auth/files/apps/api/src/auth/schema-validation.ts

@@ -1,13 +0,0 @@
-// Better Auth validates the database schema when an instance starts, and fails
-// authentication requests while the schema does not match. Servers keep that check.
-// The migration runner builds an instance only to read its options, before the
-// schema it is about to change exists or matches, so it opts out for its process.
-let validateSchema = true;
-
-export function skipAuthSchemaValidation(): void {
-  validateSchema = false;
-}
-
-export function authSchemaValidation(): boolean {
-  return validateSchema;
-}

package/dist/templates/modules/auth/files/apps/api/src/auth/skip-schema-validation.ts

@@ -1,5 +0,0 @@
-// Imported first by the migration runner, before ./auth creates the Better Auth
-// instance whose startup check would report the schema those migrations change.
-import { skipAuthSchemaValidation } from "./schema-validation";
-
-skipAuthSchemaValidation();