premanmcp 0.5.0 → 0.7.1

package/README.md

@@ -7,7 +7,7 @@ PreMan is agent-first API infrastructure. It lets backend teams expose endpoints
 ## Connect
 
 ```bash
-npx premanmcp@latest connect
+npm exec -y premanmcp@latest -- connect
 ```
 
 Pick your coding agent from the list — Cursor, Claude Code, or Codex — and PreMan
@@ -29,8 +29,8 @@ agent actually reads (`~/.cursor/mcp.json`, Claude Code's MCP config, or
 {
   "mcpServers": {
     "preman": {
-      "command": "npx",
-      "args": ["-y", "premanmcp@latest"],
+      "command": "npm",
+      "args": ["exec", "-y", "premanmcp@latest", "--"],
       "env": {
         "PREMAN_BACKEND": "https://api.preman.live",
         "PREMAN_FRONTEND": "https://app.preman.live"
@@ -42,8 +42,21 @@ 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.
+
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
-project-local config, `--print` shows the config without writing it.
+project-local config, `--print` shows the config without writing it, `--no-guide` skips
+the guided first run.
+
+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
+setup blocks for all three agents and exits 2.
 
 `preman install` still exists and does the Cursor-only half of this.
 
@@ -63,13 +76,13 @@ npm exec -y premanmcp@latest -- login
 You can also pass the key directly:
 
 ```bash
-npx premanmcp@latest connect --api-key pm_live_xxx
+npm exec -y premanmcp@latest -- connect --api-key pm_live_xxx
 ```
 
 For project-local config:
 
 ```bash
-npx premanmcp@latest connect --project
+npm exec -y premanmcp@latest -- connect --project
 ```
 
 ## What It Does
@@ -82,6 +95,7 @@ npx premanmcp@latest connect --project
 - 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`).
+- Connects your production logs from the terminal (`connect_logs`): your agent asks where the logs live, then deploys a read-only CloudFormation role for AWS, or wires a shipper to the ingest endpoint for everything else.
 
 ## Common Agent Commands
 
@@ -111,10 +125,14 @@ Show me the audit log for this hosted MCP.
 Pull my pending PreMan fix tasks and fix the failing endpoint.
 ```
 
+```text
+Connect my production logs to PreMan.
+```
+
 ## Cursor
 
 ```bash
-npx premanmcp@latest connect --agent cursor
+npm exec -y premanmcp@latest -- connect --agent cursor
 ```
 
 Manual Cursor config, if you would rather write it yourself:
@@ -123,8 +141,8 @@ Manual Cursor config, if you would rather write it yourself:
 {
   "mcpServers": {
     "preman": {
-      "command": "npx",
-      "args": ["-y", "premanmcp@latest"]
+      "command": "npm",
+      "args": ["exec", "-y", "premanmcp@latest", "--"]
     }
   }
 }
@@ -133,19 +151,19 @@ Manual Cursor config, if you would rather write it yourself:
 ## Claude Code
 
 ```bash
-npx premanmcp@latest connect --agent claude-code
+npm exec -y premanmcp@latest -- connect --agent claude-code
 ```
 
 Equivalent manual command:
 
 ```bash
-claude mcp add preman -- npx -y premanmcp@latest
+claude mcp add preman -- npm exec -y premanmcp@latest --
 ```
 
 ## Codex
 
 ```bash
-npx premanmcp@latest connect --agent codex
+npm exec -y premanmcp@latest -- connect --agent codex
 ```
 
 Writes an `[mcp_servers.preman]` block into `~/.codex/config.toml`.
@@ -153,10 +171,10 @@ Writes an `[mcp_servers.preman]` block into `~/.codex/config.toml`.
 ## CLI
 
 ```bash
-npx premanmcp@latest connect            # Pick an agent and connect it
-npx premanmcp@latest connect --agent codex   # Skip the picker
-npx premanmcp@latest connect --project  # Write project-local config
-npx premanmcp@latest connect --print    # Print config without writing
+npm exec -y premanmcp@latest -- connect            # Pick an agent and connect it
+npm exec -y premanmcp@latest -- connect --agent codex   # Skip the picker
+npm exec -y premanmcp@latest -- connect --project  # Write project-local config
+npm exec -y premanmcp@latest -- connect --print    # Print config without writing
 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 # Cursor-only installer (legacy)

package/bin/api_tools.js

@@ -0,0 +1,215 @@
+/**
+ * `preman endpoints` and `preman test` — the API-testing surface of the CLI.
+ *
+ * Both are thin proxies over `POST /mcp/call-tool`, exactly like the MCP
+ * server's tools, so the CLI and an agent calling the same tool see identical
+ * behaviour. Requires a pm_live_ key (flag, env, or stored credentials).
+ */
+
+import { readFileSync } from "node:fs";
+
+import { callBackendJson, makeArgs, resolveApiKey } from "./shared.js";
+
+export const ENDPOINTS_HELP = `
+Endpoints:
+  preman endpoints list [--status s] [--method m] [--workbench] [--json-out]
+      List endpoints saved in PreMan (add --workbench for runnable requests).
+  preman endpoints discover [--framework hint]
+      Print the codebase-discovery brief for your coding agent to execute.
+  preman endpoints setup (--file endpoints.json | --ids id1,id2) [--base-url url] [--no-workbench]
+      Register discovered endpoints and set them up as runnable requests.
+`;
+
+export const TEST_HELP = `
+Testing:
+  preman test <request-or-endpoint-id> [options]
+      Generate scenario tests for one endpoint and run them.
+      --scenario "..."       Add a described scenario (repeatable)
+      --no-run               Generate only, don't execute
+      --allow-writes         Permit mutating cases / write endpoints
+      --code                 Emit unit-test files (prints filename + content)
+      --framework pytest|jest  Framework for --code (default pytest)
+      --stress               Run a bounded load test instead
+      --duration n --rps n --concurrency n   Stress parameters
+      --json-out             Print the raw JSON result
+`;
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+export async function callTool(args, tool, toolArguments) {
+  const token = resolveApiKey(args);
+  if (!token) {
+    throw new CliError(
+      "No PreMan API key. Run `preman login` or pass --api-key pm_live_...",
+      2,
+    );
+  }
+  const result = await callBackendJson(args, "POST", "/mcp/call-tool", {
+    json: { tool, arguments: toolArguments },
+    token,
+  });
+  if (!result.ok) {
+    const detail = result.detail || result.message || result.raw || "backend error";
+    throw new CliError(`${tool} failed: ${result.status_code} ${detail}`);
+  }
+  return result;
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function collectRepeated(commandArgs, flag) {
+  const out = [];
+  for (let i = 0; i < commandArgs.length; i += 1) {
+    if (commandArgs[i] === flag && commandArgs[i + 1]) out.push(commandArgs[i + 1]);
+  }
+  return out;
+}
+
+export async function endpointsCommand(commandArgs) {
+  const sub = commandArgs[0] && !commandArgs[0].startsWith("-") ? commandArgs[0] : "list";
+  const rest = sub === commandArgs[0] ? commandArgs.slice(1) : commandArgs;
+  const args = makeArgs(rest);
+
+  if (sub === "list") {
+    const toolArguments = {
+      status: args.value("--status", "") || undefined,
+      method: args.value("--method", "") || undefined,
+      include_workbench: args.has("--workbench"),
+      limit: Number(args.value("--limit", "50")),
+    };
+    const result = await callTool(args, "get_endpoints", toolArguments);
+    if (args.has("--json-out")) return printJson(result);
+    const rows = result.endpoints || [];
+    process.stdout.write(`${rows.length} registry endpoint(s)\n`);
+    for (const ep of rows) {
+      const status = ep.status ? ` [${ep.status}]` : "";
+      process.stdout.write(`  ${ep.method || "GET"} ${ep.path_template || ep.url || ""}${status} ${ep.id || ""}\n`);
+    }
+    const workbench = result.workbench_requests || [];
+    if (workbench.length) {
+      process.stdout.write(`${workbench.length} runnable workbench request(s)\n`);
+      for (const r of workbench) {
+        process.stdout.write(`  ${r.method} ${r.url} ${r.id}\n`);
+      }
+    }
+    return undefined;
+  }
+
+  if (sub === "discover") {
+    const result = await callTool(args, "discover_endpoints_from_codebase", {
+      base_path: args.value("--path", "."),
+      framework_hint: args.value("--framework", "") || undefined,
+    });
+    if (args.has("--json-out")) return printJson(result);
+    for (const line of result.instructions || []) process.stdout.write(`${line}\n`);
+    process.stdout.write(
+      "\nHand this brief to your coding agent, then run `preman endpoints setup --file endpoints.json`.\n",
+    );
+    return undefined;
+  }
+
+  if (sub === "setup") {
+    const file = args.value("--file", "");
+    const ids = args.value("--ids", "");
+    const toolArguments = {
+      base_url: args.value("--base-url", "") || undefined,
+      setup_workbench: !args.has("--no-workbench"),
+    };
+    if (file) {
+      let parsed;
+      try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        throw new CliError(`could not read ${file}: ${error.message}`, 2);
+      }
+      toolArguments.endpoints = Array.isArray(parsed) ? parsed : parsed.endpoints;
+    } else if (ids) {
+      toolArguments.endpoint_ids = ids.split(",").map((s) => s.trim()).filter(Boolean);
+    } else {
+      throw new CliError("pass --file endpoints.json or --ids id1,id2", 2);
+    }
+    const result = await callTool(args, "register_discovered_endpoints", toolArguments);
+    if (args.has("--json-out")) return printJson(result);
+    process.stdout.write(
+      `registered ${result.registered || 0} endpoint(s), skipped ${result.skipped || 0}\n`,
+    );
+    const requests = result.workbench_request_ids || [];
+    if (requests.length) {
+      process.stdout.write(`runnable as: ${requests.join(", ")}\n`);
+    }
+    return undefined;
+  }
+
+  throw new CliError(`unknown endpoints subcommand: ${sub}${ENDPOINTS_HELP}`, 2);
+}
+
+/** Print the scenario list and run outcome from generate_endpoint_tests. */
+export function printTestSummary(result) {
+  process.stdout.write(`${result.count || 0} scenario(s) for ${result.request_id}\n`);
+  for (const c of result.cases || []) {
+    process.stdout.write(`  - ${c.name} (${c.kind})\n`);
+  }
+  const run = result.run;
+  if (!run) return;
+  process.stdout.write(
+    `run ${run.status}: ${run.passed}/${run.total} passed, ${run.skipped} skipped` +
+    `${run.aborted_reason ? `, aborted: ${run.aborted_reason}` : ""}\n`,
+  );
+  for (const o of run.outcomes || []) {
+    if (o.status !== "passed") {
+      process.stdout.write(`  FAIL ${o.case_name}: ${o.response_status ?? o.error ?? ""}\n`);
+    }
+  }
+}
+
+export async function testCommand(commandArgs) {
+  const target = commandArgs[0] && !commandArgs[0].startsWith("-") ? commandArgs[0] : "";
+  const rest = target ? commandArgs.slice(1) : commandArgs;
+  const args = makeArgs(rest);
+  if (!target) {
+    throw new CliError(`pass a request or endpoint id${TEST_HELP}`, 2);
+  }
+
+  if (args.has("--stress")) {
+    const result = await callTool(args, "run_stress_test", {
+      target,
+      duration_seconds: Number(args.value("--duration", "15")),
+      rps: Number(args.value("--rps", "5")),
+      concurrency: Number(args.value("--concurrency", "5")),
+      allow_writes: args.has("--allow-writes"),
+    });
+    if (args.has("--json-out")) return printJson(result);
+    process.stdout.write(
+      `stress ${result.status}: ${result.total_requests} requests, ` +
+      `${Math.round((result.error_rate || 0) * 1000) / 10}% errors, ` +
+      `p50 ${result.p50_ms ?? "n/a"}ms p95 ${result.p95_ms ?? "n/a"}ms p99 ${result.p99_ms ?? "n/a"}ms, ` +
+      `${Math.round((result.throughput_rps || 0) * 10) / 10} rps\n`,
+    );
+    if (result.aborted_reason) process.stdout.write(`aborted: ${result.aborted_reason}\n`);
+    return undefined;
+  }
+
+  const result = await callTool(args, "generate_endpoint_tests", {
+    target,
+    scenarios: collectRepeated(rest, "--scenario"),
+    run: !args.has("--no-run"),
+    allow_writes: args.has("--allow-writes"),
+    max_cases: Number(args.value("--max-cases", "10")),
+    include_code: args.has("--code"),
+    test_framework: args.value("--framework", "pytest"),
+  });
+  if (args.has("--json-out")) return printJson(result);
+
+  printTestSummary(result);
+  for (const artifact of result.code_artifacts || []) {
+    process.stdout.write(`\n===== ${artifact.filename} =====\n${artifact.content}\n`);
+  }
+  return undefined;
+}

package/bin/cli.js

@@ -16,10 +16,19 @@ import os from "node:os";
 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 {
+  INTEGRATIONS_HELP,
+  awsCommand,
+  githubCommand,
+  onboardCommand,
+  slackCommand,
+} from "./integrations.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import {
   CREDENTIALS_FILE,
+  cliInvocation,
   DEFAULT_BACKEND,
   DEFAULT_FRONTEND,
   authenticateTerminal,
@@ -50,20 +59,38 @@ function hasFlag(name) {
 }
 
 function printHelp() {
+  // Say "preman x" only to people who can actually run it; everyone else gets
+  // the form that works from a bare npm install.
+  const cli = cliInvocation();
+  // Padded here rather than hand-aligned: the invocation prefix is 6 characters
+  // for a global install and 38 for npm exec, so a fixed layout is wrong for
+  // one of them.
+  const usage = [
+    ["onboard", "Sign in, then connect agent, GitHub, AWS, Slack"],
+    ["connect [options]", "Pick a coding agent and connect it"],
+    ["aws | github | slack", "Connect one integration on its own"],
+    ["login", "Create/login to PreMan from the terminal"],
+    ["install [options]", "Install PreMan into Cursor MCP config"],
+    ["", "Start the PreMan MCP server"],
+    ["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"],
+  ];
+  const width = Math.max(...usage.map(([command]) => `${cli} ${command}`.trimEnd().length));
+  const usageLines = usage
+    .map(([command, blurb]) => `  ${`${cli} ${command}`.trimEnd().padEnd(width)}  ${blurb}`)
+    .join("\n");
+
   process.stdout.write(`PreMan MCP
 
 Usage:
-  preman connect [options]                           Pick a coding agent and connect it
-  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
-${CONNECT_HELP}
+${usageLines}
+${INTEGRATIONS_HELP}${CONNECT_HELP}${ENDPOINTS_HELP}${TEST_HELP}
 Login options:
   --email <email>       Pre-fill the email prompt
   --backend <url>       PreMan backend URL. Defaults to ${DEFAULT_BACKEND}
 
-Install options (Cursor only — prefer 'preman connect'):
+Install options (Cursor only — prefer '${cli} connect'):
   --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}
@@ -74,9 +101,9 @@ Install options (Cursor only — prefer 'preman connect'):
   --print               Print the config instead of writing it
 
 Examples:
-  npx premanmcp@latest connect
-  preman connect --agent claude-code
-  npm exec -y premanmcp@latest -- login
+  npm exec -y premanmcp@latest -- connect
+  ${cli} connect --agent claude-code
+  ${cli} login
   npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
 ${HOSTED_HELP}`);
 }
@@ -91,7 +118,7 @@ API key: ${creds.api_key}
 Saved to: ${CREDENTIALS_FILE}
 
 You can now run:
-  preman connect
+  ${cli} connect
 `);
 }
 
@@ -126,12 +153,12 @@ 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 npm exec -y premanmcp@latest -- 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."
 
-Tip: 'preman connect' also supports Claude Code and Codex, and links the agent to your account.
+Tip: '${cli} connect' also supports Claude Code and Codex, and links the agent to your account.
 `);
 }
 
@@ -167,6 +194,16 @@ async function main() {
     await loginCommand();
   } else if (command === "connect") {
     await connectCommand(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.
+    await onboardCommand(commandArgs, { makeArgs, authenticateTerminal, connectCommand });
+  } else if (command === "aws") {
+    await awsCommand(makeArgs(commandArgs));
+  } else if (command === "github") {
+    await githubCommand(makeArgs(commandArgs));
+  } else if (command === "slack") {
+    await slackCommand(makeArgs(commandArgs));
   } else if (command === "install") {
     await installCursorMcp();
   } else if (command === "link") {
@@ -175,6 +212,10 @@ async function main() {
     await toolsCommand(commandArgs);
   } else if (command === "run") {
     await runCommand(commandArgs);
+  } else if (command === "endpoints") {
+    await endpointsCommand(commandArgs);
+  } else if (command === "test") {
+    await testCommand(commandArgs);
   } else if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
   } else if (command === "start") {