[DX-1285] Implement get-message to retrieve latest version by serial

[sacOO7]

• Fixes https://ably.atlassian.net/browse/DX-1285
• Link to internal discussion -> https://ably-real-time.slack.com/archives/C09M25LCZLP/p1778143546471429
• Adds ably channels get-message CHANNEL_NAME MESSAGE_SERIAL — wraps the Ably REST SDK's channel.getMessage() to fetch the latest version of a single message by its serial.
• get-message is singular and explicit about operation. kabab-case follows existing conventions, e.g. ably push config set-apns
• This also display annotations summary for returned msg-serial, currently there's no way to display annotation summary for given msg-serial.
• JSON output mirrors channels history's per-element shape (raw SDK message spread, ISO-normalised timestamp, stringified action) — the right precedent for a one-shot REST query. Human output reuses the shared formatMessagesOutput formatter, so the same record renders identically across get-message, history, and subscribe.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	May 7, 2026 5:22pm

[Copilot]

Pull request overview

Adds a new channels get-message command to the Ably CLI to retrieve the latest version of a mutable message by its serial, aligning JSON and human output formats with existing channel message commands.

Changes:

• Introduces ably channels get-message <channel> <serial> implemented via Ably REST channel.getMessage(), with optional --cipher support.
• Adds unit tests validating SDK invocation, JSON envelope/shape (including timestamp normalization), human-readable formatting, and error surfacing.
• Extends E2E mutable-message test coverage to include get-message behavior (basic retrieval, post-update latest version, human output, and unknown-serial failure).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/commands/channels/get-message.ts	Implements the new channels get-message command, including JSON and human-readable output paths.
test/unit/commands/channels/get-message.test.ts	Adds unit coverage for argument/flag handling, output shape/format, and error propagation.
test/helpers/mock-ably-rest.ts	Extends the REST channel mock with a getMessage method and representative message payload.
test/e2e/channels/channel-message-ops-e2e.test.ts	Adds E2E coverage for message retrieval and latest-version semantics after updates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

[claude-code-ably-assistant]

Walkthrough

Adds ably channels get-message <channel> <serial> — a one-shot REST command that wraps channel.getMessage() to fetch the latest version of a mutable message by its serial. The PR also tightens the annotation summary indentation in formatMessagesOutput and sharpens the description of channels annotations get to clarify it returns the raw event stream, not the rolled-up summary.

Changes

Area	Files	Summary
Commands	src/commands/channels/get-message.ts	New command: fetches latest message version via REST SDK getMessage(); supports --cipher, --json, --pretty-json; normalises timestamp to ISO 8601 and stringifies action in JSON output
Commands	src/commands/channels/annotations/get.ts	Description updated to clarify this returns paginated annotation events, not the rolled-up summary
Utils	src/utils/output.ts	Fixed formatMessagesOutput: annotations summary now renders with a Summary sub-label and corrected indentation (2→4 spaces for annotation type keys, 4→6 for values)
Tests (unit)	test/unit/commands/channels/get-message.test.ts	288-line unit suite covering JSON envelope shape, timestamp normalisation, epoch-zero preservation, action stringification, version/annotations passthrough, human-readable field rendering, and error handling
Tests (e2e)	test/e2e/channels/channel-message-ops-e2e.test.ts	4 new E2E cases: basic retrieve, retrieve-after-update (with retry loop for eventual consistency), human-readable output fields, and non-zero exit on unknown serial
Tests (helpers)	test/helpers/mock-ably-rest.ts	Adds getMessage mock to MockRestChannel with a realistic default payload including version and annotations.summary

Review Notes

• Behavioral change in shared formatter: The indentation fix in formatMessagesOutput (output.ts:202–218) affects all commands that render annotations — channels history, channels subscribe, and the new get-message. Reviewers should verify the updated visual hierarchy looks correct and that no snapshot/output tests rely on the old spacing.
• message.timestamp == null guard: The timestamp normalisation uses == null (loose equality) to catch both null and undefined while preserving a legitimate 0 epoch timestamp — worth a second look to confirm this is intentional and the test covers it (it does: "epoch-zero" test case).
• E2E retry loop: The update-then-get test retries up to 10 times with 1 s delays for eventual consistency. This is sound but adds up to 10 s of potential wait time per run — acceptable given the timeout: 60000 guard.
• No new dependencies introduced.
• annotations get description change: This is a pure documentation fix but could surprise users who expected summary output from that command — the change makes the distinction explicit.