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

@@ -1205,10 +1205,7 @@ test('openAndroidApp appends launchArgs to am start when activity override is se
         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/);
     },
   );
 });
@@ -1236,10 +1233,7 @@ test('openAndroidApp appends launchArgs to am start for deep link URL opens', as
         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/);
     },
   );
 });
@@ -1313,10 +1307,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',