@macpaw/cctk 1.0.0-beta.1

package/templates/claude/skills/chrome-devtools/scripts/click.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Click an element
+ * Usage: node click.js --selector ".button" [--url https://example.com] [--wait-for ".result"]
+ * Supports both CSS and XPath selectors:
+ *   - CSS: node click.js --selector "button.submit"
+ *   - XPath: node click.js --selector "//button[contains(text(),'Submit')]"
+ */
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+import { parseSelector, waitForElement, clickElement, enhanceError } from './lib/selector.js';
+
+async function click() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.selector) {
+    outputError(new Error('--selector is required'));
+
+    return;
+  }
+
+  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',
+      });
+    }
+
+    // Parse and validate selector
+    const parsed = parseSelector(args.selector);
+
+    // Wait for element based on selector type
+    await waitForElement(page, parsed, {
+      visible: true,
+      timeout: Number.parseInt(args.timeout || '5000'),
+    });
+
+    // Set up navigation promise BEFORE clicking (in case click triggers immediate navigation)
+    const navigationPromise = page
+      .waitForNavigation({
+        waitUntil: 'load',
+        timeout: 5000,
+      })
+      .catch(() => null); // Catch timeout - navigation may not occur
+
+    // Click element
+    await clickElement(page, parsed);
+
+    // Wait for optional selector after click
+    if (args['wait-for']) {
+      await page.waitForSelector(args['wait-for'], {
+        timeout: Number.parseInt(args.timeout || '5000'),
+      });
+    } else {
+      // Wait for navigation to complete (or timeout if no navigation)
+      await navigationPromise;
+    }
+
+    outputJSON({
+      success: true,
+      url: page.url(),
+      title: await page.title(),
+    });
+
+    // 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) {
+    // Enhance error message with troubleshooting tips
+    const enhanced = enhanceError(error, args.selector);
+
+    outputError(enhanced);
+    process.exit(1);
+  }
+}
+
+click();

package/templates/claude/skills/chrome-devtools/scripts/console.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Monitor console messages
+ * Usage: node console.js --url https://example.com [--types error,warn] [--duration 5000]
+ */
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+
+async function monitorConsole() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.url) {
+    outputError(new Error('--url is required'));
+
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    const messages = [];
+    const filterTypes = args.types ? args.types.split(',') : null;
+
+    // Listen for console messages
+    page.on('console', (msg) => {
+      const type = msg.type();
+
+      if (!filterTypes || filterTypes.includes(type)) {
+        messages.push({
+          type,
+          text: msg.text(),
+          location: msg.location(),
+          timestamp: Date.now(),
+        });
+      }
+    });
+
+    // Listen for page errors
+    page.on('pageerror', (error) => {
+      messages.push({
+        type: 'pageerror',
+        text: error.message,
+        stack: error.stack,
+        timestamp: Date.now(),
+      });
+    });
+
+    // Navigate
+    await page.goto(args.url, {
+      waitUntil: args['wait-until'] || 'networkidle2',
+    });
+
+    // Wait for additional time if specified
+    if (args.duration) {
+      await new Promise((resolve) => setTimeout(resolve, Number.parseInt(args.duration)));
+    }
+
+    outputJSON({
+      success: true,
+      url: page.url(),
+      messageCount: messages.length,
+      messages,
+    });
+
+    // 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);
+  }
+}
+
+monitorConsole();

package/templates/claude/skills/chrome-devtools/scripts/evaluate.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Execute JavaScript in page context
+ * Usage: node evaluate.js --script "document.title" [--url https://example.com]
+ */
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+
+async function evaluate() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.script) {
+    outputError(new Error('--script is required'));
+
+    return;
+  }
+
+  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',
+      });
+    }
+
+    const result = await page.evaluate((script) => {
+      // eslint-disable-next-line no-eval
+      return eval(script);
+    }, args.script);
+
+    outputJSON({
+      success: true,
+      result,
+      url: page.url(),
+    });
+
+    // 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);
+  }
+}
+
+evaluate();

package/templates/claude/skills/chrome-devtools/scripts/fill.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Fill form fields
+ * Usage: node fill.js --selector "#input" --value "text" [--url https://example.com]
+ * Supports both CSS and XPath selectors:
+ *   - CSS: node fill.js --selector "#email" --value "user@example.com"
+ *   - XPath: node fill.js --selector "//input[@type='email']" --value "user@example.com"
+ */
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+} from './lib/browser.js';
+import { parseSelector, waitForElement, typeIntoElement, enhanceError } from './lib/selector.js';
+
+async function fill() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.selector) {
+    outputError(new Error('--selector is required'));
+
+    return;
+  }
+
+  if (!args.value) {
+    outputError(new Error('--value is required'));
+
+    return;
+  }
+
+  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',
+      });
+    }
+
+    // Parse and validate selector
+    const parsed = parseSelector(args.selector);
+
+    // Wait for element based on selector type
+    await waitForElement(page, parsed, {
+      visible: true,
+      timeout: Number.parseInt(args.timeout || '5000'),
+    });
+
+    // Type into element
+    await typeIntoElement(page, parsed, args.value, {
+      clear: args.clear === 'true',
+      delay: Number.parseInt(args.delay || '0'),
+    });
+
+    outputJSON({
+      success: true,
+      selector: args.selector,
+      value: args.value,
+      url: page.url(),
+    });
+
+    // 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) {
+    // Enhance error message with troubleshooting tips
+    const enhanced = enhanceError(error, args.selector);
+
+    outputError(enhanced);
+    process.exit(1);
+  }
+}
+
+fill();

package/templates/claude/skills/chrome-devtools/scripts/inject-auth.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+/**
+ * Inject authentication cookies/tokens into browser session
+ * Usage: node inject-auth.js --url https://example.com --cookies '[{"name":"token","value":"xxx","domain":".example.com"}]'
+ *        node inject-auth.js --url https://example.com --token "Bearer xxx" [--header Authorization]
+ *        node inject-auth.js --url https://example.com --local-storage '{"key":"value"}'
+ *        node inject-auth.js --url https://example.com --session-storage '{"key":"value"}'
+ *
+ * This script injects authentication data into browser session for testing protected routes.
+ * The session persists across script executions until --close true is used.
+ *
+ * Workflow for testing protected routes:
+ *   1. User manually logs into the site in their browser
+ *   2. User extracts cookies/tokens from browser DevTools
+ *   3. Run this script to inject auth into puppeteer session
+ *   4. Run other scripts (screenshot, navigate, etc.) which will use authenticated session
+ *
+ * Session behavior:
+ *   --close false  : Keep browser running (default for chaining)
+ *   --close true   : Close browser completely and clear session
+ */
+import {
+  getBrowser,
+  getPage,
+  closeBrowser,
+  disconnectBrowser,
+  parseArgs,
+  outputJSON,
+  outputError,
+  saveAuthSession,
+  clearAuthSession,
+} from './lib/browser.js';
+
+/**
+ * Parse cookies from JSON string or file
+ * @param {string} cookiesInput - JSON string or file path
+ * @returns {Array} - Array of cookie objects
+ */
+function parseCookies(cookiesInput) {
+  try {
+    // Try parsing as JSON string
+    return JSON.parse(cookiesInput);
+  } catch {
+    throw new Error(
+      `Invalid cookies format. Expected JSON array: [{"name":"cookie_name","value":"cookie_value","domain":".example.com"}]`,
+    );
+  }
+}
+
+/**
+ * Parse storage data from JSON string
+ * @param {string} storageInput - JSON string
+ * @returns {Object} - Storage key-value pairs
+ */
+function parseStorage(storageInput) {
+  try {
+    return JSON.parse(storageInput);
+  } catch {
+    throw new Error(`Invalid storage format. Expected JSON object: {"key":"value"}`);
+  }
+}
+
+async function injectAuth() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.url) {
+    outputError(new Error('--url is required (base URL for the protected site)'));
+
+    return;
+  }
+
+  // Validate at least one auth method provided
+  if (!args.cookies && !args.token && !args['local-storage'] && !args['session-storage']) {
+    outputError(
+      new Error('At least one auth method required: --cookies, --token, --local-storage, or --session-storage'),
+    );
+
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false',
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate to the URL first to set the domain context
+    await page.goto(args.url, {
+      waitUntil: args['wait-until'] || 'networkidle2',
+      timeout: Number.parseInt(args.timeout || '30000'),
+    });
+
+    const result = {
+      success: true,
+      url: args.url,
+      injected: [],
+    };
+
+    // Inject cookies
+    if (args.cookies) {
+      const cookies = parseCookies(args.cookies);
+
+      // Validate and normalize cookies
+      const normalizedCookies = cookies.map((cookie) => {
+        if (!cookie.name || !cookie.value) {
+          throw new Error(`Cookie must have 'name' and 'value' properties`);
+        }
+
+        // Extract domain from URL if not provided
+        if (!cookie.domain) {
+          const urlObj = new URL(args.url);
+
+          cookie.domain = urlObj.hostname;
+        }
+
+        return {
+          name: cookie.name,
+          value: cookie.value,
+          domain: cookie.domain,
+          path: cookie.path || '/',
+          httpOnly: cookie.httpOnly === undefined ? false : cookie.httpOnly,
+          secure: cookie.secure === undefined ? args.url.startsWith('https') : cookie.secure,
+          sameSite: cookie.sameSite || 'Lax',
+          ...(cookie.expires && { expires: cookie.expires }),
+        };
+      });
+
+      await page.setCookie(...normalizedCookies);
+      result.injected.push({
+        type: 'cookies',
+        count: normalizedCookies.length,
+        names: normalizedCookies.map((c) => c.name),
+      });
+    }
+
+    // Inject Bearer token via localStorage (common pattern)
+    if (args.token) {
+      const tokenKey = args['token-key'] || 'access_token';
+      const token = args.token.startsWith('Bearer ') ? args.token.slice(7) : args.token;
+
+      await page.evaluate(
+        (key, value) => {
+          localStorage.setItem(key, value);
+        },
+        tokenKey,
+        token,
+      );
+
+      result.injected.push({
+        type: 'token',
+        key: tokenKey,
+        storage: 'localStorage',
+      });
+
+      // Also set Authorization header for future requests if header option provided
+      if (args.header) {
+        await page.setExtraHTTPHeaders({
+          [args.header]: args.token.startsWith('Bearer ') ? args.token : `Bearer ${args.token}`,
+        });
+        result.injected.push({
+          type: 'header',
+          name: args.header,
+        });
+      }
+    }
+
+    // Inject localStorage items
+    if (args['local-storage']) {
+      const storageData = parseStorage(args['local-storage']);
+
+      await page.evaluate((data) => {
+        Object.entries(data).forEach(([key, value]) => {
+          localStorage.setItem(key, typeof value === 'string' ? value : JSON.stringify(value));
+        });
+      }, storageData);
+
+      result.injected.push({
+        type: 'localStorage',
+        keys: Object.keys(storageData),
+      });
+    }
+
+    // Inject sessionStorage items
+    if (args['session-storage']) {
+      const storageData = parseStorage(args['session-storage']);
+
+      await page.evaluate((data) => {
+        Object.entries(data).forEach(([key, value]) => {
+          sessionStorage.setItem(key, typeof value === 'string' ? value : JSON.stringify(value));
+        });
+      }, storageData);
+
+      result.injected.push({
+        type: 'sessionStorage',
+        keys: Object.keys(storageData),
+      });
+    }
+
+    // Reload page to apply auth (optional, use --reload true)
+    if (args.reload === 'true') {
+      await page.reload({ waitUntil: 'networkidle2' });
+      result.reloaded = true;
+    }
+
+    // Save auth session to file for persistence across script executions
+    const authSessionData = {};
+
+    if (args.cookies) {
+      authSessionData.cookies = parseCookies(args.cookies);
+    }
+    if (args['local-storage']) {
+      authSessionData.localStorage = parseStorage(args['local-storage']);
+    }
+    if (args['session-storage']) {
+      authSessionData.sessionStorage = parseStorage(args['session-storage']);
+    }
+    if (args.token && args.header) {
+      authSessionData.headers = {
+        [args.header]: args.token.startsWith('Bearer ') ? args.token : `Bearer ${args.token}`,
+      };
+    }
+
+    // Clear existing auth if --clear flag used
+    if (args.clear === 'true') {
+      clearAuthSession();
+      result.cleared = true;
+    } else if (Object.keys(authSessionData).length > 0) {
+      saveAuthSession(authSessionData);
+      result.persisted = true;
+    }
+
+    // Verify auth by checking page title and URL after injection
+    result.finalUrl = page.url();
+    result.title = await page.title();
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running for session persistence
+    await (args.close === 'true' ? closeBrowser() : disconnectBrowser());
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+injectAuth();

package/templates/claude/skills/chrome-devtools/scripts/install-deps.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# System dependencies installation script for Chrome DevTools Agent Skill
+# macOS-only: Chrome/Chromium includes all dependencies
+
+echo "✅ macOS detected - no additional system dependencies needed"
+echo ""
+echo "Chrome/Chromium runs natively on macOS without additional libraries."
+echo ""
+echo "📝 To install the skill, run:"
+echo "   cd .claude/skills/chrome-devtools/scripts && npm install"
+echo ""

package/templates/claude/skills/chrome-devtools/scripts/install.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Installation script for Chrome DevTools Agent Skill (macOS)
+
+set -e
+
+echo "🚀 Installing Chrome DevTools Agent Skill..."
+echo ""
+
+# Check Node.js version
+echo "Checking Node.js version..."
+NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
+
+if [ "$NODE_VERSION" -lt 18 ]; then
+  echo "❌ Error: Node.js 18+ is required. Current version: $(node --version)"
+  echo "   Install via Homebrew: brew install node"
+  exit 1
+fi
+
+echo "✓ Node.js version: $(node --version)"
+echo ""
+echo "Platform: macOS (no system dependencies needed)"
+echo ""
+
+# Install Node.js dependencies
+echo "Installing Node.js dependencies..."
+npm install
+
+echo ""
+echo "✅ Installation complete!"
+echo ""
+echo "Test the installation:"
+echo "  node navigate.js --url https://example.com"
+echo ""
+echo "For more information:"
+echo "  cat README.md"
+echo ""