padrone 1.9.0 → 2.0.0

package/dist/extension/progress-renderer.mjs

@@ -0,0 +1,351 @@
+//#region src/extension/progress-renderer.ts
+const spinnerPresets = {
+	dots: [
+		"⠋",
+		"⠙",
+		"⠹",
+		"⠸",
+		"⠼",
+		"⠴",
+		"⠦",
+		"⠧",
+		"⠇",
+		"⠏"
+	],
+	line: [
+		"-",
+		"\\",
+		"|",
+		"/"
+	],
+	arc: [
+		"◜",
+		"◠",
+		"◝",
+		"◞",
+		"◡",
+		"◟"
+	],
+	bounce: [
+		"⠁",
+		"⠂",
+		"⠄",
+		"⡀",
+		"⢀",
+		"⠠",
+		"⠐",
+		"⠈"
+	]
+};
+function resolveSpinnerConfig(config) {
+	if (config === false) return {
+		frames: [],
+		interval: 80,
+		show: "never"
+	};
+	if (config === true) return {
+		frames: spinnerPresets.dots,
+		interval: 80,
+		show: "always"
+	};
+	if (typeof config === "string") return {
+		frames: spinnerPresets[config],
+		interval: 80,
+		show: "auto"
+	};
+	if (typeof config === "object") return {
+		frames: config.frames ?? spinnerPresets.dots,
+		interval: config.interval ?? 80,
+		show: config.show ?? "auto"
+	};
+	return {
+		frames: spinnerPresets.dots,
+		interval: 80,
+		show: "auto"
+	};
+}
+const defaultBarConfig = {
+	width: 20,
+	filled: "█",
+	empty: "░",
+	animation: "bounce",
+	show: "auto"
+};
+function resolveBarConfig(bar) {
+	if (bar === false) return void 0;
+	if (!bar) return { ...defaultBarConfig };
+	if (bar === true) return {
+		...defaultBarConfig,
+		show: "always"
+	};
+	return {
+		width: bar.width ?? 20,
+		filled: bar.filled ?? "█",
+		empty: bar.empty ?? "░",
+		animation: bar.animation ?? "bounce",
+		show: bar.show ?? "always"
+	};
+}
+const SEGMENT_RATIO = .25;
+const pulseGradient = [
+	"░",
+	"▒",
+	"▓",
+	"█",
+	"▓",
+	"▒",
+	"░"
+];
+function formatIndeterminate(cfg, frame) {
+	const { width, filled, empty, animation } = cfg;
+	const pad = "".padStart(4);
+	if (animation === "pulse") return `${pad} ${pulseGradient[frame % pulseGradient.length].repeat(width)}`;
+	const seg = Math.max(2, Math.round(width * SEGMENT_RATIO));
+	const travel = width - seg;
+	if (animation === "slide") {
+		const offset = frame % (travel + 1);
+		return `${pad} ${empty.repeat(offset)}${filled.repeat(seg)}${empty.repeat(travel - offset)}`;
+	}
+	const cycle = travel * 2;
+	const pos = frame % cycle;
+	const offset = pos <= travel ? pos : cycle - pos;
+	return `${pad} ${empty.repeat(offset)}${filled.repeat(seg)}${empty.repeat(width - offset - seg)}`;
+}
+function formatBar(progress, cfg, frame) {
+	if (progress === void 0) return formatIndeterminate(cfg, frame);
+	const { width, filled, empty } = cfg;
+	const clamped = Math.max(0, Math.min(1, progress));
+	const filledCount = Math.round(clamped * width);
+	return `${`${Math.round(clamped * 100)}%`.padStart(4)} ${filled.repeat(filledCount)}${empty.repeat(width - filledCount)}`;
+}
+function parseUpdate(value) {
+	if (typeof value === "string") return { message: value };
+	if (typeof value === "number") return { progress: value };
+	return value;
+}
+function formatDuration(ms) {
+	const totalSeconds = Math.floor(ms / 1e3);
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor(totalSeconds % 3600 / 60);
+	const seconds = totalSeconds % 60;
+	if (hours > 0) return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+	return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+function estimateEta(samples) {
+	if (samples.length < 2) return void 0;
+	const first = samples[0];
+	const last = samples[samples.length - 1];
+	const progressDelta = last.progress - first.progress;
+	if (progressDelta <= 0) return void 0;
+	const rate = progressDelta / (last.time - first.time);
+	const remaining = 1 - last.progress;
+	if (remaining <= 0) return 0;
+	return remaining / rate;
+}
+/**
+* Creates a terminal progress indicator (spinner, bar, or both).
+* Returns a no-op indicator in non-TTY/CI environments.
+*/
+function createTerminalProgress(message, options) {
+	const spinnerCfg = resolveSpinnerConfig(options?.spinner);
+	const successIcon = options?.successIndicator ?? "✔";
+	const errorIcon = options?.errorIndicator ?? "✖";
+	const barCfg = resolveBarConfig(options?.bar);
+	const formatFinal = (icon, msg) => icon ? `${icon} ${msg}\n` : `${msg}\n`;
+	if (typeof process === "undefined" || !process.stderr?.isTTY) return {
+		update() {},
+		eta: {
+			start() {},
+			stop() {},
+			reset() {}
+		},
+		succeed(msg, opts) {
+			if (msg === null) return;
+			const icon = opts?.indicator ?? successIcon;
+			if (msg || message) process?.stderr?.write?.(formatFinal(icon, msg || message));
+		},
+		fail(msg, opts) {
+			if (msg === null) return;
+			const icon = opts?.indicator ?? errorIcon;
+			if (msg || message) process?.stderr?.write?.(formatFinal(icon, msg || message));
+		},
+		stop() {},
+		pause() {},
+		resume() {}
+	};
+	const ansiPattern = /\x1b\[[0-9;]*m/g;
+	if (spinnerCfg.show === "never" && (!barCfg || barCfg.show === "never") && !message) return {
+		update() {},
+		eta: {
+			start() {},
+			stop() {},
+			reset() {}
+		},
+		succeed() {},
+		fail() {},
+		stop() {},
+		pause() {},
+		resume() {}
+	};
+	const showTime = options?.time ?? false;
+	let etaEnabled = options?.eta ?? false;
+	let spinnerFrame = 0;
+	let barFrame = 0;
+	let text = message;
+	let progress;
+	let indeterminate = false;
+	let stopped = false;
+	let paused = false;
+	let timeEnabled = showTime;
+	let startTime = showTime ? Date.now() : 0;
+	const etaSamples = [];
+	let etaMs;
+	let etaCalculatedAt = 0;
+	const writeStderr = process.stderr.write.bind(process.stderr);
+	const writeStdout = process.stdout.write.bind(process.stdout);
+	let prevLineCount = 0;
+	const clearLines = () => {
+		if (prevLineCount > 1) for (let i = 1; i < prevLineCount; i++) writeStderr("\x1B[1A\x1B[2K");
+		writeStderr("\x1B[2K\r");
+		prevLineCount = 0;
+	};
+	/** Count how many terminal rows `str` occupies, accounting for line wrapping. */
+	const lineCount = (str) => {
+		const cols = process.stderr.columns || 80;
+		const visible = str.replace(ansiPattern, "");
+		return Math.max(1, Math.ceil(visible.length / cols));
+	};
+	const render = () => {
+		if (paused || stopped) return;
+		const barVisible = barCfg && (barCfg.show === "always" || barCfg.show === "auto" && (progress !== void 0 || indeterminate));
+		const spinnerVisible = spinnerCfg.show === "always" || spinnerCfg.show === "auto" && !barVisible;
+		let line = "";
+		if (barVisible) line += formatBar(progress, barCfg, barFrame);
+		const hasEta = etaEnabled && progress !== void 0 && progress < 1 && etaMs !== void 0;
+		if (timeEnabled || hasEta) {
+			const parts = [];
+			if (timeEnabled) parts.push(`⏱ ${formatDuration(Date.now() - startTime)}`);
+			if (hasEta) {
+				const elapsed = Date.now() - etaCalculatedAt;
+				parts.push(`ETA ${formatDuration(Math.max(0, etaMs - elapsed))}`);
+			}
+			if (line) line += " ";
+			line += parts.join(" | ");
+		}
+		if (spinnerVisible) {
+			if (line) line += " ";
+			line += frames[spinnerFrame] ?? "";
+		}
+		if (text) {
+			if (line) line += " ";
+			line += text;
+		}
+		if (line) {
+			clearLines();
+			writeStderr(line);
+			prevLineCount = lineCount(line);
+		} else clearLines();
+	};
+	const { frames } = spinnerCfg;
+	const needsAnimation = spinnerCfg.show !== "never" || barCfg && barCfg.show !== "never";
+	const tickInterval = barCfg && barCfg.show !== "never" ? Math.min(80, spinnerCfg.interval) : spinnerCfg.interval;
+	const timer = needsAnimation ? setInterval(() => {
+		spinnerFrame = (spinnerFrame + 1) % (frames.length || 1);
+		barFrame++;
+		render();
+	}, tickInterval) : void 0;
+	if (timer && typeof timer === "object" && "unref" in timer) timer.unref();
+	render();
+	const clear = () => {
+		if (stopped) return;
+		stopped = true;
+		paused = false;
+		if (timer) clearInterval(timer);
+		clearLines();
+	};
+	return {
+		update(value) {
+			if (stopped) return;
+			const parsed = parseUpdate(value);
+			if (parsed.message !== void 0) text = parsed.message;
+			if (parsed.progress !== void 0) {
+				progress = parsed.progress;
+				if (etaEnabled) {
+					const now = Date.now();
+					etaSamples.push({
+						time: now,
+						progress: parsed.progress
+					});
+					const estimated = estimateEta(etaSamples);
+					if (estimated !== void 0) {
+						etaMs = estimated;
+						etaCalculatedAt = now;
+					}
+				}
+			}
+			if (parsed.indeterminate !== void 0) {
+				indeterminate = parsed.indeterminate;
+				if (indeterminate) progress = void 0;
+			}
+			if (parsed.time !== void 0) {
+				if (parsed.time && !timeEnabled) {
+					timeEnabled = true;
+					startTime = Date.now();
+				} else if (!parsed.time) timeEnabled = false;
+			}
+			render();
+		},
+		eta: {
+			start() {
+				if (stopped) return;
+				etaEnabled = true;
+				render();
+			},
+			stop() {
+				if (stopped) return;
+				etaEnabled = false;
+				etaMs = void 0;
+				render();
+			},
+			reset() {
+				if (stopped) return;
+				etaSamples.length = 0;
+				etaMs = void 0;
+				etaCalculatedAt = 0;
+				render();
+			}
+		},
+		succeed(msg, opts) {
+			clear();
+			if (msg === null) return;
+			const finalMsg = msg ?? text;
+			const icon = opts?.indicator ?? successIcon;
+			if (finalMsg) writeStderr(formatFinal(icon, finalMsg));
+		},
+		fail(msg, opts) {
+			clear();
+			if (msg === null) return;
+			const finalMsg = msg ?? text;
+			const icon = opts?.indicator ?? errorIcon;
+			if (finalMsg) writeStderr(formatFinal(icon, finalMsg));
+		},
+		stop() {
+			clear();
+		},
+		pause() {
+			if (stopped || paused) return;
+			paused = true;
+			clearLines();
+			writeStdout("\x1B[2K\r");
+		},
+		resume() {
+			if (stopped || !paused) return;
+			paused = false;
+			render();
+		}
+	};
+}
+//#endregion
+export { createTerminalProgress };
+
+//# sourceMappingURL=progress-renderer.mjs.map

package/dist/extension/progress-renderer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-renderer.mjs","names":[],"sources":["../../src/extension/progress-renderer.ts"],"sourcesContent":["import type {\n  PadroneBarConfig,\n  PadroneProgress,\n  PadroneProgressOptions,\n  PadroneProgressShow,\n  PadroneProgressUpdate,\n  PadroneSpinnerConfig,\n  PadroneSpinnerPreset,\n} from '../core/runtime.ts';\n\n// ---------------------------------------------------------------------------\n// Spinner presets & resolution\n// ---------------------------------------------------------------------------\n\nconst spinnerPresets: Record<PadroneSpinnerPreset, string[]> = {\n  dots: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],\n  line: ['-', '\\\\', '|', '/'],\n  arc: ['◜', '◠', '◝', '◞', '◡', '◟'],\n  bounce: ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'],\n};\n\ntype ResolvedSpinnerConfig = { frames: string[]; interval: number; show: PadroneProgressShow };\n\nfunction resolveSpinnerConfig(config?: PadroneSpinnerConfig): ResolvedSpinnerConfig {\n  if (config === false) return { frames: [], interval: 80, show: 'never' };\n  if (config === true) return { frames: spinnerPresets.dots, interval: 80, show: 'always' };\n  if (typeof config === 'string') return { frames: spinnerPresets[config], interval: 80, show: 'auto' };\n  if (typeof config === 'object') {\n    return {\n      frames: config.frames ?? spinnerPresets.dots,\n      interval: config.interval ?? 80,\n      show: config.show ?? 'auto',\n    };\n  }\n  return { frames: spinnerPresets.dots, interval: 80, show: 'auto' };\n}\n\n// ---------------------------------------------------------------------------\n// Bar resolution & rendering\n// ---------------------------------------------------------------------------\n\ntype ResolvedBarConfig = {\n  width: number;\n  filled: string;\n  empty: string;\n  animation: 'bounce' | 'slide' | 'pulse';\n  show: PadroneProgressShow;\n};\n\nconst defaultBarConfig: ResolvedBarConfig = { width: 20, filled: '█', empty: '░', animation: 'bounce', show: 'auto' };\n\nfunction resolveBarConfig(bar: boolean | PadroneBarConfig | undefined): ResolvedBarConfig | undefined {\n  if (bar === false) return undefined;\n  if (!bar) return { ...defaultBarConfig };\n  if (bar === true) return { ...defaultBarConfig, show: 'always' };\n  return {\n    width: bar.width ?? 20,\n    filled: bar.filled ?? '█',\n    empty: bar.empty ?? '░',\n    animation: bar.animation ?? 'bounce',\n    show: bar.show ?? 'always',\n  };\n}\n\nconst SEGMENT_RATIO = 0.25;\nconst pulseGradient = ['░', '▒', '▓', '█', '▓', '▒', '░'];\n\nfunction formatIndeterminate(cfg: ResolvedBarConfig, frame: number): string {\n  const { width, filled, empty, animation } = cfg;\n  const pad = ''.padStart(4);\n\n  if (animation === 'pulse') {\n    const idx = frame % pulseGradient.length;\n    return `${pad} ${pulseGradient[idx]!.repeat(width)}`;\n  }\n\n  const seg = Math.max(2, Math.round(width * SEGMENT_RATIO));\n  const travel = width - seg;\n\n  if (animation === 'slide') {\n    const offset = frame % (travel + 1);\n    return `${pad} ${empty.repeat(offset)}${filled.repeat(seg)}${empty.repeat(travel - offset)}`;\n  }\n\n  // bounce (default)\n  const cycle = travel * 2;\n  const pos = frame % cycle;\n  const offset = pos <= travel ? pos : cycle - pos;\n  return `${pad} ${empty.repeat(offset)}${filled.repeat(seg)}${empty.repeat(width - offset - seg)}`;\n}\n\nfunction formatBar(progress: number | undefined, cfg: ResolvedBarConfig, frame: number): string {\n  if (progress === undefined) return formatIndeterminate(cfg, frame);\n  const { width, filled, empty } = cfg;\n  const clamped = Math.max(0, Math.min(1, progress));\n  const filledCount = Math.round(clamped * width);\n  const pct = `${Math.round(clamped * 100)}%`.padStart(4);\n  return `${pct} ${filled.repeat(filledCount)}${empty.repeat(width - filledCount)}`;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction parseUpdate(value: PadroneProgressUpdate): { message?: string; progress?: number; indeterminate?: boolean; time?: boolean } {\n  if (typeof value === 'string') return { message: value };\n  if (typeof value === 'number') return { progress: value };\n  return value;\n}\n\nfunction formatDuration(ms: number): string {\n  const totalSeconds = Math.floor(ms / 1000);\n  const hours = Math.floor(totalSeconds / 3600);\n  const minutes = Math.floor((totalSeconds % 3600) / 60);\n  const seconds = totalSeconds % 60;\n  if (hours > 0) return `${hours}:${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;\n  return `${minutes}:${String(seconds).padStart(2, '0')}`;\n}\n\nfunction estimateEta(samples: { time: number; progress: number }[]): number | undefined {\n  if (samples.length < 2) return undefined;\n  const first = samples[0]!;\n  const last = samples[samples.length - 1]!;\n  const progressDelta = last.progress - first.progress;\n  if (progressDelta <= 0) return undefined;\n  const timeDelta = last.time - first.time;\n  const rate = progressDelta / timeDelta;\n  const remaining = 1 - last.progress;\n  if (remaining <= 0) return 0;\n  return remaining / rate;\n}\n\n// ---------------------------------------------------------------------------\n// Factory type\n// ---------------------------------------------------------------------------\n\n/** Factory function that creates a `PadroneProgress`. */\nexport type PadroneProgressRenderer = (message: string, options?: PadroneProgressOptions) => PadroneProgress;\n\n// ---------------------------------------------------------------------------\n// Default terminal renderer\n// ---------------------------------------------------------------------------\n\n/**\n * Creates a terminal progress indicator (spinner, bar, or both).\n * Returns a no-op indicator in non-TTY/CI environments.\n */\nexport function createTerminalProgress(message: string, options?: PadroneProgressOptions): PadroneProgress {\n  const spinnerCfg = resolveSpinnerConfig(options?.spinner);\n  const successIcon = options?.successIndicator ?? '✔';\n  const errorIcon = options?.errorIndicator ?? '✖';\n  const barCfg = resolveBarConfig(options?.bar);\n\n  const formatFinal = (icon: string, msg: string) => (icon ? `${icon} ${msg}\\n` : `${msg}\\n`);\n\n  if (typeof process === 'undefined' || !process.stderr?.isTTY) {\n    const noopEta = { start() {}, stop() {}, reset() {} };\n    return {\n      update() {},\n      eta: noopEta,\n      succeed(msg, opts) {\n        if (msg === null) return;\n        const icon = opts?.indicator ?? successIcon;\n        if (msg || message) process?.stderr?.write?.(formatFinal(icon, msg || message));\n      },\n      fail(msg, opts) {\n        if (msg === null) return;\n        const icon = opts?.indicator ?? errorIcon;\n        if (msg || message) process?.stderr?.write?.(formatFinal(icon, msg || message));\n      },\n      stop() {},\n      pause() {},\n      resume() {},\n    };\n  }\n\n  // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping requires matching ESC\n  const ansiPattern = /\\x1b\\[[0-9;]*m/g;\n\n  if (spinnerCfg.show === 'never' && (!barCfg || barCfg.show === 'never') && !message) {\n    return { update() {}, eta: { start() {}, stop() {}, reset() {} }, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };\n  }\n\n  const showTime = options?.time ?? false;\n  let etaEnabled = options?.eta ?? false;\n\n  let spinnerFrame = 0;\n  let barFrame = 0;\n  let text = message;\n  let progress: number | undefined;\n  let indeterminate = false;\n  let stopped = false;\n  let paused = false;\n  let timeEnabled = showTime;\n  let startTime = showTime ? Date.now() : 0;\n  const etaSamples: { time: number; progress: number }[] = [];\n  let etaMs: number | undefined;\n  let etaCalculatedAt = 0;\n\n  const writeStderr = process.stderr.write.bind(process.stderr);\n  const writeStdout = process.stdout.write.bind(process.stdout);\n  let prevLineCount = 0;\n\n  const clearLines = () => {\n    if (prevLineCount > 1) {\n      // Move cursor up and clear each wrapped line above the current one\n      for (let i = 1; i < prevLineCount; i++) writeStderr('\\x1b[1A\\x1b[2K');\n    }\n    writeStderr('\\x1b[2K\\r');\n    prevLineCount = 0;\n  };\n\n  /** Count how many terminal rows `str` occupies, accounting for line wrapping. */\n  const lineCount = (str: string): number => {\n    const cols = process.stderr.columns || 80;\n    // Strip ANSI escape sequences for accurate width measurement\n    const visible = str.replace(ansiPattern, '');\n    return Math.max(1, Math.ceil(visible.length / cols));\n  };\n\n  const render = () => {\n    if (paused || stopped) return;\n\n    const barVisible = barCfg && (barCfg.show === 'always' || (barCfg.show === 'auto' && (progress !== undefined || indeterminate)));\n    const spinnerVisible = spinnerCfg.show === 'always' || (spinnerCfg.show === 'auto' && !barVisible);\n\n    let line = '';\n    if (barVisible) line += formatBar(progress, barCfg!, barFrame);\n    const hasEta = etaEnabled && progress !== undefined && progress < 1 && etaMs !== undefined;\n    if (timeEnabled || hasEta) {\n      const parts: string[] = [];\n      if (timeEnabled) parts.push(`⏱ ${formatDuration(Date.now() - startTime)}`);\n      if (hasEta) {\n        const elapsed = Date.now() - etaCalculatedAt;\n        parts.push(`ETA ${formatDuration(Math.max(0, etaMs! - elapsed))}`);\n      }\n      if (line) line += ' ';\n      line += parts.join(' | ');\n    }\n    if (spinnerVisible) {\n      if (line) line += ' ';\n      line += frames[spinnerFrame] ?? '';\n    }\n    if (text) {\n      if (line) line += ' ';\n      line += text;\n    }\n\n    if (line) {\n      clearLines();\n      writeStderr(line);\n      prevLineCount = lineCount(line);\n    } else {\n      clearLines();\n    }\n  };\n\n  const { frames } = spinnerCfg;\n  const needsAnimation = spinnerCfg.show !== 'never' || (barCfg && barCfg.show !== 'never');\n  const tickInterval = barCfg && barCfg.show !== 'never' ? Math.min(80, spinnerCfg.interval) : spinnerCfg.interval;\n\n  const timer = needsAnimation\n    ? setInterval(() => {\n        spinnerFrame = (spinnerFrame + 1) % (frames.length || 1);\n        barFrame++;\n        render();\n      }, tickInterval)\n    : undefined;\n\n  // Prevent the spinner timer from keeping the process alive on uncaught errors\n  if (timer && typeof timer === 'object' && 'unref' in timer) (timer as NodeJS.Timeout).unref();\n\n  render();\n\n  const clear = () => {\n    if (stopped) return;\n    stopped = true;\n    paused = false;\n    if (timer) clearInterval(timer);\n    clearLines();\n  };\n\n  const eta = {\n    start() {\n      if (stopped) return;\n      etaEnabled = true;\n      render();\n    },\n    stop() {\n      if (stopped) return;\n      etaEnabled = false;\n      etaMs = undefined;\n      render();\n    },\n    reset() {\n      if (stopped) return;\n      etaSamples.length = 0;\n      etaMs = undefined;\n      etaCalculatedAt = 0;\n      render();\n    },\n  };\n\n  return {\n    update(value) {\n      if (stopped) return;\n      const parsed = parseUpdate(value);\n      if (parsed.message !== undefined) text = parsed.message;\n      if (parsed.progress !== undefined) {\n        progress = parsed.progress;\n        if (etaEnabled) {\n          const now = Date.now();\n          etaSamples.push({ time: now, progress: parsed.progress });\n          const estimated = estimateEta(etaSamples);\n          if (estimated !== undefined) {\n            etaMs = estimated;\n            etaCalculatedAt = now;\n          }\n        }\n      }\n      if (parsed.indeterminate !== undefined) {\n        indeterminate = parsed.indeterminate;\n        if (indeterminate) progress = undefined;\n      }\n      if (parsed.time !== undefined) {\n        if (parsed.time && !timeEnabled) {\n          timeEnabled = true;\n          startTime = Date.now();\n        } else if (!parsed.time) {\n          timeEnabled = false;\n        }\n      }\n      render();\n    },\n    eta,\n    succeed(msg, opts) {\n      clear();\n      if (msg === null) return;\n      const finalMsg = msg ?? text;\n      const icon = opts?.indicator ?? successIcon;\n      if (finalMsg) writeStderr(formatFinal(icon, finalMsg));\n    },\n    fail(msg, opts) {\n      clear();\n      if (msg === null) return;\n      const finalMsg = msg ?? text;\n      const icon = opts?.indicator ?? errorIcon;\n      if (finalMsg) writeStderr(formatFinal(icon, finalMsg));\n    },\n    stop() {\n      clear();\n    },\n    pause() {\n      if (stopped || paused) return;\n      paused = true;\n      clearLines();\n      writeStdout('\\x1b[2K\\r');\n    },\n    resume() {\n      if (stopped || !paused) return;\n      paused = false;\n      render();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/extension/progress.d.mts

@@ -0,0 +1,76 @@
+import { PadroneBarConfig, PadroneProgress, PadroneSpinnerConfig } from "../core/runtime.mjs";
+import { WithInterceptor } from "../util/type-utils.mjs";
+import { CommandTypesBase } from "../types/command.mjs";
+import { PadroneProgressRenderer } from "./progress-renderer.mjs";
+
+//#region src/extension/progress.d.ts
+/** A progress message value: a plain string, `null` to suppress, or an object with a message and custom indicator icon. */
+type PadroneProgressMessage = string | null | {
+  message?: string | null;
+  indicator?: string;
+};
+/** Per-phase message configuration for progress indicators. */
+type PadroneProgressMessages<TRes = unknown> = {
+  /** Message shown during async validation. Defaults to `''` (spinner only). */validation?: string; /** Message shown while the command's action is running. */
+  progress?: string; /** Message shown when the command succeeds. `null` to suppress. Defaults to the `progress` message. */
+  success?: PadroneProgressMessage | ((result: TRes) => PadroneProgressMessage); /** Message shown when the command fails. `null` to suppress. Defaults to the error message. */
+  error?: PadroneProgressMessage | ((error: unknown) => PadroneProgressMessage);
+};
+/**
+ * Progress indicator configuration with messages, visual options, and renderer.
+ */
+type PadroneProgressConfig<TRes = unknown> = {
+  /** Per-phase messages. A string sets the `progress` message; an object configures individual phases. */message?: string | PadroneProgressMessages<TRes>; /** Spinner configuration. Default `show` is `'auto'` (visible when bar is not shown). `true` forces spinner to always show (even alongside a bar). */
+  spinner?: PadroneSpinnerConfig; /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'`. */
+  bar?: boolean | PadroneBarConfig; /** Show elapsed time since the indicator started. Can also be started on demand via `update({ time: true })`. */
+  time?: boolean; /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. */
+  eta?: boolean;
+  /**
+   * Custom renderer factory. Called to create the progress indicator.
+   * 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;
+};
+/**
+ * Shared progress defaults that can be provided via context instead of repeating
+ * at each call site. Per-instance message fields are excluded — those always come
+ * from the constructor argument.
+ *
+ * Provide via context as `{ progressConfig: PadroneProgressDefaults }`.
+ */
+type PadroneProgressDefaults = Pick<PadroneProgressConfig, 'message' | 'spinner' | 'bar' | 'time' | 'eta' | 'renderer' | 'silent'>;
+/** Builder/program type after applying `padroneProgress()`. Adds `{ progress: PadroneProgress }` to the command context. */
+type WithProgress<T> = WithInterceptor<T, {
+  progress: PadroneProgress;
+}>;
+/**
+ * Extension that adds an auto-managed progress indicator to the command pipeline.
+ *
+ * - `string` — a single message used for all states.
+ * - `PadroneProgressConfig` — separate messages for validation, progress, success, and error.
+ *
+ * The indicator is automatically started before validation, updated at each phase transition,
+ * and stopped on success (`.succeed()`) or failure (`.fail()`).
+ *
+ * Provides `{ progress: PadroneProgress }` on the command context.
+ * Access it in action handlers as `ctx.context.progress`.
+ *
+ * Uses the built-in terminal renderer by default. Pass a custom `renderer` for non-terminal
+ * environments (web UIs, testing, etc).
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .command('sync', (c) =>
+ *     c.extend(padroneProgress('Syncing...'))
+ *       .action((_args, ctx) => {
+ *         ctx.context.progress.update('halfway');
+ *       })
+ *   )
+ * ```
+ */
+declare function padroneProgress<T extends CommandTypesBase>(config?: string | PadroneProgressConfig): (builder: T) => WithProgress<T>;
+//#endregion
+export { PadroneProgressConfig, PadroneProgressDefaults, PadroneProgressMessage, PadroneProgressMessages, WithProgress, padroneProgress };
+//# sourceMappingURL=progress.d.mts.map

package/dist/extension/progress.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.mts","names":[],"sources":["../../src/extension/progress.ts"],"mappings":";;;;;;;KAYY,sBAAA;EAA2C,OAAA;EAAyB,SAAS;AAAA;;KAG7E,uBAAA;EAH6E,8EAKvF,UAAA,WAFiC;EAIjC,QAAA,WAEU;EAAV,OAAA,GAAU,sBAAA,KAA2B,MAAA,EAAQ,IAAA,KAAS,sBAAA,GAAA;EAEtD,KAAA,GAAQ,sBAAA,KAA2B,KAAA,cAAmB,sBAAA;AAAA;;;;KAM5C,qBAAA;EAVV,wGAYA,OAAA,YAAmB,uBAAA,CAAwB,IAAA,GAVjC;EAYV,OAAA,GAAU,oBAAA,EAZ2B;EAcrC,GAAA,aAAgB,gBAAA,EAZhB;EAcA,IAAA,YAdmC;EAgBnC,GAAA;EAhB4E;AAAA;AAM9E;;EAeE,QAAA,GAAW,uBAAA,EAbgC;EAe3C,MAAA;AAAA;;;;;;;;KAUU,uBAAA,GAA0B,IAAI,CAAC,qBAAA;;KAG/B,YAAA,MAAkB,eAAA,CAAgB,CAAA;EAAK,QAAA,EAAU,eAAA;AAAA;;;;;;;AAbrD;AAUR;;;;AAAgE;AAGhE;;;;;;;;;;;;;;iBAyRgB,eAAA,WAA0B,gBAAA,EAAkB,MAAA,YAAkB,qBAAA,IAAyB,OAAA,EAAS,CAAA,KAAM,YAAA,CAAa,CAAA"}