From 210b111e2736a9fe4ea7248a7fd01bf9bce82092 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Sat, 31 Oct 2026 15:43:55 -0700 Subject: [PATCH] Unify Android and iOS config formats --- .gitignore | 4 +- .../java/com/faceclaw/app/FaceclawSettings.kt | 14 +- .../app/FaceclawSettingsPortReceiver.kt | 227 +++++++++++------- App_Resources/iOS/src/FaceclawConfigPort.h | 15 +- App_Resources/iOS/src/FaceclawConfigPort.m | 115 ++++++--- README.md | 5 +- .../com/faceclaw/app/SettingsDocument.kt | 70 ------ .../faceclaw/app/settings/SettingsTransfer.kt | 179 ++++++++++++++ scripts/config-transfer.md | 118 +++++++++ scripts/config_document.py | 132 ++++++++++ scripts/ios-config.md | 53 ---- scripts/ios_config.py | 101 ++------ scripts/pull_config.sh | 81 ++++--- scripts/push_config.sh | 115 +++++---- tests/config-transfer-scripts.test.cjs | 76 ++++++ tests/ios-config-scripts.test.cjs | 21 -- .../com/faceclaw/app/SettingsTransferTest.kt | 151 ++++++++++++ tests/native/ios-config-test.m | 66 ++++- 18 files changed, 1116 insertions(+), 427 deletions(-) delete mode 100644 native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/SettingsDocument.kt create mode 100644 native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/settings/SettingsTransfer.kt create mode 100644 scripts/config-transfer.md create mode 100644 scripts/config_document.py delete mode 100644 scripts/ios-config.md create mode 100644 tests/config-transfer-scripts.test.cjs delete mode 100644 tests/ios-config-scripts.test.cjs create mode 100644 tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/SettingsTransferTest.kt diff --git a/.gitignore b/.gitignore index 182e101e..8515643e 100644 --- a/.gitignore +++ b/.gitignore @@ -44,9 +44,9 @@ __pycache__ !.vscode/launch.json !.vscode/extensions.json -# pull_config.sh output: the phone's live settings, including API keys +# pull_config*.sh output: the phone's live settings, including API keys faceclaw_settings.xml -faceclaw_settings.ios.json +faceclaw_settings*.json # Developer configs build_paths.sh diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettings.kt b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettings.kt index 6a6b1450..f48315fe 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettings.kt +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettings.kt @@ -25,13 +25,23 @@ class FaceclawSettings private constructor(context: Context) { private val prefs: SharedPreferences = context.applicationContext .getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE) private val hub = SettingsChangeHub(object : SettingsStorage { - override fun getString(key: String?, defaultValue: String?): String? = prefs.getString(key, defaultValue) + // An imported or hand-edited config can store a setting as a different type than the + // app reads it as (iOS is lenient about this); read it as text rather than crash. + override fun getString(key: String?, defaultValue: String?): String? = try { + prefs.getString(key, defaultValue) + } catch (_: ClassCastException) { + prefs.all[key]?.toString() ?: defaultValue + } override fun putString(key: String?, value: String?) { prefs.edit().putString(key, value).apply() } - override fun getBoolean(key: String?, defaultValue: Boolean): Boolean = prefs.getBoolean(key, defaultValue) + override fun getBoolean(key: String?, defaultValue: Boolean): Boolean = try { + prefs.getBoolean(key, defaultValue) + } catch (_: ClassCastException) { + prefs.all[key]?.toString()?.toBooleanStrictOrNull() ?: defaultValue + } override fun putBoolean(key: String?, value: Boolean) { prefs.edit().putBoolean(key, value).apply() diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.kt b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.kt index 788c93a1..d8fc8abf 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.kt +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.kt @@ -3,52 +3,68 @@ package com.faceclaw.app import android.content.BroadcastReceiver import android.content.Context import android.content.Intent +import android.content.SharedPreferences import android.os.Handler import android.os.Looper +import android.util.AtomicFile import android.util.Log -import android.util.Xml - -import org.xmlpull.v1.XmlPullParser import java.io.File -import java.io.FileInputStream -import java.io.FileOutputStream import java.io.IOException -import java.io.InputStream -import java.io.OutputStream /** - * adb-triggered export/import of the faceclaw_settings SharedPreferences - * file, so configuration (API keys, device addresses, ...) can be moved off a - * release build, where run-as is unavailable. See scripts/pull_config.sh and - * scripts/push_config.sh, which use run-as on debuggable builds and fall back - * to this receiver otherwise. + * adb-triggered export/import of Faceclaw's settings as the JSON document shared with iOS + * (SettingsTransfer; see scripts/config-transfer.md). scripts/pull_config.sh and + * scripts/push_config.sh drive it; it works on release builds, where run-as is unavailable. * - * adb shell am broadcast -n com.faceclaw.app/.FaceclawSettingsPortReceiver \ - * -a com.faceclaw.app.SETTINGS_EXPORT - * adb pull /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-export.xml + * adb shell am broadcast --include-stopped-packages \ + * -n com.faceclaw.app/.FaceclawSettingsPortReceiver -a com.faceclaw.app.SETTINGS_EXPORT + * adb pull /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-export.json * - * adb push settings.xml /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-import.xml - * adb shell am broadcast -n com.faceclaw.app/.FaceclawSettingsPortReceiver \ - * -a com.faceclaw.app.SETTINGS_IMPORT + * adb push settings.json /sdcard/Android/data/com.faceclaw.app/files/faceclaw-settings-import.json + * adb shell am broadcast --include-stopped-packages \ + * -n com.faceclaw.app/.FaceclawSettingsPortReceiver -a com.faceclaw.app.SETTINGS_IMPORT * - * Security: the settings file contains API tokens, so the manifest guards - * this receiver with android.permission.DUMP — a development permission the - * adb shell holds but ordinary apps cannot obtain without adb's help, keeping - * the trigger reachable from adb only. The transfer file lives in - * getExternalFilesDir(), which other apps cannot read on Android 11+ (and - * which the scripts delete as soon as the transfer completes); on the - * Android 7-10 devices minSdk still admits, apps holding READ_EXTERNAL_STORAGE - * could read it during that window. + * Settings live in two SharedPreferences files: FaceclawSettings' own, and NativeScript's + * ApplicationSettings file (prefs.db), which still holds the pairing, onboarding and EvenHub + * localStorage keys. Both are exported, and each imported key is written to the file the app + * reads it from. An import merges: settings missing from the document are left alone. + * It writes through the process's live SharedPreferences, so a running app cannot flush stale + * values over it, then exits so the next launch starts from the imported settings. + * + * Security: the settings contain API tokens, so the manifest guards this receiver with + * android.permission.DUMP — a development permission the adb shell holds but ordinary apps + * cannot obtain without adb's help, keeping the trigger reachable from adb only. The transfer + * file lives in getExternalFilesDir(), which other apps cannot read on Android 11+ (and which + * the scripts delete as soon as the transfer completes); on the Android 7-10 devices minSdk + * still admits, apps holding READ_EXTERNAL_STORAGE could read it during that window. */ class FaceclawSettingsPortReceiver : BroadcastReceiver() { companion object { private const val TAG = "FaceclawSettingsPort" const val ACTION_EXPORT = "com.faceclaw.app.SETTINGS_EXPORT" const val ACTION_IMPORT = "com.faceclaw.app.SETTINGS_IMPORT" - private const val PREFS_FILE = "faceclaw_settings.xml" - private const val EXPORT_NAME = "faceclaw-settings-export.xml" - private const val IMPORT_NAME = "faceclaw-settings-import.xml" + private const val PLATFORM = "android" + private const val SETTINGS_PREFS = "faceclaw_settings" // FaceclawSettings + private const val NATIVESCRIPT_PREFS = "prefs.db" // NativeScript ApplicationSettings + private const val EXPORT_NAME = "faceclaw-settings-export.json" + private const val IMPORT_NAME = "faceclaw-settings-import.json" + private const val BACKUP_NAME = "faceclaw-settings-previous.json" + + private enum class StoredAs { STRING, BOOLEAN, NUMBER } + + /** + * Keys the app reads through NativeScript's ApplicationSettings rather than FaceclawSettings, + * and the getter it uses (device-addresses.ts, onboarding-state.ts, evenhub/session.ts; + * tests/settings-transfer.test.cjs keeps this list in step with them). prefs.db also holds + * settings abandoned when FaceclawSettings took over, so nothing else is read from it. + */ + private fun nativeScriptKey(key: String): StoredAs? = when { + key == "onboarding.complete" || key == "onboarding.previewOnly" -> StoredAs.BOOLEAN + key == "deviceIdentity.pairedAtMs" -> StoredAs.NUMBER + key.startsWith("deviceAddress.") || key.startsWith("deviceIdentity.") || key.startsWith("evenhub:") -> StoredAs.STRING + else -> null + } } override fun onReceive(context: Context, intent: Intent?) { @@ -57,11 +73,10 @@ class FaceclawSettingsPortReceiver : BroadcastReceiver() { if (ACTION_EXPORT == action) { resultData = exportSettings(context) } else if (ACTION_IMPORT == action) { - resultData = importSettings(context) - // Exit once the broadcast result has been delivered: this - // process may hold stale in-memory SharedPreferences that a - // later apply() would flush over the imported file, and the - // next launch must re-read from disk. + val result = importSettings(context) + resultData = result + if (!result.startsWith("imported:")) return + // Restart cleanly: running code may hold settings it read before the import. Handler(Looper.getMainLooper()).postDelayed({ Log.i(TAG, "Exiting after settings import") System.exit(0) @@ -69,13 +84,15 @@ class FaceclawSettingsPortReceiver : BroadcastReceiver() { } } catch (e: Exception) { Log.e(TAG, "Settings $action failed", e) - resultData = "error: $e" + resultData = "error: ${e.message ?: e}" } } - private fun prefsFile(context: Context): File { - return File(context.applicationInfo.dataDir, "shared_prefs/$PREFS_FILE") - } + private fun settingsPrefs(context: Context): SharedPreferences = + context.getSharedPreferences(SETTINGS_PREFS, Context.MODE_PRIVATE) + + private fun nativeScriptPrefs(context: Context): SharedPreferences = + context.getSharedPreferences(NATIVESCRIPT_PREFS, Context.MODE_PRIVATE) @Throws(IOException::class) private fun externalFile(context: Context, name: String): File { @@ -84,63 +101,111 @@ class FaceclawSettingsPortReceiver : BroadcastReceiver() { return File(dir, name) } - @Throws(IOException::class) - private fun exportSettings(context: Context): String { - val prefs = prefsFile(context) - if (!prefs.exists()) { - return "error: no settings file yet ($prefs)" + private fun appVersion(context: Context): String? = + runCatching { context.packageManager.getPackageInfo(context.packageName, 0).versionName }.getOrNull() + + /** Every setting, from the file the app reads it from, as SettingsTransfer values. */ + private fun currentSettings(context: Context): Map { + val values = linkedMapOf() + for ((key, value) in settingsPrefs(context).all) { + if (key == null || nativeScriptKey(key) != null) continue + val exported = exportable(value) + if (exported != null) values[key] = exported else Log.w(TAG, "Not exporting $key: unsupported type") } + for ((key, value) in nativeScriptPrefs(context).all) { + val storedAs = nativeScriptKey(key ?: continue) ?: continue + // NativeScript stores numbers as the raw bits of a double in a long. + val exported = if (storedAs == StoredAs.NUMBER && value is Long) { + Double.fromBits(value).takeIf { it.isFinite() }?.let { JsonNumber.of(it) } + } else { + exportable(value) + } + if (exported != null) values[key] = exported else Log.w(TAG, "Not exporting $key: unsupported value") + } + return values + } + + private fun exportable(value: Any?): Any? = when (value) { + is String, is Boolean -> value + is Int, is Long -> JsonNumber(value.toString()) + is Float -> value.toDouble().takeIf { it.isFinite() }?.let { JsonNumber.of(it) } + else -> null // string sets are unused + } + + private fun exportSettings(context: Context): String { + val document = SettingsTransfer.export(currentSettings(context), PLATFORM, appVersion(context)) val out = externalFile(context, EXPORT_NAME) - copy(prefs, out) + writeAtomically(out, document) return "exported: $out" } - @Throws(Exception::class) private fun importSettings(context: Context): String { val staged = externalFile(context, IMPORT_NAME) if (!staged.exists()) { return "error: nothing staged at $staged" } - validatePrefsXml(staged) - val prefs = prefsFile(context) - prefs.parentFile?.mkdirs() - if (prefs.exists()) { - copy(prefs, File(prefs.path + ".bak")) + val plan = try { + SettingsTransfer.planImport(staged.readText(), PLATFORM) + } finally { + staged.delete() // holds API tokens } - copy(staged, prefs) - staged.delete() - return "imported: $prefs (previous settings in $PREFS_FILE.bak)" - } - /** Reject files that are not a SharedPreferences document. */ - @Throws(Exception::class) - private fun validatePrefsXml(file: File) { - FileInputStream(file).use { input -> - val parser = Xml.newPullParser() - parser.setInput(input, null) - var event = parser.next() - while (event != XmlPullParser.START_TAG && event != XmlPullParser.END_DOCUMENT) { - event = parser.next() - } - if (event != XmlPullParser.START_TAG || "map" != parser.name) { - throw IOException("not a SharedPreferences document") - } - // Walk the rest so malformed XML is caught before it replaces - // the live settings file. - while (parser.next() != XmlPullParser.END_DOCUMENT) { } - } - } - - @Throws(IOException::class) - private fun copy(from: File, to: File) { - FileInputStream(from).use { input: InputStream -> - FileOutputStream(to).use { out: OutputStream -> - val buffer = ByteArray(8192) - var n: Int - while (input.read(buffer).also { n = it } > 0) { - out.write(buffer, 0, n) + // Convert everything before writing anything, so a bad value leaves settings untouched. + val settingsWrites = ArrayList<(SharedPreferences.Editor) -> Unit>() + val nativeScriptWrites = ArrayList<(SharedPreferences.Editor) -> Unit>() + for ((key, value) in plan.values) { + when (nativeScriptKey(key)) { + // FaceclawSettings only has string and boolean getters. + null -> if (value is Boolean) { + settingsWrites.add { e -> e.putBoolean(key, value) } + } else { + settingsWrites.add { e -> e.putString(key, text(value)) } + } + StoredAs.STRING -> nativeScriptWrites.add { e -> e.putString(key, text(value)) } + StoredAs.BOOLEAN -> { + val flag = value as? Boolean ?: (value as? String)?.toBooleanStrictOrNull() + ?: throw IllegalArgumentException("Setting $key must be a boolean") + nativeScriptWrites.add { e -> e.putBoolean(key, flag) } + } + StoredAs.NUMBER -> { + val number = text(value).toDoubleOrNull()?.takeIf { it.isFinite() } + ?: throw IllegalArgumentException("Setting $key must be a number") + nativeScriptWrites.add { e -> e.putLong(key, number.toRawBits()) } } } } + + val backup = File(context.filesDir, BACKUP_NAME) + writeAtomically(backup, SettingsTransfer.export(currentSettings(context), PLATFORM, appVersion(context))) + commit(settingsPrefs(context), settingsWrites) + commit(nativeScriptPrefs(context), nativeScriptWrites) + + val skipped = if (plan.skipped.isEmpty()) "" else + " (left out ${plan.skipped.size} ${plan.sourcePlatform ?: "other-platform"}-only settings)" + return "imported: ${plan.values.size} settings$skipped; previous settings saved in $backup" + } + + private fun text(value: Any): String = when (value) { + is JsonNumber -> value.text + else -> value.toString() + } + + private fun commit(prefs: SharedPreferences, writes: List<(SharedPreferences.Editor) -> Unit>) { + if (writes.isEmpty()) return + val editor = prefs.edit() + for (write in writes) write(editor) + if (!editor.commit()) throw IOException("Could not save settings") + } + + private fun writeAtomically(file: File, text: String) { + val atomic = AtomicFile(file) + val stream = atomic.startWrite() + try { + stream.write(text.toByteArray(Charsets.UTF_8)) + atomic.finishWrite(stream) + } catch (e: IOException) { + atomic.failWrite(stream) + throw e + } } } diff --git a/App_Resources/iOS/src/FaceclawConfigPort.h b/App_Resources/iOS/src/FaceclawConfigPort.h index 768f5cd5..fb48fec7 100644 --- a/App_Resources/iOS/src/FaceclawConfigPort.h +++ b/App_Resources/iOS/src/FaceclawConfigPort.h @@ -1,6 +1,17 @@ #import -/** Developer config transfer through the app container, before workers start. */ +NS_ASSUME_NONNULL_BEGIN +/** Converts between this phone's settings and the transfer document (Kotlin SettingsTransfer). */ +@protocol FaceclawConfigCodec +/** valuesJson is a JSON object of the settings; nil when they cannot be exported. */ +- (nullable NSString *)exportValuesJson:(NSString *)valuesJson platform:(NSString *)platform appVersion:(nullable NSString *)appVersion; +/** A JSON object: {"ok":true,"settings":{...},"skipped":[...],"sourcePlatform":...} or {"ok":false,"message":...}. */ +- (NSString *)importPlanDocument:(NSString *)document platform:(NSString *)platform; +@end + +/** Developer config transfer through the app container, before workers start (scripts/config-transfer.md). */ @interface FaceclawConfigPort : NSObject + (void)processPendingRequest; -+ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain; ++ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain + codec:(id)codec appVersion:(nullable NSString *)appVersion; @end +NS_ASSUME_NONNULL_END diff --git a/App_Resources/iOS/src/FaceclawConfigPort.m b/App_Resources/iOS/src/FaceclawConfigPort.m index 7da8efa2..15ada8bc 100644 --- a/App_Resources/iOS/src/FaceclawConfigPort.m +++ b/App_Resources/iOS/src/FaceclawConfigPort.m @@ -1,57 +1,112 @@ #import "FaceclawConfigPort.h" +#include +// The app links FaceclawKit; tests/ios-config-native.cjs builds this file for macOS without it +// and supplies its own codec. +#if __has_include() +#import +@interface FaceclawKitConfigCodec : NSObject +@end +@implementation FaceclawKitConfigCodec +- (NSString *)exportValuesJson:(NSString *)valuesJson platform:(NSString *)platform appVersion:(NSString *)appVersion { + return [FaceclawKitSettingsTransfer.shared exportValuesJson:valuesJson platform:platform appVersion:appVersion]; +} +- (NSString *)importPlanDocument:(NSString *)document platform:(NSString *)platform { + return [FaceclawKitSettingsTransfer.shared importPlanDocument:document platform:platform]; +} +@end +#define FACECLAW_CONFIG_CODEC [FaceclawKitConfigCodec new] +#endif + +static NSString *const kPlatform = @"ios"; +static NSString *const kChangeToken = @"ios.settings.changeToken"; + @implementation FaceclawConfigPort + (void)processPendingRequest { +#ifdef FACECLAW_CONFIG_CODEC NSString *library = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES).firstObject; [self processDirectory:[library stringByAppendingPathComponent:@"FaceclawConfigPort"] - defaults:NSUserDefaults.standardUserDefaults domain:NSBundle.mainBundle.bundleIdentifier]; + defaults:NSUserDefaults.standardUserDefaults domain:NSBundle.mainBundle.bundleIdentifier + codec:FACECLAW_CONFIG_CODEC + appVersion:NSBundle.mainBundle.infoDictionary[@"CFBundleShortVersionString"]]; +#endif } -+ (BOOL)validSettings:(id)settings { - if (![settings isKindOfClass:NSDictionary.class] || [settings count] > 4096) return NO; - for (id key in settings) { +// Typed locals, not messages to id: FaceclawKit declares other `count`/`length` properties. ++ (BOOL)validSettings:(id)candidate { + if (![candidate isKindOfClass:NSDictionary.class]) return NO; + NSDictionary *settings = candidate; + if (settings.count > 4096) return NO; + for (id candidateKey in settings) { + if (![candidateKey isKindOfClass:NSString.class]) return NO; + NSString *key = candidateKey; id value = settings[key]; - if (![key isKindOfClass:NSString.class] || ![key length] || [key length] > 512 || + if (!key.length || key.length > 512 || !([value isKindOfClass:NSString.class] || [value isKindOfClass:NSNumber.class])) return NO; } return YES; } -+ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain { +/** The app's settings: strings and finite numbers (booleans included) in its persistent domain. */ ++ (NSDictionary *)exportableSettings:(NSDictionary *)domain { + NSMutableDictionary *settings = [NSMutableDictionary new]; + for (NSString *key in domain) { + id value = domain[key]; + if ([value isKindOfClass:NSString.class] || + ([value isKindOfClass:NSNumber.class] && isfinite([value doubleValue]))) settings[key] = value; + } + [settings removeObjectForKey:kChangeToken]; + return settings; +} ++ (void)processDirectory:(NSString *)directory defaults:(NSUserDefaults *)defaults domain:(NSString *)domain + codec:(id)codec appVersion:(NSString *)appVersion { NSString *requestPath = [directory stringByAppendingPathComponent:@"request.json"]; NSData *data = [NSData dataWithContentsOfFile:requestPath]; if (!data) return; NSFileManager *fm = NSFileManager.defaultManager; // Consume once. A failed import must never be replayed at a later launch. [fm removeItemAtPath:requestPath error:nil]; - id request = data.length <= 2 * 1024 * 1024 ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil; + // A push embeds a document of up to 2 MiB as a JSON string, which escaping can enlarge. + id request = data.length <= 8 * 1024 * 1024 ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil; BOOL valid = [request isKindOfClass:NSDictionary.class]; NSString *identifier = valid && [request[@"id"] isKindOfClass:NSString.class] ? request[@"id"] : @""; NSMutableDictionary *reply = [@{@"id":identifier, @"ok":@NO, @"message":@"Invalid config request"} mutableCopy]; [defaults synchronize]; NSDictionary *before = [defaults persistentDomainForName:domain] ?: @{}; if (valid && [request[@"operation"] isEqual:@"pull"]) { - NSMutableDictionary *settings = [NSMutableDictionary new]; - for (NSString *key in before) { - id value = before[key]; - if ([value isKindOfClass:NSString.class] || [value isKindOfClass:NSNumber.class]) settings[key] = value; + NSDictionary *settings = [self exportableSettings:before]; + NSData *values = [NSJSONSerialization dataWithJSONObject:settings options:0 error:nil]; + NSString *document = values ? [codec exportValuesJson:[[NSString alloc] initWithData:values encoding:NSUTF8StringEncoding] + platform:kPlatform appVersion:appVersion] : nil; + if (document) { + reply[@"ok"] = @YES; reply[@"message"] = @"Config exported"; + reply[@"document"] = document; reply[@"count"] = @(settings.count); + } else reply[@"message"] = @"Could not encode settings"; + } else if (valid && [request[@"operation"] isEqual:@"push"] && [request[@"document"] isKindOfClass:NSString.class]) { + NSData *planData = [[codec importPlanDocument:request[@"document"] platform:kPlatform] dataUsingEncoding:NSUTF8StringEncoding]; + id plan = planData ? [NSJSONSerialization JSONObjectWithData:planData options:0 error:nil] : nil; + NSDictionary *settings = [plan isKindOfClass:NSDictionary.class] ? plan[@"settings"] : nil; + if (![plan isKindOfClass:NSDictionary.class] || ![plan[@"ok"] isEqual:@YES]) { + id message = [plan isKindOfClass:NSDictionary.class] ? plan[@"message"] : nil; + reply[@"message"] = [message isKindOfClass:NSString.class] ? message : @"Invalid config"; + } else if (![self validSettings:settings]) { + reply[@"message"] = @"Invalid config"; + } else { + NSError *error = nil; + NSData *backup = [NSPropertyListSerialization dataWithPropertyList:before format:NSPropertyListBinaryFormat_v1_0 options:0 error:&error]; + if (backup && [backup writeToFile:[directory stringByAppendingPathComponent:@"previous.plist"] options:NSDataWritingAtomic error:&error]) { + NSMutableDictionary *next = [before mutableCopy]; + [next addEntriesFromDictionary:settings]; + next[kChangeToken] = NSUUID.UUID.UUIDString; + [defaults setPersistentDomain:next forName:domain]; + if ([defaults synchronize]) { + reply[@"ok"] = @YES; reply[@"message"] = @"Config imported"; + reply[@"count"] = @(settings.count); + if ([plan[@"skipped"] isKindOfClass:NSArray.class]) reply[@"skipped"] = plan[@"skipped"]; + if ([plan[@"sourcePlatform"] isKindOfClass:NSString.class]) reply[@"sourcePlatform"] = plan[@"sourcePlatform"]; + } else { + [defaults setPersistentDomain:before forName:domain]; [defaults synchronize]; + reply[@"message"] = @"Could not persist config; restored previous settings"; + } + } else reply[@"message"] = @"Could not back up existing settings; import skipped"; } - [settings removeObjectForKey:@"ios.settings.changeToken"]; - reply[@"config"] = @{@"schema":@1, @"settings":settings}; reply[@"ok"] = @YES; - reply[@"message"] = @"Config exported"; - } else if (valid && [request[@"operation"] isEqual:@"push"] && [self validSettings:request[@"settings"]]) { - NSError *error = nil; - NSData *backup = [NSPropertyListSerialization dataWithPropertyList:before format:NSPropertyListBinaryFormat_v1_0 options:0 error:&error]; - if (backup && [backup writeToFile:[directory stringByAppendingPathComponent:@"previous.plist"] options:NSDataWritingAtomic error:&error]) { - NSMutableDictionary *next = [before mutableCopy]; - [next addEntriesFromDictionary:request[@"settings"]]; - next[@"ios.settings.changeToken"] = NSUUID.UUID.UUIDString; - [defaults setPersistentDomain:next forName:domain]; - if ([defaults synchronize]) { - reply[@"ok"] = @YES; reply[@"message"] = @"Config imported"; - reply[@"count"] = @([request[@"settings"] count]); - } else { - [defaults setPersistentDomain:before forName:domain]; [defaults synchronize]; - reply[@"message"] = @"Could not persist config; restored previous settings"; - } - } else reply[@"message"] = @"Could not back up existing settings; import skipped"; } NSData *response = [NSJSONSerialization dataWithJSONObject:reply options:NSJSONWritingPrettyPrinted error:nil]; [response writeToFile:[directory stringByAppendingPathComponent:@"response.json"] options:NSDataWritingAtomic error:nil]; diff --git a/README.md b/README.md index 355a206e..cef53cca 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,8 @@ walk you through pairing with the glasses and installing custom firmware. For the NativeScript iOS port, see [iOS development](notes/ios-development.md). Use `scripts/pull_config_ios.sh` and `scripts/push_config_ios.sh` to transfer iPhone -settings; see [iOS config transfer](scripts/ios-config.md) for options and Android XML support. +settings. Android and iOS share one JSON config format, so a config pulled from either +platform can be pushed to the other; see [config transfer](scripts/config-transfer.md). The instructions below build the Android app. If you want to customize faceclaw, the best way to do it is to download the @@ -54,7 +55,7 @@ port into your computer, authorize access on the phone, and run Note that if you have installed a signed release build, you will have to uninstall it before installing a customized version. Use scripts/pull_config.sh to export a copy of your configuration first, and scripts/push_config.sh to -import it into the new version. +import it into the new version (see [config transfer](scripts/config-transfer.md)). ## Features diff --git a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/SettingsDocument.kt b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/SettingsDocument.kt deleted file mode 100644 index ed240a09..00000000 --- a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/SettingsDocument.kt +++ /dev/null @@ -1,70 +0,0 @@ -package com.faceclaw.app - -/** Shared on-disk settings format. Native adapters own locking and atomic IO. */ -class SettingsDocument private constructor(private val settings: Map) { - fun containsString(key: String, value: String): Boolean = settings[key] == structuredValue(key, value) - fun getString(key: String, fallback: String): String = when (val value = settings[key]) { - is String -> value - is Map<*, *>, is List<*> -> Json.write(value) - else -> fallback - } - fun getBoolean(key: String, fallback: Boolean): Boolean = settings[key] as? Boolean ?: fallback - fun getNumber(key: String, fallback: Double): Double = (settings[key] as? JsonNumber)?.text?.toDoubleOrNull() ?: fallback - fun replacingNumber(key: String, value: Double): SettingsDocument = - SettingsDocument(settings + (key to JsonNumber(value.toString()))) - fun removing(key: String): SettingsDocument = SettingsDocument(settings - key) - fun replacingString(key: String, value: String): SettingsDocument = - SettingsDocument(settings + (key to structuredValue(key, value))) - fun replacingBoolean(key: String, value: Boolean): SettingsDocument = SettingsDocument(settings + (key to value)) - fun merged(other: SettingsDocument): SettingsDocument = SettingsDocument(settings + other.settings) - fun encode(): String = Json.write(mapOf("schema" to JsonNumber(CURRENT_SCHEMA.toString()), "settings" to settings), pretty = true) + "\n" - - // A mutation/merge must never commit a document that the next launch rejects. - fun encodeForStorage(): String? { - val text = encode() - return if (runCatching { decode(text) }.isSuccess) text else null - } - - companion object { - const val CURRENT_SCHEMA = 2 - // Explicit keys avoid interpreting arbitrary text (prompts, passwords, drafts) as JSON. - private val structuredKeys = setOf( - "terminal.connections", "teleprompter.recents", "launcher.folders", "notifications.sources", - "files.bookmarks", "music.apps", "microphones.array-config", "display.uiFont2", "terminal.font", - "navigate.savedDestinations", "navigate.recentDestinations", "evenhub.installedApps.v1", "timers.state", "assistant.conversations" - ) - private fun structuredValue(key: String, value: Any?): Any? { - if ((key !in structuredKeys && !key.startsWith("ios.ble.peripheral.")) || value !is String) return value - // Preserve empty/invalid old values: callers already provide their own fallback. - val parsed = runCatching { Json.parse(value) }.getOrNull() - return if (parsed is Map<*, *> || parsed is List<*>) parsed else value - } - // Each entry migrates version N to N+1. Never rewrite unknown future schemas. - private val migrations: Map) -> Map> = mapOf( - 1 to { old -> old.mapValues { (key, value) -> structuredValue(key, value) } } - ) - internal fun decode(text: String): SettingsDocument { - require(text.encodeToByteArray().size <= 2 * 1024 * 1024) { "Config exceeds 2 MiB" } - val root = Json.parse(text) as? Map<*, *> ?: error("Expected config object") - var schema = (root["schema"] as? JsonNumber)?.text?.toIntOrNull() ?: error("Missing schema") - require(schema in 1..CURRENT_SCHEMA) { "Unsupported settings schema" } - val raw = root["settings"] as? Map<*, *> ?: error("Missing settings") - require(raw.size <= 4096) - var values: Map = raw.entries.associate { (key, value) -> - require(key is String && key.isNotEmpty() && key.length <= 512) - require(value != null) { "Null setting" } - key to value - } - while (schema < CURRENT_SCHEMA) values = migrations.getValue(schema++)(values) - return SettingsDocument(values) - } - } -} - -/** Nullable decode keeps invalid files recoverable across Objective-C/JVM bridges. */ -class SettingsCodec { - fun needsMigration(text: String): Boolean = runCatching { - ((Json.parse(text) as Map<*, *>)["schema"] as JsonNumber).text != SettingsDocument.CURRENT_SCHEMA.toString() - }.getOrDefault(false) - fun decode(text: String): SettingsDocument? = runCatching { SettingsDocument.decode(text) }.getOrNull() -} diff --git a/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/settings/SettingsTransfer.kt b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/settings/SettingsTransfer.kt new file mode 100644 index 00000000..b612797a --- /dev/null +++ b/native/kotlin/shared/src/commonMain/kotlin/com/faceclaw/app/settings/SettingsTransfer.kt @@ -0,0 +1,179 @@ +package com.faceclaw.app + +/** + * What an import will store: the values to merge into the phone's settings, plus the + * platform-local keys left out because the document was exported on another platform. + */ +class SettingsImportPlan internal constructor( + /** String, Boolean or JsonNumber. Objects/arrays in the document arrive as compact JSON strings. */ + val values: Map, + val skipped: List, + /** The platform that exported the document, or null when it doesn't say. */ + val sourcePlatform: String?, +) + +/** + * The settings export/import document shared by Android and iOS (scripts/config-transfer.md). + * Only the transfer format is shared: each platform keeps storing settings natively + * (SharedPreferences / NSUserDefaults), and its config port converts with this codec. + * + * ``` + * { + * "schema": 2, + * "platform": "android", // the exporting platform + * "appVersion": "0.8.3", // informational + * "settings": { ... }, // imported on any platform + * "platformSettings": { ... } // imported only when "platform" matches the importer + * } + * ``` + * + * Values are strings, booleans and numbers, as stored. A string holding a JSON object or array + * is written as that object/array when doing so is lossless (re-serializing it reproduces the + * stored text exactly), so structured settings are readable and editable; any object/array value + * is stored back as its compact JSON text. No setting is stored as a native object, so this never + * changes a setting's type. + * + * Schema 1 (flat `settings`, strings only; written by older iOS builds and by the scripts' + * conversion of Android shared-preferences XML) is still accepted: its keys are classified with + * [isPlatformLocal] at import time instead. + */ +object SettingsTransfer { + private const val SCHEMA = 2 + private const val MAX_BYTES = 2 * 1024 * 1024 + private const val MAX_ENTRIES = 4096 + private const val MAX_KEY_CHARS = 512 + + /** Bookkeeping that is never exported or imported. */ + private val internalKeys = setOf("ios.settings.changeToken") + + // Platform-local: values that would be wrong, or would clobber something correct, on another + // phone. Everything else is portable, including settings only one platform currently uses, + // so that they survive an Android -> iOS -> Android round trip. Enum values a platform doesn't + // offer need no entry here: each setting falls back to its default when read. + private val platformLocalPrefixes = listOf( + "ios.", "android.", // platform internals, e.g. CoreBluetooth peripheral identifiers + "deviceAddress.", "deviceIdentity.", // glasses and ring paired with this phone (bonds are per phone) + "onboarding.", // whether this phone has been set up: pairing, permissions, firmware + ) + private val platformLocalKeys = setOf( + "notifications.sources", // Android package names vs iOS bundle identifiers + "music.apps", "music.lastApp", // Android media-browser packages + "files.bookmarks", "teleprompter.recents", // paths in this phone's storage + "evenhub.installedApps.v1", // packages unpacked into this phone's storage + "integrations.evenhub.terminalId", "integrations.evenhub.openUdid", // per-phone EvenHub device IDs + ) + + fun isPlatformLocal(key: String): Boolean = + key in platformLocalKeys || platformLocalPrefixes.any { key.startsWith(it) } + + /** + * Encode a phone's settings as a document. [values] holds String, Boolean and numeric + * (JsonNumber, Int, Long, Float, Double) values; other types are rejected. + */ + fun export(values: Map, platform: String, appVersion: String? = null): String { + val settings = linkedMapOf() + val local = linkedMapOf() + for (key in values.keys.sorted()) { + if (key in internalKeys) continue + val value = values[key] + requireKey(key) + val encoded = when (value) { + is String -> structured(value) ?: value + is Boolean, is JsonNumber -> value + is Int, is Long -> JsonNumber(value.toString()) + is Float -> JsonNumber.of(value.toDouble()) + is Double -> JsonNumber.of(value) + else -> throw IllegalArgumentException("Unsupported value type for setting $key") + } + (if (isPlatformLocal(key)) local else settings)[key] = encoded + } + require(settings.size + local.size <= MAX_ENTRIES) { "Too many settings" } + val document = linkedMapOf("schema" to JsonNumber.of(SCHEMA), "platform" to platform) + if (!appVersion.isNullOrEmpty()) document["appVersion"] = appVersion + document["settings"] = settings + document["platformSettings"] = local + val text = Json.write(document, pretty = true) + "\n" + require(text.encodeToByteArray().size <= MAX_BYTES) { "Config exceeds 2 MiB" } + return text + } + + /** Validate a document and work out what importing it on [platform] stores. */ + fun planImport(text: String, platform: String): SettingsImportPlan { + require(text.encodeToByteArray().size <= MAX_BYTES) { "Config exceeds 2 MiB" } + val root = runCatching { Json.parse(text) }.getOrElse { throw IllegalArgumentException("Config is not valid JSON: ${it.message}") } + .asObject() ?: throw IllegalArgumentException("Expected a Faceclaw config object") + val schema = (root["schema"] as? JsonNumber)?.text + val source = root["platform"]?.let { it as? String ?: throw IllegalArgumentException("\"platform\" must be a string") } + val portable = section(root, "settings") ?: throw IllegalArgumentException("Missing \"settings\" object") + val values = linkedMapOf() + val skipped = ArrayList() + val seen = HashSet() + fun add(key: String, value: Any?, include: Boolean) { + requireKey(key) + require(seen.add(key)) { "Setting $key appears more than once" } + require(seen.size <= MAX_ENTRIES) { "Too many settings" } + val stored = storedValue(key, value) + if (key in internalKeys) return + if (include) values[key] = stored else skipped.add(key) + } + val from = when (schema) { + "1" -> { + // Old builds exported iOS settings only; the scripts tag converted Android XML. + val from = source ?: "ios" + for ((key, value) in portable) add(key, value, from == platform || !isPlatformLocal(key)) + from + } + "2" -> { + for ((key, value) in portable) add(key, value, true) + section(root, "platformSettings")?.forEach { (key, value) -> add(key, value, source == platform) } + source + } + else -> throw IllegalArgumentException(if (schema == null) "Missing \"schema\"" else "Unsupported config schema $schema") + } + return SettingsImportPlan(values, skipped, from) + } + + /** + * Objective-C bridge (FaceclawConfigPort.m, `exportValuesJson:platform:appVersion:`): [json] + * is a JSON object of the phone's settings. Returns the document, or null when the values + * can't be exported. + */ + fun exportValues(json: String, platform: String, appVersion: String?): String? = runCatching { + export(Json.parseObject(json), platform, appVersion) + }.onFailure { PlatformLog.w("SettingsTransfer", "export failed: ${it.message}") }.getOrNull() + + /** + * Objective-C bridge (`importPlanDocument:platform:`): never throws. Returns a JSON object, either + * `{"ok":true,"settings":{...},"skipped":[...],"sourcePlatform":...}` or `{"ok":false,"message":...}`. + */ + fun importPlan(document: String, platform: String): String = try { + val plan = planImport(document, platform) + Json.write(linkedMapOf("ok" to true, "settings" to plan.values, "skipped" to plan.skipped, "sourcePlatform" to plan.sourcePlatform)) + } catch (error: Exception) { + Json.write(mapOf("ok" to false, "message" to (error.message ?: "Invalid config"))) + } + + private fun section(root: Map, name: String): Map? { + val value = root[name] ?: return null + return value.asObject() ?: throw IllegalArgumentException("\"$name\" must be an object") + } + + private fun requireKey(key: String) { + require(key.isNotEmpty() && key.length <= MAX_KEY_CHARS) { "Invalid setting name" } + } + + private fun storedValue(key: String, value: Any?): Any = when (value) { + is String, is Boolean, is JsonNumber -> value + is Map<*, *>, is List<*> -> Json.write(value) + null -> throw IllegalArgumentException("Setting $key is null; supply an empty value to clear it") + else -> throw IllegalArgumentException("Unsupported value for setting $key") + } + + /** The object/array a string holds, when writing it back reproduces the string exactly. */ + private fun structured(text: String): Any? { + if (text.isEmpty() || (text[0] != '{' && text[0] != '[')) return null + val parsed = runCatching { Json.parse(text) }.getOrNull() + if (parsed !is Map<*, *> && parsed !is List<*>) return null + return parsed.takeIf { Json.write(it) == text } + } +} diff --git a/scripts/config-transfer.md b/scripts/config-transfer.md new file mode 100644 index 00000000..1c105633 --- /dev/null +++ b/scripts/config-transfer.md @@ -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). diff --git a/scripts/config_document.py b/scripts/config_document.py new file mode 100644 index 00000000..add22c1e --- /dev/null +++ b/scripts/config_document.py @@ -0,0 +1,132 @@ +#!/usr/bin/env python3 +"""Read a Faceclaw config file for push_config.sh / push_config_ios.sh. + +The phone-side importer (Kotlin SettingsTransfer) does the authoritative validation and +platform filtering; this catches unusable files before the scripts touch a device, and +converts legacy Android shared-preferences XML (what pull_config.sh wrote before configs +were JSON) into a schema-1 document tagged as Android. See scripts/config-transfer.md. + + config_document.py INPUT # prints the document to push +""" +import json +import math +from pathlib import Path +import sys +import xml.etree.ElementTree as ET + +LIMIT = 2 * 1024 * 1024 + + +def _check_value(key, value): + if not isinstance(key, str) or not key or len(key) > 512: + raise ValueError('Invalid setting name') + if value is None: + raise ValueError(f'Setting {key} is null; supply an empty value to clear it') + if isinstance(value, float) and not math.isfinite(value): + raise ValueError(f'Setting {key} is not a finite number') + if not isinstance(value, (str, bool, int, float, dict, list)): + raise ValueError(f'Unsupported value for setting {key}') + + +def _no_constants(name): + raise ValueError(f'{name} is not valid JSON') + + +def check_document(text): + """Validate a JSON document's shape; returns (schema, platform, setting count).""" + try: + config = json.loads(text, parse_constant=_no_constants, + object_pairs_hook=_reject_duplicate_keys) + except json.JSONDecodeError as error: + raise ValueError(f'Config is not valid JSON: {error}') from None + if not isinstance(config, dict) or type(config.get('schema')) is not int or config['schema'] not in (1, 2): + raise ValueError('Expected a Faceclaw config with "schema": 1 or 2') + platform = config.get('platform') + if platform is not None and not isinstance(platform, str): + raise ValueError('"platform" must be a string') + count = 0 + for section in ('settings', 'platformSettings'): + values = config.get(section, {} if section == 'platformSettings' else None) + if not isinstance(values, dict): + raise ValueError(f'"{section}" must be an object') + for key, value in values.items(): + _check_value(key, value) + count += len(values) + if count > 4096: + raise ValueError('Too many settings') + return config['schema'], platform, count + + +def _reject_duplicate_keys(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError(f'Setting {key} appears more than once') + result[key] = value + return result + + +def convert_android_xml(data): + """Android shared-preferences XML -> schema-1 document text (the phone classifies the keys).""" + if b'') + settings = {} + for item in root: + key = item.get('name') + if key in settings: + raise ValueError('Duplicate setting name') + if item.tag == 'string': + value = item.text or '' + elif item.tag == 'boolean' and item.get('value') in ('true', 'false'): + value = item.get('value') == 'true' + elif item.tag in ('int', 'long', 'float'): + try: + value = float(item.get('value', '')) if item.tag == 'float' else int(item.get('value', '')) + except ValueError: + raise ValueError('Invalid numeric preference value') from None + else: + raise ValueError('Unsupported Android preference type') + if len(item): + raise ValueError('Nested preference content is not supported') + _check_value(key, value) + settings[key] = value + return json.dumps({'schema': 1, 'platform': 'android', 'settings': settings}, + indent=2, ensure_ascii=False, allow_nan=False) + '\n' + + +def read_document(path): + """The document to push for a JSON config or legacy Android XML file, validated.""" + data = Path(path).read_bytes() + if len(data) > LIMIT: + raise ValueError('Config exceeds 2 MiB') + if data.lstrip().startswith(b'<'): + text = convert_android_xml(data) + else: + try: + text = data.decode('utf-8-sig') + except UnicodeDecodeError: + raise ValueError('Config is not UTF-8') from None + check_document(text) + if len(text.encode()) > LIMIT: + raise ValueError('Config exceeds 2 MiB') + return text + + +def main(): + if len(sys.argv) != 2: + print(__doc__.strip(), file=sys.stderr) + return 2 + try: + text = read_document(sys.argv[1]) + except (OSError, ValueError, ET.ParseError) as error: + print(f'Error: {error}', file=sys.stderr) + return 1 + sys.stdout.write(text) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/scripts/ios-config.md b/scripts/ios-config.md deleted file mode 100644 index e53b6ac7..00000000 --- a/scripts/ios-config.md +++ /dev/null @@ -1,53 +0,0 @@ -# iOS config transfer - -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 # faceclaw_settings.ios.json -scripts/push_config_ios.sh # import the edited file -scripts/pull_config_ios.sh -f /tmp/settings.json --device IPHONE_UDID -scripts/push_config_ios.sh faceclaw_settings.xml # 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). - -The JSON format preserves setting types: - -```json -{ - "schema": 1, - "settings": { - "terminal.connections": "[]", - "terminal.autoReconnect": true - } -} -``` - -Pull accepts an `.xml` output filename to write Android shared-preferences XML. -Push detects JSON or XML by content and supports strings, booleans and numbers. -Malformed input, unsupported values and files over 2 MiB fail before restarting -the app. Push **merges supplied keys**, preserving omitted settings (including -phone-specific pairing). To clear a value, supply its empty/default value. - -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. Each successful push first saves the previous -preferences to `Library/FaceclawConfigPort/previous.plist`. Replies are checked -against the request ID, so a stale export cannot appear to confirm an import. - -Exports may contain API keys and Terminal tokens. Scripts do not print values, -write local exports with mode 600, and remove their private temporary directory -on exit. Default export filenames are gitignored. 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). diff --git a/scripts/ios_config.py b/scripts/ios_config.py index b51f8725..a9f8020c 100644 --- a/scripts/ios_config.py +++ b/scripts/ios_config.py @@ -2,7 +2,6 @@ """Transfer Faceclaw preferences using Xcode's supported app-container APIs.""" import argparse import json -import math import os from pathlib import Path import subprocess @@ -12,72 +11,13 @@ import time import uuid import xml.etree.ElementTree as ET +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from config_document import read_document # noqa: E402 + BUNDLE = os.environ.get('IOS_BUNDLE_ID') or 'com.faceclaw.app' REMOTE = 'Library/FaceclawConfigPort' -LIMIT = 2 * 1024 * 1024 - - -def validate(settings): - if not isinstance(settings, dict) or len(settings) > 4096: - raise ValueError('Expected a settings object with at most 4096 entries') - for key, value in settings.items(): - if not isinstance(key, str) or not key or len(key) > 512: - raise ValueError('Invalid setting name') - if type(value) not in (str, bool, int, float) or isinstance(value, float) and not math.isfinite(value): - raise ValueError('Settings must contain only strings, booleans and finite numbers') - return settings - - -def read_config(path): - data = Path(path).read_bytes() - if len(data) > LIMIT: - raise ValueError('Config exceeds 2 MiB') - if data.lstrip().startswith(b'<'): - if b'') - settings = {} - for item in root: - key = item.get('name') - if key in settings: - raise ValueError('Duplicate setting name') - if item.tag == 'string': - value = item.text or '' - elif item.tag == 'boolean' and item.get('value') in ('true', 'false'): - value = item.get('value') == 'true' - elif item.tag in ('int', 'long', 'float'): - try: - value = float(item.get('value', '')) if item.tag == 'float' else int(item.get('value', '')) - except ValueError: - raise ValueError('Invalid numeric preference value') from None - else: - raise ValueError('Unsupported Android preference type') - if len(item): - raise ValueError('Nested preference content is not supported') - settings[key] = value - else: - config = json.loads(data) - if not isinstance(config, dict) or config.get('schema') != 1: - raise ValueError('Expected Faceclaw config with schema: 1 and a settings object') - settings = config.get('settings') - return validate(settings) - - -def encode_config(settings, xml=False): - validate(settings) - if not xml: - return (json.dumps({'schema': 1, 'settings': settings}, indent=2, ensure_ascii=False, allow_nan=False) + '\n').encode() - root = ET.Element('map') - for key, value in sorted(settings.items()): - if isinstance(value, str): - ET.SubElement(root, 'string', name=key).text = value - else: - kind = 'boolean' if isinstance(value, bool) else 'long' if isinstance(value, int) else 'float' - ET.SubElement(root, kind, name=key, value=str(value).lower()) - ET.indent(root) - return ET.tostring(root, encoding='utf-8', xml_declaration=True) + b'\n' +# The app reads requests of up to 8 MiB: a 2 MiB document embedded as an escaped JSON string. +REQUEST_LIMIT = 8 * 1024 * 1024 def run(args, tolerate=False): @@ -108,7 +48,7 @@ def atomic_write(path, data): def transfer(args): # Parse and validate before touching the device or restarting its app. - settings = read_config(args.file) if args.operation == 'push' else None + document = read_document(args.file) if args.operation == 'push' else None with tempfile.TemporaryDirectory(prefix='faceclaw-config-') as work: work = Path(work) device = args.device or os.environ.get('IOS_DEVICE') @@ -126,11 +66,11 @@ def transfer(args): device = available[0]['identifier'] identifier = str(uuid.uuid4()) payload = {'id': identifier, 'operation': args.operation} - if settings is not None: - payload['settings'] = settings + if document is not None: + payload['document'] = document encoded = json.dumps(payload, ensure_ascii=False, allow_nan=False).encode() - if len(encoded) > LIMIT: - raise ValueError('Config request exceeds 2 MiB') + if len(encoded) > REQUEST_LIMIT: + raise ValueError('Config request exceeds 8 MiB') stage = work / 'FaceclawConfigPort' stage.mkdir(mode=0o700) atomic_write(stage / 'request.json', encoded) @@ -164,18 +104,25 @@ def transfer(args): if response is None: raise RuntimeError('No matching config response. Unlock the phone and install a build with config-port support, then retry.') if not response.get('ok'): - raise RuntimeError(response.get('message', 'Config transfer failed')) + message = response.get('message', 'Config transfer failed') + if message == 'Invalid config request': + message += ' (does the installed build predate JSON config documents?)' + raise RuntimeError(message) if args.operation == 'pull': - settings = response['config']['settings'] - atomic_write(args.file, encode_config(settings, Path(args.file).suffix.lower() == '.xml')) - print(f'Pulled {len(settings)} settings to {args.file} (mode 600). App restarted.') + if not isinstance(response.get('document'), str): + raise RuntimeError('The installed build predates JSON config documents; update it and retry.') + atomic_write(args.file, response['document'].encode()) + print(f'Pulled {response.get("count", "?")} settings to {args.file} (mode 600). App restarted.') else: - print(f'Pushed {response["count"]} settings; app restarted. Unspecified settings preserved; previous preferences backed up in {REMOTE}/previous.plist.') + skipped = response.get('skipped') or [] + note = f' Left out {len(skipped)} {response.get("sourcePlatform") or "other-platform"}-only settings.' if skipped else '' + print(f'Pushed {response["count"]} settings; app restarted.{note} Unspecified settings preserved; ' + f'previous preferences backed up in {REMOTE}/previous.plist.') def main(): os.umask(0o077) - parser = argparse.ArgumentParser(description='Pull/push iOS Faceclaw config; restarts the app. Requires Xcode and an unlocked development device. Push merges supplied keys; accepts Android XML or Faceclaw JSON.') + parser = argparse.ArgumentParser(description='Pull/push iOS Faceclaw config; restarts the app. Requires Xcode and an unlocked development device. Push merges supplied keys; accepts Faceclaw JSON from either platform, or legacy Android XML.') parser.add_argument('operation', choices=['pull', 'push']) parser.add_argument('path', nargs='?') parser.add_argument('-f', '--file') @@ -185,6 +132,8 @@ def main(): if args.path and args.file: parser.error('Specify one file, either positional or with -f') args.file = args.file or args.path or 'faceclaw_settings.ios.json' + if args.operation == 'pull' and Path(args.file).suffix.lower() == '.xml': + parser.error('Configs are pulled as JSON; choose a .json filename') try: transfer(args) except (OSError, ValueError, RuntimeError, ET.ParseError) as error: diff --git a/scripts/pull_config.sh b/scripts/pull_config.sh index ca6f331b..a84aa051 100755 --- a/scripts/pull_config.sh +++ b/scripts/pull_config.sh @@ -1,11 +1,11 @@ #!/bin/bash -# Pull faceclaw's shared preferences off the attached device. +# Export faceclaw's settings from the attached Android device as a JSON config +# document (the same format as pull_config_ios.sh; see config-transfer.md). # Usage: pull_config.sh [output-file] [-f output-file] [adb-options...] # -# Uses run-as on debuggable (dev) builds. On release builds, where run-as is -# refused, falls back to the FaceclawSettingsPortReceiver broadcast, which -# copies the settings file into the app's external files dir for adb to pull -# (and which only the adb shell can trigger; see the receiver's javadoc). +# The app's FaceclawSettingsPortReceiver writes the document into its external +# files dir for adb to pull. Only the adb shell can trigger it (see the +# receiver's javadoc), and it works on release builds, where run-as is refused. set -euo pipefail source "$(cd "$(dirname "$0")" && pwd)/adbutil.sh" @@ -14,10 +14,12 @@ usage() { cat < "$OUT" - echo "Pulled $PREFS to $OUT" -else - echo "Release build installed; using settings-port broadcast..." - RESULT="$(adb shell am broadcast -n "$PACKAGE/.FaceclawSettingsPortReceiver" \ - -a com.faceclaw.app.SETTINGS_EXPORT)" - if ! printf '%s' "$RESULT" | grep -q 'data="exported:'; then - printf '%s\n' "$RESULT" >&2 - echo "Error: export broadcast did not report success (old app version?)" >&2 +case "$OUT" in + *.xml|*.XML) + echo "Error: configs are exported as JSON; choose a .json filename" >&2 exit 1 - fi - adb pull "$EXPORT_REMOTE" "$OUT" >/dev/null - # The export contains API tokens; don't leave it sitting on shared storage. - adb shell rm "$EXPORT_REMOTE" - echo "Pulled $PREFS to $OUT (via settings-port export)" + ;; +esac + +adb_preflight "$PACKAGE" >/dev/null + +export_broadcast() { + adb shell am broadcast --include-stopped-packages \ + -n "$PACKAGE/.FaceclawSettingsPortReceiver" -a com.faceclaw.app.SETTINGS_EXPORT +} +RESULT="$(export_broadcast)" +if ! printf '%s' "$RESULT" | grep -q 'data='; then + # No reply at all: the broadcast reached a process that was exiting (the + # app exits just after an import). Try once more in a fresh one. + adb shell sleep 1 + RESULT="$(export_broadcast)" fi +if ! printf '%s' "$RESULT" | grep -q 'data="exported: .*\.json"'; then + printf '%s\n' "$RESULT" >&2 + echo "Error: export broadcast did not report a JSON export (app predates JSON configs?)" >&2 + exit 1 +fi + +# The export contains API tokens: keep it private locally, and don't leave it +# sitting on shared storage. +umask 077 +TMP="$(mktemp "$OUT.XXXXXX")" +trap 'rm -f "$TMP"' EXIT +if ! OUTPUT="$(adb pull "$EXPORT_REMOTE" "$TMP" 2>&1)"; then + adb shell rm -f "$EXPORT_REMOTE" + printf '%s\n' "$OUTPUT" >&2 + echo "Error: could not pull $EXPORT_REMOTE" >&2 + exit 1 +fi +adb shell rm -f "$EXPORT_REMOTE" +mv "$TMP" "$OUT" +trap - EXIT +echo "Pulled settings to $OUT (mode 600)" diff --git a/scripts/push_config.sh b/scripts/push_config.sh index 9c11371a..184af735 100755 --- a/scripts/push_config.sh +++ b/scripts/push_config.sh @@ -1,26 +1,29 @@ #!/bin/bash -# Push a shared-preferences file to faceclaw on the attached device. +# Import a JSON config document (from Android or iOS; see config-transfer.md) +# into faceclaw on the attached Android device. # Usage: push_config.sh [input-file] [-f input-file] [adb-options...] -# Validates the XML, force-stops the app (so a running instance doesn't -# overwrite the pushed file from its in-memory prefs), then installs it. # -# Uses run-as on debuggable (dev) builds. On release builds, where run-as is -# refused, falls back to the FaceclawSettingsPortReceiver broadcast: the file -# is staged in the app's external files dir and the receiver (adb-only; see -# its javadoc) validates and installs it, then exits so the next launch -# re-reads settings from disk. +# The import merges: settings the file doesn't mention are left alone, and +# settings that only make sense on the platform that exported them are left +# out when the file came from iOS. Legacy shared-preferences XML (what this +# script used to take) is converted first. The file is staged in the app's +# external files dir, and FaceclawSettingsPortReceiver (adb-only; see its +# javadoc) validates it, saves the previous settings, applies it, and exits +# the app so its next launch starts from the imported settings. set -euo pipefail -source "$(cd "$(dirname "$0")" && pwd)/adbutil.sh" +SCRIPTS="$(cd "$(dirname "$0")" && pwd)" +source "$SCRIPTS/adbutil.sh" usage() { cat <&2 - exit 1 -fi - -if command -v xmllint >/dev/null 2>&1; then - xmllint --noout "$IN" -elif command -v python3 >/dev/null 2>&1; then - python3 -c 'import sys, xml.etree.ElementTree as ET; ET.parse(sys.argv[1])' "$IN" -else - echo "Error: need xmllint or python3 to validate XML" >&2 - exit 1 -fi - -MODE="$(adb_preflight "$PACKAGE")" - -adb shell am force-stop "$PACKAGE" - -if [ "$MODE" = debug ]; then - adb push "$IN" "$STAGE" - adb shell run-as "$PACKAGE" cp "$STAGE" "$PREFS" - adb shell rm "$STAGE" - echo "Pushed $IN to $PREFS (app was force-stopped; relaunch it to pick up the new settings)" -else - echo "Release build installed; using settings-port broadcast..." - adb push "$IN" "$IMPORT_REMOTE" >/dev/null - RESULT="$(adb shell am broadcast -n "$PACKAGE/.FaceclawSettingsPortReceiver" \ - -a com.faceclaw.app.SETTINGS_IMPORT)" - if ! printf '%s' "$RESULT" | grep -q 'data="imported:'; then - printf '%s\n' "$RESULT" >&2 - adb shell rm -f "$IMPORT_REMOTE" - echo "Error: import broadcast did not report success (old app version?)" >&2 - exit 1 + if [ -z "$ADBUTIL_FILE" ] && [ -f faceclaw_settings.xml ]; then + echo " (older pull_config.sh wrote faceclaw_settings.xml; pass it explicitly)" >&2 fi - echo "Pushed $IN to $PREFS via settings-port import (previous settings kept as $PREFS.bak)" + exit 1 fi +if ! command -v python3 >/dev/null 2>&1; then + echo "Error: python3 is needed to check the config before pushing it" >&2 + exit 1 +fi + +umask 077 +STAGE="$(mktemp "${TMPDIR:-/tmp}/faceclaw-config.XXXXXX")" +trap 'rm -f "$STAGE"' EXIT +# Validates (and converts legacy XML) before anything touches the device. +python3 "$SCRIPTS/config_document.py" "$IN" > "$STAGE" + +adb_preflight "$PACKAGE" >/dev/null + +if ! OUTPUT="$(adb push "$STAGE" "$IMPORT_REMOTE" 2>&1)"; then + printf '%s\n' "$OUTPUT" >&2 + echo "Error: could not stage the config on the device" >&2 + exit 1 +fi +RESULT="$(adb shell am broadcast --include-stopped-packages \ + -n "$PACKAGE/.FaceclawSettingsPortReceiver" -a com.faceclaw.app.SETTINGS_IMPORT)" +# The receiver deletes the staged file once read; this covers older builds. +adb shell rm -f "$IMPORT_REMOTE" +if ! printf '%s' "$RESULT" | grep -q 'data="imported:'; then + # An older build looks for a staged .xml file and reports "nothing staged". + if printf '%s' "$RESULT" | grep -q 'data="error:' && ! printf '%s' "$RESULT" | grep -q 'nothing staged'; then + printf '%s\n' "$RESULT" | sed -n 's/.*data="error: \(.*\)"$/Error: \1 (no settings were changed)/p' >&2 + else + printf '%s\n' "$RESULT" >&2 + echo "Error: import broadcast did not report success (app predates JSON configs?)" >&2 + fi + exit 1 +fi +printf '%s\n' "$RESULT" | sed -n 's/.*data="imported: \(.*\)"$/Imported \1/p' +# The app exits half a second after an import. Wait for that, so that a command +# run straight after this one (pull_config.sh, say) reaches a fresh process +# rather than the exiting one. A restarted process has a new pid. If the cached +# app freezer stops the process before it gets to exit, stop it from here. +PID="$(adb shell pidof "$PACKAGE" 2>/dev/null | tr -d '\r' | awk '{print $1}')" +if [ -n "$PID" ]; then + adb shell "i=0; while [ -d /proc/$PID ] && [ \$i -lt 50 ]; do sleep 0.1; i=\$((i+1)); done" + if adb shell "[ -d /proc/$PID ]" 2>/dev/null; then + adb shell am force-stop "$PACKAGE" + fi +fi +echo "The app restarts on its next launch with the imported settings." diff --git a/tests/config-transfer-scripts.test.cjs b/tests/config-transfer-scripts.test.cjs new file mode 100644 index 00000000..311b8671 --- /dev/null +++ b/tests/config-transfer-scripts.test.cjs @@ -0,0 +1,76 @@ +const test = require('node:test'); +const assert = require('node:assert'); +const { execFileSync } = require('node:child_process'); +const { readFileSync, readdirSync, statSync } = require('node:fs'); +const { join } = require('node:path'); + +test('config_document converts Android XML, passes JSON documents through and rejects unusable files', () => { + execFileSync('python3', ['-c', ` +import importlib.util, json, pathlib, sys, tempfile +sys.path.insert(0, 'scripts') +spec = importlib.util.spec_from_file_location('ios_config', 'scripts/ios_config.py') +ios = importlib.util.module_from_spec(spec); spec.loader.exec_module(ios) +import config_document as m +xml = b''' + + [{"url":"g2mirror://test@host"}] + + + + + π & < 🔋 next +''' +with tempfile.TemporaryDirectory() as d: + p = pathlib.Path(d) / 'settings' + p.write_bytes(xml) + doc = json.loads(m.read_document(p)) + assert doc['schema'] == 1 and doc['platform'] == 'android', doc + assert doc['settings'] == {'terminal.connections': '[{"url":"g2mirror://test@host"}]', 'flag': True, 'empty': '', 'number': 42, 'ratio': 0.25, 'unicode': '\\u03c0 & < \\U0001f50b\\nnext'}, doc + text = json.dumps({'schema': 2, 'platform': 'ios', 'settings': {'a': [1, {'b': None is None}]}, 'platformSettings': {'ios.x': 'y'}}) + p.write_text(text) + assert m.read_document(p) == text + ios.atomic_write(p, b'{}') + assert p.stat().st_mode & 0o777 == 0o600 + for invalid in [b'{}', b'[]', b'{"schema":3,"settings":{}}', b'{"schema":true,"settings":{}}', b'{"schema":2.0,"settings":{}}', b'{"schema":2}', + b'{"schema":2,"settings":{"x":null}}', b'{"schema":2,"settings":{"x":NaN}}', b'{"schema":2,"settings":{"x":1e999}}', + b'{"schema":2,"settings":{"x":1,"x":2}}', b'{"schema":2,"settings":{},"platformSettings":[]}', + b'{"schema":2,"platform":1,"settings":{}}', b'{"schema":2,"settings":{"":"x"}}', + b'', b'', + b'ab', b'oops']: + p.write_bytes(invalid) + try: m.read_document(p) + except (ValueError, m.ET.ParseError): pass + else: raise AssertionError(f'accepted invalid config {invalid!r}') +`], { stdio: 'inherit' }); +}); + +// FaceclawSettingsPortReceiver exports and imports the keys the app keeps in NativeScript's +// ApplicationSettings (prefs.db) from that file, by a fixed list. A new ApplicationSettings +// caller needs its keys added there (nativeScriptKey) and here. +test('settings stored outside FaceclawSettings are the ones the Android config port knows about', () => { + const known = new Map([ + ['app/g2/device-addresses.ts', ['deviceAddress.', 'deviceIdentity.']], + ['app/phone-ui/onboarding-state.ts', ['onboarding.complete', 'onboarding.previewOnly']], + ['app/apps/evenhub/session.ts', ['evenhub:']], + // iOS-only: NSUserDefaults holds every setting there. + ['app/native/ios-bluetooth.ts', null], + ['app/native/settings-store.ios.ts', null], + ]); + const users = []; + const walk = (dir) => { + for (const name of readdirSync(dir)) { + const path = join(dir, name); + if (statSync(path).isDirectory()) walk(path); + else if (path.endsWith('.ts') && /\bApplicationSettings\b/.test(readFileSync(path, 'utf8'))) users.push(path); + } + }; + walk('app'); + assert.deepStrictEqual(users.sort(), [...known.keys()].sort()); + const receiver = readFileSync('App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawSettingsPortReceiver.kt', 'utf8'); + for (const [file, keys] of known) { + for (const key of keys ?? []) { + assert.ok(receiver.includes(`"${key}"`), `${file}: FaceclawSettingsPortReceiver.nativeScriptKey is missing ${key}`); + assert.ok(readFileSync(file, 'utf8').includes(key) || file.endsWith('session.ts'), `${file} no longer uses ${key}`); + } + } +}); diff --git a/tests/ios-config-scripts.test.cjs b/tests/ios-config-scripts.test.cjs deleted file mode 100644 index ea58f159..00000000 --- a/tests/ios-config-scripts.test.cjs +++ /dev/null @@ -1,21 +0,0 @@ -const test = require('node:test'); -const { execFileSync } = require('node:child_process'); -test('iOS config codec preserves Android XML and JSON types and rejects malformed imports', () => { - execFileSync('python3', ['-c', ` -import importlib.util, pathlib, tempfile -spec = importlib.util.spec_from_file_location('config', 'scripts/ios_config.py') -m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m) -values = {'terminal.connections': '[{"url":"g2mirror://test@host"}]', 'flag': True, 'empty': '', 'number': 42, 'ratio': 0.25, 'unicode': 'π & < 🔋\\nnext'} -with tempfile.TemporaryDirectory() as d: - p = pathlib.Path(d) / 'settings' - for xml in [False, True]: - m.atomic_write(p, m.encode_config(values, xml)) - assert m.read_config(p) == values - assert p.stat().st_mode & 0o777 == 0o600 - for invalid in [b'{}', b'', b'', b'ab', b'{"schema":1,"settings":{"x":null}}', b'{"schema":1,"settings":{"x":NaN}}', b'oops']: - p.write_bytes(invalid) - try: m.read_config(p) - except (ValueError, m.ET.ParseError): pass - else: raise AssertionError('accepted invalid config') -`], { stdio: 'inherit' }); -}); diff --git a/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/SettingsTransferTest.kt b/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/SettingsTransferTest.kt new file mode 100644 index 00000000..a1d51200 --- /dev/null +++ b/tests/kotlin/src/commonTest/kotlin/com/faceclaw/app/SettingsTransferTest.kt @@ -0,0 +1,151 @@ +package com.faceclaw.app + +import kotlin.test.Test +import kotlin.test.assertEquals +import kotlin.test.assertFailsWith +import kotlin.test.assertNull +import kotlin.test.assertTrue + +class SettingsTransferTest { + private val androidSettings: Map = linkedMapOf( + "display.timeFormat" to "24h", + "terminal.connections" to """[{"id":"c1","url":"g2mirror://token@host:8737","enabled":true}]""", + "display.uiFont2" to """{"kind":"ttf","file":"Roboto-Light.ttf","size":15}""", + "navigate.homeAddress" to "[home] 1 Main St", + "assistant.prompt" to "{ \"not\": \"compact\" }", + "voice.enabled" to true, + "flappy.highScore" to "18", + "ratio" to 0.25, + "count" to 42L, + "notifications.sources" to """[{"packageName":"com.tailscale.ipn","showOnGlasses":true}]""", + "deviceIdentity.pairedAtMs" to JsonNumber("1791678209651"), + "deviceAddress.left" to "EC:D7:82:69:3C:CB", + "onboarding.complete" to true, + "evenhub:com.example.app:ls:state" to """{"level":3}""", + "ios.settings.changeToken" to "bookkeeping", + ) + + @Test + fun exportSplitsPortableAndPlatformSettingsAndExpandsJsonLosslessly() { + val text = SettingsTransfer.export(androidSettings, "android", "0.8.3") + val document = Json.parseObject(text) + assertEquals(JsonNumber("2"), document["schema"]) + assertEquals("android", document["platform"]) + assertEquals("0.8.3", document["appVersion"]) + val settings = document["settings"].asObject()!! + val local = document["platformSettings"].asObject()!! + assertEquals(settings.keys.sorted(), settings.keys.toList()) + assertEquals( + setOf("notifications.sources", "deviceIdentity.pairedAtMs", "deviceAddress.left", "onboarding.complete"), + local.keys, + ) + assertTrue("ios.settings.changeToken" !in settings && "ios.settings.changeToken" !in local) + // Compact JSON becomes structure; anything that wouldn't round-trip exactly stays a string. + assertEquals("g2mirror://token@host:8737", settings["terminal.connections"].asArray()!![0].asObject()!!["url"]) + assertEquals(JsonNumber("3"), settings["evenhub:com.example.app:ls:state"].asObject()!!["level"]) + assertEquals("[home] 1 Main St", settings["navigate.homeAddress"]) + assertEquals("{ \"not\": \"compact\" }", settings["assistant.prompt"]) + assertEquals(true, settings["voice.enabled"]) + assertEquals("18", settings["flappy.highScore"]) + assertEquals(JsonNumber("0.25"), settings["ratio"]) + assertEquals(JsonNumber("42"), settings["count"]) + assertEquals(JsonNumber("1791678209651"), local["deviceIdentity.pairedAtMs"]) + } + + @Test + fun samePlatformImportRestoresEveryValueExactly() { + val plan = SettingsTransfer.planImport(SettingsTransfer.export(androidSettings, "android"), "android") + assertEquals("android", plan.sourcePlatform) + assertTrue(plan.skipped.isEmpty()) + val expected = androidSettings - "ios.settings.changeToken" + assertEquals(expected.keys, plan.values.keys) + for ((key, value) in expected) { + val want: Any? = when (value) { + is Double -> JsonNumber.of(value) + is Long -> JsonNumber(value.toString()) + else -> value + } + assertEquals(want, plan.values[key], key) + } + } + + @Test + fun crossPlatformImportCarriesOnlyPortableSettings() { + val plan = SettingsTransfer.planImport(SettingsTransfer.export(androidSettings, "android"), "ios") + assertEquals( + setOf("notifications.sources", "deviceIdentity.pairedAtMs", "deviceAddress.left", "onboarding.complete"), + plan.skipped.toSet(), + ) + assertEquals("24h", plan.values["display.timeFormat"]) + assertEquals(androidSettings["terminal.connections"], plan.values["terminal.connections"]) + assertTrue(plan.values.keys.none { SettingsTransfer.isPlatformLocal(it) }) + } + + @Test + fun legacySchemaOneIsClassifiedAtImport() { + val iosExport = """{"schema":1,"settings":{ + "ios.ble.peripheral.EC:D7:82:69:3C:CB":"{\"identifier\":\"8A2D\",\"role\":\"left\"}", + "deviceAddress.left":"EC:D7:82:69:3C:CB", + "integrations.evenhub.terminalId":"1429021a30db4586", + "privacy.dataCollection":"full", + "onboarding.complete":true}}""" + val onAndroid = SettingsTransfer.planImport(iosExport, "android") + assertEquals("ios", onAndroid.sourcePlatform) + assertEquals(mapOf("privacy.dataCollection" to "full"), onAndroid.values) + assertEquals(4, onAndroid.skipped.size) + assertEquals(5, SettingsTransfer.planImport(iosExport, "ios").values.size) + + // scripts/config_document.py converts Android shared-preferences XML to this shape. + val fromXml = """{"schema":1,"platform":"android","settings":{"deviceAddress.left":"AA","display.mode":"576x288"}}""" + assertEquals(2, SettingsTransfer.planImport(fromXml, "android").values.size) + assertEquals(listOf("deviceAddress.left"), SettingsTransfer.planImport(fromXml, "ios").skipped) + } + + @Test + fun handEditedDocumentsFollowTheirSections() { + val edited = """{ + "schema": 2, + "settings": { "launcher.folders": { "pinball": "Games" }, "music.lastApp": "kept" }, + "platformSettings": { "deviceAddress.left": "AA" } + }""" + val plan = SettingsTransfer.planImport(edited, "ios") + assertNull(plan.sourcePlatform) + // No platform: platformSettings never apply, settings always do, even a platform-local key. + assertEquals(mapOf("launcher.folders" to """{"pinball":"Games"}""", "music.lastApp" to "kept"), plan.values) + assertEquals(listOf("deviceAddress.left"), plan.skipped) + } + + @Test + fun malformedDocumentsAreRejected() { + val invalid = listOf( + "not json", + "[]", + """{"settings":{}}""", + """{"schema":3,"settings":{}}""", + """{"schema":2}""", + """{"schema":2,"settings":[]}""", + """{"schema":2,"settings":{"x":null}}""", + """{"schema":2,"settings":{"":"empty name"}}""", + """{"schema":2,"platform":7,"settings":{}}""", + """{"schema":2,"platform":"ios","settings":{"x":"a"},"platformSettings":{"x":"b"}}""", + """{"schema":2,"settings":{"x":"a","x":"b"}}""", + ) + for (text in invalid) assertFailsWith(text) { SettingsTransfer.planImport(text, "ios") } + assertFailsWith { SettingsTransfer.export(mapOf("x" to listOf("a")), "ios") } + } + + @Test + fun objectiveCBridgeUsesJsonText() { + val document = SettingsTransfer.exportValues("""{"a":"b","on":true,"n":1.5,"ios.ble.peripheral.X":"{}"}""", "ios", null)!! + assertNull(Json.parseObject(document)["appVersion"]) + val reply = Json.parseObject(SettingsTransfer.importPlan(document, "android")) + assertEquals(true, reply["ok"]) + assertEquals(mapOf("a" to "b", "n" to JsonNumber("1.5"), "on" to true), reply["settings"]) + assertEquals(listOf("ios.ble.peripheral.X"), reply["skipped"]) + assertEquals("ios", reply["sourcePlatform"]) + val failure = Json.parseObject(SettingsTransfer.importPlan("""{"schema":9,"settings":{}}""", "ios")) + assertEquals(false, failure["ok"]) + assertEquals("Unsupported config schema 9", failure["message"]) + assertNull(SettingsTransfer.exportValues("[]", "ios", null)) + } +} diff --git a/tests/native/ios-config-test.m b/tests/native/ios-config-test.m index a5420335..ea012b66 100644 --- a/tests/native/ios-config-test.m +++ b/tests/native/ios-config-test.m @@ -1,34 +1,80 @@ #import #import "FaceclawConfigPort.h" #include -static NSDictionary *send(NSString *dir, NSUserDefaults *defaults, NSString *domain, NSDictionary *request) { +#include + +static NSString *jsonText(id object) { + return [[NSString alloc] initWithData:[NSJSONSerialization dataWithJSONObject:object options:0 error:nil] encoding:NSUTF8StringEncoding]; +} +static id parse(NSString *text) { + return [NSJSONSerialization JSONObjectWithData:[text dataUsingEncoding:NSUTF8StringEncoding] options:0 error:nil]; +} + +/** Stands in for Kotlin SettingsTransfer (tested in tests/kotlin): wraps and unwraps values. */ +@interface StubCodec : NSObject +@property NSString *lastAppVersion; +@property NSDictionary *forcedPlan; +@end +@implementation StubCodec +- (NSString *)exportValuesJson:(NSString *)valuesJson platform:(NSString *)platform appVersion:(NSString *)appVersion { + self.lastAppVersion = appVersion; + return jsonText(@{@"schema":@2, @"platform":platform, @"settings":parse(valuesJson)}); +} +- (NSString *)importPlanDocument:(NSString *)document platform:(NSString *)platform { + if (self.forcedPlan) return jsonText(self.forcedPlan); + NSDictionary *doc = parse(document); + if (![doc[@"schema"] isEqual:@2]) return jsonText(@{@"ok":@NO, @"message":@"Unsupported config schema"}); + return jsonText(@{@"ok":@YES, @"settings":doc[@"settings"], @"skipped":@[@"deviceAddress.left"], @"sourcePlatform":@"android"}); +} +@end + +static NSDictionary *send(NSString *dir, NSUserDefaults *defaults, NSString *domain, StubCodec *codec, NSDictionary *request) { NSData *json = [NSJSONSerialization dataWithJSONObject:request options:0 error:nil]; assert([json writeToFile:[dir stringByAppendingPathComponent:@"request.json"] atomically:YES]); - [FaceclawConfigPort processDirectory:dir defaults:defaults domain:domain]; + [FaceclawConfigPort processDirectory:dir defaults:defaults domain:domain codec:codec appVersion:@"1.2.3"]; assert(![NSFileManager.defaultManager fileExistsAtPath:[dir stringByAppendingPathComponent:@"request.json"]]); return [NSJSONSerialization JSONObjectWithData:[NSData dataWithContentsOfFile:[dir stringByAppendingPathComponent:@"response.json"]] options:0 error:nil]; } + int main(int argc, const char **argv) { @autoreleasepool { NSString *dir = [NSString stringWithUTF8String:argv[1]]; NSString *domain = [@"com.faceclaw.config-test." stringByAppendingString:NSUUID.UUID.UUIDString]; NSUserDefaults *defaults = [[NSUserDefaults alloc] initWithSuiteName:domain]; - [defaults setPersistentDomain:@{@"keep":@"original", @"enabled":@NO} forName:domain]; + StubCodec *codec = [StubCodec new]; + [defaults setPersistentDomain:@{@"keep":@"original", @"enabled":@NO, @"notANumber":@(NAN)} forName:domain]; NSDictionary *input = @{@"terminal.connections":@"[{\"url\":\"g2mirror://test@host\"}]", @"enabled":@YES, @"empty":@"", @"number":@42, @"unicode":@"π & < \n 🔋"}; - NSDictionary *reply = send(dir, defaults, domain, @{@"id":@"1", @"operation":@"push", @"settings":input}); + NSDictionary *reply = send(dir, defaults, domain, codec, @{@"id":@"1", @"operation":@"push", + @"document":jsonText(@{@"schema":@2, @"settings":input})}); assert([reply[@"ok"] boolValue] && [reply[@"count"] intValue] == 5); - assert([[defaults persistentDomainForName:domain][@"keep"] isEqual:@"original"]); + assert([reply[@"skipped"] isEqual:@[@"deviceAddress.left"]] && [reply[@"sourcePlatform"] isEqual:@"android"]); + NSDictionary *stored = [defaults persistentDomainForName:domain]; + assert([stored[@"keep"] isEqual:@"original"]); + assert(stored[@"enabled"] == (id)kCFBooleanTrue && [stored[@"number"] isEqual:@42]); NSDictionary *backup = [NSDictionary dictionaryWithContentsOfFile:[dir stringByAppendingPathComponent:@"previous.plist"]]; assert([backup[@"keep"] isEqual:@"original"] && ![backup[@"enabled"] boolValue]); - reply = send(dir, defaults, domain, @{@"id":@"2", @"operation":@"pull"}); + + reply = send(dir, defaults, domain, codec, @{@"id":@"2", @"operation":@"pull"}); assert([reply[@"id"] isEqual:@"2"] && [reply[@"ok"] boolValue]); - NSDictionary *output = reply[@"config"][@"settings"]; + assert([codec.lastAppVersion isEqual:@"1.2.3"]); + NSDictionary *document = parse(reply[@"document"]); + assert([document[@"platform"] isEqual:@"ios"]); + NSDictionary *output = document[@"settings"]; for (NSString *key in input) assert([output[key] isEqual:input[key]]); - assert(!output[@"ios.settings.changeToken"]); + assert([output[@"keep"] isEqual:@"original"] && [reply[@"count"] intValue] == (int)output.count); + assert(!output[@"ios.settings.changeToken"] && !output[@"notANumber"]); + NSDictionary *before = [defaults persistentDomainForName:domain]; - reply = send(dir, defaults, domain, @{@"id":@"3", @"operation":@"push", @"settings":@{@"keep":@"changed", @"invalid":@[]}}); + reply = send(dir, defaults, domain, codec, @{@"id":@"3", @"operation":@"push", @"document":jsonText(@{@"schema":@9, @"settings":@{}})}); + assert(![reply[@"ok"] boolValue] && [reply[@"message"] isEqual:@"Unsupported config schema"]); + codec.forcedPlan = @{@"ok":@YES, @"settings":@{@"keep":@"changed", @"invalid":@[]}}; + reply = send(dir, defaults, domain, codec, @{@"id":@"4", @"operation":@"push", @"document":@"{}"}); + assert(![reply[@"ok"] boolValue]); + codec.forcedPlan = nil; + // Requests from older scripts sent pre-converted settings rather than a document. + reply = send(dir, defaults, domain, codec, @{@"id":@"5", @"operation":@"push", @"settings":@{@"keep":@"changed"}}); assert(![reply[@"ok"] boolValue]); assert([[defaults persistentDomainForName:domain] isEqual:before]); - reply = send(dir, defaults, domain, @{@"id":@"4", @"operation":@"bad"}); + reply = send(dir, defaults, domain, codec, @{@"id":@"6", @"operation":@"bad"}); assert(![reply[@"ok"] boolValue]); [defaults removePersistentDomainForName:domain]; [defaults synchronize]; puts("PASS: native config merges typed values, backs up, exports, consumes requests once and rejects invalid imports atomically");