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

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

* fix(proxy): degrade to default dispatcher when proxy agent init fails instead of crashing startup

* fix(proxy): pin undici to ^7.16.0 for Node 20 compatibility (8.x requires Node >=22.19)

Author: Andy00L

package-lock.json

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

package.json

@@ -13,6 +13,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';
@@ -149,6 +150,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,59 @@
+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();
+  });
+
+  it('falls back (returns false, warns, never throws) when installing the agent fails', () => {
+    // A malformed/unsupported proxy value makes the agent throw at startup; the
+    // CLI must degrade to a proxy-less dispatcher, not crash every command.
+    const errs: string[] = [];
+    const installed = maybeInstallProxyAgent({
+      env: { HTTPS_PROXY: 'http://proxy.corp.example.com:8080' },
+      install: () => {
+        throw new Error('unsupported proxy scheme');
+      },
+      stderr: line => errs.push(line),
+    });
+    expect(installed).toBe(false);
+    expect(errs.join('\n')).toContain('ignoring proxy environment');
+  });
+
+  it('still installs when NO_PROXY is set (exemptions are applied per request by undici)', () => {
+    const install = vi.fn();
+    const installed = maybeInstallProxyAgent({
+      env: { HTTPS_PROXY: 'http://proxy.corp.example.com:8080', NO_PROXY: 'localhost,127.0.0.1' },
+      install,
+    });
+    expect(installed).toBe(true);
+    expect(install).toHaveBeenCalledTimes(1);
+  });
+});

src/lib/proxy.test.ts

@@ -0,0 +1,58 @@
+/**
+ * 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;
+  /** Warning sink. Defaults to `process.stderr`. */
+  stderr?: (line: string) => 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.
+  //
+  // A malformed or unsupported proxy value (e.g. `socks5://...`) makes the
+  // agent throw. Because this runs at startup, an unguarded throw would abort
+  // every command before the CLI's own error handling — so fall back to the
+  // default (proxy-less) dispatcher and warn instead of crashing.
+  try {
+    install(new EnvHttpProxyAgent());
+    return true;
+  } catch (error) {
+    const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
+    stderr(
+      `warning: ignoring proxy environment (could not initialize proxy agent): ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    return false;
+  }
+}