@shrkcrft/cli 0.1.0-alpha.2

package/dist/commands/why.command.js

@@ -0,0 +1,119 @@
+/**
+ * `shrk why <file>` — closes the dangling promise from
+ * `ide.command.ts:112`. For any file path under the project root,
+ * surface:
+ *
+ *   - inferred package / layer
+ *   - path conventions whose canonical path matches
+ *   - rules whose scope / tags / appliesWhen overlap with the file's
+ *     path tokens (top-N by priority)
+ *   - boundary rules whose `from` glob matches the file (these dictate
+ *     what the file is allowed to import)
+ *   - knowledge entries that reference the file or its basename
+ *   - suggested next commands
+ *
+ * Read-only. Pure composition over the live inspection — no LLM,
+ * no shell, no writes.
+ *
+ * Symbol queries (`shrk why <symbol>`) intentionally route to
+ * `shrk knowledge search` instead of trying to ground a symbol
+ * without an AST pass. Honest about scope.
+ */
+import { buildWhyReport, inspectSharkcraft, } from '@shrkcrft/inspector';
+import { flagBool, flagNumber, resolveCwd, } from "../command-registry.js";
+import { asJson, header } from "../output/format-output.js";
+export const whyCommand = {
+    name: 'why',
+    description: 'Explain the constraints that apply to a file: package / layer, path conventions, rules, boundary rules, and related knowledge. Read-only. Pure composition — no LLM, no shell.',
+    usage: 'shrk why <file> [--limit 10] [--json]',
+    async run(args) {
+        const target = args.positional[0];
+        if (!target) {
+            process.stderr.write('Usage: shrk why <file>\n' +
+                '\nFor symbol queries, use:\n  $ shrk knowledge search "<symbol>"\n' +
+                '  $ shrk search "<symbol>"\n');
+            return 2;
+        }
+        const cwd = resolveCwd(args);
+        const inspection = await inspectSharkcraft({ cwd });
+        const limit = flagNumber(args, 'limit') ?? 10;
+        const report = buildWhyReport({
+            inspection,
+            projectRoot: cwd,
+            target,
+            limit,
+        });
+        if (flagBool(args, 'json')) {
+            process.stdout.write(asJson(report) + '\n');
+            return 0;
+        }
+        renderHuman(report);
+        return 0;
+    },
+};
+function renderHuman(report) {
+    process.stdout.write(header(`Why: ${report.target.relativePath}`));
+    process.stdout.write(`  kind:       ${report.target.kind}\n`);
+    if (report.inferredPackage) {
+        process.stdout.write(`  package:    ${report.inferredPackage}\n`);
+    }
+    if (report.inferredLayer) {
+        process.stdout.write(`  layer:      ${report.inferredLayer}\n`);
+    }
+    if (report.target.kind === 'missing') {
+        process.stdout.write(`\n  (file not on disk — results below are based on the input path string only)\n`);
+    }
+    if (report.pathConventions.length > 0) {
+        process.stdout.write('\nPath conventions:\n');
+        for (const p of report.pathConventions) {
+            process.stdout.write(`  ${p.id.padEnd(35)} ${p.title}\n`);
+            process.stdout.write(`    canonical: ${p.canonicalPath}\n`);
+            if (p.source)
+                process.stdout.write(`    source: ${p.source}\n`);
+        }
+    }
+    if (report.rules.length > 0) {
+        process.stdout.write('\nApplicable rules (top by priority):\n');
+        for (const r of report.rules) {
+            process.stdout.write(`  ${r.id.padEnd(40)} [${r.priority}] ${r.title}\n`);
+            process.stdout.write(`    ${r.reason}\n`);
+            if (r.source)
+                process.stdout.write(`    source: ${r.source}\n`);
+        }
+    }
+    if (report.boundaries.length > 0) {
+        process.stdout.write('\nBoundary rules (constrain imports from this file):\n');
+        for (const b of report.boundaries) {
+            const sev = b.severity ? `[${b.severity}]` : '';
+            process.stdout.write(`  ${b.id.padEnd(40)} ${sev} ${b.title}\n`);
+            if (b.forbiddenImports && b.forbiddenImports.length > 0) {
+                process.stdout.write(`    forbidden: ${b.forbiddenImports.slice(0, 5).join(', ')}\n`);
+            }
+            if (b.allowedImports && b.allowedImports.length > 0) {
+                process.stdout.write(`    allowed:   ${b.allowedImports.slice(0, 5).join(', ')}\n`);
+            }
+            if (b.source)
+                process.stdout.write(`    source: ${b.source}\n`);
+        }
+    }
+    if (report.knowledge.length > 0) {
+        process.stdout.write('\nRelated knowledge:\n');
+        for (const k of report.knowledge) {
+            process.stdout.write(`  ${k.id.padEnd(35)} (${k.type}) ${k.title}\n`);
+            process.stdout.write(`    ${k.reason}\n`);
+        }
+    }
+    if (report.suggestedNext.length > 0) {
+        process.stdout.write('\nSuggested next:\n');
+        for (const cmd of report.suggestedNext) {
+            process.stdout.write(`  $ ${cmd}\n`);
+        }
+    }
+    if (report.pathConventions.length === 0 &&
+        report.rules.length === 0 &&
+        report.boundaries.length === 0 &&
+        report.knowledge.length === 0) {
+        process.stdout.write('\n(no registry entries matched. The file may be outside the conventions ' +
+            'or the workspace may not have rules / paths defined yet.)\n');
+    }
+}

package/dist/dashboard/dashboard-api-server.d.ts

@@ -0,0 +1,21 @@
+interface IServerOptions {
+    cwd: string;
+    host?: string;
+    port?: number;
+    /** Optional MCP tool list (passed in to avoid a CLI → MCP dependency). */
+    mcpTools?: ReadonlyArray<{
+        name: string;
+        description?: string;
+    }>;
+    /** Directory containing built dashboard static assets. When absent, /<non-api> returns 404. */
+    staticDir?: string | null;
+}
+interface IServerHandle {
+    url: string;
+    host: string;
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function startDashboardApiServer(opts: IServerOptions): Promise<IServerHandle>;
+export type { IServerHandle, IServerOptions };
+//# sourceMappingURL=dashboard-api-server.d.ts.map

package/dist/dashboard/dashboard-api-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-api-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/dashboard-api-server.ts"],"names":[],"mappings":"AAsDA,UAAU,cAAc;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,aAAa;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAcD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAiC1F;AA4ZD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

package/dist/dashboard/dashboard-api-server.js

@@ -0,0 +1,410 @@
+/**
+ * Read-only local dashboard API server.
+ *
+ * Safety contract (must hold forever):
+ *  - only GET and HEAD are allowed; everything else returns 405
+ *  - no source writes — server reads inspection state and serves JSON
+ *  - no apply / shell / onboard-write endpoints
+ *  - binds 127.0.0.1 by default; a non-localhost host emits a loud warning
+ *  - /api/health.readOnly === true
+ *
+ * This module is structured so the future `shrk dashboard --serve` command
+ * and the in-process tests share the same handler.
+ */
+import * as http from 'node:http';
+import * as fs from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildDashboardAdoption, buildDashboardArchitecture, buildDashboardBoundaries, buildDashboardCapabilities, buildDashboardCommands, buildDashboardCoverage, buildDashboardDoctor, buildDashboardDrift, buildDashboardGraph, buildDashboardGraphNode, buildDashboardGraphPath, buildDashboardHealth, buildDashboardMcpSummary, buildDashboardOnboarding, buildDashboardOverview, buildDashboardPacks, buildDashboardPipelines, buildDashboardPresets, buildDashboardQuality, buildDashboardReports, buildDashboardReview, buildDashboardSafety, buildDashboardScaffolds, buildDashboardSchemas, buildDashboardSessionDetail, buildDashboardSessions, buildDashboardStats, inspectSharkcraft, renderDevSessionHtml, scanDevSession, } from '@shrkcrft/inspector';
+import { COMMAND_CATALOG } from "../commands/command-catalog.js";
+const SCHEMA_ID = 'sharkcraft.dashboard-api/v1';
+export async function startDashboardApiServer(opts) {
+    const host = opts.host ?? '127.0.0.1';
+    const port = opts.port ?? 0;
+    if (host !== '127.0.0.1' && host !== 'localhost' && host !== '::1') {
+        process.stderr.write(`WARNING: --host ${host} exposes the dashboard API server beyond localhost. Press Ctrl+C to abort if unintended.\n`);
+    }
+    const startedAt = Date.now();
+    const sessionHubs = new Map();
+    const ctx = { opts, startedAt, sessionHubs };
+    const server = http.createServer(async (req, res) => {
+        try {
+            await handle(req, res, ctx);
+        }
+        catch (err) {
+            respondError(res, 500, 'internal', err.message);
+        }
+    });
+    await new Promise((resolve) => server.listen(port, host, () => resolve()));
+    const addr = server.address();
+    const realPort = typeof addr === 'object' && addr ? addr.port : port;
+    return {
+        url: `http://${host}:${realPort}`,
+        host,
+        port: realPort,
+        close: () => new Promise((resolve) => {
+            // Tear down every active SSE hub first.
+            for (const hub of sessionHubs.values())
+                closeHub(hub);
+            sessionHubs.clear();
+            server.close(() => resolve());
+        }),
+    };
+}
+function closeHub(hub) {
+    if (hub.debounceTimer) {
+        clearTimeout(hub.debounceTimer);
+        hub.debounceTimer = null;
+    }
+    for (const w of hub.watchers) {
+        try {
+            w.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    hub.watchers = [];
+    hub.subscribers.clear();
+}
+function ensureSessionHub(ctx, sessionId) {
+    const existing = ctx.sessionHubs.get(sessionId);
+    if (existing)
+        return existing;
+    const hub = {
+        subscribers: new Set(),
+        watchers: [],
+        version: 0,
+        debounceTimer: null,
+    };
+    const sessionDir = nodePath.join(ctx.opts.cwd, '.sharkcraft', 'sessions', sessionId);
+    const scheduleBroadcast = (event) => {
+        if (hub.debounceTimer)
+            clearTimeout(hub.debounceTimer);
+        hub.debounceTimer = setTimeout(() => {
+            hub.version += 1;
+            const line = `event: change\ndata: ${event}\nid: ${hub.version}\n\n`;
+            for (const send of [...hub.subscribers]) {
+                try {
+                    send(line);
+                }
+                catch {
+                    hub.subscribers.delete(send);
+                }
+            }
+        }, 200);
+    };
+    for (const sub of ['session.json', 'plans', 'reports']) {
+        const target = nodePath.join(sessionDir, sub);
+        if (!fs.existsSync(target))
+            continue;
+        try {
+            const w = fs.watch(target, { recursive: true }, () => scheduleBroadcast(sub));
+            hub.watchers.push(w);
+        }
+        catch {
+            try {
+                const w = fs.watch(target, () => scheduleBroadcast(sub));
+                hub.watchers.push(w);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    ctx.sessionHubs.set(sessionId, hub);
+    return hub;
+}
+async function handle(req, res, ctx) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.setHeader('allow', 'GET, HEAD');
+        return respondError(res, 405, 'method-not-allowed', `Method ${req.method} not allowed`);
+    }
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+    const opts = ctx.opts;
+    const startedAt = ctx.startedAt;
+    const projectRoot = opts.cwd;
+    // Static assets — only when not /api/*. SPA fallback to index.html.
+    if (!path.startsWith('/api/') && opts.staticDir) {
+        return serveStatic(res, opts.staticDir, path);
+    }
+    // Session live events (SSE). Subscribe via EventSource on the session detail page.
+    const sseMatch = path.match(/^\/api\/sessions\/([^/]+)\/events$/);
+    if (sseMatch) {
+        return serveSessionEvents(req, res, ctx, decodeURIComponent(sseMatch[1]));
+    }
+    // Rendered HTML report for the session (or any report on disk under the
+    // session dir). Served with a content-security-policy that disallows
+    // anything but inline styles — the report renderer never emits scripts,
+    // but iframe sandboxing in the UI is the second line of defence.
+    const reportMatch = path.match(/^\/api\/sessions\/([^/]+)\/report\.html$/);
+    if (reportMatch) {
+        return serveSessionReportHtml(res, ctx.opts.cwd, decodeURIComponent(reportMatch[1]));
+    }
+    if (path === '/api/health') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardHealth(Math.floor((Date.now() - startedAt) / 1000))));
+    }
+    if (path === '/api/capabilities') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCapabilities()));
+    }
+    if (path === '/api/commands') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCommands(COMMAND_CATALOG)));
+    }
+    if (path === '/api/schemas') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardSchemas()));
+    }
+    if (path === '/api/mcp') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardMcpSummary(opts.mcpTools ?? [])));
+    }
+    if (path === '/api/reports') {
+        const inspection = await inspectSharkcraft({ cwd: projectRoot });
+        return respond(res, buildEnvelope(projectRoot, buildDashboardReports(inspection)));
+    }
+    if (path === '/api/stats') {
+        const urlObj = new URL(req.url ?? '/', `http://${opts.host ?? '127.0.0.1'}`);
+        const topStr = urlObj.searchParams.get('top');
+        const language = urlObj.searchParams.get('language') ?? undefined;
+        const maxTopFiles = topStr !== null ? Math.max(0, Number(topStr) || 0) : undefined;
+        const stats = await buildDashboardStats(projectRoot, {
+            ...(maxTopFiles !== undefined ? { maxTopFiles } : {}),
+            ...(language ? { language } : {}),
+        });
+        return respond(res, buildEnvelope(projectRoot, stats));
+    }
+    // For data routes that need inspection, load once per request.
+    const needsInspection = path.startsWith('/api/overview') ||
+        path.startsWith('/api/doctor') ||
+        path.startsWith('/api/quality') ||
+        path.startsWith('/api/safety') ||
+        path.startsWith('/api/packs') ||
+        path.startsWith('/api/presets') ||
+        path.startsWith('/api/pipelines') ||
+        path.startsWith('/api/architecture') ||
+        path.startsWith('/api/graph') ||
+        path.startsWith('/api/onboarding') ||
+        path.startsWith('/api/review') ||
+        path.startsWith('/api/scaffolds');
+    const inspection = needsInspection
+        ? await inspectSharkcraft({ cwd: projectRoot })
+        : null;
+    if (path === '/api/overview') {
+        return respond(res, buildEnvelope(projectRoot, await buildDashboardOverview(inspection)));
+    }
+    if (path === '/api/doctor') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardDoctor(inspection)));
+    }
+    if (path === '/api/quality') {
+        return respond(res, buildEnvelope(projectRoot, await buildDashboardQuality(inspection)));
+    }
+    if (path === '/api/safety') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardSafety(inspection, COMMAND_CATALOG, (opts.mcpTools ?? []).map((t) => ({ name: t.name, description: t.description ?? '' })))));
+    }
+    if (path === '/api/packs') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardPacks(inspection)));
+    }
+    if (path === '/api/presets') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardPresets(inspection)));
+    }
+    if (path === '/api/pipelines') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardPipelines(inspection)));
+    }
+    if (path === '/api/architecture') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardArchitecture(inspection)));
+    }
+    if (path === '/api/architecture/boundaries') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardBoundaries(inspection)));
+    }
+    if (path === '/api/architecture/drift') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardDrift(inspection)));
+    }
+    if (path === '/api/architecture/coverage') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCoverage(inspection)));
+    }
+    if (path === '/api/graph') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardGraph(inspection)));
+    }
+    const nodeMatch = path.match(/^\/api\/graph\/node\/(.+)$/);
+    if (nodeMatch) {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardGraphNode(inspection, decodeURIComponent(nodeMatch[1]))));
+    }
+    if (path === '/api/graph/why') {
+        const from = url.searchParams.get('from');
+        const to = url.searchParams.get('to');
+        if (!from || !to)
+            return respondError(res, 400, 'bad-request', 'from and to query params required');
+        return respond(res, buildEnvelope(projectRoot, buildDashboardGraphPath(inspection, from, to)));
+    }
+    if (path === '/api/onboarding') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardOnboarding(inspection)));
+    }
+    if (path === '/api/onboarding/adoption') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardAdoption(inspection)));
+    }
+    if (path === '/api/scaffolds') {
+        return respond(res, buildEnvelope(projectRoot, await buildDashboardScaffolds(inspection)));
+    }
+    if (path === '/api/review') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardReview(inspection, { packetPath: url.searchParams.get('packet') ?? undefined })));
+    }
+    if (path === '/api/sessions') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardSessions(projectRoot)));
+    }
+    const sessionMatch = path.match(/^\/api\/sessions\/([^/]+)(\/report)?$/);
+    if (sessionMatch) {
+        const id = decodeURIComponent(sessionMatch[1]);
+        const detail = buildDashboardSessionDetail(projectRoot, id);
+        if (!detail.available)
+            return respondError(res, 404, 'not-found', `Unknown session: ${id}`);
+        return respond(res, buildEnvelope(projectRoot, detail));
+    }
+    return respondError(res, 404, 'not-found', `Unknown route: ${path}`);
+}
+function buildEnvelope(projectRoot, data) {
+    return {
+        schema: SCHEMA_ID,
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        data,
+    };
+}
+function respond(res, payload) {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.setHeader('x-content-type-options', 'nosniff');
+    res.setHeader('referrer-policy', 'no-referrer');
+    res.setHeader('x-sharkcraft-dashboard-api', '1');
+    if ((res.req?.method ?? 'GET') === 'HEAD') {
+        res.end();
+        return;
+    }
+    res.end(JSON.stringify(payload));
+}
+function respondError(res, status, code, message) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.end(JSON.stringify({
+        schema: SCHEMA_ID,
+        generatedAt: new Date().toISOString(),
+        data: { error: message, code },
+    }));
+}
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2',
+    '.woff': 'font/woff',
+    '.map': 'application/json; charset=utf-8',
+};
+function serveSessionEvents(req, res, ctx, sessionId) {
+    // Confirm the session exists before subscribing watchers.
+    const load = scanDevSession(ctx.opts.cwd, sessionId);
+    if (!load) {
+        return respondError(res, 404, 'not-found', `Unknown session: ${sessionId}`);
+    }
+    const hub = ensureSessionHub(ctx, sessionId);
+    res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-store',
+        'x-content-type-options': 'nosniff',
+        connection: 'keep-alive',
+    });
+    const send = (line) => {
+        res.write(line);
+    };
+    hub.subscribers.add(send);
+    // Initial hello so the client knows the stream is open.
+    send(`event: hello\ndata: ${sessionId}\nid: ${hub.version}\n\n`);
+    // Keep-alive comment ping so proxies don't close the connection.
+    const ping = setInterval(() => {
+        try {
+            res.write(`: ping\n\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }, 15000);
+    const close = () => {
+        clearInterval(ping);
+        hub.subscribers.delete(send);
+        // If we're the last subscriber, tear the hub down so file watchers
+        // don't outlive their clients.
+        if (hub.subscribers.size === 0) {
+            closeHub(hub);
+            ctx.sessionHubs.delete(sessionId);
+        }
+    };
+    req.on('close', close);
+    req.on('end', close);
+}
+function serveSessionReportHtml(res, cwd, sessionId) {
+    const load = scanDevSession(cwd, sessionId);
+    if (!load) {
+        return respondError(res, 404, 'not-found', `Unknown session: ${sessionId}`);
+    }
+    const html = renderDevSessionHtml(load, {
+        nextActionLine: load.state?.nextAction ?? undefined,
+    });
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/html; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.setHeader('x-content-type-options', 'nosniff');
+    res.setHeader('referrer-policy', 'no-referrer');
+    // Belt-and-braces: even though the renderer never emits scripts and the
+    // dashboard wraps this in a sandboxed iframe, a CSP keeps any future
+    // mishap from running JS.
+    res.setHeader('content-security-policy', "default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'");
+    if ((res.req?.method ?? 'GET') === 'HEAD') {
+        res.end();
+        return;
+    }
+    res.end(html);
+}
+function serveStatic(res, staticDir, urlPath) {
+    // Strip leading / and resolve against staticDir. Reject traversal.
+    const rel = urlPath.replace(/^\/+/, '');
+    const abs = nodePath.resolve(staticDir, rel);
+    if (!abs.startsWith(nodePath.resolve(staticDir))) {
+        return respondError(res, 400, 'bad-request', 'invalid path');
+    }
+    let target = abs;
+    try {
+        const st = statSync(target);
+        if (st.isDirectory())
+            target = nodePath.join(target, 'index.html');
+    }
+    catch {
+        // Not found — SPA fallback to index.html for client-side routing.
+        target = nodePath.join(staticDir, 'index.html');
+    }
+    if (!existsSync(target)) {
+        return respondError(res, 404, 'not-found', 'asset not found');
+    }
+    const ext = nodePath.extname(target).toLowerCase();
+    const mime = MIME[ext] ?? 'application/octet-stream';
+    const body = readFileSync(target);
+    res.statusCode = 200;
+    res.setHeader('content-type', mime);
+    res.setHeader('x-content-type-options', 'nosniff');
+    res.setHeader('referrer-policy', 'no-referrer');
+    if (ext === '.html') {
+        res.setHeader('cache-control', 'no-store');
+    }
+    else {
+        res.setHeader('cache-control', 'public, max-age=3600');
+    }
+    if ((res.req?.method ?? 'GET') === 'HEAD') {
+        res.end();
+        return;
+    }
+    res.end(body);
+}

package/dist/dashboard/live-session-server.d.ts

@@ -0,0 +1,18 @@
+import { type IDevSessionLoad } from '@shrkcrft/inspector';
+export interface ILiveSessionServerOptions {
+    cwd: string;
+    load: IDevSessionLoad;
+    host?: string;
+    port?: number;
+    live?: boolean;
+}
+export interface ILiveSessionServerHandle {
+    url: string;
+    host: string;
+    port: number;
+    /** Force-broadcast a synthetic SSE event (used by tests). */
+    triggerEvent: (event: string) => void;
+    close: () => Promise<void>;
+}
+export declare function startLiveSessionServer(opts: ILiveSessionServerOptions): Promise<ILiveSessionServerHandle>;
+//# sourceMappingURL=live-session-server.d.ts.map

package/dist/dashboard/live-session-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-session-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/live-session-server.ts"],"names":[],"mappings":"AAUA,OAAO,EAAwC,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEjG,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,eAAe,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAID,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,yBAAyB,GAC9B,OAAO,CAAC,wBAAwB,CAAC,CAwHnC"}