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

package/dist/utils/device-artifacts.js

@@ -0,0 +1,211 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { DeviceGateway } from '../gateways/device-gateway.js';
+import { ENDED_STATES, } from '../types/domain/device-session.types.js';
+const EXTENSIONS = {
+    'application/json': 'json',
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'text/plain': 'log',
+    'video/mp4': 'mp4',
+};
+function extensionFor(link, fallback) {
+    return EXTENSIONS[link.content_type.split(';')[0].trim()] ?? fallback;
+}
+/** Every page of a session's artifacts. */
+export async function fetchAllArtifacts(apiUrl, auth, id) {
+    const pages = [];
+    let before;
+    do {
+        const page = await DeviceGateway.artifacts(apiUrl, auth, id, before);
+        pages.push(page);
+        before = page.next_before ?? undefined;
+    } while (before);
+    return { pages, session: pages.at(-1).session };
+}
+/** How long after a session ends its video and log may still be uploading. */
+const PENDING_WINDOW_MS = 3 * 60 * 1000;
+/**
+ * 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 function pendingArtifacts(pages, now = Date.now()) {
+    const first = pages[0];
+    if (!first)
+        return [];
+    if (Array.isArray(first.pending))
+        return first.pending;
+    if (!ENDED_STATES.includes(first.session.state))
+        return [];
+    const lastActivity = Date.parse(first.actions[0]?.created_at ?? first.session.created_at);
+    if (!Number.isFinite(lastActivity) || now - lastActivity > PENDING_WINDOW_MS)
+        return [];
+    const pending = [];
+    if (!first.recording)
+        pending.push('recording');
+    if (!first.logs)
+        pending.push('logs');
+    return pending;
+}
+/** The warning for {@link pendingArtifacts}, or null when nothing is pending. */
+export function pendingArtifactsWarning(pending) {
+    if (pending.length === 0)
+        return null;
+    const what = pending.length === 2
+        ? 'The video and device log are'
+        : pending[0] === 'recording'
+            ? 'The video is'
+            : 'The device log is';
+    return `${what} still uploading. Run this again in a minute.`;
+}
+/**
+ * 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 function planArtifactFiles(pages) {
+    const files = [];
+    const first = pages[0];
+    if (first?.recording) {
+        files.push({
+            kind: 'recording',
+            file: `recording.${extensionFor(first.recording, 'mp4')}`,
+            url: first.recording.url,
+            bytes: first.recording.bytes,
+            created_at: first.recording.created_at,
+        });
+    }
+    if (first?.logs) {
+        files.push({
+            kind: 'logs',
+            file: `device.${extensionFor(first.logs, 'log')}`,
+            url: first.logs.url,
+            bytes: first.logs.bytes,
+            created_at: first.logs.created_at,
+        });
+    }
+    const actions = pages.flatMap((p) => p.actions).reverse();
+    const width = Math.max(3, String(actions.length).length);
+    for (const [i, action] of actions.entries()) {
+        const n = String(i + 1).padStart(width, '0');
+        if (action.screenshot) {
+            files.push({
+                kind: 'screenshot',
+                file: path.join('actions', `${n}-screenshot.${extensionFor(action.screenshot, 'jpg')}`),
+                url: action.screenshot.url,
+                bytes: action.screenshot.bytes,
+                command_id: action.command_id,
+                created_at: action.created_at,
+            });
+        }
+        if (action.hierarchy) {
+            files.push({
+                kind: 'hierarchy',
+                file: path.join('actions', `${n}-screen.${extensionFor(action.hierarchy, 'json')}`),
+                url: action.hierarchy.url,
+                bytes: action.hierarchy.bytes,
+                command_id: action.command_id,
+                created_at: action.created_at,
+            });
+        }
+    }
+    return files;
+}
+const CONCURRENCY = 4;
+const DEFAULT_IDLE_TIMEOUT_MS = 30_000;
+const DEFAULT_TOTAL_TIMEOUT_MS = 10 * 60_000;
+const DEFAULT_ATTEMPTS = 2;
+function seconds(ms) {
+    return ms >= 1000 ? `${Math.round(ms / 1000)}s` : `${ms}ms`;
+}
+/**
+ * Fetch one URL to `target`. Aborts when no data arrives for `idleMs`
+ * (including while waiting for the response headers) or when the whole
+ * download takes longer than `totalMs`. A CDN stream can stall without
+ * closing, and without these the command would wait for it forever.
+ */
+async function downloadOnce(url, target, idleMs, totalMs) {
+    const controller = new AbortController();
+    const abort = (reason) => controller.abort(new Error(reason));
+    let idle = setTimeout(() => abort(`timed out: no data for ${seconds(idleMs)}`), idleMs);
+    const total = setTimeout(() => abort(`timed out: took longer than ${seconds(totalMs)}`), totalMs);
+    const resetIdle = () => {
+        clearTimeout(idle);
+        idle = setTimeout(() => abort(`timed out: no data for ${seconds(idleMs)}`), idleMs);
+    };
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok || !res.body)
+            throw new Error(`HTTP ${res.status}`);
+        resetIdle();
+        const body = Readable.fromWeb(res.body);
+        await pipeline(body, async function* (source) {
+            for await (const chunk of source) {
+                resetIdle();
+                yield chunk;
+            }
+        }, createWriteStream(target), { signal: controller.signal });
+    }
+    catch (error) {
+        // Report the timeout, not the AbortError it surfaces as.
+        if (controller.signal.aborted && controller.signal.reason instanceof Error) {
+            throw controller.signal.reason;
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(idle);
+        clearTimeout(total);
+    }
+}
+/**
+ * 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 async function downloadArtifactFiles(dir, files, onFile = () => { }, options = {}) {
+    const idleMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    const totalMs = options.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS;
+    const attempts = Math.max(1, options.attempts ?? DEFAULT_ATTEMPTS);
+    const failed = [];
+    const queue = [...files];
+    async function worker() {
+        for (let next = queue.shift(); next; next = queue.shift()) {
+            if (!next.url) {
+                failed.push({ file: next.file, reason: 'no download link (it may have been cleaned up)' });
+                continue;
+            }
+            const target = path.join(dir, next.file);
+            let reason = '';
+            for (let attempt = 1; attempt <= attempts; attempt++) {
+                try {
+                    await mkdir(path.dirname(target), { recursive: true });
+                    await downloadOnce(next.url, target, idleMs, totalMs);
+                    reason = '';
+                    break;
+                }
+                catch (error) {
+                    reason = error instanceof Error ? error.message : String(error);
+                }
+            }
+            if (reason) {
+                // Don't leave a half-written file that looks like a real one.
+                await rm(target, { force: true }).catch(() => { });
+                failed.push({ file: next.file, reason: attempts > 1 ? `${reason} (after ${attempts} tries)` : reason });
+            }
+            else {
+                onFile(next);
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
+    return failed;
+}

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

@@ -0,0 +1,22 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+import type { DeviceFlowBundle } from '../types/domain/device-session.types.js';
+/** The API's limit on a bundle (dcd plan 2.5b). */
+export declare const MAX_BUNDLE_BYTES: number;
+/** Every file under `dir`, relative to it, in a stable order. */
+export declare function bundleFiles(dir: string): string[];
+export interface UploadFlowBundleOptions {
+    apiUrl: string;
+    auth: AuthContext;
+    dir: string;
+    log: (message: string) => void;
+}
+/**
+ * Zip a directory of flows and upload it as a flow bundle: ask the API for
+ * upload URLs, PUT the zip to both copies, then register it with its
+ * SHA-256. Encrypted like `dcd cloud`'s flow zips when the org's default
+ * (or DCD_ENCRYPT) says so. Entries are relative to `dir`, so a run's
+ * `flow` is a path inside it, e.g. `login.yaml`.
+ */
+export declare function uploadFlowBundle(opts: UploadFlowBundleOptions): Promise<DeviceFlowBundle & {
+    files: number;
+}>;

package/dist/utils/device-bundle.js

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { readdirSync } from 'node:fs';
+import * as path from 'node:path';
+import { DeviceGateway } from '../gateways/device-gateway.js';
+import { compressFilesFromRelativePath } from '../methods.js';
+import { detectCiContext } from './ci.js';
+import { CliError, getCliVersion } from './cli.js';
+import { fetchCompatibilityData } from './compatibility.js';
+import { checkKekForEncryption, encryptFlowBuffer, resolveEncryption, resolveKekPublicKey, } from './envelope.js';
+/** The API's limit on a bundle (dcd plan 2.5b). */
+export const MAX_BUNDLE_BYTES = 50 * 1024 * 1024;
+/** Never bundled: version control, dependencies, and other dot-folders. */
+function skipped(relativePath) {
+    return relativePath
+        .split(path.sep)
+        .some((part) => part === 'node_modules' || (part.startsWith('.') && part !== '.'));
+}
+/** Every file under `dir`, relative to it, in a stable order. */
+export function bundleFiles(dir) {
+    return readdirSync(dir, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => path.relative(dir, path.join(entry.parentPath, entry.name)))
+        .filter((file) => !skipped(file))
+        .sort();
+}
+/** PUT the zip to one signed URL. The URL is the credential. */
+async function put(url, body) {
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            const res = await fetch(url, {
+                method: 'PUT',
+                headers: { 'content-type': 'application/zip' },
+                body: new Uint8Array(body),
+            });
+            await res.body?.cancel();
+            if (res.ok)
+                return true;
+            if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+                return false;
+            }
+        }
+        catch {
+            // A network error: try once more.
+        }
+    }
+    return false;
+}
+/**
+ * Zip a directory of flows and upload it as a flow bundle: ask the API for
+ * upload URLs, PUT the zip to both copies, then register it with its
+ * SHA-256. Encrypted like `dcd cloud`'s flow zips when the org's default
+ * (or DCD_ENCRYPT) says so. Entries are relative to `dir`, so a run's
+ * `flow` is a path inside it, e.g. `login.yaml`.
+ */
+export async function uploadFlowBundle(opts) {
+    const { apiUrl, auth, dir, log } = opts;
+    const files = bundleFiles(dir);
+    if (!files.some((f) => /\.ya?ml$/i.test(f))) {
+        throw new CliError(`No flow files (.yaml) in ${dir}.`);
+    }
+    const zip = await compressFilesFromRelativePath(dir, files, '');
+    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 kek = encryption.enabled ? await resolveKekPublicKey(apiUrl) : null;
+    const sealed = kek ? encryptFlowBuffer(zip, kek) : null;
+    const body = sealed ? sealed.ciphertext : zip;
+    if (body.length > MAX_BUNDLE_BYTES) {
+        throw new CliError(`${dir} zips to ${(body.length / 1024 / 1024).toFixed(1)} MB; a bundle can be at most ${MAX_BUNDLE_BYTES / 1024 / 1024} MB.`);
+    }
+    const sha = createHash('sha256').update(body).digest('hex');
+    const urls = await DeviceGateway.bundleUploadUrls(apiUrl, auth, body.length);
+    const [supabase, backblaze] = await Promise.all([
+        urls.upload ? put(urls.upload.signedUrl, body) : Promise.resolve(false),
+        urls.mirror ? put(urls.mirror.signedUrl, body) : Promise.resolve(false),
+    ]);
+    if (!supabase && !backblaze) {
+        throw new Error('The flow bundle could not be uploaded. Please retry.');
+    }
+    const { bundle } = await DeviceGateway.registerBundle(apiUrl, auth, {
+        id: urls.id,
+        sha,
+        bytes: body.length,
+        supabase,
+        backblaze,
+        ...(sealed && { enc: sealed.enc }),
+    });
+    return { ...bundle, files: files.length };
+}

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

@@ -0,0 +1,81 @@
+import type { AuthContext } from '../types/domain/auth.types.js';
+import type { DeviceHumanStatus, DeviceSession } from '../types/domain/device-session.types.js';
+import { type Field } from './ui.js';
+/**
+ * Exit codes for `dcd device` (dcd docs/device-v1-plan.md, section 4.2).
+ * Scripts and agents branch on these, so they are a contract.
+ */
+export declare const DEVICE_EXIT: {
+    readonly ok: 0;
+    /** Called wrongly: a bad flag, a bad value, or no session to pick. */
+    readonly usage: 1;
+    /** It ran and failed: a flow or action failed, or the API could not do it. */
+    readonly failed: 2;
+    /** A limit: concurrency, spend cap or rate limit. */
+    readonly limit: 3;
+    /** The session has ended, or there is no such session. */
+    readonly gone: 4;
+};
+export declare function deviceExitCode(error: unknown): number;
+/**
+ * The one object `--json` prints, on success and on failure alike. `session`
+ * is left out by the commands that are not about one session (`list`,
+ * `models`, `stop --all`), so it never reads as "no session".
+ */
+export interface DeviceEnvelope<T> {
+    ok: boolean;
+    session?: DeviceSession | null;
+    data: T | null;
+    error: {
+        code: null | string;
+        message: string;
+    } | null;
+}
+export interface DeviceOutcome<T> {
+    /** The session the command was about; undefined when it is not about one. */
+    session: DeviceSession | null | undefined;
+    data: T;
+    /** Prints the result for a person. Not called under --json. */
+    print(): void;
+    /**
+     * Set when the command ran but did not succeed (a failed launch, a failed
+     * flow). The CLI then exits 2, still printing `data`.
+     */
+    failure?: {
+        code: null | string;
+        message: string;
+    };
+}
+/**
+ * Runs one `dcd device` command and prints its result: one envelope under
+ * --json, readable text otherwise. Errors leave with the matching exit code.
+ * Under --json the error is printed here, as an envelope, so the top-level
+ * handler's `{ status, error }` never appears.
+ */
+export declare function runDeviceCommand<T>(json: boolean, fn: () => Promise<DeviceOutcome<T>>): Promise<void>;
+/**
+ * Progress for a person, on stderr, so stdout carries only the result. Off
+ * under --json. These are plain lines, never a spinner, so they read the same
+ * in a terminal, a CI log or an agent's tool output.
+ */
+export declare function deviceProgress(json: boolean): (message: string) => void;
+/**
+ * The default-session rule: `<id>` may be left out when the org has exactly
+ * one open session. With none, or several, the command is a usage error and
+ * lists what there is to choose from.
+ */
+export declare function resolveSessionId(apiUrl: string, auth: AuthContext, given: string | undefined): Promise<string>;
+export declare function formatSeconds(seconds: number): string;
+/** The rows that describe a session, for {@link ui.fields}. */
+export declare function sessionFields(session: DeviceSession): Field[];
+/** A session as a branch group, with its warnings after it. */
+export declare function printSession(session: DeviceSession): void;
+/**
+ * An API timestamp for a person: how far off it is and the local time, e.g.
+ * "in 12m (14:32)" or "3m ago (14:17)". The text as given when unreadable.
+ */
+export declare function formatWhen(iso: string, now?: number): string;
+/** Where the hand-over stands, in a few words. */
+export declare function humanState(human: DeviceHumanStatus): string;
+/** The rows that describe a request for a person, for {@link ui.fields}. */
+export declare function humanFields(human: DeviceHumanStatus, now?: number): Field[];

package/dist/utils/device-output.js

@@ -0,0 +1,204 @@
+import { DeviceApiError, DeviceGateway } from '../gateways/device-gateway.js';
+import { CliError, logger } from './cli.js';
+import { colors, formatUrl } from './styling.js';
+import { ui } from './ui.js';
+/**
+ * Exit codes for `dcd device` (dcd docs/device-v1-plan.md, section 4.2).
+ * Scripts and agents branch on these, so they are a contract.
+ */
+export const DEVICE_EXIT = {
+    ok: 0,
+    /** Called wrongly: a bad flag, a bad value, or no session to pick. */
+    usage: 1,
+    /** It ran and failed: a flow or action failed, or the API could not do it. */
+    failed: 2,
+    /** A limit: concurrency, spend cap or rate limit. */
+    limit: 3,
+    /** The session has ended, or there is no such session. */
+    gone: 4,
+};
+const LIMIT_CODES = new Set(['LIVE_CONCURRENCY_LIMIT', 'LIVE_RATE_LIMITED', 'LIVE_SPEND_CAP']);
+const GONE_CODES = new Set(['LIVE_NOT_FOUND', 'LIVE_SESSION_ENDED']);
+const USAGE_CODES = new Set([
+    'LIVE_INVALID_ACTION',
+    'LIVE_INVALID_APP',
+    'LIVE_SESSION_REQUIRED',
+]);
+export function deviceExitCode(error) {
+    if (error instanceof DeviceApiError) {
+        if (error.code && GONE_CODES.has(error.code))
+            return DEVICE_EXIT.gone;
+        if (error.code && LIMIT_CODES.has(error.code))
+            return DEVICE_EXIT.limit;
+        if (error.code && USAGE_CODES.has(error.code))
+            return DEVICE_EXIT.usage;
+        if (error.status === 404)
+            return DEVICE_EXIT.gone;
+        if (error.status === 429)
+            return DEVICE_EXIT.limit;
+        if ([400, 401, 403].includes(error.status))
+            return DEVICE_EXIT.usage;
+        return DEVICE_EXIT.failed;
+    }
+    if (error instanceof CliError)
+        return error.exitCode;
+    return DEVICE_EXIT.failed;
+}
+/**
+ * Runs one `dcd device` command and prints its result: one envelope under
+ * --json, readable text otherwise. Errors leave with the matching exit code.
+ * Under --json the error is printed here, as an envelope, so the top-level
+ * handler's `{ status, error }` never appears.
+ */
+export async function runDeviceCommand(json, fn) {
+    let outcome;
+    try {
+        outcome = await fn();
+    }
+    catch (error) {
+        const exitCode = deviceExitCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        if (!json)
+            throw new CliError(message, exitCode);
+        const envelope = {
+            ok: false,
+            session: error instanceof DeviceApiError ? error.session : null,
+            data: null,
+            error: { code: error instanceof DeviceApiError ? error.code : null, message },
+        };
+        logger.json(envelope);
+        logger.fail(message, exitCode);
+    }
+    if (json) {
+        const envelope = {
+            ok: !outcome.failure,
+            ...(outcome.session !== undefined && { session: outcome.session }),
+            data: outcome.data,
+            error: outcome.failure ?? null,
+        };
+        logger.json(envelope);
+    }
+    else {
+        outcome.print();
+    }
+    if (outcome.failure)
+        logger.fail(outcome.failure.message, DEVICE_EXIT.failed);
+}
+/**
+ * Progress for a person, on stderr, so stdout carries only the result. Off
+ * under --json. These are plain lines, never a spinner, so they read the same
+ * in a terminal, a CI log or an agent's tool output.
+ */
+export function deviceProgress(json) {
+    return (message) => {
+        if (!json)
+            process.stderr.write(`${message}\n`);
+    };
+}
+/**
+ * The default-session rule: `<id>` may be left out when the org has exactly
+ * one open session. With none, or several, the command is a usage error and
+ * lists what there is to choose from.
+ */
+export async function resolveSessionId(apiUrl, auth, given) {
+    const id = given?.trim();
+    if (id)
+        return id;
+    const { sessions } = await DeviceGateway.list(apiUrl, auth);
+    if (sessions.length === 1)
+        return sessions[0].id;
+    if (sessions.length === 0) {
+        throw new CliError('No open device session. Start one with `dcd device start --platform ios|android`.', DEVICE_EXIT.usage);
+    }
+    const candidates = sessions
+        .map((s) => `  ${s.id}  ${s.platform}  ${s.state}${s.client_label ? `  ${s.client_label}` : ''}`)
+        .join('\n');
+    throw new CliError(`${sessions.length} device sessions are open. Name one:\n${candidates}`, DEVICE_EXIT.usage);
+}
+export function formatSeconds(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const rest = seconds % 60;
+    return rest ? `${minutes}m ${rest}s` : `${minutes}m`;
+}
+/** The rows that describe a session, for {@link ui.fields}. */
+export function sessionFields(session) {
+    const fields = [
+        ['session', colors.highlight(session.id)],
+        ['state', session.release_reason ? `${session.state} (${session.release_reason})` : session.state],
+        ['platform', session.platform],
+    ];
+    if (session.model)
+        fields.push(['model', session.model]);
+    if (session.client_label)
+        fields.push(['client', session.client_label]);
+    if (session.queue) {
+        const position = session.queue.position === null ? '' : `#${session.queue.position}`;
+        const eta = session.queue.eta_s === null ? '' : `, about ${formatSeconds(session.queue.eta_s)}`;
+        fields.push(['queue', `${position || 'waiting'}${eta} (${session.queue.reason.replaceAll('_', ' ')})`]);
+    }
+    if (session.time_remaining_s !== null) {
+        fields.push(['time left', formatSeconds(session.time_remaining_s)]);
+    }
+    if (session.idle_remaining_s !== null) {
+        fields.push(['idle timeout', `in ${formatSeconds(session.idle_remaining_s)}`]);
+    }
+    if (session.cost_so_far_usd !== null) {
+        fields.push(['cost so far', `$${session.cost_so_far_usd.toFixed(2)}`]);
+    }
+    if (session.last_crash) {
+        fields.push(['last crash', colors.error(`${session.last_crash.summary} (${session.last_crash.at})`)]);
+    }
+    fields.push(['monitor', formatUrl(session.monitor_url)]);
+    return fields;
+}
+/** A session as a branch group, with its warnings after it. */
+export function printSession(session) {
+    logger.log(ui.branch(ui.fields(sessionFields(session))));
+    for (const warning of session.warnings)
+        logger.log(ui.warn(warning));
+}
+/**
+ * An API timestamp for a person: how far off it is and the local time, e.g.
+ * "in 12m (14:32)" or "3m ago (14:17)". The text as given when unreadable.
+ */
+export function formatWhen(iso, now = Date.now()) {
+    const at = Date.parse(iso);
+    if (!Number.isFinite(at))
+        return iso;
+    const clock = new Date(at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+    const seconds = Math.round((at - now) / 1000);
+    if (Math.abs(seconds) < 5)
+        return `now (${clock})`;
+    return seconds > 0
+        ? `in ${formatSeconds(seconds)} (${clock})`
+        : `${formatSeconds(-seconds)} ago (${clock})`;
+}
+/** Where the hand-over stands, in a few words. */
+export function humanState(human) {
+    if (human.human_in_control)
+        return 'a person has control';
+    if (human.waiting)
+        return 'waiting for a person';
+    if (human.handed_back)
+        return 'handed back';
+    return 'no help asked for';
+}
+/** The rows that describe a request for a person, for {@link ui.fields}. */
+export function humanFields(human, now = Date.now()) {
+    const fields = [['state', humanState(human)]];
+    if (human.reason)
+        fields.push(['reason', human.reason]);
+    if (human.since)
+        fields.push(['asked', formatWhen(human.since, now)]);
+    if (human.waiting && human.expires_at) {
+        fields.push(['ends', `${formatWhen(human.expires_at, now)} unless they hand it back`]);
+    }
+    if (human.handed_back && human.handed_back_at) {
+        fields.push(['handed back', formatWhen(human.handed_back_at, now)]);
+    }
+    if (human.handed_back)
+        fields.push(['note', human.note ?? colors.dim('none')]);
+    return fields;
+}

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

@@ -0,0 +1,29 @@
+import type { DeviceCommandResult, DeviceFlowResult } from '../types/domain/device-session.types.js';
+/**
+ * What `dcd device run` shows a person: one row per flow and a short summary.
+ *
+ * The API passes on the runner's report as text in `result.output` (a pass)
+ * or `result.error` (a failure). For a directory that report is Maestro's
+ * JSON: `{ success, device_id, total_flows, total_commands_executed,
+ * results: [{ file, success, error, message }], env_vars, message }`. For one
+ * flow it is the same without `results`. Newer APIs also send
+ * `result.flows`, which is used when present. None of the runner's own
+ * fields (device_id, command counts, env_vars) are shown.
+ */
+export interface RunReport {
+    flows: DeviceFlowResult[];
+    /** The runner's one-line summary, e.g. "Some flows failed to execute". */
+    message: null | string;
+}
+/**
+ * The flows a run reported, or null when the result carries no report the
+ * CLI can read (plain text): then the text is shown as it came.
+ */
+export declare function parseRunReport(result: DeviceCommandResult): null | RunReport;
+/** The failure message for a failed run: each failing flow and why. */
+export declare function runFailureMessage(result: DeviceCommandResult, report: null | RunReport): string;
+/**
+ * Print a run's result for a person. `label` names a flow the report does not
+ * (a single flow's report has no file name).
+ */
+export declare function printRunResult(log: (line: string) => void, passed: boolean, result: DeviceCommandResult, label: string): void;