premanmcp 0.3.5 → 0.5.0

package/bin/connect.js

@@ -0,0 +1,432 @@
+/**
+ * `preman connect` — pick a coding agent and get connected, in one command.
+ *
+ * Replaces the hand-edited MCP config: the user picks Cursor / Claude Code /
+ * Codex from a list, PreMan logs them in if needed, writes that agent's config
+ * itself, and binds the connection to their account with a pair code.
+ *
+ * Optionally captures a cloud-dispatch credential in the same pass so PreMan can
+ * start agent runs for them later (SCRUM-124). That step is always skippable and
+ * never fails the connect.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  assertOk,
+  authenticateTerminal,
+  backendUrl,
+  buildServerConfig,
+  callBackendJson,
+  hasKeyAvailable,
+  makeArgs,
+  promptSecret,
+  promptText,
+  readJsonFile,
+  resolveApiKey,
+  writeJsonFile,
+} from "./shared.js";
+
+const EXIT_USAGE = 2;
+
+class ConnectError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Supported agents. `id` matches the backend's normalize_agent() vocabulary so
+ * the link record and this CLI cannot disagree about who is connected.
+ */
+const AGENTS = [
+  {
+    id: "cursor",
+    label: "Cursor",
+    aliases: ["cursor"],
+    dispatch: { credential: "Cursor API key", needsRoutine: false },
+  },
+  {
+    id: "claude_code",
+    label: "Claude Code",
+    aliases: ["claude", "claude-code", "claude_code", "claudecode"],
+    dispatch: { credential: "Claude Code routine token", needsRoutine: true },
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    aliases: ["codex", "openai-codex", "openai_codex"],
+    dispatch: null, // No public fire API; stays on the copy-paste path.
+  },
+];
+
+function findAgent(value) {
+  const raw = String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
+  return AGENTS.find((a) => a.id === raw || a.aliases.includes(raw)) || null;
+}
+
+function onPath(binary) {
+  const probe = spawnSync(process.platform === "win32" ? "where" : "which", [binary], {
+    stdio: "ignore",
+  });
+  return probe.status === 0;
+}
+
+/** Best guess at which agent this machine actually uses, for the default pick. */
+function detectAgents() {
+  const home = os.homedir();
+  return {
+    cursor: existsSync(path.join(home, ".cursor")) || Boolean(process.env.CURSOR_TRACE_ID),
+    claude_code: onPath("claude") || existsSync(path.join(home, ".claude.json")),
+    codex: onPath("codex") || existsSync(process.env.CODEX_HOME || path.join(home, ".codex")),
+  };
+}
+
+async function promptAgentChoice(detected) {
+  process.stdout.write("Which coding agent?\n");
+  AGENTS.forEach((agent, index) => {
+    const mark = detected[agent.id] ? "  (detected)" : "";
+    process.stdout.write(`  ${index + 1}. ${agent.label}${mark}\n`);
+  });
+
+  const defaultIndex = Math.max(
+    0,
+    AGENTS.findIndex((a) => detected[a.id])
+  );
+  const answer = await promptText(`Pick [${defaultIndex + 1}]: `);
+  if (!answer) return AGENTS[defaultIndex];
+
+  const byNumber = Number.parseInt(answer, 10);
+  if (Number.isInteger(byNumber) && byNumber >= 1 && byNumber <= AGENTS.length) {
+    return AGENTS[byNumber - 1];
+  }
+  const byName = findAgent(answer);
+  if (byName) return byName;
+  throw new ConnectError(`Not a valid choice: ${answer}`, EXIT_USAGE);
+}
+
+// ── Config writers ──────────────────────────────────────────────────────
+
+function cursorConfigPath(projectInstall) {
+  return projectInstall
+    ? path.join(process.cwd(), ".cursor", "mcp.json")
+    : path.join(os.homedir(), ".cursor", "mcp.json");
+}
+
+export function writeCursorConfig({ serverName, serverConfig, projectInstall }) {
+  const configPath = cursorConfigPath(projectInstall);
+  const config = { ...readJsonFile(configPath) };
+  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+  writeJsonFile(configPath, config);
+  return { path: configPath, how: "wrote" };
+}
+
+/**
+ * Claude Code owns ~/.claude.json, so prefer its own CLI. Fall back to writing
+ * the config directly when `claude` is not installed — a user can connect before
+ * installing the agent.
+ */
+export function writeClaudeConfig({ serverName, serverConfig, projectInstall }) {
+  if (onPath("claude")) {
+    const envArgs = Object.entries(serverConfig.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+    const args = [
+      "mcp",
+      "add",
+      serverName,
+      "--scope",
+      projectInstall ? "project" : "user",
+      ...envArgs,
+      "--",
+      serverConfig.command,
+      ...serverConfig.args,
+    ];
+    try {
+      execFileSync("claude", args, { stdio: "pipe" });
+      return { path: projectInstall ? ".mcp.json" : "Claude Code user config", how: "registered via claude mcp add" };
+    } catch (error) {
+      const detail = error?.stderr?.toString().trim() || error.message;
+      process.stdout.write(`Note: claude mcp add failed (${detail}); writing the config directly.\n`);
+    }
+  }
+
+  if (projectInstall) {
+    const configPath = path.join(process.cwd(), ".mcp.json");
+    const config = { ...readJsonFile(configPath) };
+    config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+    writeJsonFile(configPath, config);
+    return { path: configPath, how: "wrote" };
+  }
+
+  // Merge only mcpServers: the user config holds a lot of unrelated state.
+  // CLAUDE_CONFIG_DIR relocates that file, and writing to ~ when it is set
+  // produces a config Claude Code never reads.
+  const configPath = path.join(process.env.CLAUDE_CONFIG_DIR || os.homedir(), ".claude.json");
+  const config = { ...readJsonFile(configPath) };
+  config.mcpServers = { ...(config.mcpServers || {}), [serverName]: serverConfig };
+  writeJsonFile(configPath, config);
+  return { path: configPath, how: "wrote" };
+}
+
+/**
+ * Render the `[mcp_servers.<name>]` block for Codex's TOML config. Only strings
+ * and string arrays appear here, so a hand-rolled writer is enough — no TOML
+ * dependency for one fixed shape.
+ */
+export function renderCodexToml(serverName, serverConfig) {
+  const str = (value) => JSON.stringify(String(value));
+  const lines = [
+    `[mcp_servers.${serverName}]`,
+    `command = ${str(serverConfig.command)}`,
+    `args = [${serverConfig.args.map(str).join(", ")}]`,
+  ];
+  const env = Object.entries(serverConfig.env);
+  if (env.length) {
+    lines.push("", `[mcp_servers.${serverName}.env]`);
+    for (const [key, value] of env) lines.push(`${key} = ${str(value)}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Replace an existing preman block, or append a new one, leaving the rest alone. */
+export function upsertCodexToml(existing, serverName, block) {
+  const header = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`, "m");
+  if (!header.test(existing)) {
+    const separator = existing.trim() ? "\n" : "";
+    return `${existing.trimEnd()}${separator}\n${block}`;
+  }
+
+  const lines = existing.split("\n");
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    const isOurHeader = new RegExp(`^\\[mcp_servers\\.${serverName}(\\.|\\])`).test(line);
+    if (isOurHeader) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^\[/.test(line) && !isOurHeader) skipping = false;
+    if (!skipping) out.push(line);
+  }
+  return `${out.join("\n").trimEnd()}\n\n${block}`;
+}
+
+export function writeCodexConfig({ serverName, serverConfig }) {
+  const configPath = path.join(
+    process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+    "config.toml"
+  );
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const next = upsertCodexToml(existing, serverName, renderCodexToml(serverName, serverConfig));
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, next, { mode: 0o600 });
+  chmodSync(configPath, 0o600); // mode above is ignored for an existing file
+  return { path: configPath, how: "wrote" };
+}
+
+const WRITERS = {
+  cursor: writeCursorConfig,
+  claude_code: writeClaudeConfig,
+  codex: writeCodexConfig,
+};
+
+// ── Pairing ─────────────────────────────────────────────────────────────
+
+async function startPairing(args, agent, apiKey) {
+  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent", {
+    token: apiKey,
+    json: { agent: agent.id, project_path: process.cwd(), start_pairing: true },
+  });
+  if (!result.ok) {
+    process.stdout.write(
+      `Note: could not start pairing (${result.status_code}); the config still works, ` +
+        "your agent will link on its first PreMan call.\n"
+    );
+    return "";
+  }
+  return String(result.pair_code || "");
+}
+
+async function waitForConnection(args, apiKey, { intervalMs = 3000, timeoutMs = 300000 } = {}) {
+  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", "/workbench/coding-agent", {
+        token: apiKey,
+      });
+      if (status.ok && status.connected) return true;
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  } finally {
+    process.off("SIGINT", onInterrupt);
+  }
+  return false;
+}
+
+// ── Dispatch credential (SCRUM-124) ─────────────────────────────────────
+
+async function captureDispatchCredential(args, agent, apiKey) {
+  if (!agent.dispatch) return;
+  if (args.has("--skip-dispatch-credential")) return;
+
+  let secret = args.value("--dispatch-credential", "");
+  let routineId = args.value("--routine-id", "");
+
+  if (!secret) {
+    if (!process.stdin.isTTY) return;
+    process.stdout.write(
+      `\nOptional: paste a ${agent.dispatch.credential} so PreMan can start ${agent.label} runs for you.\n`
+    );
+    secret = await promptSecret("(Enter to skip): ");
+    if (!secret) return;
+    if (agent.dispatch.needsRoutine && !routineId) {
+      routineId = await promptText("Routine id or URL: ");
+    }
+  }
+
+  if (agent.dispatch.needsRoutine && !routineId) {
+    process.stdout.write("Skipped: a routine id is required alongside the token.\n");
+    return;
+  }
+
+  const body = agent.dispatch.needsRoutine
+    ? { provider: agent.id, secret, routine_id: extractRoutineId(routineId) }
+    : { provider: agent.id, secret };
+
+  const result = await callBackendJson(args, "PUT", "/workbench/coding-agent/dispatch", {
+    token: apiKey,
+    json: body,
+  });
+
+  if (result.ok) {
+    process.stdout.write("Cloud dispatch enabled — PreMan can now start runs for you.\n");
+  } else if (result.status_code === 404 || result.status_code === 405) {
+    process.stdout.write("Note: this PreMan backend does not support cloud dispatch yet; skipped.\n");
+  } else {
+    process.stdout.write(`Note: could not save the credential (${result.status_code}); skipped.\n`);
+  }
+}
+
+/** Accept either a bare trig_… id or the routine URL it appears in. */
+export function extractRoutineId(value) {
+  const raw = String(value || "").trim();
+  const match = raw.match(/trig_[A-Za-z0-9]+/);
+  return match ? match[0] : raw;
+}
+
+// ── Command ─────────────────────────────────────────────────────────────
+
+export const CONNECT_HELP = `
+Connect options:
+  --agent <name>              cursor | claude-code | codex (skips the picker)
+  --project                   Write project-local config instead of the user config
+  --api-key <key>             PreMan API key. If omitted, stored credentials are used
+  --email <email>             Pre-fill the email prompt when logging in
+  --backend <url>             PreMan backend URL
+  --frontend <url>            PreMan frontend URL
+  --name <name>               MCP server name. Defaults to preman
+  --dispatch-credential <t>   Cloud-dispatch token (non-interactive)
+  --routine-id <id>           Claude Code routine id, with --dispatch-credential
+  --skip-dispatch-credential  Do not ask for a cloud-dispatch credential
+  --skip-login                Write config without interactive terminal auth
+  --no-pair                   Do not mint a pair code
+  --no-wait                   Do not wait for the agent to check in
+  --print                     Print the config instead of writing it
+`;
+
+export async function connectCommand(commandArgs) {
+  const args = makeArgs(commandArgs);
+  const serverName = args.value("--name", "preman");
+  const projectInstall = args.has("--project");
+  const printOnly = args.has("--print");
+  const interactive = Boolean(process.stdin.isTTY);
+
+  let agent = findAgent(args.value("--agent", ""));
+  if (!agent && args.value("--agent", "")) {
+    throw new ConnectError(
+      `Unknown agent: ${args.value("--agent", "")}. Use cursor, claude-code, or codex.`,
+      EXIT_USAGE
+    );
+  }
+
+  if (!agent) {
+    if (!interactive) {
+      throw new ConnectError(
+        "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
+          "and --api-key pm_live_… (or --print).",
+        EXIT_USAGE
+      );
+    }
+    agent = await promptAgentChoice(detectAgents());
+  }
+
+  if (printOnly) {
+    const serverConfig = buildServerConfig(args);
+    if (agent.id === "codex") {
+      process.stdout.write(renderCodexToml(serverName, serverConfig));
+    } else {
+      process.stdout.write(`${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`);
+    }
+    return;
+  }
+
+  if (!args.has("--skip-login") && !hasKeyAvailable(args)) {
+    if (!interactive) {
+      throw new ConnectError(
+        "No PreMan credentials. Pass --api-key pm_live_… or set PREMAN_API_KEY.",
+        EXIT_USAGE
+      );
+    }
+    process.stdout.write("First, let's connect your PreMan account.\n");
+    await authenticateTerminal(args);
+    process.stdout.write("\n");
+  }
+
+  const apiKey = resolveApiKey(args);
+
+  let pairCode = "";
+  if (apiKey && !args.has("--no-pair")) {
+    pairCode = await startPairing(args, agent, apiKey);
+  }
+
+  const serverConfig = buildServerConfig(args, { pairCode });
+  const written = WRITERS[agent.id]({ serverName, serverConfig, projectInstall });
+
+  process.stdout.write(
+    `\n${agent.label} connected: ${written.how} ${written.path}\n` +
+      `Server name: ${serverName}\n` +
+      `Backend: ${serverConfig.env.PREMAN_BACKEND}\n`
+  );
+
+  // Not gated on TTY: --dispatch-credential is the non-interactive path, and the
+  // prompt inside only runs when there is a terminal to prompt on.
+  await captureDispatchCredential(args, agent, apiKey);
+
+  if (!pairCode || args.has("--no-wait") || !interactive) {
+    process.stdout.write(
+      `\nRestart ${agent.label}, then ask it: "run preman_status" to finish linking.\n`
+    );
+    return;
+  }
+
+  process.stdout.write(
+    `\nRestart ${agent.label} and ask it: "run preman_status"\n` +
+      "Waiting for your agent to check in… (Ctrl+C to stop waiting)\n"
+  );
+  const connected = await waitForConnection(args, apiKey);
+  process.stdout.write(
+    connected
+      ? `Connected as ${agent.label}.\n`
+      : `No check-in yet. Open ${agent.label} and ask it to "run preman_status" — ` +
+        "it will link on its first PreMan call.\n"
+  );
+}