ruch/Ruch CLI Documentation.json

Revolutionary React TypeScript CLI with hexagonal architecture & AI-powered development assistance. Create maintainable, scalable applications with domain-driven design and integrated AI tooling.

{
  "project": {
    "name": "Ruch CLI",
    "description": "Revolutionary tool for building React TypeScript applications with hexagonal architecture principles",
    "version": "1.0.0"
  },
  "overview": {
    "title": "Ruch CLI - Revolutionary React Development Tool",
    "description": "Command-line tool for building React TypeScript applications with hexagonal architecture",
    "features": [
      "🏗️ Build clean architecture",
      "🤖 AI-powered development",
      "🧪 Comprehensive testing",
      "📦 Domain-driven design"
    ],
    "architecturePrinciples": [
      "Business logic isolation - ALL business logic MUST be in domains",
      "No direct service imports - Always use domain hooks",
      "Cross-domain communication - Only via ports/adapters",
      "Co-located tests - Tests alongside implementation files"
    ],
    "quickStart": {
      "commands": [
        "npx ruch create user",
        "npx ruch context generate",
        "npx ruch guide-ai"
      ],
      "benefits": [
        "Complete domain structure with entities, ports, services",
        "React Query hooks for data fetching",
        "MSW handlers for testing",
        "AI-ready documentation",
        "Service context with dependency injection"
      ]
    }
  },
  "installation": {
    "quickStart": "npx ruch create user",
    "globalInstallation": [
      {
        "name": "Using Bun (Recommended)",
        "command": "bun install -g ruch"
      },
      {
        "name": "Using npm",
        "command": "npm install -g ruch"
      },
      {
        "name": "Using yarn",
        "command": "yarn global add ruch"
      },
      {
        "name": "Using pnpm",
        "command": "pnpm install -g ruch"
      }
    ],
    "systemRequirements": [
      "Node.js: 18.0 or higher",
      "Package Manager: Bun (recommended), npm, yarn, or pnpm",
      "Operating System: Windows, macOS, or Linux"
    ]
  },
  "commands": {
    "domain": {
      "create": {
        "syntax": "npx ruch create <domain-name>",
        "description": "Create a new domain with hexagonal structure",
        "generates": [
          "src/domains/{domain}/entities/",
          "src/domains/{domain}/ports/",
          "src/domains/{domain}/services/",
          "src/domains/{domain}/adapters/",
          "src/domains/{domain}/hooks/",
          "src/domains/{domain}/ui/"
        ],
        "example": "npx ruch create user"
      },
      "list": {
        "syntax": "npx ruch list",
        "description": "List all existing domains",
        "alias": "npx ruch ls"
      },
      "delete": {
        "syntax": "npx ruch delete <domain-name>",
        "description": "Delete an existing domain",
        "flags": ["--force"],
        "example": "npx ruch delete user --force"
      }
    },
    "context": {
      "init": {
        "syntax": "npx ruch context init",
        "description": "Initialize empty service context"
      },
      "generate": {
        "syntax": "npx ruch context generate",
        "description": "Generate complete service context with all domains",
        "creates": "src/context/ServiceContext.tsx"
      },
      "update": {
        "syntax": "npx ruch context update",
        "description": "Update context with missing domains"
      }
    },
    "msw": {
      "init": {
        "syntax": "npx ruch msw init",
        "description": "Initialize MSW configuration",
        "creates": [
          "src/mocks/browser.ts",
          "src/mocks/server.ts",
          "src/setupTests.ts",
          "public/mockServiceWorker.js"
        ]
      },
      "handlers": {
        "syntax": "npx ruch msw handlers",
        "description": "Generate MSW handlers for all domains",
        "creates": "src/mocks/handlers/"
      },
      "mocks": {
        "syntax": "npx ruch msw mocks",
        "description": "Generate mock data templates",
        "creates": ["src/mocks/data/", "src/mocks/factories/"]
      },
      "update": {
        "syntax": "npx ruch msw update",
        "description": "Update MSW configuration for new domains"
      }
    },
    "ai": {
      "guide-ai": {
        "syntax": "npx ruch guide-ai [--tools tool1,tool2]",
        "description": "Generate AI documentation (FLAGSHIP FEATURE)",
        "flagship": true,
        "tools": ["cursor", "copilot", "windsurf", "juni"],
        "creates": [
          "ruch-guide.json",
          "GUIDE.md",
          ".cursorrules",
          ".windsurfrules",
          ".juni/config.json"
        ],
        "examples": [
          "npx ruch guide-ai",
          "npx ruch guide-ai --tools cursor",
          "npx ruch guide-ai --tools cursor,copilot,windsurf,juni"
        ]
      }
    },
    "utils": {
      "visualize": {
        "syntax": "npx ruch visualize [--format format]",
        "description": "Interactive dependency visualization",
        "formats": ["interactive", "console", "json"]
      },
      "http-client": {
        "syntax": "npx ruch http-client",
        "description": "Generate HTTP client configuration"
      }
    }
  },
  "architectureLayers": {
    "entities": {
      "emoji": "🏛️",
      "title": "Entities (Core)",
      "description": "Business models and data structures",
      "location": "src/domains/{domain}/entities/",
      "responsibilities": [
        "Define business data structures",
        "Contain domain-specific types",
        "Include basic validation rules",
        "No dependencies on other layers"
      ],
      "example": "export interface User {\n  readonly id: UserId;\n  readonly email: Email;\n  readonly profile: UserProfile;\n  readonly createdAt: Date;\n}\n\nexport type UserId = string & { readonly brand: unique symbol };"
    },
    "services": {
      "emoji": "⚙️",
      "title": "Services (Core)",
      "description": "Pure business logic",
      "location": "src/domains/{domain}/services/",
      "responsibilities": [
        "Implement business logic",
        "Orchestrate domain operations",
        "Contain validation and business rules",
        "Depend only on entities and ports"
      ],
      "example": "export class UserService {\n  constructor(private userRepository: UserRepository) {}\n\n  async createUser(request: CreateUserRequest): Promise<User> {\n    this.validateUserRequest(request);\n    const user = this.createUserEntity(request);\n    return this.userRepository.save(user);\n  }\n}"
    },
    "ports": {
      "emoji": "🔌",
      "title": "Ports (Abstraction)",
      "description": "Abstraction interfaces",
      "location": "src/domains/{domain}/ports/",
      "responsibilities": [
        "Define contracts for external dependencies",
        "Enable dependency inversion",
        "Allow easy testing with mocks",
        "No implementation details"
      ],
      "example": "export interface UserRepository {\n  save(user: User): Promise<User>;\n  findById(id: UserId): Promise<User | null>;\n  findByEmail(email: Email): Promise<User | null>;\n}"
    },
    "adapters": {
      "emoji": "🔧",
      "title": "Adapters (Implementation)",
      "description": "Concrete implementations",
      "location": "src/domains/{domain}/adapters/",
      "responsibilities": [
        "Implement port interfaces",
        "Handle external API calls",
        "Transform external data to domain models",
        "Depend on ports and entities"
      ],
      "example": "export class UserApiAdapter implements UserRepository {\n  async save(user: User): Promise<User> {\n    const response = await fetch('/api/users', {\n      method: 'POST',\n      body: JSON.stringify(this.userToDto(user))\n    });\n    return this.dtoToUser(await response.json());\n  }\n}"
    },
    "hooks": {
      "emoji": "⚛️",
      "title": "Hooks (React Integration)",
      "description": "React Query integration",
      "location": "src/domains/{domain}/hooks/",
      "responsibilities": [
        "Bridge between React and domain services",
        "Integrate with React Query for caching",
        "Handle loading/error states",
        "Depend on services and adapters"
      ],
      "example": "export function useUsers() {\n  const { userService } = useServices();\n  \n  return useQuery({\n    queryKey: ['users'],\n    queryFn: () => userService.getAllUsers()\n  });\n}"
    },
    "ui": {
      "emoji": "🎨",
      "title": "UI (React Components)",
      "description": "Presentation layer",
      "location": "src/domains/{domain}/ui/",
      "responsibilities": [
        "Present data to users",
        "Handle user interactions",
        "Only use domain hooks, never services directly",
        "Focus purely on presentation logic"
      ],
      "example": "export function UserList() {\n  const { data: users, isLoading } = useUsers();\n  \n  if (isLoading) return <Spinner />;\n  \n  return (\n    <div>\n      {users?.map(user => (\n        <UserCard key={user.id} user={user} />\n      ))}\n    </div>\n  );\n}"
    }
  },
  "workflows": {
    "newProject": {
      "title": "🚀 Complete Project Setup",
      "steps": [
        {
          "step": 1,
          "command": "npx ruch create user",
          "description": "Create user domain"
        },
        {
          "step": 2,
          "command": "npx ruch create product",
          "description": "Create product domain"
        },
        {
          "step": 3,
          "command": "npx ruch context generate",
          "description": "Generate service context"
        },
        {
          "step": 4,
          "command": "npx ruch msw init",
          "description": "Initialize MSW"
        },
        {
          "step": 5,
          "command": "npx ruch msw handlers",
          "description": "Generate handlers"
        },
        {
          "step": 6,
          "command": "npx ruch guide-ai",
          "description": "Enable AI development (FLAGSHIP)"
        }
      ]
    },
    "addDomain": {
      "title": "🔄 Incremental Development",
      "steps": [
        {
          "step": 1,
          "command": "npx ruch create payment",
          "description": "Add new domain"
        },
        {
          "step": 2,
          "command": "npx ruch context update",
          "description": "Update configurations"
        },
        {
          "step": 3,
          "command": "npx ruch msw update",
          "description": "Update MSW for new domain"
        },
        {
          "step": 4,
          "command": "npx ruch guide-ai",
          "description": "Refresh AI documentation"
        }
      ]
    }
  },
  "testingStrategy": {
    "layers": [
      {
        "name": "Entity Testing",
        "description": "Test entities in isolation",
        "tools": ["Jest", "TypeScript"],
        "location": "*.test.ts files"
      },
      {
        "name": "Service Testing",
        "description": "Test business logic with mocked dependencies",
        "tools": ["Jest", "Mock repositories"],
        "location": "services/*.test.ts"
      },
      {
        "name": "Adapter Testing",
        "description": "Test API adapters with MSW",
        "tools": ["MSW", "Jest"],
        "location": "adapters/*.test.ts"
      },
      {
        "name": "Hook Testing",
        "description": "Test React Query hooks",
        "tools": ["React Testing Library", "MSW"],
        "location": "hooks/*.test.ts"
      },
      {
        "name": "Component Testing",
        "description": "Test complete user flows",
        "tools": ["React Testing Library", "MSW", "Jest"],
        "location": "ui/*.test.tsx"
      }
    ]
  },
  "aiIntegration": {
    "title": "AI-Powered Development (FLAGSHIP FEATURE)",
    "description": "Revolutionary feature that teaches AI assistants your hexagonal architecture",
    "tools": [
      {
        "name": "Cursor",
        "file": ".cursorrules",
        "features": [
          "Complete architecture context",
          "Domain examples",
          "Code patterns"
        ]
      },
      {
        "name": "GitHub Copilot",
        "file": "Documentation",
        "features": ["Better suggestions", "Pattern documentation"]
      },
      {
        "name": "Windsurf",
        "file": ".windsurfrules",
        "features": ["Project configuration", "Architecture understanding"]
      },
      {
        "name": "Juni",
        "file": ".juni/config.json",
        "features": ["Team collaboration", "Consistent generation"]
      }
    ],
    "beforeAfter": {
      "before": {
        "problems": [
          "❌ Direct service imports",
          "❌ Business logic in components",
          "❌ Poor error handling"
        ],
        "code": "// ❌ Wrong\nimport { UserService } from '../domains/user/services';\n\nfunction MyComponent() {\n  const userService = new UserService();\n  const users = userService.getUsers();\n  return <div>{users.map(...)}</div>;\n}"
      },
      "after": {
        "improvements": [
          "✅ Using domain hooks",
          "✅ Proper React Query",
          "✅ Error handling"
        ],
        "code": "// ✅ Correct\nimport { useUsers } from '../domains/user/hooks';\n\nfunction MyComponent() {\n  const { data: users, isLoading, error } = useUsers();\n  \n  if (isLoading) return <LoadingSpinner />;\n  if (error) return <ErrorMessage error={error} />;\n  \n  return <div>{users?.map(...)}</div>;\n}"
      }
    }
  },
  "examples": {
    "ecommerce": {
      "title": "E-Commerce Application",
      "domains": [
        "user",
        "product",
        "cart",
        "order",
        "payment",
        "notification"
      ],
      "setup": [
        "npx ruch create user",
        "npx ruch create product",
        "npx ruch create cart",
        "npx ruch create order",
        "npx ruch create payment",
        "npx ruch create notification",
        "npx ruch context generate",
        "npx ruch msw init",
        "npx ruch msw handlers",
        "npx ruch msw mocks",
        "npx ruch guide-ai"
      ]
    }
  },
  "meta": {
    "version": "1.0.0",
    "lastUpdated": "2024-12-16",
    "totalCommands": 12,
    "totalDomainLayers": 6,
    "keyFeature": "guide-ai command for AI-powered development",
    "architecture": "Simplified Hexagonal Architecture for React"
  }
}