claw-dashboard 1.8.4 → 2.0.0

package/FEATURES.md

@@ -14,13 +14,53 @@
 - **Re-added by**: Cron job 2026-02-12 (mistake - should not have been re-added)
 - **Action**: NEVER implement this feature again
 
+### Disk Usage Sparkline
+- **Date tried**: 2026-02-15
+- **Status**: DECLINED
+- **Description**: Added sparkline visualization to disk widget showing disk usage history over time
+- **Reason declined**: Disk usage changes too slowly - sparkline provides no useful insight at 2s refresh intervals
+- **User feedback**: "Disk usage changes slowly. Spark line kind of useless."
+- **Version**: Not shipped
+
+### Load Average Display
+- **Date tried**: 2026-02-15, 2026-02-18
+- **Status**: REJECTED
+- **Description**: Added 1/5/15 minute load average display to CPU widget detail line
+- **Implementation**:
+  - Attempt 1 (2026-02-15): Added as new row in System widget (increased all widget heights)
+  - Attempt 2 (2026-02-18): Moved to CPU box detail line, replacing "X cores" text
+- **Reason rejected**: Feature not needed
+- **User feedback**: "It would be better added to the cpu box to replace the middle line instead of changing the row size" (2026-02-15), then ultimately rejected 2026-02-18
+- **Version**: Not shipped
+
 ## Current Features (Retained)
+
+### Core Features
 - System stats (CPU, memory, GPU, disk, network)
 - OpenClaw sessions list
 - OpenClaw agents list
 - Uptime tracking
 - OpenClaw logs
 - Settings panel
+- Web interface / Remote access (HTTP API)
+
+### v2.0.0 Features
+- **Command Palette** (`Ctrl+K`) - Quick access to all commands
+- **Widget Arrangement Mode** (`w`) - Drag-and-drop widget reordering
+- **Widget Pinning** (`Alt+1-9`) - Pin favorites to top row
+- **Widget Size Presets** - Small/medium/large/wide per widget
+- **Dashboard Snapshots** (`Ctrl+S`/`Ctrl+O`) - Export/import state
+- **Auto-save** - State persistence with backup rotation
+- **Export Scheduling** - Automated cron-like metric exports
+- **Plugin System** - Scaffolding CLI, hot-reload, config UI
+- **Theme Selector** (`T`) - Interactive theme picker
+- **Performance Metrics Overlay** (`p`) - Memory, CPU, refresh stats
+- **Worker Thread Pool** - Background system info gathering
+- **Memory Pressure Detection** - Long-running session health
+- **Multi-gateway Support** - Multiple OpenClaw endpoints
+- **Gateway Auto-retry** - Exponential backoff for reconnections
+- **Widget Error Boundaries** - Isolate failures, retry UI (`X`)
+- **Auto Theme Detection** - Sync with system theme
 
 ## User Preferences
 - Prefer clean, uncluttered layout
@@ -45,6 +85,8 @@ When colors show as literal text like `{green-fg}text{/green-fg}` instead of ren
 - Logs need full width to be useful
 - Avoid squeezing content into narrow columns
 
+## Feature History
+
 ### Network Traffic Sparkline
 - **Date tried**: 2026-02-13
 - **Status**: SHIPPED
@@ -69,7 +111,6 @@ When colors show as literal text like `{green-fg}text{/green-fg}` instead of ren
   - When paused: clock shows [PAUSED] in yellow, footer shows "▶ running"
   - When running: footer shows "p pause"
   - Help panel updated with new key binding
-- **User feedback**: (to be filled in)
 - **Version**: v1.7.2
 
 ### Network Traffic Sparkline Visualization
@@ -81,28 +122,8 @@ When colors show as literal text like `{green-fg}text{/green-fg}` instead of ren
   - Added combined network activity sparkline (RX + TX data) displayed below interface name
   - Uses existing network history data (30 data points, ~60 seconds of history)
   - Adjusted log box position to prevent overlap (top: 23, height: 100%-24)
-- **User feedback**: (to be filled in)
 - **Version**: v1.7.3
 
-### Disk Usage Sparkline
-- **Date tried**: 2026-02-15
-- **Status**: DECLINED
-- **Description**: Added sparkline visualization to disk widget showing disk usage history over time
-- **Reason declined**: Disk usage changes too slowly - sparkline provides no useful insight at 2s refresh intervals
-- **User feedback**: "Disk usage changes slowly. Spark line kind of useless."
-- **Version**: Not shipped
-
-### Load Average Display
-- **Date tried**: 2026-02-15, 2026-02-18
-- **Status**: REJECTED
-- **Description**: Added 1/5/15 minute load average display to CPU widget detail line
-- **Implementation**:
-  - Attempt 1 (2026-02-15): Added as new row in System widget (increased all widget heights)
-  - Attempt 2 (2026-02-18): Moved to CPU box detail line, replacing "X cores" text
-- **Reason rejected**: Feature not needed
-- **User feedback**: "It would be better added to the cpu box to replace the middle line instead of changing the row size" (2026-02-15), then ultimately rejected 2026-02-18
-- **Version**: Not shipped
-
 ### Session Sorting Feature
 - **Date tried**: 2026-02-19
 - **Status**: SHIPPED
@@ -119,6 +140,156 @@ When colors show as literal text like `{green-fg}text{/green-fg}` instead of ren
   - Updated help panel with new key binding
 - **Version**: v1.8.3
 
+### Performance Monitoring Feature
+- **Date tried**: 2026-02-27
+- **Status**: SHIPPED
+- **Description**: Added performance metrics tracking and display for dashboard monitoring
+- **Metrics tracked**:
+  - Memory usage (heap used/total, percentage)
+  - CPU usage (process-specific)
+  - Refresh rate
+  - Event loop lag
+  - Process uptime
+- **Implementation**:
+  - Toggle via Settings panel ("Perf Metrics")
+  - When enabled, shows live metrics in footer: MEM, CPU, refresh rate
+  - Color-coded indicators (green/yellow/red) for memory and CPU levels
+  - History tracking for sparkline visualization
+- **Version**: v1.9.0
+
+### Web Interface / Remote Access Feature
+- **Date tried**: 2026-02-27
+- **Status**: SHIPPED
+- **Description**: Added web server mode for remote dashboard access via HTTP API
+- **Implementation**:
+  - New `--web` CLI flag to run in web server mode (no TUI)
+  - New `--web-port` flag to configure the port (default: 18790)
+  - New `--web-host` flag to configure the bind host (default: 0.0.0.0)
+  - REST API endpoints: `/health`, `/metrics`, `/sessions`, `/agents`, `/logs`, `/status`
+  - CORS-enabled for cross-origin requests
+  - JSON responses for all endpoints
+  - Graceful shutdown handling
+- **Endpoints**:
+  - `GET /health` - Health check with version and uptime
+  - `GET /metrics` - System metrics (CPU, memory, GPU, disk, network)
+  - `GET /sessions` - Active OpenClaw sessions
+  - `GET /agents` - Available OpenClaw agents
+  - `GET /logs` - Recent OpenClaw logs
+  - `GET /status` - Full dashboard status (all data combined)
+- **Security**: API key authentication and rate limiting added in v2.0.0
+- **Version**: v1.10.0
+
+### Command Palette Feature
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Quick access to all dashboard commands via fuzzy search overlay
+- **Implementation**:
+  - Press `Ctrl+K` to open command palette
+  - Type to filter commands by name or description
+  - Navigate with arrow keys, select with Enter
+  - Categories: Navigation, Display, System, Widgets
+  - Shows keyboard shortcuts for each command
+- **Version**: v2.0.0
+
+### Widget Arrangement Mode
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Drag-and-drop style widget reordering
+- **Implementation**:
+  - Press `w` to enter arrangement mode
+  - Use arrow keys to move focused widget
+  - Press Escape or `w` again to exit
+  - Layout persists across restarts
+- **Version**: v2.0.0
+
+### Widget Pinning Feature
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Pin up to 4 favorite widgets to a dedicated top row
+- **Implementation**:
+  - Press `Alt+1` through `Alt+9` to pin/unpin widgets
+  - Pinned widgets appear in a fixed top row
+  - Independent from visibility toggles
+  - Useful for keeping important widgets always visible
+- **Version**: v2.0.0
+
+### Dashboard Snapshots
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Export and import dashboard state as shareable JSON files
+- **Implementation**:
+  - Press `Ctrl+S` to export current state (settings, widget visibility, sizes, positions)
+  - Press `Ctrl+O` to import a previously saved snapshot
+  - Useful for sharing configurations across machines or backing up preferences
+- **Version**: v2.0.0
+
+### Auto-save System
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Automatic state persistence with crash recovery
+- **Implementation**:
+  - Saves state every 30 seconds (configurable)
+  - Maintains last 5 backups with rotation
+  - Restores on startup: session selection, search query, favorites filter, widget focus
+  - Configurable via settings (interval, saveOnExit)
+- **Version**: v2.0.0
+
+### Plugin System
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Extensible widget plugin architecture with scaffolding
+- **Implementation**:
+  - Interactive scaffolding CLI: `clawdash plugin:create`
+  - Plugin hot-reload with `--watch` flag for development
+  - Plugin configuration UI in settings panel
+  - Manifest validation on load
+  - Pre-commit hooks with lint-staged
+- **Version**: v2.0.0
+
+### Theme Selector UI
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Interactive theme picker with live preview
+- **Implementation**:
+  - Press `T` to open theme selector
+  - Navigate with arrow keys, preview live
+  - Themes: default, dark, high-contrast, ocean, auto (system sync)
+  - Auto theme detection syncs with system theme changes
+- **Version**: v2.0.0
+
+### Worker Thread Pool
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Offload heavy system info gathering to background threads
+- **Implementation**:
+  - Configurable worker pool for systeminformation calls
+  - Graceful degradation when workers unavailable
+  - Prevents UI blocking during expensive operations
+  - Status shown in performance overlay
+- **Version**: v2.0.0
+
+### Multi-gateway Support
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Connect to multiple OpenClaw endpoints
+- **Implementation**:
+  - Configure multiple gateways in settings
+  - Visual indicator in footer shows gateway status
+  - Per-gateway health monitoring
+  - Auto-retry with exponential backoff for failed connections
+- **Version**: v2.0.0
+
+### Widget Error Boundaries
+- **Date tried**: 2026-02-28
+- **Status**: SHIPPED (v2.0.0)
+- **Description**: Isolate widget failures from crashing entire dashboard
+- **Implementation**:
+  - Failed widgets show error state with retry button
+  - Press `X` to retry all failed widgets
+  - Other widgets continue operating normally
+  - Error details logged for debugging
+- **Version**: v2.0.0
+
 ## Version History
 - v1.5.1: Baseline
 - v1.6.0: Session list improvements, memory calculation fix
@@ -131,3 +302,6 @@ When colors show as literal text like `{green-fg}text{/green-fg}` instead of ren
 - v1.7.5: Load average display (REJECTED)
 - v1.8.1: Session list improvements
 - v1.8.2: Session sorting feature
+- v1.8.3: Session sorting enhancements
+- v1.9.0: Performance monitoring, web interface
+- v2.0.0: **MAJOR** - Command palette, widget system overhaul, snapshots, auto-save, plugin system, theme selector, multi-gateway, worker threads, error boundaries

package/README.md

@@ -4,6 +4,8 @@ A beautiful, real-time terminal dashboard for monitoring OpenClaw instances —
 
 ![Dashboard Preview](https://img.shields.io/badge/OpenClaw-Dashboard-00d4aa?style=for-the-badge)
 
+> **Coverage Report**: Run `npm run test:coverage` to generate detailed coverage reports in `coverage/`.
+
 ## ✨ Features
 
 - **🎨 Stunning Visuals**: ASCII art logo, gradient colors, donut charts, and progress bars
@@ -14,6 +16,13 @@ A beautiful, real-time terminal dashboard for monitoring OpenClaw instances —
 - **🤖 OpenClaw Integration**: Live session tracking, agent status, security audit
 - **📱 Session Management**: View all active sessions with token usage
 - **⚡ Lightweight**: Built with Node.js and blessed for minimal resource usage
+- **🔄 Auto-save**: Dashboard state persists across restarts
+- **📤 Export Scheduling**: Automated metric exports with cron-like scheduling
+- **🎛️ Widget Arrangement**: Drag-and-drop widget reordering with `w` key
+- **📌 Widget Pinning**: Pin favorite widgets to top row with `Alt+1-9`
+- **📸 Snapshots**: Export/import dashboard configurations
+- **🎨 Theme Selector**: Interactive theme picker with auto-detection
+- **🖱️ Command Palette**: Quick access to all commands with `Ctrl+K`
 
 ## 🚀 Quick Start
 
@@ -41,20 +50,79 @@ clawdash
 
 # Or with npm start (if installed locally)
 npm start
+
+# Run with plugin hot-reload (development)
+clawdash --watch
 ```
 
 ## 🎮 Controls
 
+### Basic Controls
+
 | Key | Action |
 |-----|--------|
 | `q` or `Q` | Quit the dashboard |
 | `r` or `R` | Force refresh data |
-| `p` or `Space` | Pause/resume auto-refresh |
+| `p` | Toggle performance metrics overlay |
+| `P` or `Space` | Pause/resume auto-refresh |
 | `o` | Cycle session sort (time/tokens/idle/name) |
 | `?` or `h` | Toggle help panel |
 | `s` or `S` | Open/close settings panel |
-| `Esc` | Close settings panel (when open) |
+| `Esc` | Close current modal |
 | `Ctrl+C` | Quit gracefully |
+| `Ctrl+K` | Open command palette |
+| `v` | Show version info |
+
+### Widget Controls
+
+| Key | Action |
+|-----|--------|
+| `1-9` | Toggle widgets (1:CPU, 2:MEM, 3:GPU, 4:NET, 5:DISK, 6:SYS, 7:UP, 8:HLTH, 9:GATEWAY) |
+| `Alt+1-9` | Pin/unpin widget to favorites row (max 4) |
+| `w` | Enter widget arrangement mode (drag-and-drop) |
+| `Tab` | Focus next widget |
+| `Shift+Tab` | Focus previous widget |
+| `Enter` | Show widget details (when widget focused) |
+
+### Session Controls
+
+| Key | Action |
+|-----|--------|
+| `f` | Toggle favorite on current session |
+| `F` | Show favorites only (filter) |
+| `g` | Go to first page |
+| `G` | Retry gateway connection |
+| `/` | Search/filter sessions |
+| `Return` | Show session detail |
+
+### Data & Export
+
+| Key | Action |
+|-----|--------|
+| `e` | Export dashboard data (JSON/CSV) |
+| `E` | Cycle export format |
+| `Ctrl+S` | Export snapshot (shareable config) |
+| `Ctrl+O` | Import snapshot |
+| `X` | Retry failed widgets (error recovery) |
+
+### Navigation
+
+| Key | Action |
+|-----|--------|
+| `↑`/`k` | Previous session |
+| `↓`/`j` | Next session |
+| `←`/`h` | Previous page |
+| `→`/`l` | Next page |
+| `[`/`]` | Previous/next page |
+| `Ctrl+B` | Page up |
+| `Ctrl+F` | Page down |
+
+### Theme & Display
+
+| Key | Action |
+|-----|--------|
+| `t` | Cycle theme (default/dark/high-contrast/ocean) |
+| `T` | Open theme selector |
 
 ### Session Sorting
 
@@ -69,10 +137,12 @@ Press `o` to cycle through different ways to sort the sessions list:
 Press `s` to open the settings panel where you can customize:
 
 - **Refresh Interval**: Toggle between 1s, 2s, 5s, or 10s
-- **Show Network**: Enable/disable network monitoring widget
-- **Show GPU**: Enable/disable GPU monitoring widget  
-- **Show Disk**: Enable/disable disk usage widget
-- **Show Processes**: Enable/disable top processes widget
+- **Widget Visibility**: Toggle individual widgets (1-9 keys)
+- **Widget Sizes**: Choose small/medium/large/wide for each widget
+- **Export Schedule**: Configure automated metric exports
+- **Version Check**: Set interval for update checking (1h/6h/12h/24h/off)
+- **Plugin Config**: Configure installed plugins
+- **Performance Metrics**: Show/hide performance overlay in footer
 
 Settings are automatically saved to `~/.openclaw/dashboard-settings.json` and persist across sessions.
 
@@ -181,6 +251,13 @@ Recommended: **iTerm2**, **Kitty**, **Alacritty**
 - `systeminformation` - System stats
 - `chalk` - Terminal colors
 
+## 📚 Documentation
+
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
+- **[docs/API.md](docs/API.md)** - Internal API documentation for modules
+- **[TODO.md](TODO.md)** - Planned features and development roadmap
+- **[FEATURES.md](FEATURES.md)** - Detailed feature documentation
+
 ## 🤝 Contributing
 
 Issues and PRs welcome at [github.com/openclaw/claw-dashboard](https://github.com/openclaw/claw-dashboard)

package/TODO.md

@@ -0,0 +1,28 @@
+## TODO
+
+## Backlog
+
+- Document command palette feature in README.md
+- Integration test for command palette execution flow
+- E2E test for Ctrl+K keybinding
+- Plugin marketplace/discovery - Community registry index
+- Session quick-switcher - Ctrl+K fuzzy finder for profiles
+- WebSocket support - Push-based real-time updates
+- Multiple dashboard profiles - Tabbed navigation
+- Widget grouping/collapsing - Organize dense dashboards
+- Conditional widget visibility - Show/hide based on data thresholds
+- Dashboard layout templates - Preset layouts for different roles
+- Historical data persistence - SQLite/LevelDB backend
+- Trend indicators - Compare vs historical averages
+- Anomaly detection alerts - Automatic spike detection
+- Webhook notifications - Threshold breach alerts (Slack/Discord)
+- OpenClaw event stream - Consume events from gateway
+- Plugin sandbox - Node.js VM isolation
+- Widget playground - Live preview during development
+- Plugin publishing CLI - npm-style workflow
+
+## Technical Debt
+
+- Test coverage - Improve from ~43% to 70%+
+- TypeScript migration - Start with validation.js/security.js
+- JSDoc completion - Complete PluginAPI public methods

package/build-cjs.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/**
+ * Build CJS wrappers for dual-package exports
+ * Creates CJS versions of ESM modules for backward compatibility
+ */
+
+import * as esbuild from 'esbuild';
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Custom plugin to replace import.meta.url with a CJS-compatible version
+const cjsImportMetaPlugin = {
+  name: 'cjs-import-meta',
+  setup(build) {
+    // Filter only JS files
+    const filter = /\.js$/;
+
+    build.onLoad({ filter }, async (args) => {
+      const contents = await readFileSync(args.path, 'utf8');
+
+      // Replace import.meta.url with a CJS-compatible expression
+      // We use process.cwd() as fallback since we can't know the actual file location
+      const newContents = contents.replace(
+        /import\.meta\.url/g,
+        "'file://' + (typeof __dirname !== 'undefined' ? require('path').join(__dirname, 'index.js').replace(/\\\\/g, '/') : process.cwd() + '/index.js')"
+      );
+
+      return { contents: newContents, loader: 'js' };
+    });
+  },
+};
+
+// Build config for widgets CJS bundle
+const widgetsCjsConfig = {
+  entryPoints: ['src/widgets/index.js'],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  outfile: 'dist/widgets.cjs',
+  format: 'cjs',
+  external: ['blessed', 'blessed-contrib', 'systeminformation'],
+  minify: false,
+  sourcemap: false,
+  plugins: [cjsImportMetaPlugin],
+};
+
+// Build config for main CJS bundle
+const mainCjsConfig = {
+  entryPoints: ['index.js'],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  outfile: 'index.cjs',
+  format: 'cjs',
+  external: ['blessed', 'blessed-contrib', 'systeminformation'],
+  minify: false,
+  sourcemap: false,
+  plugins: [cjsImportMetaPlugin],
+};
+
+async function buildCjs(config, name) {
+  console.log(`Building CJS ${name}...`);
+  try {
+    const result = await esbuild.build({
+      ...config,
+      write: false,
+    });
+
+    let output = result.outputFiles[0].text;
+
+    // Extract shebang if present (must be at the very start)
+    let shebang = '';
+    const shebangMatch = output.match(/^#![^\n]*\n/);
+    if (shebangMatch) {
+      shebang = shebangMatch[0];
+      output = output.slice(shebang.length);
+    }
+
+    // Also remove any shebang that might appear later in the file
+    output = output.replace(/#![^\n]*\n/g, '');
+
+    // Post-process: add __dirname polyfill at the start of the bundle
+    const polyfill = `// Polyfill for __dirname in CJS bundle
+var path = require('path');
+var __filename = process.argv[1] || process.cwd() + '/index.js';
+var __dirname = path.dirname(__filename);
+`;
+
+    // Add shebang first, then polyfill after 'use strict' if present
+    if (output.startsWith('"use strict";')) {
+      output = shebang + '"use strict";\n' + polyfill + output.slice('"use strict";'.length);
+    } else {
+      output = shebang + polyfill + output;
+    }
+
+    writeFileSync(config.outfile, output, { mode: 0o755 });
+    console.log(`✓ CJS ${name} built: ${config.outfile}`);
+    return true;
+  } catch (error) {
+    console.error(`✗ CJS ${name} build failed:`, error.message);
+    return false;
+  }
+}
+
+async function main() {
+  // Ensure dist directory exists
+  if (!existsSync('dist')) {
+    mkdirSync('dist', { recursive: true });
+  }
+
+  const widgetsResult = await buildCjs(widgetsCjsConfig, 'widgets');
+  const mainResult = await buildCjs(mainCjsConfig, 'main');
+
+  if (widgetsResult && mainResult) {
+    console.log('✓ All CJS builds completed');
+    process.exit(0);
+  } else {
+    process.exit(1);
+  }
+}
+
+main();

package/cjs-shim.js

@@ -0,0 +1,13 @@
+// CJS shim for import.meta.url polyfill
+// This file is injected into CJS builds to provide __dirname
+
+const path = require('path');
+const { fileURLToPath } = require('url');
+
+// Check if we're in a bundled environment or regular CJS
+if (typeof __filename === 'undefined') {
+  // In bundled CJS, process.cwd() is used
+  global.__dirname = path.dirname(process.execPath);
+} else {
+  global.__dirname = path.dirname(__filename);
+}