fix(sip): resolve short realm names through realm list

[jzeng-bw]

Fixes #37.

What was wrong

The SIP commands advertised realm references as an ID, short name, or FQDN, but Service.GetRealm passed the reference directly to GET /accounts/{accountId}/realms/{ref}. On the account reported in #37, --realm vapi returned 404 while the same realm's ID and FQDN worked. This broke the documented credential workflow and also affected realm reads and writes that use the shared resolver.

Existing credential-create mocks returned success for /realms/vapi, so they did not reproduce the production failure.

The fix

GetRealm keeps the direct lookup first. If it returns 404 for a valid, non-numeric short name, it now:

1. Lists the account's realms with GET /accounts/{accountId}/realms.
2. Matches the derived short name case-insensitively, including names containing hyphens.
3. Fetches the matching realm by its canonical ID, preserving the full detail response that callers expect.

For example, band sip credential list --realm vapi --plain now resolves through /realms/vapi → /realms → /realms/{id}, then lists credentials under that ID. The fallback adds two GETs only when the initial short-name lookup returns 404; successful direct lookups remain a single GET.

The shared change covers realm get/update/delete and all credential --realm consumers. UpdateRealm additionally uses the resolved ID for its PUT and any follow-up GET; otherwise its initial read would succeed but the write would still target the unsupported short name. Its existing read-modify-write behavior continues to preserve omitted fields.

Compatibility and error behavior

• IDs and FQDNs retain their direct lookup behavior. Numeric references remain IDs, even on 404; use the FQDN for an all-numeric realm name.
• A direct 401/403 or server error returns immediately without attempting a list fallback.
• No matching name returns the original 404, preserving exit 3.
• A failed list request retains its underlying error classification and adds the realm name as context.
• Multiple case-insensitive matches return exit 6 with guidance to use an ID or FQDN, rather than selecting an arbitrary realm.
• No new flags, dependencies, or output fields. README.md and AGENTS.md document the resolution and error behavior.

Tests

• TestGetRealmResolution — 13 cases covering short names, mixed case, hyphenated names, direct ID/FQDN/name success, missing names/IDs/FQDNs, initial 401/403/500, list 403, and ambiguous matches. Asserts the request paths and order, exit codes, and returned realm details.
• Credential-create stub now rejects /realms/vapi and serves list/ID endpoints, so existing idempotency and secret-handling tests exercise the fallback.
• TestUpdateRealm_ReadModifyWritePreservesUnspecifiedFields now rejects short-name requests and requires the canonical ID on the detail and update paths while checking preservation of description/default fields.

Verified locally with Go 1.26.6: go test ./internal/sip ./cmd/sip ./cmd; formatting and git diff --check clean. CI builds and full tests pass on Ubuntu, macOS, and Windows; lint, govulncheck, and Snyk checks also pass. Live API verification was not performed.

This PR was substantially AI-generated with Codex.

[bwappsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.