@willbooster/agent-skills 1.16.0 → 1.17.0

package/skills/playwright-cli/references/storage-state.md

@@ -0,0 +1,275 @@
+# Storage Management
+
+Manage cookies, localStorage, sessionStorage, and browser storage state.
+
+## Storage State
+
+Save and restore complete browser state including cookies and storage.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+bunx @playwright/cli@latest state-save
+
+# Save to specific filename
+bunx @playwright/cli@latest state-save my-auth-state.json
+```
+
+### Restore Storage State
+
+```bash
+# Load storage state from file
+bunx @playwright/cli@latest state-load my-auth-state.json
+
+# Reload page to apply cookies
+bunx @playwright/cli@latest open https://example.com
+```
+
+### Storage State File Format
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1735689600,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" }
+      ]
+    }
+  ]
+}
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+bunx @playwright/cli@latest cookie-list
+```
+
+### Filter Cookies by Domain
+
+```bash
+bunx @playwright/cli@latest cookie-list --domain=example.com
+```
+
+### Filter Cookies by Path
+
+```bash
+bunx @playwright/cli@latest cookie-list --path=/api
+```
+
+### Get Specific Cookie
+
+```bash
+bunx @playwright/cli@latest cookie-get session_id
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+bunx @playwright/cli@latest cookie-set session abc123
+
+# Cookie with options
+bunx @playwright/cli@latest cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+bunx @playwright/cli@latest cookie-set remember_me token123 --expires=1735689600
+```
+
+### Delete a Cookie
+
+```bash
+bunx @playwright/cli@latest cookie-delete session_id
+```
+
+### Clear All Cookies
+
+```bash
+bunx @playwright/cli@latest cookie-clear
+```
+
+### Advanced: Multiple Cookies or Custom Options
+
+For complex scenarios like adding multiple cookies at once, use `run-code`:
+
+```bash
+bunx @playwright/cli@latest run-code "async page => {
+  await page.context().addCookies([
+    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
+    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
+  ]);
+}"
+```
+
+## Local Storage
+
+### List All localStorage Items
+
+```bash
+bunx @playwright/cli@latest localstorage-list
+```
+
+### Get Single Value
+
+```bash
+bunx @playwright/cli@latest localstorage-get token
+```
+
+### Set Value
+
+```bash
+bunx @playwright/cli@latest localstorage-set theme dark
+```
+
+### Set JSON Value
+
+```bash
+bunx @playwright/cli@latest localstorage-set user_settings '{"theme":"dark","language":"en"}'
+```
+
+### Delete Single Item
+
+```bash
+bunx @playwright/cli@latest localstorage-delete token
+```
+
+### Clear All localStorage
+
+```bash
+bunx @playwright/cli@latest localstorage-clear
+```
+
+### Advanced: Multiple Operations
+
+For complex scenarios like setting multiple values at once, use `run-code`:
+
+```bash
+bunx @playwright/cli@latest run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('expires_at', Date.now() + 3600000);
+  });
+}"
+```
+
+## Session Storage
+
+### List All sessionStorage Items
+
+```bash
+bunx @playwright/cli@latest sessionstorage-list
+```
+
+### Get Single Value
+
+```bash
+bunx @playwright/cli@latest sessionstorage-get form_data
+```
+
+### Set Value
+
+```bash
+bunx @playwright/cli@latest sessionstorage-set step 3
+```
+
+### Delete Single Item
+
+```bash
+bunx @playwright/cli@latest sessionstorage-delete step
+```
+
+### Clear sessionStorage
+
+```bash
+bunx @playwright/cli@latest sessionstorage-clear
+```
+
+## IndexedDB
+
+### List Databases
+
+```bash
+bunx @playwright/cli@latest run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases;
+  });
+}"
+```
+
+### Delete Database
+
+```bash
+bunx @playwright/cli@latest run-code "async page => {
+  await page.evaluate(() => {
+    indexedDB.deleteDatabase('myDatabase');
+  });
+}"
+```
+
+## Common Patterns
+
+### Authentication State Reuse
+
+```bash
+# Step 1: Login and save state
+bunx @playwright/cli@latest open https://app.example.com/login
+bunx @playwright/cli@latest snapshot
+bunx @playwright/cli@latest fill e1 "user@example.com"
+bunx @playwright/cli@latest fill e2 "password123"
+bunx @playwright/cli@latest click e3
+
+# Save the authenticated state
+bunx @playwright/cli@latest state-save auth.json
+
+# Step 2: Later, restore state and skip login
+bunx @playwright/cli@latest state-load auth.json
+bunx @playwright/cli@latest open https://app.example.com/dashboard
+# Already logged in!
+```
+
+### Save and Restore Roundtrip
+
+```bash
+# Set up authentication state
+bunx @playwright/cli@latest open https://example.com
+bunx @playwright/cli@latest eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
+
+# Save state to file
+bunx @playwright/cli@latest state-save my-session.json
+
+# ... later, in a new session ...
+
+# Restore state
+bunx @playwright/cli@latest state-load my-session.json
+bunx @playwright/cli@latest open https://example.com
+# Cookies and localStorage are restored!
+```
+
+## Security Notes
+
+- Never commit storage state files containing auth tokens
+- Add `*.auth-state.json` to `.gitignore`
+- Delete state files after automation completes
+- Use environment variables for sensitive data
+- By default, sessions run in-memory mode which is safer for sensitive operations

package/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,88 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+bunx @playwright/cli@latest open https://example.com/login
+
+# Take a snapshot to see elements
+bunx @playwright/cli@latest snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+bunx @playwright/cli@latest fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+bunx @playwright/cli@latest fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+bunx @playwright/cli@latest click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+bunx @playwright/cli@latest open https://example.com
+bunx @playwright/cli@latest snapshot
+# Review the element structure
+bunx @playwright/cli@latest click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test:
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertion
+await expect(page.getByText('Success')).toBeVisible();
+```

package/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,142 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+bunx @playwright/cli@latest tracing-start
+
+# Perform actions
+bunx @playwright/cli@latest open https://example.com
+bunx @playwright/cli@latest click e1
+bunx @playwright/cli@latest fill e2 "test"
+
+# Stop trace recording
+bunx @playwright/cli@latest tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category        | Details                                            |
+| --------------- | -------------------------------------------------- |
+| **Actions**     | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM**         | Full DOM snapshot before/after each action         |
+| **Screenshots** | Visual state at each step                          |
+| **Network**     | All requests, responses, headers, bodies, timing   |
+| **Console**     | All console.log, warn, error messages              |
+| **Timing**      | Precise timing for each operation                  |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+bunx @playwright/cli@latest tracing-start
+bunx @playwright/cli@latest open https://app.example.com
+
+# This click fails - why?
+bunx @playwright/cli@latest click e5
+
+bunx @playwright/cli@latest tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+bunx @playwright/cli@latest tracing-start
+bunx @playwright/cli@latest open https://slow-site.com
+bunx @playwright/cli@latest tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+bunx @playwright/cli@latest tracing-start
+
+bunx @playwright/cli@latest open https://app.example.com/checkout
+bunx @playwright/cli@latest fill e1 "4111111111111111"
+bunx @playwright/cli@latest fill e2 "12/25"
+bunx @playwright/cli@latest fill e3 "123"
+bunx @playwright/cli@latest click e4
+
+bunx @playwright/cli@latest tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature                 | Trace       | Video       | Screenshot       |
+| ----------------------- | ----------- | ----------- | ---------------- |
+| **Format**              | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection**      | Yes         | No          | No               |
+| **Network details**     | Yes         | No          | No               |
+| **Step-by-step replay** | Yes         | Continuous  | Single frame     |
+| **File size**           | Medium      | Large       | Small            |
+| **Best for**            | Debugging   | Demos       | Quick capture    |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+bunx @playwright/cli@latest tracing-start
+bunx @playwright/cli@latest open https://example.com
+# ... all steps leading to the issue ...
+bunx @playwright/cli@latest tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,146 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+bunx @playwright/cli@latest open
+
+# Start recording
+bunx @playwright/cli@latest video-start demo.webm
+
+# Add a chapter marker for section transitions
+bunx @playwright/cli@latest video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+bunx @playwright/cli@latest goto https://example.com
+bunx @playwright/cli@latest snapshot
+bunx @playwright/cli@latest click e1
+
+# Add another chapter
+bunx @playwright/cli@latest video-chapter "Filling Form" --description="Entering test data" --duration=2000
+bunx @playwright/cli@latest fill e2 "test input"
+
+# Stop and save
+bunx @playwright/cli@latest video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+bunx @playwright/cli@latest video-start recordings/login-flow-2024-01-15.webm
+bunx @playwright/cli@latest video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1. Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request thier bounding boxes for highlight.
+2. Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3. Use playwright-cli run-code --file your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async (page) => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(
+    `
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `,
+    { duration: 2000 }
+  );
+
+  await page.screencast.stop();
+};
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method                                                                         | Use Case                                                                       |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })`                             | Custom HTML overlay — use for callouts, labels, highlights                     |
+| `disposable.dispose()`                                                         | Remove a sticky overlay added without duration                                 |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()`            | Temporarily hide/show all overlays                                             |
+
+## Tracing vs Video
+
+| Feature  | Video                | Tracing                                  |
+| -------- | -------------------- | ---------------------------------------- |
+| Output   | WebM file            | Trace file (viewable in Trace Viewer)    |
+| Shows    | Visual recording     | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis                      |
+| Size     | Larger               | Smaller                                  |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/skills/refactor-structure/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: refactor-structure
+description: Refactor the source tree by splitting oversized files, grouping related code, and reorganizing directories without changing intended behavior.
+---
+
+# Structure refactor workflow
+
+1. Inspect the current layout with `tree -h src` (or `tree -h <specified_dir>`) and read the main entry points and largest nearby files.
+2. Reorganize by responsibility to improve cohesion and reduce coupling: split oversized files, group related modules, and add directories only when they make ownership clearer.
+3. Update imports as you go and preserve existing behavior unless broader changes are explicitly requested.
+4. Run the lightest relevant verification, such as typecheck or lint, to catch broken imports or module wiring.
+5. Summarize what moved and why the new structure is easier to maintain.

package/skills/review-all/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: review-all
+description: Run Codex, Claude Code, and Gemini CLI reviews against the current branch concurrently, deduplicate the findings, and report only the review comments that are still valid for the current codebase.
+allowed-tools: Bash(bunx:*), Task
+---
+
+# Review workflow
+
+1. Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest review --agent all`
+2. Treat the combined output as a set of candidate comments returned by Codex, Claude Code, and Gemini CLI running concurrently.
+3. Merge the returned review results into a single candidate comment set, deduplicating comments that point to the same underlying issue.
+4. Judge whether each candidate comment is still valid in the current codebase.
+5. Report only the comments you judged valid. If none remain, respond with exactly: `There is no concern.`

package/skills/review-claude/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: review-claude
+description: Run Claude Code review against the current branch and report only the review comments that are still valid for the current codebase, without applying fixes.
+allowed-tools: Bash(bunx:*)
+---
+
+# Review workflow
+
+1. Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest review --agent claude`
+2. Report on the review results.

package/skills/review-codex/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: review-codex
+description: Run Codex code review against the current branch and report only the review comments that are still valid for the current codebase, without applying fixes.
+allowed-tools: Bash(bunx:*)
+---
+
+# Review workflow
+
+1. Run the following command with a 1-hour timeout (DO NOT STOP THE COMMAND BEFORE 1 HOUR ELAPSES): `bunx @willbooster/agent-skills@latest review --agent codex`
+2. Report on the review results.