@yawlabs/mcph 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `@yawlabs/mcph` are documented here. This project uses [semantic versioning](https://semver.org) and a CI-gated release flow: pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which publishes to npm.
 
+## 0.46.0 — 2026-04-18
+
+- **`mcph upgrade` — show (or run) the command that bumps `@yawlabs/mcph` to the latest version** — `mcph doctor` has surfaced staleness for a while, but the fix step was left to the user. This subcommand turns that prompt into an action: it detects *how* mcph is installed by inspecting `process.argv[1]` (global npm, npx cache, project-local `node_modules`, or a dev checkout), fetches the latest version from the npm registry (3s timeout, graceful offline fallback), and prints the exact command that moves the current install forward. `--run` spawns the upgrade for the global-npm case (whitelisted to `npm install -g @yawlabs/mcph@latest` — never arbitrary input into a shell), refuses with exit 2 on non-global install methods to avoid surprise writes, and exit 3 if the spawned npm invocation fails. `--json` emits `{ current, latest, stale, method, command }` so CI scripts can branch on staleness without parsing prose. `npx -y` installs are a no-op ("restart the MCP client and it will fetch the new version") — the path detection catches the `_npx` staging directory and says so. Exit codes are wired for scripting: 0 up-to-date or offline, 1 stale without `--run` (copy-paste mode), 2 usage/refusal, 3 `--run` failed. Completes the doctor→fix handoff that's been missing since the upgrade-check section landed.
+
 ## 0.45.0 — 2026-04-18
 
 - **Clearer 401/403 errors with token fingerprint + actionable fix link** — When the backend rejects a token (`HTTP 401` revoked/malformed, `HTTP 403` accepted but scope-denied), `fetchConfig` now throws an error that names the offending token by its fingerprint (e.g., `mcp_pat_…abcd`), explains what state the token is in, and points directly at the tokens page with a concrete re-install command. Prior wording was "Invalid MCPH_TOKEN — check your token at mcp.hosting" and "Access denied — your token may have expired" — both too vague to action without pinging support. New wording is structured as three lines: cause, fix URL, and the `mcph install … --token mcp_pat_...` re-install command. Messages surface verbatim through `mcph servers`, the top-level `mcph` runtime, and anywhere else `fetchConfig` is awaited, so every user-facing rejection reads the same way.

package/README.md

@@ -92,6 +92,7 @@ mcph servers [<namespace-filter>] [--json]    # list servers; optional substring
 mcph bundles [list|match] [--json]    # browse curated multi-server bundles (PR review, DevOps incident, etc.)
 mcph reset-learning                   # clear cross-session learning history (~/.mcph/state.json)
 mcph completion <bash|zsh|fish|powershell>   # print shell completion script
+mcph upgrade [--run] [--json]         # show (or execute) the command that bumps @yawlabs/mcph
 mcph compliance <target> [--publish]  # run the compliance suite against an MCP server
 mcph --version                        # print version
 ```

package/dist/index.js

@@ -692,6 +692,7 @@ var SUBCOMMAND_SPEC = [
   { name: "compliance", flags: ["--publish", "--help"] },
   { name: "reset-learning", flags: ["--help"] },
   { name: "completion", positional: ["bash", "zsh", "fish", "powershell"], flags: ["--help"] },
+  { name: "upgrade", flags: ["--run", "--json", "--help"] },
   { name: "help", flags: [] }
 ];
 function parseCompletionArgs(argv) {
@@ -791,6 +792,7 @@ function renderZsh() {
     compliance: "Run the compliance suite against a server",
     "reset-learning": "Clear cross-session learning history",
     completion: "Print a shell completion script",
+    upgrade: "Upgrade @yawlabs/mcph to the latest version",
     help: "Show usage"
   };
   const subcommandList = SUBCOMMAND_SPEC.map((s) => `    '${s.name}:${subcommandDescriptions[s.name] ?? ""}'`).join(
@@ -1456,7 +1458,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.45.0" : "dev";
+var VERSION = true ? "0.46.0" : "dev";
 async function runDoctor(opts = {}) {
   if (opts.json) return runDoctorJson(opts);
   const lines = [];
@@ -4744,7 +4746,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.45.0" : "dev" },
+    { name: "mcph", version: true ? "0.46.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -5225,7 +5227,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.45.0" : "dev" },
+      { name: "mcph", version: true ? "0.46.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -7398,6 +7400,182 @@ function truncateVersion(v) {
   return v.length > 8 ? v.slice(0, 8) : v;
 }
 
+// src/upgrade-cmd.ts
+import { spawn as spawn4 } from "child_process";
+var UPGRADE_USAGE = `Usage: mcph upgrade [--run] [--json]
+
+  Show (or execute) the command to upgrade @yawlabs/mcph to the latest version.
+
+  --run     If this install is global (npm install -g), spawn the upgrade
+            command. No-op for npx installs \u2014 they always fetch the latest.
+  --json    Emit a machine-readable snapshot ({ current, latest, stale,
+            method, command }) instead of prose.`;
+function parseUpgradeArgs(argv) {
+  const opts = {};
+  for (const a of argv) {
+    if (a === "--run") opts.run = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--help" || a === "-h") return { ok: false, error: UPGRADE_USAGE };
+    else return { ok: false, error: `mcph upgrade: unknown argument "${a}"
+
+${UPGRADE_USAGE}` };
+  }
+  return { ok: true, options: opts };
+}
+function detectInstallMethod(argvPath) {
+  if (!argvPath) return "unknown";
+  const normalized = argvPath.replace(/\\/g, "/");
+  if (/\/_npx\//.test(normalized)) return "npx";
+  if (/\/npm\/node_modules\/@yawlabs\/mcph\//.test(normalized)) return "global-npm";
+  if (/\/lib\/node_modules\/@yawlabs\/mcph\//.test(normalized)) return "global-npm";
+  if (/\/AppData\/Roaming\/npm\/node_modules\/@yawlabs\/mcph\//.test(normalized)) return "global-npm";
+  if (/\/node_modules\/@yawlabs\/mcph\//.test(normalized)) return "local-node-modules";
+  if (/\/mcph\/(dist|src)\//.test(normalized)) return "dev-checkout";
+  return "unknown";
+}
+function buildUpgradePlan(input) {
+  const { current, latest, method } = input;
+  const stale = latest !== null && current !== "dev" && compareSemverLocal(current, latest) < 0;
+  let command;
+  switch (method) {
+    case "global-npm":
+      command = "npm install -g @yawlabs/mcph@latest";
+      break;
+    case "npx":
+      command = null;
+      break;
+    case "local-node-modules":
+      command = "npm install @yawlabs/mcph@latest";
+      break;
+    case "dev-checkout":
+      command = "git pull && npm run build";
+      break;
+    default:
+      command = "npm install -g @yawlabs/mcph@latest";
+      break;
+  }
+  return { current, latest, stale, method, command };
+}
+function compareSemverLocal(a, b) {
+  const parse = (s) => {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(s);
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+async function defaultFetchLatest() {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), 3e3);
+  try {
+    const res = await fetch("https://registry.npmjs.org/@yawlabs/mcph/latest", {
+      signal: ac.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function defaultSpawn(cmd, args) {
+  return new Promise((resolve4) => {
+    const child = spawn4(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+    child.on("close", (code) => resolve4(typeof code === "number" ? code : 1));
+    child.on("error", () => resolve4(1));
+  });
+}
+async function runUpgrade(opts = {}) {
+  const write = opts.out ?? ((s) => process.stdout.write(s));
+  const writeErr = opts.err ?? ((s) => process.stderr.write(s));
+  const lines = [];
+  const print = (s = "") => {
+    lines.push(s);
+    write(`${s}
+`);
+  };
+  const printErr = (s) => {
+    lines.push(s);
+    writeErr(`${s}
+`);
+  };
+  const fetcher = opts.fetchLatest ?? defaultFetchLatest;
+  const current = opts.currentVersion ?? readCurrentVersion();
+  const argvPath = opts.argvPath ?? process.argv[1];
+  const method = detectInstallMethod(argvPath);
+  let latest;
+  try {
+    latest = await fetcher();
+  } catch {
+    latest = null;
+  }
+  const plan = buildUpgradePlan({ current, latest, method });
+  if (opts.json) {
+    print(JSON.stringify(plan, null, 2));
+    return { exitCode: plan.stale && !opts.run ? 1 : 0, lines };
+  }
+  if (latest === null) {
+    print("mcph upgrade: couldn't reach the npm registry (offline? firewall?).");
+    if (plan.command) {
+      print(`When you're back online, run:
+  ${plan.command}`);
+    } else {
+      print("Your install uses `npx -y` \u2014 just restart the MCP client when you're back online.");
+    }
+    return { exitCode: 0, lines };
+  }
+  print(`Current: ${current}`);
+  print(`Latest:  ${latest}`);
+  print(`Install: ${method}`);
+  if (!plan.stale) {
+    print("");
+    print("\u2713 You're on the latest version \u2014 nothing to do.");
+    return { exitCode: 0, lines };
+  }
+  print("");
+  if (method === "npx") {
+    print("Your install uses `npx -y` \u2014 restart the MCP client and it will fetch the new version.");
+    return { exitCode: 0, lines };
+  }
+  if (!plan.command) {
+    print("No upgrade command available for this install method.");
+    return { exitCode: 0, lines };
+  }
+  if (!opts.run) {
+    print(`Run:
+  ${plan.command}`);
+    return { exitCode: 1, lines };
+  }
+  if (method !== "global-npm") {
+    printErr(`mcph upgrade --run: refusing to auto-run upgrade for method "${method}". Run manually: ${plan.command}`);
+    return { exitCode: 2, lines };
+  }
+  const runner = opts.spawnImpl ?? defaultSpawn;
+  print(`Running: ${plan.command}`);
+  const code = await runner("npm", ["install", "-g", "@yawlabs/mcph@latest"]);
+  if (code === 0) {
+    print("");
+    print(`\u2713 Upgraded @yawlabs/mcph to ${latest}.`);
+    return { exitCode: 0, lines };
+  }
+  printErr(`mcph upgrade: npm exited ${code}. Try running the command manually.`);
+  return { exitCode: 3, lines };
+}
+function readCurrentVersion() {
+  const v = globalThis.__VERSION__;
+  return typeof v === "string" ? v : "dev";
+}
+
 // src/index.ts
 var KNOWN_SUBCOMMANDS = [
   "compliance",
@@ -7407,6 +7585,7 @@ var KNOWN_SUBCOMMANDS = [
   "servers",
   "bundles",
   "completion",
+  "upgrade",
   "help",
   "--help",
   "-h",
@@ -7466,6 +7645,14 @@ if (subcommand === "compliance") {
     process.exit(2);
   }
   runCompletion(parsed.options).then((r) => process.exit(r.exitCode));
+} else if (subcommand === "upgrade") {
+  const parsed = parseUpgradeArgs(process.argv.slice(3));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}
+`);
+    process.exit(2);
+  }
+  runUpgrade(parsed.options).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
   const installBlock = `    ${INSTALL_USAGE.replace(/^Usage: /, "").replace(/\n/g, "\n    ")}`;
   process.stdout.write(
@@ -7481,6 +7668,7 @@ if (subcommand === "compliance") {
     mcph compliance <target> [flags]  Run the compliance suite against an MCP server
     mcph reset-learning               Clear cross-session learning history (~/.mcph/state.json)
     mcph completion <shell>           Print a shell completion script (bash|zsh|fish|powershell)
+    mcph upgrade [--run] [--json]     Show (or run) the upgrade command for @yawlabs/mcph
     mcph --version                    Print version
 
   Install:
@@ -7501,7 +7689,7 @@ ${installBlock}
   );
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.45.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.46.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcph",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "mcp.hosting — one install, all your MCP servers, managed from the cloud",
   "license": "UNLICENSED",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",