@shrkcrft/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/dashboard/code-intelligence-data.js

@@ -0,0 +1,329 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { runArchCheck } from '@shrkcrft/architecture-guard';
+import { FrameworkQueryApi } from '@shrkcrft/framework-scanners';
+import { detectGraphFreshness, GraphQueryApi, GraphStore } from '@shrkcrft/graph';
+import { findResumePoint, } from '@shrkcrft/migrate';
+import { QualityGateReportStore, runQualityGates } from '@shrkcrft/quality-gates';
+import { BridgeStore } from '@shrkcrft/rule-graph';
+/**
+ * Build the Code Intelligence overview response.
+ *
+ * Reads the three on-disk stores plus runs the architecture-guard
+ * check inline. Every section degrades to `available: false` with a
+ * `hint` when its backing store is missing — the dashboard renders
+ * those as "run `shrk graph index` to enable" cards rather than
+ * blocking the whole panel.
+ *
+ * Pure read — never builds or writes anything.
+ */
+export function buildDashboardCodeIntelligence(projectRoot) {
+    const commandHints = [
+        { label: 'Build code graph', command: 'shrk graph index', purpose: 'Refresh the persistent code-graph store.' },
+        { label: 'Build rule-graph bridge', command: 'shrk rule-graph index', purpose: 'Rebuild bridge edges from files to assets.' },
+        { label: 'Build framework index', command: 'shrk framework index', purpose: 'Detect framework entities (NestJS, React, etc.).' },
+        { label: 'Run architecture checks', command: 'shrk arch check', purpose: 'Surface public-API misuse, cycles, fat barrels.' },
+    ];
+    // Graph.
+    const graphStore = new GraphStore(projectRoot);
+    const graph = graphStore.exists()
+        ? readGraphSection(graphStore, projectRoot)
+        : { available: false, hint: "run 'shrk graph index'" };
+    // Bridge.
+    const bridgeStore = new BridgeStore(projectRoot);
+    const bridge = bridgeStore.exists()
+        ? readBridgeSection(bridgeStore)
+        : { available: false, hint: "run 'shrk rule-graph index'" };
+    // Framework.
+    const framework = FrameworkQueryApi.missingDescription(projectRoot)
+        ? { available: false, hint: "run 'shrk framework index'" }
+        : readFrameworkSection(projectRoot);
+    // Architecture (depends on graph store existing).
+    const architecture = graph.available
+        ? readArchSection(projectRoot)
+        : { available: false, errors: 0, warnings: 0, hint: 'graph index missing' };
+    return {
+        schema: 'sharkcraft.dashboard-code-intelligence/v1',
+        available: graph.available || bridge.available || framework.available,
+        graph,
+        bridge,
+        framework,
+        architecture,
+        commandHints,
+    };
+}
+/**
+ * Build the cross-framework routes panel response.
+ *
+ * Reads the framework store. For each entity with `subtype: 'route'`
+ * (or `api-route`), emits a row with `framework`, `method`, `path`,
+ * `handler`, and `file`. Sorted alphabetically by (framework, method,
+ * path).
+ */
+export function buildDashboardRoutes(projectRoot) {
+    const commandHints = [
+        { label: 'Build framework index', command: 'shrk framework index', purpose: 'Detect routes / components across frameworks.' },
+        { label: 'List a single framework', command: 'shrk framework list --framework <name>', purpose: 'Filter the entity list to one framework.' },
+    ];
+    const missing = FrameworkQueryApi.missingDescription(projectRoot);
+    if (missing) {
+        return {
+            schema: 'sharkcraft.dashboard-routes/v1',
+            available: false,
+            total: 0,
+            byFramework: {},
+            routes: [],
+            commandHints,
+            hint: missing,
+        };
+    }
+    const api = FrameworkQueryApi.fromStore(projectRoot);
+    const rows = [];
+    for (const entity of api.list({ subtype: 'route', limit: 5000 })) {
+        rows.push(toRow(entity));
+    }
+    for (const entity of api.list({ subtype: 'api-route', limit: 5000 })) {
+        rows.push(toRow(entity));
+    }
+    rows.sort((a, b) => a.framework.localeCompare(b.framework) ||
+        a.method.localeCompare(b.method) ||
+        a.path.localeCompare(b.path));
+    const byFramework = {};
+    for (const r of rows)
+        byFramework[r.framework] = (byFramework[r.framework] ?? 0) + 1;
+    return {
+        schema: 'sharkcraft.dashboard-routes/v1',
+        available: true,
+        total: rows.length,
+        byFramework,
+        routes: rows,
+        commandHints,
+    };
+}
+function readGraphSection(store, projectRoot) {
+    const snap = store.loadSnapshot();
+    const api = new GraphQueryApi(snap);
+    const hubs = api.topHubs(8);
+    const toRow = (h) => ({
+        id: h.node.id,
+        label: h.node.label,
+        ...(h.node.path ? { path: h.node.path } : {}),
+        inDegree: h.inDegree,
+    });
+    // Freshness vs the working tree — the same signal `shrk graph status` reports.
+    // `corrupt` (store self-integrity) outranks `stale` (disk drift): a digest
+    // failure means the counts themselves can't be trusted.
+    const fresh = detectGraphFreshness(projectRoot);
+    const behind = fresh.modified.length + fresh.added.length + fresh.deleted.length;
+    const verify = store.verifyDigest();
+    const state = !verify.ok ? 'corrupt' : behind > 0 ? 'stale' : 'fresh';
+    return {
+        available: true,
+        fileCount: snap.manifest.filesIndexed,
+        nodeCount: snap.nodes.size,
+        edgeCount: snap.edges.size,
+        workspacePackages: snap.manifest.workspacePackages.length,
+        lastIndexedAt: snap.manifest.lastIndexedAt,
+        nodesByKind: snap.manifest.nodesByKind,
+        edgesByKind: snap.manifest.edgesByKind,
+        freshness: {
+            state,
+            modified: fresh.modified.length,
+            added: fresh.added.length,
+            deleted: fresh.deleted.length,
+        },
+        hubs: { symbols: hubs.symbols.map(toRow), files: hubs.files.map(toRow) },
+    };
+}
+function readBridgeSection(store) {
+    const snap = store.loadSnapshot();
+    return {
+        available: true,
+        lastBuiltAt: snap.manifest.lastBuiltAt,
+        nodesByKind: snap.manifest.nodesByKind,
+        edgesByKind: snap.manifest.edgesByKind,
+        sourceCounts: snap.manifest.sourceCounts,
+    };
+}
+function readFrameworkSection(projectRoot) {
+    const api = FrameworkQueryApi.fromStore(projectRoot);
+    const manifest = api.manifest();
+    return {
+        available: true,
+        lastBuiltAt: manifest.lastBuiltAt,
+        frameworks: manifest.frameworks,
+        countsByFramework: manifest.countsByFramework,
+        countsBySubtype: manifest.countsBySubtype,
+    };
+}
+function readArchSection(projectRoot) {
+    // Honor an optional `sharkcraft/arch.ts` if present, but never load
+    // it dynamically inside the dashboard request path — keeping HTTP
+    // handlers synchronous and avoiding arbitrary code execution under
+    // the request. Default checks only.
+    const archPath = nodePath.join(projectRoot, 'sharkcraft', 'arch.ts');
+    void archPath;
+    const report = runArchCheck({ projectRoot });
+    return {
+        available: report.diagnostics.length === 0 || !report.diagnostics.some((d) => d.includes('code-graph store missing')),
+        errors: report.countsBySeverity.error,
+        warnings: report.countsBySeverity.warning,
+        violationsByKind: report.countsByKind,
+    };
+}
+function toRow(entity) {
+    const data = entity.data ?? {};
+    return {
+        framework: String(data['framework'] ?? '?'),
+        method: String(data['method'] ?? '?'),
+        path: String(data['path'] ?? data['routePath'] ?? '/'),
+        handler: String(data['handler'] ??
+            (data['className'] && data['handler']
+                ? `${data['className']}.${data['handler']}`
+                : data['name'] ?? '?')),
+        file: entity.path ?? '?',
+    };
+}
+/**
+ * Build the Migrations panel response.
+ *
+ * Reads every `.sharkcraft/migrations/*.state.json` (written by
+ * `@shrkcrft/migrate` after each step), shapes each into a dashboard
+ * row, and stamps `resumePoint` so the UI can highlight where a
+ * partially-failed migration would pick up.
+ */
+export function buildDashboardMigrations(projectRoot) {
+    const commandHints = [
+        {
+            label: 'Plan a migration',
+            command: 'shrk migrate plan <id>',
+            purpose: 'Preview the migration before any disk writes.',
+        },
+        {
+            label: 'Apply a migration',
+            command: 'shrk migrate apply <id>',
+            purpose: 'Execute the migration; checkpoints are written after every step.',
+        },
+        {
+            label: 'Resume a halted migration',
+            command: 'shrk migrate resume <id>',
+            purpose: 'Pick up at the failed step using the saved checkpoint.',
+        },
+    ];
+    const dir = nodePath.join(projectRoot, '.sharkcraft', 'migrations');
+    if (!existsSync(dir)) {
+        return {
+            schema: 'sharkcraft.dashboard-migrations/v1',
+            available: false,
+            total: 0,
+            migrations: [],
+            commandHints,
+            hint: 'no migrations have been run yet',
+        };
+    }
+    const rows = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.state.json'))
+            continue;
+        const abs = nodePath.join(dir, entry);
+        try {
+            const report = JSON.parse(readFileSync(abs, 'utf8'));
+            const resumePoint = findResumePoint(report);
+            rows.push({
+                id: report.migration.id,
+                title: report.migration.title,
+                overall: report.overall,
+                dryRun: report.dryRun,
+                startedAt: report.startedAt,
+                totalDurationMs: report.totalDurationMs,
+                steps: report.steps.map((s) => ({
+                    index: s.index,
+                    id: s.id,
+                    kind: s.kind,
+                    status: s.status,
+                    message: s.message,
+                    durationMs: s.durationMs,
+                })),
+                ...(resumePoint !== undefined ? { resumePoint } : {}),
+            });
+        }
+        catch {
+            /* corrupted state file — skip silently */
+        }
+    }
+    rows.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+    return {
+        schema: 'sharkcraft.dashboard-migrations/v1',
+        available: true,
+        total: rows.length,
+        migrations: rows,
+        commandHints,
+    };
+}
+/**
+ * Build the Quality-Gates panel response.
+ *
+ * Runs `runQualityGates` on request — the gate is cheap enough
+ * (<500 ms on a medium repo) that a fresh run beats stale data. The
+ * graph-fresh gate inside will surface "run `shrk graph index`" as a
+ * `nextCommand` when the store is missing, so the panel degrades
+ * gracefully.
+ */
+const QUALITY_GATE_REPORT_FRESH_MS = 5 * 60 * 1000;
+export function buildDashboardQualityGates(projectRoot) {
+    const commandHints = [
+        {
+            label: 'Run the gate locally',
+            command: 'shrk gate',
+            purpose: 'Same as the panel — writes a fresh .sharkcraft/quality-gates/last.json.',
+        },
+        {
+            label: 'Fail on warnings too',
+            command: 'shrk gate --strict',
+            purpose: 'Make `warn` exit 1 (useful for CI).',
+        },
+    ];
+    // Prefer a recent persisted report (written by `shrk gate`) over
+    // running every gate on every page load — the gate is cheap but the
+    // dashboard's polling loop is not.
+    const store = new QualityGateReportStore(projectRoot);
+    const saved = store.read();
+    const savedAge = store.ageMs();
+    const isFresh = saved !== undefined && savedAge !== undefined && savedAge <= QUALITY_GATE_REPORT_FRESH_MS;
+    const report = isFresh ? saved : runQualityGates({ projectRoot });
+    if (!isFresh) {
+        // Cache the freshly-computed report so subsequent dashboard
+        // requests reuse it.
+        try {
+            store.write(report);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    const gates = report.gates.map((g) => ({
+        id: g.id,
+        label: g.label,
+        status: g.status,
+        message: g.message,
+        durationMs: g.durationMs,
+        ...(g.nextCommands && g.nextCommands.length > 0 ? { nextCommands: g.nextCommands } : {}),
+    }));
+    return {
+        schema: 'sharkcraft.dashboard-quality-gates/v1',
+        overall: report.overall,
+        startedAt: report.startedAt,
+        totalDurationMs: report.totalDurationMs,
+        counts: report.counts,
+        gates,
+        commandHints,
+    };
+}
+void statSync;

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

@@ -1 +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"}
+{"version":3,"file":"dashboard-api-server.d.ts","sourceRoot":"","sources":["../../src/dashboard/dashboard-api-server.ts"],"names":[],"mappings":"AAuIA,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;AA2BD,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAqC1F;AA0lBD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

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

@@ -15,9 +15,71 @@ 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 { buildDashboardAdoption, buildDashboardArchitecture, buildDashboardBoundaries, buildDashboardCapabilities, buildDashboardCommands, buildDashboardCoverage, buildDashboardDoctor, buildDashboardDrift, buildDashboardGraph, buildDashboardGraphNode, buildDashboardGraphPath, buildDashboardHealth, buildDashboardKnowledgeList, buildDashboardKnowledgeEntry, buildDashboardKnowledgeGraph, buildDashboardKnowledgeSimilar, buildDashboardMcpSummary, buildDashboardOnboarding, buildDashboardOverview, buildDashboardPacks, buildDashboardPipelines, buildDashboardPresets, buildDashboardQuality, buildDashboardReports, buildDashboardReview, buildDashboardSafety, buildDashboardScaffolds, buildDashboardSchemas, buildDashboardSessionDetail, buildDashboardSessions, buildDashboardStats, inspectSharkcraft, renderDevSessionHtml, scanDevSession, } from '@shrkcrft/inspector';
+import { EContentType, compactArrayToColumnar, estimateTokens } from '@shrkcrft/compress';
 import { COMMAND_CATALOG } from "../commands/command-catalog.js";
+import { buildDashboardCodeIntelligence, buildDashboardMigrations, buildDashboardQualityGates, buildDashboardRoutes, } from "./code-intelligence-data.js";
+import { buildKnowledgeAsk } from "./knowledge-ask.js";
 const SCHEMA_ID = 'sharkcraft.dashboard-api/v1';
+/**
+ * Compute the deterministic compression layer's per-surface token savings for
+ * the dashboard. Measured on the live workspace (no timestamps → stable).
+ *
+ * `realTokens`, when supplied, is an exact BPE tokenizer (cl100k_base); the
+ * panel then reports exact counts and flags `tokensAreEstimated: false`. With
+ * no tokenizer (the default in a published install, where the dev-only
+ * `gpt-tokenizer` is absent) it falls back to the engine's estimator — whose
+ * *percentages* are sound but whose *absolutes* are rough — and flags
+ * `tokensAreEstimated: true` so the UI never presents an estimate as exact.
+ */
+function buildDashboardCompression(inspection, realTokens) {
+    const graph = buildDashboardKnowledgeGraph(inspection);
+    // Both encodings are JSON, so when estimating, score them with the JSON
+    // divisor — the same ratio the engine uses — for the closest absolute counts.
+    const count = (text) => realTokens ? realTokens(text) : estimateTokens(text, EContentType.Json);
+    const surfaces = [];
+    const add = (surface, strategy, beforeText, afterText) => {
+        const before = count(beforeText);
+        // Net-loss guard: columnar/legend overhead can exceed the raw encoding on
+        // tiny arrays. The engine ships whichever is smaller, so report what the
+        // agent actually pays — never a negative saving.
+        const after = Math.min(count(afterText), before);
+        surfaces.push({ surface, strategy, before, after, savedPct: before > 0 ? Math.round((1 - after / before) * 100) : 0 });
+    };
+    const nodes = [...graph.nodes];
+    const edges = [...graph.edges];
+    add('knowledge graph', 'columnar table', JSON.stringify({ nodes, edges }), JSON.stringify({ nodes: compactArrayToColumnar(nodes) ?? nodes, edges: compactArrayToColumnar(edges) ?? edges }));
+    add('knowledge nodes', 'columnar table', JSON.stringify(nodes), JSON.stringify(compactArrayToColumnar(nodes) ?? nodes));
+    const totalsBefore = surfaces.reduce((s, x) => s + x.before, 0);
+    const totalsAfter = surfaces.reduce((s, x) => s + x.after, 0);
+    return {
+        surfaces,
+        totals: {
+            before: totalsBefore,
+            after: totalsAfter,
+            savedPct: totalsBefore > 0 ? Math.round((1 - totalsAfter / totalsBefore) * 100) : 0,
+        },
+        tokensAreEstimated: !realTokens,
+    };
+}
+/**
+ * Best-effort load of the optional dev tokenizer for exact dashboard counts.
+ * Guarded dynamic import: `gpt-tokenizer` is not a runtime dependency of the
+ * CLI, so this resolves to `undefined` in any install that did not ship it, and
+ * the dashboard transparently falls back to the estimator.
+ */
+async function loadDashboardTokenizer() {
+    try {
+        const mod = (await import('gpt-tokenizer'));
+        if (typeof mod.encode !== 'function')
+            return undefined;
+        const encode = mod.encode;
+        return (text) => (text ? encode(text).length : 0);
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function startDashboardApiServer(opts) {
     const host = opts.host ?? '127.0.0.1';
     const port = opts.port ?? 0;
@@ -26,7 +88,7 @@ export async function startDashboardApiServer(opts) {
     }
     const startedAt = Date.now();
     const sessionHubs = new Map();
-    const ctx = { opts, startedAt, sessionHubs };
+    const ctx = { opts, startedAt, sessionHubs, globalHub: null };
     const server = http.createServer(async (req, res) => {
         try {
             await handle(req, res, ctx);
@@ -47,6 +109,10 @@ export async function startDashboardApiServer(opts) {
             for (const hub of sessionHubs.values())
                 closeHub(hub);
             sessionHubs.clear();
+            if (ctx.globalHub) {
+                closeGlobalHub(ctx.globalHub);
+                ctx.globalHub = null;
+            }
             server.close(() => resolve());
         }),
     };
@@ -115,6 +181,121 @@ function ensureSessionHub(ctx, sessionId) {
     ctx.sessionHubs.set(sessionId, hub);
     return hub;
 }
+/**
+ * Watched subdirectories under `.sharkcraft/` for the global hub.
+ * Order matters only for diagnostics — the event emitted is `change:<name>`.
+ *
+ *   - `graph/`: the code-graph store; fires after `shrk graph index`.
+ *   - `bridge/`: the rule-graph bridge.
+ *   - `framework/`: framework-scanner outputs.
+ *   - `migrations/`: migrate run state (one file per migration).
+ *   - `api-surface/`: api-surface-diff caches.
+ *   - `quality-gates/`: persisted gate reports.
+ */
+const GLOBAL_WATCH_DIRS = [
+    'graph',
+    'bridge',
+    'framework',
+    'migrations',
+    'api-surface',
+    'quality-gates',
+];
+function closeGlobalHub(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 ensureGlobalHub(ctx) {
+    if (ctx.globalHub)
+        return ctx.globalHub;
+    const hub = {
+        subscribers: new Set(),
+        watchers: [],
+        version: 0,
+        debounceTimer: null,
+        lastEvent: null,
+    };
+    const broadcast = (name) => {
+        if (hub.debounceTimer)
+            clearTimeout(hub.debounceTimer);
+        hub.debounceTimer = setTimeout(() => {
+            hub.version += 1;
+            hub.lastEvent = name;
+            const line = `event: change\ndata: ${name}\nid: ${hub.version}\n\n`;
+            for (const send of [...hub.subscribers]) {
+                try {
+                    send(line);
+                }
+                catch {
+                    hub.subscribers.delete(send);
+                }
+            }
+        }, 200);
+    };
+    for (const dir of GLOBAL_WATCH_DIRS) {
+        const target = nodePath.join(ctx.opts.cwd, '.sharkcraft', dir);
+        if (!fs.existsSync(target))
+            continue;
+        try {
+            const w = fs.watch(target, { recursive: true }, () => broadcast(dir));
+            hub.watchers.push(w);
+        }
+        catch {
+            try {
+                const w = fs.watch(target, () => broadcast(dir));
+                hub.watchers.push(w);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    ctx.globalHub = hub;
+    return hub;
+}
+function serveGlobalEvents(req, res, ctx) {
+    const hub = ensureGlobalHub(ctx);
+    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);
+    send(`event: hello\ndata: ${hub.lastEvent ?? 'ready'}\nid: ${hub.version}\n\n`);
+    const ping = setInterval(() => {
+        try {
+            res.write(`: ping\n\n`);
+        }
+        catch {
+            /* ignore */
+        }
+    }, 15000);
+    const close = () => {
+        clearInterval(ping);
+        hub.subscribers.delete(send);
+        if (hub.subscribers.size === 0) {
+            closeGlobalHub(hub);
+            ctx.globalHub = null;
+        }
+    };
+    req.on('close', close);
+    req.on('end', close);
+}
 async function handle(req, res, ctx) {
     if (req.method !== 'GET' && req.method !== 'HEAD') {
         res.setHeader('allow', 'GET, HEAD');
@@ -129,11 +310,21 @@ async function handle(req, res, ctx) {
     if (!path.startsWith('/api/') && opts.staticDir) {
         return serveStatic(res, opts.staticDir, path);
     }
+    // Non-API request with no static UI installed. Common when @shrkcrft/cli
+    // is consumed without @shrkcrft/dashboard present. Return a helpful page
+    // instead of falling through to the cryptic "Unknown route: /".
+    if (!path.startsWith('/api/') && !opts.staticDir) {
+        return serveNoUiHint(res, 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]));
     }
+    // Global live events (SSE). Subscribers refetch on every change.
+    if (path === '/api/events') {
+        return serveGlobalEvents(req, res, ctx);
+    }
     // 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,
@@ -172,6 +363,18 @@ async function handle(req, res, ctx) {
         });
         return respond(res, buildEnvelope(projectRoot, stats));
     }
+    if (path === '/api/code-intelligence') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCodeIntelligence(projectRoot)));
+    }
+    if (path === '/api/routes') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardRoutes(projectRoot)));
+    }
+    if (path === '/api/migrations') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardMigrations(projectRoot)));
+    }
+    if (path === '/api/quality-gates') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardQualityGates(projectRoot)));
+    }
     // For data routes that need inspection, load once per request.
     const needsInspection = path.startsWith('/api/overview') ||
         path.startsWith('/api/doctor') ||
@@ -182,8 +385,10 @@ async function handle(req, res, ctx) {
         path.startsWith('/api/pipelines') ||
         path.startsWith('/api/architecture') ||
         path.startsWith('/api/graph') ||
+        path.startsWith('/api/knowledge') ||
         path.startsWith('/api/onboarding') ||
         path.startsWith('/api/review') ||
+        path.startsWith('/api/compression') ||
         path.startsWith('/api/scaffolds');
     const inspection = needsInspection
         ? await inspectSharkcraft({ cwd: projectRoot })
@@ -203,6 +408,10 @@ async function handle(req, res, ctx) {
     if (path === '/api/packs') {
         return respond(res, buildEnvelope(projectRoot, buildDashboardPacks(inspection)));
     }
+    if (path === '/api/compression') {
+        const realTokens = await loadDashboardTokenizer();
+        return respond(res, buildEnvelope(projectRoot, buildDashboardCompression(inspection, realTokens)));
+    }
     if (path === '/api/presets') {
         return respond(res, buildEnvelope(projectRoot, buildDashboardPresets(inspection)));
     }
@@ -235,6 +444,32 @@ async function handle(req, res, ctx) {
             return respondError(res, 400, 'bad-request', 'from and to query params required');
         return respond(res, buildEnvelope(projectRoot, buildDashboardGraphPath(inspection, from, to)));
     }
+    // Knowledge explorer. Specific sub-paths (ask / graph / entry) are matched
+    // before the bare list route. The ask route synthesizes a grounded answer
+    // with the local LLM — still a read: it never writes, and is wall-clock
+    // bounded so it cannot hang the server.
+    if (path === '/api/knowledge/ask') {
+        const q = url.searchParams.get('q');
+        if (!q || !q.trim())
+            return respondError(res, 400, 'bad-request', 'q query param required');
+        return respond(res, buildEnvelope(projectRoot, await buildKnowledgeAsk(inspection, q)));
+    }
+    if (path === '/api/knowledge/graph') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeGraph(inspection)));
+    }
+    const knowledgeSimilarMatch = path.match(/^\/api\/knowledge\/similar\/(.+)$/);
+    if (knowledgeSimilarMatch) {
+        const id = decodeURIComponent(knowledgeSimilarMatch[1]);
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeSimilar(inspection, id)));
+    }
+    const knowledgeEntryMatch = path.match(/^\/api\/knowledge\/entry\/(.+)$/);
+    if (knowledgeEntryMatch) {
+        const id = decodeURIComponent(knowledgeEntryMatch[1]);
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeEntry(inspection, id)));
+    }
+    if (path === '/api/knowledge') {
+        return respond(res, buildEnvelope(projectRoot, buildDashboardKnowledgeList(inspection)));
+    }
     if (path === '/api/onboarding') {
         return respond(res, buildEnvelope(projectRoot, buildDashboardOnboarding(inspection)));
     }
@@ -369,6 +604,25 @@ function serveSessionReportHtml(res, cwd, sessionId) {
     }
     res.end(html);
 }
+function serveNoUiHint(res, urlPath) {
+    const accept = (res.req?.headers['accept'] ?? '');
+    const wantsHtml = accept.includes('text/html');
+    if (wantsHtml) {
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>SharkCraft dashboard — UI not installed</title><meta name="viewport" content="width=device-width,initial-scale=1"><style>body{font-family:ui-sans-serif,system-ui,-apple-system,sans-serif;max-width:680px;margin:48px auto;padding:0 16px;color:#1f2937;line-height:1.55}code,pre{background:#f3f4f6;padding:2px 6px;border-radius:4px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px}pre{padding:12px;overflow:auto}h1{font-size:20px;margin-top:0}a{color:#2563eb}</style></head><body><h1>SharkCraft dashboard</h1><p>The API is running, but the web UI bundle (<code>@shrkcrft/dashboard</code>) was not found next to <code>@shrkcrft/cli</code>.</p><p>Install or upgrade it alongside the CLI:</p><pre>npm i -D @shrkcrft/dashboard@alpha</pre><p>Or point the server at a local build:</p><pre>shrk dashboard --dev-assets path/to/dashboard/dist</pre><p>The API itself is available — try <a href="/api/health">/api/health</a> or <a href="/api/overview">/api/overview</a>.</p></body></html>`;
+        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');
+        if ((res.req?.method ?? 'GET') === 'HEAD') {
+            res.end();
+            return;
+        }
+        res.end(html);
+        return;
+    }
+    respondError(res, 404, 'not-found', `No UI assets installed; ${urlPath} cannot be served. Install @shrkcrft/dashboard or pass --dev-assets.`);
+}
 function serveStatic(res, staticDir, urlPath) {
     // Strip leading / and resolve against staticDir. Reject traversal.
     const rel = urlPath.replace(/^\/+/, '');

package/dist/dashboard/knowledge-ask.d.ts

@@ -0,0 +1,4 @@
+import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { IDashboardKnowledgeAskResponse } from '@shrkcrft/dashboard-api';
+export declare function buildKnowledgeAsk(inspection: ISharkcraftInspection, question: string): Promise<IDashboardKnowledgeAskResponse>;
+//# sourceMappingURL=knowledge-ask.d.ts.map

package/dist/dashboard/knowledge-ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-ask.d.ts","sourceRoot":"","sources":["../../src/dashboard/knowledge-ask.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,8BAA8B,EAE/B,MAAM,yBAAyB,CAAC;AAwCjC,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,qBAAqB,EACjC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,8BAA8B,CAAC,CA0EzC"}