Add Windows installer packaging (Setup.exe + portable exe)

PyInstaller onedir/onefile specs, Inno Setup script, and GitHub Actions workflow to produce JUC500-Setup-win64.exe and portable builds. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-15 10:26:10 +09:00
commit 8774a4843e
31 changed files with 4677 additions and 0 deletions
@@ -0,0 +1,130 @@
+# JUC500 File Transfer (Apple Silicon ↔ Windows 11)
+
+j5create **JUC500** USB 3.0 Wormhole 케이블로 **Apple Silicon Mac**과 **Windows 11** 사이 파일을 직접 전송하는 오픈 구현입니다.
+
+## 왜 공식 앱이 Silicon Mac에서 안 되나
+
+실측/분석 결과:
+
+| 항목 | 내용 |
+|------|------|
+| USB ID | `0711:7500` / Product: **Smart Data Link** |
+| 가상 CD | `WORMHOLE` (FAT12, 공식 설치본 포함) |
+| 번들/공식 Mac 앱 (2024, v1.0.1463.47) | **x86_64 전용**, Apple Silicon 네이티브 **arm64 없음** |
+| USB 스택 | deprecated `IOUSBDevice` API (`kIOUSBDeviceInterfaceID500`) |
+| 핵심 라이브러리 | KaiJet / OTi `OTiTransfer.framework` — bounding·alive·XML UPipe |
+
+Intel Mac에서는 Rosetta 없이(구버전) 또는 Rosetta로 동작할 수 있으나, Apple Silicon + 최신 macOS에서는 공식 Wormhole 경로가 깨집니다. 이 프로젝트는 **libusb로 Vendor/CDC 인터페이스를 직접 열고**, 자체 프레임 프로토콜로 파일을 보냅니다.
+
+공식 Windows Wormhole과 호환되지 않습니다. **양쪽 모두 이 프로그램을 실행**해야 합니다.
+
+## 장치 인터페이스 (요약)
+
+```
+IF0 CDC Comm     INT 0x81
+IF1 CDC Data     BULK 0x02 / 0x83
+IF2 Mass Storage WORMHOLE CD   (OS 점유 — 건드리지 않음)
+IF3 HID mouse    (KM — OS 점유)
+IF4 HID keyboard (KM — OS 점유)
+IF5 Vendor       BULK 0x08/0x89 (데이터) + 0x0A/0x8B (keepalive)
+```
+
+## 요구 사항
+
+### macOS (Apple Silicon)
+
+- Python 3.10+
+- libusb: `brew install libusb`
+- (선택) 공식 Wormhole 앱이 떠 있으면 종료
+
+```bash
+cd /path/to/juc500
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python -m juc500_xfer info
+```
+
+### Windows 11
+
+1. Python 3.10+ 설치  
+2. [libusb](https://libusb.info/) 또는 이 저장소 `vendor/libusb-1.0.dll` 을 PATH/`vendor/` 에 배치  
+3. **Zadig**로 `Smart Data Link` 복합 장치의  
+   - **Interface 5** (Vendor Specific)  
+   - **Interface 1** (CDC Data, 권장)  
+   에 **WinUSB** 드라이버 설치  
+4. 공식 j5create Wormhole / 자동실행 소프트웨어는 **종료·제거** (같은 인터페이스를 점유함)
+
+```powershell
+cd juc500
+py -3 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+python -m juc500_xfer info
+```
+
+## 사용법
+
+양쪽 PC에 케이블을 꽂고, **먼저 수신 쪽**, 이어서 송신 쪽을 실행합니다.
+
+**Windows (수신 예)**
+
+```powershell
+python -m juc500_xfer recv --dest Downloads -y
+```
+
+**Mac (송신 예)**
+
+```bash
+python -m juc500_xfer send ~/Desktop/archive.zip
+```
+
+## Windows 설치파일
+
+산출물:
+
+| 파일 | 용도 |
+|------|------|
+| `JUC500-Setup-win64.exe` | Inno Setup 설치 프로그램 |
+| `JUC500-portable.exe` | 단일 실행 포터블 EXE |
+| `JUC500-win64-portable.zip` | 폴더형 포터블 (+ `setup.bat`) |
+
+**Mac(Apple Silicon)에서 빌드:**
+
+```bash
+./build-installer-windows.sh --ci
+# → dist-windows/ 에 위 파일 다운로드 (GitHub Actions)
+```
+
+**Windows PC에서 빌드:**
+
+```bat
+build-installer-windows.bat
+```
+
+(Inno Setup 6 필요 시 Setup.exe 생성. 없어도 portable exe/zip 은 생성됩니다.)
+
+사용 전 Win11에서 Zadig WinUSB 설정이 필요합니다 (`docs/WINDOWS.md`).
+
+## GUI
+
+fileShare와 동일한 **듀얼 패널(이 PC | 전송 | 상대 PC)** 웹 UI입니다.
+
+```bash
+python -m juc500_xfer gui
+# → http://127.0.0.1:8765/
+```
+
+양쪽 PC에서 GUI를 실행한 뒤 **연결**을 누르세요. (입력공유는 미지원, UI만 동일 구조)
+
+Windows 설치본은 `JUC500.exe` / `JUC500-portable.exe` 더블클릭으로 동일 GUI가 열립니다.
+
+## 프로토콜
+
+Vendor BULK(`0x08`/`0x89`) 위에 길이·CRC 프레임(`J5FX` 매직)을 올리고 `HELLO` 핸드셰이크로 연결을 만듭니다. 보조 파이프(`0x0A`/`0x8B`)로 keepalive를내어 링크를 유지합니다. 파일은 SHA-256으로 무결성을 검증합니다.
+
+공식 OTi XML / bounding 프로토콜은 재구현하지 않았습니다.
+
+## 분석 메모
+
+자세한 USB·바이너리 분석은 [`docs/ANALYSIS.md`](docs/ANALYSIS.md) 를 참고하세요.