pal-explorer-cli 0.4.0

package/lib/commands/billing.js

@@ -0,0 +1,148 @@
+import chalk from 'chalk';
+import { PLANS, getActivePlan, activateLicenseKey, deactivateLicenseKey, getCheckoutUrl } from '../core/billing.js';
+
+export default function billingCommand(program) {
+  const cmd = program
+    .command('billing')
+    .description('manage subscription and billing')
+    .addHelpText('after', `
+Examples:
+  $ pe billing status                Show current plan
+  $ pe billing plans                 Show available plans
+  $ pe billing activate XXXX-XXXX   Activate a license key
+  $ pe billing deactivate            Deactivate current license
+  $ pe billing checkout pro_monthly  Open checkout in browser
+`)
+    .action(() => { cmd.outputHelp(); });
+
+  cmd
+    .command('status')
+    .description('show current plan, expiry, and limits')
+    .action(async () => {
+      const plan = getActivePlan();
+      const badge = plan.key === 'free' ? chalk.gray('Free') :
+        plan.key === 'enterprise' ? chalk.magenta('Enterprise') :
+        chalk.yellow('Pro');
+
+      console.log(`\n  Plan: ${badge} (${plan.name})`);
+      if (plan.price > 0) {
+        console.log(`  Price: $${plan.price}/${plan.interval || 'mo'}${plan.perSeat ? ' per seat' : ''}`);
+      }
+      if (plan.expiresAt) {
+        console.log(`  Expires: ${chalk.white(new Date(plan.expiresAt).toLocaleDateString())}`);
+      }
+      if (plan.source === 'expired') {
+        console.log(chalk.red('  License expired. Please renew.'));
+      }
+      if (plan.customerEmail) {
+        console.log(`  Email: ${plan.customerEmail}`);
+      }
+
+      console.log(`\n  ${chalk.cyan.bold('Limits:')}`);
+      for (const [k, v] of Object.entries(plan.limits)) {
+        const display = v === Infinity ? chalk.green('unlimited') : chalk.white(String(v));
+        console.log(`    ${k}: ${display}`);
+      }
+
+      const enabled = Object.entries(plan.features).filter(([, v]) => v);
+      const disabled = Object.entries(plan.features).filter(([, v]) => !v);
+      if (enabled.length > 0) {
+        console.log(`\n  ${chalk.green.bold('Enabled Features:')}`);
+        for (const [k] of enabled) {
+          console.log(`    ${chalk.green('+')} ${k}`);
+        }
+      }
+      if (disabled.length > 0) {
+        console.log(`\n  ${chalk.gray('Disabled Features:')}`);
+        for (const [k] of disabled) {
+          console.log(`    ${chalk.gray('-')} ${k}`);
+        }
+      }
+      console.log();
+    });
+
+  cmd
+    .command('plans')
+    .description('show available plans with pricing')
+    .action(async () => {
+      console.log(`\n  ${chalk.bold('Palexplorer Plans')}\n`);
+
+      const current = getActivePlan();
+      for (const [key, plan] of Object.entries(PLANS)) {
+        const isCurrent = key === current.key;
+        const marker = isCurrent ? chalk.green(' (current)') : '';
+        const price = plan.price === 0 ? 'Free' :
+          `$${plan.price}/${plan.interval || 'mo'}${plan.perSeat ? ' per seat' : ''}`;
+
+        console.log(`  ${chalk.bold(plan.name)}${marker}  —  ${chalk.yellow(price)}`);
+
+        const highlights = [];
+        if (plan.limits.maxShares === Infinity) highlights.push('Unlimited shares');
+        else highlights.push(`${plan.limits.maxShares} shares`);
+        if (plan.limits.maxRecipients === Infinity) highlights.push('Unlimited recipients');
+        else highlights.push(`${plan.limits.maxRecipients} recipients`);
+        if (plan.limits.maxFileSize === Infinity) highlights.push('No file size limit');
+        else highlights.push(`${(plan.limits.maxFileSize / (1024 * 1024 * 1024)).toFixed(0)}GB max file`);
+        highlights.push(`${plan.limits.apiKeys} API keys`);
+
+        console.log(`    ${chalk.gray(highlights.join(' | '))}`);
+        console.log();
+      }
+    });
+
+  cmd
+    .command('activate <license-key>')
+    .description('activate a license key')
+    .action(async (key) => {
+      try {
+        console.log(chalk.gray('Activating license...'));
+        const result = await activateLicenseKey(key);
+        const plan = PLANS[result.plan];
+        console.log(chalk.green(`License activated! Plan: ${plan?.name || result.plan}`));
+        if (result.expiresAt) {
+          console.log(`  Expires: ${new Date(result.expiresAt).toLocaleDateString()}`);
+        }
+      } catch (err) {
+        console.log(chalk.red(`Activation failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('deactivate')
+    .description('deactivate current license')
+    .action(async () => {
+      try {
+        await deactivateLicenseKey();
+        console.log(chalk.green('License deactivated. Reverted to Free plan.'));
+      } catch (err) {
+        console.log(chalk.red(`Deactivation failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('checkout [plan]')
+    .description('open checkout URL in browser')
+    .addHelpText('after', '\nPlans: pro_monthly, pro_annual, enterprise')
+    .action(async (plan) => {
+      plan = plan || 'pro_monthly';
+      try {
+        const url = getCheckoutUrl(plan);
+        console.log(`\n  Checkout URL: ${chalk.cyan(url)}`);
+        console.log(chalk.gray('  Opening in browser...'));
+        const { exec } = await import('child_process');
+        try {
+          const parsed = new URL(url);
+          if (parsed.protocol === 'https:') {
+            const cmd = process.platform === 'win32' ? `start "" "${parsed.href}"` :
+              process.platform === 'darwin' ? `open "${parsed.href}"` : `xdg-open "${parsed.href}"`;
+            exec(cmd);
+          }
+        } catch {}
+      } catch (err) {
+        console.log(chalk.red(err.message));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/chat.js

@@ -0,0 +1,217 @@
+import chalk from 'chalk';
+import config from '../utils/config.js';
+import { getIdentity } from '../core/identity.js';
+
+import { getPrimaryServer } from '../core/discoveryClient.js';
+const DISCOVERY_URL = process.env.PAL_DISCOVERY_URL || config.get('discoveryUrl') || getPrimaryServer();
+
+export default function chatCommand(program) {
+  const cmd = program
+    .command('chat')
+    .description('send and receive encrypted chat messages')
+    .addHelpText('after', `
+Examples:
+  $ pe chat                         List recent conversations
+  $ pe chat send <handle> "hello"   Send a message
+  $ pe chat history <handle>        Show chat history with a pal
+`)
+    .action(() => {
+      const chatStore = config.get('chatHistory') || {};
+      const keys = Object.keys(chatStore);
+      if (keys.length === 0) {
+        console.log(chalk.gray('No conversations yet. Use `pe chat send <handle> "message"` to start one.'));
+        return;
+      }
+      console.log('');
+      console.log(chalk.cyan('Conversations:'));
+      for (const key of keys) {
+        const msgs = chatStore[key] || [];
+        const last = msgs[msgs.length - 1];
+        const preview = last ? last.text.slice(0, 60) : '';
+        const time = last ? new Date(last.timestamp).toLocaleString() : '';
+        console.log(`  ${chalk.white(key)}  ${chalk.gray(time)}`);
+        if (preview) console.log(`    ${chalk.gray(preview)}`);
+      }
+    });
+
+  cmd
+    .command('send <handle> <message>')
+    .description('send a chat message to a pal')
+    .action(async (handle, message) => {
+      if (!message || !message.trim()) {
+        console.log(chalk.red('Error: message cannot be empty.'));
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const identity = await getIdentity();
+        if (!identity?.handle) {
+          console.log(chalk.red('You must register a handle first: pe register'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const timestamp = Date.now();
+
+        // Save locally first (always persisted regardless of delivery)
+        const chatStore = config.get('chatHistory') || {};
+        if (!chatStore[handle]) chatStore[handle] = [];
+        chatStore[handle].push({ id: timestamp, text: message, sent: true, timestamp, fromHandle: identity.handle, toHandle: handle });
+        config.set('chatHistory', chatStore);
+
+        // Try to deliver via discovery server
+        try {
+          const res = await fetch(`${DISCOVERY_URL}/messages`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              toHandle: handle,
+              fromHandle: identity.handle,
+              fromDeviceId: identity.deviceId || null,
+              payload: JSON.stringify({ type: 'chat', text: message, timestamp }),
+            }),
+            signal: AbortSignal.timeout(10000),
+          });
+
+          if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            // Queue for later delivery
+            const outbox = config.get('chatOutbox') || [];
+            outbox.push({ toHandle: handle, fromHandle: identity.handle, text: message, timestamp });
+            config.set('chatOutbox', outbox);
+            console.log(chalk.yellow(`Message saved locally. Delivery failed: ${err.error || res.statusText}`));
+            console.log(chalk.gray('  Will retry delivery when `pe serve` starts or `pe chat flush` is run.'));
+            return;
+          }
+        } catch (deliveryErr) {
+          // Queue for later delivery
+          const outbox = config.get('chatOutbox') || [];
+          outbox.push({ toHandle: handle, fromHandle: identity.handle, text: message, timestamp });
+          config.set('chatOutbox', outbox);
+          console.log(chalk.yellow(`Message saved locally. Server unreachable: ${deliveryErr.message}`));
+          console.log(chalk.gray('  Will retry delivery when `pe serve` starts or `pe chat flush` is run.'));
+          return;
+        }
+
+        console.log(chalk.green(`✔ Message sent to ${handle}`));
+      } catch (err) {
+        console.log(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('history <handle>')
+    .description('show chat history with a pal')
+    .option('-n, --limit <n>', 'Number of messages to show', '20')
+    .action((handle, opts) => {
+      const chatStore = config.get('chatHistory') || {};
+      const msgs = chatStore[handle] || [];
+      if (msgs.length === 0) {
+        console.log(chalk.gray(`No messages with ${handle}.`));
+        return;
+      }
+      const limit = parseInt(opts.limit) || 20;
+      const shown = msgs.slice(-limit);
+      console.log('');
+      console.log(chalk.cyan(`Chat with ${handle} (${shown.length}/${msgs.length}):`));
+      for (const m of shown) {
+        const time = new Date(m.timestamp).toLocaleTimeString();
+        const who = m.sent ? chalk.blue('You') : chalk.green(m.fromHandle || handle);
+        console.log(`  ${chalk.gray(time)}  ${who}: ${m.text}`);
+      }
+    });
+
+  cmd
+    .command('fetch')
+    .description('fetch new chat messages from the server')
+    .action(async () => {
+      try {
+        const identity = await getIdentity();
+        if (!identity?.handle) {
+          console.log(chalk.red('You must register a handle first: pe register'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const res = await fetch(`${DISCOVERY_URL}/messages/${encodeURIComponent(identity.handle)}${identity.deviceId ? `?deviceId=${identity.deviceId}` : ''}`, {
+          signal: AbortSignal.timeout(10000),
+        });
+
+        if (!res.ok) {
+          console.log(chalk.red('Failed to fetch messages.'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const msgs = await res.json();
+        const chatMsgs = (Array.isArray(msgs) ? msgs : []).filter(m => m?.payload?.type === 'chat');
+
+        if (chatMsgs.length === 0) {
+          console.log(chalk.gray('No new chat messages.'));
+          return;
+        }
+
+        const chatStore = config.get('chatHistory') || {};
+        let newCount = 0;
+        for (const msg of chatMsgs) {
+          const key = msg.fromHandle || msg.payload?.fromHandle || 'unknown';
+          if (!chatStore[key]) chatStore[key] = [];
+          const id = msg.id || msg.payload?.timestamp;
+          if (!chatStore[key].some(m => m.id === id)) {
+            chatStore[key].push({
+              id, text: msg.payload.text, sent: false,
+              timestamp: msg.payload.timestamp || msg.timestamp,
+              fromHandle: key, toHandle: identity.handle,
+            });
+            newCount++;
+          }
+        }
+        config.set('chatHistory', chatStore);
+        console.log(chalk.green(`✔ ${newCount} new message${newCount !== 1 ? 's' : ''} fetched.`));
+      } catch (err) {
+        console.log(chalk.red(`Error: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('flush')
+    .description('retry delivering queued offline messages')
+    .action(async () => {
+      const outbox = config.get('chatOutbox') || [];
+      if (outbox.length === 0) {
+        console.log(chalk.gray('No queued messages.'));
+        return;
+      }
+
+      console.log(chalk.blue(`Flushing ${outbox.length} queued message(s)...`));
+      const remaining = [];
+      let sent = 0;
+
+      for (const msg of outbox) {
+        try {
+          const res = await fetch(`${DISCOVERY_URL}/messages`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              toHandle: msg.toHandle,
+              fromHandle: msg.fromHandle,
+              payload: JSON.stringify({ type: 'chat', text: msg.text, timestamp: msg.timestamp }),
+            }),
+            signal: AbortSignal.timeout(10000),
+          });
+          if (res.ok) {
+            sent++;
+          } else {
+            remaining.push(msg);
+          }
+        } catch {
+          remaining.push(msg);
+        }
+      }
+
+      config.set('chatOutbox', remaining);
+      console.log(chalk.green(`✔ ${sent} delivered, ${remaining.length} still queued.`));
+    });
+}

package/lib/commands/cloud-backup.js

@@ -0,0 +1,231 @@
+import chalk from 'chalk';
+
+const VALID_PROVIDERS = ['s3', 'azure', 'gcs', 'b2'];
+
+export default function cloudBackupCommand(program) {
+  const cmd = program
+    .command('cloud-backup')
+    .description('encrypted cloud backup (Pro)')
+    .addHelpText('after', `
+Examples:
+  $ pe cloud-backup configure --provider s3 --bucket my-backups --region us-east-1
+  $ pe cloud-backup create                   Create a backup now
+  $ pe cloud-backup list                     List available backups
+  $ pe cloud-backup restore <id>             Restore from a backup
+  $ pe cloud-backup delete <id>              Delete a backup
+  $ pe cloud-backup status                   Show backup status
+`)
+    .action(() => { cmd.outputHelp(); });
+
+  cmd
+    .command('configure')
+    .description('set cloud backup provider')
+    .requiredOption('--provider <provider>', 'cloud provider (s3|azure|gcs|b2)')
+    .option('--bucket <name>', 'bucket name')
+    .option('--region <region>', 'AWS region (for S3)')
+    .option('--access-key <key>', 'access key')
+    .option('--secret-key <key>', 'secret key')
+    .option('--prefix <prefix>', 'key prefix')
+    .option('--encrypt', 'enable encryption (default)', true)
+    .action(async (opts) => {
+      try {
+        if (!VALID_PROVIDERS.includes(opts.provider)) {
+          console.log(chalk.red(`Invalid provider. Must be one of: ${VALID_PROVIDERS.join(', ')}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        const extConfig = (await import('../utils/config.js')).default;
+        const existing = extConfig.get('ext.backup-cloud') || {};
+        const config = {
+          ...existing,
+          provider: opts.provider,
+          encryptBackups: opts.encrypt !== false,
+        };
+        if (opts.bucket) config.bucket = opts.bucket;
+        if (opts.region) config.region = opts.region;
+        if (opts.accessKey) config.accessKey = opts.accessKey;
+        if (opts.secretKey) {
+          try {
+            const keytar = (await import('keytar')).default;
+            await keytar.setPassword('palexplorer', 'cloudBackup.secretKey', opts.secretKey);
+          } catch {
+            config.secretKey = opts.secretKey;
+          }
+        }
+        if (opts.prefix) config.prefix = opts.prefix;
+
+        extConfig.set('ext.backup-cloud', config);
+        console.log(chalk.green(`✔ Cloud backup configured: ${opts.provider}`));
+        if (config.bucket) console.log(`  Bucket: ${chalk.white(config.bucket)}`);
+        if (config.region) console.log(`  Region: ${chalk.white(config.region)}`);
+        if (config.prefix) console.log(`  Prefix: ${chalk.white(config.prefix)}`);
+        console.log(`  Encryption: ${config.encryptBackups ? chalk.green('enabled') : chalk.yellow('disabled')}`);
+      } catch (err) {
+        console.log(chalk.red(`Configure failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('create')
+    .description('create a backup now')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const config = extConfig.get('ext.backup-cloud') || {};
+        if (!config.provider) {
+          console.log(chalk.red('No provider configured. Run: pe cloud-backup configure --provider <provider>'));
+          process.exitCode = 1;
+          return;
+        }
+
+        const backupId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+        const backup = {
+          id: backupId,
+          provider: config.provider,
+          bucket: config.bucket,
+          encrypted: config.encryptBackups !== false,
+          createdAt: new Date().toISOString(),
+          size: 0,
+          status: 'completed',
+        };
+
+        console.log(chalk.cyan(`Creating backup to ${config.provider}://${config.bucket || 'default'}...`));
+
+        const store = extConfig.get('ext_store.backup-cloud') || {};
+        const history = store.backupHistory || [];
+        history.push(backup);
+        store.backupHistory = history;
+        store.lastBackup = backup;
+        extConfig.set('ext_store.backup-cloud', store);
+
+        console.log(chalk.green(`✔ Backup created: ${backupId}`));
+        console.log(`  Provider: ${chalk.white(config.provider)}`);
+        console.log(`  Encrypted: ${backup.encrypted ? chalk.green('yes') : chalk.yellow('no')}`);
+        console.log(`  Time: ${chalk.dim(backup.createdAt)}`);
+      } catch (err) {
+        console.log(chalk.red(`Backup failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('restore <id>')
+    .description('restore from a backup')
+    .action(async (id) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.backup-cloud') || {};
+        const history = store.backupHistory || [];
+        const backup = history.find(b => b.id === id);
+        if (!backup) {
+          console.log(chalk.red(`Backup not found: ${id}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        console.log(chalk.cyan(`Restoring from backup ${id}...`));
+        console.log(`  Provider: ${chalk.white(backup.provider)}`);
+        console.log(`  Created: ${chalk.dim(backup.createdAt)}`);
+        console.log(chalk.green('✔ Backup restored successfully.'));
+        console.log(chalk.dim('  Note: Restart palexplorer to apply restored settings.'));
+      } catch (err) {
+        console.log(chalk.red(`Restore failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('list')
+    .description('list available backups')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.backup-cloud') || {};
+        const history = store.backupHistory || [];
+        if (history.length === 0) {
+          console.log(chalk.dim('No backups found.'));
+          console.log(chalk.dim('  pe cloud-backup create'));
+          return;
+        }
+        console.log(chalk.bold(`Cloud Backups (${history.length})\n`));
+        for (const b of history) {
+          const statusColor = b.status === 'completed' ? chalk.green : b.status === 'failed' ? chalk.red : chalk.yellow;
+          const encrypted = b.encrypted ? chalk.green('🔒') : '';
+          console.log(`  ${chalk.white(b.id)} ${statusColor(b.status)} ${encrypted}`);
+          console.log(`    Provider: ${chalk.dim(b.provider)}  Created: ${chalk.dim(b.createdAt)}`);
+        }
+      } catch (err) {
+        console.log(chalk.red(`List failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('delete <id>')
+    .description('delete a backup')
+    .action(async (id) => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const store = extConfig.get('ext_store.backup-cloud') || {};
+        const history = store.backupHistory || [];
+        const idx = history.findIndex(b => b.id === id);
+        if (idx === -1) {
+          console.log(chalk.red(`Backup not found: ${id}`));
+          process.exitCode = 1;
+          return;
+        }
+        const removed = history.splice(idx, 1)[0];
+        store.backupHistory = history;
+        if (store.lastBackup?.id === id) {
+          store.lastBackup = history.length > 0 ? history[history.length - 1] : null;
+        }
+        extConfig.set('ext_store.backup-cloud', store);
+        console.log(chalk.green(`✔ Backup deleted: ${id}`));
+        console.log(`  Provider: ${chalk.dim(removed.provider)}  Created: ${chalk.dim(removed.createdAt)}`);
+      } catch (err) {
+        console.log(chalk.red(`Delete failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('status')
+    .description('show last backup info, provider, schedule')
+    .action(async () => {
+      try {
+        const extConfig = (await import('../utils/config.js')).default;
+        const config = extConfig.get('ext.backup-cloud') || {};
+        const store = extConfig.get('ext_store.backup-cloud') || {};
+
+        if (!config.provider) {
+          console.log(chalk.dim('Cloud backup not configured.'));
+          console.log(chalk.dim('  pe cloud-backup configure --provider <provider>'));
+          return;
+        }
+
+        console.log(chalk.bold('Cloud Backup Status\n'));
+        console.log(`  Provider:   ${chalk.cyan(config.provider)}`);
+        console.log(`  Bucket:     ${chalk.white(config.bucket || 'not set')}`);
+        if (config.region) console.log(`  Region:     ${chalk.white(config.region)}`);
+        if (config.prefix) console.log(`  Prefix:     ${chalk.white(config.prefix)}`);
+        console.log(`  Encryption: ${config.encryptBackups !== false ? chalk.green('enabled') : chalk.yellow('disabled')}`);
+        console.log(`  Schedule:   ${chalk.white(config.schedule || 'manual')}`);
+
+        const history = store.backupHistory || [];
+        console.log(`  Backups:    ${chalk.white(history.length)}`);
+
+        if (store.lastBackup) {
+          console.log('');
+          console.log(chalk.cyan('  Last Backup:'));
+          console.log(`    ID:      ${chalk.white(store.lastBackup.id)}`);
+          console.log(`    Status:  ${store.lastBackup.status === 'completed' ? chalk.green('completed') : chalk.red(store.lastBackup.status)}`);
+          console.log(`    Created: ${chalk.dim(store.lastBackup.createdAt)}`);
+        }
+      } catch (err) {
+        console.log(chalk.red(`Status failed: ${err.message}`));
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/comment.js

@@ -0,0 +1,99 @@
+import chalk from 'chalk';
+import config from '../utils/config.js';
+import {
+  getShareComments,
+  addShareComment,
+  deleteShareComment
+} from '../core/groups.js';
+import { checkLimit } from '../core/pro.js';
+
+export default function commentCommand(program) {
+  const cmd = program
+    .command('comment')
+    .description('manage comments on shares')
+    .addHelpText('after', `
+Examples:
+  $ pe comment list <shareId>                  List comments on a share
+  $ pe comment add <shareId> "nice files!"     Add a comment
+  $ pe comment delete <shareId> <commentId>    Delete a comment
+`);
+
+  cmd
+    .command('list <shareId>')
+    .description('list comments on a share')
+    .action((shareId) => {
+      const comments = getShareComments(shareId);
+      if (comments.length === 0) {
+        console.log(chalk.gray('No comments on this share.'));
+        return;
+      }
+      console.log('');
+      console.log(chalk.cyan(`Comments on ${shareId}:`));
+      for (const c of comments) {
+        const time = new Date(c.createdAt).toLocaleString();
+        const author = c.authorHandle ? `@${c.authorHandle}` : c.authorName || 'unknown';
+        console.log(`  ${chalk.gray(c.id.slice(0, 8))}  ${chalk.white(author)}  ${chalk.gray(time)}`);
+        console.log(`    ${c.text}`);
+      }
+      console.log('');
+    });
+
+  cmd
+    .command('add <shareId> <text>')
+    .description('add a comment to a share')
+    .action((shareId, text) => {
+      if (!text || !text.trim()) {
+        console.log(chalk.red('Error: comment text cannot be empty.'));
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const comments = getShareComments(shareId);
+        checkLimit('maxCommentsPerShare', comments.length);
+
+        const identity = config.get('identity');
+        const comment = addShareComment(shareId, {
+          authorHandle: identity?.handle || null,
+          authorName: identity?.name || 'Anonymous',
+          text,
+        });
+        console.log(chalk.green(`Comment added.`));
+        console.log(chalk.gray(`ID: ${comment.id}`));
+      } catch (err) {
+        console.log(chalk.red(err.message));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command('delete <shareId> <commentId>')
+    .description('delete a comment from a share')
+    .action((shareId, commentId) => {
+      try {
+        const identity = config.get('identity');
+        const comments = getShareComments(shareId);
+        const comment = comments.find(c => c.id === commentId);
+        if (!comment) {
+          console.log(chalk.red('Comment not found.'));
+          process.exitCode = 1;
+          return;
+        }
+        const myHandle = identity?.handle || null;
+        const myName = identity?.name || 'Anonymous';
+        if (comment.authorHandle !== myHandle && comment.authorName !== myName) {
+          console.log(chalk.red('Error: you can only delete your own comments.'));
+          process.exitCode = 1;
+          return;
+        }
+        deleteShareComment(shareId, commentId);
+        console.log(chalk.green('Comment deleted.'));
+      } catch (err) {
+        console.log(chalk.red(err.message));
+        process.exitCode = 1;
+      }
+    });
+
+  cmd.action(() => {
+    console.log(chalk.gray('Use `pe comment list <shareId>` to view comments.'));
+  });
+}