Add GitHub Actions build workflow for cross-platform binary releases

.github/workflows/build-release.yml

@@ -1,16 +1,29 @@
 name: Build and Release
 
+# Only trigger on pushes to main branch that modify code files
+# Manual workflow dispatch is also supported for testing
 on:
   push:
     branches: [ main ]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
   workflow_dispatch:
 
+env:
+  # Cache key version - increment to invalidate caches
+  CACHE_VERSION: v1
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
     permissions:
-      contents: write
+      contents: write  # Required for creating releases and uploading assets
+
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.tag.outputs.tag }}
 
     steps:
     - name: Checkout code
@@ -21,68 +34,127 @@ jobs:
       with:
         bun-version: latest
 
+    - name: Cache dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.bun/install/cache
+        key: bun-${{ env.CACHE_VERSION }}-${{ hashFiles('**/bun.lockb', '**/package.json') }}
+        restore-keys: |
+          bun-${{ env.CACHE_VERSION }}-
+
     - name: Install dependencies
-      run: bun install
+      run: bun install --frozen-lockfile
 
-    - name: Make build script executable
-      run: chmod +x build.sh
+    - name: Extract version
+      id: version
+      run: |
+        VERSION=$(cat package.json | jq -r '.version')
+        if [[ -z "$VERSION" || "$VERSION" == "null" ]]; then
+          echo "❌ Failed to extract version from package.json"
+          exit 1
+        fi
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "✅ Extracted version: $VERSION"
 
+    - name: Validate build script
+      run: |
+        if [[ ! -x "build.sh" ]]; then
+          echo "❌ build.sh is not executable"
+          exit 1
+        fi
+
     - name: Build binaries
-      run: ./build.sh
-
-    - name: List build artifacts
-      run: ls -la build/
-
-    - name: Verify all binaries were created
       run: |
-        VERSION=$(cat package.json | jq -r '.version')
-        EXPECTED_FILES=(
-          "justinstall-$VERSION-linux-x64"
-          "justinstall-$VERSION-linux-arm64" 
-          "justinstall-$VERSION-windows-x64"
-          "justinstall-$VERSION-darwin-x64"
-          "justinstall-$VERSION-darwin-arm64"
+        echo "🔨 Building binaries for version ${{ steps.version.outputs.version }}"
+        ./build.sh
+
+    - name: Verify build artifacts
+      run: |
+        VERSION="${{ steps.version.outputs.version }}"
+        BUILD_DIR="build"
+
+        # Expected binaries based on current build script behavior
+        declare -A EXPECTED_BINARIES=(
+          ["linux-x64"]="justinstall-$VERSION-linux-x64"
+          ["linux-arm64"]="justinstall-$VERSION-linux-arm64"
+          ["windows-x64"]="justinstall-$VERSION-windows-x64.exe"
+          ["darwin-x64"]="justinstall-$VERSION-darwin-x64"
+          ["darwin-arm64"]="justinstall-$VERSION-darwin-arm64"
         )
 
-        for file in "${EXPECTED_FILES[@]}"; do
-          if [[ ! -f "build/$file" ]]; then
-            echo "❌ Missing binary: build/$file"
-            exit 1
+        echo "📋 Verifying build artifacts..."
+        ALL_FOUND=true
+
+        for platform in "${!EXPECTED_BINARIES[@]}"; do
+          binary="${EXPECTED_BINARIES[$platform]}"
+          if [[ -f "$BUILD_DIR/$binary" ]]; then
+            size=$(stat -f%z "$BUILD_DIR/$binary" 2>/dev/null || stat -c%s "$BUILD_DIR/$binary" 2>/dev/null)
+            echo "✅ $platform: $binary (${size} bytes)"
           else
-            echo "✅ Found binary: build/$file"
+            echo "❌ Missing $platform binary: $binary"
+            ALL_FOUND=false
           fi
         done
+
+        if [[ "$ALL_FOUND" == "false" ]]; then
+          echo "❌ Build verification failed - some binaries are missing"
+          echo "📁 Contents of build directory:"
+          ls -la "$BUILD_DIR/" || echo "Build directory not found"
+          exit 1
+        fi
+
+        echo "✅ All expected binaries verified successfully"
 
     - name: Generate release tag
       id: tag
       run: |
-        VERSION=$(cat package.json | jq -r '.version')
-        TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+        VERSION="${{ steps.version.outputs.version }}"
+        TIMESTAMP=$(date -u +%Y%m%d-%H%M%S)
         TAG="$VERSION-$TIMESTAMP"
+
+        # Validate tag format
+        if [[ ! "$TAG" =~ ^[a-zA-Z0-9v][a-zA-Z0-9v._-]*$ ]]; then
+          echo "❌ Invalid tag format: $TAG"
+          exit 1
+        fi
+
         echo "tag=$TAG" >> $GITHUB_OUTPUT
-        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "✅ Generated release tag: $TAG"
 
     - name: Create Pre-Release
-      uses: softprops/action-gh-release@v1
+      uses: softprops/action-gh-release@v2
       with:
         tag_name: ${{ steps.tag.outputs.tag }}
         name: "Pre-release ${{ steps.tag.outputs.tag }}"
         body: |
-          Automated pre-release build from commit ${{ github.sha }}
+          🤖 **Automated pre-release build**
+
+          **Version:** `${{ steps.version.outputs.version }}`
+          **Commit:** [`${{ github.sha }}`](${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }})
+          **Build:** [#${{ github.run_number }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})
+          **Built:** ${{ steps.tag.outputs.tag }}
+
+          ## 📦 Available Binaries
+
+          | Platform | Binary | Architecture |
+          |----------|--------|--------------|
+          | Linux | `justinstall-${{ steps.version.outputs.version }}-linux-x64` | x86_64 |
+          | Linux | `justinstall-${{ steps.version.outputs.version }}-linux-arm64` | ARM64 |
+          | Windows | `justinstall-${{ steps.version.outputs.version }}-windows-x64.exe` | x86_64 |
+          | macOS | `justinstall-${{ steps.version.outputs.version }}-darwin-x64` | x86_64 |
+          | macOS | `justinstall-${{ steps.version.outputs.version }}-darwin-arm64` | ARM64 (Apple Silicon) |
+
+          ## 📥 Installation
+
+          Download the appropriate binary for your platform and add it to your PATH.
 
-          **Version:** ${{ steps.tag.outputs.version }}
-          **Built on:** ${{ github.run_id }}
-          **Commit:** ${{ github.sha }}
+          ---
 
-          ## Binaries
-          - `justinstall-${{ steps.tag.outputs.version }}-linux-x64` - Linux x64
-          - `justinstall-${{ steps.tag.outputs.version }}-linux-arm64` - Linux ARM64  
-          - `justinstall-${{ steps.tag.outputs.version }}-windows-x64` - Windows x64
-          - `justinstall-${{ steps.tag.outputs.version }}-darwin-x64` - macOS x64
-          - `justinstall-${{ steps.tag.outputs.version }}-darwin-arm64` - macOS ARM64 (Apple Silicon)
-        files: |
-          build/*
+          > This is an automated pre-release. For stable releases, see the main releases.
+        files: build/*
         prerelease: true
         draft: false
+        fail_on_unmatched_files: true
+        generate_release_notes: false
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/validate.yml

@@ -0,0 +1,59 @@
+name: Validate
+
+# Run on PRs and pushes to validate the codebase
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Bun
+      uses: oven-sh/setup-bun@v1
+      with:
+        bun-version: latest
+
+    - name: Install dependencies
+      run: bun install --frozen-lockfile
+
+    - name: Validate package.json
+      run: |
+        VERSION=$(cat package.json | jq -r '.version')
+        if [[ -z "$VERSION" || "$VERSION" == "null" ]]; then
+          echo "❌ Invalid or missing version in package.json"
+          exit 1
+        fi
+        echo "✅ Version: $VERSION"
+
+    - name: Check build script
+      run: |
+        if [[ ! -x "build.sh" ]]; then
+          echo "❌ build.sh is not executable"
+          exit 1
+        fi
+        echo "✅ build.sh is executable"
+
+    - name: Test build process
+      run: |
+        echo "🔨 Testing build process..."
+        timeout 300 ./build.sh || {
+          echo "❌ Build failed or timed out"
+          exit 1
+        }
+
+        # Quick verification that some binaries were created
+        if [[ ! -d "build" ]] || [[ -z "$(ls -A build/)" ]]; then
+          echo "❌ No build artifacts created"
+          exit 1
+        fi
+
+        echo "✅ Build test completed successfully"
+        echo "📦 Created artifacts:"
+        ls -la build/

README.md

@@ -11,14 +11,35 @@ https://github.com/Explosion-Scratch/justinstall/assets/61319150/4a05e6e0-065a-4
 Grab the binary from the github releases (ironically you can use this tool to install itself)
 
 ### Automated Builds
-This project uses GitHub Actions to automatically build binaries for all supported platforms on every push to the main branch. Pre-releases are created with binaries for:
-- Linux x64
-- Linux ARM64  
-- Windows x64
-- macOS x64
-- macOS ARM64 (Apple Silicon)
 
-You can find the latest pre-releases in the [releases page](https://github.com/Explosion-Scratch/justinstall/releases).
+This project uses GitHub Actions to automatically build cross-platform binaries whenever code changes are pushed to the main branch. The build system creates pre-releases with binaries for all supported platforms:
+
+| Platform | Architecture | Binary Name |
+|----------|--------------|-------------|
+| Linux | x86_64 | `justinstall-{version}-linux-x64` |
+| Linux | ARM64 | `justinstall-{version}-linux-arm64` |
+| Windows | x86_64 | `justinstall-{version}-windows-x64.exe` |
+| macOS | x86_64 | `justinstall-{version}-darwin-x64` |
+| macOS | ARM64 (Apple Silicon) | `justinstall-{version}-darwin-arm64` |
+
+#### Getting Pre-built Binaries
+
+1. Visit the [releases page](https://github.com/Explosion-Scratch/justinstall/releases)
+2. Look for the latest pre-release (marked with "Pre-release" tag)
+3. Download the appropriate binary for your platform
+4. Make the binary executable: `chmod +x justinstall-*` (Unix/macOS)
+5. Add it to your PATH or run directly
+
+#### Build Process
+
+The automated build process:
+- Triggers only on code changes (ignoring documentation updates)
+- Uses Bun's native compilation for optimal performance
+- Verifies all binaries are created successfully before releasing
+- Creates timestamped pre-releases to avoid version conflicts
+- Includes comprehensive build metadata and download instructions
+
+For development builds or custom compilation, see the [Building](#building) section below.
 
 ## Features
 
@@ -57,6 +78,47 @@ justinstall <github-url|file-url|local-file>
 
 ## Contributing
 
+## Building
+
+To build the project locally:
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) runtime (latest version)
+- Unix-like environment (Linux, macOS, or WSL on Windows)
+
+### Build Steps
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Explosion-Scratch/justinstall.git
+   cd justinstall
+   ```
+
+2. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+3. Build all platform binaries:
+   ```bash
+   ./build.sh
+   ```
+
+This creates optimized binaries in the `build/` directory for all supported platforms. The build script uses Bun's native compilation feature for maximum performance and minimal dependencies.
+
+### Development
+
+For development and testing:
+```bash
+# Run directly with Bun
+bun run index.js --help
+
+# Or make executable and run
+chmod +x index.js
+./index.js --help
+```
+
 Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Acknowledgements