pal-explorer-cli 0.4.0

package/lib/utils/help.js

@@ -0,0 +1,357 @@
+export const HelpRegistry = {
+  general: {
+    title: "Palexplorer",
+    description: "Decentralized P2P file sharing from the command line. Share files, folders, and drives directly with your pals — no cloud required."
+  },
+  commands: {
+    init: {
+      summary: "Create a new identity",
+      details: "Generates an Ed25519 keypair and a 24-word recovery phrase. Required before any other command.",
+      subcommands: {},
+      examples: [
+        "pe init alice",
+        "pe init bob --force"
+      ]
+    },
+    whoami: {
+      summary: "Display your current identity",
+      details: "Shows your name, handle, public key, device ID, and creation date.",
+      subcommands: {},
+      examples: [
+        "pe whoami"
+      ]
+    },
+    register: {
+      summary: "Register a handle on the discovery network",
+      details: "Claims a unique @handle via direct signature or email OTP verification.",
+      subcommands: {},
+      examples: [
+        "pe register alice",
+        "pe register alice --email a@b.com"
+      ]
+    },
+    verify: {
+      summary: "Complete OTP email verification",
+      details: "Finishes the email-based handle registration started by `pe register --email`.",
+      subcommands: {},
+      examples: [
+        "pe verify 123456"
+      ]
+    },
+    recover: {
+      summary: "Recover identity from mnemonic phrase",
+      details: "Restores your Ed25519 keypair from the 24-word BIP-39 phrase shown during `pe init`.",
+      subcommands: {},
+      examples: [
+        "pe recover word1 word2 ... word24",
+        "pe recover word1 word2 ... word24 -n alice"
+      ]
+    },
+    share: {
+      summary: "Share a file, folder, or drive via P2P",
+      details: "Adds a resource to your share list. Use `pe serve` to start seeding. Supports public (global) and private (encrypted) shares.",
+      subcommands: {},
+      options: {
+        "-v, --visibility <type>": "Share visibility: global or private (default: global)",
+        "-w, --with <pals...>": "Specific pals to share with",
+        "--with-group <group>": "Share with all members of a group"
+      },
+      examples: [
+        "pe share ./photos",
+        "pe share ./docs -v private -w alice",
+        "pe share ./project --with-group team",
+        "pe share ./file.zip"
+      ]
+    },
+    list: {
+      summary: "List shared resources",
+      details: "Shows all active shares with their visibility, ID, path, and type.",
+      subcommands: {},
+      options: {
+        "--by-drive": "Group shares by drive letter"
+      },
+      examples: [
+        "pe list",
+        "pe list --by-drive"
+      ]
+    },
+    revoke: {
+      summary: "Revoke access to a shared resource",
+      details: "Removes a share entirely, or removes a specific recipient and rotates encryption keys.",
+      subcommands: {},
+      options: {
+        "--pal <palId>": "Remove a specific pal (triggers key rotation)"
+      },
+      examples: [
+        "pe revoke abc123",
+        "pe revoke ./photos",
+        "pe revoke abc123 --pal alice"
+      ]
+    },
+    serve: {
+      summary: "Start the sharing daemon",
+      details: "Seeds all active shares via WebTorrent. Supports foreground, daemon, and web dashboard modes. Auto-resumes incomplete downloads.",
+      subcommands: {},
+      options: {
+        "--daemon": "Run as background daemon",
+        "--stop": "Stop a running daemon",
+        "--web": "Start web dashboard alongside seeder",
+        "--web-port <port>": "Web dashboard port (default: 8585)"
+      },
+      examples: [
+        "pe serve",
+        "pe serve --daemon",
+        "pe serve --stop",
+        "pe serve --web",
+        "pe serve --web --web-port 9090"
+      ]
+    },
+    download: {
+      summary: "Download a file from a magnet link",
+      details: "Downloads via WebTorrent. For private shares, provide the encrypted share key for automatic decryption.",
+      subcommands: {},
+      options: {
+        "--key <encryptedShareKey>": "Encrypted share key for private share decryption"
+      },
+      examples: [
+        'pe download "magnet:?xt=urn:btih:..."',
+        'pe download "magnet:?xt=..." --key abc123'
+      ]
+    },
+    pal: {
+      summary: "Manage your list of pals (friends)",
+      details: "Add pals by @handle, invite link, or raw public key. Remove pals with automatic key rotation for affected shares.",
+      subcommands: {
+        add: "Add a pal by @handle, invite link (pal://...), or public key",
+        list: "List all your pals",
+        remove: "Remove a pal (rotates affected share keys)"
+      },
+      examples: [
+        "pe pal add @alice",
+        "pe pal add pal://... bob",
+        "pe pal add abc123def456 carol",
+        "pe pal list",
+        "pe pal remove @alice"
+      ]
+    },
+    invite: {
+      summary: "Generate a magic invite link",
+      details: "Creates a pal:// link containing your public key, handle, and name. Share it with anyone to let them add you.",
+      subcommands: {},
+      options: {
+        "--qr": "Render the invite as a QR code in the terminal"
+      },
+      examples: [
+        "pe invite",
+        "pe invite --qr"
+      ]
+    },
+    nearby: {
+      summary: "Discover nearby pals on the LAN",
+      details: "Uses mDNS (Bonjour) to find other Palexplorer users on the local network.",
+      subcommands: {},
+      options: {
+        "--add": "Auto-add discovered pals",
+        "--time <seconds>": "Scan duration (default: 10)"
+      },
+      examples: [
+        "pe nearby",
+        "pe nearby --add",
+        "pe nearby --time 30"
+      ]
+    },
+    group: {
+      summary: "Manage sharing groups",
+      details: "Create named groups of pals for easy bulk sharing with `pe share --with-group`.",
+      subcommands: {
+        create: "Create a new group",
+        add: "Add a pal to a group",
+        remove: "Remove a pal from a group",
+        list: "List all groups and members",
+        delete: "Delete a group"
+      },
+      examples: [
+        "pe group create team",
+        "pe group add team @alice",
+        "pe group remove team @alice",
+        "pe group list",
+        "pe group delete team"
+      ]
+    },
+    sync: {
+      summary: "Sync a directory with a pal",
+      details: "Builds a file manifest and sends it to a pal via the discovery server. Supports one-time and continuous (watch) modes.",
+      subcommands: {},
+      options: {
+        "--watch": "Watch for changes and continuously sync",
+        "--list": "List all sync pairs",
+        "--remove <id>": "Remove a sync pair"
+      },
+      examples: [
+        "pe sync ./project @alice",
+        "pe sync --watch ./docs @bob",
+        "pe sync --list",
+        "pe sync --remove <id>"
+      ]
+    },
+    transfers: {
+      summary: "View and manage file transfers",
+      details: "Shows active and completed transfers. Supports pause, resume, and cancel operations.",
+      subcommands: {
+        cancel: "Remove a transfer from tracking",
+        pause: "Pause a transfer",
+        resume: "Resume a paused transfer"
+      },
+      options: {
+        "--history": "Show completed transfers"
+      },
+      examples: [
+        "pe transfers",
+        "pe transfers --history",
+        "pe transfers cancel <magnet>",
+        "pe transfers pause <magnet>",
+        "pe transfers resume <magnet>"
+      ]
+    },
+    config: {
+      summary: "View and manage configuration",
+      details: "Get, set, list, and reset configuration values like port, storage path, bandwidth cap, and discovery URL.",
+      subcommands: {
+        list: "Show all current settings and known keys",
+        get: "Get a single config value",
+        set: "Set a config value",
+        reset: "Clear all custom settings"
+      },
+      examples: [
+        "pe config list",
+        "pe config get theme",
+        "pe config set theme dark",
+        "pe config reset"
+      ]
+    },
+    device: {
+      summary: "View and manage this device",
+      details: "Rename your device, register it with the discovery server, or list all devices under a handle.",
+      subcommands: {
+        rename: "Set a unique name for this device",
+        register: "Register device with the discovery server",
+        list: "List all devices registered under a handle"
+      },
+      examples: [
+        "pe device",
+        "pe device list @alice",
+        'pe device rename "My Laptop"',
+        "pe device register alice"
+      ]
+    },
+    server: {
+      summary: "Provision and manage server nodes",
+      details: "Install pe serve as a system service, configure server parameters, register with discovery, and check status. Supports Windows (schtasks), Linux (systemd), and macOS (launchd).",
+      subcommands: {
+        install: "Install as a background service (cross-platform)",
+        config: "Set server-specific operational parameters",
+        register: "Register this server node with the discovery network",
+        status: "Check server health and network connectivity"
+      },
+      examples: [
+        "pe server install",
+        "pe server status",
+        "pe server config port 8080",
+        "pe server register mynode"
+      ]
+    },
+    explorer: {
+      summary: "Manage file manager integration",
+      details: "Adds or removes a 'Share with Pal' context menu entry in Windows Explorer, macOS Finder, or Linux Nautilus.",
+      subcommands: {
+        install: "Install context menu for your platform",
+        uninstall: "Remove context menu entry"
+      },
+      examples: [
+        "pe explorer install",
+        "pe explorer uninstall"
+      ]
+    },
+    status: {
+      summary: "Show system health dashboard",
+      details: "Displays identity, daemon status, active shares, transfers, and discovery server connectivity at a glance.",
+      subcommands: {},
+      examples: [
+        "pe status"
+      ]
+    },
+    log: {
+      summary: "View application logs",
+      details: "Shows recent log entries from ~/.pal/logs/pal.log. Supports filtering by level and real-time tailing.",
+      subcommands: {},
+      options: {
+        "--tail": "Follow new log entries in real-time",
+        "--level <level>": "Filter by level (debug/info/warn/error)",
+        "-n, --lines <count>": "Number of recent lines to show (default: 20)"
+      },
+      examples: [
+        "pe log",
+        "pe log --tail",
+        "pe log --level error",
+        "pe log -n 50"
+      ]
+    },
+    completion: {
+      summary: "Generate shell completion script",
+      details: "Outputs a completion script for bash or zsh. Source it in your shell profile for tab completion.",
+      subcommands: {},
+      options: {
+        "--shell <shell>": "Shell type: bash or zsh (default: bash)"
+      },
+      examples: [
+        "pe completion",
+        "pe completion --shell zsh",
+        "source <(pe completion)"
+      ]
+    },
+    web: {
+      summary: "Open the web dashboard",
+      details: "Opens the web dashboard in your default browser. Requires `pe serve --web` to be running first.",
+      subcommands: {},
+      options: {
+        "--port <port>": "Web dashboard port (default: 8585)",
+        "--url-only": "Just print the URL without opening browser"
+      },
+      examples: [
+        "pe web",
+        "pe web --url-only",
+        "pe web --port 9090"
+      ]
+    },
+    vfs: {
+      summary: "Manage the virtual filesystem drive",
+      details: "Mounts your shared files as a virtual drive letter via WebDAV. Requires WinFSP on Windows or FUSE on Linux/macOS.",
+      subcommands: {
+        mount: "Mount virtual drive (default P:)",
+        unmount: "Unmount virtual drive",
+        status: "Show mount status and listed shares"
+      },
+      examples: [
+        "pe vfs mount",
+        "pe vfs mount S",
+        "pe vfs unmount",
+        "pe vfs status"
+      ]
+    }
+  },
+  gui: {
+    transfers: "The Transfer Manager shows all active uploads (seeding) and downloads. You can pause or cancel transfers here.",
+    inbox: "View and accept share invitations from your pals. Clicking 'Download' will add the resource to your Transfers.",
+    pals: "Manage your social circle. Search for friends by their verified email handles."
+  }
+};
+
+export const getHelp = (topic) => {
+  const parts = topic.split('.');
+  let current = HelpRegistry;
+  for (const part of parts) {
+    if (current[part]) current = current[part];
+    else return null;
+  }
+  return current;
+};

package/lib/utils/logger.js

@@ -0,0 +1,103 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const LOG_DIR = path.join(os.homedir(), '.pal', 'logs');
+const LOG_FILE = path.join(LOG_DIR, 'pal.log');
+const MAX_SIZE = 5 * 1024 * 1024; // 5MB
+
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+let _level = 'info';
+
+const _originalConsole = {
+  log: console.log.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+};
+
+function ensureLogDir() {
+  if (!fs.existsSync(LOG_DIR)) {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+  }
+}
+
+function rotate() {
+  try {
+    if (!fs.existsSync(LOG_FILE)) return;
+    const stat = fs.statSync(LOG_FILE);
+    if (stat.size < MAX_SIZE) return;
+    const rotated = LOG_FILE + '.1';
+    if (fs.existsSync(rotated)) fs.unlinkSync(rotated);
+    fs.renameSync(LOG_FILE, rotated);
+  } catch {
+    // best effort
+  }
+}
+
+function writeLog(level, message, meta) {
+  ensureLogDir();
+  rotate();
+  const entry = {
+    ts: new Date().toISOString(),
+    level,
+    msg: message,
+    ...meta && { meta }
+  };
+  fs.appendFileSync(LOG_FILE, JSON.stringify(entry) + '\n');
+}
+
+function shouldLog(level) {
+  return LEVELS[level] >= LEVELS[_level];
+}
+
+const logger = {
+  LEVELS: Object.keys(LEVELS),
+
+  get level() { return _level; },
+  get logDir() { return LOG_DIR; },
+  get logFile() { return LOG_FILE; },
+
+  setLevel(level) {
+    if (LEVELS[level] !== undefined) _level = level;
+  },
+
+  shouldLog(level) {
+    return shouldLog(level);
+  },
+
+  debug(msg, meta) {
+    writeLog('debug', msg, meta);
+    if (shouldLog('debug')) _originalConsole.debug(`[debug] ${msg}`);
+  },
+
+  info(msg, meta) {
+    writeLog('info', msg, meta);
+    if (shouldLog('info')) _originalConsole.log(msg);
+  },
+
+  warn(msg, meta) {
+    writeLog('warn', msg, meta);
+    if (shouldLog('warn')) _originalConsole.warn(`[warn] ${msg}`);
+  },
+
+  error(msg, meta) {
+    writeLog('error', msg, meta);
+    if (shouldLog('error')) _originalConsole.error(`[error] ${msg}`);
+  },
+
+  applyGlobalOverride() {
+    console.warn = (...args) => {
+      if (shouldLog('warn')) _originalConsole.warn(...args);
+    };
+    console.error = (...args) => {
+      if (shouldLog('error')) _originalConsole.error(...args);
+    };
+    console.debug = (...args) => {
+      if (shouldLog('debug')) _originalConsole.debug(...args);
+    };
+  },
+};
+
+export default logger;

package/lib/utils/torrent.js

@@ -0,0 +1,203 @@
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import { pipeline } from 'stream/promises';
+import { Readable } from 'stream';
+
+export const TORRENT_TIMEOUT_SHORT = 30_000;
+export const TORRENT_TIMEOUT_LONG = 60_000;
+export const TORRENT_TIMEOUT_METADATA = 60_000;
+
+// Reliable public trackers to speed up discovery
+export const DEFAULT_TRACKERS = [
+  'udp://tracker.opentrackr.org:1337/announce',
+  'udp://9.rarbg.com:2810/announce',
+  'udp://tracker.openbittorrent.com:6969/announce',
+  'udp://exodus.desync.com:6969/announce',
+  'udp://www.torrent.eu.org:451/announce',
+  'wss://tracker.btorrent.xyz',
+  'wss://tracker.openwebtorrent.com',
+];
+
+export function injectLanPeers(torrent, lanPeers) {
+  if (!torrent || !lanPeers?.length) return 0;
+  let injected = 0;
+  for (const peer of lanPeers) {
+    if (!peer.ip || peer.ip === 'unknown') continue;
+    if (peer.torrentPort) {
+      try {
+        torrent.addPeer(`${peer.ip}:${peer.torrentPort}`);
+        injected++;
+      } catch {
+        // peer injection can fail if address is invalid
+      }
+    }
+  }
+  return injected;
+}
+
+export async function tryLanHttpDownload(lanPeers, shareName, outputDir, opts = {}) {
+  const { onProgress, selectedFiles, timeout = 30_000 } = opts;
+  if (!lanPeers?.length || !shareName) return null;
+
+  for (const peer of lanPeers) {
+    if (!peer.ip || peer.ip === 'unknown' || !peer.webPort) continue;
+    const baseUrl = `http://${peer.ip}:${peer.webPort}`;
+
+    try {
+      // Check if peer has this share via /p2p/browse
+      const browseRes = await fetch(
+        `${baseUrl}/p2p/browse?share=${encodeURIComponent(shareName)}`,
+        { signal: AbortSignal.timeout(5000) }
+      );
+      if (!browseRes.ok) continue;
+
+      const entries = await browseRes.json();
+      if (!entries?.length) continue;
+
+      // Collect all files recursively
+      const files = await collectLanFiles(baseUrl, shareName, entries, timeout);
+      if (!files.length) continue;
+
+      // Filter files if selective download requested
+      const toDownload = selectedFiles
+        ? files.filter(f => selectedFiles.some(sf => f.name === sf || f.path.includes(sf)))
+        : files;
+
+      if (!toDownload.length) continue;
+
+      fs.mkdirSync(outputDir, { recursive: true });
+      const downloaded = [];
+      let totalBytes = 0;
+      const totalSize = toDownload.reduce((sum, f) => sum + (f.size || 0), 0);
+
+      for (const file of toDownload) {
+        const filePath = path.join(outputDir, file.path);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+        const fileRes = await fetch(
+          `${baseUrl}/p2p/file?share=${encodeURIComponent(shareName)}&path=${encodeURIComponent(file.path)}`,
+          { signal: AbortSignal.timeout(timeout) }
+        );
+        if (!fileRes.ok) continue;
+
+        await pipeline(Readable.fromWeb(fileRes.body), fs.createWriteStream(filePath));
+        totalBytes += file.size || 0;
+        downloaded.push(file);
+
+        if (onProgress && totalSize > 0) {
+          onProgress(totalBytes / totalSize, file.name);
+        }
+      }
+
+      if (downloaded.length > 0) {
+        return { files: downloaded, peerIp: peer.ip, totalBytes };
+      }
+    } catch {
+      // This peer didn't work, try next
+      continue;
+    }
+  }
+
+  return null;
+}
+
+async function collectLanFiles(baseUrl, shareName, entries, timeout) {
+  const files = [];
+
+  async function walk(items) {
+    for (const entry of items) {
+      if (entry.isDir) {
+        try {
+          const res = await fetch(
+            `${baseUrl}/p2p/browse?share=${encodeURIComponent(shareName)}&path=${encodeURIComponent(entry.path)}`,
+            { signal: AbortSignal.timeout(5000) }
+          );
+          if (res.ok) {
+            const subEntries = await res.json();
+            await walk(subEntries);
+          }
+        } catch {
+          // skip unreachable subdirs
+        }
+      } else {
+        files.push(entry);
+      }
+    }
+  }
+
+  await walk(entries);
+  return files;
+}
+
+export async function getTorrentMetadata(magnet, opts = {}) {
+  const { path: downloadPath = os.tmpdir(), timeout = TORRENT_TIMEOUT_METADATA, lanPeers } = opts;
+  const WebTorrent = (await import('webtorrent')).default;
+  const client = new WebTorrent();
+
+  try {
+    // Proactively fetch seeders from discovery server if possible
+    const infohashMatch = magnet.match(/xt=urn:btih:([a-fA-F0-9]{40})/);
+    if (infohashMatch) {
+      const infohash = infohashMatch[1];
+      try {
+        const { fetchSeeders } = await import('../core/discoveryClient.js');
+        const seeders = await fetchSeeders(infohash);
+        if (seeders.length > 0) {
+          seeders.forEach(s => {
+            if (s.peerId) {
+              // Note: We don't have direct IP here, but we can announce to the tracker
+              // that we are looking for this peerId.
+              // Actually, seeder announce usually includes connection info if available.
+            }
+          });
+        }
+      } catch (e) {
+        // ignore fetch errors
+      }
+    }
+
+    const torrent = await new Promise((resolve, reject) => {
+      // Add trackers to magnet if they are missing
+      let magnetWithTrackers = magnet;
+      if (!magnet.includes('&tr=')) {
+        DEFAULT_TRACKERS.forEach(tr => {
+          magnetWithTrackers += `&tr=${encodeURIComponent(tr)}`;
+        });
+      }
+
+      const t = client.add(magnetWithTrackers, { path: downloadPath });
+
+      // Inject LAN peers for faster discovery
+      if (lanPeers?.length) {
+        injectLanPeers(t, lanPeers);
+      }
+
+      const timer = setTimeout(() => {
+        const err = new Error(`Timed out waiting for torrent metadata (${Math.round(timeout/1000)}s)`);
+        err.code = 'ETIMEDOUT';
+        reject(err);
+      }, timeout);
+
+      t.on('metadata', () => {
+        // Metadata is ready (file list is known)
+        clearTimeout(timer);
+        resolve(t);
+      });
+
+      t.on('error', (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+
+    return { torrent, client };
+  } catch (err) {
+    await destroyClient(client);
+    throw err;
+  }
+}
+
+export async function destroyClient(client) {
+  return new Promise(resolve => client.destroy(resolve));
+}