browser-commander 0.2.0

package/src/bindings.js

@@ -0,0 +1,298 @@
+/**
+ * Browser Commander - Function Binding Helpers
+ * This module provides helper functions for binding page, engine, and log to library functions.
+ */
+
+import { wait, evaluate, safeEvaluate } from './utilities/wait.js';
+import { getUrl, unfocusAddressBar } from './utilities/url.js';
+import {
+  waitForUrlStabilization,
+  goto,
+  waitForNavigation,
+  waitForPageReady,
+  waitAfterAction,
+} from './browser/navigation.js';
+import {
+  createPlaywrightLocator,
+  getLocatorOrElement,
+  waitForLocatorOrElement,
+  waitForVisible,
+  locator,
+} from './elements/locators.js';
+import {
+  querySelector,
+  querySelectorAll,
+  findByText,
+  normalizeSelector,
+  waitForSelector,
+  withTextSelectorSupport,
+} from './elements/selectors.js';
+import { isVisible, isEnabled, count } from './elements/visibility.js';
+import {
+  textContent,
+  inputValue,
+  getAttribute,
+  getInputValue,
+  logElementInfo,
+} from './elements/content.js';
+import {
+  scrollIntoView,
+  needsScrolling,
+  scrollIntoViewIfNeeded,
+} from './interactions/scroll.js';
+import { clickElement, clickButton } from './interactions/click.js';
+import {
+  checkIfElementEmpty,
+  performFill,
+  fillTextArea,
+} from './interactions/fill.js';
+import {
+  waitForUrlCondition,
+  installClickListener,
+  checkAndClearFlag,
+  findToggleButton,
+} from './high-level/universal-logic.js';
+
+/**
+ * Create bound functions for a browser commander instance
+ * @param {Object} options - Configuration
+ * @param {Object} options.page - Browser page object
+ * @param {string} options.engine - Engine type ('playwright' or 'puppeteer')
+ * @param {Function} options.log - Logger instance
+ * @param {boolean} options.verbose - Enable verbose logging
+ * @param {Object} options.navigationManager - NavigationManager instance (optional)
+ * @param {Object} options.networkTracker - NetworkTracker instance (optional)
+ * @returns {Object} - Object containing all bound functions
+ */
+export function createBoundFunctions(options = {}) {
+  const {
+    page,
+    engine,
+    log,
+    verbose = false,
+    navigationManager,
+    networkTracker,
+  } = options;
+
+  // Create bound helper functions that inject page, engine, log
+  // Wait function now automatically gets abort signal from navigation manager
+  const waitBound = (opts) => {
+    const abortSignal = navigationManager
+      ? navigationManager.getAbortSignal()
+      : null;
+    return wait({ ...opts, log, abortSignal: opts.abortSignal || abortSignal });
+  };
+  const evaluateBound = (opts) => evaluate({ ...opts, page, engine });
+  const safeEvaluateBound = (opts) => safeEvaluate({ ...opts, page, engine });
+  const getUrlBound = () => getUrl({ page });
+  const unfocusAddressBarBound = (opts = {}) =>
+    unfocusAddressBar({ ...opts, page });
+
+  // Bound navigation - with NavigationManager integration
+  const waitForUrlStabilizationBound = (opts) =>
+    waitForUrlStabilization({
+      ...opts,
+      page,
+      log,
+      wait: waitBound,
+      navigationManager,
+    });
+  const gotoBound = (opts) =>
+    goto({
+      ...opts,
+      page,
+      waitForUrlStabilization: waitForUrlStabilizationBound,
+      navigationManager,
+    });
+  const waitForNavigationBound = (opts) =>
+    waitForNavigation({
+      ...opts,
+      page,
+      navigationManager,
+    });
+  const waitForPageReadyBound = (opts) =>
+    waitForPageReady({
+      ...opts,
+      page,
+      navigationManager,
+      networkTracker,
+      log,
+      wait: waitBound,
+    });
+  const waitAfterActionBound = (opts) =>
+    waitAfterAction({
+      ...opts,
+      page,
+      navigationManager,
+      networkTracker,
+      log,
+      wait: waitBound,
+    });
+
+  // Bound locators
+  const createPlaywrightLocatorBound = (opts) =>
+    createPlaywrightLocator({ ...opts, page });
+  const getLocatorOrElementBound = (opts) =>
+    getLocatorOrElement({ ...opts, page, engine });
+  const waitForLocatorOrElementBound = (opts) =>
+    waitForLocatorOrElement({ ...opts, page, engine });
+  const waitForVisibleBound = (opts) => waitForVisible({ ...opts, engine });
+  const locatorBound = (opts) => locator({ ...opts, page, engine });
+
+  // Bound selectors
+  const querySelectorBound = (opts) => querySelector({ ...opts, page, engine });
+  const querySelectorAllBound = (opts) =>
+    querySelectorAll({ ...opts, page, engine });
+  const findByTextBound = (opts) => findByText({ ...opts, engine });
+  const normalizeSelectorBound = (opts) =>
+    normalizeSelector({ ...opts, page, engine });
+  const waitForSelectorBound = (opts) =>
+    waitForSelector({ ...opts, page, engine });
+
+  // Bound visibility
+  const isVisibleBound = (opts) => isVisible({ ...opts, page, engine });
+  const isEnabledBound = (opts) => isEnabled({ ...opts, page, engine });
+  const countBound = (opts) => count({ ...opts, page, engine });
+
+  // Bound content
+  const textContentBound = (opts) => textContent({ ...opts, page, engine });
+  const inputValueBound = (opts) => inputValue({ ...opts, page, engine });
+  const getAttributeBound = (opts) => getAttribute({ ...opts, page, engine });
+  const getInputValueBound = (opts) => getInputValue({ ...opts, page, engine });
+  const logElementInfoBound = (opts) =>
+    logElementInfo({ ...opts, page, engine, log });
+
+  // Bound scroll
+  const scrollIntoViewBound = (opts) =>
+    scrollIntoView({ ...opts, page, engine });
+  const needsScrollingBound = (opts) =>
+    needsScrolling({ ...opts, page, engine });
+  const scrollIntoViewIfNeededBound = (opts) =>
+    scrollIntoViewIfNeeded({ ...opts, page, engine, wait: waitBound, log });
+
+  // Bound click - now navigation-aware
+  const clickElementBound = (opts) => clickElement({ ...opts, engine, log });
+  const clickButtonBound = (opts) =>
+    clickButton({
+      ...opts,
+      page,
+      engine,
+      wait: waitBound,
+      log,
+      verbose,
+      navigationManager,
+      networkTracker,
+    });
+
+  // Bound fill
+  const checkIfElementEmptyBound = (opts) =>
+    checkIfElementEmpty({ ...opts, page, engine });
+  const performFillBound = (opts) => performFill({ ...opts, page, engine });
+  const fillTextAreaBound = (opts) =>
+    fillTextArea({ ...opts, page, engine, wait: waitBound, log });
+
+  // Bound high-level
+  const waitForUrlConditionBound = (opts) =>
+    waitForUrlCondition({
+      ...opts,
+      getUrl: getUrlBound,
+      wait: waitBound,
+      evaluate: evaluateBound,
+    });
+  const installClickListenerBound = (opts) =>
+    installClickListener({ ...opts, evaluate: evaluateBound });
+  const checkAndClearFlagBound = (opts) =>
+    checkAndClearFlag({ ...opts, evaluate: evaluateBound });
+  const findToggleButtonBound = (opts) =>
+    findToggleButton({
+      ...opts,
+      count: countBound,
+      findByText: findByTextBound,
+    });
+
+  // Wrap functions with text selector support
+  const fillTextAreaWrapped = withTextSelectorSupport(
+    fillTextAreaBound,
+    engine,
+    page
+  );
+  const clickButtonWrapped = withTextSelectorSupport(
+    clickButtonBound,
+    engine,
+    page
+  );
+  const getAttributeWrapped = withTextSelectorSupport(
+    getAttributeBound,
+    engine,
+    page
+  );
+  const isVisibleWrapped = withTextSelectorSupport(
+    isVisibleBound,
+    engine,
+    page
+  );
+  const isEnabledWrapped = withTextSelectorSupport(
+    isEnabledBound,
+    engine,
+    page
+  );
+  const textContentWrapped = withTextSelectorSupport(
+    textContentBound,
+    engine,
+    page
+  );
+  const inputValueWrapped = withTextSelectorSupport(
+    inputValueBound,
+    engine,
+    page
+  );
+
+  return {
+    // Helper functions (now public)
+    createPlaywrightLocator: createPlaywrightLocatorBound,
+    getLocatorOrElement: getLocatorOrElementBound,
+    waitForLocatorOrElement: waitForLocatorOrElementBound,
+    scrollIntoView: scrollIntoViewBound,
+    scrollIntoViewIfNeeded: scrollIntoViewIfNeededBound,
+    needsScrolling: needsScrollingBound,
+    checkIfElementEmpty: checkIfElementEmptyBound,
+    performFill: performFillBound,
+    logElementInfo: logElementInfoBound,
+    normalizeSelector: normalizeSelectorBound,
+    withTextSelectorSupport: (fn) => withTextSelectorSupport(fn, engine, page),
+    waitForVisible: waitForVisibleBound,
+    clickElement: clickElementBound,
+    getInputValue: getInputValueBound,
+    unfocusAddressBar: unfocusAddressBarBound,
+
+    // Main API functions
+    wait: waitBound,
+    fillTextArea: fillTextAreaWrapped,
+    clickButton: clickButtonWrapped,
+    evaluate: evaluateBound,
+    safeEvaluate: safeEvaluateBound,
+    waitForSelector: waitForSelectorBound,
+    querySelector: querySelectorBound,
+    querySelectorAll: querySelectorAllBound,
+    waitForUrlStabilization: waitForUrlStabilizationBound,
+    goto: gotoBound,
+    getUrl: getUrlBound,
+    waitForNavigation: waitForNavigationBound,
+    waitForPageReady: waitForPageReadyBound,
+    waitAfterAction: waitAfterActionBound,
+    getAttribute: getAttributeWrapped,
+    isVisible: isVisibleWrapped,
+    isEnabled: isEnabledWrapped,
+    count: countBound,
+    textContent: textContentWrapped,
+    inputValue: inputValueWrapped,
+    locator: locatorBound,
+    findByText: findByTextBound,
+
+    // Universal High-Level Functions (DRY Principle)
+    waitForUrlCondition: waitForUrlConditionBound,
+    installClickListener: installClickListenerBound,
+    checkAndClearFlag: checkAndClearFlagBound,
+    findToggleButton: findToggleButtonBound,
+  };
+}

package/src/browser/launcher.js

@@ -0,0 +1,93 @@
+import path from 'path';
+import os from 'os';
+import { CHROME_ARGS } from '../core/constants.js';
+import { disableTranslateInPreferences } from '../core/preferences.js';
+
+/**
+ * Launch browser with default configuration
+ * @param {Object} options - Configuration options
+ * @param {string} options.engine - Browser automation engine: 'playwright' or 'puppeteer'
+ * @param {string} options.userDataDir - Path to user data directory
+ * @param {boolean} options.headless - Run in headless mode (default: false)
+ * @param {number} options.slowMo - Slow down operations by ms (default: 150 for Playwright, 0 for Puppeteer)
+ * @param {boolean} options.verbose - Enable verbose logging (default: false)
+ * @returns {Promise<Object>} - Object with browser and page
+ */
+export async function launchBrowser(options = {}) {
+  const {
+    engine = 'playwright',
+    userDataDir = path.join(os.homedir(), '.hh-apply', `${engine}-data`),
+    headless = false,
+    slowMo = engine === 'playwright' ? 150 : 0,
+    verbose = false,
+  } = options;
+
+  if (!['playwright', 'puppeteer'].includes(engine)) {
+    throw new Error(
+      `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
+    );
+  }
+
+  // Set environment variables to suppress warnings
+  process.env.GOOGLE_API_KEY = 'no';
+  process.env.GOOGLE_DEFAULT_CLIENT_ID = 'no';
+  process.env.GOOGLE_DEFAULT_CLIENT_SECRET = 'no';
+
+  // Disable translate in Preferences
+  await disableTranslateInPreferences({ userDataDir });
+
+  if (verbose) {
+    console.log(`🚀 Launching browser with ${engine} engine...`);
+  }
+
+  let browser;
+  let page;
+
+  if (engine === 'playwright') {
+    const { chromium } = await import('playwright');
+    browser = await chromium.launchPersistentContext(userDataDir, {
+      headless,
+      slowMo,
+      chromiumSandbox: true,
+      viewport: null,
+      args: CHROME_ARGS,
+      ignoreDefaultArgs: ['--enable-automation'],
+    });
+    page = browser.pages()[0];
+  } else {
+    const puppeteer = await import('puppeteer');
+    browser = await puppeteer.default.launch({
+      headless,
+      defaultViewport: null,
+      args: ['--start-maximized', ...CHROME_ARGS],
+      userDataDir,
+    });
+    const pages = await browser.pages();
+    page = pages[0];
+  }
+
+  if (verbose) {
+    console.log(`✅ Browser launched with ${engine} engine`);
+  }
+
+  // Unfocus address bar automatically after browser launch
+  // Using page.bringToFront() - confirmed working solution
+  try {
+    // Wait for the browser to fully initialize
+    await new Promise((r) => setTimeout(r, 500));
+
+    // Bring page to front - this removes focus from address bar
+    await page.bringToFront();
+
+    if (verbose) {
+      console.log('✅ Address bar unfocused automatically');
+    }
+  } catch (error) {
+    // Ignore errors - this is just a UX improvement
+    if (verbose) {
+      console.log('⚠️  Could not unfocus address bar:', error.message);
+    }
+  }
+
+  return { browser, page };
+}