Updated MUTABLE_MESSAGES_HINT message, added optional hint param to fail

method, accordingly recording error for the same

Author: sacOO7

src/base-command.ts

@@ -1740,6 +1740,7 @@ export abstract class AblyBaseCommand extends InteractiveBaseCommand {
     flags: BaseFlags,
     component: string,
     context?: Record<string, unknown>,
+    hint?: string,
   ): never {
     // If error was already handled by a prior fail() call, re-throw it.
     // This prevents double error output when fail() is called inside a try
@@ -1763,12 +1764,18 @@ export abstract class AblyBaseCommand extends InteractiveBaseCommand {
       },
     );
 
-    const friendlyHint = getFriendlyAblyErrorHint(
-      cmdError.code ??
-        (typeof cmdError.context.errorCode === "number"
-          ? cmdError.context.errorCode
-          : undefined),
-    );
+    // A command-specific hint passed by the caller takes precedence over the
+    // global registry. Use this when an Ably error code is too generic to
+    // attach a universally-applicable hint (e.g. 40400 means different things
+    // in `channels get-message` vs `apps`/`keys` lookups).
+    const friendlyHint =
+      hint ??
+      getFriendlyAblyErrorHint(
+        cmdError.code ??
+          (typeof cmdError.context.errorCode === "number"
+            ? cmdError.context.errorCode
+            : undefined),
+      );
 
     if (this.shouldOutputJson(flags)) {
       const jsonData = cmdError.toJsonData(friendlyHint);

src/commands/channels/get-message.ts

@@ -12,7 +12,7 @@ import {
 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.";
+  "Ensure the channel has a `mutableMessages` rule enabled (run `ably apps rules list`) and that the message serial is correct.";
 
 export default class ChannelsGetMessage extends AblyBaseCommand {
   static override args = {
@@ -130,18 +130,14 @@ export default class ChannelsGetMessage extends AblyBaseCommand {
       }
     } catch (error) {
       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,
-      });
+      const hint = cmdError.code === 40400 ? MUTABLE_MESSAGES_HINT : undefined;
+      this.fail(
+        error,
+        flags,
+        "channelGetMessage",
+        { channel: channelName, serial },
+        hint,
+      );
     }
   }
 }

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

@@ -285,7 +285,7 @@ describe("channels:get-message command", () => {
       expect(error?.message).toContain("Message not found");
     });
 
-    it("enriches 40400 errors with the mutableMessages hint", async () => {
+    it("appends the mutableMessages hint to human output for 40400 errors", async () => {
       const mock = getMockAblyRest();
       const channel = mock.channels._getChannel("test-channel");
       const notFound = Object.assign(new Error("Message not found"), {
@@ -305,7 +305,7 @@ describe("channels:get-message command", () => {
       expect(error?.message).toContain("ably apps rules list");
     });
 
-    it("does NOT enrich non-40400 errors with the mutableMessages hint", async () => {
+    it("does NOT append the mutableMessages hint for non-40400 errors", async () => {
       const mock = getMockAblyRest();
       const channel = mock.channels._getChannel("test-channel");
       const otherErr = Object.assign(new Error("Some other error"), {
@@ -324,7 +324,7 @@ describe("channels:get-message command", () => {
       expect(error?.message).not.toContain("mutableMessages");
     });
 
-    it("includes the mutableMessages hint in JSON error envelope for 40400", async () => {
+    it("exposes the mutableMessages hint as `error.hint` in the JSON envelope and leaves `error.message` unchanged", async () => {
       const mock = getMockAblyRest();
       const channel = mock.channels._getChannel("test-channel");
       const notFound = Object.assign(new Error("Message not found"), {
@@ -340,11 +340,16 @@ describe("channels:get-message command", () => {
 
       const records = parseNdjsonLines(stdout);
       const errorRecord = records.find((r) => r.type === "error") as
-        | { error: { message: string; code: number } }
+        | { error: { message: string; code: number; hint?: string } }
         | undefined;
       expect(errorRecord).toBeDefined();
-      expect(errorRecord!.error.message).toContain("mutableMessages");
       expect(errorRecord!.error.code).toBe(40400);
+      // hint as its own structured field, not baked into message
+      expect(errorRecord!.error.hint).toContain("mutableMessages");
+      expect(errorRecord!.error.hint).toContain("ably apps rules list");
+      // message stays as the upstream error text only
+      expect(errorRecord!.error.message).toBe("Message not found");
+      expect(errorRecord!.error.message).not.toContain("mutableMessages");
     });
   });
 });