stealth-cli 0.5.0 → 0.6.0

package/src/browser.js

@@ -6,26 +6,16 @@
  *   2. Daemon mode  — reuses background browser (faster)
  */
 
-import { launchOptions } from 'camoufox-js';
-import { firefox } from 'playwright-core';
-import os from 'os';
 import { withRetry, navigateWithRetry } from './retry.js';
-import { randomDelay, postNavigationBehavior } from './humanize.js';
+import { postNavigationBehavior } from './humanize.js';
 import { isDaemonRunning } from './daemon.js';
-import { daemonNavigate, daemonText, daemonScreenshot, daemonRequest } from './client.js';
+import { daemonNavigate, daemonRequest } from './client.js';
 import { loadProfile, touchProfile, saveCookiesToProfile, loadCookiesFromProfile } from './profiles.js';
 import { restoreSession, captureSession } from './session.js';
-import { getNextProxy, getRandomProxy, reportProxy } from './proxy-pool.js';
-
-/**
- * Detect host OS for fingerprint matching
- */
-function getHostOS() {
-  const platform = os.platform();
-  if (platform === 'darwin') return 'macos';
-  if (platform === 'win32') return 'windows';
-  return 'linux';
-}
+import { getNextProxy } from './proxy-pool.js';
+import { getHostOS, createBrowser, extractPageText } from './utils/browser-factory.js';
+import { log } from './output.js';
+import { BrowserLaunchError, NavigationError } from './errors.js';
 
 /**
  * Build proxy configuration
@@ -93,7 +83,9 @@ export async function launchBrowser(opts = {}) {
         proxyStr = profileData.proxy;
       }
       touchProfile(profileName);
-    } catch {}
+    } catch (err) {
+      log.warn(`Profile "${profileName}" failed to load: ${err.message}`);
+    }
   }
 
   // --- Proxy pool rotation ---
@@ -115,16 +107,16 @@ export async function launchBrowser(opts = {}) {
   const hostOS = profileData?.fingerprint?.os || getHostOS();
   const proxy = buildProxy(proxyStr);
 
-  const options = await launchOptions({
-    headless,
-    os: hostOS,
-    humanize: true,
-    enable_cache: true,
-    proxy: proxy || undefined,
-    geoip: !!proxy,
-  });
-
-  const browser = await firefox.launch(options);
+  let browser;
+  try {
+    browser = await createBrowser({
+      headless,
+      os: hostOS,
+      proxy: proxy || undefined,
+    });
+  } catch (err) {
+    throw new BrowserLaunchError(err.message, { cause: err });
+  }
 
   const contextOptions = {
     viewport,
@@ -157,7 +149,9 @@ export async function launchBrowser(opts = {}) {
   if (sessionInfo?.lastUrl && sessionInfo.lastUrl !== 'about:blank') {
     try {
       await page.goto(sessionInfo.lastUrl, { waitUntil: 'domcontentloaded', timeout: 15000 });
-    } catch {}
+    } catch (err) {
+      log.warn(`Session URL restore failed (${sessionInfo.lastUrl}): ${err.message}`);
+    }
   }
 
   return {
@@ -205,26 +199,31 @@ export async function closeBrowser(handle) {
 export async function navigate(handle, url, opts = {}) {
   const { timeout = 30000, waitUntil = 'domcontentloaded', humanize = false, retries = 2 } = opts;
 
-  if (handle.isDaemon) {
-    const result = await withRetry(
-      async () => {
-        const res = await daemonNavigate(url, { timeout, waitUntil });
-        if (!res?.ok) throw new Error(res?.error || 'Daemon navigation failed');
-        return res.url;
-      },
-      { maxRetries: retries, label: `navigate(daemon)` },
-    );
-    return result;
-  }
+  try {
+    if (handle.isDaemon) {
+      const result = await withRetry(
+        async () => {
+          const res = await daemonNavigate(url, { timeout, waitUntil });
+          if (!res?.ok) throw new Error(res?.error || 'Daemon navigation failed');
+          return res.url;
+        },
+        { maxRetries: retries, label: `navigate(daemon)` },
+      );
+      return result;
+    }
 
-  const finalUrl = await navigateWithRetry(handle.page, url, { timeout, waitUntil, maxRetries: retries });
+    const finalUrl = await navigateWithRetry(handle.page, url, { timeout, waitUntil, maxRetries: retries });
 
-  // Human behavior after navigation
-  if (humanize) {
-    await postNavigationBehavior(handle.page);
-  }
+    // Human behavior after navigation
+    if (humanize) {
+      await postNavigationBehavior(handle.page);
+    }
 
-  return finalUrl;
+    return finalUrl;
+  } catch (err) {
+    if (err instanceof NavigationError) throw err;
+    throw new NavigationError(url, err);
+  }
 }
 
 /**
@@ -273,15 +272,7 @@ export async function getTextContent(handle) {
     return res?.text || '';
   }
 
-  return handle.page.evaluate(() => {
-    const body = document.body;
-    if (!body) return '';
-
-    const clone = body.cloneNode(true);
-    clone.querySelectorAll('script, style, noscript').forEach((el) => el.remove());
-
-    return clone.innerText || clone.textContent || '';
-  });
+  return handle.page.evaluate(extractPageText);
 }
 
 /**

package/src/commands/batch.js

@@ -11,6 +11,8 @@ import {
 import { navigateWithRetry } from '../retry.js';
 import { randomDelay } from '../humanize.js';
 import { formatOutput, log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerBatch(program) {
   program
@@ -30,6 +32,7 @@ export function registerBatch(program) {
     .option('--retries <n>', 'Max retries per URL', '2')
     .option('--skip-errors', 'Continue on errors instead of stopping')
     .action(async (file, opts) => {
+      opts = resolveOpts(opts);
       // Read URLs from file
       if (!fs.existsSync(file)) {
         log.error(`File not found: ${file}`);
@@ -81,10 +84,10 @@ export function registerBatch(program) {
 
           try {
             if (handle.isDaemon) {
-              await navigate(handle, url, { retries: parseInt(opts.retries) });
+              await navigate(handle, url, { retries: opts.retries });
             } else {
               await navigateWithRetry(handle.page, url, {
-                maxRetries: parseInt(opts.retries),
+                maxRetries: opts.retries,
               });
               await waitForReady(handle.page, { timeout: 3000 });
             }
@@ -159,7 +162,7 @@ export function registerBatch(program) {
 
           // Delay between URLs
           if (i < urls.length - 1) {
-            const delay = parseInt(opts.delay);
+            const delay = opts.delay;
             await randomDelay(delay * 0.8, delay * 1.2);
           }
         }
@@ -170,9 +173,8 @@ export function registerBatch(program) {
         log.success(`Batch complete: ${success} succeeded, ${failed} failed, ${urls.length} total`);
       } catch (err) {
         spinner.stop();
-        log.error(`Batch failed: ${err.message}`);
         log.dim(`  Completed: ${success}/${urls.length}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/browse.js

@@ -8,25 +8,28 @@ import {
   getTextContent, getTitle, getUrl, evaluate, waitForReady,
 } from '../browser.js';
 import { formatOutput, log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerBrowse(program) {
   program
     .command('browse')
     .description('Visit a URL and print page content')
     .argument('<url>', 'URL to visit')
-    .option('-f, --format <format>', 'Output format: text, json, markdown, snapshot', 'text')
+    .option('-f, --format <format>', 'Output format: text, json, markdown, snapshot')
     .option('-w, --wait <ms>', 'Wait time after page load (ms)', '2000')
     .option('--proxy <proxy>', 'Proxy server (http://user:pass@host:port)')
     .option('--cookies <file>', 'Load cookies from Netscape-format file')
     .option('--no-headless', 'Show browser window')
-    .option('--locale <locale>', 'Browser locale', 'en-US')
+    .option('--locale <locale>', 'Browser locale')
     .option('--user-agent', 'Print the browser user-agent')
     .option('--humanize', 'Enable human behavior simulation')
-    .option('--retries <n>', 'Max retries on failure', '2')
+    .option('--retries <n>', 'Max retries on failure')
     .option('--profile <name>', 'Use a browser profile')
     .option('--session <name>', 'Use/restore a named session')
     .option('--proxy-rotate', 'Rotate proxy from pool')
     .action(async (url, opts) => {
+      opts = resolveOpts(opts);
       const spinner = ora('Launching stealth browser...').start();
       let handle;
 
@@ -50,11 +53,11 @@ export function registerBrowse(program) {
         spinner.text = `Navigating to ${url}...`;
         await navigate(handle, url, {
           humanize: opts.humanize,
-          retries: parseInt(opts.retries),
+          retries: opts.retries,
         });
 
         if (!handle.isDaemon) {
-          await waitForReady(handle.page, { timeout: parseInt(opts.wait) });
+          await waitForReady(handle.page, { timeout: opts.wait });
         }
 
         spinner.stop();
@@ -92,8 +95,7 @@ export function registerBrowse(program) {
         log.success(`Done: ${currentUrl}`);
       } catch (err) {
         spinner.stop();
-        log.error(`Browse failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/crawl.js

@@ -7,6 +7,8 @@ import { launchBrowser, closeBrowser, getTextContent, evaluate, waitForReady } f
 import { navigateWithRetry } from '../retry.js';
 import { randomDelay, humanScroll } from '../humanize.js';
 import { formatOutput, log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerCrawl(program) {
   program
@@ -25,17 +27,18 @@ export function registerCrawl(program) {
     .option('--include <pattern>', 'Only crawl URLs matching this pattern (regex)')
     .option('--exclude <pattern>', 'Skip URLs matching this pattern (regex)')
     .option('--humanize', 'Enable human behavior simulation')
-    .option('--retries <n>', 'Max retries per page', '2')
+    .option('--retries <n>', 'Max retries per page')
     .option('--profile <name>', 'Use a browser profile')
     .option('--proxy-rotate', 'Rotate proxy from pool')
     .action(async (startUrl, opts) => {
+      opts = resolveOpts(opts);
       const spinner = ora('Launching stealth browser...').start();
       let handle;
 
-      const maxDepth = parseInt(opts.depth);
-      const maxPages = parseInt(opts.limit);
-      const delay = parseInt(opts.delay);
-      const maxRetries = parseInt(opts.retries);
+      const maxDepth = opts.depth;
+      const maxPages = opts.limit;
+      const delay = opts.delay;
+      const maxRetries = opts.retries;
       const includeRegex = opts.include ? new RegExp(opts.include) : null;
       const excludeRegex = opts.exclude ? new RegExp(opts.exclude) : null;
 
@@ -60,7 +63,7 @@ export function registerCrawl(program) {
         const startOrigin = new URL(startUrl).origin;
         const visited = new Set();
         const queue = [{ url: startUrl, depth: 0 }];
-        const results = [];
+        let resultCount = 0;
         let outputStream;
 
         if (opts.output) {
@@ -78,10 +81,10 @@ export function registerCrawl(program) {
           } else {
             console.log(line);
           }
-          results.push(result);
+          resultCount++;
         };
 
-        while (queue.length > 0 && results.length < maxPages) {
+        while (queue.length > 0 && resultCount < maxPages) {
           const { url, depth } = queue.shift();
 
           if (visited.has(url)) continue;
@@ -90,7 +93,7 @@ export function registerCrawl(program) {
           if (includeRegex && !includeRegex.test(url)) continue;
           if (excludeRegex && excludeRegex.test(url)) continue;
 
-          spinner.text = `[${results.length + 1}/${maxPages}] Crawling: ${url.slice(0, 60)}...`;
+          spinner.text = `[${resultCount + 1}/${maxPages}] Crawling: ${url.slice(0, 60)}...`;
 
           try {
             // Navigate with retry
@@ -154,14 +157,13 @@ export function registerCrawl(program) {
         if (outputStream) outputStream.end();
 
         spinner.stop();
-        log.success(`Crawl complete: ${results.length} pages crawled`);
+        log.success(`Crawl complete: ${resultCount} pages crawled`);
         log.dim(`  Start: ${startUrl}`);
         log.dim(`  Depth: ${maxDepth}, Visited: ${visited.size}`);
         if (opts.output) log.dim(`  Output: ${opts.output}`);
       } catch (err) {
         spinner.stop();
-        log.error(`Crawl failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/extract.js

@@ -8,6 +8,8 @@ import {
   getUrl, evaluate, waitForReady,
 } from '../browser.js';
 import { formatOutput, log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError, ExtractionError } from '../errors.js';
 
 export function registerExtract(program) {
   program
@@ -27,11 +29,12 @@ export function registerExtract(program) {
     .option('--cookies <file>', 'Load cookies from Netscape-format file')
     .option('--no-headless', 'Show browser window')
     .option('--humanize', 'Enable human behavior simulation')
-    .option('--retries <n>', 'Max retries on failure', '2')
+    .option('--retries <n>', 'Max retries on failure')
     .option('--profile <name>', 'Use a browser profile')
     .option('--session <name>', 'Use/restore a named session')
     .option('--proxy-rotate', 'Rotate proxy from pool')
     .action(async (url, opts) => {
+      opts = resolveOpts(opts);
       const spinner = ora('Launching stealth browser...').start();
       let handle;
 
@@ -52,11 +55,11 @@ export function registerExtract(program) {
         spinner.text = `Navigating to ${url}...`;
         await navigate(handle, url, {
           humanize: opts.humanize,
-          retries: parseInt(opts.retries),
+          retries: opts.retries,
         });
 
         if (!handle.isDaemon) {
-          await waitForReady(handle.page, { timeout: parseInt(opts.wait) });
+          await waitForReady(handle.page, { timeout: opts.wait });
         }
 
         spinner.text = 'Extracting data...';
@@ -115,18 +118,29 @@ export function registerExtract(program) {
             return headings;
           })()`);
         } else {
-          const selector = opts.selector;
-          const attr = opts.attr;
-          const all = opts.all;
-          result = await evalFn(`(() => {
-            const elements = ${all}
-              ? Array.from(document.querySelectorAll('${selector}'))
-              : [document.querySelector('${selector}')].filter(Boolean);
-            return elements.map(el => {
-              if ('${attr || ''}') return el.getAttribute('${attr || ''}');
-              return el.textContent?.trim() || '';
-            });
-          })()`);
+          // Use parameter passing (not string interpolation) to prevent injection
+          result = await handle.page.evaluate(
+            ({ selector, attr, all }) => {
+              const elements = all
+                ? Array.from(document.querySelectorAll(selector))
+                : [document.querySelector(selector)].filter(Boolean);
+              return elements.map(el => {
+                if (attr) return el.getAttribute(attr);
+                return el.textContent?.trim() || '';
+              });
+            },
+            { selector: opts.selector, attr: opts.attr || null, all: !!opts.all },
+          );
+        }
+
+        // Warn when custom selector matched nothing
+        if (opts.selector && opts.selector !== 'body' &&
+            (result === null || result === undefined ||
+             (Array.isArray(result) && result.length === 0))) {
+          throw new ExtractionError(
+            `No elements found matching "${opts.selector}"`,
+            { hint: `Check the CSS selector. Try: stealth browse <url> -f snapshot` },
+          );
         }
 
         const title = await getTitle(handle);
@@ -144,8 +158,7 @@ export function registerExtract(program) {
         log.success(`Extracted from: ${currentUrl}`);
       } catch (err) {
         spinner.stop();
-        log.error(`Extract failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/fingerprint.js

@@ -6,6 +6,8 @@ import ora from 'ora';
 import chalk from 'chalk';
 import { launchBrowser, closeBrowser, navigate, evaluate, waitForReady } from '../browser.js';
 import { log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerFingerprint(program) {
   program
@@ -18,7 +20,8 @@ export function registerFingerprint(program) {
     .option('--compare <n>', 'Launch N times and compare fingerprints for uniqueness', '1')
     .option('--no-headless', 'Show browser window')
     .action(async (opts) => {
-      const compareCount = parseInt(opts.compare);
+      opts = resolveOpts(opts);
+      const compareCount = opts.compare;
 
       if (compareCount > 1) {
         await compareFingerprints(compareCount, opts);
@@ -135,8 +138,7 @@ async function showFingerprint(opts) {
     console.log();
   } catch (err) {
     spinner.stop();
-    log.error(`Fingerprint check failed: ${err.message}`);
-    process.exit(1);
+    handleError(err, { log });
   } finally {
     if (handle) await closeBrowser(handle);
   }
@@ -239,8 +241,7 @@ async function runDetectionTests(opts) {
     }
   } catch (err) {
     spinner.stop();
-    log.error(`Detection tests failed: ${err.message}`);
-    process.exit(1);
+    handleError(err, { log });
   } finally {
     if (handle) await closeBrowser(handle);
   }

package/src/commands/interactive.js

@@ -12,6 +12,8 @@ import {
 import { expandMacro, getSupportedEngines } from '../macros.js';
 import { humanClick, humanType, humanScroll, randomDelay } from '../humanize.js';
 import { log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 const HELP_TEXT = `
 ${chalk.bold('Navigation:')}
@@ -53,6 +55,7 @@ export function registerInteractive(program) {
     .option('--no-headless', 'Show browser window')
     .option('--url <url>', 'Initial URL to open')
     .action(async (opts) => {
+      opts = resolveOpts(opts);
       const spinner = ora('Launching stealth browser...').start();
       let handle;
 
@@ -276,9 +279,8 @@ export function registerInteractive(program) {
         });
       } catch (err) {
         spinner.stop();
-        log.error(`Failed to start: ${err.message}`);
         if (handle) await closeBrowser(handle);
-        process.exit(1);
+        handleError(err, { log });
       }
     });
 }

package/src/commands/monitor.js

@@ -4,9 +4,11 @@
 
 import ora from 'ora';
 import chalk from 'chalk';
-import { launchBrowser, closeBrowser, navigate, evaluate, waitForReady } from '../browser.js';
+import { launchBrowser, closeBrowser, navigate, waitForReady } from '../browser.js';
 import { randomDelay } from '../humanize.js';
 import { log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerMonitor(program) {
   program
@@ -25,8 +27,9 @@ export function registerMonitor(program) {
     .option('--proxy-rotate', 'Rotate proxy from pool')
     .option('--no-headless', 'Show browser window')
     .action(async (url, opts) => {
-      const interval = parseInt(opts.interval) * 1000;
-      const maxChecks = parseInt(opts.count);
+      opts = resolveOpts(opts);
+      const interval = opts.interval * 1000;
+      const maxChecks = opts.count;
       const selector = opts.selector || 'body';
 
       log.info(`Monitoring ${url}`);
@@ -151,8 +154,7 @@ export function registerMonitor(program) {
         console.log();
         log.success(`Monitoring complete: ${checkCount} checks, ${changeCount} changes`);
       } catch (err) {
-        log.error(`Monitor failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/pdf.js

@@ -5,6 +5,8 @@
 import ora from 'ora';
 import { launchBrowser, closeBrowser, navigate, waitForReady } from '../browser.js';
 import { log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerPdf(program) {
   program
@@ -25,8 +27,9 @@ export function registerPdf(program) {
     .option('--cookies <file>', 'Load cookies from Netscape-format file')
     .option('--profile <name>', 'Use a browser profile')
     .option('--no-headless', 'Show browser window')
-    .option('--retries <n>', 'Max retries on failure', '2')
+    .option('--retries <n>', 'Max retries on failure')
     .action(async (url, opts) => {
+      opts = resolveOpts(opts);
       const spinner = ora('Launching stealth browser...').start();
       let handle;
 
@@ -50,8 +53,8 @@ export function registerPdf(program) {
         }
 
         spinner.text = `Navigating to ${url}...`;
-        await navigate(handle, url, { retries: parseInt(opts.retries) });
-        await waitForReady(handle.page, { timeout: parseInt(opts.wait) });
+        await navigate(handle, url, { retries: opts.retries });
+        await waitForReady(handle.page, { timeout: opts.wait });
 
         spinner.text = 'Generating PDF...';
 
@@ -100,8 +103,7 @@ export function registerPdf(program) {
         log.dim(`  Format: ${opts.format}${opts.landscape ? ' landscape' : ''}`);
       } catch (err) {
         spinner.stop();
-        log.error(`PDF failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/screenshot.js

@@ -5,6 +5,8 @@
 import ora from 'ora';
 import { launchBrowser, closeBrowser, navigate, takeScreenshot, getUrl, waitForReady } from '../browser.js';
 import { log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError } from '../errors.js';
 
 export function registerScreenshot(program) {
   program
@@ -21,11 +23,12 @@ export function registerScreenshot(program) {
     .option('--no-headless', 'Show browser window')
     .option('--quality <n>', 'JPEG quality (1-100), only for .jpg output')
     .option('--humanize', 'Enable human behavior simulation')
-    .option('--retries <n>', 'Max retries on failure', '2')
+    .option('--retries <n>', 'Max retries on failure')
     .option('--profile <name>', 'Use a browser profile')
     .option('--session <name>', 'Use/restore a named session')
     .option('--proxy-rotate', 'Rotate proxy from pool')
     .action(async (url, opts) => {
+      opts = resolveOpts(opts);
       const spinner = ora('Launching stealth browser...').start();
       let handle;
 
@@ -37,8 +40,8 @@ export function registerScreenshot(program) {
           profile: opts.profile,
           session: opts.session,
           viewport: {
-            width: parseInt(opts.width),
-            height: parseInt(opts.height),
+            width: opts.width,
+            height: opts.height,
           },
         });
 
@@ -51,11 +54,11 @@ export function registerScreenshot(program) {
         spinner.text = `Navigating to ${url}...`;
         await navigate(handle, url, {
           humanize: opts.humanize,
-          retries: parseInt(opts.retries),
+          retries: opts.retries,
         });
 
         if (!handle.isDaemon) {
-          await waitForReady(handle.page, { timeout: parseInt(opts.wait) });
+          await waitForReady(handle.page, { timeout: opts.wait });
         }
 
         spinner.text = 'Taking screenshot...';
@@ -72,7 +75,7 @@ export function registerScreenshot(program) {
 
           if (opts.output.endsWith('.jpg') || opts.output.endsWith('.jpeg')) {
             screenshotOpts.type = 'jpeg';
-            if (opts.quality) screenshotOpts.quality = parseInt(opts.quality);
+            if (opts.quality) screenshotOpts.quality = opts.quality;
           } else {
             screenshotOpts.type = 'png';
           }
@@ -87,8 +90,7 @@ export function registerScreenshot(program) {
         log.dim(`  Size: ${opts.width}x${opts.height}${opts.full ? ' (full page)' : ''}`);
       } catch (err) {
         spinner.stop();
-        log.error(`Screenshot failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }