island-bridge 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# island-bridge
+
+Sync remote server folders to local directory via rsync over SSH.
+
+## Install
+
+```bash
+npm install -g island-bridge
+```
+
+Or use directly with npx:
+
+```bash
+npx island-bridge pull
+npx island-bridge push
+```
+
+## Prerequisites
+
+- Node.js >= 18
+- `rsync` installed on both local and remote machines
+- SSH access to remote server (uses system `~/.ssh/config`)
+
+## Usage
+
+1. Create `island-bridge.json` in your working directory:
+
+```json
+{
+  "remote": {
+    "host": "192.168.1.100",
+    "user": "deploy",
+    "paths": [
+      "/var/www/app",
+      "/etc/nginx/conf.d",
+      "/home/deploy/scripts"
+    ]
+  }
+}
+```
+
+2. Pull remote folders to local:
+
+```bash
+island-bridge pull
+```
+
+This creates local subdirectories matching the remote folder names:
+
+```
+./app/           <- from /var/www/app
+./conf.d/        <- from /etc/nginx/conf.d
+./scripts/       <- from /home/deploy/scripts
+```
+
+3. Push local changes back to remote:
+
+```bash
+island-bridge push
+```
+
+## 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
+- **Progress display** — real-time per-file transfer with color output
+- **Fault tolerant** — skips failed transfers, reports summary at end
+- **Zero dependencies** — pure Node.js, no npm dependencies
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { loadConfig } from '../lib/config.js';
+import { checkRsync, syncAll } from '../lib/sync.js';
+import { printSummary } from '../lib/summary.js';
+
+const USAGE = `
+island-bridge - Sync remote folders to local directory via rsync
+
+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"]
+    }
+  }
+`.trim();
+
+async function main() {
+  const command = process.argv[2];
+
+  if (!command || command === '--help' || command === '-h') {
+    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"');
+    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');
+    process.exit(1);
+  }
+
+  // Load config
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    console.error(`\x1b[31mError: ${err.message}\x1b[0m`);
+    process.exit(1);
+  }
+
+  // Execute sync
+  const results = await syncAll(config, command);
+
+  // Print summary
+  printSummary(results);
+
+  // Exit with non-zero code if any transfers failed
+  const hasFailed = results.some(r => !r.success);
+  process.exit(hasFailed ? 1 : 0);
+}
+
+main();

package/lib/config.js

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+
+const CONFIG_FILE = 'island-bridge.json';
+
+/**
+ * Load and validate config from island-bridge.json in cwd.
+ */
+export function loadConfig() {
+  let raw;
+  try {
+    raw = readFileSync(CONFIG_FILE, 'utf-8');
+  } catch {
+    throw new Error(`Failed to read ${CONFIG_FILE} from current directory`);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    throw new Error(`Failed to parse ${CONFIG_FILE}: invalid JSON`);
+  }
+
+  validate(config);
+  return config;
+}
+
+/**
+ * Validate config structure and values.
+ */
+function validate(config) {
+  if (!config.remote) {
+    throw new Error("Config error: missing 'remote' section");
+  }
+
+  const { host, user, paths } = config.remote;
+
+  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 (!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 (!Array.isArray(paths) || paths.length === 0) {
+    throw new Error("Config error: 'paths' must be a non-empty array of remote paths");
+  }
+
+  const seen = new Set();
+  for (const p of paths) {
+    if (typeof p !== 'string' || p.trim() === '') {
+      throw new Error(`Config error: each path must be a non-empty string`);
+    }
+    if (p.startsWith('-')) {
+      throw new Error(`Config error: remote path '${p}' must not start with '-'`);
+    }
+    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);
+  }
+}
+
+/**
+ * Extract folder name (last path component) from a remote path.
+ * Strips trailing slashes. Rejects root "/" and empty strings.
+ */
+export function extractFolderName(remotePath) {
+  const trimmed = remotePath.replace(/\/+$/, '');
+  if (trimmed === '' || trimmed === '/') {
+    throw new Error(`Config error: remote path '${remotePath}' resolves to root or is empty`);
+  }
+  const name = basename(trimmed);
+  if (!name) {
+    throw new Error(`Config error: cannot extract folder name from '${remotePath}'`);
+  }
+  return name;
+}

package/lib/progress.js

@@ -0,0 +1,53 @@
+/**
+ * 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
+ */
+export function streamProgress(stdout) {
+  let buffer = '';
+
+  stdout.on('data', (chunk) => {
+    buffer += chunk.toString();
+
+    // Process complete lines
+    const lines = buffer.split('\n');
+    buffer = lines.pop(); // keep incomplete line in buffer
+
+    for (const line of lines) {
+      // Handle \r-delimited progress updates
+      const parts = line.split('\r');
+      const displayLine = parts[parts.length - 1];
+
+      if (!displayLine || displayLine.trim() === '') continue;
+
+      if (/^\s/.test(displayLine)) {
+        // Progress line from --info=progress2
+        process.stdout.write(`\r\x1b[K  \x1b[36m${displayLine.trim()}\x1b[0m`);
+      } else {
+        const trimmed = displayLine.trim();
+        if (trimmed === './' || trimmed === '') continue;
+
+        if (trimmed.startsWith('deleting ')) {
+          // Deletion highlighted in yellow
+          process.stdout.write(`\r\x1b[K  \x1b[33m- ${trimmed.slice(9)}\x1b[0m\n`);
+        } else {
+          // New/updated file in green
+          process.stdout.write(`\r\x1b[K  \x1b[32m+ ${trimmed}\x1b[0m\n`);
+        }
+      }
+    }
+  });
+
+  stdout.on('end', () => {
+    // Process remaining buffer
+    if (buffer.trim()) {
+      const parts = buffer.split('\r');
+      const displayLine = parts[parts.length - 1]?.trim();
+      if (displayLine && displayLine !== './') {
+        process.stdout.write(`\r\x1b[K  \x1b[32m+ ${displayLine}\x1b[0m\n`);
+      }
+    }
+    // Clear progress line
+    process.stdout.write('\r\x1b[K');
+  });
+}

package/lib/summary.js

@@ -0,0 +1,35 @@
+/**
+ * Map rsync exit codes to human-readable messages.
+ */
+export function rsyncExitMessage(code) {
+  const messages = {
+    0: 'success',
+    11: 'disk full or quota exceeded',
+    12: 'rsync protocol error: possible network issue',
+    23: 'partial transfer: some files could not be synced',
+    24: 'vanished source files: some files disappeared during transfer',
+    30: 'timeout waiting for response',
+    35: 'timeout waiting for daemon connection',
+    255: 'SSH connection failed: check your SSH config and connectivity',
+  };
+  return messages[code] || `rsync failed with exit code ${code}`;
+}
+
+/**
+ * Print a summary of sync results.
+ */
+export function printSummary(results) {
+  console.log('\n--- Sync Summary ---');
+
+  for (const r of results) {
+    if (r.success) {
+      console.log(`  \x1b[32m✓\x1b[0m ${r.folderName} — synced successfully`);
+    } else {
+      console.log(`  \x1b[31m✗\x1b[0m ${r.folderName} — ${r.error}`);
+    }
+  }
+
+  const failed = results.filter(r => !r.success).length;
+  const total = results.length;
+  console.log(`\n${total - failed}/${total} folders synced successfully.`);
+}

package/lib/sync.js

@@ -0,0 +1,127 @@
+import { spawn, execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { extractFolderName } from './config.js';
+import { streamProgress } from './progress.js';
+import { rsyncExitMessage } from './summary.js';
+
+/**
+ * Check that rsync is available in PATH.
+ */
+export async function checkRsync() {
+  return new Promise((resolve) => {
+    execFile('rsync', ['--version'], (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+/**
+ * Build rsync arguments for a single path sync.
+ */
+export function buildRsyncArgs(user, host, remotePath, localPath, direction) {
+  const remote = `${user}@${host}:${remotePath.replace(/\/+$/, '')}/`;
+  const local = `${localPath.replace(/\/+$/, '')}/`;
+
+  const args = [
+    '-avz',
+    '--delete',
+    '--no-owner',
+    '--no-group',
+    '--info=progress2',
+    '--filter=:- .gitignore',
+    '-e', 'ssh',
+    '--', // terminate option parsing to prevent injection
+  ];
+
+  if (direction === 'pull') {
+    args.push(remote, local);
+  } else {
+    args.push(local, remote);
+  }
+
+  return args;
+}
+
+/**
+ * Execute sync for all configured remote paths.
+ */
+export async function syncAll(config, direction) {
+  const results = [];
+  const { host, user, paths } = config.remote;
+
+  for (const remotePath of paths) {
+    let folderName;
+    try {
+      folderName = extractFolderName(remotePath);
+    } catch (err) {
+      results.push({ folderName: remotePath, remotePath, success: false, error: err.message });
+      continue;
+    }
+
+    // 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`);
+      results.push({
+        folderName,
+        remotePath,
+        success: false,
+        error: `local folder '${folderName}' does not exist`,
+      });
+      continue;
+    }
+
+    const label = direction === 'pull' ? 'Pulling' : 'Pushing';
+    console.log(`\n\x1b[1m${label} ${folderName}\x1b[0m (${remotePath})`);
+
+    const args = buildRsyncArgs(user, host, remotePath, folderName, direction);
+    const result = await runRsync(args, folderName, remotePath);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * Run a single rsync command and return the result.
+ */
+function runRsync(args, folderName, remotePath) {
+  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);
+
+    // Capture stderr
+    let stderr = '';
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('error', (err) => {
+      resolve({
+        folderName,
+        remotePath,
+        success: false,
+        error: err.message,
+      });
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ folderName, remotePath, success: true, error: null });
+      } else {
+        const exitCode = code ?? -1;
+        const message = rsyncExitMessage(exitCode);
+        resolve({
+          folderName,
+          remotePath,
+          success: false,
+          error: `${message}${stderr.trim() ? ` (${stderr.trim()})` : ''}`,
+          exitCode,
+        });
+      }
+    });
+  });
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "island-bridge",
+  "version": "1.0.0",
+  "description": "Sync remote server folders to local directory via rsync over SSH",
+  "type": "module",
+  "bin": {
+    "island-bridge": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "scripts": {
+    "test": "node --test test/config.test.js"
+  },
+  "keywords": [
+    "rsync",
+    "sync",
+    "ssh",
+    "cli",
+    "remote",
+    "deploy",
+    "devtools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gong1414/island-bridge.git"
+  },
+  "author": "gong1414",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}