ymmv-cli 0.8.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
@@ -47,7 +53,10 @@ via npm Trusted Publishing, with provenance.
 - `ymmv unset editor` removes one value (`ymmv set editor -` works too); `ymmv unset --extra "Keyboard"` removes an extra
 - `ymmv delete` removes your profile (`ymmv delete -y` skips the confirm, for scripts)
 - `ymmv login` / `ymmv logout` sign in / out
-- `ymmv version` prints the CLI version
+- `ymmv update` updates the CLI to the latest release (runs the matching upgrade for npm, pnpm,
+  and bun global installs; via npx it prints the invocation to use instead; anything else gets
+  the commands to run by hand)
+- `ymmv version` prints the CLI version (and notes a newer release when one is known)
 
 Values are capped at 256 characters and extra labels at 64; a profile holds up
 to 32 extras.
@@ -68,6 +77,9 @@ Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`. Full c
 - `YMMV_HANDLE` names the GitHub username `YMMV_TOKEN` belongs to. Required for `ymmv -y` and
   `ymmv set`/`unset` under an env token (there is no server lookup for it); ignored without
   `YMMV_TOKEN`.
+- `YMMV_NO_UPDATE_CHECK` disables the startup check for newer releases (the ecosystem-standard
+  `NO_UPDATE_NOTIFIER` works too). The check is also off automatically under `CI`, in pipes,
+  and in dev builds; it never blocks or fails a command.
 
 ## Publishing from CI
 
@@ -78,7 +90,7 @@ Every profile is open JSON too: `GET https://ymmv.fyi/api/v1/u/<handle>`. Full c
    `~/.config/ymmv/token.json` (Linux), `~/Library/Preferences/ymmv/token.json` (macOS),
    `%APPDATA%\ymmv\Config\token.json` (Windows).
 3. Set it as a CI secret named `YMMV_TOKEN`, and set `YMMV_HANDLE` to your GitHub username.
-4. Run `npx ymmv-cli -y` in the job.
+4. Run `npx ymmv-cli@latest -y` in the job.
 
 Two things to know:
 

package/dist/cli.js

@@ -349,7 +349,8 @@ var CLI_VERBS = [
   "view",
   "help",
   "publish",
-  "version"
+  "version",
+  "update"
 ];
 var RESERVED = [.../* @__PURE__ */ new Set([...RESERVED_ROUTES, ...CLI_VERBS])];
 var RESERVED_SET = new Set(RESERVED);
@@ -417,10 +418,10 @@ function isHttpUrl(value) {
   return HTTP_URL_RE.test(value.trim());
 }
 var NO_OSC8_TERMS = /* @__PURE__ */ new Set(["linux", "dumb"]);
-function link(url, color, term = process.env.TERM) {
+function link(url, color, term = process.env.TERM, label) {
   const clean = sanitizeValue(url).trim();
   if (!color) return clean;
-  const text = `${CODES.amber}${displayUrl(clean)}${CODES.reset}`;
+  const text = `${CODES.amber}${label ? sanitizeValue(label) : displayUrl(clean)}${CODES.reset}`;
   if (term !== void 0 && NO_OSC8_TERMS.has(term)) return text;
   return `${OSC}8;;${clean}${ST}${text}${OSC}8;;${ST}`;
 }
@@ -539,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
@@ -626,9 +627,6 @@ async function safeFetch(url, init, reach, fetchFn = globalThis.fetch) {
   }
 }
 
-// src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
-
 // src/config.ts
 function normalizeBase(raw) {
   return raw.replace(/\/+$/, "");
@@ -1827,7 +1825,7 @@ function resolveArg(argv) {
     }
     return { kind: "publish", yes: true };
   }
-  if (first === "login" || first === "logout") return noArgs(first, rest);
+  if (first === "login" || first === "logout" || first === "update") return noArgs(first, rest);
   if (first === "publish") {
     return yesOnly("usage: ymmv publish [-y]", rest, (yes) => ({ kind: "publish", yes }));
   }
@@ -1877,6 +1875,274 @@ function reservedError(handle, hintVerbs = false) {
   };
 }
 
+// src/update.ts
+import { spawn as nodeSpawn } from "child_process";
+import { homedir } from "os";
+
+// src/update-check.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { readFileSync as readFileSync2, realpathSync } from "fs";
+import { mkdir as mkdir2, readFile as readFile2, rename as rename2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
+import envPaths2 from "env-paths";
+var REGISTRY_URL = "https://registry.npmjs.org/ymmv-cli/latest";
+var RELEASES_URL = "https://github.com/ymmv-fyi/ymmv/releases";
+var FETCH_TIMEOUT_MS = 2e3;
+var FINISH_GRACE_MS = 500;
+var SUCCESS_TTL_MS = 24 * 60 * 60 * 1e3;
+var FAILURE_TTL_MS = 6 * 60 * 60 * 1e3;
+var VERSION_FRESH_MS = 7 * 24 * 60 * 60 * 1e3;
+function ownVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+function parseTriple(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function isNewer(latest, current) {
+  const l = parseTriple(latest);
+  const c = parseTriple(current);
+  if (!l || !c) return false;
+  for (let i = 0; i < 3; i++) {
+    if (l[i] !== c[i]) return l[i] > c[i];
+  }
+  return false;
+}
+function updateCachePath() {
+  return join2(envPaths2("ymmv", { suffix: "" }).config, "update-check.json");
+}
+async function readCache(path, now) {
+  try {
+    const parsed = JSON.parse(await readFile2(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const c = parsed;
+    if (typeof c.lastCheckedAt !== "number" || typeof c.ok !== "boolean") return null;
+    if (!Number.isFinite(c.lastCheckedAt) || c.lastCheckedAt > now) return null;
+    if (c.latest !== void 0 && typeof c.latest !== "string") return null;
+    if (c.latestAt !== void 0 && (!Number.isFinite(c.latestAt) || c.latestAt > now)) return null;
+    return { lastCheckedAt: c.lastCheckedAt, ok: c.ok, latest: c.latest, latestAt: c.latestAt };
+  } catch {
+    return null;
+  }
+}
+async function writeCache(path, cache) {
+  const tmp = `${path}.${randomUUID2()}.tmp`;
+  try {
+    await mkdir2(dirname2(path), { recursive: true });
+    await writeFile2(tmp, JSON.stringify(cache));
+    await rename2(tmp, path);
+  } catch {
+    await rm2(tmp, { force: true }).catch(() => {
+    });
+  }
+}
+function binRealpath() {
+  const raw = process.argv[1];
+  if (!raw) return void 0;
+  try {
+    return realpathSync(raw);
+  } catch {
+    return raw;
+  }
+}
+var NPM_PREFIX_ROOTS = /* @__PURE__ */ new Set(["usr", "local", "homebrew", "nodejs", "node", "installation"]);
+var VERSIONISH_RE = /^v?\d+(\.\d+)*$/;
+function detectInstallMethod(binPath) {
+  if (!binPath) return "unknown";
+  const segs = binPath.split(/[\\/]+/).filter(Boolean).map((s) => s.toLowerCase());
+  const has = (name) => segs.includes(name);
+  if (has("_npx")) return "ephemeral";
+  if (has("dlx") || segs.some((s) => s.startsWith("dlx-"))) return "ephemeral";
+  if (segs.some((s) => s.startsWith("bunx-"))) return "ephemeral";
+  if (has(".bun") && has("cache")) return "ephemeral";
+  if (has(".bun") && (has("global") || has("bin"))) return "bun-global";
+  if (has(".volta")) return "unknown";
+  if (segs.some((s, i) => s === "pnpm" && segs[i + 1] === "global")) return "pnpm-global";
+  if (has(".pnpm")) return "unknown";
+  const npmGlobal = segs.some(
+    (s, i) => s === "node_modules" && segs[i + 1] === "ymmv-cli" && (segs[i - 1] === "lib" && i >= 2 && (NPM_PREFIX_ROOTS.has(segs[i - 2]) || VERSIONISH_RE.test(segs[i - 2])) || segs[i - 1] === "npm")
+  );
+  if (npmGlobal) return "npm-global";
+  return "unknown";
+}
+function npxInvocation(latest) {
+  const triple = latest ? parseTriple(latest) : null;
+  return `npx ymmv-cli@${triple ? triple.join(".") : "latest"}`;
+}
+function formatUpdateNotice(current, latest, method, color, term) {
+  const cur = parseTriple(current);
+  const lat = parseTriple(latest);
+  if (!cur || !lat || !isNewer(lat.join("."), cur.join("."))) return null;
+  const latestClean = lat.join(".");
+  const currentClean = cur.join(".");
+  const cmd = method === "ephemeral" ? npxInvocation(latestClean) : "ymmv update";
+  const c = palette(color);
+  const headline = `ymmv-cli ${latestClean} is out`;
+  const linked = color ? link(RELEASES_URL, true, term, headline) : headline;
+  return `${linked} ${c.faint}(you have ${currentClean})${c.reset} \u2192 run ${c.bold}${cmd}${c.reset}`;
+}
+function updatesOptedOut(env) {
+  if (env.YMMV_NO_UPDATE_CHECK) return true;
+  if (env.NO_UPDATE_NOTIFIER) return true;
+  if (env.CI && env.CI !== "false") return true;
+  return false;
+}
+async function readCachedLatest(deps = {}) {
+  const now = (deps.now ?? Date.now)();
+  const cache = await readCache(deps.cachePath ?? updateCachePath(), now);
+  if (!cache?.latest || cache.latestAt === void 0) return null;
+  if (now - cache.latestAt > VERSION_FRESH_MS) return null;
+  const triple = parseTriple(cache.latest);
+  return triple ? triple.join(".") : null;
+}
+var GRACE = /* @__PURE__ */ Symbol("grace");
+function startUpdateCheck(deps = {}) {
+  const env = deps.env ?? process.env;
+  const nowFn = deps.now ?? Date.now;
+  const stderrIsTTY = deps.stderrIsTTY ?? Boolean(process.stderr.isTTY);
+  const inert = { finish: async () => null, abort: () => {
+  } };
+  if (updatesOptedOut(env)) return inert;
+  if (!stderrIsTTY) return inert;
+  const current = deps.currentVersion !== void 0 ? deps.currentVersion : ownVersion();
+  const currentTriple = current === null ? null : parseTriple(current);
+  if (!currentTriple || currentTriple.join(".") === "0.0.0") return inert;
+  const currentClean = currentTriple.join(".");
+  const cachePath = deps.cachePath ?? updateCachePath();
+  const doFetch = deps.fetch ?? globalThis.fetch;
+  const method = detectInstallMethod(deps.binPath ?? binRealpath());
+  const color = useColor(env, stderrIsTTY);
+  const term = env.TERM;
+  const controller = new AbortController();
+  const notice = (latest) => latest ? formatUpdateNotice(currentClean, latest, method, color, term) : null;
+  const check = (async () => {
+    const cache = await readCache(cachePath, nowFn());
+    if (cache && nowFn() - cache.lastCheckedAt < (cache.ok ? SUCCESS_TTL_MS : FAILURE_TTL_MS)) {
+      return notice(cache.latest);
+    }
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    timeout.unref?.();
+    let fetched = null;
+    try {
+      const res = await doFetch(REGISTRY_URL, {
+        signal: controller.signal,
+        headers: { accept: "application/json" }
+      });
+      if (res.ok) {
+        const body = await res.json();
+        if (typeof body.version === "string") fetched = body.version;
+      }
+    } catch {
+    } finally {
+      clearTimeout(timeout);
+    }
+    const triple = fetched === null ? null : parseTriple(fetched);
+    const canonical2 = triple ? triple.join(".") : void 0;
+    const now = nowFn();
+    await writeCache(cachePath, {
+      lastCheckedAt: now,
+      ok: canonical2 !== void 0,
+      latest: canonical2 ?? cache?.latest,
+      latestAt: canonical2 !== void 0 ? now : cache?.latestAt
+    });
+    return notice(canonical2 ?? cache?.latest);
+  })().catch(() => null);
+  return {
+    async finish() {
+      const result = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(GRACE), FINISH_GRACE_MS);
+        timer.unref?.();
+        void check.then((v) => {
+          clearTimeout(timer);
+          resolve(v);
+        });
+      });
+      if (result === GRACE) {
+        controller.abort();
+        return null;
+      }
+      return result;
+    },
+    abort() {
+      controller.abort();
+    }
+  };
+}
+
+// src/update.ts
+var UPGRADE_COMMANDS = {
+  "npm-global": "npm i -g ymmv-cli@latest",
+  "pnpm-global": "pnpm add -g ymmv-cli@latest",
+  "bun-global": "bun add -g ymmv-cli@latest"
+};
+var MANUAL_LIST = Object.values(UPGRADE_COMMANDS).map((cmd) => `  ${cmd}`).join("\n");
+var NOT_FOUND_CODES = /* @__PURE__ */ new Set([127, 9009]);
+function manualFallback(intro) {
+  return `${intro} Update with the command that matches your setup:
+${MANUAL_LIST}`;
+}
+async function runUpdate(deps = {}) {
+  const method = detectInstallMethod(deps.binPath ?? binRealpath());
+  const c = palette(colorEnabled());
+  if (method === "ephemeral") {
+    const cached = await readCachedLatest({ now: deps.now, cachePath: deps.cachePath });
+    const current = deps.currentVersion !== void 0 ? deps.currentVersion : ownVersion();
+    const pin = cached !== null && current !== null && isNewer(cached, current) ? cached : null;
+    console.log(
+      message(
+        `This run came from a package runner cache (npx-style), so there is no install to update.
+Next time run: ${c.bold}${npxInvocation(pin)}${c.reset}`
+      )
+    );
+    return;
+  }
+  if (method === "unknown") {
+    console.log(message(manualFallback("Couldn't tell how ymmv-cli was installed.")));
+    return;
+  }
+  const cmd = UPGRADE_COMMANDS[method];
+  const doSpawn = deps.spawn ?? nodeSpawn;
+  const failSpawn = () => {
+    console.error(message(manualFallback(`Couldn't run \`${cmd}\`.`)));
+    process.exitCode = 1;
+  };
+  console.log(message(`${c.faint}running${c.reset} ${c.bold}${cmd}${c.reset}`));
+  await new Promise((resolve) => {
+    let child;
+    try {
+      child = doSpawn(cmd, { stdio: "inherit", shell: true, cwd: homedir() });
+    } catch {
+      failSpawn();
+      resolve();
+      return;
+    }
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+      resolve();
+    };
+    child.on("error", () => {
+      settle(failSpawn);
+    });
+    child.on("exit", (code) => {
+      settle(() => {
+        if (code !== null && NOT_FOUND_CODES.has(code)) {
+          failSpawn();
+        } else if (code) {
+          process.exitCode = code;
+        }
+      });
+    });
+  });
+}
+
 // src/index.ts
 var help = (c) => `${c.bold}ymmv${c.reset}: terminal-native developer tool-stack profiles (ymmv.fyi)
 
@@ -1891,6 +2157,7 @@ ${c.faint}Usage:${c.reset}
   ymmv unset --extra "L"    remove a free-form extra
   ymmv delete [-y]          delete your profile (permanent; -y skips the confirm)
   ymmv login | logout       GitHub device-flow auth
+  ymmv update               update ymmv-cli to the latest release
   ymmv help | version
 
 ${c.faint}Curated keys:${c.reset} editor, os, shell, prompt, terminal, browser, window-manager,
@@ -1922,12 +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);
@@ -1938,9 +2214,12 @@ async function interactive(run, yes) {
     prompter?.close();
   }
 }
+function wantsUpdateCheck(kind) {
+  return kind !== "help" && kind !== "version" && kind !== "error" && kind !== "update";
+}
 async function main(argv) {
   const cmd = resolveArg(argv);
-  if (cmd.kind !== "logout") {
+  if (cmd.kind !== "logout" && cmd.kind !== "update") {
     const problem = baseProblem() ?? credentialEnvProblem();
     if (problem) {
       console.error(message(problem));
@@ -1948,6 +2227,17 @@ async function main(argv) {
       return;
     }
   }
+  const update = wantsUpdateCheck(cmd.kind) ? startUpdateCheck() : null;
+  try {
+    await dispatch(cmd);
+  } catch (e) {
+    update?.abort();
+    throw e;
+  }
+  const notice = await update?.finish();
+  if (notice) console.error(message(notice));
+}
+async function dispatch(cmd) {
   switch (cmd.kind) {
     case "publish":
       await interactive(publish, cmd.yes);
@@ -1980,11 +2270,15 @@ async function main(argv) {
         );
       }
       break;
+    case "update":
+      await runUpdate();
+      break;
     case "help":
       console.log(help(palette(colorEnabled())));
       break;
     case "version":
       printVersion();
+      await printLatestHint();
       break;
     case "error":
       console.error(message(cmd.message));

package/package.json

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