@everydaydevopsio/pilot 0.5.2 → 0.6.1

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/preflight.ts

@@ -0,0 +1,144 @@
+import { constants } from 'fs';
+import { access, mkdir } from 'fs/promises';
+import { request } from 'https';
+import {
+  findChromeExecutable,
+  findFreePort,
+  resolveUserDataDir
+} from './chrome-launcher.js';
+
+export interface LinuxCheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface LinuxCheckOptions {
+  headless: boolean;
+  chromePath?: string;
+  profileName: string;
+  checkNetwork?: boolean;
+}
+
+export function checkDisplay(headless: boolean): LinuxCheckResult {
+  if (headless) {
+    return {
+      name: 'display',
+      ok: true,
+      detail: 'not required in headless mode'
+    };
+  }
+  const display = process.env.DISPLAY || process.env.WAYLAND_DISPLAY;
+  return display
+    ? { name: 'display', ok: true, detail: display }
+    : {
+        name: 'display',
+        ok: false,
+        detail:
+          'headless:false requires DISPLAY or WAYLAND_DISPLAY; use a desktop session, xvfb-run, or headless:true'
+      };
+}
+
+export async function checkChrome(
+  chromePath?: string
+): Promise<LinuxCheckResult> {
+  try {
+    const resolved = findChromeExecutable(chromePath);
+    await access(resolved, constants.X_OK);
+    return { name: 'chrome', ok: true, detail: resolved };
+  } catch (error) {
+    return { name: 'chrome', ok: false, detail: String(error) };
+  }
+}
+
+export async function checkProfile(
+  profileName: string
+): Promise<LinuxCheckResult> {
+  let profileDir: string;
+  try {
+    profileDir = resolveUserDataDir(profileName);
+  } catch (error) {
+    return { name: 'profile', ok: false, detail: String(error) };
+  }
+
+  try {
+    await mkdir(profileDir, { recursive: true });
+    await access(profileDir, constants.R_OK | constants.W_OK | constants.X_OK);
+    return { name: 'profile', ok: true, detail: profileDir };
+  } catch (error) {
+    return {
+      name: 'profile',
+      ok: false,
+      detail: `${profileDir} is not writable: ${String(error)}; set XDG_DATA_HOME to a writable directory`
+    };
+  }
+}
+
+export async function checkLoopback(): Promise<LinuxCheckResult> {
+  try {
+    const port = await findFreePort();
+    return { name: 'loopback', ok: true, detail: `127.0.0.1:${port}` };
+  } catch (error) {
+    return {
+      name: 'loopback',
+      ok: false,
+      detail: `${String(error)}; Pilot requires permission to bind an ephemeral CDP port on 127.0.0.1`
+    };
+  }
+}
+
+export async function checkOutboundHttps(
+  timeoutMs = 5000,
+  requestFn: typeof request = request
+): Promise<LinuxCheckResult> {
+  return new Promise((resolve) => {
+    const req = requestFn(
+      'https://clients3.google.com/generate_204',
+      { method: 'HEAD', timeout: timeoutMs },
+      (response) => {
+        response.resume();
+        resolve({
+          name: 'network',
+          ok: response.statusCode === 204,
+          detail: `HTTPS status ${response.statusCode ?? 'unknown'} (expected 204)`
+        });
+      }
+    );
+    req.on('timeout', () =>
+      req.destroy(new Error(`timeout after ${timeoutMs}ms`))
+    );
+    req.on('error', (error) =>
+      resolve({ name: 'network', ok: false, detail: String(error) })
+    );
+    req.end();
+  });
+}
+
+export async function runLinuxChecks(
+  options: LinuxCheckOptions
+): Promise<LinuxCheckResult[]> {
+  if (process.platform !== 'linux') return [];
+  const checks = await Promise.all([
+    checkChrome(options.chromePath),
+    Promise.resolve(checkDisplay(options.headless)),
+    checkProfile(options.profileName),
+    checkLoopback()
+  ]);
+  if (options.checkNetwork !== false) checks.push(await checkOutboundHttps());
+  return checks;
+}
+
+export async function assertLinuxBrowserPrerequisites(
+  options: LinuxCheckOptions
+): Promise<void> {
+  if (process.platform !== 'linux') return;
+  const checks = await runLinuxChecks({ ...options, checkNetwork: false });
+  const failures = checks.filter((check) => !check.ok);
+  if (failures.length > 0) {
+    throw new Error(
+      `Linux browser preflight failed:\n${failures
+        .map((failure) => `- ${failure.name}: ${failure.detail}`)
+        .join('\n')}\nRun "pilot check" for complete diagnostics.`
+    );
+  }
+}

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 };
+}