@everydaydevopsio/pilot 0.5.0 → 0.6.0

package/src/browser/chrome-launcher.ts

@@ -0,0 +1,271 @@
+import { spawn, type ChildProcess } from 'child_process';
+import { existsSync, lstatSync, readlinkSync, unlinkSync } from 'fs';
+import * as net from 'net';
+import { homedir, hostname } from 'os';
+import { join } from 'path';
+import CDP from 'chrome-remote-interface';
+import { getLogger } from '../util/logger.js';
+import type { SandboxDecision } from './types.js';
+
+export const PROFILE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+
+export function sandboxDecision(): SandboxDecision {
+  const envOverride = process.env.PILOT_CHROME_NO_SANDBOX;
+  if (envOverride !== undefined) {
+    const truthy = envOverride === 'true' || envOverride === '1';
+    return truthy
+      ? { disable: true, reason: 'env_override' }
+      : { disable: false };
+  }
+  if (process.platform !== 'linux' && process.platform !== 'win32') {
+    return { disable: false };
+  }
+  if (process.getuid?.() === 0) {
+    return { disable: true, reason: 'root_user' };
+  }
+  return { disable: false };
+}
+
+export function shouldDisableSandbox(): boolean {
+  return sandboxDecision().disable;
+}
+
+export function resolveUserDataDir(profileName: string): string {
+  if (!PROFILE_NAME_RE.test(profileName)) {
+    throw new Error(
+      `Invalid profile name "${profileName}". Use only letters, digits, hyphens, and underscores.`
+    );
+  }
+  const xdgData =
+    process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share');
+  return join(xdgData, 'pilot', profileName);
+}
+
+function fileOrSymlinkExists(filePath: string): boolean {
+  try {
+    lstatSync(filePath);
+    return true;
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      return false;
+    }
+    return true;
+  }
+}
+
+export function extractLockPid(
+  lockPath: string
+): { pid: number; lockHost: string } | null {
+  try {
+    const stat = lstatSync(lockPath);
+    if (!stat.isSymbolicLink()) return null;
+    const target = readlinkSync(lockPath);
+    const lastDash = target.lastIndexOf('-');
+    if (lastDash === -1) return null;
+    const lockHost = target.slice(0, lastDash);
+    const pid = parseInt(target.slice(lastDash + 1), 10);
+    if (isNaN(pid) || pid <= 0) return null;
+    return { pid, lockHost };
+  } catch {
+    return null;
+  }
+}
+
+export function isProcessAlive(pid: number): boolean {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    return code !== 'ESRCH';
+  }
+}
+
+function removeStaleLocks(userDataDir: string): void {
+  for (const lockName of ['SingletonLock', 'lockfile']) {
+    try {
+      unlinkSync(join(userDataDir, lockName));
+    } catch (err: unknown) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (code !== 'ENOENT') throw err;
+    }
+  }
+  const logger = getLogger();
+  logger.warn(
+    { userDataDir },
+    'Cleaned up stale Chrome lock files from a previous crash'
+  );
+}
+
+export function isProfileLocked(userDataDir: string): boolean {
+  const singletonPath = join(userDataDir, 'SingletonLock');
+  const lockfilePath = join(userDataDir, 'lockfile');
+
+  const hasSingleton = fileOrSymlinkExists(singletonPath);
+  const hasLockfile = existsSync(lockfilePath);
+
+  if (!hasSingleton && !hasLockfile) return false;
+
+  const lockInfo = hasSingleton ? extractLockPid(singletonPath) : null;
+
+  if (!lockInfo) {
+    return true;
+  }
+
+  const currentHost = hostname();
+  if (lockInfo.lockHost !== currentHost) {
+    return true;
+  }
+
+  if (isProcessAlive(lockInfo.pid)) {
+    return true;
+  }
+
+  try {
+    removeStaleLocks(userDataDir);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+export function findChromeExecutable(override?: string): string {
+  if (override) return override;
+  const env = process.env.PILOT_CHROME_PATH;
+  if (env) return env;
+
+  const platform = process.platform;
+  const candidates: string[] =
+    platform === 'darwin'
+      ? [
+          '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+          '/Applications/Chromium.app/Contents/MacOS/Chromium'
+        ]
+      : platform === 'linux'
+        ? [
+            '/usr/bin/google-chrome-stable',
+            '/usr/bin/google-chrome',
+            '/usr/bin/chromium-browser',
+            '/usr/bin/chromium',
+            '/snap/bin/chromium'
+          ]
+        : platform === 'win32'
+          ? [
+              'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+              'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'
+            ]
+          : [];
+
+  for (const p of candidates) {
+    if (existsSync(p)) return p;
+  }
+  throw new Error(
+    `Chrome not found on ${platform}. Install Google Chrome or set PILOT_CHROME_PATH.`
+  );
+}
+
+export async function findFreePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as net.AddressInfo;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}
+
+export async function waitForChromeReady(
+  port: number,
+  timeoutMs = 10000
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await CDP.List({ host: '127.0.0.1', port });
+      return;
+    } catch {
+      await new Promise((r) => setTimeout(r, 200));
+    }
+  }
+  throw new Error(
+    `Chrome did not become ready on port ${port} within ${timeoutMs}ms`
+  );
+}
+
+export interface ChromeLaunchResult {
+  process: ChildProcess;
+  port: number;
+  userDataDir: string;
+}
+
+export function launchChrome(opts: {
+  chromePath: string;
+  port: number;
+  userDataDir: string;
+  headless: boolean;
+  windowWidth: number;
+  windowHeight: number;
+}): ChildProcess {
+  const logger = getLogger();
+
+  const args = [
+    `--remote-debugging-port=${opts.port}`,
+    `--user-data-dir=${opts.userDataDir}`,
+    `--window-size=${opts.windowWidth},${opts.windowHeight}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-default-apps',
+    '--disable-extensions'
+  ];
+
+  if (opts.headless) {
+    args.push('--headless', '--disable-gpu');
+  }
+
+  if (process.platform === 'linux') {
+    args.push(
+      '--disable-dev-shm-usage',
+      '--disable-software-rasterizer',
+      '--disable-breakpad',
+      '--password-store=basic',
+      '--use-mock-keychain'
+    );
+  }
+
+  const sandbox = sandboxDecision();
+  if (sandbox.disable) {
+    args.push('--no-sandbox');
+    logger.warn(
+      { reason: sandbox.reason },
+      'Chrome will run with --no-sandbox. The renderer sandbox is disabled; any page the agent visits runs with the same privileges as this process. Set PILOT_CHROME_NO_SANDBOX=false to override, or run as a non-root user to keep the sandbox enabled.'
+    );
+  }
+
+  logger.info(
+    {
+      chromePath: opts.chromePath,
+      port: opts.port,
+      headless: opts.headless,
+      sandbox: sandbox.disable ? 'disabled' : 'enabled'
+    },
+    'Launching Chrome'
+  );
+
+  return spawn(opts.chromePath, args, {
+    stdio: ['ignore', 'ignore', 'pipe'],
+    detached: false
+  });
+}
+
+export function cleanupLockFiles(userDataDir: string): void {
+  for (const lockName of ['SingletonLock', 'lockfile']) {
+    try {
+      unlinkSync(join(userDataDir, lockName));
+    } catch {
+      // lock file may not exist — that's fine
+    }
+  }
+}

package/src/browser/connection.ts

@@ -0,0 +1,84 @@
+import CDP from 'chrome-remote-interface';
+import type { Client } from 'chrome-remote-interface';
+import { getLogger } from '../util/logger.js';
+import type { Config } from '../util/config.js';
+import { type ViewportConfig, applyViewport } from '../viewport.js';
+
+export interface ConnectionInfo {
+  host: string;
+  port: number;
+}
+
+export async function connectToChrome(opts: {
+  host: string;
+  port: number;
+}): Promise<{ client: Client; targetId: string; url: string }> {
+  const targets = await CDP.List({ host: opts.host, port: opts.port });
+
+  const pageTarget = targets.find((t) => t.type === 'page');
+  if (!pageTarget) {
+    throw new Error('No page target found in Chrome');
+  }
+
+  const client = await CDP({
+    host: opts.host,
+    port: opts.port,
+    target: pageTarget.id
+  });
+
+  return {
+    client,
+    targetId: pageTarget.id,
+    url: pageTarget.url
+  };
+}
+
+export async function enableDomains(
+  client: Client,
+  viewportConfig: ViewportConfig | null
+): Promise<void> {
+  await Promise.all([
+    client.Network.enable({}),
+    client.Console.enable(),
+    client.Page.enable(),
+    client.Runtime.enable()
+  ]);
+
+  if (viewportConfig) {
+    await applyViewport(client, viewportConfig);
+  }
+}
+
+export function getConnectionInfo(
+  config: Config,
+  launchedCdpPort: number | null
+): ConnectionInfo {
+  return {
+    host: launchedCdpPort ? '127.0.0.1' : config.cdpHost,
+    port: launchedCdpPort ?? config.cdpPort
+  };
+}
+
+export function scheduleReconnect(
+  config: Config,
+  state: {
+    destroyed: boolean;
+    retryTimer: ReturnType<typeof setTimeout> | null;
+    retryMs: number;
+  },
+  reconnectFn: () => void
+): ReturnType<typeof setTimeout> | null {
+  if (state.destroyed) return null;
+  if (state.retryTimer) return state.retryTimer;
+
+  const logger = getLogger();
+  logger.debug({ retryMs: state.retryMs }, 'Scheduling reconnect');
+
+  const timer = setTimeout(() => {
+    state.retryTimer = null;
+    state.retryMs = Math.min(state.retryMs * 2, config.cdpMaxRetryMs);
+    reconnectFn();
+  }, state.retryMs);
+  timer.unref();
+  return timer;
+}

package/src/browser/events.ts

@@ -0,0 +1,121 @@
+import type { Client } from 'chrome-remote-interface';
+
+/**
+ * Normalize CDP console level names to match ConsoleLevel.
+ * CDP uses "warning" for console.warn; normalize to "warn".
+ */
+function normLevel(raw: string): string {
+  return raw === 'warning' ? 'warn' : raw;
+}
+
+export function attachEventListeners(
+  client: Client,
+  opts: {
+    emit: (event: string, data: unknown) => void;
+    onDisconnect: () => void;
+    pendingNetworkRequests: Set<string>;
+    checkNetworkIdle: () => void;
+    onFrameNavigated: (url: string) => void;
+  }
+): void {
+  client.on('disconnect', () => {
+    opts.onDisconnect();
+  });
+
+  // Console events
+  client.Runtime.consoleAPICalled((params) => {
+    const text = params.args
+      .map((a) =>
+        a.value !== undefined ? String(a.value) : (a.description ?? '')
+      )
+      .join(' ');
+    opts.emit('console_message', {
+      level: normLevel(params.type),
+      text,
+      url: params.stackTrace?.callFrames?.[0]?.url ?? '',
+      lineNumber: params.stackTrace?.callFrames?.[0]?.lineNumber ?? 0,
+      timestamp: Date.now()
+    });
+  });
+
+  client.Console.messageAdded((params) => {
+    opts.emit('console_message', {
+      level: normLevel(params.message.level),
+      text: params.message.text,
+      url: params.message.url ?? '',
+      lineNumber: params.message.line ?? 0,
+      timestamp: Date.now()
+    });
+  });
+
+  // Runtime exceptions
+  client.Runtime.exceptionThrown((params) => {
+    const ex = params.exceptionDetails;
+    const message = ex.exception?.description ?? ex.text ?? 'Unknown exception';
+    const frames = ex.stackTrace?.callFrames?.map((f) => ({
+      url: f.url,
+      functionName: f.functionName,
+      lineNumber: f.lineNumber,
+      columnNumber: f.columnNumber
+    }));
+
+    const topFrame = frames?.[0];
+    opts.emit('console_message', {
+      level: 'error',
+      text: message,
+      url: ex.url ?? topFrame?.url ?? '',
+      lineNumber: ex.lineNumber ?? topFrame?.lineNumber ?? 0,
+      columnNumber: ex.columnNumber ?? topFrame?.columnNumber,
+      timestamp: Date.now(),
+      stackFrames: frames,
+      isException: true
+    });
+  });
+
+  // Network events
+  client.Network.requestWillBeSent((params) => {
+    opts.pendingNetworkRequests.add(params.requestId);
+    opts.emit('network_request', {
+      requestId: params.requestId,
+      url: params.request.url,
+      method: params.request.method,
+      timestamp: Date.now()
+    });
+  });
+
+  client.Network.responseReceived((params) => {
+    opts.pendingNetworkRequests.delete(params.requestId);
+    opts.checkNetworkIdle();
+    opts.emit('network_response', {
+      requestId: params.requestId,
+      url: params.response.url,
+      status: params.response.status,
+      mimeType: params.response.mimeType,
+      fromCache: params.response.fromDiskCache ?? false,
+      timestamp: Date.now()
+    });
+  });
+
+  client.Network.loadingFailed((params) => {
+    opts.pendingNetworkRequests.delete(params.requestId);
+    opts.checkNetworkIdle();
+    opts.emit('network_failed', {
+      requestId: params.requestId,
+      url: '',
+      errorText: params.errorText,
+      timestamp: Date.now()
+    });
+  });
+
+  client.Network.loadingFinished((params) => {
+    opts.pendingNetworkRequests.delete(params.requestId);
+    opts.checkNetworkIdle();
+  });
+
+  // Page navigation
+  client.Page.frameNavigated((params) => {
+    if (params.frame.parentId === undefined) {
+      opts.onFrameNavigated(params.frame.url);
+    }
+  });
+}

package/src/browser/index.ts

@@ -0,0 +1,20 @@
+// Re-export all public types and classes from the browser module
+export { BrowserManager } from './browser-manager.js';
+export type {
+  BrowserEventCallback,
+  TabInfo,
+  BrowserState,
+  LaunchOptions,
+  SandboxDecision
+} from './types.js';
+export {
+  PROFILE_NAME_RE,
+  sandboxDecision,
+  shouldDisableSandbox,
+  resolveUserDataDir,
+  extractLockPid,
+  isProcessAlive,
+  isProfileLocked,
+  findChromeExecutable,
+  findFreePort
+} from './chrome-launcher.js';

package/src/browser/inspect/element-ref.ts

@@ -0,0 +1,68 @@
+import type { StaleElementError } from './types.js';
+
+interface RefEntry {
+  backendNodeId: number;
+}
+
+export class ElementRefMap {
+  private generation = 0;
+  private refs = new Map<string, RefEntry>();
+  private counter = 0;
+
+  getGeneration(): number {
+    return this.generation;
+  }
+
+  /**
+   * Clear refs for a new snapshot within the same document.
+   * Does not increment generation.
+   */
+  resetRefs(): void {
+    this.refs.clear();
+    this.counter = 0;
+  }
+
+  /**
+   * Invalidate all refs due to navigation or DOM replacement.
+   * Increments generation so stale refs are detected.
+   */
+  invalidate(): void {
+    this.refs.clear();
+    this.counter = 0;
+    this.generation++;
+  }
+
+  nextRef(): string {
+    this.counter++;
+    return `e${this.counter}`;
+  }
+
+  set(ref: string, backendNodeId: number): void {
+    this.refs.set(ref, { backendNodeId });
+  }
+
+  resolve(ref: string): number {
+    const entry = this.refs.get(ref);
+    if (!entry) {
+      throw this.staleError(ref);
+    }
+    return entry.backendNodeId;
+  }
+
+  has(ref: string): boolean {
+    return this.refs.has(ref);
+  }
+
+  size(): number {
+    return this.refs.size;
+  }
+
+  private staleError(ref: string): StaleElementError & Error {
+    const err = new Error(
+      `Element ref "${ref}" is stale. The page has navigated or the DOM has been replaced. Take a new snapshot to get fresh refs.`
+    ) as StaleElementError & Error;
+    err.code = 'STALE_ELEMENT_REFERENCE';
+    err.ref = ref;
+    return err;
+  }
+}