@duckcodeailabs/dql-cli 1.5.0 → 1.5.2

package/dist/apps-api.js

@@ -4,7 +4,7 @@
  * dispatcher — returns `true` if the request was handled, `false` otherwise.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { join, dirname, relative } from 'node:path';
+import { join, dirname, relative, basename } from 'node:path';
 import { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboardsForApp, parseAppDocument, parseDashboardDocument, suggestAppId, } from '@duckcodeailabs/dql-core';
 import { defaultPersonaRegistry, defaultLocalAppsDbPath, LocalAppStorage, personaFromMember, } from '@duckcodeailabs/dql-project';
 export async function handleAppsApi(ctx) {
@@ -83,6 +83,163 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    m = path.match(/^\/api\/apps\/([^/]+)\/notebook-candidates$/);
+    if (m && req.method === 'GET') {
+        const appId = decodeURIComponent(m[1]);
+        const loaded = loadAppById(projectRoot, appId);
+        if (!loaded) {
+            sendJson(res, 404, { error: `App "${appId}" not found` });
+            return true;
+        }
+        sendJson(res, 200, { notebooks: listNotebookCandidates(projectRoot, loaded.app, join(projectRoot, 'apps', appId)) });
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/notebooks\/create$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = createNotebookForApp(projectRoot, appId, body);
+            if (!result.ok) {
+                sendJson(res, 400, { error: result.error });
+                return true;
+            }
+            sendJson(res, 201, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/notebooks\/preview$/);
+    if (m && req.method === 'GET') {
+        const appId = decodeURIComponent(m[1]);
+        const notebookPath = ctx.url.searchParams.get('path') ?? '';
+        const result = previewNotebookForApp(projectRoot, appId, notebookPath);
+        if (!result.ok) {
+            sendJson(res, result.status, { error: result.error });
+            return true;
+        }
+        sendJson(res, 200, result.preview);
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/notebooks\/run$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const notebookPath = cleanString(body.path);
+            if (!notebookPath) {
+                sendJson(res, 400, { error: 'path is required' });
+                return true;
+            }
+            if (!ctx.runNotebook) {
+                sendJson(res, 400, { error: 'Notebook run is unavailable in this host.' });
+                return true;
+            }
+            await ctx.runNotebook(appId, notebookPath);
+            const preview = previewNotebookForApp(projectRoot, appId, notebookPath);
+            if (!preview.ok) {
+                sendJson(res, preview.status, { error: preview.error });
+                return true;
+            }
+            sendJson(res, 200, { ok: true, preview: preview.preview });
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        }
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/notebooks$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = attachNotebookToApp(projectRoot, appId, body);
+            if (!result.ok) {
+                sendJson(res, 400, { error: result.error });
+                return true;
+            }
+            sendJson(res, 200, loadAppById(projectRoot, appId) ?? result);
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/conversations$/);
+    if (m) {
+        const appId = decodeURIComponent(m[1]);
+        if (!loadAppById(projectRoot, appId)) {
+            sendJson(res, 404, { error: `App "${appId}" not found` });
+            return true;
+        }
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            if (req.method === 'GET') {
+                sendJson(res, 200, { conversations: storage.listAppConversations(appId) });
+                return true;
+            }
+            if (req.method === 'POST') {
+                const body = await readJson(req);
+                const conversation = storage.createAppConversation({
+                    appId,
+                    title: body.title,
+                    dashboardId: body.dashboardId,
+                    notebookPath: body.notebookPath,
+                    messages: normalizeConversationMessages(body.messages),
+                });
+                sendJson(res, 201, { ok: true, conversation });
+                return true;
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+            return true;
+        }
+        finally {
+            storage.close();
+        }
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/conversations\/([^/]+)$/);
+    if (m) {
+        const appId = decodeURIComponent(m[1]);
+        const conversationId = decodeURIComponent(m[2]);
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            const conversation = storage.getAppConversation(conversationId);
+            if (!conversation || conversation.appId !== appId) {
+                sendJson(res, 404, { error: `Conversation "${conversationId}" not found` });
+                return true;
+            }
+            if (req.method === 'GET') {
+                sendJson(res, 200, { conversation });
+                return true;
+            }
+            if (req.method === 'PATCH') {
+                const body = await readJson(req);
+                const updated = storage.updateAppConversation(conversationId, {
+                    title: body.title,
+                    dashboardId: body.dashboardId,
+                    notebookPath: body.notebookPath,
+                    messages: body.messages ? normalizeConversationMessages(body.messages) : undefined,
+                });
+                sendJson(res, 200, { ok: true, conversation: updated });
+                return true;
+            }
+            if (req.method === 'DELETE') {
+                sendJson(res, 200, { ok: storage.deleteAppConversation(conversationId) });
+                return true;
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+            return true;
+        }
+        finally {
+            storage.close();
+        }
+    }
     m = path.match(/^\/api\/apps\/([^/]+)\/ai-pins$/);
     if (m) {
         const appId = decodeURIComponent(m[1]);
@@ -270,7 +427,6 @@ export async function handleAppsApi(ctx) {
     }
     return false;
 }
-// ---- Helpers ----
 function collectAppsList(projectRoot) {
     const out = [];
     for (const p of findAppDocuments(projectRoot)) {
@@ -288,10 +444,15 @@ function collectAppsList(projectRoot) {
             id: document.id,
             name: document.name,
             domain: document.domain,
+            subdomain: document.subdomain,
+            groups: document.groups ?? [],
             description: document.description,
-            audience: audienceFromTags(document.tags ?? []),
-            status: dashboards.length > 0 ? 'ready' : 'empty',
-            storage: 'shared',
+            audience: document.audience ?? audienceFromTags(document.tags ?? []),
+            lifecycle: document.lifecycle ?? 'draft',
+            certification: document.lifecycle === 'certified' ? 'certified' : 'uncertified',
+            status: document.lifecycle === 'review' ? 'review' : dashboards.length > 0 ? 'ready' : 'empty',
+            storage: document.visibility === 'private' ? 'mine' : document.visibility === 'template' ? 'template' : 'shared',
+            visibility: document.visibility ?? 'shared',
             owners: document.owners,
             tags: document.tags ?? [],
             members: document.members.length,
@@ -299,6 +460,9 @@ function collectAppsList(projectRoot) {
             policies: document.policies.length,
             schedules: (document.schedules ?? []).length,
             dashboards,
+            notebooks: listAppNotebookRefs(projectRoot, document, appDir),
+            drafts: listAppDrafts(projectRoot, appDir),
+            aiPins: countAiPins(projectRoot, document.id),
             homepage: document.homepage,
         });
     }
@@ -364,8 +528,16 @@ export function createAppPackage(projectRoot, input) {
     const appDir = join(projectRoot, 'apps', id);
     if (existsSync(appDir))
         return { ok: false, error: `App already exists: ${id}` };
+    const dashboardTitle = cleanString(input.dashboardTitle) || 'Overview';
+    const dashboardId = slugify(dashboardTitle) || 'overview';
     const owner = cleanString(input.owners?.[0]) || `${process.env.USER ?? 'owner'}@local`;
     const audience = cleanString(input.audience);
+    const subdomain = cleanString(input.subdomain);
+    const groups = normalizeTags(input.groups ?? []);
+    const visibility = input.visibility === 'private' || input.visibility === 'template' ? input.visibility : 'shared';
+    const lifecycle = input.lifecycle === 'certified' || input.lifecycle === 'review' || input.lifecycle === 'deprecated'
+        ? input.lifecycle
+        : 'draft';
     const tags = normalizeTags([...(input.tags ?? []), audience ? `audience:${slugify(audience)}` : '']);
     const selectedIds = Array.from(new Set((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean)));
     const blocks = collectBlockCandidates(projectRoot);
@@ -377,7 +549,12 @@ export function createAppPackage(projectRoot, input) {
         id,
         name,
         description: cleanString(input.purpose) || `${name} consumption surface for ${domain}`,
+        visibility,
         domain,
+        subdomain: subdomain || undefined,
+        groups,
+        audience: audience || undefined,
+        lifecycle,
         owners: [owner],
         tags,
         members: [
@@ -416,15 +593,20 @@ export function createAppPackage(projectRoot, input) {
         ],
         rlsBindings: [],
         schedules: [],
-        homepage: { type: 'dashboard', id: 'overview' },
+        homepage: { type: 'dashboard', id: dashboardId },
     };
     const dashboard = {
         version: 1,
-        id: 'overview',
+        id: dashboardId,
         metadata: {
-            title: `${name} Overview`,
+            title: dashboardTitle,
             description: cleanString(input.purpose) || `Starter dashboard for ${name}`,
             domain,
+            subdomain: subdomain || undefined,
+            groups,
+            audience: audience || undefined,
+            visibility,
+            lifecycle,
             tags,
         },
         layout: {
@@ -437,7 +619,7 @@ export function createAppPackage(projectRoot, input) {
     const paths = [
         join(appDir, 'dql.app.json'),
         join(appDir, 'README.md'),
-        join(appDir, 'dashboards', 'overview.dqld'),
+        join(appDir, 'dashboards', `${dashboardId}.dqld`),
         join(appDir, 'notebooks'),
         join(appDir, 'drafts'),
     ];
@@ -445,8 +627,8 @@ export function createAppPackage(projectRoot, input) {
     mkdirSync(join(appDir, 'notebooks'), { recursive: true });
     mkdirSync(join(appDir, 'drafts'), { recursive: true });
     writeFileSync(join(appDir, 'dql.app.json'), JSON.stringify(app, null, 2) + '\n', 'utf-8');
-    writeFileSync(join(appDir, 'dashboards', 'overview.dqld'), JSON.stringify(dashboard, null, 2) + '\n', 'utf-8');
-    writeFileSync(join(appDir, 'README.md'), appReadme(app, audience, selectedBlocks), 'utf-8');
+    writeFileSync(join(appDir, 'dashboards', `${dashboardId}.dqld`), JSON.stringify(dashboard, null, 2) + '\n', 'utf-8');
+    writeFileSync(join(appDir, 'README.md'), appReadme(app, audience, selectedBlocks, dashboardId), 'utf-8');
     const created = collectAppsList(projectRoot).find((entry) => entry.id === id);
     if (!created)
         return { ok: false, error: `App was written but could not be reloaded: ${id}` };
@@ -454,7 +636,7 @@ export function createAppPackage(projectRoot, input) {
         ok: true,
         app: created,
         paths: paths.map((path) => path.startsWith(projectRoot) ? path.slice(projectRoot.length + 1) : path),
-        dashboardId: 'overview',
+        dashboardId,
     };
 }
 function buildDashboardItems(blocks) {
@@ -516,10 +698,26 @@ function normalizeVizType(chartType) {
         return 'line';
     if (normalized === 'bar')
         return 'bar';
+    if (normalized === 'grouped_bar')
+        return 'grouped_bar';
+    if (normalized === 'stacked_bar')
+        return 'stacked_bar';
     if (normalized === 'area')
         return 'area';
     if (normalized === 'pie')
         return 'pie';
+    if (normalized === 'donut')
+        return 'donut';
+    if (normalized === 'scatter')
+        return 'scatter';
+    if (normalized === 'heatmap')
+        return 'heatmap';
+    if (normalized === 'histogram')
+        return 'histogram';
+    if (normalized === 'waterfall')
+        return 'waterfall';
+    if (normalized === 'gauge')
+        return 'gauge';
     if (normalized === 'pivot')
         return 'pivot';
     if (normalized === 'map')
@@ -528,16 +726,22 @@ function normalizeVizType(chartType) {
         return 'funnel';
     return 'table';
 }
-function appReadme(app, audience, blocks) {
+function appReadme(app, audience, blocks, dashboardId = 'overview') {
     return [
         `# ${app.name}`,
         '',
         app.description ?? '',
         '',
         `- Domain: ${app.domain}`,
+        ...(app.subdomain ? [`- Subdomain: ${app.subdomain}`] : []),
+        ...(app.groups?.length ? [`- Groups: ${app.groups.join(', ')}`] : []),
         `- Audience: ${audience || 'not specified'}`,
+        `- Visibility: ${app.visibility}`,
+        `- Lifecycle: ${app.lifecycle}`,
         `- Owners: ${app.owners.join(', ')}`,
-        `- Starter dashboard: dashboards/overview.dqld`,
+        `- Starter dashboard: dashboards/${dashboardId}.dqld`,
+        `- Supporting notebooks: notebooks/`,
+        `- Draft blocks: drafts/`,
         '',
         '## Selected Certified Blocks',
         '',
@@ -622,6 +826,17 @@ function matchArray(source, regex) {
         .map((item) => item.trim().replace(/^"|"$/g, ''))
         .filter(Boolean);
 }
+function normalizeConversationMessages(messages) {
+    return (messages ?? [])
+        .map((message) => ({
+        id: cleanString(message.id) || undefined,
+        role: message.role === 'assistant' ? 'assistant' : 'user',
+        content: cleanString(message.content),
+        events: Array.isArray(message.events) ? message.events : [],
+        createdAt: cleanString(message.createdAt) || undefined,
+    }))
+        .filter((message) => message.content.length > 0);
+}
 function cleanString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
@@ -637,6 +852,14 @@ function slugify(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
 }
+function titleFromPath(path) {
+    return basename(path)
+        .replace(/\.(dqlnb|dql)$/i, '')
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/\b\w/g, (char) => char.toUpperCase()) || path;
+}
 function audienceFromTags(tags) {
     const tag = tags.find((value) => value.startsWith('audience:'));
     if (!tag)
@@ -656,8 +879,8 @@ function createDashboardForApp(projectRoot, appId, input) {
     const loaded = loadAppById(projectRoot, appId);
     if (!loaded)
         return { ok: false, error: `App "${appId}" not found` };
-    const title = cleanString(input.title) || 'New tab';
-    const id = slugify(cleanString(input.id) || title) || `tab-${Date.now()}`;
+    const title = cleanString(input.title) || 'New page';
+    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);
@@ -669,8 +892,13 @@ function createDashboardForApp(projectRoot, appId, input) {
         id,
         metadata: {
             title,
-            description: cleanString(input.description) || `${title} dashboard tab`,
+            description: cleanString(input.description) || `${title} dashboard page`,
             domain: loaded.app.domain,
+            subdomain: loaded.app.subdomain,
+            groups: loaded.app.groups ?? [],
+            audience: loaded.app.audience,
+            visibility: loaded.app.visibility ?? 'shared',
+            lifecycle: loaded.app.lifecycle ?? 'draft',
             tags: loaded.app.tags ?? [],
         },
         layout: {
@@ -812,7 +1040,9 @@ function nextTileId(dashboard, base) {
 function normalizeVizTypeFromChart(chartConfig) {
     const chart = String(chartConfig?.chart ?? '').toLowerCase().replace(/-/g, '_');
     if (chart === 'single_value' || chart === 'kpi' || chart === 'line' || chart === 'bar' || chart === 'area'
-        || chart === 'pie' || chart === 'pivot' || chart === 'map' || chart === 'funnel') {
+        || chart === 'grouped_bar' || chart === 'stacked_bar' || chart === 'pie' || chart === 'donut'
+        || chart === 'scatter' || chart === 'heatmap' || chart === 'histogram' || chart === 'waterfall'
+        || chart === 'gauge' || chart === 'pivot' || chart === 'map' || chart === 'funnel') {
         return chart;
     }
     return 'table';
@@ -838,10 +1068,301 @@ function loadAppById(projectRoot, id) {
                 });
             }
         }
-        return { app: document, dashboards };
+        return {
+            app: document,
+            dashboards,
+            notebooks: listAppNotebookRefs(projectRoot, document, appDir),
+            drafts: listAppDrafts(projectRoot, appDir),
+            aiPins: listAiPins(projectRoot, document.id),
+        };
+    }
+    return null;
+}
+export function listNotebookCandidates(projectRoot, app, appDir) {
+    const attached = new Map(listAppNotebookRefs(projectRoot, app, appDir).map((notebook) => [notebook.path, notebook]));
+    const files = new Map();
+    for (const root of ['notebooks', 'workbooks', 'apps']) {
+        for (const file of scanFiles(join(projectRoot, root), '.dqlnb')) {
+            const rel = relative(projectRoot, file).replaceAll('\\', '/');
+            files.set(rel, file);
+        }
+    }
+    for (const notebook of attached.values()) {
+        const abs = join(projectRoot, notebook.path);
+        if (existsSync(abs))
+            files.set(notebook.path, abs);
+    }
+    return Array.from(files.entries())
+        .map(([path, abs]) => {
+        const ref = attached.get(path);
+        const stat = statSyncSafe(abs);
+        return {
+            path,
+            title: ref?.title ?? notebookTitleFromFile(abs) ?? titleFromPath(path),
+            attached: Boolean(ref),
+            role: ref?.role,
+            visibility: ref?.visibility,
+            lastModified: stat?.mtime.toISOString(),
+        };
+    })
+        .sort((a, b) => Number(b.attached) - Number(a.attached) || a.title.localeCompare(b.title));
+}
+export function createNotebookForApp(projectRoot, appId, input) {
+    const loaded = loadAppById(projectRoot, appId);
+    if (!loaded)
+        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 absPath = join(projectRoot, relPath);
+    if (existsSync(absPath))
+        return { ok: false, error: `Notebook already exists: ${relPath}` };
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, buildAppNotebookTemplate(title, loaded.app, input.template), 'utf-8');
+    const attached = attachNotebookToApp(projectRoot, appId, {
+        path: relPath,
+        title,
+        role: normalizeNotebookRole(input.role),
+        visibility: input.visibility,
+    });
+    if (!attached.ok)
+        return { ok: false, error: attached.error };
+    const preview = previewNotebookForApp(projectRoot, appId, relPath);
+    return {
+        ok: true,
+        path: relPath,
+        app: loadAppById(projectRoot, appId),
+        preview: preview.ok ? preview.preview : null,
+    };
+}
+export function previewNotebookForApp(projectRoot, appId, notebookPath) {
+    if (!loadAppById(projectRoot, appId))
+        return { ok: false, status: 404, error: `App "${appId}" not found` };
+    const rel = cleanString(notebookPath).replaceAll('\\', '/');
+    if (!rel || rel.startsWith('/') || rel.includes('..') || !rel.endsWith('.dqlnb')) {
+        return { ok: false, status: 400, error: 'notebook path must be a project-relative .dqlnb path' };
+    }
+    const abs = join(projectRoot, rel);
+    if (!existsSync(abs))
+        return { ok: false, status: 404, error: `Notebook not found: ${rel}` };
+    try {
+        const raw = readFileSync(abs, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const snapshot = readNotebookRunSnapshot(abs);
+        const snapshotByCell = new Map();
+        for (const entry of snapshot?.cells ?? []) {
+            if (entry && typeof entry === 'object' && typeof entry.cellId === 'string') {
+                snapshotByCell.set(String(entry.cellId), entry);
+            }
+        }
+        const cells = (parsed.cells ?? []).map((cell, index) => {
+            const id = typeof cell.id === 'string' ? cell.id : `cell-${index + 1}`;
+            const snap = snapshotByCell.get(id);
+            return {
+                id,
+                type: typeof cell.type === 'string' ? cell.type : 'sql',
+                name: typeof cell.name === 'string' ? cell.name : typeof cell.title === 'string' ? cell.title : undefined,
+                content: typeof cell.content === 'string' ? cell.content : typeof cell.source === 'string' ? cell.source : '',
+                upstream: typeof cell.upstream === 'string' ? cell.upstream : undefined,
+                chartConfig: cell.chartConfig ?? cell.config,
+                tableConfig: cell.tableConfig,
+                singleValueConfig: cell.singleValueConfig,
+                pivotConfig: cell.pivotConfig,
+                status: snap?.status ?? 'idle',
+                result: snap?.result,
+                error: snap?.error,
+                executionCount: snap?.executionCount,
+                executedAt: snap?.executedAt,
+            };
+        });
+        return {
+            ok: true,
+            preview: {
+                path: rel,
+                title: parsed.title ?? parsed.metadata?.title ?? titleFromPath(rel),
+                metadata: parsed.metadata ?? {},
+                cells,
+                snapshotFound: Boolean(snapshot),
+                capturedAt: typeof snapshot?.capturedAt === 'string' ? snapshot.capturedAt : undefined,
+            },
+        };
+    }
+    catch (err) {
+        return { ok: false, status: 400, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function attachNotebookToApp(projectRoot, appId, input) {
+    const notebookPath = cleanString(input.path).replaceAll('\\', '/');
+    if (!notebookPath)
+        return { ok: false, error: 'path is required' };
+    if (notebookPath.startsWith('/') || notebookPath.includes('..')) {
+        return { ok: false, error: 'notebook path must be project-relative' };
+    }
+    if (!existsSync(join(projectRoot, notebookPath))) {
+        return { ok: false, error: `Notebook not found: ${notebookPath}` };
+    }
+    for (const appJsonPath of findAppDocuments(projectRoot)) {
+        const { document } = loadAppDocument(appJsonPath);
+        if (!document || document.id !== appId)
+            continue;
+        const role = input.role === 'source' || input.role === 'analysis' ? input.role : 'supporting';
+        const visibility = input.visibility === 'private' || input.visibility === 'template' ? input.visibility : 'shared';
+        const next = {
+            ...document,
+            notebooks: [
+                ...(document.notebooks ?? []).filter((notebook) => notebook.path !== notebookPath),
+                {
+                    path: notebookPath,
+                    title: cleanString(input.title) || titleFromPath(notebookPath),
+                    role,
+                    visibility,
+                },
+            ],
+        };
+        const { document: validated, errors } = parseAppDocument(JSON.stringify(next), appJsonPath);
+        if (!validated)
+            return { ok: false, error: errors.map((e) => e.message).join('; ') };
+        writeFileSync(appJsonPath, JSON.stringify(validated, null, 2) + '\n', 'utf-8');
+        return { ok: true, path: relative(projectRoot, appJsonPath) };
+    }
+    return { ok: false, error: `App "${appId}" not found` };
+}
+function listAppNotebookRefs(projectRoot, app, appDir) {
+    const byPath = new Map();
+    for (const notebook of app.notebooks ?? []) {
+        byPath.set(notebook.path, {
+            path: notebook.path,
+            title: notebook.title,
+            role: notebook.role,
+            visibility: notebook.visibility ?? 'shared',
+        });
+    }
+    const notebooksDir = join(appDir, 'notebooks');
+    for (const file of scanFiles(notebooksDir, '.dqlnb')) {
+        const rel = relative(projectRoot, file).replaceAll('\\', '/');
+        if (byPath.has(rel))
+            continue;
+        byPath.set(rel, {
+            path: rel,
+            title: titleFromPath(rel),
+            role: 'supporting',
+            visibility: app.visibility ?? 'shared',
+        });
+    }
+    return Array.from(byPath.values()).sort((a, b) => (a.title ?? a.path).localeCompare(b.title ?? b.path));
+}
+function buildAppNotebookTemplate(title, app, template) {
+    const normalizedTemplate = cleanString(template) || 'blank';
+    const cellId = (base) => `${slugify(base) || 'cell'}_${Math.random().toString(36).slice(2, 8)}`;
+    const intro = [
+        `# ${title}`,
+        '',
+        `App: ${app.name}`,
+        `Domain: ${[app.domain, app.subdomain, ...(app.groups ?? [])].filter(Boolean).join(' / ')}`,
+        '',
+        'Use this notebook for analysis that supports the App dashboard pages.',
+    ].join('\n');
+    const cells = [
+        {
+            id: cellId('intro'),
+            type: 'markdown',
+            content: intro,
+        },
+        {
+            id: cellId('starter-sql'),
+            type: 'sql',
+            name: 'starter_query',
+            content: '-- Write supporting SQL for this App here\nSELECT 1 AS value;',
+        },
+    ];
+    if (normalizedTemplate === 'summary') {
+        cells.push({
+            id: cellId('summary'),
+            type: 'markdown',
+            content: '## Notes\n\nAdd observations, assumptions, and follow-up questions here.',
+        });
+    }
+    return JSON.stringify({
+        dqlnbVersion: 1,
+        version: 1,
+        title,
+        metadata: {
+            description: `Supporting notebook for ${app.name}`,
+            status: 'draft',
+            categories: [app.domain, app.subdomain, ...(app.groups ?? [])].filter(Boolean),
+            createdAt: new Date().toISOString(),
+            modifiedAt: new Date().toISOString(),
+        },
+        cells,
+    }, null, 2) + '\n';
+}
+function notebookTitleFromFile(absPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(absPath, 'utf-8'));
+        if (typeof parsed.title === 'string' && parsed.title.trim())
+            return parsed.title.trim();
+        if (typeof parsed.metadata?.title === 'string' && parsed.metadata.title.trim())
+            return parsed.metadata.title.trim();
+    }
+    catch {
+        // fall back to path-derived title
     }
     return null;
 }
+function readNotebookRunSnapshot(absNotebookPath) {
+    const snapshotPath = absNotebookPath.replace(/\.dqlnb$/i, '.run.json');
+    if (!existsSync(snapshotPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(snapshotPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function normalizeNotebookRole(value) {
+    return value === 'source' || value === 'analysis' ? value : 'supporting';
+}
+function listAppDrafts(projectRoot, appDir) {
+    return scanFiles(join(appDir, 'drafts'), '.dql').map((file) => {
+        const source = readFileSync(file, 'utf-8');
+        const path = relative(projectRoot, file).replaceAll('\\', '/');
+        return {
+            path,
+            name: matchString(source, /block\s+"([^"]+)"/) ?? titleFromPath(path),
+            reviewStatus: matchString(source, /status\s*=\s*"([^"]+)"/) ?? 'review',
+        };
+    }).sort((a, b) => a.name.localeCompare(b.name));
+}
+function scanFiles(root, extension) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const entry of readdirSyncSafe(root)) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory())
+            out.push(...scanFiles(full, extension));
+        else if (entry.isFile() && entry.name.endsWith(extension))
+            out.push(full);
+    }
+    return out.sort();
+}
+function countAiPins(projectRoot, appId) {
+    return listAiPins(projectRoot, appId).length;
+}
+function listAiPins(projectRoot, appId) {
+    const dbPath = defaultLocalAppsDbPath(projectRoot);
+    if (!existsSync(dbPath))
+        return [];
+    const storage = new LocalAppStorage(dbPath);
+    try {
+        return storage.listAiPins(appId);
+    }
+    finally {
+        storage.close();
+    }
+}
 function listDashboardsFor(projectRoot, id) {
     const result = loadAppById(projectRoot, id);
     return result?.dashboards ?? null;