stealth-cli 0.5.0

package/src/daemon.js

@@ -0,0 +1,294 @@
+/**
+ * Daemon mode — keeps browser alive in background for instant reuse
+ *
+ * Architecture:
+ *   1. `stealth daemon start` spawns a background HTTP server on a unix socket
+ *   2. CLI commands detect the daemon and send requests via HTTP
+ *   3. Daemon auto-shuts down after idle timeout (default 5 min)
+ *
+ * Socket: ~/.stealth/daemon.sock
+ * PID:    ~/.stealth/daemon.pid
+ */
+
+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';
+
+const STEALTH_DIR = path.join(os.homedir(), '.stealth');
+const SOCKET_PATH = path.join(STEALTH_DIR, 'daemon.sock');
+const PID_PATH = path.join(STEALTH_DIR, 'daemon.pid');
+const DEFAULT_IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+
+export { SOCKET_PATH, PID_PATH, STEALTH_DIR };
+
+/**
+ * Check if daemon is currently running
+ */
+export function isDaemonRunning() {
+  try {
+    if (!fs.existsSync(PID_PATH)) return false;
+    const pid = parseInt(fs.readFileSync(PID_PATH, 'utf-8').trim());
+    // Check if process is alive
+    process.kill(pid, 0);
+    // Also check if socket exists
+    return fs.existsSync(SOCKET_PATH);
+  } catch {
+    // Process not found or permission error
+    cleanup();
+    return false;
+  }
+}
+
+/**
+ * Clean up stale socket/pid files
+ */
+function cleanup() {
+  try { fs.unlinkSync(SOCKET_PATH); } catch {}
+  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
+ */
+export async function startDaemon(opts = {}) {
+  const { idleTimeout = DEFAULT_IDLE_TIMEOUT, verbose = false } = opts;
+
+  // Ensure directory exists
+  fs.mkdirSync(STEALTH_DIR, { recursive: true });
+
+  // Clean up stale files
+  cleanup();
+
+  const log = (msg) => {
+    if (verbose) {
+      const ts = new Date().toISOString();
+      process.stdout.write(`[${ts}] ${msg}\n`);
+    }
+  };
+
+  // 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);
+  log('Browser launched');
+
+  // Track contexts for reuse
+  // key → { context, page, lastUsed }
+  const contexts = new Map();
+  let idleTimer = null;
+
+  function resetIdleTimer() {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(async () => {
+      log('Idle timeout reached, shutting down...');
+      await shutdown();
+    }, idleTimeout);
+  }
+
+  async function getOrCreateContext(key = 'default', contextOpts = {}) {
+    resetIdleTimer();
+
+    if (contexts.has(key)) {
+      const ctx = contexts.get(key);
+      ctx.lastUsed = Date.now();
+
+      // Check if page is still alive
+      try {
+        await ctx.page.evaluate('1');
+        return ctx;
+      } catch {
+        // Page died, recreate
+        try { await ctx.context.close(); } catch {}
+        contexts.delete(key);
+      }
+    }
+
+    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 page = await context.newPage();
+    const entry = { context, page, lastUsed: Date.now() };
+    contexts.set(key, entry);
+
+    return entry;
+  }
+
+  // Handle JSON request body
+  function parseBody(req) {
+    return new Promise((resolve, reject) => {
+      let body = '';
+      req.on('data', (chunk) => { body += chunk; });
+      req.on('end', () => {
+        try {
+          resolve(body ? JSON.parse(body) : {});
+        } catch (e) {
+          reject(new Error('Invalid JSON'));
+        }
+      });
+      req.on('error', reject);
+    });
+  }
+
+  // HTTP server on unix socket
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Content-Type', 'application/json');
+
+    try {
+      const body = await parseBody(req);
+      const url = new URL(req.url, 'http://localhost');
+      const route = url.pathname;
+
+      resetIdleTimer();
+
+      // --- Routes ---
+
+      if (route === '/status') {
+        res.end(JSON.stringify({
+          ok: true,
+          pid: process.pid,
+          uptime: Math.floor(process.uptime()),
+          contexts: contexts.size,
+          browserConnected: browser.isConnected(),
+          memoryMB: Math.round(process.memoryUsage().rss / 1024 / 1024),
+        }));
+        return;
+      }
+
+      if (route === '/navigate') {
+        const { key = 'default', url: targetUrl, waitUntil = 'domcontentloaded', timeout = 30000 } = body;
+        const ctx = await getOrCreateContext(key);
+        await ctx.page.goto(targetUrl, { waitUntil, timeout });
+        res.end(JSON.stringify({ ok: true, url: ctx.page.url() }));
+        return;
+      }
+
+      if (route === '/snapshot') {
+        const { key = 'default' } = body;
+        const ctx = await getOrCreateContext(key);
+        const snapshot = await ctx.page.locator('body').ariaSnapshot({ timeout: 8000 }).catch(() => '');
+        res.end(JSON.stringify({ ok: true, snapshot, url: ctx.page.url() }));
+        return;
+      }
+
+      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 || '';
+        });
+        res.end(JSON.stringify({ ok: true, text, url: ctx.page.url() }));
+        return;
+      }
+
+      if (route === '/screenshot') {
+        const { key = 'default', fullPage = false } = body;
+        const ctx = await getOrCreateContext(key);
+        const buffer = await ctx.page.screenshot({ type: 'png', fullPage });
+        res.end(JSON.stringify({ ok: true, data: buffer.toString('base64'), url: ctx.page.url() }));
+        return;
+      }
+
+      if (route === '/evaluate') {
+        const { key = 'default', expression } = body;
+        const ctx = await getOrCreateContext(key);
+        const result = await ctx.page.evaluate(expression);
+        res.end(JSON.stringify({ ok: true, result }));
+        return;
+      }
+
+      if (route === '/title') {
+        const { key = 'default' } = body;
+        const ctx = await getOrCreateContext(key);
+        const title = await ctx.page.title();
+        res.end(JSON.stringify({ ok: true, title, url: ctx.page.url() }));
+        return;
+      }
+
+      if (route === '/close') {
+        const { key } = body;
+        if (key && contexts.has(key)) {
+          const ctx = contexts.get(key);
+          await ctx.context.close().catch(() => {});
+          contexts.delete(key);
+        }
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+
+      if (route === '/shutdown') {
+        res.end(JSON.stringify({ ok: true, message: 'Shutting down' }));
+        setTimeout(() => shutdown(), 100);
+        return;
+      }
+
+      res.statusCode = 404;
+      res.end(JSON.stringify({ error: 'Not found' }));
+    } catch (err) {
+      res.statusCode = 500;
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  });
+
+  async function shutdown() {
+    log('Shutting down daemon...');
+    for (const [, ctx] of contexts) {
+      await ctx.context.close().catch(() => {});
+    }
+    contexts.clear();
+    await browser.close().catch(() => {});
+    server.close();
+    cleanup();
+    log('Daemon stopped');
+    process.exit(0);
+  }
+
+  // Handle signals
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  // Listen on unix socket
+  server.listen(SOCKET_PATH, () => {
+    // Write PID file
+    fs.writeFileSync(PID_PATH, String(process.pid));
+    log(`Daemon started (pid: ${process.pid}, socket: ${SOCKET_PATH})`);
+    log(`Idle timeout: ${idleTimeout / 1000}s`);
+    resetIdleTimer();
+  });
+
+  server.on('error', (err) => {
+    console.error(`Daemon error: ${err.message}`);
+    cleanup();
+    process.exit(1);
+  });
+}

package/src/errors.js

@@ -0,0 +1,136 @@
+/**
+ * Standardized error types with user-friendly messages and hints
+ *
+ * Exit codes:
+ *   0  — success
+ *   1  — general error
+ *   2  — invalid arguments
+ *   3  — browser launch failed
+ *   4  — navigation failed
+ *   5  — extraction failed
+ *   6  — timeout
+ *   7  — proxy error
+ *   8  — profile/session error
+ *   130 — interrupted (SIGINT)
+ */
+
+export class StealthError extends Error {
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'StealthError';
+    this.code = opts.code || 1;
+    this.hint = opts.hint || null;
+    this.cause = opts.cause || null;
+  }
+
+  format() {
+    let msg = this.message;
+    if (this.hint) msg += `\n  Hint: ${this.hint}`;
+    return msg;
+  }
+}
+
+export class BrowserLaunchError extends StealthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 3, ...opts });
+    this.name = 'BrowserLaunchError';
+    this.hint = opts.hint || 'Try: npx camoufox-js fetch (re-download browser)';
+  }
+}
+
+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')) {
+      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';
+    }
+    super(msg, { code: 4, hint, cause });
+    this.name = 'NavigationError';
+    this.url = url;
+  }
+}
+
+export class ExtractionError extends StealthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 5, ...opts });
+    this.name = 'ExtractionError';
+    this.hint = opts.hint || 'The page structure may have changed. Try -f snapshot to inspect';
+  }
+}
+
+export class TimeoutError extends StealthError {
+  constructor(operation, timeoutMs) {
+    super(`${operation} timed out after ${timeoutMs}ms`, {
+      code: 6,
+      hint: 'Try increasing --wait or --retries',
+    });
+    this.name = 'TimeoutError';
+  }
+}
+
+export class ProxyError extends StealthError {
+  constructor(proxyUrl, cause) {
+    super(`Proxy connection failed: ${proxyUrl}`, {
+      code: 7,
+      hint: 'Check proxy URL, credentials, and connectivity. Run: stealth proxy test',
+      cause,
+    });
+    this.name = 'ProxyError';
+  }
+}
+
+export class ProfileError extends StealthError {
+  constructor(message, opts = {}) {
+    super(message, { code: 8, ...opts });
+    this.name = 'ProfileError';
+    this.hint = opts.hint || 'Run: stealth profile list';
+  }
+}
+
+export class BlockedError extends StealthError {
+  constructor(engine, url) {
+    super(`${engine} detected automation and blocked the request`, {
+      code: 4,
+      hint: 'Try: --proxy <proxy>, --warmup, --humanize, or use a different engine',
+    });
+    this.name = 'BlockedError';
+    this.url = url;
+  }
+}
+
+/**
+ * Format and print error with hint, then exit
+ */
+export function handleError(err) {
+  const { log } = loadOutput();
+
+  if (err instanceof StealthError) {
+    log.error(err.message);
+    if (err.hint) log.dim(`  Hint: ${err.hint}`);
+    process.exit(err.code);
+  }
+
+  // Unknown error
+  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?');
+  } else if (msg.includes('ENOTFOUND')) {
+    log.dim('  Hint: DNS lookup failed. Check the URL');
+  } else if (msg.includes('camoufox')) {
+    log.dim('  Hint: Try: npx camoufox-js fetch');
+  }
+
+  process.exit(1);
+}
+
+// Lazy import to avoid circular dependency
+function loadOutput() {
+  // Use dynamic require-like pattern
+  return { log: console };
+}

package/src/extractors/base.js

@@ -0,0 +1,59 @@
+/**
+ * Base extractor — generic fallback for any search page
+ */
+
+export const name = 'generic';
+
+/**
+ * Check if this extractor can handle the given URL
+ */
+export function canHandle() {
+  return true; // Fallback — always matches
+}
+
+/**
+ * Wait for search results to render
+ */
+export async function waitForResults(page) {
+  try {
+    await page.waitForSelector(
+      'h2 a[href], h3 a[href], li a[href], article a[href], .result a[href]',
+      { timeout: 5000 },
+    );
+  } catch {}
+}
+
+/**
+ * Extract search results
+ */
+export async function extractResults(page, maxResults = 10) {
+  await waitForResults(page);
+
+  return page.evaluate((max) => {
+    const results = [];
+    const candidates = document.querySelectorAll(
+      'h2 a[href], h3 a[href], li a[href], article a[href], .result a[href]',
+    );
+    const seenUrls = new Set();
+
+    for (const link of candidates) {
+      if (results.length >= max) break;
+      const href = link.href;
+      const text = link.textContent?.trim();
+
+      if (href?.startsWith('http') && text?.length > 3 && !seenUrls.has(href)) {
+        seenUrls.add(href);
+        const parent = link.closest('li, article, div, .result');
+        const snippetEl = parent?.querySelector('p, .snippet, .description, span:not(:has(a))');
+
+        results.push({
+          title: text.slice(0, 200),
+          url: href,
+          snippet: snippetEl?.textContent?.trim().slice(0, 300) || '',
+        });
+      }
+    }
+
+    return results;
+  }, maxResults);
+}

package/src/extractors/bing.js

@@ -0,0 +1,47 @@
+/**
+ * Bing Search extractor
+ */
+
+export const name = 'bing';
+
+export function canHandle(url) {
+  return /bing\.com\/search/.test(url);
+}
+
+export async function waitForResults(page) {
+  try {
+    await page.waitForSelector('#b_results .b_algo, .b_algo', { timeout: 5000 });
+  } catch {}
+}
+
+export async function extractResults(page, maxResults = 10) {
+  await waitForResults(page);
+
+  return page.evaluate((max) => {
+    const results = [];
+    const items = document.querySelectorAll('#b_results .b_algo, .b_algo');
+
+    for (const item of items) {
+      if (results.length >= max) break;
+
+      const linkEl = item.querySelector('h2 a[href]');
+      const snippetEl = item.querySelector('.b_caption p, .b_lineclamp2, .b_lineclamp3');
+      const urlEl = item.querySelector('cite, .b_attribution cite');
+
+      if (linkEl) {
+        const href = linkEl.href;
+        const title = linkEl.textContent?.trim();
+        if (href?.startsWith('http') && title) {
+          results.push({
+            title,
+            url: href,
+            snippet: snippetEl?.textContent?.trim() || '',
+            displayUrl: urlEl?.textContent?.trim() || '',
+          });
+        }
+      }
+    }
+
+    return results;
+  }, maxResults);
+}

package/src/extractors/duckduckgo.js

@@ -0,0 +1,91 @@
+/**
+ * DuckDuckGo Search extractor
+ */
+
+export const name = 'duckduckgo';
+
+export function canHandle(url) {
+  return /duckduckgo\.com/.test(url);
+}
+
+export async function waitForResults(page) {
+  const selectors = [
+    '[data-result="web"]',
+    'article[data-testid="result"]',
+    '.result--web',
+    'ol.react-results--main li',
+  ];
+
+  for (const sel of selectors) {
+    try {
+      await page.waitForSelector(sel, { timeout: 4000 });
+      return;
+    } catch {}
+  }
+}
+
+export async function extractResults(page, maxResults = 10) {
+  await waitForResults(page);
+
+  return page.evaluate((max) => {
+    const results = [];
+
+    // Modern DuckDuckGo layout (React-based)
+    const items = document.querySelectorAll(
+      'article[data-testid="result"], [data-result="web"], .result--web, ol.react-results--main > li',
+    );
+
+    for (const item of items) {
+      if (results.length >= max) break;
+
+      // Multiple title selectors for different DDG versions
+      const linkEl = item.querySelector(
+        'a[data-testid="result-title-a"], h2 a[href], a.result__a, a[href]:has(h2)',
+      );
+      const snippetEl = item.querySelector(
+        '[data-testid="result-snippet"], .result__snippet, .E2eLOJr8HctVnDOTM8fs, span.kY2IgmnCmOGjharHErah',
+      );
+      const urlEl = item.querySelector(
+        '[data-testid="result-extras-url-link"], .result__url, a.result__check',
+      );
+
+      if (linkEl) {
+        const href = linkEl.href;
+        const title = linkEl.textContent?.trim();
+        if (href?.startsWith('http') && !href.includes('duckduckgo.com') && title) {
+          results.push({
+            title,
+            url: href,
+            snippet: snippetEl?.textContent?.trim() || '',
+            displayUrl: urlEl?.textContent?.trim() || '',
+          });
+        }
+      }
+    }
+
+    // Fallback: extract from any visible links in the results area
+    if (results.length === 0) {
+      const seenUrls = new Set();
+      const links = document.querySelectorAll(
+        '#links a[href], .results a[href], [data-testid="mainline"] a[href]',
+      );
+
+      for (const link of links) {
+        if (results.length >= max) break;
+        const href = link.href;
+        const text = link.textContent?.trim();
+        if (
+          href?.startsWith('http') &&
+          !href.includes('duckduckgo.com') &&
+          text?.length > 5 &&
+          !seenUrls.has(href)
+        ) {
+          seenUrls.add(href);
+          results.push({ title: text.slice(0, 200), url: href, snippet: '' });
+        }
+      }
+    }
+
+    return results;
+  }, maxResults);
+}