@pixeyedev/core 0.4.5 → 0.4.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pixeye (pixeye.dev)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ci.d.ts

@@ -5,10 +5,14 @@ export interface CIEnvironment {
     baseBranch?: string;
     prNumber?: number;
     repository?: string;
+    trigger?: CITrigger;
+}
+export interface CITrigger {
+    runId?: string;
+    runAttempt?: string;
+    actor?: string;
+    workflow?: string;
+    eventName?: string;
+    runUrl?: 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

@@ -1,33 +1,49 @@
-import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+const readGitHubEvent = () => {
+    const path = process.env.GITHUB_EVENT_PATH;
+    if (!path) {
+        return null;
+    }
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        console.warn(`pixeye: could not read the GitHub event payload at ${path}: ${String(err)}`);
+        return null;
+    }
+};
 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 event = readGitHubEvent();
+    const eventPr = event?.pull_request ?? event?.workflow_run?.pull_requests?.[0];
+    const commit = event?.pull_request?.head?.sha ?? event?.workflow_run?.head_sha ?? process.env.GITHUB_SHA;
+    const branch = process.env.GITHUB_HEAD_REF || event?.workflow_run?.head_branch || process.env.GITHUB_REF_NAME;
     const runId = process.env.GITHUB_RUN_ID;
     if (!commit || !branch || !runId) {
         return null;
     }
-    // PR number: explicit env > GITHUB_REF on pull_request events (refs/pull/123/merge)
     const prRaw = process.env.PIXEYE_PR;
-    let prNumber = prRaw ? parseInt(prRaw, 10) : undefined;
-    if (!prNumber) {
-        const ref = process.env.GITHUB_REF ?? '';
-        const prMatch = ref.match(/^refs\/pull\/(\d+)\//);
-        if (prMatch) {
-            prNumber = parseInt(prMatch[1], 10);
-        }
-    }
-    // PR target branch: GITHUB_BASE_REF is set on pull_request events
-    const baseBranch = process.env.GITHUB_BASE_REF || undefined;
+    const prNumber = prRaw ? parseInt(prRaw, 10) : eventPr?.number;
+    const baseBranch = process.env.GITHUB_BASE_REF || eventPr?.base?.ref || undefined;
+    const repository = process.env.GITHUB_REPOSITORY;
+    const serverUrl = process.env.GITHUB_SERVER_URL;
     return {
         provider: 'github-actions',
         commit,
         branch,
         baseBranch,
         prNumber: prNumber && !isNaN(prNumber) ? prNumber : undefined,
-        repository: process.env.GITHUB_REPOSITORY
+        repository,
+        trigger: {
+            runId,
+            runAttempt: process.env.GITHUB_RUN_ATTEMPT || undefined,
+            actor: process.env.GITHUB_ACTOR || undefined,
+            workflow: process.env.GITHUB_WORKFLOW || undefined,
+            eventName: process.env.GITHUB_EVENT_NAME || undefined,
+            runUrl: serverUrl && repository ? `${serverUrl}/${repository}/actions/runs/${runId}` : undefined
+        }
     };
 };
 const detectGitLabCI = () => {
@@ -47,32 +63,14 @@ const detectGitLabCI = () => {
         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
+        repository: process.env.CI_PROJECT_PATH || undefined,
+        trigger: {
+            runId: pipelineId,
+            actor: process.env.GITLAB_USER_LOGIN || undefined,
+            workflow: process.env.CI_JOB_NAME || undefined,
+            eventName: process.env.CI_PIPELINE_SOURCE || undefined,
+            runUrl: process.env.CI_PIPELINE_URL || undefined
         }
-    }
-    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;
+    };
 };
+export const detectCIEnvironment = () => detectGitHubActions() ?? detectGitLabCI() ?? null;

package/dist/client.d.ts

@@ -1,35 +1,29 @@
-import type { CreateBuildResponse, ListBuildsResponse, PipelineFinalizeResponse, PresignUploadResponse, ScreenshotManifestEntry, SubmitShardResponse } from '@pixeyedev/shared';
+import type { CreateBuildResponse, ListBuildsResponse, PipelineFinalizeResponse, PresignUploadResponse, ScreenshotFormat, ScreenshotManifestEntry, SubmitShardResponse } from '@pixeyedev/shared';
 export declare class PixeyeError extends Error {
     status: number;
     path: string;
     body: string;
-    /**
-     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
-     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
-     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
-     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
-     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
-     */
     origin: 'api' | 'r2';
-    constructor(status: number, path: string, body: string, 
-    /**
-     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
-     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
-     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
-     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
-     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
-     */
-    origin?: 'api' | 'r2');
+    retryAfterMs?: number | undefined;
+    constructor(status: number, path: string, body: string, origin?: 'api' | 'r2', retryAfterMs?: number | undefined);
 }
 export interface PixeyeClientOptions {
     serverUrl: string;
     token: string;
+    timeoutMs?: number;
+    attempts?: number;
 }
 export declare class PixeyeClient {
     private serverUrl;
     private token;
+    private timeoutMs;
+    private attempts;
+    private reporting?;
+    get observes(): boolean;
     constructor(options: PixeyeClientOptions);
+    private send;
     private request;
+    private retryOptions;
     createBuild(opts: {
         projectToken: string;
         commitSha: string;
@@ -46,7 +40,7 @@ export declare class PixeyeClient {
     presignUpload(opts: {
         buildId: string;
         hashes: string[];
-        formats?: Record<string, 'png' | 'webp'>;
+        formats?: Record<string, ScreenshotFormat>;
     }): Promise<PresignUploadResponse>;
     uploadFile(presignedUrl: string, buffer: Buffer, contentType: string): Promise<void>;
     submitShard(opts: {
@@ -59,6 +53,6 @@ export declare class PixeyeClient {
         branch: string;
     }): Promise<ListBuildsResponse>;
     finalizePipeline(pipelineId: string): Promise<PipelineFinalizeResponse>;
-    checkFileExists(hash: string): Promise<boolean>;
-    uploadLegacy(buffer: Buffer, hash: string, filename: string): Promise<void>;
+    checkFileExists(hash: string, format?: ScreenshotFormat): Promise<boolean>;
+    uploadLegacy(buffer: Buffer, hash: string, filename: string, format?: ScreenshotFormat): Promise<void>;
 }

package/dist/client.js

@@ -1,50 +1,75 @@
-import { CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
+import { createRequire } from 'node:module';
+import { CONTENT_TYPE_BY_FORMAT, CreateBuildResponseSchema, ListBuildsResponseSchema, PipelineFinalizeResponseSchema, PRESIGN_BATCH_MAX, PresignUploadResponseSchema, SubmitShardResponseSchema } from '@pixeyedev/shared';
+import { readClientEnv } from './config.js';
+import { DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_UPLOAD_ATTEMPTS, RETRY_AFTER_MAX_MS } from './constants.js';
 import { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
 export class PixeyeError extends Error {
     status;
     path;
     body;
     origin;
-    constructor(status, path, body, 
-    /**
-     * Where the failure came from. `'api'` = the Pixeye control-plane (a 4xx
-     * here can be a customer misconfig — token/plan/permissions). `'r2'` = a
-     * data-plane PUT to R2 via a presigned URL (a 403/404 here is a Pixeye-side
-     * fault — expired URL, bucket/credential, clock skew — NEVER the customer's).
-     * Used by `isUploadMisconfig` so an R2 outage can't fail a customer's CI.
-     */
-    origin = 'api') {
+    retryAfterMs;
+    constructor(status, path, body, origin = 'api', retryAfterMs) {
         super(`Pixeye API ${path} failed (${status}): ${body}`);
         this.status = status;
         this.path = path;
         this.body = body;
         this.origin = origin;
+        this.retryAfterMs = retryAfterMs;
         this.name = 'PixeyeError';
     }
 }
+const parseRetryAfter = (response) => {
+    const seconds = Number(response.headers.get('retry-after'));
+    return Number.isFinite(seconds) && seconds > 0
+        ? Math.min(seconds * 1000, RETRY_AFTER_MAX_MS)
+        : undefined;
+};
+const { version } = createRequire(import.meta.url)('../package.json');
+const USER_AGENT = `@pixeyedev/core/${version} node/${process.versions.node}`;
 export class PixeyeClient {
     serverUrl;
     token;
+    timeoutMs;
+    attempts;
+    reporting;
+    get observes() {
+        return this.reporting === 'observe';
+    }
     constructor(options) {
+        const env = readClientEnv();
         this.serverUrl = options.serverUrl.replace(/\/$/, '');
         this.token = options.token;
+        this.timeoutMs = options.timeoutMs ?? env.timeoutMs ?? DEFAULT_HTTP_TIMEOUT_MS;
+        this.attempts = options.attempts ?? env.attempts ?? DEFAULT_UPLOAD_ATTEMPTS;
     }
-    async request(path, options = {}) {
-        const url = `${this.serverUrl}${path}`;
-        const response = await fetch(url, {
+    async send(path, options = {}) {
+        const response = await fetch(`${this.serverUrl}${path}`, {
             ...options,
+            signal: AbortSignal.timeout(this.timeoutMs),
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${this.token}`,
+                'User-Agent': USER_AGENT,
                 ...options.headers
             }
         });
         if (!response.ok) {
-            const body = await response.text();
-            throw new PixeyeError(response.status, path, body);
+            throw new PixeyeError(response.status, path.split('?')[0], await response.text(), 'api', parseRetryAfter(response));
         }
         return response.json();
     }
+    request(path, options = {}) {
+        return withRetry(() => this.send(path, options), isRetryableHttpError, this.retryOptions(path.split('?')[0]));
+    }
+    retryOptions(what) {
+        return {
+            maxAttempts: this.attempts,
+            onRetry: (attempt, err) => {
+                console.warn(`[pixeye] ${what} retry ${attempt}/${this.attempts}: ${err.message}`);
+            }
+        };
+    }
     async createBuild(opts) {
         const body = { ...opts };
         if (opts.runner) {
@@ -54,19 +79,39 @@ export class PixeyeClient {
             method: 'POST',
             body: JSON.stringify(body)
         });
-        return CreateBuildResponseSchema.parse(raw);
+        const parsed = CreateBuildResponseSchema.parse(raw);
+        this.reporting = parsed.reporting;
+        return parsed;
     }
     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);
+        const merged = {
+            urls: {},
+            existing: [],
+            uploadCount: 0,
+            skippedCount: 0,
+            warnings: []
+        };
+        for (let start = 0; start < opts.hashes.length; start += PRESIGN_BATCH_MAX) {
+            const hashes = opts.hashes.slice(start, start + PRESIGN_BATCH_MAX);
+            const inChunk = new Set(hashes);
+            const formats = Object.fromEntries(Object.entries(opts.formats ?? {}).filter(([hash]) => inChunk.has(hash)));
+            const raw = await this.request('/api/v1/upload/presign', {
+                method: 'POST',
+                body: JSON.stringify({
+                    token: this.token,
+                    buildId: opts.buildId,
+                    hashes,
+                    ...(Object.keys(formats).length > 0 ? { formats } : {})
+                })
+            });
+            const part = PresignUploadResponseSchema.parse(raw);
+            Object.assign(merged.urls, part.urls);
+            merged.existing.push(...part.existing);
+            merged.uploadCount += part.uploadCount;
+            merged.skippedCount += part.skippedCount;
+            merged.warnings.push(...part.warnings);
+        }
+        return merged;
     }
     async uploadFile(presignedUrl, buffer, contentType) {
         const maskedUrl = maskPresignedUrl(presignedUrl);
@@ -74,23 +119,16 @@ export class PixeyeClient {
             const res = await fetch(presignedUrl, {
                 method: 'PUT',
                 body: new Uint8Array(buffer),
+                signal: AbortSignal.timeout(this.timeoutMs),
                 headers: { 'Content-Type': contentType }
             });
             if (!res.ok) {
-                // 'r2' origin — a PUT failure here is Pixeye-side (expired presigned
-                // URL, bucket/creds, clock skew), never the customer's misconfig.
                 throw new PixeyeError(res.status, maskedUrl, await res.text(), 'r2');
             }
-        }, isRetryableHttpError, {
-            maxAttempts: 3,
-            baseDelayMs: 1000,
-            onRetry: (attempt, err) => {
-                console.warn(`[pixeye] Upload retry ${attempt}/3: ${err.message}`);
-            }
-        });
+        }, isRetryableHttpError, this.retryOptions('Upload'));
     }
     async submitShard(opts) {
-        const raw = await this.request(`/api/v1/builds/${opts.buildId}/shards`, {
+        const raw = await this.send(`/api/v1/builds/${opts.buildId}/shards`, {
             method: 'POST',
             body: JSON.stringify({
                 shardIndex: opts.shardIndex,
@@ -114,18 +152,24 @@ export class PixeyeClient {
         });
         return PipelineFinalizeResponseSchema.parse(raw);
     }
-    async checkFileExists(hash) {
-        const result = await this.request(`/api/v1/upload/${hash}?token=${encodeURIComponent(this.token)}`);
+    async checkFileExists(hash, format = 'png') {
+        const result = await this.request(`/api/v1/upload/${encodeURIComponent(hash)}?token=${encodeURIComponent(this.token)}` +
+            `&format=${encodeURIComponent(format)}`);
         return result.exists;
     }
-    async uploadLegacy(buffer, hash, filename) {
-        const blob = new Blob([new Uint8Array(buffer)], { type: 'image/png' });
+    async uploadLegacy(buffer, hash, filename, format = 'png') {
+        const blob = new Blob([new Uint8Array(buffer)], { type: CONTENT_TYPE_BY_FORMAT[format] });
         const formData = new FormData();
         formData.append('file', blob, filename);
         formData.append('hash', hash);
+        formData.append('format', format);
         formData.append('token', this.token);
         const url = `${this.serverUrl}/api/v1/upload`;
-        const response = await fetch(url, { method: 'POST', body: formData });
+        const response = await fetch(url, {
+            method: 'POST',
+            body: formData,
+            signal: AbortSignal.timeout(this.timeoutMs)
+        });
         if (!response.ok) {
             const body = await response.text();
             throw new PixeyeError(response.status, '/api/v1/upload', body);

package/dist/config.d.ts

@@ -30,8 +30,13 @@ 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 integerSetting: (name: string, raw: string | number | undefined, min: number) => number | undefined;
+export declare const readClientEnv: () => {
+    timeoutMs?: number;
+    attempts?: number;
+};
+export declare const resolveUploadConcurrency: (option: number | undefined) => number;
 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;

package/dist/config.js

@@ -2,7 +2,8 @@ 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';
+import { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+import { CustomerError } from './uploadError.js';
 const GLOBAL_CONFIG_DIR = join(homedir(), '.pixeye');
 const GLOBAL_CONFIG_PATH = join(GLOBAL_CONFIG_DIR, 'config.json');
 const PROJECT_CONFIG_NAME = '.pixeye.yml';
@@ -36,24 +37,33 @@ export const writeProjectConfig = async (cwd, config) => {
     ];
     await writeFile(join(cwd, PROJECT_CONFIG_NAME), lines.join('\n') + '\n');
 };
+export const integerSetting = (name, raw, min) => {
+    if (raw === undefined || raw === '') {
+        return undefined;
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < min) {
+        throw new CustomerError(`${name} must be an integer of at least ${min}, got "${raw}".`);
+    }
+    return n;
+};
+export const readClientEnv = () => ({
+    timeoutMs: integerSetting('PIXEYE_HTTP_TIMEOUT_MS', process.env.PIXEYE_HTTP_TIMEOUT_MS, 1),
+    attempts: integerSetting('PIXEYE_UPLOAD_ATTEMPTS', process.env.PIXEYE_UPLOAD_ATTEMPTS, 1)
+});
+export const resolveUploadConcurrency = (option) => integerSetting('uploadConcurrency', option, 1) ??
+    integerSetting('PIXEYE_UPLOAD_CONCURRENCY', process.env.PIXEYE_UPLOAD_CONCURRENCY, 1) ??
+    DEFAULT_UPLOAD_CONCURRENCY;
 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),
+        pr: integerSetting('PIXEYE_PR', process.env.PIXEYE_PR, 1),
         runner: process.env.PIXEYE_RUNNER || undefined
     };
 };
-/** @internal Exported for testing */
 export const parseYamlLike = (content) => {
     const result = {};
     for (const line of content.split('\n')) {
@@ -62,12 +72,10 @@ export const parseYamlLike = (content) => {
             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;

package/dist/constants.d.ts

@@ -1,4 +1,5 @@
-/** 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;
+export declare const DEFAULT_HTTP_TIMEOUT_MS = 60000;
+export declare const DEFAULT_UPLOAD_ATTEMPTS = 3;
+export declare const RETRY_AFTER_MAX_MS = 60000;

package/dist/constants.js

@@ -1,4 +1,5 @@
-/** 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;
+export const DEFAULT_HTTP_TIMEOUT_MS = 60_000;
+export const DEFAULT_UPLOAD_ATTEMPTS = 3;
+export const RETRY_AFTER_MAX_MS = 60_000;

package/dist/discover.d.ts

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

package/dist/discover.js

@@ -1,70 +1,94 @@
 import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 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');
+import { probeImage, swapImageExtension } from './imageProbe.js';
+const METADATA_SIDECAR = '.meta.json';
+const SIDECAR_SUFFIX_RE = /\.[^.]+\.json$/;
+const FAILED_NAME_SUFFIX = ' (failed)';
+const sidecarsByOwner = (siblings) => {
+    const byOwner = new Map();
+    for (const name of siblings) {
+        if (SIDECAR_SUFFIX_RE.test(name)) {
+            const owner = name.replace(SIDECAR_SUFFIX_RE, '');
+            byOwner.set(owner, [...(byOwner.get(owner) ?? []), name]);
+        }
     }
-    const width = buffer.readUInt32BE(16);
-    const height = buffer.readUInt32BE(20);
-    return { width, height };
+    return byOwner;
 };
-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 };
+const readSidecar = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf-8'));
     }
-    // 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 };
+    catch (err) {
+        console.warn(`pixeye: ignoring unreadable sidecar ${path}: ${String(err)}`);
+        return undefined;
     }
-    // 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 };
+};
+const testOf = (sidecar) => {
+    const test = sidecar.test;
+    if (!test || typeof test !== 'object') {
+        return undefined;
     }
-    throw new Error(`Unsupported WebP chunk type: ${chunk}`);
+    const { id, title, titlePath, location } = test;
+    const file = location && typeof location === 'object' ? location.file : undefined;
+    const fields = Object.fromEntries(Object.entries({ testId: id, testName: title, testFile: file }).filter(([, v]) => typeof v === 'string'));
+    const key = Array.isArray(titlePath) ? titlePath.join(' › ') : fields.testName;
+    return key ? { key, fields } : undefined;
 };
-const readDimensions = (buffer, format) => {
-    return format === 'png' ? readPngDimensions(buffer) : readWebpDimensions(buffer);
+const libraryOf = (sidecar) => {
+    const library = sidecar.automationLibrary;
+    const name = library && typeof library === 'object' ? library.name : undefined;
+    return typeof name === 'string' ? name : undefined;
 };
 export const discoverScreenshots = async (directory) => {
     const files = await glob('**/*.{png,webp}', { cwd: directory, posix: true });
     files.sort();
-    const results = [];
+    const sidecarsByDir = new Map();
+    const found = [];
+    const failedTests = new Set();
     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');
+        const { format, width, height } = probeImage(fileBuffer, relativePath);
+        const name = swapImageExtension(relativePath, '');
+        const dir = dirname(filePath);
+        const sidecars = sidecarsByDir.get(dir) ?? sidecarsByOwner(await readdir(dir));
+        sidecarsByDir.set(dir, sidecars);
+        const fileName = basename(filePath);
+        const own = [
+            ...(sidecars.get(swapImageExtension(fileName, '')) ?? []),
+            ...(sidecars.get(fileName) ?? [])
+        ];
         let metadata;
-        try {
-            const metadataContent = await readFile(metadataPath, 'utf-8');
-            metadata = JSON.parse(metadataContent);
+        let test;
+        let library;
+        for (const sidecarName of own) {
+            const sidecar = await readSidecar(join(dir, sidecarName));
+            if (!sidecar) {
+                continue;
+            }
+            if (sidecarName === swapImageExtension(fileName, METADATA_SIDECAR)) {
+                metadata = sidecar;
+            }
+            else {
+                test ??= testOf(sidecar);
+            }
+            library ??= libraryOf(sidecar);
         }
-        catch {
-            // No metadata file or invalid JSON — skip
+        if (test && metadata === undefined && name.endsWith(FAILED_NAME_SUFFIX)) {
+            failedTests.add(test.key);
         }
-        results.push({ filePath, name, fileHash, format, width, height, metadata });
+        found.push({ filePath, name, fileHash, format, width, height, metadata, test, library });
     }
+    const results = found.map(({ test, metadata, ...file }) => ({
+        ...file,
+        metadata: metadata ??
+            (test && {
+                ...test.fields,
+                ...(failedTests.has(test.key) ? { testStatus: 'failed' } : {})
+            })
+    }));
     return results;
 };

package/dist/imageProbe.d.ts

@@ -0,0 +1,9 @@
+import type { ScreenshotFormat } from '@pixeyedev/shared';
+export interface ProbedImage {
+    format: ScreenshotFormat;
+    width: number;
+    height: number;
+}
+export declare const swapImageExtension: (filePath: string, replacement: string) => string;
+export declare const sniffImageFormat: (buffer: Buffer) => ScreenshotFormat | null;
+export declare const probeImage: (buffer: Buffer, filePath: string) => ProbedImage;

package/dist/imageProbe.js

@@ -0,0 +1,102 @@
+import { CustomerError } from './uploadError.js';
+const IMAGE_EXTENSION_RE = /\.(png|webp)$/;
+export const swapImageExtension = (filePath, replacement) => filePath.replace(IMAGE_EXTENSION_RE, replacement);
+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 isPng = (buffer) => buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE);
+const isJpeg = (buffer) => buffer.length >= 3 && buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+const isWebp = (buffer) => buffer.length >= 12 &&
+    buffer.subarray(0, 4).equals(WEBP_RIFF) &&
+    buffer.subarray(8, 12).equals(WEBP_WEBP);
+export const sniffImageFormat = (buffer) => {
+    if (isPng(buffer)) {
+        return 'png';
+    }
+    if (isJpeg(buffer)) {
+        return 'jpeg';
+    }
+    if (isWebp(buffer)) {
+        return 'webp';
+    }
+    return null;
+};
+const readPngDimensions = (buffer) => {
+    if (buffer.length < 24) {
+        throw new Error('PNG header is truncated');
+    }
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+};
+const JPEG_SOF_EXCLUDED = new Set([0xc4, 0xc8, 0xcc]);
+const readJpegDimensions = (buffer) => {
+    let offset = 2;
+    while (offset + 9 < buffer.length) {
+        if (buffer[offset] !== 0xff) {
+            offset++;
+            continue;
+        }
+        const marker = buffer[offset + 1];
+        if (marker === 0xff) {
+            offset++;
+            continue;
+        }
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            offset += 2;
+            continue;
+        }
+        const segmentLength = buffer.readUInt16BE(offset + 2);
+        if (marker >= 0xc0 && marker <= 0xcf && !JPEG_SOF_EXCLUDED.has(marker)) {
+            return { height: buffer.readUInt16BE(offset + 5), width: buffer.readUInt16BE(offset + 7) };
+        }
+        if (segmentLength < 2) {
+            break;
+        }
+        offset += 2 + segmentLength;
+    }
+    throw new Error('JPEG has no start-of-frame marker');
+};
+const readWebpDimensions = (buffer) => {
+    if (buffer.length < 30) {
+        throw new Error('WebP header is truncated');
+    }
+    const chunk = buffer.subarray(12, 16).toString('ascii');
+    if (chunk === 'VP8 ') {
+        return {
+            width: buffer.readUInt16LE(26) & 0x3fff,
+            height: buffer.readUInt16LE(28) & 0x3fff
+        };
+    }
+    if (chunk === 'VP8L') {
+        const bits = buffer.readUInt32LE(21);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === 'VP8X') {
+        return {
+            width: (buffer.readUIntLE(24, 3) & 0xffffff) + 1,
+            height: (buffer.readUIntLE(27, 3) & 0xffffff) + 1
+        };
+    }
+    throw new Error(`Unsupported WebP chunk type: ${chunk}`);
+};
+export const probeImage = (buffer, filePath) => {
+    const format = sniffImageFormat(buffer);
+    if (format === null) {
+        throw new CustomerError(`${filePath} is not a PNG, JPEG or WebP image (the file is corrupt, ` +
+            `truncated, or a different format saved under an image extension)`);
+    }
+    try {
+        const dimensions = format === 'png'
+            ? readPngDimensions(buffer)
+            : format === 'jpeg'
+                ? readJpegDimensions(buffer)
+                : readWebpDimensions(buffer);
+        if (dimensions.width <= 0 || dimensions.height <= 0) {
+            throw new Error(`reported ${dimensions.width}x${dimensions.height}`);
+        }
+        return { format, ...dimensions };
+    }
+    catch (err) {
+        throw new CustomerError(`${filePath} looks like ${format.toUpperCase()} but its dimensions could not be ` +
+            `read (${err.message}) — the file is probably truncated`);
+    }
+};

package/dist/index.d.ts

@@ -1,13 +1,15 @@
 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 { integerSetting, parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, resolveUploadConcurrency, writeGlobalConfig, writeProjectConfig } from './config.js';
 export type { CIEnvironment } from './ci.js';
-export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
+export { detectCIEnvironment } from './ci.js';
 export type { DiscoveredFile } from './discover.js';
 export { discoverScreenshots } from './discover.js';
+export type { ProbedImage } from './imageProbe.js';
+export { probeImage, sniffImageFormat, swapImageExtension } from './imageProbe.js';
 export { runParallel } from './parallel.js';
 export type { RetryOptions } from './retry.js';
 export { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
-export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
-export { isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';
+export { DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_SERVER_URL, DEFAULT_UPLOAD_ATTEMPTS, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+export { CustomerError, isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';

package/dist/index.js

@@ -1,10 +1,9 @@
 export { PixeyeClient, PixeyeError } from './client.js';
-export { parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, writeGlobalConfig, writeProjectConfig } from './config.js';
-export { detectBaseBranchFromGit, detectCIEnvironment } from './ci.js';
+export { integerSetting, parseYamlLike, readEnvConfig, readGlobalConfig, readProjectConfig, resolveConfig, resolveUploadConcurrency, writeGlobalConfig, writeProjectConfig } from './config.js';
+export { detectCIEnvironment } from './ci.js';
 export { discoverScreenshots } from './discover.js';
-// Parallel execution
+export { probeImage, sniffImageFormat, swapImageExtension } from './imageProbe.js';
 export { runParallel } from './parallel.js';
 export { isRetryableHttpError, maskPresignedUrl, withRetry } from './retry.js';
-// Constants
-export { DEFAULT_SERVER_URL, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
-export { isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';
+export { DEFAULT_HTTP_TIMEOUT_MS, DEFAULT_SERVER_URL, DEFAULT_UPLOAD_ATTEMPTS, DEFAULT_UPLOAD_CONCURRENCY } from './constants.js';
+export { CustomerError, isUploadMisconfig, renderUploadFailureBanner, resolveFailOnError, uploadErrorSummary } from './uploadError.js';

package/dist/parallel.d.ts

@@ -1,4 +1 @@
-/**
- * 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

@@ -1,6 +1,3 @@
-/**
- * Run async tasks in parallel with a concurrency limit.
- */
 export const runParallel = async (items, concurrency, fn) => {
     let index = 0;
     const worker = async () => {

package/dist/retry.d.ts

@@ -3,12 +3,6 @@ export interface RetryOptions {
     baseDelayMs?: number;
     onRetry?: (attempt: number, error: Error) => void;
 }
-/**
- * Retry an async function with exponential backoff + jitter.
- * Only retries on errors where shouldRetry returns true.
- */
 export declare const withRetry: <T>(fn: () => Promise<T>, shouldRetry: (error: unknown) => boolean, opts?: RetryOptions) => Promise<T>;
-/** Returns true for HTTP 429/5xx responses or transient network errors. */
 export declare const isRetryableHttpError: (error: unknown) => boolean;
-/** Mask presigned URL signature for safe error logging. */
 export declare const maskPresignedUrl: (url: string) => string;

package/dist/retry.js

@@ -1,7 +1,3 @@
-/**
- * Retry an async function with exponential backoff + jitter.
- * Only retries on errors where shouldRetry returns true.
- */
 export const withRetry = async (fn, shouldRetry, opts = {}) => {
     const maxAttempts = opts.maxAttempts ?? 3;
     const baseDelayMs = opts.baseDelayMs ?? 1000;
@@ -13,28 +9,30 @@ export const withRetry = async (fn, shouldRetry, opts = {}) => {
             if (attempt === maxAttempts || !shouldRetry(error)) {
                 throw error;
             }
-            // Exponential backoff with equal jitter (half deterministic + half random)
             const exponential = baseDelayMs * Math.pow(2, attempt - 1);
-            const delay = exponential * (0.5 + 0.5 * Math.random());
+            const delay = retryAfterMsOf(error) ?? exponential * (0.5 + 0.5 * Math.random());
             opts.onRetry?.(attempt, error instanceof Error ? error : new Error(String(error)));
             await new Promise(r => setTimeout(r, delay));
         }
     }
     throw new Error('Unreachable');
 };
+const retryAfterMsOf = (error) => {
+    const ms = error?.retryAfterMs;
+    return typeof ms === 'number' ? ms : undefined;
+};
 const TRANSIENT_NETWORK_RE = /fetch failed|ECONNRESET|ETIMEDOUT|ECONNREFUSED|ENOTFOUND|EPIPE|socket hang up/i;
-/** Returns true for HTTP 429/5xx responses or transient network errors. */
 export const isRetryableHttpError = (error) => {
-    // Check status code first (authoritative when present)
+    if (error instanceof Error && error.name === 'TimeoutError') {
+        return true;
+    }
     const status = error?.status;
     if (status !== undefined) {
         return status === 429 || (status >= 500 && status < 600);
     }
-    // Fall back to message-based detection for genuine network errors (no HTTP response)
     if (error instanceof Error && TRANSIENT_NETWORK_RE.test(error.message)) {
         return true;
     }
     return false;
 };
-/** Mask presigned URL signature for safe error logging. */
 export const maskPresignedUrl = (url) => url.split('?')[0] + '?[signature-masked]';

package/dist/uploadError.d.ts

@@ -1,35 +1,9 @@
-/**
- * Classify an upload failure and render a loud banner — shared by the Playwright
- * reporter and the CLI so a lapsed plan / bad token surfaces identically (P0-2).
- *
- * The rule: distinguish the CUSTOMER's misconfiguration (they must act) from a
- * transient / our-side fault (their CI should not break over our hiccup).
- */
-/**
- * True when the failure is the customer's configuration/billing, not ours.
- * A `PixeyeError` from the R2 data-plane (`origin: 'r2'`) is EXCLUDED — a
- * 403/404 on a presigned PUT (expired URL, bucket/creds, clock skew) is a
- * Pixeye-side fault and must never fail the customer's CI.
- */
+export declare class CustomerError extends Error {
+    constructor(message: string);
+}
 export declare const isUploadMisconfig: (err: unknown) => boolean;
-/**
- * One-line `HTTP <status> — <detail>` summary. Prefers the error's `body`
- * (the meaningful server code, e.g. `SUBSCRIPTION_CANCELLED`) over the full
- * `PixeyeError.message`, which already embeds the status (avoids `HTTP 402 —
- * Pixeye API … failed (402): …`).
- */
 export declare const uploadErrorSummary: (err: unknown) => string;
-/**
- * Resolve the fail-on-error setting identically for the reporter and CLI: fail
- * by default; opt out via EITHER an explicit `false` option OR
- * `PIXEYE_FAIL_ON_ERROR=false`. (The CLI's commander always supplies a boolean
- * option; the reporter's is optional — this keeps both consistent.)
- */
 export declare const resolveFailOnError: (option: boolean | undefined, env: string | undefined) => boolean;
-/**
- * A bright, unmissable banner for a rejected upload. `willFail` toggles the
- * closing line between "failing this step" and "opted out — passing anyway".
- */
 export declare const renderUploadFailureBanner: (err: unknown, opts: {
     willFail: boolean;
 }) => string;

package/dist/uploadError.js

@@ -1,42 +1,23 @@
-/**
- * Classify an upload failure and render a loud banner — shared by the Playwright
- * reporter and the CLI so a lapsed plan / bad token surfaces identically (P0-2).
- *
- * The rule: distinguish the CUSTOMER's misconfiguration (they must act) from a
- * transient / our-side fault (their CI should not break over our hiccup).
- */
-/**
- * HTTP statuses that mean the CUSTOMER must act — a bad/absent token (401),
- * a lapsed subscription or exceeded quota (402), insufficient permissions
- * (403), or a wrong project/endpoint (404). These fail CI by default so a run
- * can't pass green while zero screenshots reached Pixeye. EVERYTHING else
- * (429 rate-limit, 5xx, network, timeouts, no status) is transient / our fault
- * → warn, never break their CI.
- */
-const MISCONFIG_STATUSES = [401, 402, 403, 404];
+export class CustomerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CustomerError';
+    }
+}
 const statusOf = (err) => {
     const status = err?.status;
     return typeof status === 'number' ? status : undefined;
 };
-/**
- * True when the failure is the customer's configuration/billing, not ours.
- * A `PixeyeError` from the R2 data-plane (`origin: 'r2'`) is EXCLUDED — a
- * 403/404 on a presigned PUT (expired URL, bucket/creds, clock skew) is a
- * Pixeye-side fault and must never fail the customer's CI.
- */
 export const isUploadMisconfig = (err) => {
+    if (err instanceof CustomerError) {
+        return true;
+    }
     if (err?.origin === 'r2') {
         return false;
     }
     const status = statusOf(err);
-    return status !== undefined && MISCONFIG_STATUSES.includes(status);
+    return status !== undefined && status >= 400 && status < 500 && status !== 409 && status !== 429;
 };
-/**
- * One-line `HTTP <status> — <detail>` summary. Prefers the error's `body`
- * (the meaningful server code, e.g. `SUBSCRIPTION_CANCELLED`) over the full
- * `PixeyeError.message`, which already embeds the status (avoids `HTTP 402 —
- * Pixeye API … failed (402): …`).
- */
 export const uploadErrorSummary = (err) => {
     const status = statusOf(err);
     const body = err?.body;
@@ -47,34 +28,35 @@ export const uploadErrorSummary = (err) => {
             : String(err);
     return status !== undefined ? `HTTP ${status} — ${detail}` : detail;
 };
-/**
- * Resolve the fail-on-error setting identically for the reporter and CLI: fail
- * by default; opt out via EITHER an explicit `false` option OR
- * `PIXEYE_FAIL_ON_ERROR=false`. (The CLI's commander always supplies a boolean
- * option; the reporter's is optional — this keeps both consistent.)
- */
 export const resolveFailOnError = (option, env) => option !== false && env !== 'false';
-/**
- * A bright, unmissable banner for a rejected upload. `willFail` toggles the
- * closing line between "failing this step" and "opted out — passing anyway".
- */
 export const renderUploadFailureBanner = (err, opts) => {
     const line = '━'.repeat(64);
+    const customer = isUploadMisconfig(err);
+    const cause = customer
+        ? [
+            '  This is a problem in your configuration or account (a setting, the',
+            '  API token, subscription/quota, or project permissions) — not a Pixeye',
+            '  outage. Fix it and re-run this step.'
+        ]
+        : [
+            '  This is a failure on the Pixeye side, not in your configuration: the',
+            '  upload was retried and still did not get through. Re-run this step;',
+            '  if it keeps failing, write to support@pixeye.dev with this output.'
+        ];
     const footer = opts.willFail
         ? [
-            '  Failing this step so it cannot pass silently. Fix the above, or pass',
+            '  Failing this step so lost coverage cannot pass silently. Pass',
             '  failOnError: false (reporter) / --no-fail-on-error (CLI) to opt out.'
         ]
-        : ['  failOnError is OFF — this step passes despite the lost coverage.'];
+        : ['  Not failing this step: the project is in observe mode, or failOnError is off.'];
     return [
         '',
         `\x1b[31m\x1b[1m${line}`,
-        `  ✗ PIXEYE UPLOAD REJECTED — ${uploadErrorSummary(err)}`,
+        `  ✗ PIXEYE UPLOAD ${customer ? 'REJECTED' : 'FAILED'} — ${uploadErrorSummary(err)}`,
         '',
         '  Your screenshots did NOT reach Pixeye. Visual coverage for this run is',
-        '  LOST. This is a configuration or billing problem on your account (API',
-        '  token, subscription/quota, or project permissions) — not a transient',
-        '  Pixeye outage.',
+        '  LOST.',
+        ...cause,
         '',
         ...footer,
         `${line}\x1b[0m`,

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@pixeyedev/core",
-  "version": "0.4.5",
+  "version": "0.4.7",
+  "license": "MIT",
   "private": false,
   "type": "module",
   "files": [
@@ -16,6 +17,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepack": "rm -rf dist && npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "lint": "echo 'ok'",
@@ -23,7 +25,7 @@
     "publish:dry": "npm run build && npm publish --access public --dry-run"
   },
   "dependencies": {
-    "@pixeyedev/shared": "^0.4.0",
+    "@pixeyedev/shared": "^0.4.7",
     "glob": "^11.0.0"
   },
   "devDependencies": {

package/dist/utils/parseShardInt.d.ts

@@ -1,23 +0,0 @@
-/**
- * F-095: parse shard-related env vars (PIXEYE_SHARD_INDEX,
- * PIXEYE_SHARD_TOTAL, CYPRESS_SPLIT_INDEX, CURRENTS_PARALLEL_INDEX, …)
- * with a NaN guard.
- *
- * Bare `parseInt('abc', 10)` returns NaN; `JSON.stringify({ index: NaN })`
- * coerces to `null` and the API rejects with a confusing
- * "Validation failed: index must be a number" error 30s deep into a CI
- * pipeline. Failing fast at parse time with a clear message identifying
- * the offending env var lets users fix `PIXEYE_SHARD_INDEX=` typos
- * without running the test suite.
- *
- * The helper is intentionally permissive about the shape: callers pass
- * the env var name so the error message is self-explanatory. Returns
- * `undefined` when the value is empty/missing (so callers can default).
- */
-export declare const parseShardInt: (value: string | undefined | null, name: string) => number;
-/**
- * Same as `parseShardInt` but returns `undefined` when the value is
- * missing — useful when the env var is optional and the caller will
- * fall back to a default. Still throws on a non-numeric explicit value.
- */
-export declare const parseShardIntOptional: (value: string | undefined | null, name: string) => number | undefined;

package/dist/utils/parseShardInt.js

@@ -1,41 +0,0 @@
-/**
- * F-095: parse shard-related env vars (PIXEYE_SHARD_INDEX,
- * PIXEYE_SHARD_TOTAL, CYPRESS_SPLIT_INDEX, CURRENTS_PARALLEL_INDEX, …)
- * with a NaN guard.
- *
- * Bare `parseInt('abc', 10)` returns NaN; `JSON.stringify({ index: NaN })`
- * coerces to `null` and the API rejects with a confusing
- * "Validation failed: index must be a number" error 30s deep into a CI
- * pipeline. Failing fast at parse time with a clear message identifying
- * the offending env var lets users fix `PIXEYE_SHARD_INDEX=` typos
- * without running the test suite.
- *
- * The helper is intentionally permissive about the shape: callers pass
- * the env var name so the error message is self-explanatory. Returns
- * `undefined` when the value is empty/missing (so callers can default).
- */
-export const parseShardInt = (value, name) => {
-    if (value === undefined || value === null || value === '') {
-        throw new Error(`${name} must be set`);
-    }
-    const parsed = parseInt(value, 10);
-    if (Number.isNaN(parsed)) {
-        throw new Error(`${name} must be an integer (got ${JSON.stringify(value)})`);
-    }
-    return parsed;
-};
-/**
- * Same as `parseShardInt` but returns `undefined` when the value is
- * missing — useful when the env var is optional and the caller will
- * fall back to a default. Still throws on a non-numeric explicit value.
- */
-export const parseShardIntOptional = (value, name) => {
-    if (value === undefined || value === null || value === '') {
-        return undefined;
-    }
-    const parsed = parseInt(value, 10);
-    if (Number.isNaN(parsed)) {
-        throw new Error(`${name} must be an integer (got ${JSON.stringify(value)})`);
-    }
-    return parsed;
-};