thanh-kit 2.5.0 → 2.5.1

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

@@ -19,7 +19,7 @@ async function click() {
 
   try {
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless: args.headless
     });
 
     const page = await getPage(browser);
@@ -72,6 +72,7 @@ async function click() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     // Enhance error message with troubleshooting tips
     const enhanced = enhanceError(error, args.selector);

package/templates/skills/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/skills/chrome-devtools/scripts/console.js

@@ -15,7 +15,7 @@ async function monitorConsole() {
 
   try {
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless: args.headless
     });
 
     const page = await getPage(browser);
@@ -71,8 +71,10 @@ async function monitorConsole() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     outputError(error);
+    process.exit(1);
   }
 }
 

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

@@ -15,7 +15,7 @@ async function evaluate() {
 
   try {
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless: args.headless
     });
 
     const page = await getPage(browser);
@@ -27,9 +27,10 @@ async function evaluate() {
       });
     }
 
-    const result = await page.evaluate((script) => {
+    const result = await page.evaluate(async (script) => {
+      // Wrap in async IIFE so user scripts can use await
       // eslint-disable-next-line no-eval
-      return eval(script);
+      return await eval(`(async () => { return ${script}; })()`);
     }, args.script);
 
     outputJSON({
@@ -45,8 +46,10 @@ async function evaluate() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     outputError(error);
+    process.exit(1);
   }
 }
 

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

@@ -24,7 +24,7 @@ async function fill() {
 
   try {
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless: args.headless
     });
 
     const page = await getPage(browser);
@@ -65,6 +65,7 @@ async function fill() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     // Enhance error message with troubleshooting tips
     const enhanced = enhanceError(error, args.selector);

package/templates/skills/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();

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

@@ -64,7 +64,7 @@ async function injectAuth() {
 
   try {
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless: args.headless
     });
 
     const page = await getPage(browser);
@@ -221,6 +221,7 @@ async function injectAuth() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     outputError(error);
   }

package/templates/skills/chrome-devtools/scripts/lib/browser.js

@@ -18,6 +18,51 @@ const AUTH_SESSION_FILE = path.join(__dirname, '..', '.auth-session.json');
 let browserInstance = null;
 let pageInstance = null;
 
+/**
+ * Resolve headless mode based on explicit value or OS auto-detection.
+ * - Explicit 'true'/'false' or boolean always wins
+ * - CI environments (CI, GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL) → headless
+ * - Linux → headless (servers/WSL typically have no display)
+ * - macOS/Windows → headed for better debugging
+ * @param {string|boolean|undefined} value - CLI arg value or boolean
+ * @returns {boolean} - true for headless, false for headed
+ */
+export function resolveHeadless(value) {
+  if (value === false || value === 'false') return false;
+  if (value === true || value === 'true') return true;
+
+  // Auto-detect: CI → headless
+  if (process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI || process.env.JENKINS_URL) {
+    log('Auto-detected CI environment → headless');
+    return true;
+  }
+
+  // Linux → headless (includes WSL, remote servers)
+  if (process.platform === 'linux') {
+    log('Auto-detected Linux → headless');
+    return true;
+  }
+
+  // macOS/Windows → headed for debugging
+  log(`Auto-detected ${process.platform} → headed`);
+  return false;
+}
+
+/**
+ * Get default Chrome profile path based on OS
+ * @returns {string} - Path to Chrome's default user data directory
+ */
+function getDefaultChromeProfilePath() {
+  switch (process.platform) {
+    case 'darwin':
+      return `${process.env.HOME}/Library/Application Support/Google/Chrome`;
+    case 'win32':
+      return `${process.env.LOCALAPPDATA}/Google/Chrome/User Data`;
+    default: // Linux and others
+      return `${process.env.HOME}/.config/google-chrome`;
+  }
+}
+
 /**
  * Read session info from file
  */
@@ -201,20 +246,31 @@ export async function getBrowser(options = {}) {
     return browserInstance;
   }
 
+  // Resolve Chrome profile path
+  let userDataDir = options.userDataDir || options.profile;
+  if (options.useDefaultProfile) {
+    userDataDir = getDefaultChromeProfilePath();
+    log(`Using default Chrome profile: ${userDataDir}`);
+  }
+
+  // Destructure known properties — only pass Puppeteer-valid options to launch()
+  const { headless, args: extraArgs, viewport, useDefaultProfile, profile, browserUrl, wsEndpoint: _ws, userDataDir: _udd, ...restOptions } = options;
+
   // Launch new browser
   const launchOptions = {
-    headless: options.headless !== false,
+    headless: resolveHeadless(headless),
     args: [
       '--no-sandbox',
       '--disable-setuid-sandbox',
       '--disable-dev-shm-usage',
-      ...(options.args || [])
+      ...(extraArgs || [])
     ],
-    defaultViewport: options.viewport || {
+    defaultViewport: viewport || {
       width: 1920,
       height: 1080
     },
-    ...options
+    ...(userDataDir && { userDataDir }),
+    ...restOptions
   };
 
   log('Launching new browser');

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

@@ -2,12 +2,24 @@
 /**
  * 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, parseArgs, outputJSON, outputError } from './lib/browser.js';
+import { getBrowser, getPage, closeBrowser, disconnectBrowser, saveAuthSession, parseArgs, outputJSON, outputError } from './lib/browser.js';
 
 async function navigate() {
   const args = parseArgs(process.argv.slice(2));
@@ -18,8 +30,14 @@ async function navigate() {
   }
 
   try {
+    // Force headed mode when waiting for interactive login
+    const headless = args['wait-for-login'] ? false : args.headless;
+
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless,
+      useDefaultProfile: args['use-default-profile'] === 'true',
+      profile: args.profile,
+      browserUrl: args['browser-url']
     });
 
     const page = await getPage(browser);
@@ -37,6 +55,70 @@ async function navigate() {
       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
@@ -46,8 +128,10 @@ async function navigate() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     outputError(error);
+    process.exit(1);
   }
 }
 

package/templates/skills/chrome-devtools/scripts/network.js

@@ -16,7 +16,7 @@ async function monitorNetwork() {
 
   try {
     const browser = await getBrowser({
-      headless: args.headless !== 'false'
+      headless: args.headless
     });
 
     const page = await getPage(browser);
@@ -98,8 +98,10 @@ async function monitorNetwork() {
     } else {
       await disconnectBrowser();
     }
+    process.exit(0);
   } catch (error) {
     outputError(error);
+    process.exit(1);
   }
 }