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

+2 -2
View File
@@ -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
@@ -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()
@@ -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<String, Any?> {
val values = linkedMapOf<String, Any?>()
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 <map> 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 <map> 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
}
}
}
+13 -2
View File
@@ -1,6 +1,17 @@
#import <Foundation/Foundation.h>
/** 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 <NSObject>
/** 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<FaceclawConfigCodec>)codec appVersion:(nullable NSString *)appVersion;
@end
NS_ASSUME_NONNULL_END
+85 -30
View File
@@ -1,57 +1,112 @@
#import "FaceclawConfigPort.h"
#include <math.h>
// The app links FaceclawKit; tests/ios-config-native.cjs builds this file for macOS without it
// and supplies its own codec.
#if __has_include(<FaceclawKit/FaceclawKit.h>)
#import <FaceclawKit/FaceclawKit.h>
@interface FaceclawKitConfigCodec : NSObject <FaceclawConfigCodec>
@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<FaceclawConfigCodec>)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];
+3 -2
View File
@@ -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
@@ -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<String, Any?>) {
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<Int, (Map<String, Any?>) -> Map<String, Any?>> = 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<String, Any?> = 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()
}
@@ -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<String, Any>,
val skipped: List<String>,
/** 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<String, Any?>, platform: String, appVersion: String? = null): String {
val settings = linkedMapOf<String, Any?>()
val local = linkedMapOf<String, Any?>()
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<String, Any?>("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<String, Any>()
val skipped = ArrayList<String>()
val seen = HashSet<String>()
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<String, Any?>, name: String): Map<String, Any?>? {
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 }
}
}
+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).
+132
View File
@@ -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'<!DOCTYPE' in data.upper() or b'<!ENTITY' in data.upper():
raise ValueError('XML declarations of document types/entities are not supported')
root = ET.fromstring(data)
if root.tag != 'map':
raise ValueError('Expected Android shared-preferences <map>')
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())
-53
View File
@@ -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).
+25 -76
View File
@@ -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'<!DOCTYPE' in data.upper() or b'<!ENTITY' in data.upper():
raise ValueError('XML declarations of document types/entities are not supported')
root = ET.fromstring(data)
if root.tag != 'map':
raise ValueError('Expected Android shared-preferences <map>')
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:
+52 -29
View File
@@ -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 <<EOF
Usage: $(basename "$0") [output-file] [-f output-file] [adb-options...]
Pull faceclaw's shared preferences off the attached device into output-file
(default: faceclaw_settings.xml). The output file may be given as a bare
first argument or with -f anywhere. Any other arguments are passed through
to adb, e.g. -s SERIAL or -t ID to pick one of several attached devices.
Export faceclaw's settings from the attached device into output-file
(default: faceclaw_settings.android.json), readable only by you. The output
file may be given as a bare first argument or with -f anywhere. Any other
arguments are passed through to adb, e.g. -s SERIAL or -t ID to pick one of
several attached devices. Push the file to Android or iOS with push_config.sh
or push_config_ios.sh.
EOF
}
@@ -28,26 +30,47 @@ if [ "$ADBUTIL_HELP" = 1 ]; then
fi
PACKAGE=com.faceclaw.app
PREFS=shared_prefs/faceclaw_settings.xml
OUT="${ADBUTIL_FILE:-faceclaw_settings.xml}"
EXPORT_REMOTE=/sdcard/Android/data/$PACKAGE/files/faceclaw-settings-export.xml
OUT="${ADBUTIL_FILE:-faceclaw_settings.android.json}"
EXPORT_REMOTE=/sdcard/Android/data/$PACKAGE/files/faceclaw-settings-export.json
MODE="$(adb_preflight "$PACKAGE")"
if [ "$MODE" = debug ]; then
adb exec-out run-as "$PACKAGE" cat "$PREFS" > "$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)"
+66 -49
View File
@@ -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 <<EOF
Usage: $(basename "$0") [input-file] [-f input-file] [adb-options...]
Push input-file (default: faceclaw_settings.xml) as faceclaw's shared
preferences on the attached device. The input file may be given as a bare
first argument or with -f anywhere. Any other arguments are passed through
to adb, e.g. -s SERIAL or -t ID to pick one of several attached devices.
Import input-file (default: faceclaw_settings.android.json) into faceclaw's
settings on the attached device. The file may be a config pulled from Android
or iOS, or legacy Android shared-preferences XML. It may be given as a bare
first argument or with -f anywhere. Any other arguments are passed through to
adb, e.g. -s SERIAL or -t ID to pick one of several attached devices.
EOF
}
@@ -31,44 +34,58 @@ if [ "$ADBUTIL_HELP" = 1 ]; then
fi
PACKAGE=com.faceclaw.app
PREFS=shared_prefs/faceclaw_settings.xml
IN="${ADBUTIL_FILE:-faceclaw_settings.xml}"
STAGE=/data/local/tmp/faceclaw_settings_push.xml
IMPORT_REMOTE=/sdcard/Android/data/$PACKAGE/files/faceclaw-settings-import.xml
IN="${ADBUTIL_FILE:-faceclaw_settings.android.json}"
IMPORT_REMOTE=/sdcard/Android/data/$PACKAGE/files/faceclaw-settings-import.json
if [ ! -f "$IN" ]; then
echo "Error: $IN not found" >&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."
+76
View File
@@ -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'''<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<map>
<string name="terminal.connections">[{&quot;url&quot;:&quot;g2mirror://test@host&quot;}]</string>
<boolean name="flag" value="true" />
<string name="empty"></string>
<long name="number" value="42" />
<float name="ratio" value="0.25" />
<string name="unicode">&#960; &amp; &lt; &#128267;&#10;next</string>
</map>'''
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'<map><set name="x"/></map>', b'<map><boolean name="x" value="maybe"/></map>',
b'<map><string name="x">a</string><string name="x">b</string></map>', b'<map><string name="x">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}`);
}
}
});
-21
View File
@@ -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'<map><set name="x"/></map>', b'<map><boolean name="x" value="maybe"/></map>', b'<map><string name="x">a</string><string name="x">b</string></map>', b'{"schema":1,"settings":{"x":null}}', b'{"schema":1,"settings":{"x":NaN}}', b'<map><string name="x">oops']:
p.write_bytes(invalid)
try: m.read_config(p)
except (ValueError, m.ET.ParseError): pass
else: raise AssertionError('accepted invalid config')
`], { stdio: 'inherit' });
});
@@ -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<String, Any?> = 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<String, Any>("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<String, Any>("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<IllegalArgumentException>(text) { SettingsTransfer.planImport(text, "ios") }
assertFailsWith<IllegalArgumentException> { 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<String, Any?>("a" to "b", "n" to JsonNumber("1.5"), "on" to true), reply["settings"])
assertEquals(listOf<Any?>("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))
}
}
+56 -10
View File
@@ -1,34 +1,80 @@
#import <Foundation/Foundation.h>
#import "FaceclawConfigPort.h"
#include <assert.h>
static NSDictionary *send(NSString *dir, NSUserDefaults *defaults, NSString *domain, NSDictionary *request) {
#include <math.h>
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 <FaceclawConfigCodec>
@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");