@putdotio/taizn 1.12.0 → 1.13.0

package/README.md

@@ -57,6 +57,9 @@ taizn profile
 taizn package
 taizn install
 taizn run
+taizn tv doctor
+taizn tv doctor --json
+taizn tv doctor --connect --json
 taizn tv info
 taizn tv info --json
 taizn tv pair
@@ -80,9 +83,10 @@ proof output. `profile` imports
 `package` builds and signs a `.wgt`. `install` packages and sideloads it.
 `run` launches the configured variant application on the target. `tv` commands use
 Samsung's websocket remote-control API to inspect a TV,
-pair for a remote token, and send remote-control key presses. Add `--json` to
-`tv info` for a structured TV capability snapshot, or to `tv press` for a
-structured key-sequence receipt. See
+diagnose remote-control readiness, pair for a remote token, and send remote-control
+key presses. Add `--json` to `tv doctor` for structured host/token/connection
+diagnostics, to `tv info` for a structured TV capability snapshot, or to
+`tv press` for a structured key-sequence receipt. See
 [Samsung TV Remote](./docs/TV_REMOTE.md) for pairing, environment, and limits.
 `tv press` accepts one key or a sequence of keys.
 

package/dist/taizn.mjs

@@ -484,6 +484,54 @@ const sendSamsungTvKeys = Effect.fn("sendSamsungTvKeys")(function* (env, keys, p
 	}
 	yield* Console.log(keys.length === 1 ? `Sent Samsung TV remote key: ${keys[0]}` : `Sent Samsung TV remote keys: ${keys.join(", ")}`);
 });
+const diagnoseSamsungTvRemote = Effect.fn("diagnoseSamsungTvRemote")(function* (env, doctorOptions = {}) {
+	const stateRead = yield* readRemoteStateDiagnostic();
+	const state = stateRead.state;
+	const targetHost = hostFromTarget(env.target);
+	const host = env.tvHost ?? state?.host ?? targetHost;
+	const hostSource = valueSource(env.tvHost, state?.host, targetHost);
+	const token = env.tvToken ?? state?.token;
+	const tokenSource = valueSource(env.tvToken, state?.token, void 0);
+	const remoteOptions = host ? {
+		host,
+		name: env.tvName ?? state?.name ?? DEFAULT_REMOTE_NAME,
+		port: env.tvPort ?? state?.port ?? DEFAULT_REMOTE_PORT,
+		protocol: env.tvProtocol ?? state?.protocol ?? DEFAULT_REMOTE_PROTOCOL,
+		timeoutMs: env.tvTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+		token
+	} : void 0;
+	const info = yield* readInfoDiagnostic(host, env.tvInfoPort ?? TV_INFO_PORT, remoteOptions?.timeoutMs);
+	const connection = yield* readRemoteConnectionDiagnostic(remoteOptions, doctorOptions);
+	const result = {
+		host,
+		hostSource,
+		info,
+		remote: {
+			connection,
+			name: remoteOptions?.name ?? env.tvName ?? DEFAULT_REMOTE_NAME,
+			port: remoteOptions?.port ?? env.tvPort ?? state?.port ?? DEFAULT_REMOTE_PORT,
+			protocol: remoteOptions?.protocol ?? env.tvProtocol ?? state?.protocol ?? DEFAULT_REMOTE_PROTOCOL,
+			target: remoteOptions ? remoteTarget(remoteOptions) : void 0,
+			timeoutMs: remoteOptions?.timeoutMs ?? env.tvTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+			tokenConfigured: Boolean(token),
+			tokenSource
+		},
+		state: stateRead.diagnostic,
+		target: env.target
+	};
+	if (doctorOptions.json) {
+		yield* Console.log(JSON.stringify(result));
+		return;
+	}
+	yield* Console.log(`Samsung TV doctor: ${host ?? "missing host"}`);
+	yield* Console.log(`host_source: ${hostSource}`);
+	yield* Console.log(`info: ${info.ok ? `ok ${info.name}` : `failed ${info.error.type}`}`);
+	yield* Console.log(`remote: ${result.remote.target ?? "missing"}`);
+	yield* Console.log(`token_configured: ${result.remote.tokenConfigured ? "yes" : "no"}`);
+	yield* Console.log(`remote_state: ${result.state.status}`);
+	if (connection.tested) yield* Console.log(`remote_connect: ${connection.ok ? "ok" : `failed ${connection.error.type}`}`);
+	else yield* Console.log(`remote_connect: skipped (${connection.reason})`);
+});
 const showSamsungTvInfo = Effect.fn("showSamsungTvInfo")(function* (env, infoOptions = {}) {
 	const options = yield* resolveRemoteOptions(env);
 	const info = yield* fetchSamsungTvInfo(options.host, {
@@ -582,6 +630,33 @@ const saveRemoteState = Effect.fn("saveRemoteState")(function* (options) {
 		path: paths.remoteStatePath
 	})));
 });
+const readRemoteStateDiagnostic = Effect.fn("readRemoteStateDiagnostic")(function* () {
+	const paths = yield* getPaths();
+	return yield* readRemoteState().pipe(Effect.match({
+		onFailure: (error) => ({ diagnostic: {
+			error: diagnosticError(error),
+			path: paths.remoteStatePath,
+			status: "error",
+			tokenConfigured: false
+		} }),
+		onSuccess: (state) => state ? {
+			diagnostic: {
+				host: state.host,
+				name: state.name,
+				path: paths.remoteStatePath,
+				port: state.port,
+				protocol: state.protocol,
+				status: "valid",
+				tokenConfigured: true
+			},
+			state
+		} : { diagnostic: {
+			path: paths.remoteStatePath,
+			status: "missing",
+			tokenConfigured: false
+		} }
+	}));
+});
 const connectRemote = Effect.fn("connectRemote")(function* (options, sequence) {
 	return yield* Effect.tryPromise({
 		try: () => connectRemotePromise(options, sequence),
@@ -683,6 +758,66 @@ const fetchSamsungTvInfo = Effect.fn("fetchSamsungTvInfo")(function* (host, opti
 	});
 	return yield* Schema.decodeUnknownEffect(TvInfo)(json, { errors: "all" }).pipe(Effect.mapError((error) => TvRemoteProtocolError.make({ details: error.message })));
 });
+const readInfoDiagnostic = Effect.fn("readInfoDiagnostic")(function* (host, port, timeoutMs) {
+	if (!host) return {
+		error: diagnosticError(MissingTvRemoteHost.make({})),
+		ok: false,
+		port
+	};
+	return yield* fetchSamsungTvInfo(host, {
+		port,
+		timeoutMs
+	}).pipe(Effect.match({
+		onFailure: (error) => ({
+			error: diagnosticError(error),
+			ok: false,
+			port
+		}),
+		onSuccess: (info) => {
+			const support = info.isSupport ? parseSupport(info.isSupport) : void 0;
+			return {
+				developer: {
+					enabled: stringFlag(info.device.developerMode),
+					ip: info.device.developerIP,
+					mode: info.device.developerMode
+				},
+				ip: info.device.ip ?? host,
+				model: info.device.modelName,
+				name: decodeHtml(info.name),
+				ok: true,
+				port,
+				remote: info.remote,
+				remoteAvailable: stringFlag(support?.remote_available),
+				tokenAuth: stringFlag(info.device.TokenAuthSupport),
+				type: info.type,
+				uri: info.uri
+			};
+		}
+	}));
+});
+const readRemoteConnectionDiagnostic = Effect.fn("readRemoteConnectionDiagnostic")(function* (options, doctorOptions) {
+	if (!doctorOptions.connect) return {
+		reason: "pass --connect to test the websocket endpoint",
+		tested: false
+	};
+	if (!options) return {
+		error: diagnosticError(MissingTvRemoteHost.make({})),
+		ok: false,
+		tested: true
+	};
+	return yield* connectRemote(options).pipe(Effect.match({
+		onFailure: (error) => ({
+			error: diagnosticError(error),
+			ok: false,
+			tested: true
+		}),
+		onSuccess: (returnedToken) => ({
+			ok: true,
+			tested: true,
+			tokenReturned: returnedToken.length > 0
+		})
+	}));
+});
 const isAbortError = (cause) => cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError");
 const parseRemoteEvent = (source, options) => {
 	try {
@@ -726,6 +861,53 @@ const normalizeRemoteError = (cause, options) => {
 		target: remoteTarget(options)
 	});
 };
+const diagnosticError = (error) => {
+	if (error instanceof FileSystemFailure) return {
+		message: error.message,
+		target: error.path,
+		type: "FileSystemFailure"
+	};
+	if (error instanceof InvalidJson) return {
+		details: error.details,
+		file: error.file,
+		message: error.message,
+		type: "InvalidJson"
+	};
+	if (error instanceof MissingTvRemoteHost) return {
+		message: error.message,
+		type: "MissingTvRemoteHost"
+	};
+	if (error instanceof MissingTvRemoteToken) return {
+		message: error.message,
+		type: "MissingTvRemoteToken"
+	};
+	if (error instanceof TvRemoteConnectionFailed) return {
+		message: error.message,
+		target: error.target,
+		type: "TvRemoteConnectionFailed"
+	};
+	if (error instanceof TvRemoteProtocolError) return {
+		details: error.details,
+		message: error.message,
+		type: "TvRemoteProtocolError"
+	};
+	if (error instanceof TvRemoteTimeout) return {
+		message: error.message,
+		target: error.target,
+		type: "TvRemoteTimeout"
+	};
+	return {
+		message: error.message,
+		target: error.target,
+		type: "TvRemoteUnauthorized"
+	};
+};
+const valueSource = (envValue, stateValue, targetValue) => {
+	if (envValue) return "env";
+	if (stateValue) return "state";
+	if (targetValue) return "target";
+	return "none";
+};
 const hostFromTarget = (target) => {
 	if (!target) return;
 	return target.split(":").at(0);
@@ -1262,6 +1444,15 @@ const run = Command.make("run", {}, () => withContext((context) => runWidget(con
 const tvPair = Command.make("pair", {}, () => Effect.gen(function* () {
 	yield* pairSamsungTvRemote(yield* loadEnv());
 }));
+const tvDoctor = Command.make("doctor", {
+	connect: Flag.boolean("connect"),
+	json: Flag.boolean("json")
+}, ({ connect, json }) => Effect.gen(function* () {
+	yield* diagnoseSamsungTvRemote(yield* loadEnv(), {
+		connect,
+		json
+	});
+}));
 const tvPress = Command.make("press", {
 	delayMs: Flag.integer("delay-ms").pipe(Flag.withDefault(250)),
 	json: Flag.boolean("json"),
@@ -1276,6 +1467,7 @@ const tvInfo = Command.make("info", { json: Flag.boolean("json") }, ({ json }) =
 	yield* showSamsungTvInfo(yield* loadEnv(), { json });
 }));
 const tv = Command.make("tv", {}).pipe(Command.withSubcommands([
+	tvDoctor,
 	tvPair,
 	tvPress,
 	tvInfo

package/docs/TV_REMOTE.md

@@ -6,6 +6,9 @@ and smoke checks against a physical TV or monitor.
 ## Commands
 
 ```bash
+taizn tv doctor
+taizn tv doctor --json
+taizn tv doctor --connect --json
 taizn tv info
 taizn tv info --json
 taizn tv pair
@@ -14,6 +17,10 @@ taizn tv press --json KEY_ENTER
 taizn tv press --delay-ms 250 KEY_HOME KEY_DOWN KEY_ENTER
 ```
 
+- `doctor` reports the resolved host, local `.taizn/remote.json` state, token
+  presence, HTTP metadata status, and websocket endpoint. Add `--json` for a
+  structured diagnostic. Add `--connect` only when you want to test the
+  websocket; without a token this can trigger the TV's allow/deny prompt.
 - `info` reads the TV's local `/api/v2/` metadata and reports remote-control
   support. Add `--json` to emit a structured TV capability snapshot for agents
   and scripts.
@@ -68,7 +75,8 @@ The `.taizn/` directory is local state and must stay ignored.
 
 ## Scope
 
-Remote commands send key presses only. They do not install widgets, launch
-applications, or capture screenshots. Use the regular `taizn install` and Tizen
-CLI commands for app lifecycle work. Use logs, app-level probes, Samsung Web
-Inspector, Remote Test Lab, or external capture when visual proof is needed.
+Remote commands only inspect metadata, diagnose remote readiness, pair, and send
+key presses. They do not install widgets, launch applications, or capture
+screenshots. Use the regular `taizn install` and Tizen CLI commands for app
+lifecycle work. Use logs, app-level probes, Samsung Web Inspector, Remote Test
+Lab, or external capture when visual proof is needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/taizn",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "A tiny CLI companion for interacting with Tizen ecosystem.",
   "keywords": [
     "cli",