@xpufx/paseo-forges 0.1.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-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,
+        },
+      },
+    };
+  });
+}