@syncause/debug-daemon 0.1.0

package/README.md

@@ -0,0 +1,258 @@
+# Syncause Debug Daemon
+
+The Syncause Project Debug Daemon (MCP Daemon) provides high-performance RPC services for runtime data collection, analysis, and debugging.
+
+## 🚀 Core Features
+
+### Multi-mode Transport Layer
+- **Local Mode**: Supports Windows named pipes and Unix domain sockets, providing ultra-low latency local communication.
+- **REMOTE Mode**: Supports standard HTTP protocol, facilitating cross-network or inter-container communication.
+
+### High-Performance Architecture
+- **Lightweight RPC Framework**: Based on JSON-RPC 2.0 protocol, supports request/response mode with built-in message framing.
+- **Multi-user Isolation**: Achieves multi-client isolation through `apiKey`, independently maintaining collection status and data storage.
+- **Smart Caching**: In-memory caching mechanism reduces disk I/O by 90%+, with batch writing optimization.
+- **Concurrency Safety**: Operation lock mechanism ensures safe concurrent writing, preventing data races.
+
+### Intelligent Data Processing
+- **LLM Integration**: Intelligent analysis and summary generation for runtime data.
+- **Dual-mode Search**: Supports Vector Embedding and Fuzzy Match.
+- **Automatic Polling**: Global polling mechanism synchronizes application runtime data in real-time.
+
+### Robustness Guarantee
+- **Graceful Shutdown**: Comprehensive signal handling automatically cleans up resources and persists data.
+- **Auto Shutdown**: Intelligently monitors activity status, automatically shutting down after idle time to save resources.
+- **Structured Logging**: Tiered logging support with file rotation.
+- **Configuration Management**: Unified environment variable configuration, supporting runtime tuning.
+
+## 📦 Quick Start
+
+### Prerequisites
+- Node.js 20.x or higher
+- npm or yarn
+
+### Install Dependencies
+```bash
+npm install
+```
+
+### Build Project
+```bash
+# TypeScript compilation
+npm run build
+
+# Or use esbuild for high-speed bundling
+npm run bundle
+```
+
+### Global Installation (Optional)
+```bash
+npm install -g .
+```
+
+### Start Service
+
+**Development Mode** (PowerShell):
+```powershell
+$env:MODE = "local"
+$env:LOG_TO_CONSOLE = "true"
+$env:LOG_LEVEL = "debug"
+npx tsx src/index.ts
+```
+
+**Development Mode** (Bash):
+```bash
+MODE=local LOG_TO_CONSOLE=true LOG_LEVEL=debug npx tsx src/index.ts
+```
+
+**Production Mode**:
+```bash
+node dist/index.js
+```
+
+**Run after Global Installation**:
+```bash
+syncause-debug-daemon
+```
+
+## ⚙️ Configuration Guide
+
+All configuration items can be customized via environment variables or command-line arguments.
+**Priority**: Command Line Arguments > Environment Variables > Defaults.
+
+Command-line arguments support `--KEY=VALUE` or `--key value` formats (case-insensitive).
+For example, `HTTP_PORT` can be specified via `--HTTP_PORT=9090` or `--http_port 9090`.
+
+### Server Configuration
+
+| Variable Name | Description | Default | Note |
+| :--- | :--- | :--- | :--- |
+| `MODE` | Server running mode | `local` | `local` or `remote` |
+| `AUTO_SHUTDOWN_MINUTES` | Idle auto-shutdown time | `5` | Unit: minutes. Automatically shuts down if no request (including ping) is received within this time. Set to `0` to disable. |
+| `HTTP_PORT` | HTTP mode listening port | `8080` | Valid only in HTTP mode |
+
+### Log Configuration
+
+| Variable Name | Description | Default | Options |
+| :--- | :--- | :--- | :--- |
+| `LOG_LEVEL` | Log level | `info` | `debug`, `info`, `warn`, `error` |
+| `LOG_TO_CONSOLE` | Console output | `false` | `true`, `false` |
+
+### Storage Configuration
+
+| Variable Name | Description | Default | Note |
+| :--- | :--- | :--- | :--- |
+| `STORAGE_PERSIST_INTERVAL` | Persistence check interval | `5000` | Unit: milliseconds |
+| `STORAGE_MAX_TRACES_PER_APP` | Max traces per app | `250` | Retains latest records if exceeded |
+
+### Service Configuration
+
+| Variable Name | Description | Default | Note |
+| :--- | :--- | :--- | :--- |
+| `SERVICE_PROXY_URL` | API proxy URL | `https://api.syn-cause.com/codeproxy` | Used to retrieve app and trace data |
+| `SERVICE_POLLING_INTERVAL` | Polling interval | `10000` | Unit: milliseconds |
+
+### Configuration Examples
+
+#### Via Environment Variables
+
+```powershell
+# Windows PowerShell
+$env:MODE = "local"
+$env:LOG_TO_CONSOLE = "true"
+$env:LOG_LEVEL = "debug"
+$env:SERVICE_PROXY_URL = "http://192.168.1.6:32220"
+npx tsx src/index.ts
+```
+
+```bash
+# Linux/macOS Bash
+MODE=local LOG_TO_CONSOLE=true LOG_LEVEL=debug \
+SERVICE_PROXY_URL=http://192.168.1.6:32220 \
+npx tsx src/index.ts
+```
+
+#### Via Command Line Arguments
+
+```bash
+# Cross-platform
+npx tsx src/index.ts \
+  --mode local \
+  --log_to_console true \
+  --log_level debug \
+  --service_proxy_url http://192.168.1.6:32220
+```
+
+## 📂 Project Structure
+
+```text
+src/
+├── common/          # Common protocols and utilities
+│   ├── common.ts    # Common constants and utility functions
+│   ├── framing.ts   # Message framing processing
+│   ├── protocol.ts  # RPC protocol definitions
+│   └── version.ts   # Version information
+├── config/          # Unified configuration management
+│   └── index.ts     # Configuration loading and management
+├── core/            # Core business logic layer
+│   ├── api/         # External service integration (LLM, Embedding)
+│   ├── logger/      # Structured logging system
+│   ├── services/    # Business services (Multi-user management, data collection)
+│   ├── storage/     # Storage persistence (Disk I/O, cache management)
+│   └── utils/       # Utility classes (Tree building, similarity calculation, search strategies)
+├── rpc/             # RPC protocol implementation
+│   ├── handler/     # RPC method handlers
+│   ├── server.ts    # RPC core server
+│   └── utils/       # RPC utility functions
+└── transport/       # Transport layer implementation
+    └── server/      # Local and HTTP server implementations
+        ├── baseServer.ts  # Base server abstract class
+        ├── http.ts        # HTTP server implementation
+        └── local.ts       # Local server implementation (Named pipes/Domain sockets)
+```
+
+## 📡 RPC Interfaces
+
+### Core Interfaces
+
+#### `ping`
+Client heartbeat detection and registration.
+- **Parameters**:
+  - `meta.apiKey` - User identifier
+
+#### `get_runtime_facts`
+Query application runtime data.
+- **Parameters**:
+  - `meta.apiKey` - User identifier
+  - `projectId` - Project ID
+  - `searchText` - Search keywords (optional)
+  - `matchMode` - Match mode: `embedding` or `fuzzy`
+
+#### `search_debug_traces`
+AI intelligent troubleshooting.
+- **Parameters**:
+  - `meta.apiKey` - User identifier
+  - `projectId` - Project ID
+  - `query` - Problem description
+  - `limit` - Number of results to return
+
+### Advanced Interfaces
+
+#### `get_trace_insight`
+Get complete request lifecycle report.
+- **Parameters**:
+  - `meta.apiKey` - User identifier
+  - `projectId` - Project ID
+  - `traceId` - Trace ID
+
+#### `inspect_method_snapshot`
+Method-level deep analysis.
+- **Parameters**:
+  - `meta.apiKey` - User identifier
+  - `projectId` - Project ID
+  - `traceId` - Trace ID
+  - `className` - Class name
+  - `methodName` - Method name
+  - `includeSubCalls` - Whether to include sub-calls
+
+#### `diff_trace_execution`
+Comparative analysis of two request executions.
+- **Parameters**:
+  - `meta.apiKey` - User identifier
+  - `projectId` - Project ID
+  - `baseTraceId` - Trace ID for the failure case
+  - `compareTraceId` - Trace ID for the reference case (optional)
+
+## 🛡️ Operations Guide
+
+### Graceful Shutdown
+
+When receiving `Ctrl+C` (SIGINT) or `SIGTERM` signals, the daemon will:
+
+1. Stop global polling timers.
+2. Persist all cached data to disk.
+3. Close all active connections.
+4. Flush log buffers.
+5. Initiate a 10-second timeout protection to ensure process termination.
+
+### Log Locations
+
+Log files are named by PID and stored in:
+
+- **Windows**: `%APPDATA%\syncause-debug\logs\`
+- **Linux**: `~/.local/share/syncause-debug/logs/`
+- **macOS**: `~/Library/Application Support/syncause-debug/logs/`
+
+### Dependencies
+
+Main dependencies:
+- `openai`: OpenAI API client for LLM integration.
+- `winston`: Structured logging system.
+- `uuid`: Unique identifier generation.
+- `p-limit`: Concurrency control.
+
+Development dependencies:
+- `typescript`: TypeScript compiler.
+- `esbuild`: High-speed bundling tool.
+- `tsx`: TypeScript execution tool.
+- `@types/*`: TypeScript type definitions.