moreminimore-vibe/README-BUILD-SCRIPT.md

MoreMinimore Build Script Guide

🎯 Overview

The build-moreminimore-app.sh script is a comprehensive build automation tool that handles the complete process of building the MoreMinimore Electron application with proper configuration, error handling, and cross-platform support.

🚀 Quick Start

Development Build (Recommended for Testing)

./scripts/build-moreminimore-app.sh

Production Build (Requires Code Signing)

./scripts/build-moreminimore-app.sh --production

📋 Features

✅ Automatic Code Signing Management

• Development builds: Automatically disables code signing by setting E2E_TEST_BUILD=true
• Production builds: Requires Apple Developer credentials for proper code signing

✅ Comprehensive Build Process

• Prerequisites checking (Node.js, npm, logo files)
• Dependency installation
• Build artifact cleanup
• TypeScript compilation verification
• Application building with Electron Forge
• Build verification and output reporting

✅ Error Handling & Troubleshooting

• Detailed error messages with troubleshooting steps
• Verbose mode for debugging
• Automatic logo generation if missing
• Graceful failure handling

✅ Cross-Platform Support

• macOS: Creates .zip distribution files
• Linux: Creates .deb packages
• Windows: Creates .exe installers

🔧 Usage Options

Command Line Options

./scripts/build-moreminimore-app.sh [OPTIONS]

OPTIONS:
    --production      Build for production (requires code signing setup)
    --clean-only      Only clean build artifacts, don't build
    --skip-deps       Skip dependency installation
    --verbose         Enable verbose output
    --help, -h        Show help message

Usage Examples

Standard Development Build

./scripts/build-moreminimore-app.sh

• Disables code signing automatically
• Installs dependencies
• Builds for current platform
• Creates distributable package

Production Build

./scripts/build-moreminimore-app.sh --production

• Enables code signing
• Requires Apple Developer credentials
• Creates production-ready installer

Clean Build Artifacts

./scripts/build-moreminimore-app.sh --clean-only

• Removes out/ directory
• Cleans scaffold node_modules
• Prepares for fresh build

Verbose Debug Build

./scripts/build-moreminimore-app.sh --verbose

• Shows detailed build output
• Enables Electron Forge debug logging
• Helpful for troubleshooting

Fast Build (Skip Dependencies)

./scripts/build-moreminimore-app.sh --skip-deps

• Skips npm install
• Useful for repeated builds
• Assumes dependencies are current

📁 Build Output

Development Builds

• Location: out/make/zip/darwin/arm64/
• File: moreminimore-darwin-arm64-0.31.0-beta.1.zip
• Size: ~180MB
• Code Signing: Disabled (for development/testing)

Production Builds

• Location: out/make/ with platform-specific subdirectories
• Formats:
  • macOS: .zip and .dmg
  • Windows: .exe installer
  • Linux: .deb package
• Code Signing: Enabled (requires credentials)

🔑 Code Signing Configuration

Development Builds

Automatically handled by setting:

export E2E_TEST_BUILD=true

This tells Electron Forge to skip code signing, which is perfect for development and testing.

Production Builds

Requires the following environment variables:

export APPLE_TEAM_ID="your-apple-developer-team-id"
export APPLE_ID="your-apple-id@example.com"
export APPLE_PASSWORD="your-app-specific-password"
export SM_CODE_SIGNING_CERT_SHA1_HASH="your-certificate-sha1-hash"

Setting Up Apple Developer Credentials

1. Get Apple Developer Account

   • Sign up at developer.apple.com
   • Enroll in Apple Developer Program ($99/year)

2. Create Development Certificate

   • Go to Xcode → Preferences → Accounts
   • Add your Apple ID
   • Create a development certificate

3. Find Your Team ID

   # This will show your team ID
   security find-identity -v -p codesigning
   

4. Generate App-Specific Password

   • Go to appleid.apple.com
   • Sign in with your Apple ID
   • Go to "Security" → "App-Specific Passwords"
   • Generate a new password for Electron building

5. Get Certificate Hash

   # Get the SHA1 hash of your certificate
   security find-certificate -c "Your Certificate Name" -p | openssl x509 -noout -fingerprint -sha1
   

🛠️ Troubleshooting

Common Issues & Solutions

Code Signing Errors

Error: Failed to codesign your application

Solution: Use development build mode:

./scripts/build-moreminimore-app.sh

Missing Logo Files

Error: Source logo not found: assets/moreminimorelogo.png

Solution: Ensure your logo is present:

# Place your logo at:
assets/moreminimorelogo.png

TypeScript Compilation Errors

Error: TypeScript compilation failed

Solution: Check compilation manually:

npm run ts

Dependency Issues

Error: npm install failed

Solution: Clean and reinstall:

rm -rf node_modules package-lock.json
npm install

Build Permission Errors

Error: Permission denied

Solution: Make script executable:

chmod +x scripts/build-moreminimore-app.sh

Debug Mode

For detailed troubleshooting:

./scripts/build-moreminimore-app.sh --verbose

This will show:

• Detailed npm output
• Electron Forge debug logs
• Step-by-step build process
• Error stack traces

🔄 Build Process Flow

1. Environment Setup
   ├── Parse command line arguments
   ├── Set code signing mode
   └── Configure debug options

2. Prerequisites Check
   ├── Verify Node.js and npm
   ├── Check package.json exists
   ├── Validate logo files
   └── Generate logos if needed

3. Dependency Management
   ├── Install npm dependencies
   └── Verify installation success

4. Build Preparation
   ├── Clean previous builds
   ├── Apply custom features
   └── Verify TypeScript compilation

5. Application Build
   ├── Run Electron Forge
   ├── Package application
   └── Create distributable

6. Verification
   ├── Check build output
   ├── Verify file sizes
   └── Show results

📊 Build Performance

Typical Build Times

• Clean Build: 3-5 minutes
• Incremental Build: 1-2 minutes
• Dependency Install: 30-60 seconds

Build Sizes

• Development ZIP: ~180MB
• Production Installer: ~200MB
• Source Code: ~50MB

System Requirements

• RAM: Minimum 4GB, recommended 8GB+
• Storage: 2GB free space for build artifacts
• Network: Required for dependency installation

🎨 Integration with Workflow

Development Workflow

# 1. Update code
git pull origin main

# 2. Apply custom features
./scripts/update-and-debrand.sh

# 3. Build application
./scripts/build-moreminimore-app.sh

# 4. Test application
open out/make/zip/darwin/arm64/moreminimore-darwin-arm64-*.zip

Release Workflow

# 1. Set up production credentials
export APPLE_TEAM_ID="your-team-id"
export APPLE_ID="your-apple-id@example.com"
export APPLE_PASSWORD="your-app-password"
export SM_CODE_SIGNING_CERT_SHA1_HASH="your-cert-hash"

# 2. Build production version
./scripts/build-moreminimore-app.sh --production

# 3. Distribute
# Upload out/make/ files to your distribution platform

📝 Best Practices

Before Building

1. Update dependencies: npm update
2. Clean workspace: git clean -fd
3. Check TypeScript: npm run ts
4. Verify logos: ls -la assets/

During Development

1. Use development builds: Avoid code signing overhead
2. Enable verbose mode: For debugging issues
3. Clean regularly: Prevent artifact accumulation
4. Test builds: Verify after major changes

For Production

1. Set up credentials: Configure Apple Developer account
2. Test signing: Verify code signing works
3. Clean build: Start with fresh artifacts
4. Verify output: Test installer on clean system

🔗 Related Documentation

• Logo Integration Guide
• Debranding Script Guide
• Update Script Guide
• Custom Integration Guide

🆘 Support

If you encounter issues:

1. Check the logs: Run with --verbose flag
2. Verify prerequisites: Ensure all requirements are met
3. Clean and retry: Use --clean-only then rebuild
4. Check credentials: For production builds, verify Apple Developer setup
5. Review logs: Check both script output and npm logs

The build script is designed to handle most common issues automatically and provide clear guidance when manual intervention is needed.