bruniai 0.1.2

package/README.md

@@ -0,0 +1,75 @@
+# bruniai
+
+AI-powered visual regression testing tool - core comparison library.
+
+This package provides the core comparison functionality for visual regression testing. It can be used standalone or as a dependency for building custom integrations (e.g., MCP servers, Next.js apps, etc.).
+
+## Installation
+
+```bash
+npm install bruniai
+```
+
+## Usage
+
+```typescript
+import { compareUrls } from "bruniai";
+
+const result = await compareUrls({
+  baseUrl: "https://example.com",
+  previewUrl: "https://preview.example.com",
+  page: "/contact"
+});
+
+console.log(result.status); // "pass" | "fail" | "warning" | "none"
+console.log(result.visual_analysis);
+console.log(result.images.base_screenshot);
+```
+
+## API
+
+### `compareUrls(input: CompareUrlsInput): Promise<CompareUrlsOutput>`
+
+Performs a visual comparison between two URLs.
+
+**Parameters:**
+- `baseUrl` (string): Base/reference URL to compare against
+- `previewUrl` (string): Preview/changed URL to analyze
+- `page` (string, optional): Page path to compare (default: "/")
+- `prNumber` (string, optional): PR number for metadata
+- `repository` (string, optional): Repository name for metadata
+- `prTitle` (string, optional): PR title for context
+- `prDescription` (string, optional): PR description for context
+
+**Returns:**
+- `status`: Overall comparison status ("pass" | "fail" | "warning" | "none")
+- `visual_analysis`: Detailed visual analysis result from AI
+- `sections_analysis`: Formatted sections analysis text
+- `images`: Object containing paths to generated screenshots and diff images
+
+## Requirements
+
+- Node.js 18+
+- OpenAI API key (set as `OPENAI_API_KEY` environment variable)
+
+## Development
+
+### Building
+
+First, build the parent package to generate the dist files:
+
+```bash
+cd ../..
+npm run build
+```
+
+Then build this package:
+
+```bash
+npm run build
+```
+
+## License
+
+MIT
+

package/dist/compare-urls.d.ts

@@ -0,0 +1,28 @@
+import type { CompareUrlsInput, CompareUrlsOutput } from "./types.js";
+/**
+ * Compare two URLs visually and return analysis results.
+ *
+ * This function performs a complete visual comparison workflow:
+ * - Creates a temporary directory for images
+ * - Initializes and manages Stagehand browser automation
+ * - Takes screenshots of both URLs
+ * - Generates diff images
+ * - Analyzes sections structure
+ * - Performs AI-powered visual analysis
+ * - Captures section screenshots
+ *
+ * @param input - Comparison input parameters
+ * @returns Complete analysis results with image paths
+ *
+ * @example
+ * ```typescript
+ * const result = await compareUrls({
+ *   baseUrl: "https://example.com",
+ *   previewUrl: "https://preview.example.com",
+ *   page: "/contact"
+ * });
+ * console.log(result.status); // "pass" | "fail" | "warning" | "none"
+ * ```
+ */
+export declare function compareUrls(input: CompareUrlsInput): Promise<CompareUrlsOutput>;
+//# sourceMappingURL=compare-urls.d.ts.map

package/dist/compare-urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-urls.d.ts","sourceRoot":"","sources":["../src/compare-urls.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKtE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,iBAAiB,CAAC,CA4D5B"}

package/dist/compare-urls.js

@@ -0,0 +1,82 @@
+import { Stagehand } from "@browserbasehq/stagehand";
+import { performComparison } from "../../../dist/comparison/core.js";
+import { join } from "path";
+import { mkdirSync, existsSync } from "fs";
+import { tmpdir } from "os";
+/**
+ * Compare two URLs visually and return analysis results.
+ *
+ * This function performs a complete visual comparison workflow:
+ * - Creates a temporary directory for images
+ * - Initializes and manages Stagehand browser automation
+ * - Takes screenshots of both URLs
+ * - Generates diff images
+ * - Analyzes sections structure
+ * - Performs AI-powered visual analysis
+ * - Captures section screenshots
+ *
+ * @param input - Comparison input parameters
+ * @returns Complete analysis results with image paths
+ *
+ * @example
+ * ```typescript
+ * const result = await compareUrls({
+ *   baseUrl: "https://example.com",
+ *   previewUrl: "https://preview.example.com",
+ *   page: "/contact"
+ * });
+ * console.log(result.status); // "pass" | "fail" | "warning" | "none"
+ * ```
+ */
+export async function compareUrls(input) {
+    const { baseUrl, previewUrl, page = "/" } = input;
+    // Create temporary directory for images.
+    const imagesDir = join(tmpdir(), `bruniai-${Date.now()}`);
+    if (!existsSync(imagesDir)) {
+        mkdirSync(imagesDir, { recursive: true });
+    }
+    // Initialize Stagehand.
+    const stagehand = new Stagehand({
+        env: "LOCAL",
+        localBrowserLaunchOptions: {
+            headless: true,
+        },
+    });
+    try {
+        await stagehand.init();
+        // Perform the core comparison.
+        const result = await performComparison({
+            stagehand,
+            baseUrl,
+            previewUrl,
+            page,
+            imagesDir,
+            prNumber: input.prNumber,
+            repository: input.repository,
+            prTitle: input.prTitle,
+            prDescription: input.prDescription,
+        });
+        // Build output structure.
+        const output = {
+            status: result.visual_analysis.status,
+            visual_analysis: result.visual_analysis,
+            sections_analysis: result.sections_analysis,
+            images: {
+                base_screenshot: result.base_screenshot,
+                preview_screenshot: result.preview_screenshot,
+                diff_image: result.diff_image,
+                section_screenshots: Object.keys(result.section_screenshots).length > 0
+                    ? Object.fromEntries(Object.entries(result.section_screenshots).map(([key, value]) => [
+                        key,
+                        { base: value.base, preview: value.preview },
+                    ]))
+                    : undefined,
+            },
+        };
+        return output;
+    }
+    finally {
+        await stagehand.close();
+    }
+}
+//# sourceMappingURL=compare-urls.js.map

package/dist/compare-urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-urls.js","sourceRoot":"","sources":["../src/compare-urls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAuB;IAEvB,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC;IAElD,yCAAyC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,WAAW,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,wBAAwB;IACxB,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC;QAC9B,GAAG,EAAE,OAAO;QACZ,yBAAyB,EAAE;YACzB,QAAQ,EAAE,IAAI;SACf;KACF,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;QAEvB,+BAA+B;QAC/B,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;YACrC,SAAS;YACT,OAAO;YACP,UAAU;YACV,IAAI;YACJ,SAAS;YACT,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,aAAa,EAAE,KAAK,CAAC,aAAa;SACnC,CAAC,CAAC;QAEH,0BAA0B;QAC1B,MAAM,MAAM,GAAsB;YAChC,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,MAAM;YACrC,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;YAC3C,MAAM,EAAE;gBACN,eAAe,EAAE,MAAM,CAAC,eAAe;gBACvC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;gBAC7C,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,mBAAmB,EACjB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,MAAM,GAAG,CAAC;oBAChD,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAC5C,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;wBAChB,GAAG;wBACH,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE;qBAC7C,CACF,CACF;oBACH,CAAC,CAAC,SAAS;aAChB;SACF,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * BruniAI - AI-powered visual regression testing tool.
+ *
+ * Core comparison library for visual regression testing.
+ * Provides a simple API to compare two URLs and analyze visual differences.
+ */
+export { compareUrls } from "./compare-urls.js";
+export type { CompareUrlsInput, CompareUrlsOutput, ComparisonImages, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * BruniAI - AI-powered visual regression testing tool.
+ *
+ * Core comparison library for visual regression testing.
+ * Provides a simple API to compare two URLs and analyze visual differences.
+ */
+export { compareUrls } from "./compare-urls.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+import type { VisualAnalysisResult } from "../../../dist/vision/types.js";
+/**
+ * Input parameters for compareUrls function.
+ */
+export interface CompareUrlsInput {
+    /** Base/reference URL to compare against. */
+    baseUrl: string;
+    /** Preview/changed URL to analyze. */
+    previewUrl: string;
+    /** Page path to compare (e.g., "/" or "/about"). Defaults to "/". */
+    page?: string;
+    /** Optional PR number for metadata. */
+    prNumber?: string;
+    /** Optional repository name for metadata. */
+    repository?: string;
+    /** Optional PR title for context. */
+    prTitle?: string;
+    /** Optional PR description for context. */
+    prDescription?: string;
+}
+/**
+ * Image paths returned from comparison.
+ */
+export interface ComparisonImages {
+    /** Path to base screenshot. */
+    base_screenshot: string;
+    /** Path to preview screenshot. */
+    preview_screenshot: string;
+    /** Path to diff image. */
+    diff_image: string;
+    /** Section screenshots keyed by section ID. */
+    section_screenshots?: Record<string, {
+        base: string;
+        preview: string;
+    }>;
+}
+/**
+ * Output structure for compareUrls function.
+ */
+export interface CompareUrlsOutput {
+    /** Overall comparison status. */
+    status: "pass" | "fail" | "warning" | "none";
+    /** Visual analysis result from AI. */
+    visual_analysis: VisualAnalysisResult;
+    /** Formatted sections analysis text. */
+    sections_analysis: string;
+    /** Generated images from comparison. */
+    images: ComparisonImages;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzE;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IAC7C,sCAAsC;IACtC,eAAe,EAAE,oBAAoB,CAAC;IACtC,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE,gBAAgB,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "bruniai",
+  "version": "0.1.2",
+  "type": "module",
+  "description": "AI-powered visual regression testing tool - core comparison library",
+  "author": "Joao Garin",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@browserbasehq/stagehand": "^3.0.1",
+    "dotenv": "^16.0.0",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.42.1",
+    "pngjs": "^7.0.0",
+    "sharp": "^0.34.5",
+    "uuid": "^10.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "@types/uuid": "^10.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.5.4"
+  },
+  "peerDependencies": {
+    "@browserbasehq/stagehand": "^3.0.1"
+  }
+}