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

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,10 @@
+/**
+ * Open `url` in the default browser. False if it isn't an http(s) URL or no
+ * opener could be started.
+ *
+ * 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): boolean;

package/dist/utils/browser.js

@@ -0,0 +1,35 @@
+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.
+ *
+ * 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 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] };
+    try {
+        const child = spawn(cmd.bin, cmd.args, { detached: true, stdio: 'ignore' });
+        child.unref();
+        return true;
+    }
+    catch {
+        return 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;
+}[]>;

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;
+}