@roku-sdk/device-test-client 0.0.0-stage → 2.18.0

package/src/client/factory.ts

@@ -0,0 +1,147 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `createDefaultClient` — env-driven `RkClient` factory.
+ *
+ * Extracted from `client.ts` so the file containing the `RkClient`
+ * class stays focused on ECP + log/screenshot/DOM orchestration.
+ * `client.ts` re-exports `createDefaultClient` for public-API
+ * compatibility.
+ *
+ * Sync on purpose — see `device-resolver.ts` doc comment for the
+ * full rationale. The resolver consults, in order:
+ *   1. `RK_DEVICE_IP` env var, then
+ *   2. `<testResultsDir>/.device-ip` written by `globalSetup`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { ARTIFACT_FILE, DEFAULT_KEY_DELAY, ENV_VAR } from "../constants";
+import { resolveDeviceIpSync } from "../device/device-resolver-sync";
+import { defaultTestResultsDir } from "../paths";
+import type { DeviceInfo, RkClientOptions } from "../types";
+import { RkClient } from "./client";
+
+/**
+ * Constructs an `RkClient` configured from process env. Single source of
+ * truth for client construction; used by both `setup.ts` (worker-side)
+ * and `global-setup.ts` (host-side).
+ */
+export function createDefaultClient(opts: RkClientOptions = {}): RkClient {
+    const resultsDir = defaultTestResultsDir();
+    const deviceIp = opts.deviceIp ?? resolveDeviceIpSync(resultsDir);
+    const client = new RkClient({
+        ...opts,
+        deviceIp,
+        keyDelay: opts.keyDelay ?? envKeyDelay()
+    });
+
+    // If globalSetup already wrote a device-env.json snapshot, seed
+    // the worker-side cache from it so tests can call
+    // `client.cachedDeviceInfo()` without a second ECP round-trip.
+    //
+    // Schema-validate before seeding: a corrupted snapshot (truncated
+    // write, hand-edited junk, half-overwritten file) used to be cast
+    // to `DeviceInfo` and silently used to drive baseline selection
+    // (`hd` vs `fhd`) and precondition gating (`firmwareVersion`,
+    // `deviceClass`). The corrupted values then produced wrong
+    // baselines / wrong skip decisions WITHOUT a single warning,
+    // which is exactly the failure mode this gate is supposed to
+    // prevent.
+    //
+    // Failure modes are now distinguished:
+    //   - file unreadable / not JSON          → warn + skip seeding
+    //   - JSON parses but shape is wrong      → warn + skip seeding
+    //   - JSON parses and matches `DeviceInfo`→ seed (happy path)
+    // In every case the explicit `queryDeviceInfo()` call still
+    // works, so we degrade to a slower-but-correct path rather than
+    // failing closed.
+    const envFile = join(resultsDir, ARTIFACT_FILE.DEVICE_ENV);
+    if (existsSync(envFile)) {
+        try {
+            const raw = readFileSync(envFile, "utf8");
+            const parsed = JSON.parse(raw);
+            const validation = validateDeviceInfo(parsed);
+            if (validation.ok) {
+                client.seedDeviceInfo(validation.value);
+            } else {
+                console.warn(
+                    `[device-test-client] Ignoring corrupted device-env snapshot at "${envFile}": ` +
+                        `${validation.reason}. Falling back to live queryDeviceInfo() — baseline ` +
+                        `selection and preconditions will work but a stale/junk snapshot won't ` +
+                        `silently mislead them.`
+                );
+            }
+        } catch (err) {
+            console.warn(
+                `[device-test-client] Failed to read device-env snapshot at "${envFile}": ` +
+                    `${(err as Error).message}. Cache left empty.`
+            );
+        }
+    }
+
+    return client;
+}
+
+function envKeyDelay(): number {
+    const raw = process.env[ENV_VAR.KEY_DELAY];
+    const n = Number(raw);
+    return raw && Number.isFinite(n) && n > 0 ? n : DEFAULT_KEY_DELAY;
+}
+
+type ValidationResult<T> = { ok: true; value: T } | { ok: false; reason: string };
+
+/**
+ * Narrow-checks a value against `DeviceInfo`. Hand-rolled (no zod)
+ * because this is the only place we validate this shape and the
+ * cost of an extra runtime dep is not worth it. Returns the typed
+ * value on success and a human-readable reason on failure so the
+ * warn-log is actionable.
+ *
+ * Required: every string field of `DeviceInfo` must be a non-empty
+ * string, and `libraries` must be a string→string record.
+ *
+ * Exported with an underscore-prefix because it's intentionally
+ * tested in isolation — callers should go through
+ * `createDefaultClient` which decides what to do on validation
+ * failure (currently: warn + skip seeding).
+ */
+export function __validateDeviceInfoForTesting(value: unknown): ValidationResult<DeviceInfo> {
+    return validateDeviceInfo(value);
+}
+
+function validateDeviceInfo(value: unknown): ValidationResult<DeviceInfo> {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {
+            ok: false,
+            reason: `expected an object, got ${value === null ? "null" : Array.isArray(value) ? "array" : typeof value}`
+        };
+    }
+    const v = value as Record<string, unknown>;
+    const stringFields: ReadonlyArray<keyof DeviceInfo> = [
+        "modelName",
+        "modelNumber",
+        "modelFamily",
+        "deviceClass",
+        "firmwareVersion",
+        "videoMode",
+        "locale",
+        "country"
+    ];
+    for (const field of stringFields) {
+        const fv = v[field as string];
+        if (typeof fv !== "string" || fv.length === 0) {
+            return { ok: false, reason: `field "${String(field)}" must be a non-empty string (got ${typeof fv})` };
+        }
+    }
+    if (typeof v.libraries !== "object" || v.libraries === null || Array.isArray(v.libraries)) {
+        return { ok: false, reason: `field "libraries" must be a string→string object` };
+    }
+    for (const [k, libVal] of Object.entries(v.libraries as Record<string, unknown>)) {
+        if (typeof libVal !== "string") {
+            return { ok: false, reason: `libraries["${k}"] must be a string (got ${typeof libVal})` };
+        }
+    }
+    return { ok: true, value: v as unknown as DeviceInfo };
+}

package/src/client/health.ts

@@ -0,0 +1,214 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Per-process device-health flags. Tests that detect a system
+ * dialog, crash, or unrecoverable condition flip them so subsequent
+ * tests cascade-abort in `beforeEach`.
+ *
+ * Two distinct flags, intentionally separate:
+ *
+ *   1. SOFT health (`deviceHealthy`) — flipped by `markDeviceUnhealthy`,
+ *      cleared by `resetDeviceHealth`. Models a *recoverable* fault:
+ *      a crash/reboot the device can come back from. The deploy-guard
+ *      retry loop and `installDeviceTestHooks`' recovery `beforeEach`
+ *      both clear it after a successful liveness probe.
+ *
+ *   2. FATAL latch (`deviceFatal`) — flipped by `markDeviceFatal`,
+ *      NEVER cleared in production (only the test-only reset clears it).
+ *      Models an *unrecoverable-on-this-VM* fault: the device answers
+ *      ECP and the sideload installer, but it refuses to foreground a
+ *      freshly-sideloaded dev channel ("never left home screen"). No
+ *      amount of `waitForDeviceFullyReady` / reboot-wait can cure that
+ *      from inside the test process — the device host has to be
+ *      recycled. Retrying on the wedged VM only burns the per-attempt
+ *      budget × every remaining suite (the ~20-minute waste this latch
+ *      exists to eliminate).
+ *
+ *      Recycling is the CELL's job, not this process's. When
+ *      `RK_DEVICE_FATAL_SENTINEL` names a path, `markDeviceFatal` drops
+ *      a one-line JSON marker there the instant the latch flips. The CI
+ *      cell script reads it AFTER Jest exits to tell an unrecoverable
+ *      VM wedge (release the lease, re-acquire a fresh instance, retry
+ *      once) apart from an ordinary test failure (propagate). The
+ *      marker is opt-in via env so unit tests and local runs never
+ *      touch the filesystem, and it lives OUTSIDE `test-results/`
+ *      (which Jest's globalSetup wipes per run).
+ *
+ * Critically, `resetDeviceHealth()` clears ONLY the soft flag. The
+ * fatal latch deliberately survives it: the deploy-guard resets soft
+ * health between attempts, and if that also cleared the fatal latch
+ * the loop would keep retrying a VM that can never launch.
+ *
+ * Load-bearing: single-process execution (Jest `--runInBand`).
+ *
+ * CROSS-FILE LATCH. Jest sandboxes every test FILE in its own module
+ * registry — even under `--runInBand` (which only means "one worker,
+ * serial", NOT "shared module state"). So the in-memory `deviceFatal`
+ * singleton below RESETS to `false` at the start of every test file.
+ * Within a file the latch cascades fine; across files it would not,
+ * and each fresh file would re-pay the full deploy + recovery budget
+ * (~60s) rediscovering a wedge an earlier file already proved — the
+ * shard-wide, ~hour-long waste this module exists to eliminate.
+ *
+ * The ON-DISK sentinel (`RK_DEVICE_FATAL_SENTINEL`) is the only state
+ * that survives a module-registry reset, so it — not the in-memory
+ * flag — is the source of truth for the cross-file cascade.
+ * `markDeviceFatal` writes it on the first latch and `isDeviceFatal()`
+ * rehydrates the in-memory latch from it, so the first deploy in every
+ * subsequent file short-circuits in `beforeAll` instead of deploying.
+ * The CI cell still reads the same sentinel AFTER Jest exits to decide
+ * whether to recycle the lease.
+ *
+ * The only sanctioned mid-run reset is the `deviceRecovery` hook in
+ * `installDeviceTestHooks`, and it refuses to recover once the fatal
+ * latch is set. Forked workers would silently bypass the cascade.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+let deviceHealthy = true;
+let unhealthyReason: string | null = null;
+let deviceFatal = false;
+let fatalReason: string | null = null;
+
+export function isDeviceHealthy(): boolean {
+    return deviceHealthy;
+}
+
+/**
+ * Flip the soft health flag, remembering the FIRST reason as root
+ * cause so cascade-detection messages don't obscure it.
+ */
+export function markDeviceUnhealthy(reason: string): void {
+    if (!deviceHealthy) return;
+    deviceHealthy = false;
+    unhealthyReason = reason;
+    console.warn(`[device-test-client] device marked unhealthy: ${reason}`);
+}
+
+/** Last reason that flipped the soft health flag, or `null` if still healthy. */
+export function getUnhealthyReason(): string | null {
+    return unhealthyReason;
+}
+
+/**
+ * Latch the device as FATALLY wedged: reachable on the network but
+ * structurally unable to foreground a sideloaded channel on this VM.
+ * Idempotent (first reason wins, single warn) like `markDeviceUnhealthy`.
+ *
+ * Also flips the soft health flag so the existing `beforeEach` cascade
+ * and `getUnhealthyReason()` consumers keep working unchanged — callers
+ * never need to call both. `resetDeviceHealth()` clears the soft flag
+ * but NOT this latch, so once a VM is declared wedged every subsequent
+ * deploy/recovery short-circuits instead of re-probing a dead instance.
+ */
+export function markDeviceFatal(reason: string): void {
+    // Flip soft health first (idempotent; preserves an earlier soft
+    // reason as root cause) so the cascade keeps firing even if a
+    // softer fault was recorded before the fatal diagnosis.
+    markDeviceUnhealthy(reason);
+    if (deviceFatal) return;
+    deviceFatal = true;
+    fatalReason = reason;
+    // Drop the recycle marker exactly once, on the first latch, so the
+    // CI cell can re-acquire a fresh instance and retry (see doc-block).
+    writeFatalSentinel(reason);
+    console.warn(
+        `[device-test-client] device marked FATAL (unrecoverable on this VM): ${reason}. ` +
+            `The device answers ECP/installer probes but will not foreground a sideloaded ` +
+            `channel — recovery cannot cure this. The device host must be recycled; ` +
+            `remaining suites will skip their deploys instead of retrying.`
+    );
+}
+
+/**
+ * Best-effort recycle marker for the CI cell. When
+ * `RK_DEVICE_FATAL_SENTINEL` names a path, write a one-line JSON marker
+ * the instant the fatal latch flips; the cell script reads it after
+ * Jest exits to decide whether to release + re-acquire a fresh instance
+ * and retry. Deliberately NOT exported — production code outside this
+ * module has no reason to forge a recycle signal.
+ *
+ * Opt-in via env so unit tests and local runs never touch the
+ * filesystem. A write failure is swallowed on purpose: the cascade
+ * `console.warn` and the thrown `DeviceUnhealthyError` already carry the
+ * reason, so a missing marker degrades to today's fail-fast behaviour
+ * rather than masking the underlying fatal.
+ */
+function writeFatalSentinel(reason: string): void {
+    const sentinelPath = process.env.RK_DEVICE_FATAL_SENTINEL;
+    if (!sentinelPath) return;
+    try {
+        writeFileSync(sentinelPath, `${JSON.stringify({ reason, ts: new Date().toISOString() })}\n`, "utf8");
+    } catch {
+        // best-effort — see doc-block.
+    }
+}
+
+/**
+ * Rehydrate the in-memory fatal latch from the on-disk sentinel.
+ *
+ * Jest gives every test FILE a fresh module registry, so an earlier
+ * file's `markDeviceFatal` does NOT survive in `deviceFatal` here — only
+ * the sentinel it wrote to disk does. Reading it back is what makes the
+ * fatal latch a true CROSS-FILE cascade: the first deploy in every
+ * subsequent file sees `isDeviceFatal()` and short-circuits instead of
+ * paying the ~60s deploy + recovery budget to rediscover the same wedge.
+ *
+ * Once latched in-memory we never re-read (cheap, and the flag never
+ * un-sets within a process). A negative result is re-checked on each
+ * call because the sentinel can appear partway through the run.
+ * Existence is the signal; a malformed/unreadable file still latches
+ * with a fallback reason rather than letting the cascade leak.
+ */
+function hydrateFatalFromSentinel(): void {
+    if (deviceFatal) return;
+    const sentinelPath = process.env.RK_DEVICE_FATAL_SENTINEL;
+    if (!sentinelPath || !existsSync(sentinelPath)) return;
+    deviceFatal = true;
+    try {
+        const parsed = JSON.parse(readFileSync(sentinelPath, "utf8")) as { reason?: unknown };
+        fatalReason =
+            typeof parsed.reason === "string" && parsed.reason.length > 0
+                ? parsed.reason
+                : "device fatally wedged in a prior test file (see RK_DEVICE_FATAL_SENTINEL)";
+    } catch {
+        fatalReason = "device fatally wedged in a prior test file (see RK_DEVICE_FATAL_SENTINEL)";
+    }
+}
+
+/** `true` once the device has been latched as fatally wedged (this process or a prior test file). */
+export function isDeviceFatal(): boolean {
+    hydrateFatalFromSentinel();
+    return deviceFatal;
+}
+
+/** Reason the device was latched fatal, or `null` if not fatal. */
+export function getFatalReason(): string | null {
+    hydrateFatalFromSentinel();
+    return fatalReason;
+}
+
+/**
+ * Clear the SOFT health flag only. The fatal latch deliberately
+ * survives — see the module doc-block. The deploy-guard and recovery
+ * `beforeEach` call this between attempts; clearing the fatal latch
+ * here would defeat the whole fail-fast contract.
+ */
+export function resetDeviceHealth(): void {
+    deviceHealthy = true;
+    unhealthyReason = null;
+}
+
+/**
+ * Test-only: clear BOTH the soft flag and the fatal latch so unit
+ * tests don't leak the process-lifetime fatal state across cases.
+ * NOT exported via `index.ts` — production code has no legitimate
+ * reason to un-wedge a device mid-run.
+ */
+export function __resetDeviceHealthForTests(): void {
+    deviceHealthy = true;
+    unhealthyReason = null;
+    deviceFatal = false;
+    fatalReason = null;
+}

package/src/client/parsers.ts

@@ -0,0 +1,155 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Pure parsing helpers for ECP XML responses. Extracted from
+ * `client.ts` so they can be unit-tested without an `RkClient`.
+ * No network, no fs, no module state.
+ */
+
+import type { ActiveAppInfo, AppUiNode, DeviceInfo } from "../types";
+
+/**
+ * Tuple tree produced by `xmlToJson`. Tooling types children as
+ * `unknown[]`; we narrow at each recursion step.
+ */
+export type NodeTuple = [string, Record<string, string>, Array<NodeTuple | string>];
+
+/** Runtime cast of the `xmlToJson` return into our strict `NodeTuple` shape. */
+export function asNodeTuple(
+    raw: [string, Record<string, string>, Array<[string, Record<string, string>, unknown[]] | string>] | null
+): NodeTuple | null {
+    return raw as NodeTuple | null;
+}
+
+export function tupleToAppUiNode(tuple: NodeTuple): AppUiNode {
+    const [tag, attrs, rawChildren] = tuple;
+    const children: AppUiNode[] = [];
+    for (const child of rawChildren) {
+        // Skip text nodes (whitespace or stray label literals).
+        if (typeof child !== "string") children.push(tupleToAppUiNode(child));
+    }
+    // ECP serializes SceneGraph `id` as XML `name=`; mirror it back
+    // to `id` so JSX-style selectors work. Raw `attrs.name` still
+    // available for callers that want it.
+    const normalizedAttrs = { ...attrs };
+    if (normalizedAttrs.id === undefined && normalizedAttrs.name !== undefined) {
+        normalizedAttrs.id = normalizedAttrs.name;
+    }
+    return {
+        tag,
+        attrs: normalizedAttrs,
+        bounds: parseBounds(attrs.bounds),
+        focused: attrs.focused === "true",
+        children
+    };
+}
+
+/**
+ * Parse a SceneGraph bounds string `"{x, y, w, h}"`. Returns a
+ * zero rect on parse failure so callers don't branch on `null`.
+ */
+export function parseBounds(raw: string | undefined): AppUiNode["bounds"] {
+    const zero = { x: 0, y: 0, width: 0, height: 0 };
+    if (!raw) return zero;
+    const match = /\{\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*,\s*(-?\d+)\s*\}/.exec(raw);
+    if (!match) return zero;
+    return {
+        x: Number(match[1]),
+        y: Number(match[2]),
+        width: Number(match[3]),
+        height: Number(match[4])
+    };
+}
+
+/**
+ * Map ECP `/query/device-info` to the `DeviceInfo` contract.
+ * - `modelName`: `model-name` then `friendly-model-name`.
+ * - `modelFamily`: `vendor-name` + `model-name` (ECP has no
+ *   explicit family field).
+ * - `deviceClass`: `is-tv`/`is-stick` boolean flags → `tv|stick|player`.
+ * - `videoMode`: `video-mode` then `ui-resolution` (Streaming
+ *   Stick 4K firmware 15.x lacks `video-mode`).
+ * - `libraries`: every `*-version` key not in `CORE_VERSION_FIELDS`.
+ */
+export function parseDeviceInfo(raw: Record<string, string>): DeviceInfo {
+    const modelName = raw["model-name"] ?? raw["friendly-model-name"] ?? "";
+    const vendor = raw["vendor-name"] ?? "";
+    const modelFamily = vendor && modelName ? `${vendor} ${modelName}` : modelName || vendor;
+
+    let deviceClass: string;
+    if (raw["is-tv"] === "true") deviceClass = "tv";
+    else if (raw["is-stick"] === "true") deviceClass = "stick";
+    else deviceClass = "player";
+
+    return {
+        modelName,
+        modelNumber: raw["model-number"] ?? "",
+        modelFamily,
+        deviceClass,
+        firmwareVersion: raw["software-version"] ?? "",
+        videoMode: raw["video-mode"] ?? raw["ui-resolution"] ?? "",
+        locale: raw["locale"] ?? "",
+        country: raw["user-country"] ?? raw["country"] ?? "",
+        libraries: extractLibraries(raw)
+    };
+}
+
+const CORE_VERSION_FIELDS = new Set([
+    "software-version",
+    "software-build",
+    "build-version",
+    "udn-version",
+    "channel-version"
+]);
+
+function extractLibraries(raw: Record<string, string>): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!key.endsWith("-version")) continue;
+        if (CORE_VERSION_FIELDS.has(key)) continue;
+        const name = key.slice(0, -"-version".length);
+        if (name.length === 0) continue;
+        out[name] = value;
+    }
+    return out;
+}
+
+export function parseActiveApp(root: NodeTuple): ActiveAppInfo {
+    const [, , children] = root;
+    for (const child of children) {
+        if (typeof child === "string") continue;
+        const [tag, attrs, inner] = child;
+        if (tag !== "app") continue;
+        let title = "";
+        for (const ic of inner) {
+            if (typeof ic === "string") {
+                title = ic.trim();
+                break;
+            }
+        }
+        return {
+            id: attrs.id ?? "",
+            title,
+            type: attrs.type ?? "",
+            uiLocation: attrs["ui-location"] ?? ""
+        };
+    }
+    return { id: "", title: "", type: "", uiLocation: "" };
+}
+
+/**
+ * True when the active app is a home surface rather than a channel.
+ *
+ * Firmware ships several. The classic home screen reports `<app>Roku</app>`
+ * with no attributes at all. native_tv builds instead report real apps:
+ * `native-ui` (`type="appl"`) while the transition settles, then Roku
+ * Dynamic Menu (`id="562859"`, `type="home"`). `ui-location` is what
+ * separates any of them from a channel, because a foregrounded channel
+ * reports its own id there and never `"home"`.
+ *
+ * The `id`/`title` arms are kept for firmware that omits both `type` and
+ * `ui-location`.
+ */
+export function isHomeScreenActiveApp(active: ActiveAppInfo): boolean {
+    return active.type === "home" || active.uiLocation === "home" || active.id === "" || active.title === "Roku";
+}

package/src/client/server-url.ts

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * `resolveServerUrl` — single source of truth for where the
+ * `rk server` daemon lives, shared between `RkClient` construction
+ * and `globalSetup`/`globalTeardown`.
+ *
+ * Why a dedicated module instead of an inline helper? Jest's
+ * `globalTeardown` runs in a separate module graph from the worker
+ * processes that construct `RkClient`, so we need a tree-shake-safe
+ * import path that does not pull in the full `client.ts` surface
+ * (with its `pngjs`, `@roku-sdk/tooling/*` deps) into the teardown
+ * lifecycle. Isolating this helper keeps teardown lean and makes the
+ * resolution order easy to audit in one place.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. `opts.serverUrl` — explicit override.
+ *   2. `process.env[RK_SERVER_URL]` — per-process env var.
+ *   3. `.roku/rk-server.json#apiEndpoint` — discovery file the
+ *      `rk server` CLI writes on startup. The port is derived from a
+ *      sha256 of the workspace path (see
+ *      `@roku-sdk/tooling` `server/port-derivation.ts`), so the
+ *      default `:3737` is almost never the right answer for a real
+ *      developer box. Reading this file lets the fixture's log pillar
+ *      "just work" after the user starts `rk server` — no manual
+ *      `RK_SERVER_URL=…` export required.
+ *   4. `DEFAULT_RK_SERVER_URL` — compiled-in fallback.
+ *
+ * Discovery is intentionally best-effort: a torn read during a
+ * server restart, a missing file, or a malformed JSON payload all
+ * fall through silently to the next resolution tier.
+ *
+ * Output normalization. Whatever tier wins, the returned URL is
+ * normalized to end with `/api` (no trailing slash). All consumers
+ * (`LogSession.postStart`, `LogStreamClient`, `globalSetup`'s
+ * `resetAndStartLogSession`, `RkClient.getLogStreamHealth`) build
+ * request URLs by appending `/logs/...` to this base, and every
+ * route on the server is mounted under `/api/...`
+ * (`tooling/src/server/index.ts:387: app.use("/api/logs", logRoutes)`).
+ * The discovery file already emits the canonical `http://host:port/api`
+ * shape (`coordination.ts::createPortFileData`); the env var path
+ * historically allowed a bare `http://host:port` and silently 404'd.
+ * Normalizing here makes both tiers indistinguishable to consumers
+ * and means a developer can set `RK_SERVER_URL` without remembering
+ * the `/api` suffix.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+
+import { DEFAULT_RK_SERVER_URL, ENV_VAR } from "../constants";
+
+export interface ResolveServerUrlOptions {
+    /** Explicit override (e.g. from `RkClientOptions.serverUrl`). */
+    serverUrl?: string;
+    /**
+     * Directory to start the `.roku/rk-server.json` walk from. Defaults
+     * to `process.cwd()`; tests inject a synthetic start dir so they
+     * don't depend on the actual filesystem layout.
+     */
+    startDir?: string;
+}
+
+export function resolveServerUrl(opts: ResolveServerUrlOptions = {}): string {
+    return normalizeServerUrl(resolveRawServerUrl(opts));
+}
+
+function resolveRawServerUrl(opts: ResolveServerUrlOptions): string {
+    if (opts.serverUrl) return opts.serverUrl;
+    const envUrl = process.env[ENV_VAR.RK_SERVER_URL];
+    if (envUrl) return envUrl;
+    const discovered = readRkServerDiscovery(opts.startDir ?? process.cwd());
+    if (discovered) return discovered;
+    return DEFAULT_RK_SERVER_URL;
+}
+
+/**
+ * Coerce any of the historical accepted shapes —
+ * `http://host:port`, `http://host:port/`, `http://host:port/api`,
+ * `http://host:port/api/` — into the canonical
+ * `http://host:port/api` (no trailing slash). Idempotent. Exported
+ * for unit tests; production callers should always go through
+ * `resolveServerUrl`.
+ */
+export function normalizeServerUrl(url: string): string {
+    const trimmed = url.endsWith("/") ? url.slice(0, -1) : url;
+    return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+}
+
+/**
+ * Best-effort read of `.roku/rk-server.json#apiEndpoint` by walking
+ * up from `startDir` and looking for the file directly. Returns
+ * `null` on any failure.
+ *
+ * We look for the FILE (`.roku/rk-server.json`) rather than its
+ * containing directory (`.roku/`) because per-suite scaffolding
+ * often creates a local placeholder `.roku/` (e.g. `device-tests/
+ * .roku/` is a gitkept empty dir). Anchoring on the file — which is
+ * only written by `rk server` — sidesteps those false positives.
+ *
+ * Exported for unit tests — production code should go through
+ * `resolveServerUrl`.
+ */
+export function readRkServerDiscovery(startDir: string): string | null {
+    const file = findRkServerConfigFile(startDir);
+    if (!file) return null;
+    try {
+        const raw = readFileSync(file, "utf8");
+        const parsed = JSON.parse(raw) as { apiEndpoint?: unknown };
+        if (typeof parsed.apiEndpoint === "string" && parsed.apiEndpoint) {
+            return parsed.apiEndpoint;
+        }
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Walk up from `startDir` looking for a `.roku/rk-server.json` file.
+ * Returns the absolute path to the first match, or `null` if we
+ * reach `/` first without finding one. The walk stops only at the
+ * filesystem root — we do NOT treat `.git` / `pnpm-workspace.yaml`
+ * as fences, because `rk server` typically runs at the outermost
+ * monorepo root while tests run from a package-level cwd several
+ * levels below, and we want them to find the outer config.
+ */
+function findRkServerConfigFile(startDir: string): string | null {
+    let dir = resolvePath(startDir);
+    for (;;) {
+        const candidate = join(dir, ".roku", "rk-server.json");
+        if (existsSync(candidate)) return candidate;
+        const parent = resolvePath(dir, "..");
+        if (parent === dir) return null;
+        dir = parent;
+    }
+}