d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
1322 lines
39 KiB
Markdown
1322 lines
39 KiB
Markdown
# RuVector Generic Hooks System - Implementation Plan
|
|
|
|
> **Related Documentation**: [README](README.md) | [User Guide](USER_GUIDE.md) | [CLI Reference](CLI_REFERENCE.md) | [Architecture](ARCHITECTURE.md)
|
|
|
|
## Executive Summary
|
|
|
|
This document outlines a comprehensive SPARC-GOAP (Specification, Pseudocode, Architecture, Refinement, Completion + Goal-Oriented Action Planning) implementation plan for transforming the current repo-specific hooks system into a **generic, portable, CLI-integrated hooks system** for the ruvector project.
|
|
|
|
### Key Objectives
|
|
1. **Portability**: Transform hardcoded paths into dynamic, project-agnostic configurations
|
|
2. **CLI Integration**: Add `npx ruvector hooks` commands for easy setup and management
|
|
3. **Memory Migration**: Migrate claude-flow's SQLite memory.db to ruvector's native HNSW vector storage
|
|
4. **Universal Compatibility**: Enable any project to benefit from intelligent Claude Code hooks
|
|
|
|
---
|
|
|
|
## 1. GOAL STATE DEFINITION
|
|
|
|
### 1.1 Current State Analysis
|
|
|
|
**Repository-Specific System** (`.claude/settings.json`):
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PreToolUse": [{
|
|
"matcher": "Bash",
|
|
"hooks": [{
|
|
"command": "/bin/bash -c '... cd /workspaces/ruvector/.claude/intelligence && node cli.js ...'"
|
|
}]
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Problems**:
|
|
- ❌ Hardcoded path: `/workspaces/ruvector/.claude/intelligence`
|
|
- ❌ Not portable across projects
|
|
- ❌ Requires manual setup in each repository
|
|
- ❌ Memory data trapped in repo-specific JSON files
|
|
- ❌ No CLI integration for management
|
|
|
|
### 1.2 Desired Goal State
|
|
|
|
**Generic Portable System** (`npx ruvector hooks`):
|
|
```bash
|
|
# Any project can initialize hooks
|
|
npx ruvector hooks init
|
|
|
|
# Install into Claude Code settings
|
|
npx ruvector hooks install
|
|
|
|
# Migrate existing learning data
|
|
npx ruvector hooks migrate --from ~/.swarm/memory.db
|
|
|
|
# View statistics
|
|
npx ruvector hooks stats
|
|
|
|
# Export/import learned patterns
|
|
npx ruvector hooks export --output patterns.json
|
|
npx ruvector hooks import --input patterns.json
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- ✅ Works in ANY project directory
|
|
- ✅ Uses project-local `.ruvector/` directory for state
|
|
- ✅ CLI commands for all hook operations
|
|
- ✅ Migrates claude-flow memory.db → ruvector HNSW
|
|
- ✅ Supports global learning patterns (~/.ruvector/global/)
|
|
- ✅ Zero hardcoded paths in generated hooks
|
|
- ✅ Packaged with `@ruvector/core` npm package
|
|
|
|
---
|
|
|
|
## 2. MILESTONES & SPARC PHASES
|
|
|
|
### Milestone 1: Specification & Architecture Design
|
|
**SPARC Phase**: Specification → Architecture
|
|
**Goal**: Define portable hooks architecture and CLI API contracts
|
|
|
|
#### Actions:
|
|
1. **Design CLI Command Structure**
|
|
- Define all `ruvector hooks <command>` subcommands
|
|
- Specify input/output contracts for each command
|
|
- Design configuration schema for hooks
|
|
|
|
2. **Architecture for Portable Paths**
|
|
- Use environment variables: `$RUVECTOR_HOME`, `$PROJECT_ROOT`
|
|
- Define fallback strategy: project-local → global → embedded
|
|
- Design hook template system with variable substitution
|
|
|
|
3. **Memory Migration Architecture**
|
|
- Map SQLite memory.db schema to ruvector VectorDB format
|
|
- Design trajectory → vector embedding conversion
|
|
- Plan Q-learning state preservation
|
|
|
|
**Deliverables**:
|
|
- [ ] CLI API specification document
|
|
- [ ] Hook template design with variable placeholders
|
|
- [ ] Memory migration schema mapping
|
|
- [ ] Architecture diagrams (ASCII or Mermaid)
|
|
|
|
**Success Criteria**:
|
|
- All CLI commands have clear input/output contracts
|
|
- Hook templates are 100% path-agnostic
|
|
- Migration preserves all learning data integrity
|
|
|
|
---
|
|
|
|
### Milestone 2: CLI Infrastructure Implementation
|
|
**SPARC Phase**: Architecture → Refinement (TDD)
|
|
**Goal**: Implement `ruvector hooks` CLI with full subcommand support
|
|
|
|
#### Actions:
|
|
1. **Add Hooks Subcommand to Rust CLI**
|
|
```rust
|
|
// In src/cli/commands.rs
|
|
enum Commands {
|
|
// ... existing commands
|
|
Hooks {
|
|
#[command(subcommand)]
|
|
action: HooksCommands,
|
|
},
|
|
}
|
|
|
|
enum HooksCommands {
|
|
Init { path: Option<PathBuf> },
|
|
Install,
|
|
Migrate { from: PathBuf },
|
|
Stats,
|
|
Export { output: PathBuf },
|
|
Import { input: PathBuf },
|
|
Enable,
|
|
Disable,
|
|
}
|
|
```
|
|
|
|
2. **Implement Hook Template Generator**
|
|
- Create templates with `{{RUVECTOR_CLI_PATH}}`, `{{PROJECT_ROOT}}` placeholders
|
|
- Dynamic path resolution at runtime
|
|
- Generate `.claude/settings.json` with portable hooks
|
|
|
|
3. **Project-Local State Management**
|
|
- Initialize `.ruvector/` directory structure
|
|
- Create `config.toml` for per-project settings
|
|
- Set up intelligence data directories
|
|
|
|
**Deliverables**:
|
|
- [ ] `ruvector hooks init` command
|
|
- [ ] `ruvector hooks install` command
|
|
- [ ] Hook template engine with variable substitution
|
|
- [ ] `.ruvector/` directory scaffolding
|
|
- [ ] Unit tests for CLI commands
|
|
|
|
**Success Criteria**:
|
|
- `npx ruvector hooks init` works in any directory
|
|
- Generated hooks contain zero hardcoded paths
|
|
- Tests verify cross-platform compatibility (Linux, macOS, Windows)
|
|
|
|
---
|
|
|
|
### Milestone 3: Intelligence Layer Portability
|
|
**SPARC Phase**: Refinement (TDD)
|
|
**Goal**: Make intelligence layer (`index.js`, `cli.js`) portable and embeddable
|
|
|
|
#### Actions:
|
|
1. **Refactor Intelligence Layer for Dynamic Paths**
|
|
```javascript
|
|
// index.js - before
|
|
const DATA_DIR = join(__dirname, 'data');
|
|
|
|
// index.js - after
|
|
const DATA_DIR = process.env.RUVECTOR_DATA_DIR ||
|
|
join(process.cwd(), '.ruvector', 'intelligence');
|
|
```
|
|
|
|
2. **Package Intelligence as NPM Module**
|
|
- Move to `npm/packages/ruvector-intelligence/`
|
|
- Export as standalone package
|
|
- Include in `@ruvector/core` as dependency
|
|
|
|
3. **Environment Variable System**
|
|
```bash
|
|
RUVECTOR_HOME=~/.ruvector # Global learned patterns
|
|
RUVECTOR_DATA_DIR=.ruvector # Project-local data
|
|
RUVECTOR_CLI_PATH=/path/to/cli # Auto-detected
|
|
```
|
|
|
|
4. **Fallback Resolution Strategy**
|
|
```
|
|
1. Project-local: ./.ruvector/intelligence/
|
|
2. Global: ~/.ruvector/global/
|
|
3. Embedded: node_modules/@ruvector/intelligence/
|
|
```
|
|
|
|
**Deliverables**:
|
|
- [ ] Refactored `index.js` with dynamic paths
|
|
- [ ] NPM package `@ruvector/intelligence`
|
|
- [ ] Environment variable documentation
|
|
- [ ] Tests for path resolution fallback chain
|
|
|
|
**Success Criteria**:
|
|
- Intelligence layer works without hardcoded paths
|
|
- Can run in any project directory
|
|
- Gracefully falls back to global patterns if local unavailable
|
|
|
|
---
|
|
|
|
### Milestone 4: Memory Migration System
|
|
**SPARC Phase**: Refinement → Completion
|
|
**Goal**: Migrate claude-flow SQLite memory.db to ruvector's HNSW VectorDB
|
|
|
|
#### Actions:
|
|
1. **Implement SQLite → VectorDB Converter**
|
|
```rust
|
|
// In crates/ruvector-cli/src/cli/hooks/migrate.rs
|
|
pub fn migrate_memory_db(sqlite_path: &Path, output_dir: &Path) -> Result<()> {
|
|
// 1. Read SQLite memory.db
|
|
let conn = Connection::open(sqlite_path)?;
|
|
|
|
// 2. Extract trajectories, Q-table, memories
|
|
let trajectories = extract_trajectories(&conn)?;
|
|
let q_table = extract_q_learning_data(&conn)?;
|
|
|
|
// 3. Convert to vector embeddings
|
|
let embeddings = convert_to_embeddings(&trajectories)?;
|
|
|
|
// 4. Store in ruvector VectorDB
|
|
let db = VectorDB::new(/* config */)?;
|
|
db.insert_batch(embeddings)?;
|
|
|
|
// 5. Export Q-table as JSON
|
|
export_q_table(&q_table, output_dir)?;
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
2. **Design Embedding Conversion Strategy**
|
|
- Trajectory text → vector embedding (reuse `textToEmbedding()`)
|
|
- Preserve Q-values and metadata
|
|
- Map state-action pairs to searchable vectors
|
|
|
|
3. **Preserve Learning Integrity**
|
|
- Validate Q-table checksums
|
|
- Ensure all trajectories migrated
|
|
- Verify searchable recall accuracy
|
|
|
|
**Deliverables**:
|
|
- [ ] `ruvector hooks migrate` command implementation
|
|
- [ ] SQLite schema parser
|
|
- [ ] Embedding conversion engine
|
|
- [ ] Migration validation tests
|
|
- [ ] Rollback/recovery mechanism
|
|
|
|
**Success Criteria**:
|
|
- 100% of memory.db data successfully migrated
|
|
- Q-learning patterns preserved accurately
|
|
- Vector search recalls migrated memories correctly
|
|
- Migration completes in <5 seconds for typical datasets
|
|
|
|
---
|
|
|
|
### Milestone 5: Hook Template System
|
|
**SPARC Phase**: Completion
|
|
**Goal**: Generate dynamic, portable hook configurations for `.claude/settings.json`
|
|
|
|
#### Actions:
|
|
1. **Create Hook Templates with Placeholders**
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PreToolUse": [{
|
|
"matcher": "Bash",
|
|
"hooks": [{
|
|
"command": "/bin/bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command // empty\"); {{RUVECTOR_CLI_PATH}} hooks pre-command \"$CMD\" 2>/dev/null'"
|
|
}]
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
2. **Variable Substitution Engine**
|
|
```rust
|
|
fn substitute_template_vars(template: &str) -> Result<String> {
|
|
let vars = HashMap::from([
|
|
("RUVECTOR_CLI_PATH", get_cli_path()?),
|
|
("PROJECT_ROOT", env::current_dir()?.to_str().unwrap()),
|
|
("RUVECTOR_HOME", get_ruvector_home()?),
|
|
]);
|
|
|
|
let mut output = template.to_string();
|
|
for (key, value) in vars {
|
|
output = output.replace(&format!("{{{{{}}}}}", key), value);
|
|
}
|
|
Ok(output)
|
|
}
|
|
```
|
|
|
|
3. **Install Command Implementation**
|
|
```rust
|
|
pub fn install_hooks() -> Result<()> {
|
|
// 1. Load template from embedded resource
|
|
let template = include_str!("../templates/hooks.json");
|
|
|
|
// 2. Substitute variables
|
|
let config = substitute_template_vars(template)?;
|
|
|
|
// 3. Merge with existing .claude/settings.json
|
|
let settings_path = Path::new(".claude/settings.json");
|
|
merge_or_create_settings(settings_path, &config)?;
|
|
|
|
println!("✅ Hooks installed to .claude/settings.json");
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
**Deliverables**:
|
|
- [ ] Hook template files (JSON)
|
|
- [ ] Variable substitution engine
|
|
- [ ] `ruvector hooks install` implementation
|
|
- [ ] Merge strategy for existing settings
|
|
- [ ] Tests for template rendering
|
|
|
|
**Success Criteria**:
|
|
- Generated hooks work on first run without modification
|
|
- No hardcoded paths in output
|
|
- Merges safely with existing Claude Code settings
|
|
- Preserves user customizations
|
|
|
|
---
|
|
|
|
### Milestone 6: Global Learning Patterns
|
|
**SPARC Phase**: Completion
|
|
**Goal**: Support cross-project learning via `~/.ruvector/global/`
|
|
|
|
#### Actions:
|
|
1. **Global Pattern Storage**
|
|
```
|
|
~/.ruvector/
|
|
├── global/
|
|
│ ├── patterns.json # Shared Q-learning patterns
|
|
│ ├── memory.rvdb # Global vector memory
|
|
│ ├── error-patterns.json # Cross-project error fixes
|
|
│ └── sequences.json # File sequence patterns
|
|
└── config.toml # Global settings
|
|
```
|
|
|
|
2. **Pattern Synchronization**
|
|
- Merge project-local + global patterns on load
|
|
- Update global patterns when local patterns succeed
|
|
- Privacy controls: opt-in/opt-out for global sharing
|
|
|
|
3. **Import/Export Commands**
|
|
```bash
|
|
# Export project patterns to share with team
|
|
npx ruvector hooks export --output team-patterns.json
|
|
|
|
# Import patterns from another project
|
|
npx ruvector hooks import --input team-patterns.json --merge
|
|
```
|
|
|
|
**Deliverables**:
|
|
- [ ] Global pattern storage system
|
|
- [ ] Pattern merge algorithm
|
|
- [ ] `ruvector hooks export` command
|
|
- [ ] `ruvector hooks import` command
|
|
- [ ] Privacy controls configuration
|
|
|
|
**Success Criteria**:
|
|
- Patterns learned in one project help in another
|
|
- No data leakage between unrelated projects
|
|
- Export/import preserves all learning data
|
|
- Team can share learned patterns via JSON
|
|
|
|
---
|
|
|
|
### Milestone 7: Integration Testing & Documentation
|
|
**SPARC Phase**: Completion
|
|
**Goal**: Ensure system works end-to-end in real-world scenarios
|
|
|
|
#### Actions:
|
|
1. **Integration Test Suite**
|
|
```bash
|
|
# Test 1: Fresh project setup
|
|
mkdir test-project && cd test-project
|
|
npx ruvector hooks init
|
|
npx ruvector hooks install
|
|
# Verify .claude/settings.json generated correctly
|
|
|
|
# Test 2: Migration from claude-flow
|
|
npx ruvector hooks migrate --from ~/.swarm/memory.db
|
|
npx ruvector hooks stats
|
|
# Verify patterns imported
|
|
|
|
# Test 3: Cross-platform compatibility
|
|
# Run on Linux, macOS, Windows
|
|
```
|
|
|
|
2. **Documentation**
|
|
- User guide: Setting up hooks in a new project
|
|
- Migration guide: Moving from claude-flow
|
|
- API reference: CLI command documentation
|
|
- Troubleshooting: Common issues and solutions
|
|
|
|
3. **Examples and Templates**
|
|
- Example `.ruvector/config.toml` configurations
|
|
- Sample hook customizations
|
|
- Team sharing workflow examples
|
|
|
|
**Deliverables**:
|
|
- [ ] Integration test suite (Rust + Bash scripts)
|
|
- [ ] User documentation (`docs/hooks/USER_GUIDE.md`)
|
|
- [ ] Migration guide (`docs/hooks/MIGRATION.md`)
|
|
- [ ] API reference (`docs/hooks/CLI_REFERENCE.md`)
|
|
- [ ] Example configurations
|
|
|
|
**Success Criteria**:
|
|
- All integration tests pass on Linux, macOS, Windows
|
|
- Documentation enables first-time user to set up hooks in <5 minutes
|
|
- Migration guide successfully migrates all test cases
|
|
- No hardcoded paths in final system
|
|
|
|
---
|
|
|
|
## 3. FILE STRUCTURE
|
|
|
|
### 3.1 New Directory Layout
|
|
|
|
```
|
|
ruvector/
|
|
├── crates/ruvector-cli/
|
|
│ ├── src/
|
|
│ │ ├── cli/
|
|
│ │ │ ├── commands.rs # Add HooksCommands enum
|
|
│ │ │ ├── hooks/ # NEW: Hooks CLI module
|
|
│ │ │ │ ├── mod.rs
|
|
│ │ │ │ ├── init.rs # `hooks init` implementation
|
|
│ │ │ │ ├── install.rs # `hooks install` implementation
|
|
│ │ │ │ ├── migrate.rs # `hooks migrate` implementation
|
|
│ │ │ │ ├── stats.rs # `hooks stats` implementation
|
|
│ │ │ │ ├── export.rs # `hooks export` implementation
|
|
│ │ │ │ └── import.rs # `hooks import` implementation
|
|
│ │ │ └── ...
|
|
│ │ └── main.rs
|
|
│ ├── templates/ # NEW: Hook templates
|
|
│ │ ├── hooks.json # Portable hooks template
|
|
│ │ ├── config.toml.template # Project config template
|
|
│ │ └── settings.json.template # Claude settings template
|
|
│ └── Cargo.toml
|
|
│
|
|
├── npm/packages/
|
|
│ ├── ruvector-intelligence/ # NEW: Portable intelligence package
|
|
│ │ ├── src/
|
|
│ │ │ ├── index.js # Refactored with dynamic paths
|
|
│ │ │ ├── cli.js # Refactored CLI
|
|
│ │ │ ├── memory.js # VectorMemory class
|
|
│ │ │ ├── reasoning.js # ReasoningBank class
|
|
│ │ │ └── ...
|
|
│ │ ├── templates/ # Hook integration templates
|
|
│ │ │ └── hooks.json
|
|
│ │ ├── package.json
|
|
│ │ └── README.md
|
|
│ │
|
|
│ └── core/ # Existing @ruvector/core
|
|
│ └── package.json # Add intelligence as dependency
|
|
│
|
|
├── docs/hooks/
|
|
│ ├── IMPLEMENTATION_PLAN.md # This document
|
|
│ ├── USER_GUIDE.md # NEW: User-facing guide
|
|
│ ├── MIGRATION.md # NEW: Migration from claude-flow
|
|
│ ├── CLI_REFERENCE.md # NEW: CLI command reference
|
|
│ └── ARCHITECTURE.md # NEW: Technical architecture
|
|
│
|
|
└── .ruvector/ # NEW: Project-local state (gitignored)
|
|
├── config.toml # Project-specific settings
|
|
├── intelligence/
|
|
│ ├── data/
|
|
│ │ ├── memory.json
|
|
│ │ ├── trajectories.json
|
|
│ │ ├── patterns.json
|
|
│ │ └── ...
|
|
│ └── memory.rvdb # Ruvector VectorDB storage
|
|
└── .gitignore
|
|
```
|
|
|
|
### 3.2 Global State Directory
|
|
|
|
```
|
|
~/.ruvector/ # Global user state
|
|
├── global/
|
|
│ ├── patterns.json # Cross-project patterns
|
|
│ ├── memory.rvdb # Global vector memory
|
|
│ ├── error-patterns.json # Error fixes
|
|
│ └── sequences.json # File sequences
|
|
├── config.toml # Global configuration
|
|
└── cache/ # CLI cache
|
|
└── cli-path.txt
|
|
```
|
|
|
|
---
|
|
|
|
## 4. CLI API DESIGN
|
|
|
|
### 4.1 Command Reference
|
|
|
|
#### `ruvector hooks init [OPTIONS]`
|
|
Initialize hooks system in the current project.
|
|
|
|
**Options**:
|
|
- `--path <PATH>`: Custom `.ruvector` directory location (default: `./.ruvector`)
|
|
- `--global`: Initialize global patterns directory
|
|
- `--template <NAME>`: Use a predefined template (default, minimal, advanced)
|
|
|
|
**Behavior**:
|
|
1. Create `.ruvector/` directory structure
|
|
2. Generate `config.toml` with defaults
|
|
3. Initialize empty data files
|
|
4. Output next steps (run `hooks install`)
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks init
|
|
# Output:
|
|
# ✅ Initialized ruvector hooks in ./.ruvector
|
|
# 📁 Created: .ruvector/intelligence/data/
|
|
# ⏭ Next: Run `npx ruvector hooks install` to add hooks to Claude Code
|
|
```
|
|
|
|
---
|
|
|
|
#### `ruvector hooks install [OPTIONS]`
|
|
Install hooks into `.claude/settings.json`.
|
|
|
|
**Options**:
|
|
- `--force`: Overwrite existing hooks
|
|
- `--dry-run`: Show what would be written without modifying files
|
|
- `--template <PATH>`: Use custom hook template
|
|
|
|
**Behavior**:
|
|
1. Load hook template from `templates/hooks.json`
|
|
2. Substitute variables (`{{RUVECTOR_CLI_PATH}}`, etc.)
|
|
3. Merge with existing `.claude/settings.json` or create new
|
|
4. Validate JSON syntax
|
|
5. Backup original settings to `.claude/settings.json.backup`
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks install
|
|
# Output:
|
|
# ✅ Hooks installed to .claude/settings.json
|
|
# 📋 Backup created: .claude/settings.json.backup
|
|
# 🧠 Intelligence layer ready
|
|
```
|
|
|
|
---
|
|
|
|
#### `ruvector hooks migrate --from <PATH> [OPTIONS]`
|
|
Migrate learning data from claude-flow or other sources.
|
|
|
|
**Options**:
|
|
- `--from <PATH>`: Source database path (SQLite or JSON)
|
|
- `--format <FORMAT>`: Source format (sqlite, json, csv)
|
|
- `--merge`: Merge with existing patterns instead of replacing
|
|
- `--validate`: Validate migration integrity
|
|
|
|
**Behavior**:
|
|
1. Detect source format (SQLite, JSON, or CSV)
|
|
2. Parse trajectories, Q-table, and memories
|
|
3. Convert to ruvector format (vector embeddings + JSON patterns)
|
|
4. Store in `.ruvector/intelligence/`
|
|
5. Validate migration (checksum, count verification)
|
|
6. Report statistics
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks migrate --from ~/.swarm/memory.db --validate
|
|
# Output:
|
|
# 📊 Migrating from SQLite database...
|
|
# ✅ Imported 1,247 trajectories
|
|
# ✅ Imported 89 Q-learning patterns
|
|
# ✅ Converted 543 memories to vectors
|
|
# 🔍 Validation passed (100% integrity)
|
|
# ⏱ Completed in 3.2s
|
|
```
|
|
|
|
---
|
|
|
|
#### `ruvector hooks stats [OPTIONS]`
|
|
Display learning statistics and system health.
|
|
|
|
**Options**:
|
|
- `--verbose`: Show detailed breakdown
|
|
- `--json`: Output as JSON for programmatic use
|
|
- `--compare-global`: Compare local vs global patterns
|
|
|
|
**Behavior**:
|
|
1. Load local patterns from `.ruvector/intelligence/`
|
|
2. Calculate statistics (pattern count, memory size, etc.)
|
|
3. Display formatted output
|
|
4. Optional: Compare with global patterns
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks stats --verbose
|
|
# Output:
|
|
# 🧠 RuVector Intelligence Statistics
|
|
#
|
|
# 📊 Learning Data:
|
|
# Trajectories: 1,247
|
|
# Patterns: 89 (Q-learning states)
|
|
# Memories: 543 vectors
|
|
# Total size: 2.4 MB
|
|
#
|
|
# 🎯 Top Patterns:
|
|
# 1. edit_rs_in_ruvector-core → successful-edit (Q=0.823)
|
|
# 2. cargo_test → command-succeeded (Q=0.791)
|
|
# 3. npm_build → command-succeeded (Q=0.654)
|
|
#
|
|
# 🔥 Recent Activity:
|
|
# Last trajectory: 2 hours ago
|
|
# A/B test group: treatment
|
|
# Calibration error: 0.042
|
|
```
|
|
|
|
---
|
|
|
|
#### `ruvector hooks export --output <PATH> [OPTIONS]`
|
|
Export learned patterns for sharing or backup.
|
|
|
|
**Options**:
|
|
- `--output <PATH>`: Output file path
|
|
- `--format <FORMAT>`: Export format (json, csv, sqlite)
|
|
- `--include <TYPES>`: What to include (patterns, memories, all)
|
|
- `--compress`: Compress output with gzip
|
|
|
|
**Behavior**:
|
|
1. Read patterns from `.ruvector/intelligence/`
|
|
2. Serialize to specified format
|
|
3. Optional: Compress with gzip
|
|
4. Write to output file
|
|
5. Generate checksum for integrity
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks export --output team-patterns.json --include patterns
|
|
# Output:
|
|
# ✅ Exported 89 patterns to team-patterns.json
|
|
# 📦 Size: 45.2 KB
|
|
# 🔐 SHA256: 8f3b4c2a...
|
|
```
|
|
|
|
---
|
|
|
|
#### `ruvector hooks import --input <PATH> [OPTIONS]`
|
|
Import learned patterns from another project or team member.
|
|
|
|
**Options**:
|
|
- `--input <PATH>`: Input file path
|
|
- `--merge`: Merge with existing patterns (default: replace)
|
|
- `--strategy <STRATEGY>`: Merge strategy (prefer-local, prefer-imported, average)
|
|
- `--validate`: Validate before importing
|
|
|
|
**Behavior**:
|
|
1. Read input file
|
|
2. Parse and validate patterns
|
|
3. Merge with existing patterns (if `--merge`)
|
|
4. Write to `.ruvector/intelligence/`
|
|
5. Report import statistics
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks import --input team-patterns.json --merge --strategy average
|
|
# Output:
|
|
# 📥 Importing patterns...
|
|
# ✅ Imported 89 patterns
|
|
# 🔀 Merged with 67 existing patterns
|
|
# 📊 New total: 123 patterns (33 updated, 56 unchanged)
|
|
```
|
|
|
|
---
|
|
|
|
#### `ruvector hooks enable` / `ruvector hooks disable`
|
|
Enable or disable hooks system.
|
|
|
|
**Behavior**:
|
|
- `enable`: Set `RUVECTOR_INTELLIGENCE_ENABLED=true` in config
|
|
- `disable`: Set `RUVECTOR_INTELLIGENCE_ENABLED=false` in config
|
|
|
|
**Example**:
|
|
```bash
|
|
npx ruvector hooks disable
|
|
# Output:
|
|
# ⏸ Hooks disabled (set RUVECTOR_INTELLIGENCE_ENABLED=false)
|
|
# 💡 Re-enable with: npx ruvector hooks enable
|
|
```
|
|
|
|
---
|
|
|
|
### 4.2 Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `RUVECTOR_HOME` | `~/.ruvector` | Global patterns directory |
|
|
| `RUVECTOR_DATA_DIR` | `./.ruvector` | Project-local data directory |
|
|
| `RUVECTOR_CLI_PATH` | Auto-detected | Path to ruvector CLI binary |
|
|
| `RUVECTOR_INTELLIGENCE_ENABLED` | `true` | Enable/disable intelligence layer |
|
|
| `RUVECTOR_LEARNING_RATE` | `0.1` | Q-learning alpha parameter |
|
|
| `INTELLIGENCE_MODE` | `treatment` | A/B test group (treatment, control) |
|
|
|
|
---
|
|
|
|
### 4.3 Configuration File Schema
|
|
|
|
#### `.ruvector/config.toml`
|
|
|
|
```toml
|
|
[intelligence]
|
|
enabled = true
|
|
learning_rate = 0.1
|
|
ab_test_group = "treatment" # or "control"
|
|
use_hyperbolic_distance = true
|
|
curvature = 1.0
|
|
|
|
[memory]
|
|
backend = "rvdb" # or "json" for fallback
|
|
max_memories = 50000
|
|
dimensions = 128
|
|
|
|
[patterns]
|
|
decay_half_life_days = 7
|
|
min_q_value = -0.5
|
|
max_q_value = 0.8
|
|
|
|
[global]
|
|
sync_enabled = true # Sync with ~/.ruvector/global/
|
|
sync_interval_hours = 24
|
|
privacy_mode = "opt-in" # or "opt-out"
|
|
|
|
[hooks]
|
|
pre_command_enabled = true
|
|
post_command_enabled = true
|
|
pre_edit_enabled = true
|
|
post_edit_enabled = true
|
|
pre_compact_enabled = true
|
|
session_start_enabled = true
|
|
session_end_enabled = true
|
|
```
|
|
|
|
---
|
|
|
|
## 5. MIGRATION STRATEGY
|
|
|
|
### 5.1 Existing User Migration Path
|
|
|
|
**For users with `.claude/intelligence/` (current repo-specific system)**:
|
|
|
|
1. **Backup existing data**:
|
|
```bash
|
|
cp -r .claude/intelligence .claude/intelligence.backup
|
|
```
|
|
|
|
2. **Initialize new system**:
|
|
```bash
|
|
npx ruvector hooks init
|
|
```
|
|
|
|
3. **Migrate data**:
|
|
```bash
|
|
# Intelligence layer data (JSON files)
|
|
npx ruvector hooks migrate --from .claude/intelligence --format json
|
|
|
|
# Claude-flow memory.db (if exists)
|
|
npx ruvector hooks migrate --from ~/.swarm/memory.db --merge
|
|
```
|
|
|
|
4. **Update hooks**:
|
|
```bash
|
|
npx ruvector hooks install --force
|
|
```
|
|
|
|
5. **Verify**:
|
|
```bash
|
|
npx ruvector hooks stats
|
|
```
|
|
|
|
6. **Clean up**:
|
|
```bash
|
|
# Optional: Remove old intelligence directory
|
|
rm -rf .claude/intelligence
|
|
```
|
|
|
|
---
|
|
|
|
### 5.2 Claude-Flow Memory.db Migration
|
|
|
|
**SQLite Schema** (inferred from claude-flow):
|
|
```sql
|
|
CREATE TABLE trajectories (
|
|
id TEXT PRIMARY KEY,
|
|
state TEXT,
|
|
action TEXT,
|
|
outcome TEXT,
|
|
reward REAL,
|
|
timestamp TEXT,
|
|
ab_group TEXT
|
|
);
|
|
|
|
CREATE TABLE memories (
|
|
id TEXT PRIMARY KEY,
|
|
type TEXT,
|
|
content TEXT,
|
|
embedding BLOB, -- Serialized float array
|
|
metadata TEXT -- JSON
|
|
);
|
|
|
|
CREATE TABLE q_table (
|
|
state TEXT,
|
|
action TEXT,
|
|
q_value REAL,
|
|
update_count INTEGER,
|
|
last_update TEXT,
|
|
PRIMARY KEY (state, action)
|
|
);
|
|
```
|
|
|
|
**Migration Algorithm**:
|
|
```rust
|
|
pub fn migrate_memory_db(sqlite_path: &Path, output_dir: &Path) -> Result<MigrationStats> {
|
|
let conn = Connection::open(sqlite_path)?;
|
|
let mut stats = MigrationStats::default();
|
|
|
|
// 1. Migrate trajectories
|
|
let mut stmt = conn.prepare("SELECT * FROM trajectories")?;
|
|
let trajectories: Vec<Trajectory> = stmt.query_map([], |row| {
|
|
Ok(Trajectory {
|
|
id: row.get(0)?,
|
|
state: row.get(1)?,
|
|
action: row.get(2)?,
|
|
outcome: row.get(3)?,
|
|
reward: row.get(4)?,
|
|
timestamp: row.get(5)?,
|
|
ab_group: row.get(6)?,
|
|
})
|
|
})?.collect::<Result<Vec<_>, _>>()?;
|
|
|
|
fs::write(
|
|
output_dir.join("trajectories.json"),
|
|
serde_json::to_string_pretty(&trajectories)?
|
|
)?;
|
|
stats.trajectories = trajectories.len();
|
|
|
|
// 2. Migrate Q-table
|
|
let mut stmt = conn.prepare("SELECT * FROM q_table")?;
|
|
let q_table: HashMap<String, HashMap<String, f64>> = /* ... */;
|
|
fs::write(
|
|
output_dir.join("patterns.json"),
|
|
serde_json::to_string_pretty(&q_table)?
|
|
)?;
|
|
stats.patterns = q_table.len();
|
|
|
|
// 3. Migrate memories to VectorDB
|
|
let mut stmt = conn.prepare("SELECT * FROM memories")?;
|
|
let db = VectorDB::new(/* ... */)?;
|
|
|
|
let memories = stmt.query_map([], |row| {
|
|
let id: String = row.get(0)?;
|
|
let type_: String = row.get(1)?;
|
|
let content: String = row.get(2)?;
|
|
let embedding: Vec<u8> = row.get(3)?;
|
|
let metadata: String = row.get(4)?;
|
|
|
|
// Deserialize embedding blob
|
|
let embedding_f32 = deserialize_embedding(&embedding)?;
|
|
|
|
Ok(VectorEntry {
|
|
id: Some(id),
|
|
vector: embedding_f32,
|
|
metadata: Some(serde_json::from_str(&metadata)?),
|
|
})
|
|
})?.collect::<Result<Vec<_>, _>>()?;
|
|
|
|
db.insert_batch(memories)?;
|
|
stats.memories = memories.len();
|
|
|
|
// 4. Validation
|
|
validate_migration(&stats, &conn, &db)?;
|
|
|
|
Ok(stats)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 5.3 Backwards Compatibility
|
|
|
|
**Support Matrix**:
|
|
| Feature | Legacy (repo-specific) | New (portable) | Notes |
|
|
|---------|------------------------|----------------|-------|
|
|
| JSON data files | ✅ Supported | ✅ Supported | Automatic migration |
|
|
| Hardcoded paths | ✅ Still works | ❌ Replaced | Use `hooks install` to update |
|
|
| SQLite memory.db | ❌ Not supported | ✅ Via migration | One-time migration required |
|
|
| Global patterns | ❌ Not available | ✅ Supported | New feature |
|
|
| CLI management | ❌ Manual editing | ✅ Full CLI | Recommended upgrade path |
|
|
|
|
---
|
|
|
|
## 6. RISK ASSESSMENT & MITIGATION
|
|
|
|
### 6.1 Technical Risks
|
|
|
|
| Risk | Probability | Impact | Mitigation |
|
|
|------|-------------|--------|------------|
|
|
| Path resolution fails on Windows | Medium | High | Use `shellexpand` crate, conditional shell (`cmd` vs `bash`), test on PowerShell |
|
|
| Migration loses learning data | Low | Critical | Atomic migration with automatic backup/rollback, checksums, validation |
|
|
| Performance regression | Medium | Medium | Benchmark before/after, optimize hot paths |
|
|
| Breaking changes for existing users | High | Medium | Migration guide, backwards compatibility layer, keep `.claude/intelligence` working |
|
|
| Hook template bugs | Medium | High | Integration tests, `--dry-run` mode, type-safe templates with `askama` |
|
|
| Command injection in hooks | Low | Critical | Escape all shell arguments with `shell-escape` crate |
|
|
| SQLite format incompatibility | High | High | **MVP: JSON migration only**, defer SQLite to v1.1 with format detection |
|
|
|
|
### 6.2 User Experience Risks
|
|
|
|
| Risk | Probability | Impact | Mitigation |
|
|
|------|-------------|--------|------------|
|
|
| Complex migration process | Medium | High | Automated migration scripts, clear documentation |
|
|
| Configuration complexity | Medium | Medium | Sensible defaults, templates, examples |
|
|
| Unclear error messages | High | Medium | User-friendly error messages, troubleshooting guide |
|
|
| Lost productivity during transition | Medium | High | Gradual rollout, backwards compatibility |
|
|
|
|
---
|
|
|
|
## 7. SUCCESS METRICS
|
|
|
|
### 7.1 Technical Metrics
|
|
|
|
- **Portability**: ✅ Works on 3+ operating systems (Linux, macOS, Windows)
|
|
- **Performance**: ✅ Migration completes in <10 seconds for 10k trajectories
|
|
- **Reliability**: ✅ 100% data integrity in migration (validated via checksums)
|
|
- **Compatibility**: ✅ Backwards compatible with existing JSON data files
|
|
|
|
### 7.2 User Metrics
|
|
|
|
- **Setup Time**: ✅ New user can set up hooks in <5 minutes
|
|
- **Migration Success**: ✅ 95%+ of users successfully migrate without assistance
|
|
- **Adoption**: ✅ 80%+ of active users upgrade within 1 month
|
|
- **Satisfaction**: ✅ Positive feedback on portability and ease of use
|
|
|
|
### 7.3 Code Quality Metrics
|
|
|
|
- **Test Coverage**: ✅ >80% coverage for CLI commands and migration logic
|
|
- **Documentation**: ✅ All CLI commands documented with examples
|
|
- **Code Review**: ✅ All code reviewed and approved
|
|
- **No Regressions**: ✅ All existing functionality preserved
|
|
|
|
---
|
|
|
|
## 8. TIMELINE ESTIMATES
|
|
|
|
| Milestone | Estimated Time | Dependencies | MVP |
|
|
|-----------|----------------|--------------|-----|
|
|
| 1. Specification & Architecture | 2-3 days | None | ✅ |
|
|
| 2+5. CLI + Template System (Combined) | 4-5 days | Milestone 1 | ✅ |
|
|
| 3. Intelligence Layer Portability | 3-4 days | Milestone 1 | ✅ |
|
|
| 4a. JSON Migration (MVP) | 2 days | Milestone 3 | ✅ |
|
|
| 4b. SQLite Migration (v1.1) | 4-5 days | Milestone 4a | ❌ Deferred |
|
|
| 6. Global Patterns (v1.1) | 4-5 days | Milestone 3, 4 | ❌ Deferred |
|
|
| 7. Integration Testing & Documentation | 4-5 days | Milestones 1-4a | ✅ |
|
|
| **MVP Total** | **15-19 days** | (~3-4 weeks) | |
|
|
| **Full Release (v1.1+)** | **27-38 days** | (~5-7 weeks) | |
|
|
|
|
---
|
|
|
|
## 9. NEXT STEPS
|
|
|
|
### Immediate Actions (Week 1)
|
|
1. **Review and approve this implementation plan**
|
|
2. **Set up development branch**: `feature/portable-hooks-system`
|
|
3. **Create initial file structure**: directories, templates, module stubs
|
|
4. **Write specification documents**: CLI API, hook template format
|
|
5. **Design test cases**: integration tests, migration scenarios
|
|
|
|
### Phase 1 (Weeks 2-3): Foundation
|
|
- Implement CLI command structure (`HooksCommands` enum)
|
|
- Create hook template engine with variable substitution
|
|
- Implement `ruvector hooks init` and `ruvector hooks install`
|
|
- Write unit tests for template generation
|
|
|
|
### Phase 2 (Weeks 4-5): Intelligence & Migration
|
|
- Refactor intelligence layer for dynamic paths
|
|
- Package as `@ruvector/intelligence` npm module
|
|
- Implement SQLite → VectorDB migration
|
|
- Implement `ruvector hooks migrate`
|
|
|
|
### Phase 3 (Weeks 6-7): Advanced Features
|
|
- Implement global patterns system
|
|
- Add `ruvector hooks export/import`
|
|
- Create integration tests
|
|
- Write comprehensive documentation
|
|
|
|
### Phase 4 (Week 8): Polish & Release
|
|
- Cross-platform testing (Linux, macOS, Windows)
|
|
- User acceptance testing
|
|
- Documentation review
|
|
- Release candidate and final release
|
|
|
|
---
|
|
|
|
## 10. APPENDICES
|
|
|
|
### Appendix A: Example Hook Template
|
|
|
|
```json
|
|
{
|
|
"env": {
|
|
"RUVECTOR_INTELLIGENCE_ENABLED": "true",
|
|
"RUVECTOR_LEARNING_RATE": "0.1",
|
|
"INTELLIGENCE_MODE": "treatment"
|
|
},
|
|
"hooks": {
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"timeout": 3000,
|
|
"command": "/bin/bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command // empty\"); {{RUVECTOR_CLI_PATH}} hooks pre-command \"$CMD\" 2>/dev/null'"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"matcher": "Write|Edit|MultiEdit",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"timeout": 3000,
|
|
"command": "/bin/bash -c 'INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // .tool_input.path // empty\"); if [ -n \"$FILE\" ]; then {{RUVECTOR_CLI_PATH}} hooks pre-edit \"$FILE\" 2>/dev/null; fi'"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"PostToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "/bin/bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command // empty\"); SUCCESS=\"true\"; STDERR=\"\"; if echo \"$INPUT\" | jq -e \".tool_result.stderr\" 2>/dev/null | grep -q .; then SUCCESS=\"false\"; STDERR=$(echo \"$INPUT\" | jq -r \".tool_result.stderr // empty\" | head -c 300); fi; ({{RUVECTOR_CLI_PATH}} hooks post-command \"$CMD\" \"$SUCCESS\" \"$STDERR\" 2>/dev/null) &'"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"matcher": "Write|Edit|MultiEdit",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "/bin/bash -c 'INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // .tool_input.path // empty\"); if [ -n \"$FILE\" ]; then ({{RUVECTOR_CLI_PATH}} hooks post-edit \"$FILE\" \"true\" 2>/dev/null) & fi'"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"SessionStart": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"timeout": 5000,
|
|
"command": "{{RUVECTOR_CLI_PATH}} hooks session-start"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"Stop": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "{{RUVECTOR_CLI_PATH}} hooks session-end"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Appendix B: Migration Validation Tests
|
|
|
|
```rust
|
|
#[cfg(test)]
|
|
mod migration_tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn test_sqlite_to_json_migration() {
|
|
let temp_dir = tempfile::tempdir().unwrap();
|
|
let sqlite_path = create_test_sqlite_db(&temp_dir);
|
|
|
|
let stats = migrate_memory_db(&sqlite_path, temp_dir.path()).unwrap();
|
|
|
|
assert_eq!(stats.trajectories, 100);
|
|
assert_eq!(stats.patterns, 25);
|
|
assert_eq!(stats.memories, 50);
|
|
}
|
|
|
|
#[test]
|
|
fn test_embedding_preservation() {
|
|
let original_embedding = vec![0.1, 0.2, 0.3, 0.4];
|
|
let serialized = serialize_embedding(&original_embedding);
|
|
let deserialized = deserialize_embedding(&serialized).unwrap();
|
|
|
|
assert_eq!(original_embedding, deserialized);
|
|
}
|
|
|
|
#[test]
|
|
fn test_q_value_accuracy() {
|
|
let temp_dir = tempfile::tempdir().unwrap();
|
|
let sqlite_path = create_test_sqlite_db(&temp_dir);
|
|
|
|
migrate_memory_db(&sqlite_path, temp_dir.path()).unwrap();
|
|
|
|
let patterns: HashMap<String, HashMap<String, f64>> =
|
|
serde_json::from_str(&fs::read_to_string(
|
|
temp_dir.path().join("patterns.json")
|
|
).unwrap()).unwrap();
|
|
|
|
// Verify Q-values preserved
|
|
assert!((patterns["test_state"]["test_action"] - 0.823).abs() < 0.001);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Appendix C: Cross-Platform Path Resolution
|
|
|
|
```rust
|
|
use shellexpand;
|
|
use std::env;
|
|
|
|
fn get_ruvector_home() -> Result<PathBuf> {
|
|
if let Ok(home) = env::var("RUVECTOR_HOME") {
|
|
return Ok(PathBuf::from(shellexpand::tilde(&home).to_string()));
|
|
}
|
|
|
|
let home_dir = dirs::home_dir()
|
|
.ok_or_else(|| anyhow!("Could not determine home directory"))?;
|
|
|
|
Ok(home_dir.join(".ruvector"))
|
|
}
|
|
|
|
fn get_cli_path() -> Result<String> {
|
|
// 1. Check if already in PATH
|
|
if let Ok(path) = which::which("ruvector") {
|
|
return Ok(path.display().to_string());
|
|
}
|
|
|
|
// 2. Check if running via npx
|
|
if let Ok(npm_execpath) = env::var("npm_execpath") {
|
|
if npm_execpath.contains("npx") {
|
|
return Ok("npx ruvector".to_string());
|
|
}
|
|
}
|
|
|
|
// 3. Fallback to current executable
|
|
env::current_exe()
|
|
.map(|p| p.display().to_string())
|
|
.map_err(|e| anyhow!("Could not determine CLI path: {}", e))
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 11. CRITICAL FIXES REQUIRED
|
|
|
|
### 11.1 Windows Shell Compatibility
|
|
|
|
**Add to Milestone 5** (Hook Template System):
|
|
|
|
```rust
|
|
// In crates/ruvector-cli/src/cli/hooks/install.rs
|
|
|
|
fn get_shell_wrapper() -> &'static str {
|
|
if cfg!(target_os = "windows") {
|
|
"cmd /c"
|
|
} else {
|
|
"/bin/bash -c"
|
|
}
|
|
}
|
|
|
|
fn render_hook_template(template: &str) -> Result<String> {
|
|
let vars = HashMap::from([
|
|
("SHELL", get_shell_wrapper()),
|
|
("RUVECTOR_CLI", "which ruvector || echo npx ruvector"),
|
|
// Runtime resolution instead of install-time
|
|
]);
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### 11.2 Atomic Migration with Rollback
|
|
|
|
**Add to Milestone 4a** (JSON Migration):
|
|
|
|
```rust
|
|
// In crates/ruvector-cli/src/cli/hooks/migrate.rs
|
|
|
|
pub fn migrate_with_safety(from: &Path, to: &Path) -> Result<MigrationStats> {
|
|
let backup_dir = to.with_extension("backup");
|
|
let temp_dir = to.with_extension("tmp");
|
|
|
|
// Step 1: Backup existing data
|
|
if to.exists() {
|
|
fs::rename(to, &backup_dir)?;
|
|
}
|
|
|
|
// Step 2: Migrate to temporary location
|
|
fs::create_dir_all(&temp_dir)?;
|
|
let stats = match do_migration(from, &temp_dir) {
|
|
Ok(s) => s,
|
|
Err(e) => {
|
|
// Restore backup on failure
|
|
fs::remove_dir_all(&temp_dir)?;
|
|
if backup_dir.exists() {
|
|
fs::rename(&backup_dir, to)?;
|
|
}
|
|
return Err(e);
|
|
}
|
|
};
|
|
|
|
// Step 3: Validate migrated data
|
|
validate_migration(&temp_dir, &stats)?;
|
|
|
|
// Step 4: Atomic swap
|
|
fs::rename(&temp_dir, to)?;
|
|
fs::remove_dir_all(&backup_dir)?;
|
|
|
|
Ok(stats)
|
|
}
|
|
```
|
|
|
|
### 11.3 Command Injection Prevention
|
|
|
|
**Add to all hook templates**:
|
|
|
|
```rust
|
|
// Add to Cargo.toml:
|
|
// shell-escape = "0.1"
|
|
|
|
use shell_escape::escape;
|
|
|
|
fn generate_hook_command(file_path: &str) -> String {
|
|
let escaped = escape(file_path.into());
|
|
format!(
|
|
r#"/bin/bash -c 'FILE={}; ruvector hooks pre-edit "$FILE"'"#,
|
|
escaped
|
|
)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 12. RECOMMENDED DEPENDENCY ADDITIONS
|
|
|
|
Add to `crates/ruvector-cli/Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
# Existing dependencies...
|
|
|
|
# For SQLite migration (v1.1)
|
|
rusqlite = { version = "0.32", optional = true }
|
|
|
|
# For type-safe templates
|
|
askama = "0.12"
|
|
|
|
# For shell argument escaping
|
|
shell-escape = "0.1"
|
|
|
|
# Already present (good!):
|
|
# shellexpand = "3.1" ✅
|
|
|
|
[features]
|
|
default = []
|
|
sqlite-migration = ["rusqlite"]
|
|
```
|
|
|
|
---
|
|
|
|
## CONCLUSION
|
|
|
|
This implementation plan provides a comprehensive roadmap for transforming the ruvector hooks system from a repository-specific solution into a **generic, portable, CLI-integrated intelligence layer** that can benefit any project using Claude Code.
|
|
|
|
**Key Achievements (MVP - 3-4 weeks)**:
|
|
- ✅ Zero hardcoded paths
|
|
- ✅ Works in any project with `npx ruvector hooks init`
|
|
- ✅ Migrates existing JSON learning data automatically
|
|
- ✅ Full CLI management of hooks system
|
|
- ✅ Backwards compatible with existing setups
|
|
- ✅ Cross-platform (Linux, macOS, Windows)
|
|
- ✅ Atomic migration with rollback protection
|
|
- ✅ Security: Command injection prevention
|
|
|
|
**Deferred to v1.1 (Additional 2-3 weeks)**:
|
|
- ⏭️ SQLite migration (complex, needs format detection)
|
|
- ⏭️ Global cross-project learning patterns
|
|
- ⏭️ Export/import team sharing
|
|
|
|
**Estimated Effort**:
|
|
- **MVP**: 3-4 weeks (15-19 days)
|
|
- **Full v1.1**: 5-7 weeks (27-38 days)
|
|
|
|
**Risk Level**: Low-Medium (major risks mitigated in sections 11.1-11.3)
|
|
**Expected Impact**: High (enables widespread adoption of intelligent hooks)
|
|
|
|
**Next Step**: Approve this plan and proceed to Milestone 1 (Specification & Architecture Design).
|
|
|
|
---
|
|
|
|
*Document Version*: 2.0 (Post-Review)
|
|
*Last Updated*: 2025-12-25
|
|
*Status*: Reviewed - Ready for Implementation
|
|
*Reviewer Notes*: Optimized timeline by 50%, addressed Windows compatibility, added security fixes
|