# 🐝 Ruch CLI

> **Revolutionary React Development with Hexagonal Architecture & AI-Powered Assistance**

[![npm version](https://badge.fury.io/js/ruch.svg)](https://badge.fury.io/js/ruch)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-1.0+-orange.svg)](https://bun.sh/)

**Ruch CLI** is a revolutionary command-line tool that transforms React TypeScript development by implementing clean hexagonal architecture principles while providing unprecedented AI-powered assistance for consistent, maintainable code generation.

## ✨ Key Features

### 🏗️ **Hexagonal Architecture Made Simple**

- **Complete domain structure** generation with entities, ports, services, adapters, hooks, and UI
- **Dependency inversion** patterns built-in
- **Domain isolation** with clear boundaries
- **Co-located testing** strategy

### 🤖 **AI-Powered Development (Flagship Feature)**

- **Revolutionary guide-ai** command that teaches AI assistants your architecture
- **Tool-specific configurations** for Cursor, GitHub Copilot, Windsurf, and Juni
- **Consistent code generation** that respects hexagonal boundaries
- **Architecture-aware suggestions** from AI tools

### 🧪 **Advanced Testing with MSW**

- **Realistic API simulation** with Mock Service Worker
- **Automatic handler generation** for all domains
- **Domain-isolated testing** strategies
- **Co-located test patterns**

### 📊 **Project Visualization**

- **Interactive dependency graphs** with circular dependency detection
- **Architecture health insights** and metrics
- **Real-time visualization** of domain relationships

## 🚀 Quick Start

### Installation

**Using npx (Recommended)**

```bash
npx ruch create user
```

**Global Installation**

```bash
# Using Bun (Recommended)
bun install -g ruch

# Using npm
npm install -g ruch

# Using yarn
yarn global add ruch

# Using pnpm
pnpm install -g ruch
```

### 5-Minute Setup

```bash
# 1. Create your first domain
npx ruch create user

# 2. Generate service context with dependency injection
npx ruch context generate

# 3. Set up realistic testing with MSW
npx ruch msw init
npx ruch msw handlers
npx ruch msw mocks

# 4. Enable AI-powered development (FLAGSHIP)
npx ruch guide-ai

# 5. Visualize your architecture
npx ruch visualize
```

**Result:** Complete React application with hexagonal architecture, comprehensive testing setup, and AI documentation ready for development.

## 📚 Core Concepts

### 🏛️ Hexagonal Architecture Layers

Ruch CLI implements a simplified hexagonal architecture specifically designed for React applications:

```mermaid
graph TD
    A[UI Components] --> B[Hooks]
    B --> C[Services]
    C --> D[Ports]
    D --> E[Adapters]
    E --> F[External APIs]

    G[Entities] --> C
    H[Tests] --> C
    H --> E
```

| Layer           | Description       | Location    | Responsibilities                                   |
| --------------- | ----------------- | ----------- | -------------------------------------------------- |
| **🏛️ Entities** | Business models   | `entities/` | Data structures, domain types, validation rules    |
| **⚙️ Services** | Business logic    | `services/` | Pure business logic, domain operations, validation |
| **🔌 Ports**    | Abstractions      | `ports/`    | Interfaces for external dependencies               |
| **🔧 Adapters** | Implementations   | `adapters/` | API calls, external service implementations        |
| **⚛️ Hooks**    | React integration | `hooks/`    | React Query hooks, state management                |
| **🎨 UI**       | Presentation      | `ui/`       | React components, user interactions                |

### 🎯 Architecture Principles

1. **Business Logic Isolation** - ALL business logic MUST be in domain services
2. **No Direct Service Imports** - Components ALWAYS use domain hooks
3. **Cross-Domain Communication** - Only via ports/adapters patterns
4. **Co-Located Tests** - Tests alongside implementation files
5. **Dependency Inversion** - High-level modules don't depend on low-level modules

## 🛠️ CLI Commands Reference

### 🏗️ Domain Management

#### `create <domain>` - Create New Domain

```bash
# Create complete domain with hexagonal structure
npx ruch create user

# Create domain without UI components
npx ruch create analytics --without-ui

# Create API-only domain
npx ruch create notification --without-ui --without-store
```

#### `list` - List All Domains

```bash
npx ruch list
# or
npx ruch ls
```

#### `delete <domain>` - Delete Domain

```bash
# Safe delete with confirmation
npx ruch delete user

# Force delete without confirmation
npx ruch delete user --force
```

### ⚙️ Service Context Management

#### `context generate` - Generate Service Context

```bash
# Generate complete service context with dependency injection
npx ruch context generate
```

Creates `src/context/ServiceContext.tsx` with:

- Service instantiation for all domains
- React Context Provider
- `useServices` hook
- TypeScript interfaces
- Complete test coverage

#### `context update` - Update Context

```bash
# Add missing domains to existing context
npx ruch context update
```

### 🧪 Mock Service Worker (MSW)

#### `msw init` - Initialize MSW

```bash
npx ruch msw init
```

Creates:

- `src/mocks/browser.ts` - Browser MSW setup
- `src/mocks/server.ts` - Node.js MSW setup
- `src/setupTests.ts` - Test configuration
- `public/mockServiceWorker.js` - Service worker

#### `msw handlers` - Generate Handlers

```bash
# Generate MSW handlers for all domains
npx ruch msw handlers
```

#### `msw mocks` - Generate Mock Data

```bash
# Generate realistic mock data templates
npx ruch msw mocks
```

#### `msw update` - Update MSW Configuration

```bash
# Update MSW for new domains
npx ruch msw update

# Update specific domain
npx ruch msw update user
```

### 🤖 AI-Powered Development

#### `guide-ai` - Generate AI Documentation ⭐ **FLAGSHIP FEATURE**

Transform your development workflow by teaching AI assistants to understand and respect your hexagonal architecture.

```bash
# Generate complete AI documentation
npx ruch guide-ai

# Configure specific AI tools
npx ruch guide-ai --tools cursor,copilot,windsurf,juni

# Configure single tool
npx ruch guide-ai --tools cursor
```

**What guide-ai Creates:**

| File                | Purpose                       | AI Tool   |
| ------------------- | ----------------------------- | --------- |
| `ruch-guide.json`   | Complete project mapping      | All tools |
| `GUIDE.md`          | Human-readable documentation  | All tools |
| `.cursorrules`      | Cursor-specific configuration | Cursor    |
| `.windsurfrules`    | Windsurf configuration        | Windsurf  |
| `.juni/config.json` | Juni integration              | Juni      |

**Before guide-ai:**

```typescript
// AI generates this (WRONG)
import { UserService } from '../domains/user/services';

function MyComponent() {
  const userService = new UserService(); // ❌ Direct instantiation
  const users = userService.getUsers(); // ❌ Blocking call
  return <div>{users.map(...)}</div>;
}
```

**After guide-ai:**

```typescript
// AI generates this (CORRECT)
import { useUsers } from '../domains/user/hooks';

function MyComponent() {
  const { data: users, isLoading, error } = useUsers(); // ✅ Proper hook usage

  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;

  return <div>{users?.map(...)}</div>;
}
```

### 📊 Visualization & Analysis

#### `visualize` - Interactive Dependency Visualization

```bash
# Launch interactive visualization app
npx ruch visualize

# Custom port
npx ruch visualize --port 4000

# Export to JSON
npx ruch visualize --format json --output architecture.json

# Console output
npx ruch visualize --format console

# Don't auto-open browser
npx ruch visualize --no-open
```

#### `http-client` - Generate HTTP Client

```bash
# Generate configured HTTP client with interceptors
npx ruch http-client
```

## 🏗️ Generated Project Structure

When you create a domain, Ruch generates a complete hexagonal structure:

```
src/domains/user/
├── entities/
│   ├── User.ts              # Business models and types
│   ├── UserProfile.ts       # Related entities
│   ├── index.ts             # Barrel exports
│   └── User.test.ts         # Entity tests
├── ports/
│   ├── UserRepository.ts    # Abstraction interfaces
│   ├── index.ts             # Port exports
│   └── UserRepository.test.ts
├── services/
│   ├── UserService.ts       # Pure business logic
│   ├── index.ts             # Service exports
│   └── UserService.test.ts  # Service tests (with mocked ports)
├── adapters/
│   ├── UserApiAdapter.ts    # API implementation
│   ├── index.ts             # Adapter exports
│   └── UserApiAdapter.test.ts # Adapter tests (with MSW)
├── hooks/
│   ├── useUsers.ts          # React Query hooks
│   ├── useCreateUser.ts     # Mutation hooks
│   ├── index.ts             # Hook exports
│   └── useUsers.test.ts     # Hook tests (with MSW)
├── ui/
│   ├── UserList.tsx         # Domain components
│   ├── UserCard.tsx         # Related components
│   ├── index.ts             # UI exports
│   └── UserList.test.tsx    # Component tests (integration)
└── index.ts                 # Domain entry point
```

## 🎯 Usage Workflows

### 🚀 New Project Setup

```bash
# 1. Create core domains
npx ruch create user
npx ruch create product
npx ruch create order

# 2. Generate service context with dependency injection
npx ruch context generate

# 3. Set up comprehensive testing
npx ruch msw init
npx ruch msw handlers
npx ruch msw mocks

# 4. Enable AI-powered development (FLAGSHIP)
npx ruch guide-ai

# 5. Visualize architecture
npx ruch visualize
```

### 🔄 Incremental Development

```bash
# Add new domain
npx ruch create payment

# Update existing configurations
npx ruch context update
npx ruch msw update

# Refresh AI documentation
npx ruch guide-ai

# Verify architecture
npx ruch visualize
```

### 🏢 Enterprise Development Workflow

```bash
# Create multiple business domains
npx ruch create user
npx ruch create product
npx ruch create inventory
npx ruch create order
npx ruch create payment
npx ruch create notification

# Generate complete infrastructure
npx ruch context generate
npx ruch msw init
npx ruch msw handlers
npx ruch msw mocks
npx ruch http-client

# Enable AI assistance for team development
npx ruch guide-ai --tools cursor,copilot,windsurf,juni

# Monitor architecture health
npx ruch visualize --format console
```

## 🧪 Testing Strategy

Ruch CLI implements a comprehensive testing strategy across all architectural layers:

### 🏛️ Entity Testing (Pure)

```typescript
describe('User Entity', () => {
  it('should create valid user', () => {
    const user = User.create({
      email: 'john@example.com',
      name: 'John Doe',
    });

    expect(user.id).toBeDefined();
    expect(user.email).toBe('john@example.com');
  });
});
```

### ⚙️ Service Testing (With Mock Ports)

```typescript
describe('UserService', () => {
  it('should create user with valid data', async () => {
    const mockRepository = createMockUserRepository();
    const userService = new UserService(mockRepository);

    const result = await userService.createUser(userData);

    expect(result.email).toBe(userData.email);
    expect(mockRepository.save).toHaveBeenCalled();
  });
});
```

### 🔧 Adapter Testing (With MSW)

```typescript
describe('UserApiAdapter', () => {
  it('should save user via API', async () => {
    server.use(
      http.post('/api/users', () => {
        return HttpResponse.json(mockUser);
      })
    );

    const result = await adapter.save(userData);
    expect(result.id).toBe('generated-id');
  });
});
```

### ⚛️ Hook Testing (With MSW)

```typescript
describe('useUsers', () => {
  it('should fetch users successfully', async () => {
    const { result } = renderHook(() => useUsers(), {
      wrapper: createTestWrapper(),
    });

    await waitFor(() => {
      expect(result.current.isSuccess).toBe(true);
    });
  });
});
```

### 🎨 Component Testing (Integration)

```typescript
describe('UserList', () => {
  it('should display list of users', async () => {
    render(<UserList />, { wrapper: createTestWrapper() });

    await waitFor(() => {
      expect(screen.getByText('Users')).toBeInTheDocument();
    });
  });
});
```

## 🛠️ Development

### System Requirements

- **Node.js**: 18.0 or higher
- **Package Manager**: Bun (recommended), npm, yarn, or pnpm
- **Operating System**: Windows, macOS, or Linux
- **TypeScript**: 4.9 or higher

### Local Development Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/ruch.git
cd ruch

# Install dependencies with Bun (recommended)
bun install

# Build the project
bun run build

# Make executable for local testing
chmod +x dist/index.js

# Test local installation
./dist/index.js --version
```

### Available Scripts

```bash
# Build the project
bun run build

# Run comprehensive test suite
bun test

# Run tests in watch mode
bun test --watch

# Lint code with ESLint
bun run lint

# Format code with Prettier
bun run format

# Type checking
bun run type-check

# Run all quality checks
bun run quality
```

### Project Structure

```
ruch/
├── src/
│   ├── commands/          # CLI command implementations
│   │   ├── create.ts      # Domain creation
│   │   ├── context.ts     # Service context management
│   │   ├── msw.ts         # MSW configuration
│   │   ├── guide-ai.ts    # AI documentation (flagship)
│   │   └── visualize.ts   # Architecture visualization
│   ├── services/          # Internal CLI services
│   ├── templates/         # Code generation templates
│   ├── utils/             # Shared utilities
│   └── index.ts           # CLI entry point
├── tests/                 # Comprehensive test suite
├── templates/             # Domain templates
└── docs/                  # Additional documentation
```

## 🎯 Best Practices

### 🏗️ Domain Design

- **Keep domains focused** and cohesive around business capabilities
- **Avoid domain dependencies** - use events for cross-domain communication
- **Define clear boundaries** - each domain should be independently deployable
- **Use consistent naming** - follow established conventions across domains

### 🔧 Code Organization

- **Co-locate tests** with implementation files
- **Use barrel exports** (`index.ts`) for clean imports
- **Follow naming conventions** - consistent across all domains
- **Separate concerns** between architectural layers

### 🧪 Testing Philosophy

- **Test each layer in isolation** with appropriate mocking strategies
- **Use MSW for realistic API testing** instead of basic mocks
- **Write integration tests** for complete user flows
- **Mock external dependencies** at the adapter layer

### 🤖 AI Development Workflow

- **Always regenerate guide-ai** after creating new domains
- **Keep AI documentation current** with architectural changes
- **Use consistent patterns** that AI can learn and replicate
- **Leverage AI for boilerplate** generation while maintaining quality

## 🌟 Real-World Examples

### E-Commerce Application

```bash
# Create complete e-commerce domain structure
npx ruch create user          # User authentication & management
npx ruch create product       # Product catalog & inventory
npx ruch create cart          # Shopping cart functionality
npx ruch create order         # Order processing & tracking
npx ruch create payment       # Payment processing
npx ruch create notification  # Email & SMS notifications

# Generate infrastructure
npx ruch context generate
npx ruch msw init
npx ruch msw handlers
npx ruch msw mocks

# Enable AI-powered development for team
npx ruch guide-ai --tools cursor,copilot,windsurf,juni

# Verify architecture integrity
npx ruch visualize
```

### SaaS Platform

```bash
# Create multi-tenant SaaS domains
npx ruch create tenant        # Multi-tenancy management
npx ruch create user          # User & role management
npx ruch create subscription  # Billing & subscriptions
npx ruch create analytics     # Usage analytics
npx ruch create support       # Customer support
npx ruch create integration   # Third-party integrations

# Full setup
npx ruch context generate
npx ruch msw init && npx ruch msw handlers && npx ruch msw mocks
npx ruch guide-ai
npx ruch visualize --format console
```

## 🔧 Advanced Configuration

### Custom Templates (Coming Soon)

```bash
# Use custom domain templates
npx ruch create user --template enterprise

# Generate with custom configurations
npx ruch create product --config ./ruch.config.js
```

### CI/CD Integration

```yaml
# .github/workflows/architecture-check.yml
name: Architecture Health Check
on: [push, pull_request]

jobs:
  architecture-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install -g ruch
      - run: ruch visualize --format console
      - run: ruch guide-ai --tools cursor # Keep AI docs updated
```

## 🚨 Important Considerations

### MSW Customization Required

**⚠️ CRITICAL:** All generated MSW handlers and mock data are **templates** and **MUST** be customized for your specific API and business logic.

**Recommended MSW Workflow:**

1. **Initialize**: `npx ruch msw init`
2. **Generate templates**: `npx ruch msw handlers && npx ruch msw mocks`
3. **🔥 CUSTOMIZE**: Adapt endpoints, authentication, validation, business data
4. **Test thoroughly**: Verify MSW setup with your application
5. **Maintain**: Use `npx ruch msw update` when domains change

### Architecture Rules (Enforced by guide-ai)

1. **Business Logic Isolation**: ALL business logic MUST be in domain services
2. **No Direct Service Imports**: Components ALWAYS use domain hooks
3. **Cross-Domain Communication**: Only via ports/adapters or events
4. **Co-Located Tests**: Tests MUST be alongside implementation files
5. **Dependency Direction**: Inner layers never depend on outer layers

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow

1. **Fork & Clone**: Fork the repository and clone your fork
2. **Create Branch**: `git checkout -b feature/your-feature-name`
3. **Develop**: Make your changes with tests
4. **Test**: `bun test` - ensure all tests pass
5. **Quality Check**: `bun run quality` - linting, formatting, type checking
6. **Commit**: Use conventional commits
7. **Push & PR**: Push to your fork and create a pull request

### Reporting Issues

- **Bug Reports**: Use the bug report template
- **Feature Requests**: Use the feature request template
- **Security Issues**: Email security@ruch.dev

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🏆 Recognition

Built with ❤️ for the React community by developers who believe in clean architecture and AI-assisted development.

**Star ⭐ this repository if you find it helpful!**

---

<div align="center">

### 🚀 Transform Your React Development Today

[Get Started](#-quick-start) • [Documentation](https://docs.ruch.dev) • [Examples](https://github.com/ruch-cli/examples) • [Community](https://discord.gg/ruch)

</div>