test(cli): cover catalog prewarm on handleStart bind

Author: Wibias

src/cli/catalog-prewarm.ts

@@ -0,0 +1,24 @@
+import type { OcxConfig } from "../types";
+
+type GatherRoutedModels = (config: OcxConfig) => Promise<unknown>;
+
+export type CatalogPrewarmDeps = {
+  loadConfig?: () => OcxConfig;
+  importCatalog?: () => Promise<{ gatherRoutedModels: GatherRoutedModels }>;
+};
+
+/**
+ * After the listen port is bound, kick off live provider discovery so the first
+ * GUI /v1/models and syncModelsToCodex share one gather flight instead of racing
+ * duplicate upstream /models fetches.
+ */
+export function scheduleCatalogPrewarm(deps: CatalogPrewarmDeps = {}): void {
+  void Promise.resolve()
+    .then(async () => {
+      const load = deps.loadConfig ?? (await import("../config")).loadConfig;
+      const { gatherRoutedModels } = await (deps.importCatalog?.() ?? import("../codex/catalog"));
+      return gatherRoutedModels(load());
+    })
+    .catch(() => {});
+}
+

src/cli/index.ts

@@ -38,6 +38,7 @@ import { startTokenGuardian } from "../oauth/token-guardian";
 import { startHistoryMigrationGuardian } from "../codex/history-migration-guardian";
 import { maybeAutoRestoreCodexShim } from "./codex-shim-autorestore";
 import { maybeShowStarPrompt } from "./star-prompt";
+import { scheduleCatalogPrewarm } from "./catalog-prewarm";
 import { maybeShowUpdatePrompt } from "../update/notify";
 import { syncModelsToCodex } from "../codex/sync";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
@@ -193,9 +194,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       // Prewarm the live provider model cache as soon as the port is bound so the
       // first GUI /v1/models (and syncModelsToCodex below) share one discovery flight
       // instead of racing duplicate upstream /models fetches.
-      void import("../codex/catalog").then(({ gatherRoutedModels }) => {
-        gatherRoutedModels(loadConfig()).catch(() => {});
-      });
+      scheduleCatalogPrewarm();
       break;
     } catch (err) {
       if (!isAddrInUse(err) || attempt >= 2) throw err;

tests/cli-catalog-prewarm.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { OcxConfig } from "../src/types";
+import { scheduleCatalogPrewarm } from "../src/cli/catalog-prewarm";
+
+const root = new URL("../", import.meta.url);
+
+async function readText(path: string): Promise<string> {
+  return await Bun.file(new URL(path, root)).text();
+}
+
+describe("catalog prewarm on handleStart bind", () => {
+  test("scheduleCatalogPrewarm calls gatherRoutedModels(loadConfig()) once", async () => {
+    const config = { port: 9_001, providers: {}, defaultProvider: "fixture" } as OcxConfig;
+    const gatherRoutedModels = mock(async (_config: OcxConfig) => []);
+    const load = mock(() => config);
+    const importCatalog = mock(async () => ({ gatherRoutedModels }));
+
+    scheduleCatalogPrewarm({ loadConfig: load, importCatalog });
+
+    await Bun.sleep(0);
+    expect(importCatalog).toHaveBeenCalledTimes(1);
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(gatherRoutedModels).toHaveBeenCalledTimes(1);
+    expect(gatherRoutedModels.mock.calls[0]?.[0]).toBe(config);
+  });
+
+  test("scheduleCatalogPrewarm swallows gather failures", async () => {
+    const gatherRoutedModels = mock(async () => {
+      throw new Error("discovery failed");
+    });
+    scheduleCatalogPrewarm({
+      loadConfig: () => ({ port: 9_002, providers: {}, defaultProvider: "fixture" }) as OcxConfig,
+      importCatalog: async () => ({ gatherRoutedModels }),
+    });
+    await Bun.sleep(0);
+    expect(gatherRoutedModels).toHaveBeenCalledTimes(1);
+  });
+
+  test("handleStart schedules catalog prewarm immediately after a successful bind", async () => {
+    const cli = (await readText("src/cli/index.ts")).replace(/\r\n/g, "\n");
+    const bindIdx = cli.indexOf("server = startServer(port);");
+    const prewarmIdx = cli.indexOf("scheduleCatalogPrewarm()");
+    const breakIdx = cli.indexOf("\n      break;", bindIdx);
+
+    expect(cli).toContain('from "./catalog-prewarm"');
+    expect(bindIdx).toBeGreaterThan(-1);
+    expect(prewarmIdx).toBeGreaterThan(bindIdx);
+    expect(breakIdx).toBeGreaterThan(prewarmIdx);
+    // Must stay inside the successful-bind try path, not only on a later sync.
+    expect(cli.slice(bindIdx, breakIdx)).toContain("scheduleCatalogPrewarm()");
+    expect(cli).not.toContain('void import("../codex/catalog").then(({ gatherRoutedModels })');
+  });
+});
+