Add primitive doctor and friendlier network-failure hints#68
Conversation
AGX walkthrough kept hitting ENETUNREACH from inside container environments where HTTPS_PROXY was set but Node 22+ ignores those env vars without NODE_USE_ENV_PROXY=1. The bare envelope said ENETUNREACH and nothing else, leaving the agent with no actionable next step. They asked for a doctor command that checks the local environment in one shot. This PR ships both halves. New command: primitive doctor Runs five checks and prints an interactive checklist on stderr with OK/WARN/FAIL prefixes, then a JSON summary on stdout for piping: 1. Node version, against the >=22 minimum. 2. Proxy env vars (NODE_USE_ENV_PROXY, HTTPS_PROXY, HTTP_PROXY, NO_PROXY). Warns specifically when HTTPS_PROXY is set without NODE_USE_ENV_PROXY because that is the exact failure mode that produced the AGX runs ENETUNREACH symptom. 3. API key resolution from flag, env, or saved login credentials. 4. Live /account roundtrip with the resolved key. 5. listDomains, surfacing active domains so the user can confirm the managed *.primitive.email subdomain is verified. Each non-OK row prints a hint line with the specific fix. Command exits 1 if any FAIL check fires; WARN does not fail the run so callers can pipe doctor through tooling without false negatives. Network-error hints in writeErrorWithHints Added a NETWORK_ERROR_HINTS map keyed by Node cause.code: ENETUNREACH, ECONNREFUSED, ETIMEDOUT, EAI_AGAIN. Every other CLI command that already routes through writeErrorWithHints (whoami, send, deploy, the generated operation commands) now prints a useful hint on network failure instead of the bare envelope. The hints point at NODE_USE_ENV_PROXY=1 and primitive doctor so the user has both an immediate fix to try and a way to bisect further. Tests: 11 new (3 doctor command + 8 network-error hint variants). All 154 cli-node tests green; lint and typecheck clean. Bumps cli-node to 0.24.2 so the new command and hint ship on the next CI publish.
# Conflicts: # cli-node/package.json
Greptile SummaryThis PR adds a
Confidence Score: 5/5Safe to merge — the new command is additive, the hint layer touches only the trailing output of an existing error formatter, and no existing behavior is changed. All changes are additive: a new command, a new read-only hint map, and a two-branch extension to the error output function. The previously raised issues are all addressed in the diff. The extractCauseDetails → extractErrorCode chain correctly propagates cause.code to the NETWORK_ERROR_HINTS lookup in production. No existing logic is altered. No files require special attention. Important Files Changed
Reviews (2): Last reviewed commit: "Sharpen checkProxy and checkApiKey diagn..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Greptile flagged two inaccurate diagnostic paths in the doctor command: 1. checkProxy hardcoded "HTTPS_PROXY set" in the warn message even when only HTTP_PROXY was set. A user debugging exactly the container failure mode this command exists to diagnose would read a contradiction between what the command reports and what the shell actually has. Rewrote to derive the var name(s) from process.env so the message names HTTP_PROXY, HTTPS_PROXY, or both depending on what's set. 2. checkApiKey labeled a credentials file that parsed as valid JSON but lacked an api_key field as "unreadable or malformed". Same bucket as a file that actually fails JSON.parse, which obscures the underlying issue. Split into two outcomes: "exists but contains no api_key" (file parsed) and "exists but is unreadable or malformed" (parse threw). The malformed path also surfaces the parser's error message so the user can see what was wrong without opening the file by hand. Also added the test coverage Greptile flagged as missing: the HTTP_PROXY-only warn path (which the original message bug masked), the both-vars-set message format, and the ETIMEDOUT network hint that was present in production code but unexercised. 162 cli-node tests green (5 new); lint and typecheck clean.
|
Addressed all three findings in 93efef1:
|
1 participant
Summary
AGX walkthroughs kept hitting
ENETUNREACHfrom inside container environments whereHTTPS_PROXYwas exported but Node 22+ ignores it withoutNODE_USE_ENV_PROXY=1. The CLI's error envelope just saidENETUNREACHand nothing else; the agent had no actionable next step. They asked for adoctorcommand. This PR ships both halves: the doctor command plus a network-error hint layer so the existing commands stop being dead ends.New command:
primitive doctorRuns five checks and prints an interactive checklist on stderr with
OK/WARN/FAILprefixes, then a JSON summary on stdout for piping. The checks cover the four things that actually fail in practice:>=22minimum).NODE_USE_ENV_PROXY,HTTPS_PROXY,HTTP_PROXY,NO_PROXY. Specifically warns whenHTTPS_PROXYis set withoutNODE_USE_ENV_PROXY=1, which is the AGX failure mode./accountroundtrip with the resolved key.listDomains, surfacing active domains so the user can confirm the managed*.primitive.emailsubdomain is verified.Each non-OK row prints a hint line with the specific fix. The command exits
1on anyFAIL;WARNdoes not fail.Network-error hints in
writeErrorWithHintsAdded
NETWORK_ERROR_HINTSkeyed by Nodecause.code:ENETUNREACH,ECONNREFUSED,ETIMEDOUT,EAI_AGAIN. Every CLI command that already useswriteErrorWithHints(whoami, send, deploy, all generated operation commands) now prints a useful hint on network failure instead of the bare envelope. The hints referenceNODE_USE_ENV_PROXY=1andprimitive doctorso the user has an immediate fix to try and a way to bisect further.Tests
11 new tests (3 in doctor.test.ts covering renderRow / checkNode / checkProxy / checkApiKey, 8 in api-command.test.ts covering each network-error hint variant). All 154 cli-node tests green; lint and typecheck clean.
Release
Bumps cli-node from 0.24.0 to 0.24.2 so the new command and hint ship on the next CI publish.
Test plan
primitive doctorin a fresh shell with valid PRIMITIVE_API_KEY shows 5 OK rows and exits 0.unset PRIMITIVE_API_KEY && primitive doctorshows API key FAIL with the login hint and exits 1.HTTPS_PROXY=http://localhost:9999 primitive whoami(or any command) returns an ENETUNREACH envelope followed by the NODE_USE_ENV_PROXY hint.