fix(proxy): say when Node WILL use the proxy, and name the opt-in (PHARN-12)

[PrzemekGalarowicz]

What this changes

When a proxy variable is set, pharn prints: "…but pharn will not use it: … Node's global fetch, which reads no proxy environment variable on any platform". That is not always true.

• Node 22.22.2: with NODE_USE_ENV_PROXY=1 or --use-env-proxy, fetch does connect through HTTPS_PROXY. So users who turned this on were told the opposite of what happens, and users stuck behind a proxy never learned the workaround exists.
• Node 20.20.2: ignores the variable and rejects the flag.

The notice now states which of three cases applies:

• on: the option is set and this Node supports it. The notice says the downloads go through the proxy (Node's fetch then also honours NO_PROXY).
• available: this Node supports the option but it is not set. The old warning stays and adds "re-run with NODE_USE_ENV_PROXY=1 set".
• unsupported: this Node has no such option. The old warning stays and says a newer Node release has it.

How support is detected: the check asks the running Node for its list of accepted flags (process.allowedNodeEnvironmentFlags). There is no hard-coded version table. --use-env-proxy is only counted when it appears in process.execArgv or NODE_OPTIONS as a whole word, so something like --use-env-proxy-foo does not count.

Docs: the "Proxy environment variables" section of docs/troubleshooting.md now documents the opt-in.

Built with /pharn-dev-ship; stage artifacts are in .dev/features/proxy-env-opt-in/. Results:

• validate: exit 0
• regress: no-regressions
• verify: PASS
• coverage: 97.16%

Type of change

• feat — new stack option, wizard step, or command capability
• fix — bug fix
• docs — docs-only change
• chore / refactor — tooling or internal restructure, no behavior change

Area(s) touched

lib/proxy-env | lib/proxy-env-format | docs

Checklist

• Read the existing file(s) before editing; followed the ESM .js-extension import convention.
• 10 new tests, covering every detection case and each of the three messages, all failing on the old code. I updated the existing tests on purpose: an assertion that the message says "any platform" now checks for "by default", which is the accurate wording.
• Updated docs/troubleshooting.md.
• The proxy value is still passed through redactProxyUrl before it is shown.

Quality gates

• npm run check + npm run test:coverage pass locally (1370/1370; non-root user, node 22).
• npm run build (left to CI).

Notes for the reviewer

LIMITS.md §3a and THREAT-MODEL.md still say pharn cannot use a proxy at all. Agents are blocked from editing those files, so a maintainer needs to update them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TvcuVhk8hTeDskp5pAJhnc

---

Generated by Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 1c53f41d-5208-4e12-bd4f-75f8101d31ca

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}