pi-mega-compact 0.8.21 → 0.8.23

package/dist/extensions/dashboard-server/routes-core.js

@@ -0,0 +1,62 @@
+/**
+ * dashboard-server/routes-core.ts — RouteContext interface + shared helpers.
+ *
+ * The core module defines the shared context interface and the factory that
+ * builds it. Route handler files import from here; the barrel (routes.ts)
+ * re-exports everything for server.ts.
+ */
+import { readSnapshot } from "./snapshot.js";
+// ---------------------------------------------------------------------------
+// Helper: overlayCurrentRepo
+// ---------------------------------------------------------------------------
+function makeOverlayCurrentRepo(snapshotPath, stateDir) {
+    return (idx) => {
+        if (!idx || !idx.repos.length)
+            return;
+        let snap = null;
+        try {
+            snap = readSnapshot(snapshotPath);
+        }
+        catch {
+            return;
+        }
+        if (!snap || !snap.repo)
+            return;
+        const cur = idx.repos.find((r) => r.stateDir === stateDir);
+        if (!cur)
+            return;
+        const prevSaved = cur.tokensSaved;
+        const prevCp = cur.checkpointCount;
+        const prevBytes = cur.compressedOriginalBytes;
+        const comp = snap.compression?.repo;
+        const liveSaved = comp
+            ? comp.tokensFreed
+            : (snap.repo.tokensSaved ?? prevSaved);
+        const liveCp = snap.repo.checkpointCount ?? prevCp;
+        const liveBytes = snap.integrity?.compressedOriginalBytes ?? prevBytes;
+        cur.tokensSaved = liveSaved;
+        cur.checkpointCount = liveCp;
+        cur.compressedOriginalBytes = liveBytes;
+        if (idx.summary) {
+            idx.summary.totalTokensSaved += liveSaved - prevSaved;
+            idx.summary.totalCheckpoints += liveCp - prevCp;
+            idx.summary.totalCompressedOriginalBytes += liveBytes - prevBytes;
+        }
+        idx.updatedAt = snap.updatedAt ?? idx.updatedAt;
+    };
+}
+// ---------------------------------------------------------------------------
+// Factory — builds a fully-populated RouteContext for server.ts to use.
+// ---------------------------------------------------------------------------
+export function buildRouteContext(opts) {
+    return {
+        snapshotPath: opts.snapshotPath,
+        eventsPath: opts.eventsPath,
+        stateDir: opts.stateDir,
+        SERVER_VERSION: opts.SERVER_VERSION,
+        serveClientAsset: opts.serveClientAsset,
+        eventOffsetRef: { value: 0 },
+        overlayCurrentRepo: makeOverlayCurrentRepo(opts.snapshotPath, opts.stateDir),
+        detectCrossRepoDrift: opts.detectCrossRepoDrift,
+    };
+}

package/dist/extensions/dashboard-server/routes-game.js

@@ -0,0 +1,323 @@
+/**
+ * dashboard-server/routes-game.ts — Game-mode and performance route handlers.
+ */
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+// ---------------------------------------------------------------------------
+// handleGameState — "/api/game-state" (GET + PUT)
+// ---------------------------------------------------------------------------
+export function handleGameState(req, res, ctx) {
+    if (!req.url?.startsWith("/api/game-state"))
+        return false;
+    const { stateDir } = ctx;
+    // /api/game-state — S32 game-mode settings (game_mode_on / theme /
+    // tui_display_mode). GET returns the current row; PUT applies a partial
+    // patch (validated) and returns the post-write row. The dashboard server is
+    // a detached child with no MegaRuntime ref, so it reads/writes the
+    // game_state SQLite row directly; the in-process MegaRuntime picks up the
+    // change via its fs.watch cache-eviction watcher. PREVENT-PI-004: loopback.
+    const gsReq = createRequire(import.meta.url);
+    const { getGameState, setGameState } = gsReq("../../src/store/sqlite.js");
+    const { isValidTheme } = gsReq("../../src/config/themes.js");
+    if (req.method === "GET") {
+        try {
+            const gs = getGameState(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(gs));
+        }
+        catch (e) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "game_state_unavailable",
+                detail: String(e),
+            }));
+        }
+        return true;
+    }
+    if (req.method === "PUT") {
+        // Read + parse the JSON body (capped — the patch is tiny). The handler
+        // is sync, so drain the stream via data/end listeners then continue.
+        let body = "";
+        let tooBig = false;
+        req.on("data", (chunk) => {
+            // guardrails-allow PREVENT-PI-004: loopback dashboard request body (local)
+            if (body.length > 65536) {
+                tooBig = true;
+                return;
+            }
+            body += chunk.toString();
+        });
+        req.on("end", () => {
+            if (tooBig) {
+                res.writeHead(413, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "body_too_large" }));
+                return;
+            }
+            let patch = {};
+            try {
+                patch = body ? JSON.parse(body) : {};
+            }
+            catch {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "invalid_json" }));
+                return;
+            }
+            // Reject valid-but-non-object JSON (null/[]/42) — dereferencing
+            // patch.game_mode_on would throw an unhandled TypeError inside this
+            // 'end' listener and crash the detached server (audit P1: loopback DoS).
+            if (typeof patch !== "object" ||
+                patch === null ||
+                Array.isArray(patch)) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "invalid_patch_object" }));
+                return;
+            }
+            // Validate the patch fields (unknown keys ignored; invalid values -> 400).
+            const clean = {};
+            let bad = false;
+            if (patch.game_mode_on != null) {
+                if (typeof patch.game_mode_on !== "boolean")
+                    bad = true;
+                else
+                    clean.game_mode_on = patch.game_mode_on;
+            }
+            if (patch.theme != null) {
+                if (typeof patch.theme !== "string" || !isValidTheme(patch.theme))
+                    bad = true;
+                else
+                    clean.theme = patch.theme;
+            }
+            if (patch.tui_display_mode != null) {
+                if (patch.tui_display_mode !== "full" &&
+                    patch.tui_display_mode !== "minimal")
+                    bad = true;
+                else
+                    clean.tui_display_mode = patch.tui_display_mode;
+            }
+            if (bad) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "invalid_patch" }));
+                return;
+            }
+            try {
+                const gs = setGameState(clean, stateDir); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback dashboard)
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify(gs));
+            }
+            catch (e) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    error: "game_state_write_failed",
+                    detail: String(e),
+                }));
+            }
+        });
+        return true;
+    }
+    // Any other method on /api/game-state -> 405.
+    res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+    res.end(JSON.stringify({ error: "method_not_allowed" }));
+    return true;
+}
+// ---------------------------------------------------------------------------
+// handleGameScores — "/api/game-scores"
+// ---------------------------------------------------------------------------
+export function handleGameScores(req, res, ctx) {
+    if (!req.url?.startsWith("/api/game-scores"))
+        return false;
+    const { stateDir } = ctx;
+    // /api/game-scores — S34 high-score leaderboards. GET returns the leaderboard
+    // for a metric (?metric=<m>&limit=<n>). `metric` is validated against the
+    // METRICS allow-list from src/game/scoring (re-exported via the sqlite barrel);
+    // default limit 10, clamped to [1,100]. The dashboard server is a detached
+    // child with no MegaRuntime ref, so it reads the game_scores SQLite table
+    // directly. Unknown metric -> 400, non-GET -> 405. PREVENT-PI-004: loopback.
+    const gsReq = createRequire(import.meta.url);
+    const { leaderboard, METRICS } = gsReq("../../src/store/sqlite.js");
+    if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.end(JSON.stringify({ error: "method_not_allowed" }));
+        return true;
+    }
+    try {
+        const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
+        const metricParam = url.searchParams.get("metric") ?? "cache";
+        if (!METRICS.includes(metricParam)) {
+            res.writeHead(400, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+            res.end(JSON.stringify({ error: "unknown_metric", metric: metricParam }));
+            return true;
+        }
+        const metric = metricParam; // validated against METRICS above
+        let limit = Number(url.searchParams.get("limit") ?? "10");
+        if (!Number.isFinite(limit) || limit <= 0)
+            limit = 10;
+        limit = Math.min(Math.max(limit, 1), 100); // clamp to [1,100]
+        const rows = leaderboard(stateDir, metric, { limit }); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(rows));
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            error: "game_scores_unavailable",
+            detail: String(e),
+        }));
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// handlePerf — "/api/perf"
+// ---------------------------------------------------------------------------
+export function handlePerf(req, res, ctx) {
+    if (!req.url?.startsWith("/api/perf"))
+        return false;
+    const { stateDir, snapshotPath } = ctx;
+    // /api/perf — v0.8.8 Perf dashboard tab. GET returns rolling-window
+    // aggregates over perf_samples: per-kind p50/p95 (turn/provider latency,
+    // tps avg, db recompute, disk write), latest rss/heap, cpu user/sys delta,
+    // cache hit %, plus the diag recompute/skip/replay counts (read from
+    // dashboard.json snapshot if available). The dashboard server is a detached
+    // child with no MegaRuntime ref, so it reads perf_samples via a require()'d
+    // sqlite helper (same pattern as /api/game-scores). Unknown/invalid params
+    // are clamped (never throw). Non-GET -> 405. PREVENT-PI-004: loopback.
+    const pfReq = createRequire(import.meta.url);
+    const { readPerfSamples } = pfReq("../../src/store/sqlite.js");
+    if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.end(JSON.stringify({ error: "method_not_allowed" }));
+        return true;
+    }
+    try {
+        const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
+        let minutes = Number(url.searchParams.get("minutes") ?? "30");
+        if (!Number.isFinite(minutes) || minutes <= 0)
+            minutes = 30;
+        minutes = Math.min(minutes, 1440); // cap at 24h
+        const sinceTs = Date.now() - minutes * 60_000;
+        const rows = readPerfSamples(stateDir, sinceTs); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+        const byKind = new Map();
+        for (const r of rows) {
+            let arr = byKind.get(r.kind);
+            if (!arr) {
+                arr = [];
+                byKind.set(r.kind, arr);
+            }
+            arr.push(r.value);
+        }
+        // Nearest-rank percentile (ceil(p/100*n)-1, clamped). Code-controlled,
+        // never user input (PREVENT-002 safe).
+        function pct(arr, p) {
+            if (!arr.length)
+                return 0;
+            const s = [...arr].sort((a, b) => a - b);
+            const idx = Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1));
+            return s[idx];
+        }
+        function avg(arr) {
+            if (!arr.length)
+                return 0;
+            return arr.reduce((a, b) => a + b, 0) / arr.length;
+        }
+        // rows are ASC by ts, so the last pushed value is the most recent.
+        function latest(arr) {
+            return arr.length ? arr[arr.length - 1] : 0;
+        }
+        const get = (k) => byKind.get(k) ?? [];
+        // diag counters live in the runtime-written dashboard.json (the server is
+        // a detached child with no MegaRuntime ref). Read defensively — absent
+        // until the first snapshot() write (PREVENT-001: assign before access).
+        let diag = null;
+        try {
+            const raw = readFileSync(snapshotPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && parsed.diag)
+                diag = parsed.diag;
+        }
+        catch {
+            /* dashboard.json not written yet */
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            updatedAt: new Date().toISOString(),
+            windowMinutes: minutes,
+            sampleCount: rows.length,
+            turn_latency_ms: {
+                p50: pct(get("turn_latency_ms"), 50),
+                p95: pct(get("turn_latency_ms"), 95),
+                n: get("turn_latency_ms").length,
+            },
+            provider_latency_ms: {
+                p50: pct(get("provider_latency_ms"), 50),
+                p95: pct(get("provider_latency_ms"), 95),
+                n: get("provider_latency_ms").length,
+            },
+            tps: { avg: avg(get("tps")), n: get("tps").length },
+            cache_hit_pct: {
+                avg: avg(get("cache_hit_pct")),
+                latest: latest(get("cache_hit_pct")),
+                n: get("cache_hit_pct").length,
+            },
+            db_recompute_ms: {
+                p50: pct(get("db_recompute_ms"), 50),
+                p95: pct(get("db_recompute_ms"), 95),
+                n: get("db_recompute_ms").length,
+            },
+            disk_write_ms: {
+                p50: pct(get("disk_write_ms"), 50),
+                p95: pct(get("disk_write_ms"), 95),
+                n: get("disk_write_ms").length,
+            },
+            rss_mb: { latest: latest(get("rss_mb")), n: get("rss_mb").length },
+            heap_mb: {
+                latest: latest(get("heap_mb")),
+                n: get("heap_mb").length,
+            },
+            cpu_user_ms: {
+                latest: latest(get("cpu_user_ms")),
+                n: get("cpu_user_ms").length,
+            },
+            cpu_sys_ms: {
+                latest: latest(get("cpu_sys_ms")),
+                n: get("cpu_sys_ms").length,
+            },
+            diag,
+        }));
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "perf_unavailable", detail: String(e) }));
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// handleAchievements — "/api/achievements"
+// ---------------------------------------------------------------------------
+export function handleAchievements(req, res, ctx) {
+    if (!req.url?.startsWith("/api/achievements"))
+        return false;
+    const { stateDir } = ctx;
+    // /api/achievements — S35 achievement tiles. GET returns the 9 seeded rows
+    // {id,title,description,icon,hidden,unlocked_at}. The dashboard server is a
+    // detached child with no MegaRuntime ref, so it reads game_achievements via
+    // listAchievements(stateDir) directly. Non-GET -> 405. PREVENT-PI-004: loopback.
+    const achReq = createRequire(import.meta.url);
+    const { listAchievements } = achReq("../../src/store/sqlite.js");
+    if (req.method !== "GET") {
+        res.writeHead(405, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+        res.end(JSON.stringify({ error: "method_not_allowed" }));
+        return true;
+    }
+    try {
+        const rows = listAchievements(stateDir); // guardrails-allow PREVENT-PI-004: local SQLite read (loopback dashboard)
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(rows));
+    }
+    catch (e) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            error: "achievements_unavailable",
+            detail: String(e),
+        }));
+    }
+    return true;
+}

package/dist/extensions/dashboard-server/routes-repo.js

@@ -0,0 +1,170 @@
+/**
+ * dashboard-server/routes-repo.ts — Repo-index and static route handlers.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readSnapshot } from "./snapshot.js";
+import { dashboardHtml } from "./html.js";
+import { readIndex, getIndexDir } from "./index-reader.js";
+import { ACTIVE_WINDOW_SEC } from "./types.js";
+// ---------------------------------------------------------------------------
+// handleIndex — "/" | "/index.html" | "/api/snapshot" | "/api/version"
+// ---------------------------------------------------------------------------
+export function handleIndex(req, res, ctx) {
+    const { snapshotPath, SERVER_VERSION, serveClientAsset } = ctx;
+    if (req.url === "/" || req.url === "/index.html") {
+        // Sprint B1: prefer the React client build when present; fall back to the
+        // legacy inline html.ts template when the client dist is absent.
+        if (serveClientAsset("/", res))
+            return true;
+        const tier = readSnapshot(snapshotPath).tier;
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(dashboardHtml(tier));
+        return true;
+    }
+    if (req.url === "/api/snapshot") {
+        const snap = readSnapshot(snapshotPath);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(snap));
+        return true;
+    }
+    // Server version — lets the /dashboard launcher detect a stale server from
+    // an older build and replace it on upgrade rather than reuse it.
+    if (req.url === "/api/version") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ version: SERVER_VERSION }));
+        return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// handleRepoIndex — "/api/index" | "/api/repos" | "/api/summary" | "/api/drift" | "/api/servers"
+// ---------------------------------------------------------------------------
+export function handleRepoIndex(req, res, ctx) {
+    const { overlayCurrentRepo, detectCrossRepoDrift } = ctx;
+    if (req.url === "/api/index") {
+        const idx = readIndex();
+        if (idx)
+            overlayCurrentRepo(idx);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(idx ?? { updatedAt: null, summary: null, repos: [] }));
+        return true;
+    }
+    // /api/repos — registry list. Optional `?active=24h` filters to repos
+    // seen within the last N hours (default: all). The dashboard uses this to
+    // drive its "active vs archived" badge without refetching /api/index.
+    if (req.url?.startsWith("/api/repos")) {
+        const url = new URL(req.url, "http://x"); // guardrails-allow PREVENT-PI-004: localhost dashboard URL base (loopback-only)
+        const activeParam = url.searchParams.get("active");
+        const idx = readIndex();
+        if (idx)
+            overlayCurrentRepo(idx);
+        let repos = idx?.repos ?? [];
+        if (activeParam) {
+            const m = /^(\d+)h$/.exec(activeParam);
+            if (m) {
+                const cutoffSec = Math.floor(Date.now() / 1000) - Number(m[1]) * 3600;
+                repos = repos.filter((r) => (r.lastSeen ?? 0) >= cutoffSec);
+            }
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            updatedAt: idx?.updatedAt ?? null,
+            repos,
+            count: repos.length,
+        }));
+        return true;
+    }
+    // /api/summary — header tiles without the full repo list (keeps payload
+    // small for embed scenarios). activeRepos mirrors the /api/repos?active=24h
+    // count so the dashboard can render the active badge alongside totals.
+    if (req.url?.startsWith("/api/summary")) {
+        const idx = readIndex();
+        if (idx)
+            overlayCurrentRepo(idx);
+        const repos = idx?.repos ?? [];
+        const cutoffSec = Math.floor(Date.now() / 1000) - 24 * 3600;
+        const activeRepos = repos.filter((r) => (r.lastSeen ?? 0) >= cutoffSec).length;
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            updatedAt: idx?.updatedAt ?? null,
+            summary: idx?.summary ?? null,
+            activeRepos,
+            totalRepos: repos.length,
+        }));
+        return true;
+    }
+    // /api/drift — R4: cross-repo drift report over repo_registry. Flags stale
+    // repos (>30d idle), compaction lag (active but >24h since last
+    // compaction), and recent model churn. Read-only.
+    if (req.url?.startsWith("/api/drift")) {
+        const report = detectCrossRepoDrift(getIndexDir());
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(report));
+        return true;
+    }
+    if (req.url === "/api/servers") {
+        try {
+            const idx = readIndex();
+            const nowSec = Math.floor(Date.now() / 1000);
+            const servers = (idx?.repos ?? [])
+                .filter((r) => (r.lastSeen ?? 0) >= nowSec - ACTIVE_WINDOW_SEC)
+                .map((r) => {
+                const out = {
+                    repoRoot: r.repoRoot,
+                    displayName: r.displayName,
+                    model: r.modelName,
+                    provider: r.providerName,
+                    lastSeen: r.lastSeen,
+                    lastCompactedAt: r.lastCompactedAt,
+                };
+                try {
+                    const p = join(r.stateDir, "dashboard.json");
+                    if (existsSync(p)) {
+                        const snap = JSON.parse(readFileSync(p, "utf-8"));
+                        out.tier = snap.tier ?? null;
+                        out.contextPct =
+                            snap.context && snap.context.percent != null
+                                ? snap.context.percent
+                                : null;
+                        out.state = (snap.session && snap.session.state) || null;
+                        out.cacheHits = snap.cacheHits ?? null;
+                        out.compacts = snap.compacts ?? null;
+                        out.timeSaved = snap.timeSaved ?? null;
+                        out.updatedAt = snap.updatedAt ?? null;
+                    }
+                }
+                catch {
+                    /* best-effort */
+                }
+                return out;
+            })
+                .sort((a, b) => b.lastSeen - a.lastSeen);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ updatedAt: new Date().toISOString(), servers }));
+        }
+        catch {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "servers_unavailable" }));
+        }
+        return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// handleStatic — non-/api/* GET fallback (SPA client build or legacy HTML).
+// ---------------------------------------------------------------------------
+export function handleStatic(req, res, _ctx) {
+    const { snapshotPath, serveClientAsset } = _ctx;
+    if (req.method === "GET" &&
+        req.url &&
+        !req.url.startsWith("/api/") &&
+        serveClientAsset(req.url, res)) {
+        return true;
+    }
+    // Legacy SPA fallback — serve inline HTML with current tier.
+    const tier = readSnapshot(snapshotPath).tier;
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(dashboardHtml(tier));
+    return true;
+}