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

package/LICENSE

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

package/README.md

@@ -92,3 +92,20 @@ A [gitleaks](https://github.com/gitleaks/gitleaks) scan runs in two places, both
 - **CI** — the `secret-scan` job scans the full history on every push and pull request, and is the enforced backstop regardless of local setup.
 
 
+## Contributing
+
+Contributions are welcome! Read **[CONTRIBUTING.md](CONTRIBUTING.md)** for local
+setup, our commit/PR conventions (Conventional Commit PR titles, squash-merge),
+and how releases work. All contributors sign our
+[Contributor License Agreement](CLA.md) — the bot prompts you on your first PR —
+and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+Found a security issue? Please **don't** open a public issue — see
+[SECURITY.md](SECURITY.md).
+
+
+## License
+
+[MIT](LICENSE) © Moropo Ltd t/a DeviceCloud
+
+

package/dist/commands/cloud.js

@@ -1,5 +1,6 @@
 /* eslint-disable complexity */
 import { defineCommand } from 'citty';
+import { existsSync } from 'node:fs';
 import * as path from 'node:path';
 import { flags as allFlags } from '../constants.js';
 import { ApiError, ApiGateway } from '../gateways/api-gateway.js';
@@ -16,7 +17,7 @@ import { VersionService } from '../services/version.service.js';
 import { EAndroidApiLevels, EAndroidDevices, EiOSDevices, EiOSVersions, } from '../types/domain/device.types.js';
 import { resolveAuth } from '../utils/auth.js';
 import { isCI } from '../utils/ci.js';
-import { CliError, coerceArray, getCliVersion, getUpgradeCommand, logger, parseIntFlag, validateEnum, } from '../utils/cli.js';
+import { CliError, coerceArray, collectRepeatedFlag, getCliVersion, getUpgradeCommand, logger, parseIntFlag, validateEnum, } from '../utils/cli.js';
 import { fetchCompatibilityData, } from '../utils/compatibility.js';
 import { resolveApiUrl } from '../utils/config-store.js';
 import { downloadExpoUrl, extractTarGz, findAppBundle, isUrl } from '../utils/expo.js';
@@ -69,7 +70,7 @@ export const cloudCommand = defineCommand({
         },
     },
     // eslint-disable-next-line complexity
-    async run({ args }) {
+    async run({ args, rawArgs }) {
         const cliVersion = getCliVersion();
         const deviceValidationService = new DeviceValidationService();
         const moropoService = new MoropoService();
@@ -78,11 +79,13 @@ export const cloudCommand = defineCommand({
         const testSubmissionService = new TestSubmissionService();
         const versionService = new VersionService();
         const versionCheck = async () => {
-            const latestVersion = await versionService.checkLatestCliVersion();
-            if (latestVersion && versionService.isOutdated(cliVersion, latestVersion)) {
+            const result = await versionService.checkLatestCliVersion(cliVersion);
+            if (result.ok &&
+                result.version &&
+                versionService.isOutdated(cliVersion, result.version)) {
                 out(ui.warn(colors.bold('Update available')));
                 out(ui.branch([
-                    `A new version of the DeviceCloud CLI is available: ${colors.highlight(latestVersion)}`,
+                    `A new version of the DeviceCloud CLI is available: ${colors.highlight(result.version)}`,
                     `${colors.dim('Run:')} ${colors.info(getUpgradeCommand())}`,
                 ]));
             }
@@ -119,13 +122,15 @@ export const cloudCommand = defineCommand({
             const deviceLocale = args['device-locale'];
             const downloadArtifacts = validateEnum(args['download-artifacts'], DOWNLOAD_OPTIONS, 'download-artifacts');
             const dryRun = Boolean(args['dry-run']);
-            const env = coerceArray(args.env, false);
-            const excludeFlows = coerceArray(args['exclude-flows']);
-            const excludeTags = coerceArray(args['exclude-tags']);
+            // Repeatable flags are collected from rawArgs: citty/parseArgs only keeps
+            // the last occurrence, so reading args.* directly drops earlier values.
+            const env = coerceArray(collectRepeatedFlag(rawArgs, ['--env', '-e']), false);
+            const excludeFlows = coerceArray(collectRepeatedFlag(rawArgs, ['--exclude-flows']));
+            const excludeTags = coerceArray(collectRepeatedFlag(rawArgs, ['--exclude-tags']));
             let flows = args.flows;
             const googlePlay = Boolean(args['google-play']);
             const ignoreShaCheck = Boolean(args['ignore-sha-check']);
-            const includeTags = coerceArray(args['include-tags']);
+            const includeTags = coerceArray(collectRepeatedFlag(rawArgs, ['--include-tags']));
             const iOSDevice = validateEnum(args['ios-device'], Object.values(EiOSDevices), 'ios-device');
             const iOSVersion = validateEnum(args['ios-version'], Object.values(EiOSVersions), 'ios-version');
             const androidApiLevel = validateEnum(args['android-api-level'], Object.values(EAndroidApiLevels), 'android-api-level');
@@ -135,7 +140,7 @@ export const cloudCommand = defineCommand({
             const jsonFileFlag = Boolean(args['json-file']);
             const jsonFileName = args['json-file-name'];
             const maestroVersion = args['maestro-version'];
-            const metadata = coerceArray(args.metadata, false);
+            const metadata = coerceArray(collectRepeatedFlag(rawArgs, ['--metadata', '-m']), false);
             const mitmHost = args.mitmHost;
             const mitmPath = args.mitmPath;
             const moropoApiKey = args['moropo-v1-api-key'];
@@ -236,10 +241,16 @@ export const cloudCommand = defineCommand({
                 debug,
                 logger: (m) => out(m),
             });
-            const REMOVED_MAESTRO_VERSIONS = ['1.39.1', '1.39.2', '1.39.7', '2.0.3', '2.4.0'];
-            if (REMOVED_MAESTRO_VERSIONS.includes(resolvedMaestroVersion)) {
-                throw new CliError(`Maestro version ${resolvedMaestroVersion} is no longer supported. ` +
-                    `Please upgrade to a newer version. See: https://docs.devicecloud.dev/configuration/maestro-versions`);
+            // Soft deprecation notice for Maestro versions slated for removal on
+            // 26 June 2026. Non-fatal — these still run during the grace period.
+            const DEPRECATED_MAESTRO_VERSIONS = ['1.39.5', '1.41.0'];
+            if (DEPRECATED_MAESTRO_VERSIONS.includes(resolvedMaestroVersion)) {
+                warnOut(ui.warn(colors.bold(`Maestro ${resolvedMaestroVersion} is deprecated`)));
+                warnOut(ui.branch([
+                    `Maestro ${resolvedMaestroVersion} will be removed on 26 June 2026; after that, tests pinned to it will fail.`,
+                    'Upgrade to Maestro 2.6.0 or above.',
+                    `${colors.dim('See:')} ${colors.url('https://docs.devicecloud.dev/configuration/maestro-versions')}`,
+                ]));
             }
             if (retry !== undefined && retry > 2) {
                 out(ui.warn('Retries are now free of charge but limited to 2. If your test is still failing after 2 retries, please ask for help on Discord.'));
@@ -275,6 +286,13 @@ export const cloudCommand = defineCommand({
                         out(`[DEBUG] Found .app bundle at: ${finalAppFile}`);
                     }
                 }
+                // Validate the resolved local app file early — dry-run otherwise skips
+                // the upload that would surface a missing file, so a typo'd path would
+                // pass a dry-run and only fail on the real run. (URL/.tar.gz inputs are
+                // already resolved to existing temp paths by this point.)
+                if (!existsSync(finalAppFile)) {
+                    throw new CliError(`App file does not exist: ${finalAppFile}`);
+                }
             }
             if (debug) {
                 out(`[DEBUG] First file argument: ${firstFile || 'not provided'}`);
@@ -301,6 +319,18 @@ export const cloudCommand = defineCommand({
                 debug,
                 logger: (m) => out(m),
             });
+            // iOS 16 deprecation notice (soft warning during the grace period;
+            // removed on 23 August 2026). Only fires on an explicit --ios-version 16 —
+            // when omitted the API defaults to iOS 17, so no false warning.
+            const DEPRECATED_IOS_VERSIONS = ['16'];
+            if (iOSVersion && DEPRECATED_IOS_VERSIONS.includes(iOSVersion)) {
+                warnOut(ui.warn(colors.bold('iOS 16 is deprecated')));
+                warnOut(ui.branch([
+                    'iOS 16 will be removed on 23 August 2026; after that, tests targeting it will fail.',
+                    'Switch to iOS 17 or newer — iPhone 14 also supports 17 and 18.',
+                    `${colors.dim('See:')} ${colors.url('https://docs.devicecloud.dev/getting-started/devices-configuration')}`,
+                ]));
+            }
             deviceValidationService.validateAndroidDevice(androidApiLevel, androidDevice, googlePlay, compatibilityData, { debug, logger: (m) => out(m) });
             if (maestroChromeOnboarding && !androidApiLevel && !androidDevice) {
                 warnOut('The --maestro-chrome-onboarding flag only applies to Android tests and will be ignored for iOS tests.');
@@ -385,9 +415,20 @@ export const cloudCommand = defineCommand({
             ]);
             // Only log canonical flag keys (skip citty-populated alias duplicates like apiURL/apiUrl).
             const canonicalFlagKeys = new Set(Object.keys(allFlags));
+            // Repeatable flags are recovered from rawArgs (args.* only holds the last
+            // occurrence), so echo the fully-collected values rather than args.*.
+            const repeatableDisplay = {
+                env,
+                metadata,
+                'include-tags': includeTags,
+                'exclude-tags': excludeTags,
+                'exclude-flows': excludeFlows,
+            };
             for (const [k, v] of Object.entries(args)) {
                 if (!canonicalFlagKeys.has(k))
                     continue;
+                if (k in repeatableDisplay)
+                    continue;
                 if (v === undefined || v === null || v === false)
                     continue;
                 const asString = String(v);
@@ -395,6 +436,10 @@ export const cloudCommand = defineCommand({
                     flagLogs.push(`${k}: ${asString}`);
                 }
             }
+            for (const [k, values] of Object.entries(repeatableDisplay)) {
+                if (values.length > 0)
+                    flagLogs.push(`${k}: ${values.join(', ')}`);
+            }
             const overridesEntries = Object.entries(flowOverrides);
             const hasOverrides = overridesEntries.some(([, overrides]) => Object.keys(overrides).length > 0);
             const submitRows = ui.fields([

package/dist/commands/list.js

@@ -1,5 +1,6 @@
 import { defineCommand } from 'citty';
 import { apiFlags } from '../config/flags/api.flags.js';
+import { resolveFrontendUrl } from '../config/environments.js';
 import { ApiGateway } from '../gateways/api-gateway.js';
 import { resolveAuth } from '../utils/auth.js';
 import { CliError, logger, parseIntFlag } from '../utils/cli.js';
@@ -21,8 +22,12 @@ function detectShellExpansion(name) {
             '  ✗ Incorrect: dcd list --name nightly-*\n');
     }
 }
-function displayResults(response) {
+function displayResults(response, apiUrl) {
     const { uploads, total, limit, offset } = response;
+    // Build console links from the env the CLI is pointed at, rather than the
+    // API-supplied consoleUrl (which is hardcoded to prod) — so dev/staging users
+    // get links that actually resolve.
+    const frontendUrl = resolveFrontendUrl(apiUrl);
     if (uploads.length === 0) {
         logger.log(ui.info('No uploads found matching your criteria.'));
         return;
@@ -45,7 +50,7 @@ function displayResults(response) {
             ...ui.fields([
                 ['id', formatId(upload.id)],
                 ['created', formattedDate],
-                ['console', formatUrl(upload.consoleUrl)],
+                ['console', formatUrl(`${frontendUrl}/results?upload=${upload.id}`)],
             ]),
         ]));
     }
@@ -122,7 +127,7 @@ export const listCommand = defineCommand({
                     console.log(JSON.stringify(response, null, 2));
                     return;
                 }
-                displayResults(response);
+                displayResults(response, apiUrl);
             }
             catch (error) {
                 throw new CliError(`Failed to list uploads: ${error.message}`);

package/dist/commands/status.js

@@ -1,5 +1,6 @@
 import { defineCommand } from 'citty';
 import { apiFlags } from '../config/flags/api.flags.js';
+import { resolveFrontendUrl } from '../config/environments.js';
 import { ApiGateway } from '../gateways/api-gateway.js';
 import { formatDurationSeconds } from '../methods.js';
 import { resolveAuth } from '../utils/auth.js';
@@ -163,8 +164,14 @@ async function statusMain({ apiKeyFlag, apiUrl, json, name, uploadId, }) {
         if (status.createdAt) {
             fields.push(['created', formatDateTime(status.createdAt)]);
         }
-        if (status.consoleUrl) {
-            fields.push(['console', formatUrl(status.consoleUrl)]);
+        // Prefer a console link built from the env the CLI is pointed at (the
+        // API-supplied consoleUrl is hardcoded to prod, so it misdirects
+        // dev/staging users); fall back to the API value if we have no uploadId.
+        const consoleUrl = status.uploadId
+            ? `${resolveFrontendUrl(apiUrl)}/results?upload=${status.uploadId}`
+            : status.consoleUrl;
+        if (consoleUrl) {
+            fields.push(['console', formatUrl(consoleUrl)]);
         }
         logger.log(ui.section('Upload Status'));
         logger.log(ui.branch([ui.status(status.status), ...ui.fields(fields)]));

package/dist/commands/upgrade.js

@@ -38,10 +38,17 @@ export const upgradeCommand = defineCommand({
         }
         const current = getCliVersion();
         const versionService = new VersionService();
-        const latest = await versionService.checkLatestCliVersion();
-        if (!latest) {
-            throw new CliError('Could not reach the update manifest. Check your network connection and try again.');
+        const result = await versionService.checkLatestCliVersion(current);
+        if (!result.ok) {
+            throw new CliError(`Could not reach the update manifest (${result.error}). Check your network connection and try again.`);
         }
+        // Reachable, but nothing published on this channel yet (e.g. a stable
+        // install while only betas exist). Not an error — just nothing to do.
+        if (result.version === null) {
+            logger.log(ui.info(`No newer release available on the ${result.channel} channel.`));
+            return;
+        }
+        const latest = result.version;
         if (!versionService.isOutdated(current, latest)) {
             logger.log(ui.success(`Already on the latest version (${colors.highlight(current)})`));
             return;
@@ -54,7 +61,10 @@ export const upgradeCommand = defineCommand({
         if (process.platform === 'win32') {
             // Windows can't replace a running .exe; defer to a re-run of the installer.
             const base = process.env.DCD_DOWNLOAD_BASE ?? DEFAULT_DOWNLOAD_BASE;
-            throw new CliError(`Automatic upgrade on Windows is not yet supported. Re-run the installer:\n  irm ${base}/install.ps1 | iex`);
+            // Prerelease users need the beta channel opt-in or the installer resolves
+            // the (currently non-existent) stable release.
+            const betaHint = result.channel === 'beta' ? '$env:DCD_BETA=1; ' : '';
+            throw new CliError(`Automatic upgrade on Windows is not yet supported. Re-run the installer:\n  ${betaHint}irm ${base}/install.ps1 | iex`);
         }
         const base = process.env.DCD_DOWNLOAD_BASE ?? DEFAULT_DOWNLOAD_BASE;
         const binaryUrl = `${base}/download/${latest}/${asset}`;

package/dist/methods.js

@@ -676,8 +676,9 @@ async function uploadToBackblaze(uploadUrl, authorizationToken, fileName, source
             if (debug) {
                 console.error(`[DEBUG] Backblaze upload failed with status ${response.status}: ${errorText}`);
             }
-            // Don't throw - we don't want Backblaze failures to block the primary upload
-            console.warn(`Warning: Backblaze upload failed with status ${response.status}`);
+            // Don't throw and don't warn — Backblaze is the primary attempt and the
+            // Supabase fallback usually recovers. A user-facing error is raised only
+            // if every strategy fails (see validateUploadResults).
             return false;
         }
         if (debug) {
@@ -700,12 +701,9 @@ async function uploadToBackblaze(uploadUrl, authorizationToken, fileName, source
             if (debug) {
                 console.error('[DEBUG] Network error detected - could be DNS, connection, or SSL issue');
             }
-            console.warn('Warning: Backblaze upload failed due to network error');
-        }
-        else {
-            // Don't throw - we don't want Backblaze failures to block the primary upload
-            console.warn(`Warning: Backblaze upload failed: ${error instanceof Error ? error.message : String(error)}`);
         }
+        // Don't throw and don't warn — the Supabase fallback usually recovers, and
+        // validateUploadResults raises a user-facing error only if all fail.
         return false;
     }
 }
@@ -801,12 +799,9 @@ function logBackblazeUploadError(error, debug) {
             console.error(`[DEBUG] Stack trace:\n${error.stack}`);
         }
     }
-    if (error instanceof Error && error.message.includes('network error')) {
-        console.warn('Warning: Backblaze large file upload failed due to network error');
-    }
-    else {
-        console.warn(`Warning: Backblaze large file upload failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
+    // No user-facing warning: Backblaze is the primary attempt and the Supabase
+    // fallback usually recovers; validateUploadResults raises the only
+    // user-facing error, and only when every strategy fails.
 }
 /**
  * Upload large file to Backblaze using multi-part upload with streaming (for files >= 5MB)

package/dist/services/results-polling.service.d.ts

@@ -104,7 +104,7 @@ export declare class ResultsPollingService {
      * 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…".
+     * countdown reads "refreshing…". In quiet mode the countdown is omitted.
      */
     private buildStatusFooter;
 }

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

@@ -3,6 +3,7 @@ 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';
@@ -100,10 +101,18 @@ export class ResultsPollingService {
         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;
-            const footer = this.buildStatusFooter(realtimeEnabled, subscription?.isConnected() ?? false, nextPollAt);
+            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
@@ -132,8 +141,11 @@ export class ResultsPollingService {
         }
         // 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);
+        // 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
@@ -446,21 +458,25 @@ export class ResultsPollingService {
      * 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…".
+     * countdown reads "refreshing…". In quiet mode the countdown is omitted.
      */
-    buildStatusFooter(realtimeEnabled, realtimeConnected, nextPollAt) {
+    buildStatusFooter(realtimeEnabled, realtimeConnected, nextPollAt, quiet) {
         const parts = [];
         if (realtimeEnabled) {
             parts.push(realtimeConnected
                 ? colors.success('● realtime connected')
                 : colors.warning('○ realtime connecting…'));
         }
-        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`));
+        // 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 parts.join(colors.dim('  ·  '));
     }

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

@@ -1,4 +1,19 @@
 import { CompatibilityData } from '../utils/compatibility.js';
+export type ReleaseChannel = 'beta' | 'stable';
+/**
+ * Outcome of a release-manifest lookup. `ok: true` means the manifest was
+ * reachable — `version` is the published version on the channel, or `null` when
+ * nothing is published there yet. `ok: false` means the lookup itself failed
+ * (network/timeout/non-2xx).
+ */
+export type LatestVersionResult = {
+    ok: true;
+    channel: ReleaseChannel;
+    version: null | string;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Service for handling version validation and checking
  */
@@ -6,14 +21,22 @@ export declare class VersionService {
     /**
      * Fetch the latest published CLI version from the release manifest.
      * Works for both npm- and binary-installed users (no `npm` shell-out).
-     * Silently returns null on any failure — this check is informational only.
+     *
+     * The result is discriminated so callers can tell "reachable, but no release
+     * on this channel yet" (`ok: true, version: null`) apart from an actual
+     * network/manifest failure (`ok: false`) — the old single-`null` return
+     * conflated the two and produced a misleading "check your network" error
+     * during the beta. Prerelease installs (current version contains `-`) query
+     * the opt-in beta channel; everyone else gets the stable channel.
      */
-    checkLatestCliVersion(): Promise<null | string>;
+    checkLatestCliVersion(currentVersion?: string): Promise<LatestVersionResult>;
     /**
-     * Compare two semantic version strings
-     * @param current - Current version
-     * @param latest - Latest version
-     * @returns true if current is older than latest
+     * Compare two semantic version strings (SemVer 2.0.0 precedence, including
+     * prerelease tags). Returns true if `current` is strictly older than `latest`.
+     *
+     * Prerelease handling matters here: a beta-to-beta bump such as
+     * "5.0.0-beta.0" -> "5.0.0-beta.1" shares the same major.minor.patch, so we
+     * must compare the prerelease identifiers to detect that an upgrade exists.
      */
     isOutdated(current: string, latest: string): boolean;
     /**

package/dist/services/version.service.js

@@ -1,5 +1,59 @@
 const DEFAULT_MANIFEST_URL = 'https://get.devicecloud.dev/latest.json';
 const MANIFEST_TIMEOUT_MS = 3000;
+/**
+ * Compare two semantic versions per SemVer 2.0.0 precedence rules.
+ * Returns a negative number if `a < b`, positive if `a > b`, and 0 if equal.
+ *
+ * Implements the prerelease rules that the previous naive comparator dropped:
+ *   - A version WITH a prerelease has lower precedence than the same version
+ *     without one ("1.0.0-beta" < "1.0.0").
+ *   - Prerelease identifiers are compared dot-separated, left to right:
+ *     numeric identifiers compare numerically, alphanumeric ones compare
+ *     lexically (ASCII), and numeric always sorts below alphanumeric. A longer
+ *     set of identifiers wins when all preceding ones are equal.
+ */
+function compareSemver(a, b) {
+    const split = (v) => {
+        const [core, ...preParts] = v.trim().replace(/^v/, '').split('-');
+        const nums = core.split('.').map((n) => Number(n) || 0);
+        const pre = preParts.join('-');
+        return {
+            release: [nums[0] || 0, nums[1] || 0, nums[2] || 0],
+            pre: pre ? pre.split('.') : [],
+        };
+    };
+    const left = split(a);
+    const right = split(b);
+    for (let i = 0; i < 3; i++) {
+        if (left.release[i] !== right.release[i]) {
+            return left.release[i] - right.release[i];
+        }
+    }
+    // Equal release: a version with no prerelease outranks one that has it.
+    if (left.pre.length === 0 && right.pre.length === 0)
+        return 0;
+    if (left.pre.length === 0)
+        return 1;
+    if (right.pre.length === 0)
+        return -1;
+    const len = Math.min(left.pre.length, right.pre.length);
+    for (let i = 0; i < len; i++) {
+        const lp = left.pre[i];
+        const rp = right.pre[i];
+        if (lp === rp)
+            continue;
+        const ln = /^\d+$/.test(lp);
+        const rn = /^\d+$/.test(rp);
+        if (ln && rn)
+            return Number(lp) - Number(rp);
+        if (ln)
+            return -1; // numeric identifiers sort below alphanumeric
+        if (rn)
+            return 1;
+        return lp < rp ? -1 : 1;
+    }
+    return left.pre.length - right.pre.length;
+}
 /**
  * Service for handling version validation and checking
  */
@@ -7,48 +61,54 @@ export class VersionService {
     /**
      * Fetch the latest published CLI version from the release manifest.
      * Works for both npm- and binary-installed users (no `npm` shell-out).
-     * Silently returns null on any failure — this check is informational only.
+     *
+     * The result is discriminated so callers can tell "reachable, but no release
+     * on this channel yet" (`ok: true, version: null`) apart from an actual
+     * network/manifest failure (`ok: false`) — the old single-`null` return
+     * conflated the two and produced a misleading "check your network" error
+     * during the beta. Prerelease installs (current version contains `-`) query
+     * the opt-in beta channel; everyone else gets the stable channel.
      */
-    async checkLatestCliVersion() {
-        const url = process.env.DCD_MANIFEST_URL ?? DEFAULT_MANIFEST_URL;
+    async checkLatestCliVersion(currentVersion) {
+        const channel = currentVersion?.includes('-') ? 'beta' : 'stable';
+        const base = process.env.DCD_MANIFEST_URL ?? DEFAULT_MANIFEST_URL;
+        const url = channel === 'beta'
+            ? `${base}${base.includes('?') ? '&' : '?'}channel=beta`
+            : base;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), MANIFEST_TIMEOUT_MS);
         try {
             const res = await fetch(url, { signal: controller.signal });
-            if (!res.ok)
-                return null;
+            if (!res.ok) {
+                return { ok: false, error: `manifest responded with HTTP ${res.status}` };
+            }
             const data = (await res.json());
-            return typeof data.version === 'string' ? data.version : null;
+            return {
+                ok: true,
+                channel,
+                version: typeof data.version === 'string' ? data.version : null,
+            };
         }
-        catch {
-            return null;
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
         }
         finally {
             clearTimeout(timer);
         }
     }
     /**
-     * Compare two semantic version strings
-     * @param current - Current version
-     * @param latest - Latest version
-     * @returns true if current is older than latest
+     * Compare two semantic version strings (SemVer 2.0.0 precedence, including
+     * prerelease tags). Returns true if `current` is strictly older than `latest`.
+     *
+     * Prerelease handling matters here: a beta-to-beta bump such as
+     * "5.0.0-beta.0" -> "5.0.0-beta.1" shares the same major.minor.patch, so we
+     * must compare the prerelease identifiers to detect that an upgrade exists.
      */
     isOutdated(current, latest) {
-        // Strip any prerelease suffix ("1.2.3-beta.1" -> "1.2.3") and default
-        // missing segments to 0 so short/prerelease versions still compare.
-        const parts = (version) => {
-            const nums = version.split('-')[0].split('.').map(Number);
-            return [nums[0] || 0, nums[1] || 0, nums[2] || 0];
-        };
-        const currentParts = parts(current);
-        const latestParts = parts(latest);
-        for (let i = 0; i < 3; i++) {
-            if (currentParts[i] < latestParts[i])
-                return true;
-            if (currentParts[i] > latestParts[i])
-                return false;
-        }
-        return false;
+        return compareSemver(current, latest) < 0;
     }
     /**
      * Resolve and validate Maestro version against API compatibility data

package/dist/utils/cli.d.ts

@@ -24,10 +24,24 @@ export declare function validateEnum<T extends string>(value: string | undefined
 /**
  * Coerce a flag value (possibly a single string, array, or undefined) into a
  * flat string array. Comma-separated values inside each entry are split out.
- * Used for repeatable flags like --include-tags, --env, --metadata where citty
- * surfaces a string (single use) or string[] (repeated).
+ * Pair with {@link collectRepeatedFlag} for repeatable flags.
  */
 export declare function coerceArray(value: string | string[] | undefined, split?: boolean): string[];
+/**
+ * Collect every occurrence of a repeatable flag from raw argv, in order.
+ *
+ * citty 0.2.2 delegates to Node's `parseArgs`, which — without `multiple: true`
+ * (unsupported by citty's ArgsDef) — keeps only the LAST value of a repeated
+ * `type: 'string'` flag. So `-e A=1 -e B=2` collapses to just `B=2`. We recover
+ * all occurrences by scanning rawArgs ourselves (same approach as
+ * `recoverFlagValue` in commands/live.ts).
+ *
+ * `names` lists every spelling of one logical flag, e.g. ['--env', '-e'].
+ * Handles both `--flag value` (consuming the next token, so values starting
+ * with `-` survive) and `--flag=value`. Feed the result through
+ * {@link coerceArray} for comma-splitting where appropriate.
+ */
+export declare function collectRepeatedFlag(rawArgs: string[], names: string[]): string[];
 /**
  * Parse an integer flag. Returns undefined if the value is undefined/empty.
  * Throws CliError if the value is not a valid integer.

package/dist/utils/cli.js

@@ -9,9 +9,17 @@
 import { readFileSync } from 'node:fs';
 import { telemetry } from '../services/telemetry.service.js';
 import { symbols } from './styling.js';
-// Resolve version at runtime — read the file rather than importing it, so
-// package.json never gets pulled into the tsc program / dist rootDir.
+// Resolve version at runtime. The bun-compiled binary can't read package.json
+// off disk (it isn't bundled next to the embedded module), so the build stamps
+// the version in via `bun --define __DCD_CLI_VERSION__` (see
+// scripts/build-binaries.mjs). Prefer that constant; on the npm/tsx path the
+// identifier was never defined, so `typeof` is 'undefined' (no ReferenceError)
+// and we fall back to reading package.json.
 export function getCliVersion() {
+    if (typeof __DCD_CLI_VERSION__ === 'string' &&
+        __DCD_CLI_VERSION__.length > 0) {
+        return __DCD_CLI_VERSION__;
+    }
     try {
         const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
         return pkg.version;
@@ -90,8 +98,7 @@ export function validateEnum(value, allowed, flagName) {
 /**
  * Coerce a flag value (possibly a single string, array, or undefined) into a
  * flat string array. Comma-separated values inside each entry are split out.
- * Used for repeatable flags like --include-tags, --env, --metadata where citty
- * surfaces a string (single use) or string[] (repeated).
+ * Pair with {@link collectRepeatedFlag} for repeatable flags.
  */
 export function coerceArray(value, split = true) {
     if (value === undefined)
@@ -101,6 +108,36 @@ export function coerceArray(value, split = true) {
         return arr;
     return arr.flatMap((v) => v.split(','));
 }
+/**
+ * Collect every occurrence of a repeatable flag from raw argv, in order.
+ *
+ * citty 0.2.2 delegates to Node's `parseArgs`, which — without `multiple: true`
+ * (unsupported by citty's ArgsDef) — keeps only the LAST value of a repeated
+ * `type: 'string'` flag. So `-e A=1 -e B=2` collapses to just `B=2`. We recover
+ * all occurrences by scanning rawArgs ourselves (same approach as
+ * `recoverFlagValue` in commands/live.ts).
+ *
+ * `names` lists every spelling of one logical flag, e.g. ['--env', '-e'].
+ * Handles both `--flag value` (consuming the next token, so values starting
+ * with `-` survive) and `--flag=value`. Feed the result through
+ * {@link coerceArray} for comma-splitting where appropriate.
+ */
+export function collectRepeatedFlag(rawArgs, names) {
+    const out = [];
+    for (let i = 0; i < rawArgs.length; i++) {
+        const arg = rawArgs[i];
+        const eqName = names.find((n) => arg.startsWith(`${n}=`));
+        if (eqName) {
+            out.push(arg.slice(eqName.length + 1));
+            continue;
+        }
+        if (names.includes(arg) && i + 1 < rawArgs.length) {
+            out.push(rawArgs[i + 1]);
+            i++; // consume the value so a leading-dash value isn't re-read as a flag
+        }
+    }
+    return out;
+}
 /**
  * Parse an integer flag. Returns undefined if the value is undefined/empty.
  * Throws CliError if the value is not a valid integer.

package/dist/utils/progress.d.ts

@@ -1,10 +1,13 @@
 declare class Action {
     private current;
     private _status;
+    private _lastPrinted;
+    private interactive;
     start(title: string, initialStatus?: string, _opts?: unknown): void;
     stop(message?: string): void;
     set status(value: string);
     get status(): string;
+    private print;
 }
 export declare const ux: {
     action: Action;

package/dist/utils/progress.js

@@ -3,20 +3,47 @@
  * drop-in API for existing services that used oclif's `ux.action` / `ux.info`.
  *
  * Keeps call sites unchanged while migrating away from @oclif/core.
+ *
+ * TTY-awareness: @clack/prompts' spinner animates on a timer and, when stdout
+ * isn't a TTY (CI, pipes, redirects), it can't rewrite a line in place — every
+ * frame becomes a fresh line, flooding logs with hundreds of duplicates. In
+ * non-interactive environments we skip the spinner entirely and instead print a
+ * plain line once per *distinct* status, so CI logs show real progress without
+ * the flood.
  */
 import * as p from '@clack/prompts';
+import { isCI } from './ci.js';
 class Action {
     current = null;
     _status = '';
+    // Last line emitted in non-interactive mode, for de-duplication.
+    _lastPrinted = '';
+    interactive() {
+        return process.stdout.isTTY === true && !isCI();
+    }
     start(title, initialStatus, _opts) {
+        this._status = initialStatus ?? '';
+        const line = initialStatus ? `${title} — ${initialStatus}` : title;
+        if (!this.interactive()) {
+            this.current = null;
+            this.print(line);
+            return;
+        }
         if (this.current) {
             this.current.stop();
         }
         this.current = p.spinner();
-        this._status = initialStatus ?? '';
-        this.current.start(initialStatus ? `${title} — ${initialStatus}` : title);
+        this.current.start(line);
     }
     stop(message) {
+        if (!this.interactive()) {
+            if (message)
+                this.print(message);
+            this.current = null;
+            this._status = '';
+            this._lastPrinted = '';
+            return;
+        }
         if (!this.current) {
             if (message) {
                 // eslint-disable-next-line no-console
@@ -30,13 +57,28 @@ class Action {
     }
     set status(value) {
         this._status = value;
-        if (this.current && value) {
+        if (!value)
+            return;
+        if (!this.interactive()) {
+            this.print(value);
+            return;
+        }
+        if (this.current) {
             this.current.message(value);
         }
     }
     get status() {
         return this._status;
     }
+    // Emit a line only when it differs from the previous one, so repeated polls
+    // with no state change stay quiet.
+    print(line) {
+        if (line === this._lastPrinted)
+            return;
+        this._lastPrinted = line;
+        // eslint-disable-next-line no-console
+        console.log(line);
+    }
 }
 export const ux = {
     action: new Action(),

package/package.json

@@ -60,7 +60,7 @@
     "type": "git",
     "url": "https://devicecloud.dev"
   },
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },