@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/doctor.test.js

@@ -0,0 +1,302 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { mockGetDaemonHealth, mockConnect, mockClose, mockFindShadowedUserAdapters } = vi.hoisted(() => ({
+    mockGetDaemonHealth: vi.fn(),
+    mockConnect: vi.fn(),
+    mockClose: vi.fn(),
+    mockFindShadowedUserAdapters: vi.fn(),
+}));
+vi.mock('./browser/daemon-transport.js', () => ({
+    getDaemonHealth: mockGetDaemonHealth,
+}));
+vi.mock('./browser/index.js', () => ({
+    BrowserBridge: class {
+        connect = mockConnect;
+        close = mockClose;
+    },
+}));
+vi.mock('./adapter-shadow.js', async () => {
+    const actual = await vi.importActual('./adapter-shadow.js');
+    return {
+        ...actual,
+        findShadowedUserAdapters: mockFindShadowedUserAdapters,
+    };
+});
+import { renderBrowserDoctorReport, runBrowserDoctor } from './doctor.js';
+describe('doctor report rendering', () => {
+    const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockFindShadowedUserAdapters.mockReturnValue([]);
+        // Doctor always runs live connectivity. Tests that want connect to fail override.
+        mockConnect.mockResolvedValue({
+            evaluate: vi.fn().mockResolvedValue(2),
+            closeWindow: vi.fn().mockResolvedValue(undefined),
+        });
+        mockClose.mockResolvedValue(undefined);
+    });
+    it('renders OK-style report when daemon and runtime connected', () => {
+        const text = strip(renderBrowserDoctorReport({
+            cliVersion: '1.7.9',
+            daemonRunning: true,
+            daemonVersion: '1.7.9',
+            runtimeConnected: true,
+            runtimeName: 'Cloak',
+            runtimeVersion: '1.6.8',
+            issues: [],
+        }));
+        expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('(v1.7.9)');
+        expect(text).toContain('[OK] Runtime: Cloak connected (v1.6.8)');
+        expect(text).toContain('Everything looks good!');
+        expect(text).not.toContain('webcmd browser analyze <url>');
+    });
+    it('renders a warning when daemon version is stale', () => {
+        const text = strip(renderBrowserDoctorReport({
+            cliVersion: '1.7.9',
+            daemonRunning: true,
+            daemonVersion: '1.7.6',
+            daemonStale: true,
+            runtimeConnected: true,
+            runtimeName: 'Cloak',
+            runtimeVersion: '1.0.3',
+            issues: ['Stale daemon detected: daemon v1.7.6 != CLI v1.7.9.\n  Run: webcmd daemon restart'],
+        }));
+        expect(text).toContain('[WARN] Daemon: running on port 19825 (v1.7.6, stale; CLI v1.7.9)');
+        expect(text).toContain('Run: webcmd daemon restart');
+        expect(text).not.toContain('Everything looks good!');
+    });
+    it('renders MISSING when daemon not running', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: false,
+            runtimeConnected: false,
+            issues: ['Daemon is not running.'],
+        }));
+        expect(text).toContain('[MISSING] Daemon: not running');
+        expect(text).toContain('[MISSING] Runtime: Cloak not connected');
+        expect(text).toContain('Daemon is not running.');
+    });
+    it('renders runtime not connected when daemon is running', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            runtimeConnected: false,
+            issues: ['Daemon is running but the Cloak runtime is not connected.'],
+        }));
+        expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('[MISSING] Runtime: Cloak not connected');
+    });
+    it('renders OK when the connected Cloak runtime version is unknown', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            runtimeConnected: true,
+            runtimeName: 'Cloak',
+            issues: [],
+        }));
+        expect(text).toContain('[OK] Runtime: Cloak connected (version unknown)');
+        expect(text).not.toContain('Cloak runtime is connected but did not report a version.');
+        expect(text).toContain('Everything looks good!');
+    });
+    it('renders connectivity OK when live test succeeds', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            runtimeConnected: true,
+            connectivity: { ok: true, durationMs: 1234 },
+            issues: [],
+        }));
+        expect(text).toContain('[OK] Connectivity: connected in 1.2s');
+    });
+    it('renders connected profiles when multiple are present', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            runtimeConnected: false,
+            profiles: [
+                { contextId: 'work', runtimeConnected: true, runtimeVersion: '1.2.3', pending: 0 },
+                { contextId: 'personal', runtimeConnected: true, runtimeVersion: '1.2.3', pending: 0 },
+            ],
+            issues: [],
+        }));
+        expect(text).toContain('Profiles:');
+        expect(text).toContain('work: connected v1.2.3');
+        expect(text).toContain('personal: connected v1.2.3');
+    });
+    it('renders unstable runtime state when live connectivity and status disagree', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            runtimeConnected: true,
+            runtimeFlaky: true,
+            runtimeName: 'Cloak',
+            connectivity: { ok: true, durationMs: 1234 },
+            issues: ['Cloak runtime connection is unstable.'],
+        }));
+        expect(text).toContain('[WARN] Runtime: Cloak unstable');
+        expect(text).toContain('Cloak runtime connection is unstable.');
+    });
+    it('renders unstable daemon state when live connectivity and status disagree', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: false,
+            daemonFlaky: true,
+            runtimeConnected: false,
+            connectivity: { ok: true, durationMs: 1234 },
+            issues: ['Daemon connectivity is unstable.'],
+        }));
+        expect(text).toContain('[WARN] Daemon: unstable');
+        expect(text).toContain('Daemon connectivity is unstable.');
+    });
+    it('reports daemon not running when connectivity fails and daemon stays stopped', async () => {
+        mockConnect.mockRejectedValueOnce(new Error('Could not start daemon'));
+        mockGetDaemonHealth.mockResolvedValueOnce({ state: 'stopped', status: null });
+        const report = await runBrowserDoctor();
+        expect(report.daemonRunning).toBe(false);
+        expect(report.runtimeConnected).toBe(false);
+        expect(report.connectivity?.ok).toBe(false);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Daemon is not running'),
+        ]));
+    });
+    it('reports flapping when live check succeeds but final status shows runtime disconnected', async () => {
+        mockGetDaemonHealth.mockResolvedValueOnce({ state: 'no-runtime', status: { runtimeConnected: false, runtimeName: 'Cloak' } });
+        const report = await runBrowserDoctor();
+        expect(report.daemonRunning).toBe(true);
+        expect(report.runtimeConnected).toBe(false);
+        expect(report.runtimeFlaky).toBe(true);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Cloak runtime connection is unstable'),
+        ]));
+    });
+    it('uses runtime-neutral readiness hints when the runtime is disconnected', async () => {
+        mockConnect.mockRejectedValueOnce(new Error('runtime unavailable'));
+        mockGetDaemonHealth.mockResolvedValueOnce({
+            state: 'no-runtime',
+            status: { runtimeConnected: false, runtimeName: 'Cloak' },
+        });
+        const report = await runBrowserDoctor();
+        const issues = report.issues.join('\n');
+        expect(issues).toContain('Cloak runtime is not connected');
+        expect(issues).toContain('Make sure Chrome/Chromium is open and Cloak is enabled');
+        expect(issues).not.toContain(`Webcmd Browser ${'Bridge'}`);
+        expect(issues).not.toContain(`Load ${'unpacked'}`);
+        expect(issues).not.toContain('Download the latest extension');
+    });
+    it('reports daemon flapping when live check succeeds but daemon disappears afterward', async () => {
+        mockGetDaemonHealth.mockResolvedValueOnce({ state: 'stopped', status: null });
+        const report = await runBrowserDoctor();
+        expect(report.daemonRunning).toBe(false);
+        expect(report.daemonFlaky).toBe(true);
+        expect(report.runtimeConnected).toBe(false);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Daemon connectivity is unstable'),
+        ]));
+    });
+    it('uses the fast default timeout for live connectivity checks', async () => {
+        let timeoutSeen;
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        mockConnect.mockImplementationOnce(async (opts) => {
+            timeoutSeen = opts?.timeout;
+            expect(opts?.session).toBe('__doctor__');
+            expect(opts?.surface).toBe('browser');
+            return {
+                evaluate: vi.fn().mockResolvedValue(2),
+                closeWindow,
+            };
+        });
+        mockGetDaemonHealth.mockResolvedValueOnce({ state: 'ready', status: { runtimeConnected: true, runtimeName: 'Cloak' } });
+        await runBrowserDoctor();
+        expect(timeoutSeen).toBe(8);
+        expect(closeWindow).toHaveBeenCalledTimes(1);
+    });
+    it('does not report an issue when the connected Cloak runtime does not report a version', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                runtimeConnected: true,
+                runtimeName: 'Cloak',
+                runtimeVersion: undefined,
+            },
+        };
+        mockGetDaemonHealth.mockResolvedValue(status);
+        const report = await runBrowserDoctor();
+        expect(report.runtimeConnected).toBe(true);
+        expect(report.runtimeVersion).toBeUndefined();
+        expect(report.issues.join('\n')).not.toContain('did not report a version');
+    });
+    it('does not compare runtime version to CLI version or cached extension updates', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.9',
+                runtimeConnected: true,
+                runtimeName: 'Cloak',
+                runtimeVersion: '99.0.0',
+            },
+        };
+        mockGetDaemonHealth.mockResolvedValue(status);
+        const report = await runBrowserDoctor({ cliVersion: '1.7.9' });
+        expect(report.runtimeVersion).toBe('99.0.0');
+        expect(report.issues.join('\n')).not.toContain('Extension major version mismatch');
+        expect(report.issues.join('\n')).not.toContain('Extension update available');
+        expect(report.issues.join('\n')).not.toContain('Download the latest extension');
+    });
+    it('reports an issue when daemon version differs from CLI version', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.6',
+                runtimeConnected: true,
+                runtimeName: 'Cloak',
+                runtimeVersion: '1.0.3',
+            },
+        };
+        mockGetDaemonHealth.mockResolvedValue(status);
+        const report = await runBrowserDoctor({ cliVersion: '1.7.9' });
+        expect(report.daemonStale).toBe(true);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Stale daemon detected: daemon v1.7.6 != CLI v1.7.9'),
+        ]));
+    });
+    it('reports local adapter shadows as a warning issue', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.9',
+                runtimeConnected: true,
+                runtimeName: 'Cloak',
+                runtimeVersion: '1.0.3',
+            },
+        };
+        mockGetDaemonHealth.mockResolvedValue(status);
+        mockFindShadowedUserAdapters.mockReturnValueOnce([
+            {
+                name: 'instagram/saved',
+                userPath: '/home/me/.webcmd/clis/instagram/saved.js',
+                builtinPath: '/pkg/clis/instagram/saved.js',
+            },
+        ]);
+        const report = await runBrowserDoctor({ cliVersion: '1.7.9' });
+        expect(report.adapterShadows).toHaveLength(1);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Local adapter overrides shadow packaged adapters'),
+        ]));
+    });
+    it('reports profile-required when multiple profiles are connected without a selection', async () => {
+        const status = {
+            state: 'profile-required',
+            status: {
+                runtimeConnected: false,
+                runtimeName: 'Cloak',
+                profileRequired: true,
+                profiles: [
+                    { contextId: 'work', runtimeConnected: true, pending: 0 },
+                    { contextId: 'personal', runtimeConnected: true, pending: 0 },
+                ],
+            },
+        };
+        mockGetDaemonHealth.mockResolvedValue(status);
+        // Real connectivity would fail in profile-required state; force it here so
+        // the test exercises the profile-required issue path, not the flaky path.
+        mockConnect.mockRejectedValueOnce(new Error('profile required'));
+        const report = await runBrowserDoctor();
+        expect(report.profiles).toHaveLength(2);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Multiple Chrome profiles are connected'),
+        ]));
+    });
+});

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

@@ -0,0 +1,72 @@
+/**
+ * Article download helper — shared logic for downloading articles as Markdown.
+ *
+ * Used by: zhihu/download, weixin/download, and future article adapters.
+ *
+ * Flow: ArticleData → TurndownService → image download → frontmatter → .md file
+ */
+import TurndownService from 'turndown';
+export interface ArticleData {
+    title: string;
+    author?: string;
+    publishTime?: string;
+    sourceUrl?: string;
+    contentHtml: string;
+    /** Pre-extracted code blocks to restore after Markdown conversion */
+    codeBlocks?: Array<{
+        lang: string;
+        code: string;
+    }>;
+    /** Image URLs found in the article (pre-collected from DOM) */
+    imageUrls?: string[];
+}
+export interface FrontmatterLabels {
+    author?: string;
+    publishTime?: string;
+    sourceUrl?: string;
+}
+export interface ArticleDownloadOptions {
+    output: string;
+    downloadImages?: boolean;
+    /** Extra headers for image downloads (e.g. { Referer: '...' }) */
+    imageHeaders?: Record<string, string>;
+    maxTitleLength?: number;
+    /** Custom TurndownService configuration callback */
+    configureTurndown?: (td: TurndownService) => void;
+    /** Custom image extension detector (default: infer from URL extension) */
+    detectImageExt?: (url: string) => string;
+    /** Custom frontmatter labels (default: Chinese labels) */
+    frontmatterLabels?: FrontmatterLabels;
+    /**
+     * Extra CSS selectors removed from the article before Turndown conversion.
+     * Use this to drop site-specific noise the adapter can't always trim upstream
+     * (e.g. zhihu 折叠卡, weixin 赞赏栏, wiki infobox).
+     */
+    cleanSelectors?: string[];
+    /**
+     * Write the markdown to `process.stdout` instead of a file on disk. Image
+     * download and directory creation are skipped — remote image URLs are kept
+     * as-is so the output is self-contained when piped.
+     */
+    stdout?: boolean;
+}
+export interface ArticleDownloadResult {
+    title: string;
+    author: string;
+    publish_time: string;
+    status: string;
+    size: string;
+    saved: string;
+}
+/**
+ * Download an article to Markdown with optional image localization.
+ *
+ * Handles the full pipeline:
+ * 1. HTML → Markdown (via TurndownService)
+ * 2. Code block placeholder restoration
+ * 3. Batch image downloading with concurrency + deduplication
+ * 4. Image URL replacement in Markdown
+ * 5. Frontmatter generation (customizable labels)
+ * 6. File write
+ */
+export declare function downloadArticle(data: ArticleData, options: ArticleDownloadOptions): Promise<ArticleDownloadResult[]>;

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

@@ -0,0 +1,305 @@
+/**
+ * Article download helper — shared logic for downloading articles as Markdown.
+ *
+ * Used by: zhihu/download, weixin/download, and future article adapters.
+ *
+ * Flow: ArticleData → TurndownService → image download → frontmatter → .md file
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import TurndownService from 'turndown';
+import { gfm } from 'turndown-plugin-gfm';
+import { httpDownload, sanitizeFilename } from './index.js';
+import { formatBytes } from './progress.js';
+const IMAGE_CONCURRENCY = 5;
+const DEFAULT_LABELS = {
+    author: '作者',
+    publishTime: '发布时间',
+    sourceUrl: '原文链接',
+};
+// ============================================================
+// Markdown Conversion
+// ============================================================
+// Nodes that never carry article content. Turndown keeps them by default — if an
+// adapter's contentHtml extraction misses one, CSS / scripts / widget markup
+// ends up inline in the .md. Strip them unconditionally at the converter level.
+// `svg` is not in HTMLElementTagNameMap, so we type-narrow manually.
+// `header/footer/nav/aside` cover page chrome that adapters occasionally
+// forget to trim — the article's own title/author/publishTime are supplied
+// as separate fields on ArticleData, so duplicated nodes are redundant.
+// `iframe` is NOT in this set — it's handled by a dedicated rule below that
+// degrades to a link so embedded content (YouTube, Twitter, CodePen …) keeps
+// a reachable URL in the exported markdown.
+const STRIPPED_TAGS = [
+    'script', 'style', 'noscript',
+    'canvas',
+    'form', 'button', 'dialog',
+    'header', 'footer', 'nav', 'aside',
+];
+function createTurndown(configure, cleanSelectors) {
+    const td = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+    });
+    td.use(gfm);
+    td.remove(STRIPPED_TAGS);
+    // turndown-plugin-gfm@1.0.2 emits single-tilde strikethrough (`~x~`), which
+    // is not the canonical GFM form. Override it so exported markdown is
+    // portable across common renderers.
+    td.addRule('canonicalStrikethrough', {
+        filter: (node) => ['DEL', 'S', 'STRIKE'].includes(node.nodeName),
+        replacement: (content) => `~~${content}~~`,
+    });
+    // SVG isn't in the static HTML tag map; match by name with a custom filter.
+    td.addRule('stripSvg', {
+        filter: (node) => node.nodeName === 'svg' || node.nodeName === 'SVG',
+        replacement: () => '',
+    });
+    td.addRule('linebreak', {
+        filter: 'br',
+        replacement: () => '\n',
+    });
+    // Inline base64 images would land as huge `![](data:image/...;base64,...)`
+    // strings that the image downloader can't localize. Drop them.
+    td.addRule('ignoreBase64Images', {
+        filter: (node) => {
+            if (node.nodeName !== 'IMG')
+                return false;
+            const src = node.getAttribute?.('src') ?? '';
+            return src.startsWith('data:');
+        },
+        replacement: () => '',
+    });
+    // Markdown has no native video/audio primitive. Emit inline HTML so
+    // renderers that support it (GitHub, VS Code preview …) still play the
+    // media; viewers that don't simply show the tag as text, which is still
+    // more information than dropping the node outright.
+    td.addRule('videoElement', {
+        filter: (node) => node.nodeName === 'VIDEO',
+        replacement: (_content, node) => {
+            const el = node;
+            const src = el.getAttribute('src')
+                || el.querySelector('source')?.getAttribute('src')
+                || '';
+            if (!src)
+                return '';
+            const poster = el.getAttribute('poster') || '';
+            return `\n<video src="${src}" controls${poster ? ` poster="${poster}"` : ''}></video>\n`;
+        },
+    });
+    td.addRule('audioElement', {
+        filter: (node) => node.nodeName === 'AUDIO',
+        replacement: (_content, node) => {
+            const el = node;
+            const src = el.getAttribute('src')
+                || el.querySelector('source')?.getAttribute('src')
+                || '';
+            return src ? `\n<audio src="${src}" controls></audio>\n` : '';
+        },
+    });
+    // Iframes (YouTube, Twitter, CodePen …) degrade to a markdown link so the
+    // embedded resource is still reachable from the exported file.
+    td.addRule('iframeToLink', {
+        filter: (node) => node.nodeName === 'IFRAME',
+        replacement: (_content, node) => {
+            const el = node;
+            const src = el.getAttribute('src') || '';
+            if (!src)
+                return '';
+            const title = el.getAttribute('title') || 'Embedded content';
+            return `\n[${title}](${src})\n`;
+        },
+    });
+    // Per-adapter dirty-node removal. Adapters know their site's specific noise
+    // (zhihu 折叠卡, weixin 赞赏栏, wiki 折叠 infobox …); we keep the default set
+    // empty so the generic converter stays untouched.
+    const selectorRules = (cleanSelectors ?? [])
+        .map(sel => sel.trim())
+        .filter(Boolean);
+    if (selectorRules.length > 0) {
+        td.addRule('cleanSelectors', {
+            filter: (node) => {
+                const match = node.matches;
+                if (typeof match !== 'function')
+                    return false;
+                return selectorRules.some((sel) => {
+                    try {
+                        return match.call(node, sel);
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            },
+            replacement: () => '',
+        });
+    }
+    if (configure)
+        configure(td);
+    return td;
+}
+function convertToMarkdown(contentHtml, codeBlocks, configure, cleanSelectors) {
+    const td = createTurndown(configure, cleanSelectors);
+    let md = td.turndown(contentHtml);
+    // Restore code block placeholders
+    codeBlocks.forEach((block, i) => {
+        const placeholder = `CODEBLOCK-PLACEHOLDER-${i}`;
+        const fenced = `\n\`\`\`${block.lang}\n${block.code}\n\`\`\`\n`;
+        md = md.replace(placeholder, fenced);
+    });
+    // Clean up
+    md = md.replace(/\u00a0/g, ' ');
+    // Turndown leaves behind lone dashes / middle dots when list bullets or
+    // decorative separators lose their surrounding inline context.
+    md = md.replace(/^[ \t]*[-·][ \t]*$/gm, '');
+    md = md.replace(/^[ \t]+$/gm, '');
+    md = md.replace(/[ \t]+$/gm, '');
+    md = md.replace(/\n{3,}/g, '\n\n');
+    return md;
+}
+function replaceImageUrls(md, urlMap) {
+    return md.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt, imgUrl) => {
+        const local = urlMap[imgUrl];
+        return local ? `![${alt}](${local})` : match;
+    });
+}
+// ============================================================
+// Image Downloading
+// ============================================================
+function defaultDetectImageExt(url) {
+    const extMatch = url.match(/\.(\w{3,4})(?:\?|$)/);
+    return extMatch ? extMatch[1] : 'jpg';
+}
+async function downloadImages(imgUrls, imgDir, headers, detectExt) {
+    const urlMap = {};
+    if (imgUrls.length === 0)
+        return urlMap;
+    const detect = detectExt || defaultDetectImageExt;
+    // Deduplicate image URLs
+    const seen = new Set();
+    const uniqueUrls = imgUrls.filter(url => {
+        if (seen.has(url))
+            return false;
+        seen.add(url);
+        return true;
+    });
+    for (let i = 0; i < uniqueUrls.length; i += IMAGE_CONCURRENCY) {
+        const batch = uniqueUrls.slice(i, i + IMAGE_CONCURRENCY);
+        const results = await Promise.all(batch.map(async (rawUrl, j) => {
+            const index = i + j + 1;
+            let imgUrl = rawUrl;
+            if (imgUrl.startsWith('//'))
+                imgUrl = `https:${imgUrl}`;
+            const ext = detect(imgUrl);
+            const filename = `img_${String(index).padStart(3, '0')}.${ext}`;
+            const filepath = path.join(imgDir, filename);
+            try {
+                const result = await httpDownload(imgUrl, filepath, {
+                    headers,
+                    timeout: 15000,
+                });
+                if (result.success) {
+                    return { remoteUrl: rawUrl, localPath: `images/${filename}` };
+                }
+            }
+            catch {
+                // Skip failed downloads
+            }
+            return null;
+        }));
+        for (const r of results) {
+            if (r)
+                urlMap[r.remoteUrl] = r.localPath;
+        }
+    }
+    return urlMap;
+}
+// ============================================================
+// Main API
+// ============================================================
+/**
+ * Download an article to Markdown with optional image localization.
+ *
+ * Handles the full pipeline:
+ * 1. HTML → Markdown (via TurndownService)
+ * 2. Code block placeholder restoration
+ * 3. Batch image downloading with concurrency + deduplication
+ * 4. Image URL replacement in Markdown
+ * 5. Frontmatter generation (customizable labels)
+ * 6. File write
+ */
+export async function downloadArticle(data, options) {
+    const { output, downloadImages: shouldDownloadImages = true, imageHeaders, maxTitleLength = 80, configureTurndown, detectImageExt, frontmatterLabels, cleanSelectors, stdout = false, } = options;
+    const labels = { ...DEFAULT_LABELS, ...frontmatterLabels };
+    if (!data.title) {
+        return [{
+                title: 'Error',
+                author: '-',
+                publish_time: '-',
+                status: 'failed — no title',
+                size: '-',
+                saved: '-',
+            }];
+    }
+    if (!data.contentHtml) {
+        return [{
+                title: data.title,
+                author: data.author || '-',
+                publish_time: data.publishTime || '-',
+                status: 'failed — no content',
+                size: '-',
+                saved: '-',
+            }];
+    }
+    // Convert HTML to Markdown
+    let markdown = convertToMarkdown(data.contentHtml, data.codeBlocks || [], configureTurndown, cleanSelectors);
+    const safeTitle = sanitizeFilename(data.title, maxTitleLength);
+    // Download images only when writing to disk. In stdout mode remote URLs
+    // stay intact so the piped output is self-contained.
+    if (!stdout && shouldDownloadImages && data.imageUrls && data.imageUrls.length > 0) {
+        const articleDir = path.join(output, safeTitle);
+        fs.mkdirSync(articleDir, { recursive: true });
+        const imagesDir = path.join(articleDir, 'images');
+        fs.mkdirSync(imagesDir, { recursive: true });
+        const urlMap = await downloadImages(data.imageUrls, imagesDir, imageHeaders, detectImageExt);
+        markdown = replaceImageUrls(markdown, urlMap);
+    }
+    // Build frontmatter with customizable labels.
+    // Shape: `# Title\n[> meta\n...]\n---\n\n<markdown>` — exactly one blank
+    // line separates every section, so we never produce ≥3 consecutive newlines.
+    const headerLines = [`# ${data.title}`];
+    if (data.author)
+        headerLines.push(`> ${labels.author}: ${data.author}`);
+    if (data.publishTime)
+        headerLines.push(`> ${labels.publishTime}: ${data.publishTime}`);
+    if (data.sourceUrl)
+        headerLines.push(`> ${labels.sourceUrl}: ${data.sourceUrl}`);
+    const frontmatter = headerLines.join('\n') + '\n\n---\n\n';
+    const fullContent = frontmatter + markdown;
+    const size = Buffer.byteLength(fullContent, 'utf-8');
+    if (stdout) {
+        process.stdout.write(fullContent.endsWith('\n') ? fullContent : fullContent + '\n');
+        return [{
+                title: data.title,
+                author: data.author || '-',
+                publish_time: data.publishTime || '-',
+                status: 'success',
+                size: formatBytes(size),
+                saved: '-',
+            }];
+    }
+    const articleDir = path.join(output, safeTitle);
+    fs.mkdirSync(articleDir, { recursive: true });
+    const filename = `${safeTitle}.md`;
+    const filePath = path.join(articleDir, filename);
+    fs.writeFileSync(filePath, fullContent, 'utf-8');
+    return [{
+            title: data.title,
+            author: data.author || '-',
+            publish_time: data.publishTime || '-',
+            status: 'success',
+            size: formatBytes(size),
+            saved: filePath,
+        }];
+}

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

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