ymmv-cli 0.8.0 → 0.10.0

package/README.md

@@ -9,10 +9,13 @@ clean page at `ymmv.fyi/<handle>` in about 10 seconds. See a live one:
 ![Running npx ymmv-cli to detect, confirm, and publish a dev stack to a live ymmv.fyi page](https://raw.githubusercontent.com/ymmv-fyi/ymmv/main/docs/demo.gif)
 
 ```sh
-npx ymmv-cli            # detect your stack, confirm, go live at ymmv.fyi/<you>
-npx ymmv-cli bardisty   # view someone's stack in the terminal
+npx ymmv-cli@latest            # detect your stack, confirm, go live at ymmv.fyi/<you>
+npx ymmv-cli@latest bardisty   # view someone's stack in the terminal
 ```
 
+(`@latest` makes npx look for the newest release; without a version spec, npx can pin you
+to whatever it downloaded first.)
+
 Viewing someone while you're logged in diffs their stack against yours:
 
 ```
@@ -33,6 +36,9 @@ Install once for the short `ymmv` command:
 npm i -g ymmv-cli
 ```
 
+When a newer release exists, the CLI mentions it after a command (interactive terminals only)
+and `ymmv update` upgrades a global install in place.
+
 First run includes a one-time GitHub sign-in. Works on macOS, Linux, Windows,
 and WSL. Nothing is published until you confirm (detection only pre-fills), and
 `ymmv delete` removes everything. Releases are published from GitHub Actions
@@ -47,7 +53,10 @@ via npm Trusted Publishing, with provenance.
 - `ymmv unset editor` removes one value (`ymmv set editor -` works too); `ymmv unset --extra "Keyboard"` removes an extra
 - `ymmv delete` removes your profile (`ymmv delete -y` skips the confirm, for scripts)
 - `ymmv login` / `ymmv logout` sign in / out
-- `ymmv version` prints the CLI version
+- `ymmv update` updates the CLI to the latest release (runs the matching upgrade for npm, pnpm,
+  and bun global installs; via npx it prints the invocation to use instead; anything else gets
+  the commands to run by hand)
+- `ymmv version` prints the CLI version (and notes a newer release when one is known)
 
 Values are capped at 256 characters and extra labels at 64; a profile holds up
 to 32 extras.
@@ -59,7 +68,9 @@ Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`. Full c
 ## Environment variables
 
 - `NO_COLOR` disables color output (and `FORCE_COLOR=0`/`false` force-disables it).
-- `YMMV_API` points the CLI at a different Worker (development/staging). Bare origin only.
+- `YMMV_API` points the CLI at a different Worker (development/staging). Bare origin only. That
+  Worker must be deployed with or after this CLI release: `ymmv login` requires the account id the
+  login response carries and refuses (revoking what it minted) otherwise.
 - `YMMV_TOKEN` authenticates without a browser (CI and scripts, below). Takes precedence over
   the stored login and is read-only: the CLI never writes, revokes, or deletes it, and
   `ymmv login` / `ymmv logout` keep acting on the stored login. Viewing (`ymmv <handle>`) also
@@ -68,6 +79,9 @@ Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`. Full c
 - `YMMV_HANDLE` names the GitHub username `YMMV_TOKEN` belongs to. Required for `ymmv -y` and
   `ymmv set`/`unset` under an env token (there is no server lookup for it); ignored without
   `YMMV_TOKEN`.
+- `YMMV_NO_UPDATE_CHECK` disables the startup check for newer releases (the ecosystem-standard
+  `NO_UPDATE_NOTIFIER` works too). The check is also off automatically under `CI`, in pipes,
+  and in dev builds; it never blocks or fails a command.
 
 ## Publishing from CI
 
@@ -78,7 +92,7 @@ Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`. Full c
    `~/.config/ymmv/token.json` (Linux), `~/Library/Preferences/ymmv/token.json` (macOS),
    `%APPDATA%\ymmv\Config\token.json` (Windows).
 3. Set it as a CI secret named `YMMV_TOKEN`, and set `YMMV_HANDLE` to your GitHub username.
-4. Run `npx ymmv-cli -y` in the job.
+4. Run `npx ymmv-cli@latest -y` in the job.
 
 Two things to know:
 

package/dist/cli.js

@@ -259,6 +259,9 @@ function diff(mine, theirs) {
 
 // ../shared/dist/github.js
 var GITHUB_CLIENT_ID = "Ov23liMoD29eizQcN1KZ";
+function isGithubId(x) {
+  return typeof x === "number" && Number.isSafeInteger(x) && x > 0;
+}
 
 // ../shared/dist/types.js
 var SCHEMA_VERSION = 1;
@@ -349,7 +352,8 @@ var CLI_VERBS = [
   "view",
   "help",
   "publish",
-  "version"
+  "version",
+  "update"
 ];
 var RESERVED = [.../* @__PURE__ */ new Set([...RESERVED_ROUTES, ...CLI_VERBS])];
 var RESERVED_SET = new Set(RESERVED);
@@ -389,10 +393,7 @@ var CTRL_RE = new RegExp(
   `[${String.fromCharCode(0)}-${String.fromCharCode(31)}${String.fromCharCode(127)}-${String.fromCharCode(159)}]`,
   "g"
 );
-var BIDI_RE = new RegExp(
-  `[${String.fromCharCode(8234)}-${String.fromCharCode(8238)}${String.fromCharCode(8294)}-${String.fromCharCode(8297)}${String.fromCharCode(8206)}${String.fromCharCode(8207)}]`,
-  "g"
-);
+var BIDI_RE = new RegExp("\\p{Bidi_Control}", "gu");
 function sanitizeValue(value) {
   return value.replace(ANSI_RE, "").replace(CTRL_RE, "").replace(BIDI_RE, "");
 }
@@ -417,10 +418,10 @@ function isHttpUrl(value) {
   return HTTP_URL_RE.test(value.trim());
 }
 var NO_OSC8_TERMS = /* @__PURE__ */ new Set(["linux", "dumb"]);
-function link(url, color, term = process.env.TERM) {
+function link(url, color, term = process.env.TERM, label) {
   const clean = sanitizeValue(url).trim();
   if (!color) return clean;
-  const text = `${CODES.amber}${displayUrl(clean)}${CODES.reset}`;
+  const text = `${CODES.amber}${label ? sanitizeValue(label) : displayUrl(clean)}${CODES.reset}`;
   if (term !== void 0 && NO_OSC8_TERMS.has(term)) return text;
   return `${OSC}8;;${clean}${ST}${text}${OSC}8;;${ST}`;
 }
@@ -539,11 +540,12 @@ function nudge(color) {
 function notFound(handle, color, base) {
   return `
   no ymmv profile for "${sanitizeValue(handle)}" yet.
-  publish one at ${link(base, color)} with: npx ymmv-cli`;
+  publish one at ${link(base, color)} with: npx ymmv-cli@latest`;
 }
 
 // src/http.ts
 var REQUEST_TIMEOUT_MS = 3e4;
+var REVOKE_CAP_MS = 5e3;
 var TIMEOUT_TEXT = "request timed out";
 function isTimeoutError(err) {
   return err instanceof Error && (err.name === "TimeoutError" || err.cause instanceof Error && err.cause.name === "TimeoutError");
@@ -626,9 +628,6 @@ async function safeFetch(url, init, reach, fetchFn = globalThis.fetch) {
   }
 }
 
-// src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
-
 // src/config.ts
 function normalizeBase(raw) {
   return raw.replace(/\/+$/, "");
@@ -685,6 +684,12 @@ async function bodyJson(res) {
     return null;
   }
 }
+var MintRejected = class extends Error {
+  constructor(msg) {
+    super(msg);
+    this.name = "MintRejected";
+  }
+};
 async function mintYmmvToken(accessToken) {
   const res = await safeFetch(
     `${BASE}/api/v1/auth/token`,
@@ -726,19 +731,30 @@ async function mintYmmvToken(accessToken) {
     throw new Error(`login failed: ${res.status} ${wireText(slug)}`.trim());
   }
   const data = await bodyJson(res);
-  if (!data || typeof data.token !== "string" || data.token.length === 0 || data.handle !== null && typeof data.handle !== "string") {
-    throw new Error(
-      `Unexpected response from ${BASE}. Nothing was saved; run \`ymmv login\` again.`
+  const unexpected = `Unexpected response from ${BASE}. Nothing was saved; run \`ymmv login\` again.`;
+  if (!data) throw new Error(unexpected);
+  const token = typeof data.token === "string" && data.token.length > 0 ? data.token : null;
+  const handle = data.handle === null ? null : typeof data.handle === "string" ? sanitizeValue(data.handle) : void 0;
+  if (token === null || handle === void 0 || handle !== null && !isValidHandle(handle) || !isGithubId(data.github_id)) {
+    let revokeFailed = false;
+    if (token !== null) {
+      await revokeYmmvToken(token, AbortSignal.timeout(REVOKE_CAP_MS)).catch(() => {
+        revokeFailed = true;
+      });
+    }
+    throw new MintRejected(
+      revokeFailed ? `${unexpected} The login the server minted could not be revoked.` : unexpected
     );
   }
-  return { token: data.token, handle: data.handle === null ? null : sanitizeValue(data.handle) };
+  return { token, handle, github_id: data.github_id };
 }
-async function revokeYmmvToken(token) {
+async function revokeYmmvToken(token, signal) {
   const res = await safeFetch(
     `${BASE}/api/v1/auth/logout`,
     {
       method: "POST",
       headers: { authorization: `Bearer ${token}` },
+      signal,
       // Never follow a redirect: a 30x→200 must not read as a successful revoke (which would delete
       // the local file while the server token stays live). Same guard as mint + publish/delete.
       redirect: "manual"
@@ -771,7 +787,12 @@ async function saveToken(data) {
   if (process.platform !== "win32") await chmod(dir, 448).catch(() => {
   });
   const tmp = `${path}.${randomUUID()}.tmp`;
-  const stored = { base: BASE, token: data.token, handle: data.handle };
+  const stored = {
+    base: BASE,
+    token: data.token,
+    handle: data.handle,
+    github_id: data.github_id
+  };
   try {
     await writeFile(tmp, JSON.stringify(stored), { mode: 384 });
     if (process.platform !== "win32") await chmod(tmp, 384);
@@ -792,10 +813,17 @@ async function readTokenFile() {
 }
 async function loadToken() {
   const parsed = await readTokenFile();
-  if (!parsed || parsed.base !== BASE || typeof parsed.token !== "string" || parsed.token === "" || parsed.handle !== null && typeof parsed.handle !== "string") {
+  const rawId = parsed?.github_id;
+  const idOk = rawId === void 0 || rawId === null || isGithubId(rawId);
+  if (!parsed || parsed.base !== BASE || typeof parsed.token !== "string" || parsed.token === "" || parsed.handle !== null && typeof parsed.handle !== "string" || !idOk) {
     return null;
   }
-  return parsed;
+  return {
+    base: parsed.base,
+    token: parsed.token,
+    handle: parsed.handle === "" ? null : parsed.handle,
+    github_id: isGithubId(rawId) ? rawId : null
+  };
 }
 async function peekCredential() {
   const parsed = await readTokenFile();
@@ -804,7 +832,13 @@ async function peekCredential() {
 async function loadCredential() {
   const envToken = process.env.YMMV_TOKEN || "";
   if (envToken !== "") {
-    return { base: BASE, token: envToken, handle: process.env.YMMV_HANDLE || null, source: "env" };
+    return {
+      base: BASE,
+      token: envToken,
+      handle: process.env.YMMV_HANDLE || null,
+      github_id: null,
+      source: "env"
+    };
   }
   const stored = await loadToken();
   return stored ? { ...stored, source: "file" } : null;
@@ -952,16 +986,16 @@ ${c.faint}waiting for GitHub approval\u2026 (Ctrl+C to cancel)${c.reset}`
     )
   );
   const accessToken = await pollForToken(dc, deps);
-  const { token, handle } = await mintYmmvToken(accessToken);
+  const minted = await mintYmmvToken(accessToken);
   const replaced = await peekCredential();
   try {
-    await saveToken({ token, handle });
+    await saveToken(minted);
   } catch (e) {
-    await revokeYmmvToken(token).catch(() => {
+    await revokeYmmvToken(minted.token).catch(() => {
     });
     throw e;
   }
-  if (replaced && replaced.base === BASE && replaced.token !== token) {
+  if (replaced && replaced.base === BASE && replaced.token !== minted.token) {
     try {
       await revokeYmmvToken(replaced.token);
     } catch {
@@ -970,7 +1004,7 @@ ${c.faint}waiting for GitHub approval\u2026 (Ctrl+C to cancel)${c.reset}`
   }
   console.log(
     message(
-      handle ? `Logged in as ${handle}.` : "Logged in. No handle bound (your GitHub username is a reserved word)."
+      minted.handle ? `Logged in as ${minted.handle}.` : "Logged in. No handle bound (your GitHub username is a reserved word)."
     )
   );
 }
@@ -983,18 +1017,30 @@ var PublishRefusal = class extends Error {
   }
 };
 var ENV_TOKEN_REJECTED = "The server rejected the token in YMMV_TOKEN (revoked or expired).";
+var NOT_PERSISTED = "Login did not persist a token. Run `ymmv login`.";
 async function rateLimitMessage(res) {
   return withRetryHint(await serverMessage(res) ?? "rate limited, too many requests", res);
 }
+async function loginOrRefuse() {
+  try {
+    await login();
+  } catch (e) {
+    if (e instanceof MintRejected) throw new PublishRefusal(e.message);
+    throw e;
+  }
+  const fresh = await loadCredential();
+  if (!fresh) throw new PublishRefusal(NOT_PERSISTED);
+  return fresh;
+}
 async function ensureLogin() {
   const existing = await loadCredential();
   if (existing) return existing;
   await login();
   const fresh = await loadCredential();
-  if (!fresh) throw new Error("Login did not persist a token. Run `ymmv login`.");
+  if (!fresh) throw new Error(NOT_PERSISTED);
   return fresh;
 }
-async function publishProfile(profile) {
+async function publishProfile(profile, expected) {
   const send = (c) => safeFetch(
     `${BASE}/api/v1/profile`,
     {
@@ -1008,8 +1054,13 @@ async function publishProfile(profile) {
     },
     BASE
   );
-  let cred = await ensureLogin();
-  if ((cred.handle ?? "").toLowerCase() !== profile.handle.toLowerCase()) {
+  let cred = await loadCredential();
+  if (!cred) {
+    console.log(message("Not logged in. Logging in to publish."));
+    cred = await loginOrRefuse();
+  }
+  const idDrifted = expected.source === "file" && (expected.github_id === null ? cred.github_id !== null : cred.github_id !== expected.github_id);
+  if ((cred.handle ?? "").toLowerCase() !== profile.handle.toLowerCase() || idDrifted) {
     throw new PublishRefusal(
       "The stored login changed while this command was running. Re-run it under the current account."
     );
@@ -1022,19 +1073,35 @@ async function publishProfile(profile) {
       );
     }
     const was401 = res.status === 401;
+    const before = cred;
     console.log(
       message(
         was401 ? "Session expired. Logging in again to retry the publish." : "The server no longer recognizes your handle. Logging in again to retry the publish."
       )
     );
     if (was401) await deleteToken();
-    await login();
-    cred = await ensureLogin();
-    if ((cred.handle ?? "").toLowerCase() !== profile.handle.toLowerCase()) {
-      const bound = sanitizeValue(cred.handle ?? "");
-      throw new PublishRefusal(
-        was401 ? `The re-login bound a different account ("${bound}", not "${sanitizeValue(profile.handle)}"). Nothing was published. Re-run under the account you meant.` : `Your login now binds "${bound}". Nothing was published. Re-run the command to publish under it.`
-      );
+    cred = await loginOrRefuse();
+    const known = before.github_id !== null;
+    const idChanged = known && cred.github_id !== before.github_id;
+    const sameHandle = (cred.handle ?? "").toLowerCase() === profile.handle.toLowerCase();
+    if (!sameHandle || idChanged) {
+      const mine = sanitizeValue(profile.handle);
+      const bound = cred.handle === null ? null : sanitizeValue(cred.handle);
+      const reRun = "Nothing was published. Re-run under the account you meant.";
+      const otherAccount = `The re-login bound a different account ("${bound}", not "${mine}"). ${reRun}`;
+      if (idChanged) {
+        throw new PublishRefusal(
+          sameHandle ? `The handle "${mine}" now belongs to a different GitHub account. ${reRun}` : bound === null ? `The re-login bound a different GitHub account. ${reRun}` : otherAccount
+        );
+      }
+      if (bound === null) {
+        throw new PublishRefusal(
+          "Your login no longer binds a handle (your GitHub username is a reserved word). Nothing was published."
+        );
+      }
+      const rebound = `Your login now binds "${bound}". Nothing was published. Re-run the command to publish under it.`;
+      if (known) throw new PublishRefusal(rebound);
+      throw new PublishRefusal(was401 ? otherAccount : rebound);
     }
     res = await send(cred);
     if (res.status === 401) throw new PublishRefusal("Authentication failed. Run `ymmv login`.");
@@ -1578,7 +1645,7 @@ async function publish(io) {
     }
     const entries = assemble();
     showCard(entries);
-    printPublished(await publishProfile(newProfile(handle, entries, extras)), color);
+    printPublished(await publishProfile(newProfile(handle, entries, extras), cred), color);
     return;
   }
   try {
@@ -1594,7 +1661,7 @@ async function publish(io) {
       );
       if (ans === "y") {
         try {
-          printPublished(await publishProfile(newProfile(handle, entries, extras)), color);
+          printPublished(await publishProfile(newProfile(handle, entries, extras), cred), color);
           return;
         } catch (e) {
           if (e instanceof PromptAborted || e instanceof PublishRefusal) throw e;
@@ -1673,7 +1740,7 @@ async function runSet(target) {
     process.exitCode = 1;
     return;
   }
-  const res = await publishProfile(newProfile(handle, entries, extras));
+  const res = await publishProfile(newProfile(handle, entries, extras), cred);
   const line = target.kind === "curated" ? `Set ${KEY_LABELS[target.key]} = ${target.value}.` : `Set extra ${target.label} = ${target.value}.`;
   console.log(message(`${line}${pagePointer(res.handle)}`));
 }
@@ -1696,7 +1763,7 @@ async function runUnset(target) {
     );
     return;
   }
-  const res = await publishProfile(newProfile(handle, entries, extras));
+  const res = await publishProfile(newProfile(handle, entries, extras), cred);
   const line = target.kind === "curated" ? `Removed ${KEY_LABELS[target.key]} (was "${sanitizeValue(removed.value)}").` : `Removed extra "${sanitizeValue(removed.label)}" (was "${sanitizeValue(removed.value)}").`;
   console.log(message(`${line}${pagePointer(res.handle)}`));
 }
@@ -1827,7 +1894,7 @@ function resolveArg(argv) {
     }
     return { kind: "publish", yes: true };
   }
-  if (first === "login" || first === "logout") return noArgs(first, rest);
+  if (first === "login" || first === "logout" || first === "update") return noArgs(first, rest);
   if (first === "publish") {
     return yesOnly("usage: ymmv publish [-y]", rest, (yes) => ({ kind: "publish", yes }));
   }
@@ -1877,6 +1944,274 @@ function reservedError(handle, hintVerbs = false) {
   };
 }
 
+// src/update.ts
+import { spawn as nodeSpawn } from "child_process";
+import { homedir } from "os";
+
+// src/update-check.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { readFileSync as readFileSync2, realpathSync } from "fs";
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+import envPaths2 from "env-paths";
+var REGISTRY_URL = "https://registry.npmjs.org/ymmv-cli/latest";
+var RELEASES_URL = "https://github.com/ymmv-fyi/ymmv/releases";
+var FETCH_TIMEOUT_MS = 2e3;
+var FINISH_GRACE_MS = 500;
+var SUCCESS_TTL_MS = 24 * 60 * 60 * 1e3;
+var FAILURE_TTL_MS = 6 * 60 * 60 * 1e3;
+var VERSION_FRESH_MS = 7 * 24 * 60 * 60 * 1e3;
+function ownVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+function parseTriple(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function isNewer(latest, current) {
+  const l = parseTriple(latest);
+  const c = parseTriple(current);
+  if (!l || !c) return false;
+  for (let i = 0; i < 3; i++) {
+    if (l[i] !== c[i]) return l[i] > c[i];
+  }
+  return false;
+}
+function updateCachePath() {
+  return join2(envPaths2("ymmv", { suffix: "" }).config, "update-check.json");
+}
+async function readCache(path, now) {
+  try {
+    const parsed = JSON.parse(await readFile2(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const c = parsed;
+    if (typeof c.lastCheckedAt !== "number" || typeof c.ok !== "boolean") return null;
+    if (!Number.isFinite(c.lastCheckedAt) || c.lastCheckedAt > now) return null;
+    if (c.latest !== void 0 && typeof c.latest !== "string") return null;
+    if (c.latestAt !== void 0 && (!Number.isFinite(c.latestAt) || c.latestAt > now)) return null;
+    return { lastCheckedAt: c.lastCheckedAt, ok: c.ok, latest: c.latest, latestAt: c.latestAt };
+  } catch {
+    return null;
+  }
+}
+async function writeCache(path, cache) {
+  const tmp = `${path}.${randomUUID2()}.tmp`;
+  try {
+    await mkdir2(dirname2(path), { recursive: true });
+    await writeFile2(tmp, JSON.stringify(cache));
+    await rename2(tmp, path);
+  } catch {
+    await rm2(tmp, { force: true }).catch(() => {
+    });
+  }
+}
+function binRealpath() {
+  const raw = process.argv[1];
+  if (!raw) return void 0;
+  try {
+    return realpathSync(raw);
+  } catch {
+    return raw;
+  }
+}
+var NPM_PREFIX_ROOTS = /* @__PURE__ */ new Set(["usr", "local", "homebrew", "nodejs", "node", "installation"]);
+var VERSIONISH_RE = /^v?\d+(\.\d+)*$/;
+function detectInstallMethod(binPath) {
+  if (!binPath) return "unknown";
+  const segs = binPath.split(/[\\/]+/).filter(Boolean).map((s) => s.toLowerCase());
+  const has = (name) => segs.includes(name);
+  if (has("_npx")) return "ephemeral";
+  if (has("dlx") || segs.some((s) => s.startsWith("dlx-"))) return "ephemeral";
+  if (segs.some((s) => s.startsWith("bunx-"))) return "ephemeral";
+  if (has(".bun") && has("cache")) return "ephemeral";
+  if (has(".bun") && (has("global") || has("bin"))) return "bun-global";
+  if (has(".volta")) return "unknown";
+  if (segs.some((s, i) => s === "pnpm" && segs[i + 1] === "global")) return "pnpm-global";
+  if (has(".pnpm")) return "unknown";
+  const npmGlobal = segs.some(
+    (s, i) => s === "node_modules" && segs[i + 1] === "ymmv-cli" && (segs[i - 1] === "lib" && i >= 2 && (NPM_PREFIX_ROOTS.has(segs[i - 2]) || VERSIONISH_RE.test(segs[i - 2])) || segs[i - 1] === "npm")
+  );
+  if (npmGlobal) return "npm-global";
+  return "unknown";
+}
+function npxInvocation(latest) {
+  const triple = latest ? parseTriple(latest) : null;
+  return `npx ymmv-cli@${triple ? triple.join(".") : "latest"}`;
+}
+function formatUpdateNotice(current, latest, method, color, term) {
+  const cur = parseTriple(current);
+  const lat = parseTriple(latest);
+  if (!cur || !lat || !isNewer(lat.join("."), cur.join("."))) return null;
+  const latestClean = lat.join(".");
+  const currentClean = cur.join(".");
+  const cmd = method === "ephemeral" ? npxInvocation(latestClean) : "ymmv update";
+  const c = palette(color);
+  const headline = `ymmv-cli ${latestClean} is out`;
+  const linked = color ? link(RELEASES_URL, true, term, headline) : headline;
+  return `${linked} ${c.faint}(you have ${currentClean})${c.reset} \u2192 run ${c.bold}${cmd}${c.reset}`;
+}
+function updatesOptedOut(env) {
+  if (env.YMMV_NO_UPDATE_CHECK) return true;
+  if (env.NO_UPDATE_NOTIFIER) return true;
+  if (env.CI && env.CI !== "false") return true;
+  return false;
+}
+async function readCachedLatest(deps = {}) {
+  const now = (deps.now ?? Date.now)();
+  const cache = await readCache(deps.cachePath ?? updateCachePath(), now);
+  if (!cache?.latest || cache.latestAt === void 0) return null;
+  if (now - cache.latestAt > VERSION_FRESH_MS) return null;
+  const triple = parseTriple(cache.latest);
+  return triple ? triple.join(".") : null;
+}
+var GRACE = /* @__PURE__ */ Symbol("grace");
+function startUpdateCheck(deps = {}) {
+  const env = deps.env ?? process.env;
+  const nowFn = deps.now ?? Date.now;
+  const stderrIsTTY = deps.stderrIsTTY ?? Boolean(process.stderr.isTTY);
+  const inert = { finish: async () => null, abort: () => {
+  } };
+  if (updatesOptedOut(env)) return inert;
+  if (!stderrIsTTY) return inert;
+  const current = deps.currentVersion !== void 0 ? deps.currentVersion : ownVersion();
+  const currentTriple = current === null ? null : parseTriple(current);
+  if (!currentTriple || currentTriple.join(".") === "0.0.0") return inert;
+  const currentClean = currentTriple.join(".");
+  const cachePath = deps.cachePath ?? updateCachePath();
+  const doFetch = deps.fetch ?? globalThis.fetch;
+  const method = detectInstallMethod(deps.binPath ?? binRealpath());
+  const color = useColor(env, stderrIsTTY);
+  const term = env.TERM;
+  const controller = new AbortController();
+  const notice = (latest) => latest ? formatUpdateNotice(currentClean, latest, method, color, term) : null;
+  const check = (async () => {
+    const cache = await readCache(cachePath, nowFn());
+    if (cache && nowFn() - cache.lastCheckedAt < (cache.ok ? SUCCESS_TTL_MS : FAILURE_TTL_MS)) {
+      return notice(cache.latest);
+    }
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    timeout.unref?.();
+    let fetched = null;
+    try {
+      const res = await doFetch(REGISTRY_URL, {
+        signal: controller.signal,
+        headers: { accept: "application/json" }
+      });
+      if (res.ok) {
+        const body = await res.json();
+        if (typeof body.version === "string") fetched = body.version;
+      }
+    } catch {
+    } finally {
+      clearTimeout(timeout);
+    }
+    const triple = fetched === null ? null : parseTriple(fetched);
+    const canonical2 = triple ? triple.join(".") : void 0;
+    const now = nowFn();
+    await writeCache(cachePath, {
+      lastCheckedAt: now,
+      ok: canonical2 !== void 0,
+      latest: canonical2 ?? cache?.latest,
+      latestAt: canonical2 !== void 0 ? now : cache?.latestAt
+    });
+    return notice(canonical2 ?? cache?.latest);
+  })().catch(() => null);
+  return {
+    async finish() {
+      const result = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(GRACE), FINISH_GRACE_MS);
+        timer.unref?.();
+        void check.then((v) => {
+          clearTimeout(timer);
+          resolve(v);
+        });
+      });
+      if (result === GRACE) {
+        controller.abort();
+        return null;
+      }
+      return result;
+    },
+    abort() {
+      controller.abort();
+    }
+  };
+}
+
+// src/update.ts
+var UPGRADE_COMMANDS = {
+  "npm-global": "npm i -g ymmv-cli@latest",
+  "pnpm-global": "pnpm add -g ymmv-cli@latest",
+  "bun-global": "bun add -g ymmv-cli@latest"
+};
+var MANUAL_LIST = Object.values(UPGRADE_COMMANDS).map((cmd) => `  ${cmd}`).join("\n");
+var NOT_FOUND_CODES = /* @__PURE__ */ new Set([127, 9009]);
+function manualFallback(intro) {
+  return `${intro} Update with the command that matches your setup:
+${MANUAL_LIST}`;
+}
+async function runUpdate(deps = {}) {
+  const method = detectInstallMethod(deps.binPath ?? binRealpath());
+  const c = palette(colorEnabled());
+  if (method === "ephemeral") {
+    const cached = await readCachedLatest({ now: deps.now, cachePath: deps.cachePath });
+    const current = deps.currentVersion !== void 0 ? deps.currentVersion : ownVersion();
+    const pin = cached !== null && current !== null && isNewer(cached, current) ? cached : null;
+    console.log(
+      message(
+        `This run came from a package runner cache (npx-style), so there is no install to update.
+Next time run: ${c.bold}${npxInvocation(pin)}${c.reset}`
+      )
+    );
+    return;
+  }
+  if (method === "unknown") {
+    console.log(message(manualFallback("Couldn't tell how ymmv-cli was installed.")));
+    return;
+  }
+  const cmd = UPGRADE_COMMANDS[method];
+  const doSpawn = deps.spawn ?? nodeSpawn;
+  const failSpawn = () => {
+    console.error(message(manualFallback(`Couldn't run \`${cmd}\`.`)));
+    process.exitCode = 1;
+  };
+  console.log(message(`${c.faint}running${c.reset} ${c.bold}${cmd}${c.reset}`));
+  await new Promise((resolve) => {
+    let child;
+    try {
+      child = doSpawn(cmd, { stdio: "inherit", shell: true, cwd: homedir() });
+    } catch {
+      failSpawn();
+      resolve();
+      return;
+    }
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+      resolve();
+    };
+    child.on("error", () => {
+      settle(failSpawn);
+    });
+    child.on("exit", (code) => {
+      settle(() => {
+        if (code !== null && NOT_FOUND_CODES.has(code)) {
+          failSpawn();
+        } else if (code) {
+          process.exitCode = code;
+        }
+      });
+    });
+  });
+}
+
 // src/index.ts
 var help = (c) => `${c.bold}ymmv${c.reset}: terminal-native developer tool-stack profiles (ymmv.fyi)
 
@@ -1891,6 +2226,7 @@ ${c.faint}Usage:${c.reset}
   ymmv unset --extra "L"    remove a free-form extra
   ymmv delete [-y]          delete your profile (permanent; -y skips the confirm)
   ymmv login | logout       GitHub device-flow auth
+  ymmv update               update ymmv-cli to the latest release
   ymmv help | version
 
 ${c.faint}Curated keys:${c.reset} editor, os, shell, prompt, terminal, browser, window-manager,
@@ -1922,12 +2258,21 @@ async function logout() {
   console.log(message(revoked ? "Logged out." : "Logged out (no active session on this server)."));
 }
 function printVersion() {
-  try {
-    const pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
-    console.log(`ymmv-cli ${pkg.version ?? "unknown"}`);
-  } catch {
-    console.log("ymmv-cli (version unknown)");
-  }
+  const version = ownVersion();
+  console.log(version === null ? "ymmv-cli (version unknown)" : `ymmv-cli ${version}`);
+}
+async function printLatestHint() {
+  if (!process.stderr.isTTY) return;
+  if (updatesOptedOut(process.env)) return;
+  const current = ownVersion();
+  const currentTriple = current === null ? null : parseTriple(current);
+  if (!currentTriple || currentTriple.join(".") === "0.0.0") return;
+  const latest = await readCachedLatest();
+  if (latest === null || !isNewer(latest, currentTriple.join("."))) return;
+  const c = palette(useColor(process.env, true));
+  console.error(
+    message(`${c.faint}latest: ${latest}${c.reset} \u2192 run ${c.bold}ymmv update${c.reset}`)
+  );
 }
 async function interactive(run, yes) {
   const isTTY = Boolean(process.stdin.isTTY);
@@ -1938,9 +2283,12 @@ async function interactive(run, yes) {
     prompter?.close();
   }
 }
+function wantsUpdateCheck(kind) {
+  return kind !== "help" && kind !== "version" && kind !== "error" && kind !== "update";
+}
 async function main(argv) {
   const cmd = resolveArg(argv);
-  if (cmd.kind !== "logout") {
+  if (cmd.kind !== "logout" && cmd.kind !== "update") {
     const problem = baseProblem() ?? credentialEnvProblem();
     if (problem) {
       console.error(message(problem));
@@ -1948,6 +2296,17 @@ async function main(argv) {
       return;
     }
   }
+  const update = wantsUpdateCheck(cmd.kind) ? startUpdateCheck() : null;
+  try {
+    await dispatch(cmd);
+  } catch (e) {
+    update?.abort();
+    throw e;
+  }
+  const notice = await update?.finish();
+  if (notice) console.error(message(notice));
+}
+async function dispatch(cmd) {
   switch (cmd.kind) {
     case "publish":
       await interactive(publish, cmd.yes);
@@ -1980,11 +2339,15 @@ async function main(argv) {
         );
       }
       break;
+    case "update":
+      await runUpdate();
+      break;
     case "help":
       console.log(help(palette(colorEnabled())));
       break;
     case "version":
       printVersion();
+      await printLatestHint();
       break;
     case "error":
       console.error(message(cmd.message));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ymmv-cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Publish and diff terminal-native developer tool-stack profiles at ymmv.fyi.",
   "type": "module",
   "bin": {