lobster-cli 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 iexcalibur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,6 +10,7 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/lobster-cli"><img src="https://img.shields.io/npm/v/lobster-cli?style=flat-square&color=c9a84c" alt="npm" /></a>
   <img src="https://img.shields.io/badge/node-%3E%3D20-black?style=flat-square" />
   <img src="https://img.shields.io/badge/license-MIT-black?style=flat-square" />
   <img src="https://img.shields.io/badge/AI-optional-c9a84c?style=flat-square" />
@@ -17,373 +18,250 @@
 
 ---
 
-## What is LobsterCLI
+## Why LobsterCLI
 
-LobsterCLI is a web automation engine that works in three ways:
+Every web automation tool today does one thing. Puppeteer gives you browser control — but no intelligence. LangChain gives you AI chains — but no browser. Scrapy gives you crawling — but no JavaScript. You end up wiring 3-4 tools together, writing glue code, and deciding which tool to use for each task.
 
-| Product | What it is | Install |
-|---------|-----------|---------|
-| **CLI** | Terminal tool — fetch, scrape, explore, automate | `npm install -g lobster-cli` |
-| **Chrome Extension** | Side panel chat UI — analyze any page you're browsing | Load `extension/` folder in Chrome |
-| **Library** | Import into your own Node.js project | `import { ... } from 'lobster-cli'` |
+LobsterCLI is a single engine that does all of it. It has a **Smart Router** that automatically picks the best approach for your task — from a simple HTTP fetch to a full AI agent — so you never have to choose.
+
+**What makes it unique:**
 
-All three share the same core engine — same Brain, same DOM extraction, same LLM client, same agent loop.
+- **One tool, not four.** Fetch, scrape, explore, and AI-navigate — all from `lobster`.
+- **AI is optional.** 80% of features work without any API key. The free tier covers most use cases.
+- **Smart Brain.** When you do use AI, the Brain classifies your intent and gathers only what's needed — no wasted tokens on screenshots when text is enough.
+- **Three interfaces, one engine.** CLI for developers, Chrome extension for everyone, npm library for builders. Same core, same results.
+- **Persistent sessions.** Login once with `--profile`, your cookies and auth survive forever. Attach to your running Chrome with `--attach` — use your real logged-in sessions.
+- **Stealth built-in.** Anti-bot detection out of the box. No separate puppeteer-stealth plugin, no extra config.
+- **Domain restrictions.** Build vertical products on top — a finance tool that only works on Bloomberg, a legal tool that only works on case databases. One config line.
+- **Actually works on modern sites.** Full React/Vue event simulation, shadow DOM, iframe extraction, dynamic content detection. Not just static HTML scraping.
 
 ---
 
-## When AI is needed vs when it's free
+## What is LobsterCLI
 
-This is the most important thing to understand:
+LobsterCLI is a web automation engine that works in three ways:
 
-### CLI — What's free, what needs AI
+| Product | What it is | Install |
+|---------|-----------|---------|
+| **CLI** | Terminal tool — fetch, scrape, explore, automate | `npm install -g lobster-cli` |
+| **Chrome Extension** | Side panel chat UI — analyze any page you're browsing | Load `extension/` in Chrome |
+| **Library** | Import into your own Node.js project | `npm install lobster-cli` |
 
-| Command | AI needed? | What it does |
-|---------|-----------|-------------|
-| `lobster fetch <url>` | **No** | Fetch page, extract as markdown/text/snapshot/HTML. Uses in-house parser, no Chrome needed. |
-| `lobster fetch <url> -e chrome` | **No** | Same but with full Chrome for JS-heavy pages. |
-| `lobster explore <url>` | **No** | Discover APIs, intercept network calls, detect frameworks, generate adapters. |
-| `lobster run <url>` | **No** | Run pre-built site adapters and YAML pipelines. |
-| `lobster list` | **No** | List all registered adapters. |
-| `lobster config` | **No** | View/edit settings. |
-| `lobster doctor` | **No** | Diagnose setup, check Chrome, verify API key. |
-| `lobster setup` | **No** | Interactive setup wizard (AI provider selection is optional). |
-| `lobster plugin install` | **No** | Install community adapters from GitHub. |
-| `lobster agent "task"` | **Yes** | AI agent that reads pages, reasons, clicks, types, and navigates autonomously. |
+All three share the same core engine. **80% of features work without any AI key.**
 
-**80% of CLI features work without any API key.**
+---
 
-### Chrome Extension — What's free, what needs AI
+## Install
 
-| Action | AI needed? | What it does |
-|--------|-----------|-------------|
-| Click **"Summarize this page"** | **No** | Extracts headings, word count, content preview, page type, framework detection. |
-| Click **"Extract as Markdown"** | **No** | Converts full page DOM to clean Markdown. Copy to clipboard. |
-| Click **"Detect all forms"** | **No** | Scans all form fields — labels, types, values, required/disabled state. |
-| Click **"Show key links"** | **No** | Extracts all meaningful links from the page. |
-| Click **"Monitor API calls"** | **No** | Intercepts fetch/XHR, shows live API calls with method/URL/status. |
-| Click **"DOM snapshot"** | **No** | 12-stage pruned DOM snapshot, LLM-optimized. |
-| Type any question | **Yes** | Brain classifies intent, gathers right data, sends to LLM for answer. |
-| Click **"What's on screen?"** | **Yes** | Captures screenshot + sends to vision model for visual analysis. |
+```bash
+npm install -g lobster-cli
+```
 
-**The 6 built-in chips work without AI. Typed questions need an API key.**
+Or clone and build:
 
-### What the Brain does (smart intent classification)
+```bash
+git clone https://github.com/iexcalibur/lobster-cli.git
+cd lobster-cli
+npm install && npm run build && npm link
+```
 
-When you type a question, the Brain decides what data to gather before answering:
+Requires Node.js 20+. Chrome/Chromium needed only for browser features.
 
-```
-"summarize this page"              → Brain: { screenshot: false, markdown: true }
-                                     Cost: ~$0.001 (text only)
+---
 
-"what is this email about"         → Brain: { screenshot: false, markdown: true }
-                                     Cost: ~$0.001 (text only)
+## Quick Start
 
-"what images are on this page"     → Brain: { screenshot: true, markdown: true }
-                                     Cost: ~$0.01 (screenshot + text)
+```bash
+# Extract content from any page (no AI, no Chrome)
+lobster fetch https://example.com
 
-"what does the layout look like"   → Brain: { screenshot: true, markdown: false }
-                                     Cost: ~$0.01 (screenshot only)
+# Discover hidden APIs on a site
+lobster explore https://reddit.com
 
-"what forms are on this page"      → Brain: { screenshot: false, forms: true }
-                                     Cost: ~$0.001 (form extraction + text)
-```
+# AI agent navigates autonomously (needs API key)
+lobster agent "find pricing on example.com" --url https://example.com
 
-The Brain saves money by **not** taking screenshots when they aren't needed. Most questions only need text.
+# Use stealth mode to avoid bot detection
+lobster fetch https://linkedin.com --stealth
 
-### Library — Same rules apply
+# Use a persistent profile (cookies survive restarts)
+lobster agent "check my notifications" --url https://github.com --profile work
 
-```typescript
-import { classifyIntent } from 'lobster-cli/brain'  // No AI needed for heuristic mode
-import { PuppeteerPage } from 'lobster-cli/page'     // No AI needed
-import { MARKDOWN_SCRIPT } from 'lobster-cli/dom'     // No AI needed
-import { exploreSite } from 'lobster-cli/discover'    // No AI needed
-import { AgentCore } from 'lobster-cli/agent'         // Needs AI
-import { LLM } from 'lobster-cli/llm'                 // Needs AI
+# Attach to your running Chrome (use your logged-in sessions)
+lobster agent "check inbox" --url https://gmail.com --attach
 ```
 
 ---
 
-## Install
+## What's Free vs What Needs AI
 
 ### CLI
 
-```bash
-# Install globally
-npm install -g lobster-cli
-
-# Or clone and build
-git clone https://github.com/iexcalibur/lobster-cli.git
-cd lobster-cli
-npm install
-npm run build
-npm link
-```
-
-Requires Node.js 20+. Chrome/Chromium needed only for browser features.
+| Command | AI? | What it does |
+|---------|-----|-------------|
+| `lobster fetch <url>` | No | Extract as markdown, text, snapshot, HTML, semantic tree |
+| `lobster explore <url>` | No | Discover APIs, detect frameworks, generate adapters |
+| `lobster run <url>` | No | Run site adapters and YAML pipelines |
+| `lobster list` | No | List registered adapters |
+| `lobster config` | No | View/edit settings |
+| `lobster doctor` | No | Diagnose setup |
+| `lobster setup` | No | Interactive setup wizard |
+| `lobster plugin install` | No | Install community adapters |
+| `lobster agent "task"` | **Yes** | AI agent that reasons, clicks, types, navigates |
 
 ### Chrome Extension
 
-1. Clone this repo
-2. Open `chrome://extensions/`
-3. Enable **Developer mode** (top right)
-4. Click **Load unpacked** → select the `extension/` folder
-5. Click the LobsterCLI icon → opens as a side panel
-
-### Library (in your own project)
-
-```bash
-npm install lobster-cli
-```
-
-```typescript
-import { classifyIntent, heuristicClassify } from 'lobster-cli/brain'
-import { PuppeteerPage, BrowserManager } from 'lobster-cli/browser'
-import { SNAPSHOT_SCRIPT, MARKDOWN_SCRIPT } from 'lobster-cli/dom'
-import { AgentCore } from 'lobster-cli/agent'
-import { exploreSite } from 'lobster-cli/discover'
-import { executePipeline } from 'lobster-cli/pipeline'
-import { LLM } from 'lobster-cli/llm'
-```
+| Action | AI? | What it does |
+|--------|-----|-------------|
+| Summarize this page | No | Headings, word count, content preview, framework detection |
+| Extract as Markdown | No | Full DOM-to-Markdown with copy button |
+| Detect all forms | No | Labels, types, values, required/disabled state |
+| Show key links | No | All meaningful links on the page |
+| Monitor API calls | No | Live fetch/XHR interception |
+| DOM snapshot | No | 12-stage pruned snapshot |
+| Type any question | **Yes** | Brain classifies intent, gathers data, sends to LLM |
+| What's on screen? | **Yes** | Captures screenshot + vision model analysis |
 
 ---
 
 ## AI Setup (optional)
 
-AI is only needed for `lobster agent` and typed chat questions in the extension.
-
 ```bash
 lobster setup
 ```
 
-| Provider | Default Model | Cost | Best for |
-|----------|--------------|------|----------|
-| **Google Gemini** | gemini-2.5-flash | **Free tier** | Most users — free, fast, vision support |
-| **OpenAI** | gpt-4o | Pay per token | Best reasoning |
-| **Anthropic** | claude-sonnet-4 | Pay per token | Best for code analysis |
-| **Ollama** | llama3.1 | **Free (local)** | Privacy, offline use |
-
-Or set manually:
-
-```bash
-lobster config set llm.provider gemini
-lobster config set llm.apiKey AIza...
-lobster config set llm.model gemini-2.5-flash
-```
+| Provider | Model | Cost |
+|----------|-------|------|
+| **Google Gemini** | gemini-2.5-flash | Free tier available |
+| **OpenAI** | gpt-4o | Pay per token |
+| **Anthropic** | claude-sonnet-4 | Pay per token |
+| **Ollama** | llama3.1 | Free (runs locally) |
 
 ---
 
-## CLI Commands
+## Key Features
 
-### `lobster fetch <url>` — Extract content (no AI)
+### Smart Brain
+When you ask a question, the Brain classifies your intent and gathers only what's needed:
 
-```bash
-lobster fetch https://example.com                  # markdown output
-lobster fetch https://example.com -d snapshot      # LLM-optimized DOM
-lobster fetch https://example.com -d text          # plain text
-lobster fetch https://example.com -d semantic      # W3C accessible tree
-lobster fetch https://example.com -d html          # raw HTML
-lobster fetch https://example.com -e chrome -w 5   # force Chrome, wait 5s
 ```
-
-Engines: `auto` (default), `fast` (in-house parser, no Chrome), `chrome` (full browser).
-
-### `lobster run <url>` — Smart router (no AI)
-
-```bash
-lobster run https://api.github.com/users/octocat   # direct HTTP fetch
-lobster run https://news.ycombinator.com            # adapter if registered
-lobster run https://example.com -f yaml             # output as YAML
+"summarize this page"           → reads text only (~$0.001)
+"what images are showing"       → captures screenshot + text (~$0.01)
+"what forms are on this page"   → extracts form data (~$0.001)
 ```
 
-### `lobster agent <task>` — AI agent (needs API key)
+### Persistent Profiles
+Store Chrome sessions that survive restarts — cookies, auth, extensions.
 
 ```bash
-lobster agent "search for TypeScript on Hacker News" --url https://news.ycombinator.com
-lobster agent "find the cheapest flight to Tokyo" --url https://google.com/flights
-lobster agent "log in and check my notifications" --url https://github.com
+lobster profile create work
+lobster agent "check gmail" --profile work    # login persists
 ```
 
-The agent observes the DOM → sends to LLM → decides what to click/type/scroll → repeats until done (max 40 steps).
-
-### `lobster explore <url>` — Discover APIs (no AI)
+### Chrome Attach
+Connect to your running Chrome with all your logins.
 
 ```bash
-lobster explore https://reddit.com
-lobster explore https://twitter.com -w 5
+lobster agent "check notifications" --attach
 ```
 
-Intercepts network calls, clicks around to find hidden APIs, detects frameworks, scores endpoints, and generates adapter files.
-
-### `lobster config` — Settings
+### Stealth Mode
+Anti-bot detection — hides headless Chrome fingerprint.
 
 ```bash
-lobster config show
-lobster config set llm.provider anthropic
-lobster config set browser.headless false
+lobster fetch https://protected-site.com --stealth
 ```
 
-### `lobster plugin` — Community adapters
+### Compact Snapshot
+Token-efficient DOM snapshots (~800 tokens vs ~3000+).
 
 ```bash
-lobster plugin install github-user/reddit-adapter
-lobster plugin list
+lobster fetch https://example.com -d snapshot --compact
 ```
 
----
+### Semantic Element Finding
+AI agent finds elements by name instead of guessing index numbers.
 
-## Chrome Extension
-
-The extension is a chat-style side panel (like Gemini or Claude) docked to the right of your browser.
-
-### Free features (no API key)
+```
+"click the login button" → finds [1] button "Sign In" (score: 0.81)
+```
 
-Click any of the 6 built-in chips:
+### Domain Guard
+Restrict which websites the engine can operate on.
 
-- **Summarize this page** — page type, headings, word count, framework, content preview
-- **Extract as Markdown** — full DOM-to-Markdown with copy button
-- **Detect all forms** — every form field with label, type, value, required state
-- **Show key links** — all meaningful links on the page
-- **Monitor API calls** — live fetch/XHR interception
-- **DOM snapshot** — 12-stage pruned snapshot
+```typescript
+import { DomainGuard } from 'lobster-cli/domain-guard'
 
-### AI features (needs API key)
+const guard = new DomainGuard({
+  allowDomains: ['bloomberg.com', 'yahoo.com'],
+  blockMessage: 'This tool only works on finance sites.',
+})
+```
 
-Type any question in the chat:
+### Site Explorer
+Discover hidden APIs on any website — no AI needed.
 
-- "What is this email about?" — reads page text, gives natural language answer
-- "What images are on this page?" — captures screenshot, uses vision model
-- "Draft a reply to this email" — reads content, writes a response
-- "What color is the header?" — captures screenshot, analyzes visually
+```bash
+lobster explore https://reddit.com
+```
 
-The **Brain** automatically decides whether to capture a screenshot or just read text, so you don't pay for vision when you don't need it.
+Intercepts network calls, clicks buttons to trigger hidden APIs, detects frameworks, scores endpoints, and generates YAML adapters.
 
-### Setup AI in extension
+### Pipeline Engine
+Declarative YAML pipelines with 17 steps and template expressions.
 
-Click the gear icon → Settings → pick provider → enter key → Save.
+```yaml
+steps:
+  - navigate: https://news.ycombinator.com
+  - evaluate: |
+      [...document.querySelectorAll('.titleline > a')]
+        .map(a => ({ title: a.textContent, url: a.href }))
+  - limit: 10
+```
 
 ---
 
-## Use as a library
+## Use as a Library
 
-LobsterCLI exports every module for use in your own projects:
+```bash
+npm install lobster-cli
+```
 
 ```typescript
-// Brain — intent classification
-import { classifyIntent, heuristicClassify } from 'lobster-cli/brain'
-
-// Browser — page control
+import { classifyIntent } from 'lobster-cli/brain'
 import { BrowserManager, PuppeteerPage } from 'lobster-cli/browser'
-
-// DOM scripts — run in any browser context
-import { SNAPSHOT_SCRIPT, MARKDOWN_SCRIPT, FORM_STATE_SCRIPT } from 'lobster-cli/dom'
-
-// Agent — autonomous web navigation
+import { SNAPSHOT_SCRIPT, MARKDOWN_SCRIPT } from 'lobster-cli/dom'
 import { AgentCore } from 'lobster-cli/agent'
-
-// LLM — multi-provider client
-import { LLM } from 'lobster-cli/llm'
-
-// Pipeline — declarative YAML execution
-import { executePipeline } from 'lobster-cli/pipeline'
-
-// Discovery — find site APIs
+import { DomainGuard } from 'lobster-cli/domain-guard'
 import { exploreSite } from 'lobster-cli/discover'
-
-// Config — load/save settings
-import { loadConfig, saveConfig } from 'lobster-cli/config'
-```
-
-### Example: build a search agent
-
-```typescript
-import { BrowserManager } from 'lobster-cli/browser'
-import { AgentCore } from 'lobster-cli/agent'
+import { executePipeline } from 'lobster-cli/pipeline'
 import { LLM } from 'lobster-cli/llm'
-import { classifyIntent } from 'lobster-cli/brain'
-
-async function search(query) {
-  // Brain decides what data is needed
-  const intent = await classifyIntent(query, 'Google Search')
-
-  // Launch browser
-  const browser = new BrowserManager({ headless: true })
-  const page = await browser.launch('https://google.com')
-
-  // Run agent
-  const agent = new AgentCore({ page, llm: new LLM(config), maxSteps: 20 })
-  const result = await agent.execute(query)
-
-  await page.close()
-  return result
-}
 ```
 
 ---
 
-## Architecture
-
-```
-lobster-cli/
-├── src/
-│   ├── brain/          → Intent classifier (LLM + heuristic fallback)
-│   ├── browser/        → IPage interface, Puppeteer adapter, DOM scripts
-│   │   └── dom/        → 6 extraction strategies (snapshot, markdown, semantic, etc.)
-│   ├── agent/          → Observe-think-act loop, 8 tools, auto-fixer
-│   ├── llm/            → Multi-provider client (OpenAI, Anthropic, Gemini, Ollama)
-│   ├── pipeline/       → YAML pipeline engine, 17 steps, template expressions
-│   ├── adapter/        → Site adapter registry, YAML/TS loaders
-│   ├── router/         → Smart routing (HTTP → Engine → Adapter → Agent)
-│   ├── discover/       → API discovery, endpoint scoring, adapter generation
-│   ├── cascade/        → Auth strategy detection (public → cookie → header → intercept)
-│   ├── config/         → Settings (~/.lobster/config.yaml)
-│   ├── output/         → Formatters (table, JSON, YAML, CSV, Markdown)
-│   ├── plugin/         → GitHub plugin install/uninstall
-│   ├── lib.ts          → Library exports (for npm import)
-│   ├── cli.ts          → CLI commands (commander)
-│   └── index.ts        → CLI entry point
-│
-├── extension/          → Chrome extension (side panel)
-│   ├── sidepanel/      → Chat UI (HTML/CSS/JS)
-│   ├── background/     → Service worker (LLM calls, screenshot capture)
-│   ├── shared/         → DOM scripts (same code as CLI, ported to browser JS)
-│   ├── options/        → Settings page
-│   └── manifest.json   → Chrome extension manifest (v3, side panel API)
-│
-├── logo.svg            → Logo (SVG)
-├── logo.png            → Logo (512px PNG)
-└── package.json        → Dual: CLI binary + library exports
-```
+## Chrome Extension
 
----
+Chat-style side panel docked to the right of your browser (like Gemini or Claude).
 
-## Environment Variables
+**Install:**
+1. Clone this repo
+2. Open `chrome://extensions/` → enable Developer mode
+3. Click Load unpacked → select `extension/` folder
+4. Click LobsterCLI icon → side panel opens
 
-| Variable | Purpose |
-|----------|---------|
-| `LOBSTER_API_KEY` | LLM API key (overrides config) |
-| `LOBSTER_MODEL` | LLM model name |
-| `LOBSTER_BASE_URL` | LLM API base URL |
-| `LOBSTER_CDP_ENDPOINT` | Chrome DevTools Protocol endpoint |
-| `LOBSTER_BROWSER_PATH` | Path to Chrome/Chromium binary |
+**AI setup:** Click gear icon → Settings → pick provider → enter key → Save.
 
 ---
 
-## Dependencies
-
-| Package | Purpose |
-|---------|---------|
-| `commander` | CLI framework |
-| `puppeteer-core` | Chrome control (no bundled Chrome) |
-| `zod` | Schema validation |
-| `chalk` | Terminal colors |
-| `cli-table3` | Table formatting |
-| `js-yaml` | YAML parsing |
-| `ws` | WebSocket |
+## Documentation
 
-No AI SDK. LLM calls use native `fetch()` with our own protocol adapters.
+For detailed technical documentation, see **[DOCS.md](DOCS.md)**.
 
 ---
 
 ## License
 
-MIT
+MIT License — Copyright (c) 2025 iexcalibur
+
+See [LICENSE](LICENSE) for full text.

package/dist/browser/chrome-attach.js

@@ -0,0 +1,102 @@
+// src/browser/chrome-attach.ts
+import http from "http";
+
+// src/utils/logger.ts
+import chalk from "chalk";
+var log = {
+  info: (msg) => console.log(chalk.blue("\u2139"), msg),
+  success: (msg) => console.log(chalk.green("\u2713"), msg),
+  warn: (msg) => console.log(chalk.yellow("\u26A0"), msg),
+  error: (msg) => console.error(chalk.red("\u2717"), msg),
+  debug: (msg) => {
+    if (process.env.LOBSTER_DEBUG) console.log(chalk.gray("\u22EF"), msg);
+  },
+  step: (n, msg) => console.log(chalk.cyan(`[${n}]`), msg),
+  dim: (msg) => console.log(chalk.dim(msg))
+};
+
+// src/browser/chrome-attach.ts
+var DEFAULT_PORTS = [9222, 9229, 9333, 9515];
+var PROBE_TIMEOUT = 1500;
+function probePort(port) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://127.0.0.1:${port}/json/version`, {
+      timeout: PROBE_TIMEOUT
+    }, (res) => {
+      let data = "";
+      res.on("data", (chunk) => {
+        data += chunk;
+      });
+      res.on("end", () => {
+        try {
+          const info = JSON.parse(data);
+          if (info.webSocketDebuggerUrl) {
+            resolve({
+              wsEndpoint: info.webSocketDebuggerUrl,
+              port,
+              version: info["Protocol-Version"] || "",
+              browser: info.Browser || ""
+            });
+          } else {
+            resolve(null);
+          }
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("error", () => resolve(null));
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+async function discoverChrome(ports) {
+  const portsToCheck = ports || DEFAULT_PORTS;
+  log.debug(`Scanning ports for Chrome: ${portsToCheck.join(", ")}`);
+  const results = await Promise.all(portsToCheck.map(probePort));
+  const found = results.find(Boolean) || null;
+  if (found) {
+    log.info(`Found Chrome on port ${found.port}: ${found.browser}`);
+  } else {
+    log.debug("No running Chrome instance found on debug ports.");
+  }
+  return found;
+}
+async function getWebSocketDebuggerUrl(port) {
+  const result = await probePort(port);
+  return result?.wsEndpoint || null;
+}
+async function resolveAttachTarget(target) {
+  if (target === true || target === "true") {
+    const result = await discoverChrome();
+    if (!result) {
+      throw new Error(
+        "No running Chrome found. Start Chrome with:\n  google-chrome --remote-debugging-port=9222\n  # or on Mac:\n  /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222"
+      );
+    }
+    return result.wsEndpoint;
+  }
+  if (typeof target === "string") {
+    if (target.startsWith("ws://") || target.startsWith("wss://")) {
+      return target;
+    }
+    const port = parseInt(target, 10);
+    if (!isNaN(port) && port > 0 && port < 65536) {
+      const url = await getWebSocketDebuggerUrl(port);
+      if (!url) {
+        throw new Error(`No Chrome found on port ${port}. Make sure Chrome is running with --remote-debugging-port=${port}`);
+      }
+      return url;
+    }
+    throw new Error(`Invalid attach target: "${target}". Use "true" for auto-discover, a port number, or a ws:// URL.`);
+  }
+  throw new Error("Invalid attach target.");
+}
+export {
+  discoverChrome,
+  getWebSocketDebuggerUrl,
+  resolveAttachTarget
+};
+//# sourceMappingURL=chrome-attach.js.map