@quicktvui/ai-cli 0.1.0 → 1.1.1

package/README.md

@@ -15,7 +15,17 @@ quicktvui-ai init
 quicktvui-ai doctor
 quicktvui-ai validate
 quicktvui-ai update
+quicktvui-ai create-project quick-tv-app
+quicktvui-ai setup-vue-env --project ./quick-tv-app
+quicktvui-ai setup-android-env --project ./quick-tv-app
+quicktvui-ai setup-all-env --project ./quick-tv-app
+quicktvui-ai run-dev --project ./quick-tv-app
+quicktvui-ai run-esapp --project ./quick-tv-app --pkg es.hello.world
 quicktvui-ai prompt --lang zh
+
+# alias commands for create-project
+quicktvui-ai-create-project quick-tv-app
+quicktvui-aicreate-project quick-tv-app
 ```
 
 ## Default install path
@@ -26,8 +36,38 @@ quicktvui-ai prompt --lang zh
 
 - `--dir <path>`: custom skill path
 - `--project <path>`: custom project root for rule checks
+- `--dest <path>`: destination base directory for `create-project`
+- `--offline`: use bundled template directly for `create-project`
+- `--skip-install`: skip dependency install for `create-project`
 - `--strict`: fail on doctor check issues
 - `--lang <code>`: prompt language for `prompt` command (`zh` or `en`)
+- `--gemini-dir <path>`: custom Gemini config directory (default `~/.gemini`, or `$GEMINI_CLI_HOME/.gemini`)
+- `--skip-gemini-config`: skip updating Gemini bridge config during `init`/`update`
+- `--node-major <n>`: target Node.js LTS major for `setup-vue-env` (default `20`)
+- `--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`
+- `--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
+- `--force-runtime-install`: force reinstall runtime in `direct` mode
+- `--skip-runtime-setup`: skip runtime setup in `setup-android-env`/`run-dev`
+- `--auto-load-local-bundle <true|false>`: 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 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
 
 ## Typical flow
 
@@ -38,6 +78,103 @@ quicktvui-ai doctor
 
 Then reload your AI agent so it rescans local skills.
 
+`init`/`update` also auto-maintains Gemini global context files:
+
+- updates `~/.gemini/GEMINI.md` with QuickTVUI `@.../SKILL.md` bridge block
+- ensures `~/.gemini/settings.json` contains `context.fileName` entries:
+  `GEMINI.md`, `AGENTS.md`, `SKILL.md`, `CONTEXT.md`
+
+## Create project with network fallback
+
+```bash
+quicktvui-ai create-project quick-tv-app
+```
+
+This command:
+
+1. Tries to clone `quicktvui-template` from GitHub.
+2. Falls back to the bundled local template if clone fails.
+3. Updates `package.json` (`name`, `version`).
+4. Ensures `@quicktvui/ai` exists in `devDependencies`.
+5. Installs dependencies (`yarn install`, or `npm install` fallback).
+
+## Configure Android env (device/emulator + runtime)
+
+```bash
+quicktvui-ai setup-android-env --project ./quick-tv-app
+```
+
+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
+```
+
+## Configure Vue env (Node + package manager)
+
+```bash
+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.
+3. Installs project dependencies (`yarn install` or `npm install` fallback).
+
+## Configure All Dev Envs
+
+```bash
+quicktvui-ai setup-all-env --project ./quick-tv-app
+```
+
+This command runs `setup-vue-env` and `setup-android-env` sequentially.
+
+## Run development server
+
+```bash
+quicktvui-ai run-dev --project ./quick-tv-app
+```
+
+This command:
+
+1. Runs `setup-android-env` by default.
+2. Starts project dev script (`yarn dev`, `pnpm dev`, or `npm run dev`).
+3. Waits for local server port (default `38989`) and auto triggers runtime to load local bundle.
+4. Supports `run-esapp` structured options (`--pkg/--ver/--repository/...`) or `--esapp-uri` to override auto launch URI.
+
+## Run ES app by protocol
+
+```bash
+# structured mode (recommended for AI)
+quicktvui-ai run-esapp --project ./quick-tv-app --pkg es.hello.world --from cmd
+
+# local dev bundle
+quicktvui-ai run-esapp --project ./quick-tv-app --pkg es.hello.world --uri 192.168.1.10:38989
+
+# remote repository + pinned version
+quicktvui-ai run-esapp --project ./quick-tv-app --pkg liulipeng/com.zoo --ver 1.0.0 --repository http://repo.quicktvui.com/repository/rpk
+
+# raw URI passthrough (full compatibility)
+quicktvui-ai run-esapp --esapp-uri 'esapp://action/start?from=cmd&pkg=es.hello.world&uri=assets://hello.rpk'
+```
+
+Full protocol reference: [`docs/esapp-protocol.md`](./docs/esapp-protocol.md)
+
 ## Generate LLM install prompt
 
 ```bash

package/bin/quicktvui-ai-create-project.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/index");
+
+runCli(["create-project", ...process.argv.slice(2)]).catch((error) => {
+  console.error(`[quicktvui-ai] ${error.message}`);
+  process.exit(1);
+});

package/bin/quicktvui-aicreate-project.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/index");
+
+runCli(["create-project", ...process.argv.slice(2)]).catch((error) => {
+  console.error(`[quicktvui-ai] ${error.message}`);
+  process.exit(1);
+});

package/docs/esapp-protocol.md

@@ -0,0 +1,134 @@
+# ESApp Protocol Reference (`esapp://`, `quicktv://`, `appcast://`)
+
+This document summarizes runtime launch protocol behavior from:
+
+- `es-sdk/sdk-core-entry/src/main/AndroidManifest.xml`
+- `es-sdk/sdk-core/src/main/java/eskit/sdk/core/utils/MapperUtils.java`
+- `es-sdk/sdk-core/src/main/java/eskit/sdk/core/protocol/Protocol_2.java`
+- `es-sdk/sdk-core/src/main/java/eskit/sdk/core/EsData.java`
+
+## 1) Supported URI Schemes
+
+Runtime entry activity accepts:
+
+- `esapp://`
+- `quicktv://`
+- `appcast://`
+
+## 2) Parsing Modes
+
+### Mode A: V1 action URI (recommended for command tools)
+
+```text
+esapp://action/start?from=cmd&pkg=es.hello.world&...
+```
+
+Behavior:
+
+- Recognized only when `scheme=esapp` and `host=action`.
+- `/start` maps to `action=start_es`.
+- All query params are forwarded to protocol JSON.
+
+### Mode B: V2 package URI (esapp/quicktv/appcast)
+
+```text
+esapp://es.hello.world?from=cmd
+esapp://es.hello.world/1.0.3?from=cmd
+quicktv://es.hello.world?from=cmd
+appcast://es.hello.world/1.0.3?from=cmd
+```
+
+Behavior:
+
+- If `repository` is absent:
+  - `host` is treated as `pkg`
+  - first path segment (if present) is treated as `ver`
+- If `repository` is present:
+  - `pkg = host + "/" + firstPathSegment`
+  - `ver = secondPathSegment` (optional)
+
+Repository-mode examples:
+
+```text
+esapp://huantv/zoo?repository=http://repo.example/rpk&from=cmd
+esapp://huantv/zoo/1.0.0?repository=http://repo.example/rpk&from=cmd
+```
+
+## 3) Required Fields
+
+At dispatch stage (`Protocol_2`):
+
+- `from` is required (empty is rejected)
+- `pkg` is required for `start_es`
+
+So command tools should always include:
+
+- `from=cmd` (or your caller id)
+- `pkg=<es-package>`
+
+## 4) Launch Query Parameters (Runtime `EsData` mapping)
+
+Supported startup keys include:
+
+- `pkg`
+- `ver`
+- `minVer`
+- `repository`
+- `uri`
+- `args` (JSON string)
+- `exp` (JSON string)
+- `flags`
+- `useLatest`
+- `name`
+- `icon`
+- `isCard`
+- `transparent`
+- `pageTag`
+- `pageLimit`
+- `bgColor`
+- `enc`
+- `checkNetwork`
+- `splash`
+- `feature_single_activity`
+
+## 5) Flags Compatibility
+
+`flags` supports legacy values and maps internally:
+
+- `100 -> CLEAR_TASK`
+- `200 -> SINGLE_TASK`
+- `300 -> SINGLE_TOP`
+- `400 -> SINGLE_INSTANCE`
+- `236 -> CLEAR_TASK | SINGLE_TASK`
+- `364 -> CLEAR_TASK | SINGLE_TOP`
+- `500 -> CLEAR_TASK | SINGLE_INSTANCE`
+
+## 6) URI Source Types (`uri=...`)
+
+Runtime supports common local/remote load forms through `uri`, including:
+
+- LAN debug server: `192.168.x.x:38989` or `http://192.168.x.x:38989`
+- Remote package: `http://.../xxx.rpk` or `https://...`
+- Assets: `assets://...`
+- Local file: `file://...`
+
+## 7) ADB Launch Form
+
+Typical launch command:
+
+```bash
+adb shell am start \
+  -a android.intent.action.VIEW \
+  -p com.extscreen.runtime \
+  -d 'esapp://action/start?from=cmd&pkg=es.hello.world'
+```
+
+## 8) CLI Support (`@quicktvui/ai-cli`)
+
+`quicktvui-ai run-esapp` supports:
+
+- Raw URI passthrough: `--esapp-uri '<uri>'` (full compatibility)
+- Structured launch: `--pkg/--ver/--min-ver/--repository/--uri/--args/--exp/...`
+- Extra custom query map: `--esapp-query '{"k":"v"}'`
+
+This combination covers all runtime protocol variants while preserving backward compatibility.