@puberty-labs/clits/README.md

CLiTS (Chrome Logging and Inspection Tool Suite) is a powerful Node.js library for AI-controlled Chrome browser automation, testing, and inspection. Features enhanced CSS selector support (:contains(), XPath), dry-run mode, element discovery tools, and co

<div align="center">
  <img src="https://raw.githubusercontent.com/Jason-Vaughan/CLiTS/refs/heads/main/assets/logo.png" alt="CLiTS Logo" width="200" height="200">
</div>

# CLiTS (Chrome Log Inspector & Troubleshooting System)

[![npm version](https://img.shields.io/npm/v/clits.svg)](https://www.npmjs.com/package/clits)
[![License: BSD](https://img.shields.io/badge/License-BSD-blue.svg)](LICENSE)

## 🎯 Cursor AI Integration

CLITS is specifically designed for seamless integration with Cursor AI, providing a powerful automated debugging workflow:

- **🤖 AI-First Design**: Built from the ground up for AI-assisted debugging
- **🔍 Automated Analysis**: Automatic log collection and analysis for AI processing
- **📊 Structured Output**: JSON-formatted data perfect for AI consumption
- **🎯 Smart Filtering**: AI-optimized filtering and monitoring capabilities
- **🔄 Real-time Feedback**: Instant feedback loops for AI debugging assistance

### Example AI Workflow
```typescript
// CLITS automatically provides structured data for AI analysis
const logs = await clits.captureDebugData();
// AI can now analyze the logs and provide debugging insights
```

A powerful CLI tool for extracting and sharing debugging data (logs, network info, etc.) for AI and web projects. CLI-first, with future browser extension support.

## Features

- **Chrome Integration**: Connect to Chrome DevTools protocol for real-time debugging
- **Log Extraction**: Capture console logs, network requests, and errors
- **Visual Debugging**: Screenshot capture with element highlighting
- **Element Detection**: Advanced CSS selector and visual element finding
- **Automation Framework**: JSON-based automation scripts
- **Network Monitoring**: Request/response tracking and analysis
- **Advanced Logging**: Structured logging with metadata, log rotation and size management
- **Component Monitoring**: React hooks, lifecycle tracking, prop changes
- **Network Analysis**: Request/response correlation, WebSocket tracking, JWT token monitoring, GraphQL support
- **State Management**: Redux state visualization, state change tracking, middleware debugging
- **Performance Monitoring**: React render metrics, memory usage tracking, event loop monitoring
- **UI Interaction**: User interaction recording, DOM mutation tracking, CSS change monitoring
- **Interactive login handling**
- **AI-friendly output format**
- **Extensible for custom automation**

---

## Prerequisites

- **Node.js** >= 20
- **Google Chrome** (latest recommended)
- **inquirer** (for interactive prompts)

---

## Installation

```sh
npm install -g clits
```

---

## Quick Start

### 🚀 Latest Features (v1.3.4) - AI AUTOMATION READY

**Production Status**: ✅ **ENHANCED SELECTOR SUPPORT - AI DEVELOPMENT WORKFLOW OPTIMIZED**

**🎯 NEW v1.3.4 FEATURES:**
- **Enhanced CSS Selectors**: `.bg-green-500`, `button:contains('Save')`, `[data-testid='btn']`
- **XPath Support**: `--click-xpath "//button[contains(text(), 'Delete')]"`
- **Dry-Run Mode**: `--dry-run` for testing selectors without executing clicks
- **Element Discovery**: `clits discover --selectors`, `--clickable`, `--xpath`
- **Smart Error Messages**: Shows attempted strategies and specific failure reasons

**Real-World Examples (Perfect for AI Automation):**
```bash
# Enhanced CSS selector support
clits interact --click ".bg-green-500" --capture-network
clits interact --click "button:contains('Recalculate')" --dry-run
clits interact --click "[data-testid='submit-btn']" --screenshot

# XPath expressions for complex elements
clits interact --click-xpath "//button[contains(text(), 'Save Changes')]"

# Element discovery for AI automation
clits discover --clickable --filter "btn" --output-format json
clits discover --selectors --limit 20
clits discover --xpath --filter "button"
```

**v1.3.4 Verification Results:**
- ✅ **CSS Classes**: `.bg-green-500`, `.btn.btn-primary` selectors working perfectly
- ✅ **Pseudo-selectors**: `button:contains('text')` implementation complete
- ✅ **Attribute Selectors**: `[data-testid]`, `[aria-label*="text"]` support
- ✅ **XPath Support**: Full XPath expressions via `--click-xpath`
- ✅ **Dry-Run Testing**: Safe selector testing without side effects
- ✅ **Discovery Tools**: Complete element discovery and selector generation
- ✅ **AI-Ready**: Perfect for AI-controlled browser automation workflows

### Basic Usage

```bash
# Extract logs from Chrome
clits extract --chrome --chrome-port 9222

# Interact with page elements
clits interact --click-text "Save" --chrome-port 9222
clits interact --click-region "center" --chrome-port 9222

# Run automation script
clits automate --script workflow.json --chrome-port 9222
```

## 🛡️ Cloudflare Bot Detection Workaround

**Important**: When automating Cloudflare-protected sites, you may encounter "Can't verify the user is human" errors. CLiTS includes an official workaround:

### Quick Fix
```bash
# Use the official Cloudflare-safe Chrome launcher
./scripts/start-cloudflare-safe-chrome.sh

# Or manually start Chrome with anti-detection flags
pkill -f "Google Chrome"
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug \
  --disable-blink-features=AutomationControlled \
  --exclude-switches="enable-automation" \
  --disable-extensions-except \
  --disable-plugins-discovery \
  --no-first-run \
  --no-default-browser-check &
sleep 5
```

### Verification
```bash
# Test the bypass worked
clits inspect --tabs --chrome-port 9222
clits navigate --url "https://your-cloudflare-site.com" --chrome-port 9222
clits vision --screenshot --output "cloudflare-test.png" --chrome-port 9222
```

For complete documentation, troubleshooting, and platform-specific instructions, see [**Cloudflare Workaround Guide**](docs/CLOUDFLARE_WORKAROUND.md).

### Advanced Features

```bash
# Visual element selection
clits interact --click-text "Save"               # Click element containing "Save"
clits interact --click-text "Submit"             # Click element containing "Submit"
clits interact --click-color "#ff0000"           # Click by color
clits interact --click-region "top-left"         # Click by screen region
clits interact --click-description "edit button" # Click by visual description

# Enhanced screenshot features
clits interact --screenshot --with-metadata    # Include element positions/text
clits interact --screenshot --annotated        # Draw boxes around clickable elements
clits interact --screenshot --selector-map     # Output clickable element map
clits interact --screenshot --fullpage --base64  # Full-page base64 output

# Selector discovery tools
clits inspect --find-selectors                 # List all available CSS selectors
clits inspect --find-clickable                 # List clickable elements with coordinates
clits inspect --element-map                    # Visual map of page elements
clits inspect --output-format json             # JSON output for AI processing

# Combined AI automation workflow
clits interact --click-text "Edit" --screenshot --base64 --selector-map --stdout
```

## Commands

### `clits extract`
Extract logs and debugging data from various sources.

**Options:**
- `--chrome`: Extract from Chrome DevTools
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--source <path>`: Extract from local log files
- `--patterns <glob>`: File patterns to match
- `--output-file <path>`: Save output to file
- `--format <format>`: Output format (json|text)
- `--filter <pattern>`: Filter logs by pattern
- `--time-range <range>`: Filter by time range
- `--log-levels <levels>`: Filter by log levels
- `--group-by-source`: Group logs by source
- `--error-summary`: Include summary statistics of error frequencies
- `--live-mode [duration]`: Run in live mode for specified duration in seconds (default: `60`)
- `--interactive-login`: This option is deprecated. Interactive login is now automatically handled if needed based on the selected Chrome tab.
- `--no-login`: Bypass any login prompts and run automation as unauthenticated

### `clits navigate`
Navigate to URLs, switch to specific tabs, and wait for elements.

**Options:**
- `--url <url>`: Navigate to specific URL (required)
- `--tab <index>`: **NEW (OnDeck)** - Navigate in specific tab by index (0-based)
- `--wait-for <selector>`: Wait for CSS selector to appear
- `--timeout <ms>`: Timeout in milliseconds (default: `30000`)
- `--screenshot <path>`: Take screenshot after navigation
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)

**Examples:**
```sh
# Standard navigation
clits navigate --url "http://localhost:5173/displays" --wait-for ".displays-manager" --screenshot "navigation.png"

# OnDeck: Navigate in specific tab
clits navigate --tab 1 --url "http://localhost:5173/displays" --wait-for ".displays-manager"

# Navigate in first tab with screenshot
clits navigate --tab 0 --url "http://localhost:3000/admin" --screenshot "admin-page.png"
```

### `clits discover-links`
**NEW in v1.0.7** - Discover all navigation links on the current page for dynamic automation.

**Options:**
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)
- `--verbose`: Enable verbose output

**Output Format:**
```json
{
  "links": [
    {"text": "Dashboard", "url": "/dashboard", "selector": "a[href='/dashboard']"},
    {"text": "Display Manager", "url": "/displays-manager", "selector": "a[href='/displays-manager']"},
    {"text": "Tasks", "url": "/tasks", "selector": "a[href='/tasks']"}
  ],
  "timestamp": "2025-06-08T05:52:00.000Z"
}
```

**Example:**
```sh
clits discover-links --chrome-port 9222
```

### `clits discover-tabs`
**NEW in v1.0.7-beta.3** - Advanced tab discovery and interaction for Material-UI dialogs and tabbed interfaces.

**Options:**
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)
- `--tab-label <label>`: Select tab by label after discovery
- `--tab-label-regex <pattern>`: Select tab by regex pattern
- `--custom-save-patterns <patterns>`: Custom save button text patterns (comma-separated)
- `--find-save-button`: Also discover the best save button in the current dialog
- `--verbose`: Enable verbose output

**Examples:**
```bash
# Basic tab discovery
clits discover-tabs --chrome-port 9222

# Find save button with default patterns
clits discover-tabs --chrome-port 9222 --find-save-button

# Discover tabs + find save button with custom patterns
clits discover-tabs --chrome-port 9222 --find-save-button --custom-save-patterns "Apply,Update,Confirm"

# Complete workflow: discover, select tab, find save button
clits discover-tabs --chrome-port 9222 --tab-label "Header Options" --find-save-button
```

**Advanced Features:**
- **Nested Tab Support**: Discovers tabs within `.MuiTabs-root` containers
- **Active State Detection**: Shows which tab is currently selected (`aria-selected="true"`, `.Mui-selected`)
- **Disabled State Detection**: Identifies disabled tabs (`aria-disabled="true"`, `.Mui-disabled`)
- **Multi-Strategy Selection**: Supports selection by data-testid, aria-label, text content, or nth-child

### `clits interact`
Interact with web elements, manage browser tabs, send keyboard commands, and capture screenshots.

**Element Interaction Options:**
- `--click <selector>`: Click element matching CSS selector
- `--click-text <text>`: Click element containing specific text (e.g., "Save", "Submit")
- `--by-text <text>`: Click element containing specific text (alias for --click-text, OnDeck compatibility)
- `--click-color <color>`: Click element with specific color (hex, rgb, or name)
- `--click-region <region>`: Click by screen region (top-left, top-right, bottom-left, bottom-right, center)
- `--click-description <description>`: Click by visual description (experimental AI feature)
- `--type <selector> <text>`: Type text into input field
- `--toggle <selector>`: Toggle switch/checkbox elements

**NEW: Tab Management Commands (OnDeck Feature Request)**
- `--switch-tab <index>`: Switch to tab by index (0-based) - `clits interact --switch-tab 0`
- `--tab-next`: Switch to next tab - `clits interact --tab-next`
- `--tab-prev`: Switch to previous tab - `clits interact --tab-prev`

**NEW: Keyboard Commands (OnDeck Feature Request)**
- `--key <key>`: Send keyboard key or shortcut - `clits interact --key "F5"`
- `--keys <keys>`: Send multiple keyboard keys (alias for --key) - `clits interact --keys "cmd+r"`

**Supported Keyboard Shortcuts:**
- **Page Control**: `F5`, `cmd+r`, `ctrl+r`, `cmd+shift+r`, `ctrl+shift+r` (refresh)
- **Navigation**: `escape`, `enter`, `tab`, `shift+tab`
- **Developer Tools**: `F12`, `cmd+option+i`, `ctrl+shift+i`
- **Window Management**: `cmd+w`, `ctrl+w` (close tab), `cmd+t`, `ctrl+t` (new tab)
- **Tab Navigation**: `cmd+2`, `ctrl+tab`

**Screenshot & Analysis Options:**
- `--screenshot`: Take a screenshot during interaction
- `--base64`: Output screenshot as base64 string (perfect for AI processing)
- `--stdout`: Output results in JSON format to stdout
- `--with-metadata`: Include element positions and page metadata
- `--annotated`: Add visual annotations around clickable elements
- `--selector-map`: Output map of clickable elements with coordinates
- `--fullpage`: Take a full-page screenshot

**General Options:**
- `--wait-for <selector>`: Wait for CSS selector to appear
- `--timeout <ms>`: Timeout in milliseconds (default: `30000`)
- `--capture-network`: Capture network requests during interaction
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)

**OnDeck Examples:**
```bash
# Tab switching commands
clits interact --switch-tab 0  # Switch to first tab
clits interact --switch-tab 1  # Switch to second tab
clits interact --tab-next      # Switch to next tab
clits interact --tab-prev      # Switch to previous tab

# Keyboard shortcuts (Mac)
clits interact --key "cmd+2"        # Switch to second tab via keyboard
clits interact --key "F5"           # Refresh page
clits interact --key "cmd+r"        # Refresh page (Mac)
clits interact --key "cmd+shift+r"  # Hard refresh (Mac)
clits interact --key "escape"       # Close modals/dialogs
clits interact --key "F12"          # Open dev tools

# Keyboard shortcuts (Windows/Linux)
clits interact --key "ctrl+tab"     # Switch tabs
clits interact --key "ctrl+r"       # Refresh page
clits interact --key "ctrl+shift+r" # Hard refresh
clits interact --key "ctrl+shift+i" # Open dev tools

# Better Material-UI support
clits interact --by-text "Launch"   # OnDeck-preferred text clicking
clits interact --click-text "Save"  # More robust than .MuiButton-root:nth-of-type(3)

# Combined workflows
clits interact --switch-tab 1 --key "F5" --screenshot # Switch tab and refresh
clits interact --by-text "Dashboard" --wait-for ".dashboard" --screenshot
```

### `clits inspect`
Inspect page elements, browser tabs, and discover selectors.

**Options:**
- `--find-selectors`: List all available CSS selectors on the page
- `--find-clickable`: List all clickable elements with coordinates
- `--element-map`: Generate visual map of page elements
- `--tabs`: **NEW (OnDeck)** - List all open browser tabs with URLs and titles
- `--output-format <format>`: Output format (json|table|interactive)
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)

**OnDeck Examples:**
```bash
# List all browser tabs with URLs and titles
clits inspect --tabs

# List tabs with JSON output for parsing
clits inspect --tabs --output-format json

# Combined inspection: tabs + clickable elements
clits inspect --tabs --find-clickable --output-format json
```

### `clits automate`
Run automation scripts from JSON files.

**Options:**
- `--script <path>`: JSON file with automation steps (required)
- `--monitor`: Enable monitoring during automation
- `--save-results <path>`: Save results to file
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)

**Automation Script Format:**
```json
{
  "steps": [
    {"action": "navigate", "url": "http://localhost:5173/displays"},
    {"action": "wait", "selector": "body", "timeout": 5000},
    {"action": "switch-tab", "tabIndex": 1, "wait": 1000},
    {"action": "key", "keyCommand": "F5", "wait": 2000},
    {"action": "wait", "selector": ".displays-manager", "timeout": 10000},
    {"action": "click", "selector": ".edit-button"},
    {"action": "click-text", "text": "Save", "timeout": 5000, "screenshotPath": "text-click.png"},
    {"action": "key", "keyCommand": "escape", "wait": 500},
    {"action": "click-region", "region": "center", "timeout": 5000, "screenshotPath": "region-click.png"},
    {"action": "toggle", "selector": ".toggle-switch[data-field='active']"},
    {"action": "key", "keyCommand": "cmd+r", "wait": 1000},
    {"action": "tab-next", "wait": 1000},
    {"action": "screenshot", "path": "after-toggle.png"}
  ],
  "options": {
    "timeout": 30000,
    "captureNetwork": true,
    "monitor": true
  }
}
```

**NEW OnDeck Actions:**
- `key`: Send keyboard commands - `{"action": "key", "keyCommand": "F5"}`
- `switch-tab`: Switch to specific tab - `{"action": "switch-tab", "tabIndex": 0}`
- `tab-next`: Switch to next tab - `{"action": "tab-next"}`
- `tab-prev`: Switch to previous tab - `{"action": "tab-prev"}`

📖 **Complete Documentation**: See [Automation Script Format Guide](docs/AUTOMATION_SCRIPT_FORMAT.md) for full schema, examples, and best practices.

**Example:**
```sh
# Basic automation with improved selector reliability
clits automate --script automation.json --chrome-port 9222 --monitor --save-results results.json

# Quick automation validation
clits automate --script test-workflow.json --chrome-port 9222
```

### `clits vision`
**Advanced visual state capture and screenshot automation with element-specific targeting.**

#### 🚀 NEW in v1.0.9-beta.1: Roadmap Features

**Options:**
- `--screenshot`: Take a screenshot
- `--video`: Record video of the interaction
- `--selectors <selectors>`: CSS selectors to target
- `--output <path>`: Output file path
- `--output-dir <dir>`: Output directory for batch processing
- `--base64`: Output as base64 string
- `--fullpage`: Take full-page screenshot
- `--highlight-all-clickable`: Highlight all clickable elements
- `--highlight-color <color>`: Custom highlight color
- `--annotate-text`: Add text annotations
- `--batch-diff`: Enable batch difference analysis
- `--baseline-dir <dir>`: Directory containing baseline images
- `--diff-threshold <value>`: Difference threshold (0-1)
- `--diff-report <path>`: Save diff analysis report
- `--meta <path>`: Save metadata to file
- `--chrome-host <host>`: Chrome DevTools host (default: `localhost`)
- `--chrome-port <port>`: Chrome DevTools port (default: `9222`)

**Examples:**
```bash
# Basic screenshot with element highlighting
clits vision --screenshot --selectors ".header,.content" --output "page.png"

# Full-page screenshot with annotations
clits vision --screenshot --fullpage --highlight-all-clickable --annotate-text --output "ui-documentation.png"

# Accessibility analysis visualization
clits vision --screenshot --fullpage --highlight-all-clickable --highlight-color "#0066ff" --annotate-text --meta "accessibility-report.json"
```

#### 🔄 Advanced Batch Processing Examples (NEW):
```sh
# Large-scale visual testing with diff analysis
clits vision --screenshot --selectors ".header,.sidebar,.content,.footer" --batch-diff --baseline-dir "./test-baselines" --output-dir "./test-results" --diff-report "batch-analysis.json"

# Multi-element regression testing
clits vision --screenshot --selectors ".error-states,.success-states,.warning-states" --batch-diff --diff-threshold 0.1 --output-dir "./regression-tests"

# Systematic UI validation with highlighting and video
clits vision --video --screenshot --selectors ".critical-elements" --highlight-all-clickable --batch-diff --video-output "validation-workflow.webm"
```

**AI Integration:**
VisionCLITS is designed for AI-driven visual debugging:
- **Automated Visual State Capture**: No manual intervention required
- **Structured JSON Output**: Perfect for AI analysis and decision-making
- **Element Validation**: Automatic visibility and existence checking
- **Batch Processing**: Handle multiple elements efficiently
- **Error Handling**: Graceful failures with detailed error reporting

### `clits-inspect`
Interactive website inspector for Chrome with hierarchical element navigation.

**Features:**
- **Hierarchical Element Navigation**: Navigate through page elements organized by DOM depth levels
- **Real-time Element Inspection**: View element properties, styles, and computed values
- **Network Monitoring**: Track requests and responses in real-time
- **Console Integration**: Execute JavaScript in the context of the page
- **Screenshot Capture**: Take screenshots of the current view or specific elements
- **Element Selection**: Click to select elements in the page
- **Search Functionality**: Find elements by selector, text, or attributes
- **Export Options**: Save inspection data in various formats

**Usage:**
```bash
clits-inspect --chrome-port 9222
```

**Output Format:**
```
[CLiTS-INSPECTOR][ELEMENTS] Element hierarchy
[CLiTS-INSPECTOR][STYLES] Computed styles
[CLiTS-INSPECTOR][PROPERTIES] Element properties
[CLiTS-INSPECTOR][NETWORK][REQUEST] Network request details
[CLiTS-INSPECTOR][NETWORK][RESPONSE] Network response details
[CLiTS-INSPECTOR][DOM] DOM structure
```

---

## Examples

### Standard Usage Examples

- **Node.js API Example:** See [`examples/node-api`](examples/node-api/README.md) for integrating CLiTS with an Express API, including REST endpoints for logs and error handling.
- **React Integration Example:** See [`examples/react-app`](examples/react-app/README.md) for capturing debug logs in a React app, error boundaries, and analytics integration.

---

## For AI Assistants

CLiTS is specifically designed for AI assistants with a complete automation framework that requires **zero human interaction**. The AI automation framework provides structured JSON output perfect for programmatic analysis and decision-making.

## 🤖 **AI Integration Guide**

**🚀 NEW: Complete AI Assistant Documentation Available!**

For comprehensive AI integration guidance, see our dedicated documentation:

### 📖 **Essential AI Documentation**
- **[🤖 AI Integration Guide](docs/AI_INTEGRATION.md)** - Complete getting started guide with human-in-the-loop protocols
- **[📋 AI Examples](docs/AI_EXAMPLES.md)** - Copy-pasteable command sequences for all scenarios  
- **[🚨 Error Codes](docs/ERROR_CODES.md)** - Structured error handling with recovery strategies

### 🚨 **CRITICAL: Human-in-the-Loop Protocol**

**⚠️ BEFORE ANY BROWSER AUTOMATION: AI assistants MUST follow this protocol**

1. **PAUSE AUTOMATION** - Do not attempt browser control without user permission
2. **PROMPT USER** - Explicitly ask for permission to control their browser  
3. **WAIT FOR CONFIRMATION** - Wait for explicit user approval (Y/N response)
4. **RESUME AUTOMATION** - Only proceed after receiving user consent

**Authentication Protocol:** User login sessions cannot be automated - require human intervention for all authentication.

### 🚀 **Quick AI Setup**

```bash
# 1. Start Chrome with debugging (REQUIRED)
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. Verify connection
curl http://localhost:9222/json/version

# 3. Test CLITS
clits --version
clits inspect --tabs
```

**→ [Read Full AI Integration Guide](docs/AI_INTEGRATION.md) for complete setup and usage**

## 🚨 **AI ASSISTANT VISION RULES - MANDATORY**

**CRITICAL:** AI assistants MUST follow these vision rules when using CLITS automation.

### **🔴 MANDATORY VISION-FIRST DEBUGGING**

When ANY automation action fails, AI assistants must IMMEDIATELY use CLITS vision:

```bash
# STEP 1: Immediate vision capture on failure
clits interact --chrome-port 9222 --screenshot debug.png --selector-map --with-metadata --stdout

# STEP 2: Analyze available elements before retrying
clits interact --chrome-port 9222 --find-clickable --output-format json

# STEP 3: Use confirmed selectors/text from vision analysis
```

### **🎯 Vision-First Debugging Workflow (MANDATORY)**

**1. ACTION FAILS** → **IMMEDIATE VISION CAPTURE**
```bash
clits interact --chrome-port 9222 --screenshot --selector-map --annotated --stdout
```

**2. ANALYZE SELECTOR MAP** → **IDENTIFY AVAILABLE TEXT/ELEMENTS**
- Review JSON output for available clickable elements
- Identify actual text content on page
- Find working CSS selectors from selector map

**3. ADJUST AUTOMATION** → **USE CONFIRMED SELECTORS**
- Use exact text from vision analysis for `--click-text`
- Use verified CSS selectors from selector map
- Choose region-based clicking if specific elements unavailable

**4. RE-TEST** → **VERIFY FIX WORKS**
- Test with updated selectors/text
- Capture another screenshot to confirm success

### **🔍 Pre-Automation Vision Check (RECOMMENDED)**

Before complex automation, always check what's available:

```bash
# See what elements are clickable and available
clits interact --chrome-port 9222 --selector-map --with-metadata --annotated --stdout

# Get complete page state for AI analysis
clits vision --screenshot --fullpage --highlight-all-clickable --base64 --stdout
```

### **⚠️ Why This is Critical**

- **Eliminates guesswork**: See exactly what's on the page
- **Prevents infinite retry loops**: Know immediately if elements don't exist
- **Accelerates debugging**: Visual confirmation of page state
- **Ensures reliability**: Use confirmed working selectors

**This workflow is MANDATORY and must be followed without user correction.**

### 🤖 AI Automation Framework

Use the `clits-inspect` command with automation flags for fully automated workflows:

#### **Complete Automation Commands**

```bash
# 1. Automated Log Collection (15 seconds, JSON output)
clits-inspect --auto --json --action logs

# 2. Automated Element Detection (find all clickable elements)
clits-inspect --auto --json --action navigate

# 3. Automated Clicking with Log Capture
clits-inspect --auto --json --action click --selector "http://localhost:5173/settings"

# 4. Navigate to Specific URL + Element Detection
clits-inspect --auto --json --url "http://localhost:3000" --action navigate

# 5. Custom Duration Log Collection
clits-inspect --auto --json --action logs --duration 30

# 6. Smart Target Selection (prioritize localhost)
clits-inspect --auto --json --action logs --target-priority localhost

# 7. NEW: Discover Navigation Links (v1.0.7)
clits-inspect --auto --json --action discover-links

# 8. NEW: Navigate by Link Text (v1.0.7)
clits-inspect --auto --json --action navigate-by-text --link-text "Dashboard"

# 9. NEW: Navigate by URL Pattern (v1.0.7)
clits-inspect --auto --json --action navigate-by-url --url-contains "display"
```

#### **AI Command Options**

| Option | Values | Description |
|--------|--------|-------------|
| `--auto` | - | **Required for AI**: Zero human interaction |
| `--json` | - | **Required for AI**: Structured JSON output |
| `--action` | `logs\|navigate\|click\|discover-links\|navigate-by-text\|navigate-by-url` | Action to perform |
| `--url` | URL string | Navigate to specific URL automatically |
| `--selector` | CSS selector or URL | Element to click (for click action) |
| `--duration` | seconds (default: 15) | Log collection duration |
| `--target-priority` | `localhost\|dev\|newest\|largest` | Smart tab selection |
| `--port` | port number (default: 9222) | Chrome debugging port |
| `--host` | hostname (default: localhost) | Chrome debugging host |

#### **AI Workflow Examples**

**1. Full Debugging Workflow:**
```bash
# Step 1: Auto-launch and detect elements
clits-inspect --auto --json --action navigate

# Step 2: Click on Settings link
clits-inspect --auto --json --action click --selector "http://localhost:5173/settings"

# Step 3: Collect logs after interaction
clits-inspect --auto --json --action logs --duration 10
```

**2. JSON Output Format:**
```json
{
  "success": true,
  "action": "navigate",
  "timestamp": "2025-06-08T01:41:23.034Z",
  "target": {
    "id": "1223DEB4A446164DEE13C00AA6CCE7E0",
    "title": "Vite + React + TS",
    "url": "http://localhost:5173/displays-manager"
  },
  "logs": [],
  "elements": [
    {
      "name": "🔗 Dashboard",
      "url": "http://localhost:5173/dashboard"
    },
    {
      "name": "🔗 Settings", 
      "url": "http://localhost:5173/settings"
    },
    {
      "name": "🔘 Add New Display",
      "url": "Add New Display"
    }
  ],
  "error": null
}
```

**3. Error Handling:**
```json
{
  "success": false,
  "action": "click",
  "timestamp": "2025-06-08T01:41:23.034Z",
  "error": "Element not found: #non-existent-selector",
  "target": null,
  "logs": [],
  "elements": []
}
```

#### **AI Integration Benefits**

- **🚀 Auto-launch Chrome**: Detects if Chrome is running, launches automatically if needed
- **🎯 Smart Target Selection**: Prioritizes localhost > dev > newest tabs automatically  
- **📊 Structured Output**: JSON format perfect for AI parsing and decision making
- **🔄 Action Chaining**: Navigate → detect elements → click → capture logs in sequence
- **🛡️ Error Handling**: Graceful failures with structured error responses
- **⚡ Zero Latency**: No human prompts or interactions required

#### **Programmatic Usage (Alternative)**

For direct integration in Node.js applications:

```typescript
import { ChromeExtractor } from '@puberty-labs/clits/dist/chrome-extractor';

async function aiDebugWorkflow() {
  const extractor = new ChromeExtractor({
    port: 9222,
    host: 'localhost',
    includeNetwork: true,
    includeConsole: true
  });

  try {
    // 1. Get available targets
    const targets = await extractor.getDebuggablePageTargets();
    const target = targets.find(t => t.url.includes('localhost')) || targets[0];
    
    // 2. Extract logs
    const logs = await extractor.extract(target.id);
    
    return {
      success: true,
      targetUrl: target.url,
      logCount: logs.length,
      logs: logs
    };
  } catch (error) {
    return {
      success: false,
      error: error.message
    };
  }
}
```

CLiTS enables AI assistants to build complete closed-loop debugging workflows:

1. **Launch CLiTS** → 2. **Auto-launch Chrome** → 3. **Navigate pages** → 4. **Detect elements** → 5. **Click/interact** → 6. **Capture logs** → 7. **Interpret results** → 8. **Repeat cycle**

#### **Quick Start for AI Assistants**

**Prerequisites:** 
- Install: `npm install -g @puberty-labs/clits`
- Chrome will be auto-launched if needed

**Basic AI Commands:**
```bash
# Start with element detection (most common)
clits-inspect --auto --json --action navigate

# Click a specific element
clits-inspect --auto --json --action click --selector "Dashboard"

# Collect debugging logs
clits-inspect --auto --json --action logs
```

**Advanced Automation:**
```bash
# Navigate to specific page + detect elements
clits-inspect --auto --json --action navigate --url "http://localhost:3000/admin"

# Extended log collection with smart targeting
clits-inspect --auto --json --action logs --duration 30 --target-priority localhost
```

The automation framework handles Chrome launching, tab selection, and provides structured JSON responses perfect for AI analysis. All commands are designed to work without any human intervention.

#### **NEW: Text & Region-based Automation Actions (v1.0.9-beta.27)**

**Critical Update:** Added missing `click-text` and `click-region` actions to automation framework:

```json
{
  "steps": [
    {"action": "navigate", "url": "http://localhost:5173", "timeout": 10000},
    {"action": "wait", "selector": "body", "timeout": 2000},
    {"action": "click-text", "text": "Dashboard", "wait": 1000, "screenshotPath": "navigation.png"},
    {"action": "click-text", "text": "Settings", "wait": 1000},
    {"action": "click-region", "region": "center", "wait": 500},
    {"action": "screenshot", "path": "final-result.png"}
  ],
  "options": {
    "timeout": 30000,
    "captureNetwork": true,
    "monitor": true
  }
}
```

**Supported Actions:**
- `click-text`: Click elements containing specific text (most reliable for React/MUI apps)
- `click-region`: Click by screen region (`top-left`, `top-right`, `bottom-left`, `bottom-right`, `center`)
- Both support `wait` parameter (recommended: 500-1000ms) and optional `screenshotPath`

**Usage:**
```bash
clits automate --script automation.json --chrome-port 9222 --save-results results.json
```

## Development Integration

CLITS now provides a powerful development integration framework that allows you to embed CLITS directly into your Chrome application development workflow. This integration provides:

- Direct hooks into your application's runtime
- Automatic monitoring of React, Redux, GraphQL, and more
- Built-in error boundary integration
- Performance monitoring
- User interaction recording
- DOM mutation tracking
- CSS change monitoring
- WebSocket monitoring
- JWT token monitoring
- And much more!

### Quick Start

```typescript
import { initializeCLITS } from 'clits';

// Initialize with default settings
initializeCLITS();

// Or with custom configuration
initializeCLITS({
  monitorReact: true,
  monitorRedux: true,
  monitorGraphQL: true,
  // ... other options
});
```

For detailed documentation on development integration, see [DEVELOPMENT_INTEGRATION.md](docs/DEVELOPMENT_INTEGRATION.md). # Test status: Thu Jul 24 16:53:08 PDT 2025
# Test Status: Thu Jul 24 18:14:29 PDT 2025