offgrid-ai 0.3.10 → 0.3.12

package/README.md

@@ -51,7 +51,7 @@ curl -fsSL https://raw.githubusercontent.com/eeshansrivastava89/offgrid-ai/main/
 
 1. **Auto-detect everything.** Scans for GGUF models in LM Studio, HuggingFace, and Ollama directories. Reads model metadata (quantization, context size, vision, thinking mode) directly from the GGUF file. No presets, no manual configuration.
 
-2. **One command to run.** `offgrid-ai` → pick a model → it figures out the flags, starts llama-server, syncs Pi config, and launches Pi.
+2. **One command to run.** `offgrid-ai` → pick a model → confirm context/KV memory settings on first setup → it starts llama-server, syncs Pi config, and launches Pi.
 
 3. **One model at a time.** Laptops have limited RAM. One server, one model, no confusion.
 
@@ -77,7 +77,7 @@ When you run `offgrid-ai` for the first time on a fresh machine:
    - **oMLX** — Apple Silicon optimized
 4. **Models** — If no models found, tells you where to get them.
 
-Subsequent runs skip everything that's already installed.
+Subsequent runs skip everything that's already installed. When a GGUF model is set up for the first time, offgrid-ai asks only for the memory-impacting choices: context window and KV cache precision. Sampling defaults are shown but not forced into a tuning wizard.
 
 ## Data directory
 

package/install.sh

@@ -144,8 +144,8 @@ fi
 INSTALLED_VERSION=""
 
 if [[ -n "$NPM_BIN" && -x "$NPM_BIN/offgrid-ai" ]]; then
-  # Get version
-  INSTALLED_VERSION="$(OFFGRID_NO_UPDATE_CHECK=1 "$NPM_BIN/offgrid-ai" version 2>/dev/null || echo "")"
+  # Get plain version from `offgrid-ai version` output (`offgrid-ai vX.Y.Z`).
+  INSTALLED_VERSION="$(OFFGRID_NO_UPDATE_CHECK=1 "$NPM_BIN/offgrid-ai" version 2>/dev/null | sed -E 's/^offgrid-ai v//' || echo "")"
 
   if command -v offgrid-ai &>/dev/null; then
     # Already on PATH — nothing to do
@@ -179,7 +179,7 @@ if [[ -n "$NPM_BIN" && -x "$NPM_BIN/offgrid-ai" ]]; then
 else
   # Fallback: try to find it anywhere on PATH after install
   if command -v offgrid-ai &>/dev/null; then
-    INSTALLED_VERSION="$(offgrid-ai version 2>/dev/null || echo "")"
+    INSTALLED_VERSION="$(OFFGRID_NO_UPDATE_CHECK=1 offgrid-ai version 2>/dev/null | sed -E 's/^offgrid-ai v//' || echo "")"
     ok "offgrid-ai ${INSTALLED_VERSION:+v${INSTALLED_VERSION} }installed at $(command -v offgrid-ai)"
   else
     echo ""

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "offgrid-ai",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Privacy-first CLI for running local LLMs — discover, configure, run, benchmark",
   "author": "Eeshan Srivastava (https://eeshans.com)",
   "type": "module",
   "bin": {
-    "offgrid-ai": "./bin/offgrid-ai.mjs"
+    "offgrid-ai": "bin/offgrid-ai.mjs"
   },
   "files": [
     "bin/*.mjs",

package/src/autodetect.mjs

@@ -5,7 +5,7 @@ import { readGgufMetadata } from "./gguf.mjs";
 // ── Detect model capabilities from GGUF metadata ──────────────────────────
 
 export function detectCapabilities(modelPath, mmprojPath) {
-  const meta = existsSync(modelPath) ? readGgufMetadata(modelPath) : {};
+  const meta = safeReadGgufMetadata(modelPath);
   const name = basename(modelPath).toLowerCase();
 
   // Architecture
@@ -17,7 +17,7 @@ export function detectCapabilities(modelPath, mmprojPath) {
   const thinking = hasThinkingKwargs || nameHintsThinking;
 
   // Vision — mmproj present
-  const vision = mmprojPath && existsSync(mmprojPath);
+  const vision = Boolean(mmprojPath && existsSync(mmprojPath));
 
   // MTP (multi-token prediction) — detect speculative decoding
   const mtp = /mtp/i.test(name) || architecture === "qwen3";
@@ -107,6 +107,15 @@ export function computeFlags(capabilities, modelPath, mmprojPath, draftModelPath
 
 // ── Internal helper ─────────────────────────────────────────────────────
 
+function safeReadGgufMetadata(modelPath) {
+  if (!existsSync(modelPath)) return {};
+  try {
+    return readGgufMetadata(modelPath);
+  } catch {
+    return {};
+  }
+}
+
 function numberMeta(meta, key) {
   const value = key ? meta[key] : undefined;
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;

package/src/cli.mjs

@@ -10,64 +10,41 @@ import { syncPiConfig, removeFromPiConfig, hasPiModel, launchPi, hasPi } from ".
 import { tailFriendly } from "./logs.mjs";
 import { estimateMemory } from "./estimate.mjs";
 import { pc, formatBytes, renderRows, renderSection, startInteractive, createPrompt, parseOptions } from "./ui.mjs";
+import { checkForUpdate, currentPackageVersion, detectInvocation, updateCommand, runUpdateCommand } from "./updates.mjs";
+import { removeInstallerPathEntries } from "./shell-path.mjs";
+import { configureLocalProfile } from "./profile-setup.mjs";
 
-// ── Update check ────────────────────────────────────────────────────────────
-
-const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 hours
+// ── Entry point ────────────────────────────────────────────────────────────
 
-async function checkForUpdate() {
-  if (process.env.OFFGRID_NO_UPDATE_CHECK) return null;
-  const { readFile, writeFile } = await import("node:fs/promises");
-  const { join } = await import("node:path");
-  const cacheFile = join(DATA_DIR, "update-cache.json");
+async function offerUpdate(argv) {
+  const invocation = detectInvocation();
+  const update = await checkForUpdate({ force: invocation === "npx" });
+  if (!update) return false;
 
-  // Read cached check
-  let cached;
-  try {
-    cached = JSON.parse(await readFile(cacheFile, "utf8"));
-  } catch { cached = null; }
+  const plan = updateCommand(invocation, argv);
+  console.log(pc.yellow(`\nUpdate available: v${update.latest}. You have v${update.current}.`));
+  console.log(pc.dim(`Run: ${plan.display}`));
+  console.log();
 
-  // Skip if checked recently
-  if (cached?.lastChecked && Date.now() - cached.lastChecked < UPDATE_CHECK_INTERVAL) {
-    return cached.latestVersion && cached.latestVersion !== cached.currentVersion ? { current: cached.currentVersion, latest: cached.latestVersion } : null;
-  }
+  if (!process.stdin.isTTY) return false;
 
-  // Fetch latest version from npm registry
+  const prompt = createPrompt();
   try {
-    const response = await fetch("https://registry.npmjs.org/offgrid-ai/latest", {
-      signal: AbortSignal.timeout(3000),
-    });
-    if (!response.ok) return null;
-    const body = await response.json();
-    const latestVersion = body.version;
-
-    // Get current version
-    const { readFileSync } = await import("node:fs");
-    const { dirname } = await import("node:path");
-    const { fileURLToPath } = await import("node:url");
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    const currentVersion = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
-
-    // Cache the result
-    await writeFile(cacheFile, JSON.stringify({ lastChecked: Date.now(), currentVersion, latestVersion }), "utf8");
-
-    return latestVersion !== currentVersion ? { current: currentVersion, latest: latestVersion } : null;
-  } catch {
-    // Network error or timeout — fail silently
-    return null;
+    const shouldUpdate = await prompt.yesNo("Update now?", false);
+    if (!shouldUpdate) return false;
+    await runUpdateCommand(plan);
+    if (plan.mode === "install-global") {
+      console.log(pc.green("Updated. Run offgrid-ai again to use the new version."));
+    }
+    return true;
+  } finally {
+    prompt.close();
   }
 }
 
-// ── Entry point ────────────────────────────────────────────────────────────
-
 export async function run(argv) {
   if (argv.length === 0) {
-    const update = await checkForUpdate();
-    if (update) {
-      console.log(pc.yellow(`\nUpdate available: ${update.latest}. You have v${update.current}.`));
-      console.log(pc.dim("Run: npm install -g offgrid-ai@latest"));
-      console.log();
-    }
+    if (await offerUpdate(argv)) return;
     return mainFlow();
   }
   const [command] = argv;
@@ -294,14 +271,19 @@ async function pickAndRun(prompt, profiles, newModels, managedItems) {
     const model = newModels.find((m) => m.path === modelPath);
     if (!model) throw new Error("Model not found.");
     const profile = await createProfileFromModel(model);
-    await saveProfile(profile);
-    console.log(pc.green(`Auto-configured: ${profile.label}`));
-    await syncPiConfig(profile);
-    return await runProfile(profile);
+    const configured = await configureLocalProfile(prompt, profile);
+    if (!configured) return;
+    await saveProfile(configured);
+    console.log(pc.green(`Saved profile: ${configured.label}`));
+    await syncPiConfig(configured);
+    return await runProfile(configured);
   }
 
   if (selected.startsWith("managed:")) {
-    const [, backendId, modelId] = selected.split(":");
+    const managedSelection = selected.slice("managed:".length);
+    const separator = managedSelection.indexOf(":");
+    const backendId = separator === -1 ? managedSelection : managedSelection.slice(0, separator);
+    const modelId = separator === -1 ? "" : managedSelection.slice(separator + 1);
     const model = managedItems.find((m) => m.model.id === modelId && m.backendId === backendId)?.model;
     if (!model) throw new Error("Model not found.");
     const profile = normalizeProfile({
@@ -342,10 +324,9 @@ async function runProfile(profile, options = {}) {
     console.log(pc.green(`[ready] ${backend.label} at ${profile.baseUrl}`));
   } else {
     const ready = await serverReady(profile.baseUrl);
-    if (ready && !options["reuse-existing"]) {
-      console.log(pc.green(`[ready] Server already running at ${profile.baseUrl}`));
-      console.log(pc.dim("Use --reuse-existing to reuse this server."));
-    } else if (!ready) {
+    if (ready) {
+      console.log(pc.green(`[ready] Reusing server at ${profile.baseUrl}`));
+    } else {
       console.log(pc.dim(`Starting ${backend.label} for ${profile.label}...`));
       let state;
       try {
@@ -840,11 +821,15 @@ async function uninstallCommand(argv) {
   const { options } = parseOptions(argv);
   const force = options.force || options.f;
 
-  if (!process.stdin.isTTY || force) {
-    // Non-interactive / forced: remove everything
+  if (!process.stdin.isTTY && !force) {
+    throw new Error("Non-interactive uninstall requires --force to avoid accidental data loss.");
+  }
+
+  if (force) {
+    await stopTrackedServers();
     await removeDataDir();
-    await removeSelf();
     await removeShellPath();
+    await removeSelf();
     return;
   }
 
@@ -881,8 +866,8 @@ async function uninstallCommand(argv) {
     // Remove the npm package
     const confirmUninstall = await prompt.yesNo("Uninstall offgrid-ai npm package?", true);
     if (confirmUninstall) {
-      await removeSelf();
       await removeShellPath();
+      await removeSelf();
     } else {
       console.log(pc.dim("Cancelled."));
     }
@@ -891,6 +876,14 @@ async function uninstallCommand(argv) {
   }
 }
 
+async function stopTrackedServers() {
+  const running = await runningProfiles();
+  for (const { profile } of running) {
+    const result = await stopProfile(profile);
+    console.log(result.stopped ? pc.green(`✓ ${result.message}`) : pc.dim(result.message));
+  }
+}
+
 async function removeDataDir() {
   const dataDir = DATA_DIR;
   if (existsSync(dataDir)) {
@@ -907,47 +900,13 @@ async function removeDataDir() {
 }
 
 async function removeShellPath() {
-  const { readFile, writeFile } = await import("node:fs/promises");
-  const { homedir } = await import("node:os");
-  const { promisify } = await import("node:util");
-  const { execFile } = await import("node:child_process");
-  let npmBin;
-  try {
-    const { stdout } = await promisify(execFile)("npm", ["bin", "-g"]);
-    npmBin = stdout.trim();
-  } catch { return; }
-  if (!npmBin) return;
-
-  const marker = "# Added by offgrid-ai installer";
-  const pathLine = `export PATH="${npmBin}:$PATH"`;
-  const rcFiles = [`${homedir()}/.zshrc`, `${homedir()}/.bashrc`, `${homedir()}/.bash_profile`];
-  let cleaned = false;
-
-  for (const rcFile of rcFiles) {
-    if (!existsSync(rcFile)) continue;
-    let content;
-    try { content = await readFile(rcFile, "utf8"); } catch { continue; }
-    if (!content.includes(npmBin) && !content.includes(marker)) continue;
-
-    const lines = content.split("\n");
-    const filtered = lines.filter((line, i) => {
-      // Remove the marker comment line
-      if (line.trim() === marker) return false;
-      // Remove the PATH export line added by the installer
-      if (line.trim() === pathLine) return false;
-      // Also remove a blank line that immediately precedes the marker (formatter)
-      if (i + 1 < lines.length && lines[i + 1].trim() === marker && line.trim() === "") return false;
-      return true;
-    });
-
-    if (filtered.length !== lines.length) {
-      await writeFile(rcFile, filtered.join("\n").replace(/\n{3,}/g, "\n\n") + "\n", "utf8");
-      console.log(pc.green(`✓ Cleaned PATH from ${rcFile}`));
-      cleaned = true;
-    }
-  }
-  if (!cleaned) {
+  const cleaned = await removeInstallerPathEntries();
+  if (cleaned.length === 0) {
     console.log(pc.dim("No offgrid-ai PATH entries found in shell configs."));
+    return;
+  }
+  for (const rcFile of cleaned) {
+    console.log(pc.green(`✓ Cleaned PATH from ${rcFile}`));
   }
 }
 
@@ -1015,19 +974,13 @@ async function scanManagedModels() {
 }
 
 async function printVersion() {
-  const { readFileSync } = await import("node:fs");
-  const { dirname, join } = await import("node:path");
-  const { fileURLToPath } = await import("node:url");
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  try {
-    const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
-    console.log(`offgrid-ai v${pkg.version}`);
-    const update = await checkForUpdate();
-    if (update) {
-      console.log(pc.yellow(`Update available: ${update.latest}. Run: npm install -g offgrid-ai@latest`));
-    }
-  } catch {
-    console.log("offgrid-ai v0.1.0");
+  const version = currentPackageVersion();
+  console.log(`offgrid-ai v${version}`);
+  const invocation = detectInvocation();
+  const update = await checkForUpdate({ force: invocation === "npx" });
+  if (update) {
+    const plan = updateCommand(invocation, ["version"]);
+    console.log(pc.yellow(`Update available: v${update.latest}. Run: ${plan.display}`));
   }
 }
 

package/src/profile-setup.mjs

@@ -0,0 +1,82 @@
+import { estimateMemory } from "./estimate.mjs";
+import { pc, formatBytes, renderRows, renderSection } from "./ui.mjs";
+
+const CACHE_CHOICES = [
+  { value: "bf16", label: "bf16", hint: "default: stable, good quality" },
+  { value: "f16", label: "f16", hint: "stable fallback, similar memory to bf16" },
+  { value: "q8_0", label: "q8_0", hint: "lower memory, usually safe" },
+  { value: "q4_0", label: "q4_0", hint: "lowest memory, quality/speed tradeoff" },
+];
+
+export async function configureLocalProfile(prompt, profile) {
+  console.log("");
+  console.log(renderSection("Model setup", renderRows([
+    ["Model", pc.bold(profile.label)],
+    ["Context", `${profile.flags.ctxSize.toLocaleString()} tokens`],
+    ["KV cache", `${profile.flags.cacheTypeK}/${profile.flags.cacheTypeV}`],
+    ["Sampling", samplingSummary(profile.flags)],
+  ])));
+  console.log(pc.dim("Larger context windows use more memory. KV cache precision controls memory used by attention history."));
+  console.log(pc.dim("Sampling defaults are shown for transparency; you can edit command.json later if needed.\n"));
+
+  const ctxSize = await prompt.number("Context window tokens", profile.flags.ctxSize, 1024, 1048576);
+  const cacheTypeK = await prompt.choice("K cache precision", CACHE_CHOICES, profile.flags.cacheTypeK);
+  const cacheTypeV = await prompt.choice("V cache precision", CACHE_CHOICES, profile.flags.cacheTypeV);
+  const configured = applyRuntimeFlagOverrides(profile, { ctxSize, cacheTypeK, cacheTypeV });
+
+  console.log("");
+  console.log(renderSection("Defaults", renderRows([
+    ["Temperature", configured.flags.temperature],
+    ["Top-p", configured.flags.topP],
+    ["Top-k", configured.flags.topK],
+    ["Min-p", configured.flags.minP],
+    ["Presence penalty", configured.flags.presencePenalty],
+    ["Repeat penalty", configured.flags.repeatPenalty],
+  ])));
+
+  console.log("\n" + renderMemoryEstimate(configured));
+  if (!(await prompt.yesNo("Save profile with these settings?", true))) return null;
+  return configured;
+}
+
+export function applyRuntimeFlagOverrides(profile, overrides) {
+  const flags = { ...profile.flags, ...overrides };
+  return {
+    ...profile,
+    flags,
+    baseUrl: `http://${flags.host}:${flags.port}/v1`,
+    commandArgv: updateArgv(profile.commandArgv ?? [], {
+      "--ctx-size": flags.ctxSize,
+      "--cache-type-k": flags.cacheTypeK,
+      "--cache-type-v": flags.cacheTypeV,
+    }),
+  };
+}
+
+function updateArgv(argv, values) {
+  const next = [...argv];
+  for (const [flag, value] of Object.entries(values)) {
+    const index = next.indexOf(flag);
+    if (index === -1) next.push(flag, String(value));
+    else next[index + 1] = String(value);
+  }
+  return next;
+}
+
+function renderMemoryEstimate(profile) {
+  try {
+    const est = estimateMemory(profile.modelPath, profile.mmprojPath, null, profile.flags);
+    return renderSection("Memory", renderRows([
+      ["Estimated total", pc.bold(`~${formatBytes(est.totalBytes)}`)],
+      ["Model", formatBytes(est.modelBytes)],
+      ["KV cache", est.kvBytes ? `~${formatBytes(est.kvBytes)} (${profile.flags.ctxSize.toLocaleString()} ctx, ${profile.flags.cacheTypeK}/${profile.flags.cacheTypeV})` : "unknown"],
+      ...(est.note ? [["Note", pc.yellow(est.note)]] : []),
+    ]));
+  } catch {
+    return renderSection("Memory", pc.dim("Estimate unavailable for this model."));
+  }
+}
+
+function samplingSummary(flags) {
+  return `temp ${flags.temperature}, top-p ${flags.topP}, top-k ${flags.topK}`;
+}

package/src/shell-path.mjs

@@ -0,0 +1,58 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+
+export const INSTALLER_PATH_MARKER = "# Added by offgrid-ai installer";
+
+export function defaultShellConfigFiles(home = homedir()) {
+  return [`${home}/.zshrc`, `${home}/.bashrc`, `${home}/.bash_profile`];
+}
+
+export function removeInstallerPathBlock(content) {
+  const lines = content.split("\n");
+  const kept = [];
+  let changed = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const next = lines[i + 1];
+
+    if (line.trim() === "" && next?.trim() === INSTALLER_PATH_MARKER) {
+      changed = true;
+      continue;
+    }
+
+    if (line.trim() === INSTALLER_PATH_MARKER) {
+      changed = true;
+      const following = lines[i + 1]?.trim() ?? "";
+      if (/^export\s+PATH=".+:\$PATH"$/u.test(following)) i += 1;
+      continue;
+    }
+
+    kept.push(line);
+  }
+
+  return {
+    changed,
+    content: kept.join("\n").replace(/\n{3,}/gu, "\n\n").replace(/\s+$/u, "") + "\n",
+  };
+}
+
+export async function removeInstallerPathEntries(rcFiles = defaultShellConfigFiles()) {
+  const cleaned = [];
+  for (const rcFile of rcFiles) {
+    if (!existsSync(rcFile)) continue;
+    let content;
+    try {
+      content = await readFile(rcFile, "utf8");
+    } catch {
+      continue;
+    }
+
+    const result = removeInstallerPathBlock(content);
+    if (!result.changed) continue;
+    await writeFile(rcFile, result.content, "utf8");
+    cleaned.push(rcFile);
+  }
+  return cleaned;
+}

package/src/ui.mjs

@@ -51,6 +51,7 @@ function handleCancel(value) {
 }
 
 export function renderRows(rows) {
+  if (rows.length === 0) return "";
   const width = Math.max(...rows.map(([key]) => stripVTControlCharacters(String(key)).length));
   return rows.map(([key, value]) => {
     const visible = stripVTControlCharacters(String(key)).length;
@@ -67,14 +68,21 @@ export function parseOptions(argv) {
   const options = {};
   for (let i = 0; i < argv.length; i++) {
     const item = argv[i];
+    if (item === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
     if (item.startsWith("--")) {
-      const key = item.slice(2);
+      const [key, inlineValue] = item.slice(2).split(/=(.*)/u, 2);
       const next = argv[i + 1];
-      if (next && !next.startsWith("--")) { options[key] = next; i += 1; }
+      if (inlineValue !== undefined) options[key] = inlineValue;
+      else if (next && !next.startsWith("-")) { options[key] = next; i += 1; }
       else options[key] = true;
+    } else if (/^-[A-Za-z]+$/u.test(item)) {
+      for (const key of item.slice(1)) options[key] = true;
     } else {
       positional.push(item);
     }
   }
   return { positional, options };
-}
+}

package/src/updates.mjs

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DATA_DIR } from "./config.mjs";
+
+const PACKAGE_NAME = "offgrid-ai";
+const UPDATE_CHECK_INTERVAL = 24 * 60 * 60 * 1000;
+
+export async function checkForUpdate({ now = Date.now(), fetchImpl = globalThis.fetch, force = false } = {}) {
+  if (process.env.OFFGRID_NO_UPDATE_CHECK) return null;
+
+  const currentVersion = currentPackageVersion();
+  const cacheFile = join(DATA_DIR, "update-cache.json");
+  const cached = await readUpdateCache(cacheFile);
+
+  if (!force && cached?.currentVersion === currentVersion && cached?.lastChecked && now - cached.lastChecked < UPDATE_CHECK_INTERVAL) {
+    return updateResult(currentVersion, cached.latestVersion);
+  }
+
+  try {
+    const response = await fetchImpl(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    const latestVersion = typeof body?.version === "string" ? body.version : null;
+    if (!latestVersion) return null;
+
+    await mkdir(DATA_DIR, { recursive: true });
+    await writeFile(cacheFile, JSON.stringify({ lastChecked: now, currentVersion, latestVersion }, null, 2) + "\n", "utf8");
+
+    return updateResult(currentVersion, latestVersion);
+  } catch {
+    return null;
+  }
+}
+
+export function currentPackageVersion() {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+  return pkg.version;
+}
+
+export function isNewerVersion(candidate, current) {
+  return compareVersions(candidate, current) > 0;
+}
+
+export function compareVersions(a, b) {
+  const left = versionParts(a);
+  const right = versionParts(b);
+  const len = Math.max(left.length, right.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+export function detectInvocation(env = process.env) {
+  const execPath = env.npm_execpath ?? "";
+  if (/(^|[\\/])npx-cli\.js$/u.test(execPath)) return "npx";
+  if (env.npm_command === "exec") return "npx";
+  return "global";
+}
+
+export function updateCommand(invocation = detectInvocation(), argv = []) {
+  if (invocation === "npx") {
+    const args = ["exec", "--yes", "--", `${PACKAGE_NAME}@latest`, ...argv];
+    return {
+      cmd: "npm",
+      args,
+      display: shellCommand("npm", args),
+      mode: "run-latest",
+    };
+  }
+
+  const args = ["install", "-g", `${PACKAGE_NAME}@latest`];
+  return {
+    cmd: "npm",
+    args,
+    display: shellCommand("npm", args),
+    mode: "install-global",
+  };
+}
+
+export function runUpdateCommand(plan) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(plan.cmd, plan.args, { stdio: "inherit" });
+    child.on("error", reject);
+    child.on("exit", (code) => code === 0 ? resolve() : reject(new Error(`${plan.cmd} exited with code ${code}`)));
+  });
+}
+
+async function readUpdateCache(cacheFile) {
+  try {
+    return JSON.parse(await readFile(cacheFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function updateResult(currentVersion, latestVersion) {
+  return isNewerVersion(latestVersion, currentVersion)
+    ? { current: currentVersion, latest: latestVersion }
+    : null;
+}
+
+function versionParts(value) {
+  return String(value)
+    .replace(/^v/u, "")
+    .split(/[.-]/u)
+    .map((part) => Number.parseInt(part, 10))
+    .filter((part) => Number.isFinite(part));
+}
+
+function shellCommand(cmd, args) {
+  return [cmd, ...args.map(shellQuote)].join(" ");
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  return /^[A-Za-z0-9_./:@=-]+$/u.test(text) ? text : JSON.stringify(text);
+}