vibetunnel/scripts/README.md

VibeTunnel Scripts Directory

This directory contains all automation scripts for VibeTunnel development, building, and release management. Each script is thoroughly documented with headers explaining usage, dependencies, and examples.

📋 Script Categories

🏗️ Core Development Scripts

Script	Purpose	Usage
generate-xcproj.sh	Generate Xcode project with Tuist	./scripts/generate-xcproj.sh
build.sh	Build VibeTunnel app with optional signing	./scripts/build.sh [--configuration Debug|Release] [--sign]

🚀 Release Management Scripts

Script	Purpose	Usage
preflight-check.sh	Validate release readiness	./scripts/preflight-check.sh
release.sh	Main release automation script	./scripts/release.sh <stable|beta|alpha|rc> [number]
version.sh	Manage version numbers	./scripts/version.sh --patch|--minor|--major

🔐 Code Signing & Distribution

Script	Purpose	Usage
sign-and-notarize.sh	Sign and notarize app bundles	./scripts/sign-and-notarize.sh --sign-and-notarize
codesign-app.sh	Code sign app bundle only	./scripts/codesign-app.sh <app-path>
notarize-app.sh	Notarize signed app bundle	./scripts/notarize-app.sh <app-path>
create-dmg.sh	Create and sign DMG files	./scripts/create-dmg.sh <app-path> [dmg-path]

📡 Update System Scripts

Script	Purpose	Usage
generate-appcast.sh	Generate Sparkle appcast XML	./scripts/generate-appcast.sh

✅ Verification & Testing Scripts

Script	Purpose	Usage
verify-app.sh	Verify app signing and notarization	./scripts/verify-app.sh <app-or-dmg-path>
verify-appcast.sh	Validate appcast XML files	./scripts/verify-appcast.sh

🛠️ Utility Scripts

Script	Purpose	Usage
changelog-to-html.sh	Convert changelog to HTML for appcast	./scripts/changelog-to-html.sh <version>
extract-build-number.sh	Extract build number from DMG	./scripts/extract-build-number.sh <dmg-path>

🔄 Common Workflows

Development Workflow

# 1. Generate Xcode project (after Project.swift changes)
./scripts/generate-xcproj.sh

# 2. Build and test
./scripts/build.sh --configuration Debug

Release Workflow

# 1. Check release readiness
./scripts/preflight-check.sh

# 2. Create release (choose appropriate type)
./scripts/release.sh stable           # Production release
./scripts/release.sh beta 1           # Beta release
./scripts/release.sh alpha 2          # Alpha release
./scripts/release.sh rc 1             # Release candidate

Manual Build & Distribution

# 1. Build app
./scripts/build.sh --configuration Release

# 2. Sign and notarize
./scripts/sign-and-notarize.sh --sign-and-notarize

# 3. Create DMG
./scripts/create-dmg.sh build/Build/Products/Release/VibeTunnel.app

# 4. Verify final package
./scripts/verify-app.sh build/VibeTunnel-*.dmg

🔧 IS_PRERELEASE_BUILD System

The IS_PRERELEASE_BUILD system ensures beta downloads automatically default to the pre-release update channel:

• Project.swift: Contains "IS_PRERELEASE_BUILD": "$(IS_PRERELEASE_BUILD)" configuration
• release.sh: Sets IS_PRERELEASE_BUILD=YES for beta builds, NO for stable builds
• UpdateChannel.swift: Checks the flag to determine default update channel

📦 Dependencies

Required Tools

• Xcode - iOS/macOS development environment
• Tuist - Project generation (brew install tuist)
• GitHub CLI - Release management (brew install gh)

Code Quality Tools

• xcbeautify - Pretty build output (brew install xcbeautify)

Sparkle Tools

• sign_update - EdDSA signing for appcast updates
• generate_appcast - Appcast XML generation
• generate_keys - EdDSA key generation

Install Sparkle tools:

curl -L "https://github.com/sparkle-project/Sparkle/releases/download/2.7.0/Sparkle-2.7.0.tar.xz" -o Sparkle-2.7.0.tar.xz
tar -xf Sparkle-2.7.0.tar.xz
mkdir -p ~/.local/bin
cp bin/sign_update bin/generate_appcast bin/generate_keys ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

🔐 Environment Variables

Required for Release

# App Store Connect API (for notarization)
export APP_STORE_CONNECT_API_KEY_P8="-----BEGIN PRIVATE KEY-----..."
export APP_STORE_CONNECT_KEY_ID="ABCDEF1234"
export APP_STORE_CONNECT_ISSUER_ID="12345678-1234-1234-1234-123456789012"

Optional for Development

# Pre-release build flag (automatically set by release.sh)
export IS_PRERELEASE_BUILD=YES  # or NO

# CI certificate for signing
export MACOS_SIGNING_CERTIFICATE_P12_BASE64="..."

🧹 Maintenance Notes

Script Documentation Standards

All scripts follow this documentation format:

#!/bin/bash

# =============================================================================
# VibeTunnel [Script Name]
# =============================================================================
#
# [Description of what the script does]
#
# USAGE:
#   ./scripts/script-name.sh [arguments]
#
# [Additional sections as needed: FEATURES, DEPENDENCIES, EXAMPLES, etc.]
#
# =============================================================================

Script Categories by Complexity

• Simple Scripts: Basic single-purpose utilities
• Medium Scripts: build.sh, generate-xcproj.sh - Multi-step processes
• Complex Scripts: release.sh, sign-and-notarize.sh - Full automation workflows

Testing Scripts

Most scripts can be tested safely:

• Development scripts (build.sh) are safe to run anytime
• Verification scripts are read-only and safe
• Release scripts should only be run when creating actual releases

Script Interdependencies

release.sh (main release script)
├── preflight-check.sh (validation)
├── generate-xcproj.sh (project generation)
├── build.sh (compilation)
├── sign-and-notarize.sh (code signing)
├── create-dmg.sh (packaging)
├── generate-appcast.sh (update feed)
└── verify-app.sh (verification)

🔍 Troubleshooting

Common Issues

1. "command not found" - Install missing dependencies listed above
2. "No signing identity found" - Set up Apple Developer certificates
3. "Notarization failed" - Check App Store Connect API credentials
4. "Tuist generation failed" - Ensure Project.swift syntax is valid

Debug Tips

• Run ./scripts/preflight-check.sh to validate setup
• Check individual script headers for specific requirements
• Use --verbose flags where available for detailed output
• Verify environment variables are properly set

📝 Adding New Scripts

When adding new scripts:

1. Follow the documentation header format above
2. Add appropriate error handling (set -euo pipefail)
3. Include usage examples and dependency information
4. Update this README.md with the new script
5. Test thoroughly before committing

---

Last Updated: December 2024
Maintainer: VibeTunnel Development Team