fix(pipeline): harden intercept, tap, and download steps

src/download/index.test.ts

@@ -49,11 +49,11 @@ describe('download helpers', () => {
     const destPath = path.join(tempDir, 'file.txt');
     const result = await httpDownload(`${baseUrl}/loop`, destPath, { maxRedirects: 2 });
 
-    expect(result).toEqual({
+    expect(result).toEqual(expect.objectContaining({
       success: false,
       size: 0,
       error: 'Too many redirects (> 2)',
-    });
+    }));
     expect(fs.existsSync(destPath)).toBe(false);
   });
 });

src/download/index.ts

@@ -23,6 +23,15 @@ export interface DownloadOptions {
   maxRedirects?: number;
 }
 
+export interface HttpDownloadResult {
+  success: boolean;
+  size: number;
+  error?: string;
+  statusCode?: number;
+  contentType?: string;
+  finalUrl?: string;
+}
+
 export interface YtdlpOptions {
   cookies?: string;
   cookiesFile?: string;
@@ -82,7 +91,7 @@ export async function httpDownload(
   destPath: string,
   options: DownloadOptions = {},
   redirectCount = 0,
-): Promise<{ success: boolean; size: number; error?: string }> {
+): Promise<HttpDownloadResult> {
   const { cookies, headers = {}, timeout = 30000, onProgress, maxRedirects = 10 } = options;
 
   return new Promise((resolve) => {
@@ -111,7 +120,7 @@ export async function httpDownload(
         file.close();
         if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
         if (redirectCount >= maxRedirects) {
-          resolve({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
+          resolve({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})`, finalUrl: url });
           return;
         }
         httpDownload(
@@ -126,7 +135,14 @@ export async function httpDownload(
       if (response.statusCode !== 200) {
         file.close();
         if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
-        resolve({ success: false, size: 0, error: `HTTP ${response.statusCode}` });
+        resolve({
+          success: false,
+          size: 0,
+          error: `HTTP ${response.statusCode}`,
+          statusCode: response.statusCode,
+          contentType: normalizeHeaderValue(response.headers['content-type']),
+          finalUrl: url,
+        });
         return;
       }
 
@@ -144,21 +160,27 @@ export async function httpDownload(
         file.close();
         // Rename temp file to final destination
         fs.renameSync(tempPath, destPath);
-        resolve({ success: true, size: received });
+        resolve({
+          success: true,
+          size: received,
+          statusCode: response.statusCode,
+          contentType: normalizeHeaderValue(response.headers['content-type']),
+          finalUrl: url,
+        });
       });
     });
 
     request.on('error', (err) => {
       file.close();
       if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
-      resolve({ success: false, size: 0, error: err.message });
+      resolve({ success: false, size: 0, error: err.message, finalUrl: url });
     });
 
     request.on('timeout', () => {
       request.destroy();
       file.close();
       if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath);
-      resolve({ success: false, size: 0, error: 'Timeout' });
+      resolve({ success: false, size: 0, error: 'Timeout', finalUrl: url });
     });
   });
 }
@@ -167,6 +189,10 @@ export function resolveRedirectUrl(currentUrl: string, location: string): string
   return new URL(location, currentUrl).toString();
 }
 
+function normalizeHeaderValue(header: string | string[] | undefined): string | undefined {
+  return Array.isArray(header) ? header[0] : header;
+}
+
 /**
  * Export cookies to Netscape format for yt-dlp.
  */

src/pipeline/executor.test.ts

@@ -4,6 +4,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { executePipeline } from './index.js';
+import { getStep, registerStep } from './registry.js';
 import { ConfigError } from '../errors.js';
 import type { IPage } from '../types.js';
 
@@ -189,4 +190,29 @@ describe('executePipeline', () => {
     expect(result).toEqual([{ a: 1 }]);
     expect(page.goto).toHaveBeenCalledWith('https://example.com');
   });
+
+  it.each(['intercept', 'tap'])('retries transient browser errors for %s step', async (stepName) => {
+    const original = getStep(stepName);
+    expect(original).toBeDefined();
+
+    let attempts = 0;
+    registerStep(stepName, async () => {
+      attempts += 1;
+      if (attempts === 1) {
+        throw new Error('Extension disconnected');
+      }
+      return 'ok';
+    });
+
+    try {
+      const result = await executePipeline(null, [
+        { [stepName]: {} },
+      ]);
+
+      expect(result).toBe('ok');
+      expect(attempts).toBe(2);
+    } finally {
+      registerStep(stepName, original!);
+    }
+  });
 });

src/pipeline/executor.ts

@@ -16,7 +16,7 @@ export interface PipelineContext {
 }
 
 /** Steps that interact with the browser and may fail transiently */
-const BROWSER_STEPS = new Set(['navigate', 'evaluate', 'click', 'type', 'press', 'wait', 'snapshot', 'scroll']);
+const BROWSER_STEPS = new Set(['navigate', 'evaluate', 'click', 'type', 'press', 'wait', 'snapshot', 'scroll', 'intercept', 'tap', 'download']);
 
 export async function executePipeline(
   page: IPage | null,