@sriinnu/runic 1.0.0

package/Scripts/DIRECTORY-STRUCTURE.md

@@ -0,0 +1,358 @@
+# Runic Scripts Directory Structure
+
+## Complete Overview
+
+```
+scripts/
+├── Setup Scripts (One-time initialization)
+│   ├── setup-all.sh ⭐          # One-command setup for everything
+│   ├── setup-ios.sh             # iOS Xcode project setup
+│   └── setup-react-native.sh   # React Native (Android/Windows) setup
+│
+├── Build Scripts (Daily development)
+│   ├── build-macos.sh           # Build macOS application
+│   ├── build-ios.sh             # Build iOS application
+│   ├── build-android.sh         # Build Android application
+│   └── build-windows.sh         # Build Windows application
+│
+├── CI/CD Configuration
+│   └── ci-config.yml            # GitHub Actions workflow template
+│
+├── Documentation
+│   ├── README-SCRIPTS.md ⭐     # Comprehensive documentation (19K)
+│   ├── QUICK-REFERENCE.md       # Quick reference card
+│   ├── CREATION-SUMMARY.md      # What was created
+│   └── DIRECTORY-STRUCTURE.md   # This file
+│
+└── Legacy Scripts (Pre-existing)
+    ├── build_icon.sh
+    ├── changelog-to-html.sh
+    ├── check-release-assets.sh
+    ├── compile_and_run_adhoc.sh
+    ├── compile_and_run.sh
+    ├── docs-list.mjs
+    ├── make_appcast.sh
+    ├── package_app.sh
+    ├── release.sh
+    ├── sign-and-notarize.sh
+    ├── test_live_update.sh
+    ├── validate_changelog.sh
+    └── verify_appcast.sh
+```
+
+## New Files Created (11 files)
+
+### Executable Scripts (7)
+1. ✅ `setup-all.sh` - 9.4K - Master setup orchestrator
+2. ✅ `setup-ios.sh` - 11K - iOS project initialization
+3. ✅ `setup-react-native.sh` - 14K - React Native setup
+4. ✅ `build-macos.sh` - 14K - macOS build automation
+5. ✅ `build-ios.sh` - 13K - iOS build automation
+6. ✅ `build-android.sh` - 13K - Android build automation
+7. ✅ `build-windows.sh` - 14K - Windows build automation
+
+### Configuration Files (1)
+8. ✅ `ci-config.yml` - 15K - GitHub Actions workflow
+
+### Documentation (3)
+9. ✅ `README-SCRIPTS.md` - 19K - Main documentation
+10. ✅ `QUICK-REFERENCE.md` - 2K - Quick reference
+11. ✅ `CREATION-SUMMARY.md` - 3K - Creation summary
+
+## Build Artifacts Output Structure
+
+```
+builds/
+├── macos/
+│   ├── Runic.app/              # macOS application bundle
+│   │   ├── Contents/
+│   │   │   ├── MacOS/
+│   │   │   │   └── Runic       # Executable
+│   │   │   ├── Resources/
+│   │   │   │   └── Icon.icns
+│   │   │   └── Info.plist
+│   │   └── ...
+│   └── Runic-1.0.0-macos.zip  # Distribution archive
+│
+├── ios/
+│   ├── DerivedData/            # Build products
+│   ├── RuniciOS.xcarchive/     # Archive (if --archive)
+│   └── Export/                 # IPA files
+│       └── RuniciOS.ipa
+│
+├── android/
+│   ├── app-debug.apk           # Debug APK
+│   ├── app-release.apk         # Release APK
+│   └── app-release.aab         # App Bundle (if --aab)
+│
+└── windows/
+    ├── RunicApp.exe            # Windows executable
+    ├── *.dll                   # Dependencies
+    └── Runic-1.0.0-Windows-x64.zip  # Distribution package
+```
+
+## Workflow Integration
+
+```
+.github/
+└── workflows/
+    └── ci.yml                  # Copy from scripts/ci-config.yml
+```
+
+## Script Execution Flow
+
+### Setup Flow
+```
+setup-all.sh
+├── Detect Platform
+├── setup-macos (macOS only)
+│   └── swift package resolve
+├── setup-ios.sh
+│   ├── Check Xcode
+│   ├── Install CocoaPods
+│   └── Setup code signing
+└── setup-react-native.sh
+    ├── Install npm dependencies
+    ├── Setup Android SDK
+    └── Initialize Windows (if Windows)
+```
+
+### Build Flow
+```
+build-macos.sh
+├── Check Prerequisites
+├── Clean Build (if --clean)
+├── Run SwiftLint
+├── Run Tests (unless --skip-tests)
+├── Build Application
+├── Create App Bundle
+├── Sign (unless --skip-signing)
+└── Create ZIP Archive
+
+build-ios.sh
+├── Check Prerequisites
+├── Clean Build (if --clean)
+├── Run Tests (unless --skip-tests)
+├── Build for Simulator/Device
+├── Create Archive (if --archive)
+└── Export IPA (if --archive)
+
+build-android.sh
+├── Check Prerequisites
+├── Setup Environment
+├── Clean Build (if --clean)
+├── Run Lint (unless --skip-lint)
+├── Run Tests (unless --skip-tests)
+└── Build APK/AAB
+
+build-windows.sh
+├── Check Prerequisites
+├── Setup Environment
+├── Clean Build (if --clean)
+├── Run Tests (unless --skip-tests)
+├── Build Windows App
+└── Create Distribution Package
+```
+
+## CI/CD Flow
+
+```
+GitHub Actions (ci-config.yml)
+├── Code Quality Checks
+│   ├── ESLint
+│   ├── Prettier
+│   └── TypeScript
+│
+├── Parallel Builds
+│   ├── build-macos
+│   │   ├── SwiftLint
+│   │   ├── Tests
+│   │   └── Build
+│   │
+│   ├── build-ios
+│   │   ├── Tests
+│   │   └── Build
+│   │
+│   ├── build-android
+│   │   ├── Lint
+│   │   ├── Tests
+│   │   └── Build
+│   │
+│   └── build-windows
+│       ├── Tests
+│       └── Build
+│
+├── Upload Artifacts
+│   ├── macOS .app + .zip
+│   ├── iOS builds
+│   ├── Android APK/AAB
+│   └── Windows executable
+│
+├── Deploy (if triggered)
+│   ├── TestFlight (iOS)
+│   └── Play Console (Android)
+│
+└── Build Summary
+    └── Status report
+```
+
+## Usage Patterns
+
+### First Time Setup
+```bash
+# 1. Clone repository
+git clone <repo-url>
+cd Runic
+
+# 2. Run setup
+./scripts/setup-all.sh --verbose
+
+# 3. Configure code signing (if needed)
+# See README-SCRIPTS.md for instructions
+
+# 4. Build
+./scripts/build-macos.sh
+```
+
+### Daily Development
+```bash
+# Quick build
+./scripts/build-macos.sh --skip-tests --skip-signing
+
+# Test build
+./scripts/build-macos.sh --dry-run --verbose
+
+# Full build
+./scripts/build-macos.sh
+```
+
+### Release Preparation
+```bash
+# 1. Update version
+echo "VERSION=1.2.3" > version.env
+
+# 2. Build all platforms
+./scripts/build-macos.sh
+./scripts/build-ios.sh --archive
+./scripts/build-android.sh --aab
+./scripts/build-windows.sh
+
+# 3. Test artifacts
+ls -lh builds/macos/*.zip
+ls -lh builds/ios/Export/*.ipa
+ls -lh builds/android/*.aab
+ls -lh builds/windows/*.zip
+```
+
+### CI/CD Setup
+```bash
+# 1. Copy workflow
+mkdir -p .github/workflows
+cp scripts/ci-config.yml .github/workflows/ci.yml
+
+# 2. Configure secrets (see README-SCRIPTS.md)
+
+# 3. Push
+git add .github/workflows/ci.yml
+git commit -m "Add CI/CD"
+git push
+
+# 4. Watch builds in GitHub Actions tab
+```
+
+## File Permissions
+
+All new shell scripts are executable:
+```bash
+$ ls -la scripts/*.sh
+-rwxr-xr-x  setup-all.sh
+-rwxr-xr-x  setup-ios.sh
+-rwxr-xr-x  setup-react-native.sh
+-rwxr-xr-x  build-macos.sh
+-rwxr-xr-x  build-ios.sh
+-rwxr-xr-x  build-android.sh
+-rwxr-xr-x  build-windows.sh
+```
+
+## Documentation Hierarchy
+
+```
+README-SCRIPTS.md (⭐ Start here)
+├── Overview
+├── Quick Start
+├── Setup Scripts
+│   ├── setup-all.sh guide
+│   ├── setup-ios.sh guide
+│   └── setup-react-native.sh guide
+├── Build Scripts
+│   ├── build-macos.sh guide
+│   ├── build-ios.sh guide
+│   ├── build-android.sh guide
+│   └── build-windows.sh guide
+├── CI/CD Configuration
+│   └── ci-config.yml guide
+├── Platform-Specific Guides
+│   ├── macOS Development
+│   ├── iOS Development
+│   ├── Android Development
+│   └── Windows Development
+├── GitHub Secrets Configuration
+├── Troubleshooting
+└── Advanced Usage
+
+QUICK-REFERENCE.md (Quick lookup)
+├── One-line commands
+├── Common flags
+├── Build outputs
+└── Troubleshooting
+
+CREATION-SUMMARY.md (What was built)
+├── File list
+├── Features
+├── Usage examples
+└── Quality metrics
+
+DIRECTORY-STRUCTURE.md (This file)
+└── Visual organization
+```
+
+## Key Features Map
+
+```
+All Scripts Share:
+├── ✅ Error Handling (set -e, set -u)
+├── ✅ Color Output (terminal detection)
+├── ✅ Dry-Run Mode (--dry-run)
+├── ✅ Verbose Mode (--verbose)
+├── ✅ Help System (--help)
+├── ✅ Prerequisites Checking
+├── ✅ Clear Error Messages
+└── ✅ Build Summaries
+
+Platform Coverage:
+├── ✅ macOS (Native Swift)
+├── ✅ iOS (Native iOS)
+├── ✅ Android (React Native)
+└── ✅ Windows (React Native Windows)
+
+CI/CD Features:
+├── ✅ GitHub Actions Integration
+├── ✅ Build Matrix (All Platforms)
+├── ✅ Automated Testing
+├── ✅ Code Quality Checks
+├── ✅ Artifact Management
+└── ✅ Deployment Support
+```
+
+## Quick Navigation
+
+- **Getting Started**: `README-SCRIPTS.md` → Quick Start
+- **Daily Use**: `QUICK-REFERENCE.md`
+- **Troubleshooting**: `README-SCRIPTS.md` → Troubleshooting
+- **CI/CD Setup**: `README-SCRIPTS.md` → CI/CD Configuration
+- **Code Signing**: `README-SCRIPTS.md` → Platform-Specific Guides
+- **Advanced Usage**: `README-SCRIPTS.md` → Advanced Usage
+
+---
+
+**Total**: 11 new files, ~7,330 lines, production-ready build automation! 🚀

package/Scripts/GETTING-STARTED-CHECKLIST.md

@@ -0,0 +1,364 @@
+# Getting Started with Runic Build Scripts - Checklist
+
+Use this checklist to set up and start building Runic across all platforms.
+
+## Prerequisites Checklist
+
+### For All Platforms
+- [ ] Git installed
+- [ ] Clone Runic repository
+- [ ] Navigate to project directory: `cd Runic`
+
+### For macOS/iOS Development
+- [ ] Running on macOS 14.0 or later
+- [ ] Xcode 15.0 or later installed
+- [ ] Command Line Tools installed: `xcode-select --install`
+- [ ] Xcode configured: `sudo xcode-select --switch /Applications/Xcode.app`
+
+### For Android Development
+- [ ] Java Development Kit 17 installed ([Download](https://adoptium.net))
+- [ ] Android Studio installed (or Android SDK)
+- [ ] ANDROID_HOME environment variable set
+  ```bash
+  export ANDROID_HOME=$HOME/Library/Android/sdk
+  export PATH=$PATH:$ANDROID_HOME/platform-tools
+  ```
+- [ ] Add to `~/.bashrc` or `~/.zshrc` to persist
+
+### For React Native Development
+- [ ] Node.js 18+ installed ([Download](https://nodejs.org) or use nvm)
+- [ ] npm or yarn installed
+- [ ] Watchman installed (macOS): `brew install watchman`
+
+### For Windows Development
+- [ ] Windows 10 or later
+- [ ] Visual Studio 2022 with C++ development tools
+- [ ] Windows 10 SDK (10.0.19041.0 or higher)
+- [ ] Node.js 18+ installed
+
+---
+
+## First-Time Setup Checklist
+
+### Step 1: Make Scripts Executable
+```bash
+chmod +x scripts/*.sh
+```
+- [ ] Scripts are executable
+
+### Step 2: Read Documentation
+- [ ] Skim `scripts/README-SCRIPTS.md`
+- [ ] Bookmark `scripts/QUICK-REFERENCE.md`
+- [ ] Review `scripts/DIRECTORY-STRUCTURE.md`
+
+### Step 3: Test Setup with Dry-Run
+```bash
+./scripts/setup-all.sh --dry-run --verbose
+```
+- [ ] Dry-run completes without errors
+- [ ] Review what will be executed
+- [ ] Verify all prerequisites are satisfied
+
+### Step 4: Run Actual Setup
+```bash
+./scripts/setup-all.sh --verbose
+```
+- [ ] Setup completes successfully
+- [ ] Dependencies installed
+- [ ] Configuration files created
+
+---
+
+## Code Signing Setup Checklist
+
+### iOS Code Signing
+- [ ] Apple Developer account created
+- [ ] Team ID obtained
+- [ ] Open Xcode project: `open RuniciOS/*.xcodeproj`
+- [ ] Select target → Signing & Capabilities
+- [ ] Choose team
+- [ ] Enable "Automatically manage signing"
+- [ ] Edit `RuniciOS/Config.xcconfig` with team ID
+- [ ] Test build: `./scripts/build-ios.sh --simulator`
+
+### Android Code Signing
+```bash
+# Generate keystore
+keytool -genkey -v -keystore release.keystore \
+  -alias runic-key -keyalg RSA -keysize 2048 -validity 10000
+```
+- [ ] Keystore generated
+- [ ] Create `runic-cross-platform/android/keystore.properties`:
+  ```properties
+  storePassword=YOUR_PASSWORD
+  keyPassword=YOUR_PASSWORD
+  keyAlias=runic-key
+  storeFile=release.keystore
+  ```
+- [ ] Update `android/app/build.gradle` (see README-SCRIPTS.md)
+- [ ] Test signed build: `./scripts/build-android.sh --variant release`
+
+---
+
+## First Build Checklist
+
+### macOS Build
+```bash
+./scripts/build-macos.sh --verbose
+```
+- [ ] Build completes successfully
+- [ ] App bundle created: `builds/macos/Runic.app`
+- [ ] ZIP archive created: `builds/macos/Runic-*.zip`
+- [ ] Test run: `open builds/macos/Runic.app`
+
+### iOS Build (Simulator)
+```bash
+./scripts/build-ios.sh --simulator --verbose
+```
+- [ ] Build completes successfully
+- [ ] Build products in `builds/ios/DerivedData/`
+- [ ] Open in Xcode and run on simulator
+
+### iOS Build (Device)
+```bash
+./scripts/build-ios.sh --device --archive --verbose
+```
+- [ ] Build completes successfully
+- [ ] Archive created: `builds/ios/RuniciOS.xcarchive`
+- [ ] IPA exported (if signed): `builds/ios/Export/*.ipa`
+
+### Android Build
+```bash
+./scripts/build-android.sh --variant debug --verbose
+```
+- [ ] Build completes successfully
+- [ ] APK created: `builds/android/app-debug.apk`
+- [ ] Install on device: `adb install builds/android/app-debug.apk`
+
+### Windows Build
+```bash
+./scripts/build-windows.sh --verbose
+```
+- [ ] Build completes successfully
+- [ ] Executable in `builds/windows/`
+- [ ] Test on Windows
+
+---
+
+## CI/CD Setup Checklist
+
+### Step 1: Copy Workflow
+```bash
+mkdir -p .github/workflows
+cp scripts/ci-config.yml .github/workflows/ci.yml
+```
+- [ ] Workflow file copied
+
+### Step 2: Configure GitHub Secrets
+
+#### iOS Secrets
+- [ ] Export certificate as P12
+- [ ] Base64 encode: `base64 -i certificate.p12 -o cert.txt`
+- [ ] Add to GitHub secrets: `IOS_CERTIFICATE_P12`
+- [ ] Add password: `IOS_CERTIFICATE_PASSWORD`
+- [ ] Export provisioning profile
+- [ ] Base64 encode: `base64 -i profile.mobileprovision -o profile.txt`
+- [ ] Add to GitHub secrets: `IOS_PROVISIONING_PROFILE`
+- [ ] (Optional) Add App Store Connect API key: `APP_STORE_CONNECT_API_KEY`
+
+#### Android Secrets
+- [ ] Base64 encode keystore: `base64 -i release.keystore -o keystore.txt`
+- [ ] Add to GitHub secrets: `ANDROID_KEYSTORE_BASE64`
+- [ ] Add keystore password: `ANDROID_KEYSTORE_PASSWORD`
+- [ ] Add key alias: `ANDROID_KEY_ALIAS`
+- [ ] Add key password: `ANDROID_KEY_PASSWORD`
+- [ ] (Optional) Add Play Console service account: `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON`
+
+### Step 3: Test CI/CD
+- [ ] Commit workflow: `git add .github/workflows/ci.yml`
+- [ ] Push: `git push`
+- [ ] Check GitHub Actions tab
+- [ ] Verify all jobs pass
+- [ ] Download artifacts
+
+---
+
+## Daily Development Workflow Checklist
+
+### Morning Routine
+- [ ] Pull latest changes: `git pull`
+- [ ] Update dependencies (if needed):
+  ```bash
+  swift package update          # macOS
+  cd RuniciOS && pod update     # iOS
+  cd runic-cross-platform && npm update  # React Native
+  ```
+
+### Development Builds
+- [ ] macOS: `./scripts/build-macos.sh --skip-tests --skip-signing`
+- [ ] iOS: `./scripts/build-ios.sh --simulator --skip-tests`
+- [ ] Android: `./scripts/build-android.sh --variant debug --skip-tests`
+- [ ] Windows: `./scripts/build-windows.sh --configuration Debug --skip-tests`
+
+### Before Committing
+- [ ] Run tests:
+  ```bash
+  swift test                    # macOS
+  npm test                      # React Native
+  ```
+- [ ] Run linters:
+  ```bash
+  swiftlint lint                # Swift
+  cd runic-cross-platform && npm run lint  # JavaScript
+  ```
+- [ ] Format code:
+  ```bash
+  swiftformat .                 # Swift
+  cd runic-cross-platform && npm run format  # JavaScript
+  ```
+- [ ] Commit changes
+- [ ] Push to trigger CI
+
+---
+
+## Release Workflow Checklist
+
+### Pre-Release
+- [ ] Update version number in `version.env`
+- [ ] Update CHANGELOG.md
+- [ ] Create release branch: `git checkout -b release/1.2.3`
+- [ ] Update version strings in:
+  - [ ] `version.env`
+  - [ ] iOS `Info.plist` or project settings
+  - [ ] Android `build.gradle` (versionCode, versionName)
+
+### Build Release Artifacts
+- [ ] macOS: `./scripts/build-macos.sh --clean`
+- [ ] iOS: `./scripts/build-ios.sh --archive --clean`
+- [ ] Android APK: `./scripts/build-android.sh --variant release --clean`
+- [ ] Android AAB: `./scripts/build-android.sh --aab --clean`
+- [ ] Windows: `./scripts/build-windows.sh --clean`
+
+### Test Release Builds
+- [ ] Test macOS app: `open builds/macos/Runic.app`
+- [ ] Test iOS on device
+- [ ] Test Android APK: `adb install builds/android/app-release.apk`
+- [ ] Test Windows executable
+
+### Deploy
+- [ ] macOS: Upload to website/distribution platform
+- [ ] iOS: Upload to TestFlight
+  ```bash
+  xcrun altool --upload-app -f builds/ios/Export/RuniciOS.ipa \
+    -t ios -u username -p password
+  ```
+- [ ] Android: Upload AAB to Play Console
+- [ ] Windows: Create installer and distribute
+
+### Post-Release
+- [ ] Tag release: `git tag v1.2.3`
+- [ ] Push tag: `git push origin v1.2.3`
+- [ ] Create GitHub release
+- [ ] Attach build artifacts to release
+- [ ] Merge release branch to main
+- [ ] Update documentation if needed
+
+---
+
+## Troubleshooting Checklist
+
+### If Build Fails
+
+1. **Try Dry-Run First**
+   ```bash
+   ./scripts/build-macos.sh --dry-run --verbose
+   ```
+   - [ ] Dry-run shows what will execute
+   - [ ] Prerequisites are satisfied
+
+2. **Check Prerequisites**
+   ```bash
+   ./scripts/setup-all.sh --dry-run --verbose
+   ```
+   - [ ] All required tools installed
+   - [ ] Versions are correct
+
+3. **Clean Build**
+   ```bash
+   ./scripts/build-macos.sh --clean --verbose
+   ```
+   - [ ] Old build artifacts removed
+   - [ ] Fresh build succeeds
+
+4. **Read Error Messages**
+   - [ ] Error message explains the issue
+   - [ ] Follow suggested solution
+   - [ ] Check README-SCRIPTS.md troubleshooting section
+
+5. **Check Documentation**
+   - [ ] Review `scripts/README-SCRIPTS.md`
+   - [ ] Check platform-specific guide
+   - [ ] Search for similar issues
+
+---
+
+## Additional Resources Checklist
+
+### Documentation
+- [ ] `scripts/README-SCRIPTS.md` - Complete guide
+- [ ] `scripts/QUICK-REFERENCE.md` - Quick commands
+- [ ] `scripts/CREATION-SUMMARY.md` - What was created
+- [ ] `scripts/DIRECTORY-STRUCTURE.md` - File organization
+- [ ] `scripts/GETTING-STARTED-CHECKLIST.md` - This file
+
+### Help Commands
+- [ ] Setup help: `./scripts/setup-all.sh --help`
+- [ ] Build help: `./scripts/build-macos.sh --help`
+- [ ] Dry-run: `./scripts/build-macos.sh --dry-run --verbose`
+
+### Online Resources
+- [ ] Xcode documentation
+- [ ] React Native documentation
+- [ ] Android developer guide
+- [ ] GitHub Actions documentation
+
+---
+
+## Success Criteria
+
+You've successfully set up Runic build scripts when:
+
+- ✅ All setup scripts run without errors
+- ✅ All build scripts produce artifacts
+- ✅ CI/CD workflow passes on GitHub
+- ✅ Code signing works for release builds
+- ✅ Applications run on target platforms
+
+**Congratulations! You're ready to build Runic across all platforms! 🎉**
+
+---
+
+## Need Help?
+
+1. **Check Documentation**
+   ```bash
+   cat scripts/README-SCRIPTS.md
+   cat scripts/QUICK-REFERENCE.md
+   ```
+
+2. **Run with Verbose**
+   ```bash
+   ./scripts/build-macos.sh --verbose --dry-run
+   ```
+
+3. **Review Troubleshooting**
+   - See `scripts/README-SCRIPTS.md` → Troubleshooting section
+
+4. **Open an Issue**
+   - Include script output
+   - Include system information
+   - Include `--verbose` logs
+
+---
+
+**Remember**: Start with `--dry-run` and `--verbose` to understand what scripts do before executing them!