@podosoft/podokit 1.5.0 → 1.6.1

package/dist/templates/fullstack/AGENTS.md

@@ -54,7 +54,20 @@ Merge added module settings from `.env.example` into an existing `.env`.
   `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.
+  specific prefix wins. The proxy and `serverApiClient` send the request's public
+  origin to the API in `x-forwarded-host`/`x-forwarded-proto` only when
+  `CORS_ORIGIN` lists it; an API route may use them to choose among its configured
+  origins, never as a new origin.
+- `apps/web/src/app.css` is managed. Put application styles (theme variable
+  overrides, `@theme` entries, fonts, base styles, and `@source` for packages
+  whose built components use Tailwind classes) in the app-owned
+  `apps/web/src/app.extensions.css`, which `app.css` imports last.
+- `apps/web/vite.config.ts` is managed. Put Vite options (warmup, `optimizeDeps`,
+  `define`, plugins, allowed hosts) in `appViteConfig` and SvelteKit options
+  (`alias`, `csrf`) in `appSvelteKitConfig` of the app-owned
+  `apps/web/vite.extensions.ts`. `bun run dev` proxies the exact
+  `webSocketPaths` of `.podokit/dev.json` to the API like the `podo dev` gateway,
+  so do not add a WebSocket proxy of your own.
 - 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
@@ -86,7 +99,19 @@ 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`.
+- Name a migration `apps/api/src/migrations/<timestamp>-<Name>.ts` with exactly one exported
+  migration class. The build lists compiled migrations in `dist/migrations/migrations.json` and
+  fails when one is lost; `{{apiRun}} migrate:list` prints what a build would run.
+- 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, in a second Playwright run that `test:e2e` starts
+  even when the first one failed, so run the suite through `test:e2e`, not
+  `bunx playwright test`, on more workers. Give each test its own mail and SMS recipients and
+  never empty the shared Mailpit inbox or SMS sink. See `tests/README.md`. The managed specs
+  read the app's first screen, public pages, and seeded accounts from the owned
+  `tests/helpers/app-paths.ts` (and `app-accounts.ts` with admin-dashboard): change those
+  instead of editing or ejecting a managed spec, and test the app's own screens in specs of its own.
 - 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.
@@ -121,7 +146,7 @@ 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. 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.
+- **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. Declare application environment variables in the owned `apps/api/src/config/env.extensions.ts` (`appEnvShape`, `refineAppEnv`) instead of editing `env.validation.ts`, and TypeORM entities in `APP_ENTITIES` of the owned `apps/api/src/database/entities.ts` instead of editing `data-source.ts`. List the operations your API must keep in `APP_DOCUMENTED_ROUTES` of the owned `apps/api/src/core/api-contract.extensions.ts`; `{{apiRun}} contract` checks they are registered and documented. With `auth`, declare app on/off settings in `APP_FLAG_DEFAULTS` of the owned `apps/api/src/settings/app-flags.ts` instead of editing `flag-defaults.ts`.
 - **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.
 
@@ -140,7 +165,8 @@ Useful commands:
 - `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 status` / `podo diff` — see your local edits vs. what PodoKit generated; `podo diff <path>` shows a file's line diff against the template, owned files included.
+- `podo restore <path>` — rewrite a managed file from the template, or hand an ejected file back to PodoKit.
 - `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`.
 - `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`.

package/dist/templates/fullstack/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.
@@ -188,11 +189,11 @@ HTTP, fix its public origin at build time instead:
 docker build --build-arg PODOKIT_BUILD_ORIGIN=https://example.com -f apps/web/Dockerfile -t {{projectName}}-web .
 ```
 
-For a Docker Compose deployment behind a trusted reverse proxy, set
-`PROTOCOL_HEADER=x-forwarded-proto` and `HOST_HEADER=x-forwarded-host` in the
-deployment profile runtime configuration and list the proxy's direct CIDR blocks in
-`exposure.trustedProxyCidrs`. Never trust client-controlled forwarded headers on a
-directly exposed container.
+Set `exposure.edgeProxies` in the deployment profile to the number of reverse
+proxies in front of the deployment; PodoKit derives which forwarded headers web and
+API trust from it, and trusts none when it is `0`. With a Compose gateway, also list
+the proxy's direct CIDR blocks in `exposure.trustedProxyCidrs`. Never count a proxy
+that clients can bypass.
 
 If the production API exposes WebSocket endpoints, list their exact paths under
 `exposure.webSocketPaths` in the deployment profile. The Compose driver then keeps a

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

@@ -10,14 +10,15 @@
     "test": "bun test src",
     "contract": "bun scripts/verify-api-contract.ts",
     "migrate:all": "bun scripts/run-migrations.mjs",
-    "typeorm": "bunx typeorm-ts-node-commonjs -d src/database/data-source.ts",
+    "migrate:list": "bun scripts/run-migrations.mjs --list",
+    "typeorm": "bunx --bun typeorm -d src/database/data-source.ts",
     "migration:run": "bun src/database/migrate.ts",
     "migration:revert": "bun src/database/migrate.ts --revert",
     "migration:generate": "bun run typeorm -- migration:generate"
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.5.0",
-    "@podosoft/podokit-runtime": "^0.4.1",
+    "@podosoft/podokit-contracts": "^0.6.0",
+    "@podosoft/podokit-runtime": "^0.5.1",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",
@@ -30,7 +31,6 @@
   "devDependencies": {
     "@types/bun": "^1.3.9",
     "@types/node": "^20.17.0",
-    "ts-node": "^10.9.2",
     "typescript": "^6.0.3"
   }
 }

package/dist/templates/fullstack/apps/api/scripts/build.extensions.mjs

@@ -0,0 +1,6 @@
+// This owned file is never overwritten by `podo update`. List entry points the
+// API build bundles next to PodoKit's, such as a maintenance command run from
+// the image. Each must exist. For example:
+//
+//   export const appBuildTargets = [{ entrypoint: "scripts/repair-data.ts", outdir: "dist/scripts" }];
+export const appBuildTargets = [];

package/dist/templates/fullstack/apps/api/scripts/build.mjs

@@ -1,4 +1,12 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { appBuildTargets } from "./build.extensions.mjs";
+
+// Bun inlines process.env.NODE_ENV as "development" unless told otherwise, which
+// would make every production check in the bundle, its dependencies included,
+// take the development branch. Keep it a read of the runtime environment.
+const define = { "process.env.NODE_ENV": "process.env.NODE_ENV" };
 
 const targets = [
   { entrypoint: "src/main.ts", outdir: "dist" },
@@ -8,11 +16,20 @@ const targets = [
   { entrypoint: "src/bootstrap-admin-runtime.ts", outdir: "dist" },
 ].filter((target) => existsSync(target.entrypoint));
 
+for (const target of appBuildTargets) {
+  if (!existsSync(target.entrypoint)) {
+    process.stderr.write(`Build failed: ${target.entrypoint} from build.extensions.mjs does not exist\n`);
+    process.exit(1);
+  }
+  targets.push(target);
+}
+
 for (const target of targets) {
   const result = await Bun.build({
     entrypoints: [target.entrypoint],
     outdir: target.outdir,
     target: "bun",
+    define,
   });
   if (!result.success) {
     for (const log of result.logs) process.stderr.write(`${log}\n`);
@@ -20,20 +37,52 @@ for (const target of targets) {
   }
 }
 
-if (existsSync("src/migrations")) {
-  const migrations = readdirSync("src/migrations")
-    .filter((file) => /^\d+-.+\.ts$/.test(file))
-    .map((file) => `src/migrations/${file}`);
-  if (migrations.length > 0) {
-    const result = await Bun.build({
-      entrypoints: migrations,
-      outdir: "dist/migrations",
-      target: "bun",
-      external: ["typeorm"],
-    });
-    if (!result.success) {
-      for (const log of result.logs) process.stderr.write(`${log}\n`);
-      process.exit(1);
-    }
+function fail(message) {
+  process.stderr.write(`Build migrations failed: ${message}\n`);
+  process.exit(1);
+}
+
+function isMigration(value) {
+  return typeof value === "function" &&
+    typeof value.prototype?.up === "function" &&
+    typeof value.prototype?.down === "function";
+}
+
+// Every source migration becomes dist/migrations/<file>.js, listed with its name
+// in dist/migrations/migrations.json, which the migrators and the API read in
+// production. A build that emits them anywhere else, or loses one, fails here
+// instead of a deployment that runs no migrations.
+const sources = existsSync("src/migrations")
+  ? readdirSync("src/migrations").filter((file) => /^\d+-.+\.ts$/.test(file)).sort()
+  : [];
+rmSync("dist/migrations", { recursive: true, force: true });
+mkdirSync("dist/migrations", { recursive: true });
+if (sources.length > 0) {
+  const result = await Bun.build({
+    entrypoints: sources.map((file) => `src/migrations/${file}`),
+    outdir: "dist/migrations",
+    root: "src/migrations",
+    target: "bun",
+    define,
+    external: ["typeorm"],
+  });
+  if (!result.success) {
+    for (const log of result.logs) process.stderr.write(`${log}\n`);
+    process.exit(1);
   }
 }
+const files = sources.map((file) => file.replace(/\.ts$/, ".js"));
+const built = readdirSync("dist/migrations", { recursive: true }).map(String).sort();
+if (JSON.stringify(built) !== JSON.stringify(files)) {
+  fail(`expected ${JSON.stringify(files)} in dist/migrations, found ${JSON.stringify(built)}`);
+}
+const list = [];
+for (const file of files) {
+  const module = await import(pathToFileURL(resolve("dist/migrations", file)).href);
+  const classes = Object.values(module).filter(isMigration);
+  if (classes.length !== 1) fail(`${file} must export exactly one migration class`);
+  const [Migration] = classes;
+  list.push({ file, name: new Migration().name || Migration.name });
+}
+writeFileSync("dist/migrations/migrations.json", `${JSON.stringify(list, null, 2)}\n`);
+process.stdout.write(`Built ${list.length} migrations\n`);

package/dist/templates/fullstack/apps/api/scripts/run-migrations.mjs

@@ -9,9 +9,13 @@ function entry(name) {
   return existsSync(source) ? source : null;
 }
 
+const args = process.argv.slice(2);
 // The auth module adds src/migrate.ts, which applies the Better Auth schema
-// before it runs the application migrations.
-const target = entry("migrate") ?? entry("database/migrate");
+// before it runs the application migrations. --list needs neither the
+// database nor auth, so it uses the application migrator.
+const target = args.includes("--list")
+  ? entry("database/migrate")
+  : entry("migrate") ?? entry("database/migrate");
 if (!target) {
   process.stderr.write("Run database migrations failed: no migration entry in src or dist\n");
   process.exit(1);
@@ -19,7 +23,7 @@ if (!target) {
 // Run in the API directory wherever this was started from: Bun reads decorator
 // settings from the tsconfig.json of the working directory, and the data source
 // finds .env and the migrations relative to it.
-const subprocess = Bun.spawn([process.execPath, fileURLToPath(target)], {
+const subprocess = Bun.spawn([process.execPath, fileURLToPath(target), ...args], {
   cwd: fileURLToPath(new URL("..", import.meta.url)),
   stdin: "inherit",
   stdout: "inherit",

package/dist/templates/fullstack/apps/api/scripts/verify-api-contract.ts

@@ -2,11 +2,14 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createApp } from "../src/app";
 import { validateEnv } from "../src/config/env.validation";
+import { PROVIDERS } from "../src/config/providers";
 import {
   assertApiContract,
+  assertApplicationRoutes,
   assertConsistentRouteParameters,
   documentedApiRoutes,
 } from "../src/core/api-contract";
+import { APP_DOCUMENTED_ROUTES } from "../src/core/api-contract.extensions";
 import { createCoreServices } from "../src/core/services";
 
 interface ProjectManifest {
@@ -28,9 +31,11 @@ try {
   }
   const document: unknown = await response.json();
   const modules = manifest.modules.map((module) => module.name);
-  assertApiContract(document, manifest.template, modules);
+  assertApiContract(document, manifest.template, modules, PROVIDERS);
+  assertApplicationRoutes(document, app.routes, APP_DOCUMENTED_ROUTES);
   process.stdout.write(
-    `Verified ${documentedApiRoutes(document).size} documented API operations for ${manifest.template}.\n`,
+    `Verified ${documentedApiRoutes(document).size} documented API operations for ${manifest.template}, ` +
+      `including ${APP_DOCUMENTED_ROUTES.length} application operations.\n`,
   );
 } finally {
   await services.close();

package/dist/templates/fullstack/apps/api/src/app.spec.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it, mock, type Mock } from "bun:test";
+import { AppException } from "@podosoft/podokit-contracts";
 import {
   cachedOpenApiDocument,
+  renderError,
   setRetryAfter,
   UNAVAILABLE_RETRY_AFTER_SECONDS,
   type OpenApiDocumentLoader,
@@ -98,3 +100,23 @@ describe("setRetryAfter", () => {
     expect(headers).toEqual({ "Retry-After": "7" });
   });
 });
+
+describe("renderError", () => {
+  it("puts an AppException's details in the envelope", () => {
+    const set = { headers: {} as Record<string, string | number>, status: undefined as number | string | undefined };
+    const details = { fields: [{ path: "email", code: "taken" }] };
+    const body = renderError("UNKNOWN", new AppException("SIGNUP_INVALID", "Invalid sign-up", 422, details), "/signup", set);
+    expect(set.status).toBe(422);
+    expect(body.error).toMatchObject({ code: "SIGNUP_INVALID", statusCode: 422, path: "/signup", details });
+    expect(renderError("UNKNOWN", new AppException("GONE", "Gone", 410), "/x", set).error).not.toHaveProperty("details");
+  });
+
+  it("hides the message of an unexpected error", () => {
+    const set = { headers: {} as Record<string, string | number>, status: undefined as number | string | undefined };
+    expect(renderError("UNKNOWN", new Error("secret detail"), "/x", set).error).toMatchObject({
+      code: "INTERNAL_ERROR",
+      message: "Internal server error",
+      statusCode: 500,
+    });
+  });
+});

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

@@ -4,6 +4,8 @@ import { AppException, type ErrorEnvelope } from "@podosoft/podokit-contracts";
 import { Elysia } from "elysia";
 import { configureServices, extensionModules } from "./app.extensions";
 import { validateEnv, type AppEnv } from "./config/env.validation";
+import { assertSelectedProvidersInstalled } from "./config/provider-selection";
+import { PROVIDERS } from "./config/providers";
 import { stampClientAddress } from "./core/client-address";
 import {
   appContext,
@@ -125,6 +127,43 @@ function errorEnvelope(
   };
 }
 
+export interface ErrorResponseState {
+  status?: number | string;
+  headers: Record<string, string | number>;
+}
+
+/**
+ * Renders a failed request as the standard error envelope: an AppException with
+ * its code, status, and details; an unreachable database as 503; Elysia's
+ * validation and routing errors as 400 and 404; anything else as 500 without
+ * its message.
+ */
+export function renderError(code: unknown, error: unknown, path: string, set: ErrorResponseState): ErrorEnvelope {
+  if (error instanceof AppException) {
+    set.status = error.statusCode;
+    if (error.statusCode === 503) setRetryAfter(set.headers);
+    return errorEnvelope(error.code, error.message, error.statusCode, path, error.details);
+  }
+  if (isDatabaseUnavailable(error)) {
+    set.status = 503;
+    setRetryAfter(set.headers);
+    return errorEnvelope("DATABASE_UNAVAILABLE", "The database is temporarily unavailable", 503, path);
+  }
+  const statusCode = code === "NOT_FOUND" ? 404 : code === "VALIDATION" ? 400 : 500;
+  set.status = statusCode;
+  const publicCode = code === "NOT_FOUND"
+    ? "NOT_FOUND"
+    : code === "VALIDATION"
+      ? "VALIDATION_ERROR"
+      : "INTERNAL_ERROR";
+  const message = statusCode === 500
+    ? "Internal server error"
+    : error instanceof Error
+      ? error.message
+      : "Request failed";
+  return errorEnvelope(publicCode, message, statusCode, path);
+}
+
 const buildApp = (options: CreateAppOptions = {}) => {
   const env = options.env ?? validateEnv(process.env);
   const services = options.services ?? createCoreServices(env);
@@ -135,6 +174,7 @@ const buildApp = (options: CreateAppOptions = {}) => {
   ];
   for (const module of modules) module.configure?.(env, services);
   configureServices(services);
+  assertSelectedProvidersInstalled(services, PROVIDERS);
   services.freeze();
   const context = appContext(env, services);
   const corsOrigin = env.CORS_ORIGIN?.split(",").map((origin) => origin.trim());
@@ -174,31 +214,7 @@ const buildApp = (options: CreateAppOptions = {}) => {
         "Complete request",
       );
     })
-    .onError(({ code, error, path, set }) => {
-      if (error instanceof AppException) {
-        set.status = error.statusCode;
-        if (error.statusCode === 503) setRetryAfter(set.headers);
-        return errorEnvelope(error.code, error.message, error.statusCode, path);
-      }
-      if (isDatabaseUnavailable(error)) {
-        set.status = 503;
-        setRetryAfter(set.headers);
-        return errorEnvelope("DATABASE_UNAVAILABLE", "The database is temporarily unavailable", 503, path);
-      }
-      const statusCode = code === "NOT_FOUND" ? 404 : code === "VALIDATION" ? 400 : 500;
-      set.status = statusCode;
-      const publicCode = code === "NOT_FOUND"
-        ? "NOT_FOUND"
-        : code === "VALIDATION"
-          ? "VALIDATION_ERROR"
-          : "INTERNAL_ERROR";
-      const message = statusCode === 500
-        ? "Internal server error"
-        : error instanceof Error
-          ? error.message
-          : "Request failed";
-      return errorEnvelope(publicCode, message, statusCode, path);
-    });
+    .onError(({ code, error, path, set }) => renderError(code, error, path, set));
 
   const plugins: AppPlugin[] = [
     healthPlugin,

package/dist/templates/fullstack/apps/api/src/build.spec.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "bun:test";
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+const BUILD = join(__dirname, "../scripts/build.mjs");
+// The application's own build.extensions.mjs names entry points this temporary
+// layout does not contain, so each build starts without application targets. A
+// test that needs some passes its own scripts/build.extensions.mjs.
+const NO_APP_TARGETS = "export const appBuildTargets = [];\n";
+
+/** Builds an API layout made of `files` with the app's build script. */
+async function build(files: Record<string, string>): Promise<{ root: string; code: number; stderr: string }> {
+  const root = mkdtempSync(join(tmpdir(), "api-build-"));
+  mkdirSync(join(root, "scripts"));
+  cpSync(BUILD, join(root, "scripts/build.mjs"));
+  writeFileSync(join(root, "scripts/build.extensions.mjs"), NO_APP_TARGETS);
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), content);
+  }
+  const child = Bun.spawn([process.execPath, "scripts/build.mjs"], { cwd: root, stdout: "pipe", stderr: "pipe" });
+  const [stderr, code] = await Promise.all([new Response(child.stderr).text(), child.exited]);
+  return { root, code, stderr };
+}
+
+async function run(root: string, entry: string, env: Record<string, string>): Promise<string> {
+  const child = Bun.spawn([process.execPath, entry], { cwd: root, env: { ...process.env, ...env }, stdout: "pipe" });
+  const [stdout] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+  return stdout.trim();
+}
+
+const migration = (name: string, body = ""): string =>
+  `${body}export class ${name} { name = "${name}"; async up() {} async down() {} }\n`;
+
+describe("API build", () => {
+  it("builds every migration flat into dist/migrations and lists it with its name", async () => {
+    const { root, code, stderr } = await build({
+      "src/config/table.ts": 'export const TABLE = "example";\n',
+      "src/migrations/1700000000002-AddIndex.ts": migration(
+        "AddIndex1700000000002",
+        'import { TABLE } from "../config/table";\nvoid TABLE;\n',
+      ),
+      "src/migrations/1700000000001-CreateExample.ts": migration("CreateExample1700000000001"),
+      "dist/migrations/1690000000000-Removed.js": migration("Removed1690000000000"),
+    });
+    try {
+      expect({ code, stderr }).toEqual({ code: 0, stderr: "" });
+      expect(readdirSync(join(root, "dist/migrations"), { recursive: true }).map(String).sort()).toEqual([
+        "1700000000001-CreateExample.js",
+        "1700000000002-AddIndex.js",
+        "migrations.json",
+      ]);
+      expect(JSON.parse(readFileSync(join(root, "dist/migrations/migrations.json"), "utf8"))).toEqual([
+        { file: "1700000000001-CreateExample.js", name: "CreateExample1700000000001" },
+        { file: "1700000000002-AddIndex.js", name: "AddIndex1700000000002" },
+      ]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("writes an empty list for an app without migrations", async () => {
+    const { root, code } = await build({ "src/main.ts": "export {};\n" });
+    try {
+      expect(code).toBe(0);
+      expect(readFileSync(join(root, "dist/migrations/migrations.json"), "utf8")).toBe("[]\n");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("fails on a migration file without exactly one migration class", async () => {
+    const { root, code, stderr } = await build({
+      "src/migrations/1700000000001-Two.ts": `${migration("A1700000000001")}${migration("B1700000000001")}`,
+    });
+    try {
+      expect(code).toBe(1);
+      expect(stderr).toContain("1700000000001-Two.js must export exactly one migration class");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("leaves NODE_ENV to the environment the bundle runs in", async () => {
+    const { root, code, stderr } = await build({ "src/main.ts": "console.log(process.env.NODE_ENV);\n" });
+    try {
+      expect({ code, stderr }).toEqual({ code: 0, stderr: "" });
+      expect(await run(root, "dist/main.js", { NODE_ENV: "production" })).toBe("production");
+      expect(await run(root, "dist/main.js", { NODE_ENV: "test" })).toBe("test");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("bundles the application's entry points from build.extensions.mjs", async () => {
+    const { root, code, stderr } = await build({
+      "scripts/build.extensions.mjs":
+        'export const appBuildTargets = [{ entrypoint: "scripts/repair.ts", outdir: "dist/scripts" }];\n',
+      "scripts/repair.ts": 'console.log("repaired", process.env.NODE_ENV);\n',
+    });
+    try {
+      expect({ code, stderr }).toEqual({ code: 0, stderr: "" });
+      expect(await run(root, "dist/scripts/repair.js", { NODE_ENV: "production" })).toBe("repaired production");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("fails on an application entry point that does not exist", async () => {
+    const { root, code, stderr } = await build({
+      "scripts/build.extensions.mjs": 'export const appBuildTargets = [{ entrypoint: "scripts/gone.ts", outdir: "dist" }];\n',
+    });
+    try {
+      expect(code).toBe(1);
+      expect(stderr).toContain("scripts/gone.ts from build.extensions.mjs does not exist");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/dist/templates/fullstack/apps/api/src/config/env.extensions.ts

@@ -0,0 +1,20 @@
+import type { z } from "zod";
+import type { AppEnv } from "./env.validation";
+
+// This owned file is never overwritten by `podo update`. Declare the
+// application's environment variables here: they are validated with PodoKit's
+// at startup, fail it with the same message when invalid, and are typed on
+// `AppEnv`. A name PodoKit already defines is rejected. For example:
+//
+//   import { z } from "zod";
+//   export const appEnvShape = {
+//     REPORTS_BUCKET: z.string().min(1),
+//     SYNC_INTERVAL_SECONDS: z.coerce.number().int().positive().default(60),
+//   } satisfies z.ZodRawShape;
+export const appEnvShape = {} satisfies z.ZodRawShape;
+
+/**
+ * Checks across variables, such as one that production requires. Report a
+ * problem with `context.addIssue({ code: "custom", path: ["NAME"], message })`.
+ */
+export function refineAppEnv(_env: AppEnv, _context: z.RefinementCtx): void {}

package/dist/templates/fullstack/apps/api/src/config/env.validation.spec.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "bun:test";
+import { copyFileSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateEnv } from "./env.validation";
+
+describe("environment validation", () => {
+  it("listens on every address and keeps SQLite under data/ by default", () => {
+    expect(validateEnv({})).toMatchObject({ HOST: "0.0.0.0", SQLITE_PATH: "./data/podokit.sqlite" });
+  });
+
+  it("reads HOST and SQLITE_PATH", () => {
+    expect(validateEnv({ HOST: " 127.0.0.1 ", SQLITE_PATH: "/var/lib/app/app.sqlite" }))
+      .toMatchObject({ HOST: "127.0.0.1", SQLITE_PATH: "/var/lib/app/app.sqlite" });
+    expect(() => validateEnv({ HOST: " " })).toThrow("Invalid environment");
+  });
+});
+
+/** Runs `script` next to a copy of env.validation.ts and an env.extensions.ts of the test's own. */
+async function withExtensions(extensions: string, script: string): Promise<{ code: number; stdout: string; stderr: string }> {
+  // Inside the API directory, so the copies resolve zod like the originals.
+  const root = mkdtempSync(join(__dirname, ".env-extensions-"));
+  try {
+    copyFileSync(join(__dirname, "env.validation.ts"), join(root, "env.validation.ts"));
+    writeFileSync(join(root, "env.extensions.ts"), extensions);
+    writeFileSync(join(root, "check.ts"), script);
+    const child = Bun.spawn([process.execPath, join(root, "check.ts")], { stdout: "pipe", stderr: "pipe" });
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    return { code, stdout: stdout.trim(), stderr };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+describe("application environment", () => {
+  const extensions = [
+    'import { z } from "zod";',
+    'import type { AppEnv } from "./env.validation";',
+    "export const appEnvShape = {",
+    "  REPORTS_BUCKET: z.string().min(1),",
+    "  SYNC_INTERVAL_SECONDS: z.coerce.number().int().positive().default(60),",
+    "};",
+    "export function refineAppEnv(env: AppEnv, context: z.RefinementCtx): void {",
+    '  if (env.NODE_ENV === "production" && env.REPORTS_BUCKET === "dev") {',
+    '    context.addIssue({ code: "custom", path: ["REPORTS_BUCKET"], message: "use a production bucket" });',
+    "  }",
+    "}",
+    "",
+  ].join("\n");
+
+  it("validates and types the variables of env.extensions.ts with PodoKit's", async () => {
+    const result = await withExtensions(extensions, [
+      'import { validateEnv } from "./env.validation";',
+      'const env = validateEnv({ REPORTS_BUCKET: "reports" });',
+      "const interval: number = env.SYNC_INTERVAL_SECONDS;",
+      "console.log(JSON.stringify([env.REPORTS_BUCKET, interval, env.PORT]));",
+      "for (const input of [{}, { NODE_ENV: \"production\", REPORTS_BUCKET: \"dev\" }]) {",
+      "  try { validateEnv(input); } catch (error) { console.log((error as Error).message.includes(\"REPORTS_BUCKET\")); }",
+      "}",
+      "",
+    ].join("\n"));
+    expect(result).toMatchObject({ code: 0, stdout: '["reports",60,5002]\ntrue\ntrue' });
+  });
+
+  it("rejects a variable PodoKit already defines", async () => {
+    const result = await withExtensions(
+      'import { z } from "zod";\nexport const appEnvShape = { PORT: z.string() };\nexport function refineAppEnv(): void {}\n',
+      'import "./env.validation";\n',
+    );
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain("env.extensions.ts redefines PORT");
+  });
+});