🐝 Ruch CLI

Revolutionary React Development with Hexagonal Architecture & AI-Powered Assistance

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)

npx ruch create user

Global Installation

# 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

# 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:

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

# 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

npx ruch list
# or
npx ruch ls

delete <domain> - Delete Domain

# 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

# 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

# Add missing domains to existing context
npx ruch context update

🧪 Mock Service Worker (MSW)

msw init - Initialize MSW

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

# Generate MSW handlers for all domains
npx ruch msw handlers

msw mocks - Generate Mock Data

# Generate realistic mock data templates
npx ruch msw mocks

msw update - Update MSW Configuration

# 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.

# 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:

// 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:

// 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

# 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

# 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

# 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

# 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

# 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)

describe('User Entity', () => {
  it('should create valid user', () => {
    const user = User.create({
      email: '[email protected]',
      name: 'John Doe',
    });

    expect(user.id).toBeDefined();
    expect(user.email).toBe('[email protected]');
  });
});

⚙️ Service Testing (With Mock Ports)

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)

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)

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)

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

# 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

# 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

# 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

# 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)

# 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

# .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 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 [email protected]

📄 License

MIT License - see 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!

🚀 Transform Your React Development Today

Get Started • Documentation • Examples • Community