@thinkbrowse/cli 0.1.0

package/README.md

@@ -0,0 +1,246 @@
+# @thinkbrowse/cli
+
+CLI for controlling browsers via ThinkBrowse cloud infrastructure. 21 commands covering the full browser automation API.
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+
+## Installation
+
+```bash
+npm install -g @thinkbrowse/cli
+```
+
+## Quick Start
+
+```bash
+# 1. Configure API key
+thinkbrowse config set-key mech_browse_your_api_key_here
+
+# 2. Start a cloud browser session (waits for provisioning)
+thinkbrowse cloud start
+
+# 3. Navigate and interact
+thinkbrowse navigate "https://example.com"
+thinkbrowse snapshot                    # Get accessibility tree
+thinkbrowse click "button.submit"
+thinkbrowse screenshot --output page.png
+
+# 4. Stop the session
+thinkbrowse cloud stop
+```
+
+## AI Agent Workflow
+
+The `snapshot` command returns an accessibility tree — ideal for AI agents that need to understand page structure without screenshots:
+
+```bash
+thinkbrowse cloud start
+thinkbrowse navigate "https://github.com/trending"
+thinkbrowse snapshot                    # Returns accessibility tree
+thinkbrowse click "a.repo-name"         # AI decides what to click
+thinkbrowse wait-for-text "README"      # Wait for content
+thinkbrowse extract "article" --format json
+thinkbrowse cloud stop
+```
+
+## Commands
+
+### Session Management
+
+| Command | Description |
+|---------|-------------|
+| `cloud start` | Start a new cloud browser session |
+| `cloud stop` | Stop the active session |
+| `cloud list` | List all active sessions |
+| `cloud status` | Show session details |
+| `cloud use <id>` | Switch active session |
+
+#### Cloud Start Options
+
+```bash
+thinkbrowse cloud start [options]
+
+Options:
+  -b, --browser <type>  Browser: chromium (default), firefox, webkit
+  --proxy               Enable proxy rotation
+  --stealth             Enable anti-detection mode
+  --no-wait             Return immediately without waiting for ready
+```
+
+### Navigation
+
+| Command | Description |
+|---------|-------------|
+| `navigate <url>` | Navigate to a URL |
+| `back` | Go back in browser history |
+| `forward` | Go forward in browser history |
+
+```bash
+thinkbrowse navigate "https://example.com" --wait-until networkidle
+thinkbrowse back
+thinkbrowse forward
+```
+
+### Interaction
+
+| Command | Description |
+|---------|-------------|
+| `click <selector>` | Click an element |
+| `type <selector> <text>` | Type text (appends) |
+| `fill <selector> <value>` | Fill form field (clears first) |
+| `press <key>` | Press keyboard key |
+| `scroll` | Scroll the page |
+| `hover <selector>` | Hover over element |
+| `select <selector> <value>` | Select dropdown option |
+
+```bash
+thinkbrowse fill "#email" "user@example.com"
+thinkbrowse fill "#password" "secret123"
+thinkbrowse press Enter
+thinkbrowse click ".submit-btn" --timeout 5000
+thinkbrowse hover ".dropdown-trigger"
+thinkbrowse select "#country" "US"
+thinkbrowse scroll --down 500
+thinkbrowse scroll --to "#footer"
+```
+
+### Waiting
+
+| Command | Description |
+|---------|-------------|
+| `wait <condition>` | Wait for element or time (ms) |
+| `wait-for-text <text>` | Wait for text on page |
+
+```bash
+thinkbrowse wait 2000                              # Wait 2 seconds
+thinkbrowse wait ".loading-complete"                # Wait for element
+thinkbrowse wait ".spinner" --hidden                # Wait for element to hide
+thinkbrowse wait-for-text "Success" --timeout 10000 # Wait for text
+```
+
+### Observation
+
+| Command | Description |
+|---------|-------------|
+| `snapshot` | Get accessibility tree |
+| `screenshot` | Capture screenshot |
+| `extract <selector>` | Extract content from elements |
+| `evaluate [script]` | Execute JavaScript in page |
+
+```bash
+thinkbrowse snapshot
+thinkbrowse screenshot --output page.png --full-page
+thinkbrowse extract "h1"
+thinkbrowse extract ".item" --all --format json
+thinkbrowse extract "a" --attr href --all
+thinkbrowse evaluate "document.title"
+thinkbrowse evaluate --file script.js
+```
+
+### Dialog Handling
+
+| Command | Description |
+|---------|-------------|
+| `dialog get` | Check for pending dialog |
+| `dialog accept [text]` | Accept dialog |
+| `dialog dismiss` | Dismiss dialog |
+
+```bash
+thinkbrowse dialog get                    # Check for alerts/confirms/prompts
+thinkbrowse dialog accept                 # Accept alert/confirm
+thinkbrowse dialog accept "my answer"     # Accept prompt with text
+thinkbrowse dialog dismiss                # Dismiss/cancel dialog
+```
+
+### Monitoring
+
+| Command | Description |
+|---------|-------------|
+| `console` | Get browser console messages |
+| `network` | Get network requests |
+
+```bash
+thinkbrowse console    # View console.log, warnings, errors
+thinkbrowse network    # View XHR, fetch, and other requests
+```
+
+## Configuration
+
+```bash
+thinkbrowse config set-key <api-key>     # Set API key
+thinkbrowse config show                  # Show current config
+thinkbrowse config set apiUrl <url>      # Set custom API URL
+thinkbrowse config set defaultBrowser firefox
+thinkbrowse config reset                 # Reset all config
+```
+
+Config file: `~/.thinkbrowse/config.json`
+
+## Global Options
+
+- `--json` — Force JSON output (auto-enabled for non-TTY)
+- `--quiet` — Suppress non-error output
+- `--verbose` — Show debugging info
+
+## Examples
+
+### Web Scraping
+
+```bash
+thinkbrowse cloud start
+thinkbrowse navigate "https://news.ycombinator.com"
+thinkbrowse extract ".titleline > a" --all --format json > titles.json
+thinkbrowse screenshot --output hn.png
+thinkbrowse cloud stop
+```
+
+### Form Automation
+
+```bash
+thinkbrowse cloud start
+thinkbrowse navigate "https://example.com/login"
+thinkbrowse fill "#email" "user@example.com"
+thinkbrowse fill "#password" "secret123"
+thinkbrowse click "button[type=submit]"
+thinkbrowse wait-for-text "Dashboard"
+thinkbrowse screenshot --output logged-in.png
+thinkbrowse cloud stop
+```
+
+### Debugging a Page
+
+```bash
+thinkbrowse cloud start
+thinkbrowse navigate "https://myapp.com"
+thinkbrowse console     # Check for JS errors
+thinkbrowse network     # Check failed requests
+thinkbrowse snapshot    # See page structure
+thinkbrowse cloud stop
+```
+
+## Error Handling
+
+The CLI returns structured errors with suggestions:
+
+```
+Error: API key not configured
+Tip: Run: thinkbrowse config set-key <your-api-key>
+```
+
+Retryable errors (502, 503) are automatically retried with exponential backoff.
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| `API key not configured` | Run `thinkbrowse config set-key <key>` |
+| `No active session` | Run `thinkbrowse cloud start` first |
+| `Session provisioning timed out` | Check `thinkbrowse cloud status`, try again |
+| `fetch is not defined` | Upgrade to Node.js 18+ |
+| All requests return 404 | Update to latest CLI version |
+
+## License
+
+MIT

package/dist/bin/thinkbrowse.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * ThinkBrowse CLI Entry Point
+ */
+export {};
+//# sourceMappingURL=thinkbrowse.d.ts.map

package/dist/bin/thinkbrowse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinkbrowse.d.ts","sourceRoot":"","sources":["../../bin/thinkbrowse.ts"],"names":[],"mappings":";AAEA;;GAEG"}

package/dist/bin/thinkbrowse.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * ThinkBrowse CLI Entry Point
+ */
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read package.json for version
+// When compiled, __dirname will be dist/bin, so we need to go up two levels
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+const program = new Command();
+program
+    .name('thinkbrowse')
+    .description('CLI for controlling browsers via ThinkBrowse')
+    .version(packageJson.version)
+    .option('--json', 'Output in JSON format (default for non-TTY)')
+    .option('--quiet', 'Suppress non-error output')
+    .option('--verbose', 'Verbose output with debugging info');
+// Import commands
+import { createConfigCommand } from '../src/commands/config.js';
+import { createCloudCommand } from '../src/commands/cloud.js';
+import { createNavigateCommand, createClickCommand, createTypeCommand, createFillCommand, createScrollCommand, createWaitCommand, createWaitForTextCommand, createHoverCommand, createSelectCommand, createPressCommand, createBackCommand, createForwardCommand, createSnapshotCommand, createScreenshotCommand, createExtractCommand, createEvaluateCommand, createDialogCommand, createConsoleCommand, createNetworkCommand, } from '../src/commands/actions.js';
+// Add commands
+program.addCommand(createConfigCommand());
+program.addCommand(createCloudCommand());
+// Browser actions
+program.addCommand(createNavigateCommand());
+program.addCommand(createBackCommand());
+program.addCommand(createForwardCommand());
+program.addCommand(createClickCommand());
+program.addCommand(createTypeCommand());
+program.addCommand(createFillCommand());
+program.addCommand(createPressCommand());
+program.addCommand(createScrollCommand());
+program.addCommand(createHoverCommand());
+program.addCommand(createSelectCommand());
+// Waiting
+program.addCommand(createWaitCommand());
+program.addCommand(createWaitForTextCommand());
+// Observation
+program.addCommand(createSnapshotCommand());
+program.addCommand(createScreenshotCommand());
+program.addCommand(createExtractCommand());
+program.addCommand(createEvaluateCommand());
+// Dialog, console, network
+program.addCommand(createDialogCommand());
+program.addCommand(createConsoleCommand());
+program.addCommand(createNetworkCommand());
+// Parse arguments
+program.parse(process.argv);
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+    program.outputHelp();
+}
+//# sourceMappingURL=thinkbrowse.js.map

package/dist/bin/thinkbrowse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thinkbrowse.js","sourceRoot":"","sources":["../../bin/thinkbrowse.ts"],"names":[],"mappings":"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"}

package/dist/src/adapters/cloud.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Cloud API adapter - connects to thinkbrowse.io API
+ */
+import type { BrowserAdapter } from './types.js';
+import type { Session, SessionOptions, ActionResult, NavigateOptions, ClickOptions, TypeOptions, ScreenshotOptions, ExtractOptions, WaitOptions, DialogResult, ConsoleResult, NetworkResult } from '../types.js';
+export declare class CloudAdapter implements BrowserAdapter {
+    private baseUrl;
+    private apiKey;
+    private defaultTimeout;
+    constructor(apiKey?: string, baseUrl?: string);
+    private request;
+    private sleep;
+    private getActiveSessionId;
+    startSession(options?: SessionOptions): Promise<Session>;
+    waitForSessionReady(sessionId: string, timeout?: number): Promise<Session>;
+    stopSession(sessionId?: string): Promise<void>;
+    getSession(sessionId: string): Promise<Session>;
+    listSessions(): Promise<Session[]>;
+    navigate(url: string, options?: NavigateOptions): Promise<ActionResult>;
+    goBack(): Promise<ActionResult>;
+    goForward(): Promise<ActionResult>;
+    click(selector: string, options?: ClickOptions): Promise<ActionResult>;
+    type(selector: string, text: string, options?: TypeOptions): Promise<ActionResult>;
+    fill(selector: string, value: string): Promise<ActionResult>;
+    press(key: string): Promise<ActionResult>;
+    scroll(options: {
+        selector?: string;
+        x?: number;
+        y?: number;
+    }): Promise<ActionResult>;
+    hover(selector: string): Promise<ActionResult>;
+    select(selector: string, value: string): Promise<ActionResult>;
+    wait(condition: string | number, options?: WaitOptions): Promise<ActionResult>;
+    waitForText(text: string, options?: {
+        timeout?: number;
+    }): Promise<ActionResult>;
+    snapshot(): Promise<ActionResult>;
+    screenshot(options?: ScreenshotOptions): Promise<ActionResult>;
+    extract(selector: string, options?: ExtractOptions): Promise<ActionResult>;
+    evaluate(script: string, args?: any[]): Promise<ActionResult>;
+    getDialog(): Promise<DialogResult>;
+    handleDialog(action: 'accept' | 'dismiss', promptText?: string): Promise<ActionResult>;
+    getConsoleMessages(): Promise<ConsoleResult>;
+    getNetworkRequests(): Promise<NetworkResult>;
+}
+//# sourceMappingURL=cloud.d.ts.map

package/dist/src/adapters/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../../src/adapters/cloud.ts"],"names":[],"mappings":"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"}