@putdotio/rokit 1.2.0 → 1.4.0

package/README.md

@@ -42,12 +42,19 @@ 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
+pnpm exec rokit --json active-app
 ```
 
 App-specific scenario scripts can also import the generic helpers:
 
 ```ts
-import { assertSceneGraphNode, pressKey, querySceneGraph, type RokuContext } from "@putdotio/rokit";
+import {
+  assertSceneGraphNode,
+  pressKey,
+  querySceneGraph,
+  readNamedNodeTranslation,
+  type RokuContext,
+} from "@putdotio/rokit";
 
 const target = process.env.ROKIT_TARGET;
 
@@ -62,8 +69,9 @@ const context: RokuContext = {
 };
 
 await pressKey(context, "Info");
+const xml = await querySceneGraph(context, { attempts: 3 });
 await assertSceneGraphNode(context, "videoPlayerScreen", { state: "visible" });
-await querySceneGraph(context, { attempts: 3 });
+console.log(readNamedNodeTranslation(xml, "videoPlayerScreen"));
 ```
 
 ## Commands
@@ -84,6 +92,16 @@ rokit install <zip-path>
 rokit --version
 ```
 
+Global options:
+
+```bash
+rokit --json <command>
+rokit --output json <command>
+```
+
+JSON mode wraps command output as `{ "status": "ok", "command": "...", ... }`
+and reports failures as `{ "status": "failed", "error": { "message": "..." } }`.
+
 - `check` confirms the Roku ECP endpoint responds and the developer installer
   is reachable.
 - `device-info` prints enhanced Roku device metadata as JSON.
@@ -130,6 +148,7 @@ tokens, and app-specific media identifiers do not belong in git.
 - remote keypresses
 - raw ECP queries
 - SceneGraph state queries and named-node assertions
+- SceneGraph attribute, numeric geometry, bounds, and translation readers
 - screenshots
 
 App repositories should keep their own scenario commands for product behavior,

package/dist/index.d.mts

@@ -2,6 +2,8 @@ import * as rokuDeploy from "roku-deploy";
 
 //#region src/scenegraph.d.ts
 type NodeState = "absent" | "hidden" | "visible";
+type SceneGraphBounds = readonly [x: number, y: number, width: number, height: number];
+type SceneGraphPoint = readonly [x: number, y: number];
 type NodeExpectation = {
   readonly state: NodeState;
   readonly text?: string;
@@ -11,10 +13,14 @@ type NodeExpectation = {
 };
 declare const readNamedNodeAttributes: (xml: string, nodeName: string) => string | undefined;
 declare const readNamedNodeAttribute: (xml: string, nodeName: string, attributeName: string) => string | undefined;
+declare const readNamedNodeNumber: (xml: string, nodeName: string, attributeName: string) => number | undefined;
+declare const readNamedNodeBounds: (xml: string, nodeName: string) => SceneGraphBounds | undefined;
+declare const readNamedNodeTranslation: (xml: string, nodeName: string) => SceneGraphPoint | 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;
+declare const parseSceneGraphNumberList: (value: string) => number[];
 //#endregion
 //#region src/xml.d.ts
 type ActiveApp = {
@@ -64,4 +70,4 @@ declare const takeScreenshot: (context: RokuContext & {
 }, outputPath: string) => Promise<string>;
 declare const validateRemoteKey: (key: string) => void;
 //#endregion
-export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };
+export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphBounds, type SceneGraphPoint, assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +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-DxlYPbY1.mjs";
-export { assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };
+import { C as readNamedNodeTranslation, E as readXmlTag, S as readNamedNodeNumber, T as readXmlAttribute, _ as isNamedNodeVisible, a as launchApp, b as readNamedNodeAttributes, 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 parseSceneGraphNumberList, w as readActiveApp, x as readNamedNodeBounds, y as readNamedNodeAttribute } from "./roku-7hiM97p0.mjs";
+export { assertNamedNode, assertNamedNodeState, assertNamedNodeText, assertSceneGraphNode, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/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-DxlYPbY1.mjs";
+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-7hiM97p0.mjs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";
@@ -23,9 +23,9 @@ const requirePassword = (env) => {
 	if (!password) return fail("ROKIT_PASSWORD is not set");
 	return password;
 };
+var RokitCliError = class extends Error {};
 const fail = (message) => {
-	console.error(message);
-	process.exit(1);
+	throw new RokitCliError(message);
 };
 const formatErrorMessage = (error) => {
 	if (error instanceof Error) return error.message;
@@ -42,100 +42,212 @@ const parseTimeout = (value) => {
 //#region src/cli.ts
 const packageJson = createRequire(import.meta.url)("../package.json");
 const main = async (argv = process.argv.slice(2)) => {
-	const firstArg = argv[0];
-	if (!firstArg || firstArg === "--help" || firstArg === "-h") {
-		printHelp();
-		return;
-	}
-	if (firstArg === "--version" || firstArg === "-v") {
-		console.log(packageJson.version);
-		return;
-	}
-	loadLocalEnv();
-	const env = loadEnv();
-	const target = requireTarget(env);
-	const context = {
-		password: env.password,
-		target,
-		timeoutMs: env.timeoutMs,
-		username: env.username
-	};
-	const command = parseCommand(argv);
+	let outputMode = inferOutputMode(argv);
 	try {
-		await runCommand(context, command);
+		const options = parseGlobalOptions(argv);
+		outputMode = options.outputMode;
+		const firstArg = options.args[0];
+		if (!firstArg || firstArg === "--help" || firstArg === "-h") {
+			printHelp();
+			return;
+		}
+		if (firstArg === "--version" || firstArg === "-v") {
+			console.log(packageJson.version);
+			return;
+		}
+		loadLocalEnv();
+		const env = loadEnv();
+		const target = requireTarget(env);
+		const result = await runCommand({
+			password: env.password,
+			target,
+			timeoutMs: env.timeoutMs,
+			username: env.username
+		}, parseCommand(options.args));
+		printResult(options.outputMode, result);
 	} catch (error) {
-		fail(formatErrorMessage(error));
+		printError(outputMode, formatErrorMessage(error));
+		process.exitCode = 1;
 	}
 };
 const runCommand = async (context, command) => {
 	if (command.name === "check") {
 		const summary = await checkDevice(context);
-		console.log(`device: ${summary.name} (${summary.model})`);
-		console.log(`ecp: ${summary.ecp}`);
-		console.log(`developer installer HTTP status: ${summary.installerStatus}`);
-		return;
-	}
-	if (command.name === "device-info") {
-		console.log(JSON.stringify(await getDeviceInfo(context), null, 2));
-		return;
+		return {
+			command: command.name,
+			data: summary,
+			message: [
+				`device: ${summary.name} (${summary.model})`,
+				`ecp: ${summary.ecp}`,
+				`developer installer HTTP status: ${summary.installerStatus}`
+			].join("\n"),
+			status: "ok"
+		};
 	}
+	if (command.name === "device-info") return {
+		command: command.name,
+		data: await getDeviceInfo(context),
+		status: "ok"
+	};
 	if (command.name === "active-app") {
 		const app = await queryActiveApp(context);
-		console.log(`active app: ${app.id} ${app.name} ${app.version}`.trim());
-		return;
+		return {
+			command: command.name,
+			data: app,
+			message: `active app: ${app.id} ${app.name} ${app.version}`.trim(),
+			status: "ok"
+		};
 	}
 	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;
+		return {
+			command: command.name,
+			data: app,
+			message: `active app: ${app.id} ${app.name} ${app.version}`.trim(),
+			status: "ok"
+		};
 	}
 	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;
+		return {
+			command: command.name,
+			data: app,
+			message: `launched: ${app.id} ${app.name} ${app.version}`.trim(),
+			status: "ok"
+		};
 	}
 	if (command.name === "press") {
+		const pressed = [];
 		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}`);
+			pressed.push(key);
 		}
-		return;
+		return {
+			command: command.name,
+			data: {
+				delayMs: command.args.delayMs,
+				keys: pressed
+			},
+			message: pressed.map((key) => `pressed: ${key}`).join("\n"),
+			status: "ok"
+		};
 	}
 	if (command.name === "query") {
-		console.log(await queryEcp(context, command.path));
-		return;
+		const body = await queryEcp(context, command.path);
+		return {
+			command: command.name,
+			data: {
+				body,
+				path: command.path
+			},
+			message: body,
+			status: "ok"
+		};
 	}
 	if (command.name === "sgnodes") {
-		console.log(await querySceneGraph(context));
-		return;
+		const body = await querySceneGraph(context);
+		return {
+			command: command.name,
+			data: { body },
+			message: body,
+			status: "ok"
+		};
 	}
 	if (command.name === "assert-node") {
 		await assertSceneGraphNode(context, command.args.nodeName, command.args.expectation);
-		console.log(`asserted node: ${formatNodeCondition(command.args)}`);
-		return;
+		return {
+			command: command.name,
+			data: formatNodeData(command.args),
+			message: `asserted node: ${formatNodeCondition(command.args)}`,
+			status: "ok"
+		};
 	}
 	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;
+		return {
+			command: command.name,
+			data: formatNodeData(command.args),
+			message: `matched node: ${formatNodeCondition(command.args)}`,
+			status: "ok"
+		};
 	}
 	if (command.name === "screenshot") {
 		const password = requirePassword(context);
 		mkdirSync(dirname(command.outputPath), { recursive: true });
-		console.log(`screenshot: ${await takeScreenshot({
+		const path = await takeScreenshot({
 			...context,
 			password
-		}, command.outputPath)}`);
-		return;
+		}, command.outputPath);
+		return {
+			command: command.name,
+			data: { path },
+			message: `screenshot: ${path}`,
+			status: "ok"
+		};
 	}
 	if (command.name === "install") {
 		const password = requirePassword(context);
-		console.log(await installPackage({
+		const message = await installPackage({
 			...context,
 			password
-		}, command.zipPath));
+		}, command.zipPath);
+		return {
+			command: command.name,
+			data: { message },
+			message,
+			status: "ok"
+		};
 	}
+	throw new Error(`unsupported command: ${command.name}`);
+};
+const parseGlobalOptions = (argv) => {
+	const args = [];
+	let outputMode = "text";
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === "--json") {
+			outputMode = "json";
+			continue;
+		}
+		if (arg === "--output") {
+			const value = argv[index + 1];
+			if (value !== "json" && value !== "text") fail("usage: rokit [--json|--output json|--output text] <command>");
+			outputMode = value === "json" ? "json" : "text";
+			index += 1;
+			continue;
+		}
+		args.push(arg);
+	}
+	return {
+		args,
+		outputMode
+	};
+};
+const inferOutputMode = (argv) => {
+	if (argv.includes("--json")) return "json";
+	return argv[argv.indexOf("--output") + 1] === "json" ? "json" : "text";
+};
+const printResult = (outputMode, result) => {
+	if (outputMode === "json") {
+		console.log(JSON.stringify(result, null, 2));
+		return;
+	}
+	if (result.message !== void 0) {
+		console.log(result.message);
+		return;
+	}
+	console.log(JSON.stringify(result.data, null, 2));
+};
+const printError = (outputMode, message) => {
+	if (outputMode === "json") {
+		console.error(JSON.stringify({
+			error: { message },
+			status: "failed"
+		}, null, 2));
+		return;
+	}
+	console.error(message);
 };
 const parseCommand = (argv) => {
 	const [name, ...args] = argv;
@@ -265,6 +377,11 @@ const formatNodeCondition = ({ expectation, nodeName }) => {
 	const suffix = expectation.text === void 0 ? "" : ` text=${expectation.text}`;
 	return `${nodeName} ${expectation.state}${suffix}`;
 };
+const formatNodeData = ({ expectation, nodeName, timeoutMs }) => ({
+	expectation,
+	nodeName,
+	timeoutMs
+});
 const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
@@ -305,6 +422,10 @@ usage:
   rokit install <zip-path>
   rokit --version
 
+global options:
+  --json
+  --output json | text
+
 environment:
   ROKIT_TARGET=<roku-ip>
   ROKIT_PASSWORD=<developer-mode-password>

package/dist/{roku-DxlYPbY1.mjs → roku-7hiM97p0.mjs}

@@ -28,6 +28,36 @@ const readNamedNodeAttribute = (xml, nodeName, attributeName) => {
 	if (!attributes) return;
 	return readXmlAttribute(attributes, attributeName);
 };
+const readNamedNodeNumber = (xml, nodeName, attributeName) => {
+	const value = readNamedNodeAttribute(xml, nodeName, attributeName);
+	if (value !== void 0) {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+	if (attributeName !== "width" && attributeName !== "height") return;
+	const bounds = readNamedNodeBounds(xml, nodeName);
+	if (!bounds) return;
+	return attributeName === "width" ? bounds[2] : bounds[3];
+};
+const readNamedNodeBounds = (xml, nodeName) => {
+	const bounds = readNamedNodeAttribute(xml, nodeName, "bounds");
+	if (!bounds) return;
+	const parts = parseSceneGraphNumberList(bounds);
+	if (parts.length < 4) return;
+	return [
+		parts[0],
+		parts[1],
+		parts[2],
+		parts[3]
+	];
+};
+const readNamedNodeTranslation = (xml, nodeName) => {
+	const translation = readNamedNodeAttribute(xml, nodeName, "translation");
+	if (!translation) return;
+	const parts = parseSceneGraphNumberList(translation);
+	if (parts.length < 2) return;
+	return [parts[0], parts[1]];
+};
 const isNamedNodeVisible = (xml, nodeName) => {
 	const attributes = readNamedNodeAttributes(xml, nodeName);
 	return attributes !== void 0 && !attributes.includes("visible=\"false\"");
@@ -59,6 +89,7 @@ const assertNamedNodeAttribute = (xml, nodeName, attributeName, expectedValue) =
 	if (value !== expectedValue) throw new Error(`expected "${nodeName}" ${attributeName} "${expectedValue}", got "${value ?? "missing"}"`);
 };
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const parseSceneGraphNumberList = (value) => value.replace(/[[\]{}]/g, "").split(",").map((part) => Number(part.trim())).filter((part) => Number.isFinite(part));
 //#endregion
 //#region src/roku.ts
 const ecpPort = 8060;
@@ -227,4 +258,4 @@ const sleep = (ms) => new Promise((resolve) => {
 });
 const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#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 };
+export { readNamedNodeTranslation as C, readXmlTag as E, readNamedNodeNumber as S, readXmlAttribute as T, isNamedNodeVisible as _, launchApp as a, readNamedNodeAttributes 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, parseSceneGraphNumberList as v, readActiveApp as w, readNamedNodeBounds as x, readNamedNodeAttribute as y };

package/package.json

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