cokit-cli 1.3.0 → 1.4.0

package/skills/ck-chrome-devtools/scripts/inject-auth.js

@@ -0,0 +1,230 @@
+#!/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
+    });
+
+    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: 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 ? cookie.httpOnly : false,
+          secure: cookie.secure !== undefined ? cookie.secure : args.url.startsWith('https'),
+          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
+    if (args.close === 'true') {
+      await closeBrowser();
+    } else {
+      await disconnectBrowser();
+    }
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+injectAuth();

package/skills/ck-chrome-devtools/scripts/install-deps.sh

@@ -0,0 +1,181 @@
+#!/bin/bash
+# System dependencies installation script for Chrome DevTools Agent Skill
+# This script installs required system libraries for running Chrome/Chromium
+
+set -e
+
+echo "🚀 Installing system dependencies for Chrome/Chromium..."
+echo ""
+
+# Detect OS
+if [ -f /etc/os-release ]; then
+    . /etc/os-release
+    OS=$ID
+else
+    echo "❌ Cannot detect OS. This script supports Debian/Ubuntu-based systems."
+    exit 1
+fi
+
+# Check if running as root
+if [ "$EUID" -ne 0 ]; then
+    SUDO="sudo"
+    echo "⚠️  This script requires root privileges to install system packages."
+    echo "   You may be prompted for your password."
+    echo ""
+else
+    SUDO=""
+fi
+
+# Install dependencies based on OS
+case $OS in
+    ubuntu|debian|pop)
+        echo "Detected: $PRETTY_NAME"
+        echo "Installing dependencies with apt..."
+        echo ""
+
+        $SUDO apt-get update
+
+        # Install Chrome dependencies
+        $SUDO apt-get install -y \
+            ca-certificates \
+            fonts-liberation \
+            libasound2t64 \
+            libatk-bridge2.0-0 \
+            libatk1.0-0 \
+            libc6 \
+            libcairo2 \
+            libcups2 \
+            libdbus-1-3 \
+            libexpat1 \
+            libfontconfig1 \
+            libgbm1 \
+            libgcc1 \
+            libglib2.0-0 \
+            libgtk-3-0 \
+            libnspr4 \
+            libnss3 \
+            libpango-1.0-0 \
+            libpangocairo-1.0-0 \
+            libstdc++6 \
+            libx11-6 \
+            libx11-xcb1 \
+            libxcb1 \
+            libxcomposite1 \
+            libxcursor1 \
+            libxdamage1 \
+            libxext6 \
+            libxfixes3 \
+            libxi6 \
+            libxrandr2 \
+            libxrender1 \
+            libxss1 \
+            libxtst6 \
+            lsb-release \
+            wget \
+            xdg-utils
+
+        echo ""
+        echo "✅ System dependencies installed successfully!"
+        ;;
+
+    fedora|rhel|centos)
+        echo "Detected: $PRETTY_NAME"
+        echo "Installing dependencies with dnf/yum..."
+        echo ""
+
+        # Try dnf first, fallback to yum
+        if command -v dnf &> /dev/null; then
+            PKG_MGR="dnf"
+        else
+            PKG_MGR="yum"
+        fi
+
+        $SUDO $PKG_MGR install -y \
+            alsa-lib \
+            atk \
+            at-spi2-atk \
+            cairo \
+            cups-libs \
+            dbus-libs \
+            expat \
+            fontconfig \
+            glib2 \
+            gtk3 \
+            libdrm \
+            libgbm \
+            libX11 \
+            libxcb \
+            libXcomposite \
+            libXcursor \
+            libXdamage \
+            libXext \
+            libXfixes \
+            libXi \
+            libxkbcommon \
+            libXrandr \
+            libXrender \
+            libXScrnSaver \
+            libXtst \
+            mesa-libgbm \
+            nspr \
+            nss \
+            pango
+
+        echo ""
+        echo "✅ System dependencies installed successfully!"
+        ;;
+
+    arch|manjaro)
+        echo "Detected: $PRETTY_NAME"
+        echo "Installing dependencies with pacman..."
+        echo ""
+
+        $SUDO pacman -Sy --noconfirm \
+            alsa-lib \
+            at-spi2-core \
+            cairo \
+            cups \
+            dbus \
+            expat \
+            glib2 \
+            gtk3 \
+            libdrm \
+            libx11 \
+            libxcb \
+            libxcomposite \
+            libxcursor \
+            libxdamage \
+            libxext \
+            libxfixes \
+            libxi \
+            libxkbcommon \
+            libxrandr \
+            libxrender \
+            libxshmfence \
+            libxss \
+            libxtst \
+            mesa \
+            nspr \
+            nss \
+            pango
+
+        echo ""
+        echo "✅ System dependencies installed successfully!"
+        ;;
+
+    *)
+        echo "❌ Unsupported OS: $OS"
+        echo "   This script supports: Ubuntu, Debian, Fedora, RHEL, CentOS, Arch, Manjaro"
+        echo ""
+        echo "   Please install Chrome/Chromium dependencies manually for your OS."
+        echo "   See: https://pptr.dev/troubleshooting"
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "📝 Next steps:"
+echo "   1. Run: cd $(dirname "$0")"
+echo "   2. Run: npm install"
+echo "   3. Test: node navigate.js --url https://example.com"
+echo ""

package/skills/ck-chrome-devtools/scripts/install.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Installation script for Chrome DevTools Agent Skill
+
+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 "   Please upgrade Node.js: https://nodejs.org/"
+  exit 1
+fi
+
+echo "✓ Node.js version: $(node --version)"
+echo ""
+
+# Check for system dependencies (Linux only)
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+  echo "Checking system dependencies (Linux)..."
+
+  # Check for critical Chrome dependencies
+  MISSING_DEPS=()
+
+  if ! ldconfig -p | grep -q libnss3.so; then
+    MISSING_DEPS+=("libnss3")
+  fi
+
+  if ! ldconfig -p | grep -q libnspr4.so; then
+    MISSING_DEPS+=("libnspr4")
+  fi
+
+  if ! ldconfig -p | grep -q libgbm.so; then
+    MISSING_DEPS+=("libgbm1")
+  fi
+
+  if [ ${#MISSING_DEPS[@]} -gt 0 ]; then
+    echo "⚠️  Missing system dependencies: ${MISSING_DEPS[*]}"
+    echo ""
+    echo "   Chrome/Chromium requires system libraries to run."
+    echo "   Install them with:"
+    echo ""
+    echo "   ./install-deps.sh"
+    echo ""
+    echo "   Or manually:"
+    echo "   sudo apt-get install -y libnss3 libnspr4 libgbm1 libasound2t64 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2"
+    echo ""
+
+    read -p "   Continue anyway? (y/N) " -n 1 -r
+    echo ""
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+      echo "Installation cancelled."
+      exit 1
+    fi
+  else
+    echo "✓ System dependencies found"
+  fi
+  echo ""
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+  echo "Platform: macOS (no system dependencies needed)"
+  echo ""
+elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then
+  echo "Platform: Windows (no system dependencies needed)"
+  echo ""
+fi
+
+# 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 ""

package/skills/ck-chrome-devtools/scripts/navigate.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Navigate to a URL
+ * Usage: node navigate.js --url https://example.com [--wait-until networkidle2] [--timeout 30000]
+ *        node navigate.js --url https://example.com --use-default-profile true
+ *        node navigate.js --url https://example.com --profile "/path/to/chrome/profile"
+ *        node navigate.js --url https://example.com/login --wait-for-login "/dashboard"
+ *
+ * Session behavior:
+ *   --close false  : Keep browser running, disconnect from it (default for chaining)
+ *   --close true   : Close browser completely and clear session
+ *
+ * Profile options (Chrome must be closed first):
+ *   --use-default-profile true : Use Chrome's default profile with all cookies
+ *   --profile <path>           : Use specific Chrome profile directory
+ *   --browser-url <url>        : Connect to Chrome with remote debugging
+ *
+ * Interactive login (OAuth/SSO):
+ *   --wait-for-login <pattern> : Open headed browser, wait for URL to match regex pattern
+ *   --login-timeout <ms>       : Max wait time for login (default: 300000 = 5 min)
+ */
+import { getBrowser, getPage, closeBrowser, disconnectBrowser, saveAuthSession, parseArgs, outputJSON, outputError } from './lib/browser.js';
+
+async function navigate() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.url) {
+    outputError(new Error('--url is required'));
+    return;
+  }
+
+  try {
+    // Force headed mode when waiting for interactive login
+    const headless = args['wait-for-login'] ? false : args.headless;
+
+    const browser = await getBrowser({
+      headless,
+      useDefaultProfile: args['use-default-profile'] === 'true',
+      profile: args.profile,
+      browserUrl: args['browser-url']
+    });
+
+    const page = await getPage(browser);
+
+    const options = {
+      waitUntil: args['wait-until'] || 'networkidle2',
+      timeout: parseInt(args.timeout || '30000')
+    };
+
+    await page.goto(args.url, options);
+
+    const result = {
+      success: true,
+      url: page.url(),
+      title: await page.title()
+    };
+
+    // Interactive login: wait for user to complete OAuth/SSO flow
+    if (args['wait-for-login']) {
+      const pattern = args['wait-for-login'];
+      const loginTimeout = parseInt(args['login-timeout'] || '300000');
+
+      // Validate timeout value
+      if (!Number.isFinite(loginTimeout) || loginTimeout <= 0) {
+        outputError(new Error('--login-timeout must be a positive integer (ms)'));
+        return;
+      }
+
+      // Validate regex pattern before use
+      let regex;
+      try {
+        regex = new RegExp(pattern);
+      } catch (e) {
+        outputError(new Error(`Invalid regex pattern for --wait-for-login: ${e.message}`));
+        return;
+      }
+
+      // Log to stderr so JSON output stays clean
+      process.stderr.write(`[i] Browser opened for manual login. Complete the login flow.\n`);
+      process.stderr.write(`[i] Waiting for URL to match: ${pattern} (timeout: ${loginTimeout / 1000}s)\n`);
+
+      // Poll URL from Node side — survives page navigations during OAuth redirects
+      const deadline = Date.now() + loginTimeout;
+      let loginDetected = false;
+
+      while (Date.now() < deadline) {
+        try {
+          const currentUrl = page.url();
+          if (regex.test(currentUrl)) {
+            loginDetected = true;
+            break;
+          }
+        } catch {
+          // Page may be mid-navigation, retry
+        }
+        await new Promise(r => setTimeout(r, 500));
+      }
+
+      if (loginDetected) {
+        // Save session cookies after successful login
+        const cookies = await page.cookies();
+        if (cookies.length > 0) {
+          saveAuthSession({ cookies });
+          result.cookiesSaved = cookies.length;
+        } else {
+          process.stderr.write('[!] No cookies captured. Previous session preserved.\n');
+          result.cookiesSaved = 0;
+        }
+
+        result.loginCompleted = true;
+        result.url = page.url();
+        result.title = await page.title();
+
+        process.stderr.write(`[OK] Login detected. ${result.cookiesSaved} cookies saved for session reuse.\n`);
+      } else {
+        result.loginCompleted = false;
+        result.loginError = `Login timeout after ${loginTimeout / 1000}s. URL did not match: ${pattern}`;
+        process.stderr.write(`[X] Login timeout. URL never matched: ${pattern}\n`);
+      }
+    }
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running for session persistence
+    // Use --close true to fully close browser
+    if (args.close === 'true') {
+      await closeBrowser();
+    } else {
+      await disconnectBrowser();
+    }
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+    process.exit(1);
+  }
+}
+
+navigate();