@jackwener/opencli 1.4.0 → 1.5.0

package/dist/commanderAdapter.js

@@ -14,14 +14,30 @@ import { fullName, getRegistry } from './registry.js';
 import { formatRegistryHelpText } from './serialization.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand } from './execution.js';
-import { CliError, ERROR_ICONS, getErrorMessage } from './errors.js';
+import { CliError, ERROR_ICONS, getErrorMessage, BrowserConnectError, AuthRequiredError, TimeoutError, SelectorError, EmptyResultError, ArgumentError, AdapterLoadError, CommandExecutionError, } from './errors.js';
+import { checkDaemonStatus } from './browser/discover.js';
+export function normalizeArgValue(argType, value, name) {
+    if (argType !== 'bool')
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    if (value == null || value === '')
+        return false;
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    throw new CliError('ARGUMENT', `"${name}" must be either "true" or "false".`);
+}
 /**
  * Register a single CliCommand as a Commander subcommand.
  */
 export function registerCommandToProgram(siteCmd, cmd) {
     if (siteCmd.commands.some((c) => c.name() === cmd.name))
         return;
-    const subCmd = siteCmd.command(cmd.name).description(cmd.description);
+    const deprecatedSuffix = cmd.deprecated ? ' [deprecated]' : '';
+    const subCmd = siteCmd.command(cmd.name).description(`${cmd.description}${deprecatedSuffix}`);
     // Register positional args first, then named options
     const positionalArgs = [];
     for (const arg of cmd.args) {
@@ -48,27 +64,32 @@ export function registerCommandToProgram(siteCmd, cmd) {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
         const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
         const startTime = Date.now();
-        // ── Collect kwargs ──────────────────────────────────────────────────
-        const kwargs = {};
-        for (let i = 0; i < positionalArgs.length; i++) {
-            const v = actionArgs[i];
-            if (v !== undefined)
-                kwargs[positionalArgs[i].name] = v;
-        }
-        for (const arg of cmd.args) {
-            if (arg.positional)
-                continue;
-            const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
-            const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
-            if (v !== undefined)
-                kwargs[arg.name] = v;
-        }
         // ── Execute + render ────────────────────────────────────────────────
         try {
+            // ── Collect kwargs ────────────────────────────────────────────────
+            const kwargs = {};
+            for (let i = 0; i < positionalArgs.length; i++) {
+                const v = actionArgs[i];
+                if (v !== undefined)
+                    kwargs[positionalArgs[i].name] = v;
+            }
+            for (const arg of cmd.args) {
+                if (arg.positional)
+                    continue;
+                const camelName = arg.name.replace(/-([a-z])/g, (_m, ch) => ch.toUpperCase());
+                const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
+                if (v !== undefined)
+                    kwargs[arg.name] = normalizeArgValue(arg.type, v, arg.name);
+            }
             const verbose = optionsRecord.verbose === true;
             const format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
             if (verbose)
                 process.env.OPENCLI_VERBOSE = '1';
+            if (cmd.deprecated) {
+                const message = typeof cmd.deprecated === 'string' ? cmd.deprecated : `${fullName(cmd)} is deprecated.`;
+                const replacement = cmd.replacedBy ? ` Use ${cmd.replacedBy} instead.` : '';
+                console.error(chalk.yellow(`Deprecated: ${message}${replacement}`));
+            }
             const result = await executeCommand(cmd, kwargs, verbose);
             if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
                 console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
@@ -84,22 +105,148 @@ export function registerCommandToProgram(siteCmd, cmd) {
             });
         }
         catch (err) {
-            if (err instanceof CliError) {
-                const icon = ERROR_ICONS[err.code] ?? '⚠️';
-                console.error(chalk.red(`${icon} ${err.message}`));
-                if (err.hint)
-                    console.error(chalk.yellow(`→ ${err.hint}`));
-            }
-            else if (optionsRecord.verbose === true && err instanceof Error && err.stack) {
-                console.error(chalk.red(err.stack));
-            }
-            else {
-                console.error(chalk.red(`Error: ${getErrorMessage(err)}`));
-            }
+            await renderError(err, fullName(cmd), optionsRecord.verbose === true);
             process.exitCode = 1;
         }
     });
 }
+// ── Error rendering ──────────────────────────────────────────────────────────
+const ISSUES_URL = 'https://github.com/jackwener/opencli/issues';
+/** Pattern-based classifier for untyped errors thrown by adapters. */
+function classifyGenericError(msg) {
+    const m = msg.toLowerCase();
+    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';
+}
+/** Render a status line for BrowserConnectError based on real-time or kind-derived state. */
+function renderBridgeStatus(running, extensionConnected) {
+    const ok = chalk.green('✓');
+    const fail = chalk.red('✗');
+    console.error(`  Daemon    ${running ? ok : fail} ${running ? 'running' : 'not running'}`);
+    console.error(`  Extension ${extensionConnected ? ok : fail} ${extensionConnected ? 'connected' : 'not connected'}`);
+    console.error();
+    if (!running) {
+        console.error(chalk.yellow('  Run the command again — daemon should auto-start.'));
+        console.error(chalk.dim('  Still failing? Run: opencli doctor'));
+    }
+    else if (!extensionConnected) {
+        console.error(chalk.yellow('  Install the Browser Bridge extension to continue:'));
+        console.error(chalk.dim('    1. Download from github.com/jackwener/opencli/releases'));
+        console.error(chalk.dim('    2. chrome://extensions → Enable Developer Mode → Load unpacked'));
+    }
+    else {
+        console.error(chalk.yellow('  Connection failed despite extension being active.'));
+        console.error(chalk.dim('  Try reloading the extension, or run: opencli doctor'));
+    }
+}
+async function renderError(err, cmdName, verbose) {
+    // ── BrowserConnectError: real-time diagnosis, kind as fallback ────────
+    if (err instanceof BrowserConnectError) {
+        console.error(chalk.red('🔌 Browser Bridge not connected'));
+        console.error();
+        try {
+            // 300ms matches execution.ts — localhost responds in <50ms when running.
+            const status = await checkDaemonStatus({ timeout: 300 });
+            renderBridgeStatus(status.running, status.extensionConnected);
+        }
+        catch (_statusErr) {
+            // checkDaemonStatus itself failed — derive best-guess state from kind.
+            const running = err.kind !== 'daemon-not-running';
+            const extensionConnected = err.kind === 'command-failed';
+            renderBridgeStatus(running, extensionConnected);
+        }
+        return;
+    }
+    // ── AuthRequiredError ─────────────────────────────────────────────────
+    if (err instanceof AuthRequiredError) {
+        console.error(chalk.red(`🔒 Not logged in to ${err.domain}`));
+        // Respect custom hints set by the adapter; fall back to generic guidance.
+        console.error(chalk.yellow(`→ ${err.hint ?? `Open Chrome and log in to https://${err.domain}, then retry.`}`));
+        return;
+    }
+    // ── TimeoutError ──────────────────────────────────────────────────────
+    if (err instanceof TimeoutError) {
+        console.error(chalk.red(`⏱  ${err.message}`));
+        console.error(chalk.yellow('→ Try again, or raise the limit:'));
+        console.error(chalk.dim(`    OPENCLI_BROWSER_COMMAND_TIMEOUT=60 ${cmdName}`));
+        return;
+    }
+    // ── SelectorError / EmptyResultError: likely outdated adapter ─────────
+    if (err instanceof SelectorError || err instanceof EmptyResultError) {
+        const icon = ERROR_ICONS[err.code] ?? '⚠️';
+        console.error(chalk.red(`${icon} ${err.message}`));
+        console.error(chalk.yellow('→ The page structure may have changed — this adapter may be outdated.'));
+        console.error(chalk.dim(`  Debug:  ${cmdName} --verbose`));
+        console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
+        return;
+    }
+    // ── ArgumentError ─────────────────────────────────────────────────────
+    if (err instanceof ArgumentError) {
+        console.error(chalk.red(`❌ ${err.message}`));
+        if (err.hint)
+            console.error(chalk.yellow(`→ ${err.hint}`));
+        return;
+    }
+    // ── AdapterLoadError ──────────────────────────────────────────────────
+    if (err instanceof AdapterLoadError) {
+        console.error(chalk.red(`📦 ${err.message}`));
+        if (err.hint)
+            console.error(chalk.yellow(`→ ${err.hint}`));
+        return;
+    }
+    // ── CommandExecutionError ─────────────────────────────────────────────
+    if (err instanceof CommandExecutionError) {
+        console.error(chalk.red(`💥 ${err.message}`));
+        if (err.hint) {
+            console.error(chalk.yellow(`→ ${err.hint}`));
+        }
+        else {
+            console.error(chalk.dim(`  Add --verbose for details, or report: ${ISSUES_URL}`));
+        }
+        return;
+    }
+    // ── Other typed CliError (fallback for future codes) ──────────────────
+    if (err instanceof CliError) {
+        const icon = ERROR_ICONS[err.code] ?? '⚠️';
+        console.error(chalk.red(`${icon} ${err.message}`));
+        if (err.hint)
+            console.error(chalk.yellow(`→ ${err.hint}`));
+        return;
+    }
+    // ── 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, 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}`));
+        return;
+    }
+    // ── Unknown error: show stack in verbose mode ─────────────────────────
+    if (verbose && err instanceof Error && err.stack) {
+        console.error(chalk.red(err.stack));
+    }
+    else {
+        console.error(chalk.red(`💥 Unexpected error: ${msg}`));
+        console.error(chalk.dim(`  Run with --verbose for details, or report: ${ISSUES_URL}`));
+    }
+}
 /**
  * Register all commands from the registry onto a Commander program.
  */

package/dist/commanderAdapter.test.d.ts

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

package/dist/commanderAdapter.test.js

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Command } from 'commander';
+const { mockExecuteCommand, mockRenderOutput } = vi.hoisted(() => ({
+    mockExecuteCommand: vi.fn(),
+    mockRenderOutput: vi.fn(),
+}));
+vi.mock('./execution.js', () => ({
+    executeCommand: mockExecuteCommand,
+}));
+vi.mock('./output.js', () => ({
+    render: mockRenderOutput,
+}));
+import { registerCommandToProgram } from './commanderAdapter.js';
+describe('commanderAdapter arg passing', () => {
+    const cmd = {
+        site: 'paperreview',
+        name: 'submit',
+        description: 'Submit a PDF',
+        browser: false,
+        args: [
+            { name: 'pdf', positional: true, required: true, help: 'Path to the paper PDF' },
+            { name: 'dry-run', type: 'bool', default: false, help: 'Validate only' },
+            { name: 'prepare-only', type: 'bool', default: false, help: 'Prepare only' },
+        ],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.OPENCLI_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('passes bool flag values through to executeCommand for coercion', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'paperreview', 'submit', './paper.pdf', '--dry-run', 'false']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.pdf).toBe('./paper.pdf');
+        expect(kwargs).toHaveProperty('dry-run');
+    });
+    it('passes valueless bool flags as true to executeCommand', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'paperreview', 'submit', './paper.pdf', '--prepare-only']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.pdf).toBe('./paper.pdf');
+        expect(kwargs['prepare-only']).toBe(true);
+    });
+    it('rejects invalid bool values before calling executeCommand', async () => {
+        const program = new Command();
+        const siteCmd = program.command('paperreview');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'paperreview', 'submit', './paper.pdf', '--dry-run', 'maybe']);
+        // normalizeArgValue validates bools eagerly; executeCommand should not be reached
+        expect(mockExecuteCommand).not.toHaveBeenCalled();
+    });
+});

package/dist/daemon.js

@@ -25,6 +25,7 @@ const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_P
 const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
 // ─── State ───────────────────────────────────────────────────────────
 let extensionWs = null;
+let extensionVersion = null;
 const pending = new Map();
 let idleTimer = null;
 const LOG_BUFFER_SIZE = 200;
@@ -103,6 +104,7 @@ async function handleRequest(req, res) {
         jsonResponse(res, 200, {
             ok: true,
             extensionConnected: extensionWs?.readyState === WebSocket.OPEN,
+            extensionVersion,
             pending: pending.size,
         });
         return;
@@ -195,6 +197,11 @@ wss.on('connection', (ws) => {
     ws.on('message', (data) => {
         try {
             const msg = JSON.parse(data.toString());
+            // Handle hello message from extension (version handshake)
+            if (msg.type === 'hello') {
+                extensionVersion = typeof msg.version === 'string' ? msg.version : null;
+                return;
+            }
             // Handle log messages from extension
             if (msg.type === 'log') {
                 const prefix = msg.level === 'error' ? '❌' : msg.level === 'warn' ? '⚠️' : '📋';
@@ -219,6 +226,7 @@ wss.on('connection', (ws) => {
         clearInterval(heartbeatInterval);
         if (extensionWs === ws) {
             extensionWs = null;
+            extensionVersion = null;
             // Reject all pending requests since the extension is gone
             for (const [id, p] of pending) {
                 clearTimeout(p.timer);
@@ -229,8 +237,16 @@ wss.on('connection', (ws) => {
     });
     ws.on('error', () => {
         clearInterval(heartbeatInterval);
-        if (extensionWs === ws)
+        if (extensionWs === ws) {
             extensionWs = null;
+            extensionVersion = null;
+            // Reject pending requests in case 'close' does not follow this 'error'
+            for (const [, p] of pending) {
+                clearTimeout(p.timer);
+                p.reject(new Error('Extension disconnected'));
+            }
+            pending.clear();
+        }
     });
 });
 // ─── Start ───────────────────────────────────────────────────────────

package/dist/discovery.js

@@ -19,6 +19,7 @@ import { log } from './logger.js';
 export const PLUGINS_DIR = path.join(os.homedir(), '.opencli', '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;
@@ -71,6 +72,8 @@ async function loadFromManifest(manifestPath, clisDir) {
                     pipeline: entry.pipeline,
                     timeoutSeconds: entry.timeout,
                     source: `manifest:${entry.site}/${entry.name}`,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
                     navigateBefore: entry.navigateBefore,
                 };
                 registerCommand(cmd);
@@ -91,6 +94,8 @@ async function loadFromManifest(manifestPath, clisDir) {
                     columns: entry.columns,
                     timeoutSeconds: entry.timeout,
                     source: modulePath,
+                    deprecated: entry.deprecated,
+                    replacedBy: entry.replacedBy,
                     navigateBefore: entry.navigateBefore,
                     _lazy: true,
                     _modulePath: modulePath,
@@ -153,20 +158,7 @@ async function registerYamlCli(filePath, defaultSite) {
         const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
         const strategy = parseStrategy(strategyStr);
         const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
-        const args = [];
-        if (cliDef.args && typeof cliDef.args === 'object') {
-            for (const [argName, argDef] of Object.entries(cliDef.args)) {
-                args.push({
-                    name: argName,
-                    type: argDef?.type ?? 'str',
-                    default: argDef?.default,
-                    required: argDef?.required ?? false,
-                    positional: argDef?.positional ?? false,
-                    help: argDef?.description ?? argDef?.help ?? '',
-                    choices: argDef?.choices,
-                });
-            }
-        }
+        const args = parseYamlArgs(cliDef.args);
         const cmd = {
             site,
             name,
@@ -179,6 +171,8 @@ async function registerYamlCli(filePath, defaultSite) {
             pipeline: cliDef.pipeline,
             timeoutSeconds: cliDef.timeout,
             source: filePath,
+            deprecated: cliDef.deprecated,
+            replacedBy: cliDef.replacedBy,
             navigateBefore: cliDef.navigateBefore,
         };
         registerCommand(cmd);

package/dist/doctor.d.ts

@@ -20,6 +20,7 @@ export type DoctorReport = {
     cliVersion?: string;
     daemonRunning: boolean;
     extensionConnected: boolean;
+    extensionVersion?: string;
     connectivity?: ConnectivityResult;
     sessions?: Array<{
         workspace: string;

package/dist/doctor.js

@@ -10,6 +10,7 @@ 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.
  */
@@ -64,23 +65,29 @@ export async function runBrowserDoctor(opts = {}) {
     if (connectivity && !connectivity.ok) {
         issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
     }
+    if (status.extensionVersion && opts.cliVersion && status.extensionVersion !== opts.cliVersion) {
+        issues.push(`Extension 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`), ''];
+    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]');
-    lines.push(`${extIcon} Extension: ${report.extensionConnected ? 'connected' : 'not connected'}`);
+    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]');

package/dist/download/index.js

@@ -7,6 +7,8 @@ import * as path from 'node:path';
 import * as https from 'node:https';
 import * as http from 'node:http';
 import * as os from 'node:os';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { URL } from 'node:url';
 import { isBinaryInstalled } from '../external.js';
 import { getErrorMessage } from '../errors.js';
@@ -68,65 +70,75 @@ export async function httpDownload(url, destPath, options = {}, redirectCount =
         if (cookies) {
             requestHeaders['Cookie'] = cookies;
         }
-        // Ensure directory exists
-        const dir = path.dirname(destPath);
-        fs.mkdirSync(dir, { recursive: true });
         const tempPath = `${destPath}.tmp`;
-        const file = fs.createWriteStream(tempPath);
-        const request = protocol.get(url, { headers: requestHeaders, timeout }, (response) => {
-            // Handle redirects
-            if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-                file.close();
-                if (fs.existsSync(tempPath))
-                    fs.unlinkSync(tempPath);
-                if (redirectCount >= maxRedirects) {
-                    resolve({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
-                    return;
-                }
-                const redirectUrl = resolveRedirectUrl(url, response.headers.location);
-                const originalHost = new URL(url).hostname;
-                const redirectHost = new URL(redirectUrl).hostname;
-                // Do not forward cookies when a redirect crosses host boundaries.
-                const redirectOptions = originalHost === redirectHost
-                    ? options
-                    : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
-                httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1).then(resolve);
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
                 return;
+            settled = true;
+            resolve(result);
+        };
+        const cleanupTempFile = async () => {
+            try {
+                await fs.promises.rm(tempPath, { force: true });
             }
-            if (response.statusCode !== 200) {
-                file.close();
-                if (fs.existsSync(tempPath))
-                    fs.unlinkSync(tempPath);
-                resolve({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
-                return;
+            catch {
+                // Ignore cleanup errors so the original failure is preserved.
             }
-            const totalSize = parseInt(response.headers['content-length'] || '0', 10);
-            let received = 0;
-            response.on('data', (chunk) => {
-                received += chunk.length;
-                if (onProgress)
-                    onProgress(received, totalSize);
-            });
-            response.pipe(file);
-            file.on('finish', () => {
-                file.close();
-                // Rename temp file to final destination
-                fs.renameSync(tempPath, destPath);
-                resolve({ success: true, size: received });
-            });
+        };
+        const request = protocol.get(url, { headers: requestHeaders, timeout }, (response) => {
+            void (async () => {
+                // Handle redirects before creating any file handles.
+                if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+                    response.resume();
+                    if (redirectCount >= maxRedirects) {
+                        finish({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
+                        return;
+                    }
+                    const redirectUrl = resolveRedirectUrl(url, response.headers.location);
+                    const originalHost = new URL(url).hostname;
+                    const redirectHost = new URL(redirectUrl).hostname;
+                    const redirectOptions = originalHost === redirectHost
+                        ? options
+                        : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
+                    finish(await httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1));
+                    return;
+                }
+                if (response.statusCode !== 200) {
+                    response.resume();
+                    finish({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
+                    return;
+                }
+                const totalSize = parseInt(response.headers['content-length'] || '0', 10);
+                let received = 0;
+                const progressStream = new Transform({
+                    transform(chunk, _encoding, callback) {
+                        received += chunk.length;
+                        if (onProgress)
+                            onProgress(received, totalSize);
+                        callback(null, chunk);
+                    },
+                });
+                try {
+                    await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+                    await pipeline(response, progressStream, fs.createWriteStream(tempPath));
+                    await fs.promises.rename(tempPath, destPath);
+                    finish({ success: true, size: received });
+                }
+                catch (err) {
+                    await cleanupTempFile();
+                    finish({ success: false, size: 0, error: getErrorMessage(err) });
+                }
+            })();
         });
         request.on('error', (err) => {
-            file.close();
-            if (fs.existsSync(tempPath))
-                fs.unlinkSync(tempPath);
-            resolve({ success: false, size: 0, error: err.message });
+            void (async () => {
+                await cleanupTempFile();
+                finish({ success: false, size: 0, error: err.message });
+            })();
         });
         request.on('timeout', () => {
-            request.destroy();
-            file.close();
-            if (fs.existsSync(tempPath))
-                fs.unlinkSync(tempPath);
-            resolve({ success: false, size: 0, error: 'Timeout' });
+            request.destroy(new Error('Timeout'));
         });
     });
 }

package/dist/download/index.test.js

@@ -5,11 +5,19 @@ import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { formatCookieHeader, httpDownload, resolveRedirectUrl } from './index.js';
 const servers = [];
+const tempDirs = [];
 afterEach(async () => {
     await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
         server.close((err) => (err ? reject(err) : resolve()));
     })));
     servers.length = 0;
+    for (const dir of tempDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    tempDirs.length = 0;
 });
 async function startServer(handler, hostname = '127.0.0.1') {
     const server = http.createServer(handler);
@@ -21,7 +29,9 @@ async function startServer(handler, hostname = '127.0.0.1') {
     }
     return `http://${hostname}:${address.port}`;
 }
-describe('download helpers', () => {
+// Windows Defender can briefly lock newly-written .tmp files, causing EPERM.
+// Retry once to handle this flakiness.
+describe('download helpers', { retry: process.platform === 'win32' ? 2 : 0 }, () => {
     it('resolves relative redirects against the original URL', () => {
         expect(resolveRedirectUrl('https://example.com/a/file', '/cdn/file.bin')).toBe('https://example.com/cdn/file.bin');
         expect(resolveRedirectUrl('https://example.com/a/file', '../next')).toBe('https://example.com/next');
@@ -38,7 +48,8 @@ describe('download helpers', () => {
             res.setHeader('Location', '/loop');
             res.end();
         });
-        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-dl-'));
+        tempDirs.push(tempDir);
         const destPath = path.join(tempDir, 'file.txt');
         const result = await httpDownload(`${baseUrl}/loop`, destPath, { maxRedirects: 2 });
         expect(result).toEqual({
@@ -60,7 +71,8 @@ describe('download helpers', () => {
             res.setHeader('Location', targetUrl);
             res.end();
         });
-        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-dl-'));
+        tempDirs.push(tempDir);
         const destPath = path.join(tempDir, 'redirect.txt');
         const result = await httpDownload(`${redirectUrl}/start`, destPath, { cookies: 'sid=abc' });
         expect(result).toEqual({ success: true, size: 2 });
@@ -79,7 +91,8 @@ describe('download helpers', () => {
             res.setHeader('Location', targetUrl);
             res.end();
         });
-        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-download-'));
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-dl-'));
+        tempDirs.push(tempDir);
         const destPath = path.join(tempDir, 'redirect-header.txt');
         const result = await httpDownload(`${redirectUrl}/start`, destPath, {
             headers: { Cookie: 'sid=header-cookie' },