Fix -o for large and unfinished batches, usage exit codes, and CSV columns

[jclusso]

-o silently wrote a header-only file for batches that return download_file or are still verifying, and usage errors exited 1 with unknown even though the README promises 4 and invalid_input for bad input. This also makes account status --json pass the API body through like the other commands, shows the stored login email in status for API-key logins, and gives CSV exports every verify field with blanks where the API sent nothing.

[Copilot]

Copilot review overview

🟡 Changes recommended

Leaf-command usage errors remain misclassified, and large downloads use an unbounded multi-copy memory pipeline.

Review effort: Balanced
Findings: 3

Open (3)

• Wrap leaf argument validators to return invalid_input · New
• Honor --json=false after an earlier --json flag · New
• Stream large downloads to avoid excessive memory use · New

What changed in this PR

Fixes batch exports, CLI usage error handling, JSON passthrough, and stored-account display behavior.

Changes:

• Downloads and converts large batch results while producing complete CSV schemas.
• Classifies common usage failures as invalid_input.
• Preserves account API JSON fields and displays stored login emails.

File	Description
README.md	Documents exports, CSV columns, and usage errors.
internal/​output/​file.go	Expands CSV serialization and raw-field handling.
internal/​output/​file_test.go	Tests CSV schemas and omitted values.
internal/​output/​download.go	Converts downloaded batch results.
internal/​output/​download_test.go	Tests ZIP, CSV, and JSON conversion.
internal/​api/​download.go	Fetches presigned result files.
internal/​api/​download_test.go	Tests download security and errors.
cmd/​usage_errors.go	Classifies command-line usage failures.
cmd/​usage_errors_test.go	Tests usage error behavior.
cmd/​status.go	Displays stored account emails.
cmd/​skill.go	Rejects unknown skill subcommands.
cmd/​root.go	Installs root usage-error handlers.
cmd/​batch.go	Handles incomplete and downloadable batches.
cmd/​batch_output_test.go	Tests batch file output flows.
cmd/​auth_display_test.go	Tests account JSON and email display.
cmd/​account.go	Passes account JSON through unchanged.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The changed behaviors are consistently implemented, documented, and covered by focused tests.

Review effort: Balanced
Findings: None

Resolved since last review (3)

• Stream large downloads to avoid excessive memory use
• Honor --json=false after an earlier --json flag
• Wrap leaf argument validators to return invalid_input

[Copilot]

Copilot review overview

🔵 Needs a closer look

The new archive, network, serialization, and CLI error paths are broad enough to warrant final human validation.

Review effort: Balanced
Findings: None

[Copilot]

🟡 Changes recommended

Empty partial exports and large-batch summary formatting still have correctness and output-consistency issues.

3 open findings

• Prevent partial saves when no result rows are present · New
• Use Progress for verified count when inline rows are absent · New
• Route success headline through shared Human.Success formatting · New

🧠 Review effort: Balanced

[Copilot]

🔵 Needs a closer look

Large-batch summaries omit the established duplicate count, producing inconsistent totals.

0 open findings

3 resolved since last review

• Route success headline through shared Human.Success formatting
• Use Progress for verified count when inline rows are absent
• Prevent partial saves when no result rows are present

Previously missed (1)

In code that hasn't changed since last review

Batch summary drops duplicate counts from typed aggregate

internal/​api/​types.go:59

total_counts also contains duplicate (see the established API fixture in cmd/batch_e2e_test.go:195), but the typed aggregate drops it. A download-only batch with 10 state results and 5 duplicates can therefore print Verified 15 emails while the displayed breakdown sums to 10. Model the duplicate count and account for it in PrintBatchSummary (either display it or exclude it from the verified total according to the API semantics).

🧠 Review effort: Balanced

[jclusso]

Addressed the duplicate count finding in 228c004. The backend computes processed as the four state counts plus duplicate, so the summary now reports processed - duplicate as verified and notes skipped duplicates when there are any, keeping the headline equal to the breakdown.

[Copilot]

🔵 Needs a closer look

Download-only batches without count fields are incorrectly reported as having verified zero emails.

0 open findings

Previously missed (1)

In code that hasn't changed since last review

Avoid reporting zero verified emails when count is unavailable

internal/​output/​human.go:426

A download-only response can omit both progress shapes (the new TestBatchGet_DownloadFileHint fixture does exactly this). In that case verified remains zero, so the completed large batch is now reported as Verified 0 emails. Track whether a count was actually available and render a count-free completion result (for example, Batch complete) when it was not.

🧠 Review effort: Balanced

[jclusso]

Not changing this. A download-only response without counts cannot come from the API: batch_payload and sample_batch_payload in the backend always set total_counts, and download_file is only ever added to that same payload. Only a breaking API change would produce that shape, so the fallback would be dead code.

[Copilot]

🟢 Approved

The export, usage-error, CSV, and authentication changes are coherent and covered by focused tests.

0 open findings

🧠 Review effort: Balanced