@putdotio/rokit 2.0.1 → 2.0.2

package/README.md

@@ -87,12 +87,14 @@ Common commands:
 | `sgnodes`                                          | Print the raw SceneGraph tree                      |
 | `assert-node` / `wait-node`                        | Check generic SceneGraph node state                |
 | `wait-active` / `wait-media-player` / `wait-ready` | Poll generic runtime readiness                     |
-| `screenshot <output-path>`                         | Save a developer screenshot                        |
+| `screenshot <output-path>`                         | Save a timestamped developer screenshot            |
 
 Mutating commands support `--dry-run` where the platform can validate without
 changing device or filesystem state. ECP paths reject query strings, fragments,
 traversal, backslashes, control characters, and percent-encoded path segments.
 Generated output paths must stay within the current working directory.
+Screenshots append a timestamp to the requested filename and report the actual
+path written, so repeated captures do not reuse cache-prone filenames.
 
 ## Library Use
 
@@ -137,7 +139,7 @@ await waitForSceneGraphAssertion(context, "player ready", (xml) => {
 - package, install, launch, deeplink params, and remote keypresses
 - raw ECP queries and parsed media-player state
 - SceneGraph state queries and named-node assertions
-- screenshots, snapshots, and proof artifacts
+- timestamped screenshots, snapshots, and proof artifacts
 
 Consumer app repos own product behavior: opening specific routes, asserting
 playback for real content, checking app-specific UI nodes, and generating review

package/dist/rokit.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 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, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, extname, 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";
@@ -307,7 +307,7 @@ const runCommand = async (context, command, dryRun) => {
 		};
 	}
 	if (command.name === "screenshot") {
-		const path = resolveFileOutputPath(command.outputPath, "screenshot output path");
+		const path = timestampOutputPath(resolveFileOutputPath(command.outputPath, "screenshot output path"));
 		if (dryRun) return dryRunResult(command.name, { path });
 		const password = requirePassword(deviceContext);
 		mkdirSync(dirname(path), { recursive: true });
@@ -463,7 +463,7 @@ const writeProof = async (context, outputDir, includeScreenshot) => {
 		const path = await takeScreenshot({
 			...context,
 			password
-		}, `${outputDir}/screenshot.png`);
+		}, timestampOutputPath(`${outputDir}/screenshot.png`));
 		artifacts.push({
 			kind: "screenshot",
 			path
@@ -475,6 +475,23 @@ const writeProof = async (context, outputDir, includeScreenshot) => {
 		snapshot
 	};
 };
+const timestampOutputPath = (path, date = /* @__PURE__ */ new Date()) => {
+	const extension = extname(path);
+	const name = basename(path, extension);
+	return join(dirname(path), `${name}-${formatTimestamp(date)}${extension}`);
+};
+const formatTimestamp = (date) => [
+	date.getFullYear().toString(),
+	padDatePart(date.getMonth() + 1),
+	padDatePart(date.getDate()),
+	"-",
+	padDatePart(date.getHours()),
+	padDatePart(date.getMinutes()),
+	padDatePart(date.getSeconds()),
+	"-",
+	padDatePart(date.getMilliseconds(), 3)
+].join("");
+const padDatePart = (value, length = 2) => value.toString().padStart(length, "0");
 const waitForReady = async (context, command) => {
 	const activeApp = await waitForActiveApp(context, command.appId, command.timeoutMs);
 	const sceneGraph = await observe(async () => querySceneGraph(context, {
@@ -516,7 +533,7 @@ const dryRunData = (command) => {
 			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 === "screenshot") return { path: timestampOutputPath(resolveFileOutputPath(command.outputPath, "screenshot output path")) };
 	if (command.name === "proof") return {
 		outputDir: resolveOutputPath(command.outputDir, "proof output directory"),
 		screenshot: command.screenshot
@@ -1101,7 +1118,7 @@ const describeCli = () => ({
 			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.")])
+		commandSchema("screenshot", "Write a timestamped developer screenshot.", true, true, [argumentField("outputPath", "path", "Screenshot base output path inside the current app root.")])
 	],
 	globalOptions: [
 		globalField("json", "boolean", "Print structured JSON output."),

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

@@ -19,12 +19,15 @@ repo.
 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,
+5. Screenshot commands append a timestamp to the requested filename. Use the
+   returned JSON `data.path` as the artifact path instead of assuming the input
+   path was written.
+6. 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
+7. 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
+8. Use `rokit press --until-node ...` for bounded navigation loops instead of
    arbitrary sleeps.
 
 ## Boundaries

package/package.json

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