llm-switcher 1.4.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog — LLM Switcher
 
+## Release 1.4.1 — 2026-10-07
+
+- **The update comes from npm, because that is where a release is published.** The gateway asked npm what the newest version is and ran `npm install -g llm-switcher@<version>` for exactly that version. Before, the install decided: a directory with a `.git` pulled and never asked npm, and the dashboard's Update now button read as a git operation on a project that ships to npm.
+- **A git checkout is the one install npm cannot serve, and it says so.** npm writes into the global prefix while the running code is the checkout itself, so the install lands somewhere nothing runs. The checkout is then asked, and it pulls fast-forward only. When npm held a release the checkout could not take, the notice names that version and what the checkout has, because "already the latest version" on its own would hide the one version the reader does not have.
+- **A failed npm install no longer fails the update of a checkout.** A checkout used to update without npm in the way. Asking npm first put an install between the reader and a pull, and any failure of that install -- a version the registry does not serve, a network, a read-only prefix -- ended the update even though the checkout could still have moved. Now a checkout reports what npm did and goes on to pull; an npm install with no checkout still fails loudly, because there is nothing else to try.
+
+Tests: 17 in `tests/update.test.mjs`, plus the rest of the suite.
+
 ## Release 1.4.0 — 2026-10-07
 
 - **A model answers with the tool names it was trained on, and the caller only runs its own.** A Codex model says `shell` where Claude Code declared `Bash`, and the turn ends with `Error: No such tool available: shell`. The gateway now writes the call back in the vocabulary the caller declared, and says the names in the prompt so most calls never need rewriting.

package/README.md

@@ -554,10 +554,9 @@ On Linux the unit is a systemd *user* service: it starts when you log in. To sta
 
 When npm has a newer release, the dashboard shows a notice. Click **Update now** in this notice. The gateway installs the release and starts the new code. Then the dashboard reloads. `switch update` does the same from a terminal.
 
-The gateway installs a release in one of two ways:
+The gateway installs a release from npm, because that is where a release is published. It asks the registry for the newest version and runs `npm install -g llm-switcher@<version>`, then restarts into it.
 
-- A git checkout runs `git pull --ff-only`. If the checkout has local changes, or commits that are not on the upstream branch, the update stops and changes nothing.
-- An npm install runs `npm install -g llm-switcher@<latest>`.
+A git checkout is the one install npm cannot serve: npm writes into the global prefix while the running code is the checkout itself. So when npm did not move the directory the gateway runs from, and that directory is a checkout, the checkout is asked next, and it runs `git pull --ff-only`. If the checkout has local changes, or commits that are not on the upstream branch, the update stops and changes nothing. When npm held a release the checkout could not take, the notice says both: which version npm has, and that the checkout has nothing.
 
 Requests that are open on the gateway when the update starts finish on the old code. New requests go to the new code. The Codex interceptor stops, and the new gateway starts it again. Thus a Codex request that is open at that moment fails one time. The old process stays as the parent of the new process until the gateway stops. Thus a service manager keeps the process that it started.
 

package/README.vi.md

@@ -552,10 +552,9 @@ Trên Linux, unit là service systemd *của user*: nó khởi động khi bạn
 
 Khi npm có bản mới, dashboard hiện một thông báo. Bấm **Update now** trong thông báo này. Gateway cài bản mới và chạy code mới. Sau đó dashboard tự tải lại. `switch update` làm việc tương tự từ terminal.
 
-Gateway cài bản mới theo một trong hai cách:
+Gateway cài bản mới từ npm, vì đó là nơi bản phát hành được đăng. Nó hỏi registry lấy số phiên bản mới nhất rồi chạy `npm install -g llm-switcher@<phiên bản>`, sau đó khởi động lại vào bản đó.
 
-- Bản git checkout chạy `git pull --ff-only`. Nếu checkout có thay đổi cục bộ, hoặc có commit không nằm trên nhánh upstream, việc cập nhật dừng lại và không đổi gì.
-- Bản cài bằng npm chạy `npm install -g llm-switcher@<latest>`.
+Bản git checkout là thứ duy nhất npm không phục vụ được: npm ghi vào global prefix, trong khi code đang chạy chính là thư mục checkout. Nên khi npm không dịch chuyển được thư mục mà gateway đang chạy, và thư mục đó là một checkout, gateway hỏi tiếp checkout, và checkout chạy `git pull --ff-only`. Nếu checkout có thay đổi cục bộ, hoặc có commit không nằm trên nhánh upstream, việc cập nhật dừng lại và không đổi gì. Khi npm có bản mới mà checkout không lấy được, thông báo nói cả hai: npm đang có số phiên bản nào, và checkout không có gì để cập nhật.
 
 Các request đang chạy trên gateway lúc cập nhật sẽ chạy xong trên code cũ. Request mới đi vào code mới. Interceptor của Codex dừng lại, và gateway mới khởi động nó lại. Vì vậy một request Codex đang chạy đúng lúc đó sẽ lỗi một lần. Tiến trình cũ ở lại làm tiến trình cha của tiến trình mới cho tới khi gateway dừng. Nhờ vậy service manager vẫn giữ đúng tiến trình mà nó đã khởi động.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-switcher",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Zero-dependency multi-protocol edge gateway & provider switcher for Claude Code and Codex, with OpenAI-compatible, Anthropic and Vertex upstreams",
   "keywords": [
     "llm",

package/tests/update.test.mjs

@@ -1,14 +1,29 @@
-// 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.
+// The update itself: npm is asked first and installs the version the registry names; a git
+// checkout is the fallback, and pulls fast-forward only. 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 { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
 import { applyUpdate } from '../update.mjs';
 
+const execFileAsync = promisify(execFile);
+
+// Records every command in the order it is asked. git runs for real, because the checkout has to
+// move before the fallback can be observed. npm's install is recorded and not run: the version a
+// fixture registry names is a number from the test, not one the real registry serves, and a real
+// install would put a package on the machine running the suite.
+const recording = (calls) => async (cmd, args, opts) => {
+  calls.push([cmd, ...args]);
+  if (cmd === 'npm' || cmd === 'cmd.exe') return '';
+  const { stdout } = await execFileAsync(cmd, args, { encoding: 'utf8', ...opts });
+  return stdout;
+};
+
 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'];
 
@@ -50,14 +65,14 @@ function fixture(t) {
 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 });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   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 });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.equal(r.updated, false);
   assert.match(r.reason, /latest/i);
 });
@@ -66,7 +81,7 @@ test('a gateway that runs older code than its checkout restarts into it, with no
   const fx = fixture(t);
   fx.release('1.0.1');
   git(fx.install, 'pull', '-q', '--ff-only');
-  const r = await applyUpdate({ root: fx.install, running: '1.0.0' });
+  const r = await applyUpdate({ root: fx.install, running: '1.0.0', registryUrl: await registry(t, '1.0.1') });
   assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
 });
 
@@ -75,7 +90,7 @@ test('a checkout with local edits is left alone, even when upstream moved', asyn
   fx.release('1.0.1');
   const before = fx.head();
   fs.appendFileSync(path.join(fx.install, 'package.json'), ' ');
-  const r = await applyUpdate({ root: fx.install });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.equal(r.updated, false);
   assert.match(r.reason, /local changes/i);
   assert.equal(fx.head(), before);
@@ -85,7 +100,7 @@ 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 });
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') });
   assert.equal(r.updated, false);
 });
 
@@ -95,7 +110,7 @@ test('a diverged checkout fails and is never merged', async (t) => {
   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);
+  await assert.rejects(applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0') }), /fast-forward|diverged/i);
   assert.equal(fx.head(), before);
 });
 
@@ -159,3 +174,71 @@ test('an unreachable registry is not an update', async (t) => {
   assert.equal(r.updated, false);
   assert.match(r.reason, /registry/i);
 });
+
+// ---- npm first, and the checkout only when npm cannot serve it ----
+
+test('a release on npm is installed before the checkout is asked at all', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const calls = [];
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.1'), run: recording(calls) });
+
+  const order = calls.map(c => c[0]);
+  assert.deepEqual(order.slice(0, 2), ['npm', 'git'], `npm first, then the checkout: ${order.join(' ')}`);
+  assert.deepEqual(calls[0].slice(-3), ['install', '-g', 'llm-switcher@1.0.1']);
+  // npm put the release in the global prefix, which is not this directory, so the checkout is what
+  // moved -- and that is the version this gateway runs, which is the only reason the pull happened.
+  assert.match(r.reason, /Pulled 1 commit/);
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+});
+
+test('a checkout level with its upstream runs no git pull when npm had nothing newer', async (t) => {
+  const fx = fixture(t);
+  const calls = [];
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.0'), run: recording(calls) });
+
+  assert.equal(calls.some(c => c[0] === 'npm' && c.includes('install')), false, 'no install when npm is not newer');
+  assert.equal(calls.some(c => c.includes('pull')), false, 'nothing to pull');
+  assert.match(r.reason, /latest/i);
+});
+
+test('npm holding a release the checkout cannot take is said plainly, not hidden by "latest"', async (t) => {
+  const fx = fixture(t);
+  // The checkout is level, and the registry is a version ahead of it: the two answers disagree.
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.4.0'), run: recording([]) });
+
+  assert.equal(r.updated, false);
+  assert.match(r.reason, /npm installed v1\.4\.0, but not into/);
+  assert.match(r.reason, /latest/i, 'the checkout answer is kept as well');
+});
+
+test('a checkout is still updated by git when the registry cannot be reached', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const r = await applyUpdate({ root: fx.install, registryUrl: 'http://127.0.0.1:9/' });
+
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+});
+
+test('an npm install that fails does not stop a checkout from updating', async (t) => {
+  const fx = fixture(t);
+  fx.release('1.0.1');
+  const logs = [];
+  // npm refuses the version a fixture registry names, the way a real registry would.
+  const run = async (cmd, args, opts) => {
+    if (cmd === 'npm') throw new Error('npm install failed: notarget No matching version found');
+    return recording([])(cmd, args, opts);
+  };
+  const r = await applyUpdate({ root: fx.install, registryUrl: await registry(t, '1.0.1'), run, logger: m => logs.push(m) });
+
+  assert.deepEqual({ updated: r.updated, from: r.from, to: r.to }, { updated: true, from: '1.0.0', to: '1.0.1' });
+  assert.match(r.reason, /Pulled 1 commit/);
+  // The npm failure is said out loud, not swallowed into a success nobody can explain.
+  assert.match(logs.join('\n'), /npm could not install it here/);
+});
+
+test('an npm install behind the registry still fails loudly when there is no checkout', async (t) => {
+  const root = npmInstall(t, '1.0.0');
+  const run = async () => { throw new Error('npm install failed: EACCES'); };
+  await assert.rejects(applyUpdate({ root, registryUrl: await registry(t, '1.0.1'), run }), /npm install failed/);
+});

package/update.mjs

@@ -1,5 +1,8 @@
-// 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.
+// Brings this install to the newest release. A release is published to npm, so npm is what is asked
+// first: `npm install -g llm-switcher@<version>` for the exact version the registry names. A git
+// checkout is the one install npm cannot serve, because npm writes into the global prefix while the
+// running code is the checkout itself, so the checkout is asked second and only then. Restarting
+// the gateway is the caller's job.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -80,8 +83,9 @@ async function updateNpmInstall(root, run, log, registryUrl) {
     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}.`);
+  // npm installs into the global prefix. When this gateway runs from a checkout that is a different
+  // directory, so the registry can name a release this code never receives; `elsewhere` says so.
+  if (to === from) return { ...noUpdate(from, `npm installed v${latest}, but not into ${root}.`), elsewhere: latest };
   return { updated: true, from, to, reason: `Installed v${to} from npm.` };
 }
 
@@ -93,10 +97,27 @@ export async function applyUpdate({
   registryUrl = process.env.LLM_SWITCHER_REGISTRY_URL || REGISTRY_URL,
   running = CURRENT_VERSION
 } = {}) {
-  const r = fs.existsSync(path.join(root, '.git'))
-    ? await updateCheckout(root, run, logger)
-    : await updateNpmInstall(root, run, logger, registryUrl);
-  // Newer code already on disk (a pull or an install outside the gateway) is an update for the
+  // npm writes into the global prefix, so a checkout is the one install it cannot serve: the running
+  // code is this directory, not the prefix. The registry is still asked, because the release on npm
+  // is the release every other install receives, but for a checkout a failed install is not the end
+  // of the update -- the checkout is the thing that can move, so it is asked next.
+  const checkout = fs.existsSync(path.join(root, '.git'));
+  let registry;
+  try {
+    registry = await updateNpmInstall(root, run, logger, registryUrl);
+  } catch (err) {
+    if (!checkout) throw err;
+    logger(`npm could not install it here: ${err.message}`);
+    registry = { ...noUpdate(readVersion(root), `npm could not install it here: ${err.message}`), elsewhere: true };
+  }
+  let r = registry;
+  if (!r.updated && checkout) {
+    r = await updateCheckout(root, run, logger);
+    // Neither could deliver it, and npm held a release this directory cannot take: both facts, because
+    // "already the latest version" on its own would hide the one version the reader does not have.
+    if (!r.updated && registry.elsewhere) r = { ...r, reason: `${registry.reason} ${r.reason}` };
+  }
+  // Newer code already on disk (an install outside the gateway) is an update for the
   // running process: without the restart it keeps the old code and the old version forever.
   const onDisk = readVersion(root);
   if (!r.updated && isNewer(onDisk, running)) {