workspace-architect 1.3.0

package/assets/instructions/object-calisthenics.instructions.md

@@ -0,0 +1,302 @@
+---
+applyTo: '**/*.{cs,ts,java}'
+description: Enforces Object Calisthenics principles for business domain code to ensure clean, maintainable, and robust code
+---
+# Object Calisthenics Rules
+
+> ⚠️ **Warning:** This file contains the 9 original Object Calisthenics rules. No additional rules must be added, and none of these rules should be replaced or removed.
+> Examples may be added later if needed.
+
+## Objective
+This rule enforces the principles of Object Calisthenics to ensure clean, maintainable, and robust code in the backend, **primarily for business domain code**.
+
+## Scope and Application
+- **Primary focus**: Business domain classes (aggregates, entities, value objects, domain services)
+- **Secondary focus**: Application layer services and use case handlers
+- **Exemptions**: 
+  - DTOs (Data Transfer Objects)
+  - API models/contracts
+  - Configuration classes
+  - Simple data containers without business logic
+  - Infrastructure code where flexibility is needed
+
+## Key Principles
+
+
+1. **One Level of Indentation per Method**:
+   - Ensure methods are simple and do not exceed one level of indentation.
+
+   ```csharp
+   // Bad Example - this method has multiple levels of indentation
+   public void SendNewsletter() {
+         foreach (var user in users) {
+            if (user.IsActive) {
+               // Do something
+               mailer.Send(user.Email);
+            }
+         }
+   }
+   // Good Example - Extracted method to reduce indentation
+   public void SendNewsletter() {
+       foreach (var user in users) {
+           SendEmail(user);
+       }
+   }
+   private void SendEmail(User user) {
+       if (user.IsActive) {
+           mailer.Send(user.Email);
+       }
+   }
+
+   // Good Example - Filtering users before sending emails
+   public void SendNewsletter() {
+       var activeUsers = users.Where(user => user.IsActive);
+
+       foreach (var user in activeUsers) {
+           mailer.Send(user.Email);
+       }
+   }
+   ```
+2. **Don't Use the ELSE Keyword**:
+
+   - Avoid using the `else` keyword to reduce complexity and improve readability.
+   - Use early returns to handle conditions instead.
+   - Use Fail Fast principle
+   - Use Guard Clauses to validate inputs and conditions at the beginning of methods.
+
+   ```csharp
+   // Bad Example - Using else
+   public void ProcessOrder(Order order) {
+       if (order.IsValid) {
+           // Process order
+       } else {
+           // Handle invalid order
+       }
+   }
+   // Good Example - Avoiding else
+   public void ProcessOrder(Order order) {
+       if (!order.IsValid) return;
+       // Process order
+   }
+   ```
+
+   Sample Fail fast principle:
+   ```csharp
+   public void ProcessOrder(Order order) {
+       if (order == null) throw new ArgumentNullException(nameof(order));
+       if (!order.IsValid) throw new InvalidOperationException("Invalid order");
+       // Process order
+   }
+   ```
+
+3. **Wrapping All Primitives and Strings**:
+   - Avoid using primitive types directly in your code.
+   - Wrap them in classes to provide meaningful context and behavior.
+
+   ```csharp
+   // Bad Example - Using primitive types directly
+   public class User {
+       public string Name { get; set; }
+       public int Age { get; set; }
+   }
+   // Good Example - Wrapping primitives
+   public class User {
+       private string name;
+       private Age age;
+       public User(string name, Age age) {
+           this.name = name;
+           this.age = age;
+       }
+   }
+   public class Age {
+       private int value;
+       public Age(int value) {
+           if (value < 0) throw new ArgumentOutOfRangeException(nameof(value), "Age cannot be negative");
+           this.value = value;
+       }
+   }
+   ```   
+
+4. **First Class Collections**:
+   - Use collections to encapsulate data and behavior, rather than exposing raw data structures.
+First Class Collections: a class that contains an array as an attribute should not contain any other attributes
+
+```csharp
+   // Bad Example - Exposing raw collection
+   public class Group {
+      public int Id { get; private set; }
+      public string Name { get; private set; }
+      public List<User> Users { get; private set; }
+
+      public int GetNumberOfUsersIsActive() {
+         return Users
+            .Where(user => user.IsActive)
+            .Count();
+      }
+   }
+
+   // Good Example - Encapsulating collection behavior
+   public class Group {
+      public int Id { get; private set; }
+      public string Name { get; private set; }
+
+      public GroupUserCollection userCollection { get; private set; } // The list of users is encapsulated in a class
+
+      public int GetNumberOfUsersIsActive() {
+         return userCollection
+            .GetActiveUsers()
+            .Count();
+      }
+   }
+   ```
+
+5. **One Dot per Line**:
+   - Limit the number of method calls in a single line to improve readability and maintainability.
+
+   ```csharp
+   // Bad Example - Multiple dots in a single line
+   public void ProcessOrder(Order order) {
+       var userEmail = order.User.GetEmail().ToUpper().Trim();
+       // Do something with userEmail
+   }
+   // Good Example - One dot per line
+   public void ProcessOrder(Order order) {
+       var user = order.User;
+       var email = user.GetEmail();
+       var userEmail = email.ToUpper().Trim();
+       // Do something with userEmail
+   }
+   ```
+
+6. **Don't abbreviate**:
+   - Use meaningful names for classes, methods, and variables.
+   - Avoid abbreviations that can lead to confusion.
+
+   ```csharp
+   // Bad Example - Abbreviated names
+   public class U {
+       public string N { get; set; }
+   }
+   // Good Example - Meaningful names
+   public class User {
+       public string Name { get; set; }
+   }
+   ```
+
+7. **Keep entities small (Class, method, namespace or package)**:
+   - Limit the size of classes and methods to improve code readability and maintainability.
+   - Each class should have a single responsibility and be as small as possible.
+   
+   Constraints:
+   - Maximum 10 methods per class
+   - Maximum 50 lines per class
+   - Maximum 10 classes per package or namespace
+
+   ```csharp
+   // Bad Example - Large class with multiple responsibilities
+   public class UserManager {
+       public void CreateUser(string name) { /*...*/ }
+       public void DeleteUser(int id) { /*...*/ }
+       public void SendEmail(string email) { /*...*/ }
+   }
+
+   // Good Example - Small classes with single responsibility
+   public class UserCreator {
+       public void CreateUser(string name) { /*...*/ }
+   }
+   public class UserDeleter {
+       public void DeleteUser(int id) { /*...*/ }
+   }
+
+   public class UserUpdater {
+       public void UpdateUser(int id, string name) { /*...*/ }
+   }
+   ```
+
+
+8. **No Classes with More Than Two Instance Variables**:
+   - Encourage classes to have a single responsibility by limiting the number of instance variables.
+   - Limit the number of instance variables to two to maintain simplicity.
+   - Do not count ILogger or any other logger as instance variable.
+
+   ```csharp
+   // Bad Example - Class with multiple instance variables
+   public class UserCreateCommandHandler {
+      // Bad: Too many instance variables
+      private readonly IUserRepository userRepository;
+      private readonly IEmailService emailService;
+      private readonly ILogger logger;
+      private readonly ISmsService smsService;
+
+      public UserCreateCommandHandler(IUserRepository userRepository, IEmailService emailService, ILogger logger, ISmsService smsService) {
+         this.userRepository = userRepository;
+         this.emailService = emailService;
+         this.logger = logger;
+         this.smsService = smsService;
+      }
+   }
+
+   // Good: Class with two instance variables
+   public class UserCreateCommandHandler {
+      private readonly IUserRepository userRepository;
+      private readonly INotificationService notificationService;
+      private readonly ILogger logger; // This is not counted as instance variable
+
+      public UserCreateCommandHandler(IUserRepository userRepository, INotificationService notificationService, ILogger logger) {
+         this.userRepository = userRepository;
+         this.notificationService = notificationService;
+         this.logger = logger;
+      }
+   }
+   ```
+
+9. **No Getters/Setters in Domain Classes**:
+   - Avoid exposing setters for properties in domain classes.
+   - Use private constructors and static factory methods for object creation.
+   - **Note**: This rule applies primarily to domain classes, not DTOs or data transfer objects.
+
+   ```csharp
+   // Bad Example - Domain class with public setters
+   public class User {  // Domain class
+       public string Name { get; set; } // Avoid this in domain classes
+   }
+   
+   // Good Example - Domain class with encapsulation
+   public class User {  // Domain class
+       private string name;
+       private User(string name) { this.name = name; }
+       public static User Create(string name) => new User(name);
+   }
+   
+   // Acceptable Example - DTO with public setters
+   public class UserDto {  // DTO - exemption applies
+       public string Name { get; set; } // Acceptable for DTOs
+   }
+   ```
+
+## Implementation Guidelines
+- **Domain Classes**:
+  - Use private constructors and static factory methods for creating instances.
+  - Avoid exposing setters for properties.
+  - Apply all 9 rules strictly for business domain code.
+
+- **Application Layer**:
+  - Apply these rules to use case handlers and application services.
+  - Focus on maintaining single responsibility and clean abstractions.
+
+- **DTOs and Data Objects**:
+  - Rules 3 (wrapping primitives), 8 (two instance variables), and 9 (no getters/setters) may be relaxed for DTOs.
+  - Public properties with getters/setters are acceptable for data transfer objects.
+
+- **Testing**:
+  - Ensure tests validate the behavior of objects rather than their state.
+  - Test classes may have relaxed rules for readability and maintainability.
+
+- **Code Reviews**:
+  - Enforce these rules during code reviews for domain and application code.
+  - Be pragmatic about infrastructure and DTO code.
+
+## References
+- [Object Calisthenics - Original 9 Rules by Jeff Bay](https://www.cs.helsinki.fi/u/luontola/tdd-2009/ext/ObjectCalisthenics.pdf)
+- [ThoughtWorks - Object Calisthenics](https://www.thoughtworks.com/insights/blog/object-calisthenics)
+- [Clean Code: A Handbook of Agile Software Craftsmanship - Robert C. Martin](https://www.oreilly.com/library/view/clean-code-a/9780136083238/)

package/assets/instructions/oqtane.instructions.md

@@ -0,0 +1,86 @@
+---
+description: 'Oqtane Module patterns'
+applyTo: '**/*.razor, **/*.razor.cs, **/*.razor.css'
+---
+
+## Blazor Code Style and Structure
+
+- Write idiomatic and efficient Blazor and C# code.
+- Follow .NET and Blazor conventions.
+- Use Razor Components appropriately for component-based UI development.
+- Use Blazor Components appropriately for component-based UI development.
+- Prefer inline functions for smaller components but separate complex logic into code-behind or service classes.
+- Async/await should be used where applicable to ensure non-blocking UI operations.
+
+
+## Naming Conventions
+
+- Follow PascalCase for component names, method names, and public members.
+- Use camelCase for private fields and local variables.
+- Prefix interface names with "I" (e.g., IUserService).
+
+## Blazor and .NET Specific Guidelines
+
+- Utilize Blazor's built-in features for component lifecycle (e.g., OnInitializedAsync, OnParametersSetAsync).
+- Use data binding effectively with @bind.
+- Leverage Dependency Injection for services in Blazor.
+- Structure Blazor components and services following Separation of Concerns.
+- Always use the latest version C#, currently C# 13 features like record types, pattern matching, and global usings.
+
+## Oqtane specific Guidelines
+- See base classes and patterns in the [Main Oqtane repo](https://github.com/oqtane/oqtane.framework)
+- Follow client server patterns for module development.
+- The Client project has various modules in the modules folder.
+- Each action in the client module is a seperate razor file that inherits from ModuleBase with index.razor being the default action.
+- For complex client processing like getting data, create a service class that inherits from ServiceBase and lives in the services folder. One service class for each module. 
+- Client service should call server endpoint using ServiceBase methods
+- Server project contains MVC Controllers, one for each module that match the client service calls.  Each controller will call server-side services or repositories managed by DI
+- Server projects use repository patterns for modules, one repository class per module to match the controllers. 
+
+## Error Handling and Validation
+
+- Implement proper error handling for Blazor pages and API calls.
+- Use built-in Oqtane logging methods from base classes.
+- Use logging for error tracking in the backend and consider capturing UI-level errors in Blazor with tools like ErrorBoundary.
+- Implement validation using FluentValidation or DataAnnotations in forms.
+
+## Blazor API and Performance Optimization
+
+- Utilize Blazor server-side or WebAssembly optimally based on the project requirements.
+- Use asynchronous methods (async/await) for API calls or UI actions that could block the main thread.
+- Optimize Razor components by reducing unnecessary renders and using StateHasChanged() efficiently.
+- Minimize the component render tree by avoiding re-renders unless necessary, using ShouldRender() where appropriate.
+- Use EventCallbacks for handling user interactions efficiently, passing only minimal data when triggering events.
+
+## Caching Strategies
+
+- Implement in-memory caching for frequently used data, especially for Blazor Server apps. Use IMemoryCache for lightweight caching solutions.
+- For Blazor WebAssembly, utilize localStorage or sessionStorage to cache application state between user sessions.
+- Consider Distributed Cache strategies (like Redis or SQL Server Cache) for larger applications that need shared state across multiple users or clients.
+- Cache API calls by storing responses to avoid redundant calls when data is unlikely to change, thus improving the user experience.
+
+## State Management Libraries
+
+- Use Blazor's built-in Cascading Parameters and EventCallbacks for basic state sharing across components.
+- use built-in Oqtane state management in the base classes like PageState and SiteState when appropriate.
+- Avoid adding extra depenencies like Fluxor or BlazorState when the application grows in complexity.
+- For client-side state persistence in Blazor WebAssembly, consider using Blazored.LocalStorage or Blazored.SessionStorage to maintain state between page reloads.
+- For server-side Blazor, use Scoped Services and the StateContainer pattern to manage state within user sessions while minimizing re-renders.
+
+## API Design and Integration
+
+- Use service base methods to communicate with external APIs or server project backend.
+- Implement error handling for API calls using try-catch and provide proper user feedback in the UI.
+
+## Testing and Debugging in Visual Studio
+
+- All unit testing and integration testing should be done in Visual Studio Enterprise.
+- Test Blazor components and services using xUnit, NUnit, or MSTest.
+- Use Moq or NSubstitute for mocking dependencies during tests.
+- Debug Blazor UI issues using browser developer tools and Visual Studio's debugging tools for backend and server-side issues.
+- For performance profiling and optimization, rely on Visual Studio's diagnostics tools.
+
+## Security and Authentication
+
+- Implement Authentication and Authorization using built-in Oqtane base class members like User.Roles.
+- Use HTTPS for all web communication and ensure proper CORS policies are implemented.