@chatcut/cli 0.0.0-stage → 0.1.1

package/src/doctor.mjs

@@ -0,0 +1,339 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { ensureDesktop, inspectDesktop } from "./desktop.mjs";
+import { DiagnosticError, probeMcp, requestDesktop } from "./rpc.mjs";
+
+export function errorEvidence(error) {
+  if (typeof error.toJSON === "function") return error.toJSON();
+  return {
+    code: error.code ?? "diagnostic_failed",
+    message: error.message ?? String(error),
+    stage: error.stage ?? "diagnostic",
+    ...(error.cause
+      ? {
+          cause: {
+            code: error.cause.code,
+            message: error.cause.message ?? String(error.cause),
+          },
+        }
+      : {}),
+  };
+}
+
+export async function readDesktopEndpoint(desktop) {
+  const contents = await readFile(desktop.launcherPath, "utf8");
+  let socketPath;
+  if (desktop.platform === "win32") {
+    socketPath = contents.match(
+      /^set "CHATCUT_MCP_SOCKET=([^\r\n]*)"\r?$/m,
+    )?.[1];
+  } else {
+    const quoted = contents.match(/^export CHATCUT_MCP_SOCKET=('.*')$/m)?.[1];
+    if (quoted && /^'(?:[^']|'\\'')*'$/.test(quoted))
+      socketPath = quoted.slice(1, -1).replaceAll("'\\''", "'");
+  }
+  if (!socketPath)
+    throw new DiagnosticError(
+      "invalid_launcher",
+      "desktop",
+      "The Desktop MCP launcher has no readable socket path. Open ChatCut to refresh it.",
+    );
+  const capability = (
+    await readFile(
+      path.join(desktop.userDataPath, "mcp-invocation-capability"),
+      "utf8",
+    )
+  ).trim();
+  if (!/^[A-Za-z0-9_-]{43}$/.test(capability))
+    throw new DiagnosticError(
+      "invalid_capability",
+      "desktop",
+      "The Desktop IPC capability is missing or invalid. Open ChatCut to refresh it.",
+    );
+  return { capability, socketPath };
+}
+
+export async function runDoctor(options = {}, dependencies = {}) {
+  const { client, fix = false } = options;
+  const inspect = dependencies.inspect ?? inspectDesktop;
+  const ensure = dependencies.ensure ?? ensureDesktop;
+  const probe = dependencies.probe ?? probeMcp;
+  const checks = [];
+  const findings = [];
+  let desktop = await inspect(options);
+  let repair;
+  let state;
+  if (fix) desktop = await ensure(options);
+  checks.push({
+    id: "desktop",
+    message: desktop.installed
+      ? `ChatCut ${desktop.version ?? ""} is installed.`.replaceAll("  ", " ")
+      : "ChatCut Desktop is not installed. Run chatcut app.",
+    path: desktop.appPath,
+    status: desktop.installed ? "pass" : "fail",
+  });
+  if (desktop.installed) {
+    try {
+      const result = await inspectRunningDesktop(desktop, {
+        ...dependencies,
+        client,
+        env: options.env,
+        fix,
+        platform: desktop.platform,
+      });
+      repair = result.repair;
+      state = result;
+      checks.push({
+        id: "desktop-inspection",
+        message: "Desktop answered the authenticated diagnostic request.",
+        status: "pass",
+      });
+      for (const [name, integration] of Object.entries(
+        result.integrations ?? {},
+      )) {
+        if (
+          integration.status === "unavailable" ||
+          integration.status === "disabled" ||
+          integration.status === "opted-out"
+        ) {
+          findings.push({
+            id: `integration-${name}`,
+            message: `${name}: ${integration.status}.`,
+            status: "info",
+          });
+          continue;
+        }
+        const connected =
+          integration.status === "connected" && !integration.errorMessage;
+        checks.push({
+          id: `integration-${name}`,
+          message: `${name}: ${integration.status}.`,
+          status: connected ? "pass" : "fail",
+          ...(integration.errorMessage
+            ? {
+                error: {
+                  code: integration.errorCode,
+                  message: integration.errorMessage,
+                  stage: integration.stage,
+                },
+              }
+            : {}),
+        });
+        if (integration.restartRequired)
+          findings.push({
+            id: `restart-${name}`,
+            message: `Start a new ${name} conversation to load the current MCP connection and skills.`,
+            status: "info",
+          });
+      }
+      if (result.account?.status === "sign-in-required")
+        findings.push({
+          id: "account",
+          message:
+            "Sign in inside ChatCut to use account-dependent online features.",
+          status: "info",
+        });
+      for (const [target, skills] of Object.entries(
+        result.skills?.targets ?? {},
+      )) {
+        const host = { chatGpt: "codex", claudeCode: "claude-code" }[target];
+        const required =
+          !host || result.integrations?.[host]?.status === "connected";
+        const stale =
+          skills.stale?.filter((name) => !skills.modified?.includes(name)) ??
+          [];
+        checks.push({
+          id: `skills-${target}`,
+          message: `${skills.names?.length ?? 0} ChatCut skills expected for ${target}${required ? "" : " (host unavailable, disconnected or opted out)"}.`,
+          path: skills.root,
+          status:
+            !required ||
+            (!skills.errorMessage &&
+              !skills.missing?.length &&
+              !stale.length &&
+              !skills.outdated?.length)
+              ? "pass"
+              : "fail",
+          ...(skills.errorMessage
+            ? {
+                error: {
+                  code: skills.errorCode,
+                  message: skills.errorMessage,
+                  stage: skills.stage,
+                },
+              }
+            : {}),
+          ...(skills.missing?.length ? { missing: skills.missing } : {}),
+          ...(stale.length ? { stale } : {}),
+          ...(skills.outdated?.length ? { outdated: skills.outdated } : {}),
+        });
+        if (skills.modified?.length || skills.foreign?.length)
+          findings.push({
+            foreign: skills.foreign,
+            id: `preserved-skills-${target}`,
+            message:
+              "User-modified or foreign skill paths are preserved; inspect overlaps before changing them.",
+            modified: skills.modified,
+            path: skills.root,
+            status: "info",
+          });
+        if (skills.overlaps?.length)
+          findings.push({
+            id: `skill-overlaps-${target}`,
+            message:
+              "These skill names overlap. A name match alone does not prove duplicate loading or justify deletion.",
+            overlaps: skills.overlaps,
+            path: skills.root,
+            status: "info",
+          });
+      }
+      if (repair?.errors?.length)
+        checks.push({
+          errors: repair.errors,
+          id: "repair",
+          message: "Some repairs failed; see the original errors.",
+          status: "fail",
+        });
+    } catch (error) {
+      checks.push({
+        error: errorEvidence(error),
+        id: "desktop-inspection",
+        message:
+          "Desktop inspection did not complete. Open ChatCut, or update it if doctor support is unavailable.",
+        status: "fail",
+      });
+    }
+    try {
+      const mcp = await probe({
+        command: desktop.launcherPath,
+        env: options.env,
+        platform: desktop.platform,
+      });
+      checks.push({
+        evidence: mcp,
+        id: "mcp",
+        message:
+          "MCP initialization, tool discovery and get_active_project succeeded.",
+        status: "pass",
+      });
+    } catch (error) {
+      checks.push({
+        error: errorEvidence(error),
+        id: "mcp",
+        message: "The MCP connection did not complete a read-only tool call.",
+        status: "fail",
+      });
+    }
+  }
+  findings.push({
+    id: "host-session",
+    message:
+      "This probes a new local MCP client. The current agent conversation's loaded tools and skills must be checked in that conversation; start a new conversation after connection or skill changes.",
+    status: "info",
+  });
+  const ok = checks.every((check) => check.status !== "fail");
+  return {
+    checks,
+    command: "doctor",
+    desktop,
+    findings,
+    ok,
+    repairRequested: fix,
+    schemaVersion: 1,
+    ...(repair ? { repair } : {}),
+    ...(state ? { state } : {}),
+  };
+}
+
+async function inspectRunningDesktop(
+  desktop,
+  {
+    client,
+    endpoint = readDesktopEndpoint,
+    env = process.env,
+    expectedProfile = "production",
+    fix,
+    platform = process.platform,
+    request = requestDesktop,
+    wait = delay,
+  },
+) {
+  const deadline = Date.now() + (fix ? 20_000 : 0);
+  const target = { client, env, expectedProfile, platform };
+  for (;;) {
+    try {
+      const connection = await endpoint(desktop);
+      const report = await request({
+        ...connection,
+        client,
+        method: "desktop.doctor",
+      });
+      validateDesktopReport(report, target);
+      if (!fix) return report;
+      const repaired = await request({
+        ...connection,
+        client,
+        method: "desktop.repair",
+      });
+      validateDesktopReport(repaired, target);
+      return repaired;
+    } catch (error) {
+      if (
+        fix &&
+        ["ECONNREFUSED", "ENOENT"].includes(error.code) &&
+        Date.now() < deadline
+      ) {
+        await wait(250);
+        continue;
+      }
+      if (error.code === -32601)
+        throw new DiagnosticError(
+          "desktop_update_required",
+          "desktop",
+          "This Desktop version does not provide doctor diagnostics. Run chatcut update after closing ChatCut.",
+          { cause: error },
+        );
+      throw error;
+    }
+  }
+}
+
+function validateDesktopReport(
+  report,
+  { client, env, expectedProfile, platform },
+) {
+  if (report?.version !== 1)
+    throw new DiagnosticError(
+      "unsupported_doctor_report",
+      "desktop",
+      "Desktop returned an unsupported doctor report.",
+    );
+  if (report.profileId !== expectedProfile)
+    throw new DiagnosticError(
+      "profile_mismatch",
+      "desktop",
+      `Expected the ${expectedProfile} Desktop profile, received ${report.profileId}. Repair must target the selected profile.`,
+    );
+  for (const [host, target, variable] of [
+    ["codex", "chatGpt", "CODEX_HOME"],
+    ["claude-code", "claudeCode", "CLAUDE_CONFIG_DIR"],
+  ]) {
+    const root = report.skills?.targets?.[target]?.root;
+    const paths = platform === "win32" ? path.win32 : path.posix;
+    const selectedRoot =
+      env[variable] && paths.resolve(env[variable], "skills");
+    const reportedRoot = root && paths.resolve(root);
+    const sameRoot =
+      platform === "win32"
+        ? selectedRoot?.toLowerCase() === reportedRoot?.toLowerCase()
+        : selectedRoot === reportedRoot;
+    if ((!client || client === host) && env[variable] && root && !sameRoot)
+      throw new DiagnosticError(
+        "agent_home_mismatch",
+        "desktop",
+        `${host} in Desktop uses a different ${variable} skill root (${root}). Start Desktop in the intended host environment before repair.`,
+      );
+  }
+}

package/src/rpc.mjs

@@ -0,0 +1,360 @@
+import { spawn } from "node:child_process";
+import { connect } from "node:net";
+import { StringDecoder } from "node:string_decoder";
+
+import packageInfo from "../package.json" with { type: "json" };
+
+const MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
+const PROTOCOL_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05",
+];
+
+export class DiagnosticError extends Error {
+  constructor(code, stage, message, options = {}) {
+    super(message, options);
+    this.code = code;
+    this.stage = stage;
+  }
+}
+
+export async function probeMcp({
+  args = [],
+  command,
+  env = process.env,
+  platform = process.platform,
+  spawnProcess = spawn,
+  timeoutMs = 20_000,
+}) {
+  const childEnv = { ...env };
+  for (const key of Object.keys(childEnv)) {
+    if (key.startsWith("CHATCUT_MCP_")) delete childEnv[key];
+  }
+  const isWindowsScript = platform === "win32" && /\.(cmd|bat)$/i.test(command);
+  if (isWindowsScript && (/[\r\n\0"]/u.test(command) || args.length))
+    throw new DiagnosticError(
+      "invalid_launcher",
+      "transport",
+      "The Windows MCP launcher must be an unquoted path without arguments.",
+    );
+  if (isWindowsScript) childEnv.CHATCUT_DOCTOR_LAUNCHER = command;
+  const child = spawnProcess(
+    isWindowsScript ? (env.ComSpec ?? env.COMSPEC ?? "cmd.exe") : command,
+    isWindowsScript
+      ? ["/d", "/s", "/c", '""%CHATCUT_DOCTOR_LAUNCHER%""']
+      : args,
+    {
+      env: childEnv,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+      ...(isWindowsScript ? { windowsVerbatimArguments: true } : {}),
+    },
+  );
+  let stderr = "";
+  let stopped = false;
+  child.stderr.on("data", (chunk) => {
+    if (stderr.length < 64 * 1024)
+      stderr += chunk.toString("utf8").slice(0, 64 * 1024 - stderr.length);
+  });
+  const channel = createRpcChannel(
+    child.stdout,
+    (message) => child.stdin.write(`${JSON.stringify(message)}\n`),
+    timeoutMs,
+  );
+  const overallTimer = setTimeout(
+    () =>
+      channel.fail(
+        new DiagnosticError(
+          "timeout",
+          "probe",
+          "The complete MCP diagnostic exceeded 60 seconds.",
+        ),
+      ),
+    60_000,
+  );
+  child.on("error", (cause) =>
+    channel.fail(
+      new DiagnosticError(
+        cause.code ?? "spawn_failed",
+        "transport",
+        cause.message,
+        { cause },
+      ),
+    ),
+  );
+  child.stdin.on("error", (cause) => channel.fail(cause));
+  child.on("exit", (code, signal) => {
+    stopped = true;
+    channel.fail(
+      new DiagnosticError(
+        "process_exited",
+        "transport",
+        `MCP process exited (${signal ?? code}).${stderr ? ` ${stderr.trim()}` : ""}`,
+      ),
+    );
+  });
+  try {
+    const initialized = await channel.request("initialize", {
+      capabilities: {},
+      clientInfo: { name: "chatcut-doctor", version: packageInfo.version },
+      protocolVersion: PROTOCOL_VERSIONS[0],
+    });
+    if (
+      !PROTOCOL_VERSIONS.includes(initialized?.protocolVersion) ||
+      !initialized.capabilities?.tools
+    ) {
+      throw new DiagnosticError(
+        "unsupported_mcp_server",
+        "initialize",
+        "The server did not negotiate a supported MCP version with tools.",
+      );
+    }
+    channel.notify("notifications/initialized");
+    const names = new Set();
+    let cursor;
+    const cursors = new Set();
+    for (let page = 0; page < 20; page++) {
+      const result = await channel.request(
+        "tools/list",
+        cursor ? { cursor } : {},
+      );
+      if (!Array.isArray(result?.tools))
+        throw new DiagnosticError(
+          "invalid_tools_list",
+          "tools/list",
+          "The server returned no tools array.",
+        );
+      for (const tool of result.tools)
+        if (typeof tool.name === "string") names.add(tool.name);
+      cursor = result.nextCursor;
+      if (!cursor) break;
+      if (typeof cursor !== "string" || cursors.has(cursor) || page === 19)
+        throw new DiagnosticError(
+          "invalid_tools_pagination",
+          "tools/list",
+          "MCP tool pagination did not complete within 20 pages.",
+        );
+      cursors.add(cursor);
+    }
+    if (!names.has("get_active_project"))
+      throw new DiagnosticError(
+        "missing_discovery_tool",
+        "tools/list",
+        "ChatCut's get_active_project tool is missing.",
+      );
+    const result = await channel.request("tools/call", {
+      arguments: {},
+      name: "get_active_project",
+    });
+    if (result?.isError) {
+      const message = result.content
+        ?.filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n");
+      throw new DiagnosticError(
+        "tool_call_failed",
+        "tools/call",
+        message || "get_active_project returned an error.",
+      );
+    }
+    if (!result || !Array.isArray(result.content))
+      throw new DiagnosticError(
+        "invalid_tool_result",
+        "tools/call",
+        "get_active_project returned an invalid MCP tool result.",
+      );
+    const server = initialized.serverInfo;
+    return {
+      hostSessionDiscovery: "unobserved",
+      protocolVersion: initialized.protocolVersion,
+      server: {
+        name: server?.name,
+        title: server?.title,
+        version: server?.version,
+      },
+      status: "pass",
+      toolCall: { name: "get_active_project", status: "pass" },
+      toolCount: names.size,
+    };
+  } finally {
+    clearTimeout(overallTimer);
+    child.stdin.end();
+    if (!stopped) {
+      child.kill();
+      const timer = setTimeout(() => {
+        if (!stopped) child.kill("SIGKILL");
+      }, 1_000);
+      timer.unref();
+    }
+  }
+}
+
+export async function requestDesktop({
+  capability,
+  client,
+  method,
+  socketPath,
+  timeoutMs = 30_000,
+}) {
+  const socket = connect(socketPath);
+  const channel = createRpcChannel(
+    socket,
+    (message) => socket.write(`${JSON.stringify(message)}\n`),
+    timeoutMs,
+  );
+  try {
+    return await channel.request(method, client ? { client } : {}, {
+      invocationCapability: capability,
+    });
+  } finally {
+    socket.destroy();
+  }
+}
+
+function createRpcChannel(stream, write, timeoutMs) {
+  const pending = new Map();
+  const decoder = new StringDecoder("utf8");
+  let buffer = "";
+  let nextId = 0;
+  let failure;
+
+  function fail(error) {
+    failure ??= error;
+    for (const request of pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(error);
+    }
+    pending.clear();
+  }
+
+  stream.on("data", (chunk) => {
+    buffer += decoder.write(chunk);
+    if (Buffer.byteLength(buffer) > MAX_MESSAGE_BYTES) {
+      fail(
+        new DiagnosticError(
+          "response_too_large",
+          "transport",
+          "MCP response exceeded 4 MiB.",
+        ),
+      );
+      return;
+    }
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (cause) {
+        fail(
+          new DiagnosticError(
+            "invalid_rpc_response",
+            "transport",
+            "The MCP process wrote non-JSON data to stdout.",
+            { cause },
+          ),
+        );
+        return;
+      }
+      if (
+        !message ||
+        typeof message !== "object" ||
+        message.jsonrpc !== "2.0"
+      ) {
+        fail(
+          new DiagnosticError(
+            "invalid_rpc_response",
+            "transport",
+            "Invalid JSON-RPC response.",
+          ),
+        );
+        return;
+      }
+      if (message.method) {
+        if (message.id !== undefined) {
+          write({
+            id: message.id,
+            jsonrpc: "2.0",
+            ...(message.method === "ping"
+              ? { result: {} }
+              : {
+                  error: {
+                    code: -32601,
+                    message: "Unsupported diagnostic client request",
+                  },
+                }),
+          });
+        }
+        continue;
+      }
+      const waiting = pending.get(message.id);
+      if (!waiting) continue;
+      clearTimeout(waiting.timer);
+      pending.delete(message.id);
+      if (message.error) {
+        waiting.reject(
+          new DiagnosticError(
+            message.error.code ?? "rpc_error",
+            waiting.method,
+            message.error.message ?? "JSON-RPC request failed.",
+          ),
+        );
+      } else if (Object.hasOwn(message, "result")) {
+        waiting.resolve(message.result);
+      } else {
+        waiting.reject(
+          new DiagnosticError(
+            "invalid_rpc_response",
+            waiting.method,
+            "JSON-RPC response contains neither result nor error.",
+          ),
+        );
+      }
+    }
+  });
+  stream.on("error", fail);
+  stream.on("end", () =>
+    fail(
+      new DiagnosticError(
+        "connection_closed",
+        "transport",
+        "The MCP connection closed before completing the diagnostic.",
+      ),
+    ),
+  );
+
+  return {
+    fail,
+    notify(method, params = {}) {
+      write({ jsonrpc: "2.0", method, params });
+    },
+    request(method, params = {}, extra = {}) {
+      if (failure) return Promise.reject(failure);
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(
+            new DiagnosticError(
+              "timeout",
+              method,
+              `${method} did not respond within ${timeoutMs} ms.`,
+            ),
+          );
+        }, timeoutMs);
+        pending.set(id, { method, reject, resolve, timer });
+        try {
+          write({ id, jsonrpc: "2.0", method, params, ...extra });
+        } catch (error) {
+          clearTimeout(timer);
+          pending.delete(id);
+          reject(error);
+        }
+      });
+    },
+  };
+}