fix: harden settings appearance parsing and dedupe usage contract

Author: thymikee

src/core/settings-contract.ts

@@ -0,0 +1,15 @@
+export const SETTINGS_WIFI_USAGE = '<wifi|airplane|location> <on|off>';
+export const SETTINGS_APPEARANCE_USAGE = 'appearance <light|dark|toggle>';
+export const SETTINGS_FACEID_USAGE = 'faceid <match|nonmatch|enroll|unenroll>';
+export const SETTINGS_PERMISSION_USAGE =
+  'permission <grant|deny|reset> <camera|microphone|photos|contacts|contacts-limited|notifications|calendar|location|location-always|media-library|motion|reminders|siri> [full|limited]';
+
+export const SETTINGS_USAGE_OVERRIDE = [
+  `settings ${SETTINGS_WIFI_USAGE}`,
+  `settings ${SETTINGS_APPEARANCE_USAGE}`,
+  `settings ${SETTINGS_FACEID_USAGE}`,
+  `settings ${SETTINGS_PERMISSION_USAGE}`,
+].join(' | ');
+
+export const SETTINGS_INVALID_ARGS_MESSAGE =
+  `settings requires ${SETTINGS_WIFI_USAGE}, ${SETTINGS_APPEARANCE_USAGE}, ${SETTINGS_FACEID_USAGE}, or ${SETTINGS_PERMISSION_USAGE}`;

src/daemon/handlers/snapshot.ts

@@ -1,5 +1,6 @@
 import { dispatchCommand, resolveTargetDevice } from '../../core/dispatch.ts';
 import { isCommandSupportedOnDevice } from '../../core/capabilities.ts';
+import { SETTINGS_INVALID_ARGS_MESSAGE } from '../../core/settings-contract.ts';
 import { runIosRunnerCommand, stopIosRunnerSession } from '../../platforms/ios/runner-client.ts';
 import { snapshotAndroid } from '../../platforms/android/index.ts';
 import {
@@ -394,8 +395,7 @@ export async function handleSnapshotCommands(params: {
         ok: false,
         error: {
           code: 'INVALID_ARGS',
-          message:
-            'settings requires <wifi|airplane|location> <on|off>, appearance <light|dark|toggle>, faceid <match|nonmatch|enroll|unenroll>, or permission <grant|deny|reset> <camera|microphone|photos|contacts|contacts-limited|notifications|calendar|location|location-always|media-library|motion|reminders|siri> [full|limited]',
+          message: SETTINGS_INVALID_ARGS_MESSAGE,
         },
       };
     }

src/platforms/android/__tests__/index.test.ts

@@ -336,6 +336,58 @@ test('setAndroidSetting appearance toggle flips current mode', async () => {
   );
 });
 
+test('setAndroidSetting appearance toggle from auto sets dark mode', async () => {
+  await withMockedAdb(
+    'agent-device-android-appearance-toggle-auto-',
+    [
+      '#!/bin/sh',
+      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
+      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
+      'if [ "$1" = "-s" ] && [ "$4" = "cmd" ] && [ "$5" = "uimode" ] && [ "$6" = "night" ] && [ -z "$7" ]; then',
+      '  echo "Night mode: auto"',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    async ({ argsLogPath, device }) => {
+      await setAndroidSetting(device, 'appearance', 'toggle');
+      const lines = (await fs.readFile(argsLogPath, 'utf8'))
+        .trim()
+        .split('\n')
+        .filter(Boolean);
+      const logged = lines.join(' ');
+      assert.match(logged, /shell cmd uimode night yes/);
+    },
+  );
+});
+
+test('setAndroidSetting appearance toggle rejects unknown current mode output', async () => {
+  await withMockedAdb(
+    'agent-device-android-appearance-toggle-unknown-',
+    [
+      '#!/bin/sh',
+      'if [ "$1" = "-s" ] && [ "$4" = "cmd" ] && [ "$5" = "uimode" ] && [ "$6" = "night" ] && [ -z "$7" ]; then',
+      '  echo "mode unavailable"',
+      '  exit 0',
+      'fi',
+      'exit 0',
+      '',
+    ].join('\n'),
+    async ({ device }) => {
+      await assert.rejects(
+        () => setAndroidSetting(device, 'appearance', 'toggle'),
+        (error: unknown) => {
+          assert.equal(error instanceof AppError, true);
+          assert.equal((error as AppError).code, 'COMMAND_FAILED');
+          assert.match((error as AppError).message, /Unable to determine current Android appearance/);
+          return true;
+        },
+      );
+    },
+  );
+});
+
 test('swipeAndroid invokes adb input swipe with duration', async () => {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-swipe-test-'));
   const adbPath = path.join(tmpDir, 'adb');

src/platforms/android/index.ts

@@ -12,6 +12,7 @@ import {
   parsePermissionTarget,
   type PermissionSettingOptions,
 } from '../permission-utils.ts';
+import { parseAppearanceAction } from '../appearance.ts';
 
 const ALIASES: Record<string, { type: 'intent' | 'package'; value: string }> = {
   settings: { type: 'intent', value: 'android.settings.SETTINGS' },
@@ -733,16 +734,6 @@ function parseSettingState(state: string): boolean {
   throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
 }
 
-type AppearanceAction = 'light' | 'dark' | 'toggle';
-
-function parseAppearanceAction(state: string): AppearanceAction {
-  const normalized = state.trim().toLowerCase();
-  if (normalized === 'light') return 'light';
-  if (normalized === 'dark') return 'dark';
-  if (normalized === 'toggle') return 'toggle';
-  throw new AppError('INVALID_ARGS', `Invalid appearance state: ${state}. Use light|dark|toggle.`);
-}
-
 async function resolveAndroidAppearanceTarget(
   device: DeviceInfo,
   state: string,
@@ -767,17 +758,17 @@ async function resolveAndroidAppearanceTarget(
       stderr: currentResult.stderr,
     });
   }
+  if (current === 'auto') return 'dark';
   return current === 'dark' ? 'light' : 'dark';
 }
 
-function parseAndroidAppearance(stdout: string, stderr: string): 'light' | 'dark' | null {
-  const output = `${stdout}\n${stderr}`.toLowerCase();
-  if (output.includes('night mode: yes')) return 'dark';
-  if (output.includes('night mode: no')) return 'light';
-  if (/\bdark\b/.test(output)) return 'dark';
-  if (/\blight\b/.test(output)) return 'light';
-  if (/\byes\b/.test(output)) return 'dark';
-  if (/\bno\b/.test(output)) return 'light';
+function parseAndroidAppearance(stdout: string, stderr: string): 'light' | 'dark' | 'auto' | null {
+  const match = /night mode:\s*(yes|no|auto)\b/i.exec(`${stdout}\n${stderr}`);
+  if (!match) return null;
+  const value = match[1].toLowerCase();
+  if (value === 'yes') return 'dark';
+  if (value === 'no') return 'light';
+  if (value === 'auto') return 'auto';
   return null;
 }
 

src/platforms/appearance.ts

@@ -0,0 +1,11 @@
+import { AppError } from '../utils/errors.ts';
+
+export type AppearanceAction = 'light' | 'dark' | 'toggle';
+
+export function parseAppearanceAction(state: string): AppearanceAction {
+  const normalized = state.trim().toLowerCase();
+  if (normalized === 'light') return 'light';
+  if (normalized === 'dark') return 'dark';
+  if (normalized === 'toggle') return 'toggle';
+  throw new AppError('INVALID_ARGS', `Invalid appearance state: ${state}. Use light|dark|toggle.`);
+}

src/platforms/ios/__tests__/index.test.ts

@@ -650,6 +650,43 @@ exit 1
   );
 });
 
+test('setIosSetting appearance toggle rejects unsupported current appearance output', async () => {
+  await withMockedXcrun(
+    'agent-device-ios-appearance-toggle-unsupported-test-',
+    `#!/bin/sh
+if [ "$1" = "simctl" ] && [ "$2" = "list" ] && [ "$3" = "devices" ] && [ "$4" = "-j" ]; then
+  cat <<'JSON'
+{"devices":{"com.apple.CoreSimulator.SimRuntime.iOS-18-0":[{"udid":"sim-1","state":"Booted"}]}}
+JSON
+  exit 0
+fi
+if [ "$1" = "simctl" ] && [ "$2" = "ui" ] && [ "$3" = "sim-1" ] && [ "$4" = "appearance" ] && [ -z "$5" ]; then
+  echo "unsupported"
+  exit 0
+fi
+exit 0
+`,
+    async () => {
+      const device: DeviceInfo = {
+        platform: 'ios',
+        id: 'sim-1',
+        name: 'iPhone Sim',
+        kind: 'simulator',
+        booted: true,
+      };
+      await assert.rejects(
+        () => setIosSetting(device, 'appearance', 'toggle'),
+        (error: unknown) => {
+          assert.equal(error instanceof AppError, true);
+          assert.equal((error as AppError).code, 'COMMAND_FAILED');
+          assert.match((error as AppError).message, /Unable to determine current iOS appearance/);
+          return true;
+        },
+      );
+    },
+  );
+});
+
 test('setIosSetting permission grant camera uses simctl privacy', async () => {
   await withMockedXcrun(
     'agent-device-ios-permission-camera-test-',

src/platforms/ios/apps.ts

@@ -8,6 +8,7 @@ import {
   parsePermissionTarget,
   type PermissionSettingOptions,
 } from '../permission-utils.ts';
+import { parseAppearanceAction } from '../appearance.ts';
 
 import { IOS_APP_LAUNCH_TIMEOUT_MS, IOS_DEVICECTL_TIMEOUT_MS } from './config.ts';
 import {
@@ -360,16 +361,6 @@ function parseSettingState(state: string): boolean {
   throw new AppError('INVALID_ARGS', `Invalid setting state: ${state}`);
 }
 
-type AppearanceAction = 'light' | 'dark' | 'toggle';
-
-function parseAppearanceAction(state: string): AppearanceAction {
-  const normalized = state.trim().toLowerCase();
-  if (normalized === 'light') return 'light';
-  if (normalized === 'dark') return 'dark';
-  if (normalized === 'toggle') return 'toggle';
-  throw new AppError('INVALID_ARGS', `Invalid appearance state: ${state}. Use light|dark|toggle.`);
-}
-
 async function resolveIosAppearanceTarget(deviceId: string, state: string): Promise<'light' | 'dark'> {
   const action = parseAppearanceAction(state);
   if (action !== 'toggle') return action;
@@ -395,9 +386,12 @@ async function resolveIosAppearanceTarget(deviceId: string, state: string): Prom
 }
 
 function parseIosAppearance(stdout: string, stderr: string): 'light' | 'dark' | null {
-  const match = /\b(light|dark)\b/i.exec(`${stdout}\n${stderr}`);
+  const match = /\b(light|dark|unsupported|unknown)\b/i.exec(`${stdout}\n${stderr}`);
   if (!match) return null;
-  return match[1].toLowerCase() === 'dark' ? 'dark' : 'light';
+  const value = match[1].toLowerCase();
+  if (value === 'dark') return 'dark';
+  if (value === 'light') return 'light';
+  return null;
 }
 
 type FaceIdAction = 'match' | 'nonmatch' | 'enroll' | 'unenroll';

src/utils/command-schema.ts

@@ -1,3 +1,5 @@
+import { SETTINGS_USAGE_OVERRIDE } from '../core/settings-contract.ts';
+
 export type CliFlags = {
   json: boolean;
   platform?: 'ios' | 'android';
@@ -557,8 +559,7 @@ const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS],
   },
   settings: {
-    usageOverride:
-      'settings <wifi|airplane|location> <on|off> | settings appearance <light|dark|toggle> | settings faceid <match|nonmatch|enroll|unenroll> | settings permission <grant|deny|reset> <camera|microphone|photos|contacts|contacts-limited|notifications|calendar|location|location-always|media-library|motion|reminders|siri> [full|limited]',
+    usageOverride: SETTINGS_USAGE_OVERRIDE,
     description: 'Toggle OS settings, appearance, and app permissions (session app scope for permission actions)',
     positionalArgs: ['setting', 'state', 'target?', 'mode?'],
     allowedFlags: [],