@everydaydevopsio/pilot 0.5.0 → 0.6.0

package/src/browser/performance/analyze.ts

@@ -0,0 +1,298 @@
+import type { Client } from 'chrome-remote-interface';
+import type {
+  PerformanceSummary,
+  NavigationTiming,
+  LongTask,
+  SlowRequest,
+  LargeResource
+} from './types.js';
+
+const LONG_TASK_THRESHOLD_MS = 50;
+const SLOW_REQUEST_THRESHOLD_MS = 1000;
+const LARGE_RESOURCE_THRESHOLD_BYTES = 500 * 1024;
+const MAX_ENTRIES = 100;
+
+interface TraceEvent {
+  cat?: string;
+  name?: string;
+  ph?: string;
+  dur?: number;
+  ts?: number;
+  args?: Record<string, unknown>;
+}
+
+function findNavigationStart(events: TraceEvent[]): number {
+  for (const event of events) {
+    if (event.name === 'navigationStart' && event.ts) {
+      return event.ts;
+    }
+  }
+  // Fallback: earliest timestamp in the trace
+  let earliest = Infinity;
+  for (const event of events) {
+    if (event.ts && event.ts < earliest) {
+      earliest = event.ts;
+    }
+  }
+  return earliest === Infinity ? 0 : earliest;
+}
+
+function extractNavigationTiming(events: TraceEvent[]): NavigationTiming {
+  const timing: NavigationTiming = {};
+  const baseTs = findNavigationStart(events);
+
+  for (const event of events) {
+    if (event.name === 'domContentLoadedEventEnd' && event.ts !== undefined) {
+      timing.domContentLoaded = (event.ts - baseTs) / 1000;
+    }
+    if (event.name === 'loadEventEnd' && event.ts !== undefined) {
+      timing.load = (event.ts - baseTs) / 1000;
+    }
+    if (event.name === 'firstPaint' && event.ts !== undefined) {
+      timing.firstPaint = (event.ts - baseTs) / 1000;
+    }
+    if (event.name === 'firstContentfulPaint' && event.ts !== undefined) {
+      timing.firstContentfulPaint = (event.ts - baseTs) / 1000;
+    }
+  }
+
+  return timing;
+}
+
+function extractLongTasks(events: TraceEvent[]): LongTask[] {
+  const tasks: LongTask[] = [];
+
+  for (const event of events) {
+    if (
+      event.name === 'RunTask' &&
+      event.ph === 'X' &&
+      event.dur &&
+      event.dur / 1000 > LONG_TASK_THRESHOLD_MS
+    ) {
+      tasks.push({
+        name: event.name,
+        duration: Math.round(event.dur / 1000),
+        startTime: event.ts ? Math.round(event.ts / 1000) : 0
+      });
+    }
+  }
+
+  return tasks.sort((a, b) => b.duration - a.duration).slice(0, MAX_ENTRIES);
+}
+
+function extractSlowRequests(events: TraceEvent[]): SlowRequest[] {
+  const requests = new Map<
+    string,
+    { url: string; start: number; end?: number; method?: string }
+  >();
+
+  for (const event of events) {
+    if (event.name === 'ResourceSendRequest' && event.args) {
+      const data = event.args.data as
+        | { requestId?: string; url?: string; requestMethod?: string }
+        | undefined;
+      if (data?.requestId && data.url) {
+        requests.set(data.requestId, {
+          url: data.url,
+          start: event.ts ?? 0,
+          method: data.requestMethod
+        });
+      }
+    }
+    if (event.name === 'ResourceFinish' && event.args) {
+      const data = event.args.data as { requestId?: string } | undefined;
+      if (data?.requestId) {
+        const req = requests.get(data.requestId);
+        if (req) {
+          req.end = event.ts;
+        }
+      }
+    }
+  }
+
+  const slow: SlowRequest[] = [];
+  for (const req of requests.values()) {
+    if (req.end) {
+      const duration = Math.round((req.end - req.start) / 1000);
+      if (duration > SLOW_REQUEST_THRESHOLD_MS) {
+        slow.push({ url: req.url, duration, method: req.method });
+      }
+    }
+  }
+
+  return slow.sort((a, b) => b.duration - a.duration).slice(0, MAX_ENTRIES);
+}
+
+function extractLargeResources(events: TraceEvent[]): LargeResource[] {
+  // Build a requestId → URL map from ResourceSendRequest events
+  const urlMap = new Map<string, string>();
+  for (const event of events) {
+    if (event.name === 'ResourceSendRequest' && event.args) {
+      const data = event.args.data as
+        { requestId?: string; url?: string } | undefined;
+      if (data?.requestId && data.url) {
+        urlMap.set(data.requestId, data.url);
+      }
+    }
+  }
+
+  const resources: LargeResource[] = [];
+  for (const event of events) {
+    if (event.name === 'ResourceFinish' && event.args) {
+      const data = event.args.data as
+        { decodedBodyLength?: number; requestId?: string } | undefined;
+      if (
+        data?.decodedBodyLength &&
+        data.decodedBodyLength > LARGE_RESOURCE_THRESHOLD_BYTES
+      ) {
+        resources.push({
+          url: (data.requestId && urlMap.get(data.requestId)) || '',
+          size: data.decodedBodyLength
+        });
+      }
+    }
+  }
+
+  return resources.sort((a, b) => b.size - a.size).slice(0, MAX_ENTRIES);
+}
+
+function extractJsExecutionTime(events: TraceEvent[]): number {
+  let totalUs = 0;
+  for (const event of events) {
+    if (event.cat?.includes('v8') && event.ph === 'X' && event.dur) {
+      totalUs += event.dur;
+    }
+  }
+  return Math.round(totalUs / 1000);
+}
+
+export async function analyzePerformance(
+  client: Client,
+  traceEvents: unknown[]
+): Promise<PerformanceSummary> {
+  // Get current performance metrics from CDP
+  const { metrics: rawMetrics } = await client.Performance.getMetrics();
+  const metrics: Record<string, number> = {};
+  for (const m of rawMetrics) {
+    metrics[m.name] = m.value;
+  }
+
+  const events = traceEvents as TraceEvent[];
+
+  return {
+    navigationTiming: extractNavigationTiming(events),
+    metrics,
+    longTasks: extractLongTasks(events),
+    slowRequests: extractSlowRequests(events),
+    largeResources: extractLargeResources(events),
+    totalJsExecutionMs: extractJsExecutionTime(events),
+    traceEventCount: events.length
+  };
+}
+
+export function formatPerformanceSummary(summary: PerformanceSummary): string {
+  const lines: string[] = ['Performance Summary:\n'];
+
+  // Navigation timing — use explicit undefined checks so 0ms values are shown
+  const nt = summary.navigationTiming;
+  lines.push('Navigation Timing:');
+  if (nt.domContentLoaded !== undefined)
+    lines.push(`  DOMContentLoaded: ${Math.round(nt.domContentLoaded)}ms`);
+  if (nt.load !== undefined) lines.push(`  Load: ${Math.round(nt.load)}ms`);
+  if (nt.firstPaint !== undefined)
+    lines.push(`  First Paint: ${Math.round(nt.firstPaint)}ms`);
+  if (nt.firstContentfulPaint !== undefined)
+    lines.push(
+      `  First Contentful Paint: ${Math.round(nt.firstContentfulPaint)}ms`
+    );
+  if (
+    nt.domContentLoaded === undefined &&
+    nt.load === undefined &&
+    nt.firstPaint === undefined &&
+    nt.firstContentfulPaint === undefined
+  ) {
+    lines.push('  (no timing data captured)');
+  }
+
+  // Key metrics
+  const keyMetrics = [
+    'JSHeapUsedSize',
+    'JSHeapTotalSize',
+    'Documents',
+    'Frames',
+    'LayoutCount',
+    'RecalcStyleCount',
+    'ScriptDuration',
+    'TaskDuration'
+  ];
+  const hasMetrics = keyMetrics.some((k) => summary.metrics[k] !== undefined);
+  if (hasMetrics) {
+    lines.push('');
+    lines.push('Key Metrics:');
+    for (const k of keyMetrics) {
+      if (summary.metrics[k] !== undefined) {
+        let val = summary.metrics[k];
+        let unit = '';
+        if (k.includes('Size')) {
+          val = Math.round(val / 1024);
+          unit = ' KB';
+        } else if (k.includes('Duration')) {
+          val = Math.round(val * 1000);
+          unit = ' ms';
+        }
+        lines.push(`  ${k}: ${val}${unit}`);
+      }
+    }
+  }
+
+  // JS execution time
+  if (summary.totalJsExecutionMs) {
+    lines.push('');
+    lines.push(`Total JS Execution: ${summary.totalJsExecutionMs}ms`);
+  }
+
+  // Long tasks
+  if (summary.longTasks.length > 0) {
+    lines.push('');
+    lines.push(
+      `Long Tasks (>${LONG_TASK_THRESHOLD_MS}ms): ${summary.longTasks.length}`
+    );
+    for (const t of summary.longTasks.slice(0, 10)) {
+      lines.push(`  ${t.name}: ${t.duration}ms`);
+    }
+    if (summary.longTasks.length > 10) {
+      lines.push(`  ... and ${summary.longTasks.length - 10} more`);
+    }
+  }
+
+  // Slow requests
+  if (summary.slowRequests.length > 0) {
+    lines.push('');
+    lines.push(
+      `Slow Requests (>${SLOW_REQUEST_THRESHOLD_MS}ms): ${summary.slowRequests.length}`
+    );
+    for (const r of summary.slowRequests.slice(0, 10)) {
+      lines.push(`  ${r.method ?? 'GET'} ${r.url}: ${r.duration}ms`);
+    }
+  }
+
+  // Large resources
+  if (summary.largeResources.length > 0) {
+    lines.push('');
+    lines.push(
+      `Large Resources (>${Math.round(LARGE_RESOURCE_THRESHOLD_BYTES / 1024)}KB): ${summary.largeResources.length}`
+    );
+    for (const r of summary.largeResources.slice(0, 10)) {
+      lines.push(
+        `  ${Math.round(r.size / 1024)}KB ${r.url || '(unknown url)'}`
+      );
+    }
+  }
+
+  if (summary.traceEventCount) {
+    lines.push('');
+    lines.push(`Trace events processed: ${summary.traceEventCount}`);
+  }
+
+  return lines.join('\n');
+}

package/src/browser/performance/trace.ts

@@ -0,0 +1,60 @@
+import type { Client } from 'chrome-remote-interface';
+
+const MAX_TRACE_EVENTS = 100000;
+
+export interface TraceState {
+  tracing: boolean;
+  events: unknown[];
+  listenerClient: WeakRef<Client> | null;
+}
+
+export function createTraceState(): TraceState {
+  return { tracing: false, events: [], listenerClient: null };
+}
+
+export async function startTrace(
+  client: Client,
+  state: TraceState
+): Promise<void> {
+  if (state.tracing) {
+    throw new Error('Tracing is already active. Stop it first.');
+  }
+
+  state.events = [];
+  state.tracing = true;
+
+  // Only attach listener if not already attached to this client
+  if (state.listenerClient?.deref() !== client) {
+    client.Tracing.dataCollected((params) => {
+      if (state.events.length < MAX_TRACE_EVENTS) {
+        state.events.push(...params.value);
+      }
+    });
+    state.listenerClient = new WeakRef(client);
+  }
+
+  await client.Tracing.start({
+    categories:
+      'devtools.timeline,loading,v8,v8.execute,blink.user_timing,navigation',
+    transferMode: 'ReportEvents'
+  });
+}
+
+export async function stopTrace(
+  client: Client,
+  state: TraceState
+): Promise<unknown[]> {
+  if (!state.tracing) {
+    throw new Error('No active trace. Call start first.');
+  }
+
+  await new Promise<void>((resolve) => {
+    client.Tracing.tracingComplete(() => {
+      resolve();
+    });
+    void client.Tracing.end();
+  });
+
+  state.tracing = false;
+  return state.events;
+}

package/src/browser/performance/types.ts

@@ -0,0 +1,34 @@
+export interface NavigationTiming {
+  domContentLoaded?: number;
+  load?: number;
+  firstPaint?: number;
+  firstContentfulPaint?: number;
+}
+
+export interface LongTask {
+  name: string;
+  duration: number;
+  startTime: number;
+}
+
+export interface SlowRequest {
+  url: string;
+  duration: number;
+  method?: string;
+}
+
+export interface LargeResource {
+  url: string;
+  size: number;
+  type?: string;
+}
+
+export interface PerformanceSummary {
+  navigationTiming: NavigationTiming;
+  metrics: Record<string, number>;
+  longTasks: LongTask[];
+  slowRequests: SlowRequest[];
+  largeResources: LargeResource[];
+  totalJsExecutionMs?: number;
+  traceEventCount?: number;
+}

package/src/browser/security/origins.ts

@@ -0,0 +1,102 @@
+/**
+ * Origin allow/block list evaluation.
+ *
+ * Rules:
+ * - Block wins over allow.
+ * - Both empty = everything allowed.
+ * - Supports wildcard patterns: *.example.com matches sub.example.com
+ * - Patterns with a scheme (https://...) match the full origin.
+ * - Patterns without a scheme match the host (+port) only, any scheme.
+ */
+
+function getOriginList(envVar: string): string[] {
+  const env = process.env[envVar];
+  if (!env) return [];
+  return env
+    .split(',')
+    .map((p) => p.trim())
+    .filter((p) => p.length > 0);
+}
+
+function patternToRegex(pattern: string): RegExp {
+  // Escape regex special chars except *
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  // Replace * with regex wildcard
+  const regexStr = escaped.replace(/\*/g, '.*');
+  return new RegExp(`^${regexStr}$`, 'i');
+}
+
+function hasScheme(pattern: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(pattern);
+}
+
+function matchesPattern(
+  origin: string,
+  host: string,
+  pattern: string
+): boolean {
+  if (hasScheme(pattern)) {
+    // Pattern includes scheme — match against full origin
+    return patternToRegex(pattern).test(origin);
+  }
+  // Scheme-less pattern — match against host (+port) only
+  return patternToRegex(pattern).test(host);
+}
+
+function matchesAny(origin: string, host: string, patterns: string[]): boolean {
+  return patterns.some((p) => matchesPattern(origin, host, p));
+}
+
+export function extractOrigin(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.origin;
+  } catch {
+    return url;
+  }
+}
+
+export function extractHost(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return parsed.host;
+  } catch {
+    return url;
+  }
+}
+
+export interface OriginCheckResult {
+  allowed: boolean;
+  reason?: string;
+}
+
+export function checkOrigin(url: string): OriginCheckResult {
+  const blocked = getOriginList('PILOT_BLOCKED_ORIGINS');
+  const allowed = getOriginList('PILOT_ALLOWED_ORIGINS');
+
+  // Both empty = everything allowed
+  if (blocked.length === 0 && allowed.length === 0) {
+    return { allowed: true };
+  }
+
+  const origin = extractOrigin(url);
+  const host = extractHost(url);
+
+  // Block wins over allow
+  if (blocked.length > 0 && matchesAny(origin, host, blocked)) {
+    return {
+      allowed: false,
+      reason: `Origin "${origin}" is blocked by PILOT_BLOCKED_ORIGINS`
+    };
+  }
+
+  // If allow list exists, origin must match it
+  if (allowed.length > 0 && !matchesAny(origin, host, allowed)) {
+    return {
+      allowed: false,
+      reason: `Origin "${origin}" is not in PILOT_ALLOWED_ORIGINS`
+    };
+  }
+
+  return { allowed: true };
+}

package/src/browser/tabs.ts

@@ -0,0 +1,110 @@
+import CDP from 'chrome-remote-interface';
+import type { Client } from 'chrome-remote-interface';
+import { getLogger } from '../util/logger.js';
+import type { TabInfo } from './types.js';
+import type { ConnectionInfo } from './connection.js';
+import { enableDomains } from './connection.js';
+import { attachEventListeners } from './events.js';
+import type { ViewportConfig } from '../viewport.js';
+
+export async function listTabs(
+  connInfo: ConnectionInfo,
+  activeTargetId: string | null
+): Promise<TabInfo[]> {
+  const targets = await CDP.List({ host: connInfo.host, port: connInfo.port });
+  return targets
+    .filter((t) => t.type === 'page')
+    .map((t) => ({
+      targetId: t.id,
+      url: t.url,
+      title: t.title,
+      active: t.id === activeTargetId
+    }));
+}
+
+export async function createTab(
+  connInfo: ConnectionInfo,
+  url?: string
+): Promise<TabInfo> {
+  const encodedUrl = url ? encodeURI(url) : undefined;
+  const target = await CDP.New({
+    host: connInfo.host,
+    port: connInfo.port,
+    url: encodedUrl
+  });
+  return {
+    targetId: target.id,
+    url: target.url,
+    title: target.title,
+    active: false
+  };
+}
+
+export async function closeTab(
+  connInfo: ConnectionInfo,
+  targetId: string,
+  activeTargetId: string | null
+): Promise<void> {
+  if (targetId === activeTargetId) {
+    throw new Error(
+      'Cannot close the active tab. Switch to another tab first.'
+    );
+  }
+  await CDP.Close({ host: connInfo.host, port: connInfo.port, id: targetId });
+}
+
+export interface SwitchTabResult {
+  client: Client;
+  targetId: string;
+  url: string;
+}
+
+export async function switchTab(
+  connInfo: ConnectionInfo,
+  targetId: string,
+  currentTargetId: string | null,
+  currentClient: Client | null,
+  viewportConfig: ViewportConfig | null,
+  eventListenerOpts: Parameters<typeof attachEventListeners>[1]
+): Promise<SwitchTabResult> {
+  if (targetId === currentTargetId && currentClient) {
+    return {
+      client: currentClient,
+      targetId,
+      url: ''
+    };
+  }
+
+  // Verify the target exists
+  const targets = await CDP.List({
+    host: connInfo.host,
+    port: connInfo.port
+  });
+  const target = targets.find((t) => t.id === targetId && t.type === 'page');
+  if (!target) {
+    throw new Error(`No page tab found with targetId: ${targetId}`);
+  }
+
+  // Close old client connection (but not the tab)
+  if (currentClient) {
+    await currentClient.close();
+  }
+
+  // Connect to the new target
+  const client = await CDP({
+    host: connInfo.host,
+    port: connInfo.port,
+    target: targetId
+  });
+
+  await enableDomains(client, viewportConfig);
+  attachEventListeners(client, eventListenerOpts);
+
+  // Activate the tab in the browser UI
+  await client.Target.activateTarget({ targetId });
+
+  const logger = getLogger();
+  logger.info({ targetId, url: target.url }, 'Switched to tab');
+
+  return { client, targetId, url: target.url };
+}

package/src/browser/types.ts

@@ -0,0 +1,31 @@
+import type { Client } from 'chrome-remote-interface';
+
+export type BrowserEventCallback = (event: string, data: unknown) => void;
+
+export interface TabInfo {
+  targetId: string;
+  url: string;
+  title: string;
+  active: boolean;
+}
+
+export interface BrowserState {
+  client: Client | null;
+  targetId: string | null;
+  url: string | null;
+  connected: boolean;
+}
+
+export interface LaunchOptions {
+  headless?: boolean;
+  chromePath?: string;
+  profileName?: string;
+  viewport?: string;
+  viewportWidth?: number;
+  viewportHeight?: number;
+  deviceScaleFactor?: number;
+  responsive?: boolean;
+}
+
+export type SandboxDecision =
+  { disable: false } | { disable: true; reason: 'env_override' | 'root_user' };