Add logs command to show and follow bridge log files

[jancurn]

Summary

Fixes #205

Adds a new mcpc @<session> logs command that allows users to view and follow bridge log files for MCP sessions. The implementation includes a log reader library with support for log file rotation, timestamp filtering, and live tailing.

Key Changes

• New log reader library (src/lib/log-reader.ts):

  • parseLogLine(): Parses structured log records from raw lines with ISO timestamps, log levels, and optional context tags
  • listLogFiles(): Discovers and orders rotated log files (.log.5 → .log.1 → .log)
  • readRecentLogLines(): Reads recent logs with support for --tail (limit lines) and --since (timestamp filtering)
  • followLog(): Live-follows the current log file with rotation detection and belt-and-suspenders polling for filesystem reliability
  • parseDuration() and resolveSince(): Parse duration shorthand (30s, 5m, 2h, 1d, 1w) and ISO timestamps for the --since option

• New logs command (src/cli/commands/logs.ts):

  • Implements mcpc @<session> logs with options:
    • -n/--tail <n>: Show last N lines (default: 100)
    • --follow: Stream new lines as they arrive (Ctrl+C to stop)
    • --since <value>: Filter by duration or ISO timestamp
  • Supports both human-readable and JSON output modes
  • JSON mode uses NDJSON (one record per line) when streaming with --follow
  • Displays informative headers with file count, size, and filtering details

• Integration:

  • Wired into CLI parser and shell command executor
  • Updated help text and README with usage examples
  • Added unit tests covering parsing, duration resolution, file listing, and filtering

Notable Implementation Details

• Log file rotation is detected by inode changes or size shrinkage, with automatic reset to the start of the new file
• Unparseable lines (banners, stack traces) are preserved when filtering by --since
• The followLog() function uses both fs.watch() and a 1-second polling interval for robustness across different filesystems (NFS, network mounts)
• Backlog is read from disk before following begins, allowing callers to control history depth
• Signal handlers (SIGINT/SIGTERM) gracefully drain pending data before exit

https://claude.ai/code/session_01C8o7VrBnDQfQ3QywPe5tMm