@jackwener/opencli 1.4.0 → 1.5.0

package/src/commanderAdapter.ts

@@ -16,7 +16,32 @@ import { type CliCommand, 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: string | undefined, value: unknown, name: string): unknown {
+  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.
@@ -24,7 +49,8 @@ import { CliError, ERROR_ICONS, getErrorMessage } from './errors.js';
 export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void {
   if (siteCmd.commands.some((c: Command) => 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: typeof cmd.args = [];
@@ -51,24 +77,29 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
     const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts as Record<string, unknown> : {};
     const startTime = Date.now();
 
-    // ── Collect kwargs ──────────────────────────────────────────────────
-    const kwargs: Record<string, unknown> = {};
-    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: string) => ch.toUpperCase());
-      const v = optionsRecord[arg.name] ?? optionsRecord[camelName];
-      if (v !== undefined) kwargs[arg.name] = v;
-    }
-
     // ── Execute + render ────────────────────────────────────────────────
     try {
+      // ── Collect kwargs ────────────────────────────────────────────────
+      const kwargs: Record<string, unknown> = {};
+      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: string) => 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);
 
@@ -85,20 +116,153 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
         footerExtra: resolved.footerExtra?.(kwargs),
       });
     } 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: string): 'auth' | 'http' | 'not-found' | 'other' {
+  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: boolean, extensionConnected: boolean): void {
+  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: unknown, cmdName: string, verbose: boolean): Promise<void> {
+  // ── 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/src/daemon.ts

@@ -29,6 +29,7 @@ const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
 // ─── State ───────────────────────────────────────────────────────────
 
 let extensionWs: WebSocket | null = null;
+let extensionVersion: string | null = null;
 const pending = new Map<string, {
   resolve: (data: unknown) => void;
   reject: (error: Error) => void;
@@ -117,6 +118,7 @@ async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise
     jsonResponse(res, 200, {
       ok: true,
       extensionConnected: extensionWs?.readyState === WebSocket.OPEN,
+      extensionVersion,
       pending: pending.size,
     });
     return;
@@ -222,6 +224,12 @@ wss.on('connection', (ws: WebSocket) => {
     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' ? '⚠️' : '📋';
@@ -247,6 +255,7 @@ wss.on('connection', (ws: WebSocket) => {
     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);
@@ -258,7 +267,16 @@ wss.on('connection', (ws: WebSocket) => {
 
   ws.on('error', () => {
     clearInterval(heartbeatInterval);
-    if (extensionWs === ws) extensionWs = null;
+    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();
+    }
   });
 });
 

package/src/discovery.ts

@@ -23,7 +23,7 @@ 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 type { YamlCliDefinition } from './yaml-schema.js';
+import { type YamlCliDefinition, parseYamlArgs } from './yaml-schema.js';
 
 function parseStrategy(rawStrategy: string | undefined, fallback: Strategy = Strategy.COOKIE): Strategy {
   if (!rawStrategy) return fallback;
@@ -77,6 +77,8 @@ async function loadFromManifest(manifestPath: string, clisDir: string): Promise<
           pipeline: entry.pipeline,
           timeoutSeconds: entry.timeout,
           source: `manifest:${entry.site}/${entry.name}`,
+          deprecated: entry.deprecated,
+          replacedBy: entry.replacedBy,
           navigateBefore: entry.navigateBefore,
         };
         registerCommand(cmd);
@@ -96,6 +98,8 @@ async function loadFromManifest(manifestPath: string, clisDir: string): Promise<
           columns: entry.columns,
           timeoutSeconds: entry.timeout,
           source: modulePath,
+          deprecated: entry.deprecated,
+          replacedBy: entry.replacedBy,
           navigateBefore: entry.navigateBefore,
           _lazy: true,
           _modulePath: modulePath,
@@ -158,20 +162,7 @@ async function registerYamlCli(filePath: string, defaultSite: string): Promise<v
     const strategy = parseStrategy(strategyStr);
     const browser = cliDef.browser ?? (strategy !== Strategy.PUBLIC);
 
-    const args: Arg[] = [];
-    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: CliCommand = {
       site,
@@ -185,6 +176,8 @@ async function registerYamlCli(filePath: string, defaultSite: string): Promise<v
       pipeline: cliDef.pipeline,
       timeoutSeconds: cliDef.timeout,
       source: filePath,
+      deprecated: (cliDef as Record<string, unknown>).deprecated as boolean | string | undefined,
+      replacedBy: (cliDef as Record<string, unknown>).replacedBy as string | undefined,
       navigateBefore: cliDef.navigateBefore,
     };
 

package/src/doctor.ts

@@ -11,6 +11,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';
 
 export type DoctorOptions = {
   fix?: boolean;
@@ -30,6 +31,7 @@ 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[];
@@ -94,10 +96,18 @@ export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<Doctor
     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,
@@ -105,7 +115,7 @@ export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<Doctor
 }
 
 export function renderBrowserDoctorReport(report: DoctorReport): string {
-  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]');
@@ -113,7 +123,8 @@ export function renderBrowserDoctorReport(report: DoctorReport): string {
 
   // 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) {

package/src/download/index.test.ts

@@ -6,12 +6,17 @@ import { afterEach, describe, expect, it } from 'vitest';
 import { formatCookieHeader, httpDownload, resolveRedirectUrl } from './index.js';
 
 const servers: http.Server[] = [];
+const tempDirs: string[] = [];
 
 afterEach(async () => {
   await Promise.all(servers.map((server) => new Promise<void>((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: http.RequestListener, hostname = '127.0.0.1'): Promise<string> {
@@ -25,7 +30,9 @@ async function startServer(handler: http.RequestListener, 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');
@@ -45,7 +52,8 @@ describe('download helpers', () => {
       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 });
 
@@ -71,7 +79,8 @@ describe('download helpers', () => {
       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' });
 
@@ -94,7 +103,8 @@ describe('download helpers', () => {
       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' },

package/src/download/index.ts

@@ -8,6 +8,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 type { ProgressBar } from './progress.js';
 import { isBinaryInstalled } from '../external.js';
@@ -99,74 +101,84 @@ export async function httpDownload(
       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);
+    let settled = false;
 
-    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);
-        return;
-      }
+    const finish = (result: { success: boolean; size: number; error?: string }) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
 
-      if (response.statusCode !== 200) {
-        file.close();
-        if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
-        resolve({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
-        return;
+    const cleanupTempFile = async () => {
+      try {
+        await fs.promises.rm(tempPath, { force: true });
+      } 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: Buffer) => {
-        received += chunk.length;
-        if (onProgress) onProgress(received, totalSize);
-      });
+    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;
+        }
 
-      response.pipe(file);
+        if (response.statusCode !== 200) {
+          response.resume();
+          finish({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
+          return;
+        }
 
-      file.on('finish', () => {
-        file.close();
-        // Rename temp file to final destination
-        fs.renameSync(tempPath, destPath);
-        resolve({ success: true, size: received });
-      });
+        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'));
     });
   });
 }