cokit-cli 1.0.4 → 1.0.6

package/templates/repo/.github/skills/ck-chrome-devtools/scripts/README.md

@@ -0,0 +1,272 @@
+# 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 "%USERPROFILE%/.claude/skills/chrome-devtools/scripts" ]; then
+  SKILL_DIR="%USERPROFILE%/.claude/skills/chrome-devtools/scripts"
+elif [ -d "%USERPROFILE%/.claude/skills/chrome-devtools/scripts" ]; then
+  SKILL_DIR="%USERPROFILE%/.claude/skills/chrome-devtools/scripts"
+fi
+cd "$SKILL_DIR"
+```
+
+### Quick Install
+
+```bash
+pwd  # Should show current working directory
+cd $SKILL_DIR/.claude/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.
+
+### 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 AI assistants. 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/templates/repo/.github/skills/ck-chrome-devtools/scripts/__tests__/selector.test.js

@@ -0,0 +1,210 @@
+/**
+ * Tests for selector parsing library
+ * Run with: node --test __tests__/selector.test.js
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseSelector } from '../lib/selector.js';
+
+describe('parseSelector', () => {
+  describe('CSS Selectors', () => {
+    it('should detect simple CSS selectors', () => {
+      const result = parseSelector('button');
+      assert.strictEqual(result.type, 'css');
+      assert.strictEqual(result.selector, 'button');
+    });
+
+    it('should detect class selectors', () => {
+      const result = parseSelector('.btn-submit');
+      assert.strictEqual(result.type, 'css');
+      assert.strictEqual(result.selector, '.btn-submit');
+    });
+
+    it('should detect ID selectors', () => {
+      const result = parseSelector('#email-input');
+      assert.strictEqual(result.type, 'css');
+      assert.strictEqual(result.selector, '#email-input');
+    });
+
+    it('should detect attribute selectors', () => {
+      const result = parseSelector('button[type="submit"]');
+      assert.strictEqual(result.type, 'css');
+      assert.strictEqual(result.selector, 'button[type="submit"]');
+    });
+
+    it('should detect complex CSS selectors', () => {
+      const result = parseSelector('div.container > button.btn-primary:hover');
+      assert.strictEqual(result.type, 'css');
+    });
+  });
+
+  describe('XPath Selectors', () => {
+    it('should detect absolute XPath', () => {
+      const result = parseSelector('/html/body/button');
+      assert.strictEqual(result.type, 'xpath');
+      assert.strictEqual(result.selector, '/html/body/button');
+    });
+
+    it('should detect relative XPath', () => {
+      const result = parseSelector('//button');
+      assert.strictEqual(result.type, 'xpath');
+      assert.strictEqual(result.selector, '//button');
+    });
+
+    it('should detect XPath with text matching', () => {
+      const result = parseSelector('//button[text()="Click Me"]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+
+    it('should detect XPath with contains', () => {
+      const result = parseSelector('//button[contains(text(),"Submit")]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+
+    it('should detect XPath with attributes', () => {
+      const result = parseSelector('//input[@type="email"]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+
+    it('should detect grouped XPath', () => {
+      const result = parseSelector('(//button)[1]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+  });
+
+  describe('Security Validation', () => {
+    it('should block javascript: injection', () => {
+      assert.throws(
+        () => parseSelector('//button[@onclick="javascript:alert(1)"]'),
+        /XPath injection detected.*javascript:/i
+      );
+    });
+
+    it('should block <script tag injection', () => {
+      assert.throws(
+        () => parseSelector('//div[contains(text(),"<script>alert(1)</script>")]'),
+        /XPath injection detected.*<script/i
+      );
+    });
+
+    it('should block onerror= injection', () => {
+      assert.throws(
+        () => parseSelector('//img[@onerror="alert(1)"]'),
+        /XPath injection detected.*onerror=/i
+      );
+    });
+
+    it('should block onload= injection', () => {
+      assert.throws(
+        () => parseSelector('//body[@onload="malicious()"]'),
+        /XPath injection detected.*onload=/i
+      );
+    });
+
+    it('should block onclick= injection', () => {
+      assert.throws(
+        () => parseSelector('//a[@onclick="steal()"]'),
+        /XPath injection detected.*onclick=/i
+      );
+    });
+
+    it('should block eval( injection', () => {
+      assert.throws(
+        () => parseSelector('//div[eval("malicious")]'),
+        /XPath injection detected.*eval\(/i
+      );
+    });
+
+    it('should block Function( injection', () => {
+      assert.throws(
+        () => parseSelector('//div[Function("return 1")()]'),
+        /XPath injection detected.*Function\(/i
+      );
+    });
+
+    it('should block constructor( injection', () => {
+      assert.throws(
+        () => parseSelector('//div[constructor("alert(1)")()]'),
+        /XPath injection detected.*constructor\(/i
+      );
+    });
+
+    it('should be case-insensitive for security checks', () => {
+      assert.throws(
+        () => parseSelector('//div[@ONERROR="alert(1)"]'),
+        /XPath injection detected/i
+      );
+    });
+
+    it('should block extremely long selectors (DoS prevention)', () => {
+      const longSelector = '//' + 'a'.repeat(1001);
+      assert.throws(
+        () => parseSelector(longSelector),
+        /XPath selector too long/i
+      );
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should throw on empty string', () => {
+      assert.throws(
+        () => parseSelector(''),
+        /Selector must be a non-empty string/
+      );
+    });
+
+    it('should throw on null', () => {
+      assert.throws(
+        () => parseSelector(null),
+        /Selector must be a non-empty string/
+      );
+    });
+
+    it('should throw on undefined', () => {
+      assert.throws(
+        () => parseSelector(undefined),
+        /Selector must be a non-empty string/
+      );
+    });
+
+    it('should throw on non-string input', () => {
+      assert.throws(
+        () => parseSelector(123),
+        /Selector must be a non-empty string/
+      );
+    });
+
+    it('should handle selectors with special characters', () => {
+      const result = parseSelector('button[data-test="submit-form"]');
+      assert.strictEqual(result.type, 'css');
+    });
+
+    it('should allow safe XPath with parentheses', () => {
+      const result = parseSelector('//button[contains(text(),"Save")]');
+      assert.strictEqual(result.type, 'xpath');
+      // Should not throw
+    });
+  });
+
+  describe('Real-World Examples', () => {
+    it('should handle common button selector', () => {
+      const result = parseSelector('//button[contains(text(),"Submit")]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+
+    it('should handle complex form selector', () => {
+      const result = parseSelector('//form[@id="login-form"]//input[@type="email"]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+
+    it('should handle descendant selector', () => {
+      const result = parseSelector('//div[@class="modal"]//button[@class="close"]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+
+    it('should handle nth-child equivalent', () => {
+      const result = parseSelector('(//li)[3]');
+      assert.strictEqual(result.type, 'xpath');
+    });
+  });
+});