@huyuan-ai/cli 1.0.0 → 1.0.1

package/vendor/opencli/dist/discovery.js

@@ -0,0 +1,330 @@
+/**
+ * CLI discovery: finds YAML/TS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers all YAML commands instantly without runtime YAML parsing.
+ *    TS modules are loaded lazily only when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+import { Strategy, registerCommand } from './registry.js';
+import { getErrorMessage } from './errors.js';
+import { log } from './logger.js';
+/** User runtime directory: ~/.opencli */
+export const USER_OPENCLI_DIR = path.join(os.homedir(), '.opencli');
+/** User CLIs directory: ~/.opencli/clis */
+export const USER_CLIS_DIR = path.join(USER_OPENCLI_DIR, 'clis');
+/** Plugins directory: ~/.opencli/plugins/ */
+export const PLUGINS_DIR = path.join(USER_OPENCLI_DIR, 'plugins');
+/** Matches files that register commands via cli() or lifecycle hooks */
+const PLUGIN_MODULE_PATTERN = /\b(?:cli|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
+import { parseYamlArgs } from './yaml-schema.js';
+function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
+    if (!rawStrategy)
+        return fallback;
+    const key = rawStrategy.toUpperCase();
+    return Strategy[key] ?? fallback;
+}
+import { isRecord } from './utils.js';
+function resolveHostRuntimeModulePath(moduleName) {
+    const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
+    for (const ext of ['.js', '.ts']) {
+        const candidate = path.join(runtimeDir, `${moduleName}${ext}`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return path.join(runtimeDir, `${moduleName}.js`);
+}
+async function writeCompatShimIfNeeded(filePath, content) {
+    try {
+        const existing = await fs.promises.readFile(filePath, 'utf-8');
+        if (existing === content)
+            return;
+    }
+    catch {
+        // Fall through to write missing shim
+    }
+    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).
+ */
+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`),
+    ]);
+    // 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 symlinkDir = path.join(baseDir, 'node_modules', '@jackwener');
+    const symlinkPath = path.join(symlinkDir, 'opencli');
+    try {
+        // Only recreate if symlink is missing or points to wrong target
+        let needsUpdate = true;
+        try {
+            const existing = await fs.promises.readlink(symlinkPath);
+            if (existing === opencliRoot)
+                needsUpdate = false;
+        }
+        catch { /* doesn't exist */ }
+        if (needsUpdate) {
+            await fs.promises.mkdir(symlinkDir, { recursive: true });
+            try {
+                await fs.promises.unlink(symlinkPath);
+            }
+            catch { /* doesn't exist */ }
+            await fs.promises.symlink(opencliRoot, symlinkPath, 'dir');
+        }
+    }
+    catch {
+        // Non-fatal: npm-linked installs or permission issues may prevent this
+    }
+}
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export async function discoverClis(...dirs) {
+    // Fast path: try manifest first (production / post-build)
+    for (const dir of dirs) {
+        const manifestPath = path.resolve(dir, '..', 'cli-manifest.json');
+        try {
+            await fs.promises.access(manifestPath);
+            const loaded = await loadFromManifest(manifestPath, dir);
+            if (loaded)
+                continue; // Skip filesystem scan only when manifest is usable
+        }
+        catch {
+            // Fall through to filesystem scan
+        }
+        await discoverClisFromFs(dir);
+    }
+}
+/**
+ * Fast-path: register commands from pre-compiled manifest.
+ * YAML pipelines are inlined — zero YAML parsing at runtime.
+ * TS modules are deferred — loaded lazily on first execution.
+ */
+async function loadFromManifest(manifestPath, clisDir) {
+    try {
+        const raw = await fs.promises.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(raw);
+        for (const entry of manifest) {
+            if (entry.type === 'yaml') {
+                // YAML pipelines fully inlined in manifest — register directly
+                const strategy = parseStrategy(entry.strategy);
+                const cmd = {
+                    site: entry.site,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                    description: entry.description ?? '',
+                    domain: entry.domain,
+                    strategy,
+                    browser: entry.browser,
+                    args: entry.args ?? [],
+                    columns: entry.columns,
+                    pipeline: entry.pipeline,
+                    timeoutSeconds: entry.timeout,
+                    source: `manifest:${entry.site}/${entry.name}`,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
+                    navigateBefore: entry.navigateBefore,
+                };
+                registerCommand(cmd);
+            }
+            else if (entry.type === 'ts' && entry.modulePath) {
+                // TS adapters: register a lightweight stub.
+                // The actual module is loaded lazily on first executeCommand().
+                const strategy = parseStrategy(entry.strategy ?? 'cookie');
+                const modulePath = path.resolve(clisDir, entry.modulePath);
+                const cmd = {
+                    site: entry.site,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                    description: entry.description ?? '',
+                    domain: entry.domain,
+                    strategy,
+                    browser: entry.browser ?? true,
+                    args: entry.args ?? [],
+                    columns: entry.columns,
+                    timeoutSeconds: entry.timeout,
+                    source: modulePath,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
+                    navigateBefore: entry.navigateBefore,
+                    _lazy: true,
+                    _modulePath: modulePath,
+                };
+                registerCommand(cmd);
+            }
+        }
+        return true;
+    }
+    catch (err) {
+        log.warn(`Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+/**
+ * Fallback: traditional filesystem scan (used during development with tsx).
+ */
+async function discoverClisFromFs(dir) {
+    try {
+        await fs.promises.access(dir);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const sitePromises = entries
+        .filter(entry => entry.isDirectory())
+        .map(async (entry) => {
+        const site = entry.name;
+        const siteDir = path.join(dir, site);
+        const files = await fs.promises.readdir(siteDir);
+        await Promise.all(files.map(async (file) => {
+            const filePath = path.join(siteDir, file);
+            if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                await registerYamlCli(filePath, site);
+            }
+            else if ((file.endsWith('.js') && !file.endsWith('.d.js')) ||
+                (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))) {
+                if (!(await isCliModule(filePath)))
+                    return;
+                await import(pathToFileURL(filePath).href).catch((err) => {
+                    log.warn(`Failed to load module ${filePath}: ${getErrorMessage(err)}`);
+                });
+            }
+        }));
+    });
+    await Promise.all(sitePromises);
+}
+async function registerYamlCli(filePath, defaultSite) {
+    try {
+        const raw = await fs.promises.readFile(filePath, 'utf-8');
+        const def = yaml.load(raw);
+        if (!isRecord(def))
+            return;
+        const cliDef = def;
+        const site = cliDef.site ?? defaultSite;
+        const name = cliDef.name ?? path.basename(filePath, path.extname(filePath));
+        const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
+        const strategy = parseStrategy(strategyStr);
+        const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
+        const args = parseYamlArgs(cliDef.args);
+        const cmd = {
+            site,
+            name,
+            aliases: isRecord(cliDef) && Array.isArray(cliDef.aliases)
+                ? cliDef.aliases.filter((value) => typeof value === 'string')
+                : undefined,
+            description: cliDef.description ?? '',
+            domain: cliDef.domain,
+            strategy,
+            browser,
+            args,
+            columns: cliDef.columns,
+            pipeline: cliDef.pipeline,
+            timeoutSeconds: cliDef.timeout,
+            source: filePath,
+            deprecated: cliDef.deprecated,
+            replacedBy: cliDef.replacedBy,
+            navigateBefore: cliDef.navigateBefore,
+        };
+        registerCommand(cmd);
+    }
+    catch (err) {
+        log.warn(`Failed to load ${filePath}: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Discover and register plugins from ~/.opencli/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export async function discoverPlugins() {
+    try {
+        await fs.promises.access(PLUGINS_DIR);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
+    await Promise.all(entries.map(async (entry) => {
+        const pluginDir = path.join(PLUGINS_DIR, entry.name);
+        if (!(await isDiscoverablePluginDir(entry, pluginDir)))
+            return;
+        await discoverPluginDir(pluginDir, entry.name);
+    }));
+}
+/**
+ * Flat scan: read yaml/ts files directly in a plugin directory.
+ * Unlike discoverClisFromFs, this does NOT expect nested site subdirectories.
+ */
+async function discoverPluginDir(dir, site) {
+    const files = await fs.promises.readdir(dir);
+    const fileSet = new Set(files);
+    await Promise.all(files.map(async (file) => {
+        const filePath = path.join(dir, file);
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+            await registerYamlCli(filePath, site);
+        }
+        else if (file.endsWith('.js') && !file.endsWith('.d.js')) {
+            if (!(await isCliModule(filePath)))
+                return;
+            await import(pathToFileURL(filePath).href).catch((err) => {
+                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+            });
+        }
+        else if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
+            const jsFile = file.replace(/\.ts$/, '.js');
+            // Prefer compiled .js — skip the .ts source file
+            if (fileSet.has(jsFile))
+                return;
+            // No compiled .js found — cannot import raw .ts in production Node.js.
+            // This typically means esbuild transpilation failed during plugin install.
+            log.warn(`Plugin ${site}/${file}: no compiled .js found. ` +
+                `Run "opencli plugin update ${site}" to re-transpile, or install esbuild.`);
+        }
+    }));
+}
+async function isCliModule(filePath) {
+    try {
+        const source = await fs.promises.readFile(filePath, 'utf-8');
+        return PLUGIN_MODULE_PATTERN.test(source);
+    }
+    catch (err) {
+        log.warn(`Failed to inspect module ${filePath}: ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+async function isDiscoverablePluginDir(entry, pluginDir) {
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return (await fs.promises.stat(pluginDir)).isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            log.warn(`Failed to inspect plugin link ${pluginDir}: ${getErrorMessage(err)}`);
+        }
+        return false;
+    }
+}

package/vendor/opencli/dist/doctor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * opencli doctor — diagnose browser connectivity.
+ *
+ * Simplified for the daemon-based architecture.
+ */
+export type DoctorOptions = {
+    yes?: boolean;
+    live?: boolean;
+    sessions?: boolean;
+    cliVersion?: string;
+};
+export type ConnectivityResult = {
+    ok: boolean;
+    error?: string;
+    durationMs: number;
+};
+export type DoctorReport = {
+    cliVersion?: string;
+    daemonRunning: boolean;
+    extensionConnected: boolean;
+    extensionVersion?: string;
+    connectivity?: ConnectivityResult;
+    sessions?: Array<{
+        workspace: string;
+        windowId: number;
+        tabCount: number;
+        idleMsRemaining: number;
+    }>;
+    issues: string[];
+};
+/**
+ * Test connectivity by attempting a real browser command.
+ */
+export declare function checkConnectivity(opts?: {
+    timeout?: number;
+}): Promise<ConnectivityResult>;
+export declare function runBrowserDoctor(opts?: DoctorOptions): Promise<DoctorReport>;
+export declare function renderBrowserDoctorReport(report: DoctorReport): string;

package/vendor/opencli/dist/doctor.js

@@ -0,0 +1,126 @@
+/**
+ * opencli doctor — diagnose browser connectivity.
+ *
+ * Simplified for the daemon-based architecture.
+ */
+import chalk from 'chalk';
+import { DEFAULT_DAEMON_PORT } from './constants.js';
+import { checkDaemonStatus } from './browser/discover.js';
+import { BrowserBridge } from './browser/index.js';
+import { listSessions } from './browser/daemon-client.js';
+import { getErrorMessage } from './errors.js';
+import { getRuntimeLabel } from './runtime-detect.js';
+/**
+ * Test connectivity by attempting a real browser command.
+ */
+export async function checkConnectivity(opts) {
+    const start = Date.now();
+    try {
+        const bridge = new BrowserBridge();
+        const page = await bridge.connect({ timeout: opts?.timeout ?? 8 });
+        // Try a simple eval to verify end-to-end connectivity
+        await page.evaluate('1 + 1');
+        await bridge.close();
+        return { ok: true, durationMs: Date.now() - start };
+    }
+    catch (err) {
+        return { ok: false, error: getErrorMessage(err), durationMs: Date.now() - start };
+    }
+}
+export async function runBrowserDoctor(opts = {}) {
+    // Try to auto-start daemon if it's not running, so we show accurate status.
+    let initialStatus = await checkDaemonStatus();
+    if (!initialStatus.running) {
+        try {
+            const bridge = new BrowserBridge();
+            await bridge.connect({ timeout: 5 });
+            await bridge.close();
+        }
+        catch {
+            // Auto-start failed; we'll report it below.
+        }
+    }
+    // Run the live connectivity check — it may also auto-start the daemon as a
+    // side-effect, so we read daemon status only *after* all side-effects settle.
+    let connectivity;
+    if (opts.live) {
+        connectivity = await checkConnectivity();
+    }
+    const status = await checkDaemonStatus();
+    const sessions = opts.sessions && status.running && status.extensionConnected
+        ? await listSessions()
+        : undefined;
+    const issues = [];
+    if (!status.running) {
+        issues.push('Daemon is not running. It should start automatically when you run an opencli browser command.');
+    }
+    if (status.running && !status.extensionConnected) {
+        issues.push('Daemon is running but the Chrome/Chromium extension is not connected.\n' +
+            'Please install the opencli Browser Bridge extension:\n' +
+            '  1. Download from https://github.com/jackwener/opencli/releases\n' +
+            '  2. Open chrome://extensions/ → Enable Developer Mode\n' +
+            '  3. Click "Load unpacked" → select the extension folder');
+    }
+    if (connectivity && !connectivity.ok) {
+        issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
+    }
+    if (status.extensionVersion && opts.cliVersion) {
+        const extMajor = status.extensionVersion.split('.')[0];
+        const cliMajor = opts.cliVersion.split('.')[0];
+        if (extMajor !== cliMajor) {
+            issues.push(`Extension major version mismatch: extension v${status.extensionVersion} ≠ CLI v${opts.cliVersion}\n` +
+                '  Download the latest extension from: https://github.com/jackwener/opencli/releases');
+        }
+    }
+    return {
+        cliVersion: opts.cliVersion,
+        daemonRunning: status.running,
+        extensionConnected: status.extensionConnected,
+        extensionVersion: status.extensionVersion,
+        connectivity,
+        sessions,
+        issues,
+    };
+}
+export function renderBrowserDoctorReport(report) {
+    const lines = [chalk.bold(`opencli v${report.cliVersion ?? 'unknown'} doctor`) + chalk.dim(` (${getRuntimeLabel()})`), ''];
+    // Daemon status
+    const daemonIcon = report.daemonRunning ? chalk.green('[OK]') : chalk.red('[MISSING]');
+    lines.push(`${daemonIcon} Daemon: ${report.daemonRunning ? `running on port ${DEFAULT_DAEMON_PORT}` : 'not running'}`);
+    // Extension status
+    const extIcon = report.extensionConnected ? chalk.green('[OK]') : chalk.yellow('[MISSING]');
+    const extVersion = report.extensionVersion ? chalk.dim(` (v${report.extensionVersion})`) : '';
+    lines.push(`${extIcon} Extension: ${report.extensionConnected ? 'connected' : 'not connected'}${extVersion}`);
+    // Connectivity
+    if (report.connectivity) {
+        const connIcon = report.connectivity.ok ? chalk.green('[OK]') : chalk.red('[FAIL]');
+        const detail = report.connectivity.ok
+            ? `connected in ${(report.connectivity.durationMs / 1000).toFixed(1)}s`
+            : `failed (${report.connectivity.error ?? 'unknown'})`;
+        lines.push(`${connIcon} Connectivity: ${detail}`);
+    }
+    else {
+        lines.push(`${chalk.dim('[SKIP]')} Connectivity: skipped (--no-live)`);
+    }
+    if (report.sessions) {
+        lines.push('', chalk.bold('Sessions:'));
+        if (report.sessions.length === 0) {
+            lines.push(chalk.dim('  • no active automation sessions'));
+        }
+        else {
+            for (const session of report.sessions) {
+                lines.push(chalk.dim(`  • ${session.workspace} → window ${session.windowId}, tabs=${session.tabCount}, idle=${Math.ceil(session.idleMsRemaining / 1000)}s`));
+            }
+        }
+    }
+    if (report.issues.length) {
+        lines.push('', chalk.yellow('Issues:'));
+        for (const issue of report.issues) {
+            lines.push(chalk.dim(`  • ${issue}`));
+        }
+    }
+    else if (report.daemonRunning && report.extensionConnected) {
+        lines.push('', chalk.green('Everything looks good!'));
+    }
+    return lines.join('\n');
+}

package/vendor/opencli/dist/doctor.test.d.ts

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

package/vendor/opencli/dist/doctor.test.js

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { mockCheckDaemonStatus, mockListSessions, mockConnect, mockClose } = vi.hoisted(() => ({
+    mockCheckDaemonStatus: vi.fn(),
+    mockListSessions: vi.fn(),
+    mockConnect: vi.fn(),
+    mockClose: vi.fn(),
+}));
+vi.mock('./browser/discover.js', () => ({
+    checkDaemonStatus: mockCheckDaemonStatus,
+}));
+vi.mock('./browser/daemon-client.js', () => ({
+    listSessions: mockListSessions,
+}));
+vi.mock('./browser/index.js', () => ({
+    BrowserBridge: class {
+        connect = mockConnect;
+        close = mockClose;
+    },
+}));
+import { renderBrowserDoctorReport, runBrowserDoctor } from './doctor.js';
+describe('doctor report rendering', () => {
+    const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('renders OK-style report when daemon and extension connected', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: true,
+            issues: [],
+        }));
+        expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('[OK] Extension: connected');
+        expect(text).toContain('Everything looks good!');
+    });
+    it('renders MISSING when daemon not running', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: false,
+            extensionConnected: false,
+            issues: ['Daemon is not running.'],
+        }));
+        expect(text).toContain('[MISSING] Daemon: not running');
+        expect(text).toContain('[MISSING] Extension: not connected');
+        expect(text).toContain('Daemon is not running.');
+    });
+    it('renders extension not connected when daemon is running', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: false,
+            issues: ['Daemon is running but the Chrome extension is not connected.'],
+        }));
+        expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('[MISSING] Extension: not connected');
+    });
+    it('renders connectivity OK when live test succeeds', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: true,
+            connectivity: { ok: true, durationMs: 1234 },
+            issues: [],
+        }));
+        expect(text).toContain('[OK] Connectivity: connected in 1.2s');
+    });
+    it('renders connectivity SKIP when not tested', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: true,
+            issues: [],
+        }));
+        expect(text).toContain('[SKIP] Connectivity: skipped (--no-live)');
+    });
+    it('reports consistent status when live check auto-starts the daemon', async () => {
+        // checkDaemonStatus is called twice: once for auto-start check, once for final status.
+        // First call: daemon not running (triggers auto-start attempt)
+        mockCheckDaemonStatus.mockResolvedValueOnce({ running: false, extensionConnected: false });
+        // Auto-start attempt via BrowserBridge.connect fails
+        mockConnect.mockRejectedValueOnce(new Error('Could not start daemon'));
+        // Second call: daemon still not running after failed auto-start
+        mockCheckDaemonStatus.mockResolvedValueOnce({ running: false, extensionConnected: false });
+        const report = await runBrowserDoctor({ live: false });
+        // Status reflects daemon not running
+        expect(report.daemonRunning).toBe(false);
+        expect(report.extensionConnected).toBe(false);
+        // checkDaemonStatus called twice (initial + final)
+        expect(mockCheckDaemonStatus).toHaveBeenCalledTimes(2);
+        // Should report daemon not running
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Daemon is not running'),
+        ]));
+    });
+});

package/vendor/opencli/dist/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[]>;