premanmcp 0.8.0 → 0.10.0

package/README.md

@@ -19,11 +19,12 @@ Local development form:
 node bin/cli.js connect
 ```
 
-First-time users are prompted for email, OTP, and password directly in the terminal.
-PreMan creates or connects the account, generates an API key, saves it to
-`~/.preman/credentials.json`, then writes a `preman` MCP server into the config your
-agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
-`~/.codex/config.toml`):
+First-time users are asked for an email and the code sent to it — no password: the
+terminal's credential is the `pm_live_` key. Pass `--password` to also set one for
+dashboard sign-in, or set it later from the dashboard. PreMan creates or connects the
+account, generates an API key, saves it to `~/.preman/credentials.json`, then writes a
+`preman` MCP server into the config your agent actually reads (`~/.cursor/mcp.json`,
+Claude Code's MCP config, or `~/.codex/config.toml`):
 
 ```json
 {
@@ -40,19 +41,36 @@ agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
 }
 ```
 
-Restart your agent afterwards, then ask it to `run preman_status` to finish linking.
-
 `connect` reads the config back after writing it, and prints a copy-paste snippet if it
-cannot confirm the entry landed. It then waits for your agent to check in — that
-check-in is the only real proof the agent loaded the server.
-
-Once the agent has checked in, `connect` walks you into your first test: it runs one
-against an endpoint you already have, or prints the discovery brief to hand your agent,
-followed by `preman endpoints setup` and `preman test`. Pass `--no-guide` to skip it.
+cannot confirm the entry landed. Then it finishes the link itself rather than asking you
+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. **Headless agent run** (`claude -p`, `cursor-agent -p`, `codex exec`), which also
+   proves your agent can load what was written. `--no-auto-checkin` turns it off.
+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
+redirected it — a repo-local `preman-mcp.config.json` with `"PREMAN_CONFIG_OVERRIDE": true`
+wins over the MCP config env, and otherwise only fills in what the env leaves unset.
+
+Once linked, `connect` finishes onboarding without handing you homework:
+
+| 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 |
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-project-local config, `--print` shows the config without writing it, `--no-guide` skips
-the guided first run.
+project-local config, `--print` shows the config without writing it, `--yes` accepts every
+optional step, `--no-guide` skips all of them, and `--no-runner` / `--no-desktop` /
+`--no-integrations` / `--no-hook` skip one each.
 
 In CI or any non-interactive shell, run `connect --agent <name> --api-key pm_live_…`.
 Without `--agent` there is nothing to prompt on, so `connect` prints ready-to-paste
@@ -62,10 +80,18 @@ setup blocks for all three agents and exits 2.
 
 ### Cloud dispatch (optional)
 
-`connect` offers to store a coding-agent credential — a Cursor API key, or a Claude
-Code routine token and id. With one saved, PreMan can start an agent run for you when
-it finds a failing endpoint instead of handing back a prompt to paste. Press Enter to
-skip; everything else still works.
+With a coding-agent credential saved — a Cursor API key from
+`cursor.com/dashboard → Integrations → API Keys`, or a Claude Code routine token and id
+from `claude.ai/code/routines → your routine → Add API trigger` — PreMan can start an
+agent run for you when it finds a failing endpoint, instead of handing back a prompt to
+paste.
+
+`connect` asks for it once you are already set up, so skipping costs nothing. Come back
+to it any time:
+
+```bash
+npm exec -y premanmcp@latest -- dispatch
+```
 
 You can also create or connect your account first:
 
@@ -180,6 +206,24 @@ npm exec -y premanmcp@latest -- login   # Create/login and generate a PreMan API
 npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ```
 
+### Runner
+
+`connect` sets 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)
+```
+
+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
+and refuses any job that names a different one. The agent may edit files; running commands
+needs `--full-access` (or `PREMAN_RUNNER_FULL_ACCESS=1`). Nothing runs until PreMan has
+something to fix, and `preman runner stop` ends it.
+
 Options:
 
 - `--api-key <key>`: PreMan API key.

package/bin/account.js

@@ -8,7 +8,6 @@
  */
 
 import { existsSync, rmSync } from "node:fs";
-import { spawn } from "node:child_process";
 import os from "node:os";
 
 import { detectCandidates } from "./detect.js";
@@ -19,6 +18,7 @@ import {
   cliInvocation,
   frontendUrl,
   makeArgs,
+  openUrl,
   readStoredCredentials,
   resolveApiKey,
   saveStoredCredentials,
@@ -35,17 +35,6 @@ Account options:
 const POLL_INTERVAL_MS = 3000;
 const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 
-function openBrowser(url) {
-  const opener =
-    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  try {
-    spawn(opener, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 export async function loginBrowser(args) {
@@ -61,7 +50,7 @@ export async function loginBrowser(args) {
     `\nApprove this device in your browser:\n  ${verificationUrl}\n\n` +
       `Confirmation code: ${start.user_code}\n\n`
   );
-  if (!openBrowser(verificationUrl)) {
+  if (!openUrl(verificationUrl)) {
     process.stdout.write("Could not open a browser automatically — open the link above.\n");
   }
   process.stdout.write("Waiting for approval…\n");

package/bin/cli.js

@@ -17,7 +17,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { ENDPOINTS_HELP, TEST_HELP, endpointsCommand, testCommand } from "./api_tools.js";
-import { CONNECT_HELP, connectCommand, writeCursorConfig } from "./connect.js";
+import {
+  CONNECT_HELP,
+  DISPATCH_HELP,
+  connectCommand,
+  dispatchCommand,
+  writeCursorConfig,
+} from "./connect.js";
 import {
   INTEGRATIONS_HELP,
   awsCommand,
@@ -28,6 +34,7 @@ import {
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import { STATUS_HELP, statusCommand } from "./status.js";
 import { HOOK_HELP, hookCommand } from "./hook.js";
+import { RUNNER_HELP, runnerCommand } from "./runner.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
 import { DESKTOP_HELP, installDesktopCommand } from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
@@ -74,10 +81,12 @@ function printHelp() {
     ["status", "Healthy / failing / recently fixed endpoints"],
     ["verify [options]", "Test endpoints against your local app"],
     ["hook install|uninstall|status", "Manage the git pre-push hook"],
+    ["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"],
     ["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"],
     ["login [--browser]", "Create/login to PreMan from the terminal"],
     ["logout", "Delete stored CLI credentials"],
@@ -97,7 +106,7 @@ function printHelp() {
 
 Usage:
 ${usageLines}
-${INTEGRATIONS_HELP}${CONNECT_HELP}${STATUS_HELP}${VERIFY_HELP}${HOOK_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}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
@@ -214,6 +223,8 @@ async function main() {
     await verifyCommand(commandArgs);
   } else if (command === "hook") {
     await hookCommand(commandArgs);
+  } else if (command === "runner") {
+    await runnerCommand(commandArgs);
   } else if (command === "logout") {
     await logoutCommand();
   } else if (command === "doctor") {
@@ -224,6 +235,8 @@ async function main() {
     await installDesktopCommand(commandArgs);
   } else if (command === "connect") {
     await connectCommand(commandArgs);
+  } else if (command === "dispatch") {
+    await dispatchCommand(commandArgs);
   } 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.