@empirical-gauzza/cli 1.0.9

package/lib/scheduledSync.js

@@ -0,0 +1,331 @@
+'use strict';
+
+// US-012: OS-native scheduled-task management for the autosync delivery "floor" — no custom
+// background daemon, just a per-OS scheduler entry that periodically shells out to
+// `node <cli-entry> kit sync --quiet`. See kitCommands.js (runKitUse/runKitAutosync) for the
+// reconciliation call sites, and deviceConfig.js's `scheduledSyncKitId` field for how we track
+// which Kit "owns" the currently-registered local schedule.
+//
+// Every OS-command-execution call in this file funnels through `execCommand()` below, which is
+// deliberately exported so callers/tests can invoke it directly, and which supports a
+// fully-mocked "fake mode" (see EMPIRICAL_SCHEDULER_FAKE_LOG below) so CLI-level tests that
+// spawn the real `empirical` binary as a subprocess can assert on exactly what this module
+// *would* have run/written, on any host OS, without ever touching a real OS scheduler.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { commandExists, runResolvedCommand, ensureDir } = require('./fsUtils');
+
+// ─── Config ─────────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_INTERVAL_MIN = 20;
+const MIN_INTERVAL_MIN = 5; // floor: this is a drift-catch-up mechanism, not a tight poll.
+
+const WINDOWS_TASK_NAME = 'EmpiricalKitSync';
+const LAUNCHD_LABEL = 'com.empirical.kitsync';
+const CRON_START_MARKER = '# EMPIRICAL_KIT_SYNC_START';
+const CRON_END_MARKER = '# EMPIRICAL_KIT_SYNC_END';
+
+// Interval is configurable via EMPIRICAL_KIT_SYNC_INTERVAL_MIN (minutes), default 20, floored
+// at 5 so a misconfigured env var can't turn this into a tight poll loop.
+function getSyncIntervalMinutes() {
+  const raw = Number(process.env.EMPIRICAL_KIT_SYNC_INTERVAL_MIN);
+  if (!Number.isFinite(raw) || raw <= 0) return DEFAULT_INTERVAL_MIN;
+  return Math.max(MIN_INTERVAL_MIN, Math.round(raw));
+}
+
+// The scheduled task must invoke `node <absolute-path-to-empirical.js> kit sync --quiet`
+// directly — never rely on `empirical` being on PATH, since a scheduled task's PATH may differ
+// from an interactive shell's.
+function getCliEntryPath() {
+  return path.resolve(__dirname, '../bin/empirical.js');
+}
+
+function getNodePath() {
+  return process.execPath;
+}
+
+// Platform is normally just process.platform, but tests running on one dev machine (this repo
+// is developed on Windows) need to exercise the macOS/Linux branches too — so it's overridable
+// via EMPIRICAL_SCHEDULER_PLATFORM ('win32' | 'darwin' | 'linux').
+function getPlatform() {
+  return process.env.EMPIRICAL_SCHEDULER_PLATFORM || process.platform;
+}
+
+// ─── Command-execution seam (mockable) ─────────────────────────────────────────────────────
+//
+// When EMPIRICAL_SCHEDULER_FAKE_LOG is set (a file path), no real OS command is ever run: each
+// call is appended as a JSON line to that file (command, args, input) and a canned success
+// result is returned instead. `crontab -l`'s "current crontab" reply in fake mode comes from
+// EMPIRICAL_SCHEDULER_FAKE_CRONTAB (empty/unset = "no crontab yet", matching real `crontab -l`
+// exiting non-zero when the user has none).
+function fakeExecCommand(command, args, options) {
+  const logPath = process.env.EMPIRICAL_SCHEDULER_FAKE_LOG;
+  ensureDir(path.dirname(logPath));
+  fs.appendFileSync(
+    logPath,
+    `${JSON.stringify({ command, args, input: options.input ?? null })}\n`,
+    'utf8'
+  );
+
+  if (command === 'crontab' && args[0] === '-l') {
+    const existing = process.env.EMPIRICAL_SCHEDULER_FAKE_CRONTAB || '';
+    return existing
+      ? { status: 0, stdout: existing, stderr: '', error: null }
+      : { status: 1, stdout: '', stderr: 'no crontab for user', error: null };
+  }
+
+  return { status: 0, stdout: '', stderr: '', error: null };
+}
+
+function execCommand(command, args, options = {}) {
+  if (process.env.EMPIRICAL_SCHEDULER_FAKE_LOG) {
+    return fakeExecCommand(command, args, options);
+  }
+  return runResolvedCommand(command, args, { stdio: 'pipe', ...options });
+}
+
+// In fake/test mode the target OS's real command (schtasks/launchctl/crontab) very likely isn't
+// even installed on the machine actually running the test suite (e.g. testing the Linux crontab
+// branch on a Windows dev box) — so the "is this command available" check is skipped entirely
+// when faking, same as every other OS-command execution in this module.
+function commandAvailable(cmd) {
+  if (process.env.EMPIRICAL_SCHEDULER_FAKE_LOG) return true;
+  return commandExists(cmd);
+}
+
+// ─── Pure builders (no I/O — directly unit-testable) ───────────────────────────────────────
+
+function buildSyncCommandString({ nodePath = getNodePath(), cliEntryPath = getCliEntryPath() } = {}) {
+  // A single shell-ready string, used for schtasks' /tr and shown in the launchd plist's
+  // ProgramArguments (split there instead — see buildLaunchdPlistXml).
+  return `"${nodePath}" "${cliEntryPath}" kit sync --quiet`;
+}
+
+function buildWindowsCreateArgs({ intervalMinutes, nodePath = getNodePath(), cliEntryPath = getCliEntryPath(), taskName = WINDOWS_TASK_NAME } = {}) {
+  return [
+    '/create',
+    '/tn', taskName,
+    '/tr', buildSyncCommandString({ nodePath, cliEntryPath }),
+    '/sc', 'minute',
+    '/mo', String(intervalMinutes),
+    '/f' // force-overwrite: makes re-registration idempotent instead of erroring "already exists"
+  ];
+}
+
+function buildWindowsDeleteArgs({ taskName = WINDOWS_TASK_NAME } = {}) {
+  return ['/delete', '/tn', taskName, '/f'];
+}
+
+function getLaunchAgentPlistPath() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function buildLaunchdPlistXml({
+  intervalMinutes,
+  nodePath = getNodePath(),
+  cliEntryPath = getCliEntryPath(),
+  label = LAUNCHD_LABEL
+} = {}) {
+  const intervalSeconds = intervalMinutes * 60;
+  const args = [nodePath, cliEntryPath, 'kit', 'sync', '--quiet']
+    .map((a) => `    <string>${xmlEscape(a)}</string>`)
+    .join('\n');
+
+  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>${xmlEscape(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>StartInterval</key>
+  <integer>${intervalSeconds}</integer>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>
+`;
+}
+
+function buildCronLine({ intervalMinutes, nodePath = getNodePath(), cliEntryPath = getCliEntryPath() } = {}) {
+  return `*/${intervalMinutes} * * * * "${nodePath}" "${cliEntryPath}" kit sync --quiet`;
+}
+
+// Idempotently inserts/replaces the marked EMPIRICAL_KIT_SYNC block inside an existing crontab
+// body. Never touches any other line the user already has.
+function mergeCrontab(existingContent, cronLine) {
+  const block = `${CRON_START_MARKER}\n${cronLine}\n${CRON_END_MARKER}`;
+  const lines = (existingContent || '').split(/\r?\n/);
+  const startIdx = lines.findIndex((l) => l.trim() === CRON_START_MARKER);
+  const endIdx = lines.findIndex((l) => l.trim() === CRON_END_MARKER);
+
+  let nextLines;
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    nextLines = [...lines.slice(0, startIdx), block, ...lines.slice(endIdx + 1)];
+  } else {
+    const trimmed = lines.filter((l, i) => !(i === lines.length - 1 && l === ''));
+    nextLines = trimmed.length ? [...trimmed, block] : [block];
+  }
+
+  return `${nextLines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+
+// Removes the marked block, leaving every other crontab line untouched. No-op (returns the
+// input unchanged) if the block isn't present.
+function removeCronBlock(existingContent) {
+  const lines = (existingContent || '').split(/\r?\n/);
+  const startIdx = lines.findIndex((l) => l.trim() === CRON_START_MARKER);
+  const endIdx = lines.findIndex((l) => l.trim() === CRON_END_MARKER);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    return existingContent || '';
+  }
+  const nextLines = [...lines.slice(0, startIdx), ...lines.slice(endIdx + 1)];
+  const joined = nextLines.join('\n').replace(/\n{3,}/g, '\n\n');
+  return joined.endsWith('\n') || joined === '' ? joined : `${joined}\n`;
+}
+
+// ─── Per-platform register/deregister ──────────────────────────────────────────────────────
+
+function registerWindows(intervalMinutes) {
+  if (!commandAvailable('schtasks')) {
+    throw new Error('schtasks is not available on this machine — cannot register scheduled sync');
+  }
+  const result = execCommand('schtasks', buildWindowsCreateArgs({ intervalMinutes }));
+  if (result.status !== 0) {
+    throw new Error(`schtasks /create failed: ${(result.stderr || result.stdout || '').trim() || 'unknown error'}`);
+  }
+}
+
+function deregisterWindows() {
+  if (!commandAvailable('schtasks')) return; // nothing to clean up if it was never available
+  // /delete on a task that doesn't exist exits non-zero — that's an expected, harmless outcome
+  // of "deregister" being idempotent, so we don't treat it as a failure.
+  execCommand('schtasks', buildWindowsDeleteArgs());
+}
+
+// macOS: `launchctl bootstrap`/`bootout` (the modern gui-domain API) rather than the older
+// `load`/`unload`, which Apple has deprecated since 10.10 in favor of bootstrap/bootout's
+// explicit domain targeting and clearer error semantics.
+function launchdGuiDomain() {
+  const uid = typeof os.userInfo === 'function' ? os.userInfo().uid : process.getuid?.();
+  return `gui/${uid}`;
+}
+
+function registerMacOS(intervalMinutes) {
+  const plistPath = getLaunchAgentPlistPath();
+  const xml = buildLaunchdPlistXml({ intervalMinutes });
+
+  if (process.env.EMPIRICAL_SCHEDULER_FAKE_LOG) {
+    execCommand('__write_plist__', [plistPath], { input: xml });
+  } else {
+    ensureDir(path.dirname(plistPath));
+    fs.writeFileSync(plistPath, xml, 'utf8');
+  }
+
+  if (!commandAvailable('launchctl')) {
+    throw new Error('launchctl is not available on this machine — cannot register scheduled sync');
+  }
+  const domain = launchdGuiDomain();
+  // bootout first (ignore failure — it fails harmlessly if nothing was loaded yet) so
+  // re-registration is idempotent instead of erroring on an already-loaded label.
+  execCommand('launchctl', ['bootout', `${domain}/${LAUNCHD_LABEL}`]);
+  const result = execCommand('launchctl', ['bootstrap', domain, plistPath]);
+  if (result.status !== 0) {
+    throw new Error(`launchctl bootstrap failed: ${(result.stderr || result.stdout || '').trim() || 'unknown error'}`);
+  }
+}
+
+function deregisterMacOS() {
+  const plistPath = getLaunchAgentPlistPath();
+  if (commandAvailable('launchctl')) {
+    const domain = launchdGuiDomain();
+    execCommand('launchctl', ['bootout', `${domain}/${LAUNCHD_LABEL}`]);
+  }
+  if (process.env.EMPIRICAL_SCHEDULER_FAKE_LOG) {
+    execCommand('__remove_plist__', [plistPath]);
+  } else if (fs.existsSync(plistPath)) {
+    fs.rmSync(plistPath, { force: true });
+  }
+}
+
+function registerLinux(intervalMinutes) {
+  if (!commandAvailable('crontab')) {
+    throw new Error('crontab is not available on this machine — cannot register scheduled sync');
+  }
+  const readResult = execCommand('crontab', ['-l']);
+  const existing = readResult.status === 0 ? (readResult.stdout || '') : '';
+  const nextContent = mergeCrontab(existing, buildCronLine({ intervalMinutes }));
+  const writeResult = execCommand('crontab', ['-'], { input: nextContent });
+  if (writeResult.status !== 0) {
+    throw new Error(`crontab write failed: ${(writeResult.stderr || writeResult.stdout || '').trim() || 'unknown error'}`);
+  }
+}
+
+function deregisterLinux() {
+  if (!commandAvailable('crontab')) return;
+  const readResult = execCommand('crontab', ['-l']);
+  const existing = readResult.status === 0 ? (readResult.stdout || '') : '';
+  const nextContent = removeCronBlock(existing);
+  if (nextContent === existing) return; // block wasn't present — nothing to do
+  execCommand('crontab', ['-'], { input: nextContent });
+}
+
+// ─── Public entrypoints ─────────────────────────────────────────────────────────────────────
+
+// Registers (or idempotently re-registers/updates) the per-OS scheduled task that runs
+// `node <cli-entry> kit sync --quiet` on the configured interval. Throws on failure — callers
+// decide whether that's fatal to the invoking command (see kitCommands.js, which treats
+// scheduler failures as non-fatal/best-effort so a broken scheduler never blocks `kit use`).
+function registerScheduledSync() {
+  const intervalMinutes = getSyncIntervalMinutes();
+  const platform = getPlatform();
+  if (platform === 'win32') return registerWindows(intervalMinutes);
+  if (platform === 'darwin') return registerMacOS(intervalMinutes);
+  if (platform === 'linux') return registerLinux(intervalMinutes);
+  throw new Error(`Scheduled sync is not supported on platform "${platform}"`);
+}
+
+// Deregisters the per-OS scheduled task. Always idempotent/best-effort: calling this when
+// nothing is registered is a harmless no-op, never an error.
+function deregisterScheduledSync() {
+  const platform = getPlatform();
+  if (platform === 'win32') return deregisterWindows();
+  if (platform === 'darwin') return deregisterMacOS();
+  if (platform === 'linux') return deregisterLinux();
+  throw new Error(`Scheduled sync is not supported on platform "${platform}"`);
+}
+
+module.exports = {
+  DEFAULT_INTERVAL_MIN,
+  MIN_INTERVAL_MIN,
+  WINDOWS_TASK_NAME,
+  LAUNCHD_LABEL,
+  CRON_START_MARKER,
+  CRON_END_MARKER,
+  getSyncIntervalMinutes,
+  getCliEntryPath,
+  getNodePath,
+  getPlatform,
+  getLaunchAgentPlistPath,
+  execCommand,
+  buildSyncCommandString,
+  buildWindowsCreateArgs,
+  buildWindowsDeleteArgs,
+  buildLaunchdPlistXml,
+  buildCronLine,
+  mergeCrontab,
+  removeCronBlock,
+  registerScheduledSync,
+  deregisterScheduledSync
+};