@devicecloud.dev/dcd 5.8.0 → 5.9.0

package/dist/commands/artifacts.d.ts

@@ -33,6 +33,10 @@ export declare const artifactsCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly description: "Custom file path for downloaded JUnit report (default: ./report.xml)";
     };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output the result as a single JSON object on stdout";
+    };
     readonly 'api-key': {
         readonly type: "string";
         readonly alias: ["apiKey"];

package/dist/commands/artifacts.js

@@ -1,6 +1,7 @@
 import { defineCommand } from 'citty';
 import { apiFlags } from '../config/flags/api.flags.js';
-import { ReportDownloadService } from '../services/report-download.service.js';
+import { jsonFlag } from '../config/flags/output.flags.js';
+import { ReportDownloadService, } from '../services/report-download.service.js';
 import { resolveAuth } from '../utils/auth.js';
 import { CliError, logger, validateEnum } from '../utils/cli.js';
 import { resolveApiUrl } from '../utils/config-store.js';
@@ -47,6 +48,7 @@ export const artifactsCommand = defineCommand({
             type: 'string',
             description: 'Custom file path for downloaded JUnit report (default: ./report.xml)',
         },
+        json: jsonFlag,
     },
     async run({ args }) {
         const apiKeyFlag = args['api-key'];
@@ -59,6 +61,9 @@ export const artifactsCommand = defineCommand({
         const allurePath = args['allure-path'];
         const htmlPath = args['html-path'];
         const junitPath = args['junit-path'];
+        const json = Boolean(args.json);
+        // Success lines are dropped under --json; warnings stay on stderr.
+        const log = json ? undefined : (m) => logger.log(m);
         const auth = await resolveAuth({ apiKeyFlag });
         if (downloadArtifacts && report) {
             throw new CliError('--download-artifacts cannot also be provided when using --report (flags are mutually exclusive).');
@@ -67,31 +72,41 @@ export const artifactsCommand = defineCommand({
             throw new CliError('Either --download-artifacts or --report must be specified.');
         }
         const service = new ReportDownloadService();
+        const downloads = [];
         if (downloadArtifacts) {
-            await service.downloadArtifacts({
+            downloads.push(await service.downloadArtifacts({
                 auth,
                 apiUrl,
                 artifactsPath: artifactsPath ?? './artifacts.zip',
                 debug,
                 downloadType: downloadArtifacts,
-                logger: (m) => logger.log(m),
+                logger: log,
                 uploadId,
                 warnLogger: (m) => logger.warn(m),
-            });
+            }));
         }
         if (report) {
-            await service.downloadReports({
+            const result = await service.downloadReports({
                 allurePath,
                 auth,
                 apiUrl,
                 debug,
                 htmlPath,
                 junitPath,
-                logger: (m) => logger.log(m),
+                logger: log,
                 reportType: report,
                 uploadId,
                 warnLogger: (m) => logger.warn(m),
             });
+            if (result)
+                downloads.push(result);
+        }
+        if (json) {
+            const ok = downloads.some((d) => d.ok);
+            logger.json({ status: ok ? 'SUCCESS' : 'FAILED', uploadId, downloads });
+            // Same exit code a thrown error would give, without a second JSON object.
+            if (!ok)
+                logger.fail('Every download failed', 1);
         }
     },
 });

package/dist/commands/cloud.js

@@ -751,8 +751,7 @@ export const cloudCommand = defineCommand({
                     });
                 }
                 if (json) {
-                    // eslint-disable-next-line no-console
-                    console.log(JSON.stringify(jsonOutput, null, 2));
+                    logger.json(jsonOutput);
                     return;
                 }
                 out(ui.info('Not waiting for results as async flag is set to true'));
@@ -874,8 +873,7 @@ export const cloudCommand = defineCommand({
                 await fsp.rm(p, { recursive: true, force: true }).catch(() => { });
             }
             if (output) {
-                // eslint-disable-next-line no-console
-                console.log(JSON.stringify(output, null, 2));
+                logger.json(output);
             }
         }
         if (caughtError) {

package/dist/commands/list.js

@@ -123,8 +123,7 @@ export const listCommand = defineCommand({
                     to,
                 }));
                 if (json) {
-                    // eslint-disable-next-line no-console
-                    console.log(JSON.stringify(response, null, 2));
+                    logger.json(response);
                     return;
                 }
                 displayResults(response, apiUrl);

package/dist/commands/live.js

@@ -2,9 +2,10 @@ import { defineCommand } from 'citty';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolveFrontendUrl } from '../config/environments.js';
 import { apiFlags } from '../config/flags/api.flags.js';
+import { jsonFlag } from '../config/flags/output.flags.js';
 import { ApiGateway } from '../gateways/api-gateway.js';
 import { resolveAuth } from '../utils/auth.js';
-import { CliError, logger, validateEnum } from '../utils/cli.js';
+import { CliError, logger, validateEnum, wantsJson } from '../utils/cli.js';
 import { resolveApiUrl } from '../utils/config-store.js';
 import { colors, formatUrl } from '../utils/styling.js';
 import { ui } from '../utils/ui.js';
@@ -14,6 +15,13 @@ const READY_POLL_MS = 2_000;
 async function requireAuth(keyFlag) {
     return resolveAuth({ apiKeyFlag: keyFlag });
 }
+/** Human output, dropped under --json so stdout carries only the result. */
+function humanLog(json) {
+    return (m) => {
+        if (!json)
+            logger.log(m);
+    };
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -23,7 +31,7 @@ function sleep(ms) {
  * "Installing app…", etc. Removes the need to hand-roll retry loops around the
  * 425/409 "not ready" window that `exec` returns right after start/install.
  */
-async function waitForReady(apiUrl, auth, sessionName, timeoutMs = READY_TIMEOUT_MS) {
+async function waitForReady(apiUrl, auth, sessionName, log = (m) => logger.log(m), timeoutMs = READY_TIMEOUT_MS) {
     const deadline = Date.now() + timeoutMs;
     let lastPhase = '';
     for (;;) {
@@ -36,7 +44,7 @@ async function waitForReady(apiUrl, auth, sessionName, timeoutMs = READY_TIMEOUT
         const phase = session.device_state?.phase_label ?? session.device_state?.phase ?? session.status;
         if (phase && phase !== lastPhase) {
             lastPhase = phase;
-            logger.log(`   ${colors.dim(phase)}`);
+            log(`   ${colors.dim(phase)}`);
         }
         if (Date.now() >= deadline) {
             throw new CliError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the device to be ready` +
@@ -82,7 +90,16 @@ function readFlowFile(filePath) {
         throw new CliError(`Could not read flow file '${filePath}': ${err.message}`);
     }
 }
-function printExecResult(result) {
+function printExecResult(result, json, extra = {}) {
+    if (json) {
+        logger.json({
+            success: result.success,
+            ...(result.output && { output: result.output }),
+            ...(result.error && { error: result.error }),
+            ...extra,
+        });
+        return;
+    }
     logger.log(result.success
         ? ui.success('Command executed successfully')
         : `${ui.statusSymbol('FAILED')} Command failed`);
@@ -125,6 +142,7 @@ const startSub = defineCommand({
             default: false,
             description: 'Block until the device is ready to accept commands',
         },
+        json: jsonFlag,
     },
     async run({ args }) {
         const auth = await requireAuth(args['api-key']);
@@ -140,12 +158,14 @@ const startSub = defineCommand({
         if (Boolean(androidDevice) !== Boolean(androidApiLevel)) {
             throw new CliError('--android-device and --android-api-level must be provided together.');
         }
-        logger.log(ui.warn(colors.bold('Live is in beta')));
-        logger.log(ui.branch([
+        const json = Boolean(args.json);
+        const out = humanLog(json);
+        out(ui.warn(colors.bold('Live is in beta')));
+        out(ui.branch([
             'Live device sessions are a beta feature, billed at $0.03/min.',
             `${colors.dim('Not enrolled?')} Contact support to request access.`,
         ]));
-        logger.log(ui.running(`Starting ${platform} live session…`));
+        out(ui.running(`Starting ${platform} live session…`));
         const session = await ApiGateway.startLiveSession(apiUrl, auth, {
             binaryUploadId: binaryId,
             deviceLocale,
@@ -154,17 +174,48 @@ const startSub = defineCommand({
             androidApiLevel,
         });
         const frontendUrl = resolveFrontendUrl(apiUrl);
-        logger.log(ui.success('Live session started'));
-        logger.log(ui.branch(ui.fields([
+        const consoleUrl = `${frontendUrl}/live?session=${session.session_name}`;
+        out(ui.success('Live session started'));
+        out(ui.branch(ui.fields([
             ['session', colors.highlight(session.session_name)],
             ['platform', session.platform],
             ['status', session.status],
-            ['console', formatUrl(`${frontendUrl}/live?session=${session.session_name}`)],
+            ['console', formatUrl(consoleUrl)],
         ])));
+        let ready;
         if (args.wait) {
-            logger.log(ui.running('Waiting for the device to be ready…'));
-            const ready = await waitForReady(apiUrl, auth, session.session_name);
-            logger.log(ui.success(`Device ready${ready.device_model ? ` (${ready.device_model})` : ''}`));
+            out(ui.running('Waiting for the device to be ready…'));
+            try {
+                ready = await waitForReady(apiUrl, auth, session.session_name, out);
+            }
+            catch (error) {
+                // The session exists and is billing. Under --json the name was never
+                // printed, so the top-level `{ status, error }` would leave a script
+                // with no way to `dcd live stop` it. Report the name with the error.
+                if (!json)
+                    throw error;
+                logger.json({
+                    status: 'FAILED',
+                    error: error instanceof Error ? error.message : String(error),
+                    session_name: session.session_name,
+                    platform: session.platform,
+                    ready: false,
+                    consoleUrl,
+                });
+                logger.fail(error instanceof Error ? error : String(error), error instanceof CliError ? error.exitCode : 1);
+            }
+            out(ui.success(`Device ready${ready.device_model ? ` (${ready.device_model})` : ''}`));
+        }
+        if (json) {
+            logger.json({
+                session_name: session.session_name,
+                platform: session.platform,
+                status: ready?.status ?? session.status,
+                ready: Boolean(ready?.ready),
+                consoleUrl,
+                ...(ready?.device_model && { device_model: ready.device_model }),
+            });
+            return;
         }
         logger.log(ui.section('Next steps'));
         logger.log(ui.branch(ui.fields([
@@ -180,6 +231,7 @@ const installSub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
+        json: jsonFlag,
         'app-binary-id': {
             type: 'string',
             required: true,
@@ -196,13 +248,23 @@ const installSub = defineCommand({
         const apiUrl = resolveApiUrl(args['api-url']);
         const sessionName = args.session;
         const binaryId = args['app-binary-id'];
-        logger.log(ui.running(`Installing binary ${colors.highlight(binaryId)} on session ${colors.highlight(sessionName)}…`));
+        const json = Boolean(args.json);
+        const out = humanLog(json);
+        out(ui.running(`Installing binary ${colors.highlight(binaryId)} on session ${colors.highlight(sessionName)}…`));
         await ApiGateway.installLiveBinary(apiUrl, auth, sessionName, binaryId);
-        logger.log(ui.success('Binary installed successfully'));
+        out(ui.success('Binary installed successfully'));
         if (args.wait) {
-            logger.log(ui.running('Waiting for the device to be ready…'));
-            await waitForReady(apiUrl, auth, sessionName);
-            logger.log(ui.success('Device ready'));
+            out(ui.running('Waiting for the device to be ready…'));
+            await waitForReady(apiUrl, auth, sessionName, out);
+            out(ui.success('Device ready'));
+        }
+        if (json) {
+            logger.json({
+                status: 'SUCCESS',
+                session: sessionName,
+                appBinaryId: binaryId,
+                ready: Boolean(args.wait),
+            });
         }
     },
 });
@@ -211,6 +273,7 @@ const execSub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
+        json: jsonFlag,
         yaml: { type: 'string', description: 'Maestro YAML commands to execute' },
         file: {
             type: 'string',
@@ -235,12 +298,14 @@ const execSub = defineCommand({
         if (!yaml || !yaml.trim()) {
             throw new CliError('Provide commands to execute via --yaml or --file.');
         }
+        const json = Boolean(args.json);
+        const out = humanLog(json);
         if (args.wait) {
-            await waitForReady(apiUrl, auth, sessionName);
+            await waitForReady(apiUrl, auth, sessionName, out);
         }
-        logger.log(ui.running(`Executing commands on session ${colors.highlight(sessionName)}…`));
+        out(ui.running(`Executing commands on session ${colors.highlight(sessionName)}…`));
         const result = await ApiGateway.execLiveYaml(apiUrl, auth, sessionName, yaml);
-        printExecResult(result);
+        printExecResult(result, json);
     },
 });
 const runSub = defineCommand({
@@ -251,6 +316,7 @@ const runSub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
+        json: jsonFlag,
         wait: {
             type: 'boolean',
             default: false,
@@ -277,10 +343,22 @@ const runSub = defineCommand({
         if (!commands) {
             throw new CliError(`Flow file '${flowFile}' has no commands to run.`);
         }
+        const json = Boolean(args.json);
+        const out = humanLog(json);
+        // Print the result, then fail with exit 2 if the flow failed. Under --json
+        // the result object is the output, so exit without printing a second one.
+        const finish = (result, extra = {}) => {
+            printExecResult(result, json, extra);
+            if (result.success)
+                return;
+            if (json)
+                logger.fail(result.error || 'Flow failed.', 2);
+            throw new CliError(result.error || 'Flow failed.', 2);
+        };
         if (args.wait) {
-            await waitForReady(apiUrl, auth, sessionName);
+            await waitForReady(apiUrl, auth, sessionName, out);
         }
-        logger.log(ui.running(`Running ${colors.highlight(flowFile)} on session ${colors.highlight(sessionName)}…`));
+        out(ui.running(`Running ${colors.highlight(flowFile)} on session ${colors.highlight(sessionName)}…`));
         // Submit asynchronously and poll, so a long flow isn't capped by the
         // server's 120s synchronous exec limit. Older servers ignore `async` and
         // return the full result inline — handle that by falling through.
@@ -288,9 +366,7 @@ const runSub = defineCommand({
             async: true,
         });
         if (!submitted.commandId) {
-            printExecResult(submitted);
-            if (!submitted.success)
-                throw new CliError(submitted.error || 'Flow failed.', 2);
+            finish(submitted);
             return;
         }
         const commandId = submitted.commandId;
@@ -299,9 +375,7 @@ const runSub = defineCommand({
         for (;;) {
             const status = await ApiGateway.getLiveCommand(apiUrl, auth, sessionName, commandId);
             if (status.done) {
-                printExecResult(status);
-                if (!status.success)
-                    throw new CliError(status.error || 'Flow failed.', 2);
+                finish(status, { commandId });
                 return;
             }
             if (Date.now() >= deadline) {
@@ -326,6 +400,7 @@ const screenshotSub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
+        json: jsonFlag,
         output: {
             type: 'string',
             alias: ['o'],
@@ -347,6 +422,18 @@ const screenshotSub = defineCommand({
         const base64 = match ? match[2] : dataUrl;
         const output = args.output ?? `live-screenshot.${ext}`;
         writeFileSync(output, Buffer.from(base64, 'base64'));
+        if (args.json) {
+            logger.json({
+                status: 'SUCCESS',
+                path: output,
+                format: ext,
+                ...(session.hierarchy && {
+                    width: session.hierarchy.width,
+                    height: session.hierarchy.height,
+                }),
+            });
+            return;
+        }
         logger.log(ui.success(`Screenshot saved to ${colors.highlight(output)}`));
         if (session.hierarchy) {
             logger.log(ui.branch(ui.fields([
@@ -363,7 +450,10 @@ const hierarchySub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
-        json: { type: 'boolean', description: 'Output the raw hierarchy as JSON' },
+        json: {
+            type: 'boolean',
+            description: 'Output the raw hierarchy as JSON (with --output, the file gets the hierarchy and stdout gets { status, path })',
+        },
         output: {
             type: 'string',
             alias: ['o'],
@@ -383,14 +473,12 @@ const hierarchySub = defineCommand({
                 'try again, or start/install with --wait.');
         }
         if (json) {
-            const out = JSON.stringify(hierarchy, null, 2);
             if (output) {
-                writeFileSync(output, out);
-                logger.log(ui.success(`Hierarchy written to ${colors.highlight(output)}`));
+                writeFileSync(output, JSON.stringify(hierarchy, null, 2));
+                logger.json({ status: 'SUCCESS', path: output });
             }
             else {
-                // eslint-disable-next-line no-console
-                console.log(out);
+                logger.json(hierarchy);
             }
             return;
         }
@@ -427,13 +515,19 @@ const stopSub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
+        json: jsonFlag,
     },
     async run({ args }) {
         const auth = await requireAuth(args['api-key']);
         const apiUrl = resolveApiUrl(args['api-url']);
         const sessionName = args.session;
-        logger.log(ui.running(`Stopping session ${colors.highlight(sessionName)}…`));
+        const json = Boolean(args.json);
+        humanLog(json)(ui.running(`Stopping session ${colors.highlight(sessionName)}…`));
         await ApiGateway.stopLiveSession(apiUrl, auth, sessionName);
+        if (json) {
+            logger.json({ status: 'SUCCESS', session: sessionName });
+            return;
+        }
         logger.log(ui.success('Session stopped'));
     },
 });
@@ -442,12 +536,20 @@ const statusSub = defineCommand({
     args: {
         ...apiFlags,
         session: { type: 'string', required: true, description: 'Live session name' },
+        json: jsonFlag,
     },
     async run({ args }) {
         const auth = await requireAuth(args['api-key']);
         const apiUrl = resolveApiUrl(args['api-url']);
         const sessionName = args.session;
         const session = await ApiGateway.getLiveSession(apiUrl, auth, sessionName);
+        if (args.json) {
+            // The screenshot and hierarchy are large; `screenshot` / `hierarchy`
+            // are the commands for those.
+            const { hierarchy: _hierarchy, screenshot_data_url: _screenshot, ...rest } = session;
+            logger.json(rest);
+            return;
+        }
         const fields = [
             ['session', colors.highlight(session.session_name)],
             ['platform', session.platform],
@@ -475,39 +577,40 @@ const statusSub = defineCommand({
         logger.log(ui.branch(ui.fields(fields)));
     },
 });
+const subCommands = {
+    start: startSub,
+    install: installSub,
+    exec: execSub,
+    run: runSub,
+    screenshot: screenshotSub,
+    hierarchy: hierarchySub,
+    stop: stopSub,
+    status: statusSub,
+};
 export const liveCommand = defineCommand({
     meta: {
         name: 'live',
         description: 'Start and interact with a live device session',
     },
-    subCommands: {
-        start: startSub,
-        install: installSub,
-        exec: execSub,
-        run: runSub,
-        screenshot: screenshotSub,
-        hierarchy: hierarchySub,
-        stop: stopSub,
-        status: statusSub,
-    },
+    subCommands,
     // citty's runCommand does not early-return after dispatching to a
     // subcommand — it still invokes the parent `run` afterwards. So when a
     // subcommand was matched, bail out here; otherwise the menu would print
     // after every successful subcommand.
     run({ rawArgs }) {
-        const subNames = new Set([
-            'start',
-            'install',
-            'exec',
-            'run',
-            'screenshot',
-            'hierarchy',
-            'stop',
-            'status',
-        ]);
+        const subNames = new Set(Object.keys(subCommands));
         const firstPositional = rawArgs.find((arg) => !arg.startsWith('-'));
         if (firstPositional && subNames.has(firstPositional))
             return;
+        if (wantsJson(rawArgs)) {
+            logger.json({
+                commands: Object.entries(subCommands).map(([name, sub]) => ({
+                    name,
+                    description: sub.meta.description,
+                })),
+            });
+            return;
+        }
         logger.log(ui.section('Live Session Commands'));
         logger.log(ui.branch(ui.fields([
             [colors.bold('start'), 'Start a new live device session'],

package/dist/commands/login.d.ts

@@ -13,5 +13,13 @@ export declare const loginCommand: import("citty").CommandDef<{
         readonly default: true;
         readonly description: "Open the login URL in a browser (pass --no-browser to just print it)";
     };
+    readonly org: {
+        readonly type: "string";
+        readonly description: "Organization to use, by name or id (skips the picker)";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output the result as a single JSON object on stdout";
+    };
 }>;
 export default loginCommand;