Fixed ansi/color formatting issue with respect to generated documentation

Author: sacOO7

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

@@ -434,7 +434,7 @@ If the new command shouldn't be available in the web CLI, add it to the appropri
 After creating command and test files, always run:
 ```bash
 pnpm prepare        # Build + update manifest
-pnpm exec oclif readme  # Regenerate README.md from command metadata
+pnpm generate-doc       # Regenerate command documentation
 pnpm exec eslint .  # Lint (must be 0 errors)
 pnpm test:unit      # Run tests
 ```

.gitignore

@@ -31,7 +31,7 @@ node_modules/
 # oclif files
 oclif.manifest.json
 oclif.lock
-GENERATED_README.md
+GENERATED_DOC.md
 
 # OS generated files
 **/.DS_Store

AGENTS.md

@@ -6,7 +6,7 @@
 
 ```bash
 pnpm prepare        # 1. Build + update manifest
-pnpm generate-readme  # 2. Regenerate command docs (gitignored)
+pnpm generate-doc  # 2. Regenerate docs (gitignored)
 pnpm exec eslint .  # 3. Lint (MUST be 0 errors)
 pnpm test:unit      # 4. Test (at minimum)
 pnpm test:tty       # 5. TTY tests (local only, skip in CI)

CONTRIBUTING.md

@@ -8,7 +8,7 @@ All code changes, whether features or bug fixes, **MUST** follow the mandatory w
 
 In summary, this involves:
 
-1.  **Build:** Run `pnpm prepare` to compile and update manifests, then `pnpm exec oclif readme` to regenerate the README.
+1.  **Build:** Run `pnpm prepare` to compile and update manifests, then `pnpm generate-doc` to regenerate the command documentation.
 2.  **Lint:** Run `pnpm exec eslint .` and fix all errors/warnings.
 3.  **Test:** Run relevant tests (`pnpm test:unit`, `pnpm test:integration`, `pnpm test:e2e`, `pnpm test:playwright`, or specific files) and ensure they pass. For interactive mode changes, also run `pnpm run test:tty` (requires a real terminal, not run in CI). Add new tests or update existing ones as needed.
 4.  **Document:** Update all relevant documentation (`docs/`, `AGENTS.md`, `README.md`) to reflect your changes.
@@ -53,10 +53,10 @@ This allows testing CLI changes against local server modifications before deploy
 1. Make sure all checks are passing on main
 2. Create a new release branch, in the format `release/<version>` where the version is the SemVer version of the release. In that branch:
     - Update the `package.json` version to the new version.
-    - Run `pnpm exec oclif readme` to regenerate the README with updated command documentation.
+    - Run `pnpm generate-doc` to regenerate the command documentation.
     - Update the `CHANGELOG.md` with any user-affecting changes since the last release.
-    - Review the generated README.md changes to ensure they're correct.
-    - Stage all changes: `git add package.json README.md CHANGELOG.md`
+    - Review the generated `GENERATED_DOC.md` output locally to ensure updated commands documentation is correct.
+    - Stage all changes: `git add package.json CHANGELOG.md`
     - Commit all changes with a message like `chore: prepare release <version>`.
     - Update the `package.json` for `packages/react-web-cli`.
 3. Once the release branch is approved, merge it into main.

README.md

@@ -1,8 +1,8 @@
 # Ably CLI
 
 [![npm version](https://badge.fury.io/js/@ably%2Fcli.svg)](https://badge.fury.io/js/@ably%2Fcli)
-[![Node](https://img.shields.io/node/v/@ably/cli)](https://nodejs.org)
-[![License](https://img.shields.io/npm/l/@ably/cli)](https://github.com/ably/ably-cli/blob/main/LICENSE)
+[![Node](https://img.shields.io/node/v/%40ably%2Fcli)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/%40ably%2Fcli)](https://github.com/ably/ably-cli/blob/main/LICENSE)
 
 The Ably CLI brings the full power of Ably to your terminal. You can use it to manage your Ably account and its resources, and to explore Ably's APIs and features.
 
@@ -15,7 +15,7 @@ The Ably CLI interacts with:
 
 ## Installation
 
-The Ably CLI is available as an NPM package, install using
+The Ably CLI is available as an NPM package. Install it using:
 
 ```shell
 npm install -g @ably/cli
@@ -29,9 +29,9 @@ For a list of all available commands, run:
 ably help
 ```
 
-Visit [Official Ably Documentation](https://ably.com/docs/platform/tools/cli) for CLI login, features and usage.
+Visit [the official Ably documentation](https://ably.com/docs/platform/tools/cli) for CLI login, features, and usage.
 
-# Contributing
+## Contributing
 
 Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow, testing requirements, and release process.
 

package.json

@@ -51,7 +51,7 @@
     "prepare": "[ -d .git ] && [ -d .githooks ] && git config core.hooksPath .githooks || true; pnpm run build && CI=true ABLY_INTERACTIVE=false oclif manifest",
     "postinstall": "[ \"$CI\" = \"true\" ] || (test -f ./dist/scripts/postinstall-welcome.js && node ./dist/scripts/postinstall-welcome.js || echo \"Skipping welcome script (not found)\")",
     "preversion": "pnpm run prepare",
-    "generate-readme": "[ -f GENERATED_README.md ] || printf '<!-- toc -->\\n<!-- tocstop -->\\n<!-- usage -->\\n<!-- usagestop -->\\n<!-- commands -->\\n<!-- commandsstop -->\\n' > GENERATED_README.md && oclif readme --readme-path GENERATED_README.md",
+    "generate-doc": "rm -f GENERATED_DOC.md && printf '<!-- toc -->\\n<!-- tocstop -->\\n<!-- usage -->\\n<!-- usagestop -->\\n<!-- commands -->\\n<!-- commandsstop -->\\n' > GENERATED_DOC.md && (GENERATING_DOC=true NO_COLOR=1 oclif readme --readme-path GENERATED_DOC.md)",
     "validate": "./scripts/pre-push-validation.sh",
     "pre-commit": "pnpm validate",
     "ai-init": "echo 'AI Assistant Instructions:' && cat .claude/CLAUDE.md",

src/help.ts

@@ -33,13 +33,8 @@ export default class CustomHelp extends Help {
     this.configManager = createConfigManager();
   }
 
-  // Override formatHelpOutput to apply stripAnsi when necessary
+  // Override formatHelpOutput to apply interactive-mode transformations
   formatHelpOutput(output: string): string {
-    // Check if we're generating readme (passed as an option from oclif)
-    if (this.opts.stripAnsi || process.env.GENERATING_README === "true") {
-      output = stripAnsi(output);
-    }
-
     // Strip "ably" prefix when in interactive mode
     if (this.interactiveMode) {
       output = this.stripAblyPrefix(output);
@@ -48,6 +43,11 @@ export default class CustomHelp extends Help {
     return output;
   }
 
+  // Check if ANSI codes should be stripped (oclif readme generation or while generating docs via GENERATING_DOC)
+  private shouldStripAnsi(): boolean {
+    return !!(this.opts.stripAnsi || process.env.GENERATING_DOC === "true");
+  }
+
   // Helper to strip "ably" prefix from command examples in interactive mode
   private stripAblyPrefix(text: string): string {
     if (!this.interactiveMode) return text;
@@ -193,7 +193,10 @@ export default class CustomHelp extends Help {
     } else {
       output = this.formatStandardRoot();
     }
-    return output; // Let the overridden render handle stripping
+    if (this.shouldStripAnsi()) {
+      output = stripAnsi(output);
+    }
+    return output;
   }
 
   formatStandardRoot(): string {
@@ -486,7 +489,10 @@ export default class CustomHelp extends Help {
         }
       }
     }
-    return output; // Let the overridden render handle stripping
+    if (this.shouldStripAnsi()) {
+      output = stripAnsi(output);
+    }
+    return output;
   }
 
   // Re-add the check for web CLI mode command availability