flint-orm 0.7.0 → 0.7.1

package/skills/driver-selection/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: driver-selection
+description: >
+  Choose the right driver for your environment: local file, in-memory,
+  serverless, or remote. Covers bun:sqlite, better-sqlite3, @libsql/client,
+  @libsql/client/web, @tursodatabase/database, @tursodatabase/sync. Load
+  when deciding which driver to use or when troubleshooting driver-specific
+  issues.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/entries/bun-sqlite.ts'
+  - 'kavenlabs/flint-orm:src/entries/better-sqlite3.ts'
+  - 'kavenlabs/flint-orm:src/entries/libsql.ts'
+  - 'kavenlabs/flint-orm:src/entries/libsql-web.ts'
+  - 'kavenlabs/flint-orm:src/entries/turso.ts'
+  - 'kavenlabs/flint-orm:src/entries/turso-sync.ts'
+---
+
+# flint-orm — Driver Selection
+
+## Setup
+
+```ts
+// bun:sqlite — Bun runtime only, local file
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: './app.db' });
+
+// better-sqlite3 — Node.js, local file
+import { flint } from 'flint-orm/better-sqlite3';
+const db = flint({ url: './app.db' });
+
+// libsql — local file or remote (Turso)
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+
+// libsql-web — serverless/edge, remote only (no native binary)
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+
+// turso — Turso database
+import { flint } from 'flint-orm/turso';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+
+// turso-sync — Turso with sync support
+import { flint } from 'flint-orm/turso-sync';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+```
+
+## Core Patterns
+
+### Local file database
+
+Use bun:sqlite (Bun) or better-sqlite3 (Node.js) for local SQLite files:
+
+```ts
+// Bun runtime
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: './app.db' });
+
+// Node.js
+import { flint } from 'flint-orm/better-sqlite3';
+const db = flint({ url: './app.db' });
+```
+
+### Remote database (Turso)
+
+Use libsql or turso for remote Turso databases:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+### Serverless/edge environment
+
+Use libsql-web for serverless or edge runtimes (no native binary):
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+### In-memory database
+
+All drivers support in-memory databases via `:memory:`:
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: ':memory:' });
+```
+
+## Driver Comparison
+
+| Driver | Runtime | File URLs | Remote URLs | Serverless | Auth Token |
+|--------|---------|-----------|-------------|------------|------------|
+| bun:sqlite | Bun only | ✅ | ❌ | ❌ | ❌ |
+| better-sqlite3 | Node.js | ✅ | ❌ | ❌ | ❌ |
+| libsql | Bun/Node | ✅ | ✅ | ✅ | ✅ |
+| libsql-web | Any | ❌ | ✅ | ✅ | ✅ |
+| turso | Bun/Node | ✅ | ✅ | ✅ | ✅ |
+| turso-sync | Bun/Node | ✅ | ✅ | ✅ | ✅ |
+
+## Common Mistakes
+
+### HIGH libsql requires file: prefix for local paths
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'app.db' }); // ERROR: URL_INVALID
+```
+
+Correct:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'file:./app.db' });
+```
+
+Unlike bun:sqlite and better-sqlite3, the libsql driver requires the `file:` prefix for local file paths.
+
+Source: maintainer interview
+
+### HIGH Using libsql-web with file: URLs
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({ url: 'file:./app.db' }); // ERROR
+```
+
+Correct:
+
+```ts
+// For local files, use libsql or bun-sqlite
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'file:./app.db' });
+```
+
+libsql-web only supports HTTP/WebSocket URLs — it has no native binary and cannot access local files.
+
+Source: src/entries/libsql-web.ts
+
+### HIGH Missing authToken for remote databases
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'libsql://my-db.turso.io' }); // Missing authToken
+```
+
+Correct:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({
+  url: 'libsql://my-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+Remote Turso/libsql databases require authentication.
+
+Source: maintainer interview
+
+## References
+
+- [Full driver comparison](references/driver-comparison.md)

package/skills/driver-selection/references/driver-comparison.md

@@ -0,0 +1,141 @@
+# Driver Comparison Reference
+
+Detailed comparison of all flint-orm drivers.
+
+## bun:sqlite
+
+**Runtime:** Bun only
+**Type:** Sync (Promise-wrapped for uniform API)
+**Install:** Built into Bun — no separate install needed
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: './app.db' });
+```
+
+**Options:**
+- `url: string` — Path to SQLite file or `:memory:`
+
+**Limitations:**
+- Only works in Bun runtime
+- No remote database support
+- No authentication support
+
+## better-sqlite3
+
+**Runtime:** Node.js
+**Type:** Sync (Promise-wrapped for uniform API)
+**Install:** `npm install better-sqlite3`
+
+```ts
+import { flint } from 'flint-orm/better-sqlite3';
+const db = flint({ url: './app.db' });
+```
+
+**Options:**
+- `url: string` — Path to SQLite file or `:memory:`
+
+**Limitations:**
+- No remote database support
+- No authentication support
+
+## @libsql/client
+
+**Runtime:** Bun/Node.js
+**Type:** Async
+**Install:** `npm install @libsql/client`
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+**Options:**
+- `url: string` — Local file (`file:./app.db`), remote (`libsql://...`), or in-memory (`:memory:`)
+- `authToken: string` — Required for remote databases
+
+**Capabilities:**
+- Local file access
+- Remote database access
+- Serverless compatible
+- Authentication support
+
+## @libsql/client/web
+
+**Runtime:** Any (browser, edge, serverless)
+**Type:** Async
+**Install:** `npm install @libsql/client`
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+**Options:**
+- `url: string` — Remote only (`ws://`, `wss://`, `http://`, `https://`)
+- `authToken: string` — Required for remote databases
+
+**Capabilities:**
+- No native binary — works in any JavaScript runtime
+- Serverless/edge optimized
+- Authentication support
+
+**Limitations:**
+- No local file access (`file:` URLs not supported)
+- No in-memory database support
+
+## @tursodatabase/database
+
+**Runtime:** Bun/Node.js
+**Type:** Async
+**Install:** `npm install @tursodatabase/database`
+
+```ts
+import { flint } from 'flint-orm/turso';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+**Options:**
+- `url: string` — Local file or remote Turso database
+- `authToken: string` — Required for remote databases
+
+## @tursodatabase/sync
+
+**Runtime:** Bun/Node.js
+**Type:** Async
+**Install:** `npm install @tursodatabase/sync`
+
+```ts
+import { flint } from 'flint-orm/turso-sync';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+**Options:**
+- `url: string` — Local file or remote Turso database
+- `authToken: string` — Required for remote databases
+
+**Capabilities:**
+- Includes sync support for offline-first applications
+
+## Decision Guide
+
+| Use Case | Recommended Driver |
+|----------|-------------------|
+| Bun runtime, local file | bun:sqlite |
+| Node.js, local file | better-sqlite3 |
+| Remote Turso database | libsql |
+| Serverless/edge | libsql-web |
+| Turso with sync | turso-sync |
+| Testing/prototyping | Any with `:memory:` |

package/skills/run-migrations/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: run-migrations
+description: >
+  Generate and apply schema migrations safely using the CLI or programmatic
+  API. Covers flint generate, flint migrate, flint.config.ts, and the
+  migration pipeline (serialize → diff → generateSQL). Load when creating
+  or applying migrations, or when troubleshooting migration issues.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/migration/generate.ts'
+  - 'kavenlabs/flint-orm:src/migration/migrate.ts'
+  - 'kavenlabs/flint-orm:src/migration/sql.ts'
+  - 'kavenlabs/flint-orm:src/cli.ts'
+  - 'kavenlabs/flint-orm:README.md'
+  - 'kavenlabs/flint-orm:API.md'
+---
+
+# flint-orm — Migrations
+
+## Setup
+
+### flint.config.ts
+
+```ts
+import { defineConfig } from 'flint-orm/config';
+
+export default defineConfig({
+  driver: 'bun-sqlite', // Must match the driver you import in your app
+  database: {
+    url: './app.db',
+  },
+  schema: './src/schema',
+  migrations: './flint',
+});
+```
+
+### CLI commands
+
+```bash
+# Generate a migration from schema changes
+flint generate
+flint generate --name add_users_table
+flint generate --preview  # Show SQL without writing
+
+# Apply pending migrations
+flint migrate
+flint migrate --dry-run  # Show what would run
+flint migrate --status   # Show applied vs pending
+```
+
+## Core Patterns
+
+### Generate initial migration
+
+After defining your schema, generate the first migration:
+
+```bash
+flint generate --name init_schema
+```
+
+This creates a folder in `./flint/` with:
+- `migration.ts` — The operations to apply
+- `state.json` — Snapshot of the schema
+
+### Apply migrations
+
+```bash
+flint migrate
+```
+
+This:
+1. Reads pending migrations from the migrations directory
+2. Applies them in order within transactions
+3. Records applied migrations in `__flint_migrations` table
+
+### Preview before applying
+
+Always preview before applying in production:
+
+```bash
+flint generate --preview  # Review the SQL
+flint migrate --dry-run   # Verify what would run
+flint migrate             # Apply with confidence
+```
+
+### Programmatic API
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+import { generate, migrate, getMigrationStatus } from 'flint-orm/migration';
+
+const db = flint({ url: './app.db' });
+
+// Generate a migration
+await generate([users, posts], './flint', {
+  name: 'add_posts',
+  interactive: true,
+});
+
+// Apply pending migrations
+const result = await migrate(db.$executor, { migrationsDir: './flint' });
+console.log(`Applied: ${result.applied.join(', ')}`);
+
+// Check status
+const status = await getMigrationStatus(db.$executor, './flint');
+console.log(`Pending: ${status.pending.length}`);
+```
+
+## How It Works
+
+1. `flint generate` serializes your `table()` definitions to JSON
+2. Diffs against the last migration's `state.json`
+3. Detects adds, drops, renames, and safe modifications
+4. Prompts to confirm potential renames (interactive mode)
+5. Writes a migration folder with `migration.ts` + `state.json`
+6. `flint migrate` reads pending migrations and executes them in order
+
+## Common Mistakes
+
+### HIGH Running migrate without generate first
+
+Wrong:
+
+```ts
+// Modifying schema, then:
+flint migrate // No migration files exist yet!
+```
+
+Correct:
+
+```ts
+// After schema changes:
+flint generate --name add_users_table
+flint migrate
+```
+
+`migrate` applies existing migration files — you must generate them first from schema changes.
+
+Source: README.md
+
+### HIGH Not using --preview or --dry-run before applying
+
+Wrong:
+
+```ts
+flint generate
+flint migrate // Applies without preview
+```
+
+Correct:
+
+```ts
+flint generate --preview // Review the SQL
+flint migrate --dry-run // Verify what would run
+flint migrate // Apply with confidence
+```
+
+Migrations can be destructive (dropping columns, rebuilding tables). Always preview first.
+
+Source: README.md

package/skills/setup-client/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: setup-client
+description: >
+  Install flint-orm, choose a driver, and connect to a database. Covers
+  flint() factory, driver entry points (bun-sqlite, better-sqlite3, libsql,
+  libsql-web, turso, turso-sync), and flint.config.ts configuration. Load
+  when setting up a new project or switching drivers.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/entries/bun-sqlite.ts'
+  - 'kavenlabs/flint-orm:src/entries/libsql.ts'
+  - 'kavenlabs/flint-orm:src/entries/libsql-web.ts'
+  - 'kavenlabs/flint-orm:src/entries/better-sqlite3.ts'
+  - 'kavenlabs/flint-orm:README.md'
+---
+
+# flint-orm — Client Setup
+
+flint-orm is a type-safe, driver-agnostic SQLite ORM for JavaScript. One schema, any driver.
+
+## Setup
+
+### Install with a driver
+
+```bash
+# Choose ONE driver (bun:sqlite is built into Bun, no install needed):
+bun add flint-orm                    # bun:sqlite (sync, Promise-wrapped) — Bun only
+bun add flint-orm better-sqlite3    # better-sqlite3 (sync, Promise-wrapped)
+bun add flint-orm @libsql/client    # libsql (async, local or remote)
+bun add flint-orm @libsql/client    # libsql-web (async, serverless, no file: support)
+bun add flint-orm @tursodatabase/database  # turso (async)
+bun add flint-orm @tursodatabase/sync      # turso-sync (async, authToken)
+```
+
+### Initialize the client
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+
+const db = flint({ url: './app.db' });
+```
+
+### Create flint.config.ts
+
+```ts
+import { defineConfig } from 'flint-orm/config';
+
+export default defineConfig({
+  driver: 'bun-sqlite', // Must match the driver you import in your app
+  database: {
+    url: './app.db',
+  },
+  schema: './src/schema',
+  migrations: './flint',
+});
+```
+
+## Core Patterns
+
+### Connect to a local file
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+
+const db = flint({ url: './app.db' });
+```
+
+### Connect to a remote database
+
+```ts
+import { flint } from 'flint-orm/libsql';
+
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+### Connect in a serverless environment
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+
+// libsql-web only supports ws://, wss://, http://, https:// URLs
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+## Common Mistakes
+
+### CRITICAL Driver mismatch between config and app
+
+Wrong:
+
+```ts
+// flint.config.ts
+export default defineConfig({ driver: 'bun-sqlite', ... });
+
+// app.ts
+import { flint } from 'flint-orm/libsql'; // MISMATCH
+const db = flint({ url: '...' });
+```
+
+Correct:
+
+```ts
+// flint.config.ts
+export default defineConfig({ driver: 'libsql', ... });
+
+// app.ts
+import { flint } from 'flint-orm/libsql'; // MATCHES
+const db = flint({ url: '...' });
+```
+
+The CLI uses flint.config.ts to determine which driver to use for migrations, but the app uses whichever driver you import — these must match.
+
+Source: maintainer interview
+
+### HIGH Using libsql-web for local file databases
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({ url: './app.db' }); // ERROR: file: not supported
+```
+
+Correct:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: './app.db' });
+```
+
+libsql-web only supports ws:, wss:, http:, https: URLs — it has no native binary and cannot access local files. Use the regular libsql driver for local files.
+
+Source: src/entries/libsql-web.ts