claude-flow-novice 2.18.16 → 2.18.18

package/.claude/skills/cfn-local-ruvector-accelerator/SKILL.md

@@ -1,8 +1,114 @@
-# 1. Initialize local RuVector
-./target/release/local-ruvector init
+# RuVector Local Semantic Code Search
 
-# 2. Index your codebase
-./target/release/local-ruvector index --path /path/to/project --types rs
+## WHEN TO USE THIS SKILL
 
-# 3. Query patterns instantly
-./target/release/local-ruvector query --pattern "authentication rust" --limit 5
+**USE RuVector V2 SQL for ALL indexed projects (400x FASTER than grep):**
+```bash
+# Exact name lookup - 0.002s vs grep's 0.8s
+sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT file_path, line_number FROM entities WHERE name = 'MyFunction';"
+
+# Fuzzy search - 0.004s
+sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT file_path, line_number FROM entities WHERE name LIKE '%Store%' LIMIT 10;"
+```
+
+**USE grep/rg ONLY when:**
+- Project is NOT indexed yet
+- Searching for strings that aren't code entities (error messages, comments, config values)
+- Quick one-off search in small directory
+
+**USE RuVector semantic search when:**
+- "Where is authentication implemented?" (conceptual search)
+- Finding similar patterns you can't name exactly
+- Discovering how a feature is built
+
+## Quick Commands
+
+### Semantic Search (V1 - Embeddings)
+```bash
+# Natural language search
+/codebase-search "authentication middleware pattern"
+/cfn-ruvector-search "error handling in API routes"
+
+# CLI direct (note: query text is positional, use --max-results not --limit)
+./.claude/skills/cfn-local-ruvector-accelerator/target/release/local-ruvector query "user login flow" --max-results 5
+```
+
+### Structural Search (V2 - SQL on AST)
+```bash
+# Find all callers of a function
+sqlite3 ~/.local/share/ruvector/index_v2.db \
+  "SELECT * FROM refs WHERE target_name = 'MyFunction';"
+
+# Find all functions in a file
+sqlite3 ~/.local/share/ruvector/index_v2.db \
+  "SELECT name, line_number FROM entities WHERE file_path LIKE '%myfile.rs' AND kind = 'function';"
+
+# Find entities by project (multi-project isolation)
+sqlite3 ~/.local/share/ruvector/index_v2.db \
+  "SELECT COUNT(*) FROM entities WHERE project_root = '/path/to/project';"
+```
+
+## Prerequisites
+
+**OPENAI_API_KEY is REQUIRED for indexing.** Indexing will fail without a valid key.
+
+```bash
+# Option 1: Export before running
+export OPENAI_API_KEY="sk-..."
+
+# Option 2: Add to shell profile (~/.bashrc or ~/.zshrc)
+echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
+source ~/.bashrc
+
+# Option 3: Inline with command
+OPENAI_API_KEY="sk-..." ./local-ruvector index --path /project
+```
+
+**Verify key is set:**
+```bash
+echo $OPENAI_API_KEY  # Should show your key (not empty)
+```
+
+## Index Management
+
+```bash
+# Index a project (first time or full rebuild)
+./target/release/local-ruvector index --path /path/to/project --types rs,ts,py
+
+# Incremental update (after code changes)
+/codebase-reindex
+
+# Check index stats
+sqlite3 ~/.local/share/ruvector/index_v2.db "SELECT project_root, COUNT(*) FROM entities GROUP BY project_root;"
+```
+
+## Key Features
+
+- **Multi-project isolation**: Index multiple projects in single database without data collision
+- **Non-destructive**: Indexing one project never deletes data from other projects
+- **Centralized storage**: `~/.local/share/ruvector/index_v2.db`
+- **Dual search**: V1 semantic (embeddings) + V2 structural (SQL on AST)
+- **Fast**: Rust binary with SQLite backend
+
+## Database Location
+```
+~/.local/share/ruvector/index_v2.db
+```
+
+## For Agents
+
+Before implementing changes, ALWAYS query RuVector first:
+```bash
+# Find similar patterns (slash command uses --top, CLI uses --max-results)
+/codebase-search "relevant search terms" --top 5
+# Or via CLI:
+./local-ruvector query "relevant search terms" --max-results 5
+
+# Query past errors
+./.claude/skills/cfn-ruvector-codebase-index/query-error-patterns.sh --task-description "description"
+
+# Query learnings
+./.claude/skills/cfn-ruvector-codebase-index/query-learnings.sh --task-description "description" --category PATTERN
+```
+
+This prevents duplicated work and leverages existing solutions.

package/.claude/skills/cfn-local-ruvector-accelerator/src/cli/index.rs

@@ -46,7 +46,7 @@ use anyhow::{Result, Context, anyhow};
 use std::fs;
 use std::path::{Path, PathBuf};
 use walkdir::{WalkDir, DirEntry};
-use tracing::{info, debug, warn};
+use tracing::{info, debug, warn, error};
 use regex::Regex;
 use std::sync::Arc;
 use std::sync::RwLock;
@@ -286,6 +286,15 @@ impl IndexCommand {
     }
 
     pub fn execute(&mut self) -> Result<IndexStats> {
+        // Fail early if OPENAI_API_KEY is not set
+        if std::env::var("OPENAI_API_KEY").is_err() {
+            error!("OPENAI_API_KEY environment variable is required for indexing");
+            return Err(anyhow!(
+                "OPENAI_API_KEY not found. Set it with: export OPENAI_API_KEY=\"sk-...\"\n\
+                 Indexing requires a valid OpenAI API key for generating embeddings."
+            ));
+        }
+
         info!("Starting index process");
         info!("File types: {:?}", self.file_types);
         if let Some(ref patterns) = self.patterns {
@@ -432,14 +441,21 @@ impl IndexCommand {
     ) -> Result<()> {
         let file_hash = self.calculate_file_hash(file_path)?;
 
+        // Check if file is already indexed with same hash (incremental indexing)
         if !self.force && self.is_file_indexed(file_path, &file_hash)? {
-            debug!("Skipping already indexed file: {}", file_path.display());
+            debug!("Skipping already indexed file (unchanged): {}", file_path.display());
             return Ok(());
         }
 
-        // Clean up old entries before reindexing to prevent duplicate entities
+        // Non-destructive update: Only delete entities for THIS specific file
+        // The delete_file_entities already scopes to project_root for multi-project safety
         let file_path_str = file_path.to_string_lossy();
-        self.store_v2.delete_file_entities(&file_path_str, &self.project_dir)?;
+
+        // Only clean up if the file was previously indexed (avoid unnecessary DB operations)
+        if self.is_file_in_index(file_path)? {
+            debug!("Updating existing file entries: {}", file_path.display());
+            self.store_v2.delete_file_entities(&file_path_str, &self.project_dir)?;
+        }
 
         let content = fs::read_to_string(file_path)
             .with_context(|| format!("Failed to read file: {}", file_path.display()))?;
@@ -470,7 +486,7 @@ impl IndexCommand {
             s.embeddings_generated += embeddings.len();
         }
 
-        self.mark_file_indexed(file_path, &file_hash)?;
+        self.mark_file_indexed(file_path, &file_hash, extraction_result.entities.len())?;
 
         Ok(())
     }
@@ -539,6 +555,7 @@ impl IndexCommand {
                 doc_comment: None,
                 attributes: None,
                 metadata: Some(serde_json::to_string(&entity.metadata)?),
+                project_root: project_root_str.to_string(),
                 created_at: chrono::Utc::now(),
                 updated_at: chrono::Utc::now(),
             };
@@ -654,15 +671,33 @@ impl IndexCommand {
         Ok(count > 0)
     }
 
-    fn mark_file_indexed(&self, file_path: &Path, file_hash: &str) -> Result<()> {
+    /// Check if file exists in the index (regardless of hash)
+    fn is_file_in_index(&self, file_path: &Path) -> Result<bool> {
+        let query = "SELECT COUNT(*) FROM file_hashes WHERE file_path = ?";
+        let mut stmt = self.store_v2.conn.prepare(query)?;
+        let count: i64 = stmt.query_row(
+            params![file_path.to_string_lossy()],
+            |row| row.get(0)
+        )?;
+        Ok(count > 0)
+    }
+
+    fn mark_file_indexed(&self, file_path: &Path, file_hash: &str, patterns_count: usize) -> Result<()> {
+        let timestamp = chrono::Utc::now().timestamp();
+        let file_path_str = file_path.to_string_lossy().to_string();
+
+        // Update file_hashes table (for incremental indexing)
         self.store_v2.conn.execute(
             "INSERT OR REPLACE INTO file_hashes (file_path, file_hash, indexed_at) VALUES (?1, ?2, ?3)",
-            params![
-                file_path.to_string_lossy(),
-                file_hash,
-                chrono::Utc::now().timestamp()
-            ]
+            params![&file_path_str, file_hash, timestamp]
         )?;
+
+        // Also update the files table (for legacy compatibility and stats)
+        self.store_v2.conn.execute(
+            "INSERT OR REPLACE INTO files (path, hash, last_indexed, patterns_count) VALUES (?1, ?2, ?3, ?4)",
+            params![&file_path_str, file_hash, timestamp, patterns_count as i64]
+        )?;
+
         Ok(())
     }
 

package/.claude/skills/cfn-local-ruvector-accelerator/src/cli/index_ast.rs

@@ -99,6 +99,15 @@ impl AstIndexCommand {
     }
 
     pub fn execute(&mut self) -> Result<IndexStats> {
+        // Fail early if OPENAI_API_KEY is not set
+        if std::env::var("OPENAI_API_KEY").is_err() {
+            error!("OPENAI_API_KEY environment variable is required for indexing");
+            return Err(anyhow!(
+                "OPENAI_API_KEY not found. Set it with: export OPENAI_API_KEY=\"sk-...\"\n\
+                 Indexing requires a valid OpenAI API key for generating embeddings."
+            ));
+        }
+
         let start_time = std::time::Instant::now();
 
         info!("Starting AST-based index process");
@@ -299,6 +308,7 @@ impl AstIndexCommand {
             let mut entity_map = HashMap::new();
             let mut type_usages = Vec::new();
 
+            let project_root_str = self.project_dir.to_string_lossy().to_string();
             for (idx, entity) in extraction_result.entities.iter().enumerate() {
                 let store_entity = StoreEntity {
                     id: 0,
@@ -313,6 +323,7 @@ impl AstIndexCommand {
                     doc_comment: None, // TODO: Extract doc comments
                     attributes: None, // TODO: Extract attributes
                     metadata: Some(serde_json::to_string(&entity.metadata)?),
+                    project_root: project_root_str.clone(),
                     created_at: chrono::Utc::now(),
                     updated_at: chrono::Utc::now(),
                 };
@@ -613,6 +624,7 @@ impl AstIndexCommand {
             Ok(entity.id)
         } else {
             // Create a placeholder entity for unknown references
+            let project_root_str = self.project_dir.to_string_lossy().to_string();
             let placeholder = StoreEntity {
                 id: 0,
                 kind: EntityKind::Function,
@@ -626,11 +638,11 @@ impl AstIndexCommand {
                 doc_comment: None,
                 attributes: None,
                 metadata: None,
+                project_root: project_root_str.clone(),
                 created_at: chrono::Utc::now(),
                 updated_at: chrono::Utc::now(),
             };
 
-            let project_root_str = self.project_dir.to_string_lossy();
             Ok(self.store_v2.insert_entity(&placeholder, &project_root_str)?)
         }
     }

package/.claude/skills/cfn-local-ruvector-accelerator/src/embeddings.rs

@@ -101,13 +101,10 @@ impl EmbeddingsManager {
         debug!("Generating embeddings for {} texts", texts.len());
 
         if self.config.api_key.is_none() {
-            warn!("OpenAI API key not found, falling back to dummy embeddings");
-            let mut embeddings = Vec::with_capacity(texts.len());
-            for text in texts {
-                embeddings.push(self.generate_dummy_embedding(text));
-            }
-            info!("Generated {} dummy embeddings", embeddings.len());
-            return Ok(embeddings);
+            error!("OPENAI_API_KEY environment variable not set");
+            return Err(anyhow!(
+                "OPENAI_API_KEY not found. Set it with: export OPENAI_API_KEY=\"sk-...\""
+            ));
         }
 
         let mut all_embeddings = Vec::with_capacity(texts.len());

package/.claude/skills/cfn-local-ruvector-accelerator/src/extractors/mod.rs

@@ -28,7 +28,7 @@ pub fn create_text_fallback_extractor() -> Result<text_fallback::TextFallbackExt
 }
 
 /// Common entity kinds across languages
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum EntityKind {
     // Functions
     Function,

package/.claude/skills/cfn-local-ruvector-accelerator/src/migration_v2.rs

@@ -359,21 +359,21 @@ mod tests {
 
         SchemaV2::initialize(&conn)?;
 
-        // Insert test entities with different path patterns
+        // Insert test entities with project_root set (schema now requires it)
         conn.execute(
-            "INSERT INTO entities (kind, name, file_path, line_number) VALUES (?, ?, ?, ?)",
-            params!["struct", "Test1", "/home/user/project/src/main.rs", 10]
+            "INSERT INTO entities (kind, name, file_path, line_number, project_root) VALUES (?, ?, ?, ?, ?)",
+            params!["struct", "Test1", "/home/user/project/src/main.rs", 10, "/home/user/project"]
         )?;
 
         conn.execute(
-            "INSERT INTO entities (kind, name, file_path, line_number) VALUES (?, ?, ?, ?)",
-            params!["function", "Test2", "/var/app/lib/utils.rs", 20]
+            "INSERT INTO entities (kind, name, file_path, line_number, project_root) VALUES (?, ?, ?, ?, ?)",
+            params!["function", "Test2", "/var/app/lib/utils.rs", 20, "/var/app"]
         )?;
 
-        // Run migration
+        // Run migration (will be skipped since schema already has project_root)
         MigrationV2::run_v2_migration(&mut conn)?;
 
-        // Verify project_root extraction
+        // Verify project_root values
         let project1: String = conn.query_row(
             "SELECT project_root FROM entities WHERE name = ?",
             params!["Test1"],

package/.claude/skills/cfn-local-ruvector-accelerator/src/query_api.rs

@@ -310,14 +310,15 @@ impl QueryApi {
                 row.get::<_, Option<String>>(9)?,  // doc_comment
                 row.get::<_, Option<String>>(10)?,  // attributes
                 row.get::<_, Option<String>>(11)?,  // metadata
-                row.get::<_, i64>(12)?,          // created_at
-                row.get::<_, i64>(13)?,          // updated_at
+                row.get::<_, String>(12)?,       // project_root
+                row.get::<_, i64>(13)?,          // created_at
+                row.get::<_, i64>(14)?,          // updated_at
             ))
         })?;
 
         for row in rows {
             let row = row?;
-            let (id, kind_str, name, signature, visibility_str, parent_id, file_path, line_number, column_number, doc_comment, attributes, metadata, created_at, updated_at) = row;
+            let (id, kind_str, name, signature, visibility_str, parent_id, file_path, line_number, column_number, doc_comment, attributes, metadata, project_root, created_at, updated_at) = row;
             // For now, just create a simple entity - the full parsing can be done later
             // This is just to get the IDs for reference finding
             matching_entities.push(crate::store_v2::Entity {
@@ -333,6 +334,7 @@ impl QueryApi {
                 doc_comment,
                 attributes,
                 metadata,
+                project_root,
                 created_at: chrono::DateTime::from_timestamp(created_at, 0).unwrap_or_default(),
                 updated_at: chrono::DateTime::from_timestamp(updated_at, 0).unwrap_or_default(),
             });
@@ -366,6 +368,7 @@ impl QueryApi {
                     doc_comment: None,
                     attributes: None,
                     metadata: None,
+                    project_root: "".to_string(),
                     created_at: chrono::DateTime::from_timestamp(0, 0).unwrap_or_default(),
                     updated_at: chrono::DateTime::from_timestamp(0, 0).unwrap_or_default(),
                 };

package/.claude/skills/cfn-local-ruvector-accelerator/src/schema_v2.rs

@@ -226,9 +226,10 @@ impl SchemaV2 {
                 doc_comment TEXT,
                 attributes TEXT,
                 metadata TEXT,
+                project_root TEXT NOT NULL DEFAULT '',
                 created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
                 updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
-                
+
                 FOREIGN KEY (parent_id) REFERENCES entities(id) ON DELETE RESTRICT
             );
             
@@ -282,6 +283,14 @@ impl SchemaV2 {
 
                 FOREIGN KEY (entity_id) REFERENCES entities(id) ON DELETE RESTRICT
             );
+
+            -- Create files table for tracking indexed files (stats and legacy compatibility)
+            CREATE TABLE IF NOT EXISTS files (
+                path TEXT PRIMARY KEY,
+                hash TEXT NOT NULL,
+                last_indexed INTEGER NOT NULL,
+                patterns_count INTEGER NOT NULL DEFAULT 0
+            );
             "#
         )?;
 
@@ -311,6 +320,8 @@ impl SchemaV2 {
             CREATE INDEX IF NOT EXISTS idx_entities_kind_name ON entities(kind, name);
             CREATE INDEX IF NOT EXISTS idx_entities_file_kind ON entities(file_path, kind);
             CREATE INDEX IF NOT EXISTS idx_entities_parent_kind ON entities(parent_id, kind);
+            CREATE INDEX IF NOT EXISTS idx_entities_project_root ON entities(project_root);
+            CREATE INDEX IF NOT EXISTS idx_entities_project_file ON entities(project_root, file_path);
             
             -- Reference indexes
             CREATE INDEX IF NOT EXISTS idx_refs_source ON refs(source_entity_id);
@@ -338,6 +349,10 @@ impl SchemaV2 {
             
             -- Entity-module relationship index (via file path)
             CREATE INDEX IF NOT EXISTS idx_entities_module_lookup ON entities(file_path);
+
+            -- Files table indexes
+            CREATE INDEX IF NOT EXISTS idx_files_hash ON files(hash);
+            CREATE INDEX IF NOT EXISTS idx_files_last_indexed ON files(last_indexed);
             "#
         )?;
 

package/.claude/skills/cfn-local-ruvector-accelerator/src/store_v2.rs

@@ -23,6 +23,7 @@ pub struct Entity {
     pub doc_comment: Option<String>,
     pub attributes: Option<String>,
     pub metadata: Option<String>,
+    pub project_root: String,
     pub created_at: DateTime<Utc>,
     pub updated_at: DateTime<Utc>,
 }
@@ -558,8 +559,9 @@ impl StoreV2 {
 
     // Helper methods to convert rows to structs
     pub(crate) fn row_to_entity(&self, row: &Row) -> rusqlite::Result<Entity> {
-        let created_timestamp: i64 = row.get(12)?;
-        let updated_timestamp: i64 = row.get(13)?;
+        let project_root: String = row.get(12)?;
+        let created_timestamp: i64 = row.get(13)?;
+        let updated_timestamp: i64 = row.get(14)?;
 
         let kind_str = row.get::<_, String>(1)?;
         let kind = EntityKind::from_str(&kind_str)
@@ -582,6 +584,7 @@ impl StoreV2 {
             doc_comment: row.get(9)?,
             attributes: row.get(10)?,
             metadata: row.get(11)?,
+            project_root,
             created_at: DateTime::from_timestamp(created_timestamp, 0).unwrap_or_default(),
             updated_at: DateTime::from_timestamp(updated_timestamp, 0).unwrap_or_default(),
         })
@@ -664,11 +667,12 @@ mod tests {
             doc_comment: Some("Test function".to_string()),
             attributes: None,
             metadata: None,
+            project_root: "/test/project".to_string(),
             created_at: Utc::now(),
             updated_at: Utc::now(),
         };
         
-        let entity_id = store.insert_entity(&entity)?;
+        let entity_id = store.insert_entity(&entity, "/test/project")?;
         assert!(entity_id > 0);
         
         // Retrieve entity

package/.claude/skills/cfn-local-ruvector-accelerator/src/store_v2_tx.rs

@@ -225,10 +225,11 @@ impl StoreV2WithTx {
         // Execute the callback
         f(&tx)?;
 
-        // Record file hash
+        // Record file hash with current timestamp
+        let current_time = chrono::Utc::now().timestamp();
         tx.execute(
-            "INSERT INTO file_hashes (file_path, file_hash) VALUES (?, ?)",
-            params![file_path, file_hash],
+            "INSERT INTO file_hashes (file_path, file_hash, indexed_at) VALUES (?, ?, ?)",
+            params![file_path, file_hash, current_time],
         )?;
 
         tx.commit()
@@ -308,6 +309,7 @@ mod tests {
             doc_comment: None,
             attributes: None,
             metadata: None,
+            project_root: "/test/project".to_string(),
             created_at: Utc::now(),
             updated_at: Utc::now(),
         }).collect();

package/.claude/skills/cfn-local-ruvector-accelerator/src/transaction_tests.rs

@@ -44,6 +44,7 @@ fn test_atomic_file_indexing_with_rollback() -> Result<()> {
         doc_comment: None,
         attributes: None,
         metadata: None,
+        project_root: "/test/project".to_string(),
         created_at: chrono::Utc::now(),
         updated_at: chrono::Utc::now(),
     };
@@ -67,6 +68,7 @@ fn test_atomic_file_indexing_with_rollback() -> Result<()> {
             doc_comment: None,
             attributes: None,
             metadata: None,
+            project_root: "/test/project".to_string(),
             created_at: chrono::Utc::now(),
             updated_at: chrono::Utc::now(),
         };
@@ -84,6 +86,7 @@ fn test_atomic_file_indexing_with_rollback() -> Result<()> {
             doc_comment: None,
             attributes: None,
             metadata: None,
+            project_root: "/test/project".to_string(),
             created_at: chrono::Utc::now(),
             updated_at: chrono::Utc::now(),
         };
@@ -92,8 +95,8 @@ fn test_atomic_file_indexing_with_rollback() -> Result<()> {
             r#"
             INSERT INTO entities (
                 kind, name, signature, visibility, parent_id, file_path,
-                line_number, column_number, doc_comment, attributes, metadata
-            ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)
+                line_number, column_number, doc_comment, attributes, metadata, project_root
+            ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
             "#
         )?;
 
@@ -109,6 +112,7 @@ fn test_atomic_file_indexing_with_rollback() -> Result<()> {
             entity1.doc_comment,
             entity1.attributes,
             entity1.metadata,
+            entity1.project_root,
         ])?;
 
         stmt.execute(params![
@@ -123,6 +127,7 @@ fn test_atomic_file_indexing_with_rollback() -> Result<()> {
             entity2.doc_comment,
             entity2.attributes,
             entity2.metadata,
+            entity2.project_root,
         ])?;
 
         Ok(())
@@ -220,6 +225,7 @@ fn test_batch_insert_rollback() -> Result<()> {
             doc_comment: None,
             attributes: None,
             metadata: None,
+            project_root: "/test/project".to_string(),
             created_at: chrono::Utc::now(),
             updated_at: chrono::Utc::now(),
         });

package/CLAUDE.md

@@ -24,7 +24,8 @@ Purpose: concise reference for CFN agents. Focus on persona, mandatory rules, ed
 - Do not run tests inside agents; run once via coordinator/main chat, agents read results.
 - Never save to project root; use appropriate subdirectories.
 - Never hardcode secrets; always redact as `[REDACTED]`.
-- Prefer `rg`/`grep` over `find`; when monitoring, sleep-check-sleep loops.
+- Use RuVector SQL for indexed projects (400x faster than grep); use grep only for non-indexed projects or non-code strings.
+- When monitoring, sleep-check-sleep loops.
 - All agent communication must use coordination protocols; no ad-hoc file coordination.
 
 ## 3) Cerebras MCP & Context Discovery Protocols

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow-novice",
-  "version": "2.18.16",
+  "version": "2.18.18",
   "description": "Claude Flow Novice - Advanced orchestration platform for multi-agent AI workflows with CFN Loop architecture\n\nIncludes Local RuVector Accelerator and all CFN skills for complete functionality.",
   "main": "index.js",
   "type": "module",