veil-browser 0.3.0 → 0.4.1

package/README.md

@@ -1,143 +1,265 @@
-# 🕶️ 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
+---
+
+## Browser Selection
+
+veil can use Playwright's bundled Chromium, an installed Chrome-compatible browser, or an already-running browser exposed over CDP.
 
 ```bash
-veil extract "tweets" --url https://x.com/home --platform twitter --json
+# Installed Google Chrome
+veil login reddit --browser chrome
+
+# Installed Dia
+veil login reddit --browser dia
+
+# Attach to a manually started browser over CDP
+veil login reddit --cdp-url http://127.0.0.1:9222
+
+# Launch a dedicated persistent automation profile
+veil login reddit --browser chrome --user-data-dir "$HOME/.veil/chrome-profile"
 ```
 
-### Take a screenshot
+Supported shared browser flags:
+
+- `--browser playwright|chrome|dia`
+- `--browser-path /absolute/path/to/browser`
+- `--cdp-url http://127.0.0.1:9222`
+- `--user-data-dir /path/to/profile`
+- `--timeout-ms 45000`
+
+Use a dedicated automation profile for `--user-data-dir`. Do not point veil at your live default Chrome profile while that browser is open.
+
+---
+
+## All Commands
+
+### 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 |
+| `veil serve` | Start the Streamable HTTP MCP server |
+
+**Supported platforms:** `x`, `linkedin`, `reddit`, `bluesky` (or any URL)
+
+### 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 |
+
+### Navigation
+| Command | Description |
+|---------|-------------|
+| `veil go <url>` | Navigate to URL |
+| `veil url` | Get current URL and title |
+| `veil back` | Go back |
+
+### 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 |
+
+---
+
+## Remote MCP Server for Claude
+
+veil now includes a real Streamable HTTP MCP server built on the official MCP SDK.
+
+Local HTTP example:
 
 ```bash
-veil screenshot --url https://x.com --platform twitter --output ./x-home.png
+veil serve --host 127.0.0.1 --port 3456
 ```
 
-### List saved sessions
+Direct HTTPS example:
 
 ```bash
-veil session list
+veil serve \
+  --host 0.0.0.0 \
+  --port 3443 \
+  --allowed-hosts your-domain.example \
+  --https-cert /etc/ssl/your-domain/fullchain.pem \
+  --https-key /etc/ssl/your-domain/privkey.pem
 ```
 
-### Remove a session
+Important deployment notes:
+
+- Claude needs a reachable `https://` endpoint with a valid certificate. A localhost server or self-signed certificate is useful for testing, but not for production Claude integrations.
+- The MCP endpoint is `POST /mcp`.
+- Health checks are available at `GET /healthz`.
+- When binding to `0.0.0.0` or another non-localhost interface, set `--allowed-hosts` to the real public hostname to keep host-header validation in place.
+- You can also terminate TLS in a reverse proxy or tunnel and forward plain HTTP to `veil serve`.
+- Sessions are still created separately with `veil login <platform>`. The MCP server reuses those saved sessions when tools specify a `platform`.
+
+Smoke-test the built server locally:
 
 ```bash
-veil logout twitter
+npm run build
+npm run test:mcp
 ```
 
-### Status
+---
 
-```bash
-veil status
+## For AI Agents (OpenClaw / MCP)
+
+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
+## Built by CUTTLELAB
 
-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
-```
+veil is part of the tooling stack we're building for AI agents at [CUTTLELAB](https://cuttle.io).
 
 ---
 

package/dist/browser.d.ts

@@ -1,12 +1,30 @@
 import { Browser, BrowserContext, Page } from 'playwright';
-export declare function ensureBrowser(opts?: {
+export interface BrowserLaunchOptions {
     headed?: boolean;
     platform?: string;
-}): Promise<{
+    browser?: string;
+    browserPath?: string;
+    cdpUrl?: string;
+    userDataDir?: string;
+    timeoutMs?: number | string;
+}
+/**
+ * Ensure a browser session is available, creating or attaching as needed.
+ */
+export declare function ensureBrowser(opts?: BrowserLaunchOptions): Promise<{
     browser: Browser;
     context: BrowserContext;
     page: Page;
 }>;
+/**
+ * Return the current live page if the browser is still open.
+ */
 export declare function getPage(): Promise<Page | null>;
-export declare function closeBrowser(_platform?: string): Promise<void>;
+/**
+ * Persist the current storage state when requested and close veil-owned resources.
+ */
+export declare function closeBrowser(platform?: string): Promise<void>;
+/**
+ * Sleep for a short human-like randomized delay.
+ */
 export declare function humanDelay(min?: number, max?: number): Promise<void>;