@jackwener/opencli 1.6.2 → 1.6.4

package/dist/{cli.test.js → src/cli.test.js}

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as path from 'node:path';
 const { mockExploreUrl, mockRenderExploreSummary, mockGenerateCliFromUrl, mockRenderGenerateSummary, mockRecordSession, mockRenderRecordSummary, mockCascadeProbe, mockRenderCascadeResult, mockGetBrowserFactory, mockBrowserSession, } = vi.hoisted(() => ({
     mockExploreUrl: vi.fn(),
     mockRenderExploreSummary: vi.fn(),
@@ -31,7 +32,7 @@ vi.mock('./runtime.js', () => ({
     getBrowserFactory: mockGetBrowserFactory,
     browserSession: mockBrowserSession,
 }));
-import { createProgram } from './cli.js';
+import { createProgram, findPackageRoot, resolveOperateVerifyInvocation } from './cli.js';
 describe('built-in browser commands verbose wiring', () => {
     const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
     beforeEach(() => {
@@ -86,3 +87,85 @@ describe('built-in browser commands verbose wiring', () => {
     });
     consoleLogSpy.mockClear();
 });
+describe('resolveOperateVerifyInvocation', () => {
+    it('prefers the built entry declared in package metadata', () => {
+        const projectRoot = path.join('repo-root');
+        const exists = new Set([
+            path.join(projectRoot, 'dist', 'src', 'main.js'),
+        ]);
+        expect(resolveOperateVerifyInvocation({
+            projectRoot,
+            readFile: () => JSON.stringify({ bin: { opencli: 'dist/src/main.js' } }),
+            fileExists: (candidate) => exists.has(candidate),
+        })).toEqual({
+            binary: process.execPath,
+            args: [path.join(projectRoot, 'dist', 'src', 'main.js')],
+            cwd: projectRoot,
+        });
+    });
+    it('falls back to compatibility built-entry candidates when package metadata is unavailable', () => {
+        const projectRoot = path.join('repo-root');
+        const exists = new Set([
+            path.join(projectRoot, 'dist', 'src', 'main.js'),
+        ]);
+        expect(resolveOperateVerifyInvocation({
+            projectRoot,
+            readFile: () => { throw new Error('no package json'); },
+            fileExists: (candidate) => exists.has(candidate),
+        })).toEqual({
+            binary: process.execPath,
+            args: [path.join(projectRoot, 'dist', 'src', 'main.js')],
+            cwd: projectRoot,
+        });
+    });
+    it('falls back to the local tsx binary in source checkouts on Windows', () => {
+        const projectRoot = path.join('repo-root');
+        const exists = new Set([
+            path.join(projectRoot, 'src', 'main.ts'),
+            path.join(projectRoot, 'node_modules', '.bin', 'tsx.cmd'),
+        ]);
+        expect(resolveOperateVerifyInvocation({
+            projectRoot,
+            platform: 'win32',
+            fileExists: (candidate) => exists.has(candidate),
+        })).toEqual({
+            binary: path.join(projectRoot, 'node_modules', '.bin', 'tsx.cmd'),
+            args: [path.join(projectRoot, 'src', 'main.ts')],
+            cwd: projectRoot,
+            shell: true,
+        });
+    });
+    it('falls back to npx tsx when local tsx is unavailable', () => {
+        const projectRoot = path.join('repo-root');
+        const exists = new Set([
+            path.join(projectRoot, 'src', 'main.ts'),
+        ]);
+        expect(resolveOperateVerifyInvocation({
+            projectRoot,
+            platform: 'linux',
+            fileExists: (candidate) => exists.has(candidate),
+        })).toEqual({
+            binary: 'npx',
+            args: ['tsx', path.join(projectRoot, 'src', 'main.ts')],
+            cwd: projectRoot,
+        });
+    });
+});
+describe('findPackageRoot', () => {
+    it('walks up from dist/src to the package root', () => {
+        const packageRoot = path.join('repo-root');
+        const cliFile = path.join(packageRoot, 'dist', 'src', 'cli.js');
+        const exists = new Set([
+            path.join(packageRoot, 'package.json'),
+        ]);
+        expect(findPackageRoot(cliFile, (candidate) => exists.has(candidate))).toBe(packageRoot);
+    });
+    it('walks up from src to the package root', () => {
+        const packageRoot = path.join('repo-root');
+        const cliFile = path.join(packageRoot, 'src', 'cli.ts');
+        const exists = new Set([
+            path.join(packageRoot, 'package.json'),
+        ]);
+        expect(findPackageRoot(cliFile, (candidate) => exists.has(candidate))).toBe(packageRoot);
+    });
+});

package/dist/{commanderAdapter.d.ts → src/commanderAdapter.d.ts}

@@ -16,6 +16,7 @@ export declare function normalizeArgValue(argType: string | undefined, value: un
  * Register a single CliCommand as a Commander subcommand.
  */
 export declare function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void;
+export type GenericErrorKind = 'auth' | 'http' | 'not-found' | 'other';
 /**
  * Register all commands from the registry onto a Commander program.
  */

package/dist/{commanderAdapter.js → src/commanderAdapter.js}

@@ -122,42 +122,31 @@ export function registerCommandToProgram(siteCmd, cmd) {
         }
     });
 }
-// ── Exit code resolution ─────────────────────────────────────────────────────
-/**
- * Map any thrown value to a Unix process exit code.
- *
- * - CliError subclasses carry their own exitCode (set in errors.ts).
- * - Generic Error objects are classified by message pattern so that
- *   un-typed auth / not-found errors from adapters still produce
- *   meaningful exit codes for shell scripts.
- */
-function resolveExitCode(err) {
-    if (err instanceof CliError)
-        return err.exitCode;
-    // Pattern-based fallback for untyped errors thrown by third-party adapters.
-    const msg = getErrorMessage(err);
-    const kind = classifyGenericError(msg);
-    if (kind === 'auth')
-        return EXIT_CODES.NOPERM;
-    if (kind === 'not-found')
-        return EXIT_CODES.EMPTY_RESULT;
-    if (kind === 'http')
-        return EXIT_CODES.GENERIC_ERROR; // HTTP 4xx/5xx → generic; renderer shows details
-    return EXIT_CODES.GENERIC_ERROR;
-}
-// ── Error rendering ──────────────────────────────────────────────────────────
+// ── Error classification ─────────────────────────────────────────────────────
 const ISSUES_URL = 'https://github.com/jackwener/opencli/issues';
+const GENERIC_ERROR_MAP = {
+    auth: { icon: '🔒', exitCode: EXIT_CODES.NOPERM, hint: 'Open Chrome or Chromium, log in to the target site, then retry.' },
+    http: { icon: '🌐', exitCode: EXIT_CODES.GENERIC_ERROR, hint: 'Check your login status, or the site may be temporarily unavailable.' },
+    'not-found': { icon: '📭', exitCode: EXIT_CODES.EMPTY_RESULT, hint: 'The resource was not found. The adapter or page structure may have changed.' },
+    other: { icon: '💥', exitCode: EXIT_CODES.GENERIC_ERROR, hint: '' },
+};
 /** Pattern-based classifier for untyped errors thrown by adapters. */
 function classifyGenericError(msg) {
     const m = msg.toLowerCase();
+    let kind = 'other';
     if (/not logged in|login required|please log in|未登录|请先登录|authentication required|cookie expired/.test(m))
-        return 'auth';
-    // Match "HTTP 404", "status: 500", "status 403", bare "404 Not Found", etc.
-    if (/\b(status[: ]+)?[45]\d{2}\b|http[/ ][45]\d{2}/.test(m))
-        return 'http';
-    if (/not found|未找到|could not find|no .+ found/.test(m))
-        return 'not-found';
-    return 'other';
+        kind = 'auth';
+    else if (/\b(status[: ]+)?[45]\d{2}\b|http[/ ][45]\d{2}/.test(m))
+        kind = 'http';
+    else if (/not found|未找到|could not find|no .+ found/.test(m))
+        kind = 'not-found';
+    return { kind, ...GENERIC_ERROR_MAP[kind] };
+}
+// ── Exit code resolution ─────────────────────────────────────────────────────
+function resolveExitCode(err) {
+    if (err instanceof CliError)
+        return err.exitCode;
+    return classifyGenericError(getErrorMessage(err)).exitCode;
 }
 /** Render a status line for BrowserConnectError based on real-time or kind-derived state. */
 function renderBridgeStatus(running, extensionConnected) {
@@ -256,21 +245,12 @@ async function renderError(err, cmdName, verbose) {
     }
     // ── Generic Error from adapters: classify by message pattern ──────────
     const msg = getErrorMessage(err);
-    const kind = classifyGenericError(msg);
-    if (kind === 'auth') {
-        console.error(chalk.red(`🔒 ${msg}`));
-        console.error(chalk.yellow('→ Open Chrome or Chromium, log in to the target site, then retry.'));
-        return;
-    }
-    if (kind === 'http') {
-        console.error(chalk.red(`🌐 ${msg}`));
-        console.error(chalk.yellow('→ Check your login status, or the site may be temporarily unavailable.'));
-        return;
-    }
-    if (kind === 'not-found') {
-        console.error(chalk.red(`📭 ${msg}`));
-        console.error(chalk.yellow('→ The resource was not found. The adapter or page structure may have changed.'));
-        console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
+    const classified = classifyGenericError(msg);
+    if (classified.kind !== 'other') {
+        console.error(chalk.red(`${classified.icon} ${msg}`));
+        console.error(chalk.yellow(`→ ${classified.hint}`));
+        if (classified.kind === 'not-found')
+            console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
         return;
     }
     // ── Unknown error: show stack in verbose mode ─────────────────────────

package/dist/{discovery.d.ts → src/discovery.d.ts}

@@ -14,10 +14,19 @@ export declare const USER_CLIS_DIR: string;
 /** Plugins directory: ~/.opencli/plugins/ */
 export declare const PLUGINS_DIR: string;
 /**
- * Create runtime shim files under ~/.opencli so legacy user TS CLIs can keep
- * importing ../../registry(.js) and ../../errors(.js).
+ * Create runtime shim files under ~/.opencli so user CLIs can keep
+ * importing ../../registry(.js), ../../errors(.js), etc.
+ *
+ * Adapters use relative imports like `../../registry.js` which, from
+ * ~/.opencli/clis/<site>/<cmd>.js, resolve to ~/.opencli/registry.js.
+ * We create shim files that re-export from the installed opencli runtime.
  */
 export declare function ensureUserCliCompatShims(baseDir?: string): Promise<void>;
+/**
+ * First-run fallback: if postinstall was skipped (--ignore-scripts) or failed,
+ * trigger adapter fetch on first CLI invocation when ~/.opencli/clis/ is empty.
+ */
+export declare function ensureUserAdapters(): Promise<void>;
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.

package/dist/{discovery.js → src/discovery.js}

@@ -31,6 +31,18 @@ function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
     return Strategy[key] ?? fallback;
 }
 import { isRecord } from './utils.js';
+/**
+ * Find the package root (directory containing package.json).
+ * Dev: import.meta.url is in src/ → one level up.
+ * Prod: import.meta.url is in dist/src/ → two levels up.
+ */
+function findPackageRoot() {
+    let dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    if (!fs.existsSync(path.join(dir, 'package.json'))) {
+        dir = path.resolve(dir, '..');
+    }
+    return dir;
+}
 function resolveHostRuntimeModulePath(moduleName) {
     const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
     for (const ext of ['.js', '.ts']) {
@@ -52,24 +64,63 @@ async function writeCompatShimIfNeeded(filePath, content) {
     await fs.promises.writeFile(filePath, content, 'utf-8');
 }
 /**
- * Create runtime shim files under ~/.opencli so legacy user TS CLIs can keep
- * importing ../../registry(.js) and ../../errors(.js).
+ * Create runtime shim files under ~/.opencli so user CLIs can keep
+ * importing ../../registry(.js), ../../errors(.js), etc.
+ *
+ * Adapters use relative imports like `../../registry.js` which, from
+ * ~/.opencli/clis/<site>/<cmd>.js, resolve to ~/.opencli/registry.js.
+ * We create shim files that re-export from the installed opencli runtime.
  */
 export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
     await fs.promises.mkdir(baseDir, { recursive: true });
-    const registryUrl = pathToFileURL(resolveHostRuntimeModulePath('registry-api')).href;
-    const errorsUrl = pathToFileURL(resolveHostRuntimeModulePath('errors')).href;
-    await Promise.all([
-        writeCompatShimIfNeeded(path.join(baseDir, 'registry'), `export * from '${registryUrl}';\n`),
-        writeCompatShimIfNeeded(path.join(baseDir, 'registry.js'), `export * from '${registryUrl}';\n`),
-        writeCompatShimIfNeeded(path.join(baseDir, 'errors'), `export * from '${errorsUrl}';\n`),
-        writeCompatShimIfNeeded(path.join(baseDir, 'errors.js'), `export * from '${errorsUrl}';\n`),
-        writeCompatShimIfNeeded(path.join(baseDir, 'package.json'), `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`),
-    ]);
+    // Map of shim name → runtime module name (resolved via resolveHostRuntimeModulePath)
+    const rootShims = [
+        ['registry', 'registry-api'],
+        ['errors', 'errors'],
+        ['types', 'types'],
+        ['utils', 'utils'],
+        ['logger', 'logger'],
+        ['launcher', 'launcher'],
+    ];
+    // Subdirectory shims: [subdir, filename, runtime module path relative to src/]
+    const subdirShims = [
+        ['browser', 'cdp', 'browser/cdp'],
+        ['browser', 'page', 'browser/page'],
+        ['browser', 'utils', 'browser/utils'],
+        ['download', 'index', 'download/index'],
+        ['download', 'article-download', 'download/article-download'],
+        ['download', 'media-download', 'download/media-download'],
+        ['download', 'progress', 'download/progress'],
+        ['pipeline', 'index', 'pipeline/index'],
+    ];
+    const writes = [];
+    // Root-level shims (both with and without .js extension)
+    // Also generate src/ shims: adapters import ../../src/registry.js etc., which
+    // resolve to ~/.opencli/src/registry.js when running from ~/.opencli/clis/<site>/
+    const srcDir = path.join(baseDir, 'src');
+    await fs.promises.mkdir(srcDir, { recursive: true });
+    for (const [shimName, moduleName] of rootShims) {
+        const url = pathToFileURL(resolveHostRuntimeModulePath(moduleName)).href;
+        const content = `export * from '${url}';\n`;
+        writes.push(writeCompatShimIfNeeded(path.join(baseDir, shimName), content));
+        writes.push(writeCompatShimIfNeeded(path.join(baseDir, `${shimName}.js`), content));
+        writes.push(writeCompatShimIfNeeded(path.join(srcDir, `${shimName}.js`), content));
+    }
+    // Subdirectory shims
+    for (const [subdir, filename, runtimePath] of subdirShims) {
+        const dir = path.join(baseDir, subdir);
+        await fs.promises.mkdir(dir, { recursive: true });
+        const url = pathToFileURL(resolveHostRuntimeModulePath(runtimePath)).href;
+        const content = `export * from '${url}';\n`;
+        writes.push(writeCompatShimIfNeeded(path.join(dir, `${filename}.js`), content));
+    }
+    // package.json for ESM resolution
+    writes.push(writeCompatShimIfNeeded(path.join(baseDir, 'package.json'), `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`));
+    await Promise.all(writes);
     // Create node_modules/@jackwener/opencli symlink so user TS CLIs can import
     // from '@jackwener/opencli/registry' (the package export).
     // This is needed because ~/.opencli/clis/ is outside opencli's node_modules tree.
-    const opencliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const opencliRoot = findPackageRoot();
     const symlinkDir = path.join(baseDir, 'node_modules', '@jackwener');
     const symlinkPath = path.join(symlinkDir, 'opencli');
     try {
@@ -94,6 +145,44 @@ export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
         // Non-fatal: npm-linked installs or permission issues may prevent this
     }
 }
+const ADAPTER_MANIFEST_PATH = path.join(USER_OPENCLI_DIR, 'adapter-manifest.json');
+/**
+ * First-run fallback: if postinstall was skipped (--ignore-scripts) or failed,
+ * trigger adapter fetch on first CLI invocation when ~/.opencli/clis/ is empty.
+ */
+export async function ensureUserAdapters() {
+    // If adapter manifest already exists, adapters were fetched — nothing to do
+    try {
+        await fs.promises.access(ADAPTER_MANIFEST_PATH);
+        return;
+    }
+    catch {
+        // No manifest — first run or postinstall was skipped
+    }
+    // Check if clis dir has any content (could be manually populated)
+    try {
+        const entries = await fs.promises.readdir(USER_CLIS_DIR);
+        if (entries.length > 0)
+            return;
+    }
+    catch {
+        // Dir doesn't exist — needs fetch
+    }
+    log.info('First run detected — copying adapters (one-time setup)...');
+    try {
+        const { execFileSync } = await import('node:child_process');
+        const scriptPath = path.join(findPackageRoot(), 'scripts', 'fetch-adapters.js');
+        execFileSync(process.execPath, [scriptPath], {
+            stdio: 'inherit',
+            env: { ...process.env, _OPENCLI_FIRST_RUN: '1' },
+            timeout: 120_000,
+        });
+    }
+    catch (err) {
+        log.warn(`Could not fetch adapters on first run: ${getErrorMessage(err)}`);
+        log.warn('Built-in adapters from the package will be used.');
+    }
+}
 /**
  * Discover and register CLI commands.
  * Uses pre-compiled manifest when available for instant startup.

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * 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;
+}
+export interface ArticleDownloadResult {
+    title: string;
+    author: string;
+    publish_time: string;
+    status: string;
+    size: 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,178 @@
+/**
+ * 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 { httpDownload, sanitizeFilename } from './index.js';
+import { formatBytes } from './progress.js';
+const IMAGE_CONCURRENCY = 5;
+const DEFAULT_LABELS = {
+    author: '作者',
+    publishTime: '发布时间',
+    sourceUrl: '原文链接',
+};
+// ============================================================
+// Markdown Conversion
+// ============================================================
+function createTurndown(configure) {
+    const td = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+    });
+    td.addRule('linebreak', {
+        filter: 'br',
+        replacement: () => '\n',
+    });
+    if (configure)
+        configure(td);
+    return td;
+}
+function convertToMarkdown(contentHtml, codeBlocks, configure) {
+    const td = createTurndown(configure);
+    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, ' ');
+    md = md.replace(/\n{4,}/g, '\n\n\n');
+    md = md.replace(/[ \t]+$/gm, '');
+    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, } = options;
+    const labels = { ...DEFAULT_LABELS, ...frontmatterLabels };
+    if (!data.title) {
+        return [{
+                title: 'Error',
+                author: '-',
+                publish_time: '-',
+                status: 'failed — no title',
+                size: '-',
+            }];
+    }
+    if (!data.contentHtml) {
+        return [{
+                title: data.title,
+                author: data.author || '-',
+                publish_time: data.publishTime || '-',
+                status: 'failed — no content',
+                size: '-',
+            }];
+    }
+    // Convert HTML to Markdown
+    let markdown = convertToMarkdown(data.contentHtml, data.codeBlocks || [], configureTurndown);
+    // Prepare output directory
+    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) {
+        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}`, ''];
+    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 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 || '-',
+            publish_time: data.publishTime || '-',
+            status: 'success',
+            size: formatBytes(size),
+        }];
+}