stealth-cli 0.5.0 → 0.6.0

package/src/commands/search.js

@@ -12,6 +12,8 @@ import { getExtractorByEngine } from '../extractors/index.js';
 import * as googleExtractor from '../extractors/google.js';
 import { humanScroll, randomDelay, warmup } from '../humanize.js';
 import { formatOutput, log } from '../output.js';
+import { resolveOpts } from '../utils/resolve-opts.js';
+import { handleError, BlockedError } from '../errors.js';
 
 export function registerSearch(program) {
   program
@@ -19,18 +21,19 @@ export function registerSearch(program) {
     .description('Search the web with anti-detection')
     .argument('<engine>', `Search engine: ${getSupportedEngines().join(', ')}`)
     .argument('<query>', 'Search query')
-    .option('-f, --format <format>', 'Output format: text, json, snapshot', 'text')
+    .option('-f, --format <format>', 'Output format: text, json, snapshot')
     .option('-n, --num <n>', 'Max results to extract', '10')
     .option('--proxy <proxy>', 'Proxy server')
     .option('--no-headless', 'Show browser window')
     .option('--humanize', 'Simulate human behavior (auto for Google)')
     .option('--warmup', 'Visit a random site before searching (helps bypass detection)')
-    .option('--retries <n>', 'Max retries on failure', '2')
+    .option('--retries <n>', 'Max retries on failure')
     .option('--also-ask', 'Include "People also ask" questions (Google only)')
     .option('--profile <name>', 'Use a browser profile')
     .option('--session <name>', 'Use/restore a named session')
     .option('--proxy-rotate', 'Rotate proxy from pool')
     .action(async (engine, query, opts) => {
+      opts = resolveOpts(opts);
       const url = expandMacro(engine, query);
 
       if (!url) {
@@ -69,7 +72,7 @@ export function registerSearch(program) {
           if (!success) {
             // Fallback: direct URL navigation
             spinner.text = 'Fallback: direct navigation...';
-            await navigate(handle, url, { retries: parseInt(opts.retries) });
+            await navigate(handle, url, { retries: opts.retries });
           }
 
           await waitForReady(handle.page, { timeout: 5000 });
@@ -80,18 +83,7 @@ export function registerSearch(program) {
           const currentUrl = handle.page.url();
           if (googleExtractor.isBlocked(currentUrl)) {
             spinner.stop();
-            log.warn('Google detected automation and blocked the request');
-            log.dim('  Try: --proxy <proxy> or --warmup flag');
-            log.dim('  Or use a different engine: stealth search duckduckgo "..."');
-
-            if (opts.format === 'json') {
-              console.log(formatOutput({
-                engine, query, url: currentUrl,
-                blocked: true, results: [], count: 0,
-                timestamp: new Date().toISOString(),
-              }, 'json'));
-            }
-            return;
+            throw new BlockedError('Google', currentUrl);
           }
         }
         // --- Other engines: direct navigation ---
@@ -99,7 +91,7 @@ export function registerSearch(program) {
           spinner.text = `Navigating to ${engine}...`;
           await navigate(handle, url, {
             humanize: opts.humanize,
-            retries: parseInt(opts.retries),
+            retries: opts.retries,
           });
 
           if (!handle.isDaemon) {
@@ -120,7 +112,7 @@ export function registerSearch(program) {
           let alsoAsk = [];
 
           if (!handle.isDaemon) {
-            results = await extractor.extractResults(handle.page, parseInt(opts.num));
+            results = await extractor.extractResults(handle.page, opts.num);
 
             // Google "People also ask"
             if (isGoogle && opts.alsoAsk) {
@@ -153,8 +145,7 @@ export function registerSearch(program) {
         log.success(`Search complete: ${currentUrl}`);
       } catch (err) {
         spinner.stop();
-        log.error(`Search failed: ${err.message}`);
-        process.exit(1);
+        handleError(err, { log });
       } finally {
         if (handle) await closeBrowser(handle);
       }

package/src/commands/serve.js

@@ -6,10 +6,9 @@
  */
 
 import http from 'http';
-import { launchOptions } from 'camoufox-js';
-import { firefox } from 'playwright-core';
-import os from 'os';
+import crypto from 'crypto';
 import { log } from '../output.js';
+import { createBrowser, createContext, extractPageText } from '../utils/browser-factory.js';
 
 export function registerServe(program) {
   program
@@ -19,32 +18,42 @@ export function registerServe(program) {
     .option('--host <host>', 'Host to bind to', '127.0.0.1')
     .option('--proxy <proxy>', 'Default proxy for all requests')
     .option('--no-headless', 'Show browser window')
+    .option('--token <token>', 'API token for authentication (auto-generated if not set)')
+    .option('--no-auth', 'Disable authentication (only recommended on localhost)')
     .action(async (opts) => {
-      const port = parseInt(opts.port);
+      const port = parseInt(opts.port, 10);
       const host = opts.host;
+      const apiToken = opts.token || crypto.randomBytes(24).toString('hex');
 
       log.info('Starting stealth API server...');
 
       // Launch browser
-      const hostOS = os.platform() === 'darwin' ? 'macos' : os.platform() === 'win32' ? 'windows' : 'linux';
-      const options = await launchOptions({
-        headless: opts.headless,
-        os: hostOS,
-        humanize: true,
-        enable_cache: true,
-      });
-      const browser = await firefox.launch(options);
+      const browser = await createBrowser({ headless: opts.headless });
 
       // Page pool
       const pages = new Map(); // id → { page, context, lastUsed }
+      const MAX_TABS = 20;
       let idCounter = 0;
 
       async function createPage() {
-        const context = await browser.newContext({
-          viewport: { width: 1280, height: 720 },
-          locale: 'en-US',
-          timezoneId: 'America/Los_Angeles',
-        });
+        // Evict oldest tab if limit reached
+        if (pages.size >= MAX_TABS) {
+          let oldestId = null;
+          let oldestTime = Infinity;
+          for (const [id, entry] of pages) {
+            if (entry.lastUsed < oldestTime) {
+              oldestTime = entry.lastUsed;
+              oldestId = id;
+            }
+          }
+          if (oldestId) {
+            const old = pages.get(oldestId);
+            await old.context.close().catch(() => {});
+            pages.delete(oldestId);
+          }
+        }
+
+        const context = await createContext(browser);
         const page = await context.newPage();
         const id = `tab-${++idCounter}`;
         pages.set(id, { page, context, lastUsed: Date.now() });
@@ -83,13 +92,21 @@ export function registerServe(program) {
 
         try {
           const body = method === 'POST' ? await parseBody(req) : {};
-          const query = Object.fromEntries(url.searchParams);
 
-          // --- Health ---
+          // --- Health (no auth required) ---
           if (route === '/health') {
             return json(res, { ok: true, engine: 'camoufox', pages: pages.size });
           }
 
+          // --- Auth check ---
+          if (opts.auth !== false) {
+            const authHeader = req.headers['authorization'];
+            const token = authHeader ? authHeader.replace(/^Bearer\s+/i, '') : '';
+            if (token !== apiToken) {
+              return json(res, { error: 'Unauthorized. Use: -H "Authorization: Bearer <token>"' }, 401);
+            }
+          }
+
           // --- Create tab ---
           if (route === '/tabs' && method === 'POST') {
             const { url: targetUrl } = body;
@@ -130,11 +147,7 @@ export function registerServe(program) {
               }
 
               case 'text': {
-                const text = await page.evaluate(() => {
-                  const c = document.body.cloneNode(true);
-                  c.querySelectorAll('script,style,noscript').forEach((e) => e.remove());
-                  return c.innerText || '';
-                });
+                const text = await page.evaluate(extractPageText);
                 return json(res, { ok: true, text, url: page.url() });
               }
 
@@ -213,6 +226,12 @@ export function registerServe(program) {
 
       server.listen(port, host, () => {
         log.success(`Stealth API server running on http://${host}:${port}`);
+        if (opts.auth !== false) {
+          log.info(`API Token: ${apiToken}`);
+          log.dim(`  Use: curl -H "Authorization: Bearer ${apiToken}" ...`);
+        } else {
+          log.warn('Authentication disabled (--no-auth)');
+        }
         log.dim('  Endpoints:');
         log.dim('    GET  /health                    — Server status');
         log.dim('    POST /tabs                      — Create tab { url }');

package/src/daemon.js

@@ -14,8 +14,7 @@ import http from 'http';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { launchOptions } from 'camoufox-js';
-import { firefox } from 'playwright-core';
+import { createBrowser, createContext, extractPageText } from './utils/browser-factory.js';
 
 const STEALTH_DIR = path.join(os.homedir(), '.stealth');
 const SOCKET_PATH = path.join(STEALTH_DIR, 'daemon.sock');
@@ -50,16 +49,6 @@ function cleanup() {
   try { fs.unlinkSync(PID_PATH); } catch {}
 }
 
-/**
- * Get host OS for fingerprint
- */
-function getHostOS() {
-  const platform = os.platform();
-  if (platform === 'darwin') return 'macos';
-  if (platform === 'win32') return 'windows';
-  return 'linux';
-}
-
 /**
  * Start the daemon server
  */
@@ -81,13 +70,7 @@ export async function startDaemon(opts = {}) {
 
   // Launch browser
   log('Launching Camoufox browser...');
-  const options = await launchOptions({
-    headless: true,
-    os: getHostOS(),
-    humanize: true,
-    enable_cache: true,
-  });
-  const browser = await firefox.launch(options);
+  const browser = await createBrowser({ headless: true });
   log('Browser launched');
 
   // Track contexts for reuse
@@ -121,19 +104,7 @@ export async function startDaemon(opts = {}) {
       }
     }
 
-    const {
-      locale = 'en-US',
-      timezone = 'America/Los_Angeles',
-      viewport = { width: 1280, height: 720 },
-    } = contextOpts;
-
-    const context = await browser.newContext({
-      viewport,
-      locale,
-      timezoneId: timezone,
-      permissions: ['geolocation'],
-      geolocation: { latitude: 37.7749, longitude: -122.4194 },
-    });
+    const context = await createContext(browser, contextOpts);
 
     const page = await context.newPage();
     const entry = { context, page, lastUsed: Date.now() };
@@ -202,11 +173,7 @@ export async function startDaemon(opts = {}) {
       if (route === '/text') {
         const { key = 'default' } = body;
         const ctx = await getOrCreateContext(key);
-        const text = await ctx.page.evaluate(() => {
-          const clone = document.body.cloneNode(true);
-          clone.querySelectorAll('script, style, noscript').forEach((el) => el.remove());
-          return clone.innerText || '';
-        });
+        const text = await ctx.page.evaluate(extractPageText);
         res.end(JSON.stringify({ ok: true, text, url: ctx.page.url() }));
         return;
       }

package/src/errors.js

@@ -42,7 +42,7 @@ export class NavigationError extends StealthError {
   constructor(url, cause) {
     const msg = `Failed to navigate to ${url}`;
     let hint = 'Check the URL and your network connection';
-    if (cause?.message?.includes('timeout')) {
+    if (cause?.message?.toLowerCase().includes('timeout')) {
       hint = 'Page load timed out. Try --wait <ms> or --retries <n>';
     } else if (cause?.message?.includes('net::ERR_')) {
       hint = 'Network error. Check DNS, proxy, or firewall';
@@ -103,20 +103,31 @@ export class BlockedError extends StealthError {
 
 /**
  * Format and print error with hint, then exit
+ *
+ * @param {Error} err - The error to handle
+ * @param {object} [opts]
+ * @param {object} [opts.log] - Logger (default: console with stderr)
+ * @param {boolean} [opts.exit=true] - Whether to call process.exit
  */
-export function handleError(err) {
-  const { log } = loadOutput();
+export function handleError(err, opts = {}) {
+  const { exit = true } = opts;
+
+  // Use provided log or fallback to stderr console
+  const log = opts.log || {
+    error: (msg) => console.error(`\x1b[31m✖\x1b[0m ${msg}`),
+    dim: (msg) => console.error(`\x1b[2m${msg}\x1b[0m`),
+  };
 
   if (err instanceof StealthError) {
     log.error(err.message);
     if (err.hint) log.dim(`  Hint: ${err.hint}`);
-    process.exit(err.code);
+    if (exit) process.exit(err.code);
+    return err.code;
   }
 
-  // Unknown error
+  // Unknown error — detect common patterns and add helpful hints
   log.error(err.message || String(err));
 
-  // Common error patterns → helpful hints
   const msg = err.message || '';
   if (msg.includes('ECONNREFUSED')) {
     log.dim('  Hint: Connection refused. Is the target server running?');
@@ -124,13 +135,10 @@ export function handleError(err) {
     log.dim('  Hint: DNS lookup failed. Check the URL');
   } else if (msg.includes('camoufox')) {
     log.dim('  Hint: Try: npx camoufox-js fetch');
+  } else if (msg.includes('timeout') || msg.includes('Timeout')) {
+    log.dim('  Hint: Try increasing --retries or --wait');
   }
 
-  process.exit(1);
-}
-
-// Lazy import to avoid circular dependency
-function loadOutput() {
-  // Use dynamic require-like pattern
-  return { log: console };
+  if (exit) process.exit(1);
+  return 1;
 }

package/src/mcp-server.js

@@ -18,9 +18,11 @@
  *   }
  */
 
-import { launchOptions } from 'camoufox-js';
-import { firefox } from 'playwright-core';
-import os from 'os';
+import { createRequire } from 'module';
+import { createBrowser, createContext, extractPageText } from './utils/browser-factory.js';
+
+const require = createRequire(import.meta.url);
+const { version: PKG_VERSION } = require('../package.json');
 
 // --- MCP Protocol Implementation (stdio JSON-RPC) ---
 
@@ -123,9 +125,7 @@ class McpServer {
 
   async ensureBrowser() {
     if (this.browser && this.browser.isConnected()) return this.browser;
-    const hostOS = os.platform() === 'darwin' ? 'macos' : os.platform() === 'win32' ? 'windows' : 'linux';
-    const options = await launchOptions({ headless: true, os: hostOS, humanize: true, enable_cache: true });
-    this.browser = await firefox.launch(options);
+    this.browser = await createBrowser();
     return this.browser;
   }
 
@@ -140,11 +140,7 @@ class McpServer {
       }
     }
     await this.ensureBrowser();
-    const context = await this.browser.newContext({
-      viewport: { width: 1280, height: 720 },
-      locale: 'en-US',
-      timezoneId: 'America/Los_Angeles',
-    });
+    const context = await createContext(this.browser);
     const page = await context.newPage();
     const entry = { context, page };
     this.contexts.set(key, entry);
@@ -164,11 +160,7 @@ class McpServer {
           return text(`URL: ${page.url()}\n\n${snapshot}`);
         }
 
-        const content = await page.evaluate(() => {
-          const c = document.body.cloneNode(true);
-          c.querySelectorAll('script,style,noscript').forEach((e) => e.remove());
-          return c.innerText || '';
-        });
+        const content = await page.evaluate(extractPageText);
         const title = await page.title().catch(() => '');
         return text(`Title: ${title}\nURL: ${page.url()}\n\n${content.slice(0, 15000)}`);
       }
@@ -190,11 +182,26 @@ class McpServer {
         const isGoogle = args.engine === 'google';
 
         if (isGoogle) {
+          const { humanType, randomDelay } = await import('./humanize.js');
           await page.goto('https://www.google.com', { waitUntil: 'domcontentloaded', timeout: 15000 });
-          await page.waitForTimeout(1000);
+          await randomDelay(800, 2000);
+
+          // Handle cookie consent (EU/UK)
+          try {
+            const consentBtn = page.locator(
+              'button:has-text("Accept all"), button:has-text("Accept"), button:has-text("I agree")',
+            );
+            if (await consentBtn.first().isVisible({ timeout: 1500 })) {
+              await consentBtn.first().click({ timeout: 2000 });
+              await randomDelay(500, 1000);
+            }
+          } catch {}
+
+          // Human-like typing (consistent with CLI search command)
           try {
-            await page.fill('textarea[name="q"], input[name="q"]', args.query);
-            await page.keyboard.press('Enter');
+            await humanType(page, 'textarea[name="q"], input[name="q"]', args.query, {
+              pressEnter: true,
+            });
           } catch {
             await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
           }
@@ -284,7 +291,7 @@ class McpServer {
             result = {
               protocolVersion: '2024-11-05',
               capabilities: { tools: {} },
-              serverInfo: { name: 'stealth-cli', version: '0.4.0' },
+              serverInfo: { name: 'stealth-cli', version: PKG_VERSION },
             };
             break;
 

package/src/profiles.js

@@ -14,6 +14,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
+import { ProfileError } from './errors.js';
 
 const PROFILES_DIR = path.join(os.homedir(), '.stealth', 'profiles');
 
@@ -148,7 +149,7 @@ export function createProfile(name, opts = {}) {
   const filePath = profilePath(name);
 
   if (fs.existsSync(filePath)) {
-    throw new Error(`Profile "${name}" already exists. Use --force to overwrite.`);
+    throw new ProfileError(`Profile "${name}" already exists. Use --force to overwrite.`);
   }
 
   let fingerprint;
@@ -156,7 +157,7 @@ export function createProfile(name, opts = {}) {
   if (opts.preset) {
     fingerprint = FINGERPRINT_PRESETS[opts.preset];
     if (!fingerprint) {
-      throw new Error(`Unknown preset "${opts.preset}". Available: ${Object.keys(FINGERPRINT_PRESETS).join(', ')}`);
+      throw new ProfileError(`Unknown preset "${opts.preset}". Available: ${Object.keys(FINGERPRINT_PRESETS).join(', ')}`, { hint: 'Run: stealth profile presets' });
     }
     fingerprint = { ...fingerprint }; // Clone
   } else if (opts.random || !opts.locale) {
@@ -193,7 +194,7 @@ export function loadProfile(name) {
   const filePath = profilePath(name);
 
   if (!fs.existsSync(filePath)) {
-    throw new Error(`Profile "${name}" not found. Create with: stealth profile create ${name}`);
+    throw new ProfileError(`Profile "${name}" not found`, { hint: `Create with: stealth profile create ${name}` });
   }
 
   return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
@@ -286,7 +287,7 @@ export function listProfiles() {
 export function deleteProfile(name) {
   const filePath = profilePath(name);
   if (!fs.existsSync(filePath)) {
-    throw new Error(`Profile "${name}" not found`);
+    throw new ProfileError(`Profile "${name}" not found`);
   }
   fs.unlinkSync(filePath);
 }

package/src/proxy-pool.js

@@ -7,6 +7,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { ProxyError } from './errors.js';
 
 const STEALTH_DIR = path.join(os.homedir(), '.stealth');
 const PROXIES_FILE = path.join(STEALTH_DIR, 'proxies.json');
@@ -25,7 +26,10 @@ function loadData() {
 
 function saveData(data) {
   ensureDir();
-  fs.writeFileSync(PROXIES_FILE, JSON.stringify(data, null, 2));
+  // Atomic write: write to temp file then rename (prevents corruption on crash)
+  const tmpPath = PROXIES_FILE + '.tmp';
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+  fs.renameSync(tmpPath, PROXIES_FILE);
 }
 
 /**
@@ -158,8 +162,7 @@ export function reportProxy(proxyUrl, success, latencyMs = null) {
  * Test a proxy by making a request
  */
 export async function testProxy(proxyUrl) {
-  const { launchOptions } = await import('camoufox-js');
-  const { firefox } = await import('playwright-core');
+  const { createBrowser } = await import('./utils/browser-factory.js');
 
   const start = Date.now();
   let browser;
@@ -175,15 +178,10 @@ export async function testProxy(proxyUrl) {
         password: url.password || undefined,
       };
     } catch {
-      throw new Error(`Invalid proxy URL: ${proxyUrl}`);
+      throw new ProxyError(proxyUrl, new Error('Invalid proxy URL format'));
     }
 
-    const options = await launchOptions({
-      headless: true,
-      proxy: proxyConfig,
-    });
-
-    browser = await firefox.launch(options);
+    browser = await createBrowser({ headless: true, proxy: proxyConfig });
     const context = await browser.newContext();
     const page = await context.newPage();
 

package/src/session.js

@@ -66,12 +66,12 @@ export async function captureSession(name, context, page, opts = {}) {
   // Save cookies
   try {
     session.cookies = await context.cookies();
-  } catch {}
+  } catch { /* context may be closed */ }
 
   // Save current URL
   try {
     session.lastUrl = page.url();
-  } catch {}
+  } catch { /* page may be closed */ }
 
   // Append to history
   if (session.lastUrl && session.lastUrl !== 'about:blank') {
@@ -113,7 +113,7 @@ export async function restoreSession(name, context) {
       if (validCookies.length > 0) {
         await context.addCookies(validCookies);
       }
-    } catch {}
+    } catch { /* cookies may have invalid format */ }
   }
 
   return {

package/src/utils/browser-factory.js

@@ -0,0 +1,86 @@
+/**
+ * Shared browser bootstrap utilities
+ * Eliminates duplication across browser.js, daemon.js, serve.js, mcp-server.js
+ */
+
+import os from 'os';
+import { launchOptions } from 'camoufox-js';
+import { firefox } from 'playwright-core';
+
+/**
+ * Detect host OS for Camoufox fingerprint matching
+ */
+export function getHostOS() {
+  const platform = os.platform();
+  if (platform === 'darwin') return 'macos';
+  if (platform === 'win32') return 'windows';
+  return 'linux';
+}
+
+/**
+ * Launch a Camoufox browser instance with standard settings
+ *
+ * @param {object} opts
+ * @param {boolean} [opts.headless=true]
+ * @param {string} [opts.os] - Override OS (default: auto-detect)
+ * @param {object} [opts.proxy] - { server, username?, password? }
+ * @returns {Promise<import('playwright-core').Browser>}
+ */
+export async function createBrowser(opts = {}) {
+  const {
+    headless = true,
+    os: targetOS,
+    proxy,
+  } = opts;
+
+  const options = await launchOptions({
+    headless,
+    os: targetOS || getHostOS(),
+    // Camoufox's `humanize` controls low-level fingerprint randomization (canvas noise, etc.)
+    // This is NOT the same as stealth-cli's --humanize flag (which controls mouse/scroll/type simulation).
+    // Always enabled for anti-detection effectiveness.
+    humanize: true,
+    enable_cache: true,
+    proxy: proxy || undefined,
+    geoip: !!proxy,
+  });
+
+  return firefox.launch(options);
+}
+
+/**
+ * Create a standard browser context
+ *
+ * @param {import('playwright-core').Browser} browser
+ * @param {object} opts
+ * @returns {Promise<import('playwright-core').BrowserContext>}
+ */
+export async function createContext(browser, opts = {}) {
+  const {
+    locale = 'en-US',
+    timezone = 'America/Los_Angeles',
+    viewport = { width: 1280, height: 720 },
+    geo = { latitude: 37.7749, longitude: -122.4194 },
+  } = opts;
+
+  return browser.newContext({
+    viewport,
+    locale,
+    timezoneId: timezone,
+    permissions: ['geolocation'],
+    geolocation: geo,
+  });
+}
+
+/**
+ * Extract visible text from a page.
+ * Pass directly to page.evaluate() — must not reference Node.js scope.
+ * Using a function (not a string) avoids eval-injection risks.
+ */
+export function extractPageText() {
+  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 || '';
+}