feat(api-client): emit X-DevHelm-Surface telemetry headers

[caballeto]

Summary

Reports the CLI's identity to the DevHelm API on every authenticated request so the GTM rollup can attribute usage to the CLI vs. SDKs / MCP / Terraform. Wire contract documented at https://devhelm.io/telemetry; the matching API-side handler shipped in `devhelmhq/mono#332`.

What lands on the wire (defaults)

Header	Value
`X-DevHelm-Surface`	`cli`
`X-DevHelm-Surface-Version`	`package.json` `version`
`X-DevHelm-Cli-Os`	`-` (e.g. `darwin-arm64`, `linux-x64`)
`X-DevHelm-Cli-Install-Source`	`npm` | `brew` | `other`

Install source detection (in order):

1. `DEVHELM_INSTALL_SOURCE` env var — set this in the brew formula or any other distribution channel that knows better than the heuristics
2. realpath of `process.argv[1]`:
   • `/Cellar/`, `/opt/homebrew/`, `/home/linuxbrew/` → `brew`
   • `/node_modules/` → `npm`
3. Otherwise `other` (deliberately doesn't guess wrong)

Opt-out

`DEVHELM_TELEMETRY=0` returns an empty headers object — the API receives no surface signal at all. Single env var, not per-command flag. Auth + tenant headers are unaffected. Strict equality on `"0"` (so `DEVHELM_TELEMETRY=on` / `true` / `yes` don't accidentally read as opt-out).

Zero callsite changes

`createApiClient` is the single bottleneck for every CLI command, so spreading the headers there covers all 73 commands without touching one of them. The telemetry module (`lib/surface-telemetry.ts`) is a pure function of `process.*` with no external state.

Tests

• 6 new `test/lib/surface-telemetry.test.ts` tests: defaults, OS detection, install-source override, env opt-out, strict-on-`"0"` parsing
• Full suite (899) green
• ESLint + `tsc` clean

Version bumped to `0.6.3` (additive feature; patch bump because no public CLI surface changed).

Test plan

• `npm run lint` — clean
• `npm run typecheck` — clean
• `npm test` — 899 / 899 green
• Post-release: smoke a CLI call against stage; verify the `org_surface_usage` row + the `cli_first_run` PostHog event

Made with Cursor