@quicktvui/ai-cli 1.1.2 → 1.1.5

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,8 +73,7 @@ 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-uri <uri>`: raw launch URI (`esapp://`)
 - `--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/docs/esapp-protocol.md

@@ -1,4 +1,4 @@
-# ESApp Protocol Reference (`esapp://`, `quicktv://`, `appcast://`)
+# ESApp Protocol Reference (`esapp://`)
 
 This document summarizes runtime launch protocol behavior from:
 
@@ -12,8 +12,6 @@ This document summarizes runtime launch protocol behavior from:
 Runtime entry activity accepts:
 
 - `esapp://`
-- `quicktv://`
-- `appcast://`
 
 ## 2) Parsing Modes
 
@@ -29,13 +27,11 @@ Behavior:
 - `/start` maps to `action=start_es`.
 - All query params are forwarded to protocol JSON.
 
-### Mode B: V2 package URI (esapp/quicktv/appcast)
+### Mode B: V2 package URI (esapp)
 
 ```text
 esapp://es.hello.world?from=cmd
 esapp://es.hello.world/1.0.3?from=cmd
-quicktv://es.hello.world?from=cmd
-appcast://es.hello.world/1.0.3?from=cmd
 ```
 
 Behavior:

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 {
@@ -1551,18 +1714,18 @@ function ensureSupportedEsappUri(uri) {
   const normalized = String(uri || "")
     .trim()
     .toLowerCase();
-  if (
-    normalized.startsWith("esapp://") ||
-    normalized.startsWith("quicktv://") ||
-    normalized.startsWith("appcast://")
-  ) {
+  if (normalized.startsWith("esapp://")) {
     return;
   }
   throw new Error(
-    `Unsupported URI scheme for runtime launch: ${uri}. Use esapp://, quicktv://, or appcast://.`,
+    `Unsupported URI scheme for runtime launch: ${uri}. Use esapp:// only.`,
   );
 }
 
+function quotePosixShellArg(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
 function buildEsappLaunchUri(args, projectRoot, defaults = {}) {
   const positional =
     args._ && typeof args._[1] === "string" ? args._[1].trim() : "";
@@ -1644,18 +1807,19 @@ function buildEsappLaunchUri(args, projectRoot, defaults = {}) {
 
 function startEsappOnRuntimeByUri(adbPath, serial, runtimePackage, launchUri) {
   ensureSupportedEsappUri(launchUri);
+  // Use explicit POSIX shell quoting so `&` in URI query is not truncated by
+  // remote Android shell parsing (e.g. `...from=cmd&pkg=...`).
+  const shellCommand = [
+    "am start",
+    "-a android.intent.action.VIEW",
+    `-p ${quotePosixShellArg(runtimePackage)}`,
+    `-d ${quotePosixShellArg(launchUri)}`,
+  ].join(" ");
   const result = runCommandCapture(adbPath, [
     "-s",
     serial,
     "shell",
-    "am",
-    "start",
-    "-a",
-    "android.intent.action.VIEW",
-    "-p",
-    runtimePackage,
-    "-d",
-    launchUri,
+    shellCommand,
   ]);
   const output = `${result.stdout || ""}\n${result.stderr || ""}`.trim();
   if (/(^|\s)error[:\s]/i.test(output) || /exception/i.test(output)) {
@@ -1862,6 +2026,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 +2049,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 +2200,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 +2365,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 +2385,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 +2398,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 +2528,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 +2613,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,8 +2626,7 @@ 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-uri <uri> Raw esapp:// 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
   --ver <version>   ES app version for run-esapp structured mode

package/package.json

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

package/scripts/postinstall-sync.js

@@ -1,16 +1,43 @@
 #!/usr/bin/env node
 
 const { runCli } = require("../lib/index");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 
 function isTruthy(value) {
   return value === true || value === "true" || value === "1";
 }
 
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
 function isGlobalInstall() {
   if (isTruthy(process.env.npm_config_global)) return true;
   return process.env.npm_config_location === "global";
 }
 
+function resolveCodexHome() {
+  const fromEnv = process.env.CODEX_HOME
+    ? String(process.env.CODEX_HOME).trim()
+    : "";
+  if (fromEnv) {
+    return path.resolve(fromEnv);
+  }
+  return path.join(os.homedir(), ".codex");
+}
+
+function shouldSyncCodex() {
+  const fromEnv = process.env.CODEX_HOME
+    ? String(process.env.CODEX_HOME).trim()
+    : "";
+  if (fromEnv) {
+    return true;
+  }
+  return exists(path.join(os.homedir(), ".codex"));
+}
+
 async function main() {
   if (isTruthy(process.env.QUICKTVUI_AI_SKIP_POSTINSTALL)) {
     return;
@@ -19,16 +46,51 @@ async function main() {
     return;
   }
 
+  const syncCodex = shouldSyncCodex();
+  const codexSkillsDir = path.join(resolveCodexHome(), "skills", "quicktvui");
+  const failures = [];
+
   try {
-    await runCli(["update"]);
+    if (syncCodex) {
+      await runCli(["update", "--skip-gemini-config"]);
+    } else {
+      await runCli(["update"]);
+    }
+  } catch (error) {
+    failures.push(`agents: ${error.message}`);
+  }
+
+  if (syncCodex) {
+    try {
+      await runCli(["update", "--dir", codexSkillsDir]);
+    } catch (error) {
+      failures.push(`codex: ${error.message}`);
+    }
+  }
+
+  if (failures.length === 0) {
+    if (syncCodex) {
+      console.log(
+        `[quicktvui-ai] postinstall: synced latest skill files into ~/.agents/skills/quicktvui and ${codexSkillsDir}.`,
+      );
+      return;
+    }
     console.log(
       "[quicktvui-ai] postinstall: synced latest skill files into ~/.agents/skills/quicktvui.",
     );
-  } catch (error) {
+    return;
+  }
+
+  if (syncCodex) {
     console.warn(
-      `[quicktvui-ai] postinstall: unable to auto-sync skill files (${error.message}). Run 'quicktvui-ai update' manually.`,
+      `[quicktvui-ai] postinstall: unable to fully auto-sync skill files (${failures.join("; ")}). Run 'quicktvui-ai update' and 'quicktvui-ai update --dir ${codexSkillsDir}' manually.`,
     );
+    return;
   }
+
+  console.warn(
+    `[quicktvui-ai] postinstall: unable to auto-sync skill files (${failures.join("; ")}). Run 'quicktvui-ai update' manually.`,
+  );
 }
 
 main();