fix(cor-573): CLI 503 → scheduled-maintenance copy

[dvydra]

https://entire.io/gh/entireio/cli/trails/645

COR-573 (CLI surface) — scheduled-maintenance 503 copy

Part of COR-573 — User-facing maintenance signal, split per surface. This is the CLI surface (1 of 3); siblings cover the SPA banner and the incident.io statuspage.

What

When the control plane returns HTTP 503 — a draining/maintenance host, i.e. the COR-562 cutover scenario — the entire CLI printed the raw control-plane request failed with status 503. renderCoreError now special-cases 503 to a friendly, shared message:

Entire is under scheduled maintenance — please try again shortly

Changes

• internal/coreapi/client.go — new HTTPStatus(err) (int, bool) helper, alongside APIError.
• cmd/entire/cli/corecmd.go — renderCoreError 503 branch + shared maintenanceMessage const (//nolint:staticcheck — user-facing copy kept verbatim across surfaces).
• cmd/entire/cli/corecmd_test.go — TestRenderCoreError_ScheduledMaintenance (bare 503 + 503-with-body) and TestRenderCoreError_PassThrough (nil + transport error).

Coordination

• Copy is verbatim-shared with the Cloudflare edge 503 page (COR-566) and the SPA banner (COR-573 sibling). Convergence tracked in entiredb#2121.
• Touches entireio/cli alongside COR-572 (client timeout). My change is in renderCoreError; COR-572 is in coreapi.New() — distinct functions, no file-region overlap.

Verification

• go test ./cmd/entire/cli/ ✓
• mise run lint → 0 issues ✓

NO MERGE / NO DEPLOY — draft only.

🤖 Generated with Claude Code

---

Note

Low Risk
User-facing error copy only; no auth, transport, or API behavior changes beyond 503 messaging.

Overview
Control-plane commands no longer print generic control-plane request failed with status 503 when the API returns 503. renderCoreError now maps that status to shared user-facing copy: Entire is under scheduled maintenance — please try again shortly (aligned with COR-566 edge and the SPA banner), including when a problem-detail body is present.

coreapi.HTTPStatus was added so the CLI can detect API status codes without parsing APIError text. Tests cover 503 (bare and with body), nil, and transport passthrough.

^{Reviewed by Cursor Bugbot for commit 058e835. Configure here.}

[Copilot]

Pull request overview

This PR improves the user-facing error output for control-plane commands by mapping HTTP 503 Service Unavailable responses (scheduled maintenance / draining hosts) to a friendly, shared message instead of the generic control-plane request failed with status 503.

Changes:

• Added coreapi.HTTPStatus(err) (int, bool) to extract an HTTP status code from control-plane API errors without parsing text.
• Updated renderCoreError to special-case 503 and return the scheduled-maintenance copy (even when a problem-detail body is present).
• Added unit tests covering 503 (with/without body) plus nil and transport-error passthrough.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
internal/coreapi/client.go	Adds HTTPStatus helper to detect whether an error is a core API status error and extract its status code.
cmd/entire/cli/corecmd.go	Special-cases 503 in renderCoreError to return the shared maintenance message; keeps other API errors mapped via APIError.
cmd/entire/cli/corecmd_test.go	Adds tests asserting 503 maps to the maintenance message and that nil/transport errors pass through unchanged.

[dvydra]

Copy is now the bare canonical headline (per COR-573 spec). Dropped the — please try again shortly suffix, so the CLI 503 message is byte-identical to the COR-566 edge <h1> and the SPA banner heading: Entire is under scheduled maintenance.

If you'd prefer a CLI-specific suffix, say so and I'll apply the same suffix to the SPA banner + edge page so all three stay identical — your call.

Drain-path boundary: a black-holed/draining host (COR-572) surfaces as a timeout, not a 503, so this copy only fires on an explicit 503 (e.g. behind the COR-566 edge page). Timeouts are deliberately left as generic errors — not mapped to maintenance. Open architecture question for you: is the CLI's core endpoint behind the edge-503 hosts? If not, a window-scoped timeout→maintenance mapping may be worth adding.