ci(workflow): refactor upstream sync to mirror main branch first

Restructure the upstream-sync workflow to implement a two-step sync process:
1. Hard reset fork's main branch to match upstream/main (pure mirror)
2. Merge synced main into the integration branch

Clean merges are now pushed directly to the target branch, while PRs are
only created when merge conflicts are detected. This simplifies the process
and ensures the fork's main branch stays synchronized with upstream.

Author: deepakdgupta1

.github/workflows/upstream-sync.yml

@@ -15,6 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        MAIN_BRANCH: main
         TARGET_BRANCH: local-desktop-installation-support
         SYNC_BRANCH: upstream-sync
         UPSTREAM_URL: https://github.com/Dicklesworthstone/agentic_coding_flywheel_setup.git
@@ -25,7 +26,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          ref: ${{ env.TARGET_BRANCH }}
+          ref: ${{ env.MAIN_BRANCH }}
 
       - name: Configure Git
         run: |
@@ -42,17 +43,35 @@ jobs:
           git remote add upstream "$UPSTREAM_URL"
           git fetch upstream
 
-      - name: Prepare Sync Branch
+      # Step 1: Sync fork's main branch with upstream/main (Pure Mirror)
+      - name: Sync Main Branch with Upstream
         run: |
-          # Reset sync branch to target branch to ensure a clean slate
+          echo "Syncing fork's main branch with upstream/main..."
+          
+          # Hard reset main to match upstream/main exactly
+          git checkout "$MAIN_BRANCH"
+          git reset --hard upstream/main
+          
+          # Force push to update the fork's main branch
+          git push -f origin "$MAIN_BRANCH"
+          
+          echo "✅ Fork's main branch is now a pure mirror of upstream/main"
+
+      # Step 2: Merge main into local-desktop-installation-support
+      - name: Prepare Integration Branch
+        run: |
+          # Checkout the integration branch
+          git checkout "$TARGET_BRANCH"
+          
+          # Create/reset sync branch from target for the merge
           git checkout -B "$SYNC_BRANCH" "$TARGET_BRANCH"
 
-      - name: Merge Upstream
+      - name: Merge Main into Integration Branch
         id: merge
         continue-on-error: true
         run: |
-          # Attempt to merge. If conflicts, this will fail (exit 1)
-          if git merge upstream/main --no-edit; then
+          # Attempt to merge main (which is now synced with upstream) into the integration branch
+          if git merge "$MAIN_BRANCH" --no-edit; then
             echo "merge_status=success" >> "$GITHUB_OUTPUT"
             echo "Merge successful."
           else
@@ -66,18 +85,12 @@ jobs:
           echo "Committing conflict markers..."
           # Add all files with conflict markers
           git add .
-          git commit -m "Merge upstream/main (with conflicts)"
+          git commit -m "Merge main into $TARGET_BRANCH (with conflicts)"
 
       - name: Push Sync Branch
         run: |
           git push -f origin "$SYNC_BRANCH"
 
-      - name: Push to Target (Auto-Merge)
-        if: steps.merge.outputs.merge_status == 'success'
-        run: |
-          git push origin "$SYNC_BRANCH:$TARGET_BRANCH"
-          echo "Successfully synced to $TARGET_BRANCH"
-
       - name: Ensure Labels Exist
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -89,14 +102,22 @@ jobs:
           # Debug: List labels to verify visibility
           gh label list --repo ${{ github.repository }}
 
-      - name: Create Pull Request
+      # Step 3: Handle result based on merge status
+      - name: Push Clean Merge Directly
+        if: steps.merge.outputs.merge_status == 'success'
+        run: |
+          echo "Clean merge - pushing directly to $TARGET_BRANCH..."
+          git push origin "$SYNC_BRANCH:$TARGET_BRANCH"
+          echo "✅ Successfully synced to $TARGET_BRANCH"
+
+      - name: Create Pull Request for Conflicts
         if: steps.merge.outputs.merge_status == 'conflict'
         run: |
           # Check if PR already exists
           existing_pr=$(gh pr list --repo ${{ github.repository }} --head "$SYNC_BRANCH" --base "$TARGET_BRANCH" --json number -q '.[0].number')
           
           if [[ -z "$existing_pr" ]]; then
-            echo "Creating new PR..."
+            echo "Creating new PR for conflict resolution..."
             TITLE="⚠️ Upstream Sync (Conflicts Detected)"
             BODY="This PR syncs changes from upstream. **Conflicts were detected and committed with markers.** Please review and resolve them."
             LABELS="upstream-sync,conflict"
@@ -114,19 +135,15 @@ jobs:
              echo "Updating existing PR #$existing_pr..."
              echo "PR_URL=https://github.com/${{ github.repository }}/pull/$existing_pr" >> "$GITHUB_ENV"
              
-             # Update comments/labels if status changed
-             gh pr edit "$existing_pr" --repo ${{ github.repository }} --title "⚠️ Upstream Sync (Conflicts Detected)" --add-label "conflict" --body "Updates from upstream. Conflicts detected."
+             gh pr edit "$existing_pr" --repo ${{ github.repository }} \
+               --title "⚠️ Upstream Sync (Conflicts Detected)" \
+               --add-label "conflict" \
+               --body "Updates from upstream. Conflicts detected."
           fi
 
       - name: Analyze Conflicts with AI
         if: steps.merge.outputs.merge_status == 'conflict' && env.OPENAI_API_KEY != ''
         run: |
           echo "Analyzing conflicts..."
-          # We need to install dependencies for the script if any
-          # For now assuming simple script or checking for package.json
-          
           # Run the analysis script
-          # Passing PR URL or Number potentially needed for the script to post comments
-          # Actually, if we use gh cli in the script, we just need GH_TOKEN
-          
-          bun run ./scripts/analyze-conflicts.ts "${{ env.PR_URL }}"
+          bun run ./scripts/analyze-conflicts.ts "${{ env.PR_URL }}"