@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-workspace/src/supervisor.mjs

@@ -0,0 +1,264 @@
+/**
+ * supervisor.mjs — Detect and introspect the workspace's service supervisor.
+ *
+ * The workspace can be run two ways:
+ *   1. Foreground / detached via ws.mjs (the pidfile dance).
+ *   2. Supervised by launchd (macOS) or systemd (--user, Linux), installed
+ *      via install-daemon.mjs.
+ *
+ * When a supervisor is present, ws.mjs must NOT manage the process directly:
+ *   - `kill <pid>` will be undone by KeepAlive / Restart=always within ms.
+ *   - The CLI's pidfile does not exist, so the legacy status check reports
+ *     "stopped" while a healthy process serves the port.
+ *
+ * This module exports pure-ish functions that:
+ *   - locate the per-platform unit file,
+ *   - parse the supervisor's view of the service (PID + state),
+ *   - probe which PID currently listens on a TCP port via lsof / ss / netstat.
+ *
+ * All shell-outs are funnelled through an injectable `exec` parameter so the
+ * tests can run on any host without touching launchctl / systemctl / lsof.
+ *
+ * Exit-code policy follows the tooling standard §6:
+ *   0 ok | 1 usage error | 2 operational failure | 3 transport/IO failure
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir, platform as osPlatform } from 'node:os';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+export const LAUNCHD_LABEL = 'com.dave.workspace';
+export const SYSTEMD_UNIT = 'dave-workspace.service';
+
+/**
+ * @typedef {object} SupervisorInfo
+ * @property {'launchd'|'systemd'|null} kind  Which supervisor is configured (null = none)
+ * @property {string|null} unitPath           Path to the plist (launchd) or unit (systemd) file
+ * @property {string} label                   Service label (launchd) or unit name (systemd)
+ */
+
+/**
+ * @typedef {object} SupervisorState
+ * @property {'running'|'loaded'|'inactive'|'unknown'} state
+ * @property {number|null} pid                Supervised process PID, if known
+ * @property {string|null} raw                Raw supervisor output for diagnostics
+ */
+
+/**
+ * Resolve the launchd plist path for the workspace daemon.
+ * @param {{ home?: string }} [opts]
+ */
+export function launchdPlistPath(opts = {}) {
+  const home = opts.home || homedir();
+  return join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+}
+
+/**
+ * Resolve the systemd --user unit path for the workspace daemon.
+ * @param {{ home?: string }} [opts]
+ */
+export function systemdUnitPath(opts = {}) {
+  const home = opts.home || homedir();
+  return join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT);
+}
+
+/**
+ * Detect which supervisor (if any) manages the workspace on this host.
+ *
+ * Detection is purely file-existence based — it does NOT shell out to the
+ * service manager. A unit file alone is sufficient to claim supervision;
+ * whether it is currently loaded is a separate question answered by
+ * {@link readSupervisorState}.
+ *
+ * @param {object} [deps]
+ * @param {string} [deps.platform]                  os.platform() return — overridable for tests
+ * @param {string} [deps.home]                       Home directory — overridable for tests
+ * @param {(p: string) => boolean} [deps.fileExists] Existence probe — overridable for tests
+ * @returns {SupervisorInfo}
+ */
+export function detectSupervisor(deps = {}) {
+  const plat = deps.platform || osPlatform();
+  const home = deps.home || homedir();
+  const fileExists = deps.fileExists || existsSync;
+
+  if (plat === 'darwin') {
+    const p = launchdPlistPath({ home });
+    if (fileExists(p)) return { kind: 'launchd', unitPath: p, label: LAUNCHD_LABEL };
+  }
+  if (plat === 'linux') {
+    const p = systemdUnitPath({ home });
+    if (fileExists(p)) return { kind: 'systemd', unitPath: p, label: SYSTEMD_UNIT };
+  }
+  return { kind: null, unitPath: null, label: '' };
+}
+
+/**
+ * Parse `launchctl list <label>` output for PID and last-exit info.
+ * Output is a plist-ish dict; we only need PID and LastExitStatus.
+ *
+ * @param {string} raw
+ * @returns {SupervisorState}
+ */
+export function parseLaunchctlList(raw) {
+  if (!raw) return { state: 'unknown', pid: null, raw: raw || '' };
+  const pidMatch = raw.match(/"PID"\s*=\s*(\d+)/);
+  if (pidMatch) {
+    const pid = parseInt(pidMatch[1], 10);
+    if (Number.isFinite(pid) && pid > 0) {
+      return { state: 'running', pid, raw };
+    }
+  }
+  // No PID line → loaded but not currently running (KeepAlive may be throttling
+  // a restart, or the service exited and is about to relaunch).
+  return { state: 'loaded', pid: null, raw };
+}
+
+/**
+ * Parse `systemctl --user show <unit>` (key=value pairs) for ActiveState and MainPID.
+ * @param {string} raw
+ * @returns {SupervisorState}
+ */
+export function parseSystemctlShow(raw) {
+  if (!raw) return { state: 'unknown', pid: null, raw: raw || '' };
+  const lines = raw.split(/\r?\n/);
+  const map = {};
+  for (const l of lines) {
+    const idx = l.indexOf('=');
+    if (idx === -1) continue;
+    map[l.slice(0, idx).trim()] = l.slice(idx + 1).trim();
+  }
+  const active = map.ActiveState || 'unknown';
+  const pidStr = map.MainPID;
+  const pid = pidStr && /^\d+$/.test(pidStr) && pidStr !== '0' ? parseInt(pidStr, 10) : null;
+
+  let state = 'unknown';
+  if (active === 'active') state = 'running';
+  else if (active === 'activating' || active === 'reloading') state = 'loaded';
+  else if (active === 'inactive' || active === 'failed' || active === 'deactivating') state = 'inactive';
+
+  return { state, pid, raw };
+}
+
+/**
+ * Read live supervisor state by invoking `launchctl list` / `systemctl --user show`.
+ * Shell-out is funnelled through an injectable `exec` so tests don't touch the host.
+ *
+ * @param {SupervisorInfo} info
+ * @param {object} [deps]
+ * @param {(cmd: string) => string} [deps.exec]  Sync exec returning stdout. Throws on failure.
+ * @returns {SupervisorState}
+ */
+export function readSupervisorState(info, deps = {}) {
+  const exec = deps.exec || ((cmd) => execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
+  if (!info || !info.kind) return { state: 'unknown', pid: null, raw: '' };
+
+  try {
+    if (info.kind === 'launchd') {
+      const raw = exec(`launchctl list ${info.label}`);
+      return parseLaunchctlList(raw);
+    }
+    if (info.kind === 'systemd') {
+      const raw = exec(`systemctl --user show ${info.label} --no-pager`);
+      return parseSystemctlShow(raw);
+    }
+  } catch {
+    // launchctl exits non-zero when the label isn't loaded; systemctl exits
+    // non-zero when the unit isn't installed. Either way the service is not
+    // currently registered → "inactive" is the safe report.
+    return { state: 'inactive', pid: null, raw: '' };
+  }
+  return { state: 'unknown', pid: null, raw: '' };
+}
+
+/**
+ * Identify which PID currently holds a TCP listener on `port`, if any.
+ *
+ * Probes in order:
+ *   - lsof   (mac, most Linux)
+ *   - ss     (modern Linux without lsof)
+ *   - netstat (Windows fallback)
+ *
+ * Returns null if no probe is available or no PID can be derived. Used by
+ * `pa workspace status` to corroborate the supervisor's view with what's
+ * actually listening on the port.
+ *
+ * @param {number} port
+ * @param {object} [deps]
+ * @param {(cmd: string) => string} [deps.exec]
+ * @param {string} [deps.platform]
+ * @returns {{ pid: number, command: string|null }|null}
+ */
+export function findPortListener(port, deps = {}) {
+  const exec = deps.exec || ((cmd) => execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
+  const plat = deps.platform || osPlatform();
+
+  // Windows: netstat -ano | findstr :PORT
+  if (plat === 'win32') {
+    try {
+      const raw = exec(`netstat -ano -p tcp | findstr :${port}`);
+      const line = raw.split(/\r?\n/).find((l) => l.includes('LISTENING'));
+      if (!line) return null;
+      const parts = line.trim().split(/\s+/);
+      const pid = parseInt(parts[parts.length - 1], 10);
+      if (!Number.isFinite(pid)) return null;
+      return { pid, command: null };
+    } catch {
+      return null;
+    }
+  }
+
+  // Unix: try lsof first (preferred — gives command name too).
+  try {
+    const raw = exec(`lsof -nP -iTCP:${port} -sTCP:LISTEN -Fpc`);
+    const lines = raw.split(/\r?\n/).filter(Boolean);
+    let pid = null;
+    let command = null;
+    for (const l of lines) {
+      if (l.startsWith('p')) pid = parseInt(l.slice(1), 10);
+      else if (l.startsWith('c')) command = l.slice(1);
+    }
+    if (Number.isFinite(pid)) return { pid, command };
+  } catch {
+    // lsof absent or no listener — fall through to ss.
+  }
+
+  // Linux without lsof: ss -ltnp 'sport = :PORT'
+  try {
+    const raw = exec(`ss -ltnp sport = :${port}`);
+    // Example line:
+    //   LISTEN 0  511  127.0.0.1:4200  0.0.0.0:*  users:(("node",pid=12345,fd=20))
+    const m = raw.match(/pid=(\d+)/);
+    if (!m) return null;
+    const pid = parseInt(m[1], 10);
+    if (!Number.isFinite(pid)) return null;
+    const cm = raw.match(/users:\(\("([^"]+)"/);
+    return { pid, command: cm ? cm[1] : null };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compose a one-shot CLI invocation that asks the supervisor to bounce the
+ * service. Returned as a string the caller can run via execSync — keeps the
+ * actual exec out of this module so callers can dry-run or pipe stdio.
+ *
+ * @param {SupervisorInfo} info
+ * @returns {string|null}
+ */
+export function restartCommand(info) {
+  if (!info || !info.kind) return null;
+  if (info.kind === 'launchd') {
+    // `kickstart -k` kills the running process and respawns it — exactly the
+    // semantic we want for an in-place version pickup. The gui/$UID target
+    // is the per-user launchd domain where LaunchAgents live.
+    const uid = typeof process !== 'undefined' && process.getuid ? process.getuid() : null;
+    if (uid === null) return null;
+    return `launchctl kickstart -k gui/${uid}/${info.label}`;
+  }
+  if (info.kind === 'systemd') {
+    return `systemctl --user restart ${info.label}`;
+  }
+  return null;
+}