@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/lib/selfRestart.js

@@ -0,0 +1,261 @@
+import { createHash } from 'node:crypto';
+import { watch as fsWatch } from 'node:fs';
+import { access, readdir, readFile, stat, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+
+/** launchd (KeepAlive.SuccessfulExit=false) and systemd (Restart=on-failure) start the daemon again on any non-zero exit. */
+export const RESTART_EXIT_CODE = 75;
+export const RESTART_REQUEST_FILE = 'restart.request';
+export const RESTART_HISTORY_FILE = 'restart-history.json';
+const LOOP_WINDOW_MS = 5 * 60_000;
+const LOOP_MAX_RESTARTS = 5;
+
+// Modules read data files next to them (src/lib/mirror-contract.json), so every file under src/ is source. Dotfiles
+// (.DS_Store, editor swap files) are not.
+const sourceName = (name) => !String(name).split(path.sep).some((part) => part.startsWith('.'));
+
+async function sourceFiles(root) {
+  const entries = await readdir(path.join(root, 'src'), { withFileTypes: true, recursive: true });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => path.relative(root, path.join(entry.parentPath ?? entry.path, entry.name)))
+    .filter(sourceName);
+}
+
+/** sha256 of each file under the plugin's src/ and of its package.json, by path relative to the plugin root. */
+export async function sourceSnapshot(root) {
+  const snapshot = new Map();
+  for (const file of ['package.json', ...(await sourceFiles(root))].sort()) {
+    const bytes = await readFile(path.join(root, file)).catch(() => null);
+    if (bytes) snapshot.set(file, createHash('sha256').update(bytes).digest('hex'));
+  }
+  return snapshot;
+}
+
+/** Files added, removed or rewritten with different bytes; a touch or a no-op checkout changes nothing. */
+export function changedFiles(before, after) {
+  const files = new Set([...before.keys(), ...after.keys()]);
+  return [...files].filter((file) => before.get(file) !== after.get(file)).sort();
+}
+
+const snapshotKey = (snapshot) => [...snapshot].join('\n');
+
+/**
+ * Calls onChange(files) once, when the plugin's sources differ from their bytes at start and have been quiet for
+ * debounceMs. fs.watch events reset a trailing debounce, after which the files as enumerated then are hashed. If a watch
+ * fails (FSEvents can refuse it with EMFILE, git can swap a directory away), it polls every pollMs instead, firing only
+ * when two polls debounceMs apart agree, and tries to re-arm the watch every rearmMs.
+ */
+export async function watchSource({
+  root, onChange, onError = () => {}, debounceMs = 2_000, pollMs = 5_000, rearmMs = 30_000, watch = fsWatch, now = Date.now,
+}) {
+  const booted = await sourceSnapshot(root);
+  let closed = false;
+  let fired = false;
+  let comparing = false;
+  let timer = null;
+  let poller = null;
+  let rearm = null;
+  let watchers = [];
+  let seenKey = snapshotKey(booted);
+  let seenAt = now();
+
+  const fire = (current) => {
+    const files = changedFiles(booted, current);
+    if (!files.length || fired || closed) return;
+    fired = true;
+    onChange(files);
+  };
+  const afterQuiet = async () => {
+    if (comparing || closed) return;
+    comparing = true;
+    try {
+      fire(await sourceSnapshot(root));
+    } catch {
+      changed();
+    } finally {
+      comparing = false;
+    }
+  };
+  const changed = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void afterQuiet();
+    }, debounceMs);
+  };
+  const poll = async () => {
+    if (comparing || closed) return;
+    comparing = true;
+    try {
+      const current = await sourceSnapshot(root);
+      const key = snapshotKey(current);
+      if (key !== seenKey) {
+        seenKey = key;
+        seenAt = now();
+      } else if (now() - seenAt >= debounceMs) {
+        fire(current);
+      }
+    } catch {
+      seenKey = null;
+      seenAt = now();
+    } finally {
+      comparing = false;
+    }
+  };
+  const closeWatchers = () => {
+    for (const watcher of watchers) watcher.close();
+    watchers = [];
+  };
+  const failed = (error) => {
+    closeWatchers();
+    if (closed) return;
+    if (!poller) {
+      onError(error);
+      poller = setInterval(() => void poll(), pollMs);
+      poller.unref?.();
+    }
+    clearTimeout(rearm);
+    rearm = setTimeout(arm, rearmMs);
+    rearm.unref?.();
+  };
+  function arm() {
+    if (closed) return;
+    try {
+      watchers = [
+        watch(path.join(root, 'src'), { recursive: true }, (_event, name) => {
+          if (name === null || sourceName(name)) changed();
+        }),
+        watch(root, (_event, name) => {
+          if (String(name) === 'package.json') changed();
+        }),
+      ];
+      for (const watcher of watchers) {
+        watcher.on('error', failed);
+        watcher.unref?.();
+      }
+    } catch (error) {
+      failed(error);
+    }
+  }
+  arm();
+  return {
+    get polling() {
+      return poller !== null;
+    },
+    close() {
+      closed = true;
+      clearTimeout(timer);
+      clearTimeout(rearm);
+      clearInterval(poller);
+      closeWatchers();
+    },
+  };
+}
+
+export async function restartRequested(directory) {
+  try {
+    await access(path.join(directory, RESTART_REQUEST_FILE));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Deletes restart.request and returns its mtime in ms, or null if there was none. Only the call that deleted it gets a
+ * time, so one request restarts the daemon once.
+ */
+export async function consumeRestartRequest(directory) {
+  const file = path.join(directory, RESTART_REQUEST_FILE);
+  try {
+    const { mtimeMs } = await stat(file);
+    await unlink(file);
+    return mtimeMs;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/** Counts daemon starts in a sliding window; past maxRestarts the daemon stops restarting itself until the window clears. */
+export class RestartGuard {
+  constructor({ directory, now = Date.now, windowMs = LOOP_WINDOW_MS, maxRestarts = LOOP_MAX_RESTARTS }) {
+    this.file = path.join(directory, RESTART_HISTORY_FILE);
+    this.now = now;
+    this.windowMs = windowMs;
+    this.maxRestarts = maxRestarts;
+    this.starts = [];
+  }
+
+  async recordStart() {
+    const stored = await readOwnerOnlyJson(this.file).catch(() => null);
+    const at = this.now();
+    this.starts = [...(Array.isArray(stored?.starts) ? stored.starts.filter(Number.isFinite) : []), at]
+      .filter((start) => at - start < this.windowMs)
+      .slice(-(this.maxRestarts + 2));
+    await writeOwnerOnlyJson(this.file, { starts: this.starts });
+    return this.status();
+  }
+
+  status() {
+    const at = this.now();
+    const recent = this.starts.filter((start) => at - start < this.windowMs);
+    const restarts = Math.max(0, recent.length - 1);
+    const looping = restarts > this.maxRestarts;
+    return {
+      looping,
+      restarts,
+      windowMs: this.windowMs,
+      clearsAt: looping ? recent[recent.length - this.maxRestarts - 2] + this.windowMs : null,
+    };
+  }
+}
+
+/**
+ * Tracks each long-running loop (the main cycle, a mirror pass) from begin to end. A loop that reports no progress for
+ * its limit is reported once to onStall with the step and call it was last awaiting.
+ */
+export class Watchdog {
+  constructor({ onStall, now = Date.now }) {
+    this.onStall = onStall;
+    this.now = now;
+    this.loops = new Map();
+  }
+
+  begin(loop, step, limitMs) {
+    const entry = { step, call: null, limitMs, at: this.now(), stalled: false };
+    this.loops.set(loop, entry);
+    return entry;
+  }
+
+  progress(loop, { step, call } = {}) {
+    const entry = this.loops.get(loop);
+    if (!entry) return;
+    entry.at = this.now();
+    if (step !== undefined) {
+      entry.step = step;
+      entry.call = null;
+    }
+    if (call !== undefined) entry.call = call;
+  }
+
+  end(loop, entry = this.loops.get(loop)) {
+    if (this.loops.get(loop) === entry) this.loops.delete(loop);
+  }
+
+  check() {
+    for (const [loop, entry] of this.loops) {
+      const stalledMs = this.now() - entry.at;
+      if (entry.stalled || stalledMs <= entry.limitMs) continue;
+      entry.stalled = true;
+      this.onStall({
+        loop,
+        awaiting: entry.call ? `${entry.step}: ${entry.call}` : entry.step,
+        stalledMs,
+        limitMs: entry.limitMs,
+      });
+    }
+  }
+}

package/src/lib/serviceManager.js

@@ -0,0 +1,419 @@
+import { access, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { HubError } from './errors.js';
+import {
+  ensureOwnerOnlyDirectory,
+  readOwnerOnlyJson,
+  writeOwnerOnlyText,
+} from './storage.js';
+import { execFileBounded as execFile } from './subprocess.js';
+
+const LABEL = 'com.agentpulse.hub';
+const SYSTEMD_UNIT = 'agentpulse-hub.service';
+const START_ATTEMPTS = 6;
+const START_RETRY_MS = 250;
+const ABSENT_SERVICE = /not found|could not find|no such process|not loaded|inactive|not running/i;
+
+function xml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function launchdPlist({ nodePath, daemonPath, configDir, logDir }) {
+  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>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(nodePath)}</string>
+    <string>${xml(daemonPath)}</string>
+    <string>--config-dir</string>
+    <string>${xml(configDir)}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ProcessType</key><string>Standard</string>
+  <key>StandardOutPath</key><string>${xml(path.join(logDir, 'daemon.log'))}</string>
+  <key>StandardErrorPath</key><string>${xml(path.join(logDir, 'daemon-error.log'))}</string>
+</dict>
+</plist>
+`;
+}
+
+function unxml(value) {
+  return value
+    .replaceAll('&apos;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+}
+
+function launchdArgv(contents) {
+  const programArguments = contents.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1] || '';
+  return [...programArguments.matchAll(/<string>([^<]*)<\/string>/g)].map((match) => unxml(match[1]));
+}
+
+function systemdArgv(contents) {
+  const execStart = contents.match(/^ExecStart=(.*)$/m)?.[1] || '';
+  return [...execStart.matchAll(/"((?:\\.|[^"\\])*)"|(\S+)/g)].map(([, quoted, bare]) =>
+    quoted === undefined ? bare : quoted.replace(/\\(["\\])/g, '$1')
+  );
+}
+
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function systemdArgument(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+  return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+function systemdUnit({ nodePath, daemonPath, configDir }) {
+  for (const value of [nodePath, daemonPath, configDir]) {
+    if (/[\n\r]/.test(value)) {
+      throw new HubError('HUB_SERVICE_PATH_DENIED', 'Service paths cannot contain newlines');
+    }
+  }
+  return `[Unit]
+Description=AgentPulse Pulse local connector
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${systemdArgument(nodePath)} ${systemdArgument(daemonPath)} --config-dir ${systemdArgument(configDir)}
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=true
+PrivateTmp=true
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export class ServiceManager {
+  constructor({
+    platform = process.platform,
+    home = os.homedir(),
+    uid = typeof process.getuid === 'function' ? process.getuid() : null,
+    nodePath = process.execPath,
+    daemonPath,
+    configDir = path.join(
+      process.env.XDG_CONFIG_HOME || path.join(home, '.config'),
+      'agentpulse',
+      'hub'
+    ),
+    logDir = path.join(
+      process.env.XDG_STATE_HOME || path.join(home, '.local', 'state'),
+      'agentpulse',
+      'hub',
+      'logs'
+    ),
+    execute = execFile,
+    wait = delay,
+    launchAgentsDir = path.join(home, 'Library', 'LaunchAgents'),
+  }) {
+    this.platform = platform;
+    this.home = home;
+    this.uid = uid;
+    this.nodePath = nodePath;
+    this.daemonPath = daemonPath;
+    this.configDir = configDir;
+    this.logDir = logDir;
+    this.execute = execute;
+    this.wait = wait;
+    this.launchAgentsDir = launchAgentsDir;
+  }
+
+  serviceFile() {
+    switch (this.platform) {
+      case 'darwin':
+        return path.join(this.home, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+      case 'linux':
+        return path.join(this.home, '.config', 'systemd', 'user', SYSTEMD_UNIT);
+      default:
+        throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Unsupported service platform: ${this.platform}`);
+    }
+  }
+
+  async install() {
+    if (!this.daemonPath) {
+      throw new HubError('HUB_DAEMON_PATH_MISSING', 'Daemon entry point is unavailable');
+    }
+    const serviceFile = this.serviceFile();
+    switch (this.platform) {
+      case 'darwin':
+        await ensureOwnerOnlyDirectory(this.logDir);
+        await writeOwnerOnlyText(
+          serviceFile,
+          launchdPlist({
+            nodePath: this.nodePath,
+            daemonPath: this.daemonPath,
+            configDir: this.configDir,
+            logDir: this.logDir,
+          })
+        );
+        break;
+      case 'linux':
+        await writeOwnerOnlyText(
+          serviceFile,
+          systemdUnit({
+            nodePath: this.nodePath,
+            daemonPath: this.daemonPath,
+            configDir: this.configDir,
+          })
+        );
+        await this.execute('systemctl', ['--user', 'daemon-reload']);
+        break;
+      default:
+        throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Unsupported service platform: ${this.platform}`);
+    }
+    return { serviceFile, platform: this.platform, label: LABEL };
+  }
+
+  async daemonPathCheck() {
+    let contents;
+    try {
+      contents = await readFile(this.serviceFile(), 'utf8');
+    } catch (error) {
+      if (error.code === 'ENOENT') return { ok: true, installed: null, expected: this.daemonPath };
+      throw error;
+    }
+    let argv;
+    switch (this.platform) {
+      case 'darwin':
+        argv = launchdArgv(contents);
+        break;
+      case 'linux':
+        argv = systemdArgv(contents);
+        break;
+      default:
+        throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Unsupported service platform: ${this.platform}`);
+    }
+    const [nodePath = null, installed = null] = argv;
+    let reason = null;
+    if (installed !== this.daemonPath) reason = 'daemon_path_changed';
+    else if (!nodePath || !(await exists(nodePath))) reason = 'node_missing';
+    if (!reason) return { ok: true, installed, expected: this.daemonPath, nodePath };
+    return {
+      ok: false,
+      code: 'HUB_SERVICE_PATH_STALE',
+      reason,
+      installed,
+      expected: this.daemonPath,
+      nodePath,
+      hint: 'Run `agentpulse pulse install` once, then `agentpulse pulse start`.',
+    };
+  }
+
+  async start() {
+    switch (this.platform) {
+      case 'darwin':
+        await this.#startLaunchd();
+        break;
+      case 'linux':
+        await this.execute('systemctl', ['--user', 'start', SYSTEMD_UNIT]);
+        break;
+      default:
+        throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Unsupported service platform: ${this.platform}`);
+    }
+    return this.status();
+  }
+
+  async #launchdLoaded() {
+    try {
+      await this.execute('/bin/launchctl', ['print', `gui/${this.uid}/${LABEL}`]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // launchd tears a booted-out service down asynchronously, so bootstrap and
+  // kickstart can fail briefly (codes 5 and 37) right after `pulse stop`.
+  async #startLaunchd() {
+    const target = `gui/${this.uid}/${LABEL}`;
+    let lastError = null;
+    for (let attempt = 0; attempt < START_ATTEMPTS; attempt += 1) {
+      if (attempt > 0) await this.wait(START_RETRY_MS * attempt);
+      try {
+        if (await this.#launchdLoaded()) {
+          await this.execute('/bin/launchctl', ['kickstart', '-k', target]);
+        } else {
+          await this.execute('/bin/launchctl', ['bootstrap', `gui/${this.uid}`, this.serviceFile()]);
+          await this.execute('/bin/launchctl', ['kickstart', target]);
+        }
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw new HubError('HUB_SERVICE_START_FAILED', 'launchd could not start Pulse; run `agentpulse pulse install`, then `agentpulse pulse start`', {
+      cause: lastError,
+      details: { stderr: String(lastError?.stderr || lastError?.message || '').trim().slice(0, 300) },
+    });
+  }
+
+  async status() {
+    switch (this.platform) {
+      case 'darwin': {
+        try {
+          const result = await this.execute('/bin/launchctl', [
+            'print',
+            `gui/${this.uid}/${LABEL}`,
+          ]);
+          const pid = Number(result.stdout.match(/\bpid\s*=\s*(\d+)/)?.[1]) || null;
+          const state = result.stdout.match(/\bstate\s*=\s*(\w+)/)?.[1] || (pid ? 'running' : 'loaded');
+          return { state, pid, serviceFile: this.serviceFile() };
+        } catch {
+          return { state: 'stopped', pid: null, serviceFile: this.serviceFile() };
+        }
+      }
+      case 'linux': {
+        try {
+          const result = await this.execute('systemctl', [
+            '--user',
+            'show',
+            SYSTEMD_UNIT,
+            '--property',
+            'ActiveState',
+            '--property',
+            'MainPID',
+          ]);
+          const active = result.stdout.match(/^ActiveState=(.+)$/m)?.[1] || 'unknown';
+          const pid = Number(result.stdout.match(/^MainPID=(\d+)$/m)?.[1]) || null;
+          return {
+            state: active === 'active' ? 'running' : active,
+            pid,
+            serviceFile: this.serviceFile(),
+          };
+        } catch {
+          return { state: 'stopped', pid: null, serviceFile: this.serviceFile() };
+        }
+      }
+      default:
+        throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Unsupported service platform: ${this.platform}`);
+    }
+  }
+
+  async stop() {
+    switch (this.platform) {
+      case 'darwin':
+        try {
+          await this.execute('/bin/launchctl', ['bootout', `gui/${this.uid}/${LABEL}`]);
+        } catch (error) {
+          const detail = `${error.message || ''}\n${error.stderr || ''}`;
+          if (!ABSENT_SERVICE.test(detail)) {
+            throw new HubError('HUB_SERVICE_STOP_FAILED', 'launchd could not stop Pulse', {
+              cause: error,
+            });
+          }
+        }
+        break;
+      case 'linux':
+        try {
+          await this.execute('systemctl', ['--user', 'stop', SYSTEMD_UNIT]);
+        } catch (error) {
+          const detail = `${error.message || ''}\n${error.stderr || ''}`;
+          if (!ABSENT_SERVICE.test(detail)) {
+            throw new HubError('HUB_SERVICE_STOP_FAILED', 'systemd could not stop Pulse', {
+              cause: error,
+            });
+          }
+        }
+        break;
+      default:
+        throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Unsupported service platform: ${this.platform}`);
+    }
+    return { state: 'stopped', pid: null, serviceFile: this.serviceFile() };
+  }
+
+  /**
+   * Another LaunchAgent of this machine, by label (the old local hub, its keep-awake helper), for cutover and
+   * rollback. macOS only; every call goes through the injected executor.
+   */
+  #requireLaunchd(label) {
+    if (this.platform !== 'darwin') throw new HubError('HUB_UNSUPPORTED_PLATFORM', `${label} is a macOS LaunchAgent`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/.test(label)) throw new HubError('HUB_SERVICE_LABEL_INVALID', `Bad LaunchAgent label: ${label}`);
+    return `gui/${this.uid}/${label}`;
+  }
+
+  plistFor(label) {
+    this.#requireLaunchd(label);
+    return path.join(this.launchAgentsDir, `${label}.plist`);
+  }
+
+  /** `{ loaded, pid, plist }` for a LaunchAgent label. */
+  async labelState(label) {
+    const target = this.#requireLaunchd(label);
+    const plist = this.plistFor(label);
+    try {
+      const result = await this.execute('/bin/launchctl', ['print', target]);
+      return { loaded: true, pid: Number(result.stdout.match(/\bpid\s*=\s*(\d+)/)?.[1]) || null, plist, installed: await exists(plist) };
+    } catch {
+      return { loaded: false, pid: null, plist, installed: await exists(plist) };
+    }
+  }
+
+  /** Unload a LaunchAgent and keep it from loading again at login (`disable`), until `restoreLabel`. */
+  async retireLabel(label) {
+    const target = this.#requireLaunchd(label);
+    try {
+      await this.execute('/bin/launchctl', ['bootout', target]);
+    } catch (error) {
+      if (!ABSENT_SERVICE.test(`${error.message || ''}\n${error.stderr || ''}`)) {
+        throw new HubError('HUB_SERVICE_STOP_FAILED', `launchd could not unload ${label}`, { cause: error });
+      }
+    }
+    await this.execute('/bin/launchctl', ['disable', target]);
+    return this.labelState(label);
+  }
+
+  /** Undo `retireLabel`: enable the label again and load its plist. */
+  async restoreLabel(label) {
+    const target = this.#requireLaunchd(label);
+    await this.execute('/bin/launchctl', ['enable', target]);
+    let lastError = null;
+    for (let attempt = 0; attempt < START_ATTEMPTS; attempt += 1) {
+      if (attempt > 0) await this.wait(START_RETRY_MS * attempt);
+      if ((await this.labelState(label)).loaded) return this.labelState(label);
+      try {
+        await this.execute('/bin/launchctl', ['bootstrap', `gui/${this.uid}`, this.plistFor(label)]);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if ((await this.labelState(label)).loaded) return this.labelState(label);
+    throw new HubError('HUB_SERVICE_START_FAILED', `launchd could not load ${label}`, { cause: lastError });
+  }
+
+  async health({ freshMs = 30_000, after = 0 } = {}) {
+    const health = await readOwnerOnlyJson(path.join(this.configDir, 'daemon-health.json'));
+    const heartbeat = Date.parse(health?.heartbeatAt);
+    return {
+      ok: Boolean(
+        health &&
+        Number.isFinite(heartbeat) &&
+        heartbeat >= after &&
+        Date.now() - heartbeat <= freshMs
+      ),
+      health,
+    };
+  }
+}