arch-clean

What this skill does

# arch-clean

## Purpose
This skill implements Clean Architecture principles in codebases, focusing on hexagonal patterns with ports/adapters, dependency inversion, use cases, entities, and testability. It refactors or generates code to enforce separation of concerns, making systems modular and easier to test.

## When to Use
Use this skill when refactoring monolithic apps to improve maintainability, starting new projects requiring high testability, or integrating external dependencies without tight coupling. Apply it in scenarios with complex business logic, such as e-commerce backends, or when adapting legacy code to modern architectures like microservices.

## Key Capabilities
- Generate port interfaces for adapters, ensuring dependency inversion (e.g., defines contracts like `interface UserPort { fetchUser(id: string): User; }`).
- Create use case classes that orchestrate entities and ports, promoting single responsibility.
- Invert dependencies by wrapping external libraries in adapters, e.g., converting a direct database call to a port implementation.
- Enforce testability by structuring code for unit testing, such as mocking ports in use cases.
- Validate architecture rules, like checking that inner layers don't depend on outer ones, via static analysis.

## Usage Patterns
Invoke this skill via OpenClaw's CLI for quick refactoring or through API for automated pipelines. Start by analyzing the codebase with a scan command, then apply transformations. For scripts, pipe outputs to build tools like Make or Gradle. Always specify the target directory and language (e.g., TypeScript or Java) to avoid defaults. Use in CI/CD for pre-commit hooks to enforce architecture.

## Common Commands/API
Use the OpenClaw CLI with subcommands prefixed by `arch-clean`. Authentication requires setting `$OPENCLAW_API_KEY` as an environment variable.

- **Generate a port interface:**
  ```
  openclaw arch-clean generate-port --name UserPort --methods "fetchUser(id: string)" --lang ts
  ```
  This creates a file like `UserPort.ts` with the interface.

- **Invert dependencies in a module:**
  ```
  openclaw arch-clean invert-dep --path src/services --adapter DatabaseAdapter
  ```
  Scans the specified path and wraps dependencies, e.g., replacing direct imports with adapter calls.

- **Create a use case:**
  ```
  openclaw arch-clean create-usecase --name FetchUser --ports UserPort --entities User
  ```
  Generates a class like `FetchUserUseCase.ts` with injected ports.

API endpoints for programmatic use:
- POST /api/arch-clean/generate: Body { "type": "port", "name": "UserPort", "methods": ["fetchUser(id: string)"] }, requires `$OPENCLAW_API_KEY` in headers.
- PUT /api/arch-clean/invert: Body { "path": "src/services", "adapter": "DatabaseAdapter" }.

Config formats: Use JSON files for custom rules, e.g., `.openclaw-arch.json` with { "layers": { "domain": ["entities", "usecases"], "adapters": ["http", "db"] } }.

## Integration Notes
Integrate by adding OpenClaw as a dependency in your project (e.g., npm install openclaw or via Docker image). Set `$OPENCLAW_API_KEY` for authenticated requests. For IDE plugins, configure via settings like { "arch-clean": { "defaultLang": "ts", "excludePaths": ["tests/**"] } }. Combine with linters like ESLint by piping output, e.g., `openclaw arch-clean scan | eslint --fix`. Ensure your codebase uses a supported structure, such as folders for "domain", "application", and "infrastructure", to match hexagonal patterns.

## Error Handling
Check command outputs for errors; CLI returns non-zero exit codes with JSON error messages, e.g., { "error": "Dependency not inverted: invalid path" }. For API, expect HTTP 4xx/5xx responses with bodies like { "code": 400, "message": "Missing required field: methods" }. Handle by wrapping calls in try-catch blocks, e.g.:
```
try {
  const response = await fetch('/api/arch-clean/generate', { headers: { 'X-API-Key': process.env.OPENCLAW_API_KEY } });
  if (!response.ok) throw new Error(response.statusText);
} catch (error) {
  console.error('Arch error:', error.message);
}
```
Retry transient errors (e.g., network issues) up to 3 times with exponential backoff.

## Usage Examples
1. **Refactor a simple service to use ports:** For a Node.js app, run `openclaw arch-clean invert-dep --path src/userService.js --adapter HttpAdapter`. This transforms a direct HTTP call into a port, e.g., changing `axios.get('/user')` to `this.userPort.fetchUser(id)`, improving testability by allowing mocks.

2. **Generate a use case for business logic:** In a Java project, execute `openclaw arch-clean create-usecase --name OrderProcessor --ports PaymentPort --entities Order`. This produces `OrderProcessor.java` with a method like `public void process(Order order) { this.paymentPort.charge(order); }`, enabling dependency injection for better architecture.

## Graph Relationships
- Related to: se-architecture cluster (e.g., links to skills like code-refactor for broader refactoring).
- Depends on: ports-adapters tag (connects to hexagonal-architecture for adapter implementations).
- Conflicts with: monolithic patterns (avoids tight couplings in legacy systems).