premanmcp 0.10.6 → 0.10.7

package/bin/connect/checkin.js

@@ -0,0 +1,503 @@
+/**
+ * Getting the first PreMan call to happen, so nobody has to be told to restart.
+ *
+ * Three routes to the same check-in, cheapest first: run the MCP server
+ * ourselves over stdio, open the user's agent, or wait. The terminal-opening
+ * machinery is here because "we ran your agent for you" is only true if the
+ * window it lands in is the one they go on to use.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { callBackendJson, onPath } from "../shared.js";
+
+import { findAgent } from "./agents.js";
+import { shellQuote } from "./configs.js";
+
+const MCP_CONNECT_SOURCES = new Set([
+  "mcp",
+  "preman_status",
+  "premanmcp",
+  "agent",
+  "mcp_call_tool",
+]);
+
+export async function waitForConnection(
+  args,
+  apiKey,
+  {
+    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+    timeoutMs = Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000,
+    expectedAgent = "",
+    pairingId = "",
+    stopWhen = null,
+    // Called once per unsuccessful poll, so a wait measured in minutes can show
+    // that it is still a wait rather than a hang.
+    onPoll = null,
+  } = {}
+) {
+  const deadline = Date.now() + timeoutMs;
+  let interrupted = false;
+  const onInterrupt = () => {
+    interrupted = true;
+  };
+  process.on("SIGINT", onInterrupt);
+
+  try {
+    while (Date.now() < deadline && !interrupted) {
+      const status = await callBackendJson(
+        args,
+        "GET",
+        pairingId
+          ? `/workbench/coding-agent/pairings/${encodeURIComponent(pairingId)}`
+          : "/workbench/coding-agent",
+        { token: apiKey }
+      );
+      const pairingStatus = pairingId ? String(status.status || "") : "";
+      const connected = pairingId
+        ? pairingStatus === "connected"
+        : Boolean(status.connected);
+      const connectedAgent = pairingId ? status.connected_agent : status.agent;
+      const backendAgent = findAgent(connectedAgent)?.id || "";
+      const verifiedBy = String(status.verified_by || "").trim().toLowerCase();
+      if (
+        status.ok &&
+        connected &&
+        (!expectedAgent ||
+          (backendAgent === expectedAgent && MCP_CONNECT_SOURCES.has(verifiedBy)))
+      ) {
+        return true;
+      }
+      if (pairingId && (pairingStatus === "expired" || status.status_code === 404)) {
+        return false;
+      }
+      if (stopWhen && stopWhen()) return false;
+      if (onPoll) onPoll();
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  } finally {
+    process.off("SIGINT", onInterrupt);
+  }
+  return false;
+}
+
+/** A dot per poll, and the newline that closes the run of them. */
+export function pollTicker() {
+  let dots = 0;
+  return {
+    tick() {
+      dots += 1;
+      process.stdout.write(".");
+    },
+    end() {
+      if (!dots) return;
+      dots = 0;
+      process.stdout.write("\n");
+    },
+  };
+}
+
+// ── Auto check-in ───────────────────────────────────────────────────────
+
+/**
+ * How to ask each agent to make one PreMan call without opening its UI.
+ *
+ * The link is established by the agent's first call, so anything that reaches
+ * `preman_status` finishes the connect. Claude Code needs the server on its
+ * allow-list because print mode refuses un-allowed MCP tools rather than
+ * prompting.
+ */
+export function headlessCheckIn(agent, serverName) {
+  const prompt = checkInPrompt(serverName);
+  if (agent.id === "cursor") {
+    // Without --approve-mcps, cursor-agent starts with only built-in tools even
+    // when mcp.json lists PreMan — the first-time connect check-in then reports
+    // that the server is not connected.
+    return { bin: "cursor-agent", args: ["--approve-mcps", "-p", prompt] };
+  }
+  if (agent.id === "claude_code") {
+    return { bin: "claude", args: ["-p", prompt, "--allowedTools", `mcp__${serverName}`] };
+  }
+  if (agent.id === "codex") return { bin: "codex", args: ["exec", prompt] };
+  return null;
+}
+
+function checkInPrompt(serverName) {
+  return `Call the ${serverName} MCP tool preman_status and report the result.`;
+}
+
+/**
+ * How to start each agent as the session the user actually works in.
+ *
+ * Print mode (`-p`, `codex exec`) answers once and exits: it is a batch call, not
+ * the agent anybody goes on to use, and its failures are invisible because
+ * nobody is looking at it. The interactive form is the same prompt without that
+ * flag — it needs a terminal of its own, which is what openInNewTerminal is for.
+ */
+export function interactiveCheckIn(agent, serverName) {
+  const prompt = checkInPrompt(serverName);
+  if (agent.id === "cursor") return { bin: "cursor-agent", args: ["--approve-mcps", prompt] };
+  if (agent.id === "claude_code") {
+    return { bin: "claude", args: ["--allowedTools", `mcp__${serverName}`, prompt] };
+  }
+  if (agent.id === "codex") return { bin: "codex", args: [prompt] };
+  return null;
+}
+
+/** A command line for a spec, quoted for the shell the terminal will start. */
+export function commandLine(spec) {
+  return [spec.bin, ...spec.args].map(shellQuote).join(" ");
+}
+
+/** Escape a shell line into an AppleScript string literal. */
+function appleScriptString(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * The terminal emulator to open a window in, or null when we know of none.
+ *
+ * `sync` marks the launchers that hand the work to an app and return — those
+ * report their own failure through an exit code, which is worth waiting for.
+ * The rest *are* the window, so they are spawned detached and outlive us.
+ */
+function terminalLauncher(line) {
+  if (process.platform === "darwin") {
+    const iterm = existsSync("/Applications/iTerm.app");
+    const script = iterm
+      ? `tell application "iTerm"\nactivate\nset w to (create window with default profile)\ntell current session of w to write text ${appleScriptString(line)}\nend tell`
+      : `tell application "Terminal"\nactivate\ndo script ${appleScriptString(line)}\nend tell`;
+    return { bin: "osascript", args: ["-e", script], label: iterm ? "iTerm" : "Terminal", sync: true };
+  }
+
+  if (process.platform === "win32") {
+    return {
+      bin: "cmd.exe",
+      args: ["/c", "start", "cmd.exe", "/k", line],
+      label: "Command Prompt",
+      sync: true,
+    };
+  }
+
+  // Keep the shell alive afterwards: an agent that exits immediately would
+  // otherwise take its own error message off the screen with it.
+  const body = `${line}; exec ${process.env.SHELL || "sh"}`;
+  const candidates = [
+    { bin: "x-terminal-emulator", args: ["-e", "sh", "-c", body], label: "terminal" },
+    { bin: "gnome-terminal", args: ["--", "sh", "-c", body], label: "GNOME Terminal" },
+    { bin: "konsole", args: ["-e", "sh", "-c", body], label: "Konsole" },
+    { bin: "xterm", args: ["-e", "sh", "-c", body], label: "xterm" },
+  ];
+  return candidates.find((candidate) => onPath(candidate.bin)) || null;
+}
+
+/**
+ * Open `command` in a new terminal window, best effort.
+ *
+ * Same contract as openUrl: never throws, and declines rather than guessing when
+ * nobody is watching — `PREMAN_NO_TERMINAL` for an explicit no, and a non-TTY
+ * stdout for CI, piped output and test runs. Callers fall back to a headless run.
+ */
+export function openInNewTerminal(command, options = {}) {
+  const cwd = options?.cwd || process.cwd();
+  const optOut = (process.env.PREMAN_NO_TERMINAL || "").trim().toLowerCase();
+  if (optOut && !["0", "false", "no"].includes(optOut)) {
+    return { opened: false, reason: "PREMAN_NO_TERMINAL is set" };
+  }
+  if (!process.stdout.isTTY) return { opened: false, reason: "not running in a terminal" };
+
+  const launcher = terminalLauncher(`cd ${shellQuote(cwd)} && ${command}`);
+  if (!launcher) return { opened: false, reason: "no terminal emulator found" };
+
+  try {
+    if (launcher.sync) {
+      const done = spawnSync(launcher.bin, launcher.args, { stdio: "ignore", timeout: 20000 });
+      if (done.error) return { opened: false, reason: done.error.message };
+      if (done.status !== 0) {
+        return { opened: false, reason: `${launcher.bin} exited with code ${done.status}` };
+      }
+    } else {
+      const child = spawn(launcher.bin, launcher.args, { stdio: "ignore", detached: true });
+      child.unref();
+    }
+    return { opened: true, terminal: launcher.label };
+  } catch (error) {
+    return { opened: false, reason: error.message };
+  }
+}
+
+/**
+ * Finish the link ourselves instead of asking the user to go restart their agent.
+ *
+ * The config on disk is already correct at this point; all that is missing is
+ * one call from the agent, and telling someone to make it from another terminal
+ * is a dead end in the one terminal they are sitting in.
+ *
+ * So start the agent. Interactively, in a window of its own, because that is the
+ * session the user keeps: a print-mode run answers once, exits, and leaves them
+ * exactly where they started. Only when no window can be opened — CI, SSH, a
+ * machine with no terminal emulator — does this fall back to the headless run,
+ * which still finishes the link even though nobody sees it happen.
+ *
+ * `cwd` is where the agent starts, and it is load-bearing rather than tidiness:
+ * the MCP server reads its repo config out of the working directory, so starting
+ * the agent elsewhere is how a caller escapes a directory that would otherwise
+ * redirect it to a backend this key was never issued for.
+ *
+ * Returns `ran: false` when the agent's binary is absent or will not start, and
+ * the caller falls back to the printed instructions.
+ */
+export async function autoCheckIn(
+  args,
+  agent,
+  apiKey,
+  {
+    // Never outlast the connect's own wait budget: this phase is part of it, not
+    // an extra one bolted on the front.
+    timeoutMs = Math.min(
+      Number(process.env.PREMAN_AUTO_CHECKIN_MS) || 120000,
+      Number(process.env.PREMAN_CONNECT_WAIT_MS) || 300000
+    ),
+    serverName = "preman",
+    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+    cwd = process.cwd(),
+    pairingId = "",
+    onLaunch = () => {},
+    onPoll = null,
+  } = {}
+) {
+  const session = interactiveCheckIn(agent, serverName);
+  if (session && onPath(session.bin)) {
+    const { opened, terminal } = openInNewTerminal(commandLine(session), { cwd });
+    if (opened) {
+      onLaunch({ mode: "interactive", bin: session.bin, terminal });
+      // Detached, so there is no exit to watch for and no output to quote: the
+      // agent is in front of the user now, and the deadline is all that bounds
+      // this. Whoever is watching the window can Ctrl+C out of the wait.
+      const connected = await waitForConnection(args, apiKey, {
+        intervalMs,
+        timeoutMs,
+        expectedAgent: agent.id,
+        pairingId,
+        onPoll,
+      });
+      return { ran: true, connected, command: session.bin, interactive: true, terminal };
+    }
+  }
+
+  const spec = headlessCheckIn(agent, serverName);
+  if (!spec) return { ran: false, connected: false, reason: "no headless mode" };
+  if (!onPath(spec.bin)) return { ran: false, connected: false, reason: `${spec.bin} is not on PATH` };
+
+  let child;
+  try {
+    // Piped rather than ignored: an agent that runs and does not check in used to
+    // report exactly that and nothing else, which is the least useful sentence
+    // available. Its own last words usually name the cause.
+    child = spawn(spec.bin, spec.args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    return { ran: false, connected: false, reason: error.message };
+  }
+  onLaunch({ mode: "headless", bin: spec.bin });
+
+  let spawnError = null;
+  let exitedAt = 0;
+  let output = "";
+  const absorb = (chunk) => {
+    output = `${output}${chunk}`.slice(-4000);
+  };
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", absorb);
+  child.stderr?.on("data", absorb);
+  child.on("error", (error) => {
+    spawnError = error;
+    exitedAt = exitedAt || Date.now();
+  });
+  child.on("exit", () => {
+    exitedAt = exitedAt || Date.now();
+  });
+
+  // The check-in can land moments after the agent's own process ends, so keep
+  // polling briefly past its exit rather than declaring failure at the edge.
+  const grace = intervalMs * 2;
+  try {
+    const connected = await waitForConnection(args, apiKey, {
+      intervalMs,
+      timeoutMs,
+      expectedAgent: agent.id,
+      pairingId,
+      onPoll,
+      stopWhen: () => Boolean(exitedAt) && Date.now() - exitedAt > grace,
+    });
+    if (spawnError && !connected) {
+      return { ran: false, connected: false, reason: spawnError.message, output };
+    }
+    return { ran: true, connected, command: spec.bin, output };
+  } finally {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+  }
+}
+
+/** The last non-empty line of an agent's output, for a one-line diagnosis. */
+export function lastLine(output, cap = 200) {
+  const lines = String(output || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return lines.length ? lines[lines.length - 1].slice(0, cap) : "";
+}
+
+// ── MCP self-test ───────────────────────────────────────────────────────
+
+/**
+ * How long to give the self-test, and whether to run it at all.
+ *
+ * `PREMAN_SELFTEST_MS=0` turns it off for a whole process, which is what a test
+ * run wants: the launcher is `npm exec premanmcp@latest`, so every case that
+ * reaches this would otherwise go to the registry.
+ */
+export function selfTestBudgetMs() {
+  const raw = process.env.PREMAN_SELFTEST_MS;
+  if (raw === undefined || raw === "") return 60000;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : 60000;
+}
+
+/**
+ * Run the config we just wrote, exactly as the agent will, and call one tool.
+ *
+ * This is both the fastest way to finish the link and the only check that proves
+ * the whole chain — launcher, package, key, backend — rather than proving the
+ * file is on disk. It matters because the failure it catches is invisible
+ * otherwise: a repo-local `preman-mcp.config.json` (or a stale global env) can
+ * redirect the server to a backend the key was never issued for, and every
+ * symptom of that points at the key.
+ *
+ * Speaks the two JSON-RPC calls an MCP client makes on startup. Never throws.
+ */
+export async function mcpSelfTest(
+  serverConfig,
+  { timeoutMs = selfTestBudgetMs(), cwd = process.cwd() } = {}
+) {
+  if (timeoutMs <= 0) return { ok: false, reason: "self-test disabled" };
+  let child;
+  try {
+    child = spawn(serverConfig.command, serverConfig.args, {
+      cwd,
+      env: { ...process.env, ...serverConfig.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  } catch (error) {
+    return { ok: false, reason: error.message };
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let stdinFailureTimer = null;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (stdinFailureTimer) clearTimeout(stdinFailureTimer);
+      if (child.exitCode === null && child.signalCode === null) child.kill();
+      resolve(result);
+    };
+
+    const timer = setTimeout(
+      () => finish({ ok: false, reason: `the MCP server did not answer within ${Math.round(timeoutMs / 1000)}s`, stderr: lastLine(stderr) }),
+      timeoutMs
+    );
+
+    const failStdin = (error) => {
+      if (settled || stdinFailureTimer) return;
+      const reason = error?.message || "the MCP server closed stdin";
+      // A launcher that exits immediately usually closes its pipe before Node
+      // emits the child exit. Give that more useful diagnosis one event-loop
+      // turn to win; a live process with closed stdin still fails promptly.
+      stdinFailureTimer = setTimeout(() => finish({ ok: false, reason }), 25);
+    };
+    // Stream write failures are emitted asynchronously; try/catch around
+    // `write()` cannot prevent an EPIPE from crashing the CLI.
+    child.stdin.on("error", failStdin);
+
+    const send = (message) => {
+      if (settled) return;
+      if (child.stdin.destroyed || child.stdin.writableEnded) {
+        failStdin(new Error("the MCP server closed stdin"));
+        return;
+      }
+      try {
+        child.stdin.write(`${JSON.stringify(message)}\n`, (error) => {
+          if (error) failStdin(error);
+        });
+      } catch (error) {
+        failStdin(error);
+      }
+    };
+
+    child.on("error", (error) => finish({ ok: false, reason: error.message }));
+    child.on("exit", (code) =>
+      finish({
+        ok: false,
+        reason: `the MCP server exited with code ${code}`,
+        stderr: lastLine(stderr),
+      })
+    );
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-4000);
+    });
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      let newline = stdout.indexOf("\n");
+      while (newline !== -1) {
+        const line = stdout.slice(0, newline).trim();
+        stdout = stdout.slice(newline + 1);
+        newline = stdout.indexOf("\n");
+        if (!line.startsWith("{")) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (message.id === 1) {
+          send({ jsonrpc: "2.0", method: "notifications/initialized" });
+          send({
+            jsonrpc: "2.0",
+            id: 2,
+            method: "tools/call",
+            params: { name: "preman_status", arguments: {} },
+          });
+          continue;
+        }
+        if (message.id !== 2) continue;
+        const text = message.result?.content?.[0]?.text;
+        let status = {};
+        try {
+          status = text ? JSON.parse(text) : {};
+        } catch {
+          status = { raw: text };
+        }
+        finish({ ok: !message.error, status, reason: message.error?.message || "" });
+      }
+    });
+
+    send({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "preman-connect-selftest", version: "1" },
+      },
+    });
+  });
+}