claw-dashboard 1.9.0 → 2.1.0

package/.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,150 @@
+# External Integrations
+
+**Analysis Date:** 2026-02-28
+
+## APIs & External Services
+
+**OpenClaw Gateway (Primary Integration):**
+- Default endpoint: localhost:18789
+- Protocol: HTTPS with optional token authentication
+- Endpoints queried:
+  - `/api/sessions` - Active session list
+  - `/api/agents` - Available agents
+  - `/api/logs` - Log entries
+- File: `src/gateway-manager.js`
+
+**System Information (systeminformation library):**
+- CPU: load, usage, temperature
+- Memory: total, used, free, swap
+- GPU: NVIDIA (nvidia-smi), AMD (radeontop), Intel, WSL
+- Network: interfaces, speed, stats
+- Disk: filesystems, IO, usage
+- OS: uptime, hostname, platform
+- File: Uses `systeminformation` npm package
+
+**No External Cloud Services:**
+- No telemetry or analytics services
+- No external logging services
+- No cloud-based configuration
+
+## Data Storage
+
+**Local SQLite Database:**
+- Library: sql.js (WebAssembly SQLite)
+- Path: `~/.openclaw/dashboard-history.db`
+- Tables: session_snapshots, cpu_metrics, memory_metrics, network_metrics
+- File: `src/database.js`
+
+**JSON Configuration:**
+- Settings: `~/.openclaw/dashboard-settings.json`
+- Persistent state across restarts
+- File: `src/config.js`, `src/validation.js`
+
+**File Storage:**
+- Local filesystem only
+- Export directory: `~/.openclaw/exports/`
+- Plugin directory: `~/.openclaw/plugins/`
+
+**Caching:**
+- In-memory cache with TTL
+- Categories: cpu, memory, gpu, network, disk, system, container
+- File: `src/cache.js`
+
+## Authentication & Identity
+
+**Gateway Authentication:**
+- Token-based (optional per endpoint)
+- Header: Authorization Bearer token
+- File: `src/gateway-manager.js`
+
+**Web Interface Auth (Optional):**
+- API key authentication (disabled by default)
+- Key format: `cd_[a-zA-Z0-9]{32}`
+- Max 10 keys, hashed in storage
+- File: `src/web-server.js`
+
+**File Permissions:**
+- Settings/database: 0600 (owner read/write only)
+- File: `src/security.js`
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Custom error classes (DashboardError hierarchy)
+- Centralized error handling in widgets
+- Plugin error boundary with isolation
+- File: `src/errors.js`, `src/plugin-errors.js`, `src/widgets/widget-error-boundary.js`
+
+**Logging:**
+- Local log file: `~/.openclaw/claw-dashboard.log`
+- Logger: `src/logger.js`
+- Levels: error, warn, info, debug
+- Console output during development
+
+**Performance Monitoring:**
+- Worker pool metrics
+- Memory pressure detection
+- Widget render timing
+- File: `src/performance-monitor.js`, `src/memory-pressure.js`
+
+## Web Interface
+
+**Embedded Web Server:**
+- Disabled by default
+- Port: 18790 (configurable)
+- Rate limiting: 100 requests/minute per IP
+- CORS: configurable (wildcard in development)
+- Endpoints:
+  - GET /health
+  - GET /metrics
+  - GET /sessions
+  - GET /agents
+  - GET /logs
+  - GET /status
+- File: `src/web-server.js`
+
+## CI/CD & Deployment
+
+**CI Pipeline:**
+- GitHub Actions configured (`.github/workflows/`)
+- Jest tests with coverage
+- Docker support (Dockerfile, docker-compose.yml)
+
+**Installation:**
+- npm global install: `npm install -g claw-dashboard`
+- Binary: `clawdash`
+- Manual install script: `install.sh`
+
+## Environment Configuration
+
+**Required env vars:**
+- None (all have defaults)
+
+**Optional env vars:**
+- `HOME` - Used for path expansion
+- `DARK_MODE` - Theme override
+- `THEME` - Theme override
+- `COLORFGBG` - Terminal background detection
+
+**Secrets location:**
+- Settings file (~/.openclaw/dashboard-settings.json)
+- Database file (~/.openclaw/dashboard-history.db)
+- API keys hashed before storage
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- None
+
+**Outgoing:**
+- None
+
+**Plugin System:**
+- Plugins loaded from filesystem
+- Hot-reload support via file watcher
+- Extension points for custom functionality
+- File: `src/widgets/widget-loader.js`, `src/widgets/plugin-api.js`
+
+---
+
+*Integration audit: 2026-02-28*

package/.planning/codebase/STACK.md

@@ -0,0 +1,122 @@
+# Technology Stack
+
+**Analysis Date:** 2026-02-28
+
+## Languages
+
+**Primary:**
+- JavaScript (ES2022) - All source code
+- TypeScript definitions (types.d.ts) - Type definitions for IDE support
+
+## Runtime
+
+**Environment:**
+- Node.js >= 18 (required)
+- ES Modules (`"type": "module"` in package.json)
+
+**Package Manager:**
+- npm (lockfile present: package-lock.json)
+
+## Frameworks & Libraries
+
+**Core Runtime:**
+- `blessed` ^0.1.81 - Terminal UI framework (blessed curses-like library)
+- `blessed-contrib` ^4.11.0 - Charts and widgets for blessed
+- `chalk` ^5.3.0 - Terminal string styling
+- `systeminformation` ^5.21.22 - System information gathering (CPU, memory, network, disk, GPU)
+- `sql.js` ^1.14.0 - SQLite compiled to WebAssembly for in-process database
+- `timeout-cli` ^0.3.2 - Command timeout utilities
+
+**Build System:**
+- `esbuild` ^0.25.12 - Fast bundler for CJS builds
+- Dual-package: ESM (primary) + CJS (built via build-cjs.js)
+
+**Testing:**
+- `jest` ^30.2.0 - Test framework (run with --experimental-vm-modules)
+- No additional assertion library (uses Jest built-in)
+
+**Linting:**
+- `eslint` ^10.0.2 - Linting with @eslint/js recommended config
+- Uses flat config (eslint.config.js)
+
+## Key Dependencies
+
+**Critical:**
+- `blessed` + `blessed-contrib` - Terminal UI framework (core dependency)
+- `systeminformation` - All system metrics (CPU, memory, GPU, network, disk)
+- `sql.js` - SQLite WASM for historical data persistence
+
+**Infrastructure:**
+- `chalk` - Terminal styling
+- `worker_threads` (Node.js built-in) - Worker pool for heavy operations
+- `https`/`http` (Node.js built-in) - Gateway API communication
+
+## Configuration
+
+**Environment:**
+- Settings stored in: `~/.openclaw/dashboard-settings.json`
+- Database stored in: `~/.openclaw/dashboard-history.db`
+- Plugins loaded from: `~/.openclaw/plugins/`
+- Log file: `~/.openclaw/claw-dashboard.log`
+
+**Build:**
+- esbuild.config.js - ESM build configuration
+- build-cjs.js - CJS bundle generation (creates index.cjs, dist/widgets.cjs)
+- cjs-shim.js - Provides import.meta.url polyfill for CJS
+
+**Package Exports:**
+```json
+{
+  ".": {
+    "import": "./index.js",
+    "require": "./index.cjs"
+  },
+  "./widgets": {
+    "import": "./src/widgets/index.js",
+    "require": "./dist/widgets.cjs"
+  }
+}
+```
+
+## Platform Requirements
+
+**Development:**
+- Node.js >= 18
+- npm for dependency management
+- macOS/Linux/Windows (some system features macOS-specific)
+
+**Production:**
+- Node.js runtime
+- No external services required (self-contained)
+- Optional: OpenClaw gateway endpoint on localhost:18789
+
+## Module System
+
+**Primary:** ES Modules (ESM) with `.js` extension
+**Dual Package:** CJS builds for compatibility
+**Worker Threads:** Separate worker files in `src/workers/`
+
+**Import Patterns:**
+```javascript
+// ESM imports throughout
+import blessed from 'blessed';
+import { BaseWidget } from './plugin-api.js';
+import config, { DEFAULT_SETTINGS } from './config.js';
+```
+
+## Database
+
+**Type:** SQLite via sql.js (WebAssembly)
+**Location:** `~/.openclaw/dashboard-history.db`
+**Tables:**
+- `session_snapshots` - Agent session data
+- `cpu_metrics` - CPU usage history
+- `memory_metrics` - Memory usage history
+- `network_metrics` - Network usage history
+
+**Save Interval:** 30 seconds
+**Cleanup Interval:** 1 hour (with retention policy)
+
+---
+
+*Stack analysis: 2026-02-28*

package/.planning/codebase/STRUCTURE.md

@@ -0,0 +1,201 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-02-28
+
+## Directory Layout
+
+```
+/Users/kdsmith/.openclaw/workspace/claw-dashboard/
+├── index.js                    # Main entry point (blessed TUI)
+├── index.cjs                   # CJS build output
+├── src/                        # Core source code
+│   ├── widgets/                # Widget system (plugins + built-in)
+│   ├── workers/                # Worker thread pool
+│   ├── cli/                    # CLI command handlers
+│   ├── *.js                    # Core modules (config, themes, etc.)
+├── tests/                      # Jest test suites (375 tests)
+├── examples/                   # Example plugins
+│   └── plugins/                # Widget plugin examples
+├── docs/                       # Documentation
+├── schemas/                    # JSON schemas
+├── dist/                       # CJS build output
+├── scripts/                    # Build/release scripts
+├── man/                        # Man pages
+├── build-cjs.js                # CJS build script
+├── esbuild.config.js           # ESM build config
+├── jest.config.js              # Test configuration
+├── eslint.config.js            # Lint configuration
+├── package.json                # Package manifest (ESM + CJS dual)
+└── README.md, CHANGELOG.md     # Documentation
+```
+
+## Directory Purposes
+
+**`src/` - Core Source:**
+- Purpose: All application logic
+- Contains: 35 JavaScript modules, organized by function
+- Key files:
+  - `index.js` - Main entry
+  - `config.js` - Centralized constants
+  - `themes.js` - Theme management
+  - `gateway-manager.js` - Gateway communication
+  - `database.js` - SQLite persistence
+
+**`src/widgets/` - Widget System:**
+- Purpose: Plugin architecture and built-in widgets
+- Contains: 10 files, ~14k total lines
+- Key files:
+  - `plugin-api.js` - BaseWidget and PluginAPI classes
+  - `widget-loader.js` - Lazy loading, hot-reload, registry
+  - `builtin-widgets.js` - 10 built-in widget classes
+  - `dependency-resolver.js` - Widget dependency resolution
+  - `widget-error-boundary.js` - Error isolation
+  - `config-processor.js` - Config with env interpolation
+
+**`src/workers/` - Worker Pool:**
+- Purpose: Thread pool for heavy system operations
+- Contains: 2 files
+- Files:
+  - `worker-pool.js` - Pool management (874 lines)
+  - `system-worker.js` - Worker thread code (3k lines)
+
+**`src/cli/` - CLI Commands:**
+- Purpose: Command-line argument parsing and commands
+- Contains: 6 files
+- Files:
+  - `index.js` - Centralized exports
+  - `args.js` - Argument parsing
+  - `help.js` - Help text
+  - `validate-plugin.js` - Plugin validation CLI
+  - `validate-config.js` - Config validation CLI
+
+**`tests/` - Test Suites:**
+- Purpose: Jest test coverage
+- Contains: 32 test files, 375 total tests
+- Key files:
+  - `integration.test.js` - Multi-module integration
+  - `widget-*.test.js` - Widget system tests
+  - `example-plugins.test.js` - Plugin tests
+
+**`examples/plugins/` - Example Plugins:**
+- Purpose: Reference implementations for plugin developers
+- Contains: 4 example widgets
+- Plugins:
+  - `hello-world/` - Minimal widget example
+  - `api-status/` - API polling widget
+  - `system-metrics-chart/` - Chart widget example
+  - `weather-widget/` - External API widget
+
+**`docs/` - Documentation:**
+- Purpose: User and developer documentation
+- Contains: PLUGINS.md, API.md
+
+**`schemas/` - JSON Schemas:**
+- Purpose: Validation schemas
+- Contains: Plugin manifest schema
+
+## Key File Locations
+
+**Entry Points:**
+- `index.js` - Main application entry (blessed TUI)
+- `src/workers/system-worker.js` - Worker thread entry
+- `src/cli/index.js` - CLI exports
+
+**Configuration:**
+- `src/config.js` - Centralized constants and defaults
+- `src/config-validator.js` - Runtime config validation
+- `src/validation.js` - Input validation
+- `jest.config.js` - Test config
+- `eslint.config.js` - Lint config
+
+**Core Logic:**
+- `src/gateway-manager.js` - Gateway communication
+- `src/database.js` - SQLite persistence
+- `src/cache.js` - In-memory caching
+- `src/themes.js` - Theme management
+- `src/alerts.js` - Rate limiting and alerts
+
+**Widget System:**
+- `src/widgets/plugin-api.js` - BaseWidget, PluginAPI
+- `src/widgets/widget-loader.js` - Lazy loading
+- `src/widgets/builtin-widgets.js` - Built-in widgets
+- `src/widgets/index.js` - Widget system exports
+
+**Build System:**
+- `build-cjs.js` - CJS bundle generation
+- `esbuild.config.js` - ESM build configuration
+- `cjs-shim.js` - import.meta.url polyfill
+
+## Naming Conventions
+
+**Files:**
+- Kebab-case: `widget-loader.js`, `builtin-widgets.js`
+- Extensions: `.js` for source, `.test.js` for tests
+
+**Directories:**
+- Kebab-case: `widget-error-boundary.js` directory would be `widget-error-boundary/`
+- Singular nouns except workers/ (plural by convention)
+
+**Classes:**
+- PascalCase: `BaseWidget`, `WidgetLoader`, `PluginAPI`
+- Suffix pattern: `*Widget`, `*Manager`, `*Error`
+
+**Functions/Methods:**
+- camelCase: `loadWidget()`, `getData()`, `validateConfig()`
+- Async prefix: `async` keyword, not name
+
+**Constants:**
+- UPPER_SNAKE_CASE: `DEFAULT_SETTINGS`, `REFRESH_INTERVALS`
+- Grouped in objects: `config.REFRESH_INTERVALS`
+
+## Where to Add New Code
+
+**New Widget:**
+- Implementation: `src/widgets/builtin-widgets.js` (for built-in) OR `~/.openclaw/plugins/<name>/` (for plugin)
+- Tests: `tests/<widget-name>.test.js`
+
+**New Plugin:**
+- Development: `examples/plugins/<name>/`
+- Required files: `index.js`, `plugin.json`
+- See `examples/plugins/hello-world/` for template
+
+**New Service Module:**
+- Implementation: `src/<module-name>.js`
+- Tests: `tests/<module-name>.test.js`
+- Export from: `src/widgets/index.js` if widget-related
+
+**New CLI Command:**
+- Handler: `src/cli/<command-name>.js`
+- Export: `src/cli/index.js`
+- Integration: `index.js` main CLI parsing
+
+**New Worker Task:**
+- Worker: `src/workers/system-worker.js` (add task handler)
+- Pool: `src/workers/worker-pool.js` (add public method)
+
+## Special Directories
+
+**`dist/`:**
+- Purpose: CJS build output
+- Generated: Yes (by `npm run build:cjs`)
+- Committed: Yes (for npm package)
+- Contains: `widgets.cjs` for CJS consumers
+
+**`node_modules/`:**
+- Purpose: npm dependencies
+- Generated: Yes
+- Committed: No
+
+**`coverage/`:**
+- Purpose: Jest coverage reports
+- Generated: Yes
+- Committed: No
+
+**`~/.openclaw/` (runtime):**
+- Purpose: User data directory
+- Created: At runtime if not exists
+- Contains: settings, database, logs, plugins
+
+---
+
+*Structure analysis: 2026-02-28*