fix: reject unsupported launch args openings

Author: thymikee

src/commands/client-command-contracts.ts

@@ -81,7 +81,9 @@ export const clientCommandDefinitions = [
       surface: enumField(SURFACE_VALUES),
       activity: stringField('Android activity name.'),
       launchConsole: stringField('Launch console mode.'),
-      launchArgs: stringArrayField('iOS launch arguments forwarded verbatim to the app process.'),
+      launchArgs: stringArrayField(
+        'Launch arguments forwarded verbatim to the platform launch command.',
+      ),
       relaunch: booleanField('Force relaunch.'),
       saveScript: jsonSchemaField<boolean | string>({ oneOf: [booleanSchema(), stringSchema()] }),
       noRecord: booleanField('Do not record this action.'),

src/core/__tests__/dispatch-open.test.ts

@@ -20,8 +20,7 @@ vi.mock('../../platforms/ios/apps.ts', async (importOriginal) => {
 });
 
 vi.mock('../../platforms/android/app-lifecycle.ts', async (importOriginal) => {
-  const actual =
-    await importOriginal<typeof import('../../platforms/android/app-lifecycle.ts')>();
+  const actual = await importOriginal<typeof import('../../platforms/android/app-lifecycle.ts')>();
   return {
     ...actual,
     openAndroidApp: vi.fn(async () => {}),
@@ -58,6 +57,18 @@ test('dispatch open rejects URL as first argument when second URL is provided',
   );
 });
 
+test('dispatch open rejects launch arguments without an app target', async () => {
+  await assert.rejects(
+    () => dispatchCommand(IOS_SIMULATOR, 'open', [], undefined, { launchArgs: ['-Flag'] }),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
+      assert.match((error as AppError).message, /requires an app target/i);
+      return true;
+    },
+  );
+});
+
 test('dispatch open forwards Android launch arguments to openAndroidApp', async () => {
   const device: DeviceInfo = {
     platform: 'android',
@@ -79,6 +90,29 @@ test('dispatch open forwards Android launch arguments to openAndroidApp', async
   assert.deepEqual(optionsArg.launchArgs, ['--es', 'KEY', 'value']);
 });
 
+test('dispatch open rejects launch arguments on Linux', async () => {
+  const device: DeviceInfo = {
+    platform: 'linux',
+    id: 'linux-local',
+    name: 'Linux',
+    kind: 'device',
+    booted: true,
+  };
+
+  await assert.rejects(
+    () =>
+      dispatchCommand(device, 'open', ['org.example.App'], undefined, {
+        launchArgs: ['--fixture', 'demo'],
+      }),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'UNSUPPORTED_OPERATION');
+      assert.match((error as AppError).message, /Linux/i);
+      return true;
+    },
+  );
+});
+
 test('dispatch open clears Maestro iOS simulator state and launches once', async () => {
   const result = await dispatchCommand(IOS_SIMULATOR, 'open', ['com.example.app'], undefined, {
     clearAppState: true,

src/core/dispatch.ts

@@ -181,19 +181,26 @@ async function handleOpenCommand(
   const app = positionals[0];
   const url = positionals[1];
   const launchConsole = context?.launchConsole;
+  const launchArgs = context?.launchArgs;
   if (positionals.length > 2) {
     throw new AppError('INVALID_ARGS', 'open accepts at most two arguments: <app|url> [url]');
   }
   if (!app) {
     if (launchConsole) {
       throw new AppError('INVALID_ARGS', '--launch-console requires an app target');
     }
+    if (launchArgs && launchArgs.length > 0) {
+      throw new AppError('INVALID_ARGS', '--launch-args requires an app target');
+    }
     await interactor.openDevice();
     return { app: null, ...successText('Opened device') };
   }
   if (launchConsole && (device.platform !== 'ios' || device.kind !== 'simulator')) {
     throw new AppError('UNSUPPORTED_OPERATION', LAUNCH_CONSOLE_IOS_SIMULATOR_ONLY_MESSAGE);
   }
+  if (device.platform === 'linux' && launchArgs && launchArgs.length > 0) {
+    throw new AppError('UNSUPPORTED_OPERATION', '--launch-args is not supported on Linux.');
+  }
   if (url !== undefined) {
     if (isDeepLinkTarget(app)) {
       throw new AppError(
@@ -210,7 +217,7 @@ async function handleOpenCommand(
     await interactor.open(app, {
       activity: context?.activity,
       appBundleId: context?.appBundleId,
-      launchArgs: context?.launchArgs,
+      launchArgs,
       url,
     });
     return { app, url, ...successText(`Opened: ${app}`) };
@@ -237,7 +244,7 @@ async function handleOpenCommand(
     activity: context?.activity,
     appBundleId: context?.appBundleId,
     launchConsole,
-    launchArgs: context?.launchArgs,
+    launchArgs,
   });
   return { app, ...(launchConsole ? { launchConsole } : {}), ...successText(`Opened: ${app}`) };
 }

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

@@ -66,6 +66,24 @@ async function withMockedAdb(
   }
 }
 
+function androidOpenAdbScript(): string {
+  return [
+    '#!/bin/sh',
+    'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
+    'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
+    'if [ "$1" = "-s" ]; then',
+    '  shift',
+    '  shift',
+    'fi',
+    'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
+    '  echo "Status: ok"',
+    '  exit 0',
+    'fi',
+    'exit 0',
+    '',
+  ].join('\n');
+}
+
 test('parseUiHierarchy reads double-quoted Android node attributes', () => {
   const xml =
     '<hierarchy><node class="android.widget.TextView" text="Hello" content-desc="Greeting" resource-id="com.demo:id/title" bounds="[10,20][110,60]" clickable="true" enabled="true"/></hierarchy>';
@@ -1121,25 +1139,7 @@ test('installAndroidInstallablePath invalidates cached display-name package matc
 test('openAndroidApp default launch uses -p package flag', async () => {
   await withMockedAdb(
     'agent-device-android-open-default-',
-    [
-      '#!/bin/sh',
-      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'if [ "$1" = "-s" ]; then',
-      '  shift',
-      '  shift',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "list" ]; then',
-      '  echo "package:com.example.app"',
-      '  exit 0',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
-      '  echo "Status: ok"',
-      '  exit 0',
-      'fi',
-      'exit 0',
-      '',
-    ].join('\n'),
+    androidOpenAdbScript(),
     async ({ argsLogPath, device }) => {
       await openAndroidApp(device, 'com.example.app');
       const logged = await fs.readFile(argsLogPath, 'utf8');
@@ -1152,25 +1152,7 @@ test('openAndroidApp default launch uses -p package flag', async () => {
 test('openAndroidApp appends launchArgs to am start when launching by package', async () => {
   await withMockedAdb(
     'agent-device-android-open-launch-args-',
-    [
-      '#!/bin/sh',
-      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'if [ "$1" = "-s" ]; then',
-      '  shift',
-      '  shift',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "list" ]; then',
-      '  echo "package:com.example.app"',
-      '  exit 0',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
-      '  echo "Status: ok"',
-      '  exit 0',
-      'fi',
-      'exit 0',
-      '',
-    ].join('\n'),
+    androidOpenAdbScript(),
     async ({ argsLogPath, device }) => {
       await openAndroidApp(device, 'com.example.app', {
         launchArgs: ['--es', 'screen', 'home', '--ez', 'fresh', 'true'],
@@ -1184,88 +1166,36 @@ test('openAndroidApp appends launchArgs to am start when launching by package',
 test('openAndroidApp appends launchArgs to am start when activity override is set', async () => {
   await withMockedAdb(
     'agent-device-android-open-launch-args-activity-',
-    [
-      '#!/bin/sh',
-      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'if [ "$1" = "-s" ]; then',
-      '  shift',
-      '  shift',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
-      '  echo "Status: ok"',
-      '  exit 0',
-      'fi',
-      'exit 0',
-      '',
-    ].join('\n'),
+    androidOpenAdbScript(),
     async ({ argsLogPath, device }) => {
       await openAndroidApp(device, 'com.example.app', {
         activity: '.MainActivity',
         launchArgs: ['--es', 'mode', 'debug'],
       });
       const logged = await fs.readFile(argsLogPath, 'utf8');
-      assert.match(
-        logged,
-        /-n\ncom\.example\.app\/\.MainActivity\n--es\nmode\ndebug/,
-      );
+      assert.match(logged, /-n\ncom\.example\.app\/\.MainActivity\n--es\nmode\ndebug/);
     },
   );
 });
 
 test('openAndroidApp appends launchArgs to am start for deep link URL opens', async () => {
   await withMockedAdb(
     'agent-device-android-open-launch-args-url-',
-    [
-      '#!/bin/sh',
-      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'if [ "$1" = "-s" ]; then',
-      '  shift',
-      '  shift',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
-      '  echo "Status: ok"',
-      '  exit 0',
-      'fi',
-      'exit 0',
-      '',
-    ].join('\n'),
+    androidOpenAdbScript(),
     async ({ argsLogPath, device }) => {
       await openAndroidApp(device, 'myapp://item/42', {
         launchArgs: ['--es', 'ref', 'campaign'],
       });
       const logged = await fs.readFile(argsLogPath, 'utf8');
-      assert.match(
-        logged,
-        /-d\nmyapp:\/\/item\/42\n--es\nref\ncampaign/,
-      );
+      assert.match(logged, /-d\nmyapp:\/\/item\/42\n--es\nref\ncampaign/);
     },
   );
 });
 
 test('openAndroidApp appends launchArgs to am start for app-bound URL opens', async () => {
   await withMockedAdb(
     'agent-device-android-open-launch-args-app-bound-url-',
-    [
-      '#!/bin/sh',
-      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'if [ "$1" = "-s" ]; then',
-      '  shift',
-      '  shift',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "list" ]; then',
-      '  echo "package:com.example.app"',
-      '  exit 0',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
-      '  echo "Status: ok"',
-      '  exit 0',
-      'fi',
-      'exit 0',
-      '',
-    ].join('\n'),
+    androidOpenAdbScript(),
     async ({ argsLogPath, device }) => {
       await openAndroidApp(device, 'com.example.app', {
         url: 'https://example.com/promo',
@@ -1283,25 +1213,7 @@ test('openAndroidApp appends launchArgs to am start for app-bound URL opens', as
 test('openAndroidApp shell-quotes launchArgs containing JSON or shell metacharacters', async () => {
   await withMockedAdb(
     'agent-device-android-open-launch-args-quoting-',
-    [
-      '#!/bin/sh',
-      'printf "__CMD__\\n" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'printf "%s\\n" "$@" >> "$AGENT_DEVICE_TEST_ARGS_FILE"',
-      'if [ "$1" = "-s" ]; then',
-      '  shift',
-      '  shift',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "pm" ] && [ "$3" = "list" ]; then',
-      '  echo "package:com.example.app"',
-      '  exit 0',
-      'fi',
-      'if [ "$1" = "shell" ] && [ "$2" = "am" ] && [ "$3" = "start" ]; then',
-      '  echo "Status: ok"',
-      '  exit 0',
-      'fi',
-      'exit 0',
-      '',
-    ].join('\n'),
+    androidOpenAdbScript(),
     async ({ argsLogPath, device }) => {
       // Value contains characters the device shell would otherwise re-interpret:
       // `#` (comment), `;` (statement separator), `&` (background), `*` (glob),
@@ -1313,10 +1225,7 @@ test('openAndroidApp shell-quotes launchArgs containing JSON or shell metacharac
       const logged = await fs.readFile(argsLogPath, 'utf8');
       // `--es` and the safe extra key pass through unquoted; the JSON value
       // is single-quoted so `adb shell` re-tokenisation preserves it.
-      assert.match(
-        logged,
-        /--es\nEXTRA_CONFIG\n'\{"a":"x #y;z&w","b":"path\/\*"\}'/,
-      );
+      assert.match(logged, /--es\nEXTRA_CONFIG\n'\{"a":"x #y;z&w","b":"path\/\*"\}'/);
     },
   );
 });

src/platforms/android/app-lifecycle.ts

@@ -433,10 +433,7 @@ async function openAndroidPackageActivity(
     ? activity
     : `${packageName}/${activity.startsWith('.') ? activity : `.${activity}`}`;
   try {
-    await runAndroidAdb(
-      device,
-      buildAndroidActivityLaunchArgs(component, launchCategory, options),
-    );
+    await runAndroidAdb(device, buildAndroidActivityLaunchArgs(component, launchCategory, options));
   } catch (error) {
     await maybeRethrowAndroidMissingPackageError(device, packageName, error);
     throw error;
@@ -481,10 +478,7 @@ async function openAndroidPackage(
       stderr: primaryResult.stderr,
     });
   }
-  await runAndroidAdb(
-    device,
-    buildAndroidActivityLaunchArgs(component, launchCategory, options),
-  );
+  await runAndroidAdb(device, buildAndroidActivityLaunchArgs(component, launchCategory, options));
 }
 
 function buildAndroidActivityLaunchArgs(

src/utils/__tests__/args.test.ts

@@ -331,6 +331,7 @@ test('usageForCommand documents open --launch-args', () => {
   if (help === null) throw new Error('Expected open help text');
   assert.match(help, /--launch-args <arg>/);
   assert.match(help, /forwarded verbatim/);
+  assert.match(help, /Linux and macOS reject the flag/);
 });
 
 test('parseArgs accepts install-from-source GitHub Actions artifact flag', () => {

src/utils/cli-flags.ts

@@ -506,7 +506,7 @@ const FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     multiple: true,
     usageLabel: '--launch-args <arg>',
     usageDescription:
-      'open: repeatable launch argument forwarded verbatim to the iOS launch command (simctl launch positional args for simulators; devicectl process launch positional args for devices, after `--`). Currently supported only on iOS; Android and macOS reject the flag.',
+      'open: repeatable launch argument forwarded verbatim to the platform launch command (iOS app process args; Android adb shell am start args). Linux and macOS reject the flag.',
   },
   {
     key: 'header',