@quicktvui/ai-cli 1.1.2 → 1.1.3

package/README.md

@@ -60,6 +60,8 @@ quicktvui-aicreate-project quick-tv-app
 - `--auto-emulator <true|false>`: auto create/start emulator when no adb device
 - `--adb-path <path>`: custom adb path/command (or use env `QUICKTVUI_ADB_PATH`)
 - `--device-ip <ip[:port]>`: preferred real device endpoint for `adb connect`
+- `--device <serial>`: explicit target adb serial for `setup-android-env` / `run-esapp`
+- `--allow-non-tv-device <true|false>`: allow phone/tablet target for TV run flow (default `false`)
 - `--avd-name <name>`: custom AVD name for `setup-android-env`
 - `--headless`: start emulator with `-no-window -no-audio`
 - `--runtime-version <version>`: pin runtime version in `direct` mode
@@ -71,7 +73,6 @@ quicktvui-aicreate-project quick-tv-app
 - `--port <n>`: dev server port used by `run-dev` auto load (default `38989`)
 - `--skip-env-check`: skip environment stage in `run-dev`
 - `--runtime-package <pkg>`: runtime package for `run-esapp` (default `com.extscreen.runtime`)
-- `--device <serial>`: target adb serial for `run-esapp`
 - `--esapp-uri <uri>`: raw launch URI (`esapp://`, `quicktv://`, `appcast://`)
 - `--esapp-query <json>`: extra query params JSON merged in structured mode
 - `--pkg --ver --min-ver --repository --uri --from --args --exp --flags --use-latest`: structured `esapp://action/start` params
@@ -115,15 +116,18 @@ This command:
 
 1. Detects Android SDK root (auto creates a default SDK root when missing).
 2. Detects Android SDK/adb/emulator tools. `@quicktvui/ai-cli` does not bundle adb.
-3. If sdkmanager/avdmanager is missing, it auto-downloads and installs official Android Command-line Tools.
-4. If adb is missing, it auto-installs `platform-tools` (with size estimate + sdkmanager progress).
-5. Detects connected adb devices, and asks whether to use connected device.
-6. If user doesn't use connected device (or no device exists), it asks for real-device IP and runs `adb connect`.
-7. If still no real device, asks whether to download/start official Google Android emulator.
-8. Checks Google repository reachability before emulator download; if unavailable, asks user to install emulator manually.
-9. Prints estimated download size and then starts sdkmanager download (progress shown by sdkmanager).
-10. Installs runtime APK and configures debug server host (direct mode by default).
-11. Launches runtime app and waits it enters running state.
+3. Verifies target device looks like TV (`leanback` / `television` feature). Use `--allow-non-tv-device true` only if you intentionally target phone/tablet.
+4. In non-interactive mode, requires explicit `--device <serial>` when adb devices are connected.
+5. If sdkmanager/avdmanager is missing, it auto-downloads and installs official Android Command-line Tools.
+6. If adb is missing, it auto-installs `platform-tools` (with size estimate + sdkmanager progress).
+7. Detects connected adb devices, and asks whether to use connected device.
+8. If user doesn't use connected device (or no device exists), it asks for real-device IP and runs `adb connect`.
+9. If still no real device, asks whether to download/start official Google Android emulator.
+10. Checks Google repository reachability before emulator download; if unavailable, asks user to install emulator manually.
+11. Prints estimated download size and then starts sdkmanager download (progress shown by sdkmanager).
+12. Installs runtime APK and configures debug server host.
+13. If runtime already exists, asks whether to reinstall runtime before run.
+14. Launches runtime app and waits it enters running state.
 
 ## Configure Vue env (Node + package manager)
 

package/lib/index.js

@@ -31,6 +31,8 @@ const RUNTIME_LAUNCH_ACTIVITY =
   "com.extscreen.runtime/com.extscreen.runtime.LauncherAlias";
 const RUNTIME_DEBUG_BROADCAST_ACTION =
   "com.extscreen.runtime.ACTION_CHANGE_DEBUG_SERVER";
+const RUNTIME_DEBUG_BROADCAST_ACTION_FALLBACK =
+  "tv.eskit.debugger.ACTION_CHANGE_DEBUG_SERVER";
 const RUNTIME_REPOSITORY_ROOT =
   "http://hub.quicktvui.com/repository/maven-files/apk/runtime/dev";
 const RUNTIME_REPOSITORY_METADATA_URL = `${RUNTIME_REPOSITORY_ROOT}/maven-metadata.xml`;
@@ -1212,6 +1214,105 @@ function listConnectedDevices(adbPath) {
   return parseAdbDevices(result.stdout);
 }
 
+function runAdbShellCapture(adbPath, serial, shellArgs) {
+  try {
+    const result = runCommandCapture(adbPath, [
+      "-s",
+      serial,
+      "shell",
+      ...shellArgs,
+    ]);
+    return (result.stdout || "").trim();
+  } catch (error) {
+    return "";
+  }
+}
+
+function parseAndroidWmSize(rawText) {
+  const text = String(rawText || "");
+  const match = text.match(/(\d+)\s*x\s*(\d+)/);
+  if (!match) return null;
+  const width = Number.parseInt(match[1], 10);
+  const height = Number.parseInt(match[2], 10);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  return { width, height };
+}
+
+function inspectAndroidDeviceProfile(adbPath, serial) {
+  const model =
+    runAdbShellCapture(adbPath, serial, ["getprop", "ro.product.model"]) ||
+    "unknown";
+  const characteristics =
+    runAdbShellCapture(adbPath, serial, [
+      "getprop",
+      "ro.build.characteristics",
+    ]) || "";
+  const featureText = runAdbShellCapture(adbPath, serial, [
+    "pm",
+    "list",
+    "features",
+  ]);
+  const wmSizeText = runAdbShellCapture(adbPath, serial, ["wm", "size"]);
+  const wmSize = parseAndroidWmSize(wmSizeText);
+
+  const featureLines = featureText
+    .split(/\r?\n/)
+    .map((line) => line.trim().toLowerCase())
+    .filter(Boolean);
+  const hasLeanbackFeature = featureLines.some(
+    (line) =>
+      line.includes("feature:android.software.leanback") ||
+      line.includes("feature:android.hardware.type.television"),
+  );
+  const characteristicText = characteristics.toLowerCase();
+  const hasTvCharacteristic =
+    characteristicText.includes("tv") ||
+    characteristicText.includes("television");
+  const isLikelyTv = hasLeanbackFeature || hasTvCharacteristic;
+
+  return {
+    serial,
+    model,
+    characteristics,
+    wmSize,
+    hasLeanbackFeature,
+    hasTvCharacteristic,
+    isLikelyTv,
+  };
+}
+
+async function ensureTvSuitableDevice(adbPath, serial, args) {
+  const allowNonTvDevice = toBooleanFlag(args["allow-non-tv-device"], false);
+  const profile = inspectAndroidDeviceProfile(adbPath, serial);
+  const sizeText = profile.wmSize
+    ? `${profile.wmSize.width}x${profile.wmSize.height}`
+    : "unknown";
+  console.log(
+    `Target device profile: serial=${serial}, model=${profile.model}, size=${sizeText}, tvFeature=${profile.hasLeanbackFeature}, tvCharacteristic=${profile.hasTvCharacteristic}`,
+  );
+
+  if (profile.isLikelyTv || allowNonTvDevice) {
+    if (!profile.isLikelyTv && allowNonTvDevice) {
+      console.log(
+        "Warning: selected device does not look like a TV device. Continue because --allow-non-tv-device is enabled.",
+      );
+    }
+    return profile;
+  }
+
+  const continueWithNonTv = await askYesNo(
+    `Selected device ${serial} (${profile.model}) does not look like a TV/box device. Continue with this device anyway?`,
+    false,
+    args,
+  );
+  if (!continueWithNonTv) {
+    throw new Error(
+      `Selected device is likely non-TV. Connect/select a TV device or pass --allow-non-tv-device true to continue with ${serial}.`,
+    );
+  }
+  return profile;
+}
+
 function listAvds(emulatorPath) {
   const result = runCommandCapture(emulatorPath, ["-list-avds"]);
   return result.stdout
@@ -1391,19 +1492,54 @@ async function waitForRuntimeRunning(adbPath, serial, timeoutMs) {
   return false;
 }
 
+function broadcastDebugServerHost(adbPath, serial, action, hostIp) {
+  try {
+    const result = runCommandCapture(adbPath, [
+      "-s",
+      serial,
+      "shell",
+      "am",
+      "broadcast",
+      "-a",
+      action,
+      "--es",
+      "ip",
+      hostIp,
+    ]);
+    const output = `${result.stdout || ""}\n${result.stderr || ""}`.trim();
+    const hasError = /(error|exception|failed)/i.test(output);
+    const hasCompletion = /broadcast completed/i.test(output);
+    return {
+      action,
+      success: hasCompletion && !hasError,
+      output,
+    };
+  } catch (error) {
+    return {
+      action,
+      success: false,
+      output: error.message || "unknown broadcast error",
+    };
+  }
+}
+
 function setRuntimeDebugServerHost(adbPath, serial, hostIp) {
-  runCommandCapture(adbPath, [
-    "-s",
+  const primary = broadcastDebugServerHost(
+    adbPath,
     serial,
-    "shell",
-    "am",
-    "broadcast",
-    "-a",
     RUNTIME_DEBUG_BROADCAST_ACTION,
-    "--es",
-    "ip",
     hostIp,
-  ]);
+  );
+  const fallback = broadcastDebugServerHost(
+    adbPath,
+    serial,
+    RUNTIME_DEBUG_BROADCAST_ACTION_FALLBACK,
+    hostIp,
+  );
+  return {
+    success: primary.success || fallback.success,
+    details: [primary, fallback],
+  };
 }
 
 async function ensureRuntimeInstalledAndConfigured(adbPath, serial, args) {
@@ -1436,7 +1572,26 @@ async function ensureRuntimeInstalledAndConfigured(adbPath, serial, args) {
     Boolean(desiredRuntimeVersion) &&
     (!installedVersion || installedVersion !== desiredRuntimeVersion);
 
-  if (forceRuntimeInstall || !runtimeInfo.installed || shouldInstallByVersion) {
+  if (runtimeInfo.installed) {
+    console.log(
+      `Detected runtime: installed version=${installedVersion || "unknown"}`,
+    );
+  } else {
+    console.log("Detected runtime: not installed");
+  }
+
+  let shouldInstallRuntime =
+    forceRuntimeInstall || !runtimeInfo.installed || shouldInstallByVersion;
+  if (!shouldInstallRuntime && runtimeInfo.installed) {
+    const reinstallNow = await askYesNo(
+      `Runtime already exists on ${serial}. Reinstall runtime now?`,
+      false,
+      args,
+    );
+    shouldInstallRuntime = reinstallNow;
+  }
+
+  if (shouldInstallRuntime) {
     let targetVersion = desiredRuntimeVersion;
     if (!targetVersion && !overrideRuntimeUrl) {
       const versions = await fetchRuntimeVersions();
@@ -1483,7 +1638,15 @@ async function ensureRuntimeInstalledAndConfigured(adbPath, serial, args) {
     throw new Error("Runtime app did not enter running state in time.");
   }
 
-  setRuntimeDebugServerHost(adbPath, serial, hostIp);
+  const debugServerResult = setRuntimeDebugServerHost(adbPath, serial, hostIp);
+  if (!debugServerResult.success) {
+    const details = debugServerResult.details
+      .map((item) => `${item.action}: ${item.output || "no output"}`)
+      .join(" | ");
+    throw new Error(
+      `Failed to configure runtime debug server host: ${hostIp}. Broadcast details: ${details}`,
+    );
+  }
   console.log(`Runtime debug server host configured: ${hostIp}`);
 
   return {
@@ -1862,6 +2025,10 @@ async function runSetupAndroidEnv(args) {
   const projectRoot = args.project ? path.resolve(args.project) : process.cwd();
   const skipRuntimeSetup = toBooleanFlag(args["skip-runtime-setup"], false);
   const autoEmulator = toBooleanFlag(args["auto-emulator"], true);
+  const requestedSerial =
+    typeof args.device === "string" && args.device.trim()
+      ? args.device.trim()
+      : "";
   const avdName =
     typeof args["avd-name"] === "string" && args["avd-name"].trim()
       ? args["avd-name"].trim()
@@ -1881,12 +2048,29 @@ async function runSetupAndroidEnv(args) {
   console.log(
     `ADB devices: connected=${deviceState.devices.length}, unauthorized=${deviceState.unauthorized.length}, offline=${deviceState.offline.length}`,
   );
-  let useConnectedDevice = deviceState.devices.length > 0;
+  let useConnectedDevice = false;
   let shouldSetupEmulator = false;
   let preferredRealDeviceSerial = null;
 
-  if (deviceState.devices.length > 0) {
+  if (requestedSerial) {
+    if (!deviceState.devices.includes(requestedSerial)) {
+      const connectedList = deviceState.devices.join(", ") || "none";
+      throw new Error(
+        `Requested --device ${requestedSerial} is not connected. Connected devices: ${connectedList}`,
+      );
+    }
+    useConnectedDevice = true;
+    preferredRealDeviceSerial = requestedSerial;
+    console.log(`Using requested device: ${requestedSerial}`);
+  }
+
+  if (!useConnectedDevice && deviceState.devices.length > 0) {
     const connectedList = deviceState.devices.join(", ");
+    if (!isInteractivePromptEnabled(args)) {
+      throw new Error(
+        `Detected connected Android device(s): ${connectedList}. Non-interactive mode requires explicit --device <serial> to avoid selecting the wrong device.`,
+      );
+    }
     useConnectedDevice = await askYesNo(
       `Detected connected Android device(s): ${connectedList}. Use this device for setup?`,
       true,
@@ -2015,6 +2199,7 @@ async function runSetupAndroidEnv(args) {
   if (!targetSerial) {
     throw new Error("Unable to resolve target adb device serial.");
   }
+  await ensureTvSuitableDevice(adbPath, targetSerial, args);
 
   let hostIp = getLocalIPv4Address();
   if (!skipRuntimeSetup) {
@@ -2179,6 +2364,7 @@ async function runRunEsapp(args) {
       "No Android device available. Use --device/--device-ip or run setup-android-env first.",
     );
   }
+  await ensureTvSuitableDevice(adbPath, serial, args);
 
   const launchUri = buildEsappLaunchUri(args, projectRoot, {
     pkg: resolveProjectAppPackage(projectRoot),
@@ -2198,7 +2384,7 @@ async function runRunEsapp(args) {
   console.log("ES app launch command sent.");
 }
 
-function parseVersionSegments(version) {
+function parseSemverSegments(version) {
   const normalized = String(version || "0.0.0")
     .trim()
     .split("-")[0];
@@ -2211,9 +2397,9 @@ function parseVersionSegments(version) {
   });
 }
 
-function compareVersionStrings(left, right) {
-  const leftParts = parseVersionSegments(left);
-  const rightParts = parseVersionSegments(right);
+function compareSemverStrings(left, right) {
+  const leftParts = parseSemverSegments(left);
+  const rightParts = parseSemverSegments(right);
   const total = Math.max(leftParts.length, rightParts.length);
   for (let i = 0; i < total; i += 1) {
     const leftValue = leftParts[i] || 0;
@@ -2341,7 +2527,7 @@ function resolveSkillsSource() {
   }
 
   candidates.sort((left, right) => {
-    const versionOrder = compareVersionStrings(right.version, left.version);
+    const versionOrder = compareSemverStrings(right.version, left.version);
     if (versionOrder !== 0) return versionOrder;
     return left.sourceDir.localeCompare(right.sourceDir);
   });
@@ -2426,6 +2612,8 @@ Options:
   --auto-emulator <true|false>  Auto create/start emulator when no adb device
   --adb-path <path> Custom adb binary path/command (or set QUICKTVUI_ADB_PATH)
   --device-ip <ip[:port]> Preferred real device endpoint for adb connect
+  --device <serial> Explicit target adb serial for setup-android-env/run-esapp
+  --allow-non-tv-device <true|false> Allow phone/tablet device for TV run flow (default: false)
   --avd-name <name> Custom AVD name for setup-android-env
   --headless        Start emulator with -no-window -no-audio
   --runtime-version <version> Pin runtime version when direct mode is used
@@ -2437,7 +2625,6 @@ Options:
   --port <n>        Dev server port used by run-dev auto load (default: 38989)
   --skip-env-check  Skip setup-android-env stage in run-dev
   --runtime-package <pkg> Runtime package name for run-esapp (default: com.extscreen.runtime)
-  --device <serial> Target adb device serial for run-esapp
   --esapp-uri <uri> Raw esapp:// / quicktv:// / appcast:// URI for run-esapp
   --esapp-query <json> Extra query params JSON merged into action/start URI
   --pkg <pkg>       ES app package for run-esapp structured mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai-cli",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "CLI for installing and validating QuickTVUI AI skills",
   "bin": {
     "quicktvui-ai": "bin/quicktvui-ai.js",