ruvector/docs/MACOS_PACKAGES_SETUP.md

# macOS Package Setup Complete

**Date:** 2025-11-21
**Status:** ✅ Package structure ready, awaiting binary builds

## 📦 macOS Packages Configured

### @ruvector/core-darwin-x64 (Intel Macs)
**Location:** `/workspaces/ruvector/npm/core/platforms/darwin-x64`

**Contents:**
- ✅ index.js (327B) - Module loader
- ✅ package.json (603B) - Package configuration
- ✅ README.md (876B) - Documentation
- ⏳ ruvector.node - **Needs to be built via GitHub Actions**

### @ruvector/core-darwin-arm64 (Apple Silicon)
**Location:** `/workspaces/ruvector/npm/core/platforms/darwin-arm64`

**Contents:**
- ✅ index.js (329B) - Module loader
- ✅ package.json (627B) - Package configuration
- ✅ README.md (910B) - Documentation
- ⏳ ruvector.node - **Needs to be built via GitHub Actions**

## 🔧 Package Configuration

### darwin-x64 package.json
```json
{
  "name": "@ruvector/core-darwin-x64",
  "version": "0.1.1",
  "main": "index.js",
  "os": ["darwin"],
  "cpu": ["x64"],
  "files": [
    "index.js",
    "ruvector.node",
    "*.node",
    "README.md"
  ]
}
```

### darwin-arm64 package.json
```json
{
  "name": "@ruvector/core-darwin-arm64",
  "version": "0.1.1",
  "main": "index.js",
  "os": ["darwin"],
  "cpu": ["arm64"],
  "files": [
    "index.js",
    "ruvector.node",
    "*.node",
    "README.md"
  ]
}
```

## 🚀 Building macOS Binaries

### Option 1: GitHub Actions (Recommended)

The multi-platform build workflow is already configured in `.github/workflows/build-native.yml`.

**Trigger the workflow:**

```bash
# Commit current changes
git add .
git commit -m "feat: Add macOS package configuration"

# Push to main branch (triggers workflow)
git push origin main

# Or manually trigger via GitHub Actions UI
```

**Workflow will:**
1. Build on macOS-13 (Intel) for darwin-x64
2. Build on macOS-14 (Apple Silicon) for darwin-arm64
3. Upload artifacts to GitHub
4. Binaries will be at: `npm/packages/core/native/{darwin-x64,darwin-arm64}/ruvector.node`

### Option 2: Local Build (Requires macOS)

If you have access to a Mac:

**For Intel Macs (darwin-x64):**
```bash
cd npm/packages/core
npm install
npm run build:napi -- --target x86_64-apple-darwin

# Binary will be in: native/darwin-x64/ruvector.node
```

**For Apple Silicon (darwin-arm64):**
```bash
cd npm/packages/core
npm install
npm run build:napi -- --target aarch64-apple-darwin

# Binary will be in: native/darwin-arm64/ruvector.node
```

## 📋 After Binaries Are Built

### 1. Copy Binaries to Platform Packages
```bash
# For darwin-x64
cp npm/packages/core/native/darwin-x64/ruvector.node \
   npm/core/platforms/darwin-x64/

# For darwin-arm64
cp npm/packages/core/native/darwin-arm64/ruvector.node \
   npm/core/platforms/darwin-arm64/
```

### 2. Verify Package Contents
```bash
# darwin-x64
cd npm/core/platforms/darwin-x64
npm pack --dry-run

# darwin-arm64
cd npm/core/platforms/darwin-arm64
npm pack --dry-run
```

Expected output (similar to linux-x64-gnu):
```
npm notice 📦  @ruvector/core-darwin-x64@0.1.1
npm notice === Tarball Contents ===
npm notice 876B  README.md
npm notice 327B  index.js
npm notice 603B  package.json
npm notice 4.5MB ruvector.node
npm notice === Tarball Details ===
npm notice package size:  1.9 MB
npm notice unpacked size: 4.5 MB
npm notice total files:   4
```

### 3. Test Package (On macOS)
```bash
# Copy test script
cp npm/core/test-package.cjs npm/core/platforms/darwin-x64/test.cjs
# OR
cp npm/core/test-package.cjs npm/core/platforms/darwin-arm64/test.cjs

# Update platformDir in test script to current directory
sed -i 's|platforms/linux-x64-gnu|.|' test.cjs

# Run tests
node test.cjs
```

### 4. Publish to npm
```bash
# darwin-x64
cd npm/core/platforms/darwin-x64
npm publish --access public

# darwin-arm64
cd npm/core/platforms/darwin-arm64
npm publish --access public
```

## 🎯 Current Status

### Package Structure: ✅ Complete
- [x] index.js loaders created
- [x] package.json configured correctly
- [x] README.md documentation added
- [x] Files array includes ruvector.node
- [x] Platform constraints set (os, cpu)

### Binary Building: ⏳ Pending
- [ ] darwin-x64 binary needs to be built
- [ ] darwin-arm64 binary needs to be built
- [ ] Binaries need to be copied to platform directories
- [ ] Package contents need to be verified with npm pack

### Testing: ⏳ Pending Binary Build
- [ ] darwin-x64 package needs testing on Intel Mac
- [ ] darwin-arm64 package needs testing on Apple Silicon
- [ ] All 4 test suites need to pass

### Publishing: ⏳ Pending Testing
- [ ] darwin-x64 publish to npm
- [ ] darwin-arm64 publish to npm

## 🔗 Related Packages

### Already Published
- ✅ @ruvector/core-linux-x64-gnu - Ready for publishing

### Also Need Binaries
- ⏳ @ruvector/core-linux-arm64-gnu - Awaiting build
- ⏳ @ruvector/core-win32-x64-msvc - Awaiting build

## 📝 GitHub Actions Workflow Details

**Workflow File:** `.github/workflows/build-native.yml`

**macOS Build Configuration:**
```yaml
- host: macos-13
  target: x86_64-apple-darwin
  build: npm run build:napi -- --target x86_64-apple-darwin
  platform: darwin-x64

- host: macos-14
  target: aarch64-apple-darwin
  build: npm run build:napi -- --target aarch64-apple-darwin
  platform: darwin-arm64
```

**Workflow Triggers:**
- Push to main branch
- Pull requests to main
- Manual trigger via `workflow_dispatch`
- Git tags matching `v*`

**Artifacts:**
- Name: `bindings-darwin-x64`
- Name: `bindings-darwin-arm64`
- Path: `npm/packages/core/native/{platform}/`

## 🎓 Key Differences: macOS vs Linux

### Similarities
- Same API (VectorDb, async methods)
- Same package structure (index.js loader + binary)
- Same Node.js version requirement (>= 18)
- Similar binary size (~4.3MB)

### Differences
- **Platform constraint:** `os: ["darwin"]` (not "linux")
- **CPU variants:** x64 (Intel) vs arm64 (Apple Silicon)
- **Build hosts:** macOS-13 (Intel) vs macOS-14 (ARM)
- **File paths:** May differ in temp directory handling

## ✅ Verification Checklist

Before publishing macOS packages, verify:

- [ ] Binary exists: `ls -lh npm/core/platforms/darwin-x64/ruvector.node`
- [ ] Binary size: Should be ~4.3MB
- [ ] npm pack shows 4 files (index.js, package.json, README.md, ruvector.node)
- [ ] Package size: ~4.5MB unpacked, ~1.9MB compressed
- [ ] Test script passes all 4 tests
- [ ] Module loads without errors
- [ ] Database operations work (insert, search, count, delete)

## 🚨 Important Notes

1. **Cannot build on Linux:** macOS binaries must be built on macOS runners
2. **Two macOS versions needed:** macos-13 for Intel, macos-14 for ARM
3. **Platform detection:** npm will auto-select correct package based on os/cpu
4. **Universal binaries:** Not used - separate packages for Intel and ARM
5. **Testing required:** Each platform must be tested on actual hardware

## 📚 Next Steps

1. **Trigger GitHub Actions** - Push changes to build binaries
2. **Download artifacts** - Get binaries from workflow run
3. **Copy to packages** - Move binaries to platform directories
4. **Verify with npm pack** - Ensure binaries are included
5. **Test on macOS** - Run test suite on both Intel and ARM Macs
6. **Publish to npm** - Make packages available

---

**Package Structure:** ✅ Complete and ready
**Binary Build:** ⏳ Awaiting GitHub Actions workflow
**Testing:** ⏳ Pending binary availability
**Publishing:** ⏳ Pending testing completion