@zsukim/ctv-run 1.0.0

package/README.md

@@ -0,0 +1,277 @@
+# 📺 ctv-run
+
+> React, Vue 등 **웹 기술로 만든 TV 앱**을 Vizio, LG webOS, Fire TV, Samsung Tizen에 배포하고 실행하는 CLI 도구입니다.
+
+스마트 TV 플랫폼마다 다른 개발 환경 구축과 앱 실행 과정을 단일 명령어로 자동화합니다.
+
+---
+
+## 🗂 목차
+
+1. [실행 모드 개요](#실행-모드-개요)
+2. [ctv.config.json](#ctvconfign)
+3. [플랫폼별 사전 준비](#플랫폼별-사전-준비)
+4. [플랫폼별 사용법](#플랫폼별-사용법)
+5. [주의사항](#주의사항)
+
+---
+
+## 실행 모드 개요
+
+모든 플랫폼은 두 가지 모드를 지원합니다.
+
+| 모드 | 옵션 | 설명 |
+|------|------|------|
+| **Live Mode** | (기본값) | 개발 서버 URL을 TV에 주입. HMR 지원 |
+| **Static Mode** | `--target=dist` | 빌드 결과물을 TV에 직접 설치 |
+
+> **Vizio**는 구조상 항상 URL이 필요하므로 Live Mode만 지원합니다.
+
+---
+
+## ctv.config.json
+
+프로젝트 루트에 생성하면 CLI 옵션을 생략할 수 있습니다. CLI 옵션이 항상 우선합니다.
+
+```json
+{
+  "vizio": {
+    "ip": "192.168.11.27",
+    "url": "http://192.168.11.10:3300"
+  },
+  "fire": {
+    "ip": "192.168.11.20",
+    "package": "com.example.tvapp",
+    "url": "http://192.168.11.10:3300",
+    "adbPath": "/usr/local/bin/adb",
+    "androidAssetsPath": "/path/to/android/app/src/main/assets"
+  },
+  "tizen": {
+    "ip": "192.168.11.30",
+    "appId": "A123456789.MyApp"
+  },
+  "webos": {
+    "deviceName": "my-lg-tv",
+    "appId": "com.example.tvapp"
+  },
+  "common": {
+    "devServerPort": 3300
+  }
+}
+```
+
+### Fields
+
+**Vizio**
+
+| Field | 필수 | Description |
+|-------|------|-------------|
+| `ip` | ✅ | Vizio TV 로컬 IP |
+| `url` | | TV에서 로드할 개발 서버 URL |
+
+**Fire TV**
+
+| Field | 필수 | Description |
+|-------|------|-------------|
+| `ip` | ✅ | Fire TV 로컬 IP |
+| `package` | ✅ | Android 앱 패키지명 |
+| `url` | | Live Mode에서 주입할 개발 서버 URL |
+| `adbPath` | | adb 실행 경로 (기본값: `adb`) |
+| `androidAssetsPath` | Static Mode 시 ✅ | dist 파일이 복사될 Android `assets` 폴더 절대 경로 |
+
+**Tizen**
+
+| Field | 필수 | Description |
+|-------|------|-------------|
+| `ip` | ✅ | Samsung Tizen TV 로컬 IP |
+| `appId` | | Tizen 앱 고유 ID (없으면 자동 생성) |
+
+**WebOS**
+
+| Field | 필수 | Description |
+|-------|------|-------------|
+| `deviceName` | ✅ | ares-cli에 등록된 기기 이름 |
+| `appId` | | webOS 앱 ID (기본값: `com.ctvrun.app`) |
+
+**Common**
+
+| Field | Description |
+|-------|-------------|
+| `devServerPort` | Live Mode에서 사용할 개발 서버 포트 (기본값: `3000`) |
+
+> 💡 TV IP가 개발자마다 다를 수 있으므로 `ctv.config.json`은 `.gitignore`에 추가하고, `ctv.config.sample.json`을 저장소에 공유하는 것을 권장합니다.
+
+---
+
+## 플랫폼별 사전 준비
+
+### Vizio
+
+Playwright Chromium이 필요합니다.
+
+```bash
+npx playwright install chromium
+```
+
+### Fire TV
+
+ADB가 설치되어 있어야 하며, TV에서 **개발자 옵션 → ADB 디버깅**이 활성화되어 있어야 합니다.
+
+```bash
+# 연결 확인
+adb devices
+```
+
+Static Mode(`--target=dist`) 사용 시 앱 코드에 다음 설정이 필요합니다.
+
+**AndroidManifest.xml**
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+
+<application android:usesCleartextTraffic="true" ...>
+```
+
+**MainActivity.kt** — ADB로 주입된 URL 처리
+
+```kotlin
+val intentUrl = intent.getStringExtra("TARGET_URL")
+
+if (!intentUrl.isNullOrEmpty()) {
+    webView.loadUrl(intentUrl)           // Live Mode
+} else {
+    webView.loadUrl("file:///android_asset/index.html")  // Static Mode
+}
+```
+
+### Tizen
+
+[Tizen Studio](https://developer.tizen.org/development/tizen-studio/download) 설치 후 PATH를 설정합니다.
+
+```bash
+# ~/.zshrc 또는 ~/.bash_profile
+export TIZEN_STUDIO_HOME="$HOME/tizen-studio"
+export PATH="$PATH:$TIZEN_STUDIO_HOME/tools/ide/bin:$TIZEN_STUDIO_HOME/tools"
+```
+
+```bash
+source ~/.zshrc
+
+# 설치 확인
+tizen version
+```
+
+인증서 프로필이 없으면 첫 실행 시 자동으로 생성합니다.
+
+### WebOS
+
+[LG webOS SDK](https://webostv.developer.lge.com) 설치 후 기기를 등록합니다.
+
+```bash
+# 기기 등록 (최초 1회)
+ares-setup-device
+
+# 등록 확인
+ares-setup-device --list
+```
+
+---
+
+## 플랫폼별 사용법 예시
+
+### Vizio
+
+```bash
+# URL 직접 지정
+ctv-run vizio --ip=192.168.11.27 --url=http://192.168.11.10:3300
+
+# 포트만 지정 (로컬 IP 자동 감지)
+ctv-run vizio --ip=192.168.11.27 --port=3300
+```
+
+**작동 원리**
+
+Playwright로 Vizio 웹 런처를 자동 조작하여 페어링(PIN 입력) 후 앱 URL을 주입합니다.
+
+---
+
+### Fire TV
+
+```bash
+# Live Mode — 개발 서버 URL 주입
+ctv-run fire --url=http://192.168.11.10:3300
+
+# Live Mode — 포트만 지정
+ctv-run fire --port=3300
+
+# Static Mode — dist를 Android assets에 복사 후 로컬 실행
+ctv-run fire --target=dist
+```
+
+> Static Mode는 `androidAssetsPath` 설정이 필수입니다.
+
+**작동 원리**
+
+- **Live Mode**: ADB로 앱을 실행하며 `TARGET_URL` extra를 주입합니다.
+- **Static Mode**: dist 파일을 Android `assets` 폴더에 복사한 뒤 앱을 실행합니다. 앱은 `file:///android_asset/index.html`을 로드합니다.
+
+---
+
+### Tizen
+
+```bash
+# Live Mode — 개발 서버로 리다이렉트하는 앱 설치 후 실행
+ctv-run tizen --ip=192.168.11.30
+
+# Static Mode — dist를 .wgt로 패키징하여 TV에 설치
+ctv-run tizen --ip=192.168.11.30 --target=dist
+```
+
+**작동 원리**
+
+- **Live Mode**: 개발 서버로 리다이렉트하는 `index.html`을 포함한 `.wgt`를 설치합니다.
+- **Static Mode**: dist 폴더를 `.wgt`로 패키징하여 TV에 설치합니다.
+
+`config.xml`이 없으면 자동 생성됩니다. 커스터마이징이 필요하면 프로젝트 루트에 `config.xml`을 추가하세요.
+
+디버깅은 Chrome에서 `http://[TV_IP]:9222`로 접속합니다. (TV 설정에서 디버그 모드 활성화 필요)
+
+---
+
+### WebOS
+
+```bash
+# Live Mode — 개발 서버로 리다이렉트하는 앱 설치 후 실행
+ctv-run webos --device=my-lg-tv
+
+# Static Mode — dist를 .ipk로 패키징하여 TV에 설치
+ctv-run webos --device=my-lg-tv --target=dist
+```
+
+**작동 원리**
+
+- **Live Mode**: 개발 서버로 리다이렉트하는 `index.html`을 포함한 `.ipk`를 설치합니다.
+- **Static Mode**: dist 폴더를 `.ipk`로 패키징하여 TV에 설치합니다.
+
+`appinfo.json`이 없으면 자동 생성됩니다.
+
+---
+
+## 주의사항
+
+### 네트워크
+
+개발 PC와 TV는 **동일한 Wi-Fi 또는 유선 네트워크**에 연결되어 있어야 합니다.
+
+### Live Mode 로딩 속도
+
+Vite 개발 서버는 HMR을 위해 모듈을 개별 전송하므로 TV 사양에 따라 **초기 로딩에 10~30초 이상** 걸릴 수 있습니다. 성능 확인이 필요하다면 Static Mode를 사용하세요.
+
+### Tizen 포트 권한
+
+`ctv-run tizen` 실행 시 권한 오류가 발생하면 `sudo`를 붙여 실행하세요.
+
+```bash
+sudo ctv-run tizen --ip=192.168.11.30
+```

package/dist/config.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config();
+// export function getTargetIp(platform: string) {
+//     const configPath = path.join(process.cwd(), 'ctv.config.json');
+//
+//     // 1. 설정 파일이 있으면 읽어오기
+//     if (fs.existsSync(configPath)) {
+//         const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+//         if (config.platforms?.[platform]?.ip) {
+//             return config.platforms[platform].ip;
+//         }
+//     }
+//
+//     // 2. 설정 파일이 없으면 환경변수나 기본값 사용 (테스트용)
+//     return process.env.VIZIO_TV_IP || '0.0.0.0';
+// }
+exports.CONFIG = {
+    DIST_PATH: './dist',
+    PORT: 3000,
+    // .env 파일에 TV_IP=192.168.x.x 형태로 저장하세요
+    VIZIO_TV_IP: process.env.VIZIO_TV_IP || '0.0.0.0',
+    LAUNCHER_URL: 'https://vizio-pm.s3-us-west-1.amazonaws.com/conjure-launcher.html',
+};

package/dist/firetv.js

@@ -0,0 +1,67 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFireTv = runFireTv;
+const child_process_1 = require("child_process");
+const util_1 = require("./util");
+function runFireTv() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const args = process.argv.slice(2);
+        const config = (0, util_1.loadConfig)();
+        const getArg = (name) => { var _a; return (_a = args.find(arg => arg.startsWith(`--${name}=`))) === null || _a === void 0 ? void 0 : _a.split('=')[1]; };
+        const tvIp = getArg('ip') || ((_a = config.firetv) === null || _a === void 0 ? void 0 : _a.ip);
+        const pkg = getArg('package') || ((_b = config.firetv) === null || _b === void 0 ? void 0 : _b.package);
+        const targetArg = getArg('target'); // 'dist' 등이 들어오면 번들 모드로 간주
+        const activity = getArg('activity') || ((_c = config.firetv) === null || _c === void 0 ? void 0 : _c.activity) || '.MainActivity';
+        const appUrl = getArg('url') || `http://${(0, util_1.getLocalIp)()}:5173`;
+        if (!tvIp || !pkg) {
+            console.error(`\n❌ Fire TV 필수 설정(ip, package)이 누락되었습니다!`);
+            return;
+        }
+        console.log(`-----------------------------------------`);
+        console.log(`📡 Target TV IP  : ${tvIp}`);
+        console.log(`📦 Package Name  : ${pkg}`);
+        if (targetArg) {
+            console.log(`📦 Mode          : 🏠 Bundle Mode (Local App)`);
+        }
+        else {
+            console.log(`📦 Mode          : 🌐 Live Mode (Remote URL)`);
+            console.log(`🚀 App URL       : ${appUrl}`);
+        }
+        console.log(`-----------------------------------------`);
+        try {
+            // 1. ADB 연결
+            console.log(`🔗 ADB Connecting to ${tvIp}...`);
+            (0, child_process_1.execSync)(`adb connect ${tvIp}:5555`, { stdio: 'pipe' });
+            // 2. 기존 앱 종료
+            console.log('🔄 Force stopping existing process...');
+            (0, child_process_1.execSync)(`adb -s ${tvIp}:5555 shell am force-stop ${pkg}`);
+            // 3. 실행 커맨드 조립
+            const fullActivityPath = activity.startsWith('.') ? `${pkg}/${activity}` : `${pkg}/${pkg}${activity}`;
+            let launchCmd = `adb -s ${tvIp}:5555 shell am start -n ${fullActivityPath}`;
+            /**
+             * [핵심 로직]
+             * target 인자가 없으면(Live 모드), TARGET_URL 에너테이션을 추가해서 보냅니다.
+             * target 인자가 있으면(Bundle 모드), 그냥 앱만 실행합니다.
+             */
+            if (!targetArg) {
+                launchCmd += ` --es "TARGET_URL" "${appUrl}"`;
+            }
+            console.log('📱 Launching App...');
+            (0, child_process_1.execSync)(launchCmd, { stdio: 'inherit' });
+            console.log(`\n✅ Success! Fire TV launch complete.`);
+        }
+        catch (err) {
+            console.error(`\n❌ Error: ${err.message}`);
+        }
+    });
+}

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const firetv_1 = require("./platforms/firetv");
+const tizen_1 = require("./platforms/tizen");
+const vizio_1 = require("./platforms/vizio");
+const webos_1 = require("./platforms/webos");
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const args = process.argv.slice(2);
+        const platform = args[0]; // ctv-run [vizio | webos | firetv | tizen]
+        if (!platform || platform === '--help' || platform === '-h') {
+            console.log('\n📺 CTV-RUN: Smart TV Deployment Tool');
+            console.log('-----------------------------------------');
+            console.log('사용법: ctv-run [platform] [options]');
+            console.log('\n지원 플랫폼:');
+            console.log('  vizio    - Vizio SmartCast');
+            console.log('  webos    - LG webOS TV');
+            console.log('  fire     - Amazon Fire TV / Android TV');
+            console.log('  tizen    - Samsung Tizen TV');
+            console.log('\n예시:');
+            console.log('  ctv-run webos --device=lg-tv');
+            console.log('  ctv-run tizen --ip=192.168.0.10');
+            console.log('-----------------------------------------\n');
+            return;
+        }
+        try {
+            switch (platform.toLowerCase()) {
+                case 'vizio':
+                    yield (0, vizio_1.runVizio)();
+                    break;
+                case 'webos':
+                    yield (0, webos_1.runWebOS)();
+                    break;
+                case 'fire':
+                    yield (0, firetv_1.runFireTv)();
+                    break;
+                case 'tizen':
+                    yield (0, tizen_1.runTizen)();
+                    break;
+                default:
+                    console.error(`❌ 지원하지 않는 플랫폼입니다: ${platform}`);
+                    process.exit(1);
+            }
+        }
+        catch (err) {
+            console.error(`\n❌ 실행 중 오류 발생: ${err.message}`);
+            process.exit(1);
+        }
+    });
+}
+main();

package/dist/platforms/firetv.js

@@ -0,0 +1,119 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFireTv = runFireTv;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("../utils/config");
+const ip_1 = require("../utils/ip");
+const platform_1 = require("../utils/platform");
+function runFireTv() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const args = process.argv.slice(2);
+        const config = (0, config_1.loadConfig)();
+        const getArg = (0, platform_1.makeArgParser)(args);
+        // 설정 및 인자 파싱
+        const adbBin = getArg('adbPath') || ((_a = config.fire) === null || _a === void 0 ? void 0 : _a.adbPath) || 'adb';
+        const tvIp = getArg('ip') || ((_b = config.fire) === null || _b === void 0 ? void 0 : _b.ip);
+        const pkg = getArg('package') || ((_c = config.fire) === null || _c === void 0 ? void 0 : _c.package);
+        const activity = getArg('activity') || ((_d = config.fire) === null || _d === void 0 ? void 0 : _d.activity) || '.MainActivity';
+        const targetArg = getArg('target');
+        const androidAssetsPath = getArg('assetsPath') || ((_e = config.fire) === null || _e === void 0 ? void 0 : _e.androidAssetsPath);
+        // 앱 URL 결정 (Live Mode 전용)
+        const userUrl = getArg('url') || ((_f = config.fire) === null || _f === void 0 ? void 0 : _f.url);
+        const port = getArg('port') || ((_g = config.fire) === null || _g === void 0 ? void 0 : _g.port) || ((_h = config.common) === null || _h === void 0 ? void 0 : _h.devServerPort) || 3000;
+        const appUrl = userUrl || `http://${(0, ip_1.getLocalIp)()}:${port}`;
+        if (!tvIp || !pkg) {
+            console.error(`\n❌ Fire TV 필수 설정(ip, package)이 누락되었습니다!`);
+            return;
+        }
+        // Static Mode: dist를 Android assets에 복사 (Tizen/WebOS와 동일한 개념)
+        if (targetArg) {
+            if (!androidAssetsPath) {
+                console.error(`\n❌ ctv.config.json에 'androidAssetsPath'가 설정되어 있지 않습니다.`);
+                return;
+            }
+            const distPath = path_1.default.resolve(process.cwd(), targetArg);
+            const finalAssetsPath = path_1.default.isAbsolute(androidAssetsPath)
+                ? androidAssetsPath
+                : path_1.default.resolve(process.cwd(), androidAssetsPath);
+            console.log(`-----------------------------------------`);
+            console.log(`📡 Target TV IP  : ${tvIp}`);
+            console.log(`📦 Package Name  : ${pkg}`);
+            console.log(`🛠  ADB Binary    : ${adbBin}`);
+            console.log(`📦 Mode          : 📂 Static Mode (Assets Embedded)`);
+            console.log(`📂 Path          : ${finalAssetsPath}`);
+            console.log(`-----------------------------------------`);
+            try {
+                const parentPath = path_1.default.dirname(finalAssetsPath);
+                if (!fs_1.default.existsSync(parentPath)) {
+                    console.error(`\n❌ 경로 오류: 부모 폴더가 존재하지 않습니다. (${parentPath})`);
+                    return;
+                }
+                if (fs_1.default.existsSync(finalAssetsPath)) {
+                    (0, child_process_1.execSync)(`rm -rf "${finalAssetsPath}"/*`);
+                }
+                else {
+                    (0, child_process_1.execSync)(`mkdir -p "${finalAssetsPath}"`);
+                }
+                (0, child_process_1.execSync)(`cp -r "${distPath}"/* "${finalAssetsPath}"`);
+                console.log(`✅ Asset copy complete.`);
+            }
+            catch (err) {
+                console.error(`\n❌ 파일 복사 중 에러 발생: ${err.message}`);
+                return;
+            }
+        }
+        else {
+            // Live Mode
+            console.log(`-----------------------------------------`);
+            console.log(`📡 Target TV IP  : ${tvIp}`);
+            console.log(`📦 Package Name  : ${pkg}`);
+            console.log(`🛠  ADB Binary    : ${adbBin}`);
+            console.log(`📦 Mode          : 🌐 Live Mode (Remote URL)`);
+            console.log(`🚀 App URL       : ${appUrl}`);
+            console.log(`-----------------------------------------`);
+        }
+        try {
+            // ADB 연결
+            console.log(`🔗 ADB Connecting to ${tvIp}...`);
+            (0, child_process_1.execSync)(`${adbBin} connect ${tvIp}:5555`, { stdio: 'pipe' });
+            // 기존 앱 종료
+            console.log('🔄 Force stopping existing process...');
+            (0, child_process_1.execSync)(`${adbBin} -s ${tvIp}:5555 shell am force-stop ${pkg}`);
+            // 실행 커맨드 작성
+            const fullActivityPath = activity.startsWith('.')
+                ? `${pkg}/${activity}`
+                : activity;
+            let launchCmd = `${adbBin} -s ${tvIp}:5555 shell am start -n ${fullActivityPath}`;
+            // Live Mode일 때만 URL 주입
+            if (!targetArg) {
+                launchCmd += ` --es "TARGET_URL" "${appUrl}"`;
+            }
+            console.log('📱 Launching App...');
+            (0, child_process_1.execSync)(launchCmd, { stdio: 'inherit' });
+            console.log(`\n✅ Success! Fire TV launch complete.`);
+        }
+        catch (err) {
+            if (err.message.includes('ENOENT')) {
+                console.error(`\n❌ Error: '${adbBin}' 명령어를 찾을 수 없습니다.`);
+            }
+            else {
+                console.error(`\n❌ Error: ${err.message}`);
+            }
+        }
+    });
+}