premanmcp 0.5.0 → 0.7.0

package/bin/connect.js

@@ -15,12 +15,14 @@ import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "n
 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,
@@ -49,18 +51,24 @@ const AGENTS = [
     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.",
   },
 ];
 
@@ -125,6 +133,22 @@ export function writeCursorConfig({ serverName, serverConfig, projectInstall })
   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
@@ -132,18 +156,7 @@ export function writeCursorConfig({ serverName, serverConfig, projectInstall })
  */
 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,
-    ];
+    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" };
@@ -233,6 +246,104 @@ const WRITERS = {
   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) {
@@ -250,7 +361,14 @@ async function startPairing(args, agent, apiKey) {
   return String(result.pair_code || "");
 }
 
-async function waitForConnection(args, apiKey, { intervalMs = 3000, timeoutMs = 300000 } = {}) {
+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 = () => {
@@ -323,6 +441,135 @@ export function extractRoutineId(value) {
   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 = `
@@ -340,6 +587,7 @@ Connect options:
   --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
 `;
 
@@ -360,15 +608,28 @@ export async function connectCommand(commandArgs) {
 
   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).",
+          "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") {
@@ -407,14 +668,28 @@ export async function connectCommand(commandArgs) {
       `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(
-      `\nRestart ${agent.label}, then ask it: "run preman_status" to finish linking.\n`
-    );
+    process.stdout.write(nextStepsBlock(agent));
     return;
   }
 
@@ -422,11 +697,19 @@ export async function connectCommand(commandArgs) {
     `\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"
-  );
+
+  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);
+  }
 }