codex-copilot-dx 0.4.25 → 0.4.26

package/README.md

@@ -15,7 +15,7 @@ Supports both HTTP SSE streaming and non-streaming.
 ## Prerequisites
 
 - GitHub Copilot subscription (Individual, Business, or Enterprise)
-- Node.js 18+
+- Node.js 18.17+
 - [Codex Desktop](https://openai.com/codex), [Claude Code](https://claude.com/claude-code), and/or Claude App installed
 
 ## Usage
@@ -28,7 +28,7 @@ npx codex-copilot-dx@latest
 
 On first run, it will:
 1. Authenticate with GitHub via device flow (if needed), after first trying compatible local Copilot token sources
-2. Print the local package version and warn when a newer npm release is available
+2. Print the local package version and check for a newer npm release in the background
 3. Start the adapter on loopback (`127.0.0.1:2026`)
 4. Configure Codex (`~/.codex/config.toml`) to use the adapter, including stale shell env base URLs if present
 5. Configure Claude Code (`~/.claude/settings.json`) to use the adapter; it creates the file when missing, otherwise backs up `settings.json.bak` before updating the local API env keys
@@ -50,6 +50,8 @@ Run a read-only config check without starting the adapter or changing files:
 codex-copilot-dx doctor
 ```
 
+The command exits with status `1` when it finds an invalid configuration and `0` when checks contain only OK or warning results.
+
 The doctor checks the GitHub token, Codex config, Claude Code settings, Claude App gateway profile, and whether the local adapter port is listening.
 
 For a read-only live check of the saved GitHub token, Copilot entitlement, and models endpoint, run:
@@ -99,10 +101,13 @@ Environment variables:
 | `CCDX_MAX_BODY_BYTES` | `134217728` | Maximum compressed/raw request body size |
 | `CCDX_MAX_DECODED_BODY_BYTES` | `268435456` | Maximum decoded request body size after decompression |
 | `CCDX_UPSTREAM_TIMEOUT_MS` | `120000` | Timeout for non-streaming upstream Copilot requests |
+| `CCDX_STREAM_HANDSHAKE_TIMEOUT_MS` | `120000` | Timeout while waiting for upstream streaming response headers |
+| `CCDX_STREAM_IDLE_TIMEOUT_MS` | `120000` | Maximum idle time between upstream streaming body chunks |
 | `CCDX_UPSTREAM_RETRIES` | `2` | Retries for transient Copilot upstream network errors; capped at `5` |
 | `CCDX_UPSTREAM_RETRY_DELAY_MS` | `300` | Initial upstream retry backoff in milliseconds; capped at `5000` |
 | `CCDX_LOG_PATH` | unset | Mirror terminal logs to a file; set to `1` for `~/.local/share/codex-copilot-dx/debug.log` |
 | `CCDX_LOG_LEVEL` | `info` | Set to `debug` to include upstream request attempts, status codes, retry causes, and timings |
+| `CCDX_LOG_MAX_BYTES` | `16777216` | Rotate the debug log at this size, retaining one `.1` backup; set to `0` to disable rotation |
 | `CCDX_IMG_MAX_DIM` | `2048` | Max long edge in pixels for image downscaling |
 | `CCDX_IMG_QUALITY` | `85` | WebP quality used when re-encoding images |
 | `CCDX_IMG_MIN_BYTES` | `100000` | Images smaller than this are left untouched |
@@ -123,7 +128,9 @@ Environment variables:
 | `CCDX_RESPONSE_HISTORY_MAX_BYTES` | `67108864` | Total in-memory byte budget for locally expanded Responses history |
 | `CCDX_RESPONSE_HISTORY_MAX_ENTRIES` | `4096` | Maximum stored incremental Responses history nodes |
 | `CCDX_USAGE_PATH` | `~/.local/share/codex-copilot-dx/usage.jsonl` | Local JSONL token usage log |
+| `CCDX_USAGE_MAX_BYTES` | `33554432` | Rotate the usage log at this size, retaining one `.1` backup; set to `0` to disable rotation |
 | `CCDX_DISABLE_USAGE` | unset | Set to `1` to disable usage logging |
+| `CCDX_SHUTDOWN_TIMEOUT_MS` | `5000` | Time to drain active HTTP connections before forcing shutdown |
 
 ### Usage logging
 
@@ -148,3 +155,12 @@ Newer ChatGPT/Codex clients can advertise an `image_gen` namespace that already
 ## License
 
 MIT
+
+## Development
+
+```bash
+npm ci
+npm run verify
+```
+
+`npm test` runs the unit and handler-level suite. `npm run test:smoke` starts a real local HTTP adapter with fully injected offline upstreams. `npm run pack:check` verifies the npm tarball contents without publishing. The CI workflow runs all three checks on supported Node.js release lines.

package/bin/cli.mjs

@@ -9,22 +9,58 @@ import { cacheModelEndpoints, listModels, refreshVSCodeVersion } from "../src/co
 import { claudeDesktopModelDefsFromCopilotModels, claudeDesktopModelIds, gptModelIdsFromCopilotModels, parseModelAliasEnv } from "../src/models.mjs";
 import { status } from "../src/status.mjs";
 import { configureLogging } from "../src/log.mjs";
-import { printUsageSummary } from "../src/usage.mjs";
+import { flushUsageWrites, printUsageSummary } from "../src/usage.mjs";
 import { checkForUpdate, localPackageVersion } from "../src/version.mjs";
 import { runDoctor } from "../src/doctor.mjs";
 import { checkRunningAdapter } from "../src/running-adapter.mjs";
 import { assertSafeAdapterHost, isLoopbackHost } from "../src/security.mjs";
 import { loadModelCache, saveModelCache } from "../src/model-cache.mjs";
+import { initializeModelRegistry, runInBackground } from "../src/startup.mjs";
+import { cliHelp, parseCliArgs, parseRuntimeOptions } from "../src/cli-options.mjs";
+import { closeHttpServer } from "../src/shutdown.mjs";
 
-const ADAPTER_PORT = parseInt(process.env.ADAPTER_PORT || "2026");
-const ADAPTER_HOST = process.env.ADAPTER_HOST || "127.0.0.1";
-const MODEL_REFRESH_TIMEOUT_MS = parseInt(process.env.CCDX_MODEL_REFRESH_TIMEOUT_MS || "5000", 10);
-const EXISTING_ADAPTER_TIMEOUT_MS = parseInt(process.env.CCDX_EXISTING_ADAPTER_TIMEOUT_MS || "500", 10);
 const LOCAL_VERSION = localPackageVersion();
-const command = process.argv[2];
-const CONFIGURE_CLAUDE_DESKTOP = command === "--configure-claude-desktop" || process.env.CCDX_CONFIGURE_CLAUDE_DESKTOP === "1";
+
+let CLI;
+try {
+  CLI = parseCliArgs(process.argv.slice(2));
+} catch (e) {
+  console.error(e.message);
+  console.error("Run codex-copilot-dx --help for usage.");
+  process.exit(2);
+}
+
+if (CLI.command === "help") {
+  console.log(cliHelp());
+  process.exit(0);
+}
+if (CLI.command === "version") {
+  console.log(`codex-copilot-dx v${LOCAL_VERSION}`);
+  process.exit(0);
+}
+if (CLI.command === "usage") {
+  await printUsageSummary();
+  process.exit(0);
+}
+
+let RUNTIME;
+try {
+  RUNTIME = parseRuntimeOptions(process.env);
+} catch (e) {
+  console.error(e.message);
+  process.exit(2);
+}
+
+const ADAPTER_PORT = RUNTIME.adapterPort;
+const ADAPTER_HOST = RUNTIME.adapterHost;
+const MODEL_REFRESH_TIMEOUT_MS = RUNTIME.modelRefreshTimeoutMs;
+const EXISTING_ADAPTER_TIMEOUT_MS = RUNTIME.existingAdapterTimeoutMs;
+const CONFIGURE_CLAUDE_DESKTOP = CLI.configureClaudeDesktop || process.env.CCDX_CONFIGURE_CLAUDE_DESKTOP === "1";
 const LOGGING = configureLogging();
 const MODEL_REGISTRY = { modelDefs: undefined, source: "built-in" };
+let activeServer = null;
+let modelRefreshTimer = null;
+let shuttingDown = false;
 
 if (LOGGING.filePath) {
   console.log(status("info", `Debug log: ${LOGGING.filePath}`));
@@ -140,23 +176,13 @@ async function reuseRunningAdapterIfAvailable() {
   return true;
 }
 
-if (command === "--version" || command === "-v" || command === "version") {
-  console.log(`codex-copilot-dx v${LOCAL_VERSION}`);
-  process.exit(0);
-}
-
-if (command === "usage") {
-  await printUsageSummary();
-  process.exit(0);
-}
-
-if (command === "doctor" || command === "--doctor") {
-  await runDoctor({
+if (CLI.command === "doctor") {
+  const checks = await runDoctor({
     port: ADAPTER_PORT,
     host: ADAPTER_HOST,
-    online: process.argv.slice(3).includes("--online"),
+    online: CLI.online,
   });
-  process.exit(0);
+  process.exit(checks.some((check) => check.kind === "err") ? 1 : 0);
 }
 
 console.log(`
@@ -175,21 +201,22 @@ async function printUpdateNotice() {
   }
 }
 
-// Await the update check up front so the notice is shown even on the
-// "reuse existing adapter" path, which exits early below.
-await printUpdateNotice();
-
 try {
   assertSafeAdapterHost(ADAPTER_HOST, process.env);
+  void runInBackground(printUpdateNotice);
   if (await reuseRunningAdapterIfAvailable()) process.exit(0);
 
   // Ensure GitHub login, using device flow if no token exists.
   await ensureAuth();
 
   // Refresh the VS Code version in the background; fallback is non-blocking.
-  refreshVSCodeVersion();
-  loadCachedModelRegistry();
-  const claudeDesktopModelDefs = await refreshClaudeDesktopModelDefs();
+  void refreshVSCodeVersion();
+  const modelInitialization = await initializeModelRegistry({
+    loadCached: loadCachedModelRegistry,
+    currentModelDefs: () => MODEL_REGISTRY.modelDefs,
+    refresh: refreshClaudeDesktopModelDefs,
+  });
+  const claudeDesktopModelDefs = modelInitialization.modelDefs;
 
   if (!isLoopbackHost(ADAPTER_HOST)) {
     console.log(status("warn", `ADAPTER_HOST=${ADAPTER_HOST} exposes the adapter beyond loopback because CCDX_ALLOW_LAN=1 is set. Use only on trusted networks.`));
@@ -200,7 +227,14 @@ try {
     : currentClaudeDesktopApiKey();
 
   // Start the in-process adapter.
-  await startAdapter(ADAPTER_PORT, ADAPTER_HOST, { claudeDesktopApiKey, claudeDesktopModelDefs, modelRegistry: MODEL_REGISTRY });
+  activeServer = await startAdapter(ADAPTER_PORT, ADAPTER_HOST, {
+    claudeDesktopApiKey,
+    claudeDesktopModelDefs,
+    modelRegistry: MODEL_REGISTRY,
+    upstreamTimeoutMs: RUNTIME.upstreamTimeoutMs,
+    streamHandshakeTimeoutMs: RUNTIME.streamHandshakeTimeoutMs,
+    streamIdleTimeoutMs: RUNTIME.streamIdleTimeoutMs,
+  });
 
   // Point Codex and Claude Code at the adapter.
   ensureCodexConfig(ADAPTER_PORT);
@@ -223,12 +257,12 @@ try {
 
   // Periodically refresh the model list + endpoint cache so a long-running
   // adapter picks up newly released models without a restart.
-  const refreshIntervalMs = parseInt(process.env.CCDX_MODEL_REFRESH_INTERVAL_MS || String(30 * 60 * 1000), 10);
+  const refreshIntervalMs = RUNTIME.modelRefreshIntervalMs;
   if (Number.isFinite(refreshIntervalMs) && refreshIntervalMs > 0) {
-    const timer = setInterval(() => {
+    modelRefreshTimer = setInterval(() => {
       refreshClaudeDesktopModelDefs().catch(() => {});
     }, refreshIntervalMs);
-    if (typeof timer.unref === "function") timer.unref();
+    modelRefreshTimer.unref?.();
   }
 
   console.log(`
@@ -239,11 +273,30 @@ try {
   Press Ctrl+C to stop.
 `);
 
-  process.on("SIGINT", () => {
-    console.log(`\n${status("wait", "Shutting down...")}`);
-    process.exit(0);
-  });
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    console.log(`\n${status("wait", `Shutting down on ${signal}...`)}`);
+    let exitCode = 0;
+    try {
+      if (modelRefreshTimer) clearInterval(modelRefreshTimer);
+      const result = await closeHttpServer(activeServer, { timeoutMs: RUNTIME.shutdownTimeoutMs });
+      if (result.forced) console.warn(status("warn", "Forced remaining adapter connections closed"));
+      await flushUsageWrites();
+    } catch (e) {
+      exitCode = 1;
+      console.error(status("err", `Shutdown failed: ${e.message}`));
+    } finally {
+      LOGGING.cleanup();
+      process.exit(exitCode);
+    }
+  };
+  process.once("SIGINT", () => { void shutdown("SIGINT"); });
+  process.once("SIGTERM", () => { void shutdown("SIGTERM"); });
 } catch (e) {
   console.error(status("err", e.message));
+  await closeHttpServer(activeServer, { timeoutMs: RUNTIME.shutdownTimeoutMs }).catch(() => {});
+  await flushUsageWrites();
+  LOGGING.cleanup();
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "type": "module",
   "bin": {
@@ -25,8 +25,15 @@
     "responses-api"
   ],
   "license": "MIT",
+  "engines": {
+    "node": ">=18.17"
+  },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "test:smoke": "node scripts/offline-smoke.mjs",
+    "test:e2e": "bash test/e2e.sh",
+    "pack:check": "npm pack --dry-run --json",
+    "verify": "npm test && npm run test:smoke && npm run pack:check"
   },
   "dependencies": {
     "gpt-tokenizer": "^3.4.0",