@capawesome/cli 4.21.0 → 4.22.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [4.22.0](https://github.com/capawesome-team/cli/compare/v4.21.0...v4.22.0) (2026-09-24)
+
+
+### Features
+
+* **apps:** add `--app` flag to download the simulator app bundle ([#225](https://github.com/capawesome-team/cli/issues/225)) ([ee40c92](https://github.com/capawesome-team/cli/commit/ee40c92f2d73e878b7fa1f9089cdf9420daa2ae4))
+* **apps:** add the `macos-golden-gate` build stack ([#226](https://github.com/capawesome-team/cli/issues/226)) ([23d4d39](https://github.com/capawesome-team/cli/commit/23d4d3961a752a6bf087f86aa9e93805a9026647))
+* **apps:** download build artifacts by form factor ([#216](https://github.com/capawesome-team/cli/issues/216)) ([cd06192](https://github.com/capawesome-team/cli/commit/cd061920c69ac796e271a00141ec2284cc0ae526))
+
 ## [4.21.0](https://github.com/capawesome-team/cli/compare/v4.20.0...v4.21.0) (2026-09-22)
 
 

package/dist/commands/apps/automations/create.js

@@ -28,8 +28,8 @@ export default defineCommand({
             .optional()
             .describe('The platform for the build. Supported values are `android`, `ios`, and `web`.'),
         stack: z
-            .enum(['macos-sequoia', 'macos-tahoe'], {
-            message: 'Build stack must be either `macos-sequoia` or `macos-tahoe`.',
+            .enum(['macos-sequoia', 'macos-tahoe', 'macos-golden-gate'], {
+            message: 'Build stack must be one of `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`.',
         })
             .optional()
             .describe('The build stack to use for the build process.'),

package/dist/commands/apps/automations/update.js

@@ -45,8 +45,8 @@ export default defineCommand({
             .optional()
             .describe('The platform for the build. Supported values are `android`, `ios`, and `web`.'),
         stack: z
-            .enum(['macos-sequoia', 'macos-tahoe'], {
-            message: 'Build stack must be either `macos-sequoia` or `macos-tahoe`.',
+            .enum(['macos-sequoia', 'macos-tahoe', 'macos-golden-gate'], {
+            message: 'Build stack must be one of `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`.',
         })
             .optional()
             .describe('The build stack to use for the build process.'),

package/dist/commands/apps/builds/create.js

@@ -5,6 +5,7 @@ import appCertificatesService from '../../../services/app-certificates.js';
 import appConfigurationsService from '../../../services/app-configurations.js';
 import appEnvironmentsService from '../../../services/app-environments.js';
 import appsService from '../../../services/apps.js';
+import { APP_BUILD_ARTIFACT_FORM_FACTORS, APP_BUILD_ARTIFACT_TYPES_BY_PLATFORM, handleAppBuildArtifactDownload, } from '../../../utils/app-build-artifacts.js';
 import { getAppBuildShareUrls } from '../../../utils/app-build-shares.js';
 import { parseKeyValuePairs } from '../../../utils/app-environments.js';
 import { withAuth } from '../../../utils/auth.js';
@@ -33,6 +34,10 @@ export default defineCommand({
             .union([z.boolean(), z.string()])
             .optional()
             .describe('Download the generated APK file (Android only). Optionally provide a file path.'),
+        app: z
+            .union([z.boolean(), z.string()])
+            .optional()
+            .describe('Download the generated APP file, a zipped `.app` bundle (iOS simulator builds only). Optionally provide a file path.'),
         appId: z
             .uuid({
             message: 'App ID must be a UUID.',
@@ -52,6 +57,12 @@ export default defineCommand({
             .boolean()
             .optional()
             .describe('Request an AI-powered failure summary (Capawesome Cloud Assist) if the build fails.'),
+        formFactor: z
+            .enum(APP_BUILD_ARTIFACT_FORM_FACTORS, {
+            message: 'Invalid form factor. Must be one of `mobile`, `watch`, `tv`, or `automotive`.',
+        })
+            .optional()
+            .describe('The form factor of the Android artifact to download with `--apk` or `--aab`. Supported values are `mobile`, `watch`, `tv`, and `automotive`. Without it, the first artifact in the order `mobile`, `watch`, `tv`, `automotive` is downloaded. The build always includes every application module.'),
         gitRef: z.string().optional().describe('The Git reference (branch, tag, or commit SHA) to build.'),
         ipa: z
             .union([z.boolean(), z.string()])
@@ -79,8 +90,8 @@ export default defineCommand({
             .optional()
             .describe('Number of days until the share link expires. Requires --share.'),
         stack: z
-            .enum(['macos-sequoia', 'macos-tahoe'], {
-            message: 'Build stack must be either `macos-sequoia` or `macos-tahoe`.',
+            .enum(['macos-sequoia', 'macos-tahoe', 'macos-golden-gate'], {
+            message: 'Build stack must be one of `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`.',
         })
             .optional()
             .describe('The build stack to use for the build process.'),
@@ -106,8 +117,8 @@ export default defineCommand({
     action: withAuth(async (options) => {
         let { appId, platform, type, gitRef, environment, certificate, configuration, json, stack, path: sourcePath, url, } = options;
         // Validate that detached flag cannot be used with artifact flags
-        if (options.detached && (options.apk || options.aab || options.ipa || options.zip)) {
-            consola.error('The --detached flag cannot be used with --apk, --aab, --ipa, or --zip flags.');
+        if (options.detached && (options.apk || options.aab || options.ipa || options.app || options.zip)) {
+            consola.error('The --detached flag cannot be used with --apk, --aab, --ipa, --app, or --zip flags.');
             process.exit(1);
         }
         // Validate that detached flag cannot be used with channel or destination
@@ -411,41 +422,18 @@ export default defineCommand({
             consola.success('Build completed successfully.');
             console.log();
             // Download artifacts if flags are set
-            if (options.apk && platform === 'android') {
-                await handleArtifactDownload({
-                    appId,
-                    buildId: response.id,
-                    buildArtifacts: appBuild.appBuildArtifacts,
-                    artifactType: 'apk',
-                    filePath: typeof options.apk === 'string' ? options.apk : undefined,
-                });
-            }
-            if (options.aab && platform === 'android') {
-                await handleArtifactDownload({
-                    appId,
-                    buildId: response.id,
-                    buildArtifacts: appBuild.appBuildArtifacts,
-                    artifactType: 'aab',
-                    filePath: typeof options.aab === 'string' ? options.aab : undefined,
-                });
-            }
-            if (options.ipa && platform === 'ios') {
-                await handleArtifactDownload({
-                    appId,
-                    buildId: response.id,
-                    buildArtifacts: appBuild.appBuildArtifacts,
-                    artifactType: 'ipa',
-                    filePath: typeof options.ipa === 'string' ? options.ipa : undefined,
-                });
-            }
-            if (options.zip && platform === 'web') {
-                await handleArtifactDownload({
-                    appId,
-                    buildId: response.id,
-                    buildArtifacts: appBuild.appBuildArtifacts,
-                    artifactType: 'zip',
-                    filePath: typeof options.zip === 'string' ? options.zip : undefined,
-                });
+            for (const artifactType of APP_BUILD_ARTIFACT_TYPES_BY_PLATFORM[platform]) {
+                const option = options[artifactType];
+                if (option) {
+                    await handleAppBuildArtifactDownload({
+                        appId,
+                        buildId: response.id,
+                        buildArtifacts: appBuild.appBuildArtifacts,
+                        artifactType,
+                        formFactor: options.formFactor,
+                        filePath: typeof option === 'string' ? option : undefined,
+                    });
+                }
             }
             // Create a public share link if requested
             let appBuildShare;
@@ -500,45 +488,3 @@ export default defineCommand({
         }
     }),
 });
-/**
- * Download a build artifact (APK, AAB, IPA, or ZIP).
- */
-const handleArtifactDownload = async (options) => {
-    const { appId, buildId, buildArtifacts, artifactType, filePath } = options;
-    try {
-        const artifactTypeUpper = artifactType.toUpperCase();
-        consola.start(`Downloading ${artifactTypeUpper}...`);
-        // Find the artifact
-        const artifact = buildArtifacts?.find((artifact) => artifact.type === artifactType);
-        if (!artifact) {
-            consola.warn(`No ${artifactTypeUpper} artifact found for this build.`);
-            return;
-        }
-        if (artifact.status !== 'ready') {
-            consola.warn(`${artifactTypeUpper} artifact is not ready (status: ${artifact.status}).`);
-            return;
-        }
-        // Download the artifact
-        const artifactData = await appBuildsService.downloadArtifact({
-            appId,
-            appBuildId: buildId,
-            artifactId: artifact.id,
-        });
-        // Determine the file path
-        let outputPath;
-        if (filePath) {
-            // Use provided path (can be relative or absolute)
-            outputPath = path.resolve(filePath);
-        }
-        else {
-            // Default to current working directory with build ID as filename
-            outputPath = path.resolve(`${buildId}.${artifactType}`);
-        }
-        // Save the file
-        await fs.writeFile(outputPath, Buffer.from(artifactData));
-        consola.success(`${artifactTypeUpper} downloaded successfully: ${outputPath}`);
-    }
-    catch (error) {
-        consola.error(`Failed to download ${artifactType.toUpperCase()}:`, error);
-    }
-};

package/dist/commands/apps/builds/create.test.js

@@ -2,7 +2,10 @@ import { DEFAULT_API_BASE_URL, DEFAULT_CONSOLE_BASE_URL } from '../../../config/
 import authorizationService from '../../../services/authorization-service.js';
 import userConfig from '../../../utils/user-config.js';
 import consola from 'consola';
+import fs from 'fs/promises';
 import nock from 'nock';
+import os from 'os';
+import path from 'path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import createCommand from './create.js';
 // Mock dependencies
@@ -77,6 +80,40 @@ describe('apps-builds-create', () => {
             appBuildShare: { id: shareId, qrCodeUrl, webUrl, expiresAt: null },
         }, null, 2));
     });
+    it('should download the app artifact of an iOS simulator build with --app', async () => {
+        const outputDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'capawesome-cli-create-'));
+        const outputPath = path.join(outputDirectory, 'simulator.app.zip');
+        const artifactId = 'artifact-1';
+        const artifactContent = 'zipped app bundle';
+        const options = { appId, platform: 'ios', type: 'simulator', gitRef: 'main', app: outputPath };
+        const buildScope = nock(DEFAULT_API_BASE_URL)
+            .post(`/v1/apps/${appId}/builds`, (body) => body.platform === 'ios' && body.type === 'simulator')
+            .reply(201, { id: buildId, jobId: 'job-1', numberAsString: '42' });
+        const findScope = nock(DEFAULT_API_BASE_URL)
+            .get(`/v1/apps/${appId}/builds/${buildId}`)
+            .query({ relations: 'appBuildArtifacts' })
+            .reply(200, {
+            id: buildId,
+            appBuildArtifacts: [
+                { id: 'artifact-0', status: 'ready', type: 'xcarchive' },
+                { formFactor: 'mobile', id: artifactId, status: 'ready', type: 'app' },
+            ],
+        });
+        const downloadScope = nock(DEFAULT_API_BASE_URL)
+            .get(`/v1/apps/${appId}/builds/${buildId}/artifacts/${artifactId}/download`)
+            .reply(200, artifactContent);
+        try {
+            await createCommand.action(options, undefined);
+            expect(buildScope.isDone()).toBe(true);
+            expect(findScope.isDone()).toBe(true);
+            expect(downloadScope.isDone()).toBe(true);
+            expect(await fs.readFile(outputPath, 'utf-8')).toBe(artifactContent);
+            expect(mockConsola.success).toHaveBeenCalledWith(`APP downloaded successfully: ${outputPath}`);
+        }
+        finally {
+            await fs.rm(outputDirectory, { force: true, recursive: true });
+        }
+    });
     it('should reject --share combined with --detached', async () => {
         const options = { appId, platform: 'web', gitRef: 'main', share: true, detached: true };
         await expect(createCommand.action(options, undefined)).rejects.toThrow('Process exited with code 1');

package/dist/commands/apps/builds/download.js

@@ -1,12 +1,17 @@
 import appBuildsService from '../../../services/app-builds.js';
+import { APP_BUILD_ARTIFACT_FORM_FACTORS, APP_BUILD_ARTIFACT_LABELS, APP_BUILD_ARTIFACT_TYPES_BY_PLATFORM, handleAppBuildArtifactDownload, } from '../../../utils/app-build-artifacts.js';
 import { withAuth } from '../../../utils/auth.js';
+import { isInteractive } from '../../../utils/environment.js';
 import { prompt, promptAppSelection, promptOrganizationSelection } from '../../../utils/prompt.js';
 import consola from 'consola';
-import fs from 'fs/promises';
-import path from 'path';
-import { isInteractive } from '../../../utils/environment.js';
 import { z } from 'zod';
 import { defineCommand, defineOptions } from 'zodline';
+const ARTIFACT_TYPES = ['apk', 'aab', 'ipa', 'app', 'zip'];
+const PLATFORM_LABELS = {
+    android: 'Android',
+    ios: 'iOS',
+    web: 'Web',
+};
 export default defineCommand({
     description: 'Download an app build.',
     options: defineOptions(z.object({
@@ -22,22 +27,32 @@ export default defineCommand({
         })
             .optional()
             .describe('Build ID to download.'),
+        formFactor: z
+            .enum(APP_BUILD_ARTIFACT_FORM_FACTORS, {
+            message: 'Invalid form factor. Must be one of `mobile`, `watch`, `tv`, or `automotive`.',
+        })
+            .optional()
+            .describe('The form factor of the Android artifact to download. Supported values are `mobile`, `watch`, `tv`, and `automotive`. Without it, the first artifact in the order `mobile`, `watch`, `tv`, `automotive` is downloaded.'),
         apk: z
             .union([z.boolean(), z.string()])
             .optional()
-            .describe('Download the APK artifact. Optionally provide a file path.'),
+            .describe('Download the APK artifact (Android only). Optionally provide a file path.'),
         aab: z
             .union([z.boolean(), z.string()])
             .optional()
-            .describe('Download the AAB artifact. Optionally provide a file path.'),
+            .describe('Download the AAB artifact (Android only). Optionally provide a file path.'),
         ipa: z
             .union([z.boolean(), z.string()])
             .optional()
-            .describe('Download the IPA artifact. Optionally provide a file path.'),
+            .describe('Download the IPA artifact (iOS only). Optionally provide a file path.'),
+        app: z
+            .union([z.boolean(), z.string()])
+            .optional()
+            .describe('Download the APP artifact, a zipped `.app` bundle (iOS simulator builds only). Optionally provide a file path.'),
         zip: z
             .union([z.boolean(), z.string()])
             .optional()
-            .describe('Download the ZIP artifact. Optionally provide a file path.'),
+            .describe('Download the ZIP artifact (Web only). Optionally provide a file path.'),
     })),
     action: withAuth(async (options) => {
         let { appId, buildId } = options;
@@ -74,156 +89,54 @@ export default defineCommand({
                 process.exit(1);
             }
         }
-        // Fetch the build details to get the job ID
         const build = await appBuildsService.findOne({ appId, appBuildId: buildId, relations: 'appBuildArtifacts,job' });
         if (build.job?.status !== 'succeeded') {
             consola.error('The build has not succeeded yet. Cannot download artifacts for incomplete builds.');
             process.exit(1);
         }
-        // Validate platform-specific artifact flags
-        if (build.platform === 'android' && options.ipa) {
-            consola.error('Cannot download IPA artifact for an Android build.');
-            process.exit(1);
-        }
-        if (build.platform === 'ios' && (options.apk || options.aab)) {
-            consola.error('Cannot download APK or AAB artifacts for an iOS build.');
-            process.exit(1);
-        }
-        if (build.platform === 'web' && (options.apk || options.aab || options.ipa)) {
-            consola.error('Cannot download APK, AAB, or IPA artifacts for a Web build.');
+        // Reject artifact flags that do not exist for the build's platform
+        const supportedArtifactTypes = APP_BUILD_ARTIFACT_TYPES_BY_PLATFORM[build.platform];
+        const requestedArtifactTypes = ARTIFACT_TYPES.filter((artifactType) => options[artifactType]);
+        const unsupportedArtifactType = requestedArtifactTypes.find((artifactType) => !supportedArtifactTypes.includes(artifactType));
+        if (unsupportedArtifactType) {
+            consola.error(`The ${APP_BUILD_ARTIFACT_LABELS[unsupportedArtifactType]} artifact is not available for ${PLATFORM_LABELS[build.platform]} builds.`);
             process.exit(1);
         }
-        // Determine which artifacts to download
-        let downloadApk = options.apk;
-        let downloadAab = options.aab;
-        let downloadIpa = options.ipa;
-        let downloadZip = options.zip;
         // Prompt for artifact types if none were provided
-        if (!downloadApk && !downloadAab && !downloadIpa && !downloadZip) {
+        let artifactTypesToDownload = requestedArtifactTypes;
+        if (artifactTypesToDownload.length === 0) {
             if (!isInteractive()) {
-                consola.error('You must specify at least one artifact type (--apk, --aab, --ipa, or --zip) when running in non-interactive environment.');
+                consola.error('You must specify at least one artifact type (--apk, --aab, --ipa, --app, or --zip) when running in non-interactive environment.');
                 process.exit(1);
             }
-            // Get available artifact types from the build
-            const availableArtifacts = build.appBuildArtifacts?.filter((artifact) => artifact.status === 'ready').map((artifact) => artifact.type) ||
-                [];
-            if (availableArtifacts.length === 0) {
+            const availableArtifactTypes = supportedArtifactTypes.filter((artifactType) => build.appBuildArtifacts?.some((artifact) => artifact.type === artifactType && artifact.status === 'ready'));
+            if (availableArtifactTypes.length === 0) {
                 consola.error('No artifacts available for download.');
                 process.exit(1);
             }
-            // Create options based on available artifacts and platform
-            const artifactOptions = [];
-            if (build.platform === 'android') {
-                if (availableArtifacts.includes('apk')) {
-                    artifactOptions.push({ label: 'APK', value: 'apk' });
-                }
-                if (availableArtifacts.includes('aab')) {
-                    artifactOptions.push({ label: 'AAB', value: 'aab' });
-                }
-            }
-            else if (build.platform === 'ios') {
-                if (availableArtifacts.includes('ipa')) {
-                    artifactOptions.push({ label: 'IPA', value: 'ipa' });
-                }
-            }
-            else if (build.platform === 'web') {
-                if (availableArtifacts.includes('zip')) {
-                    artifactOptions.push({ label: 'ZIP', value: 'zip' });
-                }
-            }
             // @ts-ignore wait till https://github.com/unjs/consola/pull/280 is merged
-            const selectedArtifacts = await prompt('Which artifact type(s) do you want to download:', {
+            artifactTypesToDownload = await prompt('Which artifact type(s) do you want to download:', {
                 type: 'multiselect',
-                options: artifactOptions,
+                options: availableArtifactTypes.map((artifactType) => ({
+                    label: APP_BUILD_ARTIFACT_LABELS[artifactType],
+                    value: artifactType,
+                })),
             });
-            if (!selectedArtifacts || selectedArtifacts.length === 0) {
+            if (!artifactTypesToDownload || artifactTypesToDownload.length === 0) {
                 consola.error('You must select at least one artifact type to download.');
                 process.exit(1);
             }
-            // Set flags based on selection
-            downloadApk = selectedArtifacts.includes('apk');
-            downloadAab = selectedArtifacts.includes('aab');
-            downloadIpa = selectedArtifacts.includes('ipa');
-            downloadZip = selectedArtifacts.includes('zip');
-        }
-        // Download artifacts if flags are set
-        if (downloadApk) {
-            await handleArtifactDownload({
-                appId,
-                buildId: buildId,
-                buildArtifacts: build.appBuildArtifacts,
-                artifactType: 'apk',
-                filePath: typeof options.apk === 'string' ? options.apk : undefined,
-            });
-        }
-        if (downloadAab) {
-            await handleArtifactDownload({
-                appId,
-                buildId: buildId,
-                buildArtifacts: build.appBuildArtifacts,
-                artifactType: 'aab',
-                filePath: typeof options.aab === 'string' ? options.aab : undefined,
-            });
-        }
-        if (downloadIpa) {
-            await handleArtifactDownload({
-                appId,
-                buildId: buildId,
-                buildArtifacts: build.appBuildArtifacts,
-                artifactType: 'ipa',
-                filePath: typeof options.ipa === 'string' ? options.ipa : undefined,
-            });
         }
-        if (downloadZip) {
-            await handleArtifactDownload({
+        for (const artifactType of artifactTypesToDownload) {
+            const option = options[artifactType];
+            await handleAppBuildArtifactDownload({
                 appId,
-                buildId: buildId,
+                buildId,
                 buildArtifacts: build.appBuildArtifacts,
-                artifactType: 'zip',
-                filePath: typeof options.zip === 'string' ? options.zip : undefined,
+                artifactType,
+                formFactor: options.formFactor,
+                filePath: typeof option === 'string' ? option : undefined,
             });
         }
     }),
 });
-/**
- * Download a build artifact (APK, AAB, IPA, or ZIP).
- */
-const handleArtifactDownload = async (options) => {
-    const { appId, buildId, buildArtifacts, artifactType, filePath } = options;
-    try {
-        const artifactTypeUpper = artifactType.toUpperCase();
-        consola.start(`Downloading ${artifactTypeUpper}...`);
-        // Find the artifact
-        const artifact = buildArtifacts?.find((artifact) => artifact.type === artifactType);
-        if (!artifact) {
-            consola.warn(`No ${artifactTypeUpper} artifact found for this build.`);
-            return;
-        }
-        if (artifact.status !== 'ready') {
-            consola.warn(`${artifactTypeUpper} artifact is not ready (status: ${artifact.status}).`);
-            return;
-        }
-        // Download the artifact
-        const artifactData = await appBuildsService.downloadArtifact({
-            appId,
-            appBuildId: buildId,
-            artifactId: artifact.id,
-        });
-        // Determine the file path
-        let outputPath;
-        if (filePath) {
-            // Use provided path (can be relative or absolute)
-            outputPath = path.resolve(filePath);
-        }
-        else {
-            // Default to current working directory with build ID as filename
-            outputPath = path.resolve(`${buildId}.${artifactType}`);
-        }
-        // Save the file
-        await fs.writeFile(outputPath, Buffer.from(artifactData));
-        consola.success(`${artifactTypeUpper} downloaded successfully: ${outputPath}`);
-    }
-    catch (error) {
-        consola.error(`Failed to download ${artifactType.toUpperCase()}:`, error);
-    }
-};

package/dist/commands/apps/builds/download.test.js

@@ -0,0 +1,85 @@
+import { DEFAULT_API_BASE_URL } from '../../../config/consts.js';
+import authorizationService from '../../../services/authorization-service.js';
+import userConfig from '../../../utils/user-config.js';
+import consola from 'consola';
+import fs from 'fs/promises';
+import nock from 'nock';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import downloadCommand from './download.js';
+vi.mock('@/utils/user-config.js');
+vi.mock('@/utils/prompt.js');
+vi.mock('@/services/authorization-service.js');
+vi.mock('consola');
+vi.mock('@/utils/environment.js', () => ({
+    isInteractive: () => false,
+}));
+describe('apps-builds-download', () => {
+    const mockUserConfig = vi.mocked(userConfig);
+    const mockAuthorizationService = vi.mocked(authorizationService);
+    const mockConsola = vi.mocked(consola);
+    const testToken = 'test-token';
+    const appId = '00000000-0000-0000-0000-000000000001';
+    const buildId = '00000000-0000-0000-0000-000000000002';
+    const artifactId = 'artifact-1';
+    const artifactContent = 'zipped app bundle';
+    let outputDirectory;
+    const mockSimulatorBuild = () => nock(DEFAULT_API_BASE_URL)
+        .get(`/v1/apps/${appId}/builds/${buildId}`)
+        .query({ relations: 'appBuildArtifacts,job' })
+        .matchHeader('Authorization', `Bearer ${testToken}`)
+        .reply(200, {
+        id: buildId,
+        platform: 'ios',
+        type: 'simulator',
+        job: { status: 'succeeded' },
+        appBuildArtifacts: [
+            { id: 'artifact-0', status: 'ready', type: 'xcarchive' },
+            { formFactor: 'mobile', id: artifactId, status: 'ready', type: 'app' },
+        ],
+    });
+    beforeEach(async () => {
+        vi.clearAllMocks();
+        mockUserConfig.read.mockReturnValue({ token: testToken });
+        mockAuthorizationService.hasAuthorizationToken.mockReturnValue(true);
+        mockAuthorizationService.getCurrentAuthorizationToken.mockReturnValue(testToken);
+        vi.spyOn(process, 'exit').mockImplementation((code) => {
+            throw new Error(`Process exited with code ${code}`);
+        });
+        outputDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'capawesome-cli-download-'));
+    });
+    afterEach(async () => {
+        nock.cleanAll();
+        vi.restoreAllMocks();
+        await fs.rm(outputDirectory, { force: true, recursive: true });
+    });
+    it('should download the app artifact of an iOS simulator build with --app', async () => {
+        const outputPath = path.join(outputDirectory, 'simulator.app.zip');
+        const buildScope = mockSimulatorBuild();
+        const downloadScope = nock(DEFAULT_API_BASE_URL)
+            .get(`/v1/apps/${appId}/builds/${buildId}/artifacts/${artifactId}/download`)
+            .matchHeader('Authorization', `Bearer ${testToken}`)
+            .reply(200, artifactContent);
+        await downloadCommand.action({ appId, buildId, app: outputPath }, undefined);
+        expect(buildScope.isDone()).toBe(true);
+        expect(downloadScope.isDone()).toBe(true);
+        expect(await fs.readFile(outputPath, 'utf-8')).toBe(artifactContent);
+        expect(mockConsola.success).toHaveBeenCalledWith(`APP downloaded successfully: ${outputPath}`);
+    });
+    it('should write the app artifact to `<build-id>.app.zip` by default', async () => {
+        vi.spyOn(process, 'cwd').mockReturnValue(outputDirectory);
+        mockSimulatorBuild();
+        nock(DEFAULT_API_BASE_URL)
+            .get(`/v1/apps/${appId}/builds/${buildId}/artifacts/${artifactId}/download`)
+            .reply(200, artifactContent);
+        await downloadCommand.action({ appId, buildId, app: true }, undefined);
+        const outputPath = path.join(outputDirectory, `${buildId}.app.zip`);
+        expect(await fs.readFile(outputPath, 'utf-8')).toBe(artifactContent);
+    });
+    it('should reject --zip for an iOS build', async () => {
+        mockSimulatorBuild();
+        await expect(downloadCommand.action({ appId, buildId, zip: true }, undefined)).rejects.toThrow('Process exited with code 1');
+        expect(mockConsola.error).toHaveBeenCalledWith('The ZIP artifact is not available for iOS builds.');
+    });
+});

package/dist/commands/apps/builds/run.js

@@ -1,6 +1,7 @@
 import appBuildsService from '../../../services/app-builds.js';
 import { defineCommand, defineOptions } from 'zodline';
 import { bootAndroidEmulator, findAllAndroidEmulators, installAndroidApp, launchAndroidApp, } from '../../../utils/android-emulator.js';
+import { findAppBuildArtifact } from '../../../utils/app-build-artifacts.js';
 import { withAuth } from '../../../utils/auth.js';
 import { isInteractive } from '../../../utils/environment.js';
 import { bootIosSimulator, findAllIosSimulators, installIosApp, launchIosApp, } from '../../../utils/ios-simulator.js';
@@ -99,7 +100,7 @@ export default defineCommand({
             process.exit(1);
         }
         const artifactType = isAndroid ? 'apk' : 'app';
-        const artifact = build.appBuildArtifacts?.find((artifact) => artifact.type === artifactType && artifact.status === 'ready');
+        const artifact = findAppBuildArtifact(build.appBuildArtifacts?.filter((artifact) => artifact.status === 'ready'), { type: artifactType });
         if (!artifact) {
             consola.error(`No ${artifactType.toUpperCase()} artifact is available for this build.`);
             process.exit(1);

package/dist/commands/apps/liveupdates/create.js

@@ -54,8 +54,8 @@ export default defineCommand({
             .optional()
             .describe('The rollout percentage for the deployment (0-100). Default: 100.'),
         stack: z
-            .enum(['macos-sequoia', 'macos-tahoe'], {
-            message: 'Build stack must be either `macos-sequoia` or `macos-tahoe`.',
+            .enum(['macos-sequoia', 'macos-tahoe', 'macos-golden-gate'], {
+            message: 'Build stack must be one of `macos-sequoia`, `macos-tahoe`, or `macos-golden-gate`.',
         })
             .optional()
             .describe('The build stack to use for the build process.'),

package/dist/utils/app-build-artifacts.js

@@ -0,0 +1,87 @@
+import appBuildsService from '../services/app-builds.js';
+import consola from 'consola';
+import fs from 'fs/promises';
+import path from 'path';
+export const APP_BUILD_ARTIFACT_TYPES_BY_PLATFORM = {
+    android: ['apk', 'aab'],
+    ios: ['ipa', 'app'],
+    web: ['zip'],
+};
+export const APP_BUILD_ARTIFACT_LABELS = {
+    aab: 'AAB',
+    apk: 'APK',
+    app: 'APP',
+    ipa: 'IPA',
+    zip: 'ZIP',
+};
+/**
+ * The supported form factors, ordered by selection priority.
+ */
+export const APP_BUILD_ARTIFACT_FORM_FACTORS = ['mobile', 'watch', 'tv', 'automotive'];
+/**
+ * Download the build artifact of the given type and report the outcome to the user.
+ *
+ * Skips the download with a warning if no matching artifact exists or it is not ready yet.
+ */
+export const handleAppBuildArtifactDownload = async (options) => {
+    const { appId, buildId, buildArtifacts, artifactType, formFactor, filePath } = options;
+    const artifactLabel = APP_BUILD_ARTIFACT_LABELS[artifactType];
+    try {
+        consola.start(`Downloading ${artifactLabel}...`);
+        const artifact = findAppBuildArtifact(buildArtifacts, { type: artifactType, formFactor });
+        if (!artifact) {
+            consola.warn(formFactor
+                ? `No ${artifactLabel} artifact with form factor "${formFactor}" found for this build.`
+                : `No ${artifactLabel} artifact found for this build.`);
+            return;
+        }
+        if (artifact.status !== 'ready') {
+            consola.warn(`${artifactLabel} artifact is not ready (status: ${artifact.status}).`);
+            return;
+        }
+        const outputPath = await downloadAppBuildArtifact({ appId, buildId, artifact, filePath });
+        consola.success(`${artifactLabel} downloaded successfully: ${outputPath}`);
+    }
+    catch (error) {
+        consola.error(`Failed to download ${artifactLabel}:`, error);
+    }
+};
+/**
+ * Find a build artifact by its type and, optionally, its form factor.
+ *
+ * Without a form factor, the first artifact in the order of `APP_BUILD_ARTIFACT_FORM_FACTORS` is returned.
+ */
+export const findAppBuildArtifact = (artifacts, options) => {
+    const artifactsOfType = artifacts?.filter((artifact) => artifact.type === options.type) ?? [];
+    const formFactors = options.formFactor ? [options.formFactor] : APP_BUILD_ARTIFACT_FORM_FACTORS;
+    for (const formFactor of formFactors) {
+        const artifact = artifactsOfType.find((artifact) => artifact.formFactor === formFactor);
+        if (artifact) {
+            return artifact;
+        }
+    }
+    return undefined;
+};
+/**
+ * Build the default file name for a build artifact.
+ */
+export const getAppBuildArtifactFileName = (buildId, artifact) => {
+    const formFactorSuffix = artifact.formFactor === 'mobile' ? '' : `-${artifact.formFactor}`;
+    return `${buildId}${formFactorSuffix}.${getFileExtension(artifact.type)}`;
+};
+/**
+ * Download a build artifact to disk and return the output path.
+ */
+export const downloadAppBuildArtifact = async (options) => {
+    const { appId, buildId, artifact, filePath } = options;
+    const artifactData = await appBuildsService.downloadArtifact({
+        appId,
+        appBuildId: buildId,
+        artifactId: artifact.id,
+    });
+    const outputPath = path.resolve(filePath || getAppBuildArtifactFileName(buildId, artifact));
+    await fs.writeFile(outputPath, Buffer.from(artifactData));
+    return outputPath;
+};
+// The app artifact is a zipped `.app` bundle
+const getFileExtension = (artifactType) => artifactType === 'app' ? 'app.zip' : artifactType;

package/dist/utils/app-build-artifacts.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { findAppBuildArtifact, getAppBuildArtifactFileName } from './app-build-artifacts.js';
+const createArtifact = (artifact) => ({
+    id: 'artifact-id',
+    fileMimeType: 'application/octet-stream',
+    fileName: 'app.aab',
+    fileSizeInBytes: 1,
+    formFactor: 'mobile',
+    status: 'ready',
+    type: 'aab',
+    ...artifact,
+});
+describe('findAppBuildArtifact', () => {
+    it('should return the artifacts in the selection order', () => {
+        const watchArtifact = createArtifact({ id: 'watch', formFactor: 'watch' });
+        const mobileArtifact = createArtifact({ id: 'mobile', formFactor: 'mobile' });
+        expect(findAppBuildArtifact([watchArtifact, mobileArtifact], { type: 'aab' })).toBe(mobileArtifact);
+    });
+    it('should fall back to the next form factor if no mobile artifact exists', () => {
+        const automotiveArtifact = createArtifact({ id: 'automotive', formFactor: 'automotive' });
+        const tvArtifact = createArtifact({ id: 'tv', formFactor: 'tv' });
+        expect(findAppBuildArtifact([automotiveArtifact, tvArtifact], { type: 'aab' })).toBe(tvArtifact);
+    });
+    it('should return the artifact with the requested form factor', () => {
+        const mobileArtifact = createArtifact({ id: 'mobile', formFactor: 'mobile' });
+        const watchArtifact = createArtifact({ id: 'watch', formFactor: 'watch' });
+        expect(findAppBuildArtifact([mobileArtifact, watchArtifact], { type: 'aab', formFactor: 'watch' })).toBe(watchArtifact);
+    });
+    it('should return undefined if no artifact matches the requested form factor', () => {
+        const mobileArtifact = createArtifact({ formFactor: 'mobile' });
+        expect(findAppBuildArtifact([mobileArtifact], { type: 'aab', formFactor: 'tv' })).toBeUndefined();
+    });
+    it('should ignore artifacts of another type', () => {
+        const apkArtifact = createArtifact({ id: 'apk', type: 'apk' });
+        const aabArtifact = createArtifact({ id: 'aab', type: 'aab' });
+        expect(findAppBuildArtifact([apkArtifact, aabArtifact], { type: 'apk' })).toBe(apkArtifact);
+    });
+    it('should return undefined if no artifacts are given', () => {
+        expect(findAppBuildArtifact(undefined, { type: 'aab' })).toBeUndefined();
+    });
+});
+describe('getAppBuildArtifactFileName', () => {
+    it('should not add a suffix for a mobile artifact', () => {
+        const artifact = createArtifact({ formFactor: 'mobile' });
+        expect(getAppBuildArtifactFileName('build-id', artifact)).toBe('build-id.aab');
+    });
+    it('should add the form factor as a suffix for a watch artifact', () => {
+        const artifact = createArtifact({ formFactor: 'watch' });
+        expect(getAppBuildArtifactFileName('build-id', artifact)).toBe('build-id-watch.aab');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capawesome/cli",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "description": "The Capawesome Cloud Command Line Interface (CLI) to manage Live Updates and more.",
   "type": "module",
   "scripts": {