Addressed review comments related to hint message on message serial failure

Author: sacOO7

src/commands/channels/annotations/get.ts

@@ -27,7 +27,7 @@ export default class ChannelsAnnotationsGet extends AblyBaseCommand {
   };
 
   static override description =
-    "List individual annotation events for a channel message (paginated event stream, not the rolled-up summary)";
+    "List individual annotation events published for a given channel message";
 
   static override examples = [
     '$ ably channels annotations get my-channel "01234567890:0"',

src/commands/channels/get-message.ts

@@ -2,6 +2,7 @@ import { Args, Flags } from "@oclif/core";
 import * as Ably from "ably";
 
 import { AblyBaseCommand } from "../../base-command.js";
+import { CommandError } from "../../errors/command-error.js";
 import { productApiFlags } from "../../flags.js";
 import {
   formatMessageTimestamp,
@@ -10,6 +11,9 @@ import {
 } from "../../utils/output.js";
 import type { MessageDisplayFields } from "../../utils/output.js";
 
+const MUTABLE_MESSAGES_HINT =
+  "The channel may not have mutableMessages enabled — without this rule, individual messages cannot be retrieved by serial. Please check the same using 'ably apps rules list'. If the 'Mutable Messages' rule is enabled, then make sure to enter correct message serial.";
+
 export default class ChannelsGetMessage extends AblyBaseCommand {
   static override args = {
     channelName: Args.string({
@@ -23,7 +27,7 @@ export default class ChannelsGetMessage extends AblyBaseCommand {
   };
 
   static override description =
-    "Get the latest version of a message on an Ably channel";
+    "Get the latest version of a message on an Ably channel. Requires `mutableMessages` enabled on the channel rule.";
 
   static override examples = [
     '$ ably channels get-message my-channel "01234567890:0"',
@@ -125,7 +129,16 @@ export default class ChannelsGetMessage extends AblyBaseCommand {
         this.log(formatMessagesOutput([display]));
       }
     } catch (error) {
-      this.fail(error, flags, "channelGetMessage", {
+      const cmdError = CommandError.from(error);
+      const enriched =
+        cmdError.code === 40400
+          ? new CommandError(`${cmdError.message}\n${MUTABLE_MESSAGES_HINT}`, {
+              code: cmdError.code,
+              statusCode: cmdError.statusCode,
+              context: cmdError.context,
+            })
+          : error;
+      this.fail(enriched, flags, "channelGetMessage", {
         channel: channelName,
         serial,
       });

test/unit/commands/channels/get-message.test.ts

@@ -284,5 +284,67 @@ describe("channels:get-message command", () => {
       expect(error).toBeDefined();
       expect(error?.message).toContain("Message not found");
     });
+
+    it("enriches 40400 errors with the mutableMessages hint", async () => {
+      const mock = getMockAblyRest();
+      const channel = mock.channels._getChannel("test-channel");
+      const notFound = Object.assign(new Error("Message not found"), {
+        code: 40400,
+        statusCode: 404,
+      });
+      channel.getMessage.mockRejectedValue(notFound);
+
+      const { error } = await runCommand(
+        [COMMAND, "test-channel", "serial-001"],
+        import.meta.url,
+      );
+
+      expect(error).toBeDefined();
+      expect(error?.message).toContain("Message not found");
+      expect(error?.message).toContain("mutableMessages");
+      expect(error?.message).toContain("ably apps rules list");
+    });
+
+    it("does NOT enrich non-40400 errors with the mutableMessages hint", async () => {
+      const mock = getMockAblyRest();
+      const channel = mock.channels._getChannel("test-channel");
+      const otherErr = Object.assign(new Error("Some other error"), {
+        code: 50000,
+        statusCode: 500,
+      });
+      channel.getMessage.mockRejectedValue(otherErr);
+
+      const { error } = await runCommand(
+        [COMMAND, "test-channel", "serial-001"],
+        import.meta.url,
+      );
+
+      expect(error).toBeDefined();
+      expect(error?.message).toContain("Some other error");
+      expect(error?.message).not.toContain("mutableMessages");
+    });
+
+    it("includes the mutableMessages hint in JSON error envelope for 40400", async () => {
+      const mock = getMockAblyRest();
+      const channel = mock.channels._getChannel("test-channel");
+      const notFound = Object.assign(new Error("Message not found"), {
+        code: 40400,
+        statusCode: 404,
+      });
+      channel.getMessage.mockRejectedValue(notFound);
+
+      const { stdout } = await runCommand(
+        [COMMAND, "test-channel", "serial-001", "--json"],
+        import.meta.url,
+      );
+
+      const records = parseNdjsonLines(stdout);
+      const errorRecord = records.find((r) => r.type === "error") as
+        | { error: { message: string; code: number } }
+        | undefined;
+      expect(errorRecord).toBeDefined();
+      expect(errorRecord!.error.message).toContain("mutableMessages");
+      expect(errorRecord!.error.code).toBe(40400);
+    });
   });
 });