@comfanion/usethis_search 0.1.4 → 0.1.5

package/README.md

@@ -1,17 +1,32 @@
-# @comfanion/usethis_search
+# 🔍 @comfanion/usethis_search
 
-OpenCode plugin that provides semantic search and index management tools.
+**Semantic code search with automatic indexing**
 
-## Tools
+Forget about `grep` and `find` — search code by meaning, not by text!
 
-- `search` (semantic search)
-- `codeindex` (index status, list, reindex)
+---
 
-## Storage
+## ✨ What is this?
 
-- Vectors are stored in `.opencode/vectors/<index>/` in the project.
+An OpenCode plugin that adds **smart search** to your project:
 
-## Install (OpenCode)
+- 🧠 **Semantic search** — finds code by meaning, even when words don't match
+- ⚡ **Automatic indexing** — files are indexed on change (zero effort)
+- 📦 **Local vectorization** — works offline, no API keys needed
+- 🎯 **Three indexes** — separate for code, docs, and configs
+- 🌍 **Multilingual** — supports Ukrainian, Russian, and English
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install @comfanion/usethis_search
+```
+
+### Configuration
 
 Add to `opencode.json`:
 
@@ -20,3 +35,313 @@ Add to `opencode.json`:
   "plugin": ["@comfanion/usethis_search"]
 }
 ```
+
+### First Run
+
+On OpenCode startup, the plugin automatically:
+1. Creates indexes for code and documentation
+2. Indexes all project files
+3. Shows progress via toast notifications
+
+**First indexing may take time:**
+- < 20 files — Quick coffee? ☕
+- < 100 files — ~1min. Stretch break? 🧘
+- < 500 files — ~3min. Make coffee ☕ and relax 🛋️
+- 500+ files — ~10min. Go touch grass 🌿 or take a nap 😴
+
+---
+
+## 🎯 How to Use
+
+### Search
+
+```javascript
+// Search for authentication logic
+search({ 
+  query: "authentication logic", 
+  index: "code" 
+})
+
+// Search for deployment instructions
+search({ 
+  query: "how to deploy", 
+  index: "docs" 
+})
+
+// Search for API keys in configs
+search({ 
+  query: "API keys", 
+  index: "config" 
+})
+
+// Search across all indexes
+search({ 
+  query: "database connection", 
+  searchAll: true 
+})
+```
+
+### Index Management
+
+```javascript
+// List all indexes
+codeindex({ action: "list" })
+
+// Check specific index status
+codeindex({ action: "status", index: "code" })
+
+// Reindex
+codeindex({ action: "reindex", index: "code" })
+
+// Index specific directory
+codeindex({ 
+  action: "reindex", 
+  index: "docs", 
+  dir: "docs/" 
+})
+```
+
+---
+
+## 🧠 How It Works
+
+### Semantic Search
+
+Instead of searching for exact text matches, the plugin:
+1. Converts code into **vectors** (numerical representations of meaning)
+2. Compares vectors of your query with vectors of code
+3. Finds the most **semantically similar** fragments
+
+**Example:**
+```javascript
+// You search for: "user authentication"
+// It will find code with:
+// - "login handler"
+// - "verify credentials"
+// - "session management"
+// Even if words "user" and "authentication" are absent!
+```
+
+### Automatic Indexing
+
+The plugin tracks file changes and automatically updates indexes:
+
+1. **On OpenCode startup** — checks all indexes, updates stale ones
+2. **On file edit** — queues file for reindexing
+3. **After 1 second** (debounce) — indexes changed files
+
+**Configuration in `.opencode/vectorizer.yaml`:**
+
+```yaml
+vectorizer:
+  enabled: true          # Enable plugin
+  auto_index: true       # Automatic indexing
+  debounce_ms: 1000      # Delay before indexing (ms)
+  
+  indexes:
+    code:
+      enabled: true
+      extensions: [.js, .ts, .jsx, .tsx, .py, .go, ...]
+    docs:
+      enabled: true
+      extensions: [.md, .mdx, .txt, .rst, .adoc]
+    config:
+      enabled: false     # Disabled by default
+      extensions: [.yaml, .yml, .json, .toml, ...]
+  
+  exclude:
+    - node_modules
+    - vendor
+    - dist
+    - build
+    - __pycache__
+```
+
+---
+
+## 📦 Data Structure
+
+Indexes are stored locally in your project:
+
+```
+.opencode/
+  vectors/
+    code/              # Code index
+      data/            # LanceDB tables
+      hashes.json      # File hashes (for change detection)
+    docs/              # Documentation index
+      data/
+      hashes.json
+  vectorizer.yaml      # Configuration
+  indexer.log          # Indexing log (if DEBUG=*)
+```
+
+---
+
+## 🎨 Usage Examples
+
+### 1. Find all API endpoints
+
+```javascript
+search({ 
+  query: "REST API endpoints routes", 
+  index: "code" 
+})
+```
+
+### 2. Find testing documentation
+
+```javascript
+search({ 
+  query: "how to write tests", 
+  index: "docs" 
+})
+```
+
+### 3. Find database configuration
+
+```javascript
+search({ 
+  query: "database connection settings", 
+  index: "config" 
+})
+```
+
+### 4. Find error handling
+
+```javascript
+search({ 
+  query: "error handling try catch", 
+  index: "code",
+  limit: 20  // More results
+})
+```
+
+### 5. Search across entire project
+
+```javascript
+search({ 
+  query: "authentication", 
+  searchAll: true  // Searches in code, docs, config
+})
+```
+
+---
+
+## 🛠️ Configuration
+
+### Disable automatic indexing
+
+```yaml
+# .opencode/vectorizer.yaml
+vectorizer:
+  enabled: true
+  auto_index: false  # Manual indexing only
+```
+
+### Add custom index
+
+```yaml
+vectorizer:
+  indexes:
+    tests:
+      enabled: true
+      extensions: [.test.js, .spec.ts]
+```
+
+### Change indexing delay
+
+```yaml
+vectorizer:
+  debounce_ms: 3000  # 3 seconds instead of 1
+```
+
+### Temporarily disable plugin
+
+```bash
+export OPENCODE_SKIP_AUTO_INDEX=1
+```
+
+---
+
+## 🐛 Debugging
+
+### Enable logs
+
+```bash
+export DEBUG=file-indexer
+# or
+export DEBUG=*
+```
+
+Logs will be in `.opencode/indexer.log`
+
+### Reindex everything
+
+```javascript
+codeindex({ action: "reindex", index: "code" })
+codeindex({ action: "reindex", index: "docs" })
+```
+
+### Check index status
+
+```javascript
+codeindex({ action: "list" })
+```
+
+---
+
+## 🌟 Advantages
+
+### Compared to `grep`/`find`
+
+| Feature | grep/find | usethis_search |
+|---------|-----------|----------------|
+| Text search | ✅ | ✅ |
+| Semantic search | ❌ | ✅ |
+| Finds synonyms | ❌ | ✅ |
+| Understands context | ❌ | ✅ |
+| Works offline | ✅ | ✅ |
+| Auto-updates | ❌ | ✅ |
+
+### Compared to online search (GitHub Copilot, ChatGPT)
+
+| Feature | Online | usethis_search |
+|---------|--------|----------------|
+| Works offline | ❌ | ✅ |
+| Privacy | ❌ | ✅ |
+| Free | ❌ | ✅ |
+| Speed | 🐌 | ⚡ |
+| Knows your code | ❌ | ✅ |
+
+---
+
+## 📊 Technical Details
+
+- **Vectorization:** [@xenova/transformers](https://github.com/xenova/transformers.js) (ONNX Runtime)
+- **Vector DB:** [LanceDB](https://lancedb.com/) (local, serverless)
+- **Model:** `Xenova/all-MiniLM-L6-v2` (multilingual, 384 dimensions)
+- **Model size:** ~23 MB (downloaded once)
+- **Speed:** ~0.5 sec/file (after model loading)
+
+---
+
+## 🤝 Contributing
+
+Found a bug? Have an idea? Open an issue or PR!
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 🎉 Authors
+
+Made with ❤️ by the **Comfanion** team
+
+---
+
+**Search smart, not hard!** 🚀

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/usethis_search",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "OpenCode plugin: semantic search + code index management",
   "type": "module",
   "main": "./index.ts",