@putdotio/rokit 1.0.0 → 1.1.0

package/README.md

@@ -38,19 +38,47 @@ Then run:
 pnpm exec rokit check
 pnpm exec rokit launch dev
 pnpm exec rokit press Down Select
+pnpm exec rokit press --delay-ms 250 Right Select
 pnpm exec rokit query /query/active-app
+pnpm exec rokit wait-node videoPlayerScreen visible
 pnpm exec rokit screenshot artifacts/live/player.png
 ```
 
+App-specific scenario scripts can also import the generic helpers:
+
+```ts
+import { assertSceneGraphNode, pressKey, querySceneGraph, type RokuContext } from "@putdotio/rokit";
+
+const target = process.env.ROKIT_TARGET;
+
+if (!target) {
+  throw new Error("ROKIT_TARGET is not set");
+}
+
+const context: RokuContext = {
+  target,
+  timeoutMs: 10_000,
+  username: "rokudev",
+};
+
+await pressKey(context, "Info");
+await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
+await querySceneGraph(context);
+```
+
 ## Commands
 
 ```bash
 rokit check
 rokit device-info
 rokit active-app
+rokit wait-active <app-id> [--timeout-ms <ms>]
 rokit launch <app-id> [--param key=value]
-rokit press <key> [key...]
+rokit press [--delay-ms <ms>] <key> [key...]
 rokit query <ecp-path>
+rokit sgnodes
+rokit assert-node <node-name> <visible|hidden|absent|text|attr> [value]
+rokit wait-node <node-name> <visible|hidden|absent|text|attr> [value] [--timeout-ms <ms>]
 rokit screenshot <output-path>
 rokit install <zip-path>
 rokit --version
@@ -60,10 +88,15 @@ rokit --version
   is reachable.
 - `device-info` prints enhanced Roku device metadata as JSON.
 - `active-app` prints the foreground app.
+- `wait-active` waits until the requested app is foregrounded.
 - `launch` opens an app and waits until it is active. Use repeated `--param`
   values for deeplink parameters.
-- `press` sends Roku remote keys through ECP.
+- `press` sends Roku remote keys through ECP. Use `--delay-ms` for navigation
+  sequences that need a stable gap between keys.
 - `query` prints a raw ECP response such as `/query/sgnodes/all`.
+- `sgnodes` prints the raw SceneGraph tree from `/query/sgnodes/all`.
+- `assert-node` checks a named SceneGraph node once.
+- `wait-node` polls SceneGraph until a named node condition matches.
 - `screenshot` saves a developer screenshot. It requires `ROKIT_PASSWORD`.
 - `install` publishes an existing ZIP through `roku-deploy`. It requires
   `ROKIT_PASSWORD`.
@@ -92,6 +125,7 @@ tokens, and app-specific media identifiers do not belong in git.
 - launch and deeplink parameters
 - remote keypresses
 - raw ECP queries
+- SceneGraph state queries and named-node assertions
 - screenshots
 
 App repositories should keep their own scenario commands for product behavior,
@@ -101,6 +135,8 @@ HTML, or checking app-specific UI nodes.
 ## Docs
 
 - [Contributing](./CONTRIBUTING.md)
+- [Distribution](./docs/DISTRIBUTION.md)
+- [Agent readiness](./docs/READINESS.md)
 - [Security](./SECURITY.md)
 
 ## Repo Internals

package/dist/index.d.mts

@@ -0,0 +1,63 @@
+import * as rokuDeploy from "roku-deploy";
+
+//#region src/scenegraph.d.ts
+type NodeState = "absent" | "hidden" | "visible";
+type NodeExpectation = {
+  readonly state: NodeState;
+  readonly text?: string;
+} | {
+  readonly attribute: string;
+  readonly value: string;
+};
+declare const readNamedNodeAttributes: (xml: string, nodeName: string) => string | undefined;
+declare const readNamedNodeAttribute: (xml: string, nodeName: string, attributeName: string) => string | undefined;
+declare const isNamedNodeVisible: (xml: string, nodeName: string) => boolean;
+declare const assertNamedNode: (xml: string, nodeName: string, expectation: NodeExpectation) => void;
+declare const assertNamedNodeState: (xml: string, nodeName: string, state: NodeState) => void;
+declare const assertNamedNodeText: (xml: string, nodeName: string, expectedText: string) => void;
+//#endregion
+//#region src/xml.d.ts
+type ActiveApp = {
+  readonly id: string;
+  readonly name: string;
+  readonly type: string;
+  readonly version: string;
+};
+declare const readXmlTag: (xml: string, tag: string) => string | undefined;
+declare const readXmlAttribute: (attributes: string, name: string) => string | undefined;
+declare const readActiveApp: (xml: string) => ActiveApp;
+//#endregion
+//#region src/roku.d.ts
+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 password?: string;
+  readonly target: string;
+  readonly timeoutMs: number;
+  readonly username: string;
+};
+type DeviceSummary = {
+  readonly ecp: string;
+  readonly installerStatus: number;
+  readonly model: string;
+  readonly name: string;
+};
+declare const checkDevice: (context: RokuContext) => Promise<DeviceSummary>;
+declare const getDeviceInfo: (context: RokuContext) => Promise<rokuDeploy.DeviceInfo>;
+declare const queryActiveApp: (context: RokuContext) => Promise<ActiveApp>;
+declare const waitForActiveApp: (context: RokuContext, appId: string, timeoutMs?: number) => Promise<ActiveApp>;
+declare const launchApp: (context: RokuContext, appId: string, params?: ReadonlyMap<string, string>) => Promise<ActiveApp>;
+declare const pressKey: (context: RokuContext, key: string) => Promise<void>;
+declare const queryEcp: (context: RokuContext, path: string) => Promise<string>;
+declare const querySceneGraph: (context: RokuContext) => Promise<string>;
+declare const assertSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation) => Promise<void>;
+declare const waitForSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation, timeoutMs?: number) => Promise<void>;
+declare const installPackage: (context: RokuContext & {
+  readonly password: string;
+}, zipPath: string) => Promise<string>;
+declare const takeScreenshot: (context: RokuContext & {
+  readonly password: string;
+}, outputPath: string) => Promise<string>;
+declare const validateRemoteKey: (key: string) => void;
+//#endregion
+export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RokuContext, assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { S as readXmlTag, _ as isNamedNodeVisible, a as launchApp, b as readActiveApp, c as queryEcp, d as validateRemoteKey, f as waitForActiveApp, g as assertNamedNodeText, h as assertNamedNodeState, i as installPackage, l as querySceneGraph, m as assertNamedNode, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot, v as readNamedNodeAttribute, x as readXmlAttribute, y as readNamedNodeAttributes } from "./roku-D-FxlWPE.mjs";
+export { assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };

package/dist/rokit.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/rokit.mjs

@@ -1,141 +1,8 @@
 #!/usr/bin/env node
+import { a as launchApp, c as queryEcp, f as waitForActiveApp, i as installPackage, l as querySceneGraph, n as checkDevice, o as pressKey, p as waitForSceneGraphNode, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot } from "./roku-D-FxlWPE.mjs";
 import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";
-import { basename, dirname, extname, join, resolve } from "node:path";
-import * as rokuDeploy from "roku-deploy";
-//#region src/xml.ts
-const readXmlTag = (xml, tag) => {
-	return new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml)?.[1]?.trim();
-};
-const readXmlAttribute = (attributes, name) => {
-	return new RegExp(`${name}="([^"]*)"`).exec(attributes)?.[1];
-};
-const readActiveApp = (xml) => {
-	const match = /<app\s+([^>]*)>([^<]*)<\/app>/.exec(xml);
-	if (!match) throw new Error("active app response did not include an app node");
-	const attributes = match[1] ?? "";
-	return {
-		id: readXmlAttribute(attributes, "id") ?? "",
-		name: match[2]?.trim() ?? "",
-		type: readXmlAttribute(attributes, "type") ?? "",
-		version: readXmlAttribute(attributes, "version") ?? ""
-	};
-};
-//#endregion
-//#region src/roku.ts
-const ecpPort = 8060;
-const remoteKeySet = new Set([
-	"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"
-]);
-const checkDevice = async (context) => {
-	const deviceInfo = await fetchText(context, "/query/device-info");
-	const installerStatus = await fetchInstallerStatus(context);
-	return {
-		ecp: `http://${context.target}:${ecpPort}`,
-		installerStatus,
-		model: readXmlTag(deviceInfo, "model-name") ?? "unknown model",
-		name: readXmlTag(deviceInfo, "friendly-device-name") ?? readXmlTag(deviceInfo, "friendlyName") ?? "unknown"
-	};
-};
-const getDeviceInfo = async (context) => await rokuDeploy.getDeviceInfo({
-	enhance: true,
-	host: context.target,
-	remotePort: ecpPort,
-	timeout: context.timeoutMs
-});
-const queryActiveApp = async (context) => readActiveApp(await fetchText(context, "/query/active-app"));
-const launchApp = async (context, appId, params = /* @__PURE__ */ new Map()) => {
-	const url = ecpUrl(context, `/launch/${encodeURIComponent(appId)}`);
-	for (const [key, value] of params) url.searchParams.set(key, value);
-	await postOk(context, url);
-	return await waitForActiveApp(context, appId);
-};
-const pressKey = async (context, key) => {
-	validateRemoteKey(key);
-	await postOk(context, ecpUrl(context, `/keypress/${encodeURIComponent(key)}`));
-};
-const queryEcp = async (context, path) => await fetchText(context, path.startsWith("/") ? path : `/${path}`);
-const installPackage = async (context, zipPath) => {
-	const resolvedZip = resolve(zipPath);
-	const extension = extname(resolvedZip);
-	return (await rokuDeploy.publish({
-		host: context.target,
-		outDir: dirname(resolvedZip),
-		outFile: basename(resolvedZip, extension),
-		password: context.password,
-		rootDir: process.cwd(),
-		username: context.username
-	})).message;
-};
-const takeScreenshot = async (context, outputPath) => {
-	const resolvedOutput = resolve(outputPath);
-	const extension = extname(resolvedOutput);
-	return await rokuDeploy.takeScreenshot({
-		host: context.target,
-		outDir: dirname(resolvedOutput),
-		outFile: basename(resolvedOutput, extension),
-		password: context.password
-	});
-};
-const validateRemoteKey = (key) => {
-	if (key.startsWith("Lit_")) return;
-	if (!remoteKeySet.has(key)) throw new Error(`unsupported remote key: ${key}`);
-};
-const waitForActiveApp = async (context, appId, timeoutMs = 1e4) => {
-	const start = Date.now();
-	let lastApp;
-	while (Date.now() - start < timeoutMs) {
-		lastApp = await queryActiveApp(context);
-		if (lastApp.id === appId) return lastApp;
-		await sleep(500);
-	}
-	const last = lastApp ? `${lastApp.id} ${lastApp.name}` : "unknown";
-	throw new Error(`expected active app ${appId}, got ${last}`);
-};
-const fetchInstallerStatus = async (context) => {
-	return (await fetch(`http://${context.target}`, { signal: AbortSignal.timeout(context.timeoutMs) })).status;
-};
-const fetchText = async (context, path) => {
-	const response = await fetch(ecpUrl(context, path), { signal: AbortSignal.timeout(context.timeoutMs) });
-	if (!response.ok) throw new Error(`GET ${path} returned HTTP ${response.status}`);
-	return await response.text();
-};
-const postOk = async (context, url) => {
-	const response = await fetch(url, {
-		method: "POST",
-		signal: AbortSignal.timeout(context.timeoutMs)
-	});
-	if (!response.ok) throw new Error(`POST ${url.pathname} returned HTTP ${response.status}`);
-};
-const ecpUrl = (context, path) => new URL(path, `http://${context.target}:${ecpPort}`);
-const sleep = (ms) => new Promise((resolve) => {
-	setTimeout(resolve, ms);
-});
 const envPath = join(join(process.cwd(), ".rokit"), ".env");
 const loadLocalEnv = () => {
 	if (existsSync(envPath)) process.loadEnvFile(envPath);
@@ -217,13 +84,19 @@ const runCommand = async (context, command) => {
 		console.log(`active app: ${app.id} ${app.name} ${app.version}`.trim());
 		return;
 	}
+	if (command.name === "wait-active") {
+		const app = await waitForActiveApp(context, command.appId, command.timeoutMs);
+		console.log(`active app: ${app.id} ${app.name} ${app.version}`.trim());
+		return;
+	}
 	if (command.name === "launch") {
 		const app = await launchApp(context, command.args.appId, command.args.params);
 		console.log(`launched: ${app.id} ${app.name} ${app.version}`.trim());
 		return;
 	}
 	if (command.name === "press") {
-		for (const key of command.keys) {
+		for (const [index, key] of command.args.keys.entries()) {
+			if (index > 0 && command.args.delayMs > 0) await sleep(command.args.delayMs);
 			await pressKey(context, key);
 			console.log(`pressed: ${key}`);
 		}
@@ -233,6 +106,20 @@ const runCommand = async (context, command) => {
 		console.log(await queryEcp(context, command.path));
 		return;
 	}
+	if (command.name === "sgnodes") {
+		console.log(await querySceneGraph(context));
+		return;
+	}
+	if (command.name === "assert-node") {
+		await assertSceneGraphNode(context, command.args.nodeName, command.args.expectation);
+		console.log(`asserted node: ${formatNodeCondition(command.args)}`);
+		return;
+	}
+	if (command.name === "wait-node") {
+		await waitForSceneGraphNode(context, command.args.nodeName, command.args.expectation, command.args.timeoutMs);
+		console.log(`matched node: ${formatNodeCondition(command.args)}`);
+		return;
+	}
 	if (command.name === "screenshot") {
 		const password = requirePassword(context);
 		mkdirSync(dirname(command.outputPath), { recursive: true });
@@ -255,17 +142,23 @@ const parseCommand = (argv) => {
 	if (name === "check") return { name };
 	if (name === "device-info") return { name };
 	if (name === "active-app") return { name };
-	if (name === "launch") return {
-		name,
-		args: parseLaunchArgs(args)
-	};
-	if (name === "press") {
-		if (args.length === 0) fail("usage: rokit press <key> [key...]");
+	if (name === "wait-active") {
+		const appId = args[0];
+		if (!appId) fail("usage: rokit wait-active <app-id> [--timeout-ms <ms>]");
 		return {
+			appId,
 			name,
-			keys: args
+			timeoutMs: parseTimeoutOption(args.slice(1), `rokit ${name} <app-id>`)
 		};
 	}
+	if (name === "launch") return {
+		name,
+		args: parseLaunchArgs(args)
+	};
+	if (name === "press") return {
+		name,
+		args: parsePressArgs(args)
+	};
 	if (name === "query") {
 		const path = args[0];
 		if (!path) fail("usage: rokit query <ecp-path>");
@@ -274,6 +167,11 @@ const parseCommand = (argv) => {
 			path
 		};
 	}
+	if (name === "sgnodes") return { name };
+	if (name === "assert-node" || name === "wait-node") return {
+		name,
+		args: parseNodeCondition(name, args)
+	};
 	if (name === "screenshot") {
 		const outputPath = args[0];
 		if (!outputPath) fail("usage: rokit screenshot <output-path>");
@@ -292,6 +190,84 @@ const parseCommand = (argv) => {
 	}
 	return fail(`Unknown command: ${name ?? ""}`);
 };
+const parseNodeCondition = (commandName, args) => {
+	const [nodeName, condition, ...rest] = args;
+	if (!nodeName || !condition) return fail(`usage: rokit ${commandName} <node-name> <visible|hidden|absent|text|attr> [value] [--timeout-ms <ms>]`);
+	if (condition === "visible" || condition === "hidden" || condition === "absent") {
+		const timeoutMs = parseTimeoutOption(rest, `rokit ${commandName} <node-name> ${condition}`);
+		return {
+			expectation: { state: condition },
+			nodeName,
+			timeoutMs
+		};
+	}
+	if (condition === "text") {
+		const [text, ...optionArgs] = rest;
+		if (text === void 0) fail(`usage: rokit ${commandName} <node-name> text <expected-text>`);
+		return {
+			expectation: {
+				state: "visible",
+				text
+			},
+			nodeName,
+			timeoutMs: parseTimeoutOption(optionArgs, `rokit ${commandName} <node-name> text`)
+		};
+	}
+	if (condition === "attr") {
+		const [pair, ...optionArgs] = rest;
+		if (pair === void 0) fail(`usage: rokit ${commandName} <node-name> attr <name=value>`);
+		const equalsIndex = pair.indexOf("=");
+		if (equalsIndex <= 0) fail(`Invalid attr condition: ${pair}`);
+		return {
+			expectation: {
+				attribute: pair.slice(0, equalsIndex),
+				value: pair.slice(equalsIndex + 1)
+			},
+			nodeName,
+			timeoutMs: parseTimeoutOption(optionArgs, `rokit ${commandName} <node-name> attr`)
+		};
+	}
+	return fail(`Unknown node condition: ${condition}`);
+};
+const parsePressArgs = (args) => {
+	let delayMs = 0;
+	const keys = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--delay-ms") {
+			const value = args[index + 1];
+			if (!value) fail("usage: rokit press [--delay-ms <ms>] <key> [key...]");
+			delayMs = parsePositiveInteger(value, "delay");
+			index += 1;
+			continue;
+		}
+		if (arg?.startsWith("--")) fail(`Unknown press option: ${arg}`);
+		if (arg !== void 0) keys.push(arg);
+	}
+	if (keys.length === 0) fail("usage: rokit press [--delay-ms <ms>] <key> [key...]");
+	return {
+		delayMs,
+		keys
+	};
+};
+const parseTimeoutOption = (args, usagePrefix) => {
+	if (args.length === 0) return;
+	if (args.length !== 2 || args[0] !== "--timeout-ms") fail(`usage: ${usagePrefix} [--timeout-ms <ms>]`);
+	return parsePositiveInteger(args[1] ?? "", "timeout");
+};
+const parsePositiveInteger = (value, label) => {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed <= 0) fail(`Invalid ${label}: ${value}`);
+	return parsed;
+};
+const formatNodeCondition = ({ expectation, nodeName }) => {
+	if ("attribute" in expectation) return `${nodeName} attr ${expectation.attribute}=${expectation.value}`;
+	const suffix = expectation.text === void 0 ? "" : ` text=${expectation.text}`;
+	return `${nodeName} ${expectation.state}${suffix}`;
+};
+const sleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
 const parseLaunchArgs = (args) => {
 	const appId = args[0];
 	if (!appId) fail("usage: rokit launch <app-id> [--param key=value]");
@@ -318,9 +294,13 @@ usage:
   rokit check
   rokit device-info
   rokit active-app
+  rokit wait-active <app-id> [--timeout-ms <ms>]
   rokit launch <app-id> [--param key=value]
-  rokit press <key> [key...]
+  rokit press [--delay-ms <ms>] <key> [key...]
   rokit query <ecp-path>
+  rokit sgnodes
+  rokit assert-node <node-name> <visible|hidden|absent|text|attr> [value]
+  rokit wait-node <node-name> <visible|hidden|absent|text|attr> [value] [--timeout-ms <ms>]
   rokit screenshot <output-path>
   rokit install <zip-path>
   rokit --version

package/dist/roku-D-FxlWPE.mjs

@@ -0,0 +1,197 @@
+import * as rokuDeploy from "roku-deploy";
+import { basename, dirname, extname, resolve } from "node:path";
+//#region src/xml.ts
+const readXmlTag = (xml, tag) => {
+	return new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml)?.[1]?.trim();
+};
+const readXmlAttribute = (attributes, name) => {
+	return new RegExp(`${name}="([^"]*)"`).exec(attributes)?.[1];
+};
+const readActiveApp = (xml) => {
+	const match = /<app(?:\s+([^>]*))?>([^<]*)<\/app>/.exec(xml);
+	if (!match) throw new Error("active app response did not include an app node");
+	const attributes = match[1] ?? "";
+	return {
+		id: readXmlAttribute(attributes, "id") ?? "",
+		name: match[2]?.trim() ?? "",
+		type: readXmlAttribute(attributes, "type") ?? "",
+		version: readXmlAttribute(attributes, "version") ?? ""
+	};
+};
+//#endregion
+//#region src/scenegraph.ts
+const readNamedNodeAttributes = (xml, nodeName) => {
+	return new RegExp(`<[A-Za-z0-9]+\\b(?=[^>]*\\bname="${escapeRegExp(nodeName)}")([^>]*)>`).exec(xml)?.[1];
+};
+const readNamedNodeAttribute = (xml, nodeName, attributeName) => {
+	const attributes = readNamedNodeAttributes(xml, nodeName);
+	if (!attributes) return;
+	return readXmlAttribute(attributes, attributeName);
+};
+const isNamedNodeVisible = (xml, nodeName) => {
+	const attributes = readNamedNodeAttributes(xml, nodeName);
+	return attributes !== void 0 && !attributes.includes("visible=\"false\"");
+};
+const assertNamedNode = (xml, nodeName, expectation) => {
+	if ("attribute" in expectation) {
+		assertNamedNodeAttribute(xml, nodeName, expectation.attribute, expectation.value);
+		return;
+	}
+	assertNamedNodeState(xml, nodeName, expectation.state);
+	if (expectation.text !== void 0) assertNamedNodeText(xml, nodeName, expectation.text);
+};
+const assertNamedNodeState = (xml, nodeName, state) => {
+	const attributes = readNamedNodeAttributes(xml, nodeName);
+	if (state === "absent") {
+		if (attributes !== void 0) throw new Error(`expected SceneGraph node "${nodeName}" to be absent`);
+		return;
+	}
+	if (!attributes) throw new Error(`expected SceneGraph node "${nodeName}"`);
+	if (state === "visible" && attributes.includes("visible=\"false\"")) throw new Error(`expected SceneGraph node "${nodeName}" to be visible`);
+	if (state === "hidden" && !attributes.includes("visible=\"false\"")) throw new Error(`expected SceneGraph node "${nodeName}" to be hidden`);
+};
+const assertNamedNodeText = (xml, nodeName, expectedText) => {
+	const text = readNamedNodeAttribute(xml, nodeName, "text");
+	if (text !== expectedText) throw new Error(`expected "${nodeName}" text "${expectedText}", got "${text ?? "missing"}"`);
+};
+const assertNamedNodeAttribute = (xml, nodeName, attributeName, expectedValue) => {
+	const value = readNamedNodeAttribute(xml, nodeName, attributeName);
+	if (value !== expectedValue) throw new Error(`expected "${nodeName}" ${attributeName} "${expectedValue}", got "${value ?? "missing"}"`);
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+//#endregion
+//#region src/roku.ts
+const ecpPort = 8060;
+const remoteKeySet = new Set([
+	"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"
+]);
+const checkDevice = async (context) => {
+	const deviceInfo = await fetchText(context, "/query/device-info");
+	const installerStatus = await fetchInstallerStatus(context);
+	return {
+		ecp: `http://${context.target}:${ecpPort}`,
+		installerStatus,
+		model: readXmlTag(deviceInfo, "model-name") ?? "unknown model",
+		name: readXmlTag(deviceInfo, "friendly-device-name") ?? readXmlTag(deviceInfo, "friendlyName") ?? "unknown"
+	};
+};
+const getDeviceInfo = async (context) => await rokuDeploy.getDeviceInfo({
+	enhance: true,
+	host: context.target,
+	remotePort: ecpPort,
+	timeout: context.timeoutMs
+});
+const queryActiveApp = async (context) => readActiveApp(await fetchText(context, "/query/active-app"));
+const waitForActiveApp = async (context, appId, timeoutMs = 1e4) => {
+	const start = Date.now();
+	let lastApp;
+	while (Date.now() - start < timeoutMs) {
+		lastApp = await queryActiveApp(context);
+		if (lastApp.id === appId) return lastApp;
+		await sleep(500);
+	}
+	const last = lastApp ? `${lastApp.id} ${lastApp.name}` : "unknown";
+	throw new Error(`expected active app ${appId}, got ${last}`);
+};
+const launchApp = async (context, appId, params = /* @__PURE__ */ new Map()) => {
+	const url = ecpUrl(context, `/launch/${encodeURIComponent(appId)}`);
+	for (const [key, value] of params) url.searchParams.set(key, value);
+	await postOk(context, url);
+	return await waitForActiveApp(context, appId);
+};
+const pressKey = async (context, key) => {
+	validateRemoteKey(key);
+	await postOk(context, ecpUrl(context, `/keypress/${encodeURIComponent(key)}`));
+};
+const queryEcp = async (context, path) => await fetchText(context, path.startsWith("/") ? path : `/${path}`);
+const querySceneGraph = async (context) => await queryEcp(context, "/query/sgnodes/all");
+const assertSceneGraphNode = async (context, nodeName, expectation) => {
+	assertNamedNode(await querySceneGraph(context), nodeName, expectation);
+};
+const waitForSceneGraphNode = async (context, nodeName, expectation, timeoutMs = 3e4) => {
+	const start = Date.now();
+	let lastError;
+	while (Date.now() - start < timeoutMs) {
+		try {
+			await assertSceneGraphNode(context, nodeName, expectation);
+			return;
+		} catch (error) {
+			lastError = error instanceof Error ? error.message : String(error);
+		}
+		await sleep(500);
+	}
+	const suffix = lastError ? `; last observation: ${lastError}` : "";
+	throw new Error(`expected SceneGraph node "${nodeName}" to match condition${suffix}`);
+};
+const installPackage = async (context, zipPath) => {
+	const resolvedZip = resolve(zipPath);
+	const extension = extname(resolvedZip);
+	return (await rokuDeploy.publish({
+		host: context.target,
+		outDir: dirname(resolvedZip),
+		outFile: basename(resolvedZip, extension),
+		password: context.password,
+		rootDir: process.cwd(),
+		username: context.username
+	})).message;
+};
+const takeScreenshot = async (context, outputPath) => {
+	const resolvedOutput = resolve(outputPath);
+	const extension = extname(resolvedOutput);
+	return await rokuDeploy.takeScreenshot({
+		host: context.target,
+		outDir: dirname(resolvedOutput),
+		outFile: basename(resolvedOutput, extension),
+		password: context.password
+	});
+};
+const validateRemoteKey = (key) => {
+	if (key.startsWith("Lit_")) return;
+	if (!remoteKeySet.has(key)) throw new Error(`unsupported remote key: ${key}`);
+};
+const fetchInstallerStatus = async (context) => {
+	return (await fetch(`http://${context.target}`, { signal: AbortSignal.timeout(context.timeoutMs) })).status;
+};
+const fetchText = async (context, path) => {
+	const response = await fetch(ecpUrl(context, path), { signal: AbortSignal.timeout(context.timeoutMs) });
+	if (!response.ok) throw new Error(`GET ${path} returned HTTP ${response.status}`);
+	return await response.text();
+};
+const postOk = async (context, url) => {
+	const response = await fetch(url, {
+		method: "POST",
+		signal: AbortSignal.timeout(context.timeoutMs)
+	});
+	if (!response.ok) throw new Error(`POST ${url.pathname} returned HTTP ${response.status}`);
+};
+const ecpUrl = (context, path) => new URL(path, `http://${context.target}:${ecpPort}`);
+const sleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
+//#endregion
+export { readXmlTag as S, isNamedNodeVisible as _, launchApp as a, readActiveApp as b, queryEcp as c, validateRemoteKey as d, waitForActiveApp as f, assertNamedNodeText as g, assertNamedNodeState as h, installPackage as i, querySceneGraph as l, assertNamedNode as m, checkDevice as n, pressKey as o, waitForSceneGraphNode as p, getDeviceInfo as r, queryActiveApp as s, assertSceneGraphNode as t, takeScreenshot as u, readNamedNodeAttribute as v, readXmlAttribute as x, readNamedNodeAttributes as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",
@@ -27,18 +27,27 @@
   ],
   "type": "module",
   "sideEffects": false,
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "vp pack src/rokit.ts",
+    "build": "vp pack src/index.ts src/rokit.ts --dts",
     "check": "vp check .",
     "clean": "rm -rf .turbo coverage dist",
-    "prepack": "vp pack src/rokit.ts",
-    "smoke": "vp pack src/rokit.ts && node dist/rokit.mjs --version && node dist/rokit.mjs --help >/dev/null",
+    "hooks:install": "git config core.hooksPath .git-hooks",
+    "live:smoke": "vp pack src/index.ts src/rokit.ts --dts && node dist/rokit.mjs check",
+    "prepack": "vp pack src/index.ts src/rokit.ts --dts",
+    "smoke": "vp pack src/index.ts src/rokit.ts --dts && node dist/rokit.mjs --version && node dist/rokit.mjs --help >/dev/null",
     "test": "vp test --passWithNoTests",
     "typecheck": "tsc --noEmit",
-    "verify": "vp check . && tsc --noEmit && vp pack src/rokit.ts && vp test --passWithNoTests && npm pack --dry-run"
+    "verify": "vp check . && tsc --noEmit && vp pack src/index.ts src/rokit.ts --dts && vp test --passWithNoTests && npm pack --dry-run"
   },
   "dependencies": {
     "roku-deploy": "3.17.3"