feat(insurance): explicit Archera comparison command using pkg/insurance #2156

Goal

The CLI consumes the merged Archera comparison contract pkg/insurance (cloud-commitments-go #285). It gets an explicit, read-only comparison command for a configured Archera plan. Today nothing in the CLI consumes pkg/insurance.

Contract being consumed

pkg/insurance on go main: NewClient(Config{APIKey, OrgID}, hc), (*Client).Comparison(ctx, ComparisonRequest{...}), (*Client).Plan, *HTTPError, and AssessProductSupport. Money is *big.Rat, and nil means unknown. Premium is included in totals. There is no currency field. The client never retries, never follows redirects, pins the origin and redacts the key in fmt output (except %p).

Scope

1. Dependency: bump cloud-commitments-go/pkg from 90e61e668b99 (which predates pkg/insurance) to a commit containing feat(frontend/recs): auto-refresh on page open when stale; drop freshness indicator + Refresh button (closes #284) #285. Use tidy only.
2. Configuration: the same names as the platform, default off.
   • ARCHERA_API_KEY is read from the environment only, never from a flag.
   • ARCHERA_ORG_ID and ARCHERA_PLAN_ID come from env or explicit non-secret flags. These are Archera IDs, not recommendation IDs.
   • The repo's existing env names use a CUDLY_ prefix. Whether to use the shared unprefixed names or CUDLY_ARCHERA_* is open contract question 1 on the tracking issue.
3. Command: an explicit comparison action, for example cmd/archera_comparison.go, wired in cmd/main.go and validated in cmd/validators.go.
   • It is independent of --purchase and never purchases.
   • It makes no Archera call unless the action is requested.
   • It prints the plan-wide comparison as a separate section or file and never maps it onto unrelated recommendation CSV rows.
4. Output:
   • Unknown money is printed as "unknown", never 0.
   • Term and fallback reasons are shown.
   • The "premium included" and "no currency field" notes are printed.
   • AssessProductSupport is shown per row, and unknown is the default.
   • The existing mandatory Archera disclosures stay visible.
5. Errors:
   • With the action requested but config incomplete, the command exits non-zero with a sanitized error naming the missing setting.
   • Vendor errors use HTTPError's sanitized message and Retry-After.

Acceptance criteria

• The default run (action not requested) makes no Archera request even when config is set. A test injects a failing transport.
• Requested with incomplete config: non-zero exit, a sanitized message, and no key in the output.
• Requested with complete config: an offline test runs the real command path (env, constructor, documented GET, decode, printed output) against httptest through an injected transport, and asserts the path, the header, premium-inclusive totals, unknown rendering and the disclosures.
• The key never appears in stdout, stderr or CSV. A test greps the output for the synthetic key.
• README and docs/ describe the command, the config and the disclosures.

Test strategy

Recorded or synthetic official-schema responses served by httptest, with a synthetic key and IDs. No live calls to api.archera.ai. Test one package at a time.

Dependencies

• Depends on the platform issue settling the config names and error wording (the tracking issue sets the order).
• Requires the pkg pin bump.