@devicecloud.dev/dcd 5.0.0-beta.0 → 5.0.0-beta.2

package/dist/services/results-polling.service.js

@@ -1,16 +1,16 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResultsPollingService = exports.RunFailedError = void 0;
-const path = require("node:path");
-const api_gateway_1 = require("../gateways/api-gateway");
-const methods_1 = require("../methods");
-const connectivity_1 = require("../utils/connectivity");
-const progress_1 = require("../utils/progress");
-const styling_1 = require("../utils/styling");
+import * as path from 'node:path';
+import { ApiGateway } from '../gateways/api-gateway.js';
+import { RealtimeResultsGateway, } from '../gateways/realtime-gateway.js';
+import { formatDurationSeconds } from '../methods.js';
+import { checkInternetConnectivity } from '../utils/connectivity.js';
+import { isCI } from '../utils/ci.js';
+import { ux } from '../utils/progress.js';
+import { colors, formatTestSummary, statusPalette, table } from '../utils/styling.js';
+import { ui } from '../utils/ui.js';
 /**
  * Custom error for run failures that includes the polling result
  */
-class RunFailedError extends Error {
+export class RunFailedError extends Error {
     result;
     constructor(result) {
         super('RUN_FAILED');
@@ -18,18 +18,22 @@ class RunFailedError extends Error {
         this.name = 'RunFailedError';
     }
 }
-exports.RunFailedError = RunFailedError;
 /**
  * Service for polling test results from the API
  */
-class ResultsPollingService {
+export class ResultsPollingService {
     // The run keeps executing in the cloud regardless of whether the CLI can
-    // poll, so tolerate a long stretch of transient API/network blips (~5 min at
-    // the 10s base interval) before giving up. Losing a run to a brief hiccup is
-    // far more costly than waiting a bit longer.
+    // poll, so tolerate a long stretch of transient API/network blips before
+    // giving up. Losing a run to a brief hiccup is far more costly than waiting a
+    // bit longer.
     MAX_SEQUENTIAL_FAILURES = 30;
-    POLL_INTERVAL_MS = 10_000;
-    // Cap for the backoff applied between failed polls.
+    // Backstop poll cadence. Logged-in (bearer) users also get realtime pushes
+    // (see RealtimeResultsGateway), so they only need an occasional reconciling
+    // poll; api-key users have no realtime and rely on the faster interval.
+    BEARER_POLL_INTERVAL_MS = 60_000;
+    APIKEY_POLL_INTERVAL_MS = 20_000;
+    // Base unit for the backoff applied between *failed* polls, and its cap.
+    ERROR_BACKOFF_BASE_MS = 10_000;
     MAX_ERROR_BACKOFF_MS = 30_000;
     /**
      * Poll for test results until all tests complete
@@ -46,7 +50,7 @@ class ResultsPollingService {
             // displayFinalResults. Anything else aborts mid-poll with the spinner
             // still live, which would corrupt the terminal under the error output.
             if (!options.json && !(error instanceof RunFailedError)) {
-                progress_1.ux.action.stop(styling_1.colors.error('failed'));
+                ux.action.stop(colors.error('failed'));
             }
             throw error;
         }
@@ -55,44 +59,148 @@ class ResultsPollingService {
         const { apiUrl, auth, uploadId, consoleUrl, quiet = false, json = false, debug = false, logger } = options;
         this.initializePollingDisplay(json, logger);
         let sequentialPollFailures = 0;
-        let previousSummary = '';
+        const pollIntervalMs = auth.mode === 'bearer'
+            ? this.BEARER_POLL_INTERVAL_MS
+            : this.APIKEY_POLL_INTERVAL_MS;
+        // "Poke" mechanism: a realtime change resolves the current inter-poll wait
+        // early. If a poke lands while we're mid-fetch (not waiting) it's latched
+        // and consumed by the next wait, so events are never silently dropped.
+        let resolveWake = null;
+        let pendingPoke = false;
+        const poke = () => {
+            if (resolveWake) {
+                const r = resolveWake;
+                resolveWake = null;
+                r();
+            }
+            else {
+                pendingPoke = true;
+            }
+        };
+        const waitForNextPoll = (ms) => {
+            if (pendingPoke) {
+                pendingPoke = false;
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    resolveWake = null;
+                    resolve();
+                }, ms);
+                resolveWake = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+        };
+        // Live display state, recomposed by renderStatus() so the footer (countdown
+        // to the next backstop poll + realtime connection state) stays current
+        // between polls without re-fetching. `nextPollAt` is an epoch-ms deadline
+        // while waiting, or null while a fetch is in flight.
+        let subscription;
+        let realtimeEnabled = false;
+        let statusBody = '';
+        let nextPollAt = null;
+        // The animated footer/countdown only makes sense on a TTY. In CI/pipes it
+        // would flood logs (a fresh line per frame), so we drop it and let the
+        // progress adapter print one line per distinct status change instead.
+        const interactive = !json && !isCI();
+        const renderStatus = () => {
+            if (json)
+                return;
+            if (!interactive) {
+                ux.action.status = statusBody;
+                return;
+            }
+            const footer = this.buildStatusFooter(realtimeEnabled, subscription?.isConnected() ?? false, nextPollAt, quiet);
+            ux.action.status = footer ? `${statusBody}\n${footer}` : statusBody;
+        };
+        // Realtime is a latency optimisation over the backstop poll; only logged-in
+        // (bearer) users can authenticate the socket under RLS. Any failure inside
+        // the gateway degrades silently to pure polling.
+        if (auth.mode === 'bearer' && auth.accessToken && auth.orgId && auth.env) {
+            realtimeEnabled = true;
+            subscription = RealtimeResultsGateway.subscribe({
+                accessToken: auth.accessToken,
+                debug,
+                env: auth.env,
+                log: logger,
+                onChange: poke,
+                // Reflect connect/disconnect in the live footer immediately rather than
+                // waiting for the next ticker frame.
+                onConnectionChange: renderStatus,
+                orgId: auth.orgId,
+                uploadId,
+            });
+            if (debug && logger) {
+                logger(`[DEBUG] Realtime enabled; backstop poll every ${pollIntervalMs / 1000}s`);
+            }
+        }
         if (debug && logger) {
             logger(`[DEBUG] Starting polling loop for results`);
         }
-        // Poll in a loop until all tests complete
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            try {
-                const updatedResults = await this.fetchAndLogResults(apiUrl, auth, uploadId, debug, logger);
-                const { summary } = this.calculateStatusSummary(updatedResults);
-                previousSummary = this.updateDisplayStatus(updatedResults, quiet, json, summary, previousSummary);
-                const allComplete = updatedResults.every((result) => !['PENDING', 'QUEUED', 'RUNNING'].includes(result.status));
-                if (allComplete) {
-                    return await this.handleCompletedTests(updatedResults, {
-                        consoleUrl,
-                        debug,
-                        json,
-                        logger,
-                        testMetadata,
-                        uploadId,
-                    });
+        // Tick the live footer once a second so the countdown actually counts down
+        // (the spinner's own frames don't recompute our message). Unref'd so it
+        // never keeps the process alive on its own. Only on an interactive TTY —
+        // a 1s ticker in CI would reprint the status every second.
+        const ticker = interactive
+            ? setInterval(renderStatus, 1000)
+            : null;
+        ticker?.unref?.();
+        try {
+            // Poll in a loop until all tests complete
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                try {
+                    nextPollAt = null;
+                    renderStatus();
+                    const updatedResults = await this.fetchAndLogResults(apiUrl, auth, uploadId, debug, logger);
+                    const { summary } = this.calculateStatusSummary(updatedResults);
+                    if (!json) {
+                        statusBody = this.buildStatusBody(updatedResults, quiet, summary);
+                    }
+                    const allComplete = updatedResults.every((result) => !['PENDING', 'QUEUED', 'RUNNING'].includes(result.status));
+                    if (allComplete) {
+                        return await this.handleCompletedTests(updatedResults, {
+                            consoleUrl,
+                            debug,
+                            json,
+                            logger,
+                            testMetadata,
+                            uploadId,
+                        });
+                    }
+                    // Reset failure counter on successful poll
+                    sequentialPollFailures = 0;
+                    // Wait for the next backstop poll, or a realtime poke, whichever comes
+                    // first, while the footer counts down to the deadline.
+                    nextPollAt = Date.now() + pollIntervalMs;
+                    renderStatus();
+                    await waitForNextPoll(pollIntervalMs);
                 }
-                // Reset failure counter on successful poll
-                sequentialPollFailures = 0;
-                // Wait before next poll
-                await this.sleep(this.POLL_INTERVAL_MS);
+                catch (error) {
+                    // Re-throw RunFailedError immediately (test failures, not polling errors)
+                    if (error instanceof RunFailedError) {
+                        throw error;
+                    }
+                    sequentialPollFailures++;
+                    // Handle polling errors (network issues, etc.)
+                    await this.handlePollingError(error, sequentialPollFailures, debug, logger, uploadId);
+                    // Back off (capped) before retrying so a flaky API gets some breathing
+                    // room instead of being hammered on every failure.
+                    await this.sleep(Math.min(this.ERROR_BACKOFF_BASE_MS * sequentialPollFailures, this.MAX_ERROR_BACKOFF_MS));
+                }
+            }
+        }
+        finally {
+            if (ticker) {
+                clearInterval(ticker);
             }
-            catch (error) {
-                // Re-throw RunFailedError immediately (test failures, not polling errors)
-                if (error instanceof RunFailedError) {
-                    throw error;
+            if (subscription) {
+                if (debug && logger) {
+                    logger('[DEBUG] Closing realtime subscription');
                 }
-                sequentialPollFailures++;
-                // Handle polling errors (network issues, etc.)
-                await this.handlePollingError(error, sequentialPollFailures, debug, logger, uploadId);
-                // Back off (capped) before retrying so a flaky API gets some breathing
-                // room instead of being hammered every 10s.
-                await this.sleep(Math.min(this.POLL_INTERVAL_MS * sequentialPollFailures, this.MAX_ERROR_BACKOFF_MS));
+                await subscription.unsubscribe();
             }
         }
     }
@@ -129,7 +237,7 @@ class ResultsPollingService {
         const running = statusCounts.RUNNING || 0;
         const total = results.length;
         const completed = passed + failed;
-        const summary = (0, styling_1.formatTestSummary)({
+        const summary = formatTestSummary({
             completed,
             failed,
             passed,
@@ -144,48 +252,29 @@ class ResultsPollingService {
         if (json) {
             return;
         }
-        progress_1.ux.action.stop(styling_1.colors.success('completed'));
+        ux.action.stop(colors.success('completed'));
         if (logger) {
             logger('\n');
         }
         const hasFailedTests = results.some((result) => result.status === 'FAILED');
-        (0, styling_1.table)(results, {
+        table(results, {
             duration: {
                 get(row) {
                     return row.duration_seconds
-                        ? styling_1.colors.dim((0, methods_1.formatDurationSeconds)(Number(row.duration_seconds)))
-                        : styling_1.colors.dim('-');
+                        ? colors.dim(formatDurationSeconds(Number(row.duration_seconds)))
+                        : colors.dim('-');
                 },
             },
             status: {
                 get(row) {
-                    const statusUpper = row.status.toUpperCase();
-                    switch (statusUpper) {
-                        case 'PASSED': {
-                            return styling_1.colors.success(row.status);
-                        }
-                        case 'FAILED': {
-                            return styling_1.colors.error(row.status);
-                        }
-                        case 'RUNNING': {
-                            return styling_1.colors.info(row.status);
-                        }
-                        case 'PENDING': {
-                            return styling_1.colors.warning(row.status);
-                        }
-                        case 'QUEUED': {
-                            return styling_1.colors.dim(row.status);
-                        }
-                        default: {
-                            return styling_1.colors.dim(row.status);
-                        }
-                    }
+                    const { color } = statusPalette(row.status);
+                    return color(row.status.toLowerCase());
                 },
             },
             test: {
                 get(row) {
                     const testName = row.test_file_name;
-                    const retry = row.retry_of ? styling_1.colors.dim(' (retry)') : '';
+                    const retry = row.retry_of ? colors.dim(' (retry)') : '';
                     return `${testName}${retry}`;
                 },
             },
@@ -194,7 +283,7 @@ class ResultsPollingService {
                 fail_reason: {
                     get(row) {
                         return row.status === 'FAILED' && row.fail_reason
-                            ? styling_1.colors.error(row.fail_reason)
+                            ? colors.error(row.fail_reason)
                             : '';
                     },
                 },
@@ -202,8 +291,8 @@ class ResultsPollingService {
         }, { printLine: logger });
         if (logger) {
             logger('\n');
-            logger(styling_1.colors.bold('Run completed') + styling_1.colors.dim(', you can access the results at:'));
-            logger(styling_1.colors.url(consoleUrl));
+            logger(ui.success('Run completed'));
+            logger(ui.branch(ui.fields([['results', colors.url(consoleUrl)]])));
             logger('\n');
         }
     }
@@ -220,7 +309,7 @@ class ResultsPollingService {
         if (debug && logger) {
             logger(`[DEBUG] Polling for results: ${uploadId}`);
         }
-        const { results: updatedResults } = await api_gateway_1.ApiGateway.getResultsForUpload(apiUrl, auth, uploadId);
+        const { results: updatedResults } = await ApiGateway.getResultsForUpload(apiUrl, auth, uploadId);
         // An empty array would otherwise read as "all complete, all passed".
         if (!updatedResults || updatedResults.length === 0) {
             throw new Error('no results');
@@ -298,7 +387,7 @@ class ResultsPollingService {
             if (debug && logger) {
                 logger('[DEBUG] Checking internet connectivity...');
             }
-            const connectivityCheck = await (0, connectivity_1.checkInternetConnectivity)();
+            const connectivityCheck = await checkInternetConnectivity();
             if (debug && logger) {
                 logger(`[DEBUG] ${connectivityCheck.message}`);
                 for (const result of connectivityCheck.endpointResults) {
@@ -330,11 +419,11 @@ class ResultsPollingService {
      */
     initializePollingDisplay(json, logger) {
         if (!json) {
-            progress_1.ux.action.start(styling_1.colors.bold('Waiting for results'), styling_1.colors.dim('Initializing'), {
+            ux.action.start(colors.bold('Waiting for results'), colors.dim('Initializing'), {
                 stdout: true,
             });
             if (logger) {
-                logger(styling_1.colors.dim('\nYou can safely close this terminal and the tests will continue\n'));
+                logger(colors.dim('\nYou can safely close this terminal and the tests will continue\n'));
             }
         }
     }
@@ -348,33 +437,47 @@ class ResultsPollingService {
             setTimeout(resolve, ms);
         });
     }
-    updateDisplayStatus(results, quiet, json, summary, previousSummary) {
-        if (json) {
-            return previousSummary;
-        }
+    /**
+     * Build the body of the live status display (the per-test table, or just the
+     * one-line summary in quiet mode). The footer (countdown + realtime state) is
+     * appended separately by {@link buildStatusFooter} so it can re-render on a
+     * timer without re-fetching.
+     */
+    buildStatusBody(results, quiet, summary) {
         if (quiet) {
-            if (summary !== previousSummary) {
-                progress_1.ux.action.status = summary;
-                return summary;
-            }
+            return summary;
         }
-        else {
-            progress_1.ux.action.status = styling_1.colors.dim('\nStatus      Test\n─────────── ───────────────');
-            for (const { retry_of: isRetry, status, test_file_name: test, } of results) {
-                const statusFormatted = status.toUpperCase() === 'PASSED'
-                    ? styling_1.colors.success(status.padEnd(10, ' '))
-                    : status.toUpperCase() === 'FAILED'
-                        ? styling_1.colors.error(status.padEnd(10, ' '))
-                        : status.toUpperCase() === 'RUNNING'
-                            ? styling_1.colors.info(status.padEnd(10, ' '))
-                            : status.toUpperCase() === 'QUEUED'
-                                ? styling_1.colors.dim(status.padEnd(10, ' '))
-                                : styling_1.colors.warning(status.padEnd(10, ' '));
-                const retryText = isRetry ? styling_1.colors.dim(' (retry)') : '';
-                progress_1.ux.action.status += `\n${statusFormatted}  ${test}${retryText}`;
+        const rows = results.map(({ retry_of: isRetry, status, test_file_name: test }) => {
+            const label = `${ui.statusSymbol(status)} ${ui.statusWord(status)}`;
+            const retryText = isRetry ? colors.dim(' (retry)') : '';
+            return [label, `${test}${retryText}`];
+        });
+        return `\n${ui.branch(ui.fields(rows))}`;
+    }
+    /**
+     * Build the live footer shown under the status display: whether realtime
+     * updates are connected (for logged-in users) and how long until the next
+     * backstop poll. While a fetch is in flight (`nextPollAt` is null) the
+     * countdown reads "refreshing…". In quiet mode the countdown is omitted.
+     */
+    buildStatusFooter(realtimeEnabled, realtimeConnected, nextPollAt, quiet) {
+        const parts = [];
+        if (realtimeEnabled) {
+            parts.push(realtimeConnected
+                ? colors.success('● realtime connected')
+                : colors.warning('○ realtime connecting…'));
+        }
+        // The countdown to the next backstop poll is noise in quiet mode (geared at
+        // CI), so suppress it there while keeping the realtime indicator.
+        if (!quiet) {
+            if (nextPollAt === null) {
+                parts.push(colors.dim('refreshing…'));
+            }
+            else {
+                const secondsLeft = Math.max(0, Math.ceil((nextPollAt - Date.now()) / 1000));
+                parts.push(colors.dim(`next refresh in ${secondsLeft}s`));
             }
         }
-        return previousSummary;
+        return parts.join(colors.dim('  ·  '));
     }
 }
-exports.ResultsPollingService = ResultsPollingService;

package/dist/services/telemetry.service.d.ts

@@ -1,4 +1,4 @@
-import type { AuthContext } from '../types/domain/auth.types';
+import type { AuthContext } from '../types/domain/auth.types.js';
 export type TelemetryLevel = 'log' | 'info' | 'warn' | 'error';
 declare class Telemetry {
     private buffer;
@@ -19,7 +19,16 @@ declare class Telemetry {
         auth: AuthContext;
         apiUrl?: string;
     }): void;
+    /**
+     * Override the command label attached to telemetry meta. The MCP server is
+     * long-lived and isn't a citty subcommand, so `inferCommandFromArgv` can't
+     * name it — `src/mcp/index.ts` calls this at boot.
+     */
+    setCommand(command: string): void;
     recordCommandStart(): void;
+    recordMcpToolStart(tool: string): void;
+    recordMcpToolSuccess(tool: string, durationMs: number): void;
+    recordMcpToolFailure(tool: string, error: unknown, durationMs: number): void;
     recordCommandSuccess(): void;
     recordCommandFailure(opts: {
         error: Error | string;

package/dist/services/telemetry.service.js

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.telemetry = void 0;
 /**
  * Ships CLI lifecycle + error events to Axiom via the API's `/cli/logs`
  * proxy (forwards to `cli-dev` / `cli-prod`). The proxy authenticates with
@@ -15,21 +12,21 @@ exports.telemetry = void 0;
  *
  * Opt out: `DCD_TELEMETRY_DISABLED=1` in the environment.
  */
-const node_child_process_1 = require("node:child_process");
-const node_crypto_1 = require("node:crypto");
-const node_fs_1 = require("node:fs");
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-const cli_1 = require("../utils/cli");
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getCliVersion, getInstallMethod } from '../utils/cli.js';
 const DEFAULT_API_URL = 'https://api.devicecloud.dev';
 class Telemetry {
     buffer = [];
     config = null;
     command = inferCommandFromArgv();
-    sessionId = (0, node_crypto_1.randomUUID)();
+    sessionId = randomUUID();
     startedAt = Date.now();
     disabled = !!process.env.DCD_TELEMETRY_DISABLED;
-    release = (0, cli_1.getCliVersion)();
+    release = getCliVersion();
     /**
      * Called once per invocation by `resolveAuth` after the credential check
      * succeeds. Before this is called, lifecycle events are buffered but cannot
@@ -46,12 +43,37 @@ class Telemetry {
             command: this.command,
         };
     }
+    /**
+     * Override the command label attached to telemetry meta. The MCP server is
+     * long-lived and isn't a citty subcommand, so `inferCommandFromArgv` can't
+     * name it — `src/mcp/index.ts` calls this at boot.
+     */
+    setCommand(command) {
+        this.command = command;
+    }
     recordCommandStart() {
         this.startedAt = Date.now();
         this.enqueue('info', 'cli.lifecycle', 'command started', {
             argv: scrubArgv(process.argv.slice(2)),
         });
     }
+    recordMcpToolStart(tool) {
+        this.enqueue('info', 'cli.mcp', 'mcp tool invoked', { tool });
+    }
+    recordMcpToolSuccess(tool, durationMs) {
+        this.enqueue('info', 'cli.mcp', 'mcp tool completed', {
+            tool,
+            duration_ms: durationMs,
+        });
+    }
+    recordMcpToolFailure(tool, error, durationMs) {
+        this.enqueue('error', 'cli.mcp', 'mcp tool failed', {
+            tool,
+            duration_ms: durationMs,
+            error_message: error instanceof Error ? error.message : String(error),
+            error_name: error instanceof Error ? error.name : 'Error',
+        });
+    }
     recordCommandSuccess() {
         this.enqueue('info', 'cli.lifecycle', 'command completed', {
             duration_ms: Date.now() - this.startedAt,
@@ -115,14 +137,14 @@ class Telemetry {
         // body, so it can't double as the config channel.
         let configDir;
         try {
-            configDir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'dcd-telemetry-'));
-            const configPath = (0, node_path_1.join)(configDir, 'curl.cfg');
+            configDir = mkdtempSync(join(tmpdir(), 'dcd-telemetry-'));
+            const configPath = join(configDir, 'curl.cfg');
             const headerLines = ['header = "content-type: application/json"'];
             for (const [k, v] of Object.entries(this.config.auth.headers)) {
                 headerLines.push(`header = "${k}: ${v}"`);
             }
-            (0, node_fs_1.writeFileSync)(configPath, headerLines.join('\n'), { mode: 0o600 });
-            (0, node_child_process_1.execFileSync)('curl', [
+            writeFileSync(configPath, headerLines.join('\n'), { mode: 0o600 });
+            execFileSync('curl', [
                 '-sS',
                 '-m',
                 '3',
@@ -140,7 +162,7 @@ class Telemetry {
         }
         finally {
             if (configDir)
-                (0, node_fs_1.rmSync)(configDir, { recursive: true, force: true });
+                rmSync(configDir, { recursive: true, force: true });
         }
     }
     buildMeta() {
@@ -152,7 +174,7 @@ class Telemetry {
             command: this.command,
             sessionId: this.sessionId,
             authMode: this.config.auth.mode,
-            installMethod: (0, cli_1.getInstallMethod)(),
+            installMethod: getInstallMethod(),
             nodeVersion: process.versions.node,
             platform: process.platform,
             arch: process.arch,
@@ -227,4 +249,4 @@ function inferApiUrlFromArgv() {
     }
     return DEFAULT_API_URL;
 }
-exports.telemetry = new Telemetry();
+export const telemetry = new Telemetry();

package/dist/services/test-submission.service.d.ts

@@ -1,4 +1,4 @@
-import { IExecutionPlan } from './execution-plan.service';
+import { IExecutionPlan } from './execution-plan.service.js';
 export interface TestSubmissionConfig {
     androidApiLevel?: string;
     androidDevice?: string;
@@ -35,11 +35,28 @@ export interface TestSubmissionConfig {
  */
 export declare class TestSubmissionService {
     /**
-     * Build FormData for test submission
+     * Build the test-submission payload: the compressed flow zip plus every
+     * non-`file` field, each encoded exactly as it is sent today. The same
+     * `fields` feed both the new JSON `submitFlowTest` body and the legacy
+     * multipart `buildFormData`, guaranteeing byte-identical field encoding
+     * across both paths.
      * @param config Test submission configuration
-     * @returns FormData ready to be submitted to the API
+     * @returns The flow zip buffer, its SHA-256, and the string-encoded fields
      */
-    buildTestFormData(config: TestSubmissionConfig): Promise<FormData>;
+    buildTestPayload(config: TestSubmissionConfig): Promise<{
+        buffer: Buffer;
+        fields: Record<string, string>;
+        sha: string;
+    }>;
+    /**
+     * Wraps the payload fields and flow zip into multipart FormData for the
+     * legacy `POST /uploads/flow` fallback. `file` is set first to preserve the
+     * exact part ordering the old code produced.
+     * @param fields String-encoded fields from {@link buildTestPayload}
+     * @param buffer The compressed flow zip
+     * @returns FormData ready to be submitted to the multipart API
+     */
+    buildFormData(fields: Record<string, string>, buffer: Buffer): FormData;
     private logDebug;
     private normalizeFilePath;
     private normalizePathMap;