Add formatWarning output helper and adopt across codebase

Replace ad-hoc chalk.yellow(...) warning patterns with a consistent
formatWarning() helper from src/utils/output.ts. Adopted in base
commands, connections test, interactive mode, and command-not-found hook.

Author: umair-ably

.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/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`);

src/commands/interactive.ts

@@ -13,6 +13,7 @@ import {
   INTERACTIVE_UNSUITABLE_COMMANDS,
 } from "../base-command.js";
 import { TerminalDiagnostics } from "../utils/terminal-diagnostics.js";
+import { formatWarning } from "../utils/output.js";
 import "../utils/sigint-exit.js";
 import isWebCliMode from "../utils/web-mode.js";
 
@@ -697,9 +698,7 @@ export default class Interactive extends Command {
     // Warn about unclosed quotes
     if (inDoubleQuote || inSingleQuote) {
       const quoteType = inDoubleQuote ? "double" : "single";
-      console.error(
-        chalk.yellow(`Warning: Unclosed ${quoteType} quote in command`),
-      );
+      console.error(formatWarning(`Unclosed ${quoteType} quote in command`));
     }
 
     return args;

src/hooks/command_not_found/did-you-mean.ts

@@ -3,6 +3,7 @@ import chalk from "chalk";
 import inquirer from "inquirer";
 import pkg from "fast-levenshtein";
 import { runInquirerWithReadlineRestore } from "../../utils/readline-helper.js";
+import { formatWarning } from "../../utils/output.js";
 import * as readline from "node:readline";
 const { get: levenshteinDistance } = pkg;
 
@@ -94,7 +95,7 @@ const hook: Hook<"command_not_found"> = async function (opts) {
     // Warn about command not found and suggest alternative with colored command names
     const warningMessage = `${chalk.cyan(displayOriginal.replaceAll(":", " "))} is not an ably command.`;
     if (isInteractiveMode) {
-      console.log(chalk.yellow(`Warning: ${warningMessage}`));
+      console.log(formatWarning(warningMessage));
     } else {
       this.warn(warningMessage);
     }

src/hooks/command_not_found/prompt-utils.ts

@@ -55,18 +55,6 @@ export function formatPromptMessage(
 // This file now only contains utility functions if needed,
 // or can be removed if formatPromptMessage is moved/inlined.
 
-// Example of how you might use chalk for other styling if needed:
-// export function formatError(text: string): string {
-//   return chalk.red(text);
-// }
-
-// export function formatWarning(text: string): string {
-//   return chalk.yellow(text);
-// }
-
-// Example utility function using chalk (can be adapted or removed)
 export function formatSuggestion(suggestion: string): string {
   return chalk.blueBright(suggestion);
 }
-
-// You can add other prompt-related utility functions here if needed.

src/utils/output.ts

@@ -8,6 +8,10 @@ export function formatSuccess(message: string): string {
   return `${chalk.green("✓")} ${message}`;
 }
 
+export function formatWarning(message: string): string {
+  return `${chalk.yellow("⚠")} ${message}`;
+}
+
 export function formatListening(description: string): string {
   return chalk.dim(`${description} Press Ctrl+C to exit.`);
 }