premanmcp 0.4.0 → 0.7.0

package/bin/connect.js

@@ -0,0 +1,715 @@
+/**
+ * `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 { callTool as callPremanTool, printTestSummary } from "./api_tools.js";
+import {
+  assertOk,
+  authenticateTerminal,
+  backendUrl,
+  buildServerConfig,
+  callBackendJson,
+  frontendUrl,
+  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 },
+    snippetHint: "merge into ~/.cursor/mcp.json",
+    restartHint: 'Fully quit and reopen Cursor, then Settings → MCP → toggle "preman" off and on.',
+  },
+  {
+    id: "claude_code",
+    label: "Claude Code",
+    aliases: ["claude", "claude-code", "claude_code", "claudecode"],
+    dispatch: { credential: "Claude Code routine token", needsRoutine: true },
+    snippetHint: "run:",
+    restartHint: 'Start a new Claude Code session and run `claude mcp list` — "preman" should be listed.',
+  },
+  {
+    id: "codex",
+    label: "Codex",
+    aliases: ["codex", "openai-codex", "openai_codex"],
+    dispatch: null, // No public fire API; stays on the copy-paste path.
+    snippetHint: "append to ~/.codex/config.toml",
+    restartHint: "Restart Codex so it re-reads its config.toml.",
+  },
+];
+
+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" };
+}
+
+/** The `claude mcp add` invocation, shared by the writer and the printed fallback. */
+export function claudeMcpAddArgs(serverName, serverConfig, projectInstall) {
+  const envArgs = Object.entries(serverConfig.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]);
+  return [
+    "mcp",
+    "add",
+    serverName,
+    "--scope",
+    projectInstall ? "project" : "user",
+    ...envArgs,
+    "--",
+    serverConfig.command,
+    ...serverConfig.args,
+  ];
+}
+
+/**
+ * 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 args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
+    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,
+};
+
+// ── Copy-paste fallbacks ────────────────────────────────────────────────
+
+/** Quote only what a shell would otherwise mangle, so the line stays readable. */
+function shellQuote(value) {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/** What a user would paste by hand to get exactly what the writer would have written. */
+export function renderAgentSnippet(agentId, serverName, serverConfig, { projectInstall = false } = {}) {
+  if (agentId === "codex") return renderCodexToml(serverName, serverConfig);
+  if (agentId === "claude_code") {
+    const args = claudeMcpAddArgs(serverName, serverConfig, projectInstall);
+    return `claude ${args.map(shellQuote).join(" ")}\n`;
+  }
+  return `${JSON.stringify({ mcpServers: { [serverName]: serverConfig } }, null, 2)}\n`;
+}
+
+/** Every agent's snippet, for when we could not pick one for the user. */
+export function renderAllAgentSnippets(args, serverName, { projectInstall = false } = {}) {
+  // Build config WITHOUT resolved API key to avoid leaking secrets in CI logs.
+  // Users must supply --api-key or set PREMAN_API_KEY separately.
+  const env = {
+    PREMAN_BACKEND: backendUrl(args),
+    PREMAN_FRONTEND: frontendUrl(args),
+  };
+  const serverConfig = { command: "npx", args: ["-y", "premanmcp@latest"], env };
+  
+  return AGENTS.map((agent) => {
+    // Adjust hint based on projectInstall, matching verifyWrittenConfig logic
+    let hint = agent.snippetHint;
+    if (agent.id === "cursor" && projectInstall) {
+      hint = "merge into .cursor/mcp.json";
+    } else if (agent.id === "claude_code") {
+      hint = projectInstall ? "run (with --scope project):" : "run:";
+    }
+    return `# ${agent.label} — ${hint}\n` + renderAgentSnippet(agent.id, serverName, serverConfig, { projectInstall });
+  }).join("\n");
+}
+
+// ── Post-write validation ───────────────────────────────────────────────
+
+/** The lines belonging to our `[mcp_servers.<name>]` block, or null if absent. */
+function codexBlockLines(text, serverName) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((line) => line.trim() === `[mcp_servers.${serverName}]`);
+  if (start === -1) return null;
+  const block = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^\[/.test(line) && !line.startsWith(`[mcp_servers.${serverName}.`)) break;
+    block.push(line);
+  }
+  return block;
+}
+
+/**
+ * Read back what we just wrote, so a silently-failed write is not reported as a
+ * success. Proves the entry is on disk (or that Claude Code knows about it) —
+ * whether the agent has actually loaded it is only ever proven by a check-in.
+ *
+ * Never throws: a verification that cannot run must not fail the connect. An
+ * unreadable state reports "unknown" and stays quiet, because a wrong warning
+ * costs more trust than a missing one.
+ */
+export function verifyWrittenConfig(agent, { serverName, written }) {
+  try {
+    if (agent.id === "codex") {
+      const text = written.path && existsSync(written.path) ? readFileSync(written.path, "utf8") : "";
+      const block = codexBlockLines(text, serverName);
+      if (!block) {
+        return { status: "mismatch", detail: `no [mcp_servers.${serverName}] block in ${written.path}` };
+      }
+      if (!block.some((line) => line.trim() === 'command = "npx"')) {
+        return { status: "mismatch", detail: `${written.path} does not launch npx` };
+      }
+      return { status: "verified" };
+    }
+
+    // Claude Code registered the server itself — ask its CLI what it ended up with.
+    if (agent.id === "claude_code" && written.how !== "wrote") {
+      const probe = spawnSync("claude", ["mcp", "get", serverName], { stdio: "ignore" });
+      if (probe.error) return { status: "unknown", detail: "could not run claude" };
+      return probe.status === 0
+        ? { status: "verified" }
+        : { status: "mismatch", detail: `claude mcp get ${serverName} did not find the server` };
+    }
+
+    const entry = readJsonFile(written.path).mcpServers?.[serverName];
+    if (!entry) return { status: "mismatch", detail: `${serverName} is missing from ${written.path}` };
+    if (entry.command !== "npx") {
+      return { status: "mismatch", detail: `${written.path} does not launch npx` };
+    }
+    return { status: "verified" };
+  } catch (error) {
+    return { status: "unknown", detail: error.message };
+  }
+}
+
+// ── 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 || "");
+}
+
+export async function waitForConnection(
+  args,
+  apiKey,
+  {
+    intervalMs = Number(process.env.PREMAN_CONNECT_POLL_MS) || 3000,
+    timeoutMs = Number(process.env.PREMAN_CONNECT_WAIT_MS) || 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;
+}
+
+// ── Guided first run ────────────────────────────────────────────────────
+
+const MANUAL_STEPS =
+  "  preman endpoints discover                       # brief for your agent → endpoints.json\n" +
+  "  preman endpoints setup --file endpoints.json    # register runnable requests\n" +
+  "  preman test <request-id>                        # generate + run your first scenarios\n";
+
+function nextStepsBlock(agent) {
+  return (
+    "\nNext steps:\n" +
+    `  1. Restart ${agent.label}, then ask it: "run preman_status" to finish linking.\n` +
+    "  2. preman endpoints discover                     # brief for your agent → endpoints.json\n" +
+    "  3. preman endpoints setup --file endpoints.json  # register runnable requests\n" +
+    "  4. preman test <request-id>                      # generate + run your first scenarios\n"
+  );
+}
+
+async function confirm(question) {
+  const answer = (await promptText(`${question} [Y/n]: `)).toLowerCase();
+  return answer === "" || answer.startsWith("y");
+}
+
+/**
+ * Carry a freshly linked agent to its first passing test.
+ *
+ * Discovery itself belongs to the coding agent — the backend hands back a brief
+ * for it to execute — so this either runs a test against what the account
+ * already has, or prints that brief and the two commands that follow it.
+ *
+ * Never throws: onboarding help must not turn a successful connect into a failure.
+ */
+async function guidedFirstRun(args, agent) {
+  try {
+    const inventory = await callPremanTool(args, "get_endpoints", {
+      include_workbench: true,
+      limit: 50,
+    });
+    const runnable = (inventory.workbench_requests || [])[0];
+    const registered = (inventory.endpoints || []).length;
+
+    if (runnable) {
+      const label = `${runnable.method || "GET"} ${runnable.url || ""}`.trim();
+      if (!(await confirm(`\nRun a first test against ${label}?`))) {
+        process.stdout.write(`Whenever you are ready: preman test ${runnable.id}\n`);
+        return;
+      }
+      process.stdout.write("Generating scenarios…\n");
+      const result = await callPremanTool(args, "generate_endpoint_tests", {
+        target: runnable.id,
+        run: true,
+        allow_writes: false,
+        max_cases: 10,
+      });
+      printTestSummary(result);
+      process.stdout.write(`\nAdd your own: preman test ${runnable.id} --scenario "..."\n`);
+      return;
+    }
+
+    if (registered) {
+      process.stdout.write(
+        `\nYou have ${registered} registered endpoint(s), but none are runnable yet:\n` +
+          "  preman endpoints setup --ids <id1,id2>    # make them runnable\n" +
+          "  preman test <request-id>                  # generate + run your first scenarios\n"
+      );
+      return;
+    }
+
+    if (!(await confirm("\nNo endpoints in PreMan yet. Print the discovery brief for your agent?"))) {
+      process.stdout.write(`\nWhen you are ready:\n${MANUAL_STEPS}`);
+      return;
+    }
+
+    const brief = await callPremanTool(args, "discover_endpoints_from_codebase", { base_path: "." });
+    for (const line of brief.instructions || []) process.stdout.write(`${line}\n`);
+    process.stdout.write(
+      `\nHand this brief to ${agent.label}, then run:\n` +
+        "  preman endpoints setup --file endpoints.json\n" +
+        "  preman test <request-id>\n"
+    );
+  } catch (error) {
+    process.stdout.write(
+      `Note: ${error.message}. Run \`preman endpoints list\` when you are ready.\n`
+    );
+  }
+}
+
+// ── Preflight ───────────────────────────────────────────────────────────
+
+const MIN_NODE_MAJOR = 18;
+
+/**
+ * Verify the machine can actually run the config we are about to write.
+ * Hard-fails only on a Node that cannot run the server; everything else is a
+ * warning — connect must keep working offline and behind odd shells.
+ */
+export async function preflight(args) {
+  const problems = [];
+  const notes = [];
+
+  const major = Number(process.versions.node.split(".")[0]);
+  if (Number.isFinite(major) && major < MIN_NODE_MAJOR) {
+    problems.push(
+      `Node ${process.versions.node} is too old — the PreMan MCP server needs Node ${MIN_NODE_MAJOR}+.`
+    );
+  }
+
+  if (!onPath("npx")) {
+    notes.push(
+      "npx was not found on PATH; the written config launches PreMan via npx, so make sure your agent's environment has it."
+    );
+  }
+
+  try {
+    const resp = await fetch(new URL("health", `${backendUrl(args)}/`), {
+      signal: AbortSignal.timeout(4000),
+    });
+    if (!resp.ok) {
+      notes.push(`PreMan backend ${backendUrl(args)} answered ${resp.status}; connect will continue but calls may fail.`);
+    }
+  } catch {
+    notes.push(`Could not reach ${backendUrl(args)}; connect will continue but pairing and logins need it.`);
+  }
+
+  for (const note of notes) process.stdout.write(`Note: ${note}\n`);
+  if (problems.length) {
+    throw new ConnectError(problems.join("\n"), EXIT_USAGE);
+  }
+}
+
+// ── 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
+  --no-guide                  Skip the guided first run after connecting
+  --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) {
+      // Nothing to prompt on, so leave behind everything a CI log needs to
+      // finish the setup by hand rather than just the reason it stopped.
+      process.stdout.write(
+        `preman connect needs a terminal to pick an agent. Copy-paste setup instead:\n\n${renderAllAgentSnippets(args, serverName, { projectInstall })}\n` +
+          'Then restart your agent and ask it: "run preman_status".\n' +
+          "Or rerun: preman connect --agent <cursor|claude-code|codex> --api-key pm_live_…\n"
+      );
+      throw new ConnectError(
+        "preman connect needs a terminal. In CI pass --agent <cursor|claude-code|codex> " +
+          "and --api-key pm_live_… (or --print), or use one of the snippets above.",
+        EXIT_USAGE
+      );
+    }
+    agent = await promptAgentChoice(detectAgents());
+  }
+
+  if (!printOnly) {
+    // Verify the machine can run what we are about to write — before any
+    // config edits or logins, so failures leave nothing half-done.
+    await preflight(args);
+  }
+
+  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`
+  );
+
+  const verification = verifyWrittenConfig(agent, { serverName, written });
+  if (verification.status === "mismatch") {
+    // Generate hint that matches the actual install location
+    let hint = agent.snippetHint;
+    if (agent.id === "cursor" && projectInstall) {
+      hint = "merge into .cursor/mcp.json";
+    } else if (agent.id === "claude_code") {
+      hint = projectInstall ? "run (with --scope project):" : "run:";
+    }
+    process.stdout.write(
+      `\nWarning: could not confirm the ${agent.label} config (${verification.detail}).\n` +
+        `Apply it by hand — ${hint}\n\n` +
+        renderAgentSnippet(agent.id, serverName, serverConfig, { projectInstall })
+    );
+  }
+
+  // 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(nextStepsBlock(agent));
+    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"
+  );
+
+  if (!(await waitForConnection(args, apiKey))) {
+    process.stdout.write(
+      "No check-in yet. Troubleshooting:\n" +
+        `  - ${agent.restartHint}\n` +
+        `  - Config written to: ${written.path}\n` +
+        `  - Then ask ${agent.label} to "run preman_status" — it links on its first PreMan call.\n`
+    );
+    return;
+  }
+
+  process.stdout.write(`Connected as ${agent.label}.\n`);
+  if (!args.has("--no-guide")) {
+    await guidedFirstRun(args, agent);
+  }
+}