Merge pull request #159 from ably/feature/channel-rule-mutable-messages

[DX-935] Add mutable-messages channel rule

Author: sacOO7

.claude/skills/ably-new-command/SKILL.md

@@ -189,6 +189,7 @@ if (this.shouldOutputJson(flags)) {
 |--------|-------|---------|
 | `formatProgress(msg)` | Action in progress — appends `...` automatically | `formatProgress("Attaching to channel")` |
 | `formatSuccess(msg)` | Green checkmark — always end with `.` (period, not `!`) | `formatSuccess("Subscribed to channel " + formatResource(name) + ".")` |
+| `formatWarning(msg)` | Yellow `⚠` — for non-fatal warnings. Don't prefix with "Warning:" | `formatWarning("Persistence is automatically enabled.")` |
 | `formatListening(msg)` | Dim text — auto-appends "Press Ctrl+C to exit." | `formatListening("Listening for messages.")` |
 | `formatResource(name)` | Cyan — for resource names, never use quotes | `formatResource(channelName)` |
 | `formatTimestamp(ts)` | Dim `[timestamp]` — for event streams | `formatTimestamp(isoString)` |
@@ -370,7 +371,7 @@ pnpm test:unit      # Run tests
 - [ ] Correct flag set (`productApiFlags` vs `ControlBaseCommand.globalFlags`)
 - [ ] `clientIdFlag` only if command needs client identity
 - [ ] All human output wrapped in `if (!this.shouldOutputJson(flags))`
-- [ ] Output helpers used correctly (`formatProgress`, `formatSuccess`, `formatListening`, `formatResource`, `formatTimestamp`, `formatClientId`, `formatEventType`, `formatLabel`, `formatHeading`, `formatIndex`)
+- [ ] Output helpers used correctly (`formatProgress`, `formatSuccess`, `formatWarning`, `formatListening`, `formatResource`, `formatTimestamp`, `formatClientId`, `formatEventType`, `formatLabel`, `formatHeading`, `formatIndex`)
 - [ ] `success()` messages end with `.` (period)
 - [ ] Resource names use `resource(name)`, never quoted
 - [ ] JSON output uses `logJsonResult()` (one-shot) or `logJsonEvent()` (streaming), not direct `formatJsonRecord()`

AGENTS.md

@@ -186,6 +186,7 @@ All output helpers use the `format` prefix and are exported from `src/utils/outp
 
 - **Progress**: `formatProgress("Attaching to channel: " + formatResource(name))` — no color on action text, appends `...` automatically. Never manually write `"Doing something..."` — always use `formatProgress("Doing something")`.
 - **Success**: `formatSuccess("Message published to channel " + formatResource(name) + ".")` — green checkmark, **must** end with `.` (not `!`). Never use `chalk.green(...)` directly — always use `formatSuccess()`.
+- **Warnings**: `formatWarning("Message text here.")` — yellow `⚠` symbol. Never use `chalk.yellow("Warning: ...")` directly — always use `formatWarning()`. Don't include "Warning:" prefix in the message — the symbol conveys it.
 - **Listening**: `formatListening("Listening for messages.")` — dim, includes "Press Ctrl+C to exit." Don't combine listening text inside a `formatSuccess()` call — use a separate `formatListening()` call.
 - **Resource names**: Always `formatResource(name)` (cyan), never quoted — including in `logCliEvent` messages.
 - **Timestamps**: `formatTimestamp(ts)` — dim `[timestamp]` for event streams. `formatMessageTimestamp(message.timestamp)` — converts Ably message timestamp (number|undefined) to ISO string.
@@ -229,7 +230,6 @@ this.error()         ← oclif exit (ONLY inside fail, nowhere else)
 - **`runControlCommand<T>`** returns `Promise<T>` (not nullable) — calls `this.fail()` internally on error.
 
 ### Additional output patterns (direct chalk, not helpers)
-- **Warnings**: `chalk.yellow("Warning: ...")` — for non-fatal warnings
 - **No app error**: `'No app specified. Use --app flag or select an app with "ably apps switch"'`
 
 ### Help output theme

src/base-command.ts

@@ -13,7 +13,7 @@ import { CommandError } from "./errors/command-error.js";
 import { coreGlobalFlags } from "./flags.js";
 import { InteractiveHelper } from "./services/interactive-helper.js";
 import { BaseFlags, CommandConfig } from "./types/cli.js";
-import { buildJsonRecord } from "./utils/output.js";
+import { buildJsonRecord, formatWarning } from "./utils/output.js";
 import { getCliVersion } from "./utils/version.js";
 import Spaces from "@ably/spaces";
 import { ChatClient } from "@ably/chat";
@@ -1265,7 +1265,7 @@ export abstract class AblyBaseCommand extends InteractiveBaseCommand {
         // Log timeout only if not in JSON mode
         if (!this.shouldOutputJson({})) {
           // TODO: Pass actual flags here
-          this.log(chalk.yellow("Cleanup operation timed out."));
+          this.log(formatWarning("Cleanup operation timed out."));
         }
         reject(new Error("Cleanup timed out")); // Reject promise on timeout
       }, effectiveTimeout);
@@ -1352,7 +1352,7 @@ export abstract class AblyBaseCommand extends InteractiveBaseCommand {
             break;
           }
           case "disconnected": {
-            this.log(chalk.yellow("! Disconnected from Ably"));
+            this.log(formatWarning("Disconnected from Ably"));
             break;
           }
           case "failed": {
@@ -1364,7 +1364,7 @@ export abstract class AblyBaseCommand extends InteractiveBaseCommand {
             break;
           }
           case "suspended": {
-            this.log(chalk.yellow("! Connection suspended"));
+            this.log(formatWarning("Connection suspended"));
             break;
           }
           case "connecting": {

src/base-topic-command.ts

@@ -3,6 +3,7 @@ import inquirer from "inquirer";
 import pkg from "fast-levenshtein";
 import { InteractiveBaseCommand } from "./interactive-base-command.js";
 import { runInquirerWithReadlineRestore } from "./utils/readline-helper.js";
+import { formatWarning } from "./utils/output.js";
 import * as readline from "node:readline";
 import {
   WEB_CLI_RESTRICTED_COMMANDS,
@@ -104,7 +105,7 @@ export abstract class BaseTopicCommand extends InteractiveBaseCommand {
           // In interactive mode, we need to ensure the message is visible
           // Write directly to stderr to avoid readline interference
           if (isInteractiveMode) {
-            process.stderr.write(chalk.yellow(`Warning: ${warningMessage}\n`));
+            process.stderr.write(`${formatWarning(warningMessage)}\n`);
           } else {
             this.warn(warningMessage);
           }

src/chat-base-command.ts

@@ -5,7 +5,11 @@ import { productApiFlags } from "./flags.js";
 import { BaseFlags } from "./types/cli.js";
 import chalk from "chalk";
 
-import { formatSuccess, formatListening } from "./utils/output.js";
+import {
+  formatSuccess,
+  formatListening,
+  formatWarning,
+} from "./utils/output.js";
 import isTestMode from "./utils/test-mode.js";
 
 export abstract class ChatBaseCommand extends AblyBaseCommand {
@@ -128,7 +132,7 @@ export abstract class ChatBaseCommand extends AblyBaseCommand {
         }
         case RoomStatus.Detached: {
           if (!this.shouldOutputJson(flags)) {
-            this.log(chalk.yellow("Disconnected from Ably"));
+            this.log(formatWarning("Disconnected from Ably"));
           }
           break;
         }

src/commands/apps/channel-rules/create.ts

@@ -2,13 +2,18 @@ import { Flags } from "@oclif/core";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatChannelRuleDetails } from "../../../utils/channel-rule-display.js";
-import { formatSuccess } from "../../../utils/output.js";
+import {
+  formatLabel,
+  formatSuccess,
+  formatWarning,
+} from "../../../utils/output.js";
 
 export default class ChannelRulesCreateCommand extends ControlBaseCommand {
   static description = "Create a channel rule";
 
   static examples = [
     '$ ably apps channel-rules create --name "chat" --persisted',
+    '$ ably apps channel-rules create --name "chat" --mutable-messages',
     '$ ably apps channel-rules create --name "events" --push-enabled',
     '$ ably apps channel-rules create --name "notifications" --persisted --push-enabled --app "My App"',
     '$ ably apps channel-rules create --name "chat" --persisted --json',
@@ -55,6 +60,11 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
         "Whether to expose the time serial for messages on channels matching this rule",
       required: false,
     }),
+    "mutable-messages": Flags.boolean({
+      description:
+        "Whether messages on channels matching this rule can be updated or deleted after publishing. Automatically enables message persistence.",
+      required: false,
+    }),
     name: Flags.string({
       description: "Name of the channel rule",
       required: true,
@@ -94,6 +104,22 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
 
     try {
       const controlApi = this.createControlApi(flags);
+
+      // When mutableMessages is enabled, persisted must also be enabled
+      const mutableMessages = flags["mutable-messages"];
+      let persisted = flags.persisted;
+
+      if (mutableMessages) {
+        persisted = true;
+        if (!this.shouldOutputJson(flags)) {
+          this.logToStderr(
+            formatWarning(
+              "Message persistence is automatically enabled when mutable messages is enabled.",
+            ),
+          );
+        }
+      }
+
       const namespaceData = {
         authenticated: flags.authenticated,
         batchingEnabled: flags["batching-enabled"],
@@ -103,8 +129,9 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
         conflationInterval: flags["conflation-interval"],
         conflationKey: flags["conflation-key"],
         exposeTimeSerial: flags["expose-time-serial"],
+        mutableMessages,
         persistLast: flags["persist-last"],
-        persisted: flags.persisted,
+        persisted,
         populateChannelRegistry: flags["populate-channel-registry"],
         pushEnabled: flags["push-enabled"],
         tlsOnly: flags["tls-only"],
@@ -129,6 +156,7 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
               created: new Date(createdNamespace.created).toISOString(),
               exposeTimeSerial: createdNamespace.exposeTimeSerial,
               id: createdNamespace.id,
+              mutableMessages: createdNamespace.mutableMessages,
               name: flags.name,
               persistLast: createdNamespace.persistLast,
               persisted: createdNamespace.persisted,
@@ -142,7 +170,7 @@ export default class ChannelRulesCreateCommand extends ControlBaseCommand {
         );
       } else {
         this.log(formatSuccess("Channel rule created."));
-        this.log(`ID: ${createdNamespace.id}`);
+        this.log(`${formatLabel("ID")} ${createdNamespace.id}`);
         for (const line of formatChannelRuleDetails(createdNamespace, {
           formatDate: (t) => this.formatDate(t),
         })) {

src/commands/apps/channel-rules/index.ts

@@ -9,6 +9,7 @@ export default class ChannelRulesIndexCommand extends BaseTopicCommand {
   static examples = [
     "ably apps channel-rules list",
     'ably apps channel-rules create --name "chat" --persisted',
+    "ably apps channel-rules update chat --mutable-messages",
     "ably apps channel-rules update chat --push-enabled",
     "ably apps channel-rules delete chat",
   ];

src/commands/apps/channel-rules/list.ts

@@ -16,6 +16,7 @@ interface ChannelRuleOutput {
   exposeTimeSerial: boolean;
   id: string;
   modified: string;
+  mutableMessages: boolean;
   persistLast: boolean;
   persisted: boolean;
   populateChannelRegistry: boolean;
@@ -65,6 +66,7 @@ export default class ChannelRulesListCommand extends ControlBaseCommand {
                 exposeTimeSerial: rule.exposeTimeSerial || false,
                 id: rule.id,
                 modified: new Date(rule.modified).toISOString(),
+                mutableMessages: rule.mutableMessages || false,
                 persistLast: rule.persistLast || false,
                 persisted: rule.persisted || false,
                 populateChannelRegistry: rule.populateChannelRegistry || false,

src/commands/apps/channel-rules/update.ts

@@ -2,6 +2,11 @@ import { Args, Flags } from "@oclif/core";
 
 import { ControlBaseCommand } from "../../../control-base-command.js";
 import { formatChannelRuleDetails } from "../../../utils/channel-rule-display.js";
+import {
+  formatLabel,
+  formatSuccess,
+  formatWarning,
+} from "../../../utils/output.js";
 
 export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
   static args = {
@@ -15,6 +20,7 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
 
   static examples = [
     "$ ably apps channel-rules update chat --persisted",
+    "$ ably apps channel-rules update chat --mutable-messages",
     "$ ably apps channel-rules update events --push-enabled=false",
     '$ ably apps channel-rules update notifications --persisted --push-enabled --app "My App"',
     "$ ably apps channel-rules update chat --persisted --json",
@@ -65,6 +71,12 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
         "Whether to expose the time serial for messages on channels matching this rule",
       required: false,
     }),
+    "mutable-messages": Flags.boolean({
+      allowNo: true,
+      description:
+        "Whether messages on channels matching this rule can be updated or deleted after publishing. Automatically enables message persistence.",
+      required: false,
+    }),
     "persist-last": Flags.boolean({
       allowNo: true,
       description:
@@ -120,10 +132,39 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
       const updateData: Record<string, boolean | number | string | undefined> =
         {};
 
+      // Validation for mutable-messages flag, checks with supplied/existing mutableMessages flag
+      if (
+        flags.persisted === false &&
+        (flags["mutable-messages"] === true ||
+          (flags["mutable-messages"] === undefined &&
+            namespace.mutableMessages))
+      ) {
+        this.fail(
+          "Cannot disable persistence when mutable messages is enabled. Mutable messages requires message persistence.",
+          flags,
+          "channelRuleUpdate",
+          { appId, ruleId: namespace.id },
+        );
+      }
+
       if (flags.persisted !== undefined) {
         updateData.persisted = flags.persisted;
       }
 
+      if (flags["mutable-messages"] !== undefined) {
+        updateData.mutableMessages = flags["mutable-messages"];
+        if (flags["mutable-messages"]) {
+          updateData.persisted = true;
+          if (!this.shouldOutputJson(flags)) {
+            this.logToStderr(
+              formatWarning(
+                "Message persistence is automatically enabled when mutable messages is enabled.",
+              ),
+            );
+          }
+        }
+      }
+
       if (flags["push-enabled"] !== undefined) {
         updateData.pushEnabled = flags["push-enabled"];
       }
@@ -199,6 +240,7 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
               exposeTimeSerial: updatedNamespace.exposeTimeSerial,
               id: updatedNamespace.id,
               modified: new Date(updatedNamespace.modified).toISOString(),
+              mutableMessages: updatedNamespace.mutableMessages,
               persistLast: updatedNamespace.persistLast,
               persisted: updatedNamespace.persisted,
               populateChannelRegistry: updatedNamespace.populateChannelRegistry,
@@ -210,8 +252,8 @@ export default class ChannelRulesUpdateCommand extends ControlBaseCommand {
           flags,
         );
       } else {
-        this.log("Channel rule updated successfully:");
-        this.log(`ID: ${updatedNamespace.id}`);
+        this.log(formatSuccess("Channel rule updated."));
+        this.log(`${formatLabel("ID")} ${updatedNamespace.id}`);
         for (const line of formatChannelRuleDetails(updatedNamespace, {
           formatDate: (t) => this.formatDate(t),
           showTimestamps: true,

src/commands/connections/test.ts

@@ -8,6 +8,7 @@ import {
   formatProgress,
   formatResource,
   formatSuccess,
+  formatWarning,
 } from "../../utils/output.js";
 
 export default class ConnectionsTest extends AblyBaseCommand {
@@ -172,7 +173,9 @@ export default class ConnectionsTest extends AblyBaseCommand {
             );
           } else if (partialSuccess) {
             this.log(
-              `${chalk.yellow("!")} Some connection tests succeeded, but others failed`,
+              formatWarning(
+                "Some connection tests succeeded, but others failed",
+              ),
             );
           } else {
             this.log(`${chalk.red("✗")} All connection tests failed`);