@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/download/index.test.js

@@ -0,0 +1,174 @@
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { detectContentType, exportCookiesToNetscape, formatCookieHeader, httpDownload, requiresYtdlp, resolveRedirectUrl } from './index.js';
+const servers = [];
+const tempDirs = [];
+afterEach(async () => {
+    vi.unstubAllEnvs();
+    await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    })));
+    servers.length = 0;
+    for (const dir of tempDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    tempDirs.length = 0;
+});
+async function startServer(handler, hostname = '127.0.0.1') {
+    const server = http.createServer(handler);
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, hostname, resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Failed to start test server');
+    }
+    return `http://${hostname}:${address.port}`;
+}
+// Windows Defender can briefly lock newly-written .tmp files, causing EPERM.
+// Retry once to handle this flakiness.
+describe('download helpers', { retry: process.platform === 'win32' ? 2 : 0 }, () => {
+    it('resolves relative redirects against the original URL', () => {
+        expect(resolveRedirectUrl('https://example.com/a/file', '/cdn/file.bin')).toBe('https://example.com/cdn/file.bin');
+        expect(resolveRedirectUrl('https://example.com/a/file', '../next')).toBe('https://example.com/next');
+    });
+    it('formats browser cookies into a Cookie header', () => {
+        expect(formatCookieHeader([
+            { name: 'sid', value: 'abc', domain: 'example.com' },
+            { name: 'ct0', value: 'def', domain: 'example.com' },
+        ])).toBe('sid=abc; ct0=def');
+    });
+    it('fails after exceeding the redirect limit', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', '/loop');
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-dl-'));
+        tempDirs.push(tempDir);
+        const destPath = path.join(tempDir, 'file.txt');
+        const result = await httpDownload(`${baseUrl}/loop`, destPath, { maxRedirects: 2 });
+        expect(result).toEqual({
+            success: false,
+            size: 0,
+            error: 'Too many redirects (> 2)',
+        });
+        expect(fs.existsSync(destPath)).toBe(false);
+    });
+    it('does not forward cookies across cross-domain redirects', async () => {
+        let forwardedCookie;
+        const targetUrl = await startServer((req, res) => {
+            forwardedCookie = req.headers.cookie;
+            res.statusCode = 200;
+            res.end('ok');
+        }, 'localhost');
+        const redirectUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', targetUrl);
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-dl-'));
+        tempDirs.push(tempDir);
+        const destPath = path.join(tempDir, 'redirect.txt');
+        const result = await httpDownload(`${redirectUrl}/start`, destPath, { cookies: 'sid=abc' });
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(forwardedCookie).toBeUndefined();
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
+    it('does not forward cookie headers across cross-domain redirects', async () => {
+        let forwardedCookie;
+        const targetUrl = await startServer((req, res) => {
+            forwardedCookie = req.headers.cookie;
+            res.statusCode = 200;
+            res.end('ok');
+        }, 'localhost');
+        const redirectUrl = await startServer((_req, res) => {
+            res.statusCode = 302;
+            res.setHeader('Location', targetUrl);
+            res.end();
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-dl-'));
+        tempDirs.push(tempDir);
+        const destPath = path.join(tempDir, 'redirect-header.txt');
+        const result = await httpDownload(`${redirectUrl}/start`, destPath, {
+            headers: { Cookie: 'sid=header-cookie' },
+        });
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(forwardedCookie).toBeUndefined();
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
+    it('bypasses proxy settings for loopback downloads', async () => {
+        vi.stubEnv('HTTP_PROXY', 'http://127.0.0.1:9');
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('ok');
+        });
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-dl-'));
+        tempDirs.push(tempDir);
+        const destPath = path.join(tempDir, 'loopback.txt');
+        const result = await httpDownload(`${baseUrl}/ok`, destPath);
+        expect(result).toEqual({ success: true, size: 2 });
+        expect(fs.readFileSync(destPath, 'utf8')).toBe('ok');
+    });
+    it.skipIf(process.platform === 'win32')('writes the Netscape cookie file with 0o600 owner-only permissions', async () => {
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-dl-'));
+        tempDirs.push(tempDir);
+        const cookiesPath = path.join(tempDir, 'cookies.txt');
+        exportCookiesToNetscape([
+            { name: 'sid', value: 'secret', domain: 'example.com' },
+        ], cookiesPath);
+        const mode = fs.statSync(cookiesPath).mode & 0o777;
+        expect(mode).toBe(0o600);
+    });
+    it.skipIf(process.platform === 'win32')('tightens an existing Netscape cookie file before rewriting it', async () => {
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-dl-'));
+        tempDirs.push(tempDir);
+        const cookiesPath = path.join(tempDir, 'cookies.txt');
+        fs.writeFileSync(cookiesPath, 'stale-cookie', { mode: 0o644 });
+        exportCookiesToNetscape([
+            { name: 'sid', value: 'secret', domain: 'example.com' },
+        ], cookiesPath);
+        const mode = fs.statSync(cookiesPath).mode & 0o777;
+        expect(mode).toBe(0o600);
+        expect(fs.readFileSync(cookiesPath, 'utf8')).toContain('sid\tsecret');
+    });
+});
+describe('video-platform host detection', () => {
+    it('matches real video-platform hosts (host or subdomain)', () => {
+        for (const url of [
+            'https://www.youtube.com/watch?v=abc',
+            'https://youtu.be/abc',
+            'https://m.bilibili.com/video/BV1xx',
+            'https://twitter.com/u/status/1',
+            'https://x.com/u/status/1',
+            'https://www.tiktok.com/@u/video/1',
+            'https://vimeo.com/12345',
+            'https://www.twitch.tv/u',
+        ]) {
+            expect(requiresYtdlp(url)).toBe(true);
+            expect(detectContentType(url)).toBe('video');
+        }
+    });
+    it('does not match hosts that merely end with a token or carry it in the path', () => {
+        // netflix.com / max.com / phoenix.com all *contain* the substring "x.com";
+        // the path-only token "youtu.be-guide" must not match either.
+        for (const url of [
+            'https://netflix.com/watch/123',
+            'https://www.phoenix.com/a.zip',
+            'https://max.com/movie',
+            'https://cdn.site.com/youtu.be-guide.bin',
+            'https://notx.com/a',
+        ]) {
+            expect(requiresYtdlp(url)).toBe(false);
+            expect(detectContentType(url)).not.toBe('video');
+        }
+    });
+    it('returns false for an unparseable URL instead of throwing', () => {
+        expect(requiresYtdlp('not a url')).toBe(false);
+    });
+});

package/dist/src/download/media-download.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Media download helper — shared logic for batch downloading images/videos.
+ *
+ * Used by: xiaohongshu/download, twitter/download, bilibili/download,
+ * and future media adapters.
+ *
+ * Flow: MediaItem[] → DownloadProgressTracker → httpDownload/ytdlpDownload → results
+ */
+import type { BrowserCookie } from '../types.js';
+export interface MediaItem {
+    type: 'image' | 'video' | 'video-tweet' | 'video-ytdlp';
+    url: string;
+    /** Optional custom filename (without directory) */
+    filename?: string;
+}
+export interface MediaDownloadOptions {
+    output: string;
+    /** Subdirectory inside output */
+    subdir?: string;
+    /** Cookie string for HTTP downloads */
+    cookies?: string;
+    /** Raw browser cookies — auto-exported to Netscape for yt-dlp, auto-cleaned up */
+    browserCookies?: BrowserCookie[];
+    /** Timeout in ms (default: 30000 for images, 60000 for videos) */
+    timeout?: number;
+    /** File name prefix (default: 'download') */
+    filenamePrefix?: string;
+    /** Extra yt-dlp args */
+    ytdlpExtraArgs?: string[];
+    /** Whether to show progress (default: true) */
+    verbose?: boolean;
+}
+export interface MediaDownloadResult {
+    index: number;
+    type: string;
+    status: string;
+    size: string;
+}
+/**
+ * Batch download media files with progress tracking.
+ *
+ * Handles:
+ * - DownloadProgressTracker for terminal UX
+ * - Automatic httpDownload vs ytdlpDownload routing via MediaItem.type
+ * - Cookie export to Netscape format for yt-dlp (auto-cleanup)
+ * - Directory creation
+ * - Error handling with per-file results
+ */
+export declare function downloadMedia(items: MediaItem[], options: MediaDownloadOptions): Promise<MediaDownloadResult[]>;

package/dist/src/download/media-download.js

@@ -0,0 +1,127 @@
+/**
+ * Media download helper — shared logic for batch downloading images/videos.
+ *
+ * Used by: xiaohongshu/download, twitter/download, bilibili/download,
+ * and future media adapters.
+ *
+ * Flow: MediaItem[] → DownloadProgressTracker → httpDownload/ytdlpDownload → results
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getErrorMessage } from '../errors.js';
+import { httpDownload, ytdlpDownload, checkYtdlp, getTempDir, exportCookiesToNetscape, sanitizeFilename, } from './index.js';
+import { DownloadProgressTracker, formatBytes } from './progress.js';
+// ============================================================
+// Main API
+// ============================================================
+/**
+ * Batch download media files with progress tracking.
+ *
+ * Handles:
+ * - DownloadProgressTracker for terminal UX
+ * - Automatic httpDownload vs ytdlpDownload routing via MediaItem.type
+ * - Cookie export to Netscape format for yt-dlp (auto-cleanup)
+ * - Directory creation
+ * - Error handling with per-file results
+ */
+export async function downloadMedia(items, options) {
+    const { output, subdir, cookies, browserCookies, timeout, filenamePrefix = 'download', ytdlpExtraArgs = [], verbose = true, } = options;
+    if (!items || items.length === 0) {
+        return [{ index: 0, type: '-', status: 'failed', size: 'No media found' }];
+    }
+    // Create output directory
+    const outputDir = subdir ? path.join(output, subdir) : output;
+    fs.mkdirSync(outputDir, { recursive: true });
+    // Pre-check yt-dlp availability (once, not per-item)
+    const hasYtdlp = checkYtdlp();
+    // Auto-export browser cookies to Netscape format for yt-dlp
+    let cookiesFile;
+    const needsYtdlp = items.some(m => m.type === 'video-tweet' || m.type === 'video-ytdlp');
+    if (needsYtdlp && browserCookies && browserCookies.length > 0) {
+        const tempDir = getTempDir();
+        fs.mkdirSync(tempDir, { recursive: true });
+        cookiesFile = path.join(tempDir, `media_cookies_${Date.now()}.txt`);
+        exportCookiesToNetscape(browserCookies, cookiesFile);
+    }
+    const tracker = new DownloadProgressTracker(items.length, verbose);
+    const results = [];
+    try {
+        for (let i = 0; i < items.length; i++) {
+            const media = items[i];
+            const isVideo = media.type !== 'image';
+            const ext = isVideo ? 'mp4' : 'jpg';
+            const filename = resolveMediaFilename(media.filename, filenamePrefix, i + 1, ext);
+            const destPath = path.join(outputDir, filename);
+            const progressBar = tracker.onFileStart(filename, i);
+            try {
+                let result;
+                const useYtdlp = (media.type === 'video-tweet' || media.type === 'video-ytdlp') && hasYtdlp;
+                if (useYtdlp) {
+                    result = await ytdlpDownload(media.url, destPath, {
+                        cookiesFile,
+                        extraArgs: ytdlpExtraArgs,
+                        onProgress: (percent) => {
+                            if (progressBar)
+                                progressBar.update(percent, 100);
+                        },
+                    });
+                }
+                else {
+                    // Direct HTTP download for images and direct video URLs
+                    const dlTimeout = timeout || (isVideo ? 60000 : 30000);
+                    result = await httpDownload(media.url, destPath, {
+                        cookies,
+                        timeout: dlTimeout,
+                        onProgress: (received, total) => {
+                            if (progressBar)
+                                progressBar.update(received, total);
+                        },
+                    });
+                }
+                if (progressBar) {
+                    progressBar.complete(result.success, result.success ? formatBytes(result.size) : undefined);
+                }
+                tracker.onFileComplete(result.success);
+                results.push({
+                    index: i + 1,
+                    type: media.type === 'video-tweet' || media.type === 'video-ytdlp' ? 'video' : media.type,
+                    status: result.success ? 'success' : 'failed',
+                    size: result.success ? formatBytes(result.size) : (result.error || 'unknown error'),
+                });
+            }
+            catch (err) {
+                const msg = getErrorMessage(err);
+                if (progressBar)
+                    progressBar.fail(msg);
+                tracker.onFileComplete(false);
+                results.push({
+                    index: i + 1,
+                    type: media.type,
+                    status: 'failed',
+                    size: msg,
+                });
+            }
+        }
+    }
+    finally {
+        tracker.finish();
+        // Auto-cleanup exported cookies file
+        if (cookiesFile && fs.existsSync(cookiesFile)) {
+            fs.unlinkSync(cookiesFile);
+        }
+    }
+    return results;
+}
+function resolveMediaFilename(filename, prefix, index, ext) {
+    const safePrefix = sanitizePathSegment(path.basename(path.win32.basename(prefix))) || 'download';
+    const fallback = `${safePrefix}_${index}.${ext}`;
+    if (!filename)
+        return fallback;
+    const basename = path.basename(path.win32.basename(filename));
+    const safeName = sanitizePathSegment(basename);
+    return safeName || fallback;
+}
+function sanitizePathSegment(value) {
+    const sanitized = sanitizeFilename(value);
+    return sanitized && sanitized !== '.' && sanitized !== '..' ? sanitized : '';
+}

package/dist/src/download/media-download.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/download/media-download.test.js

@@ -0,0 +1,112 @@
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { downloadMedia } from './media-download.js';
+const servers = [];
+const tempDirs = [];
+afterEach(async () => {
+    await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    })));
+    servers.length = 0;
+    for (const dir of tempDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    tempDirs.length = 0;
+});
+async function startServer(handler) {
+    const server = http.createServer(handler);
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Failed to start test server');
+    }
+    return `http://127.0.0.1:${address.port}`;
+}
+// Windows runners occasionally exceed the default 5s timeout on the first
+// http.createServer + downloadMedia roundtrip (cold-start cost on a loaded VM).
+describe('media downloads', { retry: process.platform === 'win32' ? 2 : 0 }, () => {
+    it('keeps custom filenames inside the output directory', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('image');
+        });
+        const parentDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-media-parent-'));
+        tempDirs.push(parentDir);
+        const outputDir = path.join(parentDir, 'downloads');
+        const results = await downloadMedia([
+            { type: 'image', url: `${baseUrl}/image.jpg`, filename: '../escape.jpg' },
+        ], {
+            output: outputDir,
+            verbose: false,
+        });
+        expect(results).toEqual([
+            { index: 1, type: 'image', status: 'success', size: '5.0 B' },
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'escape.jpg'), 'utf8')).toBe('image');
+        expect(fs.existsSync(path.join(parentDir, 'escape.jpg'))).toBe(false);
+    });
+    it('strips nested and absolute path components from custom filenames', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('image');
+        });
+        const parentDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-media-parent-'));
+        tempDirs.push(parentDir);
+        const outputDir = path.join(parentDir, 'downloads');
+        const results = await downloadMedia([
+            { type: 'image', url: `${baseUrl}/one.jpg`, filename: '../../etc/passwd' },
+            { type: 'image', url: `${baseUrl}/two.jpg`, filename: '/tmp/evil.jpg' },
+            { type: 'image', url: `${baseUrl}/three.jpg`, filename: 'nested/path/photo.png' },
+            { type: 'image', url: `${baseUrl}/four.jpg`, filename: '..\\windows\\escape.jpg' },
+        ], {
+            output: outputDir,
+            verbose: false,
+        });
+        expect(results).toEqual([
+            { index: 1, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 2, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 3, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 4, type: 'image', status: 'success', size: '5.0 B' },
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'passwd'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'evil.jpg'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'photo.png'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'escape.jpg'), 'utf8')).toBe('image');
+        expect(fs.existsSync(path.join(parentDir, 'etc', 'passwd'))).toBe(false);
+        expect(fs.existsSync(path.join(parentDir, 'tmp', 'evil.jpg'))).toBe(false);
+    });
+    it('falls back to generated names for empty dot-directory filenames', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('image');
+        });
+        const parentDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-media-parent-'));
+        tempDirs.push(parentDir);
+        const outputDir = path.join(parentDir, 'downloads');
+        const results = await downloadMedia([
+            { type: 'image', url: `${baseUrl}/dot.jpg`, filename: '.' },
+            { type: 'image', url: `${baseUrl}/dotdot.jpg`, filename: '..' },
+            { type: 'image', url: `${baseUrl}/blank.jpg`, filename: '   ' },
+        ], {
+            output: outputDir,
+            filenamePrefix: '../unsafe prefix',
+            verbose: false,
+        });
+        expect(results).toEqual([
+            { index: 1, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 2, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 3, type: 'image', status: 'success', size: '5.0 B' },
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'unsafe_prefix_1.jpg'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'unsafe_prefix_2.jpg'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'unsafe_prefix_3.jpg'), 'utf8')).toBe('image');
+        expect(fs.existsSync(path.join(parentDir, 'unsafe prefix_1.jpg'))).toBe(false);
+    });
+});

package/dist/src/download/progress.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Download progress display: terminal progress bars, status updates.
+ */
+export interface ProgressBar {
+    update(current: number, total: number, label?: string): void;
+    complete(success: boolean, message?: string): void;
+    fail(error: string): void;
+}
+/**
+ * Format bytes as human-readable string (KB, MB, GB).
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format milliseconds as human-readable duration.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Create a simple progress bar for terminal display.
+ */
+export declare function createProgressBar(filename: string, index: number, total: number): ProgressBar;
+/**
+ * Multi-file download progress tracker.
+ */
+export declare class DownloadProgressTracker {
+    private completed;
+    private failed;
+    private skipped;
+    private total;
+    private startTime;
+    private verbose;
+    constructor(total: number, verbose?: boolean);
+    onFileStart(filename: string, index: number): ProgressBar | null;
+    onFileComplete(success: boolean, skipped?: boolean): void;
+    getSummary(): string;
+    finish(): void;
+}

package/dist/src/download/progress.js

@@ -0,0 +1,120 @@
+/**
+ * Download progress display: terminal progress bars, status updates.
+ */
+/**
+ * Format bytes as human-readable string (KB, MB, GB).
+ */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 1)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.min(sizes.length - 1, Math.floor(Math.log(bytes) / Math.log(k)));
+    return `${(bytes / Math.pow(k, i)).toFixed(1)} ${sizes[i]}`;
+}
+/**
+ * Format milliseconds as human-readable duration.
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        const remainingSeconds = seconds % 60;
+        return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+}
+/**
+ * Create a simple progress bar for terminal display.
+ */
+export function createProgressBar(filename, index, total) {
+    const prefix = `[${index + 1}/${total}]`;
+    const truncatedName = filename.length > 40 ? filename.slice(0, 37) + '...' : filename;
+    return {
+        update(current, totalBytes, label) {
+            const percent = clampPercent(totalBytes > 0 ? Math.round((current / totalBytes) * 100) : 0);
+            const bar = createBar(percent);
+            const size = totalBytes > 0 ? formatBytes(totalBytes) : '';
+            const extra = label ? ` ${label}` : '';
+            process.stderr.write(`\r${prefix} ${truncatedName} ${bar} ${percent}% ${size}${extra}`);
+        },
+        complete(success, message) {
+            const icon = success ? '✓' : '✗';
+            const msg = message ? ` ${message}` : '';
+            process.stderr.write(`\r${prefix} ${icon} ${truncatedName}${msg}\n`);
+        },
+        fail(error) {
+            process.stderr.write(`\r${prefix} ✗ ${truncatedName} ${error}\n`);
+        },
+    };
+}
+function clampPercent(percent) {
+    if (!Number.isFinite(percent))
+        return 0;
+    return Math.max(0, Math.min(100, percent));
+}
+/**
+ * Create a progress bar string.
+ */
+function createBar(percent, width = 20) {
+    const filled = Math.round((percent / 100) * width);
+    const empty = width - filled;
+    return '█'.repeat(filled) + '░'.repeat(empty);
+}
+/**
+ * Multi-file download progress tracker.
+ */
+export class DownloadProgressTracker {
+    completed = 0;
+    failed = 0;
+    skipped = 0;
+    total;
+    startTime;
+    verbose;
+    constructor(total, verbose = true) {
+        this.total = total;
+        this.startTime = Date.now();
+        this.verbose = verbose;
+    }
+    onFileStart(filename, index) {
+        if (!this.verbose)
+            return null;
+        return createProgressBar(filename, index, this.total);
+    }
+    onFileComplete(success, skipped = false) {
+        if (skipped) {
+            this.skipped++;
+        }
+        else if (success) {
+            this.completed++;
+        }
+        else {
+            this.failed++;
+        }
+    }
+    getSummary() {
+        const elapsed = formatDuration(Date.now() - this.startTime);
+        const parts = [];
+        if (this.completed > 0) {
+            parts.push(`${this.completed} downloaded`);
+        }
+        if (this.skipped > 0) {
+            parts.push(`${this.skipped} skipped`);
+        }
+        if (this.failed > 0) {
+            parts.push(`${this.failed} failed`);
+        }
+        return `${parts.join(', ')} in ${elapsed}`;
+    }
+    finish() {
+        if (this.verbose) {
+            process.stderr.write(`\nDownload complete: ${this.getSummary()}\n`);
+        }
+    }
+}

package/dist/src/download/progress.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/download/progress.test.js

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createProgressBar, formatBytes } from './progress.js';
+describe('formatBytes', () => {
+    it('returns a stable zero-byte label for invalid or sub-byte values', () => {
+        expect(formatBytes(-1)).toBe('0 B');
+        expect(formatBytes(0.5)).toBe('0 B');
+        expect(formatBytes(Number.NaN)).toBe('0 B');
+        expect(formatBytes(Number.POSITIVE_INFINITY)).toBe('0 B');
+    });
+    it('caps very large values at the largest supported unit', () => {
+        expect(formatBytes(1024 ** 5)).toBe('1024.0 TB');
+    });
+});
+describe('download progress display', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('clamps percentages above 100 to keep the progress bar renderable', () => {
+        const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const progress = createProgressBar('file.bin', 0, 1);
+        expect(() => progress.update(150, 100)).not.toThrow();
+        expect(write).toHaveBeenCalledWith(expect.stringContaining('100%'));
+    });
+    it('clamps negative percentages to zero', () => {
+        const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const progress = createProgressBar('file.bin', 0, 1);
+        expect(() => progress.update(-10, 100)).not.toThrow();
+        expect(write).toHaveBeenCalledWith(expect.stringContaining('0%'));
+    });
+    it('renders zero percent when the total size is unknown', () => {
+        const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const progress = createProgressBar('file.bin', 0, 1);
+        expect(() => progress.update(50, 0)).not.toThrow();
+        expect(write).toHaveBeenCalledWith(expect.stringContaining('0%'));
+    });
+});