veil-browser 0.2.1 → 0.4.0

package/README.md

@@ -1,143 +1,195 @@
-# 🕶️ veil
+<div align="center">
 
-> Stealth browser CLI for AI agents — bypass bot detection, persist sessions, full web control.
+<img src="https://raw.githubusercontent.com/cuttlelab/veil/main/docs/logo.png" alt="veil" width="80" />
 
-Built for [OpenClaw](https://openclaw.ai) agents but works standalone. Playwright under the hood with stealth anti-detection baked in from day one.
+# veil
 
----
+**Stealth browser remote for AI agents.**
 
-## Features
+[![npm](https://img.shields.io/npm/v/veil-browser?color=000&style=flat-square)](https://www.npmjs.com/package/veil-browser)
+[![license](https://img.shields.io/badge/license-MIT-000?style=flat-square)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D18-000?style=flat-square)](https://nodejs.org)
 
-- 🥷 **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
+</div>
 
 ---
 
-## Install
+veil is a **headless browser CLI** built for AI agents. It runs a real, stealth Chromium browser and exposes every interaction as a simple command that returns clean JSON.
 
-```bash
-cd veil
-npm install
-npm run build
-npm link   # makes 'veil' available globally
-```
+You (or your agent) are the brain. veil is the hands.
 
-Or install Playwright browsers:
 ```bash
+npm install -g veil-browser
 npx playwright install chromium
+veil login x          # save your session once
+veil post "Hello, world from an AI agent."
 ```
 
 ---
 
-## Usage
+## Why veil
 
-### Login to a platform
+Most browser automation tools are built for developers writing scripts. veil is built for **AI agents making decisions in real-time** — where every step is a tool call, every result is parseable JSON, and the agent decides what to do next.
 
-```bash
-veil login twitter
-```
+- **No LLM inside** — veil is pure remote control. Your agent is the intelligence.
+- **Stealth by default** — hides automation signals, realistic user agent, human-like delays
+- **Persistent sessions** — log in once, reuse forever via saved cookies
+- **Every output is JSON** — `{ ok: true, ... }` or `{ ok: false, error: "..." }`
 
-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
+## Installation
 
 ```bash
-veil act "post tweet: Hello from veil 🕶️" --platform twitter
+npm install -g veil-browser
+npx playwright install chromium
 ```
 
-### Navigate headlessly
+---
+
+## Quick Start
 
 ```bash
-veil navigate https://x.com --platform twitter
+# Log in once (opens visible browser)
+veil login x
+
+# Post a tweet
+veil post "Building something new."
+
+# Like, reply, repost, quote
+veil like --nth 0
+veil reply "Great point." --nth 0
+veil repost --nth 1
+veil quote "Worth reading." --nth 2
+
+# Navigate and read any page
+veil go https://example.com
+veil snapshot          # DOM tree → understand the page
+veil read "h1"         # Extract specific elements
+veil find "Sign in"    # Check if text exists
+
+# Click, type, interact
+veil click "[data-testid='button']"
+veil type "input[name='q']" "search query"
+veil press Enter
+veil scroll down
+
+# Screenshot
+veil shot page.png
 ```
 
-### Extract data
+---
 
-```bash
-veil extract "tweets" --url https://x.com/home --platform twitter --json
-```
+## All Commands
 
-### Take a screenshot
+### Session
+| Command | Description |
+|---------|-------------|
+| `veil login <platform>` | Open visible browser → log in → save session |
+| `veil open <platform>` | Restore session and navigate to platform home |
+| `veil sessions` | List saved sessions |
+| `veil close` | Close browser |
 
-```bash
-veil screenshot --url https://x.com --platform twitter --output ./x-home.png
-```
+**Supported platforms:** `x`, `linkedin`, `reddit`, `bluesky` (or any URL)
 
-### List saved sessions
+### X / Social
+| Command | Description |
+|---------|-------------|
+| `veil post "text"` | Post a tweet |
+| `veil like --nth 0` | Like Nth post in feed |
+| `veil reply "text" --nth 0` | Reply to Nth post |
+| `veil repost --nth 0` | Repost Nth post |
+| `veil quote "text" --nth 0` | Quote Nth post with comment |
 
-```bash
-veil session list
-```
+### Navigation
+| Command | Description |
+|---------|-------------|
+| `veil go <url>` | Navigate to URL |
+| `veil url` | Get current URL and title |
+| `veil back` | Go back |
 
-### Remove a session
+### Reading
+| Command | Description |
+|---------|-------------|
+| `veil snapshot` | Full DOM tree (best for understanding page structure) |
+| `veil read [selector]` | Page text or element text |
+| `veil read <sel> --all` | All matches as array |
+| `veil read <sel> --attr href` | Read attribute value |
+| `veil find "text"` | Check if text exists on page |
+| `veil exists <selector>` | Check if selector exists |
+
+### Interaction
+| Command | Description |
+|---------|-------------|
+| `veil click <selector>` | Click element |
+| `veil click <sel> --force` | Force click (bypass overlays) |
+| `veil click <sel> --nth 2` | Click Nth match |
+| `veil type <selector> "text"` | Type into element |
+| `veil type <sel> "text" --clear` | Clear first, then type |
+| `veil press <key>` | Press key (Enter, Tab, Escape…) |
+| `veil scroll down\|up\|top\|bottom` | Scroll page |
+| `veil wait <ms>` | Wait N milliseconds |
+| `veil wait-for <selector>` | Wait until element appears |
+| `veil eval "script"` | Run JavaScript, returns result |
+
+### Screenshot
+| Command | Description |
+|---------|-------------|
+| `veil shot [file.png]` | Screenshot (full page with `--full`) |
+| `veil shot file.png --selector <sel>` | Screenshot specific element |
 
-```bash
-veil logout twitter
-```
+---
 
-### Status
+## For AI Agents (OpenClaw / MCP)
 
-```bash
-veil status
+veil ships with a `SKILL.md` that teaches OpenClaw exactly how to use it — all commands, all platform selectors, and complete task sequences.
+
+The agent pattern:
+```
+1. veil open x           → restore session
+2. veil snapshot         → understand current page
+3. veil click / type     → act
+4. veil wait 800         → let UI settle
+5. veil find / read      → verify
 ```
 
+Every command is deterministic. Every output is parseable. The agent decides the logic.
+
 ---
 
-## Command Reference
+## Platform Support
 
-| 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 |
+| Platform | Login | Post | Like | Reply | Repost | Quote |
+|----------|-------|------|------|-------|--------|-------|
+| X (Twitter) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| LinkedIn | ✅ | ✅ | ✅ | ✅ | — | — |
+| Reddit | ✅ | — | ✅ | ✅ | — | — |
+| Any website | — | — | ✅ via selectors | — | — | — |
 
 ---
 
-## Supported `act` instructions
+## Configuration
+
+Config stored at `~/.veil/config.json`. Sessions at `~/.veil/sessions/<platform>.json`.
 
 ```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"
+veil status    # show current config and saved sessions
 ```
 
 ---
 
-## Session storage
+## How It Works
 
-Sessions are saved to `~/.veil/sessions/<platform>.json` as Playwright storage state (cookies + localStorage). No encryption currently — keep your machine secure.
+1. **Stealth Chromium** — launches with flags that hide automation signals
+2. **Session cookies** — saved after manual login, restored on every run
+3. **Human timing** — random delays between actions (400–1200ms)
+4. **Clean JSON output** — every command returns `{ ok, ... }` for easy parsing
 
 ---
 
-## OpenClaw integration
-
-Use `veil` as a drop-in for the OpenClaw Browser Relay. Add it as a skill and call it from any agent:
+## Built by CUTTLELAB
 
-```bash
-veil act "post tweet: launched something today" --platform twitter --json
-```
+veil is part of the tooling stack we're building for AI agents at [CUTTLELAB](https://cuttle.io).
 
 ---
 

package/dist/browser.d.ts

@@ -1,10 +1,4 @@
 import { Browser, BrowserContext, Page } from 'playwright';
-export interface BrowserState {
-    platform: string;
-    pid: number;
-    wsEndpoint: string;
-    timestamp: number;
-}
 export declare function ensureBrowser(opts?: {
     headed?: boolean;
     platform?: string;

package/dist/browser.js

@@ -2,87 +2,99 @@ import { chromium } from 'playwright';
 import { promises as fs } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { execSync } from 'child_process';
 import { loadSession } from './session.js';
 const VEIL_DIR = join(homedir(), '.veil');
-const STATE_FILE = join(VEIL_DIR, 'browser-state.json');
-// In-process singletons
+const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36';
+// Detect system Chrome installation
+function findSystemChrome() {
+    const paths = [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/usr/bin/google-chrome',
+        '/usr/bin/chromium',
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    ];
+    for (const path of paths) {
+        try {
+            execSync(`test -x "${path}"`, { stdio: 'ignore' });
+            return path;
+        }
+        catch { }
+    }
+    return null;
+}
 let _browser = null;
 let _context = null;
 let _page = null;
-const STEALTH_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36';
 export async function ensureBrowser(opts = {}) {
-    const platform = opts.platform ?? 'default';
-    // Return existing if healthy
     if (_browser?.isConnected() && _page && !_page.isClosed()) {
         return { browser: _browser, context: _context, page: _page };
     }
-    // Fresh browser launch
+    const executablePath = findSystemChrome();
     const browser = await chromium.launch({
         headless: !opts.headed,
+        executablePath: executablePath || undefined, // Use system Chrome if found, else fallback
         args: [
             '--disable-blink-features=AutomationControlled',
             '--no-sandbox',
             '--disable-setuid-sandbox',
-            '--disable-infobars',
+            '--window-size=1280,800',
             '--disable-dev-shm-usage',
-            '--disable-accelerated-2d-canvas',
+            '--disable-gpu',
             '--no-first-run',
-            '--window-size=1280,800',
+            '--no-default-browser-check',
+            '--disable-default-apps',
+            '--disable-extensions',
         ],
     });
     const context = await browser.newContext({
         viewport: { width: 1280, height: 800 },
-        userAgent: STEALTH_UA,
+        userAgent: UA,
         locale: 'en-US',
         timezoneId: 'America/New_York',
-        permissions: ['notifications'],
         extraHTTPHeaders: { 'Accept-Language': 'en-US,en;q=0.9' },
+        ignoreHTTPSErrors: true,
     });
-    // Stealth: hide automation signals
     await context.addInitScript(() => {
+        // Spoof all automation detection vectors
         Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+        Object.defineProperty(navigator, 'chromeapp', { get: () => undefined });
         window.chrome = { runtime: {} };
         Object.defineProperty(navigator, 'plugins', { get: () => [1, 2, 3, 4, 5] });
         Object.defineProperty(navigator, 'languages', { get: () => ['en-US', 'en'] });
+        // Spoof permissions
+        window.navigator.permissions = {
+            query: () => Promise.resolve({ state: Notification.permission })
+        };
+        // Override toString on navigator to hide automation
+        const originalToString = Function.prototype.toString;
+        Function.prototype.toString = function () {
+            if (this === window.navigator.permissions.query) {
+                return 'function query() { [native code] }';
+            }
+            return originalToString.call(this);
+        };
     });
-    // Restore saved session cookies
-    const session = await loadSession(platform).catch(() => null);
-    if (session?.cookies?.length) {
+    const session = await loadSession(opts.platform ?? 'default').catch(() => null);
+    if (session?.cookies?.length)
         await context.addCookies(session.cookies).catch(() => { });
-    }
     const page = await context.newPage();
     _browser = browser;
     _context = context;
     _page = page;
-    // Persist state for reconnection
     await fs.mkdir(VEIL_DIR, { recursive: true });
-    await fs.writeFile(STATE_FILE, JSON.stringify({
-        platform,
-        pid: process.pid,
-        wsEndpoint: '',
-        timestamp: Date.now(),
-    }), 'utf-8').catch(() => { });
-    // Cleanup state on exit
-    const cleanup = () => {
-        fs.rm(STATE_FILE).catch(() => { });
-        _browser?.close().catch(() => { });
-    };
-    process.once('exit', cleanup);
-    process.once('SIGINT', () => { cleanup(); process.exit(0); });
-    process.once('SIGTERM', () => { cleanup(); process.exit(0); });
+    process.once('exit', () => { browser.close().catch(() => { }); });
     return { browser, context, page };
 }
 export async function getPage() {
-    if (_page && !_page.isClosed())
-        return _page;
-    return null;
+    return (_page && !_page.isClosed()) ? _page : null;
 }
 export async function closeBrowser(_platform) {
     await _browser?.close().catch(() => { });
     _browser = null;
     _context = null;
     _page = null;
-    await fs.rm(STATE_FILE).catch(() => { });
 }
 export function humanDelay(min = 400, max = 900) {
     return new Promise(r => setTimeout(r, Math.floor(Math.random() * (max - min) + min)));