cokit-cli 1.3.0 → 1.4.0

package/templates/repo/.github/skills/ck-chrome-devtools/scripts/click.js

@@ -0,0 +1,84 @@
+#!/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
+    });
+
+    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: 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: 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
+    if (args.close === 'true') {
+      await closeBrowser();
+    } else {
+      await 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/repo/.github/skills/ck-chrome-devtools/scripts/connect-chrome.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Connect to an existing Chrome browser launched with remote debugging
+ *
+ * Two-step workflow:
+ *   1. User launches Chrome with: chrome --remote-debugging-port=9222
+ *   2. Connect with this script: node connect-chrome.js --browser-url http://localhost:9222
+ *
+ * Or launch Chrome automatically:
+ *   node connect-chrome.js --launch --port 9222
+ *
+ * This is useful for:
+ *   - Debugging (can see browser window while scripts run)
+ *   - Using existing Chrome session with all logged-in accounts
+ *   - Avoiding Puppeteer's bundled Chromium
+ */
+import { spawn } from 'child_process';
+import { getBrowser, getPage, disconnectBrowser, parseArgs, outputJSON, outputError } from './lib/browser.js';
+
+/**
+ * Get Chrome executable path based on OS
+ * @returns {string} - Path to Chrome executable
+ */
+function getChromeExecutablePath() {
+  switch (process.platform) {
+    case 'darwin':
+      return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+    case 'win32':
+      // Try common installation paths
+      const paths = [
+        `${process.env['PROGRAMFILES']}/Google/Chrome/Application/chrome.exe`,
+        `${process.env['PROGRAMFILES(X86)']}/Google/Chrome/Application/chrome.exe`,
+        `${process.env.LOCALAPPDATA}/Google/Chrome/Application/chrome.exe`
+      ];
+      // Return first path (user should have Chrome installed in standard location)
+      return paths[0];
+    default: // Linux
+      return 'google-chrome';
+  }
+}
+
+/**
+ * Launch Chrome with remote debugging enabled
+ * @param {number} port - Debug port (default 9222)
+ * @returns {Promise<ChildProcess>}
+ */
+function launchChromeWithDebugging(port = 9222) {
+  const chromePath = getChromeExecutablePath();
+  const args = [
+    `--remote-debugging-port=${port}`,
+    '--no-first-run',
+    '--no-default-browser-check'
+  ];
+
+  const chrome = spawn(chromePath, args, {
+    detached: true,
+    stdio: 'ignore'
+  });
+
+  chrome.unref();
+  return chrome;
+}
+
+/**
+ * Wait for Chrome debug endpoint to be ready
+ * @param {string} browserUrl - Browser debug URL
+ * @param {number} timeout - Max wait time in ms
+ * @returns {Promise<boolean>}
+ */
+async function waitForDebugEndpoint(browserUrl, timeout = 10000) {
+  const start = Date.now();
+  const checkUrl = `${browserUrl}/json/version`;
+
+  while (Date.now() - start < timeout) {
+    try {
+      const response = await fetch(checkUrl);
+      if (response.ok) return true;
+    } catch {
+      // Not ready yet
+    }
+    await new Promise(r => setTimeout(r, 500));
+  }
+  return false;
+}
+
+async function connectChrome() {
+  const args = parseArgs(process.argv.slice(2));
+  const port = parseInt(args.port || '9222');
+  const browserUrl = args['browser-url'] || `http://localhost:${port}`;
+
+  try {
+    // Launch Chrome if requested
+    if (args.launch) {
+      launchChromeWithDebugging(port);
+
+      // Wait for debug endpoint
+      const ready = await waitForDebugEndpoint(browserUrl);
+      if (!ready) {
+        outputError(new Error(`Chrome did not start within timeout. Check if port ${port} is available.`));
+        return;
+      }
+    }
+
+    // Connect to Chrome via browserUrl
+    const browser = await getBrowser({ browserUrl });
+    const page = await getPage(browser);
+
+    // Navigate if URL provided
+    if (args.url) {
+      await page.goto(args.url, {
+        waitUntil: args['wait-until'] || 'networkidle2',
+        timeout: parseInt(args.timeout || '30000')
+      });
+    }
+
+    const result = {
+      success: true,
+      browserUrl,
+      connected: true,
+      url: page.url(),
+      title: await page.title(),
+      hint: args.launch
+        ? 'Chrome launched with debugging. Browser window is visible.'
+        : 'Connected to existing Chrome instance.'
+    };
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running
+    await disconnectBrowser();
+    process.exit(0);
+  } catch (error) {
+    // Provide helpful error message
+    if (error.message.includes('ECONNREFUSED')) {
+      outputError(new Error(
+        `Could not connect to Chrome at ${browserUrl}. ` +
+        `Make sure Chrome is running with: ` +
+        `chrome --remote-debugging-port=${port}`
+      ));
+    } else {
+      outputError(error);
+    }
+  }
+}
+
+connectChrome();

package/templates/repo/.github/skills/ck-chrome-devtools/scripts/console.js

@@ -0,0 +1,81 @@
+#!/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
+    });
+
+    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: 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, parseInt(args.duration)));
+    }
+
+    outputJSON({
+      success: true,
+      url: page.url(),
+      messageCount: messages.length,
+      messages: messages
+    });
+
+    // 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);
+  }
+}
+
+monitorConsole();

package/templates/repo/.github/skills/ck-chrome-devtools/scripts/evaluate.js

@@ -0,0 +1,56 @@
+#!/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
+    });
+
+    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(async (script) => {
+      // Wrap in async IIFE so user scripts can use await
+      // eslint-disable-next-line no-eval
+      return await eval(`(async () => { return ${script}; })()`);
+    }, args.script);
+
+    outputJSON({
+      success: true,
+      result: result,
+      url: page.url()
+    });
+
+    // 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);
+  }
+}
+
+evaluate();

package/templates/repo/.github/skills/ck-chrome-devtools/scripts/fill.js

@@ -0,0 +1,77 @@
+#!/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
+    });
+
+    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: parseInt(args.timeout || '5000')
+    });
+
+    // Type into element
+    await typeIntoElement(page, parsed, args.value, {
+      clear: args.clear === 'true',
+      delay: 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
+    if (args.close === 'true') {
+      await closeBrowser();
+    } else {
+      await 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/repo/.github/skills/ck-chrome-devtools/scripts/import-cookies.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * Import cookies from JSON file exported by browser extensions
+ * Supports: EditThisCookie, Cookie-Editor, Netscape (txt) formats
+ *
+ * Usage:
+ *   node import-cookies.js --file ./cookies.json --url https://example.com
+ *   node import-cookies.js --file ./cookies.txt --format netscape --url https://example.com
+ *
+ * Workflow:
+ *   1. Install "Cookie-Editor" or "EditThisCookie" Chrome extension
+ *   2. Navigate to target site and log in manually
+ *   3. Export cookies as JSON via extension
+ *   4. Run this script to import into puppeteer session
+ *   5. Use other scripts (screenshot, navigate) with authenticated session
+ */
+import fs from 'fs';
+import { getBrowser, getPage, closeBrowser, disconnectBrowser, parseArgs, outputJSON, outputError, saveAuthSession } from './lib/browser.js';
+
+/**
+ * Parse cookies from EditThisCookie/Cookie-Editor JSON format
+ * @param {Array} cookies - Array of cookie objects
+ * @returns {Array} - Normalized cookie array for Puppeteer
+ */
+function parseJsonCookies(cookies) {
+  return cookies.map(cookie => {
+    // Handle different property names from various extensions
+    const normalized = {
+      name: cookie.name,
+      value: cookie.value,
+      domain: cookie.domain,
+      path: cookie.path || '/',
+      httpOnly: cookie.httpOnly ?? false,
+      secure: cookie.secure ?? false,
+      sameSite: cookie.sameSite || 'Lax'
+    };
+
+    // Handle expiration (different extensions use different names)
+    if (cookie.expirationDate) {
+      normalized.expires = cookie.expirationDate;
+    } else if (cookie.expires) {
+      normalized.expires = typeof cookie.expires === 'number'
+        ? cookie.expires
+        : new Date(cookie.expires).getTime() / 1000;
+    }
+
+    return normalized;
+  });
+}
+
+/**
+ * Parse Netscape cookie file format (used by curl, wget, etc.)
+ * Format: domain\tflags\tpath\tsecure\texpiration\tname\tvalue
+ * @param {string} content - Netscape format cookie file content
+ * @returns {Array} - Normalized cookie array for Puppeteer
+ */
+function parseNetscapeCookies(content) {
+  const cookies = [];
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    // Skip comments and empty lines
+    if (line.startsWith('#') || line.trim() === '') continue;
+
+    const parts = line.split('\t');
+    if (parts.length < 7) continue;
+
+    const [domain, , path, secure, expires, name, value] = parts;
+
+    cookies.push({
+      name: name.trim(),
+      value: value.trim(),
+      domain: domain.trim(),
+      path: path.trim() || '/',
+      secure: secure.toUpperCase() === 'TRUE',
+      httpOnly: false, // Netscape format doesn't include httpOnly
+      expires: parseInt(expires, 10) || undefined,
+      sameSite: 'Lax'
+    });
+  }
+
+  return cookies;
+}
+
+/**
+ * Detect cookie file format from content
+ * @param {string} content - File content
+ * @returns {string} - 'json' or 'netscape'
+ */
+function detectFormat(content) {
+  const trimmed = content.trim();
+  if (trimmed.startsWith('[') || trimmed.startsWith('{')) {
+    return 'json';
+  }
+  return 'netscape';
+}
+
+async function importCookies() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.file) {
+    outputError(new Error('--file is required (path to cookies file)'));
+    return;
+  }
+
+  if (!args.url) {
+    outputError(new Error('--url is required (target URL to apply cookies)'));
+    return;
+  }
+
+  // Read cookie file
+  let fileContent;
+  try {
+    fileContent = fs.readFileSync(args.file, 'utf8');
+  } catch (e) {
+    outputError(new Error(`Failed to read cookie file: ${e.message}`));
+    return;
+  }
+
+  // Parse cookies based on format
+  const format = args.format || detectFormat(fileContent);
+  let cookies;
+
+  try {
+    if (format === 'json') {
+      const parsed = JSON.parse(fileContent);
+      // Handle both array and object with cookies property
+      const cookieArray = Array.isArray(parsed) ? parsed : (parsed.cookies || []);
+      cookies = parseJsonCookies(cookieArray);
+    } else {
+      cookies = parseNetscapeCookies(fileContent);
+    }
+  } catch (e) {
+    outputError(new Error(`Failed to parse cookies (${format}): ${e.message}`));
+    return;
+  }
+
+  if (cookies.length === 0) {
+    outputError(new Error('No valid cookies found in file'));
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate to URL first to establish domain context
+    await page.goto(args.url, {
+      waitUntil: args['wait-until'] || 'networkidle2',
+      timeout: parseInt(args.timeout || '30000')
+    });
+
+    // Filter cookies by domain if --strict-domain is set
+    let cookiesToApply = cookies;
+    if (args['strict-domain']) {
+      const urlDomain = new URL(args.url).hostname;
+      cookiesToApply = cookies.filter(c => {
+        const cookieDomain = c.domain.startsWith('.') ? c.domain.slice(1) : c.domain;
+        return urlDomain.endsWith(cookieDomain);
+      });
+    }
+
+    // Apply cookies
+    await page.setCookie(...cookiesToApply);
+
+    // Save to auth session for persistence
+    saveAuthSession({ cookies: cookiesToApply });
+
+    // Reload to apply cookies if --reload is set
+    if (args.reload === 'true') {
+      await page.reload({ waitUntil: 'networkidle2' });
+    }
+
+    const result = {
+      success: true,
+      file: args.file,
+      format,
+      url: args.url,
+      imported: {
+        total: cookiesToApply.length,
+        names: cookiesToApply.map(c => c.name)
+      },
+      persisted: true,
+      finalUrl: page.url(),
+      title: await page.title()
+    };
+
+    outputJSON(result);
+
+    // Default: disconnect to keep browser running
+    if (args.close === 'true') {
+      await closeBrowser();
+    } else {
+      await disconnectBrowser();
+    }
+    process.exit(0);
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+importCookies();