premanmcp 1.0.0 → 1.0.2

package/bin/api_tools.js

@@ -9,7 +9,13 @@
 
 import { readFileSync } from "node:fs";
 
-import { callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
+import {
+  callBackendJson,
+  cliInvocation,
+  describeFailure,
+  makeArgs,
+  resolveApiKey,
+} from "./shared.js";
 import { printPlayground } from "./desktop.js";
 
 export const ENDPOINTS_HELP = `
@@ -61,22 +67,6 @@ const TOOL_ROUTES = {
   share_endpoints_with_ui: { method: "POST", path: "/cli/playground-session" },
 };
 
-/**
- * A failure a person can act on.
- *
- * FastAPI's `detail` is often an object, and interpolating one straight into a
- * template gives `[object Object]` — which is what a retired route reported for
- * a day, hiding both its status and its remedy.
- */
-function describeFailure(result) {
-  const detail = result.detail ?? result.message ?? result.raw;
-  if (typeof detail === "string" && detail) return detail;
-  if (detail && typeof detail === "object") {
-    return detail.message || detail.code || JSON.stringify(detail);
-  }
-  return "backend error";
-}
-
 export async function callTool(args, tool, toolArguments) {
   const token = resolveApiKey(args);
   if (!token) {

package/bin/cli.js

@@ -38,7 +38,12 @@ import { STATUS_HELP, statusCommand } from "./status.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";
+import {
+  DESKTOP_HELP,
+  desktopAppRunning,
+  installDesktopCommand,
+  openDesktopSignedIn,
+} from "./desktop.js";
 import { ACCOUNT_HELP, doctorCommand, loginBrowser, logoutCommand, watchCommand } from "./account.js";
 import {
   CREDENTIALS_FILE,
@@ -150,7 +155,18 @@ Email: ${creds.user_email || "unknown"}
 Backend: ${creds.backend_url}
 API key: ${creds.api_key}
 Saved to: ${CREDENTIALS_FILE}
-
+`);
+  // `authenticateTerminal` has already left the session for the app to pick up,
+  // but only a launch reads it. Signing in here while the app is open otherwise
+  // changes nothing on screen, and the window carries on showing the previous
+  // account with no sign that a different one is now signed in.
+  if (desktopAppRunning()) {
+    process.stdout.write(
+      `\nPreMan is open and still signed in as before.\n` +
+        `  Quit and reopen it to switch${creds.user_email ? ` to ${creds.user_email}` : ""}.\n`
+    );
+  }
+  process.stdout.write(`
 You can now run:
   ${cli} connect
 `);

package/bin/desktop.js

@@ -103,6 +103,53 @@ export function desktopAppInstalled(destination = "/Applications") {
   return process.platform === "darwin" && existsSync(installedAppPath(destination));
 }
 
+/**
+ * Is a copy of the app already up?
+ *
+ * This decides whether a handoff is possible at all. `open` on a running app
+ * raises the window it already has instead of starting a process, and the
+ * session file is only read at launch -- so a running app cannot take up a
+ * session no matter how long the CLI waits for it to. Without this check the
+ * CLI waited out the full timeout and then reported the failure as though the
+ * app were merely old, which left people looking at whichever account the app
+ * was already showing with nothing to explain it.
+ *
+ * Matched on the bundle's own executable directory. The helper processes live
+ * under `Contents/Frameworks/...` and so do not match, which keeps this to the
+ * one process whose launch reads the file.
+ */
+export function desktopAppRunning(destination = "/Applications") {
+  if (process.platform !== "darwin") return false;
+  const binary = path.join(installedAppPath(destination), "Contents", "MacOS");
+  const found = spawnSync("pgrep", ["-f", binary], { encoding: "utf8" });
+  return found.status === 0 && String(found.stdout || "").trim() !== "";
+}
+
+/**
+ * Ask the app to quit, and wait for it to actually be gone.
+ *
+ * Only ever a graceful `quit`: this runs while someone is watching a setup walk,
+ * and a tool that kills an app to save three seconds is not one people leave
+ * installed. A copy that ignores the request keeps running and the caller says
+ * so rather than escalating.
+ */
+export async function quitDesktopApp({
+  destination = "/Applications",
+  timeoutMs = 8_000,
+  sleep = defaultSleep,
+} = {}) {
+  if (!desktopAppRunning(destination)) return "not-running";
+  spawnSync("osascript", ["-e", `quit app "${APP_NAME.replace(/\.app$/i, "")}"`], {
+    stdio: "ignore",
+  });
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await sleep(250);
+    if (!desktopAppRunning(destination)) return "quit";
+  }
+  return "still-running";
+}
+
 /**
  * Hand the account the CLI just signed in to over to the desktop app.
  *
@@ -165,28 +212,56 @@ export function clearDesktopSession() {
  * all would otherwise be reported as signed in while the customer looks at a
  * login screen. The file is left behind on timeout -- it expires on its own, and
  * a slow first launch can still find it.
+ *
+ * An app that is already running is the one case where waiting cannot help,
+ * because only a launch reads the file. `restartIfRunning` is how a caller whose
+ * whole purpose is to leave someone signed in asks for the restart that makes
+ * the handoff possible; callers that are only opening a window leave it off and
+ * get told the session was not taken up.
  */
 export async function openDesktopSignedIn(
   creds,
-  { destination = "/Applications", waitMs = 12_000, sleep = defaultSleep } = {}
+  {
+    destination = "/Applications",
+    waitMs = 12_000,
+    sleep = defaultSleep,
+    restartIfRunning = false,
+    // Injected the same way `sleep` is, so the running/quitting branches can be
+    // exercised without a real app on the machine running the tests.
+    isRunning = desktopAppRunning,
+    quit = quitDesktopApp,
+  } = {}
 ) {
   if (!desktopAppInstalled(destination)) {
     return { state: "not-installed" };
   }
+  const wasRunning = isRunning(destination);
+  let restarted = false;
+  if (wasRunning && restartIfRunning) {
+    restarted = (await quit({ destination, sleep })) === "quit";
+  }
   const handoff = writeDesktopSession(creds);
   // 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 };
 
+  if (wasRunning && !restarted) {
+    // Nothing is going to read the file, so the timeout would only be a slower
+    // way to reach this same answer. The session is deliberately left on disk:
+    // it is what the next launch adopts, which is exactly what the customer is
+    // about to be told to do.
+    return { state: "opened-already-running", handoff: handoff.state };
+  }
+
   const deadline = Date.now() + waitMs;
   while (Date.now() < deadline) {
     await sleep(500);
     if (!existsSync(DESKTOP_SESSION_FILE)) {
-      return { state: "opened-signed-in", handoff: handoff.state };
+      return { state: "opened-signed-in", handoff: handoff.state, restarted };
     }
   }
-  return { state: "opened-not-adopted", handoff: handoff.state };
+  return { state: "opened-not-adopted", handoff: handoff.state, restarted };
 }
 
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

package/bin/integrations.js

@@ -15,6 +15,7 @@
  */
 
 import { describeCheckout, explainNoCheckout, resolveCheckout } from "./repo.js";
+import { desktopAppInstalled, writeDesktopSession } from "./desktop.js";
 import {
   DEFAULT_BACKEND,
   assertOk,
@@ -254,7 +255,7 @@ export async function awsCommand(args) {
 // GitHub
 // ---------------------------------------------------------------------------
 
-export async function githubCommand(args) {
+export async function githubCommand(args, { ensureDesktopApp = null } = {}) {
   const token = requireKey(args);
 
   // This route answers with a bare array; callBackendJson exposes it as `list`.
@@ -265,15 +266,24 @@ export async function githubCommand(args) {
 
   const seen = new Set((await listRepos()).map((r) => r.id));
 
-  // `return_to: "desktop"` because the person who ran this is in a terminal and
-  // the CLI is already polling for the installation. The web return 302s the
-  // tab into the hosted dashboard � an app they did not ask for, on whichever
-  // environment owns the App's setup URL. The desktop return finishes on a page
-  // that offers PreMan and says the tab may be closed, which is all the browser
-  // still has to do here.
+  // The desktop return is the right ending for a run started in a terminal: the
+  // CLI is already polling for the installation, and the web return 302s the
+  // tab into the hosted dashboard — an app they did not ask for, on whichever
+  // environment owns the App's setup URL.
+  //
+  // What it must never be is unconditional. That page's only action is a
+  // preman:// link, and a machine with no app answers one with a system dialog
+  // reading "There is no application set to open the URL preman://open". That is
+  // where a first run actually ended, every time: the app installs at the end of
+  // this walk and GitHub is asked about in the middle, so by the time this link
+  // was minted there had never been an app. A caller may put one there first;
+  // without one, the web return is the only ending that leads anywhere.
+  const hasDesktopApp = ensureDesktopApp
+    ? await ensureDesktopApp()
+    : desktopAppInstalled(args.value("--dest", "/Applications"));
   const started = await callBackendJson(args, "POST", "/integrations/github/app/install", {
     token,
-    json: { return_to: "desktop" },
+    json: { return_to: hasDesktopApp ? "desktop" : "web" },
   });
   assertOk(started, "start GitHub install");
 
@@ -493,14 +503,32 @@ async function showDesktopSignedIn(openDesktopSignedIn, args, creds, stopOpening
   // The same --dest the install honoured, or the launch would look for the app
   // somewhere it was never copied to.
   const destination = args.value("--dest", "/Applications");
-  const opened = await openDesktopSignedIn(creds, { destination });
+  // This step exists to end with someone looking at PreMan as the account the
+  // walk just signed in to. A copy that is already running only reads a session
+  // when it starts, so restarting it is the difference between doing that and
+  // handing back a window still showing whoever was signed in before.
+  const opened = await openDesktopSignedIn(creds, { destination, restartIfRunning: true });
   stopOpening?.();
+  const email = String(creds?.user_email || creds?.user?.email || "").trim();
   if (opened.state === "opened-signed-in") {
-    process.stdout.write("Opened PreMan, signed in as this account.\n");
+    process.stdout.write(
+      opened.restarted
+        ? "PreMan was already open \u2014 restarted it, signed in as this account.\n"
+        : "Opened PreMan, signed in as this account.\n"
+    );
   } else if (opened.state === "not-installed") {
     process.stdout.write(
       `PreMan is not in ${destination} yet \u2014 open it once installed and sign in.\n`
     );
+  } else if (opened.state === "opened-already-running") {
+    // The window on screen belongs to an earlier session, and nothing about it
+    // says so. Name the account being switched to, and the one action that
+    // completes the switch -- the session is on disk and the next launch takes
+    // it up, so quitting really is all that is left to do.
+    process.stdout.write(
+      `PreMan was already open and kept its previous sign-in.\n` +
+        `  Quit and reopen it to switch${email ? ` to ${email}` : ""}.\n`
+    );
   } else {
     // Either the session could not be handed over or this app is too old to take
     // it up. Say so rather than let the customer wonder why they are looking at
@@ -572,6 +600,12 @@ async function askStep(question, { assumeYes, canGoBack, defaultYes = true }) {
  * only step that asks nothing: by then every decision is made, and a download is
  * something to leave running, not something to make someone watch first.
  *
+ * With one exception, and it is not a preference. Connecting a repository ends
+ * with GitHub handing the browser back through a preman:// link, and a machine
+ * with no app answers that with a system dialog rather than a window. So saying
+ * yes to the repository pulls the download forward to just before it; saying no
+ * leaves the order exactly as described above.
+ *
  * The steps themselves live in connect/guide.js, which is also what
  * `preman connect --guide` runs. Two walks that asked the same questions in
  * different words with different defaults was the thing worth deleting.
@@ -613,6 +647,43 @@ export async function onboardCommand(
   // is said in one place rather than before PreMan has looked at the code.
   const checkout = await resolveCheckout(args, resolveApiKey(args));
 
+  // What the app install did, once, shared by the step that needs an app to
+  // exist and the step that owns installing one.
+  //
+  // GitHub's callback ends on a page whose only action is a preman:// link, and
+  // the app is the last step of this walk — so a first run always handed GitHub
+  // back to a machine with nothing to open it with, and macOS said so in a
+  // dialog. The download moves in front of that step when it is needed and stays
+  // where it was when it is not: someone who declines the repository never
+  // reaches this, and still gets the app at the end.
+  //
+  // Memoised because it is a hundred megabytes and both callers want the same
+  // copy of it. Answers whether there is now an app on this machine, which is
+  // the only part either caller can act on.
+  let desktopInstall = null;
+  const installedNow = (result) => result?.state === "installed" || result?.state === "current";
+  const ensureDesktopApp = async ({ onInstalled } = {}) => {
+    const already = desktopPrecheck(args);
+    if (already?.state === "installed") return true;
+    // --no-desktop, or a platform with no build. Nothing to install here, and so
+    // nothing that could ever answer a preman:// link either.
+    if (already) return false;
+    if (!desktopInstall) {
+      process.stdout.write(
+        "Getting the PreMan app first, so GitHub has somewhere to hand you back to.\n"
+      );
+      desktopInstall = await runDesktopInstall(args, {
+        install: () => installDesktop([...commandArgs], onInstalled ? { onInstalled } : undefined),
+      });
+      // Handed the session the moment it lands, before anything can launch it.
+      // The app reads one only when it starts, and the callback's deep link is a
+      // start — without this it opens on a login screen for an account signed in
+      // ninety seconds ago.
+      if (installedNow(desktopInstall)) writeDesktopSession(creds);
+    }
+    return installedNow(desktopInstall);
+  };
+
   const steps = [
     {
       // No question. Everything below is a decision about code PreMan has not
@@ -654,7 +725,7 @@ export async function onboardCommand(
         return `Connect ${checkout.slug} so PreMan can open pull requests for the ${found} endpoint${found === 1 ? "" : "s"} it just mapped?`;
       },
       run: async () => {
-        await githubCommand(args);
+        await githubCommand(args, { ensureDesktopApp });
         // Finishing the App install is not the same as this repository being
         // connected: the install shares whichever repositories the customer
         // picked, which may not include this one. Re-asking is the difference
@@ -765,66 +836,55 @@ export async function onboardCommand(
   // and someone who already has the app does not watch it download again — both
   // of which happened when the check came after.
   const desktop = desktopPrecheck(args);
-  if (desktop?.state === "installed") {
+  if (desktop?.state === "installed" || !desktop) {
     steps.push({
       name: "Desktop app",
-      // Nothing to download, which is the point of this branch. It is not a
-      // reason to stop at the sentence: the step exists to leave the customer
-      // looking at PreMan, so the one run with nothing to install was also the
-      // only run that opened nothing, and it closed by sending someone to a
-      // website instead of the app already sitting on their machine.
+      // No question. See offerDesktop in connect/guide.js for why the ask went
+      // away; `--no-desktop` is the way past it.
+      //
+      // Installing and launching used to be one thing here, which is why the one
+      // run with nothing to install was also the only run that opened nothing: it
+      // stopped at the sentence and sent someone to a website instead of the app
+      // already sitting on their machine. They are two things now, and the
+      // install may have happened further up the walk, so this step is the launch
+      // and ensureDesktopApp decides whether anything is left to download.
       run: async () => {
-        process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
-        const stopOpening = showOpeningDesktop();
+        // Said only when this walk did not just download it. After an install of
+        // our own, announcing that it is already installed is the walk telling
+        // somebody about their own last thirty seconds.
+        if (!desktopInstall && desktopPrecheck(args)?.state === "installed") {
+          process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
+        }
+        let stopOpening = null;
         try {
+          const ready = await ensureDesktopApp({
+            onInstalled: () => {
+              stopOpening ??= showOpeningDesktop();
+            },
+          });
+          if (!ready) {
+            if (desktopInstall?.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");
+            }
+            // A failed install already said so through runDesktopInstall, and its
+            // state is what keeps this out of the summary as a skip.
+            return desktopInstall || { state: "skipped" };
+          }
+          stopOpening ??= showOpeningDesktop();
           return {
+            ...(desktopInstall || {}),
+            // Onboarding installs *and* hands the fresh session over, so the app
+            // opens already signed in rather than on a login screen for the
+            // account created ninety seconds ago.
             appOpened: await showDesktopSignedIn(openDesktopSignedIn, args, creds, stopOpening),
           };
         } finally {
-          stopOpening();
+          stopOpening?.();
         }
       },
     });
-  } else if (!desktop) {
-    steps.push({
-      name: "Desktop app",
-      // No question. See offerDesktop in connect/guide.js for why the ask went
-      // away; `--no-desktop` is the way past it.
-      run: () =>
-        runDesktopInstall(args, {
-          // Onboarding installs *and* hands the fresh session over, so the app
-          // opens already signed in rather than on a login screen for the
-          // account created ninety seconds ago.
-          install: async () => {
-            let stopOpening = null;
-            try {
-              const installed = await installDesktop([...commandArgs], {
-                onInstalled: () => {
-                  stopOpening ??= showOpeningDesktop();
-                },
-              });
-              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 installed;
-              }
-              stopOpening ??= showOpeningDesktop();
-              return {
-                ...installed,
-                appOpened: await showDesktopSignedIn(
-                  openDesktopSignedIn,
-                  args,
-                  creds,
-                  stopOpening
-                ),
-              };
-            } finally {
-              stopOpening?.();
-            }
-          },
-        }),
-    });
   }
 
   // Outcome per step rather than three lists, so revisiting a step replaces its

package/bin/shared.js

@@ -430,10 +430,33 @@ export async function callBackendJson(
   };
 }
 
+/**
+ * Turn a backend error body into something a person can act on.
+ *
+ * FastAPI's ``detail`` is a string on a raised HTTPException, an array of
+ * ``{loc, msg}`` objects on a validation error, and occasionally an object with
+ * its own shape. Interpolating it directly renders the two useful cases as
+ * ``[object Object]``, which is how "this route is gone, call /cli/endpoints
+ * instead" reached a customer as `410 [object Object]` -- a remedy the response
+ * carried and the screen never showed.
+ */
+export function describeFailure(result, fallback = "backend error") {
+  const detail = result?.detail ?? result?.message ?? result?.raw;
+  if (typeof detail === "string" && detail) return detail;
+  if (Array.isArray(detail) && detail.length) {
+    return detail.map((item) => item?.msg || JSON.stringify(item)).join("; ");
+  }
+  if (detail && typeof detail === "object") {
+    return detail.message || detail.error || detail.code || JSON.stringify(detail);
+  }
+  return fallback;
+}
+
 export 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}`);
+  throw new Error(
+    `${action} failed: ${result.status_code} ${describeFailure(result, `${action} failed`)}`
+  );
 }
 
 function authSessionFrom(result, email) {

package/bin/status.js

@@ -6,7 +6,15 @@
  * section as possibly empty.
  */
 
-import { backendUrl, callBackendJson, cliInvocation, makeArgs, resolveApiKey, truncate } from "./shared.js";
+import {
+  backendUrl,
+  callBackendJson,
+  cliInvocation,
+  describeFailure,
+  makeArgs,
+  resolveApiKey,
+  truncate,
+} from "./shared.js";
 
 export const STATUS_HELP = `
 Status options:
@@ -225,8 +233,10 @@ export async function statusCommand(commandArgs = []) {
   });
 
   if (!result.ok) {
-    const detail = result.detail || result.raw || "request failed";
-    throw new Error(`could not read status from ${backendUrl(args)}: ${result.status_code} ${detail}`);
+    throw new Error(
+      `could not read status from ${backendUrl(args)}: ${result.status_code} ` +
+        describeFailure(result, "request failed")
+    );
   }
 
   const { status_code, ok, ...payload } = result;

package/bin/tests.js

@@ -6,7 +6,13 @@
  * scenarios for one endpoint via `POST /cli/tests/generate`.
  */
 
-import { callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
+import {
+  callBackendJson,
+  cliInvocation,
+  describeFailure,
+  makeArgs,
+  resolveApiKey,
+} from "./shared.js";
 
 export const TESTS_HELP = `
 Collections tests:
@@ -62,17 +68,7 @@ function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
-function errorDetail(result) {
-  const detail = result.detail;
-  if (typeof detail === "string") return detail;
-  if (Array.isArray(detail)) {
-    return detail.map((item) => item.msg || JSON.stringify(item)).join("; ");
-  }
-  if (detail && typeof detail === "object") {
-    return detail.message || detail.error || JSON.stringify(detail);
-  }
-  return result.message || result.raw || "backend error";
-}
+const errorDetail = (result) => describeFailure(result);
 
 async function workbench(args, method, routePath, { json } = {}) {
   const token = requireKey(args);

package/bin/verify.js

@@ -27,7 +27,7 @@ import { changedFilesForPush, readChangedFiles, readPushRefsFromStdin, repoRoot
 import { missingMountPrefix, resolveLocalTarget } from "./detect.js";
 import { formatDashboardLink, formatPushLink } from "./link.js";
 import { createReporter } from "./progress.js";
-import { backendUrl, callBackendJson, cliInvocation, frontendUrl, makeArgs, nowMs, resolveApiKey } from "./shared.js";
+import { backendUrl, callBackendJson, cliInvocation, describeFailure, frontendUrl, makeArgs, nowMs, resolveApiKey } from "./shared.js";
 
 export const VERIFY_HELP = `
 Verify options:
@@ -250,7 +250,11 @@ async function fetchInventory(args, token) {
     if (!result.ok) {
       return {
         endpoints,
-        error: result.detail || `status ${result.status_code}`,
+        // FastAPI answers a rejected request with an object, and a validation
+        // error with an array of them. Interpolated straight into the skip
+        // line, both read as "[object Object]" -- which is what every push
+        // against a backend that said no has printed.
+        error: describeFailure(result, `status ${result.status_code}`),
       };
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {