@xpufx/paseo-x-comms 0.3.0

package/server/vendor/paseo-plugin-helper/mcp-config.ts

@@ -0,0 +1,367 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { parseJsonc } from "./jsonc";
+
+export interface McpServerConfig {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  disabled?: boolean;
+  autoApprove?: string[];
+  [key: string]: unknown;
+}
+
+export interface McpConfigTarget {
+  /**
+   * Absolute or relative path to the configuration file.
+   * Supports '~' expansion (e.g. "~/.claude.json").
+   */
+  path: string;
+
+  /**
+   * The top-level key under which MCP servers are defined.
+   * Defaults to "mcpServers".
+   */
+  key?: string;
+
+  /**
+   * If true, creates a timestamped backup file before modifying an existing file.
+   */
+  backup?: boolean;
+}
+
+export interface UpsertMcpServerOptions {
+  /**
+   * Target config file path or McpConfigTarget descriptor.
+   */
+  target: string | McpConfigTarget;
+
+  /**
+   * Unique name of the MCP server entry (e.g. "paseo-gateway", "top", "x-comms").
+   */
+  serverName: string;
+
+  /**
+   * MCP server configuration object (command, args, env, etc.).
+   */
+  config: McpServerConfig;
+
+  /**
+   * Override backup option. If true, creates a backup before modifying.
+   */
+  backup?: boolean;
+}
+
+export interface RemoveMcpServerOptions {
+  /**
+   * Target config file path or McpConfigTarget descriptor.
+   */
+  target: string | McpConfigTarget;
+
+  /**
+   * Name of the MCP server entry to remove.
+   */
+  serverName: string;
+
+  /**
+   * Override backup option. If true, creates a backup before removing.
+   */
+  backup?: boolean;
+}
+
+export interface McpMutationResult {
+  filePath: string;
+  serverName: string;
+  changed: boolean;
+  action: "created" | "updated" | "unchanged" | "removed" | "not_found";
+  backupPath?: string;
+}
+
+/**
+ * Standard known MCP configuration paths across major developer tools and agent runners.
+ * Note: These are pure path resolvers with zero filesystem scanning or heuristics.
+ */
+export const McpConfigPaths = {
+  /**
+   * Claude Desktop configuration path per operating system:
+   * - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+   * - Windows: %APPDATA%/Claude/claude_desktop_config.json
+   * - Linux: ~/.config/Claude/claude_desktop_config.json
+   */
+  claudeDesktop(): string {
+    const platform = process.platform;
+    const home = os.homedir();
+    if (platform === "darwin") {
+      return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+      const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+      return path.join(appData, "Claude", "claude_desktop_config.json");
+    }
+    const configDir = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+    return path.join(configDir, "Claude", "claude_desktop_config.json");
+  },
+
+  /**
+   * Claude Code CLI global configuration: ~/.claude.json
+   */
+  claudeCode(): string {
+    return path.join(os.homedir(), ".claude.json");
+  },
+
+  /**
+   * OpenCode configuration path: ~/.config/opencode/opencode.json
+   */
+  openCode(): string {
+    const home = os.homedir();
+    const configDir = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+    return path.join(configDir, "opencode", "opencode.json");
+  },
+
+  /**
+   * Cursor editor MCP configuration: ~/.cursor/mcp.json
+   */
+  cursor(): string {
+    return path.join(os.homedir(), ".cursor", "mcp.json");
+  },
+
+  /**
+   * Gemini / Antigravity CLI configuration: ~/.gemini/config/mcp_config.json
+   */
+  gemini(): string {
+    return path.join(os.homedir(), ".gemini", "config", "mcp_config.json");
+  },
+
+  /**
+   * Pi CLI agent configuration: ~/.pi/config.json
+   */
+  pi(): string {
+    return path.join(os.homedir(), ".pi", "config.json");
+  },
+};
+
+/**
+ * Expands '~' to the user's home directory.
+ */
+export function expandPath(targetPath: string): string {
+  if (targetPath === "~") {
+    return os.homedir();
+  }
+  if (targetPath.startsWith("~/") || targetPath.startsWith("~\\")) {
+    return path.join(os.homedir(), targetPath.slice(2));
+  }
+  return path.resolve(targetPath);
+}
+
+/**
+ * Deep equality check for primitives, arrays, and objects.
+ */
+function isDeepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
+    return false;
+  }
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!isDeepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+
+  const keysA = Object.keys(a as Record<string, unknown>);
+  const keysB = Object.keys(b as Record<string, unknown>);
+
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!isDeepEqual((a as any)[key], (b as any)[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * Normalizes target string or descriptor into { filePath, key, backup }.
+ */
+function normalizeTarget(target: string | McpConfigTarget, backupOverride?: boolean): {
+  filePath: string;
+  key: string;
+  backup: boolean;
+} {
+  if (typeof target === "string") {
+    return {
+      filePath: expandPath(target),
+      key: "mcpServers",
+      backup: Boolean(backupOverride),
+    };
+  }
+  return {
+    filePath: expandPath(target.path),
+    key: target.key || "mcpServers",
+    backup: backupOverride !== undefined ? backupOverride : Boolean(target.backup),
+  };
+}
+
+/**
+ * Reads an existing configuration file safely using JSONC parser.
+ * Returns an empty object if the file does not exist.
+ */
+function readConfigDocument(filePath: string): Record<string, any> {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  const raw = fs.readFileSync(filePath, "utf8");
+  if (!raw.trim()) {
+    return {};
+  }
+  return parseJsonc<Record<string, any>>(raw);
+}
+
+/**
+ * Writes data atomically to the given file path using a temporary file and POSIX atomic rename.
+ */
+function writeConfigAtomic(filePath: string, data: Record<string, any>): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}`;
+  const serialized = JSON.stringify(data, null, 2) + "\n";
+  fs.writeFileSync(tempPath, serialized, "utf8");
+  fs.renameSync(tempPath, filePath);
+}
+
+/**
+ * Retrieves an MCP server definition from a config file.
+ * Returns null if the file, key, or server does not exist.
+ */
+export function getMcpServer(
+  target: string | McpConfigTarget,
+  serverName: string
+): McpServerConfig | null {
+  const { filePath, key } = normalizeTarget(target);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const doc = readConfigDocument(filePath);
+    const servers = doc[key];
+    if (servers && typeof servers === "object" && serverName in servers) {
+      return servers[serverName] as McpServerConfig;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Upserts an MCP server definition into an agent or tool configuration file.
+ *
+ * Guarantees:
+ * 1. Namespaced idempotency: If the server configuration already exists and matches,
+ *    no write occurs, preventing file watcher thrashing.
+ * 2. JSONC safe: Reads files containing comments or trailing commas without crashing.
+ * 3. Atomic writes: Uses temporary files and atomic rename to prevent corruption.
+ * 4. Optional backups: Can create a timestamped backup before modifying existing files.
+ */
+export function upsertMcpServer(options: UpsertMcpServerOptions): McpMutationResult {
+  const { filePath, key, backup } = normalizeTarget(options.target, options.backup);
+  const { serverName, config } = options;
+
+  let doc: Record<string, any>;
+  const fileExisted = fs.existsSync(filePath);
+
+  if (fileExisted) {
+    doc = readConfigDocument(filePath);
+  } else {
+    doc = {};
+  }
+
+  if (typeof doc[key] !== "object" || doc[key] === null || Array.isArray(doc[key])) {
+    doc[key] = {};
+  }
+
+  const existingConfig = doc[key][serverName];
+  const isExisting = existingConfig !== undefined;
+
+  // Idempotency: Deep equality check
+  if (isExisting && isDeepEqual(existingConfig, config)) {
+    return {
+      filePath,
+      serverName,
+      changed: false,
+      action: "unchanged",
+    };
+  }
+
+  let backupPath: string | undefined;
+  if (backup && fileExisted) {
+    backupPath = `${filePath}.bak.${Date.now()}`;
+    fs.copyFileSync(filePath, backupPath);
+  }
+
+  doc[key][serverName] = config;
+  writeConfigAtomic(filePath, doc);
+
+  return {
+    filePath,
+    serverName,
+    changed: true,
+    action: isExisting ? "updated" : "created",
+    backupPath,
+  };
+}
+
+/**
+ * Removes an MCP server definition from a config file.
+ *
+ * Guarantees:
+ * 1. Safe no-op: If the file or server does not exist, no write occurs.
+ * 2. Atomic writes: Cleanly removes the key and updates the file atomically.
+ * 3. Optional backups: Can create a timestamped backup before removal.
+ */
+export function removeMcpServer(options: RemoveMcpServerOptions): McpMutationResult {
+  const { filePath, key, backup } = normalizeTarget(options.target, options.backup);
+  const { serverName } = options;
+
+  if (!fs.existsSync(filePath)) {
+    return {
+      filePath,
+      serverName,
+      changed: false,
+      action: "not_found",
+    };
+  }
+
+  const doc = readConfigDocument(filePath);
+  if (!doc[key] || typeof doc[key] !== "object" || !(serverName in doc[key])) {
+    return {
+      filePath,
+      serverName,
+      changed: false,
+      action: "not_found",
+    };
+  }
+
+  let backupPath: string | undefined;
+  if (backup) {
+    backupPath = `${filePath}.bak.${Date.now()}`;
+    fs.copyFileSync(filePath, backupPath);
+  }
+
+  delete doc[key][serverName];
+  writeConfigAtomic(filePath, doc);
+
+  return {
+    filePath,
+    serverName,
+    changed: true,
+    action: "removed",
+    backupPath,
+  };
+}

package/server/vendor/paseo-plugin-helper/mcp-injection.ts

@@ -0,0 +1,85 @@
+export interface McpStdioInjectionConfig {
+  type: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  alwaysLoad?: boolean;
+}
+
+export interface McpHttpInjectionConfig {
+  type: "http";
+  url: string;
+  headers?: Record<string, string>;
+  alwaysLoad?: boolean;
+}
+
+export interface McpSseInjectionConfig {
+  type: "sse";
+  url: string;
+  headers?: Record<string, string>;
+  alwaysLoad?: boolean;
+}
+
+export type McpInjectionConfig =
+  | McpStdioInjectionConfig
+  | McpHttpInjectionConfig
+  | McpSseInjectionConfig;
+
+export interface AgentCreateInjectionConfig {
+  mcpServers?: Record<string, McpInjectionConfig>;
+  [key: string]: unknown;
+}
+
+export interface AgentCreateInjectionRequest {
+  config: AgentCreateInjectionConfig;
+  env?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export type McpInjectionFilter = (input: {
+  request: AgentCreateInjectionRequest;
+}) => boolean;
+
+export type McpInjectionHookHandler = (
+  input: { request: AgentCreateInjectionRequest },
+  context?: unknown,
+) => AgentCreateInjectionRequest | void | Promise<AgentCreateInjectionRequest | void>;
+
+export interface McpInjectionServer {
+  // Loose on purpose: the real SDK declares a generic
+  // before<Name extends keyof PluginBeforeRequests>(...) whose name param is
+  // narrower than string and whose handler uses SDK request types. Typing this
+  // boundary with any keeps the SDK object directly assignable with no
+  // consumer-side adapter and no SDK imports here. Handler authors should use
+  // McpInjectionHookHandler for the precise shape.
+  before(
+    name: string,
+    handler: (input: { request: any }, context?: any) => any,
+  ): () => void;
+}
+
+export interface RegisterMcpInjectionOptions {
+  serverName: string;
+  config: McpInjectionConfig;
+  filter?: McpInjectionFilter;
+}
+
+export function registerMcpInjection(
+  server: McpInjectionServer,
+  options: RegisterMcpInjectionOptions,
+): () => void {
+  const { serverName, config, filter } = options;
+  return server.before("agent.create", ({ request }: { request: AgentCreateInjectionRequest }) => {
+    if (filter && !filter({ request })) return;
+    return {
+      ...request,
+      config: {
+        ...request.config,
+        mcpServers: {
+          ...(request.config.mcpServers ?? {}),
+          [serverName]: config,
+        },
+      },
+    };
+  });
+}

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