@duckcodeailabs/dql-cli 1.4.3 → 1.4.4

package/local-runtime.js

@@ -0,0 +1,4357 @@
+import { execSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
+import { dirname, extname, join, normalize, relative, resolve } from 'node:path';
+import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
+import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
+import { load as loadYaml } from 'js-yaml';
+import { listBlockTemplates } from './block-templates.js';
+import { getRunner as getLLMRunner } from './llm/index.js';
+import { handleAppsApi } from './apps-api.js';
+import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
+import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
+import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, } from './metricflow.js';
+export async function startLocalServer(opts) {
+    const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
+    const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
+    let connection = normalizeProjectConnection(rawConnection, projectRoot);
+    let projectConfig = loadProjectConfig(projectRoot);
+    // Load semantic layer via provider system (dql native, dbt, cubejs, etc.)
+    let semanticLayer;
+    let semanticLayerErrors = [];
+    let semanticDetectedProvider;
+    const semanticLayerDir = join(projectRoot, 'semantic-layer');
+    let semanticImportManifest = loadSemanticImportManifest(projectRoot);
+    const userPrefsPath = join(projectRoot, '.dql-user-prefs.json');
+    const semanticConfig = projectConfig.semanticLayer;
+    let semanticLastSyncTime = null;
+    {
+        const executeQuery = semanticConfig?.provider === 'snowflake'
+            ? async (sql) => { const r = await executor.executeQuery(sql, [], {}, connection); return { rows: r.rows }; }
+            : undefined;
+        const result = await resolveSemanticLayerAsync(semanticConfig, projectRoot, executeQuery);
+        semanticLayer = result.layer;
+        semanticLayerErrors = result.errors;
+        semanticDetectedProvider = result.detectedProvider;
+        semanticLastSyncTime = result.layer ? new Date().toISOString() : null;
+        semanticImportManifest = loadSemanticImportManifest(projectRoot);
+        // Legacy fallback if provider system returned nothing and no errors
+        if (!semanticLayer && semanticLayerErrors.length === 0 && existsSync(semanticLayerDir)) {
+            try {
+                semanticLayer = loadSemanticLayerFromDir(semanticLayerDir);
+                semanticLastSyncTime = new Date().toISOString();
+            }
+            catch { /* continue without */ }
+        }
+    }
+    // Auto-register data/ CSV and Parquet files as DuckDB views so semantic layer
+    // queries like `FROM orders` resolve without requiring read_csv_auto() in SQL.
+    if (connection.driver === 'file' || connection.driver === 'duckdb') {
+        const dataDir = projectConfig.dataDir
+            ? resolve(projectRoot, projectConfig.dataDir)
+            : join(projectRoot, 'data');
+        if (existsSync(dataDir)) {
+            try {
+                const files = readdirSync(dataDir, { withFileTypes: true })
+                    .filter((e) => e.isFile() && /\.(csv|parquet)$/i.test(e.name));
+                for (const file of files) {
+                    const tableName = file.name.replace(/\.(csv|parquet)$/i, '');
+                    const absPath = join(dataDir, file.name).replaceAll('\\', '/');
+                    const reader = file.name.endsWith('.parquet') ? 'read_parquet' : 'read_csv_auto';
+                    const ddl = `CREATE OR REPLACE VIEW "${tableName}" AS SELECT * FROM ${reader}('${absPath}')`;
+                    try {
+                        await executor.executeQuery(ddl, [], {}, connection);
+                    }
+                    catch { /* non-fatal */ }
+                }
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    // SSE clients for /api/watch hot-reload
+    const sseClients = new Set();
+    // Watch notebooks/, workbooks/, semantic-layer/, and data/ dirs for changes
+    if (projectRoot) {
+        for (const dir of ['notebooks', 'workbooks', 'blocks', 'dashboards', 'semantic-layer', 'data']) {
+            const watchDir = join(projectRoot, dir);
+            if (!existsSync(watchDir))
+                continue;
+            try {
+                watch(watchDir, { persistent: false }, (eventType, filename) => {
+                    if (!filename)
+                        return;
+                    const path = `${dir}/${filename}`;
+                    const payload = JSON.stringify({ type: eventType === 'rename' ? 'file-added' : 'file-changed', path });
+                    for (const client of sseClients) {
+                        try {
+                            client.write(`event: change\ndata: ${payload}\n\n`);
+                        }
+                        catch {
+                            sseClients.delete(client);
+                        }
+                    }
+                    // Hot-reload semantic layer on change and notify frontend
+                    if (dir === 'semantic-layer') {
+                        const executeQuery = semanticConfig?.provider === 'snowflake'
+                            ? async (sql) => { const r = await executor.executeQuery(sql, [], {}, connection); return { rows: r.rows }; }
+                            : undefined;
+                        resolveSemanticLayerAsync(semanticConfig, projectRoot, executeQuery).then((refreshed) => {
+                            if (refreshed.layer) {
+                                semanticLayer = refreshed.layer;
+                                semanticLayerErrors = refreshed.errors;
+                                semanticLastSyncTime = new Date().toISOString();
+                                semanticImportManifest = loadSemanticImportManifest(projectRoot);
+                            }
+                            else if (refreshed.errors.length > 0) {
+                                semanticLayerErrors = refreshed.errors;
+                            }
+                            // Notify all connected notebook clients to re-fetch the semantic layer
+                            const reloadPayload = JSON.stringify({ type: 'semantic-reload' });
+                            for (const client of sseClients) {
+                                try {
+                                    client.write(`event: change\ndata: ${reloadPayload}\n\n`);
+                                }
+                                catch {
+                                    sseClients.delete(client);
+                                }
+                            }
+                        }).catch(() => { });
+                    }
+                });
+            }
+            catch { /* dir not watchable */ }
+        }
+    }
+    const server = createServer(async (req, res) => {
+        const requestUrl = req.url || '/';
+        const url = new URL(requestUrl, 'http://127.0.0.1');
+        const path = url.pathname || '/';
+        // CORS — needed for dql-notebook SPA dev mode
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ status: 'ok' }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/settings/env-status') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ groups: collectSettingsEnvStatus() }));
+            return;
+        }
+        const appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
+        if (req.method === 'POST' && appDashRun) {
+            try {
+                const appId = decodeURIComponent(appDashRun[1]);
+                const dashboardId = decodeURIComponent(appDashRun[2]);
+                const body = await readJSON(req).catch(() => ({}));
+                const loaded = loadAppDashboard(projectRoot, appId, dashboardId);
+                if (!loaded) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Dashboard "${dashboardId}" not found in app "${appId}"` }));
+                    return;
+                }
+                const manifest = buildManifest({ projectRoot });
+                const variables = body.variables && typeof body.variables === 'object'
+                    ? body.variables
+                    : {};
+                const tiles = [];
+                for (const item of loaded.dashboard.layout.items) {
+                    const block = resolveDashboardItemBlock(item, manifest);
+                    if (!block) {
+                        tiles.push({
+                            tileId: item.i,
+                            status: 'unresolved',
+                            blockRef: isBlockIdRef(item.block) ? item.block.blockId : item.block.ref,
+                            error: 'Block reference could not be resolved',
+                        });
+                        continue;
+                    }
+                    try {
+                        assertAppAccess({
+                            app: loaded.app,
+                            domain: block.domain ?? loaded.dashboard.metadata.domain ?? loaded.app.domain,
+                            level: 'execute',
+                        });
+                        const absBlockPath = join(projectRoot, block.filePath);
+                        const source = readFileSync(absBlockPath, 'utf-8');
+                        const semanticCompose = semanticLayer
+                            ? composeSemanticBlockSql(source, semanticLayer, {
+                                driver: connection.driver,
+                                projectRoot,
+                                projectConfig,
+                                detectedProvider: semanticDetectedProvider,
+                            })
+                            : null;
+                        const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, { semanticLayer, driver: connection.driver });
+                        if (!plan && !semanticCompose?.sql) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'error',
+                                blockId: block.name,
+                                error: semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message ?? 'Block produced no executable plan',
+                            });
+                            continue;
+                        }
+                        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
+                        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...variables }), prepared.connection);
+                        tiles.push({
+                            tileId: item.i,
+                            status: 'ok',
+                            blockId: block.name,
+                            blockPath: block.filePath,
+                            certificationStatus: block.status ?? null,
+                            title: item.title ?? block.name,
+                            viz: item.viz,
+                            chartConfig: plan?.chartConfig ?? { chart: item.viz.type },
+                            result: normalizeQueryResult(result),
+                            citation: {
+                                kind: 'block',
+                                name: block.name,
+                                path: block.filePath,
+                            },
+                        });
+                    }
+                    catch (err) {
+                        if (err instanceof DQLAccessDeniedError) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'unauthorized',
+                                blockId: block.name,
+                                error: err.message,
+                            });
+                        }
+                        else {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'error',
+                                blockId: block.name,
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                        }
+                    }
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    appId,
+                    dashboardId,
+                    persona: activePersonaAppId() ? { appId: activePersonaAppId() } : null,
+                    tiles,
+                }));
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: err instanceof Error ? err.message : String(err) }));
+            }
+            return;
+        }
+        // Apps, dashboards, persona — see apps-api.ts. Returns true if handled.
+        if (path.startsWith('/api/apps') || path === '/api/persona') {
+            try {
+                const handled = await handleAppsApi({ req, res, url, path, projectRoot });
+                if (handled)
+                    return;
+            }
+            catch (err) {
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: err.message }));
+                }
+                return;
+            }
+        }
+        // SSE endpoint for hot-reload file watching
+        if (req.method === 'GET' && path === '/api/watch') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+                'X-Accel-Buffering': 'no',
+            });
+            res.write(': connected\n\n');
+            sseClients.add(res);
+            req.on('close', () => { sseClients.delete(res); });
+            return;
+        }
+        // ── dql-notebook file management API ─────────────────────────────────────
+        // GET  /api/notebooks          — list all .dql/.dqlnb files grouped by folder
+        // GET  /api/notebook-content   — read a file (?path=relative/path)
+        // POST /api/notebooks          — create new notebook
+        // PUT  /api/notebook-content   — save file
+        // GET  /api/schema             — list data files for schema panel
+        if (req.method === 'GET' && path === '/api/notebooks') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(scanNotebookFiles(projectRoot)));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/notebook-content') {
+            const filePath = url.searchParams.get('path');
+            if (!filePath) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Missing path query parameter' }));
+                return;
+            }
+            const absPath = safeJoin(projectRoot, filePath);
+            if (!absPath || !existsSync(absPath)) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'File not found' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ content: readFileSync(absPath, 'utf-8') }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/notebooks') {
+            try {
+                const body = await readJSON(req);
+                const { name, template } = body;
+                if (!name || typeof name !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing notebook name' }));
+                    return;
+                }
+                const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'notebook';
+                const nbDir = join(projectRoot, 'notebooks');
+                mkdirSync(nbDir, { recursive: true });
+                const nbPath = join(nbDir, `${slug}.dqlnb`);
+                if (existsSync(nbPath)) {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Notebook already exists' }));
+                    return;
+                }
+                const content = buildNotebookTemplate(name, template ?? 'blank');
+                writeFileSync(nbPath, content, 'utf-8');
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ path: `notebooks/${slug}.dqlnb`, content }));
+            }
+            catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'PUT' && path === '/api/notebook-content') {
+            try {
+                const body = await readJSON(req);
+                const { path: filePath, content } = body;
+                if (!filePath || typeof content !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing path or content' }));
+                    return;
+                }
+                const absPath = safeJoin(projectRoot, filePath);
+                if (!absPath) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Invalid path' }));
+                    return;
+                }
+                mkdirSync(dirname(absPath), { recursive: true });
+                const toWrite = absPath.endsWith('.dql')
+                    ? canonicalizeSafe(content)
+                    : absPath.endsWith('.dqlnb')
+                        ? canonicalizeNotebookSafe(content)
+                        : content;
+                writeFileSync(absPath, toWrite, 'utf-8');
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── run snapshots (v0.11) ───────────────────────────────────────────────
+        // Captures executed notebook state (query results + timings) in a
+        // sibling `.run.json` so notebooks can show last-run output without
+        // re-executing after a reload. Snapshots are git-ignored by default.
+        if (req.method === 'GET' && path === '/api/run-snapshot') {
+            const notebookPath = url.searchParams.get('path') ?? '';
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(readRunSnapshot(projectRoot, notebookPath)));
+            return;
+        }
+        if (req.method === 'PUT' && path === '/api/run-snapshot') {
+            try {
+                const body = await readJSON(req);
+                if (!body.path || typeof body.path !== 'string' || !body.snapshot) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing path or snapshot' }));
+                    return;
+                }
+                writeRunSnapshot(projectRoot, body.path, body.snapshot);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: err instanceof Error ? err.message : String(err) }));
+            }
+            return;
+        }
+        // ── git read-only API (v0.11) ───────────────────────────────────────────
+        // GET /api/git/status  — branch, clean, changed files
+        // GET /api/git/log     — last N commits (?limit=20)
+        // GET /api/git/diff    — unified diff for a single file (?path=relative/path)
+        if (req.method === 'GET' && path === '/api/git/status') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(await readGitStatus(projectRoot)));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/git/log') {
+            const limit = Math.min(Number(url.searchParams.get('limit') ?? 20), 200);
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(await readGitLog(projectRoot, limit)));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/git/diff') {
+            const filePath = url.searchParams.get('path') ?? '';
+            const staged = url.searchParams.get('staged') === 'true';
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(await readGitDiff(projectRoot, filePath, staged)));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/git/branches') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(await readGitBranches(projectRoot)));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/git/remote') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(await readGitRemote(projectRoot)));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/stage') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitStage(projectRoot, body.paths ?? []);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/unstage') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitUnstage(projectRoot, body.paths ?? []);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/discard') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitDiscard(projectRoot, body.paths ?? []);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/commit') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitCommit(projectRoot, body.message ?? '', body.stageAll === true);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/push') {
+            try {
+                const result = await gitPush(projectRoot);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/pull') {
+            try {
+                const result = await gitPull(projectRoot);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/branch') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitCreateBranch(projectRoot, body.name ?? '', body.checkout !== false);
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/git/checkout') {
+            try {
+                const body = (await readJSON(req));
+                const result = await gitCheckout(projectRoot, body.name ?? '');
+                res.writeHead(result.ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (e) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/schema') {
+            try {
+                const dataFiles = scanDataFiles(projectRoot);
+                const { tables, columnsByPath } = await introspectSchema(executor, connection);
+                const dbTables = tables.map((t) => ({
+                    name: t.path,
+                    path: t.path,
+                    columns: columnsByPath.get(t.path) ?? [],
+                    source: 'database',
+                    objectType: t.type,
+                }));
+                const seen = new Set(dataFiles.map((f) => f.name));
+                const merged = [
+                    ...dataFiles.map((f) => ({ ...f, source: 'file' })),
+                    ...dbTables.filter((t) => !seen.has(t.name)),
+                ];
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(merged));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[dql] /api/schema introspection failed: ${message}`);
+                const fallback = scanDataFiles(projectRoot).map((f) => ({ ...f, source: 'file' }));
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: message, fallback }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/blocks') {
+            try {
+                const body = await readJSON(req);
+                const { name, domain, content, description, tags, metricRefs, template, } = body;
+                if (!name || typeof name !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing block name' }));
+                    return;
+                }
+                const created = createBlockArtifacts(projectRoot, {
+                    name,
+                    domain,
+                    content,
+                    description,
+                    tags,
+                    metricRefs,
+                    template,
+                });
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(created));
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block already exists' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/blocks/save-from-cell') {
+            try {
+                const body = await readJSON(req);
+                const { name, domain, owner, content, description, tags, metricRefs, template, llmContext, examples, invariants, } = body;
+                if (!name || typeof name !== 'string' || !content || typeof content !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'name and content are required' }));
+                    return;
+                }
+                const missing = [];
+                if (!owner || !owner.trim())
+                    missing.push('owner');
+                if (!domain || !domain.trim())
+                    missing.push('domain');
+                if (!description || !description.trim())
+                    missing.push('description');
+                if (missing.length > 0) {
+                    res.writeHead(422, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        error: `Block is missing required governance fields: ${missing.join(', ')}`,
+                        missing,
+                    }));
+                    return;
+                }
+                const created = createBlockArtifacts(projectRoot, {
+                    name,
+                    domain,
+                    owner,
+                    content,
+                    description,
+                    tags,
+                    metricRefs,
+                    template,
+                    llmContext,
+                    examples,
+                    invariants,
+                    gitMetadata: readGitMetadata(projectRoot),
+                });
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(created));
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block already exists' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/blocks/templates') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ templates: listBlockTemplates() }));
+            return;
+        }
+        // ── Block library (list all blocks with metadata) ────────────────────
+        if (req.method === 'GET' && path === '/api/blocks/library') {
+            try {
+                const blocksDir = join(projectRoot, 'blocks');
+                const blocks = [];
+                if (existsSync(blocksDir)) {
+                    const scanDir = (dir) => {
+                        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                            if (entry.isDirectory()) {
+                                scanDir(join(dir, entry.name));
+                            }
+                            else if (entry.name.endsWith('.dql')) {
+                                const filePath = join(dir, entry.name);
+                                const relPath = relative(projectRoot, filePath);
+                                try {
+                                    const source = readFileSync(filePath, 'utf-8');
+                                    const stat = statSync(filePath);
+                                    // Quick regex parse for key block fields
+                                    const nameMatch = /block\s+"([^"]+)"/.exec(source);
+                                    const domainMatch = /domain\s*=\s*"([^"]+)"/.exec(source);
+                                    const statusMatch = /status\s*=\s*"([^"]+)"/.exec(source);
+                                    const ownerMatch = /owner\s*=\s*"([^"]+)"/.exec(source);
+                                    const descMatch = /description\s*=\s*"([^"]+)"/.exec(source);
+                                    const tagsMatch = /tags\s*=\s*\[([^\]]*)\]/.exec(source);
+                                    const parsedTags = tagsMatch
+                                        ? tagsMatch[1].split(',').map((tag) => tag.trim().replace(/^"|"$/g, '')).filter(Boolean)
+                                        : [];
+                                    const llmMatch = /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/.exec(source);
+                                    blocks.push({
+                                        name: nameMatch?.[1] ?? entry.name.replace('.dql', ''),
+                                        domain: domainMatch?.[1] ?? 'uncategorized',
+                                        status: statusMatch?.[1] ?? 'draft',
+                                        owner: ownerMatch?.[1] ?? null,
+                                        tags: parsedTags,
+                                        path: relPath,
+                                        lastModified: stat.mtime.toISOString(),
+                                        description: descMatch?.[1] ?? '',
+                                        llmContext: llmMatch?.[1] ?? null,
+                                    });
+                                }
+                                catch { /* skip unreadable files */ }
+                            }
+                        }
+                    };
+                    scanDir(blocksDir);
+                }
+                blocks.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime());
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ blocks }));
+            }
+            catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Apps (App artifact listing for notebook AppsPanel) ────────────────
+        if (req.method === 'GET' && path === '/api/apps') {
+            try {
+                const appsRoot = join(projectRoot, 'apps');
+                const apps = [];
+                const listFilesByExt = (dir, ext) => {
+                    const out = [];
+                    try {
+                        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                            const full = join(dir, entry.name);
+                            if (entry.isDirectory()) {
+                                out.push(...listFilesByExt(full, ext).map((n) => `${entry.name}/${n}`));
+                            }
+                            else if (entry.isFile() && entry.name.endsWith(ext)) {
+                                out.push(entry.name);
+                            }
+                        }
+                    }
+                    catch { /* dir missing; return [] */ }
+                    return out;
+                };
+                if (existsSync(appsRoot)) {
+                    for (const entry of readdirSync(appsRoot, { withFileTypes: true })) {
+                        if (!entry.isDirectory() || !entry.name.endsWith('.dql-app'))
+                            continue;
+                        const appDir = join(appsRoot, entry.name);
+                        try {
+                            const raw = readFileSync(join(appDir, 'app.yml'), 'utf-8');
+                            const manifest = loadYaml(raw);
+                            if (!manifest || !manifest.name || !manifest.domain)
+                                continue;
+                            apps.push({
+                                path: relative(projectRoot, appDir),
+                                manifest,
+                                notebooks: listFilesByExt(join(appDir, 'notebooks'), '.dqlnb'),
+                                dashboards: listFilesByExt(join(appDir, 'dashboards'), '.dql'),
+                                hasDigest: existsSync(join(appDir, 'digest.dql')),
+                            });
+                        }
+                        catch { /* skip unreadable apps */ }
+                    }
+                }
+                apps.sort((a, b) => a.manifest.name.localeCompare(b.manifest.name));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ apps }));
+            }
+            catch (error) {
+                const status = error instanceof DQLAccessDeniedError ? 403 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    ...(status === 403 ? { code: 'unauthorized' } : {}),
+                }));
+            }
+            return;
+        }
+        // ── Block status update ──────────────────────────────────────────────
+        if (req.method === 'POST' && path === '/api/blocks/status') {
+            try {
+                const body = await readJSON(req);
+                const blockPath = body.path;
+                const newStatus = body.newStatus;
+                const validStatuses = ['draft', 'review', 'certified', 'deprecated'];
+                if (!validStatuses.includes(newStatus)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Status must be one of: ${validStatuses.join(', ')}` }));
+                    return;
+                }
+                const absPath = resolve(projectRoot, blockPath);
+                if (!existsSync(absPath)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block file not found' }));
+                    return;
+                }
+                let source = readFileSync(absPath, 'utf-8');
+                // Update or insert status field
+                if (/status\s*=\s*"[^"]*"/.test(source)) {
+                    source = source.replace(/status\s*=\s*"[^"]*"/, `status = "${newStatus}"`);
+                }
+                else {
+                    // Insert after first { in block declaration
+                    source = source.replace(/block\s+"[^"]*"\s*\{/, (match) => `${match}\n  status = "${newStatus}"`);
+                }
+                writeFileSync(absPath, source, 'utf-8');
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, status: newStatus }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Block version history (git log) ──────────────────────────────────
+        if (req.method === 'GET' && path === '/api/blocks/history') {
+            try {
+                const blockPath = url.searchParams.get('path');
+                if (!blockPath) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path parameter is required' }));
+                    return;
+                }
+                const { execSync } = await import('node:child_process');
+                const gitLog = execSync(`git log --format="%H|||%ai|||%an|||%s" -20 -- "${blockPath}"`, { cwd: projectRoot, encoding: 'utf-8', timeout: 10000 }).trim();
+                const entries = gitLog
+                    ? gitLog.split('\n').map((line) => {
+                        const [hash, date, author, message] = line.split('|||');
+                        return { hash, date, author, message };
+                    })
+                    : [];
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ entries }));
+            }
+            catch (error) {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ entries: [] }));
+            }
+            return;
+        }
+        // ── Block body (re-read from disk, used by bound-cell refresh) ──────
+        if (req.method === 'GET' && path === '/api/blocks/body') {
+            try {
+                const blockPath = url.searchParams.get('path');
+                if (!blockPath) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path parameter is required' }));
+                    return;
+                }
+                const absolutePath = resolve(projectRoot, blockPath);
+                if (!absolutePath.startsWith(projectRoot + '/') && absolutePath !== projectRoot) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'path escapes project root' }));
+                    return;
+                }
+                if (!existsSync(absolutePath)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'block not found' }));
+                    return;
+                }
+                const body = readFileSync(absolutePath, 'utf-8');
+                let commitSha = null;
+                try {
+                    const { execSync } = await import('node:child_process');
+                    const sha = execSync(`git log -1 --format=%H -- "${blockPath}"`, {
+                        cwd: projectRoot,
+                        encoding: 'utf-8',
+                        stdio: ['ignore', 'pipe', 'ignore'],
+                        timeout: 5000,
+                    }).trim();
+                    commitSha = sha.length > 0 ? sha : null;
+                }
+                catch {
+                    commitSha = null;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ path: blockPath, body, commitSha }));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: message }));
+            }
+            return;
+        }
+        // ── Run block tests ────────────────────────────────────────────────
+        if (req.method === 'POST' && path === '/api/blocks/run-tests') {
+            try {
+                const body = await readJSON(req);
+                const source = body.source;
+                if (!source) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'source is required' }));
+                    return;
+                }
+                // Parse the block to extract tests and query SQL
+                const parser = new Parser(source, '<run-tests>');
+                const ast = parser.parse();
+                const blockNode = ast.statements.find((n) => n.kind === 'BlockDecl');
+                if (!blockNode) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'No block declaration found in source' }));
+                    return;
+                }
+                const testNodes = blockNode.tests ?? [];
+                if (testNodes.length === 0) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ assertions: [], passed: 0, failed: 0, duration: 0 }));
+                    return;
+                }
+                // Get the block's base SQL
+                const baseSql = blockNode.query?.rawSQL?.trim() ?? '';
+                if (!baseSql) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block has no query SQL to test against' }));
+                    return;
+                }
+                const resolvedSql = resolveProjectRelativeSqlPaths(baseSql, projectRoot, projectConfig.dataDir);
+                // Build and run assertions
+                const start = Date.now();
+                const results = [];
+                for (const test of testNodes) {
+                    const field = test.field;
+                    const op = test.operator;
+                    const expected = test.expected;
+                    // Extract the expected value from the AST node
+                    const expectedValue = typeof expected === 'object' && expected !== null
+                        ? (expected.value ?? String(expected))
+                        : expected;
+                    // Build a SQL query that computes the aggregate for this assertion
+                    const testSql = `SELECT ${field} AS test_value FROM (${resolvedSql}) AS __test_block`;
+                    try {
+                        const result = await executor.executeQuery(testSql, [], {}, connection);
+                        const actualRaw = result.rows?.[0];
+                        const actual = actualRaw ? Object.values(actualRaw)[0] : undefined;
+                        const actualNum = Number(actual);
+                        const expectedNum = Number(expectedValue);
+                        let passed = false;
+                        switch (op) {
+                            case '>':
+                                passed = actualNum > expectedNum;
+                                break;
+                            case '<':
+                                passed = actualNum < expectedNum;
+                                break;
+                            case '>=':
+                                passed = actualNum >= expectedNum;
+                                break;
+                            case '<=':
+                                passed = actualNum <= expectedNum;
+                                break;
+                            case '==':
+                                passed = String(actual) === String(expectedValue);
+                                break;
+                            case '!=':
+                                passed = String(actual) !== String(expectedValue);
+                                break;
+                            default: passed = false;
+                        }
+                        results.push({ field, operator: op, expected: String(expectedValue), passed, actual: String(actual ?? '') });
+                    }
+                    catch (err) {
+                        results.push({ field, operator: op, expected: String(expectedValue), passed: false, actual: `Error: ${err instanceof Error ? err.message : String(err)}` });
+                    }
+                }
+                const duration = Date.now() - start;
+                const passed = results.filter((r) => r.passed).length;
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ assertions: results, passed, failed: results.length - passed, duration }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/block-studio/catalog') {
+            try {
+                const cfg = loadProjectConfig(projectRoot);
+                const connections = cfg.connections ?? {};
+                if (Object.keys(connections).length === 0 && cfg.defaultConnection) {
+                    connections.default = cfg.defaultConnection;
+                }
+                const defaultKey = cfg.defaultConnection ? 'default' : Object.keys(connections)[0] ?? 'default';
+                const userPrefs = readUserPrefs(userPrefsPath);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    semanticTree: semanticLayer ? buildSemanticTree(semanticLayer, semanticImportManifest) : null,
+                    databaseTree: await buildDatabaseSchemaTree(projectRoot, executor, connection),
+                    connection: {
+                        default: defaultKey,
+                        current: defaultKey,
+                        connections,
+                    },
+                    favorites: userPrefs.favorites,
+                    recentlyUsed: userPrefs.recentlyUsed,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/block-studio/open') {
+            try {
+                const relativePath = url.searchParams.get('path');
+                if (!relativePath) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing block path.' }));
+                    return;
+                }
+                const payload = openBlockStudioDocument(projectRoot, relativePath, semanticLayer);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(payload));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/block-studio/validate') {
+            try {
+                const body = await readJSON(req);
+                const source = typeof body.source === 'string' ? body.source : '';
+                const validation = validateBlockStudioSource(source, semanticLayer);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(validation));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/block-studio/run') {
+            try {
+                const body = await readJSON(req);
+                const source = typeof body.source === 'string' ? body.source : '';
+                const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
+                let tableMapping;
+                if (semanticLayer) {
+                    try {
+                        const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name
+               FROM information_schema.tables
+               WHERE table_schema NOT IN ('information_schema', 'pg_catalog')`, [], {}, targetConnection);
+                        tableMapping = buildSemanticTableMapping(semanticLayer, tablesResult.rows);
+                    }
+                    catch {
+                        tableMapping = undefined;
+                    }
+                }
+                const semanticCompose = semanticLayer
+                    ? composeSemanticBlockSql(source, semanticLayer, {
+                        driver: targetConnection.driver,
+                        tableMapping,
+                        projectRoot,
+                        projectConfig,
+                        detectedProvider: semanticDetectedProvider,
+                    })
+                    : null;
+                const validation = validateBlockStudioSource(source, semanticLayer);
+                const executableSql = semanticCompose?.sql ?? validation.executableSql;
+                if (!executableSql) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    const message = semanticCompose?.diagnostics.find((item) => item.severity === 'error')?.message
+                        ?? validation.diagnostics.find((item) => item.severity === 'error')?.message
+                        ?? 'No executable SQL found in block source.';
+                    res.end(serializeJSON({ error: message, diagnostics: validation.diagnostics }));
+                    return;
+                }
+                const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver });
+                const sql = resolveProjectRelativeSqlPaths(semanticCompose?.sql ?? plan?.sql ?? executableSql, projectRoot, projectConfig.dataDir);
+                const result = await executor.executeQuery(sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), targetConnection);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    sql: plan?.sql ?? executableSql,
+                    result: normalizeQueryResult(result),
+                    chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/block-studio/save') {
+            try {
+                const body = await readJSON(req);
+                const source = typeof body.source === 'string' ? body.source : '';
+                const metadata = body.metadata && typeof body.metadata === 'object'
+                    ? body.metadata
+                    : {};
+                if (!source.trim()) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block source is required.' }));
+                    return;
+                }
+                if (!metadata.name || typeof metadata.name !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block name is required.' }));
+                    return;
+                }
+                const savedPath = saveBlockStudioArtifacts(projectRoot, {
+                    currentPath: typeof body.path === 'string' ? body.path : undefined,
+                    source,
+                    name: metadata.name,
+                    domain: metadata.domain,
+                    description: metadata.description,
+                    owner: metadata.owner,
+                    tags: Array.isArray(metadata.tags) ? metadata.tags.map(String) : [],
+                });
+                const payload = openBlockStudioDocument(projectRoot, savedPath, semanticLayer);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(payload));
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block already exists' }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/connections') {
+            const cfg = loadProjectConfig(projectRoot);
+            const raw = cfg;
+            const connections = raw.connections ?? {};
+            // If no explicit connections map, surface the defaultConnection as "default"
+            if (Object.keys(connections).length === 0 && cfg.defaultConnection) {
+                connections['default'] = cfg.defaultConnection;
+            }
+            const defaultKey = raw.defaultConnection
+                ? 'default'
+                : Object.keys(connections)[0] ?? 'default';
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ default: defaultKey, connections }));
+            return;
+        }
+        // Save/update connections
+        if (req.method === 'PUT' && path === '/api/connections') {
+            try {
+                const body = await readJSON(req);
+                const configPath = join(projectRoot, 'dql.config.json');
+                let raw = {};
+                if (existsSync(configPath)) {
+                    raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+                }
+                if (body.connections && typeof body.connections === 'object') {
+                    raw.connections = body.connections;
+                }
+                writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n', 'utf-8');
+                // Hot-swap: re-read the config and re-initialize the active connection
+                projectConfig = loadProjectConfig(projectRoot);
+                const newDefault = projectConfig.defaultConnection;
+                if (newDefault) {
+                    connection = normalizeProjectConnection(newDefault, projectRoot);
+                    // Auto-register data files if DuckDB/file driver
+                    if (connection.driver === 'file' || connection.driver === 'duckdb') {
+                        const dataDir = projectConfig.dataDir
+                            ? resolve(projectRoot, projectConfig.dataDir)
+                            : join(projectRoot, 'data');
+                        if (existsSync(dataDir)) {
+                            try {
+                                const files = readdirSync(dataDir, { withFileTypes: true })
+                                    .filter((e) => e.isFile() && /\.(csv|parquet)$/i.test(e.name));
+                                for (const file of files) {
+                                    const tableName = file.name.replace(/\.(csv|parquet)$/i, '');
+                                    const absPath = join(dataDir, file.name).replaceAll('\\', '/');
+                                    const reader = file.name.endsWith('.parquet') ? 'read_parquet' : 'read_csv_auto';
+                                    const ddl = `CREATE OR REPLACE VIEW "${tableName}" AS SELECT * FROM ${reader}('${absPath}')`;
+                                    try {
+                                        await executor.executeQuery(ddl, [], {}, connection);
+                                    }
+                                    catch { /* non-fatal */ }
+                                }
+                            }
+                            catch { /* non-fatal */ }
+                        }
+                    }
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Semantic layer discovery API ─────────────────────────────────────────
+        if (req.method === 'GET' && path === '/api/semantic-layer') {
+            const userPrefs = readUserPrefs(userPrefsPath);
+            if (!semanticLayer) {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    available: false,
+                    provider: projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? null,
+                    errors: semanticLayerErrors,
+                    metrics: [],
+                    measures: [],
+                    dimensions: [],
+                    timeDimensions: [],
+                    entities: [],
+                    hierarchies: [],
+                    semanticModels: [],
+                    savedQueries: [],
+                    domains: [],
+                    tags: [],
+                    favorites: userPrefs.favorites,
+                    recentlyUsed: userPrefs.recentlyUsed,
+                    lastSyncTime: semanticLastSyncTime,
+                }));
+                return;
+            }
+            const metrics = semanticLayer.listMetrics().map((m) => ({
+                name: m.name,
+                label: m.label,
+                description: m.description,
+                domain: m.domain,
+                sql: m.sql,
+                type: m.type,
+                table: m.table,
+                tags: m.tags ?? [],
+                owner: m.owner ?? null,
+                metricType: m.metricType ?? null,
+                typeParams: m.typeParams ?? null,
+                filter: m.filter ?? null,
+                source: m.source ?? null,
+            }));
+            const measures = semanticLayer.listMeasures().map((m) => ({
+                name: m.name,
+                label: m.label,
+                description: m.description,
+                domain: m.domain,
+                agg: m.agg,
+                expr: m.expr ?? null,
+                table: m.table,
+                cube: m.cube ?? null,
+                aggTimeDimension: m.aggTimeDimension ?? null,
+                nonAdditiveDimension: m.nonAdditiveDimension ?? null,
+                tags: m.tags ?? [],
+                owner: m.owner ?? null,
+                source: m.source ?? null,
+            }));
+            const dimensions = semanticLayer.listDimensions().map((d) => ({
+                name: d.name,
+                label: d.label,
+                description: d.description,
+                domain: d.domain,
+                sql: d.sql,
+                type: d.type,
+                table: d.table,
+                tags: d.tags ?? [],
+                owner: d.owner ?? null,
+                cube: d.cube ?? null,
+                isTimeDimension: d.isTimeDimension ?? false,
+                typeParams: d.typeParams ?? null,
+                source: d.source ?? null,
+            }));
+            const timeDimensions = semanticLayer.listTimeDimensions().map((d) => ({
+                name: d.name,
+                label: d.label,
+                description: d.description,
+                domain: d.domain,
+                sql: d.sql,
+                type: d.type,
+                table: d.table,
+                cube: d.cube ?? null,
+                granularities: d.granularities ?? [],
+                primaryTime: d.primaryTime ?? false,
+                tags: d.tags ?? [],
+                owner: d.owner ?? null,
+                typeParams: d.typeParams ?? null,
+                source: d.source ?? null,
+            }));
+            const entities = semanticLayer.listEntities().map((e) => ({
+                name: e.name,
+                label: e.label,
+                description: e.description,
+                domain: e.domain,
+                type: e.type,
+                expr: e.expr ?? null,
+                table: e.table,
+                cube: e.cube ?? null,
+                role: e.role ?? null,
+                tags: e.tags ?? [],
+                owner: e.owner ?? null,
+                source: e.source ?? null,
+            }));
+            const hierarchies = semanticLayer.listHierarchies().map((h) => ({
+                name: h.name,
+                label: h.label,
+                description: h.description,
+                domain: h.domain,
+                levels: h.levels.map((l) => ({ name: l.name, label: l.label })),
+            }));
+            const semanticModels = semanticLayer.listSemanticModels().map((m) => ({
+                name: m.name,
+                label: m.label,
+                description: m.description,
+                domain: m.domain,
+                model: m.model ?? null,
+                table: m.table,
+                entities: m.entities,
+                measures: m.measures,
+                dimensions: m.dimensions,
+                timeDimensions: m.timeDimensions,
+                tags: m.tags ?? [],
+                owner: m.owner ?? null,
+                source: m.source ?? null,
+            }));
+            const savedQueries = semanticLayer.listSavedQueries().map((q) => ({
+                name: q.name,
+                label: q.label,
+                description: q.description,
+                domain: q.domain,
+                metrics: q.metrics,
+                dimensions: q.dimensions,
+                timeDimension: q.timeDimension ?? null,
+                granularity: q.granularity ?? null,
+                filters: q.filters ?? null,
+                tags: q.tags ?? [],
+                owner: q.owner ?? null,
+                source: q.source ?? null,
+            }));
+            const provider = projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? 'dql';
+            const dbtExecutionReady = provider === 'dbt'
+                ? hasDbtSemanticManifest(projectRoot, projectConfig.semanticLayer?.projectPath)
+                : false;
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                available: true,
+                provider,
+                execution: provider === 'dbt'
+                    ? {
+                        engine: 'metricflow',
+                        ready: dbtExecutionReady,
+                        setup: dbtExecutionReady
+                            ? null
+                            : 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists, and install MetricFlow so `mf` is on PATH.',
+                    }
+                    : { engine: 'native', ready: true, setup: null },
+                errors: semanticLayerErrors,
+                metrics,
+                measures,
+                dimensions,
+                timeDimensions,
+                entities,
+                hierarchies,
+                semanticModels,
+                savedQueries,
+                domains: semanticLayer.listDomains(),
+                tags: semanticLayer.listTags(),
+                favorites: userPrefs.favorites,
+                recentlyUsed: userPrefs.recentlyUsed,
+                lastSyncTime: semanticLastSyncTime,
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/semantic-layer/tree') {
+            if (!semanticLayer) {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    tree: {
+                        id: 'provider:dql',
+                        label: 'semantic layer',
+                        kind: 'provider',
+                        count: 0,
+                        children: [],
+                    },
+                }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                tree: buildSemanticTree(semanticLayer, semanticImportManifest),
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/semantic-layer/object/')) {
+            if (!semanticLayer) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'No semantic layer configured.' }));
+                return;
+            }
+            const id = decodeURIComponent(path.slice('/api/semantic-layer/object/'.length));
+            const detail = buildSemanticObjectDetail(semanticLayer, semanticImportManifest, id);
+            if (!detail) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: `Unknown semantic object: ${id}` }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON(detail));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-layer/import') {
+            try {
+                const body = await readJSON(req);
+                const provider = body.provider;
+                if (provider !== 'dbt' && provider !== 'cubejs' && provider !== 'snowflake') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'provider must be one of dbt, cubejs, snowflake' }));
+                    return;
+                }
+                const sourceConfig = provider === 'snowflake'
+                    ? {
+                        provider,
+                        projectPath: body.projectPath ?? projectConfig.semanticLayer?.projectPath,
+                        connection: body.connection ?? projectConfig.semanticLayer?.connection,
+                    }
+                    : {
+                        provider,
+                        projectPath: typeof body.projectPath === 'string' ? body.projectPath : projectConfig.semanticLayer?.projectPath,
+                        repoUrl: typeof body.repoUrl === 'string' ? body.repoUrl : projectConfig.semanticLayer?.repoUrl,
+                        branch: typeof body.branch === 'string' ? body.branch : projectConfig.semanticLayer?.branch,
+                        subPath: typeof body.subPath === 'string' ? body.subPath : projectConfig.semanticLayer?.subPath,
+                        source: body.repoUrl || projectConfig.semanticLayer?.repoUrl
+                            ? (body.source ?? projectConfig.semanticLayer?.source ?? 'github')
+                            : 'local',
+                    };
+                const executeQuery = provider === 'snowflake'
+                    ? async (sql) => {
+                        const result = await executor.executeQuery(sql, [], {}, connection);
+                        return { rows: result.rows };
+                    }
+                    : undefined;
+                const importResult = await performSemanticImport({
+                    targetProjectRoot: projectRoot,
+                    provider,
+                    sourceConfig,
+                    executeQuery,
+                });
+                // Re-resolve using project's actual semantic config (not hardcoded 'dql')
+                const projSemConfig = loadProjectConfig(projectRoot)?.semanticLayer ?? { provider: 'dql', path: './semantic-layer' };
+                const refreshed = await resolveSemanticLayerAsync(projSemConfig, projectRoot);
+                semanticLayer = refreshed.layer;
+                semanticLayerErrors = refreshed.errors;
+                semanticDetectedProvider = refreshed.detectedProvider ?? 'dql';
+                semanticLastSyncTime = importResult.manifest.importedAt;
+                semanticImportManifest = importResult.manifest;
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(importResult));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const hint = message.includes('conflict')
+                    ? 'A file conflict was detected. Remove or rename the conflicting file and retry.'
+                    : message.includes('dbt_project.yml')
+                        ? 'Ensure your dbt project path contains a valid dbt_project.yml file.'
+                        : message.includes('query executor')
+                            ? 'A Snowflake connection is required. Configure one in the Connection panel first.'
+                            : 'Check the provider path and ensure the source files are accessible.';
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: message, hint }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-layer/sync') {
+            try {
+                const executeQuery = semanticImportManifest?.provider === 'snowflake'
+                    ? async (sql) => {
+                        const result = await executor.executeQuery(sql, [], {}, connection);
+                        return { rows: result.rows };
+                    }
+                    : undefined;
+                const importResult = await syncSemanticImport({
+                    targetProjectRoot: projectRoot,
+                    executeQuery,
+                });
+                // Re-resolve using project's actual semantic config (not hardcoded 'dql')
+                const projSemConfig = loadProjectConfig(projectRoot)?.semanticLayer ?? { provider: 'dql', path: './semantic-layer' };
+                const refreshed = await resolveSemanticLayerAsync(projSemConfig, projectRoot);
+                semanticLayer = refreshed.layer;
+                semanticLayerErrors = refreshed.errors;
+                semanticDetectedProvider = refreshed.detectedProvider ?? 'dql';
+                semanticLastSyncTime = importResult.manifest.importedAt;
+                semanticImportManifest = importResult.manifest;
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(importResult));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const hint = message.includes('No semantic import manifest')
+                    ? 'No previous import found. Use the Setup Wizard to import a semantic layer first.'
+                    : 'Check the source configuration and retry.';
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: message, hint }));
+            }
+            return;
+        }
+        // ── Semantic layer import preview (dry-run) ──────────────────────────
+        if (req.method === 'POST' && path === '/api/semantic-layer/import-preview') {
+            try {
+                const body = await readJSON(req);
+                const provider = body.provider;
+                if (provider !== 'dbt' && provider !== 'cubejs' && provider !== 'snowflake') {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'provider must be one of dbt, cubejs, snowflake' }));
+                    return;
+                }
+                const sourceConfig = provider === 'snowflake'
+                    ? {
+                        provider,
+                        projectPath: body.projectPath ?? projectConfig.semanticLayer?.projectPath,
+                        connection: body.connection ?? projectConfig.semanticLayer?.connection,
+                    }
+                    : {
+                        provider,
+                        projectPath: typeof body.projectPath === 'string' ? body.projectPath : projectConfig.semanticLayer?.projectPath,
+                        repoUrl: typeof body.repoUrl === 'string' ? body.repoUrl : projectConfig.semanticLayer?.repoUrl,
+                        branch: typeof body.branch === 'string' ? body.branch : projectConfig.semanticLayer?.branch,
+                        subPath: typeof body.subPath === 'string' ? body.subPath : projectConfig.semanticLayer?.subPath,
+                        source: body.repoUrl || projectConfig.semanticLayer?.repoUrl
+                            ? (body.source ?? projectConfig.semanticLayer?.source ?? 'github')
+                            : 'local',
+                    };
+                const executeQuery = provider === 'snowflake'
+                    ? async (sql) => {
+                        const result = await executor.executeQuery(sql, [], {}, connection);
+                        return { rows: result.rows };
+                    }
+                    : undefined;
+                const preview = await previewSemanticImport({
+                    targetProjectRoot: projectRoot,
+                    provider,
+                    sourceConfig,
+                    executeQuery,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(preview));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const hint = message.includes('dbt_project.yml')
+                    ? 'Ensure your dbt project path contains a valid dbt_project.yml file.'
+                    : message.includes('model/') || message.includes('schema/')
+                        ? 'Ensure your Cube.js project has a model/ or schema/ directory.'
+                        : message.includes('query executor')
+                            ? 'A Snowflake connection is required. Configure one in the Connection panel first.'
+                            : 'Check the provider path and ensure the source files are accessible.';
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: message, hint }));
+            }
+            return;
+        }
+        // ── Semantic layer sync diff preview ────────────────────────────────
+        if (req.method === 'POST' && path === '/api/semantic-layer/sync-preview') {
+            try {
+                const executeQuery = semanticImportManifest?.provider === 'snowflake'
+                    ? async (sql) => {
+                        const result = await executor.executeQuery(sql, [], {}, connection);
+                        return { rows: result.rows };
+                    }
+                    : undefined;
+                const diff = await computeSyncDiff({
+                    targetProjectRoot: projectRoot,
+                    executeQuery,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(diff));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/semantic-layer/search') {
+            if (!semanticLayer) {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ metrics: [], measures: [], dimensions: [], timeDimensions: [], entities: [], hierarchies: [], semanticModels: [], savedQueries: [] }));
+                return;
+            }
+            const q = url.searchParams.get('q') ?? '';
+            const domain = url.searchParams.get('domain') ?? '';
+            const tag = url.searchParams.get('tag') ?? '';
+            const type = url.searchParams.get('type') ?? '';
+            const results = semanticLayer.searchAdvanced(q, {
+                domains: domain ? [domain] : undefined,
+                tags: tag ? [tag] : undefined,
+                types: ['metric', 'measure', 'dimension', 'hierarchy', 'entity', 'semantic_model', 'saved_query'].includes(type) ? [type] : undefined,
+            });
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                metrics: results.metrics.map((m) => ({
+                    name: m.name,
+                    label: m.label,
+                    description: m.description,
+                    domain: m.domain,
+                    sql: m.sql,
+                    type: m.type,
+                    table: m.table,
+                    tags: m.tags ?? [],
+                    owner: m.owner ?? null,
+                })),
+                measures: results.measures.map((m) => ({
+                    name: m.name,
+                    label: m.label,
+                    description: m.description,
+                    domain: m.domain,
+                    agg: m.agg,
+                    expr: m.expr,
+                    table: m.table,
+                    cube: m.cube,
+                    tags: m.tags ?? [],
+                    owner: m.owner ?? null,
+                })),
+                dimensions: results.dimensions.map((d) => ({
+                    name: d.name,
+                    label: d.label,
+                    description: d.description,
+                    domain: d.domain,
+                    sql: d.sql,
+                    type: d.type,
+                    table: d.table,
+                    tags: d.tags ?? [],
+                    owner: d.owner ?? null,
+                })),
+                timeDimensions: semanticLayer.listTimeDimensions().filter((d) => results.dimensions.some((dim) => dim.name === d.name)).map((d) => ({
+                    name: d.name,
+                    label: d.label,
+                    description: d.description,
+                    domain: d.domain,
+                    sql: d.sql,
+                    type: d.type,
+                    table: d.table,
+                    tags: d.tags ?? [],
+                    owner: d.owner ?? null,
+                })),
+                entities: results.entities.map((e) => ({
+                    name: e.name,
+                    label: e.label,
+                    description: e.description,
+                    domain: e.domain,
+                    type: e.type,
+                    table: e.table,
+                    tags: e.tags ?? [],
+                    owner: e.owner ?? null,
+                })),
+                hierarchies: results.hierarchies.map((h) => ({
+                    name: h.name,
+                    label: h.label,
+                    description: h.description,
+                    domain: h.domain,
+                    levels: h.levels.map((l) => ({ name: l.name, label: l.label })),
+                })),
+                semanticModels: results.semanticModels.map((m) => ({
+                    name: m.name,
+                    label: m.label,
+                    description: m.description,
+                    domain: m.domain,
+                    table: m.table,
+                    measures: m.measures,
+                    dimensions: m.dimensions,
+                    timeDimensions: m.timeDimensions,
+                })),
+                savedQueries: results.savedQueries.map((q) => ({
+                    name: q.name,
+                    label: q.label,
+                    description: q.description,
+                    domain: q.domain,
+                    metrics: q.metrics,
+                    dimensions: q.dimensions,
+                })),
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/semantic-layer/compatible-dims') {
+            if (!semanticLayer) {
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ dimensions: [] }));
+                return;
+            }
+            const metrics = (url.searchParams.get('metrics') ?? '')
+                .split(',')
+                .map((value) => value.trim())
+                .filter(Boolean);
+            const dimensions = semanticLayer.listCompatibleDimensions(metrics).map((d) => ({
+                name: d.name,
+                label: d.label,
+                description: d.description,
+                domain: d.domain,
+                sql: d.sql,
+                type: d.type,
+                table: d.table,
+                tags: d.tags ?? [],
+                owner: d.owner ?? null,
+            }));
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ dimensions }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/user-prefs/favorites') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ favorites: readUserPrefs(userPrefsPath).favorites }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/user-prefs/favorites') {
+            try {
+                const body = await readJSON(req);
+                const prefs = readUserPrefs(userPrefsPath);
+                const name = typeof body.name === 'string' ? body.name.trim() : '';
+                if (name) {
+                    prefs.favorites = prefs.favorites.includes(name)
+                        ? prefs.favorites.filter((item) => item !== name)
+                        : [...prefs.favorites, name].sort((a, b) => a.localeCompare(b));
+                    writeUserPrefs(userPrefsPath, prefs);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ favorites: prefs.favorites }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/user-prefs/recent') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ recentlyUsed: readUserPrefs(userPrefsPath).recentlyUsed }));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/user-prefs/recent') {
+            try {
+                const body = await readJSON(req);
+                const prefs = readUserPrefs(userPrefsPath);
+                const name = typeof body.name === 'string' ? body.name.trim() : '';
+                if (name) {
+                    prefs.recentlyUsed = [name, ...prefs.recentlyUsed.filter((item) => item !== name)].slice(0, 12);
+                    writeUserPrefs(userPrefsPath, prefs);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ recentlyUsed: prefs.recentlyUsed }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // ── Semantic completions for SQL cells ─────────────────────────────────────
+        if (req.method === 'GET' && path === '/api/semantic-completions') {
+            const completions = [];
+            if (semanticLayer) {
+                for (const m of semanticLayer.listMetrics()) {
+                    completions.push({
+                        type: 'metric',
+                        name: m.name,
+                        label: m.label,
+                        description: m.description ?? '',
+                        sql: m.sql,
+                        domain: m.domain,
+                        tags: m.tags ?? [],
+                    });
+                }
+                for (const d of semanticLayer.listDimensions()) {
+                    completions.push({
+                        type: 'dimension',
+                        name: d.name,
+                        label: d.label,
+                        description: d.description ?? '',
+                        sql: d.sql,
+                        domain: d.domain,
+                        tags: d.tags ?? [],
+                    });
+                }
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ completions }));
+            return;
+        }
+        // ── end dql-notebook API ──────────────────────────────────────────────────
+        // GET /api/describe-table?table=schema.table — returns columns for a specific table
+        if (req.method === 'GET' && path === '/api/describe-table') {
+            try {
+                const tablePath = url.searchParams.get('table') ?? '';
+                const schemaName = url.searchParams.get('schema') ?? undefined;
+                if (!tablePath) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing table parameter' }));
+                    return;
+                }
+                // Try connector.listColumns() first
+                let columns = [];
+                try {
+                    const connector = await executor.getConnector(connection);
+                    if (typeof connector.listColumns === 'function') {
+                        const rawCols = await connector.listColumns(schemaName, tablePath);
+                        columns = rawCols.map((c) => ({ name: c.name, type: c.dataType }));
+                    }
+                }
+                catch {
+                    // fallback below
+                }
+                // Fallback: DESCRIBE via SQL (works for DuckDB, PG)
+                if (columns.length === 0) {
+                    try {
+                        const isFile = /\.(csv|parquet|json)$/i.test(tablePath) || tablePath.startsWith('data/');
+                        const safePath = tablePath.replace(/'/g, "''");
+                        const qualifiedIdentifier = tablePath.split('.').map((p) => `"${p.replace(/"/g, '""')}"`).join('.');
+                        const sql = isFile
+                            ? `DESCRIBE SELECT * FROM read_csv_auto('${safePath}') LIMIT 0`
+                            : `DESCRIBE ${qualifiedIdentifier}`;
+                        const result = await executor.executeQuery(sql, [], {}, connection);
+                        columns = result.rows.map((row) => ({
+                            name: String(row['column_name'] ?? row['Field'] ?? ''),
+                            type: String(row['column_type'] ?? row['Type'] ?? ''),
+                        }));
+                    }
+                    catch {
+                        // empty columns
+                    }
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(columns));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/llm/run') {
+            const body = await readJSON(req).catch(() => null);
+            if (!body || typeof body !== 'object') {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Invalid JSON body' }));
+                return;
+            }
+            const { provider, messages, upstream } = body;
+            const runner = isLLMProviderId(provider) ? getLLMRunner(provider) : null;
+            if (!runner) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: `Unknown provider: ${provider}` }));
+                return;
+            }
+            if (!Array.isArray(messages) || messages.length === 0) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'messages[] required' }));
+                return;
+            }
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache, no-transform',
+                Connection: 'keep-alive',
+            });
+            const controller = new AbortController();
+            req.on('close', () => controller.abort());
+            const emit = (turn) => { res.write(`data: ${JSON.stringify(turn)}\n\n`); };
+            try {
+                await runner.run({ provider: provider, messages, upstream, projectRoot }, emit, controller.signal);
+            }
+            catch (err) {
+                emit({ kind: 'error', message: err instanceof Error ? err.message : String(err) });
+            }
+            res.end();
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/query') {
+            try {
+                const body = await readJSON(req);
+                if (typeof body.sql !== 'string' || body.sql.trim().length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ columns: [], rows: [], error: 'Missing SQL in request body.' }));
+                    return;
+                }
+                const semantic = prepareSemanticSql(body.sql, semanticLayer);
+                if (semantic.unresolvedRefs.length > 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        columns: [],
+                        rows: [],
+                        error: `Unknown semantic reference${semantic.unresolvedRefs.length > 1 ? 's' : ''}: ${semantic.unresolvedRefs.join(', ')}`,
+                        code: 'semantic_ref',
+                        unresolvedRefs: semantic.unresolvedRefs,
+                    }));
+                    return;
+                }
+                const prepared = prepareLocalExecution(semantic.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
+                const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
+                const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
+                assertAppAccess({ app, domain, level: 'execute' });
+                const result = await executor.executeQuery(prepared.sql, Array.isArray(body.sqlParams) ? body.sqlParams : [], runtimeVariables(body.variables && typeof body.variables === 'object' ? body.variables : {}), prepared.connection);
+                const payload = serializeJSON(normalizeQueryResult(result, semantic.semanticRefs));
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(payload);
+            }
+            catch (error) {
+                if (res.headersSent || res.writableEnded) {
+                    res.end();
+                    return;
+                }
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        columns: [],
+                        rows: [],
+                        error: error.message,
+                        code: 'unauthorized',
+                    }));
+                    return;
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    columns: [],
+                    rows: [],
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        // Semantic layer query endpoint: compose SQL from metrics/dimensions
+        if (req.method === 'POST' && path === '/api/semantic-query') {
+            try {
+                if (!semanticLayer) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'No semantic layer configured. Add YAML files to semantic-layer/ directory.' }));
+                    return;
+                }
+                const body = await readJSON(req);
+                const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
+                // Resolve which connection to use — request can override default
+                const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
+                const driver = targetConnection.driver;
+                // Build table mapping: resolve semantic model names to actual DB table names
+                let tableMapping;
+                try {
+                    const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema NOT IN ('information_schema', 'pg_catalog')`, [], {}, targetConnection);
+                    const dbTableNames = new Set();
+                    const schemaQualified = new Map();
+                    for (const row of tablesResult.rows) {
+                        const schema = String(row['table_schema'] ?? '');
+                        const name = String(row['table_name'] ?? '');
+                        dbTableNames.add(name);
+                        schemaQualified.set(name, schema ? `${schema}.${name}` : name);
+                    }
+                    // For each table in the semantic layer, map to qualified name if it exists
+                    const allSemanticTables = new Set();
+                    for (const m of semanticLayer.listMetrics())
+                        allSemanticTables.add(m.table);
+                    for (const d of semanticLayer.listDimensions())
+                        allSemanticTables.add(d.table);
+                    tableMapping = {};
+                    for (const semTable of allSemanticTables) {
+                        if (dbTableNames.has(semTable) && schemaQualified.has(semTable)) {
+                            tableMapping[semTable] = schemaQualified.get(semTable);
+                        }
+                    }
+                    if (Object.keys(tableMapping).length === 0)
+                        tableMapping = undefined;
+                }
+                catch {
+                    // Non-fatal: proceed without table mapping
+                }
+                const composed = composeRuntimeSemanticQuery({
+                    metrics,
+                    dimensions,
+                    filters,
+                    limit,
+                    timeDimension,
+                    orderBy,
+                    savedQuery,
+                    engine,
+                }, semanticLayer, {
+                    projectRoot,
+                    projectConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    driver,
+                    tableMapping,
+                });
+                if (!composed) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Could not compose query for metrics: [${metrics.join(', ')}]` }));
+                    return;
+                }
+                // Execute the composed SQL against the resolved connection
+                const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
+                const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    sql: composed.sql,
+                    tables: composed.tables,
+                    joins: composed.joins,
+                    engine: composed.engine,
+                    result: normalizeQueryResult(result),
+                }));
+            }
+            catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
+                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
+                    hint: error instanceof MetricFlowUnavailableError
+                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                        : undefined,
+                }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-builder/preview') {
+            try {
+                if (!semanticLayer) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'No semantic layer configured.' }));
+                    return;
+                }
+                const body = await readJSON(req);
+                const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
+                const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
+                const driver = targetConnection.driver;
+                let tableMapping;
+                try {
+                    const tablesResult = await executor.executeQuery(`SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema NOT IN ('information_schema', 'pg_catalog')`, [], {}, targetConnection);
+                    const schemaQualified = new Map();
+                    for (const row of tablesResult.rows) {
+                        const schema = String(row['table_schema'] ?? '');
+                        const name = String(row['table_name'] ?? '');
+                        schemaQualified.set(name, schema ? `${schema}.${name}` : name);
+                    }
+                    tableMapping = {};
+                    for (const metric of semanticLayer.listMetrics()) {
+                        if (schemaQualified.has(metric.table))
+                            tableMapping[metric.table] = schemaQualified.get(metric.table);
+                    }
+                    for (const dimension of semanticLayer.listDimensions()) {
+                        if (schemaQualified.has(dimension.table))
+                            tableMapping[dimension.table] = schemaQualified.get(dimension.table);
+                    }
+                    if (Object.keys(tableMapping).length === 0)
+                        tableMapping = undefined;
+                }
+                catch {
+                    tableMapping = undefined;
+                }
+                const composed = composeRuntimeSemanticQuery({
+                    metrics,
+                    dimensions,
+                    filters,
+                    limit,
+                    timeDimension,
+                    orderBy,
+                    savedQuery,
+                    engine,
+                }, semanticLayer, {
+                    projectRoot,
+                    projectConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    driver,
+                    tableMapping,
+                });
+                if (!composed) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Could not compose semantic block preview SQL.' }));
+                    return;
+                }
+                const prepared = prepareLocalExecution(composed.sql, targetConnection, projectRoot, projectConfig);
+                const result = await executor.executeQuery(prepared.sql, [], {}, prepared.connection);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    sql: composed.sql,
+                    joins: composed.joins,
+                    tables: composed.tables,
+                    engine: composed.engine,
+                    result: normalizeQueryResult(result),
+                }));
+            }
+            catch (error) {
+                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
+                    hint: error instanceof MetricFlowUnavailableError
+                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                        : undefined,
+                }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/semantic-builder/save') {
+            try {
+                if (!semanticLayer) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'No semantic layer configured.' }));
+                    return;
+                }
+                const body = await readJSON(req);
+                const { name, domain, description, owner, tags, metrics = [], dimensions = [], timeDimension, filters = [], chart = 'table', blockType = 'semantic', engine, } = body;
+                if (!name || metrics.length === 0) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'name and at least one metric are required.' }));
+                    return;
+                }
+                const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
+                const composed = composeRuntimeSemanticQuery({
+                    metrics,
+                    dimensions,
+                    filters,
+                    timeDimension,
+                    engine,
+                }, semanticLayer, {
+                    projectRoot,
+                    projectConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    driver: targetConnection.driver,
+                });
+                if (!composed) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Could not compose semantic block SQL.' }));
+                    return;
+                }
+                const created = createSemanticBuilderBlock(projectRoot, {
+                    name,
+                    domain,
+                    description,
+                    owner,
+                    tags,
+                    metrics,
+                    dimensions,
+                    timeDimension,
+                    chart,
+                    blockType,
+                    sql: composed.sql,
+                    tables: composed.tables,
+                    provider: semanticImportManifest?.provider ?? semanticDetectedProvider ?? 'dql',
+                });
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(created));
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'BLOCK_EXISTS') {
+                    res.writeHead(409, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Block already exists' }));
+                    return;
+                }
+                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
+                    hint: error instanceof MetricFlowUnavailableError
+                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                        : undefined,
+                }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/test-connection') {
+            try {
+                const body = await readJSON(req);
+                const target = normalizeProjectConnection(isConnectionConfig(body.connection) ? body.connection : connection, projectRoot);
+                const connector = await executor.getConnector(target);
+                const ok = await connector.ping();
+                const driver = target.driver ?? 'unknown';
+                res.writeHead(ok ? 200 : 400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    ok,
+                    message: ok ? `Connected to ${driver} successfully` : `Connection to ${driver} failed`,
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    ok: false,
+                    message: error instanceof Error ? error.message : String(error),
+                }));
+            }
+            return;
+        }
+        // ---- Lineage API ----
+        if (req.method === 'GET' && path === '/api/lineage') {
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(graph.toJSON()));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/lineage/search') {
+            const term = url.searchParams.get('q') ?? '';
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const result = queryLineage(graph, { search: term });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ matches: result.matches ?? [] }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/lineage/query') {
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const types = url.searchParams.get('types')
+                    ?.split(',')
+                    .map((value) => value.trim())
+                    .filter(Boolean);
+                const upstreamDepthParam = url.searchParams.get('upstreamDepth');
+                const downstreamDepthParam = url.searchParams.get('downstreamDepth');
+                const result = queryLineage(graph, {
+                    focus: url.searchParams.get('focus') ?? undefined,
+                    search: url.searchParams.get('search') ?? undefined,
+                    types,
+                    domain: url.searchParams.get('domain') ?? undefined,
+                    upstreamDepth: upstreamDepthParam ? Number(upstreamDepthParam) : undefined,
+                    downstreamDepth: downstreamDepthParam ? Number(downstreamDepthParam) : undefined,
+                });
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/lineage/node/')) {
+            const rawNodeId = decodeURIComponent(path.slice('/api/lineage/node/'.length));
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const node = resolveLineageNode(graph, rawNodeId);
+                if (!node) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Lineage node "${rawNodeId}" not found` }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    node,
+                    incoming: graph.getIncomingEdges(node.id).map((edge) => ({
+                        edge,
+                        node: graph.getNode(edge.source),
+                    })),
+                    outgoing: graph.getOutgoingEdges(node.id).map((edge) => ({
+                        edge,
+                        node: graph.getNode(edge.target),
+                    })),
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/lineage/domain/')) {
+            const domain = decodeURIComponent(path.slice('/api/lineage/domain/'.length));
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const overview = getDomainTrustOverview(graph, domain);
+                const nodes = graph.getNodesByDomain(domain);
+                const flows = detectDomainFlows(graph);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    domain,
+                    overview,
+                    nodes,
+                    inFlows: flows.filter((f) => f.to === domain),
+                    outFlows: flows.filter((f) => f.from === domain),
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/lineage/impact/')) {
+            const blockName = decodeURIComponent(path.slice('/api/lineage/impact/'.length));
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const nodeId = `block:${blockName}`;
+                if (!graph.getNode(nodeId)) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Block "${blockName}" not found` }));
+                    return;
+                }
+                const impact = analyzeImpact(graph, nodeId);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(impact));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/lineage/block/')) {
+            const blockName = decodeURIComponent(path.slice('/api/lineage/block/'.length));
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const nodeId = `block:${blockName}`;
+                const node = graph.getNode(nodeId);
+                if (!node) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Block "${blockName}" not found` }));
+                    return;
+                }
+                const ancestors = graph.ancestors(nodeId);
+                const descendants = graph.descendants(nodeId);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ node, ancestors, descendants }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path.startsWith('/api/lineage/paths/')) {
+            const rawNodeId = decodeURIComponent(path.slice('/api/lineage/paths/'.length));
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const maxDepth = Number(url.searchParams.get('maxDepth') ?? '10') || 10;
+                const maxPaths = Number(url.searchParams.get('maxPaths') ?? '20') || 20;
+                const result = queryCompleteLineagePaths(graph, rawNodeId, { maxDepth, maxPaths });
+                if (!result) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Node "${rawNodeId}" not found` }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(result));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/lineage/trust-chain') {
+            const from = url.searchParams.get('from');
+            const to = url.searchParams.get('to');
+            if (!from || !to) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Missing "from" and "to" query parameters' }));
+                return;
+            }
+            try {
+                const graph = buildProjectLineageGraph(projectRoot, semanticLayer);
+                const chain = buildTrustChain(graph, `block:${from}`, `block:${to}`);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON(chain ?? { error: 'No path found' }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/notebook/bootstrap') {
+            const welcomeNotebook = resolveNotebook(projectRoot, projectConfig.project ?? 'DQL Project');
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({
+                projectRoot,
+                project: projectConfig.project ?? 'DQL Project',
+                defaultConnection: projectConfig.defaultConnection ?? connection,
+                connectorForms: getConnectorFormSchemas(),
+                files: listProjectFiles(projectRoot),
+                notebook: welcomeNotebook,
+            }));
+            return;
+        }
+        if (req.method === 'GET' && path === '/api/notebook/file') {
+            const relativePath = url.searchParams.get('path');
+            if (!relativePath) {
+                res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: 'Missing file path.' }));
+                return;
+            }
+            const filePath = safeJoin(projectRoot, relativePath);
+            if (!filePath || !existsSync(filePath) || statSync(filePath).isDirectory()) {
+                res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: `File not found: ${relativePath}` }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
+            res.end(readFileSync(filePath));
+            return;
+        }
+        if (req.method === 'POST' && path === '/api/notebook/execute') {
+            try {
+                const body = await readJSON(req);
+                const cell = normalizeNotebookCell(body.cell);
+                if (!cell) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'Missing notebook cell payload.' }));
+                    return;
+                }
+                const cellConnection = isConnectionConfig(body.connection) ? body.connection : connection;
+                const plan = buildExecutionPlan(cell, { semanticLayer, driver: cellConnection.driver });
+                if (!plan) {
+                    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ cellType: cell.type, result: null }));
+                    return;
+                }
+                const prepared = prepareLocalExecution(plan.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
+                const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
+                assertAppAccess({ app, domain: app?.domain, level: 'execute' });
+                const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables(plan.variables), prepared.connection);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    cellType: cell.type,
+                    title: plan.title,
+                    chartConfig: plan.chartConfig,
+                    tests: plan.tests,
+                    result: normalizeQueryResult(rawResult),
+                }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        // Create a new metric YAML file in semantic-layer/metrics/
+        if (req.method === 'POST' && path === '/api/semantic-layer/metric') {
+            try {
+                const body = await readJSON(req);
+                const { name, label, description, domain, sql, type, table, tags } = body;
+                if (!name || !sql || !type || !table) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'name, sql, type, and table are required' }));
+                    return;
+                }
+                const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+                const metricsDir = join(projectRoot, 'semantic-layer', 'metrics');
+                mkdirSync(metricsDir, { recursive: true });
+                const filePath = join(metricsDir, `${slug}.yaml`);
+                const tagList = Array.isArray(tags) && tags.length > 0
+                    ? `\ntags:\n${tags.map(t => `  - ${t}`).join('\n')}`
+                    : '';
+                const yaml = `name: ${slug}
+label: ${label || name}
+description: ${description || ''}
+domain: ${domain || 'general'}
+sql: ${sql}
+type: ${type}
+table: ${table}${tagList}
+`;
+                writeFileSync(filePath, yaml, 'utf-8');
+                res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ ok: true, path: `semantic-layer/metrics/${slug}.yaml` }));
+            }
+            catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            return;
+        }
+        if (req.method !== 'GET') {
+            res.writeHead(405, { 'Content-Type': 'text/plain; charset=utf-8' });
+            res.end('Method not allowed');
+            return;
+        }
+        const requestedPath = path === '/' ? '/index.html' : path;
+        const filePath = safeJoin(rootDir, requestedPath);
+        if (!filePath || !existsSync(filePath) || statSync(filePath).isDirectory()) {
+            res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(renderNotFound(path));
+            return;
+        }
+        const content = readFileSync(filePath);
+        res.writeHead(200, { 'Content-Type': contentTypeFor(filePath) });
+        res.end(content);
+    });
+    return new Promise((resolvePromise, reject) => {
+        let retriedWithRandomPort = false;
+        server.on('error', (error) => {
+            if (error.code === 'EADDRINUSE' && !retriedWithRandomPort) {
+                retriedWithRandomPort = true;
+                server.listen(0, bindHost);
+                return;
+            }
+            reject(error);
+        });
+        server.listen(preferredPort, bindHost, () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('Failed to resolve local server address.'));
+                return;
+            }
+            resolvePromise(address.port);
+        });
+    });
+}
+export async function assertLocalQueryRuntimeReady(executor, connection) {
+    try {
+        const connector = await executor.getConnector(connection);
+        const ok = await connector.ping();
+        if (!ok) {
+            throw new Error(`Connection check failed for driver "${connection.driver}".`);
+        }
+    }
+    catch (error) {
+        throw new Error(formatLocalQueryRuntimeError(connection, error));
+    }
+}
+export function formatLocalQueryRuntimeError(connection, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const driver = connection.driver;
+    const currentNode = process.versions.node;
+    if ((driver === 'file' || driver === 'duckdb') &&
+        detail.includes('duckdb.node')) {
+        return `Local query runtime is unavailable for driver "${driver}": DuckDB native bindings could not be loaded. Current Node.js runtime: ${currentNode}. Reinstall dependencies with a supported LTS Node release (for example Node 18, 20, or 22), then rerun "pnpm install". Original error: ${detail}`;
+    }
+    return `Local query runtime is unavailable for driver "${driver}": ${detail}`;
+}
+/**
+ * Normalize connector QueryResult → SPA-friendly shape.
+ * Connector returns columns as ColumnMeta[] ({name,type,driverType}).
+ * The notebook SPA expects columns as string[] (just names).
+ */
+function normalizeQueryResult(result, semanticRefs) {
+    const rawCols = Array.isArray(result?.columns) ? result.columns : [];
+    const columns = rawCols.map((c) => typeof c === 'string' ? c : typeof c?.name === 'string' ? c.name : String(c));
+    const hasRefs = semanticRefs && (semanticRefs.metrics.length > 0 || semanticRefs.dimensions.length > 0);
+    return {
+        columns,
+        rows: Array.isArray(result?.rows) ? result.rows : [],
+        rowCount: typeof result?.rowCount === 'number' ? result.rowCount : (result?.rows?.length ?? 0),
+        executionTime: typeof result?.executionTimeMs === 'number'
+            ? result.executionTimeMs
+            : typeof result?.executionTime === 'number'
+                ? result.executionTime
+                : 0,
+        ...(hasRefs ? { semanticRefs } : {}),
+    };
+}
+function isLLMProviderId(value) {
+    return value === 'claude-agent-sdk'
+        || value === 'claude-code'
+        || value === 'openai'
+        || value === 'gemini'
+        || value === 'ollama';
+}
+function loadAppDashboard(projectRoot, appId, dashboardId) {
+    for (const p of findAppDocuments(projectRoot)) {
+        const { document: app } = loadAppDocument(p);
+        if (!app || app.id !== appId)
+            continue;
+        const appDir = p.slice(0, -'/dql.app.json'.length);
+        for (const d of findDashboardsForApp(appDir)) {
+            const { document: dashboard } = loadDashboardDocument(d);
+            if (dashboard?.id === dashboardId)
+                return { app, dashboard };
+        }
+    }
+    return null;
+}
+function resolveDashboardItemBlock(item, manifest) {
+    if (isBlockIdRef(item.block)) {
+        return manifest.blocks[item.block.blockId] ?? null;
+    }
+    const normalizedRef = normalize(item.block.ref).replaceAll('\\', '/');
+    return Object.values(manifest.blocks).find((b) => normalize(b.filePath).replaceAll('\\', '/') === normalizedRef) ?? null;
+}
+export function serializeJSON(value) {
+    return JSON.stringify(value, (_key, current) => {
+        if (typeof current === 'bigint') {
+            const asNumber = Number(current);
+            return Number.isSafeInteger(asNumber) ? asNumber : current.toString();
+        }
+        return current;
+    });
+}
+function renderNotFound(path) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>DQL Local Runtime</title>
+    <style>
+      body { font-family: Inter, system-ui, sans-serif; margin: 40px; color: #111827; }
+      code { background: #f3f4f6; padding: 2px 6px; border-radius: 6px; }
+    </style>
+  </head>
+  <body>
+    <h1>DQL Local Runtime</h1>
+    <p>No file exists for <code>${escapeHtml(path)}</code>.</p>
+    <p>Try opening <code>/</code> or confirm that you built the bundle correctly.</p>
+  </body>
+</html>`;
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, 'dql.config.json'))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return startDir;
+        }
+        current = parent;
+    }
+}
+export function loadProjectConfig(projectRoot) {
+    const configPath = join(projectRoot, 'dql.config.json');
+    if (!existsSync(configPath)) {
+        return {};
+    }
+    const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+    const config = raw;
+    // Normalize modern `connections.default` format to `defaultConnection`
+    if (!config.defaultConnection && raw.connections) {
+        const connections = raw.connections;
+        const defaultConn = connections.default;
+        if (defaultConn?.driver) {
+            // Support both `filepath` (correct) and `path` (legacy/init compat)
+            const filepath = (defaultConn.filepath ?? defaultConn.path);
+            config.defaultConnection = {
+                driver: defaultConn.driver,
+                ...(filepath ? { filepath } : {}),
+            };
+        }
+    }
+    return config;
+}
+export function prepareLocalExecution(sql, connection, projectRoot, projectConfig) {
+    const normalizedConnection = normalizeProjectConnection(connection, projectRoot);
+    return {
+        sql: shouldResolveProjectPaths(normalizedConnection)
+            ? resolveProjectRelativeSqlPaths(sql, projectRoot, projectConfig.dataDir)
+            : sql,
+        connection: normalizedConnection,
+    };
+}
+/**
+ * Shared resolver for `@metric(name)` / `@dim(name)` refs in raw SQL.
+ * Used by notebook SQL execution and Block Studio validation so both paths
+ * behave identically. If the SQL has no refs, returns it unchanged.
+ */
+export function prepareSemanticSql(sql, semanticLayer) {
+    if (!hasSemanticRefs(sql)) {
+        return { sql, semanticRefs: { metrics: [], dimensions: [] }, unresolvedRefs: [] };
+    }
+    const resolution = resolveSemanticRefs(sql, semanticLayer);
+    return {
+        sql: resolution.resolvedSql,
+        semanticRefs: {
+            metrics: resolution.resolvedMetrics,
+            dimensions: resolution.resolvedDimensions,
+        },
+        unresolvedRefs: resolution.unresolvedRefs,
+    };
+}
+export function normalizeProjectConnection(connection, projectRoot) {
+    const normalized = { ...connection };
+    if ((normalized.driver === 'file' || normalized.driver === 'duckdb') && normalized.filepath && normalized.filepath !== ':memory:' && !isAbsoluteLikePath(normalized.filepath)) {
+        normalized.filepath = resolve(projectRoot, normalized.filepath);
+    }
+    if (normalized.driver === 'sqlite' && normalized.database && normalized.database !== ':memory:' && !isAbsoluteLikePath(normalized.database)) {
+        normalized.database = resolve(projectRoot, normalized.database);
+    }
+    return normalized;
+}
+export function resolveProjectRelativeSqlPaths(sql, projectRoot, dataDir) {
+    const resolvedRoot = resolve(projectRoot);
+    const normalizedDataDir = typeof dataDir === 'string' && dataDir.trim().length > 0
+        ? resolve(projectRoot, dataDir)
+        : join(resolvedRoot, 'data');
+    return sql.replace(/\b(read_csv_auto|read_csv|read_parquet|read_json_auto|read_json|read_ndjson_auto|read_ndjson|read_xlsx|parquet_scan)\s*\(\s*(['"])(\.{1,2}\/[^'"]*)\2/gi, (_match, fnName, quote, relativePath) => {
+        const absolutePath = relativePath.startsWith('./data/')
+            ? join(normalizedDataDir, relativePath.slice('./data/'.length))
+            : resolve(resolvedRoot, relativePath);
+        return `${fnName}(${quote}${absolutePath.replaceAll('\\', '/')}${quote}`;
+    });
+}
+function shouldResolveProjectPaths(connection) {
+    return connection.driver === 'file' || connection.driver === 'duckdb' || connection.driver === 'sqlite';
+}
+function isAbsoluteLikePath(value) {
+    return value.startsWith('/') || value.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(value);
+}
+function readJSON(req) {
+    return new Promise((resolvePromise, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        req.on('end', () => {
+            try {
+                const raw = Buffer.concat(chunks).toString('utf-8');
+                resolvePromise(raw ? JSON.parse(raw) : {});
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function safeJoin(rootDir, requestPath) {
+    const normalized = normalize(requestPath).replace(/^([.][.][/\\])+/, '');
+    const fullPath = resolve(rootDir, `.${normalized.startsWith('/') ? normalized : `/${normalized}`}`);
+    const resolvedRoot = resolve(rootDir);
+    return fullPath.startsWith(resolvedRoot) ? fullPath : null;
+}
+function contentTypeFor(filePath) {
+    switch (extname(filePath)) {
+        case '.html':
+            return 'text/html; charset=utf-8';
+        case '.json':
+            return 'application/json; charset=utf-8';
+        case '.js':
+            return 'application/javascript; charset=utf-8';
+        case '.css':
+            return 'text/css; charset=utf-8';
+        case '.svg':
+            return 'image/svg+xml';
+        case '.woff2':
+            return 'font/woff2';
+        case '.woff':
+            return 'font/woff';
+        default:
+            return 'text/plain; charset=utf-8';
+    }
+}
+function listProjectFiles(projectRoot) {
+    const allowed = new Set(['.dql', '.sql', '.md', '.json', '.csv', '.yaml', '.yml', '.dqlnb']);
+    const files = [];
+    walk(projectRoot);
+    return files.sort();
+    function walk(currentDir) {
+        for (const entry of readdirSync(currentDir)) {
+            if (entry === 'node_modules' || entry === '.git' || entry === 'dist') {
+                continue;
+            }
+            const fullPath = join(currentDir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+                continue;
+            }
+            if (allowed.has(extname(entry))) {
+                files.push(fullPath.slice(projectRoot.length + 1));
+            }
+        }
+    }
+}
+function resolveNotebook(projectRoot, projectTitle) {
+    const notebookPath = join(projectRoot, 'notebooks', 'welcome.dqlnb');
+    if (existsSync(notebookPath)) {
+        return deserializeNotebook(readFileSync(notebookPath, 'utf-8'));
+    }
+    return createWelcomeNotebook('starter', projectTitle);
+}
+function normalizeNotebookCell(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const candidate = value;
+    if (typeof candidate.id !== 'string' || typeof candidate.type !== 'string' || typeof candidate.source !== 'string') {
+        return null;
+    }
+    return {
+        id: candidate.id,
+        type: candidate.type,
+        source: candidate.source,
+        title: typeof candidate.title === 'string' ? candidate.title : undefined,
+        config: candidate.config,
+    };
+}
+function isConnectionConfig(value) {
+    return Boolean(value && typeof value === 'object' && 'driver' in value);
+}
+function scanNotebookFiles(projectRoot) {
+    const result = [];
+    const folderMap = {
+        notebooks: 'notebook',
+        workbooks: 'workbook',
+        blocks: 'block',
+        dashboards: 'dashboard',
+    };
+    for (const [folder, type] of Object.entries(folderMap)) {
+        const dir = join(projectRoot, folder);
+        if (!existsSync(dir))
+            continue;
+        collect(dir, folder, type);
+    }
+    return result;
+    function collect(currentDir, relativeDir, type) {
+        try {
+            for (const entry of readdirSync(currentDir, { withFileTypes: true })) {
+                const fullPath = join(currentDir, entry.name);
+                const relativePath = `${relativeDir}/${entry.name}`;
+                if (entry.isDirectory()) {
+                    collect(fullPath, relativePath, type);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.dql') && !entry.name.endsWith('.dqlnb'))
+                    continue;
+                result.push({
+                    name: entry.name.replace(/\.(dql|dqlnb)$/, ''),
+                    path: relativePath,
+                    type,
+                    folder: relativeDir.split('/')[0] ?? relativeDir,
+                });
+            }
+        }
+        catch { /* skip unreadable dirs */ }
+    }
+}
+function scanDataFiles(projectRoot) {
+    const dataDir = join(projectRoot, 'data');
+    if (!existsSync(dataDir))
+        return [];
+    try {
+        return readdirSync(dataDir, { withFileTypes: true })
+            .filter((e) => e.isFile() && /\.(csv|parquet|json)$/.test(e.name))
+            .map((e) => ({ name: e.name, path: `data/${e.name}`, columns: [] }));
+    }
+    catch {
+        return [];
+    }
+}
+function readUserPrefs(userPrefsPath) {
+    try {
+        if (!existsSync(userPrefsPath)) {
+            return { favorites: [], recentlyUsed: [] };
+        }
+        const raw = JSON.parse(readFileSync(userPrefsPath, 'utf-8'));
+        return {
+            favorites: Array.isArray(raw.favorites) ? raw.favorites.map(String) : [],
+            recentlyUsed: Array.isArray(raw.recentlyUsed) ? raw.recentlyUsed.map(String) : [],
+        };
+    }
+    catch {
+        return { favorites: [], recentlyUsed: [] };
+    }
+}
+function writeUserPrefs(userPrefsPath, prefs) {
+    writeFileSync(userPrefsPath, JSON.stringify(prefs, null, 2) + '\n', 'utf-8');
+}
+async function introspectSchema(executor, connection) {
+    let tables = [];
+    let columnsByPath = new Map();
+    // Tier 1: information_schema (PG, MySQL, Snowflake, MSSQL, DuckDB, Redshift, Fabric, Databricks)
+    try {
+        const catalogRows = await executor.executeQuery(`SELECT table_schema, table_name, table_type
+       FROM information_schema.tables
+       WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
+       ORDER BY table_schema, table_name`, [], {}, connection);
+        tables = catalogRows.rows.map((row) => {
+            const schema = String(row['table_schema'] ?? row['TABLE_SCHEMA'] ?? 'default');
+            const name = String(row['table_name'] ?? row['TABLE_NAME'] ?? '');
+            const type = String(row['table_type'] ?? row['TABLE_TYPE'] ?? 'TABLE');
+            const path = schema ? `${schema}.${name}` : name;
+            return { schema, name, path, type };
+        });
+        const columnRows = await executor.executeQuery(`SELECT table_schema, table_name, column_name, data_type
+       FROM information_schema.columns
+       WHERE table_schema NOT IN ('information_schema', 'pg_catalog')
+       ORDER BY table_schema, table_name, ordinal_position`, [], {}, connection);
+        columnsByPath = columnRows.rows.reduce((map, row) => {
+            const schema = String(row['table_schema'] ?? row['TABLE_SCHEMA'] ?? 'default');
+            const tableName = String(row['table_name'] ?? row['TABLE_NAME'] ?? '');
+            const path = schema ? `${schema}.${tableName}` : tableName;
+            const next = map.get(path) ?? [];
+            next.push({
+                name: String(row['column_name'] ?? row['COLUMN_NAME'] ?? ''),
+                type: String(row['data_type'] ?? row['DATA_TYPE'] ?? ''),
+            });
+            map.set(path, next);
+            return map;
+        }, new Map());
+        return { tables, columnsByPath };
+    }
+    catch {
+        // Tier 1 failed — try connector methods
+    }
+    // Tier 2: connector.listTables() + connector.listColumns() (SQLite, BigQuery, Athena, ClickHouse, Trino)
+    try {
+        const connector = await executor.getConnector(connection);
+        if (typeof connector.listTables === 'function') {
+            const rawTables = await connector.listTables();
+            tables = rawTables.map((t) => {
+                const schema = t.schema || 'default';
+                const path = t.schema ? `${t.schema}.${t.name}` : t.name;
+                return { schema, name: t.name, path, type: t.type };
+            });
+        }
+        if (typeof connector.listColumns === 'function') {
+            const rawColumns = await connector.listColumns();
+            columnsByPath = rawColumns.reduce((map, col) => {
+                const schema = col.schema || 'default';
+                const path = schema ? `${schema}.${col.table}` : col.table;
+                const next = map.get(path) ?? [];
+                next.push({ name: col.name, type: col.dataType });
+                map.set(path, next);
+                return map;
+            }, new Map());
+        }
+    }
+    catch {
+        // Tier 3: tables only, no columns — already have what we have
+    }
+    return { tables, columnsByPath };
+}
+function buildDatabaseSchemaTree(projectRoot, executor, connection) {
+    return (async () => {
+        const dataFiles = scanDataFiles(projectRoot);
+        const { tables: dbTables, columnsByPath: dbColumnsByPath } = await introspectSchema(executor, connection);
+        const schemaMap = new Map();
+        for (const table of dbTables) {
+            const schemaName = table.schema || 'default';
+            const existing = schemaMap.get(schemaName) ?? [];
+            existing.push({ name: table.name, path: table.path, type: table.type });
+            schemaMap.set(schemaName, existing);
+        }
+        const databaseNodes = Array.from(schemaMap.entries())
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([schemaName, tables]) => ({
+            id: `db-schema:${schemaName}`,
+            label: schemaName,
+            kind: 'schema',
+            children: tables
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((table) => ({
+                id: `db-table:${table.path}`,
+                label: table.name,
+                kind: 'table',
+                path: table.path,
+                type: table.type,
+                children: (dbColumnsByPath.get(table.path) ?? []).map((column) => ({
+                    id: `db-column:${table.path}:${column.name}`,
+                    label: column.name,
+                    kind: 'column',
+                    path: table.path,
+                    type: column.type,
+                })),
+            })),
+        }));
+        // Eagerly resolve file columns via DuckDB DESCRIBE
+        if (dataFiles.length > 0) {
+            const fileChildren = [];
+            for (const file of dataFiles) {
+                let columns = [];
+                try {
+                    const ext = file.name.split('.').pop()?.toLowerCase();
+                    const readFn = ext === 'parquet' ? 'read_parquet' : ext === 'json' ? 'read_json_auto' : 'read_csv_auto';
+                    const descResult = await executor.executeQuery(`DESCRIBE SELECT * FROM ${readFn}('${file.path.replace(/'/g, "''")}') LIMIT 0`, [], {}, connection);
+                    columns = descResult.rows.map((row) => ({
+                        id: `db-column:${file.path}:${String(row['column_name'] ?? '')}`,
+                        label: String(row['column_name'] ?? ''),
+                        kind: 'column',
+                        path: file.path,
+                        type: String(row['column_type'] ?? ''),
+                    }));
+                }
+                catch {
+                    // file column discovery failed — empty children is fine
+                }
+                fileChildren.push({
+                    id: `db-table:${file.path}`,
+                    label: file.name,
+                    kind: 'table',
+                    path: file.path,
+                    type: 'FILE',
+                    children: columns,
+                });
+            }
+            databaseNodes.unshift({
+                id: 'db-schema:files',
+                label: 'files',
+                kind: 'schema',
+                children: fileChildren,
+            });
+        }
+        return databaseNodes;
+    })();
+}
+function openBlockStudioDocument(projectRoot, relativePath, semanticLayer) {
+    const normalizedPath = normalize(relativePath).replace(/^\/+/, '');
+    if (!normalizedPath.startsWith('blocks/')) {
+        throw new Error('Invalid block path');
+    }
+    const absPath = join(projectRoot, normalizedPath);
+    if (!existsSync(absPath)) {
+        throw new Error(`File not found: ${normalizedPath}`);
+    }
+    const source = readFileSync(absPath, 'utf-8');
+    const companionPath = blockCompanionRelativePath(normalizedPath);
+    const companion = companionPath ? readBlockCompanionFile(projectRoot, companionPath) : null;
+    const parsedMetadata = parseBlockSourceMetadata(source);
+    const fileName = normalizedPath.split('/').pop()?.replace(/\.dql$/, '') ?? 'block';
+    const metadata = {
+        name: parsedMetadata.name || companion?.name || fileName,
+        path: normalizedPath,
+        domain: parsedMetadata.domain || companion?.domain || normalizedPath.split('/').slice(1, -1).join('/') || 'uncategorized',
+        description: parsedMetadata.description || companion?.description || '',
+        owner: parsedMetadata.owner || companion?.owner || '',
+        tags: parsedMetadata.tags.length > 0 ? parsedMetadata.tags : companion?.tags ?? [],
+        reviewStatus: companion?.reviewStatus,
+    };
+    return {
+        path: normalizedPath,
+        source,
+        metadata,
+        companionPath: companionPath && existsSync(join(projectRoot, companionPath)) ? companionPath : null,
+        validation: validateBlockStudioSource(source, semanticLayer),
+    };
+}
+function parseBlockStudioArrayField(source, key) {
+    const match = source.match(new RegExp(`\\b${key}\\s*=\\s*\\[([\\s\\S]*?)\\]`, 'i'));
+    if (!match)
+        return [];
+    return (match[1].match(/"([^"]*)"/g) ?? []).map((value) => value.slice(1, -1)).filter(Boolean);
+}
+function parseBlockStudioStringField(source, key) {
+    return source.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? undefined;
+}
+function parseSemanticBlockConfig(source) {
+    const blockType = (parseBlockStudioStringField(source, 'type') ?? 'custom').toLowerCase() === 'semantic'
+        ? 'semantic'
+        : 'custom';
+    const metric = parseBlockStudioStringField(source, 'metric');
+    const metrics = parseBlockStudioArrayField(source, 'metrics');
+    const dimensions = parseBlockStudioArrayField(source, 'dimensions');
+    const timeDimension = parseBlockStudioStringField(source, 'time_dimension');
+    const granularity = parseBlockStudioStringField(source, 'granularity');
+    const limitMatch = source.match(/\blimit\s*=\s*(\d+)/i);
+    return {
+        blockType,
+        metric,
+        metrics,
+        dimensions,
+        timeDimension,
+        granularity,
+        limit: limitMatch ? Number.parseInt(limitMatch[1], 10) : undefined,
+    };
+}
+function buildSemanticTableMapping(semanticLayer, rows) {
+    const dbTableNames = new Set();
+    const schemaQualified = new Map();
+    for (const row of rows) {
+        const schema = String(row['table_schema'] ?? '');
+        const name = String(row['table_name'] ?? '');
+        if (!name)
+            continue;
+        dbTableNames.add(name);
+        schemaQualified.set(name, schema ? `${schema}.${name}` : name);
+    }
+    const tableMapping = {};
+    const allSemanticTables = new Set();
+    for (const metric of semanticLayer.listMetrics())
+        allSemanticTables.add(metric.table);
+    for (const dimension of semanticLayer.listDimensions())
+        allSemanticTables.add(dimension.table);
+    for (const semTable of allSemanticTables) {
+        if (dbTableNames.has(semTable) && schemaQualified.has(semTable)) {
+            tableMapping[semTable] = schemaQualified.get(semTable);
+        }
+    }
+    return Object.keys(tableMapping).length > 0 ? tableMapping : undefined;
+}
+function isDbtSemanticRuntime(projectConfig, detectedProvider, semanticLayer) {
+    if (projectConfig.semanticLayer?.provider === 'dbt' || detectedProvider === 'dbt')
+        return true;
+    return Boolean(semanticLayer?.listMetrics().some((metric) => metric.source?.provider === 'dbt'));
+}
+function composeRuntimeSemanticQuery(request, semanticLayer, context) {
+    const useMetricFlow = request.engine === 'metricflow' || (request.engine !== 'native' &&
+        isDbtSemanticRuntime(context.projectConfig, context.detectedProvider, semanticLayer));
+    if (useMetricFlow) {
+        const dbtProjectPath = context.projectConfig.semanticLayer?.projectPath;
+        const compiled = compileMetricFlowQuery({
+            projectRoot: context.projectRoot,
+            dbtProjectPath,
+            metrics: request.metrics,
+            dimensions: request.dimensions,
+            filters: request.filters,
+            timeDimension: request.timeDimension,
+            orderBy: request.orderBy,
+            limit: request.limit,
+            savedQuery: request.savedQuery,
+        });
+        return {
+            sql: compiled.sql,
+            joins: [],
+            tables: [],
+            engine: 'metricflow',
+        };
+    }
+    const composed = semanticLayer.composeQuery({
+        metrics: request.metrics,
+        dimensions: request.dimensions,
+        filters: request.filters,
+        limit: request.limit,
+        timeDimension: request.timeDimension,
+        orderBy: request.orderBy,
+        driver: context.driver,
+        tableMapping: context.tableMapping,
+    });
+    return composed ? { ...composed, engine: 'native' } : null;
+}
+function composeSemanticBlockSql(source, semanticLayer, options) {
+    const config = parseSemanticBlockConfig(source);
+    const metrics = config.metrics.length > 0
+        ? config.metrics
+        : config.metric
+            ? [config.metric]
+            : [];
+    const semanticRefs = {
+        metrics,
+        dimensions: config.dimensions,
+        segments: [],
+    };
+    const diagnostics = [];
+    if (config.blockType !== 'semantic') {
+        return { sql: null, diagnostics, semanticRefs };
+    }
+    if (metrics.length === 0) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'semantic_metric_missing',
+            message: 'Semantic block is missing a metric. Add metric = "metric_name" or metrics = ["metric_name"].',
+        });
+        return { sql: null, diagnostics, semanticRefs };
+    }
+    if (config.timeDimension && !config.granularity) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'semantic_granularity_missing',
+            message: `Semantic block selects time_dimension = "${config.timeDimension}" but is missing granularity.`,
+        });
+    }
+    const refValidation = semanticLayer.validateReferences([...metrics, ...config.dimensions]);
+    for (const unknown of refValidation.unknown) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'semantic_ref',
+            message: `Unknown semantic reference: ${unknown}`,
+        });
+    }
+    if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
+        return { sql: null, diagnostics, semanticRefs };
+    }
+    let composed;
+    try {
+        composed = options?.projectRoot && options.projectConfig
+            ? composeRuntimeSemanticQuery({
+                metrics,
+                dimensions: config.dimensions,
+                timeDimension: config.timeDimension && config.granularity
+                    ? { name: config.timeDimension, granularity: config.granularity }
+                    : undefined,
+                limit: config.limit,
+            }, semanticLayer, {
+                projectRoot: options.projectRoot,
+                projectConfig: options.projectConfig,
+                detectedProvider: options.detectedProvider ?? null,
+                driver: options.driver,
+                tableMapping: options.tableMapping,
+            })
+            : semanticLayer.composeQuery({
+                metrics,
+                dimensions: config.dimensions,
+                timeDimension: config.timeDimension && config.granularity
+                    ? { name: config.timeDimension, granularity: config.granularity }
+                    : undefined,
+                limit: config.limit,
+                driver: options?.driver,
+                tableMapping: options?.tableMapping,
+            });
+    }
+    catch (error) {
+        diagnostics.push({
+            severity: 'error',
+            code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : 'semantic_compose_failed',
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { sql: null, diagnostics, semanticRefs };
+    }
+    if (!composed) {
+        diagnostics.push({
+            severity: 'error',
+            code: 'semantic_compose_failed',
+            message: `Could not compose SQL for semantic block metrics: [${metrics.join(', ')}].`,
+        });
+        return { sql: null, diagnostics, semanticRefs };
+    }
+    return {
+        sql: composed.sql,
+        diagnostics,
+        semanticRefs,
+    };
+}
+function resolveCustomBlockSql(sql, semanticLayer) {
+    if (!sql) {
+        return {
+            sql: null,
+            diagnostics: [],
+            semanticRefs: { metrics: [], dimensions: [], segments: [] },
+        };
+    }
+    const semanticRefs = extractBlockStudioSemanticReferences(sql);
+    if (!hasSemanticRefs(sql)) {
+        return { sql, diagnostics: [], semanticRefs };
+    }
+    const resolution = resolveSemanticRefs(sql, semanticLayer);
+    if (resolution.unresolvedRefs.length > 0) {
+        return {
+            sql: null,
+            diagnostics: resolution.unresolvedRefs.map((unresolved) => ({
+                severity: 'error',
+                code: 'semantic_ref',
+                message: `Unknown semantic reference: ${unresolved}`,
+            })),
+            semanticRefs,
+        };
+    }
+    return {
+        sql: resolution.resolvedSql,
+        diagnostics: [],
+        semanticRefs: {
+            metrics: resolution.resolvedMetrics,
+            dimensions: resolution.resolvedDimensions,
+            segments: semanticRefs.segments,
+        },
+    };
+}
+export function validateBlockStudioSource(source, semanticLayer) {
+    const diagnostics = [];
+    const semanticConfig = parseSemanticBlockConfig(source);
+    if (semanticConfig.blockType !== 'semantic') {
+        try {
+            const parser = new Parser(source, '<block-studio>');
+            parser.parse();
+        }
+        catch (error) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'syntax',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    else {
+        const hasBlockHeader = /\bblock\s+"[^"]+"\s*\{/i.test(source);
+        const hasClosingBrace = /\}\s*$/m.test(source);
+        if (!hasBlockHeader || !hasClosingBrace) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'semantic_shape',
+                message: 'Semantic block must use block "Name" { ... } structure.',
+            });
+        }
+    }
+    let semanticRefs = extractBlockStudioSemanticReferences(source);
+    if (semanticConfig.blockType === 'semantic') {
+        const selectedMetrics = semanticConfig.metrics.length > 0
+            ? semanticConfig.metrics
+            : semanticConfig.metric
+                ? [semanticConfig.metric]
+                : [];
+        semanticRefs = {
+            metrics: selectedMetrics,
+            dimensions: semanticConfig.dimensions,
+            segments: semanticRefs.segments,
+        };
+    }
+    let executableSql = extractBlockStudioSql(source);
+    if (semanticConfig.blockType === 'semantic') {
+        if (semanticLayer) {
+            const semanticCompose = composeSemanticBlockSql(source, semanticLayer);
+            semanticRefs = semanticCompose.semanticRefs;
+            diagnostics.push(...semanticCompose.diagnostics);
+            executableSql = semanticCompose.sql;
+        }
+        else {
+            diagnostics.push({
+                severity: 'error',
+                code: 'semantic_layer_missing',
+                message: 'Semantic block cannot run because no semantic layer is configured.',
+            });
+            executableSql = null;
+        }
+    }
+    else if (semanticLayer) {
+        const resolvedCustomSql = resolveCustomBlockSql(executableSql, semanticLayer);
+        semanticRefs = resolvedCustomSql.semanticRefs;
+        diagnostics.push(...resolvedCustomSql.diagnostics);
+        executableSql = resolvedCustomSql.sql;
+    }
+    const chartConfig = extractBlockStudioChartConfig(source);
+    if (!chartConfig) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'visualization_missing',
+            message: 'Block has no visualization section yet.',
+        });
+    }
+    if (!executableSql) {
+        diagnostics.push(semanticConfig.blockType === 'semantic'
+            ? {
+                severity: 'warning',
+                code: 'semantic_not_runnable',
+                message: 'Semantic block is not runnable yet. Select a metric and complete any required time settings.',
+            }
+            : {
+                severity: 'warning',
+                code: 'sql_missing',
+                message: 'No executable SQL found in the block source.',
+            });
+    }
+    return {
+        valid: diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
+        diagnostics,
+        semanticRefs,
+        chartConfig: chartConfig ?? undefined,
+        executableSql,
+    };
+}
+function saveBlockStudioArtifacts(projectRoot, options) {
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const safeDomain = (options.domain ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/^\/+|\/+$/g, '') || 'uncategorized';
+    const targetRelativePath = `blocks/${safeDomain}/${slug}.dql`;
+    const targetPath = join(projectRoot, targetRelativePath);
+    const previousPath = options.currentPath ? normalize(options.currentPath).replace(/^\/+/, '') : null;
+    if (existsSync(targetPath) && previousPath !== targetRelativePath) {
+        throw new Error('BLOCK_EXISTS');
+    }
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, options.source.trimEnd() + '\n', 'utf-8');
+    writeBlockCompanionFile(projectRoot, {
+        slug,
+        name: options.name,
+        domain: safeDomain,
+        description: options.description,
+        owner: options.owner,
+        tags: options.tags,
+        provider: 'dql',
+        content: options.source,
+    });
+    if (previousPath && previousPath !== targetRelativePath) {
+        const previousAbsPath = join(projectRoot, previousPath);
+        if (existsSync(previousAbsPath))
+            rmSync(previousAbsPath, { force: true });
+        const previousCompanion = blockCompanionRelativePath(previousPath);
+        if (previousCompanion) {
+            const previousCompanionPath = join(projectRoot, previousCompanion);
+            if (existsSync(previousCompanionPath))
+                rmSync(previousCompanionPath, { force: true });
+        }
+    }
+    return targetRelativePath;
+}
+function blockCompanionRelativePath(blockPath) {
+    const normalized = normalize(blockPath).replace(/^\/+/, '');
+    if (!normalized.startsWith('blocks/'))
+        return null;
+    const withoutRoot = normalized.slice('blocks/'.length).replace(/\.dql$/, '.yaml');
+    return join('semantic-layer', 'blocks', withoutRoot).replaceAll('\\', '/');
+}
+function readBlockCompanionFile(projectRoot, relativePath) {
+    const absPath = join(projectRoot, relativePath);
+    if (!existsSync(absPath))
+        return null;
+    try {
+        const content = readFileSync(absPath, 'utf-8');
+        const lines = content.split(/\r?\n/);
+        const topLevel = {};
+        const arrays = {};
+        let currentArray = null;
+        for (const rawLine of lines) {
+            const line = rawLine.replace(/\t/g, '  ');
+            if (!line.trim() || line.trimStart().startsWith('#'))
+                continue;
+            if (/^\S[^:]*:\s*$/.test(line)) {
+                currentArray = line.trim().slice(0, -1);
+                if (['tags', 'lineage', 'semanticMetrics', 'semanticDimensions'].includes(currentArray)) {
+                    arrays[currentArray] = [];
+                }
+                continue;
+            }
+            const itemMatch = line.match(/^\s*-\s*(.+)\s*$/);
+            if (itemMatch && currentArray && arrays[currentArray]) {
+                arrays[currentArray].push(parseYamlScalar(itemMatch[1]));
+                continue;
+            }
+            const scalarMatch = line.match(/^([A-Za-z0-9_]+):\s*(.+)\s*$/);
+            if (scalarMatch) {
+                currentArray = null;
+                topLevel[scalarMatch[1]] = parseYamlScalar(scalarMatch[2]);
+            }
+        }
+        return {
+            name: topLevel.name ?? '',
+            block: topLevel.block ?? '',
+            domain: topLevel.domain ?? '',
+            description: topLevel.description ?? '',
+            owner: topLevel.owner ?? '',
+            tags: arrays.tags ?? [],
+            reviewStatus: topLevel.reviewStatus ?? '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function parseBlockSourceMetadata(source) {
+    const name = source.match(/^\s*block\s+"([^"]+)"/i)?.[1] ?? '';
+    const extractString = (key) => source.match(new RegExp(`\\b${key}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? '';
+    const tags = source.match(/\btags\s*=\s*\[([^\]]*)\]/i);
+    return {
+        name,
+        domain: extractString('domain'),
+        description: extractString('description'),
+        owner: extractString('owner'),
+        tags: tags ? (tags[1].match(/"([^"]*)"/g) ?? []).map((value) => value.slice(1, -1)) : [],
+    };
+}
+function extractBlockStudioChartConfig(source) {
+    const vizMatch = source.match(/visualization\s*\{([^}]+)\}/is);
+    if (!vizMatch)
+        return null;
+    const body = vizMatch[1];
+    const get = (key) => body.match(new RegExp(`\\b${key}\\s*=\\s*["']?([\\w-]+)["']?`, 'i'))?.[1];
+    const chart = get('chart');
+    if (!chart)
+        return null;
+    const title = body.match(/\btitle\s*=\s*"([^"]+)"/i)?.[1];
+    return {
+        chart,
+        x: get('x'),
+        y: get('y'),
+        color: get('color'),
+        title,
+    };
+}
+function extractBlockStudioSql(source) {
+    const tripleQuoteMatch = source.match(/query\s*=\s*"""([\s\S]*?)"""/i);
+    if (tripleQuoteMatch)
+        return tripleQuoteMatch[1].trim() || null;
+    const bareTripleMatch = source.match(/"""([\s\S]*?)"""/);
+    if (bareTripleMatch)
+        return bareTripleMatch[1].trim() || null;
+    if (/^\s*(dashboard|workbook)\s+"/i.test(source))
+        return null;
+    const sqlKeywordMatch = source.match(/\b(SELECT|WITH|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE|EXPLAIN)\b([\s\S]*)/i);
+    if (!sqlKeywordMatch)
+        return null;
+    let raw = sqlKeywordMatch[0];
+    const dqlSectionStart = raw.search(/\b(visualization|tests|block)\s*\{/i);
+    if (dqlSectionStart > 0)
+        raw = raw.slice(0, dqlSectionStart);
+    return raw.trim() || null;
+}
+function extractBlockStudioSemanticReferences(source) {
+    const metrics = new Set();
+    const dimensions = new Set();
+    const segments = new Set();
+    const semanticRegex = /@(metric|dim)\(([^)]+)\)/gi;
+    let match;
+    while ((match = semanticRegex.exec(source))) {
+        const name = match[2].trim();
+        if (!name)
+            continue;
+        if (match[1].toLowerCase() === 'metric')
+            metrics.add(name);
+        else
+            dimensions.add(name);
+    }
+    const segmentRegex = /\/\*\s*segment:([^*]+)\*\//gi;
+    while ((match = segmentRegex.exec(source))) {
+        const name = match[1].trim();
+        if (name)
+            segments.add(name);
+    }
+    return {
+        metrics: Array.from(metrics),
+        dimensions: Array.from(dimensions),
+        segments: Array.from(segments),
+    };
+}
+function canonicalizeSafe(source) {
+    try {
+        return canonicalize(source);
+    }
+    catch {
+        // If the block body has content the parser rejects (e.g. unsupported
+        // syntax in a user-provided template), keep the original bytes rather
+        // than fail the write — format header gets added next time it passes fmt.
+        return source;
+    }
+}
+function canonicalizeNotebookSafe(source) {
+    try {
+        return canonicalizeNotebook(source);
+    }
+    catch {
+        return source;
+    }
+}
+export function readGitMetadata(projectRoot) {
+    const run = (cmd) => execSync(cmd, { cwd: projectRoot, encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    try {
+        const commitSha = run('git rev-parse HEAD');
+        let repo = null;
+        let branch = null;
+        try {
+            repo = run('git config --get remote.origin.url') || null;
+        }
+        catch { /* no remote */ }
+        try {
+            branch = run('git rev-parse --abbrev-ref HEAD') || null;
+        }
+        catch { /* detached */ }
+        return { commitSha, repo, branch };
+    }
+    catch {
+        return null;
+    }
+}
+export function createBlockArtifacts(projectRoot, options) {
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const safeDomain = (options.domain ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/^\/+|\/+$/g, '');
+    const blocksDir = safeDomain ? join(projectRoot, 'blocks', safeDomain) : join(projectRoot, 'blocks');
+    mkdirSync(blocksDir, { recursive: true });
+    const blockPath = join(blocksDir, `${slug}.dql`);
+    if (existsSync(blockPath)) {
+        throw new Error('BLOCK_EXISTS');
+    }
+    const templateContent = options.template
+        ? listBlockTemplates().find((template) => template.id === options.template)?.content
+        : undefined;
+    const relativePath = safeDomain ? `blocks/${safeDomain}/${slug}.dql` : `blocks/${slug}.dql`;
+    const fileContent = canonicalizeSafe(normalizeBlockStudioContent({
+        name: options.name,
+        domain: safeDomain || 'uncategorized',
+        owner: options.owner,
+        description: options.description,
+        tags: options.tags,
+        llmContext: options.llmContext,
+        examples: options.examples,
+        invariants: options.invariants,
+        content: options.content?.trim() || templateContent,
+    }));
+    writeFileSync(blockPath, fileContent, 'utf-8');
+    const companionPath = writeBlockCompanionFile(projectRoot, {
+        slug,
+        name: options.name,
+        domain: safeDomain || 'uncategorized',
+        owner: options.owner,
+        description: options.description,
+        tags: options.tags,
+        provider: 'dql',
+        content: fileContent,
+        gitMetadata: options.gitMetadata,
+        gitPath: relativePath,
+    });
+    return {
+        path: relativePath,
+        content: fileContent,
+        companionPath,
+    };
+}
+export function createSemanticBuilderBlock(projectRoot, options) {
+    const slug = options.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
+    const safeDomain = (options.domain ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9/_-]+/g, '-')
+        .replace(/^\/+|\/+$/g, '') || 'uncategorized';
+    const blocksDir = join(projectRoot, 'blocks', safeDomain);
+    mkdirSync(blocksDir, { recursive: true });
+    const blockPath = join(blocksDir, `${slug}.dql`);
+    if (existsSync(blockPath)) {
+        throw new Error('BLOCK_EXISTS');
+    }
+    const content = canonicalizeSafe(options.blockType === 'custom'
+        ? buildCustomSemanticBlockContent(options)
+        : buildSemanticBlockContent(options));
+    writeFileSync(blockPath, content, 'utf-8');
+    const companionPath = writeBlockCompanionFile(projectRoot, {
+        slug,
+        name: options.name,
+        domain: safeDomain,
+        description: options.description,
+        owner: options.owner,
+        tags: options.tags,
+        provider: options.provider,
+        content,
+        lineage: options.tables,
+        semanticMetrics: options.metrics,
+        semanticDimensions: [
+            ...options.dimensions,
+            ...(options.timeDimension ? [options.timeDimension.name] : []),
+        ],
+    });
+    return {
+        path: `blocks/${safeDomain}/${slug}.dql`,
+        content,
+        companionPath,
+    };
+}
+function buildSemanticBlockContent(options) {
+    const lines = [
+        `block "${options.name}" {`,
+        `    domain = "${options.domain ?? 'uncategorized'}"`,
+        '    type = "semantic"',
+    ];
+    if (options.description)
+        lines.push(`    description = "${escapeDqlString(options.description)}"`);
+    if (options.owner)
+        lines.push(`    owner = "${escapeDqlString(options.owner)}"`);
+    if (options.tags && options.tags.length > 0) {
+        lines.push(`    tags = [${options.tags.map((tag) => `"${escapeDqlString(tag)}"`).join(', ')}]`);
+    }
+    if (options.metrics.length === 1) {
+        lines.push(`    metric = "${escapeDqlString(options.metrics[0])}"`);
+    }
+    else {
+        lines.push(`    metrics = [${options.metrics.map((metric) => `"${escapeDqlString(metric)}"`).join(', ')}]`);
+    }
+    if (options.dimensions.length > 0) {
+        lines.push(`    dimensions = [${options.dimensions.map((dimension) => `"${escapeDqlString(dimension)}"`).join(', ')}]`);
+    }
+    if (options.timeDimension) {
+        lines.push(`    time_dimension = "${escapeDqlString(options.timeDimension.name)}"`);
+        lines.push(`    granularity = "${escapeDqlString(options.timeDimension.granularity)}"`);
+    }
+    const visualization = buildVisualizationBlock(options.chart ?? 'table', options.dimensions, options.timeDimension, options.metrics);
+    if (visualization) {
+        lines.push('');
+        lines.push(...visualization);
+    }
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+function buildCustomSemanticBlockContent(options) {
+    const lines = [
+        `block "${options.name}" {`,
+        `    domain = "${options.domain ?? 'uncategorized'}"`,
+        '    type = "custom"',
+    ];
+    if (options.description)
+        lines.push(`    description = "${escapeDqlString(options.description)}"`);
+    if (options.owner)
+        lines.push(`    owner = "${escapeDqlString(options.owner)}"`);
+    if (options.tags && options.tags.length > 0) {
+        lines.push(`    tags = [${options.tags.map((tag) => `"${escapeDqlString(tag)}"`).join(', ')}]`);
+    }
+    lines.push('');
+    lines.push('    query = """');
+    lines.push(...indentBlock(options.sql.trim(), 8).split('\n'));
+    lines.push('    """');
+    const visualization = buildVisualizationBlock(options.chart ?? 'table', options.dimensions, options.timeDimension, options.metrics);
+    if (visualization) {
+        lines.push('');
+        lines.push(...visualization);
+    }
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+function buildVisualizationBlock(chart, dimensions, timeDimension, metrics) {
+    const x = timeDimension ? `${timeDimension.name}_${timeDimension.granularity}` : dimensions[0];
+    const y = metrics[0];
+    if (!x && chart !== 'kpi' && chart !== 'table')
+        return null;
+    if (chart === 'table') {
+        return ['    visualization {', '        chart = "table"', '    }'];
+    }
+    if (chart === 'kpi') {
+        return ['    visualization {', '        chart = "kpi"', `        y = ${y}`, '    }'];
+    }
+    return [
+        '    visualization {',
+        `        chart = "${chart}"`,
+        `        x = ${x}`,
+        `        y = ${y}`,
+        '    }',
+    ];
+}
+function writeBlockCompanionFile(projectRoot, options) {
+    const extractedRefs = extractSemanticReferenceNames(options.content);
+    const semanticMetrics = Array.from(new Set([...(options.semanticMetrics ?? []), ...extractedRefs.metrics]));
+    const semanticDimensions = Array.from(new Set([...(options.semanticDimensions ?? []), ...extractedRefs.dimensions]));
+    const companionDir = join(projectRoot, 'semantic-layer', 'blocks', options.domain);
+    mkdirSync(companionDir, { recursive: true });
+    const companionPath = join(companionDir, `${options.slug}.yaml`);
+    const lines = [
+        `name: ${options.slug}`,
+        `block: ${options.slug}`,
+        `domain: ${options.domain}`,
+        `description: ${yamlScalar(options.description?.trim() || options.name)}`,
+    ];
+    if (options.owner)
+        lines.push(`owner: ${yamlScalar(options.owner)}`);
+    if (options.tags && options.tags.length > 0) {
+        lines.push('tags:');
+        for (const tag of options.tags)
+            lines.push(`  - ${yamlScalar(tag)}`);
+    }
+    if (options.provider) {
+        lines.push('source:');
+        lines.push(`  provider: ${yamlScalar(options.provider)}`);
+        lines.push('  objectType: block');
+        lines.push(`  objectId: ${yamlScalar(options.slug)}`);
+    }
+    if (semanticMetrics.length > 0) {
+        lines.push('semanticMetrics:');
+        for (const metric of semanticMetrics)
+            lines.push(`  - ${yamlScalar(metric)}`);
+    }
+    if (semanticDimensions.length > 0) {
+        lines.push('semanticDimensions:');
+        for (const dimension of semanticDimensions)
+            lines.push(`  - ${yamlScalar(dimension)}`);
+    }
+    const mappingEntries = [
+        ...semanticMetrics.map((metric) => [metric, metric]),
+        ...semanticDimensions.map((dimension) => [dimension, dimension]),
+    ];
+    if (mappingEntries.length > 0) {
+        lines.push('semanticMappings:');
+        for (const [key, value] of mappingEntries) {
+            lines.push(`  ${key}: ${yamlScalar(value)}`);
+        }
+    }
+    if (options.lineage && options.lineage.length > 0) {
+        lines.push('lineage:');
+        for (const table of options.lineage)
+            lines.push(`  - ${yamlScalar(table)}`);
+    }
+    if (options.gitMetadata || options.gitPath) {
+        lines.push('git:');
+        if (options.gitMetadata?.commitSha)
+            lines.push(`  commitSha: ${yamlScalar(options.gitMetadata.commitSha)}`);
+        if (options.gitMetadata?.repo)
+            lines.push(`  repo: ${yamlScalar(options.gitMetadata.repo)}`);
+        if (options.gitMetadata?.branch)
+            lines.push(`  branch: ${yamlScalar(options.gitMetadata.branch)}`);
+        if (options.gitPath)
+            lines.push(`  path: ${yamlScalar(options.gitPath)}`);
+    }
+    lines.push('reviewStatus: draft');
+    writeFileSync(companionPath, lines.join('\n') + '\n', 'utf-8');
+    return relative(projectRoot, companionPath).replaceAll('\\', '/');
+}
+function extractSemanticReferenceNames(content) {
+    const metrics = new Set();
+    const dimensions = new Set();
+    const regex = /@(metric|dim)\(([^)]+)\)/gi;
+    let match;
+    while ((match = regex.exec(content))) {
+        const name = match[2].trim();
+        if (!name)
+            continue;
+        if (match[1].toLowerCase() === 'metric') {
+            metrics.add(name);
+        }
+        else {
+            dimensions.add(name);
+        }
+    }
+    return {
+        metrics: Array.from(metrics),
+        dimensions: Array.from(dimensions),
+    };
+}
+function escapeDqlString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function indentBlock(value, spaces) {
+    const prefix = ' '.repeat(spaces);
+    return value.split('\n').map((line) => `${prefix}${line}`).join('\n');
+}
+function normalizeBlockStudioContent(options) {
+    const content = options.content?.trim();
+    if (content && /^\s*block\s+"/i.test(content)) {
+        return `${content.trimEnd()}\n`;
+    }
+    return buildBlankBlockContent({
+        name: options.name,
+        domain: options.domain,
+        owner: options.owner,
+        description: options.description,
+        tags: options.tags,
+        llmContext: options.llmContext,
+        examples: options.examples,
+        invariants: options.invariants,
+        sql: content || 'SELECT 1 AS value',
+    });
+}
+function buildBlankBlockContent(options) {
+    const lines = [
+        `block "${escapeDqlString(options.name)}" {`,
+        `    domain = "${escapeDqlString(options.domain)}"`,
+        '    type = "custom"',
+        `    description = "${escapeDqlString(options.description?.trim() || options.name)}"`,
+        `    owner = "${escapeDqlString(options.owner?.trim() ?? '')}"`,
+    ];
+    lines.push(`    tags = [${(options.tags ?? []).map((tag) => `"${escapeDqlString(tag)}"`).join(', ')}]`);
+    if (options.llmContext && options.llmContext.trim()) {
+        lines.push(`    llmContext = "${escapeDqlString(options.llmContext.trim())}"`);
+    }
+    if (options.invariants && options.invariants.length > 0) {
+        lines.push(`    invariants = [${options.invariants
+            .filter((inv) => inv && inv.trim())
+            .map((inv) => `"${escapeDqlString(inv.trim())}"`)
+            .join(', ')}]`);
+    }
+    if (options.examples && options.examples.length > 0) {
+        const items = options.examples.filter((ex) => ex.question && ex.question.trim());
+        if (items.length > 0) {
+            lines.push('    examples = [');
+            for (const ex of items) {
+                const parts = [`question = "${escapeDqlString(ex.question.trim())}"`];
+                if (ex.sql && ex.sql.trim())
+                    parts.push(`sql = "${escapeDqlString(ex.sql.trim())}"`);
+                lines.push(`        { ${parts.join(', ')} },`);
+            }
+            lines.push('    ]');
+        }
+    }
+    lines.push('');
+    lines.push('    query = """');
+    lines.push(...indentBlock(options.sql.trim(), 8).split('\n'));
+    lines.push('    """');
+    lines.push('');
+    lines.push('    visualization {');
+    lines.push('        chart = "table"');
+    lines.push('    }');
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+function parseYamlScalar(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return '';
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"'))
+        || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function yamlScalar(value) {
+    if (/^[a-zA-Z0-9_.:/-]+$/.test(value))
+        return value;
+    return JSON.stringify(value);
+}
+function buildNotebookTemplate(title, template) {
+    const id = () => Math.random().toString(36).slice(2, 10);
+    let cells;
+    if (template === 'revenue') {
+        cells = [
+            { id: id(), type: 'markdown', content: `# ${title}\n\nRevenue analysis using DQL and DuckDB.` },
+            { id: id(), type: 'sql', name: 'revenue_summary', content: "SELECT\n  segment_tier AS segment,\n  SUM(amount) AS total_revenue,\n  COUNT(*) AS deals\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY segment_tier\nORDER BY total_revenue DESC" },
+            { id: id(), type: 'sql', name: 'revenue_trend', content: "SELECT\n  recognized_at AS date,\n  SUM(amount) AS revenue\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY recognized_at\nORDER BY recognized_at" },
+        ];
+    }
+    else if (template === 'pipeline') {
+        cells = [
+            { id: id(), type: 'markdown', content: `# ${title}\n\nPipeline health and conversion analysis.` },
+            { id: id(), type: 'sql', name: 'pipeline_overview', content: "SELECT *\nFROM read_csv_auto('./data/pipeline.csv')\nLIMIT 100" },
+        ];
+    }
+    else {
+        cells = [
+            { id: id(), type: 'markdown', content: `# ${title}\n\nAdd your analysis here.` },
+            { id: id(), type: 'sql', name: 'query_1', content: 'SELECT 1 AS hello' },
+        ];
+    }
+    return JSON.stringify({ version: 1, title, cells }, null, 2);
+}
+/** Build a lineage graph from the project's blocks and semantic layer. */
+// Simple lineage graph cache: rebuilds at most every 5 seconds
+let _lineageCache = null;
+const LINEAGE_CACHE_TTL_MS = 5000;
+function buildProjectLineageGraph(projectRoot, semanticLayer) {
+    if (_lineageCache && Date.now() - _lineageCache.builtAt < LINEAGE_CACHE_TTL_MS) {
+        return _lineageCache.graph;
+    }
+    const graph = buildProjectLineageGraphUncached(projectRoot, semanticLayer);
+    _lineageCache = { graph, builtAt: Date.now() };
+    return graph;
+}
+function buildProjectLineageGraphUncached(projectRoot, semanticLayer) {
+    const manifestPath = join(projectRoot, 'dql-manifest.json');
+    if (existsSync(manifestPath)) {
+        try {
+            const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            if (manifest.lineage?.nodes && manifest.lineage?.edges) {
+                return LineageGraph.fromJSON({
+                    nodes: manifest.lineage.nodes,
+                    edges: manifest.lineage.edges,
+                });
+            }
+        }
+        catch {
+            // Fall back to a live build.
+        }
+    }
+    const dbtManifestPath = resolveDbtManifestPath(projectRoot);
+    try {
+        const manifest = buildManifest({
+            projectRoot,
+            dbtManifestPath,
+        });
+        return LineageGraph.fromJSON({
+            nodes: manifest.lineage.nodes,
+            edges: manifest.lineage.edges,
+        });
+    }
+    catch {
+        const blocks = [];
+        const metrics = [];
+        const dimensions = [];
+        const dirs = ['blocks', 'dashboards', 'workbooks'];
+        for (const dir of dirs) {
+            const dirPath = join(projectRoot, dir);
+            if (!existsSync(dirPath))
+                continue;
+            for (const entry of readdirSync(dirPath, { withFileTypes: true })) {
+                if (!entry.isFile() || extname(entry.name) !== '.dql')
+                    continue;
+                try {
+                    const source = readFileSync(join(dirPath, entry.name), 'utf-8');
+                    const parser = new Parser(source, `${dir}/${entry.name}`);
+                    const ast = parser.parse();
+                    for (const stmt of ast.statements) {
+                        const block = stmt;
+                        if (block.kind !== 'BlockDecl')
+                            continue;
+                        blocks.push({
+                            name: block.name,
+                            sql: block.query?.rawSQL ?? '',
+                            domain: extractProp(block, 'domain'),
+                            owner: extractProp(block, 'owner'),
+                            status: extractProp(block, 'status'),
+                            blockType: block.blockType,
+                            metricRef: block.metricRef,
+                            chartType: extractVizChart(block),
+                        });
+                    }
+                }
+                catch { /* skip unparseable */ }
+            }
+        }
+        if (semanticLayer) {
+            for (const m of semanticLayer.listMetrics()) {
+                metrics.push({ name: m.name, table: m.table, domain: m.domain, type: m.type });
+            }
+            for (const d of semanticLayer.listDimensions()) {
+                dimensions.push({ name: d.name, table: d.table });
+            }
+        }
+        return buildLineageGraph(blocks, metrics, dimensions);
+    }
+}
+function resolveDbtManifestPath(projectRoot) {
+    const candidate = join(projectRoot, 'target', 'manifest.json');
+    return existsSync(candidate) ? candidate : undefined;
+}
+function resolveLineageNode(graph, rawNodeId) {
+    if (graph.getNode(rawNodeId))
+        return graph.getNode(rawNodeId);
+    const result = queryLineage(graph, { focus: rawNodeId });
+    return result.focalNode;
+}
+function extractProp(block, key) {
+    // Check direct AST fields first (parser puts domain, owner, type directly on the node)
+    if (block[key] !== undefined && block[key] !== null)
+        return String(block[key]);
+    for (const prop of block.properties ?? []) {
+        if (prop.key === key && prop.value?.kind === 'Literal')
+            return String(prop.value.value);
+    }
+    return undefined;
+}
+function extractVizChart(block) {
+    for (const prop of block.visualization?.properties ?? []) {
+        if (prop.key === 'chart' && prop.value?.kind === 'Literal')
+            return String(prop.value.value);
+    }
+    return undefined;
+}
+async function execGit(cwd, args) {
+    const { execFile } = await import('node:child_process');
+    return new Promise((resolve) => {
+        execFile('git', args, { cwd, maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
+            resolve({
+                stdout: String(stdout ?? ''),
+                stderr: String(stderr ?? ''),
+                code: err ? (err.code ? 1 : err.code ?? 1) : 0,
+            });
+        });
+    });
+}
+async function readGitStatus(cwd) {
+    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (isRepo.code !== 0 || isRepo.stdout.trim() !== 'true') {
+        return { inRepo: false, branch: null, ahead: 0, behind: 0, changes: [] };
+    }
+    const branchRes = await execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const branch = branchRes.code === 0 ? branchRes.stdout.trim() : null;
+    const trackRes = await execGit(cwd, ['rev-list', '--left-right', '--count', '@{u}...HEAD']);
+    let ahead = 0;
+    let behind = 0;
+    if (trackRes.code === 0) {
+        const match = trackRes.stdout.trim().split(/\s+/);
+        behind = Number(match[0] ?? 0);
+        ahead = Number(match[1] ?? 0);
+    }
+    const statusRes = await execGit(cwd, ['status', '--porcelain=v1', '--untracked-files=normal']);
+    const changes = [];
+    if (statusRes.code === 0) {
+        for (const line of statusRes.stdout.split('\n')) {
+            if (!line)
+                continue;
+            const code = line.slice(0, 2);
+            const p = line.slice(3);
+            changes.push({ path: p, status: code });
+        }
+    }
+    return { inRepo: true, branch, ahead, behind, changes };
+}
+async function readGitLog(cwd, limit) {
+    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (isRepo.code !== 0)
+        return { inRepo: false, commits: [] };
+    const sep = '\x1f';
+    const end = '\x1e';
+    const fmt = ['%H', '%an', '%ad', '%s'].join(sep) + end;
+    const res = await execGit(cwd, ['log', `-${limit}`, `--pretty=format:${fmt}`, '--date=short']);
+    if (res.code !== 0)
+        return { inRepo: true, commits: [] };
+    const commits = [];
+    for (const entry of res.stdout.split(end)) {
+        const trimmed = entry.replace(/^\n/, '');
+        if (!trimmed)
+            continue;
+        const [hash, author, date, subject] = trimmed.split(sep);
+        if (hash)
+            commits.push({ hash, author, date, subject });
+    }
+    return { inRepo: true, commits };
+}
+function snapshotPathFor(projectRoot, notebookPath) {
+    const abs = safeJoin(projectRoot, notebookPath);
+    if (!abs)
+        return null;
+    // Strip extension and append `.run.json` so `foo.dqlnb` → `foo.run.json`
+    // and `bar.dql` → `bar.run.json`. Keeps the sibling file next to source.
+    const dot = abs.lastIndexOf('.');
+    const base = dot > abs.lastIndexOf('/') ? abs.slice(0, dot) : abs;
+    return `${base}.run.json`;
+}
+function readRunSnapshot(projectRoot, notebookPath) {
+    const p = snapshotPathFor(projectRoot, notebookPath);
+    if (!p || !existsSync(p))
+        return { found: false, snapshot: null };
+    try {
+        const raw = readFileSync(p, 'utf-8');
+        return { found: true, snapshot: JSON.parse(raw) };
+    }
+    catch {
+        return { found: false, snapshot: null };
+    }
+}
+function writeRunSnapshot(projectRoot, notebookPath, snapshot) {
+    const p = snapshotPathFor(projectRoot, notebookPath);
+    if (!p)
+        throw new Error('Invalid path');
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(snapshot, null, 2), 'utf-8');
+    // Append `*.run.json` to .gitignore once, so snapshots don't pollute git
+    // history unless the user deliberately un-ignores them.
+    ensureGitignoreEntry(projectRoot, '*.run.json');
+}
+function ensureGitignoreEntry(projectRoot, pattern) {
+    try {
+        const gitignorePath = join(projectRoot, '.gitignore');
+        const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+        const lines = existing.split('\n').map((l) => l.trim());
+        if (lines.includes(pattern))
+            return;
+        const next = existing.endsWith('\n') || existing === ''
+            ? `${existing}${pattern}\n`
+            : `${existing}\n${pattern}\n`;
+        writeFileSync(gitignorePath, next, 'utf-8');
+    }
+    catch {
+        // Best-effort; failure to write .gitignore shouldn't fail the snapshot.
+    }
+}
+async function readGitDiff(cwd, filePath, staged = false) {
+    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (isRepo.code !== 0) {
+        return { inRepo: false, diff: '', before: null, after: null, diffReport: null };
+    }
+    const baseArgs = staged ? ['diff', '--cached', '--no-color'] : ['diff', '--no-color'];
+    if (!filePath) {
+        const res = await execGit(cwd, baseArgs);
+        return { inRepo: true, diff: res.stdout, before: null, after: null, diffReport: null };
+    }
+    const isSemantic = filePath.endsWith('.dql') || filePath.endsWith('.dqlnb');
+    const [diffRes, before, after] = await Promise.all([
+        execGit(cwd, [...baseArgs, '--', filePath]),
+        isSemantic ? readHeadBlob(cwd, filePath) : Promise.resolve(null),
+        isSemantic ? readWorkingCopy(join(cwd, filePath)) : Promise.resolve(null),
+    ]);
+    const diffReport = isSemantic ? computeSemanticDiff(filePath, before, after) : null;
+    return { inRepo: true, diff: diffRes.stdout, before, after, diffReport };
+}
+// ── git write operations ──────────────────────────────────────────────────
+// Each helper validates inputs, shells out via execFile (no shell expansion),
+// then reports the trimmed stderr on failure so the UI can surface it. We
+// never accept absolute paths or paths containing `..` — staged paths must
+// stay inside the project root.
+function validatePaths(cwd, paths) {
+    if (!Array.isArray(paths) || paths.length === 0) {
+        return { ok: false, error: 'No paths provided' };
+    }
+    const cleaned = [];
+    for (const p of paths) {
+        if (typeof p !== 'string' || p.length === 0)
+            return { ok: false, error: 'Invalid path' };
+        if (p.startsWith('/'))
+            return { ok: false, error: `Absolute path not allowed: ${p}` };
+        if (p.split('/').includes('..'))
+            return { ok: false, error: `Path escape not allowed: ${p}` };
+        const resolved = join(cwd, p);
+        if (!resolved.startsWith(cwd))
+            return { ok: false, error: `Path outside project: ${p}` };
+        cleaned.push(p);
+    }
+    return { ok: true, paths: cleaned };
+}
+function gitErrorOutput(res) {
+    return (res.stderr || res.stdout || '').trim();
+}
+async function gitStage(cwd, paths) {
+    const v = validatePaths(cwd, paths);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    const res = await execGit(cwd, ['add', '--', ...v.paths]);
+    return res.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(res) };
+}
+async function gitUnstage(cwd, paths) {
+    const v = validatePaths(cwd, paths);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    // `restore --staged` works with or without HEAD; for an initial commit (no
+    // HEAD yet) git's `rm --cached` is the fallback. Try restore first.
+    const res = await execGit(cwd, ['restore', '--staged', '--', ...v.paths]);
+    if (res.code === 0)
+        return { ok: true };
+    const fallback = await execGit(cwd, ['rm', '--cached', '-r', '--', ...v.paths]);
+    return fallback.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(fallback) };
+}
+async function gitDiscard(cwd, paths) {
+    const v = validatePaths(cwd, paths);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    // For tracked files: `restore --worktree` reverts to HEAD. For untracked
+    // files: that's a no-op and we delete them via `clean -f`. Run both so
+    // the caller doesn't have to know which list each path is in.
+    const restore = await execGit(cwd, ['restore', '--worktree', '--', ...v.paths]);
+    const clean = await execGit(cwd, ['clean', '-f', '--', ...v.paths]);
+    if (restore.code !== 0 && clean.code !== 0) {
+        return { ok: false, error: gitErrorOutput(restore) || gitErrorOutput(clean) };
+    }
+    return { ok: true };
+}
+async function gitCommit(cwd, message, stageAll) {
+    const trimmed = message.trim();
+    if (!trimmed)
+        return { ok: false, error: 'Commit message required' };
+    if (stageAll) {
+        const add = await execGit(cwd, ['add', '-A']);
+        if (add.code !== 0)
+            return { ok: false, error: gitErrorOutput(add) };
+    }
+    const res = await execGit(cwd, ['commit', '-m', trimmed]);
+    if (res.code !== 0)
+        return { ok: false, error: gitErrorOutput(res) };
+    const hashRes = await execGit(cwd, ['rev-parse', 'HEAD']);
+    return { ok: true, hash: hashRes.code === 0 ? hashRes.stdout.trim() : undefined };
+}
+async function gitPush(cwd) {
+    const res = await execGit(cwd, ['push']);
+    return res.code === 0
+        ? { ok: true, output: gitErrorOutput(res) }
+        : { ok: false, error: gitErrorOutput(res) };
+}
+async function gitPull(cwd) {
+    // `--ff-only` keeps the operation non-destructive: if the local branch has
+    // diverged from upstream, we surface the error rather than auto-merging.
+    // The user can resolve via the terminal or a future merge UI.
+    const res = await execGit(cwd, ['pull', '--ff-only']);
+    return res.code === 0
+        ? { ok: true, output: gitErrorOutput(res) }
+        : { ok: false, error: gitErrorOutput(res) };
+}
+async function readGitBranches(cwd) {
+    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (isRepo.code !== 0)
+        return { inRepo: false, current: null, branches: [] };
+    const cur = await execGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const list = await execGit(cwd, ['branch', '--list', '--format=%(refname:short)']);
+    const branches = list.code === 0
+        ? list.stdout.split('\n').map((s) => s.trim()).filter(Boolean)
+        : [];
+    return { inRepo: true, current: cur.code === 0 ? cur.stdout.trim() : null, branches };
+}
+async function readGitRemote(cwd) {
+    const isRepo = await execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (isRepo.code !== 0)
+        return { inRepo: false, url: null, name: null };
+    const remoteName = await execGit(cwd, ['config', '--get', 'remote.pushDefault']);
+    const name = remoteName.code === 0 && remoteName.stdout.trim() ? remoteName.stdout.trim() : 'origin';
+    const url = await execGit(cwd, ['remote', 'get-url', name]);
+    return { inRepo: true, url: url.code === 0 ? url.stdout.trim() : null, name };
+}
+async function gitCreateBranch(cwd, name, checkout) {
+    const trimmed = name.trim();
+    // Branch names can't start with `-` (would be parsed as a flag) and must be
+    // non-empty. git itself enforces the rest of the ref-name rules.
+    if (!trimmed)
+        return { ok: false, error: 'Branch name required' };
+    if (trimmed.startsWith('-'))
+        return { ok: false, error: 'Invalid branch name' };
+    const res = checkout
+        ? await execGit(cwd, ['checkout', '-b', trimmed])
+        : await execGit(cwd, ['branch', trimmed]);
+    return res.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(res) };
+}
+async function gitCheckout(cwd, name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return { ok: false, error: 'Branch name required' };
+    if (trimmed.startsWith('-'))
+        return { ok: false, error: 'Invalid branch name' };
+    const res = await execGit(cwd, ['checkout', trimmed]);
+    return res.code === 0 ? { ok: true } : { ok: false, error: gitErrorOutput(res) };
+}
+async function readHeadBlob(cwd, filePath) {
+    try {
+        const res = await execGit(cwd, ['show', `HEAD:${filePath}`]);
+        return res.code === 0 ? res.stdout : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readWorkingCopy(absPath) {
+    try {
+        return readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function computeSemanticDiff(filePath, before, after) {
+    if (before === after)
+        return null;
+    try {
+        return filePath.endsWith('.dqlnb')
+            ? diffNotebook(before, after)
+            : diffDQL(before ?? '', after ?? '');
+    }
+    catch {
+        return null;
+    }
+}
+function collectSettingsEnvStatus() {
+    const v = (key, label, description, optional = true) => ({
+        key,
+        label,
+        description,
+        optional,
+        present: typeof process.env[key] === 'string' && process.env[key].trim().length > 0,
+    });
+    return [
+        {
+            id: 'ai',
+            title: 'AI Chat Providers',
+            description: 'Configure one or more providers. Missing keys are only a problem when that provider is selected.',
+            vars: [
+                v('ANTHROPIC_API_KEY', 'Claude Agent SDK', 'Hosted Claude provider for notebook Chat and agent commands.'),
+                v('OPENAI_API_KEY', 'OpenAI', 'Hosted OpenAI provider for notebook Chat and agent commands.'),
+                v('OPENAI_MODEL', 'OpenAI model', 'Optional override such as gpt-4.1-mini or the model your account uses.'),
+                v('GEMINI_API_KEY', 'Gemini', 'Hosted Gemini provider for notebook Chat and agent commands.'),
+                v('GEMINI_MODEL', 'Gemini model', 'Optional Gemini model override.'),
+                v('OLLAMA_BASE_URL', 'Ollama base URL', 'Local Ollama HTTP endpoint. Docker defaults to http://ollama:11434.'),
+                v('OLLAMA_MODEL', 'Ollama model', 'Optional local model name such as llama3.1.'),
+            ],
+        },
+        {
+            id: 'slack',
+            title: 'Slack',
+            description: 'Use webhooks for scheduled App deliveries, or bot credentials for the Slack chat front-end.',
+            vars: [
+                v('DQL_SLACK_WEBHOOK', 'Schedule webhook', 'Incoming webhook used by App schedules that deliver to Slack.'),
+                v('SLACK_SIGNING_SECRET', 'Slack signing secret', 'Required only when running `dql slack serve`.'),
+                v('SLACK_BOT_TOKEN', 'Slack bot token', 'Bot token used by Slack chat commands when `dql slack serve` is enabled.'),
+            ],
+        },
+        {
+            id: 'email',
+            title: 'Email',
+            description: 'SMTP is optional. Without it, email schedules stay in stub mode with a clear delivery message.',
+            vars: [
+                v('DQL_SMTP_URL', 'SMTP URL', 'SMTP connection URL for email schedule delivery.'),
+                v('DQL_SMTP_FROM', 'SMTP sender', 'Optional sender address for scheduled emails.'),
+            ],
+        },
+        {
+            id: 'runtime',
+            title: 'Runtime',
+            description: 'Local server and runtime toggles used by Docker and native notebook sessions.',
+            vars: [
+                v('DQL_HOST', 'Notebook bind host', 'Host interface for the local notebook server. Docker uses 0.0.0.0 inside the container.'),
+                v('DQL_RUNTIME_URL', 'Runtime URL', 'Optional URL used by headless agent commands to call an existing runtime.'),
+                v('DQL_LLM_KEY', 'Legacy LLM key', 'Fallback key accepted by older Claude provider configurations.'),
+            ],
+        },
+    ];
+}
+//# sourceMappingURL=local-runtime.js.map