@capawesome/cli 4.20.0 → 4.22.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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)
+
+
+### Features
+
+* **apps:** link repositories via git connections ([#222](https://github.com/capawesome-team/cli/issues/222)) ([f567ea6](https://github.com/capawesome-team/cli/commit/f567ea6d0e836b4aea8e4d57ff10d934a6788fe2))
+
+
+### Bug Fixes
+
+* retry rate limited requests ([#223](https://github.com/capawesome-team/cli/issues/223)) ([47d9733](https://github.com/capawesome-team/cli/commit/47d9733ec28bf0bb3235b8dccdd5b353ec24d0b5))
+
 ## [4.20.0](https://github.com/capawesome-team/cli/compare/v4.19.0...v4.20.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/import.js

@@ -15,6 +15,7 @@ import { withAuth } from '../../utils/auth.js';
 import { isInteractive } from '../../utils/environment.js';
 import { getMessageFromUnknownError, UserError } from '../../utils/error.js';
 import { isReadable } from '../../utils/file.js';
+import { getGitRepositoryPath } from '../../utils/git.js';
 import { prompt, promptOrganizationSelection } from '../../utils/prompt.js';
 import zip from '../../utils/zip.js';
 import { defineCommand, defineOptions } from 'zodline';
@@ -24,8 +25,6 @@ import os from 'os';
 import path from 'path';
 import { z } from 'zod';
 const SIGNALS = ['SIGHUP', 'SIGINT', 'SIGTERM'];
-// Maps the providers of `parseGitRemoteUrl` to the providers of git connections.
-const GIT_CONNECTION_PROVIDERS = { azure: 'azure_devops' };
 export default defineCommand({
     description: 'Import apps from an Ionic Appflow export.',
     options: defineOptions(z.object({
@@ -102,8 +101,11 @@ export default defineCommand({
             const { resolvedApps, skippedApps: unresolvedApps } = await resolveIonicAppTypes(selectedApps, ionicAppType);
             selectedSkippedApps.push(...unresolvedApps);
             await assignUniqueAppNames(resolvedApps, organizationId);
-            const unconnectedGitProviders = await findUnconnectedGitProviders(resolvedApps, organizationId);
-            for (const provider of unconnectedGitProviders) {
+            const gitConnectionIds = await findGitConnectionIds(resolvedApps, organizationId);
+            for (const provider of getGitProviders(resolvedApps)) {
+                if (gitConnectionIds.has(provider)) {
+                    continue;
+                }
                 const appCount = resolvedApps.filter((app) => app.repository?.provider === provider).length;
                 consola.warn(`The organization has no \`${provider}\` git connection, so the repositories of ${appCount} app(s) will not be linked. Connect the git provider at ${DEFAULT_CONSOLE_BASE_URL}/organizations/${organizationId}/git before running the import to link them automatically, or link the repositories manually in the Capawesome Cloud Console afterwards.`);
             }
@@ -125,7 +127,7 @@ export default defineCommand({
                 if (dryRun) {
                     continue;
                 }
-                await importApp(organizationId, outcome, unconnectedGitProviders);
+                await importApp(organizationId, outcome, gitConnectionIds);
             }
             const errorCount = outcomes.reduce((count, outcome) => count + outcome.errors.length, 0);
             if (json) {
@@ -234,22 +236,23 @@ const assignUniqueAppNames = async (apps, organizationId) => {
         }
     }
 };
-const findUnconnectedGitProviders = async (apps, organizationId) => {
-    const providers = new Set(apps.flatMap((app) => (app.repository ? [app.repository.provider] : [])));
-    const unconnectedProviders = new Set();
-    for (const provider of providers) {
-        const gitConnections = await gitConnectionsService.findAll({
+const getGitProviders = (apps) => new Set(apps.flatMap((app) => (app.repository ? [app.repository.provider] : [])));
+const findGitConnectionIds = async (apps, organizationId) => {
+    const gitConnectionIds = new Map();
+    for (const provider of getGitProviders(apps)) {
+        const [gitConnection] = await gitConnectionsService.findAll({
             organizationId,
-            provider: GIT_CONNECTION_PROVIDERS[provider] ?? provider,
+            provider,
+            restricted: false,
             limit: 1,
         });
-        if (gitConnections.length === 0) {
-            unconnectedProviders.add(provider);
+        if (gitConnection) {
+            gitConnectionIds.set(provider, gitConnection.id);
         }
     }
-    return unconnectedProviders;
+    return gitConnectionIds;
 };
-const importApp = async (organizationId, outcome, unconnectedGitProviders) => {
+const importApp = async (organizationId, outcome, gitConnectionIds) => {
     const { app } = outcome;
     consola.start(`Importing app \`${app.sourceName}\`...`);
     let appId;
@@ -426,22 +429,20 @@ const importApp = async (organizationId, outcome, unconnectedGitProviders) => {
             outcome.errors.push(`Failed to create automation \`${automation.name}\`: ${getMessageFromUnknownError(error)}`);
         }
     }
-    if (app.repository && unconnectedGitProviders.has(app.repository.provider)) {
-        app.notes.push(`The repository \`${app.repository.ownerSlug}/${app.repository.repositorySlug}\` was not linked because the organization has no \`${app.repository.provider}\` git connection.`);
-    }
-    else if (app.repository) {
-        try {
-            await appsService.linkRepository({
-                appId,
-                ownerSlug: app.repository.ownerSlug,
-                provider: app.repository.provider,
-                repositorySlug: app.repository.repositorySlug,
-                projectSlug: app.repository.projectSlug,
-            });
-            consola.success(`Linked repository \`${app.repository.ownerSlug}/${app.repository.repositorySlug}\`.`);
-        }
-        catch (error) {
-            app.notes.push(`The repository \`${app.repository.ownerSlug}/${app.repository.repositorySlug}\` could not be linked: ${getMessageFromUnknownError(error)} Make sure the git provider is connected in the Capawesome Cloud Console and link the repository manually.`);
+    if (app.repository) {
+        const gitConnectionId = gitConnectionIds.get(app.repository.provider);
+        const repositoryPath = getGitRepositoryPath(app.repository);
+        if (!gitConnectionId) {
+            app.notes.push(`The repository \`${repositoryPath}\` was not linked because the organization has no \`${app.repository.provider}\` git connection.`);
+        }
+        else {
+            try {
+                await appsService.linkRepository({ appId, gitConnectionId, path: repositoryPath });
+                consola.success(`Linked repository \`${repositoryPath}\`.`);
+            }
+            catch (error) {
+                app.notes.push(`The repository \`${repositoryPath}\` could not be linked: ${getMessageFromUnknownError(error)} Link the repository manually in the Capawesome Cloud Console.`);
+            }
         }
     }
 };

package/dist/commands/apps/import.test.js

@@ -153,12 +153,11 @@ describe('apps-import', () => {
         })
             .reply(201, { id: 'automation-1', name: 'Android Release' })
             .get(`/v1/organizations/${organizationId}/git-connections`)
-            .query({ provider: 'github', limit: 1 })
+            .query({ provider: 'github', restricted: 'false', limit: 1 })
             .reply(200, [{ id: 'git-connection-1', provider: 'github' }])
             .put(`/v1/apps/${appId}/repository`, {
-            ownerSlug: 'robingenz',
-            provider: 'github',
-            repositorySlug: 'appflow-export-test',
+            gitConnectionId: 'git-connection-1',
+            path: 'robingenz/appflow-export-test',
         })
             .reply(200, { id: appId });
         await importCommand.action({ file: exportFile, organizationId, json: true }, undefined);
@@ -409,19 +408,14 @@ describe('apps-import', () => {
             .query({ organizationId, limit: 50, offset: 0 })
             .reply(200, [])
             .get(`/v1/organizations/${organizationId}/git-connections`)
-            .query({ provider: 'azure_devops', limit: 1 })
+            .query({ provider: 'azure_devops', restricted: 'false', limit: 1 })
             .reply(200, [{ id: 'git-connection-1', provider: 'azure_devops' }])
             .post('/v1/apps', { name: 'My App', type: 'capacitor' })
             .query({ organizationId })
             .reply(201, { id: 'app-1', name: 'My App', type: 'capacitor' })
             .get('/v1/apps/app-1/channels')
             .reply(200, [])
-            .put('/v1/apps/app-1/repository', {
-            ownerSlug: 'my-org',
-            provider: 'azure',
-            repositorySlug: 'my-repo',
-            projectSlug: 'my-project',
-        })
+            .put('/v1/apps/app-1/repository', { gitConnectionId: 'git-connection-1', path: 'my-org/my-project/my-repo' })
             .reply(200, { id: 'app-1' });
         await importCommand.action({ file: exportFile, organizationId, json: true }, undefined);
         expect(scope.isDone()).toBe(true);
@@ -445,7 +439,7 @@ describe('apps-import', () => {
             .query({ organizationId, limit: 50, offset: 0 })
             .reply(200, [])
             .get(`/v1/organizations/${organizationId}/git-connections`)
-            .query({ provider: 'github', limit: 1 })
+            .query({ provider: 'github', restricted: 'false', limit: 1 })
             .reply(200, [])
             .post('/v1/apps', { name: 'My App', type: 'capacitor' })
             .query({ organizationId })

package/dist/commands/apps/link.js

@@ -1,7 +1,9 @@
+import { DEFAULT_CONSOLE_BASE_URL } from '../../config/consts.js';
 import appsService from '../../services/apps.js';
+import gitConnectionsService from '../../services/git-connections.js';
 import { withAuth } from '../../utils/auth.js';
 import { isInteractive } from '../../utils/environment.js';
-import { getGitRemoteInfo } from '../../utils/git.js';
+import { getGitRemoteInfo, getGitRepositoryPath } from '../../utils/git.js';
 import { promptAppSelection, promptOrganizationSelection } from '../../utils/prompt.js';
 import consola from 'consola';
 import { z } from 'zod';
@@ -10,9 +12,13 @@ export default defineCommand({
     description: 'Connect a git repository to an app.',
     options: defineOptions(z.object({
         appId: z.string().optional().describe('ID of the app.'),
+        gitConnectionId: z
+            .string()
+            .optional()
+            .describe('ID of the git connection to use. Defaults to the first git connection of the organization for the git provider of the repository.'),
     })),
     action: withAuth(async (options, args) => {
-        let { appId } = options;
+        let { appId, gitConnectionId } = options;
         if (!appId) {
             if (!isInteractive()) {
                 consola.error('You must provide the app ID when running in non-interactive environment.');
@@ -22,12 +28,24 @@ export default defineCommand({
             appId = await promptAppSelection(organizationId);
         }
         const gitRemoteInfo = getGitRemoteInfo();
+        if (!gitConnectionId) {
+            const app = await appsService.findOne({ appId });
+            const [gitConnection] = await gitConnectionsService.findAll({
+                organizationId: app.organizationId,
+                provider: gitRemoteInfo.provider,
+                restricted: false,
+                limit: 1,
+            });
+            if (!gitConnection) {
+                consola.error(`No \`${gitRemoteInfo.provider}\` git connection found in the organization. Connect the git provider first at ${DEFAULT_CONSOLE_BASE_URL}/organizations/${app.organizationId}/git.`);
+                process.exit(1);
+            }
+            gitConnectionId = gitConnection.id;
+        }
         await appsService.linkRepository({
             appId,
-            ownerSlug: gitRemoteInfo.ownerSlug,
-            provider: gitRemoteInfo.provider,
-            repositorySlug: gitRemoteInfo.repositorySlug,
-            projectSlug: gitRemoteInfo.projectSlug,
+            gitConnectionId,
+            path: getGitRepositoryPath(gitRemoteInfo),
         });
         consola.success('Repository connected successfully.');
     }),

package/dist/commands/apps/link.test.js

@@ -13,7 +13,8 @@ vi.mock('consola');
 vi.mock('@/utils/environment.js', () => ({
     isInteractive: () => true,
 }));
-vi.mock('@/utils/git.js', () => ({
+vi.mock('@/utils/git.js', async (importOriginal) => ({
+    ...(await importOriginal()),
     getGitRemoteInfo: () => ({
         ownerSlug: 'capawesome-team',
         provider: 'github',
@@ -26,10 +27,13 @@ describe('apps-link', () => {
     const mockPromptAppSelection = vi.mocked(promptAppSelection);
     const mockConsola = vi.mocked(consola);
     const mockAuthorizationService = vi.mocked(authorizationService);
+    const appId = 'app-123';
+    const organizationId = 'org-1';
+    const testToken = 'test-token';
     beforeEach(() => {
         vi.clearAllMocks();
-        mockUserConfig.read.mockReturnValue({ token: 'test-token' });
-        mockAuthorizationService.getCurrentAuthorizationToken.mockReturnValue('test-token');
+        mockUserConfig.read.mockReturnValue({ token: testToken });
+        mockAuthorizationService.getCurrentAuthorizationToken.mockReturnValue(testToken);
         mockAuthorizationService.hasAuthorizationToken.mockReturnValue(true);
         vi.spyOn(process, 'exit').mockImplementation((code) => {
             throw new Error(`Process exited with code ${code}`);
@@ -39,56 +43,50 @@ describe('apps-link', () => {
         nock.cleanAll();
         vi.restoreAllMocks();
     });
-    it('should link repository with provided app ID', async () => {
-        const appId = 'app-123';
-        const testToken = 'test-token';
-        const options = { appId };
-        const scope = nock(DEFAULT_API_BASE_URL)
-            .put(`/v1/apps/${appId}/repository`, {
-            ownerSlug: 'capawesome-team',
-            provider: 'github',
-            repositorySlug: 'cli',
-        })
+    const mockGitConnectionLookup = (gitConnections) => nock(DEFAULT_API_BASE_URL)
+        .get(`/v1/apps/${appId}`)
+        .reply(200, { id: appId, name: 'Test App', organizationId, type: 'capacitor' })
+        .get(`/v1/organizations/${organizationId}/git-connections`)
+        .query({ provider: 'github', restricted: 'false', limit: 1 })
+        .reply(200, gitConnections);
+    it('should link repository using the git connection of the organization', async () => {
+        const scope = mockGitConnectionLookup([{ id: 'git-connection-1' }])
+            .put(`/v1/apps/${appId}/repository`, { gitConnectionId: 'git-connection-1', path: 'capawesome-team/cli' })
             .matchHeader('Authorization', `Bearer ${testToken}`)
             .reply(200, { id: appId, name: 'Test App' });
-        await linkCommand.action(options, undefined);
+        await linkCommand.action({ appId }, undefined);
         expect(scope.isDone()).toBe(true);
         expect(mockConsola.success).toHaveBeenCalledWith('Repository connected successfully.');
     });
+    it('should link repository using the provided git connection ID', async () => {
+        const scope = nock(DEFAULT_API_BASE_URL)
+            .put(`/v1/apps/${appId}/repository`, { gitConnectionId: 'git-connection-2', path: 'capawesome-team/cli' })
+            .reply(200, { id: appId, name: 'Test App' });
+        await linkCommand.action({ appId, gitConnectionId: 'git-connection-2' }, undefined);
+        expect(scope.isDone()).toBe(true);
+    });
     it('should prompt for organization and app when app ID is not provided', async () => {
-        const appId = 'app-123';
-        const orgId = 'org-1';
-        const testToken = 'test-token';
-        const options = {};
-        mockPromptOrganizationSelection.mockResolvedValueOnce(orgId);
+        mockPromptOrganizationSelection.mockResolvedValueOnce(organizationId);
         mockPromptAppSelection.mockResolvedValueOnce(appId);
-        const scope = nock(DEFAULT_API_BASE_URL)
-            .put(`/v1/apps/${appId}/repository`, {
-            ownerSlug: 'capawesome-team',
-            provider: 'github',
-            repositorySlug: 'cli',
-        })
-            .matchHeader('Authorization', `Bearer ${testToken}`)
+        const scope = mockGitConnectionLookup([{ id: 'git-connection-1' }])
+            .put(`/v1/apps/${appId}/repository`, { gitConnectionId: 'git-connection-1', path: 'capawesome-team/cli' })
             .reply(200, { id: appId, name: 'Test App' });
-        await linkCommand.action(options, undefined);
+        await linkCommand.action({}, undefined);
         expect(scope.isDone()).toBe(true);
         expect(mockPromptOrganizationSelection).toHaveBeenCalled();
-        expect(mockPromptAppSelection).toHaveBeenCalledWith(orgId);
-        expect(mockConsola.success).toHaveBeenCalledWith('Repository connected successfully.');
+        expect(mockPromptAppSelection).toHaveBeenCalledWith(organizationId);
+    });
+    it('should error if the organization has no git connection for the provider', async () => {
+        const scope = mockGitConnectionLookup([]);
+        await expect(linkCommand.action({ appId }, undefined)).rejects.toThrow('Process exited with code 1');
+        expect(scope.isDone()).toBe(true);
+        expect(mockConsola.error).toHaveBeenCalledWith(expect.stringContaining('No `github` git connection found'));
     });
     it('should handle API error', async () => {
-        const appId = 'app-123';
-        const testToken = 'test-token';
-        const options = { appId };
-        const scope = nock(DEFAULT_API_BASE_URL)
-            .put(`/v1/apps/${appId}/repository`, {
-            ownerSlug: 'capawesome-team',
-            provider: 'github',
-            repositorySlug: 'cli',
-        })
-            .matchHeader('Authorization', `Bearer ${testToken}`)
-            .reply(400, { message: 'Git provider not connected' });
-        await expect(linkCommand.action(options, undefined)).rejects.toThrow();
+        const scope = mockGitConnectionLookup([{ id: 'git-connection-1' }])
+            .put(`/v1/apps/${appId}/repository`, { gitConnectionId: 'git-connection-1', path: 'capawesome-team/cli' })
+            .reply(400, { message: 'Repository not found' });
+        await expect(linkCommand.action({ appId }, undefined)).rejects.toThrow();
         expect(scope.isDone()).toBe(true);
     });
 });

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/services/git-connections.js

@@ -16,6 +16,9 @@ class GitConnectionsServiceImpl {
         if (dto.provider !== undefined) {
             params.provider = dto.provider;
         }
+        if (dto.restricted !== undefined) {
+            params.restricted = dto.restricted.toString();
+        }
         const response = await this.httpClient.get(`/v1/organizations/${dto.organizationId}/git-connections`, {
             headers: {
                 Authorization: `Bearer ${authorizationService.getCurrentAuthorizationToken()}`,

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/dist/utils/git.js

@@ -4,8 +4,8 @@ const HOSTNAME_TO_PROVIDER = {
     'github.com': 'github',
     'gitlab.com': 'gitlab',
     'bitbucket.org': 'bitbucket',
-    'dev.azure.com': 'azure',
-    'ssh.dev.azure.com': 'azure',
+    'dev.azure.com': 'azure_devops',
+    'ssh.dev.azure.com': 'azure_devops',
 };
 export const getGitRemoteInfo = () => {
     const remoteUrl = getGitRemoteUrl();
@@ -25,7 +25,7 @@ export const parseGitRemoteUrl = (remoteUrl) => {
     if (azureHttpsMatch && azureHttpsMatch[1] && azureHttpsMatch[2] && azureHttpsMatch[3]) {
         return {
             ownerSlug: azureHttpsMatch[1],
-            provider: 'azure',
+            provider: 'azure_devops',
             repositorySlug: azureHttpsMatch[3],
             projectSlug: azureHttpsMatch[2],
         };
@@ -35,7 +35,7 @@ export const parseGitRemoteUrl = (remoteUrl) => {
     if (azureSshMatch && azureSshMatch[1] && azureSshMatch[2] && azureSshMatch[3]) {
         return {
             ownerSlug: azureSshMatch[1],
-            provider: 'azure',
+            provider: 'azure_devops',
             repositorySlug: azureSshMatch[3],
             projectSlug: azureSshMatch[2],
         };
@@ -45,7 +45,7 @@ export const parseGitRemoteUrl = (remoteUrl) => {
     if (vsHttpsMatch && vsHttpsMatch[1] && vsHttpsMatch[2] && vsHttpsMatch[3]) {
         return {
             ownerSlug: vsHttpsMatch[1],
-            provider: 'azure',
+            provider: 'azure_devops',
             repositorySlug: vsHttpsMatch[3],
             projectSlug: vsHttpsMatch[2],
         };
@@ -90,3 +90,4 @@ export const parseGitRemoteUrl = (remoteUrl) => {
     }
     throw new UserError('Could not parse git remote URL.');
 };
+export const getGitRepositoryPath = (remoteInfo) => [remoteInfo.ownerSlug, remoteInfo.projectSlug, remoteInfo.repositorySlug].filter(Boolean).join('/');

package/dist/utils/git.test.js

@@ -87,7 +87,7 @@ describe('parseGitRemoteUrl', () => {
         const result = parseGitRemoteUrl('https://dev.azure.com/my-org/my-project/_git/my-repo');
         expect(result).toEqual({
             ownerSlug: 'my-org',
-            provider: 'azure',
+            provider: 'azure_devops',
             repositorySlug: 'my-repo',
             projectSlug: 'my-project',
         });
@@ -96,7 +96,7 @@ describe('parseGitRemoteUrl', () => {
         const result = parseGitRemoteUrl('git@ssh.dev.azure.com:v3/my-org/my-project/my-repo');
         expect(result).toEqual({
             ownerSlug: 'my-org',
-            provider: 'azure',
+            provider: 'azure_devops',
             repositorySlug: 'my-repo',
             projectSlug: 'my-project',
         });
@@ -105,7 +105,7 @@ describe('parseGitRemoteUrl', () => {
         const result = parseGitRemoteUrl('https://my-org.visualstudio.com/my-project/_git/my-repo');
         expect(result).toEqual({
             ownerSlug: 'my-org',
-            provider: 'azure',
+            provider: 'azure_devops',
             repositorySlug: 'my-repo',
             projectSlug: 'my-project',
         });

package/dist/utils/http-client.js

@@ -2,19 +2,28 @@ import { createRequire } from 'module';
 import configService from '../services/config.js';
 import axios from 'axios';
 import axiosRetry from 'axios-retry';
+import consola from 'consola';
 import { HttpProxyAgent } from 'http-proxy-agent';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
+const isRateLimitError = (error) => error.response?.status === 429;
 // Register middleware to retry failed requests
 axiosRetry(axios, {
     retries: 3,
+    // Waits at least as long as the `Retry-After` header of rate limited responses
     retryDelay: axiosRetry.exponentialDelay,
     retryCondition: (error) => {
-        // Network errors and 5xx responses are retried
+        // Network errors, rate limited requests and 5xx responses are retried
         return (axiosRetry.isNetworkOrIdempotentRequestError(error) ||
+            isRateLimitError(error) ||
             (error.response?.status !== undefined && error.response.status >= 500));
     },
+    onRetry: (_retryCount, error) => {
+        if (isRateLimitError(error)) {
+            consola.warn('Rate limit reached. Retrying...');
+        }
+    },
 });
 /**
  * Gets the appropriate proxy agent based on the target URL protocol and environment variables.

package/dist/utils/http-client.test.js

@@ -1,4 +1,5 @@
 import configService from '../services/config.js';
+import consola from 'consola';
 import nock from 'nock';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 // Mock the config service
@@ -7,6 +8,7 @@ vi.mock('@/services/config.js', () => ({
         getValueForKey: vi.fn().mockResolvedValue('https://api.example.com'),
     },
 }));
+vi.mock('consola');
 describe('http-client', () => {
     let originalEnv;
     beforeEach(() => {
@@ -23,6 +25,7 @@ describe('http-client', () => {
     afterEach(() => {
         // Restore original environment variables
         process.env = originalEnv;
+        vi.useRealTimers();
     });
     it('should retry requests on 5xx status codes', async () => {
         // Mock the API_BASE_URL
@@ -50,6 +53,29 @@ describe('http-client', () => {
         await expect(httpClient.get('/not-found')).rejects.toThrow();
         expect(nock.isDone()).toBe(true);
     });
+    it('should retry rate limited requests after the `Retry-After` delay', async () => {
+        vi.mocked(configService.getValueForKey).mockResolvedValue('https://api.example.com');
+        // Mock a 429 response followed by success
+        nock('https://api.example.com')
+            .post('/rate-limited')
+            .reply(429, { error: 'Too Many Requests' }, { 'Retry-After': '10' })
+            .post('/rate-limited')
+            .reply(200, { success: true });
+        const { default: httpClient } = await import('./http-client.js');
+        // Only fake `setTimeout` so the request itself is still served by nock
+        vi.useFakeTimers({ toFake: ['setTimeout'] });
+        const responsePromise = httpClient.post('/rate-limited');
+        // Wait until the retry has been scheduled
+        await vi.waitFor(() => expect(vi.getTimerCount()).toBe(1));
+        await vi.advanceTimersByTimeAsync(5000);
+        expect(nock.isDone()).toBe(false);
+        await vi.runAllTimersAsync();
+        const response = await responsePromise;
+        expect(response.status).toBe(200);
+        expect(response.data).toEqual({ success: true });
+        expect(nock.isDone()).toBe(true);
+        expect(consola.warn).toHaveBeenCalledWith('Rate limit reached. Retrying...');
+    });
     it('should eventually fail after maximum retries on persistent 5xx errors', async () => {
         vi.mocked(configService.getValueForKey).mockResolvedValue('https://api.example.com');
         // Mock 4 consecutive 500 responses (initial + 3 retries)

package/package.json

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