@mthanh/vespercli 1.8.0 → 2.0.0

package/assets/copilot/packs/playwright/skills/chrome-devtools/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: chrome-devtools
+description: Browser automation, debugging, and performance analysis using Puppeteer CLI scripts. Use for automating browsers, taking screenshots, analyzing performance, monitoring network traffic, web scraping, form automation, and JavaScript debugging.
+license: Apache-2.0
+---
+
+# Chrome DevTools Agent Skill
+
+Browser automation via executable Puppeteer scripts. All scripts output JSON for easy parsing.
+
+## Quick Start
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+### Installation
+
+#### Step 1: Install System Dependencies (Linux/WSL only)
+
+On Linux/WSL, Chrome requires system libraries. Install them first:
+
+```bash
+pwd  # Should show current working directory
+cd .vesper/skills/chrome-devtools/scripts
+./install-deps.sh  # Auto-detects OS and installs required libs
+```
+
+Supports: Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro
+
+**macOS/Windows**: Skip this step (dependencies bundled with Chrome)
+
+#### Step 2: Install Node Dependencies
+
+```bash
+npm install  # Installs puppeteer, debug, yargs
+```
+
+#### Step 3: Install ImageMagick (Optional, Recommended)
+
+ImageMagick enables automatic screenshot compression to keep files under 5MB:
+
+**macOS:**
+```bash
+brew install imagemagick
+```
+
+**Ubuntu/Debian/WSL:**
+```bash
+sudo apt-get install imagemagick
+```
+
+**Verify:**
+```bash
+magick -version  # or: convert -version
+```
+
+Without ImageMagick, screenshots >5MB will not be compressed (may fail to load in Gemini/Claude).
+
+### Test
+```bash
+node navigate.js --url https://example.com
+# Output: {"success": true, "url": "https://example.com", "title": "Example Domain"}
+```
+
+## Available Scripts
+
+All scripts are in `.vesper/skills/chrome-devtools/scripts/`
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+### Script Usage
+- `./scripts/README.md`
+
+### Core Automation
+- `navigate.js` - Navigate to URLs
+- `screenshot.js` - Capture screenshots (full page or element)
+- `click.js` - Click elements
+- `fill.js` - Fill form fields
+- `evaluate.js` - Execute JavaScript in page context
+
+### Analysis & Monitoring
+- `snapshot.js` - Extract interactive elements with metadata
+- `console.js` - Monitor console messages/errors
+- `network.js` - Track HTTP requests/responses
+- `performance.js` - Measure Core Web Vitals + record traces
+
+## Usage Patterns
+
+### Single Command
+```bash
+pwd  # Should show current working directory
+cd .vesper/skills/chrome-devtools/scripts
+node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
+```
+**Important**: Always save screenshots to `./docs/screenshots` directory.
+
+### Automatic Image Compression
+Screenshots are **automatically compressed** if they exceed 5MB to ensure compatibility with Gemini API and Claude Code (which have 5MB limits). This uses ImageMagick internally:
+
+```bash
+# Default: auto-compress if >5MB
+node screenshot.js --url https://example.com --output page.png
+
+# Custom size threshold (e.g., 3MB)
+node screenshot.js --url https://example.com --output page.png --max-size 3
+
+# Disable compression
+node screenshot.js --url https://example.com --output page.png --no-compress
+```
+
+**Compression behavior:**
+- PNG: Resizes to 90% + quality 85 (or 75% + quality 70 if still too large)
+- JPEG: Quality 80 + progressive encoding (or quality 60 if still too large)
+- Other formats: Converted to JPEG with compression
+- Requires ImageMagick installed (see imagemagick skill)
+
+**Output includes compression info:**
+```json
+{
+  "success": true,
+  "output": "/path/to/page.png",
+  "compressed": true,
+  "originalSize": 8388608,
+  "size": 3145728,
+  "compressionRatio": "62.50%",
+  "url": "https://example.com"
+}
+```
+
+### Chain Commands (reuse browser)
+```bash
+# Keep browser open with --close false
+node navigate.js --url https://example.com/login --close false
+node fill.js --selector "#email" --value "user@example.com" --close false
+node fill.js --selector "#password" --value "secret" --close false
+node click.js --selector "button[type=submit]"
+```
+
+### Parse JSON Output
+```bash
+# Extract specific fields with jq
+node performance.js --url https://example.com | jq '.vitals.LCP'
+
+# Save to file
+node network.js --url https://example.com --output /tmp/requests.json
+```
+
+## Execution Protocol
+
+### Working Directory Verification
+
+BEFORE executing any script:
+1. Check current working directory with `pwd`
+2. Verify in `.vesper/skills/chrome-devtools/scripts/` directory
+3. If wrong directory, `cd` to correct location
+4. Use absolute paths for all output files
+
+Example:
+```bash
+pwd  # Should show: .../chrome-devtools/scripts
+# If wrong:
+cd .vesper/skills/chrome-devtools/scripts
+```
+
+### Output Validation
+
+AFTER screenshot/capture operations:
+1. Verify file created with `ls -lh <output-path>`
+2. Read screenshot using Read tool to confirm content
+3. Check JSON output for success:true
+4. Report file size and compression status
+
+Example:
+```bash
+node screenshot.js --url https://example.com --output ./docs/screenshots/page.png
+ls -lh ./docs/screenshots/page.png  # Verify file exists
+# Then use Read tool to visually inspect
+```
+
+5. Restart working directory to the project root.
+
+### Error Recovery
+
+If script fails:
+1. Check error message for selector issues
+2. Use snapshot.js to discover correct selectors
+3. Try XPath selector if CSS selector fails
+4. Verify element is visible and interactive
+
+Example:
+```bash
+# CSS selector fails
+node click.js --url https://example.com --selector ".btn-submit"
+# Error: waiting for selector ".btn-submit" failed
+
+# Discover correct selector
+node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'
+
+# Try XPath
+node click.js --url https://example.com --selector "//button[contains(text(),'Submit')]"
+```
+
+### Common Mistakes
+
+❌ Wrong working directory → output files go to wrong location
+❌ Skipping output validation → silent failures
+❌ Using complex CSS selectors without testing → selector errors
+❌ Not checking element visibility → timeout errors
+
+✅ Always verify `pwd` before running scripts
+✅ Always validate output after screenshots
+✅ Use snapshot.js to discover selectors
+✅ Test selectors with simple commands first
+
+## Common Workflows
+
+### Web Scraping
+```bash
+node evaluate.js --url https://example.com --script "
+  Array.from(document.querySelectorAll('.item')).map(el => ({
+    title: el.querySelector('h2')?.textContent,
+    link: el.querySelector('a')?.href
+  }))
+" | jq '.result'
+```
+
+### Performance Testing
+```bash
+PERF=$(node performance.js --url https://example.com)
+LCP=$(echo $PERF | jq '.vitals.LCP')
+if (( $(echo "$LCP < 2500" | bc -l) )); then
+  echo "✓ LCP passed: ${LCP}ms"
+else
+  echo "✗ LCP failed: ${LCP}ms"
+fi
+```
+
+### Form Automation
+```bash
+node fill.js --url https://example.com --selector "#search" --value "query" --close false
+node click.js --selector "button[type=submit]"
+```
+
+### Error Monitoring
+```bash
+node console.js --url https://example.com --types error,warn --duration 5000 | jq '.messageCount'
+```
+
+## Script Options
+
+All scripts support:
+- `--headless false` - Show browser window
+- `--close false` - Keep browser open for chaining
+- `--timeout 30000` - Set timeout (milliseconds)
+- `--wait-until networkidle2` - Wait strategy
+
+See `./scripts/README.md` for complete options.
+
+## Output Format
+
+All scripts output JSON to stdout:
+```json
+{
+  "success": true,
+  "url": "https://example.com",
+  ... // script-specific data
+}
+```
+
+Errors go to stderr:
+```json
+{
+  "success": false,
+  "error": "Error message"
+}
+```
+
+## Finding Elements
+
+Use `snapshot.js` to discover selectors:
+```bash
+node snapshot.js --url https://example.com | jq '.elements[] | {tagName, text, selector}'
+```
+
+## Troubleshooting
+
+### Common Errors
+
+**"Cannot find package 'puppeteer'"**
+- Run: `npm install` in the scripts directory
+
+**"error while loading shared libraries: libnss3.so"** (Linux/WSL)
+- Missing system dependencies
+- Fix: Run `./install-deps.sh` in scripts directory
+- Manual install: `sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1`
+
+**"Failed to launch the browser process"**
+- Check system dependencies installed (Linux/WSL)
+- Verify Chrome downloaded: `ls ~/.cache/puppeteer`
+- Try: `npm rebuild` then `npm install`
+
+**Chrome not found**
+- Puppeteer auto-downloads Chrome during `npm install`
+- If failed, manually trigger: `npx puppeteer browsers install chrome`
+
+### Script Issues
+
+**Element not found**
+- Get snapshot first to find correct selector: `node snapshot.js --url <url>`
+
+**Script hangs**
+- Increase timeout: `--timeout 60000`
+- Change wait strategy: `--wait-until load` or `--wait-until domcontentloaded`
+
+**Blank screenshot**
+- Wait for page load: `--wait-until networkidle2`
+- Increase timeout: `--timeout 30000`
+
+**Permission denied on scripts**
+- Make executable: `chmod +x *.sh`
+
+**Screenshot too large (>5MB)**
+- Install ImageMagick for automatic compression
+- Manually set lower threshold: `--max-size 3`
+- Use JPEG format instead of PNG: `--format jpeg --quality 80`
+- Capture specific element instead of full page: `--selector .main-content`
+
+**Compression not working**
+- Verify ImageMagick installed: `magick -version` or `convert -version`
+- Check file was actually compressed in output JSON: `"compressed": true`
+- For very large pages, use `--selector` to capture only needed area
+
+## Reference Documentation
+
+Detailed guides available in `./references/`:
+- [CDP Domains Reference](./references/cdp-domains.md) - 47 Chrome DevTools Protocol domains
+- [Puppeteer Quick Reference](./references/puppeteer-reference.md) - Complete Puppeteer API patterns
+- [Performance Analysis Guide](./references/performance-guide.md) - Core Web Vitals optimization
+
+## Advanced Usage
+
+### Custom Scripts
+Create custom scripts using shared library:
+```javascript
+import { getBrowser, getPage, closeBrowser, outputJSON } from './lib/browser.js';
+// Your automation logic
+```
+
+### Direct CDP Access
+```javascript
+const client = await page.createCDPSession();
+await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });
+```
+
+See reference documentation for advanced patterns and complete API coverage.
+
+## External Resources
+
+- [Puppeteer Documentation](https://pptr.dev/)
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
+- [Scripts README](./scripts/README.md)

package/assets/copilot/packs/playwright/skills/chrome-devtools/scripts/README.md

@@ -0,0 +1,213 @@
+# Chrome DevTools Scripts
+
+CLI scripts for browser automation using Puppeteer.
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+## Installation
+
+### Quick Install
+
+```bash
+pwd  # Should show current working directory
+cd .vesper/skills/chrome-devtools/scripts
+./install.sh  # Auto-checks dependencies and installs
+```
+
+### Manual Installation
+
+**Linux/WSL** - Install system dependencies first:
+```bash
+./install-deps.sh  # Auto-detects OS (Ubuntu, Debian, Fedora, etc.)
+```
+
+Or manually:
+```bash
+sudo apt-get install -y libnss3 libnspr4 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1
+```
+
+**All platforms** - Install Node dependencies:
+```bash
+npm install
+```
+
+## Scripts
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+### navigate.js
+Navigate to a URL.
+
+```bash
+node navigate.js --url https://example.com [--wait-until networkidle2] [--timeout 30000]
+```
+
+### screenshot.js
+Take a screenshot with automatic compression.
+
+**Important**: Always save screenshots to `./docs/screenshots` directory.
+
+```bash
+node screenshot.js --output screenshot.png [--url https://example.com] [--full-page true] [--selector .element] [--max-size 5] [--no-compress]
+```
+
+**Automatic Compression**: Screenshots >5MB are automatically compressed using ImageMagick to ensure compatibility with Gemini API and Claude Code. Install ImageMagick for this feature:
+- macOS: `brew install imagemagick`
+- Linux: `sudo apt-get install imagemagick`
+
+Options:
+- `--max-size N` - Custom size threshold in MB (default: 5)
+- `--no-compress` - Disable automatic compression
+- `--format png|jpeg` - Output format (default: png)
+- `--quality N` - JPEG quality 0-100 (default: auto)
+
+### click.js
+Click an element.
+
+```bash
+node click.js --selector ".button" [--url https://example.com] [--wait-for ".result"]
+```
+
+### fill.js
+Fill form fields.
+
+```bash
+node fill.js --selector "#input" --value "text" [--url https://example.com] [--clear true]
+```
+
+### evaluate.js
+Execute JavaScript in page context.
+
+```bash
+node evaluate.js --script "document.title" [--url https://example.com]
+```
+
+### snapshot.js
+Get DOM snapshot with interactive elements.
+
+```bash
+node snapshot.js [--url https://example.com] [--output snapshot.json]
+```
+
+### console.js
+Monitor console messages.
+
+```bash
+node console.js --url https://example.com [--types error,warn] [--duration 5000]
+```
+
+### network.js
+Monitor network requests.
+
+```bash
+node network.js --url https://example.com [--types xhr,fetch] [--output requests.json]
+```
+
+### performance.js
+Measure performance metrics and record trace.
+
+```bash
+node performance.js --url https://example.com [--trace trace.json] [--metrics] [--resources true]
+```
+
+## Common Options
+
+- `--headless false` - Show browser window
+- `--close false` - Keep browser open
+- `--timeout 30000` - Set timeout in milliseconds
+- `--wait-until networkidle2` - Wait strategy (load, domcontentloaded, networkidle0, networkidle2)
+
+## Selector Support
+
+Scripts that accept `--selector` (click.js, fill.js, screenshot.js) support both **CSS** and **XPath** selectors.
+
+### CSS Selectors (Default)
+
+```bash
+# Element tag
+node click.js --selector "button" --url https://example.com
+
+# Class selector
+node click.js --selector ".btn-submit" --url https://example.com
+
+# ID selector
+node fill.js --selector "#email" --value "user@example.com" --url https://example.com
+
+# Attribute selector
+node click.js --selector 'button[type="submit"]' --url https://example.com
+
+# Complex selector
+node screenshot.js --selector "div.container > button.btn-primary" --output btn.png
+```
+
+### XPath Selectors
+
+XPath selectors start with `/` or `(//` and are automatically detected:
+
+```bash
+# Text matching - exact
+node click.js --selector '//button[text()="Submit"]' --url https://example.com
+
+# Text matching - contains
+node click.js --selector '//button[contains(text(),"Submit")]' --url https://example.com
+
+# Attribute matching
+node fill.js --selector '//input[@type="email"]' --value "user@example.com"
+
+# Multiple conditions
+node click.js --selector '//button[@type="submit" and contains(text(),"Save")]'
+
+# Descendant selection
+node screenshot.js --selector '//div[@class="modal"]//button[@class="close"]' --output modal.png
+
+# Nth element
+node click.js --selector '(//button)[2]'  # Second button on page
+```
+
+### Discovering Selectors
+
+Use `snapshot.js` to discover correct selectors:
+
+```bash
+# Get all interactive elements
+node snapshot.js --url https://example.com | jq '.elements[]'
+
+# Find buttons
+node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="BUTTON")'
+
+# Find inputs
+node snapshot.js --url https://example.com | jq '.elements[] | select(.tagName=="INPUT")'
+```
+
+### Security
+
+XPath selectors are validated to prevent injection attacks. The following patterns are blocked:
+- `javascript:`
+- `<script`
+- `onerror=`, `onload=`, `onclick=`
+- `eval(`, `Function(`, `constructor(`
+
+Selectors exceeding 1000 characters are rejected (DoS prevention).
+
+## Output Format
+
+All scripts output JSON to stdout:
+
+```json
+{
+  "success": true,
+  "url": "https://example.com",
+  "title": "Example Domain",
+  ...
+}
+```
+
+Errors are output to stderr:
+
+```json
+{
+  "success": false,
+  "error": "Error message",
+  "stack": "..."
+}
+```

package/assets/copilot/packs/playwright/skills/playwright-generate-test/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: playwright-generate-test
+description: Generate a Playwright end-to-end test for a given scenario by analyzing source code (not by exploring a live browser). Use when asked to write, generate, or scaffold a Playwright test, an e2e test, or a browser test for a page, component, or user flow. Uses the codebase index to locate the relevant source, derives accessible locators (getByRole/getByTestId/getByText) and expected behaviors from the actual component source, writes a TypeScript `@playwright/test` file under `tests/`, and iterates until it passes.
+---
+
+# Playwright Test Generation from Source
+
+Generate a Playwright test based on a provided scenario by analyzing source code.
+
+## Instructions
+
+1. If no scenario is provided, ask the user for one.
+2. Use the `vesper-indexing` MCP tools (`vesper_search`, `vesper_symbols`) to find the relevant component/page source files.
+3. Read the source — identify routes, `data-testid` attributes, interactive elements, and expected behaviors.
+4. Generate a TypeScript test using `@playwright/test` with proper locators derived from the source.
+5. Save the test file in the `tests/` directory.
+6. Run it with `npx playwright test <file> --reporter=list`.
+7. If the test fails, read the error, fix it, and re-run until green.
+
+## Constraints
+
+- DO NOT explore the website with a browser — generate from source code.
+- DO verify locators exist in the actual component source before using them.
+- DO use `getByRole`, `getByTestId`, `getByText` — prefer accessible locators.
+- DO run the test and iterate until it passes.

package/assets/copilot/packs/playwright/skills/playwright-typescript/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: playwright-typescript
+description: Playwright test generation instructions
+---
+
+## Test Writing Guidelines
+
+### Code Quality Standards
+- **Locators**: Prioritize user-facing, role-based locators (`getByRole`, `getByLabel`, `getByText`, etc.) for resilience and accessibility. Use `test.step()` to group interactions and improve test readability and reporting.
+- **Assertions**: Use auto-retrying web-first assertions. These assertions start with the `await` keyword (e.g., `await expect(locator).toHaveText()`). Avoid `expect(locator).toBeVisible()` unless specifically testing for visibility changes.
+- **Timeouts**: Rely on Playwright's built-in auto-waiting mechanisms. Avoid hard-coded waits or increased default timeouts.
+- **Clarity**: Use descriptive test and step titles that clearly state the intent. Add comments only to explain complex logic or non-obvious interactions.
+
+
+### Test Structure
+- **Imports**: Start with `import { test, expect } from '@playwright/test';`.
+- **Organization**: Group related tests for a feature under a `test.describe()` block.
+- **Hooks**: Use `beforeEach` for setup actions common to all tests in a `describe` block (e.g., navigating to a page).
+- **Titles**: Follow a clear naming convention, such as `Feature - Specific action or scenario`.
+
+
+### File Organization
+- **Location**: Store all test files in the `tests/` directory.
+- **Naming**: Use the convention `<feature-or-page>.spec.ts` (e.g., `login.spec.ts`, `search.spec.ts`).
+- **Scope**: Aim for one test file per major application feature or page.
+
+### Assertion Best Practices
+- **UI Structure**: Use `toMatchAriaSnapshot` to verify the accessibility tree structure of a component. This provides a comprehensive and accessible snapshot.
+- **Element Counts**: Use `toHaveCount` to assert the number of elements found by a locator.
+- **Text Content**: Use `toHaveText` for exact text matches and `toContainText` for partial matches.
+- **Navigation**: Use `toHaveURL` to verify the page URL after an action.
+
+
+## Example Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Movie Search Feature', () => {
+  test.beforeEach(async ({ page }) => {
+    // Navigate to the application before each test
+    await page.goto('https://debs-obrien.github.io/playwright-movies-app');
+  });
+
+  test('Search for a movie by title', async ({ page }) => {
+    await test.step('Activate and perform search', async () => {
+      await page.getByRole('search').click();
+      const searchInput = page.getByRole('textbox', { name: 'Search Input' });
+      await searchInput.fill('Garfield');
+      await searchInput.press('Enter');
+    });
+
+    await test.step('Verify search results', async () => {
+      // Verify the accessibility tree of the search results
+      await expect(page.getByRole('main')).toMatchAriaSnapshot(`
+        - main:
+          - heading "Garfield" [level=1]
+          - heading "search results" [level=2]
+          - list "movies":
+            - listitem "movie":
+              - link "poster of The Garfield Movie The Garfield Movie rating":
+                - /url: /playwright-movies-app/movie?id=tt5779228&page=1
+                - img "poster of The Garfield Movie"
+                - heading "The Garfield Movie" [level=2]
+      `);
+    });
+  });
+});
+```
+
+## Test Execution Strategy
+
+1. **Initial Run**: Execute tests with `npx playwright test --project=chromium`
+2. **Debug Failures**: Analyze test failures and identify root causes
+3. **Iterate**: Refine locators, assertions, or test logic as needed
+4. **Validate**: Ensure tests pass consistently and cover the intended functionality
+5. **Report**: Provide feedback on test results and any issues discovered
+
+## Quality Checklist
+
+Before finalizing tests, ensure:
+- [ ] All locators are accessible and specific and avoid strict mode violations
+- [ ] Tests are grouped logically and follow a clear structure
+- [ ] Assertions are meaningful and reflect user expectations
+- [ ] Tests follow consistent naming conventions
+- [ ] Code is properly formatted and commented