@stella-studio/ck 1.0.0

package/.claude/skills/chrome-devtools/scripts/aria-snapshot.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Get ARIA-based accessibility snapshot with stable element refs
+ * Usage: node aria-snapshot.js [--url https://example.com] [--output snapshot.yaml]
+ *
+ * Returns YAML-formatted accessibility tree with:
+ * - Semantic roles (button, link, textbox, heading, etc.)
+ * - Accessible names (what screen readers announce)
+ * - Element states (checked, disabled, expanded)
+ * - Stable refs [ref=eN] that persist for interaction
+ *
+ * Session behavior:
+ *   By default, browser stays running for session persistence
+ *   Use --close true to fully close browser
+ */
+import { getBrowser, getPage, closeBrowser, disconnectBrowser, parseArgs, outputJSON, outputError } from './lib/browser.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Get ARIA snapshot script to inject into page
+ * Builds YAML-formatted accessibility tree with element references
+ */
+function getAriaSnapshotScript() {
+  return `
+(function() {
+  // Store refs on window for later retrieval via selectRef
+  window.__chromeDevToolsRefs = window.__chromeDevToolsRefs || new Map();
+  let refCounter = window.__chromeDevToolsRefCounter || 1;
+
+  // ARIA roles we care about for interaction
+  const INTERACTIVE_ROLES = new Set([
+    'button', 'link', 'textbox', 'checkbox', 'radio', 'combobox',
+    'listbox', 'option', 'menuitem', 'menuitemcheckbox', 'menuitemradio',
+    'tab', 'switch', 'slider', 'spinbutton', 'searchbox', 'tree', 'treeitem',
+    'grid', 'gridcell', 'row', 'rowheader', 'columnheader'
+  ]);
+
+  // Landmark roles for structure
+  const LANDMARK_ROLES = new Set([
+    'banner', 'navigation', 'main', 'complementary', 'contentinfo',
+    'search', 'form', 'region', 'article', 'dialog', 'alertdialog'
+  ]);
+
+  // Implicit ARIA roles from HTML elements
+  const IMPLICIT_ROLES = {
+    'A': (el) => el.href ? 'link' : null,
+    'BUTTON': () => 'button',
+    'INPUT': (el) => {
+      const type = el.type?.toLowerCase();
+      if (type === 'checkbox') return 'checkbox';
+      if (type === 'radio') return 'radio';
+      if (type === 'submit' || type === 'button' || type === 'reset') return 'button';
+      if (type === 'search') return 'searchbox';
+      if (type === 'range') return 'slider';
+      if (type === 'number') return 'spinbutton';
+      return 'textbox';
+    },
+    'TEXTAREA': () => 'textbox',
+    'SELECT': () => 'combobox',
+    'OPTION': () => 'option',
+    'IMG': () => 'img',
+    'NAV': () => 'navigation',
+    'MAIN': () => 'main',
+    'HEADER': () => 'banner',
+    'FOOTER': () => 'contentinfo',
+    'ASIDE': () => 'complementary',
+    'ARTICLE': () => 'article',
+    'SECTION': (el) => el.getAttribute('aria-label') || el.getAttribute('aria-labelledby') ? 'region' : null,
+    'FORM': () => 'form',
+    'UL': () => 'list',
+    'OL': () => 'list',
+    'LI': () => 'listitem',
+    'H1': () => 'heading',
+    'H2': () => 'heading',
+    'H3': () => 'heading',
+    'H4': () => 'heading',
+    'H5': () => 'heading',
+    'H6': () => 'heading',
+    'TABLE': () => 'table',
+    'TR': () => 'row',
+    'TH': () => 'columnheader',
+    'TD': () => 'cell',
+    'DIALOG': () => 'dialog'
+  };
+
+  function getRole(el) {
+    // Explicit role takes precedence
+    const explicitRole = el.getAttribute('role');
+    if (explicitRole) return explicitRole;
+
+    // Check implicit role
+    const implicitFn = IMPLICIT_ROLES[el.tagName];
+    if (implicitFn) return implicitFn(el);
+
+    return null;
+  }
+
+  function getAccessibleName(el) {
+    // aria-label takes precedence
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel) return ariaLabel.trim();
+
+    // aria-labelledby
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const labels = labelledBy.split(' ')
+        .map(id => document.getElementById(id)?.textContent?.trim())
+        .filter(Boolean)
+        .join(' ');
+      if (labels) return labels;
+    }
+
+    // Input associated label
+    if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT') {
+      if (el.id) {
+        const label = document.querySelector('label[for="' + el.id + '"]');
+        if (label) return label.textContent?.trim();
+      }
+      // Check parent label
+      const parentLabel = el.closest('label');
+      if (parentLabel) {
+        const labelText = parentLabel.textContent?.replace(el.value || '', '')?.trim();
+        if (labelText) return labelText;
+      }
+    }
+
+    // Button/link content
+    if (el.tagName === 'BUTTON' || el.tagName === 'A') {
+      const text = el.textContent?.trim();
+      if (text) return text.substring(0, 100);
+    }
+
+    // Alt text for images
+    if (el.tagName === 'IMG') {
+      return el.alt || null;
+    }
+
+    // Title attribute fallback
+    if (el.title) return el.title.trim();
+
+    // Placeholder for inputs
+    if (el.placeholder) return null; // Return null, will add as /placeholder
+
+    return null;
+  }
+
+  function getStateFlags(el) {
+    const flags = [];
+
+    // Checked state
+    if (el.checked || el.getAttribute('aria-checked') === 'true') {
+      flags.push('checked');
+    }
+
+    // Disabled state
+    if (el.disabled || el.getAttribute('aria-disabled') === 'true') {
+      flags.push('disabled');
+    }
+
+    // Expanded state
+    if (el.getAttribute('aria-expanded') === 'true') {
+      flags.push('expanded');
+    }
+
+    // Selected state
+    if (el.selected || el.getAttribute('aria-selected') === 'true') {
+      flags.push('selected');
+    }
+
+    // Pressed state
+    if (el.getAttribute('aria-pressed') === 'true') {
+      flags.push('pressed');
+    }
+
+    // Required state
+    if (el.required || el.getAttribute('aria-required') === 'true') {
+      flags.push('required');
+    }
+
+    return flags;
+  }
+
+  function isVisible(el) {
+    const style = window.getComputedStyle(el);
+    if (style.display === 'none' || style.visibility === 'hidden') return false;
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+
+  function isInteractiveOrLandmark(role) {
+    return INTERACTIVE_ROLES.has(role) || LANDMARK_ROLES.has(role);
+  }
+
+  function shouldInclude(el) {
+    if (!isVisible(el)) return false;
+    const role = getRole(el);
+    if (!role) return false;
+    // Include interactive, landmarks, and structural elements
+    return isInteractiveOrLandmark(role) ||
+           role === 'heading' ||
+           role === 'img' ||
+           role === 'list' ||
+           role === 'listitem' ||
+           role === 'table' ||
+           role === 'row' ||
+           role === 'cell' ||
+           role === 'columnheader';
+  }
+
+  function assignRef(el, role) {
+    // Only assign refs to interactive elements
+    if (!INTERACTIVE_ROLES.has(role)) return null;
+
+    const ref = 'e' + refCounter++;
+    window.__chromeDevToolsRefs.set(ref, el);
+    return ref;
+  }
+
+  function buildYaml(el, indent = 0) {
+    const role = getRole(el);
+    if (!role) return '';
+
+    const prefix = '  '.repeat(indent) + '- ';
+    const lines = [];
+
+    // Build the line: role "name" [flags] [ref=eN]
+    let line = prefix + role;
+
+    const name = getAccessibleName(el);
+    if (name) {
+      line += ' "' + name.replace(/"/g, '\\\\"') + '"';
+    }
+
+    // Add heading level
+    if (role === 'heading') {
+      const level = el.tagName.match(/H(\\d)/)?.[1] || el.getAttribute('aria-level');
+      if (level) line += ' [level=' + level + ']';
+    }
+
+    // Add state flags
+    const flags = getStateFlags(el);
+    flags.forEach(flag => {
+      line += ' [' + flag + ']';
+    });
+
+    // Add ref for interactive elements
+    const ref = assignRef(el, role);
+    if (ref) {
+      line += ' [ref=' + ref + ']';
+    }
+
+    lines.push(line);
+
+    // Add metadata on subsequent lines
+    if (el.tagName === 'A' && el.href) {
+      lines.push('  '.repeat(indent + 1) + '/url: ' + el.href);
+    }
+    if (el.placeholder) {
+      lines.push('  '.repeat(indent + 1) + '/placeholder: "' + el.placeholder + '"');
+    }
+    if (el.tagName === 'INPUT' && el.value && el.type !== 'password') {
+      lines.push('  '.repeat(indent + 1) + '/value: "' + el.value.substring(0, 50) + '"');
+    }
+
+    // Process children
+    const children = Array.from(el.children);
+    children.forEach(child => {
+      const childYaml = buildYaml(child, indent + 1);
+      if (childYaml) lines.push(childYaml);
+    });
+
+    return lines.join('\\n');
+  }
+
+  function getSnapshot() {
+    const lines = [];
+
+    // Start from body
+    const children = Array.from(document.body.children);
+    children.forEach(child => {
+      const yaml = buildYaml(child, 0);
+      if (yaml) lines.push(yaml);
+    });
+
+    // Save ref counter for next snapshot
+    window.__chromeDevToolsRefCounter = refCounter;
+
+    return lines.join('\\n');
+  }
+
+  return getSnapshot();
+})();
+`;
+}
+
+async function ariaSnapshot() {
+  const args = parseArgs(process.argv.slice(2));
+
+  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'
+      });
+    }
+
+    // Get ARIA snapshot
+    const snapshot = await page.evaluate(getAriaSnapshotScript());
+
+    // Build result
+    const result = {
+      success: true,
+      url: page.url(),
+      title: await page.title(),
+      format: 'yaml',
+      snapshot: snapshot
+    };
+
+    // Output to file or stdout
+    if (args.output) {
+      const outputPath = args.output;
+
+      // Ensure snapshots directory exists
+      const outputDir = path.dirname(outputPath);
+      await fs.mkdir(outputDir, { recursive: true });
+
+      // Write YAML snapshot
+      await fs.writeFile(outputPath, snapshot, 'utf8');
+
+      outputJSON({
+        success: true,
+        output: path.resolve(outputPath),
+        url: page.url()
+      });
+    } else {
+      // Output to stdout
+      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);
+  }
+}
+
+ariaSnapshot();

package/.claude/skills/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 !== '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: 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/.claude/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/.claude/skills/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 !== '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: 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();