@podosoft/podokit 1.5.0 → 1.6.0

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

@@ -4,9 +4,11 @@ import { createApp } from "../src/app";
 import { validateEnv } from "../src/config/env.validation";
 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 {
@@ -29,8 +31,10 @@ try {
   const document: unknown = await response.json();
   const modules = manifest.modules.map((module) => module.name);
   assertApiContract(document, manifest.template, modules);
+  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,118 @@
+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");
+const EXTENSIONS = join(__dirname, "../scripts/build.extensions.mjs");
+
+/** 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"));
+  cpSync(EXTENSIONS, join(root, "scripts/build.extensions.mjs"));
+  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");
+  });
+});

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

@@ -1,8 +1,12 @@
 import { z } from "zod";
+import { appEnvShape, refineAppEnv } from "./env.extensions";
 
 // Schema-validated environment. Fails fast at boot if something is wrong.
-const schema = z.object({
+// Application variables come from the owned env.extensions.ts.
+const podokitShape = {
   NODE_ENV: z.string().default("development"),
+  // The address the API listens on; 127.0.0.1 keeps it off the network.
+  HOST: z.string().trim().min(1).default("0.0.0.0"),
   PORT: z.coerce.number().default(5002),
   // Bytes one request body may hold; 128 MiB is Bun's default.
   API_MAX_REQUEST_BODY_SIZE: z.coerce.number().int().positive().default(128 * 1024 * 1024),
@@ -24,6 +28,8 @@ const schema = z.object({
     .default("x-forwarded-for"),
   CORS_ORIGIN: z.string().optional(),
   DATABASE_URL: z.string().optional(),
+  // The SQLite file when DATABASE_URL is unset, relative to the API directory.
+  SQLITE_PATH: z.string().trim().min(1).default("./data/podokit.sqlite"),
   POSTGRES_HOST: z.string().default("localhost"),
   POSTGRES_PORT: z.coerce.number().default(5432),
   POSTGRES_USER: z.string().default("podokit"),
@@ -36,9 +42,18 @@ const schema = z.object({
   DB_AUTH_POOL_MAX: z.coerce.number().int().positive().default(10),
   READINESS_CHECK_TIMEOUT_MS: z.coerce.number().int().positive().default(800),
   READINESS_CACHE_MS: z.coerce.number().int().nonnegative().default(2000),
-});
+} satisfies z.ZodRawShape;
 
-export type AppEnv = z.infer<typeof schema>;
+const redefined = Object.keys(appEnvShape).filter((name) => name in podokitShape);
+if (redefined.length > 0) {
+  throw new Error(`Invalid environment schema: env.extensions.ts redefines ${redefined.join(", ")}`);
+}
+
+const objectSchema = z.object({ ...podokitShape, ...appEnvShape });
+
+export type AppEnv = z.infer<typeof objectSchema>;
+
+const schema = objectSchema.superRefine((env, context) => refineAppEnv(env, context));
 
 // Renamed settings fail loudly: falling back to the default would count and
 // record every browser request under the web server's address.

package/dist/templates/fullstack/apps/api/src/config/provider-selection.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "bun:test";
+import { CACHE, type ProviderSelections, type ServiceKey } from "@podosoft/podokit-runtime";
+import {
+  assertSelectedProvidersInstalled,
+  providersFromEnvironment,
+  selectedFromEnvironment,
+} from "./provider-selection";
+
+const generated: ProviderSelections = {
+  database: "postgres",
+  cache: "redis",
+  "object-storage": "s3",
+  events: "redis",
+  jobs: "bullmq",
+};
+
+function registry(keys: symbol[]): { tryResolve<T>(key: ServiceKey<T>): T | undefined } {
+  return { tryResolve: <T>(key: ServiceKey<T>) => (keys.includes(key) ? ({} as T) : undefined) };
+}
+
+describe("provider selection", () => {
+  it("keeps the generated providers without variables", () => {
+    expect(providersFromEnvironment(generated, {})).toEqual(generated);
+    expect(providersFromEnvironment(generated, { DATABASE_PROVIDER: " " })).toEqual(generated);
+  });
+
+  it("replaces a capability whose variable is set", () => {
+    const env = { DATABASE_PROVIDER: "SQLite", CACHE_PROVIDER: "memory", JOBS_PROVIDER: "local" };
+    expect(providersFromEnvironment(generated, env)).toEqual({
+      ...generated,
+      database: "sqlite",
+      cache: "memory",
+      jobs: "local",
+    });
+    expect(selectedFromEnvironment(env)).toEqual(["database", "cache", "jobs"]);
+  });
+
+  it("rejects an unknown provider name", () => {
+    expect(() => providersFromEnvironment(generated, { OBJECT_STORAGE_PROVIDER: "gcs" })).toThrow(
+      "OBJECT_STORAGE_PROVIDER must be one of s3, local",
+    );
+  });
+
+  it("fails when a variable selects a provider without its module", () => {
+    const env = { CACHE_PROVIDER: "memory", DATABASE_PROVIDER: "sqlite" };
+    const providers = providersFromEnvironment(generated, env);
+    expect(() => assertSelectedProvidersInstalled(registry([]), providers, env)).toThrow(
+      "no installed module provides CACHE_PROVIDER=memory",
+    );
+    expect(() => assertSelectedProvidersInstalled(registry([CACHE]), providers, env)).not.toThrow();
+    expect(() => assertSelectedProvidersInstalled(registry([]), generated, {})).not.toThrow();
+  });
+});