pal-explorer-cli 0.4.12 → 0.4.14

package/lib/commands/server.js

@@ -1,350 +1,350 @@
-import chalk from 'chalk';
-import config from '../utils/config.js';
-import { spawn, exec } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import fs from 'fs';
-import readline from 'readline';
-import { getPrimaryServer, getServers, checkServer, verifyAllServers, fetchServerKey, acceptServerKey, keyFingerprint } from '../core/discoveryClient.js';
-import { refreshServerList, healthCheckServers, getServerRoles, SERVER_ROLES, isWriteTrusted } from '../core/serverList.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-function confirm(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer.trim().toLowerCase() === 'y'); }));
-}
-
-async function installWindows() {
-  const pePath = process.execPath;
-  const scriptPath = path.resolve(__dirname, '../../bin/pal.js');
-  const taskName = 'PalexplorerServe';
-  const cmd = `schtasks /create /tn "${taskName}" /tr "\\"${pePath}\\" \\"${scriptPath}\\" serve" /sc onlogon /rl limited /f`;
-
-  return new Promise((resolve) => {
-    exec(cmd, (err, stdout, stderr) => {
-      if (err) {
-        console.log(chalk.yellow('Could not create scheduled task automatically.'));
-        console.log(chalk.gray('To install manually, create a scheduled task:'));
-        console.log(chalk.gray(`  schtasks /create /tn "${taskName}" /tr "pe serve" /sc onlogon /rl limited`));
-        return resolve();
-      }
-      console.log(chalk.green(`Scheduled task "${taskName}" created. pe serve will run on login.`));
-      resolve();
-    });
-  });
-}
-
-async function installLinux() {
-  const serviceSource = path.resolve(__dirname, '../../installer/linux/palexplorer.service');
-  const serviceDir = path.join(process.env.HOME, '.config/systemd/user');
-  const serviceDest = path.join(serviceDir, 'palexplorer.service');
-
-  try {
-    fs.mkdirSync(serviceDir, { recursive: true });
-
-    if (fs.existsSync(serviceSource)) {
-      fs.copyFileSync(serviceSource, serviceDest);
-    } else {
-      const serviceContent = `[Unit]
-Description=Palexplorer P2P File Sharing Daemon
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-ExecStart=${process.execPath} ${path.resolve(__dirname, '../../bin/pal.js')} serve
-Restart=on-failure
-RestartSec=10
-Environment=NODE_ENV=production
-
-[Install]
-WantedBy=default.target
-`;
-      fs.writeFileSync(serviceDest, serviceContent);
-    }
-
-    console.log(chalk.green(`Service file written to ${serviceDest}`));
-    console.log(chalk.gray('Enable with:'));
-    console.log(chalk.gray('  systemctl --user daemon-reload'));
-    console.log(chalk.gray('  systemctl --user enable --now palexplorer'));
-  } catch (err) {
-    console.log(chalk.red('Failed to install systemd service:'), err.message);
-  }
-}
-
-async function installMacOS() {
-  const plistDir = path.join(process.env.HOME, 'Library/LaunchAgents');
-  const plistPath = path.join(plistDir, 'com.palexplorer.serve.plist');
-  const pePath = process.execPath;
-  const scriptPath = path.resolve(__dirname, '../../bin/pal.js');
-
-  const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.palexplorer.serve</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>${pePath}</string>
-        <string>${scriptPath}</string>
-        <string>serve</string>
-    </array>
-    <key>RunAtLoad</key>
-    <true/>
-    <key>KeepAlive</key>
-    <true/>
-    <key>StandardOutPath</key>
-    <string>/tmp/palexplorer.log</string>
-    <key>StandardErrorPath</key>
-    <string>/tmp/palexplorer.err</string>
-</dict>
-</plist>
-`;
-
-  try {
-    fs.mkdirSync(plistDir, { recursive: true });
-    fs.writeFileSync(plistPath, plistContent);
-    console.log(chalk.green(`LaunchAgent written to ${plistPath}`));
-    console.log(chalk.gray('Load with:'));
-    console.log(chalk.gray(`  launchctl load ${plistPath}`));
-  } catch (err) {
-    console.log(chalk.red('Failed to install LaunchAgent:'), err.message);
-  }
-}
-
-export default function serverCommand(program) {
-  const server = program.command('server').description('provision and manage Palexplorer server nodes')
-    .addHelpText('after', `
-Examples:
-  $ pe server install               Install as system service
-  $ pe server status                Check service status
-  $ pe server config                Show server configuration
-  $ pe server register              Register device with discovery server
-`);
-
-  server
-    .command('install')
-    .description('install pe serve as a background service (cross-platform)')
-    .action(async () => {
-      const platform = process.platform;
-      console.log(chalk.blue(`Installing Palexplorer service for ${platform}...`));
-
-      if (platform === 'win32') {
-        await installWindows();
-      } else if (platform === 'linux') {
-        await installLinux();
-      } else if (platform === 'darwin') {
-        await installMacOS();
-      } else {
-        console.log(chalk.red(`Unsupported platform: ${platform}`));
-      }
-    });
-
-  server
-    .command('config <key> <value>')
-    .description('set server-specific operational parameters')
-    .action((key, value) => {
-      // Validate common keys
-      const validKeys = ['port', 'storage_path', 'max_connections', 'bandwidth_cap'];
-      if (!validKeys.includes(key)) {
-        console.log(chalk.yellow(`Warning: '${key}' is not a standard server parameter. Setting anyway.`));
-      }
-
-      const settings = config.get('settings') || {};
-      settings[key] = value;
-      config.set('settings', settings);
-      console.log(chalk.green(`✔ Server configuration updated: ${key} = ${value}`));
-    });
-
-  server
-    .command('register <handle>')
-    .description('register this server node with a handle in the Discovery Network')
-    .action(async (handle) => {
-      const DISCOVERY_URL = getPrimaryServer();
-      const { getIdentity, setIdentityHandle } = await import('../core/identity.js');
-      const identity = await getIdentity();
-      if (!identity || !identity.privateKey) {
-        console.log(chalk.red('No identity found. Run `pe init <name>` first.'));
-        return;
-      }
-
-      const sodium = (await import('sodium-native')).default;
-      const privateKey = Buffer.from(identity.privateKey, 'hex');
-
-      try {
-        console.log(chalk.blue(`Registering handle @${handle} on discovery server...`));
-        // Step 1: Get challenge
-        const chalRes = await fetch(`${DISCOVERY_URL}/register/challenge`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ handle, publicKey: identity.publicKey })
-        });
-        const chalData = await chalRes.json();
-        if (!chalData.challengeId) {
-          console.log(chalk.red(`Challenge failed: ${chalData.error || 'unknown error'}`));
-          return;
-        }
-
-        // Step 2: Sign challenge and register
-        const message = `register:${handle}:${chalData.nonce}`;
-        const sig = Buffer.alloc(sodium.crypto_sign_BYTES);
-        sodium.crypto_sign_detached(sig, Buffer.from(message), privateKey);
-
-        const regRes = await fetch(`${DISCOVERY_URL}/register`, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ handle, publicKey: identity.publicKey, challengeId: chalData.challengeId, signature: sig.toString('hex') })
-        });
-        const result = await regRes.json();
-        if (result.success) {
-          console.log(chalk.green(`✔ Node registered as @${handle}`));
-          setIdentityHandle(handle);
-        } else {
-          console.log(chalk.red(`Registration failed: ${result.error}`));
-        }
-      } catch {
-        console.log(chalk.red(`Could not reach discovery server at ${DISCOVERY_URL}`));
-      }
-    });
-
-  server
-    .command('status')
-    .description('check server health and network connectivity')
-    .action(() => {
-      const identity = config.get('identity');
-      const settings = config.get('settings') || {};
-      const shares = config.get('shares') || [];
-
-      console.log('');
-      console.log(chalk.cyan('Palexplorer Server Status:'));
-      console.log(`- Node Identity: ${identity ? chalk.green(identity.name) : chalk.red('Not Initialized')}`);
-      console.log(`- Public Key: ${identity ? chalk.gray(identity.publicKey) : 'N/A'}`);
-      console.log(`- Active Shares: ${chalk.white(shares.length)}`);
-      console.log(`- Bound Port: ${chalk.white(settings.port || 'Auto (1900)')}`);
-      console.log(`- OS: ${chalk.white(process.platform)}`);
-      console.log('');
-    });
-
-  server
-    .command('list')
-    .description('list all configured discovery servers with health status and roles')
-    .action(async () => {
-      const servers = getServers();
-      console.log('');
-      console.log(chalk.cyan('Discovery Servers:'));
-      const checks = await Promise.all(servers.map(s => checkServer(s)));
-      for (let i = 0; i < checks.length; i++) {
-        const c = checks[i];
-        const primary = i === 0 ? chalk.cyan(' (primary)') : '';
-        const status = c.reachable ? chalk.green('reachable') : chalk.red('down');
-        const meta = getServerRoles(c.url);
-        const rolesStr = chalk.gray(`[${meta.roles.join(', ')}]`);
-        const addedBy = meta.addedBy !== 'bootstrap' ? chalk.gray(` (${meta.addedBy})`) : '';
-        const trust = isWriteTrusted(c.url) ? chalk.green('read+write') : chalk.yellow('read-only');
-        console.log(`  ${i + 1}. ${chalk.white(c.url)} — ${status}${primary} ${rolesStr} ${trust}${addedBy}`);
-      }
-      console.log('');
-    });
-
-  server
-    .command('refresh')
-    .description('fetch and update server list from all known servers')
-    .action(async () => {
-      console.log(chalk.blue('Refreshing server list...'));
-      const servers = await refreshServerList((step) => {
-        console.log(chalk.gray(`  ${step}`));
-      });
-      console.log(chalk.green(`\nFound ${servers.length} server(s). Running health checks...`));
-      const checks = await healthCheckServers(servers);
-      for (const c of checks) {
-        const status = c.reachable
-          ? chalk.green(`reachable (${c.latencyMs}ms)`)
-          : chalk.red('unreachable');
-        console.log(`  ${chalk.white(c.url)} — ${status}`);
-      }
-      console.log('');
-    });
-
-  server
-    .command('roles <url>')
-    .description('query and display a server\'s supported roles')
-    .action(async (url) => {
-      const normalized = url.replace(/\/+$/, '');
-      try {
-        const parsed = new URL(normalized);
-        const host = parsed.hostname;
-        if (host === 'localhost' || host.startsWith('127.') || host.startsWith('10.') ||
-            host.startsWith('192.168.') || host.startsWith('169.254.') || host === '0.0.0.0' ||
-            /^172\.(1[6-9]|2\d|3[01])\./.test(host)) {
-          console.log(chalk.yellow('⚠ Warning: querying a private/local network address.'));
-        }
-        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-          console.log(chalk.red('Server URL must use http:// or https://'));
-          process.exitCode = 1;
-          return;
-        }
-      } catch { /* URL validation is best-effort */ }
-      console.log(chalk.blue(`Querying roles for ${normalized}...`));
-      try {
-        const res = await fetch(`${normalized}/status`, { signal: AbortSignal.timeout(5000) });
-        if (!res.ok) {
-          console.log(chalk.red(`Server returned status ${res.status}`));
-          return;
-        }
-        const data = await res.json();
-        console.log('');
-        console.log(chalk.cyan(`Server: ${normalized}`));
-        console.log(`  Status: ${chalk.green(data.status || 'unknown')}`);
-        console.log(`  Version: ${chalk.white(data.version || 'unknown')}`);
-        if (Array.isArray(data.roles)) {
-          console.log(`  Roles: ${chalk.white(data.roles.join(', '))}`);
-        } else {
-          console.log(`  Roles: ${chalk.yellow('not reported (legacy server, assumed all)')}`);
-        }
-        if (data.network) {
-          console.log(`  Network: ${chalk.white(data.network)}`);
-        }
-        console.log('');
-      } catch (err) {
-        console.log(chalk.red(`Could not reach server: ${err.message}`));
-      }
-    });
-
-  server
-    .command('verify')
-    .description('verify pinned keys for all configured servers')
-    .action(async () => {
-      console.log(chalk.blue('Verifying server keys...\n'));
-      const results = await verifyAllServers();
-
-      for (const r of results) {
-        if (r.status === 'ok') {
-          console.log(`  ${chalk.green('✔')} ${chalk.white(r.url)} — ${chalk.green('key verified')} (${chalk.cyan(r.fingerprint)})`);
-        } else if (r.status === 'key-changed') {
-          console.log(`  ${chalk.red('✘')} ${chalk.white(r.url)} — ${chalk.red('KEY CHANGED')}`);
-          console.log(`    Pinned:  ${chalk.yellow(r.pinnedFingerprint)}`);
-          console.log(`    Current: ${chalk.red(r.currentFingerprint)}`);
-          console.log(chalk.red(`    ${r.message}`));
-
-          const ok = await confirm(chalk.white('    Accept the new key? (y/N) '));
-          if (ok) {
-            const keyResult = await fetchServerKey(r.url);
-            if (keyResult) {
-              acceptServerKey(r.url, keyResult.publicKey);
-              console.log(chalk.green('    ✔ New key accepted and pinned.'));
-            }
-          } else {
-            console.log(chalk.yellow('    Key NOT accepted. Consider removing this server.'));
-          }
-        } else if (r.status === 'no-pinned-key') {
-          console.log(`  ${chalk.yellow('?')} ${chalk.white(r.url)} — ${chalk.yellow('no pinned key')}`);
-          console.log(chalk.gray(`    ${r.message}`));
-        } else if (r.status === 'unreachable') {
-          console.log(`  ${chalk.red('—')} ${chalk.white(r.url)} — ${chalk.red('unreachable')}`);
-        }
-      }
-      console.log('');
-    });
-}
+import chalk from 'chalk';
+import config from '../utils/config.js';
+import { spawn, exec } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import readline from 'readline';
+import { getPrimaryServer, getServers, checkServer, verifyAllServers, fetchServerKey, acceptServerKey, keyFingerprint } from '../core/discoveryClient.js';
+import { refreshServerList, healthCheckServers, getServerRoles, SERVER_ROLES, isWriteTrusted } from '../core/serverList.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function confirm(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer.trim().toLowerCase() === 'y'); }));
+}
+
+async function installWindows() {
+  const pePath = process.execPath;
+  const scriptPath = path.resolve(__dirname, '../../bin/pal.js');
+  const taskName = 'PalexplorerServe';
+  const cmd = `schtasks /create /tn "${taskName}" /tr "\\"${pePath}\\" \\"${scriptPath}\\" serve" /sc onlogon /rl limited /f`;
+
+  return new Promise((resolve) => {
+    exec(cmd, (err, stdout, stderr) => {
+      if (err) {
+        console.log(chalk.yellow('Could not create scheduled task automatically.'));
+        console.log(chalk.gray('To install manually, create a scheduled task:'));
+        console.log(chalk.gray(`  schtasks /create /tn "${taskName}" /tr "pal serve" /sc onlogon /rl limited`));
+        return resolve();
+      }
+      console.log(chalk.green(`Scheduled task "${taskName}" created. pal serve will run on login.`));
+      resolve();
+    });
+  });
+}
+
+async function installLinux() {
+  const serviceSource = path.resolve(__dirname, '../../installer/linux/palexplorer.service');
+  const serviceDir = path.join(process.env.HOME, '.config/systemd/user');
+  const serviceDest = path.join(serviceDir, 'palexplorer.service');
+
+  try {
+    fs.mkdirSync(serviceDir, { recursive: true });
+
+    if (fs.existsSync(serviceSource)) {
+      fs.copyFileSync(serviceSource, serviceDest);
+    } else {
+      const serviceContent = `[Unit]
+Description=Palexplorer P2P File Sharing Daemon
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${process.execPath} ${path.resolve(__dirname, '../../bin/pal.js')} serve
+Restart=on-failure
+RestartSec=10
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=default.target
+`;
+      fs.writeFileSync(serviceDest, serviceContent);
+    }
+
+    console.log(chalk.green(`Service file written to ${serviceDest}`));
+    console.log(chalk.gray('Enable with:'));
+    console.log(chalk.gray('  systemctl --user daemon-reload'));
+    console.log(chalk.gray('  systemctl --user enable --now palexplorer'));
+  } catch (err) {
+    console.log(chalk.red('Failed to install systemd service:'), err.message);
+  }
+}
+
+async function installMacOS() {
+  const plistDir = path.join(process.env.HOME, 'Library/LaunchAgents');
+  const plistPath = path.join(plistDir, 'com.palexplorer.serve.plist');
+  const pePath = process.execPath;
+  const scriptPath = path.resolve(__dirname, '../../bin/pal.js');
+
+  const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.palexplorer.serve</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${pePath}</string>
+        <string>${scriptPath}</string>
+        <string>serve</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/tmp/palexplorer.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/palexplorer.err</string>
+</dict>
+</plist>
+`;
+
+  try {
+    fs.mkdirSync(plistDir, { recursive: true });
+    fs.writeFileSync(plistPath, plistContent);
+    console.log(chalk.green(`LaunchAgent written to ${plistPath}`));
+    console.log(chalk.gray('Load with:'));
+    console.log(chalk.gray(`  launchctl load ${plistPath}`));
+  } catch (err) {
+    console.log(chalk.red('Failed to install LaunchAgent:'), err.message);
+  }
+}
+
+export default function serverCommand(program) {
+  const server = program.command('server').description('provision and manage Palexplorer server nodes')
+    .addHelpText('after', `
+Examples:
+  $ pal server install               Install as system service
+  $ pal server status                Check service status
+  $ pal server config                Show server configuration
+  $ pal server register              Register device with discovery server
+`);
+
+  server
+    .command('install')
+    .description('install pal serve as a background service (cross-platform)')
+    .action(async () => {
+      const platform = process.platform;
+      console.log(chalk.blue(`Installing Palexplorer service for ${platform}...`));
+
+      if (platform === 'win32') {
+        await installWindows();
+      } else if (platform === 'linux') {
+        await installLinux();
+      } else if (platform === 'darwin') {
+        await installMacOS();
+      } else {
+        console.log(chalk.red(`Unsupported platform: ${platform}`));
+      }
+    });
+
+  server
+    .command('config <key> <value>')
+    .description('set server-specific operational parameters')
+    .action((key, value) => {
+      // Validate common keys
+      const validKeys = ['port', 'storage_path', 'max_connections', 'bandwidth_cap'];
+      if (!validKeys.includes(key)) {
+        console.log(chalk.yellow(`Warning: '${key}' is not a standard server parameter. Setting anyway.`));
+      }
+
+      const settings = config.get('settings') || {};
+      settings[key] = value;
+      config.set('settings', settings);
+      console.log(chalk.green(`✔ Server configuration updated: ${key} = ${value}`));
+    });
+
+  server
+    .command('register <handle>')
+    .description('register this server node with a handle in the Discovery Network')
+    .action(async (handle) => {
+      const DISCOVERY_URL = getPrimaryServer();
+      const { getIdentity, setIdentityHandle } = await import('../core/identity.js');
+      const identity = await getIdentity();
+      if (!identity || !identity.privateKey) {
+        console.log(chalk.red('No identity found. Run `pal init <name>` first.'));
+        return;
+      }
+
+      const sodium = (await import('sodium-native')).default;
+      const privateKey = Buffer.from(identity.privateKey, 'hex');
+
+      try {
+        console.log(chalk.blue(`Registering handle @${handle} on discovery server...`));
+        // Step 1: Get challenge
+        const chalRes = await fetch(`${DISCOVERY_URL}/register/challenge`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ handle, publicKey: identity.publicKey })
+        });
+        const chalData = await chalRes.json();
+        if (!chalData.challengeId) {
+          console.log(chalk.red(`Challenge failed: ${chalData.error || 'unknown error'}`));
+          return;
+        }
+
+        // Step 2: Sign challenge and register
+        const message = `register:${handle}:${chalData.nonce}`;
+        const sig = Buffer.alloc(sodium.crypto_sign_BYTES);
+        sodium.crypto_sign_detached(sig, Buffer.from(message), privateKey);
+
+        const regRes = await fetch(`${DISCOVERY_URL}/register`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ handle, publicKey: identity.publicKey, challengeId: chalData.challengeId, signature: sig.toString('hex') })
+        });
+        const result = await regRes.json();
+        if (result.success) {
+          console.log(chalk.green(`✔ Node registered as @${handle}`));
+          setIdentityHandle(handle);
+        } else {
+          console.log(chalk.red(`Registration failed: ${result.error}`));
+        }
+      } catch {
+        console.log(chalk.red(`Could not reach discovery server at ${DISCOVERY_URL}`));
+      }
+    });
+
+  server
+    .command('status')
+    .description('check server health and network connectivity')
+    .action(() => {
+      const identity = config.get('identity');
+      const settings = config.get('settings') || {};
+      const shares = config.get('shares') || [];
+
+      console.log('');
+      console.log(chalk.cyan('Palexplorer Server Status:'));
+      console.log(`- Node Identity: ${identity ? chalk.green(identity.name) : chalk.red('Not Initialized')}`);
+      console.log(`- Public Key: ${identity ? chalk.gray(identity.publicKey) : 'N/A'}`);
+      console.log(`- Active Shares: ${chalk.white(shares.length)}`);
+      console.log(`- Bound Port: ${chalk.white(settings.port || 'Auto (1900)')}`);
+      console.log(`- OS: ${chalk.white(process.platform)}`);
+      console.log('');
+    });
+
+  server
+    .command('list')
+    .description('list all configured discovery servers with health status and roles')
+    .action(async () => {
+      const servers = getServers();
+      console.log('');
+      console.log(chalk.cyan('Discovery Servers:'));
+      const checks = await Promise.all(servers.map(s => checkServer(s)));
+      for (let i = 0; i < checks.length; i++) {
+        const c = checks[i];
+        const primary = i === 0 ? chalk.cyan(' (primary)') : '';
+        const status = c.reachable ? chalk.green('reachable') : chalk.red('down');
+        const meta = getServerRoles(c.url);
+        const rolesStr = chalk.gray(`[${meta.roles.join(', ')}]`);
+        const addedBy = meta.addedBy !== 'bootstrap' ? chalk.gray(` (${meta.addedBy})`) : '';
+        const trust = isWriteTrusted(c.url) ? chalk.green('read+write') : chalk.yellow('read-only');
+        console.log(`  ${i + 1}. ${chalk.white(c.url)} — ${status}${primary} ${rolesStr} ${trust}${addedBy}`);
+      }
+      console.log('');
+    });
+
+  server
+    .command('refresh')
+    .description('fetch and update server list from all known servers')
+    .action(async () => {
+      console.log(chalk.blue('Refreshing server list...'));
+      const servers = await refreshServerList((step) => {
+        console.log(chalk.gray(`  ${step}`));
+      });
+      console.log(chalk.green(`\nFound ${servers.length} server(s). Running health checks...`));
+      const checks = await healthCheckServers(servers);
+      for (const c of checks) {
+        const status = c.reachable
+          ? chalk.green(`reachable (${c.latencyMs}ms)`)
+          : chalk.red('unreachable');
+        console.log(`  ${chalk.white(c.url)} — ${status}`);
+      }
+      console.log('');
+    });
+
+  server
+    .command('roles <url>')
+    .description('query and display a server\'s supported roles')
+    .action(async (url) => {
+      const normalized = url.replace(/\/+$/, '');
+      try {
+        const parsed = new URL(normalized);
+        const host = parsed.hostname;
+        if (host === 'localhost' || host.startsWith('127.') || host.startsWith('10.') ||
+            host.startsWith('192.168.') || host.startsWith('169.254.') || host === '0.0.0.0' ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(host)) {
+          console.log(chalk.yellow('⚠ Warning: querying a private/local network address.'));
+        }
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+          console.log(chalk.red('Server URL must use http:// or https://'));
+          process.exitCode = 1;
+          return;
+        }
+      } catch { /* URL validation is best-effort */ }
+      console.log(chalk.blue(`Querying roles for ${normalized}...`));
+      try {
+        const res = await fetch(`${normalized}/status`, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok) {
+          console.log(chalk.red(`Server returned status ${res.status}`));
+          return;
+        }
+        const data = await res.json();
+        console.log('');
+        console.log(chalk.cyan(`Server: ${normalized}`));
+        console.log(`  Status: ${chalk.green(data.status || 'unknown')}`);
+        console.log(`  Version: ${chalk.white(data.version || 'unknown')}`);
+        if (Array.isArray(data.roles)) {
+          console.log(`  Roles: ${chalk.white(data.roles.join(', '))}`);
+        } else {
+          console.log(`  Roles: ${chalk.yellow('not reported (legacy server, assumed all)')}`);
+        }
+        if (data.network) {
+          console.log(`  Network: ${chalk.white(data.network)}`);
+        }
+        console.log('');
+      } catch (err) {
+        console.log(chalk.red(`Could not reach server: ${err.message}`));
+      }
+    });
+
+  server
+    .command('verify')
+    .description('verify pinned keys for all configured servers')
+    .action(async () => {
+      console.log(chalk.blue('Verifying server keys...\n'));
+      const results = await verifyAllServers();
+
+      for (const r of results) {
+        if (r.status === 'ok') {
+          console.log(`  ${chalk.green('✔')} ${chalk.white(r.url)} — ${chalk.green('key verified')} (${chalk.cyan(r.fingerprint)})`);
+        } else if (r.status === 'key-changed') {
+          console.log(`  ${chalk.red('✘')} ${chalk.white(r.url)} — ${chalk.red('KEY CHANGED')}`);
+          console.log(`    Pinned:  ${chalk.yellow(r.pinnedFingerprint)}`);
+          console.log(`    Current: ${chalk.red(r.currentFingerprint)}`);
+          console.log(chalk.red(`    ${r.message}`));
+
+          const ok = await confirm(chalk.white('    Accept the new key? (y/N) '));
+          if (ok) {
+            const keyResult = await fetchServerKey(r.url);
+            if (keyResult) {
+              acceptServerKey(r.url, keyResult.publicKey);
+              console.log(chalk.green('    ✔ New key accepted and pinned.'));
+            }
+          } else {
+            console.log(chalk.yellow('    Key NOT accepted. Consider removing this server.'));
+          }
+        } else if (r.status === 'no-pinned-key') {
+          console.log(`  ${chalk.yellow('?')} ${chalk.white(r.url)} — ${chalk.yellow('no pinned key')}`);
+          console.log(chalk.gray(`    ${r.message}`));
+        } else if (r.status === 'unreachable') {
+          console.log(`  ${chalk.red('—')} ${chalk.white(r.url)} — ${chalk.red('unreachable')}`);
+        }
+      }
+      console.log('');
+    });
+}