docs(ipuaro): complete comprehensive documentation for v0.17.0

Added: - ARCHITECTURE.md: Complete architecture documentation with Clean Architecture principles, data flows, design decisions - TOOLS.md: Comprehensive reference for all 18 tools with examples and best practices - README.md: Enhanced with tools reference, slash commands, hotkeys, troubleshooting, FAQ, API examples Updated: - README.md: Status to Release Candidate, all features marked complete - CHANGELOG.md: Added v0.17.0 entry with documentation statistics - ROADMAP.md: Added v0.17.0 milestone, marked documentation complete - package.json: Bumped version to 0.17.0 Documentation statistics: - Total: ~2500 lines across 3 files - 18/18 tools documented (100%) - 8/8 slash commands documented (100%) - 50+ code examples - 6 troubleshooting entries - 8 FAQ answers All tests passing (1420), coverage 97.59%, zero lint errors
2025-12-27 23:06:54 +05:00 · 2025-12-01 16:09:47 +05:00
parent 8f995fc596
commit baccfd53c0
6 changed files with 2680 additions and 53 deletions
--- a/packages/ipuaro/README.md
+++ b/packages/ipuaro/README.md
@@ -7,9 +7,9 @@
 [![npm version](https://badge.fury.io/js/@samiyev%2Fipuaro.svg)](https://www.npmjs.com/package/@samiyev/ipuaro)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

-> **Status:** 🚧 Early Development (v0.1.0 Foundation)
+> **Status:** 🎉 Release Candidate (v0.16.0 → v1.0.0)
 >
-> Core infrastructure is ready. Active development in progress.
+> All core features complete. Production-ready release coming soon.

 ## Vision

@@ -19,18 +19,20 @@ Work with codebases of any size using local AI:
 - 🔒 **100% Local**: Your code never leaves your machine
 - ⚡ **Fast**: Redis persistence + tree-sitter parsing

-## Planned Features
+## Features

-### 18 LLM Tools
+### 18 LLM Tools (All Implemented ✅)

-| Category | Tools | Status |
-|----------|-------|--------|
-| **Read** | `get_lines`, `get_function`, `get_class`, `get_structure` | 🔜 v0.5.0 |
-| **Edit** | `edit_lines`, `create_file`, `delete_file` | 🔜 v0.6.0 |
-| **Search** | `find_references`, `find_definition` | 🔜 v0.7.0 |
-| **Analysis** | `get_dependencies`, `get_dependents`, `get_complexity`, `get_todos` | 🔜 v0.8.0 |
-| **Git** | `git_status`, `git_diff`, `git_commit` | 🔜 v0.9.0 |
-| **Run** | `run_command`, `run_tests` | 🔜 v0.9.0 |
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Read** | `get_lines`, `get_function`, `get_class`, `get_structure` | Read code without loading everything into context |
+| **Edit** | `edit_lines`, `create_file`, `delete_file` | Make changes with confirmation and undo support |
+| **Search** | `find_references`, `find_definition` | Find symbol definitions and usages across codebase |
+| **Analysis** | `get_dependencies`, `get_dependents`, `get_complexity`, `get_todos` | Analyze code structure, complexity, and TODOs |
+| **Git** | `git_status`, `git_diff`, `git_commit` | Git operations with safety checks |
+| **Run** | `run_command`, `run_tests` | Execute commands and tests with security validation |
+
+See [Tools Documentation](#tools-reference) below for detailed usage examples.

 ### Terminal UI

@@ -54,6 +56,31 @@ Work with codebases of any size using local AI:
 └───────────────────────────────────────────────────────────┘
 ```

+### Slash Commands
+
+Control your session with built-in commands:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands and hotkeys |
+| `/clear` | Clear chat history (keeps session) |
+| `/undo` | Revert last file change from undo stack |
+| `/sessions [list\|load\|delete] [id]` | Manage sessions |
+| `/status` | Show system status (LLM, context, stats) |
+| `/reindex` | Force full project reindexation |
+| `/eval` | LLM self-check for hallucinations |
+| `/auto-apply [on\|off]` | Toggle auto-apply mode for edits |
+
+### Hotkeys
+
+| Hotkey | Action |
+|--------|--------|
+| `Ctrl+C` | Interrupt generation (1st press) / Exit (2nd press within 1s) |
+| `Ctrl+D` | Exit and save session |
+| `Ctrl+Z` | Undo last file change |
+| `↑` / `↓` | Navigate input history |
+| `Tab` | Path autocomplete (coming soon) |
+
 ### Key Capabilities

 🔍 **Smart Code Understanding**
@@ -181,49 +208,263 @@ Clean Architecture with clear separation:

 ## Development Status

-### ✅ Completed (v0.1.0)
+### ✅ Completed (v0.1.0 - v0.16.0)

- [x] Project setup (tsup, vitest, ESM)
- [x] Domain entities (Session, Project)
- [x] Value objects (FileData, FileAST, ChatMessage, etc.)
- [x] Service interfaces (IStorage, ILLMClient, ITool, IIndexer)
- [x] Shared module (Config, Errors, Utils)
- [x] CLI placeholder commands
- [x] 91 unit tests, 100% coverage
+- [x] **v0.1.0 - v0.4.0**: Foundation (domain, storage, indexer, LLM integration)
+- [x] **v0.5.0 - v0.9.0**: All 18 tools implemented
+- [x] **v0.10.0**: Session management with undo support
+- [x] **v0.11.0 - v0.12.0**: Full TUI with all components
+- [x] **v0.13.0**: Security (PathValidator, command validation)
+- [x] **v0.14.0**: 8 slash commands
+- [x] **v0.15.0**: CLI entry point with onboarding
+- [x] **v0.16.0**: Comprehensive error handling system
+- [x] **1420 tests, 98% coverage**

-### 🔜 Next Up
+### 🔜 v1.0.0 - Production Ready

- [ ] **v0.2.0** - Redis Storage
- [ ] **v0.3.0** - Indexer (file scanning, AST parsing)
- [ ] **v0.4.0** - LLM Integration (Ollama)
- [ ] **v0.5.0-0.9.0** - Tools implementation
- [ ] **v0.10.0** - Session management
- [ ] **v0.11.0** - TUI
+- [ ] Performance optimizations
+- [ ] Complete documentation
+- [ ] Working examples

-See [ROADMAP.md](./ROADMAP.md) for detailed development plan.
+See [ROADMAP.md](./ROADMAP.md) for detailed development plan and [CHANGELOG.md](./CHANGELOG.md) for release history.

-## API (Coming Soon)
+## Tools Reference
+
+The AI agent has access to 18 tools for working with your codebase. Here are the most commonly used ones:
+
+### Read Tools
+
+**`get_lines(path, start?, end?)`**
+Read specific lines from a file.
+
+```
+You: Show me the authentication logic
+Assistant: [get_lines src/auth/service.ts 45 67]
+# Returns lines 45-67 with line numbers
+```
+
+**`get_function(path, name)`**
+Get a specific function's source code and metadata.
+
+```
+You: How does the login function work?
+Assistant: [get_function src/auth/service.ts login]
+# Returns function code, params, return type, and metadata
+```
+
+**`get_class(path, name)`**
+Get a specific class's source code and metadata.
+
+```
+You: Show me the UserService class
+Assistant: [get_class src/services/user.ts UserService]
+# Returns class code, methods, properties, and inheritance info
+```
+
+**`get_structure(path?, depth?)`**
+Get directory tree structure.
+
+```
+You: What's in the src/auth directory?
+Assistant: [get_structure src/auth]
+# Returns ASCII tree with files and folders
+```
+
+### Edit Tools
+
+**`edit_lines(path, start, end, content)`**
+Replace lines in a file (requires confirmation).
+
+```
+You: Update the timeout to 5000ms
+Assistant: [edit_lines src/config.ts 23 23 "  timeout: 5000,"]
+# Shows diff, asks for confirmation
+```
+
+**`create_file(path, content)`**
+Create a new file (requires confirmation).
+
+```
+You: Create a new utility for date formatting
+Assistant: [create_file src/utils/date.ts "export function formatDate..."]
+# Creates file after confirmation
+```
+
+**`delete_file(path)`**
+Delete a file (requires confirmation).
+
+```
+You: Remove the old test file
+Assistant: [delete_file tests/old-test.test.ts]
+# Deletes after confirmation
+```
+
+### Search Tools
+
+**`find_references(symbol, path?)`**
+Find all usages of a symbol across the codebase.
+
+```
+You: Where is getUserById used?
+Assistant: [find_references getUserById]
+# Returns all files/lines where it's called
+```
+
+**`find_definition(symbol)`**
+Find where a symbol is defined.
+
+```
+You: Where is ApiClient defined?
+Assistant: [find_definition ApiClient]
+# Returns file, line, and context
+```
+
+### Analysis Tools
+
+**`get_dependencies(path)`**
+Get files that a specific file imports.
+
+```
+You: What does auth.ts depend on?
+Assistant: [get_dependencies src/auth/service.ts]
+# Returns list of imported files
+```
+
+**`get_dependents(path)`**
+Get files that import a specific file.
+
+```
+You: What files use the database module?
+Assistant: [get_dependents src/db/index.ts]
+# Returns list of files importing this
+```
+
+**`get_complexity(path?, limit?)`**
+Get complexity metrics for files.
+
+```
+You: Which files are most complex?
+Assistant: [get_complexity null 10]
+# Returns top 10 most complex files with metrics
+```
+
+**`get_todos(path?, type?)`**
+Find TODO/FIXME/HACK comments.
+
+```
+You: What TODOs are there?
+Assistant: [get_todos]
+# Returns all TODO comments with locations
+```
+
+### Git Tools
+
+**`git_status()`**
+Get current git repository status.
+
+```
+You: What files have changed?
+Assistant: [git_status]
+# Returns branch, staged, modified, untracked files
+```
+
+**`git_diff(path?, staged?)`**
+Get uncommitted changes.
+
+```
+You: Show me what changed in auth.ts
+Assistant: [git_diff src/auth/service.ts]
+# Returns diff output
+```
+
+**`git_commit(message, files?)`**
+Create a git commit (requires confirmation).
+
+```
+You: Commit these auth changes
+Assistant: [git_commit "feat: add password reset flow" ["src/auth/service.ts"]]
+# Creates commit after confirmation
+```
+
+### Run Tools
+
+**`run_command(command, timeout?)`**
+Execute shell commands (with security validation).
+
+```
+You: Run the build
+Assistant: [run_command "npm run build"]
+# Checks security, then executes
+```
+
+**`run_tests(path?, filter?, watch?)`**
+Run project tests.
+
+```
+You: Test the auth module
+Assistant: [run_tests "tests/auth" null false]
+# Auto-detects test runner and executes
+```
+
+For complete tool documentation with all parameters and options, see [TOOLS.md](./TOOLS.md).
+
+## Programmatic API
+
+You can use ipuaro as a library in your own Node.js applications:

 ```typescript
-import { startSession, handleMessage } from "@samiyev/ipuaro"
+import {
+    createRedisClient,
+    RedisStorage,
+    OllamaClient,
+    ToolRegistry,
+    StartSession,
+    HandleMessage
+} from "@samiyev/ipuaro"
+
+// Initialize dependencies
+const redis = await createRedisClient({ host: "localhost", port: 6379 })
+const storage = new RedisStorage(redis, "my-project")
+const llm = new OllamaClient({
+    model: "qwen2.5-coder:7b-instruct",
+    contextWindow: 128000,
+    temperature: 0.1
+})
+const tools = new ToolRegistry()
+
+// Register tools
+tools.register(new GetLinesTool(storage, "/path/to/project"))
+// ... register other tools

 // Start a session
-const session = await startSession({
-    projectPath: "./my-project",
-    model: "qwen2.5-coder:7b-instruct"
-})
+const startSession = new StartSession(storage)
+const session = await startSession.execute("my-project")

-// Send a message
-const response = await handleMessage(session, "Explain the auth flow")
+// Handle a message
+const handleMessage = new HandleMessage(storage, llm, tools)
+await handleMessage.execute(session, "Show me the auth flow")

-console.log(response.content)
-console.log(`Tokens: ${response.stats.tokens}`)
-console.log(`Tool calls: ${response.stats.toolCalls}`)
+// Session is automatically updated in Redis
 ```

+For full API documentation, see the TypeScript definitions in `src/` or explore the [source code](./src/).
+
 ## How It Works

-### Lazy Loading Context
+### 1. Project Indexing
+
+When you start ipuaro, it scans your project and builds an index:
+
+```
+1. File Scanner → Recursively scans files (.ts, .js, .tsx, .jsx)
+2. AST Parser → Parses with tree-sitter (extracts functions, classes, imports)
+3. Meta Analyzer → Calculates complexity, dependencies, hub detection
+4. Index Builder → Creates symbol index and dependency graph
+5. Redis Storage → Persists everything for instant startup next time
+6. Watchdog → Watches files for changes and updates index in background
+```
+
+### 2. Lazy Loading Context

 Instead of loading entire codebase into context:

@@ -232,24 +473,161 @@ Traditional approach:
 ├── Load all files → 500k tokens → ❌ Exceeds context window

 ipuaro approach:
-├── Load project structure → 2k tokens
-├── Load AST metadata → 10k tokens
-├── On demand: get_function("auth.ts", "login") → 200 tokens
-├── Total: ~12k tokens → ✅ Fits in context
+├── Load project structure → ~2k tokens
+├── Load AST metadata → ~10k tokens
+├── On demand: get_function("auth.ts", "login") → ~200 tokens
+├── Total: ~12k tokens → ✅ Fits in 128k context window
 ```

-### Tool-Based Code Access
+Context automatically compresses when usage exceeds 80% by summarizing old messages.
+
+### 3. Tool-Based Code Access
+
+The LLM doesn't see your code initially. It only sees structure and metadata. When it needs code, it uses tools:

 ```
-User: "How does user creation work?"
+You: "How does user creation work?"

-ipuaro:
-1. [get_structure src/] → sees user/ folder
-2. [get_function src/user/service.ts createUser] → gets function code
+Agent reasoning:
+1. [get_structure src/] → sees user/ folder exists
+2. [get_function src/user/service.ts createUser] → loads specific function
 3. [find_references createUser] → finds all usages
-4. Synthesizes answer with specific code context
+4. Synthesizes answer with only relevant code loaded
+
+Total tokens used: ~2k (vs loading entire src/ which could be 50k+)
 ```

+### 4. Session Persistence
+
+Everything is saved to Redis:
+- Chat history and context state
+- Undo stack (last 10 file changes)
+- Session metadata and statistics
+
+Resume your session anytime with `/sessions load <id>`.
+
+### 5. Security Model
+
+Three-layer security:
+1. **Blacklist**: Dangerous commands always blocked (rm -rf, sudo, etc.)
+2. **Whitelist**: Safe commands auto-approved (npm, git status, etc.)
+3. **Confirmation**: Unknown commands require user approval
+
+File operations are restricted to project directory only (path traversal prevention).
+
+## Troubleshooting
+
+### Redis Connection Errors
+
+**Error**: `Redis connection failed`
+
+**Solutions**:
+```bash
+# Check if Redis is running
+redis-cli ping  # Should return "PONG"
+
+# Start Redis with AOF persistence
+redis-server --appendonly yes
+
+# Check Redis logs
+tail -f /usr/local/var/log/redis.log  # macOS
+```
+
+### Ollama Model Not Found
+
+**Error**: `Model qwen2.5-coder:7b-instruct not found`
+
+**Solutions**:
+```bash
+# Pull the model
+ollama pull qwen2.5-coder:7b-instruct
+
+# List installed models
+ollama list
+
+# Check Ollama is running
+ollama serve
+```
+
+### Large Project Performance
+
+**Issue**: Indexing takes too long or uses too much memory
+
+**Solutions**:
+```bash
+# Index only a subdirectory
+ipuaro ./src
+
+# Add more ignore patterns to .ipuaro.json
+{
+    "project": {
+        "ignorePatterns": ["node_modules", "dist", ".git", "coverage", "build"]
+    }
+}
+
+# Increase Node.js memory limit
+NODE_OPTIONS="--max-old-space-size=4096" ipuaro
+```
+
+### Context Window Exceeded
+
+**Issue**: `Context window exceeded` errors
+
+**Solutions**:
+- Context auto-compresses at 80%, but you can manually `/clear` history
+- Use more targeted questions instead of asking about entire codebase
+- The agent will automatically use tools to load only what's needed
+
+### File Changes Not Detected
+
+**Issue**: Made changes but agent doesn't see them
+
+**Solutions**:
+```bash
+# Force reindex
+/reindex
+
+# Or restart with fresh index
+rm -rf ~/.ipuaro/cache
+ipuaro
+```
+
+### Undo Not Working
+
+**Issue**: `/undo` says no changes to undo
+
+**Explanation**: Undo stack only tracks the last 10 file edits made through ipuaro. Manual file edits outside ipuaro cannot be undone.
+
+## FAQ
+
+**Q: Does ipuaro send my code to any external servers?**
+
+A: No. Everything runs locally. Ollama runs on your machine, Redis stores data locally, and no network requests are made except to your local Ollama instance.
+
+**Q: What languages are supported?**
+
+A: Currently TypeScript, JavaScript (including TSX/JSX). More languages planned for future versions.
+
+**Q: Can I use OpenAI/Anthropic/other LLM providers?**
+
+A: Currently only Ollama is supported. OpenAI/Anthropic support is planned for v1.2.0.
+
+**Q: How much disk space does Redis use?**
+
+A: Depends on project size. A typical mid-size project (1000 files) uses ~50-100MB. Redis uses AOF persistence, so data survives restarts.
+
+**Q: Can I use ipuaro in a CI/CD pipeline?**
+
+A: Yes, but it's designed for interactive use. For automated code analysis, consider the programmatic API.
+
+**Q: What's the difference between ipuaro and GitHub Copilot?**
+
+A: Copilot is an autocomplete tool. ipuaro is a conversational agent that can read, analyze, modify files, run commands, and has full codebase understanding through AST parsing.
+
+**Q: Why Redis instead of SQLite or JSON files?**
+
+A: Redis provides fast in-memory access, AOF persistence, and handles concurrent access well. The session model fits Redis's data structures perfectly.
+
 ## Contributing

 Contributions welcome! This project is in early development.