premanmcp 0.10.5 → 0.10.7

package/README.md

@@ -48,11 +48,13 @@ to go restart anything, in cheapest-first order:
 1. **Self-test.** It starts the MCP server exactly as your agent will and calls
    `preman_status` over stdio. That both completes the link and proves the whole chain —
    launcher, package, key, backend. `--no-self-test` turns it off.
-2. **Agent run**, which also proves your agent can load what was written. It opens your
-   agent interactively in a new terminal window — the session you go on to use — and falls
-   back to a headless run (`claude -p`, `cursor-agent -p`, `codex exec`) where no window can
-   be opened, such as CI or SSH. `--no-auto-checkin` turns it off, `PREMAN_NO_TERMINAL=1`
-   keeps it headless.
+2. **Agent run**, which also proves your agent can load what was written. For Cursor it
+   runs `cursor-agent mcp enable` after writing `mcp.json` (new servers stay off the CLI
+   approved list otherwise) and launches the agent with `--approve-mcps` so the check-in
+   can actually call `preman_status`. It opens your agent interactively in a new terminal
+   window — the session you go on to use — and falls back to a headless run (`claude -p`,
+   `cursor-agent --approve-mcps -p`, `codex exec`) where no window can be opened, such as
+   CI or SSH. `--no-auto-checkin` turns it off, `PREMAN_NO_TERMINAL=1` keeps it headless.
 3. **Wait**, if neither is possible: restart your agent and it links on its first call.
 
 A self-test that answers from an unexpected backend is reported with the file that
@@ -71,6 +73,10 @@ up a link that already worked:
 
 ```bash
 preman endpoints discover          # map this repo's endpoints
+preman tests generate              # heuristic suites on saved Collections requests
+preman tests review                # list flagged suites; --approve <id> enables schedule
+preman tests setup                 # harvest path-param fixture IDs into a .env snippet
+preman tests enrich                # optional LLM cases on remaining heuristic suites
 preman runner start --background   # let PreMan apply fixes on this machine
 preman github                      # or connect it in the dashboard
 preman status                      # which of those are done
@@ -133,6 +139,7 @@ npm exec -y premanmcp@latest -- connect --project
 ## What It Does
 
 - Converts API endpoints into agent-callable MCP tools.
+- Migrates a Postman collection in one call (`migrate_from_postman`): keeps the assertions your `pm.test` blocks declared, splits the environment into shared variables and encrypted secrets, and schedules a monitored test suite per request.
 - Creates/connects a PreMan account from the terminal or IDE agent.
 - Lets agents test real backend endpoints from the IDE.
 - Syncs endpoint inventory across backend and frontend workflows.
@@ -166,6 +173,10 @@ Convert these endpoints into an MCP.
 Show me the audit log for this hosted MCP.
 ```
 
+```text
+Move my Postman collection over to PreMan.
+```
+
 ```text
 Pull my pending PreMan fix tasks and fix the failing endpoint.
 ```
@@ -230,6 +241,7 @@ npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ```bash
 preman hook install         # Write the pre-push hook (connect does this too)
 preman hook status          # Installed? And does the command in it still answer?
+preman hook repair          # Rewrite it if it stopped working (usually automatic)
 preman hook uninstall       # Remove it, restoring any hook it replaced
 ```
 
@@ -242,17 +254,33 @@ than `@latest`, so upgrading us never changes what your pushes run; re-run `hook
 to move it. Set `PREMAN_HOOK_INVOCATION` to write a command of your own instead, and
 `PREMAN_SKIP_HOOK=1` to silence the hook for a push.
 
+You should not have to run `repair`. A hook of ours that stops answering is rewritten in the
+background by anything that proves PreMan runs here — any command, or your agent starting the
+MCP server — because nothing re-runs `connect` after an upgrade to notice, and the broken
+state is silent. It is narrow on purpose: a hook that still works keeps the version it pins, a
+hook we did not write is never touched, and no hook is installed where you never asked for
+one. The answer is remembered for an hour per directory, and `PREMAN_NO_HOOK_REPAIR=1` turns
+it off.
+
 ### Runner
 
-`connect --guide` sets this up for you; these are for managing it afterwards.
+`preman onboard` and `connect --guide` set this up for you; these are for managing it
+afterwards.
 
 ```bash
 preman runner status              # Paired? Running?
 preman runner start --background  # Hold the job stream, log to ~/.preman/runner.log
 preman runner stop                # Stop it and report offline
-preman runner register --agent claude-code   # Re-pair (e.g. a different project)
+preman runner register --agent claude-code   # Pair without starting
 ```
 
+`start` pairs this machine itself when it is not paired yet, and re-pairs it when the
+backend has revoked the token it held, so neither is a command you have to be told to run.
+It works out which agent to pair as from the session it is running in, then from the agent
+PreMan is already configured in, then from the only one installed — and asks only when
+those disagree. Pass `--agent cursor|claude-code|codex` to settle it yourself, which is
+also what a machine with no terminal to ask in needs.
+
 The runner holds one outbound connection to PreMan and runs the work PreMan queues for
 this machine — a failing endpoint becomes an agent run in your own repo instead of a
 prompt you have to paste. It is bound to the agent and directory it was registered with

package/bin/account.js

@@ -29,7 +29,7 @@ export const ACCOUNT_HELP = `
 Account options:
   login --browser       Approve sign-in in the browser instead of typing a password
   logout                Delete stored CLI credentials
-  doctor                Check backend, credentials, target, and integrations
+  doctor [--port n]     Check backend, credentials, target, and integrations
   watch <run-id>        Follow a push simulation as it runs
 `;
 
@@ -140,7 +140,10 @@ export async function doctorCommand(commandArgs = []) {
     if (!status.ok) failures += 1;
   }
 
-  const candidates = detectCandidates(process.cwd());
+  const explicitPort = args.value("--port", "");
+  const candidates = detectCandidates(process.cwd(), {
+    extraPorts: explicitPort ? [explicitPort] : [],
+  });
   results.push(
     line(
       "local target",
@@ -150,6 +153,7 @@ export async function doctorCommand(commandArgs = []) {
         : "no signals in this directory"
     )
   );
+  if (!candidates.length) failures += 1;
 
   // An installed hook whose command no longer answers is the one failure here
   // that reports itself as success everywhere else: `git push` prints a single
@@ -200,7 +204,18 @@ export async function doctorCommand(commandArgs = []) {
   return { failures };
 }
 
-const TERMINAL_STATUSES = new Set(["complete", "completed", "failed", "error", "cancelled"]);
+const TERMINAL_STATUSES = new Set([
+  "complete",
+  "completed",
+  "succeeded",
+  "failed",
+  "error",
+  "cancelled",
+]);
+
+export function isTerminalSimulationStatus(value) {
+  return TERMINAL_STATUSES.has(String(value || "").toLowerCase());
+}
 
 export async function watchCommand(commandArgs = []) {
   const args = makeArgs(commandArgs);
@@ -235,7 +250,7 @@ export async function watchCommand(commandArgs = []) {
       process.stdout.write(`  ${mark} ${String(step.key || "").padEnd(14)} ${step.message || ""}\n`);
     }
 
-    if (TERMINAL_STATUSES.has(String(result.status || "").toLowerCase())) {
+    if (isTerminalSimulationStatus(result.status)) {
       const verdict = result.summary?.verdict || result.status;
       process.stdout.write(`\nRun ${result.status}: ${verdict}\n`);
       return result;

package/bin/api_tools.js

@@ -8,7 +8,7 @@
 
 import { readFileSync } from "node:fs";
 
-import { callBackendJson, makeArgs, resolveApiKey } from "./shared.js";
+import { callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
 
 export const ENDPOINTS_HELP = `
 Endpoints:

package/bin/cli.js

@@ -17,12 +17,14 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ENDPOINTS_HELP, TEST_HELP, endpointsCommand, testCommand } from "./api_tools.js";
+import { TESTS_HELP, testsCommand } from "./tests.js";
 import {
   CONNECT_HELP,
   DISPATCH_HELP,
   connectCommand,
   discoverEndpoints,
   dispatchCommand,
+  resolveAgentForPairing,
   writeCursorConfig,
 } from "./connect.js";
 import {
@@ -34,7 +36,7 @@ import {
 } from "./integrations.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import { STATUS_HELP, statusCommand } from "./status.js";
-import { HOOK_HELP, hookCommand } from "./hook.js";
+import { HOOK_HELP, hookCommand, scheduleHookRepair } from "./hook.js";
 import { RUNNER_HELP, runnerCommand } from "./runner.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
 import { DESKTOP_HELP, installDesktopCommand } from "./desktop.js";
@@ -55,7 +57,9 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 
 const args = process.argv.slice(2);
-const command = args[0] === "--help" || args[0] === "-h"
+const command = args.length === 0 && process.stdin.isTTY
+  ? "connect"
+  : args[0] === "--help" || args[0] === "-h"
   ? "help"
   : args[0] && !args[0].startsWith("-")
     ? args[0]
@@ -97,6 +101,7 @@ function printHelp() {
     ["link|tools|run ...", "Drive a published hosted MCP"],
     ["endpoints list|discover|setup ...", "Discover, list, and set up API endpoints"],
     ["test <id> [--scenario ...] [--stress]", "Generate + run tests for an endpoint"],
+    ["tests generate|review|setup|enrich", "Collections: generate, review, fixtures, enrich"],
   ];
   const width = Math.max(...usage.map(([command]) => `${cli} ${command}`.trimEnd().length));
   const usageLines = usage
@@ -107,7 +112,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${RUNNER_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}
+${INTEGRATIONS_HELP}${CONNECT_HELP}${DISPATCH_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_HELP}${RUNNER_HELP}${ACCOUNT_HELP}${DESKTOP_HELP}${ENDPOINTS_HELP}${TEST_HELP}${TESTS_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -135,6 +140,7 @@ async function loginCommand() {
     await loginBrowser(cliArgs);
     return;
   }
+  const cli = cliInvocation();
   const creds = await authenticateTerminal(cliArgs);
   process.stdout.write(`PreMan account ready.
 
@@ -153,6 +159,7 @@ You can now run:
  * the same write plus agent choice, pairing, and dispatch setup.
  */
 async function installCursorMcp() {
+  const cli = cliInvocation();
   const serverName = argValue("--name", "preman");
   const projectInstall = hasFlag("--project");
 
@@ -179,7 +186,7 @@ Server name: ${serverName}
 Backend: ${serverConfig.env.PREMAN_BACKEND}
 
 Next steps:
-1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : "Run ${cli} login to create/connect your account and generate an API key."}
+1. ${hasInlineKey ? "Your PreMan API key was written to the MCP config." : hasStoredKey ? `Your PreMan API key is saved in ${CREDENTIALS_FILE}; the MCP server will load it automatically.` : `Run ${cli} login to create/connect your account and generate an API key.`}
 2. Restart Cursor or toggle the PreMan MCP server off/on.
 3. In your API repo, ask your coding agent:
    "Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet."
@@ -216,6 +223,11 @@ function startServer() {
 }
 
 async function main() {
+  // Running at all is the signal. `hook` and `verify` own the hook themselves,
+  // and connect reinstalls it in the foreground, so a background rewrite there
+  // would only race with the one the user is watching.
+  if (!["hook", "verify", "connect"].includes(command)) scheduleHookRepair();
+
   if (command === "login") {
     await loginCommand();
   } else if (command === "status") {
@@ -225,7 +237,10 @@ async function main() {
   } else if (command === "hook") {
     await hookCommand(commandArgs);
   } else if (command === "runner") {
-    await runnerCommand(commandArgs);
+    // Injected rather than imported inside runner.js, which connect.js already
+    // depends on: the agent picker lives there, and importing it back would
+    // close the cycle.
+    await runnerCommand(commandArgs, { resolveAgent: resolveAgentForPairing });
   } else if (command === "logout") {
     await logoutCommand();
   } else if (command === "doctor") {
@@ -266,6 +281,8 @@ async function main() {
     await endpointsCommand(commandArgs);
   } else if (command === "test") {
     await testCommand(commandArgs);
+  } else if (command === "tests") {
+    await testsCommand(commandArgs);
   } else if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
   } else if (command === "start") {

package/bin/connect/agents.js

@@ -0,0 +1,198 @@
+/**
+ * Which coding agent this machine should use, and how it is asked.
+ *
+ * The registry is the shared vocabulary: `id` matches the backend's
+ * normalize_agent(), so a link record and this CLI cannot disagree about who is
+ * connected. Resolution is ordered by how much each signal actually knows --
+ * the session we are inside, the agent PreMan is already written into, the only
+ * one installed -- because asking is the step people resent most.
+ */
+
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { onPath, promptText, readJsonFile } from "../shared.js";
+import { ConnectError, EXIT_USAGE } from "./errors.js";
+
+/**
+ * Supported agents. `id` matches the backend's normalize_agent() vocabulary so
+ * the link record and this CLI cannot disagree about who is connected.
+ */
+export const AGENTS = [
+  {
+    id: "cursor",
+    label: "Cursor",
+    aliases: ["cursor"],
+    dispatch: {
+      credential: "Cursor API key",
+      needsRoutine: false,
+      source: "cursor.com/dashboard → Integrations → API Keys",
+    },
+    snippetHint: "merge into ~/.cursor/mcp.json, then run: cursor-agent mcp enable preman",
+    restartHint:
+      'Fully quit and reopen Cursor, then Settings → MCP → toggle "preman" off and on. For the CLI, run `cursor-agent mcp enable preman`.',
+  },
+  {
+    id: "claude_code",
+    label: "Claude Code",
+    aliases: ["claude", "claude-code", "claude_code", "claudecode"],
+    dispatch: {
+      credential: "Claude Code routine token",
+      needsRoutine: true,
+      // Named explicitly because "Claude Code routine token" reads like an
+      // Anthropic API key, which is a different credential from a different page.
+      source: "claude.ai/code/routines → your routine → Add API trigger",
+    },
+    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.",
+  },
+];
+
+export function findAgent(value) {
+  const raw = String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
+  return AGENTS.find((a) => a.id === raw || a.aliases.includes(raw)) || null;
+}
+
+
+/**
+ * Why this agent's CLI cannot run unattended right now, or "".
+ *
+ * Installed is not the same as usable. `cursor-agent` sits on PATH and exits 1
+ * on every `-p` run until someone signs in, which surfaced as "Cursor did not
+ * register any endpoints" and sent people looking at PreMan for an hour. Only
+ * Cursor is probed because only its CLI has a cheap non-interactive status
+ * subcommand; the others are diagnosed from their own output when they fail.
+ */
+export function agentBlocker(agentId) {
+  if (agentId !== "cursor") return "";
+  const probe = spawnSync("cursor-agent", ["status"], {
+    encoding: "utf8",
+    timeout: 15000,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const text = `${probe.stdout || ""}${probe.stderr || ""}`;
+  if (/not logged in|not authenticated|no active session/i.test(text)) {
+    return "cursor-agent is installed but not signed in — run `cursor-agent login`";
+  }
+  return "";
+}
+
+/** Best guess at which agent this machine actually uses, for the default pick. */
+export 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")),
+  };
+}
+
+/**
+ * The agent whose session this command is running inside, if any.
+ *
+ * A better default than "first one installed": someone who types this into an
+ * agent's terminal almost always means that agent, and on a machine with all
+ * three installed the detected-order default is usually wrong.
+ */
+export function runningInside(env = process.env) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE) return "claude_code";
+  if (env.CURSOR_TRACE_ID) return "cursor";
+  return "";
+}
+
+/** Is PreMan's MCP server already written into this agent's config? */
+function agentIsLinked(agentId, serverName = "preman") {
+  try {
+    const home = os.homedir();
+    if (agentId === "cursor") {
+      return Boolean(readJsonFile(path.join(home, ".cursor", "mcp.json")).mcpServers?.[serverName]);
+    }
+    if (agentId === "claude_code") {
+      return Boolean(readJsonFile(path.join(home, ".claude.json")).mcpServers?.[serverName]);
+    }
+    if (agentId === "codex") {
+      const file = path.join(process.env.CODEX_HOME || path.join(home, ".codex"), "config.toml");
+      return existsSync(file) && readFileSync(file, "utf8").includes(`[mcp_servers.${serverName}]`);
+    }
+  } catch {
+    // An unreadable config is not an answer; fall through to the other signals.
+  }
+  return false;
+}
+
+/**
+ * Which agent this machine should pair as, or "" when only a person can say.
+ *
+ * Pairing needs an agent id, and demanding `--agent` for it turned "start the
+ * runner" into a command someone had to be told twice. The signals are ordered
+ * by how much they actually know: the session we are inside, then the agent
+ * PreMan is already configured in, then the only one installed. Asking is the
+ * last resort rather than the first, and a machine with no terminal to ask in
+ * gets "" so the caller can fail with a sentence instead of hanging on a prompt.
+ */
+export async function resolveAgentForPairing({ interactive = Boolean(process.stdin.isTTY) } = {}) {
+  const inside = runningInside();
+  if (inside) return inside;
+
+  const linked = AGENTS.filter((agent) => agentIsLinked(agent.id));
+  if (linked.length === 1) return linked[0].id;
+
+  const detected = detectAgents();
+  const present = AGENTS.filter((agent) => detected[agent.id]);
+  if (present.length === 1) return present[0].id;
+
+  if (!interactive) return "";
+  const picked = await promptAgentChoice(detected);
+  return picked?.id || "";
+}
+
+/**
+ * The agent a directly-invoked command should drive, as an object, or null.
+ *
+ * Same signals as pairing, resolved to the record `discoverEndpoints` needs,
+ * with an explicit `--agent` taking precedence so the command stays scriptable
+ * on a machine that has all three installed. Commands the user typed on purpose
+ * get to run the agent; the caller falls back to printing the brief on null,
+ * which is also what a non-interactive run with no clear answer gets.
+ */
+export async function resolveAgentToDrive({ agent = "", ...options } = {}) {
+  return findAgent(agent) || findAgent(await resolveAgentForPairing(options));
+}
+
+export async function promptAgentChoice(detected, insideId = runningInside()) {
+  process.stdout.write("Which coding agent?\n");
+  AGENTS.forEach((agent, index) => {
+    let mark = "";
+    if (agent.id === insideId) mark = "  (this session)";
+    else if (detected[agent.id]) mark = "  (detected)";
+    process.stdout.write(`  ${index + 1}. ${agent.label}${mark}\n`);
+  });
+
+  const inside = AGENTS.findIndex((a) => a.id === insideId);
+  const defaultIndex =
+    inside >= 0
+      ? inside
+      : 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);
+}