turbine-orm 0.18.0 → 0.19.1

package/dist/cjs/cli/studio.js

@@ -3,15 +3,20 @@
  * turbine-orm CLI — Studio
  *
  * A local, read-only web UI for browsing databases, exploring relations,
- * and running SELECT queries. Pure Node (built-in `http` module), no
- * runtime dependencies beyond `pg`, bound to 127.0.0.1 only.
+ * and composing queries visually. ORM-native since v0.19: there is no
+ * raw-SQL input surface — the Query tab builds `findMany` args that are
+ * validated against introspected metadata and compiled by QueryInterface
+ * (`/api/builder`). Pure Node (built-in `http` module), no runtime
+ * dependencies beyond `pg`, bound to 127.0.0.1 only.
  *
  * Security model:
  *   • Bind 127.0.0.1 only (never 0.0.0.0 — no LAN exposure)
  *   • Random auth token generated per process, required in Cookie header
- *   • SELECT/WITH-only guard on the query endpoint
+ *   • No SQL input surface at all — every identifier in a builder request is
+ *     validated against the introspected schema; all values are $N params
  *   • Every query runs in a READ ONLY transaction (belt-and-suspenders)
- *   • 30s statement timeout
+ *   • 30s statement timeout via parameterized set_config()
+ *   • Per-session rate limiting, CSP + security headers, cross-origin refusal
  *
  * Not implemented (deliberately): row editing, DDL, destructive operations.
  * Studio is for inspection. Use the CLI, migrate, or raw SQL for writes.
@@ -155,6 +160,13 @@ async function handleRequest(req, res, ctx) {
         sendHtml(res, 200, studio_ui_generated_js_1.STUDIO_HTML);
         return;
     }
+    // Favicon — answered before the auth gate so the browser's automatic request
+    // doesn't 401/404 on every load. No icon body needed (204).
+    if (pathname === '/favicon.ico') {
+        res.writeHead(204, { 'Content-Length': '0' });
+        res.end();
+        return;
+    }
     // API routes — all require auth.
     if (!isAuthorized(req, ctx.authToken)) {
         sendJson(res, 401, { error: 'unauthorized — use the URL printed in the terminal' });
@@ -175,9 +187,6 @@ async function handleRequest(req, res, ctx) {
         const rawName = decodeURIComponent(pathname.slice('/api/tables/'.length));
         return apiTableRows(res, ctx, rawName, url.searchParams);
     }
-    if (pathname === '/api/query' && req.method === 'POST') {
-        return apiQuery(req, res, ctx);
-    }
     if (pathname === '/api/builder' && req.method === 'POST') {
         return apiBuilder(req, res, ctx);
     }
@@ -237,6 +246,15 @@ function constantTimeEqual(a, b) {
     }
     return result === 0;
 }
+/**
+ * Build a helpful "unknown table" error that lists the available tables so the
+ * caller can spot a typo or schema mismatch immediately.
+ */
+function unknownTableMessage(name, ctx) {
+    const available = Object.keys(ctx.metadata.tables);
+    const list = available.length ? available.join(', ') : '(none)';
+    return `[turbine] Unknown table "${name}" in schema "${ctx.options.schema}". Available: ${list}`;
+}
 // ---------------------------------------------------------------------------
 // API: /api/schema
 // ---------------------------------------------------------------------------
@@ -269,7 +287,9 @@ async function apiSchema(res, ctx) {
      WHERE n.nspname = $1 AND c.relkind = 'r'`, [ctx.options.schema]);
     const counts = new Map();
     for (const row of countsResult.rows) {
-        counts.set(row.relname, Number(row.reltuples));
+        // pg_class.reltuples is -1 on PG14+ until a table is ANALYZEd; clamp so the
+        // sidebar never shows a negative estimate.
+        counts.set(row.relname, Math.max(0, Number(row.reltuples)));
     }
     sendJson(res, 200, {
         schema: ctx.options.schema,
@@ -283,7 +303,7 @@ async function apiSchema(res, ctx) {
 async function apiTableRows(res, ctx, rawTableName, params) {
     const table = ctx.metadata.tables[rawTableName];
     if (!table) {
-        sendJson(res, 404, { error: `unknown table: ${rawTableName}` });
+        sendJson(res, 404, { error: unknownTableMessage(rawTableName, ctx) });
         return;
     }
     const limit = clampInt(params.get('limit'), 50, 1, 500);
@@ -378,54 +398,6 @@ function escapeLikePattern(s) {
     return s.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_');
 }
 // ---------------------------------------------------------------------------
-// API: /api/query — read-only SELECT/WITH runner
-// ---------------------------------------------------------------------------
-async function apiQuery(req, res, ctx) {
-    const body = await readJsonBody(req);
-    const rawSql = typeof body?.sql === 'string' ? body.sql.trim() : '';
-    if (!rawSql) {
-        sendJson(res, 400, { error: 'missing sql' });
-        return;
-    }
-    if (rawSql.length > 10_000) {
-        sendJson(res, 400, { error: 'query too long — maximum 10,000 characters allowed' });
-        return;
-    }
-    if (!isReadOnlyStatement(rawSql)) {
-        sendJson(res, 400, {
-            error: 'only SELECT / WITH statements are allowed in Studio — use the CLI for writes',
-        });
-        return;
-    }
-    const client = await ctx.pool.connect();
-    try {
-        await client.query('BEGIN READ ONLY');
-        await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
-        const started = Date.now();
-        const result = await client.query(rawSql);
-        const elapsedMs = Date.now() - started;
-        await client.query('COMMIT');
-        sendJson(res, 200, {
-            columns: result.fields.map((f) => ({ name: f.name, dataTypeID: f.dataTypeID })),
-            rows: result.rows.map((r) => serializeRow(r)),
-            rowCount: result.rowCount ?? result.rows.length,
-            elapsedMs,
-        });
-    }
-    catch (err) {
-        try {
-            await client.query('ROLLBACK');
-        }
-        catch {
-            /* ignore */
-        }
-        sendJson(res, 400, { error: err instanceof Error ? err.message : String(err) });
-    }
-    finally {
-        client.release();
-    }
-}
-// ---------------------------------------------------------------------------
 // API: /api/builder — Turbine ORM findMany spec runner
 // ---------------------------------------------------------------------------
 async function apiBuilder(req, res, ctx) {
@@ -433,7 +405,7 @@ async function apiBuilder(req, res, ctx) {
     const tableName = typeof body?.table === 'string' ? body.table : '';
     const args = (body?.args ?? {});
     if (!tableName || !ctx.metadata.tables[tableName]) {
-        sendJson(res, 400, { error: `unknown table: ${tableName}` });
+        sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
     }
     let deferred;
@@ -453,6 +425,11 @@ async function apiBuilder(req, res, ctx) {
     try {
         await client.query('BEGIN READ ONLY');
         await client.query(ctx.statementTimeout.sql, ctx.statementTimeout.params);
+        // QueryInterface emits unqualified table identifiers, which resolve via
+        // the connection's search_path. Pin it to the configured --schema so the
+        // Query tab reads the same schema as the Data tab (set_config is
+        // transaction-local and fully parameterized).
+        await client.query(`SELECT set_config('search_path', $1, true)`, [ctx.options.schema]);
         const started = Date.now();
         const result = await client.query(deferred.sql, deferred.params);
         const elapsedMs = Date.now() - started;
@@ -481,6 +458,8 @@ async function apiBuilder(req, res, ctx) {
 function savedQueriesPath(ctx) {
     return (0, node_path_1.resolve)(ctx.stateDir, 'studio-queries.json');
 }
+/** One-shot flag so the legacy saved-query notice isn't logged on every request. */
+let legacyDropNoticeShown = false;
 function loadSavedQueries(ctx) {
     const file = savedQueriesPath(ctx);
     if (!(0, node_fs_1.existsSync)(file))
@@ -490,7 +469,17 @@ function loadSavedQueries(ctx) {
         const parsed = JSON.parse(raw);
         if (!parsed.queries || !Array.isArray(parsed.queries))
             return { version: 1, queries: [] };
-        return { version: 1, queries: parsed.queries };
+        // Drop any legacy raw-SQL entries — Studio is builder-only now. Tell the
+        // user instead of silently discarding their saved work (the file on disk
+        // is only rewritten when a new query is saved, so this is recoverable).
+        const queries = parsed.queries.filter((q) => q && q.kind === 'builder');
+        const dropped = parsed.queries.length - queries.length;
+        if (dropped > 0 && !legacyDropNoticeShown) {
+            legacyDropNoticeShown = true;
+            console.warn(`[turbine studio] Ignoring ${dropped} legacy raw-SQL saved quer${dropped === 1 ? 'y' : 'ies'} in ${file} — ` +
+                'Studio is builder-only since v0.19. The entries remain in the file until a new query is saved.');
+        }
+        return { version: 1, queries };
     }
     catch {
         return { version: 1, queries: [] };
@@ -513,27 +502,17 @@ async function apiCreateSavedQuery(req, res, ctx) {
     const body = await readJsonBody(req);
     const table = typeof body?.table === 'string' ? body.table : '';
     const name = typeof body?.name === 'string' ? body.name.trim() : '';
-    const kind = body?.kind === 'builder' ? 'builder' : body?.kind === 'sql' ? 'sql' : null;
     if (!table || !ctx.metadata.tables[table]) {
-        sendJson(res, 400, { error: `unknown table: ${table}` });
+        sendJson(res, 400, { error: unknownTableMessage(table, ctx) });
         return;
     }
     if (!name) {
         sendJson(res, 400, { error: 'name is required' });
         return;
     }
-    if (!kind) {
-        sendJson(res, 400, { error: 'kind must be "sql" or "builder"' });
-        return;
-    }
-    const sql = kind === 'sql' && typeof body?.sql === 'string' ? body.sql : undefined;
-    const args = kind === 'builder' ? body?.args : undefined;
-    if (kind === 'sql' && !sql) {
-        sendJson(res, 400, { error: 'sql is required for kind=sql' });
-        return;
-    }
-    if (kind === 'sql' && sql && !isReadOnlyStatement(sql)) {
-        sendJson(res, 400, { error: 'saved sql must be SELECT/WITH only' });
+    // Studio only persists visual-builder queries (no raw SQL surface).
+    if (body?.kind !== 'builder') {
+        sendJson(res, 400, { error: 'kind must be "builder"' });
         return;
     }
     const data = loadSavedQueries(ctx);
@@ -541,9 +520,8 @@ async function apiCreateSavedQuery(req, res, ctx) {
         id: (0, node_crypto_1.randomUUID)(),
         table,
         name,
-        kind,
-        sql,
-        args,
+        kind: 'builder',
+        args: body?.args,
         createdAt: new Date().toISOString(),
     };
     data.queries.push(entry);

package/dist/cjs/client.js

@@ -210,6 +210,14 @@ class TurbineClient {
     /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
     activeSubscriptions = new Set();
     constructor(config = {}, schema) {
+        // Constructing without schema metadata previously crashed deep in the
+        // constructor with an opaque "Cannot read properties of undefined
+        // (reading 'tables')". Fail fast with an actionable message instead.
+        if (!schema || typeof schema !== 'object' || !schema.tables) {
+            throw new errors_js_1.ValidationError('[turbine] TurbineClient requires schema metadata as its second argument. ' +
+                'Run `npx turbine generate` and use the generated client (`turbine()` from your output dir), ' +
+                'or pass the generated `schemaMetadata` object: new TurbineClient(config, schemaMetadata).');
+        }
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).