llm-switcher 1.2.10 → 1.2.12

package/tests/update.e2e.test.mjs

@@ -0,0 +1,197 @@
+// A real gateway, run from a copy of this checkout that tracks a local bare repository. A release
+// pushed there must reach the running gateway through POST /api/update, and through --autoupdate at
+// start. Nothing here reaches the network or the real home directory.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { launchBrowser, skipReason } from './cdp.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+const ID = ['-c', 'user.name=t', '-c', 'user.email=t@t', '-c', 'commit.gpgsign=false', '-c', 'core.autocrlf=false'];
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+const freePort = () => new Promise(r => {
+  const s = net.createServer().listen(0, '127.0.0.1', () => { const { port } = s.address(); s.close(() => r(port)); });
+});
+
+function copySource(dest) {
+  const files = git(ROOT, 'ls-files', '--cached', '--others', '--exclude-standard').split(/\r?\n/).filter(Boolean);
+  for (const f of files) {
+    const from = path.join(ROOT, f);
+    if (!fs.existsSync(from)) continue;
+    fs.mkdirSync(path.dirname(path.join(dest, f)), { recursive: true });
+    fs.copyFileSync(from, path.join(dest, f));
+  }
+}
+
+function bumpVersion(dir, version) {
+  const p = path.join(dir, 'package.json');
+  fs.writeFileSync(p, JSON.stringify({ ...JSON.parse(fs.readFileSync(p, 'utf8')), version }, null, 2) + '\n');
+}
+
+// The npm registry answer only drives the dashboard notice; a git checkout updates from git.
+async function registry(t, version) {
+  const srv = http.createServer((req, res) => { res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ version })); });
+  await new Promise(r => srv.listen(0, '127.0.0.1', r));
+  t.after(() => srv.close());
+  return `http://127.0.0.1:${srv.address().port}/`;
+}
+
+async function fixture(t, { registryUrl = 'http://127.0.0.1:9/' } = {}) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-update-e2e-'));
+  const upstream = path.join(base, 'upstream.git');
+  const install = path.join(base, 'install');
+  const publisher = path.join(base, 'publisher');
+  git(base, 'init', '-q', '--bare', '-b', 'main', upstream);
+  fs.mkdirSync(install);
+  copySource(install);
+  git(install, 'init', '-q', '-b', 'main');
+  git(install, 'add', '-A');
+  git(install, ...ID, 'commit', '-q', '-m', 'installed');
+  git(install, 'remote', 'add', 'origin', upstream);
+  git(install, 'push', '-q', '-u', 'origin', 'main');
+  fs.mkdirSync(publisher);
+  git(publisher, 'init', '-q', '-b', 'main');
+  git(publisher, 'remote', 'add', 'origin', upstream);
+  git(publisher, 'fetch', '-q', 'origin');
+  git(publisher, 'checkout', '-q', '-b', 'main', '--track', 'origin/main');
+
+  const data = path.join(base, 'data');
+  const home = path.join(data, 'home');
+  fs.mkdirSync(home, { recursive: true });
+  const port = await freePort();
+  const cfgPath = path.join(data, 'config.json');
+  fs.writeFileSync(cfgPath, JSON.stringify({
+    port, blindfold: { port: await freePort() }, activeProfiles: { anthropic: null, responses: null, 'openai-chat': null, vertex: null },
+    profiles: { plain: { name: 'Plain', mode: 'convert', inFormat: 'auto', baseURL: 'http://127.0.0.1:9/v1', apiKey: 'k', defaultModels: { opus: 'o' } } }
+  }, null, 2));
+  const env = {
+    ...process.env, HOME: home, USERPROFILE: home, CODEX_HOME: path.join(home, '.codex'), CLAUDE_CONFIG_DIR: path.join(home, '.claude'),
+    LLM_SWITCHER_CONFIG: cfgPath, LLM_SWITCHER_STATE_DIR: data, LLM_SWITCHER_BLINDFOLD_CERTS: path.join(data, 'certs'),
+    LLM_SWITCHER_PORT: '', PORT: '', LLM_SWITCHER_REGISTRY_URL: registryUrl
+  };
+
+  let proc = null;
+  let log = '';
+  const pid = async () => {
+    try { return (await (await fetch(`http://127.0.0.1:${port}/health?challenge=t`)).json()).pid ?? null; } catch { return null; }
+  };
+  const fx = {
+    port,
+    log: () => log,
+    pid,
+    release(version) {
+      bumpVersion(publisher, version);
+      git(publisher, 'add', '-A');
+      git(publisher, ...ID, 'commit', '-q', '-m', `v${version}`);
+      git(publisher, 'push', '-q', 'origin', 'main');
+    },
+    async start(...extra) {
+      proc = spawn(process.execPath, [path.join(install, 'proxy.mjs'), '--port', String(port), ...extra], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+      proc.stdout.on('data', d => { log += d; });
+      proc.stderr.on('data', d => { log += d; });
+      return proc;
+    },
+    async waitFor(check, what) {
+      for (let i = 0; i < 120; i++) {
+        const v = await check();
+        if (v) return v;
+        await sleep(250);
+      }
+      throw new Error(`timed out waiting for ${what}\n${log}`);
+    },
+    cli: (...args) => new Promise((resolve) => {
+      const c = spawn(process.execPath, [path.join(install, 'switch.mjs'), ...args, '--port', String(port)], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      c.stdout.on('data', d => { out += d; });
+      c.stderr.on('data', d => { out += d; });
+      c.on('close', code => resolve({ code, out }));
+    }),
+    dashboardUrl: `http://127.0.0.1:${port}/ui`,
+    api: (p, opts = {}) => fetch(`http://127.0.0.1:${port}${p}`, {
+      ...opts,
+      headers: { 'x-llm-switcher-token': fs.readFileSync(path.join(data, 'admin.token'), 'utf8').trim(), 'Content-Type': 'application/json' }
+    })
+  };
+  t.after(async () => {
+    const live = await pid();
+    if (live) try { process.kill(live); } catch {}
+    proc?.kill();
+    await sleep(300);
+    fs.rmSync(base, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+  });
+  return fx;
+}
+
+async function readSse(res) {
+  const events = [];
+  for (const block of (await res.text()).split('\n\n')) {
+    const event = /^event: (.*)$/m.exec(block)?.[1];
+    if (event) events.push({ event, data: JSON.parse(/^data: (.*)$/m.exec(block)[1]) });
+  }
+  return events;
+}
+
+test('POST /api/update pulls the release and a new gateway takes over the port', { timeout: 90000 }, async (t) => {
+  const fx = await fixture(t);
+  const proc = await fx.start();
+  const oldPid = await fx.waitFor(fx.pid, 'the gateway');
+  assert.equal((await (await fx.api('/api/version')).json()).current, JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version);
+
+  fx.release('9.9.9');
+  const events = await readSse(await fx.api('/api/update', { method: 'POST', body: '{}' }));
+  const result = events.find(e => e.event === 'result')?.data;
+  assert.equal(result?.updated, true, JSON.stringify(events));
+  assert.equal(result.to, '9.9.9');
+
+  await fx.waitFor(async () => { const p = await fx.pid(); return p && p !== oldPid; }, 'the new gateway');
+  assert.equal((await (await fx.api('/api/version')).json()).current, '9.9.9');
+  // The first process stays as the parent: a service manager still sees the pid it started.
+  assert.equal(proc.exitCode, null);
+
+  const again = (await readSse(await fx.api('/api/update', { method: 'POST', body: '{}' }))).find(e => e.event === 'result')?.data;
+  assert.equal(again?.updated, false);
+  assert.match(again.reason, /latest/i);
+});
+
+test('--autoupdate starts the newest release', { timeout: 90000 }, async (t) => {
+  const fx = await fixture(t);
+  fx.release('9.9.10');
+  await fx.start('--autoupdate');
+  await fx.waitFor(fx.pid, 'the gateway');
+  assert.equal((await (await fx.api('/api/version')).json()).current, '9.9.10');
+  assert.match(fx.log(), /Pulled 1 commit/);
+});
+
+test('switch update asks the running gateway and waits for the new one', { timeout: 90000 }, async (t) => {
+  const fx = await fixture(t);
+  await fx.start();
+  await fx.waitFor(fx.pid, 'the gateway');
+  fx.release('9.9.11');
+  const r = await fx.cli('update');
+  assert.equal(r.code, 0, r.out);
+  assert.match(r.out, /runs v9\.9\.11/);
+  assert.equal((await (await fx.api('/api/version')).json()).current, '9.9.11');
+});
+
+test('the dashboard Update now button installs the release and reloads on the new gateway', { timeout: 90000, skip: skipReason() }, async (t) => {
+  const fx = await fixture(t, { registryUrl: await registry(t, '9.9.12') });
+  await fx.start();
+  await fx.waitFor(fx.pid, 'the gateway');
+  fx.release('9.9.12');
+  const browser = await launchBrowser();
+  t.after(() => browser.close());
+  const page = await browser.newPage();
+  await page.goto(fx.dashboardUrl);
+  await page.waitFor(`!document.getElementById('update-notice').hidden`, 'the update notice');
+  await page.click('#update-now');
+  await page.waitFor(`document.getElementById('app-version')?.textContent === 'v9.9.12'`, 'the reloaded dashboard on the new version', 30000);
+  assert.equal(await page.evaluate(`document.getElementById('update-notice').hidden`), true);
+});

package/tests/update.test.mjs

@@ -0,0 +1,145 @@
+// The update itself: a git checkout pulls fast-forward only, an npm install asks the registry.
+// Every remote here is a local bare repository or a local HTTP server.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { applyUpdate } from '../update.mjs';
+
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+const ID = ['-c', 'user.name=t', '-c', 'user.email=t@t', '-c', 'commit.gpgsign=false'];
+
+function writeVersion(dir, version) {
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'llm-switcher', version }) + '\n');
+}
+
+function commit(dir, msg) {
+  git(dir, 'add', '-A');
+  git(dir, ...ID, 'commit', '-q', '-m', msg);
+}
+
+// upstream.git <- publisher (pushes releases), and install (the checkout being updated).
+function fixture(t) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-update-'));
+  t.after(() => fs.rmSync(base, { recursive: true, force: true }));
+  const upstream = path.join(base, 'upstream.git');
+  const publisher = path.join(base, 'publisher');
+  const install = path.join(base, 'install');
+  git(base, 'init', '-q', '--bare', '-b', 'main', upstream);
+  for (const dir of [publisher, install]) {
+    fs.mkdirSync(dir);
+    git(dir, 'init', '-q', '-b', 'main');
+    git(dir, 'remote', 'add', 'origin', upstream);
+  }
+  writeVersion(publisher, '1.0.0');
+  commit(publisher, 'v1.0.0');
+  git(publisher, 'push', '-q', '-u', 'origin', 'main');
+  git(install, 'fetch', '-q', 'origin');
+  git(install, 'checkout', '-q', '-b', 'main', '--track', 'origin/main');
+  const release = (version) => {
+    writeVersion(publisher, version);
+    commit(publisher, `v${version}`);
+    git(publisher, 'push', '-q', 'origin', 'main');
+  };
+  return { install, release, head: () => git(install, 'rev-parse', 'HEAD') };
+}
+
+test('a checkout behind its upstream pulls and reports the new version', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const r = await applyUpdate({ root: fx.install });
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+  assert.equal(JSON.parse(fs.readFileSync(path.join(fx.install, 'package.json'), 'utf8')).version, '1.0.1');
+});
+
+test('a checkout level with its upstream does nothing', async (t) => {
+  const fx = fixture(t);
+  const r = await applyUpdate({ root: fx.install });
+  assert.equal(r.updated, false);
+  assert.match(r.reason, /latest/i);
+});
+
+test('a checkout with local edits is left alone, even when upstream moved', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const before = fx.head();
+  fs.appendFileSync(path.join(fx.install, 'package.json'), ' ');
+  const r = await applyUpdate({ root: fx.install });
+  assert.equal(r.updated, false);
+  assert.match(r.reason, /local changes/i);
+  assert.equal(fx.head(), before);
+});
+
+test('a checkout that is only ahead of upstream does nothing', async (t) => {
+  const fx = fixture(t);
+  fs.writeFileSync(path.join(fx.install, 'local.txt'), 'x');
+  commit(fx.install, 'local work');
+  const r = await applyUpdate({ root: fx.install });
+  assert.equal(r.updated, false);
+});
+
+test('a diverged checkout fails and is never merged', async (t) => {
+  const fx = fixture(t);
+  fs.writeFileSync(path.join(fx.install, 'local.txt'), 'x');
+  commit(fx.install, 'local work');
+  fx.release('1.0.1');
+  const before = fx.head();
+  await assert.rejects(applyUpdate({ root: fx.install }), /fast-forward|diverged/i);
+  assert.equal(fx.head(), before);
+});
+
+async function registry(t, version) {
+  const srv = http.createServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ version }));
+  });
+  await new Promise(r => srv.listen(0, '127.0.0.1', r));
+  t.after(() => srv.close());
+  return `http://127.0.0.1:${srv.address().port}/`;
+}
+
+function npmInstall(t, version) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'llmsw-npm-'));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  writeVersion(root, version);
+  return root;
+}
+
+test('an npm install on the latest version runs no install', async (t) => {
+  const root = npmInstall(t, '1.0.0');
+  const calls = [];
+  const r = await applyUpdate({ root, registryUrl: await registry(t, '1.0.0'), run: async (...a) => { calls.push(a); return ''; } });
+  assert.equal(r.updated, false);
+  assert.deepEqual(calls, []);
+});
+
+test('an npm install behind the registry installs that exact version globally', async (t) => {
+  const root = npmInstall(t, '1.0.0');
+  const calls = [];
+  const run = async (cmd, args) => { calls.push([cmd, ...args]); writeVersion(root, '1.0.1'); return ''; };
+  const r = await applyUpdate({ root, registryUrl: await registry(t, '1.0.1'), run });
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].slice(-3), ['install', '-g', 'llm-switcher@1.0.1']);
+});
+
+// launchd and systemd --user start the gateway with a short PATH that has no Homebrew or nvm npm.
+test('npm runs with the directory of the running node first on PATH', async (t) => {
+  const root = npmInstall(t, '1.0.0');
+  let env = null;
+  const run = async (cmd, args, opts) => { env = opts.env; writeVersion(root, '1.0.1'); return ''; };
+  await applyUpdate({ root, registryUrl: await registry(t, '1.0.1'), run });
+  const keys = Object.keys(env).filter(k => k.toUpperCase() === 'PATH');
+  assert.equal(keys.length, 1, `one PATH key, got ${keys.join(', ')}`);
+  assert.equal(env[keys[0]].split(path.delimiter)[0], path.dirname(process.execPath));
+});
+
+test('an unreachable registry is not an update', async (t) => {
+  const root = npmInstall(t, '1.0.0');
+  const r = await applyUpdate({ root, registryUrl: 'http://127.0.0.1:9/' });
+  assert.equal(r.updated, false);
+  assert.match(r.reason, /registry/i);
+});

package/ui.html

@@ -184,6 +184,8 @@
     .update-notice[hidden] { display: none; }
     .update-notice b { color: var(--warn); font-weight: 600; }
     .update-notice code { font-family: var(--font-mono); font-size: 0.72rem; overflow-wrap: anywhere; color: var(--muted); }
+    .update-notice .update-actions { display: flex; flex-wrap: wrap; gap: 0.4rem; }
+    .update-notice #update-status { color: var(--muted); overflow-wrap: anywhere; }
 
     aside nav { display: grid; gap: 0.25rem; }
     aside a.nav-link {
@@ -886,7 +888,11 @@
     <div id="update-notice" class="update-notice" role="status" hidden>
       <b>Update available: v<span id="update-latest"></span></b>
       <code id="update-command"></code>
-      <button type="button" class="btn btn-outline btn-sm" onclick="copyUpdateCommand()">Copy command</button>
+      <div class="update-actions">
+        <button type="button" id="update-now" class="btn btn-primary btn-sm" onclick="runUpdate()">Update now</button>
+        <button type="button" class="btn btn-outline btn-sm" onclick="copyUpdateCommand()">Copy command</button>
+      </div>
+      <span id="update-status" aria-live="polite" hidden></span>
     </div>
 
     <nav id="sideNav">
@@ -2678,6 +2684,69 @@
       navigator.clipboard.writeText(cmd).then(() => showToast('Copied: ' + cmd), () => showToast('Copy failed. Select the command and copy it by hand.', true));
     }
 
+    async function gatewayPid() {
+      try {
+        return (await (await fetch('/health?challenge=ui', { cache: 'no-store' })).json()).pid ?? null;
+      } catch {
+        return null;
+      }
+    }
+
+    // The gateway streams the update as SSE, then hands over to the new code. A new pid on /health
+    // means the new gateway answers; the reload then loads the new dashboard too.
+    async function runUpdate() {
+      const btn = document.getElementById('update-now');
+      const status = document.getElementById('update-status');
+      const say = (text) => { status.textContent = text; status.hidden = false; };
+      const reset = () => { btn.disabled = false; btn.textContent = 'Update now'; };
+      btn.disabled = true;
+      btn.textContent = 'Updating...';
+      say('Checking for the new release...');
+      try {
+        const before = await gatewayPid();
+        const res = await api('/api/update', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
+        if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error || 'HTTP ' + res.status);
+        let result = null, failed = null, buf = '';
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += decoder.decode(value, { stream: true });
+          let i;
+          while ((i = buf.indexOf('\n\n')) !== -1) {
+            const block = buf.slice(0, i);
+            buf = buf.slice(i + 2);
+            const event = /^event: (.*)$/m.exec(block)?.[1];
+            const data = JSON.parse(/^data: (.*)$/m.exec(block)?.[1] || 'null');
+            if (event === 'log') say(data.text);
+            else if (event === 'result') result = data;
+            else if (event === 'error') failed = data.message;
+          }
+        }
+        if (failed || !result) throw new Error(failed || 'The gateway closed the update without a result.');
+        if (!result.updated) {
+          say(result.reason);
+          reset();
+          return;
+        }
+        say('Installed v' + result.to + '. Restarting the gateway...');
+        for (let n = 0; n < 60; n++) {
+          await new Promise(r => setTimeout(r, 500));
+          const pid = await gatewayPid();
+          if (pid && pid !== before) {
+            location.reload();
+            return;
+          }
+        }
+        throw new Error('The new gateway did not answer. Read proxy.log.');
+      } catch (err) {
+        say(err.message);
+        showToast('Update failed: ' + err.message, true);
+        reset();
+      }
+    }
+
     document.addEventListener('DOMContentLoaded', () => {
       // Setup initial theme buttons state
       const currentTheme = document.documentElement.dataset.theme || 'dark';

package/update.mjs

@@ -0,0 +1,98 @@
+// Brings this install to the newest release: a git checkout pulls fast-forward only, an npm install
+// asks the registry and installs that exact version. Restarting the gateway is the caller's job.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { isNewer } from './version.mjs';
+
+const ROOT = path.dirname(fileURLToPath(import.meta.url));
+const REGISTRY_URL = 'https://registry.npmjs.org/llm-switcher/latest';
+const execFileAsync = promisify(execFile);
+
+// Async on purpose: the gateway runs this in-process, and a blocking install would stall every request.
+async function runCommand(cmd, args, opts = {}) {
+  const { stdout } = await execFileAsync(cmd, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+    timeout: 120000,
+    ...opts,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0', ...opts.env }
+  });
+  return stdout;
+}
+
+function readVersion(root) {
+  try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version || '0.0.0'; } catch { return '0.0.0'; }
+}
+
+// launchd and systemd --user give the gateway a short PATH without a Homebrew or nvm npm. The npm
+// next to the running node is the right one, and its launcher finds node on the same PATH.
+function envWithNodeFirst(env = process.env) {
+  const key = Object.keys(env).find(k => k.toUpperCase() === 'PATH') || 'PATH';
+  return { ...env, [key]: [path.dirname(process.execPath), env[key]].filter(Boolean).join(path.delimiter) };
+}
+
+const failure = (what, err) => new Error(`${what} failed: ${String(err.stderr || err.message).trim()}`);
+const noUpdate = (from, reason) => ({ updated: false, from, to: from, reason });
+
+async function updateCheckout(root, run, log) {
+  const git = (...args) => run('git', ['-C', root, ...args]);
+  const from = readVersion(root);
+  // A pull into edited files would mix someone's work in progress with the release.
+  if ((await git('status', '--porcelain', '--untracked-files=no')).trim()) {
+    return noUpdate(from, 'The checkout has local changes. Commit or stash them, then update.');
+  }
+  try {
+    await git('rev-parse', '--abbrev-ref', '@{u}');
+  } catch {
+    return noUpdate(from, 'The current branch has no upstream branch to update from.');
+  }
+  log('Fetching the upstream branch...');
+  try { await git('fetch', '--quiet'); } catch (err) { throw failure('git fetch', err); }
+  const behind = Number((await git('rev-list', '--count', 'HEAD..@{u}')).trim());
+  if (!behind) return noUpdate(from, `Already on the latest version (v${from}).`);
+  log(`Pulling ${behind} new commit(s)...`);
+  // --ff-only: a branch with local commits fails here instead of getting a merge commit.
+  try { await git('pull', '--ff-only', '--quiet'); } catch (err) { throw failure('git pull --ff-only', err); }
+  return { updated: true, from, to: readVersion(root), reason: `Pulled ${behind} commit(s).` };
+}
+
+async function updateNpmInstall(root, run, log, registryUrl) {
+  const from = readVersion(root);
+  let latest = null;
+  try {
+    const r = await fetch(registryUrl, { signal: AbortSignal.timeout(5000), headers: { accept: 'application/json' } });
+    if (r.ok) latest = (await r.json())?.version ?? null;
+  } catch {}
+  if (!latest) return noUpdate(from, 'Could not reach the npm registry.');
+  if (!isNewer(latest, from)) return noUpdate(from, `Already on the latest version (v${from}).`);
+  log(`Installing llm-switcher@${latest} from npm...`);
+  // npm.cmd is a batch file, and Node runs one only through cmd.exe. The cwd is the home directory,
+  // because Windows cannot replace a package directory that a process holds as its cwd.
+  const npmArgs = ['install', '-g', `llm-switcher@${latest}`];
+  const [cmd, args] = process.platform === 'win32' ? ['cmd.exe', ['/d', '/s', '/c', 'npm.cmd', ...npmArgs]] : ['npm', npmArgs];
+  try {
+    await run(cmd, args, { cwd: os.homedir(), timeout: 300000, env: envWithNodeFirst() });
+  } catch (err) {
+    throw failure('npm install', err);
+  }
+  const to = readVersion(root);
+  // npm can install into another prefix than the one this gateway runs from; then nothing changed here.
+  if (to === from) return noUpdate(from, `npm installed v${latest}, but not into ${root}.`);
+  return { updated: true, from, to, reason: `Installed v${to} from npm.` };
+}
+
+/** Returns { updated, from, to, reason }. Throws only when an update started and failed. */
+export async function applyUpdate({
+  root = ROOT,
+  run = runCommand,
+  logger = () => {},
+  registryUrl = process.env.LLM_SWITCHER_REGISTRY_URL || REGISTRY_URL
+} = {}) {
+  return fs.existsSync(path.join(root, '.git'))
+    ? updateCheckout(root, run, logger)
+    : updateNpmInstall(root, run, logger, registryUrl);
+}