premanmcp 0.3.4 → 0.4.0

package/README.md

@@ -7,19 +7,24 @@ PreMan is agent-first API infrastructure. It lets backend teams expose endpoints
 ## Install
 
 ```bash
-npx premanmcp install
+npm exec -y premanmcp@latest -- install
 ```
 
-This writes an `preman` MCP server into `~/.cursor/mcp.json`:
+Local development form:
+
+```bash
+node bin/cli.js install
+```
+
+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 `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "preman": {
-      "command": "npx",
-      "args": ["-y", "premanmcp"],
+      "command": "npm",
+      "args": ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"],
       "env": {
-        "PREMAN_API_KEY": "pm_live_YOUR_API_KEY_HERE",
         "PREMAN_BACKEND": "https://api.preman.live",
         "PREMAN_FRONTEND": "https://app.preman.live"
       }
@@ -28,35 +33,47 @@ This writes an `preman` MCP server into `~/.cursor/mcp.json`:
 }
 ```
 
-Replace `pm_live_YOUR_API_KEY_HERE` with an API key from [PreMan settings](https://app.preman.live/settings/), then restart Cursor or toggle the MCP server off/on.
+Restart Cursor or toggle the MCP server off/on after install. The MCP server loads the saved key automatically.
+
+You can also create or connect your account before install:
+
+```bash
+npm exec -y premanmcp@latest -- login
+```
 
 You can also pass the key directly:
 
 ```bash
-npx premanmcp install --api-key pm_live_xxx
+npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
 ```
 
 For project-local installation:
 
 ```bash
-npx premanmcp install --project
+npm exec -y premanmcp@latest -- install --project
 ```
 
 ## What It Does
 
 - Converts API endpoints into agent-callable MCP tools.
+- 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.
 - Adds API-key auth for PreMan MCP access.
 - Supports hosted MCPs with consumer tokens for customer-facing agent access.
 - Records per-call observability so teams can audit which agent did what.
+- Hands failing-endpoint alerts to your agent as fix tasks (`preman_get_fix_task` → repro curl → `preman_complete_fix_task`).
 
 ## Common Agent Commands
 
 After installing, ask your coding agent:
 
 ```text
-Use the PreMan MCP to convert my login endpoint into an MCP tool.
+Use PreMan to convert the endpoints I choose into a hosted MCP server, then give me the Cursor/Claude install snippet.
+```
+
+```text
+Use PreMan to sign me up, verify my email OTP, create my API key, then scan this project.
 ```
 
 ```text
@@ -71,12 +88,16 @@ Convert these endpoints into an MCP.
 Show me the audit log for this hosted MCP.
 ```
 
+```text
+Pull my pending PreMan fix tasks and fix the failing endpoint.
+```
+
 ## Cursor
 
 The installer targets Cursor by default:
 
 ```bash
-npx premanmcp install
+npm exec -y premanmcp@latest -- install
 ```
 
 Manual Cursor config:
@@ -85,11 +106,8 @@ Manual Cursor config:
 {
   "mcpServers": {
     "preman": {
-      "command": "npx",
-      "args": ["-y", "premanmcp"],
-      "env": {
-        "PREMAN_API_KEY": "pm_live_YOUR_API_KEY_HERE"
-      }
+      "command": "npm",
+      "args": ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"]
     }
   }
 }
@@ -98,17 +116,18 @@ Manual Cursor config:
 ## Claude Code
 
 ```bash
-claude mcp add preman -- npx -y premanmcp
+claude mcp add preman -- npm exec -y --package premanmcp@latest -- premanmcp
 ```
 
 ## CLI
 
 ```bash
-npx premanmcp                         # Start the MCP server
-npx premanmcp install                 # Install Cursor MCP config
-npx premanmcp install --print         # Print config without writing
-npx premanmcp install --project       # Write .cursor/mcp.json in current repo
-npx premanmcp install --api-key KEY   # Install with your PreMan API key
+npm exec -y premanmcp@latest --       # Start the MCP server
+npm exec -y premanmcp@latest -- login # Create/login and generate a PreMan API key
+npm exec -y premanmcp@latest -- install          # Install Cursor MCP config
+npm exec -y premanmcp@latest -- install --project # Write .cursor/mcp.json in current repo
+npm exec -y premanmcp@latest -- install --print   # Print config without writing
+npm exec -y premanmcp@latest -- install --api-key KEY # Install with your PreMan API key
 ```
 
 Options:
@@ -118,13 +137,48 @@ Options:
 - `--frontend <url>`: PreMan frontend URL. Defaults to `https://app.preman.live`.
 - `--name <name>`: MCP server name. Defaults to `preman`.
 - `--project`: Write `.cursor/mcp.json` in the current project.
+- `--skip-login`: Install config without interactive terminal auth.
 - `--print`: Print the generated MCP config without writing it.
 
+## Run a hosted MCP from the terminal
+
+Installing the package also gives you a `preman` command. Once a selection is published as a
+hosted MCP, you can call its tools straight from a shell — same published selection, same
+consumer token, and same audit trail as an agent calling `POST /h/<id>/mcp`. Updating the
+selection updates the terminal; there is nothing to re-install.
+
+```bash
+preman link https://api.preman.live/h/<id>/mcp --env staging --token pm_hmcp_xxx
+preman tools --env staging
+preman run post_users_id_orders --env staging --arg id=42 --json '{"body":{"sku":"A1"}}'
+```
+
+`link` takes the URL straight from the deploy install snippet (a bare hosted MCP id works too,
+with `--backend`). Profiles are stored in `~/.preman/cli.json` (mode 0600); `--env <name>`
+picks one. Tool names are the ones the runtime publishes — run `preman tools` to see them.
+
+Run options:
+
+- `--env <name>`: Profile to use. Falls back to `PREMAN_MCP_URL`, then the default profile.
+- `--arg key=value`: String argument (repeatable). `--arg key:=json` sends a JSON-typed value.
+- `--json '{...}'`: Full arguments object. `--json -` reads it from stdin.
+- `--timeout <seconds>`: Client-side timeout. Defaults to 60.
+- `--json-out`: Print the raw JSON-RPC result.
+- `<tool>` may be dotted — `preman run staging.get_orders` selects the profile inline.
+
+Exit codes: `0` success, `1` the tool returned an error, `2` usage, `3` authentication,
+`4` JSON-RPC error (e.g. unknown tool), `5` network failure.
+
 ## Environment Variables
 
 - `PREMAN_API_KEY`: PreMan API key.
 - `PREMAN_BACKEND`: PreMan backend URL.
 - `PREMAN_FRONTEND`: PreMan frontend URL.
+- `PREMAN_MCP_URL`: Hosted MCP endpoint (`…/h/<id>/mcp`) for `preman run`/`preman tools` when
+  `--env` is omitted — useful in CI, where no profile file exists.
+- `PREMAN_MCP_TOKEN`: Consumer token for `PREMAN_MCP_URL`.
+
+If `PREMAN_API_KEY` is omitted, the MCP server loads credentials from `~/.preman/credentials.json`.
 
 ## Product
 

package/bin/cli.js

@@ -4,22 +4,27 @@
  * PreMan CLI.
  *
  * Usage:
- *   npx premanmcp install
- *   npx premanmcp install --api-key pm_live_xxx
- *   npx premanmcp
+ *   npm exec -y premanmcp@latest -- login
+ *   npm exec -y premanmcp@latest -- install
+ *   npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
+ *   npm exec -y premanmcp@latest --
  */
 
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 const DEFAULT_BACKEND = "https://api.preman.live";
 const DEFAULT_FRONTEND = "https://app.preman.live";
-const API_KEY_PLACEHOLDER = "pm_live_YOUR_API_KEY_HERE";
+const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
+const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
 
 const args = process.argv.slice(2);
 const command = args[0] === "--help" || args[0] === "-h"
@@ -43,23 +48,31 @@ function printHelp() {
   process.stdout.write(`PreMan MCP
 
 Usage:
-  npx premanmcp install [options]  Install PreMan into Cursor MCP config
-  npx premanmcp                   Start the PreMan MCP server
+  npm exec -y premanmcp@latest -- login              Create/login to PreMan from the terminal
+  npm exec -y premanmcp@latest -- install [options]  Install PreMan into Cursor MCP config
+  npm exec -y premanmcp@latest --                    Start the PreMan MCP server
+  preman link|tools|run ...                          Drive a published hosted MCP
+
+Login options:
+  --email <email>       Pre-fill the email prompt
+  --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
 
 Install options:
-  --api-key <key>       PreMan API key. Defaults to ${API_KEY_PLACEHOLDER}
+  --api-key <key>       PreMan API key. If omitted, stored CLI credentials are used
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
   --frontend <url>      PreMan frontend URL. Defaults to ${DEFAULT_FRONTEND}
   --name <name>         MCP server name. Defaults to preman
   --project             Write .cursor/mcp.json in the current project
   --global              Write ~/.cursor/mcp.json (default)
+  --skip-login          Install config without interactive terminal auth
   --print               Print the config instead of writing it
 
 Examples:
-  npx premanmcp install
-  npx premanmcp install --api-key pm_live_xxx
-  npx premanmcp install --project --backend http://127.0.0.1:8000
-`);
+  npm exec -y premanmcp@latest -- login
+  npm exec -y premanmcp@latest -- install
+  npm exec -y premanmcp@latest -- install --api-key pm_live_xxx
+  npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
+${HOSTED_HELP}`);
 }
 
 function readJsonFile(filePath) {
@@ -73,25 +86,306 @@ function readJsonFile(filePath) {
   }
 }
 
+function readStoredCredentials() {
+  try {
+    const raw = readFileSync(CREDENTIALS_FILE, "utf8").trim();
+    if (!raw) return null;
+    const creds = JSON.parse(raw);
+    if (creds && typeof creds.api_key === "string" && creds.api_key.startsWith("pm_live_")) {
+      return creds;
+    }
+  } catch {
+    // No stored credentials yet.
+  }
+  return null;
+}
+
+function saveStoredCredentials(creds) {
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CREDENTIALS_FILE, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+}
+
+function backendUrl() {
+  return argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND).replace(/\/+$/, "");
+}
+
+async function promptText(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptSecret(question) {
+  if (!process.stdin.isTTY || !process.stdin.setRawMode) {
+    return promptText(question);
+  }
+
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const wasRaw = stdin.isRaw;
+    let value = "";
+
+    function cleanup() {
+      stdin.off("data", onData);
+      stdin.setRawMode(Boolean(wasRaw));
+      stdin.pause();
+    }
+
+    function onData(chunk) {
+      const text = String(chunk);
+      if (text === "\u0003") {
+        stdout.write("\n");
+        cleanup();
+        process.exit(130);
+      }
+      if (text === "\r" || text === "\n" || text === "\u0004") {
+        stdout.write("\n");
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (text === "\u007f" || text === "\b") {
+        if (value.length) {
+          value = value.slice(0, -1);
+          stdout.write("\b \b");
+        }
+        return;
+      }
+      value += text;
+      stdout.write("*");
+    }
+
+    stdout.write(question);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    stdin.on("data", onData);
+  });
+}
+
+async function promptPasswordTwice() {
+  const password = await promptSecret("Create password: ");
+  if (!password || password.length < 6) {
+    throw new Error("Password must be at least 6 characters.");
+  }
+  const confirm = await promptSecret("Confirm password: ");
+  if (password !== confirm) {
+    throw new Error("Passwords do not match.");
+  }
+  return password;
+}
+
+async function callBackendJson(method, routePath, { json, token, query } = {}) {
+  const url = new URL(routePath.replace(/^\/+/, ""), `${backendUrl()}/`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value != null && value !== "") url.searchParams.set(key, String(value));
+    }
+  }
+
+  const headers = { Accept: "application/json" };
+  const hasBody = json !== undefined && json !== null;
+  if (hasBody) headers["Content-Type"] = "application/json";
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const resp = await fetch(url, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(json) : undefined,
+  });
+  const text = await resp.text();
+  let body = {};
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    body = { raw: text };
+  }
+  return {
+    status_code: resp.status,
+    ok: resp.ok,
+    ...body,
+  };
+}
+
+function assertOk(result, action) {
+  if (result.ok) return;
+  const detail = result.detail || result.message || result.raw || `${action} failed`;
+  throw new Error(`${action} failed: ${result.status_code} ${detail}`);
+}
+
+async function verifyUnconfirmedAccount(email) {
+  process.stdout.write("This email exists but is not verified. Sending a new OTP.\n");
+  const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
+  assertOk(resend, "resend OTP");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson("POST", "/auth/verify-otp", { json: { email, otp } });
+  assertOk(verified, "verify OTP");
+  return verified.access_token;
+}
+
+async function createAccountFromTerminal(email) {
+  const signup = await callBackendJson("POST", "/auth/start-signup", {
+    json: { email },
+  });
+
+  if (signup.ok) {
+    process.stdout.write("Verification code sent. Check your email.\n");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson("POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    return String(setPassword.access_token || "");
+  }
+
+  if (signup.status_code !== 404) {
+    assertOk(signup, "start signup");
+  }
+
+  process.stdout.write(
+    "This PreMan backend uses the password-first signup flow. Create your password now, then enter the email code.\n"
+  );
+  const password = await promptPasswordTwice();
+  const legacySignup = await callBackendJson("POST", "/auth/signup", {
+    json: { email, password },
+  });
+  assertOk(legacySignup, "signup");
+  process.stdout.write("Verification code sent. Check your email.\n");
+  const otp = await promptText("Verification code: ");
+  const verified = await callBackendJson("POST", "/auth/verify-otp", {
+    json: { email, otp },
+  });
+  assertOk(verified, "verify OTP");
+  return String(verified.access_token || "");
+}
+
+async function authenticateTerminal() {
+  const explicitKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
+  if (explicitKey && explicitKey.startsWith("pm_live_")) {
+    const creds = {
+      api_key: explicitKey,
+      backend_url: backendUrl(),
+      user_email: argValue("--email", ""),
+      device_name: os.hostname(),
+      created_at: new Date().toISOString(),
+    };
+    saveStoredCredentials(creds);
+    return creds;
+  }
+
+  const email = (argValue("--email", "") || await promptText("Email: ")).trim().toLowerCase();
+  if (!email) throw new Error("Email is required.");
+
+  process.stdout.write(`Checking PreMan account for ${email}...\n`);
+  const account = await callBackendJson("GET", "/auth/needs-password", { query: { email } });
+  assertOk(account, "check account");
+
+  let accessToken = "";
+
+  if (!account.exists) {
+    process.stdout.write("No PreMan account found. Creating one now.\n");
+    accessToken = await createAccountFromTerminal(email);
+  } else if (account.needs_password) {
+    process.stdout.write("This account needs a password. Sending an OTP first.\n");
+    const resend = await callBackendJson("POST", "/auth/resend-otp", { json: { email } });
+    assertOk(resend, "resend OTP");
+    const otp = await promptText("Verification code: ");
+    const password = await promptPasswordTwice();
+    const setPassword = await callBackendJson("POST", "/auth/set-password", {
+      json: { email, otp, new_password: password },
+    });
+    assertOk(setPassword, "set password");
+    accessToken = String(setPassword.access_token || "");
+  } else {
+    const password = await promptSecret("Password: ");
+    const login = await callBackendJson("POST", "/auth/login", {
+      json: { email, password },
+    });
+    if (!login.ok && login.status_code === 403 && String(login.detail || "").toLowerCase().includes("not verified")) {
+      accessToken = await verifyUnconfirmedAccount(email);
+    } else {
+      assertOk(login, "login");
+      accessToken = String(login.access_token || "");
+    }
+  }
+
+  if (!accessToken) throw new Error("PreMan did not return an access token.");
+
+  const keyName = `PreMan MCP CLI (${os.hostname()})`;
+  const key = await callBackendJson("POST", "/api-keys", {
+    token: accessToken,
+    json: { name: keyName },
+  });
+  assertOk(key, "create API key");
+  if (!key.key || !String(key.key).startsWith("pm_live_")) {
+    throw new Error("PreMan did not return a valid API key.");
+  }
+
+  const creds = {
+    api_key: String(key.key),
+    backend_url: backendUrl(),
+    user_email: email,
+    device_name: os.hostname(),
+    created_at: new Date().toISOString(),
+  };
+  saveStoredCredentials(creds);
+  return creds;
+}
+
 function buildServerConfig() {
-  const apiKey = argValue("--api-key", process.env.PREMAN_API_KEY || API_KEY_PLACEHOLDER);
+  const apiKey = argValue("--api-key", process.env.PREMAN_API_KEY || "");
   const backend = argValue("--backend", process.env.PREMAN_BACKEND || DEFAULT_BACKEND);
   const frontend = argValue("--frontend", process.env.PREMAN_FRONTEND || DEFAULT_FRONTEND);
+  const env = {
+    PREMAN_BACKEND: backend,
+    PREMAN_FRONTEND: frontend,
+  };
+  if (apiKey) {
+    env.PREMAN_API_KEY = apiKey;
+  }
 
   return {
-    command: "npx",
-    args: ["-y", "premanmcp"],
-    env: {
-      PREMAN_API_KEY: apiKey,
-      PREMAN_BACKEND: backend,
-      PREMAN_FRONTEND: frontend,
-    },
+    command: "npm",
+    args: ["exec", "-y", "--package", "premanmcp@latest", "--", "premanmcp"],
+    env,
   };
 }
 
-function installCursorMcp() {
+async function loginCommand() {
+  const creds = await authenticateTerminal();
+  process.stdout.write(`PreMan account ready.
+
+Email: ${creds.user_email || "unknown"}
+Backend: ${creds.backend_url}
+API key: ${creds.api_key}
+Saved to: ${CREDENTIALS_FILE}
+
+You can now run:
+  npm exec -y premanmcp@latest -- install
+`);
+}
+
+async function installCursorMcp() {
   const serverName = argValue("--name", "preman");
   const projectInstall = hasFlag("--project");
+
+  if (
+    !hasFlag("--print") &&
+    !hasFlag("--skip-login") &&
+    !argValue("--api-key", "") &&
+    !process.env.PREMAN_API_KEY &&
+    !readStoredCredentials()
+  ) {
+    process.stdout.write("First, let's create or connect your PreMan account.\n");
+    await authenticateTerminal();
+    process.stdout.write("\n");
+  }
+
   const serverConfig = buildServerConfig();
 
   if (hasFlag("--print")) {
@@ -115,16 +409,18 @@ function installCursorMcp() {
   mkdirSync(path.dirname(configPath), { recursive: true });
   writeFileSync(configPath, rendered, { mode: 0o600 });
 
-  const usedPlaceholder = config.mcpServers[serverName].env.PREMAN_API_KEY === API_KEY_PLACEHOLDER;
+  const hasInlineKey = Boolean(config.mcpServers[serverName].env.PREMAN_API_KEY);
+  const hasStoredKey = Boolean(readStoredCredentials());
   process.stdout.write(`PreMan MCP installed in ${configPath}
 
 Server name: ${serverName}
 Backend: ${config.mcpServers[serverName].env.PREMAN_BACKEND}
 
 Next steps:
-1. ${usedPlaceholder ? `Replace ${API_KEY_PLACEHOLDER} with your PreMan API key in ${configPath}. Find or create one at https://app.preman.live/settings/.` : "Your PreMan API key was written to the MCP config."}
+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 npm exec -y premanmcp@latest -- login to create/connect your account and generate an API key."}
 2. Restart Cursor or toggle the PreMan MCP server off/on.
-3. Ask your agent: "Use the PreMan MCP to convert my login endpoint into an MCP tool." Then open https://app.preman.live/ to see the session and generated MCP.
+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."
 `);
 }
 
@@ -155,14 +451,30 @@ function startServer() {
   });
 }
 
-if (command === "install") {
-  installCursorMcp();
-} else if (command === "help" || command === "--help" || command === "-h") {
-  printHelp();
-} else if (command === "start") {
-  startServer();
-} else {
-  process.stderr.write(`Unknown command: ${command}\n\n`);
-  printHelp();
-  process.exit(1);
+async function main() {
+  if (command === "login") {
+    await loginCommand();
+  } else if (command === "install") {
+    await installCursorMcp();
+  } else if (command === "link") {
+    await linkCommand(commandArgs);
+  } else if (command === "tools") {
+    await toolsCommand(commandArgs);
+  } else if (command === "run") {
+    await runCommand(commandArgs);
+  } else if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+  } else if (command === "start") {
+    startServer();
+  } else {
+    process.stderr.write(`Unknown command: ${command}\n\n`);
+    printHelp();
+    process.exit(1);
+  }
 }
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[preman] ${message}\n`);
+  process.exit(error?.exitCode || 1);
+});