@mewbleh/purrx 1.0.8

package/src/tools/mcp.js

@@ -0,0 +1,223 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { configFilePath } from "../config.js";
+
+// Minimal MCP (Model Context Protocol) client over stdio using JSON-RPC 2.0
+// with newline-delimited framing. Connects to configured servers, lists their
+// tools, and proxies tools/call requests.
+
+const PROTOCOL_VERSION = "2024-11-05";
+
+class McpServer {
+  constructor(name, config) {
+    this.name = name;
+    this.config = config;
+    this.proc = null;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.buffer = "";
+    this.tools = [];
+    this.ready = false;
+  }
+
+  async start() {
+    const { command, args = [], env = {} } = this.config;
+    // On Windows, launchers like `npx` resolve to `.cmd` shims that require a
+    // shell. MCP configs come from the user's own trusted config file, so the
+    // shell concatenation risk is acceptable here.
+    this.proc = spawn(command, args, {
+      env: { ...process.env, ...env },
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: process.platform === "win32",
+    });
+
+    this.proc.stdout.setEncoding("utf8");
+    this.proc.stdout.on("data", (chunk) => this._onData(chunk));
+    this.proc.stderr.setEncoding("utf8");
+    this.proc.stderr.on("data", (data) => {
+      // MCP servers commonly log to stderr; ignore unless debugging.
+      if (process.env.PURRX_DEBUG) {
+        process.stderr.write(`[mcp:${this.name}] ${data}`);
+      }
+    });
+    this.proc.on("error", (err) => {
+      for (const { reject } of this.pending.values()) reject(err);
+      this.pending.clear();
+    });
+    this.proc.on("exit", () => {
+      this.ready = false;
+    });
+
+    // Handshake.
+    await this._request("initialize", {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      clientInfo: { name: "purrx", version: "1.0.0" },
+    });
+    this._notify("notifications/initialized", {});
+    this.ready = true;
+
+    // Discover tools.
+    const result = await this._request("tools/list", {});
+    this.tools = result?.tools || [];
+    return this.tools;
+  }
+
+  _onData(chunk) {
+    this.buffer += chunk;
+    let idx;
+    while ((idx = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (msg.id !== undefined && this.pending.has(msg.id)) {
+        const { resolve, reject } = this.pending.get(msg.id);
+        this.pending.delete(msg.id);
+        if (msg.error) {
+          reject(new Error(msg.error.message || "MCP error"));
+        } else {
+          resolve(msg.result);
+        }
+      }
+      // Notifications from server are ignored.
+    }
+  }
+
+  _send(obj) {
+    if (!this.proc || !this.proc.stdin.writable) {
+      throw new Error(`MCP server ${this.name} is not running`);
+    }
+    this.proc.stdin.write(JSON.stringify(obj) + "\n");
+  }
+
+  _request(method, params) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this._send({ jsonrpc: "2.0", id, method, params });
+      // Timeout so a hung server doesn't block forever.
+      setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`MCP ${this.name} ${method} timed out`));
+        }
+      }, 30_000);
+    });
+  }
+
+  _notify(method, params) {
+    this._send({ jsonrpc: "2.0", method, params });
+  }
+
+  async callTool(toolName, args) {
+    const result = await this._request("tools/call", {
+      name: toolName,
+      arguments: args || {},
+    });
+    // MCP returns { content: [{type:'text', text:...}], isError? }
+    if (result?.content) {
+      const text = result.content
+        .map((c) => (c.type === "text" ? c.text : JSON.stringify(c)))
+        .join("\n");
+      return result.isError ? `Error: ${text}` : text;
+    }
+    return JSON.stringify(result);
+  }
+
+  stop() {
+    try {
+      this.proc?.kill();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+// Reads MCP server config from <home>/config.json:
+//   { "mcpServers": { "name": { "command": "...", "args": [...], "env": {} } } }
+export function readMcpConfig() {
+  try {
+    const raw = fs.readFileSync(configFilePath(), "utf8");
+    const cfg = JSON.parse(raw);
+    return cfg.mcpServers || {};
+  } catch {
+    return {};
+  }
+}
+
+// Manages all configured MCP servers and exposes their tools as purrx tool
+// definitions (namespaced as "mcp__<server>__<tool>").
+export class McpManager {
+  constructor() {
+    this.servers = new Map();
+    this.toolRoutes = new Map(); // namespacedName -> { server, toolName }
+  }
+
+  /**
+   * @param {(msg: string) => void} [onLog]
+   * @returns {Promise<import("../types.js").ToolDefinition[]>}
+   */
+  async connectAll(onLog = (/** @type {string} */ _msg) => {}) {
+    const config = readMcpConfig();
+    const names = Object.keys(config);
+    if (!names.length) return [];
+
+    const defs = [];
+    for (const name of names) {
+      if (config[name].disabled) continue;
+      const server = new McpServer(name, config[name]);
+      try {
+        const tools = await server.start();
+        this.servers.set(name, server);
+        for (const t of tools) {
+          const nsName = `mcp__${name}__${t.name}`;
+          this.toolRoutes.set(nsName, { server, toolName: t.name });
+          defs.push({
+            type: "function",
+            name: nsName,
+            description: `[MCP:${name}] ${t.description || t.name}`,
+            parameters: t.inputSchema || {
+              type: "object",
+              properties: {},
+            },
+          });
+        }
+        onLog(`connected MCP server "${name}" (${tools.length} tools)`);
+      } catch (err) {
+        onLog(`failed to connect MCP server "${name}": ${/** @type {Error} */ (err).message}`);
+        server.stop();
+      }
+    }
+    return defs;
+  }
+
+  isMcpTool(name) {
+    return this.toolRoutes.has(name);
+  }
+
+  async callTool(name, args) {
+    const route = this.toolRoutes.get(name);
+    if (!route) return `Error: unknown MCP tool "${name}"`;
+    try {
+      return await route.server.callTool(route.toolName, args);
+    } catch (err) {
+      return `Error: ${err.message}`;
+    }
+  }
+
+  stopAll() {
+    for (const s of this.servers.values()) s.stop();
+    this.servers.clear();
+    this.toolRoutes.clear();
+  }
+
+  serverCount() {
+    return this.servers.size;
+  }
+}

package/src/tools/registry.js

@@ -0,0 +1,62 @@
+import { toolDefinitions as builtinTools, executeTool, READ_ONLY_TOOLS } from "./builtin.js";
+import { McpManager } from "./mcp.js";
+
+// The registry unifies three kinds of tools:
+//   1. purrx built-in function tools (file ops, search, shell, fetch)
+//   2. OpenAI/ChatGPT server-side tools (e.g. web_search) - executed by the API
+//   3. MCP tools from configured servers - proxied locally
+//
+// It produces the combined `tools` array sent to the API and routes
+// tool calls to the right executor.
+
+// Server-side tools the model runs on OpenAI's side. We just declare them;
+// the API handles execution and streams results back as output items.
+export const SERVER_SIDE_TOOLS = {
+  web_search: { type: "web_search" },
+};
+
+export class ToolRegistry {
+  constructor() {
+    this.mcp = new McpManager();
+    this.mcpDefs = [];
+    this.enabledServerSide = new Set();
+  }
+
+  // Connect MCP servers (if any configured) and collect their tool defs.
+  async init({ onLog = () => {}, webSearch = true } = {}) {
+    this.mcpDefs = await this.mcp.connectAll(onLog);
+    if (webSearch) this.enabledServerSide.add("web_search");
+  }
+
+  // The full tool list to send to the API.
+  definitions() {
+    const serverSide = [...this.enabledServerSide]
+      .map((k) => SERVER_SIDE_TOOLS[k])
+      .filter(Boolean);
+    return [...builtinTools, ...this.mcpDefs, ...serverSide];
+  }
+
+  isReadOnly(name) {
+    return READ_ONLY_TOOLS.has(name);
+  }
+
+  isMcp(name) {
+    return this.mcp.isMcpTool(name);
+  }
+
+  // Execute a locally-handled tool call (built-in or MCP).
+  async execute(name, args, cwd) {
+    if (this.mcp.isMcpTool(name)) {
+      return this.mcp.callTool(name, args);
+    }
+    return executeTool(name, args, cwd);
+  }
+
+  shutdown() {
+    this.mcp.stopAll();
+  }
+
+  mcpServerCount() {
+    return this.mcp.serverCount();
+  }
+}

package/src/types.js

@@ -0,0 +1,68 @@
+// Shared JSDoc type definitions for purrx. This file has no runtime exports;
+// it exists so other modules can reference types via `import("./types.js")`.
+
+/**
+ * How requests authenticate against the backend.
+ * @typedef {Object} AuthInfo
+ * @property {"apikey"|"chatgpt"} mode
+ * @property {string} [apiKey]      Present when mode is "apikey".
+ * @property {string} [accessToken] Present when mode is "chatgpt".
+ * @property {string|null} [accountId] ChatGPT account id, if known.
+ */
+
+/**
+ * Token bundle stored inside auth.json.
+ * @typedef {Object} StoredTokens
+ * @property {string} id_token
+ * @property {string} access_token
+ * @property {string} refresh_token
+ * @property {string|null} account_id
+ */
+
+/**
+ * The on-disk auth.json shape (Codex-compatible).
+ * @typedef {Object} AuthDotJson
+ * @property {string|null} [OPENAI_API_KEY]
+ * @property {StoredTokens|null} [tokens]
+ * @property {string} [last_refresh]
+ */
+
+/**
+ * A single conversation item in the Responses API input format.
+ * @typedef {Object} HistoryItem
+ * @property {string} type
+ * @property {string} [role]
+ * @property {Array<Object>} [content]
+ * @property {string} [name]
+ * @property {string} [arguments]
+ * @property {string} [call_id]
+ * @property {string} [output]
+ */
+
+/**
+ * A persisted conversation session.
+ * @typedef {Object} Session
+ * @property {string} id
+ * @property {string} created_at
+ * @property {string} updated_at
+ * @property {string} cwd
+ * @property {string|null} model
+ * @property {string} [policy]
+ * @property {HistoryItem[]} history
+ */
+
+/**
+ * An OpenAI Responses API tool definition (function or server-side tool).
+ * @typedef {Object} ToolDefinition
+ * @property {string} type
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {Object} [parameters]
+ */
+
+/**
+ * Approval policy names.
+ * @typedef {"suggest"|"auto-edit"|"full-auto"} ApprovalPolicy
+ */
+
+export {};

package/src/ui/render.js

@@ -0,0 +1,47 @@
+import { marked } from "marked";
+import { markedTerminal } from "marked-terminal";
+import chalk from "chalk";
+
+// Configure marked to render Markdown for the terminal (bold, lists, tables,
+// and syntax-highlighted code blocks via cli-highlight, which marked-terminal
+// uses internally).
+let configured = false;
+function ensureConfigured() {
+  if (configured) return;
+  marked.use(
+    markedTerminal({
+      // Tasteful, modern palette. marked-terminal accepts chalk functions.
+      code: chalk.cyan,
+      blockquote: chalk.gray.italic,
+      heading: chalk.bold.white,
+      firstHeading: chalk.bold.white,
+      strong: chalk.bold,
+      em: chalk.italic,
+      link: chalk.blue.underline,
+      href: chalk.blue.underline,
+      listitem: (text) => text,
+      reflowText: false,
+      width: Math.min(process.stdout.columns || 80, 100),
+    })
+  );
+  configured = true;
+}
+
+/**
+ * Render a Markdown string to styled terminal text.
+ * @param {string} md
+ * @returns {string}
+ */
+export function renderMarkdown(md) {
+  // chalk.level === 0 means colors are disabled (NO_COLOR / non-TTY without
+  // FORCE_COLOR). In that case marked-terminal still adds useful structure
+  // (indentation, bullets), so we render anyway but it stays plain.
+  ensureConfigured();
+  try {
+    // marked may return a promise if async extensions are used; ours are sync.
+    const out = /** @type {string} */ (marked.parse(md));
+    return typeof out === "string" ? out.replace(/\n$/, "") : md;
+  } catch {
+    return md;
+  }
+}

package/src/ui/theme.js

@@ -0,0 +1,114 @@
+import chalk from "chalk";
+import boxen from "boxen";
+import ora from "ora";
+
+// Terminal styling built on chalk (color), boxen (frames), and ora (spinner).
+// chalk auto-detects color support and respects NO_COLOR, so we don't need a
+// manual on/off switch here.
+
+/**
+ * Color helpers. Thin wrappers over chalk so the rest of the app has a stable
+ * surface and we can restyle in one place.
+ */
+export const c = {
+  reset: "",
+  bold: (s) => chalk.bold(s),
+  dim: (s) => chalk.dim(s),
+  italic: (s) => chalk.italic(s),
+  red: (s) => chalk.red(s),
+  green: (s) => chalk.green(s),
+  yellow: (s) => chalk.yellow(s),
+  blue: (s) => chalk.blue(s),
+  magenta: (s) => chalk.magenta(s),
+  cyan: (s) => chalk.cyan(s),
+  gray: (s) => chalk.gray(s),
+  // Brand accent used for the wordmark and prompt.
+  accent: (s) => chalk.hex("#a78bfa")(s),
+};
+
+export function termWidth() {
+  return Math.min(process.stdout.columns || 80, 100);
+}
+
+/**
+ * Horizontal rule, optionally with a left-aligned label.
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function rule(label = "") {
+  const width = termWidth();
+  if (!label) return chalk.gray("─".repeat(width));
+  // strip ANSI for length math
+  const plain = label.replace(/\x1b\[[0-9;]*m/g, "");
+  const prefix = "── ";
+  const rest = Math.max(0, width - prefix.length - plain.length - 1);
+  return chalk.gray(prefix) + label + " " + chalk.gray("─".repeat(rest));
+}
+
+/**
+ * Render content inside a rounded box.
+ * @param {string} content
+ * @param {{ title?: string, borderColor?: string, dimBorder?: boolean }} [opts]
+ * @returns {string}
+ */
+export function box(content, opts = {}) {
+  return boxen(content, {
+    padding: { top: 0, bottom: 0, left: 1, right: 1 },
+    borderStyle: "round",
+    borderColor: opts.borderColor || "gray",
+    dimBorder: opts.dimBorder ?? false,
+    title: opts.title,
+    width: termWidth(),
+  });
+}
+
+// Cat-flavored status phrases shown while the agent works. The UX is feline,
+// the visuals stay clean (no ASCII cat).
+const WORKING_PHRASES = [
+  "prowling",
+  "sniffing around",
+  "pawing through the code",
+  "on the hunt",
+  "stalking the bug",
+  "thinking",
+];
+
+export function randomWorkingPhrase() {
+  return WORKING_PHRASES[Math.floor(Math.random() * WORKING_PHRASES.length)];
+}
+
+/**
+ * Create an ora-backed spinner. Returns a small wrapper with the same surface
+ * the rest of the app already uses (start/setText/stop).
+ * @param {string} [text]
+ */
+export function createSpinner(text = "thinking") {
+  const spinner = ora({
+    text: chalk.dim(text),
+    spinner: "dots",
+    color: "magenta",
+    // ora handles non-TTY by silently no-op rendering.
+  });
+  return {
+    start() {
+      spinner.start();
+    },
+    setText(t) {
+      spinner.text = chalk.dim(t);
+    },
+    stop() {
+      spinner.stop();
+    },
+  };
+}
+
+// Symbols used across the UI. Clean and modern; the cat personality lives in
+// the wording, not in ASCII faces.
+export const sym = {
+  ok: chalk.green("✓"),
+  fail: chalk.red("✗"),
+  bullet: chalk.gray("·"),
+  arrow: chalk.hex("#a78bfa")("❯"),
+  tool: chalk.blue("⚙"),
+  warn: chalk.yellow("!"),
+};