Unify Android and iOS config formats

This commit is contained in:
James Babcock committed 2026-10-31 15:43:55 -07:00
1 parent 35a4ae7064
commit 210b111e27
18 files changed
+1116 -427

No files matched your search

+118
View File
@@ -0,0 +1,118 @@
# Config transfer (Android and iOS)
Both platforms export and import the same JSON config document, so a config
pulled from one phone can be pushed to either platform.
```sh
scripts/pull_config.sh # Android -> faceclaw_settings.android.json
scripts/push_config.sh # faceclaw_settings.android.json -> Android
scripts/pull_config_ios.sh # iPhone -> faceclaw_settings.ios.json
scripts/push_config_ios.sh # faceclaw_settings.ios.json -> iPhone
scripts/pull_config.sh && scripts/push_config_ios.sh faceclaw_settings.android.json # Android -> iPhone
scripts/pull_config_ios.sh && scripts/push_config.sh faceclaw_settings.ios.json # iPhone -> Android
```
Push also accepts legacy Android shared-preferences XML (`faceclaw_settings.xml`
from older `pull_config.sh`). Pulls write files with mode 600; the default
filenames are gitignored. **Configs contain API keys and Terminal tokens: treat
them as secrets.**
## Format
```json
{
"schema": 2,
"platform": "android",
"appVersion": "0.8.3",
"settings": {
"display.timeFormat": "24h",
"terminal.autoReconnect": true,
"terminal.connections": [{ "id": "c1", "url": "g2mirror://token@host:8737", "enabled": true }]
},
"platformSettings": {
"deviceAddress.left": "EC:D7:82:69:3C:CB",
"notifications.sources": [{ "packageName": "com.tailscale.ipn", "appName": "Tailscale", "showOnGlasses": true }]
}
}
```
- `settings` are imported on any platform.
- `platformSettings` are imported only when `platform` matches the phone importing
them. They are the settings that would be wrong on another phone: the paired
glasses and ring, onboarding state, notification sources (Android package names
vs iOS bundle IDs), Android media apps, file paths (Files bookmarks, Teleprompter
recents), installed EvenHub packages, per-phone device IDs and `ios.*` internals.
The list is `SettingsTransfer.isPlatformLocal` in
`native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/settings/SettingsTransfer.kt`;
every other setting is portable, including ones only one platform uses today, so
they survive a round trip through the other platform. An enum value one platform
doesn't offer (e.g. the Android-only "external" assistant backend) is harmless:
each setting reads as its default when its stored value isn't one of its choices.
- Values are strings, booleans and numbers, as the app stores them. Settings stored
as JSON text (connections, folders, fonts, timers, EvenHub app storage, ...) are
written as real JSON objects/arrays when that round-trips exactly; on import any
object/array is stored back as its compact JSON text.
Schema 1 (a flat `settings` object, from older iOS pulls) is still accepted; its keys
are sorted into portable and platform-local at import time. When editing by hand,
move a key between the two sections to control whether it crosses platforms.
## Semantics
Push **merges**: settings the file doesn't mention are left alone, so a cross-platform
import keeps the target phone's pairing and other platform-local settings. To clear a
value, supply its empty/default value. Malformed files, null values and files over
2 MiB fail before the device is touched (`scripts/config_document.py`) or before
anything is written (the phone re-validates with the same Kotlin codec).
Each import first saves the previous settings: Android writes a config document to
the app's private `files/faceclaw-settings-previous.json`; iOS saves its preferences
to `Library/FaceclawConfigPort/previous.plist`. Both apps restart after an import.
Storage itself is unchanged and per-platform. Android keeps settings in
`shared_prefs/faceclaw_settings.xml`, except the pairing, onboarding and EvenHub
localStorage keys, which still live in NativeScript's `prefs.db.xml`; the export reads
and the import writes each key in the file the app reads it from
(`FaceclawSettingsPortReceiver.nativeScriptKey`). iOS keeps everything in its
NSUserDefaults app domain.
## Android
`pull_config.sh` / `push_config.sh` drive `FaceclawSettingsPortReceiver` with
`am broadcast`, which works on debug and release builds (release builds refuse
`run-as`). The receiver is guarded by `android.permission.DUMP`, so only the adb shell
can trigger it. The document is shuttled through the app's external files dir and
deleted as soon as it has been read. An import writes through the app's live
SharedPreferences, then exits the app so its next launch starts from the imported
settings. Pass `-s SERIAL` (or other adb options) to pick a device.
## iOS
Requires Xcode, Python 3, a development build with `FaceclawConfigPort`, and an
unlocked/trusted iPhone. Both commands restart Faceclaw, briefly interrupting its
Bluetooth and Terminal sessions.
```sh
scripts/pull_config_ios.sh -f /tmp/settings.json --device IPHONE_UDID
scripts/push_config_ios.sh faceclaw_settings.xml # legacy Android pull_config.sh output
```
Use `--device` / `-d` or set `IOS_DEVICE` when more than one device is connected.
Without either, the script selects the only device with an active Xcode tunnel.
For the simulator, add `--simulator` (defaults to `booted`; `--device` selects one).
Transfers use `devicectl` app-container access. The app consumes a uniquely
identified request at bootstrap, before loading settings getters and workers;
it applies imports through NSUserDefaults rather than overwriting a plist that
cfprefsd could restore from cache. Replies are checked against the request ID, so a
stale export cannot appear to confirm an import. Scripts do not print values and
remove their private temporary directory on exit. Device request/reply/backup files
stay in the private Library directory, outside Files/Finder Documents.
Terminal's configured `g2mirror://` scheme uses plain WebSockets; `g2mirrors://`
uses TLS. The iOS build declares local networking and an explicit ATS exception
for the current development server `100.68.94.67`. On iOS 17+, another literal IP
requires its own build-time `NSExceptionDomains` entry, or a TLS endpoint. The
exception does not disable TLS certificate verification. See Apple's
[IP exception rules](https://developer.apple.com/documentation/bundleresources/information-property-list/nsapptransportsecurity/nsexceptiondomains).