premanmcp 0.13.0 → 0.15.0

package/README.md

@@ -10,8 +10,9 @@ PreMan is agent-first API infrastructure. It lets backend teams expose endpoints
 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.
+Create the account, verify the email, get the PreMan app installed and opened already
+signed in, and hook this repo so `git push` checks the endpoints you touched. A bare
+`preman` in a terminal does the same thing.
 
 ## Connect a coding agent
 
@@ -93,9 +94,11 @@ preman status                      # which of those are done
 ```
 
 `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
+out runs: create the account and verify the email, install the PreMan app and open it
+already signed in, then write the pre-push hook into this repo — one question per step, `b`
+to go back, and a summary at the end. GitHub, AWS and Slack are their own commands now.
+Onboarding outside a git repository skips the hook rather than failing; run `preman hook
+install` in the repo you meant. 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.
@@ -257,7 +260,7 @@ npm exec -y premanmcp@latest -- install # Cursor-only installer (legacy)
 ### Push testing
 
 ```bash
-preman hook install         # Write the pre-push hook (connect does this too)
+preman hook install         # Write the pre-push hook (onboard and connect do this too)
 preman hook status          # Installed? And does the command in it still answer?
 preman hook repair          # Rewrite it if it stopped working (usually automatic)
 preman hook uninstall       # Remove it, restoring any hook it replaced
@@ -280,6 +283,39 @@ hook we did not write is never touched, and no hook is installed where you never
 one. The answer is remembered for an hour per directory, and `PREMAN_NO_HOOK_REPAIR=1` turns
 it off.
 
+#### The link a push leaves behind
+
+Once runs are stored, the hook prints a line you can click straight through to that push:
+
+```
+◆ PreMan · check #a3f21c passed — view results
+  https://app.preman.live/observability/endpoints?batch=a3f21c9e-…
+```
+
+Where the click lands is decided before anything is printed, because a terminal hands the
+URL it was given to the OS and there is nothing left of the hook by then:
+
+| What is true when the hook runs | What the link opens |
+| --- | --- |
+| A frontend other than `app.preman.live` | That frontend, in the browser |
+| PreMan.app installed and new enough to route | The desktop app, via `preman://` |
+| Anything else | `app.preman.live`, in the browser |
+
+The frontend is read from `--frontend`, then `PREMAN_FRONTEND`, then the one saved at login
+in `~/.preman/credentials.json`. That last fallback is what makes a local setup work from a
+hook at all: `git push` does not carry the shell that exported the variable, and a `dev.env`
+file is not an environment.
+
+The bare URL is always printed underneath, because macOS Terminal.app renders no hyperlink.
+Piped output — a GUI git client, CI — gets the plain line with no escapes at all, and
+`NO_COLOR` drops the colour but keeps the link.
+
+Desktop builds from `MIN_ROUTE_VERSION` in `bin/link.js` onward are expected to read
+`preman://open?source=push&route=<url-encoded path>` and navigate to that path. Older builds
+raise the window and ignore the query, so the CLI reads `CFBundleShortVersionString` out of
+the installed bundle and falls back to https rather than sending them somewhere they cannot
+follow.
+
 ### Runner
 
 `preman onboard` and `connect --guide` set this up for you; these are for managing it

package/bin/account.js

@@ -11,6 +11,7 @@ import { existsSync, rmSync } from "node:fs";
 import os from "node:os";
 
 import { detectCandidates } from "./detect.js";
+import { DESKTOP_SESSION_FILE } from "./desktop.js";
 import { hookStatus } from "./hook.js";
 import {
   CREDENTIALS_FILE,
@@ -90,6 +91,10 @@ export async function logoutCommand() {
   } else {
     process.stdout.write("No stored credentials to remove.\n");
   }
+  if (existsSync(DESKTOP_SESSION_FILE)) {
+    rmSync(DESKTOP_SESSION_FILE, { force: true });
+    process.stdout.write(`Removed ${DESKTOP_SESSION_FILE}\n`);
+  }
   process.stdout.write(
     "Note: this does not revoke the API key. Revoke it in the dashboard if the machine is shared.\n"
   );

package/bin/cli.js

@@ -35,7 +35,7 @@ import {
 } from "./integrations.js";
 import { HOSTED_HELP, linkCommand, runCommand, toolsCommand } from "./hosted.js";
 import { STATUS_HELP, statusCommand } from "./status.js";
-import { HOOK_HELP, hookCommand, scheduleHookRepair } from "./hook.js";
+import { HOOK_HELP, hookCommand, installHook, scheduleHookRepair } from "./hook.js";
 import { RUNNER_HELP, runnerCommand } from "./runner.js";
 import { VERIFY_HELP, verifyCommand } from "./verify.js";
 import { DESKTOP_HELP, installDesktopCommand, openDesktopSignedIn } from "./desktop.js";
@@ -91,7 +91,7 @@ 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", "Create an account, install the app signed in, then integrations"],
+    ["onboard", "Sign in, map this repo's endpoints, connect it, test on push"],
     ["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"],
@@ -263,6 +263,7 @@ async function main() {
       authenticateTerminal,
       installDesktop: installDesktopCommand,
       openDesktopSignedIn,
+      installPushHook: installHook,
     });
   } else if (command === "aws") {
     await awsCommand(makeArgs(commandArgs));

package/bin/connect/guide.js

@@ -114,6 +114,10 @@ async function endpointCounts(args) {
  * asking, so an agent given only the MCP server can call PreMan and read nothing.
  */
 export function headlessDiscovery(agent, serverName, instructions = []) {
+  // Onboarding reaches here with no agent at all: nothing has been linked yet,
+  // and the machine may have none installed. That is not a failure, it is the
+  // brief-printing path, so answer "nothing to run" rather than throwing.
+  if (!agent) return null;
   const prompt = [
     `Register this project's HTTP endpoints in PreMan using the ${serverName} MCP tools.`,
     "Work autonomously and do not ask for confirmation.",
@@ -168,13 +172,20 @@ export async function discoverEndpoints(
     // Discovery has to read *this* repo, so it cannot be moved out of a directory
     // that redirects it the way the check-in was — it can only be skipped, before
     // it spends ten minutes proving what the self-test already found out.
-    const blocker = blockedHere || (spec && onPath(spec.bin) ? agentBlocker(agent.id) : "");
+    // PREMAN_NO_AGENT is for runs that must not spawn one -- CI, a sandbox, a
+    // suite testing the walk rather than the walk's agent. It takes the same
+    // path a missing agent does: print the brief and move on.
+    const blocker =
+      blockedHere ||
+      (process.env.PREMAN_NO_AGENT ? "PREMAN_NO_AGENT is set" : "") ||
+      (agent && spec && onPath(spec.bin) ? agentBlocker(agent.id) : "");
     if (!spec || !onPath(spec.bin) || blocker) {
       // Say why before printing homework: "here is a brief" reads as PreMan not
       // working, when the actual answer is one login away.
       if (blocker) process.stdout.write(`${MARK.skip()} ${blocker}\n`);
       for (const line of brief.instructions || []) process.stdout.write(`${line}\n`);
-      process.stdout.write(`\nHand this brief to ${agent.label}, then run:\n${manualSteps()}`);
+      const who = agent ? agent.label : "your coding agent";
+      process.stdout.write(`\nHand this brief to ${who}, then run:\n${manualSteps()}`);
       return before;
     }
 
@@ -356,35 +367,86 @@ async function setUpRunner(args, agent, { assumeYes }) {
   }
 }
 
-/** Offer the desktop app. Optional by design — the terminal flow is complete without it. */
-async function offerDesktop(args, { assumeYes }) {
+/**
+ * The question, word for word, wherever the desktop app is offered.
+ *
+ * Shared because both walks ask it and they must not drift: "install the
+ * desktop app?" got yes from people who thought they were agreeing to a menu
+ * bar icon, then spent two minutes watching an unexplained download. The size
+ * and the destination are the two facts that change the answer, and the last
+ * clause is there because the honest answer to "do I need this?" is no.
+ */
+export function desktopQuestion(args) {
+  const dest = args.value("--dest", "/Applications");
+  return `Download the PreMan desktop app? ~150MB, installs to ${dest} — optional, everything works without it`;
+}
+
+/** Where this run would put the app, honouring the same --dest the install does. */
+function desktopAppPath(args) {
+  return path.join(args.value("--dest", "/Applications"), "PreMan.app");
+}
+
+/**
+ * Why the desktop app should not be asked about here, or null to go ahead.
+ *
+ * Split out from the offer so a caller that runs its own prompt loop can decide
+ * whether the question is worth asking *before* asking it. Both of these were
+ * bugs when the check lived after the prompt: a Linux user got a macOS-only
+ * question, and someone who already had the app got asked to download it again.
+ */
+export function desktopPrecheck(args) {
   if (args.has("--no-desktop")) return { state: "skipped" };
-  if (process.platform !== "darwin") return { state: "unsupported" };
+  // An explicit --desktop is honoured whatever the platform: someone who asked
+  // for the app by name is owed the macOS-only notice and the download link
+  // rather than silence. Only the unasked offer is withheld where there is no
+  // build, because a step that announces itself to say "not for you" reads as
+  // something being broken.
+  if (process.platform !== "darwin" && !args.has("--desktop")) return { state: "unsupported" };
+  if (existsSync(desktopAppPath(args))) return { state: "installed" };
+  return null;
+}
+
+/**
+ * Install the desktop app, reporting rather than raising.
+ *
+ * `install` is injectable because onboarding does more than this one does — it
+ * hands the fresh session to the app so it opens signed in — and the part worth
+ * sharing is the guards, the default and the wording, not the install itself.
+ */
+export async function runDesktopInstall(args, { install = null } = {}) {
+  try {
+    return (await (install ? install() : installDesktopCommand([]))) || { state: "done" };
+  } catch (error) {
+    process.stdout.write(`${MARK.fail()} Desktop install failed: ${error.message}\n`);
+    return { state: "failed", detail: error.message };
+  }
+}
+
+export function desktopSkipped() {
+  process.stdout.write(`${MARK.skip()} Skipped. Install later: ${cliInvocation()} install-desktop\n`);
+}
+
+/** Offer the desktop app. Optional by design — the terminal flow is complete without it. */
+async function offerDesktop(args, { assumeYes } = {}) {
+  const already = desktopPrecheck(args);
+  // Silent on Linux and Windows: there is no build to offer, and a step that
+  // announces itself only to say "not for you" reads as something being wrong.
+  if (already && already.state !== "installed") return already;
   step("Desktop app");
-  if (existsSync("/Applications/PreMan.app")) {
+  if (already) {
     process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
-    return { state: "installed" };
+    return already;
   }
   // Default no, unlike every other step here: this one downloads a hundred-odd
   // megabytes and writes to /Applications, which nobody should get by pressing
-  // Enter to move past a prompt.
-  if (
-    !(await confirm("Install the PreMan desktop app to watch runs and endpoints?", {
-      assumeYes,
-      defaultYes: false,
-    }))
-  ) {
-    process.stdout.write(
-      `${MARK.skip()} Skipped. Install later: ${cliInvocation()} install-desktop\n`
-    );
+  // Enter to move past a prompt. `--desktop` is how an unattended run opts in,
+  // since `--yes` deliberately no longer does.
+  const wanted = args.has("--desktop");
+  if (!wanted && !(await confirm(desktopQuestion(args), { assumeYes, defaultYes: false }))) {
+    desktopSkipped();
     return { state: "skipped" };
   }
-  try {
-    return await installDesktopCommand([]);
-  } catch (error) {
-    process.stdout.write(`${MARK.fail()} Desktop install failed: ${error.message}\n`);
-    return { state: "failed", detail: error.message };
-  }
+  return runDesktopInstall(args);
 }
 
 /**

package/bin/connect.js

@@ -34,6 +34,7 @@ import {
   resolveApiKey,
 } from "./shared.js";
 import { MARK } from "./integrations.js";
+import { describeCheckout, resolveCheckout } from "./repo.js";
 import { ConnectError, EXIT_USAGE } from "./connect/errors.js";
 import {
   agentBlocker,
@@ -286,6 +287,13 @@ export async function connectCommand(commandArgs) {
 
   process.stdout.write(`${MARK.ok()} Connected as ${agent.label}.\n`);
 
+  // A statement, not a step: the agent is now pointed at this working tree, and
+  // whether PreMan knows this tree as a connected repository decides what the
+  // discovery below is worth. One request, no prompt, and silence when there is
+  // no GitHub remote to resolve — `preman github` is still where connecting
+  // happens.
+  process.stdout.write(describeCheckout(await resolveCheckout(args, apiKey)));
+
   // Connecting is one job. Running discovery, pairing a runner, offering the
   // desktop app and installing three integrations is five more, each with its
   // own prompt and its own way to fail -- and a connect that ends in a failed

package/bin/desktop.js

@@ -26,7 +26,7 @@ import {
 import os from "node:os";
 import path from "node:path";
 
-import { CREDENTIALS_DIR, cliInvocation, makeArgs } from "./shared.js";
+import { CREDENTIALS_DIR, makeArgs } from "./shared.js";
 
 export const DESKTOP_HELP = `
 Install-desktop options:
@@ -68,18 +68,50 @@ export function desktopAppInstalled(destination = "/Applications") {
  * 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.
  */
+function desktopSessionUser(creds) {
+  const raw = creds?.user;
+  if (!raw || typeof raw !== "object") return null;
+  const id = raw.id;
+  const email = typeof raw.email === "string" ? raw.email : "";
+  if (id == null || !email) return null;
+  const user = { id, email };
+  if (typeof raw.email_verified === "boolean") user.email_verified = raw.email_verified;
+  return user;
+}
+
+/**
+ * The desktop app's durable login cache is Chromium localStorage:
+ * `flow_auth_token` (the JWT from /auth/verify-otp or /auth/login) and
+ * `flow_auth_user` (`{"id", "email"}`). This file is the handoff that lets the
+ * app write those keys as if the customer had signed in on its own screen.
+ */
 export function writeDesktopSession(creds) {
   const apiKey = String(creds?.api_key || "").trim();
-  if (!apiKey.startsWith("pm_live_")) return { state: "no-key" };
+  const accessToken = String(creds?.access_token || "").trim();
+  const hasApiKey = apiKey.startsWith("pm_live_");
+  if (!hasApiKey && !accessToken) return { state: "no-key" };
+  const payload = {
+    user_email: creds?.user_email ?? creds?.user?.email ?? null,
+    created_at: new Date().toISOString(),
+  };
+  if (hasApiKey) payload.api_key = apiKey;
+  if (accessToken) payload.access_token = accessToken;
+  const user = desktopSessionUser(creds);
+  if (user) payload.user = user;
   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 }
-  );
+  writeFileSync(DESKTOP_SESSION_FILE, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+  // writeFileSync's mode only applies when it creates the file, and this one
+  // holds a session token — tighten an existing file explicitly.
+  chmodSync(DESKTOP_SESSION_FILE, 0o600);
   return { state: "written", path: DESKTOP_SESSION_FILE };
 }
 
+export function clearDesktopSession() {
+  if (!existsSync(DESKTOP_SESSION_FILE)) return false;
+  rmSync(DESKTOP_SESSION_FILE, { force: true });
+  return true;
+}
+
 /**
  * Install-or-not aside, get the customer into the app signed in.
  *
@@ -100,7 +132,9 @@ export async function openDesktopSignedIn(
     return { state: "not-installed" };
   }
   const handoff = writeDesktopSession(creds);
-  spawn("open", ["-a", "PreMan"], { stdio: "ignore", detached: true }).unref();
+  // The bundle path rather than the name: `open -a PreMan` asks LaunchServices,
+  // which may well pick a different copy than the one just installed.
+  spawn("open", ["-a", installedAppPath(destination)], { stdio: "ignore", detached: true }).unref();
   if (handoff.state !== "written") return { state: "opened", handoff: handoff.state };
 
   const deadline = Date.now() + waitMs;
@@ -269,7 +303,7 @@ function appInsideVolume(volume) {
   return bundle ? path.join(volume, bundle) : null;
 }
 
-export async function installDesktopCommand(commandArgs = []) {
+export async function installDesktopCommand(commandArgs = [], { onInstalled } = {}) {
   const args = makeArgs(commandArgs);
 
   if (process.platform !== "darwin" && !args.has("--print-url")) {
@@ -334,11 +368,10 @@ export async function installDesktopCommand(commandArgs = []) {
     run("cp", ["-R", source, target]);
     chmodSync(target, 0o755);
 
-    process.stdout.write(
-      `\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 };
+    const result = { state: "installed", version, arch, path: target };
+    process.stdout.write(`\nInstalled ${target}\n\n`);
+    onInstalled?.(result);
+    return result;
   } finally {
     if (mounted) {
       spawnSync("hdiutil", ["detach", mounted, "-quiet"], { encoding: "utf8" });

package/bin/detect.js

@@ -276,24 +276,76 @@ function inventoryForCandidate(candidate, inventory) {
   return { inventory: selected, scope };
 }
 
-/** Route keys the live app advertises through its generated spec, if it has one. */
+/** Route keys the live app advertises through its generated spec, if it has one.
+ *
+ * `keys` answers "is this the same service"; `routes` maps each key back to the
+ * path as written, which is what a caller needs to build a URL that resolves.
+ * Normalising is lossy in both case and parameter name, so the original cannot
+ * be recovered from the key afterwards.
+ */
 async function liveSpecRoutes(baseUrl, timeoutMs) {
   for (const specPath of SPEC_PATHS) {
     const spec = await fetchJson(`${baseUrl}${specPath}`, timeoutMs);
     const paths = spec && typeof spec === "object" ? spec.paths : null;
     if (!paths || typeof paths !== "object") continue;
     const keys = new Set();
+    const routes = new Map();
     for (const [rawPath, methods] of Object.entries(paths)) {
       if (!methods || typeof methods !== "object") continue;
       for (const method of Object.keys(methods)) {
-        keys.add(`${method.toUpperCase()} ${normalisePathTemplate(rawPath)}`);
+        const key = `${method.toUpperCase()} ${normalisePathTemplate(rawPath)}`;
+        keys.add(key);
+        if (!routes.has(key)) routes.set(key, String(rawPath));
       }
     }
-    if (keys.size) return { keys, via: specPath };
+    if (keys.size) return { keys, routes, via: specPath };
   }
   return null;
 }
 
+/**
+ * The mount prefix a scanned path is missing, according to the running app.
+ *
+ * A pre-push plan is scanned from the files the push touched, so the module that
+ * mounts the router is usually not among them -- and shipping it would not be
+ * enough anyway, because the prefix is commonly a variable
+ * (`include_router(r, prefix=settings.api_prefix)`) whose literal lives in a
+ * config class. No static scan resolves that without executing the app. The app
+ * itself has already published the answer in its spec, so the scanned path is
+ * matched against it by suffix and the difference is returned.
+ *
+ * Deliberately conservative, because a wrong prefix here sends real requests to
+ * a URL nobody wrote: the method must match, the suffix must land on a segment
+ * boundary so `/orders` cannot claim `/preorders`, and exactly one spec route
+ * may match. Two matches mean the same tail is mounted twice and choosing
+ * either would be a guess.
+ *
+ * Returns "" when the path is already correct, or null when it cannot be
+ * resolved -- which the caller must treat as "leave it alone", not as "".
+ */
+export function missingMountPrefix(method, path, specRoutes) {
+  if (!specRoutes || typeof specRoutes.get !== "function") return null;
+  const verb = String(method || "GET").toUpperCase();
+  const normalised = normalisePathTemplate(path);
+  if (!normalised || normalised === "/") return null;
+  // The leading slash is what makes the comparison below segment-aware: it is
+  // why `/orders` does not match `/api/v1/preorders`, whose tail is `eorders`.
+  const suffix = normalised.startsWith("/") ? normalised : `/${normalised}`;
+  if (specRoutes.has(`${verb} ${suffix}`)) return "";
+
+  let found = null;
+  for (const key of specRoutes.keys()) {
+    const gap = key.indexOf(" ");
+    if (key.slice(0, gap) !== verb) continue;
+    const candidate = key.slice(gap + 1);
+    if (!candidate.endsWith(suffix)) continue;
+    // Ambiguous: refuse rather than pick.
+    if (found !== null) return null;
+    found = candidate.slice(0, candidate.length - suffix.length).replace(/\/+$/, "");
+  }
+  return found;
+}
+
 export const CONFIRM_MIN_OVERLAP = 0.5;
 export const CONFIRM_MIN_ROUTES = 2;
 
@@ -345,6 +397,10 @@ export async function confirmCandidate(candidate, inventory, { timeoutMs = 2000
         expected: expected.size,
         overlap: Number(overlap.toFixed(3)),
         via: live.via,
+        // Carried so the caller can reconcile a scanned path against what the
+        // app actually serves. Only ever set on a spec-confirmed target: the
+        // probe path below proves reachability, not the route table.
+        specRoutes: live.routes,
       };
     }
     return {

package/bin/hook.js

@@ -171,13 +171,19 @@ function isOurHook(text) {
   return text.includes(MARKER);
 }
 
-export function installHook(args, { invocation = provenInvocation() } = {}) {
+export function installHook(args, { invocation } = {}) {
+  // Deliberately before the invocation is resolved: proving one costs a probe
+  // that can shell out to npm and reach the registry, and somewhere that is not
+  // a repository has nowhere to put a hook however that probe turns out. As a
+  // default parameter this ran first, so `preman onboard` in a plain directory
+  // spent up to the probe timeout before reporting there was nothing to do.
   const target = hookPath();
+  const resolved = invocation ?? provenInvocation();
 
   // A hook holding a command that does not run is worse than no hook: it is
   // silent, it says "installed" in every status we print, and the only sign of
   // it is one skipped line scrolling past a push nobody reads.
-  if (!invocation) {
+  if (!resolved) {
     return {
       path: target,
       action: "unproven",
@@ -187,7 +193,7 @@ export function installHook(args, { invocation = provenInvocation() } = {}) {
     };
   }
 
-  const body = hookBody(invocation);
+  const body = hookBody(resolved);
   mkdirSync(path.dirname(target), { recursive: true });
 
   if (existsSync(target)) {
@@ -195,7 +201,7 @@ export function installHook(args, { invocation = provenInvocation() } = {}) {
     if (isOurHook(existing)) {
       writeFileSync(target, body, { mode: 0o755 });
       chmodSync(target, 0o755);
-      return { path: target, action: "updated", invocation };
+      return { path: target, action: "updated", invocation: resolved };
     }
     if (!args.has("--force")) {
       return {
@@ -211,14 +217,14 @@ export function installHook(args, { invocation = provenInvocation() } = {}) {
     return {
       path: target,
       action: "replaced",
-      invocation,
+      invocation: resolved,
       detail: `previous hook saved to ${backup}`,
     };
   }
 
   writeFileSync(target, body, { mode: 0o755 });
   chmodSync(target, 0o755);
-  return { path: target, action: "installed", invocation };
+  return { path: target, action: "installed", invocation: resolved };
 }
 
 export function uninstallHook() {