@pixeyedev/core 0.4.0

package/dist/ci.d.ts

@@ -0,0 +1,14 @@
+export interface CIEnvironment {
+    provider: string;
+    commit: string;
+    branch: string;
+    baseBranch?: string;
+    prNumber?: number;
+    repository?: string;
+}
+/**
+ * Try to detect the base branch using git merge-base.
+ * Checks common default branch names (main, master, develop).
+ */
+export declare const detectBaseBranchFromGit: () => string | undefined;
+export declare const detectCIEnvironment: () => CIEnvironment | null;

package/dist/ci.js

@@ -0,0 +1,70 @@
+import { execFileSync } from 'node:child_process';
+const detectGitHubActions = () => {
+    if (!process.env.GITHUB_ACTIONS) {
+        return null;
+    }
+    const commit = process.env.GITHUB_SHA;
+    const branch = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME;
+    const runId = process.env.GITHUB_RUN_ID;
+    if (!commit || !branch || !runId) {
+        return null;
+    }
+    const prRaw = process.env.PIXEYE_PR;
+    const prNumber = prRaw ? parseInt(prRaw, 10) : undefined;
+    // PR target branch: GITHUB_BASE_REF is set on pull_request events
+    const baseBranch = process.env.GITHUB_BASE_REF || undefined;
+    return {
+        provider: 'github-actions',
+        commit,
+        branch,
+        baseBranch,
+        prNumber: prNumber && !isNaN(prNumber) ? prNumber : undefined,
+        repository: process.env.GITHUB_REPOSITORY
+    };
+};
+const detectGitLabCI = () => {
+    if (!process.env.GITLAB_CI) {
+        return null;
+    }
+    const commit = process.env.CI_COMMIT_SHA;
+    const branch = process.env.CI_COMMIT_REF_NAME;
+    const pipelineId = process.env.CI_PIPELINE_ID;
+    if (!commit || !branch || !pipelineId) {
+        return null;
+    }
+    const mrIid = process.env.CI_MERGE_REQUEST_IID;
+    return {
+        provider: 'gitlab-ci',
+        commit,
+        branch,
+        baseBranch: process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME || undefined,
+        prNumber: mrIid ? parseInt(mrIid, 10) : undefined,
+        repository: undefined
+    };
+};
+/**
+ * Try to detect the base branch using git merge-base.
+ * Checks common default branch names (main, master, develop).
+ */
+export const detectBaseBranchFromGit = () => {
+    const candidates = ['main', 'master', 'develop'];
+    for (const candidate of candidates) {
+        try {
+            execFileSync('git', ['rev-parse', '--verify', `origin/${candidate}`], { stdio: 'ignore' });
+            execFileSync('git', ['merge-base', 'HEAD', `origin/${candidate}`], { stdio: 'ignore' });
+            return candidate;
+        }
+        catch {
+            // Branch doesn't exist or no common ancestor
+        }
+    }
+    return undefined;
+};
+export const detectCIEnvironment = () => {
+    const ci = detectGitHubActions() ?? detectGitLabCI() ?? null;
+    // If CI detected but no baseBranch, try git merge-base
+    if (ci && !ci.baseBranch) {
+        ci.baseBranch = detectBaseBranchFromGit();
+    }
+    return ci;
+};

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import type { CreateBuildResponse, ListBuildsResponse, PipelineFinalizeResponse, PresignUploadResponse, ScreenshotManifestEntry, SubmitShardResponse } from '@pixeyedev/shared';
+export declare class PixeyeError extends Error {
+    status: number;
+    path: string;
+    body: string;
+    constructor(status: number, path: string, body: string);
+}
+export interface PixeyeClientOptions {
+    serverUrl: string;
+    token: string;
+}
+export declare class PixeyeClient {
+    private serverUrl;
+    private token;
+    constructor(options: PixeyeClientOptions);
+    private request;
+    createBuild(opts: {
+        projectToken: string;
+        commitSha: string;
+        branch: string;
+        prNumber?: number;
+        shardCount?: number;
+        partial?: boolean;
+        metadata?: Record<string, unknown>;
+        runner?: string;
+        baseBranch?: string;
+        authorName?: string;
+        commitMessage?: string;
+    }): Promise<CreateBuildResponse>;
+    presignUpload(opts: {
+        buildId: string;
+        hashes: string[];
+        formats?: Record<string, 'png' | 'webp'>;
+    }): Promise<PresignUploadResponse>;
+    uploadFile(presignedUrl: string, buffer: Buffer, contentType: string): Promise<void>;
+    submitShard(opts: {
+        buildId: string;
+        shardIndex: number;
+        screenshots: ScreenshotManifestEntry[];
+    }): Promise<SubmitShardResponse>;
+    listBuilds(opts: {
+        commitSha: string;
+        branch: string;
+    }): Promise<ListBuildsResponse>;
+    finalizePipeline(pipelineId: string): Promise<PipelineFinalizeResponse>;
+    checkFileExists(hash: string): Promise<boolean>;
+    uploadLegacy(buffer: Buffer, hash: string, filename: string): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,112 @@
+import { CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
+export class PixeyeError extends Error {
+    status;
+    path;
+    body;
+    constructor(status, path, body) {
+        super(`Pixeye API ${path} failed (${status}): ${body}`);
+        this.status = status;
+        this.path = path;
+        this.body = body;
+        this.name = 'PixeyeError';
+    }
+}
+export class PixeyeClient {
+    serverUrl;
+    token;
+    constructor(options) {
+        this.serverUrl = options.serverUrl.replace(/\/$/, '');
+        this.token = options.token;
+    }
+    async request(path, options = {}) {
+        const url = `${this.serverUrl}${path}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.token}`,
+                ...options.headers
+            }
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new PixeyeError(response.status, path, body);
+        }
+        return response.json();
+    }
+    async createBuild(opts) {
+        const body = { ...opts };
+        if (opts.runner) {
+            body.metadata = { ...(opts.metadata ?? {}), runner: opts.runner };
+        }
+        const raw = await this.request('/api/v1/builds', {
+            method: 'POST',
+            body: JSON.stringify(body)
+        });
+        return CreateBuildResponseSchema.parse(raw);
+    }
+    async presignUpload(opts) {
+        const raw = await this.request('/api/v1/upload/presign', {
+            method: 'POST',
+            body: JSON.stringify({
+                token: this.token,
+                buildId: opts.buildId,
+                hashes: opts.hashes,
+                ...(opts.formats && Object.keys(opts.formats).length > 0 ? { formats: opts.formats } : {})
+            })
+        });
+        return PresignUploadResponseSchema.parse(raw);
+    }
+    async uploadFile(presignedUrl, buffer, contentType) {
+        const res = await fetch(presignedUrl, {
+            method: 'PUT',
+            body: new Uint8Array(buffer),
+            headers: { 'Content-Type': contentType }
+        });
+        if (!res.ok) {
+            throw new PixeyeError(res.status, presignedUrl, await res.text());
+        }
+    }
+    async submitShard(opts) {
+        const raw = await this.request(`/api/v1/builds/${opts.buildId}/shards`, {
+            method: 'POST',
+            body: JSON.stringify({
+                shardIndex: opts.shardIndex,
+                screenshots: opts.screenshots,
+                projectToken: this.token
+            })
+        });
+        return SubmitShardResponseSchema.parse(raw);
+    }
+    async listBuilds(opts) {
+        const params = new URLSearchParams({
+            commitSha: opts.commitSha,
+            branch: opts.branch
+        });
+        const raw = await this.request(`/api/v1/builds?${params}`);
+        return ListBuildsResponseSchema.parse(raw);
+    }
+    async finalizePipeline(pipelineId) {
+        const raw = await this.request(`/api/v1/pipelines/${pipelineId}/finalize`, {
+            method: 'POST'
+        });
+        return PipelineFinalizeResponseSchema.parse(raw);
+    }
+    async checkFileExists(hash) {
+        const result = await this.request(`/api/v1/upload/${hash}?token=${encodeURIComponent(this.token)}`);
+        return result.exists;
+    }
+    async uploadLegacy(buffer, hash, filename) {
+        const blob = new Blob([new Uint8Array(buffer)], { type: 'image/png' });
+        const formData = new FormData();
+        formData.append('file', blob, filename);
+        formData.append('hash', hash);
+        formData.append('token', this.token);
+        const url = `${this.serverUrl}/api/v1/upload`;
+        const response = await fetch(url, { method: 'POST', body: formData });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new PixeyeError(response.status, '/api/v1/upload', body);
+        }
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,38 @@
+export interface PixeyeConfig {
+    server?: string;
+    token?: string;
+}
+export interface ProjectConfig {
+    server: string;
+    token: string;
+    screenshotDir?: string;
+}
+export interface EnvConfig {
+    server?: string;
+    token?: string;
+    commit?: string;
+    branch?: string;
+    pr?: number;
+    runner?: string;
+}
+export interface ResolvedConfig {
+    serverUrl: string;
+    token: string;
+    commitSha: string;
+    branch: string;
+    prNumber?: number;
+    runner?: string;
+    baseBranch?: string;
+    shardIndex: number;
+    shardTotal: number;
+}
+export declare const readGlobalConfig: () => Promise<PixeyeConfig>;
+export declare const writeGlobalConfig: (config: PixeyeConfig) => Promise<void>;
+export declare const readProjectConfig: (cwd: string) => Promise<ProjectConfig | null>;
+export declare const writeProjectConfig: (cwd: string, config: ProjectConfig) => Promise<void>;
+export declare const readEnvConfig: () => EnvConfig;
+/** @internal Exported for testing */
+export declare const parseYamlLike: (content: string) => ProjectConfig;
+export declare const resolveConfig: (overrides?: Partial<ResolvedConfig> & {
+    cwd?: string;
+}) => Promise<ResolvedConfig>;

package/dist/config.js

@@ -0,0 +1,111 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { detectCIEnvironment } from './ci.js';
+import { DEFAULT_SERVER_URL } from './constants.js';
+const GLOBAL_CONFIG_DIR = join(homedir(), '.pixeye');
+const GLOBAL_CONFIG_PATH = join(GLOBAL_CONFIG_DIR, 'config.json');
+const PROJECT_CONFIG_NAME = '.pixeye.yml';
+export const readGlobalConfig = async () => {
+    try {
+        const content = await readFile(GLOBAL_CONFIG_PATH, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+};
+export const writeGlobalConfig = async (config) => {
+    await mkdir(GLOBAL_CONFIG_DIR, { recursive: true });
+    await writeFile(GLOBAL_CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+};
+export const readProjectConfig = async (cwd) => {
+    try {
+        const content = await readFile(join(cwd, PROJECT_CONFIG_NAME), 'utf-8');
+        return parseYamlLike(content);
+    }
+    catch {
+        return null;
+    }
+};
+export const writeProjectConfig = async (cwd, config) => {
+    const lines = [
+        `server: ${config.server}`,
+        `token: ${config.token}`,
+        ...(config.screenshotDir ? [`screenshotDir: ${config.screenshotDir}`] : [])
+    ];
+    await writeFile(join(cwd, PROJECT_CONFIG_NAME), lines.join('\n') + '\n');
+};
+export const readEnvConfig = () => {
+    const intOrUndef = (val) => {
+        if (val === undefined) {
+            return undefined;
+        }
+        const n = parseInt(val, 10);
+        return isNaN(n) ? undefined : n;
+    };
+    return {
+        server: process.env.PIXEYE_SERVER || undefined,
+        token: process.env.PIXEYE_TOKEN || undefined,
+        commit: process.env.PIXEYE_COMMIT || undefined,
+        branch: process.env.PIXEYE_BRANCH || undefined,
+        pr: intOrUndef(process.env.PIXEYE_PR),
+        runner: process.env.PIXEYE_RUNNER || undefined
+    };
+};
+/** @internal Exported for testing */
+export const parseYamlLike = (content) => {
+    const result = {};
+    for (const line of content.split('\n')) {
+        const match = line.match(/^([\w-]+):\s*(.+)$/);
+        if (match) {
+            let value = match[2].trim();
+            const isQuoted = (value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"));
+            // Strip surrounding quotes
+            if (isQuoted) {
+                value = value.slice(1, -1);
+            }
+            else {
+                // Remove inline comments only for unquoted values
+                value = value.replace(/\s+#.*$/, '');
+            }
+            result[match[1]] = value;
+        }
+    }
+    if (typeof result.server !== 'string' || typeof result.token !== 'string') {
+        throw new Error('.pixeye.yml: "server" and "token" are required');
+    }
+    return { server: result.server, token: result.token, screenshotDir: result.screenshotDir };
+};
+export const resolveConfig = async (overrides = {}) => {
+    const envConfig = readEnvConfig();
+    const ci = detectCIEnvironment();
+    const projectConfig = await readProjectConfig(overrides.cwd ?? process.cwd());
+    const globalConfig = await readGlobalConfig();
+    const serverUrl = overrides.serverUrl ??
+        envConfig.server ??
+        projectConfig?.server ??
+        globalConfig.server ??
+        DEFAULT_SERVER_URL;
+    const token = overrides.token ?? envConfig.token ?? projectConfig?.token ?? globalConfig.token;
+    if (!token) {
+        throw new Error('Pixeye token required. Set PIXEYE_TOKEN, pass --token, or run `pixeye login`.');
+    }
+    const commitSha = overrides.commitSha ?? envConfig.commit ?? ci?.commit;
+    const branch = overrides.branch ?? envConfig.branch ?? ci?.branch;
+    if (!commitSha || !branch) {
+        throw new Error('commitSha and branch required. Set PIXEYE_COMMIT/PIXEYE_BRANCH, pass --commit/--branch, or run in CI.');
+    }
+    return {
+        serverUrl: serverUrl.replace(/\/$/, ''),
+        token,
+        commitSha,
+        branch,
+        prNumber: overrides.prNumber ?? envConfig.pr ?? ci?.prNumber,
+        runner: overrides.runner ?? envConfig.runner,
+        baseBranch: overrides.baseBranch ?? ci?.baseBranch,
+        shardIndex: overrides.shardIndex ?? 0,
+        shardTotal: overrides.shardTotal ?? 1
+    };
+};

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+/** Default Pixeye server URL. */
+export declare const DEFAULT_SERVER_URL = "https://pixeye.dev";
+/** Default number of concurrent screenshot uploads. Overridable via PIXEYE_UPLOAD_CONCURRENCY env. */
+export declare const DEFAULT_UPLOAD_CONCURRENCY = 32;

package/dist/constants.js

@@ -0,0 +1,4 @@
+/** Default Pixeye server URL. */
+export const DEFAULT_SERVER_URL = 'https://pixeye.dev';
+/** Default number of concurrent screenshot uploads. Overridable via PIXEYE_UPLOAD_CONCURRENCY env. */
+export const DEFAULT_UPLOAD_CONCURRENCY = 32;

package/dist/discover.d.ts

@@ -0,0 +1,10 @@
+export interface DiscoveredFile {
+    filePath: string;
+    name: string;
+    fileHash: string;
+    format: 'png' | 'webp';
+    width: number;
+    height: number;
+    metadata?: Record<string, unknown>;
+}
+export declare const discoverScreenshots: (directory: string) => Promise<DiscoveredFile[]>;

package/dist/discover.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { glob } from 'glob';
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const WEBP_RIFF = Buffer.from('RIFF');
+const WEBP_WEBP = Buffer.from('WEBP');
+const readPngDimensions = (buffer) => {
+    if (buffer.length < 24 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new Error('Invalid PNG file: missing or incorrect PNG signature');
+    }
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    return { width, height };
+};
+const readWebpDimensions = (buffer) => {
+    if (buffer.length < 30 ||
+        !buffer.subarray(0, 4).equals(WEBP_RIFF) ||
+        !buffer.subarray(8, 12).equals(WEBP_WEBP)) {
+        throw new Error('Invalid WebP file: missing RIFF/WEBP signature');
+    }
+    // VP8 lossy: chunk starts at offset 12, dimensions at offset 26-29
+    const chunk = buffer.subarray(12, 16).toString('ascii');
+    if (chunk === 'VP8 ') {
+        const width = buffer.readUInt16LE(26) & 0x3fff;
+        const height = buffer.readUInt16LE(28) & 0x3fff;
+        return { width, height };
+    }
+    // VP8L lossless: chunk starts at offset 12, dimensions encoded at offset 21
+    if (chunk === 'VP8L') {
+        const bits = buffer.readUInt32LE(21);
+        const width = (bits & 0x3fff) + 1;
+        const height = ((bits >> 14) & 0x3fff) + 1;
+        return { width, height };
+    }
+    // VP8X extended: dimensions at offset 24-29
+    if (chunk === 'VP8X') {
+        const width = (buffer.readUIntLE(24, 3) & 0xffffff) + 1;
+        const height = (buffer.readUIntLE(27, 3) & 0xffffff) + 1;
+        return { width, height };
+    }
+    throw new Error(`Unsupported WebP chunk type: ${chunk}`);
+};
+const readDimensions = (buffer, format) => {
+    return format === 'png' ? readPngDimensions(buffer) : readWebpDimensions(buffer);
+};
+export const discoverScreenshots = async (directory) => {
+    const files = await glob('**/*.{png,webp}', { cwd: directory, posix: true });
+    files.sort();
+    const results = [];
+    for (const relativePath of files) {
+        const filePath = `${directory}/${relativePath}`;
+        const fileBuffer = await readFile(filePath);
+        const format = relativePath.endsWith('.webp') ? 'webp' : 'png';
+        const fileHash = createHash('sha256').update(fileBuffer).digest('hex');
+        const { width, height } = readDimensions(fileBuffer, format);
+        const name = relativePath.replace(/\.(png|webp)$/, '');
+        // Check for companion metadata file
+        const metadataPath = filePath.replace(/\.(png|webp)$/, '.pixeye.json');
+        let metadata;
+        try {
+            const metadataContent = await readFile(metadataPath, 'utf-8');
+            metadata = JSON.parse(metadataContent);
+        }
+        catch {
+            // No metadata file or invalid JSON — skip
+        }
+        results.push({ filePath, name, fileHash, format, width, height, metadata });
+    }
+    return results;
+};

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { PixeyeClientOptions } from './client.js';
+export { PixeyeClient, PixeyeError } from './client.js';
+export type { EnvConfig, PixeyeConfig, ProjectConfig, ResolvedConfig } from './config.js';
+export { parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, writeGlobalConfig, writeProjectConfig } from './config.js';
+export type { CIEnvironment } from './ci.js';
+export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
+export type { DiscoveredFile } from './discover.js';
+export { discoverScreenshots } from './discover.js';
+export { runParallel } from './parallel.js';
+export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { PixeyeClient, PixeyeError } from './client.js';
+export { parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, writeGlobalConfig, writeProjectConfig } from './config.js';
+export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
+export { discoverScreenshots } from './discover.js';
+// Parallel execution
+export { runParallel } from './parallel.js';
+// Constants
+export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';

package/dist/parallel.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Run async tasks in parallel with a concurrency limit.
+ */
+export declare const runParallel: <T>(items: T[], concurrency: number, fn: (item: T) => Promise<void>) => Promise<void>;

package/dist/parallel.js

@@ -0,0 +1,13 @@
+/**
+ * Run async tasks in parallel with a concurrency limit.
+ */
+export const runParallel = async (items, concurrency, fn) => {
+    let index = 0;
+    const worker = async () => {
+        while (index < items.length) {
+            const i = index++;
+            await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@pixeyedev/core",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "echo 'ok'",
+    "ai-check": "exit 0",
+    "publish:dry": "npm run build && npm publish --access public --dry-run"
+  },
+  "dependencies": {
+    "@pixeyedev/shared": "^0.4.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}