claw-dashboard 2.1.1 → 2.2.0

package/.planning/codebase/ARCHITECTURE.md

@@ -1,206 +0,0 @@
-# Architecture
-
-**Analysis Date:** 2026-02-28
-
-## Pattern Overview
-
-**Overall:** Modular widget-based terminal dashboard with plugin architecture
-
-**Key Characteristics:**
-- Widget-based UI components using blessed framework
-- Plugin system with lazy loading and hot-reload
-- Event-driven architecture (EventEmitter pattern)
-- Worker thread pool for heavy system operations
-- Rate limiting throughout API access
-- Comprehensive error boundaries
-
-## Layers
-
-**Application Layer:**
-- Purpose: Entry point, CLI parsing, main dashboard orchestration
-- Location: `index.js`
-- Contains: Main screen setup, keyboard handlers, initialization sequence
-- Depends on: All other layers
-- Used by: CLI binary
-
-**Widget Layer:**
-- Purpose: UI components and plugin system
-- Location: `src/widgets/`
-- Contains: BaseWidget class, PluginAPI, WidgetLoader, built-in widgets
-- Depends on: blessed, blessed-contrib
-- Used by: Application layer
-
-**Service Layer:**
-- Purpose: Business logic, data fetching, caching
-- Location: `src/*.js` (non-widget files)
-- Contains: gateway-manager, database, cache, themes, alerts, validation
-- Depends on: systeminformation, sql.js
-- Used by: Widgets and Application
-
-**Worker Layer:**
-- Purpose: Offload heavy system calls to threads
-- Location: `src/workers/`
-- Contains: WorkerPool, system-worker
-- Depends on: Node.js worker_threads
-- Used by: Application layer for system metrics
-
-**Data Layer:**
-- Purpose: Persistence and caching
-- Location: `src/database.js`, `src/cache.js`
-- Contains: SQLite persistence, in-memory caching
-- Depends on: sql.js, fs
-- Used by: Service layer
-
-## Data Flow
-
-**System Metrics Flow:**
-
-1. Widget requests data via PluginAPI
-2. PluginAPI checks rate limiter
-3. Widget calls getData() which may use:
-   - Worker pool for systeminformation calls
-   - Cache for recent data
-   - Direct fetch for real-time data
-4. Data returns to widget
-5. Widget renders to blessed elements
-
-**Gateway Data Flow:**
-
-1. GatewayManager initialized with endpoints
-2. Periodic fetch from `/api/sessions`, `/api/agents`
-3. Checksum verification (optional)
-4. Data aggregated from multiple endpoints
-5. Stored in SQLite database
-6. Widgets query database for display
-
-**Widget Plugin Flow:**
-
-1. WidgetLoader discovers plugins from `~/.openclaw/plugins/`
-2. Manifest validated (`src/plugin-manifest-validator.js`)
-3. Dependencies resolved (`src/widgets/dependency-resolver.js`)
-4. Widget class loaded dynamically
-5. BaseWidget lifecycle: init -> create -> getData -> render -> destroy
-6. Config watcher enables hot-reload
-
-## Key Abstractions
-
-**BaseWidget:**
-- Purpose: Base class for all widgets
-- Location: `src/widgets/plugin-api.js` (class BaseWidget)
-- Pattern: Template method pattern with lifecycle hooks
-- Methods: init(), create(screen, theme), getData(), render(data), destroy()
-
-**PluginAPI:**
-- Purpose: Stable API for widget development
-- Location: `src/widgets/plugin-api.js`
-- Pattern: Facade pattern with rate limiting
-- Extension points: registerExtensionPoint(), extend(), registerProvider()
-
-**WidgetLoader:**
-- Purpose: Lazy loading and plugin management
-- Location: `src/widgets/widget-loader.js`
-- Pattern: Registry + Factory pattern
-- Features: Priority-based loading, dependency resolution, hot-reload
-
-**GatewayManager:**
-- Purpose: Multi-endpoint gateway aggregation
-- Location: `src/gateway-manager.js`
-- Pattern: Manager pattern with aggregation
-- Features: Checksum verification, retry logic, endpoint health tracking
-
-**Error Boundaries:**
-- Purpose: Isolate widget failures
-- Location: `src/widgets/widget-error-boundary.js`
-- Pattern: Decorator pattern
-- Features: Per-widget error isolation, automatic retry
-
-## Entry Points
-
-**Main Entry:**
-- Location: `index.js`
-- Triggers: CLI execution (`clawdash` or `node index.js`)
-- Responsibilities:
-  - Parse CLI args (`src/cli/index.js`)
-  - Initialize database
-  - Setup blessed screen
-  - Load widgets via WidgetLoader
-  - Setup keyboard handlers
-  - Start refresh loop
-
-**CLI Commands:**
-- Location: `src/cli/`
-- Files: args.js, help.js, version.js, validate-plugin.js, validate-config.js
-- Exports centralized in: `src/cli/index.js`
-
-**Worker Entry:**
-- Location: `src/workers/system-worker.js`
-- Triggers: WorkerPool initialization
-- Responsibilities: Execute systeminformation calls in separate threads
-
-## State Management
-
-**Theme State:**
-- File: `src/themes.js`
-- Pattern: Singleton with observer pattern
-- Detection: Auto-detects system dark/light mode
-- Persistence: Settings file
-
-**Settings State:**
-- File: `src/config.js` (constants), `src/validation.js` (validation)
-- Pattern: Immutable constants with validation
-- Storage: JSON file at `~/.openclaw/dashboard-settings.json`
-
-**Widget State:**
-- File: `src/widgets/widget-loader.js`
-- Pattern: Registry with metadata
-- Storage: In-memory Map instances
-
-**Performance State:**
-- File: `src/performance-monitor.js`
-- Pattern: Observer with periodic sampling
-- Metrics: Memory usage, worker pool stats
-
-## Error Handling
-
-**Strategy:** Hierarchical error classes with boundary isolation
-
-**Patterns:**
-- Custom error hierarchy: `DashboardError` -> specific errors
-- Widget error boundaries isolate failures
-- Plugin error analyzer for debugging
-- Rate-limited error reporting
-
-**Error Classes:**
-- `src/errors.js`: DashboardError, ConfigError, SettingsError, GatewayError, etc.
-- `src/plugin-errors.js`: PluginError, PluginErrorAnalyzer
-
-## Cross-Cutting Concerns
-
-**Logging:**
-- Location: `src/logger.js`
-- Pattern: Centralized with level filtering
-- Output: Console + file (`~/.openclaw/claw-dashboard.log`)
-
-**Validation:**
-- Location: `src/validation.js`
-- Pattern: Schema-based with detailed error messages
-- Scope: Settings, file paths, refresh intervals
-
-**Security:**
-- Location: `src/security.js`
-- Pattern: Input sanitization + path validation
-- Features: Path traversal prevention, file permission management
-
-**Rate Limiting:**
-- Location: `src/alerts.js` (RateLimiter class)
-- Pattern: Token bucket per category
-- Integration: PluginAPI uses for API calls
-
-**Caching:**
-- Location: `src/cache.js`
-- Pattern: TTL-based with category-specific timeouts
-- Features: Debounce, throttle, memoization
-
----
-
-*Architecture analysis: 2026-02-28*

package/.planning/codebase/INTEGRATIONS.md

@@ -1,150 +0,0 @@
-# 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

@@ -1,122 +0,0 @@
-# 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

@@ -1,201 +0,0 @@
-# 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*