@xpufx/paseo-forges 0.1.0

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

@@ -0,0 +1,91 @@
+import net from "node:net";
+
+export interface PingHostOptions {
+  timeoutMs?: number;
+}
+
+/**
+ * Checks whether a TCP port is currently open and accepting connections on a host.
+ */
+export function isPortOpen(port: number, host = "127.0.0.1", options?: PingHostOptions): Promise<boolean> {
+  const timeoutMs = options?.timeoutMs ?? 1000;
+
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    const cleanup = () => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+      }
+    };
+
+    socket.setTimeout(timeoutMs);
+
+    socket.once("connect", () => {
+      cleanup();
+      resolve(true);
+    });
+
+    socket.once("timeout", () => {
+      cleanup();
+      resolve(false);
+    });
+
+    socket.once("error", () => {
+      cleanup();
+      resolve(false);
+    });
+
+    try {
+      socket.connect(port, host);
+    } catch {
+      cleanup();
+      resolve(false);
+    }
+  });
+}
+
+/**
+ * Finds an available TCP port starting from startPort.
+ * Tries up to maxAttempts ports.
+ */
+export function findAvailablePort(startPort = 3000, maxAttempts = 50, host = "127.0.0.1"): Promise<number> {
+  return new Promise((resolve, reject) => {
+    let currentPort = startPort;
+    const endPort = startPort + maxAttempts;
+
+    function tryNext() {
+      if (currentPort >= endPort) {
+        return reject(new Error(`No available port found in range [${startPort}, ${endPort})`));
+      }
+
+      const server = net.createServer();
+
+      server.once("error", () => {
+        currentPort++;
+        tryNext();
+      });
+
+      server.once("listening", () => {
+        const addr = server.address();
+        const port = typeof addr === "object" && addr ? addr.port : currentPort;
+        server.close(() => {
+          resolve(port);
+        });
+      });
+
+      server.listen(currentPort, host);
+    }
+
+    tryNext();
+  });
+}
+
+/**
+ * Pings a host and port via TCP to verify connectivity.
+ */
+export async function pingHost(host: string, port: number, options?: PingHostOptions): Promise<boolean> {
+  return isPortOpen(port, host, options);
+}

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

@@ -0,0 +1,160 @@
+import { safeSpawn } from "./process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+export interface PaseoPluginInfo {
+  id: string;
+  path: string;
+  enabled: boolean;
+  status: "running" | "disabled" | "failed" | string;
+  source?: "directory" | "git" | string;
+  remote?: string;
+  ref?: string;
+  commit?: string;
+  error?: string;
+}
+
+export type PluginStatusFilter = "all" | "enabled" | "disabled" | "running" | "failed";
+
+export interface ListPluginsOptions {
+  /** Filter results by status or enablement. Defaults to "all". */
+  filter?: PluginStatusFilter;
+  /** In-memory TTL cache duration in milliseconds. Defaults to 5000ms. */
+  cacheTtlMs?: number;
+  /** If true, bypasses the in-memory cache and queries the daemon fresh. */
+  forceRefresh?: boolean;
+}
+
+let cachedPlugins: PaseoPluginInfo[] | null = null;
+let lastFetchTime = 0;
+
+/**
+ * Clears the in-memory plugin list cache.
+ */
+export function clearPluginCache(): void {
+  cachedPlugins = null;
+  lastFetchTime = 0;
+}
+
+/**
+ * Reads configured plugins fallback from ~/.paseo/config.json when CLI is unavailable.
+ */
+function readConfigPluginsFallback(): PaseoPluginInfo[] {
+  try {
+    const configPath = path.join(os.homedir(), ".paseo", "config.json");
+    if (!fs.existsSync(configPath)) return [];
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const pluginsObj = parsed?.plugins;
+    if (!pluginsObj || typeof pluginsObj !== "object") return [];
+
+    return Object.entries(pluginsObj).map(([id, val]: [string, any]) => {
+      const isEnabled = val?.enabled !== false;
+      return {
+        id,
+        path: val?.path ?? "",
+        enabled: isEnabled,
+        status: isEnabled ? "unknown" : "disabled",
+        source: val?.source,
+        remote: val?.remote,
+        ref: val?.ref,
+        commit: val?.commit,
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Lists plugins from the Paseo daemon, with optional filtering and TTL caching.
+ * Primary mechanism uses 'paseo plugin ls --json', with fallback to ~/.paseo/config.json.
+ */
+export async function listPlugins(options: ListPluginsOptions = {}): Promise<PaseoPluginInfo[]> {
+  const { filter = "all", cacheTtlMs = 5000, forceRefresh = false } = options;
+  const now = Date.now();
+
+  if (!forceRefresh && cachedPlugins && now - lastFetchTime < cacheTtlMs) {
+    return applyFilter(cachedPlugins, filter);
+  }
+
+  let plugins: PaseoPluginInfo[] = [];
+
+  try {
+    const result = await safeSpawn("paseo", ["plugin", "ls", "--json"], { timeoutMs: 3000 });
+    if (result.code === 0 && result.stdout.trim()) {
+      plugins = JSON.parse(result.stdout.trim());
+    } else {
+      plugins = readConfigPluginsFallback();
+    }
+  } catch {
+    plugins = readConfigPluginsFallback();
+  }
+
+  cachedPlugins = plugins;
+  lastFetchTime = now;
+
+  return applyFilter(plugins, filter);
+}
+
+function applyFilter(plugins: PaseoPluginInfo[], filter: PluginStatusFilter): PaseoPluginInfo[] {
+  switch (filter) {
+    case "enabled":
+      return plugins.filter((p) => p.enabled);
+    case "disabled":
+      return plugins.filter((p) => !p.enabled);
+    case "running":
+      return plugins.filter((p) => p.status === "running");
+    case "failed":
+      return plugins.filter((p) => p.status === "failed");
+    case "all":
+    default:
+      return plugins;
+  }
+}
+
+/**
+ * Retrieves metadata for a specific plugin by ID.
+ * Returns null if the plugin is not installed or found.
+ */
+export async function getPluginInfo(
+  pluginId: string,
+  options?: { cacheTtlMs?: number; forceRefresh?: boolean },
+): Promise<PaseoPluginInfo | null> {
+  const plugins = await listPlugins(options);
+  return plugins.find((p) => p.id === pluginId) ?? null;
+}
+
+/**
+ * Checks whether a plugin is installed in Paseo.
+ */
+export async function isPluginInstalled(
+  pluginId: string,
+  options?: { cacheTtlMs?: number; forceRefresh?: boolean },
+): Promise<boolean> {
+  const info = await getPluginInfo(pluginId, options);
+  return info !== null;
+}
+
+/**
+ * Checks whether a plugin is installed and marked as enabled in Paseo.
+ */
+export async function isPluginEnabled(
+  pluginId: string,
+  options?: { cacheTtlMs?: number; forceRefresh?: boolean },
+): Promise<boolean> {
+  const info = await getPluginInfo(pluginId, options);
+  return info !== null && info.enabled;
+}
+
+/**
+ * Checks whether a plugin is currently running in the Paseo daemon.
+ */
+export async function isPluginRunning(
+  pluginId: string,
+  options?: { cacheTtlMs?: number; forceRefresh?: boolean },
+): Promise<boolean> {
+  const info = await getPluginInfo(pluginId, options);
+  return info !== null && info.status === "running";
+}

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