island-bridge 1.0.0 → 1.1.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

@@ -59,13 +59,152 @@ 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 |
+
+## 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 |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
+
+## 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,
+  "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
+# 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
+
+# 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
+
+# View sync history
+island-bridge history
+```
+
 ## 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
 

package/bin/cli.js

@@ -1,42 +1,92 @@
 #!/usr/bin/env node
 
+import { parseArgs } from '../lib/args.js';
 import { loadConfig } from '../lib/config.js';
-import { checkRsync, syncAll } from '../lib/sync.js';
+import { checkRsync, syncAll, diffPreview } from '../lib/sync.js';
 import { printSummary } from '../lib/summary.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 { 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
+  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
+
+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
+  -V, --version        Show version
+  -h, --help           Show this help message
 
-Config:
-  Place an island-bridge.json in the working directory:
+Config (island-bridge.json):
   {
-    "remote": {
-      "host": "192.168.1.100",
-      "user": "deploy",
-      "paths": ["/var/www/app", "/etc/nginx/conf.d"]
-    }
+    "remote": { "host": "...", "user": "...", "paths": [...] },
+    "exclude": ["node_modules", "*.log"],
+    "bwlimit": 1000,
+    "hooks": { "beforeSync": "...", "afterSync": "..." },
+    "profiles": { "staging": { "remote": { ... } } }
   }
 `.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);
+  }
 
-  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) {
+    console.log(`island-bridge v${pkg.version}`);
+    process.exit(0);
+  }
+
+  const validCommands = ['pull', 'push', 'watch', 'diff', 'history'];
+  if (!validCommands.includes(args.command)) {
+    console.error(`Unknown command: ${args.command}`);
+    console.error(`Valid commands: ${validCommands.join(', ')}`);
     process.exit(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
+    }
+    showHistory(config?._filePath);
+    process.exit(0);
+  }
+
   // Pre-flight: check rsync
   const rsyncOk = await checkRsync();
   if (!rsyncOk) {
@@ -47,19 +97,102 @@ async function main() {
   // 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`);
     process.exit(1);
   }
 
-  // Execute sync
-  const results = await syncAll(config, command);
+  if (!args.quiet && args.env) {
+    console.log(`\x1b[90mUsing profile: ${args.env}\x1b[0m`);
+  }
+
+  if (!args.quiet && config._filePath) {
+    console.log(`\x1b[90mConfig: ${config._filePath}\x1b[0m`);
+  }
+
+  // Interactive selection
+  if (args.select && ['pull', 'push', 'diff'].includes(args.command)) {
+    config.remote.paths = await selectPaths(config.remote.paths);
+  }
+
+  // Watch mode
+  if (args.command === 'watch') {
+    startWatch(config, {
+      dryRun: args.dryRun,
+      verbose: args.verbose,
+      quiet: args.quiet,
+      bwlimit: args.bwlimit,
+    });
+    return; // watch runs indefinitely
+  }
+
+  // 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`);
+          }
+        }
+      }
+    }
+    process.exit(0);
+  }
+
+  // Pull or Push
+  const options = {
+    dryRun: args.dryRun,
+    verbose: args.verbose,
+    quiet: args.quiet,
+    bwlimit: args.bwlimit,
+  };
+
+  // Disable hooks from configs found via upward search (planted-config protection)
+  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`);
+      config.hooks = {};
+    }
+  }
+
+  // Run beforeSync hook
+  if (config.hooks.beforeSync) {
+    runHook('beforeSync', config.hooks.beforeSync, args.quiet);
+  }
+
+  const results = await syncAll(config, args.command, options);
 
-  // Print summary
-  printSummary(results);
+  // Run afterSync hook
+  if (config.hooks.afterSync) {
+    runHook('afterSync', config.hooks.afterSync, args.quiet);
+  }
+
+  // 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');
+    }
+  }
 
-  // Exit with non-zero code if any transfers failed
   const hasFailed = results.some(r => !r.success);
   process.exit(hasFailed ? 1 : 0);
 }

package/lib/args.js

@@ -0,0 +1,75 @@
+/**
+ * Lightweight CLI argument parser for island-bridge.
+ * Zero dependencies.
+ */
+export function parseArgs(argv = process.argv.slice(2)) {
+  const args = {
+    command: null,
+    dryRun: false,
+    verbose: false,
+    quiet: false,
+    config: null,
+    env: null,
+    bwlimit: null,
+    select: false,
+    help: false,
+    version: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--dry-run':
+      case '-n':
+        args.dryRun = true;
+        break;
+      case '--verbose':
+      case '-v':
+        args.verbose = true;
+        break;
+      case '--quiet':
+      case '-q':
+        args.quiet = true;
+        break;
+      case '--config':
+      case '-c':
+        args.config = argv[++i];
+        if (!args.config || args.config.startsWith('-')) throw new Error('--config requires a file path');
+        break;
+      case '--env':
+        args.env = argv[++i];
+        if (!args.env || args.env.startsWith('-')) throw new Error('--env requires a profile name');
+        break;
+      case '--bwlimit':
+        args.bwlimit = argv[++i];
+        if (!args.bwlimit || isNaN(Number(args.bwlimit))) {
+          throw new Error('--bwlimit requires a numeric value (KB/s)');
+        }
+        args.bwlimit = Number(args.bwlimit);
+        break;
+      case '--select':
+      case '-s':
+        args.select = true;
+        break;
+      case '--help':
+      case '-h':
+        args.help = true;
+        break;
+      case '--version':
+      case '-V':
+        args.version = true;
+        break;
+      default:
+        if (!arg.startsWith('-') && !args.command) {
+          args.command = arg;
+        }
+        break;
+    }
+  }
+
+  if (args.verbose && args.quiet) {
+    throw new Error('Cannot use --verbose and --quiet together');
+  }
+
+  return args;
+}

package/lib/config.js

@@ -1,27 +1,87 @@
-import { readFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+import { basename, resolve, dirname, join } from 'node:path';
 
 const CONFIG_FILE = 'island-bridge.json';
 
 /**
- * Load and validate config from island-bridge.json in cwd.
+ * Search for config file starting from startDir, walking up to root.
  */
-export function loadConfig() {
+export function findConfigFile(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+
+  while (true) {
+    const candidate = join(dir, CONFIG_FILE);
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Load and validate config.
+ * @param {object} [options]
+ * @param {string} [options.configPath] - Explicit config file path (--config)
+ * @param {string} [options.env] - Profile name to merge (--env)
+ */
+export function loadConfig({ configPath, env } = {}) {
+  let filePath;
+
+  if (configPath) {
+    filePath = resolve(configPath);
+    if (!existsSync(filePath)) {
+      throw new Error(`Config file not found: ${configPath}`);
+    }
+  } else {
+    filePath = findConfigFile();
+    if (!filePath) {
+      throw new Error(`Cannot find ${CONFIG_FILE} in current or parent directories`);
+    }
+  }
+
   let raw;
   try {
-    raw = readFileSync(CONFIG_FILE, 'utf-8');
+    raw = readFileSync(filePath, 'utf-8');
   } catch {
-    throw new Error(`Failed to read ${CONFIG_FILE} from current directory`);
+    throw new Error(`Failed to read config: ${filePath}`);
   }
 
   let config;
   try {
     config = JSON.parse(raw);
   } catch {
-    throw new Error(`Failed to parse ${CONFIG_FILE}: invalid JSON`);
+    throw new Error(`Failed to parse ${filePath}: invalid JSON`);
+  }
+
+  // Merge profile if specified
+  if (env) {
+    if (env === '__proto__' || env === 'constructor' || env === 'prototype') {
+      throw new Error(`Config error: profile name '${env}' is not allowed`);
+    }
+    if (!config.profiles || !config.profiles[env]) {
+      const available = config.profiles ? Object.keys(config.profiles).join(', ') : 'none';
+      throw new Error(`Profile '${env}' not found. Available: ${available}`);
+    }
+    const profile = config.profiles[env];
+    config = {
+      ...config,
+      ...profile,
+      remote: { ...config.remote, ...profile.remote },
+      hooks: { ...config.hooks, ...profile.hooks },
+    };
   }
 
   validate(config);
+
+  // Normalize optional fields
+  config.exclude = config.exclude || [];
+  config.hooks = config.hooks || {};
+  config.bwlimit = config.bwlimit || null;
+  config._filePath = filePath;
+  config._explicitConfig = !!configPath;
+
   return config;
 }
 
@@ -38,15 +98,15 @@ function validate(config) {
   if (!host || typeof host !== 'string' || host.trim() === '') {
     throw new Error("Config error: 'host' must be a non-empty string");
   }
-  if (host.startsWith('-') || /\s/.test(host)) {
-    throw new Error("Config error: 'host' must not start with '-' or contain whitespace");
+  if (!/^[a-zA-Z0-9._:-]+$/.test(host)) {
+    throw new Error("Config error: 'host' contains invalid characters. Use hostname, IPv4, or IPv6 only");
   }
 
   if (!user || typeof user !== 'string' || user.trim() === '') {
     throw new Error("Config error: 'user' must be a non-empty string");
   }
-  if (user.startsWith('-') || /\s/.test(user)) {
-    throw new Error("Config error: 'user' must not start with '-' or contain whitespace");
+  if (!/^[a-zA-Z0-9._-]+$/.test(user)) {
+    throw new Error("Config error: 'user' contains invalid characters");
   }
 
   if (!Array.isArray(paths) || paths.length === 0) {
@@ -61,12 +121,59 @@ function validate(config) {
     if (p.startsWith('-')) {
       throw new Error(`Config error: remote path '${p}' must not start with '-'`);
     }
+    if (/[`$;|&><(){}]/.test(p)) {
+      throw new Error(`Config error: remote path '${p}' contains disallowed characters`);
+    }
     const name = extractFolderName(p);
     if (seen.has(name)) {
       throw new Error(`Config error: folder name collision — multiple remote paths resolve to '${name}'`);
     }
     seen.add(name);
   }
+
+  // Validate exclude
+  if (config.exclude !== undefined) {
+    if (!Array.isArray(config.exclude)) {
+      throw new Error("Config error: 'exclude' must be an array of strings");
+    }
+    for (const e of config.exclude) {
+      if (typeof e !== 'string') {
+        throw new Error("Config error: each exclude pattern must be a string");
+      }
+      if (e.startsWith('-')) {
+        throw new Error(`Config error: exclude pattern '${e}' must not start with '-'`);
+      }
+    }
+  }
+
+  // Validate hooks
+  if (config.hooks !== undefined) {
+    if (typeof config.hooks !== 'object' || Array.isArray(config.hooks)) {
+      throw new Error("Config error: 'hooks' must be an object");
+    }
+    for (const key of Object.keys(config.hooks)) {
+      if (key !== 'beforeSync' && key !== 'afterSync') {
+        throw new Error(`Config error: unknown hook '${key}'. Supported: beforeSync, afterSync`);
+      }
+      if (typeof config.hooks[key] !== 'string') {
+        throw new Error(`Config error: hook '${key}' must be a string`);
+      }
+    }
+  }
+
+  // Validate bwlimit
+  if (config.bwlimit !== undefined && config.bwlimit !== null) {
+    if (typeof config.bwlimit !== 'number' || config.bwlimit <= 0) {
+      throw new Error("Config error: 'bwlimit' must be a positive number (KB/s)");
+    }
+  }
+
+  // Validate profiles
+  if (config.profiles !== undefined) {
+    if (typeof config.profiles !== 'object' || Array.isArray(config.profiles)) {
+      throw new Error("Config error: 'profiles' must be an object");
+    }
+  }
 }
 
 /**

package/lib/history.js

@@ -0,0 +1,94 @@
+import { readFileSync, writeFileSync, existsSync, lstatSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const HISTORY_FILE = '.island-bridge-history.json';
+
+/**
+ * Record a sync operation to history.
+ */
+export function recordSync(configPath, direction, results) {
+  const historyPath = configPath ? join(dirname(configPath), HISTORY_FILE) : HISTORY_FILE;
+
+  let history = [];
+  if (existsSync(historyPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(historyPath, 'utf-8'));
+      history = Array.isArray(parsed) ? parsed : [];
+    } catch {
+      history = [];
+    }
+  }
+
+  const entry = {
+    timestamp: new Date().toISOString(),
+    direction,
+    folders: results.map(r => ({
+      name: r.folderName,
+      path: r.remotePath,
+      success: r.success,
+      error: r.error || null,
+    })),
+    success: results.every(r => r.success),
+    total: results.length,
+    failed: results.filter(r => !r.success).length,
+  };
+
+  history.push(entry);
+
+  // Keep last 100 entries
+  if (history.length > 100) {
+    history = history.slice(-100);
+  }
+
+  // Refuse to write through symlinks
+  if (existsSync(historyPath) && lstatSync(historyPath).isSymbolicLink()) {
+    return;
+  }
+
+  try {
+    writeFileSync(historyPath, JSON.stringify(history, null, 2) + '\n');
+  } catch {
+    // Silently ignore write errors for history
+  }
+}
+
+/**
+ * Display sync history.
+ */
+export function showHistory(configPath) {
+  const historyPath = configPath ? join(dirname(configPath), HISTORY_FILE) : HISTORY_FILE;
+
+  if (!existsSync(historyPath)) {
+    console.log('No sync history found.');
+    return;
+  }
+
+  let history;
+  try {
+    const parsed = JSON.parse(readFileSync(historyPath, 'utf-8'));
+    history = Array.isArray(parsed) ? parsed : [];
+  } catch {
+    console.log('Failed to read history file.');
+    return;
+  }
+
+  if (history.length === 0) {
+    console.log('No sync history found.');
+    return;
+  }
+
+  console.log('\n--- Sync History ---\n');
+
+  const recent = history.slice(-20);
+  for (const entry of recent) {
+    const date = new Date(entry.timestamp).toLocaleString();
+    const status = entry.success ? '\x1b[32m\u2713\x1b[0m' : '\x1b[31m\u2717\x1b[0m';
+    const dir = entry.direction === 'pull' ? '\u2193 pull' : '\u2191 push';
+    const folders = entry.folders.map(f => f.name).join(', ');
+    const stats = `${entry.total - entry.failed}/${entry.total} ok`;
+
+    console.log(`  ${status} ${date}  ${dir}  [${folders}]  ${stats}`);
+  }
+
+  console.log(`\nShowing last ${recent.length} of ${history.length} entries.`);
+}

package/lib/hooks.js

@@ -0,0 +1,26 @@
+import { execSync } from 'node:child_process';
+
+/**
+ * Execute a hook command.
+ * @param {string} name - Hook name (beforeSync, afterSync)
+ * @param {string} command - Shell command to execute
+ * @param {boolean} quiet - Suppress output
+ */
+export function runHook(name, command, quiet = false) {
+  if (!command) return;
+
+  if (!quiet) {
+    console.log(`\x1b[90m[hook:${name}] ${command}\x1b[0m`);
+  }
+
+  try {
+    execSync(command, {
+      stdio: quiet ? 'ignore' : 'inherit',
+      timeout: 30000,
+      shell: true,
+    });
+  } catch (err) {
+    const msg = err.status ? `exited with code ${err.status}` : err.message;
+    console.error(`\x1b[33mWarning: hook '${name}' failed: ${msg}\x1b[0m`);
+  }
+}

package/lib/interactive.js

@@ -0,0 +1,46 @@
+import { createInterface } from 'node:readline';
+import { extractFolderName } from './config.js';
+
+/**
+ * Interactive path selection.
+ * Returns filtered paths array.
+ */
+export async function selectPaths(paths) {
+  console.log('\nAvailable folders:\n');
+
+  const folders = paths.map((p, i) => {
+    const name = extractFolderName(p);
+    console.log(`  ${i + 1}) ${name} (${p})`);
+    return { index: i, name, path: p };
+  });
+
+  console.log(`  a) All\n`);
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  const answer = await new Promise((resolve) => {
+    rl.question('Select folders (comma-separated numbers or "a" for all): ', resolve);
+  });
+  rl.close();
+
+  const input = answer.trim().toLowerCase();
+
+  if (input === 'a' || input === 'all' || input === '') {
+    return paths;
+  }
+
+  const indices = input.split(',')
+    .map(s => parseInt(s.trim(), 10) - 1)
+    .filter(i => i >= 0 && i < paths.length);
+
+  if (indices.length === 0) {
+    console.log('No valid selection, using all folders.');
+    return paths;
+  }
+
+  const selected = indices.map(i => paths[i]);
+  const names = indices.map(i => folders[i].name).join(', ');
+  console.log(`\nSelected: ${names}\n`);
+
+  return selected;
+}

package/lib/progress.js

@@ -2,8 +2,11 @@
  * Parse rsync stdout output in real-time.
  * - Lines NOT starting with whitespace = filenames (from -v verbose)
  * - Lines starting with whitespace = progress updates from --info=progress2
+ * @param {object} stdout - Readable stream
+ * @param {object} [options]
+ * @param {boolean} [options.verbose] - Show extra detail
  */
-export function streamProgress(stdout) {
+export function streamProgress(stdout, options = {}) {
   let buffer = '';
 
   stdout.on('data', (chunk) => {

package/lib/sync.js

@@ -17,8 +17,19 @@ export async function checkRsync() {
 
 /**
  * Build rsync arguments for a single path sync.
+ * @param {string} user
+ * @param {string} host
+ * @param {string} remotePath
+ * @param {string} localPath
+ * @param {string} direction - 'pull' or 'push'
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun] - Preview only
+ * @param {boolean} [options.verbose] - Extra verbosity
+ * @param {string[]} [options.exclude] - Exclude patterns
+ * @param {number} [options.bwlimit] - Bandwidth limit in KB/s
+ * @param {boolean} [options.itemize] - Show itemized changes (for diff preview)
  */
-export function buildRsyncArgs(user, host, remotePath, localPath, direction) {
+export function buildRsyncArgs(user, host, remotePath, localPath, direction, options = {}) {
   const remote = `${user}@${host}:${remotePath.replace(/\/+$/, '')}/`;
   const local = `${localPath.replace(/\/+$/, '')}/`;
 
@@ -30,9 +41,32 @@ export function buildRsyncArgs(user, host, remotePath, localPath, direction) {
     '--info=progress2',
     '--filter=:- .gitignore',
     '-e', 'ssh',
-    '--', // terminate option parsing to prevent injection
   ];
 
+  if (options.dryRun) {
+    args.push('--dry-run');
+  }
+
+  if (options.verbose) {
+    args.push('--verbose');
+  }
+
+  if (options.itemize) {
+    args.push('--itemize-changes');
+  }
+
+  if (options.bwlimit) {
+    args.push(`--bwlimit=${options.bwlimit}`);
+  }
+
+  if (options.exclude) {
+    for (const pattern of options.exclude) {
+      args.push(`--exclude=${pattern}`);
+    }
+  }
+
+  args.push('--'); // terminate option parsing to prevent injection
+
   if (direction === 'pull') {
     args.push(remote, local);
   } else {
@@ -44,10 +78,15 @@ export function buildRsyncArgs(user, host, remotePath, localPath, direction) {
 
 /**
  * Execute sync for all configured remote paths.
+ * @param {object} config - Parsed config
+ * @param {string} direction - 'pull' or 'push'
+ * @param {object} [options] - CLI options
  */
-export async function syncAll(config, direction) {
+export async function syncAll(config, direction, options = {}) {
   const results = [];
   const { host, user, paths } = config.remote;
+  const mergedExclude = [...(config.exclude || []), ...(options.exclude || [])];
+  const mergedBwlimit = options.bwlimit || config.bwlimit || null;
 
   for (const remotePath of paths) {
     let folderName;
@@ -60,7 +99,9 @@ export async function syncAll(config, direction) {
 
     // For push: check local folder exists
     if (direction === 'push' && !existsSync(folderName)) {
-      console.log(`\x1b[33mWarning: local folder '${folderName}' does not exist, skipping push\x1b[0m`);
+      if (!options.quiet) {
+        console.log(`\x1b[33mWarning: local folder '${folderName}' does not exist, skipping push\x1b[0m`);
+      }
       results.push({
         folderName,
         remotePath,
@@ -70,28 +111,95 @@ export async function syncAll(config, direction) {
       continue;
     }
 
-    const label = direction === 'pull' ? 'Pulling' : 'Pushing';
-    console.log(`\n\x1b[1m${label} ${folderName}\x1b[0m (${remotePath})`);
+    if (!options.quiet) {
+      const label = direction === 'pull' ? 'Pulling' : 'Pushing';
+      const dryLabel = options.dryRun ? ' (dry-run)' : '';
+      console.log(`\n\x1b[1m${label} ${folderName}\x1b[0m (${remotePath})${dryLabel}`);
+    }
+
+    const rsyncOptions = {
+      dryRun: options.dryRun,
+      verbose: options.verbose,
+      exclude: mergedExclude,
+      bwlimit: mergedBwlimit,
+    };
 
-    const args = buildRsyncArgs(user, host, remotePath, folderName, direction);
-    const result = await runRsync(args, folderName, remotePath);
+    const args = buildRsyncArgs(user, host, remotePath, folderName, direction, rsyncOptions);
+    const result = await runRsync(args, folderName, remotePath, options);
     results.push(result);
   }
 
   return results;
 }
 
+/**
+ * Run rsync in diff/preview mode — returns itemized changes.
+ */
+export async function diffPreview(config, direction, options = {}) {
+  const results = [];
+  const { host, user, paths } = config.remote;
+  const mergedExclude = [...(config.exclude || []), ...(options.exclude || [])];
+
+  for (const remotePath of paths) {
+    let folderName;
+    try {
+      folderName = extractFolderName(remotePath);
+    } catch {
+      continue;
+    }
+
+    const rsyncOptions = {
+      dryRun: true,
+      itemize: true,
+      exclude: mergedExclude,
+      bwlimit: options.bwlimit || config.bwlimit || null,
+    };
+
+    const args = buildRsyncArgs(user, host, remotePath, folderName, direction, rsyncOptions);
+    const changes = await runRsyncCapture(args);
+    if (changes.length > 0) {
+      results.push({ folderName, remotePath, changes });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Run rsync and capture full output (for diff preview).
+ */
+function runRsyncCapture(args) {
+  return new Promise((resolve) => {
+    const child = spawn('rsync', args, {
+      stdio: ['inherit', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (data) => { stdout += data.toString(); });
+    child.stderr.resume();
+    child.on('error', () => resolve([]));
+    child.on('close', () => {
+      const lines = stdout.split('\n').filter(l => l.trim() && !l.startsWith(' ') && l !== './');
+      resolve(lines);
+    });
+  });
+}
+
 /**
  * Run a single rsync command and return the result.
  */
-function runRsync(args, folderName, remotePath) {
+function runRsync(args, folderName, remotePath, options = {}) {
   return new Promise((resolve) => {
     const child = spawn('rsync', args, {
       stdio: ['inherit', 'pipe', 'pipe'], // stdin inherited for SSH password prompts
     });
 
-    // Stream stdout for progress display
-    streamProgress(child.stdout);
+    // Stream stdout for progress display (unless quiet)
+    if (!options.quiet) {
+      streamProgress(child.stdout, options);
+    } else {
+      child.stdout.resume(); // drain stdout to prevent backpressure
+    }
 
     // Capture stderr
     let stderr = '';

package/lib/watch.js

@@ -0,0 +1,64 @@
+import { watch as fsWatch } from 'node:fs';
+import { resolve } from 'node:path';
+import { extractFolderName } from './config.js';
+import { syncAll } from './sync.js';
+
+/**
+ * Watch local folders for changes and auto-push.
+ */
+export function startWatch(config, options = {}) {
+  const { paths } = config.remote;
+  const debounceMs = 500;
+  let timer = null;
+  let syncing = false;
+
+  const folders = paths.map(p => extractFolderName(p));
+
+  console.log('\x1b[1mWatching for changes...\x1b[0m');
+  for (const folder of folders) {
+    console.log(`  \x1b[36m→\x1b[0m ${folder}/`);
+  }
+  console.log('\nPress Ctrl+C to stop.\n');
+
+  const watchers = [];
+
+  for (const folder of folders) {
+    const absPath = resolve(folder);
+    try {
+      const watcher = fsWatch(absPath, { recursive: true }, (eventType, filename) => {
+        if (filename && (filename.startsWith('.') || filename.endsWith('~') || filename.endsWith('.swp'))) {
+          return;
+        }
+
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(async () => {
+          if (syncing) return;
+          syncing = true;
+
+          const time = new Date().toLocaleTimeString();
+          console.log(`\x1b[90m[${time}]\x1b[0m Change detected${filename ? `: ${filename}` : ''}`);
+
+          try {
+            await syncAll(config, 'push', options);
+          } catch (err) {
+            console.error(`\x1b[31mSync error: ${err.message}\x1b[0m`);
+          }
+
+          syncing = false;
+          console.log('\x1b[90mWatching for changes...\x1b[0m\n');
+        }, debounceMs);
+      });
+      watchers.push(watcher);
+    } catch (err) {
+      console.error(`\x1b[33mWarning: cannot watch '${folder}': ${err.message}\x1b[0m`);
+    }
+  }
+
+  process.on('SIGINT', () => {
+    console.log('\n\x1b[1mStopping watch...\x1b[0m');
+    for (const w of watchers) w.close();
+    process.exit(0);
+  });
+
+  return watchers;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "island-bridge",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Sync remote server folders to local directory via rsync over SSH",
   "type": "module",
   "bin": {
@@ -11,7 +11,7 @@
     "lib/"
   ],
   "scripts": {
-    "test": "node --test test/config.test.js"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "rsync",