@devicecloud.dev/dcd 5.8.0 → 5.9.0

package/dist/config/supabase-key.js

@@ -0,0 +1,54 @@
+/**
+ * The Supabase publishable key, fetched from the dcd API at runtime (dcd#1112).
+ *
+ * Releases up to this one compiled the anon key in, so the key could never be
+ * rotated without breaking every CLI version pinned in customer CI. The API now
+ * serves it from the public `GET /cli-config`, and rotating it is an env change
+ * on the API.
+ *
+ * Fetched once per process and kept in memory only. It is deliberately not
+ * cached on disk: a stale key makes GoTrue answer a refresh with a 4xx, which
+ * `resolveAuth` treats as a dead session and deletes the user's login.
+ *
+ * Only the key comes from the API. The Supabase URLs stay pinned in
+ * `ENVIRONMENTS`: prod goes through the `cloud.devicecloud.dev` custom domain,
+ * which customer firewalls may allow-list, not the API's raw `supabase.co` URL.
+ */
+import { ENVIRONMENTS } from './environments.js';
+const FETCH_TIMEOUT_MS = 10_000;
+const cache = new Map();
+async function fetchSupabaseKey(env) {
+    const url = `${ENVIRONMENTS[env].apiUrl}/cli-config`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch CLI config from ${url}: HTTP ${res.status}`);
+    }
+    const body = (await res.json());
+    const key = body.supabase_publishable_key;
+    if (typeof key !== 'string' || key.length === 0) {
+        throw new Error(`CLI config from ${url} has no supabase_publishable_key`);
+    }
+    return key;
+}
+/** The publishable key for `env`. A failed fetch is not cached, so the next call retries. */
+export function getSupabaseKey(env) {
+    let pending = cache.get(env);
+    if (!pending) {
+        pending = fetchSupabaseKey(env);
+        cache.set(env, pending);
+        pending.catch(() => cache.delete(env));
+    }
+    return pending;
+}
+/**
+ * Headers that authenticate a raw Storage/Auth request with `key` alone. A
+ * legacy anon key is a JWT and also goes in `Authorization`; an
+ * `sb_publishable_` key is not a JWT and must only be sent as `apikey`.
+ */
+export function supabaseKeyHeaders(key) {
+    return key.startsWith('sb_') ? { apikey: key } : { apikey: key, authorization: `Bearer ${key}` };
+}
+/** Test seam: forget fetched keys. */
+export function resetSupabaseKeyCache() {
+    cache.clear();
+}

package/dist/gateways/cli-auth-gateway.d.ts

@@ -1,3 +1,4 @@
+import type { DcdEnvName } from '../config/environments.js';
 import type { StoredSession } from '../utils/config-store.js';
 /**
  * Thrown when a session refresh fails. `definitive` distinguishes "Supabase
@@ -18,6 +19,6 @@ export interface RefreshedSession {
     user_id: string;
 }
 export declare const CliAuthGateway: {
-    refresh(supabaseUrl: string, supabaseAnonKey: string, session: StoredSession): Promise<RefreshedSession>;
-    signOut(supabaseUrl: string, supabaseAnonKey: string, session: StoredSession): Promise<void>;
+    refresh(supabaseUrl: string, env: DcdEnvName, session: StoredSession): Promise<RefreshedSession>;
+    signOut(supabaseUrl: string, env: DcdEnvName, session: StoredSession): Promise<void>;
 };

package/dist/gateways/cli-auth-gateway.js

@@ -6,6 +6,7 @@
  * login command's PKCE rendezvous flow (see src/commands/login.ts).
  */
 import { createClient, isAuthApiError } from '@supabase/supabase-js';
+import { getSupabaseKey } from '../config/supabase-key.js';
 /**
  * Thrown when a session refresh fails. `definitive` distinguishes "Supabase
  * rejected this refresh token" (revoked, already used, malformed — re-login
@@ -20,14 +21,23 @@ export class SessionRefreshError extends Error {
         this.name = 'SessionRefreshError';
     }
 }
-function client(supabaseUrl, supabaseAnonKey) {
-    return createClient(supabaseUrl, supabaseAnonKey, {
+function client(supabaseUrl, supabaseKey) {
+    return createClient(supabaseUrl, supabaseKey, {
         auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
     });
 }
 export const CliAuthGateway = {
-    async refresh(supabaseUrl, supabaseAnonKey, session) {
-        const sb = client(supabaseUrl, supabaseAnonKey);
+    async refresh(supabaseUrl, env, session) {
+        let supabaseKey;
+        try {
+            supabaseKey = await getSupabaseKey(env);
+        }
+        catch (error) {
+            // Never definitive: the refresh token was not even tried, so the stored
+            // session must survive for the next attempt.
+            throw new SessionRefreshError(`Failed to refresh session: ${error.message}`, false);
+        }
+        const sb = client(supabaseUrl, supabaseKey);
         const { data, error } = await sb.auth.refreshSession({
             refresh_token: session.refresh_token,
         });
@@ -53,14 +63,14 @@ export const CliAuthGateway = {
             user_id: u.id,
         };
     },
-    async signOut(supabaseUrl, supabaseAnonKey, session) {
+    async signOut(supabaseUrl, env, session) {
         // `scope: 'local'` clears this client's SDK state only — no server call,
         // no revocation. supabase-js defaults to `scope: 'global'`, which revokes
         // EVERY session for the user (browser, mobile, other CLIs), so
         // `dcd logout` would kick the user out of the web app. We don't want
         // that — logging out locally should be local.
-        const sb = client(supabaseUrl, supabaseAnonKey);
         try {
+            const sb = client(supabaseUrl, await getSupabaseKey(env));
             await sb.auth.setSession({
                 access_token: session.access_token,
                 refresh_token: session.refresh_token,

package/dist/gateways/realtime-gateway.js

@@ -15,6 +15,7 @@
  */
 import { createClient, REALTIME_SUBSCRIBE_STATES, } from '@supabase/supabase-js';
 import { ENVIRONMENTS } from '../config/environments.js';
+import { getSupabaseKey } from '../config/supabase-key.js';
 export class RealtimeResultsGateway {
     /**
      * Open a realtime subscription to `results` changes for the given upload.
@@ -34,17 +35,28 @@ export class RealtimeResultsGateway {
             onConnectionChange?.(next);
         };
         let client;
-        try {
-            const { url, anonKey } = ENVIRONMENTS[env].supabase;
-            client = createClient(url, anonKey, {
+        let channel;
+        let closed = false;
+        // The latest JWT, so a refresh that lands while the key is still being
+        // fetched is the one the socket joins with.
+        let token = accessToken;
+        // The publishable key comes from the API (dcd#1112), so the socket opens
+        // asynchronously. `subscribe` stays synchronous for the caller: until it
+        // connects, `isConnected` is false and the backstop poll covers the gap.
+        const ready = getSupabaseKey(env)
+            .then((supabaseKey) => {
+            if (closed)
+                return;
+            const sb = createClient(ENVIRONMENTS[env].supabase.url, supabaseKey, {
                 // Match SupabaseClientGateway / the frontend; no session persistence —
                 // we set the token explicitly below.
                 auth: { autoRefreshToken: false, persistSession: false },
                 realtime: { params: { eventsPerSecond: 10 } },
             });
+            client = sb;
             // Attach the user's JWT to the socket so RLS is enforced on the channel.
-            client.realtime.setAuth(accessToken);
-            const channel = client
+            sb.realtime.setAuth(token);
+            channel = sb
                 .channel(`results-cli-${uploadId}`)
                 .on(
             // The typings don't cover the postgres_changes overload cleanly.
@@ -73,29 +85,8 @@ export class RealtimeResultsGateway {
                     setConnected(false);
                 }
             });
-            const activeClient = client;
-            return {
-                isConnected: () => connected,
-                async unsubscribe() {
-                    setConnected(false);
-                    try {
-                        await activeClient.removeChannel(channel);
-                        await activeClient.realtime.disconnect();
-                    }
-                    catch {
-                        /* best effort — process is exiting anyway */
-                    }
-                },
-                updateAccessToken(nextToken) {
-                    // setAuth updates the join payload and pushes the token to joined
-                    // channels. A failure only costs realtime; the backstop poll stays.
-                    activeClient.realtime.setAuth(nextToken).catch((error) => {
-                        dbg(`failed to update the socket's token: ${error instanceof Error ? error.message : String(error)}`);
-                    });
-                },
-            };
-        }
-        catch (error) {
+        })
+            .catch((error) => {
             dbg(`failed to subscribe: ${error instanceof Error ? error.message : String(error)}`);
             // Best-effort cleanup of a half-built client, then degrade to polling.
             try {
@@ -104,11 +95,34 @@ export class RealtimeResultsGateway {
             catch {
                 /* ignore */
             }
-            return {
-                isConnected: () => false,
-                async unsubscribe() { },
-                updateAccessToken() { },
-            };
-        }
+            client = undefined;
+            channel = undefined;
+        });
+        return {
+            isConnected: () => connected,
+            async unsubscribe() {
+                closed = true;
+                setConnected(false);
+                await ready;
+                if (!client)
+                    return;
+                try {
+                    if (channel)
+                        await client.removeChannel(channel);
+                    await client.realtime.disconnect();
+                }
+                catch {
+                    /* best effort — process is exiting anyway */
+                }
+            },
+            updateAccessToken(nextToken) {
+                token = nextToken;
+                // setAuth updates the join payload and pushes the token to joined
+                // channels. A failure only costs realtime; the backstop poll stays.
+                client?.realtime.setAuth(nextToken).catch((error) => {
+                    dbg(`failed to update the socket's token: ${error instanceof Error ? error.message : String(error)}`);
+                });
+            },
+        };
     }
 }

package/dist/gateways/supabase-gateway.d.ts

@@ -9,7 +9,7 @@ export interface ResumableUploadSource {
 export declare class SupabaseGateway {
     /**
      * Upload to Supabase using resumable uploads (TUS protocol)
-     * Uploads to staging location (uploads/{id}/) using anon key
+     * Uploads to staging location (uploads/{id}/) using the publishable key
      * File is later moved to final location by API after finalization
      * @param env - Environment (dev or prod)
      * @param path - Staging storage path (uploads/{id}/file.ext)

package/dist/gateways/supabase-gateway.js

@@ -2,10 +2,11 @@ import { createReadStream } from 'node:fs';
 import { createClient } from '@supabase/supabase-js';
 import * as tus from 'tus-js-client';
 import { ENVIRONMENTS } from '../config/environments.js';
+import { getSupabaseKey, supabaseKeyHeaders } from '../config/supabase-key.js';
 export class SupabaseGateway {
     /**
      * Upload to Supabase using resumable uploads (TUS protocol)
-     * Uploads to staging location (uploads/{id}/) using anon key
+     * Uploads to staging location (uploads/{id}/) using the publishable key
      * File is later moved to final location by API after finalization
      * @param env - Environment (dev or prod)
      * @param path - Staging storage path (uploads/{id}/file.ext)
@@ -15,7 +16,8 @@ export class SupabaseGateway {
      * @returns Promise that resolves when upload completes
      */
     static async uploadResumable(env, path, source, debug = false, onProgress) {
-        const { anonKey: SUPABASE_PUBLIC_KEY, projectRef } = ENVIRONMENTS[env].supabase;
+        const { projectRef } = ENVIRONMENTS[env].supabase;
+        const supabaseKey = await getSupabaseKey(env);
         const storageUrl = `https://${projectRef}.storage.supabase.co`;
         if (debug) {
             console.log(`[DEBUG] Resumable upload starting...`);
@@ -35,9 +37,9 @@ export class SupabaseGateway {
                 // Retry configuration - will retry 5 times with increasing delays
                 retryDelays: [0, 3000, 5000, 10_000, 20_000],
                 // Authentication and headers
-                // Use anon key for staging uploads to uploads/* folder
+                // Publishable key for staging uploads to uploads/* folder
                 headers: {
-                    authorization: `Bearer ${SUPABASE_PUBLIC_KEY}`,
+                    ...supabaseKeyHeaders(supabaseKey),
                     'x-upsert': 'true', // Allow overwriting existing files
                 },
                 // Upload metadata
@@ -93,7 +95,7 @@ export class SupabaseGateway {
         });
     }
     static async uploadToSignedUrl(env, path, token, file, debug = false) {
-        const { url: SUPABASE_URL, anonKey: SUPABASE_PUBLIC_KEY } = ENVIRONMENTS[env].supabase;
+        const { url: SUPABASE_URL } = ENVIRONMENTS[env].supabase;
         if (debug) {
             console.log(`[DEBUG] Supabase upload starting...`);
             console.log(`[DEBUG] Supabase URL: ${SUPABASE_URL}`);
@@ -102,7 +104,7 @@ export class SupabaseGateway {
             console.log(`[DEBUG] File type: ${file.type}`);
         }
         try {
-            const supabase = createClient(SUPABASE_URL, SUPABASE_PUBLIC_KEY);
+            const supabase = createClient(SUPABASE_URL, await getSupabaseKey(env));
             const uploadToUrl = await supabase.storage
                 .from('organizations')
                 .uploadToSignedUrl(path, token, file);

package/dist/index.js

@@ -13,7 +13,7 @@ import { upgradeCommand } from './commands/upgrade.js';
 import { uploadCommand } from './commands/upload.js';
 import { whoamiCommand } from './commands/whoami.js';
 import { telemetry } from './services/telemetry.service.js';
-import { CliError, getCliVersion, logger } from './utils/cli.js';
+import { CliError, getCliVersion, logger, wantsJson } from './utils/cli.js';
 import { withoutHiddenArgs } from './utils/help.js';
 // @clack/prompts ships the US spelling ("Canceled") for its built-in
 // spinner/prompt cancellation message; align it with the British spelling
@@ -88,9 +88,12 @@ async function run() {
         await telemetry.flush();
     }
     catch (error) {
+        // Under --json, stdout must stay a single JSON object: no help text, and
+        // the error itself is printed as `{ status: 'FAILED', error }`.
+        const json = wantsJson(rawArgs);
         // citty throws CLIError (by name — the class isn't exported) for usage
         // problems like unknown commands or missing required args.
-        if (error instanceof Error && error.name === 'CLIError') {
+        if (!json && error instanceof Error && error.name === 'CLIError') {
             await showHelp(rawArgs);
         }
         const exitCode = error instanceof CliError ? error.exitCode : 1;
@@ -98,6 +101,7 @@ async function run() {
         // synchronously, and exits with the given code.
         logger.error(error instanceof Error ? error : String(error), {
             exit: exitCode,
+            json,
         });
     }
 }

package/dist/services/report-download.service.d.ts

@@ -17,6 +17,13 @@ export interface ReportDownloadOptions extends DownloadOptions {
     junitPath?: string;
     reportType: 'allure' | 'html' | 'html-detailed' | 'junit';
 }
+/** What one download attempt did; failures are warned about, not thrown. */
+export interface DownloadResult {
+    error?: string;
+    ok: boolean;
+    path: string;
+    type: 'allure' | 'artifacts' | 'html' | 'junit';
+}
 /**
  * Service for downloading test artifacts and reports
  */
@@ -24,21 +31,21 @@ export declare class ReportDownloadService {
     /**
      * Download test artifacts as a zip file
      * @param options Download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did
      */
-    downloadArtifacts(options: ArtifactsDownloadOptions): Promise<void>;
+    downloadArtifacts(options: ArtifactsDownloadOptions): Promise<DownloadResult>;
     /**
      * Handle downloading reports based on the report type specified
      * @param options Report download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did, or undefined for an unknown report type
      */
-    downloadReports(options: ReportDownloadOptions): Promise<void>;
+    downloadReports(options: ReportDownloadOptions): Promise<DownloadResult | undefined>;
     /**
      * Download a specific report type
      * @param type Report type to download
      * @param filePath Path where report should be saved
      * @param options Download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did
      */
     private downloadReport;
     /**

package/dist/services/report-download.service.js

@@ -8,7 +8,7 @@ export class ReportDownloadService {
     /**
      * Download test artifacts as a zip file
      * @param options Download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did
      */
     async downloadArtifacts(options) {
         const { apiUrl, auth, uploadId, downloadType, artifactsPath = './artifacts.zip', debug = false, logger, warnLogger, } = options;
@@ -23,53 +23,53 @@ export class ReportDownloadService {
                 logger('\n');
                 logger(`Test artifacts have been downloaded to ${artifactsPath}`);
             }
+            return { ok: true, path: artifactsPath, type: 'artifacts' };
         }
         catch (error) {
             if (debug && logger) {
                 logger(`[DEBUG] Error downloading artifacts: ${error}`);
             }
             this.warnDownloadFailure(warnLogger, 'artifacts', 'No artifacts found for this upload. Make sure your tests generated results.', error);
+            return { error: errorText(error), ok: false, path: artifactsPath, type: 'artifacts' };
         }
     }
     /**
      * Handle downloading reports based on the report type specified
      * @param options Report download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did, or undefined for an unknown report type
      */
     async downloadReports(options) {
         const { reportType, junitPath, allurePath, htmlPath, warnLogger, ...downloadOptions } = options;
         switch (reportType) {
             case 'junit': {
                 const reportPath = path.resolve(process.cwd(), junitPath || 'report.xml');
-                await this.downloadReport('junit', reportPath, {
+                return this.downloadReport('junit', reportPath, {
                     ...downloadOptions,
                     warnLogger,
                 });
-                break;
             }
             case 'allure': {
                 const reportPath = path.resolve(process.cwd(), allurePath || 'report.html');
-                await this.downloadReport('allure', reportPath, {
+                return this.downloadReport('allure', reportPath, {
                     ...downloadOptions,
                     warnLogger,
                 });
-                break;
             }
             case 'html':
             case 'html-detailed': {
                 // The HTML report is a ZIP (report.html plus its screenshots and
                 // assets), so the default name says so. An explicit path is kept as-is.
                 const htmlReportPath = path.resolve(process.cwd(), htmlPath || 'report.zip');
-                await this.downloadReport('html', htmlReportPath, {
+                return this.downloadReport('html', htmlReportPath, {
                     ...downloadOptions,
                     warnLogger,
                 });
-                break;
             }
             default: {
                 if (warnLogger) {
                     warnLogger(`Unknown report type: ${reportType}`);
                 }
+                return undefined;
             }
         }
     }
@@ -78,7 +78,7 @@ export class ReportDownloadService {
      * @param type Report type to download
      * @param filePath Path where report should be saved
      * @param options Download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did
      */
     async downloadReport(type, filePath, options) {
         const { apiUrl, auth, uploadId, debug = false, logger, warnLogger } = options;
@@ -91,12 +91,14 @@ export class ReportDownloadService {
             if (logger) {
                 logger(`${type.toUpperCase()} test report has been downloaded to ${filePath}`);
             }
+            return { ok: true, path: filePath, type };
         }
         catch (error) {
             if (debug && logger) {
                 logger(`[DEBUG] Error downloading ${type.toUpperCase()} report: ${error}`);
             }
             this.warnDownloadFailure(warnLogger, `${type.toUpperCase()} report`, `No ${type.toUpperCase()} reports found for this upload. Make sure your tests generated results.`, error);
+            return { error: errorText(error), ok: false, path: filePath, type };
         }
     }
     /**
@@ -112,7 +114,7 @@ export class ReportDownloadService {
         if (!warnLogger) {
             return;
         }
-        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorMessage = errorText(error);
         warnLogger(`Failed to download ${subject}: ${errorMessage}`);
         if (errorMessage.includes('404')) {
             warnLogger(notFoundHint);
@@ -125,3 +127,6 @@ export class ReportDownloadService {
         }
     }
 }
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/utils/auth.js

@@ -9,7 +9,6 @@
  * poll), which re-checks with isAuthExpiring / refreshAuth below.
  */
 import { closeSync, openSync, rmSync, statSync } from 'node:fs';
-import { ENVIRONMENTS } from '../config/environments.js';
 import { CliAuthGateway, SessionRefreshError, } from '../gateways/cli-auth-gateway.js';
 import { telemetry } from '../services/telemetry.service.js';
 import { CliError } from './cli.js';
@@ -144,10 +143,9 @@ async function refreshSessionWithLock(initial) {
         if (session.expires_at > now + REFRESH_SKEW_SECONDS) {
             return { config: current, session };
         }
-        const { anonKey } = ENVIRONMENTS[current.env].supabase;
         let refreshed;
         try {
-            refreshed = await CliAuthGateway.refresh(current.supabase_url, anonKey, session);
+            refreshed = await CliAuthGateway.refresh(current.supabase_url, current.env, session);
         }
         catch (error) {
             if (error instanceof SessionRefreshError && error.definitive) {

package/dist/utils/ci.d.ts

@@ -10,6 +10,15 @@
  * counts — providers set `CI=true`, but a bare presence check is the safe net.
  */
 export declare function isCI(): boolean;
+/**
+ * Whether a prompt drawn on `output` can be answered: stdin and `output` must
+ * both be terminals. Without that (a script, CI, a shell an agent runs) a clack
+ * prompt waits for a keypress that never comes. Unlike isCI(), CI env vars
+ * don't count: a terminal with `CI=true` exported can still answer a prompt.
+ */
+export declare function canPrompt(output?: {
+    isTTY?: boolean;
+}): boolean;
 /** Which DCD CI integration (if any) is wrapping this CLI invocation, and its version. */
 export interface CiContext {
     /** e.g. 'github' | 'bitrise' | 'bitbucket' | 'eas' | 'gitlab' | 'circleci'. */

package/dist/utils/ci.js

@@ -37,6 +37,15 @@ export function isCI() {
     }
     return !process.stdout.isTTY;
 }
+/**
+ * Whether a prompt drawn on `output` can be answered: stdin and `output` must
+ * both be terminals. Without that (a script, CI, a shell an agent runs) a clack
+ * prompt waits for a keypress that never comes. Unlike isCI(), CI env vars
+ * don't count: a terminal with `CI=true` exported can still answer a prompt.
+ */
+export function canPrompt(output = process.stdout) {
+    return process.stdin.isTTY === true && output.isTTY === true;
+}
 /** Infer the CI provider from the env vars each platform sets natively. */
 function inferProvider() {
     const env = process.env;

package/dist/utils/cli.d.ts

@@ -9,13 +9,20 @@ export declare class CliError extends Error {
 export interface Logger {
     log(message: string): void;
     warn(message: string): void;
+    json(value: unknown): void;
     error(message: Error | string, opts?: {
         exit?: number;
         json?: boolean;
     }): never;
     exit(code?: number): never;
+    fail(message: Error | string, exitCode: number): never;
 }
 export declare const logger: Logger;
+/**
+ * Whether the invocation asked for JSON output. Read from raw argv so the
+ * top-level error handler can honour it even when citty never parsed args.
+ */
+export declare function wantsJson(rawArgs: string[]): boolean;
 /**
  * Validate that a string flag value is one of the allowed options.
  * Returns the value untouched on success; throws CliError otherwise.

package/dist/utils/cli.js

@@ -7,6 +7,7 @@
  *   sites ported from oclif keep working.
  */
 import { readFileSync } from 'node:fs';
+import { stripVTControlCharacters } from 'node:util';
 import { telemetry } from '../services/telemetry.service.js';
 import { symbols } from './styling.js';
 // Resolve version at runtime. The bun-compiled binary can't read package.json
@@ -57,13 +58,18 @@ export const logger = {
         // eslint-disable-next-line no-console
         console.warn(symbols.warning + ' ' + message);
     },
+    json(value) {
+        // The one stdout write under --json; everything else is gated off.
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(value, null, 2));
+    },
     error(message, opts = {}) {
         const text = message instanceof Error ? message.message : message;
         if (opts.json) {
             // When --json is active, emit failures as JSON on stdout so that
             // scripts consuming the output never need to parse stderr too.
-            // eslint-disable-next-line no-console
-            console.log(JSON.stringify({ status: 'FAILED', error: text }, null, 2));
+            // citty colours some of its messages; JSON consumers want plain text.
+            logger.json({ status: 'FAILED', error: stripVTControlCharacters(text) });
         }
         else {
             // The literal "Error:" prefix is important for tests and for grep-friendly
@@ -71,18 +77,29 @@ export const logger = {
             // eslint-disable-next-line no-console
             console.error(symbols.error + ' Error: ' + text);
         }
+        return logger.fail(message, opts.exit ?? 1);
+    },
+    exit(code = 0) {
+        process.exit(code);
+    },
+    // Exit as a failure without printing anything — for --json paths that have
+    // already written their result object and must not print a second one.
+    fail(message, exitCode) {
         // process.exit bypasses beforeExit, so async fetch in telemetry.flush()
         // would be killed mid-flight. flushSync uses curl to ship synchronously
         // before we exit; it's a no-op if telemetry never reached configure().
-        const exitCode = opts.exit ?? 1;
         telemetry.recordCommandFailure({ error: message, exitCode });
         telemetry.flushSync();
         process.exit(exitCode);
     },
-    exit(code = 0) {
-        process.exit(code);
-    },
 };
+/**
+ * Whether the invocation asked for JSON output. Read from raw argv so the
+ * top-level error handler can honour it even when citty never parsed args.
+ */
+export function wantsJson(rawArgs) {
+    return rawArgs.some((a) => a === '--json' || a === '--json=true');
+}
 /**
  * Validate that a string flag value is one of the allowed options.
  * Returns the value untouched on success; throws CliError otherwise.