@vinkius-core/mcp-fusion-inspector 1.0.0

package/README.md

@@ -0,0 +1,218 @@
+<p align="center">
+  <h1 align="center">@vinkius-core/mcp-fusion-inspector</h1>
+  <p align="center">
+    <strong>MCP Fusion Inspector</strong> — Real-time interactive terminal dashboard for MCP Fusion servers
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@vinkius-core/mcp-fusion-inspector"><img src="https://img.shields.io/npm/v/@vinkius-core/mcp-fusion-inspector?color=blue" alt="npm" /></a>
+  <a href="https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node" />
+</p>
+
+---
+
+> Zero-overhead observability for MCP Fusion servers. Connects via **Shadow Socket** (IPC) — no stdio interference, no port conflicts, no agent disruption.
+
+## Why Inspector?
+
+MCP servers communicate over stdio, which means traditional debugging tools (`console.log`, debuggers) are off-limits. The Inspector solves this by opening an **out-of-band Shadow Socket** (Named Pipe on Windows / Unix Domain Socket on Linux/macOS) that streams real-time telemetry without touching stdio.
+
+```
+┌─────────────────────────────────────────────┐
+│  MCP Client (Claude, Cursor, etc.)         │
+│         ↕ stdio (MCP protocol)             │
+│  MCP Fusion Server                         │
+│         ↕ Shadow Socket (IPC)              │
+│  Inspector TUI / stderr logger              │
+└─────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+```bash
+# Launch interactive TUI (auto-discovers running server)
+npx fusion inspect
+
+# Short alias
+npx fusion insp
+
+# Built-in simulator (no server needed — great for demos)
+npx fusion insp --demo
+
+# Headless stderr output (ECS / K8s / CI)
+npx fusion insp --out stderr
+
+# Connect to a specific server PID
+npx fusion insp --pid 12345
+```
+
+## Dashboard Panels
+
+### Topology
+
+Live tool registry showing every registered tool and action with:
+
+| Column | Description |
+|--------|-------------|
+| Status | `✓` ok, `✗` error, `⋯` pending |
+| Tool | `group.action` qualified name |
+| Type | `R/O` read-only, `W` write, `🔒` sandboxed, `◆FSM` state-gated |
+| Latency | Last execution time in ms |
+| Calls | Total invocation count |
+| Middleware | Chain length per action |
+
+Tabs: **Tools** · **Prompts** · **Resources**
+
+### Traffic Log
+
+Real-time color-coded event stream — every pipeline stage appears as it happens:
+
+```
+19:32:01  ROUTE   billing.createInvoice
+19:32:01  ZOD     ✓ 2ms
+19:32:01  MW      chain(2)
+19:32:01  EXEC    ✓ 45ms
+19:32:01  SLICE   4.2KB → 1.1KB (73.8% saved)
+19:32:01  DLP     ✖ $.user.email → [REDACTED]
+```
+
+### X-Ray Inspector
+
+Select any tool in the list to see deep inspection in the right panel:
+
+- **Error Autopsy** — Full exception with pipeline stage (`VALIDATE`, `MIDDLEWARE`, `EXECUTE`), self-healing recovery hints
+- **Last Input** — Zod-validated arguments (pretty-printed JSON)
+- **Select Reflection** — Which fields the AI chose via `_select` (e.g. "3 of 12 fields")
+- **Late Guillotine** — Token economy: raw DB bytes vs. wire bytes with savings percentage bar
+- **Cognitive Guardrails** — Array truncation from `agentLimit()` (e.g. "500 → 50 items")
+- **DLP Redactions** — Masked PII paths (`$.user.email → [REDACTED]`)
+- **Cognitive Rules** — System rules injected by the Presenter
+- **Call History** — Rolling log with latency, status, and summary per call
+
+### Header Bar
+
+Server name · PID · Heap usage · Uptime · Requests/second
+
+## Telemetry Events
+
+The Inspector processes all events emitted by the MCP Fusion pipeline:
+
+| Event | Source | Description |
+|-------|--------|-------------|
+| `topology` | `startServer()` | Tool registry snapshot (initial + hot-reload) |
+| `heartbeat` | `startServer()` | PID, heap, uptime (every 5s) |
+| `route` | Pipeline | Action routing resolution |
+| `validate` | Pipeline | Zod validation result + duration |
+| `middleware` | Pipeline | Middleware chain length |
+| `execute` | Pipeline | Handler execution result + duration |
+| `error` | Pipeline | Exception with recovery hints |
+| `presenter.slice` | Presenter | Raw bytes vs. wire bytes (token savings) |
+| `presenter.rules` | Presenter | Injected system rules |
+| `dlp.redact` | DLP | PII redaction paths |
+| `fsm.transition` | FSM Gate | State machine transition (from → to) |
+| `sandbox.exec` | Sandbox | Sandboxed execution metrics |
+| `governance` | Governance | Policy enforcement events |
+
+## Output Modes
+
+### Interactive TUI (default)
+
+Full-screen terminal dashboard with keyboard navigation.
+
+```bash
+fusion inspect
+fusion insp --demo
+```
+
+**Keyboard shortcuts:**
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` / `j` `k` | Navigate tool list |
+| `q` / `Ctrl+C` | Exit |
+
+### Headless (stderr)
+
+Structured log output for non-TTY environments. Ideal for containers, CI/CD, and log aggregation.
+
+```bash
+# Color-coded stderr
+fusion insp --out stderr
+
+# NDJSON format (set env var)
+FUSION_LOG_FORMAT=json fusion insp --out stderr
+
+# Pipe to file
+fusion insp --out stderr | tee telemetry.log
+```
+
+Respects `NO_COLOR` environment variable.
+
+## Programmatic API
+
+```typescript
+import {
+    commandTop,
+    streamToStderr,
+    startSimulator,
+} from '@vinkius-core/mcp-fusion-inspector';
+
+// Launch the interactive TUI
+await commandTop({ pid: 12345 });
+
+// Launch the headless stderr logger
+await streamToStderr({ pid: 12345 });
+
+// Start the built-in simulator (returns a TelemetryBus)
+const bus = await startSimulator({ rps: 5 });
+// ... use bus.path to connect TUI or logger
+await bus.close();
+```
+
+### Rendering Utilities
+
+Low-level ANSI primitives exported for custom TUI implementations:
+
+```typescript
+import {
+    ansi,
+    ScreenManager,
+    box,
+    hline,
+    pad,
+    truncate,
+    progressBar,
+    stringWidth,
+    RingBuffer,
+} from '@vinkius-core/mcp-fusion-inspector';
+```
+
+## Installation
+
+```bash
+npm install @vinkius-core/mcp-fusion-inspector
+```
+
+### Peer Dependency
+
+Requires `@vinkius-core/mcp-fusion` ≥ 3.0.0 (provides `TelemetryEvent` types and `TelemetryBus`).
+
+## How It Works
+
+1. **Server side** — `startServer({ telemetry: true })` creates a Shadow Socket (Named Pipe / UDS) and streams `TelemetryEvent` objects as newline-delimited JSON.
+
+2. **Client side** — The Inspector connects to the Shadow Socket, parses events, and updates the TUI state at 15 fps (throttled to prevent flicker).
+
+3. **Auto-discovery** — When no `--pid` or `--path` is specified, the Inspector scans for the well-known IPC path pattern and auto-connects. If no server is found, it polls every 2 seconds. If the connection drops, it auto-reconnects.
+
+## Requirements
+
+- **Node.js** ≥ 18.0.0
+- **Interactive terminal** (for TUI mode) — `--out stderr` for non-TTY environments
+- **MCP Fusion** ≥ 3.0.0 (peer dependency)
+
+## License
+
+[Apache-2.0](https://github.com/vinkius-labs/mcp-fusion/blob/main/LICENSE)

package/dist/AnsiRenderer.d.ts

@@ -0,0 +1,160 @@
+/**
+ * AnsiRenderer — Low-Level Terminal Rendering Engine
+ *
+ * Pure ANSI escape sequence renderer for the Inspector TUI.
+ * Zero dependencies — uses only built-in Node.js `process.stdout`.
+ *
+ * Features:
+ * - Alternate screen buffer management (like vim/htop)
+ * - Double-buffered rendering (only emit changed cells)
+ * - Unicode-aware column width calculation (Gotcha #3: emoji double-width)
+ * - Debounced resize handling (Gotcha #4: SIGWINCH bomb)
+ * - Box drawing with Unicode characters
+ *
+ * @module
+ */
+export declare const ansi: {
+    readonly cyan: (s: string) => string;
+    readonly green: (s: string) => string;
+    readonly red: (s: string) => string;
+    readonly yellow: (s: string) => string;
+    readonly magenta: (s: string) => string;
+    readonly blue: (s: string) => string;
+    readonly dim: (s: string) => string;
+    readonly bold: (s: string) => string;
+    readonly inverse: (s: string) => string;
+    readonly reset: "\u001B[0m";
+    readonly fg: {
+        readonly cyan: "\u001B[36m";
+        readonly green: "\u001B[32m";
+        readonly red: "\u001B[31m";
+        readonly yellow: "\u001B[33m";
+        readonly magenta: "\u001B[35m";
+        readonly blue: "\u001B[34m";
+        readonly white: "\u001B[37m";
+    };
+    readonly bg: {
+        readonly red: "\u001B[41m";
+        readonly green: "\u001B[42m";
+        readonly yellow: "\u001B[43m";
+        readonly blue: "\u001B[44m";
+    };
+    readonly hideCursor: "\u001B[?25l";
+    readonly showCursor: "\u001B[?25h";
+    readonly altScreen: "\u001B[?1049h";
+    readonly mainScreen: "\u001B[?1049l";
+    readonly clearScreen: "\u001B[2J\u001B[H";
+    readonly moveTo: (row: number, col: number) => string;
+    readonly clearLine: "\u001B[2K";
+};
+/**
+ * Calculate the visual width of a string in terminal columns.
+ *
+ * Handles:
+ * - East Asian Fullwidth characters (2 columns)
+ * - Emoji (2 columns each)
+ * - Combining characters (0 columns)
+ * - ANSI escape sequences (0 columns — invisible)
+ * - Variation selectors and ZWJ (0 columns)
+ *
+ * This is a lightweight approximation inspired by `string-width`.
+ * It avoids the full ICU dependency by checking Unicode block ranges.
+ *
+ * @param str - The string to measure
+ * @returns Width in terminal columns
+ */
+export declare function stringWidth(str: string): number;
+/**
+ * Truncate a string to fit within a maximum visual column width.
+ * ANSI codes are preserved correctly.
+ *
+ * @param str - String to truncate
+ * @param maxWidth - Maximum visual width in columns
+ * @param suffix - Suffix to add if truncated (default: '…')
+ * @returns Truncated string
+ */
+export declare function truncate(str: string, maxWidth: number, suffix?: string): string;
+/**
+ * Pad a string to a specific visual width with spaces.
+ *
+ * @param str - String to pad
+ * @param targetWidth - Desired visual width
+ * @param align - 'left' or 'right' alignment
+ * @returns Padded string
+ */
+export declare function pad(str: string, targetWidth: number, align?: 'left' | 'right'): string;
+/** Unicode box drawing characters */
+export declare const box: {
+    readonly topLeft: "╭";
+    readonly topRight: "╮";
+    readonly bottomLeft: "╰";
+    readonly bottomRight: "╯";
+    readonly horizontal: "─";
+    readonly vertical: "│";
+    readonly teeRight: "├";
+    readonly teeLeft: "┤";
+    readonly teeDown: "┬";
+    readonly teeUp: "┴";
+    readonly cross: "┼";
+};
+/**
+ * Draw a horizontal line with box-drawing characters.
+ * @param width - Total width including corners/tees
+ * @param left - Left character (e.g. '├' or '╭')
+ * @param right - Right character (e.g. '┤' or '╮')
+ * @param fill - Fill character (default: '─')
+ */
+export declare function hline(width: number, left: string, right: string, fill?: "─"): string;
+/**
+ * Render an ASCII progress/savings bar.
+ *
+ * @param ratio - Value between 0 and 1
+ * @param width - Total width in columns
+ * @param filledChar - Character for filled portion (default: '█')
+ * @param emptyChar - Character for empty portion (default: '░')
+ * @returns Colored progress bar string
+ */
+export declare function progressBar(ratio: number, width: number, filledChar?: string, emptyChar?: string): string;
+/**
+ * Low-level screen manager for alternate buffer TUI rendering.
+ *
+ * Provides:
+ * - Enter/exit alternate screen buffer
+ * - Raw mode stdin management
+ * - Debounced resize handling (Gotcha #4)
+ * - Direct cursor positioning writes
+ */
+export declare class ScreenManager {
+    private _active;
+    private _resizeTimer;
+    private _resizeCallback;
+    private _inputCallback;
+    private _cols;
+    private _rows;
+    /** Current terminal columns */
+    get cols(): number;
+    /** Current terminal rows */
+    get rows(): number;
+    /** Whether the screen is active (alternate buffer + raw mode) */
+    get active(): boolean;
+    /**
+     * Enter the alternate screen buffer and enable raw mode.
+     *
+     * @param onResize - Callback for terminal resize (debounced 100ms, Gotcha #4)
+     * @param onInput - Callback for keyboard input (raw bytes)
+     */
+    enter(onResize: () => void, onInput: (key: string, raw: Buffer) => void): void;
+    /**
+     * Exit the alternate screen buffer and restore normal operation.
+     */
+    exit(): void;
+    /** Write at a specific position (1-indexed) */
+    writeAt(row: number, col: number, text: string): void;
+    /** Clear the entire screen */
+    clear(): void;
+    /** Flush output */
+    flush(): void;
+    private _handleResize;
+    private _handleInput;
+}
+//# sourceMappingURL=AnsiRenderer.d.ts.map

package/dist/AnsiRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnsiRenderer.d.ts","sourceRoot":"","sources":["../src/AnsiRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,eAAO,MAAM,IAAI;uBAEA,MAAM,KAAG,MAAM;wBACf,MAAM,KAAG,MAAM;sBACf,MAAM,KAAG,MAAM;yBACf,MAAM,KAAG,MAAM;0BACf,MAAM,KAAG,MAAM;uBACf,MAAM,KAAG,MAAM;sBACf,MAAM,KAAG,MAAM;uBACf,MAAM,KAAG,MAAM;0BACf,MAAM,KAAG,MAAM;;;;;;;;;;;;;;;;;;;;;;2BAoBd,MAAM,OAAO,MAAM,KAAG,MAAM;;CAEpC,CAAC;AAMX;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqD/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,MAAM,CAiC5E;AAED;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,GAAG,OAAgB,GAAG,MAAM,CAK9F;AAMD,qCAAqC;AACrC,eAAO,MAAM,GAAG;;;;;;;;;;;;CAON,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,MAAiB,GAAG,MAAM,CAE/F;AAMD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,SAAM,EAAE,SAAS,SAAM,GAAG,MAAM,CAYnG;AAMD;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,eAAe,CAA2B;IAClD,OAAO,CAAC,cAAc,CAAmD;IACzE,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,KAAK,CAAM;IAEnB,+BAA+B;IAC/B,IAAI,IAAI,IAAI,MAAM,CAAuB;IACzC,4BAA4B;IAC5B,IAAI,IAAI,IAAI,MAAM,CAAuB;IACzC,iEAAiE;IACjE,IAAI,MAAM,IAAI,OAAO,CAAyB;IAE9C;;;;;OAKG;IACH,KAAK,CACD,QAAQ,EAAE,MAAM,IAAI,EACpB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,GAC5C,IAAI;IAwBP;;OAEG;IACH,IAAI,IAAI,IAAI;IAwBZ,+CAA+C;IAC/C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrD,8BAA8B;IAC9B,KAAK,IAAI,IAAI;IAIb,mBAAmB;IACnB,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,aAAa,CAYnB;IAEF,OAAO,CAAC,YAAY,CAGlB;CACL"}