feat(cli): respect NO_COLOR environment variable per no-color.org (#12)

* feat(cli): respect NO_COLOR environment variable per no-color.org

* fix(ticker): treat empty NO_COLOR as color-enabled per no-color.org

Author: lxcario

DOCUMENTATION.md

@@ -426,12 +426,13 @@ These apply to every command:
 
 ### Environment variables
 
-| Variable                        | Purpose                                                                           |
-| ------------------------------- | --------------------------------------------------------------------------------- |
-| `TESTSPRITE_API_KEY`            | API key — overrides the credentials file                                          |
-| `TESTSPRITE_API_URL`            | API endpoint — overrides the credentials file                                     |
-| `TESTSPRITE_PROFILE`            | Active profile (below `--profile`, above `default`)                               |
-| `TESTSPRITE_REQUEST_TIMEOUT_MS` | Per-request timeout in **milliseconds** (default `120000`, range `1000`–`600000`) |
+| Variable                        | Purpose                                                                                 |
+| ------------------------------- | --------------------------------------------------------------------------------------- |
+| `TESTSPRITE_API_KEY`            | API key — overrides the credentials file                                                |
+| `TESTSPRITE_API_URL`            | API endpoint — overrides the credentials file                                           |
+| `TESTSPRITE_PROFILE`            | Active profile (below `--profile`, above `default`)                                     |
+| `TESTSPRITE_REQUEST_TIMEOUT_MS` | Per-request timeout in **milliseconds** (default `120000`, range `1000`–`600000`)       |
+| `NO_COLOR`                      | Suppress ANSI escape sequences in ticker output ([no-color.org](https://no-color.org/)) |
 
 ### Scopes
 

src/lib/ticker.spec.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, expect, it, vi } from 'vitest';
-import { createTicker } from './ticker.js';
+import { createTicker, isNoColor } from './ticker.js';
 
 describe('createTicker — non-TTY (CI mode)', () => {
   it('update is a no-op (no writes)', () => {
@@ -222,3 +222,66 @@ describe('createTicker — spy on process.stderr', () => {
     }
   });
 });
+
+describe('createTicker — NO_COLOR support', () => {
+  it('suppresses ANSI escape sequences when noColor=true on TTY', () => {
+    const lines: string[] = [];
+    const raw: string[] = [];
+    const ticker = createTicker(
+      line => lines.push(line),
+      true, // isTTY = true
+      text => raw.push(text),
+      true, // noColor = true
+    );
+    ticker.update('progress');
+    // Should use stderrWrite (line-oriented) instead of rawWrite with ANSI
+    expect(raw).toHaveLength(0);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]!).not.toContain('\x1b[2K');
+    expect(lines[0]!).not.toContain('\r');
+    expect(lines[0]!).toContain('progress');
+  });
+
+  it('finalize emits plain text without ANSI when noColor=true on TTY', () => {
+    const lines: string[] = [];
+    const raw: string[] = [];
+    const ticker = createTicker(
+      line => lines.push(line),
+      true,
+      text => raw.push(text),
+      true, // noColor = true
+    );
+    ticker.finalize('done');
+    expect(raw).toHaveLength(0);
+    expect(lines).toHaveLength(1);
+    expect(lines[0]!).not.toContain('\x1b[2K');
+    expect(lines[0]!).toContain('done');
+  });
+
+  it('normal ANSI output when noColor=false on TTY', () => {
+    const raw: string[] = [];
+    const ticker = createTicker(
+      () => {},
+      true,
+      text => raw.push(text),
+      false, // noColor = false
+    );
+    ticker.update('progress');
+    expect(raw).toHaveLength(1);
+    expect(raw[0]!).toContain('\x1b[2K\r');
+  });
+});
+
+describe('isNoColor', () => {
+  it('returns true when NO_COLOR is set to a non-empty value', () => {
+    expect(isNoColor({ NO_COLOR: '1' })).toBe(true);
+    expect(isNoColor({ NO_COLOR: 'true' })).toBe(true);
+  });
+
+  it('returns false when NO_COLOR is absent or empty', () => {
+    expect(isNoColor({})).toBe(false);
+    expect(isNoColor({ OTHER_VAR: '1' })).toBe(false);
+    // Per https://no-color.org/, an empty NO_COLOR does NOT disable color.
+    expect(isNoColor({ NO_COLOR: '' })).toBe(false);
+  });
+});

src/lib/ticker.ts

@@ -8,6 +8,9 @@
  *  - Uses `\r` + ANSI clear-line to overwrite in place on TTY
  *  - On terminal, emits one final line + newline then prints the result
  *  - `--output json` disables the ticker (caller doesn't create one)
+ *  - Respects the NO_COLOR env var (https://no-color.org/): when set,
+ *    ANSI escape sequences are suppressed and updates are emitted as
+ *    plain lines instead of in-place overwrites.
  *
  * Overhead: <2ms per update (no syscalls beyond a single write).
  *
@@ -25,6 +28,15 @@ export interface Ticker {
   finalize(line?: string): void;
 }
 
+/**
+ * Returns true when NO_COLOR is present in the environment and is not
+ * an empty string, per https://no-color.org/.
+ */
+export function isNoColor(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env.NO_COLOR;
+  return typeof value === 'string' && value.length > 0;
+}
+
 /**
  * Create a ticker bound to the given stderr writer. Respects
  * `isTTY` to silently no-op in CI environments.
@@ -35,18 +47,22 @@ export interface Ticker {
  * @param stderrRaw - optional raw writer (no \n appended); used for
  *   the carriage-return + clear-line trick. Defaults to
  *   `process.stderr.write.bind(process.stderr)`.
+ * @param noColor - whether to suppress ANSI escape sequences.
+ *   Defaults to checking `NO_COLOR` env var per https://no-color.org/.
  */
 export function createTicker(
   stderrWrite: (line: string) => void,
   isTTY?: boolean,
   stderrRaw?: (text: string) => void,
+  noColor?: boolean,
 ): Ticker {
   const tty = isTTY ?? (typeof process !== 'undefined' ? process.stderr.isTTY === true : false);
   const rawWrite =
     stderrRaw ??
     (typeof process !== 'undefined'
       ? (text: string) => process.stderr.write(text)
       : (_text: string) => undefined);
+  const suppressAnsi = noColor ?? isNoColor();
 
   let lastLength = 0;
 
@@ -58,6 +74,25 @@ export function createTicker(
     };
   }
 
+  if (suppressAnsi) {
+    // TTY but NO_COLOR: emit plain-text lines without ANSI escape sequences.
+    return {
+      update(line: string): void {
+        const stamped = `${new Date().toISOString()} ${line}`;
+        stderrWrite(stamped);
+        lastLength = stamped.length;
+      },
+      finalize(line?: string): void {
+        if (line !== undefined) {
+          const stamped = `${new Date().toISOString()} ${line}`;
+          stderrWrite(stamped);
+          lastLength = stamped.length;
+        }
+        void stderrWrite;
+      },
+    };
+  }
+
   return {
     update(line: string): void {
       // ANSI ESC[2K clears the entire line; \r moves to column 0.