@askdb/studio 0.2.0-beta.37 → 0.2.0-beta.39

package/dist/server.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { createServer } from "node:http";
 import { extname, relative, join, resolve, dirname, sep } from "node:path";
 import { spawn } from "node:child_process";
@@ -7,9 +7,9 @@ import { fileURLToPath } from "node:url";
 import { generateText as defaultGenerateText } from "ai";
 import { ASKDB_AI_PROVIDERS, bootstrapAskDbEnv, getAskDbRuntimeConfig, } from "@askdb/config";
 import { createAiRegistry, resolveReasoningEffort, } from "@askdb/ai";
-import { ask, formatSensitiveReference, isBuiltInDialectId, loadSchema, schemaHasSensitiveIdentifiers, SqlValidationError, validateSensitiveReferences, suggestEnrichment, tenantScopeSchema, normalizeTenantPolicy, parseTenantPolicyMarkdown, SchemaParseError, writeTenantPolicyMarkdown, tenantPolicyFrontmatterSchema, } from "@askdb/core";
+import { ask, DEFAULT_TENANT_SQL_MODE, formatSchemaV2ForNlToSql, formatSensitiveReference, isBuiltInDialectId, loadSchema, saveSchemaFile, schemaHasSensitiveIdentifiers, SensitiveEnrichmentTargetError, SqlValidationError, validateSensitiveReferences, suggestEnrichment, tenantScopeSchema, SchemaParseError, tenantPolicyFrontmatterSchema, } from "@askdb/core";
 import { buildSchemaIndex, chunkContentHash, chunkSchema, aiSdkEmbedderId, createAiSdkEmbedder, createFileStore, createMemoryStore, createPgvectorStore, createRetriever, detectEmbeddingDimensions, loadChunkerSourcesFromDir, PgvectorDimensionMismatchError, } from "@askdb/rag";
-import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveConcepts, saveTable, } from "@askdb/enrich";
+import { buildDefaultTableBody, buildFrontmatter, buildSuggestionContext, buildSuggestionTarget, buildTableDraft, loadWorkspace, replaceH2Section, replaceTableDescription, saveConcepts, saveTable, saveTenantPolicy, } from "@askdb/enrich";
 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";
@@ -97,7 +97,7 @@ export function createStudioServer(options) {
             }
             if (req.method === "GET" && url.pathname === "/api/introspect/status") {
                 requireWorkspace(state);
-                return writeJson(res, 200, buildIntrospectionPlanDto());
+                return writeJson(res, 200, await buildIntrospectionPlanDto());
             }
             if (req.method === "POST" && url.pathname === "/api/introspect") {
                 if (!isLoopbackRequest(req)) {
@@ -122,7 +122,7 @@ export function createStudioServer(options) {
             if (req.method === "POST" && url.pathname === "/api/tenant-policy") {
                 const body = await readJson(req);
                 const { frontmatter, bodyText } = parseTenantPolicyBody(body);
-                saveTenantPolicy(state, frontmatter, bodyText);
+                saveTenantPolicyDraft(state, frontmatter, bodyText);
                 return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
             }
             if (req.method === "POST" && url.pathname === "/api/suggest-tenant-policy") {
@@ -132,7 +132,7 @@ export function createStudioServer(options) {
             if (req.method === "POST" && url.pathname === "/api/suggest") {
                 const body = await readJson(req);
                 const source = parseSuggestSource(body);
-                const candidates = await suggestForSource(requireWorkspace(state), source);
+                const candidates = await suggestForSource(state, source);
                 return writeJson(res, 200, { candidates });
             }
             if (req.method === "GET" && url.pathname === "/api/rag/status") {
@@ -360,8 +360,8 @@ async function handleResync(state) {
         workspace: serializeWorkspace(state.workspace),
     };
 }
-function buildIntrospectionPlanDto() {
-    const plan = resolveStudioIntrospectionPlan();
+async function buildIntrospectionPlanDto() {
+    const plan = await resolveStudioIntrospectionPlan();
     return plan.ok
         ? { ok: true, engine: plan.engine, sourceLabel: plan.sourceLabel }
         : { ok: false, engine: plan.engine, error: plan.error };
@@ -421,23 +421,17 @@ function saveConceptsDraft(state, concepts) {
     saveConcepts(requireWorkspace(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.
+function saveTenantPolicyDraft(state, frontmatter, body) {
+    // `saveTenantPolicy` refuses a policy `loadSchema` would reject (e.g. two root labels
+    // deriving one placeholder) before writing; that's the caller's mistake, so 400.
     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))));
+        saveTenantPolicy(requireWorkspace(state), frontmatter, body);
     }
     catch (error) {
         if (error instanceof SchemaParseError)
             throw new StudioHttpError(400, error.message);
         throw error;
     }
-    writeFileSync(filePath, md, "utf8");
     state.workspace = loadWorkspace(state.schemaDir);
 }
 function parseTenantPolicyBody(body) {
@@ -471,7 +465,7 @@ function saveDraft(state, tableId, draft) {
     saveTable(workspace, tableId, frontmatter, body);
     state.workspace = loadWorkspace(state.schemaDir);
 }
-async function suggestForSource(workspace, source) {
+async function suggestForSource(state, source) {
     const rt = getAskDbRuntimeConfig();
     const aiConfig = ai.resolveAiConfig(rt.ai.aiEnv);
     if (!aiConfig) {
@@ -482,37 +476,108 @@ async function suggestForSource(workspace, source) {
     const providerOptions = reasoningEffort
         ? ai.resolveProviderOptions(aiConfig, { reasoningEffort })
         : undefined;
-    const candidates = await suggestEnrichment(buildSuggestionTarget(workspace, source), buildSuggestionContext(workspace, source.tableId), model, providerOptions ? { providerOptions } : undefined);
+    // `loadSchema()` carries effective sensitivity (front-matter escalations included), and the
+    // prompt follows `modes.omitSensitiveFromPrompt` as `ask()` does (#625, ADR 0026).
+    requireWorkspace(state);
+    const schema = loadSchema(state.schemaDir);
+    let candidates;
+    try {
+        candidates = await suggestEnrichment(buildSuggestionTarget(schema, source), buildSuggestionContext(schema, source.tableId), model, {
+            omitSensitiveIdentifiersFromPrompt: rt.modes.omitSensitiveFromPrompt,
+            ...(providerOptions ? { providerOptions } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof SensitiveEnrichmentTargetError) {
+            throw new StudioHttpError(400, "This column is sensitive, and `modes.omitSensitiveFromPrompt` keeps sensitive columns out of the model's prompt, so Studio can't suggest for it.");
+        }
+        throw error;
+    }
     return candidates.map((candidate) => ({ text: candidate.text }));
 }
+/**
+ * The schema as the tenant-policy draft sends it to the model, with the sensitivity rules
+ * `ask()` applies (#324): `formatSchemaV2ForNlToSql` tags sensitive columns, or withholds
+ * them when `omitSensitive` is on. Only the physical layer goes in (names, types, keys and
+ * foreign keys), never descriptions, aliases or common query language, and untracked tables
+ * stay out as they do for `ask()`. A foreign key is listed only when both of its columns are.
+ * `warnings` names the primary and foreign keys withheld as sensitive, which the draft can't
+ * scope through.
+ */
+function tenantPolicySchemaForPrompt(schema, omitSensitive) {
+    const tracked = schema.tables.filter((table) => table.tracked !== false);
+    const physical = {
+        schemaId: schema.schemaId,
+        warnings: [],
+        tables: tracked.map((table) => ({
+            id: table.id,
+            name: table.name,
+            schema: table.schema,
+            sensitive: table.sensitive,
+            columns: table.columns.map((column) => ({
+                id: column.id,
+                name: column.name,
+                type: column.type,
+                nullable: column.nullable,
+                primaryKey: column.primaryKey,
+                sensitive: column.sensitive,
+            })),
+        })),
+    };
+    const { ddl } = formatSchemaV2ForNlToSql(physical, { omitSensitiveIdentifiersFromPrompt: omitSensitive });
+    // The formatter prints no foreign keys yet, so Studio lists them, mirroring the formatter's
+    // omission rule (packages/core/src/schema/v2/format.ts): a column is withheld when omission
+    // is on and it is sensitive, which `loadSchema()` sets on every column of a sensitive table.
+    // When core prints foreign keys (#349, step 5), use its lines and delete this block (ADR 0021).
+    const names = new Map();
+    const withheld = new Set();
+    for (const table of schema.tables) {
+        for (const column of table.columns) {
+            names.set(column.id, `${table.schema}.${table.name}.${column.name}`);
+            if (omitSensitive && column.sensitive)
+                withheld.add(column.id);
+        }
+    }
+    const nameOf = (id) => names.get(id) ?? id;
+    const listed = new Set();
+    const withheldKeys = [];
+    for (const table of tracked) {
+        for (const column of table.columns) {
+            if (!withheld.has(column.id))
+                listed.add(column.id);
+            else if (column.primaryKey)
+                withheldKeys.push(`${nameOf(column.id)} (primary key)`);
+        }
+    }
+    const foreignKeys = [];
+    for (const fk of tracked.flatMap((table) => table.relationships ?? [])) {
+        if (listed.has(fk.from) && listed.has(fk.to))
+            foreignKeys.push(`- ${fk.from} -> ${fk.to}`);
+        else if (withheld.has(fk.from) || withheld.has(fk.to)) {
+            withheldKeys.push(`${nameOf(fk.from)} → ${nameOf(fk.to)} (foreign key)`);
+        }
+    }
+    const warnings = withheldKeys.length > 0
+        ? [
+            `Withheld from the model because they're marked sensitive: ${withheldKeys.join(", ")}. ` +
+                "If any of them carries tenant scope, add it to the policy by hand.",
+        ]
+        : [];
+    return {
+        schemaId: schema.schemaId,
+        schemaDdl: foreignKeys.length > 0 ? `${ddl}\n\nForeign keys:\n${foreignKeys.join("\n")}` : ddl,
+        tableIds: tracked.map((table) => table.id),
+        warnings,
+    };
+}
 async function suggestTenantPolicyDraft(state) {
     const rt = getAskDbRuntimeConfig();
     const model = await ai.createLanguageModelFromEnv(rt.ai.aiEnv);
     if (!model) {
         throw new StudioHttpError(400, ai.keyMissingMessage("AI tenant policy suggestion"));
     }
-    // Build a compact DDL-like representation of the schema for the prompt
-    const workspace = requireWorkspace(state);
-    const schemaId = workspace.physical.schemaId;
-    const schemaDdl = workspace.tables
-        .map((t) => {
-        const cols = t.physical.columns
-            .map((c) => {
-            const parts = [c.name, c.type];
-            if (c.primaryKey)
-                parts.push("PRIMARY KEY");
-            if (!c.nullable)
-                parts.push("NOT NULL");
-            return `  ${parts.join(" ")}`;
-        })
-            .join(",\n");
-        const rels = (t.physical.relationships ?? [])
-            .map((r) => `  -- FK: ${r.from} -> ${r.to}`)
-            .join("\n");
-        return `CREATE TABLE ${t.physical.schema}.${t.physical.name} (\n${cols}\n);\n${rels}`.trim();
-    })
-        .join("\n\n");
-    const tableIds = workspace.tables.map((t) => t.physical.id);
+    requireWorkspace(state);
+    const { schemaId, schemaDdl, tableIds, warnings } = tenantPolicySchemaForPrompt(loadSchema(state.schemaDir), rt.modes.omitSensitiveFromPrompt);
     const systemPrompt = `You are an expert database architect specializing in multi-tenant SaaS systems.
 You analyze database schemas and produce a tenant-policy configuration in a specific JSON format.
 
@@ -571,15 +636,14 @@ If the schema has no clear multi-tenant pattern, still make your best guess at w
     if (!validation.success) {
         throw new StudioHttpError(500, `AI-generated tenant policy frontmatter is invalid: ${validation.error.issues.map((i) => i.message).join("; ")}`);
     }
-    parsed.frontmatter = validation.data;
-    return parsed;
+    return { frontmatter: validation.data, body: parsed.body, warnings };
 }
 async function askSampleQuestion(state, options) {
     const rt = getAskDbRuntimeConfig();
     const mockSql = rt.dev.mockSql;
     const aiConfig = mockSql ? undefined : ai.resolveAiConfig(rt.ai.aiEnv);
     if (!mockSql && !aiConfig) {
-        throw new StudioHttpError(400, `${ai.keyMissingMessage("Sample NL-to-SQL generation")} Set ASKDB_MOCK_SQL to bypass the live model.`);
+        throw new StudioHttpError(400, `${ai.keyMissingMessage("Sample NL-to-SQL generation")} Set dev.mockSql in askdb.config to bypass the live model.`);
     }
     const reasoningEffort = mockSql ? undefined : resolveReasoningEffort(rt.ai.aiEnv, "nlToSql");
     const providerOptions = aiConfig && reasoningEffort ? ai.resolveProviderOptions(aiConfig, { reasoningEffort }) : undefined;
@@ -603,6 +667,9 @@ async function askSampleQuestion(state, options) {
         model,
         dialect,
         explain: true,
+        // `ask()` doesn't read config, so each host applies `modes.omitSensitiveFromPrompt`
+        // itself, as `@askdb/client` does (#601).
+        ...(rt.modes.omitSensitiveFromPrompt ? { omitSensitiveIdentifiersFromNlToSqlPrompt: true } : {}),
         ...(options.tenantScope ? { tenantScope: options.tenantScope } : {}),
         ...(options.tenantSqlMode ? { tenantSqlMode: options.tenantSqlMode } : {}),
         ...(ragIndex
@@ -645,7 +712,7 @@ async function askSampleQuestion(state, options) {
         tenant: options.tenantScope
             ? {
                 enabled: true,
-                sqlMode: options.tenantSqlMode ?? "sql-only",
+                sqlMode: options.tenantSqlMode ?? DEFAULT_TENANT_SQL_MODE,
                 bindings: result.tenantBindings ?? [],
                 params: result.tenantParams ?? [],
             }
@@ -1118,7 +1185,7 @@ function appendPlaygroundHistory(schemaDir, entry) {
     };
     const updated = [newEntry, ...existing].slice(0, HISTORY_MAX_STORED);
     ensureSchemaDirGitignore(schemaDir);
-    writeFileSync(histPath, JSON.stringify(updated, null, 2), "utf8");
+    saveSchemaFile(schemaDir, HISTORY_FILE_NAME, JSON.stringify(updated, null, 2));
 }
 /**
  * Keep Playground history (questions + generated SQL, local-only) out of git.
@@ -1128,19 +1195,25 @@ function appendPlaygroundHistory(schemaDir, entry) {
  * - 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.
+ * - Existing `.gitignore` without the entry: add the entry at the end and keep
+ *   every existing byte as it was.
+ * - Both are saved with `saveSchemaFile()`, so a `.gitignore` that is a symbolic
+ *   link is refused, not written through (ADR 0028).
  * - 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());
+            // Kept as bytes: Git matches patterns byte for byte, and a non-UTF-8 file name
+            // in an existing line must survive the rewrite.
+            const content = readFileSync(gitignorePath);
+            const lines = content.toString("utf8").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");
+            const separator = content.length === 0 || content.at(-1) === 0x0a ? "" : "\n";
+            const entry = `${separator}# AskDB Studio Playground history (local only)\n${HISTORY_FILE_NAME}\n`;
+            saveSchemaFile(schemaDir, ".gitignore", Buffer.concat([content, Buffer.from(entry, "utf8")]));
             return;
         }
         const lines = [
@@ -1154,7 +1227,7 @@ function ensureSchemaDirGitignore(schemaDir) {
         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");
+        saveSchemaFile(schemaDir, ".gitignore", `${lines.join("\n")}\n`);
     }
     catch {
         // Non-fatal: the history write matters more than this defensive file.
@@ -1180,7 +1253,7 @@ function deletePlaygroundHistoryEntry(schemaDir, id) {
     if (filtered.length === existing.length) {
         return { ok: false, error: "not found" };
     }
-    writeFileSync(histPath, JSON.stringify(filtered, null, 2), "utf8");
+    saveSchemaFile(schemaDir, HISTORY_FILE_NAME, JSON.stringify(filtered, null, 2));
     return { ok: true };
 }
 const HISTORY_LIMITS = {