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

package/dist/types/domain/live.types.d.ts

@@ -0,0 +1,76 @@
+/** Summary returned when a live session is created. */
+export interface LiveSessionSummary {
+    id: number;
+    platform: string;
+    session_name: string;
+    status: string;
+}
+/** One node of the device view hierarchy, as the live API exposes it. */
+export interface LiveHierarchyElement {
+    id: string;
+    text?: string;
+    accessibilityText?: string;
+    resourceId?: string;
+    resourceIdIndex?: number;
+    textIndex?: number;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** The device view hierarchy plus the frame it was captured against. */
+export interface LiveHierarchy {
+    elements: LiveHierarchyElement[];
+    width: number;
+    height: number;
+    /** base64 PNG of the frame the hierarchy was captured against. */
+    screenshot: string;
+}
+/** Where the device is in its boot/stream lifecycle. */
+export interface LiveDeviceState {
+    phase: string;
+    /** Server-derived human label for `phase` — prefer this over mapping it. */
+    phase_label?: string;
+    last_seen_at?: string;
+}
+/**
+ * Full live session record returned by `GET /live/:identifier`. The API returns
+ * far more than the create summary — including the current screenshot, the view
+ * hierarchy, and a `ready` flag — which the screenshot/hierarchy/--wait commands
+ * read directly.
+ */
+export interface LiveSession extends LiveSessionSummary {
+    binary_upload_id: null | string;
+    created_at: string;
+    device_state?: LiveDeviceState | null;
+    /** Current device frame as a `data:image/png;base64,...` URL. */
+    screenshot_data_url?: null | string;
+    hierarchy?: LiveHierarchy | null;
+    /** True when the session can accept exec requests (RUNNING + streaming). */
+    ready?: boolean;
+    /** Model the simulator actually cloned, e.g. "pixel-7-api-34". */
+    device_model?: null | string;
+    /** Locale requested for the session, e.g. "de_DE", or null for default. */
+    device_locale?: null | string;
+    seconds_until_auto_cancel?: null | number;
+}
+/** Result of executing Maestro YAML against a live session. */
+export interface LiveExecResult {
+    error?: string;
+    output?: string;
+    success: boolean;
+    /** Async mode only: id of the queued command to poll, and its submit status. */
+    commandId?: string;
+    status?: string;
+}
+/** Status of a queued live command (async exec poll). */
+export interface LiveCommandStatus {
+    status: string;
+    /** True once the command reached a terminal state (passed/failed/timeout). */
+    done: boolean;
+    success: boolean;
+    output?: string;
+    error?: string;
+}

package/dist/types/domain/live.types.js

@@ -0,0 +1,3 @@
+// Hand-defined: the swagger spec has no /live routes, so openapi-typescript
+// cannot generate these in schema.types.ts.
+export {};

package/dist/types/generated/schema.types.js

@@ -1,3 +1,2 @@
-"use strict";
 /* eslint-disable prettier/prettier */
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/index.d.ts

@@ -2,5 +2,5 @@
  * Centralized type exports.
  * Types are organized by domain in subdirectories.
  */
-export * from './domain/device.types';
-export * from './generated/schema.types';
+export * from './domain/device.types.js';
+export * from './generated/schema.types.js';

package/dist/types/index.js

@@ -1,24 +1,8 @@
-"use strict";
 /**
  * Centralized type exports.
  * Types are organized by domain in subdirectories.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
 // Domain-specific types
-__exportStar(require("./domain/device.types"), exports);
+export * from './domain/device.types.js';
 // Generated types from OpenAPI schema
-__exportStar(require("./generated/schema.types"), exports);
+export * from './generated/schema.types.js';

package/dist/types.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/utils/auth.d.ts

@@ -0,0 +1,13 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+export interface ResolveAuthOptions {
+    apiKeyFlag: string | undefined;
+    /** When true, bypass stored session entirely (for `dcd login` itself). */
+    skipSession?: boolean;
+    /**
+     * When true, ignore the --api-key flag / DEVICE_CLOUD_API_KEY env and
+     * resolve straight from the stored session (for `dcd switch-org`, which
+     * needs a browser login even when an API key is exported).
+     */
+    sessionOnly?: boolean;
+}
+export declare function resolveAuth(opts: ResolveAuthOptions): Promise<AuthContext>;

package/dist/utils/auth.js

@@ -0,0 +1,141 @@
+/**
+ * Resolves which credential a command should use and returns the fetch headers
+ * to send. Precedence: --api-key flag > DEVICE_CLOUD_API_KEY env > stored
+ * Supabase session (refreshed if near expiry). Throws CliError if none found.
+ *
+ * The refresh path writes the rotated tokens back to disk atomically. Callers
+ * use the returned AuthContext for the duration of the command — one resolve
+ * per invocation, not per request.
+ */
+import { closeSync, openSync, rmSync, statSync } from 'node:fs';
+import { ENVIRONMENTS } from '../config/environments.js';
+import { CliAuthGateway } from '../gateways/cli-auth-gateway.js';
+import { telemetry } from '../services/telemetry.service.js';
+import { CliError } from './cli.js';
+import { getConfigPath, readConfig, writeConfig, } from './config-store.js';
+const REFRESH_SKEW_SECONDS = 60;
+// Refresh lock tuning: a refresh is a single HTTP round-trip, so anything
+// holding the lock longer than this is presumed dead.
+const LOCK_STALE_MS = 10_000;
+const LOCK_WAIT_MS = 10_000;
+const LOCK_POLL_MS = 250;
+export async function resolveAuth(opts) {
+    if (!opts.sessionOnly) {
+        const flag = opts.apiKeyFlag?.trim();
+        if (flag) {
+            const auth = {
+                mode: 'apiKey',
+                headers: { 'x-app-api-key': flag },
+            };
+            telemetry.configure({ auth });
+            return auth;
+        }
+        const env = process.env.DEVICE_CLOUD_API_KEY?.trim();
+        if (env) {
+            const auth = {
+                mode: 'apiKey',
+                headers: { 'x-app-api-key': env },
+            };
+            telemetry.configure({ auth });
+            return auth;
+        }
+    }
+    if (opts.skipSession) {
+        throw missingCredentialsError();
+    }
+    let config = readConfig();
+    if (!config?.session) {
+        throw missingCredentialsError();
+    }
+    const now = Math.floor(Date.now() / 1000);
+    let session = config.session;
+    if (session.expires_at <= now + REFRESH_SKEW_SECONDS) {
+        ({ config, session } = await refreshSessionWithLock(config));
+    }
+    if (!config.current_org_id) {
+        throw new CliError('No active organization set. Run `dcd switch-org <slug>` to pick one.');
+    }
+    const auth = {
+        mode: 'bearer',
+        accessToken: session.access_token,
+        env: config.env,
+        orgId: config.current_org_id,
+        userEmail: session.user_email,
+        headers: {
+            authorization: `Bearer ${session.access_token}`,
+            'x-dcd-org': config.current_org_id,
+        },
+    };
+    telemetry.configure({ auth, apiUrl: config.api_url });
+    return auth;
+}
+/**
+ * Refresh the stored session under a config-adjacent lockfile so two
+ * concurrent `dcd` invocations (CI matrices) can't both consume the same
+ * Supabase refresh token — token rotation would revoke the session family.
+ */
+async function refreshSessionWithLock(initial) {
+    const lockPath = `${getConfigPath()}.lock`;
+    await acquireRefreshLock(lockPath);
+    try {
+        // Re-read: another process may have refreshed while we waited.
+        const current = readConfig() ?? initial;
+        const session = current.session ?? initial.session;
+        const now = Math.floor(Date.now() / 1000);
+        if (session.expires_at > now + REFRESH_SKEW_SECONDS) {
+            return { config: current, session };
+        }
+        const { anonKey } = ENVIRONMENTS[current.env].supabase;
+        const refreshed = await CliAuthGateway.refresh(current.supabase_url, anonKey, session);
+        // Re-read again and merge only `session` so a concurrent `switch-org`
+        // write (org fields) isn't reverted by our pre-refresh snapshot.
+        const merged = { ...(readConfig() ?? current), session: refreshed };
+        writeConfig(merged);
+        return { config: merged, session: refreshed };
+    }
+    finally {
+        try {
+            rmSync(lockPath, { force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+async function acquireRefreshLock(lockPath) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            closeSync(openSync(lockPath, 'wx'));
+            return;
+        }
+        catch {
+            if (Date.now() >= deadline) {
+                // Don't hang the command forever: steal the lock if possible and
+                // proceed regardless — worst case we race like the pre-lock code did.
+                try {
+                    rmSync(lockPath, { force: true });
+                }
+                catch { /* best effort */ }
+                try {
+                    closeSync(openSync(lockPath, 'wx'));
+                }
+                catch { /* best effort */ }
+                return;
+            }
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                    // Holder presumed dead — take over.
+                    rmSync(lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                // Lock vanished between open and stat — fall through to a short
+                // sleep (not an immediate retry) so persistent fs errors can't spin.
+            }
+            await new Promise((resolve) => { setTimeout(resolve, LOCK_POLL_MS); });
+        }
+    }
+}
+function missingCredentialsError() {
+    return new CliError('Not authenticated. Provide an API key via --api-key or the DEVICE_CLOUD_API_KEY environment variable, or run `dcd login`.');
+}

package/dist/utils/ci.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Best-effort detection of non-interactive / CI environments. Used to suppress
+ * interactive niceties (e.g. the `dcd login` nudge) that only make sense for a
+ * human at a terminal. Dependency-free on purpose — these are the env vars the
+ * major providers set, plus a TTY check for piped/redirected output.
+ */
+/**
+ * Returns true when running under CI or otherwise non-interactively (no TTY on
+ * stdout, e.g. output piped to a file). A truthy value for any known CI env var
+ * counts — providers set `CI=true`, but a bare presence check is the safe net.
+ */
+export declare function isCI(): boolean;

package/dist/utils/ci.js

@@ -0,0 +1,39 @@
+/**
+ * Best-effort detection of non-interactive / CI environments. Used to suppress
+ * interactive niceties (e.g. the `dcd login` nudge) that only make sense for a
+ * human at a terminal. Dependency-free on purpose — these are the env vars the
+ * major providers set, plus a TTY check for piped/redirected output.
+ */
+// Generic + per-provider markers. `CI` is set by virtually every provider;
+// the rest cover platforms that historically didn't set it.
+const CI_ENV_VARS = [
+    'CI',
+    'CONTINUOUS_INTEGRATION',
+    'BUILD_NUMBER',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'CIRCLECI',
+    'TRAVIS',
+    'BUILDKITE',
+    'DRONE',
+    'TEAMCITY_VERSION',
+    'TF_BUILD', // Azure Pipelines
+    'JENKINS_URL',
+    'BITBUCKET_BUILD_NUMBER',
+    'APPVEYOR',
+    'CODEBUILD_BUILD_ID',
+];
+/**
+ * Returns true when running under CI or otherwise non-interactively (no TTY on
+ * stdout, e.g. output piped to a file). A truthy value for any known CI env var
+ * counts — providers set `CI=true`, but a bare presence check is the safe net.
+ */
+export function isCI() {
+    for (const name of CI_ENV_VARS) {
+        const value = process.env[name];
+        if (value !== undefined && value !== '' && value !== 'false' && value !== '0') {
+            return true;
+        }
+    }
+    return !process.stdout.isTTY;
+}

package/dist/utils/cli.d.ts

@@ -0,0 +1,35 @@
+export declare function getCliVersion(): string;
+export type InstallMethod = 'binary' | 'npm';
+export declare function getInstallMethod(): InstallMethod;
+export declare function getUpgradeCommand(): string;
+export declare class CliError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export interface Logger {
+    log(message: string): void;
+    warn(message: string): void;
+    error(message: Error | string, opts?: {
+        exit?: number;
+        json?: boolean;
+    }): never;
+    exit(code?: number): never;
+}
+export declare const logger: Logger;
+/**
+ * Validate that a string flag value is one of the allowed options.
+ * Returns the value untouched on success; throws CliError otherwise.
+ */
+export declare function validateEnum<T extends string>(value: string | undefined, allowed: readonly T[], flagName: string): T | 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).
+ */
+export declare function coerceArray(value: string | string[] | undefined, split?: boolean): string[];
+/**
+ * Parse an integer flag. Returns undefined if the value is undefined/empty.
+ * Throws CliError if the value is not a valid integer.
+ */
+export declare function parseIntFlag(value: string | undefined, flagName: string): number | undefined;

package/dist/utils/cli.js

@@ -0,0 +1,118 @@
+/**
+ * Shared helpers for command files.
+ * - Version lookup from package.json
+ * - Enum validation for string flags (citty 0.1.6 has no native enum)
+ * - Array coercion for repeatable flags with comma-separated values
+ * - A minimal Logger mirroring the oclif Command log/warn/error shape so call
+ *   sites ported from oclif keep working.
+ */
+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.
+export function getCliVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// The Bun runtime sets process.versions.bun; bun-compiled standalone binaries
+// inherit this. Node-run installs (npm/pnpm/npx/tsx) don't expose it.
+export function getInstallMethod() {
+    return typeof process.versions.bun === 'string'
+        ? 'binary'
+        : 'npm';
+}
+export function getUpgradeCommand() {
+    return getInstallMethod() === 'binary'
+        ? 'dcd upgrade'
+        : 'npm install -g @devicecloud.dev/dcd@latest';
+}
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'CliError';
+    }
+}
+export const logger = {
+    log(message) {
+        // eslint-disable-next-line no-console
+        console.log(message);
+    },
+    warn(message) {
+        // eslint-disable-next-line no-console
+        console.warn(symbols.warning + ' ' + message);
+    },
+    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));
+        }
+        else {
+            // The literal "Error:" prefix is important for tests and for grep-friendly
+            // CI logs — it survives color stripping and matches /error/i assertions.
+            // eslint-disable-next-line no-console
+            console.error(symbols.error + ' Error: ' + text);
+        }
+        // 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);
+    },
+};
+/**
+ * Validate that a string flag value is one of the allowed options.
+ * Returns the value untouched on success; throws CliError otherwise.
+ */
+export function validateEnum(value, allowed, flagName) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    if (!allowed.includes(value)) {
+        throw new CliError(`Invalid value for --${flagName}: "${value}". Expected one of: ${allowed.join(', ')}`);
+    }
+    return value;
+}
+/**
+ * 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).
+ */
+export function coerceArray(value, split = true) {
+    if (value === undefined)
+        return [];
+    const arr = Array.isArray(value) ? value : [value];
+    if (!split)
+        return arr;
+    return arr.flatMap((v) => v.split(','));
+}
+/**
+ * Parse an integer flag. Returns undefined if the value is undefined/empty.
+ * Throws CliError if the value is not a valid integer.
+ */
+export function parseIntFlag(value, flagName) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    // All integer flags (limit/offset/retry) are non-negative; also rejects
+    // trailing garbage that parseInt would silently accept ("20abc" -> 20).
+    const trimmed = String(value).trim();
+    if (!/^\d+$/.test(trimmed)) {
+        throw new CliError(`Invalid integer value for --${flagName}: "${value}"`);
+    }
+    return Number.parseInt(trimmed, 10);
+}

package/dist/utils/compatibility.d.ts

@@ -1,3 +1,4 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
 export interface CompatibilityData {
     android: Record<string, string[]>;
     androidPlay: Record<string, string[]>;
@@ -8,5 +9,5 @@ export interface CompatibilityData {
         supportedVersions: string[];
     };
 }
-export declare function fetchCompatibilityData(apiUrl: string, apiKey: string): Promise<CompatibilityData>;
+export declare function fetchCompatibilityData(apiUrl: string, auth: AuthContext): Promise<CompatibilityData>;
 export declare function clearCompatibilityCache(): void;

package/dist/utils/compatibility.js

@@ -1,9 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fetchCompatibilityData = fetchCompatibilityData;
-exports.clearCompatibilityCache = clearCompatibilityCache;
 let cachedCompatibilityData = null;
-async function fetchCompatibilityData(apiUrl, apiKey) {
+export async function fetchCompatibilityData(apiUrl, auth) {
     if (cachedCompatibilityData) {
         return cachedCompatibilityData;
     }
@@ -11,7 +7,7 @@ async function fetchCompatibilityData(apiUrl, apiKey) {
         const response = await fetch(`${apiUrl}/results/compatibility/data`, {
             headers: {
                 'Content-Type': 'application/json',
-                'x-app-api-key': apiKey,
+                ...auth.headers,
             },
             method: 'GET',
         });
@@ -27,9 +23,11 @@ async function fetchCompatibilityData(apiUrl, apiKey) {
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to fetch compatibility data from API: ${errorMessage}`);
+        throw new Error(`Failed to fetch compatibility data from API: ${errorMessage}`, {
+            cause: error,
+        });
     }
 }
-function clearCompatibilityCache() {
+export function clearCompatibilityCache() {
     cachedCompatibilityData = null;
 }

package/dist/utils/config-store.d.ts

@@ -0,0 +1,35 @@
+export declare const CONFIG_SCHEMA_VERSION = 1;
+export interface StoredSession {
+    access_token: string;
+    refresh_token: string;
+    /** Unix epoch seconds. */
+    expires_at: number;
+    user_email: string;
+    user_id: string;
+}
+export interface StoredConfig {
+    version: number;
+    env: 'dev' | 'prod';
+    api_url: string;
+    supabase_url: string;
+    session?: StoredSession;
+    current_org_id?: string;
+    current_org_name?: string;
+}
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function readConfig(): StoredConfig | null;
+/**
+ * Resolve the API URL a command should talk to. Precedence:
+ *   1. explicit --api-url flag
+ *   2. api_url stored by `dcd login` (honors the env the user logged into)
+ *   3. prod default
+ *
+ * Without this, session commands default to prod and a dev/staging Bearer
+ * token is rejected with a misleading "Invalid or expired JWT". `switch-org`
+ * has always done this; this helper extends it to every command.
+ */
+export declare function resolveApiUrl(flag: string | undefined): string;
+export declare function writeConfig(config: StoredConfig): void;
+export declare function clearConfig(): void;
+export declare function configFileMode(): number | null;