feat(shorebird_cli): add --track to shorebird preview (#3092)

packages/shorebird_cli/lib/src/commands/patch/patch_command.dart

@@ -75,7 +75,7 @@ class PatchCommand extends ShorebirdCommand {
         help: 'The product flavor to use when building the app.',
       )
       ..addOption(
-        'release-version',
+        CommonArguments.releaseVersionArg.name,
         help: '''
 The version of the associated release (e.g. "1.0.0").
 If you are building an xcframework or aar, this number needs to match the host app's release version.

packages/shorebird_cli/lib/src/commands/preview_command.dart

@@ -89,7 +89,15 @@ This is only applicable when previewing Android releases.''',
       ..addFlag(
         'staging',
         negatable: false,
-        help: 'Preview the release on the staging environment.',
+        help:
+            '[DEPRECATED] Preview the release on the staging environment. Use --track=staging instead.',
+        hide: true,
+      )
+      ..addOption(
+        'track',
+        allowed: DeploymentTrack.values.map((v) => v.channel),
+        help: 'The track to preview.',
+        defaultsTo: DeploymentTrack.stable.channel,
       );
   }
 
@@ -110,6 +118,12 @@ This is only applicable when previewing Android releases.''',
   @override
   String get description => 'Preview a specific release on a device.';
 
+  /// The deployment track to publish the patch to.
+  DeploymentTrack get track {
+    final channel = results['track'] as String;
+    return DeploymentTrack.values.firstWhere((t) => t.channel == channel);
+  }
+
   @override
   Future<int> run() async {
     // TODO(bryanoltman): check preview target and run either
@@ -122,6 +136,13 @@ This is only applicable when previewing Android releases.''',
       return error.exitCode.code;
     }
 
+    if (results.wasParsed('staging')) {
+      logger.err(
+        '''The --staging flag is deprecated and will be removed in a future release. Use --track=staging instead.''',
+      );
+      return ExitCode.usage.code;
+    }
+
     final shorebirdYaml = shorebirdEnv.getShorebirdYaml();
     final String? appId;
 
@@ -249,8 +270,6 @@ This is only applicable when previewing Android releases.''',
     }
 
     final deviceId = results['device-id'] as String?;
-    final isStaging = results['staging'] == true;
-    final track = isStaging ? DeploymentTrack.staging : DeploymentTrack.stable;
 
     return switch (releasePlatform) {
       ReleasePlatform.android => installAndLaunchAndroid(

packages/shorebird_cli/test/src/commands/preview_command_test.dart

@@ -228,6 +228,11 @@ void main() {
       when(() => argResults['app-id']).thenReturn(appId);
       when(() => argResults['release-version']).thenReturn(releaseVersion);
       when(() => argResults['staging']).thenReturn(false);
+      when(
+        () => argResults['track'],
+      ).thenReturn(DeploymentTrack.stable.channel);
+      when(() => argResults.wasParsed(any())).thenReturn(true);
+      when(() => argResults.wasParsed('staging')).thenReturn(false);
       when(() => auth.isAuthenticated).thenReturn(true);
       when(() => cache.getPreviewDirectory(any())).thenReturn(previewDirectory);
       when(
@@ -272,6 +277,27 @@ void main() {
       when(() => platform.isWindows).thenReturn(false);
     });
 
+    group('when --staging is passed', () {
+      setUp(() {
+        when(() => argResults.wasParsed('staging')).thenReturn(true);
+      });
+
+      test(
+        '''warns that staging flag will be deprecated and exits with usage code''',
+        () async {
+          await expectLater(
+            runWithOverrides(command.run),
+            completion(equals(ExitCode.usage.code)),
+          );
+          verify(
+            () => logger.err(
+              '''The --staging flag is deprecated and will be removed in a future release. Use --track=staging instead.''',
+            ),
+          ).called(1);
+        },
+      );
+    });
+
     group('when validation fails', () {
       final exception = ValidationFailedException();
       setUp(() {
@@ -1606,7 +1632,9 @@ channel: ${track.channel}
       group('when install/launch succeeds (staging)', () {
         late File shorebirdYaml;
         setUp(() {
-          when(() => argResults['staging']).thenReturn(true);
+          when(
+            () => argResults['track'],
+          ).thenReturn(DeploymentTrack.staging.channel);
           shorebirdYaml =
               File(
                   p.join(
@@ -2142,7 +2170,9 @@ channel: ${DeploymentTrack.staging.channel}
       group('staging', () {
         late File shorebirdYaml;
         setUp(() {
-          when(() => argResults['staging']).thenReturn(true);
+          when(
+            () => argResults['track'],
+          ).thenReturn(DeploymentTrack.staging.channel);
           shorebirdYaml = setupMacosShorebirdYaml();
         });