feat(list flows): add pagination support

[mbevc1]

Bring kosli list flows in line with kosli list trails/list artifacts by adding --page and --page-limit flags (issue #978).

• embed shared listOptions, wire addListFlags and validate()
• sending per_page switches the endpoint to the {data, pagination} envelope response
• parse the envelope and print a "Showing page X of Y, total Z items" footer; include the page number in the empty-result message
• move the --name shorthand from -n to -N so it no longer clashes with --page-limit's -n (the family-wide convention)

Note: default preserves existing behaviour.

Closes #978

[claude]

Claude finished @mbevc1's task in 1m 53s —— View job

---

Review — feat(list flows): add pagination support

• Gather context (diff, commits)
• Static analysis (go build ./..., go vet ./cmd/kosli/) — both pass ✅
• Review current code state
• Post review feedback

This revision addresses all three points from my earlier review. Nice work. 👍

Previous feedback — resolved

• Redundant validate wrapper → removed; PreRunE now calls the promoted o.validate(cmd) from the embedded listOptions. ✅
• Help text didn't mention pagination → added listFlowsLongDesc + an Example block mirroring list trails. ✅
• Silent truncation of large orgs → solved more thoroughly than I suggested: pagination is now opt-in (o.paginate = cmd.Flags().Changed("page") || Changed("page-limit")), so the bare kosli list flows still returns all flows. This preserves backwards compatibility instead of just documenting the truncation — a better outcome. ✅

Remaining notes (all minor / non-blocking)

1. Two CLI-contract changes still need a changelog/release-note callout (process, not code):

   • --name shorthand moved -n → -N, so kosli list flows -n <substr> now binds to --page-limit (int) and fails. The family-wide convention is sound, but scripts will break.
   • --output json returns the {data, pagination} envelope when paginated, vs. a plain array otherwise. Worth flagging since the JSON shape now depends on whether pagination flags were passed.

2. Pre-existing latent panic (not introduced here, but in the touched function) — printFlowsListAsTable does tags := flow["tags"].(map[string]interface{}) (listFlows.go:167). If the API ever omits tags or returns null, the unchecked type assertion panics. Optional to harden while you're in here:

   tags, _ := flow["tags"].(map[string]interface{}) // nil-safe; range over nil is a no-op

3. Envelope detection by [ prefix (listFlows.go:142) is a reasonable heuristic and is well-commented. Just noting it couples table rendering to a wire-format assumption; if the unpaginated endpoint ever wraps its array, this branch silently mis-parses. Low risk given current API behaviour.

Testing

Good coverage — the new cases exercise pagination metadata, paging through pages, the empty-page message with page number, -N/-i shorthands, and all four boundary errors (negative/zero page & page-limit). The opt-in default is also covered by the existing array-shape assertions. Solid.

Summary

Clean, well-commented, conventions-aligned, and responsive to prior feedback. No blocking issues from me — the only must-do is documenting the two breaking CLI-contract changes in the release notes. Items 2 and 3 are optional hardening.
· 20260629_flow_pagination