turbine-orm 0.19.1 → 0.21.0

package/README.md

@@ -1,6 +1,6 @@
 # turbine-orm
 
-One dependency. No WASM engine. The Postgres ORM that ships light and locks tight.
+The Postgres ORM your DBA will sign off on. A read-only Studio that can't touch prod, errors that never leak PII, one dependency, and checksummed migrations.
 
 ```
 npm install turbine-orm
@@ -10,16 +10,16 @@ npm install turbine-orm
 
 ## Why Turbine?
 
-Prisma ships a 1.6 MB WASM query engine. Drizzle ships zero runtime but no Studio, no typed errors, no migration checksums. Turbine ships **one dependency (`pg`) and no engine binary**, and bundles six things no other TS ORM has together:
+Every TS ORM now resolves nested relations in a single `json_agg` query — Prisma 7 and Drizzle v2 both ship it, and so does Turbine. That part is table stakes. The reason to reach for Turbine is the **safety bundle**: the boxes a DBA ticks before a query layer goes anywhere near production. It's the only TypeScript ORM that ships all six of these together:
 
-1. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~30 KB gzipped (~109 KB minified); the edge entry to ~21 KB gzipped. Prisma's WASM query engine alone is 1.6 MB.
-2. **Built-in read-only Studio.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and — since v0.19 — no raw-SQL surface at all: queries are composed in the ORM's own validated builder. The only TS ORM Studio that physically cannot mutate your database. DBA-approvable.
-3. **PII-safe error messages.** Turbine errors show WHERE keys, not values. A `UniqueConstraintError` says which column violated the constraint — never the actual user data. Safe to log, safe to surface to monitoring, no scrubbing needed.
+1. **Read-only Studio your DBA will approve.** `npx turbine studio` spins up a loopback-bound web UI with 192-bit auth tokens, `BEGIN READ ONLY` transactions, and — since v0.19 — no raw-SQL surface at all: queries are composed in the ORM's own validated builder. The only TS ORM Studio that physically cannot mutate your database.
+2. **PII-safe error messages.** Turbine errors show WHERE keys, not values. A `UniqueConstraintError` says which column violated the constraint — never the actual user data. Safe to log, safe to surface to monitoring, no scrubbing needed.
+3. **One runtime dependency (`pg`).** No engine binary, no WASM adapter, no adapter packages to keep in lockstep. The main entry bundles to ~31 kB brotli (~109 KB minified); the edge entry to ~22 kB brotli. Prisma's WASM query engine alone is 1.6 MB.
 4. **SQL-first migrations with drift detection.** Write real SQL. SHA-256 checksums catch modified migration files. `pg_try_advisory_lock()` prevents concurrent runs. Each migration in its own transaction. No shadow database, no magic DSL.
-5. **Edge-native — one import swap.** `turbineHttp(pool, schema)` — same API on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No WASM bundle, no adapter package, no separate serverless build.
+5. **Edge-native — one import swap.** `turbineHttp(pool, SCHEMA)` — same API on Neon, Vercel Postgres, Cloudflare Hyperdrive, Supabase. No WASM bundle, no adapter package, no separate serverless build.
 6. **Pipeline batching via wire protocol.** Real Parse/Bind/Execute pipeline — not queries wrapped in a transaction. N independent queries in one round-trip.
 
-Every ORM claims single-query nested loads now (Prisma 7 and Drizzle v2 both use json_agg). Turbine does too — see [How It Works](#how-it-works). The differentiator isn't the query strategy; it's the one-dependency, no-WASM footprint, the read-only Studio, and the error messages that never leak user data.
+See [How It Works](#how-it-works) for the `json_agg` query strategy itself — but the query strategy isn't why you'd pick Turbine. The safety bundle above is: a Studio that can't mutate prod, errors that never leak PII, one dependency, and checksummed migrations.
 
 ## Benchmarks
 
@@ -343,6 +343,8 @@ const db = turbine({
 
 ### Middleware
 
+Middleware wraps every query. It runs **after SQL generation**, so it can observe what's about to execute (`params.model`, `params.action`, `params.args`), measure timing, and transform the result returned by `next()` — but it cannot change the query itself.
+
 ```typescript
 // Query timing
 db.$use(async (params, next) => {
@@ -352,15 +354,33 @@ db.$use(async (params, next) => {
   return result;
 });
 
-// Soft-delete filter
+// Result transformation — redact a field on the way out
 db.$use(async (params, next) => {
-  if (params.action === 'findMany' || params.action === 'findUnique') {
-    params.args.where = { ...params.args.where, deletedAt: null };
+  const result = await next(params);
+  if (params.model === 'users' && Array.isArray(result)) {
+    for (const row of result as { email?: string }[]) row.email = '[redacted]';
   }
-  return next(params);
+  return result;
 });
 ```
 
+> **Warning:** `params.args` is a read-only snapshot — mutating it does not change the executed SQL. The query is fully built and parameterized before middleware runs.
+
+Because middleware can't rewrite queries, cross-cutting filters like **soft deletes** belong in the query itself — either explicitly or via a small scoped helper:
+
+```typescript
+import type { WhereClause } from 'turbine-orm';
+
+// Explicit filter
+const users = await db.users.findMany({ where: { deletedAt: null } });
+
+// Scoped helper that always applies the filter
+const activeUsers = (where: WhereClause<User> = {}) =>
+  db.users.findMany({ where: { ...where, deletedAt: null } });
+
+const rows = await activeUsers({ orgId: 1 });
+```
+
 ### Error handling
 
 Turbine throws typed errors you can catch programmatically:
@@ -384,7 +404,7 @@ try {
 }
 ```
 
-Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation), `TURBINE_E008` (UniqueConstraint), `TURBINE_E009` (ForeignKey), `TURBINE_E010` (NotNullViolation), `TURBINE_E011` (CheckConstraint), `TURBINE_E012` (Deadlock), `TURBINE_E013` (SerializationFailure), `TURBINE_E014` (Pipeline), `TURBINE_E015` (OptimisticLock), `TURBINE_E016` (ExclusionConstraint).
+Error codes: `TURBINE_E001` (NotFound), `TURBINE_E002` (Timeout), `TURBINE_E003` (Validation), `TURBINE_E004` (Connection), `TURBINE_E005` (Relation), `TURBINE_E006` (Migration), `TURBINE_E007` (CircularRelation), `TURBINE_E008` (UniqueConstraint), `TURBINE_E009` (ForeignKey), `TURBINE_E010` (NotNullViolation), `TURBINE_E011` (CheckConstraint), `TURBINE_E012` (Deadlock), `TURBINE_E013` (SerializationFailure), `TURBINE_E014` (Pipeline), `TURBINE_E015` (OptimisticLock), `TURBINE_E016` (ExclusionConstraint), `TURBINE_E017` (UnsupportedFeature — a Postgres-only feature invoked on another engine).
 
 Full reference with `wrapPgError()` translation, retry patterns for `DeadlockError` / `SerializationFailureError`, and safe vs verbose message modes: **[turbineorm.dev/errors](https://turbineorm.dev/errors)**.
 
@@ -557,6 +577,7 @@ Commands:
   seed                         Run seed file
   status                       Show database schema summary
   studio                       Launch local read-only Studio web UI
+  observe                      Launch local metrics dashboard (requires TURBINE_OBSERVE_URL)
 
 Options:
   --url, -u <url>       Postgres connection string
@@ -638,6 +659,42 @@ npx turbine studio --port 5173 --host 127.0.0.1 --no-open
 - **Every query runs inside `BEGIN READ ONLY`** with a 30s transaction-local statement timeout (parameterized `set_config`). Writes are physically impossible at the transaction level.
 - **Security headers on every response** — CSP, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` — plus per-session rate limiting and cross-origin refusal.
 
+## Observability
+
+Built-in query metrics with zero new dependencies. `$observe` buffers per-query timings in memory and flushes **per-minute aggregates** — count, avg, p50, p95, p99, and error count per `model:action` — to a `_turbine_metrics` table in a **separate database**, over its own 1-connection pool so metrics writes never contend with your application pool.
+
+```typescript
+const handle = await db.$observe({
+  connectionString: process.env.TURBINE_OBSERVE_URL!, // metrics DB (not your app DB)
+  flushIntervalMs: 60_000, // default: 60s
+  retentionDays: 30,       // default: 30 — older buckets are pruned on flush
+});
+
+// Later, to flush remaining metrics and close the metrics pool
+await handle.stop();
+```
+
+`$observe` creates the `_turbine_metrics` table if it doesn't exist. Flushes are fire-and-forget (`INSERT ... ON CONFLICT` additive merge) and never throw into your application. If the `TURBINE_OBSERVE_URL` environment variable is set, the client starts observing automatically on construction — no code needed.
+
+For your own instrumentation, subscribe to query events with `$on('query')` — each event carries `sql`, `params`, `duration` (ms), `model`, `action`, `rows`, `timestamp`, and `error` (if the query failed):
+
+```typescript
+db.$on('query', (e) => {
+  if (e.duration > 200) {
+    console.warn(`slow query: ${e.model}.${e.action} (${e.duration.toFixed(1)}ms, ${e.rows} rows)`);
+  }
+});
+```
+
+View the collected metrics in a local dashboard:
+
+```bash
+TURBINE_OBSERVE_URL=postgres://... npx turbine observe
+# Flags: --port (default 4984), --host (default 127.0.0.1), --no-open
+```
+
+Same security model as Studio: loopback binding by default, per-process random auth token in an `HttpOnly` cookie, CSP headers, and read-only access to the metrics table.
+
 ## Serverless / Edge
 
 Turbine's core is driver-agnostic: pass any pg-compatible pool to `TurbineConfig.pool` (or use the `turbineHttp()` factory) and Turbine runs on **Vercel Edge**, **Cloudflare Workers**, **Deno Deploy**, **Netlify Edge**, or any other environment where a direct TCP connection is unavailable. No new dependencies — install whichever driver you already use.
@@ -648,12 +705,12 @@ Turbine's core is driver-agnostic: pass any pg-compatible pool to `TurbineConfig
 // app/api/users/route.ts
 import { Pool } from '@neondatabase/serverless';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { schema } from '@/generated/turbine/metadata';
+import { SCHEMA } from '@/generated/turbine/metadata';
 
 export const runtime = 'edge';
 
 const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-const db = turbineHttp(pool, schema);
+const db = turbineHttp(pool, SCHEMA);
 
 export async function GET() {
   const users = await db.table('users').findMany({
@@ -669,22 +726,22 @@ export async function GET() {
 ```ts
 import { createPool } from '@vercel/postgres';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { schema } from './generated/turbine/metadata.js';
+import { SCHEMA } from './generated/turbine/metadata.js';
 
 const pool = createPool({ connectionString: process.env.POSTGRES_URL });
-const db = turbineHttp(pool, schema);
+const db = turbineHttp(pool, SCHEMA);
 ```
 
 ### Supabase (direct Postgres — no HTTP proxy needed)
 
 ```ts
 import { TurbineClient } from 'turbine-orm';
-import { schema } from './generated/turbine/metadata.js';
+import { SCHEMA } from './generated/turbine/metadata.js';
 
 const db = new TurbineClient({
   connectionString: process.env.SUPABASE_DB_URL,
   ssl: { rejectUnauthorized: false },
-}, schema);
+}, SCHEMA);
 ```
 
 ### Cloudflare Workers
@@ -692,12 +749,12 @@ const db = new TurbineClient({
 ```ts
 import { Pool } from '@neondatabase/serverless';
 import { turbineHttp } from 'turbine-orm/serverless';
-import { schema } from './generated/turbine/metadata';
+import { SCHEMA } from './generated/turbine/metadata';
 
 export default {
   async fetch(req: Request, env: Env) {
     const pool = new Pool({ connectionString: env.DATABASE_URL });
-    const db = turbineHttp(pool, schema);
+    const db = turbineHttp(pool, SCHEMA);
     const users = await db.table('users').findMany({ limit: 10 });
     return Response.json(users);
   },
@@ -712,6 +769,70 @@ export default {
 
 When Turbine receives an external pool, `db.disconnect()` is a no-op: the caller owns the pool's lifecycle.
 
+## Database engines
+
+Turbine is **Postgres-first** — `import { TurbineClient } from 'turbine-orm'` targets PostgreSQL, and the safety bundle above is built around it. When you need another database, the same typed API runs on **SQLite**, **MySQL 8**, and **SQL Server** through subpath exports. Multi-engine is *additive*, not a pivot: pick the engine that fits, keep the same `findMany` / `with` / `where` API.
+
+The root install stays one dependency (`pg`). Each engine's driver is its own concern: SQLite needs nothing (Node's built-in `node:sqlite`), MySQL and SQL Server use **optional peer dependencies** you install only if you use them.
+
+```bash
+# SQLite — zero extra deps (Node >= 22.5, built-in node:sqlite)
+npm install turbine-orm
+
+# MySQL 8 — optional peer
+npm install turbine-orm mysql2
+
+# SQL Server 2016+ — optional peer
+npm install turbine-orm mssql
+```
+
+Each engine ships a factory that returns the same `TurbineClient`:
+
+```ts
+// SQLite — synchronous; pass a file path, ':memory:', or an open DatabaseSync
+import { turbineSqlite } from 'turbine-orm/sqlite';
+import { SCHEMA } from './generated/turbine/metadata.js';
+
+const db = turbineSqlite(':memory:', SCHEMA);
+const users = await db.users.findMany({ with: { posts: true }, limit: 10 });
+```
+
+```ts
+// MySQL 8 — async; connection string, mysql2 config, or an existing mysql2 pool
+import { turbineMysql } from 'turbine-orm/mysql';
+import { SCHEMA } from './generated/turbine/metadata.js';
+
+const db = await turbineMysql('mysql://user:pass@localhost:3306/app', SCHEMA);
+```
+
+```ts
+// SQL Server 2016+ — async; connection string, mssql config, or an existing pool
+import { turbineMssql } from 'turbine-orm/mssql';
+import { SCHEMA } from './generated/turbine/metadata.js';
+
+const db = await turbineMssql('mssql://sa:Passw0rd!@localhost:1433/app', SCHEMA);
+```
+
+### Capability matrix
+
+Everything is honest about what ports and what doesn't. Features marked **PG-only** throw a typed `UnsupportedFeatureError` (`TURBINE_E017`) on other engines rather than silently degrading.
+
+| Feature | PostgreSQL | SQLite | MySQL 8 | SQL Server |
+|---|:---:|:---:|:---:|:---:|
+| Single-query nested `with` | ✓ `json_agg` | ✓ `json_group_array` | ✓ `JSON_ARRAYAGG` | ✓ `FOR JSON PATH` |
+| Transactions + savepoints | ✓ | ✓ (single-writer) | ✓ | ✓ |
+| Streaming (`findManyStream`) | ✓ | ✓ | ✓ | ✓ |
+| Migrations (`turbine migrate` CLI) | ✓ | PG-only (CLI) | PG-only (CLI) | PG-only (CLI) |
+| pgvector distance / KNN | ✓ | ✗ E017 | ✗ E017 | ✗ E017 |
+| LISTEN/NOTIFY realtime | ✓ | ✗ E017 | ✗ E017 | ✗ E017 |
+| RLS `sessionContext` | ✓ | ✗ E017 | ✗ E017 | ✗ E017 |
+
+✗ E017 = throws `UnsupportedFeatureError`. The full matrix (atomic updates, introspection, optimistic locking, per-cell mechanics) is on [turbineorm.dev/engines](https://turbineorm.dev/engines).
+
+**Engine notes:** SQLite uses `RETURNING` (≥ 3.35) just like Postgres. MySQL has no `RETURNING`, so writes re-`SELECT` the affected row and **`createMany` returns `[]`** (the rows ARE inserted — re-query if you need them). SQL Server returns rows via `OUTPUT`/`MERGE`; `DISTINCT ON` is Postgres-only. Only Postgres streams via a true cursor (constant memory); the other engines' `findManyStream` materializes the result then yields it in batches. Optimistic locking throws `OptimisticLockError` on all engines (on MySQL the conflict is detected from the version-checked UPDATE's affected-row count). The `turbine` CLI (`generate`, `migrate`) is currently PostgreSQL-only — point the engine factories at a hand-written or programmatically introspected `SCHEMA`.
+
+Full setup, signatures, and the complete support matrix: **[turbineorm.dev/engines](https://turbineorm.dev/engines)**.
+
 ## Configuration
 
 Create `turbine.config.ts` in your project root (or run `npx turbine init`):
@@ -761,18 +882,18 @@ Turbine maps Postgres types to TypeScript:
 |---|---|---|---|---|
 | **Engine / runtime** | No engine binary (`pg` only) | Client + 1.6 MB WASM engine | No engine | No engine |
 | **Runtime deps** | 1 (`pg`) | `@prisma/client` + adapter | 0 | 0 |
-| **Main bundle (gzip)** | ~30 KB | dominated by 1.6 MB WASM | ~7 KB core | small |
+| **Main bundle (brotli)** | ~31 kB | dominated by 1.6 MB WASM | ~7 KB core | small |
 | **Studio** | Read-only, 192-bit auth | Full CRUD, cloud-hosted | Paid tier | None |
 | **Error PII safety** | Keys only by default | Values in messages | Raw pg errors | Raw pg errors |
 | **Migrations** | SQL-first, SHA-256 checksums | DSL-generated, shadow DB | SQL or Drizzle Kit | None |
-| **Edge runtime** | One import swap, ~21 KB gzip | 1.6 MB WASM adapter | Native | Native |
+| **Edge runtime** | One import swap, ~22 kB brotli | 1.6 MB WASM adapter | Native | Native |
 | **Pipeline batching** | Parse/Bind/Execute protocol | Sequential in txn | Sequential | Manual |
 | **Typed errors** | `isRetryable` discriminant | Error codes only | None | None |
 | **Nested relations** | 1 query, deep type inference | 1 query, shallow inference | 1 query, `relations()` re-declaration | Manual (`jsonArrayFrom`) |
 | **Many-to-many** | Auto-detected from junctions | Implicit/explicit | Explicit `relations()` | Manual joins |
 | **Vector search** | Built-in `distance` / KNN | Preview / raw | Extension API | Manual |
 | **LISTEN/NOTIFY** | `$listen` / `$notify` | None | None | None |
-| **Multi-DB** | PostgreSQL only | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
+| **Multi-DB** | Postgres-first (+ SQLite/MySQL/MSSQL engines) | PG, MySQL, SQLite, MSSQL | PG, MySQL, SQLite | PG, MySQL, SQLite |
 
 All three ORMs now do single-query nested loads — that's table stakes. Turbine's real differentiators: no engine binary or WASM — just one dependency (`pg`), vs Prisma's 1.6 MB WASM query engine; the only read-only Studio in the ecosystem; error messages that never leak PII; and SQL-first migrations with SHA-256 drift detection. See [Benchmarks](#benchmarks) for performance numbers — most scenarios are within noise over a real pooled database.
 
@@ -780,7 +901,7 @@ All three ORMs now do single-query nested loads — that's table stakes. Turbine
 
 Turbine is focused and opinionated. Here's what it doesn't do:
 
-- **PostgreSQL only.** No MySQL, SQLite, or MSSQL. By design — going deep on one database enables the performance advantage and the edge-runtime story.
+- **Postgres-first.** PostgreSQL is the default and primary target — going deep on one database is what enables the safety bundle and the edge-runtime story. SQLite, MySQL 8, and SQL Server engines are available as additive subpath exports (see [Database engines](#database-engines)), but several flagship features (pgvector, LISTEN/NOTIFY, RLS `sessionContext`) are Postgres-only and throw `UnsupportedFeatureError` elsewhere.
 - **Full-text search** is available via a `search` filter — `where: { title: { search: 'hello & world', config: 'english' } }` compiles to a parameterized `to_tsvector(...) @@ to_tsquery(...)`. For advanced ranking (`ts_rank`, weighted vectors) use `db.raw`.
 - **Large nested result sets.** Nested results are materialized server-side in PostgreSQL memory. For relations with 10K+ rows, always use `limit` in your `with` clause — or stream the parents with `findManyStream` and resolve children per-row.
 
@@ -818,6 +939,17 @@ Turbine is focused and opinionated. Here's what it doesn't do:
 - PostgreSQL >= 14
 - Works with both ESM (`import`) and CommonJS (`require`)
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the test strategy, and the PR checklist. The unit suite runs without a database:
+
+```bash
+npm install
+npm run test:unit
+```
+
+Integration tests need a PostgreSQL instance via `DATABASE_URL` (see CONTRIBUTING.md for a one-command seeded setup).
+
 ## License
 
 MIT

package/dist/adapters/cockroachdb.js

@@ -54,15 +54,10 @@ const CREATE_LOCK_TABLE_SQL = `
 // Introspection query overrides
 // ---------------------------------------------------------------------------
 /**
- * CockroachDB index introspection via SHOW INDEXES.
- * This returns a different shape than pg_indexes, so the consumer
- * needs to handle the transformation. However, since we're providing this
- * as a drop-in SQL string for the existing introspection flow, we use
- * CockroachDB's pg_indexes compatibility view but with a fallback query
- * that produces the same columns.
- *
- * CockroachDB's pg_indexes is compatible since v22.1 — we keep this
- * override for older versions or when indexdef is incomplete.
+ * CockroachDB index introspection via the pg_indexes compatibility view.
+ * CockroachDB exposes pg_indexes (compatible since v22.1) with the same
+ * tablename/indexname/indexdef columns as PostgreSQL, so the standard
+ * introspection flow consumes this drop-in SQL string unchanged.
  */
 const SQL_INDEXES_CRDB = `
   SELECT

package/dist/cjs/adapters/cockroachdb.js

@@ -57,15 +57,10 @@ const CREATE_LOCK_TABLE_SQL = `
 // Introspection query overrides
 // ---------------------------------------------------------------------------
 /**
- * CockroachDB index introspection via SHOW INDEXES.
- * This returns a different shape than pg_indexes, so the consumer
- * needs to handle the transformation. However, since we're providing this
- * as a drop-in SQL string for the existing introspection flow, we use
- * CockroachDB's pg_indexes compatibility view but with a fallback query
- * that produces the same columns.
- *
- * CockroachDB's pg_indexes is compatible since v22.1 — we keep this
- * override for older versions or when indexdef is incomplete.
+ * CockroachDB index introspection via the pg_indexes compatibility view.
+ * CockroachDB exposes pg_indexes (compatible since v22.1) with the same
+ * tablename/indexname/indexdef columns as PostgreSQL, so the standard
+ * introspection flow consumes this drop-in SQL string unchanged.
  */
 const SQL_INDEXES_CRDB = `
   SELECT

package/dist/cjs/cli/index.js

@@ -964,9 +964,10 @@ async function cmdStudio(args, config) {
         console.log((0, ui_js_1.red)(`✗ invalid port: ${args.port}`));
         process.exit(1);
     }
-    // Refuse to bind anything other than loopback unless explicitly overridden.
-    // This is deliberate: Studio has no real authentication beyond a random
-    // session token, so exposing it on a LAN interface is foot-gun territory.
+    // Warn loudly when an explicit non-loopback --host is used — the user is
+    // opting in, so we proceed rather than refuse. Studio has no real
+    // authentication beyond a random session token, so exposing it on a LAN
+    // interface is foot-gun territory.
     if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
         console.log((0, ui_js_1.warn)(`Studio is binding to ${(0, ui_js_1.yellow)(host)} — this is NOT loopback. ` +
             `Anyone on your network who can reach this port + guess the session token can read your database.`));
@@ -1039,6 +1040,8 @@ async function cmdObserve(args) {
         console.log((0, ui_js_1.red)(`✗ invalid port: ${args.port}`));
         process.exit(1);
     }
+    // Warn loudly when an explicit non-loopback --host is used — the user is
+    // opting in, so we proceed rather than refuse.
     if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
         console.log((0, ui_js_1.warn)(`Observe is binding to ${(0, ui_js_1.yellow)(host)} — this is NOT loopback. ` +
             `Anyone on your network who can reach this port + guess the session token can read your metrics.`));
@@ -1164,13 +1167,15 @@ function showMigrateHelp() {
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
+    console.log(`    ${(0, ui_js_1.cyan)('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${(0, ui_js_1.dim)('(create only)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}    Number of migrations to apply/rollback`);
-    console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}          Show SQL without executing`);
-    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}      Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}      Show detailed output`);
+    console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}         Show SQL without executing`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}     Bypass checksum validation ${(0, ui_js_1.dim)('(migrate up only — advanced)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}     Show detailed output`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create add_users_table`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate create add_email_index --auto`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate up`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate down --step 2`);
     console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine migrate status`);
@@ -1215,16 +1220,17 @@ function showHelp() {
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Commands:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('init')}               Initialize a Turbine project`);
-    console.log(`    ${(0, ui_js_1.cyan)('generate')} ${(0, ui_js_1.dim)('| pull')}   Introspect database ${ui_js_1.symbols.arrow} generate types`);
+    console.log(`    ${(0, ui_js_1.cyan)('generate')} ${(0, ui_js_1.dim)('| pull')}    Introspect database ${ui_js_1.symbols.arrow} generate types`);
     console.log(`    ${(0, ui_js_1.cyan)('push')}               Apply schema definitions to database`);
-    console.log(`    ${(0, ui_js_1.cyan)('migrate')} ${(0, ui_js_1.dim)('<sub>')}     SQL migration management`);
-    console.log(`      ${(0, ui_js_1.dim)('create <name>')}     Create a new migration file`);
+    console.log(`    ${(0, ui_js_1.cyan)('migrate')} ${(0, ui_js_1.dim)('<sub>')}      SQL migration management`);
+    console.log(`      ${(0, ui_js_1.dim)('create <name>')}    Create a new migration file`);
     console.log(`      ${(0, ui_js_1.dim)('up')}               Apply pending migrations`);
     console.log(`      ${(0, ui_js_1.dim)('down')}             Rollback last migration`);
     console.log(`      ${(0, ui_js_1.dim)('status')}           Show applied/pending migrations`);
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
-    console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}     Show schema summary`);
+    console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
     console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI`);
+    console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}      Postgres connection string`);
@@ -1236,8 +1242,13 @@ function showHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}        Show detailed output`);
     console.log(`    ${(0, ui_js_1.cyan)('--force, -f')}          Overwrite existing files`);
     (0, ui_js_1.newline)();
-    console.log(`  ${(0, ui_js_1.bold)('Studio options:')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}           HTTP port ${(0, ui_js_1.dim)('(default: 4983)')}`);
+    console.log(`  ${(0, ui_js_1.bold)('Migrate options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--auto')}               Auto-generate UP/DOWN SQL from schema diff ${(0, ui_js_1.dim)('(create)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--step, -n')} ${(0, ui_js_1.dim)('<N>')}       Number of migrations to apply/rollback`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-drift')}        Bypass checksum validation on ${(0, ui_js_1.cyan)('migrate up')} ${(0, ui_js_1.dim)('(advanced)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Studio / observe options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}           HTTP port ${(0, ui_js_1.dim)('(default: 4983 studio, 4984 observe)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}        Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--no-open')}            Don't auto-open the browser`);
     (0, ui_js_1.newline)();

package/dist/cjs/cli/observe-ui.js

@@ -132,12 +132,22 @@ exports.OBSERVE_HTML = `<!doctype html>
         + '</svg>';
     }
 
+    function escapeHtml(s) {
+      if (s == null) return '';
+      return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+    }
+
     function renderModels(data) {
       const el = document.getElementById('models-table');
       if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No data yet</p>'; return; }
       let html = '<table><thead><tr><th>Model</th><th>Action</th><th class="num">Count</th><th class="num">Avg (ms)</th><th class="num">P95 (ms)</th><th class="num">P99 (ms)</th></tr></thead><tbody>';
       for (const row of data) {
-        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'
+        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'
           + '<td class="num">' + row.count + '</td>'
           + '<td class="num">' + row.avg_ms.toFixed(1) + '</td>'
           + '<td class="num">' + row.p95_ms.toFixed(1) + '</td>'
@@ -154,7 +164,7 @@ exports.OBSERVE_HTML = `<!doctype html>
       for (const row of data) {
         const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';
         const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';
-        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'
+        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'
           + '<td class="num">' + row.count + '</td>'
           + '<td class="num">' + row.error_count + '</td>'
           + '<td class="num ' + cls + '">' + rate + '%</td></tr>';

package/dist/cjs/cli/observe.js

@@ -116,13 +116,12 @@ function isAuthorized(req, expectedToken) {
     return false;
 }
 function constantTimeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let result = 0;
-    for (let i = 0; i < a.length; i++) {
-        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return result === 0;
+    // Hash both inputs to fixed-length 32-byte SHA-256 digests before comparing.
+    // This makes the comparison constant-length (timingSafeEqual never throws on a
+    // length mismatch) and leaks neither length nor content via timing.
+    const ah = (0, node_crypto_1.createHash)('sha256').update(a).digest();
+    const bh = (0, node_crypto_1.createHash)('sha256').update(b).digest();
+    return (0, node_crypto_1.timingSafeEqual)(ah, bh);
 }
 // ---------------------------------------------------------------------------
 // API handlers