@xpufx/paseo-x-comms 0.3.0

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

@@ -0,0 +1,210 @@
+import { redactSecrets } from "./redact";
+import { resolvePluginVersion } from "./version";
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_SEVERITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+function isLogLevel(value: unknown): value is LogLevel {
+  return (
+    value === "debug" || value === "info" || value === "warn" || value === "error"
+  );
+}
+
+/**
+ * Resolves the minimum log level from the environment. Precedence:
+ * `PASEO_PLUGIN_LOG_LEVEL` > `PASEO_LOG_LEVEL` > `PASEO_DEBUG=1` (debug).
+ * Returns undefined when nothing is set so callers can apply their default.
+ */
+export function resolveMinLevelFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): LogLevel | undefined {
+  const raw = env.PASEO_PLUGIN_LOG_LEVEL ?? env.PASEO_LOG_LEVEL;
+  if (typeof raw === "string" && isLogLevel(raw.trim().toLowerCase())) {
+    return raw.trim().toLowerCase() as LogLevel;
+  }
+  const debugFlag = env.PASEO_DEBUG ?? env.PASEO_PLUGIN_DEBUG;
+  if (
+    typeof debugFlag === "string" &&
+    ["1", "true", "yes", "debug"].includes(debugFlag.trim().toLowerCase())
+  ) {
+    return "debug";
+  }
+  return undefined;
+}
+
+/**
+ * True when running in production. Retained for callers that need a
+ * production check; note the default log level no longer keys off this.
+ */
+export function isProductionEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  return (env.NODE_ENV ?? "").trim().toLowerCase() === "production";
+}
+
+/**
+ * True only when `NODE_ENV` is explicitly a development value
+ * (`development`/`dev`). Unset, empty, `production`, and anything else
+ * (e.g. `test`) all count as quiet, so a shipped plugin defaults to info
+ * without any env var set.
+ */
+export function isDevelopmentEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  const nodeEnv = (env.NODE_ENV ?? "").trim().toLowerCase();
+  return nodeEnv === "development" || nodeEnv === "dev";
+}
+
+/**
+ * Default rule (documented for operators):
+ * explicit `PASEO_PLUGIN_LOG_LEVEL`/`PASEO_LOG_LEVEL`/`PASEO_DEBUG` always wins;
+ * otherwise quiet (`info`) — including when no env var is set at all, so a
+ * shipped plugin never emits debug logs by default. Debug only when `NODE_ENV`
+ * is explicitly a development value (`development`/`dev`).
+ */
+export function resolveDefaultMinLevel(
+  env: NodeJS.ProcessEnv = process.env,
+): LogLevel {
+  return resolveMinLevelFromEnv(env) ?? (isDevelopmentEnv(env) ? "debug" : "info");
+}
+
+export interface PluginLoggerOptions {
+  /**
+   * Version of the plugin.
+   * If omitted, automatically resolves from `package.json` (augmented by git tag/hash).
+   */
+  version?: string;
+
+  /**
+   * Whether to emit a formatted startup banner on initialization.
+   * Defaults to `true`.
+   */
+  banner?: boolean;
+
+  /**
+   * Subsystem or module tag within the plugin (e.g. "poller", "mcp-client").
+   */
+  subsystem?: string;
+
+  /**
+   * Minimum log level to print. Defaults to resolveDefaultMinLevel():
+   * info unless NODE_ENV is explicitly development (or an explicit level is set).
+   */
+  minLevel?: LogLevel;
+
+  /**
+   * Optional custom metadata key-values to include in the startup banner.
+   */
+  meta?: Record<string, string | number | boolean>;
+}
+
+export interface PluginLogger {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+  /** Surfaces a caught/suppressed error at debug level so it reaches the plugin log. */
+  suppressed(context: string, error: unknown): void;
+  child(subsystemOrOptions: string | Partial<PluginLoggerOptions>): PluginLogger;
+}
+
+function formatData(data: unknown): string {
+  if (data === undefined) return "";
+  if (data instanceof Error) {
+    return `error="${data.message}"${data.stack ? `\n${data.stack}` : ""}`;
+  }
+
+  const sanitized = redactSecrets(data);
+  if (typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)) {
+    const pairs = Object.entries(sanitized as Record<string, unknown>).map(
+      ([k, v]) => `${k}=${typeof v === "object" ? JSON.stringify(v) : String(v)}`,
+    );
+    return pairs.join(" ");
+  }
+
+  return typeof sanitized === "string" ? sanitized : JSON.stringify(sanitized);
+}
+
+/**
+ * Creates a structured logger for Paseo plugins.
+ * By default, displays the plugin name and version in startup logs and tags each line
+ * for Paseo's log stream without fragmented multi-line JSON.
+ *
+ * If `options.version` is omitted, it automatically resolves the version from `package.json`
+ * augmented with git metadata.
+ */
+export function createPluginLogger(
+  pluginId: string,
+  options: PluginLoggerOptions = {},
+): PluginLogger {
+  const resolvedVer = options.version ?? resolvePluginVersion({ fallback: "" });
+  const {
+    banner = true,
+    subsystem,
+    minLevel = resolveDefaultMinLevel(),
+    meta = {},
+  } = options;
+
+  const minSeverity = LEVEL_SEVERITY[minLevel];
+
+  // Prefix format: "[name vX.Y.Z]" or "[name]" or "[name vX.Y.Z:subsystem]"
+  const versionTag = resolvedVer ? ` v${resolvedVer}` : "";
+  const subTag = subsystem ? `:${subsystem}` : "";
+  const baseTag = `[${pluginId}${versionTag}${subTag}]`;
+
+  if (banner) {
+    const bannerDetails = [
+      `pid ${process.pid}`,
+      `node ${process.version}`,
+      ...Object.entries(meta).map(([k, v]) => `${k} ${v}`),
+    ].join(", ");
+
+    // Emit startup banner directly to stdout
+    console.log(`${baseTag} Initializing plugin (${bannerDetails})`);
+  }
+
+  function emit(level: LogLevel, message: string, data?: unknown) {
+    if (LEVEL_SEVERITY[level] < minSeverity) return;
+
+    const levelTag = `[${level.toUpperCase()}]`;
+    const formattedData = formatData(data);
+    const line = formattedData
+      ? `${baseTag} ${levelTag} ${message} ${formattedData}`
+      : `${baseTag} ${levelTag} ${message}`;
+
+    if (level === "error" || level === "warn") {
+      console.error(line);
+    } else {
+      console.log(line);
+    }
+  }
+
+  return {
+    debug(message: string, data?: unknown) {
+      emit("debug", message, data);
+    },
+    info(message: string, data?: unknown) {
+      emit("info", message, data);
+    },
+    warn(message: string, data?: unknown) {
+      emit("warn", message, data);
+    },
+    error(message: string, data?: unknown) {
+      emit("error", message, data);
+    },
+    suppressed(context: string, error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      emit("debug", `${context}: ${detail}`, error);
+    },
+    child(subsystemOrOptions: string | Partial<PluginLoggerOptions>): PluginLogger {
+      const childOptions: PluginLoggerOptions =
+        typeof subsystemOrOptions === "string"
+          ? { ...options, version: resolvedVer, banner: false, subsystem: subsystemOrOptions }
+          : { ...options, version: resolvedVer, banner: false, ...subsystemOrOptions };
+
+      return createPluginLogger(pluginId, childOptions);
+    },
+  };
+}

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

@@ -0,0 +1,349 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import readline from "node:readline";
+import crypto from "node:crypto";
+import { StderrRingBuffer } from "./ring-buffer";
+import { killProcessTree } from "./process-killer";
+import { McpHttpClient, type McpHttpOptions } from "./http-client";
+import type {
+  McpClientOptions,
+  McpPingOptions,
+  McpPingResult,
+  McpToolCallResult,
+  McpToolInfo,
+} from "./types";
+
+interface PendingRequest {
+  resolve: (res: any) => void;
+  reject: (err: Error) => void;
+  timer: NodeJS.Timeout;
+}
+
+export class McpClient {
+  private child: ChildProcess | null = null;
+  private stderrBuffer = new StderrRingBuffer(30);
+  private pendingRequests = new Map<string | number, PendingRequest>();
+  private initialized = false;
+  private _serverInfo?: { name: string; version?: string };
+  private _instructions?: string;
+  private _capabilities?: Record<string, unknown>;
+  private _protocolVersion?: string;
+  private initPromise?: Promise<void>;
+
+  /**
+   * Server metadata returned during MCP initialize handshake.
+   */
+  get serverInfo(): { name: string; version?: string } | undefined {
+    return this._serverInfo;
+  }
+
+  /**
+   * Optional server instructions / system prompt guidance returned during MCP initialize handshake.
+   */
+  get instructions(): string | undefined {
+    return this._instructions;
+  }
+
+  /**
+   * Declared server capabilities returned during initialize handshake.
+   */
+  get capabilities(): Record<string, unknown> | undefined {
+    return this._capabilities;
+  }
+
+  /**
+   * Protocol version negotiated during initialize handshake.
+   */
+  get protocolVersion(): string | undefined {
+    return this._protocolVersion;
+  }
+
+  private constructor(
+    private readonly command: string,
+    private readonly args: string[] = [],
+    private readonly env?: Record<string, string>,
+    private readonly options: McpClientOptions = {},
+  ) {}
+
+  /**
+   * Creates an MCP client talking to a local process over stdio.
+   */
+  static forStdio(
+    command: string,
+    args: string[] = [],
+    env?: Record<string, string>,
+    options?: McpClientOptions,
+  ): McpClient {
+    return new McpClient(command, args, env, options);
+  }
+
+  /**
+   * Creates an MCP client connecting to an HTTP or Server-Sent Events (SSE) MCP server.
+   */
+  static forHttp(url: string, options?: McpHttpOptions): McpHttpClient {
+    return new McpHttpClient(url, options);
+  }
+
+  private startProcess(): Promise<void> {
+    if (this.child && !this.child.killed) return Promise.resolve();
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.child = spawn(this.command, this.args, {
+          env: {
+            ...process.env,
+            ...this.env,
+          },
+          shell: false,
+          detached: process.platform !== "win32",
+        });
+
+        this.child.on("error", (err: any) => {
+          const isNotFound = err.code === "ENOENT" || err.code === "EACCES";
+          const formattedErr = isNotFound
+            ? new Error(`Executable "${this.command}" not found in PATH or cannot be executed (${err.code}).`)
+            : err;
+          this.rejectAllPending(formattedErr);
+          reject(formattedErr);
+        });
+
+        this.child.stderr?.on("data", (chunk: Buffer | string) => {
+          this.stderrBuffer.push(chunk.toString());
+        });
+
+        if (this.child.stdout) {
+          const rl = readline.createInterface({
+            input: this.child.stdout,
+            crlfDelay: Infinity,
+          });
+
+          rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed || !trimmed.startsWith("{")) {
+              // Ignore non-JSON output (e.g. startup banners or debug logs)
+              return;
+            }
+            try {
+              const msg = JSON.parse(trimmed);
+              this.handleMessage(msg);
+            } catch {
+              // Ignore JSON parse errors from malformed stdout noise
+            }
+          });
+        }
+
+        this.child.on("close", (code, signal) => {
+          const stderr = this.stderrBuffer.getRecentText();
+          const reason = stderr
+            ? `Process exited with code ${code ?? signal}:\n${stderr}`
+            : `Process exited unexpectedly with code ${code ?? signal}.`;
+          this.rejectAllPending(new Error(reason));
+        });
+
+        resolve();
+      } catch (err: any) {
+        const isNotFound = err?.code === "ENOENT" || err?.code === "EACCES";
+        const formattedErr = isNotFound
+          ? new Error(`Executable "${this.command}" not found in PATH or cannot be executed (${err?.code}).`)
+          : err;
+        reject(formattedErr);
+      }
+    });
+  }
+
+  private handleMessage(msg: any): void {
+    if (!msg || typeof msg !== "object") return;
+
+    // Handle responses to requests
+    if (msg.id !== undefined && msg.id !== null) {
+      const pending = this.pendingRequests.get(msg.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(msg.id);
+
+        if (msg.error) {
+          const err = new Error(msg.error.message || `JSON-RPC error ${msg.error.code}`);
+          (err as any).code = msg.error.code;
+          (err as any).data = msg.error.data;
+          pending.reject(err);
+        } else {
+          pending.resolve(msg.result);
+        }
+      }
+    }
+  }
+
+  private rejectAllPending(err: Error): void {
+    for (const [id, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timer);
+      pending.reject(err);
+    }
+    this.pendingRequests.clear();
+  }
+
+  private async sendRequest<T = any>(
+    method: string,
+    params?: any,
+    timeoutMs?: number,
+  ): Promise<T> {
+    await this.startProcess();
+
+    if (!this.child || !this.child.stdin || this.child.killed) {
+      throw new Error(`Process "${this.command}" is not running.`);
+    }
+
+    const id = crypto.randomUUID();
+    const timeout = timeoutMs ?? this.options.timeoutMs ?? 10000;
+
+    const payload = JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method,
+      ...(params !== undefined ? { params } : {}),
+    });
+
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        const stderr = this.stderrBuffer.getRecentText();
+        const msg = stderr
+          ? `Request "${method}" timed out after ${timeout}ms. Stderr output:\n${stderr}`
+          : `Request "${method}" timed out after ${timeout}ms.`;
+        reject(new Error(msg));
+      }, timeout);
+
+      this.pendingRequests.set(id, { resolve, reject, timer });
+
+      this.child!.stdin!.write(payload + "\n", (err) => {
+        if (err) {
+          clearTimeout(timer);
+          this.pendingRequests.delete(id);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private sendNotification(method: string, params?: any): void {
+    if (!this.child || !this.child.stdin || this.child.killed) return;
+    const payload = JSON.stringify({
+      jsonrpc: "2.0",
+      method,
+      ...(params !== undefined ? { params } : {}),
+    });
+    this.child.stdin.write(payload + "\n");
+  }
+
+  /**
+   * Performs the MCP initialize handshake and sends the initialized notification.
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+    if (this.initPromise) return this.initPromise;
+
+    this.initPromise = (async () => {
+      const result = await this.sendRequest("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {
+          tools: {},
+        },
+        clientInfo: this.options.clientInfo ?? {
+          name: "paseo-plugin",
+          version: "1.0.0",
+        },
+      });
+
+      this._serverInfo = result?.serverInfo;
+      this._instructions = result?.instructions;
+      this._capabilities = result?.capabilities;
+      this._protocolVersion = result?.protocolVersion;
+      this.sendNotification("notifications/initialized");
+      this.initialized = true;
+    })();
+
+    return this.initPromise;
+  }
+
+  /**
+   * Checks the health and responsiveness of the MCP server.
+   * If protocol ping fails with -32601 (Method not found), seamlessly falls back
+   * to handshake validation.
+   */
+  async ping(options: McpPingOptions = {}): Promise<McpPingResult> {
+    const start = Date.now();
+    const timeout = options.timeoutMs ?? this.options.timeoutMs ?? 10000;
+
+    try {
+      await this.initialize();
+
+      if (options.mode === "tools") {
+        await this.listTools();
+      } else {
+        try {
+          await this.sendRequest("ping", {}, timeout);
+        } catch (err: any) {
+          // Method not found (-32601) is common on minimalist servers; fallback to handshake
+          if (err.code !== -32601) {
+            throw err;
+          }
+        }
+      }
+
+      return {
+        healthy: true,
+        latencyMs: Date.now() - start,
+        serverInfo: this._serverInfo,
+        instructions: this._instructions,
+        stderr: this.stderrBuffer.getRecentText(),
+      };
+    } catch (err: any) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - start,
+        error: err.message,
+        stderr: this.stderrBuffer.getRecentText(),
+      };
+    }
+  }
+
+  /**
+   * Enumerates available tools on the MCP server.
+   */
+  async listTools(): Promise<McpToolInfo[]> {
+    await this.initialize();
+    const result = await this.sendRequest("tools/list", {});
+    return (result?.tools as McpToolInfo[]) ?? [];
+  }
+
+  /**
+   * Calls a tool by name with the given arguments.
+   */
+  async callTool(name: string, args: Record<string, unknown> = {}): Promise<McpToolCallResult> {
+    await this.initialize();
+    const result = await this.sendRequest("tools/call", {
+      name,
+      arguments: args,
+    });
+    return result as McpToolCallResult;
+  }
+
+  /**
+   * Retrieves the recent stderr lines captured in the ring buffer.
+   */
+  getStderr(): string {
+    return this.stderrBuffer.getRecentText();
+  }
+
+  /**
+   * Cleanly closes the client, killing the child process and its process tree.
+   */
+  async close(): Promise<void> {
+    this.rejectAllPending(new Error("Client was closed."));
+    if (this.child) {
+      const child = this.child;
+      this.child = null;
+      await killProcessTree(child);
+    }
+    this.initialized = false;
+    this.initPromise = undefined;
+  }
+}