premanmcp 0.10.4 → 0.10.6

package/README.md

@@ -64,21 +64,28 @@ and then retries from your home directory, where the override cannot reach it
 first, then your agent. Agents you start in the overriding directory keep using its
 backend, which is the point of the file.
 
-Once linked, `connect` finishes onboarding without handing you homework:
+Once linked, `connect` installs the git pre-push hook — so `git push` checks the endpoints
+you touched — prints what is left, and stops. It asks nothing. Everything else it used to
+run is its own command, because each one can fail on its own and none of them should hold
+up a link that already worked:
 
-| Step | What happens |
-|------|--------------|
-| Endpoints | Runs your agent on the discovery brief, then reports `N endpoints · M runnable` |
-| First test | Generates and runs scenarios against the first runnable request |
-| Runner | Pairs this machine and starts `preman runner` in the background, so PreMan can apply fixes here instead of only describing them |
-| Desktop app | Offers the macOS app for watching runs and endpoints |
-| Integrations | Shows GitHub / AWS / Slack, opens what is missing, and picks the connection up when you finish in the browser or the desktop app |
-| Testing on push | Installs the git pre-push hook, so `git push` checks the endpoints you touched |
+```bash
+preman endpoints discover          # map this repo's endpoints
+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
+```
+
+`preman onboard` (or `setup`) is the prompted walk through all of it — sign in, coding
+agent, endpoints, runner, GitHub, AWS, Slack — one question per step, `b` to go back, and a
+summary at the end. `connect --guide` runs the old full pass inside connect itself:
+discovery, a first test, the runner, the desktop app and the integration prompts.
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-project-local config, `--print` shows the config without writing it, `--yes` takes every
-step's default without asking, `--no-guide` skips all of them, and `--no-runner` /
-`--no-desktop` / `--no-integrations` / `--no-hook` skip one each.
+project-local config, `--print` shows the config without writing it, `--no-hook` leaves
+push testing alone, and `--no-guide` connects and nothing else. With `--guide`, `--yes`
+takes every step's default without asking and `--no-runner` / `--no-desktop` /
+`--no-integrations` skip one each.
 
 `--yes` deliberately does *not* install the desktop app: that step's default is no, because
 it downloads a hundred-odd megabytes and writes to `/Applications`. Run `install-desktop`
@@ -126,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.
@@ -159,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.
 ```
@@ -218,17 +230,51 @@ npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API
 npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ```
 
+### Push testing
+
+```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
+```
+
+The hook is generated shell that runs `preman verify --pre-push` and can only ever be
+advisory: no backend, no credentials, a crash or a timeout all exit 0 with a notice. Before
+writing it, `install` runs the command it is about to embed and requires an answer — a hook
+holding a `preman` that belongs to another package prints `checks skipped` at every push and
+looks installed forever. The embedded command is pinned to the version that wrote it rather
+than `@latest`, so upgrading us never changes what your pushes run; re-run `hook install`
+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` 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

@@ -11,6 +11,7 @@ import { existsSync, rmSync } from "node:fs";
 import os from "node:os";
 
 import { detectCandidates } from "./detect.js";
+import { hookStatus } from "./hook.js";
 import {
   CREDENTIALS_FILE,
   backendUrl,
@@ -150,6 +151,39 @@ export async function doctorCommand(commandArgs = []) {
     )
   );
 
+  // 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
+  // skipped line and nothing else ever mentions it.
+  const hook = (() => {
+    try {
+      return hookStatus({ probe: true });
+    } catch {
+      return null; // not a git repository
+    }
+  })();
+  if (hook && hook.state === "installed") {
+    results.push(
+      line(
+        "push hook",
+        hook.works,
+        hook.works
+          ? `${hook.invocation}${hook.current ? "" : ` — out of date, run \`${cliInvocation()} hook install --force\``}`
+          : `${hook.invocation || "unreadable"} does not answer — run \`${cliInvocation()} hook install --force\``
+      )
+    );
+    if (!hook.works) failures += 1;
+  } else if (hook) {
+    results.push(
+      line(
+        "push hook",
+        null,
+        hook.state === "foreign"
+          ? "another tool owns pre-push here"
+          : `not installed — run \`${cliInvocation()} hook install\``
+      )
+    );
+  }
+
   if (status?.ok) {
     const integrations = status.integrations || {};
     for (const [name, section] of Object.entries(integrations)) {

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

@@ -21,7 +21,9 @@ import {
   CONNECT_HELP,
   DISPATCH_HELP,
   connectCommand,
+  discoverEndpoints,
   dispatchCommand,
+  resolveAgentForPairing,
   writeCursorConfig,
 } from "./connect.js";
 import {
@@ -33,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";
@@ -84,7 +86,7 @@ function printHelp() {
     ["runner start|status|stop", "Run PreMan's queued agent work on this machine"],
     ["doctor", "Diagnose credentials, backend, target, integrations"],
     ["install-desktop", "Download and install the PreMan desktop app"],
-    ["onboard", "Sign in, then connect agent, GitHub, AWS, Slack"],
+    ["onboard", "Sign in, then agent, endpoints, runner, GitHub, AWS, Slack"],
     ["connect [options]", "Pick a coding agent and connect it"],
     ["dispatch [options]", "Let PreMan start agent runs for you"],
     ["aws | github | slack", "Connect one integration on its own"],
@@ -134,6 +136,7 @@ async function loginCommand() {
     await loginBrowser(cliArgs);
     return;
   }
+  const cli = cliInvocation();
   const creds = await authenticateTerminal(cliArgs);
   process.stdout.write(`PreMan account ready.
 
@@ -152,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");
 
@@ -178,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."
@@ -215,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") {
@@ -224,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") {
@@ -240,7 +252,13 @@ async function main() {
   } else if (command === "onboard" || command === "setup") {
     // makeArgs/authenticateTerminal/connectCommand are injected rather than
     // imported there, so integrations.js stays free of a cycle back into the CLI.
-    await onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand });
+    await onboardCommand(commandArgs, {
+      makeArgs,
+      authenticateTerminal,
+      connectCommand,
+      discoverEndpoints,
+      runnerCommand,
+    });
   } else if (command === "aws") {
     await awsCommand(makeArgs(commandArgs));
   } else if (command === "github") {

package/bin/connect.js

@@ -21,6 +21,7 @@ import { installHook, hookStatus } from "./hook.js";
 import { MARK, awsCommand, githubCommand, slackCommand } from "./integrations.js";
 import {
   confirmRunnerOnline,
+  pairingIsLive,
   readRunnerState,
   registerRunner,
   runnerIsAlive,
@@ -156,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) => {
@@ -1060,6 +1107,26 @@ function nextStepsBlock(agent) {
   );
 }
 
+/**
+ * What is left once the link is done, as commands rather than as questions.
+ *
+ * Connect used to run all of these itself, which bought a prompt per step and a
+ * wait as long as the slowest broken one — and a link that had already succeeded
+ * ended on a failed runner and a five-minute GitHub poll. Each is one command, so
+ * this lists them and gets out of the way.
+ */
+function whatIsLeftBlock(args) {
+  const cli = cliInvocation();
+  return (
+    "\nWhat is left:\n" +
+    `  ${cli} endpoints discover          # map this repo's endpoints\n` +
+    `  ${cli} runner start --background   # let PreMan apply fixes on this machine\n` +
+    `  ${cli} github                      # connect GitHub, or do it in the dashboard\n` +
+    `\n${cli} status reports your endpoints, last push and integrations.\n` +
+    `Watch runs at ${frontendUrl(args)}\n`
+  );
+}
+
 /**
  * Ask, or take the step's own default when nobody can answer.
  *
@@ -1130,7 +1197,7 @@ export function headlessDiscovery(agent, serverName, instructions = []) {
  *
  * Never throws: a failed discovery must not fail the connect.
  */
-async function discoverEndpoints(args, agent, serverName, blockedHere = "") {
+export async function discoverEndpoints(args, agent, serverName, blockedHere = "") {
   try {
     const before = await endpointCounts(args);
     if (before.registered) {
@@ -1241,6 +1308,24 @@ async function runFirstTest(args, runnable, { assumeYes }) {
   }
 }
 
+/**
+ * Whether a stored pairing can still be used, rather than merely matching.
+ *
+ * Matching agent and path only prove the state was written for this project. The
+ * token behind it can be revoked, replaced by another device, or left over from an
+ * API key that no longer exists — and reusing one of those starts a daemon that
+ * 401s on its first stream and exits, which reads as "the runner cannot start
+ * here" when the pairing is the only thing that needed replacing.
+ *
+ * A backend we cannot reach answers "usable": re-pairing is for a token the
+ * backend rejected, not for a network that was briefly down.
+ */
+export async function runnerPairingIsUsable(args, existing, agentId, { cwd = process.cwd() } = {}) {
+  if (!existing || existing.agent !== agentId) return false;
+  if (path.resolve(String(existing.project_path || "")) !== path.resolve(cwd)) return false;
+  return pairingIsLive(args, existing);
+}
+
 /**
  * Pair this machine as a runner and leave it running.
  *
@@ -1267,7 +1352,7 @@ async function setUpRunner(args, agent, { assumeYes }) {
   }
 
   try {
-    if (!existing || existing.agent !== agent.id || existing.project_path !== path.resolve(process.cwd())) {
+    if (!(await runnerPairingIsUsable(args, existing, agent.id))) {
       await registerRunner(args, { agent: agent.id, projectPath: process.cwd() });
     }
     const started = startBackground([]);
@@ -1409,7 +1494,7 @@ async function setUpPushTesting(args) {
   if (args.has("--no-hook")) return { state: "skipped" };
   const current = (() => {
     try {
-      return hookStatus();
+      return hookStatus({ probe: true });
     } catch {
       return null; // not a git repository
     }
@@ -1418,9 +1503,10 @@ async function setUpPushTesting(args) {
     process.stdout.write(`${MARK.skip()} Not a git repository — no push testing here.\n`);
     return { state: "unavailable" };
   }
-  // A hook whose invocation went stale is reinstalled rather than reported as on:
-  // it is the case where PreMan looks connected and silently checks nothing.
-  if (current.state === "installed" && current.current) {
+  // A hook whose invocation went stale, or no longer answers, is reinstalled
+  // rather than reported as on: it is the case where PreMan looks connected and
+  // silently checks nothing.
+  if (current.state === "installed" && current.current && current.works) {
     process.stdout.write(`${MARK.ok()} Push testing already on.\n`);
     return { state: "installed" };
   }
@@ -1432,6 +1518,13 @@ async function setUpPushTesting(args) {
     );
     return result;
   }
+  if (result.action === "unproven") {
+    process.stdout.write(
+      `${MARK.skip()} No push testing: ${result.detail}\n` +
+        `   Then: ${cliInvocation()} hook install\n`
+    );
+    return result;
+  }
   process.stdout.write(
     `${MARK.ok()} Push testing on — \`git push\` now checks the endpoints you touched.\n` +
       "   It never blocks a push; PREMAN_SKIP_HOOK=1 silences it.\n"
@@ -1440,10 +1533,12 @@ async function setUpPushTesting(args) {
 }
 
 /**
- * Everything after the link, in one pass, with nothing left for the user to run.
+ * Everything after the link, in one pass, for whoever asks for it with `--guide`.
  *
  * Order follows what a new account needs to see: what PreMan found, then where to
- * watch it, then who to tell, then when to run it.
+ * watch it, then who to tell, then when to run it. It is opt-in because running
+ * all of it unasked is what turned a finished connect into a screen of prompts,
+ * a dead runner and a five-minute wait on an integration nobody had asked for.
  */
 async function guidedFirstRun(args, agent, apiKey, serverName, { blockedHere = "" } = {}) {
   const assumeYes = args.has("--yes");
@@ -1544,10 +1639,12 @@ Connect options:
   --no-self-test              Do not start the MCP server to finish the link
   --no-auto-checkin           Do not run the agent to finish the link
   --no-wait                   Do not wait for the agent to check in
-  --no-guide                  Skip the guided first run after connecting
-  --no-runner                 Do not pair this machine as a job runner
-  --no-desktop                Do not offer the desktop app
-  --no-integrations           Do not check or offer GitHub / AWS / Slack
+  --guide                     Also run discovery, the runner, the desktop app
+                              and the integration prompts after connecting
+  --no-guide                  Connect only: no push hook, no closing summary
+  --no-runner                 With --guide, do not pair this machine as a runner
+  --no-desktop                With --guide, do not offer the desktop app
+  --no-integrations           With --guide, do not offer GitHub / AWS / Slack
   --no-hook                   Do not install the git pre-push hook
   --yes                       Take every step's default without prompting
                               (the desktop app defaults to no; install-desktop)
@@ -1670,18 +1767,36 @@ export async function connectCommand(commandArgs) {
     serverConfig,
     projectInstall,
   });
+  // The agent goes back to the caller because `onboard` runs steps after this one
+  // that need to know which agent to drive, and asking twice is a question we
+  // already have the answer to.
+  const connected = { agent, serverName, linked: checkIn.linked };
   if (!checkIn.linked) {
     // Still honour an explicitly-passed credential, but do not open a new prompt
     // on top of a connect that just told the user something went wrong.
     await captureDispatchCredential(args, agent, apiKey, { prompt: false });
-    return;
+    return connected;
   }
 
   process.stdout.write(`${MARK.ok()} Connected as ${agent.label}.\n`);
-  if (!args.has("--no-guide")) {
+
+  // Connecting is one job. Running discovery, pairing a runner, offering the
+  // desktop app and installing three integrations is five more, each with its
+  // own prompt and its own way to fail -- and a connect that ends in a failed
+  // runner and a five-minute GitHub poll reads as a broken product rather than a
+  // finished link. The push hook stays because it is the only one that is not a
+  // question: it is what makes PreMan run at all, and it costs a file write.
+  if (args.has("--guide") && !args.has("--no-guide")) {
     await guidedFirstRun(args, agent, apiKey, serverName, { blockedHere: checkIn.blockedHere });
+    await captureDispatchCredential(args, agent, apiKey);
+    return connected;
   }
-  await captureDispatchCredential(args, agent, apiKey);
+  if (!args.has("--no-guide")) {
+    await setUpPushTesting(args);
+    process.stdout.write(whatIsLeftBlock(args));
+  }
+  await captureDispatchCredential(args, agent, apiKey, { prompt: false });
+  return connected;
 }
 
 /**