veil-browser 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# 🕶️ veil
+
+> Stealth browser CLI for AI agents — bypass bot detection, persist sessions, full web control.
+
+Built for [OpenClaw](https://openclaw.ai) agents but works standalone. Playwright under the hood with stealth anti-detection baked in from day one.
+
+---
+
+## Features
+
+- 🥷 **Stealth by default** — powered by `playwright-extra` + `puppeteer-extra-plugin-stealth`
+- 🔐 **Persistent sessions** — log in once, use forever (saved to `~/.veil/sessions/`)
+- 👁️ **Interactive login mode** — opens a real visible browser for you to authenticate manually
+- 🤖 **Agent-friendly commands** — natural language actions, JSON output
+- 🌐 **Works everywhere** — X/Twitter, Reddit, LinkedIn, GitHub, Instagram, any site
+
+---
+
+## Install
+
+```bash
+cd veil
+npm install
+npm run build
+npm link   # makes 'veil' available globally
+```
+
+Or install Playwright browsers:
+```bash
+npx playwright install chromium
+```
+
+---
+
+## Usage
+
+### Login to a platform
+
+```bash
+veil login twitter
+```
+
+Opens a visible Chromium browser. Log in normally (username, password, 2FA). Veil detects when you're on the home page and saves the session automatically.
+
+### Post a tweet
+
+```bash
+veil act "post tweet: Hello from veil 🕶️" --platform twitter
+```
+
+### Navigate headlessly
+
+```bash
+veil navigate https://x.com --platform twitter
+```
+
+### Extract data
+
+```bash
+veil extract "tweets" --url https://x.com/home --platform twitter --json
+```
+
+### Take a screenshot
+
+```bash
+veil screenshot --url https://x.com --platform twitter --output ./x-home.png
+```
+
+### List saved sessions
+
+```bash
+veil session list
+```
+
+### Remove a session
+
+```bash
+veil logout twitter
+```
+
+### Status
+
+```bash
+veil status
+```
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `veil login <platform>` | Open visible browser for manual login, save session |
+| `veil logout <platform>` | Remove saved session |
+| `veil navigate <url>` | Navigate to URL (headless stealth) |
+| `veil act "<instruction>"` | Perform natural language action |
+| `veil extract "<query>"` | Extract data as JSON |
+| `veil screenshot` | Take screenshot |
+| `veil session list` | List all saved sessions |
+| `veil status` | Show veil status |
+
+### Common flags
+
+| Flag | Description |
+|------|-------------|
+| `-p, --platform <name>` | Use saved session for this platform |
+| `-u, --url <url>` | Navigate to URL before action |
+| `-H, --headed` | Run in visible browser mode |
+| `-o, --output <path>` | Output file path (screenshot) |
+| `--json` | Output machine-readable JSON |
+
+---
+
+## Supported `act` instructions
+
+```bash
+veil act "click Login"
+veil act "type 'hello world' into search"
+veil act "post tweet: your content here"
+veil act "like tweet"
+veil act "scroll down"
+veil act "press enter"
+veil act "go to https://example.com"
+```
+
+---
+
+## Session storage
+
+Sessions are saved to `~/.veil/sessions/<platform>.json` as Playwright storage state (cookies + localStorage). No encryption currently — keep your machine secure.
+
+---
+
+## OpenClaw integration
+
+Use `veil` as a drop-in for the OpenClaw Browser Relay. Add it as a skill and call it from any agent:
+
+```bash
+veil act "post tweet: launched something today" --platform twitter --json
+```
+
+---
+
+## License
+
+MIT

package/dist/ai.d.ts

@@ -0,0 +1,19 @@
+import type { Page } from 'playwright';
+interface ActionStep {
+    action: 'click' | 'type' | 'press' | 'navigate' | 'wait' | 'scroll' | 'select';
+    selector?: string;
+    text?: string;
+    key?: string;
+    url?: string;
+    direction?: 'up' | 'down';
+    ms?: number;
+    description?: string;
+}
+export declare function aiAct(page: Page, instruction: string, opts?: {
+    verbose?: boolean;
+}): Promise<{
+    success: boolean;
+    steps: ActionStep[];
+    error?: string;
+}>;
+export {};

package/dist/ai.js

@@ -0,0 +1,253 @@
+import { humanDelay } from './browser.js';
+import chalk from 'chalk';
+import ora from 'ora';
+import { promises as fs } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+async function loadConfig() {
+    const configFile = join(homedir(), '.veil', 'config.json');
+    try {
+        const raw = await fs.readFile(configFile, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function getLLMConfig(config) {
+    // Priority: config file > env vars
+    if (config.llm?.apiKey)
+        return config.llm;
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (openaiKey)
+        return { provider: 'openai', apiKey: openaiKey, model: 'gpt-4o-mini' };
+    const anthropicKey = process.env.ANTHROPIC_API_KEY;
+    if (anthropicKey)
+        return { provider: 'anthropic', apiKey: anthropicKey, model: 'claude-haiku-4-5' };
+    const openrouterKey = process.env.OPENROUTER_API_KEY;
+    if (openrouterKey)
+        return { provider: 'openrouter', apiKey: openrouterKey, model: 'openai/gpt-4o-mini' };
+    return null;
+}
+// Get a compact accessibility snapshot of the page for LLM consumption
+async function getPageSnapshot(page) {
+    const snapshot = await page.evaluate(() => {
+        const elements = [];
+        function processNode(el, depth = 0) {
+            if (depth > 6)
+                return;
+            const tag = el.tagName.toLowerCase();
+            const role = el.getAttribute('role');
+            const ariaLabel = el.getAttribute('aria-label');
+            const testId = el.getAttribute('data-testid');
+            const type = el.getAttribute('type');
+            const placeholder = el.getAttribute('placeholder');
+            const text = el.innerText?.slice(0, 80).trim().replace(/\n/g, ' ');
+            const href = el.getAttribute('href');
+            const disabled = el.getAttribute('disabled') !== null || el.getAttribute('aria-disabled') === 'true';
+            const isInteractive = ['a', 'button', 'input', 'textarea', 'select'].includes(tag) || role;
+            if (!isInteractive && !text)
+                return;
+            const attrs = [];
+            if (testId)
+                attrs.push(`data-testid="${testId}"`);
+            if (role)
+                attrs.push(`role="${role}"`);
+            if (ariaLabel)
+                attrs.push(`aria-label="${ariaLabel}"`);
+            if (type)
+                attrs.push(`type="${type}"`);
+            if (placeholder)
+                attrs.push(`placeholder="${placeholder}"`);
+            if (href)
+                attrs.push(`href="${href.slice(0, 60)}"`);
+            if (disabled)
+                attrs.push('disabled');
+            const indent = '  '.repeat(depth);
+            const attrStr = attrs.length ? ` [${attrs.join(', ')}]` : '';
+            const textStr = text ? ` "${text.slice(0, 60)}"` : '';
+            elements.push(`${indent}<${tag}${attrStr}${textStr}>`);
+            for (const child of el.children) {
+                processNode(child, depth + 1);
+            }
+        }
+        processNode(document.body);
+        return elements.slice(0, 200).join('\n');
+    });
+    return snapshot;
+}
+// Call LLM to get action steps
+async function getActionsFromLLM(instruction, snapshot, pageUrl, llm) {
+    const systemPrompt = `You are a browser automation assistant. Given a page snapshot (ARIA/DOM tree) and a user instruction, return a JSON array of action steps to complete the task.
+
+Available actions:
+- click: { action: "click", selector: "CSS or data-testid selector", description: "..." }
+- type: { action: "type", selector: "...", text: "the text to type", description: "..." }
+- press: { action: "press", key: "Enter|Tab|Escape|...", description: "..." }
+- navigate: { action: "navigate", url: "https://...", description: "..." }
+- wait: { action: "wait", ms: 1000, description: "..." }
+- scroll: { action: "scroll", direction: "down", description: "..." }
+
+Rules:
+- Prefer data-testid selectors when available (most stable)
+- For Twitter/X: use [data-testid="tweetTextarea_0"] for tweet box, [data-testid="tweetButtonInline"] for post button
+- Return ONLY valid JSON array, no explanation
+- Add a wait step after clicks on buttons that trigger UI changes
+- For typing in contenteditable areas, click first then type`;
+    const userPrompt = `Current URL: ${pageUrl}
+
+Page snapshot:
+${snapshot.slice(0, 4000)}
+
+Instruction: ${instruction}
+
+Return JSON array of action steps:`;
+    let response;
+    if (llm.provider === 'openai' || llm.provider === 'openrouter') {
+        const baseUrl = llm.provider === 'openrouter'
+            ? 'https://openrouter.ai/api/v1'
+            : 'https://api.openai.com/v1';
+        response = await fetch(`${baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${llm.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: llm.model,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: userPrompt },
+                ],
+                temperature: 0,
+                max_tokens: 1000,
+            }),
+        });
+    }
+    else {
+        // Anthropic
+        response = await fetch('https://api.anthropic.com/v1/messages', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': llm.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify({
+                model: llm.model,
+                max_tokens: 1000,
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userPrompt }],
+            }),
+        });
+    }
+    if (!response.ok) {
+        throw new Error(`LLM API error: ${response.status} ${await response.text()}`);
+    }
+    const data = await response.json();
+    const content = llm.provider === 'anthropic'
+        ? data.content[0].text
+        : data.choices[0].message.content;
+    // Extract JSON from response
+    const jsonMatch = content.match(/\[[\s\S]*\]/);
+    if (!jsonMatch)
+        throw new Error('LLM returned no valid JSON array');
+    return JSON.parse(jsonMatch[0]);
+}
+// Execute a single action step
+async function executeStep(page, step) {
+    switch (step.action) {
+        case 'click': {
+            if (!step.selector)
+                throw new Error('click requires selector');
+            // Try multiple selector strategies
+            const el = page.locator(step.selector).first();
+            await el.waitFor({ timeout: 5000 }).catch(() => { });
+            await el.click({ timeout: 5000 });
+            await humanDelay(300, 700);
+            break;
+        }
+        case 'type': {
+            if (!step.selector || !step.text)
+                throw new Error('type requires selector and text');
+            const el = page.locator(step.selector).first();
+            await el.waitFor({ timeout: 5000 }).catch(() => { });
+            await el.click();
+            await humanDelay(200, 400);
+            // Type with human-like delays
+            for (const char of step.text) {
+                await page.keyboard.type(char, { delay: Math.random() * 60 + 30 });
+            }
+            await humanDelay(300, 600);
+            break;
+        }
+        case 'press': {
+            if (!step.key)
+                throw new Error('press requires key');
+            await page.keyboard.press(step.key);
+            await humanDelay(200, 400);
+            break;
+        }
+        case 'navigate': {
+            if (!step.url)
+                throw new Error('navigate requires url');
+            await page.goto(step.url, { waitUntil: 'domcontentloaded', timeout: 30000 });
+            await humanDelay(800, 1500);
+            break;
+        }
+        case 'wait': {
+            await new Promise((r) => setTimeout(r, step.ms ?? 1000));
+            break;
+        }
+        case 'scroll': {
+            const amount = step.direction === 'up' ? -600 : 600;
+            await page.evaluate((y) => window.scrollBy(0, y), amount);
+            await humanDelay(300, 500);
+            break;
+        }
+    }
+}
+// Main AI-powered act function
+export async function aiAct(page, instruction, opts = {}) {
+    const config = await loadConfig();
+    const llm = getLLMConfig(config);
+    if (!llm) {
+        throw new Error('No LLM configured. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY env var, ' +
+            'or run: veil config llm.provider openai && veil config llm.apiKey YOUR_KEY');
+    }
+    const spinner = ora({ text: '🧠 Analyzing page...', color: 'cyan' }).start();
+    try {
+        // 1. Get page snapshot
+        const snapshot = await getPageSnapshot(page);
+        const pageUrl = page.url();
+        spinner.text = '🧠 Asking AI what to do...';
+        // 2. Get action steps from LLM
+        const steps = await getActionsFromLLM(instruction, snapshot, pageUrl, llm);
+        if (opts.verbose) {
+            spinner.stop();
+            console.log(chalk.cyan('\n📋 AI action plan:'));
+            steps.forEach((s, i) => {
+                console.log(chalk.gray(`  ${i + 1}. ${s.action}${s.description ? ': ' + s.description : ''}`));
+            });
+            console.log('');
+            spinner.start('Executing...');
+        }
+        else {
+            spinner.text = `Executing ${steps.length} steps...`;
+        }
+        // 3. Execute each step
+        for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            if (opts.verbose) {
+                spinner.text = `Step ${i + 1}/${steps.length}: ${step.action} ${step.description ?? ''}`;
+            }
+            await executeStep(page, step);
+        }
+        spinner.succeed(chalk.green(`✅ Done: ${instruction}`));
+        return { success: true, steps };
+    }
+    catch (err) {
+        spinner.fail(chalk.red(`❌ AI act failed: ${err.message}`));
+        return { success: false, steps: [], error: err.message };
+    }
+}

package/dist/browser.d.ts

@@ -0,0 +1,12 @@
+import type { Browser, BrowserContext, Page } from 'playwright';
+export interface LaunchOptions {
+    headed?: boolean;
+    platform?: string;
+}
+export declare function getBrowser(opts?: LaunchOptions): Promise<{
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+}>;
+export declare function closeBrowser(platform?: string): Promise<void>;
+export declare function humanDelay(min?: number, max?: number): Promise<void>;

package/dist/browser.js

@@ -0,0 +1,46 @@
+import { chromium } from 'playwright-extra';
+import StealthPlugin from 'puppeteer-extra-plugin-stealth';
+import { loadSession, saveSession } from './session.js';
+// @ts-ignore
+chromium.use(StealthPlugin());
+let _browser = null;
+let _context = null;
+let _page = null;
+export async function getBrowser(opts = {}) {
+    const headless = !opts.headed;
+    _browser = await chromium.launch({
+        headless,
+        args: [
+            '--no-sandbox',
+            '--disable-blink-features=AutomationControlled',
+            '--disable-infobars',
+            '--window-size=1280,800',
+        ],
+    });
+    const storageState = opts.platform ? await loadSession(opts.platform) : undefined;
+    _context = await _browser.newContext({
+        storageState: storageState ?? undefined,
+        viewport: { width: 1280, height: 800 },
+        userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
+        locale: 'en-US',
+        timezoneId: 'Europe/Bratislava',
+    });
+    _page = await _context.newPage();
+    return { browser: _browser, context: _context, page: _page };
+}
+export async function closeBrowser(platform) {
+    if (_context && platform) {
+        const state = await _context.storageState();
+        await saveSession(platform, state);
+    }
+    if (_browser) {
+        await _browser.close();
+        _browser = null;
+        _context = null;
+        _page = null;
+    }
+}
+export function humanDelay(min = 300, max = 900) {
+    const ms = Math.floor(Math.random() * (max - min) + min);
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/captcha.d.ts

@@ -0,0 +1,27 @@
+import type { Page } from 'playwright';
+export interface VeilConfig {
+    captcha?: {
+        provider?: '2captcha' | 'capmonster' | 'anticaptcha';
+        apiKey?: string;
+    };
+    proxy?: {
+        server?: string;
+        username?: string;
+        password?: string;
+    };
+}
+export type VeilErrorCode = 'SELECTOR_NOT_FOUND' | 'NAVIGATION_TIMEOUT' | 'SESSION_EXPIRED' | 'CAPTCHA_DETECTED' | 'RATE_LIMITED' | 'UNKNOWN';
+export declare class VeilError extends Error {
+    code: VeilErrorCode;
+    screenshotPath?: string;
+    suggestion?: string;
+    constructor(code: VeilErrorCode, message: string, suggestion?: string);
+}
+export declare function detectCaptcha(page: Page): Promise<'turnstile' | 'recaptcha' | 'hcaptcha' | 'image' | null>;
+export declare function handleCaptcha(page: Page, screenshotDir?: string): Promise<boolean>;
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: {
+    attempts?: number;
+    delay?: number;
+    label?: string;
+}): Promise<T>;
+export declare function screenshotOnError(page: Page, label: string): Promise<string | null>;