feat(desktop): automate Mac App Store packaging and App Store Connect delivery

[chrisbbreuer]

Goal

Make a Stacks desktop app publishable to the Mac App Store through Buddy and a reusable GitHub Actions workflow. The repeatable path should be automated from a clean macOS runner; account enrollment, legal agreements, and one-time secret creation remain explicit human steps.

Related distribution work: pantry-pm/pantry#219.

Confirmed current gaps

buddy build:desktop currently emits a launcher, craft-runtime, desktop.json, provenance, and checksums under storage/framework/desktop-dist. It does not yet produce or validate the App Store deliverable:

• no .app bundle with a complete Info.plist;
• no embedded Mac App Store provisioning profile;
• no parent/helper App Sandbox entitlement split;
• no Mac App Distribution or Mac Installer Distribution signing;
• no signed installer .pkg;
• no App Store Connect validation/upload command;
• no reusable workflow for importing certificates and secrets;
• no automated certificate/profile reconciliation through the App Store Connect API;
• no universal arm64+x64 merge for a single dual-architecture Store binary;
• no listing metadata, screenshots, privacy, pricing, agreements, or review submission automation.

Apple requires App Sandbox for Mac App Store distribution and supports API-key/JWT build upload automation:

• https://developer.apple.com/documentation/security/protecting-user-data-with-app-sandbox
• https://developer.apple.com/help/account/create-certificates/certificates-overview
• https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds/
• https://developer.apple.com/help/app-store-connect/get-started/app-store-connect-api/

Phase 1: deterministic Buddy package/sign/upload path

• Add buddy desktop:apple:doctor to check macOS/Xcode tooling, bundle metadata, certificate identities, profile presence, API credentials, and Craft compatibility without mutating Apple or GitHub state.
• Add buddy desktop:apple:init to generate a documented reusable-workflow caller without overwriting an existing workflow.
• Add buddy desktop:apple:package to build the desktop payload, create a valid .app, embed the profile, sign the helper/runtime before the parent app, produce a signed installer .pkg, verify signatures and entitlements, and write provenance/checksums.
• Add buddy desktop:apple:publish with package-only, --validate-only, and upload modes using App Store Connect API key auth.
• Derive app name/version from the project and require explicit bundle ID, team ID, signing identities, and provisioning profile.
• Default entitlements to App Sandbox plus outbound network access; allow an audited app-owned entitlement file for additional capabilities.
• Ensure the embedded Craft runtime inherits the parent sandbox and cannot escape it.
• Add a reusable workflow_call workflow that builds Craft from an immutable revision, imports signing material into an ephemeral keychain, runs Buddy validation/package/upload, and uploads the resulting package/provenance/checksums as workflow artifacts.
• Ensure every secret is passed through environment/files with restrictive permissions and is absent from logs and artifacts.

Phase 2: Apple resource reconciliation

Use the App Store Connect API where Apple exposes the resource:

• Register or reconcile the explicit bundle ID and capabilities.
• Create/download/rotate Mac App Distribution and Mac Installer Distribution certificates from a caller-provided CSR/private key strategy.
• Create/download/refresh the Mac App Store provisioning profile.
• Add buddy desktop:apple:provision --plan and --apply, with idempotent diffs and no certificate revocation unless explicitly requested.
• Upload the binary with JWT authentication and poll until processing completes.
• Synchronize version metadata and attach the processed build.
• Add a prepare-only mode for metadata and a separate explicit App Review submission action.

Do not attempt to automate unavailable or legally sensitive actions: Developer Program enrollment, paid-app banking/tax setup, contract acceptance, export-compliance attestations requiring owner judgment, privacy answers, age rating answers, or final release policy decisions.

Phase 3: Store readiness and multi-architecture quality

• Build arm64 and x64 launcher/runtime pairs from the same revisions and merge compatible Mach-O binaries with lipo into one universal app.
• Validate minimum macOS version, architecture set, bundle ID, marketing version, build number, category, icon, copyright, and usage descriptions.
• Run a sandboxed launch smoke test before upload.
• Verify the actual signed entitlements with codesign -d --entitlements :-.
• Add Store rejection preflight checks for forbidden paths, unsigned nested code, mutable executables, private frameworks, and missing privacy declarations.
• Generate and validate required App Store screenshots from deterministic UI fixtures, while keeping human approval before upload.
• Attach Store delivery receipts to the corresponding GitHub Release through Pantry once feat(release): add macOS App Store and S3-compatible distribution targets pantry-pm/pantry#219 lands.

Required secrets and variables

Secrets:

• APPLE_APP_CERTIFICATE_BASE64
• APPLE_INSTALLER_CERTIFICATE_BASE64
• APPLE_CERTIFICATE_PASSWORD
• APPLE_PROVISIONING_PROFILE_BASE64
• APP_STORE_CONNECT_API_KEY
• APP_STORE_CONNECT_API_KEY_ID
• APP_STORE_CONNECT_API_ISSUER_ID
• an ephemeral keychain password (generated in CI when possible)

Variables/inputs:

• app name
• bundle ID
• Apple team ID
• Mac App Distribution signing identity
• Mac Installer Distribution signing identity
• minimum macOS version
• category
• release tag/version/build number
• validate-only vs upload vs submit-for-review

Tests and evidence

• Pure unit tests for plist/entitlement/workflow rendering and required-input diagnostics.
• Command tests with an injected process runner so no test invokes Apple services.
• macOS CI fixture that creates an unsigned app/package and verifies layout/provenance.
• Signed private fixture proving nested code order, profile embedding, sandbox inheritance, package signature, and App Store validation.
• Secret-redaction regression tests.
• Protocol evidence updated from pending only after signed validation artifacts exist.

Acceptance criteria

• A new Stacks app can generate a caller workflow with one Buddy command.
• A configured repository can produce a signed Mac App Store .pkg from a clean pinned runner.
• Validation and upload use API-key auth and can be retried without rebuilding or duplicating versions.
• All non-secret inputs and exact source/Craft revisions are recorded in provenance.
• Manual Apple account/legal steps are clearly listed and never presented as automated.
• GitHub Release artifacts, Pantry receipts, and App Store delivery records identify the same package SHA-256.

[chrisbbreuer]

Phase 1 is now implemented on main:

• a5651f839f adds Buddy desktop:apple:init, desktop:apple:doctor, desktop:apple:package, and desktop:apple:publish.
• The reusable desktop-app-store.yml workflow uses an ephemeral keychain, installs signing assets, signs the Craft helper before the app, builds the installer package, validates/uploads with an App Store Connect API key, and retains checksums/provenance as artifacts.
• 7b4576592b completes the npm-backed app TypeScript/scaffold migration used by desktop apps.
• Focused updater and Mac App Store command tests pass; the release workflow is publishing v0.70.211 now.

The issue remains open for Phase 2/3: automatic identifier/capability/profile management through Apple APIs where supported, notarized Developer ID distribution, CI smoke fixtures, and release-provider integration tracked in pantry-pm/pantry#219.

[chrisbbreuer]

Follow-up shipped in v0.70.212:

• release workflows are now serialized (0855b63b2b), preventing a newer npm workspace publish from entering dependency resolution during an older tag’s clean-install smoke test;
• npm-backed updates remove the obsolete pantry.lock (6f0673af69);
• the complete v0.70.212 release, clean-install smoke test, GitHub release asset upload, and Homebrew job passed: https://github.com/stacksjs/stacks/actions/runs/30403752773.

Postline was upgraded through Buddy to v0.70.212 and a second update was idempotent. The remaining unchecked issue phases are Apple-account provisioning/capability automation and the broader distribution targets linked in pantry-pm/pantry#219.

[chrisbbreuer]

Architecture update: generic Apple distribution work has been moved out of Stacks and into Pantry, per pantry-pm/pantry#219.

Pantry v0.11.0 now owns App Store Connect authentication/client behavior, Bundle IDs, capabilities, certificates, profiles, macOS provisioning plan/apply, CSR generation, P12 export, App Store version reconciliation, build polling/attachment, upload receipts, and S3-compatible release mirroring. Stacks now keeps a thin Safari-specific adapter (container/appex Bundle ID mapping, Xcode build/archive, and listing metadata) plus Buddy commands that delegate to ts-pantry.

The reusable Stacks workflow is pinned to the audited Pantry Action commit and records the Apple bundle ID, marketing version, build number, source revision, package hash, and delivery ID. Pantry publication is in progress; once npm exposes ts-pantry@0.11.0, the Stacks lockfile and generated Buddy docs will be updated and the complete suite rerun.

[chrisbbreuer]

Confirmed release and integration checkpoint:

• Stacks v0.70.216 is published to npm and GitHub, with all five Buddy archives and the Homebrew update complete: https://github.com/stacksjs/stacks/actions/runs/30409589112
• Generic App Store Connect authentication, bundle/capability/certificate/profile reconciliation, provisioning, build polling, receipts, and S3 mirroring now live in Pantry. Stacks retains only its Safari/Craft/Xcode mapping and delegates through ts-pantry.
• Buddy now exposes safe CSR and provisioning plan/apply commands; the reusable Apple workflow is pinned to the audited Pantry Action and records bundle ID, marketing version, build number, source revision, package hash, and delivery ID.
• The desktop lifecycle matrix passes on Linux, Windows, Intel macOS, and Apple Silicon macOS: https://github.com/stacksjs/stacks/actions/runs/30409115405
• Full Stacks CI passed, including compile, protocol, tests, typecheck, lint, and deployment: https://github.com/stacksjs/stacks/actions/runs/30409115424
• Postline was updated through Buddy from the npm-backed framework to v0.70.216. A second Buddy update was idempotent, storage/framework/core remains absent, all managed framework manifests are current, AI assets were refreshed without drift, and typecheck, 69 unit tests, browser-suite discovery, lint, and the 13-page production build pass.

This issue remains open only for the credentialed Apple-side evidence that cannot be truthfully simulated in public CI: a signed private fixture, actual App Store validation/upload against the owner account, human-approved listing/privacy answers, and explicit review submission. Reusable provider work and remaining distribution evidence are tracked in pantry-pm/pantry#219.

[chrisbbreuer]

Final version follow-up: v0.70.217 landed while the integration verification was finishing and is now published to npm/GitHub with all Buddy assets: https://github.com/stacksjs/stacks/releases/tag/v0.70.217

Postline was advanced again through Buddy to v0.70.217. The second update is idempotent; all 34 managed manifests are current, AI assets have no drift, storage/framework/core remains absent, and typecheck, 69 unit tests, browser-suite discovery, zero-error lint, and the 13/13 production build pass. The final Postline sync is stacksjs/postline@3ec5778.