premanmcp 0.10.5 → 0.10.6

package/README.md

@@ -133,6 +133,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 +167,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 +235,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 +248,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/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

@@ -23,6 +23,7 @@ import {
   connectCommand,
   discoverEndpoints,
   dispatchCommand,
+  resolveAgentForPairing,
   writeCursorConfig,
 } from "./connect.js";
 import {
@@ -34,7 +35,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";
@@ -135,6 +136,7 @@ async function loginCommand() {
     await loginBrowser(cliArgs);
     return;
   }
+  const cli = cliInvocation();
   const creds = await authenticateTerminal(cliArgs);
   process.stdout.write(`PreMan account ready.
 
@@ -153,6 +155,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 +182,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 +219,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 +233,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") {

package/bin/connect.js

@@ -157,6 +157,52 @@ export function runningInside(env = process.env) {
   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 || "";
+}
+
 async function promptAgentChoice(detected, insideId = runningInside()) {
   process.stdout.write("Which coding agent?\n");
   AGENTS.forEach((agent, index) => {

package/bin/hook.js

@@ -8,9 +8,11 @@
  * by construction rather than by configuration.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { cliInvocation, makeArgs, packageVersion } from "./shared.js";
 import { BLOCK_EXIT_CODE } from "./verify.js";
@@ -20,14 +22,23 @@ Hook options:
   install               Write the pre-push hook into this repository
   uninstall             Remove PreMan's pre-push hook
   status                Report whether the hook is installed, and still works
+  repair                Rewrite a hook of ours whose command no longer answers
   --force               Overwrite a foreign pre-push hook (a backup is kept)
   PREMAN_HOOK_INVOCATION=<cmd>  Use this command line instead of probing for one
+  PREMAN_NO_HOOK_REPAIR=1       Never repair a hook in the background
 `;
 
 const MARKER = "# >>> preman pre-push >>>";
 const END_MARKER = "# <<< preman pre-push <<<";
 const HOOK_TIMEOUT_SECONDS = 120;
 const PROBE_TIMEOUT_MS = 45000;
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HEALTH_FILE = path.join(os.homedir(), ".preman", "hook-health.json");
+// How long a healthy answer is believed for. The repair costs a probe, and a
+// hook that worked an hour ago almost always still works, so this is the knob
+// that keeps a background check off the critical path of every command.
+const RECHECK_MS = 60 * 60 * 1000;
+const HEALTH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 
 function gitDir() {
   const result = spawnSync("git", ["rev-parse", "--git-dir"], { encoding: "utf8" });
@@ -259,6 +270,94 @@ export function hookStatus({ probe = false } = {}) {
   };
 }
 
+function readHookChecks() {
+  try {
+    const parsed = JSON.parse(readFileSync(HEALTH_FILE, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Remember what a check found, so the next command does not pay for it again. */
+function rememberHookCheck(cwd, now, fields) {
+  const checks = readHookChecks();
+  for (const [key, value] of Object.entries(checks)) {
+    if (now - Number(value?.at || 0) > HEALTH_TTL_MS) delete checks[key];
+  }
+  checks[cwd] = { at: now, ...fields };
+  try {
+    mkdirSync(path.dirname(HEALTH_FILE), { recursive: true });
+    writeFileSync(HEALTH_FILE, JSON.stringify(checks, null, 2) + "\n", { mode: 0o600 });
+  } catch {
+    // A cache we cannot write costs a probe next time and nothing else.
+  }
+  return { cwd, ...fields };
+}
+
+/**
+ * Put a hook of ours back into working order, without being asked.
+ *
+ * The failure this exists for is invisible: a hook written by a version that
+ * embedded the wrong command keeps printing one skipped line per push, and
+ * nothing re-runs `connect` after an upgrade to notice. So anything that proves
+ * PreMan is running here -- any command, the MCP server starting -- is taken as
+ * the moment to check.
+ *
+ * Deliberately narrow. It only ever rewrites a hook we wrote that no longer
+ * answers: an absent hook is not installed behind the user, a foreign hook is
+ * not touched, and a hook that works is left on whatever version it pins.
+ */
+export function repairDeadHook({ cwd = process.cwd(), now = Date.now(), force = false } = {}) {
+  const remember = (fields) => rememberHookCheck(cwd, now, fields);
+  if (!force) {
+    const last = readHookChecks()[cwd];
+    if (last && now - Number(last.at || 0) < RECHECK_MS) return { cwd, action: "recent" };
+  }
+
+  let status;
+  try {
+    status = hookStatus({ probe: true });
+  } catch {
+    return remember({ action: "not-a-repository" });
+  }
+  if (status.state !== "installed") return remember({ action: status.state });
+  if (status.works) return remember({ action: "healthy", invocation: status.invocation });
+
+  const result = installHook(makeArgs([]));
+  return remember({
+    action: result.action === "updated" ? "repaired" : result.action,
+    invocation: result.invocation || "",
+    replaced: status.invocation,
+  });
+}
+
+/**
+ * Run the repair in a detached child, because every step of it is synchronous
+ * and one of them shells out to npm. Nothing that merely wants a healthy hook
+ * should wait on a probe, least of all the MCP server, whose stdout is a
+ * protocol -- hence stdio ignored rather than inherited.
+ */
+export function scheduleHookRepair({ cwd = process.cwd(), now = Date.now() } = {}) {
+  if (process.env.PREMAN_HOOK) return { action: "skipped", reason: "running inside the hook" };
+  if (process.env.PREMAN_NO_HOOK_REPAIR) return { action: "skipped", reason: "disabled" };
+  const last = readHookChecks()[cwd];
+  if (last && now - Number(last.at || 0) < RECHECK_MS) {
+    return { action: "skipped", reason: "checked recently" };
+  }
+  try {
+    const child = spawn(process.execPath, [path.join(__dirname, "cli.js"), "hook", "repair"], {
+      cwd,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+    return { action: "spawned", pid: child.pid };
+  } catch {
+    return { action: "skipped", reason: "could not spawn" };
+  }
+}
+
 export async function hookCommand(commandArgs = []) {
   const sub = commandArgs.find((value) => !value.startsWith("-")) || "status";
   const args = makeArgs(commandArgs);
@@ -279,6 +378,22 @@ export async function hookCommand(commandArgs = []) {
     return result;
   }
 
+  if (sub === "repair") {
+    // Asked for by hand, "repair" means now: the hourly gate exists to keep this
+    // off the critical path of unrelated commands, not to refuse a person.
+    const result = repairDeadHook({ force: !args.has("--if-stale") });
+    const said = {
+      repaired: () => `Pre-push hook repaired: it now runs ${result.invocation}\n`,
+      healthy: () => "Pre-push hook already works here.\n",
+      recent: () => "Pre-push hook checked recently; nothing to do.\n",
+      absent: () => `No PreMan hook here. Install one: ${cliInvocation()} hook install\n`,
+      foreign: () => "The pre-push hook here is not ours; left alone.\n",
+      unproven: () => "Cannot repair: no way to run the PreMan CLI was found here.\n",
+    }[result.action];
+    process.stdout.write(said ? said() : `Pre-push hook: ${result.action}\n`);
+    return result;
+  }
+
   if (sub === "uninstall") {
     const result = uninstallHook();
     process.stdout.write(

package/bin/runner.js

@@ -765,8 +765,9 @@ async function goOffline(args, state, log = defaultLog) {
 
 export const RUNNER_HELP = `
 Runner options:
-  runner start [--background]   Hold the job stream and run queued work here
-  runner register [--agent a]   Pair this machine as a runner (connect does this)
+  runner start [--background]   Hold the job stream and run queued work here,
+                                pairing this machine first if it is not paired
+  runner register [--agent a]   Pair without starting (start does this for you)
   runner status                 Report whether the local runner is running
   runner stop                   Stop the background runner and go offline
   --agent <name>                claude-code | cursor | codex
@@ -858,7 +859,9 @@ async function startForeground(args, commandArgs) {
     const agent = normalizeAgentId(args.value("--agent", "")) || "";
     if (!agent) {
       throw new RunnerError(
-        `This machine is not paired as a runner yet. Run '${cliInvocation()} runner register --agent claude-code'.`,
+        "This machine is not paired as a runner yet, and which agent to pair as could not be" +
+          ` worked out here. Say so directly: '${cliInvocation()} runner start --background` +
+          " --agent cursor|claude-code|codex'.",
         2
       );
     }
@@ -915,9 +918,22 @@ async function startForeground(args, commandArgs) {
   }
 }
 
-export async function runnerCommand(commandArgs = []) {
+export async function runnerCommand(commandArgs = [], { resolveAgent = null } = {}) {
   const sub = commandArgs.find((value) => !value.startsWith("-")) || "status";
-  const args = makeArgs(commandArgs);
+  let args = makeArgs(commandArgs);
+
+  // Pairing needs an agent id, and the only place that can be asked for one is
+  // here: `--background` hands the work to a detached child with no terminal, so
+  // a question deferred to it is a question nobody ever sees.
+  if ((sub === "register" || sub === "start") && resolveAgent && !args.value("--agent", "")) {
+    if (sub === "register" || !readRunnerState()) {
+      const resolved = await resolveAgent();
+      if (resolved) {
+        commandArgs = [...commandArgs, "--agent", resolved];
+        args = makeArgs(commandArgs);
+      }
+    }
+  }
 
   if (sub === "register") {
     const agent = normalizeAgentId(args.value("--agent", ""));
@@ -966,7 +982,7 @@ export async function runnerCommand(commandArgs = []) {
     const alive = runnerIsAlive(pid);
     if (!state) {
       process.stdout.write(
-        `Local runner: not paired\n  Pair it: ${cliInvocation()} runner register --agent claude-code\n`
+        `Local runner: not paired\n  Start it: ${cliInvocation()} runner start --background\n`
       );
       return { state: "unpaired" };
     }

package/dist/server.js

@@ -3,10 +3,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { registerUserAuthFlowTools } from "./user_auth_flow.js";
 import { shareAuthFlowToUi } from "./auth_flow_ui.js";
+import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { MCP_PREVIEW_RESOURCE_URI, RESOURCE_URI_META_KEY, buildConversionPanelHtml, writeMcpPreviewFile, } from "./mcp-preview-panel.js";
 let REPO_CONFIG = null;
@@ -1444,11 +1446,34 @@ export function createServer() {
     return server;
 }
 // ── Start ─────────────────────────────────────────────────────────────
+/**
+ * A pre-push hook PreMan wrote can stop working — the machine gained a `preman`
+ * belonging to another package, or lost the one it pinned — and the only symptom
+ * is one skipped line per push. This process starting is proof PreMan runs here,
+ * so it is a good moment to check. Detached with stdio ignored: the check shells
+ * out to npm, and this process's stdout is the MCP protocol.
+ */
+function repairPushHookInBackground() {
+    try {
+        const cli = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "bin", "cli.js");
+        if (!existsSync(cli))
+            return;
+        const child = spawn(process.execPath, [cli, "hook", "repair", "--if-stale"], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+    }
+    catch {
+        // Never worth failing a server start over.
+    }
+}
 async function main() {
     await initAuth();
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    repairPushHookInBackground();
     // Starting the configured MCP server is itself proof that the coding agent
     // is live.  Previously the workbench remained in `connecting` until someone
     // explicitly asked the agent to call `preman_status`, even when this process

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "open-mcp-preview-in-cursor": "node scripts/open-cursor-preview.mjs",
     "test": "npm run build && npm run test:connect && npm run test:node",
     "test:connect": "node scripts/smoke-connect.mjs",
-    "test:node": "node --test --test-timeout=30000 scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs"
+    "test:node": "node --test --test-timeout=90000 scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-api-tools.mjs scripts/smoke-bin-scope.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^0.1.0",