premanmcp 0.15.1 → 0.15.3

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;
@@ -387,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" };
@@ -431,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 {
@@ -442,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");
@@ -457,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);
 }
 
@@ -605,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

@@ -370,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";
@@ -401,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
@@ -417,8 +416,9 @@ 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");
@@ -561,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({
@@ -576,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
@@ -618,7 +615,9 @@ export async function onboardCommand(
                 // why they are looking at a login screen.
                 process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
               }
-              return installed;
+              // Whether the app is on screen decides what the last line of the walk
+              // should say, and only this closure knows.
+              return { ...installed, appOpened: opened.state !== "not-installed" };
             } finally {
               stopOpening?.();
             }
@@ -668,10 +667,18 @@ export async function onboardCommand(
     }
 
     try {
-      // A step that caught its own failure and already explained it says so, and
-      // is not summarised as done; anything else that returns is taken as done.
+      // A step that caught its own failure and already explained it says so; a step
+      // with nothing to do says that; anything else that returns is done.
+      //
+      // Translated rather than spread over, because the summary knows three words
+      // and a step may report any of its own. Spreading put `Desktop app: undefined`
+      // at the end of a successful install: the install reports state "installed",
+      // which is none of the three, so it printed as a failure with no detail.
       const reported = await step.run();
-      outcome.set(step.name, { state: "done", ...(reported || {}) });
+      const state =
+        { failed: "failed", skipped: "skipped", unsupported: "skipped" }[reported?.state] ||
+        "done";
+      outcome.set(step.name, { ...(reported || {}), state });
     } catch (err) {
       // Report and carry on: a failed Slack install must not cost the customer
       // the AWS connection they just finished.
@@ -690,23 +697,33 @@ export async function onboardCommand(
     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`);
+  // The app is on screen by the time this prints, so telling them to go and open
+  // a website is a step backwards. The website still earns its mention -- it is
+  // the way in from a machine that has no app, and the account is the same one --
+  // but as an alternative, not as the next thing to do.
+  const appOpened = outcome.get("Desktop app")?.appOpened === true;
+  process.stdout.write(
+    appOpened
+      ? `\nPreMan is open. You can also sign in at ${frontendUrl(args)}.\n`
+      : `\nOpen ${frontendUrl(args)} to see your logs and endpoints.\n`
+  );
 }
 
 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.1",
+  "version": "0.15.3",
   "description": "Turn APIs into agent-callable MCP tools with auth, testing, and audit logs",
   "type": "module",
   "bin": {