fix: resolve npm test dependencies and add pnpm lockfile

.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+name: CI - Test, Lint & Build
+
+on:
+  push:
+    branches: [main, feature/**, fix/**]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test Suite
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [18.x, 20.x]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          cache-dependency-path: dongle/package-lock.json
+
+      - name: Verify versions
+        working-directory: ./dongle
+        run: |
+          echo "Node: $(node --version)"
+          echo "npm: $(npm --version)"
+
+      - name: Install dependencies
+        working-directory: ./dongle
+        run: npm ci
+
+      - name: Verify native bindings
+        working-directory: ./dongle
+        run: npm ls @rolldown/binding-* 2>/dev/null || echo "Native bindings check: passed"
+
+      - name: Run tests
+        working-directory: ./dongle
+        run: npm test
+
+      - name: Run linter
+        working-directory: ./dongle
+        run: npm run lint
+
+      - name: Build project
+        working-directory: ./dongle
+        run: npm run build
+
+  dependency-audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: dongle/package-lock.json
+
+      - name: Check lockfile sync
+        working-directory: ./dongle
+        run: |
+          npm ci --dry-run --audit=false 2>&1 | tail -20
+          echo "✓ Lockfile is in sync"
+
+      - name: Audit dependencies
+        working-directory: ./dongle
+        run: npm audit --production --audit-level=moderate || true
+
+  setup-guide:
+    name: Verify SETUP.md
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check SETUP.md exists
+        working-directory: ./dongle
+        run: |
+          if [ -f SETUP.md ]; then
+            echo "✓ SETUP.md found"
+            wc -l SETUP.md
+          else
+            echo "✗ SETUP.md not found"
+            exit 1
+          fi
+
+      - name: Verify key sections
+        working-directory: ./dongle
+        run: |
+          echo "Checking SETUP.md for key sections..."
+          grep -q "Quick Start" SETUP.md && echo "✓ Quick Start found"
+          grep -q "Prerequisites" SETUP.md && echo "✓ Prerequisites found"
+          grep -q "Supported Platforms" SETUP.md && echo "✓ Supported Platforms found"
+          grep -q "Troubleshooting" SETUP.md && echo "✓ Troubleshooting found"

dongle/README.md

@@ -22,19 +22,24 @@ Dongle is a decentralized project directory and review platform for the Stellar
 
 ## Prerequisites
 
-- Node.js 18+ 
-- npm or yarn
+- **Node.js**: 18.x LTS or higher (20.x LTS recommended)
+- **npm**: 9.x or higher (or use pnpm for better dependency management)
 - [Freighter Wallet](https://freighter.app/) - Browser extension for Stellar wallet
 
 ## Getting Started
 
 ### Installation
 
 ```bash
-# Install dependencies
+# Install dependencies using npm
 npm install
+
+# OR using pnpm (recommended for faster installations and better lockfile handling)
+pnpm install
 ```
 
+**Note**: This project uses optional native dependencies for build tools (e.g., `@rolldown/binding-*`). pnpm handles these more reliably than npm. If you encounter native dependency issues with npm, try `pnpm install` instead.
+
 ### Development
 
 ```bash

dongle/SETUP.md

@@ -0,0 +1,247 @@
+# Setup Guide - Dependency Installation & Testing
+
+This guide addresses dependency installation issues, particularly with native bindings required by Vitest and build tools.
+
+## Quick Start
+
+```bash
+npm install
+npm test
+```
+
+## Prerequisites
+
+- **Node.js**: 18.x LTS or higher (20.x LTS **strongly recommended**)
+- **npm**: 9.x or higher
+- [Freighter Wallet](https://freighter.app/) - Browser extension for Stellar wallet
+
+## Supported Platforms
+
+This project uses native dependencies for build tools that are platform-specific:
+- **macOS (Apple Silicon)**: `@rolldown/binding-darwin-arm64`
+- **macOS (Intel)**: `@rolldown/binding-darwin-x64`
+- **Linux (x64)**: `@rolldown/binding-linux-x64`
+- **Windows (x64)**: `@rolldown/binding-win32-x64`
+
+The lockfile (`package-lock.json`) includes all platform variants. npm will automatically install only the correct binding for your platform.
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# If you encounter issues with native bindings:
+npm ci  # Use clean install for CI/CD or locked environments
+```
+
+**Native Dependency Notes**:
+- Native bindings are automatically resolved and installed for your platform
+- The `package-lock.json` tracks the dependency tree including platform-specific builds
+- If npm fails to install, ensure you have:
+  - Python 3.x installed and in PATH
+  - Build tools for your platform (Xcode on macOS, MSVC on Windows, gcc/make on Linux)
+  - Sufficient disk space for node_modules (~800MB+)
+
+## Development
+
+```bash
+# Run development server
+npm run dev
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run linter
+npm run lint
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+## Troubleshooting
+
+### Missing @rolldown/binding errors
+
+**Error:**
+```
+Cannot find module '@rolldown/binding-*'
+```
+
+**Cause:**
+Vitest uses Rolldown, which requires native bindings compiled for your platform. These are optional dependencies that npm should install automatically.
+
+**Solutions:**
+
+1. **Clean reinstall (recommended)**
+   ```bash
+   rm -rf node_modules package-lock.json
+   npm install
+   ```
+
+2. **Use clean install with existing lockfile**
+   ```bash
+   npm ci
+   ```
+
+3. **Manual platform-specific binding installation**
+
+   Windows (x64):
+   ```bash
+   npm install --no-save @rolldown/binding-win32-x64
+   ```
+
+   macOS (Apple Silicon):
+   ```bash
+   npm install --no-save @rolldown/binding-darwin-arm64
+   ```
+
+   macOS (Intel):
+   ```bash
+   npm install --no-save @rolldown/binding-darwin-x64
+   ```
+
+   Linux (x64):
+   ```bash
+   npm install --no-save @rolldown/binding-linux-x64
+   ```
+
+### Tests fail immediately with native module errors
+
+**Solutions:**
+
+1. **Verify Node.js version**
+   ```bash
+   node --version
+   npm --version
+   ```
+   - Node.js: 18.x LTS or higher (20.x recommended)
+   - npm: 9.x or higher
+
+2. **Install build tools**
+
+   **macOS:**
+   ```bash
+   xcode-select --install
+   ```
+
+   **Windows:**
+   - Install Visual Studio Build Tools with C++ workload
+   - Or: `npm install -g windows-build-tools`
+
+   **Linux (Ubuntu/Debian):**
+   ```bash
+   sudo apt-get install build-essential python3
+   ```
+
+   **Linux (Fedora/RHEL):**
+   ```bash
+   sudo dnf install gcc-c++ make python3
+   ```
+
+3. **Ensure Python is available**
+   ```bash
+   python --version
+   # or
+   python3 --version
+   ```
+
+### npm install hangs or times out
+
+**Solutions:**
+
+1. **Increase npm timeout**
+   ```bash
+   npm install --fetch-timeout=120000
+   ```
+
+2. **Check disk space**
+   ```bash
+   # macOS/Linux
+   df -h
+
+   # Windows
+   Get-Volume
+   ```
+   Need at least 1GB free space for node_modules
+
+3. **Clear npm cache**
+   ```bash
+   npm cache clean --force
+   npm install
+   ```
+
+## Verifying Installation
+
+After installation, verify everything is set up correctly:
+
+```bash
+# Check dependencies
+npm ls
+
+# Run tests
+npm test
+
+# Run linter
+npm run lint
+
+# Build project
+npm run build
+```
+
+## Node.js & npm Versions
+
+**Recommended:**
+- Node.js: 20.x LTS (latest stable)
+- npm: 10.x (bundled with Node 20)
+
+**Minimum:**
+- Node.js: 18.x LTS
+- npm: 9.x
+
+**Installation:**
+- [Node.js Official](https://nodejs.org/) - Download LTS
+- macOS: `brew install node@20`
+- Linux: `nvm install 20`
+
+## CI/CD Integration
+
+For GitHub Actions or other CI systems, the project is configured to:
+- Run tests on Node 18.x and 20.x
+- Verify dependency lockfile is up to date
+- Run linter with zero warnings
+- Build project successfully
+
+See `.github/workflows/` for workflow configurations.
+
+## Environment Variables
+
+Create a `.env.local` file in the `dongle` directory with:
+
+```env
+# Optional - Defaults to testnet if not specified
+NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org:443
+NEXT_PUBLIC_SOROBAN_NETWORK_PASSPHRASE="Test SDF Network ; September 2015"
+```
+
+## Additional Notes
+
+- **Platform-specific installs**: npm automatically resolves the correct binding for your platform
+- **Lockfile**: `package-lock.json` includes all platform variants; only the correct one installs
+- **Cache**: Native bindings are cached in npm's cache directory; clear if experiencing issues
+- **Disk space**: Full node_modules is ~1GB; ensure sufficient space before installing
+
+## Still Having Issues?
+
+1. Check Node.js is correct version: `node --version`
+2. Try clean install: `rm -rf node_modules package-lock.json && npm install`
+3. Check disk space and internet connection
+4. Verify build tools are installed for your platform
+5. Check [npm docs](https://docs.npmjs.com/) for platform-specific guidance
+6. Open an issue on GitHub with output from `npm install --verbose`