flint-orm 0.6.0 → 0.7.1

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

package/skills/update-schema/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: update-schema
+description: >
+  Add columns and tables without data loss. Covers safe vs unsafe migrations,
+  rebuildTable operation, additive migration patterns, and which changes
+  trigger table rebuilds. Load when modifying schema after initial migration
+  or when planning schema evolution.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/migration/diff.ts'
+  - 'kavenlabs/flint-orm:src/migration/sql.ts'
+  - 'kavenlabs/flint-orm:src/migration/migrate.ts'
+  - 'kavenlabs/flint-orm:README.md'
+---
+
+# flint-orm — Schema Updates
+
+## Setup
+
+After defining your initial schema, you'll need to evolve it over time. flint-orm detects changes and generates appropriate migrations.
+
+## Core Patterns
+
+### Safe migration: Adding a column with default
+
+```ts
+// Add a new column with a default value — safe, no data loss
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull().default('active'), // NEW: safe to add
+});
+```
+
+### Safe migration: Adding a new table
+
+```ts
+// Add a new table — always safe
+const posts = snakeCase.table('posts', {
+  id: integer().autoIncrement().primaryKey(),
+  userId: integer().notNull().references(users.id),
+  title: text().notNull(),
+});
+```
+
+### Unsafe migration: Changing column type
+
+```ts
+// Changing a column type triggers a table rebuild
+// The old column was: age: text('age')
+// The new column is:  age: integer('age')
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  age: integer('age').notNull().default(0), // TYPE CHANGE: triggers rebuild
+});
+```
+
+### Unsafe migration: Adding NOT NULL without default
+
+```ts
+// Adding NOT NULL without a default triggers a table rebuild
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull(), // NO DEFAULT: triggers rebuild
+});
+```
+
+## Migration Safety Reference
+
+### Safe changes (no rebuild)
+
+| Change | Example |
+|--------|---------|
+| Add column with default | `status: text().default('active')` |
+| Add new table | `snakeCase.table('new_table', {...})` |
+| Add index | `index('idx_name').on(t.name)` |
+| Drop index | Remove from index callback |
+| Change default value | `status: text().default('inactive')` |
+
+### Unsafe changes (triggers rebuild)
+
+| Change | Example |
+|--------|---------|
+| Change column type | `text()` → `integer()` |
+| Add NOT NULL without default | `text().notNull()` (no `.default()`) |
+| Remove NOT NULL | `text().notNull()` → `text()` |
+| Add/remove UNIQUE | `text().unique()` → `text()` |
+| Remove default | `text().default('x')` → `text()` |
+| Add/change/remove foreign key | `.references(col)` changes |
+| Change FK actions | `.onDelete('cascade')` changes |
+| Change autoincrement | `.autoIncrement()` changes |
+
+### What is rebuildTable?
+
+When an unsafe change is detected, flint-orm generates a `rebuildTable` operation that:
+
+1. Creates a temporary table with the new schema
+2. Copies data from the old table
+3. Drops the old table
+4. Renames the temporary table to the original name
+5. Recreates indexes
+
+This happens within a transaction — if anything fails, the original table is preserved.
+
+## Common Mistakes
+
+### HIGH Adding NOT NULL column without a default
+
+Wrong:
+
+```ts
+// After initial migration, adding:
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull(), // No default — triggers rebuild
+});
+```
+
+Correct:
+
+```ts
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull().default('active'), // Safe: has default
+});
+```
+
+SQLite cannot add NOT NULL columns to existing tables without a default — this triggers a table rebuild.
+
+Source: src/migration/diff.ts
+
+### HIGH Changing a column type
+
+Wrong:
+
+```ts
+// Changing after initial migration:
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  age: integer('age'), // Was: age: text('age')
+});
+```
+
+Correct:
+
+```ts
+// Plan for the type from the start, or accept the rebuild
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  age: integer('age').notNull().default(0), // Correct type from start
+});
+```
+
+SQLite has no `ALTER COLUMN TYPE` — this always triggers a table rebuild.
+
+Source: src/migration/diff.ts
+
+### HIGH Dropping a column referenced by foreign keys
+
+Wrong:
+
+```ts
+// Dropping users.id when orders.userId references it
+// Migration fails with: Cannot rebuild "users" — referenced by: orders
+```
+
+Correct:
+
+```bash
+# Migrate dependent tables first, then rebuild the parent
+flint migrate # Apply orders migration first
+flint generate # Then rebuild users
+```
+
+The migration runner checks for incoming foreign keys before rebuild — it will refuse if other tables reference the table being rebuilt.
+
+Source: src/migration/migrate.ts