feat(cli): add doctor command to validate environment and provider setup

[Nsanjayboruds]

Problem

Missing environment diagnostics in the CLI make onboarding and PR iteration slow. Users frequently hit hidden issues (Node/PNPM version mismatch, missing AI provider keys for Groq/Google/Mistral, workspace install problems, or network reachability failures).
These issues only surface during runtime commands, producing unclear errors and increasing back-and-forth with maintainers.
There is no single command to proactively verify setup and provide remediation guidance.

Solution

Add lingo.dev doctor to run modular checks and print a structured pass/fail report with actionable fixes.
Checks:
Versions: Node (>=18), PNPM presence, and workspace integrity (pnpm install done).
Config: .env/environment variables for supported providers (Groq/Google/Mistral).
Providers: basic SDK init (mock mode when keys are missing); optional non‑billable smoke test only with --live.
Network: DNS + HTTPS reachability for provider endpoints with timeouts.
CLI UX:
Flags: --json for CI, --strict to exit non‑zero on any failure, --provider= to focus checks, --live to attempt safe non‑billable calls.
Output: human-readable table plus remediation tips; machine-readable JSON when requested.
Acceptance criteria:
pnpm lingo.dev doctor prints a clear report with pass/fail and suggested fixes.
--json outputs structured results suitable for CI pipelines.
Detects missing keys, version mismatch, and unreachable endpoints reliably (with timeouts).
Unit tests for each check module and a small integration test for CLI wiring.
Changeset added from repo root.
Non‑goals:
Managing/storing credentials or performing billable calls without explicit opt‑in (--live).
Requested assignment: I’d like to work on this—please assign me.

Visuals

$ pnpm lingo.dev doctor

Lingo.dev Doctor Report
────────────────────────────────────────────
Environment
Node version 20.11.1 ✅ OK (>=18)
PNPM found (9.12.3) ✅ OK
Workspace install completed ✅ OK

Configuration
GROQ_API_KEY missing ❌ Set GROQ_API_KEY in .env
GOOGLE_API_KEY present ✅ OK
MISTRAL_API_KEY present ✅ OK

Network
groq.com API unreachable (timeout) ❌ Check internet/DNS/firewall
googleapis.com reachable ✅ OK
mistral.ai reachable ✅ OK

Providers (mock)
Groq init skipped (no key) ℹ️ Use --live after setting key
Google init initialized ✅ OK
Mistral init initialized ✅ OK

Summary
3 checks failed, 9 passed
Remediation:
- Add GROQ_API_KEY to .env and re-run doctor
- Investigate network reachability to groq.com (proxy/firewall)
Exit code: 1 (use --strict for CI)

Example JSON output:

{
"environment": {
"node": {"version": "20.11.1", "ok": true},
"pnpm": {"version": "9.12.3", "ok": true},
"workspaceInstall": {"ok": true}
},
"config": {
"GROQ_API_KEY": {"present": false},
"GOOGLE_API_KEY": {"present": true},
"MISTRAL_API_KEY": {"present": true}
},
"network": {
"groq.com": {"reachable": false, "error": "timeout"},
"googleapis.com": {"reachable": true},
"mistral.ai": {"reachable": true}
},
"providers": {
"groq": {"init": "skipped"},
"google": {"init": "ok"},
"mistral": {"init": "ok"}
},
"summary": {"passed": 9, "failed": 3}
}

Workarounds

OS: Linux (Ubuntu), local repo cloned from upstream.
Verified versions: node -v (>=18), pnpm -v (9.x).
Clean install: pnpm install --frozen-lockfile.
Built and tested: pnpm turbo build --force, pnpm turbo test --force.
Ran CLI locally:
Watch mode: cd packages/cli && pnpm run dev
Help check: cd packages/cli && pnpm lingo.dev --help
Attempted manual “doctor-like” checks:
Created .env and tested provider keys (Groq/Google/Mistral).
Reachability: curl/ping/dig for provider endpoints; observed timeouts behind corporate proxy.
Mocked provider init when keys absent; confirmed CLI produces opaque errors without early diagnostics.
Tried demos:
Next 16: pnpm --filter @compiler/demo-next dev → OK with Google/Mistral keys; Groq unreachable in my network.
Vite SPA: pnpm --filter vite-react-spa dev → OK; same Groq reachability issue.
Mitigations tried: toggled proxy/VPN, cleared DNS cache, different network; errors persisted. These motivated a unified doctor command to surface problems early with actionable fixes.

[vrcprl]

@Nsanjayboruds - sounds very interesting from the first look! Let me discuss this internally with the team and get back to you.

[Nsanjayboruds]

Thanks for taking a look! Happy to provide more details, mockups, or even start working on an initial implementation if it helps the discussion. Looking forward to your feedback.