Add undici-based HTTP/HTTPS proxy support with tests and documentation

[rattalur]

This pull request adds support for running the CLI behind an HTTP or HTTPS proxy, configurable via standard environment variables. It introduces a new utility for proxy configuration, updates documentation to describe proxy usage, and adds direct support for proxying all API requests. The implementation ensures that proxy settings are respected consistently, including bypass logic via NO_PROXY, and is fully tested.

Proxy support implementation:

• Added a new utility (src/utils/proxy.ts) that resolves HTTP_PROXY/HTTPS_PROXY (case-insensitive), honors NO_PROXY for bypassing, and installs an undici.ProxyAgent as the global dispatcher for all outbound API requests.
• Updated the CLI entrypoint (src/index.ts) to call configureProxyFromEnv() before any API configuration or command registration, ensuring proxy settings are applied globally. [1] [2]

Dependencies and testing:

• Added undici as a direct dependency in package.json to provide the proxy agent and dispatcher.
• Added comprehensive unit tests for proxy resolution, bypass logic, and dispatcher installation in src/utils/proxy.test.ts.

Documentation updates:

• Documented proxy support and environment variables in README.md (new "Proxy Support" section), AGENTS.md (environment variable table), and SPECS/README.md (feature changelog). [1] [2] [3] [4]

Resolves Issue #40

[codacy-production]

Not up to standards ⛔

🔴 Issues 1 minor

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category	Results
Comprehensibility	1 minor

View in Codacy

🟢 Metrics 40 complexity · 0 duplication

Metric	Results
Complexity	40
Duplication	0

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}

[codacy-production]

Pull Request Overview

The implementation correctly introduces proxy support using undici, and the project remains 'up to standards' according to Codacy. However, there is a logic flaw that should be addressed before merging: the current configuration only checks the NO_PROXY bypass for the primary Codacy API host during initialization.

Because the undici.ProxyAgent is not initialized with the noProxy configuration, all other outbound requests (such as fetching CVE data from Mitre) will be forced through the proxy even if they are explicitly listed in the environment variables. Leveraging the library's native bypass support will provide a more robust and standard-compliant implementation.

About this PR

• The implementation should aim for full parity with standard networking tools by ensuring all outbound requests—not just the primary API calls—respect the NO_PROXY configuration. Transitioning to the native noProxy option in undici will solve this systemically.

Test suggestions

• Verify resolveProxyUrl handles precedence (HTTPS > HTTP) and case-insensitivity correctly.
• Verify shouldBypassProxy handles exact matches, suffix matches, and the wildcard '*' correctly.
• Verify configureProxyFromEnv installs the global dispatcher with the resolved URL.
• Verify configureProxyFromEnv skips installation if the API host matches a NO_PROXY entry.
• Verify proxy bypass logic respects the custom hostname from CODACY_API_BASE_URL.

_{TIP How was this review? Give us feedback}

[alerizzo]

Thanks for this, @rattalur — and for reporting #40. You clearly debugged this against a real corporate proxy, and the "curl works but the CLI doesn't" diagnostic in your docs was good enough that we borrowed it.

We've landed proxy support in #43 rather than merging this, for two reasons:

Consistency. There's already a shared proxy implementation in @codacy/tooling that the Analysis CLI uses and the VS Code extension's env contract matches. This CLI already depended on that package, so #43 just calls into it — one set of variables now configures every Codacy tool, with no second copy to drift.

Node 20. undici@8.10.1 requires Node >= 22.19, but this package declares engines: ">=20". On Node 20 require("undici") throws at module load, so codacy --version stopped working even with no proxy configured. Our CI should have caught that and didn't — #43 closes that gap too.

#43 supports everything you documented, plus SSL_CERT_FILE, NO_PROXY matched per host, and bare host:port. NODE_EXTRA_CA_CERTS still works, so your existing setup is unaffected. You're credited as Co-Authored-By and named in the release notes.

Would you let us know if it actually fixes your case? We tested against a proxy we built ourselves, not a real corporate one — yours is the environment that produced #40:

1. Does codacy info work with just HTTPS_PROXY set?
2. Your docs suggest you also hit TLS interception — does SSL_CERT_FILE (or NODE_EXTRA_CA_CERTS) pointed at your corporate bundle resolve it?
3. Does your proxy require authentication?

To try it before release (a git-ref install won't build dist/):

git clone -b feat/proxy-tls-support https://github.com/codacy/codacy-cloud-cli.git
cd codacy-cloud-cli && npm ci && npm run update-api && npm run build
HTTPS_PROXY=http://your-proxy:8080 node dist/index.js info

Closing this in favour of #43. If anything's still broken or you want to iterate, open an issue or PR and we'll pick it up there — thanks again.

[rattalur]

@alerizzo : I have used nodes 24 for building and testing locally. My code worked when HTTPS_PROXY and Additional node certificate is set. Without additional node certificate variable, I have hit TLS exception. There is no proxy authentication needed in my case.