fix: enforce archive release channel qualifier behavior

Author: leoafarias

lib/src/services/archive_service.dart

@@ -14,6 +14,7 @@ import 'releases_service/releases_client.dart';
 
 class ArchiveService extends ContextualService {
   static const _supportedArchiveChannels = {'stable', 'beta', 'dev'};
+  static const _supportedArchiveReleaseQualifiers = {'beta', 'dev'};
 
   const ArchiveService(super.context);
 
@@ -54,6 +55,36 @@ class ArchiveService extends ContextualService {
     }
 
     if (version.isRelease) {
+      final releaseQualifier = version.releaseChannel?.name;
+      if (releaseQualifier != null) {
+        if (releaseQualifier == FlutterChannel.stable.name) {
+          throw const AppException(
+            'Archive installation does not support the "@stable" qualifier. '
+            'Use the version without a channel suffix, or use @beta/@dev.',
+          );
+        }
+
+        if (!_supportedArchiveReleaseQualifiers.contains(releaseQualifier)) {
+          throw AppException(
+            'Archive installation supports release qualifiers only for '
+            '@beta and @dev. Received "@$releaseQualifier".',
+          );
+        }
+
+        final channelReleases =
+            await releaseClient.getChannelReleases(releaseQualifier);
+        for (final release in channelReleases) {
+          if (release.version == version.version) {
+            return release;
+          }
+        }
+
+        throw AppException(
+          'Release ${version.version} could not be found in the '
+          '$releaseQualifier channel releases metadata.',
+        );
+      }
+
       final release = await releaseClient.getReleaseByVersion(version.version);
       if (release == null) {
         throw AppException(

test/services/archive_service_test.dart

@@ -200,6 +200,64 @@ void main() {
           ),
         );
       });
+
+      test('uses channel-specific lookup for @beta qualifiers', () async {
+        final version = FlutterVersion.parse('2.2.2@beta');
+
+        when(() => mockReleaseClient.getChannelReleases('beta')).thenAnswer(
+          (_) async => [],
+        );
+
+        await expectLater(
+          archiveService.install(version, tempDir),
+          throwsA(
+            isA<AppException>().having(
+              (e) => e.message,
+              'message',
+              contains('beta channel releases metadata'),
+            ),
+          ),
+        );
+
+        verify(() => mockReleaseClient.getChannelReleases('beta')).called(1);
+        verifyNever(() => mockReleaseClient.getReleaseByVersion(any()));
+      });
+
+      test('rejects @stable qualifier for release versions', () async {
+        final version = FlutterVersion.parse('2.2.2@stable');
+
+        expect(
+          () => archiveService.install(version, tempDir),
+          throwsA(
+            isA<AppException>().having(
+              (e) => e.message,
+              'message',
+              contains('does not support the "@stable" qualifier'),
+            ),
+          ),
+        );
+
+        verifyNever(() => mockReleaseClient.getChannelReleases(any()));
+        verifyNever(() => mockReleaseClient.getReleaseByVersion(any()));
+      });
+
+      test('rejects unsupported release qualifiers like @master', () async {
+        final version = FlutterVersion.parse('2.2.2@master');
+
+        expect(
+          () => archiveService.install(version, tempDir),
+          throwsA(
+            isA<AppException>().having(
+              (e) => e.message,
+              'message',
+              contains('@beta and @dev'),
+            ),
+          ),
+        );
+
+        verifyNever(() => mockReleaseClient.getChannelReleases(any()));
+        verifyNever(() => mockReleaseClient.getReleaseByVersion(any()));
+      });
     });
 
     group('archive download and extraction failures', () {