@ulpi/browse 0.7.5 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulpi/browse",
-  "version": "0.7.5",
+  "version": "1.0.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/ulpi-io/browse"
@@ -8,20 +8,20 @@
   "dependencies": {
     "@lightpanda/browser": "^1.2.0",
     "@ulpi/browse": "^0.3.0",
+    "better-sqlite3": "^11.0.0",
     "diff": "^7.0.0",
     "playwright": "^1.58.2",
     "playwright-core": "^1.58.2"
   },
   "bin": {
-    "browse": "bin/browse.ts"
+    "browse": "dist/browse.mjs"
   },
   "description": "Fast headless browser CLI — persistent Chromium daemon via Playwright.",
   "engines": {
-    "bun": ">=1.0.0"
+    "node": ">=18.0.0"
   },
   "files": [
-    "bin/",
-    "src/",
+    "dist/",
     "skill/",
     "LICENSE",
     "README.md",
@@ -41,19 +41,23 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build --compile --external electron --external chromium-bidi src/cli.ts --outfile dist/browse && rm -f .*.bun-build",
+    "build": "esbuild src/cli.ts --bundle --format=esm --platform=node --target=node18 --outfile=dist/browse.mjs --external:playwright --external:playwright-core --external:better-sqlite3 --external:electron --external:chromium-bidi --banner:js='#!/usr/bin/env node'",
     "build:all": "bash scripts/build-all.sh",
-    "dev": "bun run src/cli.ts",
-    "server": "bun run src/server.ts",
-    "test": "bun test",
-    "start": "bun run src/server.ts",
-    "postinstall": "bunx playwright install chromium",
-    "benchmark": "bun run benchmark.ts"
+    "dev": "tsx src/cli.ts",
+    "server": "tsx src/server.ts",
+    "test": "vitest run",
+    "start": "tsx src/server.ts",
+    "postinstall": "npx playwright install chromium",
+    "benchmark": "tsx benchmark.ts"
   },
   "type": "module",
   "devDependencies": {
+    "@types/better-sqlite3": "^7.0.0",
     "@types/node": "^25.5.0",
-    "typescript": "^5.9.3"
+    "esbuild": "^0.25.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
   },
   "optionalDependencies": {
     "rebrowser-playwright": "^1.52.0"

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browse
-version: 2.5.1
+version: 2.8.0
 description: |
   Fast web browsing for AI coding agents via persistent headless Chromium daemon. Navigate to any URL,
   read page content, click elements, fill forms, run JavaScript, take screenshots,
@@ -31,8 +31,7 @@ fi
 
 If `NEEDS_INSTALL`:
 1. Tell the user: "browse needs a one-time install via npm. OK to proceed?"
-2. If they approve: `bun install -g @ulpi/browse`
-3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
+2. If they approve: `npm install -g @ulpi/browse`
 
 ### Permissions check
 
@@ -75,13 +74,21 @@ If the file is missing or does not contain browse permission rules in `permissio
 "Bash(browse frame:*)",
 "Bash(browse sessions:*)", "Bash(browse session-close:*)",
 "Bash(browse state:*)", "Bash(browse auth:*)", "Bash(browse har:*)", "Bash(browse video:*)",
+"Bash(browse record:*)",
 "Bash(browse route:*)", "Bash(browse offline:*)",
 "Bash(browse status:*)", "Bash(browse stop:*)", "Bash(browse restart:*)",
 "Bash(browse cookie:*)", "Bash(browse header:*)",
 "Bash(browse useragent:*)",
 "Bash(browse clipboard:*)", "Bash(browse screenshot-diff:*)",
 "Bash(browse find:*)", "Bash(browse inspect:*)",
-"Bash(browse instances:*)", "Bash(browse --headed:*)"
+"Bash(browse instances:*)", "Bash(browse --headed:*)",
+"Bash(browse rightclick:*)", "Bash(browse tap:*)",
+"Bash(browse swipe:*)", "Bash(browse mouse:*)",
+"Bash(browse keyboard:*)", "Bash(browse scrollinto:*)",
+"Bash(browse scrollintoview:*)", "Bash(browse set:*)",
+"Bash(browse box:*)", "Bash(browse errors:*)",
+"Bash(browse doctor:*)", "Bash(browse upgrade:*)",
+"Bash(browse --max-output:*)"
 ```
 
 ## IMPORTANT
@@ -189,6 +196,28 @@ browse --allowed-domains example.com,*.cdn.example.com goto https://example.com
 # State persistence
 browse state save mysite
 browse state load mysite
+browse state clean                    # delete states older than 7 days
+browse state clean --older-than 30    # custom threshold
+
+# Cookie management
+browse cookie clear                                      # clear all cookies
+browse cookie set auth token --domain .example.com       # set with options
+browse cookie export ./cookies.json                      # export to file
+browse cookie import ./cookies.json                      # import from file
+
+# Cookie import from real browsers (macOS — Chrome, Arc, Brave, Edge)
+browse cookie-import --list                              # show installed browsers
+browse cookie-import chrome --domain .example.com        # import cookies for a domain
+browse cookie-import arc --domain .github.com            # import from Arc
+browse cookie-import chrome --profile "Profile 1" --domain .site.com  # specific Chrome profile
+
+# Session auto-persistence (named sessions survive restarts)
+browse --session myapp goto https://app.com/login        # login...
+browse session-close myapp                               # state auto-saved (encrypted if BROWSE_ENCRYPTION_KEY set)
+browse --session myapp goto https://app.com/dashboard    # cookies auto-restored
+
+# Load state at launch
+browse --state auth.json goto https://app.com            # load cookies before first command
 
 # Auth vault (credentials never visible to LLM)
 browse auth save github https://github.com/login user pass123
@@ -199,11 +228,31 @@ browse har start
 browse goto https://example.com
 browse har stop ./recording.har
 
-# Video recording
+# Video recording (watch a .webm of the session)
+browse video start ./videos
+browse goto https://example.com
+browse click @e3
+browse video stop
+
+# Command recording (export replayable scripts)
+browse record start
+browse goto https://example.com
+browse click "a"
+browse fill "[id=search]" "test query"
+browse record stop
+browse record export replay ./recording.json    # replay with: npx @puppeteer/replay ./recording.json
+browse record export browse ./steps.json        # replay with: cat steps.json | browse chain
+
+# Both together (video + replayable script)
 browse video start ./videos
+browse record start
 browse goto https://example.com
+browse snapshot -i
 browse click @e3
+browse fill "[id=email]" "user@test.com"
+browse record stop
 browse video stop
+browse record export replay ./recording.json
 
 # Device emulation
 browse emulate iphone
@@ -286,11 +335,13 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ```
 browse click <selector>        Click element (CSS selector or @ref)
 browse click <x>,<y>           Click at page coordinates (e.g. 590,461)
+browse rightclick <selector>   Right-click element (context menu)
 browse dblclick <selector>     Double-click element
 browse fill <selector> <value> Fill input field
 browse select <selector> <val> Select dropdown value
 browse hover <selector>        Hover over element
 browse focus <selector>        Focus element
+browse tap <selector>          Tap element (requires touch context via emulate)
 browse check <selector>        Check checkbox
 browse uncheck <selector>      Uncheck checkbox
 browse drag <src> <tgt>        Drag source to target
@@ -298,8 +349,24 @@ browse type <text>             Type into focused element
 browse press <key>             Press key (Enter, Tab, Escape, etc.)
 browse keydown <key>           Hold key down
 browse keyup <key>             Release key
+browse keyboard inserttext <t> Insert text without key events
 browse scroll [sel|up|down]    Scroll element/viewport/bottom
-browse wait <sel|--url|--network-idle>  Wait for element, URL, or network
+browse scrollinto <sel>        Scroll element into view (explicit)
+browse swipe <dir> [px]        Swipe up/down/left/right (touch events)
+browse mouse move <x> <y>     Move mouse to coordinates
+browse mouse down [button]     Press mouse button (left/right/middle)
+browse mouse up [button]       Release mouse button
+browse mouse wheel <dy> [dx]   Scroll wheel
+browse wait <sel>              Wait for element to appear
+browse wait <sel> --state hidden  Wait for element to disappear
+browse wait <ms>               Wait for milliseconds
+browse wait --text "..."       Wait for text to appear in page
+browse wait --fn "expr"        Wait for JavaScript condition
+browse wait --load <state>     Wait for load state
+browse wait --url <pattern>    Wait for URL match
+browse wait --network-idle     Wait for network idle
+browse set geo <lat> <lng>     Set geolocation
+browse set media <scheme>      Set color scheme (dark/light/no-preference)
 browse viewport <WxH>          Set viewport size (e.g. 375x812)
 browse upload <sel> <files>    Upload file(s) to a file input
 browse highlight <selector>    Highlight element (visual debugging)
@@ -327,8 +394,10 @@ browse attrs <selector>        Get element attributes as JSON
 browse element-state <selector> Element state (visible/enabled/checked/focused)
 browse value <selector>        Get input field value
 browse count <selector>        Count matching elements
+browse box <selector>          Get bounding box as JSON {x, y, width, height}
 browse dialog                  Last dialog info or "(no dialog detected)"
 browse console [--clear]       View/clear console messages
+browse errors [--clear]        View/clear page errors (filtered from console)
 browse network [--clear]       View/clear network requests
 browse cookies                 Dump all cookies as JSON
 browse storage [set <k> <v>]   View/set localStorage
@@ -342,6 +411,8 @@ browse clipboard write <text>  Write text to system clipboard
 ```
 browse screenshot [path]              Viewport screenshot (default: .browse/sessions/{id}/screenshot.png)
 browse screenshot --full [path]       Full-page screenshot (entire scrollable page)
+browse screenshot <sel|@ref> [path]   Screenshot specific element
+browse screenshot --clip x,y,w,h [path]  Screenshot clipped region
 browse screenshot --annotate [path]   Screenshot with numbered badges + legend
 browse pdf [path]                     Save as PDF
 browse responsive [prefix]            Screenshots at mobile/tablet/desktop
@@ -360,6 +431,11 @@ browse find text <query>              Find elements by text content
 browse find label <query>             Find elements by label
 browse find placeholder <query>       Find elements by placeholder
 browse find testid <query>            Find elements by test ID
+browse find alt <query>               Find elements by alt text
+browse find title <query>             Find elements by title attribute
+browse find first <sel>               First matching element
+browse find last <sel>                Last matching element
+browse find nth <n> <sel>             Nth matching element (0-indexed)
 ```
 
 ### Compare
@@ -394,6 +470,15 @@ browse state save [name]       Save cookies + localStorage (all origins)
 browse state load [name]       Restore saved state
 browse state list              List saved states
 browse state show [name]       Show contents of saved state
+browse state clean             Delete states older than 7 days
+browse state clean --older-than N   Custom age threshold (days)
+```
+
+### Cookie import (macOS — borrow auth from real browsers)
+```
+browse cookie-import --list                         List installed browsers
+browse cookie-import <browser> --domain <d>         Import cookies for a domain
+browse cookie-import <browser> --profile <p> --domain <d>   Specific Chrome profile
 ```
 
 ### Auth vault
@@ -417,11 +502,22 @@ browse video stop              Stop recording and save video files
 browse video status            Check if recording is active
 ```
 
+### Command recording & export
+```
+browse record start                    Start recording commands
+browse record stop                     Stop recording, keep steps for export
+browse record status                   Recording state and step count
+browse record export browse [path]     Export as chain-compatible JSON (replay with browse chain)
+browse record export replay [path]    Export as Chrome DevTools Recorder (Playwright/Puppeteer)
+```
+
 ### Server management
 ```
 browse status                  Server health, uptime, session count
 browse instances               List all running browse servers (instance, PID, port, status)
 browse version                 Print CLI version
+browse doctor                  System check (Bun, Playwright, Chromium)
+browse upgrade                 Self-update via npm
 browse stop                    Shutdown server
 browse restart                 Kill + restart server
 browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
@@ -431,10 +527,12 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 
 | Flag | Description |
 |------|-------------|
-| `--session <id>` | Named session (isolates tabs, refs, cookies) |
+| `--session <id>` | Named session (isolates tabs, refs, cookies — auto-persists on close) |
+| `--state <path>` | Load state file (cookies/storage) before first command |
 | `--json` | Wrap output as `{success, data, command}` |
 | `--content-boundaries` | Wrap page content in nonce-delimited markers (prompt injection defense) |
 | `--allowed-domains <d,d>` | Block navigation/resources outside allowlist |
+| `--max-output <n>` | Truncate output to N characters |
 | `--headed` | Run browser in headed (visible) mode |
 | `--runtime <name>` | Browser engine: playwright (default), rebrowser (stealth) |
 
@@ -480,6 +578,7 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Auto-login | `auth save gh https://github.com/login user pass` → `auth login gh` |
 | Record network | `har start` → browse around → `har stop ./out.har` |
 | Record video | `video start ./vids` → browse around → `video stop` |
+| Export automation script | `record start` → browse around → `record export replay ./recording.json` |
 | Parallel agents | `--session agent-a <cmd>` / `--session agent-b <cmd>` |
 | Multi-step flow | `echo '[...]' \| browse chain` |
 | Secure browsing | `--allowed-domains example.com goto https://example.com` |
@@ -489,6 +588,14 @@ browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 | Find by accessibility | `find role button` / `find text "Submit"` |
 | Visual regression | `screenshot-diff baseline.png` |
 | Debug with DevTools | `inspect` (set BROWSE_DEBUG_PORT first) |
+| Get element position | `box @e3` |
+| Check page errors | `errors` |
+| Right-click context menu | `rightclick @e3` |
+| Test mobile gestures | `emulate iphone` → `tap @e1` / `swipe down` |
+| Set dark mode | `set media dark` |
+| Test geolocation | `set geo 37.7 -122.4` → verify in page |
+| Export/import cookies | `cookie export ./cookies.json` / `cookie import ./cookies.json` |
+| Limit output size | `--max-output 5000 text` |
 | See the browser | `browse --headed goto <url>` |
 | Bypass bot detection | `--runtime rebrowser goto <url>` |
 

package/bin/browse.ts

@@ -1,11 +0,0 @@
-#!/usr/bin/env bun
-import { main } from '../src/cli';
-
-if (process.env.__BROWSE_SERVER_MODE === '1') {
-  import('../src/server');
-} else {
-  main().catch((err) => {
-    console.error(`[browse] ${err.message}`);
-    process.exit(1);
-  });
-}

package/src/auth-vault.ts

@@ -1,244 +0,0 @@
-/**
- * Credential vault — AES-256-GCM encrypted credential storage
- *
- * Encryption key: BROWSE_ENCRYPTION_KEY env var (64-char hex)
- * or auto-generated at .browse/.encryption-key
- *
- * Storage: .browse/auth/<name>.json (mode 0o600)
- * Password never returned in list/get — only hasPassword: true
- */
-
-import * as crypto from 'crypto';
-import * as fs from 'fs';
-import * as path from 'path';
-import type { BrowserManager } from './browser-manager';
-import { DEFAULTS } from './constants';
-import { sanitizeName } from './sanitize';
-
-interface StoredCredential {
-  name: string;
-  url: string;
-  username: string;
-  encrypted: true;
-  iv: string;       // base64
-  authTag: string;  // base64
-  data: string;     // base64 (encrypted password)
-  usernameSelector?: string;
-  passwordSelector?: string;
-  submitSelector?: string;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface CredentialInfo {
-  name: string;
-  url: string;
-  username: string;
-  hasPassword: boolean;
-  createdAt: string;
-}
-
-export class AuthVault {
-  private authDir: string;
-  private encryptionKey: Buffer;
-
-  constructor(localDir: string) {
-    this.authDir = path.join(localDir, 'auth');
-    this.encryptionKey = this.resolveKey(localDir);
-  }
-
-  private resolveKey(localDir: string): Buffer {
-    // 1. Env var (64-char hex = 32 bytes)
-    const envKey = process.env.BROWSE_ENCRYPTION_KEY;
-    if (envKey) {
-      if (envKey.length !== 64) {
-        throw new Error('BROWSE_ENCRYPTION_KEY must be 64 hex characters (32 bytes)');
-      }
-      return Buffer.from(envKey, 'hex');
-    }
-
-    // 2. Key file
-    const keyPath = path.join(localDir, '.encryption-key');
-    if (fs.existsSync(keyPath)) {
-      const hex = fs.readFileSync(keyPath, 'utf-8').trim();
-      return Buffer.from(hex, 'hex');
-    }
-
-    // 3. Auto-generate
-    const key = crypto.randomBytes(32);
-    fs.writeFileSync(keyPath, key.toString('hex') + '\n', { mode: 0o600 });
-    return key;
-  }
-
-  private encrypt(plaintext: string): { ciphertext: string; iv: string; authTag: string } {
-    const iv = crypto.randomBytes(12);
-    const cipher = crypto.createCipheriv('aes-256-gcm', this.encryptionKey, iv);
-    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
-    return {
-      ciphertext: encrypted.toString('base64'),
-      iv: iv.toString('base64'),
-      authTag: cipher.getAuthTag().toString('base64'),
-    };
-  }
-
-  private decrypt(ciphertext: string, iv: string, authTag: string): string {
-    const decipher = crypto.createDecipheriv(
-      'aes-256-gcm',
-      this.encryptionKey,
-      Buffer.from(iv, 'base64'),
-    );
-    decipher.setAuthTag(Buffer.from(authTag, 'base64'));
-    const decrypted = Buffer.concat([
-      decipher.update(Buffer.from(ciphertext, 'base64')),
-      decipher.final(),
-    ]);
-    return decrypted.toString('utf-8');
-  }
-
-  save(
-    name: string,
-    url: string,
-    username: string,
-    password: string,
-    selectors?: { username?: string; password?: string; submit?: string },
-  ): void {
-    fs.mkdirSync(this.authDir, { recursive: true });
-
-    const { ciphertext, iv, authTag } = this.encrypt(password);
-    const now = new Date().toISOString();
-
-    const credential: StoredCredential = {
-      name,
-      url,
-      username,
-      encrypted: true,
-      iv,
-      authTag,
-      data: ciphertext,
-      usernameSelector: selectors?.username,
-      passwordSelector: selectors?.password,
-      submitSelector: selectors?.submit,
-      createdAt: now,
-      updatedAt: now,
-    };
-
-    const filePath = path.join(this.authDir, `${sanitizeName(name)}.json`);
-    fs.writeFileSync(filePath, JSON.stringify(credential, null, 2), { mode: 0o600 });
-  }
-
-  private load(name: string): StoredCredential {
-    const filePath = path.join(this.authDir, `${sanitizeName(name)}.json`);
-    if (!fs.existsSync(filePath)) {
-      throw new Error(`Credential "${name}" not found. Run "browse auth list" to see saved credentials.`);
-    }
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-  }
-
-  async login(name: string, bm: BrowserManager): Promise<string> {
-    const cred = this.load(name);
-    const password = this.decrypt(cred.data, cred.iv, cred.authTag);
-    const page = bm.getPage();
-
-    // Navigate to login URL
-    await page.goto(cred.url, {
-      waitUntil: 'domcontentloaded',
-      timeout: DEFAULTS.COMMAND_TIMEOUT_MS,
-    });
-
-    // Resolve selectors: use stored or auto-detect
-    const userSel = cred.usernameSelector || await autoDetectSelector(page, 'username');
-    const passSel = cred.passwordSelector || await autoDetectSelector(page, 'password');
-    const submitSel = cred.submitSelector || await autoDetectSelector(page, 'submit');
-
-    // Fill credentials
-    await page.fill(userSel, cred.username, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
-    await page.fill(passSel, password, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
-
-    // Submit
-    await page.click(submitSel, { timeout: DEFAULTS.ACTION_TIMEOUT_MS });
-    await page.waitForLoadState('domcontentloaded').catch(() => {});
-
-    return `Logged in as ${cred.username} at ${page.url()}`;
-  }
-
-  list(): CredentialInfo[] {
-    if (!fs.existsSync(this.authDir)) return [];
-
-    const files = fs.readdirSync(this.authDir).filter(f => f.endsWith('.json'));
-    return files.map(f => {
-      try {
-        const data = JSON.parse(fs.readFileSync(path.join(this.authDir, f), 'utf-8'));
-        return {
-          name: data.name,
-          url: data.url,
-          username: data.username,
-          hasPassword: true,
-          createdAt: data.createdAt,
-        };
-      } catch {
-        return null;
-      }
-    }).filter(Boolean) as CredentialInfo[];
-  }
-
-  delete(name: string): void {
-    const filePath = path.join(this.authDir, `${sanitizeName(name)}.json`);
-    if (!fs.existsSync(filePath)) {
-      throw new Error(`Credential "${name}" not found.`);
-    }
-    fs.unlinkSync(filePath);
-  }
-}
-
-/**
- * Auto-detect login form selectors by common patterns.
- */
-async function autoDetectSelector(page: any, field: 'username' | 'password' | 'submit'): Promise<string> {
-  if (field === 'username') {
-    const candidates = [
-      'input[type="email"]',
-      'input[name="email"]',
-      'input[name="username"]',
-      'input[name="user"]',
-      'input[name="login"]',
-      'input[autocomplete="username"]',
-      'input[autocomplete="email"]',
-      'input[type="text"]:first-of-type',
-    ];
-    for (const sel of candidates) {
-      const count = await page.locator(sel).count();
-      if (count > 0) return sel;
-    }
-    throw new Error('Could not auto-detect username field. Save with explicit selectors: browse auth save <name> <url> <user> <pass> --user-sel <sel> --pass-sel <sel> --submit-sel <sel>');
-  }
-
-  if (field === 'password') {
-    const candidates = [
-      'input[type="password"]',
-      'input[name="password"]',
-      'input[name="pass"]',
-      'input[autocomplete="current-password"]',
-    ];
-    for (const sel of candidates) {
-      const count = await page.locator(sel).count();
-      if (count > 0) return sel;
-    }
-    throw new Error('Could not auto-detect password field.');
-  }
-
-  // submit
-  const candidates = [
-    'button[type="submit"]',
-    'input[type="submit"]',
-    'form button',
-    'button:has-text("Log in")',
-    'button:has-text("Sign in")',
-    'button:has-text("Login")',
-    'button:has-text("Submit")',
-  ];
-  for (const sel of candidates) {
-    const count = await page.locator(sel).count();
-    if (count > 0) return sel;
-  }
-  throw new Error('Could not auto-detect submit button.');
-}