premanmcp 0.11.0 → 0.12.0

package/README.md

@@ -4,14 +4,24 @@ Turn your APIs into MCP tools that coding agents can discover, call, test, and a
 
 PreMan is agent-first API infrastructure. It lets backend teams expose endpoints to AI coding agents through MCP, add an auth layer around those tools, and see exactly which agent called what.
 
-## Connect
+## Start
+
+```bash
+npm exec -y premanmcp@latest -- onboard
+```
+
+Create the account, verify the email, and get the PreMan app installed and opened
+already signed in. A bare `preman` in a terminal does the same thing.
+
+## Connect a coding agent
 
 ```bash
 npm exec -y premanmcp@latest -- connect
 ```
 
-Pick your coding agent from the list — Cursor, Claude Code, or Codex — and PreMan
-writes that agent's MCP config for you. No hand-edited config anywhere.
+Optional, and separate from starting out. Pick your coding agent from the list — Cursor,
+Claude Code, or Codex — and PreMan writes that agent's MCP config for you. No hand-edited
+config anywhere.
 
 Local development form:
 
@@ -82,10 +92,18 @@ 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.
+`preman onboard` (or `setup`, or a bare `preman` in a terminal) is what someone starting
+out runs: create the account and verify the email, then install the PreMan app and open it
+already signed in, then GitHub, AWS, Slack — one question per step, `b` to go back, and a
+summary at the end. Connecting a coding agent is no longer part of starting out; run
+`preman connect` when you actually want one wired into an IDE. `connect --guide` still runs
+the full pass inside connect itself: discovery, a first test, the runner, the desktop app
+and the integration prompts.
+
+The app opens signed in because the CLI leaves the key it just minted in
+`~/.preman/desktop-session.json`, which the app reads once and deletes. An app too old to
+look for it, or a machine that is not macOS, falls back to signing in on the app's own
+login screen with the account you just created.
 
 Useful flags: `--agent cursor|claude-code|codex` skips the picker, `--project` writes
 project-local config, `--print` shows the config without writing it, `--no-hook` leaves

package/bin/cli.js

@@ -22,7 +22,6 @@ import {
   CONNECT_HELP,
   DISPATCH_HELP,
   connectCommand,
-  discoverEndpoints,
   dispatchCommand,
   resolveAgentForPairing,
   writeCursorConfig,
@@ -39,7 +38,7 @@ import { STATUS_HELP, statusCommand } from "./status.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";
+import { DESKTOP_HELP, installDesktopCommand, openDesktopSignedIn } from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
 import {
   CREDENTIALS_FILE,
@@ -57,8 +56,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.join(__dirname, "..");
 
 const args = process.argv.slice(2);
+// A bare `preman` in a terminal is someone starting out, so it runs setup:
+// account first, then the app. Piped or redirected (no TTY) it is an MCP host
+// launching the server, which must stay the behaviour for `start`.
 const command = args.length === 0 && process.stdin.isTTY
-  ? "connect"
+  ? "onboard"
   : args[0] === "--help" || args[0] === "-h"
   ? "help"
   : args[0] && !args[0].startsWith("-")
@@ -89,8 +91,8 @@ 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 agent, endpoints, runner, GitHub, AWS, Slack"],
-    ["connect [options]", "Pick a coding agent and connect it"],
+    ["onboard", "Create an account, install the app signed in, then integrations"],
+    ["connect [options]", "Pick a coding agent and connect it (optional)"],
     ["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"],
@@ -254,14 +256,13 @@ async function main() {
   } else if (command === "dispatch") {
     await dispatchCommand(commandArgs);
   } else if (command === "onboard" || command === "setup") {
-    // makeArgs/authenticateTerminal/connectCommand are injected rather than
+    // makeArgs/authenticateTerminal/the desktop pair are injected rather than
     // imported there, so integrations.js stays free of a cycle back into the CLI.
     await onboardCommand(commandArgs, {
       makeArgs,
       authenticateTerminal,
-      connectCommand,
-      discoverEndpoints,
-      runnerCommand,
+      installDesktop: installDesktopCommand,
+      openDesktopSignedIn,
     });
   } else if (command === "aws") {
     await awsCommand(makeArgs(commandArgs));

package/bin/desktop.js

@@ -13,11 +13,11 @@
 
 import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { cliInvocation, makeArgs } from "./shared.js";
+import { CREDENTIALS_DIR, cliInvocation, makeArgs } from "./shared.js";
 
 export const DESKTOP_HELP = `
 Install-desktop options:
@@ -32,6 +32,60 @@ const RELEASE_API = "https://api.github.com/repos/PreMan-Inc/PreMan-Desktop/rele
 export const APP_NAME = "PreMan.app";
 const DOWNLOAD_TIMEOUT_MS = 300_000;
 
+/**
+ * Where the desktop app looks for a session the CLI just established.
+ *
+ * The key travels through a file rather than the `preman://` URL because a URL
+ * is handed to LaunchServices, which records it; the file sits in the directory
+ * that already holds the same key, with the same 0600 mode, so this adds no new
+ * class of exposure. The app deletes it on read, which is what makes it
+ * single-use -- the CLI cannot know whether an installed app is new enough to
+ * consume it, so expiry is enforced on the reading side.
+ */
+export const DESKTOP_SESSION_FILE = path.join(CREDENTIALS_DIR, "desktop-session.json");
+
+export function installedAppPath(destination = "/Applications") {
+  return path.join(destination, APP_NAME);
+}
+
+export function desktopAppInstalled(destination = "/Applications") {
+  return process.platform === "darwin" && existsSync(installedAppPath(destination));
+}
+
+/**
+ * Hand the account the CLI just signed in to over to the desktop app.
+ *
+ * Returns what actually happened rather than a boolean, because the caller has
+ * something different to say in each case: an app that is not installed is not
+ * a failure, it is the fallback where the customer signs in themselves.
+ */
+export function writeDesktopSession(creds) {
+  const apiKey = String(creds?.api_key || "").trim();
+  if (!apiKey.startsWith("pm_live_")) return { state: "no-key" };
+  mkdirSync(CREDENTIALS_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(
+    DESKTOP_SESSION_FILE,
+    `${JSON.stringify({ api_key: apiKey, user_email: creds?.user_email ?? null, created_at: new Date().toISOString() }, null, 2)}\n`,
+    { mode: 0o600 }
+  );
+  return { state: "written", path: DESKTOP_SESSION_FILE };
+}
+
+/**
+ * Install-or-not aside, get the customer into the app signed in.
+ *
+ * The session is written before the app is launched so a cold start finds it on
+ * first read, rather than racing a window that is already loading.
+ */
+export function openDesktopSignedIn(creds, { destination = "/Applications" } = {}) {
+  if (!desktopAppInstalled(destination)) {
+    return { state: "not-installed" };
+  }
+  const handoff = writeDesktopSession(creds);
+  spawn("open", ["-a", "PreMan"], { stdio: "ignore", detached: true }).unref();
+  return { state: handoff.state === "written" ? "opened-signed-in" : "opened", handoff: handoff.state };
+}
+
 /**
  * Open a Playground session URL in PreMan.app on macOS when it is installed.
  * Windows/Linux (and Mac without the app) get the website URL printed instead.
@@ -225,8 +279,8 @@ export async function installDesktopCommand(commandArgs = []) {
     chmodSync(target, 0o755);
 
     process.stdout.write(
-      `\nInstalled ${target}\n\nNext: open PreMan and it will pair with this account.\n` +
-        `Then run \`${cliInvocation()} status\` to see endpoint health.\n`
+      `\nInstalled ${target}\n\nNext: open PreMan and sign in with the account you use here.\n` +
+        `\`${cliInvocation()} onboard\` installs it and opens it already signed in.\n`
     );
     return { state: "installed", version, arch, path: target };
   } finally {

package/bin/integrations.js

@@ -337,17 +337,6 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
-/**
- * Why a step that needs a connected agent cannot run on its own.
- *
- * Both of these drive the agent `connect` just linked, so skipping that step
- * leaves them without one -- which is a thing to say plainly, with the command
- * that does it later, rather than a stack trace about a missing id.
- */
-function needsAgent(command) {
-  return `no coding agent connected yet -- run '${cliInvocation()} connect', then '${cliInvocation()} ${command}'`;
-}
-
 /** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
 async function askStep(question, { assumeYes, canGoBack }) {
   if (assumeYes) return "yes";
@@ -368,7 +357,7 @@ async function askStep(question, { assumeYes, canGoBack }) {
  */
 export async function onboardCommand(
   commandArgs,
-  { makeArgs, authenticateTerminal, connectCommand, discoverEndpoints, runnerCommand }
+  { makeArgs, authenticateTerminal, installDesktop, openDesktopSignedIn }
 ) {
   const args = makeArgs(commandArgs);
   const assumeYes = args.has("--yes");
@@ -378,32 +367,30 @@ export async function onboardCommand(
   const creds = await authenticateTerminal(args);
   connected(`Signed in as ${creds.user_email || "your account"}.`);
 
-  // Which agent the endpoints and runner steps drive. `connect` decided it, by
-  // detection or by asking, and this is the answer rather than a second prompt.
-  let linked = null;
-
   const steps = [
     {
-      name: "coding agent",
-      question: "Connect your coding agent?",
+      name: "PreMan app",
+      question: "Install the PreMan app and open it signed in?",
       run: async () => {
-        linked = (await connectCommand([...commandArgs, "--skip-login"])) || null;
-      },
-    },
-    {
-      name: "endpoints",
-      question: "Map this repository's endpoints?",
-      run: () => {
-        if (!linked?.agent) throw new Error(needsAgent("endpoints discover"));
-        return discoverEndpoints(args, linked.agent, linked.serverName);
-      },
-    },
-    {
-      name: "runner",
-      question: "Let PreMan run your agent here when it finds something to fix?",
-      run: () => {
-        if (!linked?.agent) throw new Error(needsAgent("runner start --background"));
-        return runnerCommand(["start", "--background", "--agent", linked.agent.id]);
+        const installed = await installDesktop([...commandArgs]);
+        if (installed?.state === "unsupported") {
+          // Not a failure: the download link has already been printed, and the
+          // account this step exists to create is finished either way.
+          process.stdout.write("Sign in there with the account you just used.\n");
+          return;
+        }
+        const opened = openDesktopSignedIn(creds);
+        if (opened.state === "opened-signed-in") {
+          process.stdout.write("Opened PreMan, signed in as this account.\n");
+        } else if (opened.state === "not-installed") {
+          process.stdout.write(
+            "PreMan is not in /Applications yet \u2014 open it once installed and sign in.\n"
+          );
+        } else {
+          // The app is there but the session could not be handed over, so say so
+          // rather than let the customer wonder why they are at a login screen.
+          process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
+        }
       },
     },
     { name: "GitHub", question: "Connect GitHub?", run: () => githubCommand(args) },
@@ -464,8 +451,9 @@ export async function onboardCommand(
 
 export const INTEGRATIONS_HELP = `
 Setup options:
-  preman onboard              Sign in, then agent, endpoints, runner, GitHub,
-                              AWS and Slack, one prompt per step
+  preman onboard              Create or sign in to an account, install the
+                              PreMan app signed in, then GitHub, AWS and Slack,
+                              one prompt per step
   preman aws                  Connect an AWS account and stream a log group
   preman github               Install the PreMan GitHub App
   preman slack                Add PreMan to a Slack workspace

package/dist/server.js

@@ -1332,6 +1332,90 @@ export function createServer() {
             });
         }
     });
+    // ── Collections test generation ────────────────────────────────────
+    // The dashboard's Generate Tests / Review flagged / Setup fixtures /
+    // Enrich with agent buttons, so an agent can run them without clicking.
+    server.tool("generate_saved_tests", "Generate scheduled test suites for every endpoint already saved in a PreMan workspace. This is the dashboard's Collections 'Generate Tests' button: it clones the workspace's connected GitHub repository, matches the discovered routes onto the saved endpoints by method and path, and writes heuristic cases onto the ones it matches. No model is involved, so nothing invents a body for a DELETE. Write, destructive, low-confidence, and path-parameter routes come back flagged and disabled — clear them with review_generated_tests. This is not generate_tests, which writes cases for a single endpoint you describe.", {
+        action: z
+            .enum(["generate", "status"])
+            .optional()
+            .describe("generate (default) runs the scan; status is read-only counts"),
+        integration_id: z
+            .string()
+            .optional()
+            .describe("Connected repo to scan. Omit to use the one with the most synced endpoints."),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("generate_saved_tests", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: [
+                    "Connect a GitHub repository to this workspace in Settings → Integrations, then retry.",
+                ],
+                related_tools: ["review_generated_tests", "setup_test_fixtures", "enrich_generated_tests"],
+            });
+        }
+    });
+    server.tool("review_generated_tests", "List and approve the generated test suites PreMan flagged for human review. This is the dashboard's 'Review flagged' button. generate_saved_tests deliberately leaves mutating and ambiguous routes disabled; this is how a reviewed suite gets turned on. Approving enables the suite's read-only schedule and does not raise the unattended write policy, so a DELETE stays gated at run time. List first and show the user each suite and its reason; only use approve_all when they asked to clear the whole queue.", {
+        action: z
+            .enum(["list", "approve", "approve_all"])
+            .optional()
+            .describe("list (default) | approve one request_id | approve_all (max 50)"),
+        request_id: z.string().optional().describe("Saved request to approve; required for approve"),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("review_generated_tests", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Call review_generated_tests with action='list' to see the queue."],
+                related_tools: ["generate_saved_tests", "enrich_generated_tests"],
+            });
+        }
+    });
+    server.tool("setup_test_fixtures", "Fill the {id} path parameters in saved PreMan endpoints with real record ids. This is the dashboard's 'Setup fixtures' button: a happy-path test for GET /users/{id} needs an id that exists, so PreMan calls the sibling list route read-only, harvests ids from the response, and falls back to the endpoint's schema example. It never mints a fake UUID that would only 404 and never fires a write. Harvested values are stored in workspace settings and returned as a .env snippet. This does not approve anything.", {
+        action: z
+            .enum(["setup", "list"])
+            .optional()
+            .describe("setup (default) harvests ids; list reports what is still missing"),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("setup_test_fixtures", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: ["Save at least one endpoint with a {id} path parameter, then retry."],
+                related_tools: ["generate_saved_tests", "review_generated_tests"],
+            });
+        }
+    });
+    server.tool("enrich_generated_tests", "Add model-written test cases on top of PreMan's heuristic suites. This is the dashboard's 'Enrich with agent' button. generate_saved_tests writes deterministic cases only; this pass asks a model for a few extra edge cases per suite. It touches review-cleared suites only, skips destructive and billing-sensitive requests unless workspace policy already allows that risk, skips suites already enriched, and stops after 40 suites per call so a large collection cannot fan out into hundreds of model calls. Leftovers come back as remaining.", {
+        action: z
+            .enum(["enrich", "list"])
+            .optional()
+            .describe("enrich (default) runs the pass; list returns the eligible suites"),
+        workspace_id: z.string().optional().describe("Defaults to the caller's own workspace"),
+    }, async (args) => {
+        try {
+            const result = await callBackend("enrich_generated_tests", args);
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return toolError(e.message, inferErrorCode(e.message), {
+                next_actions: [
+                    "Run generate_saved_tests first, then clear the review queue with review_generated_tests.",
+                ],
+                related_tools: ["generate_saved_tests", "review_generated_tests"],
+            });
+        }
+    });
     server.tool("share_endpoints_with_ui", "Push discovered or verified endpoints into the PreMan Playground so the user can see them, test them, and convert selected endpoints into hosted MCP tools. Use this after verify_endpoints_live or when the user explicitly asks to stream endpoints to the UI.", {
         endpoints: z.array(z.any()).describe("Endpoints to push. Each item should include method plus path/path_template/url; include schemas when available."),
         upstream_base_url: z.string().optional().describe("Default upstream base URL for testing and MCP generation, e.g. http://127.0.0.1:8000 or https://api.example.com"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "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=90000 scripts/smoke-account.mjs scripts/smoke-cli-entrypoint.mjs 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-tests-workbench.mjs scripts/smoke-bin-scope.mjs"
+    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-cli-entrypoint.mjs 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-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^0.1.0",