@podosoft/podokit 1.0.1 → 1.1.2

package/dist/remove.js

@@ -6,7 +6,6 @@ const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const add_1 = require("./add");
 const lockfile_1 = require("./lockfile");
-const toolchain_1 = require("./toolchain");
 function readModuleManifest(moduleDir, vars) {
     const source = (0, node_fs_1.readFileSync)((0, node_path_1.join)(moduleDir, "module.manifest.json"), "utf8");
     return JSON.parse(vars ? (0, podokit_template_engine_1.renderTokens)(source, vars) : source);
@@ -51,7 +50,7 @@ function removeModule(options) {
     }
     const vars = {
         projectName: projectName(projectRoot),
-        ...(0, toolchain_1.toolchainTemplateVars)(manifest.toolchain),
+        ...(0, lockfile_1.manifestTemplateVars)(manifest),
     };
     const targetManifest = readModuleManifest(moduleDir, vars);
     // Resolve the manifests of the OTHER installed modules once — used for the
@@ -64,7 +63,11 @@ function removeModule(options) {
     })
         .filter((m) => m !== null);
     // Guard: refuse if another installed module requires this one.
-    const dependents = others.filter((o) => (o.manifest.requires ?? []).includes(module)).map((o) => o.name);
+    const selectedCapabilities = Object.entries(targetManifest.provides ?? {})
+        .filter(([capability, provider]) => manifest.providers[capability] === provider)
+        .map(([capability]) => capability);
+    const dependents = others.filter((other) => (other.manifest.requires ?? []).includes(module)
+        || (other.manifest.requiresCapabilities ?? []).some((capability) => selectedCapabilities.includes(capability))).map((other) => other.name);
     if (dependents.length) {
         throw new Error(`Cannot remove "${module}": required by ${dependents.join(", ")}. Remove ${dependents.length > 1 ? "those" : "that"} first.`);
     }

package/dist/templates/fullstack/AGENTS.md

@@ -8,9 +8,9 @@ Follow it so your changes match the project's conventions.
 
 A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 
-- `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + PostgreSQL, merged OpenAPI at `/api-docs`.
+- `apps/api` — **Elysia** backend (`{{projectName}}-api`), Bun.SQL + `{{databaseProvider}}`, merged OpenAPI at `/api-docs`.
 - `apps/web` — **SvelteKit** frontend (`{{projectName}}-web`), Tailwind v4 + shadcn-svelte + typesafe-i18n.
-- `infra/` — Docker Compose (PostgreSQL/Redis) and example k3s manifests.
+- `infra/` — provider-aware Docker Compose and example k3s manifests.
 - `.podokit/` — PodoKit generation metadata plus application-owned development and
   deployment profiles (see "PodoKit tooling" below).
 
@@ -19,7 +19,7 @@ A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 ```bash
 {{packageManager}} install
 cp .env.example .env
-docker compose -f infra/docker/docker-compose.yml up -d   # PostgreSQL (+ Redis)
+docker compose -f infra/docker/docker-compose.yml up -d   # selected external providers only
 {{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
@@ -74,9 +74,10 @@ Useful commands:
   exact API WebSocket allowlist; never use a prefix or wildcard for that allowlist.
 - `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 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. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
+- `podo deploy` — plan, apply, verify, or roll back an immutable release on Kubernetes or one Docker host. Production API WebSocket paths belong in the deployment profile's exact `exposure.webSocketPaths` allowlist; Compose trusts forwarding headers only from `exposure.trustedProxyCidrs`. Tag `vX.Y.Z` to build and push the images (`.github/workflows/release.yml`; check its runner — GitHub-hosted minutes are free for public repositories only). Use `.agents/skills/podokit-deploy`.
 - `podo deploy sync` — copy local build output into a running Compose deployment and restart it, for iterating without a release. Not a release: no image is published and the next `apply` discards it. Use `.agents/skills/podokit-deploy-fast`.
 
 ## Commit conventions

package/dist/templates/fullstack/README.md

@@ -40,7 +40,7 @@ Run lifecycle and container commands from a second terminal:
 ```
 
 `dev watch` reads `.podokit/manifest.json` and automatically activates `cache`,
-`storage`, and `queue` when installed modules require Redis, MinIO, or a worker.
+`storage`, and `queue` when installed modules require Redis, Silo, or a worker.
 `dev up` uses the same shared gateway and module profiles without keeping Compose
 Watch attached.
 You can still activate an additional Compose profile explicitly:
@@ -118,5 +118,12 @@ docker build --build-arg PODOKIT_BUILD_ORIGIN=https://example.com -f apps/web/Do
 
 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. Never trust client-controlled forwarded
-headers on a directly exposed container.
+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.
+
+If the production API exposes WebSocket endpoints, list their exact paths under
+`exposure.webSocketPaths` in the deployment profile. The Compose driver then keeps a
+single published port, sends only those paths to API, and sends all other traffic to
+web. The external TLS proxy continues to use the same single upstream. Keep
+`trustedProxyCidrs` empty unless that upstream is a known reverse proxy.

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

@@ -11,12 +11,13 @@
     "contract": "bun scripts/verify-api-contract.ts",
     "migrate:all": "bun dist/database/migrate.js",
     "typeorm": "bunx typeorm-ts-node-commonjs -d src/database/data-source.ts",
-    "migration:run": "bun run typeorm -- migration:run",
-    "migration:revert": "bun run typeorm -- migration:revert",
+    "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.4.0",
+    "@podosoft/podokit-runtime": "^0.2.0",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

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

@@ -5,6 +5,7 @@ const schema = z.object({
   NODE_ENV: z.string().default("development"),
   PORT: z.coerce.number().default(5002),
   CORS_ORIGIN: z.string().optional(),
+  DATABASE_URL: z.string().optional(),
   POSTGRES_HOST: z.string().default("localhost"),
   POSTGRES_PORT: z.coerce.number().default(5432),
   POSTGRES_USER: z.string().default("podokit"),

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

@@ -0,0 +1,9 @@
+import type { ProviderSelections } from "@podosoft/podokit-runtime";
+
+export const PROVIDERS = {
+  database: "{{databaseProvider}}",
+  cache: "{{cacheProvider}}",
+  "object-storage": "{{objectStorageProvider}}",
+  events: "{{eventsProvider}}",
+  jobs: "{{jobsProvider}}",
+} as const satisfies ProviderSelections;

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

@@ -1,10 +1,14 @@
 import { Elysia } from "elysia";
 import pino, { type Logger } from "pino";
+import {
+  DATABASE as RUNTIME_DATABASE,
+  type ServiceKey,
+} from "@podosoft/podokit-runtime";
 import type { AppEnv } from "../config/env.validation";
 import { Database } from "../database/database";
 import { ReadinessService } from "../health/readiness.service";
 
-export type ServiceKey<T> = symbol & { readonly __service?: T };
+export type { ServiceKey } from "@podosoft/podokit-runtime";
 
 export class ServiceRegistry {
   private readonly values = new Map<symbol, unknown>();
@@ -142,7 +146,7 @@ export class OpenApiRegistry {
   }
 }
 
-export const DATABASE = Symbol("database") as ServiceKey<Database>;
+export const DATABASE = RUNTIME_DATABASE as ServiceKey<Database>;
 export const READINESS = Symbol("readiness") as ServiceKey<ReadinessService>;
 export const LOGGER = Symbol("logger") as ServiceKey<Logger>;
 export const ACCESS_POLICY = Symbol("access-policy") as ServiceKey<AccessPolicy>;
@@ -185,6 +189,7 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
   accessPolicy.register("*", "/api-docs-json", "public");
   accessPolicy.register("*", "/api-docs-elysia-json", "public");
   services.register(DATABASE, database, () => database.close());
+  services.onStart(() => database.connect());
   services.register(READINESS, readiness);
   services.register(LOGGER, logger);
   services.register(ACCESS_POLICY, accessPolicy);

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

@@ -2,23 +2,45 @@ 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";
 
 const compiledMigrations = join(process.cwd(), "dist", "migrations");
 const migrations = existsSync(compiledMigrations)
   ? [join(compiledMigrations, "[0-9]*.js")]
   : [join(process.cwd(), "src", "migrations", "[0-9]*.ts")];
 
-export const dataSourceOptions: DataSourceOptions = {
-  type: "postgres",
-  host: process.env.POSTGRES_HOST ?? "localhost",
-  port: Number(process.env.POSTGRES_PORT ?? 5432),
-  username: process.env.POSTGRES_USER ?? "podokit",
-  password: process.env.POSTGRES_PASSWORD ?? "podokit",
-  database: process.env.POSTGRES_DB ?? "podokit",
+const commonOptions = {
   entities: [],
   migrations,
   synchronize: false,
 };
 
+const env = validateEnv(process.env);
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+export const dataSourceOptions: DataSourceOptions = databaseProvider() === "sqlite"
+  ? {
+      type: "better-sqlite3",
+      database: sqliteDatabasePath(databaseUrl(env)),
+      enableWAL: true,
+      ...commonOptions,
+    }
+  : {
+      type: "postgres",
+      ...(process.env.DATABASE_URL ? { url: process.env.DATABASE_URL } : {}),
+      host: env.POSTGRES_HOST,
+      port: env.POSTGRES_PORT,
+      username: env.POSTGRES_USER,
+      password: env.POSTGRES_PASSWORD,
+      database: env.POSTGRES_DB,
+      ...commonOptions,
+    };
+
 // Used by the TypeORM CLI for migrations (see package.json scripts).
-export default new DataSource(dataSourceOptions);
+export const appDataSource = new DataSource(dataSourceOptions);
+export default appDataSource;

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import type { AppEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
+import { databaseUrl, sqliteDatabasePath } from "./database";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+
+const env: AppEnv = {
+  NODE_ENV: "test",
+  PORT: 5002,
+  POSTGRES_HOST: "localhost",
+  POSTGRES_PORT: 5432,
+  POSTGRES_USER: "podokit",
+  POSTGRES_PASSWORD: "podokit",
+  POSTGRES_DB: "podokit",
+};
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
+describe("database provider", () => {
+  it("uses DATABASE_URL as the canonical connection setting", () => {
+    const provider = databaseProvider();
+    const DATABASE_URL = provider === "sqlite"
+      ? "sqlite://:memory:"
+      : "postgres://podokit:podokit@localhost:5432/podokit";
+    expect(databaseUrl({ ...env, DATABASE_URL })).toBe(DATABASE_URL);
+  });
+
+  it("keeps the PostgreSQL fields as a fallback and creates a SQLite default", () => {
+    const url = databaseUrl(env);
+    const provider = databaseProvider();
+    if (provider === "sqlite") expect(url).toMatch(/^sqlite:\/\//);
+    else expect(url).toBe("postgres://podokit:podokit@localhost:5432/podokit");
+  });
+
+  it("rejects a connection URL for the other database dialect", () => {
+    const provider = databaseProvider();
+    const DATABASE_URL = provider === "sqlite"
+      ? "postgres://podokit:podokit@localhost:5432/podokit"
+      : "sqlite://:memory:";
+    expect(() => databaseUrl({ ...env, DATABASE_URL })).toThrow("DATABASE_URL must use");
+  });
+
+  it("creates the parent directory for an explicit SQLite database", () => {
+    const root = mkdtempSync(join(tmpdir(), "podokit-sqlite-"));
+    try {
+      const path = join(root, "nested", "app.sqlite");
+      expect(sqliteDatabasePath(`sqlite://${path}`)).toBe(path);
+      expect(existsSync(dirname(path))).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -1,22 +1,78 @@
 import { SQL } from "bun";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import type { AppEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
+
+function isSqliteUrl(url: string): boolean {
+  return url === ":memory:" || /^(?:sqlite|file):/.test(url);
+}
+
+function selectedDatabaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
 
 export function databaseUrl(env: AppEnv): string {
+  const provider = selectedDatabaseProvider();
+  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");
+    }
+    if (provider === "postgres" && isSqliteUrl(env.DATABASE_URL)) {
+      throw new Error("DATABASE_URL must use postgres: for the PostgreSQL provider");
+    }
+    return env.DATABASE_URL;
+  }
+  if (provider === "sqlite") {
+    const path = resolve("./data/podokit.sqlite");
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    return `sqlite://${path}`;
+  }
   const username = encodeURIComponent(env.POSTGRES_USER);
   const password = encodeURIComponent(env.POSTGRES_PASSWORD);
   const database = encodeURIComponent(env.POSTGRES_DB);
   return `postgres://${username}:${password}@${env.POSTGRES_HOST}:${env.POSTGRES_PORT}/${database}`;
 }
 
+export function sqliteDatabasePath(url: string): string {
+  if (url === ":memory:" || url === "sqlite://:memory:") return ":memory:";
+  const path = url.startsWith("sqlite://")
+    ? url.slice("sqlite://".length)
+    : url.startsWith("file:")
+      ? decodeURIComponent(new URL(url).pathname)
+      : undefined;
+  if (!path) throw new Error("SQLite database URL must use sqlite:, file:, or :memory:");
+  mkdirSync(dirname(resolve(path)), { recursive: true, mode: 0o700 });
+  return path;
+}
+
 export class Database {
+  readonly provider: DatabaseProviderName = selectedDatabaseProvider();
   readonly sql: SQL;
+  private ready?: Promise<void>;
 
   constructor(env: AppEnv) {
-    this.sql = new SQL(databaseUrl(env), { max: 20 });
+    const url = databaseUrl(env);
+    this.sql = this.provider === "sqlite"
+      ? new SQL(url, { adapter: "sqlite", create: true, readwrite: true, strict: true })
+      : new SQL(url, { max: 20 });
+  }
+
+  connect(): Promise<void> {
+    this.ready ??= (async () => {
+      if (this.provider === "sqlite") {
+        await this.sql`PRAGMA journal_mode = WAL`;
+        await this.sql`PRAGMA foreign_keys = ON`;
+        await this.sql`PRAGMA busy_timeout = 5000`;
+      }
+      await this.sql`SELECT 1`;
+    })();
+    return this.ready;
   }
 
   async ping(): Promise<void> {
-    await this.sql`SELECT 1`;
+    await this.connect();
   }
 
   async close(): Promise<void> {

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

@@ -1,9 +1,31 @@
-import dataSource from "./data-source";
+import { Database as SqliteDatabase } from "bun:sqlite";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { validateEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
+import { databaseUrl, sqliteDatabasePath } from "./database";
+import { revertLatestSqliteMigration, runSqliteMigrations } from "./sqlite-migrator";
+
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
 
 async function migrate(): Promise<void> {
+  if (databaseProvider() === "sqlite") {
+    const env = validateEnv(process.env);
+    const database = new SqliteDatabase(sqliteDatabasePath(databaseUrl(env)), { create: true });
+    try {
+      if (process.argv.includes("--revert")) await revertLatestSqliteMigration(database);
+      else await runSqliteMigrations(database);
+    } finally {
+      database.close();
+    }
+    return;
+  }
+  const { appDataSource: dataSource } = await import("./data-source.js");
   await dataSource.initialize();
   try {
-    await dataSource.runMigrations({ transaction: "all" });
+    if (process.argv.includes("--revert")) await dataSource.undoLastMigration({ transaction: "all" });
+    else await dataSource.runMigrations({ transaction: "all" });
   } finally {
     await dataSource.destroy();
   }

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

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "bun:test";
+import { Database as SqliteDatabase } from "bun:sqlite";
+import type { MigrationInterface, QueryRunner } from "typeorm";
+import {
+  revertLatestSqliteMigration,
+  runSqliteMigrations,
+  type SqliteMigrationDefinition,
+} from "./sqlite-migrator";
+
+class CreateExample1000 implements MigrationInterface {
+  name = "CreateExample1000";
+
+  async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('CREATE TABLE "example" ("id" text PRIMARY KEY)');
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('DROP TABLE "example"');
+  }
+}
+
+const definitions: readonly SqliteMigrationDefinition[] = [
+  { timestamp: 1_000, migration: new CreateExample1000() },
+];
+
+describe("SQLite migrator", () => {
+  it("runs each migration once and records it atomically", async () => {
+    const database = new SqliteDatabase(":memory:");
+    try {
+      await runSqliteMigrations(database, definitions);
+      await runSqliteMigrations(database, definitions);
+      expect(database.query<{ count: number }, []>('SELECT count(*) AS "count" FROM "migrations"').get()?.count).toBe(1);
+      expect(database.query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE name = 'example'").get()?.name).toBe("example");
+    } finally {
+      database.close();
+    }
+  });
+
+  it("reverts the latest applied migration", async () => {
+    const database = new SqliteDatabase(":memory:");
+    try {
+      await runSqliteMigrations(database, definitions);
+      await expect(revertLatestSqliteMigration(database, definitions)).resolves.toBe(true);
+      expect(database.query<{ name: string }, []>("SELECT name FROM sqlite_master WHERE name = 'example'").get()).toBeNull();
+      await expect(revertLatestSqliteMigration(database, definitions)).resolves.toBe(false);
+    } finally {
+      database.close();
+    }
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/sqlite-migrator.ts

@@ -0,0 +1,134 @@
+import { Database as SqliteDatabase } from "bun:sqlite";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { MigrationInterface, QueryRunner } from "typeorm";
+
+export interface SqliteMigrationDefinition {
+  timestamp: number;
+  migration: MigrationInterface;
+}
+
+interface AppliedMigration {
+  id: number;
+  timestamp: number;
+  name: string;
+}
+
+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";
+}
+
+async function discoverMigrations(): Promise<SqliteMigrationDefinition[]> {
+  const compiled = join(process.cwd(), "dist", "migrations");
+  const source = join(process.cwd(), "src", "migrations");
+  const directory = process.env.NODE_ENV === "production" && existsSync(compiled)
+    ? compiled
+    : source;
+  if (!existsSync(directory)) return [];
+  const files = readdirSync(directory)
+    .filter((file) => /^\d+-.+\.(?:js|ts)$/.test(file))
+    .sort();
+  const definitions: SqliteMigrationDefinition[] = [];
+  for (const file of files) {
+    const loaded = await import(pathToFileURL(join(directory, file)).href) as Record<string, unknown>;
+    const constructors = Object.values(loaded).filter(isMigration);
+    if (constructors.length !== 1) {
+      throw new Error(`SQLite migration ${file} must export exactly one migration class`);
+    }
+    const timestamp = Number(file.slice(0, file.indexOf("-")));
+    if (!Number.isSafeInteger(timestamp)) throw new Error(`SQLite migration ${file} has an invalid timestamp`);
+    const Constructor = constructors[0];
+    if (!Constructor) throw new Error(`SQLite migration ${file} has no migration class`);
+    definitions.push({ timestamp, migration: new Constructor() });
+  }
+  return definitions;
+}
+
+function queryRunner(database: SqliteDatabase): QueryRunner {
+  return {
+    connection: { options: { type: "better-sqlite3" } },
+    query: (sql: string): Promise<unknown> => Promise.resolve(database.run(sql)),
+  } as unknown as QueryRunner;
+}
+
+function prepare(database: SqliteDatabase): void {
+  database.run("PRAGMA journal_mode = WAL");
+  database.run("PRAGMA foreign_keys = ON");
+  database.run("PRAGMA busy_timeout = 5000");
+  database.run(`
+    CREATE TABLE IF NOT EXISTS "migrations" (
+      "id" integer PRIMARY KEY AUTOINCREMENT,
+      "timestamp" bigint NOT NULL,
+      "name" text NOT NULL UNIQUE
+    )
+  `);
+}
+
+function migrationName(migration: MigrationInterface): string {
+  if (typeof migration.name !== "string" || migration.name.length === 0) {
+    throw new Error("SQLite migration classes must declare a non-empty name");
+  }
+  return migration.name;
+}
+
+export async function runSqliteMigrations(
+  database: SqliteDatabase,
+  supplied?: readonly SqliteMigrationDefinition[],
+): Promise<void> {
+  prepare(database);
+  const definitions = supplied ? [...supplied] : await discoverMigrations();
+  definitions.sort((left, right) => left.timestamp - right.timestamp);
+  const applied = new Set(
+    database.query<Pick<AppliedMigration, "name">, []>(
+      'SELECT "name" FROM "migrations"',
+    ).all().map((row) => row.name),
+  );
+  const runner = queryRunner(database);
+  for (const definition of definitions) {
+    const name = migrationName(definition.migration);
+    if (applied.has(name)) continue;
+    database.run("BEGIN IMMEDIATE");
+    try {
+      await definition.migration.up(runner);
+      database.query(
+        'INSERT INTO "migrations" ("timestamp", "name") VALUES (?1, ?2)',
+      ).run(definition.timestamp, name);
+      database.run("COMMIT");
+    } catch (error) {
+      database.run("ROLLBACK");
+      throw error;
+    }
+  }
+}
+
+export async function revertLatestSqliteMigration(
+  database: SqliteDatabase,
+  supplied?: readonly SqliteMigrationDefinition[],
+): Promise<boolean> {
+  prepare(database);
+  const latest = database.query<AppliedMigration, []>(
+    'SELECT "id", "timestamp", "name" FROM "migrations" ORDER BY "id" DESC LIMIT 1',
+  ).get();
+  if (!latest) return false;
+  const definitions = supplied ? [...supplied] : await discoverMigrations();
+  const definition = definitions.find((item) => migrationName(item.migration) === latest.name);
+  if (!definition) throw new Error(`Cannot find SQLite migration ${latest.name} to revert`);
+  const runner = queryRunner(database);
+  database.run("BEGIN IMMEDIATE");
+  try {
+    await definition.migration.down(runner);
+    database.query('DELETE FROM "migrations" WHERE "id" = ?1').run(latest.id);
+    database.run("COMMIT");
+    return true;
+  } catch (error) {
+    database.run("ROLLBACK");
+    throw error;
+  }
+}

package/dist/templates/fullstack/compose.dev.yaml

@@ -102,7 +102,7 @@ services:
 
   minio:
     profiles: [storage]
-    image: minio/minio:latest
+    image: pgsty/silo:RELEASE.2026-09-16T00-00-00Z
     command: server /data --console-address ":9001"
     environment:
       MINIO_ROOT_USER: podokit
@@ -113,7 +113,7 @@ services:
 
   minio-init:
     profiles: [storage]
-    image: minio/mc:latest
+    image: pgsty/mc:RELEASE.2026-09-16T00-00-00Z
     depends_on:
       minio: { condition: service_started }
     entrypoint:

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -60,9 +60,14 @@ it at a different host invalidates the profile instead of deploying somewhere el
 The fields that differ from the Kubernetes driver:
 
 - `target`: Docker context, endpoint fingerprint, Compose project name
-- `exposure`: `bindAddress` and `port` published from the web service. It defaults to
-  `127.0.0.1`, because the expected front door is a reverse proxy on the same host —
-  binding every interface publishes the app before TLS exists
+- `exposure`: `bindAddress` and `port`, plus an exact `webSocketPaths` allowlist,
+  `trustedProxyCidrs`, and `gatewayImage`. With an empty allowlist, web owns the
+  published port. With paths, an internal gateway owns it, sends only exact listed
+  paths to API, and sends every other request to web. Forwarding headers are trusted
+  only from the direct proxy CIDRs in `trustedProxyCidrs`; leave it empty without an
+  external proxy. The bind address defaults to `127.0.0.1`, because the expected
+  front door is a trusted reverse proxy — binding every interface publishes the app
+  before TLS exists.
 - `workloads`: replicas plus Compose `cpus` and `memory` limits
 - `dependencies`: `managed`, `external`, or `disabled`, each with a named Docker
   volume and the path of its env file on the target host
@@ -86,3 +91,5 @@ Required keys:
 Data volumes are declared `external`, so `docker compose down -v` cannot delete the
 database. Editing an env file changes the containers' rollout label, so the next
 apply actually restarts them instead of leaving stale environment values running.
+The gateway image is resolved to an immutable digest during planning. The external
+TLS proxy keeps one upstream; do not duplicate the WebSocket path split there.

package/dist/templates/fullstack/dot-env.example

@@ -4,6 +4,8 @@
 NODE_ENV=development
 PORT=5002
 
+# Canonical database connection. Set this for PostgreSQL or SQLite; POSTGRES_* remains a fallback.
+# DATABASE_URL=postgres://podokit:podokit@localhost:5432/podokit
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_USER=podokit

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin.module.ts

@@ -3,6 +3,7 @@ import {
   PROFILE_IMAGE_REQUIRED,
   PROFILE_IMAGE_TOO_LARGE,
 } from "@podosoft/podokit-contracts";
+import { OBJECT_STORAGE } from "@podosoft/podokit-runtime";
 import { Elysia, t } from "elysia";
 import { AUTH } from "./auth/auth.module";
 import {
@@ -20,7 +21,6 @@ import {
   SiteSettingsService,
 } from "./site-settings/site-settings.service";
 import { validateSiteSetting } from "./site-settings/site-settings.validation";
-import { STORAGE } from "./storage/storage.module";
 
 export const SITE_SETTINGS = Symbol("site-settings") as ServiceKey<SiteSettingsService>;
 export const PROFILE_IMAGES = Symbol("profile-images") as ServiceKey<ProfileImageService>;
@@ -138,7 +138,7 @@ const adminPlugin: AppPlugin = ({ services }) => {
 export const adminModule: PodokitModule = {
   name: "admin-dashboard",
   configure: (_env, services): void => {
-    const storage = services.resolve(STORAGE);
+    const storage = services.resolve(OBJECT_STORAGE);
     const site = new SiteSettingsService(services.resolve(DATABASE).sql, storage);
     const profileImages = new ProfileImageService(storage, services.resolve(LOGGER));
     services.register(SITE_SETTINGS, site);