ruch
Version:
Revolutionary React TypeScript CLI with hexagonal architecture & AI-powered development assistance. Create maintainable, scalable applications with domain-driven design and integrated AI tooling.
733 lines (536 loc) • 19.8 kB
Markdown
# 🐝 Ruch CLI
> **Revolutionary React Development with Hexagonal Architecture & AI-Powered Assistance**
[](https://badge.fury.io/js/ruch)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](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>