Run a virtual iPhone on an Apple Silicon Mac.
Swift
feat(vm create): prompt for firmware pairing when a source is omitted
zqxwcee490a2aaf8f2
diff --git a/README.md b/README.mdindex 074ee6f3..f12eac35 100644--- a/README.md+++ b/README.md@@ -71,10 +71,10 @@ csrutil allow-research-guests enableThen reboot into macOS and allowlist the repo with [`amfidont`](https://github.com/zqxwce/amfidont) (or [`amfree`](https://github.com/retX0/amfree)):```bash-sudo amfidont --path <repo>+sudo amfidont --path <path_to_vphone-cli.app>```-> The `less` (patchless) variant needs Option A, or Option B with `amfidont -S` (`sudo amfidont -S --path <repo>`).+> The `less` (patchless) variant needs Option A, or Option B with `amfidont -S` (`sudo amfidont -S --path <path_to_vphone-cli.app>`).**Dependencies:**@@ -97,7 +97,7 @@ Two one-time bootstrap scripts (a compiled binary can't build itself), then everPut the binary on your `PATH` so the examples below work verbatim:```bash-cd .build/release+cd .build/vphone-cli.app/Contents/MacOS/vphone-cli --help```@@ -109,7 +109,7 @@ One command creates a VM end-to-end (download → patch → DFU restore → CFWvphone-cli vm create myphone -V jb # -V / --variant```-With no source flags it downloads a default tested iPhone + cloudOS pair. To choose specific firmware, pass **`-i`/`--iphone-source`** and **`-c`/`--cloudos-source`** — each takes either a **URL** or a **local `.ipsw` path** (see [Tested Environments](#tested-environments) for known-good pairs):+The user is then prompted to choose iOS <-> cloudOS paring, you can specify either one by passing **`-i`/`--iphone-source`** and/or **`-c`/`--cloudos-source`**, i.e.:```bash# from local IPSWs@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \# or from URLs — downloaded and cached under ~/.vphone/ipswsvphone-cli vm create myphone -V jb \- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \+ -c "https://.../399b6..."```-The CFW-install stage needs root (host disk mount) and will prompt for `sudo`; pass `-s <pw>` (`--sudo-password`) to run unattended. Add `-v` to watch the restore (pmd3 log, colorized), `-vv` for pmd3 debug detail, `-vvv` for vphone-cli's internal trace. Then boot it:+Then boot it:```bashvphone-cli vm launch myphone```-VMs live in a **library** at `~/.vphone/VMs/` (override any command with `--library-root <dir>`). Run any VM command with no name (e.g. `vphone-cli vm launch`) to pick from a menu of your VMs.-## Commands`vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.@@ -187,6 +185,18 @@ without the repo. Provisioning is automatic; run `vphone-cli setup` to do itup front. Point at a specific interpreter with `VPHONE_PYTHON=/path/to/python3`,or relocate the venv with `VPHONE_VENV_DIR=/path`.+## Locations++Everything vphone-cli creates lives under `~/.vphone/` — kept outside the repo and the `.app` so the signed bundle stays portable:++| Path | Contents |+| ----------------- | -------------------------------------------------------------------------------------------- |+| `~/.vphone/VMs/` | VM bundles — one directory per VM. This is the library; override with `$VPHONE_LIBRARY_ROOT`. |+| `~/.vphone/ipsws/`| Downloaded iPhone + cloudOS IPSWs, cached and reused across VMs. |+| `~/.vphone/tools/`| Cached APFS seal-volume artifacts (`apfs_sealvolume_<version>`) fetched during `fw prepare`. |+| `~/.vphone/debs/` | Cached `.deb` packages the `jb`/`exp` CFW install lays into the guest (Sileo, apt, …). |+| `~/.vphone/venv/` | Auto-provisioned Python environment (see [Python runtime](#python-runtime); override with `$VPHONE_VENV_DIR`). |+## FAQ**`zsh: killed ./vphone-cli`** — AMFI/debug restrictions aren't bypassed; see [Prerequisites](#prerequisites) (`amfi_get_out_of_my_way=1` or `amfidont`).diff --git a/docs/README_ja.md b/docs/README_ja.mdindex 1dd4bd4b..25eeb611 100644--- a/docs/README_ja.md+++ b/docs/README_ja.md@@ -71,10 +71,10 @@ csrutil allow-research-guests enableその後 macOS で再起動し、[`amfidont`](https://github.com/zqxwce/amfidont)(または [`amfree`](https://github.com/retX0/amfree))でリポジトリを許可リストに追加します:```bash-sudo amfidont --path <repo>+sudo amfidont --path <path_to_vphone-cli.app>```-> `less`(パッチなし)バリアントにはオプション A、またはオプション B に `amfidont -S` を組み合わせたもの(`sudo amfidont -S --path <repo>`)が必要です。+> `less`(パッチなし)バリアントにはオプション A、またはオプション B に `amfidont -S` を組み合わせたもの(`sudo amfidont -S --path <path_to_vphone-cli.app>`)が必要です。**依存関係:**@@ -97,7 +97,7 @@ brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass key以下の例をそのまま実行できるように、バイナリを `PATH` に追加します:```bash-cd .build/release+cd .build/vphone-cli.app/Contents/MacOS/vphone-cli --help```@@ -109,7 +109,7 @@ vphone-cli --helpvphone-cli vm create myphone -V jb # -V / --variant```-ソースフラグを指定しない場合、動作確認済みのデフォルトの iPhone + cloudOS ペアがダウンロードされます。特定のファームウェアを選ぶには **`-i`/`--iphone-source`** と **`-c`/`--cloudos-source`** を渡します — それぞれ **URL** または **ローカルの `.ipsw` パス** のいずれかを取ります(既知の良好なペアについては [動作確認済み環境](#動作確認済み環境) を参照):+その後、iOS <-> cloudOS のペアリングを選ぶよう促されます。**`-i`/`--iphone-source`** および/または **`-c`/`--cloudos-source`** を渡して、どちらか(または両方)を指定することもできます。例:```bash# ローカルの IPSW から@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \# または URL から — ~/.vphone/ipsws 以下にダウンロードしてキャッシュvphone-cli vm create myphone -V jb \- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \+ -c "https://.../399b6..."```-CFW インストール段階は root 権限(ホストディスクのマウント)が必要で、`sudo` の入力を求めます。無人で実行するには `-s <pw>`(`--sudo-password`)を渡します。復元の様子を見るには `-v`(pmd3 ログ、カラー表示)、pmd3 のデバッグ詳細には `-vv`、vphone-cli の内部トレースには `-vvv` を追加します。その後、起動します:+その後、起動します:```bashvphone-cli vm launch myphone```-VM は `~/.vphone/VMs/` にある **ライブラリ** に保存されます(任意のコマンドで `--library-root <dir>` によって上書き可能)。VM コマンドを名前なしで実行すると(例: `vphone-cli vm launch`)、VM のメニューから選択できます。-## コマンド`vphone-cli vm create` はパイプライン全体を実行します。以下の個別ステップを使うと、手動で操作したり 1 つの段階を再実行したりできます。@@ -181,6 +179,18 @@ vphone-cli vm launch myphone # 6. 初回起動いくつかのステップ(DFU 復元、IPSW 処理)は Python を通じて実行されます。初回使用時、vphone-cli はバンドルされた `requirements.txt` を使用して、最新のホスト `python3`(3.11+)から `~/.vphone/venv` に自己完結型の venv をプロビジョニングします — そのため署名済みの `.app` は **ポータブル** です。任意の場所(例: `/Applications`)にコピーすればリポジトリなしで動作します。プロビジョニングは自動ですが、事前に行うには `vphone-cli setup` を実行します。特定のインタプリタを指定するには `VPHONE_PYTHON=/path/to/python3`、venv の場所を変更するには `VPHONE_VENV_DIR=/path` を使用します。+## 場所++vphone-cli が生成するものはすべて `~/.vphone/` 以下に置かれます — 署名済みバンドルがポータブルであり続けるよう、リポジトリと `.app` の外に保管されます:++| パス | 内容 |+| ----------------- | ------------------------------------------------------------------------------------------ |+| `~/.vphone/VMs/` | VM バンドル — VM ごとに 1 ディレクトリ。ライブラリであり、`$VPHONE_LIBRARY_ROOT` で上書きできます。 |+| `~/.vphone/ipsws/`| ダウンロードされた iPhone + cloudOS の IPSW。キャッシュされ、複数の VM で再利用されます。 |+| `~/.vphone/tools/`| `fw prepare` 中に取得された APFS seal-volume アーティファクト(`apfs_sealvolume_<version>`)のキャッシュ。 |+| `~/.vphone/debs/` | `jb`/`exp` の CFW インストールがゲストに配置する `.deb` パッケージのキャッシュ(Sileo、apt など)。 |+| `~/.vphone/venv/` | 自動的にプロビジョニングされる Python 環境([Python ランタイム](#python-ランタイム) を参照。`$VPHONE_VENV_DIR` で上書き可能)。 |+## FAQ**`zsh: killed ./vphone-cli`** — AMFI/デバッグ制限がバイパスされていません。[前提条件](#前提条件) を参照してください(`amfi_get_out_of_my_way=1` または `amfidont`)。diff --git a/docs/README_ko.md b/docs/README_ko.mdindex e4cf8986..fbaec127 100644--- a/docs/README_ko.md+++ b/docs/README_ko.md@@ -71,10 +71,10 @@ csrutil allow-research-guests enable그런 다음 macOS로 재부팅하고 [`amfidont`](https://github.com/zqxwce/amfidont) (또는 [`amfree`](https://github.com/retX0/amfree))로 저장소를 허용 목록에 추가합니다:```bash-sudo amfidont --path <repo>+sudo amfidont --path <path_to_vphone-cli.app>```-> `less` (patchless) 변형은 방법 A, 또는 `amfidont -S`를 포함한 방법 B(`sudo amfidont -S --path <repo>`)가 필요합니다.+> `less` (patchless) 변형은 방법 A, 또는 `amfidont -S`를 포함한 방법 B(`sudo amfidont -S --path <path_to_vphone-cli.app>`)가 필요합니다.**의존성:**@@ -97,7 +97,7 @@ brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass key아래 예제가 그대로 작동하도록 바이너리를 `PATH`에 추가하세요:```bash-cd .build/release+cd .build/vphone-cli.app/Contents/MacOS/vphone-cli --help```@@ -109,7 +109,7 @@ vphone-cli --helpvphone-cli vm create myphone -V jb # -V / --variant```-소스 플래그가 없으면 기본적으로 테스트된 iPhone + cloudOS 쌍을 다운로드합니다. 특정 펌웨어를 선택하려면 **`-i`/`--iphone-source`**와 **`-c`/`--cloudos-source`**를 전달하세요 — 각각 **URL** 또는 **로컬 `.ipsw` 경로**를 받습니다 (검증된 쌍은 [테스트 환경](#테스트-환경)을 참조하세요):+그러면 iOS <-> cloudOS 페어링을 선택하라는 안내가 표시됩니다. **`-i`/`--iphone-source`** 및/또는 **`-c`/`--cloudos-source`**를 전달하여 둘 중 하나(또는 둘 다)를 직접 지정할 수도 있습니다. 예:```bash# 로컬 IPSW에서@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \# 또는 URL에서 — 다운로드되어 ~/.vphone/ipsws 아래에 캐시됨vphone-cli vm create myphone -V jb \- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \+ -c "https://.../399b6..."```-CFW 설치 단계는 root(호스트 디스크 마운트)가 필요하며 `sudo`를 요청합니다; 무인 실행을 위해서는 `-s <pw>`(`--sudo-password`)를 전달하세요. 복원 과정을 보려면 `-v`(pmd3 로그, 색상 표시), pmd3 디버그 상세 정보는 `-vv`, vphone-cli의 내부 추적은 `-vvv`를 추가하세요. 그런 다음 부팅합니다:+그런 다음 부팅합니다:```bashvphone-cli vm launch myphone```-VM은 `~/.vphone/VMs/`의 **라이브러리**에 저장됩니다 (어떤 명령이든 `--library-root <dir>`로 재정의할 수 있습니다). 이름 없이 VM 명령을 실행하면 (예: `vphone-cli vm launch`) VM 목록 메뉴에서 선택할 수 있습니다.-## 명령어`vphone-cli vm create`는 전체 파이프라인을 실행합니다; 아래 개별 단계들을 사용하면 수동으로 진행하거나 한 단계만 다시 실행할 수 있습니다.@@ -187,6 +185,18 @@ vphone-cli는 번들된 `requirements.txt`를 사용하여 최신 호스트 `pyt실행하세요. 특정 인터프리터를 지정하려면 `VPHONE_PYTHON=/path/to/python3`을,venv 위치를 변경하려면 `VPHONE_VENV_DIR=/path`를 사용하세요.+## 위치++vphone-cli가 생성하는 모든 것은 `~/.vphone/` 아래에 있습니다 — 서명된 번들이 이식 가능하도록 저장소와 `.app` 외부에 보관됩니다:++| 경로 | 내용 |+| ----------------- | ------------------------------------------------------------------------------------------ |+| `~/.vphone/VMs/` | VM 번들 — VM마다 하나의 디렉터리. 라이브러리이며, `$VPHONE_LIBRARY_ROOT`로 재정의할 수 있습니다. |+| `~/.vphone/ipsws/`| 다운로드된 iPhone + cloudOS IPSW, 캐시되어 여러 VM에서 재사용됩니다. |+| `~/.vphone/tools/`| `fw prepare` 중에 가져온 APFS seal-volume 아티팩트(`apfs_sealvolume_<version>`) 캐시. |+| `~/.vphone/debs/` | `jb`/`exp` CFW 설치가 게스트에 넣는 `.deb` 패키지 캐시 (Sileo, apt 등). |+| `~/.vphone/venv/` | 자동으로 프로비저닝되는 Python 환경 ([Python 런타임](#python-런타임) 참조; `$VPHONE_VENV_DIR`로 재정의). |+## FAQ**`zsh: killed ./vphone-cli`** — AMFI/디버그 제한이 우회되지 않았습니다; [사전 요구 사항](#사전-요구-사항)을 참조하세요 (`amfi_get_out_of_my_way=1` 또는 `amfidont`).diff --git a/docs/README_zh.md b/docs/README_zh.mdindex a7b9ace3..1927ae32 100644--- a/docs/README_zh.md+++ b/docs/README_zh.md@@ -71,10 +71,10 @@ csrutil allow-research-guests enable然后重启进入 macOS,用 [`amfidont`](https://github.com/zqxwce/amfidont)(或 [`amfree`](https://github.com/retX0/amfree))将仓库加入白名单:```bash-sudo amfidont --path <repo>+sudo amfidont --path <path_to_vphone-cli.app>```-> `less`(无补丁)变体需要方案 A,或者搭配 `amfidont -S` 的方案 B(`sudo amfidont -S --path <repo>`)。+> `less`(无补丁)变体需要方案 A,或者搭配 `amfidont -S` 的方案 B(`sudo amfidont -S --path <path_to_vphone-cli.app>`)。**依赖:**@@ -97,7 +97,7 @@ brew install [email protected] aria2 wget gnu-tar openssl@3 ldid-procursus sshpass key把二进制加入你的 `PATH`,这样下面的示例就能原样运行:```bash-cd .build/release+cd .build/vphone-cli.app/Contents/MacOS/vphone-cli --help```@@ -109,7 +109,7 @@ vphone-cli --helpvphone-cli vm create myphone -V jb # -V / --variant```-不带源标志时,它会下载一对默认的、经过测试的 iPhone + cloudOS 固件。要选择特定固件,请传入 **`-i`/`--iphone-source`** 和 **`-c`/`--cloudos-source`**——每个都接受 **URL** 或**本地 `.ipsw` 路径**(已验证可用的固件对见[测试环境](#测试环境)):+随后会提示你选择 iOS <-> cloudOS 配对;你也可以通过传入 **`-i`/`--iphone-source`** 和/或 **`-c`/`--cloudos-source`** 指定其中之一(或两者)。例如:```bash# 使用本地 IPSW@@ -119,18 +119,16 @@ vphone-cli vm create myphone -V jb \# 或使用 URL——下载后缓存到 ~/.vphone/ipswsvphone-cli vm create myphone -V jb \- -i "https://updates.cdn-apple.com/.../iPhone17,3_26.1_23B85_Restore.ipsw" \- -c "https://updates.cdn-apple.com/private-cloud-compute/<id>"+ -i "https://.../iPhone17,3_26.1_23B85_Restore.ipsw" \+ -c "https://.../399b6..."```-CFW 安装阶段需要 root 权限(挂载宿主机磁盘),并会提示输入 `sudo`;传入 `-s <pw>`(`--sudo-password`)可无人值守运行。加上 `-v` 可观看恢复过程(pmd3 日志,带颜色),`-vv` 显示 pmd3 调试细节,`-vvv` 显示 vphone-cli 的内部跟踪。然后启动它:+然后启动它:```bashvphone-cli vm launch myphone```-虚拟机存放在位于 `~/.vphone/VMs/` 的**库**中(任何命令都可用 `--library-root <dir>` 覆盖)。运行任何虚拟机命令时不带名称(例如 `vphone-cli vm launch`),即可从你的虚拟机菜单中选择。-## 命令`vphone-cli vm create` 会运行整个流水线;下面的各个步骤让你可以手动驱动它,或重新运行某一个阶段。@@ -181,6 +179,18 @@ vphone-cli vm launch myphone # 6. 首次启动有几个步骤(DFU 恢复、IPSW 处理)通过 Python 运行。首次使用时,vphone-cli 会基于宿主机上较新的 `python3`(3.11+)并使用捆绑的 `requirements.txt`,在 `~/.vphone/venv` 处配置一个自包含的 venv——因此签名后的 `.app` 是**可移植的**:把它复制到任何地方(例如 `/Applications`),无需仓库即可运行。配置是自动进行的;运行 `vphone-cli setup` 可提前完成配置。用 `VPHONE_PYTHON=/path/to/python3` 指定特定的解释器,或用 `VPHONE_VENV_DIR=/path` 迁移 venv。+## 位置++vphone-cli 创建的所有内容都位于 `~/.vphone/` 下——保存在仓库和 `.app` 之外,以便签名后的包保持可移植:++| 路径 | 内容 |+| ----------------- | -------------------------------------------------------------------------------- |+| `~/.vphone/VMs/` | 虚拟机包——每个虚拟机一个目录。这是库;可用 `$VPHONE_LIBRARY_ROOT` 覆盖。 |+| `~/.vphone/ipsws/`| 已下载的 iPhone + cloudOS IPSW,缓存后在多个虚拟机间复用。 |+| `~/.vphone/tools/`| `fw prepare` 期间获取的 APFS seal-volume 制品(`apfs_sealvolume_<version>`)缓存。 |+| `~/.vphone/debs/` | `jb`/`exp` CFW 安装写入客户机的 `.deb` 包缓存(Sileo、apt 等)。 |+| `~/.vphone/venv/` | 自动配置的 Python 环境(见 [Python 运行时](#python-运行时);可用 `$VPHONE_VENV_DIR` 覆盖)。 |+## 常见问题**`zsh: killed ./vphone-cli`** —— AMFI/debug 限制未被绕过;见[前置条件](#前置条件)(`amfi_get_out_of_my_way=1` 或 `amfidont`)。diff --git a/sources/VPhoneCore/VPhoneFirmwareCatalog.swift b/sources/VPhoneCore/VPhoneFirmwareCatalog.swiftnew file mode 100644index 00000000..26e7ec7a--- /dev/null+++ b/sources/VPhoneCore/VPhoneFirmwareCatalog.swift@@ -0,0 +1,70 @@+import Foundation++// MARK: - VPhoneFirmwarePairing++/// A known iPhone-IPSW ↔ cloudOS pairing for iPhone17,3, with friendly names for+/// prompts and the direct download URLs `fw prepare` consumes.+public struct VPhoneFirmwarePairing: Sendable, Equatable {+ public let iosName: String+ public let iosURL: String+ public let cloudosName: String+ public let cloudosURL: String++ public init(iosName: String, iosURL: String, cloudosName: String, cloudosURL: String) {+ self.iosName = iosName+ self.iosURL = iosURL+ self.cloudosName = cloudosName+ self.cloudosURL = cloudosURL+ }+}++// MARK: - VPhoneCloudOSOption++public struct VPhoneCloudOSOption: Sendable, Equatable {+ public let name: String+ public let url: String+ public init(name: String, url: String) { self.name = name; self.url = url }+}++// MARK: - VPhoneFirmwareCatalog++/// The known downloadable iPhone/cloudOS pairings. Prompts show the friendly+/// `iosName`/`cloudosName`; selection resolves to the URLs.+public enum VPhoneFirmwareCatalog {+ // cloudOS images (one per major); referenced by multiple iPhone builds.+ static let cloud261 = "https://updates.cdn-apple.com/private-cloud-compute/399b664dd623358c3de118ffc114e42dcd51c9309e751d43bc949b98f4e31349"+ static let cloud262 = "https://updates.cdn-apple.com/private-cloud-compute/0cb00f22e0f7a8b33995b49b2bdca77f781ed6093a09c570ac21b0f012bab908"+ static let cloud263 = "https://updates.cdn-apple.com/private-cloud-compute/edc92b58ab7e2f207a6407fd0a0e1a60f7d43bf9d93325bf6d3db3e154ee5525"+ static let cloud264 = "https://updates.cdn-apple.com/private-cloud-compute/c0ecdb4b310cf5239ab2b248dd3098eec297dc5aa3bbe6ada27273262b0b8b64"++ public static let pairings: [VPhoneFirmwarePairing] = [+ .init(iosName: "iOS 18.6.2", iosURL: "https://updates.cdn-apple.com/2025SummerFCS/fullrestores/093-20738/98758B5A-311E-4538-B365-FEE3D8792CDF/iPhone17,3_18.6.2_22G100_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),+ .init(iosName: "iOS 26.0", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-40775/B7282E74-76C1-4D0A-8FAE-CE97FC2330C2/iPhone17,3_26.0_23A341_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),+ .init(iosName: "iOS 26.0.1", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/093-46329/C1717B2A-9E58-4131-A398-75D9B1D01A89/iPhone17,3_26.0.1_23A355_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),+ .init(iosName: "iOS 26.1", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-13864/668EFC0E-5911-454C-96C6-E1063CB80042/iPhone17,3_26.1_23B85_Restore.ipsw", cloudosName: "cloudOS 26.1", cloudosURL: cloud261),+ .init(iosName: "iOS 26.2", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/089-90760/1214478F-8ED8-4AE0-B693-2F63CE0259A9/iPhone17,3_26.2_23C55_Restore.ipsw", cloudosName: "cloudOS 26.2", cloudosURL: cloud262),+ .init(iosName: "iOS 26.2.1", iosURL: "https://updates.cdn-apple.com/2025FallFCS/fullrestores/047-34150/D14FB1F1-B8C5-4A20-9250-8DD35EF19BF5/iPhone17,3_26.2.1_23C71_Restore.ipsw", cloudosName: "cloudOS 26.2", cloudosURL: cloud262),+ .init(iosName: "iOS 26.3", iosURL: "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-39165/E8E603F3-A2E2-4638-8067-394754896386/iPhone17,3_26.3_23D127_Restore.ipsw", cloudosName: "cloudOS 26.3", cloudosURL: cloud263),+ .init(iosName: "iOS 26.3.1", iosURL: "https://updates.cdn-apple.com/2026WinterFCS/fullrestores/047-90312/17B5C7BE-C560-43BD-BA9A-7DD1E5C2FC23/iPhone17,3_26.3.1_23D8133_Restore.ipsw", cloudosName: "cloudOS 26.3", cloudosURL: cloud263),+ .init(iosName: "iOS 26.4", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-06082/FE21226A-B87F-4FC7-9D4B-B97A9EAF5C20/iPhone17,3_26.4_23E246_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 26.4.1", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-28526/10E1E3EC-6A3E-4620-A569-8E0C4361AB77/iPhone17,3_26.4.1_23E254_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 26.4.2", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-60828/A4082066-CCC4-4903-89E6-FF4801EA609C/iPhone17,3_26.4.2_23E261_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 26.5", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/122-63074/5E6B4A05-BDBC-45FE-9606-22B8F4315989/iPhone17,3_26.5_23F77_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 26.5.2", iosURL: "https://updates.cdn-apple.com/2026SpringFCS/fullrestores/140-25549/1AFB1F72-E48E-476A-9C21-42B27C846C01/iPhone17,3_26.5.2_23F84_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 26.6", iosURL: "https://updates.cdn-apple.com/2026SummerFCS/fullrestores/140-58193/1F477C3E-934B-43C0-B428-753B9E005EC0/iPhone17,3_26.6_23G71_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 27 beta 1", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/122-99394/32118457-A80B-4953-BF2A-11F74FD7D375/iPhone17,3_27.0_24A5355q_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 27 beta 2", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-21207/F0510574-F649-48C5-B535-0A477E342BFB/iPhone17,3_27.0_24A5370h_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 27 beta 3", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-35950/D135F5B5-C2BE-4630-8AE9-C78A6F0E8381/iPhone17,3_27.0_24A5380h_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ .init(iosName: "iOS 27 beta 4", iosURL: "https://updates.cdn-apple.com/2026SpringSeed/fullrestores/140-57108/5E816D0E-89BB-4B95-8825-6A3EDF22E509/iPhone17,3_27.0_24A5390f_Restore.ipsw", cloudosName: "cloudOS 26.4", cloudosURL: cloud264),+ ]++ /// Distinct cloudOS images (first-seen order) for the "choose the cloudOS" prompt.+ public static var cloudOSOptions: [VPhoneCloudOSOption] {+ var seen = Set<String>()+ var out: [VPhoneCloudOSOption] = []+ for p in pairings where seen.insert(p.cloudosName).inserted {+ out.append(VPhoneCloudOSOption(name: p.cloudosName, url: p.cloudosURL))+ }+ return out+ }+}diff --git a/sources/VPhoneCore/VPhoneFirmwarePicker.swift b/sources/VPhoneCore/VPhoneFirmwarePicker.swiftnew file mode 100644index 00000000..607977ff--- /dev/null+++ b/sources/VPhoneCore/VPhoneFirmwarePicker.swift@@ -0,0 +1,132 @@+import Foundation++// MARK: - VPhoneFirmwarePickerError++public enum VPhoneFirmwarePickerError: Error, CustomStringConvertible, Equatable {+ case aborted+ case invalidSelection++ public var description: String {+ switch self {+ case .aborted: "firmware selection aborted"+ case .invalidSelection: "no valid firmware selection made"+ }+ }+}++// MARK: - VPhoneFirmwareSources++/// The resolved `fw prepare` sources — a URL or local path per component, or+/// nil to let `fw_prepare.sh` fall back to its built-in default.+public struct VPhoneFirmwareSources: Sendable, Equatable {+ public let iphoneSource: String?+ public let cloudosSource: String?+ public init(iphoneSource: String?, cloudosSource: String?) {+ self.iphoneSource = iphoneSource+ self.cloudosSource = cloudosSource+ }+}++// MARK: - VPhoneFirmwarePicker++public enum VPhoneFirmwarePicker {+ /// Resolve the iPhone/cloudOS sources for `vm create`, prompting only for+ /// what's missing. Both given → passthrough. Non-interactive → passthrough+ /// (fw_prepare defaults fill any gap). Neither given → pick a full pairing.+ /// One given → prompt for just the other. Prompts show friendly names; the+ /// result carries URLs. I/O is injected so the logic is unit-testable.+ public static func resolve(+ iphone: String?,+ cloudos: String?,+ isInteractive: Bool,+ maxRetries: Int = 5,+ read: () -> String?,+ write: (String) -> Void+ ) throws -> VPhoneFirmwareSources {+ let iphone = (iphone?.isEmpty == true) ? nil : iphone+ let cloudos = (cloudos?.isEmpty == true) ? nil : cloudos++ // Nothing to prompt for: both supplied, or we can't prompt anyway.+ if (iphone != nil && cloudos != nil) || !isInteractive {+ return VPhoneFirmwareSources(iphoneSource: iphone, cloudosSource: cloudos)+ }++ if iphone == nil, cloudos == nil {+ let p = try pickPairing(maxRetries: maxRetries, read: read, write: write)+ return VPhoneFirmwareSources(iphoneSource: p.iosURL, cloudosSource: p.cloudosURL)+ }+ if iphone == nil { // cloudOS supplied, choose the iPhone build+ let p = try pickIPhone(maxRetries: maxRetries, read: read, write: write)+ return VPhoneFirmwareSources(iphoneSource: p.iosURL, cloudosSource: cloudos)+ }+ // iPhone supplied, choose the cloudOS image+ let c = try pickCloudOS(maxRetries: maxRetries, read: read, write: write)+ return VPhoneFirmwareSources(iphoneSource: iphone, cloudosSource: c.url)+ }++ // MARK: - Prompts++ static func pickPairing(+ maxRetries: Int, read: () -> String?, write: (String) -> Void+ ) throws -> VPhoneFirmwarePairing {+ let pairings = VPhoneFirmwareCatalog.pairings+ let w = pairings.map(\.iosName.count).max() ?? 0+ let idx = try choose(+ "Select a firmware pairing to download:",+ pairings.map { $0.iosName.padding(toLength: w, withPad: " ", startingAt: 0)+ + " (→ \($0.cloudosName))" },+ maxRetries: maxRetries, read: read, write: write)+ let p = pairings[idx]+ write("→ \(p.iosName) + \(p.cloudosName)")+ return p+ }++ static func pickIPhone(+ maxRetries: Int, read: () -> String?, write: (String) -> Void+ ) throws -> VPhoneFirmwarePairing {+ let pairings = VPhoneFirmwareCatalog.pairings+ let idx = try choose(+ "Select an iPhone firmware to download:",+ pairings.map(\.iosName),+ maxRetries: maxRetries, read: read, write: write)+ let p = pairings[idx]+ write("→ \(p.iosName)")+ return p+ }++ static func pickCloudOS(+ maxRetries: Int, read: () -> String?, write: (String) -> Void+ ) throws -> VPhoneCloudOSOption {+ let options = VPhoneFirmwareCatalog.cloudOSOptions+ let idx = try choose(+ "Select a cloudOS firmware to download:",+ options.map(\.name),+ maxRetries: maxRetries, read: read, write: write)+ let c = options[idx]+ write("→ \(c.name)")+ return c+ }++ /// Show a numbered menu and read a 1-based index (mirrors VPhoneVMPicker).+ static func choose(+ _ prompt: String, _ labels: [String],+ maxRetries: Int, read: () -> String?, write: (String) -> Void+ ) throws -> Int {+ write(prompt)+ let iw = String(labels.count).count // right-align indices so labels start in one column+ for (i, label) in labels.enumerated() {+ let n = String(i + 1)+ let padded = String(repeating: " ", count: iw - n.count) + n+ write(" [\(padded)] \(label)")+ }+ for _ in 0..<maxRetries {+ write("Enter number: ")+ guard let line = read() else { throw VPhoneFirmwarePickerError.aborted }+ let choice = line.trimmingCharacters(in: .whitespacesAndNewlines)+ if choice.isEmpty { continue }+ if let n = Int(choice), n >= 1, n <= labels.count { return n - 1 }+ write(" '\(choice)' is not a valid selection.")+ }+ throw VPhoneFirmwarePickerError.invalidSelection+ }+}diff --git a/sources/vphone-cli/VPhoneFirmwareSelection.swift b/sources/vphone-cli/VPhoneFirmwareSelection.swiftnew file mode 100644index 00000000..cdb98ffe--- /dev/null+++ b/sources/vphone-cli/VPhoneFirmwareSelection.swift@@ -0,0 +1,18 @@+import Foundation+import VPhoneCore++enum VPhoneFirmwareSelection {+ private static var isTTY: Bool { isatty(FileHandle.standardInput.fileDescriptor) != 0 }+ private static func err(_ s: String) { FileHandle.standardError.write(Data((s + "\n").utf8)) }++ /// Resolve `vm create`'s iPhone/cloudOS sources, prompting on a TTY for+ /// whichever component the user didn't pass. Non-interactive or fully+ /// specified → returns the inputs unchanged (fw_prepare defaults fill gaps).+ static func resolve(iphone: String?, cloudos: String?) throws -> VPhoneFirmwareSources {+ try VPhoneFirmwarePicker.resolve(+ iphone: iphone, cloudos: cloudos,+ isInteractive: isTTY,+ read: { readLine(strippingNewline: true) },+ write: { err($0) })+ }+}diff --git a/sources/vphone-cli/VPhoneVMCreateCLI.swift b/sources/vphone-cli/VPhoneVMCreateCLI.swiftindex 5500e85d..6c60ccf4 100644--- a/sources/vphone-cli/VPhoneVMCreateCLI.swift+++ b/sources/vphone-cli/VPhoneVMCreateCLI.swift@@ -29,10 +29,13 @@ struct VPhoneVMCreateCommand: ParsableCommand {func run() throws {let resources = projectRoot.map { VPhoneResources(base: URL(fileURLWithPath: $0)) } ?? .resolve()let selfExe = VPhoneResources.runningExecutable()+ // Prompt for any firmware component not supplied on the command line.+ let sources = try VPhoneFirmwareSelection.resolve(iphone: iphoneSource, cloudos: cloudosSource)let orchestrator = VPhoneCreateOrchestrator(library: lib.library, resources: resources, selfExecutable: selfExe)try orchestrator.run(.init(- name: name, variant: variant, iphoneSource: iphoneSource, cloudosSource: cloudosSource,+ name: name, variant: variant,+ iphoneSource: sources.iphoneSource, cloudosSource: sources.cloudosSource,sudoPassword: sudoPassword, spoofBuild: spoofBuild, forceDSCMaxSlide: forceDSCMaxSlide,interactive: interactive, verbosity: VPhoneVerbosity(count: verboseCount)))}diff --git a/tests/VPhoneCoreTests/FirmwarePickerTests.swift b/tests/VPhoneCoreTests/FirmwarePickerTests.swiftnew file mode 100644index 00000000..f3f5f7a3--- /dev/null+++ b/tests/VPhoneCoreTests/FirmwarePickerTests.swift@@ -0,0 +1,143 @@+@testable import VPhoneCore+import Testing++struct FirmwarePickerTests {+ /// A scripted stdin: pops one line per `read()` call.+ private func reader(_ lines: [String?]) -> () -> String? {+ var i = 0+ return { defer { i += 1 }; return i < lines.count ? lines[i] : nil }+ }++ // MARK: - Catalog integrity++ @Test func catalogHasEighteenPairings() {+ #expect(VPhoneFirmwareCatalog.pairings.count == 18)+ }++ @Test func everyPairingIsPopulated() {+ for p in VPhoneFirmwareCatalog.pairings {+ #expect(!p.iosName.isEmpty)+ #expect(p.iosURL.hasPrefix("https://"))+ #expect(p.iosURL.hasSuffix(".ipsw"))+ #expect(p.cloudosName.hasPrefix("cloudOS "))+ #expect(p.cloudosURL.contains("/private-cloud-compute/"))+ }+ }++ @Test func cloudOSOptionsAreDistinctInFirstSeenOrder() {+ let opts = VPhoneFirmwareCatalog.cloudOSOptions+ #expect(opts.map(\.name) == ["cloudOS 26.1", "cloudOS 26.2", "cloudOS 26.3", "cloudOS 26.4"])+ #expect(Set(opts.map(\.url)).count == opts.count) // no dup URLs+ }++ // MARK: - Passthrough++ @Test func bothProvidedPassesThrough() throws {+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: "a.ipsw", cloudos: "b.dmg", isInteractive: true,+ read: { nil }, write: { _ in })+ #expect(out == VPhoneFirmwareSources(iphoneSource: "a.ipsw", cloudosSource: "b.dmg"))+ }++ @Test func nonInteractivePassesThroughEvenWhenIncomplete() throws {+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: false,+ read: { nil }, write: { _ in })+ #expect(out == VPhoneFirmwareSources(iphoneSource: nil, cloudosSource: nil))+ }++ @Test func emptyStringsTreatedAsUnset() throws {+ // Non-interactive + empty → passthrough as nil (no prompt), not "".+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: "", cloudos: "", isInteractive: false,+ read: { nil }, write: { _ in })+ #expect(out == VPhoneFirmwareSources(iphoneSource: nil, cloudosSource: nil))+ }++ // MARK: - Prompt: neither provided++ @Test func neitherProvidedPicksFullPairing() throws {+ // "1" → first pairing (iOS 18.6.2 → cloudOS 26.1).+ let first = VPhoneFirmwareCatalog.pairings[0]+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: true,+ read: reader(["1"]), write: { _ in })+ #expect(out == VPhoneFirmwareSources(iphoneSource: first.iosURL, cloudosSource: first.cloudosURL))+ }++ @Test func neitherProvidedResolvesBothFromChosenPairing() throws {+ let idx = 8 // iOS 26.4 (menu number 9), paired with cloudOS 26.4+ let p = VPhoneFirmwareCatalog.pairings[idx]+ #expect(p.iosName == "iOS 26.4")+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: true,+ read: reader([String(idx + 1)]), write: { _ in })+ #expect(out.iphoneSource == p.iosURL)+ #expect(out.cloudosSource == p.cloudosURL)+ }++ // MARK: - Prompt: only one side missing++ @Test func iPhoneProvidedPromptsForCloudOSOnly() throws {+ // cloudOS menu: [1]26.1 [2]26.2 [3]26.3 [4]26.4 → pick 4.+ let opts = VPhoneFirmwareCatalog.cloudOSOptions+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: "custom.ipsw", cloudos: nil, isInteractive: true,+ read: reader(["4"]), write: { _ in })+ #expect(out.iphoneSource == "custom.ipsw") // untouched+ #expect(out.cloudosSource == opts[3].url) // chosen cloudOS 26.4+ }++ @Test func cloudOSProvidedPromptsForIPhoneOnly() throws {+ let p = VPhoneFirmwareCatalog.pairings[3] // iOS 26.1 (menu 4)+ #expect(p.iosName == "iOS 26.1")+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: "custom.dmg", isInteractive: true,+ read: reader(["4"]), write: { _ in })+ #expect(out.iphoneSource == p.iosURL) // chosen iPhone build+ #expect(out.cloudosSource == "custom.dmg") // untouched+ }++ // MARK: - Menu formatting++ @Test func pairingMenuIsColumnAligned() throws {+ var lines: [String] = []+ _ = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: true,+ read: reader(["1"]), write: { lines.append($0) })+ let menu = lines.filter { $0.hasPrefix(" [") }+ #expect(menu.count == 18)+ // Label text starts in one column regardless of 1- vs 2-digit index.+ let labelStarts = Set(menu.map { $0.range(of: "] ")!.upperBound.utf16Offset(in: $0) })+ #expect(labelStarts.count == 1)+ // The "(→ cloudOS …)" arrow lands in one column across every row.+ let arrowCols = Set(menu.map { $0.range(of: "(→")!.lowerBound.utf16Offset(in: $0) })+ #expect(arrowCols.count == 1)+ }++ // MARK: - Retry / abort semantics++ @Test func retriesThenSucceeds() throws {+ let first = VPhoneFirmwareCatalog.pairings[0]+ let out = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: true,+ read: reader(["", "999", "garbage", "1"]), write: { _ in })+ #expect(out.iphoneSource == first.iosURL)+ }++ @Test func eofAborts() {+ #expect(throws: VPhoneFirmwarePickerError.aborted) {+ _ = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: true,+ read: { nil }, write: { _ in })+ }+ }++ @Test func tooManyInvalidThrows() {+ #expect(throws: VPhoneFirmwarePickerError.invalidSelection) {+ _ = try VPhoneFirmwarePicker.resolve(+ iphone: nil, cloudos: nil, isInteractive: true,+ maxRetries: 2, read: reader(["x", "y", "z"]), write: { _ in })+ }+ }+}