pi-codemcp 0.1.0

package/src/json-file.ts

@@ -0,0 +1,54 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+export type JsonRecord = Record<string, unknown>;
+
+export function readJsonObject(path: string, label: string): JsonRecord {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON`, { cause: error });
+  }
+  return requireJsonObject(parsed, label);
+}
+
+export function requireJsonObject(value: unknown, label: string): JsonRecord {
+  if (!isJsonRecord(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  return value;
+}
+
+export function writeJsonObjectAtomically(path: string, value: JsonRecord): void {
+  const directory = dirname(path);
+  mkdirSync(directory, { recursive: true });
+  const temporary = join(directory, `.${process.pid}.${Date.now()}.tmp`);
+  const mode = existsSync(path) ? statSync(path).mode : 0o600;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    mode,
+  });
+  try {
+    renameSync(temporary, path);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Preserve the original write error.
+    }
+    throw error;
+  }
+}
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/lifecycle.ts

@@ -0,0 +1,59 @@
+import { SidecarClient, type SidecarClientOptions, type SidecarToolName } from "./mcp-client.js";
+import { type CodeMcpSettings, loadCodeMcpSettings } from "./settings.js";
+
+export class CodeMcpLifecycle {
+  readonly sidecar: SidecarClient;
+  private reloadBarrier: Promise<void> = Promise.resolve();
+
+  constructor(options: SidecarClientOptions = {}) {
+    this.sidecar = new SidecarClient(options);
+  }
+
+  get configPath(): string {
+    return this.sidecar.configPath;
+  }
+
+  get settingsPath(): string {
+    return this.sidecar.settingsPath;
+  }
+
+  get chainsPath(): string {
+    return this.sidecar.chainsPath;
+  }
+
+  get projectChainsPath(): string | undefined {
+    return this.sidecar.projectChainsPath;
+  }
+
+  configureProjectChains(path: string | undefined): void {
+    this.sidecar.configureProjectChains(path);
+  }
+
+  loadSettings(): CodeMcpSettings {
+    return loadCodeMcpSettings(this.settingsPath);
+  }
+
+  async request(
+    name: SidecarToolName,
+    args: Record<string, unknown>,
+    signal?: AbortSignal,
+  ): Promise<Record<string, unknown>> {
+    await this.reloadBarrier;
+    return this.sidecar.call(name, args, signal);
+  }
+
+  async warmup(): Promise<void> {
+    await this.request("status", {});
+  }
+
+  reload(): Promise<void> {
+    const operation = this.reloadBarrier.then(() => this.sidecar.close());
+    this.reloadBarrier = operation.catch(() => undefined);
+    return operation;
+  }
+
+  async shutdown(): Promise<void> {
+    await this.reloadBarrier;
+    await this.sidecar.close();
+  }
+}

package/src/mcp-client.ts

@@ -0,0 +1,303 @@
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { loadCodeMcpSettings } from "./settings.js";
+
+type JsonObject = Record<string, unknown>;
+
+export type SidecarToolName =
+  | "search"
+  | "discover"
+  | "reload_settings"
+  | "apply_manager_changes"
+  | "execute"
+  | "save_chain"
+  | "list_chains"
+  | "execute_chain"
+  | "revalidate_chain"
+  | "delete_chain"
+  | "status";
+
+const LONG_RUNNING_TOOLS = new Set<SidecarToolName>([
+  "execute",
+  "save_chain",
+  "execute_chain",
+  "revalidate_chain",
+]);
+
+export interface SidecarClientOptions {
+  packageRoot?: string;
+  agentDir?: string;
+  environment?: Record<string, string>;
+  projectChainsPath?: string;
+}
+
+export class SidecarClient {
+  private readonly packageRoot: string;
+  private readonly packageVersion: string;
+  private readonly agentDir: string;
+  private readonly environment: Record<string, string>;
+  private client: Client | undefined;
+  private transport: StdioClientTransport | undefined;
+  private startPromise: Promise<void> | undefined;
+  private closePromise: Promise<void> | undefined;
+  private projectChainsDirectory: string | undefined;
+  private stderrTail = "";
+
+  constructor(options: SidecarClientOptions = {}) {
+    this.packageRoot = resolve(
+      options.packageRoot ?? fileURLToPath(new URL("..", import.meta.url)),
+    );
+    this.packageVersion = readPackageVersion(this.packageRoot);
+    this.agentDir = resolve(options.agentDir ?? getAgentDir());
+    this.projectChainsDirectory = options.projectChainsPath
+      ? resolve(options.projectChainsPath)
+      : undefined;
+    this.environment = {
+      ...definedProcessEnvironment(),
+      ...(options.environment ?? {}),
+      PI_CODEMCP_AGENT_DIR: this.agentDir,
+      ...(this.projectChainsDirectory === undefined
+        ? {}
+        : { PI_CODEMCP_PROJECT_CHAINS_DIR: this.projectChainsDirectory }),
+      UV_PROJECT_ENVIRONMENT: join(this.agentDir, "pi-codemcp", "runtime", "venv"),
+    };
+    if (this.projectChainsDirectory === undefined) {
+      delete this.environment.PI_CODEMCP_PROJECT_CHAINS_DIR;
+    }
+  }
+
+  get configPath(): string {
+    return join(this.agentDir, "mcp.json");
+  }
+
+  get settingsPath(): string {
+    return join(this.agentDir, "pi-codemcp", "settings.json");
+  }
+
+  get chainsPath(): string {
+    return join(this.agentDir, "pi-codemcp", "chains");
+  }
+
+  get projectChainsPath(): string | undefined {
+    return this.projectChainsDirectory;
+  }
+
+  configureProjectChains(path: string | undefined): void {
+    const resolved = path === undefined ? undefined : resolve(path);
+    if (resolved === this.projectChainsDirectory) return;
+    if (this.client || this.transport || this.startPromise || this.closePromise) {
+      throw new Error("Cannot change CodeMCP project chain scope after the sidecar has started");
+    }
+    this.projectChainsDirectory = resolved;
+    if (resolved === undefined) delete this.environment.PI_CODEMCP_PROJECT_CHAINS_DIR;
+    else this.environment.PI_CODEMCP_PROJECT_CHAINS_DIR = resolved;
+  }
+
+  get pid(): number | null {
+    return this.transport?.pid ?? null;
+  }
+
+  get connected(): boolean {
+    return this.client !== undefined && this.transport?.pid !== null;
+  }
+
+  async call(name: SidecarToolName, args: JsonObject, signal?: AbortSignal): Promise<JsonObject> {
+    await this.ensureStarted(signal);
+    const client = this.client;
+    if (!client) throw new Error("Sidecar client failed to initialize");
+    const timeout = LONG_RUNNING_TOOLS.has(name)
+      ? loadCodeMcpSettings(this.settingsPath).executionTimeoutSeconds * 1_000 + 5_000
+      : 30_000;
+    const result = await client.callTool({ name, arguments: args }, undefined, {
+      timeout,
+      ...(signal === undefined ? {} : { signal }),
+    });
+
+    if (result.isError) {
+      throw new Error(textContent(result.content) || `Sidecar tool ${name} failed`);
+    }
+    if (isJsonObject(result.structuredContent)) {
+      return result.structuredContent;
+    }
+
+    const text = textContent(result.content);
+    if (!text) {
+      throw new Error(`Sidecar tool ${name} returned no structured result`);
+    }
+    const parsed: unknown = JSON.parse(text);
+    if (!isJsonObject(parsed)) {
+      throw new Error(`Sidecar tool ${name} returned a non-object result`);
+    }
+    return parsed;
+  }
+
+  async close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.closeInternal();
+    try {
+      await this.closePromise;
+    } finally {
+      this.closePromise = undefined;
+    }
+  }
+
+  private async ensureStarted(signal?: AbortSignal): Promise<void> {
+    if (this.client && this.transport && !this.startPromise) return;
+    if (!this.startPromise) {
+      this.startPromise = this.start(signal).catch(async (error: unknown) => {
+        await this.closeInternal();
+        const detail = this.stderrTail.trim();
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(detail ? `${message}\n${detail}` : message, { cause: error });
+      });
+    }
+
+    const startPromise = this.startPromise;
+    try {
+      await startPromise;
+    } finally {
+      if (this.startPromise === startPromise) this.startPromise = undefined;
+    }
+  }
+
+  private async start(signal?: AbortSignal): Promise<void> {
+    this.stderrTail = "";
+    const transport = new StdioClientTransport({
+      command: prepareBundledUv(this.packageRoot, this.agentDir),
+      args: [
+        "run",
+        ...(isTruthy(process.env.PI_OFFLINE) ? ["--offline"] : []),
+        "--project",
+        "sidecar",
+        "--frozen",
+        "--no-dev",
+        "-m",
+        "sidecar.gateway",
+      ],
+      cwd: this.packageRoot,
+      env: this.environment,
+      stderr: "pipe",
+    });
+    transport.stderr?.on("data", (chunk: Buffer | string) => {
+      this.stderrTail = `${this.stderrTail}${chunk.toString()}`.slice(-8192);
+    });
+
+    const client = new Client({
+      name: "pi-codemcp",
+      version: this.packageVersion,
+    });
+    this.transport = transport;
+    this.client = client;
+    await client.connect(transport, {
+      timeout: 310_000,
+      ...(signal === undefined ? {} : { signal }),
+    });
+  }
+
+  private async closeInternal(): Promise<void> {
+    const client = this.client;
+    const transport = this.transport;
+    this.client = undefined;
+    this.transport = undefined;
+    this.startPromise = undefined;
+
+    if (client) {
+      try {
+        await client.close();
+      } finally {
+        if (transport) await transport.close();
+      }
+    } else if (transport) {
+      await transport.close();
+    }
+  }
+}
+
+function readPackageVersion(packageRoot: string): string {
+  const packageJson = join(packageRoot, "package.json");
+  const metadata: unknown = JSON.parse(readFileSync(packageJson, "utf8"));
+  if (!isJsonObject(metadata) || typeof metadata.version !== "string") {
+    throw new Error(`pi-codemcp package has invalid metadata: ${packageJson}`);
+  }
+  return metadata.version;
+}
+
+function prepareBundledUv(packageRoot: string, agentDir: string): string {
+  const packageRequire = createRequire(join(packageRoot, "package.json"));
+  const platformPackage = `@manzt/uv-${process.platform}-${process.arch}`;
+  let packageJson: string;
+  try {
+    packageJson = packageRequire.resolve(`${platformPackage}/package.json`);
+  } catch (error) {
+    throw new Error(
+      `Bundled uv is unavailable for ${process.platform}/${process.arch}; reinstall pi-codemcp with optional dependencies enabled`,
+      { cause: error },
+    );
+  }
+  const metadata: unknown = JSON.parse(readFileSync(packageJson, "utf8"));
+  if (!isJsonObject(metadata) || typeof metadata.version !== "string") {
+    throw new Error(`Bundled uv package has invalid metadata: ${packageJson}`);
+  }
+
+  const binaryName = process.platform === "win32" ? "uv.exe" : "uv";
+  const source = join(dirname(packageJson), "bin", binaryName);
+  if (!existsSync(source)) {
+    throw new Error(`Bundled uv executable is missing: ${source}`);
+  }
+
+  const runtimeDirectory = join(agentDir, "pi-codemcp", "runtime", "uv", metadata.version);
+  const executable = join(runtimeDirectory, binaryName);
+  if (existsSync(executable)) return executable;
+
+  mkdirSync(runtimeDirectory, { recursive: true });
+  const temporary = `${executable}.${process.pid}.tmp`;
+  copyFileSync(source, temporary);
+  if (process.platform !== "win32") chmodSync(temporary, 0o755);
+  try {
+    renameSync(temporary, executable);
+  } catch (error) {
+    if (!existsSync(executable)) throw error;
+    unlinkSync(temporary);
+  }
+  return executable;
+}
+
+function definedProcessEnvironment(): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(process.env).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined,
+    ),
+  );
+}
+
+function isTruthy(value: string | undefined): boolean {
+  return value !== undefined && ["1", "true", "yes"].includes(value.toLowerCase());
+}
+
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function textContent(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (item): item is { type: "text"; text: string } =>
+        isJsonObject(item) && item.type === "text" && typeof item.text === "string",
+    )
+    .map((item) => item.text)
+    .join("\n");
+}