pal-explorer-cli 0.4.0

package/lib/commands/sync.js

@@ -0,0 +1,827 @@
+import chalk from 'chalk';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import config from '../utils/config.js';
+import logger from '../utils/logger.js';
+import { buildManifest as buildDiffManifest, diffManifests as diffFileManifests, diffSummary } from '../core/fileDiff.js';
+import { getFriends } from '../core/users.js';
+import {
+  buildManifest,
+  diffManifests,
+  manifestToMap,
+  detectConflicts,
+  applyDiff,
+  formatSize,
+} from '../core/syncEngine.js';
+import {
+  getSyncPairs,
+  addSyncPair,
+  removeSyncPair,
+  updateSyncPair,
+  findSyncPair,
+  saveSyncManifest,
+  getSyncManifest,
+  getLastSyncedManifestMap,
+  addSyncHistoryEntry,
+  getSyncHistory,
+} from '../core/syncState.js';
+import { getPrimaryServer } from '../core/discoveryClient.js';
+
+function getIdentity() {
+  const identity = config.get('identity');
+  if (!identity?.handle) {
+    throw new Error('Not registered. Run `pe init` and `pe register` first.');
+  }
+  return identity;
+}
+
+function findPal(palName) {
+  const friends = getFriends();
+  const pal = friends.find(f => f.name === palName || f.id === palName || f.handle === palName);
+  if (!pal) {
+    throw new Error(`Pal '${palName}' not found. Add them first with \`pe pal add\`.`);
+  }
+  return pal;
+}
+
+function validateDir(dirPath) {
+  const abs = path.resolve(dirPath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`Path not found: ${abs}`);
+  }
+  if (!fs.statSync(abs).isDirectory()) {
+    throw new Error('Sync only works with directories. Use `pe share` for single files.');
+  }
+  return abs;
+}
+
+async function sendMessage(toHandle, body) {
+  const identity = getIdentity();
+  const serverUrl = getPrimaryServer();
+  const res = await fetch(`${serverUrl}/messages`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      toHandle,
+      fromHandle: identity.handle,
+      payload: body,
+    }),
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`Discovery server error: ${res.status} ${err.error || res.statusText}`);
+  }
+}
+
+async function getMessages() {
+  const identity = getIdentity();
+  const serverUrl = getPrimaryServer();
+  const timestamp = String(Date.now());
+  const message = `${identity.handle}:${timestamp}`;
+  let headers = {};
+  try {
+    const { signMessage } = await import('../crypto/chatEncryption.js');
+    const pk = identity.publicKey;
+    const sk = config.get('identity')?.privateKey || (await import('../core/identity.js')).then(m => m.getIdentity()).then(i => i?.privateKey);
+    const privateKey = typeof sk === 'string' ? sk : await sk;
+    if (privateKey) {
+      const sig = signMessage(message, privateKey);
+      headers = { 'x-public-key': pk, 'x-timestamp': timestamp, 'x-signature': sig };
+    }
+  } catch {}
+  const res = await fetch(`${serverUrl}/messages/${encodeURIComponent(identity.handle)}`, { headers, signal: AbortSignal.timeout(10000) });
+  if (!res.ok) {
+    throw new Error(`Discovery server error: ${res.status} ${res.statusText}`);
+  }
+  return res.json();
+}
+
+// --- pe sync push <path> <pal> ---
+
+async function pushSync(dirPath, palName) {
+  let absolutePath, pal;
+  try {
+    absolutePath = validateDir(dirPath);
+    pal = findPal(palName);
+  } catch (err) {
+    console.log(chalk.red(err.message));
+    process.exitCode = 1;
+    return;
+  }
+
+  const palHandle = pal.handle || pal.name;
+  const palId = pal.id;
+
+  console.log(chalk.blue(`Scanning ${absolutePath}...`));
+  const existingPair = findSyncPair(absolutePath, palId);
+  const cachedManifest = existingPair ? getSyncManifest(existingPair.id) : null;
+  const manifest = await buildManifest(absolutePath, cachedManifest);
+  console.log(chalk.gray(`  ${manifest.length} file(s) indexed`));
+
+  const pair = addSyncPair(absolutePath, palId, `sync:${palHandle}`);
+  const lastManifest = getSyncManifest(pair.id);
+  const manifestMap = manifestToMap(manifest);
+
+  let added = 0, modified = 0, deleted = 0;
+  if (lastManifest) {
+    const lastMap = manifestToMap(lastManifest);
+    const diff = diffManifests(lastMap, manifestMap);
+    added = diff.added.length;
+    modified = diff.modified.length;
+    deleted = diff.deleted.length;
+
+    if (added === 0 && modified === 0 && deleted === 0) {
+      console.log(chalk.green('Already in sync. No changes to push.'));
+      return;
+    }
+
+    console.log(chalk.white(`  Changes: ${chalk.green(`+${added}`)} added, ${chalk.yellow(`~${modified}`)} modified, ${chalk.red(`-${deleted}`)} deleted`));
+  } else {
+    console.log(chalk.gray('  First sync for this pair.'));
+  }
+
+  // Look up or create a share for this directory so we have a magnet link
+  let allShares = config.get('shares') || [];
+  let dirShare = allShares.find(s => s.path === absolutePath && s.magnet);
+  let magnet = dirShare?.magnet || null;
+
+  // If no share exists, auto-create a hidden sync share
+  if (!dirShare) {
+    const existing = allShares.find(s => s.path === absolutePath);
+    if (!existing) {
+      const { addShare } = await import('../core/shares.js');
+      try {
+        const autoShare = addShare(absolutePath, 'folder', 'private', { read: true }, [{ name: pal.name, id: palId, handle: palHandle }], { recursive: true });
+        autoShare.syncHidden = true;
+        allShares = config.get('shares') || [];
+        const idx = allShares.findIndex(s => s.id === autoShare.id);
+        if (idx !== -1) { allShares[idx].syncHidden = true; config.set('shares', allShares); }
+        console.log(chalk.gray(`  Auto-created sync share for ${path.basename(absolutePath)}`));
+      } catch {}
+    }
+  }
+
+  // Seed the directory to get a magnet link if we don't have one
+  if (!magnet) {
+    console.log(chalk.blue('Seeding directory for P2P sync...'));
+    try {
+      const WebTorrent = (await import('webtorrent')).default;
+      const client = new WebTorrent();
+      magnet = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => { client.destroy(); reject(new Error('Seed timeout')); }, 30000);
+        client.seed(absolutePath, { name: path.basename(absolutePath) }, (torrent) => {
+          clearTimeout(timeout);
+          // Persist magnet to share config
+          const shares = config.get('shares') || [];
+          const entry = shares.find(s => s.path === absolutePath);
+          if (entry) { entry.magnet = torrent.magnetURI; config.set('shares', shares); }
+          console.log(chalk.green(`  Seeding: ${torrent.magnetURI.slice(0, 60)}...`));
+          // Keep seeding in background (don't destroy client)
+          resolve(torrent.magnetURI);
+        });
+      });
+    } catch (err) {
+      console.log(chalk.yellow(`  Could not seed: ${err.message}. Sending manifest without magnet.`));
+    }
+  }
+
+  console.log(chalk.blue(`Sending manifest to ${pal.name}...`));
+  try {
+    await sendMessage(palHandle, {
+      type: 'sync-manifest',
+      syncPairId: pair.id,
+      manifest,
+      magnet,
+      timestamp: new Date().toISOString(),
+    });
+
+    saveSyncManifest(pair.id, manifest);
+    updateSyncPair(pair.id, {
+      lastSync: new Date().toISOString(),
+      status: 'synced',
+      lastDirection: 'push',
+    });
+
+    addSyncHistoryEntry(pair.id, {
+      direction: 'push',
+      filesAdded: added || manifest.length,
+      filesModified: modified,
+      filesDeleted: deleted,
+      totalFiles: manifest.length,
+    });
+
+    console.log(chalk.green(`Push complete. Manifest sent to ${pal.name}.`));
+    console.log(chalk.gray(`Sync pair: ${pair.id}`));
+    console.log(chalk.gray('Pal can run `pe sync pull` to fetch changes.'));
+  } catch (err) {
+    updateSyncPair(pair.id, { status: 'error' });
+    logger.error(`Push sync failed: ${err.message}`);
+    console.log(chalk.yellow(`Could not reach discovery server: ${err.message}`));
+    console.log(chalk.gray('Manifest built locally. Will sync when server is available.'));
+    process.exitCode = 1;
+  }
+}
+
+// --- pe sync pull <path> <pal> ---
+
+async function pullSync(dirPath, palName) {
+  let absolutePath, pal;
+  try {
+    absolutePath = validateDir(dirPath);
+    pal = findPal(palName);
+  } catch (err) {
+    console.log(chalk.red(err.message));
+    process.exitCode = 1;
+    return;
+  }
+
+  const palHandle = pal.handle || pal.name;
+  const palId = pal.id;
+
+  console.log(chalk.blue(`Checking messages from ${pal.name}...`));
+
+  let messages;
+  try {
+    messages = await getMessages();
+  } catch (err) {
+    logger.error(`Pull sync failed: ${err.message}`);
+    console.log(chalk.red(`Could not reach discovery server: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const syncMessages = (Array.isArray(messages) ? messages : [])
+    .map(m => {
+      try {
+        let data = m.payload || m.body;
+        // Handle double-encoded JSON (string of JSON string)
+        if (typeof data === 'string') {
+          data = JSON.parse(data);
+          if (typeof data === 'string') data = JSON.parse(data);
+        }
+        return { ...m, parsed: data };
+      } catch { return null; }
+    })
+    .filter(m => m && m.parsed?.type === 'sync-manifest' && (m.fromHandle || m.from) === palHandle)
+    .sort((a, b) => new Date(b.parsed.timestamp) - new Date(a.parsed.timestamp));
+
+  if (syncMessages.length === 0) {
+    console.log(chalk.yellow(`No sync manifests from ${pal.name}. Ask them to run \`pe sync push\`.`));
+    return;
+  }
+
+  const latest = syncMessages[0].parsed;
+  const remoteManifest = latest.manifest;
+  console.log(chalk.gray(`  Found manifest from ${latest.timestamp} (${remoteManifest.length} files)`));
+
+  console.log(chalk.blue(`Scanning local ${absolutePath}...`));
+  const existingPullPair = findSyncPair(absolutePath, palId);
+  const cachedPullManifest = existingPullPair ? getSyncManifest(existingPullPair.id) : null;
+  const localManifest = await buildManifest(absolutePath, cachedPullManifest);
+  console.log(chalk.gray(`  ${localManifest.length} local file(s)`));
+
+  const localMap = manifestToMap(localManifest);
+  const remoteMap = manifestToMap(remoteManifest);
+
+  const pair = addSyncPair(absolutePath, palId, `sync:${palHandle}`);
+  const baseMap = getLastSyncedManifestMap(pair.id);
+
+  const { conflicts } = detectConflicts(localMap, remoteMap, baseMap);
+  const diff = diffManifests(localMap, remoteMap);
+
+  if (conflicts.length > 0) {
+    diff.conflicts = conflicts;
+    diff.modified = diff.modified.filter(
+      m => !conflicts.some(c => c.relativePath === m.relativePath)
+    );
+  }
+
+  const totalChanges = diff.added.length + diff.modified.length + diff.deleted.length + (diff.conflicts?.length || 0);
+  if (totalChanges === 0) {
+    console.log(chalk.green('Already in sync. No changes to pull.'));
+    return;
+  }
+
+  console.log(chalk.white(`  Changes to apply:`));
+  if (diff.added.length) console.log(chalk.green(`    + ${diff.added.length} new file(s)`));
+  if (diff.modified.length) console.log(chalk.yellow(`    ~ ${diff.modified.length} modified file(s)`));
+  if (diff.deleted.length) console.log(chalk.red(`    - ${diff.deleted.length} deleted file(s)`));
+  if (conflicts.length) console.log(chalk.magenta(`    ! ${conflicts.length} conflict(s) (both sides changed)`));
+
+  const magnet = latest.magnet || null;
+
+  if (magnet) {
+    // P2P sync: download the shared directory via WebTorrent, then apply diff
+    console.log(chalk.blue('Downloading via P2P...'));
+
+    try {
+      const WebTorrent = (await import('webtorrent')).default;
+      const tmpDir = path.join(os.tmpdir(), `pe-sync-${pair.id}-${Date.now()}`);
+      fs.mkdirSync(tmpDir, { recursive: true });
+
+      const client = new WebTorrent();
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          client.destroy();
+          reject(new Error('Download timed out after 5 minutes'));
+        }, 5 * 60 * 1000);
+
+        client.add(magnet, { path: tmpDir }, (torrent) => {
+          console.log(chalk.gray(`  Downloading ${torrent.files.length} file(s)...`));
+
+          torrent.on('done', async () => {
+            clearTimeout(timeout);
+            console.log(chalk.green('  Download complete. Applying changes...'));
+
+            // The torrent downloads into tmpDir/<torrent.name>/
+            const sourcePath = path.join(tmpDir, torrent.name);
+            const results = applyDiff(diff, sourcePath, absolutePath);
+
+            if (results.copied.length) {
+              console.log(chalk.green(`  Copied ${results.copied.length} file(s)`));
+            }
+            if (results.deleted.length) {
+              console.log(chalk.red(`  Deleted ${results.deleted.length} file(s)`));
+            }
+            if (results.conflicted.length) {
+              console.log(chalk.magenta(`  ${results.conflicted.length} conflict(s) saved with .sync-conflict suffix`));
+              for (const c of results.conflicted) {
+                console.log(chalk.gray(`    ${c.original} -> ${c.conflictFile}`));
+              }
+            }
+            if (results.errors.length) {
+              console.log(chalk.red(`  ${results.errors.length} error(s):`));
+              for (const e of results.errors) {
+                console.log(chalk.red(`    ${e.file}: ${e.error}`));
+              }
+            }
+
+            const newManifest = await buildManifest(absolutePath, getSyncManifest(pair.id));
+            saveSyncManifest(pair.id, newManifest);
+            updateSyncPair(pair.id, {
+              lastSync: new Date().toISOString(),
+              status: 'synced',
+              lastDirection: 'pull',
+            });
+
+            addSyncHistoryEntry(pair.id, {
+              direction: 'pull',
+              filesAdded: results.copied.length,
+              filesModified: 0,
+              filesDeleted: results.deleted.length,
+              conflicts: results.conflicted.length,
+              totalFiles: newManifest.length,
+            });
+
+            client.destroy();
+            // Clean up temp dir
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+            console.log(chalk.green('Pull complete.'));
+            resolve();
+          });
+
+          torrent.on('error', (err) => {
+            clearTimeout(timeout);
+            client.destroy();
+            reject(err);
+          });
+        });
+      });
+    } catch (err) {
+      logger.error(`P2P sync download failed: ${err.message}`);
+      console.log(chalk.yellow(`P2P download failed: ${err.message}`));
+      console.log(chalk.gray('Saving diff for manual resolution. Use `pe sync status` to review.'));
+
+      saveSyncManifest(pair.id, remoteManifest);
+      updateSyncPair(pair.id, {
+        lastSync: new Date().toISOString(),
+        status: 'pending-download',
+        lastDirection: 'pull',
+        pendingDiff: {
+          added: diff.added.length,
+          modified: diff.modified.length,
+          deleted: diff.deleted.length,
+          conflicts: conflicts.length,
+        },
+      });
+    }
+  } else {
+    // No magnet available — pal needs to share the directory first
+    console.log(chalk.yellow('No magnet link in manifest. Pal must share the directory first.'));
+    console.log(chalk.gray('Ask them to run `pe share <path>` then `pe sync push` again.'));
+    console.log(chalk.gray('Diff summary saved. Use `pe sync status` to review.'));
+
+    saveSyncManifest(pair.id, remoteManifest);
+    updateSyncPair(pair.id, {
+      lastSync: new Date().toISOString(),
+      status: 'pending-download',
+      lastDirection: 'pull',
+      pendingDiff: {
+        added: diff.added.length,
+        modified: diff.modified.length,
+        deleted: diff.deleted.length,
+        conflicts: conflicts.length,
+      },
+    });
+  }
+}
+
+// --- pe sync status <path> ---
+
+async function syncStatus(dirPath) {
+  if (!dirPath) {
+    const pairs = getSyncPairs();
+    if (pairs.length === 0) {
+      console.log(chalk.gray('No sync pairs configured. Use `pe sync push <path> <pal>` to start.'));
+      return;
+    }
+
+    const friends = getFriends();
+    console.log('');
+    console.log(chalk.cyan.bold('Sync Pairs'));
+    console.log('');
+
+    for (const pair of pairs) {
+      const pal = friends.find(f => f.id === pair.palId);
+      const palName = pal?.name || pair.palId;
+      const statusColor =
+        pair.status === 'synced' ? chalk.green :
+        pair.status === 'error' ? chalk.red :
+        pair.status === 'pending-download' ? chalk.yellow :
+        chalk.gray;
+
+      console.log(`  ${chalk.white(pair.localPath)} ${chalk.gray('->')} ${chalk.yellow(palName)}`);
+      console.log(`    Status: ${statusColor(pair.status)}  Direction: ${pair.lastDirection || '-'}  Last: ${pair.lastSync || 'never'}`);
+      console.log(`    ${chalk.gray(`ID: ${pair.id}`)}`);
+    }
+    console.log('');
+    return;
+  }
+
+  let absolutePath;
+  try {
+    absolutePath = validateDir(dirPath);
+  } catch (err) {
+    console.log(chalk.red(err.message));
+    process.exitCode = 1;
+    return;
+  }
+
+  const pairs = getSyncPairs().filter(p => p.localPath === absolutePath);
+  if (pairs.length === 0) {
+    console.log(chalk.yellow(`No sync pairs for ${absolutePath}.`));
+    console.log(chalk.gray('Use `pe sync push <path> <pal>` to create one.'));
+    return;
+  }
+
+  const friends = getFriends();
+  console.log('');
+  console.log(chalk.cyan.bold(`Sync Status: ${absolutePath}`));
+  console.log('');
+
+  const statusCached = pairs.length === 1 ? getSyncManifest(pairs[0].id) : null;
+  const currentManifest = await buildManifest(absolutePath, statusCached);
+  const currentMap = manifestToMap(currentManifest);
+
+  for (const pair of pairs) {
+    const pal = friends.find(f => f.id === pair.palId);
+    const palName = pal?.name || pair.palId;
+    const lastManifest = getSyncManifest(pair.id);
+
+    console.log(`  ${chalk.yellow(palName)} (${pair.status})`);
+
+    if (!lastManifest) {
+      console.log(chalk.gray('    No previous sync. All files will be synced.'));
+      console.log(`    ${chalk.white(`${currentManifest.length} file(s) to push`)}`);
+    } else {
+      const lastMap = manifestToMap(lastManifest);
+      const diff = diffManifests(lastMap, currentMap);
+      const total = diff.added.length + diff.modified.length + diff.deleted.length;
+
+      if (total === 0) {
+        console.log(chalk.green('    In sync. No local changes.'));
+      } else {
+        console.log(`    ${chalk.green(`+${diff.added.length}`)} added  ${chalk.yellow(`~${diff.modified.length}`)} modified  ${chalk.red(`-${diff.deleted.length}`)} deleted`);
+        if (diff.added.length <= 5) {
+          for (const a of diff.added) console.log(chalk.green(`      + ${a.relativePath}`));
+        }
+        if (diff.modified.length <= 5) {
+          for (const m of diff.modified) console.log(chalk.yellow(`      ~ ${m.relativePath}`));
+        }
+        if (diff.deleted.length <= 5) {
+          for (const d of diff.deleted) console.log(chalk.red(`      - ${d.relativePath}`));
+        }
+      }
+    }
+
+    const history = getSyncHistory(pair.id);
+    if (history.length > 0) {
+      console.log(chalk.gray(`    Last ${Math.min(history.length, 3)} syncs:`));
+      for (const h of history.slice(0, 3)) {
+        const dir = h.direction === 'push' ? chalk.blue('PUSH') : chalk.magenta('PULL');
+        const changes = [];
+        if (h.filesAdded) changes.push(chalk.green(`+${h.filesAdded}`));
+        if (h.filesModified) changes.push(chalk.yellow(`~${h.filesModified}`));
+        if (h.filesDeleted) changes.push(chalk.red(`-${h.filesDeleted}`));
+        if (h.conflicts) changes.push(chalk.magenta(`!${h.conflicts}`));
+        console.log(chalk.gray(`      ${h.timestamp}  ${dir}  ${changes.join(' ')}`));
+      }
+    }
+    console.log('');
+  }
+}
+
+// --- pe sync watch <path> <pal> ---
+
+function watchSync(dirPath, palName) {
+  let absolutePath, pal;
+  try {
+    absolutePath = validateDir(dirPath);
+    pal = findPal(palName);
+  } catch (err) {
+    console.log(chalk.red(err.message));
+    process.exitCode = 1;
+    return;
+  }
+
+  const palHandle = pal.handle || pal.name;
+  const palId = pal.id;
+  const pair = addSyncPair(absolutePath, palId, `sync:${palHandle}`);
+
+  console.log(chalk.blue(`Watching ${absolutePath} for changes...`));
+  console.log(chalk.gray(`Syncing to ${pal.name}. Press Ctrl+C to stop.`));
+
+  let debounceTimer = null;
+  const debounceMs = 2000;
+  let syncing = false;
+
+  const triggerSync = async () => {
+    if (syncing) return;
+    syncing = true;
+
+    try {
+      const lastManifest = getSyncManifest(pair.id);
+      const manifest = await buildManifest(absolutePath, lastManifest);
+
+      if (lastManifest) {
+        const lastMap = manifestToMap(lastManifest);
+        const currentMap = manifestToMap(manifest);
+        const diff = diffManifests(lastMap, currentMap);
+        const total = diff.added.length + diff.modified.length + diff.deleted.length;
+        if (total === 0) {
+          syncing = false;
+          return;
+        }
+        console.log(chalk.blue(`Change detected: ${chalk.green(`+${diff.added.length}`)} ${chalk.yellow(`~${diff.modified.length}`)} ${chalk.red(`-${diff.deleted.length}`)}`));
+      } else {
+        console.log(chalk.blue(`Initial sync: ${manifest.length} file(s)`));
+      }
+
+      // Include magnet if available from existing share
+      const watchShares = config.get('shares') || [];
+      const watchShare = watchShares.find(s => s.path === absolutePath && s.magnet);
+
+      await sendMessage(palHandle, {
+        type: 'sync-manifest',
+        syncPairId: pair.id,
+        manifest,
+        magnet: watchShare?.magnet || null,
+        timestamp: new Date().toISOString(),
+      });
+
+      saveSyncManifest(pair.id, manifest);
+      updateSyncPair(pair.id, {
+        lastSync: new Date().toISOString(),
+        status: 'synced',
+        lastDirection: 'push',
+      });
+
+      addSyncHistoryEntry(pair.id, {
+        direction: 'push',
+        totalFiles: manifest.length,
+        auto: true,
+      });
+
+      console.log(chalk.green(`Synced to ${pal.name} at ${new Date().toLocaleTimeString()}`));
+    } catch (err) {
+      logger.error(`Watch sync failed: ${err.message}`);
+      console.log(chalk.yellow(`Sync failed: ${err.message}`));
+    } finally {
+      syncing = false;
+    }
+  };
+
+  try {
+    const watcher = fs.watch(absolutePath, { recursive: true }, (_event, filename) => {
+      if (filename && /node_modules|\.git/.test(filename)) return;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(triggerSync, debounceMs);
+    });
+    process.on('SIGINT', () => { watcher.close(); process.exit(0); });
+  } catch (err) {
+    console.log(chalk.red(`Watch failed: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
+  triggerSync();
+}
+
+// --- pe sync remove <id> ---
+
+function removePair(id) {
+  const pairs = getSyncPairs();
+  const pair = pairs.find(p => p.id === id);
+  if (!pair) {
+    console.log(chalk.red(`Sync pair '${id}' not found.`));
+    process.exitCode = 1;
+    return;
+  }
+  removeSyncPair(id);
+  console.log(chalk.green(`Removed sync pair ${id}.`));
+}
+
+function formatSyncBytes(b) {
+  if (!b) return '0 B';
+  if (b < 1024) return b + ' B';
+  if (b < 1048576) return (b / 1024).toFixed(1) + ' KB';
+  if (b < 1073741824) return (b / 1048576).toFixed(1) + ' MB';
+  return (b / 1073741824).toFixed(2) + ' GB';
+}
+
+// --- Command registration ---
+
+export default function syncCommand(program) {
+  const cmd = program
+    .command('sync')
+    .description('sync directories with pals');
+
+  cmd
+    .command('push <path> <pal>')
+    .description('push local changes to a pal')
+    .action(async (syncPath, pal) => {
+      if (!syncPath || !syncPath.trim()) {
+        console.log(chalk.red('Error: path cannot be empty.'));
+        process.exitCode = 1;
+        return;
+      }
+      await pushSync(syncPath, pal);
+    });
+
+  cmd
+    .command('pull <path> <pal>')
+    .description('pull changes from a pal')
+    .action(async (syncPath, pal) => {
+      if (!syncPath || !syncPath.trim()) {
+        console.log(chalk.red('Error: path cannot be empty.'));
+        process.exitCode = 1;
+        return;
+      }
+      await pullSync(syncPath, pal);
+    });
+
+  cmd
+    .command('status [path]')
+    .description('show sync status and changes since last sync')
+    .action((syncPath) => {
+      syncStatus(syncPath);
+    });
+
+  cmd
+    .command('watch <path> <pal>')
+    .description('watch directory and auto-push on changes')
+    .action((syncPath, pal) => {
+      watchSync(syncPath, pal);
+    });
+
+  cmd
+    .command('list')
+    .description('list all sync pairs')
+    .action(() => {
+      syncStatus();
+    });
+
+  cmd
+    .command('remove <id>')
+    .description('remove a sync pair')
+    .action((id) => {
+      removePair(id);
+    });
+
+  cmd
+    .command('history [pairId]')
+    .description('view sync history')
+    .action((pairId) => {
+      const pairs = getSyncPairs();
+      if (pairs.length === 0) {
+        console.log(chalk.gray('No sync pairs configured.'));
+        return;
+      }
+
+      const friends = getFriends();
+      const targetPairs = pairId ? pairs.filter(p => p.id === pairId) : pairs;
+      if (targetPairs.length === 0) {
+        console.log(chalk.red(`Sync pair '${pairId}' not found.`));
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log('');
+      console.log(chalk.cyan.bold('Sync History'));
+      console.log('');
+
+      for (const pair of targetPairs) {
+        const pal = friends.find(f => f.id === pair.palId);
+        const palName = pal?.name || pair.palId;
+        console.log(`  ${chalk.white(pair.localPath)} ${chalk.gray('->')} ${chalk.yellow(palName)}`);
+        console.log(`  ${chalk.gray(`ID: ${pair.id}`)}`);
+
+        const history = getSyncHistory(pair.id);
+        if (history.length === 0) {
+          console.log(chalk.gray('    No history yet.'));
+        } else {
+          for (const h of history) {
+            const dir = h.direction === 'push' ? chalk.blue('PUSH') : chalk.magenta('PULL');
+            const changes = [];
+            if (h.filesAdded) changes.push(chalk.green(`+${h.filesAdded}`));
+            if (h.filesModified) changes.push(chalk.yellow(`~${h.filesModified}`));
+            if (h.filesDeleted) changes.push(chalk.red(`-${h.filesDeleted}`));
+            if (h.conflicts) changes.push(chalk.magenta(`!${h.conflicts}`));
+            if (h.totalFiles) changes.push(chalk.gray(`(${h.totalFiles} total)`));
+            console.log(`    ${chalk.gray(h.timestamp)}  ${dir}  ${changes.join(' ')}${h.auto ? chalk.gray(' [auto]') : ''}`);
+          }
+        }
+        console.log('');
+      }
+    });
+
+  cmd
+    .command('diff <localPath> <remotePath>')
+    .description('compare local and remote folders, show what needs to transfer')
+    .option('--json', 'Output as JSON')
+    .action(async (localPath, remotePath, opts) => {
+      try {
+        console.log(chalk.blue('Building local manifest...'));
+        const localManifest = buildDiffManifest(localPath);
+        console.log(chalk.blue('Building remote manifest...'));
+        const remoteManifest = buildDiffManifest(remotePath);
+
+        const diff = diffFileManifests(localManifest, remoteManifest);
+        const summary = diffSummary(diff);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ diff, summary }, null, 2));
+          return;
+        }
+
+        console.log();
+        if (diff.added.length > 0) {
+          console.log(chalk.green(`  + ${diff.added.length} new files`));
+          diff.added.forEach(f => console.log(chalk.green(`    + ${f.path} (${formatSyncBytes(f.size)})`)));
+        }
+        if (diff.modified.length > 0) {
+          console.log(chalk.yellow(`  ~ ${diff.modified.length} modified files`));
+          diff.modified.forEach(f => console.log(chalk.yellow(`    ~ ${f.path} (${formatSyncBytes(f.size)})`)));
+        }
+        if (diff.deleted.length > 0) {
+          console.log(chalk.red(`  - ${diff.deleted.length} deleted files`));
+          diff.deleted.forEach(f => console.log(chalk.red(`    - ${f.path}`)));
+        }
+        if (diff.unchanged.length > 0) {
+          console.log(chalk.gray(`  = ${diff.unchanged.length} unchanged files`));
+        }
+
+        console.log();
+        console.log(chalk.white(`  Transfer needed: ${formatSyncBytes(summary.transferBytes)} (${summary.addedCount + summary.modifiedCount} files)`));
+        console.log(chalk.gray(`  Skipping: ${summary.skippedFiles} files already up to date`));
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err.message}`));
+        process.exit(1);
+      }
+    });
+
+  cmd.addHelpText('after', `
+${chalk.cyan('Examples:')}
+  $ pe sync push ./project alice      Push local changes to alice
+  $ pe sync pull ./project alice      Pull alice's changes locally
+  $ pe sync status ./project          Show what changed since last sync
+  $ pe sync status                    Show all sync pairs
+  $ pe sync watch ./project alice     Watch and auto-push on changes
+  $ pe sync list                      List all sync pairs
+  $ pe sync remove <id>               Remove a sync pair
+  $ pe sync diff ./local ./remote     Compare two folders, show transfer needed
+  $ pe sync history                   View sync history for all pairs
+  $ pe sync history <id>              View sync history for a specific pair
+
+${chalk.cyan('How it works:')}
+  1. ${chalk.white('push')} scans your directory, computes file hashes, and sends
+     the manifest to your pal via the discovery server.
+  2. ${chalk.white('pull')} checks for manifests from your pal, compares with
+     your local files, and applies changes.
+  3. If both sides modified the same file, a ${chalk.magenta('.sync-conflict')} copy
+     is created so you don't lose either version.
+  4. ${chalk.white('watch')} monitors your directory and auto-pushes on changes.
+`);
+}