claw-dashboard 1.9.0 → 2.0.0

package/.c8rc.json

@@ -0,0 +1,38 @@
+{
+  "all": true,
+  "include": [
+    "index.js",
+    "src/**/*.js"
+  ],
+  "exclude": [
+    "node_modules/**",
+    "coverage/**",
+    "tests/**",
+    "dist/**",
+    "scripts/**",
+    "examples/**",
+    "src/workers/**",
+    "**/*.test.js",
+    "**/*.config.js"
+  ],
+  "reporter": [
+    "text",
+    "text-summary",
+    "lcov",
+    "html",
+    "json-summary"
+  ],
+  "check-coverage": true,
+  "statements": 35,
+  "branches": 30,
+  "functions": 20,
+  "lines": 35,
+  "watermarks": {
+    "statements": [70, 90],
+    "branches": [65, 85],
+    "functions": [70, 90],
+    "lines": [70, 90]
+  },
+  "report-dir": "./coverage",
+  "temp-dir": "./coverage/.tmp"
+}

package/.dockerignore

@@ -0,0 +1,68 @@
+# Dependencies
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Testing
+tests/
+coverage/
+*.test.js
+*.spec.js
+jest.config.js
+
+# Documentation
+docs/
+*.md
+CONTRIBUTING.md
+CHANGELOG.md
+README.md
+TODO.md
+
+# Git
+.git
+.gitignore
+.gitattributes
+
+# CI/CD
+.github/
+.travis.yml
+.gitlab-ci.yml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+logs/
+*.log
+
+# Runtime data
+pids/
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Build outputs
+dist/
+build/
+
+# Worktrees
+.worktrees/
+
+# Installation scripts (not needed in container)
+install.sh
+start.sh

package/.github/dependabot.yml

@@ -0,0 +1,45 @@
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '09:00'
+    open-pull-requests-limit: 10
+    reviewers:
+      - 'spleck'
+    assignees:
+      - 'spleck'
+    commit-message:
+      prefix: 'chore(deps)'
+      include: 'scope'
+    labels:
+      - 'dependencies'
+    groups:
+      dev-dependencies:
+        patterns:
+          - '*'
+        exclude-patterns:
+          - 'blessed*'
+          - 'systeminformation'
+      production-dependencies:
+        patterns:
+          - 'blessed*'
+          - 'systeminformation'
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+      day: 'monday'
+      time: '09:00'
+    open-pull-requests-limit: 5
+    reviewers:
+      - 'spleck'
+    commit-message:
+      prefix: 'chore(actions)'
+      include: 'scope'
+    labels:
+      - 'dependencies'
+      - 'github-actions'

package/.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Description
+
+Brief description of the changes in this PR.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Refactoring (no functional changes)
+- [ ] Performance improvement
+- [ ] Test addition or improvement
+
+## Checklist
+
+- [ ] I have run `npm test` and all tests pass
+- [ ] I have run `npm run build` and the build succeeds
+- [ ] My code follows the project's style guidelines
+- [ ] I have performed a self-review of my code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+
+## Testing
+
+Describe the tests you ran and how to reproduce them:
+
+## Screenshots (if applicable)
+
+## Related Issues
+
+Fixes #(issue number)
+
+## Additional Notes
+
+Any other information that would be helpful for reviewers.

package/.github/workflows/ci.yml

@@ -0,0 +1,147 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - '.github/*.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - '.github/*.md'
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+      fail-fast: false
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter (ESLint checks)
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Run tests with coverage
+        if: matrix.node-version == 20
+        run: npm run test:coverage
+
+      - name: Upload coverage to Codecov
+        if: matrix.node-version == 20 && github.event_name != 'pull_request'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+          fail_ci_if_error: false
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build distribution
+        run: npm run build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: false
+          tags: claw-dashboard:test
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  security-audit:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit
+        run: npm audit --audit-level=moderate
+        continue-on-error: true
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@master
+        with:
+          scan-type: 'fs'
+          scan-ref: '.'
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+
+      - name: Upload Trivy scan results
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: 'trivy-results.sarif'

package/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  release:
+    types: [created, published]
+
+jobs:
+  build-and-publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build all bundles
+        run: |
+          npm run build
+          npm run build:cjs
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/security.yml

@@ -0,0 +1,84 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Run daily at 2:00 AM UTC
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+jobs:
+  npm-audit:
+    name: NPM Audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit
+        run: |
+          npm audit --audit-level=moderate || exit_code=$?
+          if [ "${exit_code:-0}" -eq 0 ]; then
+            echo "No vulnerabilities found"
+          elif [ "${exit_code:-0}" -eq 1 ]; then
+            echo "Vulnerabilities found! See above for details."
+            exit 1
+          fi
+
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: moderate
+          comment-summary-in-pr: true
+
+  codeql-analysis:
+    name: CodeQL Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['javascript']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{matrix.language}}"

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.planning/codebase/ARCHITECTURE.md

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