feat(cli): honor HTTPS_PROXY/HTTP_PROXY/NO_PROXY behind corporate and CI proxies

Author: Andy00L

package-lock.json

@@ -50,6 +50,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "commander": "^12.1.0",
+    "undici": "^8.5.0",
     "valibot": "^1.4.1"
   },
   "devDependencies": {

package.json

@@ -12,6 +12,7 @@ import { createTestCommand } from './commands/test.js';
 import { createUsageCommand } from './commands/usage.js';
 import { ApiError, CLIError, RequestTimeoutError } from './lib/errors.js';
 import { Output, isOutputMode } from './lib/output.js';
+import { maybeInstallProxyAgent } from './lib/proxy.js';
 import { renderCommanderError, rephraseUnknownOption } from './lib/render-error.js';
 import { maybeEmitSkillNudge } from './lib/skill-nudge.js';
 import { VERSION } from './version.js';
@@ -138,6 +139,10 @@ program.hook('preAction', (_thisCommand, actionCommand) => {
   });
 });
 
+// Corporate/CI proxies: honor HTTPS_PROXY/HTTP_PROXY/NO_PROXY (Node's fetch
+// ignores them by default). No-op when no proxy variable is set.
+maybeInstallProxyAgent();
+
 try {
   await program.parseAsync(process.argv);
 } catch (err) {

src/index.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it, vi } from 'vitest';
+import { maybeInstallProxyAgent } from './proxy.js';
+
+describe('maybeInstallProxyAgent', () => {
+  it('installs an agent when HTTPS_PROXY is set', () => {
+    const install = vi.fn();
+    const installed = maybeInstallProxyAgent({
+      env: { HTTPS_PROXY: 'http://proxy.corp.example.com:8080' },
+      install,
+    });
+    expect(installed).toBe(true);
+    expect(install).toHaveBeenCalledTimes(1);
+  });
+
+  it.each(['https_proxy', 'HTTP_PROXY', 'http_proxy'] as const)(
+    'also honors the %s spelling',
+    name => {
+      const install = vi.fn();
+      const installed = maybeInstallProxyAgent({
+        env: { [name]: 'http://proxy.corp.example.com:8080' },
+        install,
+      });
+      expect(installed).toBe(true);
+      expect(install).toHaveBeenCalledTimes(1);
+    },
+  );
+
+  it('does nothing when no proxy variable is set (default path unchanged)', () => {
+    const install = vi.fn();
+    expect(maybeInstallProxyAgent({ env: {}, install })).toBe(false);
+    expect(maybeInstallProxyAgent({ env: { HTTPS_PROXY: '' }, install })).toBe(false);
+    expect(install).not.toHaveBeenCalled();
+  });
+});

src/lib/proxy.test.ts

@@ -0,0 +1,41 @@
+/**
+ * Proxy support (issue #119): honor HTTPS_PROXY / HTTP_PROXY / NO_PROXY.
+ *
+ * Node's built-in fetch (undici) deliberately ignores the proxy environment
+ * variables, so behind a corporate or CI proxy every request dies with
+ * `fetch failed` after a full retry cycle. Installing undici's
+ * `EnvHttpProxyAgent` as the global dispatcher restores the conventional
+ * behavior (including NO_PROXY exemptions) for every fetch the CLI makes.
+ *
+ * Only active when a proxy env var is actually present, so the default path
+ * stays byte-identical and pays zero startup cost. Dependency note for
+ * reviewers: this adds `undici` as an explicit runtime dependency (the same
+ * engine Node already bundles); the alternative, a hand-rolled CONNECT
+ * tunnel, would re-implement what undici ships and maintains.
+ */
+import type { Dispatcher } from 'undici';
+import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
+
+export interface ProxyDeps {
+  env?: NodeJS.ProcessEnv;
+  /** Dispatcher installer. Defaults to undici's setGlobalDispatcher. */
+  install?: (agent: Dispatcher) => void;
+}
+
+/**
+ * Install the env-driven proxy dispatcher when any proxy variable is set
+ * (both canonical upper-case and conventional lower-case spellings).
+ * Returns whether an agent was installed (observable for tests/debugging).
+ */
+export function maybeInstallProxyAgent(deps: ProxyDeps = {}): boolean {
+  const env = deps.env ?? process.env;
+  const hasProxy = [env.HTTPS_PROXY, env.https_proxy, env.HTTP_PROXY, env.http_proxy].some(
+    value => typeof value === 'string' && value.length > 0,
+  );
+  if (!hasProxy) return false;
+  const install = deps.install ?? setGlobalDispatcher;
+  // EnvHttpProxyAgent reads HTTPS_PROXY/HTTP_PROXY/NO_PROXY itself, per
+  // request, so NO_PROXY exemptions apply without extra plumbing here.
+  install(new EnvHttpProxyAgent());
+  return true;
+}