ailabs/puaros
1
0
Fork 0
mirror of https://github.com/samiyev/puaros.git synced 2025-12-27 23:06:54 +05:00
Code Issues Packages Projects Releases Wiki Activity

docs: add ipuaro package documentation to root files

Browse Source
This commit is contained in:
imfozilbek
2025-11-29 22:10:13 +05:00
parent 085e236c4a
commit ec7adb1330
2 changed files with 169 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
CLAUDE.md
View File

@@ -4,7 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## Project Overview
Puaros is a TypeScript monorepo using pnpm workspaces. Currently contains the `@puaros/guardian` package - a code quality guardian for detecting hardcoded values, circular dependencies, framework leaks, naming violations, and architecture violations. The project uses Node.js 22.18.0 (see `.nvmrc`). Puaros is a TypeScript monorepo using pnpm workspaces. Contains two packages:
- **`@puaros/guardian`** - Code quality guardian for detecting hardcoded values, circular dependencies, framework leaks, naming violations, and architecture violations.
- **`@puaros/ipuaro`** - Local AI agent for codebase operations with "infinite" context feeling. Uses lazy loading, Redis persistence, tree-sitter AST parsing, and Ollama LLM integration.
The project uses Node.js 22.18.0 (see `.nvmrc`).
## Essential Commands ## Essential Commands
@@ -110,18 +116,27 @@ Commits should only follow the Conventional Commits format without any additiona
``` ```
puaros/ puaros/
├── packages/ ├── packages/
│ └── guardian/ # @puaros/guardian - Code quality analyzer │ ├── guardian/ # @puaros/guardian - Code quality analyzer
│ ├── src/ # Source files (Clean Architecture layers) │ │ ├── src/ # Source files (Clean Architecture)
│ │ ├── domain/ # Domain layer (entities, value objects) │ │ │ ├── domain/ # Entities, value objects
│ │ ├── application/ # Application layer (use cases, DTOs) │ │ │ ├── application/ # Use cases, DTOs
│ │ ├── infrastructure/ # Infrastructure layer (parsers, analyzers) │ │ │ ├── infrastructure/ # Parsers, analyzers
│ │ ├── cli/ # CLI implementation │ │ │ ├── cli/ # CLI implementation
│ │ └── shared/ # Shared utilities │ │ │ └── shared/ # Shared utilities
│ ├── dist/ # Build output │ │ ├── bin/ # CLI entry point
│ │ ├── tests/ # Test files
│ │ └── examples/ # Usage examples
│ └── ipuaro/ # @puaros/ipuaro - Local AI agent
│ ├── src/ # Source files (Clean Architecture)
│ │ ├── domain/ # Entities, value objects, services
│ │ ├── application/ # Use cases, DTOs, mappers
│ │ ├── infrastructure/ # Storage, LLM, indexer, tools
│ │ ├── tui/ # Terminal UI (Ink/React)
│ │ ├── cli/ # CLI commands
│ │ └── shared/ # Types, constants, utils
│ ├── bin/ # CLI entry point │ ├── bin/ # CLI entry point
│ ├── tests/ # Test files │ ├── tests/ # Unit and E2E tests
│ ├── examples/ # Usage examples │ └── examples/ # Demo projects
│ └── package.json # Uses Vitest for testing
├── pnpm-workspace.yaml # Workspace configuration ├── pnpm-workspace.yaml # Workspace configuration
└── tsconfig.base.json # Shared TypeScript config └── tsconfig.base.json # Shared TypeScript config
``` ```
@@ -142,6 +157,34 @@ Key features:
- Architecture violation detection - Architecture violation detection
- CLI tool with `guardian` command - CLI tool with `guardian` command
### ipuaro Package Architecture
The ipuaro package follows Clean Architecture principles:
- **Domain Layer**: Entities (Session, Project), value objects (FileData, FileAST, ChatMessage), service interfaces
- **Application Layer**: Use cases (StartSession, HandleMessage, IndexProject, ExecuteTool), DTOs, mappers
- **Infrastructure Layer**: Redis storage, Ollama client, indexer, 18 tool implementations, security
- **TUI Layer**: Ink/React components (StatusBar, Chat, Input, DiffView, ConfirmDialog)
- **CLI Layer**: Commander.js entry point and commands
Key features:
- 18 LLM tools (read, edit, search, analysis, git, run)
- Redis persistence with AOF
- tree-sitter AST parsing (ts, tsx, js, jsx)
- Ollama LLM integration (qwen2.5-coder:7b-instruct)
- File watching via chokidar
- Session and undo management
- Security (blacklist/whitelist for commands)
**Tools summary:**
| Category | Tools |
|----------|-------|
| Read | get_lines, get_function, get_class, get_structure |
| Edit | edit_lines, create_file, delete_file |
| Search | find_references, find_definition |
| Analysis | get_dependencies, get_dependents, get_complexity, get_todos |
| Git | git_status, git_diff, git_commit |
| Run | run_command, run_tests |
### TypeScript Configuration ### TypeScript Configuration
Base configuration (`tsconfig.base.json`) uses: Base configuration (`tsconfig.base.json`) uses:
@@ -169,19 +212,30 @@ Guardian package (`packages/guardian/tsconfig.json`):
## Dependencies ## Dependencies
Guardian package uses: **Guardian package:**
- `commander` - CLI framework for command-line interface - `commander` - CLI framework
- `simple-git` - Git operations - `simple-git` - Git operations
- `tree-sitter` - Abstract syntax tree parsing - `tree-sitter` - AST parsing
- `tree-sitter-javascript` - JavaScript parser - `tree-sitter-javascript/typescript` - JS/TS parsers
- `tree-sitter-typescript` - TypeScript parser
- `uuid` - UUID generation - `uuid` - UUID generation
Development tools: **ipuaro package:**
- Vitest for testing with coverage thresholds - `ink`, `ink-text-input`, `react` - Terminal UI
- `ioredis` - Redis client
- `tree-sitter` - AST parsing
- `tree-sitter-javascript/typescript` - JS/TS parsers
- `ollama` - LLM client
- `simple-git` - Git operations
- `chokidar` - File watching
- `commander` - CLI framework
- `zod` - Validation
- `ignore` - Gitignore parsing
**Development tools (shared):**
- Vitest for testing (80% coverage threshold)
- ESLint with TypeScript strict rules - ESLint with TypeScript strict rules
- Prettier for formatting - Prettier (4-space indentation)
- `@vitest/ui` - Vitest UI for interactive testing - `@vitest/ui` - Interactive testing UI
- `@vitest/coverage-v8` - Coverage reporting - `@vitest/coverage-v8` - Coverage reporting
## Development Workflow ## Development Workflow

104
README.md
View File

@@ -6,6 +6,8 @@ A TypeScript monorepo for code quality and analysis tools.
- **[@puaros/guardian](./packages/guardian)** - Research-backed code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, secrets, circular dependencies, architecture violations, and anemic domain models. Every rule is based on academic research, industry standards (OWASP, SonarQube), and authoritative books (Martin Fowler, Uncle Bob, Eric Evans). Perfect for AI-assisted development and enforcing Clean Architecture at scale. - **[@puaros/guardian](./packages/guardian)** - Research-backed code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, secrets, circular dependencies, architecture violations, and anemic domain models. Every rule is based on academic research, industry standards (OWASP, SonarQube), and authoritative books (Martin Fowler, Uncle Bob, Eric Evans). Perfect for AI-assisted development and enforcing Clean Architecture at scale.
- **[@puaros/ipuaro](./packages/ipuaro)** - Local AI agent for codebase operations with "infinite" context feeling. Uses lazy loading and smart context management to work with codebases of any size. Features 18 LLM tools for reading, editing, searching, and analyzing code. Built with Ink/React TUI, Redis persistence, tree-sitter AST parsing, and Ollama integration.
## Prerequisites ## Prerequisites
- Node.js 22.18.0 (use `nvm use` to automatically switch to the correct version) - Node.js 22.18.0 (use `nvm use` to automatically switch to the correct version)
@@ -75,18 +77,27 @@ pnpm eslint "packages/**/*.ts"
``` ```
puaros/ puaros/
├── packages/ ├── packages/
│ └── guardian/ # @puaros/guardian - Code quality analyzer │ ├── guardian/ # @puaros/guardian - Code quality analyzer
│ │ ├── src/ # Source files (Clean Architecture)
│ │ │ ├── domain/ # Domain layer
│ │ │ ├── application/ # Application layer
│ │ │ ├── infrastructure/# Infrastructure layer
│ │ │ ├── cli/ # CLI implementation
│ │ │ └── shared/ # Shared utilities
│ │ ├── bin/ # CLI entry point
│ │ ├── tests/ # Unit and integration tests
│ │ └── examples/ # Usage examples
│ └── ipuaro/ # @puaros/ipuaro - Local AI agent
│ ├── src/ # Source files (Clean Architecture) │ ├── src/ # Source files (Clean Architecture)
│ │ ├── domain/ # Domain layer │ │ ├── domain/ # Entities, value objects, services
│ │ ├── application/ # Application layer │ │ ├── application/ # Use cases, DTOs, mappers
│ │ ├── infrastructure/# Infrastructure layer │ │ ├── infrastructure/# Storage, LLM, indexer, tools
│ │ ├── cli/ # CLI implementation │ │ ├── tui/ # Terminal UI (Ink/React)
│ │ └── shared/ # Shared utilities │ │ ├── cli/ # CLI commands
│ ├── dist/ # Build output (generated) │ │ └── shared/ # Types, constants, utils
│ ├── bin/ # CLI entry point │ ├── bin/ # CLI entry point
│ ├── tests/ # Unit and integration tests │ ├── tests/ # Unit and E2E tests
│ ├── examples/ # Usage examples │ └── examples/ # Demo projects
│ └── package.json
├── pnpm-workspace.yaml # Workspace configuration ├── pnpm-workspace.yaml # Workspace configuration
├── tsconfig.base.json # Shared TypeScript config ├── tsconfig.base.json # Shared TypeScript config
├── eslint.config.mjs # ESLint configuration ├── eslint.config.mjs # ESLint configuration
@@ -204,6 +215,79 @@ guardian check ./src --format json > report.json
guardian check ./src --fail-on hardcode --fail-on circular guardian check ./src --fail-on hardcode --fail-on circular
``` ```
## ipuaro Package
The `@puaros/ipuaro` package is a local AI agent for codebase operations:
### Features
- **Infinite Context Feeling**: Lazy loading and smart context management for any codebase size
- **18 LLM Tools**: Read, edit, search, analyze code through natural language
- **Terminal UI**: Full-featured TUI built with Ink/React
- **Redis Persistence**: Sessions, undo stack, and project index stored in Redis
- **AST Parsing**: tree-sitter for TypeScript/JavaScript analysis
- **File Watching**: Real-time index updates via chokidar
- **Security**: Blacklist/whitelist for command execution
### Tech Stack
| Component | Technology |
|-----------|------------|
| Runtime | Node.js + TypeScript |
| TUI | Ink (React for terminal) |
| Storage | Redis with AOF persistence |
| AST | tree-sitter (ts, tsx, js, jsx) |
| LLM | Ollama (qwen2.5-coder:7b-instruct) |
| Git | simple-git |
| File watching | chokidar |
### Tools (18 total)
| Category | Tools |
|----------|-------|
| **Read** | get_lines, get_function, get_class, get_structure |
| **Edit** | edit_lines, create_file, delete_file |
| **Search** | find_references, find_definition |
| **Analysis** | get_dependencies, get_dependents, get_complexity, get_todos |
| **Git** | git_status, git_diff, git_commit |
| **Run** | run_command, run_tests |
### Architecture
Built with Clean Architecture principles:
- **Domain Layer**: Entities, value objects, service interfaces
- **Application Layer**: Use cases, DTOs, mappers
- **Infrastructure Layer**: Redis storage, Ollama client, indexer, tools
- **TUI Layer**: Ink/React components and hooks
- **CLI Layer**: Commander.js entry point
### Usage
```bash
# Start TUI in current directory
ipuaro
# Start in specific directory
ipuaro /path/to/project
# Index only (no TUI)
ipuaro index
# With auto-apply mode
ipuaro --auto-apply
```
### Commands
| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/clear` | Clear chat history |
| `/undo` | Revert last file change |
| `/sessions` | Manage sessions |
| `/status` | System status |
| `/reindex` | Force reindexation |
## Dependencies ## Dependencies
Guardian package uses: Guardian package uses: