@devicecloud.dev/dcd 4.4.9 → 5.0.0-beta.1

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

@@ -1,17 +1,15 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResultsPollingService = exports.RunFailedError = void 0;
-const core_1 = require("@oclif/core");
-const cli_ux_1 = require("@oclif/core/lib/cli-ux");
-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 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 { 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');
@@ -19,61 +17,178 @@ class RunFailedError extends Error {
         this.name = 'RunFailedError';
     }
 }
-exports.RunFailedError = RunFailedError;
 /**
  * Service for polling test results from the API
  */
-class ResultsPollingService {
-    MAX_SEQUENTIAL_FAILURES = 10;
-    POLL_INTERVAL_MS = 10_000;
+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 before
+    // giving up. Losing a run to a brief hiccup is far more costly than waiting a
+    // bit longer.
+    MAX_SEQUENTIAL_FAILURES = 30;
+    // 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
-     * @param results Initial test results from submission
      * @param options Polling configuration
      * @param testMetadata Optional metadata map for each test (flowName, tags)
      * @returns Promise that resolves with final test results or rejects if tests fail
      */
-    async pollUntilComplete(results, options, testMetadata) {
-        const { apiUrl, apiKey, uploadId, consoleUrl, quiet = false, json = false, debug = false, logger } = options;
+    async pollUntilComplete(options, testMetadata) {
+        try {
+            return await this.pollLoop(options, testMetadata);
+        }
+        catch (error) {
+            // RunFailedError is a completed run — the spinner was already stopped by
+            // 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)) {
+                ux.action.stop(colors.error('failed'));
+            }
+            throw error;
+        }
+    }
+    async pollLoop(options, testMetadata) {
+        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;
+        const renderStatus = () => {
+            if (json)
+                return;
+            const footer = this.buildStatusFooter(realtimeEnabled, subscription?.isConnected() ?? false, nextPollAt);
+            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, apiKey, 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.
+        const ticker = json ? null : setInterval(renderStatus, 1000);
+        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);
-                // Wait before retrying after an error
-                await this.sleep(this.POLL_INTERVAL_MS);
+                await subscription.unsubscribe();
             }
         }
     }
@@ -81,11 +196,13 @@ class ResultsPollingService {
         const resultsWithoutEarlierTries = this.filterLatestResults(results);
         return {
             consoleUrl,
-            status: resultsWithoutEarlierTries.some((result) => result.status === 'FAILED')
-                ? 'FAILED'
-                : 'PASSED',
+            // Anything other than an explicit pass (CANCELLED, ERROR, a status we
+            // don't know about yet) must fail the run — this gates CI exit codes.
+            status: resultsWithoutEarlierTries.every((result) => result.status === 'PASSED')
+                ? 'PASSED'
+                : 'FAILED',
             tests: resultsWithoutEarlierTries.map((r) => ({
-                durationSeconds: r.duration_seconds,
+                durationSeconds: r.duration_seconds ?? null,
                 failReason: r.status === 'FAILED' ? r.fail_reason || 'No reason provided' : undefined,
                 fileName: r.test_file_name,
                 flowName: testMetadata?.[r.test_file_name]?.flowName || path.parse(r.test_file_name).name,
@@ -108,7 +225,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,
@@ -123,48 +240,29 @@ class ResultsPollingService {
         if (json) {
             return;
         }
-        core_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, cli_ux_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}`;
                 },
             },
@@ -173,7 +271,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)
                             : '';
                     },
                 },
@@ -181,26 +279,27 @@ 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');
         }
     }
     /**
      * Fetch results from API and log debug information
      * @param apiUrl API base URL
-     * @param apiKey API authentication key
+     * @param auth AuthContext carrying request headers
      * @param uploadId Upload ID to fetch results for
      * @param debug Whether debug logging is enabled
      * @param logger Optional logger function
      * @returns Promise resolving to test results
      */
-    async fetchAndLogResults(apiUrl, apiKey, uploadId, debug, logger) {
+    async fetchAndLogResults(apiUrl, auth, uploadId, debug, logger) {
         if (debug && logger) {
             logger(`[DEBUG] Polling for results: ${uploadId}`);
         }
-        const { results: updatedResults } = await api_gateway_1.ApiGateway.getResultsForUpload(apiUrl, apiKey, uploadId);
-        if (!updatedResults) {
+        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');
         }
         if (debug && logger) {
@@ -212,11 +311,31 @@ class ResultsPollingService {
         return updatedResults;
     }
     filterLatestResults(results) {
-        return results.filter((result) => {
-            const originalTryId = result.retry_of || result.id;
-            const tries = results.filter((r) => r.retry_of === originalTryId || r.id === originalTryId);
-            return result.id === Math.max(...tries.map((t) => t.id));
-        });
+        // Resolve each row to the root of its retry chain (a retry's `retry_of`
+        // may point at the previous retry rather than the original attempt), then
+        // keep only the newest row per root.
+        const byId = new Map(results.map((result) => [result.id, result]));
+        const rootIdOf = (result) => {
+            let current = result;
+            const seen = new Set([current.id]);
+            while (current.retry_of) {
+                const parent = byId.get(current.retry_of);
+                if (!parent || seen.has(parent.id))
+                    return current.retry_of;
+                seen.add(parent.id);
+                current = parent;
+            }
+            return current.id;
+        };
+        const latestByRoot = new Map();
+        for (const result of results) {
+            const rootId = rootIdOf(result);
+            const existing = latestByRoot.get(rootId);
+            if (!existing || result.id > existing.id) {
+                latestByRoot.set(rootId, result);
+            }
+        }
+        return results.filter((result) => latestByRoot.get(rootIdOf(result)) === result);
     }
     /**
      * Handle completed tests and return final result
@@ -242,16 +361,21 @@ class ResultsPollingService {
         }
         return output;
     }
-    async handlePollingError(error, sequentialPollFailures, debug, logger) {
+    async handlePollingError(error, sequentialPollFailures, debug, logger, uploadId) {
+        // The run is unaffected by our inability to poll — always point the user at
+        // how to reconnect to it rather than leaving them thinking it died.
+        const resumeHint = uploadId
+            ? `\n\nThe test is still running in the cloud. Reconnect with:\n  dcd status --upload-id ${uploadId}`
+            : '';
         if (debug && logger) {
             logger(`[DEBUG] Error polling for results: ${error}`);
             logger(`[DEBUG] Sequential poll failures: ${sequentialPollFailures}`);
         }
-        if (sequentialPollFailures > this.MAX_SEQUENTIAL_FAILURES) {
+        if (sequentialPollFailures >= this.MAX_SEQUENTIAL_FAILURES) {
             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) {
@@ -267,9 +391,9 @@ class ResultsPollingService {
                 const endpointDetails = connectivityCheck.endpointResults
                     .map((r) => `  - ${r.endpoint}: ${r.error} (${r.latencyMs}ms)`)
                     .join('\n');
-                throw new Error(`Unable to fetch results after ${this.MAX_SEQUENTIAL_FAILURES} attempts.\n\nInternet connectivity check failed - all test endpoints unreachable:\n${endpointDetails}\n\nPlease verify your network connection and DNS resolution.`);
+                throw new Error(`Unable to fetch results after ${this.MAX_SEQUENTIAL_FAILURES} attempts.\n\nInternet connectivity check failed - all test endpoints unreachable:\n${endpointDetails}\n\nPlease verify your network connection and DNS resolution.${resumeHint}`);
             }
-            throw new Error(`unable to fetch results after ${this.MAX_SEQUENTIAL_FAILURES} attempts`);
+            throw new Error(`unable to fetch results after ${this.MAX_SEQUENTIAL_FAILURES} attempts${resumeHint}`);
         }
         if (logger) {
             logger('unable to fetch results, trying again...');
@@ -283,11 +407,11 @@ class ResultsPollingService {
      */
     initializePollingDisplay(json, logger) {
         if (!json) {
-            core_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'));
             }
         }
     }
@@ -301,33 +425,43 @@ 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) {
-                core_1.ux.action.status = summary;
-                return summary;
-            }
+            return summary;
+        }
+        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…".
+     */
+    buildStatusFooter(realtimeEnabled, realtimeConnected, nextPollAt) {
+        const parts = [];
+        if (realtimeEnabled) {
+            parts.push(realtimeConnected
+                ? colors.success('● realtime connected')
+                : colors.warning('○ realtime connecting…'));
+        }
+        if (nextPollAt === null) {
+            parts.push(colors.dim('refreshing…'));
         }
         else {
-            core_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)') : '';
-                core_1.ux.action.status += `\n${statusFormatted}  ${test}${retryText}`;
-            }
+            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

@@ -0,0 +1,49 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+export type TelemetryLevel = 'log' | 'info' | 'warn' | 'error';
+declare class Telemetry {
+    private buffer;
+    private config;
+    private command;
+    private sessionId;
+    private startedAt;
+    private readonly disabled;
+    private readonly release;
+    /**
+     * Called once per invocation by `resolveAuth` after the credential check
+     * succeeds. Before this is called, lifecycle events are buffered but cannot
+     * be sent. Commands that never reach `resolveAuth` (`--help`, `--version`,
+     * `dcd login` before sign-in completes) will skip telemetry entirely — by
+     * design, since those flows have no identity to attach.
+     */
+    configure(opts: {
+        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;
+        exitCode: number;
+    }): void;
+    private enqueue;
+    flush(): Promise<void>;
+    /**
+     * Synchronous flush via `curl`. Used right before `process.exit` (which
+     * bypasses `beforeExit`, so async `fetch` would be killed mid-flight).
+     * Node has no built-in sync HTTP and `curl` ships with macOS, Linux, and
+     * Windows ≥ 1803 — that's the supported surface for the CLI.
+     */
+    flushSync(): void;
+    private buildMeta;
+}
+export declare const telemetry: Telemetry;
+export {};