puaros/packages/ipuaro/examples/demo-project

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

# macOS
brew install redis
redis-server --appendonly yes

2. Ollama - With qwen2.5-coder model

brew install ollama
ollama serve
ollama pull qwen2.5-coder:7b-instruct

3. Node.js - v20 or higher

Installation

# Install dependencies
npm install

# Or with pnpm
pnpm install

Using ipuaro with Demo Project

Start ipuaro

# 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

# Start Redis with persistence
redis-server --appendonly yes

Ollama Model Not Found

# 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
• Architecture Guide
• Tools Reference
• GitHub Repository

---

Happy coding with ipuaro! 🎩✨