refactor(updates): fetch version from registry instead of npm CLI to support multiple managers (#446)

## Background  
Addressing feedback from
https://github.com/openai/codex/pull/333#discussion_r2050893224, this PR
adds support for Bun alongside npm, pnpm while keeping the code simple.

## Summary  
The update‑check flow is refactored to use a direct registry lookup
(`fast-npm-meta` + `semver`) instead of shelling out to `npm outdated`,
and adds a lightweight installer‑detection mechanism that:

1. Checks if the invoked script lives under a known global‑bin directory
(npm, pnpm, or bun)
2. If not, falls back to local detection via `getUserAgent()` (the
`package‑manager‑detector` library)

## What’s Changed  
- **Registry‑based version check**  
- Replace `execFile("npm", ["outdated"])` with `getLatestVersion()` and
`semver.gt()`
- **Multi‑manager support**  
- New `renderUpdateCommand` handles update commands for `npm`, `pnpm`,
and `bun`.
  - Detect global installer first via `detectInstallerByPath()`  
  - Fallback to local detection via `getUserAgent()`  
- **Module cleanup**  
- Extract `detectInstallerByPath` into
`utils/package-manager-detector.ts`
- Remove legacy `checkOutdated`, `getNPMCommandPath`, and child‑process
JSON parsing
- **Flow improvements in `checkForUpdates`**  
  1. Short‑circuit by `UPDATE_CHECK_FREQUENCY`  
  3. Fetch & compare versions  
  4. Persist new timestamp immediately  
  5. Render & display styled box only when an update exists  
- **Maintain simplicity**
- All multi‑manager logic lives in one small helper and a concise lookup
rather than a complex adapter hierarchy
- Core `checkForUpdates` remains a single, easy‑to‑follow async function
- **Dependencies added**  
- `fast-npm-meta`, `semver`, `package-manager-detector`, `@types/semver`

## Considerations
If we decide to drop the interactive update‑message (`npm install -g
@openai/codex`) rendering altogether, we could remove most of the
installer‑detection code and dependencies, which would simplify the
codebase further but result in a less friendly UX.

## Preview

* npm

![refactor-update-check-flow-npm](https://github.com/user-attachments/assets/57320114-3fb6-4985-8780-3388a1d1ec85)

* bun

![refactor-update-check-flow-bun](https://github.com/user-attachments/assets/d93bf0ae-a687-412a-ab92-581b4f967307)

## Simple Flow Chart

```mermaid
flowchart TD
  A(Start) --> B[Read state]
  B --> C{Recent check?}
  C -- Yes --> Z[End]
  C -- No --> D[Fetch latest version]
  D --> E[Save check time]
  E --> F{Version data OK?}
  F -- No --> Z
  F -- Yes --> G{Update available?}
  G -- No --> Z
  G -- Yes --> H{Global install?}
  H -- Yes --> I[Select global manager]
  H -- No --> K{Local install?}
  K -- No --> Z
  K -- Yes --> L[Select local manager]
  I & L --> M[Render update message]
  M --> N[Format with boxen]
  N --> O[Print update]
  O --> Z
```

codex-cli/tests/__snapshots__/check-updates.test.ts.snap

@@ -1,12 +1,12 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Check for updates > should outputs the update message when package is outdated 1`] = `
+exports[`checkForUpdates() > renders a box when a newer version exists and no global installer 1`] = `
 "
-   ╭─────────────────────────────────────────────────────────────╮
-   │                                                             │
-   │              Update available! 1.0.0 → 2.0.0.               │
-   │   To update, run: npm install -g @openai/codex to update.   │
-   │                                                             │
-   ╰─────────────────────────────────────────────────────────────╯
+   ╭─────────────────────────────────────────────────╮
+   │                                                 │
+   │        Update available! 1.0.0 → 2.0.0.         │
+   │   To update, run bun add -g my-pkg to update.   │
+   │                                                 │
+   ╰─────────────────────────────────────────────────╯
 "
 `;

codex-cli/tests/check-updates.test.ts

@@ -1,112 +1,178 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { join } from "node:path";
+import os from "node:os";
+import type { UpdateOptions } from "../src/utils/check-updates";
+import { getLatestVersion } from "fast-npm-meta";
+import { getUserAgent } from "package-manager-detector";
 import {
   checkForUpdates,
-  checkOutdated,
-  getNPMCommandPath,
-} from "../src/utils/check-updates.js";
-import { execFile } from "node:child_process";
-import { join } from "node:path";
-import { CONFIG_DIR } from "src/utils/config.js";
-import { beforeEach } from "node:test";
-
-vi.mock("which", () => ({
-  default: vi.fn(() => "/usr/local/bin/npm"),
-}));
-
-vi.mock("child_process", () => ({
-  execFile: vi.fn((_cmd, _args, _opts, callback) => {
-    const stdout = JSON.stringify({
-      "@openai/codex": {
-        current: "1.0.0",
-        latest: "2.0.0",
-      },
-    });
-    callback?.(null, stdout, "");
-    return {} as any;
-  }),
-}));
+  renderUpdateCommand,
+} from "../src/utils/check-updates";
+import { detectInstallerByPath } from "../src/utils/package-manager-detector";
+import { CLI_VERSION } from "../src/utils/session";
 
+// In-memory FS mock
 let memfs: Record<string, string> = {};
-
-vi.mock("node:fs/promises", async (importOriginal) => ({
-  ...(await importOriginal()),
-  readFile: async (path: string) => {
-    if (memfs[path] === undefined) {
-      throw new Error("ENOENT");
-    }
-    return memfs[path];
-  },
-}));
-
-beforeEach(() => {
-  memfs = {}; // reset in‑memory store
+vi.mock("node:fs/promises", async (importOriginal) => {
+  return {
+    ...(await importOriginal()),
+    readFile: async (path: string) => {
+      if (!(path in memfs)) {
+        const err: any = new Error(
+          `ENOENT: no such file or directory, open '${path}'`,
+        );
+        err.code = "ENOENT";
+        throw err;
+      }
+      return memfs[path];
+    },
+    writeFile: async (path: string, data: string) => {
+      memfs[path] = data;
+    },
+    rm: async (path: string) => {
+      delete memfs[path];
+    },
+  };
 });
 
-describe("Check for updates", () => {
-  it("should return the path to npm", async () => {
-    const npmPath = await getNPMCommandPath();
-    expect(npmPath).toBeDefined();
+// Mock package name & CLI version
+const MOCK_PKG = "my-pkg";
+vi.mock("../package.json", () => ({ name: MOCK_PKG }));
+vi.mock("../src/utils/session", () => ({ CLI_VERSION: "1.0.0" }));
+vi.mock("../src/utils/package-manager-detector", async (importOriginal) => {
+  return {
+    ...(await importOriginal()),
+    detectInstallerByPath: vi.fn(),
+  };
+});
+
+// Mock external services
+vi.mock("fast-npm-meta", () => ({ getLatestVersion: vi.fn() }));
+vi.mock("package-manager-detector", () => ({ getUserAgent: vi.fn() }));
+
+describe("renderUpdateCommand()", () => {
+  it.each([
+    [{ manager: "npm", packageName: MOCK_PKG }, `npm install -g ${MOCK_PKG}`],
+    [{ manager: "pnpm", packageName: MOCK_PKG }, `pnpm add -g ${MOCK_PKG}`],
+    [{ manager: "bun", packageName: MOCK_PKG }, `bun add -g ${MOCK_PKG}`],
+    [{ manager: "yarn", packageName: MOCK_PKG }, `yarn global add ${MOCK_PKG}`],
+    [
+      { manager: "deno", packageName: MOCK_PKG },
+      `deno install -g npm:${MOCK_PKG}`,
+    ],
+  ])("%s → command", async (options, cmd) => {
+    expect(renderUpdateCommand(options as UpdateOptions)).toBe(cmd);
+  });
+});
+
+describe("checkForUpdates()", () => {
+  // Use a stable directory under the OS temp
+  const TMP = join(os.tmpdir(), "update-test-memfs");
+  const STATE_PATH = join(TMP, "update-check.json");
+
+  beforeEach(async () => {
+    memfs = {};
+    // Mock CONFIG_DIR to our TMP
+    vi.doMock("../src/utils/config", () => ({ CONFIG_DIR: TMP }));
+
+    // Freeze time so the 24h logic is deterministic
+    vi.useFakeTimers().setSystemTime(new Date("2025-01-01T00:00:00Z"));
+    vi.resetAllMocks();
   });
 
-  it("should return undefined if npm is not found", async () => {
-    vi.mocked(await import("which")).default.mockImplementationOnce(() => {
-      throw new Error("not found");
-    });
-
-    const npmPath = await getNPMCommandPath();
-    expect(npmPath).toBeUndefined();
+  afterEach(async () => {
+    vi.useRealTimers();
   });
 
-  it("should return the return value when package is outdated", async () => {
-    const npmPath = await getNPMCommandPath();
+  it("uses global installer when detected, ignoring local agent", async () => {
+    // seed old timestamp
+    const old = new Date("2000-01-01T00:00:00Z").toUTCString();
+    memfs[STATE_PATH] = JSON.stringify({ lastUpdateCheck: old });
 
-    const info = await checkOutdated(npmPath!);
-    expect(info).toStrictEqual({
-      currentVersion: "1.0.0",
-      latestVersion: "2.0.0",
-    });
-  });
+    // simulate registry says update available
+    vi.mocked(getLatestVersion).mockResolvedValue({ version: "2.0.0" } as any);
+    // local agent would be npm, but global detection wins
+    vi.mocked(getUserAgent).mockReturnValue("npm");
+    vi.mocked(detectInstallerByPath).mockReturnValue(Promise.resolve("pnpm"));
 
-  it("should return undefined when package is not outdated", async () => {
-    const npmPath = await getNPMCommandPath();
-    vi.mocked(execFile).mockImplementationOnce(
-      (_cmd, _args, _opts, callback) => {
-        // Simulate the case where the package is not outdated, returning an empty object
-        const stdout = JSON.stringify({});
-        callback?.(null, stdout, "");
-        return {} as any;
-      },
-    );
-
-    const info = await checkOutdated(npmPath!);
-    expect(info).toBeUndefined();
-  });
-
-  it("should outputs the update message when package is outdated", async () => {
-    const codexStatePath = join(CONFIG_DIR, "update-check.json");
-    // Use a fixed early date far in the past to ensure it's always at least 1 day before now
-    memfs[codexStatePath] = JSON.stringify({
-      lastUpdateCheck: new Date("2000-01-01T00:00:00Z").toUTCString(),
-    });
-    await checkForUpdates();
-    // Spy on console.log to capture output
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
     await checkForUpdates();
-    expect(logSpy).toHaveBeenCalled();
-    // The last call should be the boxen message
-    const lastCallArg = logSpy.mock.calls.at(-1)?.[0];
-    expect(lastCallArg).toMatchSnapshot();
+
+    // should render using `pnpm` (global) rather than `npm`
+    expect(logSpy).toHaveBeenCalledOnce();
+    const output = logSpy.mock.calls.at(0)?.at(0);
+    expect(output).toContain("pnpm add -g"); // global branch used
+    // state updated
+    const newState = JSON.parse(memfs[STATE_PATH]!);
+    expect(newState.lastUpdateCheck).toBe(new Date().toUTCString());
   });
 
-  it("should not output the update message when package is not outdated", async () => {
-    const codexStatePath = join(CONFIG_DIR, "update-check.json");
-    memfs[codexStatePath] = JSON.stringify({
-      lastUpdateCheck: new Date().toUTCString(),
-    });
-    await checkForUpdates();
-    // Spy on console.log to capture output
+  it("skips when lastUpdateCheck is still fresh (<frequency)", async () => {
+    // seed a timestamp 12h ago
+    const recent = new Date(Date.now() - 1000 * 60 * 60 * 12).toUTCString();
+    memfs[STATE_PATH] = JSON.stringify({ lastUpdateCheck: recent });
+
+    const versionSpy = vi.mocked(getLatestVersion);
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
     await checkForUpdates();
+
+    expect(versionSpy).not.toHaveBeenCalled();
     expect(logSpy).not.toHaveBeenCalled();
   });
+
+  it("does not print when up-to-date", async () => {
+    vi.mocked(getLatestVersion).mockResolvedValue({
+      version: CLI_VERSION,
+    } as any);
+    vi.mocked(getUserAgent).mockReturnValue("npm");
+    vi.mocked(detectInstallerByPath).mockResolvedValue(undefined);
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await checkForUpdates();
+
+    expect(logSpy).not.toHaveBeenCalled();
+    // but state still written
+    const state = JSON.parse(memfs[STATE_PATH]!);
+    expect(state.lastUpdateCheck).toBe(new Date().toUTCString());
+  });
+
+  it("does not print when no manager detected at all", async () => {
+    vi.mocked(getLatestVersion).mockResolvedValue({ version: "2.0.0" } as any);
+    vi.mocked(detectInstallerByPath).mockResolvedValue(undefined);
+    vi.mocked(getUserAgent).mockReturnValue(null);
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await checkForUpdates();
+
+    expect(logSpy).not.toHaveBeenCalled();
+    // state still written
+    const state = JSON.parse(memfs[STATE_PATH]!);
+    expect(state.lastUpdateCheck).toBe(new Date().toUTCString());
+  });
+
+  it("renders a box when a newer version exists and no global installer", async () => {
+    // old timestamp
+    const old = new Date("2000-01-01T00:00:00Z").toUTCString();
+    memfs[STATE_PATH] = JSON.stringify({ lastUpdateCheck: old });
+
+    vi.mocked(getLatestVersion).mockResolvedValue({ version: "2.0.0" } as any);
+    vi.mocked(detectInstallerByPath).mockResolvedValue(undefined);
+    vi.mocked(getUserAgent).mockReturnValue("bun");
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await checkForUpdates();
+
+    expect(logSpy).toHaveBeenCalledOnce();
+    const output = logSpy.mock.calls[0]![0] as string;
+    expect(output).toContain("bun add -g");
+    expect(output).to.matchSnapshot();
+    // state updated
+    const state = JSON.parse(memfs[STATE_PATH]!);
+    expect(state.lastUpdateCheck).toBe(new Date().toUTCString());
+  });
 });

codex-cli/tests/package-manager-detector.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import which from "which";
+import { detectInstallerByPath } from "../src/utils/package-manager-detector";
+import { execFileSync } from "node:child_process";
+
+vi.mock("which", () => ({
+  default: { sync: vi.fn() },
+}));
+vi.mock("node:child_process", () => ({ execFileSync: vi.fn() }));
+
+describe("detectInstallerByPath()", () => {
+  const originalArgv = process.argv;
+  const fakeBinDirs = {
+    // `npm prefix -g` returns the global “prefix” (we’ll add `/bin` when detecting)
+    npm: "/usr/local",
+    pnpm: "/home/user/.local/share/pnpm/bin",
+    bun: "/Users/test/.bun/bin",
+  } as const;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    // Pretend each manager binary is on PATH:
+    vi.mocked(which.sync).mockImplementation(() => "/fake/path");
+
+    vi.mocked(execFileSync).mockImplementation(
+      (
+        cmd: string,
+        _args: ReadonlyArray<string> = [],
+        _options: unknown,
+      ): string => {
+        return fakeBinDirs[cmd as keyof typeof fakeBinDirs];
+      },
+    );
+  });
+
+  afterEach(() => {
+    // Restore the real argv so tests don’t leak
+    process.argv = originalArgv;
+  });
+
+  it.each(Object.entries(fakeBinDirs))(
+    "detects %s when invoked from its global-bin",
+    async (manager, binDir) => {
+      // Simulate the shim living under that binDir
+      process.argv =
+        manager === "npm"
+          ? [process.argv[0]!, `${binDir}/bin/my-cli`]
+          : [process.argv[0]!, `${binDir}/my-cli`];
+      const detected = await detectInstallerByPath();
+      expect(detected).toBe(manager);
+    },
+  );
+
+  it("returns undefined if argv[1] is missing", async () => {
+    process.argv = [process.argv[0]!];
+    expect(await detectInstallerByPath()).toBeUndefined();
+    expect(execFileSync).not.toHaveBeenCalled();
+  });
+
+  it("returns undefined if shim isn't in any manager's bin", async () => {
+    // stub execFileSync to some other dirs
+    vi.mocked(execFileSync).mockImplementation(() => "/some/other/dir");
+    process.argv = [process.argv[0]!, "/home/user/.node_modules/.bin/my-cli"];
+    expect(await detectInstallerByPath()).toBeUndefined();
+  });
+});