proofscan 0.2.0 → 0.3.1

package/README.md

@@ -10,7 +10,7 @@ proofscan provides visibility into MCP (Model Context Protocol) server communica
 - Captures all JSON-RPC messages (requests, responses, notifications)
 - Stores events in SQLite for efficient querying and analysis
 - Supports importing server configurations from mcp.so / Claude Desktop format
-- Manages session history with retention policies and archival
+- Provides intuitive CLI commands for viewing and exploring data
 
 ## Installation
 
@@ -24,122 +24,195 @@ Or run without installing:
 npx proofscan --help
 ```
 
-## CLI Commands
+## CLI Commands (v0.3.0)
 
 The CLI is available as both `pfscan` (short) and `proofscan` (full).
 
+### Command Structure (git-style)
+
+```
+Common Commands:
+  view, v       View recent events timeline (default)
+  tree, t       Show connector → session → rpc structure
+  explore, e    Interactive data browser
+  scan, s       Run a new scan
+  status, st    Show system status
+
+Management:
+  archive, a    Archive and prune old data
+  config, c     Configuration management
+  connectors    Connector management
+
+Shortcuts:
+  v=view  t=tree  e=explore  s=scan  st=status  a=archive  c=config
+```
+
+**Note:** Running `pfscan` without arguments is equivalent to `pfscan view`.
+
 ## Quickstart
 
 ### 1. Initialize Configuration
 
 ```bash
-# Create config in OS-standard location
 pfscan config init
-
-# Check where config is stored
-pfscan config path
+pfscan config path   # Show config location
 ```
 
-### 2. Import MCP Server from mcp.so / Claude Desktop
-
-Copy the `mcpServers` JSON from mcp.so or Claude Desktop settings and import via stdin:
+### 2. Import MCP Server
 
 ```bash
-# Full mcpServers format
-echo '{ "mcpServers": { "time": { "command": "uvx", "args": ["mcp-server-time"] } } }' | pfscan connectors import --from mcpServers --stdin
-
-# Or just the server definition (requires --name)
-echo '{ "command": "uvx", "args": ["mcp-server-time"] }' | pfscan connectors import --from mcpServers --stdin --name time
-
-# Import from file
-pfscan connectors import --from mcpServers --file ./servers.json
+# From mcp.so / Claude Desktop format
+echo '{"mcpServers":{"time":{"command":"uvx","args":["mcp-server-time"]}}}' \
+  | pfscan connectors import --from mcpServers --stdin
 ```
 
-### 3. List Connectors
+### 3. Scan and View
 
 ```bash
-pfscan connectors list
+pfscan scan start --id time   # Run scan
+pfscan                        # View recent events (same as pfscan view)
+pfscan tree                   # Show structure
+pfscan status                 # Show system status
 ```
 
-### 4. Scan a Connector
+## View Command (Phase 2.1)
+
+The `view` command displays a timeline of recent events with millisecond precision.
 
 ```bash
-pfscan scan start --id time
+$ pfscan view --limit 10
+Time         Sym Dir St Method                         Session      Extra
+-------------------------------------------------------------------------
+21:01:58.743 → → ✓ initialize                     ses=f2442c... lat=269ms size=183B
+21:01:59.018 ← ← ✓ initialize                     ses=f2442c...
+21:01:59.025 • →   notifications/initialized      ses=f2442c...
+21:01:59.037 → → ✓ tools/list                     ses=f2442c...
+21:01:59.049 ← ← ✓ tools/list                     ses=f2442c... lat=12ms size=1.0KB
 ```
 
-### 5. View Sessions and Events
+### View Options
 
 ```bash
-# List all sessions
-pfscan sessions list
+pfscan view --limit 50           # Show 50 events
+pfscan view --since 24h          # Events in last 24 hours
+pfscan view --since 7d           # Events in last 7 days
+pfscan view --errors             # Show only errors
+pfscan view --method tools       # Filter by method name
+pfscan view --connector time     # Filter by connector
+pfscan view --session abc123     # Filter by session (partial match)
+pfscan view --fulltime           # Show full timestamp (YYYY-MM-DD HH:MM:SS.mmm)
+pfscan view --with-sessions      # Include session start/end events
+pfscan view --json               # Output as JSON (EventLine array)
+```
 
-# Show session details
-pfscan sessions show --id <session_id>
+### Event Symbols
 
-# View recent events
-pfscan monitor tail --id time --last 20
-```
+| Symbol | Meaning |
+|--------|---------|
+| ▶ | Session start |
+| ■ | Session end |
+| → | Request (Client → Server) |
+| ← | Response (Server → Client) |
+| • | Notification |
+| ✖ | Error |
 
-## Commands
+## Tree Command (Phase 2.1)
 
-### Global Options
+The `tree` command shows a hierarchical view of connector → session → rpc.
 
-```
--c, --config <path>  Path to config file
---json               Output in JSON format
--v, --verbose        Verbose output
+```bash
+$ pfscan tree
+└── 📦 time
+    ├── 📋 f2442c9b... (2 rpcs, 8 events)
+    │   ├── ↔️ ✓ tools/list (id=2, 12ms)
+    │   └── ↔️ ✓ initialize (id=1, 269ms)
+    └── 📋 3cf5a66e... (2 rpcs, 8 events)
+        ├── ↔️ ✓ tools/list (id=2, 13ms)
+        └── ↔️ ✓ initialize (id=1, 271ms)
+
+1 connector(s), 2 session(s), 4 rpc(s)
 ```
 
-### Config
+### Tree Options
 
 ```bash
-pfscan config path                    # Show config file path
-pfscan config init [--force]          # Initialize config
-pfscan config show                    # Show config (secrets masked)
-pfscan config validate                # Validate config
+pfscan tree time              # Show specific connector
+pfscan tree --sessions 10     # Show 10 sessions per connector
+pfscan tree --rpc 20          # Show 20 RPCs per session
+pfscan tree --rpc-all         # Show all RPCs
+pfscan tree --method init     # Filter by method name
+pfscan tree --status ok       # Filter by status (ok, err, all)
+pfscan tree --compact         # Compact output (no icons)
+pfscan tree --since 24h       # Filter by time
+pfscan tree --json            # Output as JSON (TreeNode array)
 ```
 
-### Connectors
+## Explore Command (Phase 2.1)
+
+The `explore` command provides interactive navigation through data.
 
 ```bash
-pfscan connectors list                        # List all connectors
-pfscan connectors show --id <id>              # Show connector details
-pfscan connectors add --id <id> --stdio "cmd" # Add stdio connector
-pfscan connectors enable --id <id>            # Enable connector
-pfscan connectors disable --id <id>           # Disable connector
-pfscan connectors remove --id <id>            # Remove connector
+$ pfscan explore
+═══════════════════════════════════════════════════════════════
+  proofscan explore
+═══════════════════════════════════════════════════════════════
+  Path: connectors
+───────────────────────────────────────────────────────────────
 
-# Import from mcpServers format
-pfscan connectors import --from mcpServers --stdin
-pfscan connectors import --from mcpServers --file <path> [--name <id>]
-```
+  Connectors:
 
-### Scan
+    [1] time (3 sessions)
 
-```bash
-pfscan scan start --id <id> [--timeout <sec>]
+  > 1
 ```
 
-### Monitor
+### Explore Navigation
+
+- **Number**: Select item
+- **b**: Go back
+- **t**: Show tree view
+- **?**: Help
+- **q**: Quit
+- **p**: View request/response pair (in RPC view)
 
 ```bash
-pfscan monitor tail --id <id> [--last <N>]
+pfscan explore                    # Start from connectors
+pfscan explore --session abc123   # Jump to specific session
 ```
 
-### Sessions (Phase 2)
+## Status Command (Phase 2.1)
+
+The `status` command shows database and system status.
 
 ```bash
-pfscan sessions list [--connector <id>] [--limit <N>]   # List sessions
-pfscan sessions show --id <session_id>                   # Show session details
-pfscan sessions prune [--before <date>] [--keep-last <N>] [--yes]  # Prune old sessions
+$ pfscan status
+proofscan Status
+═════════════════════════════════════════════════════
+
+Configuration:
+  Config file:  /home/user/.config/proofscan/config.json
+  Data dir:     /home/user/.config/proofscan
+
+Database:
+  events.db:    72.0KB
+  proofs.db:    24.0KB
+  Schema ver:   1
+  Tables:       sessions, rpc_calls, events
+
+Data Summary:
+  Connectors:   1
+  Sessions:     3
+  RPC calls:    6
+  Events:       24
+  Latest:       2025-12-28T12:01:58.610Z
 ```
 
-### Archive (Phase 2)
+## Global Options
 
-```bash
-pfscan archive status                           # Show database status
-pfscan archive plan                             # Show what would be archived
-pfscan archive run [--yes] [--vacuum]           # Execute archive based on retention
+```
+-c, --config <path>  Path to config file
+--json               Output in JSON format
+-v, --verbose        Verbose output
 ```
 
 ## Config File Format
@@ -160,7 +233,7 @@ Config is stored in the OS-standard location:
       "transport": {
         "type": "stdio",
         "command": "uvx",
-        "args": ["mcp-server-time", "--local-timezone=America/New_York"]
+        "args": ["mcp-server-time"]
       }
     }
   ],
@@ -180,7 +253,7 @@ Config is stored in the OS-standard location:
 | `raw_days` | 7 | Clear raw JSON after N days |
 | `max_db_mb` | 500 | Target database size limit |
 
-## Data Storage (Phase 2)
+## Data Storage
 
 proofscan uses a 2-file SQLite structure:
 
@@ -191,244 +264,95 @@ proofscan uses a 2-file SQLite structure:
 └── proofs.db     # Immutable proof records (never pruned)
 ```
 
-### events.db Schema
-
-- **sessions**: Scan session records with connector, timestamps, exit status
-- **events**: Individual JSON-RPC messages with direction, kind, timestamps
-- **rpc_calls**: Request/response pairs with timing and success status
-
-### proofs.db Schema
-
-- **proofs**: Immutable proof records with hashes, references, and artifact URIs
-
-Sessions linked to proofs are automatically protected from pruning.
-
-## Example Session
+### EventLine Model (Phase 2.1)
+
+Internally, all events are normalized to the `EventLine` format:
+
+```typescript
+interface EventLine {
+  ts_ms: number;           // Timestamp (epoch ms)
+  kind: 'session_start' | 'session_end' | 'req' | 'res' | 'notify' | 'error';
+  direction?: '→' | '←';  // → = Client→Server, ← = Server→Client
+  label: string;           // Method name or event type
+  connector_id?: string;
+  session_id?: string;
+  rpc_id?: string | number;
+  status: 'OK' | 'ERR' | '-';
+  latency_ms?: number;
+  size_bytes?: number;
+  raw_json?: string;
+  meta?: Record<string, unknown>;
+}
+```
 
-```bash
-# Initialize
-$ pfscan config init
-✓ Config created at: /home/user/.config/proofscan/config.json
+This normalized model allows the schema to evolve without breaking the CLI.
 
-# Import a server
-$ echo '{"mcpServers":{"time":{"command":"uvx","args":["mcp-server-time"]}}}' \
-  | pfscan connectors import --from mcpServers --stdin
-✓ Imported 1 connector(s): time
-
-# List connectors
-$ pfscan connectors list
-ID    Enabled  Type   Command/URL
------------------------------------
-time  yes      stdio  uvx mcp-server-time
-
-# Scan the server
-$ pfscan scan start --id time
-Scanning connector: time...
-✓ Scan successful!
-  Connector: time
-  Session: dcaa519e-e14b-41ea-ac7c-7f2066cc8020
-  Tools found: 2
-  Tool names: get_current_time, convert_time
-  Events recorded: 8
-
-# List sessions
-$ pfscan sessions list
-Session ID   Connector  Started              Duration  Status  Events  Protected
---------------------------------------------------------------------------------
-dcaa519e...  time       2025/01/15 10:30:00  450ms     normal  8       no
-
-# Show session details
-$ pfscan sessions show --id dcaa519e-e14b-41ea-ac7c-7f2066cc8020
-Session: dcaa519e-e14b-41ea-ac7c-7f2066cc8020
-Connector: time
-Started: 2025/01/15 10:30:00
-Ended: 2025/01/15 10:30:00
-Duration: 450ms
-Status: normal
-Protected: no
-Events: 8
-RPC Calls: 2
-Proofs: 0
-
-RPC Calls:
-  ✓ initialize (id: 1)
-  ✓ tools/list (id: 2)
-
-# View events
-$ pfscan monitor tail --id time --last 5
-Recent events for 'time' (last 5):
-
-Time     Dir Status Kind         Summary
-----------------------------------------------------------------------
-10:30:01 → ✓ request      initialize
-10:30:01 ←   response
-10:30:01 →   notification  notifications/initialized
-10:30:01 → ✓ request      tools/list
-10:30:01 ←   response
-```
+## Archive Command
 
-## Archive Example (Phase 2)
+Archive and prune old data based on retention settings.
 
 ```bash
-# Check current database status
-$ pfscan archive status
-Database Status
-===============
-
-events.db size: 80.0 KB
-proofs.db size: 24.0 KB
-
-Total sessions: 6
-Protected sessions: 0
-Total proofs: 0
-raw_json storage: 4.8 KB
-
-# View archive plan (based on retention settings)
-$ pfscan archive plan
-Archive Plan
-============
-
-Retention Settings:
-  keep_last_sessions: 3
-  raw_days: 7
-  max_db_mb: 500
-
-Current Status:
-  events.db size: 80.0 KB
-  proofs.db size: 24.0 KB
-
-Planned Actions:
-
-  Sessions to delete: 3
-Session ID   Connector  Events  Reason
---------------------------------------------------------------
-c3f3ee9a...  time       8       Exceeds keep_last_sessions (3)
-050212d2...  time       8       Exceeds keep_last_sessions (3)
-dcaa519e...  time       8       Exceeds keep_last_sessions (3)
-
-  raw_json to clear: 0 events
-  Estimated savings: ~0.0 MB
-
-Run "pfscan archive run" to execute (or "pfscan archive run --yes" to confirm).
-
-# Dry run (shows what would happen)
-$ pfscan archive run
-Archive Run (DRY RUN)
-=====================
-
-Sessions to delete: 3
-raw_json to clear: 0 events
-Estimated savings: ~0.0 MB
-
-Run with --yes to actually execute.
-
-# Execute archive with vacuum
-$ pfscan archive run --yes --vacuum
-Archive Run Complete
-====================
-
-Sessions deleted: 3
-raw_json cleared: 0 events
-Database vacuumed
-
-Final events.db size: 72.0 KB
-✓ Archive complete
-
-# Verify sessions after archive
-$ pfscan sessions list
-Session ID   Connector  Started              Duration  Status  Events  Protected
---------------------------------------------------------------------------------
-f2442c9b...  time       2025/01/15 11:01:58  454ms     normal  8       no
-f641b379...  time       2025/01/15 11:01:58  467ms     normal  8       no
-3cf5a66e...  time       2025/01/15 11:01:57  449ms     normal  8       no
+pfscan archive status               # Show database status
+pfscan archive plan                 # Show what would be archived
+pfscan archive run                  # Dry run
+pfscan archive run --yes            # Actually execute
+pfscan archive run --yes --vacuum   # Execute and reclaim space
 ```
 
 ## JSON Output
 
-Add `--json` for machine-readable output:
+All commands support `--json` for machine-readable output:
 
 ```bash
-$ pfscan connectors list --json
+$ pfscan view --json --limit 3
 [
   {
-    "ID": "time",
-    "Enabled": "yes",
-    "Type": "stdio",
-    "Command/URL": "uvx mcp-server-time"
-  }
+    "ts_ms": 1766923317974,
+    "kind": "req",
+    "direction": "→",
+    "label": "tools/list",
+    "connector_id": "time",
+    "session_id": "3cf5a66e-...",
+    "rpc_id": "2",
+    "status": "OK",
+    "size_bytes": 58
+  },
+  ...
 ]
 
-$ pfscan scan start --id time --json
-{
-  "success": true,
-  "connector_id": "time",
-  "session_id": "dcaa519e-e14b-41ea-ac7c-7f2066cc8020",
-  "tools_count": 2,
-  "tools": ["get_current_time", "convert_time"],
-  "event_count": 8
-}
-
-$ pfscan archive status --json
-{
-  "events_db_size": 81920,
-  "proofs_db_size": 24576,
-  "total_sessions": 6,
-  "protected_sessions": 0,
-  "total_proofs": 0,
-  "raw_json_size": 4896
-}
-```
-
-## Supported mcpServers Input Formats
-
-proofscan accepts several JSON formats for import:
-
-### A) Full wrapper
-
-```json
-{
-  "mcpServers": {
-    "time": { "command": "uvx", "args": ["mcp-server-time"] }
+$ pfscan tree --json
+[
+  {
+    "type": "connector",
+    "id": "time",
+    "label": "time",
+    "meta": { "session_count": 3 },
+    "children": [...]
   }
-}
+]
 ```
 
-### B) Direct mcpServers object
-
-```json
-{
-  "time": { "command": "uvx", "args": ["mcp-server-time"] }
-}
-```
+## Connector Management
 
-### C) Single server definition (requires `--name`)
+```bash
+pfscan connectors list                        # List all
+pfscan connectors show --id <id>              # Show details
+pfscan connectors add --id <id> --stdio "cmd" # Add connector
+pfscan connectors enable --id <id>            # Enable
+pfscan connectors disable --id <id>           # Disable
+pfscan connectors remove --id <id>            # Remove
 
-```json
-{
-  "command": "uvx",
-  "args": ["mcp-server-time"]
-}
+# Import from mcpServers format
+pfscan connectors import --from mcpServers --stdin
+pfscan connectors import --from mcpServers --file <path>
 ```
 
-## Failure Handling
-
-Failures are always recorded as events. Even if a scan fails, you can inspect what happened:
+## Session Management
 
 ```bash
-$ pfscan scan start --id broken-server
-Scanning connector: broken-server...
-✗ Scan failed!
-  Connector: broken-server
-  Session: abc123...
-  Error: Initialize failed: Request timeout for method: initialize
-  Events recorded: 3
-
-$ pfscan monitor tail --id broken-server --last 5
-Time     Dir Status Kind         Summary
-----------------------------------------------------------------------
-10:35:01 →   transport    [connect_attempt]
-10:35:01 ←   transport    [connected]
-10:35:31 →   transport    [initialize_failed] Initialize failed: Request timeout...
+pfscan sessions list [--connector <id>] [--last <N>]
+pfscan sessions show --id <session_id>
+pfscan sessions prune [--before <date>] [--keep-last <N>] [--yes]
 ```
 
 ## Development

package/dist/analyzers/IAnalyzer.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Analyzer Interface
+ *
+ * Phase 2.1: Skeleton for event analysis hooks
+ * Full implementation in Phase 3
+ */
+import type { EventLine, EventLinePair } from '../eventline/types.js';
+/**
+ * Analysis result
+ */
+export interface AnalysisResult {
+    /** Analyzer identifier */
+    analyzer: string;
+    /** Analysis timestamp */
+    ts_ms: number;
+    /** Findings from analysis */
+    findings: AnalysisFinding[];
+    /** Statistics */
+    stats?: Record<string, unknown>;
+    /** Metadata */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Individual finding from analysis
+ */
+export interface AnalysisFinding {
+    /** Finding type */
+    type: 'info' | 'warning' | 'error' | 'suggestion';
+    /** Finding category */
+    category: string;
+    /** Human-readable message */
+    message: string;
+    /** Related event(s) */
+    events?: EventLine[];
+    /** Related pair(s) */
+    pairs?: EventLinePair[];
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Analyzer interface
+ *
+ * Analyzers process events and produce findings
+ */
+export interface IAnalyzer {
+    /** Analyzer name */
+    readonly name: string;
+    /** Analyzer version */
+    readonly version: string;
+    /** Description */
+    readonly description: string;
+    /**
+     * Analyze a batch of events
+     * @param events - Events to analyze
+     * @returns Analysis result
+     */
+    analyze(events: EventLine[]): Promise<AnalysisResult>;
+    /**
+     * Analyze RPC pairs
+     * @param pairs - RPC pairs to analyze
+     * @returns Analysis result
+     */
+    analyzePairs(pairs: EventLinePair[]): Promise<AnalysisResult>;
+}
+/**
+ * Analyzer registry
+ */
+export declare class AnalyzerRegistry {
+    private analyzers;
+    /**
+     * Register an analyzer
+     */
+    register(analyzer: IAnalyzer): void;
+    /**
+     * Get analyzer by name
+     */
+    get(name: string): IAnalyzer | undefined;
+    /**
+     * Get all registered analyzers
+     */
+    getAll(): IAnalyzer[];
+    /**
+     * Run all analyzers on events
+     */
+    analyzeAll(events: EventLine[]): Promise<AnalysisResult[]>;
+}
+//# sourceMappingURL=IAnalyzer.d.ts.map

package/dist/analyzers/IAnalyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAnalyzer.d.ts","sourceRoot":"","sources":["../../src/analyzers/IAnalyzer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IAEd,6BAA6B;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE5B,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,eAAe;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;IAElD,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IAEjB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAEhB,uBAAuB;IACvB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IAErB,sBAAsB;IACtB,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IAExB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uBAAuB;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,kBAAkB;IAClB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEtD;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC/D;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAqC;IAEtD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IAInC;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC;;OAEG;IACH,MAAM,IAAI,SAAS,EAAE;IAIrB;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CAejE"}