proofscan 0.2.0 → 0.3.0

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/cli.d.ts

@@ -1,7 +1,21 @@
 #!/usr/bin/env node
 /**
- * proofscan CLI
+ * proofscan CLI - Phase 2.1
  * MCP Server scanner - eliminate black boxes
+ *
+ * Command structure (git-style flat):
+ *   pfscan view        # View events (default)
+ *   pfscan tree        # Structure overview
+ *   pfscan explore     # Interactive browse
+ *   pfscan scan        # Run scan
+ *   pfscan status      # System status
+ *   pfscan archive     # Archive/prune data
+ *   pfscan config      # Configuration
+ *   pfscan connectors  # Connector management
+ *
+ * Shortcuts:
+ *   v = view, t = tree, e = explore, s = scan
+ *   st = status, a = archive, c = config
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}