@askdb/studio 0.2.0-beta.27 → 0.2.0-beta.29

package/dist/client/index.html

@@ -6,7 +6,7 @@
     <title>AskDB Studio</title>
     <link rel="icon" type="image/png" media="(prefers-color-scheme: light)" href="/assets/brand/light-icon.png" />
     <link rel="icon" type="image/png" media="(prefers-color-scheme: dark)" href="/assets/brand/dark-icon.png" />
-    <script type="module" crossorigin src="/assets/index-DYBXDl3K.js"></script>
+    <script type="module" crossorigin src="/assets/index-BgdvYJyR.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Bj6qGfT6.css">
   </head>
   <body>

package/dist/introspection.d.ts

@@ -0,0 +1,35 @@
+import { type ConnectorProvider } from "@askdb/connectors";
+export type StudioIntrospectionPlan = {
+    ok: true;
+    engine: ConnectorProvider;
+    sourceLabel: string;
+} | {
+    ok: false;
+    engine: ConnectorProvider | null;
+    error: string;
+};
+/**
+ * Resolve what a server-side introspection run would do, from the runtime
+ * config alone. Mirrors the CLI's flag-free resolution in
+ * `apps/cli/src/introspect.ts` (config provider + per-engine connection).
+ * Never includes credentials in `sourceLabel` — it is shown in the UI.
+ */
+export declare function resolveStudioIntrospectionPlan(): StudioIntrospectionPlan;
+export type StudioIntrospectionRun = {
+    engine: ConnectorProvider;
+    schemaId: string;
+    tables: number;
+    warnings: string[];
+};
+/**
+ * Run introspection server-side into `outDir`, preserving any existing
+ * enrichment markdown (the writer keeps `tables/*.md`, `concepts.md`, and
+ * `tenant-policy.md` when `existingArtifactDir` is supplied — the same
+ * guarantee `askdb introspect` gives).
+ */
+export declare function runStudioIntrospection(options: {
+    outDir: string;
+    schemaId?: string;
+    hasExistingArtifact: boolean;
+}): Promise<StudioIntrospectionRun>;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../src/introspection.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAC;AAe3B,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,wBAAgB,8BAA8B,IAAI,uBAAuB,CASxE;AA4ED,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,OAAO,CAAC;CAC9B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAkClC"}

package/dist/introspection.js

@@ -0,0 +1,138 @@
+import { basename } from "node:path";
+import { getAskDbRuntimeConfig } from "@askdb/config";
+import { introspect, } from "@askdb/introspect";
+import { createConnectorRegistry, } from "@askdb/connectors";
+import { postgresConnectorProvider } from "@askdb/postgres";
+import { mysqlConnectorProvider } from "@askdb/mysql";
+import { sqliteConnectorProvider } from "@askdb/sqlite";
+import { sqlServerConnectorProvider } from "@askdb/sqlserver";
+import { prismaConnectorProvider } from "@askdb/prisma";
+const connectorRegistry = createConnectorRegistry([
+    postgresConnectorProvider,
+    mysqlConnectorProvider,
+    sqliteConnectorProvider,
+    sqlServerConnectorProvider,
+    prismaConnectorProvider,
+]);
+/**
+ * Resolve what a server-side introspection run would do, from the runtime
+ * config alone. Mirrors the CLI's flag-free resolution in
+ * `apps/cli/src/introspect.ts` (config provider + per-engine connection).
+ * Never includes credentials in `sourceLabel` — it is shown in the UI.
+ */
+export function resolveStudioIntrospectionPlan() {
+    const rt = getAskDbRuntimeConfig();
+    const engine = rt.introspection.provider;
+    if (!connectorRegistry.hasProvider(engine)) {
+        return { ok: false, engine: null, error: `Unsupported introspection provider: ${engine}` };
+    }
+    const connection = resolveConnection(engine);
+    if (!connection.ok)
+        return { ok: false, engine, error: connection.error };
+    return { ok: true, engine, sourceLabel: connection.sourceLabel };
+}
+function resolveConnection(engine) {
+    const rt = getAskDbRuntimeConfig();
+    switch (engine) {
+        case "postgres": {
+            const url = rt.introspection.postgresDatabaseUrl;
+            if (!url) {
+                return {
+                    ok: false,
+                    error: "No Postgres connection configured. Set introspection.providerConfig.postgres.databaseUrl in askdb.config.ts (bound to an env var in .env).",
+                };
+            }
+            return { ok: true, url, sourceLabel: redactUrl(url) };
+        }
+        case "mysql": {
+            const url = rt.introspection.mysqlDatabaseUrl;
+            if (!url) {
+                return {
+                    ok: false,
+                    error: "No MySQL connection configured. Set introspection.providerConfig.mysql.databaseUrl in askdb.config.ts (bound to an env var in .env).",
+                };
+            }
+            return { ok: true, url, sourceLabel: redactUrl(url) };
+        }
+        case "sqlserver": {
+            const url = rt.introspection.sqlserverDatabaseUrl;
+            if (!url) {
+                return {
+                    ok: false,
+                    error: "No SQL Server connection configured. Set introspection.providerConfig.sqlserver.databaseUrl in askdb.config.ts (bound to an env var in .env).",
+                };
+            }
+            return { ok: true, url, sourceLabel: redactUrl(url) };
+        }
+        case "sqlite": {
+            const file = rt.introspection.sqliteFile;
+            if (!file) {
+                return {
+                    ok: false,
+                    error: "No SQLite file configured. Set introspection.providerConfig.sqlite.file in askdb.config.ts.",
+                };
+            }
+            return { ok: true, url: file, sourceLabel: file };
+        }
+        case "prisma": {
+            // When unset, @askdb/prisma auto-discovers prisma/schema.prisma in the project root.
+            const schemaPath = rt.introspection.prismaSchemaPath;
+            return {
+                ok: true,
+                schemaPath,
+                sourceLabel: schemaPath ?? "auto-discovered prisma/schema.prisma",
+            };
+        }
+    }
+}
+/** Strip credentials from a connection string for display (never shown raw in the UI). */
+function redactUrl(raw) {
+    try {
+        const url = new URL(raw);
+        return `${url.protocol}//${url.host}${url.pathname}`;
+    }
+    catch {
+        // ADO.NET-style or otherwise unparseable — show only that it is configured.
+        return "configured connection";
+    }
+}
+/**
+ * Run introspection server-side into `outDir`, preserving any existing
+ * enrichment markdown (the writer keeps `tables/*.md`, `concepts.md`, and
+ * `tenant-policy.md` when `existingArtifactDir` is supplied — the same
+ * guarantee `askdb introspect` gives).
+ */
+export async function runStudioIntrospection(options) {
+    const plan = resolveStudioIntrospectionPlan();
+    if (!plan.ok)
+        throw new Error(plan.error);
+    const connection = resolveConnection(plan.engine);
+    if (!connection.ok)
+        throw new Error(connection.error);
+    const schemaId = options.schemaId ?? inferSchemaId(options.outDir);
+    const connectorConfig = {
+        provider: plan.engine,
+        url: connection.url,
+        schemaPath: connection.schemaPath,
+        schemaId,
+    };
+    const runConfig = connectorRegistry.createConnector(connectorConfig);
+    const connector = runConfig.connector;
+    const result = await introspect(runConfig.input, {
+        outDir: options.outDir,
+        schemaId,
+        existingArtifactDir: options.hasExistingArtifact ? options.outDir : undefined,
+    }, { connector });
+    return {
+        engine: plan.engine,
+        schemaId,
+        tables: result.schema.schemas.reduce((sum, namespace) => sum + namespace.tables.length, 0),
+        warnings: result.warnings.map((warning) => typeof warning === "string" ? warning : JSON.stringify(warning)),
+    };
+}
+function inferSchemaId(path) {
+    const name = basename(path);
+    const inferred = name.endsWith(".schema") ? name.slice(0, -".schema".length) : name;
+    return inferred || "introspected";
+}
+//# sourceMappingURL=introspection.js.map

package/dist/introspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.js","sourceRoot":"","sources":["../src/introspection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACL,UAAU,GAGX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,GAGxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,MAAM,iBAAiB,GAAG,uBAAuB,CAAC;IAChD,yBAAyB;IACzB,sBAAsB;IACtB,uBAAuB;IACvB,0BAA0B;IAC1B,uBAAuB;CACxB,CAAC,CAAC;AAMH;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B;IAC5C,MAAM,EAAE,GAAG,qBAAqB,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC,QAA6B,CAAC;IAC9D,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,uCAAuC,MAAM,EAAE,EAAE,CAAC;IAC7F,CAAC;IACD,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,UAAU,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC;AACnE,CAAC;AAMD,SAAS,iBAAiB,CAAC,MAAyB;IAClD,MAAM,EAAE,GAAG,qBAAqB,EAAE,CAAC;IACnC,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,GAAG,GAAG,EAAE,CAAC,aAAa,CAAC,mBAAmB,CAAC;YACjD,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EACH,4IAA4I;iBAC/I,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,GAAG,GAAG,EAAE,CAAC,aAAa,CAAC,gBAAgB,CAAC;YAC9C,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EACH,sIAAsI;iBACzI,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,CAAC;QACD,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,MAAM,GAAG,GAAG,EAAE,CAAC,aAAa,CAAC,oBAAoB,CAAC;YAClD,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EACH,+IAA+I;iBAClJ,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,IAAI,GAAG,EAAE,CAAC,aAAa,CAAC,UAAU,CAAC;YACzC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,KAAK,EACH,6FAA6F;iBAChG,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QACpD,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,qFAAqF;YACrF,MAAM,UAAU,GAAG,EAAE,CAAC,aAAa,CAAC,gBAAgB,CAAC;YACrD,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,UAAU;gBACV,WAAW,EAAE,UAAU,IAAI,sCAAsC;aAClE,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,OAAO,uBAAuB,CAAC;IACjC,CAAC;AACH,CAAC;AASD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAI5C;IACC,MAAM,IAAI,GAAG,8BAA8B,EAAE,CAAC;IAC9C,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,UAAU,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,MAAM,eAAe,GAAoB;QACvC,QAAQ,EAAE,IAAI,CAAC,MAAM;QACrB,GAAG,EAAE,UAAU,CAAC,GAAG;QACnB,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,QAAQ;KACT,CAAC;IACF,MAAM,SAAS,GAAG,iBAAiB,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,SAAS,CAAC,SAA+B,CAAC;IAE5D,MAAM,MAAM,GAAqB,MAAM,UAAU,CAC/C,SAAS,CAAC,KAAK,EACf;QACE,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ;QACR,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;KAC9E,EACD,EAAE,SAAS,EAAE,CACd,CAAC;IAEF,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ;QACR,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1F,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACxC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAChE;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpF,OAAO,QAAQ,IAAI,cAAc,CAAC;AACpC,CAAC"}

package/dist/server.d.ts

@@ -1,11 +1,18 @@
 import { createServer } from "node:http";
 import { createPgvectorStore } from "@askdb/rag";
 import { type Workspace } from "@askdb/enrich";
-import type { StudioWorkspaceDto } from "./shared/api.js";
+import type { SetupReason, StudioWorkspaceDto } from "./shared/api.js";
 export type StudioOptions = {
     schema: string;
     host?: string;
     port?: number;
+    /**
+     * Start in setup mode instead of failing: `"no-config"` when no
+     * `askdb.config.*` was found, `"no-artifact"` when the config exists but the
+     * schema artifact hasn't been introspected yet. The browser wizard walks the
+     * user through the missing steps and flips the server to ready.
+     */
+    setupReason?: SetupReason | null;
 };
 export type StudioServer = ReturnType<typeof createServer>;
 export declare function setStudioPgvectorStoreFactoryForTests(factory: typeof createPgvectorStore | undefined): void;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAA6C,MAAM,WAAW,CAAC;AA+BpF,OAAO,EAOL,mBAAmB,EAOpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAaL,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAYV,kBAAkB,EAGnB,MAAM,iBAAiB,CAAC;AAQzB,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AAyD3D,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,OAAO,mBAAmB,GAAG,SAAS,GAC9C,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAiHvE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,kBAAkB,CAyC3E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAA6C,MAAM,WAAW,CAAC;AA+BpF,OAAO,EAOL,mBAAmB,EAOpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAaL,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAYV,WAAW,EAKX,kBAAkB,EAGnB,MAAM,iBAAiB,CAAC;AAUzB,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AA0D3D,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,OAAO,mBAAmB,GAAG,SAAS,GAC9C,IAAI,CAEN;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAwJvE;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,kBAAkB,CA8C3E"}

package/dist/server.js

@@ -1,11 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { extname, relative, join, resolve, dirname } from "node:path";
+import { extname, relative, join, resolve, dirname, sep } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { generateText as defaultGenerateText } from "ai";
-import { getAskDbRuntimeConfig } from "@askdb/config";
+import { bootstrapAskDbEnv, getAskDbRuntimeConfig } from "@askdb/config";
 import { createAiRegistry, } from "@askdb/ai";
 import { anthropicProvider } from "@askdb/ai-anthropic";
 import { azureProvider } from "@askdb/ai-azure";
@@ -15,6 +15,8 @@ import { ask, isBuiltInDialectId, loadSchema, suggestEnrichment, tenantScopeSche
 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 { resolveStudioIntrospectionPlan, runStudioIntrospection } from "./introspection.js";
+import { probeSetupState, writeSetupConfig, SetupError } from "./setup.js";
 const ai = createAiRegistry([openaiProvider, azureProvider, googleProvider, anthropicProvider]);
 const CLIENT_DIR = fileURLToPath(new URL("./client/", import.meta.url));
 const STUDIO_RAG_MOCK_DIMENSIONS = 64;
@@ -26,12 +28,14 @@ export function setStudioPgvectorStoreFactoryForTests(factory) {
 }
 export function createStudioServer(options) {
     const schemaDir = resolve(options.schema);
-    if (!existsSync(schemaDir)) {
+    const setupReason = options.setupReason ?? null;
+    if (!setupReason && !existsSync(schemaDir)) {
         throw new Error(`schema directory not found: ${schemaDir}`);
     }
     const state = {
         schemaDir,
-        workspace: loadWorkspace(schemaDir),
+        workspace: setupReason ? null : loadWorkspace(schemaDir),
+        setupReason,
     };
     return createServer(async (req, res) => {
         try {
@@ -42,27 +46,63 @@ export function createStudioServer(options) {
             if (req.method === "GET" && url.pathname.startsWith("/assets/")) {
                 return serveClientFile(res, decodeURIComponent(url.pathname.slice(1)));
             }
+            if (req.method === "GET" && url.pathname === "/api/setup/status") {
+                return writeJson(res, 200, buildSetupStatus(state));
+            }
+            if (req.method === "POST" && url.pathname === "/api/setup/config") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Setup is only available from loopback clients." } });
+                }
+                const body = await readJson(req);
+                const result = handleSetupConfig(state, body);
+                return writeJson(res, 200, result);
+            }
+            if (req.method === "POST" && url.pathname === "/api/setup/introspect") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Setup is only available from loopback clients." } });
+                }
+                const result = await handleSetupIntrospect(state);
+                return writeJson(res, 200, result);
+            }
+            // Everything below needs a loaded workspace — route setup-mode clients to the wizard.
+            if (state.setupReason && url.pathname.startsWith("/api/")) {
+                return writeJson(res, 409, {
+                    error: { message: "Studio needs setup. Open Studio in the browser to finish the guided setup." },
+                    setup: buildSetupStatus(state),
+                });
+            }
             if (req.method === "GET" && url.pathname === "/api/workspace") {
-                return writeJson(res, 200, serializeWorkspace(state.workspace));
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
+            }
+            if (req.method === "GET" && url.pathname === "/api/introspect/status") {
+                requireWorkspace(state);
+                return writeJson(res, 200, buildIntrospectionPlanDto());
+            }
+            if (req.method === "POST" && url.pathname === "/api/introspect") {
+                if (!isLoopbackRequest(req)) {
+                    return writeJson(res, 403, { error: { message: "Resync is only available from loopback clients." } });
+                }
+                const result = await handleResync(state);
+                return writeJson(res, 200, result);
             }
             if (req.method === "POST" && url.pathname.startsWith("/api/tables/")) {
                 const tableId = decodeURIComponent(url.pathname.slice("/api/tables/".length));
                 const body = await readJson(req);
                 const draft = parseTableDraftBody(body);
                 saveDraft(state, tableId, draft);
-                return writeJson(res, 200, serializeWorkspace(state.workspace));
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
             }
             if (req.method === "POST" && url.pathname === "/api/concepts") {
                 const body = await readJson(req);
                 const concepts = parseConceptsBody(body);
                 saveConceptsDraft(state, concepts);
-                return writeJson(res, 200, serializeWorkspace(state.workspace));
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
             }
             if (req.method === "POST" && url.pathname === "/api/tenant-policy") {
                 const body = await readJson(req);
                 const { frontmatter, bodyText } = parseTenantPolicyBody(body);
                 saveTenantPolicy(state, frontmatter, bodyText);
-                return writeJson(res, 200, serializeWorkspace(state.workspace));
+                return writeJson(res, 200, serializeWorkspace(requireWorkspace(state)));
             }
             if (req.method === "POST" && url.pathname === "/api/suggest-tenant-policy") {
                 const draft = await suggestTenantPolicyDraft(state);
@@ -71,7 +111,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(state.workspace, source);
+                const candidates = await suggestForSource(requireWorkspace(state), source);
                 return writeJson(res, 200, { candidates });
             }
             if (req.method === "GET" && url.pathname === "/api/rag/status") {
@@ -130,7 +170,7 @@ export function createStudioServer(options) {
             writeJson(res, 404, { error: { message: "Not found" } });
         }
         catch (error) {
-            const status = error instanceof StudioHttpError ? error.status : 500;
+            const status = error instanceof StudioHttpError || error instanceof SetupError ? error.status : 500;
             writeJson(res, status, {
                 error: { message: error instanceof Error ? error.message : String(error) },
             });
@@ -149,9 +189,15 @@ export function serializeWorkspace(workspace) {
             return undefined;
         }
     })();
+    const schema = loadSchema(workspace.schemaDir);
+    const schemaProvider = "provider" in schema && typeof schema.provider === "string" ? schema.provider : undefined;
+    const dialect = rt.nlToSql.dialect ??
+        (schemaProvider && isBuiltInDialectId(schemaProvider) ? schemaProvider : "postgres");
     return {
         schemaDir: workspace.schemaDir,
+        schemaPathRelative: toRelativeSchemaPath(workspace.schemaDir),
         schemaId: workspace.physical.schemaId,
+        dialect,
         warnings: workspace.warnings,
         aiConfigured: Boolean(aiConfig),
         model: aiConfig?.model ?? "gpt-4o-mini",
@@ -169,14 +215,167 @@ export function serializeWorkspace(workspace) {
             };
         }),
         concepts: workspace.concepts?.frontmatter.concepts ?? [],
-        tenantPolicy: (() => {
-            const schema = loadSchema(workspace.schemaDir);
-            return schema.tenantPolicy ?? null;
-        })(),
+        tenantPolicy: schema.tenantPolicy ?? null,
+    };
+}
+function toRelativeSchemaPath(schemaDir) {
+    const rel = relative(process.cwd(), schemaDir);
+    if (rel === "")
+        return ".";
+    if (rel.startsWith("..") || rel.includes(`..${sep}`))
+        return schemaDir;
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+// ---------------------------------------------------------------------------
+// Setup wizard + server-side introspection (resync)
+// ---------------------------------------------------------------------------
+function requireWorkspace(state) {
+    if (!state.workspace) {
+        throw new StudioHttpError(409, "Studio is in setup mode — finish the guided setup first.");
+    }
+    return state.workspace;
+}
+function buildSetupStatus(state) {
+    const projectDir = process.cwd();
+    if (!state.setupReason) {
+        return {
+            needed: false,
+            reason: null,
+            projectDir,
+            configPath: null,
+            outputDir: state.schemaDir,
+            configLoadError: null,
+        };
+    }
+    const probe = probeSetupState(projectDir);
+    return {
+        needed: true,
+        reason: probe.hasConfig ? "no-artifact" : "no-config",
+        projectDir,
+        configPath: probe.configPath,
+        outputDir: probe.outputDir,
+        configLoadError: probe.loadError,
+    };
+}
+function handleSetupConfig(state, body) {
+    if (!state.setupReason) {
+        throw new StudioHttpError(409, "Studio is already set up — edit askdb.config.ts directly.");
+    }
+    const input = parseSetupConfigBody(body);
+    const result = writeSetupConfig(process.cwd(), input);
+    // Config now exists; the artifact usually doesn't yet.
+    const probe = probeSetupState(process.cwd());
+    if (probe.hasArtifact && probe.outputDir) {
+        state.schemaDir = probe.outputDir;
+        state.workspace = loadWorkspace(probe.outputDir);
+        state.setupReason = null;
+    }
+    else {
+        state.setupReason = "no-artifact";
+    }
+    return {
+        configPath: result.configPath,
+        envExamplePath: result.envExamplePath,
+        envVars: result.envVars,
+        installed: result.installed,
+        manualInstallCommand: result.manualInstallCommand,
+        packageJsonCreated: result.packageJsonCreated,
+        status: buildSetupStatus(state),
+    };
+}
+async function handleSetupIntrospect(state) {
+    if (!state.setupReason) {
+        throw new StudioHttpError(409, "Studio is already set up — use Resync schema instead.");
+    }
+    // probeSetupState re-bootstraps, picking up any .env created since server start.
+    const probe = probeSetupState(process.cwd());
+    if (!probe.hasConfig) {
+        throw new StudioHttpError(409, "Write askdb.config.ts first (setup step 1).");
+    }
+    if (probe.loadError || !probe.outputDir) {
+        throw new StudioHttpError(409, `askdb.config.ts exists but could not be loaded: ${probe.loadError ?? "unknown error"}. ` +
+            "Install the project dependencies shown in setup step 1, then retry.");
+    }
+    const outDir = probe.outputDir;
+    const run = await runStudioIntrospection({
+        outDir,
+        hasExistingArtifact: existsSync(join(outDir, "schema.json")),
+    });
+    state.schemaDir = outDir;
+    state.workspace = loadWorkspace(outDir);
+    state.setupReason = null;
+    return {
+        ok: true,
+        engine: run.engine,
+        schemaId: run.schemaId,
+        tables: run.tables,
+        warnings: run.warnings,
+        workspace: serializeWorkspace(state.workspace),
+    };
+}
+async function handleResync(state) {
+    const workspace = requireWorkspace(state);
+    // Refresh the runtime snapshot so config edits made while Studio runs are honored.
+    try {
+        bootstrapAskDbEnv({ cwd: process.cwd() });
+    }
+    catch {
+        // Keep the snapshot the server started with when the config disappeared mid-session.
+    }
+    const run = await runStudioIntrospection({
+        outDir: state.schemaDir,
+        schemaId: workspace.physical.schemaId,
+        hasExistingArtifact: true,
+    });
+    state.workspace = loadWorkspace(state.schemaDir);
+    return {
+        ok: true,
+        engine: run.engine,
+        schemaId: run.schemaId,
+        tables: run.tables,
+        warnings: run.warnings,
+        workspace: serializeWorkspace(state.workspace),
+    };
+}
+function buildIntrospectionPlanDto() {
+    const plan = resolveStudioIntrospectionPlan();
+    return plan.ok
+        ? { ok: true, engine: plan.engine, sourceLabel: plan.sourceLabel }
+        : { ok: false, engine: plan.engine, error: plan.error };
+}
+function parseSetupConfigBody(body) {
+    if (!isRecord(body)) {
+        throw new StudioHttpError(400, "Request body must be a JSON object.");
+    }
+    const databases = ["postgres", "mysql", "sqlite", "sqlserver", "prisma"];
+    const aiProviders = ["openai", "anthropic", "google", "azure"];
+    if (typeof body.database !== "string" || !databases.includes(body.database)) {
+        throw new StudioHttpError(400, `\`database\` must be one of: ${databases.join(", ")}.`);
+    }
+    if (typeof body.aiProvider !== "string" ||
+        !aiProviders.includes(body.aiProvider)) {
+        throw new StudioHttpError(400, `\`aiProvider\` must be one of: ${aiProviders.join(", ")}.`);
+    }
+    const optionalString = (key) => {
+        const value = body[key];
+        if (value === undefined || value === null || value === "")
+            return undefined;
+        if (typeof value !== "string")
+            throw new StudioHttpError(400, `\`${key}\` must be a string.`);
+        return value;
+    };
+    return {
+        database: body.database,
+        aiProvider: body.aiProvider,
+        connectionEnv: optionalString("connectionEnv"),
+        sqliteFile: optionalString("sqliteFile"),
+        prismaSchema: optionalString("prismaSchema"),
+        aiKeyEnv: optionalString("aiKeyEnv"),
+        schemaOut: optionalString("schemaOut"),
     };
 }
 function saveConceptsDraft(state, concepts) {
-    saveConcepts(state.workspace, { concepts });
+    saveConcepts(requireWorkspace(state), { concepts });
     state.workspace = loadWorkspace(state.schemaDir);
 }
 function saveTenantPolicy(state, frontmatter, body) {
@@ -197,10 +396,11 @@ function parseTenantPolicyBody(body) {
     return { frontmatter: parsed.data, bodyText };
 }
 function saveDraft(state, tableId, draft) {
-    const table = state.workspace.tables.find((candidate) => candidate.physical.id === tableId);
+    const workspace = requireWorkspace(state);
+    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, state.workspace.physical.schemaId, draft);
+    const frontmatter = buildFrontmatter(table.physical, workspace.physical.schemaId, draft);
     let body = table.parsed
         ? replaceTableDescription(table.parsed.body, draft.description)
         : buildDefaultTableBody(table.physical.name, draft.description);
@@ -210,7 +410,7 @@ function saveDraft(state, tableId, draft) {
     if (draft.exampleQuestions !== undefined) {
         body = replaceH2Section(body, "Example questions", draft.exampleQuestions);
     }
-    saveTable(state.workspace, tableId, frontmatter, body);
+    saveTable(workspace, tableId, frontmatter, body);
     state.workspace = loadWorkspace(state.schemaDir);
 }
 async function suggestForSource(workspace, source) {
@@ -229,7 +429,7 @@ async function suggestTenantPolicyDraft(state) {
         throw new StudioHttpError(400, ai.keyMissingMessage("AI tenant policy suggestion"));
     }
     // Build a compact DDL-like representation of the schema for the prompt
-    const workspace = state.workspace;
+    const workspace = requireWorkspace(state);
     const schemaId = workspace.physical.schemaId;
     const schemaDdl = workspace.tables
         .map((t) => {