feat: Complete RuVector Extensions with 5 Major Features + Critical CommonJS Fix

.githooks/pre-commit

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Git pre-commit hook to automatically sync package-lock.json
+# Install: ln -sf ../../.githooks/pre-commit .git/hooks/pre-commit
+
+export GIT_HOOK="pre-commit"
+
+# Run the sync script
+./scripts/sync-lockfile.sh
+
+exit $?

.github/workflows/validate-lockfile.yml

@@ -0,0 +1,48 @@
+name: Validate Package Lock File
+
+on:
+  pull_request:
+    paths:
+      - 'npm/**/package.json'
+      - 'npm/package-lock.json'
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - 'npm/**/package.json'
+      - 'npm/package-lock.json'
+
+jobs:
+  validate-lockfile:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+          cache-dependency-path: npm/package-lock.json
+
+      - name: Validate lock file is in sync
+        run: |
+          cd npm
+          npm ci --dry-run
+
+      - name: Check for lock file changes needed
+        if: failure()
+        run: |
+          echo "❌ package-lock.json is out of sync with package.json"
+          echo ""
+          echo "To fix this issue:"
+          echo "  1. Run: cd npm && npm install"
+          echo "  2. Commit the updated package-lock.json"
+          echo "  3. Push to your branch"
+          echo ""
+          echo "Or use the automated script:"
+          echo "  ./scripts/sync-lockfile.sh"
+          exit 1

docs/CONTRIBUTING.md

@@ -0,0 +1,226 @@
+# Contributing to RuVector
+
+Thank you for your interest in contributing to RuVector!
+
+## Development Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/ruvnet/ruvector.git
+cd ruvector
+```
+
+### 2. Install Dependencies
+
+```bash
+cd npm
+npm install
+```
+
+### 3. Install Git Hooks (Recommended)
+
+We provide git hooks that automatically keep `package-lock.json` in sync:
+
+```bash
+./scripts/install-hooks.sh
+```
+
+This will:
+- Automatically run `npm install` when you modify `package.json`
+- Stage the updated `package-lock.json` automatically
+- Prevent CI/CD failures due to lock file mismatches
+
+## Package Management
+
+### Adding Dependencies
+
+When adding new dependencies to any package:
+
+```bash
+cd npm/packages/<package-name>
+npm install <dependency>
+```
+
+**Important**: Always commit the updated `package-lock.json` with your changes!
+
+### Manual Lock File Sync
+
+If you forget to sync the lock file, you can use our helper script:
+
+```bash
+./scripts/sync-lockfile.sh
+```
+
+## Common Issues
+
+### CI/CD Fails with "Lock file out of sync"
+
+**Problem**: `npm ci` fails with:
+```
+npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync
+```
+
+**Solution**:
+```bash
+cd npm
+npm install
+git add package-lock.json
+git commit -m "fix: Sync package-lock.json"
+git push
+```
+
+Or use the automated script:
+```bash
+./scripts/sync-lockfile.sh
+```
+
+### Pre-commit Hook Not Working
+
+If the git hook isn't triggering:
+
+```bash
+# Reinstall hooks
+./scripts/install-hooks.sh
+
+# Verify hook is executable
+ls -la .git/hooks/pre-commit
+```
+
+## Development Workflow
+
+1. **Create a feature branch**
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Write code in the appropriate package
+   - Add tests for new features
+   - Update documentation
+
+3. **Build and test**
+   ```bash
+   cd npm
+   npm run build
+   npm test
+   ```
+
+4. **Commit your changes**
+   ```bash
+   git add .
+   git commit -m "feat: Your descriptive commit message"
+   ```
+
+   The pre-commit hook will automatically sync the lock file if needed.
+
+5. **Push and create PR**
+   ```bash
+   git push origin feat/your-feature-name
+   ```
+
+## Package Structure
+
+```
+ruvector/
+├── npm/
+│   ├── core/              # @ruvector/core - Native Rust bindings
+│   ├── packages/
+│   │   ├── ruvector/      # ruvector - Wrapper package
+│   │   └── ruvector-extensions/  # ruvector-extensions - Feature extensions
+│   └── package-lock.json  # Workspace lock file
+├── scripts/
+│   ├── sync-lockfile.sh   # Auto-sync lock file
+│   ├── install-hooks.sh   # Install git hooks
+│   └── ci-sync-lockfile.sh  # CI/CD lock file sync
+└── .githooks/
+    └── pre-commit         # Pre-commit hook script
+```
+
+## Testing
+
+### Run All Tests
+```bash
+cd npm
+npm test
+```
+
+### Test Specific Package
+```bash
+cd npm/packages/ruvector-extensions
+npm test
+```
+
+### Manual Testing
+```bash
+cd npm/packages/ruvector-extensions/examples
+tsx complete-integration.ts
+```
+
+## Code Style
+
+- **TypeScript**: Use strict mode, full type annotations
+- **Formatting**: 2 spaces, semicolons, single quotes
+- **Comments**: JSDoc for public APIs
+- **Naming**: camelCase for variables/functions, PascalCase for classes
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `docs:` - Documentation changes
+- `refactor:` - Code refactoring
+- `test:` - Test updates
+- `chore:` - Build/tooling changes
+
+Examples:
+```
+feat: Add OpenAI embeddings provider
+fix: Resolve CommonJS export issue
+docs: Update embeddings API documentation
+chore: Sync package-lock.json
+```
+
+## Pull Request Process
+
+1. **Ensure CI passes**
+   - All tests pass
+   - Build succeeds
+   - No linting errors
+
+2. **Update documentation**
+   - README.md if public API changes
+   - JSDoc comments for new functions
+   - CHANGELOG.md with notable changes
+
+3. **Describe your changes**
+   - Clear PR title and description
+   - Reference related issues
+   - Include examples if applicable
+
+4. **Request review**
+   - Maintainers will review within 48 hours
+   - Address feedback promptly
+   - Keep discussion focused and professional
+
+## Release Process
+
+Releases are handled by maintainers:
+
+1. Version bump in package.json
+2. Update CHANGELOG.md
+3. Create git tag
+4. Publish to npm
+5. Create GitHub release
+
+## Questions?
+
+- 📖 Check the [documentation](../README.md)
+- 🐛 Report bugs in [Issues](https://github.com/ruvnet/ruvector/issues)
+- 💬 Ask questions in [Discussions](https://github.com/ruvnet/ruvector/discussions)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.