ymmv-cli 0.7.0 → 0.9.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
@@ -40,18 +46,61 @@ via npm Trusted Publishing, with provenance.
 
 ## Commands
 
-- `ymmv` detects, confirms, and publishes (re-run any time to update)
+- `ymmv` detects, confirms, and publishes (re-run any time to update; `ymmv publish` is the same command)
 - `ymmv <handle>` views a profile, or diffs it against yours when you're logged in
 - `ymmv set editor Neovim` changes one value
-- `ymmv set --extra "Keyboard=HHKB"` adds a free-form line of your own
+- `ymmv set --extra "Keyboard=HHKB"` adds a free-form line of your own (`-e` works too)
 - `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` removes your profile (`ymmv delete -y` skips the confirm, for scripts)
 - `ymmv login` / `ymmv logout` sign in / out
-
-Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`.
-
-Color output respects `NO_COLOR`; set `YMMV_API` to point the CLI at a different Worker
-(development).
+- `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.
+
+Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`. Full contract
+(shape, statuses, caching, CORS):
+<https://github.com/ymmv-fyi/ymmv/blob/main/docs/api.md>.
+
+## 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_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
+  keeps using the stored login for the you-side of a diff. The token is sent to the server
+  `YMMV_API` selects, so set the two together.
+- `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
+
+`ymmv login` needs a browser, so mint the token on your machine and hand it to CI:
+
+1. Run `ymmv login` locally.
+2. Copy the `token` value from the token file:
+   `~/.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@latest -y` in the job.
+
+Two things to know:
+
+- `ymmv -y` publishes the merge of your existing profile with what it detects on the machine it
+  runs on. Values you already published always win, but curated keys you have never set get the
+  CI runner's detected values (its OS, shell, and so on). For targeted updates from CI, prefer
+  `ymmv set <key> <value>`.
+- A rejected or revoked `YMMV_TOKEN` fails with an error naming the variable; nothing falls back
+  to an interactive login, and the stored login file on the runner (if any) is left untouched.
+  `ymmv delete` acts on the account the token is bound to, regardless of `YMMV_HANDLE`.
 
 ## License
 

package/dist/cli.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 
+// ../shared/dist/caps.js
+var MAX_EXTRAS = 32;
+var MAX_LABEL = 64;
+var MAX_VALUE = 256;
+
 // ../shared/dist/keys.js
 var CURATED_KEYS = [
   "editor",
@@ -276,7 +281,8 @@ function parseProfile(raw) {
   if (!isRecord(raw))
     throw new ProfileParseError("profile is not an object");
   if (raw.schema_version !== SCHEMA_VERSION) {
-    throw new ProfileParseError(`unsupported schema_version: ${String(raw.schema_version)}`);
+    const got = String(raw.schema_version);
+    throw new ProfileParseError(`unsupported schema_version: ${got.length > 64 ? `${got.slice(0, 64)}\u2026` : got}. Upgrade the ymmv CLI (npm i -g ymmv-cli).`);
   }
   if (typeof raw.handle !== "string")
     throw new ProfileParseError("handle is not a string");
@@ -334,7 +340,18 @@ function parseProfile(raw) {
 
 // ../shared/dist/reserved.js
 var RESERVED_ROUTES = ["404", "api", "login", "logout"];
-var CLI_VERBS = ["login", "logout", "set", "unset", "delete", "view", "help"];
+var CLI_VERBS = [
+  "login",
+  "logout",
+  "set",
+  "unset",
+  "delete",
+  "view",
+  "help",
+  "publish",
+  "version",
+  "update"
+];
 var RESERVED = [.../* @__PURE__ */ new Set([...RESERVED_ROUTES, ...CLI_VERBS])];
 var RESERVED_SET = new Set(RESERVED);
 function isReserved(handle) {
@@ -382,7 +399,9 @@ function sanitizeValue(value) {
 }
 function useColor(env, isTTY) {
   if (env.NO_COLOR !== void 0) return false;
-  if (env.FORCE_COLOR !== void 0) return env.FORCE_COLOR !== "0";
+  if (env.FORCE_COLOR !== void 0) {
+    return env.FORCE_COLOR !== "0" && env.FORCE_COLOR !== "false";
+  }
   if (env.TERM === "dumb") return false;
   return isTTY;
 }
@@ -399,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}`;
 }
@@ -442,13 +461,15 @@ function renderProfile(profile, opts) {
   const val = (v) => isHttpUrl(v) ? link(v, opts.color) : v;
   const lines = [
     "",
-    `  ${c.faint}${opts.site}/${c.reset}${c.bold}${sanitizeValue(profile.handle)}${c.reset}`,
-    ""
+    `  ${c.faint}${opts.site}/${c.reset}${c.bold}${sanitizeValue(profile.handle)}${c.reset}`
   ];
-  for (const r of rows) {
-    lines.push(
-      r.value === null ? `  ${c.faint}${r.label.padEnd(labelW)}  ${MISSING}${c.reset}` : `  ${c.faint}${r.label.padEnd(labelW)}${c.reset}  ${val(r.value)}`
-    );
+  if (rows.length) {
+    lines.push("");
+    for (const r of rows) {
+      lines.push(
+        r.value === null ? `  ${c.faint}${r.label.padEnd(labelW)}  ${MISSING}${c.reset}` : `  ${c.faint}${r.label.padEnd(labelW)}${c.reset}  ${val(r.value)}`
+      );
+    }
   }
   if (extras.length) {
     lines.push("");
@@ -519,7 +540,7 @@ 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
@@ -553,17 +574,30 @@ function wireText(text) {
   return clean.length > 200 ? `${clean.slice(0, 200)}\u2026` : clean;
 }
 var INVISIBLE_RE = new RegExp("\\p{Default_Ignorable_Code_Point}", "gu");
-async function serverMessage(res) {
+async function wireBody(res) {
+  try {
+    return await res.text();
+  } catch (err) {
+    if (isTimeoutError(err)) throw err;
+    return "";
+  }
+}
+function wireErrorBody(raw) {
   try {
-    const body = await res.json();
+    const body = JSON.parse(raw);
+    const out = {};
+    if (typeof body?.error === "string") out.slug = body.error;
     if (typeof body?.message === "string") {
       const clean = wireText(body.message).trim();
-      if (clean.replace(INVISIBLE_RE, "").trim()) return clean;
+      if (clean.replace(INVISIBLE_RE, "").trim()) out.message = clean;
     }
-  } catch (err) {
-    if (isTimeoutError(err)) throw err;
+    return out;
+  } catch {
+    return {};
   }
-  return void 0;
+}
+async function serverMessage(res) {
+  return wireErrorBody(await wireBody(res)).message;
 }
 function withRetryHint(msg, res) {
   const retry = res.headers.get("retry-after");
@@ -574,6 +608,12 @@ function displayError(err) {
   const text = err instanceof Error ? err.message : String(err);
   return text.split(/\r?\n/).map((line) => sanitizeValue(line)).join("\n");
 }
+var NetworkError = class extends Error {
+  constructor(message2, options) {
+    super(message2, options);
+    this.name = "NetworkError";
+  }
+};
 async function safeFetch(url, init, reach, fetchFn = globalThis.fetch) {
   try {
     return await fetchFn(url, {
@@ -581,17 +621,58 @@ async function safeFetch(url, init, reach, fetchFn = globalThis.fetch) {
       signal: init?.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS)
     });
   } catch (err) {
-    throw new Error(`Can't reach ${reach}. Check your connection (${causeText(err)})`, {
+    throw new NetworkError(`Can't reach ${reach}. Check your connection (${causeText(err)})`, {
       cause: err
     });
   }
 }
 
-// src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
-
 // src/config.ts
-var BASE = (process.env.YMMV_API ?? "https://ymmv.fyi").replace(/\/+$/, "");
+function normalizeBase(raw) {
+  return raw.replace(/\/+$/, "");
+}
+var BASE = normalizeBase(process.env.YMMV_API || "https://ymmv.fyi");
+function baseProblem(raw = process.env.YMMV_API) {
+  if (raw === void 0 || raw === "") return null;
+  const shown = `YMMV_API is set to "${sanitizeValue(raw)}"`;
+  if (/\s/.test(raw)) return `${shown} which contains whitespace. Remove it.`;
+  const base = normalizeBase(raw);
+  let url;
+  try {
+    url = new URL(base);
+  } catch {
+    return `${shown} which is not a full URL. Use a bare origin like https://ymmv.fyi (the http:// or https:// scheme is required).`;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return `${shown} which is not an http or https URL. Use a bare origin like https://ymmv.fyi.`;
+  }
+  if (url.username || url.password) {
+    return `${shown} which contains credentials. Use a bare origin like https://ymmv.fyi.`;
+  }
+  if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+    return `${shown} which is not a bare origin. Drop the path (the Worker's redirects are root-absolute, so a path-mounted base breaks): use just the scheme and host, like https://ymmv.fyi.`;
+  }
+  if (base !== url.origin) {
+    return `${shown} which is not in canonical form. Use exactly the scheme and host, like https://ymmv.fyi.`;
+  }
+  return null;
+}
+function credentialEnvProblem(rawToken = process.env.YMMV_TOKEN, rawHandle = process.env.YMMV_HANDLE) {
+  if (rawToken === void 0 || rawToken === "") return null;
+  if (!/^[\x21-\x7E]+$/.test(rawToken)) {
+    return "YMMV_TOKEN contains whitespace, control, or non-ASCII characters. Set it to the exact token value.";
+  }
+  if (rawHandle !== void 0 && rawHandle !== "") {
+    const shown = `YMMV_HANDLE is set to "${sanitizeValue(rawHandle)}"`;
+    if (!isValidHandle(rawHandle)) {
+      return `${shown} which is not a valid GitHub username. Set it to the handle bound to YMMV_TOKEN.`;
+    }
+    if (isReserved(rawHandle)) {
+      return `${shown} which is a reserved word, so no handle can be bound to it.`;
+    }
+  }
+  return null;
+}
 
 // src/auth-http.ts
 async function bodyJson(res) {
@@ -631,7 +712,16 @@ async function mintYmmvToken(accessToken) {
       );
     }
     const body = await bodyJson(res) ?? {};
-    throw new Error(`login failed: ${res.status} ${wireText(body.error ?? "")}`.trim());
+    const slug = typeof body.error === "string" ? body.error : "";
+    if (res.status === 401 && slug === "github_auth_failed") {
+      throw new Error("GitHub rejected the authorization. Run `ymmv login` to try again.");
+    }
+    if (res.status === 500 && slug === "internal_error") {
+      throw new Error(
+        "The server hit an error minting your login. Run `ymmv login` again shortly."
+      );
+    }
+    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") {
@@ -690,38 +780,49 @@ async function saveToken(data) {
     throw e;
   }
 }
-async function loadToken() {
-  let raw;
+async function readTokenFile() {
   try {
-    raw = await readFile(tokenFilePath(), "utf8");
+    const parsed = JSON.parse(await readFile(tokenFilePath(), "utf8"));
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
   }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
+}
+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") {
     return null;
   }
-  if (parsed.base !== BASE || typeof parsed.token !== "string") return null;
   return parsed;
 }
+async function peekCredential() {
+  const parsed = await readTokenFile();
+  return parsed && typeof parsed.base === "string" && typeof parsed.token === "string" && parsed.token !== "" ? { base: parsed.base, token: parsed.token } : null;
+}
+async function loadCredential() {
+  const envToken = process.env.YMMV_TOKEN || "";
+  if (envToken !== "") {
+    return { base: BASE, token: envToken, handle: process.env.YMMV_HANDLE || null, source: "env" };
+  }
+  const stored = await loadToken();
+  return stored ? { ...stored, source: "file" } : null;
+}
 async function deleteToken() {
   await rm(tokenFilePath(), { force: true });
 }
 async function peekBase() {
-  try {
-    const parsed = JSON.parse(await readFile(tokenFilePath(), "utf8"));
-    return typeof parsed.base === "string" ? parsed.base : null;
-  } catch {
-    return null;
-  }
+  const parsed = await readTokenFile();
+  return typeof parsed?.base === "string" ? parsed.base : null;
 }
 
 // src/device-flow.ts
 var DEVICE_CODE_URL = "https://github.com/login/device/code";
 var TOKEN_URL = "https://github.com/login/oauth/access_token";
 var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var DEFAULT_POLL_INTERVAL_S = 5;
+function usableInterval(v) {
+  return typeof v === "number" && Number.isFinite(v) && v >= 1 && v <= 900;
+}
 async function requestDeviceCode(deps = {}) {
   const doFetch = deps.fetch ?? globalThis.fetch;
   const res = await safeFetch(
@@ -741,7 +842,10 @@ async function requestDeviceCode(deps = {}) {
     if (isTimeoutError(err)) throw err;
     return null;
   });
-  if (!data || typeof data.device_code !== "string" || typeof data.user_code !== "string" || typeof data.verification_uri !== "string" || typeof data.expires_in !== "number") {
+  if (!data || typeof data.device_code !== "string" || typeof data.user_code !== "string" || typeof data.verification_uri !== "string" || // expires_in gets the same rigor as interval: NaN makes the deadline NaN (instant false
+  // "expired"), Infinity/1e300 make it unreachable (a middlebox feeding parseable
+  // authorization_pending bodies would hold the login forever - the deadline is the only exit).
+  typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in) || data.expires_in <= 0 || data.expires_in > 86400 || data.interval !== void 0 && !usableInterval(data.interval)) {
     throw new Error("GitHub sent an unexpected device-code response. Run `ymmv login` again.");
   }
   return data;
@@ -750,7 +854,7 @@ async function pollForToken(dc, deps = {}) {
   const doFetch = deps.fetch ?? globalThis.fetch;
   const sleep = deps.sleep ?? realSleep;
   const now = deps.now ?? Date.now;
-  let interval = dc.interval || 5;
+  let interval = usableInterval(dc.interval) ? dc.interval : DEFAULT_POLL_INTERVAL_S;
   const deadline = now() + dc.expires_in * 1e3;
   let transientFailures = 0;
   let lastCause = "";
@@ -802,7 +906,7 @@ async function pollForToken(dc, deps = {}) {
       case "authorization_pending":
         break;
       case "slow_down":
-        interval = Math.max(tok.interval ?? 0, interval + 5);
+        interval = usableInterval(tok.interval) ? Math.max(tok.interval, interval + DEFAULT_POLL_INTERVAL_S) : interval + DEFAULT_POLL_INTERVAL_S;
         break;
       case "access_denied":
         throw new Error("Authorization denied. Run `ymmv login` to try again.");
@@ -820,9 +924,24 @@ async function login(deps = {}) {
       "Device login needs an interactive terminal. Run `ymmv login` in a real terminal (a piped or CI shell can't complete the GitHub device flow)."
     );
   }
-  const dc = await requestDeviceCode(deps);
+  if (process.env.YMMV_TOKEN) {
+    console.error(
+      message(
+        "YMMV_TOKEN is set and takes precedence over stored logins. This login will be saved but not used until you unset it."
+      )
+    );
+  }
+  const prior = await peekCredential();
   const color = colorEnabled();
   const c = palette(color);
+  if (prior && prior.base !== BASE) {
+    console.error(
+      message(
+        `You're logged in to ${sanitizeValue(prior.base)}. Logging in here replaces that stored token. To revoke it first, set YMMV_API to that server and run \`ymmv logout\`.`
+      )
+    );
+  }
+  const dc = await requestDeviceCode(deps);
   const verifyUri = /^https:\/\/github\.com\//.test(dc.verification_uri) ? link(dc.verification_uri, color) : sanitizeValue(dc.verification_uri);
   console.log(
     message(
@@ -832,6 +951,7 @@ ${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 replaced = await peekCredential();
   try {
     await saveToken({ token, handle });
   } catch (e) {
@@ -839,6 +959,13 @@ ${c.faint}waiting for GitHub approval\u2026 (Ctrl+C to cancel)${c.reset}`
     });
     throw e;
   }
+  if (replaced && replaced.base === BASE && replaced.token !== token) {
+    try {
+      await revokeYmmvToken(replaced.token);
+    } catch {
+      console.error(message(`${c.faint}(couldn't revoke the previous session's token)${c.reset}`));
+    }
+  }
   console.log(
     message(
       handle ? `Logged in as ${handle}.` : "Logged in. No handle bound (your GitHub username is a reserved word)."
@@ -847,14 +974,21 @@ ${c.faint}waiting for GitHub approval\u2026 (Ctrl+C to cancel)${c.reset}`
 }
 
 // src/api.ts
+var PublishRefusal = class extends Error {
+  constructor(msg) {
+    super(msg);
+    this.name = "PublishRefusal";
+  }
+};
+var ENV_TOKEN_REJECTED = "The server rejected the token in YMMV_TOKEN (revoked or expired).";
 async function rateLimitMessage(res) {
   return withRetryHint(await serverMessage(res) ?? "rate limited, too many requests", res);
 }
 async function ensureLogin() {
-  const existing = await loadToken();
+  const existing = await loadCredential();
   if (existing) return existing;
   await login();
-  const fresh = await loadToken();
+  const fresh = await loadCredential();
   if (!fresh) throw new Error("Login did not persist a token. Run `ymmv login`.");
   return fresh;
 }
@@ -874,35 +1008,60 @@ async function publishProfile(profile) {
   );
   let cred = await ensureLogin();
   if ((cred.handle ?? "").toLowerCase() !== profile.handle.toLowerCase()) {
-    throw new Error(
+    throw new PublishRefusal(
       "The stored login changed while this command was running. Re-run it under the current account."
     );
   }
   let res = await send(cred);
   if (res.status === 401 || res.status === 409) {
+    if (cred.source === "env") {
+      throw new PublishRefusal(
+        res.status === 401 ? `${ENV_TOKEN_REJECTED} Mint a new one with \`ymmv login\` on an interactive machine and update YMMV_TOKEN.` : "The server no longer accepts this handle for the YMMV_TOKEN account. Update YMMV_HANDLE, or mint a fresh token with `ymmv login`."
+      );
+    }
     const was401 = res.status === 401;
+    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 Error(
+      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.`
       );
     }
     res = await send(cred);
-    if (res.status === 401) throw new Error("Authentication failed. Run `ymmv login`.");
+    if (res.status === 401) throw new PublishRefusal("Authentication failed. Run `ymmv login`.");
     if (res.status === 409) {
+      const { slug, message: srvMsg } = wireErrorBody(await wireBody(res));
+      if (slug === "handle_not_bound") {
+        throw new PublishRefusal(
+          "The server still refuses this handle after a fresh login. Wait a moment and re-run the command."
+        );
+      }
       throw new Error(
-        await serverMessage(res) ?? "that handle is taken by another account (your GitHub handle may have been reused)."
+        srvMsg ?? "that handle is taken by another account (your GitHub handle may have been reused)."
       );
     }
   }
   if (res.status === 429) throw new Error(await rateLimitMessage(res));
   if (!res.ok) {
-    throw new Error(`publish failed: ${res.status} ${wireText(await res.text())}`);
+    const raw = await wireBody(res);
+    const parsed = wireErrorBody(raw);
+    if (res.status === 400 && parsed.slug === "unsupported_schema_version") {
+      throw new PublishRefusal(parsed.message ?? `publish failed: ${res.status} ${wireText(raw)}`);
+    }
+    throw new Error(parsed.message ?? `publish failed: ${res.status} ${wireText(raw)}`);
+  }
+  let data = {};
+  try {
+    data = await res.json();
+  } catch {
   }
-  const data = await res.json();
   const shown = typeof data.handle === "string" ? sanitizeValue(data.handle) : profile.handle;
   return { handle: shown, url: `${BASE}/${shown}` };
 }
@@ -914,8 +1073,7 @@ async function fetchProfileJson(handle) {
   }
   return parseProfile(await res.json());
 }
-async function deleteProfile() {
-  const cred = await ensureLogin();
+async function deleteProfile(cred) {
   const res = await safeFetch(
     `${BASE}/api/v1/profile`,
     {
@@ -926,11 +1084,14 @@ async function deleteProfile() {
     BASE
   );
   if (res.status === 401) {
-    throw new Error("Session expired. Run `ymmv login`, then `ymmv delete` again.");
+    throw new Error(
+      cred.source === "env" ? `${ENV_TOKEN_REJECTED} Update YMMV_TOKEN and run \`ymmv delete\` again.` : "Session expired. Run `ymmv login`, then `ymmv delete` again."
+    );
   }
   if (res.status === 429) throw new Error(await rateLimitMessage(res));
   if (!res.ok) {
-    throw new Error(`delete failed: ${res.status} ${wireText(await res.text())}`);
+    const raw = await wireBody(res);
+    throw new Error(wireErrorBody(raw).message ?? `delete failed: ${res.status} ${wireText(raw)}`);
   }
 }
 
@@ -1299,7 +1460,7 @@ function requireHandle(cred) {
   if (cred.handle) return cred.handle;
   console.error(
     message(
-      "Your GitHub username is a reserved word, so no handle is bound. Rename on GitHub, then run `ymmv login` again."
+      cred.source === "env" ? "YMMV_TOKEN is set but YMMV_HANDLE is not. Set YMMV_HANDLE to the GitHub username the token belongs to." : "Your GitHub username is a reserved word, so no handle is bound. Rename on GitHub, then run `ymmv login` again."
     )
   );
   process.exitCode = 1;
@@ -1334,9 +1495,21 @@ async function promptEntries(defaults, prompter) {
   console.log(message(`${c.faint}Enter to keep, "-" to clear${c.reset}`));
   const chosen = /* @__PURE__ */ new Map();
   for (const key of CURATED_KEYS) {
-    const answer = (await prompter.ask(KEY_LABELS[key], defaults.get(key))).trim();
-    const value = answer === "-" ? "" : answer;
-    if (value) chosen.set(key, value);
+    for (; ; ) {
+      const answer = (await prompter.ask(KEY_LABELS[key], defaults.get(key))).trim();
+      const value = answer === "-" ? "" : answer;
+      if (value.length > MAX_VALUE) {
+        const isDefault = value === (defaults.get(key) ?? "").trim();
+        console.log(
+          message(
+            `${c.faint}${isDefault ? `the saved value is ${value.length} characters; the cap is ${MAX_VALUE}. Type a shorter value or - to clear` : `that value is ${value.length} characters; the cap is ${MAX_VALUE}`}${c.reset}`
+          )
+        );
+        continue;
+      }
+      if (value) chosen.set(key, value);
+      break;
+    }
   }
   return chosen;
 }
@@ -1391,6 +1564,16 @@ async function publish(io) {
   let values = defaults;
   const assemble = () => [...entriesFromMap(values), ...carried];
   if (!io.interactive || !io.prompter || io.yes) {
+    const over = [...values].find(([, v]) => v.length > MAX_VALUE);
+    if (over) {
+      console.error(
+        message(
+          `The detected ${KEY_LABELS[over[0]]} value is ${over[1].length} characters; the cap is ${MAX_VALUE}. Set a shorter one: ymmv set ${over[0]} <value>.`
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
     const entries = assemble();
     showCard(entries);
     printPublished(await publishProfile(newProfile(handle, entries, extras)), color);
@@ -1408,8 +1591,20 @@ async function publish(io) {
         "Y/n/e=edit"
       );
       if (ans === "y") {
-        printPublished(await publishProfile(newProfile(handle, entries, extras)), color);
-        return;
+        try {
+          printPublished(await publishProfile(newProfile(handle, entries, extras)), color);
+          return;
+        } catch (e) {
+          if (e instanceof PromptAborted || e instanceof PublishRefusal) throw e;
+          const ambiguous = e instanceof NetworkError || isTimeoutError(e);
+          console.error(
+            message(
+              `${displayError(e)}
+${ambiguous ? "The publish may not have completed. Your answers are kept." : "Nothing was published. Your answers are kept."}`
+            )
+          );
+          continue;
+        }
       }
       if (ans === "n") {
         console.log(message("Aborted. Nothing published."));
@@ -1436,7 +1631,11 @@ async function view(handle) {
   }
   const cred = await loadToken();
   if (cred?.handle) {
-    const mine = await fetchProfileJson(cred.handle).catch(() => null);
+    let mineFailed = false;
+    const mine = await fetchProfileJson(cred.handle).catch(() => {
+      mineFailed = true;
+      return null;
+    });
     if (mine && mine.handle.toLowerCase() !== theirs.handle.toLowerCase()) {
       console.log(
         renderDiff(diff(mine, theirs), { color: c, theirsLabel: theirs.handle, mineLabel: "you" })
@@ -1445,7 +1644,12 @@ async function view(handle) {
     }
     if (!mine) {
       console.log(renderProfile(theirs, { color: c, site: displayUrl(BASE) }));
-      console.log(nudge(c));
+      if (mineFailed) {
+        const codes = palette(c);
+        console.error(message(`${codes.faint}(couldn't load your profile to diff)${codes.reset}`));
+      } else {
+        console.log(nudge(c));
+      }
       return;
     }
   }
@@ -1458,6 +1662,15 @@ async function runSet(target) {
   const existing = await fetchProfileJson(handle);
   assertHandleUnchanged(existing, handle);
   const { entries, extras } = applySet(existing, target);
+  if (target.kind === "extra" && extras.length > MAX_EXTRAS) {
+    console.error(
+      message(
+        `Your profile already has ${MAX_EXTRAS} extras; that's the cap. Remove one first: ymmv unset --extra "Label".`
+      )
+    );
+    process.exitCode = 1;
+    return;
+  }
   const res = await publishProfile(newProfile(handle, entries, extras));
   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)}`));
@@ -1487,7 +1700,7 @@ async function runUnset(target) {
 }
 async function runDelete(io) {
   const cred = await ensureLogin();
-  const target = cred.handle ? `${displayUrl(BASE)}/${sanitizeValue(cred.handle)}` : "your profile";
+  const target = cred.source === "env" ? "the profile bound to YMMV_TOKEN" : cred.handle ? `${displayUrl(BASE)}/${sanitizeValue(cred.handle)}` : "your profile";
   if (!io.yes) {
     if (!io.interactive || !io.prompter) {
       console.error(
@@ -1515,8 +1728,8 @@ ${message("Cancelled. Nothing deleted.")}`);
       return;
     }
   }
-  await deleteProfile();
-  await deleteToken();
+  await deleteProfile(cred);
+  if (cred.source === "file") await deleteToken();
   console.log(message(`Deleted ${target}. Run \`ymmv\` to publish again.`));
 }
 
@@ -1526,15 +1739,33 @@ var UNSET_EXTRA = 'ymmv unset --extra "Label"';
 var SET_USAGE = `usage: ymmv set <key> <value>  |  ${SET_EXTRA}`;
 var EXTRA_USAGE = `usage: ${SET_EXTRA}`;
 var UNSET_USAGE = `usage: ymmv unset <key>  |  ${UNSET_EXTRA}`;
+var VIEW_USAGE = "usage: ymmv view <handle>";
 function invalidKeyError(head, hint) {
   return {
     kind: "error",
-    message: `"${head}" is not a curated key. Valid keys: ${CURATED_KEYS.join(", ")}.
+    message: `"${sanitizeValue(head)}" is not a curated key. Valid keys: ${CURATED_KEYS.join(", ")}.
 For anything else, use: ${hint}.`
   };
 }
-function hasYes(args) {
-  return args.includes("-y") || args.includes("--yes");
+function noArgs(verb, rest) {
+  return rest.length === 0 ? { kind: verb } : { kind: "error", message: `usage: ymmv ${verb}` };
+}
+function yesOnly(usage, rest, make) {
+  if (rest.length === 0) return make(false);
+  if (rest.length === 1 && (rest[0] === "-y" || rest[0] === "--yes")) return make(true);
+  return { kind: "error", message: usage };
+}
+function labelCapError(label) {
+  return {
+    kind: "error",
+    message: `That label is ${label.length} characters; the cap is ${MAX_LABEL}.`
+  };
+}
+function valueCapError(value) {
+  return {
+    kind: "error",
+    message: `That value is ${value.length} characters; the cap is ${MAX_VALUE}.`
+  };
 }
 function parseSet(rest) {
   const head = rest[0];
@@ -1546,6 +1777,8 @@ function parseSet(rest) {
     const value2 = spec.slice(eq + 1).trim();
     if (!label || !value2) return { kind: "error", message: EXTRA_USAGE };
     if (value2 === "-") return { kind: "unset", target: { kind: "extra", label } };
+    if (label.length > MAX_LABEL) return labelCapError(label);
+    if (value2.length > MAX_VALUE) return valueCapError(value2);
     return { kind: "set", target: { kind: "extra", label, value: value2 } };
   }
   if (!head) return { kind: "error", message: SET_USAGE };
@@ -1553,6 +1786,7 @@ function parseSet(rest) {
   const value = rest.slice(1).join(" ").trim();
   if (!value) return { kind: "error", message: `usage: ymmv set ${head} <value>` };
   if (value === "-") return { kind: "unset", target: { kind: "curated", key: head } };
+  if (value.length > MAX_VALUE) return valueCapError(value);
   return { kind: "set", target: { kind: "curated", key: head, value } };
 }
 function parseUnset(rest) {
@@ -1575,43 +1809,340 @@ function parseUnset(rest) {
 }
 function resolveArg(argv) {
   const first = argv[0];
+  const rest = argv.slice(1);
   if (first === "-h" || first === "--help" || first === "help") return { kind: "help" };
-  if (first === "-V" || first === "-v" || first === "--version") return { kind: "version" };
+  if (first === "-V" || first === "-v" || first === "--version" || first === "version") {
+    return rest.length === 0 ? { kind: "version" } : { kind: "error", message: "usage: ymmv version" };
+  }
   if (first === void 0) return { kind: "publish", yes: false };
-  if (first === "-y" || first === "--yes") return { kind: "publish", yes: true };
-  if (first === "login") return { kind: "login" };
-  if (first === "logout") return { kind: "logout" };
-  if (first === "delete") return { kind: "delete", yes: hasYes(argv.slice(1)) };
-  if (first === "set") return parseSet(argv.slice(1));
-  if (first === "unset") return parseUnset(argv.slice(1));
+  if (first === "-y" || first === "--yes") {
+    if (rest.length > 0) {
+      const example = rest[0] === "delete" || rest[0] === "publish" ? rest[0] : "publish";
+      return {
+        kind: "error",
+        message: `Put ${first} after the command: ymmv ${example} -y. A bare ymmv -y publishes without prompts.`
+      };
+    }
+    return { kind: "publish", yes: true };
+  }
+  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 }));
+  }
+  if (first === "delete") {
+    return yesOnly(
+      "usage: ymmv delete [-y] (deletes your own profile; takes no handle)",
+      rest,
+      (yes) => ({ kind: "delete", yes })
+    );
+  }
+  if (first === "set") return parseSet(rest);
+  if (first === "unset") return parseUnset(rest);
   if (first === "view") {
-    const handle = argv[1];
-    if (!handle) return { kind: "error", message: "usage: ymmv view <handle>" };
+    const handle = rest[0];
+    if (!handle) return { kind: "error", message: VIEW_USAGE };
     if (!isValidHandle(handle)) {
-      return { kind: "error", message: `"${handle}" is not a valid GitHub handle.` };
+      return { kind: "error", message: `"${sanitizeValue(handle)}" is not a valid GitHub handle.` };
     }
     if (isReserved(handle)) return reservedError(handle);
+    if (rest.length > 1) return { kind: "error", message: VIEW_USAGE };
     return { kind: "view", handle };
   }
   if (first.startsWith("-")) {
-    return { kind: "error", message: `Unknown option "${first}". Run \`ymmv help\`.` };
+    return {
+      kind: "error",
+      message: `Unknown option "${sanitizeValue(first)}". Run \`ymmv help\`.`
+    };
   }
   if (!isValidHandle(first)) {
     return {
       kind: "error",
-      message: `"${first}" is not a valid GitHub handle. Run \`ymmv help\`.`
+      message: `"${sanitizeValue(first)}" is not a valid GitHub handle. Run \`ymmv help\`.`
     };
   }
-  if (isReserved(first)) return reservedError(first);
+  if (isReserved(first)) return reservedError(first, true);
+  if (rest.length > 0) {
+    return { kind: "error", message: `Unexpected arguments after "${first}". Run \`ymmv help\`.` };
+  }
   return { kind: "view", handle: first };
 }
-function reservedError(handle) {
+function reservedError(handle, hintVerbs = false) {
+  const verb = handle.toLowerCase();
+  const hint = hintVerbs && CLI_VERBS.includes(verb) ? ` Did you mean: ymmv ${verb}?` : "";
   return {
     kind: "error",
-    message: `"${handle}" is a reserved name; it can't have a profile.`
+    message: `"${handle}" is a reserved name; it can't have a profile.${hint}`
   };
 }
 
+// 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)
 
@@ -1621,12 +2152,13 @@ ${c.faint}Usage:${c.reset}
   ymmv <handle>             view a profile; logged in, see the diff vs yours
   ymmv view <handle>        explicit view (same as ymmv <handle>)
   ymmv set <key> <value>    set one curated key
-  ymmv set --extra "L=V"    set a free-form extra
+  ymmv set --extra "L=V"    set a free-form extra (-e works too)
   ymmv unset <key>          remove one curated key (ymmv set <key> - works too)
   ymmv unset --extra "L"    remove a free-form extra
-  ymmv delete               delete your profile (permanent)
+  ymmv delete [-y]          delete your profile (permanent; -y skips the confirm)
   ymmv login | logout       GitHub device-flow auth
-  ymmv help | --version
+  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,
               font, theme, multiplexer, version-manager, dotfiles, ai-tool`;
@@ -1636,7 +2168,7 @@ async function logout() {
     const otherBase = await peekBase();
     console.log(
       message(
-        otherBase && otherBase !== BASE ? `Not logged in to ${BASE} (a token for ${otherBase} exists; set YMMV_API to that to log out of it).` : "Not logged in."
+        otherBase && otherBase !== BASE ? `Not logged in to ${BASE} (a token for ${sanitizeValue(otherBase)} exists; set YMMV_API to that to log out of it).` : "Not logged in."
       )
     );
     return;
@@ -1644,10 +2176,10 @@ async function logout() {
   let revoked;
   try {
     revoked = await revokeYmmvToken(stored.token);
-  } catch {
+  } catch (e) {
     console.error(
       message(
-        "Couldn't reach the server to revoke. Your token is still active. Run `ymmv logout` again when connected."
+        e instanceof NetworkError || isTimeoutError(e) ? "Couldn't reach the server to revoke. Your token is still active. Run `ymmv logout` again when connected." : "The server didn't confirm the revoke. Your token is still active. Run `ymmv logout` again shortly."
       )
     );
     process.exitCode = 1;
@@ -1657,12 +2189,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);
@@ -1673,8 +2214,30 @@ 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" && cmd.kind !== "update") {
+    const problem = baseProblem() ?? credentialEnvProblem();
+    if (problem) {
+      console.error(message(problem));
+      process.exitCode = 1;
+      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);
@@ -1699,12 +2262,23 @@ async function main(argv) {
     }
     case "logout":
       await logout();
+      if (process.env.YMMV_TOKEN) {
+        console.error(
+          message(
+            "Note: YMMV_TOKEN is set and still authenticates API calls. Unset it to stop using that token."
+          )
+        );
+      }
+      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.7.0",
+  "version": "0.9.0",
   "description": "Publish and diff terminal-native developer tool-stack profiles at ymmv.fyi.",
   "type": "module",
   "bin": {