@duckcodeailabs/dql-cli 0.8.4 → 0.8.6

package/dist/local-runtime.js

@@ -1,17 +1,23 @@
 import { createServer } from 'node:http';
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, watch, writeFileSync } from 'node:fs';
-import { dirname, extname, join, normalize, resolve } from 'node:path';
+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, } from '@duckcodeailabs/dql-notebook';
 import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLineageGraph, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, } from '@duckcodeailabs/dql-core';
+import { listBlockTemplates } from './block-templates.js';
+import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
 export async function startLocalServer(opts) {
-    const { rootDir, executor, connection, preferredPort, projectRoot = process.cwd() } = opts;
-    const projectConfig = loadProjectConfig(projectRoot);
+    const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
+    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 }; }
@@ -20,10 +26,13 @@ export async function startLocalServer(opts) {
         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 */ }
         }
@@ -83,6 +92,8 @@ export async function startLocalServer(opts) {
                             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;
@@ -221,32 +232,14 @@ export async function startLocalServer(opts) {
         if (req.method === 'GET' && path === '/api/schema') {
             try {
                 const dataFiles = scanDataFiles(projectRoot);
-                // Also query database tables from the connected database
-                let dbTables = [];
-                try {
-                    const connector = await executor.getConnector(connection);
-                    if (typeof connector.listTables === 'function') {
-                        const tables = await connector.listTables();
-                        dbTables = tables.map((t) => {
-                            const qualifiedName = t.schema ? `${t.schema}.${t.name}` : t.name;
-                            return { name: qualifiedName, path: qualifiedName, columns: [], source: 'database' };
-                        });
-                    }
-                    else {
-                        // Fallback: query information_schema directly
-                        const result = await executor.executeQuery(`SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema NOT IN ('information_schema', 'pg_catalog') ORDER BY table_schema, table_name`, [], {}, connection);
-                        dbTables = result.rows.map((row) => {
-                            const schema = String(row['table_schema'] ?? '');
-                            const name = String(row['table_name'] ?? '');
-                            const qualifiedName = schema ? `${schema}.${name}` : name;
-                            return { name: qualifiedName, path: qualifiedName, columns: [], source: 'database' };
-                        });
-                    }
-                }
-                catch {
-                    // Non-fatal: schema discovery from DB may fail if not connected
-                }
-                // Merge: data files first, then db tables (dedup by name)
+                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' })),
@@ -264,25 +257,358 @@ export async function startLocalServer(opts) {
         if (req.method === 'POST' && path === '/api/blocks') {
             try {
                 const body = await readJSON(req);
-                const { name } = body;
+                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 slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'block';
-                const blocksDir = join(projectRoot, 'blocks');
-                mkdirSync(blocksDir, { recursive: true });
-                const blockPath = join(blocksDir, `${slug}.dql`);
-                if (existsSync(blockPath)) {
+                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;
                 }
-                const content = `-- ${name}\nSELECT 1;\n`;
-                writeFileSync(blockPath, content, 'utf-8');
+                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, content, description, tags, metricRefs, template, } = 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 created = createBlockArtifacts(projectRoot, {
+                    name,
+                    domain,
+                    content,
+                    description,
+                    tags,
+                    metricRefs,
+                    template,
+                });
                 res.writeHead(201, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ path: `blocks/${slug}.dql`, content }));
+                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)
+                                        : [];
+                                    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] ?? '',
+                                    });
+                                }
+                                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) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+            }
+            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;
+        }
+        // ── 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 validation = validateBlockStudioSource(source, semanticLayer);
+                if (!validation.executableSql) {
+                    res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: 'No executable SQL found in block source.' }));
+                    return;
+                }
+                const sql = resolveProjectRelativeSqlPaths(validation.executableSql, projectRoot, projectConfig.dataDir);
+                const result = await executor.executeQuery(sql, [], {}, connection);
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    sql: validation.executableSql,
+                    result: normalizeQueryResult(result),
+                    chartConfig: validation.chartConfig ?? null,
+                }));
             }
             catch (error) {
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
@@ -290,6 +616,47 @@ export async function startLocalServer(opts) {
             }
             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;
@@ -305,8 +672,60 @@ export async function startLocalServer(opts) {
             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({
@@ -316,6 +735,11 @@ export async function startLocalServer(opts) {
                     metrics: [],
                     dimensions: [],
                     hierarchies: [],
+                    domains: [],
+                    tags: [],
+                    favorites: userPrefs.favorites,
+                    recentlyUsed: userPrefs.recentlyUsed,
+                    lastSyncTime: semanticLastSyncTime,
                 }));
                 return;
             }
@@ -324,6 +748,7 @@ export async function startLocalServer(opts) {
                 label: m.label,
                 description: m.description,
                 domain: m.domain,
+                sql: m.sql,
                 type: m.type,
                 table: m.table,
                 tags: m.tags ?? [],
@@ -333,9 +758,12 @@ export async function startLocalServer(opts) {
                 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,
             }));
             const hierarchies = semanticLayer.listHierarchies().map((h) => ({
                 name: h.name,
@@ -352,7 +780,343 @@ export async function startLocalServer(opts) {
                 metrics,
                 dimensions,
                 hierarchies,
+                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: [], dimensions: [], hierarchies: [] }));
+                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: type === 'metric' || type === 'dimension' || type === 'hierarchy' ? [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,
+                })),
+                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,
+                })),
+                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 })),
+                })),
+            }));
+            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 ─────────────────────────────────────
@@ -360,10 +1124,26 @@ export async function startLocalServer(opts) {
             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 });
+                    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 });
+                    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' });
@@ -371,6 +1151,56 @@ export async function startLocalServer(opts) {
             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/query') {
             try {
                 const body = await readJSON(req);
@@ -465,6 +1295,119 @@ export async function startLocalServer(opts) {
             }
             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 } = 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 = semanticLayer.composeQuery({ metrics, dimensions, filters, limit, timeDimension, orderBy, 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,
+                    result: normalizeQueryResult(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 === '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', } = 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 = semanticLayer.composeQuery({
+                    metrics,
+                    dimensions,
+                    filters,
+                    timeDimension,
+                    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;
+                }
+                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/test-connection') {
             try {
                 const body = await readJSON(req);
@@ -968,23 +1911,32 @@ function scanNotebookFiles(projectRoot) {
         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(dir, { withFileTypes: true })) {
+            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: `${folder}/${entry.name}`,
+                    path: relativePath,
                     type,
-                    folder,
+                    folder: relativeDir.split('/')[0] ?? relativeDir,
                 });
             }
         }
         catch { /* skip unreadable dirs */ }
     }
-    return result;
 }
 function scanDataFiles(projectRoot) {
     const dataDir = join(projectRoot, 'data');
@@ -999,6 +1951,699 @@ function scanDataFiles(projectRoot) {
         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 validateBlockStudioSource(source, semanticLayer) {
+    const diagnostics = [];
+    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),
+        });
+    }
+    const semanticRefs = extractBlockStudioSemanticReferences(source);
+    if (semanticLayer) {
+        const refValidation = semanticLayer.validateReferences([
+            ...semanticRefs.metrics,
+            ...semanticRefs.dimensions,
+            ...semanticRefs.segments,
+        ]);
+        for (const unknown of refValidation.unknown) {
+            diagnostics.push({
+                severity: 'error',
+                code: 'semantic_ref',
+                message: `Unknown semantic reference: ${unknown}`,
+            });
+        }
+    }
+    const chartConfig = extractBlockStudioChartConfig(source);
+    if (!chartConfig) {
+        diagnostics.push({
+            severity: 'warning',
+            code: 'visualization_missing',
+            message: 'Block has no visualization section yet.',
+        });
+    }
+    const executableSql = extractBlockStudioSql(source);
+    if (!executableSql) {
+        diagnostics.push({
+            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),
+    };
+}
+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 fileContent = normalizeBlockStudioContent({
+        name: options.name,
+        domain: safeDomain || 'uncategorized',
+        description: options.description,
+        tags: options.tags,
+        content: options.content?.trim() || templateContent,
+    });
+    writeFileSync(blockPath, fileContent, 'utf-8');
+    const relativePath = safeDomain ? `blocks/${safeDomain}/${slug}.dql` : `blocks/${slug}.dql`;
+    const companionPath = writeBlockCompanionFile(projectRoot, {
+        slug,
+        name: options.name,
+        domain: safeDomain || 'uncategorized',
+        description: options.description,
+        tags: options.tags,
+        provider: 'dql',
+        content: fileContent,
+    });
+    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 = 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)}`);
+    }
+    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,
+        description: options.description,
+        tags: options.tags,
+        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 = ""',
+    ];
+    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('    """');
+    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;