refactor: derive platform allow-lists from the canonical device tuples (#895)

The set of platforms was hand-restated in three places that must agree:
the canonical tuples in src/utils/device.ts, the --platform flag's
enumValues in cli-flags.ts, and the leaf-platform validation in
client-normalizers.ts. The two non-canonical copies could drift.

- Export PLATFORMS from device.ts and add an isPlatform() leaf-platform
  type guard derived from it (excludes the `apple` selector).
- Derive the --platform enumValues and usageLabel from PLATFORM_SELECTORS.
- Derive normalizeOpenDevice's leaf-platform check from isPlatform();
  per-platform udid/serial identifier shaping is unchanged.

Behaviorless: the derived sets equal the previous hardcoded sets.

Author: thymikee

src/__tests__/client-normalizers.test.ts

@@ -0,0 +1,54 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { normalizeOpenDevice } from '../client-normalizers.ts';
+import { PLATFORMS } from '../utils/device.ts';
+
+test('normalizeOpenDevice accepts exactly the canonical leaf platforms', () => {
+  for (const platform of PLATFORMS) {
+    const result = normalizeOpenDevice({
+      platform,
+      id: 'device-1',
+      device: 'Device One',
+    });
+    assert.ok(result, `expected platform "${platform}" to be accepted`);
+    assert.equal(result.platform, platform);
+  }
+  // Lock the membership so the derived check cannot silently widen/narrow.
+  assert.deepEqual([...PLATFORMS], ['ios', 'macos', 'android', 'linux', 'web']);
+});
+
+test('normalizeOpenDevice rejects the apple selector and unknown platforms', () => {
+  // `apple` is a selector, not a concrete device platform, so it must be rejected here.
+  assert.equal(
+    normalizeOpenDevice({ platform: 'apple', id: 'device-1', device: 'Device One' }),
+    undefined,
+  );
+  assert.equal(
+    normalizeOpenDevice({ platform: 'windows', id: 'device-1', device: 'Device One' }),
+    undefined,
+  );
+  assert.equal(
+    normalizeOpenDevice({ platform: undefined, id: 'device-1', device: 'Device One' }),
+    undefined,
+  );
+});
+
+test('normalizeOpenDevice preserves per-platform identifier shaping', () => {
+  const ios = normalizeOpenDevice({
+    platform: 'ios',
+    id: 'udid-1',
+    device: 'iPhone',
+    ios_simulator_device_set: '/tmp/set',
+  });
+  assert.deepEqual(ios?.ios, { udid: 'udid-1', simulatorSetPath: '/tmp/set' });
+  assert.equal(ios?.android, undefined);
+
+  const android = normalizeOpenDevice({
+    platform: 'android',
+    id: 'serial-1',
+    device: 'Pixel',
+    serial: 'explicit-serial',
+  });
+  assert.deepEqual(android?.android, { serial: 'explicit-serial' });
+  assert.equal(android?.ios, undefined);
+});

src/client-normalizers.ts

@@ -4,6 +4,7 @@ import type { DaemonRequest, SessionRuntimeHints } from './daemon/types.ts';
 import { AppError, type NormalizedError } from './utils/errors.ts';
 import type { SnapshotNode } from './utils/snapshot.ts';
 import { buildAppIdentifiers, buildDeviceIdentifiers } from './client-shared.ts';
+import { isPlatform } from './utils/device.ts';
 import {
   leaseScopeFromOptions,
   leaseScopeToCommandFlags,
@@ -183,15 +184,7 @@ export function normalizeOpenDevice(
   const platform = value.platform;
   const id = readOptionalString(value, 'id');
   const name = readOptionalString(value, 'device');
-  if (
-    (platform !== 'ios' &&
-      platform !== 'macos' &&
-      platform !== 'android' &&
-      platform !== 'linux' &&
-      platform !== 'web') ||
-    !id ||
-    !name
-  ) {
+  if (!isPlatform(platform) || !id || !name) {
     return undefined;
   }
   const target = readDeviceTarget(value, 'target');

src/utils/__tests__/cli-flags.test.ts

@@ -0,0 +1,18 @@
+import { test } from 'vitest';
+import assert from 'node:assert/strict';
+import { getFlagDefinition } from '../cli-flags.ts';
+import { PLATFORM_SELECTORS } from '../device.ts';
+
+test('--platform enumValues are derived from the canonical PLATFORM_SELECTORS tuple', () => {
+  const platformFlag = getFlagDefinition('--platform');
+  assert.ok(platformFlag, 'expected a --platform flag definition');
+  assert.deepEqual(platformFlag.enumValues, [...PLATFORM_SELECTORS]);
+  // Guard the exact membership that today's CLI accepts so the derivation cannot drift.
+  assert.deepEqual(platformFlag.enumValues, ['ios', 'macos', 'android', 'linux', 'web', 'apple']);
+});
+
+test('--platform usageLabel lists the same selectors as enumValues', () => {
+  const platformFlag = getFlagDefinition('--platform');
+  assert.ok(platformFlag);
+  assert.equal(platformFlag.usageLabel, `--platform ${PLATFORM_SELECTORS.join('|')}`);
+});

src/utils/__tests__/device.test.ts

@@ -1,7 +1,9 @@
 import { test } from 'vitest';
 import assert from 'node:assert/strict';
 import {
+  isPlatform,
   matchesPlatformSelector,
+  PLATFORMS,
   resolveApplePlatformName,
   resolveAppleSimulatorSetPathForSelector,
   resolveDevice,
@@ -15,6 +17,16 @@ test('matchesPlatformSelector resolves apple selector across Apple platforms', (
   assert.equal(matchesPlatformSelector('android', 'apple'), false);
 });
 
+test('isPlatform accepts exactly the canonical PLATFORMS tuple', () => {
+  for (const platform of PLATFORMS) {
+    assert.equal(isPlatform(platform), true);
+  }
+  // The `apple` selector is not a concrete leaf platform.
+  assert.equal(isPlatform('apple'), false);
+  assert.equal(isPlatform('windows'), false);
+  assert.equal(isPlatform(undefined), false);
+});
+
 test('resolveApplePlatformName resolves tv and desktop targets', () => {
   assert.equal(resolveApplePlatformName('tv'), 'tvOS');
   assert.equal(resolveApplePlatformName('mobile'), 'iOS');

src/utils/cli-flags.ts

@@ -3,7 +3,7 @@ import type { RecordingExportQuality } from '../core/recording-export-quality.ts
 import type { BackMode } from '../core/back-mode.ts';
 import type { ClickButton } from '../core/click-button.ts';
 import type { SwipePattern } from '../core/scroll-gesture.ts';
-import type { DeviceTarget, PlatformSelector } from './device.ts';
+import { PLATFORM_SELECTORS, type DeviceTarget, type PlatformSelector } from './device.ts';
 import type {
   DaemonInstallSource,
   DaemonServerMode,
@@ -344,8 +344,8 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     key: 'platform',
     names: ['--platform'],
     type: 'enum',
-    enumValues: ['ios', 'macos', 'android', 'linux', 'web', 'apple'],
-    usageLabel: '--platform ios|macos|android|linux|web|apple',
+    enumValues: PLATFORM_SELECTORS,
+    usageLabel: `--platform ${PLATFORM_SELECTORS.join('|')}`,
     usageDescription: 'Platform to target (`apple` aliases the Apple automation backend)',
   },
   {

src/utils/device.ts

@@ -1,7 +1,7 @@
 import { AppError } from './errors.ts';
 
 export type ApplePlatform = 'ios' | 'macos';
-const PLATFORMS = ['ios', 'macos', 'android', 'linux', 'web'] as const;
+export const PLATFORMS = ['ios', 'macos', 'android', 'linux', 'web'] as const;
 export type Platform = (typeof PLATFORMS)[number];
 export const PLATFORM_SELECTORS = [...PLATFORMS, 'apple'] as const;
 export type PlatformSelector = (typeof PLATFORM_SELECTORS)[number];
@@ -46,6 +46,12 @@ export function isApplePlatform(
   return platform === 'apple' || platform === 'ios' || platform === 'macos';
 }
 
+export function isPlatform(value: unknown): value is Platform {
+  // Leaf-platform membership derived from the canonical PLATFORMS tuple (excludes the
+  // `apple` selector, which is not a concrete device platform).
+  return (PLATFORMS as readonly unknown[]).includes(value);
+}
+
 export function matchesPlatformSelector(
   platform: Platform,
   selector: PlatformSelector | undefined,