@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/chrome-devtools/scripts/README.md

@@ -0,0 +1,288 @@
+# Chrome DevTools Scripts
+
+CLI scripts for browser automation using Puppeteer.
+
+**CRITICAL**: Always check `pwd` before running scripts.
+
+## Installation
+
+## Skill Location
+
+Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
+
+```bash
+# Detect skill location
+SKILL_DIR=""
+if [ -d ".claude/skills/chrome-devtools/scripts" ]; then
+  SKILL_DIR=".claude/skills/chrome-devtools/scripts"
+elif [ -d "$HOME/.claude/skills/chrome-devtools/scripts" ]; then
+  SKILL_DIR="$HOME/.claude/skills/chrome-devtools/scripts"
+fi
+cd "$SKILL_DIR"
+```
+
+### Quick Install
+
+```bash
+cd .claude/skills/chrome-devtools/scripts && npm install
+```
+
+### 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.
+
+### inject-auth.js
+Inject authentication (cookies, tokens, storage) for testing protected routes.
+
+**Workflow for testing protected routes:**
+1. User manually logs into the site in their browser
+2. User extracts cookies/tokens from browser DevTools (Application tab)
+3. Run inject-auth.js to inject auth into puppeteer session
+4. Run other scripts which will use the authenticated session
+
+```bash
+# Inject cookies
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc123","domain":".example.com"}]'
+
+# Inject Bearer token (stores in localStorage + sets HTTP header)
+node inject-auth.js --url https://example.com --token "Bearer eyJhbGciOi..." --header Authorization
+
+# Inject localStorage items
+node inject-auth.js --url https://example.com --local-storage '{"auth_token":"xyz","user_id":"123"}'
+
+# Inject sessionStorage items
+node inject-auth.js --url https://example.com --session-storage '{"temp_key":"value"}'
+
+# Combined injection
+node inject-auth.js --url https://example.com \
+  --cookies '[{"name":"session","value":"abc"}]' \
+  --local-storage '{"user":"data"}' \
+  --reload true
+
+# Clear saved auth session
+node inject-auth.js --url https://example.com --cookies '[]' --clear true
+```
+
+Options:
+- `--cookies '<json>'` - JSON array of cookie objects (name, value, domain required)
+- `--token '<token>'` - Bearer token to inject
+- `--token-key '<key>'` - localStorage key for token (default: access_token)
+- `--header '<name>'` - HTTP header name for token (e.g., Authorization)
+- `--local-storage '<json>'` - JSON object of localStorage key-value pairs
+- `--session-storage '<json>'` - JSON object of sessionStorage key-value pairs
+- `--reload true` - Reload page after injection to apply auth
+- `--clear true` - Clear the saved auth session file
+
+**Session persistence:** Auth is saved to `.auth-session.json` (valid 24h) and automatically applied by subsequent script runs until `--clear true` is used or browser closes.
+
+### 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]
+```
+
+### ws-debug.js
+Debug WebSocket connections (basic mode).
+
+```bash
+node ws-debug.js
+```
+
+Monitors WebSocket events via CDP: created, handshake, response, closed, error.
+
+### ws-full-debug.js
+Debug WebSocket connections with full event tracking.
+
+```bash
+node ws-full-debug.js
+```
+
+Monitors all WebSocket events including frame sent/received, with detailed logging.
+
+## 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/templates/claude/skills/chrome-devtools/scripts/aria-snapshot.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+/**
+ * Get ARIA-based accessibility snapshot with stable element refs
+ * Usage: node aria-snapshot.js [--url https://example.com] [--output snapshot.yaml]
+ *
+ * Returns YAML-formatted accessibility tree with:
+ * - Semantic roles (button, link, textbox, heading, etc.)
+ * - Accessible names (what screen readers announce)
+ * - Element states (checked, disabled, expanded)
+ * - Stable refs [ref=eN] that persist for interaction
+ *
+ * Session behavior:
+ *   By default, browser stays running for session persistence
+ *   Use --close true to fully close browser
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get ARIA snapshot script to inject into page
+ * Builds YAML-formatted accessibility tree with element references
+ */
+function getAriaSnapshotScript() {
+  return `
+(function() {
+  // Store refs on window for later retrieval via selectRef
+  window.__chromeDevToolsRefs = window.__chromeDevToolsRefs || new Map();
+  let refCounter = window.__chromeDevToolsRefCounter || 1;
+
+  // ARIA roles we care about for interaction
+  const INTERACTIVE_ROLES = new Set([
+    'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
+    'listbox', 'option', 'menuitem', 'menuitemcheckbox', 'menuitemradio',
+    'tab', 'switch', 'slider', 'spinbutton', 'searchbox', 'tree', 'treeitem',
+    'grid', 'gridcell', 'row', 'rowheader', 'columnheader'
+  ]);
+
+  // Landmark roles for structure
+  const LANDMARK_ROLES = new Set([
+    'banner', 'navigation', 'main', 'complementary', 'contentinfo',
+    'search', 'form', 'region', 'article', 'dialog', 'alertdialog'
+  ]);
+
+  // Implicit ARIA roles from HTML elements
+  const IMPLICIT_ROLES = {
+    'A': (el) => el.href ? 'link' : null,
+    'BUTTON': () => 'button',
+    'INPUT': (el) => {
+      const type = el.type?.toLowerCase();
+      if (type === 'checkbox') return 'checkbox';
+      if (type === 'radio') return 'radio';
+      if (type === 'submit' || type === 'button' || type === 'reset') return 'button';
+      if (type === 'search') return 'searchbox';
+      if (type === 'range') return 'slider';
+      if (type === 'number') return 'spinbutton';
+      return 'textbox';
+    },
+    'TEXTAREA': () => 'textbox',
+    'SELECT': () => 'combobox',
+    'OPTION': () => 'option',
+    'IMG': () => 'img',
+    'NAV': () => 'navigation',
+    'MAIN': () => 'main',
+    'HEADER': () => 'banner',
+    'FOOTER': () => 'contentinfo',
+    'ASIDE': () => 'complementary',
+    'ARTICLE': () => 'article',
+    'SECTION': (el) => el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') ? 'region' : null,
+    'FORM': () => 'form',
+    'UL': () => 'list',
+    'OL': () => 'list',
+    'LI': () => 'listitem',
+    'H1': () => 'heading',
+    'H2': () => 'heading',
+    'H3': () => 'heading',
+    'H4': () => 'heading',
+    'H5': () => 'heading',
+    'H6': () => 'heading',
+    'TABLE': () => 'table',
+    'TR': () => 'row',
+    'TH': () => 'columnheader',
+    'TD': () => 'cell',
+    'DIALOG': () => 'dialog'
+  };
+
+  function getRole(el) {
+    // Explicit role takes precedence
+    const explicitRole = el.getAttribute('role');
+    if (explicitRole) return explicitRole;
+
+    // Check implicit role
+    const implicitFn = IMPLICIT_ROLES[el.tagName];
+    if (implicitFn) return implicitFn(el);
+
+    return null;
+  }
+
+  function getAccessibleName(el) {
+    // aria-label takes precedence
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel) return ariaLabel.trim();
+
+    // aria-labelledby
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const labels = labelledBy.split(' ')
+        .map(id => document.getElementById(id)?.textContent?.trim())
+        .filter(Boolean)
+        .join(' ');
+      if (labels) return labels;
+    }
+
+    // Input associated label
+    if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT') {
+      if (el.id) {
+        const label = document.querySelector('label[for="' + el.id + '"]');
+        if (label) return label.textContent?.trim();
+      }
+      // Check parent label
+      const parentLabel = el.closest('label');
+      if (parentLabel) {
+        const labelText = parentLabel.textContent?.replace(el.value || '', '')?.trim();
+        if (labelText) return labelText;
+      }
+    }
+
+    // Button/link content
+    if (el.tagName === 'BUTTON' || el.tagName === 'A') {
+      const text = el.textContent?.trim();
+      if (text) return text.substring(0, 100);
+    }
+
+    // Alt text for images
+    if (el.tagName === 'IMG') {
+      return el.alt || null;
+    }
+
+    // Title attribute fallback
+    if (el.title) return el.title.trim();
+
+    // Placeholder for inputs
+    if (el.placeholder) return null; // Return null, will add as /placeholder
+
+    return null;
+  }
+
+  function getStateFlags(el) {
+    const flags = [];
+
+    // Checked state
+    if (el.checked || el.getAttribute('aria-checked') === 'true') {
+      flags.push('checked');
+    }
+
+    // Disabled state
+    if (el.disabled || el.getAttribute('aria-disabled') === 'true') {
+      flags.push('disabled');
+    }
+
+    // Expanded state
+    if (el.getAttribute('aria-expanded') === 'true') {
+      flags.push('expanded');
+    }
+
+    // Selected state
+    if (el.selected || el.getAttribute('aria-selected') === 'true') {
+      flags.push('selected');
+    }
+
+    // Pressed state
+    if (el.getAttribute('aria-pressed') === 'true') {
+      flags.push('pressed');
+    }
+
+    // Required state
+    if (el.required || el.getAttribute('aria-required') === 'true') {
+      flags.push('required');
+    }
+
+    return flags;
+  }
+
+  function isVisible(el) {
+    const style = window.getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return false;
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+
+  function isInteractiveOrLandmark(role) {
+    return INTERACTIVE_ROLES.has(role) || LANDMARK_ROLES.has(role);
+  }
+
+  function shouldInclude(el) {
+    if (!isVisible(el)) return false;
+    const role = getRole(el);
+    if (!role) return false;
+    // Include interactive, landmarks, and structural elements
+    return isInteractiveOrLandmark(role) ||
+           role === 'heading' ||
+           role === 'img' ||
+           role === 'list' ||
+           role === 'listitem' ||
+           role === 'table' ||
+           role === 'row' ||
+           role === 'cell' ||
+           role === 'columnheader';
+  }
+
+  function assignRef(el, role) {
+    // Only assign refs to interactive elements
+    if (!INTERACTIVE_ROLES.has(role)) return null;
+
+    const ref = 'e' + refCounter++;
+    window.__chromeDevToolsRefs.set(ref, el);
+    return ref;
+  }
+
+  function buildYaml(el, indent = 0) {
+    const role = getRole(el);
+    if (!role) return '';
+
+    const prefix = '  '.repeat(indent) + '- ';
+    const lines = [];
+
+    // Build the line: role "name" [flags] [ref=eN]
+    let line = prefix + role;
+
+    const name = getAccessibleName(el);
+    if (name) {
+      line += ' "' + name.replace(/"/g, '\\\\"') + '"';
+    }
+
+    // Add heading level
+    if (role === 'heading') {
+      const level = el.tagName.match(/H(\\d)/)?.[1] || el.getAttribute('aria-level');
+      if (level) line += ' [level=' + level + ']';
+    }
+
+    // Add state flags
+    const flags = getStateFlags(el);
+    flags.forEach(flag => {
+      line += ' [' + flag + ']';
+    });
+
+    // Add ref for interactive elements
+    const ref = assignRef(el, role);
+    if (ref) {
+      line += ' [ref=' + ref + ']';
+    }
+
+    lines.push(line);
+
+    // Add metadata on subsequent lines
+    if (el.tagName === 'A' && el.href) {
+      lines.push('  '.repeat(indent + 1) + '/url: ' + el.href);
+    }
+    if (el.placeholder) {
+      lines.push('  '.repeat(indent + 1) + '/placeholder: "' + el.placeholder + '"');
+    }
+    if (el.tagName === 'INPUT' && el.value && el.type !== 'password') {
+      lines.push('  '.repeat(indent + 1) + '/value: "' + el.value.substring(0, 50) + '"');
+    }
+
+    // Process children
+    const children = Array.from(el.children);
+    children.forEach(child => {
+      const childYaml = buildYaml(child, indent + 1);
+      if (childYaml) lines.push(childYaml);
+    });
+
+    return lines.join('\\n');
+  }
+
+  function getSnapshot() {
+    const lines = [];
+
+    // Start from body
+    const children = Array.from(document.body.children);
+    children.forEach(child => {
+      const yaml = buildYaml(child, 0);
+      if (yaml) lines.push(yaml);
+    });
+
+    // Save ref counter for next snapshot
+    window.__chromeDevToolsRefCounter = refCounter;
+
+    return lines.join('\\n');
+  }
+
+  return getSnapshot();
+})();
+`;
+}
+
+async function ariaSnapshot() {
+  const args = parseArgs(process.argv.slice(2));
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate if URL provided
+    if (args.url) {
+      await page.goto(args.url, {
+        waitUntil: args['wait-until'] || 'networkidle2',
+      });
+    }
+
+    // Get ARIA snapshot
+    const snapshot = await page.evaluate(getAriaSnapshotScript());
+
+    // Build result
+    const result = {
+      success: true,
+      url: page.url(),
+      title: await page.title(),
+      format: 'yaml',
+      snapshot,
+    };
+
+    // Output to file or stdout
+    if (args.output) {
+      const outputPath = args.output;
+
+      // Ensure snapshots directory exists
+      const outputDir = path.dirname(outputPath);
+
+      await fs.mkdir(outputDir, { recursive: true });
+
+      // Write YAML snapshot
+      await fs.writeFile(outputPath, snapshot, 'utf8');
+
+      outputJSON({
+        success: true,
+        output: path.resolve(outputPath),
+        url: page.url(),
+      });
+    } else {
+      // Output to stdout
+      outputJSON(result);
+    }
+
+    // Default: disconnect to keep browser running for session persistence
+    // Use --close true to fully close browser
+    await (args.close === 'true' ? closeBrowser() : disconnectBrowser());
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+ariaSnapshot();