codex-copilot-dx 0.4.9 → 0.4.10

package/README.md

@@ -38,6 +38,16 @@ Claude Code picks up the new `ANTHROPIC_BASE_URL` on its next launch.
 
 Do not set Claude Code by manually exporting `ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN` in your shell. Let `codex-copilot-dx` write the local config files instead. If you previously exported those variables, remove them from shell startup files and restart the terminal before launching Claude Code.
 
+### Diagnostics
+
+Run a read-only config check without starting the adapter or changing files:
+
+```bash
+codex-copilot-dx doctor
+```
+
+The doctor checks the GitHub token, Codex config, Claude Code settings, Claude App gateway profile, and whether the local adapter port is listening.
+
 ### Claude App opt-in
 
 Claude App support is opt-in so the default Codex Desktop and Claude Code setup stays unchanged:

package/bin/cli.mjs

@@ -9,6 +9,7 @@ import { refreshVSCodeVersion } from "../src/copilot.mjs";
 import { status } from "../src/status.mjs";
 import { printUsageSummary } from "../src/usage.mjs";
 import { checkForUpdate, localPackageVersion } from "../src/version.mjs";
+import { runDoctor } from "../src/doctor.mjs";
 
 const ADAPTER_PORT = parseInt(process.env.ADAPTER_PORT || "2026");
 const ADAPTER_HOST = process.env.ADAPTER_HOST || "127.0.0.1";
@@ -30,6 +31,11 @@ if (command === "usage") {
   process.exit(0);
 }
 
+if (command === "doctor" || command === "--doctor") {
+  await runDoctor({ port: ADAPTER_PORT, host: ADAPTER_HOST });
+  process.exit(0);
+}
+
 console.log(`
   codex-copilot-dx v${LOCAL_VERSION}
   Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "Use Codex Desktop, Claude Code, and Claude App with GitHub Copilot",
   "type": "module",
   "bin": {

package/src/adapter.mjs

@@ -122,6 +122,7 @@ export async function readJsonBody(req, {
 }
 
 function sendJsonError(res, err, fallbackStatus = 400) {
+  if (res.destroyed || res.writableEnded) return;
   if (!res.headersSent) res.writeHead(err?.statusCode || fallbackStatus, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ error: err?.message || "Request failed" }));
 }
@@ -164,30 +165,61 @@ export function writeOrDrain(res, chunk) {
   });
 }
 
-function createRequestAbort(req, res) {
+export function isAbortLikeError(err) {
+  return err?.name === "AbortError" || /operation was aborted/i.test(String(err?.message || ""));
+}
+
+export function abortErrorStatusCode(reason) {
+  if (reason === "upstream_timeout") return 504;
+  if (reason === "client_aborted" || reason === "client_closed") return 499;
+  return 400;
+}
+
+export function createRequestAbort(req, res) {
   const controller = new AbortController();
   let timer = null;
   let cleaned = false;
-  const abort = () => {
-    if (!cleaned && !controller.signal.aborted) controller.abort();
+  let reason = null;
+  const abort = (nextReason = "aborted") => {
+    if (!cleaned && !controller.signal.aborted) {
+      reason = nextReason;
+      controller.abort();
+    }
+  };
+  const onReqAborted = () => abort("client_aborted");
+  const onResClose = () => {
+    if (!res.writableEnded) abort("client_closed");
   };
-  req.on("aborted", abort);
-  res.on("close", abort);
+  req.on("aborted", onReqAborted);
+  res.on("close", onResClose);
   return {
     signal: controller.signal,
+    get reason() { return reason; },
     setTimeout(ms) {
       if (timer) clearTimeout(timer);
-      if (ms > 0) timer = setTimeout(abort, ms);
+      if (ms > 0) timer = setTimeout(() => abort("upstream_timeout"), ms);
     },
     cleanup() {
       cleaned = true;
       if (timer) clearTimeout(timer);
-      req.off("aborted", abort);
-      res.off("close", abort);
+      req.off("aborted", onReqAborted);
+      res.off("close", onResClose);
     },
   };
 }
 
+function logRequestFailure(label, err, abort) {
+  if (!isAbortLikeError(err)) {
+    console.error(status("err", `${label} request failed: ${err.message}`));
+    return;
+  }
+
+  const reason = abort?.reason || "aborted";
+  err.statusCode ||= abortErrorStatusCode(reason);
+  const detail = reason === "upstream_timeout" ? `${reason} after ${UPSTREAM_TIMEOUT_MS}ms` : reason;
+  console.warn(status("warn", `${label} request aborted: ${detail}`));
+}
+
 function responsesInputItems(input) {
   if (input === undefined || input === null) return [];
   if (typeof input === "string") {
@@ -562,13 +594,16 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
                 res.writeHead(200, { "Content-Type": "application/json" });
                 res.end(JSON.stringify(resp));
               } catch (e) {
-                if (!res.headersSent) res.writeHead(502);
-                res.end("Bad Gateway");
+                logRequestFailure("Responses", e, abort);
+                if (!res.destroyed && !res.writableEnded) {
+                  if (!res.headersSent) res.writeHead(e?.statusCode || 502);
+                  res.end("Bad Gateway");
+                }
               }
             }
           }
         } catch (e) {
-          console.error(status("err", `Responses request failed: ${e.message}`));
+          logRequestFailure("Responses", e, abort);
           sendJsonError(res, e);
         } finally {
           abort.cleanup();
@@ -589,7 +624,7 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
           console.log(status("info", `responses compact model=${model} stream=${!!parsed.stream}`));
           await proxyCopilotResponses(prepared, req, res, copilotResponsesCompact, { signal: abort.signal });
         } catch (e) {
-          console.error(status("err", `Responses compact request failed: ${e.message}`));
+          logRequestFailure("Responses compact", e, abort);
           sendJsonError(res, e);
         } finally {
           abort.cleanup();
@@ -608,7 +643,13 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
       abort.setTimeout(UPSTREAM_TIMEOUT_MS);
       listModels({ signal: abort.signal })
         .then(({ status, body }) => { res.writeHead(status, { "Content-Type": "application/json" }); res.end(body); })
-        .catch((e) => { if (!res.headersSent) res.writeHead(502); res.end(JSON.stringify({ error: e.message })); })
+        .catch((e) => {
+          logRequestFailure("Models", e, abort);
+          if (!res.destroyed && !res.writableEnded) {
+            if (!res.headersSent) res.writeHead(e?.statusCode || 502);
+            res.end(JSON.stringify({ error: e.message }));
+          }
+        })
         .finally(() => abort.cleanup());
       return;
     }
@@ -671,7 +712,7 @@ export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
             res.end(JSON.stringify(anthropicMsg));
           }
         } catch (e) {
-          console.error(status("err", `Messages request failed: ${e.message}`));
+          logRequestFailure("Messages", e, abort);
           sendJsonError(res, e);
         } finally {
           abort.cleanup();

package/src/auth.mjs

@@ -6,7 +6,10 @@ import { status } from "./status.mjs";
 
 const CLIENT_ID = "Iv1.b507a08c87ecfe98"; // Public GitHub Copilot client ID.
 const SCOPE = "read:user";
-const GITHUB_TOKEN_PATH = path.join(os.homedir(), ".local", "share", "copilot-api", "github_token");
+
+export function githubTokenPath(home = os.homedir()) {
+  return path.join(home, ".local", "share", "copilot-api", "github_token");
+}
 
 // Map GitHub polling responses to a small local state machine.
 export function interpretPoll(data) {
@@ -40,6 +43,7 @@ function openAndCopy(userCode, verificationUri) {
 }
 
 export async function ensureAuth() {
+  const GITHUB_TOKEN_PATH = githubTokenPath();
   if (fs.existsSync(GITHUB_TOKEN_PATH)) {
     console.log(status("ok", "GitHub token found"));
     return;
@@ -90,6 +94,7 @@ export async function ensureAuth() {
 }
 
 function writeToken(token) {
+  const GITHUB_TOKEN_PATH = githubTokenPath();
   fs.mkdirSync(path.dirname(GITHUB_TOKEN_PATH), { recursive: true });
   fs.writeFileSync(GITHUB_TOKEN_PATH, token, { mode: 0o600 });
 }

package/src/doctor.mjs

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import net from "node:net";
+import { githubTokenPath } from "./auth.mjs";
+import { claudeDesktopPaths } from "./claude-desktop-config.mjs";
+import { status } from "./status.mjs";
+
+function localGatewayBaseUrl(host, port) {
+  const safeHost = String(host || "127.0.0.1");
+  const urlHost = safeHost.includes(":") && !safeHost.startsWith("[") ? `[${safeHost}]` : safeHost;
+  return `http://${urlHost}:${port}`;
+}
+
+function readText(filePath) {
+  try {
+    return { ok: true, text: fs.readFileSync(filePath, "utf8") };
+  } catch (e) {
+    return { ok: false, missing: e?.code === "ENOENT", error: e };
+  }
+}
+
+function readJson(filePath) {
+  const raw = readText(filePath);
+  if (!raw.ok) return raw;
+  try {
+    return { ok: true, json: JSON.parse(raw.text) };
+  } catch (e) {
+    return { ok: false, parseError: true, error: e };
+  }
+}
+
+function tomlString(content, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`^\\s*${escaped}\\s*=\\s*"([^"]*)"`, "m").exec(content);
+  return match?.[1] || "";
+}
+
+function displayPath(home, filePath) {
+  const rel = path.relative(home, filePath);
+  if (!rel.startsWith("..") && !path.isAbsolute(rel)) return `~/${rel}`;
+  return filePath;
+}
+
+function valueLabel(value) {
+  return value ? `"${value}"` : "missing";
+}
+
+export function inspectGitHubToken({ home = os.homedir() } = {}) {
+  const filePath = githubTokenPath(home);
+  const token = readText(filePath);
+  if (!token.ok) {
+    return [{ kind: "warn", message: `GitHub token not found at ${displayPath(home, filePath)}` }];
+  }
+  if (!token.text.trim()) {
+    return [{ kind: "err", message: `GitHub token file is empty at ${displayPath(home, filePath)}` }];
+  }
+  return [{ kind: "ok", message: "GitHub token found" }];
+}
+
+export function inspectCodexConfig({ home = os.homedir(), port = 2026 } = {}) {
+  const filePath = path.join(home, ".codex", "config.toml");
+  const expectedBaseUrl = `http://127.0.0.1:${port}/v1`;
+  const expectedAnthropicBaseUrl = `http://127.0.0.1:${port}`;
+  const config = readText(filePath);
+  if (!config.ok) {
+    return [{ kind: "warn", message: `Codex config not found at ${displayPath(home, filePath)}` }];
+  }
+
+  const checks = [];
+  const baseUrl = tomlString(config.text, "openai_base_url");
+  checks.push(baseUrl === expectedBaseUrl
+    ? { kind: "ok", message: `Codex base URL points to ${expectedBaseUrl}` }
+    : { kind: "warn", message: `Codex base URL is ${valueLabel(baseUrl)}; expected "${expectedBaseUrl}"` });
+
+  const missing = [];
+  if (tomlString(config.text, "OPENAI_BASE_URL") !== expectedBaseUrl) missing.push("OPENAI_BASE_URL");
+  if (tomlString(config.text, "OPENAI_API_KEY") !== "dummy") missing.push("OPENAI_API_KEY");
+  if (tomlString(config.text, "ANTHROPIC_BASE_URL") !== expectedAnthropicBaseUrl) missing.push("ANTHROPIC_BASE_URL");
+  if (tomlString(config.text, "ANTHROPIC_AUTH_TOKEN") !== "dummy") missing.push("ANTHROPIC_AUTH_TOKEN");
+  checks.push(missing.length === 0
+    ? { kind: "ok", message: "Codex shell env local API keys are configured" }
+    : { kind: "warn", message: `Codex shell env local API keys need update: ${missing.join(", ")}` });
+  return checks;
+}
+
+export function inspectClaudeCodeConfig({ home = os.homedir(), port = 2026 } = {}) {
+  const filePath = path.join(home, ".claude", "settings.json");
+  const expectedBaseUrl = `http://127.0.0.1:${port}`;
+  const settings = readJson(filePath);
+  if (!settings.ok) {
+    const reason = settings.parseError ? `could not parse: ${settings.error.message}` : `not found at ${displayPath(home, filePath)}`;
+    return [{ kind: settings.parseError ? "err" : "warn", message: `Claude Code settings ${reason}` }];
+  }
+
+  const env = settings.json?.env || {};
+  const missing = [];
+  if (env.ANTHROPIC_BASE_URL !== expectedBaseUrl) missing.push("ANTHROPIC_BASE_URL");
+  if (env.ANTHROPIC_AUTH_TOKEN !== "dummy") missing.push("ANTHROPIC_AUTH_TOKEN");
+  return [missing.length === 0
+    ? { kind: "ok", message: `Claude Code points to ${expectedBaseUrl}` }
+    : { kind: "warn", message: `Claude Code settings need update: ${missing.join(", ")}` }];
+}
+
+export function inspectClaudeAppConfig({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+  host = "127.0.0.1",
+  port = 2026,
+} = {}) {
+  const paths = claudeDesktopPaths(home, platform, env);
+  const expectedBaseUrl = localGatewayBaseUrl(host, port);
+  const checks = [];
+
+  const normalConfig = readJson(paths.normalConfigPath);
+  const threepConfig = readJson(paths.threepConfigPath);
+  if (normalConfig.ok && threepConfig.ok
+    && normalConfig.json?.deploymentMode === "3p"
+    && threepConfig.json?.deploymentMode === "3p") {
+    checks.push({ kind: "ok", message: "Claude App deployment mode is 3p" });
+  } else {
+    checks.push({ kind: "warn", message: "Claude App deployment mode is not fully configured for 3p" });
+  }
+
+  const meta = readJson(paths.metaPath);
+  const appliedId = meta.ok ? String(meta.json?.appliedId || "").trim() : "";
+  if (!appliedId) {
+    checks.push({ kind: "warn", message: "Claude App gateway profile is not configured; run with --configure-claude-desktop" });
+    return checks;
+  }
+
+  const profilePath = path.join(paths.configLibraryPath, `${appliedId}.json`);
+  const profile = readJson(profilePath);
+  if (!profile.ok) {
+    checks.push({ kind: "warn", message: `Claude App active gateway profile not found at ${displayPath(home, profilePath)}` });
+    return checks;
+  }
+
+  const p = profile.json || {};
+  const missing = [];
+  if (p.inferenceProvider !== "gateway") missing.push("inferenceProvider");
+  if (p.inferenceGatewayBaseUrl !== expectedBaseUrl) missing.push(`inferenceGatewayBaseUrl expected "${expectedBaseUrl}"`);
+  if (p.inferenceGatewayAuthScheme !== "bearer") missing.push("inferenceGatewayAuthScheme");
+  if (!String(p.inferenceGatewayApiKey || "").trim()) missing.push("inferenceGatewayApiKey");
+  if (!String(p.inferenceModels || "").trim()) missing.push("inferenceModels");
+  checks.push(missing.length === 0
+    ? { kind: "ok", message: `Claude App gateway profile points to ${expectedBaseUrl}` }
+    : { kind: "warn", message: `Claude App gateway profile needs update: ${missing.join(", ")}` });
+  return checks;
+}
+
+function connectHost(host) {
+  const normalized = String(host || "127.0.0.1").replace(/^\[(.*)\]$/, "$1");
+  if (normalized === "0.0.0.0") return "127.0.0.1";
+  if (normalized === "::") return "::1";
+  return normalized;
+}
+
+export function checkAdapterListening({ host = "127.0.0.1", port = 2026, timeoutMs = 500 } = {}) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host: connectHost(host), port });
+    const done = (ok) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+export async function collectDoctorChecks({
+  home = os.homedir(),
+  platform = process.platform,
+  env = process.env,
+  host = "127.0.0.1",
+  port = 2026,
+  checkAdapter = true,
+  checkAdapterListeningFn = checkAdapterListening,
+} = {}) {
+  const checks = [
+    ...inspectGitHubToken({ home }),
+    ...inspectCodexConfig({ home, port }),
+    ...inspectClaudeCodeConfig({ home, port }),
+    ...inspectClaudeAppConfig({ home, platform, env, host, port }),
+  ];
+
+  if (checkAdapter) {
+    const listening = await checkAdapterListeningFn({ host, port });
+    checks.push(listening
+      ? { kind: "ok", message: `Adapter is listening on ${localGatewayBaseUrl(host, port)}` }
+      : { kind: "warn", message: `Adapter is not listening on ${localGatewayBaseUrl(host, port)}` });
+  }
+
+  return checks;
+}
+
+export async function runDoctor(options = {}) {
+  const log = options.log || console.log;
+  log("codex-copilot-dx doctor");
+  const checks = await collectDoctorChecks(options);
+  for (const check of checks) log(status(check.kind, check.message));
+  return checks;
+}