@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/serviceManager.js

@@ -0,0 +1,358 @@
+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,
+  }) {
+    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;
+  }
+
+  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() };
+  }
+
+  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,
+    };
+  }
+}

package/src/lib/storage.js

@@ -0,0 +1,131 @@
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+} from 'node:fs/promises';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { HubError } from './errors.js';
+
+export async function ensureOwnerOnlyDirectory(directory) {
+  const absolute = path.resolve(directory);
+  const root = path.parse(absolute).root;
+  const components = absolute.slice(root.length).split(path.sep).filter(Boolean);
+  let current = root;
+  let ownerAnchorReached = false;
+  for (const component of components) {
+    current = path.join(current, component);
+    try {
+      const componentInfo = await lstat(current);
+      if (componentInfo.isSymbolicLink()) {
+        if (ownerAnchorReached || current === absolute) {
+          throw new HubError('HUB_UNSAFE_STORAGE', `Storage ancestor is a symlink: ${current}`);
+        }
+        continue;
+      }
+      if (!componentInfo.isDirectory()) {
+        throw new HubError('HUB_UNSAFE_STORAGE', `Storage ancestor is not a directory: ${current}`);
+      }
+      if (typeof process.getuid === 'function' && componentInfo.uid === process.getuid()) {
+        ownerAnchorReached = true;
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await mkdir(current, { mode: 0o700 });
+      ownerAnchorReached = true;
+    }
+  }
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new HubError('HUB_UNSAFE_STORAGE', `Storage path is not a real directory: ${directory}`);
+  }
+  if (typeof process.getuid === 'function' && info.uid !== process.getuid()) {
+    throw new HubError('HUB_STORAGE_NOT_OWNED', `Storage path is not owned by the current user: ${directory}`);
+  }
+  await chmod(directory, 0o700);
+  return directory;
+}
+
+export async function assertOwnerOnlyFile(file) {
+  const info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink()) {
+    throw new HubError('HUB_UNSAFE_STORAGE', `Storage path is not a regular file: ${file}`);
+  }
+  if (typeof process.getuid === 'function' && info.uid !== process.getuid()) {
+    throw new HubError('HUB_STORAGE_NOT_OWNED', `Storage file is not owned by the current user: ${file}`);
+  }
+  if ((info.mode & 0o077) !== 0) {
+    throw new HubError('HUB_STORAGE_PERMISSIONS', `Storage file must be owner-only: ${file}`);
+  }
+}
+
+export async function writeOwnerOnlyJson(file, value) {
+  return writeOwnerOnlyText(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function writeOwnerOnlyText(file, value) {
+  const directory = path.dirname(file);
+  await ensureOwnerOnlyDirectory(directory);
+  try {
+    const existing = await lstat(file);
+    if (existing.isSymbolicLink()) {
+      throw new HubError('HUB_UNSAFE_STORAGE', `Refusing to replace symlink: ${file}`);
+    }
+    if (!existing.isFile()) {
+      throw new HubError('HUB_UNSAFE_STORAGE', `Refusing to replace non-file storage: ${file}`);
+    }
+    if (typeof process.getuid === 'function' && existing.uid !== process.getuid()) {
+      throw new HubError('HUB_STORAGE_NOT_OWNED', `Storage file is not owned by the current user: ${file}`);
+    }
+    if ((existing.mode & 0o077) !== 0) {
+      throw new HubError('HUB_STORAGE_PERMISSIONS', `Storage file must already be owner-only: ${file}`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const temporary = path.join(
+    directory,
+    `.${path.basename(file)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`
+  );
+  const handle = await open(temporary, 'wx', 0o600);
+  try {
+    await handle.writeFile(String(value), 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    await rename(temporary, file);
+    await chmod(file, 0o600);
+    try {
+      const directoryHandle = await open(directory, 'r');
+      try {
+        await directoryHandle.sync();
+      } finally {
+        await directoryHandle.close();
+      }
+    } catch {
+      // Some filesystems do not support directory fsync; the atomic rename still applies.
+    }
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+export async function readOwnerOnlyJson(file, fallback = null) {
+  try {
+    await assertOwnerOnlyFile(file);
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    if (error instanceof SyntaxError) {
+      throw new HubError('HUB_INVALID_CONFIG', `Invalid JSON in ${file}`, { cause: error });
+    }
+    throw error;
+  }
+}

package/src/lib/subprocess.js

@@ -0,0 +1,45 @@
+import { execFile as execFileCallback, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+
+export const SUBPROCESS_TIMEOUT_MS = 30_000;
+
+const execFileAsync = promisify(execFileCallback);
+const bounded = (ms, fallback) => (Number.isFinite(ms) && ms > 0 ? ms : fallback);
+
+/** execFile that always ends: past its timeout (never unbounded, not even with timeout: 0) the child is SIGKILLed. */
+export function execFileBounded(bin, args, { defaultTimeoutMs = SUBPROCESS_TIMEOUT_MS, ...options } = {}) {
+  return execFileAsync(bin, args, { ...options, timeout: bounded(options.timeout, defaultTimeoutMs), killSignal: 'SIGKILL' });
+}
+
+/**
+ * Runs bin with input on stdin and resolves { code, signal, stdout, stderr } when it exits. Past timeoutMs the child
+ * is SIGKILLed and the promise rejects with onTimeout(result), so a hung tool never holds its caller.
+ */
+export function spawnBounded(bin, args, {
+  input = '', env = process.env, timeoutMs = SUBPROCESS_TIMEOUT_MS, onTimeout = () => Object.assign(new Error(`${bin} timed out`), { code: 'ETIMEDOUT' }),
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+    const stdout = [];
+    const stderr = [];
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGKILL');
+    }, bounded(timeoutMs, SUBPROCESS_TIMEOUT_MS));
+    child.stdout.on('data', (chunk) => stdout.push(chunk));
+    child.stderr.on('data', (chunk) => stderr.push(chunk));
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      const result = { code, signal, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') };
+      if (timedOut) reject(Object.assign(onTimeout(result), { result }));
+      else resolve(result);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}

package/src/lib/tokenStore.js

@@ -0,0 +1,97 @@
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { acquireOwnerLock } from './ownerLock.js';
+import { ProcessIdentityProvider } from './processOwnership.js';
+import { readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+
+const SECRET_REFERENCE = 'oauth-session';
+const METADATA_FILE = 'oauth-session.json';
+const LOCK_FILE = 'oauth-refresh.lock';
+const inProcessLocks = new Map();
+
+export class TokenStore {
+  constructor({ secretStore, configDir, lockTimeoutMs = 10_000, identityProvider = new ProcessIdentityProvider() }) {
+    this.secretStore = secretStore;
+    this.metadataFile = path.join(configDir, METADATA_FILE);
+    this.lockFile = path.join(configDir, LOCK_FILE);
+    this.lockTimeoutMs = lockTimeoutMs;
+    this.identityProvider = identityProvider;
+  }
+
+  async load() {
+    const metadata = await readOwnerOnlyJson(this.metadataFile);
+    if (!metadata) return null;
+    const secret = await this.secretStore.get(SECRET_REFERENCE);
+    if (!secret) return null;
+    let tokens;
+    try {
+      tokens = JSON.parse(secret);
+    } catch (error) {
+      throw new HubError('HUB_TOKEN_STORE_CORRUPT', 'Stored Pulse sign-in is unreadable; run `agentpulse pulse login`', {
+        cause: error,
+      });
+    }
+    return {
+      platformUrl: metadata.platformUrl,
+      userId: metadata.userId,
+      teamId: metadata.teamId,
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken ?? null,
+      expiresAt: metadata.expiresAt,
+      scopes: metadata.scopes || [],
+    };
+  }
+
+  async scopes() {
+    const metadata = await readOwnerOnlyJson(this.metadataFile);
+    return Array.isArray(metadata?.scopes) ? metadata.scopes : [];
+  }
+
+  async save(session) {
+    if (typeof session?.accessToken !== 'string' || !session.userId || !session.teamId || !session.platformUrl) {
+      throw new HubError('HUB_TOKEN_STORE_INVALID', 'Refusing to store an incomplete Pulse sign-in');
+    }
+    await this.secretStore.set(SECRET_REFERENCE, JSON.stringify({
+      accessToken: session.accessToken,
+      refreshToken: session.refreshToken ?? null,
+    }));
+    await writeOwnerOnlyJson(this.metadataFile, {
+      platformUrl: session.platformUrl,
+      userId: session.userId,
+      teamId: session.teamId,
+      expiresAt: session.expiresAt,
+      scopes: session.scopes || [],
+    });
+  }
+
+  async clear() {
+    await this.secretStore.delete(SECRET_REFERENCE);
+    await rm(this.metadataFile, { force: true });
+  }
+
+  async withRefreshLock(action) {
+    const previous = inProcessLocks.get(this.lockFile) || Promise.resolve();
+    let release;
+    const current = previous.then(() => new Promise((resolve) => { release = resolve; }));
+    inProcessLocks.set(this.lockFile, current);
+    await previous;
+    try {
+      const releaseFile = await acquireOwnerLock({
+        file: this.lockFile,
+        identity: await this.identityProvider.capture(process.pid),
+        identityProvider: this.identityProvider,
+        timeoutMs: this.lockTimeoutMs,
+        heldError: () => new HubError('HUB_REFRESH_LOCKED', 'Another Pulse process is refreshing the sign-in; retry shortly'),
+      });
+      try {
+        return await action();
+      } finally {
+        await releaseFile();
+      }
+    } finally {
+      release();
+      if (inProcessLocks.get(this.lockFile) === current) inProcessLocks.delete(this.lockFile);
+    }
+  }
+}