@putdotio/rokit 1.6.0 → 2.0.0

package/dist/{roku-CXHAzYR-.mjs → roku-BxnS6Axs.mjs}

@@ -1,5 +1,6 @@
 import * as rokuDeploy from "roku-deploy";
-import { basename, dirname, extname, resolve } from "node:path";
+import { createSocket } from "node:dgram";
+import { basename, dirname, extname, isAbsolute, resolve } from "node:path";
 //#region src/xml.ts
 const readXmlTag = (xml, tag) => {
 	return new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml)?.[1]?.trim();
@@ -70,6 +71,9 @@ const isNamedNodeVisible = (xml, nodeName) => {
 	const attributes = readNamedNodeAttributes(xml, nodeName);
 	return attributes !== void 0 && !attributes.includes("visible=\"false\"");
 };
+const isCompleteSceneGraph = (xml) => !xml.includes("<All_Nodes>") || xml.includes("</sgnodes>") && (readSceneGraphStatus(xml).status !== void 0 || readSceneGraphFailure(xml) !== void 0);
+const escapeXmlAttribute = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+const sceneGraphContainsText = (xml, text) => xml.includes(escapeXmlAttribute(text));
 const assertSceneGraphNumberNear = (actual, expected, label, tolerance = 1) => {
 	if (actual === void 0 || Math.abs(actual - expected) > tolerance) throw new Error(`expected ${label} ${expected}, got ${actual ?? "missing"}`);
 };
@@ -158,6 +162,50 @@ const getDeviceInfo = async (context) => await rokuDeploy.getDeviceInfo({
 	timeout: context.timeoutMs
 });
 const queryActiveApp = async (context) => readActiveApp(await fetchText(context, "/query/active-app"));
+const discoverRokuDevices = async (timeoutMs = 3e3) => await new Promise((resolveDevices, reject) => {
+	const socket = createSocket("udp4");
+	const devices = /* @__PURE__ */ new Map();
+	const request = [
+		"M-SEARCH * HTTP/1.1",
+		"HOST: 239.255.255.250:1900",
+		"MAN: \"ssdp:discover\"",
+		"MX: 1",
+		"ST: roku:ecp",
+		"",
+		""
+	].join("\r\n");
+	const finish = () => {
+		socket.close();
+		resolveDevices([...devices.values()]);
+	};
+	const timer = setTimeout(finish, timeoutMs);
+	socket.on("message", (message) => {
+		const headers = readSsdpHeaders(message.toString("utf8"));
+		const location = headers.get("location");
+		if (!location) return;
+		devices.set(location, {
+			location,
+			server: headers.get("server"),
+			target: readLocationTarget(location),
+			usn: headers.get("usn")
+		});
+	});
+	socket.on("error", (error) => {
+		clearTimeout(timer);
+		socket.close();
+		reject(error);
+	});
+	socket.bind(() => {
+		socket.setBroadcast(true);
+		socket.send(Buffer.from(request), 1900, "239.255.255.250", (error) => {
+			if (error) {
+				clearTimeout(timer);
+				socket.close();
+				reject(error);
+			}
+		});
+	});
+});
 const waitForActiveApp = async (context, appId, timeoutMs = 1e4) => {
 	const start = Date.now();
 	let lastApp;
@@ -188,9 +236,23 @@ 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 queryEcp = async (context, path) => {
+	const safePath = validateEcpPath(path);
+	return await fetchText(context, safePath.startsWith("/") ? safePath : `/${safePath}`);
+};
 const queryMediaPlayerXml = async (context) => await queryEcp(context, "/query/media-player");
 const queryMediaPlayer = async (context) => readMediaPlayerInfo(await queryMediaPlayerXml(context));
+const queryMediaPlayerXmlSafe = async (context) => {
+	try {
+		return await queryMediaPlayerXml(context);
+	} catch {
+		return;
+	}
+};
+const queryMediaPlayerSafe = async (context) => {
+	const xml = await queryMediaPlayerXmlSafe(context);
+	return xml === void 0 ? void 0 : readMediaPlayerInfo(xml);
+};
 const readMediaPlayerInfo = (xml) => {
 	const playerAttributes = /<player(?:\s+([^>]*))?>/.exec(xml)?.[1] ?? "";
 	const formatAttributes = /<format(?:\s+([^>]*))?\/>/.exec(xml)?.[1] ?? "";
@@ -216,7 +278,12 @@ const readMediaPlayerInfo = (xml) => {
 const readMediaPlayerState = (xml) => readMediaPlayerInfo(xml).state;
 const readMediaPlayerPositionMs = (xml) => readMediaPlayerInfo(xml).positionMs;
 const readMediaPlayerContainer = (xml) => readMediaPlayerInfo(xml).container;
-const isActiveMediaPlayerState = (state) => state === "buffer" || state === "pause" || state === "play";
+const isActiveMediaPlayerState = (state) => state === "buffer" || state === "buffering" || state === "pause" || state === "play";
+const assertMediaPlayerContainer = async (context, expectedContainer) => {
+	const mediaPlayer = await queryMediaPlayer(context);
+	if (mediaPlayer.container !== expectedContainer) throw new Error(`expected media-player container ${expectedContainer}, got ${mediaPlayer.container ?? "unknown"}`);
+	return mediaPlayer;
+};
 const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4) => {
 	const start = Date.now();
 	let lastState;
@@ -237,14 +304,22 @@ const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4)
 };
 const querySceneGraph = async (context, options = {}) => {
 	const attempts = options.attempts ?? 1;
+	const requireComplete = options.requireComplete ?? false;
 	const retryDelayMs = options.retryDelayMs ?? 500;
+	let lastXml = "";
 	let lastError;
-	for (let attempt = 0; attempt < attempts; attempt += 1) try {
-		return await queryEcp(context, "/query/sgnodes/all");
-	} catch (error) {
-		lastError = error;
+	for (let attempt = 0; attempt < attempts; attempt += 1) {
+		try {
+			const xml = await queryEcp(context, "/query/sgnodes/all");
+			if (!requireComplete || isCompleteSceneGraph(xml)) return xml;
+			lastXml = xml;
+		} catch (error) {
+			lastError = error;
+			lastXml = "";
+		}
 		if (attempt < attempts - 1) await sleep(retryDelayMs);
 	}
+	if (lastXml !== "") throw new Error("SceneGraph query returned incomplete XML");
 	throw new Error(`SceneGraph query failed: ${formatErrorMessage(lastError)}`);
 };
 const assertSceneGraphNode = async (context, nodeName, expectation) => {
@@ -305,6 +380,39 @@ const takeScreenshot = async (context, outputPath) => {
 		password: context.password
 	});
 };
+const packageChannel = async (outputPath, rootDir = process.cwd()) => {
+	const options = packageOptions(outputPath, rootDir);
+	await rokuDeploy.createPackage(options);
+	return { path: rokuDeploy.getOutputZipFilePath(options) };
+};
+const resolvePackageOutputPath = (outputPath, rootDir = process.cwd()) => {
+	const options = packageOptions(outputPath, rootDir);
+	return rokuDeploy.getOutputZipFilePath(options);
+};
+const packageOptions = (outputPath, rootDir = process.cwd()) => {
+	const resolvedRoot = resolve(rootDir);
+	const resolvedOutput = isAbsolute(outputPath) ? resolve(outputPath) : resolve(resolvedRoot, outputPath);
+	return {
+		outDir: dirname(resolvedOutput),
+		outFile: basename(resolvedOutput),
+		rootDir: resolvedRoot
+	};
+};
+const validateEcpPath = (path) => {
+	rejectUnsafeInput(path, "ECP path");
+	if (path.includes("\\")) throw new Error("ECP path must not include backslashes");
+	if (path.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(path)) throw new Error("ECP path must be device-relative");
+	if (path.includes("?") || path.includes("#")) throw new Error("ECP path must not include query strings or fragments");
+	if (/(^|[/\\])\.\.($|[/\\])/.test(path)) throw new Error("ECP path must not include path traversal");
+	if (/%(?:2e|2f|5c)/i.test(path)) throw new Error("ECP path must not include percent-encoded path segments");
+	return path;
+};
+const rejectUnsafeInput = (value, label) => {
+	if ([...value].some((character) => {
+		const code = character.charCodeAt(0);
+		return code < 32 || code === 127;
+	})) throw new Error(`${label} contains control characters`);
+};
 const validateRemoteKey = (key) => {
 	if (key.startsWith("Lit_")) return;
 	if (!remoteKeySet.has(key)) throw new Error(`unsupported remote key: ${key}`);
@@ -359,5 +467,21 @@ const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+const readSsdpHeaders = (text) => {
+	const headers = /* @__PURE__ */ new Map();
+	for (const line of text.split(/\r?\n/)) {
+		const separator = line.indexOf(":");
+		if (separator <= 0) continue;
+		headers.set(line.slice(0, separator).trim().toLowerCase(), line.slice(separator + 1).trim());
+	}
+	return headers;
+};
+const readLocationTarget = (location) => {
+	try {
+		return new URL(location).hostname;
+	} catch {
+		return;
+	}
+};
 //#endregion
-export { parseSceneGraphNumberList as A, readXmlTag as B, assertNamedNode as C, assertNamedNodeTranslation as D, assertNamedNodeText as E, readNamedNodeTranslation as F, readSceneGraphFailure as I, readSceneGraphStatus as L, readNamedNodeAttributes as M, readNamedNodeBounds as N, assertSceneGraphNumberNear as O, readNamedNodeNumber as P, readActiveApp as R, waitForSceneGraphNode as S, assertNamedNodeState as T, takeScreenshot as _, isActiveMediaPlayerState as a, waitForMediaPlayerState as b, queryActiveApp as c, queryMediaPlayerXml as d, querySceneGraph as f, readMediaPlayerState as g, readMediaPlayerPositionMs as h, installPackage as i, readNamedNodeAttribute as j, isNamedNodeVisible as k, queryEcp as l, readMediaPlayerInfo as m, checkDevice as n, launchApp as o, readMediaPlayerContainer as p, getDeviceInfo as r, pressKey as s, assertSceneGraphNode as t, queryMediaPlayer as u, validateRemoteKey as v, assertNamedNodeSize as w, waitForSceneGraphAssertion as x, waitForActiveApp as y, readXmlAttribute as z };
+export { assertNamedNode as A, readNamedNodeAttribute as B, takeScreenshot as C, waitForMediaPlayerState as D, waitForActiveApp as E, assertSceneGraphNumberNear as F, readSceneGraphFailure as G, readNamedNodeBounds as H, escapeXmlAttribute as I, readActiveApp as J, readSceneGraphStatus as K, isCompleteSceneGraph as L, assertNamedNodeState as M, assertNamedNodeText as N, waitForSceneGraphAssertion as O, assertNamedNodeTranslation as P, isNamedNodeVisible as R, resolvePackageOutputPath as S, validateRemoteKey as T, readNamedNodeNumber as U, readNamedNodeAttributes as V, readNamedNodeTranslation as W, readXmlTag as X, readXmlAttribute as Y, querySceneGraph as _, getDeviceInfo as a, readMediaPlayerPositionMs as b, launchApp as c, queryActiveApp as d, queryEcp as f, queryMediaPlayerXmlSafe as g, queryMediaPlayerXml as h, discoverRokuDevices as i, assertNamedNodeSize as j, waitForSceneGraphNode as k, packageChannel as l, queryMediaPlayerSafe as m, assertSceneGraphNode as n, installPackage as o, queryMediaPlayer as p, sceneGraphContainsText as q, checkDevice as r, isActiveMediaPlayerState as s, assertMediaPlayerContainer as t, pressKey as u, readMediaPlayerContainer as v, validateEcpPath as w, readMediaPlayerState as x, readMediaPlayerInfo as y, parseSceneGraphNumberList as z };

package/docs/DISTRIBUTION.md

@@ -0,0 +1,60 @@
+# Distribution
+
+`rokit` is a public npm package published as `@putdotio/rokit`.
+
+## Local Contract
+
+The release path starts with the repo-local verification command:
+
+```bash
+pnpm verify
+```
+
+`verify` runs formatting/lint checks, TypeScript, package bundling, tests, and an npm pack dry run. GitHub Actions calls this same command before release.
+
+## Continuous Release
+
+Merges to `main` are considered publishable. The CI workflow runs:
+
+1. `verify` on pull requests and `main` pushes.
+2. semantic-release on `main` after `verify` passes.
+
+semantic-release analyzes conventional commits, publishes to npm, creates GitHub Releases, and writes release metadata when needed.
+
+## Release Credentials
+
+The release job uses the `release` GitHub Environment with `deployment: false`.
+
+Required protected inputs:
+
+- `PUTIO_RELEASE_BOT_CLIENT_ID` as a repository or Environment variable
+- `PUTIO_RELEASE_BOT_PRIVATE_KEY` as an Environment secret
+
+The npm package uses Trusted Publishing from GitHub Actions. On npm, configure owner `putdotio`, repository `rokit`, workflow `ci.yml`, and Environment named `release` for the package.
+
+During the `@semantic-release/npm` publish step, npm detects the GitHub OIDC identity, mints short-lived publish credentials, and publishes provenance for the release job.
+
+Release writes use the `putio-release-bot` installation token. The default `GITHUB_TOKEN` remains read-only, and the release-bot remote is configured only after dependencies are installed.
+
+## Package Contents
+
+The npm package includes `dist`, `README.md`, `docs`, `examples`, `AGENTS.md`,
+`CONTRIBUTING.md`, and `SECURITY.md`. The docs and generic live probe are
+included so agents consuming the package can inspect readiness, distribution,
+security, and generic Roku proof mechanics without cloning extra private
+context.
+
+## Release Smoke
+
+After a release, confirm the tag and package are visible:
+
+```bash
+gh release list --repo putdotio/rokit --limit 5
+npm view @putdotio/rokit version
+```
+
+Live Roku behavior is not required for npm release. Real-device checks are local/manual because they require a developer-enabled Roku:
+
+```bash
+ROKIT_TARGET=<roku-ip> pnpm live:smoke
+```

package/docs/READINESS.md

@@ -0,0 +1,80 @@
+# Agent Readiness
+
+Status: current as of 2026-05-17
+
+`rokit` is a CLI/package repo. There is no long-running app to boot; readiness is based on deterministic package verification plus optional live Roku proof.
+
+## Grade
+
+Overall: B+
+
+| Dimension  | Status | Evidence                                                                                                                                                                                 | Gap                                     |
+| ---------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| bootable   | pass   | `pnpm smoke` builds the CLI and checks `--version` plus `--help`                                                                                                                         | no server boot surface, by design       |
+| testable   | pass   | `pnpm verify` runs TypeScript, bundle, unit tests, and npm pack dry run                                                                                                                  | live Roku checks require local hardware |
+| observable | pass   | CLI commands print active app, device info, raw ECP state, SceneGraph XML, snapshots, proof bundles, screenshots, compact assertion failures, and JSON output by default in non-TTY runs | no CI hardware lane                     |
+| verifiable | pass   | CI runs `pnpm verify`; `pnpm live:smoke` proves a configured Roku responds; `pnpm live:probe` packages, installs, launches, drives, asserts, screenshots, and proofs a generic channel   | no CI hardware lane                     |
+
+## Layers
+
+- Boot: `pnpm smoke`, `rokit describe`
+- Smoke: `pnpm smoke`, `rokit check`
+- Interact: `rokit press`, `rokit launch`, `rokit query`, `rokit sgnodes`
+- E2e: `pnpm live:probe` for a configured developer-enabled Roku
+- Enforce: GitHub Actions `verify`, optional `.git-hooks/pre-push`
+- Observe: ECP responses, SceneGraph XML, `rokit snapshot`, `rokit proof`, screenshots, concise command output
+- Isolate: `.rokit/` and `.env` stay local per worktree
+
+## Agent-Facing CLI Contract
+
+- The CLI entrypoint runs through Effect's Node runtime, and expected CLI
+  failures are schema-backed errors rendered without stack traces.
+- `rokit describe` exposes the machine-readable command surface, parameters,
+  JSON payload fields, and global options without a Roku target.
+- Non-TTY command output defaults to JSON. Use `--output text` when a human
+  transcript is required.
+- `--input-json` lets agents provide typed command payloads without translating
+  everything into flags.
+- `--fields` trims JSON output for context-window control.
+- `--dry-run` validates mutating commands without touching a device or writing
+  files.
+- ECP paths and generated output paths are hardened against common agent
+  mistakes: query strings, fragments, traversal, backslashes, control
+  characters, encoded path segments, and writes outside the current app root.
+
+## Setup For Agents
+
+```bash
+pnpm install
+pnpm verify
+```
+
+`pnpm install` runs the local Effect source setup outside CI only. When `CI` is
+set to any non-empty value, `scripts/prepare-effect.sh` exits without cloning
+`.repos/effect` so install, pack, publish, and CI/CD workspaces stay predictable.
+
+Optional local hook:
+
+```bash
+pnpm hooks:install
+```
+
+Optional live smoke:
+
+```bash
+ROKIT_TARGET=<roku-ip> pnpm live:smoke
+```
+
+Full local live probe:
+
+```bash
+cp .env.example .env
+# Fill ROKIT_TARGET and ROKIT_PASSWORD.
+pnpm live:probe
+```
+
+`pnpm live:probe` reads `.env` and `.env.local`, accepts `ROKU_DEV_TARGET` and
+`ROKU_DEV_PASSWORD` as fallbacks, copies `examples/live-probe-channel` into
+`.rokit/live-probe/app`, packages it, installs it into the Roku developer slot,
+launches `dev`, checks generic SceneGraph labels, sends `Info Back`, and writes
+proof artifacts to `.rokit/live-probe/artifacts`.

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

@@ -0,0 +1,40 @@
+---
+name: rokit-harness
+description: Use rokit as a generic Roku harness adapter for packaging, installing, launching, key input, ECP/SceneGraph/media-player observation, readiness waits, screenshots, and proof bundles.
+---
+
+# rokit Harness
+
+Use this skill when a repo consumes `@putdotio/rokit` for Roku device harness
+work. Keep `rokit` generic and put app journeys, product selectors, fixture
+names, content IDs, account state, and product assertions in the consumer app
+repo.
+
+## Workflow
+
+1. Run `rokit describe` to inspect the command surface instead of guessing
+   flags or `--input-json` payload fields.
+2. Use `--dry-run` before mutating commands such as `package`, `install`,
+   `launch`, `press`, `screenshot`, or `proof`.
+3. Prefer structured output. In automation, rely on the non-TTY JSON default or
+   pass `--json` explicitly.
+4. Use `--fields` to keep observations small when only a few values are needed.
+5. For live proof, use `rokit snapshot` for a quick state read,
+   `rokit proof <output-dir>` for review artifacts, or `pnpm live:probe` in the
+   rokit repo for the full generic package/install/launch/input/proof probe.
+6. Use `rokit wait-ready <app-id>` after launch when the app can race ECP or
+   SceneGraph readiness.
+7. Use `rokit press --until-node ...` for bounded navigation loops instead of
+   arbitrary sleeps.
+
+## Boundaries
+
+- Device IPs, developer passwords, screenshots, packages, and proof bundles stay
+  local or ignored.
+- `rokit` can assert generic Roku and SceneGraph state. Consumer repos own
+  product routes, screen names when product-specific, playback/content
+  expectations, and review narratives.
+- ECP query paths must be plain paths. Do not include query strings, fragments,
+  traversal, backslashes, or encoded path segments.
+- The local Effect source setup is skipped whenever `CI` is set. Do not make CI,
+  install, pack, or publish flows depend on cloning `.repos/effect`.

package/examples/live-probe-channel/components/MainScene.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<component name="MainScene" extends="Scene">
+  <children>
+    <Rectangle
+      id="background"
+      width="1280"
+      height="720"
+      color="0x101820FF" />
+    <Label
+      id="title"
+      text="Rokit Live Probe"
+      translation="[120, 140]"
+      width="1040"
+      height="80"
+      horizAlign="center"
+      vertAlign="center" />
+    <Label
+      id="status"
+      text="Install, launch, input, and proof OK"
+      translation="[120, 250]"
+      width="1040"
+      height="60"
+      horizAlign="center"
+      vertAlign="center" />
+  </children>
+</component>

package/examples/live-probe-channel/manifest

@@ -0,0 +1,5 @@
+title=Rokit Live Probe
+major_version=1
+minor_version=0
+build_version=1
+ui_resolutions=hd

package/examples/live-probe-channel/source/main.brs

@@ -0,0 +1,14 @@
+sub Main()
+  screen = CreateObject("roSGScreen")
+  port = CreateObject("roMessagePort")
+  screen.SetMessagePort(port)
+  screen.CreateScene("MainScene")
+  screen.Show()
+
+  while true
+    msg = Wait(0, port)
+    if Type(msg) = "roSGScreenEvent" and msg.IsScreenClosed() then
+      return
+    end if
+  end while
+end sub

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",
@@ -22,8 +22,13 @@
     "rokit": "dist/rokit.mjs"
   },
   "files": [
+    "AGENTS.md",
+    "CONTRIBUTING.md",
     "dist",
-    "README.md"
+    "docs",
+    "examples",
+    "README.md",
+    "SECURITY.md"
   ],
   "type": "module",
   "sideEffects": false,
@@ -43,17 +48,22 @@
     "clean": "rm -rf .turbo coverage dist",
     "hooks:install": "git config core.hooksPath .git-hooks",
     "live:smoke": "vp pack src/index.ts src/rokit.ts --dts && node dist/rokit.mjs check",
+    "live:probe": "scripts/live-probe.sh",
+    "prepare": "./scripts/prepare-effect.sh",
     "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",
+    "test": "vp pack src/index.ts src/rokit.ts --dts && vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit",
-    "verify": "vp check . && tsc --noEmit && vp pack src/index.ts src/rokit.ts --dts && vp test --passWithNoTests && npm pack --dry-run"
+    "verify": "vp check . && tsc --noEmit && vp run test && npm pack --dry-run"
   },
   "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.66",
+    "effect": "4.0.0-beta.66",
     "roku-deploy": "3.17.3"
   },
   "devDependencies": {
-    "@types/node": "^25.7.0",
+    "@effect/vitest": "4.0.0-beta.66",
+    "@types/node": "^24.12.4",
     "typescript": "^6.0.2",
     "vite-plus": "^0.1.20",
     "vitest": "^4.1.6"