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

package/dist/commands/live.js

@@ -0,0 +1,513 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveCommand = void 0;
+const citty_1 = require("citty");
+const node_fs_1 = require("node:fs");
+const environments_1 = require("../config/environments");
+const api_flags_1 = require("../config/flags/api.flags");
+const api_gateway_1 = require("../gateways/api-gateway");
+const auth_1 = require("../utils/auth");
+const cli_1 = require("../utils/cli");
+const config_store_1 = require("../utils/config-store");
+const styling_1 = require("../utils/styling");
+const PLATFORM_OPTIONS = ['android', 'ios'];
+const READY_TIMEOUT_MS = 180_000;
+const READY_POLL_MS = 2_000;
+async function requireAuth(keyFlag) {
+    return (0, auth_1.resolveAuth)({ apiKeyFlag: keyFlag });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Poll the session until it reports `ready` (RUNNING + device streaming),
+ * surfacing each new device phase so the user sees "Cloning device…",
+ * "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) {
+    const deadline = Date.now() + timeoutMs;
+    let lastPhase = '';
+    for (;;) {
+        const session = await api_gateway_1.ApiGateway.getLiveSession(apiUrl, auth, sessionName);
+        if (session.ready)
+            return session;
+        if (['CANCELLED', 'FAILED', 'STOPPED'].includes(session.status?.toUpperCase?.() ?? '')) {
+            throw new cli_1.CliError(`Session ${sessionName} is ${session.status}; cannot become ready.`);
+        }
+        const phase = session.device_state?.phase_label ?? session.device_state?.phase ?? session.status;
+        if (phase && phase !== lastPhase) {
+            lastPhase = phase;
+            cli_1.logger.log(`   ${styling_1.colors.dim(phase)}`);
+        }
+        if (Date.now() >= deadline) {
+            throw new cli_1.CliError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the device to be ready` +
+                (phase ? ` (last phase: ${phase})` : '') +
+                '.');
+        }
+        await sleep(READY_POLL_MS);
+    }
+}
+/**
+ * Strip a Maestro flow header (`appId: ...` config block up to and including the
+ * first `---`) so a whole flow file can be fed to the exec endpoint, which wants
+ * just the command list. Returns the input unchanged if there's no `---`.
+ */
+function extractFlowCommands(text) {
+    const lines = text.split(/\r?\n/);
+    const idx = lines.findIndex((l) => l.trim() === '---');
+    if (idx === -1)
+        return text.trim();
+    return lines.slice(idx + 1).join('\n').trim();
+}
+/**
+ * citty/mri silently drops the value after `--flag` when that value starts with
+ * `-` (e.g. `--yaml "- launchApp"`) for non-required string args. Recover it
+ * from the raw argv so the ergonomic inline form keeps working.
+ */
+function recoverFlagValue(flag, parsed, rawArgs) {
+    if (parsed && parsed.trim())
+        return parsed;
+    const eq = rawArgs.find((a) => a.startsWith(`${flag}=`));
+    if (eq)
+        return eq.slice(flag.length + 1);
+    const idx = rawArgs.indexOf(flag);
+    if (idx !== -1 && idx + 1 < rawArgs.length)
+        return rawArgs[idx + 1];
+    return parsed;
+}
+function readFlowFile(filePath) {
+    try {
+        return (0, node_fs_1.readFileSync)(filePath, 'utf8');
+    }
+    catch (err) {
+        throw new cli_1.CliError(`Could not read flow file '${filePath}': ${err.message}`);
+    }
+}
+function printExecResult(result) {
+    cli_1.logger.log(result.success
+        ? `${styling_1.symbols.success} Command executed successfully`
+        : `${styling_1.symbols.error} Command failed`);
+    if (result.output) {
+        cli_1.logger.log((0, styling_1.sectionHeader)('Output'));
+        cli_1.logger.log(result.output);
+    }
+    if (result.error) {
+        cli_1.logger.log((0, styling_1.sectionHeader)('Error'));
+        cli_1.logger.log(styling_1.colors.error(result.error));
+    }
+}
+const startSub = (0, citty_1.defineCommand)({
+    meta: { name: 'start', description: 'Start a new live device session' },
+    args: {
+        ...api_flags_1.apiFlags,
+        platform: {
+            type: 'string',
+            default: 'android',
+            description: 'Device platform (options: android, ios)',
+        },
+        'app-binary-id': {
+            type: 'string',
+            description: 'Binary upload ID to install on the device',
+        },
+        'device-locale': {
+            type: 'string',
+            description: 'Device locale, ISO-639-1 + ISO-3166-1, e.g. "de_DE"',
+        },
+        'android-device': {
+            type: 'string',
+            description: '[Android] Device profile to match a cloud run (options: pixel-6, pixel-6-pro, pixel-7, pixel-7-pro)',
+        },
+        'android-api-level': {
+            type: 'string',
+            description: '[Android] API level for the device, e.g. 34 (requires --android-device)',
+        },
+        wait: {
+            type: 'boolean',
+            default: false,
+            description: 'Block until the device is ready to accept commands',
+        },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const platform = (0, cli_1.validateEnum)(args.platform, PLATFORM_OPTIONS, 'platform');
+        const binaryId = args['app-binary-id'];
+        const deviceLocale = args['device-locale'];
+        const androidDevice = args['android-device'];
+        const androidApiLevel = args['android-api-level'];
+        if ((androidDevice || androidApiLevel) && platform !== 'android') {
+            throw new cli_1.CliError('--android-device/--android-api-level are only valid with --platform android.');
+        }
+        if (Boolean(androidDevice) !== Boolean(androidApiLevel)) {
+            throw new cli_1.CliError('--android-device and --android-api-level must be provided together.');
+        }
+        cli_1.logger.log(`${styling_1.symbols.running} Starting ${platform} live session...`);
+        const session = await api_gateway_1.ApiGateway.startLiveSession(apiUrl, auth, {
+            binaryUploadId: binaryId,
+            deviceLocale,
+            platform,
+            androidDevice,
+            androidApiLevel,
+        });
+        const frontendUrl = (0, environments_1.resolveFrontendUrl)(apiUrl);
+        cli_1.logger.log(`${styling_1.symbols.success} Live session started`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Session:')}    ${styling_1.colors.highlight(session.session_name)}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Platform:')}   ${session.platform}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Status:')}     ${session.status}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Console:')}    ${styling_1.colors.highlight(`${frontendUrl}/live?session=${session.session_name}`)}`);
+        if (args.wait) {
+            cli_1.logger.log('');
+            cli_1.logger.log(`${styling_1.symbols.running} Waiting for the device to be ready...`);
+            const ready = await waitForReady(apiUrl, auth, session.session_name);
+            cli_1.logger.log(`${styling_1.symbols.success} Device ready${ready.device_model ? ` (${ready.device_model})` : ''}`);
+        }
+        cli_1.logger.log('');
+        cli_1.logger.log(`   ${styling_1.colors.dim('Install a binary:')}  ${styling_1.colors.highlight(`dcd live install --session ${session.session_name} --app-binary-id <id>`)}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Run a flow:')}        ${styling_1.colors.highlight(`dcd live run --session ${session.session_name} path/to/flow.yaml`)}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Inspect screen:')}    ${styling_1.colors.highlight(`dcd live hierarchy --session ${session.session_name}`)}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Stop session:')}      ${styling_1.colors.highlight(`dcd live stop --session ${session.session_name}`)}`);
+    },
+});
+const installSub = (0, citty_1.defineCommand)({
+    meta: { name: 'install', description: 'Install a binary on the device' },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+        'app-binary-id': {
+            type: 'string',
+            required: true,
+            description: 'Binary upload ID to install on the device',
+        },
+        wait: {
+            type: 'boolean',
+            default: false,
+            description: 'Block until the device is ready again after installing',
+        },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        const binaryId = args['app-binary-id'];
+        cli_1.logger.log(`${styling_1.symbols.running} Installing binary ${styling_1.colors.highlight(binaryId)} on session ${styling_1.colors.highlight(sessionName)}...`);
+        await api_gateway_1.ApiGateway.installLiveBinary(apiUrl, auth, sessionName, binaryId);
+        cli_1.logger.log(`${styling_1.symbols.success} Binary installed successfully`);
+        if (args.wait) {
+            cli_1.logger.log(`${styling_1.symbols.running} Waiting for the device to be ready...`);
+            await waitForReady(apiUrl, auth, sessionName);
+            cli_1.logger.log(`${styling_1.symbols.success} Device ready`);
+        }
+    },
+});
+const execSub = (0, citty_1.defineCommand)({
+    meta: { name: 'exec', description: 'Execute Maestro YAML commands' },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+        yaml: { type: 'string', description: 'Maestro YAML commands to execute' },
+        file: {
+            type: 'string',
+            description: 'Path to a file containing the Maestro YAML to execute',
+        },
+        wait: {
+            type: 'boolean',
+            default: false,
+            description: 'Wait for the device to be ready before executing',
+        },
+    },
+    async run({ args, rawArgs }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        const inlineYaml = recoverFlagValue('--yaml', args.yaml, rawArgs);
+        const file = args.file;
+        if (inlineYaml && file) {
+            throw new cli_1.CliError('Pass either --yaml or --file, not both.');
+        }
+        const yaml = file ? readFlowFile(file) : inlineYaml;
+        if (!yaml || !yaml.trim()) {
+            throw new cli_1.CliError('Provide commands to execute via --yaml or --file.');
+        }
+        if (args.wait) {
+            await waitForReady(apiUrl, auth, sessionName);
+        }
+        cli_1.logger.log(`${styling_1.symbols.running} Executing commands on session ${styling_1.colors.highlight(sessionName)}...`);
+        const result = await api_gateway_1.ApiGateway.execLiveYaml(apiUrl, auth, sessionName, yaml);
+        printExecResult(result);
+    },
+});
+const runSub = (0, citty_1.defineCommand)({
+    meta: {
+        name: 'run',
+        description: 'Run a whole Maestro flow file against the live session',
+    },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+        wait: {
+            type: 'boolean',
+            default: false,
+            description: 'Wait for the device to be ready before running',
+        },
+        timeout: {
+            type: 'string',
+            default: '600',
+            description: 'Max seconds to wait for the flow to finish (default 600)',
+        },
+        flowFile: {
+            type: 'positional',
+            required: true,
+            description: 'Path to the Maestro flow file to run (e.g. flow.yaml)',
+        },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        const flowFile = args.flowFile;
+        const timeoutMs = Math.max(1, Number(args.timeout) || 600) * 1000;
+        const commands = extractFlowCommands(readFlowFile(flowFile));
+        if (!commands) {
+            throw new cli_1.CliError(`Flow file '${flowFile}' has no commands to run.`);
+        }
+        if (args.wait) {
+            await waitForReady(apiUrl, auth, sessionName);
+        }
+        cli_1.logger.log(`${styling_1.symbols.running} Running ${styling_1.colors.highlight(flowFile)} on session ${styling_1.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.
+        const submitted = await api_gateway_1.ApiGateway.execLiveYaml(apiUrl, auth, sessionName, commands, {
+            async: true,
+        });
+        if (!submitted.commandId) {
+            printExecResult(submitted);
+            if (!submitted.success)
+                throw new cli_1.CliError(submitted.error || 'Flow failed.', 2);
+            return;
+        }
+        const commandId = submitted.commandId;
+        const deadline = Date.now() + timeoutMs;
+        let lastKeepalive = Date.now();
+        for (;;) {
+            const status = await api_gateway_1.ApiGateway.getLiveCommand(apiUrl, auth, sessionName, commandId);
+            if (status.done) {
+                printExecResult(status);
+                if (!status.success)
+                    throw new cli_1.CliError(status.error || 'Flow failed.', 2);
+                return;
+            }
+            if (Date.now() >= deadline) {
+                throw new cli_1.CliError(`Flow still running after ${Math.round(timeoutMs / 1000)}s (command ${commandId}). ` +
+                    'Raise --timeout if the flow legitimately runs longer.', 2);
+            }
+            // Keep the session alive during long polls so the inactivity sweep
+            // doesn't cancel it mid-flow.
+            if (Date.now() - lastKeepalive > 60_000) {
+                await api_gateway_1.ApiGateway.keepaliveLiveSession(apiUrl, auth, sessionName);
+                lastKeepalive = Date.now();
+            }
+            await sleep(2_000);
+        }
+    },
+});
+const screenshotSub = (0, citty_1.defineCommand)({
+    meta: {
+        name: 'screenshot',
+        description: 'Save the current device screen to an image file (PNG/JPEG)',
+    },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+        output: {
+            type: 'string',
+            alias: ['o'],
+            description: 'File path to write the screenshot to (default: live-screenshot.<ext> matching the device format)',
+        },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        const session = await api_gateway_1.ApiGateway.getLiveSession(apiUrl, auth, sessionName);
+        const dataUrl = session.screenshot_data_url ?? session.hierarchy?.screenshot;
+        if (!dataUrl) {
+            throw new cli_1.CliError(`No screenshot available yet for ${sessionName}. The device may not be streaming — ` +
+                'try again, or start/install with --wait.');
+        }
+        const match = /^data:image\/(\w+);base64,(.+)$/s.exec(dataUrl);
+        const ext = match ? match[1].replace('jpeg', 'jpg') : 'png';
+        const base64 = match ? match[2] : dataUrl;
+        const output = args.output ?? `live-screenshot.${ext}`;
+        (0, node_fs_1.writeFileSync)(output, Buffer.from(base64, 'base64'));
+        cli_1.logger.log(`${styling_1.symbols.success} Screenshot saved to ${styling_1.colors.highlight(output)}`);
+        if (session.hierarchy) {
+            cli_1.logger.log(`   ${styling_1.colors.dim('Resolution:')} ${session.hierarchy.width}x${session.hierarchy.height}`);
+        }
+    },
+});
+const hierarchySub = (0, citty_1.defineCommand)({
+    meta: {
+        name: 'hierarchy',
+        description: 'Dump the current view hierarchy (the selectors you can tap/assert on)',
+    },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+        json: { type: 'boolean', description: 'Output the raw hierarchy as JSON' },
+        output: {
+            type: 'string',
+            alias: ['o'],
+            description: 'Write the output to a file instead of stdout',
+        },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        const json = Boolean(args.json);
+        const output = args.output;
+        const session = await api_gateway_1.ApiGateway.getLiveSession(apiUrl, auth, sessionName);
+        const hierarchy = session.hierarchy;
+        if (!hierarchy) {
+            throw new cli_1.CliError(`No hierarchy available yet for ${sessionName}. The device may not be streaming — ` +
+                'try again, or start/install with --wait.');
+        }
+        if (json) {
+            const out = JSON.stringify(hierarchy, null, 2);
+            if (output) {
+                (0, node_fs_1.writeFileSync)(output, out);
+                cli_1.logger.log(`${styling_1.symbols.success} Hierarchy written to ${styling_1.colors.highlight(output)}`);
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.log(out);
+            }
+            return;
+        }
+        // Human-readable: only the nodes worth selecting on (have text / a11y / id).
+        const lines = [];
+        lines.push(`Hierarchy — ${hierarchy.width}x${hierarchy.height}, ${hierarchy.elements.length} elements`);
+        for (const el of hierarchy.elements) {
+            const parts = [];
+            if (el.text)
+                parts.push(`"${el.text}"`);
+            if (el.accessibilityText)
+                parts.push(`a11y:"${el.accessibilityText}"`);
+            if (el.resourceId)
+                parts.push(`id:${el.resourceId}`);
+            if (parts.length === 0)
+                continue;
+            const bounds = el.bounds
+                ? `  ${styling_1.colors.dim(`(${el.bounds.x},${el.bounds.y} ${el.bounds.width}x${el.bounds.height})`)}`
+                : '';
+            lines.push(`  ${parts.join('  ')}${bounds}`);
+        }
+        const out = lines.join('\n');
+        if (output) {
+            (0, node_fs_1.writeFileSync)(output, `${out}\n`);
+            cli_1.logger.log(`${styling_1.symbols.success} Hierarchy written to ${styling_1.colors.highlight(output)}`);
+        }
+        else {
+            cli_1.logger.log(out);
+        }
+    },
+});
+const stopSub = (0, citty_1.defineCommand)({
+    meta: { name: 'stop', description: 'Stop a live session' },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        cli_1.logger.log(`${styling_1.symbols.running} Stopping session ${styling_1.colors.highlight(sessionName)}...`);
+        await api_gateway_1.ApiGateway.stopLiveSession(apiUrl, auth, sessionName);
+        cli_1.logger.log(`${styling_1.symbols.success} Session stopped`);
+    },
+});
+const statusSub = (0, citty_1.defineCommand)({
+    meta: { name: 'status', description: 'Get session status' },
+    args: {
+        ...api_flags_1.apiFlags,
+        session: { type: 'string', required: true, description: 'Live session name' },
+    },
+    async run({ args }) {
+        const auth = await requireAuth(args['api-key']);
+        const apiUrl = (0, config_store_1.resolveApiUrl)(args['api-url']);
+        const sessionName = args.session;
+        const session = await api_gateway_1.ApiGateway.getLiveSession(apiUrl, auth, sessionName);
+        cli_1.logger.log((0, styling_1.sectionHeader)('Live Session'));
+        cli_1.logger.log(`   ${styling_1.colors.dim('Session:')}    ${styling_1.colors.highlight(session.session_name)}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Platform:')}   ${session.platform}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Status:')}     ${session.status}`);
+        cli_1.logger.log(`   ${styling_1.colors.dim('Ready:')}      ${session.ready ? styling_1.colors.success('yes') : styling_1.colors.warning('no')}`);
+        const phase = session.device_state?.phase_label ?? session.device_state?.phase;
+        if (phase) {
+            cli_1.logger.log(`   ${styling_1.colors.dim('Phase:')}      ${phase}`);
+        }
+        if (session.device_model) {
+            cli_1.logger.log(`   ${styling_1.colors.dim('Device:')}     ${session.device_model}`);
+        }
+        if (session.device_locale) {
+            cli_1.logger.log(`   ${styling_1.colors.dim('Locale:')}     ${session.device_locale}`);
+        }
+        if (session.binary_upload_id) {
+            cli_1.logger.log(`   ${styling_1.colors.dim('Binary:')}     ${session.binary_upload_id}`);
+        }
+        if (typeof session.seconds_until_auto_cancel === 'number') {
+            cli_1.logger.log(`   ${styling_1.colors.dim('Auto-cancel in:')} ${session.seconds_until_auto_cancel}s`);
+        }
+        cli_1.logger.log(`   ${styling_1.colors.dim('Created:')}    ${new Date(session.created_at).toLocaleString()}`);
+    },
+});
+exports.liveCommand = (0, citty_1.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,
+    },
+    // 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 firstPositional = rawArgs.find((arg) => !arg.startsWith('-'));
+        if (firstPositional && subNames.has(firstPositional))
+            return;
+        cli_1.logger.log((0, styling_1.sectionHeader)('Live Session Commands'));
+        cli_1.logger.log(`   ${styling_1.colors.bold('start')}       Start a new live device session`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('install')}     Install a binary on the device`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('exec')}        Execute Maestro YAML commands`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('run')}         Run a whole Maestro flow file`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('screenshot')}  Save the current device screen to an image file`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('hierarchy')}   Dump the current view hierarchy (selectors)`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('stop')}        Stop a live session`);
+        cli_1.logger.log(`   ${styling_1.colors.bold('status')}      Get session status`);
+        cli_1.logger.log('');
+        cli_1.logger.log(`   Run ${styling_1.colors.highlight('dcd live <command> --help')} for details`);
+    },
+});
+exports.default = exports.liveCommand;

package/dist/commands/login.d.ts

@@ -0,0 +1,17 @@
+export declare const loginCommand: import("citty").CommandDef<{
+    'api-url': {
+        type: "string";
+        default: string;
+        description: string;
+    };
+    'frontend-url': {
+        type: "string";
+        description: string;
+    };
+    browser: {
+        type: "boolean";
+        default: true;
+        description: string;
+    };
+}>;
+export default loginCommand;