premanmcp 0.7.0 → 0.7.1

package/bin/cli.js

@@ -28,6 +28,7 @@ import {
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import {
   CREDENTIALS_FILE,
+  cliInvocation,
   DEFAULT_BACKEND,
   DEFAULT_FRONTEND,
   authenticateTerminal,
@@ -58,24 +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 onboard                                     Sign in, then connect agent, GitHub, AWS, Slack
-  preman connect [options]                           Pick a coding agent and connect it
-  preman aws | github | slack                        Connect one integration on its own
-  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
-  preman endpoints list|discover|setup ...           Discover, list, and set up API endpoints
-  preman test <id> [--scenario ...] [--stress]       Generate + run tests for an endpoint
+${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}
@@ -87,8 +102,8 @@ Install options (Cursor only — prefer 'preman connect'):
 
 Examples:
   npm exec -y premanmcp@latest -- connect
-  preman connect --agent claude-code
-  npm exec -y premanmcp@latest -- login
+  ${cli} connect --agent claude-code
+  ${cli} login
   npm exec -y premanmcp@latest -- install --project --backend http://127.0.0.1:8000
 ${HOSTED_HELP}`);
 }
@@ -103,7 +118,7 @@ API key: ${creds.api_key}
 Saved to: ${CREDENTIALS_FILE}
 
 You can now run:
-  preman connect
+  ${cli} connect
 `);
 }
 
@@ -138,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.
 `);
 }
 

package/bin/connect.js

@@ -22,6 +22,7 @@ import {
   backendUrl,
   buildServerConfig,
   callBackendJson,
+  cliInvocation,
   frontendUrl,
   hasKeyAvailable,
   makeArgs,
@@ -401,11 +402,21 @@ async function captureDispatchCredential(args, agent, apiKey) {
 
   if (!secret) {
     if (!process.stdin.isTTY) return;
+    // Framed as the expected step rather than an optional aside. Without it
+    // PreMan can only suggest fixes; with it, it can run them. Presenting it as
+    // "optional, press Enter to skip" meant almost everyone skipped the thing
+    // that makes the product act rather than advise.
     process.stdout.write(
-      `\nOptional: paste a ${agent.dispatch.credential} so PreMan can start ${agent.label} runs for you.\n`
+      `\nLet PreMan start ${agent.label} runs for you — it can then apply fixes and\n` +
+        `run checks on a schedule instead of only telling you what to do.\n`
     );
-    secret = await promptSecret("(Enter to skip): ");
-    if (!secret) return;
+    secret = await promptSecret(`Paste your ${agent.dispatch.credential} (Enter to set up later): `);
+    if (!secret) {
+      process.stdout.write(
+        `Skipped. Run '${cliInvocation()} connect --agent ${agent.id.replace("_", "-")}' when you have the token.\n`
+      );
+      return;
+    }
     if (agent.dispatch.needsRoutine && !routineId) {
       routineId = await promptText("Routine id or URL: ");
     }

package/bin/integrations.js

@@ -224,8 +224,13 @@ export async function awsCommand(args) {
 export async function githubCommand(args) {
   const token = requireKey(args);
 
-  const before = await callBackendJson(args, "GET", "/integrations/github", { token });
-  const seen = new Set((before.integrations || before.repos || []).map((r) => r.id));
+  // This route answers with a bare array; callBackendJson exposes it as `list`.
+  const listRepos = async () => {
+    const resp = await callBackendJson(args, "GET", "/integrations/github", { token });
+    return resp.list || resp.integrations || resp.repos || [];
+  };
+
+  const seen = new Set((await listRepos()).map((r) => r.id));
 
   const started = await callBackendJson(args, "POST", "/integrations/github/app/install", {
     token,
@@ -239,11 +244,17 @@ export async function githubCommand(args) {
   process.stdout.write("Pick the repositories PreMan may read.\n");
 
   const done = await waitFor("the installation", async () => {
-    const now = await callBackendJson(args, "GET", "/integrations/github", { token });
-    const rows = now.integrations || now.repos || [];
+    // Installing the App and having repositories appear are two events: the
+    // callback records the installation, and a refresh materialises the repos.
+    // Polling the repo list alone waits for something that may never arrive on
+    // its own.
+    await callBackendJson(args, "POST", "/integrations/github/app/refresh", {
+      token,
+      json: {},
+    });
     // Compare against what existed before, so a user who already had repos
     // connected is not told they are done the moment polling starts.
-    const fresh = rows.filter((r) => !seen.has(r.id));
+    const fresh = (await listRepos()).filter((r) => !seen.has(r.id));
     return fresh.length ? fresh : null;
   });
 
@@ -289,10 +300,14 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
-async function askYes(question, { assumeYes }) {
-  if (assumeYes) return true;
-  const answer = (await promptText(`${question} [Y/n]: `)).trim().toLowerCase();
-  return answer === "" || answer === "y" || answer === "yes";
+/** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
+async function askStep(question, { assumeYes, canGoBack }) {
+  if (assumeYes) return "yes";
+  const hint = canGoBack ? "[Y/n/b]" : "[Y/n]";
+  const answer = (await promptText(`${question} ${hint}: `)).trim().toLowerCase();
+  if (canGoBack && (answer === "b" || answer === "back")) return "back";
+  if (answer === "" || answer === "y" || answer === "yes") return "yes";
+  return "no";
 }
 
 /**
@@ -323,32 +338,54 @@ export async function onboardCommand(commandArgs, { makeArgs, authenticateTermin
     { name: "Slack", question: "Connect Slack?", run: () => slackCommand(args) },
   ];
 
-  const done = [];
-  const skipped = [];
-  const failed = [];
-
-  for (const step of steps) {
+  // Outcome per step rather than three lists, so revisiting a step replaces its
+  // result instead of recording it twice.
+  const outcome = new Map();
+
+  // Indexed rather than for..of so "back" can move the cursor. Re-running a
+  // step is safe: every one of these is idempotent on the backend -- an AWS
+  // grant returns the existing link, and an App install that already happened
+  // is detected rather than duplicated.
+  let i = 0;
+  while (i < steps.length) {
+    const step = steps[i];
     process.stdout.write(`\n── ${step.name} ──\n`);
-    if (!(await askYes(step.question, { assumeYes }))) {
-      skipped.push(step.name);
+
+    const choice = await askStep(step.question, { assumeYes, canGoBack: i > 0 });
+    if (choice === "back") {
+      // Drop the result we are about to redo, or the summary would report the
+      // stale outcome of a step the customer chose to revisit.
+      outcome.delete(steps[i - 1].name);
+      i -= 1;
       continue;
     }
+    if (choice === "no") {
+      outcome.set(step.name, { state: "skipped" });
+      i += 1;
+      continue;
+    }
+
     try {
       await step.run();
-      done.push(step.name);
+      outcome.set(step.name, { state: "done" });
     } catch (err) {
       // Report and carry on: a failed Slack install must not cost the customer
       // the AWS connection they just finished.
-      failed.push(`${step.name}: ${err.message}`);
+      outcome.set(step.name, { state: "failed", detail: err.message });
       process.stdout.write(`Could not finish ${step.name}: ${err.message}\n`);
     }
+    i += 1;
   }
 
   process.stdout.write("\n── done ──\n");
   // One line per step, marked, so the outcome is scannable rather than prose.
-  for (const name of done) process.stdout.write(`${MARK.ok()} ${name}\n`);
-  for (const name of skipped) process.stdout.write(`${MARK.skip()} ${name} (skipped)\n`);
-  for (const failure of failed) process.stdout.write(`${MARK.fail()} ${failure}\n`);
+  for (const step of steps) {
+    const result = outcome.get(step.name);
+    if (!result) continue;
+    if (result.state === "done") process.stdout.write(`${MARK.ok()} ${step.name}\n`);
+    else if (result.state === "skipped") process.stdout.write(`${MARK.skip()} ${step.name} (skipped)\n`);
+    else process.stdout.write(`${MARK.fail()} ${step.name}: ${result.detail}\n`);
+  }
   process.stdout.write(`\nOpen ${frontendUrl(args)} to see your logs and endpoints.\n`);
 }
 
@@ -360,6 +397,7 @@ Setup options:
   preman slack                Add PreMan to a Slack workspace
 
   --yes                       Accept every step without prompting (onboard)
+  b at any onboard prompt     Go back to the previous step
   --account <id>              AWS account id, skips the prompt
   --region <region>           AWS region for log groups. Defaults to us-east-1
   --project-id <id>           PreMan project to attach the log connector to

package/bin/shared.js

@@ -7,6 +7,7 @@
  * over a module-level argv, so a command can pass its own slice.
  */
 
+import { spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -18,6 +19,28 @@ export const CREDENTIALS_DIR = path.join(os.homedir(), ".preman");
 export const CREDENTIALS_FILE = path.join(CREDENTIALS_DIR, "credentials.json");
 
 /** Wrap a raw argv slice in the positional lookup the CLI has always used. */
+/**
+ * How to tell this user to invoke us.
+ *
+ * The help used to say "preman connect" unconditionally, which is only true
+ * after a global install. Anyone reading it straight out of
+ * `npm exec premanmcp -- --help` -- the way the docs tell them to run it --
+ * copied a command that answers "command not found".
+ */
+let _invocation = null;
+
+export function cliInvocation() {
+  if (_invocation) return _invocation;
+  const probe = process.platform === "win32" ? "where" : "which";
+  try {
+    const found = spawnSync(probe, ["preman"], { stdio: "pipe", encoding: "utf8" });
+    _invocation = found.status === 0 && found.stdout.trim() ? "preman" : null;
+  } catch {
+    _invocation = null;
+  }
+  return (_invocation ||= "npm exec -y premanmcp@latest --");
+}
+
 export function makeArgs(commandArgs = []) {
   return {
     raw: commandArgs,
@@ -173,6 +196,12 @@ export async function callBackendJson(args, method, routePath, { json, token, qu
   } catch {
     body = { raw: text };
   }
+  // Some routes answer with a bare array. Spreading one into this object turns
+  // it into {0:…,1:…} and quietly loses the list, so it gets its own key.
+  if (Array.isArray(body)) {
+    return { status_code: resp.status, ok: resp.ok, list: body };
+  }
+
   return {
     status_code: resp.status,
     ok: resp.ok,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {