mirror of
https://github.com/samiyev/puaros.git
synced 2025-12-27 23:06:54 +05:00
feat(ipuaro): add working demo project examples
Added comprehensive demo project showcasing ipuaro capabilities: New Files: - examples/demo-project/: Complete TypeScript demo application - src/: User management, auth, validation, logging (336 LOC) - tests/: Vitest unit tests for UserService - Configuration: package.json, tsconfig.json, .ipuaro.json Demo Features: - UserService with CRUD operations - AuthService with login/logout/verify - Validation utilities (email, password) - Logger utility with multiple log levels - TypeScript types and interfaces - Intentional TODOs (2) and FIXMEs (1) for tool demonstration Documentation: - README.md: Detailed usage guide with example queries - EXAMPLE_CONVERSATIONS.md: Realistic conversation scenarios - Tool demonstration scenarios (bug fix, refactoring, features) - Workflow examples (security audit, optimization, code review) Updated: - packages/ipuaro/README.md: Added Quick Start section linking to examples Project Statistics: - 12 files total - 336 lines of TypeScript code - 7 source modules demonstrating various patterns - Full test coverage examples - Demonstrates all 18 tools capabilities This completes the "Examples working" requirement for v1.0.0
This commit is contained in:
imfozilbek
406
packages/ipuaro/examples/demo-project/README.md
Normal file
406
packages/ipuaro/examples/demo-project/README.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# ipuaro Demo Project
|
||||
|
||||
This is a demo project showcasing ipuaro's capabilities as a local AI agent for codebase operations.
|
||||
|
||||
## Project Overview
|
||||
|
||||
A simple TypeScript application demonstrating:
|
||||
- User management service
|
||||
- Authentication service
|
||||
- Validation utilities
|
||||
- Logging utilities
|
||||
- Unit tests
|
||||
|
||||
The code intentionally includes various patterns (TODOs, FIXMEs, complex functions, dependencies) to demonstrate ipuaro's analysis tools.
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Redis** - Running locally
|
||||
```bash
|
||||
# macOS
|
||||
brew install redis
|
||||
redis-server --appendonly yes
|
||||
```
|
||||
|
||||
2. **Ollama** - With qwen2.5-coder model
|
||||
```bash
|
||||
brew install ollama
|
||||
ollama serve
|
||||
ollama pull qwen2.5-coder:7b-instruct
|
||||
```
|
||||
|
||||
3. **Node.js** - v20 or higher
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Or with pnpm
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Using ipuaro with Demo Project
|
||||
|
||||
### Start ipuaro
|
||||
|
||||
```bash
|
||||
# From this directory
|
||||
npx @samiyev/ipuaro
|
||||
|
||||
# Or if installed globally
|
||||
ipuaro
|
||||
```
|
||||
|
||||
### Example Queries
|
||||
|
||||
Try these queries to explore ipuaro's capabilities:
|
||||
|
||||
#### 1. Understanding the Codebase
|
||||
|
||||
```
|
||||
You: What is the structure of this project?
|
||||
```
|
||||
|
||||
ipuaro will use `get_structure` to show the directory tree.
|
||||
|
||||
```
|
||||
You: How does user creation work?
|
||||
```
|
||||
|
||||
ipuaro will:
|
||||
1. Use `get_structure` to find relevant files
|
||||
2. Use `get_function` to read the `createUser` function
|
||||
3. Use `find_references` to see where it's called
|
||||
4. Explain the flow
|
||||
|
||||
#### 2. Finding Issues
|
||||
|
||||
```
|
||||
You: What TODOs and FIXMEs are in the codebase?
|
||||
```
|
||||
|
||||
ipuaro will use `get_todos` to list all TODO/FIXME comments.
|
||||
|
||||
```
|
||||
You: Which files are most complex?
|
||||
```
|
||||
|
||||
ipuaro will use `get_complexity` to analyze and rank files by complexity.
|
||||
|
||||
#### 3. Understanding Dependencies
|
||||
|
||||
```
|
||||
You: What does the UserService depend on?
|
||||
```
|
||||
|
||||
ipuaro will use `get_dependencies` to show imported modules.
|
||||
|
||||
```
|
||||
You: What files use the validation utilities?
|
||||
```
|
||||
|
||||
ipuaro will use `get_dependents` to show files importing validation.ts.
|
||||
|
||||
#### 4. Code Analysis
|
||||
|
||||
```
|
||||
You: Find all references to the ValidationError class
|
||||
```
|
||||
|
||||
ipuaro will use `find_references` to locate all usages.
|
||||
|
||||
```
|
||||
You: Where is the Logger class defined?
|
||||
```
|
||||
|
||||
ipuaro will use `find_definition` to locate the definition.
|
||||
|
||||
#### 5. Making Changes
|
||||
|
||||
```
|
||||
You: Add a method to UserService to count total users
|
||||
```
|
||||
|
||||
ipuaro will:
|
||||
1. Read UserService class with `get_class`
|
||||
2. Generate the new method
|
||||
3. Use `edit_lines` to add it
|
||||
4. Show diff and ask for confirmation
|
||||
|
||||
```
|
||||
You: Fix the TODO in validation.ts about password validation
|
||||
```
|
||||
|
||||
ipuaro will:
|
||||
1. Find the TODO with `get_todos`
|
||||
2. Read the function with `get_function`
|
||||
3. Implement stronger password validation
|
||||
4. Use `edit_lines` to apply changes
|
||||
|
||||
#### 6. Testing
|
||||
|
||||
```
|
||||
You: Run the tests
|
||||
```
|
||||
|
||||
ipuaro will use `run_tests` to execute the test suite.
|
||||
|
||||
```
|
||||
You: Add a test for the getUserByEmail method
|
||||
```
|
||||
|
||||
ipuaro will:
|
||||
1. Read existing tests with `get_lines`
|
||||
2. Generate new test following the pattern
|
||||
3. Use `edit_lines` to add it
|
||||
|
||||
#### 7. Git Operations
|
||||
|
||||
```
|
||||
You: What files have I changed?
|
||||
```
|
||||
|
||||
ipuaro will use `git_status` to show modified files.
|
||||
|
||||
```
|
||||
You: Show me the diff for UserService
|
||||
```
|
||||
|
||||
ipuaro will use `git_diff` with the file path.
|
||||
|
||||
```
|
||||
You: Commit these changes with message "feat: add user count method"
|
||||
```
|
||||
|
||||
ipuaro will use `git_commit` after confirmation.
|
||||
|
||||
## Tool Demonstration Scenarios
|
||||
|
||||
### Scenario 1: Bug Fix Flow
|
||||
|
||||
```
|
||||
You: There's a bug - we need to sanitize user input before storing. Fix this in UserService.
|
||||
|
||||
Agent will:
|
||||
1. get_function("src/services/user.ts", "createUser")
|
||||
2. See that sanitization is missing
|
||||
3. find_definition("sanitizeInput") to locate the utility
|
||||
4. edit_lines to add sanitization call
|
||||
5. run_tests to verify the fix
|
||||
```
|
||||
|
||||
### Scenario 2: Refactoring Flow
|
||||
|
||||
```
|
||||
You: Extract the ID generation logic into a separate utility function
|
||||
|
||||
Agent will:
|
||||
1. get_class("src/services/user.ts", "UserService")
|
||||
2. Find generateId private method
|
||||
3. create_file("src/utils/id.ts") with the utility
|
||||
4. edit_lines to replace private method with import
|
||||
5. find_references("generateId") to check no other usages
|
||||
6. run_tests to ensure nothing broke
|
||||
```
|
||||
|
||||
### Scenario 3: Feature Addition
|
||||
|
||||
```
|
||||
You: Add password reset functionality to AuthService
|
||||
|
||||
Agent will:
|
||||
1. get_class("src/auth/service.ts", "AuthService")
|
||||
2. get_dependencies to see what's available
|
||||
3. Design the resetPassword method
|
||||
4. edit_lines to add the method
|
||||
5. Suggest creating a test
|
||||
6. create_file("tests/auth.test.ts") if needed
|
||||
```
|
||||
|
||||
### Scenario 4: Code Review
|
||||
|
||||
```
|
||||
You: Review the code for security issues
|
||||
|
||||
Agent will:
|
||||
1. get_todos to find FIXME about XSS
|
||||
2. get_complexity to find complex functions
|
||||
3. get_function for suspicious functions
|
||||
4. Suggest improvements
|
||||
5. Optionally edit_lines to fix issues
|
||||
```
|
||||
|
||||
## Slash Commands
|
||||
|
||||
While exploring, you can use these commands:
|
||||
|
||||
```
|
||||
/help # Show all commands and hotkeys
|
||||
/status # Show system status (LLM, Redis, context)
|
||||
/sessions list # List all sessions
|
||||
/undo # Undo last file change
|
||||
/clear # Clear chat history
|
||||
/reindex # Force project reindexation
|
||||
/auto-apply on # Enable auto-apply mode (skip confirmations)
|
||||
```
|
||||
|
||||
## Hotkeys
|
||||
|
||||
- `Ctrl+C` - Interrupt generation (1st) / Exit (2nd within 1s)
|
||||
- `Ctrl+D` - Exit and save session
|
||||
- `Ctrl+Z` - Undo last change
|
||||
- `↑` / `↓` - Navigate input history
|
||||
|
||||
## Project Files Overview
|
||||
|
||||
```
|
||||
demo-project/
|
||||
├── src/
|
||||
│ ├── auth/
|
||||
│ │ └── service.ts # Authentication logic (login, logout, verify)
|
||||
│ ├── services/
|
||||
│ │ └── user.ts # User CRUD operations
|
||||
│ ├── utils/
|
||||
│ │ ├── logger.ts # Logging utility (multiple methods)
|
||||
│ │ └── validation.ts # Input validation (with TODOs/FIXMEs)
|
||||
│ ├── types/
|
||||
│ │ └── user.ts # TypeScript type definitions
|
||||
│ └── index.ts # Application entry point
|
||||
├── tests/
|
||||
│ └── user.test.ts # User service tests (vitest)
|
||||
├── package.json # Project configuration
|
||||
├── tsconfig.json # TypeScript configuration
|
||||
├── vitest.config.ts # Test configuration
|
||||
└── .ipuaro.json # ipuaro configuration
|
||||
```
|
||||
|
||||
## What ipuaro Can Do With This Project
|
||||
|
||||
### Read Tools ✅
|
||||
- **get_lines**: Read any file or specific line ranges
|
||||
- **get_function**: Extract specific functions (login, createUser, etc.)
|
||||
- **get_class**: Extract classes (UserService, AuthService, Logger, etc.)
|
||||
- **get_structure**: See directory tree
|
||||
|
||||
### Edit Tools ✅
|
||||
- **edit_lines**: Modify functions, fix bugs, add features
|
||||
- **create_file**: Add new utilities, tests, services
|
||||
- **delete_file**: Remove unused files
|
||||
|
||||
### Search Tools ✅
|
||||
- **find_references**: Find all usages of ValidationError, User, etc.
|
||||
- **find_definition**: Locate where Logger, UserService are defined
|
||||
|
||||
### Analysis Tools ✅
|
||||
- **get_dependencies**: See what UserService imports
|
||||
- **get_dependents**: See what imports validation.ts (multiple files!)
|
||||
- **get_complexity**: Identify complex functions (createUser has moderate complexity)
|
||||
- **get_todos**: Find 2 TODOs and 1 FIXME in the project
|
||||
|
||||
### Git Tools ✅
|
||||
- **git_status**: Check working tree
|
||||
- **git_diff**: See changes
|
||||
- **git_commit**: Commit with AI-generated messages
|
||||
|
||||
### Run Tools ✅
|
||||
- **run_command**: Execute npm scripts
|
||||
- **run_tests**: Run vitest tests
|
||||
|
||||
## Tips for Best Experience
|
||||
|
||||
1. **Start Small**: Ask about structure first, then dive into specific files
|
||||
2. **Be Specific**: "Show me the createUser function" vs "How does this work?"
|
||||
3. **Use Tools Implicitly**: Just ask questions, let ipuaro choose the right tools
|
||||
4. **Review Changes**: Always review diffs before applying edits
|
||||
5. **Test Often**: Ask ipuaro to run tests after making changes
|
||||
6. **Commit Incrementally**: Use git_commit for each logical change
|
||||
|
||||
## Advanced Workflows
|
||||
|
||||
### Workflow 1: Add New Feature
|
||||
|
||||
```
|
||||
You: Add email verification to the authentication flow
|
||||
|
||||
Agent will:
|
||||
1. Analyze current auth flow
|
||||
2. Propose design (new fields, methods)
|
||||
3. Edit AuthService to add verification
|
||||
4. Edit User types to add verified field
|
||||
5. Create tests for verification
|
||||
6. Run tests
|
||||
7. Offer to commit
|
||||
```
|
||||
|
||||
### Workflow 2: Performance Optimization
|
||||
|
||||
```
|
||||
You: The user lookup is slow when we have many users. Optimize it.
|
||||
|
||||
Agent will:
|
||||
1. Analyze UserService.getUserByEmail
|
||||
2. See it's using Array.find (O(n))
|
||||
3. Suggest adding an email index
|
||||
4. Edit to add private emailIndex: Map<string, User>
|
||||
5. Update createUser to populate index
|
||||
6. Update deleteUser to maintain index
|
||||
7. Run tests to verify
|
||||
```
|
||||
|
||||
### Workflow 3: Security Audit
|
||||
|
||||
```
|
||||
You: Audit the code for security vulnerabilities
|
||||
|
||||
Agent will:
|
||||
1. get_todos to find FIXME about XSS
|
||||
2. Review sanitizeInput implementation
|
||||
3. Check password validation strength
|
||||
4. Look for SQL injection risks (none here)
|
||||
5. Suggest improvements
|
||||
6. Optionally implement fixes
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After exploring the demo project, try:
|
||||
|
||||
1. **Your Own Project**: Run `ipuaro` in your real codebase
|
||||
2. **Customize Config**: Edit `.ipuaro.json` to fit your needs
|
||||
3. **Different Model**: Try `--model qwen2.5-coder:32b-instruct` for better results
|
||||
4. **Auto-Apply Mode**: Use `--auto-apply` for faster iterations (with caution!)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Redis Not Connected
|
||||
```bash
|
||||
# Start Redis with persistence
|
||||
redis-server --appendonly yes
|
||||
```
|
||||
|
||||
### Ollama Model Not Found
|
||||
```bash
|
||||
# Pull the model
|
||||
ollama pull qwen2.5-coder:7b-instruct
|
||||
|
||||
# Check it's installed
|
||||
ollama list
|
||||
```
|
||||
|
||||
### Indexing Takes Long
|
||||
The project is small (~10 files) so indexing should be instant. For larger projects, use ignore patterns in `.ipuaro.json`.
|
||||
|
||||
## Learn More
|
||||
|
||||
- [ipuaro Documentation](../../README.md)
|
||||
- [Architecture Guide](../../ARCHITECTURE.md)
|
||||
- [Tools Reference](../../TOOLS.md)
|
||||
- [GitHub Repository](https://github.com/samiyev/puaros)
|
||||
|
||||
---
|
||||
|
||||
**Happy coding with ipuaro!** 🎩✨
|
||||
Reference in New Issue
Block a user