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

package/src/device/device-resolver.ts

@@ -0,0 +1,141 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Async device IP resolution. Split from the sync resolver so
+ * `createDefaultClient` never transitively loads
+ * `@roku-sdk/tooling`'s ESM `devices-store` (top-level
+ * `import.meta.url`) under CommonJS consumers like ts-jest.
+ *
+ * Flow: `globalSetup` calls `resolveActiveDeviceIp()` and persists
+ * via `persistDeviceIp`; worker processes read the persisted IP
+ * synchronously through `device-resolver-sync.ts`.
+ *
+ * Resolution precedence (later wins on conflict):
+ *   0. (Layer 0) `RK_DEVICE_LEASE_ID` — read the lease file
+ *      `.roku/leases/<id>.json` and use its `ip`. This is the
+ *      canonical CI path for provider-backed pools; the provider writes the
+ *      lease at acquire-time and pins the consumer at boot.
+ *   1. `RK_DEVICE_IP` — partner-side override. Still WINS on
+ *      conflict so existing partner pipelines that pin an IP
+ *      keep working byte-for-byte after this file lands.
+ *   2. `.roku/` active device → first registered device.
+ *
+ * IMPORTANT: `RK_DEVICE_IP` deliberately wins over a lease file.
+ * Rationale:
+ *   - Partner pipelines have set `RK_DEVICE_IP` for years; flipping
+ *     precedence would silently break them when an unrelated lease
+ *     file from a prior interactive `rk device lease acquire` is
+ *     still on disk.
+ *   - The internal CI path always sets `RK_DEVICE_LEASE_ID` AND
+ *     leaves `RK_DEVICE_IP` unset, so the lease-file path "wins"
+ *     in practice without any precedence ambiguity.
+ */
+
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+
+import { leaseFilePath, readLeaseFile } from "@roku-sdk/tooling/src/device-pool/lease-writer";
+import { loadListMergedDevices } from "@roku-sdk/tooling/src/device-test-helpers";
+
+import { DEVICE_IP_CACHE_FILE, ENV_VAR } from "../constants";
+import { RkClientError } from "../errors";
+
+// `loadListMergedDevices` lives on the tooling side (in
+// `@roku-sdk/tooling/device-test-helpers`) so the deep-require path
+// is owned by the package whose internals it references. Static
+// import of `devices-store` would pull in `get-config.ts` (top-level
+// `import.meta.url`) which is illegal under our CommonJS tsconfig;
+// the helper defers resolution to runtime via `require()`.
+
+export { resolveDeviceIpSync } from "./device-resolver-sync";
+
+/**
+ * Layer 0 lookup: read the lease file the device-pool provider wrote
+ * for this job and return its `ip` if usable.
+ *
+ * Returns `undefined` (not throws) on every recoverable miss — env
+ * unset, lease dir missing, file corrupt — so a higher precedence
+ * layer (`RK_DEVICE_IP`) or a lower one (`.roku/` active) can still
+ * resolve a valid IP. The one fatal case is "env says use lease X
+ * but no other layer has an IP either"; that surfaces at the bottom
+ * of `resolveActiveDeviceIp` as the existing `RK_DEVICE_IP_UNRESOLVED`
+ * error, which already has the actionable remediation steps.
+ *
+ * We deliberately do NOT mutate `.roku/roku-dev-config.json` or
+ * `rk-server` state — the lease file is the single source of truth,
+ * and `rk-server` (when started in a job with `RK_DEVICE_LEASE_ID`
+ * set) reads through the same file directly. This is what makes the
+ * parallel-CI model safe: workspace-singleton state cannot race.
+ */
+async function resolveFromLeaseFile(cwd: string): Promise<string | undefined> {
+    const leaseId = process.env[ENV_VAR.RK_DEVICE_LEASE_ID];
+    if (!leaseId || leaseId.length === 0) return undefined;
+    const leaseDir = process.env[ENV_VAR.RK_DEVICE_LEASE_DIR] ?? join(cwd, ".roku", "leases");
+    try {
+        const lease = await readLeaseFile(leaseId, leaseDir);
+        if (typeof lease.ip === "string" && lease.ip.length > 0) {
+            return lease.ip;
+        }
+        return undefined;
+    } catch {
+        // `readLeaseFile` throws `DevicePoolError(INVALID_LEASE_FILE)`
+        // on ENOENT / malformed JSON / schema mismatch. We treat that
+        // as "Layer 0 didn't resolve" and let the higher / lower
+        // layers continue. A truly broken lease file is logged louder
+        // by the CLI verbs that wrote it (acquire/reap); the resolver
+        // is not the right place to surface that.
+        return undefined;
+    }
+}
+
+/**
+ * Resolve the device IP. See file-level doc-block for the precedence
+ * order. Throws `RkClientError(RK_DEVICE_IP_UNRESOLVED)` with an
+ * actionable message when no layer yields an IP.
+ */
+export async function resolveActiveDeviceIp(cwd: string = process.cwd()): Promise<string> {
+    const envIp = process.env[ENV_VAR.RK_DEVICE_IP];
+    if (envIp && envIp.length > 0) return envIp;
+
+    const leaseIp = await resolveFromLeaseFile(cwd);
+    if (leaseIp) return leaseIp;
+
+    const listMergedDevices = loadListMergedDevices();
+    const { devices, activeId, activeRceId } = await listMergedDevices(cwd);
+    if (activeRceId) {
+        throw new RkClientError(
+            `The active device ${activeRceId} is a Roku Cloud Emulator device; device tests run on LAN devices only. ` +
+                `Set ${ENV_VAR.RK_DEVICE_IP}=<ip> or run \`rk device set-active <lan-device>\`.`,
+            "DEVICE_KIND_UNSUPPORTED"
+        );
+    }
+    if (activeId) {
+        const active = devices.find(d => d.id === activeId);
+        if (active?.ip) return active.ip;
+    }
+
+    if (devices.length > 0 && devices[0]?.ip) return devices[0].ip;
+
+    throw new RkClientError(
+        `Unable to resolve a Roku device IP. Set ${ENV_VAR.RK_DEVICE_IP}=<ip>, ` +
+            `set ${ENV_VAR.RK_DEVICE_LEASE_ID}=<leaseId> after \`rk device lease acquire --target <ipv4>\` ` +
+            `(no \`rk device add\` required for raw IPs), or run \`rk device add <ip>\` in the workspace, ` +
+            `then re-run the suite. IPv6 and hostnames are not supported by the local pool.`,
+        "RK_DEVICE_IP_UNRESOLVED"
+    );
+}
+
+// Re-export `leaseFilePath` so consumers (e.g. `rk-server`) that
+// need to construct the same path as the resolver have a single
+// source of truth. Avoids two implementations drifting on
+// `.roku/leases/<id>.json` layout.
+export { leaseFilePath };
+
+/**
+ * Write the resolved IP into `testResultsDir/.device-ip` so worker
+ * processes (spawned after globalSetup) can read it synchronously.
+ */
+export async function persistDeviceIp(testResultsDir: string, ip: string): Promise<void> {
+    await fs.mkdir(testResultsDir, { recursive: true });
+    await fs.writeFile(join(testResultsDir, DEVICE_IP_CACHE_FILE), ip, "utf8");
+}

package/src/device/lease-provisioning.ts

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Provisioning facts the device-pool provider recorded on the lease.
+ *
+ * These describe how the device was *prepared*, which no ECP query can
+ * answer: `/query/device-info` reports the running `ui-software` version
+ * but not which OS image produced it. `globalSetup` folds them into the
+ * `device-env.json` artifact so a red CI run carries its own provenance.
+ *
+ * The lease file — not an env var — is the source of truth. Provider-owned
+ * env vars are Roku-internal and deliberately unknown to this package; the
+ * lease is the generic, already-sanctioned hand-off (the same one
+ * `device-resolver.ts` reads the IP from), and it records what the provider
+ * *actually* booted rather than what CI *asked* for.
+ *
+ * Every miss degrades to `{}`: no lease (local desk run), a provider that
+ * flashes nothing (`local`, say), a corrupt file, or an older provider
+ * that predates the rider. The artifact simply omits the field — absence
+ * means "unknown", never "none".
+ */
+
+import { join } from "node:path";
+
+import { readLeaseFile } from "@roku-sdk/tooling/src/device-pool/lease-writer";
+
+import { ENV_VAR, LEASE_FIELD } from "../constants";
+
+export interface LeaseProvisioning {
+    /** See `LEASE_FIELD.ROOTFS_ARTIFACTORY_PATH`. Absent when unknown. */
+    rootfsArtifactoryPath?: string;
+}
+
+/**
+ * Read the provisioning riders off this job's lease. Never throws — a
+ * diagnostics-only artifact field must not be able to fail a suite that
+ * would otherwise pass.
+ */
+export async function readLeaseProvisioning(cwd: string = process.cwd()): Promise<LeaseProvisioning> {
+    const leaseId = process.env[ENV_VAR.RK_DEVICE_LEASE_ID];
+    if (!leaseId || leaseId.length === 0) return {};
+    const leaseDir = process.env[ENV_VAR.RK_DEVICE_LEASE_DIR] ?? join(cwd, ".roku", "leases");
+    try {
+        const lease = await readLeaseFile(leaseId, leaseDir);
+        const rootfs = (lease as Record<string, unknown>)[LEASE_FIELD.ROOTFS_ARTIFACTORY_PATH];
+        return typeof rootfs === "string" && rootfs.length > 0 ? { rootfsArtifactoryPath: rootfs } : {};
+    } catch {
+        // `readLeaseFile` throws on ENOENT / malformed JSON / schema
+        // mismatch. The IP resolver already ran against the same file and
+        // reports a genuinely broken lease far more loudly than a
+        // provenance field ever should, so stay silent here.
+        return {};
+    }
+}