island-bridge 1.1.0 → 2.0.0

package/README.md

@@ -21,9 +21,28 @@ npx island-bridge push
 - `rsync` installed on both local and remote machines
 - SSH access to remote server (uses system `~/.ssh/config`)
 
+## Quick Start
+
+```bash
+# Create config interactively
+island-bridge init
+
+# Or create config via flags (AI/script friendly)
+island-bridge init --host 192.168.1.100 --user deploy --paths "/var/www/app,/etc/nginx/conf.d"
+
+# Check environment is ready
+island-bridge status
+
+# Pull remote folders to local
+island-bridge pull
+
+# Push local changes back
+island-bridge push
+```
+
 ## Usage
 
-1. Create `island-bridge.json` in your working directory:
+1. Create `island-bridge.json` in your working directory (or run `island-bridge init`):
 
 ```json
 {
@@ -68,6 +87,9 @@ island-bridge push
 | `watch` | Watch local folders and auto-push on changes |
 | `diff` | Preview changes without syncing |
 | `history` | Show sync history |
+| `init` | Create config file interactively or via flags |
+| `status` | Show config, SSH, rsync, and paths status |
+| `backup` | Manage sync backups (list, restore, clean) |
 
 ## Options
 
@@ -80,9 +102,80 @@ island-bridge push
 | `--env <name>` | Use named profile from config |
 | `--bwlimit <KB/s>` | Limit transfer bandwidth |
 | `-s, --select` | Interactively select folders to sync |
+| `--path <name>` | Sync specific folder by name (repeatable) |
+| `--json` | Output in JSON format (for scripts/AI) |
+| `--no-backup` | Skip backup for this sync |
 | `-V, --version` | Show version |
 | `-h, --help` | Show help |
 
+## Backup & Restore
+
+Backups are **enabled by default**. Before each sync, files that will be overwritten are automatically saved to a timestamped backup directory.
+
+```bash
+# List available backups
+island-bridge backup list
+
+# Restore a specific backup
+island-bridge backup restore 2026-04-07T14-30-00
+
+# Clean old backups, keep 5 most recent
+island-bridge backup clean --keep 5
+```
+
+### Backup Config
+
+```json
+{
+  "backup": {
+    "enabled": true,
+    "maxCount": 10,
+    "localDir": ".island-bridge-backups",
+    "remoteDir": "~/.island-bridge-backups"
+  }
+}
+```
+
+Use `--no-backup` to skip backup for a single sync operation.
+
+## JSON Output (AI/Script Friendly)
+
+Add `--json` to any command for structured JSON output — no colors, no progress bars, no interactive prompts:
+
+```bash
+# Check environment before syncing
+island-bridge status --json
+
+# Sync and parse results programmatically
+island-bridge pull --json
+
+# Create config non-interactively
+island-bridge init --json --host example.com --user deploy --paths "/var/www/app"
+```
+
+Example JSON output:
+
+```json
+{
+  "version": "2.0.0",
+  "command": "pull",
+  "success": true,
+  "results": [
+    {
+      "folder": "app",
+      "remotePath": "/var/www/app",
+      "success": true,
+      "changes": [
+        { "type": "add", "file": "index.js" },
+        { "type": "delete", "file": "old.css" }
+      ]
+    }
+  ],
+  "messages": [],
+  "errors": []
+}
+```
+
 ## Advanced Config
 
 ```json
@@ -94,6 +187,10 @@ island-bridge push
   },
   "exclude": ["node_modules", ".DS_Store", "*.log"],
   "bwlimit": 1000,
+  "backup": {
+    "enabled": true,
+    "maxCount": 10
+  },
   "hooks": {
     "beforeSync": "echo 'Starting sync...'",
     "afterSync": "pm2 restart app"
@@ -162,6 +259,12 @@ island-bridge pull --config /path/to/my-config.json
 ## Examples
 
 ```bash
+# Create config interactively
+island-bridge init
+
+# Check everything is working
+island-bridge status
+
 # Preview what would change
 island-bridge pull --dry-run
 
@@ -171,6 +274,9 @@ island-bridge diff
 # Sync with bandwidth limit
 island-bridge pull --bwlimit 500
 
+# Sync only specific folder
+island-bridge pull --path app
+
 # Auto-push on file changes
 island-bridge watch
 
@@ -183,8 +289,15 @@ island-bridge pull --env staging
 # Quiet mode for CI/scripts
 island-bridge push --quiet
 
+# JSON output for AI/scripts
+island-bridge pull --json
+
 # View sync history
 island-bridge history
+
+# List and restore backups
+island-bridge backup list
+island-bridge backup restore 2026-04-07T14-30-00
 ```
 
 ## Features
@@ -207,6 +320,12 @@ island-bridge history
 - **Config search** — finds config in parent directories
 - **Fault tolerant** — skips failed transfers, reports summary at end
 - **Zero dependencies** — pure Node.js, no npm dependencies
+- **Auto backup** — files backed up before overwrite, with restore support
+- **JSON output** — structured output for AI agents and scripts
+- **Init command** — interactive or flag-based config setup
+- **Status check** — diagnose SSH, rsync, and path issues
+- **Path filter** — sync specific folders with `--path`
+- **Error hints** — actionable suggestions on every error
 
 ## License
 

package/bin/cli.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env node
 
 import { parseArgs } from '../lib/args.js';
-import { loadConfig } from '../lib/config.js';
+import { loadConfig, extractFolderName } from '../lib/config.js';
 import { checkRsync, syncAll, diffPreview } from '../lib/sync.js';
-import { printSummary } from '../lib/summary.js';
+import { Reporter } from '../lib/reporter.js';
 import { startWatch } from '../lib/watch.js';
 import { recordSync, showHistory } from '../lib/history.js';
 import { runHook } from '../lib/hooks.js';
 import { selectPaths } from '../lib/interactive.js';
+import { runInit } from '../lib/init.js';
+import { runStatus } from '../lib/status.js';
+import { listBackups, restoreBackup, cleanBackups } from '../lib/backup.js';
+import { getErrorHint } from '../lib/summary.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -27,6 +31,9 @@ Commands:
   watch       Watch local folders and auto-push on changes
   diff        Preview changes without syncing
   history     Show sync history
+  init        Create island-bridge.json config interactively
+  status      Show config, SSH, rsync, and paths status
+  backup      Manage sync backups (list, restore, clean)
 
 Options:
   -n, --dry-run        Preview sync without making changes
@@ -36,17 +43,16 @@ Options:
       --env <name>     Use named profile from config
       --bwlimit <KB/s> Limit transfer bandwidth
   -s, --select         Interactively select folders to sync
+      --path <name>    Sync specific folder by name (repeatable)
+      --json           Output in JSON format (for scripts/AI)
+      --no-backup      Skip backup for this sync
   -V, --version        Show version
   -h, --help           Show this help message
 
-Config (island-bridge.json):
-  {
-    "remote": { "host": "...", "user": "...", "paths": [...] },
-    "exclude": ["node_modules", "*.log"],
-    "bwlimit": 1000,
-    "hooks": { "beforeSync": "...", "afterSync": "..." },
-    "profiles": { "staging": { "remote": { ... } } }
-  }
+Backup subcommands:
+  backup list                  List available backups
+  backup restore <timestamp>   Restore files from a backup
+  backup clean --keep <N>      Remove old backups, keep N most recent
 `.trim();
 
 async function main() {
@@ -58,24 +64,44 @@ async function main() {
     process.exit(1);
   }
 
+  const reporter = new Reporter(args.json ? 'json' : 'human');
+
   if (args.help || (!args.command && !args.version)) {
     console.log(USAGE);
     process.exit(0);
   }
 
   if (args.version) {
-    console.log(`island-bridge v${pkg.version}`);
+    if (args.json) {
+      reporter.setCommand('version');
+      reporter.info(pkg.version);
+      reporter.flush();
+    } else {
+      console.log(`island-bridge v${pkg.version}`);
+    }
     process.exit(0);
   }
 
-  const validCommands = ['pull', 'push', 'watch', 'diff', 'history'];
+  const validCommands = ['pull', 'push', 'watch', 'diff', 'history', 'init', 'status', 'backup'];
   if (!validCommands.includes(args.command)) {
-    console.error(`Unknown command: ${args.command}`);
-    console.error(`Valid commands: ${validCommands.join(', ')}`);
+    reporter.error(
+      `Unknown command: ${args.command}`,
+      `Valid commands: ${validCommands.join(', ')}`
+    );
+    if (args.json) reporter.flush();
     process.exit(1);
   }
 
-  // History doesn't need rsync
+  reporter.setCommand(args.command);
+
+  // === Init ===
+  if (args.command === 'init') {
+    const ok = await runInit(args, reporter);
+    if (args.json) reporter.flush();
+    process.exit(ok ? 0 : 1);
+  }
+
+  // === History (doesn't need rsync) ===
   if (args.command === 'history') {
     let config;
     try {
@@ -83,116 +109,239 @@ async function main() {
     } catch {
       // Show history from cwd if no config found
     }
-    showHistory(config?._filePath);
+    if (args.json) {
+      const { readFileSync: rfs, existsSync: efs } = await import('node:fs');
+      const { dirname: dn, join: jn } = await import('node:path');
+      const historyFile = config?._filePath
+        ? jn(dn(config._filePath), '.island-bridge-history.json')
+        : '.island-bridge-history.json';
+      let entries = [];
+      if (efs(historyFile)) {
+        try {
+          const parsed = JSON.parse(rfs(historyFile, 'utf-8'));
+          entries = Array.isArray(parsed) ? parsed : [];
+        } catch { /* ignore */ }
+      }
+      reporter.historyReport(entries);
+      reporter.flush();
+    } else {
+      showHistory(config?._filePath);
+    }
     process.exit(0);
   }
 
-  // Pre-flight: check rsync
+  // === Backup ===
+  if (args.command === 'backup') {
+    let config;
+    try {
+      config = loadConfig({ configPath: args.config, env: args.env });
+    } catch {
+      config = { backup: { enabled: true, localDir: '.island-bridge-backups', remoteDir: '~/.island-bridge-backups', maxCount: 10 } };
+    }
+    const backupConfig = config.backup;
+
+    if (args.subcommand === 'list') {
+      const backups = listBackups(backupConfig.localDir);
+      if (args.json) {
+        reporter.historyReport(backups.map(b => ({ timestamp: b.name, date: b.date.toISOString() })));
+        reporter.flush();
+      } else {
+        if (backups.length === 0) {
+          console.log('No backups found.');
+        } else {
+          console.log('\n--- Backups ---\n');
+          for (const b of backups) {
+            console.log(`  ${b.name}  (${b.date.toLocaleString()})`);
+          }
+          console.log(`\n${backups.length} backup(s) found.`);
+        }
+      }
+      process.exit(0);
+    }
+
+    if (args.subcommand === 'restore') {
+      if (!args.backupTimestamp) {
+        reporter.error('backup restore requires a timestamp', 'Run "island-bridge backup list" to see available backups');
+        if (args.json) reporter.flush();
+        process.exit(1);
+      }
+      try {
+        const results = restoreBackup(backupConfig.localDir, args.backupTimestamp);
+        if (args.json) {
+          for (const r of results) {
+            reporter.syncEnd(r.folder, r);
+          }
+          reporter.flush();
+        } else {
+          for (const r of results) {
+            if (r.success) {
+              console.log(`  \x1b[32m\u2713\x1b[0m ${r.folder} restored`);
+            } else {
+              console.log(`  \x1b[31m\u2717\x1b[0m ${r.folder} \u2014 ${r.error}`);
+            }
+          }
+        }
+      } catch (err) {
+        reporter.error(err.message, 'Run "island-bridge backup list" to see available backups');
+        if (args.json) reporter.flush();
+        process.exit(1);
+      }
+      process.exit(0);
+    }
+
+    if (args.subcommand === 'clean') {
+      const keep = args.keep || backupConfig.maxCount || 10;
+      const removed = cleanBackups(backupConfig.localDir, keep);
+      if (args.json) {
+        reporter.info(`Removed ${removed.length} backup(s), keeping ${keep}`);
+        reporter.flush();
+      } else {
+        if (removed.length === 0) {
+          console.log(`No backups to remove (keeping ${keep}).`);
+        } else {
+          for (const name of removed) {
+            console.log(`  Removed: ${name}`);
+          }
+          console.log(`\nRemoved ${removed.length} backup(s), keeping ${keep}.`);
+        }
+      }
+      process.exit(0);
+    }
+
+    reporter.error(
+      'Unknown backup subcommand',
+      'Usage: island-bridge backup <list|restore|clean>'
+    );
+    if (args.json) reporter.flush();
+    process.exit(1);
+  }
+
+  // === Pre-flight: check rsync ===
   const rsyncOk = await checkRsync();
   if (!rsyncOk) {
-    console.error('\x1b[31mError: rsync is required but not found in PATH. Install rsync and try again.\x1b[0m');
+    reporter.error(
+      'rsync is required but not found in PATH',
+      getErrorHint('rsync-not-found')
+    );
+    if (args.json) reporter.flush();
     process.exit(1);
   }
 
-  // Load config
+  // === Load config ===
   let config;
   try {
     config = loadConfig({ configPath: args.config, env: args.env });
   } catch (err) {
-    console.error(`\x1b[31mError: ${err.message}\x1b[0m`);
+    const hint = err.message.includes('Cannot find')
+      ? getErrorHint('config-not-found')
+      : null;
+    reporter.error(err.message, hint);
+    if (args.json) reporter.flush();
     process.exit(1);
   }
 
-  if (!args.quiet && args.env) {
-    console.log(`\x1b[90mUsing profile: ${args.env}\x1b[0m`);
+  if (args.env) {
+    reporter.info(`Using profile: ${args.env}`);
+  }
+  if (config._filePath) {
+    reporter.info(`Config: ${config._filePath}`);
   }
 
-  if (!args.quiet && config._filePath) {
-    console.log(`\x1b[90mConfig: ${config._filePath}\x1b[0m`);
+  // === Status ===
+  if (args.command === 'status') {
+    await runStatus(config, reporter);
+    if (args.json) reporter.flush();
+    process.exit(0);
+  }
+
+  // === --path filter ===
+  if (args.path.length > 0) {
+    const allNames = config.remote.paths.map(p => extractFolderName(p));
+    const invalid = args.path.filter(name => !allNames.includes(name));
+    if (invalid.length > 0) {
+      reporter.error(
+        `Unknown folder name(s): ${invalid.join(', ')}`,
+        `Available folders: ${allNames.join(', ')}`
+      );
+      if (args.json) reporter.flush();
+      process.exit(1);
+    }
+    config.remote.paths = config.remote.paths.filter(p =>
+      args.path.includes(extractFolderName(p))
+    );
   }
 
-  // Interactive selection
-  if (args.select && ['pull', 'push', 'diff'].includes(args.command)) {
-    config.remote.paths = await selectPaths(config.remote.paths);
+  // === Interactive selection ===
+  if (args.select && !args.json && ['pull', 'push', 'diff'].includes(args.command)) {
+    config.remote.paths = await selectPaths(config.remote.paths, reporter);
   }
 
-  // Watch mode
+  // === Watch mode ===
   if (args.command === 'watch') {
     startWatch(config, {
       dryRun: args.dryRun,
       verbose: args.verbose,
       quiet: args.quiet,
       bwlimit: args.bwlimit,
-    });
-    return; // watch runs indefinitely
+      noBackup: args.noBackup,
+    }, reporter);
+    return;
   }
 
-  // Diff preview
+  // === Diff preview ===
   if (args.command === 'diff') {
     const diffs = await diffPreview(config, 'pull', {
       bwlimit: args.bwlimit,
       exclude: config.exclude,
     });
-
-    if (diffs.length === 0) {
-      console.log('\nNo changes detected.');
-    } else {
-      for (const d of diffs) {
-        console.log(`\n\x1b[1m${d.folderName}\x1b[0m (${d.remotePath}):`);
-        for (const line of d.changes) {
-          if (line.startsWith('*deleting')) {
-            console.log(`  \x1b[31m- ${line}\x1b[0m`);
-          } else if (line.startsWith('>') || line.startsWith('<')) {
-            console.log(`  \x1b[32m+ ${line}\x1b[0m`);
-          } else {
-            console.log(`  \x1b[33m~ ${line}\x1b[0m`);
-          }
-        }
-      }
-    }
+    reporter.diffReport(diffs);
+    if (args.json) reporter.flush();
     process.exit(0);
   }
 
-  // Pull or Push
+  // === Pull or Push ===
   const options = {
     dryRun: args.dryRun,
     verbose: args.verbose,
     quiet: args.quiet,
     bwlimit: args.bwlimit,
+    noBackup: args.noBackup,
   };
 
-  // Disable hooks from configs found via upward search (planted-config protection)
+  // Disable hooks from configs found via upward search
   if (!config._explicitConfig && config._filePath !== join(process.cwd(), 'island-bridge.json')) {
     if (config.hooks.beforeSync || config.hooks.afterSync) {
-      console.warn(`\x1b[33mWarning: hooks ignored from inherited config ${config._filePath}\x1b[0m`);
-      console.warn(`\x1b[33mUse --config ${config._filePath} to explicitly enable hooks.\x1b[0m`);
+      reporter.warn(`hooks ignored from inherited config ${config._filePath}`);
+      reporter.warn(`Use --config ${config._filePath} to explicitly enable hooks.`);
       config.hooks = {};
     }
   }
 
   // Run beforeSync hook
   if (config.hooks.beforeSync) {
-    runHook('beforeSync', config.hooks.beforeSync, args.quiet);
+    runHook('beforeSync', config.hooks.beforeSync, args.quiet, reporter);
   }
 
-  const results = await syncAll(config, args.command, options);
+  const results = await syncAll(config, args.command, options, reporter);
 
   // Run afterSync hook
   if (config.hooks.afterSync) {
-    runHook('afterSync', config.hooks.afterSync, args.quiet);
+    runHook('afterSync', config.hooks.afterSync, args.quiet, reporter);
   }
 
   // Record history
   recordSync(config._filePath, args.command, results);
 
-  // Print summary (unless quiet)
-  if (!args.quiet) {
-    printSummary(results);
-    if (args.dryRun) {
-      console.log('\n\x1b[90m(dry-run mode \u2014 no changes were made)\x1b[0m');
+  // Print summary
+  if (!args.quiet || args.json) {
+    reporter.summary(results);
+    if (!args.json && args.dryRun) {
+      reporter.info('(dry-run mode \u2014 no changes were made)');
     }
   }
 
+  if (args.json) reporter.flush();
+
   const hasFailed = results.some(r => !r.success);
   process.exit(hasFailed ? 1 : 0);
 }

package/lib/args.js

@@ -5,15 +5,26 @@
 export function parseArgs(argv = process.argv.slice(2)) {
   const args = {
     command: null,
+    subcommand: null,
     dryRun: false,
     verbose: false,
     quiet: false,
+    json: false,
     config: null,
     env: null,
     bwlimit: null,
     select: false,
+    noBackup: false,
+    path: [],
     help: false,
     version: false,
+    // init-specific
+    host: null,
+    user: null,
+    paths: null,
+    // backup-specific
+    backupTimestamp: null,
+    keep: null,
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -31,6 +42,9 @@ export function parseArgs(argv = process.argv.slice(2)) {
       case '-q':
         args.quiet = true;
         break;
+      case '--json':
+        args.json = true;
+        break;
       case '--config':
       case '-c':
         args.config = argv[++i];
@@ -51,6 +65,35 @@ export function parseArgs(argv = process.argv.slice(2)) {
       case '-s':
         args.select = true;
         break;
+      case '--no-backup':
+        args.noBackup = true;
+        break;
+      case '--path':
+        {
+          const val = argv[++i];
+          if (!val || val.startsWith('-')) throw new Error('--path requires a folder name');
+          args.path.push(val);
+        }
+        break;
+      case '--host':
+        args.host = argv[++i];
+        if (!args.host) throw new Error('--host requires a value');
+        break;
+      case '--user':
+        args.user = argv[++i];
+        if (!args.user) throw new Error('--user requires a value');
+        break;
+      case '--paths':
+        args.paths = argv[++i];
+        if (!args.paths) throw new Error('--paths requires a value');
+        break;
+      case '--keep':
+        args.keep = argv[++i];
+        if (!args.keep || isNaN(Number(args.keep))) {
+          throw new Error('--keep requires a numeric value');
+        }
+        args.keep = Number(args.keep);
+        break;
       case '--help':
       case '-h':
         args.help = true;
@@ -60,8 +103,14 @@ export function parseArgs(argv = process.argv.slice(2)) {
         args.version = true;
         break;
       default:
-        if (!arg.startsWith('-') && !args.command) {
-          args.command = arg;
+        if (!arg.startsWith('-')) {
+          if (!args.command) {
+            args.command = arg;
+          } else if (args.command === 'backup' && !args.subcommand) {
+            args.subcommand = arg;
+          } else if (args.command === 'backup' && args.subcommand === 'restore' && !args.backupTimestamp) {
+            args.backupTimestamp = arg;
+          }
         }
         break;
     }