@askdb/studio 0.2.0-beta.35 → 0.2.0-beta.36

package/dist/server.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { extname, relative, join, resolve, dirname, sep } from "node:path";
 import { spawn } from "node:child_process";
@@ -11,14 +11,24 @@ import { anthropicProvider } from "@askdb/ai-anthropic";
 import { azureProvider } from "@askdb/ai-azure";
 import { googleProvider } from "@askdb/ai-google";
 import { openaiProvider } from "@askdb/ai-openai";
-import { ask, isBuiltInDialectId, loadSchema, suggestEnrichment, tenantScopeSchema, writeTenantPolicyMarkdown, tenantPolicyFrontmatterSchema, } from "@askdb/core";
+import { ask, formatSensitiveReference, isBuiltInDialectId, loadSchema, schemaHasSensitiveIdentifiers, SqlValidationError, validateSensitiveReferences, suggestEnrichment, tenantScopeSchema, normalizeTenantPolicy, parseTenantPolicyMarkdown, SchemaParseError, writeTenantPolicyMarkdown, tenantPolicyFrontmatterSchema, } from "@askdb/core";
 import { buildSchemaIndex, chunkContentHash, chunkSchema, createAiSdkEmbedder, createFileStore, createMemoryStore, createPgvectorStore, createRetriever, loadChunkerSourcesFromDir, } from "@askdb/rag";
 import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveConcepts, saveTable, } from "@askdb/enrich";
-import { EXECUTE_DRIVER_REGISTRY, isDriverInstalled } from "./execute-registry.js";
+import { EXECUTE_DRIVER_REGISTRY, executeDialectFor, isDriverInstalled, isStudioExecuteProvider, validateExecuteSql, } from "./execute-registry.js";
+import { lockfilePackageManager, packageManagerAddArgs, packageManagerSpawnSpec, } from "./package-manager.js";
 import { resolveStudioIntrospectionPlan, runStudioIntrospection } from "./introspection.js";
 import { probeSetupState, writeSetupConfig, SetupError } from "./setup.js";
+import { checkApiRequest, checkHost, createStudioSessionToken, injectSessionToken, } from "./request-guard.js";
 const ai = createAiRegistry([openaiProvider, azureProvider, googleProvider, anthropicProvider]);
-const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+const DEFAULT_CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
+let clientDirForTests;
+/** @internal Tests only — serve client assets from another directory. */
+export function setStudioClientDirForTests(dir) {
+    clientDirForTests = dir;
+}
+function clientDir() {
+    return clientDirForTests ?? DEFAULT_CLIENT_DIR;
+}
 const STUDIO_RAG_MOCK_DIMENSIONS = 64;
 const STUDIO_RAG_MOCK_EMBEDDER_ID = `studio:mock-lexical-${STUDIO_RAG_MOCK_DIMENSIONS}`;
 const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
@@ -37,11 +47,24 @@ export function createStudioServer(options) {
         workspace: setupReason ? null : loadWorkspace(schemaDir),
         setupReason,
     };
-    return createServer(async (req, res) => {
+    const sessionToken = createStudioSessionToken();
+    const server = createServer(async (req, res) => {
         try {
+            // Host allowlist on every request (static assets included) — defeats DNS rebinding.
+            const hostFailure = checkHost(req, options.host);
+            if (hostFailure) {
+                return writeJson(res, hostFailure.status, { error: { message: hostFailure.message } });
+            }
             const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+            // Origin, session token, and content-type checks on every API call.
+            if (url.pathname.startsWith("/api/")) {
+                const apiFailure = checkApiRequest(req, sessionToken);
+                if (apiFailure) {
+                    return writeJson(res, apiFailure.status, { error: { message: apiFailure.message } });
+                }
+            }
             if (req.method === "GET" && url.pathname === "/") {
-                return serveClientFile(res, "index.html");
+                return serveIndexHtml(res, sessionToken);
             }
             if (req.method === "GET" && url.pathname.startsWith("/assets/")) {
                 return serveClientFile(res, decodeURIComponent(url.pathname.slice(1)));
@@ -165,7 +188,7 @@ export function createStudioServer(options) {
                 return writeJson(res, 200, result);
             }
             if (req.method === "GET" && !url.pathname.startsWith("/api/")) {
-                return serveClientFile(res, "index.html");
+                return serveIndexHtml(res, sessionToken);
             }
             writeJson(res, 404, { error: { message: "Not found" } });
         }
@@ -176,6 +199,7 @@ export function createStudioServer(options) {
             });
         }
     });
+    return Object.assign(server, { sessionToken });
 }
 export function serializeWorkspace(workspace) {
     const rt = getAskDbRuntimeConfig();
@@ -212,6 +236,7 @@ export function serializeWorkspace(workspace) {
                 missingColumnIds: workspace.warnings
                     .filter((warning) => warning.kind === "missing_column_md" && warning.tableId === table.physical.id)
                     .map((warning) => warning.columnId),
+                escalatedByOtherFiles: table.escalatedByOtherFiles ?? [],
             };
         }),
         concepts: workspace.concepts?.frontmatter.concepts ?? [],
@@ -398,8 +423,21 @@ function saveConceptsDraft(state, concepts) {
     state.workspace = loadWorkspace(state.schemaDir);
 }
 function saveTenantPolicy(state, frontmatter, body) {
+    const workspace = requireWorkspace(state);
     const filePath = join(state.schemaDir, "tenant-policy.md");
     const md = writeTenantPolicyMarkdown(frontmatter, body);
+    // Run core's own load-time validation before writing: a policy that `loadSchema` would
+    // reject (e.g. two root labels deriving one placeholder) must not reach disk, or every
+    // later request fails until the file is fixed by hand.
+    try {
+        const physical = workspace.physical;
+        normalizeTenantPolicy(parseTenantPolicyMarkdown(md, filePath), new Set(physical.tables.map((table) => table.id)), new Set(physical.tables.flatMap((table) => table.columns.map((column) => column.id))));
+    }
+    catch (error) {
+        if (error instanceof SchemaParseError)
+            throw new StudioHttpError(400, error.message);
+        throw error;
+    }
     writeFileSync(filePath, md, "utf8");
     state.workspace = loadWorkspace(state.schemaDir);
 }
@@ -419,7 +457,9 @@ function saveDraft(state, tableId, draft) {
     const table = workspace.tables.find((candidate) => candidate.physical.id === tableId);
     if (!table)
         throw new StudioHttpError(404, `No such table: ${tableId}`);
-    const frontmatter = buildFrontmatter(table.physical, workspace.physical.schemaId, draft);
+    // Passing the file's current front-matter keeps entries for other tables' columns
+    // (e.g. a misplaced `sensitive: true`), which the draft does not carry.
+    const frontmatter = buildFrontmatter(table.physical, workspace.physical.schemaId, draft, table.parsed?.frontmatter);
     let body = table.parsed
         ? replaceTableDescription(table.parsed.body, draft.description)
         : buildDefaultTableBody(table.physical.name, draft.description);
@@ -1052,8 +1092,9 @@ function stableTokenHash(token) {
 // ---------------------------------------------------------------------------
 const HISTORY_MAX_STORED = 200;
 const HISTORY_MAX_RETURNED = 50;
+const HISTORY_FILE_NAME = "playground-history.json";
 function playgroundHistoryPath(schemaDir) {
-    return join(schemaDir, "playground-history.json");
+    return join(schemaDir, HISTORY_FILE_NAME);
 }
 function readPlaygroundHistory(schemaDir) {
     const raw = readOptionalJson(playgroundHistoryPath(schemaDir));
@@ -1072,8 +1113,59 @@ function appendPlaygroundHistory(schemaDir, entry) {
         timestamp: new Date().toISOString(),
     };
     const updated = [newEntry, ...existing].slice(0, HISTORY_MAX_STORED);
+    ensureSchemaDirGitignore(schemaDir);
     writeFileSync(histPath, JSON.stringify(updated, null, 2), "utf8");
 }
+/**
+ * Keep Playground history (questions + generated SQL, local-only) out of git.
+ * The schema artifact directory is meant to be committed, so Studio makes sure
+ * its `.gitignore` lists `playground-history.json` before writing the file.
+ *
+ * - No `.gitignore` yet: write one that also ignores `.env` files — the same
+ *   rules `askdb init` writes (plan 043) — unless the schema dir is the project
+ *   root, where ignoring `.env` is the project's call, not Studio's.
+ * - Existing `.gitignore` without the entry: append the entry; never rewrite.
+ * - Failure is non-fatal: history still saves.
+ */
+function ensureSchemaDirGitignore(schemaDir) {
+    const gitignorePath = join(schemaDir, ".gitignore");
+    try {
+        if (existsSync(gitignorePath)) {
+            const content = readFileSync(gitignorePath, "utf8");
+            const lines = content.split(/\r?\n/).map((line) => line.trim());
+            if (lines.includes(HISTORY_FILE_NAME) || lines.includes(`/${HISTORY_FILE_NAME}`))
+                return;
+            const separator = content === "" || content.endsWith("\n") ? "" : "\n";
+            appendFileSync(gitignorePath, `${separator}# AskDB Studio Playground history (local only)\n${HISTORY_FILE_NAME}\n`, "utf8");
+            return;
+        }
+        const lines = [
+            "# Written by AskDB Studio.",
+            "#",
+            "# The schema artifact in this directory is meant to be committed: schema.json",
+            "# plus any enrichment you author in Studio. Playground history (your questions",
+            "# and generated SQL) is local only.",
+            HISTORY_FILE_NAME,
+        ];
+        if (!isProjectRootDir(schemaDir)) {
+            lines.push("", "# Credentials: keep API keys and connection strings out of version control", "# even when they live here.", ".env", ".env.*", "!.env.example");
+        }
+        writeFileSync(gitignorePath, `${lines.join("\n")}\n`, "utf8");
+    }
+    catch {
+        // Non-fatal: the history write matters more than this defensive file.
+    }
+}
+function isProjectRootDir(dir) {
+    if (existsSync(join(dir, "package.json")))
+        return true;
+    try {
+        return readdirSync(dir).some((name) => name.startsWith("askdb.config."));
+    }
+    catch {
+        return false;
+    }
+}
 function deletePlaygroundHistoryEntry(schemaDir, id) {
     const histPath = playgroundHistoryPath(schemaDir);
     const raw = readOptionalJson(histPath);
@@ -1087,36 +1179,130 @@ function deletePlaygroundHistoryEntry(schemaDir, id) {
     writeFileSync(histPath, JSON.stringify(filtered, null, 2), "utf8");
     return { ok: true };
 }
+const HISTORY_LIMITS = {
+    question: 4_000,
+    sql: 100_000,
+    explain: 100_000,
+    /** Serialized JSON size for `tenantScope` / `tenantParams`. */
+    json: 20_000,
+    error: 2_000,
+    ragChunkIds: 200,
+    ragChunkId: 512,
+};
+/**
+ * Validate a history entry and copy **only** the known fields — the file is
+ * written inside the schema artifact directory, so nothing unexpected (or
+ * unbounded) from the request body may be persisted.
+ */
 function parsePlaygroundHistoryEntry(body) {
     if (!isRecord(body)) {
         throw new StudioHttpError(400, "Request body must be a JSON object.");
     }
-    if (typeof body.question !== "string" || body.question.trim() === "") {
+    const question = requireBoundedString(body.question, "question", HISTORY_LIMITS.question);
+    if (question.trim() === "") {
         throw new StudioHttpError(400, "`question` is required.");
     }
     if (body.mode !== "full" && body.mode !== "rag") {
         throw new StudioHttpError(400, "`mode` must be `full` or `rag`.");
     }
-    if (typeof body.sqlMode !== "string") {
-        throw new StudioHttpError(400, "`sqlMode` is required.");
+    if (body.sqlMode !== "sql-only" && body.sqlMode !== "sql-params") {
+        throw new StudioHttpError(400, "`sqlMode` must be `sql-only` or `sql-params`.");
     }
-    if (typeof body.sql !== "string") {
-        throw new StudioHttpError(400, "`sql` is required.");
+    const entry = {
+        question,
+        mode: body.mode,
+        sqlMode: body.sqlMode,
+        sql: requireBoundedString(body.sql, "sql", HISTORY_LIMITS.sql),
+    };
+    if (body.explain !== undefined && body.explain !== null) {
+        entry.explain = requireBoundedString(body.explain, "explain", HISTORY_LIMITS.explain);
     }
-    return body;
+    if (body.tenantScope !== undefined && body.tenantScope !== null) {
+        entry.tenantScope = requireBoundedJsonObject(body.tenantScope, "tenantScope");
+    }
+    if (body.tenantParams !== undefined && body.tenantParams !== null) {
+        entry.tenantParams = requireBoundedJsonObject(body.tenantParams, "tenantParams");
+    }
+    if (body.executionResult !== undefined && body.executionResult !== null) {
+        const r = body.executionResult;
+        if (!isRecord(r) ||
+            !isNonNegativeFinite(r.rowCount) ||
+            !isNonNegativeFinite(r.durationMs) ||
+            typeof r.truncated !== "boolean") {
+            throw new StudioHttpError(400, "`executionResult` must be { rowCount: number, durationMs: number, truncated: boolean, error?: string }.");
+        }
+        entry.executionResult = {
+            rowCount: r.rowCount,
+            durationMs: r.durationMs,
+            truncated: r.truncated,
+            ...(r.error !== undefined
+                ? { error: requireBoundedString(r.error, "executionResult.error", HISTORY_LIMITS.error) }
+                : {}),
+        };
+    }
+    if (body.ragChunkIds !== undefined && body.ragChunkIds !== null) {
+        if (!Array.isArray(body.ragChunkIds) ||
+            body.ragChunkIds.length > HISTORY_LIMITS.ragChunkIds ||
+            !body.ragChunkIds.every((id) => typeof id === "string" && id.length <= HISTORY_LIMITS.ragChunkId)) {
+            throw new StudioHttpError(400, `\`ragChunkIds\` must be an array of at most ${HISTORY_LIMITS.ragChunkIds} strings.`);
+        }
+        entry.ragChunkIds = [...body.ragChunkIds];
+    }
+    return entry;
+}
+function requireBoundedString(value, field, maxLength) {
+    if (typeof value !== "string") {
+        throw new StudioHttpError(400, `\`${field}\` must be a string.`);
+    }
+    if (value.length > maxLength) {
+        throw new StudioHttpError(400, `\`${field}\` is too long (max ${maxLength} characters).`);
+    }
+    return value;
+}
+function requireBoundedJsonObject(value, field) {
+    if (!isRecord(value)) {
+        throw new StudioHttpError(400, `\`${field}\` must be a JSON object.`);
+    }
+    if (JSON.stringify(value).length > HISTORY_LIMITS.json) {
+        throw new StudioHttpError(400, `\`${field}\` is too large (max ${HISTORY_LIMITS.json} characters as JSON).`);
+    }
+    return value;
+}
+function isNonNegativeFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
 // ---------------------------------------------------------------------------
 // Execute endpoint helpers
 // ---------------------------------------------------------------------------
+const EXECUTE_DISABLED_MESSAGE = "Studio execute is off. To run generated SQL from the Playground, set `studio.execute.enabled: true` " +
+    "and an execute connection (`studio.execute.databaseUrl`, or `studio.execute.file` for SQLite) in " +
+    "askdb.config.ts, ideally for a read-only database role, then restart Studio.";
+function executeNotConfiguredMessage(exec) {
+    const field = exec.provider === "sqlite" ? "studio.execute.file" : "studio.execute.databaseUrl";
+    const base = `No execute connection configured. Set \`${field}\` in askdb.config.ts (ideally a read-only database role).`;
+    return exec.introspectionConnectionAvailable
+        ? `${base} Studio no longer reuses the introspection connection by default; set \`studio.execute.useIntrospectionConnection: true\` to opt in.`
+        : base;
+}
 async function getExecuteStatus(schemaDir) {
     const rt = getAskDbRuntimeConfig();
-    const { provider, databaseUrl, file } = rt.studio.execute;
+    const exec = rt.studio.execute;
+    const { provider, databaseUrl, file } = exec;
     const def = EXECUTE_DRIVER_REGISTRY[provider];
     const projectRoot = findProjectRoot(schemaDir) ?? schemaDir;
     const installed = isDriverInstalled(def.packageName, projectRoot);
     const connectionKind = provider === "sqlite" ? "file" : "url";
     const configured = connectionKind === "file" ? Boolean(file) : Boolean(databaseUrl);
+    const disabledReason = !exec.enabled
+        ? EXECUTE_DISABLED_MESSAGE
+        : !configured
+            ? executeNotConfiguredMessage(exec)
+            : null;
     return {
+        enabled: exec.enabled,
+        disabledReason,
+        timeoutMs: exec.timeoutMs,
+        maxRows: exec.maxRows,
         provider,
         label: def.label,
         configured,
@@ -1124,50 +1310,44 @@ async function getExecuteStatus(schemaDir) {
         packageName: def.packageName,
         installed,
         installCommand: def.installCommand,
-        canInstallFromStudio: true,
+        canInstallFromStudio: exec.enabled,
         manualInstallReason: null,
     };
 }
 async function installExecuteDriver(body, schemaDir) {
     const rt = getAskDbRuntimeConfig();
-    const configuredProvider = rt.studio.execute.provider;
-    // Accept the configured provider or an explicit allowlisted provider.
-    let provider = configuredProvider;
-    if (isRecord(body) && typeof body.provider === "string") {
-        const requested = body.provider;
-        if (!(requested in EXECUTE_DRIVER_REGISTRY)) {
-            return {
-                ok: false,
-                provider: configuredProvider,
-                packageName: EXECUTE_DRIVER_REGISTRY[configuredProvider].packageName,
-                command: [],
-                error: `Unknown provider: ${body.provider}`,
-                installed: false,
-            };
+    if (!rt.studio.execute.enabled) {
+        throw new StudioHttpError(403, EXECUTE_DISABLED_MESSAGE);
+    }
+    // Accept the configured provider or an explicit allowlisted provider. `Object.hasOwn`
+    // (via isStudioExecuteProvider) rejects inherited keys such as "constructor".
+    let provider = rt.studio.execute.provider;
+    if (isRecord(body) && body.provider !== undefined) {
+        if (!isStudioExecuteProvider(body.provider)) {
+            throw new StudioHttpError(400, `Unknown provider: ${JSON.stringify(body.provider)}. Expected one of: ${Object.keys(EXECUTE_DRIVER_REGISTRY).join(", ")}.`);
         }
-        provider = requested;
+        provider = body.provider;
     }
     const def = EXECUTE_DRIVER_REGISTRY[provider];
-    const { packageManager, command, args, manualReason } = detectPackageManager(schemaDir, def.packageName);
-    if (manualReason) {
+    const detection = detectPackageManager(schemaDir, def.packageName);
+    if (detection.manualReason !== null) {
         return {
             ok: false,
             provider,
             packageName: def.packageName,
             command: [],
-            error: manualReason,
+            error: detection.manualReason,
             installed: false,
         };
     }
-    // Run the install.
-    const { stdout, stderr, code } = await spawnCommand(command, args, schemaDir);
-    const projectRoot = findProjectRoot(schemaDir) ?? schemaDir;
+    const { packageManager, projectRoot, spawnSpec } = detection;
+    const { stdout, stderr, code } = await spawnCommand(spawnSpec, projectRoot);
     const installed = isDriverInstalled(def.packageName, projectRoot);
     return {
         ok: code === 0,
         provider,
         packageName: def.packageName,
-        command: [command, ...args],
+        command: [spawnSpec.command, ...spawnSpec.args],
         stdout,
         stderr,
         error: code !== 0 ? `${packageManager} exited with code ${code}` : undefined,
@@ -1178,50 +1358,17 @@ function detectPackageManager(cwd, packageName) {
     // Walk up from schemaDir to find the project root's lockfile.
     const projectRoot = findProjectRoot(cwd);
     if (!projectRoot) {
-        return {
-            packageManager: "",
-            command: "",
-            args: [],
-            manualReason: `Could not locate a package.json above ${cwd}. Run the install manually.`,
-        };
+        return { manualReason: `Could not locate a package.json above ${cwd}. Run the install manually.` };
     }
-    if (existsSync(join(projectRoot, "pnpm-lock.yaml"))) {
-        return {
-            packageManager: "pnpm",
-            command: "pnpm",
-            args: ["add", packageName],
-            manualReason: null,
-        };
-    }
-    if (existsSync(join(projectRoot, "package-lock.json"))) {
-        return {
-            packageManager: "npm",
-            command: "npm",
-            args: ["install", packageName],
-            manualReason: null,
-        };
-    }
-    if (existsSync(join(projectRoot, "yarn.lock"))) {
-        return {
-            packageManager: "yarn",
-            command: "yarn",
-            args: ["add", packageName],
-            manualReason: null,
-        };
-    }
-    if (existsSync(join(projectRoot, "bun.lockb")) || existsSync(join(projectRoot, "bun.lock"))) {
-        return {
-            packageManager: "bun",
-            command: "bun",
-            args: ["add", packageName],
-            manualReason: null,
-        };
+    const pm = lockfilePackageManager(projectRoot);
+    if (!pm) {
+        return { manualReason: `No recognized lockfile found in ${projectRoot}. Run: pnpm add ${packageName}` };
     }
     return {
-        packageManager: "",
-        command: "",
-        args: [],
-        manualReason: `No recognized lockfile found in ${projectRoot}. Run: pnpm add ${packageName}`,
+        manualReason: null,
+        packageManager: pm,
+        projectRoot,
+        spawnSpec: packageManagerSpawnSpec(pm, packageManagerAddArgs(pm, [packageName])),
     };
 }
 function findProjectRoot(startDir) {
@@ -1236,9 +1383,9 @@ function findProjectRoot(startDir) {
     }
     return null;
 }
-function spawnCommand(command, args, cwd) {
+function spawnCommand(spec, cwd) {
     return new Promise((resolve) => {
-        const proc = spawn(command, args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+        const proc = spawn(spec.command, spec.args, { cwd, shell: spec.shell, stdio: ["ignore", "pipe", "pipe"] });
         const stdoutChunks = [];
         const stderrChunks = [];
         proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
@@ -1257,15 +1404,69 @@ function spawnCommand(command, args, cwd) {
 }
 async function executeQuery(body, schemaDir) {
     const rt = getAskDbRuntimeConfig();
-    const { provider, databaseUrl, file } = rt.studio.execute;
+    const exec = rt.studio.execute;
+    if (!exec.enabled) {
+        throw new StudioHttpError(403, EXECUTE_DISABLED_MESSAGE);
+    }
     if (!isRecord(body) || typeof body.sql !== "string" || body.sql.trim() === "") {
-        return { ok: false, error: "`sql` is required." };
+        throw new StudioHttpError(400, "`sql` is required.");
+    }
+    if (body.params !== undefined && !Array.isArray(body.params)) {
+        throw new StudioHttpError(400, "`params` must be an array.");
+    }
+    const params = body.params ?? [];
+    // Same read-only SELECT guardrail `ask()` applies, for the execute engine's
+    // dialect — rejects multi-statement input, comments, DDL/DML keywords, …
+    // before anything reaches a driver.
+    let sql;
+    try {
+        sql = validateExecuteSql(exec.provider, body.sql, rt.nlToSql.dialect);
+    }
+    catch (error) {
+        if (error instanceof SqlValidationError) {
+            throw new StudioHttpError(400, `SQL rejected by the read-only guardrail (${error.rule}): ${error.message}`);
+        }
+        throw error;
     }
-    const sql = body.sql;
-    const params = Array.isArray(body.params) ? body.params : [];
+    const warnings = sensitiveExecuteWarnings(sql, schemaDir, executeDialectFor(exec.provider, rt.nlToSql.dialect));
     const projectRoot = findProjectRoot(schemaDir) ?? schemaDir;
-    const def = EXECUTE_DRIVER_REGISTRY[provider];
-    return def.execute({ connectionString: databaseUrl, file, sql, params, projectRoot });
+    const def = EXECUTE_DRIVER_REGISTRY[exec.provider];
+    const result = await def.execute({
+        connectionString: exec.databaseUrl,
+        file: exec.file,
+        sql,
+        params,
+        projectRoot,
+        timeoutMs: exec.timeoutMs,
+        maxRows: exec.maxRows,
+    });
+    if (!result.ok && /^No (connection URL|SQLite file path) configured/.test(result.error)) {
+        return { ok: false, error: executeNotConfiguredMessage(exec) };
+    }
+    return result.ok && warnings.length > 0 ? { ...result, warnings } : result;
+}
+/**
+ * Warn (never block) when the SQL references identifiers marked `sensitive` —
+ * the same check `ask()` runs in its default `"warn"` mode. Studio has no
+ * strict-mode setting; hosts that need enforcement call
+ * `validateSensitiveReferences(sql, schema, { mode: "strict" })` themselves.
+ */
+function sensitiveExecuteWarnings(sql, schemaDir, dialect) {
+    let schema;
+    try {
+        schema = loadSchema(schemaDir);
+    }
+    catch {
+        return [];
+    }
+    if (!schemaHasSensitiveIdentifiers(schema))
+        return [];
+    const result = validateSensitiveReferences(sql, schema, { mode: "warn", dialect });
+    if (result.references.length === 0)
+        return [];
+    return [
+        `This query reads identifiers marked sensitive: ${result.references.map(formatSensitiveReference).join(", ")}.`,
+    ];
 }
 function isLoopbackRequest(req) {
     const socket = req.socket;
@@ -1468,11 +1669,36 @@ function sumNullable(values) {
 function readFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
+/** Largest JSON request body Studio accepts. */
+export const MAX_JSON_BODY_BYTES = 1024 * 1024;
+function bodyTooLarge() {
+    return new StudioHttpError(413, `Request body is too large (limit ${MAX_JSON_BODY_BYTES} bytes).`);
+}
 async function readJson(req) {
+    const declared = Number(req.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_JSON_BODY_BYTES) {
+        // Node discards the unread body after the 413 response is sent.
+        throw bodyTooLarge();
+    }
     const chunks = [];
+    let size = 0;
+    let overflow = false;
     for await (const chunk of req) {
-        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        // Keep draining (without buffering) once over the limit, so the client
+        // can read the 413 instead of hitting a reset connection.
+        if (overflow)
+            continue;
+        const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        size += buf.length;
+        if (size > MAX_JSON_BODY_BYTES) {
+            overflow = true;
+            chunks.length = 0;
+            continue;
+        }
+        chunks.push(buf);
     }
+    if (overflow)
+        throw bodyTooLarge();
     if (chunks.length === 0)
         return {};
     try {
@@ -1492,25 +1718,49 @@ function writeText(res, status, contentType, body) {
     });
     res.end(body);
 }
-function serveClientFile(res, relativePath) {
-    const filePath = resolve(CLIENT_DIR, relativePath);
-    const fileRelativeToClientDir = relative(CLIENT_DIR, filePath);
+function resolveClientFile(res, relativePath) {
+    const root = clientDir();
+    const filePath = resolve(root, relativePath);
+    const fileRelativeToClientDir = relative(root, filePath);
     if (fileRelativeToClientDir.startsWith("..") || fileRelativeToClientDir === "") {
-        return writeJson(res, 404, { error: { message: "Not found" } });
+        writeJson(res, 404, { error: { message: "Not found" } });
+        return null;
     }
     if (!existsSync(filePath)) {
-        return writeJson(res, 500, {
+        writeJson(res, 500, {
             error: {
                 message: "Studio client assets are missing. Run `pnpm --filter @askdb/studio build` before starting Studio.",
             },
         });
+        return null;
     }
+    return filePath;
+}
+function serveClientFile(res, relativePath) {
+    const filePath = resolveClientFile(res, relativePath);
+    if (!filePath)
+        return;
     res.writeHead(200, {
         "content-type": contentTypeFor(filePath),
         "cache-control": "no-store",
     });
     res.end(readFileSync(filePath));
 }
+/** Serve the SPA shell with this launch's session token injected. */
+function serveIndexHtml(res, sessionToken) {
+    const filePath = resolveClientFile(res, "index.html");
+    if (!filePath)
+        return;
+    res.writeHead(200, {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+        // The page carries the session token and drives SQL execution — never let
+        // another site frame it (clickjacking).
+        "x-frame-options": "DENY",
+        "content-security-policy": "frame-ancestors 'none'",
+    });
+    res.end(injectSessionToken(readFileSync(filePath, "utf8"), sessionToken));
+}
 function contentTypeFor(path) {
     switch (extname(path)) {
         case ".html":