proofscan 0.10.62 → 0.11.1

package/dist/html/types.ts

@@ -0,0 +1,491 @@
+/**
+ * HTML Report Types (Phase 5.0)
+ *
+ * Data models for HTML export functionality.
+ * Supports RPC detail and Session reports with embedded JSON.
+ */
+
+/**
+ * Schema version for HTML reports
+ */
+export const HTML_REPORT_SCHEMA_VERSION = 1;
+
+/**
+ * Default embed limit for payload JSON (256KB)
+ */
+export const DEFAULT_EMBED_MAX_BYTES = 262144;
+
+/**
+ * Preview length for truncated payloads
+ */
+export const TRUNCATION_PREVIEW_LENGTH = 4096;
+
+/**
+ * Short ID length for display (e.g., session IDs, RPC IDs)
+ */
+export const SHORT_ID_LENGTH = 8;
+
+/**
+ * Report metadata
+ */
+export interface HtmlReportMeta {
+  schemaVersion: number;
+  generatedAt: string;      // ISO8601
+  generatedBy: string;      // "proofscan v0.x.x"
+  redacted: boolean;
+}
+
+/**
+ * RPC status values (uppercase for consistency)
+ */
+export type RpcStatus = 'OK' | 'ERR' | 'PENDING';
+
+/**
+ * HTML export options
+ */
+export interface HtmlExportOptions {
+  /** Output directory */
+  outDir: string;
+  /** Open in browser after export */
+  open: boolean;
+  /** Redact sensitive values */
+  redact: boolean;
+  /** Max bytes per payload before truncation */
+  embedMaxBytes: number;
+  /** Write oversized payloads to separate files */
+  spill: boolean;
+}
+
+/**
+ * Default export options
+ */
+export const DEFAULT_EXPORT_OPTIONS: HtmlExportOptions = {
+  outDir: './pfscan_reports',
+  open: false,
+  redact: false,
+  embedMaxBytes: DEFAULT_EMBED_MAX_BYTES,
+  spill: false,
+};
+
+/**
+ * RPC payload with truncation support
+ */
+export interface PayloadData {
+  /** Full JSON (null if truncated) */
+  json: unknown | null;
+  /** Size in bytes */
+  size: number;
+  /** Whether payload was truncated */
+  truncated: boolean;
+  /** Preview string if truncated (first N chars) */
+  preview: string | null;
+  /** Relative path to spill file if --spill enabled */
+  spillFile?: string;
+}
+
+/**
+ * RPC detail for HTML report
+ */
+export interface HtmlRpcData {
+  rpc_id: string;
+  session_id: string;
+  target_id: string;
+  method: string;
+  status: RpcStatus;
+  latency_ms: number | null;
+  error_code: number | null;
+  request_ts: string;
+  response_ts: string | null;
+  request: PayloadData;
+  response: PayloadData;
+}
+
+/**
+ * RPC Report V1
+ */
+export interface HtmlRpcReportV1 {
+  meta: HtmlReportMeta;
+  rpc: HtmlRpcData;
+}
+
+/**
+ * Session RPC detail for table rows
+ */
+export interface SessionRpcDetail {
+  rpc_id: string;
+  method: string;
+  status: RpcStatus;
+  latency_ms: number | null;
+  request_ts: string;
+  response_ts: string | null;
+  error_code: number | null;
+  request: PayloadData;
+  response: PayloadData;
+}
+
+/**
+ * Session data for HTML report
+ */
+export interface HtmlSessionData {
+  session_id: string;
+  target_id: string;
+  started_at: string;
+  ended_at: string | null;
+  exit_reason: string | null;
+  rpc_count: number;
+  event_count: number;
+  /** Total latency across all RPCs in milliseconds */
+  total_latency_ms: number | null;
+}
+
+/**
+ * Session Report V1
+ */
+export interface HtmlSessionReportV1 {
+  meta: HtmlReportMeta;
+  session: HtmlSessionData;
+  rpcs: SessionRpcDetail[];
+}
+
+/**
+ * Convert DB status to RpcStatus
+ */
+export function toRpcStatus(success: number | null): RpcStatus {
+  if (success === 1) return 'OK';
+  if (success === 0) return 'ERR';
+  return 'PENDING';
+}
+
+/**
+ * Get status symbol for display
+ */
+export function getStatusSymbol(status: RpcStatus): string {
+  switch (status) {
+    case 'OK': return '✓';
+    case 'ERR': return '✗';
+    case 'PENDING': return '?';
+  }
+}
+
+/**
+ * Create payload data with truncation handling
+ */
+export function createPayloadData(
+  json: unknown | null,
+  rawJson: string | null,
+  embedMaxBytes: number,
+  spillFile?: string
+): PayloadData {
+  if (rawJson === null || json === null) {
+    return {
+      json: null,
+      size: 0,
+      truncated: false,
+      preview: null,
+    };
+  }
+
+  const size = Buffer.byteLength(rawJson, 'utf8');
+  const truncated = size > embedMaxBytes;
+
+  if (truncated) {
+    return {
+      json: null,
+      size,
+      truncated: true,
+      preview: rawJson.slice(0, TRUNCATION_PREVIEW_LENGTH),
+      spillFile,
+    };
+  }
+
+  return {
+    json,
+    size,
+    truncated: false,
+    preview: null,
+  };
+}
+
+/**
+ * Generate output filename for RPC HTML
+ */
+export function getRpcHtmlFilename(rpcId: string): string {
+  return `rpc_${rpcId}.html`;
+}
+
+/**
+ * Generate output filename for Session HTML
+ */
+export function getSessionHtmlFilename(sessionId: string): string {
+  const short = sessionId.slice(0, 8);
+  return `session_${short}.html`;
+}
+
+/**
+ * Generate spill filename for payload
+ */
+export function getSpillFilename(
+  sessionId: string,
+  rpcId: string,
+  type: 'req' | 'res'
+): string {
+  const sessionShort = sessionId.slice(0, 8);
+  return `payload_${sessionShort}_${rpcId}_${type}.json`;
+}
+
+// ============================================================================
+// Connector HTML Report Types (Phase 5.1)
+// ============================================================================
+
+/**
+ * MCP Server capabilities from initialize response
+ */
+export interface HtmlMcpCapabilities {
+  tools: boolean;       // capabilities.tools is present
+  resources: boolean;   // capabilities.resources is present
+  prompts: boolean;     // capabilities.prompts is present
+}
+
+/**
+ * MCP Server info extracted from initialize response
+ */
+export interface HtmlMcpServerInfo {
+  name: string | null;          // serverInfo.name from initialize response
+  version: string | null;       // serverInfo.version
+  protocolVersion: string | null; // protocolVersion from initialize response
+  capabilities: HtmlMcpCapabilities;  // supported capabilities
+}
+
+/**
+ * Connector configuration info for HTML display
+ */
+export interface HtmlConnectorInfo {
+  target_id: string;
+  enabled: boolean;
+  transport: {
+    type: 'stdio' | 'rpc-http' | 'rpc-sse';
+    /** For stdio: command + args joined */
+    command?: string;
+    /** For http/sse: URL */
+    url?: string;
+  };
+  /** MCP server info from latest initialize response (if available) */
+  server?: HtmlMcpServerInfo;
+  /** Total session count in DB */
+  session_count: number;
+  /** Sessions included in this export */
+  displayed_sessions: number;
+  /** Pagination offset */
+  offset: number;
+}
+
+/**
+ * Connector session row for left pane list
+ */
+export interface HtmlConnectorSessionRow {
+  session_id: string;
+  short_id: string;         // 8文字プレフィックス
+  started_at: string;
+  ended_at: string | null;
+  rpc_count: number;
+  event_count: number;
+  error_count: number;      // For ERR badge (success=0 count)
+  total_latency_ms: number | null;
+}
+
+/**
+ * Connector Report V1 - embeds multiple session reports
+ */
+export interface HtmlConnectorReportV1 {
+  meta: HtmlReportMeta;
+  connector: HtmlConnectorInfo;
+  /** セッション一覧（左ペイン用） */
+  sessions: HtmlConnectorSessionRow[];
+  /** セッション詳細（右ペイン用）- session_id をキーとするマップ */
+  session_reports: Record<string, HtmlSessionReportV1>;
+  /** Analytics data (Phase 5.2) */
+  analytics: HtmlConnectorAnalyticsV1;
+}
+
+/**
+ * Generate output filename for Connector HTML
+ * Sanitizes connector ID (replaces non-alphanumeric with hyphen)
+ */
+export function getConnectorHtmlFilename(connectorId: string): string {
+  const sanitized = connectorId.replace(/[^a-zA-Z0-9-_]/g, '-');
+  return `connector_${sanitized}.html`;
+}
+
+// ============================================================================
+// Connector HTML Analytics Types (Phase 5.2)
+// ============================================================================
+
+/**
+ * Connector-level KPIs
+ */
+export interface HtmlConnectorKpis {
+  rpc_total: number;
+  rpc_ok: number;
+  rpc_err: number;
+  rpc_pending: number;
+  avg_latency_ms: number | null;    // null if no RPCs with latency
+  p95_latency_ms: number | null;    // null if < 20 samples (nearest-rank method)
+  max_latency_ms: number | null;
+  total_request_bytes: number;
+  total_response_bytes: number;
+  sessions_total: number;
+  sessions_displayed: number;
+  top_tool_name: string | null;
+  top_tool_calls: number | null;
+}
+
+/**
+ * Heatmap cell (GitHub contributions style)
+ */
+export interface HtmlHeatmapCell {
+  date: string;    // YYYY-MM-DD (UTC)
+  count: number;   // RPC count
+}
+
+/**
+ * Heatmap data with intensity calculation
+ */
+export interface HtmlHeatmapData {
+  start_date: string;
+  end_date: string;
+  cells: HtmlHeatmapCell[];   // Full range including 0-count days
+  max_count: number;          // For intensity scaling
+}
+
+/**
+ * Latency histogram bucket
+ */
+export interface HtmlLatencyBucket {
+  label: string;      // e.g., "0-10", "1000+"
+  from_ms: number;
+  to_ms: number | null;  // null = +∞ (for "1000+" bucket)
+  count: number;
+}
+
+/**
+ * Latency histogram data
+ */
+export interface HtmlLatencyHistogram {
+  buckets: HtmlLatencyBucket[];
+  sample_size: number;      // RPCs with latency_ms
+  excluded_count: number;   // RPCs without latency_ms
+}
+
+/**
+ * Method latency entry for bar chart (one bar per method)
+ */
+export interface HtmlMethodLatencyEntry {
+  method: string;           // e.g., "initialize", "tools/list", "tools/call"
+  latencies: number[];      // All latency values for this method
+  min_ms: number | null;
+  max_ms: number | null;
+  avg_ms: number | null;
+  p50_ms: number | null;    // Median
+  count: number;            // Number of calls
+}
+
+/**
+ * Method-based latency chart data (logarithmic Y-axis)
+ */
+export interface HtmlMethodLatencyData {
+  methods: HtmlMethodLatencyEntry[];
+  sample_size: number;
+  max_latency_ms: number;   // For Y-axis scaling
+}
+
+/**
+ * Top tool entry
+ */
+export interface HtmlTopTool {
+  name: string;
+  count: number;
+  pct: number;    // 0-100
+}
+
+/**
+ * Top tools data
+ */
+export interface HtmlTopToolsData {
+  items: HtmlTopTool[];   // Top 5
+  total_calls: number;    // Total tools/call count
+}
+
+/**
+ * Method distribution slice (for donut chart)
+ */
+export interface HtmlMethodSlice {
+  method: string;
+  count: number;
+  pct: number;    // 0-100
+}
+
+/**
+ * Method distribution data
+ */
+export interface HtmlMethodDistribution {
+  slices: HtmlMethodSlice[];   // Top 5 methods + "Others"
+  total_rpcs: number;
+}
+
+/**
+ * Complete analytics data
+ */
+export interface HtmlConnectorAnalyticsV1 {
+  kpis: HtmlConnectorKpis;
+  heatmap: HtmlHeatmapData;
+  latency: HtmlLatencyHistogram;
+  /** Method-based latency chart (X: methods, Y: log scale latency) */
+  method_latency: HtmlMethodLatencyData;
+  top_tools: HtmlTopToolsData;
+  method_distribution: HtmlMethodDistribution;
+}
+
+// ============================================================================
+// RPC Inspector Types (Phase 11.5)
+// ============================================================================
+
+/**
+ * JSON Pointer target (request or response payload)
+ */
+export type JsonPointerTarget = 'request' | 'response';
+
+/**
+ * Pointer link for summary-to-raw navigation
+ */
+export interface JsonPointer {
+  target: JsonPointerTarget;
+  path: string; // JSON Pointer format, e.g., "#/result/tools/0/name"
+}
+
+/**
+ * Summary row with optional pointer link
+ */
+export interface SummaryRow {
+  type: 'header' | 'property' | 'item';
+  label: string;
+  value?: string;
+  pointer?: JsonPointer;
+  children?: SummaryRow[];
+  cssClass?: string;
+}
+
+/**
+ * Method-specific summary renderer result
+ */
+export interface MethodSummary {
+  method: string;
+  rows: SummaryRow[];
+}
+
+/**
+ * Method summary handler interface
+ */
+export interface MethodSummaryHandler {
+  method: string | RegExp;
+  render: (request: unknown, response: unknown) => SummaryRow[];
+}

package/dist/html/utils.ts

@@ -0,0 +1,107 @@
+/**
+ * HTML Export Utilities
+ *
+ * Shared utility functions for HTML export functionality.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { t } from '../i18n/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get package version for HTML reports
+ */
+let _packageVersion: string = '';
+export function getPackageVersion(): string {
+  if (_packageVersion) {
+    return _packageVersion;
+  }
+  try {
+    const pkgPath = path.resolve(__dirname, '../../package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    _packageVersion = pkg.version || '0.0.0';
+  } catch {
+    _packageVersion = '0.0.0';
+  }
+  return _packageVersion;
+}
+
+/**
+ * Validate and sanitize output directory path
+ * Prevents path traversal attacks by ensuring the path doesn't escape CWD
+ *
+ * @param outDir - User-provided output directory
+ * @returns Resolved absolute path
+ * @throws Error if path is invalid or escapes current directory
+ */
+export function validateOutputPath(outDir: string): string {
+  const cwd = process.cwd();
+  const resolved = path.resolve(cwd, outDir);
+  const normalized = path.normalize(resolved);
+
+  // Ensure the path is within or equal to CWD
+  // Allow paths that start with CWD or are absolute paths explicitly provided
+  if (!normalized.startsWith(cwd) && !path.isAbsolute(outDir)) {
+    throw new Error(t('errors.pathEscapes'));
+  }
+
+  // Check for suspicious patterns even in absolute paths
+  if (outDir.includes('..')) {
+    // If it contains '..' but still resolves within cwd, that's OK
+    // If it resolves outside, reject
+    if (!normalized.startsWith(cwd)) {
+      throw new Error(t('errors.pathEscapes'));
+    }
+  }
+
+  return normalized;
+}
+
+/**
+ * Validate embedMaxBytes option
+ *
+ * @param value - String value from CLI
+ * @returns Validated positive integer
+ * @throws Error if value is invalid
+ */
+export function validateEmbedMaxBytes(value: string): number {
+  const parsed = parseInt(value, 10);
+  if (isNaN(parsed) || parsed <= 0) {
+    throw new Error(t('errors.invalidEmbedMaxBytes', { value }));
+  }
+  return parsed;
+}
+
+/**
+ * Safely create output directory
+ *
+ * @param outDir - Output directory path (should be validated first)
+ */
+export function ensureOutputDir(outDir: string): void {
+  try {
+    if (!fs.existsSync(outDir)) {
+      fs.mkdirSync(outDir, { recursive: true });
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(t('errors.createDirFailed', { path: outDir, error: message }));
+  }
+}
+
+/**
+ * Safely write file with error handling
+ *
+ * @param filePath - Full path to write
+ * @param content - Content to write
+ */
+export function safeWriteFile(filePath: string, content: string): void {
+  try {
+    fs.writeFileSync(filePath, content, 'utf8');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(t('errors.writeFileFailed', { path: filePath, error: message }));
+  }
+}

package/dist/monitor/data/connectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connectors.d.ts","sourceRoot":"","sources":["../../../src/monitor/data/connectors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAMrB,MAAM,aAAa,CAAC;AAOrB;;GAEG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CA8C1B;AAkWD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4BtC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CA8DzB"}
+{"version":3,"file":"connectors.d.ts","sourceRoot":"","sources":["../../../src/monitor/data/connectors.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAMrB,MAAM,aAAa,CAAC;AAOrB;;GAEG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAuD1B;AA2cD;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4BtC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CA8DzB"}