@venturewild/workspace 0.1.2 → 0.1.4

package/server/src/service.mjs

@@ -1,16 +1,25 @@
 // service.mjs — installs / removes the per-OS, NO-ADMIN autostart entry that
-// launches the WorkspaceSupervisor hidden at login. See docs/always-on-design.md.
+// launches the WorkspaceSupervisor at login. See docs/always-on-design.md.
 //
 // Windows (proven end-to-end incl. a real reboot, 2026-05-30): writes a tiny VBS
 // that runs `node <cli> service run` with no window, and registers it under
-// HKCU\...\Run (per-user, NO admin / UAC). macOS (LaunchAgent + KeepAlive) and
-// Linux (systemd --user + Restart=always) are designed but not yet implemented —
-// they return a clear "not yet" result so callers degrade gracefully (the user
-// can still run `wild-workspace` manually).
+// HKCU\...\Run (per-user, NO admin / UAC).
 //
-// All state (the VBS, service.json, the supervisor's lock/logs) lives in the
-// machine-global dir (~/.wild-workspace), NEVER the synced workspace (locked
-// principle #1). Every external touch-point (reg.exe, kill) is an injected seam.
+// macOS (code-complete + unit-tested 2026-06-01; real-Mac reboot proof pending):
+// writes a `~/Library/LaunchAgents/<label>.plist` (RunAtLoad + KeepAlive +
+// ThrottleInterval) and registers it in the user's GUI domain via
+// `launchctl bootstrap gui/<uid>` (legacy `launchctl load -w` fallback). Runs as
+// the user, NO admin — macOS 13+ shows a one-time "Background item added" toast +
+// a Login Items toggle (consent, not admin). launchd provides crash-restart for
+// free; the supervisor still owns the singleton lock + child watchdog.
+//
+// Linux (systemd --user) is designed but not yet implemented — it returns a clear
+// "not yet" result so callers degrade gracefully (the user runs `wild-workspace`).
+//
+// All state (the VBS / plist, service.json, the supervisor's lock/logs) lives in
+// the machine-global dir (~/.wild-workspace) or ~/Library/LaunchAgents, NEVER the
+// synced workspace (locked principle #1). Every external touch-point (reg.exe,
+// launchctl, kill) is an injected seam for testability.
 
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -22,11 +31,28 @@ const execFileP = promisify(execFile);
 
 export const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
 export const RUN_VALUE_NAME = 'WildWorkspace';
+export const LAUNCHD_LABEL = 'llc.venturewild.workspace';
 
 export function globalDir() { return path.join(os.homedir(), '.wild-workspace'); }
+function defaultLaunchAgentsDir() { return path.join(os.homedir(), 'Library', 'LaunchAgents'); }
+function currentUid() { return typeof process.getuid === 'function' ? process.getuid() : 0; }
 
 /** Is per-user autostart implemented for this platform yet? */
-export function isSupported(platform = process.platform) { return platform === 'win32'; }
+export function isSupported(platform = process.platform) {
+  return platform === 'win32' || platform === 'darwin';
+}
+
+/** Shared: read the supervisor's pidfile and report whether that pid is alive. */
+function supervisorLiveness(dir) {
+  let supervisorPid = null, supervisorAlive = false;
+  try { supervisorPid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim()) || null; } catch { /* none */ }
+  if (supervisorPid) {
+    try { process.kill(supervisorPid, 0); supervisorAlive = true; } catch (e) { supervisorAlive = !!(e && e.code === 'EPERM'); }
+  }
+  return { supervisorPid, supervisorAlive };
+}
+
+// --- Windows implementation -------------------------------------------------
 
 // A VBS that runs `node <cli> service run` with NO window (0 = SW_HIDE,
 // False = don't wait). VBS string literals escape a `"` as `""`.
@@ -45,8 +71,6 @@ export function buildVbs(node, cli) {
 /** The HKCU\Run value: launch the VBS via the windowless wscript host. */
 export function buildRunValue(vbs) { return `wscript.exe "${vbs}"`; }
 
-// --- Windows implementation -------------------------------------------------
-
 async function winInstall({ node, cli, workspaceDir, port, version }, { dir, execFileImpl }) {
   fs.mkdirSync(dir, { recursive: true });
   const vbs = path.join(dir, 'launch-hidden.vbs');
@@ -59,7 +83,7 @@ async function winInstall({ node, cli, workspaceDir, port, version }, { dir, exe
   );
   const runValue = buildRunValue(vbs);
   await execFileImpl('reg', ['add', RUN_KEY, '/v', RUN_VALUE_NAME, '/t', 'REG_SZ', '/d', runValue, '/f']);
-  return { installed: true, mechanism: 'HKCU\\Run', vbs, runValue, serviceJson };
+  return { installed: true, mechanism: 'HKCU\\Run', launcher: vbs, vbs, runValue, serviceJson };
 }
 
 async function winUninstall({ dir, execFileImpl, killImpl }) {
@@ -81,15 +105,128 @@ async function winStatus({ dir, execFileImpl, probeImpl, port }) {
     installed = new RegExp(RUN_VALUE_NAME, 'i').test(stdout);
     runValue = (stdout.match(/REG_SZ\s+(.*?)\s*$/m) || [])[1] || null;
   } catch { /* value absent → not installed */ }
-  let supervisorPid = null, supervisorAlive = false;
-  try { supervisorPid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim()) || null; } catch { /* none */ }
-  if (supervisorPid) {
-    try { process.kill(supervisorPid, 0); supervisorAlive = true; } catch (e) { supervisorAlive = !!(e && e.code === 'EPERM'); }
-  }
+  const { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
   const serverUp = await probeImpl(port);
   return { installed, runValue, supervisorPid, supervisorAlive, serverUp };
 }
 
+// --- macOS implementation ---------------------------------------------------
+
+export function plistPath(launchAgentsDir) {
+  return path.join(launchAgentsDir, `${LAUNCHD_LABEL}.plist`);
+}
+
+function xmlEscape(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// A LaunchAgent that runs `node <cli> service run` at login + relaunches it if it
+// dies (KeepAlive). ThrottleInterval bounds the restart rate. Output is logged to
+// ~/.wild-workspace so a silent death is debuggable (footgun checklist §8).
+export function buildPlist({ node, cli, workspaceDir, outLog, errLog, label = LAUNCHD_LABEL }) {
+  const args = [node, cli, 'service', 'run'].map((a) => `    <string>${xmlEscape(a)}</string>`);
+  const env = workspaceDir ? [
+    '  <key>EnvironmentVariables</key>',
+    '  <dict>',
+    '    <key>WILD_WORKSPACE_DIR</key>',
+    `    <string>${xmlEscape(workspaceDir)}</string>`,
+    '  </dict>',
+  ] : [];
+  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>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <true/>',
+    '  <key>ThrottleInterval</key>',
+    '  <integer>10</integer>',
+    ...env,
+    '  <key>StandardOutPath</key>',
+    `  <string>${xmlEscape(outLog)}</string>`,
+    '  <key>StandardErrorPath</key>',
+    `  <string>${xmlEscape(errLog)}</string>`,
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+async function macInstall({ node, cli, workspaceDir, port, version }, { dir, launchAgentsDir, execFileImpl, uid }) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.mkdirSync(launchAgentsDir, { recursive: true });
+  const plist = plistPath(launchAgentsDir);
+  const serviceJson = path.join(dir, 'service.json');
+  const outLog = path.join(dir, 'launchagent.out.log');
+  const errLog = path.join(dir, 'launchagent.err.log');
+  fs.writeFileSync(plist, buildPlist({ node, cli, workspaceDir, outLog, errLog }), 'utf8');
+  fs.writeFileSync(
+    serviceJson,
+    JSON.stringify({ node, cli, workspaceDir, port, version, installedAt: new Date().toISOString() }, null, 2),
+    'utf8',
+  );
+  const domain = `gui/${uid}`;
+  const target = `${domain}/${LAUNCHD_LABEL}`;
+  // Clear any prior registration so a changed plist is picked up (launchd caches
+  // the loaded plist; bootout→bootstrap makes re-install idempotent).
+  try { await execFileImpl('launchctl', ['bootout', target]); } catch { /* not loaded */ }
+  let loadVerb = 'bootstrap';
+  try {
+    await execFileImpl('launchctl', ['bootstrap', domain, plist]);
+  } catch {
+    // Pre-Yosemite-style macOS without `bootstrap` — fall back to the legacy verb.
+    await execFileImpl('launchctl', ['load', '-w', plist]);
+    loadVerb = 'load';
+  }
+  return { installed: true, mechanism: 'LaunchAgent', launcher: plist, plist, label: LAUNCHD_LABEL, runValue: target, serviceJson, loadVerb };
+}
+
+async function macUninstall({ dir, launchAgentsDir, execFileImpl, killImpl, uid }) {
+  const plist = plistPath(launchAgentsDir);
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+  try {
+    await execFileImpl('launchctl', ['bootout', target]);
+  } catch {
+    try { await execFileImpl('launchctl', ['unload', '-w', plist]); } catch { /* not loaded */ }
+  }
+  // launchd's bootout SIGTERMs the launchd-managed supervisor; a manually-started
+  // one still holds the lock, so stop it too (mirrors the Windows path).
+  let stoppedPid = null;
+  try {
+    const pid = Number(fs.readFileSync(path.join(dir, 'supervisor.lock'), 'utf8').trim());
+    if (pid) { killImpl(pid); stoppedPid = pid; }
+  } catch { /* none running */ }
+  let removedKey = false;
+  try { if (fs.existsSync(plist)) { fs.unlinkSync(plist); removedKey = true; } } catch { /* gone */ }
+  try { fs.unlinkSync(path.join(dir, 'service.json')); } catch { /* gone */ }
+  return { uninstalled: true, removedKey, stoppedPid };
+}
+
+async function macStatus({ dir, launchAgentsDir, execFileImpl, probeImpl, uid, port }) {
+  const plist = plistPath(launchAgentsDir);
+  const installed = fs.existsSync(plist); // the plist IS the persistent registration
+  const target = `gui/${uid}/${LAUNCHD_LABEL}`;
+  let loaded = false, launchdPid = null;
+  try {
+    const { stdout } = await execFileImpl('launchctl', ['print', target]);
+    launchdPid = Number((stdout.match(/\bpid\s*=\s*(\d+)/i) || [])[1]) || null;
+    loaded = launchdPid !== null || /state\s*=\s*running/i.test(stdout);
+  } catch { /* not loaded into launchd */ }
+  let { supervisorPid, supervisorAlive } = supervisorLiveness(dir);
+  if (launchdPid) { supervisorPid = launchdPid; supervisorAlive = true; }
+  else if (loaded) { supervisorAlive = true; }
+  const serverUp = await probeImpl(port);
+  return { installed, runValue: installed ? plist : null, supervisorPid, supervisorAlive, serverUp, loaded };
+}
+
 // --- public API (platform dispatch) ----------------------------------------
 
 const unsupported = (platform, key) => ({
@@ -101,27 +238,60 @@ const unsupported = (platform, key) => ({
 
 export async function installService(opts = {}, deps = {}) {
   const platform = deps.platform || process.platform;
-  if (platform !== 'win32') return unsupported(platform, 'installed');
-  return winInstall(opts, { dir: deps.dir || globalDir(), execFileImpl: deps.execFileImpl || execFileP });
+  if (platform === 'win32') {
+    return winInstall(opts, { dir: deps.dir || globalDir(), execFileImpl: deps.execFileImpl || execFileP });
+  }
+  if (platform === 'darwin') {
+    return macInstall(opts, {
+      dir: deps.dir || globalDir(),
+      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      uid: deps.uid ?? currentUid(),
+    });
+  }
+  return unsupported(platform, 'installed');
 }
 
 export async function uninstallService(deps = {}) {
   const platform = deps.platform || process.platform;
-  if (platform !== 'win32') return unsupported(platform, 'uninstalled');
-  return winUninstall({
-    dir: deps.dir || globalDir(),
-    execFileImpl: deps.execFileImpl || execFileP,
-    killImpl: deps.killImpl || ((pid) => process.kill(pid)),
-  });
+  if (platform === 'win32') {
+    return winUninstall({
+      dir: deps.dir || globalDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
+    });
+  }
+  if (platform === 'darwin') {
+    return macUninstall({
+      dir: deps.dir || globalDir(),
+      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      killImpl: deps.killImpl || ((pid) => process.kill(pid)),
+      uid: deps.uid ?? currentUid(),
+    });
+  }
+  return unsupported(platform, 'uninstalled');
 }
 
 export async function serviceStatus(opts = {}, deps = {}) {
   const platform = deps.platform || process.platform;
-  if (platform !== 'win32') return { supported: false, platform };
-  return winStatus({
-    dir: deps.dir || globalDir(),
-    execFileImpl: deps.execFileImpl || execFileP,
-    probeImpl: deps.probeImpl || (async () => false),
-    port: opts.port || 5173,
-  });
+  if (platform === 'win32') {
+    return winStatus({
+      dir: deps.dir || globalDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      probeImpl: deps.probeImpl || (async () => false),
+      port: opts.port || 5173,
+    });
+  }
+  if (platform === 'darwin') {
+    return macStatus({
+      dir: deps.dir || globalDir(),
+      launchAgentsDir: deps.launchAgentsDir || defaultLaunchAgentsDir(),
+      execFileImpl: deps.execFileImpl || execFileP,
+      probeImpl: deps.probeImpl || (async () => false),
+      uid: deps.uid ?? currentUid(),
+      port: opts.port || 5173,
+    });
+  }
+  return { supported: false, platform };
 }