@holmes-lab/holmes-kit 0.10.1 → 0.12.0

package/dist/holmes/mcp/tool-schemas.js

@@ -133,6 +133,16 @@ exports.TOOL_SCHEMAS = {
             },
         },
     },
+    rtm_dashboard: {
+        description: "Launch (idempotently) the interactive RTM/CPG dashboard the agent would otherwise start by hand, and return { ok, url, running, census } — use it when a human asks to SEE the RTM heatmap / coverage matrix / dashboard. `url` is the localhost address to open; `running` is true when an already-live server for this project was reused (a second call never starts a second server). `census` is an honesty summary of what the dashboard shows — { reqCount, pipelineCount, coveredCount, coveragePct, retiredCount, findingsScanned } — so the caller can report coverage without scraping the page. No spec writes, no ledger append. Refuses when a supplied `root` points at a different project than the server is bound to.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
+                port: { type: 'number', description: 'Optional port to bind when first launching (default 8080). Ignored if a server for this project is already running.' },
+            },
+        },
+    },
     spec_approve: {
         description: 'Approve a spec as a sealing ACT: confirm the ledger destination BEFORE sealing → validate (zero errors) → record approved_digest + parent_digests snapshots → status: approved (written only at the version this act read; a concurrent edit wins and the approval is refused for retry) → append spec-approved to the provenance ledger. Requires a valid out-of-band HOLMES_APPROVAL in the SERVER environment (fail-closed; nothing in the request can substitute). Refuses an unsealed approved parent — seal parents first.',
         inputSchema: {

package/dist/holmes/project/npx-bin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @implements A-SPEC-542.1
+ * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
+ * platform of the machine whose terminal reads the emitted hint. Field-measured 2026-09-05 (codex on
+ * Windows): a locked-down PowerShell execution policy blocks the `npx` call because the `.ps1` shim
+ * is resolved first (PSSecurityException); `npx.cmd` runs. Everywhere else `npx` is correct, so every
+ * non-win32 emission stays byte-identical. Only the exact 'win32' token switches — a typo or unknown
+ * platform must never flip a POSIX hint to a Windows-only form.
+ */
+export declare function npxBin(platform?: string): string;

package/dist/holmes/project/npx-bin.js

@@ -0,0 +1,16 @@
+"use strict";
+// @implements A-SPEC-542.1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.npxBin = npxBin;
+/**
+ * @implements A-SPEC-542.1
+ * The npx binary an OPERATOR can actually run on the platform this process runs on — which is the
+ * platform of the machine whose terminal reads the emitted hint. Field-measured 2026-09-05 (codex on
+ * Windows): a locked-down PowerShell execution policy blocks the `npx` call because the `.ps1` shim
+ * is resolved first (PSSecurityException); `npx.cmd` runs. Everywhere else `npx` is correct, so every
+ * non-win32 emission stays byte-identical. Only the exact 'win32' token switches — a typo or unknown
+ * platform must never flip a POSIX hint to a Windows-only form.
+ */
+function npxBin(platform = process.platform) {
+    return platform === 'win32' ? 'npx.cmd' : 'npx';
+}

package/dist/holmes/server/cfg-view.d.ts

@@ -0,0 +1,45 @@
+import type { Cfg, CfgEdge } from '../cpg/foundation/cfg';
+import type { Pdg } from '../cpg/foundation/cdg';
+import type { PersistedAst } from '../cpg/foundation/ast-store';
+export interface CfgViewBlock {
+    id: number;
+    line: number;
+    label: string;
+    unreachable: boolean;
+}
+export interface CfgView {
+    entry: number;
+    exit: number;
+    blocks: CfgViewBlock[];
+    edges: {
+        from: number;
+        to: number;
+        kind: CfgEdge['kind'];
+    }[];
+    ctrlDeps: {
+        ctrl: number;
+        dep: number;
+    }[];
+    dataDeps: {
+        from: number;
+        to: number;
+        name: string;
+    }[];
+}
+/**
+ * @implements A-SPEC-545.4
+ * Pure: 1-based line number of a byte offset (count of newlines in [0, offset) + 1). Clamped.
+ */
+export declare function lineAtByte(source: string, offset: number): number;
+/**
+ * @implements A-SPEC-545.4
+ * Pure: fold a foundation Cfg + Pdg into a display-ready graph — block labels/lines, control-flow
+ * edges, block-level control deps, and reaching defs projected to block pairs (deduped, no self-edge).
+ */
+export declare function buildCfgView(cfg: Cfg | {
+    unsupported: string;
+}, pdg: Pdg | {
+    unsupported: string;
+}, ast: PersistedAst, source: string): CfgView | {
+    unsupported: string;
+};

package/dist/holmes/server/cfg-view.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineAtByte = lineAtByte;
+exports.buildCfgView = buildCfgView;
+/**
+ * @implements A-SPEC-545.4
+ * Pure: 1-based line number of a byte offset (count of newlines in [0, offset) + 1). Clamped.
+ */
+function lineAtByte(source, offset) {
+    const at = Math.max(0, Math.min(offset, source.length));
+    let line = 1;
+    for (let i = 0; i < at; i++)
+        if (source.charCodeAt(i) === 10)
+            line++;
+    return line;
+}
+/**
+ * @implements A-SPEC-545.4
+ * Pure: fold a foundation Cfg + Pdg into a display-ready graph — block labels/lines, control-flow
+ * edges, block-level control deps, and reaching defs projected to block pairs (deduped, no self-edge).
+ */
+function buildCfgView(cfg, pdg, ast, source) {
+    if ('unsupported' in cfg)
+        return cfg;
+    if ('unsupported' in pdg)
+        return pdg;
+    // stmt node index → owning block id
+    const blockOf = new Map();
+    for (const b of cfg.blocks)
+        for (const s of b.stmts)
+            blockOf.set(s, b.id);
+    const unreachable = new Set(cfg.unreachable);
+    const blocks = cfg.blocks.map((b) => {
+        const first = b.stmts.length ? b.stmts[0] : -1;
+        const node = first >= 0 ? ast.nodes[first] : undefined;
+        const line = node ? lineAtByte(source, node.start) : 0;
+        const raw = node ? source.slice(node.start, node.end) : '';
+        const label = raw.split('\n', 1)[0].slice(0, 80);
+        return { id: b.id, line, label, unreachable: unreachable.has(b.id) };
+    });
+    const edges = cfg.edges.map((e) => ({ from: e.from, to: e.to, kind: e.kind }));
+    const ctrlDeps = pdg.controlDeps.map((c) => ({ ctrl: c.ctrl, dep: c.dep }));
+    const seen = new Set();
+    const dataDeps = [];
+    for (const d of pdg.reachingDefs) {
+        const from = blockOf.get(d.defStmt);
+        const to = blockOf.get(d.useStmt);
+        if (from === undefined || to === undefined || from === to)
+            continue; // no self-edge / unresolved
+        const key = `${from}>${to}:${d.name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        dataDeps.push({ from, to, name: d.name });
+    }
+    return { entry: cfg.entry, exit: cfg.exit, blocks, edges, ctrlDeps, dataDeps };
+}

package/dist/holmes/server/dashboard-launcher.d.ts

@@ -0,0 +1,40 @@
+/** Honesty summary of what a launched dashboard shows — derived from the endpoints it serves. */
+export interface DashboardCensus {
+    reqCount: number;
+    pipelineCount: number;
+    coveredCount: number;
+    coveragePct: number;
+    retiredCount: number;
+    findingsScanned: boolean;
+}
+/**
+ * @implements A-SPEC-545.3
+ * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
+ * coveragePct never divides by zero.
+ */
+export declare function dashboardCensus(rtm: any, heatmap: any): DashboardCensus;
+export interface LaunchResult {
+    url: string;
+    port: number;
+    running: boolean;
+}
+export interface StartedHandle {
+    url: string;
+    port: number;
+    stop?: () => Promise<void>;
+}
+type Starter = (opts: {
+    root: string;
+    port?: number;
+}) => Promise<StartedHandle>;
+/**
+ * @implements A-SPEC-545.3
+ * Idempotent per-root dashboard registry: start once, reuse thereafter. `start` is injected so the
+ * idempotency is testable without a real server. A failing start registers nothing.
+ */
+export declare function ensureDashboard(root: string, port: number | undefined, start: Starter): Promise<LaunchResult>;
+/** Test hook: forget all launched servers (without stopping them). */
+export declare function _resetLauncher(): void;
+/** Test/shutdown hook: stop every launched server and clear the registry. */
+export declare function _stopAll(): Promise<void>;
+export {};

package/dist/holmes/server/dashboard-launcher.js

@@ -0,0 +1,54 @@
+"use strict";
+// @implements A-SPEC-545.3
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardCensus = dashboardCensus;
+exports.ensureDashboard = ensureDashboard;
+exports._resetLauncher = _resetLauncher;
+exports._stopAll = _stopAll;
+/**
+ * @implements A-SPEC-545.3
+ * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
+ * coveragePct never divides by zero.
+ */
+function dashboardCensus(rtm, heatmap) {
+    const reqCount = heatmap?.matrix?.reqs?.length ?? 0;
+    const pipelineCount = heatmap?.pipelineCount ?? 0;
+    const coveredCount = heatmap?.completeCount ?? 0;
+    const coveragePct = pipelineCount > 0 ? Math.round((coveredCount / pipelineCount) * 100) : 0;
+    return {
+        reqCount,
+        pipelineCount,
+        coveredCount,
+        coveragePct,
+        retiredCount: rtm?.retired?.count ?? 0,
+        findingsScanned: heatmap?.findingsScanned === true,
+    };
+}
+const live = new Map();
+/**
+ * @implements A-SPEC-545.3
+ * Idempotent per-root dashboard registry: start once, reuse thereafter. `start` is injected so the
+ * idempotency is testable without a real server. A failing start registers nothing.
+ */
+async function ensureDashboard(root, port, start) {
+    const existing = live.get(root);
+    if (existing)
+        return { url: existing.url, port: existing.port, running: true };
+    const h = await start({ root, port }); // a throw here registers nothing and propagates
+    live.set(root, h);
+    return { url: h.url, port: h.port, running: false };
+}
+/** Test hook: forget all launched servers (without stopping them). */
+function _resetLauncher() {
+    live.clear();
+}
+/** Test/shutdown hook: stop every launched server and clear the registry. */
+async function _stopAll() {
+    for (const h of live.values()) {
+        try {
+            await h.stop?.();
+        }
+        catch { /* best effort */ }
+    }
+    live.clear();
+}