@duckcodeailabs/dql-cli 1.4.1 → 1.4.4

package/apps-api.d.ts

@@ -0,0 +1,77 @@
+/**
+ * HTTP handlers for `/api/apps`, `/api/apps/:id`, `/api/apps/:id/dashboards/:did`,
+ * `/api/persona`. Designed to be invoked from `local-runtime.ts`'s request
+ * dispatcher — returns `true` if the request was handled, `false` otherwise.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type AppDocument } from '@duckcodeailabs/dql-core';
+interface Ctx {
+    req: IncomingMessage;
+    res: ServerResponse;
+    url: URL;
+    path: string;
+    projectRoot: string;
+}
+export declare function handleAppsApi(ctx: Ctx): Promise<boolean>;
+declare function collectAppsList(projectRoot: string): Array<{
+    id: string;
+    name: string;
+    domain: string;
+    description?: string;
+    audience?: string;
+    status?: 'ready' | 'empty';
+    owners: string[];
+    tags: string[];
+    members: number;
+    roles: number;
+    policies: number;
+    schedules: number;
+    dashboards: Array<{
+        id: string;
+        title: string;
+    }>;
+    homepage?: AppDocument['homepage'];
+}>;
+interface AppRecommendationRequest {
+    domain?: string;
+    tags?: string[];
+    purpose?: string;
+    audience?: string;
+    certifiedOnly?: boolean;
+}
+interface AppCreateRequest {
+    name?: string;
+    domain?: string;
+    purpose?: string;
+    audience?: string;
+    tags?: string[];
+    owners?: string[];
+    selectedBlockIds?: string[];
+}
+interface BlockCandidate {
+    id: string;
+    name: string;
+    domain: string;
+    status: string;
+    owner: string | null;
+    tags: string[];
+    path: string;
+    lastModified: string;
+    description: string;
+    llmContext: string | null;
+    chartType?: string;
+    score: number;
+    reasons: string[];
+}
+export declare function recommendBlocks(projectRoot: string, input: AppRecommendationRequest): BlockCandidate[];
+export declare function createAppPackage(projectRoot: string, input: AppCreateRequest): {
+    ok: true;
+    app: ReturnType<typeof collectAppsList>[number];
+    paths: string[];
+    dashboardId: string;
+} | {
+    ok: false;
+    error: string;
+};
+export {};
+//# sourceMappingURL=apps-api.d.ts.map

package/apps-api.d.ts.map

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

package/apps-api.js

@@ -0,0 +1,612 @@
+/**
+ * HTTP handlers for `/api/apps`, `/api/apps/:id`, `/api/apps/:id/dashboards/:did`,
+ * `/api/persona`. Designed to be invoked from `local-runtime.ts`'s request
+ * 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 { loadAppDocument, findAppDocuments, loadDashboardDocument, findDashboardsForApp, parseAppDocument, parseDashboardDocument, suggestAppId, } from '@duckcodeailabs/dql-core';
+import { defaultPersonaRegistry, personaFromMember, } from '@duckcodeailabs/dql-project';
+export async function handleAppsApi(ctx) {
+    const { req, res, path, projectRoot } = ctx;
+    // ── Apps ────────────────────────────────────────────────────────────────
+    if (req.method === 'GET' && path === '/api/apps') {
+        const apps = collectAppsList(projectRoot);
+        sendJson(res, 200, { apps });
+        return true;
+    }
+    if (req.method === 'POST' && path === '/api/apps/recommend-blocks') {
+        try {
+            const body = await readJson(req);
+            sendJson(res, 200, { blocks: recommendBlocks(projectRoot, body) });
+        }
+        catch (err) {
+            sendJson(res, 500, { error: err.message });
+        }
+        return true;
+    }
+    if (req.method === 'POST' && path === '/api/apps') {
+        try {
+            const body = await readJson(req);
+            const result = createAppPackage(projectRoot, 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;
+    }
+    // /api/apps/:id  — single App with dashboards summary
+    let m = path.match(/^\/api\/apps\/([^/]+)$/);
+    if (m && req.method === 'GET') {
+        const id = m[1];
+        const result = loadAppById(projectRoot, id);
+        if (!result) {
+            sendJson(res, 404, { error: `App "${id}" not found` });
+            return true;
+        }
+        sendJson(res, 200, result);
+        return true;
+    }
+    // /api/apps/:id/dashboards
+    m = path.match(/^\/api\/apps\/([^/]+)\/dashboards$/);
+    if (m && req.method === 'GET') {
+        const id = m[1];
+        const dashboards = listDashboardsFor(projectRoot, id);
+        if (dashboards === null) {
+            sendJson(res, 404, { error: `App "${id}" not found` });
+            return true;
+        }
+        sendJson(res, 200, { dashboards });
+        return true;
+    }
+    // /api/apps/:id/dashboards/:did
+    m = path.match(/^\/api\/apps\/([^/]+)\/dashboards\/([^/]+)$/);
+    if (m) {
+        const id = m[1];
+        const did = m[2];
+        if (req.method === 'GET') {
+            const result = loadDashboardForApp(projectRoot, id, did);
+            if (!result) {
+                sendJson(res, 404, { error: `Dashboard "${did}" not found in app "${id}"` });
+                return true;
+            }
+            sendJson(res, 200, result);
+            return true;
+        }
+        if (req.method === 'PUT' || req.method === 'POST') {
+            try {
+                const body = await readJson(req);
+                const written = await writeDashboard(projectRoot, id, did, body);
+                if (!written.ok) {
+                    sendJson(res, 400, { error: written.error });
+                    return true;
+                }
+                sendJson(res, 200, { ok: true, path: written.path });
+            }
+            catch (err) {
+                sendJson(res, 500, { error: err.message });
+            }
+            return true;
+        }
+    }
+    // ── Persona ────────────────────────────────────────────────────────────
+    if (path === '/api/persona') {
+        if (req.method === 'GET') {
+            sendJson(res, 200, { persona: defaultPersonaRegistry.active });
+            return true;
+        }
+        if (req.method === 'DELETE') {
+            defaultPersonaRegistry.clear();
+            sendJson(res, 200, { persona: null });
+            return true;
+        }
+        if (req.method === 'POST') {
+            try {
+                const body = await readJson(req);
+                const userId = typeof body.userId === 'string' ? body.userId : null;
+                const appId = typeof body.appId === 'string' ? body.appId : null;
+                if (!userId) {
+                    sendJson(res, 400, { error: 'userId is required' });
+                    return true;
+                }
+                const persona = activatePersona(projectRoot, userId, appId);
+                if (!persona) {
+                    sendJson(res, 404, { error: 'No App member matches this userId' });
+                    return true;
+                }
+                sendJson(res, 200, { persona });
+            }
+            catch (err) {
+                sendJson(res, 500, { error: err.message });
+            }
+            return true;
+        }
+    }
+    return false;
+}
+// ---- Helpers ----
+function collectAppsList(projectRoot) {
+    const out = [];
+    for (const p of findAppDocuments(projectRoot)) {
+        const { document } = loadAppDocument(p);
+        if (!document)
+            continue;
+        const appDir = p.slice(0, -'/dql.app.json'.length);
+        const dashboards = [];
+        for (const d of findDashboardsForApp(appDir)) {
+            const { document: dd } = loadDashboardDocument(d);
+            if (dd)
+                dashboards.push({ id: dd.id, title: dd.metadata.title });
+        }
+        out.push({
+            id: document.id,
+            name: document.name,
+            domain: document.domain,
+            description: document.description,
+            audience: audienceFromTags(document.tags ?? []),
+            status: dashboards.length > 0 ? 'ready' : 'empty',
+            owners: document.owners,
+            tags: document.tags ?? [],
+            members: document.members.length,
+            roles: document.roles.length,
+            policies: document.policies.length,
+            schedules: (document.schedules ?? []).length,
+            dashboards,
+            homepage: document.homepage,
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function recommendBlocks(projectRoot, input) {
+    const domain = cleanString(input.domain).toLowerCase();
+    const tags = normalizeTags(input.tags ?? []);
+    const text = [input.purpose, input.audience, ...(input.tags ?? [])].map((v) => cleanString(v).toLowerCase()).filter(Boolean);
+    const certifiedOnly = input.certifiedOnly !== false;
+    const hasCriteria = Boolean(domain || tags.length > 0 || text.length > 0);
+    return collectBlockCandidates(projectRoot)
+        .map((block) => {
+        let score = 0;
+        let criteriaScore = 0;
+        const reasons = [];
+        if (domain && block.domain.toLowerCase() === domain) {
+            score += 100;
+            criteriaScore += 100;
+            reasons.push('domain match');
+        }
+        if (certifiedOnly && block.status !== 'certified')
+            return null;
+        if (block.status === 'certified') {
+            score += 30;
+            reasons.push('certified');
+        }
+        const overlap = block.tags.filter((tag) => tags.includes(tag.toLowerCase()));
+        if (overlap.length > 0) {
+            score += overlap.length * 12;
+            criteriaScore += overlap.length * 12;
+            reasons.push(`tag match: ${overlap.join(', ')}`);
+        }
+        const haystack = [block.name, block.description, block.owner ?? '', block.llmContext ?? '', ...block.tags]
+            .join(' ')
+            .toLowerCase();
+        const textHits = text.filter((term) => term && haystack.includes(term));
+        if (textHits.length > 0) {
+            score += textHits.length * 6;
+            criteriaScore += textHits.length * 6;
+            reasons.push('context match');
+        }
+        if (score === 0 && !domain && tags.length === 0 && !certifiedOnly)
+            score = 1;
+        if (hasCriteria && criteriaScore === 0)
+            return null;
+        if (score === 0)
+            return null;
+        return { ...block, score, reasons };
+    })
+        .filter((block) => Boolean(block))
+        .sort((a, b) => b.score - a.score || new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime())
+        .slice(0, 50);
+}
+export function createAppPackage(projectRoot, input) {
+    const name = cleanString(input.name);
+    const domain = cleanString(input.domain);
+    if (!name)
+        return { ok: false, error: 'name is required' };
+    if (!domain)
+        return { ok: false, error: 'domain is required' };
+    const id = suggestAppId(name);
+    const appDir = join(projectRoot, 'apps', id);
+    if (existsSync(appDir))
+        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 tags = normalizeTags([...(input.tags ?? []), audience ? `audience:${slugify(audience)}` : '']);
+    const selectedIds = Array.from(new Set((input.selectedBlockIds ?? []).map(cleanString).filter(Boolean)));
+    const blocks = collectBlockCandidates(projectRoot);
+    const selectedBlocks = selectedIds
+        .map((blockId) => blocks.find((block) => block.id === blockId || block.name === blockId))
+        .filter((block) => Boolean(block));
+    const app = {
+        version: 1,
+        id,
+        name,
+        description: cleanString(input.purpose) || `${name} consumption surface for ${domain}`,
+        domain,
+        owners: [owner],
+        tags,
+        members: [
+            { userId: owner, displayName: owner, roles: ['owner', 'analyst'] },
+        ],
+        roles: [
+            { id: 'owner', displayName: 'Owner', description: 'Full access to dashboards and App configuration.' },
+            { id: 'analyst', displayName: 'Analyst', description: 'Can execute dashboards and review generated drafts.' },
+            { id: 'viewer', displayName: 'Viewer', description: 'Read-only access to certified dashboard consumption.' },
+        ],
+        policies: [
+            {
+                id: 'viewers-read',
+                domain,
+                minClassification: 'internal',
+                allowedRoles: ['viewer', 'analyst', 'owner'],
+                accessLevel: 'read',
+                enabled: true,
+            },
+            {
+                id: 'analyst-execute',
+                domain,
+                minClassification: 'internal',
+                allowedRoles: ['analyst', 'owner'],
+                accessLevel: 'execute',
+                enabled: true,
+            },
+            {
+                id: 'owner-admin',
+                domain,
+                minClassification: 'restricted',
+                allowedRoles: ['owner'],
+                accessLevel: 'admin',
+                enabled: true,
+            },
+        ],
+        rlsBindings: [],
+        schedules: [],
+        homepage: { type: 'dashboard', id: 'overview' },
+    };
+    const dashboard = {
+        version: 1,
+        id: 'overview',
+        metadata: {
+            title: `${name} Overview`,
+            description: cleanString(input.purpose) || `Starter dashboard for ${name}`,
+            domain,
+            tags,
+        },
+        layout: {
+            kind: 'grid',
+            cols: 12,
+            rowHeight: 80,
+            items: buildDashboardItems(selectedBlocks),
+        },
+    };
+    const paths = [
+        join(appDir, 'dql.app.json'),
+        join(appDir, 'README.md'),
+        join(appDir, 'dashboards', 'overview.dqld'),
+        join(appDir, 'notebooks'),
+        join(appDir, 'drafts'),
+    ];
+    mkdirSync(join(appDir, 'dashboards'), { recursive: true });
+    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');
+    const created = collectAppsList(projectRoot).find((entry) => entry.id === id);
+    if (!created)
+        return { ok: false, error: `App was written but could not be reloaded: ${id}` };
+    return {
+        ok: true,
+        app: created,
+        paths: paths.map((path) => path.startsWith(projectRoot) ? path.slice(projectRoot.length + 1) : path),
+        dashboardId: 'overview',
+    };
+}
+function buildDashboardItems(blocks) {
+    let x = 0;
+    let y = 0;
+    let rowH = 0;
+    return [...blocks]
+        .sort((a, b) => vizRank(a.chartType) - vizRank(b.chartType))
+        .map((block, index) => {
+        const chartType = normalizeVizType(block.chartType);
+        const size = tileSize(chartType);
+        if (x + size.w > 12) {
+            x = 0;
+            y += rowH || size.h;
+            rowH = 0;
+        }
+        const item = dashboardItemForBlock(block, chartType, x, y, size, index);
+        x += size.w;
+        rowH = Math.max(rowH, size.h);
+        return item;
+    });
+}
+function dashboardItemForBlock(block, chartType, x, y, size, index) {
+    return {
+        i: slugify(block.name) || `tile-${index + 1}`,
+        x,
+        y,
+        w: size.w,
+        h: size.h,
+        block: { blockId: block.name },
+        viz: { type: chartType },
+        title: block.name,
+    };
+}
+function vizRank(chartType) {
+    const normalized = normalizeVizType(chartType);
+    if (normalized === 'single_value' || normalized === 'kpi')
+        return 0;
+    if (normalized === 'line' || normalized === 'area')
+        return 1;
+    if (normalized === 'bar' || normalized === 'pie' || normalized === 'funnel' || normalized === 'map')
+        return 2;
+    return 3;
+}
+function tileSize(chartType) {
+    if (chartType === 'single_value' || chartType === 'kpi')
+        return { w: 3, h: 2 };
+    if (chartType === 'table' || chartType === 'pivot')
+        return { w: 6, h: 4 };
+    return { w: 6, h: 3 };
+}
+function normalizeVizType(chartType) {
+    const normalized = (chartType ?? 'table').toLowerCase().replace(/-/g, '_');
+    if (normalized === 'single' || normalized === 'single_value')
+        return 'single_value';
+    if (normalized === 'kpi')
+        return 'kpi';
+    if (normalized === 'line')
+        return 'line';
+    if (normalized === 'bar')
+        return 'bar';
+    if (normalized === 'area')
+        return 'area';
+    if (normalized === 'pie')
+        return 'pie';
+    if (normalized === 'pivot')
+        return 'pivot';
+    if (normalized === 'map')
+        return 'map';
+    if (normalized === 'funnel')
+        return 'funnel';
+    return 'table';
+}
+function appReadme(app, audience, blocks) {
+    return [
+        `# ${app.name}`,
+        '',
+        app.description ?? '',
+        '',
+        `- Domain: ${app.domain}`,
+        `- Audience: ${audience || 'not specified'}`,
+        `- Owners: ${app.owners.join(', ')}`,
+        `- Starter dashboard: dashboards/overview.dqld`,
+        '',
+        '## Selected Certified Blocks',
+        '',
+        ...(blocks.length > 0
+            ? blocks.map((block) => `- ${block.name} (${block.domain}, ${block.status}) - ${block.path}`)
+            : ['No blocks selected yet. Add certified blocks from the Apps Command Center.']),
+        '',
+        '## Governance',
+        '',
+        'This OSS App uses local persona switching with owner, analyst, and viewer roles. Real authentication and SSO are intentionally outside OSS scope.',
+        '',
+    ].join('\n');
+}
+function collectBlockCandidates(projectRoot) {
+    const blocksDir = join(projectRoot, 'blocks');
+    const blocks = [];
+    if (!existsSync(blocksDir))
+        return blocks;
+    const scanDir = (dir) => {
+        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')) {
+                try {
+                    const source = readFileSync(filePath, 'utf-8');
+                    const stat = statSyncSafe(filePath);
+                    const name = matchString(source, /block\s+"([^"]+)"/) ?? entry.name.replace(/\.dql$/, '');
+                    const tags = matchArray(source, /tags\s*=\s*\[([^\]]*)\]/);
+                    blocks.push({
+                        id: name,
+                        name,
+                        domain: matchString(source, /domain\s*=\s*"([^"]+)"/) ?? 'uncategorized',
+                        status: matchString(source, /status\s*=\s*"([^"]+)"/) ?? 'draft',
+                        owner: matchString(source, /owner\s*=\s*"([^"]+)"/),
+                        tags,
+                        path: filePath.slice(projectRoot.length + 1),
+                        lastModified: stat?.mtime.toISOString() ?? new Date(0).toISOString(),
+                        description: matchString(source, /description\s*=\s*"((?:[^"\\]|\\.)*)"/) ?? '',
+                        llmContext: matchString(source, /llmContext\s*=\s*"((?:[^"\\]|\\.)*)"/),
+                        chartType: matchString(source, /chart\s*=\s*"([^"]+)"/) ?? matchString(source, /chart\.(\w+)\s*\(/) ?? undefined,
+                        score: 0,
+                        reasons: [],
+                    });
+                }
+                catch {
+                    // skip unreadable block
+                }
+            }
+        }
+    };
+    scanDir(blocksDir);
+    return blocks;
+}
+function readdirSyncSafe(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function statSyncSafe(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function matchString(source, regex) {
+    const match = regex.exec(source);
+    return match?.[1]?.replace(/\\"/g, '"').trim() || null;
+}
+function matchArray(source, regex) {
+    const match = regex.exec(source);
+    if (!match)
+        return [];
+    return match[1]
+        .split(',')
+        .map((item) => item.trim().replace(/^"|"$/g, ''))
+        .filter(Boolean);
+}
+function cleanString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function normalizeTags(values) {
+    return Array.from(new Set(values.map((value) => cleanString(value)).filter(Boolean)));
+}
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function audienceFromTags(tags) {
+    const tag = tags.find((value) => value.startsWith('audience:'));
+    if (!tag)
+        return undefined;
+    return tag.slice('audience:'.length).replace(/-/g, ' ');
+}
+function loadAppById(projectRoot, id) {
+    for (const p of findAppDocuments(projectRoot)) {
+        const { document } = loadAppDocument(p);
+        if (!document || document.id !== id)
+            continue;
+        const appDir = p.slice(0, -'/dql.app.json'.length);
+        const dashboards = [];
+        for (const d of findDashboardsForApp(appDir)) {
+            const { document: dd } = loadDashboardDocument(d);
+            if (dd) {
+                dashboards.push({
+                    id: dd.id,
+                    title: dd.metadata.title,
+                    description: dd.metadata.description,
+                    itemCount: dd.layout.items.length,
+                });
+            }
+        }
+        return { app: document, dashboards };
+    }
+    return null;
+}
+function listDashboardsFor(projectRoot, id) {
+    const result = loadAppById(projectRoot, id);
+    return result?.dashboards ?? null;
+}
+function loadDashboardForApp(projectRoot, appId, dashboardId) {
+    for (const p of findAppDocuments(projectRoot)) {
+        const { document } = loadAppDocument(p);
+        if (!document || document.id !== appId)
+            continue;
+        const appDir = p.slice(0, -'/dql.app.json'.length);
+        for (const d of findDashboardsForApp(appDir)) {
+            const { document: dd } = loadDashboardDocument(d);
+            if (dd && dd.id === dashboardId) {
+                return { app: document, dashboard: dd };
+            }
+        }
+    }
+    return null;
+}
+async function writeDashboard(projectRoot, appId, dashboardId, payload) {
+    // Validate against the dashboard schema before touching disk.
+    const { document, errors } = parseDashboardDocument(JSON.stringify(payload), '<incoming>');
+    if (!document) {
+        return { ok: false, error: errors.map((e) => e.message).join('; ') };
+    }
+    if (document.id !== dashboardId) {
+        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 dashboardPath = join(appDir, 'dashboards', `${dashboardId}.dqld`);
+    mkdirSync(dirname(dashboardPath), { recursive: true });
+    writeFileSync(dashboardPath, JSON.stringify(document, null, 2) + '\n', 'utf-8');
+    return { ok: true, path: dashboardPath };
+}
+function activatePersona(projectRoot, userId, appId) {
+    // If an App id is provided, scope the persona to it.
+    if (appId) {
+        for (const p of findAppDocuments(projectRoot)) {
+            const { document } = loadAppDocument(p);
+            if (!document || document.id !== appId)
+                continue;
+            return defaultPersonaRegistry.setFromApp(document, userId);
+        }
+        return null;
+    }
+    // Otherwise pick the first App that contains the user.
+    for (const p of findAppDocuments(projectRoot)) {
+        const { document } = loadAppDocument(p);
+        if (!document)
+            continue;
+        const member = document.members.find((m) => m.userId === userId);
+        if (member) {
+            const persona = personaFromMember(document, member);
+            defaultPersonaRegistry.set(persona);
+            return persona;
+        }
+    }
+    return null;
+}
+// ---- IO utilities ----
+function sendJson(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify(body));
+}
+async function readJson(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf-8');
+            if (!raw)
+                return resolve({});
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+// reference unused parseAppDocument/readFileSync to keep import stable for forward use
+void parseAppDocument;
+void readFileSync;
+//# sourceMappingURL=apps-api.js.map