@surmrf/icloud-surge-sync 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 iCloud-Surge-Sync contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# iCloud Surge Sync
+
+One-way distribution for Surge configuration files. A primary device watches an iCloud-backed folder and publishes
+changes to Git. Other devices periodically pull the Git repository as read-only subscribers.
+
+```text
+iCloud folder -> primary push device -> Git remote -> pull devices
+```
+
+The project uses the Git credentials already configured on each machine. It does not read or store access tokens.
+
+## Install
+
+Node.js 18.17 or newer is required.
+
+```bash
+npm install --global @surmrf/icloud-surge-sync
+```
+
+Until the first npm release, install from a checkout with:
+
+```bash
+npm install --global .
+```
+
+## Configure a device
+
+Interactive setup:
+
+```bash
+icss init --role push
+```
+
+The `push` role is the primary publisher. Configure only one primary device unless you are prepared to resolve Git
+push races manually.
+
+```bash
+icss init --role pull
+```
+
+The `pull` role is a read-only subscriber and does not require an iCloud folder.
+
+Non-interactive examples:
+
+```bash
+icss init \
+  --role push \
+  --icloud-folder "/absolute/path/to/icloud/surge" \
+  --git-folder "/absolute/path/to/local/repository" \
+  --remote "git@github.com:owner/private-config.git"
+
+icss init \
+  --role pull \
+  --git-folder "/absolute/path/to/local/repository" \
+  --remote "git@github.com:owner/private-config.git"
+```
+
+`--remote` is only required when the local Git folder has not already been cloned.
+
+Default configuration locations:
+
+- macOS: `~/Library/Application Support/iCloud-Surge-Sync/config.json`
+- Linux: `~/.config/icloud-surge-sync/config.json`
+
+Use `--config /absolute/path/config.json` to override the location.
+
+## Verify and run
+
+```bash
+icss doctor
+icss run
+```
+
+`doctor` validates the selected role, folders, Git repository, `origin`, and existing Git authentication. SSH keys or
+HTTPS credentials must be configured with Git before installing the background service.
+
+## Background service
+
+macOS uses a per-user LaunchAgent. Linux uses a systemd user service.
+
+```bash
+icss daemon install
+icss status
+icss logs
+icss daemon restart
+icss daemon uninstall
+```
+
+Configuration and logs are retained during normal uninstall. Remove them explicitly with:
+
+```bash
+icss daemon uninstall --purge
+```
+
+On a headless Linux host, user lingering may need to be enabled separately so the service can start without an
+interactive login.
+
+## Development
+
+```bash
+pnpm install
+pnpm format
+pnpm check
+pnpm test
+pnpm verify
+```
+
+Biome is the single formatter and linter for JavaScript and JSON. Use `pnpm check:fix` to apply formatting, import
+organization, and safe lint fixes together.
+
+For backwards-compatible source execution, `pnpm push` and `pnpm pull` can use a project-root `config.json` based on
+`config.json.example`.

package/bin/cli.js

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const readline = require('node:readline/promises');
+const simpleGit = require('simple-git');
+const { stdin, stdout } = require('node:process');
+const packageJson = require('../package.json');
+const { loadConfig, resolveConfigPath, saveConfig } = require('../src/config');
+const { daemonStatus, followLogs, installDaemon, restartDaemon, uninstallDaemon } = require('../src/daemon');
+const { runPull } = require('../src/pull');
+const { runPush } = require('../src/push');
+const {
+  isInside,
+  validateForPull,
+  validateForPush,
+  validateGitFolder,
+  validateIcloudFolder,
+} = require('../src/utils/config-validator');
+
+const BOOLEAN_FLAGS = new Set(['force', 'purge', 'help', 'version']);
+
+function camelCase(value) {
+  return value.replace(/-([a-z])/g, (_, character) => character.toUpperCase());
+}
+
+function parseArguments(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+
+    const [rawName, inlineValue] = token.slice(2).split(/=(.*)/s, 2);
+    const name = camelCase(rawName);
+    if (inlineValue !== undefined) {
+      flags[name] = inlineValue;
+    } else if (BOOLEAN_FLAGS.has(name)) {
+      flags[name] = true;
+    } else {
+      index += 1;
+      if (index >= argv.length) {
+        throw new Error(`Missing value for --${rawName}`);
+      }
+      flags[name] = argv[index];
+    }
+  }
+  return { flags, positionals };
+}
+
+function printHelp() {
+  console.log(`iCloud Surge Sync ${packageJson.version}
+
+Usage:
+  icss init --role <push|pull> [options]
+  icss run [push|pull] [--config <path>]
+  icss doctor [--config <path>]
+  icss status [--config <path>]
+  icss logs [--config <path>]
+  icss daemon <install|uninstall|restart|status> [options]
+
+Init options:
+  --role <push|pull>          Device role; push is the primary publisher
+  --icloud-folder <path>     Source folder, required for push
+  --git-folder <path>        Local Git working tree
+  --remote <url>             Clone URL when git-folder is not a repository
+  --branch <name>            Branch name, defaults to the repository default
+  --poll-interval <ms>       Pull interval, defaults to 10000
+  --config <path>            Override the platform config path
+  --force                    Replace an existing configuration
+
+Daemon options:
+  --purge                    With uninstall, also remove config and logs
+`);
+}
+
+async function ask(question, defaultValue) {
+  const interface_ = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const suffix = defaultValue ? ` [${defaultValue}]` : '';
+    const answer = (await interface_.question(`${question}${suffix}: `)).trim();
+    return answer || defaultValue;
+  } finally {
+    interface_.close();
+  }
+}
+
+async function valueOrPrompt(value, question, defaultValue) {
+  if (value) {
+    return value;
+  }
+  if (!stdin.isTTY) {
+    return defaultValue;
+  }
+  return ask(question, defaultValue);
+}
+
+async function isGitRepository(folder) {
+  if (!fs.existsSync(folder)) {
+    return false;
+  }
+  try {
+    return await simpleGit(folder).checkIsRepo();
+  } catch {
+    return false;
+  }
+}
+
+async function prepareGitFolder(gitFolder, remote, branch) {
+  if (await isGitRepository(gitFolder)) {
+    const git = simpleGit(gitFolder);
+    const remotes = await git.getRemotes();
+    if (remote && !remotes.some((item) => item.name === 'origin')) {
+      await git.addRemote('origin', remote);
+    }
+    return;
+  }
+
+  if (!remote) {
+    throw new Error('gitFolder is not a Git repository; provide --remote so it can be cloned');
+  }
+  if (fs.existsSync(gitFolder) && fs.readdirSync(gitFolder).length > 0) {
+    throw new Error(`Cannot clone into a non-empty directory: ${gitFolder}`);
+  }
+  fs.mkdirSync(path.dirname(gitFolder), { recursive: true });
+  const cloneOptions = branch ? ['--branch', branch] : [];
+  await simpleGit().clone(remote, gitFolder, cloneOptions);
+}
+
+async function initialize(flags) {
+  const configPath = resolveConfigPath(flags.config);
+  if (fs.existsSync(configPath) && !flags.force) {
+    const replacement = stdin.isTTY && (await ask(`Configuration exists at ${configPath}. Replace it?`, 'no'));
+    if (replacement?.toLowerCase() !== 'yes') {
+      throw new Error('Configuration was not changed; use --force to replace it');
+    }
+  }
+
+  const role = (await valueOrPrompt(flags.role, 'Device role (push or pull)', 'push')).toLowerCase();
+  if (!['push', 'pull'].includes(role)) {
+    throw new Error('Role must be "push" or "pull"');
+  }
+
+  const gitFolderInput = await valueOrPrompt(flags.gitFolder, 'Local Git folder');
+  if (!gitFolderInput) {
+    throw new Error('gitFolder is required');
+  }
+  const gitFolder = path.resolve(gitFolderInput.replace(/^~(?=$|[/\\])/, os.homedir()));
+  let icloudFolder;
+  if (role === 'push') {
+    const sourceInput = await valueOrPrompt(flags.icloudFolder, 'iCloud source folder');
+    if (!sourceInput) {
+      throw new Error('icloudFolder is required for the primary push device');
+    }
+    icloudFolder = path.resolve(sourceInput.replace(/^~(?=$|[/\\])/, os.homedir()));
+    validateIcloudFolder(icloudFolder);
+  }
+
+  if (role === 'push' && (isInside(icloudFolder, gitFolder) || isInside(gitFolder, icloudFolder))) {
+    throw new Error('icloudFolder and gitFolder must not be the same directory or nested inside each other');
+  }
+
+  let remote = flags.remote;
+  if (!(await isGitRepository(gitFolder))) {
+    remote = await valueOrPrompt(remote, 'Git remote URL');
+  }
+  await prepareGitFolder(gitFolder, remote, flags.branch);
+  validateGitFolder(gitFolder);
+
+  const config = {
+    role,
+    ...(role === 'push' ? { icloudFolder } : {}),
+    gitFolder,
+    ...(role === 'pull' ? { pollInterval: Number(flags.pollInterval || 10000) } : {}),
+  };
+  if (role === 'pull' && (!Number.isFinite(config.pollInterval) || config.pollInterval < 1000)) {
+    throw new Error('pollInterval must be a number of at least 1000 milliseconds');
+  }
+
+  const savedPath = saveConfig(config, configPath);
+  console.log(`Configured this device as ${role === 'push' ? 'the primary push device' : 'a pull device'}.`);
+  console.log(`Configuration: ${savedPath}`);
+  console.log('Next: icss doctor && icss daemon install');
+}
+
+function getConfiguredRole(configPath, requestedRole) {
+  const { config } = loadConfig(configPath);
+  const role = requestedRole || config.role;
+  if (!['push', 'pull'].includes(role)) {
+    throw new Error('No valid device role is configured; run icss init --role push|pull');
+  }
+  if (requestedRole && config.role && requestedRole !== config.role) {
+    throw new Error(`This device is configured as "${config.role}", not "${requestedRole}"`);
+  }
+  return role;
+}
+
+async function runConfigured(configPath, requestedRole) {
+  const role = getConfiguredRole(configPath, requestedRole);
+  if (role === 'push') {
+    await runPush({ configPath });
+  } else {
+    await runPull({ configPath });
+  }
+}
+
+async function doctor(configPath) {
+  const role = getConfiguredRole(configPath);
+  const config = role === 'push' ? validateForPush(configPath) : validateForPull(configPath);
+  const git = simpleGit({ baseDir: config.gitFolder, timeout: { block: 60 * 1000 } }).env({
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+  });
+  const remotes = await git.getRemotes(true);
+  const origin = remotes.find((remote) => remote.name === 'origin');
+  if (!origin) {
+    throw new Error('Git remote "origin" is not configured');
+  }
+  await git.listRemote(['--heads', 'origin']);
+
+  console.log(`✓ configuration: ${config.configPath}`);
+  console.log(`✓ role: ${role}${role === 'push' ? ' (primary device)' : ''}`);
+  if (role === 'push') {
+    console.log('✓ iCloud folder is readable');
+  }
+  console.log('✓ Git folder is writable');
+  console.log('✓ origin is configured and reachable with existing Git credentials');
+}
+
+function validatedConfig(configPath) {
+  const role = getConfiguredRole(configPath);
+  return role === 'push' ? validateForPush(configPath) : validateForPull(configPath);
+}
+
+async function daemonCommand(action, flags) {
+  const configPath = resolveConfigPath(flags.config);
+  if (action === 'uninstall') {
+    uninstallDaemon({ configPath, purge: Boolean(flags.purge) });
+    console.log(`Daemon uninstalled${flags.purge ? '; configuration and logs removed' : ''}.`);
+    return;
+  }
+
+  if (action === 'status') {
+    const status = daemonStatus({ configPath });
+    console.log(`installed: ${status.installed ? 'yes' : 'no'}`);
+    console.log(`running: ${status.running ? 'yes' : 'no'}`);
+    return;
+  }
+
+  if (action === 'restart') {
+    restartDaemon({ configPath });
+    console.log('Daemon restarted.');
+    return;
+  }
+
+  if (action === 'install') {
+    await doctor(configPath);
+    const config = validatedConfig(configPath);
+    const paths = installDaemon({ config, configPath: config.configPath });
+    console.log(`Daemon installed for role: ${config.role}`);
+    console.log(`Service file: ${paths.servicePath}`);
+    if (process.platform === 'linux') {
+      console.log('For a headless machine, enable user lingering separately if the service must run before login.');
+    }
+    return;
+  }
+
+  throw new Error('Daemon action must be install, uninstall, restart, or status');
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const { flags, positionals } = parseArguments(argv);
+  const [command, subcommand] = positionals;
+  if (command === 'version' || flags.version) {
+    console.log(packageJson.version);
+    return;
+  }
+  if (!command || command === 'help' || flags.help) {
+    printHelp();
+    return;
+  }
+  if (command === 'init') {
+    await initialize(flags);
+    return;
+  }
+  if (command === 'run') {
+    await runConfigured(flags.config, subcommand);
+    return;
+  }
+  if (command === 'doctor') {
+    await doctor(flags.config);
+    return;
+  }
+  if (command === 'daemon') {
+    await daemonCommand(subcommand, flags);
+    return;
+  }
+  if (command === 'status') {
+    await daemonCommand('status', flags);
+    return;
+  }
+  if (command === 'logs') {
+    await followLogs({ configPath: resolveConfigPath(flags.config) });
+    return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { main, parseArguments };

package/config.json.example

@@ -0,0 +1,5 @@
+{
+  "role": "push",
+  "icloudFolder": "/Users/username/Library/Mobile Documents/com~apple~CloudDocs/MyFiles",
+  "gitFolder": "/Users/username/Workspaces/my-sync-repo"
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@surmrf/icloud-surge-sync",
+  "version": "1.0.0",
+  "description": "One-way Surge configuration distribution from iCloud through Git.",
+  "bin": {
+    "icloud-surge-sync": "bin/cli.js",
+    "icss": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "config.json.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "push": "node bin/cli.js run push",
+    "pull": "node bin/cli.js run pull",
+    "test": "node --test",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "verify": "biome ci . && node --test",
+    "prepublishOnly": "npm run verify"
+  },
+  "keywords": [
+    "icloud",
+    "surge",
+    "git",
+    "sync",
+    "backup"
+  ],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anyforker/iCloud-Surge-Sync.git"
+  },
+  "homepage": "https://github.com/anyforker/iCloud-Surge-Sync#readme",
+  "bugs": {
+    "url": "https://github.com/anyforker/iCloud-Surge-Sync/issues"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@10.8.0",
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "fs-extra": "^11.3.0",
+    "simple-git": "^3.36.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.6"
+  }
+}

package/src/config.js

@@ -0,0 +1,111 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const APP_DIRECTORY = 'iCloud-Surge-Sync';
+const CONFIG_ENV = 'ICLOUD_SURGE_SYNC_CONFIG';
+
+function expandHome(value, homeDirectory = os.homedir()) {
+  if (value === '~') {
+    return homeDirectory;
+  }
+  if (value.startsWith(`~${path.sep}`) || value.startsWith('~/')) {
+    return path.join(homeDirectory, value.slice(2));
+  }
+  return value;
+}
+
+function getDefaultConfigPath(options = {}) {
+  const platform = options.platform || process.platform;
+  const environment = options.environment || process.env;
+  const homeDirectory = options.homeDirectory || os.homedir();
+
+  if (platform === 'darwin') {
+    return path.join(homeDirectory, 'Library', 'Application Support', APP_DIRECTORY, 'config.json');
+  }
+  if (platform === 'win32') {
+    const appData = environment.APPDATA || path.join(homeDirectory, 'AppData', 'Roaming');
+    return path.join(appData, APP_DIRECTORY, 'config.json');
+  }
+
+  const configHome = environment.XDG_CONFIG_HOME || path.join(homeDirectory, '.config');
+  return path.join(configHome, 'icloud-surge-sync', 'config.json');
+}
+
+function resolveConfigPath(explicitPath, options = {}) {
+  const environment = options.environment || process.env;
+  const selected = explicitPath || environment[CONFIG_ENV] || getDefaultConfigPath(options);
+  return path.resolve(expandHome(selected, options.homeDirectory));
+}
+
+function findConfigPath(explicitPath, options = {}) {
+  const resolved = resolveConfigPath(explicitPath, options);
+  if (explicitPath || (options.environment || process.env)[CONFIG_ENV] || fs.existsSync(resolved)) {
+    return resolved;
+  }
+
+  // Keep direct execution from a source checkout backwards-compatible.
+  const legacyPath = path.resolve(__dirname, '../config.json');
+  return fs.existsSync(legacyPath) ? legacyPath : resolved;
+}
+
+function normalizeConfig(config) {
+  const normalized = { ...config };
+  if (typeof normalized.icloudFolder === 'string') {
+    normalized.icloudFolder = path.resolve(expandHome(normalized.icloudFolder));
+  }
+  if (typeof normalized.gitFolder === 'string') {
+    normalized.gitFolder = path.resolve(expandHome(normalized.gitFolder));
+  }
+  return normalized;
+}
+
+function loadConfig(explicitPath, options = {}) {
+  const configPath = findConfigPath(explicitPath, options);
+  if (!fs.existsSync(configPath)) {
+    const error = new Error(`Configuration file not found: ${configPath}`);
+    error.code = 'CONFIG_NOT_FOUND';
+    throw error;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    error.message = `Failed to parse configuration ${configPath}: ${error.message}`;
+    error.code = 'CONFIG_INVALID_JSON';
+    throw error;
+  }
+
+  return { config: normalizeConfig(parsed), configPath };
+}
+
+function saveConfig(config, explicitPath, options = {}) {
+  const configPath = resolveConfigPath(explicitPath, options);
+  fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  const temporaryPath = `${configPath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(normalizeConfig(config), null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporaryPath, configPath);
+  try {
+    fs.chmodSync(configPath, 0o600);
+  } catch {
+    // Windows does not implement POSIX file modes.
+  }
+  return configPath;
+}
+
+function getRuntimeDirectory(configPath) {
+  return path.dirname(configPath);
+}
+
+module.exports = {
+  CONFIG_ENV,
+  expandHome,
+  findConfigPath,
+  getDefaultConfigPath,
+  getRuntimeDirectory,
+  loadConfig,
+  normalizeConfig,
+  resolveConfigPath,
+  saveConfig,
+};

package/src/daemon.js

@@ -0,0 +1,225 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync, spawn } = require('node:child_process');
+const { getRuntimeDirectory } = require('./config');
+
+const SERVICE_LABEL = 'io.github.anyforker.icloud-surge-sync';
+const SYSTEMD_SERVICE = 'icloud-surge-sync.service';
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function quoteSystemd(value) {
+  const escaped = String(value)
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('$', '$$')
+    .replaceAll('%', '%%');
+  return `"${escaped}"`;
+}
+
+function getExecutableArguments(configPath) {
+  const cliPath = path.resolve(__dirname, '../bin/cli.js');
+  return [process.execPath, cliPath, 'run', '--config', configPath];
+}
+
+function buildLaunchAgent({ configPath, gitFolder, logPath, environmentPath = process.env.PATH }) {
+  const argumentsXml = getExecutableArguments(configPath)
+    .map((argument) => `      <string>${escapeXml(argument)}</string>`)
+    .join('\n');
+  const pathValue = environmentPath || '/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${SERVICE_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argumentsXml}
+    </array>
+    <key>WorkingDirectory</key>
+    <string>${escapeXml(gitFolder)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>PATH</key>
+      <string>${escapeXml(pathValue)}</string>
+      <key>GIT_TERMINAL_PROMPT</key>
+      <string>0</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>StandardOutPath</key>
+    <string>${escapeXml(logPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${escapeXml(logPath)}</string>
+  </dict>
+</plist>
+`;
+}
+
+function buildSystemdUnit({ configPath, gitFolder }) {
+  const command = getExecutableArguments(configPath).map(quoteSystemd).join(' ');
+  return `[Unit]
+Description=iCloud Surge Sync
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${command}
+WorkingDirectory=${quoteSystemd(gitFolder)}
+Environment=GIT_TERMINAL_PROMPT=0
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function run(command, arguments_, options = {}) {
+  const result = spawnSync(command, arguments_, {
+    encoding: 'utf8',
+    stdio: options.inherit ? 'inherit' : 'pipe',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0 && !options.allowFailure) {
+    const details = (result.stderr || result.stdout || '').trim();
+    throw new Error(`${command} failed${details ? `: ${details}` : ''}`);
+  }
+  return result;
+}
+
+function getDaemonPaths(configPath, platform = process.platform) {
+  const runtimeDirectory = getRuntimeDirectory(configPath);
+  const logDirectory = path.join(runtimeDirectory, 'logs');
+  if (platform === 'darwin') {
+    return {
+      servicePath: path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`),
+      logDirectory,
+      logPath: path.join(logDirectory, 'daemon.log'),
+    };
+  }
+  if (platform === 'linux') {
+    const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+    return {
+      servicePath: path.join(configHome, 'systemd', 'user', SYSTEMD_SERVICE),
+      logDirectory,
+      logPath: null,
+    };
+  }
+  throw new Error(`Daemon management is not supported on ${platform}`);
+}
+
+function installDaemon({ config, configPath, platform = process.platform }) {
+  const paths = getDaemonPaths(configPath, platform);
+  fs.mkdirSync(path.dirname(paths.servicePath), { recursive: true });
+  fs.mkdirSync(paths.logDirectory, { recursive: true, mode: 0o700 });
+
+  if (platform === 'darwin') {
+    const domain = `gui/${process.getuid()}`;
+    run('launchctl', ['bootout', `${domain}/${SERVICE_LABEL}`], { allowFailure: true });
+    fs.writeFileSync(
+      paths.servicePath,
+      buildLaunchAgent({
+        configPath,
+        gitFolder: config.gitFolder,
+        logPath: paths.logPath,
+      }),
+      { mode: 0o600 },
+    );
+    run('launchctl', ['bootstrap', domain, paths.servicePath]);
+    return paths;
+  }
+
+  fs.writeFileSync(paths.servicePath, buildSystemdUnit({ configPath, gitFolder: config.gitFolder }), { mode: 0o644 });
+  run('systemctl', ['--user', 'daemon-reload']);
+  run('systemctl', ['--user', 'enable', '--now', SYSTEMD_SERVICE]);
+  return paths;
+}
+
+function uninstallDaemon({ configPath, platform = process.platform, purge = false }) {
+  const paths = getDaemonPaths(configPath, platform);
+  if (platform === 'darwin') {
+    const domain = `gui/${process.getuid()}`;
+    run('launchctl', ['bootout', `${domain}/${SERVICE_LABEL}`], { allowFailure: true });
+  } else {
+    run('systemctl', ['--user', 'disable', '--now', SYSTEMD_SERVICE], { allowFailure: true });
+  }
+
+  fs.rmSync(paths.servicePath, { force: true });
+  if (platform === 'linux') {
+    run('systemctl', ['--user', 'daemon-reload'], { allowFailure: true });
+  }
+  if (purge) {
+    fs.rmSync(configPath, { force: true });
+    fs.rmSync(paths.logDirectory, { recursive: true, force: true });
+  }
+  return paths;
+}
+
+function daemonStatus({ configPath, platform = process.platform }) {
+  const paths = getDaemonPaths(configPath, platform);
+  if (!fs.existsSync(paths.servicePath)) {
+    return { installed: false, running: false, details: 'Service file is not installed.' };
+  }
+
+  if (platform === 'darwin') {
+    const target = `gui/${process.getuid()}/${SERVICE_LABEL}`;
+    const result = run('launchctl', ['print', target], { allowFailure: true });
+    return { installed: true, running: result.status === 0, details: (result.stdout || result.stderr).trim(), paths };
+  }
+
+  const result = run('systemctl', ['--user', 'is-active', SYSTEMD_SERVICE], { allowFailure: true });
+  return { installed: true, running: result.stdout.trim() === 'active', details: result.stdout.trim(), paths };
+}
+
+function restartDaemon({ platform = process.platform }) {
+  if (platform === 'darwin') {
+    run('launchctl', ['kickstart', '-k', `gui/${process.getuid()}/${SERVICE_LABEL}`]);
+  } else if (platform === 'linux') {
+    run('systemctl', ['--user', 'restart', SYSTEMD_SERVICE]);
+  } else {
+    throw new Error(`Daemon management is not supported on ${platform}`);
+  }
+}
+
+function followLogs({ configPath, platform = process.platform }) {
+  const paths = getDaemonPaths(configPath, platform);
+  const command = platform === 'darwin' ? 'tail' : 'journalctl';
+  const arguments_ =
+    platform === 'darwin' ? ['-n', '100', '-f', paths.logPath] : ['--user', '-u', SYSTEMD_SERVICE, '-n', '100', '-f'];
+  const child = spawn(command, arguments_, { stdio: 'inherit' });
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code) => resolve(code || 0));
+  });
+}
+
+module.exports = {
+  SERVICE_LABEL,
+  SYSTEMD_SERVICE,
+  buildLaunchAgent,
+  buildSystemdUnit,
+  daemonStatus,
+  followLogs,
+  getDaemonPaths,
+  installDaemon,
+  restartDaemon,
+  uninstallDaemon,
+};

package/src/pull.js

@@ -0,0 +1,75 @@
+const simpleGit = require('simple-git');
+const logger = require('./utils/logger');
+const { validateForPull } = require('./utils/config-validator');
+
+function createGit(gitFolder) {
+  return simpleGit({
+    baseDir: gitFolder,
+    maxConcurrentProcesses: 1,
+    timeout: { block: 60 * 1000 },
+  }).env({
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+  });
+}
+
+async function runPull(options = {}) {
+  const config = options.config || validateForPull(options.configPath);
+  const git = createGit(config.gitFolder);
+  const pollInterval = options.pollInterval || config.pollInterval || 10 * 1000;
+  let pollTimer = null;
+  let stopped = false;
+
+  const checkAndPull = async () => {
+    try {
+      logger.log('Checking for updates...');
+      await git.fetch();
+      const status = await git.status();
+      if (status.behind > 0) {
+        logger.log(`Repo is behind by ${status.behind} commits. Pulling...`);
+        await git.pull();
+        logger.log('Pull done.');
+      } else {
+        logger.log('Up to date. No action needed.');
+      }
+    } catch (error) {
+      logger.error('Fetch/pull failed:', error.message);
+      logger.log('Will retry in the next check cycle...');
+    }
+  };
+
+  const poll = async () => {
+    await checkAndPull();
+    if (!stopped) {
+      pollTimer = setTimeout(poll, pollInterval);
+    }
+  };
+
+  const stop = () => {
+    stopped = true;
+    clearTimeout(pollTimer);
+    logger.log('Pull service stopped.');
+  };
+
+  if (options.handleSignals !== false) {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.once(signal, () => {
+        stop();
+        process.exit(0);
+      });
+    }
+  }
+
+  logger.log(`Pull device is tracking: ${config.gitFolder}`);
+  poll();
+  return { stop, checkAndPull };
+}
+
+if (require.main === module) {
+  runPull().catch((error) => {
+    logger.error(error.message);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { runPull };

package/src/push.js

@@ -0,0 +1,152 @@
+const chokidar = require('chokidar');
+const fs = require('fs-extra');
+const path = require('node:path');
+const simpleGit = require('simple-git');
+const logger = require('./utils/logger');
+const { validateForPush } = require('./utils/config-validator');
+
+function createGit(gitFolder) {
+  return simpleGit({
+    baseDir: gitFolder,
+    maxConcurrentProcesses: 1,
+    timeout: { block: 60 * 1000 },
+  }).env({
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+  });
+}
+
+async function runPush(options = {}) {
+  const config = options.config || validateForPush(options.configPath);
+  const icloudFolder = config.icloudFolder;
+  const gitFolder = config.gitFolder;
+  const git = createGit(gitFolder);
+
+  const copyChangedFile = async (filePath) => {
+    const relative = path.relative(icloudFolder, filePath);
+    const destination = path.join(gitFolder, relative);
+    try {
+      await fs.ensureDir(path.dirname(destination));
+      await fs.copy(filePath, destination);
+      logger.log(`Copied: ${relative}`);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        logger.error(`Source file not found: ${relative}`);
+      } else if (error.code === 'EACCES') {
+        logger.error(`Permission denied when copying: ${relative}`);
+      } else if (error.code === 'ENOSPC') {
+        logger.error(`No space left on device when copying: ${relative}`);
+      } else {
+        logger.error(`Copy failed: ${relative}`, error.message);
+      }
+    }
+  };
+
+  const removeDeletedFile = async (filePath) => {
+    const relative = path.relative(icloudFolder, filePath);
+    const destination = path.join(gitFolder, relative);
+    try {
+      await fs.remove(destination);
+      logger.log(`Deleted: ${relative}`);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        logger.log(`File already deleted: ${relative}`);
+      } else if (error.code === 'EACCES') {
+        logger.error(`Permission denied when deleting: ${relative}`);
+      } else {
+        logger.error(`Delete failed: ${relative}`, error.message);
+      }
+    }
+  };
+
+  let pushTimer = null;
+  let pushInProgress = false;
+  let pushPending = false;
+
+  const scheduleCommitAndPush = () => {
+    pushPending = true;
+    clearTimeout(pushTimer);
+    pushTimer = setTimeout(commitAndPush, options.debounceMs || 5000);
+  };
+
+  const commitAndPush = async () => {
+    if (pushInProgress) {
+      return;
+    }
+
+    pushInProgress = true;
+    pushPending = false;
+
+    try {
+      await git.add('.');
+      const status = await git.status();
+      if (status.staged.length === 0) {
+        logger.log('No changes to commit');
+        return;
+      }
+
+      logger.log(`Committing ${status.staged.length} file(s)...`);
+      await git.commit(`Auto-sync: ${new Date().toISOString()}`);
+      logger.log('Pushing to remote...');
+      await git.push();
+      logger.log('Git push done.');
+    } catch (error) {
+      logger.error('Git operation failed:', error.message);
+    } finally {
+      pushInProgress = false;
+      if (pushPending) {
+        scheduleCommitAndPush();
+      }
+    }
+  };
+
+  const watcher = chokidar.watch(icloudFolder, {
+    ignored: /(^|[/\\])\../,
+    persistent: true,
+    ignoreInitial: false,
+  });
+
+  watcher
+    .on('add', async (filePath) => {
+      await copyChangedFile(filePath);
+      scheduleCommitAndPush();
+    })
+    .on('change', async (filePath) => {
+      await copyChangedFile(filePath);
+      scheduleCommitAndPush();
+    })
+    .on('unlink', async (filePath) => {
+      await removeDeletedFile(filePath);
+      scheduleCommitAndPush();
+    })
+    .on('error', (error) => {
+      logger.error('Watcher error:', error.message);
+    });
+
+  const stop = async () => {
+    clearTimeout(pushTimer);
+    await watcher.close();
+    logger.log('Push service stopped.');
+  };
+
+  if (options.handleSignals !== false) {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      process.once(signal, async () => {
+        await stop();
+        process.exit(0);
+      });
+    }
+  }
+
+  logger.log(`Primary push device is watching: ${icloudFolder}`);
+  return { watcher, stop, commitAndPush };
+}
+
+if (require.main === module) {
+  runPush().catch((error) => {
+    logger.error(error.message);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { runPush };

package/src/utils/config-validator.js

@@ -0,0 +1,89 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadConfig } = require('../config');
+const logger = require('./logger');
+
+class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+function isInside(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function assertDirectory(folder, fieldName) {
+  if (!folder) {
+    throw new ConfigError(`${fieldName} is not configured`);
+  }
+  if (!path.isAbsolute(folder)) {
+    throw new ConfigError(`${fieldName} must be an absolute path: ${folder}`);
+  }
+  if (!fs.existsSync(folder)) {
+    throw new ConfigError(`${fieldName} does not exist: ${folder}`);
+  }
+  if (!fs.statSync(folder).isDirectory()) {
+    throw new ConfigError(`${fieldName} is not a directory: ${folder}`);
+  }
+}
+
+function validateGitFolder(gitFolder) {
+  assertDirectory(gitFolder, 'gitFolder');
+  const gitMarker = path.join(gitFolder, '.git');
+  if (!fs.existsSync(gitMarker)) {
+    throw new ConfigError(`gitFolder is not a Git repository: ${gitFolder}`);
+  }
+  fs.accessSync(gitFolder, fs.constants.R_OK | fs.constants.W_OK);
+  logger.log(`Git folder validated: ${gitFolder}`);
+}
+
+function validateIcloudFolder(icloudFolder) {
+  assertDirectory(icloudFolder, 'icloudFolder');
+  fs.accessSync(icloudFolder, fs.constants.R_OK);
+  logger.log(`iCloud folder validated: ${icloudFolder}`);
+}
+
+function validateRole(config, expectedRole) {
+  if (config.role && config.role !== expectedRole) {
+    throw new ConfigError(`This device is configured as "${config.role}", not "${expectedRole}"`);
+  }
+}
+
+function readAndValidate(configPath, expectedRole) {
+  const loaded = loadConfig(configPath);
+  validateRole(loaded.config, expectedRole);
+  validateGitFolder(loaded.config.gitFolder);
+
+  if (expectedRole === 'push') {
+    validateIcloudFolder(loaded.config.icloudFolder);
+    const source = path.resolve(loaded.config.icloudFolder);
+    const target = path.resolve(loaded.config.gitFolder);
+    if (isInside(source, target) || isInside(target, source)) {
+      throw new ConfigError('icloudFolder and gitFolder must not be the same directory or nested inside each other');
+    }
+  }
+
+  return { ...loaded.config, role: expectedRole, configPath: loaded.configPath };
+}
+
+function validateForPull(configPath) {
+  logger.log('Validating pull device configuration...');
+  return readAndValidate(configPath, 'pull');
+}
+
+function validateForPush(configPath) {
+  logger.log('Validating primary push device configuration...');
+  return readAndValidate(configPath, 'push');
+}
+
+module.exports = {
+  ConfigError,
+  isInside,
+  validateForPull,
+  validateForPush,
+  validateGitFolder,
+  validateIcloudFolder,
+};

package/src/utils/logger.js

@@ -0,0 +1,32 @@
+const APP_NAME = 'iCloud-Surge-Sync';
+
+function pad(value, length = 2) {
+  return String(value).padStart(length, '0');
+}
+
+function formatTimestamp(date = new Date()) {
+  return `${[date.getFullYear(), pad(date.getMonth() + 1), pad(date.getDate())].join(
+    '-',
+  )} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+}
+
+function write(level, message, ...args) {
+  const line = `${formatTimestamp()} | ${level} | ${APP_NAME} | ${message}`;
+  if (level === 'ERROR') {
+    console.error(line, ...args);
+  } else {
+    console.log(line, ...args);
+  }
+}
+
+const logger = {
+  log: (message, ...args) => write('INFO', message, ...args),
+  info: (message, ...args) => write('INFO', message, ...args),
+  warn: (message, ...args) => write('WARN', message, ...args),
+  error: (message, ...args) => write('ERROR', message, ...args),
+  success: (message, ...args) => write('SUCCESS', message, ...args),
+  start: (message, ...args) => write('START', message, ...args),
+  stop: (message, ...args) => write('STOP', message, ...args),
+};
+
+module.exports = logger;