@duckcodeailabs/dql-cli 1.6.18 → 1.6.20

package/dist/apps-api.d.ts

@@ -4,7 +4,7 @@
  * dispatcher — returns `true` if the request was handled, `false` otherwise.
  */
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { type AppDocument } from '@duckcodeailabs/dql-core';
+import { type AppDocument, type DashboardDisplayMetadata, type DashboardDocument } from '@duckcodeailabs/dql-core';
 import { type LocalAppInvestigationIntent } from '@duckcodeailabs/dql-project';
 interface Ctx {
     req: IncomingMessage;
@@ -20,6 +20,7 @@ export declare function handleAppsApi(ctx: Ctx): Promise<boolean>;
 type AppListEntry = {
     id: string;
     name: string;
+    filePath: string;
     domain: string;
     subdomain?: string;
     groups: string[];
@@ -63,6 +64,19 @@ interface AppRecommendationRequest {
     audience?: string;
     certifiedOnly?: boolean;
 }
+interface VisualizationRecommendationRequest {
+    blockRef?: string;
+    resultSchema?: unknown;
+    rowSample?: Array<Record<string, unknown>>;
+    rows?: Array<Record<string, unknown>>;
+    appAudience?: string;
+    audience?: string;
+    prompt?: string;
+    filters?: unknown;
+    allowedVisualizations?: string[];
+    component?: DashboardDisplayMetadata['component'];
+    defaultVisualization?: string;
+}
 interface AppCreateRequest {
     name?: string;
     domain?: string;
@@ -122,6 +136,18 @@ interface BlockCandidate {
     reasons: string[];
 }
 export declare function recommendBlocks(projectRoot: string, input: AppRecommendationRequest): BlockCandidate[];
+export declare function recommendVisualization(projectRoot: string, input: VisualizationRecommendationRequest): {
+    ok: true;
+    display: DashboardDisplayMetadata;
+    evidence: Array<{
+        source: string;
+        reason: string;
+    }>;
+    warnings: string[];
+} | {
+    ok: false;
+    error: string;
+};
 export declare function generateAppPackage(projectRoot: string, input: AppGenerateRequest): Promise<{
     ok: true;
     plan: unknown;
@@ -157,8 +183,22 @@ declare function buildDeterministicInvestigationSql(projectRoot: string, input:
     sourceBlockPath: string;
     sourceBlockName: string;
 } | undefined;
+export declare function createDashboardForApp(projectRoot: string, appId: string, input: {
+    id?: string;
+    title?: string;
+    description?: string;
+}): {
+    ok: true;
+    dashboard: DashboardDocument;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
 declare function loadAppById(projectRoot: string, id: string): {
     app: AppDocument;
+    appDir: string;
+    appPath: string;
     dashboards: Array<{
         id: string;
         title: string;

package/dist/apps-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps-api.d.ts","sourceRoot":"","sources":["../src/apps-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apps-api.d.ts","sourceRoot":"","sources":["../src/apps-api.ts"],"names":[],"mappings":"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"}

package/dist/apps-api.js

@@ -9,6 +9,21 @@ import { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboard
 import { defaultPersonaRegistry, defaultLocalAppsDbPath, LocalAppStorage, personaFromMember, } from '@duckcodeailabs/dql-project';
 export async function handleAppsApi(ctx) {
     const { req, res, path, projectRoot } = ctx;
+    if (req.method === 'POST' && path === '/api/visualizations/recommend') {
+        try {
+            const body = await readJson(req);
+            const result = recommendVisualization(projectRoot, body);
+            if (!result.ok) {
+                sendJson(res, 400, result);
+                return true;
+            }
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err.message });
+        }
+        return true;
+    }
     // ── Apps ────────────────────────────────────────────────────────────────
     if (req.method === 'GET' && path === '/api/apps') {
         const apps = collectAppsList(projectRoot);
@@ -107,7 +122,7 @@ export async function handleAppsApi(ctx) {
             sendJson(res, 404, { error: `App "${appId}" not found` });
             return true;
         }
-        sendJson(res, 200, { notebooks: listNotebookCandidates(projectRoot, loaded.app, join(projectRoot, 'apps', appId)) });
+        sendJson(res, 200, { notebooks: listNotebookCandidates(projectRoot, loaded.app, loaded.appDir) });
         return true;
     }
     m = path.match(/^\/api\/apps\/([^/]+)\/notebooks\/create$/);
@@ -612,6 +627,7 @@ function collectAppsList(projectRoot) {
         out.push({
             id: document.id,
             name: document.name,
+            filePath: relative(projectRoot, appDir),
             domain: document.domain,
             subdomain: document.subdomain,
             groups: document.groups ?? [],
@@ -710,6 +726,79 @@ export function recommendBlocks(projectRoot, input) {
         .sort((a, b) => b.score - a.score || new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime())
         .slice(0, 50);
 }
+export function recommendVisualization(projectRoot, input) {
+    const blockRef = cleanString(input.blockRef);
+    const prompt = cleanString(input.prompt).toLowerCase();
+    const audience = cleanString(input.appAudience) || cleanString(input.audience);
+    const rows = Array.isArray(input.rowSample) ? input.rowSample : Array.isArray(input.rows) ? input.rows : [];
+    const columns = extractRecommendationColumns(input.resultSchema, rows);
+    const block = blockRef
+        ? collectBlockCandidates(projectRoot).find((candidate) => candidate.id === blockRef ||
+            candidate.name === blockRef ||
+            candidate.path === blockRef ||
+            candidate.path.endsWith(`/${blockRef}`))
+        : undefined;
+    const evidence = [];
+    const warnings = [];
+    if (block) {
+        evidence.push({ source: block.path, reason: `Block hint: ${block.chartType ?? 'table'}; status: ${block.status}; domain: ${block.domain}` });
+    }
+    else if (blockRef) {
+        warnings.push(`Block reference was not found locally: ${blockRef}`);
+    }
+    if (columns.length > 0) {
+        evidence.push({ source: 'result_schema', reason: `${columns.length} result column(s) were inspected.` });
+    }
+    else {
+        warnings.push('No result schema or row sample was provided, so recommendation used block metadata and prompt only.');
+    }
+    if (audience) {
+        evidence.push({ source: 'audience', reason: `Audience: ${audience}` });
+    }
+    const requestedViz = cleanString(input.defaultVisualization);
+    if (requestedViz && !isSupportedVizType(requestedViz)) {
+        return { ok: false, error: `Unsupported visualization: ${requestedViz}` };
+    }
+    const defaultVisualization = requestedViz
+        ? normalizeVizType(requestedViz)
+        : recommendVizType({ columns, rows, prompt, blockChartType: block?.chartType });
+    const component = input.component ?? componentForViz(defaultVisualization, prompt);
+    if (!componentVizCompatible(component, defaultVisualization)) {
+        return {
+            ok: false,
+            error: `${component} cannot use ${defaultVisualization}. Choose one of ${allowedVisualizationsForComponent(component, defaultVisualization).join(', ')}.`,
+        };
+    }
+    const unsupportedAllowed = (input.allowedVisualizations ?? []).filter((value) => !isSupportedVizType(value));
+    if (unsupportedAllowed.length > 0) {
+        return { ok: false, error: `Unsupported allowed visualization(s): ${unsupportedAllowed.join(', ')}` };
+    }
+    const supportedAllowed = (input.allowedVisualizations ?? [])
+        .map((value) => normalizeVizType(value))
+        .filter((value, index, arr) => arr.indexOf(value) === index);
+    if (supportedAllowed.length > 0 && !supportedAllowed.includes(defaultVisualization)) {
+        return {
+            ok: false,
+            error: `Requested visualization ${defaultVisualization} is outside allowed visualizations: ${supportedAllowed.join(', ')}.`,
+        };
+    }
+    const allowedVisualizations = supportedAllowed.length > 0
+        ? supportedAllowed
+        : allowedVisualizationsForComponent(component, defaultVisualization);
+    const fieldHints = fieldHintsForColumns(columns, rows, prompt);
+    const display = {
+        mode: block ? 'block_hint' : 'ai_generated',
+        component,
+        defaultVisualization,
+        allowedVisualizations,
+        ...(Object.keys(fieldHints).length > 0 ? { fieldHints } : {}),
+        layoutIntent: layoutIntentForComponent(component),
+        rationale: recommendationRationale(component, defaultVisualization, block, columns, prompt),
+        trustState: block?.status === 'certified' ? 'certified' : 'review_required',
+        reviewStatus: block?.status === 'certified' ? 'certified' : 'review_required',
+    };
+    return { ok: true, display, evidence, warnings };
+}
 export async function generateAppPackage(projectRoot, input) {
     const prompt = cleanString(input.prompt);
     if (!prompt)
@@ -758,7 +847,7 @@ export function createAppPackage(projectRoot, input) {
     if (!domain)
         return { ok: false, error: 'domain is required' };
     const id = suggestAppId(name);
-    const appDir = join(projectRoot, 'apps', id);
+    const appDir = resolveAppPackageDir(projectRoot, domain, id);
     if (existsSync(appDir))
         return { ok: false, error: `App already exists: ${id}` };
     const dashboardTitle = cleanString(input.dashboardTitle) || 'Overview';
@@ -901,6 +990,7 @@ function dashboardItemForBlock(block, chartType, x, y, size, index) {
         h: size.h,
         block: { blockId: block.name },
         viz: { type: chartType },
+        display: displayForBlockHint(block, chartType),
         title: block.name,
     };
 }
@@ -957,8 +1047,183 @@ function normalizeVizType(chartType) {
         return 'map';
     if (normalized === 'funnel')
         return 'funnel';
+    if (normalized === 'text')
+        return 'text';
+    if (normalized === 'heading')
+        return 'heading';
     return 'table';
 }
+function isSupportedVizType(chartType) {
+    const normalized = (chartType ?? '').toLowerCase().replace(/-/g, '_');
+    return [
+        'single', 'single_value', 'kpi', 'line', 'bar', 'grouped_bar', 'stacked_bar',
+        'area', 'pie', 'donut', 'scatter', 'heatmap', 'histogram', 'waterfall',
+        'gauge', 'pivot', 'map', 'funnel', 'table', 'text', 'heading',
+    ].includes(normalized);
+}
+function displayForBlockHint(block, chartType) {
+    const component = componentForViz(chartType, `${block.name} ${block.description} ${block.tags.join(' ')}`.toLowerCase());
+    return {
+        mode: 'block_hint',
+        component,
+        defaultVisualization: chartType,
+        allowedVisualizations: allowedVisualizationsForComponent(component, chartType),
+        layoutIntent: layoutIntentForComponent(component),
+        rationale: `Block-level visualization is treated as a display hint for ${block.name}; apps and notebooks may override it.`,
+        trustState: block.status === 'certified' ? 'certified' : 'draft_ready',
+        reviewStatus: block.status === 'certified' ? 'certified' : 'draft_ready',
+    };
+}
+function displayForAiPin(title, chartType, input) {
+    const text = `${title} ${cleanString(input.question)} ${cleanString(input.answer)}`.toLowerCase();
+    const component = componentForViz(chartType, text);
+    const certified = input.certification === 'certified' || input.reviewStatus === 'certified';
+    return {
+        mode: 'ai_generated',
+        component,
+        defaultVisualization: chartType,
+        allowedVisualizations: allowedVisualizationsForComponent(component, chartType),
+        layoutIntent: layoutIntentForComponent(component),
+        rationale: 'AI-generated research pin saved as governed presentation metadata; promote the SQL to a draft block before treating it as reusable logic.',
+        trustState: certified ? 'certified' : 'review_required',
+        reviewStatus: certified ? 'certified' : 'review_required',
+    };
+}
+function extractRecommendationColumns(schema, rows) {
+    const rawColumns = Array.isArray(schema)
+        ? schema
+        : schema && typeof schema === 'object' && Array.isArray(schema.columns)
+            ? schema.columns
+            : [];
+    const columns = rawColumns.flatMap((column) => {
+        if (typeof column === 'string')
+            return [{ name: column }];
+        if (column && typeof column === 'object') {
+            const record = column;
+            const name = cleanString(record.name) || cleanString(record.field) || cleanString(record.id);
+            if (!name)
+                return [];
+            const type = cleanString(record.type) || cleanString(record.dataType);
+            return [{ name, ...(type ? { type } : {}) }];
+        }
+        return [];
+    });
+    if (columns.length > 0)
+        return columns;
+    const first = rows.find((row) => row && typeof row === 'object');
+    return first ? Object.keys(first).map((name) => ({ name, type: typeof first[name] })) : [];
+}
+function recommendVizType(input) {
+    const names = input.columns.map((column) => column.name.toLowerCase());
+    const hasTime = names.some((name) => /\b(date|time|week|month|quarter|year|season|period)\b/.test(name));
+    const measures = input.columns.filter((column) => isMeasureColumn(column, input.rows));
+    const dimensions = input.columns.filter((column) => !isMeasureColumn(column, input.rows));
+    if (/\bpivot|matrix|cross.?tab\b/.test(input.prompt))
+        return 'pivot';
+    if (/\btrend|over time|weekly|monthly|daily|quarterly\b/.test(input.prompt) || (hasTime && measures.length > 0))
+        return 'line';
+    if (/\btop|bottom|rank|ranking|leader|leaderboard|players?|scorers?\b/.test(input.prompt))
+        return 'bar';
+    if (measures.length === 1 && dimensions.length === 0)
+        return 'single_value';
+    if (dimensions.length > 0 && measures.length > 0)
+        return 'bar';
+    return normalizeVizType(input.blockChartType);
+}
+function isMeasureColumn(column, rows) {
+    const type = (column.type ?? '').toLowerCase();
+    if (/\b(number|numeric|decimal|double|float|integer|int|bigint|real)\b/.test(type))
+        return true;
+    const name = column.name.toLowerCase();
+    if (/\b(count|sum|avg|average|total|revenue|arr|amount|rate|score|points?|goals?|rank|value)\b/.test(name))
+        return true;
+    const sample = rows.map((row) => row[column.name]).find((value) => value !== null && value !== undefined);
+    return typeof sample === 'number';
+}
+function fieldHintsForColumns(columns, rows, prompt) {
+    const hints = {};
+    const measure = columns.find((column) => isMeasureColumn(column, rows));
+    const time = columns.find((column) => /\b(date|time|week|month|quarter|year|season|period)\b/i.test(column.name));
+    const rank = columns.find((column) => /\b(rank|position)\b/i.test(column.name));
+    const label = columns.find((column) => !isMeasureColumn(column, rows) && /\b(name|player|customer|account|team|segment|region|category|label)\b/i.test(column.name)) ?? columns.find((column) => !isMeasureColumn(column, rows));
+    if (label)
+        hints.label = label.name;
+    if (measure)
+        hints.value = measure.name;
+    if (time)
+        hints.time = time.name;
+    if (rank || /\brank|top|bottom\b/i.test(prompt))
+        hints.rank = rank?.name ?? 'rank';
+    if (time && measure) {
+        hints.x = time.name;
+        hints.y = measure.name;
+    }
+    else if (label && measure) {
+        hints.x = label.name;
+        hints.y = measure.name;
+    }
+    return hints;
+}
+function componentForViz(viz, text) {
+    if (viz === 'single_value' || viz === 'kpi' || viz === 'gauge')
+        return 'KpiMetric';
+    if (viz === 'line' || viz === 'area')
+        return 'TrendPanel';
+    if (viz === 'pivot')
+        return 'PivotTable';
+    if (viz === 'text' || viz === 'heading')
+        return /\btrust|evidence|caveat|quality\b/.test(text) ? 'TrustCallout' : 'NarrativePanel';
+    if (/\btop|bottom|rank|ranking|leader|leaderboard|scorer|player\b/.test(text))
+        return 'RankingPanel';
+    if (viz === 'bar' || viz === 'grouped_bar' || viz === 'stacked_bar' || viz === 'pie' || viz === 'donut')
+        return 'RankingPanel';
+    return 'EvidenceTable';
+}
+function allowedVisualizationsForComponent(component, primary) {
+    const base = new Set([primary]);
+    for (const viz of compatibleVisualizationsForComponent(component))
+        base.add(viz);
+    return Array.from(base);
+}
+function compatibleVisualizationsForComponent(component) {
+    if (component === 'KpiMetric') {
+        return ['single_value', 'kpi', 'gauge', 'table'];
+    }
+    if (component === 'TrendPanel')
+        return ['line', 'area', 'bar', 'table'];
+    if (component === 'RankingPanel')
+        return ['bar', 'grouped_bar', 'stacked_bar', 'pie', 'donut', 'table'];
+    if (component === 'PivotTable')
+        return ['pivot', 'table', 'bar'];
+    if (component === 'EvidenceTable')
+        return ['table', 'bar', 'scatter', 'heatmap', 'histogram', 'waterfall', 'map', 'funnel'];
+    return ['text', 'heading'];
+}
+function componentVizCompatible(component, viz) {
+    return compatibleVisualizationsForComponent(component).includes(viz);
+}
+function layoutIntentForComponent(component) {
+    if (component === 'KpiMetric' || component === 'TrustCallout' || component === 'ResearchActions')
+        return 'compact';
+    if (component === 'TrendPanel' || component === 'RankingPanel')
+        return 'wide';
+    if (component === 'PivotTable' || component === 'EvidenceTable')
+        return 'standard';
+    if (component === 'BusinessBrief')
+        return 'wide';
+    return 'standard';
+}
+function recommendationRationale(component, viz, block, columns, prompt) {
+    if (block) {
+        return `Recommended ${component} with ${viz} from the block display hint and result shape. The certified block remains the business logic source.`;
+    }
+    if (columns.length > 0) {
+        return `Recommended ${component} with ${viz} from ${columns.length} output column(s) and the app prompt. This is consumer-level metadata pending review.`;
+    }
+    return prompt
+        ? `Recommended ${component} with ${viz} from the app prompt. Review against previewed fields before sharing.`
+        : `Recommended ${component} with ${viz} as a safe table-first presentation fallback.`;
+}
 function appReadme(app, audience, blocks, dashboardId = 'overview') {
     return [
         `# ${app.name}`,
@@ -989,18 +1254,19 @@ function appReadme(app, audience, blocks, dashboardId = 'overview') {
     ].join('\n');
 }
 function collectBlockCandidates(projectRoot) {
-    const blocksDir = join(projectRoot, 'blocks');
     const blocks = [];
-    if (!existsSync(blocksDir))
-        return blocks;
+    const seen = new Set();
     const scanDir = (dir) => {
+        if (!existsSync(dir))
+            return;
         for (const entry of readdirSyncSafe(dir)) {
             const filePath = join(dir, entry.name);
             if (entry.isDirectory()) {
                 scanDir(filePath);
             }
-            else if (entry.isFile() && entry.name.endsWith('.dql')) {
+            else if (entry.isFile() && entry.name.endsWith('.dql') && !seen.has(filePath)) {
                 try {
+                    seen.add(filePath);
                     const source = readFileSync(filePath, 'utf-8');
                     const stat = statSyncSafe(filePath);
                     const name = matchString(source, /block\s+"([^"]+)"/) ?? entry.name.replace(/\.dql$/, '');
@@ -1012,7 +1278,7 @@ function collectBlockCandidates(projectRoot) {
                         status: matchString(source, /status\s*=\s*"([^"]+)"/) ?? 'draft',
                         owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
                         tags,
-                        path: filePath.slice(projectRoot.length + 1),
+                        path: relative(projectRoot, filePath).replaceAll('\\', '/'),
                         lastModified: stat?.mtime.toISOString() ?? new Date(0).toISOString(),
                         description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
                         llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
@@ -1027,7 +1293,8 @@ function collectBlockCandidates(projectRoot) {
             }
         }
     };
-    scanDir(blocksDir);
+    scanDir(join(projectRoot, 'blocks'));
+    scanDir(join(projectRoot, 'domains'));
     return blocks;
 }
 function readdirSyncSafe(dir) {
@@ -1902,6 +2169,14 @@ function slugify(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+function resolveAppPackageDir(projectRoot, domain, id) {
+    const domainSlug = slugify(domain);
+    const domainDir = domainSlug ? join(projectRoot, 'domains', domainSlug) : '';
+    if (domainDir && existsSync(domainDir)) {
+        return join(domainDir, 'apps', id);
+    }
+    return join(projectRoot, 'apps', id);
+}
 function titleFromPath(path) {
     return basename(path)
         .replace(/\.(dqlnb|dql)$/i, '')
@@ -1925,7 +2200,7 @@ function appAllowsExecute(app, domain) {
         return policy.accessLevel === 'execute' || policy.accessLevel === 'admin';
     });
 }
-function createDashboardForApp(projectRoot, appId, input) {
+export function createDashboardForApp(projectRoot, appId, input) {
     const loaded = loadAppById(projectRoot, appId);
     if (!loaded)
         return { ok: false, error: `App "${appId}" not found` };
@@ -1933,7 +2208,7 @@ function createDashboardForApp(projectRoot, appId, input) {
     const id = slugify(cleanString(input.id) || title) || `page-${Date.now()}`;
     if (!/^[a-z0-9][a-z0-9_-]*$/i.test(id))
         return { ok: false, error: 'dashboard id must be folder-safe' };
-    const appDir = join(projectRoot, 'apps', appId);
+    const appDir = loaded.appDir;
     const dashboardPath = join(appDir, 'dashboards', `${id}.dqld`);
     if (existsSync(dashboardPath))
         return { ok: false, error: `Dashboard already exists: ${id}` };
@@ -2010,11 +2285,13 @@ function createAiPinTile(projectRoot, appId, input) {
             evidence: input.evidence,
             followUps: Array.isArray(input.followUps) ? input.followUps.filter((item) => typeof item === 'string') : [],
         });
+        const vizType = normalizeVizTypeFromChart(input.chartConfig);
         const tile = {
             i: tileId,
             ...nextTilePosition(loaded.dashboard),
             aiPin: { id: pin.id },
-            viz: { type: normalizeVizTypeFromChart(input.chartConfig) },
+            viz: { type: vizType },
+            display: displayForAiPin(title, vizType, input),
             title,
         };
         const dashboard = {
@@ -2057,7 +2334,7 @@ function promoteAiPinToDraftBlock(projectRoot, appId, pinId) {
             analysisPlan?.dimensions?.length ? `Dimensions: ${analysisPlan.dimensions.join(', ')}` : '',
             analysisPlan?.measures?.length ? `Measures: ${analysisPlan.measures.join(', ')}` : '',
         ].filter(Boolean).join(' | ');
-        const draftDir = join(projectRoot, 'apps', appId, 'drafts');
+        const draftDir = join(loaded.appDir, 'drafts');
         const blockPath = join(draftDir, `${blockName}.dql`);
         mkdirSync(draftDir, { recursive: true });
         const source = [
@@ -2138,6 +2415,8 @@ function loadAppById(projectRoot, id) {
         }
         return {
             app: document,
+            appDir,
+            appPath: relative(projectRoot, appDir),
             dashboards,
             notebooks: listAppNotebookRefs(projectRoot, document, appDir),
             drafts: listAppDrafts(projectRoot, appDir),
@@ -2182,8 +2461,8 @@ export function createNotebookForApp(projectRoot, appId, input) {
         return { ok: false, error: `App "${appId}" not found` };
     const title = cleanString(input.title) || cleanString(input.name) || 'App analysis';
     const slug = slugify(cleanString(input.name) || title) || `notebook-${Date.now()}`;
-    const appDir = join(projectRoot, 'apps', appId);
-    const relPath = `apps/${appId}/notebooks/${slug}.dqlnb`;
+    const appDir = loaded.appDir;
+    const relPath = relative(projectRoot, join(appDir, 'notebooks', `${slug}.dqlnb`)).replaceAll('\\', '/');
     const absPath = join(projectRoot, relPath);
     if (existsSync(absPath))
         return { ok: false, error: `Notebook already exists: ${relPath}` };
@@ -2488,10 +2767,10 @@ function writeDashboard(projectRoot, appId, dashboardId, payload) {
         return { ok: false, error: `dashboard.id (${document.id}) does not match URL :did (${dashboardId})` };
     }
     // Confirm the App exists.
-    const appDir = join(projectRoot, 'apps', appId);
-    if (!existsSync(join(appDir, 'dql.app.json'))) {
-        return { ok: false, error: `App "${appId}" not found at ${appDir}` };
-    }
+    const loaded = loadAppById(projectRoot, appId);
+    if (!loaded)
+        return { ok: false, error: `App "${appId}" not found` };
+    const appDir = loaded.appDir;
     const dashboardPath = join(appDir, 'dashboards', `${dashboardId}.dqld`);
     mkdirSync(dirname(dashboardPath), { recursive: true });
     writeFileSync(dashboardPath, JSON.stringify(document, null, 2) + '\n', 'utf-8');