turbine-orm 0.14.0 → 0.16.0

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

package/dist/cli/observe-ui.js

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

package/dist/cli/observe.d.ts

@@ -0,0 +1,20 @@
+/**
+ * turbine-orm CLI — Observe
+ *
+ * A local, read-only dashboard for viewing query metrics stored in
+ * _turbine_metrics. Same security model as Studio: loopback binding,
+ * random token, HttpOnly cookie, CSP headers, read-only transactions.
+ */
+export interface ObserveOptions {
+    url: string;
+    port: number;
+    host: string;
+    openBrowser: boolean;
+}
+export interface ObserveServerHandle {
+    dispose: () => Promise<void>;
+    authToken: string;
+    url: string;
+}
+export declare function startObserve(options: ObserveOptions): Promise<ObserveServerHandle>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/cli/observe.js

@@ -0,0 +1,237 @@
+/**
+ * turbine-orm CLI — Observe
+ *
+ * A local, read-only dashboard for viewing query metrics stored in
+ * _turbine_metrics. Same security model as Studio: loopback binding,
+ * random token, HttpOnly cookie, CSP headers, read-only transactions.
+ */
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import pg from 'pg';
+import { OBSERVE_HTML } from './observe-ui.js';
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+export async function startObserve(options) {
+    const pool = new pg.Pool({
+        connectionString: options.url,
+        max: 2,
+        idleTimeoutMillis: 10_000,
+    });
+    const probe = await pool.connect();
+    try {
+        await probe.query('SELECT 1');
+    }
+    finally {
+        probe.release();
+    }
+    const authToken = randomBytes(24).toString('hex');
+    const server = createServer((req, res) => {
+        handleRequest(req, res, pool, options, authToken).catch((err) => {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port, options.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
+    const url = `http://${hostPart}:${options.port}/?token=${authToken}`;
+    if (options.openBrowser) {
+        openUrl(url);
+    }
+    return {
+        authToken,
+        url,
+        dispose: async () => {
+            await new Promise((resolve) => server.close(() => resolve()));
+            await pool.end();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Request routing
+// ---------------------------------------------------------------------------
+async function handleRequest(req, res, pool, options, authToken) {
+    const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
+    const expectedOrigin = `http://${hostPart}:${options.port}`;
+    const origin = req.headers.origin;
+    if (origin && origin !== expectedOrigin) {
+        sendJson(res, 403, { error: 'cross-origin requests not allowed' });
+        return;
+    }
+    const url = new URL(req.url ?? '/', expectedOrigin);
+    const pathname = url.pathname;
+    if (pathname === '/' || pathname === '/index.html') {
+        if (req.method !== 'GET' && req.method !== 'HEAD') {
+            sendText(res, 405, 'Method Not Allowed');
+            return;
+        }
+        const queryToken = url.searchParams.get('token');
+        if (queryToken && constantTimeEqual(queryToken, authToken)) {
+            res.writeHead(302, {
+                Location: '/',
+                'Set-Cookie': `turbine_observe_token=${authToken}; Path=/; HttpOnly; SameSite=Strict`,
+            });
+            res.end();
+            return;
+        }
+        sendHtml(res, 200, OBSERVE_HTML);
+        return;
+    }
+    if (!isAuthorized(req, authToken)) {
+        sendJson(res, 401, { error: 'unauthorized' });
+        return;
+    }
+    if (pathname === '/api/latency' && req.method === 'GET') {
+        return apiLatency(res, pool, url.searchParams);
+    }
+    if (pathname === '/api/models' && req.method === 'GET') {
+        return apiModels(res, pool, url.searchParams);
+    }
+    sendJson(res, 404, { error: 'not found' });
+}
+// ---------------------------------------------------------------------------
+// Auth
+// ---------------------------------------------------------------------------
+function isAuthorized(req, expectedToken) {
+    const headerToken = req.headers['x-turbine-token'];
+    if (typeof headerToken === 'string' && constantTimeEqual(headerToken, expectedToken)) {
+        return true;
+    }
+    const cookieHeader = req.headers.cookie ?? '';
+    const match = /turbine_observe_token=([a-f0-9]+)/.exec(cookieHeader);
+    if (match?.[1] && constantTimeEqual(match[1], expectedToken)) {
+        return true;
+    }
+    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;
+}
+// ---------------------------------------------------------------------------
+// API handlers
+// ---------------------------------------------------------------------------
+function rangeToInterval(range) {
+    switch (range) {
+        case '6h':
+            return '6 hours';
+        case '24h':
+            return '24 hours';
+        case '7d':
+            return '7 days';
+        default:
+            return '1 hour';
+    }
+}
+async function apiLatency(res, pool, params) {
+    const range = params.get('range') ?? '1h';
+    const interval = rangeToInterval(range);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN READ ONLY');
+        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        const result = await client.query(`SELECT bucket, SUM(count) as count,
+              SUM(avg_ms * count) / NULLIF(SUM(count), 0) as avg_ms,
+              MAX(p95_ms) as p95_ms,
+              MAX(p99_ms) as p99_ms
+       FROM _turbine_metrics
+       WHERE bucket >= NOW() - $1::interval
+       GROUP BY bucket
+       ORDER BY bucket`, [interval]);
+        await client.query('COMMIT');
+        sendJson(res, 200, result.rows);
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+async function apiModels(res, pool, params) {
+    const range = params.get('range') ?? '1h';
+    const interval = rangeToInterval(range);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN READ ONLY');
+        await client.query(`SET LOCAL statement_timeout = '30s'`);
+        const result = await client.query(`SELECT model, action,
+              SUM(count)::int as count,
+              SUM(avg_ms * count) / NULLIF(SUM(count), 0) as avg_ms,
+              MAX(p95_ms) as p95_ms,
+              MAX(p99_ms) as p99_ms,
+              SUM(error_count)::int as error_count
+       FROM _turbine_metrics
+       WHERE bucket >= NOW() - $1::interval
+       GROUP BY model, action
+       ORDER BY MAX(p95_ms) DESC
+       LIMIT 50`, [interval]);
+        await client.query('COMMIT');
+        sendJson(res, 200, result.rows);
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch { }
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+    finally {
+        client.release();
+    }
+}
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+const SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",
+};
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'application/json' });
+    res.end(payload);
+}
+function sendHtml(res, status, html) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+}
+function sendText(res, status, text) {
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/plain' });
+    res.end(text);
+}
+// ---------------------------------------------------------------------------
+// Browser open
+// ---------------------------------------------------------------------------
+function openUrl(url) {
+    const { platform: os } = process;
+    const { spawn } = require('node:child_process');
+    try {
+        if (os === 'darwin')
+            spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+        else if (os === 'win32')
+            spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+        else
+            spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        // Best effort
+    }
+}
+//# sourceMappingURL=observe.js.map

package/dist/cli/studio.d.ts

@@ -45,8 +45,16 @@ export interface StudioContext {
     options: StudioOptions;
     authToken: string;
     stateDir: string;
-    /** Resolved statement timeout SQL string (adapter-aware). */
-    statementTimeoutSQL: string;
+    /** Resolved statement timeout (adapter-aware) — parameterized SQL + values. */
+    statementTimeout: {
+        sql: string;
+        params: unknown[];
+    };
+    /** Rate limiter state — tracks requests per authenticated session. */
+    rateLimiter: Map<string, {
+        count: number;
+        resetAt: number;
+    }>;
 }
 /**
  * Start the Studio server. Returns a handle with the session token, a pre-built