@podosoft/podokit 1.5.0 → 1.6.0

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,10 +1,13 @@
 import { describe, expect, it } from "bun:test";
 import {
   assertApiContract,
+  assertApplicationRoutes,
   assertConsistentRouteParameters,
   documentedApiRoutes,
   expectedApiRoutes,
   missingApiRoutes,
+  normalizeApiRoute,
+  registeredApiRoutes,
 } from "./api-contract";
 
 describe("API contract inventory", () => {
@@ -57,4 +60,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

@@ -97,6 +97,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
 };
 
 interface RuntimeRoute {
+  method?: string;
   path: string;
 }
 
@@ -109,11 +110,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

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;

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

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { MigrationInterface } from "typeorm";
+import {
+  assertMigrationsLoaded,
+  loadMigrations,
+  MIGRATION_LIST,
+  migrationPaths,
+  migrationSet,
+} from "./migration-files";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function apiRoot(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "migration-files-"));
+  roots.push(root);
+  for (const [path, content] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), content);
+  }
+  return root;
+}
+
+const migrationSource = (name: string): string =>
+  `export class ${name} { name = "${name}"; async up() {} async down() {} }\n`;
+
+const loaded = (...names: string[]): MigrationInterface[] =>
+  names.map((name) => ({ name, up: async () => undefined, down: async () => undefined }));
+
+describe("migration files", () => {
+  it("lists source migrations in timestamp order outside production", () => {
+    const root = apiRoot({
+      "src/migrations/1700000000002-Second.ts": migrationSource("Second1700000000002"),
+      "src/migrations/1700000000001-First.ts": migrationSource("First1700000000001"),
+      "src/migrations/helpers.ts": "export {};\n",
+      "dist/migrations/1690000000000-Stale.js": migrationSource("Stale1690000000000"),
+    });
+    const set = migrationSet({ root, production: false });
+    expect(set).toEqual({
+      directory: join(root, "src/migrations"),
+      compiled: false,
+      files: [{ file: "1700000000001-First.ts" }, { file: "1700000000002-Second.ts" }],
+    });
+    expect(migrationPaths(set)).toEqual([
+      join(root, "src/migrations/1700000000001-First.ts"),
+      join(root, "src/migrations/1700000000002-Second.ts"),
+    ]);
+  });
+
+  it("reads the build's list in production", () => {
+    const list = [{ file: "1700000000001-First.js", name: "First1700000000001" }];
+    const root = apiRoot({
+      [`dist/migrations/${MIGRATION_LIST}`]: JSON.stringify(list),
+      "dist/migrations/1700000000001-First.js": migrationSource("First1700000000001"),
+    });
+    expect(migrationSet({ root, production: true })).toEqual({
+      directory: join(root, "dist/migrations"),
+      compiled: true,
+      files: list,
+    });
+  });
+
+  it("refuses a build output without its list instead of running no migrations", () => {
+    const root = apiRoot({ "dist/main.js": "", "dist/migrations/src/migrations/1700000000001-First.js": "" });
+    expect(() => migrationSet({ root, production: true })).toThrow(`${MIGRATION_LIST} is missing`);
+  });
+
+  it("refuses a list whose files are missing", () => {
+    const root = apiRoot({
+      [`dist/migrations/${MIGRATION_LIST}`]: JSON.stringify([{ file: "1700000000001-First.js", name: "First1700000000001" }]),
+    });
+    expect(() => migrationSet({ root, production: true })).toThrow("Compiled migrations are missing");
+  });
+
+  it("runs source migrations when production code runs without a build", () => {
+    const root = apiRoot({ "src/migrations/1700000000001-First.ts": migrationSource("First1700000000001") });
+    expect(migrationSet({ root, production: true })).toMatchObject({ compiled: false, files: [{ file: "1700000000001-First.ts" }] });
+  });
+
+  it("fails when a runner loaded fewer migrations than the set holds", () => {
+    const root = apiRoot({
+      "src/migrations/1700000000001-First.ts": migrationSource("First1700000000001"),
+      "src/migrations/1700000000002-Second.ts": migrationSource("Second1700000000002"),
+    });
+    const set = migrationSet({ root, production: false });
+    expect(() => assertMigrationsLoaded([], set)).toThrow("Loaded 0 of the 2 migrations");
+    expect(() => assertMigrationsLoaded(loaded("First1700000000001", "Second1700000000002"), set)).not.toThrow();
+  });
+
+  it("fails when the build's listed names did not load", () => {
+    const set = {
+      directory: "dist/migrations",
+      compiled: true,
+      files: [{ file: "1700000000001-First.js", name: "First1700000000001" }],
+    };
+    expect(() => assertMigrationsLoaded(loaded("Other1700000000001"), set)).toThrow("did not load: First1700000000001");
+  });
+
+  it("loads one migration class from each file", async () => {
+    const root = apiRoot({
+      "src/migrations/1700000000001-First.ts": migrationSource("First1700000000001"),
+      "src/migrations/1700000000002-Two.ts": `${migrationSource("A1700000000002")}${migrationSource("B1700000000002")}`,
+    });
+    const set = migrationSet({ root, production: false });
+    await expect(loadMigrations({ ...set, files: set.files.slice(0, 1) })).resolves.toMatchObject([
+      { file: "1700000000001-First.ts", timestamp: 1700000000001, migration: { name: "First1700000000001" } },
+    ]);
+    await expect(loadMigrations(set)).rejects.toThrow("must export exactly one migration class");
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/migration-files.ts

@@ -0,0 +1,134 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { MigrationInterface } from "typeorm";
+
+/** The list `scripts/build.mjs` writes next to the compiled migrations. */
+export const MIGRATION_LIST = "migrations.json";
+
+const SOURCE_FILE = /^\d+-.+\.ts$/;
+
+export interface MigrationFile {
+  file: string;
+  /** The migration's name, recorded by the build; unknown for source files until loaded. */
+  name?: string;
+}
+
+export interface MigrationSet {
+  directory: string;
+  /** True for the build output, which lists its migrations in `migrations.json`. */
+  compiled: boolean;
+  /** In timestamp order. */
+  files: MigrationFile[];
+}
+
+export interface MigrationSetOptions {
+  /** The API directory. Defaults to the working directory. */
+  root?: string;
+  /** Reads the build output. Defaults to NODE_ENV=production. */
+  production?: boolean;
+}
+
+function readList(path: string): MigrationFile[] {
+  const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (
+    !Array.isArray(parsed) ||
+    !parsed.every((entry: unknown) =>
+      typeof entry === "object" && entry !== null &&
+      typeof (entry as Record<string, unknown>).file === "string" &&
+      typeof (entry as Record<string, unknown>).name === "string"
+    )
+  ) {
+    throw new Error(`${path} must list { file, name } entries; rebuild the API`);
+  }
+  return parsed as MigrationFile[];
+}
+
+/**
+ * The migrations this process runs. In production that is the build output's
+ * list; a build output without its list fails instead of running none.
+ * Otherwise it is every `<timestamp>-<name>.ts` file in `src/migrations`.
+ */
+export function migrationSet(options: MigrationSetOptions = {}): MigrationSet {
+  const root = options.root ?? process.cwd();
+  const production = options.production ?? process.env.NODE_ENV === "production";
+  const compiled = join(root, "dist", "migrations");
+  const source = join(root, "src", "migrations");
+  if (production && existsSync(join(root, "dist"))) {
+    const list = join(compiled, MIGRATION_LIST);
+    if (!existsSync(list)) {
+      throw new Error(`${list} is missing; build the API with scripts/build.mjs before running it`);
+    }
+    const files = readList(list);
+    const missing = files.filter((entry) => !existsSync(join(compiled, entry.file)));
+    if (missing.length > 0) {
+      throw new Error(`Compiled migrations are missing from ${compiled}: ${missing.map((entry) => entry.file).join(", ")}`);
+    }
+    return { directory: compiled, compiled: true, files };
+  }
+  const files = existsSync(source)
+    ? readdirSync(source).filter((file) => SOURCE_FILE.test(file)).sort().map((file) => ({ file }))
+    : [];
+  return { directory: source, compiled: false, files };
+}
+
+export function migrationPaths(set: MigrationSet): string[] {
+  return set.files.map((entry) => join(set.directory, entry.file));
+}
+
+type MigrationConstructor = new () => MigrationInterface;
+
+function isMigration(value: unknown): value is MigrationConstructor {
+  if (typeof value !== "function") return false;
+  const prototype = (value as { prototype?: unknown }).prototype;
+  if (!prototype || typeof prototype !== "object") return false;
+  const record = prototype as Record<string, unknown>;
+  return typeof record.up === "function" && typeof record.down === "function";
+}
+
+/** TypeORM's name for a migration: its `name` property, else its class name. */
+export function migrationName(migration: MigrationInterface): string {
+  return migration.name || migration.constructor.name;
+}
+
+export interface LoadedMigration {
+  file: string;
+  timestamp: number;
+  migration: MigrationInterface;
+}
+
+/** Imports every file of the set; each must export exactly one migration class. */
+export async function loadMigrations(set: MigrationSet): Promise<LoadedMigration[]> {
+  const loaded: LoadedMigration[] = [];
+  for (const entry of set.files) {
+    const module = await import(pathToFileURL(join(set.directory, entry.file)).href) as Record<string, unknown>;
+    const constructors = Object.values(module).filter(isMigration);
+    const Constructor = constructors[0];
+    if (constructors.length !== 1 || !Constructor) {
+      throw new Error(`Migration ${entry.file} must export exactly one migration class`);
+    }
+    const timestamp = Number(entry.file.slice(0, entry.file.indexOf("-")));
+    if (!Number.isSafeInteger(timestamp)) throw new Error(`Migration ${entry.file} has an invalid timestamp`);
+    loaded.push({ file: entry.file, timestamp, migration: new Constructor() });
+  }
+  return loaded;
+}
+
+/**
+ * Fails unless the migrations a runner loaded are the set: TypeORM loads
+ * nothing, without an error, from a path that matches no file.
+ */
+export function assertMigrationsLoaded(loaded: readonly MigrationInterface[], set: MigrationSet): void {
+  if (loaded.length !== set.files.length) {
+    throw new Error(
+      `Loaded ${loaded.length} of the ${set.files.length} migrations in ${set.directory}; ` +
+        "each migration file must export exactly one migration class",
+    );
+  }
+  if (!set.compiled) return;
+  const names = new Set(loaded.map(migrationName));
+  const absent = set.files.filter((entry) => entry.name && !names.has(entry.name));
+  if (absent.length > 0) {
+    throw new Error(`Migrations listed in ${MIGRATION_LIST} did not load: ${absent.map((entry) => entry.name).join(", ")}`);
+  }
+}