@qoretechnologies/qlip 0.1.3-pr.31.g4b62f97 → 0.1.3-pr.32.g3ecd7a4

package/README.md

@@ -317,6 +317,10 @@ Several `vitest run` invocations (or `test-storybook` shards) can capture into o
 
 Add `--fail-on-partial-build` to `qlip-upload` (or `upload.failOnPartialBuild` on the plugin) to turn "screenshots on disk that never reached the manifest" from a warning into a red build.
 
+### Large builds: processing timeout
+
+The server diffs the whole build before it answers the final upload request, which takes minutes for a large Storybook (about 8–12 minutes for ~2,200 snapshots). `qlip-upload` waits up to 30 minutes for that answer; raise it with `--processing-timeout <seconds>` (or `$QLIP_PROCESSING_TIMEOUT`, or `upload.processingTimeoutMs` on the plugin). A timeout or network failure is reported with the failing phase and its cause; add `--fail-on-upload-error` (or `upload.failOnUploadError`) to make it fail the CI step instead of logging it.
+
 ## Manifest
 
 Each run writes `manifest.json` inside the build folder with tool metadata, defaults, stats, and per-screenshot entries (auto + manual).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { qlipVitestPlugin } from './plugin/vitestPlugin.js';
 export { screenshot } from './runtime/screenshot.js';
-export { uploadBuild, QlipUploadError, type QlipUploadInput, type QlipUploadResult, } from './upload/upload.js';
+export { uploadBuild, QlipUploadError, QlipUploadNetworkError, DEFAULT_PROCESSING_TIMEOUT_MS, type QlipUploadInput, type QlipUploadResult, } from './upload/upload.js';
 export { autodetectBranch, autodetectCommit, autodetectBaseBranch, autodetectAncestorCommits, } from './upload/autodetect.js';
 export type { QlipConsoleLevel, QlipConsoleMessage, QlipManifest, QlipManifestEntry, QlipParameters, QlipPluginOptions, QlipResolvedDefaults, QlipScreenshotOptions, QlipUploadOptions, QlipViewport, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EACL,WAAW,EACX,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EACL,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,6BAA6B,EAC7B,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
 export { qlipVitestPlugin } from './plugin/vitestPlugin.js';
 export { screenshot } from './runtime/screenshot.js';
-export { uploadBuild, QlipUploadError, } from './upload/upload.js';
+export { uploadBuild, QlipUploadError, QlipUploadNetworkError, DEFAULT_PROCESSING_TIMEOUT_MS, } from './upload/upload.js';
 export { autodetectBranch, autodetectCommit, autodetectBaseBranch, autodetectAncestorCommits, } from './upload/autodetect.js';

package/dist/test-runner/cli/upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/test-runner/cli/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAoIH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EAAE,EACd,MAAK,MAAM,CAAC,UAAwB,EACpC,SAAQ;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAY,KAC7E,OAAO,CAAC,gBAAgB,CAsE1B,CAAC"}
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/test-runner/cli/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA2IH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EAAE,EACd,MAAK,MAAM,CAAC,UAAwB,EACpC,SAAQ;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAY,KAC7E,OAAO,CAAC,gBAAgB,CAqF1B,CAAC"}

package/dist/test-runner/cli/upload.js

@@ -52,6 +52,9 @@ Options:
   --token <token>             Bearer token. Default: \$QLIP_UPLOAD_TOKEN.
   --branch <branch>           Override branch detection.
   --commit <sha>              Override commit detection.
+  --processing-timeout <s>    Seconds to wait for the server to process
+                              the build. Default:
+                              \$QLIP_PROCESSING_TIMEOUT or 1800.
   --fail-on-upload-error      Exit non-zero on upload failure (default:
                               log error + exit 0).
   --fail-on-partial-build     Exit non-zero when screenshots on disk are
@@ -95,6 +98,9 @@ const parseArgs = (argv) => {
             case '--commit':
                 args.commit = next();
                 break;
+            case '--processing-timeout':
+                args.processingTimeout = next();
+                break;
             case '--fail-on-upload-error':
                 args.failOnUploadError = true;
                 break;
@@ -172,6 +178,16 @@ export const runUpload = async (argv, env = process.env, logger = console) => {
         logger.error(`qlip-upload: ${err.message}`);
         return { exitCode: 1 };
     }
+    const processingTimeout = parsed.processingTimeout ?? env['QLIP_PROCESSING_TIMEOUT'];
+    let processingTimeoutMs;
+    if (processingTimeout !== undefined && processingTimeout !== '') {
+        const seconds = Number(processingTimeout);
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+            logger.error(`qlip-upload: --processing-timeout must be a positive number of seconds, got "${processingTimeout}"`);
+            return { exitCode: 1 };
+        }
+        processingTimeoutMs = seconds * 1000;
+    }
     const project = parsed.project ?? env['QLIP_PROJECT'] ?? 'default';
     const token = parsed.token ?? env['QLIP_UPLOAD_TOKEN'];
     const upload = {
@@ -180,6 +196,7 @@ export const runUpload = async (argv, env = process.env, logger = console) => {
         ...(token !== undefined && token !== '' ? { uploadToken: token } : {}),
         ...(parsed.branch !== undefined ? { branch: parsed.branch } : {}),
         ...(parsed.commit !== undefined ? { commit: parsed.commit } : {}),
+        ...(processingTimeoutMs !== undefined ? { processingTimeoutMs } : {}),
         failOnUploadError: parsed.failOnUploadError,
         failOnPartialBuild: parsed.failOnPartialBuild,
     };

package/dist/types.d.ts

@@ -170,6 +170,12 @@ export interface QlipUploadOptions {
      * Set to `true` in CI when you want red builds on upload errors.
      */
     failOnUploadError?: boolean;
+    /**
+     * How long to wait for the server to answer the requests it answers only
+     * after processing the build (finalize, or the legacy upload), in ms.
+     * Default: 30 minutes. See `design/UPLOAD.md` "Long-running requests".
+     */
+    processingTimeoutMs?: number;
     /**
      * Whether a partial build should fail the run. A build is partial
      * when PNGs exist on disk that no manifest entry references — i.e.

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/upload/processing-request.d.ts

@@ -0,0 +1,15 @@
+/**
+ * HTTP transport for the upload requests qlip-server answers only once it
+ * has processed the whole build: `finalize` and the legacy multipart POST.
+ *
+ * Node's global `fetch` (undici) fails any request whose response headers
+ * take longer than 300 s (`headersTimeout`) with a bare "fetch failed", and
+ * the limit can't be raised without depending on the `undici` package. A
+ * large build's diff runs longer than that, so these requests go through
+ * `node:http`, which imposes no response deadline: the caller's `signal` is
+ * the only one. See design/UPLOAD.md "Long-running requests".
+ */
+/** The subset of `fetch` the upload client uses; `fetch` itself satisfies it. */
+export type TFetchLike = (url: string, init: RequestInit) => Promise<Response>;
+export declare const fetchAwaitingProcessing: TFetchLike;
+//# sourceMappingURL=processing-request.d.ts.map

package/dist/upload/processing-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processing-request.d.ts","sourceRoot":"","sources":["../../src/upload/processing-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAqC/E,eAAO,MAAM,uBAAuB,EAAE,UAsDrC,CAAC"}

package/dist/upload/processing-request.js

@@ -0,0 +1,89 @@
+/**
+ * HTTP transport for the upload requests qlip-server answers only once it
+ * has processed the whole build: `finalize` and the legacy multipart POST.
+ *
+ * Node's global `fetch` (undici) fails any request whose response headers
+ * take longer than 300 s (`headersTimeout`) with a bare "fetch failed", and
+ * the limit can't be raised without depending on the `undici` package. A
+ * large build's diff runs longer than that, so these requests go through
+ * `node:http`, which imposes no response deadline: the caller's `signal` is
+ * the only one. See design/UPLOAD.md "Long-running requests".
+ */
+import http from 'node:http';
+import https from 'node:https';
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+const encodeBody = async (body) => {
+    if (body === undefined || body === null) {
+        return { bytes: new Uint8Array(0), contentType: null };
+    }
+    // Response serializes every BodyInit (FormData gets its multipart boundary).
+    const encoded = new Response(body);
+    return {
+        bytes: new Uint8Array(await encoded.arrayBuffer()),
+        contentType: encoded.headers.get('content-type'),
+    };
+};
+const toResponse = (res, body) => {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(res.headers)) {
+        if (value === undefined)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value]) {
+            headers.append(name, item);
+        }
+    }
+    const status = res.statusCode ?? 0;
+    return new Response(NULL_BODY_STATUSES.has(status) ? null : new Uint8Array(body), {
+        status,
+        statusText: res.statusMessage ?? '',
+        headers,
+    });
+};
+export const fetchAwaitingProcessing = async (url, init) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'https:'
+        ? https
+        : target.protocol === 'http:'
+            ? http
+            : undefined;
+    if (transport === undefined) {
+        throw new TypeError(`unsupported protocol: ${target.protocol}`);
+    }
+    const { bytes, contentType } = await encodeBody(init.body);
+    const headers = {};
+    if (contentType !== null)
+        headers['content-type'] = contentType;
+    new Headers(init.headers).forEach((value, name) => {
+        headers[name] = value;
+    });
+    headers['content-length'] = String(bytes.byteLength);
+    return new Promise((resolve, reject) => {
+        const req = transport.request(target, {
+            method: init.method ?? 'GET',
+            headers,
+            ...(init.signal ? { signal: init.signal } : {}),
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => {
+                chunks.push(chunk);
+            });
+            res.on('error', reject);
+            // A connection dropped mid-body ends the stream without `end`.
+            res.on('close', () => {
+                if (!res.complete) {
+                    reject(new Error('connection closed before the response completed'));
+                }
+            });
+            res.on('end', () => {
+                try {
+                    resolve(toResponse(res, Buffer.concat(chunks)));
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+        req.on('error', reject);
+        req.end(bytes);
+    });
+};

package/dist/upload/upload.d.ts

@@ -3,6 +3,7 @@
  * Wire contract: `qlip-server/design/UPLOAD.md §0`.
  */
 import type { QlipUploadOptions } from '../types.js';
+import type { TFetchLike } from './processing-request.js';
 export interface QlipUploadResult {
     /** Build ID echoed by the server (matches the manifest's buildId). */
     buildId: string;
@@ -20,13 +21,24 @@ export interface QlipUploadInput {
     buildDir: string;
     /** Resolved upload options (branch/commit already auto-detected). */
     options: QlipUploadOptions;
-    /** Override for tests. Defaults to global fetch. */
-    fetchImpl?: typeof fetch;
+    /**
+     * Override for tests. Defaults to global fetch for create + blobs, and to
+     * a `node:http` transport for the finalize / legacy requests the server
+     * answers only after processing (see `processing-request.ts`). An
+     * override is used for every phase, so its own response timeouts apply.
+     */
+    fetchImpl?: TFetchLike;
     /** Base backoff (ms) between blob-PUT retries; test seam, attempt N waits N×. */
     retryBaseDelayMs?: number;
 }
 /** Default server when `upload.serverUrl` is omitted: the hosted instance. */
 export declare const DEFAULT_SERVER_URL = "https://qlip.qoretechnologies.com";
+/**
+ * Default deadline for the finalize / legacy response. qorus-ide builds of
+ * ~2.1k snapshots measured 470–713 s of server processing (2026-10, see
+ * design/UPLOAD.md "Long-running requests"); 30 min leaves 2.5× headroom.
+ */
+export declare const DEFAULT_PROCESSING_TIMEOUT_MS: number;
 export type TUploadPhase = 'create' | 'blob' | 'finalize' | 'legacy';
 /**
  * Resolve the effective server base URL (default applied, trailing slash
@@ -39,5 +51,15 @@ export declare class QlipUploadError extends Error {
     readonly phase: TUploadPhase;
     constructor(status: number, statusText: string, body: string, phase?: TUploadPhase);
 }
+/**
+ * The request never produced an HTTP response: a network error, or no
+ * response before the client's deadline. `status`-less, unlike
+ * `QlipUploadError`.
+ */
+export declare class QlipUploadNetworkError extends Error {
+    readonly phase: TUploadPhase;
+    readonly cause: unknown;
+    constructor(phase: TUploadPhase, cause: unknown, detail?: string);
+}
 export declare const uploadBuild: (input: QlipUploadInput) => Promise<QlipUploadResult>;
 //# sourceMappingURL=upload.d.ts.map

package/dist/upload/upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../src/upload/upload.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGnE,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,IAAI,GAAG,QAAQ,CAAC;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,iBAAiB,CAAC;IAC3B,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,sCAAsC,CAAC;AAOtE,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC,KAC5C,MAAsE,CAAC;AAE1E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAG3B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAuB;CAUjC;AA6JD,eAAO,MAAM,WAAW,GACtB,OAAO,eAAe,KACrB,OAAO,CAAC,gBAAgB,CAkG1B,CAAC"}
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../src/upload/upload.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAgB,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,IAAI,GAAG,QAAQ,CAAC;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,sCAAsC,CAAC;AAMtE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,SAAS,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC,KAC5C,MAAsE,CAAC;AAE1E,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAG3B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,YAAuB;CAUjC;AA4BD;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM;CAQjE;AAiND,eAAO,MAAM,WAAW,GACtB,OAAO,eAAe,KACrB,OAAO,CAAC,gBAAgB,CAgH1B,CAAC"}

package/dist/upload/upload.js

@@ -5,12 +5,19 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { hashFile } from './hash.js';
+import { fetchAwaitingProcessing } from './processing-request.js';
 /** Default server when `upload.serverUrl` is omitted: the hosted instance. */
 export const DEFAULT_SERVER_URL = 'https://qlip.qoretechnologies.com';
 const TRANSFER_CONCURRENCY = 10;
 const BLOB_RETRIES = 2;
 const BLOB_TIMEOUT_MS = 30000;
 const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+/**
+ * Default deadline for the finalize / legacy response. qorus-ide builds of
+ * ~2.1k snapshots measured 470–713 s of server processing (2026-10, see
+ * design/UPLOAD.md "Long-running requests"); 30 min leaves 2.5× headroom.
+ */
+export const DEFAULT_PROCESSING_TIMEOUT_MS = 30 * 60000;
 /**
  * Resolve the effective server base URL (default applied, trailing slash
  * stripped). Exported so log lines report the URL the upload actually hits.
@@ -25,6 +32,76 @@ export class QlipUploadError extends Error {
         this.phase = phase;
     }
 }
+/**
+ * `fetch failed` alone hides why: the reason (a timeout, a reset, a DNS
+ * failure) lives on the `cause` chain, so the message spells that out.
+ */
+const describeCause = (err) => {
+    const parts = [];
+    const seen = new Set();
+    let current = err;
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof Error) {
+            const code = current.code;
+            parts.push(typeof code === 'string' && code !== ''
+                ? `${current.message} (${code})`
+                : current.message);
+            current = current.cause;
+        }
+        else {
+            parts.push(String(current));
+            break;
+        }
+    }
+    return parts.join(': ');
+};
+/**
+ * The request never produced an HTTP response: a network error, or no
+ * response before the client's deadline. `status`-less, unlike
+ * `QlipUploadError`.
+ */
+export class QlipUploadNetworkError extends Error {
+    constructor(phase, cause, detail) {
+        super(`qlip upload failed [${phase}]: ${detail ?? `network error — ${describeCause(cause)}`}`);
+        this.name = 'QlipUploadNetworkError';
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+/** `fetchImpl`, with a transport failure reported as a phase-tagged error. */
+const withPhase = (phase, fetchImpl) => async (url, init) => {
+    try {
+        return await fetchImpl(url, init);
+    }
+    catch (err) {
+        throw new QlipUploadNetworkError(phase, err);
+    }
+};
+/**
+ * Send a request the server answers only after processing the build. No
+ * retry: the server keeps processing after a dropped connection, and a
+ * second finalize would race the first.
+ */
+const sendAwaitingProcessing = async (phase, fetchImpl, url, init, timeoutMs) => {
+    const signal = AbortSignal.timeout(timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal });
+    }
+    catch (err) {
+        if (signal.aborted) {
+            throw new QlipUploadNetworkError(phase, err, `no response within ${String(timeoutMs / 1000)} s; the server may still be processing the build — check it in the dashboard, and raise the processing timeout if builds this size take longer`);
+        }
+        throw new QlipUploadNetworkError(phase, err);
+    }
+};
+const resolveProcessingTimeoutMs = (options) => {
+    const value = options.processingTimeoutMs ?? DEFAULT_PROCESSING_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`upload.processingTimeoutMs must be a positive number of milliseconds, got ${String(value)}`);
+    }
+    return value;
+};
 /** Contextual hint appended to 413s, tailored to the phase that hit it. */
 const hintFor = (status, phase) => {
     if (status !== 413)
@@ -97,10 +174,12 @@ const putBlob = async (fetchImpl, url, bytes, baseHeaders, retryBaseDelayMs) =>
         if (attempt < BLOB_RETRIES)
             await delay(retryBaseDelayMs * (attempt + 1));
     }
-    throw lastError;
+    if (lastError instanceof QlipUploadError)
+        throw lastError;
+    throw new QlipUploadNetworkError('blob', lastError);
 };
 /** Pre-v2 single-multipart upload; fallback when the server lacks v2 routes. */
-const uploadBuildLegacy = async (fetchImpl, baseUrl, buildDir, options, manifest) => {
+const uploadBuildLegacy = async (fetchImpl, baseUrl, buildDir, options, manifest, processingTimeoutMs) => {
     const form = new FormData();
     form.append('manifest', new Blob([JSON.stringify(manifest)], { type: 'application/json' }), 'manifest.json');
     const captured = manifest.entries.filter((e) => e.status === 'captured');
@@ -131,18 +210,16 @@ const uploadBuildLegacy = async (fetchImpl, baseUrl, buildDir, options, manifest
     if (options.triggeredById !== undefined) {
         form.append('triggeredById', String(options.triggeredById));
     }
-    const response = await fetchImpl(`${baseUrl}/api/builds/upload`, {
-        method: 'POST',
-        body: form,
-        headers: authHeaders(options),
-    });
+    const response = await sendAwaitingProcessing('legacy', fetchImpl, `${baseUrl}/api/builds/upload`, { method: 'POST', body: form, headers: authHeaders(options) }, processingTimeoutMs);
     if (!response.ok)
         throw await errorFromResponse(response, 'legacy');
     return { buildId: manifest.buildId, status: response.status, protocol: 'legacy' };
 };
 export const uploadBuild = async (input) => {
     const { buildDir, options } = input;
+    const processingTimeoutMs = resolveProcessingTimeoutMs(options);
     const fetchImpl = input.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const processingFetch = input.fetchImpl ?? fetchAwaitingProcessing;
     const retryBaseDelayMs = input.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
     const baseUrl = resolveServerUrl(options);
     const headers = authHeaders(options);
@@ -154,7 +231,8 @@ export const uploadBuild = async (input) => {
         entry.sha256 = sha256;
         entry.sizeBytes = sizeBytes;
     });
-    const createResponse = await fetchImpl(`${baseUrl}/api/builds`, {
+    const createFetch = withPhase('create', fetchImpl);
+    const createResponse = await createFetch(`${baseUrl}/api/builds`, {
         method: 'POST',
         headers: { ...headers, 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -181,7 +259,7 @@ export const uploadBuild = async (input) => {
     });
     // 404 ⇒ server predates the v2 routes; fall back to legacy multipart.
     if (createResponse.status === 404) {
-        return uploadBuildLegacy(fetchImpl, baseUrl, buildDir, options, manifest);
+        return uploadBuildLegacy(processingFetch, baseUrl, buildDir, options, manifest, processingTimeoutMs);
     }
     if (!createResponse.ok)
         throw await errorFromResponse(createResponse, 'create');
@@ -201,7 +279,7 @@ export const uploadBuild = async (input) => {
         const bytes = await readFile(path.join(buildDir, relPath));
         await putBlob(fetchImpl, `${baseUrl}/api/builds/${buildPath}/blobs/${key}`, bytes, headers, retryBaseDelayMs);
     });
-    const finalizeResponse = await fetchImpl(`${baseUrl}/api/builds/${buildPath}/finalize`, { method: 'POST', headers });
+    const finalizeResponse = await sendAwaitingProcessing('finalize', processingFetch, `${baseUrl}/api/builds/${buildPath}/finalize`, { method: 'POST', headers }, processingTimeoutMs);
     if (!finalizeResponse.ok) {
         throw await errorFromResponse(finalizeResponse, 'finalize');
     }

package/dist-cjs/test-runner/cli/upload.js

@@ -58,6 +58,9 @@ Options:
   --token <token>             Bearer token. Default: \$QLIP_UPLOAD_TOKEN.
   --branch <branch>           Override branch detection.
   --commit <sha>              Override commit detection.
+  --processing-timeout <s>    Seconds to wait for the server to process
+                              the build. Default:
+                              \$QLIP_PROCESSING_TIMEOUT or 1800.
   --fail-on-upload-error      Exit non-zero on upload failure (default:
                               log error + exit 0).
   --fail-on-partial-build     Exit non-zero when screenshots on disk are
@@ -101,6 +104,9 @@ const parseArgs = (argv) => {
             case '--commit':
                 args.commit = next();
                 break;
+            case '--processing-timeout':
+                args.processingTimeout = next();
+                break;
             case '--fail-on-upload-error':
                 args.failOnUploadError = true;
                 break;
@@ -178,6 +184,16 @@ const runUpload = async (argv, env = process.env, logger = console) => {
         logger.error(`qlip-upload: ${err.message}`);
         return { exitCode: 1 };
     }
+    const processingTimeout = parsed.processingTimeout ?? env['QLIP_PROCESSING_TIMEOUT'];
+    let processingTimeoutMs;
+    if (processingTimeout !== undefined && processingTimeout !== '') {
+        const seconds = Number(processingTimeout);
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+            logger.error(`qlip-upload: --processing-timeout must be a positive number of seconds, got "${processingTimeout}"`);
+            return { exitCode: 1 };
+        }
+        processingTimeoutMs = seconds * 1000;
+    }
     const project = parsed.project ?? env['QLIP_PROJECT'] ?? 'default';
     const token = parsed.token ?? env['QLIP_UPLOAD_TOKEN'];
     const upload = {
@@ -186,6 +202,7 @@ const runUpload = async (argv, env = process.env, logger = console) => {
         ...(token !== undefined && token !== '' ? { uploadToken: token } : {}),
         ...(parsed.branch !== undefined ? { branch: parsed.branch } : {}),
         ...(parsed.commit !== undefined ? { commit: parsed.commit } : {}),
+        ...(processingTimeoutMs !== undefined ? { processingTimeoutMs } : {}),
         failOnUploadError: parsed.failOnUploadError,
         failOnPartialBuild: parsed.failOnPartialBuild,
     };

package/dist-cjs/upload/processing-request.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * HTTP transport for the upload requests qlip-server answers only once it
+ * has processed the whole build: `finalize` and the legacy multipart POST.
+ *
+ * Node's global `fetch` (undici) fails any request whose response headers
+ * take longer than 300 s (`headersTimeout`) with a bare "fetch failed", and
+ * the limit can't be raised without depending on the `undici` package. A
+ * large build's diff runs longer than that, so these requests go through
+ * `node:http`, which imposes no response deadline: the caller's `signal` is
+ * the only one. See design/UPLOAD.md "Long-running requests".
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchAwaitingProcessing = void 0;
+const node_http_1 = __importDefault(require("node:http"));
+const node_https_1 = __importDefault(require("node:https"));
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+const encodeBody = async (body) => {
+    if (body === undefined || body === null) {
+        return { bytes: new Uint8Array(0), contentType: null };
+    }
+    // Response serializes every BodyInit (FormData gets its multipart boundary).
+    const encoded = new Response(body);
+    return {
+        bytes: new Uint8Array(await encoded.arrayBuffer()),
+        contentType: encoded.headers.get('content-type'),
+    };
+};
+const toResponse = (res, body) => {
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(res.headers)) {
+        if (value === undefined)
+            continue;
+        for (const item of Array.isArray(value) ? value : [value]) {
+            headers.append(name, item);
+        }
+    }
+    const status = res.statusCode ?? 0;
+    return new Response(NULL_BODY_STATUSES.has(status) ? null : new Uint8Array(body), {
+        status,
+        statusText: res.statusMessage ?? '',
+        headers,
+    });
+};
+const fetchAwaitingProcessing = async (url, init) => {
+    const target = new URL(url);
+    const transport = target.protocol === 'https:'
+        ? node_https_1.default
+        : target.protocol === 'http:'
+            ? node_http_1.default
+            : undefined;
+    if (transport === undefined) {
+        throw new TypeError(`unsupported protocol: ${target.protocol}`);
+    }
+    const { bytes, contentType } = await encodeBody(init.body);
+    const headers = {};
+    if (contentType !== null)
+        headers['content-type'] = contentType;
+    new Headers(init.headers).forEach((value, name) => {
+        headers[name] = value;
+    });
+    headers['content-length'] = String(bytes.byteLength);
+    return new Promise((resolve, reject) => {
+        const req = transport.request(target, {
+            method: init.method ?? 'GET',
+            headers,
+            ...(init.signal ? { signal: init.signal } : {}),
+        }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => {
+                chunks.push(chunk);
+            });
+            res.on('error', reject);
+            // A connection dropped mid-body ends the stream without `end`.
+            res.on('close', () => {
+                if (!res.complete) {
+                    reject(new Error('connection closed before the response completed'));
+                }
+            });
+            res.on('end', () => {
+                try {
+                    resolve(toResponse(res, Buffer.concat(chunks)));
+                }
+                catch (err) {
+                    reject(err);
+                }
+            });
+        });
+        req.on('error', reject);
+        req.end(bytes);
+    });
+};
+exports.fetchAwaitingProcessing = fetchAwaitingProcessing;

package/dist-cjs/upload/upload.js

@@ -7,16 +7,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.uploadBuild = exports.QlipUploadError = exports.resolveServerUrl = exports.DEFAULT_SERVER_URL = void 0;
+exports.uploadBuild = exports.QlipUploadNetworkError = exports.QlipUploadError = exports.resolveServerUrl = exports.DEFAULT_PROCESSING_TIMEOUT_MS = exports.DEFAULT_SERVER_URL = void 0;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const hash_js_1 = require("./hash.js");
+const processing_request_js_1 = require("./processing-request.js");
 /** Default server when `upload.serverUrl` is omitted: the hosted instance. */
 exports.DEFAULT_SERVER_URL = 'https://qlip.qoretechnologies.com';
 const TRANSFER_CONCURRENCY = 10;
 const BLOB_RETRIES = 2;
 const BLOB_TIMEOUT_MS = 30000;
 const DEFAULT_RETRY_BASE_DELAY_MS = 500;
+/**
+ * Default deadline for the finalize / legacy response. qorus-ide builds of
+ * ~2.1k snapshots measured 470–713 s of server processing (2026-10, see
+ * design/UPLOAD.md "Long-running requests"); 30 min leaves 2.5× headroom.
+ */
+exports.DEFAULT_PROCESSING_TIMEOUT_MS = 30 * 60000;
 /**
  * Resolve the effective server base URL (default applied, trailing slash
  * stripped). Exported so log lines report the URL the upload actually hits.
@@ -33,6 +40,77 @@ class QlipUploadError extends Error {
     }
 }
 exports.QlipUploadError = QlipUploadError;
+/**
+ * `fetch failed` alone hides why: the reason (a timeout, a reset, a DNS
+ * failure) lives on the `cause` chain, so the message spells that out.
+ */
+const describeCause = (err) => {
+    const parts = [];
+    const seen = new Set();
+    let current = err;
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        if (current instanceof Error) {
+            const code = current.code;
+            parts.push(typeof code === 'string' && code !== ''
+                ? `${current.message} (${code})`
+                : current.message);
+            current = current.cause;
+        }
+        else {
+            parts.push(String(current));
+            break;
+        }
+    }
+    return parts.join(': ');
+};
+/**
+ * The request never produced an HTTP response: a network error, or no
+ * response before the client's deadline. `status`-less, unlike
+ * `QlipUploadError`.
+ */
+class QlipUploadNetworkError extends Error {
+    constructor(phase, cause, detail) {
+        super(`qlip upload failed [${phase}]: ${detail ?? `network error — ${describeCause(cause)}`}`);
+        this.name = 'QlipUploadNetworkError';
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+exports.QlipUploadNetworkError = QlipUploadNetworkError;
+/** `fetchImpl`, with a transport failure reported as a phase-tagged error. */
+const withPhase = (phase, fetchImpl) => async (url, init) => {
+    try {
+        return await fetchImpl(url, init);
+    }
+    catch (err) {
+        throw new QlipUploadNetworkError(phase, err);
+    }
+};
+/**
+ * Send a request the server answers only after processing the build. No
+ * retry: the server keeps processing after a dropped connection, and a
+ * second finalize would race the first.
+ */
+const sendAwaitingProcessing = async (phase, fetchImpl, url, init, timeoutMs) => {
+    const signal = AbortSignal.timeout(timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal });
+    }
+    catch (err) {
+        if (signal.aborted) {
+            throw new QlipUploadNetworkError(phase, err, `no response within ${String(timeoutMs / 1000)} s; the server may still be processing the build — check it in the dashboard, and raise the processing timeout if builds this size take longer`);
+        }
+        throw new QlipUploadNetworkError(phase, err);
+    }
+};
+const resolveProcessingTimeoutMs = (options) => {
+    const value = options.processingTimeoutMs ?? exports.DEFAULT_PROCESSING_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`upload.processingTimeoutMs must be a positive number of milliseconds, got ${String(value)}`);
+    }
+    return value;
+};
 /** Contextual hint appended to 413s, tailored to the phase that hit it. */
 const hintFor = (status, phase) => {
     if (status !== 413)
@@ -105,10 +183,12 @@ const putBlob = async (fetchImpl, url, bytes, baseHeaders, retryBaseDelayMs) =>
         if (attempt < BLOB_RETRIES)
             await delay(retryBaseDelayMs * (attempt + 1));
     }
-    throw lastError;
+    if (lastError instanceof QlipUploadError)
+        throw lastError;
+    throw new QlipUploadNetworkError('blob', lastError);
 };
 /** Pre-v2 single-multipart upload; fallback when the server lacks v2 routes. */
-const uploadBuildLegacy = async (fetchImpl, baseUrl, buildDir, options, manifest) => {
+const uploadBuildLegacy = async (fetchImpl, baseUrl, buildDir, options, manifest, processingTimeoutMs) => {
     const form = new FormData();
     form.append('manifest', new Blob([JSON.stringify(manifest)], { type: 'application/json' }), 'manifest.json');
     const captured = manifest.entries.filter((e) => e.status === 'captured');
@@ -139,18 +219,16 @@ const uploadBuildLegacy = async (fetchImpl, baseUrl, buildDir, options, manifest
     if (options.triggeredById !== undefined) {
         form.append('triggeredById', String(options.triggeredById));
     }
-    const response = await fetchImpl(`${baseUrl}/api/builds/upload`, {
-        method: 'POST',
-        body: form,
-        headers: authHeaders(options),
-    });
+    const response = await sendAwaitingProcessing('legacy', fetchImpl, `${baseUrl}/api/builds/upload`, { method: 'POST', body: form, headers: authHeaders(options) }, processingTimeoutMs);
     if (!response.ok)
         throw await errorFromResponse(response, 'legacy');
     return { buildId: manifest.buildId, status: response.status, protocol: 'legacy' };
 };
 const uploadBuild = async (input) => {
     const { buildDir, options } = input;
+    const processingTimeoutMs = resolveProcessingTimeoutMs(options);
     const fetchImpl = input.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const processingFetch = input.fetchImpl ?? processing_request_js_1.fetchAwaitingProcessing;
     const retryBaseDelayMs = input.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
     const baseUrl = (0, exports.resolveServerUrl)(options);
     const headers = authHeaders(options);
@@ -162,7 +240,8 @@ const uploadBuild = async (input) => {
         entry.sha256 = sha256;
         entry.sizeBytes = sizeBytes;
     });
-    const createResponse = await fetchImpl(`${baseUrl}/api/builds`, {
+    const createFetch = withPhase('create', fetchImpl);
+    const createResponse = await createFetch(`${baseUrl}/api/builds`, {
         method: 'POST',
         headers: { ...headers, 'Content-Type': 'application/json' },
         body: JSON.stringify({
@@ -189,7 +268,7 @@ const uploadBuild = async (input) => {
     });
     // 404 ⇒ server predates the v2 routes; fall back to legacy multipart.
     if (createResponse.status === 404) {
-        return uploadBuildLegacy(fetchImpl, baseUrl, buildDir, options, manifest);
+        return uploadBuildLegacy(processingFetch, baseUrl, buildDir, options, manifest, processingTimeoutMs);
     }
     if (!createResponse.ok)
         throw await errorFromResponse(createResponse, 'create');
@@ -209,7 +288,7 @@ const uploadBuild = async (input) => {
         const bytes = await (0, promises_1.readFile)(node_path_1.default.join(buildDir, relPath));
         await putBlob(fetchImpl, `${baseUrl}/api/builds/${buildPath}/blobs/${key}`, bytes, headers, retryBaseDelayMs);
     });
-    const finalizeResponse = await fetchImpl(`${baseUrl}/api/builds/${buildPath}/finalize`, { method: 'POST', headers });
+    const finalizeResponse = await sendAwaitingProcessing('finalize', processingFetch, `${baseUrl}/api/builds/${buildPath}/finalize`, { method: 'POST', headers }, processingTimeoutMs);
     if (!finalizeResponse.ok) {
         throw await errorFromResponse(finalizeResponse, 'finalize');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qoretechnologies/qlip",
-  "version": "0.1.3-pr.31.g4b62f97",
+  "version": "0.1.3-pr.32.g3ecd7a4",
   "description": "Storybook screenshot capture for the Vitest addon",
   "type": "module",
   "main": "./dist/index.js",