[cristim]

Closes #2266

What

Adds cudly archera-line-items, a read-only command that lists Archera vendor line items so a user can find a real line_item_id before running archera-comparison with an explicit line-item filter.

• Reuses insurance.Client.LineItems from the pinned cloud-commitments-go (all pages, no partial result). No dependency bump, no ID mapping.
• Output carries exact nullable decimals and IDs. It never echoes the API key or settings secrets, and it is size-bounded.
• archeraSettings(org, plan) is shared with archera-comparison.

Commits (each <= 400 additions+deletions)

1. feat: command, wiring, fixture, registration and window/comparison-reuse tests (362)
2. test: validation, late-page failures and privacy (147)
3. docs: README, docs/cli index, docs/cli/archera-line-items.md (39)

Local verification (macOS, this HEAD)

• go build -o cudly ./cmd, go vet ./..., go test ./..., make lint: all pass.
• Tests run through rootCmd.Execute against an httptest vendor server. They cover page-2 HTTP 500, decode error, bad metadata, duplicate item, oversize body, cancellation, 429 and redirect, and all of these produce empty output. Listed IDs are reused in the comparison filter, asserted on the request query.
• Mutation probe: disabling pagination (end < total && false) fails TestArcheraLineItemsWindowsAndComparisonReuse.
• Synthetic fixtures only; no live Archera account was called.

Independent reviews follow as PR comments.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a read-only command to browse Archera plan line items in pages, with table or JSON output. Results include item and offer details, selection and commitment values, and paging information.
  • Organization and plan settings can be supplied using command-line flags or environment variables.
• Documentation
  • Added CLI guidance covering configuration, output formats, pagination, and command limitations, with links to the Archera line-items guide.

[cristim]

@coderabbitai review

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: LeanerCloud/cloud-commitments-cli/.coderabbit.yaml
• Review profile: CHILL
• Plan: Essentials
• Run ID: 3f1a3cd0-5622-4b6d-a708-b6a535441e48

📥 Commits

Reviewing files that changed from the base of the PR and between 83a7193 and c59223b.

📒 Files selected for processing: 8

• README.md
• cmd/archera_comparison.go
• cmd/archera_comparison_test.go
• cmd/archera_line_items.go
• cmd/archera_line_items_test.go
• cmd/testdata/archera_line_item.json
• docs/cli/README.md
• docs/cli/archera-line-items.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

📝 Walkthrough

The CLI adds an opt-in, read-only archera-line-items command. It retrieves Archera plan line items, sorts them by UUID, and displays a local page as a table or JSON. The command validates inputs and complete retrieval before writing output.

Changes: Archera line-item discovery

Layer / File(s)	Summary
Command configuration and settings cmd/archera_line_items.go, cmd/archera_comparison.go, cmd/archera_comparison_test.go, cmd/archera_line_items_test.go	The new command defines output and paging options and accepts organization and plan values from flags or environment. The API key remains environment-only. Test helpers reset and invoke either Archera command.
Retrieval, pagination, and validation cmd/archera_line_items.go, cmd/archera_line_items_test.go, cmd/testdata/archera_line_item.json	The command fetches and converts line items, sorts them, and builds the requested local page. Tests cover pagination, request deadlines, invalid inputs, and failures that produce no partial output.
Rendering and command documentation cmd/archera_line_items.go, cmd/archera_line_items_test.go, README.md, docs/cli/README.md, docs/cli/archera-line-items.md	The command renders bounded JSON or table output with paging metadata and disclosures. Tests cover output handling. The CLI references describe the command, its fields, and its limits.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant CLI as archera-line-items command
  participant Settings as archeraSettings
  participant Client as insurance.Client
  participant Stdout as stdout
  CLI->>Settings: Resolve organization and plan settings
  CLI->>Client: Fetch all line-item pages
  Client-->>CLI: Return line items
  CLI->>Stdout: Write rendered local page

Loading

Merge Risk: ⚪ Minimal · up to c5922

No actionable issue remains from the supplied evidence; the command is mergeable after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 8.70% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 4 files. (4 skipped: 4…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the primary change: adding Archera vendor line-item listing for comparison filters.
Linked Issues check		Issue #2266 coding requirements are met. archera-line-items is registered as a read-only command. It uses insurance.Client.LineItems, fetches all vendor pages before output, applies bounded local …
Out of Scope Changes check		The changes stay within issue #2266. The shared archeraSettings change supports the new command without changing comparison behavior. Comparison test-helper updates verify ID reuse and command isola…

Full details: Linked Issues check

Explanation

Issue #2266 coding requirements are met. archera-line-items is registered as a read-only command. It uses insurance.Client.LineItems, fetches all vendor pages before output, applies bounded local windows, supports table and JSON, preserves IDs and exact decimal text, and emits the required disclosures. Configuration uses the environment-only API key and existing org/plan settings. Tests cover validation, pagination, late failures, privacy, cancellation, redirects, 429 responses, size limits, help, and reuse of a listed ID in archera-comparison. go.mod contains the requested cloud-commitments-go/pkg pin and unchanged provider pins. Documentation is included.

Full details: Out of Scope Changes check

Explanation

The changes stay within issue #2266. The shared archeraSettings change supports the new command without changing comparison behavior. Comparison test-helper updates verify ID reuse and command isolation. The README and CLI documentation describe the new discovery workflow. No unrelated feature, purchase, binding, live vendor integration, or dependency-scope change is present.

Full details: Docstring Coverage

Explanation

Docstring coverage is 8.70% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 23 functions across 4 files. (4 skipped: 4 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

• Fix all pre-merge checks with AI

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

⚠️ Action not completed

Already reviewed the last commit. Use @coderabbitai full review to rerun a review of the entire changeset.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Independent review A (claude-cc-libs-reviewA, Sonnet, cold brief, not the author)

Reviewed SHA: c59223b
Verdict: APPROVE. No blocker or major findings.

Local verification (scratch worktree at this SHA, macOS):

• go build ./cmd, go vet ./..., go test ./... and make lint (0 issues) all pass.
• Commit sizes are 362, 147 and 39 lines. Files are under 500 lines.

What was attacked:

• Field mapping: every printed field was compared against the pinned insurance.LineItem (line_items.go:18-57). Nullable pointers stay null, and decimals stay exact via archeraMoney.
• Pagination: the command only calls client.LineItems (line_items_client.go:89-119), which returns all pages or an error. The tests cover page-2 500, decode, bad metadata, duplicate, oversize, cancellation, 429 and redirect.
• Privacy: every output and error path goes through redaction, and the tests assert the key is absent from stdout, stderr, logs and errors.
• Reuse: archeraSettings is shared with archera-comparison, with no behaviour change.

Mutation probes:

Probe	Result
nil region rendered as ""	caught
window end shortened by one	caught
per-field redaction removed	caught
whole-output key check removed	survived (defense in depth, see nit 1)

Nits, to be addressed in a follow-up commit on this PR:

1. cmd/archera_line_items.go archeraListingRender: no test reaches the whole-output key check. A test with a key split across adjacent fields is needed.
2. *archeraMoney(row.SelectedCommitment) relies on upstream always setting the field (line_items.go:140). Add a pointer comment.
3. The table output uses raw tabs. Use text/tabwriter so columns align.

[cristim]

Independent review B (claude-cc-libs-reviewB, Sonnet, cold brief, not the author, independent of review A)

Reviewed SHA: c59223b
Verdict: APPROVE. No actionable findings.

Local verification (scratch worktree at this SHA, macOS): go build ./cmd, go vet ./..., go test ./... and make lint (0 issues) all pass.

What was attacked:

• UX contract: run against the built binary. Covered --help flags and defaults, root listing, missing key, positional-arg rejection, and that --limit=<key> does not echo the key. The docs match the code: 30s aggregate deadline, offset edge cases, 512 KiB cap, 13 fields, ID sort.
• Pinned client: LineItems in the pkg module cache returns all rows or an error. It validates pagination, rejects cross-page duplicate IDs and bounds bytes. SelectedCommitment is always non-nil after decode, so the dereference is safe.
• archeraSettings refactor: the only other caller passes org and plan in the same order. Swapping them is caught by TestArcheraFlagsOverrideEnvironment.
• Secrets: every error goes through archeraSafeError, and the final JSON is checked by archeraKeyReadable. Tests cover a 500 body echoing the key, a key equal to a UUID, ESC bytes, and log/slog capture. No Authorization header is ever printed.
• Concurrency and size: one 30s context across all pages, plus tests for cancellation, 429 Retry-After, redirects, empty stdout on late-page failure, and the 512 KiB output cap.

Mutation probes:

Probe	Result
sort descending	killed
offset > total changed to >=	killed
swap org/plan in archera-comparison	killed
disable per-row ID key check	survived; the final render check covers it (defense in depth)

Low / info (non-blocking):

• SetFlagErrorFunc also genericizes unknown-flag errors.
• The per-row ID check is redundant with the final render check.

Both are tracked with review A's nits for a follow-up PR.

[cristim]

Merge gate verdict (claude-cc-libs)

Every gate holds at head c59223b, which is unchanged since both reviews:

• Two independent reviews: A and B both APPROVE (comments above). Neither reviewer is the author.
• Local verification at this SHA: build, vet, go test ./... and make lint pass in both reviewers' scratch worktrees, plus the author's run. Fixtures are synthetic; there is no real-account coverage of the Archera API.
• CI: every required job is green on this SHA.
• CodeRabbit: no actionable comments, no inline threads, 0 unresolved threads.
• Mergeability: MERGEABLE/CLEAN against main 83a7193.

The non-blocking nits from both reviews go in a follow-up PR: a test for the whole-output key check, text/tabwriter table alignment, and an unknown-flag error message.

Squash-merging per the vacation-run auto-merge authority.