[DX-935] Add mutable-messages channel rule

[sacOO7]

• Fixes https://ably.atlassian.net/browse/DX-935
• Needs to be enabled for for message update, append and deletes
• Also needed for message annotations
• Related openspec update PR => [DX-144] Update control API spec for missing fields docs#3257

Also adds formatWarning helper... noticed this could do with standardising around as part of this PR. Kept in an isolated commit

Summary by CodeRabbit

Release Notes

• New Features

  • Added --mutable-messages flag to enable mutable messaging for channel rules during creation and updates.
  • Mutable messages field now displays in channel rule details and JSON output.
  • Automatic persistence enforcement when mutable messages is enabled, with user notification.

• Improvements

  • Validation prevents disabling persistence when mutable messages is enabled.

[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 11, 2026 2:15pm

[coderabbitai]

Walkthrough

This pull request introduces a new mutable-messages boolean flag to channel rules, enabling mutability control for persisted messages. The flag is added to create and update commands, propagated through the API service layer, displayed in rule details, and accompanied by comprehensive test coverage including validation that mutable messages require persistence.

Changes

Cohort / File(s)	Summary
Command implementations src/commands/apps/channel-rules/create.ts, src/commands/apps/channel-rules/list.ts, src/commands/apps/channel-rules/update.ts	Added mutable-messages flag to create and update commands. Create command enforces persistence requirement with warning. Update command validates that mutable messages cannot be paired with disabled persistence. List command exposes mutableMessages in output. All commands include new field in JSON responses.
API service layer src/services/control-api.ts	Extended Namespace interface and create/update payload types with optional mutableMessages?: boolean property.
Display utilities src/utils/channel-rule-display.ts	Added conditional rendering of "Mutable Messages" field in formatted channel rule details output.
Test coverage test/unit/commands/apps/channel-rules/create.test.ts, test/unit/commands/apps/channel-rules/list.test.ts, test/unit/commands/apps/channel-rules/update.test.ts	Added 6 new tests covering mutable-messages flag creation, list display, update behavior, persistence enforcement, JSON serialization, and error handling for conflicting flag combinations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 A mutable message, now we can say,
Messages change in their persistent way,
Through flags and through tests, the feature bounds,
With warnings and validation all around! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely summarizes the main change: adding a mutable-messages flag to channel rules, which aligns with the core objective to enable message update operations.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/channel-rule-mutable-messages

---

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.}

[sacOO7]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

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.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/commands/apps/channel-rules/update.ts`:
- Around line 166-174: The code currently sets updateData.persisted = true and
emits the warning whenever flags["mutable-messages"] is present (including
--no-mutable-messages); change the condition so the persisted override and the
warning only run when flags["mutable-messages"] === true, i.e., explicitly
enabling mutable messages. Also reuse the same warning text/constant used in
create.ts (import or reference that constant) instead of duplicating the string,
and wrap the this.logToStderr(...) call in if (!this.shouldOutputJson(flags)) so
the warning is suppressed for --json output; keep the assignment to
updateData.mutableMessages = flags["mutable-messages"] as-is.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 32ed5959-7578-45a3-b8fd-4faaf2560a39

📥 Commits

Reviewing files that changed from the base of the PR and between 8333bed and 549ff4b.

📒 Files selected for processing (8)

• src/commands/apps/channel-rules/create.ts
• src/commands/apps/channel-rules/list.ts
• src/commands/apps/channel-rules/update.ts
• src/services/control-api.ts
• src/utils/channel-rule-display.ts
• test/unit/commands/apps/channel-rules/create.test.ts
• test/unit/commands/apps/channel-rules/list.test.ts
• test/unit/commands/apps/channel-rules/update.test.ts

[cursor]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on April 4.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[Copilot]

Pull request overview

Adds support for the Ably “mutable messages” channel rule capability across the CLI’s channel-rules commands, including create/update flags, list/detail display, and JSON output, with tests covering the new behavior.

Changes:

• Add --mutable-messages support to apps:channel-rules:create and apps:channel-rules:update, including auto-enabling persistence when enabled.
• Include mutableMessages in channel rule list/details output and JSON output.
• Extend Control API namespace typings and add unit tests for create/update/list scenarios.

Reviewed changes

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

Show a summary per file

File	Description
test/unit/commands/apps/channel-rules/update.test.ts	Adds tests for updating mutable messages, persistence enforcement, and JSON output.
test/unit/commands/apps/channel-rules/list.test.ts	Adds tests ensuring mutableMessages shows in human output and JSON output.
test/unit/commands/apps/channel-rules/create.test.ts	Adds tests for create with mutable messages, persistence auto-enable, and JSON behavior.
src/utils/channel-rule-display.ts	Adds “Mutable Messages” line to human-readable channel rule details when present.
src/services/control-api.ts	Extends Namespace and namespace create/update payload types with mutableMessages.
src/commands/apps/channel-rules/update.ts	Introduces --mutable-messages flag, validation, persistence auto-enable, and JSON output field.
src/commands/apps/channel-rules/list.ts	Adds mutableMessages to JSON output mapping for list.
src/commands/apps/channel-rules/index.ts	Updates examples to mention mutable messages.
src/commands/apps/channel-rules/create.ts	Introduces --mutable-messages flag and persistence auto-enable + warning behavior.

---

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