Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
2026-02-28 14:39:40 -05:00
commit d803bfe2b1
7854 changed files with 3522914 additions and 0 deletions
--- a/docs/publishing/PUBLISHING.md
+++ b/docs/publishing/PUBLISHING.md
@@ -0,0 +1,587 @@
+# Publishing Guide
+
+Complete guide for publishing rUvector packages to npm.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Publishing Process](#publishing-process)
+- [Version Management](#version-management)
+- [CI/CD Workflow](#cicd-workflow)
+- [Manual Publishing](#manual-publishing)
+- [Troubleshooting](#troubleshooting)
+- [Post-Publication](#post-publication)
+
+## Overview
+
+rUvector uses automated publishing via GitHub Actions. When you push a version tag, the CI/CD pipeline:
+
+1. Builds native binaries for all 5 platforms
+2. Publishes platform-specific packages
+3. Publishes the main `@ruvector/core` package
+
+### Published Packages
+
+The publishing workflow creates these npm packages:
+
+**Platform-specific packages** (native binaries):
+- `ruvector-core-darwin-arm64` - macOS Apple Silicon (M1/M2/M3)
+- `ruvector-core-darwin-x64` - macOS Intel
+- `ruvector-core-linux-arm64-gnu` - Linux ARM64
+- `ruvector-core-linux-x64-gnu` - Linux x64
+- `ruvector-core-win32-x64-msvc` - Windows x64
+
+**Main package**:
+- `@ruvector/core` - Main package with TypeScript types and platform detection
+
+## Prerequisites
+
+### 1. NPM Authentication
+
+Ensure you have npm publish permissions:
+
+```bash
+npm whoami
+# Should show your npm username
+```
+
+### 2. GitHub Secrets
+
+The repository must have the `NPM_TOKEN` secret configured:
+
+1. Go to **Settings** → **Secrets and variables** → **Actions**
+2. Add `NPM_TOKEN` with your npm authentication token
+3. Generate token at: https://www.npmjs.com/settings/[username]/tokens
+
+### 3. Git Configuration
+
+```bash
+# Verify git user
+git config user.name
+git config user.email
+
+# Verify remote
+git remote -v
+```
+
+### 4. Build System Check
+
+All platforms must build successfully:
+
+```bash
+# View latest build status
+gh run list --workflow "Build Native Modules" --limit 1
+
+# Or check PR directly
+gh pr checks <PR-NUMBER>
+```
+
+## Publishing Process
+
+### Option 1: Automated Publishing (Recommended)
+
+This is the standard workflow for releases:
+
+#### Step 1: Ensure All Builds Pass
+
+```bash
+# Check current build status
+gh run list --limit 1
+```
+
+All 5 platform builds should be passing:
+- ✅ darwin-arm64 (Apple Silicon)
+- ✅ darwin-x64 (Intel Mac)
+- ✅ linux-arm64-gnu
+- ✅ linux-x64-gnu
+- ✅ win32-x64-msvc
+
+#### Step 2: Update Version
+
+```bash
+# Navigate to package directory
+cd npm/core
+
+# Bump version (choose one)
+npm version patch   # 0.1.1 -> 0.1.2
+npm version minor   # 0.1.1 -> 0.2.0
+npm version major   # 0.1.1 -> 1.0.0
+
+# Or manually edit package.json
+```
+
+Also update platform package versions to match:
+
+```bash
+# Edit npm/core/package.json
+# Update optionalDependencies versions to match
+```
+
+#### Step 3: Commit Version Bump
+
+```bash
+cd /workspaces/ruvector
+
+git add npm/core/package.json npm/package-lock.json
+git commit -m "chore: bump version to X.Y.Z"
+git push
+```
+
+#### Step 4: Create and Push Tag
+
+```bash
+# Create annotated tag
+git tag vX.Y.Z -a -m "Release vX.Y.Z
+
+- Feature 1
+- Feature 2
+- Bug fix 3"
+
+# Push tag to trigger publishing
+git push origin vX.Y.Z
+```
+
+#### Step 5: Monitor Publishing Workflow
+
+```bash
+# Watch workflow progress
+gh run watch
+
+# Or view in browser
+gh run list --limit 1
+```
+
+The workflow will:
+1. ⏳ Build all 5 platforms (~7 minutes)
+2. ⏳ Upload artifacts
+3. ⏳ Run publish job
+4. ✅ Publish packages to npm
+
+#### Step 6: Verify Publication
+
+```bash
+# Check npm registry
+npm view @ruvector/core versions
+npm view ruvector-core-darwin-arm64 versions
+
+# Or search npm
+npm search @ruvector
+```
+
+### Option 2: Quick Release from PR
+
+If you have a PR with passing builds:
+
+```bash
+# 1. Update version
+npm version patch -w npm/core
+
+# 2. Commit and push
+git add -A
+git commit -m "chore: bump version to X.Y.Z"
+git push
+
+# 3. Create and push tag
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### Option 3: Release After Merge
+
+```bash
+# 1. Merge PR to main
+gh pr merge <PR-NUMBER> --squash
+
+# 2. Pull latest
+git checkout main
+git pull
+
+# 3. Create tag
+git tag vX.Y.Z -a -m "Release vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+## Version Management
+
+### Versioning Strategy
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0): Breaking changes
+- **MINOR** (0.1.0): New features, backwards compatible
+- **PATCH** (0.0.1): Bug fixes, backwards compatible
+
+### Version Synchronization
+
+**Critical**: All packages must use synchronized versions:
+
+```json
+// npm/core/package.json
+{
+  "version": "0.1.2",
+  "optionalDependencies": {
+    "ruvector-core-darwin-arm64": "0.1.2",    // ← Must match
+    "ruvector-core-darwin-x64": "0.1.2",      // ← Must match
+    "ruvector-core-linux-arm64-gnu": "0.1.2", // ← Must match
+    "ruvector-core-linux-x64-gnu": "0.1.2",   // ← Must match
+    "ruvector-core-win32-x64-msvc": "0.1.2"   // ← Must match
+  }
+}
+```
+
+### Pre-release Versions
+
+For beta/alpha releases:
+
+```bash
+# Create pre-release version
+npm version prerelease --preid=beta
+# 0.1.1 -> 0.1.2-beta.0
+
+git tag v0.1.2-beta.0
+git push origin v0.1.2-beta.0
+```
+
+## CI/CD Workflow
+
+### Workflow Triggers
+
+The build workflow (`.github/workflows/build-native.yml`) triggers on:
+
+1. **Pull Requests** to main
+   - Builds all platforms
+   - Does NOT publish
+
+2. **Pushes** to main
+   - Builds all platforms
+   - Does NOT publish
+
+3. **Tags** matching `v*`
+   - Builds all platforms
+   - **PUBLISHES** to npm ✅
+
+### Build Matrix
+
+The workflow builds for 5 platforms in parallel:
+
+```yaml
+matrix:
+  settings:
+    - host: ubuntu-22.04
+      platform: linux-x64-gnu
+
+    - host: ubuntu-22.04
+      platform: linux-arm64-gnu
+
+    - host: macos-15-intel
+      platform: darwin-x64
+
+    - host: macos-14
+      platform: darwin-arm64
+
+    - host: windows-2022
+      platform: win32-x64-msvc
+```
+
+### Publish Job
+
+The publish job runs **only on tags**:
+
+```yaml
+publish:
+  needs: build
+  if: startsWith(github.ref, 'refs/tags/v')
+  steps:
+    - Download all artifacts
+    - Copy binaries to platform packages
+    - Publish platform packages
+    - Publish main package
+```
+
+### Workflow Files
+
+```
+.github/workflows/
+├── build-native.yml      # Main build & publish workflow
+└── agentic-synth-ci.yml  # Additional CI checks
+```
+
+## Manual Publishing
+
+If you need to publish manually (not recommended):
+
+### Prerequisites
+
+```bash
+# Login to npm
+npm login
+
+# Verify authentication
+npm whoami
+```
+
+### Build All Platforms
+
+You'll need access to all 5 platforms or use cross-compilation:
+
+```bash
+# Linux x64
+cargo build --release --target x86_64-unknown-linux-gnu
+
+# Linux ARM64
+cargo build --release --target aarch64-unknown-linux-gnu
+
+# macOS Intel
+cargo build --release --target x86_64-apple-darwin
+
+# macOS ARM64
+cargo build --release --target aarch64-apple-darwin
+
+# Windows
+cargo build --release --target x86_64-pc-windows-msvc
+```
+
+### Publish Platform Packages
+
+```bash
+cd npm/core/platforms
+
+# Publish each platform
+cd darwin-arm64 && npm publish --access public
+cd ../darwin-x64 && npm publish --access public
+cd ../linux-arm64-gnu && npm publish --access public
+cd ../linux-x64-gnu && npm publish --access public
+cd ../win32-x64-msvc && npm publish --access public
+```
+
+### Publish Main Package
+
+```bash
+cd npm/core
+npm run build  # Compile TypeScript
+npm publish --access public
+```
+
+## Troubleshooting
+
+### Build Failures
+
+#### Issue: Version Mismatch Error
+
+```
+npm error Invalid: lock file's ruvector-core-darwin-arm64@0.1.1
+does not satisfy ruvector-core-darwin-arm64@0.1.2
+```
+
+**Solution**: Synchronize versions in `npm/core/package.json`:
+
+```bash
+# Update optionalDependencies to match platform package versions
+cd npm
+npm install
+git add package-lock.json
+git commit -m "fix: sync package versions"
+```
+
+#### Issue: macOS Build Failures
+
+```
+Error: macos-13 runner deprecated
+```
+
+**Solution**: Update workflow to use `macos-15-intel`:
+
+```yaml
+- host: macos-15-intel  # Not macos-13
+  platform: darwin-x64
+```
+
+#### Issue: Windows PowerShell Errors
+
+```
+Could not find a part of the path 'D:\dev\null'
+```
+
+**Solution**: Add `shell: bash` to Windows-compatible steps:
+
+```yaml
+- name: Find built .node files
+  shell: bash  # ← Add this
+  run: |
+    find . -name "*.node" 2>/dev/null || true
+```
+
+### Publishing Failures
+
+#### Issue: NPM Authentication Failed
+
+```
+npm error code ENEEDAUTH
+npm error need auth This command requires you to be logged in
+```
+
+**Solution**:
+1. Verify `NPM_TOKEN` secret in GitHub repository settings
+2. Regenerate token if expired: https://www.npmjs.com/settings/[username]/tokens
+3. Update repository secret
+
+#### Issue: Permission Denied
+
+```
+npm error code E403
+npm error 403 Forbidden - PUT https://registry.npmjs.org/@ruvector%2fcore
+```
+
+**Solution**:
+1. Verify you have publish permissions for `@ruvector` scope
+2. Contact npm org admin to grant permissions
+3. Ensure package name is available on npm
+
+#### Issue: Build Artifacts Not Found
+
+```
+Error: No files were found with the provided path: npm/core/platforms/*/
+```
+
+**Solution**:
+1. Check that all 5 builds completed successfully
+2. Verify artifact upload step succeeded
+3. Check artifact names match expected pattern: `bindings-{platform}`
+
+### Version Issues
+
+#### Issue: Tag Already Exists
+
+```
+error: tag 'v0.1.2' already exists
+```
+
+**Solution**:
+```bash
+# Delete local tag
+git tag -d v0.1.2
+
+# Delete remote tag
+git push origin :refs/tags/v0.1.2
+
+# Create tag again
+git tag v0.1.2
+git push origin v0.1.2
+```
+
+#### Issue: Wrong Version Published
+
+If you published the wrong version:
+
+```bash
+# Deprecate the bad version
+npm deprecate @ruvector/core@0.1.2 "Incorrect version, use 0.1.3"
+
+# Unpublish (only within 72 hours)
+npm unpublish @ruvector/core@0.1.2
+
+# Publish correct version
+git tag v0.1.3
+git push origin v0.1.3
+```
+
+## Post-Publication
+
+### Verify Published Packages
+
+```bash
+# Check versions
+npm view @ruvector/core versions
+npm view ruvector-core-darwin-arm64 versions
+
+# Test installation
+npm create vite@latest test-project
+cd test-project
+npm install @ruvector/core
+npm run dev
+```
+
+### Update Documentation
+
+After publishing:
+
+1. Update `CHANGELOG.md` with release notes
+2. Update `README.md` version badges
+3. Create GitHub Release with notes
+4. Update documentation site if applicable
+
+### Create GitHub Release
+
+```bash
+# Using gh CLI
+gh release create v0.1.2 \
+  --title "Release v0.1.2" \
+  --notes "## Changes
+
+- Feature 1
+- Feature 2
+- Bug fix 3
+
+**Full Changelog**: https://github.com/ruvnet/ruvector/compare/v0.1.1...v0.1.2"
+
+# Or create manually at:
+# https://github.com/ruvnet/ruvector/releases/new
+```
+
+### Announce Release
+
+- Post on social media
+- Update project website
+- Notify users on Discord/Slack
+- Send newsletter if applicable
+
+## Release Checklist
+
+Use this checklist for each release:
+
+```markdown
+## Pre-Release
+- [ ] All tests passing
+- [ ] All 5 platform builds passing
+- [ ] Documentation updated
+- [ ] CHANGELOG.md updated
+- [ ] Version bumped in package.json
+- [ ] Version synchronized across all packages
+
+## Release
+- [ ] Version committed and pushed
+- [ ] Git tag created
+- [ ] Tag pushed to trigger workflow
+- [ ] Workflow completed successfully
+- [ ] Packages published to npm
+
+## Post-Release
+- [ ] Verified packages on npm
+- [ ] Test installation works
+- [ ] GitHub Release created
+- [ ] Documentation updated
+- [ ] Announced release
+```
+
+## Additional Resources
+
+- [npm Publishing Documentation](https://docs.npmjs.com/cli/v8/commands/npm-publish)
+- [Semantic Versioning](https://semver.org/)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [NAPI-RS Documentation](https://napi.rs/)
+- [Rust Cross-Compilation](https://rust-lang.github.io/rustup/cross-compilation.html)
+
+## Support
+
+If you encounter issues not covered in this guide:
+
+1. Check [GitHub Issues](https://github.com/ruvnet/ruvector/issues)
+2. Review [GitHub Actions Logs](https://github.com/ruvnet/ruvector/actions)
+3. Ask in [Discussions](https://github.com/ruvnet/ruvector/discussions)
+4. Contact maintainers
+
+---
+
+Last Updated: 2025-11-25
+Version: 1.0.0