Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/docs/hooks/REVIEW_REPORT.md

@@ -0,0 +1,569 @@
+# Implementation Plan Code Review Report
+
+> **Related Documentation**: [README](README.md) | [Implementation Plan](IMPLEMENTATION_PLAN.md) | [MVP Checklist](MVP_CHECKLIST.md)
+
+**Document**: `/home/user/ruvector/docs/hooks/IMPLEMENTATION_PLAN.md`
+**Reviewer**: Code Review Agent
+**Date**: 2025-12-25
+**Status**: ✅ APPROVED WITH REVISIONS
+
+---
+
+## Executive Summary
+
+The implementation plan is **technically sound** and well-structured, but contains **3 critical issues** that would cause failures on Windows and during migration. After review:
+
+- **Timeline optimized**: 6-8 weeks → **3-4 weeks for MVP** (50% reduction)
+- **Critical fixes added**: Windows compatibility, SQLite migration risks, command injection
+- **Scope refined**: Deferred complex features (global patterns, SQLite) to v1.1
+- **Code quality improved**: Type-safe templates, idiomatic Rust patterns, security hardening
+
+**Recommendation**: Proceed with implementation using revised plan (now v2.0).
+
+---
+
+## 1. Critical Issues (Must Fix)
+
+### Issue #1: Windows Compatibility Broken
+**Severity**: 🔴 Critical
+**Location**: Hook templates (lines 1022, 1033)
+**Impact**: Complete failure on Windows
+
+**Problem**:
+```json
+{
+  "command": "/bin/bash -c '...'"  // ❌ /bin/bash doesn't exist on Windows
+}
+```
+
+**Fix Applied** (Section 11.1):
+```rust
+fn get_shell_wrapper() -> &'static str {
+    if cfg!(target_os = "windows") { "cmd /c" }
+    else { "/bin/bash -c" }
+}
+```
+
+**Testing Required**:
+- ✅ PowerShell environment
+- ✅ WSL environment
+- ✅ CMD.exe environment
+
+---
+
+### Issue #2: SQLite Migration Format Undefined
+**Severity**: 🔴 Critical
+**Location**: Milestone 4, lines 871-887
+**Impact**: Data loss during migration
+
+**Problem**:
+```rust
+let embedding: Vec<u8> = row.get(3)?;
+let embedding_f32 = deserialize_embedding(&embedding)?;
+// ❌ What format? Numpy? MessagePack? Raw bytes?
+```
+
+**Fix Applied**:
+- **MVP**: Defer SQLite migration to v1.1
+- **JSON-only migration** for MVP (2 days instead of 5-7 days)
+- **Future**: Add format detection before deserialization
+
+**Timeline Savings**: 3-5 days
+
+---
+
+### Issue #3: Runtime Path Resolution Missing
+**Severity**: 🟡 High
+**Location**: Template substitution (line 288)
+**Impact**: Hooks break after binary reinstallation
+
+**Problem**:
+```rust
+// Hardcodes path at install time
+output.replace("{{RUVECTOR_CLI_PATH}}", "/usr/local/bin/ruvector");
+// If user reinstalls via npm, path changes
+```
+
+**Fix Applied**:
+```json
+{
+  "command": "/bin/bash -c 'RUVECTOR=$(which ruvector || echo npx ruvector); $RUVECTOR hooks pre-edit'"
+}
+```
+
+**Benefit**: Hooks survive binary moves/reinstalls
+
+---
+
+## 2. Scope Optimizations
+
+### Optimization #1: Defer Global Patterns System
+**Original**: Milestone 6 (4-5 days)
+**Decision**: Move to v1.1
+
+**Rationale**:
+- Adds complexity (sync conflicts, privacy controls)
+- Not required for core functionality
+- Can be added non-disruptively later
+
+**Timeline Savings**: 4-5 days
+
+---
+
+### Optimization #2: JSON Migration First
+**Original**: SQLite + JSON migration (5-7 days)
+**Revised**: JSON-only for MVP (2 days)
+
+**Rationale**:
+- Most users have existing JSON data (`.claude/intelligence/`)
+- SQLite migration is complex (format detection, embedding deserialization)
+- Lower risk to validate with JSON first
+
+**Timeline Savings**: 3-5 days
+
+---
+
+### Optimization #3: Combine Milestones 2 & 5
+**Original**: Separate CLI (5-7 days) + Templates (3-4 days)
+**Revised**: Combined (4-5 days)
+
+**Rationale**:
+- Template engine and `hooks install` are tightly coupled
+- Building together prevents context switching overhead
+
+**Timeline Savings**: 4-6 days
+
+---
+
+## 3. Missing Elements Added
+
+### 3.1 Error Handling Strategy
+**Added to**: All hook execution points
+
+```rust
+pub fn execute_hook_safely(hook: &HookCommand) -> Result<()> {
+    match hook.execute().timeout(Duration::from_secs(3)) {
+        Ok(Ok(_)) => Ok(()),
+        Ok(Err(e)) => {
+            eprintln!("⚠️ Hook failed (non-fatal): {}", e);
+            Ok(()) // Don't block Claude Code
+        }
+        Err(_) => {
+            eprintln!("⚠️ Hook timeout");
+            Ok(())
+        }
+    }
+}
+```
+
+**Benefit**: Hooks never block Claude Code operations
+
+---
+
+### 3.2 Atomic Migration with Rollback
+**Added to**: Milestone 4a (Section 11.2)
+
+```rust
+pub fn migrate_with_safety(from: &Path, to: &Path) -> Result<MigrationStats> {
+    // 1. Backup existing data
+    // 2. Migrate to temporary location
+    // 3. Validate migrated data
+    // 4. Atomic swap
+    // On any error: restore backup
+}
+```
+
+**Benefit**: Zero data loss risk
+
+---
+
+### 3.3 Security: Command Injection Prevention
+**Added to**: All hook templates (Section 11.3)
+
+```rust
+use shell_escape::escape;
+
+fn generate_hook_command(file_path: &str) -> String {
+    let escaped = escape(file_path.into());
+    format!(r#"ruvector hooks pre-edit {}"#, escaped)
+}
+```
+
+**Prevents**: Malicious filenames like `; rm -rf /`
+
+---
+
+### 3.4 Windows-Specific Testing Checklist
+**Added to**: Milestone 7
+
+- ✅ PowerShell compatibility
+- ✅ Path separator handling (`\` vs `/`)
+- ✅ WSL environment testing
+- ✅ Bundled `jq` binary (not in Windows PATH)
+
+---
+
+## 4. Code Quality Improvements
+
+### 4.1 Type-Safe Templates
+**Issue**: String-based templates are error-prone (line 288)
+
+**Improvement**:
+```rust
+#[derive(Template)]
+#[template(path = "hooks.json.j2")]
+struct HookTemplate {
+    ruvector_cli_path: String,
+    project_root: String,
+}
+
+let rendered = HookTemplate { /* ... */ }.render()?;
+```
+
+**Benefit**: Compile-time template validation
+
+**Dependency**: `askama = "0.12"` (added to Section 12)
+
+---
+
+### 4.2 Idiomatic Rust Error Handling
+**Issue**: Non-idiomatic file writing (Appendix B, line 844)
+
+**Before**:
+```rust
+fs::write(path, serde_json::to_string_pretty(&data)?)?;
+```
+
+**After**:
+```rust
+let mut file = File::create(path)?;
+serde_json::to_writer_pretty(&mut file, &data)?;
+file.sync_all()?; // Ensure durability
+```
+
+**Benefit**: Explicit error points, guaranteed disk sync
+
+---
+
+### 4.3 Extract Magic Numbers to Config
+**Issue**: Hardcoded values in templates (lines 1022, 1033)
+
+**Before**:
+```json
+{ "timeout": 3000 }  // Magic number
+```
+
+**After** (add to `config.toml`):
+```toml
+[hooks]
+timeout_ms = 3000
+stderr_max_bytes = 300
+max_retries = 2
+```
+
+**Benefit**: User-configurable timeouts
+
+---
+
+## 5. Leveraging Existing Crates
+
+### 5.1 Already Available (No Work Needed)
+| Feature | Crate | Location |
+|---------|-------|----------|
+| Path expansion | `shellexpand = "3.1"` | `Cargo.toml:74` ✅ |
+| CLI framework | `clap` | `Cargo.toml:29` ✅ |
+| Vector storage | `ruvector-core` | `Cargo.toml:21` ✅ |
+| Async runtime | `tokio` | `Cargo.toml:34` ✅ |
+
+**Action**: No additional dependencies needed for MVP!
+
+---
+
+### 5.2 Recommended Additions (v1.1)
+```toml
+[dependencies]
+rusqlite = { version = "0.32", optional = true }  # SQLite migration
+askama = "0.12"                                   # Type-safe templates
+shell-escape = "0.1"                              # Security
+
+[features]
+sqlite-migration = ["rusqlite"]
+```
+
+---
+
+### 5.3 Use rvlite for Vector Storage
+**Current plan**: Generic `VectorDB`
+**Better**: Use `rvlite` (already in ruvector ecosystem)
+
+```rust
+use rvlite::RvLite;
+
+pub fn migrate_to_rvlite(trajectories: &[Trajectory]) -> Result<()> {
+    let db = RvLite::create(".ruvector/memory.rvdb")?;
+    db.sql("CREATE TABLE memories (id TEXT, embedding VECTOR(128))")?;
+    // rvlite supports SQL, SPARQL, and Cypher
+}
+```
+
+**Benefit**:
+- Unified storage layer
+- WASM-compatible
+- Already part of ruvector
+
+---
+
+## 6. MVP Definition
+
+### What's Included (3-4 weeks)
+✅ **Week 1-2**: Foundation
+- `ruvector hooks init` (create `.ruvector/` structure)
+- `ruvector hooks install` (generate portable hooks)
+- Template engine with runtime path resolution
+- JSON-to-JSON migration
+
+✅ **Week 3**: Intelligence Layer
+- Refactor `index.js` with `process.env.RUVECTOR_DATA_DIR`
+- Zero hardcoded paths
+- Test in fresh project
+
+✅ **Week 4**: Polish
+- Cross-platform testing (Linux, macOS, Windows)
+- `ruvector hooks stats` command
+- Error handling + rollback
+- Documentation
+
+---
+
+### What's Deferred to v1.1 (Additional 2-3 weeks)
+❌ SQLite migration (needs format detection)
+❌ Global patterns system (sync complexity)
+❌ Export/import commands (nice-to-have)
+❌ `ruvector hooks enable/disable` (low priority)
+
+---
+
+## 7. Timeline Comparison
+
+| Version | Original | Optimized | Savings |
+|---------|----------|-----------|---------|
+| **MVP** | N/A | **3-4 weeks** | N/A |
+| **Full v1.0** | 6-8 weeks | 3-4 weeks | **50%** |
+| **v1.1 (Full Features)** | 6-8 weeks | 5-7 weeks | ~15% |
+
+**Key Changes**:
+1. Defined MVP scope (didn't exist before)
+2. Deferred complex features (SQLite, global patterns)
+3. Combined milestones (CLI + Templates)
+4. Focused on JSON migration (most common use case)
+
+---
+
+## 8. Risks Mitigated
+
+| Risk | Original Plan | Revised Plan |
+|------|---------------|--------------|
+| Windows failure | ⚠️ Testing only | ✅ Conditional shell detection |
+| Data loss | ⚠️ Checksums only | ✅ Atomic migration + rollback |
+| Command injection | ❌ Not addressed | ✅ `shell-escape` crate |
+| SQLite format errors | ⚠️ Assumed format | ✅ Deferred to v1.1 with detection |
+| Hardcoded paths | ⚠️ Install-time subst | ✅ Runtime resolution |
+
+---
+
+## 9. Specific File Changes Required
+
+### 9.1 Update Cargo.toml
+**File**: `/home/user/ruvector/crates/ruvector-cli/Cargo.toml`
+
+```toml
+[dependencies]
+# Add these lines:
+askama = "0.12"           # Type-safe templates
+shell-escape = "0.1"      # Security
+
+# v1.1 only:
+rusqlite = { version = "0.32", optional = true }
+
+[features]
+default = []
+sqlite-migration = ["rusqlite"]
+```
+
+---
+
+### 9.2 Create Hook Template
+**File**: `/home/user/ruvector/crates/ruvector-cli/templates/hooks.json.j2`
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "command": "{{ shell }} 'RUVECTOR=$(which ruvector || echo npx ruvector); $RUVECTOR hooks pre-command \"$CMD\"'"
+      }]
+    }]
+  }
+}
+```
+
+---
+
+### 9.3 Refactor Intelligence Layer
+**File**: `/home/user/ruvector/.claude/intelligence/index.js`
+
+**Line 20** (currently):
+```javascript
+const DATA_DIR = join(__dirname, 'data');
+```
+
+**Change to**:
+```javascript
+const DATA_DIR = process.env.RUVECTOR_DATA_DIR ||
+                 join(process.cwd(), '.ruvector', 'intelligence') ||
+                 join(__dirname, 'data');  // Fallback for legacy
+```
+
+---
+
+## 10. Testing Strategy
+
+### 10.1 Cross-Platform Testing
+**Required Environments**:
+- ✅ Ubuntu 22.04 (GitHub Actions)
+- ✅ macOS 14 Sonoma (M1 + Intel)
+- ✅ Windows 11 (PowerShell + CMD + WSL)
+
+**Test Cases**:
+1. Fresh project setup (`npx ruvector hooks init`)
+2. Migration from existing `.claude/intelligence/`
+3. Hooks trigger correctly (pre-edit, post-command)
+4. Path resolution across platforms
+5. Binary reinstallation (verify hooks still work)
+
+---
+
+### 10.2 Integration Tests
+**File**: `/home/user/ruvector/crates/ruvector-cli/tests/hooks_integration.rs`
+
+```rust
+#[test]
+fn test_hooks_init_creates_structure() {
+    let temp = tempdir()?;
+    run_cmd(&["ruvector", "hooks", "init"], &temp)?;
+
+    assert!(temp.path().join(".ruvector/config.toml").exists());
+    assert!(temp.path().join(".ruvector/intelligence").exists());
+}
+
+#[test]
+fn test_migration_preserves_data() {
+    // Test JSON migration accuracy
+}
+
+#[test]
+fn test_windows_shell_compatibility() {
+    // Platform-specific shell tests
+}
+```
+
+---
+
+## 11. Documentation Requirements
+
+### 11.1 User-Facing Docs
+**File**: `/home/user/ruvector/docs/hooks/USER_GUIDE.md`
+
+**Sections**:
+1. Quick Start (5-minute setup)
+2. Migration from existing setup
+3. Troubleshooting common issues
+4. Configuration reference
+
+---
+
+### 11.2 API Reference
+**File**: `/home/user/ruvector/docs/hooks/CLI_REFERENCE.md`
+
+**Format**:
+```markdown
+## ruvector hooks init
+
+Initialize hooks system in current project.
+
+**Usage**: `npx ruvector hooks init [OPTIONS]`
+
+**Options**:
+- `--path <PATH>`: Custom directory (default: `./.ruvector`)
+- `--template <NAME>`: Use template (default, minimal, advanced)
+
+**Example**:
+```bash
+npx ruvector hooks init
+npx ruvector hooks install
+```
+```
+
+---
+
+## 12. Success Metrics
+
+### MVP Success Criteria
+- ✅ Works on Linux, macOS, Windows (3/3 platforms)
+- ✅ Migration completes in <5 seconds for 1000 trajectories
+- ✅ Zero data loss in migration (validated via checksums)
+- ✅ Hooks survive binary reinstallation
+- ✅ First-time setup takes <5 minutes
+- ✅ Zero hardcoded paths in generated hooks
+
+### Code Quality Metrics
+- ✅ Test coverage >80% for CLI commands
+- ✅ All commands have examples in docs
+- ✅ No clippy warnings on stable Rust
+- ✅ All integration tests pass on 3 platforms
+
+---
+
+## 13. Recommendations Summary
+
+### Immediate Actions (Before Coding)
+1. ✅ **Approve revised plan** (v2.0 in IMPLEMENTATION_PLAN.md)
+2. ✅ **Add dependencies** to Cargo.toml (Section 12)
+3. ✅ **Create hook templates** directory structure
+4. ✅ **Set up CI testing** for Windows/macOS/Linux
+
+### Implementation Order
+1. **Week 1**: Milestone 1 (Spec) + Start Milestone 2 (CLI scaffolding)
+2. **Week 2**: Finish Milestone 2+5 (CLI + Templates)
+3. **Week 3**: Milestone 3 (Intelligence Layer) + 4a (JSON Migration)
+4. **Week 4**: Milestone 7 (Testing + Docs)
+
+### v1.1 Planning
+- Schedule SQLite migration for v1.1.0 (add format detection)
+- Schedule global patterns for v1.1.0 (design sync protocol first)
+- Consider team sharing features for v1.2.0
+
+---
+
+## 14. Final Verdict
+
+**Status**: ✅ **APPROVED FOR IMPLEMENTATION** (with revisions)
+
+**Confidence Level**: High (8/10)
+
+**Remaining Risks**:
+- Windows testing may uncover edge cases (10% probability)
+- Intelligence layer refactor may need iteration (15% probability)
+- User adoption may surface unforeseen use cases (20% probability)
+
+**Overall Assessment**: The plan is **solid, well-researched, and implementable**. The revised timeline (3-4 weeks for MVP) is **realistic and achievable**. Critical issues have been identified and fixed. Code quality improvements will prevent future maintenance burden.
+
+**Next Step**: Create feature branch `feature/portable-hooks-mvp` and begin Milestone 1.
+
+---
+
+**Reviewed By**: Code Review Agent
+**Approved By**: [Pending]
+**Implementation Start**: [TBD]
+**Target MVP Release**: [TBD + 3-4 weeks]