@koreanhole/opencodex 2.98.0 → 3.0.0

package/src/cli/entry.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+import { randomBytes } from "node:crypto";
+import { rmSync } from "node:fs";
+import {
+  ADAPTER_DEFAULT_PORT,
+  ADAPTER_PROVIDER_IDS,
+  ADAPTER_TOKEN_ENV,
+  AdapterConfigError,
+  adapterRuntimePath,
+  discoverManagedProviderMetadata,
+  readAdapterRuntime,
+  readUpstreamConfig,
+  removeAdapterRuntimeIfPid,
+  restoreManagedProviderRows,
+  setAdapterDefaultProvider,
+  syncManagedProviderRows,
+  writeAdapterRuntime,
+  type AdapterProviderId,
+} from "../adapter-runtime/config";
+import { startAdapterGateway, type AdapterGateway } from "../adapter-runtime/gateway";
+import { ConfigError } from "../config";
+import { UpstreamPackageError, resolveUpstreamPackage } from "../upstream/package";
+import { loadUpstreamCli } from "../upstream/cli";
+import { runAdapterCli } from "./index";
+
+type AdapterCli = (argv: string[]) => Promise<number>;
+type UpstreamLoader = () => Promise<void>;
+type StartPreparer = (env: NodeJS.ProcessEnv) => Promise<unknown>;
+
+export interface EntryDeps {
+  adapterCli?: AdapterCli;
+  loadUpstream?: UpstreamLoader;
+  prepareStart?: StartPreparer;
+}
+
+const DISTRIBUTION_PACKAGE = "@koreanhole/opencodex";
+
+function isAdapterId(value: string | undefined): value is AdapterProviderId {
+  return value === "gemini-cli" || value === "cline-cli";
+}
+
+export function isAdapterOwnedCommand(argv: readonly string[]): boolean {
+  const command = argv[0];
+  if (command === "__cli-agent-mcp") return true;
+  if (command === "update") return true;
+  if (command === "system" && argv.slice(1).includes("update")) return true;
+  if (command === "login" && (argv[1] === "cline-cli" || argv[1] === "gemini-cli")) return true;
+  if (command === "adapter" && argv[1] === "detach") return true;
+  if (command !== "provider") return false;
+  if (argv[1] === "add" && isAdapterId(argv[2])) return true;
+  if (argv[1] === "use" && isAdapterId(argv[2])) return true;
+  return false;
+}
+
+function takeFlag(args: string[], flag: string): boolean {
+  const index = args.indexOf(flag);
+  if (index < 0) return false;
+  args.splice(index, 1);
+  return true;
+}
+
+async function adapterProviderCommand(args: string[], env: NodeJS.ProcessEnv): Promise<number> {
+  const sub = args.shift();
+  if (sub !== "add" && sub !== "use") throw new ConfigError("Unknown provider command: " + String(sub ?? "(missing)"));
+  const provider = args.shift();
+  if (!isAdapterId(provider)) throw new ConfigError("Only gemini-cli and cline-cli are handled for provider " + sub + ".");
+  if (sub === "add") {
+    const setDefault = takeFlag(args, "--set-default");
+    if (args.length > 0) throw new ConfigError("Unknown provider add option: " + args[0]);
+    const runtime = await readAdapterRuntime(env);
+    await syncManagedProviderRows({
+      env,
+      gatewayPort: runtime?.port ?? ADAPTER_DEFAULT_PORT,
+      ...(setDefault ? { defaultProvider: provider } : {}),
+    });
+    console.log("Configured " + provider + ".");
+    return 0;
+  }
+  if (args.length > 0) throw new ConfigError("Unknown provider use option: " + args[0]);
+  await setAdapterDefaultProvider(provider, env);
+  console.log("Default provider: " + provider);
+  return 0;
+}
+
+async function detachAdapter(env: NodeJS.ProcessEnv): Promise<number> {
+  const result = await restoreManagedProviderRows(env);
+  if (!result.restored) {
+    console.log("CLI adapters are not attached.");
+    return 0;
+  }
+  if (result.preservedUserRows.length > 0) {
+    console.log("Preserved user-owned provider rows: " + result.preservedUserRows.join(", "));
+  }
+  console.log("CLI adapter provider rows detached.");
+  return 0;
+}
+
+function printDistributionUpdate(argv: readonly string[]): number {
+  const command = "npm install -g " + DISTRIBUTION_PACKAGE + "@latest";
+  if (argv.includes("--json")) {
+    console.log(JSON.stringify({
+      ok: false,
+      reason: "distribution_managed",
+      package: DISTRIBUTION_PACKAGE,
+      command,
+    }));
+  } else {
+    console.error("ocx: updates are managed by " + DISTRIBUTION_PACKAGE + ".");
+    console.error("Run: " + command);
+  }
+  return 2;
+}
+
+async function runAdapterCommand(argv: string[], env: NodeJS.ProcessEnv, adapterCli: AdapterCli): Promise<number> {
+  if (argv[0] === "__cli-agent-mcp") return adapterCli(argv);
+  if (argv[0] === "login") return adapterCli(argv);
+  if (argv[0] === "update" || (argv[0] === "system" && argv.slice(1).includes("update"))) {
+    return printDistributionUpdate(argv);
+  }
+  if (argv[0] === "adapter" && argv[1] === "detach") return detachAdapter(env);
+  if (argv[0] === "provider") return adapterProviderCommand(argv.slice(1), env);
+  throw new ConfigError("Internal adapter dispatch error.");
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Attach the two managed rows and keep the gateway in the serving process. */
+export async function prepareAdapterStart(
+  env: NodeJS.ProcessEnv = process.env,
+  deps: {
+    discoverMetadata?: typeof discoverManagedProviderMetadata;
+    startGateway?: typeof startAdapterGateway;
+    syncRows?: typeof syncManagedProviderRows;
+  } = {},
+): Promise<AdapterGateway | undefined> {
+  const existing = await readAdapterRuntime(env);
+  const inheritedToken = env[ADAPTER_TOKEN_ENV]?.trim();
+  if (existing && existing.pid !== process.pid && pidAlive(existing.pid) && !inheritedToken) {
+    throw new AdapterConfigError(
+      "The CLI adapter gateway is already running in another process; restart it from that process or stop it first.",
+    );
+  }
+  const token = inheritedToken || randomBytes(32).toString("base64url");
+  env[ADAPTER_TOKEN_ENV] = token;
+  let gateway: AdapterGateway | undefined;
+  let gatewayPort: number;
+  if (existing && existing.pid !== process.pid && pidAlive(existing.pid)) {
+    gatewayPort = existing.port;
+  } else {
+    if (existing) await removeAdapterRuntimeIfPid(existing.pid, env);
+    gateway = (deps.startGateway ?? startAdapterGateway)({ token, env });
+    gatewayPort = gateway.port;
+    await writeAdapterRuntime({
+      version: 1,
+      pid: process.pid,
+      host: "127.0.0.1",
+      port: gatewayPort,
+      tokenEnv: ADAPTER_TOKEN_ENV,
+      providers: [...ADAPTER_PROVIDER_IDS],
+      startedAt: new Date().toISOString(),
+    }, env);
+    process.once("exit", () => {
+      try {
+        rmSync(adapterRuntimePath(env), { force: true });
+      } catch {
+        // best effort
+      }
+    });
+  }
+
+  try {
+    const metadata = await (deps.discoverMetadata ?? discoverManagedProviderMetadata)(env).catch(() => undefined);
+    const synced = await (deps.syncRows ?? syncManagedProviderRows)({
+      env,
+      gatewayPort,
+      ...(metadata ? { metadata } : {}),
+    });
+    if (synced.providerEnvToken) env.OPENCODEX_API_AUTH_TOKEN ??= synced.providerEnvToken;
+    return gateway;
+  } catch (error) {
+    await gateway?.stop().catch(() => undefined);
+    await removeAdapterRuntimeIfPid(process.pid, env).catch(() => undefined);
+    throw error;
+  }
+}
+
+export async function runEntry(argv: string[], deps: EntryDeps = {}): Promise<void> {
+  const env = process.env;
+  env.OCX_DISABLE_UPDATE_CHECK ??= "1";
+  if (isAdapterOwnedCommand(argv)) {
+    process.exitCode = await runAdapterCommand(argv, env, deps.adapterCli ?? runAdapterCli);
+    return;
+  }
+  if (argv[0] === "start") {
+    await (deps.prepareStart ?? prepareAdapterStart)(env);
+  }
+  const entry = process.argv[1] ?? "ocx";
+  const executable = process.argv[0] ?? "bun";
+  process.argv = [executable, entry, ...argv];
+  await (deps.loadUpstream ?? (() => loadUpstreamCli()))();
+}
+
+function printError(error: unknown): number {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error("ocx: " + message);
+  return error instanceof ConfigError || error instanceof AdapterConfigError || error instanceof UpstreamPackageError ? 2 : 1;
+}
+
+if (import.meta.main) {
+  try {
+    await runEntry(process.argv.slice(2));
+  } catch (error) {
+    process.exitCode = printError(error);
+  }
+}

package/src/cli/index.ts

@@ -20,6 +20,7 @@ import { startServer } from "../server";
 import { loginClineAcp } from "../adapters/cli-agent/cline/acp";
 import { runCodingAgentMcpServer } from "../adapters/cli-agent/mcp-server";
 import { syncCodexCatalog } from "../lib/codex-catalog";
+import { injectCodexConfig, recordCodexCatalogState, restoreCodexConfig } from "../lib/codex-inject";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -61,7 +62,10 @@ function help(): string {
     "  provider list [--json]                 Show supported providers",
     "  start [--port <port>] [--host <host>] Start the proxy",
     "  status [--json]                        Check the running proxy",
-    "  stop [--json]                          Stop the running proxy",
+    "  stop [--json]                          Stop the proxy and restore native Codex",
+    "  restore [--json]                       Restore native Codex without stopping",
+    "  restore back [--json]                  Re-point Codex at the running proxy",
+    "  eject                                  Alias of restore",
     "  codex sync [--json]                    Refresh the Codex model catalog",
     "  version                                Print the package version",
     "  help                                   Show this help",
@@ -179,21 +183,27 @@ async function startCommand(args: string[]): Promise<number> {
     config.port = parsed;
   }
   if (host !== undefined) config.host = host;
+  const running = startServer(config, { env });
+  try {
+    await injectCodexConfig({ env, endpoint: { host: running.host, port: running.port }, config });
+  } catch (error) {
+    await running.stop(true).catch(() => undefined);
+    throw error;
+  }
   try {
     const catalog = await syncCodexCatalog({ env });
     if (catalog.ok && catalog.written) {
+      await recordCodexCatalogState(env).catch(error => {
+        console.warn(`[opencodex] Codex catalog state was not journaled: ${error instanceof Error ? error.message : String(error)}`);
+      });
       console.log(`Codex catalog refreshed: ${catalog.path}`);
       console.log("Restart the Codex app/app-server to reload the model picker.");
-      if (!catalog.configured) {
-        console.log(`Activate it with: model_catalog_json = "${catalog.path}"`);
-      }
     } else if (!catalog.ok) {
       console.warn(`[opencodex] Codex catalog was not refreshed: ${catalog.message}`);
     }
   } catch (error) {
     console.warn(`[opencodex] Codex catalog refresh failed: ${error instanceof Error ? error.message : String(error)}`);
   }
-  const running = startServer(config, { env });
   await writeRuntimeState({ pid: process.pid, port: running.port, host: running.host, startedAt: new Date().toISOString() }, env);
   console.log(`opencodex listening on http://${running.host}:${running.port}/v1 (default provider: ${config.defaultProvider})`);
   console.log(`Health: http://${running.host}:${running.port}/healthz`);
@@ -202,10 +212,22 @@ async function startCommand(args: string[]): Promise<number> {
     console.log(`\nStopping proxy (${signal})...`);
     await running.stop(true);
     await removeRuntimeStateIfPid(process.pid, env);
-    process.exit(0);
+    let exitCode = 0;
+    try {
+      const restored = await restoreCodexConfig({ env });
+      if (!restored.success) {
+        exitCode = 1;
+        console.error(`ocx: Codex restore did not complete: ${restored.catalog.message}`);
+      }
+    } catch (error) {
+      exitCode = 1;
+      console.error(`ocx: Codex restore failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exit(exitCode);
   };
   process.once("SIGINT", () => void shutdown("SIGINT"));
   process.once("SIGTERM", () => void shutdown("SIGTERM"));
+  process.once("SIGHUP", () => void shutdown("SIGHUP"));
   await new Promise<never>(() => undefined);
   return 0;
 }
@@ -232,9 +254,42 @@ async function codexCommand(args: string[]): Promise<number> {
     }
     console.log("Codex reload required: restart the Codex app or app-server model picker.");
   }
+  if (result.ok) await recordCodexCatalogState(process.env).catch(() => undefined);
   return 0;
 }
 
+async function restoreCommand(args: string[]): Promise<number> {
+  const env = process.env;
+  const back = args[0] === "back";
+  if (back) args.shift();
+  const json = takeFlag(args, "--json");
+  const removeProviderTable = takeFlag(args, "--remove-codex-provider-table");
+  if (args.length > 0) throw new ConfigError(`Unknown restore option: ${args[0]}`);
+  let result;
+  if (back) {
+    const state = await readRuntimeState(env);
+    if (!state) throw new ConfigError("Proxy is not running; start it before `ocx restore back`.");
+    const config = await loadConfig(env);
+    if (!isAlive(state.pid) || !await health(state.host, state.port, config, env)) {
+      throw new ConfigError("The recorded proxy is not healthy; refusing to restore Codex routing.");
+    }
+    result = await injectCodexConfig({
+      env,
+      endpoint: { host: state.host, port: state.port },
+      config,
+    });
+    result = { ...result, action: "restore-back" as const };
+  } else {
+    result = await restoreCodexConfig({ env, removeProviderTable });
+  }
+  if (json) console.log(JSON.stringify(result));
+  else {
+    console.log(result.config.message);
+    console.log(result.catalog.message);
+  }
+  return result.success ? 0 : 1;
+}
+
 async function statusCommand(args: string[]): Promise<number> {
   const json = takeFlag(args, "--json");
   if (args.length > 0) throw new ConfigError(`Unknown status option: ${args[0]}`);
@@ -257,16 +312,24 @@ async function stopCommand(args: string[]): Promise<number> {
   if (args.length > 0) throw new ConfigError(`Unknown stop option: ${args[0]}`);
   const state = await readRuntimeState();
   if (!state) {
-    if (json) console.log(JSON.stringify({ stopped: false, reason: "not-running" }));
-    else console.log("Proxy is not running.");
+    const restored = await restoreCodexConfig({ env: process.env });
+    if (json) console.log(JSON.stringify({ stopped: false, reason: "not-running", restore: restored }));
+    else {
+      console.log("Proxy is not running.");
+      console.log(restored.config.message);
+    }
     return 1;
   }
   const config = await loadConfig();
   if (!isAlive(state.pid)) {
     await removeRuntimeStateIfPid(state.pid);
-    if (json) console.log(JSON.stringify({ stopped: true, stale: true }));
-    else console.log("Removed stale proxy state.");
-    return 0;
+    const restored = await restoreCodexConfig({ env: process.env });
+    if (json) console.log(JSON.stringify({ stopped: true, stale: true, restore: restored }));
+    else {
+      console.log("Removed stale proxy state.");
+      console.log(restored.config.message);
+    }
+    return restored.success ? 0 : 1;
   }
   if (!await health(state.host, state.port, config, process.env)) {
     throw new ConfigError(`Refusing to stop pid ${state.pid}: it is not the opencodex proxy recorded by this home.`);
@@ -276,12 +339,16 @@ async function stopCommand(args: string[]): Promise<number> {
   while (isAlive(state.pid) && Date.now() < deadline) await Bun.sleep(50);
   if (isAlive(state.pid)) process.kill(state.pid, "SIGKILL");
   await removeRuntimeStateIfPid(state.pid);
-  if (json) console.log(JSON.stringify({ stopped: true, pid: state.pid }));
-  else console.log(`Stopped proxy (pid ${state.pid}).`);
-  return 0;
+  const restored = await restoreCodexConfig({ env: process.env });
+  if (json) console.log(JSON.stringify({ stopped: true, pid: state.pid, restore: restored }));
+  else {
+    console.log(`Stopped proxy (pid ${state.pid}).`);
+    console.log(restored.config.message);
+  }
+  return restored.success ? 0 : 1;
 }
 
-async function main(argv: string[]): Promise<number> {
+export async function runAdapterCli(argv: string[]): Promise<number> {
   if (argv[0] === "__cli-agent-mcp") {
     await runCodingAgentMcpServer(argv[1] ?? "", argv[2]);
     return 0;
@@ -301,11 +368,14 @@ async function main(argv: string[]): Promise<number> {
   if (command === "start") return await startCommand(argv);
   if (command === "status") return await statusCommand(argv);
   if (command === "stop") return await stopCommand(argv);
-  throw new ConfigError(`Unknown command: ${command}. Expected login, provider, codex, start, status, stop, version, or help.`);
+  if (command === "restore" || command === "eject") return await restoreCommand(argv);
+  throw new ConfigError(`Unknown command: ${command}. Expected login, provider, codex, start, status, stop, restore, eject, version, or help.`);
 }
 
-try {
-  process.exitCode = await main(process.argv.slice(2));
-} catch (error) {
-  process.exitCode = printError(error);
+if (import.meta.main) {
+  try {
+    process.exitCode = await runAdapterCli(process.argv.slice(2));
+  } catch (error) {
+    process.exitCode = printError(error);
+  }
 }

package/src/lib/codex-catalog.ts

@@ -257,6 +257,67 @@ function readRootTomlString(text: string, key: string): string | undefined {
   return match?.[1]?.trim() || undefined;
 }
 
+export function codexHome(env: NodeJS.ProcessEnv = process.env): string {
+  return env.CODEX_HOME?.trim() || join(env.HOME?.trim() || homedir(), ".codex");
+}
+
+/** Resolve the catalog only when opencodex is allowed to manage that file. */
+export async function resolveCodexCatalogPath(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string | undefined> {
+  const home = codexHome(env);
+  let configured: string | undefined;
+  try {
+    configured = readRootTomlString(await readFile(join(home, "config.toml"), "utf8"), "model_catalog_json");
+  } catch {
+    configured = undefined;
+  }
+  if (configured && basename(configured) !== "opencodex-catalog.json") return undefined;
+  return configured ? resolve(home, configured) : join(home, "opencodex-catalog.json");
+}
+
+export function isManagedCodexCatalogSlug(slug: unknown): boolean {
+  return managedSlug(slug);
+}
+
+/** Remove only opencodex-routed rows; preserve native/user rows. */
+export async function removeManagedCodexCatalogRows(path: string): Promise<{
+  changed: boolean;
+  removed: number;
+  message: string;
+}> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { changed: false, removed: 0, message: "No opencodex catalog file was present." };
+    }
+    throw error;
+  }
+  let parsed: Record<string, unknown>;
+  try {
+    const value = asRecord(JSON.parse(raw));
+    if (!value) throw new Error("catalog is not an object");
+    parsed = value;
+  } catch {
+    throw new Error("The opencodex catalog is malformed; it was preserved.");
+  }
+  const models = Array.isArray(parsed.models) ? parsed.models : undefined;
+  if (!models || models.some(model => !asRecord(model))) {
+    throw new Error("The opencodex catalog has an invalid models field; it was preserved.");
+  }
+  const kept = models.filter(model => !managedSlug(asRecord(model)?.slug));
+  const removed = models.length - kept.length;
+  if (removed === 0) return { changed: false, removed: 0, message: "No managed catalog rows were present." };
+  if (kept.length === 0 && basename(path) === "opencodex-catalog.json") {
+    await rm(path, { force: true });
+    return { changed: true, removed, message: `Removed ${removed} managed catalog row(s) and the empty opencodex catalog.` };
+  }
+  await writeCodexCatalog(path, { ...parsed, models: kept } as CodexCatalogDocument);
+  return { changed: true, removed, message: `Removed ${removed} managed catalog row(s) from ${path}.` };
+}
+
 export async function writeCodexCatalog(
   path: string,
   document: CodexCatalogDocument,