@putdotio/rokit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) put.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+  <p>
+    <img src="https://static.put.io/images/putio-boncuk.png" width="72">
+  </p>
+
+  <h1>rokit</h1>
+
+  <p>A tiny CLI companion for Roku device harness work.</p>
+
+  <p>
+    <a href="https://github.com/putdotio/rokit/actions/workflows/ci.yml?query=branch%3Amain" style="text-decoration:none;"><img src="https://img.shields.io/github/actions/workflow/status/putdotio/rokit/ci.yml?branch=main&style=flat&label=ci&colorA=000000&colorB=000000" alt="CI"></a>
+    <a href="https://www.npmjs.com/package/@putdotio/rokit" style="text-decoration:none;"><img src="https://img.shields.io/npm/v/%40putdotio%2Frokit?style=flat&label=npm&logo=npm&colorA=000000&colorB=000000" alt="npm version"></a>
+    <a href="https://github.com/putdotio/rokit/blob/main/LICENSE" style="text-decoration:none;"><img src="https://img.shields.io/github/license/putdotio/rokit?style=flat&label=license&colorA=000000&colorB=000000" alt="License"></a>
+  </p>
+</div>
+
+## Install
+
+```bash
+pnpm add -D @putdotio/rokit
+```
+
+`rokit` wraps Roku platform primitives for live-device proof loops. It does not
+own app-specific journeys, content IDs, credentials, or product assertions.
+
+## Usage
+
+Create `.rokit/.env` or export environment variables in the app repo:
+
+```bash
+ROKIT_TARGET=<roku-ip>
+ROKIT_PASSWORD=<developer-mode-password>
+```
+
+Then run:
+
+```bash
+pnpm exec rokit check
+pnpm exec rokit launch dev
+pnpm exec rokit press Down Select
+pnpm exec rokit query /query/active-app
+pnpm exec rokit screenshot artifacts/live/player.png
+```
+
+## Commands
+
+```bash
+rokit check
+rokit device-info
+rokit active-app
+rokit launch <app-id> [--param key=value]
+rokit press <key> [key...]
+rokit query <ecp-path>
+rokit screenshot <output-path>
+rokit install <zip-path>
+rokit --version
+```
+
+- `check` confirms the Roku ECP endpoint responds and the developer installer
+  is reachable.
+- `device-info` prints enhanced Roku device metadata as JSON.
+- `active-app` prints the foreground app.
+- `launch` opens an app and waits until it is active. Use repeated `--param`
+  values for deeplink parameters.
+- `press` sends Roku remote keys through ECP.
+- `query` prints a raw ECP response such as `/query/sgnodes/all`.
+- `screenshot` saves a developer screenshot. It requires `ROKIT_PASSWORD`.
+- `install` publishes an existing ZIP through `roku-deploy`. It requires
+  `ROKIT_PASSWORD`.
+
+## Environment
+
+```bash
+ROKIT_TARGET=<roku-ip>
+ROKIT_PASSWORD=<developer-mode-password>
+ROKIT_USERNAME=rokudev
+ROKIT_TIMEOUT_MS=10000
+```
+
+`ROKU_DEV_TARGET` and `ROKU_DEV_PASSWORD` are accepted as fallbacks for app
+repos that already use Roku dev naming.
+
+Keep `.rokit/` local. Device IPs, Developer Mode passwords, signing keys, user
+tokens, and app-specific media identifiers do not belong in git.
+
+## Boundaries
+
+`rokit` is the generic Roku harness layer:
+
+- device info
+- install/publish
+- launch and deeplink parameters
+- remote keypresses
+- raw ECP queries
+- screenshots
+
+App repositories should keep their own scenario commands for product behavior,
+such as opening a specific route, asserting playback state, generating review
+HTML, or checking app-specific UI nodes.
+
+## Docs
+
+- [Contributing](./CONTRIBUTING.md)
+- [Security](./SECURITY.md)
+
+## Repo Internals
+
+- [Agent guide](./AGENTS.md)
+
+## License
+
+[MIT](./LICENSE)

package/dist/rokit.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+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);
+};
+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) return fail("ROKIT_TARGET is not set");
+	return normalizeTarget(target);
+};
+const requirePassword = (env) => {
+	const password = env.password;
+	if (!password) return fail("ROKIT_PASSWORD is not set");
+	return password;
+};
+const fail = (message) => {
+	console.error(message);
+	process.exit(1);
+};
+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 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);
+	try {
+		await runCommand(context, command);
+	} catch (error) {
+		fail(formatErrorMessage(error));
+	}
+};
+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;
+	}
+	if (command.name === "active-app") {
+		const app = await queryActiveApp(context);
+		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) {
+			await pressKey(context, key);
+			console.log(`pressed: ${key}`);
+		}
+		return;
+	}
+	if (command.name === "query") {
+		console.log(await queryEcp(context, command.path));
+		return;
+	}
+	if (command.name === "screenshot") {
+		const password = requirePassword(context);
+		mkdirSync(dirname(command.outputPath), { recursive: true });
+		console.log(`screenshot: ${await takeScreenshot({
+			...context,
+			password
+		}, command.outputPath)}`);
+		return;
+	}
+	if (command.name === "install") {
+		const password = requirePassword(context);
+		console.log(await installPackage({
+			...context,
+			password
+		}, command.zipPath));
+	}
+};
+const parseCommand = (argv) => {
+	const [name, ...args] = 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...]");
+		return {
+			name,
+			keys: args
+		};
+	}
+	if (name === "query") {
+		const path = args[0];
+		if (!path) fail("usage: rokit query <ecp-path>");
+		return {
+			name,
+			path
+		};
+	}
+	if (name === "screenshot") {
+		const outputPath = args[0];
+		if (!outputPath) fail("usage: rokit screenshot <output-path>");
+		return {
+			name,
+			outputPath
+		};
+	}
+	if (name === "install") {
+		const zipPath = args[0];
+		if (!zipPath) fail("usage: rokit install <zip-path>");
+		return {
+			name,
+			zipPath
+		};
+	}
+	return fail(`Unknown command: ${name ?? ""}`);
+};
+const parseLaunchArgs = (args) => {
+	const appId = args[0];
+	if (!appId) fail("usage: rokit launch <app-id> [--param key=value]");
+	const params = /* @__PURE__ */ new Map();
+	for (let index = 1; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg !== "--param") fail(`Unknown launch option: ${arg ?? ""}`);
+		const pair = args[index + 1];
+		if (!pair) fail("usage: rokit launch <app-id> [--param key=value]");
+		const equalsIndex = pair.indexOf("=");
+		if (equalsIndex <= 0) fail(`Invalid launch param: ${pair}`);
+		params.set(pair.slice(0, equalsIndex), pair.slice(equalsIndex + 1));
+		index += 1;
+	}
+	return {
+		appId,
+		params
+	};
+};
+const printHelp = () => {
+	console.log(`rokit - Roku device harness helper
+
+usage:
+  rokit check
+  rokit device-info
+  rokit active-app
+  rokit launch <app-id> [--param key=value]
+  rokit press <key> [key...]
+  rokit query <ecp-path>
+  rokit screenshot <output-path>
+  rokit install <zip-path>
+  rokit --version
+
+environment:
+  ROKIT_TARGET=<roku-ip>
+  ROKIT_PASSWORD=<developer-mode-password>
+  ROKIT_USERNAME=rokudev
+  ROKIT_TIMEOUT_MS=10000
+
+compatibility:
+  ROKU_DEV_TARGET and ROKU_DEV_PASSWORD are accepted as fallbacks.`);
+};
+//#endregion
+//#region src/rokit.ts
+await main();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@putdotio/rokit",
+  "version": "1.0.0",
+  "description": "A tiny CLI companion for Roku device harness work.",
+  "keywords": [
+    "cli",
+    "harness",
+    "roku",
+    "tv"
+  ],
+  "homepage": "https://github.com/putdotio/rokit#readme",
+  "bugs": {
+    "url": "https://github.com/putdotio/rokit/issues"
+  },
+  "license": "MIT",
+  "author": "put.io <devs@put.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/putdotio/rokit.git"
+  },
+  "bin": {
+    "rokit": "dist/rokit.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack src/rokit.ts",
+    "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",
+    "test": "vp test --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "verify": "vp check . && tsc --noEmit && vp pack src/rokit.ts && vp test --passWithNoTests && npm pack --dry-run"
+  },
+  "dependencies": {
+    "roku-deploy": "3.17.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.2",
+    "vite-plus": "^0.1.20",
+    "vitest": "^4.1.6"
+  },
+  "engines": {
+    "node": ">=24.14.0 <25"
+  },
+  "packageManager": "pnpm@11.0.0"
+}