@duckcodeailabs/dql-cli 1.4.1 → 1.4.4

package/{dist/local-runtime.js → local-runtime.js}

@@ -3,12 +3,14 @@ import { createServer } from 'node:http';
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
 import { dirname, extname, join, normalize, relative, resolve } from 'node:path';
 import { buildExecutionPlan, createWelcomeNotebook, deserializeNotebook, getConnectorFormSchemas, hasSemanticRefs, resolveSemanticRefs, } from '@duckcodeailabs/dql-notebook';
-import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLineageGraph, buildManifest, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
+import { loadSemanticLayerFromDir, resolveSemanticLayerAsync, Parser, buildLineageGraph, buildManifest, findAppDocuments, findDashboardsForApp, isBlockIdRef, loadAppDocument, loadDashboardDocument, analyzeImpact, buildTrustChain, detectDomainFlows, getDomainTrustOverview, queryLineage, queryCompleteLineagePaths, LineageGraph, canonicalize, canonicalizeNotebook, diffDQL, diffNotebook, } from '@duckcodeailabs/dql-core';
 import { load as loadYaml } from 'js-yaml';
 import { listBlockTemplates } from './block-templates.js';
 import { getRunner as getLLMRunner } from './llm/index.js';
 import { handleAppsApi } from './apps-api.js';
+import { DQLAccessDeniedError, activePersonaAppId, assertAppAccess, loadRuntimeApp, runtimeVariables, } from './governance-runtime.js';
 import { buildSemanticObjectDetail, buildSemanticTree, computeSyncDiff, loadSemanticImportManifest, performSemanticImport, previewSemanticImport, syncSemanticImport, } from './semantic-import.js';
+import { MetricFlowUnavailableError, compileMetricFlowQuery, hasDbtSemanticManifest, } from './metricflow.js';
 export async function startLocalServer(opts) {
     const { rootDir, executor, connection: rawConnection, preferredPort, projectRoot = process.cwd() } = opts;
     const bindHost = opts.host ?? process.env.DQL_HOST ?? '127.0.0.1';
@@ -138,6 +140,117 @@ export async function startLocalServer(opts) {
             res.end(serializeJSON({ status: 'ok' }));
             return;
         }
+        if (req.method === 'GET' && path === '/api/settings/env-status') {
+            res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(serializeJSON({ groups: collectSettingsEnvStatus() }));
+            return;
+        }
+        const appDashRun = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/run$/);
+        if (req.method === 'POST' && appDashRun) {
+            try {
+                const appId = decodeURIComponent(appDashRun[1]);
+                const dashboardId = decodeURIComponent(appDashRun[2]);
+                const body = await readJSON(req).catch(() => ({}));
+                const loaded = loadAppDashboard(projectRoot, appId, dashboardId);
+                if (!loaded) {
+                    res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: `Dashboard "${dashboardId}" not found in app "${appId}"` }));
+                    return;
+                }
+                const manifest = buildManifest({ projectRoot });
+                const variables = body.variables && typeof body.variables === 'object'
+                    ? body.variables
+                    : {};
+                const tiles = [];
+                for (const item of loaded.dashboard.layout.items) {
+                    const block = resolveDashboardItemBlock(item, manifest);
+                    if (!block) {
+                        tiles.push({
+                            tileId: item.i,
+                            status: 'unresolved',
+                            blockRef: isBlockIdRef(item.block) ? item.block.blockId : item.block.ref,
+                            error: 'Block reference could not be resolved',
+                        });
+                        continue;
+                    }
+                    try {
+                        assertAppAccess({
+                            app: loaded.app,
+                            domain: block.domain ?? loaded.dashboard.metadata.domain ?? loaded.app.domain,
+                            level: 'execute',
+                        });
+                        const absBlockPath = join(projectRoot, block.filePath);
+                        const source = readFileSync(absBlockPath, 'utf-8');
+                        const semanticCompose = semanticLayer
+                            ? composeSemanticBlockSql(source, semanticLayer, {
+                                driver: connection.driver,
+                                projectRoot,
+                                projectConfig,
+                                detectedProvider: semanticDetectedProvider,
+                            })
+                            : null;
+                        const plan = buildExecutionPlan({ id: item.i, type: 'dql', source, title: item.title ?? block.name }, { semanticLayer, driver: connection.driver });
+                        if (!plan && !semanticCompose?.sql) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'error',
+                                blockId: block.name,
+                                error: semanticCompose?.diagnostics.find((diagnostic) => diagnostic.severity === 'error')?.message ?? 'Block produced no executable plan',
+                            });
+                            continue;
+                        }
+                        const prepared = prepareLocalExecution(semanticCompose?.sql ?? plan.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
+                        const result = await executor.executeQuery(prepared.sql, plan?.sqlParams ?? [], runtimeVariables({ ...(plan?.variables ?? {}), ...variables }), prepared.connection);
+                        tiles.push({
+                            tileId: item.i,
+                            status: 'ok',
+                            blockId: block.name,
+                            blockPath: block.filePath,
+                            certificationStatus: block.status ?? null,
+                            title: item.title ?? block.name,
+                            viz: item.viz,
+                            chartConfig: plan?.chartConfig ?? { chart: item.viz.type },
+                            result: normalizeQueryResult(result),
+                            citation: {
+                                kind: 'block',
+                                name: block.name,
+                                path: block.filePath,
+                            },
+                        });
+                    }
+                    catch (err) {
+                        if (err instanceof DQLAccessDeniedError) {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'unauthorized',
+                                blockId: block.name,
+                                error: err.message,
+                            });
+                        }
+                        else {
+                            tiles.push({
+                                tileId: item.i,
+                                status: 'error',
+                                blockId: block.name,
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                        }
+                    }
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    appId,
+                    dashboardId,
+                    persona: activePersonaAppId() ? { appId: activePersonaAppId() } : null,
+                    tiles,
+                }));
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({ error: err instanceof Error ? err.message : String(err) }));
+            }
+            return;
+        }
         // Apps, dashboards, persona — see apps-api.ts. Returns true if handled.
         if (path.startsWith('/api/apps') || path === '/api/persona') {
             try {
@@ -218,6 +331,11 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ path: `notebooks/${slug}.dqlnb`, content }));
             }
             catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
@@ -249,6 +367,11 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ ok: true }));
             }
             catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
@@ -584,6 +707,11 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ blocks }));
             }
             catch (error) {
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
             }
@@ -636,8 +764,12 @@ export async function startLocalServer(opts) {
                 res.end(serializeJSON({ apps }));
             }
             catch (error) {
-                res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
-                res.end(serializeJSON({ error: error instanceof Error ? error.message : String(error) }));
+                const status = error instanceof DQLAccessDeniedError ? 403 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    ...(status === 403 ? { code: 'unauthorized' } : {}),
+                }));
             }
             return;
         }
@@ -918,7 +1050,13 @@ export async function startLocalServer(opts) {
                     }
                 }
                 const semanticCompose = semanticLayer
-                    ? composeSemanticBlockSql(source, semanticLayer, { driver: targetConnection.driver, tableMapping })
+                    ? composeSemanticBlockSql(source, semanticLayer, {
+                        driver: targetConnection.driver,
+                        tableMapping,
+                        projectRoot,
+                        projectConfig,
+                        detectedProvider: semanticDetectedProvider,
+                    })
                     : null;
                 const validation = validateBlockStudioSource(source, semanticLayer);
                 const executableSql = semanticCompose?.sql ?? validation.executableSql;
@@ -930,13 +1068,14 @@ export async function startLocalServer(opts) {
                     res.end(serializeJSON({ error: message, diagnostics: validation.diagnostics }));
                     return;
                 }
-                const sql = resolveProjectRelativeSqlPaths(executableSql, projectRoot, projectConfig.dataDir);
-                const result = await executor.executeQuery(sql, [], {}, targetConnection);
+                const plan = buildExecutionPlan({ id: 'block-studio', type: 'dql', source, title: 'Block Studio' }, { semanticLayer, driver: targetConnection.driver });
+                const sql = resolveProjectRelativeSqlPaths(semanticCompose?.sql ?? plan?.sql ?? executableSql, projectRoot, projectConfig.dataDir);
+                const result = await executor.executeQuery(sql, plan?.sqlParams ?? [], runtimeVariables(plan?.variables ?? {}), targetConnection);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
-                    sql: executableSql,
+                    sql: plan?.sql ?? executableSql,
                     result: normalizeQueryResult(result),
-                    chartConfig: validation.chartConfig ?? null,
+                    chartConfig: plan?.chartConfig ?? validation.chartConfig ?? null,
                 }));
             }
             catch (error) {
@@ -1062,8 +1201,13 @@ export async function startLocalServer(opts) {
                     provider: projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? null,
                     errors: semanticLayerErrors,
                     metrics: [],
+                    measures: [],
                     dimensions: [],
+                    timeDimensions: [],
+                    entities: [],
                     hierarchies: [],
+                    semanticModels: [],
+                    savedQueries: [],
                     domains: [],
                     tags: [],
                     favorites: userPrefs.favorites,
@@ -1082,6 +1226,25 @@ export async function startLocalServer(opts) {
                 table: m.table,
                 tags: m.tags ?? [],
                 owner: m.owner ?? null,
+                metricType: m.metricType ?? null,
+                typeParams: m.typeParams ?? null,
+                filter: m.filter ?? null,
+                source: m.source ?? null,
+            }));
+            const measures = semanticLayer.listMeasures().map((m) => ({
+                name: m.name,
+                label: m.label,
+                description: m.description,
+                domain: m.domain,
+                agg: m.agg,
+                expr: m.expr ?? null,
+                table: m.table,
+                cube: m.cube ?? null,
+                aggTimeDimension: m.aggTimeDimension ?? null,
+                nonAdditiveDimension: m.nonAdditiveDimension ?? null,
+                tags: m.tags ?? [],
+                owner: m.owner ?? null,
+                source: m.source ?? null,
             }));
             const dimensions = semanticLayer.listDimensions().map((d) => ({
                 name: d.name,
@@ -1093,6 +1256,40 @@ export async function startLocalServer(opts) {
                 table: d.table,
                 tags: d.tags ?? [],
                 owner: d.owner ?? null,
+                cube: d.cube ?? null,
+                isTimeDimension: d.isTimeDimension ?? false,
+                typeParams: d.typeParams ?? null,
+                source: d.source ?? null,
+            }));
+            const timeDimensions = semanticLayer.listTimeDimensions().map((d) => ({
+                name: d.name,
+                label: d.label,
+                description: d.description,
+                domain: d.domain,
+                sql: d.sql,
+                type: d.type,
+                table: d.table,
+                cube: d.cube ?? null,
+                granularities: d.granularities ?? [],
+                primaryTime: d.primaryTime ?? false,
+                tags: d.tags ?? [],
+                owner: d.owner ?? null,
+                typeParams: d.typeParams ?? null,
+                source: d.source ?? null,
+            }));
+            const entities = semanticLayer.listEntities().map((e) => ({
+                name: e.name,
+                label: e.label,
+                description: e.description,
+                domain: e.domain,
+                type: e.type,
+                expr: e.expr ?? null,
+                table: e.table,
+                cube: e.cube ?? null,
+                role: e.role ?? null,
+                tags: e.tags ?? [],
+                owner: e.owner ?? null,
+                source: e.source ?? null,
             }));
             const hierarchies = semanticLayer.listHierarchies().map((h) => ({
                 name: h.name,
@@ -1101,14 +1298,61 @@ export async function startLocalServer(opts) {
                 domain: h.domain,
                 levels: h.levels.map((l) => ({ name: l.name, label: l.label })),
             }));
+            const semanticModels = semanticLayer.listSemanticModels().map((m) => ({
+                name: m.name,
+                label: m.label,
+                description: m.description,
+                domain: m.domain,
+                model: m.model ?? null,
+                table: m.table,
+                entities: m.entities,
+                measures: m.measures,
+                dimensions: m.dimensions,
+                timeDimensions: m.timeDimensions,
+                tags: m.tags ?? [],
+                owner: m.owner ?? null,
+                source: m.source ?? null,
+            }));
+            const savedQueries = semanticLayer.listSavedQueries().map((q) => ({
+                name: q.name,
+                label: q.label,
+                description: q.description,
+                domain: q.domain,
+                metrics: q.metrics,
+                dimensions: q.dimensions,
+                timeDimension: q.timeDimension ?? null,
+                granularity: q.granularity ?? null,
+                filters: q.filters ?? null,
+                tags: q.tags ?? [],
+                owner: q.owner ?? null,
+                source: q.source ?? null,
+            }));
+            const provider = projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? 'dql';
+            const dbtExecutionReady = provider === 'dbt'
+                ? hasDbtSemanticManifest(projectRoot, projectConfig.semanticLayer?.projectPath)
+                : false;
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
                 available: true,
-                provider: projectConfig.semanticLayer?.provider ?? semanticDetectedProvider ?? 'dql',
+                provider,
+                execution: provider === 'dbt'
+                    ? {
+                        engine: 'metricflow',
+                        ready: dbtExecutionReady,
+                        setup: dbtExecutionReady
+                            ? null
+                            : 'Run `dbt parse` or `dbt build` so target/semantic_manifest.json exists, and install MetricFlow so `mf` is on PATH.',
+                    }
+                    : { engine: 'native', ready: true, setup: null },
                 errors: semanticLayerErrors,
                 metrics,
+                measures,
                 dimensions,
+                timeDimensions,
+                entities,
                 hierarchies,
+                semanticModels,
+                savedQueries,
                 domains: semanticLayer.listDomains(),
                 tags: semanticLayer.listTags(),
                 favorites: userPrefs.favorites,
@@ -1329,7 +1573,7 @@ export async function startLocalServer(opts) {
         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: [] }));
+                res.end(serializeJSON({ metrics: [], measures: [], dimensions: [], timeDimensions: [], entities: [], hierarchies: [], semanticModels: [], savedQueries: [] }));
                 return;
             }
             const q = url.searchParams.get('q') ?? '';
@@ -1339,7 +1583,7 @@ export async function startLocalServer(opts) {
             const results = semanticLayer.searchAdvanced(q, {
                 domains: domain ? [domain] : undefined,
                 tags: tag ? [tag] : undefined,
-                types: type === 'metric' || type === 'dimension' || type === 'hierarchy' ? [type] : undefined,
+                types: ['metric', 'measure', 'dimension', 'hierarchy', 'entity', 'semantic_model', 'saved_query'].includes(type) ? [type] : undefined,
             });
             res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
             res.end(serializeJSON({
@@ -1354,6 +1598,18 @@ export async function startLocalServer(opts) {
                     tags: m.tags ?? [],
                     owner: m.owner ?? null,
                 })),
+                measures: results.measures.map((m) => ({
+                    name: m.name,
+                    label: m.label,
+                    description: m.description,
+                    domain: m.domain,
+                    agg: m.agg,
+                    expr: m.expr,
+                    table: m.table,
+                    cube: m.cube,
+                    tags: m.tags ?? [],
+                    owner: m.owner ?? null,
+                })),
                 dimensions: results.dimensions.map((d) => ({
                     name: d.name,
                     label: d.label,
@@ -1365,6 +1621,27 @@ export async function startLocalServer(opts) {
                     tags: d.tags ?? [],
                     owner: d.owner ?? null,
                 })),
+                timeDimensions: semanticLayer.listTimeDimensions().filter((d) => results.dimensions.some((dim) => dim.name === d.name)).map((d) => ({
+                    name: d.name,
+                    label: d.label,
+                    description: d.description,
+                    domain: d.domain,
+                    sql: d.sql,
+                    type: d.type,
+                    table: d.table,
+                    tags: d.tags ?? [],
+                    owner: d.owner ?? null,
+                })),
+                entities: results.entities.map((e) => ({
+                    name: e.name,
+                    label: e.label,
+                    description: e.description,
+                    domain: e.domain,
+                    type: e.type,
+                    table: e.table,
+                    tags: e.tags ?? [],
+                    owner: e.owner ?? null,
+                })),
                 hierarchies: results.hierarchies.map((h) => ({
                     name: h.name,
                     label: h.label,
@@ -1372,6 +1649,24 @@ export async function startLocalServer(opts) {
                     domain: h.domain,
                     levels: h.levels.map((l) => ({ name: l.name, label: l.label })),
                 })),
+                semanticModels: results.semanticModels.map((m) => ({
+                    name: m.name,
+                    label: m.label,
+                    description: m.description,
+                    domain: m.domain,
+                    table: m.table,
+                    measures: m.measures,
+                    dimensions: m.dimensions,
+                    timeDimensions: m.timeDimensions,
+                })),
+                savedQueries: results.savedQueries.map((q) => ({
+                    name: q.name,
+                    label: q.label,
+                    description: q.description,
+                    domain: q.domain,
+                    metrics: q.metrics,
+                    dimensions: q.dimensions,
+                })),
             }));
             return;
         }
@@ -1538,7 +1833,7 @@ export async function startLocalServer(opts) {
                 return;
             }
             const { provider, messages, upstream } = body;
-            const runner = provider === 'claude-agent-sdk' || provider === 'claude-code' ? getLLMRunner(provider) : null;
+            const runner = isLLMProviderId(provider) ? getLLMRunner(provider) : null;
             if (!runner) {
                 res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({ error: `Unknown provider: ${provider}` }));
@@ -1587,7 +1882,10 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const prepared = prepareLocalExecution(semantic.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
-                const result = await executor.executeQuery(prepared.sql, Array.isArray(body.sqlParams) ? body.sqlParams : [], body.variables && typeof body.variables === 'object' ? body.variables : {}, prepared.connection);
+                const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
+                const domain = typeof body.domain === 'string' ? body.domain : app?.domain;
+                assertAppAccess({ app, domain, level: 'execute' });
+                const result = await executor.executeQuery(prepared.sql, Array.isArray(body.sqlParams) ? body.sqlParams : [], runtimeVariables(body.variables && typeof body.variables === 'object' ? body.variables : {}), prepared.connection);
                 const payload = serializeJSON(normalizeQueryResult(result, semantic.semanticRefs));
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(payload);
@@ -1597,6 +1895,16 @@ export async function startLocalServer(opts) {
                     res.end();
                     return;
                 }
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({
+                        columns: [],
+                        rows: [],
+                        error: error.message,
+                        code: 'unauthorized',
+                    }));
+                    return;
+                }
                 res.writeHead(500, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     columns: [],
@@ -1615,7 +1923,7 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const body = await readJSON(req);
-                const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy } = body;
+                const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
                 // Resolve which connection to use — request can override default
                 const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
                 const driver = targetConnection.driver;
@@ -1649,7 +1957,22 @@ export async function startLocalServer(opts) {
                 catch {
                     // Non-fatal: proceed without table mapping
                 }
-                const composed = semanticLayer.composeQuery({ metrics, dimensions, filters, limit, timeDimension, orderBy, driver, tableMapping });
+                const composed = composeRuntimeSemanticQuery({
+                    metrics,
+                    dimensions,
+                    filters,
+                    limit,
+                    timeDimension,
+                    orderBy,
+                    savedQuery,
+                    engine,
+                }, semanticLayer, {
+                    projectRoot,
+                    projectConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    driver,
+                    tableMapping,
+                });
                 if (!composed) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ error: `Could not compose query for metrics: [${metrics.join(', ')}]` }));
@@ -1663,12 +1986,25 @@ export async function startLocalServer(opts) {
                     sql: composed.sql,
                     tables: composed.tables,
                     joins: composed.joins,
+                    engine: composed.engine,
                     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) }));
+                if (error instanceof DQLAccessDeniedError) {
+                    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+                    res.end(serializeJSON({ error: error.message, code: 'unauthorized' }));
+                    return;
+                }
+                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
+                    hint: error instanceof MetricFlowUnavailableError
+                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                        : undefined,
+                }));
             }
             return;
         }
@@ -1680,7 +2016,7 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const body = await readJSON(req);
-                const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy } = body;
+                const { metrics = [], dimensions = [], filters = [], limit, timeDimension, orderBy, savedQuery, engine } = body;
                 const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
                 const driver = targetConnection.driver;
                 let tableMapping;
@@ -1707,7 +2043,22 @@ export async function startLocalServer(opts) {
                 catch {
                     tableMapping = undefined;
                 }
-                const composed = semanticLayer.composeQuery({ metrics, dimensions, filters, limit, timeDimension, orderBy, driver, tableMapping });
+                const composed = composeRuntimeSemanticQuery({
+                    metrics,
+                    dimensions,
+                    filters,
+                    limit,
+                    timeDimension,
+                    orderBy,
+                    savedQuery,
+                    engine,
+                }, semanticLayer, {
+                    projectRoot,
+                    projectConfig,
+                    detectedProvider: semanticDetectedProvider,
+                    driver,
+                    tableMapping,
+                });
                 if (!composed) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ error: 'Could not compose semantic block preview SQL.' }));
@@ -1720,12 +2071,20 @@ export async function startLocalServer(opts) {
                     sql: composed.sql,
                     joins: composed.joins,
                     tables: composed.tables,
+                    engine: composed.engine,
                     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) }));
+                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
+                    hint: error instanceof MetricFlowUnavailableError
+                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                        : undefined,
+                }));
             }
             return;
         }
@@ -1737,18 +2096,23 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const body = await readJSON(req);
-                const { name, domain, description, owner, tags, metrics = [], dimensions = [], timeDimension, filters = [], chart = 'table', blockType = 'semantic', } = body;
+                const { name, domain, description, owner, tags, metrics = [], dimensions = [], timeDimension, filters = [], chart = 'table', blockType = 'semantic', engine, } = body;
                 if (!name || metrics.length === 0) {
                     res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
                     res.end(serializeJSON({ error: 'name and at least one metric are required.' }));
                     return;
                 }
                 const targetConnection = isConnectionConfig(body.connection) ? body.connection : connection;
-                const composed = semanticLayer.composeQuery({
+                const composed = composeRuntimeSemanticQuery({
                     metrics,
                     dimensions,
                     filters,
                     timeDimension,
+                    engine,
+                }, semanticLayer, {
+                    projectRoot,
+                    projectConfig,
+                    detectedProvider: semanticDetectedProvider,
                     driver: targetConnection.driver,
                 });
                 if (!composed) {
@@ -1780,8 +2144,15 @@ export async function startLocalServer(opts) {
                     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) }));
+                const status = error instanceof MetricFlowUnavailableError ? 400 : 500;
+                res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+                res.end(serializeJSON({
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : undefined,
+                    hint: error instanceof MetricFlowUnavailableError
+                        ? 'Install dbt Semantic Layer dependencies, run dbt parse/build to create target/semantic_manifest.json, then retry.'
+                        : undefined,
+                }));
             }
             return;
         }
@@ -2041,7 +2412,9 @@ export async function startLocalServer(opts) {
                     return;
                 }
                 const prepared = prepareLocalExecution(plan.sql, isConnectionConfig(body.connection) ? body.connection : connection, projectRoot, projectConfig);
-                const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, plan.variables, prepared.connection);
+                const app = loadRuntimeApp(projectRoot, typeof body.appId === 'string' ? body.appId : activePersonaAppId());
+                assertAppAccess({ app, domain: app?.domain, level: 'execute' });
+                const rawResult = await executor.executeQuery(prepared.sql, plan.sqlParams, runtimeVariables(plan.variables), prepared.connection);
                 res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
                 res.end(serializeJSON({
                     cellType: cell.type,
@@ -2171,6 +2544,34 @@ function normalizeQueryResult(result, semanticRefs) {
         ...(hasRefs ? { semanticRefs } : {}),
     };
 }
+function isLLMProviderId(value) {
+    return value === 'claude-agent-sdk'
+        || value === 'claude-code'
+        || value === 'openai'
+        || value === 'gemini'
+        || value === 'ollama';
+}
+function loadAppDashboard(projectRoot, appId, dashboardId) {
+    for (const p of findAppDocuments(projectRoot)) {
+        const { document: app } = loadAppDocument(p);
+        if (!app || app.id !== appId)
+            continue;
+        const appDir = p.slice(0, -'/dql.app.json'.length);
+        for (const d of findDashboardsForApp(appDir)) {
+            const { document: dashboard } = loadDashboardDocument(d);
+            if (dashboard?.id === dashboardId)
+                return { app, dashboard };
+        }
+    }
+    return null;
+}
+function resolveDashboardItemBlock(item, manifest) {
+    if (isBlockIdRef(item.block)) {
+        return manifest.blocks[item.block.blockId] ?? null;
+    }
+    const normalizedRef = normalize(item.block.ref).replaceAll('\\', '/');
+    return Object.values(manifest.blocks).find((b) => normalize(b.filePath).replaceAll('\\', '/') === normalizedRef) ?? null;
+}
 export function serializeJSON(value) {
     return JSON.stringify(value, (_key, current) => {
         if (typeof current === 'bigint') {
@@ -2679,6 +3080,46 @@ function buildSemanticTableMapping(semanticLayer, rows) {
     }
     return Object.keys(tableMapping).length > 0 ? tableMapping : undefined;
 }
+function isDbtSemanticRuntime(projectConfig, detectedProvider, semanticLayer) {
+    if (projectConfig.semanticLayer?.provider === 'dbt' || detectedProvider === 'dbt')
+        return true;
+    return Boolean(semanticLayer?.listMetrics().some((metric) => metric.source?.provider === 'dbt'));
+}
+function composeRuntimeSemanticQuery(request, semanticLayer, context) {
+    const useMetricFlow = request.engine === 'metricflow' || (request.engine !== 'native' &&
+        isDbtSemanticRuntime(context.projectConfig, context.detectedProvider, semanticLayer));
+    if (useMetricFlow) {
+        const dbtProjectPath = context.projectConfig.semanticLayer?.projectPath;
+        const compiled = compileMetricFlowQuery({
+            projectRoot: context.projectRoot,
+            dbtProjectPath,
+            metrics: request.metrics,
+            dimensions: request.dimensions,
+            filters: request.filters,
+            timeDimension: request.timeDimension,
+            orderBy: request.orderBy,
+            limit: request.limit,
+            savedQuery: request.savedQuery,
+        });
+        return {
+            sql: compiled.sql,
+            joins: [],
+            tables: [],
+            engine: 'metricflow',
+        };
+    }
+    const composed = semanticLayer.composeQuery({
+        metrics: request.metrics,
+        dimensions: request.dimensions,
+        filters: request.filters,
+        limit: request.limit,
+        timeDimension: request.timeDimension,
+        orderBy: request.orderBy,
+        driver: context.driver,
+        tableMapping: context.tableMapping,
+    });
+    return composed ? { ...composed, engine: 'native' } : null;
+}
 function composeSemanticBlockSql(source, semanticLayer, options) {
     const config = parseSemanticBlockConfig(source);
     const metrics = config.metrics.length > 0
@@ -2721,16 +3162,42 @@ function composeSemanticBlockSql(source, semanticLayer, options) {
     if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
         return { sql: null, diagnostics, semanticRefs };
     }
-    const composed = semanticLayer.composeQuery({
-        metrics,
-        dimensions: config.dimensions,
-        timeDimension: config.timeDimension && config.granularity
-            ? { name: config.timeDimension, granularity: config.granularity }
-            : undefined,
-        limit: config.limit,
-        driver: options?.driver,
-        tableMapping: options?.tableMapping,
-    });
+    let composed;
+    try {
+        composed = options?.projectRoot && options.projectConfig
+            ? composeRuntimeSemanticQuery({
+                metrics,
+                dimensions: config.dimensions,
+                timeDimension: config.timeDimension && config.granularity
+                    ? { name: config.timeDimension, granularity: config.granularity }
+                    : undefined,
+                limit: config.limit,
+            }, semanticLayer, {
+                projectRoot: options.projectRoot,
+                projectConfig: options.projectConfig,
+                detectedProvider: options.detectedProvider ?? null,
+                driver: options.driver,
+                tableMapping: options.tableMapping,
+            })
+            : semanticLayer.composeQuery({
+                metrics,
+                dimensions: config.dimensions,
+                timeDimension: config.timeDimension && config.granularity
+                    ? { name: config.timeDimension, granularity: config.granularity }
+                    : undefined,
+                limit: config.limit,
+                driver: options?.driver,
+                tableMapping: options?.tableMapping,
+            });
+    }
+    catch (error) {
+        diagnostics.push({
+            severity: 'error',
+            code: error instanceof MetricFlowUnavailableError ? 'metricflow_unavailable' : 'semantic_compose_failed',
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { sql: null, diagnostics, semanticRefs };
+    }
     if (!composed) {
         diagnostics.push({
             severity: 'error',
@@ -3833,4 +4300,58 @@ function computeSemanticDiff(filePath, before, after) {
         return null;
     }
 }
+function collectSettingsEnvStatus() {
+    const v = (key, label, description, optional = true) => ({
+        key,
+        label,
+        description,
+        optional,
+        present: typeof process.env[key] === 'string' && process.env[key].trim().length > 0,
+    });
+    return [
+        {
+            id: 'ai',
+            title: 'AI Chat Providers',
+            description: 'Configure one or more providers. Missing keys are only a problem when that provider is selected.',
+            vars: [
+                v('ANTHROPIC_API_KEY', 'Claude Agent SDK', 'Hosted Claude provider for notebook Chat and agent commands.'),
+                v('OPENAI_API_KEY', 'OpenAI', 'Hosted OpenAI provider for notebook Chat and agent commands.'),
+                v('OPENAI_MODEL', 'OpenAI model', 'Optional override such as gpt-4.1-mini or the model your account uses.'),
+                v('GEMINI_API_KEY', 'Gemini', 'Hosted Gemini provider for notebook Chat and agent commands.'),
+                v('GEMINI_MODEL', 'Gemini model', 'Optional Gemini model override.'),
+                v('OLLAMA_BASE_URL', 'Ollama base URL', 'Local Ollama HTTP endpoint. Docker defaults to http://ollama:11434.'),
+                v('OLLAMA_MODEL', 'Ollama model', 'Optional local model name such as llama3.1.'),
+            ],
+        },
+        {
+            id: 'slack',
+            title: 'Slack',
+            description: 'Use webhooks for scheduled App deliveries, or bot credentials for the Slack chat front-end.',
+            vars: [
+                v('DQL_SLACK_WEBHOOK', 'Schedule webhook', 'Incoming webhook used by App schedules that deliver to Slack.'),
+                v('SLACK_SIGNING_SECRET', 'Slack signing secret', 'Required only when running `dql slack serve`.'),
+                v('SLACK_BOT_TOKEN', 'Slack bot token', 'Bot token used by Slack chat commands when `dql slack serve` is enabled.'),
+            ],
+        },
+        {
+            id: 'email',
+            title: 'Email',
+            description: 'SMTP is optional. Without it, email schedules stay in stub mode with a clear delivery message.',
+            vars: [
+                v('DQL_SMTP_URL', 'SMTP URL', 'SMTP connection URL for email schedule delivery.'),
+                v('DQL_SMTP_FROM', 'SMTP sender', 'Optional sender address for scheduled emails.'),
+            ],
+        },
+        {
+            id: 'runtime',
+            title: 'Runtime',
+            description: 'Local server and runtime toggles used by Docker and native notebook sessions.',
+            vars: [
+                v('DQL_HOST', 'Notebook bind host', 'Host interface for the local notebook server. Docker uses 0.0.0.0 inside the container.'),
+                v('DQL_RUNTIME_URL', 'Runtime URL', 'Optional URL used by headless agent commands to call an existing runtime.'),
+                v('DQL_LLM_KEY', 'Legacy LLM key', 'Fallback key accepted by older Claude provider configurations.'),
+            ],
+        },
+    ];
+}
 //# sourceMappingURL=local-runtime.js.map