@quenty/cli-output-helpers 1.10.1 → 1.11.0

package/src/reporting/json-file-reporter.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs/promises';
 import { OutputHelper } from '../outputHelper.js';
 import { BaseReporter } from './reporter.js';
+import { formatJson } from './format-json.js';
 import { type IStateTracker } from './state/state-tracker.js';
 
 /**
@@ -32,7 +33,7 @@ export class JsonFileReporter extends BaseReporter {
       },
     };
 
-    await fs.writeFile(this._outputPath, JSON.stringify(summary, null, 2));
+    await fs.writeFile(this._outputPath, formatJson(summary, { pretty: true }));
     OutputHelper.info(`Results written to ${this._outputPath}`);
   }
 }

package/src/reporting/progress-format.ts

@@ -20,7 +20,9 @@ export function formatProgressInline(progress?: ProgressSummary): string {
       return `(${progress.passed}/${progress.total})`;
     case 'bytes':
       if (progress.totalBytes > 0 && progress.transferredBytes > 0) {
-        return `(${_formatBytes(progress.transferredBytes)}/${_formatBytes(progress.totalBytes)})`;
+        return `(${_formatBytes(progress.transferredBytes)}/${_formatBytes(
+          progress.totalBytes
+        )})`;
       }
       return `(${_formatBytes(progress.totalBytes)})`;
     case 'steps':
@@ -79,7 +81,8 @@ export function summarizeFailure(
 
   if (error) {
     const firstLine = error.split('\n')[0];
-    const short = firstLine.length > 60 ? firstLine.slice(0, 57) + '...' : firstLine;
+    const short =
+      firstLine.length > 60 ? firstLine.slice(0, 57) + '...' : firstLine;
     if (parts.length > 0) {
       parts.push(`: ${short}`);
     } else {

package/src/reporting/reporter.ts

@@ -6,7 +6,17 @@
  */
 
 /** Execution phases a package can move through. */
-export type JobPhase = 'waiting' | 'building' | 'downloading' | 'merging' | 'combining' | 'uploading' | 'scheduling' | 'launching' | 'connecting' | 'executing';
+export type JobPhase =
+  | 'waiting'
+  | 'building'
+  | 'downloading'
+  | 'merging'
+  | 'combining'
+  | 'uploading'
+  | 'scheduling'
+  | 'launching'
+  | 'connecting'
+  | 'executing';
 
 /** Unified status for a package moving through the job lifecycle. */
 export type PackageStatus = 'pending' | JobPhase | 'passed' | 'failed';
@@ -94,7 +104,10 @@ export class BaseReporter implements Reporter {
   async startAsync(): Promise<void> {}
   onPackageStart(_packageName: string): void {}
   onPackagePhaseChange(_packageName: string, _phase: JobPhase): void {}
-  onPackageProgressUpdate(_packageName: string, _progress: ProgressSummary): void {}
+  onPackageProgressUpdate(
+    _packageName: string,
+    _progress: ProgressSummary
+  ): void {}
   onPackageResult(_result: PackageResult, _bufferedOutput?: string[]): void {}
   async stopAsync(): Promise<void> {}
 }

package/src/reporting/result-reporter.ts

@@ -0,0 +1,40 @@
+/**
+ * Single-result reporter — for commands that produce one result (or a polled
+ * series of results), as opposed to batch jobs with per-package lifecycle.
+ *
+ * Use this for any CLI command that:
+ *   - Runs once and prints a result to stdout
+ *   - Writes a result to a file via --output
+ *   - Polls a result on an interval and redraws (--watch)
+ *
+ * For batch jobs (multi-package, lifecycle phases, progress events), use the
+ * Reporter interface in reporter.ts instead.
+ */
+
+/**
+ * Lifecycle hooks for a single-result reporter. Implementations decide how
+ * to render the result (stdout, file, watch redraw, etc).
+ */
+export interface ResultReporter<T = unknown> {
+  /** Called once before any results are reported. */
+  startAsync(): Promise<void>;
+
+  /**
+   * Called when a result is available. May be called multiple times for
+   * watch mode (each tick produces a fresh result).
+   */
+  onResult(result: T): void;
+
+  /** Called once after the final result. */
+  stopAsync(): Promise<void>;
+}
+
+/**
+ * Base class with no-op defaults. Reporters extend this and override only
+ * the hooks they need.
+ */
+export class BaseResultReporter<T = unknown> implements ResultReporter<T> {
+  async startAsync(): Promise<void> {}
+  onResult(_result: T): void {}
+  async stopAsync(): Promise<void> {}
+}

package/src/reporting/simple-reporter.ts

@@ -40,7 +40,9 @@ export class SimpleReporter extends BaseReporter {
 
     const progressText = formatProgressResult(result.progressSummary);
     if (result.success) {
-      const msg = progressText ? `${this._successMessage} ${progressText}` : this._successMessage;
+      const msg = progressText
+        ? `${this._successMessage} ${progressText}`
+        : this._successMessage;
       OutputHelper.info(msg);
     } else {
       OutputHelper.error(this._failureMessage);

package/src/reporting/spinner-reporter.test.ts

@@ -13,12 +13,13 @@ function setup() {
   // Capture everything written to stdout
   const writes: string[] = [];
   const realWrite = process.stdout.write.bind(process.stdout);
-  vi.spyOn(process.stdout, 'write').mockImplementation(
-    ((chunk: any, ...args: any[]) => {
-      writes.push(typeof chunk === 'string' ? chunk : chunk.toString());
-      return true;
-    }) as any
-  );
+  vi.spyOn(process.stdout, 'write').mockImplementation(((
+    chunk: any,
+    ...args: any[]
+  ) => {
+    writes.push(typeof chunk === 'string' ? chunk : chunk.toString());
+    return true;
+  }) as any);
 
   // Suppress console.log (used by startAsync header)
   vi.spyOn(console, 'log').mockImplementation(() => {});

package/src/reporting/spinner-reporter.ts

@@ -2,7 +2,11 @@ import { OutputHelper } from '../outputHelper.js';
 import { formatDurationMs } from '../cli-utils.js';
 import { type PackageResult, BaseReporter } from './reporter.js';
 import { type IStateTracker } from './state/state-tracker.js';
-import { formatProgressInline, formatProgressResult, isEmptyTestRun } from './progress-format.js';
+import {
+  formatProgressInline,
+  formatProgressResult,
+  isEmptyTestRun,
+} from './progress-format.js';
 
 export interface SpinnerReporterOptions {
   showLogs: boolean;
@@ -122,8 +126,8 @@ export class SpinnerReporter extends BaseReporter {
       ? OutputHelper.formatSuccess('✓')
       : OutputHelper.formatError('✗');
     const status = result.success
-      ? (this._options.successLabel ?? 'Passed')
-      : (this._options.failureLabel ?? 'FAILED');
+      ? this._options.successLabel ?? 'Passed'
+      : this._options.failureLabel ?? 'FAILED';
     const formatted = result.success
       ? OutputHelper.formatSuccess(status)
       : OutputHelper.formatError(status);
@@ -172,10 +176,14 @@ export class SpinnerReporter extends BaseReporter {
           ? `${phaseLabel} ${progressText}`
           : phaseLabel;
         const statusText = OutputHelper.formatInfo(plain.padEnd(22));
-        line = `  ${icon} ${state.name.padEnd(30)} ${statusText} ${OutputHelper.formatDim(time)}`;
+        line = `  ${icon} ${state.name.padEnd(
+          30
+        )} ${statusText} ${OutputHelper.formatDim(time)}`;
       } else if (state.status === 'passed') {
         const icon = OutputHelper.formatSuccess('✓');
-        const progressText = formatProgressResult(state.result?.progressSummary);
+        const progressText = formatProgressResult(
+          state.result?.progressSummary
+        );
         const label = this._options.successLabel ?? 'Passed';
         const empty = isEmptyTestRun(state.result?.progressSummary);
         let plain = progressText ? `${label} ${progressText}` : label;
@@ -183,15 +191,19 @@ export class SpinnerReporter extends BaseReporter {
         const statusText = empty
           ? OutputHelper.formatWarning(plain.padEnd(22))
           : OutputHelper.formatSuccess(plain.padEnd(22));
-        line = `  ${icon} ${state.name.padEnd(30)} ${statusText} ${OutputHelper.formatDim(time)}`;
+        line = `  ${icon} ${state.name.padEnd(
+          30
+        )} ${statusText} ${OutputHelper.formatDim(time)}`;
       } else {
         const icon = OutputHelper.formatError('✗');
         const failedPhase = state.result?.failedPhase;
         const plain = failedPhase
           ? `${this._options.failureLabel ?? 'FAILED'} at ${failedPhase}`
-          : (this._options.failureLabel ?? 'FAILED');
+          : this._options.failureLabel ?? 'FAILED';
         const statusText = OutputHelper.formatError(plain.padEnd(22));
-        line = `  ${icon} ${state.name.padEnd(30)} ${statusText} ${OutputHelper.formatDim(time)}`;
+        line = `  ${icon} ${state.name.padEnd(
+          30
+        )} ${statusText} ${OutputHelper.formatDim(time)}`;
       }
 
       lines.push(line);

package/src/reporting/state/live-state-tracker.ts

@@ -1,4 +1,10 @@
-import { type PackageResult, type PackageStatus, type JobPhase, type ProgressSummary, BaseReporter } from '../reporter.js';
+import {
+  type PackageResult,
+  type PackageStatus,
+  type JobPhase,
+  type ProgressSummary,
+  BaseReporter,
+} from '../reporter.js';
 import { type IStateTracker, type PackageState } from './state-tracker.js';
 
 export type { PackageState } from './state-tracker.js';
@@ -8,10 +14,7 @@ export type { PackageState } from './state-tracker.js';
  * Extends BaseReporter to receive lifecycle hooks and mutate state.
  * Reporters read from it via the IStateTracker interface.
  */
-export class LiveStateTracker
-  extends BaseReporter
-  implements IStateTracker
-{
+export class LiveStateTracker extends BaseReporter implements IStateTracker {
   private _packages: Map<string, PackageState>;
   private _startTimeMs = 0;
   private _completed = 0;
@@ -77,7 +80,10 @@ export class LiveStateTracker
     state.progress = undefined; // clear progress on phase transition
   }
 
-  override onPackageProgressUpdate(name: string, progress: ProgressSummary): void {
+  override onPackageProgressUpdate(
+    name: string,
+    progress: ProgressSummary
+  ): void {
     const state = this._packages.get(name);
     if (!state) return;
     state.progress = progress;

package/src/reporting/state/loaded-state-tracker.ts

@@ -4,10 +4,7 @@ import {
   type PackageStatus,
   type BatchSummary,
 } from '../reporter.js';
-import {
-  type IStateTracker,
-  type PackageState,
-} from './state-tracker.js';
+import { type IStateTracker, type PackageState } from './state-tracker.js';
 
 /**
  * Batch state loaded from a previously-saved BatchSummary JSON file.
@@ -31,9 +28,7 @@ export class LoadedStateTracker implements IStateTracker {
     this._startTimeMs = startTimeMs;
   }
 
-  static async fromFileAsync(
-    filePath: string
-  ): Promise<LoadedStateTracker> {
+  static async fromFileAsync(filePath: string): Promise<LoadedStateTracker> {
     const raw = await fs.readFile(filePath, 'utf-8');
     const summary = JSON.parse(raw) as BatchSummary;
     return LoadedStateTracker.fromSummary(summary);

package/src/reporting/state/state-tracker.ts

@@ -1,4 +1,8 @@
-import { type PackageResult, type PackageStatus, type ProgressSummary } from '../reporter.js';
+import {
+  type PackageResult,
+  type PackageStatus,
+  type ProgressSummary,
+} from '../reporter.js';
 
 export interface PackageState {
   name: string;

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

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { StdoutResultReporter } from './stdout-result-reporter.js';
+
+describe('StdoutResultReporter', () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+  });
+
+  it('writes rendered result to stdout on each onResult', () => {
+    const reporter = new StdoutResultReporter<{ name: string }>({
+      render: (r) => `name=${r.name}`,
+    });
+
+    reporter.onResult({ name: 'first' });
+    reporter.onResult({ name: 'second' });
+
+    expect(logSpy).toHaveBeenCalledTimes(2);
+    expect(logSpy).toHaveBeenNthCalledWith(1, 'name=first');
+    expect(logSpy).toHaveBeenNthCalledWith(2, 'name=second');
+  });
+
+  it('startAsync and stopAsync are no-ops', async () => {
+    const reporter = new StdoutResultReporter<unknown>({ render: () => '' });
+    await reporter.startAsync();
+    await reporter.stopAsync();
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,23 @@
+/**
+ * Writes a rendered result to stdout. One-shot — calls render(result) and
+ * console.log(...) on each onResult.
+ */
+
+import { BaseResultReporter } from './result-reporter.js';
+
+export interface StdoutResultReporterOptions<T> {
+  render: (result: T) => string;
+}
+
+export class StdoutResultReporter<T = unknown> extends BaseResultReporter<T> {
+  private _render: (result: T) => string;
+
+  constructor(options: StdoutResultReporterOptions<T>) {
+    super();
+    this._render = options.render;
+  }
+
+  override onResult(result: T): void {
+    console.log(this._render(result));
+  }
+}

package/src/reporting/summary-table-reporter.ts

@@ -1,6 +1,7 @@
 import { OutputHelper } from '../outputHelper.js';
 import { formatDurationMs } from '../cli-utils.js';
-import { BaseReporter } from './reporter.js';
+import { BaseReporter, type PackageResult } from './reporter.js';
+import { formatTable, type TableColumn } from './format-table.js';
 import { type IStateTracker } from './state/state-tracker.js';
 import { formatProgressResult, isEmptyTestRun } from './progress-format.js';
 
@@ -39,44 +40,30 @@ export class SummaryTableReporter extends BaseReporter {
     const passed = results.length - failures.length;
     const durationMs = Date.now() - this._state.startTimeMs;
 
-    const STATUS_WIDTH = 26;
-
-    console.log('');
-    console.log('Package'.padEnd(40) + 'Status'.padEnd(STATUS_WIDTH) + 'Duration');
-    console.log('─'.repeat(40 + STATUS_WIDTH + 8));
-
     let emptyRunCount = 0;
-    for (const result of results) {
-      const progressText = formatProgressResult(result.progressSummary);
-      const empty = isEmptyTestRun(result.progressSummary);
-      if (empty) emptyRunCount++;
 
-      let label: string;
-      if (result.success) {
-        label = progressText ? `${this._successLabel} ${progressText}` : this._successLabel;
-      } else {
-        const failedPhase = result.failedPhase;
-        label = failedPhase
-          ? `${this._failureLabel} at ${failedPhase}`
-          : this._failureLabel;
-      }
+    const columns: TableColumn<PackageResult>[] = [
+      {
+        header: 'Package',
+        value: (r) => r.packageName,
+        minWidth: 40,
+      },
+      {
+        header: 'Status',
+        value: (r) => this._statusLabel(r),
+        format: (label, r) =>
+          this._colorStatus(label, r, () => emptyRunCount++),
+        minWidth: 26,
+      },
+      {
+        header: 'Duration',
+        value: (r) => formatDurationMs(r.durationMs),
+        format: (v) => OutputHelper.formatDim(v),
+      },
+    ];
 
-      // Pad the plain text BEFORE wrapping in ANSI so padEnd counts visible chars
-      const paddedLabel = label.padEnd(STATUS_WIDTH);
-      let status: string;
-      if (result.success) {
-        status = empty
-          ? OutputHelper.formatWarning(paddedLabel)
-          : OutputHelper.formatSuccess(paddedLabel);
-      } else {
-        status = OutputHelper.formatError(paddedLabel);
-      }
-
-      const duration = OutputHelper.formatDim(
-        formatDurationMs(result.durationMs)
-      );
-      console.log(result.packageName.padEnd(40) + status + duration);
-    }
+    console.log('');
+    console.log(formatTable(results, columns));
 
     console.log('');
     const passedText = OutputHelper.formatSuccess(`${passed} passed`);
@@ -99,4 +86,32 @@ export class SummaryTableReporter extends BaseReporter {
       );
     }
   }
+
+  private _statusLabel(result: PackageResult): string {
+    if (result.success) {
+      const progressText = formatProgressResult(result.progressSummary);
+      return progressText
+        ? `${this._successLabel} ${progressText}`
+        : this._successLabel;
+    }
+    const failedPhase = result.failedPhase;
+    return failedPhase
+      ? `${this._failureLabel} at ${failedPhase}`
+      : this._failureLabel;
+  }
+
+  private _colorStatus(
+    label: string,
+    result: PackageResult,
+    countEmpty: () => void
+  ): string {
+    if (result.success) {
+      const empty = isEmptyTestRun(result.progressSummary);
+      if (empty) countEmpty();
+      return empty
+        ? OutputHelper.formatWarning(label)
+        : OutputHelper.formatSuccess(label);
+    }
+    return OutputHelper.formatError(label);
+  }
 }

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');
+  });
+});