feat: add silent mode and eta helpers to progress

Author: KurtGokhan

packages/padrone/src/core/runtime.ts

@@ -31,6 +31,15 @@ export type PadroneProgress = {
   succeed: (message?: string | null, options?: { indicator?: string }) => void;
   /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */
   fail: (message?: string | null, options?: { indicator?: string }) => void;
+  /** Control ETA (estimated time remaining) display at runtime. */
+  eta: {
+    /** Enable ETA tracking. Starts collecting samples from subsequent `update()` calls. */
+    start: () => void;
+    /** Disable ETA display. */
+    stop: () => void;
+    /** Clear collected samples and restart estimation. Useful between operation phases. */
+    reset: () => void;
+  };
   /** Stop without success/fail status. */
   stop: () => void;
   /** Temporarily hide the indicator so other output can be written cleanly. */

packages/padrone/src/extension/progress-renderer.ts

@@ -154,8 +154,10 @@ export function createTerminalProgress(message: string, options?: PadroneProgres
   const formatFinal = (icon: string, msg: string) => (icon ? `${icon} ${msg}\n` : `${msg}\n`);
 
   if (typeof process === 'undefined' || !process.stderr?.isTTY) {
+    const noopEta = { start() {}, stop() {}, reset() {} };
     return {
       update() {},
+      eta: noopEta,
       succeed(msg, opts) {
         if (msg === null) return;
         const icon = opts?.indicator ?? successIcon;
@@ -176,11 +178,11 @@ export function createTerminalProgress(message: string, options?: PadroneProgres
   const ansiPattern = /\x1b\[[0-9;]*m/g;
 
   if (spinnerCfg.show === 'never' && (!barCfg || barCfg.show === 'never') && !message) {
-    return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+    return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
   }
 
   const showTime = options?.time ?? false;
-  const showEta = options?.eta ?? false;
+  let etaEnabled = options?.eta ?? false;
 
   let spinnerFrame = 0;
   let barFrame = 0;
@@ -224,7 +226,7 @@ export function createTerminalProgress(message: string, options?: PadroneProgres
 
     let line = '';
     if (barVisible) line += formatBar(progress, barCfg!, barFrame);
-    const hasEta = showEta && progress !== undefined && progress < 1 && etaMs !== undefined;
+    const hasEta = etaEnabled && progress !== undefined && progress < 1 && etaMs !== undefined;
     if (timeEnabled || hasEta) {
       const parts: string[] = [];
       if (timeEnabled) parts.push(`⏱ ${formatDuration(Date.now() - startTime)}`);
@@ -278,14 +280,35 @@ export function createTerminalProgress(message: string, options?: PadroneProgres
     clearLines();
   };
 
+  const eta = {
+    start() {
+      if (stopped) return;
+      etaEnabled = true;
+      render();
+    },
+    stop() {
+      if (stopped) return;
+      etaEnabled = false;
+      etaMs = undefined;
+      render();
+    },
+    reset() {
+      if (stopped) return;
+      etaSamples.length = 0;
+      etaMs = undefined;
+      etaCalculatedAt = 0;
+      render();
+    },
+  };
+
   return {
     update(value) {
       if (stopped) return;
       const parsed = parseUpdate(value);
       if (parsed.message !== undefined) text = parsed.message;
       if (parsed.progress !== undefined) {
         progress = parsed.progress;
-        if (showEta) {
+        if (etaEnabled) {
           const now = Date.now();
           etaSamples.push({ time: now, progress: parsed.progress });
           const estimated = estimateEta(etaSamples);
@@ -309,6 +332,7 @@ export function createTerminalProgress(message: string, options?: PadroneProgres
       }
       render();
     },
+    eta,
     succeed(msg, opts) {
       clear();
       if (msg === null) return;

packages/padrone/src/extension/progress.ts

@@ -43,6 +43,8 @@ export type PadroneProgressConfig<TRes = unknown> = {
    * Defaults to the built-in terminal renderer (`createTerminalProgress`).
    */
   renderer?: PadroneProgressRenderer;
+  /** Suppress all progress output. The `progress` interface is still provided on the context as a no-op. */
+  silent?: boolean;
 };
 
 /**
@@ -52,7 +54,7 @@ export type PadroneProgressConfig<TRes = unknown> = {
  *
  * Provide via context as `{ progressConfig: PadroneProgressDefaults }`.
  */
-export type PadroneProgressDefaults = Pick<PadroneProgressConfig, 'message' | 'spinner' | 'bar' | 'time' | 'eta' | 'renderer'>;
+export type PadroneProgressDefaults = Pick<PadroneProgressConfig, 'message' | 'spinner' | 'bar' | 'time' | 'eta' | 'renderer' | 'silent'>;
 
 /** Builder/program type after applying `padroneProgress()`. Adds `{ progress: PadroneProgress }` to the command context. */
 export type WithProgress<T> = WithInterceptor<T, { progress: PadroneProgress }>;
@@ -61,8 +63,10 @@ export type WithProgress<T> = WithInterceptor<T, { progress: PadroneProgress }>;
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+const noopEta = { start() {}, stop() {}, reset() {} };
 const noopIndicator: PadroneProgress = {
   update() {},
+  eta: noopEta,
   succeed() {},
   fail() {},
   stop() {},
@@ -146,6 +150,7 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
   const rawRenderer = isObj ? config.renderer : undefined;
   const rawTime = isObj ? config.time : undefined;
   const rawEta = isObj ? config.eta : undefined;
+  const rawSilent = isObj ? config.silent : undefined;
 
   return defineInterceptor({ id: 'padrone:progress', name: 'padrone:progress' })
     .requires<{ progressConfig?: PadroneProgressDefaults }>()
@@ -155,11 +160,13 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
       // Lazily resolved from context + constructor args
       let resolvedRenderer: PadroneProgressRenderer | undefined;
       let resolvedOptions: PadroneProgressOptions | undefined;
+      let resolvedSilent = false;
       let msgs: ReturnType<typeof resolveMessages> | undefined;
 
       function resolve(ctx: { context?: { progressConfig?: PadroneProgressDefaults } }) {
         if (resolvedRenderer) return;
         const ctxCfg = (ctx.context as Record<string, unknown> | undefined)?.progressConfig as PadroneProgressDefaults | undefined;
+        resolvedSilent = rawSilent ?? ctxCfg?.silent ?? false;
         const spinner = rawSpinner ?? ctxCfg?.spinner;
         const bar = rawBar ?? ctxCfg?.bar;
         const time = rawTime ?? ctxCfg?.time;
@@ -179,6 +186,7 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
       return {
         validate(ctx, next) {
           resolve(ctx);
+          if (resolvedSilent) return next();
           indicator = resolvedRenderer!(msgs!.validation || msgs!.progress, resolvedOptions);
 
           const originalOutput = ctx.runtime.output;
@@ -227,6 +235,8 @@ function progressInterceptor(config: string | PadroneProgressConfig) {
         },
 
         execute(_ctx, next) {
+          if (resolvedSilent) return next({ context: { progress: noopIndicator } });
+
           // Transition from validation message to progress message
           if (indicator && msgs!.validation) indicator.update(msgs!.progress);
 

packages/padrone/tests/progress.test.ts

@@ -35,6 +35,7 @@ function createMockProgress() {
       stop: () => {
         calls.push('stop');
       },
+      eta: { start() {}, stop() {}, reset() {} },
       pause: () => {
         calls.push('pause');
       },
@@ -571,7 +572,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app')
@@ -637,7 +638,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -652,7 +653,7 @@ describe('progress', () => {
       let receivedOptions: any = 'NOT_CALLED';
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -667,7 +668,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -684,7 +685,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -699,7 +700,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -757,7 +758,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -772,7 +773,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -787,7 +788,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app').command('cmd', (c) =>
@@ -802,7 +803,7 @@ describe('progress', () => {
       let receivedOptions: any;
       const renderer: PadroneProgressRenderer = (_message, options) => {
         receivedOptions = options;
-        return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+        return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
       };
 
       const program = createPadrone('app')