# macOS App Release Guide

**For Apple Developer Account holders** — Sign and notarize SOPHIAClaw for distribution.

---

## Quick Start

### Prerequisites

1. **Apple Developer Account** (personal or organization)
2. **Xcode** installed (includes command line tools)
3. **Codesigning certificate** created in Apple Developer Portal
4. **Notarization access** enabled in App Store Connect

---

## Step 1: Create Signing Certificate

### Option A: Xcode (Recommended)

1. Open **Xcode** → **Settings** → **Accounts**
2. Select your Apple ID → **Manage Certificates**
3. Click **+** → **Apple Development** or **Distribution**
4. Certificate appears in **Keychain Access** under "My Certificates"

### Option B: Apple Developer Portal

1. Visit [developer.apple.com](https://developer.apple.com)
2. **Certificates, IDs & Profiles** → **Certificates**
3. **+ Create** → Choose:
   - **Development**: `Apple Development` (testing)
   - **Distribution**: `Developer ID Application` (public releases)
4. Download `.cer`, double-click to install in Keychain

### Find Your Identity

```bash
# List all identities
security find-identity -p codesigning -v

# Copy the quoted name (without team ID)
# Example: "Apple Distribution: Your Name (TEAM123456)"
export SIGN_IDENTITY="Apple Distribution: Your Name"
```

---

## Step 2: Create Notarization Profile

### Keychain Profile (Recommended)

```bash
# Interactive (prompts for password)
xcrun notarytool store-credentials sophiaclaw-notary \
  --apple-id YOUR_APPLE_ID \
  --team-id YOUR_TEAM_ID \
  --password

# Test profile
xcrun notarytool history --keychain-profile sophiaclaw-notary
```

### Or Use API Key

1. [App Store Connect](https://appstoreconnect.apple.com) → **Users and Access**
2. **Integrations** → **Generate API Key**
3. Download `.p8` file, note **Key ID** and **Issuer ID**

```bash
export NOTARYTOOL_KEY="$HOME/Downloads/AuthKey_XXXXXXX.p8"
export NOTARYTOOL_KEY_ID="XXXXXXX"
export NOTARYTOOL_ISSUER="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
```

---

## Step 3: Build, Sign & Notarize

### Automated Script

```bash
# Set credentials
export SIGN_IDENTITY="Apple Distribution: Your Name"
export NOTARYTOOL_PROFILE="sophiaclaw-notary"

# Run full release
./scripts/release-mac-app-full.sh
```

### Manual Steps

```bash
# 1. Build and package
./scripts/package-mac-dist.sh

# 2. Verify codesign
codesign --verify --verbose dist/SOPHIAClaw.app

# 3. Create DMG
./scripts/create-dmg.sh

# 4. Notarize DMG
STAPLE_APP_PATH=dist/SOPHIAClaw.app \
  ./scripts/notarize-mac-artifact.sh \
  dist/SOPHIAClaw_v0.0.8.dmg

# 5. Validate
xcrun stapler validate dist/SOPHIAClaw_v0.0.8.dmg
echo "Success: Notarization valid"
```

---

## Step 4: Create GitHub Release

### Get Version from package.json

```bash
VERSION=$(node -p "require('./package.json').version")
echo "Releasing v$VERSION"
```

### Upload to GitHub

```bash
# Create release (interactive)
gh release create "v$VERSION" \
  dist/SOPHIAClaw_v$VERSION.dmg \
  dist/SOPHIAClaw_v$VERSION.dSYM.zip \
  --title "SOPHIAClaw v$VERSION" \
  --notes "See CHANGELOG.md for details"

# Or use file for notes
gh release create "v$VERSION" \
  dist/SOPHIAClaw_v$VERSION.dmg \
  --title "SOPHIAClaw v$VERSION" \
  --notes-file <(sed -n "/## $VERSION/,/^## /p" CHANGELOG.md | head -n -1)
```

---

## Step 5: Test on Fresh Mac

1. **Download** DMG from GitHub Releases
2. **Mount**: Double-click `SOPHIAClaw_v0.0.8.dmg`
3. **Install**: Drag `SOPHIAClaw.app` to `/Applications`
4. **First Launch**:
   - If Gatekeeper blocks: **System Settings → Privacy & Security → Open Anyway**
   - Or: `Ctrl+Click` → **Open** → confirm
5. **Verify**:
   ```bash
   # Check notarization
   xcrun stapler validate /Applications/SOPHIAClaw.app
   # Output: The validate action for the file: Succeeded
   ```

---

## Troubleshooting

### "DMG is corrupted"

**Cause**: Ad-hoc signed or not notarized  
**Fix**: Re-run release script with valid `SIGN_IDENTITY`

### Gatekeeper Blocks App

**First-time launch** (expected):

```bash
# From Terminal (bypass for testing)
xattr -cr /Applications/SOPHIAClaw.app
open -a SOPHIAClaw
```

**Permanent** (after notarization):

1. System Settings → Privacy & Security
2. Scroll to bottom → "SOPHIAClaw was blocked" → **Open Anyway**

### Codesign Fails

```bash
# Check identity exists
security find-identity -p codesigning -v

# List certificate thumbprint
openssl crl2pkcs7 -nocrl -certfile "<certfile>" | openssl pkcs7 -print_certs -text -noout
```

### Notarization Rejected

1. Check history:

   ```bash
   xcrun notarytool history --keychain-profile sophiaclaw-notary --output json | jq '.[0]'
   ```

2. Common issues:
   - **Invalid signature**: Ensure `SIGN_IDENTITY` matches cert
   - **Missing entitlements**: Run `codesign-mac-app.sh` with correct entitlements
   - **Hardened runtime**: Already enabled in package script

---

## Release Checklist

- [ ] Certificate created and in Keychain
- [ ] Notarization profile created
- [ ] `SIGN_IDENTITY` exported
- [ ] `NOTARYTOOL_PROFILE` or `NOTARYTOOL_KEY` exported
- [ ] Build successful: `./scripts/package-mac-dist.sh`
- [ ] Codesign verified: `codesign --verify dist/SOPHIAClaw.app`
- [ ] DMG created: `./scripts/create-dmg.sh`
- [ ] Notarized: `./scripts/notarize-mac-artifact.sh`
- [ ] Staple validated: `xcrun stapler validate`
- [ ] GitHub release created: `gh release create`
- [ ] Tested on fresh Mac (no prior install)

---

## Version Bumping

Update `package.json` before release:

```json
{
  "version": "0.0.8"
}
```

Then rebuild:

```bash
./scripts/release-mac-app-full.sh
```

---

## Sparkle Feed (Auto-Update)

SophiaClaw uses Sparkle for auto-updates.

### Feed Location

`appcast.xml` → GitHub Pages or S3

### Generate Feed

```bash
# After creating release
./scripts/sparkle-generate-feed.sh \
  dist/SOPHIAClaw_v*.dmg \
  dist/SOPHIACL_v*.dSYM.zip
```

Requires:

- `SPARKLE_PRIVATE_ED_KEY` (signing key)
- `SPARKLE_PUBLIC_ED_KEY` (embedded in app)

See [docs/platforms/mac/appcast.md](appcast.md) for details.

---

## Scripts Reference

| Script                     | Purpose                        |
| -------------------------- | ------------------------------ |
| `package-mac-dist.sh`      | Build + sign + package         |
| `codesign-mac-app.sh`      | Codesign with entitlements     |
| `create-dmg.sh`            | Create drag-to-install DMG     |
| `notarize-mac-artifact.sh` | Submit to Apple Notary service |
| `release-mac-app-full.sh`  | End-to-end release             |

---

**Next**: [Packaging Guide](packaging.md) | [Code Sign Details](codesign.md) | [Notarization](notarization.md)