Add iPhone17,3 iOS 27.0 beta 8 (24A5430a) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 22 -> 23.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add iPhone17,3 iOS 27.0 beta 7 (24A5424a) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 21 -> 22.
Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Ej64m761KR33KaNYh3BuTo
The bundled 26.6.1 IPSW pointed at the 23G82 release candidate, which
differs from the shipped release. Point it at the 23G83 final restore
and update the tested-environment tables accordingly.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add iPhone17,3 iOS 27.0 beta 6 (24A5418b) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 20 -> 21.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add iPhone17,3 iOS 26.6.1 (23G82) paired with cloudOS 26.4 to the
firmware catalog so it appears in the `fw prepare` picker, `fw catalog`,
and the `--json` report. Document it in the Tested Environments table
across README.md and the ja/ko/zh translations. Bump the hardcoded
pairing/menu count in FirmwarePickerTests 19 -> 20.
Co-Authored-By: Claude Fable 5 <[email protected]>
Export/import UX overhaul, wiring in the counting-pipe and progress-bar
primitives:
- Compression: replace `--compress {fast,balanced,max}` with a fast
(zstd -3) default and a single `--max` (xz -9) flag; drop balanced.
- `vm export --out DIR`: when the destination is an existing directory,
auto-name the archive `<vm>.tzst`/`.txz` and print the resolved path.
- `vm import ARCHIVE`: take the archive as a positional argument instead
of `--in`.
- Progress bars: export runs a two-stage tar pipeline (uncompressed
gnutar producer -> compressing consumer via bsdtar `@-`) so the bar is
driven off the known uncompressed total; import extracts once (was
decompressing twice) and counts the archive as it is fed into `tar -x`.
gnutar avoids the pax-header `@-` mtree misbid on large members and,
unlike ustar, carries files >8 GB.
Import validates the single top-level bundle after extracting into a
private staging dir, still failing fast on an explicit --name collision.
Tests: default is fast zstd; --max is xz; directory auto-naming yields
the right extensions; export/import invoke progress with monotonic,
correctly-totalled callbacks.
Co-Authored-By: Claude Fable 5 <[email protected]>
Two building blocks for streaming progress on vm export/import, unused
until the export/import rework wires them in:
- VPhoneProcessRunner.runCountingTarPipe: drives a /usr/bin/tar consumer
that reads its archive on stdin, invoking a callback with the running
byte total. The source is either a producer tar (export) or a file read
directly (import). SIGPIPE is ignored so a consumer that dies early
surfaces as its exit status instead of killing this process.
- VPhoneProgressBar: a single-line redrawing byte bar that renders to
stderr only when it is a TTY, so piped/--json/GUI-subprocess runs stay
clean and it simply no-ops.
Co-Authored-By: Claude Fable 5 <[email protected]>
Export previously hardcoded xz -9 (the densest but slowest libarchive
compressor), forcing a multi-GB Disk.img through the most aggressive
setting on every export.
Add a `--compress {fast,balanced,max}` preset on `vphone vm export`,
default `balanced`:
fast zstd -3
balanced zstd -19 (new default)
max xz -9 (previous behavior)
All presets go through the same system /usr/bin/tar (libarchive) already
used for xz, so no new dependency and no raised platform floor. Import is
unchanged: it already auto-detects the compressor via `tar -tf`/`-xf`, so
zstd and xz archives both import.
Tests assert each preset's magic bytes (zstd vs xz), that fast/max
round-trip, and the default is zstd. README examples updated.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add the iPhone17,3 27.0 24A5408d + cloudOS 26.4 pairing to the firmware
catalog so it is selectable in `fw prepare` / `vm create`, and bump the two
hardcoded pairing counts in the picker tests (18 -> 19).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01N2bwKrGJWY7o2ArdxibVPe
The unified tool provisions ~/.vphone/venv itself and never runs
setup_venv.sh, so it lost that script's libkeystone handling. It
pip-installs and then verifies with pythonIsUsable, which only probes
ipsw_parser — a venv with keystone bindings and no native library
passes, gets cached as good, and fails much later inside fw patch.
That state is reachable and silent. PyPI has no arm64 macOS wheel
(only macosx_10_14_x86_64), so pip builds keystone-engine from its
sdist, and the sdist's darwin path ignores the build's exit status
(subprocess.call plus a glob that matches nothing) — a failed native
build still installs bindings alone and pip reports success.
Probe that keystone can assemble rather than merely import, and on
failure install a loadable dylib next to the bindings: copy one from
Homebrew if the bottle ships it, else link one from libkeystone.a,
matching setup_venv.sh. The managed venv is repaired in place before
being rebuilt, since a missing dylib is not worth a full re-install.
Verified: repairs a venv whose dylibs were removed, and recovers a
fresh bootstrap that produced bindings-only (pip cache cleared, cmake
off PATH) — pip exits 0, the guard catches it, the venv is accepted.
Co-Authored-By: Claude Fable 5 <[email protected]>
`do shell script … with administrator privileges` runs the command under a
helper process that inherits none of our fds, so AppleScript can only hand
back its output once the command has EXITED — and it rewrites every \n to
\r on the way, which a reader applying terminal semantics (the GUI's log
view) takes for progress-bar overwrites, keeping only the final line. The
CFW install stage therefore sat silent for minutes and then showed one line.
Name our own terminal in the command instead: ttyname(stdout) is an absolute
device path the privileged shell can open, and under the GUI it is already
the pty the app is reading. Output then arrives as produced, with newlines
intact, on a tty the script's children line-buffer to. Gated on `echo` so
quiet verbosity still suppresses it, and skipped when stdout is not a tty.
Co-Authored-By: Claude Fable 5 <[email protected]>
Show the known iOS ↔ cloudOS firmware pairings, one recommended cloudOS
per iOS build, projected from VPhoneFirmwareCatalog.pairings. Human
output is an aligned table; `--json`/`-j` emits an object carrying the
device plus each pairing's download URLs.
Co-Authored-By: Claude Fable 5 <[email protected]>
`vm info --json` and `vm list --json` encode VPhoneBundleReport, which
carried no network field — so the network mode was absent from JSON even
though the human-readable output prints `net:`. Consumers parsing JSON had
no way to read a VM's network config.
Project the manifest's NetworkConfig into VPhoneBundleReport as `network`,
so both `info` and `list` emit it as structured JSON (mode, macAddress,
bridgeInterface). NetworkConfig gains Equatable (VPhoneBundleReport is
Equatable). The text `net:` line now reads from the same report projection.
Co-Authored-By: Claude Fable 5 <[email protected]>
`vm info` now reports the CFW variant the VM was last restored to, its
predicted UDID, and the product type the guest identifies as.
- udid: read from the bundle's udid-prediction.txt (VPhoneRestoreOps.resolveUDID)
- variant + device: recorded into restore-info.json at CFW-install time, in
both the standalone `cfw install` and the `vm create` orchestrator. device is
iPhone99,11 for every variant except exp, whose DeviceTree rewrite -> iPhone17,3.
- both new restore-info.json fields are optional, so pre-existing bundles decode
unchanged and pick up variant/device on their next install.
Co-Authored-By: Claude Fable 5 <[email protected]>
Adds `--network nat|bridged|none` and `--bridge-interface` to `vm config`,
and wires the boot path to honor the stored networkConfig (it previously
hardcoded NAT and ignored the manifest). `vm info` now shows the mode.
- New VPhoneNetworking: validates the mode, resolves/auto-picks the bridge
interface, and builds the VZ network device — shared by config-time
editing and boot.
- bridged uses VZBridgedNetworkDeviceAttachment (com.apple.vm.networking
entitlement already present); hostOnly is rejected (no native VZ
attachment); none yields no NIC.
- Rename NetworkMode.none -> .off (raw value kept "none") so a NetworkMode?
literal `.none` can't silently bind to Optional.none.
The MAC is left framework-assigned; forcing a custom MAC breaks guest
networking, so no MAC override is exposed.
Co-Authored-By: Claude Fable 5 <[email protected]>
* feat: add --root-popup to elevate CFW host-mount via macOS auth dialog
Adds --root-popup to `cfw install` and `vm create`, elevating the CFW host-mount through macOS's native authentication dialog (osascript -> do shell script with administrator privileges) instead of the script's sudo re-exec. do shell script runs under a bare env, so the vars the bundled scripts read are forwarded inline, plus SUDO_USER so the script's chown-back still returns artifacts to the invoking user. On `vm create`, --sudo-password takes precedence.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
* cfw: remove entire .cfw_temp on install cleanup
Replaces the selective `rm -f` of individual temp binaries with `rm -rf "$TEMP_DIR"`, dropping the cached Cryptex DMGs along with the temp files.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
Delete the three large regenerable intermediates once their consumers
finish, keeping the source archives so nothing needs re-downloading:
- built restore firmware (iPhone*_Restore/) after CFW install (its last
consumer — it copies the SystemOS/AppOS cryptexes onto Disk.img)
- extracted base-IPSW dirs (iOS + cloudOS) at end of fw prepare; the
downloaded .ipsw files are kept, so a re-run re-extracts, no re-download
- extracted CFW input dirs (cfw_input/, cfw_jb_input/) after cfw install;
the resources .tar.zst archives are kept
Opt out with --keep-artifacts on `vm create` / `cfw install`, which
threads VPHONE_KEEP_ARTIFACTS to fw_prepare.sh and cfw_install_host.sh.
Co-authored-by: Claude Fable 5 <[email protected]>
Snapshot the restored iOS userland and cloudOS kernel versions to
restore-info.json at the bundle root so they are readable without booting
the VM, rewritten after every successful restore (vm create and vm restore).
Versions are read host-side from the bundle's iPhone*_Restore plists
(iPhone-BuildManifest.plist for iOS, the hybrid BuildManifest.plist for
cloudOS). vm list / vm info / --json surface them; the file lives at the
bundle root so vm export carries it even when the IPSW dir is excluded.
Co-authored-by: Claude Fable 5 <[email protected]>
`vm create` on an interactive terminal now prompts for whichever firmware
component wasn't passed on the command line, choosing from a known-good
iPhone/cloudOS catalog by friendly name (e.g. "iOS 26.4", "cloudOS 26.4")
rather than raw URLs. Supply one of --iphone-source/--cloudos-source and
only the other is asked for; supply neither and a full pairing is chosen.
Non-interactive runs (or both flags set) pass through unchanged, so
fw_prepare's defaults still fill any gap and scripted use is unaffected.
- VPhoneFirmwareCatalog: 18 iPhone17,3 pairings + 4 distinct cloudOS images.
- VPhoneFirmwarePicker: pure, injectable-I/O resolver (13 unit tests).
- VPhoneFirmwareSelection: TTY adapter (isatty + readLine → stderr prompts).
- Wired into `vm create` before the orchestrator runs; READMEs (+ ja/ko/zh)
document the prompt behavior.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
A whole-codebase audit surfaced path bugs that only bite the bundled .app —
especially when brew puts vphone-cli on $PATH via a symlink, so the process
launches by a bare name from an arbitrary CWD:
- HIGH (crash): CommandLine.arguments[0] was used to locate the running binary
and the resource base (VPhoneResources.resolve default, vm launch bootBinary,
vm create selfExe). Under a bare-name PATH launch argv[0] is just
"vphone-cli", which URL(fileURLWithPath:) resolves against the CWD (e.g.
$HOME/vphone-cli) — so `vm launch` errored "not found" and `vm create` couldn't
respawn to boot. Add VPhoneResources.runningExecutable() using
Bundle.main.executableURL (the kernel-provided path, correct regardless of
argv[0]/CWD/symlink) and route all three through it. One helper fixes every
.resolve() consumer.
- MEDIUM (silent): the extra-deb feature resolved its cache + manifest under the
read-only bundle (Resources/debs, Resources/debs.list). Honor VPHONE_DEBS_DIR
(a writable ~/.vphone/debs the app now sets, mirroring IPSW_DIR/VPHONE_SEAL_DIR)
and bundle debs.list.
- LOW (cosmetic): fw_prepare read ../README.md (absent in the bundle → firmwares
labeled "Not Tested"). Bundle README.md.
Verified: Bundle.main.executableURL yields the real binary under a bare-name
symlink launch (argv[0] → $HOME); build clean; 79 VPhoneCore tests pass.
Foundation `Process` starts children in a NEW process group, so a sudo it
spawns is a *background* member of the controlling terminal — it can't disable
echo or read the tty, so the typed password showed and wasn't delivered. No
stdio wiring fixes that (confirmed: a Process child's pgid != the parent's).
Add VPhoneProcessRunner.runForeground: hand the terminal to the child's process
group via tcsetpgrp (SIGTTOU/SIGTTIN ignored during the swap), restore ours
after. The CFW-install step uses it when no --sudo-password is given, so sudo
owns the tty and reads the password DIRECTLY — vphone-cli never sees it. Its
`echo` flag still honors verbosity: quiet suppresses the install's own output
(stdout/stderr → /dev/null) while sudo's /dev/tty prompt keeps working. With
--sudo-password the unattended askpass path is unchanged; a non-interactive run
with no password fails fast.
Verified under a PTY: without tcsetpgrp the child is background (the bug); with
it the child is foreground; and echo=false hides the child's output while it
stays foreground.
Also serialize LibraryTests: its two VPHONE_LIBRARY_ROOT env tests mutate a
process-global and raced under Swift Testing's parallelism (intermittent
failures) — mark the suite @Suite(.serialized).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
The library the consolidated CLI is built on:
- bundle/library model (VPhoneBundle, VPhoneLibrary, VPhoneVirtualMachineManifest),
bundle ops + reporting, restore helpers (VPhoneRestoreOps)
- host process primitives: VPhoneProcessRunner, VPhoneManagedProcess (spawn +
stdout pattern-match + SIGKILL-escalating terminate), VPhoneLaunchLayout,
VPhoneBootPatterns
- VPhoneResources: bundled-.app vs dev asset resolution, and Python resolution
that provisions a per-user venv (~/.vphone/venv) on demand so the app is
portable — never depends on the repo's .venv
- VPhoneVerbosity (quiet/info/debug/trace) and VPhoneVMPicker
Manifest moves out of the executable target into VPhoneCore. Full unit-test
suite under tests/VPhoneCoreTests.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Y4VDqWf5pVakcFLqB23CKe
