Imported from romankurnovskii/BrewMate (.agents/skills/app-store-deploy/SKILL.md). Install upstream with npx skills add romankurnovskii/BrewMate --skill app-store-deploy. Copyright stays with the author.

Skill: App Store Deployment

This skill automates the versioning, building, and uploading of the BrewMate application to TestFlight / Mac App Store. It ensures that the app is properly signed and distributed using the correct Mac App Store (MAS) provisioning profiles and developer certificates.

Prerequisites

• macOS Environment: The deployment must be run on a Mac with Xcode command-line tools installed.
• Developer Certificates: Ensure "3rd Party Mac Developer Application" and "3rd Party Mac Developer Installer" certificates are in your System Keychain.
• Provisioning Profile: A valid profile must be present at .credentials/BrewMate_Distribution.provisionprofile.
• Environment Variables: A .env file must contain:
  • APPLE_ID: Your Apple Developer email.
  • APPLE_APP_SPECIFIC_PASSWORD: An app-specific password generated from appleid.apple.com.
• Tooling: jq must be installed for version management.

Automated Workflow

The easiest way to deploy is using the provided script:

# Deploys with automatic patch version increment (1.0.x -> 1.0.x+1)
./.agents/skills/app-store-deploy/scripts/deploy.sh

# Deploys with a specific version
./.agents/skills/app-store-deploy/scripts/deploy.sh 1.0.15

What the script does:

1. Loads credentials from .env.
2. Determines target version (either auto-increments current patch version or uses specified parameter).
3. Runs MAS Universal Build: Executes the project's native build script ./scripts/build-mas-universal.sh (or npm run build:mas) which compiles TypeScript, sets up code-signing with your 3rd Party Mac Developer certificates, and packages a signed .pkg file.
4. Uploads to TestFlight: Submits the generated bundle to App Store Connect using xcrun altool --upload-app.

Manual Deployment Steps

If you need to perform steps manually:

1. Build for MAS

Run the following command to generate a signed .pkg file under dist-app/:

npm run build:mas

2. Upload to TestFlight

Use altool to upload the generated package:

xcrun altool --upload-app --type macos --file "dist-app/mas-universal/BrewMate-[version]-universal.pkg" --username "$APPLE_ID" --password "$APPLE_APP_SPECIFIC_PASSWORD"

Alternatively, you can open the generated package in the macOS Transporter application for a visual upload:

npm run submit:mas

Troubleshooting

• Signing Errors: Ensure your Keychain is unlocked. Run security unlock-keychain if necessary.
• Validation Errors (409): Usually due to a version conflict in App Store Connect. Ensure you have bumped the version or build number.
• Architecture Mismatch: Ensure you are using the --universal flag (automatically handled by the build-mas script).

Success Checklist

• Version bumped in package.json.
• Universal binary built and signed successfully.
• .pkg file generated in dist-app/mas-universal/.
• Upload to TestFlight/App Store Connect completed successfully.
• Changes committed to the repository.