eyeballs-cli 0.1.0

package/src/core.ts

@@ -0,0 +1,438 @@
+import { chromium, type Browser, type Page } from 'playwright';
+import pixelmatch from 'pixelmatch';
+import { PNG, type PNGWithMetadata } from 'pngjs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { randomUUID } from 'crypto';
+
+// --- Types ---
+
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+export interface Region {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface CaptureResult {
+  buffer: Buffer;
+  width: number;
+  height: number;
+  loadTimeMs: number;
+}
+
+export interface DiffResult {
+  changed: boolean;
+  diffPercent: number;
+  threshold: number;
+  diffBuffer?: Buffer;
+}
+
+export interface Watch {
+  id: string;
+  url: string;
+  viewport: Viewport;
+  mode: 'pixel';
+  config: {
+    threshold: number;
+    region: Region | null;
+  };
+  baselinePath: string;
+  createdAt: string;
+  lastCheckAt: string | null;
+  lastDiffPercent: number;
+}
+
+export interface WatchesFile {
+  watches: Watch[];
+}
+
+export interface CheckResult {
+  changed: boolean;
+  diffPercent: number;
+  threshold: number;
+  message: string;
+  screenshotBuffer: Buffer;
+  diffBuffer?: Buffer;
+  watch: Watch;
+}
+
+// --- Error types ---
+
+export type EyeballsErrorCode =
+  | 'TIMEOUT'
+  | 'LOAD_FAILED'
+  | 'INVALID_URL'
+  | 'BROWSER_NOT_INSTALLED'
+  | 'BROWSER_VERSION_MISMATCH'
+  | 'BROWSER_LAUNCH_FAILED'
+  | 'STORAGE_FAILED'
+  | 'NOT_FOUND';
+
+export class EyeballsError extends Error {
+  constructor(
+    public code: EyeballsErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'EyeballsError';
+  }
+}
+
+// --- Storage ---
+
+const EYEBALLS_DIR = join(homedir(), '.eyeballs');
+const SCREENSHOTS_DIR = join(EYEBALLS_DIR, 'screenshots');
+const WATCHES_FILE = join(EYEBALLS_DIR, 'watches.json');
+
+function ensureDirs(): void {
+  try {
+    mkdirSync(EYEBALLS_DIR, { recursive: true });
+    mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+  } catch {
+    throw new EyeballsError('STORAGE_FAILED', 'Could not create ~/.eyeballs directory');
+  }
+}
+
+export function loadWatches(): WatchesFile {
+  ensureDirs();
+  if (!existsSync(WATCHES_FILE)) {
+    return { watches: [] };
+  }
+  try {
+    const raw = readFileSync(WATCHES_FILE, 'utf-8');
+    return JSON.parse(raw) as WatchesFile;
+  } catch {
+    return { watches: [] };
+  }
+}
+
+function saveWatches(data: WatchesFile): void {
+  ensureDirs();
+  try {
+    writeFileSync(WATCHES_FILE, JSON.stringify(data, null, 2));
+  } catch {
+    throw new EyeballsError('STORAGE_FAILED', 'Could not write watches.json');
+  }
+}
+
+function saveScreenshot(id: string, suffix: string, buffer: Buffer): string {
+  ensureDirs();
+  const filename = `${id}-${suffix}.png`;
+  const filepath = join(SCREENSHOTS_DIR, filename);
+  try {
+    writeFileSync(filepath, buffer);
+  } catch {
+    throw new EyeballsError('STORAGE_FAILED', 'Could not write screenshot');
+  }
+  return filepath;
+}
+
+// --- Browser ---
+
+let browser: Browser | null = null;
+
+async function getBrowser(): Promise<Browser> {
+  if (browser && browser.isConnected()) {
+    return browser;
+  }
+  try {
+    browser = await chromium.launch();
+    return browser;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('Executable doesn\'t exist') || msg.includes('browserType.launch')) {
+      if (msg.includes('Chromium') && msg.includes('revision')) {
+        throw new EyeballsError(
+          'BROWSER_VERSION_MISMATCH',
+          'Chromium version mismatch. Run: npx playwright install chromium',
+        );
+      }
+      throw new EyeballsError(
+        'BROWSER_NOT_INSTALLED',
+        'Run: npx playwright install chromium',
+      );
+    }
+    throw new EyeballsError('BROWSER_LAUNCH_FAILED', `Chromium cannot start: ${msg}`);
+  }
+}
+
+export async function shutdownBrowser(): Promise<void> {
+  if (browser) {
+    await browser.close().catch(() => {});
+    browser = null;
+  }
+}
+
+// Cleanup on exit
+process.on('exit', () => {
+  browser?.close().catch(() => {});
+});
+process.on('SIGINT', async () => {
+  await shutdownBrowser();
+  process.exit(0);
+});
+process.on('SIGTERM', async () => {
+  await shutdownBrowser();
+  process.exit(0);
+});
+
+// --- URL validation ---
+
+function validateUrl(url: string): void {
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    throw new EyeballsError('INVALID_URL', 'URL must start with http:// or https://');
+  }
+  try {
+    new URL(url);
+  } catch {
+    throw new EyeballsError('INVALID_URL', `Invalid URL: ${url}`);
+  }
+}
+
+// --- Capture ---
+
+export async function capture(
+  url: string,
+  viewport: Viewport = { width: 1280, height: 720 },
+): Promise<CaptureResult> {
+  validateUrl(url);
+
+  const b = await getBrowser();
+  const context = await b.newContext({ viewport });
+  const page: Page = await context.newPage();
+
+  const start = Date.now();
+  try {
+    const response = await page.goto(url, {
+      waitUntil: 'networkidle',
+      timeout: 30000,
+    });
+
+    if (response) {
+      const status = response.status();
+      if (status >= 400) {
+        throw new EyeballsError('LOAD_FAILED', `Page returned ${status}`);
+      }
+    }
+
+    // Wait for paint to settle
+    await page.waitForTimeout(2000);
+
+    const buffer = await page.screenshot({ type: 'png' });
+    const loadTimeMs = Date.now() - start;
+
+    return {
+      buffer: Buffer.from(buffer),
+      width: viewport.width,
+      height: viewport.height,
+      loadTimeMs,
+    };
+  } catch (err) {
+    if (err instanceof EyeballsError) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('Timeout') || msg.includes('timeout')) {
+      throw new EyeballsError('TIMEOUT', 'Page failed to load within 30s');
+    }
+    throw new EyeballsError('LOAD_FAILED', `Failed to load page: ${msg}`);
+  } finally {
+    await page.close().catch(() => {});
+    await context.close().catch(() => {});
+  }
+}
+
+// --- Diff ---
+
+export function diff(
+  baseline: Buffer,
+  current: Buffer,
+  threshold: number = 5,
+  region?: Region | null,
+): DiffResult {
+  let img1: PNGWithMetadata | PNG = PNG.sync.read(baseline);
+  let img2: PNGWithMetadata | PNG = PNG.sync.read(current);
+
+  // Region crop if specified
+  if (region) {
+    img1 = cropPng(img1, region);
+    img2 = cropPng(img2, region);
+  }
+
+  // Ensure same dimensions
+  if (img1.width !== img2.width || img1.height !== img2.height) {
+    return {
+      changed: true,
+      diffPercent: 100,
+      threshold,
+      diffBuffer: undefined,
+    };
+  }
+
+  const { width, height } = img1;
+  const diffPng = new PNG({ width, height });
+
+  const numDiffPixels = pixelmatch(
+    img1.data as unknown as Uint8Array,
+    img2.data as unknown as Uint8Array,
+    diffPng.data as unknown as Uint8Array,
+    width,
+    height,
+    { threshold: 0.1 },
+  );
+
+  const totalPixels = width * height;
+  const diffPercent = (numDiffPixels / totalPixels) * 100;
+  const changed = diffPercent > threshold;
+
+  return {
+    changed,
+    diffPercent: Math.round(diffPercent * 100) / 100,
+    threshold,
+    diffBuffer: changed ? Buffer.from(PNG.sync.write(diffPng)) : undefined,
+  };
+}
+
+function cropPng(png: PNG, region: Region): PNG {
+  const cropped = new PNG({ width: region.width, height: region.height });
+  for (let y = 0; y < region.height; y++) {
+    for (let x = 0; x < region.width; x++) {
+      const srcIdx = ((region.y + y) * png.width + (region.x + x)) << 2;
+      const dstIdx = (y * region.width + x) << 2;
+      cropped.data[dstIdx] = png.data[srcIdx];
+      cropped.data[dstIdx + 1] = png.data[srcIdx + 1];
+      cropped.data[dstIdx + 2] = png.data[srcIdx + 2];
+      cropped.data[dstIdx + 3] = png.data[srcIdx + 3];
+    }
+  }
+  return cropped;
+}
+
+// --- Check URL (baseline + diff) ---
+
+export async function checkUrl(options: {
+  url: string;
+  viewport?: Viewport;
+  threshold?: number;
+  region?: Region | null;
+  resetBaseline?: boolean;
+}): Promise<CheckResult> {
+  const { url, viewport = { width: 1280, height: 720 }, threshold = 5, region = null, resetBaseline = false } = options;
+
+  const data = loadWatches();
+  let watch = data.watches.find((w) => w.url === url);
+
+  // Capture current screenshot
+  const result = await capture(url, viewport);
+
+  // Reset baseline
+  if (watch && resetBaseline) {
+    const baselinePath = saveScreenshot(watch.id, 'baseline', result.buffer);
+    watch.baselinePath = baselinePath;
+    watch.viewport = viewport;
+    watch.config = { threshold, region };
+    watch.lastCheckAt = new Date().toISOString();
+    watch.lastDiffPercent = 0;
+    saveWatches(data);
+
+    return {
+      changed: false,
+      diffPercent: 0,
+      threshold,
+      message: 'Baseline updated',
+      screenshotBuffer: result.buffer,
+      watch,
+    };
+  }
+
+  // No baseline yet, store it
+  if (!watch) {
+    const id = randomUUID().slice(0, 8);
+    const baselinePath = saveScreenshot(id, 'baseline', result.buffer);
+
+    watch = {
+      id,
+      url,
+      viewport,
+      mode: 'pixel',
+      config: { threshold, region },
+      baselinePath,
+      createdAt: new Date().toISOString(),
+      lastCheckAt: new Date().toISOString(),
+      lastDiffPercent: 0,
+    };
+
+    data.watches.push(watch);
+    saveWatches(data);
+
+    return {
+      changed: false,
+      diffPercent: 0,
+      threshold,
+      message: 'Baseline captured',
+      screenshotBuffer: result.buffer,
+      watch,
+    };
+  }
+
+  // Diff against baseline
+  const baseline = readFileSync(watch.baselinePath);
+  const diffResult = diff(baseline, result.buffer, threshold, region);
+
+  // Save current screenshot
+  saveScreenshot(watch.id, 'latest', result.buffer);
+  if (diffResult.diffBuffer) {
+    saveScreenshot(watch.id, 'diff', diffResult.diffBuffer);
+  }
+
+  watch.lastCheckAt = new Date().toISOString();
+  watch.lastDiffPercent = diffResult.diffPercent;
+  saveWatches(data);
+
+  return {
+    changed: diffResult.changed,
+    diffPercent: diffResult.diffPercent,
+    threshold,
+    message: diffResult.changed
+      ? `Changed: ${diffResult.diffPercent}% pixels differ (threshold: ${threshold}%)`
+      : `No change: ${diffResult.diffPercent}% pixels differ (threshold: ${threshold}%)`,
+    screenshotBuffer: result.buffer,
+    diffBuffer: diffResult.diffBuffer,
+    watch,
+  };
+}
+
+// --- List / Remove watches ---
+
+export function listWatches(): Watch[] {
+  return loadWatches().watches;
+}
+
+export function removeWatch(id: string): void {
+  const data = loadWatches();
+  const idx = data.watches.findIndex((w) => w.id === id);
+
+  if (idx === -1) {
+    throw new EyeballsError('NOT_FOUND', `Watch ${id} not found`);
+  }
+
+  data.watches.splice(idx, 1);
+  saveWatches(data);
+
+  // Clean up screenshot files for this watch
+  try {
+    const files = readdirSync(SCREENSHOTS_DIR);
+    for (const file of files) {
+      if (file.startsWith(`${id}-`)) {
+        unlinkSync(join(SCREENSHOTS_DIR, file));
+      }
+    }
+  } catch {
+    // Best effort cleanup
+  }
+}

package/src/mcp.ts

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {
+  capture,
+  checkUrl,
+  listWatches,
+  removeWatch,
+  EyeballsError,
+  type Viewport,
+  type Region,
+} from './core.js';
+
+const tools = [
+  {
+    name: 'screenshot',
+    description:
+      'Take a screenshot of a web page. Returns the image and metadata (width, height, load time).',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL to screenshot (must start with http:// or https://)',
+        },
+        viewport: {
+          type: 'object',
+          description: 'Viewport size (default: 1280x720)',
+          properties: {
+            width: { type: 'number' },
+            height: { type: 'number' },
+          },
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'check_url',
+    description:
+      'Check a URL for visual changes. On first call, captures a baseline screenshot. On subsequent calls, compares against the baseline and reports the pixel diff percentage. Use reset_baseline to accept the current state as the new baseline.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        url: {
+          type: 'string',
+          description: 'URL to check (must start with http:// or https://)',
+        },
+        viewport: {
+          type: 'object',
+          description: 'Viewport size (default: 1280x720). Stored with baseline for consistent diffs.',
+          properties: {
+            width: { type: 'number' },
+            height: { type: 'number' },
+          },
+        },
+        threshold: {
+          type: 'number',
+          description: 'Percentage of pixels that must differ to count as "changed" (default: 5)',
+        },
+        region: {
+          type: 'object',
+          description: 'Crop region to compare (exclude headers, ads, etc.)',
+          properties: {
+            x: { type: 'number' },
+            y: { type: 'number' },
+            width: { type: 'number' },
+            height: { type: 'number' },
+          },
+        },
+        reset_baseline: {
+          type: 'boolean',
+          description: 'Set to true to accept the current page as the new baseline',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'list_watches',
+    description: 'List all stored baselines (watched URLs) and their last check status.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {},
+    },
+  },
+  {
+    name: 'remove_watch',
+    description: 'Remove a stored baseline and its screenshots.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        id: {
+          type: 'string',
+          description: 'The watch ID to remove (from list_watches)',
+        },
+      },
+      required: ['id'],
+    },
+  },
+];
+
+async function handleTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<Array<{ type: string; text?: string; data?: string; mimeType?: string }>> {
+  switch (name) {
+    case 'screenshot': {
+      const result = await capture(
+        args.url as string,
+        args.viewport as Viewport | undefined,
+      );
+      const base64 = result.buffer.toString('base64');
+      return [
+        {
+          type: 'image',
+          data: base64,
+          mimeType: 'image/png',
+        },
+        {
+          type: 'text',
+          text: JSON.stringify({
+            width: result.width,
+            height: result.height,
+            loadTimeMs: result.loadTimeMs,
+            base64Length: base64.length,
+          }),
+        },
+      ];
+    }
+
+    case 'check_url': {
+      const result = await checkUrl({
+        url: args.url as string,
+        viewport: args.viewport as Viewport | undefined,
+        threshold: args.threshold as number | undefined,
+        region: args.region as Region | undefined,
+        resetBaseline: args.reset_baseline as boolean | undefined,
+      });
+
+      const content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> = [];
+
+      // Return the current screenshot
+      content.push({
+        type: 'image',
+        data: result.screenshotBuffer.toString('base64'),
+        mimeType: 'image/png',
+      });
+
+      // If there's a diff image, return it too
+      if (result.diffBuffer) {
+        content.push({
+          type: 'image',
+          data: result.diffBuffer.toString('base64'),
+          mimeType: 'image/png',
+        });
+      }
+
+      // Text summary
+      content.push({
+        type: 'text',
+        text: JSON.stringify({
+          changed: result.changed,
+          diffPercent: result.diffPercent,
+          threshold: result.threshold,
+          message: result.message,
+          watchId: result.watch.id,
+          url: result.watch.url,
+        }),
+      });
+
+      return content;
+    }
+
+    case 'list_watches': {
+      const watches = listWatches();
+      if (watches.length === 0) {
+        return [{ type: 'text', text: 'No watches. Use check_url to start monitoring a URL.' }];
+      }
+      return [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            watches.map((w) => ({
+              id: w.id,
+              url: w.url,
+              viewport: w.viewport,
+              threshold: w.config.threshold,
+              region: w.config.region,
+              lastCheckAt: w.lastCheckAt,
+              lastDiffPercent: w.lastDiffPercent,
+              createdAt: w.createdAt,
+            })),
+            null,
+            2,
+          ),
+        },
+      ];
+    }
+
+    case 'remove_watch': {
+      removeWatch(args.id as string);
+      return [{ type: 'text', text: `Watch ${args.id} removed.` }];
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+const server = new Server(
+  { name: 'eyeballs', version: '0.1.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    const content = await handleTool(name, (args ?? {}) as Record<string, unknown>);
+    return { content };
+  } catch (error) {
+    const message =
+      error instanceof EyeballsError
+        ? `${error.code}: ${error.message}`
+        : `Error: ${(error as Error).message}`;
+    return {
+      content: [{ type: 'text', text: message }],
+      isError: true,
+    };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('eyeballs MCP server running');

package/src/types/pixelmatch.d.ts

@@ -0,0 +1,20 @@
+declare module 'pixelmatch' {
+  interface PixelmatchOptions {
+    threshold?: number;
+    includeAA?: boolean;
+    alpha?: number;
+    aaColor?: [number, number, number];
+    diffColor?: [number, number, number];
+    diffColorAlt?: [number, number, number];
+    diffMask?: boolean;
+  }
+
+  export default function pixelmatch(
+    img1: Buffer | Uint8Array | Uint8ClampedArray,
+    img2: Buffer | Uint8Array | Uint8ClampedArray,
+    output: Buffer | Uint8Array | Uint8ClampedArray | null,
+    width: number,
+    height: number,
+    options?: PixelmatchOptions
+  ): number;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test"]
+}