premanmcp 1.0.3 → 1.0.5

package/bin/hook.js

@@ -139,6 +139,57 @@ function isGeneratedInvocation(invocation) {
   return invocation === "preman" || /^npm exec -y premanmcp@\S+ --$/.test(invocation);
 }
 
+/**
+ * The release a generated invocation pins, or "" when it does not pin one.
+ *
+ * The bare `preman` form resolves at push time, and `@latest` is whatever we
+ * ship next, so neither can be out of date. Only an explicit version can be.
+ */
+export function pinnedRelease(invocation) {
+  const match = /^npm exec -y premanmcp@(\S+) --$/.exec(String(invocation || "").trim());
+  const version = match ? match[1] : "";
+  return version === "latest" ? "" : version;
+}
+
+/**
+ * Is `left` an earlier release than `right`?
+ *
+ * Anything this cannot read as three numbers compares as not-older, so a
+ * prerelease tag or a mirror's own numbering is left alone rather than being
+ * rewritten on a guess.
+ */
+export function isOlderRelease(left, right) {
+  const parse = (value) => String(value).split(".").map((part) => Number.parseInt(part, 10));
+  const a = parse(left);
+  const b = parse(right);
+  if (a.length !== 3 || b.length !== 3) return false;
+  if ([...a, ...b].some((part) => !Number.isFinite(part))) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index];
+  }
+  return false;
+}
+
+/**
+ * Does this hook run a PreMan older than the one asking?
+ *
+ * A pinned hook keeps working long after it stops being current -- it answers
+ * `help`, it runs `verify`, it just does all of it as the version that wrote
+ * it. Found in the wild: a hook still on 0.13.0 while 1.0.4 was installed,
+ * printing an error message whose formatting had been fixed several releases
+ * earlier, with nothing anywhere to say why.
+ *
+ * Only ever true when we would be moving forward. An older CLI run for some
+ * other reason must not drag a newer hook back with it.
+ */
+export function hookIsBehind(invocation) {
+  if (declaredInvocation()) return false;
+  const pinned = pinnedRelease(invocation);
+  const running = packageVersion();
+  if (!pinned || !running) return false;
+  return isOlderRelease(pinned, running);
+}
+
 function hookBody(invocation) {
   // `exec` is deliberately absent: we want the wrapper to survive the CLI exiting
   // non-zero and still exit 0 itself.
@@ -319,9 +370,11 @@ function rememberHookCheck(cwd, now, fields) {
  * PreMan is running here -- any command, the MCP server starting -- is taken as
  * the moment to check.
  *
- * Deliberately narrow. It only ever rewrites a hook we wrote that no longer
- * answers: an absent hook is not installed behind the user, a foreign hook is
- * not touched, and a hook that works is left on whatever version it pins.
+ * Deliberately narrow. It only ever rewrites a hook we wrote: an absent hook is
+ * not installed behind the user, and a foreign hook is not touched. A working
+ * hook is rewritten only when it pins a release older than the one running --
+ * see `hookIsBehind` -- because "it answers" and "it is the CLI we ship" stopped
+ * being the same question once a pin could outlive several releases.
  */
 export function repairDeadHook({ cwd = process.cwd(), now = Date.now(), force = false } = {}) {
   const remember = (fields) => rememberHookCheck(cwd, now, fields);
@@ -337,11 +390,14 @@ export function repairDeadHook({ cwd = process.cwd(), now = Date.now(), force =
     return remember({ action: "not-a-repository" });
   }
   if (status.state !== "installed") return remember({ action: status.state });
-  if (status.works) return remember({ action: "healthy", invocation: status.invocation });
+  const behind = hookIsBehind(status.invocation);
+  if (status.works && !behind) {
+    return remember({ action: "healthy", invocation: status.invocation });
+  }
 
   const result = installHook(makeArgs([]));
   return remember({
-    action: result.action === "updated" ? "repaired" : result.action,
+    action: result.action === "updated" ? (behind ? "upgraded" : "repaired") : result.action,
     invocation: result.invocation || "",
     replaced: status.invocation,
   });

package/bin/shared.js

@@ -482,16 +482,52 @@ export async function callBackendJson(
  * instead" reached a customer as `410 [object Object]` -- a remedy the response
  * carried and the screen never showed.
  */
+/**
+ * A readable reason for a backend failure, always as a string.
+ *
+ * FastAPI answers a rejected request with an object and a validation error with
+ * an array of them, and every caller interpolates what comes back into a line
+ * somebody reads. The nested cases used to be handed back as they arrived --
+ * `detail.message` being itself an object was returned as an object -- so the
+ * line printed "[object Object]", which is the exact failure this function
+ * exists to prevent, reintroduced one level further down.
+ */
 export function describeFailure(result, fallback = "backend error") {
-  const detail = result?.detail ?? result?.message ?? result?.raw;
-  if (typeof detail === "string" && detail) return detail;
-  if (Array.isArray(detail) && detail.length) {
-    return detail.map((item) => item?.msg || JSON.stringify(item)).join("; ");
+  return readDetail(result?.detail ?? result?.message ?? result?.raw) || fallback;
+}
+
+/** The first thing in `detail` a person could read, however deeply it is wrapped. */
+function readDetail(detail, depth = 0) {
+  if (typeof detail === "string") return detail.trim();
+  if (typeof detail === "number" || typeof detail === "boolean") return String(detail);
+  if (Array.isArray(detail)) {
+    return detail
+      .map((item) => readDetail(item, depth + 1))
+      .filter(Boolean)
+      .join("; ");
   }
   if (detail && typeof detail === "object") {
-    return detail.message || detail.error || detail.code || JSON.stringify(detail);
+    // Bounded, because these arrive from somewhere else and a structure that
+    // refers to itself must not take the CLI down on its way to a skip message.
+    if (depth < 3) {
+      for (const key of ["msg", "message", "detail", "error", "description", "code"]) {
+        const nested = readDetail(detail[key], depth + 1);
+        if (nested) return nested;
+      }
+    }
+    try {
+      const json = JSON.stringify(detail);
+      // An empty object describes nothing. Printing "{}" as the reason a push
+      // was skipped is the same unhelpfulness as "[object Object]" in nicer
+      // punctuation; the caller's fallback at least names the kind of failure.
+      return json === "{}" || json === "[]" ? "" : json;
+    } catch {
+      // Circular, or otherwise not describable. The caller's fallback is better
+      // than throwing from the thing that was explaining a failure.
+      return "";
+    }
   }
-  return fallback;
+  return "";
 }
 
 export function assertOk(result, action) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "test": "npm run build && npm run test:proxy",
     "test:proxy": "node --test scripts/smoke-proxy.mjs",
     "test:connect": "node scripts/smoke-connect.mjs",
-    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-onboard-opening.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs",
+    "test:node": "node --test --test-timeout=90000 scripts/smoke-account.mjs scripts/smoke-cli-entrypoint.mjs scripts/smoke-launcher-config.mjs scripts/smoke-runner.mjs scripts/smoke-repo-config.mjs scripts/smoke-onboard.mjs scripts/smoke-onboard-opening.mjs scripts/smoke-local-detect.mjs scripts/smoke-prepush-hook.mjs scripts/smoke-cli-identity.mjs scripts/smoke-runner-heartbeat.mjs scripts/smoke-verify-prepush.mjs scripts/smoke-push-diff.mjs scripts/smoke-progress-reporter.mjs scripts/smoke-verify-plan.mjs scripts/smoke-install-desktop.mjs scripts/smoke-desktop-session.mjs scripts/smoke-api-tools.mjs scripts/smoke-tests-workbench.mjs scripts/smoke-bin-scope.mjs scripts/smoke-shared-errors.mjs",
     "test:dmg": "node --test --test-timeout=300000 scripts/smoke-install-desktop-volume.mjs"
   },
   "devDependencies": {