premanmcp 0.16.3 → 1.0.0

package/bin/desktop.js

@@ -1,10 +1,30 @@
 /**
  * `preman install-desktop` — download and install the PreMan desktop app.
  *
- * Version-less asset names are used on purpose: `/releases/latest/download/
- * PreMan-mac-arm64.dmg` keeps working after every release, where a versioned URL
- * would 404 the day the next build ships. The live tag is read from the GitHub
- * API only to report what was installed.
+ * ## One release, resolved once
+ *
+ * An install reads three things from the release: the version to report, the
+ * disk image, and the checksum to verify it against. Each used to be a separate
+ * request to `/releases/latest/…`, which is three independent answers to "what
+ * is the newest release" taken minutes apart, across a 100 MB download. Desktop
+ * ships several times a day, so those answers disagreed regularly, and every way
+ * they could disagree was bad:
+ *
+ *  * The version was read *before* the download, so a release landing mid-fetch
+ *    meant reporting `Installed PreMan 0.3.170` over a copy of 0.3.172 — the
+ *    install genuinely was not the version it claimed.
+ *  * The manifest was read *after*, so the same race made the checksum belong to
+ *    a different build than the image. That is a hard `size mismatch`, and the
+ *    100 MB the user just waited for is discarded and fetched again.
+ *  * `electron-updater` then found a newer build on first launch and downloaded
+ *    a third copy, this time a 97 MB ZIP.
+ *
+ * So the tag is resolved once, up front, and every later request is pinned to
+ * it. A pinned install is reproducible, its reported version is the one on disk,
+ * and its checksum describes the bytes it actually fetched. Version-less aliases
+ * remain the fallback for when the tag cannot be resolved, which is the only
+ * reason they still exist here: they are what keeps a URL valid across releases,
+ * at the cost of not saying which release it is.
  *
  * Arch detection is trivial here in a way it is not on the website: `uname -m`
  * is authoritative, so there is no need for the WebGL guessing the download page
@@ -32,6 +52,7 @@ export const DESKTOP_HELP = `
 Install-desktop options:
   --arch <arm64|x64>    Override architecture detection
   --dest <dir>          Install directory. Defaults to /Applications
+  --force               Reinstall even when the latest release is already installed
   --keep-dmg            Leave the downloaded disk image in place
   --print-url           Print the resolved download URL and exit
 `;
@@ -57,6 +78,27 @@ export function installedAppPath(destination = "/Applications") {
   return path.join(destination, APP_NAME);
 }
 
+/**
+ * `CFBundleShortVersionString` of the installed app, or `""`.
+ *
+ * Lives here rather than in link.js, which is where it started, because the
+ * installer needs it too -- to answer "is this already the release I am about to
+ * download" -- and link.js already imports this module, so the dependency only
+ * points one way from here.
+ */
+export function installedDesktopVersion(destination = "/Applications") {
+  try {
+    const plist = path.join(installedAppPath(destination), "Contents", "Info.plist");
+    const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(
+      readFileSync(plist, "utf8")
+    );
+    return match ? match[1].trim() : "";
+  } catch {
+    // Not installed, or a bundle we cannot read.
+    return "";
+  }
+}
+
 export function desktopAppInstalled(destination = "/Applications") {
   return process.platform === "darwin" && existsSync(installedAppPath(destination));
 }
@@ -174,10 +216,29 @@ export function printPlayground(url) {
   }
 }
 
-export function dmgUrl(arch) {
+/**
+ * Where to fetch the disk image for `arch`.
+ *
+ * With a tag, the release's own versioned asset -- one exact build, which cannot
+ * become a different one between resolving it and finishing the download.
+ * Without one, the version-less alias, which always resolves to something but
+ * will not say what.
+ */
+export function dmgUrl(arch, tag = null) {
+  if (tag) return `${RELEASES_BASE}/download/${tag}/PreMan-${versionFromTag(tag)}-${arch}.dmg`;
   return `${RELEASES_BASE}/latest/download/PreMan-mac-${arch}.dmg`;
 }
 
+/** Where to fetch the update manifest, pinned the same way. */
+export function manifestUrl(tag = null) {
+  if (tag) return `${RELEASES_BASE}/download/${tag}/latest-mac.yml`;
+  return `${RELEASES_BASE}/latest/download/latest-mac.yml`;
+}
+
+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";
@@ -201,16 +262,46 @@ async function fetchLatestRelease() {
   }
 }
 
+/**
+ * The tag `/releases/latest` currently points at, read out of its redirect.
+ *
+ * A second way to ask, because the first one is rate limited: the GitHub API
+ * allows 60 unauthenticated calls an hour per address, which a shared office or
+ * a CI runner can exhaust without doing anything unusual. Downloads are not
+ * limited, and the alias redirects to the release it resolved -- so asking for
+ * the alias and declining to follow the redirect yields the same tag the
+ * download itself would have used, which is exactly the one worth pinning.
+ */
+export function tagFromRedirect(location) {
+  return String(location || "").match(/\/releases\/download\/([^/]+)\//)?.[1] ?? null;
+}
+
+async function resolveReleaseTag(arch) {
+  const release = await fetchLatestRelease();
+  if (release?.tag_name) return String(release.tag_name);
+  try {
+    const resp = await fetch(dmgUrl(arch), {
+      method: "HEAD",
+      redirect: "manual",
+      headers: { "User-Agent": "premanmcp-cli" },
+    });
+    return tagFromRedirect(resp.headers.get("location"));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The sha512 and size electron-builder published for this architecture's disk
  * image, or null if the manifest could not be read.
  *
  * `latest-mac.yml` is the only integrity signal available without our own signing
  * infrastructure. It keys entries by the *versioned* filename
- * (`PreMan-0.3.79-arm64.dmg`), while we download the version-less alias, so the
- * version has to be read out of the manifest to find the right entry. The alias
- * is a copy of the same artifact, which the size check confirms before the digest
- * is trusted.
+ * (`PreMan-0.3.79-arm64.dmg`), so the version is read out of the manifest to
+ * find the right entry. On a pinned install that version is the tag's, and the
+ * asset named in the manifest is the one that was downloaded; on a fallback
+ * install it describes the alias's twin, which the size check confirms before
+ * the digest is trusted.
  */
 export function parseMacManifest(text, arch) {
   const version = text.match(/^version:\s*(\S+)/m)?.[1];
@@ -231,9 +322,9 @@ export function parseMacManifest(text, arch) {
   return null;
 }
 
-async function expectedDigest(arch) {
+async function expectedDigest(arch, tag = null) {
   try {
-    const resp = await fetch(`${RELEASES_BASE}/latest/download/latest-mac.yml`, {
+    const resp = await fetch(manifestUrl(tag), {
       headers: { "User-Agent": "premanmcp-cli" },
     });
     if (!resp.ok) return null;
@@ -367,18 +458,41 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
   if (!["arm64", "x64"].includes(arch)) {
     throw new Error(`unsupported --arch ${arch}; expected arm64 or x64`);
   }
-  const url = dmgUrl(arch);
-
   if (args.has("--print-url")) {
-    process.stdout.write(`${url}\n`);
-    return { state: "printed", url, arch };
+    // The alias, and no network call: this is asked for by scripts and by people
+    // who want the URL that keeps working, not the one for today's build.
+    const alias = dmgUrl(arch);
+    process.stdout.write(`${alias}\n`);
+    return { state: "printed", url: alias, arch };
   }
 
-  const release = await fetchLatestRelease();
-  const version = String(release?.tag_name || "").replace(/^v/i, "") || "latest";
+  // 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");
 
-  process.stdout.write(`Downloading PreMan ${version} (${arch})…\n`);
+  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.
+    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(destination) };
+  }
+
+  if (installed === version) {
+    process.stdout.write(`Reinstalling PreMan ${version} (${arch})…\n`);
+  } else if (installed) {
+    process.stdout.write(`Replacing PreMan ${installed} with ${version} (${arch})…\n`);
+  } else {
+    process.stdout.write(`Downloading PreMan ${version} (${arch})…\n`);
+  }
   const workDir = mkdtempSync(path.join(os.tmpdir(), "preman-desktop-"));
   const dmgPath = path.join(workDir, `PreMan-mac-${arch}.dmg`);
   let mounted = null;
@@ -386,8 +500,21 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
   try {
     const progress = progressLine();
     let bytes;
+    let pinned = tag;
     try {
-      bytes = await download(url, dmgPath, progress.tick);
+      try {
+        bytes = await download(url, dmgPath, progress.tick);
+      } catch (err) {
+        // Pinning names an asset instead of an alias, so it is the one thing
+        // here that can be wrong about a release rather than merely unlucky --
+        // an older build that predates the versioned artifact, or a rename.
+        // Falling back to the alias costs the guarantees above and is still an
+        // install; failing outright would make this worse than what it replaced.
+        if (!pinned || !/download failed: 404/.test(String(err?.message))) throw err;
+        process.stdout.write(`  ${tag} has no versioned image; using the latest alias\n`);
+        pinned = null;
+        bytes = await download(dmgUrl(arch), dmgPath, progress.tick);
+      }
     } finally {
       // Cleared even when the download throws, or the error prints onto the
       // half-drawn progress line.
@@ -395,7 +522,9 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
     }
     process.stdout.write(`  ${(bytes / BYTES_PER_MB).toFixed(1)} MB\n`);
 
-    const expected = await expectedDigest(arch);
+    // 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(
@@ -425,8 +554,12 @@ export async function installDesktopCommand(commandArgs = [], { onInstalled } =
     run("cp", ["-R", source, target]);
     chmodSync(target, 0o755);
 
-    const result = { state: "installed", version, arch, path: target };
-    process.stdout.write(`\nInstalled ${target}\n\n`);
+    // 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 result = { state: "installed", version: installedVersion, arch, path: target };
+    process.stdout.write(`\nInstalled PreMan ${installedVersion} to ${target}\n\n`);
     onInstalled?.(result);
     return result;
   } finally {

package/bin/integrations.js

@@ -265,9 +265,15 @@ 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.
   const started = await callBackendJson(args, "POST", "/integrations/github/app/install", {
     token,
-    json: {},
+    json: { return_to: "desktop" },
   });
   assertOk(started, "start GitHub install");
 

package/bin/link.js

@@ -14,12 +14,11 @@
  * a `git push` is exactly the behaviour that gets a tool uninstalled.
  */
 
-import { readFileSync } from "node:fs";
-import path from "node:path";
-
-import { desktopAppInstalled, installedAppPath } from "./desktop.js";
+import { desktopAppInstalled, installedDesktopVersion } from "./desktop.js";
 import { DEFAULT_FRONTEND, frontendUrl } from "./shared.js";
 
+export { installedDesktopVersion };
+
 const DIM = "\u001b[2m";
 const RESET = "\u001b[0m";
 
@@ -82,20 +81,6 @@ export function compareVersions(a, b) {
   return 0;
 }
 
-/** CFBundleShortVersionString of the installed app, or "". */
-export function installedDesktopVersion(destination = "/Applications") {
-  try {
-    const plist = path.join(installedAppPath(destination), "Contents", "Info.plist");
-    const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(
-      readFileSync(plist, "utf8")
-    );
-    return match ? match[1].trim() : "";
-  } catch {
-    // Not installed, or a bundle we cannot read. Either way: not routable.
-    return "";
-  }
-}
-
 export function desktopSupportsRouting(destination = "/Applications") {
   const version = installedDesktopVersion(destination);
   return Boolean(version) && compareVersions(version, MIN_ROUTE_VERSION) >= 0;

package/bin/tests.js

@@ -3,7 +3,7 @@
  *
  * Thin HTTP wrappers over the same `/workbench/generate-tests` routes the
  * dashboard uses. Distinct from `preman test <id>`, which generates + runs
- * scenarios for one endpoint via `POST /mcp/call-tool`.
+ * scenarios for one endpoint via `POST /cli/tests/generate`.
  */
 
 import { callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";

package/bin/verify.js

@@ -243,12 +243,9 @@ async function safeCall(args, method, routePath, options) {
 async function fetchInventory(args, token) {
   const endpoints = [];
   for (let offset = 0; offset < INVENTORY_MAX_ENDPOINTS; offset += INVENTORY_PAGE_SIZE) {
-    const result = await safeCall(args, "POST", "/mcp/call-tool", {
+    const result = await safeCall(args, "GET", "/cli/endpoints", {
       token,
-      json: {
-        tool: "get_endpoints",
-        arguments: { format: "json", limit: INVENTORY_PAGE_SIZE, offset },
-      },
+      query: { limit: INVENTORY_PAGE_SIZE, offset },
     });
     if (!result.ok) {
       return {

package/dist/server.d.ts

@@ -1,2 +1,7 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function createServer(): McpServer;
+/** Transparent stdio -> hosted Streamable HTTP MCP bridge.
+ *
+ * This process deliberately defines no tools or schemas. Initialization,
+ * discovery, notifications, and calls are forwarded byte-for-byte at the JSON-
+ * RPC layer so the Python service remains the sole public contract authority.
+ */
+export {};