claw-dashboard 1.8.4 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,293 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-02-28
+
+### Major Features
+
+#### Command Palette (Ctrl+K)
+- Quick access to all dashboard commands via fuzzy search
+- Keyboard shortcut discovery and command execution
+- Categories for Navigation, Display, System, and Widgets
+
+#### Widget System Overhaul
+- **Drag-and-drop arrangement mode** - Press `w` to enter arrangement mode, use arrow keys to reorder widgets
+- **Widget pinning** - Pin up to 4 favorite widgets to the top row with `Alt+1-9`
+- **Widget size presets** - Resize any widget to small, medium, large, or wide
+- **Improved widget navigation** - Tab/Shift+Tab to cycle focus between widgets
+- **Enter key actions** - Show widget details or performance overlay when widget is focused
+
+#### Dashboard Snapshots
+- Export full dashboard state as shareable JSON files (`Ctrl+S`)
+- Import snapshots to restore configurations (`Ctrl+O`)
+- Includes widget visibility, sizes, positions, and settings
+
+#### Auto-save System
+- Automatic state persistence every 30 seconds
+- Crash recovery with backup rotation (keeps last 5 backups)
+- Restores session selection, search queries, favorites filter, and widget focus on restart
+
+#### Export Scheduling
+- Automated metric exports with cron-like scheduling
+- Configurable format (JSON/CSV), directory, and retention
+- Optional metrics inclusion and custom schedules
+
+#### Plugin System
+- Interactive plugin scaffolding CLI for creating new widgets
+- Plugin hot-reload with `--watch` flag for development
+- Plugin configuration UI in settings panel
+- Manifest validation on load
+- Pre-commit hooks with lint-staged for plugin development
+
+#### Theme System Enhancements
+- **Theme selector UI** - Interactive picker with live preview (`T` key)
+- **Auto theme detection** - Syncs with system theme changes
+- **Animated loading states** - Smooth transitions for splash screen
+
+#### Performance & Monitoring
+- **Performance metrics overlay** - Memory, CPU, and refresh rate stats (press `p`)
+- **Worker thread pool** - Offloads heavy system info gathering for UI responsiveness
+- **Memory pressure detection** - Monitors long-running session health
+- **Graceful degradation** - Continues operating when system data fetching fails
+
+#### Gateway Management
+- **Multi-gateway support** - Connect to multiple OpenClaw endpoints
+- **Auto-retry with exponential backoff** - Configurable retry logic
+- **Gateway status widget** - Visual indicator of gateway health
+- **Manual retry** - Press `G` to retry connection when offline
+
+#### Error Handling
+- **Widget error boundaries** - Isolates widget failures from dashboard
+- **Error recovery UI** - Press `X` to retry failed widgets
+- **Custom error classes** - Better error categorization and handling
+- **Widget error isolation** - Failed widgets show retry button without crashing dashboard
+
+### New Controls
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+K` | Open command palette |
+| `w` | Enter widget arrangement mode |
+| `Alt+1-9` | Pin/unpin widget to favorites |
+| `T` | Open theme selector |
+| `Ctrl+S` | Export dashboard snapshot |
+| `Ctrl+O` | Import dashboard snapshot |
+| `X` | Retry failed widgets |
+| `Enter` | Show widget details (when focused) |
+
+### Changed
+- **Swapped hotkeys**: `p` now opens performance overlay, `P` (capital) pauses
+- Improved settings panel with more options
+- Enhanced footer with gateway status and performance metrics
+- Better cross-platform GPU support (WSL2, Windows WMI, Linux nvidia-smi)
+- Container environment detection (Docker, Kubernetes, WSL)
+
+### Fixed
+- Navigation crash during settings modal close (race condition)
+- Worker timer leak in widget refresh intervals
+- Session detail view color markup display
+- Settings list refresh after changing refresh interval
+- Modal state getting stuck when closing multiple modals quickly
+- Performance overlay now properly captures input (q/Escape/p to close)
+- Version check now non-blocking with configurable 12h interval
+- Widget destroy errors with proper null checks
+- Log level filter default to "all" instead of "error"
+
+### Security
+- Web server API key authentication
+- Web server rate limiting and CORS configuration
+- File path validation for export/import operations
+- Gateway endpoint configuration validation
+
+### Developer Features
+- c8 code coverage reporting with threshold checks
+- Enhanced CLI organization with modular handlers
+- Plugin validator with verbose mode
+- Pre-commit hooks for code quality
+
+## [1.9.0] - 2025-02-06
+
+### Added
+- Dynamic widget reflow and show/hide functionality (keys 1-4)
+- Session TPS (transactions per second) column
+- Session count display in sessions header
+- Data Health widget with data freshness tracking
+- Sound notifications for alerts
+- Auto-detect terminal theme on first run
+- Vi-mode navigation (hjkl keys)
+- Favorites/bookmarks feature for quick navigation
+- Tooltip hints system for first-run users
+
+### Changed
+- Improved session sorting options (recent, context size, idle time, CPU, memory)
+- Enhanced UI with theme persistence
+
+### Fixed
+- Arrow key navigation for session pages
+- Network interface change handling
+- Stale session TPS cleanup
+- Toggle search binding error
+
+## [1.8.5] - 2025-02-04
+
+### Added
+- Widget toggle feature (press 1-4 to show/hide)
+
+## [1.8.4] - 2025-02-04
+
+### Added
+- Session duration display in session list
+
+## [1.8.2] - 2025-02-03
+
+### Fixed
+- TPS calculation using correct session data source
+
+## [1.8.0] - 2025-02-03
+
+### Added
+- Dashboard export functionality (JSON, CSV, markdown)
+- Logger module for file-based logging
+- Session sorting by CPU, memory, and load average
+
+### Changed
+- Read sessions directly from sessions.json for improved reliability
+
+### Removed
+- Load average display feature (rejected due to cross-platform inconsistencies)
+
+## [1.7.3] - 2025-02-02
+
+### Changed
+- Stale sessions now displayed in gray instead of red
+
+## [1.7.2] - 2025-02-02
+
+### Changed
+- Clock widget now uses local timezone
+
+## [1.7.1] - 2025-02-02
+
+### Added
+- Clock widget displaying current time
+- Log level filtering and colorizing
+
+## [1.7.0] - 2025-02-01
+
+### Added
+- Network traffic sparkline visualization
+- Top Processes widget
+
+## [1.6.0] - 2025-01-31
+
+### Added
+- SQLite persistence for metrics and sessions
+- Cache module with TTL support
+- Adaptive refresh rate based on system load
+
+## [1.5.1] - 2025-01-30
+
+### Fixed
+- Session navigation bounds checking
+- Race condition in settings management
+
+## [1.5.0] - 2025-01-30
+
+### Added
+- Alerts system with configurable thresholds
+- Retry logic with exponential backoff
+- Validation module for input sanitization
+
+## [1.4.1] - 2025-01-29
+
+### Added
+- Interactive settings panel
+- Version display in header
+- UI polish and refinements
+
+## [1.4.0] - 2025-01-28
+
+### Added
+- Interactive settings panel with real-time updates
+- Mouse support for navigation
+- Session detail view
+
+### Changed
+- Enhanced theme system with 4 customizable themes
+
+## [1.3.0] - 2025-01-27
+
+### Added
+- Theme system with customizable color schemes
+- Session search functionality
+- Pagination for large session lists
+
+## [1.2.0] - 2025-01-26
+
+### Added
+- GPU monitoring (basic support)
+- Disk usage visualization
+- Network interface monitoring
+
+## [1.1.0] - 2025-01-25
+
+### Added
+- Memory usage display with progress bars
+- CPU utilization sparkline
+- System information panel
+
+## [1.0.0] - 2025-01-24
+
+### Added
+- Initial release of Claw Dashboard
+- Real-time OpenClaw session monitoring
+- Basic CPU and memory metrics
+- Terminal-based UI using blessed
+- Cross-platform support (macOS, Linux)
+- Session list with status indicators
+- Auto-refresh with configurable interval
+
+---
+
+## Version Format
+
+Versions follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** - Incompatible API changes or major feature rewrites
+- **MINOR** - New functionality (backward compatible)
+- **PATCH** - Bug fixes and small improvements (backward compatible)
+
+## Categories
+
+- **Added** - New features
+- **Changed** - Changes to existing functionality
+- **Deprecated** - Soon-to-be removed features
+- **Removed** - Removed features
+- **Fixed** - Bug fixes
+- **Security** - Security improvements
+
+## Release Notes Template
+
+When adding a new release, use this template:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New feature description
+
+### Changed
+- Change description
+
+### Fixed
+- Bug fix description
+
+### Security
+- Security improvement description
+```

package/CONTRIBUTING.md

@@ -0,0 +1,378 @@
+# Contributing to Claw Dashboard
+
+Thank you for your interest in contributing to Claw Dashboard! This document provides guidelines and instructions for contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [Release Process](#release-process)
+
+## Code of Conduct
+
+This project adheres to a code of conduct that we expect all contributors to follow:
+
+- Be respectful and inclusive in all interactions
+- Welcome newcomers and help them learn
+- Focus on constructive feedback
+- Accept constructive criticism gracefully
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** v18 or higher
+- **npm** v9 or higher
+- **OpenClaw** installed and configured (for full integration testing)
+
+### Setup
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/claw-dashboard.git
+   cd claw-dashboard
+   ```
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+4. Run the dashboard:
+   ```bash
+   npm start
+   ```
+
+## Development Workflow
+
+### Branch Naming
+
+Use descriptive branch names with the following prefixes:
+
+- `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation changes
+- `refactor/` - Code refactoring
+- `test/` - Test additions or updates
+
+Examples:
+```
+feature/add-custom-widgets
+fix/memory-leak-on-refresh
+docs/update-api-examples
+```
+
+### Making Changes
+
+1. Create a new branch from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following the [coding standards](#coding-standards)
+
+3. Test your changes:
+   ```bash
+   npm test
+   ```
+
+4. Update documentation if needed (README.md, API.md, CHANGELOG.md)
+
+## Coding Standards
+
+### JavaScript Style
+
+- Use ES modules (`import`/`export`)
+- Use 2 spaces for indentation
+- Use semicolons
+- Prefer `const` and `let` over `var`
+- Use camelCase for variables and functions
+- Use PascalCase for classes
+- Use UPPER_SNAKE_CASE for constants
+
+Example:
+```javascript
+// Good
+const MAX_RETRIES = 3;
+
+export async function fetchData() {
+  const result = await getData();
+  return result;
+}
+
+export class DataFetcher {
+  constructor() {
+    this.cache = new Map();
+  }
+}
+
+// Bad
+var MAX_RETRIES = 3;
+
+function fetch_data() {
+  let result = getData();
+  return result;
+}
+```
+
+### Code Organization
+
+- Place all source files in `src/`
+- Group related functionality into modules
+- Keep functions focused and small
+- Export only what's necessary from modules
+
+### Configuration
+
+All magic numbers and configurable values should be centralized in `src/config.js`:
+
+```javascript
+// In src/config.js
+export const CACHE_TTL = {
+  CPU: 1000,
+  MEMORY: 1000,
+  GPU: 5000,
+};
+
+// In your module
+import { CACHE_TTL } from './config.js';
+```
+
+### Error Handling
+
+Use the custom error classes from `src/errors.js`:
+
+```javascript
+import { GatewayError, DataFetchError } from './errors.js';
+import logger from './logger.js';
+
+try {
+  const data = await fetchData();
+} catch (error) {
+  logger.error('Failed to fetch:', error.message);
+  throw new GatewayError('Fetch failed', { cause: error });
+}
+```
+
+### Logging
+
+Use the logger module instead of `console.log`:
+
+```javascript
+import logger from './logger.js';
+
+logger.debug('Debug info');    // Only shows with DEBUG=1
+logger.info('General info');
+logger.warn('Warning message');
+logger.error('Error message');
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm test -- --watch
+```
+
+### Writing Tests
+
+Place test files in the `tests/` directory with the naming pattern `*.test.js`:
+
+```javascript
+// tests/my-feature.test.js
+import { describe, test, expect } from '@jest/globals';
+import { myFunction } from '../src/my-module.js';
+
+describe('myFunction', () => {
+  test('should return expected result', () => {
+    const result = myFunction('input');
+    expect(result).toBe('expected output');
+  });
+
+  test('should handle errors gracefully', async () => {
+    await expect(myFunction(null)).rejects.toThrow();
+  });
+});
+```
+
+### Test Guidelines
+
+- Write tests for new functionality
+- Ensure all existing tests pass before submitting
+- Aim for meaningful coverage, not just high percentages
+- Test edge cases and error conditions
+- Use descriptive test names that explain the behavior
+
+## Submitting Changes
+
+### Pull Request Process
+
+1. Ensure your branch is up to date with `main`:
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   ```
+
+2. Run the full test suite:
+   ```bash
+   npm test
+   ```
+
+3. Update the CHANGELOG.md if applicable
+
+4. Push your branch:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+5. Create a Pull Request on GitHub with:
+   - Clear title describing the change
+   - Detailed description explaining what and why
+   - Reference any related issues (e.g., "Fixes #123")
+   - Screenshots/gifs for UI changes
+
+### PR Review Process
+
+- All PRs require at least one review
+- Address review feedback promptly
+- Be open to suggestions and changes
+- Squash commits if requested
+
+## Commit Message Guidelines
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+### Format
+
+```
+<type>: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation changes |
+| `style` | Code style changes (formatting, semicolons, etc.) |
+| `refactor` | Code refactoring |
+| `test` | Test additions or updates |
+| `chore` | Build process or auxiliary tool changes |
+
+### Examples
+
+```
+feat: add session sorting by token usage
+
+fix: resolve memory leak in widget refresh cycle
+docs: update API documentation for gateway manager
+refactor: extract cache logic into separate module
+test: add unit tests for error classes
+chore: update dependencies to latest versions
+```
+
+### Rules
+
+- Use present tense ("add feature" not "added feature")
+- Use imperative mood ("move cursor" not "moves cursor")
+- Don't capitalize the first letter
+- No period at the end
+- Keep the first line under 72 characters
+
+## Release Process
+
+We use an automated release script that handles versioning, building, signing, and tagging.
+
+### Prerequisites
+
+- Node.js v18+ with npm
+- GPG key configured (for signed releases)
+- GitHub CLI (`gh`) installed (for GitHub releases)
+
+### Quick Release
+
+```bash
+# Patch release (1.0.0 → 1.0.1)
+npm run release
+
+# Minor release (1.0.0 → 1.1.0)
+npm run release minor
+
+# Major release (1.0.0 → 2.0.0)
+npm run release major
+
+# With GPG signing
+npm run release:sign
+
+# With GitHub release creation
+npm run release:github
+```
+
+### Manual Release Steps
+
+If you prefer to release manually:
+
+1. Update version in `package.json`
+2. Update CHANGELOG.md with release date
+3. Build the project: `npm run build`
+4. Create a git tag: `git tag vX.Y.Z`
+5. Push tags: `git push origin vX.Y.Z`
+6. Create a GitHub release with release notes
+
+### Release Script Features
+
+The automated release script (`scripts/release.js`):
+
+- **Validates** the working directory is clean
+- **Bumps** version in package.json (patch/minor/major)
+- **Updates** CHANGELOG.md with new release date
+- **Builds** the project with ESBuild (creates `dist/clawdash`)
+- **Signs** releases with GPG (optional, use `--sign`)
+- **Creates** git commit and annotated tag
+- **Publishes** GitHub release (optional, use `--github`)
+
+### Build System
+
+We use **ESBuild** for bundling:
+
+```bash
+# Production build (minified)
+npm run build
+
+# Development build (with source maps)
+npm run build:dev
+
+# Analyze bundle size
+npm run build -- --analyze
+```
+
+The build creates:
+- `dist/clawdash` - Bundled, minified executable
+- `dist/clawdash.meta.json` - Bundle analysis metadata
+
+## Questions?
+
+If you have questions or need help:
+
+- Open an issue on GitHub
+- Check existing issues and discussions
+- Review the [API documentation](docs/API.md)
+
+Thank you for contributing!

package/Dockerfile

@@ -0,0 +1,54 @@
+# Claw Dashboard - Production Docker Image
+# Multi-stage build for optimized image size
+
+# Stage 1: Dependencies
+FROM node:20-alpine AS dependencies
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json package-lock.json ./
+
+# Install production dependencies only
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Stage 2: Production
+FROM node:20-alpine AS production
+
+# Add metadata labels
+LABEL maintainer="Kevin Smith <kevin@example.com>"
+LABEL org.opencontainers.image.title="Claw Dashboard"
+LABEL org.opencontainers.image.description="A beautiful console dashboard for monitoring OpenClaw instances"
+LABEL org.opencontainers.image.source="https://github.com/spleck/claw-dashboard"
+LABEL org.opencontainers.image.licenses="MIT"
+
+# Create non-root user for security
+RUN addgroup -g 1000 -S claw && \
+    adduser -u 1000 -S claw -G claw
+
+WORKDIR /app
+
+# Copy production dependencies from dependencies stage
+COPY --from=dependencies /app/node_modules ./node_modules
+
+# Copy application files
+COPY --chown=claw:claw index.js ./
+COPY --chown=claw:claw src ./src
+
+# Switch to non-root user
+USER claw
+
+# Expose any potential web interface port (for future use)
+EXPOSE 18790
+
+# Set environment variables
+ENV NODE_ENV=production
+ENV TERM=xterm-256color
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD node -e "console.log('healthy')" || exit 1
+
+# Run the dashboard
+ENTRYPOINT ["node", "index.js"]
+CMD []