island-bridge 1.0.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gong1414
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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
 {
@@ -59,15 +78,254 @@ This creates local subdirectories matching the remote folder names:
 island-bridge push
 ```
 
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pull` | Pull remote folders to local directory |
+| `push` | Push local folders to remote server |
+| `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
+
+| Option | Description |
+|--------|-------------|
+| `-n, --dry-run` | Preview sync without making changes |
+| `-v, --verbose` | Show detailed output |
+| `-q, --quiet` | Suppress output (exit code only) |
+| `-c, --config <path>` | Use specific config file |
+| `--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
+{
+  "remote": {
+    "host": "192.168.1.100",
+    "user": "deploy",
+    "paths": ["/var/www/app", "/etc/nginx/conf.d"]
+  },
+  "exclude": ["node_modules", ".DS_Store", "*.log"],
+  "bwlimit": 1000,
+  "backup": {
+    "enabled": true,
+    "maxCount": 10
+  },
+  "hooks": {
+    "beforeSync": "echo 'Starting sync...'",
+    "afterSync": "pm2 restart app"
+  },
+  "profiles": {
+    "staging": {
+      "remote": {
+        "host": "staging.example.com",
+        "user": "deploy",
+        "paths": ["/var/www/app"]
+      }
+    },
+    "production": {
+      "remote": {
+        "host": "prod.example.com",
+        "user": "admin",
+        "paths": ["/var/www/app"]
+      }
+    }
+  }
+}
+```
+
+### Exclude Rules
+
+Custom exclude patterns are applied in addition to `.gitignore` rules:
+
+```json
+{
+  "exclude": ["node_modules", "*.log", ".env"]
+}
+```
+
+### Hooks
+
+Run shell commands before and after sync:
+
+```json
+{
+  "hooks": {
+    "beforeSync": "npm run build",
+    "afterSync": "ssh deploy@server 'pm2 restart app'"
+  }
+}
+```
+
+### Multi-Environment Profiles
+
+Switch between environments using `--env`:
+
+```bash
+island-bridge pull --env staging
+island-bridge push --env production
+```
+
+Profile settings are merged over the base config.
+
+### Config File Search
+
+The config file is searched starting from the current directory upward (like `.gitignore`). Use `--config` to specify an explicit path:
+
+```bash
+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
+
+# Diff preview (itemized changes)
+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
+
+# Select specific folders interactively
+island-bridge pull --select
+
+# Use staging profile
+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
 
 - **Bidirectional sync** — `pull` downloads, `push` uploads
 - **Multi-folder** — sync multiple remote paths in one config
 - **rsync over SSH** — uses system SSH config for authentication
 - **Auto .gitignore** — respects `.gitignore` exclusion rules
+- **Custom excludes** — additional exclude patterns in config
 - **Progress display** — real-time per-file transfer with color output
+- **Dry-run mode** — preview changes without syncing
+- **Diff preview** — see itemized file changes before sync
+- **Watch mode** — auto-push on local file changes
+- **Multi-environment** — switch profiles with `--env`
+- **Interactive select** — choose which folders to sync
+- **Hooks** — run commands before/after sync
+- **Bandwidth limit** — control transfer speed
+- **Sync history** — track past sync operations
+- **Verbose/Quiet** — control output detail level
+- **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,65 +1,347 @@
 #!/usr/bin/env node
 
-import { loadConfig } from '../lib/config.js';
-import { checkRsync, syncAll } from '../lib/sync.js';
-import { printSummary } from '../lib/summary.js';
+import { parseArgs } from '../lib/args.js';
+import { loadConfig, extractFolderName } from '../lib/config.js';
+import { checkRsync, syncAll, diffPreview } from '../lib/sync.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';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 
 const USAGE = `
-island-bridge - Sync remote folders to local directory via rsync
+island-bridge v${pkg.version} - Sync remote folders via rsync over SSH
 
 Usage:
-  island-bridge pull    Pull remote folders to local directory
-  island-bridge push    Push local folders to remote server
-  island-bridge --help  Show this help message
-
-Config:
-  Place an island-bridge.json in the working directory:
-  {
-    "remote": {
-      "host": "192.168.1.100",
-      "user": "deploy",
-      "paths": ["/var/www/app", "/etc/nginx/conf.d"]
-    }
-  }
+  island-bridge <command> [options]
+
+Commands:
+  pull        Pull remote folders to local directory
+  push        Push local folders to remote server
+  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
+  -v, --verbose        Show detailed output
+  -q, --quiet          Suppress output (exit code only)
+  -c, --config <path>  Use specific config file
+      --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
+
+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() {
-  const command = process.argv[2];
+  let args;
+  try {
+    args = parseArgs();
+  } catch (err) {
+    console.error(`\x1b[31mError: ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+
+  const reporter = new Reporter(args.json ? 'json' : 'human');
 
-  if (!command || command === '--help' || command === '-h') {
+  if (args.help || (!args.command && !args.version)) {
     console.log(USAGE);
     process.exit(0);
   }
 
-  if (command !== 'pull' && command !== 'push') {
-    console.error(`Unknown command: ${command}`);
-    console.error('Use "island-bridge pull" or "island-bridge push"');
+  if (args.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', 'init', 'status', 'backup'];
+  if (!validCommands.includes(args.command)) {
+    reporter.error(
+      `Unknown command: ${args.command}`,
+      `Valid commands: ${validCommands.join(', ')}`
+    );
+    if (args.json) reporter.flush();
+    process.exit(1);
+  }
+
+  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 {
+      config = loadConfig({ configPath: args.config, env: args.env });
+    } catch {
+      // Show history from cwd if no config found
+    }
+    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);
+  }
+
+  // === 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
+  // === 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();
+    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);
   }
 
-  // Execute sync
-  const results = await syncAll(config, command);
+  if (args.env) {
+    reporter.info(`Using profile: ${args.env}`);
+  }
+  if (config._filePath) {
+    reporter.info(`Config: ${config._filePath}`);
+  }
+
+  // === 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 && !args.json && ['pull', 'push', 'diff'].includes(args.command)) {
+    config.remote.paths = await selectPaths(config.remote.paths, reporter);
+  }
+
+  // === Watch mode ===
+  if (args.command === 'watch') {
+    startWatch(config, {
+      dryRun: args.dryRun,
+      verbose: args.verbose,
+      quiet: args.quiet,
+      bwlimit: args.bwlimit,
+      noBackup: args.noBackup,
+    }, reporter);
+    return;
+  }
+
+  // === Diff preview ===
+  if (args.command === 'diff') {
+    const diffs = await diffPreview(config, 'pull', {
+      bwlimit: args.bwlimit,
+      exclude: config.exclude,
+    });
+    reporter.diffReport(diffs);
+    if (args.json) reporter.flush();
+    process.exit(0);
+  }
+
+  // === 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
+  if (!config._explicitConfig && config._filePath !== join(process.cwd(), 'island-bridge.json')) {
+    if (config.hooks.beforeSync || config.hooks.afterSync) {
+      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, reporter);
+  }
+
+  const results = await syncAll(config, args.command, options, reporter);
+
+  // Run afterSync hook
+  if (config.hooks.afterSync) {
+    runHook('afterSync', config.hooks.afterSync, args.quiet, reporter);
+  }
+
+  // Record history
+  recordSync(config._filePath, args.command, results);
 
   // Print summary
-  printSummary(results);
+  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();
 
-  // Exit with non-zero code if any transfers failed
   const hasFailed = results.some(r => !r.success);
   process.exit(hasFailed ? 1 : 0);
 }