proofscan 0.1.1 → 0.3.0

package/README.md

@@ -8,8 +8,9 @@ proofscan provides visibility into MCP (Model Context Protocol) server communica
 
 - Connects to MCP servers via stdio transport
 - Captures all JSON-RPC messages (requests, responses, notifications)
-- Stores events in JSONL format for later analysis
+- Stores events in SQLite for efficient querying and analysis
 - Supports importing server configurations from mcp.so / Claude Desktop format
+- Provides intuitive CLI commands for viewing and exploring data
 
 ## Installation
 
@@ -23,99 +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 Events
+### View Options
 
 ```bash
-pfscan monitor tail --id time --last 20
+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)
 ```
 
-## Commands
+### Event Symbols
 
-### Global Options
+| Symbol | Meaning |
+|--------|---------|
+| ▶ | Session start |
+| ■ | Session end |
+| → | Request (Client → Server) |
+| ← | Response (Server → Client) |
+| • | Notification |
+| ✖ | Error |
 
-```
--c, --config <path>  Path to config file
---json               Output in JSON format
--v, --verbose        Verbose output
+## Tree Command (Phase 2.1)
+
+The `tree` command shows a hierarchical view of connector → session → rpc.
+
+```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:
+
+    [1] time (3 sessions)
+
+  > 1
 ```
 
-### Scan
+### 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 scan start --id <id> [--timeout <sec>]
+pfscan explore                    # Start from connectors
+pfscan explore --session abc123   # Jump to specific session
 ```
 
-### Monitor
+## Status Command (Phase 2.1)
+
+The `status` command shows database and system status.
 
 ```bash
-pfscan monitor tail --id <id> [--last <N>]
+$ 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
+```
+
+## Global Options
+
+```
+-c, --config <path>  Path to config file
+--json               Output in JSON format
+-v, --verbose        Verbose output
 ```
 
 ## Config File Format
@@ -136,151 +233,126 @@ 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"]
       }
     }
-  ]
+  ],
+  "retention": {
+    "keep_last_sessions": 50,
+    "raw_days": 7,
+    "max_db_mb": 500
+  }
 }
 ```
 
-## Event Storage
+### Retention Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `keep_last_sessions` | 50 | Keep last N sessions per connector |
+| `raw_days` | 7 | Clear raw JSON after N days |
+| `max_db_mb` | 500 | Target database size limit |
 
-Events are stored in JSONL format:
+## Data Storage
+
+proofscan uses a 2-file SQLite structure:
 
 ```
-~/.config/proofscan/events/<connector_id>/<YYYYMMDD>.jsonl
+~/.config/proofscan/
+├── config.json
+├── events.db     # Sessions, events, RPC calls (can be pruned)
+└── proofs.db     # Immutable proof records (never pruned)
 ```
 
-Each event contains:
-
-```json
-{
-  "event_id": "uuid",
-  "ts": "2024-01-15T10:30:00.000Z",
-  "connector_id": "time",
-  "direction": "client_to_server",
-  "kind": "request",
-  "method": "tools/list",
-  "rpc_id": 1,
-  "ok": true,
-  "raw": "{...}"
+### 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>;
 }
 ```
 
-## Example Session
+This normalized model allows the schema to evolve without breaking the CLI.
 
-```bash
-# Initialize
-$ pfscan config init
-✓ Config created at: /home/user/.config/proofscan/config.json
+## Archive Command
 
-# 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
-  Tools found: 1
-  Tool names: get_current_time
-  Events recorded: 8
-
-# 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 and prune old data based on retention settings.
+
+```bash
+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",
-  "tools_count": 1,
-  "tools": ["get_current_time"],
-  "event_count": 8
-}
-```
-
-## 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
+## Connector Management
 
-```json
-{
-  "time": { "command": "uvx", "args": ["mcp-server-time"] }
-}
-```
-
-### 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
-  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"}

package/dist/cli.js

@@ -1,25 +1,60 @@
 #!/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
  */
 import { Command } from 'commander';
 import { resolveConfigPath } from './utils/config-path.js';
 import { setOutputOptions } from './utils/output.js';
-import { createConfigCommand, createConnectorsCommand, createScanCommand, createMonitorCommand, } from './commands/index.js';
+import { createConfigCommand, createConnectorsCommand, createScanCommand, createMonitorCommand, createSessionsCommand, createArchiveCommand, createViewCommand, createTreeCommand, createExploreCommand, createStatusCommand, } from './commands/index.js';
 const program = new Command();
 // Global state for config path
 let globalConfigPath;
 function getConfigPath() {
     return resolveConfigPath({ configPath: globalConfigPath });
 }
+// Custom help formatting
+const HELP_HEADER = `
+proofscan - MCP Server scanner
+Eliminate black boxes by capturing JSON-RPC communication.
+
+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
+`;
 program
     .name('pfscan')
-    .description('MCP Server scanner - eliminate black boxes by capturing JSON-RPC from connection to tools/list')
-    .version('0.1.1')
+    .description('MCP Server scanner - eliminate black boxes by capturing JSON-RPC')
+    .version('0.3.0')
     .option('-c, --config <path>', 'Path to config file')
     .option('--json', 'Output in JSON format')
     .option('-v, --verbose', 'Verbose output')
+    .addHelpText('before', HELP_HEADER)
     .hook('preAction', (thisCommand) => {
     const opts = thisCommand.opts();
     globalConfigPath = opts.config;
@@ -28,11 +63,98 @@ program
         verbose: opts.verbose,
     });
 });
-// Add subcommands
-program.addCommand(createConfigCommand(getConfigPath));
+// ============================================================
+// Primary commands (Phase 2.1 - git style)
+// ============================================================
+// view (default command)
+const viewCmd = createViewCommand(getConfigPath);
+program.addCommand(viewCmd);
+// Alias: v = view
+const vCmd = createViewCommand(getConfigPath);
+vCmd.name('v').description('Alias for view');
+program.addCommand(vCmd);
+// tree
+const treeCmd = createTreeCommand(getConfigPath);
+program.addCommand(treeCmd);
+// Alias: t = tree
+const tCmd = createTreeCommand(getConfigPath);
+tCmd.name('t').description('Alias for tree');
+program.addCommand(tCmd);
+// explore
+const exploreCmd = createExploreCommand(getConfigPath);
+program.addCommand(exploreCmd);
+// Alias: e = explore
+const eCmd = createExploreCommand(getConfigPath);
+eCmd.name('e').description('Alias for explore');
+program.addCommand(eCmd);
+// status
+const statusCmd = createStatusCommand(getConfigPath);
+program.addCommand(statusCmd);
+// Alias: st = status
+const stCmd = createStatusCommand(getConfigPath);
+stCmd.name('st').description('Alias for status');
+program.addCommand(stCmd);
+// ============================================================
+// Existing commands (maintained for compatibility)
+// ============================================================
+// scan
+const scanCmd = createScanCommand(getConfigPath);
+program.addCommand(scanCmd);
+// Alias: s = scan
+const sCmd = createScanCommand(getConfigPath);
+sCmd.name('s').description('Alias for scan');
+program.addCommand(sCmd);
+// archive
+const archiveCmd = createArchiveCommand(getConfigPath);
+program.addCommand(archiveCmd);
+// Alias: a = archive
+const aCmd = createArchiveCommand(getConfigPath);
+aCmd.name('a').description('Alias for archive');
+program.addCommand(aCmd);
+// config
+const configCmd = createConfigCommand(getConfigPath);
+program.addCommand(configCmd);
+// Alias: c = config
+const cCmd = createConfigCommand(getConfigPath);
+cCmd.name('c').description('Alias for config');
+program.addCommand(cCmd);
+// connectors (no short alias - too long)
 program.addCommand(createConnectorsCommand(getConfigPath));
-program.addCommand(createScanCommand(getConfigPath));
+// sessions (kept for compatibility, but sessions list → view --with-sessions)
+program.addCommand(createSessionsCommand(getConfigPath));
+// monitor (kept for compatibility, but monitor tail → view)
 program.addCommand(createMonitorCommand(getConfigPath));
+// ============================================================
+// Default action: pfscan → pfscan view
+// ============================================================
+// Check if no subcommand is provided (only options like --config, --json)
+function hasSubcommand() {
+    const knownCommands = new Set([
+        'view', 'v', 'tree', 't', 'explore', 'e', 'status', 'st',
+        'scan', 's', 'archive', 'a', 'config', 'c',
+        'connectors', 'sessions', 'monitor', 'help'
+    ]);
+    for (let i = 2; i < process.argv.length; i++) {
+        const arg = process.argv[i];
+        // Skip option flags and their values
+        if (arg.startsWith('-')) {
+            // If it's --config, skip the next arg too
+            if (arg === '-c' || arg === '--config') {
+                i++;
+            }
+            continue;
+        }
+        // This is a positional argument - check if it's a command
+        if (knownCommands.has(arg)) {
+            return true;
+        }
+    }
+    return false;
+}
+// If no subcommand, insert 'view' right after program name (before any options)
+if (!hasSubcommand()) {
+    process.argv.splice(2, 0, 'view');
+}
 // Parse and run
 program.parse();
 //# sourceMappingURL=cli.js.map