puaros/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Puaros is a TypeScript monorepo using pnpm workspaces. Contains two packages:

• @samiyev/guardian - Code quality guardian for detecting hardcoded values, circular dependencies, framework leaks, naming violations, and architecture violations.

• @samiyev/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).

Path Reference

Root: /Users/fozilbeksamiyev/projects/ailabs/puaros

Key Paths

Description	Path
Root	.
Guardian package	packages/guardian
Guardian src	packages/guardian/src
Guardian tests	packages/guardian/tests
Guardian CLI	packages/guardian/src/cli
Guardian domain	packages/guardian/src/domain
Guardian infrastructure	packages/guardian/src/infrastructure
ipuaro package	packages/ipuaro
ipuaro docs	packages/ipuaro/docs

File Locations

File	Location
Root package.json	./package.json
Guardian package.json	packages/guardian/package.json
Guardian tsconfig	packages/guardian/tsconfig.json
Guardian TODO	packages/guardian/TODO.md
Guardian CHANGELOG	packages/guardian/CHANGELOG.md
ipuaro ROADMAP	packages/ipuaro/ROADMAP.md
ESLint config	./eslint.config.mjs
Prettier config	./.prettierrc
Base tsconfig	./tsconfig.base.json

Path Rules

1. Always use relative paths from project root (not absolute)
2. Package paths start with packages/<name>/
3. Source code is in packages/<name>/src/
4. Tests are in packages/<name>/tests/
5. Docs are in packages/<name>/docs/ or ./docs/

Essential Commands

Build & Development

# Build all packages
pnpm build:all

# Clean all builds
pnpm clean:all

# Build specific package
cd packages/guardian && pnpm build

# Watch mode for specific package
cd packages/guardian && pnpm watch

Testing

# Run all tests across packages
pnpm test

# Guardian package testing options
cd packages/guardian
pnpm test              # Run tests in watch mode
pnpm test:run          # Run tests once
pnpm test:coverage     # Generate coverage report (80% threshold)
pnpm test:ui           # Open Vitest UI
pnpm test:watch        # Explicit watch mode

Tests use Vitest with coverage thresholds set to 80% for lines, functions, branches, and statements.

Linting & Formatting

# Format all TypeScript files
pnpm format

# Lint and auto-fix all TypeScript files
pnpm lint

# Check linting without fixing
pnpm eslint "packages/**/*.ts"

Code Style Requirements

Critical: This project uses 4-space indentation, not 2 spaces.

Key Configuration

• Indentation: 4 spaces (enforced by Prettier)
• Line Length: 100 characters max
• Quotes: Double quotes
• Semicolons: Never used
• Trailing Commas: Always in multiline
• TypeScript: Strict type checking with nodenext modules

TypeScript Rules to Follow

From eslint.config.mjs and detailed in LINTING.md:

1. Type Safety (warnings, must address):

   • Avoid any type - use proper typing
   • Declare explicit function return types
   • No floating promises (always await or handle)
   • No unsafe type operations

2. Code Quality (errors, must fix):

   • Use const for non-reassigned variables
   • Always use === instead of ==
   • Always use curly braces for conditionals/loops
   • Handle all promises (no floating promises)
   • No console.log (use console.warn/console.error or proper logger)

3. Complexity Limits (warnings):

   • Max cyclomatic complexity: 15
   • Max function parameters: 5
   • Max lines per function: 100
   • Max nesting depth: 4

4. Comments Style:

   • Single-line comments must have a space after // (e.g., // Comment)
   • Multi-line comments should use JSDoc style (/** */)
   • No section divider comments (e.g., // Entities, // Value Objects) in code
   • Comments should explain "why", not "what" (code should be self-documenting)
   • TODO/FIXME/HACK comments trigger warnings

Git Commit Format

Follow Conventional Commits format. See .gitmessage for full rules.

Monorepo format: <type>(<package>): <subject>

Examples:

• feat(guardian): add circular dependency detector
• fix(ipuaro): resolve memory leak in indexer
• docs(guardian): update CLI usage examples
• refactor(ipuaro): extract tool registry

Root-level changes: <type>: <subject> (no scope)

• chore: update eslint config
• docs: update root README

Types: feat, fix, docs, style, refactor, test, chore

Rules:

• Imperative mood, no caps, max 50 chars
• Do NOT add "Generated with Claude Code" footer
• Do NOT add "Co-Authored-By: Claude"

Monorepo Structure

puaros/
├── packages/
│   ├── guardian/                # @samiyev/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/                  # @samiyev/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/               # Unit and E2E tests
│       └── examples/            # Demo projects
├── pnpm-workspace.yaml          # Workspace configuration
└── tsconfig.base.json           # Shared TypeScript config

Guardian Package Architecture

The guardian package follows Clean Architecture principles:

• Domain Layer: Core business logic (entities, value objects, domain events)
• Application Layer: Use cases, DTOs, and mappers
• Infrastructure Layer: External concerns (parsers, analyzers, file scanners)
• CLI Layer: Command-line interface implementation

Key features:

• Hardcode detection (magic numbers, strings)
• Circular dependency detection
• Framework leak detection (domain importing frameworks)
• Naming convention validation
• 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:

• Module: nodenext with nodenext resolution
• Target: ES2023
• Strict null checks enabled
• Decorators enabled (experimental)
• JSX configured for React

Guardian package (packages/guardian/tsconfig.json):

• Module: CommonJS
• Module Resolution: node
• Target: ES2023
• Output to dist/ from src/
• Strict type checking enabled

Important: The guardian package uses CommonJS output for compatibility.

Adding New Packages

1. Create packages/new-package/ directory
2. Add package.json with name @samiyev/new-package
3. Create tsconfig.json extending ../../tsconfig.base.json
4. Package auto-discovered via pnpm-workspace.yaml glob pattern

Dependencies

Guardian package:

• commander - CLI framework
• simple-git - Git operations
• tree-sitter - AST parsing
• tree-sitter-javascript/typescript - JS/TS parsers
• uuid - UUID generation

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 (4-space indentation)
• @vitest/ui - Interactive testing UI
• @vitest/coverage-v8 - Coverage reporting

Monorepo Versioning Strategy

Git Tag Format

Prefixed tags for each package:

guardian-v0.5.0
ipuaro-v0.1.0

Why prefixed tags:

• Independent versioning per package
• Clear release history for each package
• Works with npm publish and CI/CD
• Easy to filter: git tag -l "guardian-*"

Legacy tags: Tags before monorepo (v0.1.0, v0.2.0, etc.) are kept as-is for historical reference.

Semantic Versioning

All packages follow SemVer: MAJOR.MINOR.PATCH

• MAJOR (1.0.0) - Breaking API changes
• MINOR (0.1.0) - New features, backwards compatible
• PATCH (0.0.1) - Bug fixes, backwards compatible

Pre-1.0 policy: Minor bumps (0.x.0) may include breaking changes.

Release Pipeline

Quick reference: Say "run pipeline for [package]" to execute full release flow.

The pipeline has 6 phases. Each phase must pass before proceeding.

Phase 1: Quality Gates

cd packages/<package>

# All must pass:
pnpm format                              # 4-space indentation
pnpm build                               # TypeScript compiles
cd ../.. && pnpm eslint "packages/**/*.ts" --fix  # 0 errors, 0 warnings
cd packages/<package>
pnpm test:run                            # All tests pass
pnpm test:coverage                       # Coverage ≥80%

Phase 2: Documentation

Update these files in packages/<package>/:

File	Action
README.md	Add feature docs, update CLI usage, update API
TODO.md	Mark completed tasks, add new tech debt if any
CHANGELOG.md	Add version entry with all changes
ROADMAP.md	Update if milestone completed

Tech debt rule: If implementation leaves known issues, shortcuts, or future improvements needed — add them to TODO.md before committing.

Phase 3: Manual Testing

cd packages/<package>

# Test CLI/API manually
node dist/cli/index.js <command> ./examples

# Verify output, edge cases, error handling

Phase 4: Commit

git add .
git commit -m "<type>(<package>): <description>"

# Examples:
# feat(guardian): add --limit option
# fix(ipuaro): resolve memory leak in indexer
# docs(guardian): update API examples

Commit types: feat, fix, docs, style, refactor, test, chore

Phase 5: Version & Tag

cd packages/<package>

# Bump version
npm version patch  # 0.5.2 → 0.5.3 (bug fix)
npm version minor  # 0.5.2 → 0.6.0 (new feature)
npm version major  # 0.5.2 → 1.0.0 (breaking change)

# Create prefixed git tag
git tag <package>-v<version>
# Example: git tag guardian-v0.6.0

# Push
git push origin main
git push origin <package>-v<version>

Phase 6: Publish (Maintainers Only)

cd packages/<package>

# Final verification
pnpm build && pnpm test:run && pnpm test:coverage

# Check package contents
npm pack --dry-run

# Publish
npm publish --access public

# Verify
npm info @samiyev/<package>

Pipeline Checklist

Copy and use for each release:

## Release: <package> v<version>

### Quality Gates
- [ ] `pnpm format` - no changes
- [ ] `pnpm build` - compiles
- [ ] `pnpm eslint` - 0 errors, 0 warnings
- [ ] `pnpm test:run` - all pass
- [ ] `pnpm test:coverage` - ≥80%

### Documentation
- [ ] README.md updated
- [ ] TODO.md - completed tasks marked, new debt added
- [ ] CHANGELOG.md - version entry added
- [ ] ROADMAP.md updated (if needed)

### Testing
- [ ] CLI/API tested manually
- [ ] Edge cases verified

### Release
- [ ] Commit with conventional format
- [ ] Version bumped in package.json
- [ ] Git tag created: <package>-v<version>
- [ ] Pushed to origin
- [ ] Published to npm (if public release)

Working with Roadmap

When the user points to ROADMAP.md or asks about the roadmap/next steps:

1. Read both files together:

   • packages/<package>/ROADMAP.md - to understand the planned features and milestones
   • packages/<package>/CHANGELOG.md - to see what's already implemented

2. Determine current position:

   • Check the latest version in CHANGELOG.md
   • Cross-reference with ROADMAP.md milestones
   • Identify which roadmap items are already completed (present in CHANGELOG)

3. Suggest next steps:

   • Find the first uncompleted item in the current milestone
   • Or identify the next milestone if current one is complete
   • Present clear "start here" recommendation

Example workflow:

User: "Let's work on the roadmap" or points to ROADMAP.md

Claude should:
1. Read ROADMAP.md → See milestones v0.1.0, v0.2.0, v0.3.0...
2. Read CHANGELOG.md → See latest release is v0.1.1
3. Compare → v0.1.0 milestone complete, v0.2.0 in progress
4. Report → "v0.1.0 is complete. For v0.2.0, next item is: <feature>"

Common Workflows

Adding a new CLI option

# 1. Add to cli/constants.ts (CLI_OPTIONS, CLI_DESCRIPTIONS)
# 2. Add option in cli/index.ts (.option() call)
# 3. Parse and use option in action handler
# 4. Test: node dist/cli/index.js <command> --your-option
# 5. Run pipeline

Adding a new detector (guardian)

# 1. Create value object in domain/value-objects/
# 2. Create detector in infrastructure/analyzers/
# 3. Add interface to domain/services/
# 4. Integrate in application/use-cases/AnalyzeProject.ts
# 5. Add CLI output in cli/index.ts
# 6. Write tests (aim for >90% coverage)
# 7. Run pipeline

Adding a new tool (ipuaro)

# 1. Define tool schema in infrastructure/tools/schemas/
# 2. Implement tool in infrastructure/tools/
# 3. Register in infrastructure/tools/index.ts
# 4. Add tests
# 5. Run pipeline

Fixing technical debt

# 1. Find issue in TODO.md
# 2. Implement fix
# 3. Update TODO.md (mark as completed)
# 4. Run pipeline with type: "refactor:" or "fix:"

Debugging Tips

Build errors:

pnpm tsc --noEmit
pnpm tsc --noEmit packages/<package>/src/path/to/file.ts

Test failures:

pnpm vitest tests/path/to/test.test.ts
pnpm test:ui

Coverage issues:

pnpm test:coverage
open coverage/index.html

Important Notes

• Always run pnpm format before committing to ensure 4-space indentation
• Fix ESLint warnings incrementally - they indicate real type safety issues
• Coverage is enforced - maintain 80% coverage for all metrics when running pnpm test:coverage
• Test CLI manually - automated tests don't cover CLI output formatting
• Update documentation - README.md and TODO.md should always reflect current state
• Follow Clean Architecture - keep layers separate and dependencies flowing inward