@duckcodeailabs/dql-cli 1.4.4 → 1.5.1

package/{apps-api.js → dist/apps-api.js}

@@ -4,9 +4,9 @@
  * dispatcher — returns `true` if the request was handled, `false` otherwise.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { join, dirname } 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, personaFromMember, } from '@duckcodeailabs/dql-project';
+import { defaultPersonaRegistry, defaultLocalAppsDbPath, LocalAppStorage, personaFromMember, } from '@duckcodeailabs/dql-project';
 export async function handleAppsApi(ctx) {
     const { req, res, path, projectRoot } = ctx;
     // ── Apps ────────────────────────────────────────────────────────────────
@@ -40,8 +40,166 @@ export async function handleAppsApi(ctx) {
         }
         return true;
     }
+    let m = path.match(/^\/api\/apps\/([^/]+)\/editor\/catalog$/);
+    if (m && req.method === 'GET') {
+        const appId = decodeURIComponent(m[1]);
+        const app = loadAppById(projectRoot, appId)?.app;
+        if (!app) {
+            sendJson(res, 404, { error: `App "${appId}" not found` });
+            return true;
+        }
+        const domain = ctx.url.searchParams.get('domain') ?? app.domain;
+        const certifiedOnly = ctx.url.searchParams.get('certifiedOnly') !== 'false';
+        const blocks = collectBlockCandidates(projectRoot)
+            .filter((block) => !certifiedOnly || block.status === 'certified')
+            .filter((block) => !domain || block.domain === domain || appAllowsExecute(app, block.domain))
+            .sort((a, b) => {
+            const aDomain = a.domain === app.domain ? 0 : 1;
+            const bDomain = b.domain === app.domain ? 0 : 1;
+            return aDomain - bDomain || a.name.localeCompare(b.name);
+        });
+        sendJson(res, 200, {
+            appId,
+            defaultDomain: app.domain,
+            domains: unique(blocks.map((block) => block.domain)),
+            blocks,
+        });
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/dashboards$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        try {
+            const body = await readJson(req);
+            const result = createDashboardForApp(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$/);
+    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\/([^/]+)\/ai-pins$/);
+    if (m) {
+        const appId = decodeURIComponent(m[1]);
+        if (req.method === 'GET') {
+            const dashboardId = ctx.url.searchParams.get('dashboardId') ?? undefined;
+            const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+            try {
+                sendJson(res, 200, { pins: storage.listAiPins(appId, dashboardId) });
+            }
+            finally {
+                storage.close();
+            }
+            return true;
+        }
+        if (req.method === 'POST') {
+            try {
+                const body = await readJson(req);
+                const created = createAiPinTile(projectRoot, appId, body);
+                if (!created.ok) {
+                    sendJson(res, 400, { error: created.error });
+                    return true;
+                }
+                sendJson(res, 201, created);
+            }
+            catch (err) {
+                sendJson(res, 500, { error: err.message });
+            }
+            return true;
+        }
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/ai-pins\/([^/]+)\/refresh$/);
+    if (m && req.method === 'POST') {
+        const pinId = decodeURIComponent(m[2]);
+        const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+        try {
+            const pin = storage.getAiPin(pinId);
+            if (!pin) {
+                sendJson(res, 404, { error: `AI pin "${pinId}" not found` });
+                return true;
+            }
+            if (!pin.sql) {
+                const updated = storage.updateAiPinResult(pinId, pin.result, 'Pin has no SQL to refresh.');
+                sendJson(res, 400, { error: 'Pin has no SQL to refresh.', pin: updated });
+                return true;
+            }
+            if (!ctx.executeSql) {
+                const updated = storage.updateAiPinResult(pinId, pin.result, 'This host cannot execute AI pin SQL.');
+                sendJson(res, 400, { error: 'This host cannot execute AI pin SQL.', pin: updated });
+                return true;
+            }
+            const result = await ctx.executeSql(pin.sql);
+            const updated = storage.updateAiPinResult(pinId, result);
+            sendJson(res, 200, { ok: true, pin: updated });
+        }
+        catch (err) {
+            const pin = storage.updateAiPinResult(pinId, undefined, err instanceof Error ? err.message : String(err));
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err), pin });
+        }
+        finally {
+            storage.close();
+        }
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/ai-pins\/([^/]+)\/promote$/);
+    if (m && req.method === 'POST') {
+        const appId = decodeURIComponent(m[1]);
+        const pinId = decodeURIComponent(m[2]);
+        try {
+            const result = promoteAiPinToDraftBlock(projectRoot, appId, pinId);
+            if (!result.ok) {
+                sendJson(res, 400, { error: result.error });
+                return true;
+            }
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+        return true;
+    }
+    m = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)\/layout$/);
+    if (m && req.method === 'PATCH') {
+        const appId = decodeURIComponent(m[1]);
+        const dashboardId = decodeURIComponent(m[2]);
+        try {
+            const body = await readJson(req);
+            const result = patchDashboardLayout(projectRoot, appId, dashboardId, body);
+            if (!result.ok) {
+                sendJson(res, 400, { error: result.error });
+                return true;
+            }
+            sendJson(res, 200, result);
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+        return true;
+    }
     // /api/apps/:id  — single App with dashboards summary
-    let m = path.match(/^\/api\/apps\/([^/]+)$/);
+    m = path.match(/^\/api\/apps\/([^/]+)$/);
     if (m && req.method === 'GET') {
         const id = m[1];
         const result = loadAppById(projectRoot, id);
@@ -129,7 +287,6 @@ export async function handleAppsApi(ctx) {
     }
     return false;
 }
-// ---- Helpers ----
 function collectAppsList(projectRoot) {
     const out = [];
     for (const p of findAppDocuments(projectRoot)) {
@@ -147,9 +304,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',
+            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,
@@ -157,6 +320,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,
         });
     }
@@ -224,6 +390,12 @@ export function createAppPackage(projectRoot, input) {
         return { ok: false, error: `App already exists: ${id}` };
     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);
@@ -235,7 +407,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: [
@@ -283,6 +460,11 @@ export function createAppPackage(projectRoot, input) {
             title: `${name} Overview`,
             description: cleanString(input.purpose) || `Starter dashboard for ${name}`,
             domain,
+            subdomain: subdomain || undefined,
+            groups,
+            audience: audience || undefined,
+            visibility,
+            lifecycle,
             tags,
         },
         layout: {
@@ -374,10 +556,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')
@@ -393,9 +591,15 @@ function appReadme(app, audience, blocks) {
         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`,
+        `- Supporting notebooks: notebooks/`,
+        `- Draft blocks: drafts/`,
         '',
         '## Selected Certified Blocks',
         '',
@@ -486,18 +690,213 @@ function cleanString(value) {
 function normalizeTags(values) {
     return Array.from(new Set(values.map((value) => cleanString(value)).filter(Boolean)));
 }
+function unique(values) {
+    return Array.from(new Set(values.filter(Boolean))).sort((a, b) => a.localeCompare(b));
+}
 function slugify(value) {
     return value
         .toLowerCase()
         .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)
         return undefined;
     return tag.slice('audience:'.length).replace(/-/g, ' ');
 }
+function appAllowsExecute(app, domain) {
+    return (app.policies ?? []).some((policy) => {
+        if (policy.enabled === false)
+            return false;
+        if (policy.domain !== '*' && policy.domain !== domain)
+            return false;
+        return policy.accessLevel === 'execute' || policy.accessLevel === 'admin';
+    });
+}
+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()}`;
+    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 dashboardPath = join(appDir, 'dashboards', `${id}.dqld`);
+    if (existsSync(dashboardPath))
+        return { ok: false, error: `Dashboard already exists: ${id}` };
+    const dashboard = {
+        version: 1,
+        id,
+        metadata: {
+            title,
+            description: cleanString(input.description) || `${title} dashboard tab`,
+            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: {
+            kind: 'grid',
+            cols: 12,
+            rowHeight: 80,
+            items: [],
+        },
+    };
+    mkdirSync(dirname(dashboardPath), { recursive: true });
+    writeFileSync(dashboardPath, JSON.stringify(dashboard, null, 2) + '\n', 'utf-8');
+    return { ok: true, dashboard, path: relative(projectRoot, dashboardPath) };
+}
+function patchDashboardLayout(projectRoot, appId, dashboardId, input) {
+    const loaded = loadDashboardForApp(projectRoot, appId, dashboardId);
+    if (!loaded)
+        return { ok: false, error: `Dashboard "${dashboardId}" not found in app "${appId}"` };
+    const next = {
+        ...loaded.dashboard,
+        layout: input.layout
+            ? input.layout
+            : {
+                ...loaded.dashboard.layout,
+                items: input.items ?? loaded.dashboard.layout.items,
+            },
+    };
+    const written = writeDashboard(projectRoot, appId, dashboardId, next);
+    if (!written.ok)
+        return written;
+    return { ok: true, dashboard: next, path: relative(projectRoot, written.path) };
+}
+function createAiPinTile(projectRoot, appId, input) {
+    const dashboardId = cleanString(input.dashboardId);
+    if (!dashboardId)
+        return { ok: false, error: 'dashboardId is required' };
+    const loaded = loadDashboardForApp(projectRoot, appId, dashboardId);
+    if (!loaded)
+        return { ok: false, error: `Dashboard "${dashboardId}" not found in app "${appId}"` };
+    const title = cleanString(input.title) || 'AI result';
+    const tileId = cleanString(input.tileId) || nextTileId(loaded.dashboard, slugify(title) || 'ai-pin');
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        const pin = storage.createAiPin({
+            appId,
+            dashboardId,
+            tileId,
+            title,
+            answer: cleanString(input.answer) || title,
+            sql: cleanString(input.sql) || undefined,
+            sourceTier: cleanString(input.sourceTier) || undefined,
+            certification: input.certification === 'certified' ? 'certified' : 'ai_generated',
+            reviewStatus: input.reviewStatus,
+            refreshCadence: input.refreshCadence === 'daily' ? 'daily' : 'none',
+            chartConfig: input.chartConfig,
+            result: input.result,
+            citations: Array.isArray(input.citations) ? input.citations : [],
+        });
+        const tile = {
+            i: tileId,
+            ...nextTilePosition(loaded.dashboard),
+            aiPin: { id: pin.id },
+            viz: { type: normalizeVizTypeFromChart(input.chartConfig) },
+            title,
+        };
+        const dashboard = {
+            ...loaded.dashboard,
+            layout: {
+                ...loaded.dashboard.layout,
+                items: [...loaded.dashboard.layout.items, tile],
+            },
+        };
+        const written = writeDashboard(projectRoot, appId, dashboardId, dashboard);
+        if (!written.ok) {
+            return { ok: false, error: written.error };
+        }
+        return { ok: true, pin, dashboard, tile };
+    }
+    finally {
+        storage.close();
+    }
+}
+function promoteAiPinToDraftBlock(projectRoot, appId, pinId) {
+    const loaded = loadAppById(projectRoot, appId);
+    if (!loaded)
+        return { ok: false, error: `App "${appId}" not found` };
+    const storage = new LocalAppStorage(defaultLocalAppsDbPath(projectRoot));
+    try {
+        const pin = storage.getAiPin(pinId);
+        if (!pin)
+            return { ok: false, error: `AI pin "${pinId}" not found` };
+        if (!pin.sql)
+            return { ok: false, error: 'AI pin has no SQL to promote' };
+        const blockName = slugify(pin.title) || pin.id;
+        const draftDir = join(projectRoot, 'apps', appId, 'drafts');
+        const blockPath = join(draftDir, `${blockName}.dql`);
+        mkdirSync(draftDir, { recursive: true });
+        const source = [
+            `block "${blockName}" {`,
+            `  domain = "${escapeDqlString(loaded.app.domain)}"`,
+            '  type = "custom"',
+            '  status = "review"',
+            `  owner = "${escapeDqlString(loaded.app.owners[0] ?? `${process.env.USER ?? 'analyst'}@local`)}"`,
+            `  description = "${escapeDqlString(pin.answer.slice(0, 240))}"`,
+            '  tags = ["ai-generated", "needs-review"]',
+            '',
+            '  query = """',
+            pin.sql,
+            '  """',
+            '',
+            '  visualization {',
+            `    chart = "${escapeDqlString(String(pin.chartConfig?.chart ?? 'table'))}"`,
+            '  }',
+            '}',
+            '',
+        ].join('\n');
+        writeFileSync(blockPath, source, 'utf-8');
+        const updated = storage.markAiPinPromoted(pinId, relative(projectRoot, blockPath));
+        return { ok: true, pin: updated, blockPath: relative(projectRoot, blockPath) };
+    }
+    finally {
+        storage.close();
+    }
+}
+function nextTilePosition(dashboard) {
+    const maxY = dashboard.layout.items.reduce((value, item) => Math.max(value, item.y + item.h), 0);
+    return { x: 0, y: maxY, w: 6, h: 3 };
+}
+function nextTileId(dashboard, base) {
+    const used = new Set(dashboard.layout.items.map((item) => item.i));
+    if (!used.has(base))
+        return base;
+    for (let i = 2; i < 1000; i++) {
+        const candidate = `${base}-${i}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+    return `${base}-${Date.now()}`;
+}
+function normalizeVizTypeFromChart(chartConfig) {
+    const chart = String(chartConfig?.chart ?? '').toLowerCase().replace(/-/g, '_');
+    if (chart === 'single_value' || chart === 'kpi' || chart === 'line' || chart === 'bar' || chart === 'area'
+        || 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';
+}
+function escapeDqlString(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\r?\n/g, ' ');
+}
 function loadAppById(projectRoot, id) {
     for (const p of findAppDocuments(projectRoot)) {
         const { document } = loadAppDocument(p);
@@ -516,10 +915,115 @@ 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;
 }
+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 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;
@@ -539,7 +1043,7 @@ function loadDashboardForApp(projectRoot, appId, dashboardId) {
     }
     return null;
 }
-async function writeDashboard(projectRoot, appId, dashboardId, payload) {
+function writeDashboard(projectRoot, appId, dashboardId, payload) {
     // Validate against the dashboard schema before touching disk.
     const { document, errors } = parseDashboardDocument(JSON.stringify(payload), '<incoming>');
     if (!document) {