ymmv-cli 0.6.2 → 0.8.0

package/README.md

@@ -40,18 +40,55 @@ 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 version` prints the CLI version
+
+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`.
+
+## 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 -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,10 +1,9 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
-
-// src/config.ts
-var BASE = (process.env.YMMV_API ?? "https://ymmv.fyi").replace(/\/+$/, "");
+// ../shared/dist/caps.js
+var MAX_EXTRAS = 32;
+var MAX_LABEL = 64;
+var MAX_VALUE = 256;
 
 // ../shared/dist/keys.js
 var CURATED_KEYS = [
@@ -282,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");
@@ -340,9 +340,22 @@ 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"
+];
 var RESERVED = [.../* @__PURE__ */ new Set([...RESERVED_ROUTES, ...CLI_VERBS])];
 var RESERVED_SET = new Set(RESERVED);
+function isReserved(handle) {
+  return RESERVED_SET.has(handle.toLowerCase());
+}
 var HANDLE_RE = /^[a-zA-Z0-9](?:-?[a-zA-Z0-9])*$/;
 function isValidHandle(handle) {
   return handle.length >= 1 && handle.length <= 39 && HANDLE_RE.test(handle);
@@ -385,7 +398,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;
 }
@@ -445,13 +460,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("");
@@ -526,6 +543,11 @@ function notFound(handle, color, base) {
 }
 
 // src/http.ts
+var REQUEST_TIMEOUT_MS = 3e4;
+var TIMEOUT_TEXT = "request timed out";
+function isTimeoutError(err) {
+  return err instanceof Error && (err.name === "TimeoutError" || err.cause instanceof Error && err.cause.name === "TimeoutError");
+}
 function causeText(err) {
   const pick = (e) => {
     if (e instanceof AggregateError) {
@@ -536,6 +558,7 @@ function causeText(err) {
     }
     return e.message;
   };
+  if (isTimeoutError(err)) return TIMEOUT_TEXT;
   let text;
   if (err instanceof Error) {
     const fromCause = err.cause instanceof Error ? pick(err.cause) : "";
@@ -549,17 +572,119 @@ function wireText(text) {
   const clean = sanitizeValue(String(text));
   return clean.length > 200 ? `${clean.slice(0, 200)}\u2026` : clean;
 }
+var INVISIBLE_RE = new RegExp("\\p{Default_Ignorable_Code_Point}", "gu");
+async function wireBody(res) {
+  try {
+    return await res.text();
+  } catch (err) {
+    if (isTimeoutError(err)) throw err;
+    return "";
+  }
+}
+function wireErrorBody(raw) {
+  try {
+    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()) out.message = clean;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+async function serverMessage(res) {
+  return wireErrorBody(await wireBody(res)).message;
+}
+function withRetryHint(msg, res) {
+  const retry = res.headers.get("retry-after");
+  return retry && /^\d+$/.test(retry) ? `${msg} (retry in ${retry}s)` : msg;
+}
+function displayError(err) {
+  if (err instanceof Error && err.name === "TimeoutError") return TIMEOUT_TEXT;
+  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, init);
+    return await fetchFn(url, {
+      ...init,
+      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
+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) {
+  try {
+    return await res.json();
+  } catch (err) {
+    if (isTimeoutError(err)) throw err;
+    return null;
+  }
+}
 async function mintYmmvToken(accessToken) {
   const res = await safeFetch(
     `${BASE}/api/v1/auth/token`,
@@ -575,20 +700,32 @@ async function mintYmmvToken(accessToken) {
     BASE
   );
   if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
     if (res.status === 503) {
       throw new Error(
-        body.message ? wireText(body.message) : "GitHub is unavailable. Run `ymmv login` again shortly."
+        await serverMessage(res) ?? "GitHub is unavailable. Run `ymmv login` again shortly."
       );
     }
     if (res.status === 429) {
-      const retry = res.headers.get("retry-after");
-      const msg = body.message ? wireText(body.message) : "Too many login attempts. Slow down and try again shortly";
-      throw new Error(retry && /^\d+$/.test(retry) ? `${msg} (retry in ${retry}s)` : msg);
+      throw new Error(
+        withRetryHint(
+          await serverMessage(res) ?? "Too many login attempts. Slow down and try again shortly",
+          res
+        )
+      );
     }
-    throw new Error(`login failed: ${res.status} ${wireText(body.error ?? "")}`.trim());
+    const body = await bodyJson(res) ?? {};
+    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 res.json().catch(() => null);
+  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.`
@@ -597,16 +734,23 @@ async function mintYmmvToken(accessToken) {
   return { token: data.token, handle: data.handle === null ? null : sanitizeValue(data.handle) };
 }
 async function revokeYmmvToken(token) {
-  const res = await fetch(`${BASE}/api/v1/auth/logout`, {
-    method: "POST",
-    headers: { authorization: `Bearer ${token}` },
-    // 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"
-  });
+  const res = await safeFetch(
+    `${BASE}/api/v1/auth/logout`,
+    {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}` },
+      // 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"
+    },
+    BASE
+  );
   if (!res.ok) throw new Error(`logout failed: ${res.status}`);
-  const body = await res.json().catch(() => ({}));
-  return body.revoked === true;
+  const body = await bodyJson(res);
+  if (!body || typeof body.revoked !== "boolean") {
+    throw new Error("logout failed: unexpected response");
+  }
+  return body.revoked;
 }
 
 // src/commands.ts
@@ -638,38 +782,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(
@@ -685,8 +840,14 @@ async function requestDeviceCode(deps = {}) {
   if (!res.ok) {
     throw new Error(`device code request failed: ${res.status} ${wireText(await res.text())}`);
   }
-  const data = await res.json().catch(() => null);
-  if (!data || typeof data.device_code !== "string" || typeof data.user_code !== "string" || typeof data.verification_uri !== "string" || typeof data.expires_in !== "number") {
+  const data = await res.json().catch((err) => {
+    if (isTimeoutError(err)) throw err;
+    return null;
+  });
+  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;
@@ -695,13 +856,14 @@ 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 = "";
   const MAX_TRANSIENT_FAILURES = 5;
   while (now() < deadline) {
     await sleep(interval * 1e3);
+    if (now() >= deadline) break;
     let res;
     try {
       res = await doFetch(TOKEN_URL, {
@@ -711,7 +873,12 @@ async function pollForToken(dc, deps = {}) {
           client_id: GITHUB_CLIENT_ID,
           device_code: dc.device_code,
           grant_type: "urn:ietf:params:oauth:grant-type:device_code"
-        })
+        }),
+        // GitHub answers this endpoint immediately — slow_down pacing lives in the sleep above,
+        // never inside a held request — so the per-request timeout can't cut pacing short. It only
+        // turns a HUNG poll into a TimeoutError feeding the transient counter (previously a hang
+        // here stalled the login forever: the deadline is only checked between iterations).
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
       });
     } catch (err) {
       lastCause = causeText(err);
@@ -720,9 +887,9 @@ async function pollForToken(dc, deps = {}) {
     if (res?.ok) {
       try {
         tok = await res.json();
-      } catch {
+      } catch (err) {
         tok = void 0;
-        lastCause = "unexpected response body";
+        lastCause = isTimeoutError(err) ? causeText(err) : "unexpected response body";
       }
     } else if (res) {
       lastCause = `HTTP ${res.status}`;
@@ -741,7 +908,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.");
@@ -759,9 +926,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(
@@ -771,6 +953,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) {
@@ -778,6 +961,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)."
@@ -786,21 +976,21 @@ ${c.faint}waiting for GitHub approval\u2026 (Ctrl+C to cancel)${c.reset}`
 }
 
 // src/api.ts
-async function rateLimitMessage(res) {
-  const retry = res.headers.get("retry-after");
-  let msg = "rate limited, too many requests";
-  try {
-    const body = await res.json();
-    if (typeof body?.message === "string" && body.message) msg = wireText(body.message);
-  } catch {
+var PublishRefusal = class extends Error {
+  constructor(msg) {
+    super(msg);
+    this.name = "PublishRefusal";
   }
-  return retry && /^\d+$/.test(retry) ? `${msg} (retry in ${retry}s)` : msg;
+};
+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;
 }
@@ -820,35 +1010,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(
-        "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}` };
 }
@@ -860,8 +1075,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`,
     {
@@ -872,11 +1086,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)}`);
   }
 }
 
@@ -1245,7 +1462,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;
@@ -1280,9 +1497,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;
 }
@@ -1337,6 +1566,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);
@@ -1354,8 +1593,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."));
@@ -1382,7 +1633,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" })
@@ -1391,7 +1646,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;
     }
   }
@@ -1404,6 +1664,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)}`));
@@ -1433,7 +1702,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(
@@ -1461,8 +1730,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.`));
 }
 
@@ -1472,15 +1741,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];
@@ -1492,6 +1779,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 };
@@ -1499,6 +1788,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) {
@@ -1521,34 +1811,71 @@ 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") 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, true);
+  if (rest.length > 0) {
+    return { kind: "error", message: `Unexpected arguments after "${first}". Run \`ymmv help\`.` };
+  }
   return { kind: "view", handle: first };
 }
+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.${hint}`
+  };
+}
 
 // src/index.ts
 var help = (c) => `${c.bold}ymmv${c.reset}: terminal-native developer tool-stack profiles (ymmv.fyi)
@@ -1557,14 +1884,14 @@ ${c.faint}Usage:${c.reset}
   ymmv                      detect your stack, confirm, and publish your profile
   ymmv -y                   publish without prompts (required when stdin isn't a TTY)
   ymmv <handle>             view a profile; logged in, see the diff vs yours
-  ymmv view <handle>        explicit view (when a handle collides with a verb)
+  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 help | version
 
 ${c.faint}Curated keys:${c.reset} editor, os, shell, prompt, terminal, browser, window-manager,
               font, theme, multiplexer, version-manager, dotfiles, ai-tool`;
@@ -1574,7 +1901,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;
@@ -1582,10 +1909,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;
@@ -1613,6 +1940,14 @@ async function interactive(run, yes) {
 }
 async function main(argv) {
   const cmd = resolveArg(argv);
+  if (cmd.kind !== "logout") {
+    const problem = baseProblem() ?? credentialEnvProblem();
+    if (problem) {
+      console.error(message(problem));
+      process.exitCode = 1;
+      return;
+    }
+  }
   switch (cmd.kind) {
     case "publish":
       await interactive(publish, cmd.yes);
@@ -1637,6 +1972,13 @@ 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 "help":
       console.log(help(palette(colorEnabled())));
@@ -1653,7 +1995,7 @@ async function main(argv) {
 
 // src/cli.ts
 main(process.argv.slice(2)).catch((err) => {
-  console.error(message(err instanceof Error ? err.message : String(err)));
+  console.error(message(displayError(err)));
   process.exitCode = 1;
 }).finally(() => {
   (process.exitCode ? process.stderr : process.stdout).write("\n");

package/package.json

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