premanmcp 0.10.6 → 0.11.0

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

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

@@ -9,6 +9,7 @@
 import { readFileSync } from "node:fs";
 
 import { callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
+import { printPlayground } from "./desktop.js";
 
 export const ENDPOINTS_HELP = `
 Endpoints:
@@ -144,6 +145,13 @@ export async function endpointsCommand(commandArgs) {
     if (requests.length) {
       process.stdout.write(`runnable as: ${requests.join(", ")}\n`);
     }
+    const url = result.ui?.url || result.url;
+    printPlayground(url);
+    if (result.campaign?.id) {
+      process.stdout.write(
+        `test campaign ${result.campaign.id}: ${result.campaign.queued || 0} queued, ${result.campaign.skipped || 0} skipped\n`,
+      );
+    }
     return undefined;
   }
 

package/bin/cli.js

@@ -17,6 +17,7 @@ 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,
@@ -56,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]
@@ -98,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
@@ -108,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}
@@ -277,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);
+}