@jackwener/opencli 1.7.6 → 1.7.7

package/dist/src/cli.test.js

@@ -17,7 +17,7 @@ vi.mock('./browser/index.js', () => {
         },
     };
 });
-import { createProgram, findPackageRoot, resolveBrowserVerifyInvocation } from './cli.js';
+import { createProgram, findPackageRoot, normalizeVerifyRows, renderVerifyPreview, resolveBrowserVerifyInvocation } from './cli.js';
 describe('resolveBrowserVerifyInvocation', () => {
     it('prefers the built entry declared in package metadata', () => {
         const projectRoot = path.join('repo-root');
@@ -102,6 +102,7 @@ describe('browser tab targeting commands', () => {
             getActivePage: vi.fn().mockReturnValue('tab-1'),
             getCurrentUrl: vi.fn().mockResolvedValue('https://one.example'),
             startNetworkCapture: vi.fn().mockResolvedValue(true),
+            getCookies: vi.fn().mockResolvedValue([]),
             evaluate: vi.fn().mockResolvedValue({ ok: true }),
             tabs: vi.fn().mockResolvedValue([
                 { index: 0, page: 'tab-1', url: 'https://one.example', title: 'one', active: true },
@@ -117,6 +118,15 @@ describe('browser tab targeting commands', () => {
             readNetworkCapture: vi.fn().mockResolvedValue([]),
         };
     });
+    function lastJsonLog() {
+        const calls = consoleLogSpy.mock.calls;
+        if (calls.length === 0)
+            throw new Error('Expected at least one console.log call');
+        const last = calls[calls.length - 1][0];
+        if (typeof last !== 'string')
+            throw new Error(`Expected string arg to console.log, got ${typeof last}`);
+        return JSON.parse(last);
+    }
     it('binds browser commands to an explicit target tab via --tab', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'opencli', 'browser', 'eval', '--tab', 'tab-2', 'document.title']);
@@ -233,6 +243,203 @@ describe('browser tab targeting commands', () => {
         expect(browserState.page?.closeTab).not.toHaveBeenCalled();
         expect(stderrSpy.mock.calls.flat().join('\n')).toContain('Target tab tab-stale is not part of the current browser session');
     });
+    it('browser analyze merges HttpOnly cookie names from page.getCookies and drains stale capture before verdict', async () => {
+        browserState.page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://target.example'),
+            startNetworkCapture: vi.fn().mockResolvedValue(true),
+            getCookies: vi.fn().mockResolvedValue([{ name: 'cf_clearance', value: 'x', domain: '.target.example' }]),
+            evaluate: vi.fn().mockResolvedValue({
+                cookieNames: [],
+                initialState: {
+                    __INITIAL_STATE__: false,
+                    __NUXT__: false,
+                    __NEXT_DATA__: false,
+                    __APOLLO_STATE__: false,
+                },
+                title: 'Target',
+                finalUrl: 'https://target.example/',
+            }),
+            tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
+            readNetworkCapture: vi.fn()
+                .mockResolvedValueOnce([
+                {
+                    url: 'https://stale.example/api/old',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: '{"stale":true}',
+                },
+            ])
+                .mockResolvedValueOnce([
+                {
+                    url: 'https://target.example/waf',
+                    method: 'GET',
+                    responseStatus: 403,
+                    responseContentType: 'text/html',
+                    responsePreview: 'Cloudflare Ray ID',
+                },
+            ]),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'analyze', 'https://target.example/']);
+        const out = lastJsonLog();
+        expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
+        expect(out.anti_bot.vendor).toBe('cloudflare');
+        expect(out.anti_bot.evidence).toContain('cookie:cf_clearance');
+    });
+    it('browser analyze falls back to interceptor buffer when network capture is unsupported', async () => {
+        let bufferReads = 0;
+        browserState.page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://target.example'),
+            startNetworkCapture: vi.fn().mockResolvedValue(false),
+            getCookies: vi.fn().mockResolvedValue([{ name: 'cf_clearance', value: 'x', domain: '.target.example' }]),
+            evaluate: vi.fn().mockImplementation(async (arg) => {
+                if (typeof arg === 'string' && arg.includes('document.cookie')) {
+                    return {
+                        cookieNames: [],
+                        initialState: {
+                            __INITIAL_STATE__: false,
+                            __NUXT__: false,
+                            __NEXT_DATA__: false,
+                            __APOLLO_STATE__: false,
+                        },
+                        title: 'Target',
+                        finalUrl: 'https://target.example/',
+                    };
+                }
+                if (typeof arg === 'string' && arg.includes('window.__opencli_net = []')) {
+                    bufferReads += 1;
+                    if (bufferReads === 1) {
+                        return JSON.stringify([
+                            {
+                                url: 'https://stale.example/api/old',
+                                method: 'GET',
+                                status: 200,
+                                size: 12,
+                                ct: 'application/json',
+                                body: { stale: true },
+                            },
+                        ]);
+                    }
+                    return JSON.stringify([
+                        {
+                            url: 'https://target.example/waf',
+                            method: 'GET',
+                            status: 403,
+                            size: 17,
+                            ct: 'text/html',
+                            body: 'Cloudflare Ray ID',
+                        },
+                    ]);
+                }
+                return undefined;
+            }),
+            tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
+            readNetworkCapture: vi.fn().mockResolvedValue([]),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'analyze', 'https://target.example/']);
+        const out = lastJsonLog();
+        expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
+        expect(bufferReads).toBe(2);
+        expect(out.anti_bot.vendor).toBe('cloudflare');
+        expect(out.anti_bot.evidence).toContain('cookie:cf_clearance');
+        expect(out.anti_bot.evidence).toContain('body:https://target.example/waf');
+    });
+    it('browser wait xhr starts capture, injects interceptor on fallback, and ignores stale ring entries', async () => {
+        browserState.page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://target.example'),
+            startNetworkCapture: vi.fn().mockResolvedValue(false),
+            evaluate: vi.fn().mockResolvedValue(undefined),
+            tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
+            readNetworkCapture: vi.fn()
+                .mockResolvedValueOnce([
+                {
+                    url: 'https://stale.example/api/old',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: '{"stale":true}',
+                },
+            ])
+                .mockResolvedValueOnce([
+                {
+                    url: 'https://target.example/api/target',
+                    method: 'GET',
+                    responseStatus: 200,
+                    responseContentType: 'application/json',
+                    responsePreview: '{"ok":true}',
+                },
+            ]),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'xhr', '/api/target', '--timeout', '900']);
+        const out = lastJsonLog();
+        expect(browserState.page?.startNetworkCapture).toHaveBeenCalledTimes(1);
+        expect(browserState.page?.evaluate).toHaveBeenCalledWith(expect.stringContaining('window.__opencli_net'));
+        expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
+        expect(out.matched.url).toBe('https://target.example/api/target');
+    });
+    it('browser wait xhr reads interceptor buffer when network capture is unsupported', async () => {
+        let bufferReads = 0;
+        browserState.page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            setActivePage: vi.fn(),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://target.example'),
+            startNetworkCapture: vi.fn().mockResolvedValue(false),
+            evaluate: vi.fn().mockImplementation(async (arg) => {
+                if (typeof arg === 'string' && arg.includes('window.__opencli_net = []')) {
+                    bufferReads += 1;
+                    if (bufferReads === 1) {
+                        return JSON.stringify([
+                            {
+                                url: 'https://stale.example/api/old',
+                                method: 'GET',
+                                status: 200,
+                                size: 12,
+                                ct: 'application/json',
+                                body: { stale: true },
+                            },
+                        ]);
+                    }
+                    return JSON.stringify([
+                        {
+                            url: 'https://target.example/api/target',
+                            method: 'GET',
+                            status: 200,
+                            size: 11,
+                            ct: 'application/json',
+                            body: { ok: true },
+                        },
+                    ]);
+                }
+                return undefined;
+            }),
+            tabs: vi.fn().mockResolvedValue([{ index: 0, page: 'tab-1', url: 'https://target.example', title: 'Target', active: true }]),
+            readNetworkCapture: vi.fn().mockResolvedValue([]),
+        };
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'opencli', 'browser', 'wait', 'xhr', '/api/target', '--timeout', '900']);
+        const out = lastJsonLog();
+        expect(browserState.page?.startNetworkCapture).toHaveBeenCalledTimes(1);
+        expect(browserState.page?.readNetworkCapture).toHaveBeenCalledTimes(2);
+        expect(bufferReads).toBe(2);
+        expect(out.matched.url).toBe('https://target.example/api/target');
+    });
 });
 describe('browser network command', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
@@ -1045,3 +1252,52 @@ describe('findPackageRoot', () => {
         expect(findPackageRoot(cliFile, (candidate) => exists.has(candidate))).toBe(packageRoot);
     });
 });
+describe('normalizeVerifyRows', () => {
+    it('returns an empty array for null / primitives', () => {
+        expect(normalizeVerifyRows(null)).toEqual([]);
+        expect(normalizeVerifyRows(undefined)).toEqual([]);
+        expect(normalizeVerifyRows('hello')).toEqual([]);
+    });
+    it('passes through array-of-objects', () => {
+        const rows = [{ a: 1 }, { a: 2 }];
+        expect(normalizeVerifyRows(rows)).toEqual(rows);
+    });
+    it('wraps array-of-primitives as { value } rows', () => {
+        expect(normalizeVerifyRows([1, 'two', null])).toEqual([
+            { value: 1 }, { value: 'two' }, { value: null },
+        ]);
+    });
+    it('unwraps common envelope shapes', () => {
+        expect(normalizeVerifyRows({ rows: [{ a: 1 }] })).toEqual([{ a: 1 }]);
+        expect(normalizeVerifyRows({ items: [{ b: 2 }] })).toEqual([{ b: 2 }]);
+        expect(normalizeVerifyRows({ data: [{ c: 3 }] })).toEqual([{ c: 3 }]);
+        expect(normalizeVerifyRows({ results: [{ d: 4 }] })).toEqual([{ d: 4 }]);
+    });
+    it('wraps a single object as a one-row array', () => {
+        expect(normalizeVerifyRows({ ok: true })).toEqual([{ ok: true }]);
+    });
+});
+describe('renderVerifyPreview', () => {
+    it('emits a placeholder for empty rows', () => {
+        expect(renderVerifyPreview([])).toContain('no rows');
+    });
+    it('prints column headers followed by row cells', () => {
+        const out = renderVerifyPreview([{ a: 'x', b: 1 }, { a: 'y', b: 2 }]);
+        const lines = out.split('\n');
+        expect(lines[0]).toContain('a');
+        expect(lines[0]).toContain('b');
+        expect(lines.some((l) => l.includes('x') && l.includes('1'))).toBe(true);
+        expect(lines.some((l) => l.includes('y') && l.includes('2'))).toBe(true);
+    });
+    it('truncates long cells and reports hidden rows / columns', () => {
+        const rows = Array.from({ length: 15 }, (_, i) => ({
+            a: i, b: 'x'.repeat(100), c: i, d: i, e: i, f: i, g: i, h: i,
+        }));
+        const out = renderVerifyPreview(rows, { maxRows: 5, maxCols: 3, cellMax: 10 });
+        expect(out).toContain('and 10 more row');
+        expect(out).toContain('more column');
+        // cell gets truncated
+        expect(out).toContain('xxxxxxxxxx');
+        expect(out).not.toContain('xxxxxxxxxxx'); // never 11 consecutive
+    });
+});

package/dist/src/daemon.d.ts

@@ -9,7 +9,8 @@
  *   1. Origin check — reject HTTP/WS from non chrome-extension:// origins
  *   2. Custom header — require X-OpenCLI header (browsers can't send it
  *      without CORS preflight, which we deny)
- *   3. No CORS headers — responses never include Access-Control-Allow-Origin
+ *   3. No CORS headers on command endpoints — only /ping is readable from the
+ *      Browser Bridge extension origin so the extension can probe daemon reachability
  *   4. Body size limit — 1 MB max to prevent OOM
  *   5. WebSocket verifyClient — reject upgrade before connection is established
  *
@@ -18,4 +19,4 @@
  *   - Persistent — stays alive until explicit shutdown, SIGTERM, or uninstall
  *   - Listens on localhost:19825
  */
-export {};
+export declare function getResponseCorsHeaders(pathname: string, origin?: string): Record<string, string> | undefined;

package/dist/src/daemon.js

@@ -9,7 +9,8 @@
  *   1. Origin check — reject HTTP/WS from non chrome-extension:// origins
  *   2. Custom header — require X-OpenCLI header (browsers can't send it
  *      without CORS preflight, which we deny)
- *   3. No CORS headers — responses never include Access-Control-Allow-Origin
+ *   3. No CORS headers on command endpoints — only /ping is readable from the
+ *      Browser Bridge extension origin so the extension can probe daemon reachability
  *   4. Body size limit — 1 MB max to prevent OOM
  *   5. WebSocket verifyClient — reject upgrade before connection is established
  *
@@ -60,10 +61,20 @@ function readBody(req) {
             reject(err); });
     });
 }
-function jsonResponse(res, status, data) {
-    res.writeHead(status, { 'Content-Type': 'application/json' });
+function jsonResponse(res, status, data, extraHeaders) {
+    res.writeHead(status, { 'Content-Type': 'application/json', ...extraHeaders });
     res.end(JSON.stringify(data));
 }
+export function getResponseCorsHeaders(pathname, origin) {
+    if (pathname !== '/ping')
+        return undefined;
+    if (!origin || !origin.startsWith('chrome-extension://'))
+        return undefined;
+    return {
+        'Access-Control-Allow-Origin': origin,
+        Vary: 'Origin',
+    };
+}
 async function handleRequest(req, res) {
     // ─── Security: Origin & custom-header check ──────────────────────
     // Block browser-based CSRF: browsers always send an Origin header on
@@ -93,7 +104,7 @@ async function handleRequest(req, res) {
     // Timing side-channels can reveal daemon presence to local processes, which
     // is an accepted risk given the daemon is loopback-only and short-lived.
     if (req.method === 'GET' && pathname === '/ping') {
-        jsonResponse(res, 200, { ok: true });
+        jsonResponse(res, 200, { ok: true }, getResponseCorsHeaders(pathname, origin));
         return;
     }
     // Require custom header on all other HTTP requests.  Browsers cannot attach
@@ -272,6 +283,7 @@ wss.on('connection', (ws) => {
         if (extensionWs === ws) {
             extensionWs = null;
             extensionVersion = null;
+            extensionCompatRange = null;
             // Reject pending requests in case 'close' does not follow this 'error'
             for (const [, p] of pending) {
                 clearTimeout(p.timer);

package/dist/src/daemon.test.d.ts

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

package/dist/src/daemon.test.js

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { getResponseCorsHeaders } from './daemon.js';
+describe('getResponseCorsHeaders', () => {
+    it('allows the Browser Bridge extension origin to read /ping', () => {
+        expect(getResponseCorsHeaders('/ping', 'chrome-extension://abc123')).toEqual({
+            'Access-Control-Allow-Origin': 'chrome-extension://abc123',
+            Vary: 'Origin',
+        });
+    });
+    it('does not add CORS headers for ordinary web origins', () => {
+        expect(getResponseCorsHeaders('/ping', 'https://example.com')).toBeUndefined();
+    });
+    it('does not add CORS headers when origin is absent', () => {
+        expect(getResponseCorsHeaders('/ping')).toBeUndefined();
+    });
+    it('does not add CORS headers for command endpoints even from the extension origin', () => {
+        expect(getResponseCorsHeaders('/command', 'chrome-extension://abc123')).toBeUndefined();
+    });
+});

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

@@ -37,6 +37,18 @@ export interface ArticleDownloadOptions {
     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;

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

@@ -8,6 +8,7 @@
 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;
@@ -19,22 +20,127 @@ const DEFAULT_LABELS = {
 // ============================================================
 // Markdown Conversion
 // ============================================================
-function createTurndown(configure) {
+// 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) {
-    const td = createTurndown(configure);
+function convertToMarkdown(contentHtml, codeBlocks, configure, cleanSelectors) {
+    const td = createTurndown(configure, cleanSelectors);
     let md = td.turndown(contentHtml);
     // Restore code block placeholders
     codeBlocks.forEach((block, i) => {
@@ -44,8 +150,12 @@ function convertToMarkdown(contentHtml, codeBlocks, configure) {
     });
     // Clean up
     md = md.replace(/\u00a0/g, ' ');
-    md = md.replace(/\n{4,}/g, '\n\n\n');
+    // 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) {
@@ -120,7 +230,7 @@ async function downloadImages(imgUrls, imgDir, headers, detectExt) {
  * 6. File write
  */
 export async function downloadArticle(data, options) {
-    const { output, downloadImages: shouldDownloadImages = true, imageHeaders, maxTitleLength = 80, configureTurndown, detectImageExt, frontmatterLabels, } = 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 [{
@@ -143,33 +253,47 @@ export async function downloadArticle(data, options) {
             }];
     }
     // Convert HTML to Markdown
-    let markdown = convertToMarkdown(data.contentHtml, data.codeBlocks || [], configureTurndown);
-    // Prepare output directory
+    let markdown = convertToMarkdown(data.contentHtml, data.codeBlocks || [], configureTurndown, cleanSelectors);
     const safeTitle = sanitizeFilename(data.title, maxTitleLength);
-    const articleDir = path.join(output, safeTitle);
-    fs.mkdirSync(articleDir, { recursive: true });
-    // Download images
-    if (shouldDownloadImages && data.imageUrls && data.imageUrls.length > 0) {
+    // 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
-    const headerLines = [`# ${data.title}`, ''];
+    // 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}`);
-    headerLines.push('', '---', '');
-    const fullContent = headerLines.join('\n') + markdown;
-    // Write file
+    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');
-    const size = Buffer.byteLength(fullContent, 'utf-8');
     return [{
             title: data.title,
             author: data.author || '-',