[DX-970] Feature: implement missing presence commands

[sacOO7]

• Added channels presence get-all and channels presence update
• Refactored presence enter for better status update
• Fixes https://ably.atlassian.net/browse/DX-970

Summary by CodeRabbit

• New Features

  • Added channels presence get-all command to retrieve current presence members on a channel with optional --limit flag.
  • Added channels presence update command to update presence data on a channel.
  • Added spaces occupancy get and spaces occupancy subscribe commands to monitor space occupancy metrics.

• Improvements

  • Standardized argument naming across Spaces commands (SPACE → SPACE_NAME).
  • Enhanced JSON output for long-running commands with status signals to indicate active operations.
  • Improved output formatting and messaging for consistency across all Spaces commands.

• Documentation

  • Updated README with new command references and CLI version information.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
cli-web-cli	Ready	Preview, Comment	Mar 19, 2026 6:20pm

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8a5520ec-4d31-45a3-821e-734cb46c8136

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This pull request introduces hold-state command semantics with a new logJsonStatus helper, adds channels presence get-all and update commands, introduces spaces occupancy get and subscribe commands, standardizes argument naming from SPACE to SPACE_NAME across spaces commands, simplifies spaces command logic by removing metrics from list and subscription snapshots, and updates supporting documentation and tests.

Changes

Cohort / File(s)	Summary
Documentation & Skills .claude/skills/..., README.md, docs/Project-Structure.md	Updated skill documentation to reflect hold-command semantics requiring logJsonStatus("holding", ...) after results. Updated README with new CLI version, channels presence commands (get-all, update), spaces occupancy commands, and renamed SPACE→SPACE_NAME argument labels. Updated project structure to mention occupancy capabilities.
JSON Output & Logging Infrastructure src/base-command.ts, src/utils/output.ts, AGENTS.md	Extended formatJsonRecord type to include "status", added logJsonStatus(status, message, flags) method to emit JSON status records for hold commands. Updated JSON envelope specification and documentation for status signals.
Spaces Base & Output Utilities src/spaces-base-command.ts, src/utils/spaces-output.ts	Enhanced spaces cleanup to track entry state (hasEnteredSpace, markAsEntered()), suppress unhandledRejection errors during cleanup, and unsubscribe presence handlers. Added new module with formatted output types and helpers (MemberOutput, CursorOutput, LockOutput, LocationEntry) and block formatters for consistent spaces command display.
Channels Presence Commands src/commands/channels/presence/enter.ts, src/commands/channels/presence/get-all.ts, src/commands/channels/presence/update.ts	Modified enter to use shared JSON parsing and emit logJsonStatus("holding", ...). Added new get-all command with --limit support, pagination handling, and JSON result envelope. Added new update command for presence data with manual entry, hold semantics, and cleanup via finally block.
Spaces Cursors Commands src/commands/spaces/cursors/get-all.ts, src/commands/spaces/cursors/set.ts, src/commands/spaces/cursors/subscribe.ts	Renamed space arg to space_name, removed complex connection/subscription logic, simplified to direct SDK calls, replaced local type definitions with imports from @ably/spaces, standardized output via new block formatters, added logJsonStatus("holding", ...) for set command.
Spaces Locations Commands src/commands/spaces/locations/get-all.ts, src/commands/spaces/locations/set.ts, src/commands/spaces/locations/subscribe.ts	Renamed space arg to space_name, removed getAll snapshot fetching in subscribe, changed init from enterSpace: true to enterSpace: false with explicit entry, simplified output payloads via formatters, removed interactive update subscription in set (hold-only), added logJsonStatus("holding", ...) calls.
Spaces Locks Commands src/commands/spaces/locks/acquire.ts, src/commands/spaces/locks/get-all.ts, src/commands/spaces/locks/get.ts, src/commands/spaces/locks/subscribe.ts	Renamed space arg to space_name, removed getAll snapshot fetching in subscribe, changed init from enterSpace: true to enterSpace: false, standardized output via formatLockBlock/formatLockOutput, removed custom type definitions, added logJsonStatus("holding", ...) to acquire and subscribe.
Spaces Members Commands src/commands/spaces/members/enter.ts, src/commands/spaces/members/subscribe.ts	Renamed space arg to space_name, removed presence subscription in enter command, removed initial members snapshot in subscribe, changed init from enterSpace: true to enterSpace: false, simplified output via block formatters, replaced custom formatting with consistent helpers, added logJsonStatus("holding", ...) to enter.
Spaces List Command src/commands/spaces/list.ts	Removed occupancy metrics from space items (removed SpaceMetrics, status field, metrics output logic), adjusted formatting with newlines, kept pagination logic intact.
Spaces Occupancy Commands src/commands/spaces/occupancy/index.ts, src/commands/spaces/occupancy/get.ts, src/commands/spaces/occupancy/subscribe.ts	Added new occupancy parent command, new get command for retrieving current occupancy metrics via REST (connections, publishers, subscribers, presence metrics), new subscribe command for real-time occupancy event streaming with formatted metric blocks.
Test Files test/...	Updated tests across all modified commands to reflect new behavior: removed getAll/subscription snapshot assertions, changed mock return shapes (objects vs. arrays), updated output format expectations, added NDJSON parsing for --json output, verified logJsonStatus("holding", ...) emissions, adjusted mock payloads to include richer object fields, updated arg name assertions from SPACE to SPACE_NAME.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Suggested reviewers

• jamiehenson
• denissellu

Poem

🐰 From hold to hold, a rabbit hops with glee,
New status signals dancing wild and free,
Spaces simplified, occupancy revealed,
Presence commands unlocked, control redefined.
Hold steady now—Ctrl+C when you're done! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 76.92% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title 'DX-970 Feature: implement missing presence commands' directly describes the primary objective: implementing presence commands as specified in the issue.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/implement-missing-presence-commands

📝 Coding Plan

• Generate coding plan for human review comments

---

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 and usage tips.}

[Copilot]

Pull request overview

Implements the remaining Channels Presence CLI surface area by adding “get all members” and “update presence data” commands, and aligning presence enter output/JSON structure with the newer long-running command patterns.

Changes:

• Added channels presence get-all (REST) with limit + pagination metadata and human/JSON output.
• Added channels presence update (Realtime) to enter, update data, then hold presence until exit/timeout.
• Refactored channels presence enter JSON/human output (progress + labeled fields + status record) and consolidated JSON parsing via parseJsonFlag().

Reviewed changes

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

Show a summary per file

File	Description
src/commands/channels/presence/get-all.ts	New REST command to list current presence members with limit + pagination hints and JSON output.
src/commands/channels/presence/update.ts	New Realtime command to enter + update presence data and hold until cleanup.
src/commands/channels/presence/enter.ts	Refines output and JSON envelope shape; switches --data parsing to parseJsonFlag().
test/unit/commands/channels/presence/get-all.test.ts	Unit coverage for get-all output, JSON shape, limit, pagination, and error handling.
test/unit/commands/channels/presence/update.test.ts	Unit coverage for update flow (enter+update), JSON output/status, and error cases.
test/unit/commands/channels/presence/enter.test.ts	Expanded tests for progress text, labeled fields, JSON result/status, and holding/listening messaging.
README.md	Documents the new commands in the CLI reference.

---

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