@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/utils/progress.js

@@ -1,469 +1,469 @@
-import chalk from 'chalk';
-
-/**
- * Comprehensive progress tracker for multi-step operations with sub-progress.
- *
- * Features:
- * - Multiple step tracking
- * - Progress bars for individual steps
- * - Nested progress (e.g., batches within a step)
- * - Time tracking
- * - Dynamic message updates
- *
- * @example
- * const progress = new ProgressTracker('Pull Operation');
- * progress.addStep('auth', 'Authenticating...');
- * progress.addStep('download', 'Downloading files...');
- * progress.addStep('process', 'Processing files...');
- *
- * progress.start();
- * progress.startStep('auth');
- * // ... do auth work
- * progress.completeStep('auth', 'Authenticated');
- *
- * progress.startStep('download');
- * progress.updateProgress('download', 0, 100);
- * // ... download files
- * progress.updateProgress('download', 50, 100);
- * progress.completeStep('download', 'Downloaded 100 files');
- *
- * progress.finish();
- */
-export class ProgressTracker {
-    constructor(title = 'Operation') {
-        this.title = title;
-        this.steps = new Map();
-        this.currentStep = null;
-        this.startTime = null;
-        this.spinnerChars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-        this.spinnerIndex = 0;
-        this.interval = null;
-        this.lastRenderLength = 0;
-        this.isFinished = false;
-        this.issues = [];  // Collected issues/warnings to display at end
-    }
-
-    /**
-     * Add a step to track
-     * @param {string} id - Unique identifier for the step
-     * @param {string} label - Display label for the step
-     * @param {object} options - Optional configuration
-     * @param {boolean} options.hasProgress - Whether this step has progress (0-100%)
-     */
-    addStep(id, label, options = {}) {
-        this.steps.set(id, {
-            id,
-            label,
-            status: 'pending', // pending, active, completed, failed
-            hasProgress: options.hasProgress || false,
-            progress: { current: 0, total: 100 },
-            message: '',
-            startTime: null,
-            endTime: null,
-            error: null
-        });
-    }
-
-    /**
-     * Start the progress tracker
-     */
-    start() {
-        this.startTime = Date.now();
-        this.isFinished = false;
-        this.render();
-        this.startSpinner();
-    }
-
-    /**
-     * Start a specific step
-     * @param {string} id - Step identifier
-     * @param {string} message - Optional custom message
-     */
-    startStep(id, message = '') {
-        const step = this.steps.get(id);
-        if (!step) {
-            throw new Error(`Step '${id}' not found`);
-        }
-
-        // Complete previous step if any
-        if (this.currentStep && this.steps.get(this.currentStep).status === 'active') {
-            this.completeStep(this.currentStep);
-        }
-
-        step.status = 'active';
-        step.startTime = Date.now();
-        step.message = message || step.label;
-        this.currentStep = id;
-        this.render();
-    }
-
-    /**
-     * Update progress for a step
-     * @param {string} id - Step identifier
-     * @param {number} current - Current progress value
-     * @param {number} total - Total progress value
-     * @param {string} message - Optional message to display
-     */
-    updateProgress(id, current, total, message = '') {
-        const step = this.steps.get(id);
-        if (!step) return;
-
-        step.progress.current = current;
-        step.progress.total = total;
-        if (message) {
-            step.message = message;
-        }
-        this.render();
-    }
-
-    /**
-     * Complete a step
-     * @param {string} id - Step identifier
-     * @param {string} message - Optional completion message
-     */
-    completeStep(id, message = '') {
-        const step = this.steps.get(id);
-        if (!step) return;
-
-        step.status = 'completed';
-        step.endTime = Date.now();
-        if (message) {
-            step.message = message;
-        }
-        this.render();
-    }
-
-    /**
-     * Mark a step as failed
-     * @param {string} id - Step identifier
-     * @param {string} error - Error message
-     */
-    failStep(id, error) {
-        const step = this.steps.get(id);
-        if (!step) return;
-
-        step.status = 'failed';
-        step.endTime = Date.now();
-        step.error = error;
-        this.render();
-    }
-
-    /**
-     * Add an issue/warning to be displayed at the end
-     * @param {string} type - 'error' | 'warning' | 'info'
-     * @param {string} message - The issue message
-     * @param {string} [hint] - Optional hint for resolution
-     */
-    addIssue(type, message, hint = null) {
-        this.issues.push({ type, message, hint });
-    }
-
-    /**
-     * Check if there are any issues collected
-     * @returns {boolean}
-     */
-    hasIssues() {
-        return this.issues.length > 0;
-    }
-
-    /**
-     * Get issues by type
-     * @param {string} type - 'error' | 'warning' | 'info'
-     * @returns {Array}
-     */
-    getIssues(type = null) {
-        if (type) {
-            return this.issues.filter(i => i.type === type);
-        }
-        return this.issues;
-    }
-
-    /**
-     * Update the message for the current step
-     * @param {string} message - New message
-     */
-    updateMessage(message) {
-        if (!this.currentStep) return;
-        const step = this.steps.get(this.currentStep);
-        if (step) {
-            step.message = message;
-            this.render();
-        }
-    }
-
-    /**
-     * Render the progress display
-     */
-    render() {
-        if (this.isFinished) return;
-
-        // Clear previous render
-        if (this.lastRenderLength > 0) {
-            for (let i = 0; i < this.lastRenderLength; i++) {
-                process.stdout.write('\x1B[1A\x1B[2K'); // Move up and clear line
-            }
-        }
-
-        const lines = [];
-
-        // Title with elapsed time
-        const elapsed = this.formatDuration(Date.now() - this.startTime);
-        lines.push(chalk.bold.blue(`\n${this.title}`) + chalk.gray(` (${elapsed})`));
-        lines.push('');
-
-        // Render each step
-        for (const [id, step] of this.steps) {
-            const prefix = this.getStepPrefix(step);
-            const label = step.status === 'active'
-                ? chalk.cyan(step.label)
-                : step.status === 'completed'
-                ? chalk.gray(step.label)
-                : step.status === 'failed'
-                ? chalk.red(step.label)
-                : chalk.gray(step.label);
-
-            let line = `${prefix} ${label}`;
-
-            // Add progress bar if applicable
-            if (step.hasProgress && step.status === 'active' && step.progress.total > 0) {
-                const percentage = Math.floor((step.progress.current / step.progress.total) * 100);
-                const progressBar = this.renderProgressBar(percentage);
-                line += ` ${progressBar} ${percentage}%`;
-            }
-
-            // Add message or duration
-            if (step.message && step.status === 'active') {
-                line += chalk.gray(` - ${step.message}`);
-            } else if (step.status === 'completed' && step.endTime && step.startTime) {
-                const duration = this.formatDuration(step.endTime - step.startTime);
-                line += chalk.gray(` (${duration})`);
-                if (step.message) {
-                    line += chalk.gray(` - ${step.message}`);
-                }
-            } else if (step.status === 'failed' && step.error) {
-                line += chalk.red(` - ${step.error}`);
-            }
-
-            lines.push(line);
-        }
-
-        lines.push(''); // Empty line at the end
-
-        this.lastRenderLength = lines.length;
-        process.stdout.write(lines.join('\n'));
-    }
-
-    /**
-     * Get the prefix icon for a step
-     */
-    getStepPrefix(step) {
-        switch (step.status) {
-            case 'pending':
-                return chalk.gray('◯');
-            case 'active':
-                return chalk.cyan(this.spinnerChars[this.spinnerIndex]);
-            case 'completed':
-                return chalk.green('✓');
-            case 'failed':
-                return chalk.red('✗');
-            default:
-                return chalk.gray('◯');
-        }
-    }
-
-    /**
-     * Render a progress bar
-     * @param {number} percentage - Progress percentage (0-100)
-     */
-    renderProgressBar(percentage) {
-        const width = 20;
-        // Clamp percentage between 0 and 100 to prevent negative values
-        const clampedPercentage = Math.max(0, Math.min(100, percentage));
-        const filled = Math.floor((clampedPercentage / 100) * width);
-        const empty = width - filled;
-
-        const bar = chalk.cyan('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
-        return `[${bar}]`;
-    }
-
-    /**
-     * Format duration in ms to human readable format
-     */
-    formatDuration(ms) {
-        if (ms < 1000) return `${ms}ms`;
-        if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-        const minutes = Math.floor(ms / 60000);
-        const seconds = Math.floor((ms % 60000) / 1000);
-        return `${minutes}m ${seconds}s`;
-    }
-
-    /**
-     * Start the spinner animation
-     */
-    startSpinner() {
-        this.interval = setInterval(() => {
-            this.spinnerIndex = (this.spinnerIndex + 1) % this.spinnerChars.length;
-            this.render();
-        }, 80);
-    }
-
-    /**
-     * Stop the spinner animation
-     */
-    stopSpinner() {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-    }
-
-    /**
-     * Finish the progress tracker
-     * @param {string} message - Optional final message
-     * @param {object} options - Optional configuration
-     * @param {boolean} options.showIssues - Whether to show collected issues (default: false)
-     */
-    finish(message = '', options = {}) {
-        const { showIssues = false } = options;
-
-        this.stopSpinner();
-        this.isFinished = true;
-
-        // Complete any active steps
-        if (this.currentStep && this.steps.get(this.currentStep).status === 'active') {
-            this.completeStep(this.currentStep);
-        }
-
-        this.render();
-
-        // Print summary
-        const totalTime = this.formatDuration(Date.now() - this.startTime);
-        const completed = Array.from(this.steps.values()).filter(s => s.status === 'completed').length;
-        const failed = Array.from(this.steps.values()).filter(s => s.status === 'failed').length;
-
-        if (message) {
-            console.log(chalk.bold.green(`\n${message}`));
-        }
-
-        console.log(chalk.gray(`Total time: ${totalTime}`));
-
-        if (failed > 0) {
-            console.log(chalk.red(`✗ ${failed} step(s) failed`));
-        } else {
-            console.log(chalk.green(`✓ All ${completed} step(s) completed successfully`));
-        }
-        console.log('');
-
-        // Only display collected issues if explicitly requested
-        if (showIssues && this.issues.length > 0) {
-            this.displayIssues();
-        }
-    }
-
-    /**
-     * Display collected issues
-     * Can be called manually after finish() if needed
-     */
-    displayIssues() {
-        if (this.issues.length === 0) return;
-
-        const errors = this.issues.filter(i => i.type === 'error');
-        const warnings = this.issues.filter(i => i.type === 'warning');
-        const infos = this.issues.filter(i => i.type === 'info');
-
-        console.log(chalk.bold('Issues Summary:'));
-
-        if (errors.length > 0) {
-            console.log(chalk.red(`  ✗ ${errors.length} error(s)`));
-            errors.forEach((issue, i) => {
-                console.log(chalk.red(`    ${i + 1}. ${issue.message}`));
-                if (issue.hint) {
-                    console.log(chalk.yellow(`       ${issue.hint}`));
-                }
-            });
-        }
-
-        if (warnings.length > 0) {
-            console.log(chalk.yellow(`  ⚠ ${warnings.length} warning(s)`));
-            warnings.forEach((issue, i) => {
-                console.log(chalk.yellow(`    ${i + 1}. ${issue.message}`));
-                if (issue.hint) {
-                    console.log(chalk.gray(`       ${issue.hint}`));
-                }
-            });
-        }
-
-        if (infos.length > 0) {
-            console.log(chalk.cyan(`  ℹ ${infos.length} info(s)`));
-            infos.forEach((issue, i) => {
-                console.log(chalk.cyan(`    ${i + 1}. ${issue.message}`));
-                if (issue.hint) {
-                    console.log(chalk.gray(`       ${issue.hint}`));
-                }
-            });
-        }
-
-        console.log('');
-    }
-
-    /**
-     * Abort the progress tracker with an error
-     * @param {string} error - Error message
-     */
-    abort(error) {
-        this.stopSpinner();
-        this.isFinished = true;
-
-        if (this.currentStep) {
-            this.failStep(this.currentStep, error);
-        }
-
-        this.render();
-        console.log(chalk.bold.red(`\n✗ ${error}\n`));
-    }
-}
-
-/**
- * Helper function to create and use a simple progress tracker
- * @param {string} title - Title of the operation
- * @param {Array} steps - Array of step definitions
- * @param {Function} fn - Async function that receives the progress tracker
- * @returns {Promise} Result of the function
- *
- * @example
- * await withProgress('Pull Operation', [
- *   { id: 'auth', label: 'Authenticating...' },
- *   { id: 'download', label: 'Downloading files...', hasProgress: true },
- *   { id: 'process', label: 'Processing files...' }
- * ], async (progress) => {
- *   progress.startStep('auth');
- *   await authenticate();
- *   progress.completeStep('auth');
- *
- *   progress.startStep('download');
- *   for (let i = 0; i <= 100; i += 10) {
- *     progress.updateProgress('download', i, 100);
- *     await downloadBatch(i);
- *   }
- *   progress.completeStep('download');
- * });
- */
-export async function withProgress(title, steps, fn) {
-    const progress = new ProgressTracker(title);
-
-    // Add all steps
-    for (const step of steps) {
-        progress.addStep(step.id, step.label, step);
-    }
-
-    progress.start();
-
-    try {
-        const result = await fn(progress);
-        progress.finish();
-        return result;
-    } catch (error) {
-        progress.abort(error.message);
-        throw error;
-    }
-}
+import chalk from 'chalk';
+
+/**
+ * Comprehensive progress tracker for multi-step operations with sub-progress.
+ *
+ * Features:
+ * - Multiple step tracking
+ * - Progress bars for individual steps
+ * - Nested progress (e.g., batches within a step)
+ * - Time tracking
+ * - Dynamic message updates
+ *
+ * @example
+ * const progress = new ProgressTracker('Pull Operation');
+ * progress.addStep('auth', 'Authenticating...');
+ * progress.addStep('download', 'Downloading files...');
+ * progress.addStep('process', 'Processing files...');
+ *
+ * progress.start();
+ * progress.startStep('auth');
+ * // ... do auth work
+ * progress.completeStep('auth', 'Authenticated');
+ *
+ * progress.startStep('download');
+ * progress.updateProgress('download', 0, 100);
+ * // ... download files
+ * progress.updateProgress('download', 50, 100);
+ * progress.completeStep('download', 'Downloaded 100 files');
+ *
+ * progress.finish();
+ */
+export class ProgressTracker {
+    constructor(title = 'Operation') {
+        this.title = title;
+        this.steps = new Map();
+        this.currentStep = null;
+        this.startTime = null;
+        this.spinnerChars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+        this.spinnerIndex = 0;
+        this.interval = null;
+        this.lastRenderLength = 0;
+        this.isFinished = false;
+        this.issues = [];  // Collected issues/warnings to display at end
+    }
+
+    /**
+     * Add a step to track
+     * @param {string} id - Unique identifier for the step
+     * @param {string} label - Display label for the step
+     * @param {object} options - Optional configuration
+     * @param {boolean} options.hasProgress - Whether this step has progress (0-100%)
+     */
+    addStep(id, label, options = {}) {
+        this.steps.set(id, {
+            id,
+            label,
+            status: 'pending', // pending, active, completed, failed
+            hasProgress: options.hasProgress || false,
+            progress: { current: 0, total: 100 },
+            message: '',
+            startTime: null,
+            endTime: null,
+            error: null
+        });
+    }
+
+    /**
+     * Start the progress tracker
+     */
+    start() {
+        this.startTime = Date.now();
+        this.isFinished = false;
+        this.render();
+        this.startSpinner();
+    }
+
+    /**
+     * Start a specific step
+     * @param {string} id - Step identifier
+     * @param {string} message - Optional custom message
+     */
+    startStep(id, message = '') {
+        const step = this.steps.get(id);
+        if (!step) {
+            throw new Error(`Step '${id}' not found`);
+        }
+
+        // Complete previous step if any
+        if (this.currentStep && this.steps.get(this.currentStep).status === 'active') {
+            this.completeStep(this.currentStep);
+        }
+
+        step.status = 'active';
+        step.startTime = Date.now();
+        step.message = message || step.label;
+        this.currentStep = id;
+        this.render();
+    }
+
+    /**
+     * Update progress for a step
+     * @param {string} id - Step identifier
+     * @param {number} current - Current progress value
+     * @param {number} total - Total progress value
+     * @param {string} message - Optional message to display
+     */
+    updateProgress(id, current, total, message = '') {
+        const step = this.steps.get(id);
+        if (!step) return;
+
+        step.progress.current = current;
+        step.progress.total = total;
+        if (message) {
+            step.message = message;
+        }
+        this.render();
+    }
+
+    /**
+     * Complete a step
+     * @param {string} id - Step identifier
+     * @param {string} message - Optional completion message
+     */
+    completeStep(id, message = '') {
+        const step = this.steps.get(id);
+        if (!step) return;
+
+        step.status = 'completed';
+        step.endTime = Date.now();
+        if (message) {
+            step.message = message;
+        }
+        this.render();
+    }
+
+    /**
+     * Mark a step as failed
+     * @param {string} id - Step identifier
+     * @param {string} error - Error message
+     */
+    failStep(id, error) {
+        const step = this.steps.get(id);
+        if (!step) return;
+
+        step.status = 'failed';
+        step.endTime = Date.now();
+        step.error = error;
+        this.render();
+    }
+
+    /**
+     * Add an issue/warning to be displayed at the end
+     * @param {string} type - 'error' | 'warning' | 'info'
+     * @param {string} message - The issue message
+     * @param {string} [hint] - Optional hint for resolution
+     */
+    addIssue(type, message, hint = null) {
+        this.issues.push({ type, message, hint });
+    }
+
+    /**
+     * Check if there are any issues collected
+     * @returns {boolean}
+     */
+    hasIssues() {
+        return this.issues.length > 0;
+    }
+
+    /**
+     * Get issues by type
+     * @param {string} type - 'error' | 'warning' | 'info'
+     * @returns {Array}
+     */
+    getIssues(type = null) {
+        if (type) {
+            return this.issues.filter(i => i.type === type);
+        }
+        return this.issues;
+    }
+
+    /**
+     * Update the message for the current step
+     * @param {string} message - New message
+     */
+    updateMessage(message) {
+        if (!this.currentStep) return;
+        const step = this.steps.get(this.currentStep);
+        if (step) {
+            step.message = message;
+            this.render();
+        }
+    }
+
+    /**
+     * Render the progress display
+     */
+    render() {
+        if (this.isFinished) return;
+
+        // Clear previous render
+        if (this.lastRenderLength > 0) {
+            for (let i = 0; i < this.lastRenderLength; i++) {
+                process.stdout.write('\x1B[1A\x1B[2K'); // Move up and clear line
+            }
+        }
+
+        const lines = [];
+
+        // Title with elapsed time
+        const elapsed = this.formatDuration(Date.now() - this.startTime);
+        lines.push(chalk.bold.blue(`\n${this.title}`) + chalk.gray(` (${elapsed})`));
+        lines.push('');
+
+        // Render each step
+        for (const [id, step] of this.steps) {
+            const prefix = this.getStepPrefix(step);
+            const label = step.status === 'active'
+                ? chalk.cyan(step.label)
+                : step.status === 'completed'
+                ? chalk.gray(step.label)
+                : step.status === 'failed'
+                ? chalk.red(step.label)
+                : chalk.gray(step.label);
+
+            let line = `${prefix} ${label}`;
+
+            // Add progress bar if applicable
+            if (step.hasProgress && step.status === 'active' && step.progress.total > 0) {
+                const percentage = Math.floor((step.progress.current / step.progress.total) * 100);
+                const progressBar = this.renderProgressBar(percentage);
+                line += ` ${progressBar} ${percentage}%`;
+            }
+
+            // Add message or duration
+            if (step.message && step.status === 'active') {
+                line += chalk.gray(` - ${step.message}`);
+            } else if (step.status === 'completed' && step.endTime && step.startTime) {
+                const duration = this.formatDuration(step.endTime - step.startTime);
+                line += chalk.gray(` (${duration})`);
+                if (step.message) {
+                    line += chalk.gray(` - ${step.message}`);
+                }
+            } else if (step.status === 'failed' && step.error) {
+                line += chalk.red(` - ${step.error}`);
+            }
+
+            lines.push(line);
+        }
+
+        lines.push(''); // Empty line at the end
+
+        this.lastRenderLength = lines.length;
+        process.stdout.write(lines.join('\n'));
+    }
+
+    /**
+     * Get the prefix icon for a step
+     */
+    getStepPrefix(step) {
+        switch (step.status) {
+            case 'pending':
+                return chalk.gray('◯');
+            case 'active':
+                return chalk.cyan(this.spinnerChars[this.spinnerIndex]);
+            case 'completed':
+                return chalk.green('✓');
+            case 'failed':
+                return chalk.red('✗');
+            default:
+                return chalk.gray('◯');
+        }
+    }
+
+    /**
+     * Render a progress bar
+     * @param {number} percentage - Progress percentage (0-100)
+     */
+    renderProgressBar(percentage) {
+        const width = 20;
+        // Clamp percentage between 0 and 100 to prevent negative values
+        const clampedPercentage = Math.max(0, Math.min(100, percentage));
+        const filled = Math.floor((clampedPercentage / 100) * width);
+        const empty = width - filled;
+
+        const bar = chalk.cyan('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
+        return `[${bar}]`;
+    }
+
+    /**
+     * Format duration in ms to human readable format
+     */
+    formatDuration(ms) {
+        if (ms < 1000) return `${ms}ms`;
+        if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+        const minutes = Math.floor(ms / 60000);
+        const seconds = Math.floor((ms % 60000) / 1000);
+        return `${minutes}m ${seconds}s`;
+    }
+
+    /**
+     * Start the spinner animation
+     */
+    startSpinner() {
+        this.interval = setInterval(() => {
+            this.spinnerIndex = (this.spinnerIndex + 1) % this.spinnerChars.length;
+            this.render();
+        }, 80);
+    }
+
+    /**
+     * Stop the spinner animation
+     */
+    stopSpinner() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+    }
+
+    /**
+     * Finish the progress tracker
+     * @param {string} message - Optional final message
+     * @param {object} options - Optional configuration
+     * @param {boolean} options.showIssues - Whether to show collected issues (default: false)
+     */
+    finish(message = '', options = {}) {
+        const { showIssues = false } = options;
+
+        this.stopSpinner();
+        this.isFinished = true;
+
+        // Complete any active steps
+        if (this.currentStep && this.steps.get(this.currentStep).status === 'active') {
+            this.completeStep(this.currentStep);
+        }
+
+        this.render();
+
+        // Print summary
+        const totalTime = this.formatDuration(Date.now() - this.startTime);
+        const completed = Array.from(this.steps.values()).filter(s => s.status === 'completed').length;
+        const failed = Array.from(this.steps.values()).filter(s => s.status === 'failed').length;
+
+        if (message) {
+            console.log(chalk.bold.green(`\n${message}`));
+        }
+
+        console.log(chalk.gray(`Total time: ${totalTime}`));
+
+        if (failed > 0) {
+            console.log(chalk.red(`✗ ${failed} step(s) failed`));
+        } else {
+            console.log(chalk.green(`✓ All ${completed} step(s) completed successfully`));
+        }
+        console.log('');
+
+        // Only display collected issues if explicitly requested
+        if (showIssues && this.issues.length > 0) {
+            this.displayIssues();
+        }
+    }
+
+    /**
+     * Display collected issues
+     * Can be called manually after finish() if needed
+     */
+    displayIssues() {
+        if (this.issues.length === 0) return;
+
+        const errors = this.issues.filter(i => i.type === 'error');
+        const warnings = this.issues.filter(i => i.type === 'warning');
+        const infos = this.issues.filter(i => i.type === 'info');
+
+        console.log(chalk.bold('Issues Summary:'));
+
+        if (errors.length > 0) {
+            console.log(chalk.red(`  ✗ ${errors.length} error(s)`));
+            errors.forEach((issue, i) => {
+                console.log(chalk.red(`    ${i + 1}. ${issue.message}`));
+                if (issue.hint) {
+                    console.log(chalk.yellow(`       ${issue.hint}`));
+                }
+            });
+        }
+
+        if (warnings.length > 0) {
+            console.log(chalk.yellow(`  ⚠ ${warnings.length} warning(s)`));
+            warnings.forEach((issue, i) => {
+                console.log(chalk.yellow(`    ${i + 1}. ${issue.message}`));
+                if (issue.hint) {
+                    console.log(chalk.gray(`       ${issue.hint}`));
+                }
+            });
+        }
+
+        if (infos.length > 0) {
+            console.log(chalk.cyan(`  ℹ ${infos.length} info(s)`));
+            infos.forEach((issue, i) => {
+                console.log(chalk.cyan(`    ${i + 1}. ${issue.message}`));
+                if (issue.hint) {
+                    console.log(chalk.gray(`       ${issue.hint}`));
+                }
+            });
+        }
+
+        console.log('');
+    }
+
+    /**
+     * Abort the progress tracker with an error
+     * @param {string} error - Error message
+     */
+    abort(error) {
+        this.stopSpinner();
+        this.isFinished = true;
+
+        if (this.currentStep) {
+            this.failStep(this.currentStep, error);
+        }
+
+        this.render();
+        console.log(chalk.bold.red(`\n✗ ${error}\n`));
+    }
+}
+
+/**
+ * Helper function to create and use a simple progress tracker
+ * @param {string} title - Title of the operation
+ * @param {Array} steps - Array of step definitions
+ * @param {Function} fn - Async function that receives the progress tracker
+ * @returns {Promise} Result of the function
+ *
+ * @example
+ * await withProgress('Pull Operation', [
+ *   { id: 'auth', label: 'Authenticating...' },
+ *   { id: 'download', label: 'Downloading files...', hasProgress: true },
+ *   { id: 'process', label: 'Processing files...' }
+ * ], async (progress) => {
+ *   progress.startStep('auth');
+ *   await authenticate();
+ *   progress.completeStep('auth');
+ *
+ *   progress.startStep('download');
+ *   for (let i = 0; i <= 100; i += 10) {
+ *     progress.updateProgress('download', i, 100);
+ *     await downloadBatch(i);
+ *   }
+ *   progress.completeStep('download');
+ * });
+ */
+export async function withProgress(title, steps, fn) {
+    const progress = new ProgressTracker(title);
+
+    // Add all steps
+    for (const step of steps) {
+        progress.addStep(step.id, step.label, step);
+    }
+
+    progress.start();
+
+    try {
+        const result = await fn(progress);
+        progress.finish();
+        return result;
+    } catch (error) {
+        progress.abort(error.message);
+        throw error;
+    }
+}