cleanyourtv-app 딥다이브
— 컴퓨터 없이 폰이 TV에 ADB를 걸어 정리하는 Kotlin 앱

1프로젝트 한줄 요약

cleanyourtv-app은 폰이 직접 ADB 클라이언트가 되어 TV를 읽고(분석), 계획을 보여 주고(확인), 앱을 끄고 새 홈 화면을 설치하는(정리) Android 앱입니다. 앱은 pm disable-user --user 0 <패키지> 같은 명령을 TV 쪽 셸에 보내며, 끈 앱은 pm enable로 되살릴 수 있습니다. 코드는 Kotlin 약 55,000줄(.kt 380개) 규모입니다.

1-1. 같은 이름의 기존 카드(Gathin23/cleanyourtv)와의 관계

카탈로그에는 이미 cleanyourtv-deep-dive.html(Gathin23/cleanyourtv, 컴퓨터용 스크립트·런처)가 있습니다. 두 레포는 다른 저장소이고, 소스에서 확인되는 관계는 아래와 같습니다.

즉 포크가 아니라 “업스트림의 런처와 TV별 목록을 입력으로 쓰는 별도 앱”입니다. 다만 이 체크아웃에는 서브모듈 내용이 비어 있어(gitlink만 존재) 업스트림 런처의 소스는 읽지 못했습니다. 포크 여부는 GitHub 메타데이터의 영역이라 여기서는 판단하지 않습니다.

2왜 주목받는가

TrendShift 목록에서 24위로 큐에 올라온 레포입니다. 순위 말고 소스에서 확인되는 매력은 세 가지입니다.

2-1. 필요한 준비물이 폰 한 대로 줄었다

업스트림 도구는 adb가 설치된 컴퓨터나 코딩 에이전트가 필요합니다. 이 앱은 README 기준으로 Android 9 이상 폰, 같은 Wi-Fi, TV의 네트워크 디버깅만 요구합니다. 앱의 AndroidManifest.xml에서 선언한 권한은 인터넷·네트워크 상태·Wi-Fi 멀티캐스트(TV 찾기)·포그라운드 서비스·알림·생체 인증(USE_BIOMETRIC)뿐이고, 위치·저장소·카메라·연락처는 없습니다.

2-2. 사고가 나도 돌아갈 길을 코드로 강제한다

TV는 잘못 건드리면 리모컨조차 안 먹는 기기입니다. 그래서 이 레포의 설계 문서와 코드는 삭제 대신 비활성화, 변경 전 상태 기록, TV 내부 워치독, 보호 패키지 목록(Denylist.kt), 위험한 TV 계열에서 홈 화면 교체 자동 생략(HomeSwitchRisk.kt)을 갖춥니다. 이는 4장에서 코드로 확인합니다.

2-3. 열흘도 안 되는 사이에 0.1.0에서 0.3.5까지

CHANGELOG.md에는 0.1.0(2026-10-20)부터 0.3.5(2026-10-24)까지 8개 버전이 있고, git 로그의 첫 커밋은 2026-10-19, 총 419 커밋입니다. README는 “AI 코딩 에이전트와 사람의 검토로 개발했다”고 밝힙니다. 짧은 기간에 이만한 규모가 나온 것은 테스트(*Test.kt 121개)와 모듈 규칙 검사가 에이전트 작업의 안전망 역할을 했기 때문으로 읽히지만, 그 테스트들이 통과하는지는 이번 분석에서 실행해 확인하지 않았습니다.

3기술 스택 전체 지도

이 프로젝트에는 백엔드 서버가 없습니다. “백엔드”에 해당하는 것은 폰 앱 안의 순수 Kotlin 모듈(core/*, adb/*)이고, 인프라에 해당하는 것은 GitHub Actions와 재현 가능 빌드용 Docker 이미지입니다.

3-1. 폰 앱 (프론트엔드 + 로직)

3-2. TV 쪽에 설치되는 것

TV에는 두 개의 작은 APK가 번들됩니다. 앱 자산 android/platform/src/main/assets/bundled/에 cleanyourtv-launcher.apk(약 421KB, 업스트림 홈 화면)와 cleanyourtv-curtain.apk(약 66KB, 정리 중 TV 화면에 진행 상황을 보여 주는 “커튼”)가 들어 있습니다. 커튼은 의존성이 없는 별도 TV 앱(:tv:curtain, 허용 외부 의존 0개)입니다.

3-3. 테스트·품질·배포

같은 코드에서 두 가지 스토어 빌드가 나옵니다. full은 GitHub에서 업데이트를 확인하고 추가 모듈을 내려받지만, play는 업데이트 확인·외부 다운로드가 없고 네트워크 보안 설정에 GitHub 호스트가 없습니다(app/src/full, app/src/play의 Store.kt와 network_security_config.xml).

4아키텍처 심화 분석

4-1. 모듈 계층 (ModuleRules.kt)

모듈은 계층 번호를 갖고, 자기보다 낮은 번호의 모듈에만 의존할 수 있습니다. 규칙은 데이터로 코드에 적혀 있고, checkModuleGraph Gradle 작업이 실제 빌드 그래프를 검사합니다. 외부 라이브러리도 모듈별 허용 목록이 있습니다.

4-2. 한 번의 정리가 흐르는 길

4-3. 핵심 설계 패턴 1 — 명령을 문자열이 아닌 타입으로

core/model/.../Ops.kt의 sealed interface Op는 TV에 할 수 있는 일의 어휘 전부입니다. Disable, Enable, DefaultState, Install, SettingsPut, SetHome, ArmHomeWatchdog, PushAsset, Reboot, DebugOff, CurtainCue 등 20여 개가 있고, 임의의 셸 문자열을 담는 항목은 없습니다. ShellRenderer가 이 Op를 “상수 단어 + 검증된 토큰”으로만 조립해 정확히 한 줄로 만들고, 쓰기 Op마다 확인용 읽기(verify)를 붙입니다.

// core/ops/ShellRenderer.kt (발췌)
is Op.Disable -> Rendered(op, lines(line(PM, "disable-user", USER, "0", writePkg(op.pkg))), null,
    Privilege.PROFILE_STEP, Op.Read(ProbeKind.DISABLED), T_PM, CAP_DEFAULT)
is Op.Enable  -> Rendered(op, lines(line(PM, "enable", USER, "0", pkg(op.pkg))), null,
    Privilege.PROFILE_STEP, Op.Read(ProbeKind.DISABLED), T_PM, CAP_DEFAULT)

패키지 이름·클래스·실행 토큰은 정규식(PACKAGE_RE, CLASS_RE, RUN_TOKEN_RE)으로 만든 값 클래스이고, 렌더러는 한 번 더 검증합니다. 따라서 악의적이거나 깨진 패키지 이름이 셸 메타문자를 끌고 들어오기 어렵게 되어 있습니다.

4-4. 핵심 설계 패턴 2 — 이중 방어(렌더러 + 세션 가드)

adb/session/.../Support.kt의 PmGuard는 렌더러와 별개로, 세션이 TV에 보내기 직전에 줄을 다시 검사합니다. pm 쓰기 명령이 있는 줄에 ; | & 같은 연결 문자가 섞여 있으면 거부하고, 예외는 워치독 템플릿과 정규식 WATCHDOG_RE가 줄 전체와 일치할 때뿐입니다. 한 군데 버그가 있어도 다른 층이 막도록 한 구조입니다.

4-5. 핵심 설계 패턴 3 — TV 안에서 도는 데드맨 타이머

홈 화면을 바꾸는 순간 폰과의 연결이 끊기거나 새 홈이 죽으면 TV를 쓸 수 없습니다. Watchdog.kt는 TV 셸에서 다음 본문을 백그라운드로 실행합니다.

sleep SECONDS & wait; [ -f /data/local/tmp/cleanyourtv/home-ok-TOKEN ] && exit 0;
pm enable --user 0 STOCKPKG; cmd package set-home-activity --user 0 STOCKCOMP;
am start -W -a android.intent.action.MAIN -c android.intent.category.HOME

폰이 새 홈 화면을 확인하면 home-ok-TOKEN 파일을 만들어 타이머를 무력화하고, 확인이 없으면 TV가 스스로 기본 런처를 되살립니다. 기본 대기는 DefaultPlanner.WATCHDOG_SECONDS = 150초이고(허용 범위 30~300초), 폰 쪽 확인 창은 confirmWindowMs = 90_000입니다. 소스 주석에는 sleep & wait로 쓰는 이유(TV의 sh가 포그라운드 sleep 중에는 SIGTERM을 미뤄 워치독이 안 죽던 Mi TV 실기기 문제)가 적혀 있습니다.

4-6. 핵심 설계 패턴 4 — 저널과 가드 구간

Engine.kt의 JournalRecord(PlanStart, Begin, Done, Failed, Section, Rollback, Paused, End)는 CRC32와 함께 파일에 먼저 기록되고 force된 뒤 다음 단계로 갑니다. 구간 상태는 ARMED → CONFIRMED | ROLLED_BACK이고, 연결이 끊겨 InDoubt가 되거나 구간이 열린 채 남으면, DefaultEngine의 복구 코드가 저널에서 가장 최근 ARMED 기록을 찾아 구간을 이어 가거나 롤백합니다(이 복구 경로를 실제로 돌려 보지는 않았습니다). 상태는 Idle, Running, AwaitingConfirm, Paused, RollingBack, InDoubt, Finished 일곱 가지입니다.

4-7. 핵심 설계 패턴 5 — 위험한 TV에서는 홈 교체를 하지 않는다

HomeSwitchRisk.kt는 “정리만 하고 홈 화면은 건드리지 않는” 조건을 데이터로 가집니다.

나머지 안전 구조는 Denylist.kt입니다. 프레임워크(android), 시스템 UI, 설정, 패키지 설치 관리자, 권한 컨트롤러, Play 서비스·Play 스토어, 블루투스(리모컨 페어링), 네트워크 스택·Wi-Fi 계열 접두사가 코드 상수로 박혀 있어 어떤 프로필도 이를 덮어쓸 수 없습니다. 상시 실행(persistent) 패키지, TV 입력(HDMI·튜너) 제공 패키지, 현재 키보드·화면보호기도 실시간 사실로 보호합니다.

4-8. 신뢰 체인 — 앱이 내려받는 것을 어떻게 믿는가

선택 모듈(예: 번들 인덱스의 “Retro” NES 게임 앱)은 서명된 목록으로만 제공됩니다. MinisignIndexVerifier의 검증 순서는 고정입니다.

1. keys.json이 앱에 컴파일된 루트 공개키(TrustRoots.INDEX_ROOT_PUBLIC_KEY)의 minisign 서명을 갖는지, 번들된 것보다 오래된 파일이 아닌지 확인
2. index.json 서명 키가 폐기(revoked)·미등록·서명 불일치가 아닌지 확인
3. JSON 파싱 한도 확인, 시퀀스 번호가 마지막으로 받은 것보다 작으면 ROLLBACK 거부, 만료일이 지났으면 EXPIRED 거부

네트워크 접속 허용 호스트는 DownloadHosts.kt에 github.com, api.github.com, objects.githubusercontent.com, release-assets.githubusercontent.com 네 개뿐이고, https·기본 포트·사용자 정보 없음·정확한 호스트 일치를 리다이렉트 매 단계마다 검사합니다.

5디렉토리 구조 해부

5-1. 읽는 순서 추천

코드 주석에는 “DECISIONS-W5.md, K2”처럼 docs/history/의 문서 이름이 자주 나옵니다. README에 따르면 PRODUCT-SPEC·ARCHITECTURE·SECURITY 같은 원 설계 문서는 코드보다 먼저 쓰였고 이 저장소에는 없으니, 의도를 확인하려면 docs/history/DECISIONS-W*.md와 reviews/를 보는 것이 가장 빠릅니다.

6학습 포인트 (기술별)

6-1. ADB 프로토콜을 직접 구현하기

adb/wire/Protocol.kt는 CNXN, AUTH, OPEN, WRTE, OKAY, CLSE, STLS 명령 상수를 정의합니다. dadb에서 가져온 코드지만 파일 머리말에 변경점이 적혀 있습니다: 명령마다 읽을 길이의 상한을 두고(제어 메시지 256KiB, 데이터 프레임 1MiB), 체크섬과 매직 워드를 검증하고, 알 수 없는 명령은 거부합니다. HostileFrameFuzzTest는 임의로 깨뜨린 프레임을 읽는 쪽이 견디는지 검사합니다.

배울 것: 길이 필드를 믿지 않는 파서, 바이너리 프로토콜의 퍼징 테스트, 라이선스 파생 고지(Apache-2.0 NOTICE).

6-2. 키를 폰 밖으로 내보내지 않는 ADB 인증

KeystoreAdbSigner는 RSA-2048 키를 StrongBox, 안 되면 TEE, 그것도 안 되면 소프트웨어 키(SecretBox로 봉인) 순서로 만들고, 각 경로는 자체 점검을 통과한 뒤에만 사용합니다. 서명은 20바이트 토큰에 대한 DigestInfo(SHA-1) PKCS#1 v1.5 한 가지로 제한해 “아무 데이터나 서명해 주는 오라클”이 되지 않게 했습니다.

6-3. 입력 검증 3중 구조

값 클래스(정규식) → 렌더러 재검증 → 세션 PmGuard. 같은 규칙을 서로 다른 층에서 독립적으로 확인하는 방식은 셸을 다루는 어떤 프로젝트에도 옮겨 쓸 수 있습니다.

6-4. 골든 테스트로 “보내는 명령”을 고정하기

core/ops/src/test/resources/golden/에는 Op별 기대 출력이 01-disable.txt부터 59-cue-finale.txt까지 59개와 planhash.txt로 저장되어 있습니다. 렌더러가 바뀌면 TV로 가는 한 줄이 바뀌므로 테스트가 바로 깨집니다.

6-5. 테스트 대역을 “페르소나”로 만든 가짜 TV

testing/fake-adbd는 실제 ADB 프로토콜로 응답하는 가짜 TV 서버이고 Persona로 기기별 프로퍼티·패키지 목록을 바꿉니다. fixtures/conformance/mitv-axso0-2026-10-18 같은 실제 TV 캡처가 가짜 TV의 기준이 됩니다. 캡처에서 시리얼 등을 지우는지는 scripts/check-redaction.py가 CI에서 검사합니다.

6-6. 릴리스 투명성: 재현 빌드와 서명 검증

CI는 서명 키를 갖지 않고, 컨테이너에서 같은 커밋을 두 번 빌드해 바이트 단위로 비교한 서명 전 APK를 올립니다. 관리자가 로컬에서 서명한 APK는 verify-release.sh가 “서명 전 빌드 + 서명뿐”인지 확인합니다. README는 릴리스 인증서 SHA-256(eaf7af38…cd65)을 공개합니다.

이 레포의 가장 값진 학습 포인트는 기능이 아니라, 모든 위험한 동작에 “입력 제한, 사전 기록, 확인 읽기, 복구 경로”를 한 세트로 붙이는 습관입니다.

7하드웨어 / 시스템 요구사항

지원 범위는 README가 “131개 모델, 46개 브랜드”로 밝히고, 소스에서는 profile-meta.json의 프로필 수 131이 확인됩니다. 모델이 목록에 없어도 브랜드 공통분모(BrandSureSet)만 끄는 보수적 정리를 합니다.

8직접 해볼 수 있는 실습 과제

git clone --recurse-submodules https://github.com/udhaykumarbala/cleanyourtv-app.git
cd cleanyourtv-app
echo "sdk.dir=$ANDROID_HOME" > local.properties
./gradlew :core:ops:test --console=plain

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• udhaykumarbala/cleanyourtv-app — 저장소(분석 기준 커밋 8681e7f92f057efc9530e95809491ea06bf175fd)
• 릴리스 목록 — 이 글의 기준은 0.3.5이고, 목록에는 더 새로운 v0.3.6-beta1이 있음
• Gathin23/cleanyourtv — 업스트림(컴퓨터용 도구·런처·TV 목록). 카탈로그의 cleanyourtv 딥다이브 참고
• mobile-dev-inc/dadb — ADB 프로토콜 코드의 출발점(Apache-2.0)
• CONTRIBUTING.md, SECURITY.md, PRIVACY.md
• docs/history — 설계 결정과 리뷰 기록