@podosoft/podokit 1.5.0 → 1.6.1

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();
+  });
+});

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

@@ -0,0 +1,79 @@
+import {
+  CACHE,
+  EVENTS,
+  JOBS,
+  OBJECT_STORAGE,
+  PROVIDER_CAPABILITIES,
+  PROVIDER_NAMES,
+  type ProviderCapability,
+  type ProviderSelections,
+  type ServiceKey,
+} from "@podosoft/podokit-runtime";
+
+/** The variable that replaces each capability's generated provider at startup. */
+export const PROVIDER_VARIABLES: Readonly<Record<ProviderCapability, string>> = {
+  database: "DATABASE_PROVIDER",
+  cache: "CACHE_PROVIDER",
+  "object-storage": "OBJECT_STORAGE_PROVIDER",
+  events: "EVENTS_PROVIDER",
+  jobs: "JOBS_PROVIDER",
+};
+
+export type ProviderEnvironment = Readonly<Record<string, string | undefined>>;
+
+/** The capabilities whose provider a variable selects, for example in a desktop build. */
+export function selectedFromEnvironment(env: ProviderEnvironment = process.env): ProviderCapability[] {
+  return PROVIDER_CAPABILITIES.filter((capability) => Boolean(env[PROVIDER_VARIABLES[capability]]?.trim()));
+}
+
+/**
+ * The generated selection, with a capability replaced when its variable is set,
+ * so one build can run, say, PostgreSQL on a server and SQLite in a desktop
+ * shell. The selected provider's module must be installed; an unknown name
+ * fails at startup.
+ */
+export function providersFromEnvironment(
+  generated: ProviderSelections,
+  env: ProviderEnvironment = process.env,
+): ProviderSelections {
+  const selections: Record<string, string> = { ...generated };
+  for (const capability of selectedFromEnvironment(env)) {
+    const variable = PROVIDER_VARIABLES[capability];
+    const value = env[variable]?.trim().toLowerCase() ?? "";
+    const allowed: readonly string[] = PROVIDER_NAMES[capability];
+    if (!allowed.includes(value)) {
+      throw new Error(`Invalid environment: ${variable} must be one of ${allowed.join(", ")}`);
+    }
+    selections[capability] = value;
+  }
+  return selections as unknown as ProviderSelections;
+}
+
+// The service each provider module registers when its provider is selected.
+// The database has no module: the core service serves PostgreSQL and SQLite.
+const PROVIDER_SERVICES: Partial<Record<ProviderCapability, ServiceKey<unknown>>> = {
+  cache: CACHE,
+  "object-storage": OBJECT_STORAGE,
+  events: EVENTS,
+  jobs: JOBS,
+};
+
+/**
+ * Fails startup when a variable selects a provider whose module is not
+ * installed, which would otherwise fail the first request that needs it.
+ */
+export function assertSelectedProvidersInstalled(
+  services: { tryResolve<T>(key: ServiceKey<T>): T | undefined },
+  providers: ProviderSelections,
+  env: ProviderEnvironment = process.env,
+): void {
+  const missing = selectedFromEnvironment(env).flatMap((capability) => {
+    const key = PROVIDER_SERVICES[capability];
+    return key && services.tryResolve(key) === undefined
+      ? [`${PROVIDER_VARIABLES[capability]}=${providers[capability]}`]
+      : [];
+  });
+  if (missing.length > 0) {
+    throw new Error(`Invalid environment: no installed module provides ${missing.join(", ")}`);
+  }
+}

package/dist/templates/fullstack/apps/api/src/config/providers.ts

@@ -1,11 +1,15 @@
 import type { ProviderSelections } from "@podosoft/podokit-runtime";
+import { providersFromEnvironment } from "./provider-selection";
 
-// Typed with every provider name, not the selected ones: the module of a
+// The providers selected when the project was generated or by `podo provider
+// set`. Typed with every provider name, not the selected ones: the module of a
 // provider that stays installed after a switch compares against its own name.
-export const PROVIDERS: Readonly<ProviderSelections> = {
+// A <CAPABILITY>_PROVIDER variable replaces one at startup; see
+// provider-selection.ts.
+export const PROVIDERS: Readonly<ProviderSelections> = providersFromEnvironment({
   database: "{{databaseProvider}}",
   cache: "{{cacheProvider}}",
   "object-storage": "{{objectStorageProvider}}",
   events: "{{eventsProvider}}",
   jobs: "{{jobsProvider}}",
-};
+});

package/dist/templates/fullstack/apps/api/src/core/api-contract.extensions.ts

@@ -0,0 +1,6 @@
+// This owned file is never overwritten by `podo update`. List the operations
+// the application's own API must serve, as "METHOD /path". `bun run contract`
+// fails when one is not registered or missing from the OpenAPI document, for
+// example after a route was renamed or hidden by mistake. Parameters may use
+// either syntax: "GET /reports/{id}" or "GET /reports/:id".
+export const APP_DOCUMENTED_ROUTES: readonly string[] = [];

package/dist/templates/fullstack/apps/api/src/core/api-contract.spec.ts

@@ -1,15 +1,19 @@
 import { describe, expect, it } from "bun:test";
+import { LOCAL_PROVIDER_SELECTIONS, SERVER_PROVIDER_SELECTIONS } from "@podosoft/podokit-runtime";
 import {
   assertApiContract,
+  assertApplicationRoutes,
   assertConsistentRouteParameters,
   documentedApiRoutes,
   expectedApiRoutes,
   missingApiRoutes,
+  normalizeApiRoute,
+  registeredApiRoutes,
 } from "./api-contract";
 
 describe("API contract inventory", () => {
   it("covers the core, Todo, module, and Better Auth routes", () => {
-    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"]);
+    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"], SERVER_PROVIDER_SELECTIONS);
 
     expect(expected).toContain("GET /health/ready");
     expect(expected).toContain("PATCH /todos/{id}");
@@ -20,7 +24,7 @@ describe("API contract inventory", () => {
   });
 
   it("uses one structural parameter name for every public blog post route", () => {
-    const expected = expectedApiRoutes("fullstack", ["blog"]);
+    const expected = expectedApiRoutes("fullstack", ["blog"], SERVER_PROVIDER_SELECTIONS);
 
     expect(expected).toContain("GET /blog/{postRef}");
     expect(expected).toContain("PATCH /blog/{postRef}");
@@ -29,15 +33,53 @@ describe("API contract inventory", () => {
     expect(expected).not.toContain("PATCH /blog/{id}");
   });
 
+  it("expects a provider module's routes only while its provider is selected", () => {
+    const modules = [
+      "object-storage-s3",
+      "object-storage-local",
+      "redis",
+      "cache-memory",
+      "bullmq",
+      "jobs-local",
+    ];
+    const server = expectedApiRoutes("fullstack", modules, SERVER_PROVIDER_SELECTIONS);
+    const local = expectedApiRoutes("fullstack", modules, LOCAL_PROVIDER_SELECTIONS);
+
+    expect(server).toContain("PUT /storage/{key}");
+    expect(server).not.toContain("GET /files/content/*");
+    expect(server).toContain("PUT /cache/{key}");
+    expect(server).toContain("POST /jobs");
+    expect(local).toContain("PUT /storage/{key}");
+    expect(local).toContain("GET /files/content/*");
+    expect(local).not.toContain("PUT /cache/{key}");
+    expect(local).not.toContain("GET /cache/{key}");
+    expect(local).toContain("GET /jobs/{id}");
+
+    const s3Document = {
+      paths: {
+        "/health": { get: {} },
+        "/health/ready": { get: {} },
+        "/storage/{key}": { get: {}, put: {} },
+        "/storage/{key}/presigned": { get: {} },
+      },
+    };
+    const storage = ["object-storage-s3", "object-storage-local"];
+    expect(() => assertApiContract(s3Document, "fullstack", storage, SERVER_PROVIDER_SELECTIONS)).not.toThrow();
+    expect(() => assertApiContract(s3Document, "fullstack", storage, {
+      ...SERVER_PROVIDER_SELECTIONS,
+      "object-storage": "local",
+    })).toThrow("GET /files/content/*");
+  });
+
   it("normalizes OpenAPI operations and reports an exact missing route", () => {
     const document = { paths: { "/health": { get: {} }, "/health/ready": { get: {} } } };
 
     expect(documentedApiRoutes(document)).toEqual(new Set(["GET /health", "GET /health/ready"]));
-    expect(missingApiRoutes(document, "fullstack", ["redis"])).toEqual([
+    expect(missingApiRoutes(document, "fullstack", ["redis"], SERVER_PROVIDER_SELECTIONS)).toEqual([
       "GET /cache/{key}",
       "PUT /cache/{key}",
     ]);
-    expect(() => assertApiContract(document, "fullstack", ["redis"])).toThrow(
+    expect(() => assertApiContract(document, "fullstack", ["redis"], SERVER_PROVIDER_SELECTIONS)).toThrow(
       "OpenAPI contract is missing routes",
     );
   });
@@ -57,4 +99,30 @@ describe("API contract inventory", () => {
       { method: "DELETE", path: "/hosts/:hostId/services/:serviceId" },
     ])).not.toThrow();
   });
+
+  it("normalizes runtime and OpenAPI parameter syntax", () => {
+    expect(normalizeApiRoute("get /reports/:id/rows/:rowId")).toBe("GET /reports/{id}/rows/{rowId}");
+    expect(normalizeApiRoute("GET /reports/{id}")).toBe("GET /reports/{id}");
+    expect(registeredApiRoutes([
+      { method: "GET", path: "/reports/:id" },
+      { method: "POST", path: "/reports" },
+      { path: "/no-method" },
+    ])).toEqual(new Set(["GET /reports/{id}", "POST /reports"]));
+  });
+
+  it("requires every application route to be registered and documented", () => {
+    const document = { paths: { "/reports/{id}": { get: {} }, "/hidden": {} } };
+    const routes = [{ method: "GET", path: "/reports/:id" }, { method: "DELETE", path: "/hidden" }];
+
+    expect(() => assertApplicationRoutes(document, routes, ["GET /reports/:id", "GET /reports/{id}"])).not.toThrow();
+    expect(() => assertApplicationRoutes(document, routes, [])).not.toThrow();
+    expect(() => assertApplicationRoutes(document, routes, ["DELETE /hidden", "POST /reports"])).toThrow(
+      [
+        "Application API contract failed:",
+        "DELETE /hidden is missing from the OpenAPI document",
+        "POST /reports is not registered",
+        "POST /reports is missing from the OpenAPI document",
+      ].join("\n"),
+    );
+  });
 });

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -1,3 +1,5 @@
+import type { ProviderCapability, ProviderSelections } from "@podosoft/podokit-runtime";
+
 const OPERATIONS = new Set(["get", "post", "put", "patch", "delete", "options", "head"]);
 
 const CORE_ROUTES = [
@@ -81,6 +83,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "DELETE /files/uploads/{id}",
   ],
   "job-progress": ["POST /progress"],
+  "jobs-local": ["POST /jobs", "GET /jobs/{id}"],
   "object-storage-local": [
     "GET /files/content/*",
     "PUT /storage/{key}",
@@ -96,7 +99,24 @@ const MODULE_ROUTES: Record<string, string[]> = {
   sse: ["GET /events/stream", "POST /events"],
 };
 
+/**
+ * The provider each provider module implements. Such a module registers its
+ * routes only while its provider is selected, so an app may keep, say, both
+ * object-storage modules installed and serve the routes of one.
+ */
+export const MODULE_PROVIDERS: Readonly<Record<string, readonly [ProviderCapability, string]>> = {
+  bullmq: ["jobs", "bullmq"],
+  "cache-memory": ["cache", "memory"],
+  "events-memory": ["events", "memory"],
+  "events-redis": ["events", "redis"],
+  "jobs-local": ["jobs", "local"],
+  "object-storage-local": ["object-storage", "local"],
+  "object-storage-s3": ["object-storage", "s3"],
+  redis: ["cache", "redis"],
+};
+
 interface RuntimeRoute {
+  method?: string;
   path: string;
 }
 
@@ -109,11 +129,47 @@ function record(value: unknown): Record<string, unknown> {
 function runtimeRoutes(value: unknown): RuntimeRoute[] {
   if (!Array.isArray(value)) return [];
   return value.flatMap((route) => {
-    const path = record(route).path;
-    return typeof path === "string" ? [{ path }] : [];
+    const { path, method } = record(route);
+    if (typeof path !== "string") return [];
+    return [typeof method === "string" ? { method, path } : { path }];
   });
 }
 
+/** "METHOD /path" with OpenAPI parameters, so ":id" and "{id}" compare equal. */
+export function normalizeApiRoute(route: string): string {
+  const [method = "", path = ""] = route.trim().split(/\s+/, 2);
+  const openApiPath = path
+    .split("/")
+    .map((segment) => segment.startsWith(":") ? `{${segment.slice(1).replace(/[?*]$/, "")}}` : segment)
+    .join("/");
+  return `${method.toUpperCase()} ${openApiPath}`;
+}
+
+/** The operations an Elysia app registers, as normalized "METHOD /path" entries. */
+export function registeredApiRoutes(routes: unknown): Set<string> {
+  const registered = new Set<string>();
+  for (const route of runtimeRoutes(routes)) {
+    if (route.method) registered.add(normalizeApiRoute(`${route.method} ${route.path}`));
+  }
+  return registered;
+}
+
+/**
+ * Fails unless every application route is both registered and documented.
+ * `expected` comes from APP_DOCUMENTED_ROUTES in api-contract.extensions.ts.
+ */
+export function assertApplicationRoutes(document: unknown, routes: unknown, expected: readonly string[]): void {
+  const documented = documentedApiRoutes(document);
+  const registered = registeredApiRoutes(routes);
+  const problems = [...new Set(expected.map(normalizeApiRoute))].sort().flatMap((route) => [
+    ...(registered.has(route) ? [] : [`${route} is not registered`]),
+    ...(documented.has(route) ? [] : [`${route} is missing from the OpenAPI document`]),
+  ]);
+  if (problems.length > 0) {
+    throw new Error(`Application API contract failed:\n${problems.join("\n")}`);
+  }
+}
+
 /**
  * Memoirist stores one parameter name at each structural radix-tree position.
  * Routes such as `/hosts/:id` and `/hosts/:hostId/files` therefore cannot share
@@ -158,10 +214,20 @@ export function documentedApiRoutes(document: unknown): Set<string> {
   return routes;
 }
 
-export function expectedApiRoutes(template: string, modules: string[]): Set<string> {
+/**
+ * The routes the template and the installed modules serve. A provider module
+ * counts only when `providers`, the app's PROVIDERS, selects its provider.
+ */
+export function expectedApiRoutes(
+  template: string,
+  modules: string[],
+  providers: Readonly<ProviderSelections>,
+): Set<string> {
   const routes = new Set(CORE_ROUTES);
   for (const route of TEMPLATE_ROUTES[template] ?? []) routes.add(route);
   for (const module of modules) {
+    const provider = MODULE_PROVIDERS[module];
+    if (provider && providers[provider[0]] !== provider[1]) continue;
     for (const route of MODULE_ROUTES[module] ?? []) routes.add(route);
   }
   return routes;
@@ -171,15 +237,21 @@ export function missingApiRoutes(
   document: unknown,
   template: string,
   modules: string[],
+  providers: Readonly<ProviderSelections>,
 ): string[] {
   const documented = documentedApiRoutes(document);
-  return [...expectedApiRoutes(template, modules)]
+  return [...expectedApiRoutes(template, modules, providers)]
     .filter((route) => !documented.has(route))
     .sort();
 }
 
-export function assertApiContract(document: unknown, template: string, modules: string[]): void {
-  const missing = missingApiRoutes(document, template, modules);
+export function assertApiContract(
+  document: unknown,
+  template: string,
+  modules: string[],
+  providers: Readonly<ProviderSelections>,
+): void {
+  const missing = missingApiRoutes(document, template, modules, providers);
   if (missing.length > 0) {
     throw new Error(`OpenAPI contract is missing routes:\n${missing.join("\n")}`);
   }

package/dist/templates/fullstack/apps/api/src/core/services.ts

@@ -6,6 +6,8 @@ import {
 } from "@podosoft/podokit-runtime";
 import type { AppEnv } from "../config/env.validation";
 import { Database } from "../database/database";
+import { migrationSet } from "../database/migration-files";
+import { MIGRATIONS_READINESS_CHECK, pendingMigrationsCheck } from "../database/migration-readiness";
 import { DATABASE_READINESS_CHECK, ReadinessService } from "../health/readiness.service";
 
 export type { ServiceKey } from "@podosoft/podokit-runtime";
@@ -410,6 +412,17 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
   });
   services.register(READINESS, readiness);
   readiness.register(DATABASE_READINESS_CHECK, () => services.resolve(DATABASE).ping());
+  if (env.NODE_ENV === "production") {
+    // Throws when the build output lacks its migration list, so the API does not
+    // start without knowing which migrations its schema needs.
+    const migrations = migrationSet({ production: true });
+    if (migrations.compiled) {
+      readiness.register(
+        MIGRATIONS_READINESS_CHECK,
+        pendingMigrationsCheck(() => services.resolve(DATABASE).sql, migrations),
+      );
+    }
+  }
   services.register(LOGGER, logger);
   services.register(ACCESS_POLICY, accessPolicy);
   services.register(REQUEST_GUARDS, requestGuards);

package/dist/templates/fullstack/apps/api/src/database/data-source.spec.ts

@@ -1,6 +1,17 @@
 import { describe, expect, it } from "bun:test";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { Column, Entity, PrimaryColumn } from "typeorm";
 import { PROVIDERS } from "../config/providers";
+import { APP_ENTITIES } from "./entities";
+
+@Entity("probe_item")
+class ProbeItem {
+  @PrimaryColumn()
+  id!: string;
+
+  @Column()
+  count!: number;
+}
 
 function databaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
@@ -13,3 +24,19 @@ describe.skipIf(databaseProvider() !== "postgres")("migration data source", () =
     expect(dataSourceOptions.migrationsTransactionMode).toBe("each");
   });
 });
+
+describe("application entities", () => {
+  // The TypeORM data source serves PostgreSQL; SQLite migrates without it.
+  it.skipIf(databaseProvider() !== "postgres")("loads the entities of the owned entities.ts", async () => {
+    const { dataSourceOptions } = await import("./data-source.js");
+    expect(dataSourceOptions.entities).toBe(APP_ENTITIES);
+  });
+
+  it("compiles TypeORM entity decorators with their design types", () => {
+    // TypeORM infers a column's type from this metadata.
+    const designType = (Reflect as unknown as {
+      getMetadata(key: string, target: object, property: string): unknown;
+    }).getMetadata("design:type", ProbeItem.prototype, "count");
+    expect(designType).toBe(Number);
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/data-source.ts

@@ -1,20 +1,18 @@
 import "dotenv/config";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
 import { DataSource, type DataSourceOptions } from "typeorm";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { PROVIDERS } from "../config/providers";
 import { validateEnv } from "../config/env.validation";
 import { databaseUrl, sqliteDatabasePath } from "./database";
+import { APP_ENTITIES } from "./entities";
+import { migrationPaths, migrationSet } from "./migration-files";
 
-const compiledMigrations = join(process.cwd(), "dist", "migrations");
-const migrations = existsSync(compiledMigrations)
-  ? [join(compiledMigrations, "[0-9]*.js")]
-  : [join(process.cwd(), "src", "migrations", "[0-9]*.ts")];
+/** The migrations the data source loads; compare them with `assertMigrationsLoaded`. */
+export const appMigrations = migrationSet();
 
 const commonOptions = {
-  entities: [],
-  migrations,
+  entities: APP_ENTITIES,
+  migrations: migrationPaths(appMigrations),
   // One transaction per migration, so a migration can set `transaction = false`
   // for statements such as CREATE INDEX CONCURRENTLY.
   migrationsTransactionMode: "each" as const,
@@ -44,6 +42,5 @@ export const dataSourceOptions: DataSourceOptions = databaseProvider() === "sqli
       ...commonOptions,
     };
 
-// Used by the TypeORM CLI for migrations (see package.json scripts).
+// The TypeORM CLI (see package.json scripts) takes the file's only DataSource export.
 export const appDataSource = new DataSource(dataSourceOptions);
-export default appDataSource;

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

@@ -86,6 +86,18 @@ describe("database provider", () => {
     expect(() => databaseUrl({ ...env, DATABASE_URL })).toThrow("DATABASE_URL must use");
   });
 
+  it("puts the default SQLite database at SQLITE_PATH", () => {
+    const root = mkdtempSync(join(tmpdir(), "podokit-sqlite-"));
+    try {
+      const path = join(root, "state", "app.sqlite");
+      expect(databaseUrl({ ...env, SQLITE_PATH: path }, "sqlite")).toBe(`sqlite://${path}`);
+      expect(existsSync(dirname(path))).toBe(true);
+      expect(databaseUrl(env, "sqlite")).toBe(`sqlite://${join(process.cwd(), "data/podokit.sqlite")}`);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   it("creates the parent directory for an explicit SQLite database", () => {
     const root = mkdtempSync(join(tmpdir(), "podokit-sqlite-"));
     try {

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

@@ -14,8 +14,7 @@ function selectedDatabaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
 }
 
-export function databaseUrl(env: AppEnv): string {
-  const provider = selectedDatabaseProvider();
+export function databaseUrl(env: AppEnv, provider: DatabaseProviderName = selectedDatabaseProvider()): string {
   if (env.DATABASE_URL) {
     if (provider === "sqlite" && !isSqliteUrl(env.DATABASE_URL)) {
       throw new Error("DATABASE_URL must use sqlite:, file:, or :memory: for the SQLite provider");
@@ -26,7 +25,7 @@ export function databaseUrl(env: AppEnv): string {
     return env.DATABASE_URL;
   }
   if (provider === "sqlite") {
-    const path = resolve("./data/podokit.sqlite");
+    const path = resolve(env.SQLITE_PATH);
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     return `sqlite://${path}`;
   }

package/dist/templates/fullstack/apps/api/src/database/entities.ts

@@ -0,0 +1,12 @@
+import type { DataSourceOptions } from "typeorm";
+
+// This owned file is never overwritten by `podo update`. List the
+// application's TypeORM entities here: the migration data source loads them,
+// so `migration:generate` compares them with the database and code that uses
+// `appDataSource` gets their repositories. For example:
+//
+//   import { Invoice } from "../invoices/invoice.entity";
+//   export const APP_ENTITIES: AppEntities = [Invoice];
+export type AppEntities = NonNullable<DataSourceOptions["entities"]>;
+
+export const APP_ENTITIES: AppEntities = [];

package/dist/templates/fullstack/apps/api/src/database/migrate.ts

@@ -3,12 +3,21 @@ import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import { databaseUrl, sqliteDatabasePath } from "./database";
+import { assertMigrationsLoaded, loadMigrations, migrationName, migrationSet } from "./migration-files";
 import { revertLatestSqliteMigration, runSqliteMigrations } from "./sqlite-migrator";
 
 function databaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
 }
 
+/** Prints the migrations this build runs, one name per line, without a database. */
+async function list(): Promise<void> {
+  const set = migrationSet();
+  const loaded = await loadMigrations(set);
+  for (const { migration } of loaded) process.stdout.write(`${migrationName(migration)}\n`);
+  process.stderr.write(`${loaded.length} migrations in ${set.directory}\n`);
+}
+
 async function migrate(): Promise<void> {
   if (databaseProvider() === "sqlite") {
     const env = validateEnv(process.env);
@@ -21,9 +30,10 @@ async function migrate(): Promise<void> {
     }
     return;
   }
-  const { appDataSource: dataSource } = await import("./data-source.js");
+  const { appDataSource: dataSource, appMigrations } = await import("./data-source.js");
   await dataSource.initialize();
   try {
+    assertMigrationsLoaded(dataSource.migrations, appMigrations);
     if (process.argv.includes("--revert")) await dataSource.undoLastMigration({ transaction: "all" });
     else await dataSource.runMigrations();
   } finally {
@@ -31,7 +41,7 @@ async function migrate(): Promise<void> {
   }
 }
 
-void migrate().catch((error: unknown) => {
+void (process.argv.includes("--list") ? list() : migrate()).catch((error: unknown) => {
   const message = error instanceof Error ? error.message : String(error);
   process.stderr.write(`Migration failed: ${message}\n`);
   process.exitCode = 1;