@devicecloud.dev/dcd 5.11.0-beta.1 → 5.11.0-beta.3

package/dist/types/domain/device-session.types.d.ts

@@ -0,0 +1,197 @@
+export type DeviceSessionState = 'active' | 'expired' | 'failed' | 'needs_human' | 'provisioning' | 'queued' | 'ready' | 'released';
+/** States a session can no longer leave. */
+export declare const ENDED_STATES: readonly DeviceSessionState[];
+/**
+ * The compact `session` block every /device/sessions response carries
+ * (ILiveSessionSummary in the API). `id` is the session name, which every
+ * `dcd device` command takes.
+ */
+export interface DeviceSession {
+    id: string;
+    live_id: number;
+    state: DeviceSessionState;
+    release_reason: null | string;
+    platform: string;
+    model: null | string;
+    client_label: null | string;
+    created_at: string;
+    queue: {
+        eta_s: null | number;
+        position: null | number;
+        reason: 'fleet_busy' | 'waiting_for_device';
+    } | null;
+    time_remaining_s: null | number;
+    idle_remaining_s: null | number;
+    cost_so_far_usd: null | number;
+    last_crash: {
+        at: string;
+        summary: string;
+    } | null;
+    /**
+     * The build the session asked for and where its install is. Null when no
+     * build was asked for; absent from APIs older than this field.
+     */
+    install?: {
+        binary_upload_id: string;
+        error: null | string;
+        status: 'failed' | 'installed' | 'installing';
+    } | null;
+    warnings: string[];
+    monitor_url: string;
+}
+/**
+ * GET .../human and POST .../request-human (ILiveHumanStatus in the API):
+ * whether the session waits for a person, and what they said on handing back.
+ */
+export interface DeviceHumanStatus {
+    /** The session is in needs_human: wait, polling this. */
+    waiting: boolean;
+    /** Why help was asked for, while waiting. */
+    reason: null | string;
+    /** When help was asked for, while waiting. */
+    since: null | string;
+    /** When the session ends unless a person hands it back, while waiting. */
+    expires_at: null | string;
+    /** A person handed the session back since help was last asked for. */
+    handed_back: boolean;
+    /** Their note, if they left one. */
+    note: null | string;
+    handed_back_at: null | string;
+    /** A person has taken control in the console; commands answer 409 meanwhile. */
+    human_in_control: boolean;
+    controller_user_id: null | string;
+}
+/** POST /device/sessions. */
+export interface StartDeviceSessionRequest {
+    platform: 'android' | 'ios';
+    binaryUploadId?: string;
+    model?: string;
+    os?: string;
+    googlePlay?: boolean;
+    deviceLocale?: string;
+    clientLabel?: string;
+    maxDurationMin?: number;
+    record?: boolean;
+}
+/** One entry of GET /device/models. */
+export interface DeviceModel {
+    model: string;
+    name: string;
+    os: string[];
+    default_os: string;
+    google_play: boolean;
+    default: boolean;
+}
+export interface DeviceCatalogue {
+    android: DeviceModel[];
+    ios: DeviceModel[];
+}
+/** What POST .../install answers with beside the session. */
+export interface DeviceInstalledApp {
+    app_id: null | string;
+    binary_upload_id: string;
+    reused: boolean;
+}
+/** One flow of a run, as newer APIs report it in `result.flows`. */
+export interface DeviceFlowResult {
+    error: null | string;
+    /** The flow's path inside the bundle; null for a single flow. */
+    file: null | string;
+    success: boolean;
+}
+/** The result of a typed action, a launch or a run. */
+export interface DeviceCommandResult {
+    error?: string;
+    /** Each flow of a run. Absent from APIs older than this field. */
+    flows?: DeviceFlowResult[];
+    output?: string;
+    success: boolean;
+}
+/** One element of the compact screen (Maestro's key names). */
+export interface DeviceScreenElement {
+    /** Bounds, "[left,top][right,bottom]". */
+    b: string;
+    a11y?: string;
+    hint?: string;
+    rid?: string;
+    txt?: string;
+}
+/** GET .../inspect: the elements worth targeting, and what each key means. */
+export interface DeviceScreen {
+    elements: DeviceScreenElement[];
+    /** False when no new frame came in time; this is then the latest. */
+    fresh: boolean;
+    height: number;
+    keys: Record<string, string>;
+    width: number;
+}
+/** GET .../screenshot. */
+export interface DeviceScreenshot {
+    captured_at: null | string;
+    /** A JPEG data URL. */
+    data_url: string;
+    fresh: boolean;
+}
+/** POST .../run and GET .../commands/:id. */
+export interface DeviceRunResponse {
+    command_id: string;
+    result: DeviceCommandResult | null;
+    session: DeviceSession;
+    /** `running` when the flow outlasted the API's wait: poll the command. */
+    status: 'failed' | 'passed' | 'running';
+}
+/** GET .../logs. */
+export interface DeviceLogs {
+    app_id: null | string;
+    lines: string[];
+    /** logcat, ios-unified-log, or none before an app is installed. */
+    source: string;
+}
+/** A short-lived download link for one stored artifact. */
+export interface DeviceArtifactLink {
+    bytes: null | number;
+    content_type: string;
+    created_at: string;
+    /** Null when the file could not be signed (e.g. already cleaned up). */
+    url: null | string;
+}
+/** GET .../artifacts: one page, newest actions first. */
+export interface DeviceArtifactsPage {
+    actions: {
+        command_id: null | string;
+        created_at: string;
+        hierarchy: DeviceArtifactLink | null;
+        screenshot: DeviceArtifactLink | null;
+    }[];
+    logs: DeviceArtifactLink | null;
+    /** Pass as `before` for the next (older) page; null on the last page. */
+    next_before: null | string;
+    /**
+     * Files the runner is still uploading after the session ended: the video
+     * and the device log land up to a minute or so later. Absent from APIs
+     * older than this field.
+     */
+    pending?: ('logs' | 'recording')[];
+    recording: DeviceArtifactLink | null;
+    session: DeviceSession;
+}
+/** POST /device/bundles/upload-url: where to PUT the zip (both, when both are given). */
+export interface DeviceBundleUploadUrls {
+    id: string;
+    mirror: {
+        path: string;
+        signedUrl: string;
+    } | null;
+    upload: {
+        path: string;
+        signedUrl: string;
+    } | null;
+}
+/** A registered flow bundle. `run` takes its id as `flowUploadId`. */
+export interface DeviceFlowBundle {
+    bytes: number;
+    created_at: string;
+    encrypted: boolean;
+    id: string;
+    sha: string;
+}

package/dist/types/domain/device-session.types.js

@@ -0,0 +1,5 @@
+// Hand-defined: the /device/sessions routes are not in the swagger spec the
+// CLI generates schema.types.ts from. They mirror the API's own types in
+// dcd/api/src/apps/live/live.types.ts and device-sessions.controller.ts.
+/** States a session can no longer leave. */
+export const ENDED_STATES = ['released', 'expired', 'failed'];

package/dist/utils/app-upload.d.ts

@@ -0,0 +1,19 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+/** The platform a local build is for, from its file name; undefined if unknown. */
+export declare function platformOfAppFile(filePath: string): 'android' | 'ios' | undefined;
+export interface UploadLocalAppOptions {
+    apiUrl: string;
+    auth: AuthContext;
+    filePath: string;
+    /** Show the upload's progress spinner. Only on a TTY, never under --json. */
+    showProgress: boolean;
+    /** One line of progress for a person, e.g. the encryption notice. */
+    log: (message: string) => void;
+}
+/**
+ * Upload a local build the way `dcd upload` does, and return its binary id:
+ * an Expo `.tar.gz` is unpacked to its `.app`, a `.zip` is checked, and the
+ * org's encryption default applies. URLs are not handled here: `dcd device`
+ * hands those to the API's install-from-URL instead.
+ */
+export declare function uploadLocalApp(opts: UploadLocalAppOptions): Promise<string>;

package/dist/utils/app-upload.js

@@ -0,0 +1,69 @@
+import { rm } from 'node:fs/promises';
+import { uploadBinary, verifyAppZip } from '../methods.js';
+import { detectCiContext } from './ci.js';
+import { CliError, getCliVersion } from './cli.js';
+import { fetchCompatibilityData } from './compatibility.js';
+import { checkKekForEncryption, resolveEncryption } from './envelope.js';
+import { extractTarGz, findAppBundle } from './expo.js';
+const APP_EXTENSIONS = ['.apk', '.app', '.zip', '.tar.gz'];
+/** The platform a local build is for, from its file name; undefined if unknown. */
+export function platformOfAppFile(filePath) {
+    const clean = filePath.replace(/\/+$/, '');
+    if (clean.endsWith('.apk'))
+        return 'android';
+    if (['.app', '.zip', '.tar.gz'].some((ext) => clean.endsWith(ext)))
+        return 'ios';
+    return undefined;
+}
+/**
+ * Upload a local build the way `dcd upload` does, and return its binary id:
+ * an Expo `.tar.gz` is unpacked to its `.app`, a `.zip` is checked, and the
+ * org's encryption default applies. URLs are not handled here: `dcd device`
+ * hands those to the API's install-from-URL instead.
+ */
+export async function uploadLocalApp(opts) {
+    const { apiUrl, auth, log } = opts;
+    let filePath = opts.filePath.replace(/\/+$/, '');
+    if (!APP_EXTENSIONS.some((ext) => filePath.endsWith(ext))) {
+        throw new CliError('The app must be a .apk for Android, or a .app, .zip or .tar.gz (Expo) for iOS.');
+    }
+    // As in `dcd upload`: a failed compatibility fetch leaves the default off
+    // rather than failing the upload.
+    let serverDefault;
+    try {
+        const ci = detectCiContext();
+        const compatibility = await fetchCompatibilityData(apiUrl, auth, {
+            cliVersion: getCliVersion(),
+            ciProvider: ci.provider,
+            ciWrapperVersion: ci.wrapperVersion,
+        });
+        serverDefault = compatibility.encryption?.defaultOn;
+    }
+    catch {
+        serverDefault = undefined;
+    }
+    const encryption = await checkKekForEncryption(resolveEncryption({ serverDefault }), apiUrl);
+    if (encryption.notice)
+        log(encryption.notice);
+    const tempDirs = [];
+    try {
+        if (filePath.endsWith('.tar.gz')) {
+            const dir = await extractTarGz(filePath, false);
+            tempDirs.push(dir);
+            filePath = await findAppBundle(dir);
+        }
+        if (filePath.endsWith('.zip'))
+            await verifyAppZip(filePath);
+        return await uploadBinary({
+            apiUrl,
+            auth,
+            encrypt: encryption.enabled,
+            filePath,
+            log: opts.showProgress,
+        });
+    }
+    finally {
+        for (const dir of tempDirs)
+            await rm(dir, { force: true, recursive: true }).catch(() => { });
+    }
+}

package/dist/utils/auth.d.ts

@@ -44,11 +44,3 @@ export declare function refreshAuth(auth: AuthContext): Promise<AuthContext>;
  * next attempt may get past.
  */
 export declare function isDefinitiveAuthFailure(error: unknown): boolean;
-/**
- * Remove only the (definitively dead) session from the stored config, keeping
- * env/api_url/org so a re-login lands back in the same environment. With the
- * dead session gone, subsequent commands report "Not authenticated" instead
- * of failing the same refresh, and `dcd login` skips its "already logged in"
- * confirm. Exported for tests.
- */
-export declare function dropStoredSession(): void;

package/dist/utils/auth.js

@@ -143,16 +143,14 @@ async function refreshSessionWithLock(initial) {
         if (session.expires_at > now + REFRESH_SKEW_SECONDS) {
             return { config: current, session };
         }
-        let refreshed;
-        try {
-            refreshed = await CliAuthGateway.refresh(current.supabase_url, current.env, session);
-        }
-        catch (error) {
-            if (error instanceof SessionRefreshError && error.definitive) {
-                dropStoredSession();
-            }
-            throw error;
-        }
+        // A failed refresh never deletes the stored session, even one Supabase
+        // refused outright. A refusal is not always the session's fault: an old
+        // CLI build sending a retired Supabase key gets a 401 ("Legacy API keys
+        // are disabled") for a session that is still good, and wiping it then
+        // forced a fresh login when an upgrade alone would have fixed it. The
+        // error tells the user to log in again; only `dcd logout` (or the next
+        // `dcd login`) replaces the stored session.
+        const refreshed = await CliAuthGateway.refresh(current.supabase_url, current.env, 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 };
@@ -166,20 +164,6 @@ async function refreshSessionWithLock(initial) {
         catch { /* best effort */ }
     }
 }
-/**
- * Remove only the (definitively dead) session from the stored config, keeping
- * env/api_url/org so a re-login lands back in the same environment. With the
- * dead session gone, subsequent commands report "Not authenticated" instead
- * of failing the same refresh, and `dcd login` skips its "already logged in"
- * confirm. Exported for tests.
- */
-export function dropStoredSession() {
-    const config = readConfig();
-    if (!config?.session)
-        return;
-    delete config.session;
-    writeConfig(config);
-}
 async function acquireRefreshLock(lockPath) {
     const deadline = Date.now() + LOCK_WAIT_MS;
     for (;;) {

package/dist/utils/browser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Open `url` in the default browser. False if it isn't an http(s) URL or no
+ * opener could be started (none installed, as on a headless box).
+ *
+ * Only http(s) is opened, so a URL can't name a local file or start with `-`
+ * and be read as an option. No opener goes through a shell: Windows uses
+ * rundll32, because `cmd /c start` parses the URL again and treats its `&`
+ * as a command separator.
+ */
+export declare function openBrowser(url: string): Promise<boolean>;
+/**
+ * Start `bin` detached. False if it couldn't be started. A missing program is
+ * reported as an 'error' event, not thrown, and with no listener it would
+ * crash the process, so this waits for 'spawn' or 'error' to know.
+ */
+export declare function startOpener(bin: string, args: string[]): Promise<boolean>;

package/dist/utils/browser.js

@@ -0,0 +1,48 @@
+import { spawn } from 'node:child_process';
+/**
+ * Open `url` in the default browser. False if it isn't an http(s) URL or no
+ * opener could be started (none installed, as on a headless box).
+ *
+ * Only http(s) is opened, so a URL can't name a local file or start with `-`
+ * and be read as an option. No opener goes through a shell: Windows uses
+ * rundll32, because `cmd /c start` parses the URL again and treats its `&`
+ * as a command separator.
+ */
+export async function openBrowser(url) {
+    let href;
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return false;
+        href = parsed.href;
+    }
+    catch {
+        return false;
+    }
+    const cmd = process.platform === 'darwin'
+        ? { bin: 'open', args: [href] }
+        : process.platform === 'win32'
+            ? { bin: 'rundll32', args: ['url.dll,FileProtocolHandler', href] }
+            : { bin: 'xdg-open', args: [href] };
+    return startOpener(cmd.bin, cmd.args);
+}
+/**
+ * Start `bin` detached. False if it couldn't be started. A missing program is
+ * reported as an 'error' event, not thrown, and with no listener it would
+ * crash the process, so this waits for 'spawn' or 'error' to know.
+ */
+export function startOpener(bin, args) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(bin, args, { detached: true, stdio: 'ignore' });
+            child.once('spawn', () => {
+                child.unref();
+                resolve(true);
+            });
+            child.once('error', () => resolve(false));
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}

package/dist/utils/device-artifacts.d.ts

@@ -0,0 +1,55 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+import { type DeviceArtifactsPage, type DeviceSession } from '../types/domain/device-session.types.js';
+/** One file a session left behind, and where it goes on disk. */
+export interface DeviceArtifactFile {
+    /** recording, logs, screenshot or hierarchy. */
+    kind: 'hierarchy' | 'logs' | 'recording' | 'screenshot';
+    /** Relative to the output directory. */
+    file: string;
+    url: null | string;
+    bytes: null | number;
+    /** The action a screenshot or screen dump was taken after. */
+    command_id?: null | string;
+    created_at: string;
+}
+/** Every page of a session's artifacts. */
+export declare function fetchAllArtifacts(apiUrl: string, auth: AuthContext, id: string): Promise<{
+    pages: DeviceArtifactsPage[];
+    session: DeviceSession;
+}>;
+/**
+ * What a session's runner is still uploading: the video (`recording`) and
+ * the device log (`logs`) land up to a minute or so after the session ends.
+ * The API says so in `pending`. An API older than that field gets a guess:
+ * an ended session missing either file whose last activity (its newest
+ * action, else its start) was under three minutes ago. The session summary
+ * carries no end time, so the last activity stands in for it.
+ */
+export declare function pendingArtifacts(pages: DeviceArtifactsPage[], now?: number): ('logs' | 'recording')[];
+/** The warning for {@link pendingArtifacts}, or null when nothing is pending. */
+export declare function pendingArtifactsWarning(pending: ('logs' | 'recording')[]): null | string;
+/**
+ * Lay the artifacts out as files: `recording.mp4`, `device.log`, and per
+ * action `actions/001-screenshot.jpg` and `actions/001-screen.json`,
+ * numbered oldest first so the folder reads in order.
+ */
+export declare function planArtifactFiles(pages: DeviceArtifactsPage[]): DeviceArtifactFile[];
+/** Timeouts and retries for one artifact download. */
+export interface DownloadArtifactOptions {
+    /** Give up on an attempt that receives no data for this long. */
+    idleTimeoutMs?: number;
+    /** Give up on an attempt that takes longer than this in total. */
+    totalTimeoutMs?: number;
+    /** How many times to try each file before reporting it failed. */
+    attempts?: number;
+}
+/**
+ * Download every file with a link into `dir`, four at a time. Each file is
+ * tried twice (a stalled CDN response usually succeeds on a second
+ * request). Returns the files that could not be fetched, with why, rather
+ * than failing the rest.
+ */
+export declare function downloadArtifactFiles(dir: string, files: DeviceArtifactFile[], onFile?: (file: DeviceArtifactFile) => void, options?: DownloadArtifactOptions): Promise<{
+    file: string;
+    reason: string;
+}[]>;