@quenty/cli-output-helpers 1.10.0 → 1.11.0

package/src/reporting/watch-renderer.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createWatchRenderer } from './watch-renderer.js';
+
+describe('createWatchRenderer', () => {
+  let writes: string[];
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    writes = [];
+    vi.spyOn(process.stdout, 'write').mockImplementation(((chunk: any) => {
+      writes.push(typeof chunk === 'string' ? chunk : chunk.toString());
+      return true;
+    }) as any);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('start renders immediately and stop clears interval with final render', () => {
+    let count = 0;
+    const renderer = createWatchRenderer(() => `frame-${count++}`, {
+      rewrite: false,
+      intervalMs: 1000,
+    });
+
+    renderer.start();
+    expect(writes).toEqual(['frame-0\n']);
+
+    renderer.stop();
+    // stop does a final render
+    expect(writes).toEqual(['frame-0\n', 'frame-1\n']);
+
+    // After stop, no more renders should happen
+    writes.length = 0;
+    vi.advanceTimersByTime(3000);
+    expect(writes).toEqual([]);
+  });
+
+  it('update forces immediate render and resets interval', () => {
+    let count = 0;
+    const renderer = createWatchRenderer(() => `frame-${count++}`, {
+      rewrite: false,
+      intervalMs: 1000,
+    });
+
+    renderer.start(); // frame-0
+    expect(writes).toEqual(['frame-0\n']);
+
+    // Advance 500ms, then force update
+    vi.advanceTimersByTime(500);
+    renderer.update(); // frame-1 (forced)
+    expect(writes).toEqual(['frame-0\n', 'frame-1\n']);
+
+    // Advance 500ms more — the old interval would have fired at 1000ms total,
+    // but update() reset it, so nothing fires yet
+    vi.advanceTimersByTime(500);
+    expect(writes).toEqual(['frame-0\n', 'frame-1\n']);
+
+    // Advance another 500ms (1000ms since update), new interval fires
+    vi.advanceTimersByTime(500);
+    expect(writes).toEqual(['frame-0\n', 'frame-1\n', 'frame-2\n']);
+
+    renderer.stop();
+  });
+
+  it('non-TTY mode only writes when content changes', () => {
+    let value = 'same';
+    const renderer = createWatchRenderer(() => value, {
+      rewrite: false,
+      intervalMs: 100,
+    });
+
+    renderer.start(); // writes "same"
+    expect(writes).toEqual(['same\n']);
+
+    // Same content on next interval — should NOT write
+    vi.advanceTimersByTime(100);
+    expect(writes).toEqual(['same\n']);
+
+    // Change content — should write
+    value = 'different';
+    vi.advanceTimersByTime(100);
+    expect(writes).toEqual(['same\n', 'different\n']);
+
+    renderer.stop();
+  });
+
+  it('stop clears the interval so no more renders happen', () => {
+    let count = 0;
+    const renderer = createWatchRenderer(() => `f-${count++}`, {
+      rewrite: false,
+      intervalMs: 100,
+    });
+
+    renderer.start(); // f-0
+    renderer.stop(); // f-1 (final)
+
+    writes.length = 0;
+    vi.advanceTimersByTime(1000);
+    expect(writes).toEqual([]);
+  });
+
+  it('TTY rewrite mode hides/shows cursor and uses escape codes', () => {
+    let count = 0;
+    const renderer = createWatchRenderer(() => `line-${count++}`, {
+      rewrite: true,
+      intervalMs: 100,
+    });
+
+    renderer.start();
+    // Should have written hide-cursor + first frame
+    expect(writes[0]).toBe('\x1b[?25l');
+    expect(writes[1]).toBe('line-0\n');
+
+    // Advance to trigger second render — should include cursor-up + clear
+    vi.advanceTimersByTime(100);
+    const cursorUpWrite = writes.find((w) => w.includes('\x1b[1A\x1b[J'));
+    expect(cursorUpWrite).toBeDefined();
+
+    renderer.stop();
+    // Should have written show-cursor
+    const lastWrite = writes[writes.length - 1];
+    expect(lastWrite).toBe('\x1b[?25h');
+  });
+});

package/src/reporting/watch-renderer.ts

@@ -0,0 +1,132 @@
+/**
+ * Live-updating renderer for watch/monitoring commands. In TTY mode,
+ * rewrites output in-place using cursor control. In non-TTY mode,
+ * appends new output only when it changes.
+ */
+
+export interface WatchRendererOptions {
+  intervalMs?: number;
+  rewrite?: boolean;
+}
+
+export interface WatchRenderer {
+  start(): void;
+  update(): void;
+  stop(): void;
+}
+
+export function createWatchRenderer(
+  render: () => string,
+  options?: WatchRendererOptions
+): WatchRenderer {
+  const intervalMs = options?.intervalMs ?? 1000;
+  const rewrite = options?.rewrite ?? (process.stdout.isTTY ? true : false);
+
+  let _intervalHandle: ReturnType<typeof setInterval> | null = null;
+  let _previousOutput: string = '';
+  let _previousLineCount: number = 0;
+
+  function _render(): void {
+    const output = render();
+
+    if (rewrite) {
+      // TTY rewrite mode: move cursor up and clear previous output
+      if (_previousLineCount > 0) {
+        process.stdout.write(`\x1b[${_previousLineCount}A\x1b[J`);
+      }
+      process.stdout.write(output + '\n');
+      _previousLineCount = output.split('\n').length;
+    } else {
+      // Non-TTY append mode: only write when content changes
+      if (output !== _previousOutput) {
+        process.stdout.write(output + '\n');
+      }
+    }
+
+    _previousOutput = output;
+  }
+
+  function _startInterval(): void {
+    _intervalHandle = setInterval(_render, intervalMs);
+  }
+
+  function _clearInterval(): void {
+    if (_intervalHandle !== null) {
+      clearInterval(_intervalHandle);
+      _intervalHandle = null;
+    }
+  }
+
+  let _cursorHidden = false;
+  let _signalsBound = false;
+
+  function _showCursor(): void {
+    if (_cursorHidden) {
+      _cursorHidden = false;
+      process.stdout.write('\x1b[?25h');
+    }
+  }
+
+  function _onSignal(signal: NodeJS.Signals): void {
+    _clearInterval();
+    _showCursor();
+    // Restore default behavior so the process actually exits
+    process.removeListener('SIGINT', _onSignal);
+    process.removeListener('SIGTERM', _onSignal);
+    process.kill(process.pid, signal);
+  }
+
+  function _bindSignals(): void {
+    if (_signalsBound) return;
+    _signalsBound = true;
+    process.once('SIGINT', _onSignal);
+    process.once('SIGTERM', _onSignal);
+  }
+
+  function _unbindSignals(): void {
+    if (!_signalsBound) return;
+    _signalsBound = false;
+    process.removeListener('SIGINT', _onSignal);
+    process.removeListener('SIGTERM', _onSignal);
+  }
+
+  return {
+    start(): void {
+      if (rewrite) {
+        process.stdout.write('\x1b[?25l'); // hide cursor
+        _cursorHidden = true;
+        _bindSignals();
+      }
+      try {
+        _render();
+      } catch (err) {
+        _showCursor();
+        _unbindSignals();
+        throw err;
+      }
+      _startInterval();
+    },
+
+    update(): void {
+      _clearInterval();
+      try {
+        _render();
+      } catch (err) {
+        _showCursor();
+        _unbindSignals();
+        throw err;
+      }
+      _startInterval();
+    },
+
+    stop(): void {
+      _clearInterval();
+      try {
+        _render();
+      } finally {
+        _showCursor();
+        _unbindSignals();
+      }
+    },
+  };
+}

package/src/reporting/watch-result-reporter.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { WatchResultReporter } from './watch-result-reporter.js';
+
+describe('WatchResultReporter', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let writeSpy: any;
+  const originalIsTTY = process.stdout.isTTY;
+
+  beforeEach(() => {
+    writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    writeSpy.mockRestore();
+    process.stdout.isTTY = originalIsTTY;
+  });
+
+  it('starts the renderer on the first onResult and updates on subsequent calls', () => {
+    process.stdout.isTTY = false;
+    const renderFn = vi.fn((r: { v: number }) => `v=${r.v}`);
+    const reporter = new WatchResultReporter<{ v: number }>({
+      render: renderFn,
+      intervalMs: 1000,
+    });
+
+    reporter.onResult({ v: 1 });
+    expect(renderFn).toHaveBeenCalledWith({ v: 1 });
+    expect(writeSpy).toHaveBeenCalled();
+
+    reporter.onResult({ v: 2 });
+    expect(renderFn).toHaveBeenCalledWith({ v: 2 });
+  });
+
+  it('stopAsync without any onResult does not start the renderer', async () => {
+    process.stdout.isTTY = false;
+    const renderFn = vi.fn(() => '');
+    const reporter = new WatchResultReporter<unknown>({ render: renderFn });
+
+    await reporter.stopAsync();
+    expect(renderFn).not.toHaveBeenCalled();
+  });
+});

package/src/reporting/watch-result-reporter.ts

@@ -0,0 +1,45 @@
+/**
+ * Live-redraw reporter for watch-mode commands. Wraps the WatchRenderer —
+ * stores the latest result and redraws via cursor manipulation.
+ *
+ * The first onResult starts the underlying renderer; subsequent calls update
+ * it. stopAsync stops the renderer and restores the cursor.
+ */
+
+import { BaseResultReporter } from './result-reporter.js';
+import { createWatchRenderer, type WatchRenderer } from './watch-renderer.js';
+
+export interface WatchResultReporterOptions<T> {
+  render: (result: T) => string;
+  intervalMs?: number;
+}
+
+export class WatchResultReporter<T = unknown> extends BaseResultReporter<T> {
+  private _renderer: WatchRenderer;
+  private _latest: T | undefined;
+  private _started = false;
+
+  constructor(options: WatchResultReporterOptions<T>) {
+    super();
+    this._renderer = createWatchRenderer(
+      () => (this._latest === undefined ? '' : options.render(this._latest)),
+      { intervalMs: options.intervalMs }
+    );
+  }
+
+  override onResult(result: T): void {
+    this._latest = result;
+    if (!this._started) {
+      this._started = true;
+      this._renderer.start();
+    } else {
+      this._renderer.update();
+    }
+  }
+
+  override async stopAsync(): Promise<void> {
+    if (this._started) {
+      this._renderer.stop();
+    }
+  }
+}