claw-dashboard 1.9.0 → 2.1.0

package/esbuild.config.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * ESBuild configuration for claw-dashboard
+ * Bundles the application for distribution
+ */
+
+import * as esbuild from 'esbuild';
+import { readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Get current version from package.json
+ * @returns {string} Current version
+ */
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+/**
+ * Create banner with version info
+ * @returns {string} Banner comment
+ */
+function createBanner() {
+  const version = getVersion();
+  return `#!/usr/bin/env node
+/**
+ * claw-dashboard v${version}
+ * A beautiful console dashboard for monitoring OpenClaw instances
+ *
+ * License: MIT
+ * Repository: https://github.com/spleck/claw-dashboard
+ */
+`;
+}
+
+/**
+ * Build configuration
+ */
+const buildConfig = {
+  entryPoints: ['index.js'],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  outfile: 'dist/clawdash',
+  format: 'esm',
+  banner: {
+    js: createBanner(),
+  },
+  // External dependencies that should not be bundled
+  // (native modules, large dependencies, or things with dynamic requires)
+  external: [
+    'blessed',
+    'blessed-contrib',
+    'systeminformation',
+  ],
+  minify: true,
+  sourcemap: false,
+  metafile: true,
+  logLevel: 'info',
+};
+
+/**
+ * Development build configuration
+ */
+const devConfig = {
+  ...buildConfig,
+  minify: false,
+  sourcemap: true,
+  outfile: 'dist/clawdash.dev',
+};
+
+/**
+ * Run build
+ * @param {Object} config - Build configuration
+ * @param {string} mode - Build mode (production or development)
+ */
+async function build(config, mode = 'production') {
+  console.log(`Building for ${mode}...`);
+  console.log(`Version: ${getVersion()}`);
+
+  try {
+    const result = await esbuild.build({
+      ...config,
+      write: false,
+    });
+
+    // Add shebang if not present and make executable
+    let output = result.outputFiles[0].text;
+    if (!output.startsWith('#!')) {
+      output = '#!/usr/bin/env node\n' + output;
+    }
+
+    // Write the output file
+    writeFileSync(config.outfile, output, { mode: 0o755 });
+
+    // Write metafile for analysis
+    if (result.metafile) {
+      writeFileSync(
+        config.outfile + '.meta.json',
+        JSON.stringify(result.metafile, null, 2)
+      );
+    }
+
+    // Calculate bundle size
+    const bytes = Buffer.byteLength(output, 'utf8');
+    const kb = (bytes / 1024).toFixed(2);
+
+    console.log(`✓ Build successful: ${config.outfile} (${kb} KB)`);
+
+    // Print bundle analysis
+    if (result.metafile) {
+      const outputs = result.metafile.outputs;
+      const outputKey = Object.keys(outputs).find(k => k.endsWith('.js') || k.endsWith('clawdash'));
+      if (outputKey) {
+        const output = outputs[outputKey];
+        console.log(`  - Bundle size: ${(output.bytes / 1024).toFixed(2)} KB`);
+        console.log(`  - Exports: ${output.exports.join(', ')}`);
+      }
+    }
+
+    return true;
+  } catch (error) {
+    console.error('✗ Build failed:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const args = process.argv.slice(2);
+  const isDev = args.includes('--dev') || args.includes('-d');
+  const shouldAnalyze = args.includes('--analyze') || args.includes('-a');
+
+  const config = isDev ? devConfig : buildConfig;
+
+  const success = await build(config, isDev ? 'development' : 'production');
+
+  if (success && shouldAnalyze) {
+    console.log('\nBundle analysis written to:', config.outfile + '.meta.json');
+  }
+
+  process.exit(success ? 0 : 1);
+}
+
+// Run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main();
+}
+
+export { build, buildConfig, devConfig };

package/eslint.config.js

@@ -0,0 +1,56 @@
+import js from '@eslint/js';
+
+export default [
+  js.configs.recommended,
+  {
+    files: ['src/**/*.js'],
+    ignores: ['src/workers/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        clearTimeout: 'readonly',
+        setImmediate: 'readonly',
+        clearImmediate: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        exports: 'readonly',
+        global: 'readonly'
+      }
+    },
+    rules: {
+      'no-unused-vars': 'off',
+      'no-empty': 'off',
+      'no-control-regex': 'off',
+      'no-undef': 'off',
+      'semi': ['error', 'always'],
+      'quotes': ['error', 'single'],
+      'prefer-const': 'off',
+      'no-var': 'off',
+      'preserve-caught-error': 'off'
+    }
+  },
+  {
+    files: ['tests/**/*.js'],
+    languageOptions: {
+      globals: {
+        describe: 'readonly',
+        test: 'readonly',
+        expect: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        jest: 'readonly'
+      }
+    }
+  }
+];

package/examples/plugins/README.md

@@ -0,0 +1,122 @@
+# Plugin Examples
+
+This directory contains example plugins demonstrating the Claw Dashboard widget plugin system.
+
+## Available Examples
+
+### hello-world
+
+The simplest possible widget example demonstrating:
+- Basic widget structure extending BaseWidget
+- Required lifecycle methods (init, create, getData, render, destroy)
+- Simple configuration handling
+- Basic blessed UI creation
+
+### weather-widget
+
+A weather widget that demonstrates:
+- Plugin manifest structure
+- Widget class extending BaseWidget
+- UI creation with blessed
+- Simulated data fetching and rendering
+- Configuration handling with defaults
+
+### api-status
+
+An API integration widget demonstrating:
+- Fetching data from external APIs
+- Error handling and retry logic
+- Loading states and timeout handling
+- **Environment variable configuration** (`${ENV_VAR:-default}`)
+- **Config versioning** (`__version: "1.1.0"`)
+- Configurable refresh intervals
+- Request statistics tracking
+
+### system-metrics-chart
+
+A data visualization widget demonstrating:
+- **blessed-contrib line charts** for time-series data
+- Multiple metric support (CPU, memory, network)
+- Dynamic data updates with configurable refresh
+- History management for rolling data windows
+- Theme integration for chart styling
+
+## Installation
+
+To install an example plugin:
+
+```bash
+# Copy the plugin to the plugins directory
+cp -r hello-world ~/.openclaw/plugins/
+# or
+cp -r weather-widget ~/.openclaw/plugins/
+# or
+cp -r api-status ~/.openclaw/plugins/
+# or
+cp -r system-metrics-chart ~/.openclaw/plugins/
+
+# Restart clawdash
+clawdash
+```
+
+## Example Comparison
+
+| Example | Complexity | Demonstrates |
+|---------|------------|--------------|
+| `hello-world` | Beginner | Basic structure, lifecycle hooks |
+| `weather-widget` | Beginner | Configuration, data fetching |
+| `api-status` | Intermediate | API integration, error handling |
+| `system-metrics-chart` | Advanced | Data visualization, charts, history |
+
+## Creating Your Own Plugin
+
+1. Copy the example that best matches your use case:
+   - Start with `hello-world` for simple widgets
+   - Use `weather-widget` for data-driven widgets
+   - Use `api-status` for external API integration
+   - Use `system-metrics-chart` for data visualization
+
+2. Update `plugin.json` with your plugin details
+3. Modify `index.js` to implement your widget logic
+4. Install to `~/.openclaw/plugins/`
+
+## Environment Variable Configuration
+
+Widget configs support environment variable interpolation using the syntax:
+
+```json
+{
+  "config": {
+    "__version": "1.0.0",
+    "apiUrl": "${API_URL:-https://default.example.com}",
+    "apiKey": "${API_KEY}",
+    "timeout": "${TIMEOUT:-5000}"
+  }
+}
+```
+
+- `${VAR}` - Uses the environment variable value, or keeps the literal if not set
+- `${VAR:-default}` - Uses the environment variable, or the default value if not set
+
+Set environment variables before running clawdash:
+
+```bash
+export API_URL="https://api.example.com"
+export API_KEY="your-secret-key"
+clawdash
+```
+
+## Config Versioning
+
+Widget configs can include a `__version` field to enable automatic migration when the dashboard is updated:
+
+```json
+{
+  "config": {
+    "__version": "1.0.0",
+    "setting": "value"
+  }
+}
+```
+
+See the full documentation in `docs/PLUGINS.md`.

package/examples/plugins/api-status/index.js

@@ -0,0 +1,294 @@
+/**
+ * API Status Widget Plugin
+ * Demonstrates API integration patterns including:
+ * - Fetching data from external APIs
+ * - Error handling and retry logic
+ * - Loading states
+ * - Configurable refresh intervals
+ * - Timeout handling
+ */
+
+import { BaseWidget } from '../../../src/widgets/plugin-api.js';
+
+/**
+ * API Status Widget - Fetches and displays data from an external API
+ */
+export default class ApiStatusWidget extends BaseWidget {
+  constructor(options = {}) {
+    super(options);
+    this.name = options.name || 'API Status';
+    this.description = 'Fetches data from external API';
+
+    // Internal state
+    this.loading = false;
+    this.error = null;
+    this.lastFetch = null;
+    this.refreshTimer = null;
+    this.data = null;
+  }
+
+  /**
+   * Initialize the widget
+   */
+  async init() {
+    this.log('info', 'API Status widget initialized');
+    return true;
+  }
+
+  /**
+   * Create the widget UI
+   * @param {Object} screen - Blessed screen object
+   * @param {Object} theme - Theme colors
+   */
+  async create(screen, theme = {}) {
+    const C = theme.colors || {};
+    const blessed = await import('blessed');
+
+    this.screen = screen;
+    this.theme = theme;
+
+    // Main container
+    this.box = blessed.default.box({
+      parent: screen,
+      width: '50%',
+      height: 7,
+      border: { type: 'line' },
+      label: ' API STATUS ',
+      style: { border: { fg: C.cyan || 'cyan' } },
+    });
+
+    // Status line (shows loading/success/error)
+    this.statusText = blessed.default.text({
+      parent: this.box,
+      top: 0,
+      left: 1,
+      content: 'Initializing...',
+      style: { fg: C.gray || 'gray' },
+    });
+
+    // Data content line
+    this.contentText = blessed.default.text({
+      parent: this.box,
+      top: 1,
+      left: 1,
+      content: '',
+      style: { fg: C.white || 'white' },
+      wrap: true,
+    });
+
+    // Last updated line
+    this.updatedText = blessed.default.text({
+      parent: this.box,
+      top: 3,
+      left: 1,
+      content: 'Never updated',
+      style: { fg: C.gray || 'gray' },
+    });
+
+    // Stats line (shows request count, errors)
+    this.statsText = blessed.default.text({
+      parent: this.box,
+      top: 4,
+      left: 1,
+      content: 'Requests: 0 | Errors: 0',
+      style: { fg: C.gray || 'gray' },
+    });
+
+    this.loaded = true;
+    this.log('debug', 'API Status widget UI created');
+
+    // Start auto-refresh if configured
+    const refreshInterval = this.config.refreshInterval || 60000;
+    if (refreshInterval > 0) {
+      this.startAutoRefresh(refreshInterval);
+    }
+
+    return this;
+  }
+
+  /**
+   * Fetch data from the configured API
+   * Includes retry logic and timeout handling
+   */
+  async getData() {
+    const apiUrl = this.config.apiUrl || 'https://api.github.com/zen';
+    const timeout = this.config.timeout || 5000;
+    const maxRetries = this.config.retries || 3;
+
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        this.loading = true;
+        this.error = null;
+        this.updateStatus('loading', `Fetching (attempt ${attempt}/${maxRetries})...`);
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+        const response = await fetch(apiUrl, {
+          signal: controller.signal,
+          headers: {
+            'User-Agent': 'Claw-Dashboard-Widget/1.0',
+          },
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        // Handle different response types
+        const contentType = response.headers.get('content-type') || '';
+        let data;
+
+        if (contentType.includes('application/json')) {
+          data = await response.json();
+        } else {
+          data = await response.text();
+        }
+
+        this.loading = false;
+        this.lastFetch = new Date();
+
+        return {
+          success: true,
+          data,
+          timestamp: this.lastFetch.toISOString(),
+          apiUrl,
+        };
+      } catch (err) {
+        lastError = err;
+        this.log('warn', `API fetch attempt ${attempt} failed: ${err.message}`);
+
+        // Don't retry on abort (timeout)
+        if (err.name === 'AbortError') {
+          break;
+        }
+
+        // Wait before retrying (exponential backoff)
+        if (attempt < maxRetries) {
+          await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+        }
+      }
+    }
+
+    // All retries failed
+    this.loading = false;
+    this.error = lastError;
+
+    return {
+      success: false,
+      error: lastError?.message || 'Unknown error',
+      timestamp: new Date().toISOString(),
+      apiUrl,
+    };
+  }
+
+  /**
+   * Render the widget with fetched data
+   * @param {Object} result - Result from getData()
+   */
+  render(result) {
+    if (!this.box) return;
+
+    if (result.success) {
+      this.updateStatus('success', 'Connected');
+
+      // Format the data for display
+      let content;
+      if (typeof result.data === 'object') {
+        content = JSON.stringify(result.data, null, 0).slice(0, 100);
+      } else {
+        content = String(result.data).slice(0, 100);
+      }
+
+      this.contentText.setContent(content);
+      this.contentText.style.fg = this.theme?.colors?.white || 'white';
+    } else {
+      this.updateStatus('error', `Error: ${result.error}`);
+      this.contentText.setContent('Unable to fetch data');
+      this.contentText.style.fg = this.theme?.colors?.red || 'red';
+    }
+
+    // Update timestamp
+    this.updatedText.setContent(`Last: ${result.timestamp || 'Never'}`);
+
+    // Update stats
+    const stats = this.getStats();
+    this.statsText.setContent(`Requests: ${stats.requests} | Errors: ${stats.errors}`);
+  }
+
+  /**
+   * Update the status indicator
+   * @private
+   */
+  updateStatus(status, message) {
+    const colors = {
+      loading: this.theme?.colors?.yellow || 'yellow',
+      success: this.theme?.colors?.green || 'green',
+      error: this.theme?.colors?.red || 'red',
+    };
+
+    this.statusText.setContent(message);
+    this.statusText.style.fg = colors[status] || 'white';
+  }
+
+  /**
+   * Track request statistics
+   * @private
+   */
+  getStats() {
+    if (!this._stats) {
+      this._stats = { requests: 0, errors: 0 };
+    }
+    return this._stats;
+  }
+
+  /**
+   * Start auto-refresh timer
+   * @param {number} intervalMs - Refresh interval in milliseconds
+   */
+  startAutoRefresh(intervalMs) {
+    this.stopAutoRefresh();
+    this.refreshTimer = setInterval(() => {
+      if (!this.loading) {
+        this.getData()
+          .then(data => this.render(data))
+          .catch(err => this.log('error', `Auto-refresh failed: ${err.message}`));
+      }
+    }, intervalMs);
+
+    this.log('debug', `Auto-refresh started (${intervalMs}ms interval)`);
+  }
+
+  /**
+   * Stop auto-refresh timer
+   */
+  stopAutoRefresh() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+      this.log('debug', 'Auto-refresh stopped');
+    }
+  }
+
+  /**
+   * Destroy the widget
+   */
+  async destroy() {
+    this.stopAutoRefresh();
+
+    if (this.box) {
+      this.box.destroy();
+      this.box = null;
+    }
+
+    this.loaded = false;
+    this.log('info', 'API Status widget destroyed');
+  }
+}
+
+// Export named export for flexibility
+export { ApiStatusWidget };

package/examples/plugins/api-status/plugin.json

@@ -0,0 +1,19 @@
+{
+  "id": "example-api-status",
+  "name": "API Status",
+  "description": "Example widget demonstrating API integration with error handling, loading states, and environment variable configuration",
+  "version": "1.1.0",
+  "author": "Claw Dashboard Team",
+  "category": "example",
+  "type": "widget",
+  "lazyLoad": true,
+  "priority": 100,
+  "config": {
+    "__version": "1.1.0",
+    "apiUrl": "${API_STATUS_URL:-https://api.github.com/zen}",
+    "apiKey": "${API_STATUS_KEY:-}",
+    "refreshInterval": "${API_STATUS_REFRESH:-60000}",
+    "timeout": "${API_STATUS_TIMEOUT:-5000}",
+    "retries": "${API_STATUS_RETRIES:-3}"
+  }
+}