@xpufx/paseo-x-comms 0.3.0

package/server/vendor/paseo-plugin-helper/process.ts

@@ -0,0 +1,186 @@
+import { spawn, type SpawnOptions } from "node:child_process";
+
+export interface SafeSpawnOptions extends SpawnOptions {
+  timeoutMs?: number;
+  maxBuffer?: number;
+}
+
+/**
+ * Kills a spawned child together with everything it started. Plain
+ * child.kill() only signals the direct child, so grandchildren (df, git
+ * helpers, shell pipelines) orphan and accumulate. Negative-pid kill targets
+ * the whole process group, which requires the child to lead its own group
+ * (detached spawn, POSIX only).
+ */
+function killProcessGroup(
+  child: ReturnType<typeof spawn>,
+  signal: NodeJS.Signals,
+): void {
+  try {
+    if (
+      process.platform !== "win32" &&
+      child.pid !== undefined
+    ) {
+      process.kill(-child.pid, signal);
+      return;
+    }
+  } catch {
+    // Group kill missed (already gone or no permission); fall through.
+  }
+  try {
+    child.kill(signal);
+  } catch {
+    // Already gone.
+  }
+}
+
+export interface SafeSpawnResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  durationMs: number;
+}
+
+/**
+ * Spawns a process safely with timeout management, stdout/stderr capture,
+ * and clean process group termination without shell vulnerabilities.
+ */
+export function safeSpawn(
+  command: string,
+  args: string[] = [],
+  options: SafeSpawnOptions = {},
+): Promise<SafeSpawnResult> {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const timeoutMs = options.timeoutMs ?? 15000;
+    const maxBuffer = options.maxBuffer ?? 10 * 1024 * 1024; // 10MB
+
+    const child = spawn(command, args, {
+      ...options,
+      shell: false,
+      detached: options.detached ?? process.platform !== "win32",
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let exited = false;
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        killProcessGroup(child, "SIGTERM");
+        setTimeout(() => {
+          if (!exited) killProcessGroup(child, "SIGKILL");
+        }, 2000);
+      }, timeoutMs);
+    }
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      if (stdout.length < maxBuffer) {
+        stdout += chunk.toString();
+      }
+    });
+
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      if (stderr.length < maxBuffer) {
+        stderr += chunk.toString();
+      }
+    });
+
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+
+    child.on("close", (code, signal) => {
+      exited = true;
+      if (timer) clearTimeout(timer);
+      const durationMs = Date.now() - startTime;
+      if (timedOut) {
+        reject(new Error(`Command '${command}' timed out after ${timeoutMs}ms`));
+        return;
+      }
+      resolve({
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        code,
+        signal,
+        durationMs,
+      });
+    });
+  });
+}
+
+/**
+ * Executes a shell command line string with timeout protection, stdout/stderr capture,
+ * and clean process termination.
+ */
+export function safeExec(
+  command: string,
+  options: SafeSpawnOptions = {},
+): Promise<SafeSpawnResult> {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const timeoutMs = options.timeoutMs ?? 15000;
+    const maxBuffer = options.maxBuffer ?? 10 * 1024 * 1024; // 10MB
+
+    const child = spawn(command, {
+      ...options,
+      shell: true,
+      detached: options.detached ?? process.platform !== "win32",
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let exited = false;
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        killProcessGroup(child, "SIGTERM");
+        setTimeout(() => {
+          if (!exited) killProcessGroup(child, "SIGKILL");
+        }, 2000);
+      }, timeoutMs);
+    }
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      if (stdout.length < maxBuffer) {
+        stdout += chunk.toString();
+      }
+    });
+
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      if (stderr.length < maxBuffer) {
+        stderr += chunk.toString();
+      }
+    });
+
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      reject(err);
+    });
+
+    child.on("close", (code, signal) => {
+      exited = true;
+      if (timer) clearTimeout(timer);
+      const durationMs = Date.now() - startTime;
+      if (timedOut) {
+        reject(new Error(`Command '${command}' timed out after ${timeoutMs}ms`));
+        return;
+      }
+      resolve({
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        code,
+        signal,
+        durationMs,
+      });
+    });
+  });
+}

package/server/vendor/paseo-plugin-helper/redact.ts

@@ -0,0 +1,86 @@
+export interface RedactOptions {
+  mask?: string;
+  customSensitiveKeys?: string[];
+  preserveLength?: boolean;
+}
+
+const DEFAULT_SENSITIVE_KEYS = [
+  "password",
+  "passwd",
+  "secret",
+  "token",
+  "apikey",
+  "api_key",
+  "access_token",
+  "refresh_token",
+  "privatekey",
+  "private_key",
+  "authorization",
+  "auth",
+  "credential",
+  "credentials",
+  "cert",
+  "certificate",
+];
+
+function isSensitiveKey(key: string, customKeys: string[] = []): boolean {
+  const normalized = key.toLowerCase().replace(/[-_]/g, "");
+  return [...DEFAULT_SENSITIVE_KEYS, ...customKeys].some((k) =>
+    normalized.includes(k.replace(/[-_]/g, "")),
+  );
+}
+
+function maskString(val: string, mask = "[REDACTED]"): string {
+  if (val.length <= 8) return mask;
+  // Keep first 3 and last 3 characters if long enough, using custom mask if provided
+  const placeholder = mask === "[REDACTED]" ? "..." : mask;
+  return `${val.slice(0, 3)}${placeholder}${val.slice(-3)}`;
+}
+
+/**
+ * Deeply redacts sensitive keys and values in an object or primitive before logging or sending over RPC.
+ */
+export function redactSecrets<T>(target: T, options: RedactOptions = {}): T {
+  const mask = options.mask ?? "[REDACTED]";
+  const customKeys = options.customSensitiveKeys ?? [];
+
+  if (target === null || target === undefined) return target;
+
+  if (typeof target === "string") {
+    // Redact Bearer tokens in headers
+    let result = target.replace(/(Bearer\s+)[A-Za-z0-9\-._~+/]+=*/gi, `$1${mask}`);
+    // Redact basic auth in URLs
+    result = result.replace(/(https?:\/\/[^:]+:)[^@]+(@)/gi, `$1${mask}$2`);
+    // Redact Paseo pairing offers (password-equivalent): app.paseo.sh/#offer=
+    // plus the base64 tail, optionally JSON-sniffed by serverId key below.
+    // Tail covers standard (+/=) and URL-safe (-_) base64 so partial
+    // offers never leak through a truncated match.
+    result = result.replace(
+      /(https?:\/\/app\.paseo\.sh\/#offer=)[A-Za-z0-9\-_.~+/]+=*/gi,
+      `$1${mask}`,
+    );
+    return result as unknown as T;
+  }
+
+  if (Array.isArray(target)) {
+    return target.map((item) => redactSecrets(item, options)) as unknown as T;
+  }
+
+  if (typeof target === "object") {
+    const clone: Record<string, any> = {};
+    for (const [key, value] of Object.entries(target)) {
+      if (isSensitiveKey(key, customKeys)) {
+        clone[key] = typeof value === "string" ? maskString(value, mask) : mask;
+      } else if (typeof value === "object" && value !== null) {
+        clone[key] = redactSecrets(value, options);
+      } else if (typeof value === "string") {
+        clone[key] = redactSecrets(value, options);
+      } else {
+        clone[key] = value;
+      }
+    }
+    return clone as T;
+  }
+
+  return target;
+}

package/server/vendor/paseo-plugin-helper/rpc-guard.ts

@@ -0,0 +1,77 @@
+import { withTimeout, TimeoutError } from "../../../shared/vendor/paseo-plugin-helper/async";
+
+export interface RpcGuardOptions<T> {
+  timeoutMs?: number;
+  maxInflight?: number;
+  getStale?: () => T | null | undefined;
+  onTimeout?: (info: { timeoutMs: number; inflight: number }) => void;
+  onSaturated?: (info: { maxInflight: number }) => void;
+}
+
+export interface GuardedRpcHandler<TInput, TOutput> {
+  (input?: TInput): Promise<TOutput>;
+  inflight(): number;
+}
+
+export function guardRpcHandler<TInput, TOutput>(
+  handler: (input?: TInput) => Promise<TOutput> | TOutput,
+  options: RpcGuardOptions<TOutput> = {},
+): GuardedRpcHandler<TInput, TOutput> {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const maxInflight = options.maxInflight ?? 4;
+  let inflight = 0;
+
+  const guarded = (async (input?: TInput): Promise<TOutput> => {
+    if (inflight >= maxInflight) {
+      options.onSaturated?.({ maxInflight });
+      const stale = options.getStale?.();
+      if (stale != null) {
+        return stale;
+      }
+      throw new Error(
+        `RPC handler saturated (${inflight} inflight, cap ${maxInflight}): shedding load`,
+      );
+    }
+    inflight += 1;
+    try {
+      return await withTimeout(
+        Promise.resolve().then(() => handler(input)),
+        timeoutMs,
+        "RPC handler",
+      );
+    } catch (err) {
+      if (err instanceof TimeoutError) {
+        options.onTimeout?.({ timeoutMs, inflight });
+      }
+      throw err;
+    } finally {
+      inflight -= 1;
+    }
+  }) as GuardedRpcHandler<TInput, TOutput>;
+  guarded.inflight = () => inflight;
+  return guarded;
+}
+
+export interface LoopWatchdogOptions {
+  thresholdMs?: number;
+  intervalMs?: number;
+  onLag?: (lagMs: number) => void;
+}
+
+export function createLoopWatchdog(options: LoopWatchdogOptions = {}): () => void {
+  const thresholdMs = options.thresholdMs ?? 1000;
+  const intervalMs = options.intervalMs ?? 1000;
+  let last = Date.now();
+  const timer = setInterval(() => {
+    const now = Date.now();
+    const lagMs = now - last - intervalMs;
+    last = now;
+    if (lagMs >= thresholdMs) {
+      options.onLag?.(lagMs);
+    }
+  }, intervalMs);
+  if (typeof (timer as unknown as { unref?: unknown }).unref === "function") {
+    (timer as unknown as { unref: () => void }).unref();
+  }
+  return () => clearInterval(timer);
+}

package/server/vendor/paseo-plugin-helper/settings.ts

@@ -0,0 +1,97 @@
+import type { SettingsContract } from "../../../shared/vendor/paseo-plugin-helper/settings";
+import type { PluginStorage } from "./storage";
+
+/**
+ * Structural server context interface satisfied by both Paseo v0.7 PluginContext
+ * and Paseo v0.8 PluginServerContext.
+ */
+export interface HandleableServerContext {
+  handle(contract: any, handler: (input?: any) => any): any;
+}
+
+export interface RegisterSettingsRpcOptions<TSettings> {
+  /**
+   * Optional callback invoked whenever settings are updated.
+   */
+  onUpdate?: (newSettings: TSettings, prevSettings: TSettings) => void | Promise<void>;
+  /**
+   * Optional callback invoked whenever settings are reset.
+   */
+  onReset?: (defaultSettings: TSettings, prevSettings: TSettings) => void | Promise<void>;
+}
+
+/**
+ * Registers RPC handlers on the daemon PluginContext/PluginServerContext for a SettingsContract.
+ * Connects get, update, and reset RPCs directly to atomic PluginStorage persistence.
+ * Works with both Paseo v0.7 and Paseo v0.8.
+ */
+export function registerSettingsRpc<TSettings extends Record<string, any>>(
+  context: HandleableServerContext,
+  contract: SettingsContract<TSettings>,
+  storage: PluginStorage<TSettings>,
+  options: RegisterSettingsRpcOptions<TSettings> = {},
+): void {
+  // Register GET handler
+  context.handle(contract.get, async () => {
+    return storage.readAsync();
+  });
+
+  // Register UPDATE handler
+  context.handle(contract.update, async (input) => {
+    const prev = await storage.readAsync();
+    const updated = await storage.updateAsync((current) => {
+      return { ...current, ...(input as Partial<TSettings>) };
+    });
+    if (options.onUpdate) {
+      await options.onUpdate(updated, prev);
+    }
+    return updated;
+  });
+
+  // Register RESET handler
+  context.handle(contract.reset, async () => {
+    const prev = await storage.readAsync();
+    storage.reset();
+    const fresh = await storage.readAsync();
+    if (options.onReset) {
+      await options.onReset(fresh, prev);
+    }
+    return fresh;
+  });
+}
+
+/**
+ * Creates individual RPC handler functions (get, update, reset) for a SettingsContract.
+ * Useful when registering handlers in root index.ts via plugin.handle() so that
+ * Paseo's AST-based client compiler can cleanly strip all server registrations.
+ */
+export function createSettingsHandlers<TSettings extends Record<string, any>>(
+  contract: SettingsContract<TSettings>,
+  storage: PluginStorage<TSettings>,
+  options: RegisterSettingsRpcOptions<TSettings> = {},
+) {
+  return {
+    get: async () => {
+      return storage.readAsync();
+    },
+    update: async (input: unknown) => {
+      const prev = await storage.readAsync();
+      const updated = await storage.updateAsync((current) => {
+        return { ...current, ...(input as Partial<TSettings>) };
+      });
+      if (options.onUpdate) {
+        await options.onUpdate(updated, prev);
+      }
+      return updated;
+    },
+    reset: async () => {
+      const prev = await storage.readAsync();
+      storage.reset();
+      const fresh = await storage.readAsync();
+      if (options.onReset) {
+        await options.onReset(fresh, prev);
+      }
+      return fresh;
+    },
+  };
+}

package/server/vendor/paseo-plugin-helper/shared-settings.ts

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ZodType } from "zod";
+import { defineSettingsContract, type SettingsContract } from "../../../shared/vendor/paseo-plugin-helper/settings";
+import { PluginStorage } from "./storage";
+import {
+  createSettingsHandlers,
+  registerSettingsRpc,
+  type HandleableServerContext,
+  type RegisterSettingsRpcOptions,
+} from "./settings";
+
+export interface SharedPluginSettingsOptions<TSettings extends Record<string, any>> {
+  suite: string;
+  filename?: string;
+  schema: ZodType<TSettings> & { partial?: () => ZodType<Partial<TSettings>> };
+  defaultData?: Partial<TSettings>;
+  contract?: SettingsContract<TSettings>;
+  contractName?: string;
+  description?: string;
+  namespace?: string;
+  baseDir?: string;
+  watchDebounceMs?: number;
+}
+
+export type SharedSettingsListener<TSettings> = (settings: TSettings) => void;
+
+export interface SharedPluginSettings<TSettings extends Record<string, any>> {
+  readonly suite: string;
+  readonly contract: SettingsContract<TSettings>;
+  readonly storage: PluginStorage<TSettings>;
+  readonly filePath: string;
+  get(): Promise<TSettings>;
+  update(patch: Partial<TSettings>): Promise<TSettings>;
+  reset(): Promise<TSettings>;
+  read(): TSettings;
+  reload(): TSettings;
+  subscribe(listener: SharedSettingsListener<TSettings>): () => void;
+  watch(listener: SharedSettingsListener<TSettings>): () => void;
+  register(
+    context: HandleableServerContext,
+    options?: RegisterSettingsRpcOptions<TSettings>,
+  ): void;
+  createHandlers(options?: RegisterSettingsRpcOptions<TSettings>): {
+    get: () => Promise<TSettings>;
+    update: (input: unknown) => Promise<TSettings>;
+    reset: () => Promise<TSettings>;
+  };
+  dispose(): void;
+}
+
+function safeSerialize(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Creates a suite-scoped settings store shared across independent sibling plugins.
+ * Every plugin in the suite points at the same file
+ * (`~/.paseo/plugin-data/xpufx/<suite>/<filename>`) through an atomic PluginStorage,
+ * so an update written by Plugin A is immediately readable by Plugin B.
+ */
+export function createSharedPluginSettings<TSettings extends Record<string, any>>(
+  options: SharedPluginSettingsOptions<TSettings>,
+): SharedPluginSettings<TSettings> {
+  const {
+    suite,
+    filename = "settings.json",
+    schema,
+    defaultData,
+    description,
+    namespace,
+    baseDir,
+    watchDebounceMs = 25,
+  } = options;
+  const contractName = options.contractName ?? `${suite}.shared-settings`;
+
+  const contract =
+    options.contract ??
+    defineSettingsContract({
+      name: contractName,
+      schema,
+      ...(defaultData !== undefined ? { defaultData } : {}),
+      ...(description !== undefined ? { description } : {}),
+    });
+
+  const storage = new PluginStorage<TSettings>(suite, filename, {
+    ...(namespace !== undefined ? { namespace } : {}),
+    ...(baseDir !== undefined ? { baseDir } : {}),
+    schema: contract.schema,
+    defaultData: contract.defaultSettings,
+  });
+
+  const listeners = new Set<SharedSettingsListener<TSettings>>();
+  let watcher: fs.FSWatcher | null = null;
+  let debounceTimer: NodeJS.Timeout | null = null;
+  let lastSnapshot = "";
+
+  function snapshot(): string {
+    return safeSerialize(storage.read());
+  }
+
+  function emitIfChanged(): void {
+    const next = storage.read();
+    const nextSnapshot = safeSerialize(next);
+    if (nextSnapshot !== lastSnapshot) {
+      lastSnapshot = nextSnapshot;
+      for (const listener of [...listeners]) {
+        try {
+          listener(next);
+        } catch {
+          // Listener errors must not break sibling notification fan-out
+        }
+      }
+    }
+  }
+
+  function scheduleEmit(): void {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    // @ts-ignore
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      try {
+        emitIfChanged();
+      } catch {
+        // Disk reads may race atomic renames; next event retries
+      }
+    }, watchDebounceMs);
+  }
+
+  function ensureWatcher(): void {
+    if (watcher) return;
+    const dir = path.dirname(storage.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    lastSnapshot = snapshot();
+    watcher = fs.watch(dir, (_event, watchedFile) => {
+      if (watchedFile && watchedFile.toString() !== path.basename(storage.filePath)) return;
+      scheduleEmit();
+    });
+    watcher.on("error", () => {});
+    if (typeof (watcher as unknown as { unref?: () => void }).unref === "function") {
+      (watcher as unknown as { unref: () => void }).unref();
+    }
+  }
+
+  function disposeWatcher(): void {
+    if (debounceTimer) {
+// @ts-ignore
+    clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    if (watcher) {
+      try {
+        watcher.close();
+      } catch {}
+      watcher = null;
+    }
+  }
+
+  function subscribe(listener: SharedSettingsListener<TSettings>): () => void {
+    listeners.add(listener);
+    try {
+      ensureWatcher();
+    } catch {
+      // Watching is best-effort; polling via reload() still works
+    }
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size === 0) disposeWatcher();
+    };
+  }
+
+  return {
+    suite,
+    contract,
+    storage,
+    filePath: storage.filePath,
+
+    async get(): Promise<TSettings> {
+      return storage.readAsync();
+    },
+
+    async update(patch: Partial<TSettings>): Promise<TSettings> {
+      const updated = await storage.updateAsync((current) => ({
+        ...current,
+        ...patch,
+      }));
+      lastSnapshot = safeSerialize(updated);
+      for (const listener of [...listeners]) {
+        try {
+          listener(updated);
+        } catch {}
+      }
+      return updated;
+    },
+
+    async reset(): Promise<TSettings> {
+      storage.reset();
+      const fresh = await storage.readAsync();
+      lastSnapshot = safeSerialize(fresh);
+      for (const listener of [...listeners]) {
+        try {
+          listener(fresh);
+        } catch {}
+      }
+      return fresh;
+    },
+
+    read(): TSettings {
+      return storage.read();
+    },
+
+    reload(): TSettings {
+      const next = storage.read();
+      lastSnapshot = safeSerialize(next);
+      return next;
+    },
+
+    subscribe,
+    watch: subscribe,
+
+    register(
+      context: HandleableServerContext,
+      rpcOptions: RegisterSettingsRpcOptions<TSettings> = {},
+    ): void {
+      registerSettingsRpc(context, contract, storage, rpcOptions);
+    },
+
+    createHandlers(rpcOptions: RegisterSettingsRpcOptions<TSettings> = {}) {
+      return createSettingsHandlers(contract, storage, rpcOptions);
+    },
+
+    dispose(): void {
+      listeners.clear();
+      disposeWatcher();
+    },
+  };
+}