premanmcp 1.1.11 → 1.1.13

package/bin/desktop.js

@@ -31,25 +31,33 @@
  * has to do.
  */
 
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import { once } from "node:events";
 import {
+  accessSync,
   chmodSync,
+  constants,
+  createWriteStream,
   existsSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
   readdirSync,
+  renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { finished } from "node:stream/promises";
 
 import { CREDENTIALS_DIR, makeArgs } from "./shared.js";
 
 export const DESKTOP_HELP = `
 Install-desktop options:
+  --allow-unverified    Install even when no published checksum can be read
   --arch <arm64|x64>    Override architecture detection
   --dest <dir>          Install directory. Defaults to /Applications
   --force               Reinstall even when the latest release is already installed
@@ -60,7 +68,43 @@ Install-desktop options:
 const RELEASES_BASE = "https://github.com/PreMan-Inc/PreMan-Desktop/releases";
 const RELEASE_API = "https://api.github.com/repos/PreMan-Inc/PreMan-Desktop/releases/latest";
 export const APP_NAME = "PreMan.app";
-const DOWNLOAD_TIMEOUT_MS = 300_000;
+/**
+ * How long the download may go without receiving a byte.
+ *
+ * This was a budget for the whole transfer, which is not the same thing: five
+ * minutes is a 150 MB image at 500 KB/s, so a slow but perfectly healthy
+ * connection was aborted near the end of it, the partial file thrown away and
+ * nothing retried. A download making steady progress has nothing wrong with it
+ * however long it takes. What is worth giving up on is silence.
+ */
+const DOWNLOAD_STALL_TIMEOUT_MS = 60_000;
+
+/** A connection that drops is worth asking again; a status code is an answer. */
+const DOWNLOAD_ATTEMPTS = 3;
+const RETRY_BACKOFF_MS = 1_000;
+
+/**
+ * The cap for tag resolution and the manifest.
+ *
+ * These are small requests that run before the progress line exists, so a hung
+ * connection to the release host stalled the whole walk with nothing on screen
+ * to say what it was waiting for. Unlike the image, they are bounded by total
+ * time: there is no such thing as one of them legitimately taking a minute.
+ */
+const METADATA_TIMEOUT_MS = 15_000;
+
+/**
+ * The oldest macOS the app will start on.
+ *
+ * This is the `LSMinimumSystemVersion` of the shipped bundle, which comes from
+ * Electron and not from the desktop repo's electron-builder.yml -- that sets no
+ * `minimumSystemVersion`, so the floor moves on its own the next time the app
+ * takes an Electron major. It cannot be read out of a build that has not been
+ * downloaded yet, so it is duplicated here and has to be changed with it.
+ * Verified against release/mac-arm64/PreMan.app and node_modules/electron/dist
+ * on Electron 38, both of which say 12.0.
+ */
+const MIN_MACOS_VERSION = "12.0";
 
 /**
  * Where the desktop app looks for a session the CLI just established.
@@ -260,7 +304,13 @@ export async function openDesktopSignedIn(
     return { state: "opened-already-running", handoff: handoff.state };
   }
 
-  launch(destination);
+  // An injected launch returns whatever the test wants it to, so only an
+  // explicit failure counts as one.
+  const launched = launch(destination);
+  if (launched?.ok === false) {
+    reportLaunchFailure(destination, launched.detail);
+    return { state: "launch-failed", detail: launched.detail, handoff: handoff.state };
+  }
   if (handoff.state !== "written") return { state: "opened", handoff: handoff.state };
 
   if (wasRunning && !restarted) {
@@ -285,11 +335,40 @@ const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 // The bundle path rather than the name: `open -a PreMan` asks LaunchServices,
 // which may well pick a different copy than the one just installed.
-const defaultLaunch = (destination) =>
-  spawn("open", ["-a", installedAppPath(destination)], {
-    stdio: "ignore",
-    detached: true,
-  }).unref();
+//
+// Waited on, and its exit status read. A detached spawn with its stdio ignored
+// reported a Gatekeeper refusal, a damaged bundle and a successful launch
+// identically, so the walk's closing line told people to sign in to a window
+// that was never going to appear. `open` returns once LaunchServices has
+// accepted the launch rather than once the app is up, so this does not wait for
+// a cold Electron start.
+const defaultLaunch = (destination) => {
+  const opened = spawnSync("open", ["-a", installedAppPath(destination)], { encoding: "utf8" });
+  if (opened.status === 0) return { ok: true };
+  return {
+    ok: false,
+    detail:
+      String(opened.stderr || opened.error?.message || `open exited ${opened.status}`).trim() ||
+      "open reported no reason",
+  };
+};
+
+/**
+ * Say that a launch failed, here rather than in the caller.
+ *
+ * Every other outcome is phrased by whoever asked for it, which is the right
+ * split for results a caller can choose between. A launch that did not happen
+ * is not one of those: the failure is invisible unless it is reported where it
+ * was found, and what to do about it belongs to Gatekeeper rather than to the
+ * flow that happened to be running.
+ */
+function reportLaunchFailure(destination, detail) {
+  process.stdout.write(
+    `Could not open ${installedAppPath(destination)}: ${detail}\n` +
+      `  macOS may be refusing the bundle. Open it once from Finder -- right-click PreMan,\n` +
+      `  then Open -- or reinstall it with: preman install-desktop --force\n`
+  );
+}
 
 /**
  * Open a Playground session URL in PreMan.app on macOS when it is installed.
@@ -299,11 +378,15 @@ export function openPlayground(url) {
   const target = String(url || "").trim();
   if (!target) return "none";
   const app = path.join("/Applications", APP_NAME);
-  if (process.platform === "darwin" && existsSync(app)) {
-    spawn("open", ["-a", "PreMan", target], { stdio: "ignore", detached: true }).unref();
-    return "desktop";
-  }
-  return "web";
+  if (process.platform !== "darwin" || !existsSync(app)) return "web";
+  // The bundle path, and waited on: the app being present says nothing about it
+  // being openable, and a detached spawn whose stdio was ignored could not tell
+  // a quarantined or damaged copy from a successful handoff. A failed spawn also
+  // arrives as an asynchronous 'error' event, which with no listener on it takes
+  // the whole process down.
+  const opened = spawnSync("open", ["-a", app, target], { encoding: "utf8" });
+  if (opened.status === 0) return "desktop";
+  return "app-failed";
 }
 
 export function printPlayground(url) {
@@ -313,6 +396,13 @@ export function printPlayground(url) {
   process.stdout.write(`Watch it: ${target}\n`);
   if (where === "desktop") {
     process.stdout.write("Opened in PreMan desktop\n");
+  } else if (where === "app-failed") {
+    // Handing the URL to the browser is the fallback, and it was a silent one:
+    // nothing said the app had been tried and refused, so a link that opened
+    // nowhere read as the CLI having printed a URL for no reason.
+    process.stdout.write(
+      "PreMan desktop would not open it, so nothing was opened. Use the link above in a browser.\n"
+    );
   }
 }
 
@@ -339,21 +429,86 @@ export function versionFromTag(tag) {
   return String(tag || "").replace(/^v/i, "");
 }
 
-export function detectArch() {
-  const machine = os.machine ? os.machine() : os.arch();
-  if (machine === "arm64" || machine === "aarch64") return "arm64";
-  if (machine === "x86_64" || machine === "x64") return "x64";
-  // Rosetta reports x86_64 for the Node binary itself, so ask sysctl whether the
-  // hardware is actually Apple silicon before handing over an Intel build.
-  const probe = spawnSync("sysctl", ["-n", "hw.optional.arm64"], { encoding: "utf8" });
-  if (probe.status === 0 && probe.stdout.trim() === "1") return "arm64";
-  return "x64";
+/**
+ * Whether a sysctl this machine may not have answers yes.
+ *
+ * `stdout` is null when the binary could not be spawned at all, which is what
+ * made reading it a crash rather than the fallback it was written to be.
+ */
+function sysctlIsOne(key) {
+  const probe = spawnSync("sysctl", ["-n", key], { encoding: "utf8" });
+  return probe.status === 0 && String(probe.stdout || "").trim() === "1";
+}
+
+/**
+ * Which build this machine should be given.
+ *
+ * The reported architecture cannot have the last word on macOS. Rosetta runs
+ * the Node binary translated, so `os.machine()` says `x86_64` on an Apple
+ * silicon Mac whenever the CLI is started from an Intel node or an Intel
+ * terminal -- and that is exactly the machine that must not be handed the Intel
+ * app, because it would run it translated and then keep it: electron-updater
+ * follows the architecture the app was installed as, so the wrong one is not
+ * something a later update corrects. Returning on the reported value first
+ * meant the probe written for that case could never run.
+ *
+ * `sysctl.proc_translated` is the process being translated and
+ * `hw.optional.arm64` the hardware under it; asking both covers a translated
+ * process whichever one of them Rosetta chooses to answer. Neither exists on an
+ * Intel Mac and `sysctl` itself does not exist elsewhere, so a probe that
+ * errors or prints something unexpected leaves the reported value standing.
+ */
+export function detectArch({
+  machine = os.machine ? os.machine() : os.arch(),
+  platform = process.platform,
+  // Injected so the translated case can be exercised on a machine that is not
+  // being translated, which is every machine these tests run on.
+  sysctl = sysctlIsOne,
+} = {}) {
+  const reported = machine === "arm64" || machine === "aarch64" ? "arm64" : "x64";
+  if (reported === "arm64" || platform !== "darwin") return reported;
+  if (sysctl("sysctl.proc_translated") || sysctl("hw.optional.arm64")) return "arm64";
+  return reported;
+}
+
+/**
+ * The running macOS version when it is below what the app needs, else "".
+ *
+ * `sw_vers` rather than `os.release()`, which reports the Darwin kernel version
+ * and would need a mapping table kept up to date for no benefit. A probe that
+ * cannot answer is not a reason to refuse an install, so an unreadable version
+ * goes ahead and lets the app speak for itself.
+ */
+export function macosProductVersion() {
+  const probe = spawnSync("sw_vers", ["-productVersion"], { encoding: "utf8" });
+  if (probe.status !== 0) return "";
+  return String(probe.stdout || "").trim();
+}
+
+export function macosBelowMinimum(probe = macosProductVersion) {
+  const running = probe();
+  if (!running) return "";
+  return versionBelow(running, MIN_MACOS_VERSION) ? running : "";
+}
+
+/** Field by field and numeric: "11.7.10" is below "12.0", "26.5" is not. */
+export function versionBelow(version, minimum) {
+  const fields = (value) => String(value).split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const left = fields(version);
+  const right = fields(minimum);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const a = left[i] ?? 0;
+    const b = right[i] ?? 0;
+    if (a !== b) return a < b;
+  }
+  return false;
 }
 
 async function fetchLatestRelease() {
   try {
     const resp = await fetch(RELEASE_API, {
       headers: { Accept: "application/vnd.github+json", "User-Agent": "premanmcp-cli" },
+      signal: AbortSignal.timeout(METADATA_TIMEOUT_MS),
     });
     if (!resp.ok) return null;
     return await resp.json();
@@ -384,6 +539,7 @@ async function resolveReleaseTag(arch) {
       method: "HEAD",
       redirect: "manual",
       headers: { "User-Agent": "premanmcp-cli" },
+      signal: AbortSignal.timeout(METADATA_TIMEOUT_MS),
     });
     return tagFromRedirect(resp.headers.get("location"));
   } catch {
@@ -423,15 +579,26 @@ export function parseMacManifest(text, arch) {
 }
 
 async function expectedDigest(arch, tag = null) {
+  let resp;
   try {
-    const resp = await fetch(manifestUrl(tag), {
+    resp = await fetch(manifestUrl(tag), {
       headers: { "User-Agent": "premanmcp-cli" },
+      signal: AbortSignal.timeout(METADATA_TIMEOUT_MS),
     });
-    if (!resp.ok) return null;
-    return parseMacManifest(await resp.text(), arch);
-  } catch {
-    return null;
+  } catch (err) {
+    return { state: "unreachable", detail: err?.message || "the request failed" };
   }
+  if (!resp.ok) return { state: "unreachable", detail: `HTTP ${resp.status}` };
+  let digest;
+  try {
+    digest = parseMacManifest(await resp.text(), arch);
+  } catch (err) {
+    return { state: "unreachable", detail: err?.message || "the manifest could not be read" };
+  }
+  // A manifest that reads fine but carries no entry for this architecture is
+  // the release's own omission rather than anything to do with the transport,
+  // and the two are not answered the same way.
+  return digest ? { state: "ok", digest } : { state: "unpublished" };
 }
 
 const BYTES_PER_MB = 1024 * 1024;
@@ -470,33 +637,111 @@ export function progressLine() {
   return { tick, clear };
 }
 
-export async function download(url, destination, onProgress) {
+/** How much of a partial download survived the connection dropping. */
+function partialSize(filePath) {
+  try {
+    return statSync(filePath).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * How large the file is altogether, which on a resumed request `content-length`
+ * does not say: that describes the remainder being sent.
+ */
+function totalBytes(resp, from) {
+  const whole = resp.headers.get("content-range")?.match(/\/(\d+)\s*$/)?.[1];
+  if (whole) return Number(whole);
+  const length = Number(resp.headers.get("content-length")) || 0;
+  return length ? length + from : 0;
+}
+
+/**
+ * One attempt at the image, written to disk as it arrives.
+ *
+ * The body used to be collected into an array of chunks and concatenated, which
+ * asks a small machine for the whole 150 MB twice over at the moment it
+ * finishes. Streaming it also means an interrupted transfer leaves the bytes it
+ * did get where the next attempt can continue from them.
+ *
+ * A resume is only trusted on a 206. A server that ignores the range header
+ * answers 200 with the whole file, and appending that to what is already on
+ * disk builds an image nothing but the checksum would catch.
+ */
+async function downloadOnce(url, destination, onProgress, offset) {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+  let timer = null;
+  const stall = () => {
+    clearTimeout(timer);
+    timer = setTimeout(
+      () => controller.abort(new Error(`no data for ${DOWNLOAD_STALL_TIMEOUT_MS / 1000}s`)),
+      DOWNLOAD_STALL_TIMEOUT_MS
+    );
+  };
+  const headers = { "User-Agent": "premanmcp-cli" };
+  if (offset > 0) headers.Range = `bytes=${offset}-`;
+  // Started before the fetch, so a connection that never answers is bounded by
+  // the same rule as one that goes quiet halfway.
+  stall();
   try {
-    const resp = await fetch(url, { signal: controller.signal, redirect: "follow" });
-    if (!resp.ok) throw new Error(`download failed: ${resp.status} ${url}`);
-    // 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 resp = await fetch(url, { signal: controller.signal, redirect: "follow", headers });
+    if (!resp.ok) {
+      const error = new Error(`download failed: ${resp.status} ${url}`);
+      // A status is an answer rather than a dropped connection, so asking again
+      // gets the same one -- and 404 in particular is what the caller reads to
+      // fall back from a pinned asset to the version-less alias.
+      error.fatal = true;
+      throw error;
     }
-    const buffer = Buffer.concat(chunks);
-    writeFileSync(destination, buffer);
-    return buffer.length;
+    const resumed = offset > 0 && resp.status === 206;
+    const file = createWriteStream(destination, { flags: resumed ? "a" : "w" });
+    let received = resumed ? offset : 0;
+    const total = totalBytes(resp, received);
+    try {
+      for await (const chunk of resp.body) {
+        if (!file.write(chunk)) await once(file, "drain");
+        received += chunk.length;
+        stall();
+        onProgress?.(received, total);
+      }
+      file.end();
+      await finished(file);
+    } catch (err) {
+      file.destroy();
+      throw err;
+    }
+    return received;
   } finally {
     clearTimeout(timer);
   }
 }
 
+/**
+ * Fetch `url` to `destination`, retrying a connection that drops.
+ *
+ * A transfer that died three quarters of the way through a 150 MB image used to
+ * end the install, which is the most expensive possible moment to give up: the
+ * bytes were already on disk and the release had already been resolved. So the
+ * attempt is repeated, resuming from the partial file where the server allows
+ * it, and the retry is announced because the progress line otherwise appears to
+ * jump backwards on its own.
+ */
+export async function download(url, destination, onProgress) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await downloadOnce(url, destination, onProgress, attempt === 1 ? 0 : partialSize(destination));
+    } catch (err) {
+      if (err?.fatal || attempt >= DOWNLOAD_ATTEMPTS) throw err;
+      process.stdout.write(
+        `\n  download interrupted (${err?.message || "connection lost"}); ` +
+          `attempt ${attempt + 1} of ${DOWNLOAD_ATTEMPTS}\n`
+      );
+      await defaultSleep(RETRY_BACKOFF_MS * attempt);
+    }
+  }
+}
+
 function sha512Base64(filePath) {
   return createHash("sha512").update(readFileSync(filePath)).digest("base64");
 }
@@ -543,13 +788,211 @@ function appInsideVolume(volume) {
   return bundle ? path.join(volume, bundle) : null;
 }
 
-export async function installDesktopCommand(commandArgs = [], { onInstalled } = {}) {
+/**
+ * The copy already on this machine, wherever it ended up.
+ *
+ * Two places rather than one, because an install lands in ~/Applications when
+ * /Applications cannot be written to, and a later run that only looked in
+ * /Applications would not find it: it would fetch the same release again every
+ * time it ran, and install a second copy beside the first.
+ */
+function existingInstall(requested) {
+  const candidates = requested
+    ? [requested]
+    : ["/Applications", path.join(os.homedir(), "Applications")];
+  for (const dir of candidates) {
+    const version = installedDesktopVersion(dir);
+    if (version) return { destination: dir, version };
+  }
+  return { destination: requested || "/Applications", version: "" };
+}
+
+function writableDirectory(dir) {
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where this install can actually write.
+ *
+ * /Applications belongs to root:admin, so an unprivileged account -- which is
+ * every account on plenty of MDM-enrolled Macs -- cannot write to it, and there
+ * was no fallback: the install resolved a release, downloaded 150 MB, attached
+ * the image and only then failed, on the copy. ~/Applications is a real
+ * LaunchServices location that needs no password, so it is the second choice,
+ * and the caller says where the app went because nobody thinks to look there.
+ *
+ * An explicit --dest is never second-guessed. The suite passes one to keep
+ * installs off a developer's own /Applications, and quietly installing
+ * somewhere else instead would defeat the point of it.
+ */
+function installDestination(requested, existing) {
+  if (requested) {
+    try {
+      mkdirSync(requested, { recursive: true });
+    } catch {
+      // Reported by the check below, which says the same thing better.
+    }
+    if (!writableDirectory(requested)) {
+      throw new Error(`cannot write to ${requested}. Nothing was downloaded.`);
+    }
+    return { destination: requested, fallbackFrom: null };
+  }
+  // An update goes back to wherever the app already is, or a copy installed in
+  // the fallback directory gets shadowed by a second one in /Applications.
+  if (existing.version && writableDirectory(existing.destination)) {
+    return { destination: existing.destination, fallbackFrom: null };
+  }
+  if (writableDirectory("/Applications")) {
+    return { destination: "/Applications", fallbackFrom: null };
+  }
+  const home = path.join(os.homedir(), "Applications");
+  try {
+    mkdirSync(home, { recursive: true });
+  } catch {
+    // Same as above: the writability check is the one worth reporting.
+  }
+  if (!writableDirectory(home)) {
+    throw new Error(
+      `neither /Applications nor ${home} can be written to by this account. ` +
+        `Nothing was downloaded. Run this from an account that can install ` +
+        `applications, or pass --dest with a directory you own.`
+    );
+  }
+  return { destination: home, fallbackFrom: "/Applications" };
+}
+
+/**
+ * Refuse an image that cannot be shown to be the one that was published.
+ *
+ * A mismatch has always been fatal and stays that way: the bytes are not the
+ * release, and nothing about that improves by installing them. What changed is
+ * the missing case, which used to print one line and carry on. The manifest is
+ * the only integrity signal there is without our own signing infrastructure, so
+ * failing open means a substituted image, or a truncated one from a proxy that
+ * served its error page with a 200, installs exactly as quietly as a good
+ * download. Every release publishes latest-mac.yml beside the image, and an
+ * install pinned to a tag reads both out of the same release -- so a checksum
+ * that is missing there is a broken release rather than a normal condition.
+ * `--allow-unverified` is how someone says otherwise, and it is loud about it.
+ *
+ * The two cases are worded apart deliberately. "No checksum was published" and
+ * "the checksum did not match" are a release problem and a compromised download
+ * respectively, and they are not the same conversation to have with anyone.
+ */
+function verifyDownload(dmgPath, bytes, expected, { arch, allowUnverified }) {
+  if (expected?.state === "ok") {
+    const digest = expected.digest;
+    if (digest.size && digest.size !== bytes) {
+      throw new Error(
+        `size mismatch: downloaded ${bytes} bytes but the release manifest ` +
+          `records ${digest.size} for ${digest.asset}. Nothing was installed.`
+      );
+    }
+    if (sha512Base64(dmgPath) !== digest.sha512) {
+      throw new Error(
+        "digest mismatch: the downloaded disk image does not match the checksum " +
+          "published with the release. Nothing was installed."
+      );
+    }
+    process.stdout.write(`  checksum verified against ${digest.asset}\n`);
+    return digest;
+  }
+  const why =
+    expected?.state === "unreachable"
+      ? `the checksum published with this release could not be read (${expected.detail})`
+      : `this release publishes no checksum for the ${arch} disk image`;
+  if (!allowUnverified) {
+    throw new Error(
+      `unverified download: ${why}. The image was not installed, because an ` +
+        `image that cannot be checked against the release is not known to be ` +
+        `the release. Try again, or pass --allow-unverified to install it anyway.`
+    );
+  }
+  process.stdout.write(
+    `  WARNING: ${why}.\n` +
+      `  --allow-unverified was passed, so PreMan is being installed from an image that\n` +
+      `  was never checked against a published checksum.\n`
+  );
+  return null;
+}
+
+/**
+ * Does this look like something that will launch?
+ *
+ * A bundle is a directory, so a copy that ran out of disk or was interrupted
+ * leaves one behind that exists, satisfies every check this file used to make,
+ * and cannot start. Contents/MacOS is what LaunchServices runs, which makes it
+ * the one thing whose absence means the bundle certainly will not open.
+ *
+ * Info.plist is deliberately not required as well. Its only reader here is the
+ * installed-version check, which already falls back to the manifest when it
+ * cannot parse one, so insisting on it would turn something this command
+ * recovers from into a refusal to install.
+ */
+function looksLikeAppBundle(bundle) {
+  return existsSync(path.join(bundle, "Contents", "MacOS"));
+}
+
+/**
+ * Put the new bundle in place without taking the old one out first.
+ *
+ * `rmSync` and then `cp -R` deleted the working copy before the replacement
+ * existed, and the copy is the step most likely not to finish: a full disk, a
+ * Ctrl-C somewhere in the ninety seconds it takes, a directory that turns out
+ * to want a password. What that left behind was no PreMan at all, which is
+ * worse than the version the customer was updating away from. So the copy lands
+ * beside the target under a name of its own, is checked, and is only moved into
+ * place once it is whole -- and the bundle it replaces is not removed until
+ * after that move has succeeded.
+ */
+function installBundle(source, target) {
+  // Hidden, and outside the .app extension: a half-copied PreMan.app in
+  // /Applications is something Finder offers to open and LaunchServices
+  // registers, and it exists for as long as the copy takes.
+  const staging = path.join(path.dirname(target), `.${APP_NAME}.installing`);
+  const replaced = path.join(path.dirname(target), `.${APP_NAME}.replaced`);
+  rmSync(staging, { recursive: true, force: true });
+  rmSync(replaced, { recursive: true, force: true });
+  try {
+    run("cp", ["-R", source, staging]);
+    chmodSync(staging, 0o755);
+    if (!looksLikeAppBundle(staging)) {
+      throw new Error(
+        `the copy of ${path.basename(source)} has no Contents/MacOS in it, so it ` +
+          `would not launch. Nothing was installed.`
+      );
+    }
+    if (existsSync(target)) renameSync(target, replaced);
+    try {
+      renameSync(staging, target);
+    } catch (err) {
+      // Both names are in the same directory, so this is not a cross-device
+      // move; whatever it is, the copy that was working goes back.
+      if (existsSync(replaced) && !existsSync(target)) renameSync(replaced, target);
+      throw err;
+    }
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+    rmSync(replaced, { recursive: true, force: true });
+  }
+}
+
+export async function installDesktopCommand(
+  commandArgs = [],
+  { onInstalled, macosVersion = macosProductVersion } = {}
+) {
   const args = makeArgs(commandArgs);
 
   if (process.platform !== "darwin" && !args.has("--print-url")) {
     process.stdout.write(
       `The PreMan desktop app is macOS-only right now.\n` +
-        `Downloads for other platforms: ${RELEASES_BASE}/latest\n`
+        `Downloads for other platforms: ${RELEASES_BASE}/latest\n` +
+        `Nothing was downloaded here: that page is the whole of the install on this platform.\n`
     );
     return { state: "unsupported", platform: process.platform };
   }
@@ -566,24 +1009,75 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
     return { state: "printed", url: alias, arch };
   }
 
+  const tooOld = macosBelowMinimum(macosVersion);
+  if (tooOld) {
+    // Before the download rather than after it. An older Mac used to fetch the
+    // whole image, install it, and then be told by LaunchServices that the
+    // application could not be opened -- a message about the OS, from the OS,
+    // with nothing in it to say that the version floor was the reason or that
+    // the 150 MB had been spent on something that was never going to run.
+    process.stdout.write(
+      `The PreMan desktop app requires macOS ${MIN_MACOS_VERSION} or later.\n` +
+        `This Mac is running macOS ${tooOld}, so nothing was downloaded.\n` +
+        `Update macOS and run preman install-desktop again.\n`
+    );
+    return { state: "unsupported-macos", macos: tooOld, required: MIN_MACOS_VERSION, arch };
+  }
+
+  // Read before anything is resolved, so whether there is work to do does not
+  // depend on the release host being reachable.
+  const existing = existingInstall(args.value("--dest", ""));
+  const installed = existing.version;
+
   // Resolved once. Everything below is pinned to this tag, so the version
   // reported, the image downloaded and the checksum verified against it all
   // describe the same release even if another ships while this runs.
   const tag = await resolveReleaseTag(arch);
   const url = dmgUrl(arch, tag);
   const version = tag ? versionFromTag(tag) : "latest";
-  const destination = args.value("--dest", "/Applications");
 
-  const installed = installedDesktopVersion(destination);
-  if (tag && installed && installed === version && !args.has("--force")) {
-    // Re-fetching 100 MB to arrive at the bytes already on disk is the most
-    // literal form of the "it downloads the update again" complaint, and it is
-    // what this command did every time it was run.
+  if (installed && !args.has("--force")) {
+    if (tag && installed === version) {
+      // Re-fetching 100 MB to arrive at the bytes already on disk is the most
+      // literal form of the "it downloads the update again" complaint, and it is
+      // what this command did every time it was run.
+      process.stdout.write(
+        `PreMan ${installed} is already installed and is the latest release.\n` +
+          `Nothing to do. Use --force to reinstall.\n`
+      );
+      return {
+        state: "current",
+        version: installed,
+        arch,
+        path: installedAppPath(existing.destination),
+      };
+    }
+    if (!tag) {
+      // This whole branch used to be gated on having a tag, so a release host
+      // that could not be reached turned "you already have it" into an error --
+      // on the one question here whose answer is entirely on the local disk.
+      process.stdout.write(
+        `PreMan ${installed} is installed at ${installedAppPath(existing.destination)}.\n` +
+          `The release server could not be reached, so whether a newer build exists is\n` +
+          `unknown and nothing was changed. Use --force to reinstall.\n`
+      );
+      return {
+        state: "current",
+        version: installed,
+        arch,
+        path: installedAppPath(existing.destination),
+        latestKnown: false,
+      };
+    }
+  }
+
+  const { destination, fallbackFrom } = installDestination(args.value("--dest", ""), existing);
+  if (fallbackFrom) {
     process.stdout.write(
-      `PreMan ${installed} is already installed and is the latest release.\n` +
-        `Nothing to do. Use --force to reinstall.\n`
+      `${fallbackFrom} cannot be written to by this account, which is normal on a Mac managed\n` +
+        `by an organisation. PreMan is being installed to ${destination} instead --\n` +
+        `look for it there rather than in ${fallbackFrom}. It launches the same way.\n`
     );
-    return { state: "current", version: installed, arch, path: installedAppPath(destination) };
   }
 
   if (installed === version) {
@@ -624,24 +1118,10 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
 
     // Read from the same place the image came from, pinned or not, so the two
     // can never describe different releases.
-    const expected = await expectedDigest(arch, pinned);
-    if (expected) {
-      if (expected.size && expected.size !== bytes) {
-        throw new Error(
-          `size mismatch: downloaded ${bytes} bytes but the release manifest ` +
-            `records ${expected.size} for ${expected.asset}. Nothing was installed.`
-        );
-      }
-      if (sha512Base64(dmgPath) !== expected.sha512) {
-        throw new Error(
-          "digest mismatch: the downloaded disk image does not match the checksum " +
-            "published with the release. Nothing was installed."
-        );
-      }
-      process.stdout.write(`  checksum verified against ${expected.asset}\n`);
-    } else {
-      process.stdout.write("  checksum unavailable for this release; skipping verification\n");
-    }
+    const verified = verifyDownload(dmgPath, bytes, await expectedDigest(arch, pinned), {
+      arch,
+      allowUnverified: args.has("--allow-unverified"),
+    });
 
     mounted = attachDiskImage(dmgPath, path.join(workDir, "mnt"));
 
@@ -650,14 +1130,12 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
       throw new Error(`no application bundle found inside the disk image at ${mounted}`);
     }
     const target = path.join(destination, APP_NAME);
-    if (existsSync(target)) rmSync(target, { recursive: true, force: true });
-    run("cp", ["-R", source, target]);
-    chmodSync(target, 0o755);
+    installBundle(source, target);
 
     // The manifest's version describes bytes whose size and digest were just
     // checked against it, which makes it a better answer than the tag resolved
     // before any of this ran -- and the only honest one on the alias fallback.
-    const installedVersion = expected?.version || installedDesktopVersion(destination) || version;
+    const installedVersion = verified?.version || installedDesktopVersion(destination) || version;
     const result = { state: "installed", version: installedVersion, arch, path: target };
     process.stdout.write(`\nInstalled PreMan ${installedVersion} to ${target}\n\n`);
     onInstalled?.(result);