@agentpulselabs/cli-plugin-pulse 0.1.0 → 1.0.0

package/src/lib/secretStore.js

@@ -0,0 +1,169 @@
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import { HubError } from './errors.js';
+import { spawnBounded } from './subprocess.js';
+
+const SERVICE = 'com.agentpulse.hub';
+/** A Keychain or libsecret call normally takes well under a second; one that hangs (a locked keychain) is killed. */
+export const SECRET_COMMAND_TIMEOUT_MS = 10_000;
+
+/** What a secret-command error may carry: the command's output can be a secret, so only how it ended. */
+const exitOnly = ({ code, signal }) => ({ code, signal });
+
+export async function runSecretCommand(bin, args, { input = '', env = process.env, timeoutMs = SECRET_COMMAND_TIMEOUT_MS } = {}) {
+  let result;
+  try {
+    result = await spawnBounded(bin, args, {
+      input,
+      env,
+      timeoutMs,
+      onTimeout: () => new HubError('HUB_SECRET_STORE_TIMEOUT', `${bin} did not answer within ${timeoutMs} ms and was stopped`),
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new HubError(
+        'HUB_SECRET_STORE_UNAVAILABLE',
+        `${bin} is not installed; Pulse stores sign-in and keys only in the OS keychain (install libsecret's secret-tool on Linux)`,
+        { cause: error },
+      );
+    }
+    if (error.result) error.result = exitOnly(error.result);
+    throw error;
+  }
+  if (result.code === 0) return result;
+  const error = new HubError('HUB_SECRET_STORE_FAILED', `${bin} failed with exit ${result.code}`);
+  error.result = exitOnly(result);
+  throw error;
+}
+
+const SECURITY = '/usr/bin/security';
+const CHUNKED_PREFIX = 'b64chunks:';
+const CHUNK_CHARACTERS = 1024;
+const KEYCHAIN_NAME = /^[A-Za-z0-9._@-]+$/;
+
+export class KeychainSecretStore {
+  constructor({ execute = runSecretCommand, account = os.userInfo().username } = {}) {
+    if (!KEYCHAIN_NAME.test(account)) {
+      throw new HubError('HUB_SECRET_STORE_UNAVAILABLE', 'The macOS account name cannot be used as a Keychain account');
+    }
+    this.execute = execute;
+    this.account = account;
+  }
+
+  #service(reference) {
+    const service = `${SERVICE}.${reference}`;
+    if (!KEYCHAIN_NAME.test(service)) throw new HubError('HUB_SECRET_STORE_FAILED', 'Invalid Keychain item name');
+    return service;
+  }
+
+  async #find(service) {
+    try {
+      const result = await this.execute(SECURITY, ['find-generic-password', '-a', this.account, '-s', service, '-w']);
+      return result.stdout.replace(/\n$/, '');
+    } catch (error) {
+      if (error.result?.code === 44) return null;
+      throw error;
+    }
+  }
+
+  async #remove(service) {
+    try {
+      await this.execute(SECURITY, ['delete-generic-password', '-a', this.account, '-s', service]);
+    } catch (error) {
+      if (error.result?.code !== 44) throw error;
+    }
+  }
+
+  async #write(entries) {
+    const lines = entries.map(([service, data]) => `add-generic-password -U -a "${this.account}" -s "${service}" -w ${data}`);
+    await this.execute(SECURITY, ['-i'], { input: `${lines.join('\n')}\n` });
+  }
+
+  static #parts(service, header) {
+    if (!header?.startsWith(CHUNKED_PREFIX)) return null;
+    const [generation, count] = header.slice(CHUNKED_PREFIX.length).split(':');
+    return Array.from({ length: Number(count) || 0 }, (_unused, index) => `${service}.${generation}.${index}`);
+  }
+
+  async get(reference) {
+    const service = this.#service(reference);
+    const header = await this.#find(service);
+    const parts = KeychainSecretStore.#parts(service, header);
+    if (!parts) return header;
+    const chunks = [];
+    for (const part of parts) {
+      const chunk = await this.#find(part);
+      if (chunk === null) throw new HubError('HUB_SECRET_STORE_CORRUPT', 'A Keychain secret is incomplete');
+      chunks.push(chunk);
+    }
+    return Buffer.from(chunks.join(''), 'base64').toString('utf8');
+  }
+
+  async set(reference, value) {
+    const service = this.#service(reference);
+    const previous = KeychainSecretStore.#parts(service, await this.#find(service)) || [];
+    const encoded = Buffer.from(String(value), 'utf8').toString('base64');
+    const chunks = encoded.match(new RegExp(`.{1,${CHUNK_CHARACTERS}}`, 'g')) || [];
+    const generation = randomBytes(6).toString('hex');
+    if (chunks.length) {
+      await this.#write(chunks.map((chunk, index) => [`${service}.${generation}.${index}`, chunk]));
+    }
+    await this.#write([[service, `${CHUNKED_PREFIX}${generation}:${chunks.length}`]]);
+    if ((await this.get(reference)) !== String(value)) {
+      throw new HubError('HUB_SECRET_STORE_FAILED', 'The Keychain did not store the secret intact');
+    }
+    for (const part of previous) await this.#remove(part);
+  }
+
+  async delete(reference) {
+    const service = this.#service(reference);
+    const parts = KeychainSecretStore.#parts(service, await this.#find(service)) || [];
+    await this.#remove(service);
+    for (const part of parts) await this.#remove(part);
+  }
+}
+
+export class LibsecretStore {
+  constructor({ execute = runSecretCommand } = {}) {
+    this.execute = execute;
+  }
+
+  async get(reference) {
+    try {
+      const result = await this.execute('secret-tool', [
+        'lookup',
+        'service',
+        SERVICE,
+        'reference',
+        reference,
+      ]);
+      return result.stdout.replace(/\n$/, '');
+    } catch (error) {
+      if (error.result?.code === 1) return null;
+      throw error;
+    }
+  }
+
+  async set(reference, value) {
+    await this.execute(
+      'secret-tool',
+      ['store', '--label', 'AgentPulse Pulse connector', 'service', SERVICE, 'reference', reference],
+      { input: String(value) }
+    );
+  }
+
+  async delete(reference) {
+    await this.execute('secret-tool', ['clear', 'service', SERVICE, 'reference', reference]);
+  }
+}
+
+export function defaultSecretStore(platform = process.platform) {
+  switch (platform) {
+    case 'darwin':
+      return new KeychainSecretStore();
+    case 'linux':
+      return new LibsecretStore();
+    default:
+      throw new HubError('HUB_UNSUPPORTED_PLATFORM', `Pulse supports macOS and Linux, not ${platform}`);
+  }
+}

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,
+      });
+    }
+  }
+}