Fix conflicts in pnpm lock file during merges

.gitattributes

@@ -0,0 +1,4 @@
+# Auto-resolve pnpm lockfile conflicts
+# Use 'union' merge strategy which combines both sides
+# Then run 'pnpm install' to regenerate the lockfile correctly
+pnpm-lock.yaml merge=union

README.md

@@ -45,14 +45,23 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
 
 ## ⚡ Quick Start
 
-### 1. Installation
+### 1. Setup Development Environment
+
+```bash
+# For contributors: Setup automatic pnpm-lock.yaml merge conflict resolution
+./scripts/setup-merge-driver.sh
+```
+
+📖 **Having issues with pnpm-lock.yaml merge conflicts?** See [pnpm Lock Conflict Resolution Guide](./docs/pnpm-lock-conflict-resolution.md)
+
+### 2. Installation
 
 ```bash
 # Install core and a driver (e.g., Postgres or SQLite)
 npm install @objectql/core @objectql/driver-sql sqlite3
 ```
 
-### 2. The Universal Script
+### 3. The Universal Script
 
 ObjectQL can run in a single file without complex configuration.
 

docs/pnpm-lock-conflict-resolution.md

@@ -0,0 +1,196 @@
+# pnpm Lock File Merge Conflict Resolution
+
+## Problem
+
+When multiple developers work on the same repository and modify dependencies in parallel, merging branches often results in conflicts in the `pnpm-lock.yaml` file. These conflicts can be tedious to resolve manually.
+
+## Solution
+
+This repository uses an **automated conflict resolution strategy** for `pnpm-lock.yaml`:
+
+1. **Union Merge Strategy**: Git automatically combines both versions of the lockfile
+2. **Post-Merge Hook**: Automatically runs `pnpm install` after merges to regenerate a valid lockfile
+3. **Version Enforcement**: The repository requires `pnpm >= 10.0.0` to ensure consistency
+
+## How It Works
+
+The solution uses Git's built-in `union` merge strategy combined with a post-merge hook:
+
+1. **`.gitattributes`**: Configures pnpm-lock.yaml to use union merge (combines both sides)
+2. **`.git/hooks/post-merge`**: Automatically runs `pnpm install` after any merge that touches pnpm-lock.yaml
+3. **`package.json`**: Enforces pnpm version consistency across all developers
+
+## Setup Instructions
+
+### For Developers
+
+After cloning this repository, run the setup script once:
+
+```bash
+./scripts/setup-merge-driver.sh
+```
+
+This will:
+- Create a post-merge Git hook that auto-runs `pnpm install` after merges
+- Display helpful information about how the system works
+
+### What Happens During a Merge?
+
+When you merge a branch that has changes in `pnpm-lock.yaml`:
+
+1. Git uses the `union` strategy to combine both versions of the lockfile
+2. The merge completes without stopping for manual conflict resolution
+3. The post-merge hook automatically runs `pnpm install --no-frozen-lockfile`
+4. pnpm regenerates a correct lockfile based on all package.json files
+5. You review the changes and commit if needed
+
+### Example Workflow
+
+```bash
+# Start merging a branch
+git merge feature-branch
+
+# Git automatically:
+# 1. ✅ Combines both versions of pnpm-lock.yaml
+# 2. ✅ Completes the merge
+# 3. ✅ Runs pnpm install automatically (via post-merge hook)
+
+# You see:
+# 📦 pnpm-lock.yaml was updated in merge, running pnpm install...
+# ✅ Dependencies synchronized
+
+# Review the changes
+git status
+git diff pnpm-lock.yaml
+
+# If pnpm-lock.yaml was modified by pnpm install, commit it
+git add pnpm-lock.yaml
+git commit -m "chore: update pnpm-lock.yaml after merge"
+```
+
+### Important Notes
+
+⚠️ **Prerequisites:**
+- You must have `pnpm` installed and available in your PATH
+- The repository enforces `pnpm >= 10.0.0` (see `package.json` engines field)
+- Run `./scripts/setup-merge-driver.sh` once after cloning
+
+⚠️ **Package.json Conflicts:**
+- If there are conflicts in `package.json` files, you must resolve those manually **first**
+- After resolving package.json conflicts, run `pnpm install` manually
+- Then complete the merge
+
+⚠️ **Review After Merge:**
+- Always review the regenerated `pnpm-lock.yaml` to ensure dependencies are correct
+- The post-merge hook will remind you to review and commit changes
+- Run tests after merging to verify everything works as expected
+
+## Manual Resolution (Fallback)
+
+If you prefer manual resolution or if the automatic process fails:
+
+1. Resolve any `package.json` conflicts first
+2. Run `pnpm install` to regenerate the lockfile:
+   ```bash
+   pnpm install --no-frozen-lockfile
+   ```
+3. Stage and commit the regenerated lockfile:
+   ```bash
+   git add pnpm-lock.yaml
+   git commit -m "chore: regenerate pnpm-lock.yaml"
+   ```
+
+## Version Consistency
+
+To prevent lockfile conflicts caused by different pnpm versions, this repository:
+
+- Specifies `packageManager: "pnpm@10.0.0"` in `package.json`
+- Requires `pnpm >= 10.0.0` in the `engines` field
+- Uses `pnpm@10` in GitHub Actions CI
+
+All developers should use the same major version of pnpm. Consider using [Corepack](https://nodejs.org/api/corepack.html) to automatically use the correct pnpm version:
+
+```bash
+corepack enable
+corepack prepare pnpm@10.0.0 --activate
+```
+
+## Troubleshooting
+
+### "pnpm is not installed"
+
+Install pnpm globally:
+
+```bash
+npm install -g pnpm@10
+```
+
+Or use Corepack:
+
+```bash
+corepack enable
+corepack prepare pnpm@10.0.0 --activate
+```
+
+### Post-merge hook not running
+
+1. Verify the hook is installed and executable:
+   ```bash
+   ls -la .git/hooks/post-merge
+   ```
+
+2. Re-run the setup script:
+   ```bash
+   ./scripts/setup-merge-driver.sh
+   ```
+
+3. Make sure you're using `git merge` (hooks don't run with some Git GUI tools)
+
+### pnpm install fails after merge
+
+1. Check that you have no `package.json` conflicts remaining:
+   ```bash
+   git status
+   ```
+
+2. Resolve any package.json conflicts manually
+
+3. Run `pnpm install` manually:
+   ```bash
+   pnpm install --no-frozen-lockfile
+   ```
+
+4. Complete the merge:
+   ```bash
+   git add pnpm-lock.yaml
+   git commit
+   ```
+
+### Want to disable automatic pnpm install?
+
+If you prefer to run `pnpm install` manually after merges:
+
+```bash
+rm .git/hooks/post-merge
+```
+
+The union merge strategy will still work, you'll just need to run `pnpm install` yourself.
+
+## CI/CD Integration
+
+The GitHub Actions workflows in this repository already use pnpm@10 consistently. No additional CI configuration is needed.
+
+## How This Compares to Other Solutions
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Union merge + hook** (This repo) | ✅ Simple<br>✅ Reliable<br>✅ No custom code<br>✅ Works with all Git tools | ⚠️ Requires one-time setup<br>⚠️ May need manual commit |
+| **Custom merge driver** | ✅ Fully automatic | ❌ Complex<br>❌ Hard to debug<br>❌ May fail silently |
+| **Manual resolution** | ✅ Full control | ❌ Tedious<br>❌ Error-prone<br>❌ Slows down workflow |
+| **Always use ours/theirs** | ✅ Never blocks | ❌ Loses changes<br>❌ Must always regenerate |
+
+## References
+
+- [pnpm - Working with Git](https://pnpm.io/git)
+- [Git Attributes - Merge Strategies](https://git-scm.com/docs/gitattributes#_built_in_merge_drivers)
+- [Git Hooks - post-merge](https://git-scm.com/docs/githooks#_post_merge)

docs/pnpm-lock-test-results.md

@@ -0,0 +1,83 @@
+# pnpm Lock Merge Conflict Resolution - Test Results
+
+## Test Date
+2026-01-15
+
+## Test Scenario
+
+Simulated a realistic merge conflict scenario where:
+- **Branch A**: Added `lodash@^4.17.21` to `packages/foundation/types/package.json`
+- **Branch B**: Added `axios@^1.6.0` to `packages/foundation/core/package.json`
+- Both branches modified `pnpm-lock.yaml`
+
+## Test Execution
+
+### Setup
+1. Installed pnpm@10.0.0
+2. Ran `./scripts/setup-merge-driver.sh` to configure Git hooks
+3. Created two diverging branches with different dependency changes
+
+### Merge Process
+```bash
+# Branch A changes
+- Modified: packages/foundation/types/package.json
+- Modified: pnpm-lock.yaml
+- Committed: "test: add lodash dependency"
+
+# Branch B changes  
+- Modified: packages/foundation/core/package.json
+- Modified: pnpm-lock.yaml
+- Committed: "test: add axios dependency"
+
+# Merge
+$ git merge test-branch --no-edit
+Auto-merging pnpm-lock.yaml
+Merge made by the 'ort' strategy.
+ packages/foundation/types/package.json | 3 ++-
+ pnpm-lock.yaml                         | 3 +++
+ 2 files changed, 5 insertions(+), 1 deletion(-)
+```
+
+### Post-Merge Hook Execution
+```bash
+📦 pnpm-lock.yaml was updated in merge, running pnpm install...
+Scope: all 22 workspace projects
+Lockfile is up to date, resolution step is skipped
+Already up to date
+
+Done in 1.2s
+✅ Dependencies synchronized
+⚠️  Please review pnpm-lock.yaml and commit if needed
+```
+
+## Verification Results
+
+### ✅ Dependency Verification
+- **lodash**: Found in `packages/foundation/types/package.json` ✓
+- **axios**: Found in `packages/foundation/core/package.json` ✓
+
+### ✅ Lockfile Validation
+```bash
+$ pnpm install --frozen-lockfile
+# Result: Success - lockfile is valid and consistent
+```
+
+### ✅ Merge Completion
+- No manual conflict resolution required
+- No merge conflicts left unresolved
+- Both branches' changes were preserved correctly
+
+## Test Result
+
+**✅ PASSED** - All verification checks successful
+
+The automated pnpm lock merge conflict resolution:
+1. Successfully merged conflicting lockfile changes using union strategy
+2. Automatically ran pnpm install via post-merge hook
+3. Generated a valid, consistent lockfile
+4. Preserved all dependency changes from both branches
+5. Required no manual intervention
+
+## Conclusion
+
+The solution works correctly and achieves the goal of automatically resolving pnpm-lock.yaml merge conflicts without manual intervention from developers.

package.json

@@ -1,6 +1,11 @@
 {
   "name": "objectql-monorepo",
   "private": true,
+  "packageManager": "pnpm@10.0.0",
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=10.0.0"
+  },
   "scripts": {
     "build": "tsc -b && pnpm -r run build",
     "check-versions": "node scripts/check-versions.js",

scripts/pnpm-merge-driver.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# Git merge driver for pnpm-lock.yaml
+# This script automatically resolves merge conflicts in pnpm-lock.yaml
+# by regenerating the lockfile using pnpm install
+#
+# Usage: This script is called automatically by git when a merge conflict
+# occurs in pnpm-lock.yaml (configured via .gitattributes)
+#
+# Arguments (provided by git):
+# $1 - %O - ancestor's version
+# $2 - %A - current version
+# $3 - %B - other branches' version
+# $4 - %L - conflict marker size (optional)
+# $5 - %P - pathname in which the merged result will be stored
+
+set -e
+
+ANCESTOR=$1
+CURRENT=$2
+OTHER=$3
+PATHNAME=$5
+
+echo "🔄 Resolving pnpm-lock.yaml merge conflict..."
+
+# Check if pnpm is available
+if ! command -v pnpm &> /dev/null; then
+    echo "❌ Error: pnpm is not installed or not in PATH"
+    echo "Please install pnpm: npm install -g pnpm"
+    exit 1
+fi
+
+# Get the repository root directory
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# Change to repository root
+cd "$REPO_ROOT"
+
+# First, accept the current version (ours) to resolve the git conflict state
+cp "$CURRENT" "$PATHNAME"
+
+echo "📦 Regenerating pnpm-lock.yaml by running pnpm install..."
+
+# Run pnpm install to regenerate the lockfile
+# This will merge dependencies from both branches correctly
+if pnpm install --lockfile-only --no-frozen-lockfile 2>&1; then
+    echo "✅ Successfully regenerated pnpm-lock.yaml"
+
+    # Copy the regenerated lockfile to the output location
+    if [ -f "$REPO_ROOT/pnpm-lock.yaml" ]; then
+        cp "$REPO_ROOT/pnpm-lock.yaml" "$PATHNAME"
+        echo "✅ Merge conflict resolved successfully"
+        exit 0
+    else
+        echo "❌ Error: pnpm-lock.yaml not found after regeneration"
+        exit 1
+    fi
+else
+    echo "❌ Error: pnpm install failed"
+    echo "Please resolve package.json conflicts first, then run: pnpm install"
+    exit 1
+fi