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)**
```bash
./scripts/build-moreminimore-app.sh
```

### **Production Build (Requires Code Signing)**
```bash
./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**
```bash
./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**
```bash
./scripts/build-moreminimore-app.sh
```
- Disables code signing automatically
- Installs dependencies
- Builds for current platform
- Creates distributable package

#### **Production Build**
```bash
./scripts/build-moreminimore-app.sh --production
```
- Enables code signing
- Requires Apple Developer credentials
- Creates production-ready installer

#### **Clean Build Artifacts**
```bash
./scripts/build-moreminimore-app.sh --clean-only
```
- Removes `out/` directory
- Cleans scaffold node_modules
- Prepares for fresh build

#### **Verbose Debug Build**
```bash
./scripts/build-moreminimore-app.sh --verbose
```
- Shows detailed build output
- Enables Electron Forge debug logging
- Helpful for troubleshooting

#### **Fast Build (Skip Dependencies)**
```bash
./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:
```bash
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:

```bash
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](https://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**
   ```bash
   # This will show your team ID
   security find-identity -v -p codesigning
   ```

4. **Generate App-Specific Password**
   - Go to [appleid.apple.com](https://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**
   ```bash
   # 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:
```bash
./scripts/build-moreminimore-app.sh
```

#### **Missing Logo Files**
```
Error: Source logo not found: assets/moreminimorelogo.png
```
**Solution**: Ensure your logo is present:
```bash
# Place your logo at:
assets/moreminimorelogo.png
```

#### **TypeScript Compilation Errors**
```
Error: TypeScript compilation failed
```
**Solution**: Check compilation manually:
```bash
npm run ts
```

#### **Dependency Issues**
```
Error: npm install failed
```
**Solution**: Clean and reinstall:
```bash
rm -rf node_modules package-lock.json
npm install
```

#### **Build Permission Errors**
```
Error: Permission denied
```
**Solution**: Make script executable:
```bash
chmod +x scripts/build-moreminimore-app.sh
```

### **Debug Mode**
For detailed troubleshooting:
```bash
./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**
```bash
# 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**
```bash
# 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](README-LOGO-INTEGRATION.md)
- [Debranding Script Guide](README-DEBRAND.md)
- [Update Script Guide](README-UPDATE-SCRIPT.md)
- [Custom Integration Guide](README-CUSTOM-INTEGRATION.md)

## 🆘 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.