turbine-orm 0.15.0 → 0.16.0

package/dist/cjs/nested-write.js

@@ -4,8 +4,8 @@
  *
  * Tree-walking create/update that resolves relation fields in `data` into
  * batched SQL operations within a transaction. Supports create, connect,
- * connectOrCreate, disconnect, set, and delete on related records at
- * arbitrary depth (capped at 10).
+ * connectOrCreate, disconnect, set, delete, update, and upsert on related
+ * records at arbitrary depth (capped at 10).
  *
  * This module is imported by `query/builder.ts` when the `data` argument
  * of `create()` or `update()` contains relation fields. It never imports
@@ -22,7 +22,7 @@ const errors_js_1 = require("./errors.js");
 const schema_js_1 = require("./schema.js");
 const MAX_DEPTH = 10;
 const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
-const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete']);
+const UPDATE_ONLY_OPS = new Set(['disconnect', 'set', 'delete', 'update', 'upsert']);
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for testing)
 // ---------------------------------------------------------------------------
@@ -100,7 +100,7 @@ function validateOps(relationName, ops, isUpdate) {
     for (const opName of Object.keys(ops)) {
         if (!CREATE_ONLY_OPS.has(opName) && !UPDATE_ONLY_OPS.has(opName)) {
             throw new errors_js_1.ValidationError(`[turbine] Unknown nested write operation "${opName}" on relation "${relationName}". ` +
-                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete' : ''}.`);
+                `Valid operations: create, connect, connectOrCreate${isUpdate ? ', disconnect, set, delete, update, upsert' : ''}.`);
         }
         if (!isUpdate && UPDATE_ONLY_OPS.has(opName)) {
             throw new errors_js_1.ValidationError(`[turbine] Operation "${opName}" on relation "${relationName}" is only valid inside update(), not create().`);
@@ -223,9 +223,25 @@ async function executeNestedUpdate(ctx, tableName, where, data, depth = 0, path
             if (ops.delete !== undefined) {
                 await processDelete(ctx, rel, ops.delete);
             }
+            // update
+            if (ops.update !== undefined) {
+                await processNestedUpdate(ctx, rel, ops.update);
+            }
+            // upsert
+            if (ops.upsert !== undefined) {
+                await processNestedUpsert(ctx, rel, ops.upsert, parentRow);
+            }
         }
         else if (rel.type === 'belongsTo') {
             await processBelongsToCreate(ctx, rel, ops, parentRow, tableName, depth, path, relName);
+            // update (belongsTo — derive where from parent FK)
+            if (ops.update !== undefined) {
+                await processBelongsToUpdate(ctx, rel, ops.update, parentRow, tableName);
+            }
+            // upsert (belongsTo)
+            if (ops.upsert !== undefined) {
+                await processBelongsToUpsert(ctx, rel, ops.upsert, parentRow, tableName);
+            }
             if (ops.disconnect !== undefined) {
                 // For belongsTo disconnect, null out the FK on the parent
                 const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
@@ -459,6 +475,80 @@ async function processSet(ctx, rel, setItems, parentRow) {
         await ctx.tx.table(rel.to).update({ where: target, data: updateData });
     }
 }
+// ---------------------------------------------------------------------------
+// update / upsert operations (update-context only)
+// ---------------------------------------------------------------------------
+async function processNestedUpdate(ctx, rel, updateArg) {
+    const items = toArray(updateArg);
+    for (const item of items) {
+        if (!item.where || !item.data) {
+            throw new errors_js_1.ValidationError(`[turbine] Nested update on "${rel.name}" requires both "where" and "data" fields.`);
+        }
+        await ctx.tx.table(rel.to).update({ where: item.where, data: item.data });
+    }
+}
+async function processNestedUpsert(ctx, rel, upsertArg, parentRow) {
+    const items = toArray(upsertArg);
+    for (const item of items) {
+        if (!item.where || !item.create || !item.update) {
+            throw new errors_js_1.ValidationError(`[turbine] Nested upsert on "${rel.name}" requires "where", "create", and "update" fields.`);
+        }
+        const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+        if (existing) {
+            await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+        }
+        else {
+            const injected = injectForeignKey(item.create, rel, parentRow, ctx.schema);
+            await ctx.tx.table(rel.to).create({ data: injected });
+        }
+    }
+}
+async function processBelongsToUpdate(ctx, rel, updateArg, parentRow, parentTable) {
+    const item = updateArg;
+    if (!item.data) {
+        throw new errors_js_1.ValidationError(`[turbine] Nested update on belongsTo "${rel.name}" requires a "data" field.`);
+    }
+    // Derive where from parent's FK values
+    const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+    const refs = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+    const parentMeta = ctx.schema.tables[parentTable];
+    const relatedTable = ctx.schema.tables[rel.to];
+    const where = {};
+    for (let i = 0; i < fks.length; i++) {
+        const fkField = parentMeta?.reverseColumnMap[fks[i]] ?? fks[i];
+        const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+        where[refField] = parentRow[fkField];
+    }
+    await ctx.tx.table(rel.to).update({ where, data: item.data });
+}
+async function processBelongsToUpsert(ctx, rel, upsertArg, parentRow, parentTable) {
+    const item = upsertArg;
+    if (!item.where || !item.create || !item.update) {
+        throw new errors_js_1.ValidationError(`[turbine] Nested upsert on belongsTo "${rel.name}" requires "where", "create", and "update" fields.`);
+    }
+    const existing = await ctx.tx.table(rel.to).findUnique({ where: item.where });
+    if (existing) {
+        await ctx.tx.table(rel.to).update({ where: item.where, data: item.update });
+    }
+    else {
+        // Create the related row, then update parent's FK to point at it
+        const createdRow = (await ctx.tx.table(rel.to).create({ data: item.create }));
+        const fks = (0, schema_js_1.normalizeKeyColumns)(rel.foreignKey);
+        const refs = (0, schema_js_1.normalizeKeyColumns)(rel.referenceKey);
+        const parentMeta = ctx.schema.tables[parentTable];
+        const relatedTable = ctx.schema.tables[rel.to];
+        const updateData = {};
+        for (let i = 0; i < fks.length; i++) {
+            const fkField = parentMeta.reverseColumnMap[fks[i]] ?? fks[i];
+            const refField = relatedTable?.reverseColumnMap[refs[i]] ?? refs[i];
+            updateData[fkField] = createdRow[refField];
+        }
+        await ctx.tx.table(parentTable).update({
+            where: pkWhere(parentMeta, parentRow),
+            data: updateData,
+        });
+    }
+}
 async function processDelete(ctx, rel, deleteArg) {
     const items = toArray(deleteArg);
     for (const target of items) {

package/dist/cjs/observe.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * turbine-orm — Observability module
+ *
+ * Buffers query metrics in memory (keyed by model:action per minute bucket),
+ * then periodically flushes aggregates (count, avg, p50, p95, p99, errors)
+ * to a dedicated _turbine_metrics table. Uses a separate 1-connection pool
+ * so metrics writes never contend with the application pool.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObserveEngine = void 0;
+exports.floorToMinute = floorToMinute;
+exports.percentile = percentile;
+const pg_1 = __importDefault(require("pg"));
+function floorToMinute(date) {
+    const d = new Date(date);
+    d.setSeconds(0, 0);
+    return d;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil(p * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+// ---------------------------------------------------------------------------
+// Schema DDL
+// ---------------------------------------------------------------------------
+const SCHEMA_DDL = `
+CREATE TABLE IF NOT EXISTS _turbine_metrics (
+  id          BIGSERIAL PRIMARY KEY,
+  bucket      TIMESTAMPTZ NOT NULL,
+  model       TEXT NOT NULL,
+  action      TEXT NOT NULL,
+  count       INTEGER NOT NULL DEFAULT 0,
+  avg_ms      REAL NOT NULL DEFAULT 0,
+  p50_ms      REAL NOT NULL DEFAULT 0,
+  p95_ms      REAL NOT NULL DEFAULT 0,
+  p99_ms      REAL NOT NULL DEFAULT 0,
+  error_count INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(bucket, model, action)
+);
+CREATE INDEX IF NOT EXISTS idx_turbine_metrics_bucket ON _turbine_metrics(bucket);
+`;
+const UPSERT_SQL = `
+INSERT INTO _turbine_metrics (bucket, model, action, count, avg_ms, p50_ms, p95_ms, p99_ms, error_count)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+ON CONFLICT (bucket, model, action) DO UPDATE SET
+  count = _turbine_metrics.count + EXCLUDED.count,
+  avg_ms = (_turbine_metrics.avg_ms * _turbine_metrics.count + EXCLUDED.avg_ms * EXCLUDED.count)
+           / (_turbine_metrics.count + EXCLUDED.count),
+  p50_ms = EXCLUDED.p50_ms,
+  p95_ms = EXCLUDED.p95_ms,
+  p99_ms = EXCLUDED.p99_ms,
+  error_count = _turbine_metrics.error_count + EXCLUDED.error_count
+`;
+const RETENTION_SQL = `DELETE FROM _turbine_metrics WHERE bucket < NOW() - INTERVAL '1 day' * $1`;
+// ---------------------------------------------------------------------------
+// Observe engine
+// ---------------------------------------------------------------------------
+class ObserveEngine {
+    pool;
+    buffer = new Map();
+    currentBucket;
+    flushIntervalMs;
+    retentionDays;
+    timer;
+    listener;
+    stopped = false;
+    constructor(config) {
+        this.pool = new pg_1.default.Pool({ connectionString: config.connectionString, max: 1 });
+        this.flushIntervalMs = config.flushIntervalMs ?? 60_000;
+        this.retentionDays = config.retentionDays ?? 30;
+        this.currentBucket = floorToMinute(new Date());
+        this.listener = (event) => {
+            if (this.stopped)
+                return;
+            const nowBucket = floorToMinute(new Date());
+            if (nowBucket.getTime() !== this.currentBucket.getTime()) {
+                this.currentBucket = nowBucket;
+            }
+            const key = `${event.model}:${event.action}`;
+            let entry = this.buffer.get(key);
+            if (!entry) {
+                entry = { durations: [], errors: 0 };
+                this.buffer.set(key, entry);
+            }
+            entry.durations.push(event.duration);
+            if (event.error)
+                entry.errors++;
+        };
+    }
+    getListener() {
+        return this.listener;
+    }
+    async init() {
+        await this.pool.query(SCHEMA_DDL);
+        this.timer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+        // Unref so it doesn't keep the process alive
+        if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+    }
+    async flush() {
+        if (this.buffer.size === 0)
+            return;
+        const bucket = this.currentBucket;
+        const entries = new Map(this.buffer);
+        this.buffer.clear();
+        for (const [key, entry] of entries) {
+            const [model, action] = key.split(':');
+            const sorted = entry.durations.slice().sort((a, b) => a - b);
+            const count = sorted.length;
+            const avg = sorted.reduce((s, v) => s + v, 0) / count;
+            const p50 = percentile(sorted, 0.5);
+            const p95 = percentile(sorted, 0.95);
+            const p99 = percentile(sorted, 0.99);
+            try {
+                await this.pool.query(UPSERT_SQL, [bucket, model, action, count, avg, p50, p95, p99, entry.errors]);
+            }
+            catch {
+                // Fire-and-forget — never throw from flush
+            }
+        }
+        try {
+            await this.pool.query(RETENTION_SQL, [this.retentionDays]);
+        }
+        catch {
+            // Best effort
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.flush();
+        await this.pool.end();
+    }
+}
+exports.ObserveEngine = ObserveEngine;

package/dist/cjs/query/builder.js

@@ -191,6 +191,8 @@ class QueryInterface {
     txScoped;
     /** Original options reference — forwarded to child QIs in nested writes. */
     options;
+    /** Set by executeWithMiddleware so queryWithTimeout can include it in events. */
+    currentAction = 'raw';
     constructor(pool, table, schema, middlewares, options) {
         this.pool = pool;
         this.table = table;
@@ -272,12 +274,25 @@ class QueryInterface {
     resetUnlimitedWarnings() {
         this.warnedTables.clear();
     }
+    emitQueryEvent(sql, params, duration, action, rows, error) {
+        const onQuery = this.options?._onQuery;
+        if (!onQuery)
+            return;
+        try {
+            onQuery({ sql, params, duration, model: this.table, action, rows, timestamp: new Date(), error });
+        }
+        catch {
+            // Listener errors must never crash a query
+        }
+    }
     /**
      * Execute a pool.query with an optional timeout.
      * If timeout is set, races the query against a timer and rejects on expiry.
      * pg driver errors are translated to typed Turbine errors via wrapPgError.
      */
     async queryWithTimeout(sql, params, timeout, preparedName) {
+        const start = performance.now();
+        const action = this.currentAction;
         // Build the query argument — use object form with `name` for prepared
         // statements, or the plain (text, values) form otherwise.
         const usePrepared = preparedName && this.preparedStatementsEnabled;
@@ -286,10 +301,14 @@ class QueryInterface {
             : this.pool.query(sql, params);
         if (!timeout) {
             try {
-                return await exec;
+                const result = await exec;
+                this.emitQueryEvent(sql, params, performance.now() - start, action, result.rowCount ?? 0);
+                return result;
             }
             catch (err) {
-                throw (0, errors_js_1.wrapPgError)(err);
+                const wrapped = (0, errors_js_1.wrapPgError)(err);
+                this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+                throw wrapped;
             }
         }
         let timer;
@@ -297,10 +316,14 @@ class QueryInterface {
             timer = setTimeout(() => reject(new errors_js_1.TimeoutError(timeout)), timeout);
         });
         try {
-            return await Promise.race([exec, timeoutPromise]);
+            const result = await Promise.race([exec, timeoutPromise]);
+            this.emitQueryEvent(sql, params, performance.now() - start, action, result.rowCount ?? 0);
+            return result;
         }
         catch (err) {
-            throw (0, errors_js_1.wrapPgError)(err);
+            const wrapped = (0, errors_js_1.wrapPgError)(err);
+            this.emitQueryEvent(sql, params, performance.now() - start, action, 0, wrapped instanceof Error ? wrapped : undefined);
+            throw wrapped;
         }
         finally {
             clearTimeout(timer);
@@ -316,6 +339,7 @@ class QueryInterface {
      * To intercept queries before SQL generation, use the raw() method instead.
      */
     async executeWithMiddleware(action, args, executor) {
+        this.currentAction = action;
         if (this.middlewares.length === 0) {
             return executor();
         }
@@ -335,7 +359,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findUnique
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUnique(args) {
         return this.executeWithMiddleware('findUnique', args, async () => {
             const deferred = this.buildFindUnique(args);
@@ -439,7 +462,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findMany
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findMany(args) {
         this.maybeWarnUnlimited(args);
         // Dev-only: warn on deeply nested with clauses
@@ -641,7 +663,6 @@ class QueryInterface {
      * }
      * ```
      */
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async *findManyStream(args) {
         const batchSize = Math.max(1, Math.floor(Number(args?.batchSize ?? 1000)));
         const hasRelations = !!args?.with;
@@ -650,6 +671,7 @@ class QueryInterface {
             ...args,
             limit: batchSize + 1,
         });
+        this.currentAction = 'findManyStream';
         const speculativeResult = await this.queryWithTimeout(speculativeDeferred.sql, speculativeDeferred.params, args?.timeout);
         if (speculativeResult.rows.length <= batchSize) {
             // Small drain — yield all rows and return, no cursor needed
@@ -698,7 +720,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirst — like findMany but returns a single row or null
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirst(args) {
         return this.executeWithMiddleware('findFirst', (args ?? {}), async () => {
             const deferred = this.buildFindFirst(args);
@@ -724,7 +745,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findFirstOrThrow — like findFirst but throws if no record found
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findFirstOrThrow(args) {
         return this.executeWithMiddleware('findFirstOrThrow', (args ?? {}), async () => {
             const deferred = this.buildFindFirstOrThrow(args);
@@ -755,7 +775,6 @@ class QueryInterface {
     // -------------------------------------------------------------------------
     // findUniqueOrThrow — like findUnique but throws if no record found
     // -------------------------------------------------------------------------
-    // biome-ignore lint/complexity/noBannedTypes: {} means "no with clause" — matches TypedWithClause default
     async findUniqueOrThrow(args) {
         return this.executeWithMiddleware('findUniqueOrThrow', args, async () => {
             const deferred = this.buildFindUniqueOrThrow(args);
@@ -1669,7 +1688,11 @@ class QueryInterface {
             const relDef = this.tableMeta.relations[key];
             if (relDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 const filterObj = value;
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                if ('some' in filterObj ||
+                    'every' in filterObj ||
+                    'none' in filterObj ||
+                    'is' in filterObj ||
+                    'isNot' in filterObj) {
                     const relParts = [];
                     if (filterObj.some !== undefined)
                         relParts.push(`some(${this.fingerprintRelFilter(relDef.to, filterObj.some)})`);
@@ -1677,6 +1700,10 @@ class QueryInterface {
                         relParts.push(`every(${this.fingerprintRelFilter(relDef.to, filterObj.every)})`);
                     if (filterObj.none !== undefined)
                         relParts.push(`none(${this.fingerprintRelFilter(relDef.to, filterObj.none)})`);
+                    if (filterObj.is !== undefined)
+                        relParts.push(`is(${this.fingerprintRelFilter(relDef.to, filterObj.is)})`);
+                    if (filterObj.isNot !== undefined)
+                        relParts.push(`isNot(${this.fingerprintRelFilter(relDef.to, filterObj.isNot)})`);
                     parts.push(`${key}:{${relParts.join(',')}}`);
                     continue;
                 }
@@ -1798,13 +1825,21 @@ class QueryInterface {
             const relationDef = this.tableMeta.relations[key];
             if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 const filterObj = value;
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                if ('some' in filterObj ||
+                    'every' in filterObj ||
+                    'none' in filterObj ||
+                    'is' in filterObj ||
+                    'isNot' in filterObj) {
                     if (filterObj.some !== undefined)
                         this.collectRelFilterParams(relationDef.to, filterObj.some, params);
                     if (filterObj.none !== undefined)
                         this.collectRelFilterParams(relationDef.to, filterObj.none, params);
                     if (filterObj.every !== undefined)
                         this.collectRelFilterParams(relationDef.to, filterObj.every, params);
+                    if (filterObj.is !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.is, params);
+                    if (filterObj.isNot !== undefined)
+                        this.collectRelFilterParams(relationDef.to, filterObj.isNot, params);
                     continue;
                 }
             }
@@ -2157,7 +2192,11 @@ class QueryInterface {
             if (relationDef && typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 const filterObj = value;
                 // Check if this is a relation filter (has some/every/none keys)
-                if ('some' in filterObj || 'every' in filterObj || 'none' in filterObj) {
+                if ('some' in filterObj ||
+                    'every' in filterObj ||
+                    'none' in filterObj ||
+                    'is' in filterObj ||
+                    'isNot' in filterObj) {
                     const relClause = this.buildRelationFilter(key, relationDef, filterObj, params);
                     if (relClause)
                         andClauses.push(relClause);
@@ -2274,6 +2313,20 @@ class QueryInterface {
                 // "every" with empty filter = true (all match trivially)
             }
         }
+        // "is": EXISTS — for to-one relations (same SQL as "some")
+        if (filterObj.is !== undefined) {
+            const subWhere = filterObj.is;
+            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
+            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
+            clauses.push(`EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+        }
+        // "isNot": NOT EXISTS — for to-one relations (same SQL as "none")
+        if (filterObj.isNot !== undefined) {
+            const subWhere = filterObj.isNot;
+            const filterClause = this.buildSubWhereForRelation(targetTable, subWhere, params);
+            const fullWhere = filterClause ? `${correlation} AND ${filterClause}` : correlation;
+            clauses.push(`NOT EXISTS (SELECT 1 FROM ${qt} WHERE ${fullWhere})`);
+        }
         return clauses.length > 0 ? clauses.join(' AND ') : null;
     }
     /**

package/dist/cli/index.d.ts

@@ -13,6 +13,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine studio                — Launch local read-only web UI
+ *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate

package/dist/cli/index.js

@@ -13,6 +13,7 @@
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
  *   turbine studio                — Launch local read-only web UI
+ *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -28,6 +29,7 @@ import { schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfig, resolveConfig } from './config.js';
 import { needsTsLoader, registerTsLoader } from './loader.js';
 import { createMigration, listMigrationFiles, migrateDown, migrateStatus, migrateUp } from './migrate.js';
+import { startObserve } from './observe.js';
 import { startStudio } from './studio.js';
 import { banner, blue, bold, box, cyan, dim, divider, elapsed, error, table as formatTable, gray, green, header, info, label, magenta, newline, red, redactUrl, Spinner, success, symbols, warn, yellow, } from './ui.js';
 function parseArgs() {
@@ -970,6 +972,65 @@ async function cmdStudio(args, config) {
     });
 }
 // ---------------------------------------------------------------------------
+// Command: observe
+// ---------------------------------------------------------------------------
+async function cmdObserve(args) {
+    banner();
+    const url = process.env.TURBINE_OBSERVE_URL;
+    if (!url) {
+        error('TURBINE_OBSERVE_URL environment variable is required for the observe command.');
+        newline();
+        console.log(`  ${dim('Set it to the Postgres connection string where metrics are stored.')}`);
+        console.log(`  ${dim('Example:')} ${cyan('TURBINE_OBSERVE_URL=postgres://... npx turbine observe')}`);
+        newline();
+        process.exit(1);
+    }
+    const port = args.port ?? 4984;
+    const host = args.host ?? '127.0.0.1';
+    const openBrowser = !args.noOpen;
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        console.log(red(`✗ invalid port: ${args.port}`));
+        process.exit(1);
+    }
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+        console.log(warn(`Observe is binding to ${yellow(host)} — this is NOT loopback. ` +
+            `Anyone on your network who can reach this port + guess the session token can read your metrics.`));
+    }
+    const spinner = new Spinner('Connecting to metrics database').start();
+    let handle;
+    try {
+        handle = await startObserve({ url, port, host, openBrowser });
+        spinner.succeed('Observe dashboard is running');
+    }
+    catch (err) {
+        spinner.fail(`Failed to start Observe: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    newline();
+    console.log(box([
+        `${bold('Turbine Observe')}  ${dim('— query metrics dashboard')}`,
+        '',
+        `  ${cyan('URL:')}  ${bold(handle.url)}`,
+        '',
+        dim('Open the URL above in your browser. Press Ctrl+C to stop.'),
+    ].join('\n'), { title: bold(cyan('Observe')), padding: 1 }));
+    newline();
+    await new Promise((resolve) => {
+        const shutdown = async () => {
+            console.log(dim('\n  shutting down…'));
+            try {
+                await handle.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve();
+        };
+        process.once('SIGINT', shutdown);
+        process.once('SIGTERM', shutdown);
+    });
+}
+// ---------------------------------------------------------------------------
 // Subcommand help
 // ---------------------------------------------------------------------------
 function showSubcommandHelp(command) {
@@ -1253,6 +1314,9 @@ async function main() {
             case 'studio':
                 await cmdStudio(args, config);
                 break;
+            case 'observe':
+                await cmdObserve(args);
+                break;
             default:
                 error(`Unknown command: ${bold(args.command)}`);
                 newline();

package/dist/cli/observe-ui.d.ts

@@ -0,0 +1,2 @@
+export declare const OBSERVE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n  <meta name=\"color-scheme\" content=\"dark\" />\n  <title>Turbine Observe</title>\n  <style>\n    :root {\n      --bg: #0a0a0b;\n      --bg-elev: #111113;\n      --bg-hover: #1a1a1d;\n      --border: #26262b;\n      --text: #e6e6ea;\n      --text-dim: #8a8a93;\n      --accent: #60a5fa;\n      --green: #4ade80;\n      --red: #f87171;\n      --orange: #fb923c;\n      --purple: #a78bfa;\n      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n      --sans: system-ui, -apple-system, sans-serif;\n      --radius: 6px;\n    }\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }\n    h1 { font-size: 20px; margin-bottom: 4px; }\n    .subtitle { color: var(--text-dim); margin-bottom: 24px; }\n    .controls { display: flex; gap: 8px; margin-bottom: 24px; }\n    .controls button {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;\n    }\n    .controls button.active { border-color: var(--accent); color: var(--accent); }\n    .card {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      padding: 16px; margin-bottom: 16px;\n    }\n    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }\n    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }\n    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }\n    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }\n    .num { text-align: right; }\n    .error-rate { color: var(--red); }\n    .low-error { color: var(--green); }\n    svg { width: 100%; height: 200px; }\n    .chart-line { fill: none; stroke-width: 1.5; }\n    .line-avg { stroke: var(--accent); }\n    .line-p95 { stroke: var(--orange); }\n    .line-p99 { stroke: var(--red); }\n    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }\n    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }\n    .legend .l-avg::before { background: var(--accent); }\n    .legend .l-p95::before { background: var(--orange); }\n    .legend .l-p99::before { background: var(--red); }\n    .empty { color: var(--text-dim); text-align: center; padding: 40px; }\n  </style>\n</head>\n<body>\n  <h1>Turbine Observe</h1>\n  <p class=\"subtitle\">Query performance metrics</p>\n  <div class=\"controls\">\n    <button data-range=\"1h\" class=\"active\">1h</button>\n    <button data-range=\"6h\">6h</button>\n    <button data-range=\"24h\">24h</button>\n    <button data-range=\"7d\">7d</button>\n  </div>\n  <div class=\"card\" id=\"latency-card\">\n    <h2>Latency over time</h2>\n    <div id=\"chart\"></div>\n    <div class=\"legend\">\n      <span class=\"l-avg\">avg</span>\n      <span class=\"l-p95\">p95</span>\n      <span class=\"l-p99\">p99</span>\n    </div>\n  </div>\n  <div class=\"card\" id=\"models-card\">\n    <h2>Top models</h2>\n    <div id=\"models-table\"></div>\n  </div>\n  <div class=\"card\" id=\"errors-card\">\n    <h2>Error rates</h2>\n    <div id=\"errors-table\"></div>\n  </div>\n  <script>\n    let currentRange = '1h';\n    const token = document.cookie.match(/turbine_observe_token=([a-f0-9]+)/)?.[1] || '';\n    const headers = { 'x-turbine-token': token };\n\n    document.querySelector('.controls').addEventListener('click', e => {\n      if (e.target.tagName !== 'BUTTON') return;\n      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));\n      e.target.classList.add('active');\n      currentRange = e.target.dataset.range;\n      refresh();\n    });\n\n    async function fetchJson(path) {\n      const res = await fetch(path, { headers });\n      if (!res.ok) return null;\n      return res.json();\n    }\n\n    function buildSvgPath(points, width, height, maxY) {\n      if (points.length === 0) return '';\n      const xStep = width / Math.max(points.length - 1, 1);\n      return points.map((y, i) => {\n        const px = i * xStep;\n        const py = height - (y / maxY) * height;\n        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);\n      }).join(' ');\n    }\n\n    function renderChart(data) {\n      const el = document.getElementById('chart');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      const width = 800; const height = 180;\n      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);\n      const maxY = Math.max(...allVals, 1) * 1.1;\n      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);\n      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);\n      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);\n      el.innerHTML = '<svg viewBox=\"0 0 ' + width + ' ' + height + '\" preserveAspectRatio=\"none\">'\n        + '<path class=\"chart-line line-avg\" d=\"' + avgPath + '\"/>'\n        + '<path class=\"chart-line line-p95\" d=\"' + p95Path + '\"/>'\n        + '<path class=\"chart-line line-p99\" d=\"' + p99Path + '\"/>'\n        + '</svg>';\n    }\n\n    function renderModels(data) {\n      const el = document.getElementById('models-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      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>';\n      for (const row of data) {\n        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'\n          + '<td class=\"num\">' + row.count + '</td>'\n          + '<td class=\"num\">' + row.avg_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p95_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p99_ms.toFixed(1) + '</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    function renderErrors(data) {\n      const el = document.getElementById('errors-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No errors</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Total</th><th class=\"num\">Errors</th><th class=\"num\">Rate</th></tr></thead><tbody>';\n      for (const row of data) {\n        const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';\n        const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';\n        html += '<tr><td>' + row.model + '</td><td>' + row.action + '</td>'\n          + '<td class=\"num\">' + row.count + '</td>'\n          + '<td class=\"num\">' + row.error_count + '</td>'\n          + '<td class=\"num ' + cls + '\">' + rate + '%</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    async function refresh() {\n      const [latency, models] = await Promise.all([\n        fetchJson('/api/latency?range=' + currentRange),\n        fetchJson('/api/models?range=' + currentRange),\n      ]);\n      renderChart(latency);\n      renderModels(models);\n      // Derive errors from models data\n      const withErrors = (models || []).filter(m => m.error_count > 0);\n      renderErrors(withErrors);\n    }\n\n    refresh();\n    setInterval(refresh, 60000);\n  </script>\n</body>\n</html>";
+//# sourceMappingURL=observe-ui.d.ts.map