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

{
  "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

{
  "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:

# 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):

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):

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

# 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

# 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)

# 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

# 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

• index.js loaders created
• package.json configured correctly
• README.md documentation added
• Files array includes ruvector.node
• 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:

- 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