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

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

@@ -4,8 +4,9 @@ import { CompatibilityData } from '../utils/compatibility';
  */
 export declare class VersionService {
     /**
-     * Check npm registry for the latest published version of the CLI
-     * @returns Latest version string or null if check fails
+     * Fetch the latest published CLI version from the release manifest.
+     * Works for both npm- and binary-installed users (no `npm` shell-out).
+     * Silently returns null on any failure — this check is informational only.
      */
     checkLatestCliVersion(): Promise<null | string>;
     /**

package/dist/services/version.service.js

@@ -1,27 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersionService = void 0;
-const node_child_process_1 = require("node:child_process");
+const DEFAULT_MANIFEST_URL = 'https://get.devicecloud.dev/latest.json';
+const MANIFEST_TIMEOUT_MS = 3000;
 /**
  * Service for handling version validation and checking
  */
 class VersionService {
     /**
-     * Check npm registry for the latest published version of the CLI
-     * @returns Latest version string or null if check fails
+     * Fetch the latest published CLI version from the release manifest.
+     * Works for both npm- and binary-installed users (no `npm` shell-out).
+     * Silently returns null on any failure — this check is informational only.
      */
     async checkLatestCliVersion() {
+        const url = process.env.DCD_MANIFEST_URL ?? DEFAULT_MANIFEST_URL;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), MANIFEST_TIMEOUT_MS);
         try {
-            const latestVersion = (0, node_child_process_1.execSync)('npm view @devicecloud.dev/dcd version', {
-                encoding: 'utf8',
-                stdio: ['ignore', 'pipe', 'ignore'],
-            }).trim();
-            return latestVersion;
+            const res = await fetch(url, { signal: controller.signal });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            return typeof data.version === 'string' ? data.version : null;
         }
         catch {
-            // Silently fail - version check is informational only
             return null;
         }
+        finally {
+            clearTimeout(timer);
+        }
     }
     /**
      * Compare two semantic version strings
@@ -30,8 +37,14 @@ class VersionService {
      * @returns true if current is older than latest
      */
     isOutdated(current, latest) {
-        const currentParts = current.split('.').map(Number);
-        const latestParts = latest.split('.').map(Number);
+        // Strip any prerelease suffix ("1.2.3-beta.1" -> "1.2.3") and default
+        // missing segments to 0 so short/prerelease versions still compare.
+        const parts = (version) => {
+            const nums = version.split('-')[0].split('.').map(Number);
+            return [nums[0] || 0, nums[1] || 0, nums[2] || 0];
+        };
+        const currentParts = parts(current);
+        const latestParts = parts(latest);
         for (let i = 0; i < 3; i++) {
             if (currentParts[i] < latestParts[i])
                 return true;
@@ -68,6 +81,9 @@ class VersionService {
                 log(`[DEBUG] Using default Maestro version ${defaultVersion}`);
             }
         }
+        if (!resolvedVersion) {
+            throw new Error('Unable to resolve a Maestro version: compatibility data did not provide a default.');
+        }
         // Validate Maestro version
         if (!supportedVersions.includes(resolvedVersion)) {
             throw new Error(`Maestro version ${resolvedVersion} is not supported. Supported versions: ${supportedVersions.join(', ')}`);

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

@@ -0,0 +1,12 @@
+/**
+ * Auth context threaded through gateways and services. Callers build this once
+ * (via resolveAuth) and the gateway spreads .headers into every fetch.
+ */
+export interface AuthContext {
+    headers: Record<string, string>;
+    mode: 'apiKey' | 'bearer';
+    /** Present when mode === 'bearer'. */
+    orgId?: string;
+    /** Present when mode === 'bearer'. */
+    userEmail?: string;
+}

package/dist/types/{schema.types.js → domain/auth.types.js}

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

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,4 @@
+"use strict";
+// Hand-defined: the swagger spec has no /live routes, so openapi-typescript
+// cannot generate these in schema.types.ts.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/auth.d.ts

@@ -0,0 +1,13 @@
+import type { AuthContext } from '../types/domain/auth.types';
+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,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAuth = resolveAuth;
+/**
+ * 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.
+ */
+const node_fs_1 = require("node:fs");
+const environments_1 = require("../config/environments");
+const cli_auth_gateway_1 = require("../gateways/cli-auth-gateway");
+const telemetry_service_1 = require("../services/telemetry.service");
+const cli_1 = require("./cli");
+const config_store_1 = require("./config-store");
+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;
+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_service_1.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_service_1.telemetry.configure({ auth });
+            return auth;
+        }
+    }
+    if (opts.skipSession) {
+        throw missingCredentialsError();
+    }
+    let config = (0, config_store_1.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 cli_1.CliError('No active organization set. Run `dcd switch-org <slug>` to pick one.');
+    }
+    const auth = {
+        mode: 'bearer',
+        orgId: config.current_org_id,
+        userEmail: session.user_email,
+        headers: {
+            authorization: `Bearer ${session.access_token}`,
+            'x-dcd-org': config.current_org_id,
+        },
+    };
+    telemetry_service_1.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 = `${(0, config_store_1.getConfigPath)()}.lock`;
+    await acquireRefreshLock(lockPath);
+    try {
+        // Re-read: another process may have refreshed while we waited.
+        const current = (0, config_store_1.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_1.ENVIRONMENTS[current.env].supabase;
+        const refreshed = await cli_auth_gateway_1.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 = { ...((0, config_store_1.readConfig)() ?? current), session: refreshed };
+        (0, config_store_1.writeConfig)(merged);
+        return { config: merged, session: refreshed };
+    }
+    finally {
+        try {
+            (0, node_fs_1.rmSync)(lockPath, { force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+async function acquireRefreshLock(lockPath) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            (0, node_fs_1.closeSync)((0, node_fs_1.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 {
+                    (0, node_fs_1.rmSync)(lockPath, { force: true });
+                }
+                catch { /* best effort */ }
+                try {
+                    (0, node_fs_1.closeSync)((0, node_fs_1.openSync)(lockPath, 'wx'));
+                }
+                catch { /* best effort */ }
+                return;
+            }
+            try {
+                if (Date.now() - (0, node_fs_1.statSync)(lockPath).mtimeMs > LOCK_STALE_MS) {
+                    // Holder presumed dead — take over.
+                    (0, node_fs_1.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 cli_1.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/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,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.CliError = void 0;
+exports.getCliVersion = getCliVersion;
+exports.getInstallMethod = getInstallMethod;
+exports.getUpgradeCommand = getUpgradeCommand;
+exports.validateEnum = validateEnum;
+exports.coerceArray = coerceArray;
+exports.parseIntFlag = parseIntFlag;
+/**
+ * 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.
+ */
+const telemetry_service_1 = require("../services/telemetry.service");
+const styling_1 = require("./styling");
+// Resolve version at runtime — avoids pulling package.json into the tsbuildinfo rootDir.
+function getCliVersion() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pkg = require('../../package.json');
+        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.
+function getInstallMethod() {
+    return typeof process.versions.bun === 'string'
+        ? 'binary'
+        : 'npm';
+}
+function getUpgradeCommand() {
+    return getInstallMethod() === 'binary'
+        ? 'dcd upgrade'
+        : 'npm install -g @devicecloud.dev/dcd@latest';
+}
+class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'CliError';
+    }
+}
+exports.CliError = CliError;
+exports.logger = {
+    log(message) {
+        // eslint-disable-next-line no-console
+        console.log(message);
+    },
+    warn(message) {
+        // eslint-disable-next-line no-console
+        console.warn(styling_1.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(styling_1.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_service_1.telemetry.recordCommandFailure({ error: message, exitCode });
+        telemetry_service_1.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.
+ */
+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).
+ */
+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.
+ */
+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';
 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

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchCompatibilityData = fetchCompatibilityData;
 exports.clearCompatibilityCache = clearCompatibilityCache;
 let cachedCompatibilityData = null;
-async function fetchCompatibilityData(apiUrl, apiKey) {
+async function fetchCompatibilityData(apiUrl, auth) {
     if (cachedCompatibilityData) {
         return cachedCompatibilityData;
     }
@@ -11,7 +11,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',
         });

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;