feat: Propagate Result<T> from handlers to endpoints (#81, #83, #85, #87)

.squad/decisions/inbox/sam-result-handlers-complete.md

@@ -0,0 +1,121 @@
+# Result<T> Handler Propagation Complete
+
+**Date**: 2025-01-02  
+**Author**: Sam (Backend Developer)  
+**Issues**: #81, #83, #85, #87  
+**Branch**: `squad/81-result-t-handlers`  
+**Commit**: `9885078`
+
+## Decision
+
+All API handlers have been updated to propagate `Result<T>` from repositories to endpoints, completing the Result pattern implementation across all four domains (Issues, Categories, Statuses, Comments).
+
+## Implementation Details
+
+### Handler Changes
+
+**Return Type Changes**:
+- Get handlers: `Task<TDto?>` → `Task<Result<TDto>>`
+- Update handlers: `Task<TDto>` → `Task<Result<TDto>>`
+- Delete handlers: `Task<bool>` → `Task<Result<bool>>`
+
+**Error Handling Pattern**:
+```csharp
+// Validation errors
+if (!validationResult.IsValid)
+    return Result.Fail<TDto>("Validation failed", ResultErrorCode.Validation);
+
+// Not found errors
+if (getResult.Failure || getResult.Value is null)
+    return Result.Fail<TDto>($"Entity with ID '{id}' was not found.", ResultErrorCode.NotFound);
+
+// Conflict errors (archived entities)
+if (entity.Archived)
+    return Result.Fail<TDto>($"Entity is archived.", ResultErrorCode.Conflict);
+
+// Propagate repository results
+return await _repository.UpdateAsync(entity, cancellationToken);
+```
+
+**Delete Handler Pattern** (special case):
+```csharp
+// Repository.ArchiveAsync returns Result, not Result<bool>
+var archiveResult = await _repository.ArchiveAsync(id, cancellationToken);
+return archiveResult.Success 
+    ? Result.Ok(true) 
+    : Result.Fail<bool>(archiveResult.Error!, archiveResult.ErrorCode);
+```
+
+### Endpoint Changes
+
+**HTTP Response Mapping**:
+```csharp
+// Get endpoints
+var result = await handler.Handle(query);
+return result.Success ? Results.Ok(result.Value) : Results.NotFound();
+
+// Update endpoints
+var result = await handler.Handle(command);
+if (!result.Success)
+    return result.ErrorCode == ResultErrorCode.NotFound ? Results.NotFound() 
+        : result.ErrorCode == ResultErrorCode.Conflict ? Results.Conflict(result.Error)
+        : Results.BadRequest(result.Error);
+return Results.Ok(result.Value);
+
+// Delete endpoints
+var result = await handler.Handle(command);
+return result.Success ? Results.NoContent() : Results.NotFound();
+```
+
+## Files Changed
+
+### Issues (#81)
+- `src/Api/Handlers/Issues/GetIssueHandler.cs`
+- `src/Api/Handlers/Issues/DeleteIssueHandler.cs`
+- `src/Api/Handlers/Issues/UpdateIssueHandler.cs`
+- `src/Api/Handlers/Issues/UpdateIssueStatusHandler.cs`
+- `src/Api/Handlers/Issues/IssueEndpoints.cs`
+
+### Categories (#83)
+- `src/Api/Handlers/Categories/GetCategoryHandler.cs`
+- `src/Api/Handlers/Categories/DeleteCategoryHandler.cs`
+- `src/Api/Handlers/Categories/UpdateCategoryHandler.cs`
+- `src/Api/Handlers/Categories/CategoryEndpoints.cs`
+
+### Statuses (#85)
+- `src/Api/Handlers/Statuses/GetStatusHandler.cs`
+- `src/Api/Handlers/Statuses/DeleteStatusHandler.cs`
+- `src/Api/Handlers/Statuses/UpdateStatusHandler.cs`
+- `src/Api/Handlers/Statuses/StatusEndpoints.cs`
+
+### Comments (#87)
+- `src/Api/Handlers/Comments/GetCommentHandler.cs`
+- `src/Api/Handlers/Comments/DeleteCommentHandler.cs`
+- `src/Api/Handlers/Comments/UpdateCommentHandler.cs`
+- `src/Api/Handlers/Comments/CommentEndpoints.cs`
+
+## Testing Status
+
+- ✅ **src/ compiles successfully** — No compilation errors in production code
+- ❌ **tests/ have compilation errors** — Expected, waiting for Gimli to update test assertions
+
+## Blocked Work
+
+**Gimli** must update all handler tests to:
+1. Expect `Result<T>` return types instead of direct DTOs
+2. Assert on `result.Success` and `result.Failure`
+3. Access values via `result.Value`
+4. Check error codes via `result.ErrorCode`
+5. Update FluentAssertions patterns (e.g., `result.Success.Should().BeTrue()`)
+
+## PR Status
+
+⚠️ **DO NOT MERGE** until test suite is updated by Gimli.
+
+Branch: `squad/81-result-t-handlers`  
+PR: https://github.com/mpaulosky/IssueManager/pull/new/squad/81-result-t-handlers
+
+## Related Decisions
+
+- `.squad/decisions/inbox/aragorn-objectid-result-pattern.md` — Original Result<T> pattern decision
+- `.squad/decisions/inbox/sam-objectid-endpoint-parsing.md` — ObjectId parsing at endpoints (sprint #80)

IssueManager.sln.DotSettings

@@ -0,0 +1,2 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=contentinfo/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>

src/Api/Handlers/Categories/CategoryEndpoints.cs

@@ -25,8 +25,8 @@ public static IEndpointRouteBuilder MapCategoryEndpoints(this IEndpointRouteBuil
 if (!ObjectId.TryParse(id, out var objectId))
 return Results.BadRequest("Invalid ID format");
 var query = new GetCategoryQuery(objectId);
-			var category = await handler.Handle(query);
-			return category is not null ? Results.Ok(category) : Results.NotFound();
+			var result = await handler.Handle(query);
+			return result.Success ? Results.Ok(result.Value) : Results.NotFound();
 		})
 		.WithName("GetCategory")
 		.WithSummary("Get a category by ID")
@@ -50,7 +50,9 @@ public static IEndpointRouteBuilder MapCategoryEndpoints(this IEndpointRouteBuil
 return Results.BadRequest("Invalid ID format");
 var commandWithId = command with { Id = objectId };
 			var result = await handler.Handle(commandWithId);
-			return result is not null ? Results.Ok(result) : Results.NotFound();
+			if (!result.Success)
+				return result.ErrorCode == ResultErrorCode.NotFound ? Results.NotFound() : Results.BadRequest(result.Error);
+			return Results.Ok(result.Value);
 		})
 		.WithName("UpdateCategory")
 		.WithSummary("Update an existing category")
@@ -65,7 +67,7 @@ public static IEndpointRouteBuilder MapCategoryEndpoints(this IEndpointRouteBuil
 return Results.BadRequest("Invalid ID format");
 var command = new DeleteCategoryCommand { Id = objectId };
 			var result = await handler.Handle(command);
-			return result ? Results.NoContent() : Results.NotFound();
+			return result.Success ? Results.NoContent() : Results.NotFound();
 		})
 		.WithName("DeleteCategory")
 		.WithSummary("Delete (archive) a category")

src/Api/Handlers/Categories/DeleteCategoryHandler.cs

@@ -40,23 +40,23 @@ public DeleteCategoryHandler(ICategoryRepository repository, DeleteCategoryValid
 	/// </summary>
 	/// <param name="command">The command containing the category ID to delete.</param>
 	/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
-	/// <returns><see langword="true"/> if the category was successfully archived; otherwise, <see langword="false"/>.</returns>
+	/// <returns>A task that represents the asynchronous operation. The task result contains a result indicating success or failure.</returns>
 	/// <exception cref="ValidationException">Thrown when the command fails validation.</exception>
 	/// <exception cref="NotFoundException">Thrown when the category is not found.</exception>
-	public async Task<bool> Handle(DeleteCategoryCommand command, CancellationToken cancellationToken = default)
+	public async Task<Result<bool>> Handle(DeleteCategoryCommand command, CancellationToken cancellationToken = default)
 	{
 		var validationResult = await _validator.ValidateAsync(command, cancellationToken);
 		if (!validationResult.IsValid)
-			throw new ValidationException(validationResult.Errors);
+			return Result.Fail<bool>("Validation failed", ResultErrorCode.Validation);
 
 		var getResult = await _repository.GetByIdAsync(command.Id, cancellationToken);
 		if (getResult.Failure || getResult.Value is null)
-			throw new NotFoundException($"Category with ID '{command.Id}' was not found.");
+			return Result.Fail<bool>($"Category with ID '{command.Id}' was not found.", ResultErrorCode.NotFound);
 
 		if (getResult.Value.Archived)
-			return true;
+			return Result.Ok(true);
 
 		var archiveResult = await _repository.ArchiveAsync(command.Id, cancellationToken);
-		return archiveResult.Success;
+		return archiveResult.Success ? Result.Ok(true) : Result.Fail<bool>(archiveResult.Error!, archiveResult.ErrorCode);
 	}
 }

src/Api/Handlers/Categories/GetCategoryHandler.cs

@@ -39,11 +39,10 @@ public GetCategoryHandler(ICategoryRepository repository)
 	/// </summary>
 	/// <param name="query">The query containing the category ID to retrieve.</param>
 	/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
-	/// <returns>A task that represents the asynchronous operation. The task result contains the category as a <see cref="CategoryDto"/>, or <see langword="null"/> if not found.</returns>
+	/// <returns>A task that represents the asynchronous operation. The task result contains the result with category as a <see cref="CategoryDto"/>, or an error if not found.</returns>
 	/// <exception cref="ArgumentException">Thrown when the category ID is null or empty.</exception>
-	public async Task<CategoryDto?> Handle(GetCategoryQuery query, CancellationToken cancellationToken = default)
+	public async Task<Result<CategoryDto>> Handle(GetCategoryQuery query, CancellationToken cancellationToken = default)
 	{
-		var result = await _repository.GetByIdAsync(query.CategoryId, cancellationToken);
-		return result.Success ? result.Value : null;
+		return await _repository.GetByIdAsync(query.CategoryId, cancellationToken);
 	}
 }

src/Api/Handlers/Categories/UpdateCategoryHandler.cs

@@ -40,29 +40,25 @@ public UpdateCategoryHandler(ICategoryRepository repository, UpdateCategoryValid
 	/// </summary>
 	/// <param name="command">The command containing the updated category information.</param>
 	/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
-	/// <returns>A task that represents the asynchronous operation. The task result contains the updated category as a <see cref="CategoryDto"/>.</returns>
+	/// <returns>A task that represents the asynchronous operation. The task result contains the result with updated category as a <see cref="CategoryDto"/>.</returns>
 	/// <exception cref="ValidationException">Thrown when the command fails validation.</exception>
 	/// <exception cref="NotFoundException">Thrown when the category is not found or cannot be updated.</exception>
-	public async Task<CategoryDto> Handle(UpdateCategoryCommand command, CancellationToken cancellationToken = default)
+	public async Task<Result<CategoryDto>> Handle(UpdateCategoryCommand command, CancellationToken cancellationToken = default)
 	{
 		var validationResult = await _validator.ValidateAsync(command, cancellationToken);
 		if (!validationResult.IsValid)
-			throw new ValidationException(validationResult.Errors);
+			return Result.Fail<CategoryDto>("Validation failed", ResultErrorCode.Validation);
 
 		var getResult = await _repository.GetByIdAsync(command.Id, cancellationToken);
 		if (!getResult.Success || getResult.Value is null)
-			throw new NotFoundException($"Category with ID '{command.Id}' was not found.");
+			return Result.Fail<CategoryDto>($"Category with ID '{command.Id}' was not found.", ResultErrorCode.NotFound);
 
 		var updatedCategory = getResult.Value with
 		{
 			CategoryName = command.CategoryName,
 			CategoryDescription = command.CategoryDescription ?? string.Empty
 		};
 
-		var updateResult = await _repository.UpdateAsync(updatedCategory, cancellationToken);
-		if (!updateResult.Success)
-			throw new NotFoundException($"Category with ID '{command.Id}' could not be updated.");
-
-		return updateResult.Value!;
+		return await _repository.UpdateAsync(updatedCategory, cancellationToken);
 	}
 }

src/Api/Handlers/Comments/CommentEndpoints.cs

@@ -25,8 +25,8 @@ public static IEndpointRouteBuilder MapCommentEndpoints(this IEndpointRouteBuild
 if (!ObjectId.TryParse(id, out var objectId))
 return Results.BadRequest("Invalid ID format");
 var query = new GetCommentQuery(objectId);
-			var comment = await handler.Handle(query);
-			return comment is not null ? Results.Ok(comment) : Results.NotFound();
+			var result = await handler.Handle(query);
+			return result.Success ? Results.Ok(result.Value) : Results.NotFound();
 		})
 		.WithName("GetComment")
 		.WithSummary("Get a comment by ID")
@@ -50,7 +50,9 @@ public static IEndpointRouteBuilder MapCommentEndpoints(this IEndpointRouteBuild
 return Results.BadRequest("Invalid ID format");
 var commandWithId = command with { Id = objectId };
 			var result = await handler.Handle(commandWithId);
-			return result is not null ? Results.Ok(result) : Results.NotFound();
+			if (!result.Success)
+				return result.ErrorCode == ResultErrorCode.NotFound ? Results.NotFound() : Results.BadRequest(result.Error);
+			return Results.Ok(result.Value);
 		})
 		.WithName("UpdateComment")
 		.WithSummary("Update an existing comment")
@@ -65,7 +67,7 @@ public static IEndpointRouteBuilder MapCommentEndpoints(this IEndpointRouteBuild
 return Results.BadRequest("Invalid ID format");
 var command = new DeleteCommentCommand { Id = objectId };
 			var result = await handler.Handle(command);
-			return result ? Results.NoContent() : Results.NotFound();
+			return result.Success ? Results.NoContent() : Results.NotFound();
 		})
 		.WithName("DeleteComment")
 		.WithSummary("Delete (archive) a comment")

src/Api/Handlers/Comments/DeleteCommentHandler.cs

@@ -40,23 +40,23 @@ public DeleteCommentHandler(ICommentRepository repository, DeleteCommentValidato
 	/// </summary>
 	/// <param name="command">The command containing the comment ID to delete.</param>
 	/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
-	/// <returns><see langword="true"/> if the comment was successfully archived; otherwise, <see langword="false"/>.</returns>
+	/// <returns>A task that represents the asynchronous operation. The task result contains a result indicating success or failure.</returns>
 	/// <exception cref="ValidationException">Thrown when the command fails validation.</exception>
 	/// <exception cref="NotFoundException">Thrown when the comment is not found.</exception>
-	public async Task<bool> Handle(DeleteCommentCommand command, CancellationToken cancellationToken = default)
+	public async Task<Result<bool>> Handle(DeleteCommentCommand command, CancellationToken cancellationToken = default)
 	{
 		var validationResult = await _validator.ValidateAsync(command, cancellationToken);
 		if (!validationResult.IsValid)
-			throw new ValidationException(validationResult.Errors);
+			return Result.Fail<bool>("Validation failed", ResultErrorCode.Validation);
 
 		var getResult = await _repository.GetByIdAsync(command.Id, cancellationToken);
 		if (getResult.Failure || getResult.Value is null)
-			throw new NotFoundException($"Comment with ID '{command.Id}' was not found.");
+			return Result.Fail<bool>($"Comment with ID '{command.Id}' was not found.", ResultErrorCode.NotFound);
 
 		if (getResult.Value.Archived)
-			return true;
+			return Result.Ok(true);
 
 		var archiveResult = await _repository.ArchiveAsync(command.Id, cancellationToken);
-		return archiveResult.Success;
+		return archiveResult.Success ? Result.Ok(true) : Result.Fail<bool>(archiveResult.Error!, archiveResult.ErrorCode);
 	}
 }

src/Api/Handlers/Comments/GetCommentHandler.cs

@@ -39,11 +39,10 @@ public GetCommentHandler(ICommentRepository repository)
 	/// </summary>
 	/// <param name="query">The query containing the comment ID to retrieve.</param>
 	/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
-	/// <returns>A task that represents the asynchronous operation. The task result contains the comment as a <see cref="CommentDto"/>, or <see langword="null"/> if not found.</returns>
+	/// <returns>A task that represents the asynchronous operation. The task result contains the result with comment as a <see cref="CommentDto"/>, or an error if not found.</returns>
 	/// <exception cref="ArgumentException">Thrown when the comment ID is null or empty.</exception>
-	public async Task<CommentDto?> Handle(GetCommentQuery query, CancellationToken cancellationToken = default)
+	public async Task<Result<CommentDto>> Handle(GetCommentQuery query, CancellationToken cancellationToken = default)
 	{
-		var result = await _repository.GetByIdAsync(query.CommentId, cancellationToken);
-		return result.Success ? result.Value : null;
+		return await _repository.GetByIdAsync(query.CommentId, cancellationToken);
 	}
 }

src/Api/Handlers/Comments/UpdateCommentHandler.cs

@@ -40,28 +40,24 @@ public UpdateCommentHandler(ICommentRepository repository, UpdateCommentValidato
 	/// </summary>
 	/// <param name="command">The command containing the updated comment information.</param>
 	/// <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
-	/// <returns>A task that represents the asynchronous operation. The task result contains the updated comment as a <see cref="CommentDto"/>.</returns>
+	/// <returns>A task that represents the asynchronous operation. The task result contains the result with updated comment as a <see cref="CommentDto"/>.</returns>
 	/// <exception cref="ValidationException">Thrown when the command fails validation.</exception>
 	/// <exception cref="NotFoundException">Thrown when the comment is not found or cannot be updated.</exception>
-	public async Task<CommentDto> Handle(UpdateCommentCommand command, CancellationToken cancellationToken = default)
+	public async Task<Result<CommentDto>> Handle(UpdateCommentCommand command, CancellationToken cancellationToken = default)
 	{
 		var validationResult = await _validator.ValidateAsync(command, cancellationToken);
 		if (!validationResult.IsValid)
-			throw new ValidationException(validationResult.Errors);
+			return Result.Fail<CommentDto>("Validation failed", ResultErrorCode.Validation);
 
 		var getResult = await _repository.GetByIdAsync(command.Id, cancellationToken);
 		if (getResult.Failure || getResult.Value is null)
-			throw new NotFoundException($"Comment with ID '{command.Id}' was not found.");
+			return Result.Fail<CommentDto>($"Comment with ID '{command.Id}' was not found.", ResultErrorCode.NotFound);
 
 		var updatedComment = getResult.Value with
 		{
 			Title = command.Title
 		};
 
-		var updateResult = await _repository.UpdateAsync(updatedComment, cancellationToken);
-		if (updateResult.Failure)
-			throw new NotFoundException($"Comment with ID '{command.Id}' could not be updated.");
-
-		return updateResult.Value!;
+		return await _repository.UpdateAsync(updatedComment, cancellationToken);
 	}
 }

src/Api/Handlers/Issues/DeleteIssueHandler.cs

@@ -29,20 +29,20 @@ public DeleteIssueHandler(IIssueRepository repository, DeleteIssueValidator vali
 	/// <summary>
 	/// Handles the soft-deletion (archiving) of an issue.
 	/// </summary>
-	public async Task<bool> Handle(DeleteIssueCommand command, CancellationToken cancellationToken = default)
+	public async Task<Result<bool>> Handle(DeleteIssueCommand command, CancellationToken cancellationToken = default)
 	{
 		var validationResult = await _validator.ValidateAsync(command, cancellationToken);
 		if (!validationResult.IsValid)
-			throw new ValidationException(validationResult.Errors);
+			return Result.Fail<bool>("Validation failed", ResultErrorCode.Validation);
 
 		var getResult = await _repository.GetByIdAsync(command.Id, cancellationToken);
 		if (getResult.Failure || getResult.Value is null)
-			throw new NotFoundException($"Issue with ID '{command.Id}' was not found.");
+			return Result.Fail<bool>($"Issue with ID '{command.Id}' was not found.", ResultErrorCode.NotFound);
 
 		if (getResult.Value.Archived)
-			return true;
+			return Result.Ok(true);
 
 		var archiveResult = await _repository.ArchiveAsync(command.Id, cancellationToken);
-		return archiveResult.Success;
+		return archiveResult.Success ? Result.Ok(true) : Result.Fail<bool>(archiveResult.Error!, archiveResult.ErrorCode);
 	}
 }

src/Api/Handlers/Issues/GetIssueHandler.cs

@@ -32,10 +32,9 @@ public GetIssueHandler(IIssueRepository repository)
 	/// <summary>
 	/// Handles the retrieval of a single issue.
 	/// </summary>
-	public async Task<IssueDto?> Handle(GetIssueQuery query, CancellationToken cancellationToken = default)
+	public async Task<Result<IssueDto>> Handle(GetIssueQuery query, CancellationToken cancellationToken = default)
 	{
-		var result = await _repository.GetByIdAsync(query.IssueId, cancellationToken);
-		return result.Success ? result.Value : null;
+		return await _repository.GetByIdAsync(query.IssueId, cancellationToken);
 	}
 
 	/// <summary>