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

package/src/jest/preconditions.ts

@@ -0,0 +1,239 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Precondition assertions.
+ *
+ * - `requirePrecondition(client, reqs)`: sync guard, throws
+ *   `PreconditionNotMetError` on first failing field.
+ * - `itOnDevice` / `describeOnDevice`: registration-time wrappers
+ *   that read `DeviceInfo` synchronously from `device-env.json`
+ *   and call `.skip()` on mismatch.
+ *
+ * Evaluation order is the caller's `reqs` key insertion order
+ * (JS preserves it), so the caller picks which field reports first.
+ */
+
+import semver from "semver";
+
+import type { RkClient } from "../client/client";
+import { getDeviceClass } from "../device/device-class";
+import { readCachedDeviceInfoSync } from "../device/device-env-sync";
+import { PreconditionNotImplementedError, PreconditionNotMetError, RkClientError } from "../errors";
+import type { DeviceInfo, Precondition } from "../types";
+
+export interface OnDeviceTestOptions {
+    preconditions?: Precondition;
+    timeout?: number;
+}
+
+export interface OnDeviceDescribeOptions {
+    preconditions?: Precondition;
+}
+
+/**
+ * Sync precondition guard. Throws `PreconditionNotMetError` on
+ * mismatch. A throw here is a Jest **failure**, not a skip
+ * (jest-circus has no mid-test skip); use `itOnDevice` /
+ * `describeOnDevice` for skip-on-mismatch semantics.
+ */
+export function requirePrecondition(client: RkClient, requirements: Precondition): void {
+    const info = client.cachedDeviceInfo();
+    if (info === null) {
+        throw new RkClientError(
+            `requirePrecondition: no cached DeviceInfo available. Call installDeviceTestHooks or await client.queryDeviceInfo() before requirePrecondition so the cache is populated.`,
+            "PRECONDITION_NO_DEVICE_INFO"
+        );
+    }
+    evaluatePrecondition(info, requirements);
+}
+
+/**
+ * Evaluate `reqs` against `info`. Throws `PreconditionNotMetError`
+ * (or `PreconditionNotImplementedError`) on first failing field.
+ * Internal helper for `requirePrecondition` and the registration
+ * wrappers.
+ */
+export function evaluatePrecondition(info: DeviceInfo, reqs: Precondition): void {
+    for (const key of Object.keys(reqs) as Array<keyof Precondition>) {
+        switch (key) {
+            case "firmwareVersion": {
+                const required = reqs.firmwareVersion;
+                if (required === undefined) continue;
+                checkSemver("firmwareVersion", info.firmwareVersion, required);
+                continue;
+            }
+            case "modelFamily":
+                if (reqs.modelFamily !== undefined) {
+                    checkExact("modelFamily", info.modelFamily, reqs.modelFamily);
+                }
+                continue;
+            case "deviceClass":
+                if (reqs.deviceClass !== undefined) {
+                    // DeviceInfo.deviceClass is a form-factor tag;
+                    // perf tier comes from the static modelName table.
+                    const derived = getDeviceClass(info.modelName);
+                    checkExact("deviceClass", derived, reqs.deviceClass);
+                }
+                continue;
+            case "videoMode":
+                if (reqs.videoMode !== undefined) {
+                    checkVideoMode(info.videoMode, reqs.videoMode);
+                }
+                continue;
+            case "locale":
+                if (reqs.locale !== undefined) {
+                    checkExact("locale", info.locale, reqs.locale);
+                }
+                continue;
+            case "country":
+                if (reqs.country !== undefined) {
+                    checkExact("country", info.country, reqs.country);
+                }
+                continue;
+            case "library": {
+                if (reqs.library === undefined) continue;
+                // ECP doesn't surface library versions reliably;
+                // dedicated subclass keeps reporters distinguishable.
+                const expected = `${reqs.library.name}@${reqs.library.version}`;
+                throw new PreconditionNotImplementedError(
+                    `Precondition not met: library version checks (${expected}) are not implemented — ECP does not surface library versions today.`,
+                    {
+                        feature: "library-version",
+                        field: "library",
+                        expected,
+                        actual: info.libraries?.[reqs.library.name] ?? ""
+                    }
+                );
+            }
+        }
+    }
+}
+
+// ---------------------------------------------------------------------
+// Field checkers
+// ---------------------------------------------------------------------
+
+function checkExact(field: string, actual: string, expected: string): void {
+    if (actual === expected) return;
+    throw new PreconditionNotMetError(
+        `Precondition not met: requires ${field}="${expected}", device has ${field}="${actual}"`,
+        { field, expected, actual, reason: "mismatch" }
+    );
+}
+
+/**
+ * Prefix-match: `"1080p"` matches `"1080p"` and `"1080p60"`.
+ * Callers wanting exact match declare the longer prefix.
+ */
+function checkVideoMode(actual: string, expected: string): void {
+    if (actual.startsWith(expected)) return;
+    throw new PreconditionNotMetError(
+        `Precondition not met: requires videoMode="${expected}", device has videoMode="${actual}"`,
+        { field: "videoMode", expected, actual, reason: "mismatch" }
+    );
+}
+
+/**
+ * Coerces 4-part Roku firmware (`"12.5.4.1234"` → `"12.5.4"`) and
+ * runs through `semver.satisfies`. Invalid range → `RkClientError`
+ * (test-author bug). Non-semver `actual` → fail closed as mismatch.
+ */
+function checkSemver(field: string, actual: string, range: string): void {
+    const coercedActual = semver.coerce(actual);
+    const validRange = semver.validRange(range);
+    if (validRange === null) {
+        throw new RkClientError(
+            `Invalid semver range in precondition: ${field}="${range}". Examples of valid ranges: ">=12.0", ">=12.0 <14.0", "^12.0".`,
+            "PRECONDITION_INVALID_SEMVER_RANGE"
+        );
+    }
+    if (coercedActual === null) {
+        throw new PreconditionNotMetError(
+            `Precondition not met: requires ${field}${range}, device has ${field}=${actual || "<empty>"}`,
+            { field, expected: range, actual, reason: "mismatch" }
+        );
+    }
+    if (semver.satisfies(coercedActual, validRange)) return;
+    throw new PreconditionNotMetError(
+        `Precondition not met: requires ${field}${range}, device has ${field}=${actual}`,
+        { field, expected: range, actual, reason: "mismatch" }
+    );
+}
+
+// ---------------------------------------------------------------------
+// Registration-time wrappers
+// ---------------------------------------------------------------------
+
+// Per-module flag: warn once per file, not once per itOnDevice call.
+let fallbackWarned = false;
+
+/** Test-only reset for `fallbackWarned`. NOT exported via index.ts. */
+export function __resetFallbackWarnedForTests(): void {
+    fallbackWarned = false;
+}
+
+/**
+ * Returns the mismatch error, or null on pass / missing snapshot.
+ * Missing snapshot → register normally; the first real ECP call
+ * fails fast with remediation if no device is connected.
+ */
+function evaluateAtRegistration(preconditions: Precondition | undefined): PreconditionNotMetError | null {
+    if (!preconditions || Object.keys(preconditions).length === 0) return null;
+    const info = readCachedDeviceInfoSync();
+    if (info === null) {
+        if (!fallbackWarned) {
+            fallbackWarned = true;
+            console.warn(
+                `[device-test-client] No device-env.json snapshot found at ${process.cwd()}; ` +
+                    `itOnDevice/describeOnDevice preconditions will not be enforced for this run. ` +
+                    `Run via Jest globalSetup (installDeviceTestHooks wiring) so the snapshot is written.`
+            );
+        }
+        return null;
+    }
+    try {
+        evaluatePrecondition(info, preconditions);
+        return null;
+    } catch (err) {
+        if (err instanceof PreconditionNotMetError) return err;
+        throw err;
+    }
+}
+
+/**
+ * Strip the stable `"Precondition not met: "` prefix from the skip
+ * label so Jest's reporter one-liner stays compact.
+ */
+function skipLabel(name: string, err: PreconditionNotMetError): string {
+    const prefix = "Precondition not met: ";
+    const reason = err.message.startsWith(prefix) ? err.message.slice(prefix.length) : err.message;
+    return `${name} (skipped: ${reason})`;
+}
+
+/**
+ * Registration-time `it` wrapper that calls `it.skip()` on a
+ * synchronously-evaluated precondition mismatch. No `preconditions`
+ * → plain `it()`. No `device-env.json` → register normally + warn.
+ */
+export function itOnDevice(name: string, fn: () => void | Promise<void>, opts: OnDeviceTestOptions = {}): void {
+    const timeout = opts.timeout;
+    // ProvidesCallback union prefers Promise<unknown>; our signature
+    // is a strict subset at runtime.
+    const cb = fn as jest.ProvidesCallback;
+    const err = evaluateAtRegistration(opts.preconditions);
+    if (err) {
+        it.skip(skipLabel(name, err), cb, timeout);
+        return;
+    }
+    it(name, cb, timeout);
+}
+
+/** Registration-time `describe` wrapper; see `itOnDevice`. */
+export function describeOnDevice(name: string, fn: () => void, opts: OnDeviceDescribeOptions = {}): void {
+    const err = evaluateAtRegistration(opts.preconditions);
+    if (err) {
+        describe.skip(skipLabel(name, err), fn);
+        return;
+    }
+    describe(name, fn);
+}

package/src/jest/telemetry.ts

@@ -0,0 +1,331 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Device-lease telemetry helpers for the parallel-device rollout.
+ *
+ * Two outputs, both consumed downstream by post-run analysis:
+ *
+ *   1. **`[device-lease]` structured log line.** Single-line
+ *      `<prefix> <json>` written by `globalSetup` (acquire) and
+ *      `globalTeardown` (release). The single-line shape is
+ *      load-bearing: log aggregators parse with a one-shot regex
+ *      (`^\[device-lease\] (\{.*\})$`), no backreferences, no
+ *      multi-line accumulators. Insertion order of the JSON object
+ *      keys is `device, shard, provider, pid, host, acquiredAt|releasedAt`
+ *      — relied on by the dashboard's column ordering.
+ *
+ *   2. **JUnit `<properties>` per `<testcase>`.** `jest-junit@16`
+ *      does NOT support a static `properties` config option. The
+ *      supported mechanism is a CommonJS file
+ *      pointed at by the reporter's `testCasePropertiesFile` /
+ *      `testCasePropertiesDirectory` options; that file is
+ *      `require()`d at JUnit-generation time and must export a
+ *      function `(testCase) => Record<string, string>`. We bake the
+ *      resolved values into the file source at `globalSetup` time
+ *      so the reporter (which runs in the parent Jest process at
+ *      the very end of the run) does not need to re-read the
+ *      environment — env mutations by globalSetup don't always
+ *      survive across the lifecycle on every Jest config.
+ *
+ * Both consumers — log line and JUnit property — read the same
+ * resolved triple `{ deviceId, shardName, providerKind }` so a
+ * single source of truth keeps them from drifting.
+ *
+ * Leaf module: must not import from `client/`, `assertions/`, or
+ * any other `jest/` file. Pure functions only; the only side
+ * effects are `process.stdout` (via `console.log`) and the atomic
+ * file write in `writeJUnitTelemetryPropertiesFile`.
+ */
+
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+
+import { ENV_VAR } from "../constants";
+
+/**
+ * Default `providerKind` used when `RK_PROVIDER_KIND` is unset.
+ * The baseline only knows the local provider; the provider seam
+ * and the internal / custom providers set the env var explicitly via the CLI.
+ */
+export const DEFAULT_PROVIDER_KIND = "local";
+
+/**
+ * Default `shardName` used when `RK_SHARD_NAME` is unset.
+ * Literal `"default"` (not empty string) so JUnit consumers and
+ * dashboards never render an empty value — most viewers display
+ * empty as "(empty)" or hide the field entirely, which makes
+ * un-sharded baseline runs invisible in the rollout report.
+ */
+export const DEFAULT_SHARD_NAME = "default";
+
+/**
+ * Prefix on every `[device-lease]` log line. Unique enough that
+ * a `grep "^\[device-lease\] "` against the CI log gives a clean
+ * acquire/release timeline. Kept distinct from the
+ * `[device-test-client]` prefix used by the existing diagnostics
+ * so log aggregators can route the two streams independently.
+ */
+export const DEVICE_LEASE_LOG_PREFIX = "[device-lease]";
+
+/** Resolved telemetry inputs shared by the log line and the JUnit properties. */
+export interface DeviceLeaseTelemetry {
+    /**
+     * Stable identifier for the physical (or virtual) device.
+     * For `LocalProvider`: the resolved device IP. For internal / custom:
+     * the inventory id / cloud slot id.
+     */
+    readonly deviceId: string;
+    /** GitLab CI shard / job slice (`RK_SHARD_NAME`); `"default"` if unset. */
+    readonly shardName: string;
+    /** Device-pool provider kind (`RK_PROVIDER_KIND`); `"local"` if unset. */
+    readonly providerKind: string;
+    /** OS pid of the Jest parent process emitting the log. */
+    readonly pid: number;
+    /** `os.hostname()` of the runner / pod emitting the log. */
+    readonly host: string;
+}
+
+/**
+ * `[device-lease]` log payload emitted on `globalSetup`. The
+ * `acquiredAt` field is the ISO-8601 timestamp when the suite
+ * took ownership of the device. Kept readonly so consumers can
+ * `JSON.stringify` without worrying about accidental mutation
+ * after capture.
+ */
+export interface DeviceLeaseAcquireEvent extends DeviceLeaseTelemetry {
+    /** ISO-8601 (with `Z`); generated via `new Date().toISOString()`. */
+    readonly acquiredAt: string;
+}
+
+/** `[device-lease]` log payload emitted on `globalTeardown`. */
+export interface DeviceLeaseReleaseEvent extends DeviceLeaseTelemetry {
+    /** ISO-8601 (with `Z`); generated via `new Date().toISOString()`. */
+    readonly releasedAt: string;
+}
+
+export type DeviceLeaseEvent = DeviceLeaseAcquireEvent | DeviceLeaseReleaseEvent;
+
+/**
+ * Shape of the JUnit `<property>` set written per `<testcase>`.
+ *
+ * Field names mirror the spec verbatim: `device-id` and
+ * `shard-name` are kebab-case, `providerKind` is camelCase.
+ * The mixed convention is intentional at this layer — the
+ * downstream analysis scripts that consume these properties key
+ * off these exact strings, so renaming requires a coordinated
+ * change in both producers and consumers.
+ */
+export interface JUnitTelemetryProperties {
+    readonly "device-id": string;
+    readonly "shard-name": string;
+    readonly providerKind: string;
+}
+
+/**
+ * Resolve telemetry inputs from a known `deviceId` plus the
+ * environment / process. The argument struct is a discriminated
+ * input so partner consumers can construct their own resolver
+ * without re-reading `process.env` (e.g. when wrapping in a
+ * different host like Bun or a non-Jest harness).
+ *
+ * Pure: no I/O, no `console.*`. Safe to call from anywhere.
+ */
+export function resolveTelemetry(args: {
+    /** Resolved device identifier (typically the IP for `LocalProvider`). */
+    deviceId: string;
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `process.pid`. */
+    pid?: number;
+    /** Defaults to `os.hostname()`. */
+    host?: string;
+}): DeviceLeaseTelemetry {
+    // Fail-fast partner-API guard: an empty deviceId would emit
+    // `"device":""` to the log line and the JUnit property —
+    // indistinguishable from "field missing" in most viewers and
+    // a silent breakage of the telemetry contract. The
+    // first-party caller (`global-setup.ts`) already gets a
+    // non-empty IP from `resolveActiveDeviceIp` (which throws on
+    // empty), so this only fires for partner misuse.
+    if (args.deviceId.length === 0) {
+        throw new Error(
+            "[device-lease] resolveTelemetry: deviceId must be a non-empty string. " +
+                "If you are wiring telemetry into a custom globalSetup, resolve the device " +
+                "identifier (IP for LocalProvider, slot id for cloud providers) before calling."
+        );
+    }
+    const env = args.env ?? process.env;
+    const rawShard = env[ENV_VAR.RK_SHARD_NAME];
+    const rawProvider = env[ENV_VAR.RK_PROVIDER_KIND];
+    return {
+        deviceId: args.deviceId,
+        shardName: rawShard && rawShard.length > 0 ? rawShard : DEFAULT_SHARD_NAME,
+        providerKind: rawProvider && rawProvider.length > 0 ? rawProvider : DEFAULT_PROVIDER_KIND,
+        pid: args.pid ?? process.pid,
+        host: args.host ?? hostname()
+    };
+}
+
+/**
+ * Build the acquire-event payload. Separated from
+ * {@link emitDeviceLeaseLog} so callers can capture-and-assert
+ * (unit tests) without piping `console.log` through a stub, and
+ * so the same payload can be persisted alongside the log line
+ * in a later phase if needed.
+ */
+export function buildAcquireEvent(
+    telemetry: DeviceLeaseTelemetry,
+    /** Defaults to `new Date().toISOString()`. */
+    acquiredAt: string = new Date().toISOString()
+): DeviceLeaseAcquireEvent {
+    return { ...telemetry, acquiredAt };
+}
+
+/**
+ * Build the release-event payload. Symmetric to
+ * {@link buildAcquireEvent} — see that function's docstring for
+ * the rationale of the explicit-timestamp parameter.
+ */
+export function buildReleaseEvent(
+    telemetry: DeviceLeaseTelemetry,
+    /** Defaults to `new Date().toISOString()`. */
+    releasedAt: string = new Date().toISOString()
+): DeviceLeaseReleaseEvent {
+    return { ...telemetry, releasedAt };
+}
+
+/**
+ * Format a `[device-lease]` log line. Output shape:
+ *
+ *     [device-lease] {"device":"<id>","shard":"<shard>","provider":"<kind>","pid":<n>,"host":"<host>","acquiredAt":"<iso>"}
+ *     [device-lease] {"device":"<id>","shard":"<shard>","provider":"<kind>","pid":<n>,"host":"<host>","releasedAt":"<iso>"}
+ *
+ * Insertion order of the keys matters: the dashboard pivots on
+ * column order to render an "active leases at time T" timeline,
+ * and `JSON.stringify` preserves insertion order for non-numeric
+ * string keys (ECMA-262 §9.1.12 / `OrdinaryOwnPropertyKeys`).
+ * Always exactly one space between prefix and JSON; no trailing
+ * whitespace; no embedded newlines.
+ */
+export function formatDeviceLeaseLog(event: DeviceLeaseEvent): string {
+    // Discriminant guard: the union is acquire XOR release. A
+    // partner that hand-constructs an event with both fields
+    // (e.g. via `{ ...acquireEvent, releasedAt: "..." }`) would
+    // silently get the acquire branch under naive `"x" in event`
+    // checks and ship a corrupt record. Fail fast so the contract
+    // violation surfaces at the call site, not on the dashboard.
+    const hasAcquire = "acquiredAt" in event;
+    const hasRelease = "releasedAt" in event;
+    if (hasAcquire === hasRelease) {
+        throw new Error(
+            "[device-lease] formatDeviceLeaseLog: event must have exactly one of " +
+                "`acquiredAt` or `releasedAt` (got " +
+                `acquiredAt=${hasAcquire}, releasedAt=${hasRelease}). ` +
+                "Use buildAcquireEvent/buildReleaseEvent to construct events safely."
+        );
+    }
+    // Build the wire-format object with the spec's key names
+    // (`device`, `shard`, `provider` — NOT the JUnit property
+    // names). Insertion order = wire order.
+    const wire: Record<string, string | number> = {
+        device: event.deviceId,
+        shard: event.shardName,
+        provider: event.providerKind,
+        pid: event.pid,
+        host: event.host
+    };
+    if (hasAcquire) {
+        wire.acquiredAt = (event as DeviceLeaseAcquireEvent).acquiredAt;
+    } else {
+        wire.releasedAt = (event as DeviceLeaseReleaseEvent).releasedAt;
+    }
+    return `${DEVICE_LEASE_LOG_PREFIX} ${JSON.stringify(wire)}`;
+}
+
+/**
+ * Emit a `[device-lease]` log line to stdout. `console.log`
+ * (not `process.stdout.write`) for two reasons:
+ *
+ *   - It already trailing-newlines, matching every other log
+ *     line emitted by `device-test-client` (`logDeviceDiagnostic`,
+ *     the `console.warn` paths in `global-setup.ts`).
+ *   - Jest does NOT swallow `globalSetup` / `globalTeardown`
+ *     `console.*` output (those run in the parent process,
+ *     outside the per-test console buffering); CI sees it
+ *     verbatim regardless of Jest verbosity.
+ */
+export function emitDeviceLeaseLog(event: DeviceLeaseEvent): void {
+    console.log(formatDeviceLeaseLog(event));
+}
+
+/**
+ * Build the per-`<testcase>` JUnit properties record. Pure
+ * helper exposed independently of the file writer so partners
+ * who roll their own `jest-junit` plumbing (or use a different
+ * JUnit reporter) can plug the same data into their own
+ * mechanism.
+ */
+export function buildJUnitTelemetryProperties(telemetry: DeviceLeaseTelemetry): JUnitTelemetryProperties {
+    return {
+        "device-id": telemetry.deviceId,
+        "shard-name": telemetry.shardName,
+        providerKind: telemetry.providerKind
+    };
+}
+
+/**
+ * Atomically write the CommonJS file that `jest-junit`
+ * `require()`s at JUnit-generation time. Contract with the
+ * reporter (`buildJsonResults.js`):
+ *
+ *     module.exports = function (testCase) { return {...}; };
+ *
+ * The function returns a constant for every test case because
+ * device-id / shard-name / provider-kind are run-scoped, not
+ * test-scoped. We bake JSON-encoded values into the file source
+ * (rather than reading env vars at require-time) so the reporter
+ * is decoupled from the runtime env of the Jest parent — env
+ * mutations by globalSetup are not guaranteed to survive across
+ * every Jest configuration (workers, custom test environments).
+ *
+ * Atomic write (`write tmp` + `renameSync`) prevents jest-junit
+ * from `require()`-ing a torn partial file if the run is killed
+ * mid-write; mirrors the precedent in
+ * [`artifacts.ts → writeDeviceEnvSnapshot`](./artifacts.ts).
+ */
+export function writeJUnitTelemetryPropertiesFile(filePath: string, telemetry: DeviceLeaseTelemetry): void {
+    const props = buildJUnitTelemetryProperties(telemetry);
+    // `JSON.stringify` for each value gives us a safe encoding
+    // for any character (quotes, backslashes, newlines), and a
+    // valid JS string literal — the file body is then a tiny
+    // CJS module returning that literal-keyed object on every
+    // call. Generated lines are kept short for human readability
+    // when a CI engineer cats the file during triage.
+    const body =
+        "// AUTO-GENERATED by @roku-sdk/device-test-client/jest/telemetry.ts.\n" +
+        "// Read by `jest-junit` to populate per-<testcase> <properties>.\n" +
+        "// Do not edit by hand and do not commit — this file is rewritten\n" +
+        "// every run by `globalSetup` and lives under `test-results/` which\n" +
+        "// is git-ignored except for `.gitkeep`.\n" +
+        "module.exports = function deviceLeaseTestCaseProperties() {\n" +
+        "    return {\n" +
+        `        ${JSON.stringify("device-id")}: ${JSON.stringify(props["device-id"])},\n` +
+        `        ${JSON.stringify("shard-name")}: ${JSON.stringify(props["shard-name"])},\n` +
+        `        ${JSON.stringify("providerKind")}: ${JSON.stringify(props.providerKind)}\n` +
+        "    };\n" +
+        "};\n";
+    // Ensure the parent directory exists. The first-party caller
+    // (`global-setup.ts`) goes through `cleanArtifacts` which
+    // creates `test-results/` recursively, but a partner using
+    // this helper standalone may point it at an unmade path.
+    // `mkdir -p` semantics — no-op if the dir exists.
+    mkdirSync(dirname(filePath), { recursive: true });
+    // Per-pid+timestamp tmp name so concurrent writes (e.g. a
+    // partner that runs two suites against two devices in
+    // separate test-results dirs sharing a parent) cannot
+    // clobber each other's in-flight tmp files.
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, body, "utf8");
+    renameSync(tmp, filePath);
+}

package/src/logs/device-log-sink.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 Roku, Inc.
+// SPDX-License-Identifier: MIT
+/**
+ * Streams every observed `LogBuffer` line to
+ * `test-results/device.log`. Single-writer: relies on
+ * `maxWorkers: 1`. If that pin is ever lifted, consumers must
+ * shard per worker (e.g. `device.<worker>.log`).
+ *
+ * Leaf module: structural `LogBufferLike` keeps the graph acyclic.
+ */
+
+import { createWriteStream, type WriteStream } from "node:fs";
+import { join } from "node:path";
+
+import { ARTIFACT_FILE } from "../constants";
+import type { LogBufferLike } from "../types";
+
+export interface DeviceLogSink {
+    /** Append `line\n`. Never throws; errors surface on close(). */
+    write(line: string): void;
+    /** Flush and close. Subsequent writes are no-ops. */
+    close(): Promise<void>;
+}
+
+/**
+ * Truncate-open `<testResultsDir>/device.log`. Emits a header with
+ * device IP + ISO timestamp.
+ */
+export function openDeviceLogSink(testResultsDir: string, deviceIp?: string): DeviceLogSink {
+    const file = join(testResultsDir, ARTIFACT_FILE.DEVICE_LOG);
+    const stream: WriteStream = createWriteStream(file, {
+        flags: "w",
+        encoding: "utf8"
+    });
+    const header = `# device.log — run started ${new Date().toISOString()} — ` + `device ${deviceIp ?? "unknown"}\n`;
+    stream.write(header);
+
+    let closed = false;
+    return {
+        write(line: string): void {
+            if (closed) return;
+            // Swallow write errors so a destroyed stream can't
+            // unwind through `LogBuffer.append` and kill the test.
+            try {
+                stream.write(`${line}\n`);
+            } catch {
+                // best-effort; close() will surface any latent error
+            }
+        },
+        close(): Promise<void> {
+            if (closed) return Promise.resolve();
+            closed = true;
+            return new Promise<void>(resolve => {
+                stream.end(() => resolve());
+            });
+        }
+    };
+}
+
+/**
+ * Subscribe `sink` to `buffer`'s append feed. Caller MUST invoke the
+ * returned unsubscribe BEFORE `sink.close()` to avoid writing to an
+ * already-ended stream.
+ */
+export function attachToBuffer(sink: DeviceLogSink, buffer: LogBufferLike): () => void {
+    return buffer.subscribe(entry => {
+        sink.write(entry.line);
+    });
+}