Architecture

The Swift package has three products: the DocksmithCore library, the DocksmithApp macOS GUI executable, and the read-only docksmith CLI. The core resolves and runs Apple’s separately installed cfgutil and decodes selected-device responses. Public IOKit USB discovery keeps a physically connected phone visible when Configurator cannot access it. Optional Xcode CoreDevice discovery and inventory match exact ECID or UDID identity; device names never determine targeting. Configurator takes precedence when available.

The app keeps device selection, app inventory, and a Home Screen draft in its workspace. It reads in the background and ignores stale results after selection changes. App removal requires an exact in-app preview and confirmation, then shows per-app outcomes. The preview freezes the device, target, backend and selected app identifiers. CoreDevice removal requires command support and explicit removable, nonhidden, noninternal inventory metadata. Device or backend drift stops the remaining batch. Absence is verified only from a complete fresh inventory. Layout editing works with a draft; Apply checks the current device layout against the baseline and saves a private local backup before writing. Unknown layout entries and partial reads prevent Apply.

The CLI remains read-only: devices discovers connected devices, and probe requires a selected device. A probe discovers again, checks the selection, requests installedApps, then requests the icon layout. It derives counts and warnings without returning raw inventory or layout contents in its public report.

Responses can be incomplete. A decodable response accompanied by a nonzero cfgutil status retains its decoded count and adds a partial-result warning. Malformed or missing data is reported as indeterminate. The CLI does not issue device-changing commands. The GUI can remove reviewed apps using Configurator or supported Xcode commands; Home Screen reads and writes require Configurator. Missing or partial layout data does not discard a successful app inventory.

Run swift test from the repository root for parser and device-selection checks. When filing issues, share commands and redacted warnings, never device identifiers, pairing material, app inventory, or raw device reports.