@quicktvui/ai-cli 1.1.1 → 1.1.3

package/README.md

@@ -8,6 +8,15 @@ QuickTVUI skill runtime CLI.
 npm install -g @quicktvui/ai-cli @quicktvui/ai-skills
 ```
 
+Starting from `@quicktvui/ai-cli@1.1.2`, global install/upgrade auto-runs
+`quicktvui-ai update` to sync:
+
+- `~/.agents/skills/quicktvui`
+- `~/.gemini/GEMINI.md` bridge block
+- `~/.gemini/settings.json` context file names
+
+Set `QUICKTVUI_AI_SKIP_POSTINSTALL=1` to disable auto-sync.
+
 ## Commands
 
 ```bash
@@ -47,14 +56,14 @@ quicktvui-aicreate-project quick-tv-app
 - `--skip-node-install`: skip Node.js install stage in `setup-vue-env`
 - `--force-node-install`: force Node.js install stage in `setup-vue-env`
 - `--skip-yarn-install`: skip yarn global install in `setup-vue-env`
-- `--skip-quicktvui-cli-install`: skip `@quicktvui/cli` global install in `setup-vue-env`
 - `--skip-project-install`: skip project dependency install in `setup-vue-env`
 - `--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-setup-mode <direct|qui>`: runtime setup mode (default `direct`)
 - `--runtime-version <version>`: pin runtime version in `direct` mode
 - `--runtime-url <url>`: use custom runtime apk url in `direct` mode
 - `--server-host <ip>`: override debug server host IP
@@ -64,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
@@ -108,21 +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.
-
-To use official interactive setup flow instead of direct mode:
-
-```bash
-quicktvui-ai setup-android-env --project ./quick-tv-app --runtime-setup-mode qui
-```
+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)
 
@@ -133,7 +138,7 @@ quicktvui-ai setup-vue-env --project ./quick-tv-app
 This command:
 
 1. Ensures Node.js LTS (macOS/Windows auto install).
-2. Ensures `yarn` and `@quicktvui/cli` are installed globally.
+2. Ensures `yarn` is installed globally.
 3. Installs project dependencies (`yarn install` or `npm install` fallback).
 
 ## Configure All Dev Envs

package/lib/index.js

@@ -7,7 +7,13 @@ const https = require("https");
 const net = require("net");
 const { spawnSync, spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.4";
+const PACKAGE_VERSION = (() => {
+  try {
+    return require("../package.json").version || "0.0.0";
+  } catch (error) {
+    return "0.0.0";
+  }
+})();
 const DEFAULT_INSTALL_DIR = path.join(
   os.homedir(),
   ".agents",
@@ -25,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`;
@@ -33,6 +41,8 @@ const REQUIRED_SKILL_FILES = [
   "SKILL.md",
   path.join("references", "scaffold-checklist.md"),
   path.join("references", "create-project-checklist.md"),
+  path.join("references", "dev-env-checklist.md"),
+  path.join("references", "esapp-protocol-cheatsheet.md"),
   path.join("references", "lookup-checklist.md"),
   path.join("references", "bug-report-template.md"),
 ];
@@ -1204,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
@@ -1383,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) {
@@ -1428,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();
@@ -1475,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 {
@@ -1783,10 +1954,6 @@ async function runSetupVueEnv(args) {
   );
   const skipNodeInstall = toBooleanFlag(args["skip-node-install"], false);
   const skipYarnInstall = toBooleanFlag(args["skip-yarn-install"], false);
-  const skipQuicktvuiCliInstall = toBooleanFlag(
-    args["skip-quicktvui-cli-install"],
-    false,
-  );
   const skipProjectInstall = toBooleanFlag(args["skip-project-install"], false);
 
   if (
@@ -1818,13 +1985,6 @@ async function runSetupVueEnv(args) {
     runCommand("npm", ["install", "-g", "yarn"], { stdio: "inherit" });
   }
 
-  if (!skipQuicktvuiCliInstall && !commandCanRun("qui", ["--help"])) {
-    console.log("Installing @quicktvui/cli globally...");
-    runCommand("npm", ["install", "-g", "@quicktvui/cli@latest"], {
-      stdio: "inherit",
-    });
-  }
-
   if (!skipProjectInstall) {
     if (!exists(path.join(projectRoot, "package.json"))) {
       throw new Error(`Missing package.json in project root: ${projectRoot}`);
@@ -1865,10 +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 runtimeSetupMode =
-    typeof args["runtime-setup-mode"] === "string"
-      ? String(args["runtime-setup-mode"]).trim().toLowerCase()
-      : "direct";
+  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()
@@ -1888,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,
@@ -2022,26 +2199,16 @@ 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) {
-    if (runtimeSetupMode === "qui") {
-      if (!commandCanRun("qui", ["--help"])) {
-        throw new Error(
-          "QuickTVUI CLI 'qui' is unavailable. Run: npm install -g @quicktvui/cli@latest",
-        );
-      }
-      console.log("Running 'qui setup' to configure runtime APK...");
-      runCommand("qui", ["setup"], { cwd: projectRoot });
-      hostIp = getLocalIPv4Address();
-    } else {
-      const runtimeResult = await ensureRuntimeInstalledAndConfigured(
-        adbPath,
-        targetSerial,
-        args,
-      );
-      hostIp = runtimeResult.hostIp;
-    }
+    const runtimeResult = await ensureRuntimeInstalledAndConfigured(
+      adbPath,
+      targetSerial,
+      args,
+    );
+    hostIp = runtimeResult.hostIp;
   } else {
     console.log("Skip runtime setup due to --skip-runtime-setup.");
   }
@@ -2197,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),
@@ -2216,34 +2384,155 @@ async function runRunEsapp(args) {
   console.log("ES app launch command sent.");
 }
 
-function resolveSkillsSource() {
+function parseSemverSegments(version) {
+  const normalized = String(version || "0.0.0")
+    .trim()
+    .split("-")[0];
+  const parts = normalized ? normalized.split(".") : [];
+  if (parts.length === 0) return [0, 0, 0];
+
+  return parts.map((part) => {
+    const parsed = Number.parseInt(part, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+  });
+}
+
+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;
+    const rightValue = rightParts[i] || 0;
+    if (leftValue > rightValue) return 1;
+    if (leftValue < rightValue) return -1;
+  }
+  return 0;
+}
+
+function buildSkillsSourceCandidateFromPackageRoot(packageRoot, sourceLabel) {
+  if (!packageRoot) return null;
+  const resolvedPackageRoot = path.resolve(packageRoot);
+  const sourceDir = path.join(resolvedPackageRoot, "skills", "quicktvui");
+  if (!exists(sourceDir)) return null;
+
+  let version = "0.0.0";
+  const packageJsonPath = path.join(resolvedPackageRoot, "package.json");
+  if (exists(packageJsonPath)) {
+    try {
+      const packageJson = readJsonFile(packageJsonPath);
+      if (
+        packageJson &&
+        typeof packageJson.version === "string" &&
+        packageJson.version.trim()
+      ) {
+        version = packageJson.version.trim();
+      }
+    } catch (error) {
+      // Ignore parse errors; keep default version for ordering.
+    }
+  }
+
+  return {
+    sourceLabel,
+    sourceDir,
+    packageRoot: resolvedPackageRoot,
+    version,
+  };
+}
+
+function buildSkillsSourceCandidateFromRequire() {
   try {
-    // Preferred: installed dependency
     const { getSkillsRoot } = require("@quicktvui/ai-skills");
-    const resolved = path.join(getSkillsRoot(), "quicktvui");
-    if (exists(resolved)) return resolved;
+    if (typeof getSkillsRoot !== "function") return null;
+    const resolvedSkillsRoot = getSkillsRoot();
+    const sourceDir = path.join(resolvedSkillsRoot, "quicktvui");
+    if (!exists(sourceDir)) return null;
+
+    let packageRoot = null;
+    let version = "0.0.0";
+    try {
+      const packageJsonPath =
+        require.resolve("@quicktvui/ai-skills/package.json");
+      packageRoot = path.dirname(packageJsonPath);
+      const packageJson = readJsonFile(packageJsonPath);
+      if (
+        packageJson &&
+        typeof packageJson.version === "string" &&
+        packageJson.version.trim()
+      ) {
+        version = packageJson.version.trim();
+      }
+    } catch (error) {
+      // Keep fallback metadata if package.json cannot be resolved.
+    }
+
+    return {
+      sourceLabel: "dependency-resolved",
+      sourceDir: path.resolve(sourceDir),
+      packageRoot: packageRoot ? path.resolve(packageRoot) : null,
+      version,
+    };
   } catch (error) {
-    // Fallback for monorepo local development
+    return null;
+  }
+}
+
+function resolveSkillsSource() {
+  const candidates = [];
+  const seenSourceDirs = new Set();
+
+  function addCandidate(candidate) {
+    if (!candidate || !candidate.sourceDir) return;
+    const key = path.resolve(candidate.sourceDir);
+    if (seenSourceDirs.has(key)) return;
+    seenSourceDirs.add(key);
+    candidates.push(candidate);
   }
 
-  const localFallback = path.resolve(
+  // Prefer globally upgraded sibling package if present.
+  const globalSiblingPackageRoot = path.resolve(
+    __dirname,
+    "..",
+    "..",
+    "ai-skills",
+  );
+  addCandidate(
+    buildSkillsSourceCandidateFromPackageRoot(
+      globalSiblingPackageRoot,
+      "global-sibling",
+    ),
+  );
+
+  // Dependency resolution keeps compatibility when only @quicktvui/ai-cli is installed.
+  addCandidate(buildSkillsSourceCandidateFromRequire());
+
+  // Monorepo fallback for local development.
+  const monorepoPackageRoot = path.resolve(
     __dirname,
     "..",
     "..",
     "..",
     "packages",
     "quicktvui-ai-skills",
-    "skills",
-    "quicktvui",
+  );
+  addCandidate(
+    buildSkillsSourceCandidateFromPackageRoot(monorepoPackageRoot, "monorepo"),
   );
 
-  if (!exists(localFallback)) {
+  if (candidates.length === 0) {
     throw new Error(
       "Unable to locate QuickTVUI skill assets. Install @quicktvui/ai-skills or use repository local layout.",
     );
   }
 
-  return localFallback;
+  candidates.sort((left, right) => {
+    const versionOrder = compareSemverStrings(right.version, left.version);
+    if (versionOrder !== 0) return versionOrder;
+    return left.sourceDir.localeCompare(right.sourceDir);
+  });
+
+  return candidates[0].sourceDir;
 }
 
 function getInstallDir(args) {
@@ -2295,7 +2584,7 @@ Commands:
   validate   Strict check for required skill files (non-zero exit if missing)
   update     Reinstall skill assets to target directory
   create-project  Create a QuickTVUI project (remote clone, local fallback)
-  setup-vue-env  Setup Vue development environment (Node/yarn/quicktvui cli)
+  setup-vue-env  Setup Vue development environment (Node/yarn)
   setup-android-env  Configure Android device/emulator + runtime environment
   setup-all-env  Setup both Vue and Android development environments
   run-dev    Run project dev command (optionally checks Android env first)
@@ -2319,14 +2608,14 @@ Options:
   --skip-node-install  Skip Node.js auto-install stage in setup-vue-env
   --force-node-install Force Node.js auto-install even if current version is ok
   --skip-yarn-install Skip yarn global install in setup-vue-env
-  --skip-quicktvui-cli-install Skip @quicktvui/cli global install in setup-vue-env
   --skip-project-install Skip project dependency install in setup-vue-env
   --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-setup-mode <direct|qui> Runtime setup mode in setup-android-env (default: direct)
   --runtime-version <version> Pin runtime version when direct mode is used
   --runtime-url <url> Use custom runtime apk url in direct mode
   --server-host <ip> Override local debug server host IP
@@ -2336,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
@@ -2771,7 +3059,7 @@ async function runCreateProject(args) {
     "- ensured: package.json name/version updated and @quicktvui/ai added to devDependencies",
   );
   console.log(
-    "- next: if not configured, run 'npm install -g @quicktvui/cli@latest' and 'qui setup'",
+    "- next: run 'quicktvui-ai setup-all-env --project <project-path>' to prepare development and runtime environments",
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai-cli",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "CLI for installing and validating QuickTVUI AI skills",
   "bin": {
     "quicktvui-ai": "bin/quicktvui-ai.js",
@@ -8,6 +8,9 @@
     "quicktvui-aicreate-project": "bin/quicktvui-aicreate-project.js"
   },
   "main": "lib/index.js",
+  "scripts": {
+    "postinstall": "node scripts/postinstall-sync.js"
+  },
   "files": [
     "bin",
     "lib",
@@ -25,6 +28,6 @@
   "author": "QuickTVUI",
   "license": "MIT",
   "dependencies": {
-    "@quicktvui/ai-skills": "^0.1.0"
+    "@quicktvui/ai-skills": "^1.1.1"
   }
 }

package/scripts/postinstall-sync.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/index");
+
+function isTruthy(value) {
+  return value === true || value === "true" || value === "1";
+}
+
+function isGlobalInstall() {
+  if (isTruthy(process.env.npm_config_global)) return true;
+  return process.env.npm_config_location === "global";
+}
+
+async function main() {
+  if (isTruthy(process.env.QUICKTVUI_AI_SKIP_POSTINSTALL)) {
+    return;
+  }
+  if (!isGlobalInstall()) {
+    return;
+  }
+
+  try {
+    await runCli(["update"]);
+    console.log(
+      "[quicktvui-ai] postinstall: synced latest skill files into ~/.agents/skills/quicktvui.",
+    );
+  } catch (error) {
+    console.warn(
+      `[quicktvui-ai] postinstall: unable to auto-sync skill files (${error.message}). Run 'quicktvui-ai update' manually.`,
+    );
+  }
+}
+
+main();