claw-dashboard 1.9.0 → 2.1.0

package/src/cli/import-snapshot.js

@@ -0,0 +1,230 @@
+/**
+ * CLI Import Snapshot Module
+ * Imports dashboard configuration from a snapshot file
+ */
+
+import fs from 'fs';
+import os from 'os';
+import { join, resolve } from 'path';
+import {
+  importSnapshotFromFile,
+  validateSnapshot,
+  mergeSnapshotSettings,
+  getSnapshotSummary,
+  getSnapshotsDirectory,
+  listSnapshots,
+} from '../snapshot.js';
+import { DEFAULT_SETTINGS, PATHS } from '../config.js';
+
+/**
+ * Save settings to file
+ * @param {Object} settings - Settings to save
+ */
+function saveSettings(settings) {
+  try {
+    const settingsPath = PATHS.SETTINGS;
+    const dir = PATHS.OPENCLAW_DIR;
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  } catch (err) {
+    throw new Error(`Failed to save settings: ${err.message}`);
+  }
+}
+
+/**
+ * Run the import-snapshot CLI command
+ * @param {string[]} args - CLI arguments
+ * @returns {number} Exit code
+ */
+export async function runImportSnapshotCli(args) {
+  const jsonOutput = args.includes('--json') || args.includes('-j');
+  const dryRun = args.includes('--dry-run') || args.includes('-d');
+  const force = args.includes('--force') || args.includes('-f');
+  const showHelp = args.includes('--help') || args.includes('-h');
+  const listMode = args.includes('--list') || args.includes('-l');
+
+  // Get file path (first non-flag argument)
+  const filePath = args.find(a => !a.startsWith('-'));
+
+  if (showHelp) {
+    console.log(`
+Import Dashboard Snapshot for Claw Dashboard
+
+Usage: clawdash import-snapshot [path] [options]
+
+Arguments:
+  path              Path to snapshot file (optional with --list)
+
+Options:
+  -l, --list        List available snapshots
+  -d, --dry-run     Validate without applying
+  -f, --force       Skip confirmation
+  -j, --json        Output results as JSON
+  -h, --help        Show this help message
+
+Examples:
+  clawdash import-snapshot --list
+  clawdash import-snapshot ~/my-layout.json
+  clawdash import-snapshot ~/.openclaw/snapshots/claw-snapshot-*.json --dry-run
+  clawdash import-snapshot ~/backup.json --force
+`);
+    return 0;
+  }
+
+  // List mode
+  if (listMode) {
+    const snapshots = listSnapshots();
+    if (jsonOutput) {
+      console.log(JSON.stringify({ snapshots }, null, 2));
+    } else {
+      if (snapshots.length === 0) {
+        console.log('No snapshots found in ~/.openclaw/snapshots/');
+      } else {
+        console.log('Available snapshots:');
+        console.log('');
+        snapshots.forEach((s, i) => {
+          const date = new Date(s.createdAt).toLocaleDateString();
+          console.log(`  ${i + 1}. ${s.name}`);
+          console.log(`     Created: ${date}`);
+          console.log(`     Path: ${s.path}`);
+          if (s.metadata) {
+            console.log(`     Widgets: ${s.metadata.widgetCount}, Plugins: ${s.metadata.pluginCount}`);
+          }
+          console.log('');
+        });
+      }
+    }
+    return 0;
+  }
+
+  // Require file path for import
+  if (!filePath) {
+    if (jsonOutput) {
+      console.log(JSON.stringify({
+        success: false,
+        error: 'File path is required (use --list to see available snapshots)',
+      }, null, 2));
+    } else {
+      console.error('Error: File path is required');
+      console.error('Run with --list to see available snapshots');
+      console.error('Run with --help for usage information');
+    }
+    return 1;
+  }
+
+  try {
+    // Resolve the path
+    let resolvedPath = filePath;
+    if (filePath.startsWith('~')) {
+      resolvedPath = join(os.homedir(), filePath.slice(1));
+    }
+    resolvedPath = resolve(resolvedPath);
+
+    // Import and validate
+    const result = importSnapshotFromFile(resolvedPath);
+
+    if (!result.success) {
+      if (jsonOutput) {
+        console.log(JSON.stringify({
+          success: false,
+          error: result.error,
+          path: resolvedPath,
+        }, null, 2));
+      } else {
+        console.error(`✗ Import failed: ${result.error}`);
+      }
+      return 1;
+    }
+
+    const { snapshot } = result;
+
+    // Dry run mode - just validate and show info
+    if (dryRun) {
+      const summary = getSnapshotSummary(snapshot);
+      if (jsonOutput) {
+        console.log(JSON.stringify({
+          success: true,
+          dryRun: true,
+          path: resolvedPath,
+          snapshot: {
+            name: snapshot.name,
+            description: snapshot.description,
+            version: snapshot.dashboardVersion,
+            schemaVersion: snapshot.schemaVersion,
+            createdAt: snapshot.createdAt,
+            metadata: snapshot.metadata,
+          },
+          summary: summary.split('\n'),
+        }, null, 2));
+      } else {
+        console.log('✓ Snapshot is valid (dry run, no changes applied)');
+        console.log('');
+        console.log(summary);
+      }
+      return 0;
+    }
+
+    // Show summary before applying (unless --force)
+    if (!jsonOutput && !force) {
+      const summary = getSnapshotSummary(snapshot);
+      console.log('Snapshot to import:');
+      console.log('');
+      console.log(summary);
+      console.log('');
+      console.log('Run with --force to apply, or --dry-run to preview');
+      return 0;
+    }
+
+    // Load current settings and merge
+    const currentSettings = { ...DEFAULT_SETTINGS };
+    try {
+      if (fs.existsSync(PATHS.SETTINGS)) {
+        const data = fs.readFileSync(PATHS.SETTINGS, 'utf8');
+        Object.assign(currentSettings, JSON.parse(data));
+      }
+    } catch (err) {
+      // Continue with defaults
+    }
+
+    const mergedSettings = mergeSnapshotSettings(currentSettings, snapshot.settings);
+
+    // Save merged settings
+    saveSettings(mergedSettings);
+
+    if (jsonOutput) {
+      console.log(JSON.stringify({
+        success: true,
+        path: resolvedPath,
+        snapshot: {
+          name: snapshot.name,
+          version: snapshot.dashboardVersion,
+          createdAt: snapshot.createdAt,
+        },
+        applied: Object.keys(snapshot.settings),
+      }, null, 2));
+    } else {
+      console.log('✓ Snapshot imported successfully');
+      console.log(`  Name: ${snapshot.name}`);
+      console.log(`  Version: ${snapshot.dashboardVersion}`);
+      console.log('');
+      console.log('Settings have been merged and saved.');
+      console.log('Restart Claw Dashboard to apply all changes.');
+    }
+
+    return 0;
+  } catch (err) {
+    if (jsonOutput) {
+      console.log(JSON.stringify({
+        success: false,
+        error: err.message,
+      }, null, 2));
+    } else {
+      console.error(`✗ Import error: ${err.message}`);
+    }
+    return 1;
+  }
+}
+
+export default { runImportSnapshotCli };

package/src/cli/index.js

@@ -0,0 +1,14 @@
+/**
+ * CLI Module Index
+ * Centralized export for all CLI command handlers
+ */
+
+export { parseCliArgs } from './args.js';
+export { showHelp } from './help.js';
+export { showVersion } from './version.js';
+export { runValidatePluginCli } from './validate-plugin.js';
+export { runValidateConfigCli } from './validate-config.js';
+export { runExportSnapshotCli } from './export-snapshot.js';
+export { runImportSnapshotCli } from './import-snapshot.js';
+export { runListTemplatesCli } from './list-templates.js';
+export { runExportScheduleCli } from './export-schedule.js';

package/src/cli/list-templates.js

@@ -0,0 +1,69 @@
+/**
+ * CLI List Templates Module
+ * Lists available widget templates for scaffolding
+ */
+
+import { listTemplates } from '../plugin-scaffold.js';
+
+/**
+ * Run the list-templates CLI command
+ * @param {string[]} args - CLI arguments
+ * @returns {number} Exit code
+ */
+export async function runListTemplatesCli(args) {
+  const showHelp = args.includes('--help') || args.includes('-h');
+
+  if (showHelp) {
+    console.log(`
+List Available Widget Templates
+
+Usage: clawdash list-templates [options]
+
+Options:
+  -j, --json        Output as JSON
+  -h, --help        Show this help message
+
+Examples:
+  clawdash list-templates
+  clawdash list-templates --json
+`);
+    return 0;
+  }
+
+  const jsonOutput = args.includes('--json') || args.includes('-j');
+
+  try {
+    const templates = listTemplates();
+
+    if (jsonOutput) {
+      console.log(JSON.stringify(templates, null, 2));
+    } else {
+      console.log('');
+      console.log('╔══════════════════════════════════════════════════════════════╗');
+      console.log('║           Available Widget Templates                         ║');
+      console.log('╚══════════════════════════════════════════════════════════════╝');
+      console.log('');
+
+      templates.forEach((template, index) => {
+        console.log(`  ${index + 1}. ${template.name}`);
+        console.log(`     ID: ${template.id}`);
+        console.log(`     ${template.description}`);
+        console.log('');
+      });
+
+      console.log('Usage:');
+      console.log('  clawdash create-plugin <name> --template <id>');
+      console.log('');
+      console.log('Example:');
+      console.log('  clawdash create-plugin my-widget --template api');
+      console.log('');
+    }
+
+    return 0;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return 1;
+  }
+}
+
+export default { runListTemplatesCli };

package/src/cli/validate-config.js

@@ -0,0 +1,76 @@
+/**
+ * CLI Validate Config Module
+ * Validates dashboard configuration files
+ */
+
+import os from 'os';
+import { resolve, join } from 'path';
+import { validateConfigFile, formatConfigValidationResult, getDefaultConfigPath } from '../config-validator.js';
+
+/**
+ * Run the validate-config CLI command
+ * @param {string[]} args - CLI arguments
+ * @returns {number} Exit code
+ */
+export async function runValidateConfigCli(args) {
+  const configPath = args[0];
+  const jsonOutput = args.includes('--json') || args.includes('-j');
+  const showHelp = args.includes('--help') || args.includes('-h');
+  const strict = args.includes('--strict') || args.includes('-s');
+
+  if (showHelp) {
+    console.log(`
+Validate Dashboard Configuration for Claw Dashboard
+
+Usage: clawdash validate-config [path] [options]
+
+Arguments:
+  path                Path to configuration file (optional)
+                      Defaults to: ~/.openclaw/dashboard-settings.json
+
+Options:
+  -j, --json          Output results as JSON
+  -s, --strict        Fail on unknown properties
+  -h, --help          Show this help message
+
+Examples:
+  clawdash validate-config
+  clawdash validate-config ~/.openclaw/dashboard-settings.json
+  clawdash validate-config ./my-config.json --json
+  clawdash validate-config --strict
+`);
+    return 0;
+  }
+
+  // Determine the config file path
+  const targetPath = configPath || getDefaultConfigPath();
+
+  // Resolve the path (handle ~ expansion)
+  let resolvedPath = targetPath;
+  if (targetPath.startsWith('~')) {
+    resolvedPath = join(os.homedir(), targetPath.slice(1));
+  }
+  resolvedPath = resolve(resolvedPath);
+
+  // Validate the configuration
+  const result = validateConfigFile(resolvedPath, { strict });
+
+  // Output results
+  if (jsonOutput) {
+    const output = {
+      valid: result.valid,
+      path: resolvedPath,
+      errors: result.errors,
+      warnings: result.warnings,
+      info: result.info,
+      stats: result.stats,
+    };
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log(formatConfigValidationResult(result, resolvedPath));
+  }
+
+  return result.valid ? 0 : 1;
+}
+
+export default { runValidateConfigCli };

package/src/cli/validate-plugin.js

@@ -0,0 +1,187 @@
+/**
+ * CLI Validate Plugin Module
+ * Validates plugin.json manifest files
+ */
+
+import fs from 'fs';
+import os from 'os';
+import { dirname, join, resolve } from 'path';
+import { validateManifest, validatePluginIdFormat } from '../plugin-manifest-validator.js';
+
+/**
+ * Run the validate-plugin CLI command
+ * @param {string[]} args - CLI arguments
+ * @returns {number} Exit code
+ */
+export async function runValidatePluginCli(args) {
+  const pluginPath = args[0];
+  const jsonOutput = args.includes('--json') || args.includes('-j');
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const showHelp = args.includes('--help') || args.includes('-h');
+
+  if (showHelp) {
+    console.log(`
+Validate Plugin Manifest for Claw Dashboard
+
+Usage: clawdash validate-plugin <path> [options]
+
+Arguments:
+  path              Path to plugin.json file or plugin directory
+
+Options:
+  -j, --json        Output results as JSON
+  -v, --verbose     Show detailed output including code analysis
+  -h, --help        Show this help message
+
+Examples:
+  clawdash validate-plugin ./my-widget/plugin.json
+  clawdash validate-plugin ~/.openclaw/plugins/my-widget
+  clawdash validate-plugin ./my-widget --json
+  clawdash validate-plugin ./my-widget --verbose
+`);
+    return 0;
+  }
+
+  if (!pluginPath) {
+    console.error('Error: Path is required');
+    console.error('Run with --help for usage information');
+    return 1;
+  }
+
+  // Resolve the path
+  let resolvedPath = pluginPath;
+  if (pluginPath.startsWith('~')) {
+    resolvedPath = join(os.homedir(), pluginPath.slice(1));
+  }
+  resolvedPath = resolve(resolvedPath);
+
+  // Check if path exists
+  if (!fs.existsSync(resolvedPath)) {
+    const result = {
+      valid: false,
+      error: `Path does not exist: ${pluginPath}`,
+    };
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.error}`);
+    }
+    return 1;
+  }
+
+  // Determine the manifest file path
+  let manifestPath = resolvedPath;
+  const stats = fs.statSync(resolvedPath);
+  if (stats.isDirectory()) {
+    manifestPath = join(resolvedPath, 'plugin.json');
+    if (!fs.existsSync(manifestPath)) {
+      const result = {
+        valid: false,
+        path: resolvedPath,
+        error: `No plugin.json found in directory: ${pluginPath}`,
+      };
+      if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Error: ${result.error}`);
+      }
+      return 1;
+    }
+  }
+
+  // Read and parse the manifest
+  let manifest;
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf8');
+    manifest = JSON.parse(content);
+  } catch (err) {
+    const result = {
+      valid: false,
+      path: manifestPath,
+      error: `Failed to read/parse plugin.json: ${err.message}`,
+    };
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Error: ${result.error}`);
+    }
+    return 1;
+  }
+
+  // Validate the manifest
+  const validation = validateManifest(manifest);
+
+  // Also validate the plugin ID if present
+  let idValidation = { valid: true };
+  if (manifest.id) {
+    idValidation = validatePluginIdFormat(manifest.id);
+  }
+
+  const result = {
+    valid: validation.valid && idValidation.valid,
+    path: manifestPath,
+    errors: validation.errors,
+    id: manifest.id || null,
+    name: manifest.name || null,
+    version: manifest.version || null,
+  };
+
+  if (!idValidation.valid) {
+    result.errors.push(`Invalid plugin ID: ${idValidation.error}`);
+  }
+
+  // Enhanced validation for verbose mode
+  let warnings = [];
+  if (verbose && result.valid) {
+    // Check for recommended fields
+    if (!manifest.description || manifest.description === 'A custom widget plugin for Claw Dashboard') {
+      warnings.push('Add a meaningful description to your plugin');
+    }
+    if (!manifest.author) {
+      warnings.push('Missing author - recommended for plugin distribution');
+    }
+    if (!manifest.config || Object.keys(manifest.config).length === 0) {
+      warnings.push('Consider adding configurable options to your plugin');
+    }
+    // Check for index.js if it's a widget type
+    if (manifest.type === 'widget') {
+      const indexPath = stats.isDirectory() ? join(resolvedPath, 'index.js') : join(dirname(resolvedPath), 'index.js');
+      if (!fs.existsSync(indexPath)) {
+        result.valid = false;
+        result.errors.push('Widget plugins must have an index.js file');
+      }
+    }
+  }
+
+  // Output results
+  if (jsonOutput) {
+    if (verbose) {
+      result.warnings = warnings;
+    }
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (result.valid) {
+      console.log(`✓ Valid plugin manifest: ${manifestPath}`);
+      console.log(`  ID: ${result.id}`);
+      console.log(`  Name: ${result.name}`);
+      console.log(`  Version: ${result.version}`);
+      if (verbose && warnings.length > 0) {
+        console.log('');
+        console.log('Warnings:');
+        warnings.forEach(warning => {
+          console.log(`  ⚠ ${warning}`);
+        });
+      }
+    } else {
+      console.error(`✗ Invalid plugin manifest: ${manifestPath}`);
+      console.error('  Errors:');
+      result.errors.forEach(error => {
+        console.error(`    - ${error}`);
+      });
+    }
+  }
+
+  return result.valid ? 0 : 1;
+}
+
+export default { runValidatePluginCli };

package/src/cli/version.js

@@ -0,0 +1,15 @@
+/**
+ * CLI Version Module
+ * Displays version information for Claw Dashboard
+ */
+
+import { DASHBOARD_VERSION } from '../config.js';
+
+/**
+ * Display version information
+ */
+export function showVersion() {
+  console.log(`clawdash ${DASHBOARD_VERSION}`);
+}
+
+export default { showVersion };