Merge pull request #74 from Bullish-Design/claude/refactor-devman-architecture-GsTY3

Refactor to layered architecture with Railway-Oriented Programming

Author: Bullish-Design

MIGRATION.md

@@ -0,0 +1,75 @@
+# Migration Guide: v0.1.0 to v0.2.0
+
+## Breaking Changes
+
+### 1. TemplateValidator Returns Structured Results
+
+**Before:**
+```python
+issues = TemplateValidator.validate(ref)
+# issues: dict[str, list[str]]
+if issues["errors"]:
+    for error in issues["errors"]:
+        print(error)
+```
+
+**After:**
+```python
+result = TemplateValidator.validate_typed(ref)
+# result: ValidationResult
+if not result.is_valid:
+    for error in result.errors:
+        print(f"{error.message} at {error.location}")
+```
+
+### 2. TemplateReference.create() Returns Result
+
+**Before:**
+```python
+try:
+    ref = TemplateReference(source_type="file", location=path)
+except ValueError as e:
+    handle_error(e)
+```
+
+**After:**
+```python
+result = TemplateReference.create("file", path)
+if result.is_err():
+    handle_error(result.unwrap_err())
+else:
+    ref = result.unwrap()
+```
+
+### 3. CopierConfig.questions Is Now Typed
+
+**Before:**
+```python
+config.questions["name"]  # type: Any
+```
+
+**After:**
+```python
+config.questions["name"]  # type: Question (typed when loaded via from_yaml_file)
+# Can use isinstance() for type checking:
+if isinstance(config.questions["name"], StrQuestion):
+    default = config.questions["name"].default
+```
+
+## Backward Compatibility
+
+The following are maintained for backward compatibility but deprecated:
+
+- `TemplateReference.from_string()` - Use `create()` instead
+- `TemplateValidator.validate()` - Use `validate_typed()` instead
+- `TemplateValidator.validate_structure()` - Use `validate_structure_typed()` instead
+- `CopierConfig.validate_questions()` - Use `validate_questions_structured()` instead
+- `devman.cli.DevmanFinder` - Use `devman.domain.finder.DevmanFinder` instead
+
+## New Features
+
+- Structured error types in `devman.domain.errors`
+- Use cases in `devman.application.use_cases`
+- Value objects in `devman.domain.models`
+- Domain finder in `devman.domain.finder`
+- `parse_question()` function for type-safe question parsing

README.md

@@ -90,6 +90,46 @@ See `tests/fixtures/example_copier.yaml` for a complete example.
 - `devman version`: Print the current devman version.
 - `devman hello NAME`: Print a greeting.
 
+## Architecture
+
+devman follows a layered architecture:
+
+### Domain Layer (`src/devman/domain/`)
+Pure business logic with no framework dependencies:
+- **Models**: Value objects (`ProjectRoot`, `DevmanDirectory`, `ValidationResult`)
+- **Errors**: Structured error types for all failure cases
+- **Services**: `DevmanFinder` for .devman directory location
+- **Protocols**: Interfaces for dependency inversion
+
+### Application Layer (`src/devman/application/`)
+Use cases orchestrating domain objects:
+- `FindDevmanUseCase`: Locate .devman directory
+- `RunDevenvUseCase`: Execute devenv commands
+- `ValidateTemplateUseCase`: Validate template structure
+
+### Infrastructure Layer
+- **CLI** (`cli.py`): Typer-based command interface
+- **Schemas** (`schemas/`): Pydantic models for copier.yaml
+- **Templates** (`templates.py`): Template reference and validation
+
+### Error Handling
+Uses Railway-Oriented Programming with `Result` types:
+- `Ok(value)` for success
+- `Err(error)` for failures
+- No exceptions in business logic
+- All errors are typed domain objects
+
+Example:
+```python
+result = ProjectRoot.create(path)
+if result.is_ok():
+    root = result.unwrap()
+    # ... use root
+else:
+    error = result.unwrap_err()
+    print(f"Failed: {error}")
+```
+
 ## Development
 ```bash
 # Install dev dependencies

pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
     "pydantic-settings>=2.0.0",
     "copier>=9.0.0",
     "pyyaml>=6.0.0",
+    "result>=0.17.0",
 ]
 
 [project.optional-dependencies]

src/devman/__init__.py

@@ -2,4 +2,3 @@
 """DevEnv project templating system."""
 
 __version__ = "0.1.0"
-

src/devman/application/__init__.py

@@ -0,0 +1,2 @@
+# src/devman/application/__init__.py
+"""Application layer: use cases orchestrating domain objects."""

src/devman/application/use_cases.py

@@ -0,0 +1,128 @@
+# src/devman/application/use_cases.py
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from result import Err, Ok, Result
+
+from devman.domain.errors import DomainError, DevmanNotFoundError
+from devman.domain.finder import DevmanFinder
+from devman.domain.models import DevmanDirectory, ProjectRoot, ValidationResult
+from devman.templates import TemplateReference, TemplateValidator
+
+
+@dataclass(frozen=True)
+class FindDevmanCommand:
+    """Command to locate .devman directory."""
+
+    start_path: Path | None = None
+    projects_root: ProjectRoot | None = None
+
+
+@dataclass(frozen=True)
+class FindDevmanResult:
+    """Result of finding .devman directory."""
+
+    devman_directory: DevmanDirectory
+
+
+class FindDevmanUseCase:
+    """Use case: Find nearest .devman directory."""
+
+    def execute(
+        self, command: FindDevmanCommand
+    ) -> Result[FindDevmanResult, DevmanNotFoundError]:
+        """Execute the find operation."""
+        finder = DevmanFinder(projects_root=command.projects_root)
+        result = finder.find(start_path=command.start_path)
+
+        return result.map(
+            lambda devman_dir: FindDevmanResult(devman_directory=devman_dir)
+        )
+
+
+@dataclass(frozen=True)
+class RunDevenvCommand:
+    """Command to run devenv with arguments."""
+
+    devenv_args: list[str]
+    devman_directory: DevmanDirectory
+
+
+@dataclass(frozen=True)
+class RunDevenvResult:
+    """Result of running devenv command."""
+
+    exit_code: int
+
+
+@dataclass(frozen=True)
+class RunDevenvError(DomainError):
+    """Error running devenv command."""
+
+    exit_code: int
+    stderr: str | None = None
+
+
+class RunDevenvUseCase:
+    """Use case: Execute devenv command in .devman directory."""
+
+    def execute(
+        self, command: RunDevenvCommand
+    ) -> Result[RunDevenvResult, RunDevenvError]:
+        """Execute devenv with provided arguments."""
+        try:
+            result = subprocess.run(
+                ["devenv", *command.devenv_args],
+                cwd=command.devman_directory.path,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            return Ok(RunDevenvResult(exit_code=result.returncode))
+
+        except subprocess.CalledProcessError as e:
+            return Err(
+                RunDevenvError(
+                    message=f"devenv failed with exit code {e.returncode}",
+                    exit_code=e.returncode,
+                    stderr=e.stderr if e.stderr else None,
+                )
+            )
+
+        except FileNotFoundError:
+            return Err(
+                RunDevenvError(
+                    message="devenv command not found",
+                    exit_code=127,
+                )
+            )
+
+
+@dataclass(frozen=True)
+class ValidateTemplateCommand:
+    """Command to validate a template."""
+
+    template_reference: TemplateReference
+
+
+@dataclass(frozen=True)
+class ValidateTemplateResult:
+    """Result of template validation."""
+
+    validation_result: ValidationResult
+
+    @property
+    def is_valid(self) -> bool:
+        return self.validation_result.is_valid
+
+
+class ValidateTemplateUseCase:
+    """Use case: Validate template structure and schema."""
+
+    def execute(self, command: ValidateTemplateCommand) -> ValidateTemplateResult:
+        """Execute validation."""
+        validation_result = TemplateValidator.validate_typed(command.template_reference)
+        return ValidateTemplateResult(validation_result=validation_result)