feat: add gh models usage command for premium request billing

[marcelsafin]

Summary

Adds a new gh models usage command that displays premium request usage statistics from the GitHub billing API. This addresses #81.

What it does

$ gh models usage --today

Premium request usage for marcelsafin (2026-03-29, today)

PRODUCT  MODEL              REQUESTS  GROSS  NET
Copilot  Claude Opus 4.6    51.0      $2.04  $0.00
Copilot  Claude Sonnet 4.6  1.0       $0.04  $0.00

Total: 52 requests, $2.08 gross, $0.00 net
All usage included in your plan (100% discount)

Features

• Shows requests, gross cost, and net cost per model
• --today flag for daily usage
• --year, --month, --day flags for specific periods
• Sorted by gross amount descending
• Color-coded discount/cost summary (green = 100% included, yellow = partial cost)
• Helpful error message when user scope is missing

API Used

• GET /user — resolve username
• GET /users/{username}/settings/billing/premium_request/usage — premium request breakdown

Files Changed

• cmd/usage/usage.go — new command implementation
• cmd/usage/usage_test.go — 7 test cases with httptest mock server
• cmd/root.go — register usage subcommand
• pkg/command/config.go — add Token field to Config for auth

Testing

All existing tests pass. New tests cover:

• Happy path with usage table
• Net cost display
• Empty usage
• Missing token error
• --today flag
• Help text
• Sort order verification

Closes #81

[Copilot]

Pull request overview

Adds a new gh models usage subcommand to fetch and display premium request usage/cost breakdown from the GitHub billing API, fitting into the CLI’s command suite alongside list, run, eval, etc.

Changes:

• Introduces cmd/usage command to query /user + premium request billing usage and render a table + totals/discount summary.
• Adds a Token field to command.Config and plumbs it from the root command.
• Adds initial unit tests for the new command and registers the subcommand in cmd/root.go.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
pkg/command/config.go	Adds Token to shared command config; updates terminal-based constructor accordingly.
cmd/usage/usage.go	Implements gh models usage, including API calls, sorting, and output formatting.
cmd/usage/usage_test.go	Adds httptest-based coverage for common usage flows and output formatting.
cmd/root.go	Registers the new usage subcommand and passes auth token into config.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

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

[marcelsafin]

Addressed Copilot review feedback in 5ac332d:

Behavior fixes

• Date validation — --year/--month/--day now rejected with a clear error before any API call (year ≥ 1, month 1–12, day 0–31).
• --today mutual exclusion — using --today with --year/--month/--day now errors via Cobra's MarkFlagsMutuallyExclusive instead of silently overriding.
• Totals match visible rows — GrossQuantity > 0 filter now applied to totals too, so "Total: …" matches the printed table.
• NaN/+Inf guard — (totalNet / totalGross) * 100 now guarded; emits 'gross amount unavailable' note when totalGross == 0.

Test fixes

• newTestServer now matches the exact billing path (no more prefix/suffix wildcards) so tests fail loudly on unexpected endpoints.
• Sort-order assertion now requires both substrings present (require.GreaterOrEqual(idx, 0)) so it can't pass on -1 < 10.
• Added tests for the NaN guard, --today mutual exclusion, invalid month, and invalid day.

Already-addressed feedback (verified): http.Client with 30s timeout via opts.httpClient, sort.Slice for ordering, opts struct instead of mutable global, and root_test.go already asserts the usage subcommand in help output.

@copilot review

[marcelsafin]

All review threads are resolved and make check passes on 5ac332d. Ready for another maintainer pass.