@putdotio/rokit 1.7.0 → 2.0.1

package/dist/rokit.mjs

@@ -1,9 +1,33 @@
 #!/usr/bin/env node
-import { C as waitForMediaPlayerState, S as waitForActiveApp, T as waitForSceneGraphNode, a as installPackage, b as takeScreenshot, c as pressKey, d as queryMediaPlayer, h as querySceneGraph, i as getDeviceInfo, l as queryActiveApp, n as assertSceneGraphNode, r as checkDevice, s as launchApp, u as queryEcp } from "./roku-B61mpmWt.mjs";
+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 { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { existsSync, mkdirSync } from "node:fs";
-const envPath = join(join(process.cwd(), ".rokit"), ".env");
+import { dirname, isAbsolute, join, relative, resolve } 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);
 };
@@ -15,17 +39,41 @@ const loadEnv = () => ({
 });
 const requireTarget = (env) => {
 	const target = env.target?.trim();
-	if (!target) return fail("ROKIT_TARGET is not set");
+	if (!target) throw MissingTarget.make({});
 	return normalizeTarget(target);
 };
 const requirePassword = (env) => {
 	const password = env.password;
-	if (!password) return fail("ROKIT_PASSWORD is not set");
+	if (!password) throw MissingPassword.make({});
 	return password;
 };
-var RokitCliError = class extends Error {};
+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 new RokitCliError(message);
+	throw InvalidInput.make({ message });
 };
 const formatErrorMessage = (error) => {
 	if (error instanceof Error) return error.message;
@@ -41,38 +89,83 @@ const parseTimeout = (value) => {
 //#endregion
 //#region src/cli.ts
 const packageJson = createRequire(import.meta.url)("../package.json");
-const main = async (argv = process.argv.slice(2)) => {
+const mainEffect = Effect.fn("mainEffect")(function* (argv = process.argv.slice(2)) {
 	let outputMode = inferOutputMode(argv);
-	try {
-		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;
-		}
+	let fields = [];
+	yield* Effect.tryPromise({
+		try: async () => {
+			await runMain(argv, (mode) => {
+				outputMode = mode;
+			}, (nextFields) => {
+				fields = nextFields;
+			});
+		},
+		catch: normalizeError
+	}).pipe(Effect.catch((error) => Effect.sync(() => {
+		printError(outputMode, renderError(error), fields);
+		process.exitCode = 1;
+	})));
+});
+const runMain = async (argv, setOutputMode, setFields) => {
+	const options = parseGlobalOptions(argv);
+	const fields = options.fields;
+	setOutputMode(options.outputMode);
+	setFields(fields);
+	const firstArg = options.inputJson === void 0 ? options.args[0] : "input-json";
+	if (options.inputJson === void 0 && (!firstArg || firstArg === "--help" || firstArg === "-h")) {
+		printHelp();
+		return;
+	}
+	if (options.inputJson === void 0 && (firstArg === "--version" || firstArg === "-v")) {
+		console.log(packageJson.version);
+		return;
+	}
+	const command = parseCommand(options);
+	let context;
+	if (commandNeedsTarget(command, options.dryRun)) {
 		loadLocalEnv();
 		const env = loadEnv();
-		const target = requireTarget(env);
-		const result = await runCommand({
+		context = {
 			password: env.password,
-			target,
+			target: requireTarget(env),
 			timeoutMs: env.timeoutMs,
 			username: env.username
-		}, parseCommand(options.args));
-		printResult(options.outputMode, result);
-	} catch (error) {
-		printError(outputMode, formatErrorMessage(error));
-		process.exitCode = 1;
+		};
 	}
+	const result = await runCommand(context, command, options.dryRun);
+	printResult(options.outputMode, result, fields);
 };
-const runCommand = async (context, command) => {
+const runCommand = async (context, command, dryRun) => {
+	if (command.name === "describe") return {
+		command: command.name,
+		data: describeCli(),
+		status: "ok"
+	};
+	if (command.name === "discover") {
+		if (dryRun) return dryRunResult(command.name, { timeoutMs: command.timeoutMs ?? 3e3 });
+		const devices = await discoverRokuDevices(command.timeoutMs);
+		return {
+			command: command.name,
+			data: { devices },
+			message: devices.length === 0 ? "no Roku devices discovered" : devices.map((device) => `${device.target ?? "unknown"} ${device.location}`).join("\n"),
+			status: "ok"
+		};
+	}
+	if (command.name === "package") {
+		const outputPath = resolveFileOutputPath(command.outputPath, "package output path");
+		if (dryRun) return dryRunResult(command.name, { path: resolvePackageOutputPath(outputPath) });
+		const result = await packageChannel(outputPath);
+		return {
+			command: command.name,
+			data: result,
+			message: `package: ${result.path}`,
+			status: "ok"
+		};
+	}
+	if (dryRun && commandSupportsDryRun(command)) return dryRunResult(command.name, dryRunData(command));
+	const deviceContext = requireContext(context);
 	if (command.name === "check") {
-		const summary = await checkDevice(context);
+		const summary = await checkDevice(deviceContext);
 		return {
 			command: command.name,
 			data: summary,
@@ -86,11 +179,11 @@ const runCommand = async (context, command) => {
 	}
 	if (command.name === "device-info") return {
 		command: command.name,
-		data: await getDeviceInfo(context),
+		data: await getDeviceInfo(deviceContext),
 		status: "ok"
 	};
 	if (command.name === "active-app") {
-		const app = await queryActiveApp(context);
+		const app = await queryActiveApp(deviceContext);
 		return {
 			command: command.name,
 			data: app,
@@ -99,7 +192,7 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "media-player") {
-		const mediaPlayer = await queryMediaPlayer(context);
+		const mediaPlayer = await queryMediaPlayer(deviceContext);
 		return {
 			command: command.name,
 			data: mediaPlayer,
@@ -108,7 +201,7 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "wait-media-player") {
-		const mediaPlayer = await waitForMediaPlayerState(context, command.state, command.timeoutMs);
+		const mediaPlayer = await waitForMediaPlayerState(deviceContext, command.state, command.timeoutMs);
 		return {
 			command: command.name,
 			data: mediaPlayer,
@@ -117,7 +210,7 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "wait-active") {
-		const app = await waitForActiveApp(context, command.appId, command.timeoutMs);
+		const app = await waitForActiveApp(deviceContext, command.appId, command.timeoutMs);
 		return {
 			command: command.name,
 			data: app,
@@ -126,7 +219,11 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "launch") {
-		const app = await launchApp(context, command.args.appId, command.args.params);
+		if (dryRun) return dryRunResult(command.name, {
+			appId: command.args.appId,
+			params: Object.fromEntries(command.args.params)
+		});
+		const app = await launchApp(deviceContext, command.args.appId, command.args.params);
 		return {
 			command: command.name,
 			data: app,
@@ -135,24 +232,43 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "press") {
+		if (dryRun) return dryRunResult(command.name, {
+			delayMs: command.args.delayMs,
+			keys: command.args.keys,
+			maxAttempts: command.args.maxAttempts,
+			until: command.args.until ? formatNodeData(command.args.until) : void 0
+		});
 		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);
-			pressed.push(key);
+		let attempts = 0;
+		while (attempts < command.args.maxAttempts) {
+			attempts += 1;
+			for (const [index, key] of command.args.keys.entries()) {
+				if ((index > 0 || attempts > 1) && command.args.delayMs > 0) await sleep(command.args.delayMs);
+				await pressKey(deviceContext, key);
+				pressed.push(key);
+			}
+			if (!command.args.until) break;
+			try {
+				await assertSceneGraphNode(deviceContext, command.args.until.nodeName, command.args.until.expectation);
+				break;
+			} catch (error) {
+				if (attempts >= command.args.maxAttempts) throw error;
+			}
 		}
 		return {
 			command: command.name,
 			data: {
+				attempts,
 				delayMs: command.args.delayMs,
-				keys: pressed
+				keys: pressed,
+				until: command.args.until ? formatNodeData(command.args.until) : void 0
 			},
 			message: pressed.map((key) => `pressed: ${key}`).join("\n"),
 			status: "ok"
 		};
 	}
 	if (command.name === "query") {
-		const body = await queryEcp(context, command.path);
+		const body = await queryEcp(deviceContext, command.path);
 		return {
 			command: command.name,
 			data: {
@@ -164,7 +280,7 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "sgnodes") {
-		const body = await querySceneGraph(context);
+		const body = await querySceneGraph(deviceContext);
 		return {
 			command: command.name,
 			data: { body },
@@ -173,7 +289,7 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "assert-node") {
-		await assertSceneGraphNode(context, command.args.nodeName, command.args.expectation);
+		await assertSceneGraphNode(deviceContext, command.args.nodeName, command.args.expectation);
 		return {
 			command: command.name,
 			data: formatNodeData(command.args),
@@ -182,7 +298,7 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "wait-node") {
-		await waitForSceneGraphNode(context, command.args.nodeName, command.args.expectation, command.args.timeoutMs);
+		await waitForSceneGraphNode(deviceContext, command.args.nodeName, command.args.expectation, command.args.timeoutMs);
 		return {
 			command: command.name,
 			data: formatNodeData(command.args),
@@ -191,23 +307,59 @@ const runCommand = async (context, command) => {
 		};
 	}
 	if (command.name === "screenshot") {
-		const password = requirePassword(context);
-		mkdirSync(dirname(command.outputPath), { recursive: true });
-		const path = await takeScreenshot({
-			...context,
+		const path = resolveFileOutputPath(command.outputPath, "screenshot output path");
+		if (dryRun) return dryRunResult(command.name, { path });
+		const password = requirePassword(deviceContext);
+		mkdirSync(dirname(path), { recursive: true });
+		const screenshotPath = await takeScreenshot({
+			...deviceContext,
 			password
-		}, command.outputPath);
+		}, path);
+		return {
+			command: command.name,
+			data: { path: screenshotPath },
+			message: `screenshot: ${screenshotPath}`,
+			status: "ok"
+		};
+	}
+	if (command.name === "snapshot") {
+		const data = await collectSnapshot(deviceContext);
+		return observationResult(command.name, data);
+	}
+	if (command.name === "proof") {
+		const outputDir = resolveOutputPath(command.outputDir, "proof output directory");
+		if (dryRun) return dryRunResult(command.name, {
+			outputDir,
+			screenshot: command.screenshot
+		});
+		const data = await writeProof(deviceContext, outputDir, command.screenshot);
+		return {
+			command: command.name,
+			data,
+			...partialObservationMetadata(data.snapshot),
+			message: data.artifacts.map((artifact) => `${artifact.kind}: ${artifact.path}`).join("\n"),
+			status: "ok"
+		};
+	}
+	if (command.name === "wait-ready") {
+		const data = await waitForReady(deviceContext, command);
+		const failedObservations = data.sceneGraph.status === "failed" ? ["sceneGraph"] : [];
 		return {
 			command: command.name,
-			data: { path },
-			message: `screenshot: ${path}`,
+			data,
+			...failedObservations.length > 0 ? {
+				failedObservations,
+				partial: true
+			} : void 0,
+			message: `ready: active app ${data.activeApp.id}`,
 			status: "ok"
 		};
 	}
 	if (command.name === "install") {
-		const password = requirePassword(context);
+		if (dryRun) return dryRunResult(command.name, { zipPath: command.zipPath });
+		const password = requirePassword(deviceContext);
 		const message = await installPackage({
-			...context,
+			...deviceContext,
 			password
 		}, command.zipPath);
 		return {
@@ -217,13 +369,191 @@ const runCommand = async (context, command) => {
 			status: "ok"
 		};
 	}
-	throw new Error(`unsupported command: ${command.name}`);
+	throw new Error("unsupported command");
+};
+const requireContext = (context) => {
+	if (!context) return fail("ROKIT_TARGET is not set");
+	return context;
+};
+const dryRunResult = (command, data) => ({
+	command,
+	data,
+	dryRun: true,
+	message: `dry-run: ${command}`,
+	status: "ok"
+});
+const observe = async (read) => {
+	try {
+		return {
+			data: await read(),
+			status: "ok"
+		};
+	} catch (error) {
+		return {
+			error: { message: renderError(normalizeError(error)) },
+			status: "failed"
+		};
+	}
+};
+const collectSnapshot = async (context) => {
+	const sceneGraph = await observe(async () => await querySceneGraph(context));
+	const sceneGraphBody = sceneGraph.status === "ok" ? sceneGraph.data : void 0;
+	return {
+		activeApp: await observe(async () => await queryActiveApp(context)),
+		device: await observe(async () => await checkDevice(context)),
+		mediaPlayer: await observe(async () => await queryMediaPlayer(context)),
+		sceneGraph: sceneGraphBody === void 0 ? sceneGraph : {
+			data: {
+				failure: readSceneGraphFailure(sceneGraphBody),
+				status: readSceneGraphStatus(sceneGraphBody)
+			},
+			status: "ok"
+		}
+	};
+};
+const observationResult = (command, data) => ({
+	command,
+	data,
+	...partialObservationMetadata(data),
+	status: "ok"
+});
+const partialObservationMetadata = (snapshot) => {
+	const failedObservations = failedSnapshotObservations(snapshot);
+	return failedObservations.length === 0 ? {} : {
+		failedObservations,
+		partial: true
+	};
+};
+const failedSnapshotObservations = (snapshot) => {
+	const failures = [];
+	if (snapshot.activeApp.status === "failed") failures.push("activeApp");
+	if (snapshot.device.status === "failed") failures.push("device");
+	if (snapshot.mediaPlayer.status === "failed") failures.push("mediaPlayer");
+	if (snapshot.sceneGraph.status === "failed") failures.push("sceneGraph");
+	return failures;
+};
+const writeProof = async (context, outputDir, includeScreenshot) => {
+	mkdirSync(outputDir, { recursive: true });
+	const artifacts = [];
+	const writeJson = (name, value) => {
+		const path = `${outputDir}/${name}.json`;
+		writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+		artifacts.push({
+			kind: "json",
+			path
+		});
+		return path;
+	};
+	const snapshot = await collectSnapshot(context);
+	writeJson("summary", snapshot);
+	const sceneGraph = await observe(async () => await querySceneGraph(context));
+	if (sceneGraph.status === "ok") {
+		const path = `${outputDir}/sgnodes.xml`;
+		writeFileSync(path, sceneGraph.data);
+		artifacts.push({
+			kind: "xml",
+			path
+		});
+	}
+	writeJson("device-info", await observe(async () => await getDeviceInfo(context)));
+	writeJson("active-app", await observe(async () => await queryActiveApp(context)));
+	writeJson("media-player", await observe(async () => await queryMediaPlayer(context)));
+	if (includeScreenshot) {
+		const password = requirePassword(context);
+		const path = await takeScreenshot({
+			...context,
+			password
+		}, `${outputDir}/screenshot.png`);
+		artifacts.push({
+			kind: "screenshot",
+			path
+		});
+	}
+	return {
+		artifacts,
+		outputDir,
+		snapshot
+	};
+};
+const waitForReady = async (context, command) => {
+	const activeApp = await waitForActiveApp(context, command.appId, command.timeoutMs);
+	const sceneGraph = await observe(async () => querySceneGraph(context, {
+		attempts: 3,
+		requireComplete: true
+	}));
+	if (command.node) await waitForSceneGraphNode(context, command.node.nodeName, command.node.expectation, command.node.timeoutMs ?? command.timeoutMs);
+	return {
+		activeApp,
+		mediaPlayer: command.mediaState ? {
+			data: await waitForMediaPlayerState(context, command.mediaState, command.timeoutMs),
+			status: "ok"
+		} : await observe(async () => queryMediaPlayer(context)),
+		sceneGraph: sceneGraph.status === "ok" ? {
+			data: {
+				failure: readSceneGraphFailure(sceneGraph.data),
+				status: readSceneGraphStatus(sceneGraph.data)
+			},
+			status: "ok"
+		} : sceneGraph
+	};
+};
+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 dryRunData = (command) => {
+	if (command.name === "launch") return {
+		appId: command.args.appId,
+		params: Object.fromEntries(command.args.params)
+	};
+	if (command.name === "press") {
+		for (const key of command.args.keys) validateRemoteKey(key);
+		return {
+			delayMs: command.args.delayMs,
+			keys: command.args.keys,
+			maxAttempts: command.args.maxAttempts,
+			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 === "proof") return {
+		outputDir: resolveOutputPath(command.outputDir, "proof output directory"),
+		screenshot: command.screenshot
+	};
+	if (command.name === "package") return { path: resolveOutputPath(command.outputPath, "package output path") };
+	if (command.name === "install") return { zipPath: command.zipPath };
+	return {};
 };
 const parseGlobalOptions = (argv) => {
 	const args = [];
-	let outputMode = "text";
+	let dryRun = false;
+	let fields = [];
+	let inputJson;
+	let outputMode = defaultOutputMode();
 	for (let index = 0; index < argv.length; index += 1) {
 		const arg = argv[index];
+		if (arg === "--dry-run") {
+			dryRun = true;
+			continue;
+		}
+		if (arg === "--fields") {
+			const value = argv[index + 1];
+			if (!value) fail("usage: rokit [--fields field[,field...]] <command>");
+			fields = value.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
+			outputMode = "json";
+			index += 1;
+			continue;
+		}
+		if (arg === "--input-json") {
+			const value = argv[index + 1];
+			if (!value) fail("usage: rokit --input-json '<payload>'");
+			if (inputJson !== void 0) fail("usage: rokit --input-json '<payload>'");
+			inputJson = value;
+			outputMode = "json";
+			index += 1;
+			continue;
+		}
 		if (arg === "--json") {
 			outputMode = "json";
 			continue;
@@ -237,18 +567,27 @@ const parseGlobalOptions = (argv) => {
 		}
 		args.push(arg);
 	}
+	if (inputJson !== void 0 && args.length > 0) fail("usage: rokit --input-json '<payload>'");
 	return {
 		args,
+		dryRun,
+		fields,
+		inputJson,
 		outputMode
 	};
 };
 const inferOutputMode = (argv) => {
 	if (argv.includes("--json")) return "json";
-	return argv[argv.indexOf("--output") + 1] === "json" ? "json" : "text";
+	const outputIndex = argv.indexOf("--output");
+	if (argv[outputIndex + 1] === "json") return "json";
+	if (argv[outputIndex + 1] === "text") return "text";
+	if (argv.includes("--input-json") || argv.includes("--fields")) return "json";
+	return defaultOutputMode();
 };
-const printResult = (outputMode, result) => {
+const defaultOutputMode = () => process.stdout.isTTY ? "text" : "json";
+const printResult = (outputMode, result, fields) => {
 	if (outputMode === "json") {
-		console.log(JSON.stringify(result, null, 2));
+		console.log(JSON.stringify(applyFields(result, fields), null, 2));
 		return;
 	}
 	if (result.message !== void 0) {
@@ -257,7 +596,7 @@ const printResult = (outputMode, result) => {
 	}
 	console.log(JSON.stringify(result.data, null, 2));
 };
-const printError = (outputMode, message) => {
+const printError = (outputMode, message, _fields) => {
 	if (outputMode === "json") {
 		console.error(JSON.stringify({
 			error: { message },
@@ -267,9 +606,15 @@ const printError = (outputMode, message) => {
 	}
 	console.error(message);
 };
-const parseCommand = (argv) => {
-	const [name, ...args] = argv;
+const parseCommand = (options) => {
+	if (options.inputJson !== void 0) return parseInputJson(options.inputJson);
+	const [name, ...args] = options.args;
+	if (name === "describe") return { name };
 	if (name === "check") return { name };
+	if (name === "discover") return {
+		name,
+		timeoutMs: parseOptionalTimeout(args, "rokit discover")
+	};
 	if (name === "device-info") return { name };
 	if (name === "active-app") return { name };
 	if (name === "media-player") return { name };
@@ -282,6 +627,7 @@ const parseCommand = (argv) => {
 			timeoutMs: parseTimeoutOption(args.slice(1), "rokit wait-media-player <state>")
 		};
 	}
+	if (name === "wait-ready") return parseWaitReadyArgs(args);
 	if (name === "wait-active") {
 		const appId = args[0];
 		if (!appId) fail("usage: rokit wait-active <app-id> [--timeout-ms <ms>]");
@@ -302,6 +648,7 @@ const parseCommand = (argv) => {
 	if (name === "query") {
 		const path = args[0];
 		if (!path) fail("usage: rokit query <ecp-path>");
+		rejectUnsafeEcpPath(path);
 		return {
 			name,
 			path
@@ -320,6 +667,12 @@ const parseCommand = (argv) => {
 			outputPath
 		};
 	}
+	if (name === "snapshot") return { name };
+	if (name === "proof") return parseProofArgs(args);
+	if (name === "package") return {
+		name,
+		outputPath: parseOutputPath(args, "rokit package --out <zip-path>")
+	};
 	if (name === "install") {
 		const zipPath = args[0];
 		if (!zipPath) fail("usage: rokit install <zip-path>");
@@ -371,7 +724,10 @@ const parseNodeCondition = (commandName, args) => {
 };
 const parsePressArgs = (args) => {
 	let delayMs = 0;
+	let maxAttempts = 1;
+	let maxAttemptsWasProvided = false;
 	const keys = [];
+	let until;
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === "--delay-ms") {
@@ -381,15 +737,254 @@ const parsePressArgs = (args) => {
 			index += 1;
 			continue;
 		}
+		if (arg === "--max") {
+			const value = args[index + 1];
+			if (!value) fail("usage: rokit press [--delay-ms <ms>] [--until-node ... --max <count>] <key> [key...]");
+			maxAttempts = parsePositiveInteger(value, "max attempts");
+			maxAttemptsWasProvided = true;
+			index += 1;
+			continue;
+		}
+		if (arg === "--until-node") {
+			until = parseNodeCondition("press --until-node", args.slice(index + 1));
+			if (!maxAttemptsWasProvided) maxAttempts = 8;
+			break;
+		}
 		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
+		keys,
+		maxAttempts,
+		until
+	};
+};
+const parseOptionalTimeout = (args, usagePrefix) => args.length === 0 ? void 0 : parseTimeoutOption(args, usagePrefix);
+const parseOutputPath = (args, usage) => {
+	if (args.length === 1 && args[0] !== void 0 && !args[0].startsWith("--")) return args[0];
+	if (args.length === 2 && args[0] === "--out" && args[1] !== void 0) return args[1];
+	return fail(`usage: ${usage}`);
+};
+const parseProofArgs = (args) => {
+	let outputDir;
+	let screenshot = false;
+	const assignOutputDir = (nextOutputDir) => {
+		if (!nextOutputDir) fail("usage: rokit proof <output-dir> [--screenshot]");
+		if (outputDir !== void 0) fail("usage: rokit proof <output-dir> [--screenshot]");
+		outputDir = nextOutputDir;
+	};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--out") {
+			assignOutputDir(args[index + 1]);
+			index += 1;
+			continue;
+		}
+		if (arg === "--screenshot") {
+			screenshot = true;
+			continue;
+		}
+		if (arg?.startsWith("--")) fail(`Unknown proof option: ${arg}`);
+		assignOutputDir(arg);
+	}
+	if (!outputDir) return fail("usage: rokit proof <output-dir> [--screenshot]");
+	return {
+		name: "proof",
+		outputDir,
+		screenshot
+	};
+};
+const parseWaitReadyArgs = (args) => {
+	const appId = args[0];
+	if (!appId) return fail("usage: rokit wait-ready <app-id> [--media-state <state>] [--node ...] [--timeout-ms <ms>]");
+	let mediaState;
+	let node;
+	let timeoutMs;
+	for (let index = 1; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--media-state") {
+			mediaState = args[index + 1];
+			if (!mediaState) fail("usage: rokit wait-ready <app-id> --media-state <state>");
+			index += 1;
+			continue;
+		}
+		if (arg === "--timeout-ms") {
+			timeoutMs = parsePositiveInteger(args[index + 1] ?? "", "timeout");
+			index += 1;
+			continue;
+		}
+		if (arg === "--node") {
+			node = parseNodeCondition("wait-ready --node", args.slice(index + 1));
+			break;
+		}
+		fail(`Unknown wait-ready option: ${arg ?? ""}`);
+	}
+	return {
+		appId,
+		mediaState,
+		name: "wait-ready",
+		node,
+		timeoutMs: timeoutMs ?? node?.timeoutMs
+	};
+};
+const parseInputJson = (value) => {
+	const parsed = requireRecord(JSON.parse(value), "input JSON");
+	const command = readString(parsed, "command");
+	if (command === "describe") return { name: "describe" };
+	if (command === "discover") return {
+		name: "discover",
+		timeoutMs: readOptionalNumber(parsed, "timeoutMs")
+	};
+	if (command === "check" || command === "device-info" || command === "active-app") return { name: command };
+	if (command === "media-player" || command === "sgnodes" || command === "snapshot") return { name: command };
+	if (command === "wait-active") return {
+		appId: readString(parsed, "appId"),
+		name: "wait-active",
+		timeoutMs: readOptionalNumber(parsed, "timeoutMs")
+	};
+	if (command === "wait-media-player") return {
+		name: "wait-media-player",
+		state: readString(parsed, "state"),
+		timeoutMs: readOptionalNumber(parsed, "timeoutMs")
+	};
+	if (command === "wait-ready") return {
+		appId: readString(parsed, "appId"),
+		mediaState: readOptionalString(parsed, "mediaState"),
+		name: "wait-ready",
+		node: readOptionalNodeCondition(parsed, "node"),
+		timeoutMs: readOptionalNumber(parsed, "timeoutMs")
+	};
+	if (command === "launch") return {
+		args: {
+			appId: readString(parsed, "appId"),
+			params: readStringMap(parsed, "params")
+		},
+		name: "launch"
+	};
+	if (command === "press") {
+		const keys = readStringArray(parsed, "keys");
+		const until = readOptionalNodeCondition(parsed, "until");
+		if (keys.length === 0) fail("input JSON field must include at least one key: keys");
+		return {
+			args: {
+				delayMs: readOptionalNumber(parsed, "delayMs") ?? 0,
+				keys,
+				maxAttempts: readOptionalNumber(parsed, "maxAttempts") ?? (until === void 0 ? 1 : 8),
+				until
+			},
+			name: "press"
+		};
+	}
+	if (command === "query") {
+		const path = readString(parsed, "path");
+		rejectUnsafeEcpPath(path);
+		return {
+			name: "query",
+			path
+		};
+	}
+	if (command === "assert-node" || command === "wait-node") return {
+		args: {
+			expectation: readNodeExpectation(parsed),
+			nodeName: readString(parsed, "nodeName"),
+			timeoutMs: readOptionalNumber(parsed, "timeoutMs")
+		},
+		name: command
+	};
+	if (command === "screenshot") return {
+		name: "screenshot",
+		outputPath: readString(parsed, "outputPath")
+	};
+	if (command === "proof") return {
+		name: "proof",
+		outputDir: readString(parsed, "outputDir"),
+		screenshot: readOptionalBoolean(parsed, "screenshot") ?? false
+	};
+	if (command === "package") return {
+		name: "package",
+		outputPath: readString(parsed, "outputPath")
+	};
+	if (command === "install") return {
+		name: "install",
+		zipPath: readString(parsed, "zipPath")
+	};
+	return fail(`Unknown command: ${command}`);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const requireRecord = (value, label) => {
+	if (!isRecord(value)) return fail(`${label} must be an object`);
+	return value;
+};
+const readString = (record, key) => {
+	const value = record[key];
+	if (typeof value !== "string" || value.length === 0) return fail(`input JSON is missing string field: ${key}`);
+	return value;
+};
+const readOptionalString = (record, key) => {
+	const value = record[key];
+	if (value === void 0) return;
+	if (typeof value !== "string") return fail(`input JSON field must be a string: ${key}`);
+	return value;
+};
+const readOptionalBoolean = (record, key) => {
+	const value = record[key];
+	if (value === void 0) return;
+	if (typeof value !== "boolean") return fail(`input JSON field must be a boolean: ${key}`);
+	return value;
+};
+const readOptionalNumber = (record, key) => {
+	const value = record[key];
+	if (value === void 0) return;
+	if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) return fail(`input JSON field must be a positive integer: ${key}`);
+	return value;
+};
+const readStringArray = (record, key) => {
+	const value = 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 readStringMap = (record, key) => {
+	const value = record[key];
+	if (value === void 0) return /* @__PURE__ */ new Map();
+	if (!isRecord(value)) return fail(`input JSON field must be an object: ${key}`);
+	const params = /* @__PURE__ */ new Map();
+	for (const [paramKey, paramValue] of Object.entries(value)) {
+		if (typeof paramValue !== "string") return fail(`input JSON map values must be strings: ${key}`);
+		params.set(paramKey, paramValue);
+	}
+	return params;
+};
+const readOptionalNodeCondition = (record, key) => {
+	const value = record[key];
+	if (value === void 0) return;
+	if (!isRecord(value)) return fail(`input JSON field must be an object: ${key}`);
+	return {
+		expectation: readNodeExpectation(value),
+		nodeName: readString(value, "nodeName"),
+		timeoutMs: readOptionalNumber(value, "timeoutMs")
 	};
 };
+const readNodeExpectation = (record) => {
+	const expectation = record.expectation;
+	if (isRecord(expectation)) {
+		if (typeof expectation.attribute === "string" && typeof expectation.value === "string") return {
+			attribute: expectation.attribute,
+			value: expectation.value
+		};
+		const state = expectation.state;
+		if (state === "visible" || state === "hidden" || state === "absent") {
+			const text = expectation.text;
+			if (text !== void 0 && typeof text !== "string") return fail("input JSON node expectation text must be a string");
+			return text === void 0 ? { state } : {
+				state,
+				text
+			};
+		}
+	}
+	return fail("input JSON is missing a valid node expectation");
+};
 const parseTimeoutOption = (args, usagePrefix) => {
 	if (args.length === 0) return;
 	if (args.length !== 2 || args[0] !== "--timeout-ms") fail(`usage: ${usagePrefix} [--timeout-ms <ms>]`);
@@ -419,6 +1014,33 @@ const formatMediaPlayerMessage = (mediaPlayer) => {
 	].join(" ")}`;
 };
 const formatMaybeMs = (value) => value === void 0 ? "unknown" : `${value}ms`;
+const applyFields = (value, fields) => {
+	if (fields.length === 0) return value;
+	const output = {};
+	for (const field of fields) copyField(value, output, field.split("."));
+	preserveStatusMetadata(value, output);
+	return output;
+};
+const preserveStatusMetadata = (source, target) => {
+	if (!isRecord(source)) return;
+	for (const key of [
+		"status",
+		"partial",
+		"failedObservations"
+	]) if (key in source) target[key] = source[key];
+};
+const copyField = (source, target, path) => {
+	const [head, ...tail] = path;
+	if (!head || !isRecord(source) || !(head in source)) return;
+	if (tail.length === 0) {
+		target[head] = source[head];
+		return;
+	}
+	const child = target[head];
+	const childTarget = isRecord(child) ? child : {};
+	target[head] = childTarget;
+	copyField(source[head], childTarget, tail);
+};
 const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
@@ -441,18 +1063,125 @@ const parseLaunchArgs = (args) => {
 		params
 	};
 };
+const describeCli = () => ({
+	automation: {
+		dryRun: true,
+		inputJson: true,
+		nonTtyJsonDefault: true,
+		outputFields: true,
+		schemaIntrospection: true
+	},
+	commands: [
+		commandSchema("describe", "Print machine-readable command schemas.", false, false, []),
+		commandSchema("check", "Check ECP and developer installer reachability.", true, false, []),
+		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, []),
+		commandSchema("media-player", "Read parsed /query/media-player state.", true, false, []),
+		commandSchema("snapshot", "Read a compact state snapshot.", true, false, []),
+		commandSchema("proof", "Write reviewable state artifacts.", true, true, [argumentField("outputDir", "path", "Directory where proof artifacts are written."), optionField("screenshot", "boolean", "Include a developer screenshot.")]),
+		commandSchema("package", "Create a sideload ZIP from the current app root.", false, true, [optionField("outputPath", "path", "ZIP output path inside the current app root.", true)]),
+		commandSchema("install", "Publish an existing ZIP to a developer-enabled Roku.", true, true, [argumentField("zipPath", "path", "Existing sideload ZIP path.")]),
+		commandSchema("launch", "Launch an app by id with optional params.", true, true, [argumentField("appId", "string", "Roku application id."), optionField("params", "record<string,string>", "Launch parameters.", false, true)]),
+		commandSchema("press", "Send remote keys, optionally until a node condition matches.", true, true, [
+			argumentField("keys", "string[]", "Remote keys to send.", true, true),
+			optionField("delayMs", "positive-integer", "Delay between keys in milliseconds."),
+			optionField("maxAttempts", "positive-integer", "Maximum repeated attempts."),
+			optionField("until", "node-condition", "SceneGraph condition that stops the loop.")
+		]),
+		commandSchema("query", "Read a raw ECP path.", true, false, [argumentField("path", "ecp-path", "Raw ECP path without query string or fragment.")]),
+		commandSchema("sgnodes", "Read raw SceneGraph XML.", true, false, []),
+		commandSchema("assert-node", "Assert one SceneGraph node condition.", true, false, [...nodeConditionFields()], [...nodeConditionInputJsonFields()]),
+		commandSchema("wait-node", "Wait for a SceneGraph node condition.", true, false, [...nodeConditionFields(), optionField("timeoutMs", "positive-integer", "Wait timeout in milliseconds.")], [...nodeConditionInputJsonFields(), optionField("timeoutMs", "positive-integer", "Wait timeout in milliseconds.")]),
+		commandSchema("wait-active", "Wait for a foreground app id.", true, false, [argumentField("appId", "string", "Expected foreground Roku application id."), optionField("timeoutMs", "positive-integer", "Wait timeout in milliseconds.")]),
+		commandSchema("wait-media-player", "Wait for a media-player state.", true, false, [argumentField("state", "string", "Expected media-player state."), optionField("timeoutMs", "positive-integer", "Wait timeout in milliseconds.")]),
+		commandSchema("wait-ready", "Wait for active app plus optional node/media readiness.", true, false, [
+			argumentField("appId", "string", "Expected foreground Roku application id."),
+			optionField("mediaState", "string", "Optional media-player state to wait for."),
+			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.")])
+	],
+	globalOptions: [
+		globalField("json", "boolean", "Print structured JSON output."),
+		globalField("output", "json|text", "Select structured or human output.", false, ["json", "text"]),
+		globalField("dryRun", "boolean", "Validate mutating commands without side effects."),
+		globalField("fields", "field-mask", "Comma-separated JSON field mask for output trimming."),
+		globalField("inputJson", "json-object", "Command payload matching the described input schema.")
+	],
+	schemaVersion: 2
+});
+const commandSchema = (name, description, requiresTarget, mutates, parameters, inputJsonFields = parameters) => ({
+	description,
+	inputJson: {
+		fields: [{
+			description: "Command name.",
+			name: "command",
+			required: true,
+			type: "string",
+			values: [name]
+		}, ...inputJsonFields],
+		required: ["command", ...inputJsonFields.filter((field) => field.required).map((field) => field.name)]
+	},
+	mutates,
+	name,
+	parameters,
+	requiresTarget
+});
+const argumentField = (name, type, description, required = true, repeatable = false, values) => ({
+	description,
+	name,
+	repeatable,
+	required,
+	type,
+	values
+});
+const optionField = (name, type, description, required = false, repeatable = false, values) => ({
+	description,
+	name,
+	repeatable,
+	required,
+	type,
+	values
+});
+const globalField = (name, type, description, required = false, values) => ({
+	description,
+	name,
+	required,
+	type,
+	values
+});
+const nodeConditionFields = () => [
+	argumentField("nodeName", "string", "SceneGraph node name."),
+	argumentField("condition", "visible|hidden|absent|text|attr", "Expected node condition.", true, false, [
+		"visible",
+		"hidden",
+		"absent",
+		"text",
+		"attr"
+	]),
+	optionField("value", "string", "Text or attr name=value pair for text/attr conditions.")
+];
+const nodeConditionInputJsonFields = () => [argumentField("nodeName", "string", "SceneGraph node name."), argumentField("expectation", "node-expectation-object", "Expected node state, text, or attribute object.")];
 const printHelp = () => {
 	console.log(`rokit - Roku device harness helper
 
 usage:
+  rokit describe
   rokit check
+  rokit discover [--timeout-ms <ms>]
   rokit device-info
   rokit active-app
   rokit media-player
+  rokit snapshot
+  rokit proof <output-dir> [--screenshot]
+  rokit package --out <zip-path>
   rokit wait-active <app-id> [--timeout-ms <ms>]
   rokit wait-media-player <state> [--timeout-ms <ms>]
+  rokit wait-ready <app-id> [--media-state <state>] [--node <node-name> <condition> [value]] [--timeout-ms <ms>]
   rokit launch <app-id> [--param key=value]
-  rokit press [--delay-ms <ms>] <key> [key...]
+  rokit press [--delay-ms <ms>] [--max <count>] <key> [key...] [--until-node <node-name> <condition> [value]]
   rokit query <ecp-path>
   rokit sgnodes
   rokit assert-node <node-name> <visible|hidden|absent|text|attr> [value]
@@ -464,6 +1193,9 @@ usage:
 global options:
   --json
   --output json | text
+  --dry-run
+  --fields field[,field...]
+  --input-json '<payload>'
 
 environment:
   ROKIT_TARGET=<roku-ip>
@@ -476,6 +1208,6 @@ compatibility:
 };
 //#endregion
 //#region src/rokit.ts
-await main();
+NodeRuntime.runMain(mainEffect());
 //#endregion
 export {};