@podosoft/podokit 1.1.2 → 1.1.4

package/README.md

@@ -7,11 +7,38 @@ through native `Bun.SQL`, Tailwind CSS v4, shadcn-svelte, Docker, and k3s assets
 The CLI itself remains Node-compatible, so either `npx` or `bunx` can create and
 maintain projects. Generated PodoKit v1 applications are Bun-only.
 
+## Choose infrastructure
+
+`fullstack` is the default template. `todo` adds a working CRUD example; `base`
+is a minimal workspace with placeholder scripts. For a small working app, use
+`fullstack` or `todo` with local providers rather than choosing `base` just to
+avoid external infrastructure.
+
+| Capability | Default | Local alternative |
+| --- | --- | --- |
+| Database | `postgres` — PostgreSQL | `sqlite` — database file |
+| Cache | `redis` | `memory` — in-process cache |
+| Object storage | `s3` — AWS S3 or S3-compatible storage | `local` — local files |
+| Events | `redis` | `memory` — in-process events |
+| Jobs | `bullmq` — Redis queue and separate worker | `local` — database-backed embedded worker |
+
+A simple program, prototype, desktop app, or single-process service can use
+**SQLite, memory cache, and local files** without PostgreSQL, Redis, or S3.
+Providers can be mixed. Local providers require one API process.
+
+Only the database is selected during creation with `--database postgres|sqlite`.
+Other capabilities use `provider set` after creation; there are no `--cache` or
+`--storage` creation flags. Choosing SQLite alone leaves the other defaults
+unchanged. Creation records selections, while applying a provider or adding a
+feature installs the necessary optional implementation modules.
+
 ## Quick start
 
+### Default server setup
+
 ```bash
 npx @podosoft/podokit create my-app
-# or: bunx @podosoft/podokit create my-app
+# or: bunx --bun @podosoft/podokit create my-app
 
 cd my-app
 bun install
@@ -28,6 +55,26 @@ PostgreSQL or SQLite persistence:
 
 ![Generated todo app](https://raw.githubusercontent.com/podosoft-dev/podokit/main/docs/images/todo-app.png)
 
+### Small app with local providers
+
+```bash
+bunx --bun @podosoft/podokit create podokit --template todo --database sqlite --yes
+cd podokit
+bunx --bun @podosoft/podokit provider set cache memory --apply
+bunx --bun @podosoft/podokit provider set object-storage local --apply
+bunx --bun @podosoft/podokit provider set events memory --apply
+bunx --bun @podosoft/podokit provider set jobs local --apply
+bun install
+cp .env.example .env
+bun run --cwd apps/api migration:run
+```
+
+Run `bun run --cwd apps/api dev` and `bun run --cwd apps/web dev` in separate
+terminals and open `http://localhost:5001`. This host-process setup requires no
+Docker. SQLite and local files default to `./data/podokit.sqlite` and
+`./data/files`, relative to the API working directory. Memory state disappears
+on restart; files and the database-backed local jobs persist.
+
 ## Commands
 
 | Command | Purpose |
@@ -85,14 +132,21 @@ and [updating guide](https://github.com/podosoft-dev/podokit/blob/main/docs/upda
 
 ## Runtime providers
 
-Generated projects use stable capability contracts with server defaults
-(`postgres`, `redis`, `s3`, Redis events, and `bullmq`) and local alternatives
-(`sqlite`, memory cache/events, local files/jobs). `podo provider set` is a dry
-run by default and installs the selected implementation module on `--apply`.
-It changes code and configuration only; it never migrates or deletes data.
+Inspect active selections and available alternatives with `podo provider list`.
+`podo provider set` is a dry run by default and installs the selected
+implementation module on `--apply`. Configure providers before adding features:
+`file-upload` uses local storage when selected, and `job-progress` can use local
+jobs and memory events. Changes append settings to `.env.example`; merge them
+into an existing `.env` manually. Switching changes code and configuration only;
+it never migrates or deletes data.
+
+S3's development settings use Silo with `STORAGE_PROVIDER=minio`; use
+`STORAGE_PROVIDER=aws` for AWS S3. Local files use `LOCAL_STORAGE_PATH`.
 
 See the [runtime provider guide](https://github.com/podosoft-dev/podokit/blob/main/docs/providers.md)
 before switching an existing project.
+For the complete creation sequence, see
+[Getting Started](https://github.com/podosoft-dev/podokit/blob/main/docs/getting-started.md).
 
 ## Compatibility boundary
 

package/dist/templates/base/AGENTS.md

@@ -5,19 +5,25 @@ by [PodoKit](https://github.com/podosoft-dev/podokit).
 
 ## Project overview
 
-A minimal Bun 1.4 workspace starter. Build it up from here — add features with the
-`podo` CLI (`podo add <module>`; run `podo add` with no argument to list them).
+A minimal Bun 1.4 workspace starter with placeholder API/web scripts. Build your
+own foundation here. Modules requiring the fullstack service registry, provider
+consumers, or injection points cannot be added directly to this skeleton.
+
+For a simple working full-stack app, create `fullstack` or `todo` with SQLite,
+memory cache/events, local files, and local jobs. Those templates support local
+providers independently of template choice and need one API process. See
+[Getting Started](https://github.com/podosoft-dev/podokit/blob/main/docs/getting-started.md).
 
 ## Commands
 
 ```bash
 {{packageManager}} install
-{{rootRun}} dev      # runs workspace dev scripts
 {{rootRun}} build
 {{rootRun}} lint     # type-check
 {{rootRun}} test
 ```
 
+The generated scripts are placeholders; implement them before running the app.
 ## Code style
 
 - TypeScript `strict`. **No `any`** (use `unknown` + narrowing), no `@ts-ignore`.

package/dist/templates/base/README.md

@@ -2,18 +2,22 @@
 
 Generated with [PodoKit](https://github.com/podosoft-dev/podokit).
 
-A minimal Bun 1.4 TypeScript workspace. Add the `fullstack` template when you
-need an Elysia API and SvelteKit web application.
+A minimal Bun 1.4 TypeScript workspace with placeholder API/web scripts. Choose
+`fullstack` or `todo` when creating a project that needs the working Elysia API,
+SvelteKit web app, database integration, or feature modules.
+
+For a simple working app, those templates support SQLite, memory cache/events,
+local files, and local jobs without external PostgreSQL, Redis, or S3 services.
+`base` is for building your own foundation; it does not include the provider
+consumers or module integration points. See
+[Getting Started](https://github.com/podosoft-dev/podokit/blob/main/docs/getting-started.md).
 
 ## Getting started
 
 ```bash
 {{packageManager}} install
-{{packageManager}} run dev
-```
-
-Copy the example environment file before running:
-
-```bash
 cp .env.example .env
 ```
+
+Implement the workspace scripts before running the application. The generated
+`dev` commands are placeholders and do not start services.

package/dist/templates/fullstack/AGENTS.md

@@ -16,18 +16,36 @@ A Bun 1.4 full-stack TypeScript monorepo ({{packageManager}} workspaces):
 
 ## 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   # selected external providers only
+{{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,

package/dist/templates/fullstack/README.md

@@ -2,9 +2,47 @@
 
 Full-stack TypeScript starter generated with [PodoKit](https://github.com/podosoft-dev/podokit).
 
-- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, merged OpenAPI at `/api-docs`, a standard error envelope, and Bun.SQL + PostgreSQL. TypeORM is used only to execute migrations.
+- `apps/api` — Bun 1.4 + Elysia API: schema-validated env, `/health` + `/health/ready`, merged OpenAPI at `/api-docs`, a standard error envelope, and Bun.SQL with PostgreSQL or SQLite. TypeORM is used only for PostgreSQL migrations; SQLite has its own migration runner.
 - `apps/web` — SvelteKit app (TailwindCSS v4, shadcn-svelte, typesafe-i18n) 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,13 +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
+{{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:
 
 ```bash
-# start local PostgreSQL + Redis
-docker compose -f infra/docker/docker-compose.yml up -d
+{{apiRun}} dev # terminal 1
+```
 
-{{packageManager}} run dev
+```bash
+{{webRun}} dev # terminal 2
 ```
 
 - API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
@@ -71,13 +123,18 @@ docker compose -f infra/docker/docker-compose.yml up -d
 
 ## Database & migrations
 
-The API uses Bun.SQL for request-time queries and TypeORM only as a migration
-runner. Add a numbered migration under `apps/api/src/migrations`, then run it:
+The API uses Bun.SQL with the selected PostgreSQL or SQLite database. TypeORM
+runs PostgreSQL migrations; SQLite uses the local migration runner. Add a
+numbered migration under `apps/api/src/migrations`, then run it:
 
 ```bash
 {{apiRun}} migration:run
 ```
 
+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.
+
 Want a worked example? Generate the `todo` template instead:
 `{{packageExecutor}} @podosoft/podokit create my-app --template todo`.
 

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

@@ -6,7 +6,7 @@
     "dev": "bun --watch src/main.ts",
     "build": "bun scripts/build.mjs",
     "start": "bun dist/main.js",
-    "lint": "bunx tsc -p tsconfig.json --noEmit",
+    "lint": "bunx --bun tsc -p tsconfig.json --noEmit",
     "test": "bun test src",
     "contract": "bun scripts/verify-api-contract.ts",
     "migrate:all": "bun dist/database/migrate.js",

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

@@ -1,170 +1,88 @@
 import { describe, expect, it } from "bun:test";
-import { SUPPORTED_SOCIAL_PROVIDERS } from "@podosoft/podokit-auth";
+import { Database } from "bun:sqlite";
 import {
-  legacyAccountIssuer,
-  legacyAccountIssuerTriggerSql,
   migrateLegacyAccountIssuers,
+  migrateSqliteLegacyAccountIssuers,
   type AccountIssuerMigrationClient,
-  type AccountIssuerMigrationDatabase,
 } from "./account-issuer-migration";
 
-type Statement = { sql: string; values?: readonly unknown[] };
-type LegacyAccountOptions = {
-  tableExists?: boolean;
-  column?: { dataType: string; isNullable: "YES" | "NO" };
-  counts?: {
-    blankIssuer?: number;
-    credentialMismatch?: number;
-    unresolvedIssuer?: number;
-    collision?: number;
-  };
-};
-
-class LegacyAccountClient implements AccountIssuerMigrationClient {
-  readonly statements: Statement[] = [];
+class AccountClient implements AccountIssuerMigrationClient {
+  readonly statements: string[] = [];
   released = false;
-
-  constructor(
-    private readonly providers: readonly string[],
-    private readonly options: LegacyAccountOptions = {},
-  ) {}
-
-  async query<Row extends Record<string, unknown>>(
-    sql: string,
-    values?: readonly unknown[],
-  ): Promise<readonly Row[]> {
-    this.statements.push({ sql, ...(values ? { values } : {}) });
-    if (sql.includes("information_schema.tables")) {
-      return [{ exists: this.options.tableExists ?? true }] as unknown as Row[];
-    }
-    if (sql.includes("information_schema.columns")) {
-      return (this.options.column ? [this.options.column] : []) as unknown as Row[];
-    }
-    if (sql.includes('SELECT DISTINCT "providerId"')) {
-      return this.providers.map((providerId) => ({ providerId })) as unknown as Row[];
-    }
-    if (sql.includes('COUNT(*)::int AS "count"')) {
-      const count = sql.includes('"accountId" <> "userId"')
-        ? this.options.counts?.credentialMismatch
-        : sql.includes("AS collisions")
-          ? this.options.counts?.collision
-          : sql.includes('"issuer" IS NULL OR')
-            ? this.options.counts?.unresolvedIssuer
-            : this.options.counts?.blankIssuer;
-      return [{ count: count ?? 0 }] as unknown as Row[];
-    }
+  constructor(private readonly table = true, private readonly issuer = true, private readonly collisions = 0) {}
+  async query<Row extends Record<string, unknown>>(sql: string): Promise<readonly Row[]> {
+    this.statements.push(sql.trim());
+    if (sql.includes("to_regclass")) return [{ exists: this.table }] as unknown as Row[];
+    if (sql.includes("pg_attribute")) return [{ exists: this.issuer }] as unknown as Row[];
+    if (sql.includes("AS collisions")) return [{ count: this.collisions }] as unknown as Row[];
     return [];
   }
-
-  release(): void {
-    this.released = true;
-  }
+  release(): void { this.released = true; }
 }
 
-function database(client: LegacyAccountClient): AccountIssuerMigrationDatabase {
-  return { connect: async (): Promise<AccountIssuerMigrationClient> => client };
+async function migrate(client: AccountClient): Promise<string> {
+  return migrateLegacyAccountIssuers({ connect: async (): Promise<AccountIssuerMigrationClient> => client });
 }
 
-describe("Better Auth account issuer migration", () => {
-  it("maps every safely derivable provider and refuses identities that need trusted external data", () => {
-    expect(legacyAccountIssuer("credential")).toBe("local:credential");
-    expect(legacyAccountIssuer("google")).toBe("https://accounts.google.com");
-    expect(legacyAccountIssuer("apple")).toBe("https://appleid.apple.com");
-    expect(legacyAccountIssuer("facebook")).toBe("https://www.facebook.com");
-    expect(legacyAccountIssuer("line")).toBe("https://access.line.me");
-    expect(legacyAccountIssuer("github")).toBe("local:oauth:github");
-    expect(legacyAccountIssuer("microsoft")).toBeUndefined();
-    expect(legacyAccountIssuer("unknown-provider")).toBeUndefined();
-
-    for (const { id } of SUPPORTED_SOCIAL_PROVIDERS) {
-      if (id !== "microsoft") expect(legacyAccountIssuer(id), id).toBeDefined();
-    }
-  });
+function legacyDatabase(): Database {
+  const database = new Database(":memory:");
+  database.run('CREATE TABLE account (id text PRIMARY KEY, "providerId" text NOT NULL, "accountId" text NOT NULL, "userId" text NOT NULL, password text, issuer text NOT NULL)');
+  database.run('CREATE UNIQUE INDEX "account_issuer_accountId_uidx" ON account (issuer, "accountId")');
+  database.run('INSERT INTO account VALUES (\'account\', \'credential\', \'user\', \'user\', \'password-hash\', \'local:credential\')');
+  return database;
+}
 
-  it("installs a fail-closed compatibility trigger for the release that is still serving", () => {
-    const sql = legacyAccountIssuerTriggerSql();
-    expect(sql).toContain("BEFORE INSERT");
-    expect(sql).toContain('WHEN (NEW."issuer" IS NULL)');
-    expect(sql).toContain("NEW.\"accountId\" := NEW.\"userId\"");
-    expect(sql).toContain("RAISE EXCEPTION");
-    expect(sql).not.toContain("WHEN 'microsoft'");
+describe("Better Auth account identity cleanup", () => {
+  it("leaves an absent PostgreSQL table to the auth migrator", async (): Promise<void> => {
+    const client = new AccountClient(false);
+    expect(await migrate(client)).toBe("absent");
+    expect(client.statements.at(-1)).toBe("COMMIT");
+    expect(client.released).toBe(true);
   });
-
-  it("adds, backfills, validates, constrains, and indexes a legacy account table in one transaction", async () => {
-    const client = new LegacyAccountClient(["credential", "google", "github"]);
-
-    await expect(migrateLegacyAccountIssuers(database(client))).resolves.toBe("migrated");
-
-    const statements = client.statements.map(({ sql }) => sql.trim());
-    expect(statements[0]).toBe("BEGIN");
-    expect(statements.some((sql) => sql.includes('ADD COLUMN "issuer" text'))).toBe(true);
-    expect(
-      client.statements.some(
-        ({ sql, values }) => sql.includes('UPDATE "account"') && values?.[0] === "local:credential",
-      ),
-    ).toBe(true);
-    expect(
-      client.statements.some(
-        ({ sql, values }) => sql.includes('UPDATE "account"') && values?.[0] === "https://accounts.google.com",
-      ),
-    ).toBe(true);
-    expect(statements.some((sql) => sql.includes("CREATE TRIGGER podokit_fill_legacy_account_issuer"))).toBe(
-      true,
-    );
-    expect(statements.some((sql) => sql.includes('ALTER COLUMN "issuer" SET NOT NULL'))).toBe(true);
-    expect(statements.some((sql) => sql.includes('CREATE UNIQUE INDEX IF NOT EXISTS'))).toBe(true);
-    expect(statements.at(-1)).toBe("COMMIT");
+  it("relaxes legacy PostgreSQL constraints without rewriting account data", async (): Promise<void> => {
+    const client = new AccountClient();
+    expect(await migrate(client)).toBe("migrated");
+    expect(client.statements.some((sql) => sql.includes('ALTER COLUMN "issuer" DROP NOT NULL'))).toBe(true);
+    expect(client.statements.some((sql) => sql.startsWith("UPDATE") || sql.startsWith("DELETE"))).toBe(false);
+    expect(client.statements.at(-1)).toBe("COMMIT");
     expect(client.released).toBe(true);
   });
-
-  it("rolls back instead of guessing a Microsoft or unknown issuer", async () => {
-    const client = new LegacyAccountClient(["microsoft"]);
-
-    await expect(migrateLegacyAccountIssuers(database(client))).rejects.toThrow(
-      "Cannot infer a trusted Better Auth issuer for legacy provider microsoft",
-    );
-
-    expect(client.statements.map(({ sql }) => sql.trim())).toContain("ROLLBACK");
-    expect(client.statements.some(({ sql }) => sql.includes('SET NOT NULL'))).toBe(false);
+  it("does not add issuer to a current PostgreSQL schema", async (): Promise<void> => {
+    const client = new AccountClient(true, false);
+    expect(await migrate(client)).toBe("current");
+    expect(client.statements.some((sql) => sql.includes("ADD COLUMN") || sql.includes("ALTER COLUMN"))).toBe(false);
+  });
+  it("rolls back PostgreSQL identity collisions before changing constraints", async (): Promise<void> => {
+    const client = new AccountClient(true, true, 1);
+    await expect(migrate(client)).rejects.toThrow("duplicate providerId and accountId");
+    expect(client.statements.at(-1)).toBe("ROLLBACK");
+    expect(client.statements.some((sql) => sql.startsWith("ALTER") || sql.startsWith("DROP"))).toBe(false);
     expect(client.released).toBe(true);
   });
-
-  it("leaves a fresh database to the normal migrator and protects a current schema", async () => {
-    const absent = new LegacyAccountClient([], { tableExists: false });
-    const current = new LegacyAccountClient([], {
-      column: { dataType: "text", isNullable: "NO" },
-    });
-
-    await expect(migrateLegacyAccountIssuers(database(absent))).resolves.toBe("absent");
-    await expect(migrateLegacyAccountIssuers(database(current))).resolves.toBe("current");
-
-    expect(absent.statements.some(({ sql }) => sql.includes("CREATE TRIGGER"))).toBe(false);
-    expect(current.statements.some(({ sql }) => sql.includes("CREATE TRIGGER"))).toBe(true);
-    for (const client of [absent, current]) {
-      expect(client.statements.at(-1)?.sql.trim()).toBe("COMMIT");
-      expect(client.released).toBe(true);
-    }
+  it("leaves an absent SQLite table to the auth migrator", (): void => {
+    const database = new Database(":memory:");
+    try { expect(migrateSqliteLegacyAccountIssuers(database)).toBe("absent"); }
+    finally { database.close(); }
   });
-
-  it("rolls back before constraints when credentials mismatch or identity keys collide", async () => {
-    const mismatch = new LegacyAccountClient(["credential"], {
-      counts: { credentialMismatch: 1 },
-    });
-    const collision = new LegacyAccountClient(["google"], {
-      counts: { collision: 1 },
-    });
-
-    await expect(migrateLegacyAccountIssuers(database(mismatch))).rejects.toThrow(
-      "accountId differs from the linked userId",
-    );
-    await expect(migrateLegacyAccountIssuers(database(collision))).rejects.toThrow(
-      "collide on the new issuer and accountId identity key",
-    );
-
-    for (const client of [mismatch, collision]) {
-      expect(client.statements.map(({ sql }) => sql.trim())).toContain("ROLLBACK");
-      expect(client.statements.some(({ sql }) => sql.includes('SET NOT NULL'))).toBe(false);
-      expect(client.released).toBe(true);
-    }
+  it("preserves SQLite accounts, accepts new rows without issuer, and can rerun", (): void => {
+    const database = legacyDatabase();
+    try {
+      expect(migrateSqliteLegacyAccountIssuers(database)).toBe("migrated");
+      expect(database.query('SELECT "userId", password FROM account').get()).toEqual({ userId: "user", password: "password-hash" });
+      database.run('INSERT INTO account (id, "providerId", "accountId", "userId") VALUES (\'new\', \'github\', \'user\', \'user\')');
+      expect(migrateSqliteLegacyAccountIssuers(database)).toBe("current");
+      expect(database.query('SELECT count(*) AS count FROM account').get()).toEqual({ count: 2 });
+      expect(() => database.run('INSERT INTO account (id, "providerId", "accountId", "userId") VALUES (\'duplicate\', \'github\', \'user\', \'other\')')).toThrow();
+    } finally { database.close(); }
+  });
+  it("rolls back SQLite collisions without losing rows, issuer, or its index", (): void => {
+    const database = legacyDatabase();
+    try {
+      database.run('INSERT INTO account VALUES (\'collision\', \'credential\', \'user\', \'other\', \'other-hash\', \'other-issuer\')');
+      expect(() => migrateSqliteLegacyAccountIssuers(database)).toThrow("duplicate providerId and accountId");
+      expect(database.query('SELECT count(*) AS count FROM account').get()).toEqual({ count: 2 });
+      expect(database.query('SELECT issuer FROM account WHERE id = \'account\'').get()).toEqual({ issuer: "local:credential" });
+      expect(database.query('SELECT name FROM sqlite_master WHERE name = \'account_issuer_accountId_uidx\'').get()).toBeTruthy();
+    } finally { database.close(); }
   });
 });

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/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];

package/dist/templates/todo/tests/api/todo.api.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "@playwright/test";
+
+test("Todo CRUD preserves UUIDs, booleans, and timestamps @smoke", async ({ request, baseURL }): Promise<void> => {
+  const title = `Todo API ${crypto.randomUUID()}`;
+  const headers = { Origin: baseURL ?? "http://localhost:5001" };
+  const response = await request.post("/api/todos", { data: { title }, headers });
+  expect(response.status()).toBe(201);
+  const created: unknown = await response.json();
+  expect(created).toMatchObject({ title, completed: false, id: expect.any(String), createdAt: expect.any(String) });
+  if (typeof created !== "object" || created === null || !("id" in created) || typeof created.id !== "string"
+    || !("createdAt" in created) || typeof created.createdAt !== "string") {
+    throw new Error("Todo response must include an ID and timestamp");
+  }
+  const id = created.id;
+  try {
+    expect(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(new Date(created.createdAt).toISOString()).toBe(created.createdAt);
+    const list = await request.get("/api/todos");
+    expect(list.status()).toBe(200);
+    expect(await list.json()).toEqual(expect.arrayContaining([created]));
+
+    const update = await request.patch(`/api/todos/${id}`, { data: { title: `${title} updated`, completed: true }, headers });
+    expect(update.status()).toBe(200);
+    expect(await update.json()).toEqual({ ...created, title: `${title} updated`, completed: true });
+    expect((await request.delete(`/api/todos/${id}`, { headers })).status()).toBe(204);
+    expect((await request.get(`/api/todos/${id}`)).status()).toBe(404);
+    expect((await request.patch(`/api/todos/${id}`, { data: { completed: false }, headers })).status()).toBe(404);
+    expect((await request.delete(`/api/todos/${id}`, { headers })).status()).toBe(404);
+  } finally {
+    await request.delete(`/api/todos/${id}`, { headers });
+  }
+});

package/dist/templates/todo/tests/ui/todo.ui.spec.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "@playwright/test";
+
+test("Todo items persist through create, complete, reload, and delete @smoke", async ({ page, request, baseURL }): Promise<void> => {
+  const title = `Todo UI ${crypto.randomUUID()}`;
+  try {
+    await page.goto("/");
+    await page.getByPlaceholder("Add a todo…").fill(title);
+    await page.getByRole("button", { name: "Add", exact: true }).click();
+    const row = page.getByRole("listitem").filter({ hasText: title });
+    await expect(row).toBeVisible();
+    await expect(row.getByRole("checkbox")).not.toBeChecked();
+    await row.getByRole("checkbox").check();
+    await expect(row.getByRole("checkbox")).toBeChecked();
+    await page.reload();
+    await expect(row.getByRole("checkbox")).toBeChecked();
+    await row.getByRole("button", { name: "Delete", exact: true }).click();
+    await expect(row).toHaveCount(0);
+    await page.reload();
+    await expect(row).toHaveCount(0);
+  } finally {
+    const items: unknown = await (await request.get("/api/todos")).json();
+    if (Array.isArray(items)) {
+      for (const item of items as unknown[]) {
+        if (typeof item === "object" && item !== null && "title" in item && item.title === title
+          && "id" in item && typeof item.id === "string") {
+          await request.delete(`/api/todos/${item.id}`, { headers: { Origin: baseURL ?? "http://localhost:5001" } });
+        }
+      }
+    }
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {