first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/plugins/library-navigator/skills/sp-db-sqlite/SKILL.md
+++ b/plugins/library-navigator/skills/sp-db-sqlite/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: sp-db-sqlite
+description: Universal SQLite adapter for Bun (bun:sqlite) and browser (@sqlite.org/sqlite-wasm) with Drizzle ORM, LRU prepared-statement cache, and forward-only migrations
+---
+
+# sp-db-sqlite
+
+## Architecture
+
+| Class / Function | Responsibility |
+|---|---|
+| `SqliteAdapter` | Main `DatabaseAdapter` implementation backed by `bun:sqlite` on Bun and `@sqlite.org/sqlite-wasm` in the browser. |
+| `createSqliteAdapter` | Factory that selects the correct runtime adapter (Bun vs browser WASM). |
+| `createBunDriver` | Server-side driver binding for `bun:sqlite`. |
+| `createWasmDriver` | Browser-side driver spawning a Web Worker with `@sqlite.org/sqlite-wasm`. |
+| `PreparedStatementCache` | LRU cache (default 128 entries) for prepared statements reused across `query()` calls. |
+| `MigrationRunner` | Forward-only ledger-tracked migration runner with dry-run support. |
+| `SqliteError` + `SQLITE_CODES` | Structured error registry (`ENVIRONMENT_ERROR`, `QUERY_FAILED`, `TRANSACTION_FAILED`, etc.). |
+| `withQuerySpan` | OTel tracing wrapper for SQLite operations. |
+
+## File Structure
+
+```
+persistence/database/db-sqlite/src/
+  adapter/          — SqliteAdapter, createSqliteAdapter, adapter.bun, adapter.wasm
+  cache/            — PreparedStatementCache (LRU)
+  conformance/      — DatabaseAdapter conformance suite
+  connection/       — Connection helpers and singleton management
+  drivers/
+    bun-driver/     — createBunDriver
+    wasm-driver/    — createWasmDriver
+    wasm-worker/    — Web Worker host for WASM driver
+  errors/           — SqliteError + SQLITE_CODES
+  migration/        — MigrationRunner
+  otel/             — OTel spans and metrics
+  schemas/          — Zod-validated config types
+  unsafe/           — ./unsafe subpath for raw queries
+```
+
+## Sibling packages
+
+- `sp-db` — universal database adapter interface this package implements
+- `sp-migration` — migration tooling
+- `sp-seed` — database seeding
+- `sp-surrealdb` — SurrealDB adapter
+
+## Patterns
+
+### Quick Start — Bun runtime
+
+```ts
+import { createSqliteAdapter } from "@suaveplan/db-sqlite/adapter";
+
+const db = await createSqliteAdapter({ url: ":memory:" });
+
+await db.exec(`
+    CREATE TABLE users (id TEXT PRIMARY KEY, email TEXT NOT NULL);
+`);
+
+await db.run("INSERT INTO users (id, email) VALUES (?, ?)", ["user-123", "alice@example.com"]);
+
+const rows = await db.all<{ id: string; email: string }>(
+    "SELECT id, email FROM users WHERE id = ?",
+    ["user-123"],
+);
+
+await db.close();
+```
+
+### Singleton via @suaveplan/db
+
+```ts
+import { getSingleton } from "@suaveplan/db";
+import { SqliteAdapter } from "@suaveplan/db-sqlite";
+
+const db = await getSingleton("app", () => new SqliteAdapter({ filename: "./app.db" }));
+```
+
+### Transactional operations
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.execute("INSERT INTO accounts VALUES (?, ?)", [1, "Alice"]);
+  await tx.execute("INSERT INTO accounts VALUES (?, ?)", [2, "Bob"]);
+});
+```
+
+### Migrations
+
+```ts
+const result = await db.migrate({ migrationsFolder: "./db/migrations" });
+console.log(`Applied ${result.applied} migration(s)`);
+```
+
+## Constraints
+
+- Bun runtime uses `bun:sqlite`; browser runtime uses `@sqlite.org/sqlite-wasm` via Web Worker.
+- `./adapter` conditional export resolves to `adapter.bun.ts` on Bun and `adapter.wasm.ts` in browsers.
+- `SqliteAdapter` throws `SqliteError(SQLITE.ENVIRONMENT_ERROR)` when constructed outside Bun (unless using browser conditional export).
+- `connect()` is idempotent — concurrent callers share one in-flight promise.
+- `transaction()` uses `BEGIN IMMEDIATE` to prevent deadlocks on concurrent writes; auto-rollback on failure.
+- `migrate()` invalidates the prepared-statement cache on success.
+- `./unsafe` subpath exposes raw query surface without ORM wrapping.
+- 100% statement + branch + function + line coverage required.
+
+## Checklist
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/db-sqlite` passes
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/db-sqlite` reports 100%
+- [ ] `bun run docs:check --filter=@suaveplan/db-sqlite` passes
+- [ ] Every `src/**/*.md` has a sibling `.ts` module with matching exports
+- [ ] Conditional export `./adapter` resolves correctly on both Bun and browser bundles