ailabs/puaros
1
0
Fork 0
mirror of https://github.com/samiyev/puaros.git synced 2025-12-27 15:00:41 +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
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
@@ -110,18 +116,27 @@ Commits should only follow the Conventional Commits format without any additiona
```
puaros/
├── packages/
│ └── guardian/ # @puaros/guardian - Code quality analyzer
│ ├── src/ # Source files (Clean Architecture layers)
│ │ ├── domain/ # Domain layer (entities, value objects)
│ │ ├── application/ # Application layer (use cases, DTOs)
│ │ ├── infrastructure/ # Infrastructure layer (parsers, analyzers)
│ │ ├── cli/ # CLI implementation
│ │ └── shared/ # Shared utilities
│ ├── dist/ # Build output
│ ├── guardian/ # @puaros/guardian - Code quality analyzer
│ │ ├── src/ # Source files (Clean Architecture)
│ │ │ ├── domain/ # Entities, value objects
│ │ │ ├── application/ # Use cases, DTOs
│ │ │ ├── infrastructure/ # Parsers, analyzers
│ │ │ ├── cli/ # CLI implementation
│ │ │ └── shared/ # Shared utilities
│ │ ├── 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
│ ├── tests/ # Test files
│ ├── examples/ # Usage examples
│ └── package.json # Uses Vitest for testing
│ ├── tests/ # Unit and E2E tests
│ └── examples/ # Demo projects
├── pnpm-workspace.yaml # Workspace configuration
└── tsconfig.base.json # Shared TypeScript config
```
@@ -142,6 +157,34 @@ Key features:
- Architecture violation detection
- 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
Base configuration (`tsconfig.base.json`) uses:
@@ -169,19 +212,30 @@ Guardian package (`packages/guardian/tsconfig.json`):
## Dependencies
Guardian package uses:
- `commander` - CLI framework for command-line interface
**Guardian package:**
- `commander` - CLI framework
- `simple-git` - Git operations
- `tree-sitter` - Abstract syntax tree parsing
- `tree-sitter-javascript` - JavaScript parser
- `tree-sitter-typescript` - TypeScript parser
- `tree-sitter` - AST parsing
- `tree-sitter-javascript/typescript` - JS/TS parsers
- `uuid` - UUID generation
Development tools:
- Vitest for testing with coverage thresholds
**ipuaro package:**
- `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
- Prettier for formatting
- `@vitest/ui` - Vitest UI for interactive testing
- Prettier (4-space indentation)
- `@vitest/ui` - Interactive testing UI
- `@vitest/coverage-v8` - Coverage reporting
## 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/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
- Node.js 22.18.0 (use `nvm use` to automatically switch to the correct version)
@@ -75,18 +77,27 @@ pnpm eslint "packages/**/*.ts"
```
puaros/
├── 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)
│ │ ├── domain/ # Domain layer
│ │ ├── application/ # Application layer
│ │ ├── infrastructure/# Infrastructure layer
│ │ ├── cli/ # CLI implementation
│ │ └── shared/ # Shared utilities
│ ├── dist/ # Build output (generated)
│ │ ├── 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
│ ├── tests/ # Unit and integration tests
│ ├── examples/ # Usage examples
│ └── package.json
│ ├── tests/ # Unit and E2E tests
│ └── examples/ # Demo projects
├── pnpm-workspace.yaml # Workspace configuration
├── tsconfig.base.json # Shared TypeScript config
├── 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
```
## 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
Guardian package uses: