Add admin refund-balance CLI

[gianfrancopiana]

Ref antiwork/gumroad/issues/5153

What

Adds gumroad admin users refund-balance for suspended users. The command previews unpaid balance first, requires --expected-email, then queues refund balance only if the previewed count and total still match.

It also supports --dry-run for previewing the guarded POST without queueing refunds, and updates the admin docs and embedded skill guidance to match the new flow.

Why

This closes the gap between the internal admin API and the CLI for the post-suspension refund workflow. The stale-preview guard reduces the risk of refunding the wrong balance after state changes, and the required email check adds a basic account-safety guard.

---

This PR was implemented with AI assistance using gpt‑5.5 xhigh.

---

Note

High Risk
Queues buyer refunds from Gumroad-held unpaid balance; mistakes or stale preview mismatches are financially impactful despite count/total/email guards.

Overview
Adds gumroad admin users refund-balance for post-suspension workflows: it GETs unpaid balance, then POSTs to queue refunds only when the previewed purchase count and total cents still match (plus required --expected-email).

--dry-run still hits the preview endpoint but prints the guarded POST instead of queueing refunds; zero balance skips confirmation and POST with a skipped result. admincmd now exposes mutation token/actor banner helpers so this two-step flow can show the admin actor before preview. README, embedded skill, and tests document and lock in the behavior.

^{Reviewed by Cursor Bugbot for commit 955ecb1. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a gumroad admin users refund-balance CLI command for queuing buyer refunds on a suspended user's unpaid balance. The command uses a two-step preview-then-mutate pattern with stale-state guards, mutation-token-first auth, and an --expected-email safety check.

• New command (refund_balance.go): GETs users/unpaid_balance, resolves mutation token, optionally shows actor banner, then either dry-runs or POSTs users/refund_balance with the previewed count and total as guards; zero-balance short-circuits before the confirmation prompt.
• admincmd exports ResolveMutationToken and WriteActorBanner to allow this two-step flow without duplicating internal token-policy logic.
• Docs and tests: README, SKILL.md, and the embed test are updated; the new test file covers auth validation, dry-run, JSON/plain output, cancellation, and server error surfacing.

Confidence Score: 5/5

The command correctly gates every path behind mutation-token auth, previews balance before any POST, and uses the previewed count and total as stale-state guards. Zero-balance and cancellation paths exit cleanly without making the refund call.

All four concerns raised in prior review rounds have been addressed: zero-balance now short-circuits before confirmation, JSON output is handled consistently across all exit paths, the unused Total field has been removed from the structs, and ResolveMutationToken is called before the dry-run branch so the same auth policy applies to both paths. No new logic defects were identified.

No files require special attention. refund_balance.go is the highest-risk file given the irreversible financial workflow, but its auth, guard, and output logic all appear correct.

Important Files Changed

Filename	Overview
internal/cmd/admin/users/refund_balance.go	Core implementation of the refund-balance command; stale-state guards, auth flow, and output modes are all present. Previously raised issues have been addressed. No new blocking issues identified.
internal/cmd/admin/users/refund_balance_test.go	Good coverage: auth guard, happy path, dry-run, JSON/plain output, zero-balance skip, cancellation, and server-error surfacing are all tested.
internal/admincmd/read.go	Adds thin public wrappers delegating to existing unexported helpers; no logic change to existing paths.
internal/cmd/admin/users/users.go	Registers newRefundBalanceCmd and adds example line; straightforward wiring change.
skills/gumroad/SKILL.md	Documents the new command usage and output fields correctly including both the dry-run and live examples.

_{Reviews (4): Last reviewed commit: "Validate auth for refund dry-runs" | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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