@podosoft/podokit 1.1.2 → 1.1.5

package/dist/templates/modules/auth/files/apps/api/src/auth/account-issuer-migration.ts

@@ -1,3 +1,4 @@
+import type { Database as SqliteDatabase } from "bun:sqlite";
 import type { Pool } from "pg";
 
 type MigrationRow = Record<string, unknown>;
@@ -13,95 +14,17 @@ export interface AccountIssuerMigrationDatabase {
 
 export type AccountIssuerMigrationResult = "absent" | "current" | "migrated";
 
-const LEGACY_ACCOUNT_ISSUERS = new Map<string, string>([
-  ["credential", "local:credential"],
-  ["google", "https://accounts.google.com"],
-  ["github", "local:oauth:github"],
-  ["apple", "https://appleid.apple.com"],
-  ["facebook", "https://www.facebook.com"],
-  ["discord", "local:oauth:discord"],
-  ["gitlab", "local:oauth:gitlab"],
-  ["linkedin", "local:oauth:linkedin"],
-  ["twitch", "local:oauth:twitch"],
-  ["spotify", "local:oauth:spotify"],
-  ["dropbox", "local:oauth:dropbox"],
-  ["kakao", "local:oauth:kakao"],
-  ["naver", "local:oauth:naver"],
-  ["line", "https://access.line.me"],
-  ["slack", "local:oauth:slack"],
-  ["notion", "local:oauth:notion"],
-  ["twitter", "local:oauth:twitter"],
-  ["tiktok", "local:oauth:tiktok"],
-  ["reddit", "local:oauth:reddit"],
-  ["zoom", "local:oauth:zoom"],
-  ["figma", "local:oauth:figma"],
-  ["salesforce", "local:oauth:salesforce"],
-  ["atlassian", "local:oauth:atlassian"],
-  ["kick", "local:oauth:kick"],
-]);
-
-/**
- * Resolve only identities Better Auth can migrate without consulting mutable or
- * unverified profile data. Microsoft is deliberately absent: its 1.7 identity
- * changes from `sub` to the directory `oid`, which needs a trusted external map.
- */
-export function legacyAccountIssuer(providerId: string): string | undefined {
-  return LEGACY_ACCOUNT_ISSUERS.get(providerId);
-}
-
-function sqlLiteral(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`;
-}
-
-/** Keep the release that is still serving able to insert accounts during rollout. */
-export function legacyAccountIssuerTriggerSql(): string {
-  const cases = [...LEGACY_ACCOUNT_ISSUERS.entries()]
-    .map(([providerId, issuer]) => `    WHEN ${sqlLiteral(providerId)} THEN ${sqlLiteral(issuer)}`)
-    .join("\n");
-
-  return `
-CREATE OR REPLACE FUNCTION public.podokit_fill_legacy_account_issuer()
-RETURNS trigger
-LANGUAGE plpgsql
-AS $podokit$
-BEGIN
-  IF NEW."issuer" IS NOT NULL THEN
-    RETURN NEW;
-  END IF;
-
-  NEW."issuer" := CASE NEW."providerId"
-${cases}
-    ELSE NULL
-  END;
-
-  IF NEW."issuer" IS NULL THEN
-    RAISE EXCEPTION 'Cannot infer Better Auth issuer for legacy provider %', NEW."providerId"
-      USING ERRCODE = '23502',
-            HINT = 'Add an explicit trusted issuer mapping before creating this account.';
-  END IF;
-
-  IF NEW."providerId" = 'credential' THEN
-    NEW."accountId" := NEW."userId";
-  END IF;
-
-  RETURN NEW;
-END
-$podokit$;
-
-DROP TRIGGER IF EXISTS podokit_fill_legacy_account_issuer ON "account";
-CREATE TRIGGER podokit_fill_legacy_account_issuer
-BEFORE INSERT ON "account"
-FOR EACH ROW
-WHEN (NEW."issuer" IS NULL)
-EXECUTE FUNCTION public.podokit_fill_legacy_account_issuer();
-`;
-}
-
-function readCount(rows: readonly MigrationRow[], label: string): number {
+function readCount(rows: readonly MigrationRow[]): number {
   const value = rows[0]?.count;
   if (typeof value === "number" && Number.isSafeInteger(value)) return value;
   if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
-  throw new Error(`Cannot read ${label} count during the Better Auth account migration.`);
+  throw new Error("Cannot read account identity collision count");
+}
+
+function assertNoCollisions(count: number): void {
+  if (count > 0) {
+    throw new Error("Cannot upgrade Better Auth: duplicate providerId and accountId identities require manual resolution");
+  }
 }
 
 export function postgresAccountIssuerMigrationDatabase(pool: Pool): AccountIssuerMigrationDatabase {
@@ -119,138 +42,47 @@ export function postgresAccountIssuerMigrationDatabase(pool: Pool): AccountIssue
   };
 }
 
-/**
- * Upgrade a populated pre-1.7 Better Auth account table without guessing identity.
- *
- * The compatibility trigger is installed in the same transaction as the NOT NULL
- * constraint. Writes from the release that is still serving either receive the
- * exact 1.7 issuer or fail closed for an identity that requires a trusted manual
- * mapping; they can never create a corrupt empty issuer during the rollout.
- */
+/** Relax the obsolete 1.7.0-1.7.2 issuer schema for Better Auth 1.7.3 and later. */
 export async function migrateLegacyAccountIssuers(
   database: AccountIssuerMigrationDatabase,
 ): Promise<AccountIssuerMigrationResult> {
   const client = await database.connect();
   let transactionOpen = false;
-
   try {
     await client.query("BEGIN");
     transactionOpen = true;
     await client.query("SELECT pg_advisory_xact_lock(1886350955, 1)");
-
     const tableRows = await client.query<{ exists: boolean }>(`
-      SELECT EXISTS (
-        SELECT 1
-        FROM information_schema.tables
-        WHERE table_schema = 'public' AND table_name = 'account'
-      ) AS "exists"
+      SELECT to_regclass('"account"') IS NOT NULL AS "exists"
     `);
     if (tableRows[0]?.exists !== true) {
       await client.query("COMMIT");
       transactionOpen = false;
       return "absent";
     }
-
-    const columnRows = await client.query<{ dataType: string; isNullable: "YES" | "NO" }>(`
-      SELECT data_type AS "dataType", is_nullable AS "isNullable"
-      FROM information_schema.columns
-      WHERE table_schema = 'public' AND table_name = 'account' AND column_name = 'issuer'
-    `);
-    const column = columnRows[0];
-    if (column && column.dataType !== "text" && column.dataType !== "character varying") {
-      throw new Error(`Cannot migrate Better Auth account issuer from database type ${column.dataType}.`);
-    }
-
-    if (column?.isNullable === "NO") {
-      const invalidRows = await client.query<MigrationRow>(`
-        SELECT COUNT(*)::int AS "count"
-        FROM "account"
-        WHERE btrim("issuer") = ''
-      `);
-      if (readCount(invalidRows, "blank issuer") > 0) {
-        throw new Error("Cannot continue: the Better Auth account table contains blank issuer values.");
-      }
-      await client.query(legacyAccountIssuerTriggerSql());
-      await client.query("COMMIT");
-      transactionOpen = false;
-      return "current";
-    }
-
-    if (!column) {
-      await client.query('ALTER TABLE "account" ADD COLUMN "issuer" text');
-    }
-
-    const providerRows = await client.query<{ providerId: string }>(`
-      SELECT DISTINCT "providerId"
-      FROM "account"
-      WHERE "issuer" IS NULL
-      ORDER BY "providerId"
-    `);
-    for (const { providerId } of providerRows) {
-      const issuer = legacyAccountIssuer(providerId);
-      if (!issuer) {
-        throw new Error(
-          `Cannot infer a trusted Better Auth issuer for legacy provider ${providerId}. ` +
-            "Follow the Better Auth 1.7 account identity migration guide and provide a verified mapping.",
-        );
-      }
-
-      if (providerId === "credential") {
-        const mismatchRows = await client.query<MigrationRow>(`
-          SELECT COUNT(*)::int AS "count"
-          FROM "account"
-          WHERE "issuer" IS NULL
-            AND "providerId" = 'credential'
-            AND "accountId" <> "userId"
-        `);
-        if (readCount(mismatchRows, "credential identity mismatch") > 0) {
-          throw new Error(
-            "Cannot migrate credential accounts whose accountId differs from the linked userId.",
-          );
-        }
-      }
-
-      await client.query(
-        `UPDATE "account"
-         SET "issuer" = $1,
-             "accountId" = CASE WHEN "providerId" = 'credential' THEN "userId" ELSE "accountId" END
-         WHERE "issuer" IS NULL AND "providerId" = $2`,
-        [issuer, providerId],
-      );
-    }
-
-    const invalidRows = await client.query<MigrationRow>(`
-      SELECT COUNT(*)::int AS "count"
-      FROM "account"
-      WHERE "issuer" IS NULL OR btrim("issuer") = ''
-    `);
-    if (readCount(invalidRows, "unresolved issuer") > 0) {
-      throw new Error("Cannot continue: one or more Better Auth accounts have no trusted issuer.");
-    }
-
-    const collisionRows = await client.query<MigrationRow>(`
-      SELECT COUNT(*)::int AS "count"
-      FROM (
-        SELECT "issuer", "accountId"
-        FROM "account"
-        GROUP BY "issuer", "accountId"
-        HAVING COUNT(*) > 1
+    await client.query('LOCK TABLE "account" IN SHARE ROW EXCLUSIVE MODE');
+    const collisions = await client.query<MigrationRow>(`
+      SELECT COUNT(*)::int AS "count" FROM (
+        SELECT "providerId", "accountId" FROM "account"
+        GROUP BY "providerId", "accountId" HAVING COUNT(*) > 1
       ) AS collisions
     `);
-    if (readCount(collisionRows, "identity collision") > 0) {
-      throw new Error(
-        "Cannot continue: Better Auth accounts collide on the new issuer and accountId identity key.",
-      );
+    assertNoCollisions(readCount(collisions));
+    const columns = await client.query<{ exists: boolean }>(`
+      SELECT EXISTS (
+        SELECT 1 FROM pg_attribute
+        WHERE attrelid = '"account"'::regclass AND attname = 'issuer' AND NOT attisdropped
+      ) AS "exists"
+    `);
+    await client.query('DROP TRIGGER IF EXISTS podokit_fill_legacy_account_issuer ON "account"');
+    await client.query('DROP INDEX IF EXISTS "account_issuer_accountId_uidx"');
+    if (columns[0]?.exists === true) {
+      await client.query('ALTER TABLE "account" ALTER COLUMN "issuer" DROP NOT NULL');
     }
-
-    await client.query(legacyAccountIssuerTriggerSql());
-    await client.query('ALTER TABLE "account" ALTER COLUMN "issuer" SET NOT NULL');
-    await client.query(
-      'CREATE UNIQUE INDEX IF NOT EXISTS "account_issuer_accountId_uidx" ON "account" ("issuer", "accountId")',
-    );
+    await client.query('CREATE UNIQUE INDEX IF NOT EXISTS "account_providerId_accountId_uidx" ON "account" ("providerId", "accountId")');
     await client.query("COMMIT");
     transactionOpen = false;
-    return "migrated";
+    return columns[0]?.exists === true ? "migrated" : "current";
   } catch (error: unknown) {
     if (transactionOpen) await client.query("ROLLBACK");
     throw error;
@@ -258,3 +90,34 @@ export async function migrateLegacyAccountIssuers(
     client.release();
   }
 }
+
+/** SQLite follows the upstream cleanup: remove the unused issuer column. */
+export function migrateSqliteLegacyAccountIssuers(database: SqliteDatabase): AccountIssuerMigrationResult {
+  database.run("BEGIN IMMEDIATE");
+  try {
+    const table = database.query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'account'",
+    ).get();
+    if (!table) {
+      database.run("COMMIT");
+      return "absent";
+    }
+    const collision = database.query<{ count: number }, []>(`
+      SELECT COUNT(*) AS count FROM (
+        SELECT "providerId", "accountId" FROM "account"
+        GROUP BY "providerId", "accountId" HAVING COUNT(*) > 1
+      )
+    `).get();
+    assertNoCollisions(readCount(collision ? [collision] : []));
+    const hasIssuer = database.query<{ name: string }, []>('PRAGMA table_info("account")').all()
+      .some((column) => column.name === "issuer");
+    database.run('DROP INDEX IF EXISTS "account_issuer_accountId_uidx"');
+    if (hasIssuer) database.run('ALTER TABLE "account" DROP COLUMN "issuer"');
+    database.run('CREATE UNIQUE INDEX IF NOT EXISTS "account_providerId_accountId_uidx" ON "account" ("providerId", "accountId")');
+    database.run("COMMIT");
+    return hasIssuer ? "migrated" : "current";
+  } catch (error: unknown) {
+    database.run("ROLLBACK");
+    throw error;
+  }
+}

package/dist/templates/modules/auth/files/apps/api/src/migrate.ts

@@ -3,6 +3,7 @@ import { auth } from "./auth/auth";
 import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";
 import {
   migrateLegacyAccountIssuers,
+  migrateSqliteLegacyAccountIssuers,
   postgresAccountIssuerMigrationDatabase,
 } from "./auth/account-issuer-migration";
 import { runSqliteMigrations } from "./database/sqlite-migrator";
@@ -11,6 +12,7 @@ async function runMigrations(): Promise<void> {
   if (postgresPool) {
     await migrateLegacyAccountIssuers(postgresAccountIssuerMigrationDatabase(postgresPool));
   }
+  if (sqliteDatabase) migrateSqliteLegacyAccountIssuers(sqliteDatabase);
 
   const authMigrations = await getMigrations(auth.options);
   await authMigrations.runMigrations();

package/dist/templates/modules/auth/module.manifest.json

@@ -9,11 +9,11 @@
   "dependencies": {
     "@podosoft/podokit-auth": "^0.4.0",
     "@podosoft/podokit-contracts": "^0.4.0",
-    "better-auth": "^1.7.1",
+    "better-auth": "^1.7.7",
     "pg": "^8.12.0",
-    "@better-auth/api-key": "^1.7.1",
-    "@better-auth/passkey": "^1.7.1",
-    "@better-auth/oauth-provider": "^1.7.1"
+    "@better-auth/api-key": "^1.7.7",
+    "@better-auth/passkey": "^1.7.7",
+    "@better-auth/oauth-provider": "^1.7.7"
   },
   "devDependencies": {
     "@types/pg": "^8.11.10"
@@ -58,7 +58,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### auth (Better Auth + Elysia)\n- The API is secure by default: every application route needs a session except health, OpenAPI, `/api/auth/*`, and routes explicitly registered in `ACCESS_POLICY`.\n- Register a public route during module configuration with `services.resolve(ACCESS_POLICY).register(\"GET\", \"/path\", \"public\")`; use `AUTH` and `AuthService.requireSession()` or `requireAdmin()` when a handler needs the current user.\n- Configure OAuth providers, SMTP, sign-up approval, automatic logout, and server toggles on the admin Settings page. Only `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are required environment variables.\n- Use `{{apiRun}} auth:configure{{apiWorkspaceArg}} -- ...` and `.claude/skills/podokit-configure-auth` to apply OAuth/SMTP credentials without committing secrets.\n- Run `bun run --cwd apps/api migrate:all` in development and production so Better Auth and application migrations use the versions installed by the app.\n"
+      "text": "### auth (Better Auth + Elysia)\n- The API is secure by default: every application route needs a session except health, OpenAPI, `/api/auth/*`, and routes explicitly registered in `ACCESS_POLICY`.\n- Register a public route during module configuration with `services.resolve(ACCESS_POLICY).register(\"GET\", \"/path\", \"public\")`; use `AUTH` and `AuthService.requireSession()` or `requireAdmin()` when a handler needs the current user.\n- Configure OAuth providers, SMTP, sign-up approval, automatic logout, and server toggles on the admin Settings page. Only `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are required environment variables.\n- Use `{{apiRun}} auth:configure{{apiWorkspaceArg}} -- ...` and `.claude/skills/podokit-configure-auth` to apply OAuth/SMTP credentials without committing secrets.\n- Run `bun run --cwd apps/api migrate:all` in development and production so Better Auth and application migrations use the versions installed by the app.\n- Back up existing databases before upgrading authentication. Migrations check duplicate `(providerId, accountId)` identities and clean up obsolete issuer constraints; resolve reported collisions manually rather than guessing account ownership.\n"
     }
   ],
   "instructions": [

package/dist/templates/modules/object-storage-s3/files/tests/api/storage.api.spec.ts

@@ -27,9 +27,13 @@ test("object storage: put, get, and presign @smoke", async ({ playwright }) => {
     expect(presigned.ok()).toBeTruthy();
     const pre = await presigned.json() as { url: string };
     expect(new URL(pre.url).pathname).toContain(key);
-    const download = await ctx.get(pre.url);
-    expect(download.ok()).toBeTruthy();
-    expect(await download.text()).toBe("hello world");
+    // The URL is signed for the API's S3 endpoint. A containerized dev stack signs an
+    // in-network host, so download it only when the runner was given that endpoint too.
+    if (process.env.S3_ENDPOINT) {
+      const download = await ctx.get(pre.url);
+      expect(download.ok()).toBeTruthy();
+      expect(await download.text()).toBe("hello world");
+    }
   } finally {
     await ctx.dispose();
   }

package/dist/templates/todo/AGENTS.md

@@ -8,26 +8,44 @@ 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.
-- `.podokit/` — PodoKit's generation lockfile (see "PodoKit tooling" below). Do not edit by hand.
+- `infra/` — Docker Compose references for external services and example k3s manifests.
+- `.podokit/` — generation metadata plus application-owned development and deployment profiles.
 - **Todo example**: `apps/api/src/todos/` (Elysia plugin, Bun.SQL repository, and migration) and the todo UI in `apps/web/src/routes/` show the end-to-end patterns to follow.
 
 ## Setup & commands
 
+Inspect active infrastructure with `podo provider list`. New-project defaults
+are `database=postgres`, `cache=redis`, `object-storage=s3`, `events=redis`, and
+`jobs=bullmq`. A simple single-process app can instead use `sqlite`, `memory`
+cache/events, `local` files, and `local` jobs. Only the database has a creation
+flag (`--database`); apply other choices using
+`podo provider set <capability> <provider> --apply` before adding features.
+Provider selection does not migrate or delete existing data.
+
 ```bash
 {{packageManager}} install
 cp .env.example .env
-docker compose -f infra/docker/docker-compose.yml up -d   # PostgreSQL (+ Redis)
+{{apiRun}} migration:run
 {{rootRun}} dev        # api on http://localhost:5002, web on http://localhost:5001
 ```
 
+For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
+before migrating. Add `--profile cache` for Redis; Silo uses the overlay from
+`object-storage-s3`. Skip external services entirely for the complete local
+combination. `podo dev watch` is a separate container workflow and requires
+Docker. SQLite and local files default to `./data/podokit.sqlite` and
+`./data/files` relative to the API working directory; migrations and runtime
+must use the same database path. Keep local providers at one API process.
+Merge added module settings from `.env.example` into an existing `.env`.
+
 - **Ports: web = 5001, api = 5002.** The web app reaches the API only through its
   SvelteKit server proxy (`/api/*`), never with a direct browser `fetch`.
 - Build: `{{rootRun}} build`  ·  Type-check/lint: `{{rootRun}} lint`  ·  Unit tests: `{{rootRun}} test`
 - Per workspace: `{{apiRun}} build` / `{{webRun}} build`.
-- DB migrations (TypeORM migration layer only): `{{apiRun}} migration:run`.
+- Application migrations (PostgreSQL or SQLite): `{{apiRun}} migration:run`.
+- When `auth` is installed, run `{{apiRun}} migrate:all` for Better Auth and application tables.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`.
 - Playwright officially runs on Node, so `bunx playwright` respects its Node
   shebang. Node LTS is a test-tool dependency only; API, web, worker, migrations,
@@ -69,6 +87,7 @@ in `.podokit/files.lock` — respect it:
 
 Useful commands:
 
+- `podo provider list` / `podo provider set <capability> <provider> [--apply]` — inspect or switch database, cache, storage, events, and jobs; set previews by default.
 - `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 status` / `podo diff` — see your local edits vs. what PodoKit generated.

package/dist/templates/todo/README.md

@@ -2,9 +2,47 @@
 
 Full-stack TypeScript app generated with [PodoKit](https://github.com/podosoft-dev/podokit).
 
-- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, a Bun.SQL Todo CRUD resource backed by PostgreSQL, merged OpenAPI at `/api-docs`, and a standard error envelope.
+- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, a Bun.SQL Todo CRUD resource backed by PostgreSQL or SQLite, merged OpenAPI at `/api-docs`, and a standard error envelope.
 - `apps/web` — SvelteKit app (TailwindCSS v4, shadcn-svelte, typesafe-i18n) with a todo UI that talks to the API through a server-side proxy.
-- `infra/` — Docker Compose (PostgreSQL, Redis) and k3s manifests.
+- `infra/` — Docker Compose references for external services and k3s manifests.
+
+## Infrastructure choices
+
+Inspect the current selections with `{{packageExecutor}} @podosoft/podokit provider list`.
+New projects use these defaults unless configured otherwise:
+
+| Capability | Default | Lightweight alternative |
+| --- | --- | --- |
+| Database | `postgres` | `sqlite` |
+| Cache | `redis` | `memory` |
+| Object storage | `s3` | `local` |
+| Events | `redis` | `memory` |
+| Jobs | `bullmq` | `local` |
+
+For a simple program, prototype, or desktop app, SQLite, memory cache/events,
+local files, and local jobs can run inside one API process without PostgreSQL,
+Redis, or S3 services. `create --database sqlite` selects only the database;
+choose the other providers after creation:
+
+```bash
+{{packageExecutor}} @podosoft/podokit provider set cache memory --apply
+{{packageExecutor}} @podosoft/podokit provider set object-storage local --apply
+{{packageExecutor}} @podosoft/podokit provider set events memory --apply
+{{packageExecutor}} @podosoft/podokit provider set jobs local --apply
+```
+
+Apply providers before adding features, then install dependencies and merge new
+`.env.example` entries into `.env`. These commands install implementation modules
+and configure them; they do not move or delete data. SQLite defaults to
+`./data/podokit.sqlite`, and local files to `LOCAL_STORAGE_PATH=./data/files`,
+relative to the API working directory. Memory cache/events are lost on restart;
+the database, files, and local job records persist. Use absolute paths and back
+up the database and files together for packaged or production apps.
+
+Use the host-process setup below to avoid Docker. The containerized loop still
+requires Docker. See the PodoKit
+[runtime provider guide](https://github.com/podosoft-dev/podokit/blob/main/docs/providers.md)
+for server settings, Silo/AWS S3 configuration, and provider switching.
 
 ## Getting started
 
@@ -57,17 +95,27 @@ through Compose Watch, including Vite HMR on the same portless browser origin.
 
 ### Alternative: host processes
 
-Use this loop when you want only the web and API processes on the host:
+Use this loop for an app with SQLite and local providers, or when you want the
+web and API processes on the host. Prepare the project first:
 
 ```bash
-# start local PostgreSQL + Redis
-docker compose -f infra/docker/docker-compose.yml up -d
-
-# run database migrations
+{{packageManager}} install
+cp .env.example .env
 {{apiRun}} migration:run
+```
+
+For PostgreSQL, start `docker compose -f infra/docker/docker-compose.yml up -d`
+before migrating. Redis needs `--profile cache`; Silo needs the storage overlay
+added by `object-storage-s3`. Skip those services for the complete local setup.
+
+Run each service in a separate terminal from the project root:
 
-# run api + web
-{{packageManager}} run dev
+```bash
+{{apiRun}} dev # terminal 1
+```
+
+```bash
+{{webRun}} dev # terminal 2
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
@@ -78,14 +126,19 @@ tunnel, see the PodoKit [development guide](https://github.com/podosoft-dev/podo
 
 ## Database & migrations
 
-The API uses Bun.SQL with PostgreSQL. TypeORM is limited to the migration layer;
-a sample Todo repository and initial migration are included.
+The API uses Bun.SQL with the selected PostgreSQL or SQLite database. TypeORM
+runs PostgreSQL migrations; SQLite uses the local migration runner. A sample
+Todo repository and initial migration are included.
 
 ```bash
 {{apiRun}} migration:run      # apply migrations
 {{apiRun}} migration:revert   # roll back the last one
 ```
 
+When `auth` is installed, use `{{apiRun}} migrate:all` to create or update both
+Better Auth and application tables. Set the module's required environment
+values before migrating.
+
 ## Deploy
 
 Docker Compose lives in `infra/docker`; the basic k3s manifests in `infra/k3s`

package/dist/templates/todo/apps/api/src/migrations/1720100000000-InitTodos.ts

@@ -4,6 +4,17 @@ export class InitTodos1720100000000 implements MigrationInterface {
   name = "InitTodos1720100000000";
 
   async up(queryRunner: QueryRunner): Promise<void> {
+    if (queryRunner.connection.options.type === "better-sqlite3") {
+      await queryRunner.query(`
+        CREATE TABLE "todos" (
+          "id" text NOT NULL PRIMARY KEY,
+          "title" character varying(500) NOT NULL,
+          "completed" boolean NOT NULL DEFAULT false,
+          "createdAt" text NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+        )
+      `);
+      return;
+    }
     await queryRunner.query(`CREATE EXTENSION IF NOT EXISTS "pgcrypto"`);
     await queryRunner.query(`
       CREATE TABLE "todos" (

package/dist/templates/todo/apps/api/src/todos/todo.repository.spec.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "bun:test";
+import { SQL } from "bun";
+import { Database as SqliteDatabase } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  revertLatestSqliteMigration,
+  runSqliteMigrations,
+  type SqliteMigrationDefinition,
+} from "../database/sqlite-migrator";
+import { InitTodos1720100000000 } from "../migrations/1720100000000-InitTodos";
+import { TodoRepository } from "./todo.repository";
+
+const migrations: readonly SqliteMigrationDefinition[] = [
+  { timestamp: 1720100000000, migration: new InitTodos1720100000000() },
+];
+
+describe("Todo SQLite persistence", () => {
+  it("preserves boolean and Date rows returned by PostgreSQL", async (): Promise<void> => {
+    const row = {
+      id: crypto.randomUUID(),
+      title: "Existing task",
+      completed: true,
+      createdAt: new Date("2026-10-07T00:00:00.000Z"),
+    };
+    const sql = ((): Promise<typeof row[]> => Promise.resolve([row])) as unknown as SQL;
+    expect(await new TodoRepository(sql).find(row.id)).toEqual({
+      ...row,
+      createdAt: "2026-10-07T00:00:00.000Z",
+    });
+  });
+
+  it("applies the initial migration once and reverts it", async (): Promise<void> => {
+    const database = new SqliteDatabase(":memory:");
+    try {
+      await runSqliteMigrations(database, migrations);
+      await runSqliteMigrations(database, migrations);
+      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 = 'todos'").get()?.name).toBe("todos");
+      expect(await revertLatestSqliteMigration(database, migrations)).toBe(true);
+      expect(database.query("SELECT name FROM sqlite_master WHERE name = 'todos'").get()).toBeNull();
+    } finally {
+      database.close();
+    }
+  });
+
+  it("creates, reads, updates, and removes records with stable API types", async (): Promise<void> => {
+    const directory = mkdtempSync(join(tmpdir(), "podokit-todo-"));
+    const path = join(directory, "podokit.sqlite");
+    const database = new SqliteDatabase(path);
+    let sql: SQL | undefined;
+    try {
+      await runSqliteMigrations(database, migrations);
+      sql = new SQL(`sqlite://${path}`, { adapter: "sqlite" });
+      const repository = new TodoRepository(sql);
+      const todo = await repository.create("First task");
+      expect(todo.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+      expect(todo.completed).toBe(false);
+      expect(new Date(todo.createdAt).toISOString()).toBe(todo.createdAt);
+      expect(await repository.find(todo.id)).toEqual(todo);
+      expect(await repository.all()).toEqual([todo]);
+
+      const updated = await repository.update(todo.id, { title: "Completed task", completed: true });
+      expect(updated).toEqual({ ...todo, title: "Completed task", completed: true });
+      expect(await repository.remove(todo.id)).toBe(true);
+      expect(await repository.find(todo.id)).toBeNull();
+      expect(await repository.update(todo.id, { completed: false })).toBeNull();
+      expect(await repository.remove(todo.id)).toBe(false);
+    } finally {
+      await sql?.close();
+      database.close();
+      rmSync(directory, { recursive: true, force: true });
+    }
+  });
+});

package/dist/templates/todo/apps/api/src/todos/todo.repository.ts

@@ -10,12 +10,16 @@ export interface TodoRecord {
 interface TodoRow {
   id: string;
   title: string;
-  completed: boolean;
-  createdAt: Date;
+  completed: boolean | number;
+  createdAt: Date | string;
 }
 
 function record(row: TodoRow): TodoRecord {
-  return { ...row, createdAt: row.createdAt.toISOString() };
+  return {
+    ...row,
+    completed: Boolean(row.completed),
+    createdAt: (row.createdAt instanceof Date ? row.createdAt : new Date(row.createdAt)).toISOString(),
+  };
 }
 
 export class TodoRepository {
@@ -39,8 +43,9 @@ export class TodoRepository {
   }
 
   async create(title: string): Promise<TodoRecord> {
+    const id = crypto.randomUUID();
     const rows = await this.sql<TodoRow[]>`
-      INSERT INTO todos (title) VALUES (${title})
+      INSERT INTO todos (id, title) VALUES (${id}, ${title})
       RETURNING id, title, completed, "createdAt"
     `;
     const row = rows[0];