premanmcp 0.15.0 → 0.15.2

package/README.md

@@ -114,9 +114,14 @@ push testing alone, and `--no-guide` connects and nothing else. With `--guide`,
 takes every step's default without asking and `--no-runner` / `--no-desktop` /
 `--no-integrations` skip one each.
 
-`--yes` deliberately does *not* install the desktop app: that step's default is no, because
-it downloads a hundred-odd megabytes and writes to `/Applications`. Run `install-desktop`
-when you want it.
+The desktop app is installed rather than offered. It was a question for a while, defaulted
+to no on the grounds that nobody should get a 150MB download by pressing Enter, and what
+that produced was a setup whose last act was to describe the app and decline to install
+it. The build is Developer ID signed and notarized, it is checked against the sha512
+published with the release before anything is copied into `/Applications`, and nothing
+arrives through a browser so there is no quarantine flag and no Gatekeeper warning on
+first launch. `--no-desktop`, or `PREMAN_NO_DESKTOP=1` where no flag can be passed, skips
+it; `install-desktop` does it on its own.
 
 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

package/bin/connect/guide.js

@@ -74,11 +74,11 @@ export function whatIsLeftBlock(args) {
 /**
  * Ask, or take the step's own default when nobody can answer.
  *
- * `--yes` returns the default rather than a blanket yes, which matters for
- * exactly one step: the desktop app defaults to no because it downloads a
- * hundred-odd megabytes and writes to /Applications. A blanket yes made
- * `preman connect --yes` do that unattended, which is not what anyone means by
- * "do not ask me questions" -- they get `preman install-desktop` for that.
+ * `--yes` returns each step's own default rather than a blanket yes, so a step
+ * that should not ride in on a keypress can say so. The desktop app used to be
+ * the only one that did, on the grounds that `--yes` should not mean 150MB into
+ * /Applications unattended; it does not ask at all now, and `PREMAN_NO_DESKTOP`
+ * or `--no-desktop` is how a run that does not want it says so.
  */
 export async function confirm(question, { assumeYes = false, defaultYes = true } = {}) {
   if (assumeYes) return defaultYes;
@@ -149,7 +149,13 @@ export async function discoverEndpoints(
   args,
   agent,
   serverName,
-  { blockedHere = "", force = false, basePath = ".", frameworkHint = undefined } = {}
+  {
+    blockedHere = "",
+    force = false,
+    basePath = ".",
+    frameworkHint = undefined,
+    handOffBrief = true,
+  } = {}
 ) {
   try {
     const before = await endpointCounts(args);
@@ -183,6 +189,20 @@ export async function discoverEndpoints(
       // 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`);
+      // The brief is written for an agent to execute, not for a person to read.
+      // Twenty lines of it in the middle of a setup walk reads as PreMan having
+      // failed, and the walk still has questions to ask after this. `endpoints
+      // discover` prints the same brief whenever it is actually wanted, so the
+      // pointer loses nothing but the wall of text.
+      if (!handOffBrief) {
+        if (!blocker) {
+          process.stdout.write(`${MARK.skip()} no coding agent here to read this repo\n`);
+        }
+        process.stdout.write(
+          `   Map it from inside one: ${cliInvocation()} endpoints discover\n`
+        );
+        return before;
+      }
       for (const line of brief.instructions || []) process.stdout.write(`${line}\n`);
       const who = agent ? agent.label : "your coding agent";
       process.stdout.write(`\nHand this brief to ${who}, then run:\n${manualSteps()}`);
@@ -367,38 +387,38 @@ async function setUpRunner(args, agent, { 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.
+ * An opt-out for runs that cannot pass a flag.
  *
- * 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.
+ * A bare `preman` with no arguments is a real entry point and now installs the
+ * app, which is right for a customer and wrong for a CI image or a suite that
+ * drives the walk end to end. `--no-desktop` cannot reach either of those, so
+ * they get the environment variable instead. Same spelling as PREMAN_NO_BROWSER
+ * and PREMAN_NO_AGENT, including that 0/false/no mean the opt-out is off.
+ */
+function noDesktopEnv() {
+  const optOut = (process.env.PREMAN_NO_DESKTOP || "").trim().toLowerCase();
+  return Boolean(optOut) && !["0", "false", "no"].includes(optOut);
+}
+
+/**
+ * Why the desktop app should not be installed here, or null to go ahead.
+ *
+ * Split out from the step so a caller running its own loop can decide whether
+ * the step is worth listing *before* listing it. Both of these were bugs when
+ * the check lived after: a Linux user got a macOS-only step, and someone who
+ * already had the app watched it download again.
  */
 export function desktopPrecheck(args) {
-  if (args.has("--no-desktop")) return { state: "skipped" };
+  if (args.has("--no-desktop") || noDesktopEnv()) return { state: "skipped" };
   // 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
+  // rather than silence. Only the unasked install 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" };
@@ -411,7 +431,7 @@ export function desktopPrecheck(args) {
  *
  * `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.
+ * sharing is the guards and the wording, not the install itself.
  */
 export async function runDesktopInstall(args, { install = null } = {}) {
   try {
@@ -422,14 +442,22 @@ export async function runDesktopInstall(args, { install = null } = {}) {
   }
 }
 
-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 } = {}) {
+/**
+ * Install the desktop app. Not a question.
+ *
+ * It used to be one, defaulted to no, on the grounds that the download is large
+ * and nobody should get it by pressing Enter. What that produced was a setup
+ * whose last act was to describe a thing and decline to do it — the customer
+ * still had to go install the app, only now by hand and later. The download is
+ * the whole reason a terminal is better placed to do this than a download page:
+ * the build is Developer ID signed and notarized, it lands in /Applications
+ * verified against the checksum published with the release, and because nothing
+ * here came through a browser there is no quarantine flag and so no Gatekeeper
+ * warning on first launch. Opting out is `--no-desktop`.
+ */
+async function offerDesktop(args) {
   const already = desktopPrecheck(args);
-  // Silent on Linux and Windows: there is no build to offer, and a step that
+  // Silent on Linux and Windows: there is no build to install, 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");
@@ -437,15 +465,6 @@ async function offerDesktop(args, { assumeYes } = {}) {
     process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
     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. `--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" };
-  }
   return runDesktopInstall(args);
 }
 
@@ -585,7 +604,7 @@ export async function guidedFirstRun(args, agent, apiKey, serverName, { blockedH
   step("Runner");
   await setUpRunner(args, agent, { assumeYes });
 
-  await offerDesktop(args, { assumeYes });
+  await offerDesktop(args);
 
   step("Integrations");
   await connectIntegrations(args, apiKey, { assumeYes });

package/bin/connect.js

@@ -144,11 +144,11 @@ Connect options:
                               and the integration prompts after connecting
   --no-guide                  Connect only: no push hook, no closing summary
   --no-runner                 With --guide, do not pair this machine as a runner
-  --no-desktop                With --guide, do not offer the desktop app
+  --no-desktop                With --guide, skip the desktop app, which otherwise
+                              installs. PREMAN_NO_DESKTOP=1 does the same
   --no-integrations           With --guide, do not offer GitHub / AWS / Slack
   --no-hook                   Do not install the git pre-push hook
   --yes                       Take every step's default without prompting
-                              (the desktop app defaults to no; install-desktop)
   --print                     Print the config instead of writing it
 `;
 

package/bin/desktop.js

@@ -243,13 +243,62 @@ async function expectedDigest(arch) {
   }
 }
 
-async function download(url, destination) {
+const BYTES_PER_MB = 1024 * 1024;
+
+/**
+ * A single line that rewrites itself, or nothing at all when not on a terminal.
+ *
+ * Onboarding no longer asks before installing the app, and a step nobody agreed
+ * to cannot also go quiet for ninety seconds: a still cursor during a 150 MB
+ * fetch is indistinguishable from a hang, and the reflex is Ctrl-C halfway
+ * through. Redirected output gets the summary line that already existed rather
+ * than a few hundred carriage returns, which is why this is TTY-only.
+ */
+function progressLine() {
+  if (!process.stdout.isTTY) return { tick: () => {}, clear: () => {} };
+  let lastDrawn = 0;
+  let width = 0;
+  const tick = (received, total) => {
+    const now = Date.now();
+    // One redraw per chunk is thousands of writes for an effect the eye cannot
+    // follow. The final chunk always draws, so the line never stops short.
+    if (now - lastDrawn < 150 && received !== total) return;
+    lastDrawn = now;
+    const got = (received / BYTES_PER_MB).toFixed(1);
+    const text = total
+      ? `  ${got} of ${(total / BYTES_PER_MB).toFixed(1)} MB  ${Math.floor((received / total) * 100)}%`
+      : `  ${got} MB`;
+    // Padded to the widest line drawn so far, or a shorter one leaves the tail
+    // of its predecessor on screen.
+    width = Math.max(width, text.length);
+    process.stdout.write(`\r${text.padEnd(width)}`);
+  };
+  const clear = () => {
+    if (width) process.stdout.write(`\r${" ".repeat(width)}\r`);
+  };
+  return { tick, clear };
+}
+
+async function download(url, destination, onProgress) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
   try {
     const resp = await fetch(url, { signal: controller.signal, redirect: "follow" });
     if (!resp.ok) throw new Error(`download failed: ${resp.status} ${url}`);
-    const buffer = Buffer.from(await resp.arrayBuffer());
+    // Read the body in chunks rather than as one arrayBuffer: the buffering is
+    // the same either way, but only this version can say how far along it is.
+    const total = Number(resp.headers.get("content-length")) || 0;
+    const reader = resp.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      received += value.length;
+      onProgress?.(received, total);
+    }
+    const buffer = Buffer.concat(chunks);
     writeFileSync(destination, buffer);
     return buffer.length;
   } finally {
@@ -335,8 +384,16 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
   let mounted = null;
 
   try {
-    const bytes = await download(url, dmgPath);
-    process.stdout.write(`  ${(bytes / 1024 / 1024).toFixed(1)} MB\n`);
+    const progress = progressLine();
+    let bytes;
+    try {
+      bytes = await download(url, dmgPath, progress.tick);
+    } finally {
+      // Cleared even when the download throws, or the error prints onto the
+      // half-drawn progress line.
+      progress.clear();
+    }
+    process.stdout.write(`  ${(bytes / BYTES_PER_MB).toFixed(1)} MB\n`);
 
     const expected = await expectedDigest(arch);
     if (expected) {

package/bin/integrations.js

@@ -16,7 +16,9 @@
 
 import { describeCheckout, explainNoCheckout, resolveCheckout } from "./repo.js";
 import {
+  DEFAULT_BACKEND,
   assertOk,
+  backendUrl,
   callBackendJson,
   cliInvocation,
   frontendUrl,
@@ -86,10 +88,14 @@ function showOpeningDesktop() {
   };
 }
 
+const INSTALLATIONS_URL = "https://github.com/settings/installations";
+
 function present(url, what) {
   process.stdout.write(`\n  ${url}\n\n`);
-  if (openUrl(url)) process.stdout.write(`Opened ${what} in your browser.\n`);
-  else process.stdout.write(`Open the link above to ${what}.\n`);
+  // A tab appearing is its own confirmation; saying so as well spends a line
+  // on what the customer is already looking at. It earns its place only when
+  // no tab opened and the link is the way through.
+  if (!openUrl(url)) process.stdout.write(`Open the link above to ${what}.\n`);
 }
 
 /**
@@ -293,9 +299,7 @@ export async function githubCommand(args) {
     {
       timeoutMs: Number(process.env.PREMAN_GITHUB_POLL_MS) || GITHUB_POLL_TIMEOUT_MS,
       hintAfterMs: 20000,
-      hint:
-        "Still nothing from GitHub. Picking at least one repository and confirming\n" +
-        "is what sends you back here.",
+      hint: "Still nothing from GitHub — confirm a repository to come back here.",
     }
   );
 
@@ -319,15 +323,12 @@ function githubHandOff(args, refresh) {
   if (installed) {
     return (
       `The App is installed, but no repositories are shared with it.\n` +
-      `  - Add some: https://github.com/settings/installations\n` +
-      `  - Then re-run '${cliInvocation()} github'.\n`
+      `  Add some at ${INSTALLATIONS_URL}, then re-run '${cliInvocation()} github'.\n`
     );
   }
   return (
-    `Nothing from GitHub yet — no need to wait here.\n` +
-    `  - Finish the install in the browser; it records itself when you confirm.\n` +
-    `  - Check it: ${frontendUrl(args)}  or  https://github.com/settings/installations\n` +
-    `  - Then re-run '${cliInvocation()} github'.\n`
+    `Nothing from GitHub yet. Finish the install in the browser — it records itself.\n` +
+    `  Then re-run '${cliInvocation()} github'.\n`
   );
 }
 
@@ -369,11 +370,9 @@ export async function slackCommand(args) {
  * "yes" | "no" | "back" -- back only offered once there is somewhere to go.
  *
  * `--yes` takes each step's own default rather than answering yes to all of
- * them. One step needs that today and it is the expensive one: the desktop app
- * defaults to no because it downloads a hundred-odd megabytes and writes to
- * /Applications, and `onboard --yes` used to do exactly that, unattended, to
- * someone who only meant "stop asking me questions". They have
- * `preman install-desktop` when they want it.
+ * them, so a step that should not ride in on a keypress can say so. Every step
+ * that asks defaults to yes today; the desktop app, which used to be the
+ * exception, no longer asks at all.
  */
 async function askStep(question, { assumeYes, canGoBack, defaultYes = true }) {
   const fallback = defaultYes ? "yes" : "no";
@@ -400,7 +399,8 @@ async function askStep(question, { assumeYes, canGoBack, defaultYes = true }) {
  * halfway had a desktop app pointed at an empty account. Endpoints come first
  * now because they are the only step that shows what PreMan is for, and every
  * ask after it can name what it just found. The app goes last because it is the
- * one thing here nobody needs.
+ * 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.
  *
  * The steps themselves live in connect/guide.js, which is also what
  * `preman connect --guide` runs. Two walks that asked the same questions in
@@ -416,12 +416,24 @@ export async function onboardCommand(
   // Imported at call time, not at the top: guide.js imports this module for MARK
   // and the three integration commands, so a static edge back would close the
   // cycle. By the time anyone runs onboard, this module is fully evaluated.
-  const { desktopPrecheck, desktopQuestion, desktopSkipped, discoverEndpoints, runDesktopInstall } =
-    await import("./connect/guide.js");
+  const { desktopPrecheck, discoverEndpoints, runDesktopInstall } = await import(
+    "./connect/guide.js"
+  );
   const { resolveAgentToDrive } = await import("./connect/agents.js");
 
   process.stdout.write("PreMan setup\n\n");
 
+  // Which PreMan this is talking to is invisible until the very last line,
+  // and a stored login from a local run silently redirects the whole walk:
+  // the account is created in a database nobody else can see, and the GitHub
+  // App redirects to the real callback, so the install never arrives and the
+  // wait looks like GitHub being slow. Production says nothing, because there
+  // is nothing to warn about; anything else is worth one line up front.
+  const target = backendUrl(args);
+  if (target !== DEFAULT_BACKEND) {
+    process.stdout.write(`${MARK.skip()} Using ${target}, not ${DEFAULT_BACKEND}.\n\n`);
+  }
+
   const creds = await authenticateTerminal(args);
   connected(`Signed in as ${creds.user_email || "your account"}.`);
 
@@ -449,7 +461,9 @@ export async function onboardCommand(
           agent: args.value("--agent", ""),
           interactive: false,
         });
-        const counts = await discoverEndpoints(args, agent, args.value("--name", "preman"));
+        const counts = await discoverEndpoints(args, agent, args.value("--name", "preman"), {
+          handOffBrief: false,
+        });
         return { state: counts.registered ? "done" : "skipped", counts };
       },
     },
@@ -483,9 +497,7 @@ export async function onboardCommand(
           return;
         }
         process.stdout.write(
-          `${checkout.slug} is still not shared with PreMan.\n` +
-            `  Add it at https://github.com/settings/installations, then re-run ` +
-            `'${cliInvocation()} github'.\n`
+          `${checkout.slug} is still not shared. Add it at ${INSTALLATIONS_URL}.\n`
         );
       },
     });
@@ -549,10 +561,10 @@ export async function onboardCommand(
     },
   });
 
-  // Last, defaulted to no, and only where there is something to install. The
-  // guards run out here rather than inside the step so a Linux user is not
-  // asked a macOS question and someone who already has the app is not asked to
-  // download it again — both of which happened when the check came after.
+  // Last, and only where there is something to install. The guards run out here
+  // rather than inside the step so a Linux user does not get a macOS-only step
+  // 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") {
     steps.push({
@@ -564,11 +576,8 @@ export async function onboardCommand(
   } else if (!desktop) {
     steps.push({
       name: "Desktop app",
-      question: desktopQuestion(args),
-      // `--desktop` is how an unattended run opts in, since `--yes` gives every
-      // step its own default and this step's default is no.
-      defaultYes: args.has("--desktop"),
-      onSkip: desktopSkipped,
+      // 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
@@ -685,16 +694,17 @@ export const INTEGRATIONS_HELP = `
 Setup options:
   preman onboard              Sign in, map this repo's endpoints, connect it for
                               pull requests, and check the endpoints you touch on
-                              every git push. Offers the desktop app at the end
+                              every git push. Installs the desktop app at the end
   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
 
-  --yes                       Take each step's default without prompting. The
-                              desktop app defaults to no, so --yes never
-                              downloads it (onboard)
-  --desktop                   Install the desktop app without asking (onboard)
-  --no-desktop                Do not offer the desktop app at all (onboard)
+  --yes                       Take each step's default without prompting (onboard)
+  --desktop                   Install the desktop app even where there is no macOS
+                              build, to print the download link (onboard)
+  --no-desktop                Skip the desktop app, which otherwise installs
+                              (onboard)
+  PREMAN_NO_DESKTOP=1         The same, for runs that cannot pass a flag
   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

package/package.json

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