@agentrhq/webcmd 0.1.1 → 0.1.2

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

@@ -0,0 +1,235 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { downloadArticle } from './article-download.js';
+const tempDirs = [];
+afterEach(() => {
+    for (const dir of tempDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors in tests.
+        }
+    }
+    tempDirs.length = 0;
+});
+async function runAndRead(contentHtml, opts = {}) {
+    const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-article-'));
+    tempDirs.push(tempDir);
+    const result = await downloadArticle({
+        title: 'Test Article',
+        contentHtml,
+    }, {
+        output: tempDir,
+        downloadImages: false,
+        ...(opts.cleanSelectors && { cleanSelectors: opts.cleanSelectors }),
+    });
+    expect(result[0].status).toBe('success');
+    return fs.readFileSync(result[0].saved, 'utf8');
+}
+describe('downloadArticle', () => {
+    it('returns the saved markdown file path on success', async () => {
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-article-'));
+        tempDirs.push(tempDir);
+        const result = await downloadArticle({
+            title: 'Test Article',
+            author: 'Author',
+            publishTime: '2026-04-20 12:00:00',
+            sourceUrl: 'https://example.com/article',
+            contentHtml: '<p>Hello world</p>',
+        }, {
+            output: tempDir,
+            downloadImages: false,
+        });
+        expect(result).toHaveLength(1);
+        expect(result[0].status).toBe('success');
+        expect(result[0].saved).toMatch(new RegExp(`^${tempDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+        expect(path.extname(result[0].saved)).toBe('.md');
+        expect(fs.existsSync(result[0].saved)).toBe(true);
+        expect(fs.readFileSync(result[0].saved, 'utf8')).toContain('Hello world');
+    });
+    describe('markdown pipeline', () => {
+        it('converts GFM tables', async () => {
+            const md = await runAndRead('<table><thead><tr><th>a</th><th>b</th></tr></thead>' +
+                '<tbody><tr><td>1</td><td>2</td></tr></tbody></table>');
+            expect(md).toMatch(/\|\s*a\s*\|\s*b\s*\|/);
+            expect(md).toMatch(/\|\s*---\s*\|\s*---\s*\|/);
+            expect(md).toMatch(/\|\s*1\s*\|\s*2\s*\|/);
+        });
+        it('converts strikethrough and task lists', async () => {
+            const md = await runAndRead('<p><del>gone</del></p>' +
+                '<ul><li><input type="checkbox" checked>done</li><li><input type="checkbox">todo</li></ul>');
+            expect(md).toContain('~~gone~~');
+            expect(md).toContain('[x] done');
+            expect(md).toContain('[ ] todo');
+        });
+        it('strips script / style / noscript / form but keeps iframe as a link', async () => {
+            const md = await runAndRead('<p>keep</p>' +
+                '<script>alert(1)</script>' +
+                '<style>.x{color:red}</style>' +
+                '<noscript>nojs</noscript>' +
+                '<iframe src="https://www.youtube.com/embed/abc" title="Demo video"></iframe>' +
+                '<form><button>click</button></form>');
+            expect(md).toContain('keep');
+            expect(md).not.toContain('alert');
+            expect(md).not.toContain('color:red');
+            expect(md).not.toContain('nojs');
+            expect(md).not.toContain('click');
+            // Iframe degrades to a link preserving the embedded URL.
+            expect(md).toContain('[Demo video](https://www.youtube.com/embed/abc)');
+        });
+        it('strips SVG nodes entirely', async () => {
+            const md = await runAndRead('<p>before</p><svg><circle cx="5" cy="5" r="4"/></svg><p>after</p>');
+            expect(md).toContain('before');
+            expect(md).toContain('after');
+            expect(md).not.toContain('svg');
+            expect(md).not.toContain('circle');
+        });
+        it('drops base64 data URI images but keeps regular images', async () => {
+            const md = await runAndRead('<p><img alt="inline" src="data:image/png;base64,iVBORw0KGgo="></p>' +
+                '<p><img alt="keep" src="https://example.com/a.jpg"></p>');
+            expect(md).not.toContain('data:image');
+            expect(md).toContain('![keep](https://example.com/a.jpg)');
+        });
+        it('collapses 3+ blank lines and strips lone bullet / middle-dot residue', async () => {
+            const md = await runAndRead('<p>top</p>' +
+                '<p>-</p>' +
+                '<p>·</p>' +
+                '<p>bottom</p>');
+            expect(md).not.toMatch(/\n{3,}/);
+            expect(md).not.toMatch(/^\s*-\s*$/m);
+            expect(md).not.toMatch(/^\s*·\s*$/m);
+            expect(md).toContain('top');
+            expect(md).toContain('bottom');
+        });
+        it('strips page chrome (header / footer / nav / aside)', async () => {
+            const md = await runAndRead('<header><p>page-header-text</p></header>' +
+                '<nav><a href="/">home-link</a></nav>' +
+                '<p>article-body</p>' +
+                '<aside><p>sidebar-text</p></aside>' +
+                '<footer><p>page-footer-text</p></footer>');
+            expect(md).toContain('article-body');
+            expect(md).not.toContain('page-header-text');
+            expect(md).not.toContain('home-link');
+            expect(md).not.toContain('sidebar-text');
+            expect(md).not.toContain('page-footer-text');
+        });
+        it('cleanSelectors removes matching nodes before conversion', async () => {
+            const md = await runAndRead('<p>keep-me</p>' +
+                '<div class="vote-card">折叠卡</div>' +
+                '<section class="reward-panel">赞赏栏</section>' +
+                '<p>also-keep</p>', { cleanSelectors: ['.vote-card', '.reward-panel'] });
+            expect(md).toContain('keep-me');
+            expect(md).toContain('also-keep');
+            expect(md).not.toContain('折叠卡');
+            expect(md).not.toContain('赞赏栏');
+        });
+        it('cleanSelectors silently ignores invalid selectors', async () => {
+            const md = await runAndRead('<p>survives</p><div class="x">and-this-too</div>', { cleanSelectors: ['!!!not-a-valid-selector', '.missing'] });
+            expect(md).toContain('survives');
+            expect(md).toContain('and-this-too');
+        });
+        it('cleanSelectors keeps valid selectors active when one selector is invalid', async () => {
+            const md = await runAndRead('<p>keep</p><div class="vote-card">strip-me</div><p>also-keep</p>', { cleanSelectors: ['!!!not-a-valid-selector', '.vote-card'] });
+            expect(md).toContain('keep');
+            expect(md).toContain('also-keep');
+            expect(md).not.toContain('strip-me');
+        });
+        it('preserves <video> as inline HTML with src + poster', async () => {
+            const md = await runAndRead('<p>before</p>' +
+                '<video src="https://cdn.example.com/clip.mp4" poster="https://cdn.example.com/poster.jpg"></video>' +
+                '<p>after</p>');
+            expect(md).toContain('<video src="https://cdn.example.com/clip.mp4" controls poster="https://cdn.example.com/poster.jpg"></video>');
+            expect(md).toContain('before');
+            expect(md).toContain('after');
+        });
+        it('falls back to <source> inside <video> when src attribute is absent', async () => {
+            const md = await runAndRead('<video><source src="https://cdn.example.com/clip.mp4" type="video/mp4"></video>');
+            expect(md).toContain('<video src="https://cdn.example.com/clip.mp4" controls></video>');
+        });
+        it('drops <video> with no src and no <source>', async () => {
+            const md = await runAndRead('<p>before</p><video></video><p>after</p>');
+            expect(md).not.toContain('<video');
+            expect(md).toContain('before');
+            expect(md).toContain('after');
+        });
+        it('preserves <audio> as inline HTML', async () => {
+            const md = await runAndRead('<audio src="https://cdn.example.com/podcast.mp3"></audio>');
+            expect(md).toContain('<audio src="https://cdn.example.com/podcast.mp3" controls></audio>');
+        });
+        it('degrades <iframe> to a markdown link with title', async () => {
+            const md = await runAndRead('<iframe src="https://codepen.io/pen/abc" title="Live demo"></iframe>');
+            expect(md).toContain('[Live demo](https://codepen.io/pen/abc)');
+        });
+        it('defaults iframe title to "Embedded content" when missing', async () => {
+            const md = await runAndRead('<iframe src="https://example.com/embed"></iframe>');
+            expect(md).toContain('[Embedded content](https://example.com/embed)');
+        });
+        it('drops <iframe> with no src', async () => {
+            const md = await runAndRead('<p>before</p><iframe></iframe><p>after</p>');
+            expect(md).not.toContain('iframe');
+            expect(md).toContain('before');
+            expect(md).toContain('after');
+        });
+    });
+    describe('stdout mode', () => {
+        it('writes markdown to process.stdout and skips file write', async () => {
+            const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-article-'));
+            tempDirs.push(tempDir);
+            const chunks = [];
+            const originalWrite = process.stdout.write.bind(process.stdout);
+            process.stdout.write = ((chunk) => {
+                chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+                return true;
+            });
+            try {
+                const result = await downloadArticle({
+                    title: 'Piped',
+                    contentHtml: '<p>Streaming body</p>',
+                    sourceUrl: 'https://example.com/a',
+                }, {
+                    output: tempDir,
+                    stdout: true,
+                });
+                expect(result[0].status).toBe('success');
+                expect(result[0].saved).toBe('-');
+                expect(fs.readdirSync(tempDir)).toHaveLength(0);
+                const emitted = chunks.join('');
+                expect(emitted).toContain('# Piped');
+                expect(emitted).toContain('Streaming body');
+                expect(emitted.endsWith('\n')).toBe(true);
+            }
+            finally {
+                process.stdout.write = originalWrite;
+            }
+        });
+        it('keeps remote image URLs intact in stdout mode (no download)', async () => {
+            const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-article-'));
+            tempDirs.push(tempDir);
+            const chunks = [];
+            const originalWrite = process.stdout.write.bind(process.stdout);
+            process.stdout.write = ((chunk) => {
+                chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+                return true;
+            });
+            try {
+                await downloadArticle({
+                    title: 'WithImage',
+                    contentHtml: '<p><img src="https://example.com/a.jpg"></p>',
+                    imageUrls: ['https://example.com/a.jpg'],
+                }, {
+                    output: tempDir,
+                    downloadImages: true,
+                    stdout: true,
+                });
+                expect(fs.readdirSync(tempDir)).toHaveLength(0);
+                expect(chunks.join('')).toContain('https://example.com/a.jpg');
+            }
+            finally {
+                process.stdout.write = originalWrite;
+            }
+        });
+    });
+});

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

@@ -0,0 +1,71 @@
+/**
+ * Download utilities: HTTP downloads, yt-dlp wrapper, format conversion.
+ */
+import type { BrowserCookie } from '../types.js';
+export type { BrowserCookie } from '../types.js';
+export interface DownloadOptions {
+    cookies?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    onProgress?: (received: number, total: number) => void;
+    maxRedirects?: number;
+}
+export interface YtdlpOptions {
+    cookies?: string;
+    cookiesFile?: string;
+    format?: string;
+    extraArgs?: string[];
+    onProgress?: (percent: number) => void;
+}
+/** Check if yt-dlp is available in PATH. */
+export declare function checkYtdlp(): boolean;
+/**
+ * Detect content type from URL and optional headers.
+ */
+export declare function detectContentType(url: string, contentType?: string): 'image' | 'video' | 'document' | 'binary';
+/**
+ * Check if URL requires yt-dlp for download.
+ */
+export declare function requiresYtdlp(url: string): boolean;
+/**
+ * HTTP download with progress callback.
+ */
+export declare function httpDownload(url: string, destPath: string, options?: DownloadOptions, redirectCount?: number): Promise<{
+    success: boolean;
+    size: number;
+    error?: string;
+}>;
+export declare function resolveRedirectUrl(currentUrl: string, location: string): string;
+/**
+ * Export cookies to Netscape format for yt-dlp.
+ */
+export declare function exportCookiesToNetscape(cookies: BrowserCookie[], filePath: string): void;
+export declare function formatCookieHeader(cookies: BrowserCookie[]): string;
+/**
+ * Download video using yt-dlp.
+ */
+export declare function ytdlpDownload(url: string, destPath: string, options?: YtdlpOptions): Promise<{
+    success: boolean;
+    size: number;
+    error?: string;
+}>;
+/**
+ * Save document content to file.
+ */
+export declare function saveDocument(content: string, destPath: string, format?: 'json' | 'markdown' | 'html' | 'text', metadata?: Record<string, unknown>): Promise<{
+    success: boolean;
+    size: number;
+    error?: string;
+}>;
+/**
+ * Sanitize filename by removing invalid characters.
+ */
+export declare function sanitizeFilename(name: string, maxLength?: number): string;
+/**
+ * Generate filename from URL if not provided.
+ */
+export declare function generateFilename(url: string, index: number, extension?: string): string;
+/**
+ * Get temp directory for cookie files.
+ */
+export declare function getTempDir(): string;

package/dist/src/download/index.js

@@ -0,0 +1,363 @@
+/**
+ * Download utilities: HTTP downloads, yt-dlp wrapper, format conversion.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { URL } from 'node:url';
+import { isBinaryInstalled } from '../external.js';
+import { getErrorMessage } from '../errors.js';
+import { fetchWithNodeNetwork } from '../node-network.js';
+import { log } from '../logger.js';
+/** Check if yt-dlp is available in PATH. */
+export function checkYtdlp() {
+    return isBinaryInstalled('yt-dlp');
+}
+/** Domains that host video content and can be downloaded via yt-dlp. */
+const VIDEO_PLATFORM_DOMAINS = [
+    'youtube.com', 'youtu.be', 'bilibili.com', 'twitter.com',
+    'x.com', 'tiktok.com', 'vimeo.com', 'twitch.tv',
+];
+/**
+ * Whether a URL's host is a known video platform.
+ *
+ * Matches on the parsed hostname with a domain boundary (exact host or a
+ * subdomain) rather than a raw substring of the whole URL. A plain
+ * `url.includes('x.com')` wrongly classifies `netflix.com`, `max.com`, etc.
+ * (and any URL whose path merely contains a token like `youtu.be`) as a
+ * video platform, routing ordinary files to yt-dlp and mislabelling content
+ * types. Mirrors the host-boundary check used in execution.ts.
+ */
+function isVideoPlatformUrl(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return VIDEO_PLATFORM_DOMAINS.some((d) => host === d || host.endsWith(`.${d}`));
+}
+const IMAGE_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg', '.ico', '.bmp', '.avif']);
+const VIDEO_EXTENSIONS = new Set(['.mp4', '.webm', '.avi', '.mov', '.mkv', '.flv', '.m3u8', '.ts']);
+const DOC_EXTENSIONS = new Set(['.html', '.htm', '.json', '.xml', '.txt', '.md', '.markdown']);
+/**
+ * Detect content type from URL and optional headers.
+ */
+export function detectContentType(url, contentType) {
+    if (contentType) {
+        if (contentType.startsWith('image/'))
+            return 'image';
+        if (contentType.startsWith('video/'))
+            return 'video';
+        if (contentType.startsWith('text/') || contentType.includes('json') || contentType.includes('xml'))
+            return 'document';
+    }
+    const ext = path.extname(new URL(url).pathname).toLowerCase();
+    if (IMAGE_EXTENSIONS.has(ext))
+        return 'image';
+    if (VIDEO_EXTENSIONS.has(ext))
+        return 'video';
+    if (isVideoPlatformUrl(url))
+        return 'video';
+    if (DOC_EXTENSIONS.has(ext))
+        return 'document';
+    return 'binary';
+}
+/**
+ * Check if URL requires yt-dlp for download.
+ */
+export function requiresYtdlp(url) {
+    return isVideoPlatformUrl(url);
+}
+/**
+ * HTTP download with progress callback.
+ */
+export async function httpDownload(url, destPath, options = {}, redirectCount = 0) {
+    const { cookies, headers = {}, timeout = 30000, onProgress, maxRedirects = 10 } = options;
+    const requestHeaders = {
+        'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
+        ...headers,
+    };
+    if (cookies) {
+        requestHeaders['Cookie'] = cookies;
+    }
+    const tempPath = `${destPath}.tmp`;
+    const cleanupTempFile = async () => {
+        try {
+            await fs.promises.rm(tempPath, { force: true });
+        }
+        catch {
+            // Ignore cleanup errors so the original failure is preserved.
+        }
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetchWithNodeNetwork(url, {
+            headers: requestHeaders,
+            signal: controller.signal,
+            redirect: 'manual',
+        });
+        clearTimeout(timer);
+        // Handle redirects before creating any file handles.
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (location) {
+                if (redirectCount >= maxRedirects) {
+                    return { success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` };
+                }
+                const redirectUrl = resolveRedirectUrl(url, location);
+                const originalHost = new URL(url).hostname;
+                const redirectHost = new URL(redirectUrl).hostname;
+                const redirectOptions = originalHost === redirectHost
+                    ? options
+                    : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
+                return httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1);
+            }
+        }
+        if (response.status !== 200) {
+            return { success: false, size: 0, error: `HTTP ${response.status}` };
+        }
+        if (!response.body) {
+            return { success: false, size: 0, error: 'Empty response body' };
+        }
+        const totalSize = parseInt(response.headers.get('content-length') || '0', 10);
+        let received = 0;
+        const progressStream = new Transform({
+            transform(chunk, _encoding, callback) {
+                received += chunk.length;
+                if (onProgress)
+                    onProgress(received, totalSize);
+                callback(null, chunk);
+            },
+        });
+        try {
+            await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+            await pipeline(Readable.fromWeb(response.body), progressStream, fs.createWriteStream(tempPath));
+            await fs.promises.rename(tempPath, destPath);
+            return { success: true, size: received };
+        }
+        catch (err) {
+            await cleanupTempFile();
+            return { success: false, size: 0, error: getErrorMessage(err) };
+        }
+    }
+    catch (err) {
+        clearTimeout(timer);
+        await cleanupTempFile();
+        return { success: false, size: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function resolveRedirectUrl(currentUrl, location) {
+    return new URL(location, currentUrl).toString();
+}
+function stripCookieHeaders(headers) {
+    if (!headers)
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => key.toLowerCase() !== 'cookie'));
+}
+/**
+ * Export cookies to Netscape format for yt-dlp.
+ */
+export function exportCookiesToNetscape(cookies, filePath) {
+    const lines = [
+        '# Netscape HTTP Cookie File',
+        '# https://curl.se/docs/http-cookies.html',
+        '# This is a generated file!  Do not edit.',
+        '',
+    ];
+    for (const cookie of cookies) {
+        const domain = cookie.domain.startsWith('.') ? cookie.domain : `.${cookie.domain}`;
+        const includeSubdomains = 'TRUE';
+        const cookiePath = cookie.path || '/';
+        const secure = cookie.secure ? 'TRUE' : 'FALSE';
+        const expiry = typeof cookie.expirationDate === 'number' && cookie.expirationDate > 0
+            ? Math.floor(cookie.expirationDate)
+            : Math.floor(Date.now() / 1000) + 86400 * 365; // fallback: 1 year from now
+        const safeName = cookie.name.replace(/[\t\n\r]/g, '');
+        const safeValue = cookie.value.replace(/[\t\n\r]/g, '');
+        lines.push(`${domain}\t${includeSubdomains}\t${cookiePath}\t${secure}\t${expiry}\t${safeName}\t${safeValue}`);
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    // 0o600: file holds live session cookies, must be owner-only. fchmod before
+    // writing also tightens a pre-existing broad file before new secrets land.
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC, 0o600);
+        fs.fchmodSync(fd, 0o600);
+        fs.writeFileSync(fd, lines.join('\n'), 'utf8');
+    }
+    finally {
+        if (fd !== undefined) {
+            fs.closeSync(fd);
+        }
+    }
+}
+export function formatCookieHeader(cookies) {
+    return cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join('; ');
+}
+/**
+ * Download video using yt-dlp.
+ */
+export async function ytdlpDownload(url, destPath, options = {}) {
+    const { cookiesFile, format = 'best', extraArgs = [], onProgress } = options;
+    if (!checkYtdlp()) {
+        return { success: false, size: 0, error: 'yt-dlp not installed. Install with: pip install yt-dlp' };
+    }
+    return new Promise((resolve) => {
+        const dir = path.dirname(destPath);
+        fs.mkdirSync(dir, { recursive: true });
+        // Build yt-dlp arguments
+        const args = [
+            url,
+            '-o', destPath,
+            '-f', format,
+            '--no-playlist',
+            '--progress',
+        ];
+        if (cookiesFile) {
+            if (fs.existsSync(cookiesFile)) {
+                args.push('--cookies', cookiesFile);
+            }
+            else {
+                log.warn(`[download] Cookies file not found: ${cookiesFile}, falling back to browser cookies`);
+                args.push('--cookies-from-browser', 'chrome');
+            }
+        }
+        else {
+            // Try to use browser cookies
+            args.push('--cookies-from-browser', 'chrome');
+        }
+        args.push(...extraArgs);
+        const proc = spawn('yt-dlp', args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let lastPercent = 0;
+        let errorOutput = '';
+        proc.stderr.on('data', (data) => {
+            const line = data.toString();
+            errorOutput += line;
+            // Parse progress from yt-dlp output
+            const match = line.match(/(\d+\.?\d*)%/);
+            if (match && onProgress) {
+                const percent = parseFloat(match[1]);
+                if (percent > lastPercent) {
+                    lastPercent = percent;
+                    onProgress(percent);
+                }
+            }
+        });
+        proc.stdout.on('data', (data) => {
+            const line = data.toString();
+            const match = line.match(/(\d+\.?\d*)%/);
+            if (match && onProgress) {
+                const percent = parseFloat(match[1]);
+                if (percent > lastPercent) {
+                    lastPercent = percent;
+                    onProgress(percent);
+                }
+            }
+        });
+        proc.on('close', (code) => {
+            if (code === 0 && fs.existsSync(destPath)) {
+                const stats = fs.statSync(destPath);
+                resolve({ success: true, size: stats.size });
+            }
+            else {
+                // Check for common yt-dlp output patterns
+                const patterns = fs.readdirSync(dir).filter(f => f.startsWith(path.basename(destPath, path.extname(destPath))));
+                if (patterns.length > 0) {
+                    const actualFile = path.join(dir, patterns[0]);
+                    const stats = fs.statSync(actualFile);
+                    resolve({ success: true, size: stats.size });
+                }
+                else {
+                    resolve({ success: false, size: 0, error: errorOutput.slice(0, 200) || `Exit code ${code}` });
+                }
+            }
+        });
+        proc.on('error', (err) => {
+            resolve({ success: false, size: 0, error: err.message });
+        });
+    });
+}
+/**
+ * Save document content to file.
+ */
+export async function saveDocument(content, destPath, format = 'markdown', metadata) {
+    try {
+        const dir = path.dirname(destPath);
+        fs.mkdirSync(dir, { recursive: true });
+        let output;
+        if (format === 'json') {
+            output = JSON.stringify({ ...metadata, content }, null, 2);
+        }
+        else if (format === 'markdown') {
+            // Add frontmatter if metadata exists
+            const frontmatter = metadata ? `---\n${Object.entries(metadata).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join('\n')}\n---\n\n` : '';
+            output = frontmatter + content;
+        }
+        else {
+            output = content;
+        }
+        fs.writeFileSync(destPath, output, 'utf-8');
+        return { success: true, size: Buffer.byteLength(output, 'utf-8') };
+    }
+    catch (err) {
+        return { success: false, size: 0, error: getErrorMessage(err) };
+    }
+}
+/**
+ * Sanitize filename by removing invalid characters.
+ */
+export function sanitizeFilename(name, maxLength = 200) {
+    return name
+        .replace(/[<>:"/\\|?*\x00-\x1f]/g, '_') // Remove invalid chars
+        .replace(/\s+/g, '_') // Replace spaces with underscores
+        .replace(/_+/g, '_') // Collapse multiple underscores
+        .replace(/^_|_$/g, '') // Trim underscores
+        .slice(0, maxLength);
+}
+/**
+ * Generate filename from URL if not provided.
+ */
+export function generateFilename(url, index, extension) {
+    try {
+        const parsedUrl = new URL(url);
+        const pathname = parsedUrl.pathname;
+        const basename = path.basename(pathname);
+        if (basename && basename !== '/' && basename.includes('.')) {
+            return sanitizeFilename(basename);
+        }
+        // Generate from hostname and index
+        const ext = extension || detectExtension(url);
+        const hostname = parsedUrl.hostname.replace(/^www\./, '');
+        return sanitizeFilename(`${hostname}_${index + 1}${ext}`);
+    }
+    catch {
+        const ext = extension || '.bin';
+        return `download_${index + 1}${ext}`;
+    }
+}
+/**
+ * Detect file extension from URL.
+ */
+function detectExtension(url) {
+    const type = detectContentType(url);
+    switch (type) {
+        case 'image': return '.jpg';
+        case 'video': return '.mp4';
+        case 'document': return '.md';
+        default: return '.bin';
+    }
+}
+/**
+ * Get temp directory for cookie files.
+ */
+export function getTempDir() {
+    return path.join(os.tmpdir(), 'webcmd-download');
+}

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

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