feat(im): add +chat-members-list shortcut for member listing

[shifengjuan-dev]

Summary

Adds a dedicated +chat-members-list shortcut that lists chat members, returning users and bots in separate users[] / bots[] buckets.

It owns its pagination loop (mirroring the paginateLoop conventions: per-page log line, --page-limit cap, non-advancing-token guard) because the list_members response is multi-bucket — the generic --page-all merger is built for single-array responses and would silently drop the bots[] bucket and the final-page truncations[] signal.

What it does

• Merges users[] and bots[] across pages; takes truncations[] / has_more / page_token from the last page so a server-side cap is never hidden
• Surfaces truncations[] with a loud stderr warning when the server caps a bucket due to security config (the list is incomplete)
• --member-types filter (user/bot), --member-id-type, and the standard --page-all / --page-limit / --page-token flags
• With --page-all and no explicit --page-size, uses the max page size to minimize round-trips
• Docs: SKILL.md Shortcuts table + references/lark-im-chat-members-list.md

Test plan

• Unit: bucket merge (users+bots), last-page truncations[], has_more/page_token from last page, --member-types normalization, --page-all integration over mocked pages, --page-limit cutoff, effective page-size selection
• Live: verified against a 324-member group (server-truncated at 100 → truncations:[{"limit":100,"member_type":"user"}] + stderr warning) and a 21-user/5-bot group (both buckets merged, no false warning); --member-types bot filter returns bots only

• New Features

  • Added a new +chat-members-list skill/shortcut to list chat members, with support for user/bot filtering and cursor-based pagination.

• Documentation

  • Updated the chat member management docs to reflect the available operations and adjusted permission scope mappings accordingly.

• Bug Fixes / Quality

  • Added tests to verify multi-page member merging, truncation handling, and pagination stop behavior for +chat-members-list.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new +chat-members-list shortcut is implemented to list chat members with pagination support, returning members in separate users and bots buckets. The shortcut supports member-type filtering, page-size configuration, automatic pagination via --page-all, page limits, and explicit cursor positioning. Results include server-side truncation signals with stderr warnings. Comprehensive unit and integration tests validate pagination merging, helper functions, and pagination scenarios. Skill documentation is updated to reflect the new shortcut and remove superseded API endpoints.

Changes

IM chat members list shortcut

Layer / File(s)	Summary
Shortcut command definition with flags and contract shortcuts/im/im_chat_members_list.go	ImChatMembersList shortcut declares command metadata and all flags (--chat-id, --member-types, --member-id-type, --page-size, --page-token, --page-all, --page-limit), validates inputs, builds a dry-run API description respecting auto-pagination, and implements execution entry point. chatMembersResult struct aggregates per-bucket member lists (users, bots), truncation signals, optional totals, and pagination state.
Pagination loop and page merging logic shortcuts/im/im_chat_members_list.go	fetchChatMembers pagination loop repeatedly calls the members list endpoint, merges pages via mergeChatMemberPages (concatenating users/bots while preserving final-page truncations and pagination metadata), and enforces --page-limit cutoff. Paging helpers effectiveChatMembersPageSize and chatMembersShouldAutoPaginate resolve page sizing and auto-pagination behavior. buildChatMembersParams normalizes member-type filters; normalizeMemberTypes validates and deduplicates input.
Output rendering and display formatting shortcuts/im/im_chat_members_list.go	renderChatMembersPretty prints chat id, enumerated members per bucket, and human-readable truncation/pagination warnings (with resume cursor when available). Utilities writeChatMembersTruncationWarning, valueOrAll, and valueOrDash format stderr warnings and field values.
Shortcut discovery and test registration shortcuts/im/shortcuts.go, shortcuts/im/helpers_test.go	ImChatMembersList is registered in Shortcuts() function return list. TestShortcuts is updated to expect +chat-members-list in shortcut discovery output.
Unit tests for pagination and validation helpers shortcuts/im/im_chat_members_list_test.go	mergeChatMemberPages tests validate user/bot concatenation, truncation sourcing from final page, and pagination signal derivation. normalizeMemberTypes tests verify input validation and normalization. effectiveChatMembersPageSize tests check page-size resolution for --page-all and default modes. Test helpers cmlPage and us provide mock payload construction.
End-to-end pagination tests with HTTP mocking shortcuts/im/im_chat_members_list_test.go	TestFetchChatMembers_PageAllMergesBucketsAndTruncations verifies multi-page draining with bucket merging and truncation preservation. TestFetchChatMembers_PageLimitStops verifies loop termination at page limit with has_more=true and stderr notice. newChatMembersTestRuntime helper wires shortcut flags and HTTP mocking for pagination scenarios.
Skill definition and reference documentation skills/lark-im/SKILL.md, skills/lark-im/references/lark-im-chat-members-list.md	SKILL.md adds +chat-members-list to Shortcuts list, removes deprecated chat.members.bots and chat.members.get API resources, and updates permissions table with +chat-members-list → im:chat.members:read. Comprehensive reference doc covers CLI usage, parameters, output schema, truncation behavior with warnings, pagination rules, and error troubleshooting.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• larksuite/cli#616: Both PRs modify member listing in skills/lark-im/SKILL.md; #616 adds chat.members.bots, while this PR implements a replacement +chat-members-list shortcut and removes the deprecated endpoints.

Suggested labels

feature

Suggested reviewers

• YangJunzhou-01
• liangshuo-1

Poem

🐰 A shortcut hops through lists so long,
With users, bots—they all belong,
Pagination dances, pages merge with care,
Members listed, truncations laid bare! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(im): add +chat-members-list shortcut for member listing' accurately reflects the main change: adding a new shortcut implementation for listing chat members with users and bots in separate buckets.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description covers the summary, key changes, and test plan clearly, with only the optional Changes and Related Issues sections missing.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.75%. Comparing base (03ea6e7) to head (ef080c8).
⚠️ Report is 29 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1398      +/-   ##
==========================================
+ Coverage   71.58%   72.75%   +1.17%     
==========================================
  Files         689      730      +41     
  Lines       65521    69034    +3513     
==========================================
+ Hits        46901    50228    +3327     
- Misses      14972    15034      +62     
- Partials     3648     3772     +124     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@ca1b03f66559b96c5247804927929d90420a23b3

🧩 Skill update

npx skills add shifengjuan-dev/lark-cli#feat/im-chat-members -y -g

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/im/im_chat_members_list_test.go`:
- Around line 94-121: The TestNormalizeMemberTypes function uses only basic
error existence checks via wantErr but lacks typed error assertions as required
by coding guidelines. For the error cases in this test (when wantErr is true),
replace the simple nil check with proper typed error validation: use errors.As
to assert the returned error is of type *errs.ValidationError and verify its
Param field contains the appropriate invalid input, use errs.ProblemOf to assert
the error has correct category and subtype metadata, and verify any cause
preservation where applicable to ensure full error contract compliance.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7f7acaac-1869-41ba-b045-3130e5153a01

📥 Commits

Reviewing files that changed from the base of the PR and between ef080c8 and 60cd5b2.

📒 Files selected for processing (6)

• shortcuts/im/helpers_test.go
• shortcuts/im/im_chat_members_list.go
• shortcuts/im/im_chat_members_list_test.go
• shortcuts/im/shortcuts.go
• skills/lark-im/SKILL.md
• skills/lark-im/references/lark-im-chat-members-list.md

✅ Files skipped from review due to trivial changes (2)

• shortcuts/im/shortcuts.go
• skills/lark-im/references/lark-im-chat-members-list.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/lark-im/SKILL.md