tunacode-cli 0.0.76.3__tar.gz → 0.0.76.4__tar.gz

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/.claude/patterns/coding_patterns.md

@@ -9,4 +9,4 @@
 7. **Move Declaration & Initialization Together** - Keep a variable's birth and first value adjacent for comprehension & dependency safety
 8. **Explaining Variable** - Extract a sub-expression into a well-named variable to record intent
 9. **Explaining Constant** - Replace magic literals with symbolic constants that broadcast meaning
-10. **Explicit Parameters** - Split a routine so all inputs are passed openly, banishing hidden state or maps
+10. **Explicit Parameters** - Split a routine so all inputs are passed openly, banishing hidden state or maps

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/.gitignore

@@ -60,7 +60,7 @@ scratchpad_*.md
 
 # Memory bank and agent tools
 # memory-bank/  # Important project documentation - should be tracked
-llm-agent-tools/
+# llm-agent-tools/  # Removed - now tracking this directory
 .researcher/
 
 # Logs

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/AGENTS.md

@@ -21,6 +21,16 @@ You MUST comply with the rules below. You will be penalized if you deviate. Answ
 * Enforce `ruff check --fix .` before PRs.
 * Use explicit typing. `cast(...)` and `assert ...` are OK.
 * `# type: ignore` only with strong justification.
+* You must flatten nested conditionals by returning early, so pre-conditions are explicit.
+* If it is never executed, remove it. You MUST make sure what we remove has been committed before in case we need to rollback.
+* Normalize symmetries: you must make identical things look identical and different things look different for faster pattern-spotting.
+* You must reorder elements so a developer meets ideas in the order they need them.
+* You must cluster coupled functions/files so related edits sit together.
+* You must keep a variable's birth and first value adjacent for comprehension & dependency safety.
+* Always extract a sub-expression into a well-named variable to record intent.
+* Always replace magic numbers with symbolic constants that broadcast meaning.
+* Never use magic literals; symbolic constants are preferred.
+* ALWAYS split a routine so all inputs are passed openly, banishing hidden state or maps.
 
 ### Error Handling
 
@@ -86,6 +96,8 @@ Docs → model-friendly explanations of purposes & relationships.
 Delta Summaries → record API/behavior shifts with reasoning.
 
 Memory Anchors → embed UUID-tagged semantic anchors in code.
+you MUST use this tool to drop anchors: python3 knowledge_base/tools/anchor_drop.py <file> <line> <description> to mark important locations
+   with UUID-based comments stored in .claude/memory_anchors/anchors.json
 ---
 
 ### Example##\#
@@ -108,9 +120,23 @@ in llm-agent-tools/rag_modules/ a tool exist to search the .claude/ directory vi
 ./rag-cli.sh search "query"     # Search across .claude/
 ./rag-cli.sh stats              # Show index stats
 
-# Filtered / formatted search
-./rag-cli.sh search "query" --category dev --format json --limit 5
+### Filtered / formatted search
 
+./rag-cli.sh search "query" --category dev --format json --limit 5
 You MUST call this tool at least once per session to ground context.
 Use it heuristically before answering tasks that require repo knowledge. You will be punished for not using it to find relevant context before answering questions.
+
+**Problem**: Search for "fuzzy" in the .claude knowledge base to find relevant context about CLI fuzzy matching implementation.
+
+```bash
+# First index the .claude directory
+./rag-cli.sh index --dir .claude
+
+# Search for specific content
+./rag-cli.sh search "fuzzy" --format text
+
+# Results found:
+# 1. behavior_changes.json - CLI fuzzy matching enhancement details
+# 2. file_classifications.json - Test file classification for fuzzy matching
+```
 ---

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/CLAUDE.md

@@ -91,7 +91,9 @@ Rules:
 * Docs → model-friendly explanations of purposes & relationships.
 * Delta Summaries → record API/behavior shifts with reasoning.
 * Memory Anchors → embed UUID-tagged semantic anchors in code.
-* Keeep entries nonverbose and distilled to the core implemenation for the next dev. You will be punished for not following these instructions. 
+you MUST use this tool to drop anchors: python3 knowledge_base/tools/anchor_drop.py <file> <line> <description> to mark important locations
+   with UUID-based comments stored in .claude/memory_anchors/anchors.json
+* Keeep entries nonverbose and distilled to the core implemenation for the next dev. You will be punished for not following these instructions.
 
 
 ---
@@ -121,9 +123,22 @@ In llm-agent-tools/rag_modules/ a tool exists to search the .claude/ directory v
 
 ./rag-cli.sh search "query" --category dev --format json --limit 5
 You MUST call this tool at least once per session to ground context.
-If llm-agent-tool dir doesnt exist skip this step
 Use it heuristically before answering tasks that require repo knowledge. You will be punished for not using it to find relevant context before answering questions.
 
+**Problem**: Search for "fuzzy" in the .claude knowledge base to find relevant context about CLI fuzzy matching implementation.
+
+```bash
+# First index the .claude directory
+./rag-cli.sh index --dir .claude
+
+# Search for specific content
+./rag-cli.sh search "fuzzy" --format text
+
+# Results found:
+# 1. behavior_changes.json - CLI fuzzy matching enhancement details
+# 2. file_classifications.json - Test file classification for fuzzy matching
+```
+
 ---
 
 ## Available Sub-Agents

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunacode-cli
-Version: 0.0.76.3
+Version: 0.0.76.4
 Summary: Your agentic CLI developer.
 Project-URL: Homepage, https://tunacode.xyz/
 Project-URL: Repository, https://github.com/alchemiststudiosDOTai/tunacode

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/TODO.md

@@ -45,4 +45,4 @@
 
 ---
 
-**Code Changes:** ~30 lines total (new utility + modified completer logic)
+**Code Changes:** ~30 lines total (new utility + modified completer logic)

{tunacode_cli-0.0.76.3 → tunacode_cli-0.0.76.4}/documentation/changelog/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.76.4] - 2025-09-25
+
+### Added
+- **Fuzzy Matching Integration** - Merged new-fuzzy branch with enhanced CLI and file reference completion
+- **Memory Anchor Tool** - Added UUID-based semantic anchoring system for code documentation
+- **Knowledge Base Structure** - Comprehensive RAG tooling for .claude/ directory search and indexing
+
+### Changed
+- **File Reference System** - Enhanced @mentions with fuzzy-first matching and smart directory browsing
+- **CLI Command Resolution** - Added fuzzy fallback using difflib.get_close_matches for better UX
+- **Code Quality** - Updated coding patterns and best practices in CLAUDE.md
+
+### Fixed
+- **Documentation Consistency** - Resolved merge conflicts and updated project instructions
+- **Import Cleanup** - Removed unused imports and improved code organization
+
+## [Unreleased] - 2025-09-22
+
+### Added
+- **Enhanced File Reference Completion** - Fuzzy-first matching for @mentions with smart directory browsing
+- **Fuzzy CLI Command Matching** - CLI suggests closest commands when no exact/prefix match
+- **Models Registry Pydantic Conversion** - Complete conversion to Pydantic BaseModel with validation
+- **RAG Tooling** - SQLite FTS5 index for .claude/ knowledge base search and indexing
+- **Comprehensive Validation Tests** - Added golden baseline tests and validation edge cases
+
+### Changed
+- **File Reference Ordering** - New priority: exact files > fuzzy files > exact dirs > fuzzy dirs
+- **Bare Directory Browsing** - Type `@dir` (without trailing slash) to browse directory contents
+- **Code Style Guidelines** - Updated CLAUDE.md with improved coding patterns and best practices
+- **Models Registry Validation** - Added constraints for non-negative costs and positive limits
+
+### Fixed
+- **Unused Import Removal** - Removed unused Iterable import from fuzzy_utils.py
+- **Validation Edge Cases** - Enhanced registry validation for model loading scenarios
+
 ## [0.0.76.2] - 2025-09-19
 
 ### Added

tunacode_cli-0.0.76.4/llm-agent-tools/.gitignore

@@ -0,0 +1,15 @@
+# Ignore personal knowledge base directory
+.claude/
+
+# Environment variables
+.env
+
+# Scalene profiles
+profile.html
+profile.json
+profiles/
+*.scalene
+
+# Test database
+test.db
+*.db

tunacode_cli-0.0.76.4/llm-agent-tools/README.md

@@ -0,0 +1,155 @@
+# RAG Modules
+
+Retrieval-Augmented Generation modules for indexing and searching documentation using SQLite FTS5.
+
+## Quick Start (CLI)
+
+The included `rag-cli.sh` provides a simple interface for using the RAG tools:
+
+```bash
+# Index the default memory-bank directory
+./rag-cli.sh index
+
+# Search indexed content
+./rag-cli.sh search "your query here"
+
+# View index statistics
+./rag-cli.sh stats
+
+# Index a custom directory
+./rag-cli.sh index --dir /path/to/your/docs
+```
+
+## Directory Structure
+
+```
+rag_modules/
+├── rag-cli.sh          # Main CLI script
+├── rag_knowledge.db    # SQLite database (created after first run)
+├── indexer.py          # Documentation indexer
+├── search.py           # Full-text search interface
+├── stats.py            # Index statistics and health monitoring
+├── README.md           # This file
+└── default_directory_behavior.md  # Details on directory detection
+```
+
+## Customizing Path Pointing
+
+The RAG system is flexible and can point to any directory you want to index:
+
+### Via CLI (Recommended)
+```bash
+# Index any directory
+./rag-cli.sh index --dir /path/to/your/project/docs
+
+# Index multiple directories
+./rag-cli.sh index --dir ./docs ./wiki ./notes
+
+# Use a custom database location
+./rag-cli.sh index --dir ./docs --db-path /custom/path/to/my.db
+```
+
+### Via Environment Variables
+```bash
+# Set custom database path
+export RAG_DB_PATH="/custom/location/knowledge.db"
+
+# Enable verbose output
+export RAG_VERBOSE=1
+
+# Then run commands normally
+./rag-cli.sh index
+```
+
+### Direct Module Usage
+```bash
+# Index specific directories with full control
+python3 indexer.py --directories ./src ./docs ./README.md --db-path ./my_docs.db
+
+# Search with specific parameters
+python3 search.py --db-path ./my_docs.db --query "API reference" --category src --format json
+```
+
+## Agent Usage Guide
+
+For AI agents and programmatic use:
+
+### 1. Index Documentation
+```bash
+# For agent knowledge bases
+./rag-cli.sh index --dir /path/to/agent/knowledge
+```
+
+### 2. Search (JSON output recommended)
+```bash
+# Get search results in JSON format for parsing
+./rag-cli.sh search "implementation details" --format json
+
+# Search within specific categories
+./rag-cli.sh search "API methods" --category api --format json
+```
+
+### 3. Check Index Health
+```bash
+# Get statistics in JSON format
+./rag-cli.sh stats --json
+```
+
+## CLI Reference
+
+### Index Command
+```bash
+./rag-cli.sh index [options]
+  --full           # Full rebuild of index
+  --dir DIR        # Directory to index (default: ../memory-bank)
+  --db PATH        # Custom database path
+```
+
+### Search Command
+```bash
+./rag-cli.sh search <query> [options]
+  --category CAT   # Search within specific category
+  --format FMT     # Output: json|text|markdown (default: json)
+  --limit N        # Maximum results (default: 10)
+  --db PATH        # Custom database path
+```
+
+### Stats Command
+```bash
+./rag-cli.sh stats [options]
+  --json           # Output in JSON format
+  --db PATH        # Custom database path
+```
+
+## Default Directory Behavior
+
+When no directories are specified, the system automatically searches for documentation:
+1. First looks in the current directory for `docs/` or `documentation/` folders
+2. If not found, checks the parent directory for the same folders
+
+## Supported File Types
+
+- Markdown files (.md, .markdown)
+- Text files (.txt)
+
+## Output Formats
+
+- **JSON**: Compact JSONL format for agent consumption
+- **Text**: Human-readable with highlighted search terms
+- **Markdown**: Formatted output with proper formatting
+
+## Examples
+
+```bash
+# Index project documentation
+./rag-cli.sh index --dir ./docs
+
+# Search for specific patterns
+./rag-cli.sh search "authentication flow" --category guide --format markdown
+
+# Check what's indexed
+./rag-cli.sh stats
+
+# Full reindex when files change significantly
+./rag-cli.sh index --full --dir ./docs
+```

tunacode_cli-0.0.76.4/llm-agent-tools/knowledge_base/README.md

@@ -0,0 +1,88 @@
+# Knowledge Base Tools
+
+A suite of command-line tools designed for code agents and human-in-the-loop workflows to Create, Read, Update, and Delete (CRUD) knowledge base anchors in code repositories.
+
+## Overview
+
+These tools help maintain persistent memory anchors within codebases, enabling:
+- Code agents to remember important context across sessions
+- Human developers to mark and annotate significant code locations
+- Collaborative annotation of code with contextual information
+- Persistent knowledge storage that survives code changes
+
+## Tools
+
+### anchor_drop.py
+
+The first tool in the suite. Drops memory anchors at specific locations in code files.
+
+**Features:**
+- Inserts `CLAUDE_ANCHOR[key=UUID]` comments in code
+- Supports multiple programming languages with appropriate comment syntax
+- Maintains anchor metadata in `.claude/memory_anchors/anchors.json`
+- Generates unique UUID keys for each anchor
+
+**Usage:**
+```bash
+python3 anchor_drop.py <file_path> <line_number> <description> [kind]
+```
+
+**Examples:**
+```bash
+# Drop an anchor at line 42 in main.py
+python3 anchor_drop.py main.py 42 "Critical authentication logic"
+
+# Drop an anchor with specific kind
+python3 anchor_drop.py utils.py 15 "Helper function" "function"
+```
+
+**Supported Languages:**
+- Python (.py) - `#` comments
+- JavaScript (.js) - `//` comments
+- TypeScript (.ts) - `//` comments
+- Go (.go) - `//` comments
+- C/C++ (.c, .cpp) - `//` comments
+- Java (.java) - `//` comments
+- Rust (.rs) - `//` comments
+- Zig (.zig) - `//` comments
+- SQL (.sql) - `--` comments
+- HTML (.html, .htm) - `<!-- -->` comments
+
+## Anchor Data Structure
+
+Anchors are stored in `.claude/memory_anchors/anchors.json` with the following structure:
+
+```json
+{
+  "version": 1,
+  "generated": "2025-09-23T11:35:02Z",
+  "anchors": [
+    {
+      "key": "affbd046",
+      "path": "test_file.py",
+      "line": 12,
+      "kind": "line",
+      "description": "Important calculation function",
+      "status": "active",
+      "created": "2025-09-23T11:35:00Z"
+    }
+  ]
+}
+```
+
+## Use Cases
+
+1. **Code Agent Memory**: Allow agents to remember important code locations and context
+2. **Code Reviews**: Mark sections needing attention or explanation
+3. **Documentation**: Embed documentation directly in code locations
+4. **Debugging**: Anchor problematic code sections with notes
+5. **Learning**: Annotate code examples with explanations
+
+## Future Tools
+
+Planned additions to the tool suite:
+- `anchor_list.py` - List all anchors in the repository
+- `anchor_update.py` - Update anchor descriptions and metadata
+- `anchor_delete.py` - Remove anchors from code and registry
+- `anchor_search.py` - Search anchors by description or metadata
+- `anchor_export.py` - Export anchors in various formats

tunacode_cli-0.0.76.4/llm-agent-tools/knowledge_base/tools/anchor_drop.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""
+Drop a memory anchor:
+- Inserts a CLAUDE_ANCHOR comment in the code with UUID key
+- Appends entry in .claude/memory_anchors/anchors.json
+"""
+
+import json
+import pathlib
+import time
+import uuid
+
+LANG_PREFIX = {
+    ".py": "#",
+    ".js": "//",
+    ".ts": "//",
+    ".go": "//",
+    ".c": "//",
+    ".cpp": "//",
+    ".java": "//",
+    ".rs": "//",
+    ".zig": "//",
+    ".sql": "--",
+    ".html": "<!--",
+    ".htm": "<!--",
+}
+LANG_SUFFIX = {".html": " -->", ".htm": " -->"}
+
+
+def drop_anchor(file_path, line_num, desc, kind="line"):
+    root = pathlib.Path(".claude/memory_anchors")
+    root.mkdir(parents=True, exist_ok=True)
+    anchors_file = root / "anchors.json"
+
+    # Load or init template
+    data = {
+        "version": 1,
+        "generated": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "anchors": [],
+    }
+    if anchors_file.exists():
+        with open(anchors_file, "r") as f:
+            try:
+                data = json.load(f)
+            except json.JSONDecodeError:
+                print("Invalid anchors.json; reinitializing.")
+
+    # Generate key
+    key = str(uuid.uuid4())[:8]
+
+    # New entry
+    entry = {
+        "key": key,
+        "path": file_path,
+        "line": line_num,
+        "kind": kind,
+        "description": desc,
+        "status": "active",
+        "created": time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    data["anchors"].append(entry)
+    data["generated"] = time.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    # Insert comment
+    p = pathlib.Path(file_path)
+    if not p.exists():
+        print(f"File {file_path} not found.")
+        return
+
+    with open(p, "r") as f:
+        text = f.readlines()
+
+    if line_num < 1 or line_num > len(text) + 1:
+        print(f"Invalid line {line_num} for file with {len(text)} lines.")
+        return
+
+    ext = p.suffix.lower()
+    pre = LANG_PREFIX.get(ext, "//")
+    post = LANG_SUFFIX.get(ext, "")
+    comment = f"{pre} CLAUDE_ANCHOR[key={key}] {desc}{post}\n"
+    text.insert(line_num - 1, comment)
+
+    with open(p, "w") as f:
+        f.writelines(text)
+
+    # Write JSON
+    with open(anchors_file, "w") as f:
+        json.dump(data, f, indent=2)
+
+    print(f"Anchor {key} dropped at {file_path}:{line_num}")
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 4:
+        print("Usage: python anchor_drop.py <file> <line> <desc> [kind]")
+        sys.exit(1)
+
+    file_path = sys.argv[1]
+    line_num = int(sys.argv[2])
+    desc = sys.argv[3]
+    kind = sys.argv[4] if len(sys.argv) > 4 else "line"
+    drop_anchor(file_path, line_num, desc, kind)

tunacode_cli-0.0.76.4/llm-agent-tools/rag_modules/README.md

@@ -0,0 +1,155 @@
+# RAG Modules
+
+Retrieval-Augmented Generation modules for indexing and searching documentation using SQLite FTS5.
+
+## Quick Start (CLI)
+
+The included `rag-cli.sh` provides a simple interface for using the RAG tools:
+
+```bash
+# Index the default memory-bank directory
+./rag-cli.sh index
+
+# Search indexed content
+./rag-cli.sh search "your query here"
+
+# View index statistics
+./rag-cli.sh stats
+
+# Index a custom directory
+./rag-cli.sh index --dir /path/to/your/docs
+```
+
+## Directory Structure
+
+```
+rag_modules/
+├── rag-cli.sh          # Main CLI script
+├── rag_knowledge.db    # SQLite database (created after first run)
+├── indexer.py          # Documentation indexer
+├── search.py           # Full-text search interface
+├── stats.py            # Index statistics and health monitoring
+├── README.md           # This file
+└── default_directory_behavior.md  # Details on directory detection
+```
+
+## Customizing Path Pointing
+
+The RAG system is flexible and can point to any directory you want to index:
+
+### Via CLI (Recommended)
+```bash
+# Index any directory
+./rag-cli.sh index --dir /path/to/your/project/docs
+
+# Index multiple directories
+./rag-cli.sh index --dir ./docs ./wiki ./notes
+
+# Use a custom database location
+./rag-cli.sh index --dir ./docs --db-path /custom/path/to/my.db
+```
+
+### Via Environment Variables
+```bash
+# Set custom database path
+export RAG_DB_PATH="/custom/location/knowledge.db"
+
+# Enable verbose output
+export RAG_VERBOSE=1
+
+# Then run commands normally
+./rag-cli.sh index
+```
+
+### Direct Module Usage
+```bash
+# Index specific directories with full control
+python3 indexer.py --directories ./src ./docs ./README.md --db-path ./my_docs.db
+
+# Search with specific parameters
+python3 search.py --db-path ./my_docs.db --query "API reference" --category src --format json
+```
+
+## Agent Usage Guide
+
+For AI agents and programmatic use:
+
+### 1. Index Documentation
+```bash
+# For agent knowledge bases
+./rag-cli.sh index --dir /path/to/agent/knowledge
+```
+
+### 2. Search (JSON output recommended)
+```bash
+# Get search results in JSON format for parsing
+./rag-cli.sh search "implementation details" --format json
+
+# Search within specific categories
+./rag-cli.sh search "API methods" --category api --format json
+```
+
+### 3. Check Index Health
+```bash
+# Get statistics in JSON format
+./rag-cli.sh stats --json
+```
+
+## CLI Reference
+
+### Index Command
+```bash
+./rag-cli.sh index [options]
+  --full           # Full rebuild of index
+  --dir DIR        # Directory to index (default: ../memory-bank)
+  --db PATH        # Custom database path
+```
+
+### Search Command
+```bash
+./rag-cli.sh search <query> [options]
+  --category CAT   # Search within specific category
+  --format FMT     # Output: json|text|markdown (default: json)
+  --limit N        # Maximum results (default: 10)
+  --db PATH        # Custom database path
+```
+
+### Stats Command
+```bash
+./rag-cli.sh stats [options]
+  --json           # Output in JSON format
+  --db PATH        # Custom database path
+```
+
+## Default Directory Behavior
+
+When no directories are specified, the system automatically searches for documentation:
+1. First looks in the current directory for `docs/` or `documentation/` folders
+2. If not found, checks the parent directory for the same folders
+
+## Supported File Types
+
+- Markdown files (.md, .markdown)
+- Text files (.txt)
+
+## Output Formats
+
+- **JSON**: Compact JSONL format for agent consumption
+- **Text**: Human-readable with highlighted search terms
+- **Markdown**: Formatted output with proper formatting
+
+## Examples
+
+```bash
+# Index project documentation
+./rag-cli.sh index --dir ./docs
+
+# Search for specific patterns
+./rag-cli.sh search "authentication flow" --category guide --format markdown
+
+# Check what's indexed
+./rag-cli.sh stats
+
+# Full reindex when files change significantly
+./rag-cli.sh index --full --dir ./docs
+```