refactor: Move all manual clones to be submodules (#218)

.gitmodules

@@ -16,3 +16,33 @@
 [submodule "vendor/swift-argument-parser"]
 	path = vendor/swift-argument-parser
 	url = https://github.com/apple/swift-argument-parser.git
+[submodule "scripts/repos/trustcache"]
+	path = scripts/repos/trustcache
+	url = https://github.com/CRKatri/trustcache.git
+[submodule "scripts/repos/insert_dylib"]
+	path = scripts/repos/insert_dylib
+	url = https://github.com/tyilo/insert_dylib.git
+[submodule "scripts/repos/libplist"]
+	path = scripts/repos/libplist
+	url = https://github.com/libimobiledevice/libplist.git
+[submodule "scripts/repos/libimobiledevice-glue"]
+	path = scripts/repos/libimobiledevice-glue
+	url = https://github.com/libimobiledevice/libimobiledevice-glue.git
+[submodule "scripts/repos/libusbmuxd"]
+	path = scripts/repos/libusbmuxd
+	url = https://github.com/libimobiledevice/libusbmuxd.git
+[submodule "scripts/repos/libtatsu"]
+	path = scripts/repos/libtatsu
+	url = https://github.com/libimobiledevice/libtatsu.git
+[submodule "scripts/repos/libimobiledevice"]
+	path = scripts/repos/libimobiledevice
+	url = https://github.com/libimobiledevice/libimobiledevice.git
+[submodule "scripts/repos/libirecovery"]
+	path = scripts/repos/libirecovery
+	url = https://github.com/libimobiledevice/libirecovery.git
+[submodule "scripts/repos/idevicerestore"]
+	path = scripts/repos/idevicerestore
+	url = https://github.com/libimobiledevice/idevicerestore.git
+[submodule "scripts/repos/libzip"]
+	path = scripts/repos/libzip
+	url = https://github.com/nih-at/libzip.git

AGENTS.md

@@ -91,6 +91,7 @@ scripts/
 ├── patchers/                     # Python CFW patcher modules
 │   └── cfw.py                    #   CFW binary patcher entrypoint
 ├── resources/                    # Resource archives (git submodule)
+├── repos/                        # Toolchain source repos (git submodules: trustcache, insert_dylib, libimobiledevice stack)
 ├── patches/                      # Build-time patches (libirecovery)
 ├── fw_prepare.sh                 # Download IPSWs, merge cloudOS into iPhone
 ├── fw_manifest.py                # Generate hybrid BuildManifest/Restore plists
@@ -101,10 +102,10 @@ scripts/
 ├── cfw_install_jb.sh             # Regular + jetsam fix + procursus
 ├── vm_create.sh                  # Create VM directory
 ├── setup_machine.sh              # Full automation (setup → first boot)
-├── setup_tools.sh                # Install deps, build toolchain, create venv
+├── setup_tools.sh                # Install deps, build toolchain from submodules, create venv
 ├── setup_venv.sh                 # Create Python venv
 ├── setup_venv_linux.sh           # Create Python venv (Linux)
-├── setup_libimobiledevice.sh     # Build libimobiledevice from source
+├── setup_libimobiledevice.sh     # Build libimobiledevice stack from scripts/repos submodules
 └── tail_jb_patch_logs.sh         # Tail JB patch log output
 
 research/                         # Detailed firmware/patch documentation

Makefile

@@ -53,7 +53,7 @@ help:
 	@echo "             SUDO_PASSWORD=...         Preload sudo credential for setup flow"
 	@echo ""
 	@echo "Setup (one-time):"
-	@echo "  make setup_tools             Install all tools (brew, trustcache, insert_dylib, libimobiledevice, venv)"
+	@echo "  make setup_tools             Install all tools (brew, submodule-sourced trustcache/insert_dylib/libimobiledevice, venv)"
 	@echo ""
 	@echo "Build:"
 	@echo "  make build                   Build + sign vphone-cli"

README.md

@@ -85,7 +85,7 @@ Boot into Recovery (long press power button), open Terminal, then choose one set
 brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake
 ```
 
-**Submodules** — this repo uses a git submodule for resource archives. Clone with:
+**Submodules** — this repo uses git submodules for resources, vendored Swift deps, and toolchain sources under `scripts/repos/`. Clone with:
 
 ```bash
 git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
@@ -103,7 +103,7 @@ make setup_machine            # full automation through "First Boot" (includes r
 ## Manual Setup
 
 ```bash
-make setup_tools              # install brew deps, build trustcache, clone insert_dylib, build libimobiledevice, create Python venv
+make setup_tools              # install brew deps, build trustcache + insert_dylib + libimobiledevice from submodule sources, create Python venv
 make build                    # build + sign vphone-cli
 make vm_new                   # create VM directory with manifest (config.plist)
 # options: CPU=8 MEMORY=8192 DISK_SIZE=64

docs/README_ja.md

@@ -76,7 +76,7 @@ Apple の Virtualization.framework と PCC の研究用 VM インフラを使用
 brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake
 ```
 
-**Submodules** — このリポジトリはリソースアーカイブに git submodule を使用しています。クローン時に以下を使用してください：
+**Submodules** — このリポジトリはリソース、Swift 依存、`scripts/repos/` 配下のツールチェーンソースに git submodule を使用しています。クローン時に以下を使用してください：
 
 ```bash
 git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
@@ -92,7 +92,7 @@ make setup_machine            # 初回起動までを完全自動化（復元/
 ## 手動セットアップ
 
 ```bash
-make setup_tools              # brew の依存関係インストール、trustcache + libimobiledevice のビルド、Python venv の作成
+make setup_tools              # brew の依存関係インストール、submodule ソースから trustcache + insert_dylib + libimobiledevice をビルド、Python venv の作成
 make build                    # vphone-cli のビルド + 署名
 make vm_new                   # VM ディレクトリとマニフェスト（config.plist）の作成
 # オプション：CPU=8 MEMORY=8192 DISK_SIZE=64

docs/README_ko.md

@@ -76,7 +76,7 @@ PCC 리서치 VM 인프라와 Apple의 Virtualization.framework를 사용하여
 brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake
 ```
 
-**Submodules** — 이 저장소는 리소스 아카이브를 위해 git submodule을 사용합니다. 클론 시 다음 명령어를 사용하세요:
+**Submodules** — 이 저장소는 리소스, Swift 의존성, `scripts/repos/` 아래 툴체인 소스를 git submodule로 관리합니다. 클론 시 다음 명령어를 사용하세요:
 
 ```bash
 git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
@@ -92,7 +92,7 @@ make setup_machine            # "First Boot"까지의 전체 과정 자동화 (
 ## 수동 설정
 
 ```bash
-make setup_tools              # brew 의존성 설치, trustcache + libimobiledevice 빌드, Python venv 생성
+make setup_tools              # brew 의존성 설치, submodule 소스에서 trustcache + insert_dylib + libimobiledevice 빌드, Python venv 생성
 make build                    # vphone-cli 빌드 및 서명
 make vm_new                   # VM 디렉토리 및 매니페스트(config.plist) 생성
 # 옵션: CPU=8 MEMORY=8192 DISK_SIZE=64

docs/README_zh.md

@@ -76,7 +76,7 @@
 brew install ideviceinstaller wget gnu-tar openssl@3 ldid-procursus sshpass keystone autoconf automake pkg-config libtool cmake
 ```
 
-**Submodules** —— 本仓库使用 git submodule 存储资源文件。克隆时请使用：
+**Submodules** —— 本仓库通过 git submodule 管理资源、Swift 依赖以及 `scripts/repos/` 下的工具链源码。克隆时请使用：
 
 ```bash
 git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git
@@ -94,7 +94,7 @@ make setup_machine            # 完全自动化完成"首次启动"流程（包
 ## 手动设置
 
 ```bash
-make setup_tools              # 安装 brew 依赖、构建 trustcache + libimobiledevice、创建 Python 虚拟环境
+make setup_tools              # 安装 brew 依赖、从 submodule 源码构建 trustcache + insert_dylib + libimobiledevice、创建 Python 虚拟环境
 make build                    # 构建并签名 vphone-cli
 make vm_new                   # 创建 VM 目录及清单文件（config.plist）
 # 选项：CPU=8 MEMORY=8192 DISK_SIZE=64

research/0_binary_patch_comparison.md

@@ -301,3 +301,7 @@
   - replaced the old AppKit-first recorder path with a private-display-only implementation built around hidden `VZGraphicsDisplay._takeScreenshotWithCompletionHandler:` capture.
   - added still screenshot actions that can copy the captured image to the pasteboard or save a PNG to disk using the same private capture path.
   - `make build` is used as the sanity check path; live VM validation is still needed to confirm the exact screenshot object type returned on macOS 15.
+- 2026-03-15 tooling source sync update:
+  - removed ad-hoc `git clone` source fetching from `scripts/setup_tools.sh` and `scripts/setup_libimobiledevice.sh`.
+  - added pinned git-submodule sources under `scripts/repos/` for: `trustcache`, `insert_dylib`, `libplist`, `libimobiledevice-glue`, `libusbmuxd`, `libtatsu`, `libimobiledevice`, `libirecovery`, `idevicerestore`.
+  - setup scripts now initialize required submodules via `git submodule update --init --recursive <path>` and stage build copies under local tool build directories.

scripts/setup_libimobiledevice.sh

@@ -3,18 +3,20 @@
 #
 # Produces: idevicerestore, irecovery, and related idevice* tools
 # Prefix:   .limd/  (override with LIMD_PREFIX env var)
+# Source:   scripts/repos/* git submodules (staged into .limd/src before build)
 # Requires: autoconf automake libtool pkg-config cmake git
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPOS_DIR="$SCRIPT_DIR/repos"
 
 PREFIX="${LIMD_PREFIX:-$PROJECT_DIR/.limd}"
 SRC="$PREFIX/src"
 LOG="$PREFIX/log"
 
-NPROC="$(sysctl -n hw.logicalcpu)"
+NPROC="$(sysctl -n hw.logicalcpu 2>/dev/null || getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)"
 SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"
 
 OPENSSL_PREFIX="$(brew --prefix openssl@3 2>/dev/null || true)"
@@ -39,7 +41,7 @@ die() {
 
 check_tools() {
     local missing=()
-    for cmd in autoconf automake pkg-config cmake git; do
+    for cmd in autoconf automake pkg-config cmake git patch; do
         command -v "$cmd" &>/dev/null || missing+=("$cmd")
     done
     command -v glibtoolize &>/dev/null || command -v libtoolize &>/dev/null ||
@@ -47,17 +49,35 @@ check_tools() {
     ((${#missing[@]} == 0)) || die "Missing: ${missing[*]} — brew install ${missing[*]}"
 }
 
-clone() {
-    local url="$1" dir="$2"
-    if [[ -d "$dir/.git" ]]; then
-        git -C "$dir" fetch --depth 1 origin --quiet
-        git -C "$dir" reset --hard FETCH_HEAD --quiet
-        git -C "$dir" clean -fdx --quiet
-    else
-        git clone --depth 1 "$url" "$dir" --quiet
+ensure_repo_submodule() {
+    local rel_path="$1"
+    local abs_path="$PROJECT_DIR/$rel_path"
+
+    if [[ ! -e "$abs_path/.git" ]]; then
+        git -C "$PROJECT_DIR" submodule update --init --recursive "$rel_path"
     fi
 }
 
+stage_repo_source() {
+    local name="$1"
+    local src_dir="$REPOS_DIR/$name"
+    local dst_dir="$SRC/$name"
+    local version=""
+
+    ensure_repo_submodule "scripts/repos/$name"
+    rm -rf "$dst_dir"
+    ditto "$src_dir" "$dst_dir"
+
+    # Some autotools projects expect either git metadata or .tarball-version.
+    # Staged sources are intentionally detached from git, so preserve version info.
+    version="$(git -C "$src_dir" describe --tags --always 2>/dev/null || true)"
+    if [[ -n "$version" ]]; then
+        printf "%s\n" "$version" >"$dst_dir/.tarball-version"
+    fi
+
+    rm -rf "$dst_dir/.git"
+}
+
 build_lib() {
     local name="$1"
     shift
@@ -76,12 +96,14 @@ build_lib() {
 check_tools
 echo "Building libimobiledevice toolchain → $PREFIX"
 echo ""
+echo "Using submodule sources from scripts/repos/"
+echo ""
 
 # ── 1. Core libraries ───────────────────────────────────────────
 
 echo "[1/3] Core libraries (using homebrew openssl@3)"
 for lib in libplist libimobiledevice-glue libusbmuxd libtatsu libimobiledevice; do
-    clone "https://github.com/libimobiledevice/$lib" "$SRC/$lib"
+    stage_repo_source "$lib"
     case "$lib" in
         libplist | libimobiledevice) build_lib "$lib" --without-cython ;;
         *) build_lib "$lib" ;;
@@ -91,42 +113,43 @@ done
 # ── 2. libirecovery (+ PCC research VM patch) ───────────────────
 
 echo "[2/3] libirecovery + libzip"
-clone "https://github.com/libimobiledevice/libirecovery" "$SRC/libirecovery"
+stage_repo_source "libirecovery"
 
 # PR #150: register iPhone99,11 / vresearch101ap for PCC research VMs
 if ! grep -q 'vresearch101ap' "$SRC/libirecovery/src/libirecovery.c"; then
-    cd "$SRC/libirecovery"
-    git apply "$SCRIPT_DIR/patches/libirecovery-pcc-vm.patch" ||
-        die "Failed to apply libirecovery PCC patch — check context"
-    cd "$SRC"
+    if ! (cd "$SRC/libirecovery" && patch -p1 --batch --forward --dry-run <"$SCRIPT_DIR/patches/libirecovery-pcc-vm.patch" >/dev/null); then
+        die "Failed to validate libirecovery PCC patch — check context"
+    fi
+    if ! (cd "$SRC/libirecovery" && patch -p1 --batch --forward <"$SCRIPT_DIR/patches/libirecovery-pcc-vm.patch" >"$LOG/libirecovery-pcc-vm.patch.log" 2>&1); then
+        die "Failed to apply libirecovery PCC patch — see $LOG/libirecovery-pcc-vm.patch.log"
+    fi
+    grep -q 'vresearch101ap' "$SRC/libirecovery/src/libirecovery.c" ||
+        die "libirecovery PCC patch command succeeded but expected marker is still missing"
 fi
 build_lib libirecovery
 
-# ── libzip (static, for idevicerestore) ──────────────────────────
+# ── libzip (static, for idevicerestore, from submodule) ───────────
 
-LIBZIP_VER="1.11.4"
 if [[ ! -f "$PREFIX/lib/pkgconfig/libzip.pc" ]]; then
     echo "  libzip"
-    [[ -d "$SRC/libzip-$LIBZIP_VER" ]] ||
-        curl -LfsS "https://github.com/nih-at/libzip/releases/download/v$LIBZIP_VER/libzip-$LIBZIP_VER.tar.gz" |
-        tar xz -C "$SRC"
-    cmake -S "$SRC/libzip-$LIBZIP_VER" -B "$SRC/libzip-$LIBZIP_VER/build" \
+    stage_repo_source "libzip"
+    cmake -S "$SRC/libzip" -B "$SRC/libzip/build" \
         -DCMAKE_INSTALL_PREFIX="$PREFIX" -DCMAKE_OSX_SYSROOT="$SDKROOT" \
         -DBUILD_SHARED_LIBS=OFF -DBUILD_DOC=OFF -DBUILD_EXAMPLES=OFF \
         -DBUILD_REGRESS=OFF -DBUILD_TOOLS=OFF \
         -DENABLE_BZIP2=OFF -DENABLE_LZMA=OFF -DENABLE_ZSTD=OFF \
         -DENABLE_GNUTLS=OFF -DENABLE_MBEDTLS=OFF -DENABLE_OPENSSL=OFF \
         >"$LOG/libzip-cmake.log" 2>&1
-    cmake --build "$SRC/libzip-$LIBZIP_VER/build" -j"$NPROC" \
+    cmake --build "$SRC/libzip/build" -j"$NPROC" \
         >"$LOG/libzip-build.log" 2>&1
-    cmake --install "$SRC/libzip-$LIBZIP_VER/build" \
+    cmake --install "$SRC/libzip/build" \
         >"$LOG/libzip-install.log" 2>&1
 fi
 
 # ── 3. idevicerestore ───────────────────────────────────────────
 
 echo "[3/3] idevicerestore"
-clone "https://github.com/libimobiledevice/idevicerestore" "$SRC/idevicerestore"
+stage_repo_source "idevicerestore"
 build_lib idevicerestore \
     libcurl_CFLAGS="-I$SDKROOT/usr/include" \
     libcurl_LIBS="-lcurl" \

scripts/setup_tools.sh

@@ -2,26 +2,23 @@
 # setup_tools.sh — Install all required host tools for vphone-cli
 #
 # Installs brew packages, builds trustcache from source,
-# clones insert_dylib, builds libimobiledevice toolchain, and creates Python venv.
+# builds insert_dylib from submodule source, builds libimobiledevice toolchain, and creates Python venv.
 #
 # Run: make setup_tools
 
 set -euo pipefail
 
-SCRIPT_DIR="${0:a:h}"
-PROJECT_DIR="${SCRIPT_DIR:h}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 TOOLS_PREFIX="${TOOLS_PREFIX:-$PROJECT_DIR/.tools}"
+REPOS_DIR="$SCRIPT_DIR/repos"
 
-clone_or_update() {
-    local url="$1"
-    local dir="$2"
+ensure_repo_submodule() {
+    local rel_path="$1"
+    local abs_path="$PROJECT_DIR/$rel_path"
 
-    if [[ -d "$dir/.git" ]]; then
-        git -C "$dir" fetch --depth 1 origin --quiet
-        git -C "$dir" reset --hard FETCH_HEAD --quiet
-        git -C "$dir" clean -fdx --quiet
-    else
-        git clone --depth 1 "$url" "$dir" --quiet
+    if [[ ! -e "$abs_path/.git" ]]; then
+        git -C "$PROJECT_DIR" submodule update --init --recursive "$rel_path"
     fi
 }
 
@@ -53,11 +50,14 @@ TRUSTCACHE_BIN="$TOOLS_PREFIX/bin/trustcache"
 if [[ -x "$TRUSTCACHE_BIN" ]]; then
     echo "  Already built: $TRUSTCACHE_BIN"
 else
-    echo "  Building from source (CRKatri/trustcache)..."
+    echo "  Building from submodule source (scripts/repos/trustcache)..."
+    ensure_repo_submodule "scripts/repos/trustcache"
+
     BUILD_DIR=$(mktemp -d)
     trap "rm -rf '$BUILD_DIR'" EXIT
 
-    git clone --depth 1 https://github.com/CRKatri/trustcache.git "$BUILD_DIR/trustcache" --quiet
+    ditto "$REPOS_DIR/trustcache" "$BUILD_DIR/trustcache"
+    rm -rf "$BUILD_DIR/trustcache/.git"
 
     OPENSSL_PREFIX="$(brew --prefix openssl@3)"
     make -C "$BUILD_DIR/trustcache" \
@@ -79,9 +79,8 @@ INSERT_DYLIB_BIN="$TOOLS_PREFIX/bin/insert_dylib"
 if [[ -x "$INSERT_DYLIB_BIN" ]]; then
     echo "  Already built: $INSERT_DYLIB_BIN"
 else
-    INSERT_DYLIB_DIR="$TOOLS_PREFIX/src/insert_dylib"
-    mkdir -p "${INSERT_DYLIB_DIR:h}"
-    clone_or_update "https://github.com/tyilo/insert_dylib" "$INSERT_DYLIB_DIR"
+    INSERT_DYLIB_DIR="$REPOS_DIR/insert_dylib"
+    ensure_repo_submodule "scripts/repos/insert_dylib"
     echo "  Building insert_dylib..."
     mkdir -p "$TOOLS_PREFIX/bin"
     clang -o "$INSERT_DYLIB_BIN" "$INSERT_DYLIB_DIR/insert_dylib/main.c" -framework Security -O2