@putdotio/rokit 2.0.1 → 2.1.0

package/AGENTS.md

@@ -48,12 +48,12 @@ Keep it platform-focused, typed, and useful for both humans and agents.
 - Missing config/env and child-command failures should not print stack traces.
 - `ROKIT_PASSWORD` is required only for developer-installer operations such as
   install and screenshot.
-- `ROKU_DEV_TARGET` and `ROKU_DEV_PASSWORD` are compatibility fallbacks, not the
-  primary public contract.
+- `ROKU_DEV_TARGET` and `ROKU_DEV_PASSWORD` are optional fallback aliases, not
+  the primary public contract.
 - Avoid sleeps in generic commands. App repos can add meaningful wait/assert
   loops around `rokit` primitives.
-- Release details live in `docs/DISTRIBUTION.md`; readiness details live in
-  `docs/READINESS.md`.
+- Release details live in `docs/DISTRIBUTION.md`; debugging details live in
+  `docs/DEBUGGING.md`; readiness details live in `docs/READINESS.md`.
 
 ## When Contracts Change
 

package/README.md

@@ -17,12 +17,12 @@
 
 ## Install
 
+Requires Node `>=24.14.0`; install it in a consumer repo with:
+
 ```bash
 pnpm add -D @putdotio/rokit
 ```
 
-Node `>=24.14`
-
 ## Quick Start
 
 Set the target Roku in the app repo that consumes `rokit`:
@@ -40,13 +40,13 @@ pnpm exec rokit package --out artifacts/live/channel.zip
 pnpm exec rokit install artifacts/live/channel.zip
 pnpm exec rokit launch dev
 pnpm exec rokit press Down Select
+pnpm exec rokit console artifacts/live/console.log --duration-ms 30000
 pnpm exec rokit proof artifacts/live/proof --screenshot
 ```
 
 `ROKIT_PASSWORD` is required for developer-installer operations such as
 `install` and `screenshot`. `ROKU_DEV_TARGET` and `ROKU_DEV_PASSWORD` are
-accepted as compatibility fallbacks for app repos that already use Roku dev
-naming.
+accepted as optional aliases when the `ROKIT_*` names are unset.
 
 ## Automation
 
@@ -76,6 +76,8 @@ Common commands:
 | `discover`                                         | Find Roku ECP devices with SSDP                    |
 | `device-info`                                      | Read Roku device metadata                          |
 | `active-app`                                       | Read the foreground app                            |
+| `console <output-path>`                            | Capture BrightScript console output from `8085`    |
+| `debug-command <command> [args...]`                | Run an allowlisted Roku debug command              |
 | `media-player`                                     | Read parsed `/query/media-player` state            |
 | `snapshot`                                         | Read a compact state snapshot                      |
 | `proof <output-dir>`                               | Write reviewable local proof artifacts             |
@@ -87,12 +89,14 @@ Common commands:
 | `sgnodes`                                          | Print the raw SceneGraph tree                      |
 | `assert-node` / `wait-node`                        | Check generic SceneGraph node state                |
 | `wait-active` / `wait-media-player` / `wait-ready` | Poll generic runtime readiness                     |
-| `screenshot <output-path>`                         | Save a developer screenshot                        |
+| `screenshot <output-path>`                         | Save a timestamped developer screenshot            |
 
 Mutating commands support `--dry-run` where the platform can validate without
 changing device or filesystem state. ECP paths reject query strings, fragments,
 traversal, backslashes, control characters, and percent-encoded path segments.
 Generated output paths must stay within the current working directory.
+Screenshots append a timestamp to the requested filename and report the actual
+path written, so repeated captures do not reuse cache-prone filenames.
 
 ## Library Use
 
@@ -136,8 +140,9 @@ await waitForSceneGraphAssertion(context, "player ready", (xml) => {
 
 - package, install, launch, deeplink params, and remote keypresses
 - raw ECP queries and parsed media-player state
+- BrightScript console capture and allowlisted debug-server commands
 - SceneGraph state queries and named-node assertions
-- screenshots, snapshots, and proof artifacts
+- timestamped screenshots, snapshots, and proof artifacts
 
 Consumer app repos own product behavior: opening specific routes, asserting
 playback for real content, checking app-specific UI nodes, and generating review
@@ -146,6 +151,7 @@ artifacts.
 ## Docs
 
 - [Contributing](./CONTRIBUTING.md)
+- [Roku debugging](./docs/DEBUGGING.md)
 - [Distribution](./docs/DISTRIBUTION.md)
 - [Agent readiness](./docs/READINESS.md)
 - [Security](./SECURITY.md)

package/dist/{roku-BxnS6Axs.mjs → debug-af6vvS9T.mjs}

@@ -1,6 +1,37 @@
+import { createConnection } from "node:net";
+import { Schema } from "effect";
+import { existsSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import * as rokuDeploy from "roku-deploy";
 import { createSocket } from "node:dgram";
-import { basename, dirname, extname, isAbsolute, resolve } from "node:path";
+//#region src/errors.ts
+var InvalidInput = class extends Schema.TaggedErrorClass()("InvalidInput", { message: Schema.String }) {};
+var MissingTarget = class extends Schema.TaggedErrorClass()("MissingTarget", {}) {
+	get message() {
+		return "ROKIT_TARGET is not set";
+	}
+};
+var MissingPassword = class extends Schema.TaggedErrorClass()("MissingPassword", {}) {
+	get message() {
+		return "ROKIT_PASSWORD is not set";
+	}
+};
+var DebugPortUnavailable = class extends Schema.TaggedErrorClass()("DebugPortUnavailable", {
+	detail: Schema.String,
+	port: Schema.Number
+}) {
+	get message() {
+		return `Roku debug port ${this.port} unavailable: ${this.detail}`;
+	}
+};
+var UnexpectedRokitFailure = class extends Schema.TaggedErrorClass()("UnexpectedRokitFailure", { message: Schema.String }) {};
+const renderError = (error) => error.message;
+const normalizeError = (error) => {
+	if (isRokitError(error)) return error;
+	return UnexpectedRokitFailure.make({ message: error instanceof Error ? error.message : String(error) });
+};
+const isRokitError = (error) => error instanceof DebugPortUnavailable || error instanceof InvalidInput || error instanceof MissingPassword || error instanceof MissingTarget || error instanceof UnexpectedRokitFailure;
+//#endregion
 //#region src/xml.ts
 const readXmlTag = (xml, tag) => {
 	return new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml)?.[1]?.trim();
@@ -215,7 +246,7 @@ const waitForActiveApp = async (context, appId, timeoutMs = 1e4) => {
 			lastApp = await queryActiveApp(context);
 			lastError = void 0;
 		} catch (error) {
-			lastError = formatErrorMessage(error);
+			lastError = formatErrorMessage$1(error);
 			await sleep(500);
 			continue;
 		}
@@ -295,7 +326,7 @@ const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4)
 			lastError = void 0;
 			if (mediaPlayer.state === expectedState) return mediaPlayer;
 		} catch (error) {
-			lastError = formatErrorMessage(error);
+			lastError = formatErrorMessage$1(error);
 		}
 		await sleep(500);
 	}
@@ -320,7 +351,7 @@ const querySceneGraph = async (context, options = {}) => {
 		if (attempt < attempts - 1) await sleep(retryDelayMs);
 	}
 	if (lastXml !== "") throw new Error("SceneGraph query returned incomplete XML");
-	throw new Error(`SceneGraph query failed: ${formatErrorMessage(lastError)}`);
+	throw new Error(`SceneGraph query failed: ${formatErrorMessage$1(lastError)}`);
 };
 const assertSceneGraphNode = async (context, nodeName, expectation) => {
 	assertNamedNode(await querySceneGraph(context), nodeName, expectation);
@@ -351,7 +382,7 @@ const waitForSceneGraphAssertion = async (context, description, assertXml, optio
 			assertXml(xml);
 			return xml;
 		} catch (error) {
-			lastError = formatErrorMessage(error);
+			lastError = formatErrorMessage$1(error);
 		}
 		await sleep(pollIntervalMs);
 	}
@@ -399,7 +430,7 @@ const packageOptions = (outputPath, rootDir = process.cwd()) => {
 	};
 };
 const validateEcpPath = (path) => {
-	rejectUnsafeInput(path, "ECP path");
+	rejectUnsafeInput$1(path, "ECP path");
 	if (path.includes("\\")) throw new Error("ECP path must not include backslashes");
 	if (path.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(path)) throw new Error("ECP path must be device-relative");
 	if (path.includes("?") || path.includes("#")) throw new Error("ECP path must not include query strings or fragments");
@@ -407,7 +438,7 @@ const validateEcpPath = (path) => {
 	if (/%(?:2e|2f|5c)/i.test(path)) throw new Error("ECP path must not include percent-encoded path segments");
 	return path;
 };
-const rejectUnsafeInput = (value, label) => {
+const rejectUnsafeInput$1 = (value, label) => {
 	if ([...value].some((character) => {
 		const code = character.charCodeAt(0);
 		return code < 32 || code === 127;
@@ -440,7 +471,7 @@ const postLaunchMaybeAccepted = async (context, url) => {
 		});
 		if (!response.ok && response.status !== 503) throw new Error(`POST ${url.pathname} returned HTTP ${response.status}`);
 	} catch (error) {
-		const message = formatErrorMessage(error).toLowerCase();
+		const message = formatErrorMessage$1(error).toLowerCase();
 		if (!message.includes("abort") && !message.includes("timeout") && !message.includes("fetch failed")) throw error;
 	}
 };
@@ -466,7 +497,7 @@ const readXmlNumberAttribute = (attributes, name) => {
 const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
-const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+const formatErrorMessage$1 = (error) => error instanceof Error ? error.message : String(error);
 const readSsdpHeaders = (text) => {
 	const headers = /* @__PURE__ */ new Map();
 	for (const line of text.split(/\r?\n/)) {
@@ -484,4 +515,236 @@ const readLocationTarget = (location) => {
 	}
 };
 //#endregion
-export { assertNamedNode as A, readNamedNodeAttribute as B, takeScreenshot as C, waitForMediaPlayerState as D, waitForActiveApp as E, assertSceneGraphNumberNear as F, readSceneGraphFailure as G, readNamedNodeBounds as H, escapeXmlAttribute as I, readActiveApp as J, readSceneGraphStatus as K, isCompleteSceneGraph as L, assertNamedNodeState as M, assertNamedNodeText as N, waitForSceneGraphAssertion as O, assertNamedNodeTranslation as P, isNamedNodeVisible as R, resolvePackageOutputPath as S, validateRemoteKey as T, readNamedNodeNumber as U, readNamedNodeAttributes as V, readNamedNodeTranslation as W, readXmlTag as X, readXmlAttribute as Y, querySceneGraph as _, getDeviceInfo as a, readMediaPlayerPositionMs as b, launchApp as c, queryActiveApp as d, queryEcp as f, queryMediaPlayerXmlSafe as g, queryMediaPlayerXml as h, discoverRokuDevices as i, assertNamedNodeSize as j, waitForSceneGraphNode as k, packageChannel as l, queryMediaPlayerSafe as m, assertSceneGraphNode as n, installPackage as o, queryMediaPlayer as p, sceneGraphContainsText as q, checkDevice as r, isActiveMediaPlayerState as s, assertMediaPlayerContainer as t, pressKey as u, readMediaPlayerContainer as v, validateEcpPath as w, readMediaPlayerState as x, readMediaPlayerInfo as y, parseSceneGraphNumberList as z };
+//#region src/runtime.ts
+const appDir = process.cwd();
+const envPath = join(join(appDir, ".rokit"), ".env");
+const loadLocalEnv = () => {
+	if (existsSync(envPath)) process.loadEnvFile(envPath);
+};
+const loadEnv = () => ({
+	password: process.env.ROKIT_PASSWORD ?? process.env.ROKU_DEV_PASSWORD,
+	target: process.env.ROKIT_TARGET ?? process.env.ROKU_DEV_TARGET,
+	timeoutMs: parseTimeout(process.env.ROKIT_TIMEOUT_MS),
+	username: process.env.ROKIT_USERNAME ?? "rokudev"
+});
+const requireTarget = (env) => {
+	const target = env.target?.trim();
+	if (!target) throw MissingTarget.make({});
+	return normalizeTarget(target);
+};
+const requirePassword = (env) => {
+	const password = env.password;
+	if (!password) throw MissingPassword.make({});
+	return password;
+};
+const resolveOutputPath = (path, label) => {
+	rejectUnsafeInput(path, label);
+	const resolved = resolve(appDir, path);
+	const relativePath = relative(appDir, resolved);
+	if (relativePath.startsWith("..") || isAbsolute(relativePath)) fail(`${label} must stay within the current working directory`);
+	return resolved;
+};
+const resolveFileOutputPath = (path, label) => {
+	const resolved = resolveOutputPath(path, label);
+	if (resolved === appDir) fail(`${label} must name a file within the current working directory`);
+	return resolved;
+};
+const rejectUnsafeInput = (value, label) => {
+	if ([...value].some((character) => {
+		const code = character.charCodeAt(0);
+		return code < 32 || code === 127;
+	})) fail(`${label} contains control characters`);
+};
+const rejectUnsafeEcpPath = (value) => {
+	try {
+		validateEcpPath(value);
+	} catch (error) {
+		fail(formatErrorMessage(error));
+	}
+};
+const fail = (message) => {
+	throw InvalidInput.make({ message });
+};
+const formatErrorMessage = (error) => {
+	if (error instanceof Error) return error.message;
+	return String(error);
+};
+const normalizeTarget = (target) => target.replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/:\d+$/, "");
+const parseTimeout = (value) => {
+	if (value === void 0) return 1e4;
+	const timeout = Number(value);
+	if (!Number.isFinite(timeout) || timeout <= 0) fail(`Invalid ROKIT_TIMEOUT_MS: ${value}`);
+	return timeout;
+};
+//#endregion
+//#region src/debug.ts
+const debugServerPort = 8080;
+const brightScriptConsolePort = 8085;
+const buildDebugCommand = (command, args) => {
+	validateDebugToken(command, "debug command");
+	for (const arg of args) rejectUnsafeInput(arg, "debug command argument");
+	if (command === "chanperf") {
+		validateChanperfArgs(args);
+		return debugServerCommand(command, args);
+	}
+	if (command === "brightscript_warnings") {
+		validateOptionalNonNegativeInteger(args, "brightscript_warnings");
+		return debugServerCommand(command, args);
+	}
+	if (command === "free" || command === "loaded_textures" || command === "r2d2_bitmaps") {
+		validateNoArgs(command, args);
+		return debugServerCommand(command, args);
+	}
+	if (command === "sgnodes") return debugServerCommand(command, normalizeSceneGraphNodeArgs(args));
+	if (command === "bsc" || command === "bscs" || command === "bt" || command === "classes" || command === "help" || command === "last" || command === "list") {
+		validateNoArgs(command, args);
+		return brightScriptConsoleCommand(command, args);
+	}
+	if (command === "threads" || command === "ths") {
+		validateOptionalNonNegativeInteger(args, command);
+		return brightScriptConsoleCommand(command, args);
+	}
+	return fail(`Unsupported Roku debug command: ${command}`);
+};
+const runDebugCommand = async (context, command, durationMs, idleTimeoutMs) => {
+	const safeCommand = buildDebugCommand(command.command, command.args);
+	const startedAt = Date.now();
+	const port = resolveDebugPort(context, safeCommand.port);
+	const body = await readDebugSocket(context, port, {
+		durationMs,
+		idleTimeoutMs,
+		request: safeCommand.request
+	});
+	const elapsedMs = Date.now() - startedAt;
+	return {
+		args: safeCommand.args,
+		body,
+		bytes: Buffer.byteLength(body),
+		command: safeCommand.command,
+		elapsedMs,
+		port
+	};
+};
+const captureDebugConsole = async (context, durationMs) => {
+	const startedAt = Date.now();
+	const port = resolveDebugPort(context, brightScriptConsolePort);
+	const body = await readDebugSocket(context, port, { durationMs });
+	const elapsedMs = Date.now() - startedAt;
+	return {
+		body,
+		bytes: Buffer.byteLength(body),
+		durationMs,
+		elapsedMs,
+		port
+	};
+};
+const debugServerCommand = (command, args) => ({
+	args,
+	command,
+	port: debugServerPort,
+	request: formatDebugRequest(command, args)
+});
+const brightScriptConsoleCommand = (command, args) => ({
+	args,
+	command,
+	port: brightScriptConsolePort,
+	request: formatDebugRequest(command, args)
+});
+const readDebugSocket = async (context, port, options) => await new Promise((resolve, reject) => {
+	let body = "";
+	let durationTimer;
+	let idleTimer;
+	let settled = false;
+	const socket = createConnection({
+		host: context.target,
+		port
+	});
+	const clearTimers = () => {
+		if (durationTimer !== void 0) clearTimeout(durationTimer);
+		if (idleTimer !== void 0) clearTimeout(idleTimer);
+	};
+	const finish = () => {
+		if (settled) return;
+		settled = true;
+		clearTimers();
+		socket.destroy();
+		resolve(body);
+	};
+	const failRead = (detail) => {
+		if (settled) return;
+		settled = true;
+		clearTimers();
+		socket.destroy();
+		reject(DebugPortUnavailable.make({
+			detail,
+			port
+		}));
+	};
+	const scheduleIdleTimer = () => {
+		if (options.idleTimeoutMs === void 0) return;
+		if (idleTimer !== void 0) clearTimeout(idleTimer);
+		idleTimer = setTimeout(finish, options.idleTimeoutMs);
+	};
+	socket.setEncoding("utf8");
+	socket.setTimeout(context.timeoutMs);
+	socket.once("connect", () => {
+		socket.setTimeout(0);
+		durationTimer = setTimeout(finish, options.durationMs);
+		if (options.request !== void 0) socket.write(options.request);
+	});
+	socket.on("data", (chunk) => {
+		body = `${body}${chunk}`;
+		scheduleIdleTimer();
+	});
+	socket.once("timeout", () => {
+		failRead("connection timed out");
+	});
+	socket.once("error", (error) => {
+		if (body.length > 0) {
+			finish();
+			return;
+		}
+		failRead(error.message);
+	});
+	socket.once("close", finish);
+});
+const formatDebugRequest = (command, args) => `${[command, ...args].join(" ")}\r\n`;
+const resolveDebugPort = (context, port) => port === debugServerPort ? context.debugServerPort ?? debugServerPort : context.debugConsolePort ?? brightScriptConsolePort;
+const validateDebugToken = (value, label) => {
+	rejectUnsafeInput(value, label);
+	if (!/^[A-Za-z0-9_-]+$/.test(value)) fail(`${label} contains unsupported characters`);
+};
+const validateChanperfArgs = (args) => {
+	if (args.length === 0) return;
+	if (args[0] === "-r") fail("chanperf -r writes to the BrightScript console; use rokit console for capture");
+	fail("usage: rokit debug-command chanperf");
+};
+const normalizeSceneGraphNodeArgs = (args) => {
+	if (args.length === 1 && (args[0] === "roots" || args[0] === "all")) return args;
+	if (args.length === 1) {
+		validateDebugToken(args[0] ?? "", "sgnodes id");
+		return args;
+	}
+	if (args.length === 2 && args[0] === "id") {
+		validateDebugToken(args[1] ?? "", "sgnodes id");
+		return [args[1] ?? ""];
+	}
+	return fail("usage: rokit debug-command sgnodes <roots|all|node-id|id node-id>");
+};
+const validateNoArgs = (command, args) => {
+	if (args.length > 0) fail(`usage: rokit debug-command ${command}`);
+};
+const validateOptionalNonNegativeInteger = (args, command) => {
+	if (args.length === 0) return;
+	if (args.length === 1) {
+		validateNonNegativeInteger(args[0] ?? "", `${command} argument`);
+		return;
+	}
+	fail(`usage: rokit debug-command ${command} [id]`);
+};
+const validateNonNegativeInteger = (value, label) => {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 0) fail(`Invalid ${label}: ${value}`);
+};
+//#endregion
+export { readNamedNodeBounds as $, readMediaPlayerInfo as A, waitForSceneGraphNode as B, queryEcp as C, queryMediaPlayerXmlSafe as D, queryMediaPlayerXml as E, validateEcpPath as F, assertNamedNodeTranslation as G, assertNamedNodeSize as H, validateRemoteKey as I, isCompleteSceneGraph as J, assertSceneGraphNumberNear as K, waitForActiveApp as L, readMediaPlayerState as M, resolvePackageOutputPath as N, querySceneGraph as O, takeScreenshot as P, readNamedNodeAttributes as Q, waitForMediaPlayerState as R, queryActiveApp as S, queryMediaPlayerSafe as T, assertNamedNodeState as U, assertNamedNode as V, assertNamedNodeText as W, parseSceneGraphNumberList as X, isNamedNodeVisible as Y, readNamedNodeAttribute as Z, installPackage as _, loadEnv as a, readActiveApp as at, packageChannel as b, requirePassword as c, normalizeError as ct, resolveOutputPath as d, readNamedNodeNumber as et, assertMediaPlayerContainer as f, getDeviceInfo as g, discoverRokuDevices as h, fail as i, sceneGraphContainsText as it, readMediaPlayerPositionMs as j, readMediaPlayerContainer as k, requireTarget as l, renderError as lt, checkDevice as m, captureDebugConsole as n, readSceneGraphFailure as nt, loadLocalEnv as o, readXmlAttribute as ot, assertSceneGraphNode as p, escapeXmlAttribute as q, runDebugCommand as r, readSceneGraphStatus as rt, rejectUnsafeEcpPath as s, readXmlTag as st, buildDebugCommand as t, readNamedNodeTranslation as tt, resolveFileOutputPath as u, isActiveMediaPlayerState as v, queryMediaPlayer as w, pressKey as x, launchApp as y, waitForSceneGraphAssertion as z };

package/dist/index.d.mts

@@ -49,6 +49,8 @@ declare const readActiveApp: (xml: string) => ActiveApp;
 declare const remoteKeys: readonly ["Home", "Rev", "Fwd", "Play", "Select", "Left", "Right", "Down", "Up", "Back", "InstantReplay", "Info", "Backspace", "Search", "Enter", "VolumeDown", "VolumeMute", "VolumeUp", "PowerOff", "ChannelUp", "ChannelDown", "InputTuner", "InputHDMI1", "InputHDMI2", "InputHDMI3", "InputHDMI4"];
 type RemoteKey = (typeof remoteKeys)[number] | `Lit_${string}`;
 type RokuContext = {
+  readonly debugConsolePort?: number;
+  readonly debugServerPort?: number;
   readonly password?: string;
   readonly target: string;
   readonly timeoutMs: number;
@@ -130,4 +132,31 @@ declare const packageChannel: (outputPath: string, rootDir?: string) => Promise<
 declare const validateEcpPath: (path: string) => string;
 declare const validateRemoteKey: (key: string) => void;
 //#endregion
-export { type ActiveApp, type DeviceSummary, type DiscoveredRokuDevice, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type PackageResult, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+//#region src/debug.d.ts
+type RokuDebugPort = 8080 | 8085;
+type RokuDebugCommand = {
+  readonly args: readonly string[];
+  readonly command: string;
+  readonly port: RokuDebugPort;
+  readonly request: string;
+};
+type DebugCommandResult = {
+  readonly args: readonly string[];
+  readonly body: string;
+  readonly bytes: number;
+  readonly command: string;
+  readonly elapsedMs: number;
+  readonly port: number;
+};
+type DebugConsoleCapture = {
+  readonly body: string;
+  readonly bytes: number;
+  readonly durationMs: number;
+  readonly elapsedMs: number;
+  readonly port: number;
+};
+declare const buildDebugCommand: (command: string, args: readonly string[]) => RokuDebugCommand;
+declare const runDebugCommand: (context: RokuContext, command: RokuDebugCommand, durationMs: number, idleTimeoutMs: number) => Promise<DebugCommandResult>;
+declare const captureDebugConsole: (context: RokuContext, durationMs: number) => Promise<DebugConsoleCapture>;
+//#endregion
+export { type ActiveApp, type DebugCommandResult, type DebugConsoleCapture, type DeviceSummary, type DiscoveredRokuDevice, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type PackageResult, type RemoteKey, type RetryOptions, type RokuContext, type RokuDebugCommand, type RokuDebugPort, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as assertNamedNode, B as readNamedNodeAttribute, C as takeScreenshot, D as waitForMediaPlayerState, E as waitForActiveApp, F as assertSceneGraphNumberNear, G as readSceneGraphFailure, H as readNamedNodeBounds, I as escapeXmlAttribute, J as readActiveApp, K as readSceneGraphStatus, L as isCompleteSceneGraph, M as assertNamedNodeState, N as assertNamedNodeText, O as waitForSceneGraphAssertion, P as assertNamedNodeTranslation, R as isNamedNodeVisible, T as validateRemoteKey, U as readNamedNodeNumber, V as readNamedNodeAttributes, W as readNamedNodeTranslation, X as readXmlTag, Y as readXmlAttribute, _ as querySceneGraph, a as getDeviceInfo, b as readMediaPlayerPositionMs, c as launchApp, d as queryActiveApp, f as queryEcp, g as queryMediaPlayerXmlSafe, h as queryMediaPlayerXml, i as discoverRokuDevices, j as assertNamedNodeSize, k as waitForSceneGraphNode, l as packageChannel, m as queryMediaPlayerSafe, n as assertSceneGraphNode, o as installPackage, p as queryMediaPlayer, q as sceneGraphContainsText, r as checkDevice, s as isActiveMediaPlayerState, t as assertMediaPlayerContainer, u as pressKey, v as readMediaPlayerContainer, w as validateEcpPath, x as readMediaPlayerState, y as readMediaPlayerInfo, z as parseSceneGraphNumberList } from "./roku-BxnS6Axs.mjs";
-export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };
+import { $ as readNamedNodeBounds, A as readMediaPlayerInfo, B as waitForSceneGraphNode, C as queryEcp, D as queryMediaPlayerXmlSafe, E as queryMediaPlayerXml, F as validateEcpPath, G as assertNamedNodeTranslation, H as assertNamedNodeSize, I as validateRemoteKey, J as isCompleteSceneGraph, K as assertSceneGraphNumberNear, L as waitForActiveApp, M as readMediaPlayerState, O as querySceneGraph, P as takeScreenshot, Q as readNamedNodeAttributes, R as waitForMediaPlayerState, S as queryActiveApp, T as queryMediaPlayerSafe, U as assertNamedNodeState, V as assertNamedNode, W as assertNamedNodeText, X as parseSceneGraphNumberList, Y as isNamedNodeVisible, Z as readNamedNodeAttribute, _ as installPackage, at as readActiveApp, b as packageChannel, et as readNamedNodeNumber, f as assertMediaPlayerContainer, g as getDeviceInfo, h as discoverRokuDevices, it as sceneGraphContainsText, j as readMediaPlayerPositionMs, k as readMediaPlayerContainer, m as checkDevice, n as captureDebugConsole, nt as readSceneGraphFailure, ot as readXmlAttribute, p as assertSceneGraphNode, q as escapeXmlAttribute, r as runDebugCommand, rt as readSceneGraphStatus, st as readXmlTag, t as buildDebugCommand, tt as readNamedNodeTranslation, v as isActiveMediaPlayerState, w as queryMediaPlayer, x as pressKey, y as launchApp, z as waitForSceneGraphAssertion } from "./debug-af6vvS9T.mjs";
+export { assertMediaPlayerContainer, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, buildDebugCommand, captureDebugConsole, checkDevice, discoverRokuDevices, escapeXmlAttribute, getDeviceInfo, installPackage, isActiveMediaPlayerState, isCompleteSceneGraph, isNamedNodeVisible, launchApp, packageChannel, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerSafe, queryMediaPlayerXml, queryMediaPlayerXmlSafe, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, runDebugCommand, sceneGraphContainsText, takeScreenshot, validateEcpPath, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,94 +1,15 @@
 #!/usr/bin/env node
-import { C as takeScreenshot, D as waitForMediaPlayerState, E as waitForActiveApp, G as readSceneGraphFailure, K as readSceneGraphStatus, S as resolvePackageOutputPath, T as validateRemoteKey, _ as querySceneGraph, a as getDeviceInfo, c as launchApp, d as queryActiveApp, f as queryEcp, i as discoverRokuDevices, k as waitForSceneGraphNode, l as packageChannel, n as assertSceneGraphNode, o as installPackage, p as queryMediaPlayer, r as checkDevice, u as pressKey, w as validateEcpPath } from "./roku-BxnS6Axs.mjs";
+import { B as waitForSceneGraphNode, C as queryEcp, I as validateRemoteKey, L as waitForActiveApp, N as resolvePackageOutputPath, O as querySceneGraph, P as takeScreenshot, R as waitForMediaPlayerState, S as queryActiveApp, _ as installPackage, a as loadEnv, b as packageChannel, c as requirePassword, ct as normalizeError, d as resolveOutputPath, g as getDeviceInfo, h as discoverRokuDevices, i as fail, l as requireTarget, lt as renderError, m as checkDevice, n as captureDebugConsole, nt as readSceneGraphFailure, o as loadLocalEnv, p as assertSceneGraphNode, r as runDebugCommand, rt as readSceneGraphStatus, s as rejectUnsafeEcpPath, t as buildDebugCommand, u as resolveFileOutputPath, w as queryMediaPlayer, x as pressKey, y as launchApp } from "./debug-af6vvS9T.mjs";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { Effect } from "effect";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
 import { NodeRuntime } from "@effect/platform-node";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { Effect, Schema } from "effect";
-//#region src/errors.ts
-var InvalidInput = class extends Schema.TaggedErrorClass()("InvalidInput", { message: Schema.String }) {};
-var MissingTarget = class extends Schema.TaggedErrorClass()("MissingTarget", {}) {
-	get message() {
-		return "ROKIT_TARGET is not set";
-	}
-};
-var MissingPassword = class extends Schema.TaggedErrorClass()("MissingPassword", {}) {
-	get message() {
-		return "ROKIT_PASSWORD is not set";
-	}
-};
-var UnexpectedRokitFailure = class extends Schema.TaggedErrorClass()("UnexpectedRokitFailure", { message: Schema.String }) {};
-const renderError = (error) => error.message;
-const normalizeError = (error) => {
-	if (isRokitError(error)) return error;
-	return UnexpectedRokitFailure.make({ message: error instanceof Error ? error.message : String(error) });
-};
-const isRokitError = (error) => error instanceof InvalidInput || error instanceof MissingPassword || error instanceof MissingTarget || error instanceof UnexpectedRokitFailure;
-//#endregion
-//#region src/runtime.ts
-const appDir = process.cwd();
-const envPath = join(join(appDir, ".rokit"), ".env");
-const loadLocalEnv = () => {
-	if (existsSync(envPath)) process.loadEnvFile(envPath);
-};
-const loadEnv = () => ({
-	password: process.env.ROKIT_PASSWORD ?? process.env.ROKU_DEV_PASSWORD,
-	target: process.env.ROKIT_TARGET ?? process.env.ROKU_DEV_TARGET,
-	timeoutMs: parseTimeout(process.env.ROKIT_TIMEOUT_MS),
-	username: process.env.ROKIT_USERNAME ?? "rokudev"
-});
-const requireTarget = (env) => {
-	const target = env.target?.trim();
-	if (!target) throw MissingTarget.make({});
-	return normalizeTarget(target);
-};
-const requirePassword = (env) => {
-	const password = env.password;
-	if (!password) throw MissingPassword.make({});
-	return password;
-};
-const resolveOutputPath = (path, label) => {
-	rejectUnsafeInput(path, label);
-	const resolved = resolve(appDir, path);
-	const relativePath = relative(appDir, resolved);
-	if (relativePath.startsWith("..") || isAbsolute(relativePath)) fail(`${label} must stay within the current working directory`);
-	return resolved;
-};
-const resolveFileOutputPath = (path, label) => {
-	const resolved = resolveOutputPath(path, label);
-	if (resolved === appDir) fail(`${label} must name a file within the current working directory`);
-	return resolved;
-};
-const rejectUnsafeInput = (value, label) => {
-	if ([...value].some((character) => {
-		const code = character.charCodeAt(0);
-		return code < 32 || code === 127;
-	})) fail(`${label} contains control characters`);
-};
-const rejectUnsafeEcpPath = (value) => {
-	try {
-		validateEcpPath(value);
-	} catch (error) {
-		fail(formatErrorMessage(error));
-	}
-};
-const fail = (message) => {
-	throw InvalidInput.make({ message });
-};
-const formatErrorMessage = (error) => {
-	if (error instanceof Error) return error.message;
-	return String(error);
-};
-const normalizeTarget = (target) => target.replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/:\d+$/, "");
-const parseTimeout = (value) => {
-	if (value === void 0) return 1e4;
-	const timeout = Number(value);
-	if (!Number.isFinite(timeout) || timeout <= 0) fail(`Invalid ROKIT_TIMEOUT_MS: ${value}`);
-	return timeout;
-};
-//#endregion
 //#region src/cli.ts
 const packageJson = createRequire(import.meta.url)("../package.json");
+const defaultConsoleDurationMs = 3e4;
+const defaultDebugCommandDurationMs = 3e3;
+const defaultDebugCommandIdleTimeoutMs = 500;
 const mainEffect = Effect.fn("mainEffect")(function* (argv = process.argv.slice(2)) {
 	let outputMode = inferOutputMode(argv);
 	let fields = [];
@@ -177,6 +98,30 @@ const runCommand = async (context, command, dryRun) => {
 			status: "ok"
 		};
 	}
+	if (command.name === "console") {
+		const path = timestampOutputPath(resolveFileOutputPath(command.args.outputPath, "console output path"));
+		const capture = await captureDebugConsole(deviceContext, command.args.durationMs);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, capture.body);
+		return {
+			command: command.name,
+			data: {
+				...capture,
+				path
+			},
+			message: `console: ${path}`,
+			status: "ok"
+		};
+	}
+	if (command.name === "debug-command") {
+		const result = await runDebugCommand(deviceContext, command.args.command, command.args.durationMs, command.args.idleTimeoutMs);
+		return {
+			command: command.name,
+			data: result,
+			message: result.body,
+			status: "ok"
+		};
+	}
 	if (command.name === "device-info") return {
 		command: command.name,
 		data: await getDeviceInfo(deviceContext),
@@ -307,7 +252,7 @@ const runCommand = async (context, command, dryRun) => {
 		};
 	}
 	if (command.name === "screenshot") {
-		const path = resolveFileOutputPath(command.outputPath, "screenshot output path");
+		const path = timestampOutputPath(resolveFileOutputPath(command.outputPath, "screenshot output path"));
 		if (dryRun) return dryRunResult(command.name, { path });
 		const password = requirePassword(deviceContext);
 		mkdirSync(dirname(path), { recursive: true });
@@ -463,7 +408,7 @@ const writeProof = async (context, outputDir, includeScreenshot) => {
 		const path = await takeScreenshot({
 			...context,
 			password
-		}, `${outputDir}/screenshot.png`);
+		}, timestampOutputPath(`${outputDir}/screenshot.png`));
 		artifacts.push({
 			kind: "screenshot",
 			path
@@ -475,6 +420,23 @@ const writeProof = async (context, outputDir, includeScreenshot) => {
 		snapshot
 	};
 };
+const timestampOutputPath = (path, date = /* @__PURE__ */ new Date()) => {
+	const extension = extname(path);
+	const name = basename(path, extension);
+	return join(dirname(path), `${name}-${formatTimestamp(date)}${extension}`);
+};
+const formatTimestamp = (date) => [
+	date.getFullYear().toString(),
+	padDatePart(date.getMonth() + 1),
+	padDatePart(date.getDate()),
+	"-",
+	padDatePart(date.getHours()),
+	padDatePart(date.getMinutes()),
+	padDatePart(date.getSeconds()),
+	"-",
+	padDatePart(date.getMilliseconds(), 3)
+].join("");
+const padDatePart = (value, length = 2) => value.toString().padStart(length, "0");
 const waitForReady = async (context, command) => {
 	const activeApp = await waitForActiveApp(context, command.appId, command.timeoutMs);
 	const sceneGraph = await observe(async () => querySceneGraph(context, {
@@ -501,7 +463,7 @@ const commandNeedsTarget = (command, dryRun) => {
 	if (command.name === "describe" || command.name === "discover" || command.name === "package") return false;
 	return !(dryRun && commandSupportsDryRun(command));
 };
-const commandSupportsDryRun = (command) => command.name === "install" || command.name === "launch" || command.name === "package" || command.name === "press" || command.name === "proof" || command.name === "screenshot";
+const commandSupportsDryRun = (command) => command.name === "console" || command.name === "debug-command" || command.name === "install" || command.name === "launch" || command.name === "package" || command.name === "press" || command.name === "proof" || command.name === "screenshot";
 const dryRunData = (command) => {
 	if (command.name === "launch") return {
 		appId: command.args.appId,
@@ -516,7 +478,20 @@ const dryRunData = (command) => {
 			until: command.args.until ? formatNodeData(command.args.until) : void 0
 		};
 	}
-	if (command.name === "screenshot") return { path: resolveFileOutputPath(command.outputPath, "screenshot output path") };
+	if (command.name === "console") return {
+		durationMs: command.args.durationMs,
+		path: timestampOutputPath(resolveFileOutputPath(command.args.outputPath, "console output path")),
+		port: 8085
+	};
+	if (command.name === "debug-command") return {
+		args: command.args.command.args,
+		command: command.args.command.command,
+		durationMs: command.args.durationMs,
+		idleTimeoutMs: command.args.idleTimeoutMs,
+		port: command.args.command.port,
+		request: command.args.command.request.trim()
+	};
+	if (command.name === "screenshot") return { path: timestampOutputPath(resolveFileOutputPath(command.outputPath, "screenshot output path")) };
 	if (command.name === "proof") return {
 		outputDir: resolveOutputPath(command.outputDir, "proof output directory"),
 		screenshot: command.screenshot
@@ -611,6 +586,14 @@ const parseCommand = (options) => {
 	const [name, ...args] = options.args;
 	if (name === "describe") return { name };
 	if (name === "check") return { name };
+	if (name === "console") return {
+		name,
+		args: parseConsoleArgs(args)
+	};
+	if (name === "debug-command") return {
+		name,
+		args: parseDebugCommandArgs(args)
+	};
 	if (name === "discover") return {
 		name,
 		timeoutMs: parseOptionalTimeout(args, "rokit discover")
@@ -767,6 +750,52 @@ const parseOutputPath = (args, usage) => {
 	if (args.length === 2 && args[0] === "--out" && args[1] !== void 0) return args[1];
 	return fail(`usage: ${usage}`);
 };
+const parseConsoleArgs = (args) => {
+	let outputPath;
+	let durationMs = defaultConsoleDurationMs;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--duration-ms") {
+			durationMs = parsePositiveInteger(args[index + 1] ?? "", "duration");
+			index += 1;
+			continue;
+		}
+		if (arg?.startsWith("--")) fail(`Unknown console option: ${arg}`);
+		if (outputPath !== void 0 || arg === void 0) fail("usage: rokit console <output-path> [--duration-ms <ms>]");
+		outputPath = arg;
+	}
+	if (outputPath !== void 0) return {
+		durationMs,
+		outputPath
+	};
+	return fail("usage: rokit console <output-path> [--duration-ms <ms>]");
+};
+const parseDebugCommandArgs = (args) => {
+	let durationMs = defaultDebugCommandDurationMs;
+	let idleTimeoutMs = defaultDebugCommandIdleTimeoutMs;
+	const commandArgs = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--duration-ms") {
+			durationMs = parsePositiveInteger(args[index + 1] ?? "", "duration");
+			index += 1;
+			continue;
+		}
+		if (arg === "--idle-timeout-ms") {
+			idleTimeoutMs = parsePositiveInteger(args[index + 1] ?? "", "idle timeout");
+			index += 1;
+			continue;
+		}
+		if (arg !== void 0) commandArgs.push(arg);
+	}
+	const [command, ...debugArgs] = commandArgs;
+	if (command === void 0) fail("usage: rokit debug-command <command> [args...] [--duration-ms <ms>]");
+	return {
+		command: buildDebugCommand(command, debugArgs),
+		durationMs,
+		idleTimeoutMs
+	};
+};
 const parseProofArgs = (args) => {
 	let outputDir;
 	let screenshot = false;
@@ -838,6 +867,21 @@ const parseInputJson = (value) => {
 		timeoutMs: readOptionalNumber(parsed, "timeoutMs")
 	};
 	if (command === "check" || command === "device-info" || command === "active-app") return { name: command };
+	if (command === "console") return {
+		args: {
+			durationMs: readOptionalNumber(parsed, "durationMs") ?? defaultConsoleDurationMs,
+			outputPath: readString(parsed, "outputPath")
+		},
+		name: "console"
+	};
+	if (command === "debug-command") return {
+		args: {
+			command: buildDebugCommand(readString(parsed, "debugCommand"), readOptionalStringArray(parsed, "args") ?? []),
+			durationMs: readOptionalNumber(parsed, "durationMs") ?? defaultDebugCommandDurationMs,
+			idleTimeoutMs: readOptionalNumber(parsed, "idleTimeoutMs") ?? defaultDebugCommandIdleTimeoutMs
+		},
+		name: "debug-command"
+	};
 	if (command === "media-player" || command === "sgnodes" || command === "snapshot") return { name: command };
 	if (command === "wait-active") return {
 		appId: readString(parsed, "appId"),
@@ -945,6 +989,12 @@ const readStringArray = (record, key) => {
 	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) return fail(`input JSON field must be a string array: ${key}`);
 	return value.map((item) => String(item));
 };
+const readOptionalStringArray = (record, key) => {
+	const value = record[key];
+	if (value === void 0) return;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) return fail(`input JSON field must be a string array: ${key}`);
+	return value.map((item) => String(item));
+};
 const readStringMap = (record, key) => {
 	const value = record[key];
 	if (value === void 0) return /* @__PURE__ */ new Map();
@@ -1074,6 +1124,13 @@ const describeCli = () => ({
 	commands: [
 		commandSchema("describe", "Print machine-readable command schemas.", false, false, []),
 		commandSchema("check", "Check ECP and developer installer reachability.", true, false, []),
+		commandSchema("console", "Capture BrightScript console output from port 8085.", true, true, [argumentField("outputPath", "path", "Console log output path inside the current app root."), optionField("durationMs", "positive-integer", "Capture duration in milliseconds.")]),
+		commandSchema("debug-command", "Run an allowlisted Roku debug command.", true, true, [
+			argumentField("debugCommand", "string", "Allowlisted Roku debug command."),
+			argumentField("args", "string[]", "Debug command arguments.", false, true),
+			optionField("durationMs", "positive-integer", "Maximum read duration in milliseconds."),
+			optionField("idleTimeoutMs", "positive-integer", "Stop reading after this many idle milliseconds.")
+		]),
 		commandSchema("discover", "Discover Roku ECP devices with SSDP.", false, false, [optionField("timeoutMs", "positive-integer", "Discovery timeout in milliseconds.")]),
 		commandSchema("device-info", "Read enhanced Roku device metadata.", true, false, []),
 		commandSchema("active-app", "Read the foreground app.", true, false, []),
@@ -1101,7 +1158,7 @@ const describeCli = () => ({
 			optionField("node", "node-condition", "Optional SceneGraph node condition."),
 			optionField("timeoutMs", "positive-integer", "Wait timeout in milliseconds.")
 		]),
-		commandSchema("screenshot", "Write a developer screenshot.", true, true, [argumentField("outputPath", "path", "Screenshot output path inside the current app root.")])
+		commandSchema("screenshot", "Write a timestamped developer screenshot.", true, true, [argumentField("outputPath", "path", "Screenshot base output path inside the current app root.")])
 	],
 	globalOptions: [
 		globalField("json", "boolean", "Print structured JSON output."),
@@ -1170,6 +1227,8 @@ const printHelp = () => {
 usage:
   rokit describe
   rokit check
+  rokit console <output-path> [--duration-ms <ms>]
+  rokit debug-command <command> [args...] [--duration-ms <ms>] [--idle-timeout-ms <ms>]
   rokit discover [--timeout-ms <ms>]
   rokit device-info
   rokit active-app
@@ -1203,8 +1262,8 @@ environment:
   ROKIT_USERNAME=rokudev
   ROKIT_TIMEOUT_MS=10000
 
-compatibility:
-  ROKU_DEV_TARGET and ROKU_DEV_PASSWORD are accepted as fallbacks.`);
+aliases:
+  ROKU_DEV_TARGET and ROKU_DEV_PASSWORD are accepted when ROKIT_* names are unset.`);
 };
 //#endregion
 //#region src/rokit.ts

package/docs/DEBUGGING.md

@@ -0,0 +1,75 @@
+# Roku Debugging
+
+`rokit` can wrap Roku debugging surfaces when they expose generic device or
+runtime state. Keep product journeys, selectors, content IDs, account state, and
+assertions in consumer app repos.
+
+## Official Surfaces
+
+Roku documents the developer debug console as a telnet connection to port
+`8085`. It emits app runtime output, compilation errors, crash line numbers,
+stack traces, and variable state when an app fails. Open it before sideloading or
+reproducing a startup crash so the first failure is captured.
+
+Roku also documents debug-server utilities on port `8080`. Useful generic
+commands include:
+
+| Command             | Port   | Use                                         |
+| ------------------- | ------ | ------------------------------------------- |
+| `chanperf`          | `8080` | Current app memory and CPU snapshot         |
+| `free`              | `8080` | Device memory snapshot                      |
+| `sgnodes roots`     | `8080` | Top-level SceneGraph nodes                  |
+| `sgnodes all`       | `8080` | Full SceneGraph node listing                |
+| `sgnodes <node_ID>` | `8080` | SceneGraph nodes with a matching `id` field |
+| `loaded_textures`   | `8080` | Loaded texture diagnostics                  |
+| `r2d2_bitmaps`      | `8080` | Bitmap diagnostics                          |
+
+The BrightScript debug protocol is a separate binary protocol for interactive
+debugger clients. It can inspect variables, stack traces, breakpoints, and
+stepping state after a launch request enables remote debugging. It is not the
+first `rokit` target because crash capture needs append-only text artifacts more
+than an IDE-style session.
+
+Sources:
+
+- [Roku debugging](https://developer.roku.com/docs/developer-program/debugging/debugging-channels.md)
+- [BrightScript debug protocol](https://developer.roku.com/docs/developer-program/debugging/socket-based-debugger.md)
+- [Roku developer tools](https://developer.roku.com/docs/developer-program/dev-tools/tools-overview.md)
+
+## `rokit` Shape
+
+The implemented first slice covers text telnet capture and allowlisted
+debug-server commands:
+
+- `rokit console <output-path> [--duration-ms <ms>]` captures port `8085`
+  output to a timestamped local log.
+- `rokit debug-command <command> [args...]` sends one allowlisted command to
+  port `8080` or `8085` and prints the response.
+
+`debug-command` is described as mutating for agent safety because some
+allowlisted Roku commands can affect profiling/debugger state.
+
+Roku's `chanperf -r <seconds>` command writes repeated samples to the
+BrightScript console on `8085`, not the `8080` socket that receives the command.
+`rokit debug-command` intentionally rejects that form until a coordinated
+capture command can open the console, start sampling, stop sampling, and write
+one proof bundle.
+
+The natural next command is `rokit crash-watch <app-id> <output-dir>`, which
+would connect to the console, launch an app, capture logs, and write normal
+proof artifacts after the capture window.
+
+Use Node's `node:net` module directly instead of shelling out to a local telnet
+binary. This keeps the CLI cross-platform, typed, and easier to test.
+
+## Limits
+
+- Live verification requires a developer-enabled Roku with reachable debug
+  ports. Unit tests can cover parsing, command validation, output paths, and
+  socket behavior with fake TCP servers.
+- The console should be connected before the repro. It cannot recover log lines
+  emitted before the socket was open.
+- Another tool, such as an IDE or Roku plugin, may already own the console
+  connection.
+- If the device hard-reboots, `rokit` can only preserve bytes received before
+  the socket disconnects.

package/docs/READINESS.md

@@ -8,12 +8,12 @@ Status: current as of 2026-05-17
 
 Overall: B+
 
-| Dimension  | Status | Evidence                                                                                                                                                                                 | Gap                                     |
-| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| bootable   | pass   | `pnpm smoke` builds the CLI and checks `--version` plus `--help`                                                                                                                         | no server boot surface, by design       |
-| testable   | pass   | `pnpm verify` runs TypeScript, bundle, unit tests, and npm pack dry run                                                                                                                  | live Roku checks require local hardware |
-| observable | pass   | CLI commands print active app, device info, raw ECP state, SceneGraph XML, snapshots, proof bundles, screenshots, compact assertion failures, and JSON output by default in non-TTY runs | no CI hardware lane                     |
-| verifiable | pass   | CI runs `pnpm verify`; `pnpm live:smoke` proves a configured Roku responds; `pnpm live:probe` packages, installs, launches, drives, asserts, screenshots, and proofs a generic channel   | no CI hardware lane                     |
+| Dimension  | Status | Evidence                                                                                                                                                                                                                                 | Gap                                     |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| bootable   | pass   | `pnpm smoke` builds the CLI and checks `--version` plus `--help`                                                                                                                                                                         | no server boot surface, by design       |
+| testable   | pass   | `pnpm verify` runs TypeScript, bundle, unit tests, and npm pack dry run                                                                                                                                                                  | live Roku checks require local hardware |
+| observable | pass   | CLI commands print active app, device info, raw ECP state, SceneGraph XML, BrightScript console logs, debug-server output, snapshots, proof bundles, screenshots, compact assertion failures, and JSON output by default in non-TTY runs | no CI hardware lane                     |
+| verifiable | pass   | CI runs `pnpm verify`; `pnpm live:smoke` proves a configured Roku responds; `pnpm live:probe` packages, installs, launches, drives, asserts, screenshots, and proofs a generic channel                                                   | no CI hardware lane                     |
 
 ## Layers
 
@@ -22,7 +22,7 @@ Overall: B+
 - Interact: `rokit press`, `rokit launch`, `rokit query`, `rokit sgnodes`
 - E2e: `pnpm live:probe` for a configured developer-enabled Roku
 - Enforce: GitHub Actions `verify`, optional `.git-hooks/pre-push`
-- Observe: ECP responses, SceneGraph XML, `rokit snapshot`, `rokit proof`, screenshots, concise command output
+- Observe: ECP responses, SceneGraph XML, `rokit console`, `rokit debug-command`, `rokit snapshot`, `rokit proof`, screenshots, concise command output
 - Isolate: `.rokit/` and `.env` stay local per worktree
 
 ## Agent-Facing CLI Contract

package/docs/skills/rokit-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rokit-harness
-description: Use rokit as a generic Roku harness adapter for packaging, installing, launching, key input, ECP/SceneGraph/media-player observation, readiness waits, screenshots, and proof bundles.
+description: Use rokit as a generic Roku harness adapter for packaging, installing, launching, key input, ECP/SceneGraph/media-player observation, readiness waits, debug console capture, screenshots, and proof bundles.
 ---
 
 # rokit Harness
@@ -19,12 +19,18 @@ repo.
 3. Prefer structured output. In automation, rely on the non-TTY JSON default or
    pass `--json` explicitly.
 4. Use `--fields` to keep observations small when only a few values are needed.
-5. For live proof, use `rokit snapshot` for a quick state read,
+5. Screenshot commands append a timestamp to the requested filename. Use the
+   returned JSON `data.path` as the artifact path instead of assuming the input
+   path was written.
+6. For live proof, use `rokit snapshot` for a quick state read,
    `rokit proof <output-dir>` for review artifacts, or `pnpm live:probe` in the
    rokit repo for the full generic package/install/launch/input/proof probe.
-6. Use `rokit wait-ready <app-id>` after launch when the app can race ECP or
+7. For crash/debug proof, start `rokit console <output-path>` before
+   reproducing the problem so startup errors and crash traces are captured.
+   Use `rokit debug-command <command>` only for generic Roku debug commands.
+8. Use `rokit wait-ready <app-id>` after launch when the app can race ECP or
    SceneGraph readiness.
-7. Use `rokit press --until-node ...` for bounded navigation loops instead of
+9. Use `rokit press --until-node ...` for bounded navigation loops instead of
    arbitrary sleeps.
 
 ## Boundaries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",