@quicktvui/ai-cli 0.1.0 → 1.1.1

package/lib/index.js

@@ -1,14 +1,33 @@
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
+const readline = require("node:readline/promises");
+const http = require("http");
+const https = require("https");
+const net = require("net");
+const { spawnSync, spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.0";
+const PACKAGE_VERSION = "0.1.4";
 const DEFAULT_INSTALL_DIR = path.join(
   os.homedir(),
   ".agents",
   "skills",
   "quicktvui",
 );
+const TEMPLATE_REPO_URL = "https://github.com/quicktvui/quicktvui-template.git";
+const DEFAULT_QUICKTVUI_AI_VERSION = "^1.1.0";
+const DEFAULT_ANDROID_AVD_NAME = "quicktvui_tv";
+const DEFAULT_ANDROID_API_LEVEL = "android-35";
+const DEFAULT_NODE_LTS_MAJOR = 20;
+const DEFAULT_DEV_SERVER_PORT = 38989;
+const RUNTIME_PACKAGE_NAME = "com.extscreen.runtime";
+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_REPOSITORY_ROOT =
+  "http://hub.quicktvui.com/repository/maven-files/apk/runtime/dev";
+const RUNTIME_REPOSITORY_METADATA_URL = `${RUNTIME_REPOSITORY_ROOT}/maven-metadata.xml`;
 
 const REQUIRED_SKILL_FILES = [
   "SKILL.md",
@@ -17,27 +36,2184 @@ const REQUIRED_SKILL_FILES = [
   path.join("references", "lookup-checklist.md"),
   path.join("references", "bug-report-template.md"),
 ];
+const QUICKTVUI_GEMINI_BRIDGE_START = "<!-- QUICKTVUI_SKILL_BRIDGE_START -->";
+const QUICKTVUI_GEMINI_BRIDGE_END = "<!-- QUICKTVUI_SKILL_BRIDGE_END -->";
+const DEFAULT_GEMINI_CONTEXT_FILENAMES = [
+  "GEMINI.md",
+  "AGENTS.md",
+  "SKILL.md",
+  "CONTEXT.md",
+];
+
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function copyDirectoryRecursive(src, dest) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function removeDirectoryIfExists(dirPath) {
+  if (exists(dirPath)) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+  }
+}
+
+function backupFile(filePath) {
+  if (!exists(filePath)) return null;
+  const backupPath = `${filePath}.bak`;
+  try {
+    fs.copyFileSync(filePath, backupPath);
+    return backupPath;
+  } catch (error) {
+    return null;
+  }
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function needsWindowsShell(command) {
+  return process.platform === "win32" && /\.(bat|cmd)$/i.test(String(command));
+}
+
+function withSpawnOptions(command, options) {
+  if (needsWindowsShell(command)) {
+    return { shell: true, ...options };
+  }
+  return options;
+}
+
+function runCommand(command, args, options = {}) {
+  const result = spawnSync(
+    command,
+    args,
+    withSpawnOptions(command, {
+      stdio: "inherit",
+      ...options,
+    }),
+  );
+  if (result.error) {
+    throw new Error(`Failed to run '${command}': ${result.error.message}`);
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    throw new Error(`Command failed: ${command} ${args.join(" ")}`);
+  }
+}
+
+function runCommandCapture(command, args, options = {}) {
+  const result = spawnSync(
+    command,
+    args,
+    withSpawnOptions(command, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      ...options,
+    }),
+  );
+
+  if (result.error) {
+    throw new Error(`Failed to run '${command}': ${result.error.message}`);
+  }
+
+  if (typeof result.status === "number" && result.status !== 0) {
+    const stderr = (result.stderr || "").trim();
+    const stdout = (result.stdout || "").trim();
+    const reason = stderr || stdout || "unknown error";
+    throw new Error(`Command failed: ${command} ${args.join(" ")}\n${reason}`);
+  }
+
+  return {
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+function runCommandDetached(command, args, options = {}) {
+  let child;
+  try {
+    child = spawn(
+      command,
+      args,
+      withSpawnOptions(command, {
+        detached: true,
+        stdio: "ignore",
+        ...options,
+      }),
+    );
+  } catch (error) {
+    throw new Error(`Failed to run '${command}': ${error.message}`);
+  }
+  child.unref();
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ["--version"], { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+function commandCanRun(command, args) {
+  const result = spawnSync(
+    command,
+    args,
+    withSpawnOptions(command, { stdio: "ignore" }),
+  );
+  return !result.error && result.status === 0;
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJsonFile(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function resolveBundledTemplateSource() {
+  const packageTemplate = path.resolve(
+    __dirname,
+    "..",
+    "templates",
+    "quicktvui-template",
+  );
+  if (exists(packageTemplate)) return packageTemplate;
+
+  const monorepoFallback = path.resolve(
+    __dirname,
+    "..",
+    "..",
+    "..",
+    "packages",
+    "quicktvui-ai-cli",
+    "templates",
+    "quicktvui-template",
+  );
+  if (exists(monorepoFallback)) return monorepoFallback;
+
+  throw new Error(
+    "Bundled quicktvui-template snapshot is missing from @quicktvui/ai-cli.",
+  );
+}
+
+function ensureProjectPackageRules(projectDir, projectName) {
+  const packageJsonPath = path.join(projectDir, "package.json");
+  if (!exists(packageJsonPath)) {
+    throw new Error(`Missing package.json in created project: ${projectDir}`);
+  }
+
+  const packageJson = readJsonFile(packageJsonPath);
+  packageJson.name = projectName;
+  packageJson.version = "1.0.0";
+
+  if (!packageJson.devDependencies) {
+    packageJson.devDependencies = {};
+  }
+  if (!packageJson.devDependencies["@quicktvui/ai"]) {
+    packageJson.devDependencies["@quicktvui/ai"] = DEFAULT_QUICKTVUI_AI_VERSION;
+  }
+
+  writeJsonFile(packageJsonPath, packageJson);
+}
+
+function installProjectDependencies(projectDir, args) {
+  if (args["skip-install"]) {
+    console.log("Skip dependency installation due to --skip-install.");
+    return;
+  }
+
+  if (commandExists("yarn")) {
+    runCommand("yarn", ["install"], { cwd: projectDir });
+    return;
+  }
+
+  if (commandExists("npm")) {
+    runCommand("npm", ["install"], { cwd: projectDir });
+    return;
+  }
+
+  console.log(
+    "Warning: neither yarn nor npm found. Install dependencies manually in project directory.",
+  );
+}
+
+function isDirectoryEmpty(dirPath) {
+  if (!exists(dirPath)) return true;
+  const entries = fs.readdirSync(dirPath);
+  return entries.length === 0;
+}
+
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function pickPrimaryDeviceSerial(deviceState) {
+  if (!deviceState || !Array.isArray(deviceState.devices)) return null;
+  if (deviceState.devices.length === 0) return null;
+  const emulator = deviceState.devices.find((serial) =>
+    serial.startsWith("emulator-"),
+  );
+  return emulator || deviceState.devices[0];
+}
+
+function getLocalIPv4Address() {
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    const records = interfaces[name] || [];
+    for (const item of records) {
+      if (
+        item &&
+        item.family === "IPv4" &&
+        item.address !== "127.0.0.1" &&
+        !item.internal
+      ) {
+        return item.address;
+      }
+    }
+  }
+  return null;
+}
+
+function parseVersionSegments(version) {
+  return String(version)
+    .trim()
+    .split(".")
+    .map((segment) => {
+      const numberValue = Number(segment);
+      if (Number.isFinite(numberValue)) return numberValue;
+      return segment;
+    });
+}
+
+function compareVersionDesc(a, b) {
+  const aSeg = parseVersionSegments(a);
+  const bSeg = parseVersionSegments(b);
+  const max = Math.max(aSeg.length, bSeg.length);
+  for (let i = 0; i < max; i += 1) {
+    const left = typeof aSeg[i] === "undefined" ? 0 : aSeg[i];
+    const right = typeof bSeg[i] === "undefined" ? 0 : bSeg[i];
+    if (typeof left === "number" && typeof right === "number") {
+      if (left > right) return -1;
+      if (left < right) return 1;
+      continue;
+    }
+    const cmp = String(right).localeCompare(String(left), undefined, {
+      numeric: true,
+      sensitivity: "base",
+    });
+    if (cmp !== 0) return cmp;
+  }
+  return 0;
+}
+
+function fetchWithRedirect(url, redirectCount = 0, timeoutMs = 20000) {
+  return new Promise((resolve, reject) => {
+    if (redirectCount > 8) {
+      reject(new Error(`Too many redirects: ${url}`));
+      return;
+    }
+    const client = url.startsWith("https://") ? https : http;
+    const req = client.get(url, (res) => {
+      const status = res.statusCode || 0;
+      if ([301, 302, 303, 307, 308].includes(status) && res.headers.location) {
+        const nextUrl = new URL(res.headers.location, url).toString();
+        res.resume();
+        resolve(fetchWithRedirect(nextUrl, redirectCount + 1, timeoutMs));
+        return;
+      }
+      if (status >= 400) {
+        const errorChunks = [];
+        res.on("data", (chunk) => errorChunks.push(chunk));
+        res.on("end", () => {
+          const detail = Buffer.concat(errorChunks).toString("utf8").trim();
+          reject(
+            new Error(
+              `Request failed (${status}) ${url}${detail ? `: ${detail}` : ""}`,
+            ),
+          );
+        });
+        return;
+      }
+      resolve(res);
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`Request timeout after ${timeoutMs}ms: ${url}`));
+    });
+    req.on("error", reject);
+  });
+}
+
+async function fetchText(url, timeoutMs = 20000) {
+  const response = await fetchWithRedirect(url, 0, timeoutMs);
+  return await new Promise((resolve, reject) => {
+    const chunks = [];
+    response.on("data", (chunk) => chunks.push(chunk));
+    response.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    response.on("error", reject);
+  });
+}
+
+async function downloadToFile(url, filePath, timeoutMs = 60000) {
+  const response = await fetchWithRedirect(url, 0, timeoutMs);
+  await new Promise((resolve, reject) => {
+    const writer = fs.createWriteStream(filePath);
+    response.pipe(writer);
+    response.on("error", reject);
+    writer.on("error", reject);
+    writer.on("finish", resolve);
+  });
+}
+
+function parseRuntimeVersionList(metadataText) {
+  const matches = metadataText.match(/<version>[^<]+<\/version>/g) || [];
+  const versions = matches
+    .map((entry) =>
+      entry.replace("<version>", "").replace("</version>", "").trim(),
+    )
+    .filter(Boolean);
+  return Array.from(new Set(versions)).sort(compareVersionDesc);
+}
+
+async function fetchRuntimeVersions() {
+  const metadata = await fetchText(RUNTIME_REPOSITORY_METADATA_URL);
+  return parseRuntimeVersionList(metadata);
+}
+
+function buildRuntimeApkUrl(version) {
+  return `${RUNTIME_REPOSITORY_ROOT}/${version}/dev-${version}.apk`;
+}
+
+function waitForPort(host, port, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+
+    const tryConnect = () => {
+      const socket = new net.Socket();
+      let settled = false;
+      socket.setTimeout(2000);
+
+      socket.on("connect", () => {
+        if (settled) return;
+        settled = true;
+        socket.destroy();
+        resolve(true);
+      });
+
+      socket.on("timeout", () => {
+        socket.destroy();
+      });
+      socket.on("error", () => {
+        socket.destroy();
+      });
+      socket.on("close", () => {
+        if (settled) return;
+        if (Date.now() - startedAt >= timeoutMs) {
+          settled = true;
+          reject(new Error(`Timed out waiting for ${host}:${port}`));
+          return;
+        }
+        setTimeout(tryConnect, 1000);
+      });
+
+      socket.connect(port, host);
+    };
+
+    tryConnect();
+  });
+}
+
+function resolveNodeMajorVersion() {
+  const raw = process.versions && process.versions.node;
+  if (!raw) return null;
+  const major = Number(String(raw).split(".")[0]);
+  if (!Number.isFinite(major)) return null;
+  return major;
+}
+
+function commandExistsViaShell(shellCmd) {
+  const result = spawnSync(shellCmd, [], { stdio: "ignore", shell: true });
+  return !result.error && result.status === 0;
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes);
+  if (!Number.isFinite(value) || value <= 0) return "unknown";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let current = value;
+  let index = 0;
+  while (current >= 1024 && index < units.length - 1) {
+    current /= 1024;
+    index += 1;
+  }
+  return `${current.toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+}
+
+function isInteractivePromptEnabled(args) {
+  const autoYes = toBooleanFlag(args.yes, false);
+  const noInteractive = toBooleanFlag(args["no-interactive"], false);
+  if (autoYes || noInteractive) return false;
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+async function askYesNo(question, defaultValue, args) {
+  if (!isInteractivePromptEnabled(args)) {
+    return defaultValue;
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const suffix = defaultValue ? "[Y/n]" : "[y/N]";
+    const answer = (await rl.question(`${question} ${suffix} `))
+      .trim()
+      .toLowerCase();
+    if (!answer) return defaultValue;
+    if (answer === "y" || answer === "yes") return true;
+    if (answer === "n" || answer === "no") return false;
+    return defaultValue;
+  } finally {
+    rl.close();
+  }
+}
+
+async function askText(question, defaultValue, args) {
+  if (!isInteractivePromptEnabled(args)) {
+    return defaultValue || "";
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const suffix = defaultValue ? ` [default: ${defaultValue}]` : "";
+    const answer = (await rl.question(`${question}${suffix} `)).trim();
+    return answer || defaultValue || "";
+  } finally {
+    rl.close();
+  }
+}
+
+function normalizeDeviceEndpoint(input) {
+  const raw = String(input || "").trim();
+  if (!raw) return "";
+  if (raw.includes(":")) return raw;
+  return `${raw}:5555`;
+}
+
+function tryAdbConnect(adbPath, endpoint) {
+  const result = spawnSync(adbPath, ["connect", endpoint], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.error) {
+    return {
+      connected: false,
+      output: result.error.message,
+    };
+  }
+  const stdout = (result.stdout || "").trim();
+  const stderr = (result.stderr || "").trim();
+  const output = [stdout, stderr].filter(Boolean).join("\n");
+  const connected = /connected to|already connected to/i.test(output);
+  return { connected, output };
+}
+
+async function connectRealDeviceByIp(adbPath, args) {
+  let defaultInput =
+    typeof args["device-ip"] === "string" ? args["device-ip"].trim() : "";
+  if (!isInteractivePromptEnabled(args) && !defaultInput) {
+    return null;
+  }
+  let attempt = 0;
+  while (attempt < 3) {
+    attempt += 1;
+    const rawInput = await askText(
+      "Enter Android device IP (example: 192.168.1.100 or 192.168.1.100:5555):",
+      defaultInput,
+      args,
+    );
+    const endpoint = normalizeDeviceEndpoint(rawInput);
+    if (!endpoint) {
+      const retryEmpty = await askYesNo(
+        "Device IP is empty. Do you want to retry input?",
+        attempt < 3,
+        args,
+      );
+      if (!retryEmpty) return null;
+      continue;
+    }
+
+    defaultInput = endpoint;
+    console.log(`Trying to connect device: ${endpoint}`);
+    const connectResult = tryAdbConnect(adbPath, endpoint);
+    if (connectResult.connected) {
+      console.log(`Device connected: ${endpoint}`);
+      return endpoint;
+    }
+
+    console.log(
+      `Connect failed: ${connectResult.output || "unknown adb connect error"}`,
+    );
+    const retry = await askYesNo(
+      "Failed to connect by IP. Try another IP?",
+      attempt < 3,
+      args,
+    );
+    if (!retry) return null;
+  }
+
+  return null;
+}
+
+function parseRemotePackageSizeMap(xmlText) {
+  const sizeMap = new Map();
+  const packageRegex =
+    /<remotePackage\s+path="([^"]+)">([\s\S]*?)<\/remotePackage>/g;
+  let packageMatch = packageRegex.exec(xmlText);
+  while (packageMatch) {
+    const pkgPath = packageMatch[1];
+    const pkgBody = packageMatch[2];
+    const sizeMatches = pkgBody.match(/<size>(\d+)<\/size>/g) || [];
+    let maxSize = 0;
+    for (const raw of sizeMatches) {
+      const num = Number(raw.replace("<size>", "").replace("</size>", ""));
+      if (Number.isFinite(num) && num > maxSize) {
+        maxSize = num;
+      }
+    }
+    if (maxSize > 0) {
+      sizeMap.set(pkgPath, maxSize);
+    }
+    packageMatch = packageRegex.exec(xmlText);
+  }
+  return sizeMap;
+}
+
+async function canReachGoogleAndroidRepo() {
+  try {
+    const res = await fetchWithRedirect(
+      "https://dl.google.com/android/repository/repository2-1.xml",
+      0,
+      8000,
+    );
+    res.resume();
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function fetchAndroidPackageSizeMap() {
+  const xml = await fetchText(
+    "https://dl.google.com/android/repository/repository2-1.xml",
+  );
+  return parseRemotePackageSizeMap(xml);
+}
+
+function printEmulatorDownloadEstimate(sizeMap, systemImageCandidates) {
+  const basePackages = ["platform-tools", "emulator"];
+  const packageLines = [];
+  let total = 0;
+
+  for (const pkg of basePackages) {
+    const size = sizeMap.get(pkg);
+    if (size) {
+      total += size;
+      packageLines.push(`- ${pkg}: ${formatBytes(size)}`);
+    } else {
+      packageLines.push(`- ${pkg}: unknown`);
+    }
+  }
+
+  const matchedSystemImage = systemImageCandidates.find((candidate) =>
+    sizeMap.has(candidate),
+  );
+  if (matchedSystemImage) {
+    const size = sizeMap.get(matchedSystemImage);
+    total += size;
+    packageLines.push(`- ${matchedSystemImage}: ${formatBytes(size)}`);
+  } else {
+    packageLines.push(`- system-image: unknown (candidate not found in index)`);
+  }
+
+  console.log("Estimated Android download size:");
+  for (const line of packageLines) {
+    console.log(line);
+  }
+  if (total > 0) {
+    console.log(`- total (known): ${formatBytes(total)}`);
+  }
+  console.log("Download progress will be shown by sdkmanager below.");
+}
+
+function printSdkPackageDownloadEstimate(sizeMap, packageNames, title) {
+  const packageLines = [];
+  let total = 0;
+  for (const packageName of packageNames) {
+    const size = sizeMap.get(packageName);
+    if (size) {
+      total += size;
+      packageLines.push(`- ${packageName}: ${formatBytes(size)}`);
+    } else {
+      packageLines.push(`- ${packageName}: unknown`);
+    }
+  }
+  console.log(title);
+  for (const line of packageLines) {
+    console.log(line);
+  }
+  if (total > 0) {
+    console.log(`- total (known): ${formatBytes(total)}`);
+  }
+  console.log("Download progress will be shown by sdkmanager below.");
+}
+
+function getDefaultAndroidSdkRoots() {
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return [path.join(home, "Library", "Android", "sdk")];
+  }
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA;
+    const roots = [];
+    if (localAppData) {
+      roots.push(path.join(localAppData, "Android", "sdk"));
+    }
+    roots.push(path.join(home, "AppData", "Local", "Android", "sdk"));
+    return roots;
+  }
+  return [path.join(home, "Android", "Sdk"), path.join(home, "Android", "sdk")];
+}
+
+function getPreferredAndroidSdkRootPath() {
+  const fromEnv =
+    process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME || "";
+  if (fromEnv) {
+    return path.resolve(fromEnv);
+  }
+  const defaults = getDefaultAndroidSdkRoots();
+  if (defaults.length > 0) {
+    return path.resolve(defaults[0]);
+  }
+  return path.resolve(path.join(os.homedir(), "Android", "Sdk"));
+}
+
+function resolveAndroidSdkRoot() {
+  const fromEnv =
+    process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME || "";
+  if (fromEnv && exists(fromEnv)) {
+    return {
+      sdkRoot: path.resolve(fromEnv),
+      source: "environment",
+    };
+  }
+
+  for (const sdkPath of getDefaultAndroidSdkRoots()) {
+    if (exists(sdkPath)) {
+      return {
+        sdkRoot: path.resolve(sdkPath),
+        source: "default-path",
+      };
+    }
+  }
+
+  return {
+    sdkRoot: null,
+    source: "missing",
+  };
+}
+
+function resolveAndroidSdkRootForSetup() {
+  const resolved = resolveAndroidSdkRoot();
+  if (resolved.sdkRoot) {
+    return resolved;
+  }
+
+  const autoPath = getPreferredAndroidSdkRootPath();
+  ensureDir(autoPath);
+  return {
+    sdkRoot: path.resolve(autoPath),
+    source: "auto-created",
+  };
+}
+
+function binaryExists(binaryPath, checkArgs = ["--version"]) {
+  if (!binaryPath) return false;
+  if (!exists(binaryPath)) return false;
+  const result = spawnSync(
+    binaryPath,
+    checkArgs,
+    withSpawnOptions(binaryPath, { stdio: "ignore" }),
+  );
+  return !result.error && result.status === 0;
+}
+
+function resolveAndroidTool(toolName, sdkRoot) {
+  const toolNameVariants = [];
+  if (process.platform === "win32") {
+    if (toolName === "sdkmanager" || toolName === "avdmanager") {
+      toolNameVariants.push(`${toolName}.bat`, `${toolName}.exe`);
+    } else {
+      toolNameVariants.push(`${toolName}.exe`);
+    }
+  } else {
+    toolNameVariants.push(toolName);
+  }
+
+  if (toolName === "adb" && commandCanRun("adb", ["version"])) {
+    return "adb";
+  }
+  if (toolName === "emulator" && commandCanRun("emulator", ["-version"])) {
+    return "emulator";
+  }
+  if (toolName === "avdmanager" && commandCanRun("avdmanager", ["--help"])) {
+    return "avdmanager";
+  }
+  if (toolName === "sdkmanager" && commandCanRun("sdkmanager", ["--help"])) {
+    return "sdkmanager";
+  }
+
+  if (!sdkRoot) return null;
+
+  const candidates = [];
+  if (toolName === "adb") {
+    for (const name of toolNameVariants) {
+      candidates.push(path.join(sdkRoot, "platform-tools", name));
+    }
+  } else if (toolName === "emulator") {
+    for (const name of toolNameVariants) {
+      candidates.push(path.join(sdkRoot, "emulator", name));
+    }
+  } else if (toolName === "sdkmanager" || toolName === "avdmanager") {
+    for (const name of toolNameVariants) {
+      candidates.push(
+        path.join(sdkRoot, "cmdline-tools", "latest", "bin", name),
+      );
+      candidates.push(path.join(sdkRoot, "tools", "bin", name));
+    }
+  }
+
+  for (const candidate of candidates) {
+    let checkArgs = ["--help"];
+    if (toolName === "adb") checkArgs = ["version"];
+    if (toolName === "emulator") checkArgs = ["-version"];
+    if (binaryExists(candidate, checkArgs)) {
+      return candidate;
+    }
+    if (
+      (toolName === "sdkmanager" || toolName === "avdmanager") &&
+      exists(candidate)
+    ) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function getAndroidRepoHostOsTag() {
+  if (process.platform === "darwin") return "macosx";
+  if (process.platform === "win32") return "windows";
+  if (process.platform === "linux") return "linux";
+  return null;
+}
+
+function parseCommandLineToolsPathRank(packagePath) {
+  const token = String(packagePath || "").split(";")[1] || "";
+  if (token === "latest") return 1_000_000;
+  const num = Number(token.replace(/[^\d.]/g, ""));
+  if (Number.isFinite(num)) return num;
+  return 0;
+}
+
+function parseAndroidCommandLineToolsArchiveInfo(xmlText) {
+  const hostOs = getAndroidRepoHostOsTag();
+  if (!hostOs) {
+    throw new Error(
+      `Unsupported platform for Android Command-line Tools: ${process.platform}`,
+    );
+  }
+
+  const packageRegex =
+    /<remotePackage\s+path="(cmdline-tools;[^"]+)">([\s\S]*?)<\/remotePackage>/g;
+  const packageEntries = [];
+  let packageMatch = packageRegex.exec(xmlText);
+  while (packageMatch) {
+    const packagePath = packageMatch[1];
+    const body = packageMatch[2];
+    packageEntries.push({
+      packagePath,
+      body,
+      rank: parseCommandLineToolsPathRank(packagePath),
+    });
+    packageMatch = packageRegex.exec(xmlText);
+  }
+
+  if (packageEntries.length === 0) {
+    throw new Error("Unable to find Android cmdline-tools package metadata.");
+  }
+
+  packageEntries.sort((a, b) => b.rank - a.rank);
+  for (const entry of packageEntries) {
+    const archiveRegex = /<archive>([\s\S]*?)<\/archive>/g;
+    const archives = [];
+    let archiveMatch = archiveRegex.exec(entry.body);
+    while (archiveMatch) {
+      const archiveBody = archiveMatch[1];
+      const completeMatch = archiveBody.match(
+        /<complete>([\s\S]*?)<\/complete>/,
+      );
+      if (completeMatch) {
+        const completeBody = completeMatch[1];
+        const urlMatch = completeBody.match(/<url>([^<]+)<\/url>/);
+        const sizeMatch = completeBody.match(/<size>(\d+)<\/size>/);
+        const hostOsMatch = archiveBody.match(/<host-os>([^<]+)<\/host-os>/);
+        if (urlMatch) {
+          archives.push({
+            hostOs: hostOsMatch ? hostOsMatch[1] : "",
+            url: urlMatch[1],
+            sizeBytes: sizeMatch ? Number(sizeMatch[1]) : 0,
+            packagePath: entry.packagePath,
+          });
+        }
+      }
+      archiveMatch = archiveRegex.exec(entry.body);
+    }
+
+    const exactHost = archives.find((item) => item.hostOs === hostOs);
+    if (exactHost) return exactHost;
+
+    const noHost = archives.find((item) => !item.hostOs);
+    if (noHost) return noHost;
+  }
+
+  throw new Error(
+    `Unable to find Android cmdline-tools archive for host OS '${hostOs}'.`,
+  );
+}
+
+function buildAndroidRepositoryUrl(relativeOrAbsolutePath) {
+  const raw = String(relativeOrAbsolutePath || "");
+  if (!raw) return "";
+  if (/^https?:\/\//i.test(raw)) return raw;
+  return `https://dl.google.com/android/repository/${raw.replace(/^\/+/, "")}`;
+}
+
+function escapePowerShellLiteral(value) {
+  return String(value).replace(/'/g, "''");
+}
+
+function extractZipArchive(zipPath, destination) {
+  ensureDir(destination);
+  if (process.platform === "win32") {
+    if (
+      !commandCanRun("powershell", [
+        "-NoProfile",
+        "-Command",
+        "$PSVersionTable.PSVersion.ToString()",
+      ])
+    ) {
+      throw new Error(
+        "PowerShell is required to extract Android command-line tools zip on Windows.",
+      );
+    }
+    const escapedZip = escapePowerShellLiteral(path.resolve(zipPath));
+    const escapedDest = escapePowerShellLiteral(path.resolve(destination));
+    runCommand("powershell", [
+      "-NoProfile",
+      "-Command",
+      `Expand-Archive -Path '${escapedZip}' -DestinationPath '${escapedDest}' -Force`,
+    ]);
+    return;
+  }
+
+  if (commandCanRun("unzip", ["-v"])) {
+    runCommand("unzip", ["-q", zipPath, "-d", destination]);
+    return;
+  }
+
+  if (process.platform === "darwin" && commandCanRun("ditto", ["-h"])) {
+    runCommand("ditto", ["-x", "-k", zipPath, destination]);
+    return;
+  }
+
+  throw new Error(
+    "No zip extraction tool found. Install unzip (or use PowerShell on Windows).",
+  );
+}
+
+function findCommandLineToolsSourceDir(extractRoot) {
+  const sdkmanagerName =
+    process.platform === "win32" ? "sdkmanager.bat" : "sdkmanager";
+  const queue = [{ dir: extractRoot, depth: 0 }];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || current.depth > 5) continue;
+    const sdkmanagerPath = path.join(current.dir, "bin", sdkmanagerName);
+    if (exists(sdkmanagerPath)) {
+      return current.dir;
+    }
+    const entries = fs.readdirSync(current.dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        queue.push({
+          dir: path.join(current.dir, entry.name),
+          depth: current.depth + 1,
+        });
+      }
+    }
+  }
+  return null;
+}
+
+async function installAndroidCommandLineTools(sdkRoot) {
+  if (!sdkRoot) {
+    throw new Error(
+      "Android SDK root is missing, unable to install command-line tools.",
+    );
+  }
+  console.log(
+    "Android sdkmanager is unavailable. Try to auto-install Android Command-line Tools...",
+  );
+
+  const googleReachable = await canReachGoogleAndroidRepo();
+  if (!googleReachable) {
+    throw new Error(
+      "Unable to connect to Google Android repository (dl.google.com). Please manually install Android command-line tools and set ANDROID_SDK_ROOT.",
+    );
+  }
+
+  const repositoryXml = await fetchText(
+    "https://dl.google.com/android/repository/repository2-1.xml",
+  );
+  const archive = parseAndroidCommandLineToolsArchiveInfo(repositoryXml);
+  const downloadUrl = buildAndroidRepositoryUrl(archive.url);
+  if (!downloadUrl) {
+    throw new Error(
+      "Unable to resolve Android command-line tools download URL.",
+    );
+  }
+
+  if (archive.sizeBytes > 0) {
+    console.log("Estimated Android download size for command-line tools:");
+    console.log(`- ${archive.packagePath}: ${formatBytes(archive.sizeBytes)}`);
+  } else {
+    console.log(
+      "Estimated Android download size for command-line tools: unknown",
+    );
+  }
+
+  const tempRoot = fs.mkdtempSync(
+    path.join(os.tmpdir(), "quicktvui-cmdline-tools-"),
+  );
+  const zipPath = path.join(tempRoot, "commandlinetools.zip");
+  const extractDir = path.join(tempRoot, "extract");
+  ensureDir(extractDir);
+
+  try {
+    console.log(`Downloading Android command-line tools: ${downloadUrl}`);
+    await downloadToFile(downloadUrl, zipPath);
+    console.log("Extracting Android command-line tools...");
+    extractZipArchive(zipPath, extractDir);
+
+    const sourceDir = findCommandLineToolsSourceDir(extractDir);
+    if (!sourceDir) {
+      throw new Error(
+        "Extracted command-line tools are invalid (sdkmanager not found).",
+      );
+    }
+
+    const cmdlineToolsDir = path.join(sdkRoot, "cmdline-tools");
+    const latestDir = path.join(cmdlineToolsDir, "latest");
+    ensureDir(cmdlineToolsDir);
+    removeDirectoryIfExists(latestDir);
+    copyDirectoryRecursive(sourceDir, latestDir);
+    if (process.platform !== "win32") {
+      const sdkmanagerScript = path.join(latestDir, "bin", "sdkmanager");
+      const avdmanagerScript = path.join(latestDir, "bin", "avdmanager");
+      if (exists(sdkmanagerScript)) fs.chmodSync(sdkmanagerScript, 0o755);
+      if (exists(avdmanagerScript)) fs.chmodSync(avdmanagerScript, 0o755);
+    }
+    console.log(`Installed Android command-line tools: ${latestDir}`);
+  } finally {
+    removeDirectoryIfExists(tempRoot);
+  }
+}
+
+async function ensureAndroidCommandLineToolsAvailable(sdkRoot) {
+  let sdkmanagerPath = resolveAndroidTool("sdkmanager", sdkRoot);
+  let avdmanagerPath = resolveAndroidTool("avdmanager", sdkRoot);
+  if (sdkmanagerPath && avdmanagerPath) {
+    return { sdkmanagerPath, avdmanagerPath };
+  }
+
+  await installAndroidCommandLineTools(sdkRoot);
+  sdkmanagerPath = resolveAndroidTool("sdkmanager", sdkRoot);
+  avdmanagerPath = resolveAndroidTool("avdmanager", sdkRoot);
+  return { sdkmanagerPath, avdmanagerPath };
+}
+
+function resolveAdbOverride(rawValue) {
+  const value = String(rawValue || "").trim();
+  if (!value) return null;
+  const looksLikePath =
+    value.startsWith(".") ||
+    value.includes("/") ||
+    value.includes("\\") ||
+    path.isAbsolute(value);
+  if (looksLikePath) {
+    const candidate = path.resolve(value);
+    return binaryExists(candidate, ["version"]) ? candidate : null;
+  }
+  return commandCanRun(value, ["version"]) ? value : null;
+}
+
+function resolveAdbOverrideFromArgs(args) {
+  const fromArg =
+    typeof args["adb-path"] === "string" ? args["adb-path"].trim() : "";
+  if (fromArg) {
+    const resolved = resolveAdbOverride(fromArg);
+    if (!resolved) {
+      throw new Error(
+        `Invalid --adb-path: ${fromArg}. Please provide a valid adb binary path or command.`,
+      );
+    }
+    return { adbPath: resolved, source: "--adb-path" };
+  }
+
+  const fromEnv =
+    typeof process.env.QUICKTVUI_ADB_PATH === "string"
+      ? process.env.QUICKTVUI_ADB_PATH.trim()
+      : "";
+  if (fromEnv) {
+    const resolved = resolveAdbOverride(fromEnv);
+    if (resolved) {
+      return { adbPath: resolved, source: "QUICKTVUI_ADB_PATH" };
+    }
+    console.log(
+      `Warning: QUICKTVUI_ADB_PATH is set but invalid: ${fromEnv}. Ignore and continue auto detection.`,
+    );
+  }
+
+  return null;
+}
+
+async function resolveAdbPathForSetup(args, sdkRoot) {
+  const override = resolveAdbOverrideFromArgs(args);
+  if (override) {
+    console.log(`Using adb from ${override.source}: ${override.adbPath}`);
+    return override.adbPath;
+  }
+
+  let adbPath = resolveAndroidTool("adb", sdkRoot);
+  if (adbPath) {
+    return adbPath;
+  }
+
+  if (!sdkRoot) {
+    return null;
+  }
+
+  let sdkmanagerPath = resolveAndroidTool("sdkmanager", sdkRoot);
+  if (!sdkmanagerPath) {
+    const toolPaths = await ensureAndroidCommandLineToolsAvailable(sdkRoot);
+    sdkmanagerPath = toolPaths.sdkmanagerPath;
+  }
+  if (!sdkmanagerPath) return null;
+
+  console.log(
+    "adb is unavailable. Try to auto-install Android SDK Platform-Tools...",
+  );
+
+  const googleReachable = await canReachGoogleAndroidRepo();
+  if (!googleReachable) {
+    throw new Error(
+      "adb is missing and Google repository (dl.google.com) is unreachable. Please manually install Android SDK Platform-Tools, then rerun (or pass --adb-path / QUICKTVUI_ADB_PATH).",
+    );
+  }
+
+  try {
+    const sizeMap = await fetchAndroidPackageSizeMap();
+    printSdkPackageDownloadEstimate(
+      sizeMap,
+      ["platform-tools"],
+      "Estimated Android download size for adb:",
+    );
+  } catch (error) {
+    console.log(
+      `Unable to fetch package size metadata: ${error.message}. Continue with sdkmanager download.`,
+    );
+  }
+
+  console.log("Installing required Android SDK package: platform-tools...");
+  ensureAndroidSdkPackages(sdkmanagerPath, sdkRoot, ["platform-tools"]);
+  adbPath = resolveAndroidTool("adb", sdkRoot);
+  return adbPath;
+}
+
+function parseAdbDevices(rawOutput) {
+  const lines = rawOutput
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const devices = [];
+  const unauthorized = [];
+  const offline = [];
+
+  for (const line of lines) {
+    if (line.startsWith("List of devices attached")) continue;
+    const columns = line.split(/\s+/);
+    if (columns.length < 2) continue;
+    const serial = columns[0];
+    const state = columns[1];
+    if (state === "device") {
+      devices.push(serial);
+    } else if (state === "unauthorized") {
+      unauthorized.push(serial);
+    } else if (state === "offline") {
+      offline.push(serial);
+    }
+  }
+
+  return { devices, unauthorized, offline };
+}
+
+function listConnectedDevices(adbPath) {
+  const result = runCommandCapture(adbPath, ["devices"]);
+  return parseAdbDevices(result.stdout);
+}
+
+function listAvds(emulatorPath) {
+  const result = runCommandCapture(emulatorPath, ["-list-avds"]);
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function getPreferredSystemImageCandidates() {
+  const apiLevel =
+    process.env.QUICKTVUI_ANDROID_API || DEFAULT_ANDROID_API_LEVEL;
+  const hostArch = os.arch();
+  const abi = hostArch === "arm64" ? "arm64-v8a" : "x86_64";
+  return [
+    `system-images;${apiLevel};google_apis;${abi}`,
+    `system-images;${apiLevel};google_apis_playstore;${abi}`,
+    `system-images;${apiLevel};default;${abi}`,
+  ];
+}
+
+function ensureAndroidSdkPackages(sdkmanagerPath, sdkRoot, packages) {
+  runCommand(sdkmanagerPath, ["--licenses"], {
+    input: "y\n".repeat(80),
+    stdio: ["pipe", "inherit", "inherit"],
+  });
+
+  for (const packageName of packages) {
+    runCommand(sdkmanagerPath, [`--sdk_root=${sdkRoot}`, packageName], {
+      stdio: "inherit",
+    });
+  }
+}
+
+function installSystemImagePackage(sdkmanagerPath, sdkRoot) {
+  const candidates = getPreferredSystemImageCandidates();
+  let lastError;
+
+  for (const candidate of candidates) {
+    try {
+      console.log(`Trying Android system image: ${candidate}`);
+      runCommand(sdkmanagerPath, [`--sdk_root=${sdkRoot}`, candidate], {
+        stdio: "inherit",
+      });
+      return candidate;
+    } catch (error) {
+      lastError = error;
+      console.log(`- skipped: ${candidate}`);
+    }
+  }
+
+  throw new Error(
+    `Unable to install Android system image automatically. ${
+      lastError ? lastError.message : ""
+    }`.trim(),
+  );
+}
+
+function createAvd(avdmanagerPath, avdName, imagePackage) {
+  runCommand(
+    avdmanagerPath,
+    ["create", "avd", "-n", avdName, "-k", imagePackage, "-f"],
+    {
+      input: "no\n",
+      stdio: ["pipe", "inherit", "inherit"],
+    },
+  );
+}
+
+function startAvd(emulatorPath, avdName, args) {
+  const emulatorArgs = [
+    "-avd",
+    avdName,
+    "-netdelay",
+    "none",
+    "-netspeed",
+    "full",
+  ];
+  if (args.headless) {
+    emulatorArgs.push("-no-window", "-no-audio");
+  }
+  runCommandDetached(emulatorPath, emulatorArgs);
+}
+
+async function waitForAdbDevice(adbPath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const status = listConnectedDevices(adbPath);
+      if (status.devices.length > 0) {
+        return status.devices[0];
+      }
+    } catch (error) {
+      // ignore transient adb boot race
+    }
+    await delay(2000);
+  }
+  throw new Error("Timed out waiting for Android device connection.");
+}
+
+async function waitForBootComplete(adbPath, serial, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const result = runCommandCapture(adbPath, [
+        "-s",
+        serial,
+        "shell",
+        "getprop",
+        "sys.boot_completed",
+      ]);
+      if ((result.stdout || "").trim() === "1") {
+        return;
+      }
+    } catch (error) {
+      // ignore transient shell failures during emulator boot
+    }
+    await delay(2500);
+  }
+  throw new Error(`Timed out waiting for device boot completion: ${serial}`);
+}
+
+function getInstalledRuntimeInfo(adbPath, serial) {
+  try {
+    const result = runCommandCapture(adbPath, [
+      "-s",
+      serial,
+      "shell",
+      "dumpsys",
+      "package",
+      RUNTIME_PACKAGE_NAME,
+    ]);
+    const text = result.stdout || "";
+    if (text.includes("Unable to find package")) {
+      return { installed: false, versionName: null, versionCode: null };
+    }
+    const versionNameLine = text
+      .split(/\r?\n/)
+      .find((line) => line.includes("versionName="));
+    const versionCodeLine = text
+      .split(/\r?\n/)
+      .find((line) => line.includes("versionCode="));
+    const versionName = versionNameLine
+      ? versionNameLine.split("=").slice(1).join("=").trim()
+      : null;
+    const versionCode = versionCodeLine
+      ? versionCodeLine.split("=").slice(1).join("=").trim()
+      : null;
+    return {
+      installed: true,
+      versionName,
+      versionCode,
+    };
+  } catch (error) {
+    return { installed: false, versionName: null, versionCode: null };
+  }
+}
+
+async function waitForRuntimeRunning(adbPath, serial, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const result = runCommandCapture(adbPath, [
+        "-s",
+        serial,
+        "shell",
+        "pidof",
+        RUNTIME_PACKAGE_NAME,
+      ]);
+      if ((result.stdout || "").trim()) {
+        return true;
+      }
+    } catch (error) {
+      // ignore during startup
+    }
+    await delay(1000);
+  }
+  return false;
+}
+
+function setRuntimeDebugServerHost(adbPath, serial, hostIp) {
+  runCommandCapture(adbPath, [
+    "-s",
+    serial,
+    "shell",
+    "am",
+    "broadcast",
+    "-a",
+    RUNTIME_DEBUG_BROADCAST_ACTION,
+    "--es",
+    "ip",
+    hostIp,
+  ]);
+}
+
+async function ensureRuntimeInstalledAndConfigured(adbPath, serial, args) {
+  const forceRuntimeInstall = toBooleanFlag(
+    args["force-runtime-install"],
+    false,
+  );
+  const desiredRuntimeVersion =
+    typeof args["runtime-version"] === "string" &&
+    args["runtime-version"].trim()
+      ? args["runtime-version"].trim()
+      : "";
+  const overrideRuntimeUrl =
+    typeof args["runtime-url"] === "string" && args["runtime-url"].trim()
+      ? args["runtime-url"].trim()
+      : "";
+  const hostIp =
+    (typeof args["server-host"] === "string" && args["server-host"].trim()) ||
+    getLocalIPv4Address();
+
+  if (!hostIp) {
+    throw new Error(
+      "Unable to detect local IPv4 address for runtime debug server host.",
+    );
+  }
+
+  let runtimeInfo = getInstalledRuntimeInfo(adbPath, serial);
+  let installedVersion = runtimeInfo.versionName;
+  const shouldInstallByVersion =
+    Boolean(desiredRuntimeVersion) &&
+    (!installedVersion || installedVersion !== desiredRuntimeVersion);
+
+  if (forceRuntimeInstall || !runtimeInfo.installed || shouldInstallByVersion) {
+    let targetVersion = desiredRuntimeVersion;
+    if (!targetVersion && !overrideRuntimeUrl) {
+      const versions = await fetchRuntimeVersions();
+      if (!versions || versions.length === 0) {
+        throw new Error("No runtime versions found in runtime repository.");
+      }
+      targetVersion = versions[0];
+    }
+
+    const apkUrl = overrideRuntimeUrl || buildRuntimeApkUrl(targetVersion);
+    const apkName = `quicktvui-runtime-${targetVersion || Date.now()}.apk`;
+    const apkPath = path.join(os.tmpdir(), apkName);
+    console.log(`Downloading runtime APK: ${apkUrl}`);
+    await downloadToFile(apkUrl, apkPath);
+
+    try {
+      console.log("Installing runtime APK...");
+      runCommand(adbPath, ["-s", serial, "install", "-r", apkPath], {
+        stdio: "inherit",
+      });
+    } finally {
+      if (exists(apkPath)) {
+        fs.rmSync(apkPath, { force: true });
+      }
+    }
+
+    runtimeInfo = getInstalledRuntimeInfo(adbPath, serial);
+    installedVersion = runtimeInfo.versionName;
+  }
+
+  console.log(`Launching runtime app: ${RUNTIME_PACKAGE_NAME}`);
+  runCommandCapture(adbPath, [
+    "-s",
+    serial,
+    "shell",
+    "am",
+    "start",
+    "-n",
+    RUNTIME_LAUNCH_ACTIVITY,
+  ]);
+
+  const isRunning = await waitForRuntimeRunning(adbPath, serial, 25000);
+  if (!isRunning) {
+    throw new Error("Runtime app did not enter running state in time.");
+  }
+
+  setRuntimeDebugServerHost(adbPath, serial, hostIp);
+  console.log(`Runtime debug server host configured: ${hostIp}`);
+
+  return {
+    hostIp,
+    runtimeVersion: installedVersion,
+  };
+}
+
+function resolveProjectAppPackage(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!exists(packageJsonPath)) {
+    return "quicktvui-app";
+  }
+  const packageJson = readJsonFile(packageJsonPath);
+  if (typeof packageJson.appName === "string" && packageJson.appName.trim()) {
+    return packageJson.appName.trim();
+  }
+  if (typeof packageJson.name === "string" && packageJson.name.trim()) {
+    return packageJson.name.replace(/^@[^/]+\//, "").trim();
+  }
+  return "quicktvui-app";
+}
+
+function parseJsonObjectArg(rawValue, optionName) {
+  if (typeof rawValue === "undefined") return {};
+  if (rawValue && typeof rawValue === "object" && !Array.isArray(rawValue)) {
+    return rawValue;
+  }
+  const text = String(rawValue).trim();
+  if (!text) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${optionName} must be a valid JSON object string.`);
+  }
+  if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+    throw new Error(`${optionName} must be a JSON object.`);
+  }
+  return parsed;
+}
+
+function appendEsappParam(target, key, value) {
+  if (typeof value === "undefined" || value === null) return;
+  if (typeof value === "string" && !value.trim()) return;
+  target[key] = value;
+}
+
+function buildEsappActionStartUri(queryParams) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(queryParams || {})) {
+    if (typeof value === "undefined" || value === null) continue;
+    if (typeof value === "string" && !value.trim()) continue;
+    if (typeof value === "object") {
+      search.set(String(key), JSON.stringify(value));
+      continue;
+    }
+    search.set(String(key), String(value));
+  }
+  const query = search.toString();
+  return query ? `esapp://action/start?${query}` : "esapp://action/start";
+}
+
+function ensureSupportedEsappUri(uri) {
+  const normalized = String(uri || "")
+    .trim()
+    .toLowerCase();
+  if (
+    normalized.startsWith("esapp://") ||
+    normalized.startsWith("quicktv://") ||
+    normalized.startsWith("appcast://")
+  ) {
+    return;
+  }
+  throw new Error(
+    `Unsupported URI scheme for runtime launch: ${uri}. Use esapp://, quicktv://, or appcast://.`,
+  );
+}
+
+function buildEsappLaunchUri(args, projectRoot, defaults = {}) {
+  const positional =
+    args._ && typeof args._[1] === "string" ? args._[1].trim() : "";
+  const rawUri =
+    (typeof args["esapp-uri"] === "string" && args["esapp-uri"].trim()) ||
+    (positional.includes("://") ? positional : "");
+  if (rawUri) {
+    ensureSupportedEsappUri(rawUri);
+    return rawUri;
+  }
+
+  const query = {};
+  const defaultPkg =
+    (typeof defaults.pkg === "string" && defaults.pkg.trim()) ||
+    resolveProjectAppPackage(projectRoot);
+  const defaultFrom =
+    (typeof defaults.from === "string" && defaults.from.trim()) || "cmd";
+
+  const pkg =
+    (typeof args.pkg === "string" && args.pkg.trim()) ||
+    (!positional.includes("://") ? positional : "") ||
+    defaultPkg;
+  if (!pkg) {
+    throw new Error(
+      "Missing target package for esapp launch. Use --pkg <package> or --esapp-uri <uri>.",
+    );
+  }
+
+  appendEsappParam(
+    query,
+    "from",
+    (typeof args.from === "string" && args.from.trim()) || defaultFrom,
+  );
+  appendEsappParam(query, "pkg", pkg);
+
+  appendEsappParam(query, "ver", args.ver);
+  appendEsappParam(query, "minVer", args["min-ver"]);
+  appendEsappParam(query, "repository", args.repository);
+  appendEsappParam(query, "uri", args.uri || defaults.uri);
+  appendEsappParam(query, "flags", args.flags);
+  appendEsappParam(query, "args", args.args);
+  appendEsappParam(query, "exp", args.exp);
+  appendEsappParam(query, "name", args.name);
+  appendEsappParam(query, "icon", args.icon);
+  appendEsappParam(query, "pageTag", args["page-tag"]);
+  appendEsappParam(query, "pageLimit", args["page-limit"]);
+  appendEsappParam(query, "bgColor", args["bg-color"]);
+  appendEsappParam(query, "splash", args.splash);
+
+  if (typeof args["is-card"] !== "undefined") {
+    query.isCard = toBooleanFlag(args["is-card"], false);
+  }
+  if (typeof args.transparent !== "undefined") {
+    query.transparent = toBooleanFlag(args.transparent, false);
+  }
+  if (typeof args.enc !== "undefined") {
+    query.enc = toBooleanFlag(args.enc, false);
+  }
+  if (typeof args["check-network"] !== "undefined") {
+    query.checkNetwork = toBooleanFlag(args["check-network"], false);
+  }
+  if (typeof args["use-latest"] !== "undefined") {
+    query.useLatest = toBooleanFlag(args["use-latest"], false);
+  }
+  if (typeof args["feature-single-activity"] !== "undefined") {
+    query.feature_single_activity = toBooleanFlag(
+      args["feature-single-activity"],
+      false,
+    );
+  }
+
+  const extQuery = parseJsonObjectArg(args["esapp-query"], "--esapp-query");
+  for (const [key, value] of Object.entries(extQuery)) {
+    appendEsappParam(query, key, value);
+  }
+
+  return buildEsappActionStartUri(query);
+}
+
+function startEsappOnRuntimeByUri(adbPath, serial, runtimePackage, launchUri) {
+  ensureSupportedEsappUri(launchUri);
+  const result = runCommandCapture(adbPath, [
+    "-s",
+    serial,
+    "shell",
+    "am",
+    "start",
+    "-a",
+    "android.intent.action.VIEW",
+    "-p",
+    runtimePackage,
+    "-d",
+    launchUri,
+  ]);
+  const output = `${result.stdout || ""}\n${result.stderr || ""}`.trim();
+  if (/(^|\s)error[:\s]/i.test(output) || /exception/i.test(output)) {
+    throw new Error(output || "Unknown runtime start error.");
+  }
+  return output;
+}
+
+async function clickRuntimeLoadButtonByDpad(adbPath, serial) {
+  const rightCount = 6;
+  for (let i = 0; i < rightCount; i += 1) {
+    runCommandCapture(adbPath, [
+      "-s",
+      serial,
+      "shell",
+      "input",
+      "keyevent",
+      "22",
+    ]);
+    await delay(120);
+  }
+  runCommandCapture(adbPath, [
+    "-s",
+    serial,
+    "shell",
+    "input",
+    "keyevent",
+    "23",
+  ]);
+}
 
-function exists(filePath) {
-  return fs.existsSync(filePath);
+async function autoLoadLocalBundleOnRuntime(
+  adbPath,
+  serial,
+  projectRoot,
+  hostIp,
+  port,
+  args = {},
+) {
+  const appPkg = resolveProjectAppPackage(projectRoot);
+  const launchUri = buildEsappLaunchUri(args, projectRoot, {
+    pkg: appPkg,
+    from: "cmd",
+    uri: `${hostIp}:${port}`,
+  });
+  console.log(`Auto loading bundle on runtime: ${launchUri}`);
+  try {
+    startEsappOnRuntimeByUri(adbPath, serial, RUNTIME_PACKAGE_NAME, launchUri);
+    console.log("Triggered local bundle by runtime intent.");
+    return;
+  } catch (error) {
+    console.log(
+      `Runtime intent load failed, fallback to key events: ${error.message}`,
+    );
+  }
+
+  await clickRuntimeLoadButtonByDpad(adbPath, serial);
+  console.log("Triggered runtime load button with DPAD key events.");
 }
 
-function ensureDir(dirPath) {
-  fs.mkdirSync(dirPath, { recursive: true });
+function shouldInstallNodeForCurrentPlatform(requiredMajor, args) {
+  const force = toBooleanFlag(args["force-node-install"], false);
+  if (force) return true;
+  const currentMajor = resolveNodeMajorVersion();
+  if (!currentMajor) return true;
+  return currentMajor < requiredMajor;
 }
 
-function copyDirectoryRecursive(src, dest) {
-  ensureDir(dest);
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDirectoryRecursive(srcPath, destPath);
+function installNodeForMac(requiredMajor) {
+  if (commandCanRun("brew", ["--version"])) {
+    runCommand("brew", ["install", `node@${requiredMajor}`], {
+      stdio: "inherit",
+    });
+    runCommand(
+      "brew",
+      ["link", `node@${requiredMajor}`, "--force", "--overwrite"],
+      {
+        stdio: "inherit",
+      },
+    );
+    return;
+  }
+
+  if (
+    commandExistsViaShell(
+      "/bin/zsh -lc 'command -v nvm >/dev/null 2>&1 && nvm --version >/dev/null 2>&1'",
+    )
+  ) {
+    runCommand(
+      "/bin/zsh",
+      ["-lc", `nvm install ${requiredMajor} && nvm use ${requiredMajor}`],
+      { stdio: "inherit" },
+    );
+    return;
+  }
+
+  throw new Error(
+    "Unable to auto-install Node.js on macOS. Install Homebrew or nvm first, then rerun setup-vue-env.",
+  );
+}
+
+function installNodeForWindows() {
+  if (commandCanRun("winget", ["--version"])) {
+    runCommand(
+      "winget",
+      [
+        "install",
+        "--id",
+        "OpenJS.NodeJS.LTS",
+        "-e",
+        "--accept-source-agreements",
+        "--accept-package-agreements",
+      ],
+      { stdio: "inherit" },
+    );
+    return;
+  }
+
+  if (commandCanRun("choco", ["-v"])) {
+    runCommand("choco", ["install", "nodejs-lts", "-y"], { stdio: "inherit" });
+    return;
+  }
+
+  throw new Error(
+    "Unable to auto-install Node.js on Windows. Install winget or chocolatey first, then rerun setup-vue-env.",
+  );
+}
+
+async function runSetupVueEnv(args) {
+  const projectRoot = args.project ? path.resolve(args.project) : process.cwd();
+  const requiredNodeMajor = Number(
+    args["node-major"] || DEFAULT_NODE_LTS_MAJOR,
+  );
+  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 (
+    !skipNodeInstall &&
+    shouldInstallNodeForCurrentPlatform(requiredNodeMajor, args)
+  ) {
+    console.log(`Installing Node.js LTS (major ${requiredNodeMajor})...`);
+    if (process.platform === "darwin") {
+      installNodeForMac(requiredNodeMajor);
+    } else if (process.platform === "win32") {
+      installNodeForWindows();
     } else {
-      fs.copyFileSync(srcPath, destPath);
+      throw new Error(
+        "Auto Node.js installation currently supports macOS and Windows only.",
+      );
+    }
+  } else {
+    console.log(
+      `Node.js check passed (current=${process.versions.node}, required>=${requiredNodeMajor}).`,
+    );
+  }
+
+  if (!commandCanRun("npm", ["--version"])) {
+    throw new Error("npm is unavailable after Node.js setup.");
+  }
+
+  if (!skipYarnInstall && !commandCanRun("yarn", ["--version"])) {
+    console.log("Installing yarn globally...");
+    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}`);
+    }
+    console.log(`Installing project dependencies: ${projectRoot}`);
+    installProjectDependencies(projectRoot, args);
+  }
+
+  console.log(
+    `Vue development environment is ready for project: ${projectRoot}`,
+  );
+}
+
+async function runSetupAllEnv(args) {
+  console.log("Step 1/2: setup Vue development environment...");
+  await runSetupVueEnv(args);
+  console.log("Step 2/2: setup Android runtime environment...");
+  await runSetupAndroidEnv(args);
+  console.log("All development environments are ready.");
+}
+
+function resolvePackageManagerCommand(projectRoot) {
+  const yarnLock = path.join(projectRoot, "yarn.lock");
+  const pnpmLock = path.join(projectRoot, "pnpm-lock.yaml");
+  if (exists(yarnLock) && commandExists("yarn")) {
+    return { command: "yarn", args: ["dev"] };
+  }
+  if (exists(pnpmLock) && commandExists("pnpm")) {
+    return { command: "pnpm", args: ["dev"] };
+  }
+  if (commandExists("npm")) {
+    return { command: "npm", args: ["run", "dev"] };
+  }
+  throw new Error("Neither yarn, pnpm, nor npm is available on this machine.");
+}
+
+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 avdName =
+    typeof args["avd-name"] === "string" && args["avd-name"].trim()
+      ? args["avd-name"].trim()
+      : DEFAULT_ANDROID_AVD_NAME;
+
+  const { sdkRoot, source } = resolveAndroidSdkRootForSetup();
+  console.log(`Android SDK root: ${sdkRoot || "not found"} (${source})`);
+
+  const adbPath = await resolveAdbPathForSetup(args, sdkRoot);
+  if (!adbPath) {
+    throw new Error(
+      "adb is unavailable. quicktvui-ai does not bundle adb by default. Install Android SDK Platform-Tools (or Android Studio), or pass --adb-path <path>.",
+    );
+  }
+
+  let deviceState = listConnectedDevices(adbPath);
+  console.log(
+    `ADB devices: connected=${deviceState.devices.length}, unauthorized=${deviceState.unauthorized.length}, offline=${deviceState.offline.length}`,
+  );
+  let useConnectedDevice = deviceState.devices.length > 0;
+  let shouldSetupEmulator = false;
+  let preferredRealDeviceSerial = null;
+
+  if (deviceState.devices.length > 0) {
+    const connectedList = deviceState.devices.join(", ");
+    useConnectedDevice = await askYesNo(
+      `Detected connected Android device(s): ${connectedList}. Use this device for setup?`,
+      true,
+      args,
+    );
+    if (useConnectedDevice) {
+      preferredRealDeviceSerial = deviceState.devices[0] || null;
+    }
+  }
+
+  if (!useConnectedDevice) {
+    const connectRealByIp = await askYesNo(
+      "Do you want to connect a real device by IP now (adb connect)?",
+      true,
+      args,
+    );
+    if (connectRealByIp) {
+      const connectedEndpoint = await connectRealDeviceByIp(adbPath, args);
+      if (connectedEndpoint) {
+        await delay(600);
+        deviceState = listConnectedDevices(adbPath);
+        if (deviceState.devices.length > 0) {
+          useConnectedDevice = true;
+          preferredRealDeviceSerial =
+            deviceState.devices.find(
+              (serial) => serial === connectedEndpoint,
+            ) || connectedEndpoint;
+          console.log(
+            `Detected connected device(s): ${deviceState.devices.join(", ")}`,
+          );
+        }
+      }
+    }
+  }
+
+  if (!useConnectedDevice) {
+    if (autoEmulator) {
+      shouldSetupEmulator = await askYesNo(
+        "No usable real device found. Do you want to download and use official Google Android emulator now?",
+        true,
+        args,
+      );
+    }
+
+    if (!shouldSetupEmulator) {
+      throw new Error(
+        "No real device connected and emulator setup declined. Please manually install/connect device or emulator.",
+      );
+    }
+  }
+
+  if (!useConnectedDevice && shouldSetupEmulator) {
+    const emulatorPath = resolveAndroidTool("emulator", sdkRoot);
+    if (!emulatorPath) {
+      throw new Error(
+        "No Android device is connected and emulator tool is unavailable. Install Android Studio (with SDK + Emulator) first.",
+      );
+    }
+
+    let avds = listAvds(emulatorPath);
+    if (avds.length === 0) {
+      let sdkmanagerPath = resolveAndroidTool("sdkmanager", sdkRoot);
+      let avdmanagerPath = resolveAndroidTool("avdmanager", sdkRoot);
+
+      if (!sdkRoot || !sdkmanagerPath || !avdmanagerPath) {
+        const toolPaths = await ensureAndroidCommandLineToolsAvailable(sdkRoot);
+        sdkmanagerPath = toolPaths.sdkmanagerPath;
+        avdmanagerPath = toolPaths.avdmanagerPath;
+      }
+
+      if (!sdkmanagerPath || !avdmanagerPath) {
+        throw new Error(
+          "No AVD found and sdkmanager/avdmanager is still unavailable after auto-install. Please install Android command-line tools manually.",
+        );
+      }
+
+      const googleReachable = await canReachGoogleAndroidRepo();
+      if (!googleReachable) {
+        throw new Error(
+          "Unable to connect to Google Android repository (dl.google.com). Please manually download/install Android emulator and SDK, then rerun setup-android-env.",
+        );
+      }
+
+      try {
+        const sizeMap = await fetchAndroidPackageSizeMap();
+        printEmulatorDownloadEstimate(
+          sizeMap,
+          getPreferredSystemImageCandidates(),
+        );
+      } catch (error) {
+        console.log(
+          `Unable to fetch package size metadata: ${error.message}. Continue with sdkmanager download.`,
+        );
+      }
+
+      console.log("Installing required Android SDK packages...");
+      ensureAndroidSdkPackages(sdkmanagerPath, sdkRoot, [
+        "platform-tools",
+        "emulator",
+      ]);
+
+      const imagePackage = installSystemImagePackage(sdkmanagerPath, sdkRoot);
+      console.log(`Creating AVD: ${avdName}`);
+      createAvd(avdmanagerPath, avdName, imagePackage);
+      avds = listAvds(emulatorPath);
+    }
+
+    const targetAvd = avds.includes(avdName) ? avdName : avds[0];
+    console.log(`Starting Android emulator: ${targetAvd}`);
+    startAvd(emulatorPath, targetAvd, args);
+
+    const serial = await waitForAdbDevice(adbPath, 180000);
+    await waitForBootComplete(adbPath, serial, 180000);
+    console.log(`Emulator ready: ${serial}`);
+  }
+
+  deviceState = listConnectedDevices(adbPath);
+  if (deviceState.devices.length === 0) {
+    throw new Error(
+      "No Android device is connected. Connect a TV/box via adb or enable --auto-emulator.",
+    );
+  }
+
+  const deviceSerial = pickPrimaryDeviceSerial(deviceState);
+  const targetSerial = preferredRealDeviceSerial || deviceSerial;
+  if (!targetSerial) {
+    throw new Error("Unable to resolve target adb device serial.");
+  }
+
+  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;
+    }
+  } else {
+    console.log("Skip runtime setup due to --skip-runtime-setup.");
+  }
+
+  console.log(
+    `Android environment is ready for project: ${projectRoot}, device=${targetSerial}`,
+  );
+  return {
+    projectRoot,
+    adbPath,
+    deviceSerial: targetSerial,
+    hostIp,
+  };
+}
+
+async function runRunDev(args) {
+  const projectRoot = args.project ? path.resolve(args.project) : process.cwd();
+  if (!exists(path.join(projectRoot, "package.json"))) {
+    throw new Error(`Missing package.json in project root: ${projectRoot}`);
+  }
+
+  let setupResult = null;
+  if (!toBooleanFlag(args["skip-env-check"], false)) {
+    setupResult = await runSetupAndroidEnv({
+      ...args,
+      project: projectRoot,
+      "skip-runtime-setup": args["skip-runtime-setup"],
+    });
+  } else {
+    console.log("Skip Android environment check due to --skip-env-check.");
+  }
+
+  const command = resolvePackageManagerCommand(projectRoot);
+  const autoLoadLocalBundle = toBooleanFlag(
+    args["auto-load-local-bundle"],
+    true,
+  );
+  const serverPort = Number(args.port || DEFAULT_DEV_SERVER_PORT);
+
+  console.log(
+    `Starting dev server with '${command.command} ${command.args.join(" ")}'...`,
+  );
+  const child = spawn(command.command, command.args, {
+    cwd: projectRoot,
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+
+  if (autoLoadLocalBundle) {
+    try {
+      const adbPath =
+        (setupResult && setupResult.adbPath) ||
+        resolveAndroidTool("adb", resolveAndroidSdkRoot().sdkRoot);
+      if (adbPath) {
+        const serial =
+          (setupResult && setupResult.deviceSerial) ||
+          pickPrimaryDeviceSerial(listConnectedDevices(adbPath));
+        const hostIp =
+          (setupResult && setupResult.hostIp) ||
+          (typeof args["server-host"] === "string"
+            ? args["server-host"]
+            : "") ||
+          getLocalIPv4Address();
+
+        if (serial && hostIp) {
+          console.log(`Waiting for local dev server on port ${serverPort}...`);
+          await waitForPort("127.0.0.1", serverPort, 150000);
+          await autoLoadLocalBundleOnRuntime(
+            adbPath,
+            serial,
+            projectRoot,
+            hostIp,
+            serverPort,
+            args,
+          );
+        } else {
+          console.log(
+            "Skip auto local-bundle trigger: missing adb device or local host IP.",
+          );
+        }
+      } else {
+        console.log("Skip auto local-bundle trigger: adb is unavailable.");
+      }
+    } catch (error) {
+      console.log(`Auto local-bundle trigger failed: ${error.message}`);
+    }
+  }
+
+  await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("exit", (code, signal) => {
+      if (code === 0 || signal === "SIGINT" || signal === "SIGTERM") {
+        resolve(true);
+      } else {
+        reject(
+          new Error(`Dev server exited with code ${code}, signal ${signal}`),
+        );
+      }
+    });
+  });
+}
+
+async function runRunEsapp(args) {
+  const projectRoot = args.project ? path.resolve(args.project) : process.cwd();
+  let setupResult = null;
+  if (!toBooleanFlag(args["skip-env-check"], false)) {
+    setupResult = await runSetupAndroidEnv({
+      ...args,
+      project: projectRoot,
+      "skip-runtime-setup": args["skip-runtime-setup"],
+    });
+  } else {
+    console.log("Skip Android environment check due to --skip-env-check.");
+  }
+
+  const sdkState = resolveAndroidSdkRootForSetup();
+  const adbPath =
+    (setupResult && setupResult.adbPath) ||
+    (await resolveAdbPathForSetup(args, sdkState.sdkRoot));
+  if (!adbPath) {
+    throw new Error("adb is unavailable for run-esapp.");
+  }
+
+  let serial = typeof args.device === "string" ? args.device.trim() : "";
+  if (!serial && setupResult && setupResult.deviceSerial) {
+    serial = setupResult.deviceSerial;
+  }
+
+  if (
+    !serial &&
+    typeof args["device-ip"] === "string" &&
+    args["device-ip"].trim()
+  ) {
+    const endpoint = normalizeDeviceEndpoint(args["device-ip"]);
+    console.log(`Trying to connect device: ${endpoint}`);
+    const connectResult = tryAdbConnect(adbPath, endpoint);
+    if (!connectResult.connected) {
+      throw new Error(
+        `Failed to connect device ${endpoint}: ${
+          connectResult.output || "unknown adb connect error"
+        }`,
+      );
     }
+    await delay(600);
+  }
+
+  if (!serial) {
+    const state = listConnectedDevices(adbPath);
+    serial = pickPrimaryDeviceSerial(state);
   }
+  if (!serial) {
+    throw new Error(
+      "No Android device available. Use --device/--device-ip or run setup-android-env first.",
+    );
+  }
+
+  const launchUri = buildEsappLaunchUri(args, projectRoot, {
+    pkg: resolveProjectAppPackage(projectRoot),
+    from: "cmd",
+  });
+  const runtimePackage =
+    typeof args["runtime-package"] === "string" &&
+    args["runtime-package"].trim()
+      ? args["runtime-package"].trim()
+      : RUNTIME_PACKAGE_NAME;
+
+  console.log("Launching ES app via protocol...");
+  console.log(`- device: ${serial}`);
+  console.log(`- runtime: ${runtimePackage}`);
+  console.log(`- uri: ${launchUri}`);
+  startEsappOnRuntimeByUri(adbPath, serial, runtimePackage, launchUri);
+  console.log("ES app launch command sent.");
 }
 
 function resolveSkillsSource() {
@@ -97,6 +2273,16 @@ function parseArgs(argv) {
   return args;
 }
 
+function toBooleanFlag(value, defaultValue) {
+  if (typeof value === "undefined") return defaultValue;
+  if (typeof value === "boolean") return value;
+
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return defaultValue;
+}
+
 function printHelp() {
   console.log(`quicktvui-ai v${PACKAGE_VERSION}
 
@@ -108,14 +2294,61 @@ Commands:
   doctor     Check whether skills and local QuickTVUI rules are available
   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-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)
+  run-esapp  Launch an ES app on runtime via esapp:// protocol
   prompt     Print an LLM-ready installation prompt block
   help       Show this message
 
 Options:
   --dir <path>      Custom skill installation directory
   --project <path>  Project root for @quicktvui/ai checks (default: current dir)
+  --dest <path>     Destination base directory for create-project
+  --offline         Skip git clone and use bundled template directly
+  --skip-install    Skip dependency install in create-project
   --strict          Non-zero exit in doctor when checks fail
   --lang <code>     Prompt language for 'prompt' command: zh | en
+  --gemini-dir <path> Gemini config directory (default: ~/.gemini or $GEMINI_CLI_HOME/.gemini)
+  --skip-gemini-config Skip updating Gemini bridge files during init/update
+  --yes             Non-interactive mode; accept default prompts
+  --no-interactive  Disable interactive prompts
+  --node-major <n>  Target Node.js LTS major for setup-vue-env (default: 20)
+  --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
+  --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
+  --force-runtime-install Force reinstall runtime apk in direct mode
+  --skip-runtime-setup  Skip runtime setup stage in setup-android-env/run-dev
+  --auto-load-local-bundle <true|false> Try auto trigger runtime to load local bundle in run-dev
+  --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
+  --ver <version>   ES app version for run-esapp structured mode
+  --min-ver <ver>   ES app minVer for run-esapp structured mode
+  --repository <url> Repository URL for run-esapp structured mode
+  --uri <uri>       ES app load URI (local/remote/assets/file) for run-esapp structured mode
+  --from <from>     Caller marker for run-esapp (default: cmd)
+  --args <json>     Startup args JSON string for run-esapp
+  --exp <json>      Startup exp JSON string for run-esapp
+  --flags <n>       Startup flags for run-esapp (supports old 100/200/300/400 mapping)
+  --use-latest <true|false> Pass useLatest for run-esapp
 `);
 }
 
@@ -193,6 +2426,191 @@ function installSkills(installDir) {
   return { installDir, sourceDir };
 }
 
+function resolveGeminiConfigDir(args) {
+  if (typeof args["gemini-dir"] === "string" && args["gemini-dir"].trim()) {
+    return path.resolve(args["gemini-dir"].trim());
+  }
+
+  const customGeminiHome = process.env.GEMINI_CLI_HOME
+    ? String(process.env.GEMINI_CLI_HOME).trim()
+    : "";
+  if (customGeminiHome) {
+    const resolved = path.resolve(customGeminiHome);
+    if (path.basename(resolved).toLowerCase() === ".gemini") {
+      return resolved;
+    }
+    return path.join(resolved, ".gemini");
+  }
+
+  return path.join(os.homedir(), ".gemini");
+}
+
+function buildGeminiBridgeImportPaths(installDir) {
+  const preferredFiles = [
+    "SKILL.md",
+    path.join("references", "create-project-checklist.md"),
+    path.join("references", "dev-env-checklist.md"),
+    path.join("references", "esapp-protocol-cheatsheet.md"),
+  ];
+
+  const importPaths = [];
+  for (const relPath of preferredFiles) {
+    const absolutePath = path.join(installDir, relPath);
+    if (exists(absolutePath)) {
+      importPaths.push(absolutePath);
+    }
+  }
+
+  if (importPaths.length === 0) {
+    importPaths.push(path.join(installDir, "SKILL.md"));
+  }
+
+  return importPaths;
+}
+
+function updateGeminiBridgeConfig(args, installDir) {
+  if (toBooleanFlag(args["skip-gemini-config"], false)) {
+    return {
+      skipped: true,
+      reason: "flag",
+    };
+  }
+
+  const geminiDir = resolveGeminiConfigDir(args);
+  ensureDir(geminiDir);
+
+  const geminiMdPath = path.join(geminiDir, "GEMINI.md");
+  const settingsPath = path.join(geminiDir, "settings.json");
+  const importPaths = buildGeminiBridgeImportPaths(installDir);
+
+  const bridgeBlock = [
+    QUICKTVUI_GEMINI_BRIDGE_START,
+    "QuickTVUI global skill bridge (managed by quicktvui-ai assistant).",
+    ...importPaths.map((importPath) => `@${importPath}`),
+    QUICKTVUI_GEMINI_BRIDGE_END,
+  ].join("\n");
+
+  const beforeGeminiMd = exists(geminiMdPath)
+    ? fs.readFileSync(geminiMdPath, "utf8")
+    : "";
+  const bridgePattern = new RegExp(
+    `${escapeRegExp(QUICKTVUI_GEMINI_BRIDGE_START)}[\\s\\S]*?${escapeRegExp(QUICKTVUI_GEMINI_BRIDGE_END)}`,
+    "m",
+  );
+  let nextGeminiMd;
+  if (bridgePattern.test(beforeGeminiMd)) {
+    nextGeminiMd = beforeGeminiMd.replace(bridgePattern, bridgeBlock);
+  } else {
+    const trimmed = beforeGeminiMd.replace(/\s*$/, "");
+    nextGeminiMd = trimmed
+      ? `${trimmed}\n\n${bridgeBlock}\n`
+      : `${bridgeBlock}\n`;
+  }
+
+  let geminiMdUpdated = false;
+  let geminiMdBackup = null;
+  if (nextGeminiMd !== beforeGeminiMd) {
+    geminiMdBackup = backupFile(geminiMdPath);
+    fs.writeFileSync(geminiMdPath, nextGeminiMd, "utf8");
+    geminiMdUpdated = true;
+  }
+
+  const result = {
+    skipped: false,
+    geminiDir,
+    geminiMdPath,
+    settingsPath,
+    importPaths,
+    geminiMdUpdated,
+    geminiMdBackup,
+    settingsUpdated: false,
+    settingsBackup: null,
+    settingsParseError: null,
+  };
+
+  let settings = {};
+  const beforeSettings = exists(settingsPath)
+    ? fs.readFileSync(settingsPath, "utf8")
+    : "";
+  if (beforeSettings.trim()) {
+    try {
+      settings = JSON.parse(beforeSettings);
+    } catch (error) {
+      result.settingsParseError = error.message;
+      return result;
+    }
+  }
+
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    settings = {};
+  }
+  if (!settings.context || typeof settings.context !== "object") {
+    settings.context = {};
+  }
+
+  const current = settings.context.fileName;
+  const normalizedList = Array.isArray(current)
+    ? current
+        .map((item) => String(item).trim())
+        .filter((item) => item.length > 0)
+    : typeof current === "string" && current.trim()
+      ? [current.trim()]
+      : [];
+
+  const lowerSet = new Set(normalizedList.map((item) => item.toLowerCase()));
+  for (const fileName of DEFAULT_GEMINI_CONTEXT_FILENAMES) {
+    if (!lowerSet.has(fileName.toLowerCase())) {
+      normalizedList.push(fileName);
+      lowerSet.add(fileName.toLowerCase());
+    }
+  }
+  settings.context.fileName = normalizedList;
+
+  const nextSettings = `${JSON.stringify(settings, null, 2)}\n`;
+  if (nextSettings !== beforeSettings) {
+    result.settingsBackup = backupFile(settingsPath);
+    fs.writeFileSync(settingsPath, nextSettings, "utf8");
+    result.settingsUpdated = true;
+  }
+
+  return result;
+}
+
+function printGeminiBridgeResult(state) {
+  if (!state) return;
+  if (state.error) {
+    console.log(`- Gemini config: failed (${state.error})`);
+    console.log(
+      `  Hint: rerun with --skip-gemini-config or fix filesystem permission.`,
+    );
+    return;
+  }
+  if (state.skipped) {
+    console.log(`- Gemini config: skipped (--skip-gemini-config)`);
+    return;
+  }
+
+  console.log(`- Gemini config dir: ${state.geminiDir}`);
+  console.log(
+    `- Gemini bridge block: ${state.geminiMdUpdated ? "updated" : "already up to date"}`,
+  );
+  console.log(
+    `- Gemini context.fileName: ${
+      state.settingsParseError
+        ? "skipped (settings.json parse failed)"
+        : state.settingsUpdated
+          ? "updated"
+          : "already up to date"
+    }`,
+  );
+  if (state.settingsParseError) {
+    console.log(`  Warning: ${state.settingsParseError}`);
+    console.log(
+      `  Hint: fix ${state.settingsPath} JSON and rerun 'quicktvui-ai init'.`,
+    );
+  }
+}
+
 function printDoctorReport(skillState, projectState, projectRoot) {
   console.log(`Skill dir: ${skillState.installDir}`);
   console.log(`- Directory exists: ${skillState.exists ? "yes" : "no"}`);
@@ -220,9 +2638,16 @@ function printDoctorReport(skillState, projectState, projectRoot) {
 async function runInit(args) {
   const installDir = getInstallDir(args);
   const result = installSkills(installDir);
+  let geminiState;
+  try {
+    geminiState = updateGeminiBridgeConfig(args, result.installDir);
+  } catch (error) {
+    geminiState = { error: error.message };
+  }
   console.log(`Installed QuickTVUI skill assets.`);
   console.log(`- source: ${result.sourceDir}`);
   console.log(`- target: ${result.installDir}`);
+  printGeminiBridgeResult(geminiState);
   console.log(`Next: restart/reload your AI agent so it can rescan skills.`);
 }
 
@@ -276,9 +2701,78 @@ async function runValidate(args) {
 async function runUpdate(args) {
   const installDir = getInstallDir(args);
   const result = installSkills(installDir);
+  let geminiState;
+  try {
+    geminiState = updateGeminiBridgeConfig(args, result.installDir);
+  } catch (error) {
+    geminiState = { error: error.message };
+  }
   console.log(`Updated QuickTVUI skill assets.`);
   console.log(`- source: ${result.sourceDir}`);
   console.log(`- target: ${result.installDir}`);
+  printGeminiBridgeResult(geminiState);
+}
+
+function cloneTemplateProject(targetDir) {
+  runCommand("git", ["clone", "--depth", "1", TEMPLATE_REPO_URL, targetDir]);
+  removeDirectoryIfExists(path.join(targetDir, ".git"));
+}
+
+function copyBundledTemplateProject(targetDir) {
+  const templateSource = resolveBundledTemplateSource();
+  copyDirectoryRecursive(templateSource, targetDir);
+  removeDirectoryIfExists(path.join(targetDir, ".git"));
+}
+
+async function runCreateProject(args) {
+  const projectName = args._[1];
+  if (!projectName) {
+    throw new Error(
+      "Missing project name. Usage: quicktvui-ai create-project <project-name>",
+    );
+  }
+
+  const destinationBase = args.dest ? path.resolve(args.dest) : process.cwd();
+  ensureDir(destinationBase);
+
+  const targetDir = path.join(destinationBase, projectName);
+  if (exists(targetDir) && !isDirectoryEmpty(targetDir)) {
+    throw new Error(`Target directory is not empty: ${targetDir}`);
+  }
+  ensureDir(targetDir);
+
+  let usedSource = "bundled-template";
+  let cloneError;
+
+  if (!args.offline) {
+    try {
+      cloneTemplateProject(targetDir);
+      usedSource = "git-clone";
+    } catch (error) {
+      cloneError = error;
+      removeDirectoryIfExists(targetDir);
+      ensureDir(targetDir);
+    }
+  }
+
+  if (usedSource !== "git-clone") {
+    copyBundledTemplateProject(targetDir);
+  }
+
+  ensureProjectPackageRules(targetDir, projectName);
+  installProjectDependencies(targetDir, args);
+
+  console.log(`Created QuickTVUI project: ${targetDir}`);
+  console.log(`- source: ${usedSource}`);
+  if (cloneError) {
+    console.log(`- clone fallback reason: ${cloneError.message}`);
+  }
+  console.log(
+    "- 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'",
+  );
 }
 
 function buildPrompt(lang) {
@@ -300,7 +2794,24 @@ quicktvui-ai doctor
 npm install @quicktvui/ai --save-dev
 \`\`\`
 
-安装完成后请提醒用户重启或 reload AI Agent，以便重新扫描 ~/.agents/skills/quicktvui。`;
+安装完成后请提醒用户重启或 reload AI Agent，以便重新扫描 ~/.agents/skills/quicktvui。
+并提示：quicktvui-ai init 会自动更新 ~/.gemini/GEMINI.md 与 ~/.gemini/settings.json 的 QuickTVUI bridge 配置。
+
+创建项目时优先使用：
+\`\`\`bash
+quicktvui-ai create-project <project-name>
+\`\`\`
+该命令在 git clone 失败时会自动回退到本地内置模板。
+
+项目创建后可执行：
+\`\`\`bash
+quicktvui-ai setup-vue-env --project <project-path>
+quicktvui-ai setup-android-env --project <project-path>
+quicktvui-ai run-dev --project <project-path>
+quicktvui-ai run-esapp --project <project-path> --pkg <es-package>
+# 或一键
+quicktvui-ai setup-all-env --project <project-path>
+\`\`\``;
   }
 
   return `# Install QuickTVUI AI Skill Runtime
@@ -319,7 +2830,24 @@ If the user is inside a QuickTVUI project, also run:
 npm install @quicktvui/ai --save-dev
 \`\`\`
 
-After installation, ask the user to restart or reload the AI Agent so it rescans ~/.agents/skills/quicktvui.`;
+After installation, ask the user to restart or reload the AI Agent so it rescans ~/.agents/skills/quicktvui.
+Also note that quicktvui-ai init auto-updates QuickTVUI bridge config in ~/.gemini/GEMINI.md and ~/.gemini/settings.json.
+
+When creating a project, prefer:
+\`\`\`bash
+quicktvui-ai create-project <project-name>
+\`\`\`
+This command auto-fallbacks to bundled local template when git clone fails.
+
+After project creation, you can run:
+\`\`\`bash
+quicktvui-ai setup-vue-env --project <project-path>
+quicktvui-ai setup-android-env --project <project-path>
+quicktvui-ai run-dev --project <project-path>
+quicktvui-ai run-esapp --project <project-path> --pkg <es-package>
+# or one command
+quicktvui-ai setup-all-env --project <project-path>
+\`\`\``;
 }
 
 async function runPrompt(args) {
@@ -340,6 +2868,18 @@ async function runCli(argv) {
       return runValidate(args);
     case "update":
       return runUpdate(args);
+    case "create-project":
+      return runCreateProject(args);
+    case "setup-vue-env":
+      return runSetupVueEnv(args);
+    case "setup-android-env":
+      return runSetupAndroidEnv(args);
+    case "setup-all-env":
+      return runSetupAllEnv(args);
+    case "run-dev":
+      return runRunDev(args);
+    case "run-esapp":
+      return runRunEsapp(args);
     case "prompt":
       return runPrompt(args);
     case "help":