@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/dotnet/tooling/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: .NET Tooling
+description: Essential tooling for .NET development and CI/CD.
+metadata:
+  labels: [dotnet, tooling, testing, build, nuget]
+  triggers:
+    files: ['**/*.csproj', '**/*.sln', '.editorconfig', 'Directory.Build.props']
+    keywords: [PackageReference, dotnet, test, build, publish]
+---
+
+# .NET Tooling
+
+## **Priority: P1 (OPERATIONAL)**
+
+Essential tooling for .NET development, testing, and CI/CD.
+
+## Implementation Guidelines
+
+- **Project Files**: SDK-style `.csproj`. Use `Directory.Build.props` for shared settings.
+- **Central Package Management**: `Directory.Packages.props` for version consistency.
+- **Testing**: xUnit or NUnit. FluentAssertions for readable assertions. Moq for mocking.
+- **Code Analysis**: Enable built-in analyzers. Consider StyleCop, SonarQube.
+- **Build**: `dotnet build`, `dotnet publish`. Use Release config for production.
+- **EditorConfig**: Consistent code style across team.
+- **CI/CD**: GitHub Actions, Azure DevOps, or GitLab CI.
+
+## Anti-Patterns
+
+- **No `packages.config`**: Migrate to `PackageReference`.
+- **No skipping tests in CI**: Tests must pass before merge.
+- **No ignoring warnings**: Fix or suppress with documented justification.
+- **No floating versions**: Pin versions (`8.0.0`, not `8.*`).
+
+## Code
+
+```xml
+<!-- Directory.Build.props (shared across all projects) -->
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <AnalysisLevel>latest-recommended</AnalysisLevel>
+  </PropertyGroup>
+</Project>
+
+<!-- Directory.Packages.props (Central Package Management) -->
+<Project>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
+    <PackageVersion Include="FluentValidation" Version="11.9.0" />
+    <PackageVersion Include="xunit" Version="2.6.6" />
+  </ItemGroup>
+</Project>
+```
+
+```csharp
+// xUnit test with FluentAssertions
+public class UserServiceTests
+{
+    [Fact]
+    public async Task GetUser_WithValidId_ReturnsUser()
+    {
+        // Arrange
+        var mockRepo = new Mock<IUserRepository>();
+        mockRepo.Setup(r => r.GetByIdAsync(1, default))
+            .ReturnsAsync(new User { Id = 1, Name = "Test" });
+        var sut = new UserService(mockRepo.Object);
+
+        // Act
+        var result = await sut.GetUserAsync(1);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.Name.Should().Be("Test");
+        mockRepo.Verify(r => r.GetByIdAsync(1, default), Times.Once);
+    }
+}
+```
+
+## Reference & Examples
+
+For CI/CD configuration and Docker setup:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+language | best-practices | security

package/rules/dotnet/tooling/references/REFERENCE.md

@@ -0,0 +1,300 @@
+# .NET Tooling Reference
+
+Testing, CI/CD, and build configuration patterns.
+
+## References
+
+- [**Testing Setup**](testing-setup.md) - xUnit, NUnit, integration tests.
+- [**CI/CD**](ci-cd.md) - GitHub Actions, Azure DevOps pipelines.
+- [**Docker**](docker.md) - Multi-stage builds for .NET.
+
+## Project File (.csproj) Reference
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <!-- Code analysis -->
+    <AnalysisLevel>latest-recommended</AnalysisLevel>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+
+    <!-- Assembly info -->
+    <Version>1.0.0</Version>
+    <Authors>Your Name</Authors>
+
+    <!-- Build optimization -->
+    <PublishTrimmed>true</PublishTrimmed>
+    <PublishSingleFile>true</PublishSingleFile>
+    <SelfContained>true</SelfContained>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Package references (versions from Directory.Packages.props) -->
+    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" />
+    <PackageReference Include="Serilog.AspNetCore" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <!-- Project references -->
+    <ProjectReference Include="..\Domain\Domain.csproj" />
+    <ProjectReference Include="..\Infrastructure\Infrastructure.csproj" />
+  </ItemGroup>
+</Project>
+```
+
+## GitHub Actions CI/CD
+
+```yaml
+# .github/workflows/ci.yml
+name: CI/CD
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+env:
+  DOTNET_VERSION: '8.0.x'
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Restore dependencies
+        run: dotnet restore
+
+      - name: Build
+        run: dotnet build --no-restore --configuration Release
+
+      - name: Test
+        run: dotnet test --no-build --configuration Release --collect:"XPlat Code Coverage" --results-directory ./coverage
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        with:
+          directory: ./coverage
+          fail_ci_if_error: true
+
+  publish:
+    needs: build-and-test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: ${{ env.DOTNET_VERSION }}
+
+      - name: Publish
+        run: dotnet publish src/WebApi/WebApi.csproj -c Release -o ./publish
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/${{ github.repository }}:latest
+```
+
+## Docker Multi-Stage Build
+
+```dockerfile
+# Dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+WORKDIR /src
+
+# Copy csproj files and restore
+COPY ["src/WebApi/WebApi.csproj", "src/WebApi/"]
+COPY ["src/Domain/Domain.csproj", "src/Domain/"]
+COPY ["src/Infrastructure/Infrastructure.csproj", "src/Infrastructure/"]
+COPY ["Directory.Build.props", "./"]
+COPY ["Directory.Packages.props", "./"]
+RUN dotnet restore "src/WebApi/WebApi.csproj"
+
+# Copy everything and build
+COPY . .
+RUN dotnet publish "src/WebApi/WebApi.csproj" -c Release -o /app/publish --no-restore
+
+# Runtime image
+FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
+WORKDIR /app
+
+# Create non-root user
+RUN adduser --disabled-password --gecos "" appuser
+USER appuser
+
+COPY --from=build /app/publish .
+
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+
+ENTRYPOINT ["dotnet", "WebApi.dll"]
+```
+
+## Integration Testing with WebApplicationFactory
+
+```csharp
+// CustomWebApplicationFactory.cs
+public class CustomWebApplicationFactory<TProgram> : WebApplicationFactory<TProgram>
+    where TProgram : class
+{
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        builder.ConfigureServices(services =>
+        {
+            // Replace real database with in-memory
+            var descriptor = services.SingleOrDefault(
+                d => d.ServiceType == typeof(DbContextOptions<AppDbContext>));
+
+            if (descriptor != null)
+                services.Remove(descriptor);
+
+            services.AddDbContext<AppDbContext>(options =>
+                options.UseInMemoryDatabase("TestDb"));
+
+            // Replace external services with fakes
+            services.AddScoped<IEmailService, FakeEmailService>();
+        });
+
+        builder.UseEnvironment("Testing");
+    }
+}
+
+// Integration tests
+public class UsersApiTests : IClassFixture<CustomWebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+    private readonly CustomWebApplicationFactory<Program> _factory;
+
+    public UsersApiTests(CustomWebApplicationFactory<Program> factory)
+    {
+        _factory = factory;
+        _client = factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task GetUsers_ReturnsSuccessAndUsers()
+    {
+        // Arrange - seed data
+        using var scope = _factory.Services.CreateScope();
+        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+        db.Users.Add(new User { Name = "Test User", Email = "test@example.com" });
+        await db.SaveChangesAsync();
+
+        // Act
+        var response = await _client.GetAsync("/api/users");
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+        var users = await response.Content.ReadFromJsonAsync<List<UserDto>>();
+        users.Should().ContainSingle(u => u.Email == "test@example.com");
+    }
+
+    [Fact]
+    public async Task CreateUser_WithValidData_ReturnsCreated()
+    {
+        // Arrange
+        var newUser = new CreateUserDto { Name = "New User", Email = "new@example.com" };
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/api/users", newUser);
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+        response.Headers.Location.Should().NotBeNull();
+    }
+}
+```
+
+## EditorConfig
+
+```ini
+# .editorconfig
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.cs]
+# Naming conventions
+dotnet_naming_rule.private_fields_should_be_camel_case.severity = error
+dotnet_naming_rule.private_fields_should_be_camel_case.symbols = private_fields
+dotnet_naming_rule.private_fields_should_be_camel_case.style = camel_case_underscore
+
+dotnet_naming_symbols.private_fields.applicable_kinds = field
+dotnet_naming_symbols.private_fields.applicable_accessibilities = private
+
+dotnet_naming_style.camel_case_underscore.required_prefix = _
+dotnet_naming_style.camel_case_underscore.capitalization = camel_case
+
+# Code style
+csharp_style_var_for_built_in_types = false:suggestion
+csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_style_expression_bodied_methods = when_on_single_line:suggestion
+csharp_prefer_braces = true:warning
+
+# Formatting
+csharp_new_line_before_open_brace = all
+csharp_new_line_before_else = true
+csharp_new_line_before_catch = true
+csharp_new_line_before_finally = true
+
+[*.{json,yml,yaml}]
+indent_size = 2
+```
+
+## Benchmark.NET Setup
+
+```csharp
+// Install: dotnet add package BenchmarkDotNet
+
+[MemoryDiagnoser]
+[SimpleJob(RuntimeMoniker.Net80)]
+public class StringConcatBenchmarks
+{
+    private readonly string[] _strings = Enumerable.Range(0, 100)
+        .Select(i => $"String{i}").ToArray();
+
+    [Benchmark(Baseline = true)]
+    public string ConcatWithPlus()
+    {
+        string result = "";
+        foreach (var s in _strings)
+            result += s;
+        return result;
+    }
+
+    [Benchmark]
+    public string ConcatWithStringBuilder()
+    {
+        var sb = new StringBuilder();
+        foreach (var s in _strings)
+            sb.Append(s);
+        return sb.ToString();
+    }
+
+    [Benchmark]
+    public string ConcatWithJoin() => string.Join("", _strings);
+}
+
+// Run: dotnet run -c Release
+```

package/rules/flutter/auto-route-navigation/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: Flutter AutoRoute Navigation
+description: Typed routing, nested routes, and guards using auto_route.
+metadata:
+  labels: [navigation, auto-route, routing]
+  triggers:
+    files: ['**/router.dart', '**/app_router.dart']
+    keywords: [AutoRoute, AutoRouter, router, guards, navigate, push]
+---
+
+# AutoRoute Navigation
+
+## **Priority: P1 (HIGH)**
+
+Type-safe routing system with code generation using `auto_route`.
+
+## Structure
+
+```text
+core/router/
+├── app_router.dart # Router configuration
+└── app_router.gr.dart # Generated routes
+```
+
+## Implementation Guidelines
+
+- **@RoutePage**: Annotate all screen/page widgets with `@RoutePage()`.
+- **Router Config**: Extend `_$AppRouter` and annotate with `@AutoRouterConfig`.
+- **Typed Navigation**: Use generated route classes (e.g., `HomeRoute()`). Never use strings.
+- **Nested Routes & Tabs**: Use `children` in `AutoRoute` for tabs. When navigating to a route with nested tabs, use the `children` parameter to define the initial active sub-route (e.g., `context.navigateTo(OrdersTabRoute(children: [ViewByOrdersPageRoute()]))`).
+- **Guards**: Implement `AutoRouteGuard` for authentication/authorization logic.
+
+- **Parameters**: Constructors of `@RoutePage` widgets automatically become route parameters.
+- **Declarative**: Prefer `context.pushRoute()` or `context.replaceRoute()`.
+
+## Reference & Examples
+
+For full Router configuration and Auth Guard implementation:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+go-router-navigation | layer-based-clean-architecture

package/rules/flutter/auto-route-navigation/references/REFERENCE.md

@@ -0,0 +1,19 @@
+# AutoRoute Routing Reference
+
+Detailed examples for implementing a scalable, type-safe routing system in Flutter.
+
+## References
+
+- [**AppRouter Configuration**](router-config.md) - Standard setup with `@AutoRouterConfig`.
+- [**Auth Guards**](guards.md) - Protecting routes based on authentication state.
+- [**Nested Routes & Tabs**](nested-routes.md) - Implementation for bottom navigation bars or sub-flows.
+
+## **Quick Navigation Command**
+
+```dart
+// Navigating to a page with parameters
+context.pushRoute(ProfileRoute(userId: '123'));
+
+// Popping and returning a value
+context.maybePop(true);
+```

package/rules/flutter/auto-route-navigation/references/router-config.md

@@ -0,0 +1,62 @@
+# AppRouter Configuration
+
+Standard setup for `auto_route` to ensure code generation and type-safety.
+
+## **Router File (`app_router.dart`)**
+
+```dart
+import 'package:auto_route/auto_route.dart';
+import 'app_router.gr.dart'; // Inherited generated classes
+
+@AutoRouterConfig(replaceInRouteName: 'Page|Screen,Route')
+class AppRouter extends _$AppRouter {
+  @override
+  List<AutoRoute> get routes => [
+    // 1. Initial Route
+    AutoRoute(page: SplashRoute.page, initial: true),
+    
+    // 2. Protected Routes (with Guards)
+    AutoRoute(
+      page: DashboardRoute.page, 
+      guards: [AuthGuard()],
+    ),
+    
+    // 3. Nested Routes (Tabs)
+    AutoRoute(
+      page: HomeTabsRoute.page,
+      children: [
+        AutoRoute(page: PostsRoute.page),
+        AutoRoute(page: SettingsRoute.page),
+      ],
+    ),
+  ];
+}
+```
+
+## **Dynamic Tab Initialization**
+
+If you need to navigate to a tabbed route and set a specific initial tab based on logic:
+
+```dart
+context.navigateTo(
+  OrdersTabRoute(
+    children: params.tab == OrderTab.orders()
+        ? [const ViewByOrdersPageRoute()]
+        : [const ViewByItemsPageRoute()],
+  ),
+);
+```
+
+## **Typed Parameters**
+
+When you define a Screen with a constructor, `auto_route` generates matching parameters:
+
+```dart
+@RoutePage()
+class UserProfilePage extends StatelessWidget {
+  final String userId;
+  const UserProfilePage({required this.userId});
+  
+  // Navigation: context.pushRoute(UserProfileRoute(userId: '123'));
+}
+```

package/rules/flutter/bloc-state-management/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: Flutter BLoC State Management
+description: Standards for predictable state management using flutter_bloc, freezed, and equatable.
+metadata:
+  labels: [state-management, bloc, cubit, freezed, equatable]
+  triggers:
+    files: ['**_bloc.dart', '**_cubit.dart', '**_state.dart', '**_event.dart']
+    keywords:
+      [
+        BlocProvider,
+        BlocBuilder,
+        BlocListener,
+        Cubit,
+        Emitter,
+        transformer,
+        Equatable,
+      ]
+---
+
+# BLoC State Management
+
+## **Priority: P0 (CRITICAL)**
+
+Predictable state management separating business logic from UI using `bloc`, `freezed`, or `equatable`.
+
+## Structure
+
+```text
+presentation/blocs/
+├── auth/
+│   ├── auth_bloc.dart
+│   ├── auth_event.dart # (@freezed or Equatable)
+│   └── auth_state.dart # (@freezed or Equatable)
+```
+
+## Implementation Guidelines
+
+- **States & Events**: Default to `@freezed` (Priority). Use `Equatable` if the library is present in `pubspec.yaml`.
+  - **freezed**: Use for union states (initial, loading, success) and automatic `copyWith`.
+  - **Equatable**: Apply if code generation (build_runner) is avoided or `equatable` is the only comparison library in `pubspec.yaml`.
+  - Choose strategy:
+    - **Union State**: Exclusive UI phases (loading vs data).
+    - **Property-based State**: Complex forms (Option<$Either>, flags).
+- **State Properties**: Use enums, sealed classes, or `Status` objects.
+- **Error Handling**: Use `Failure` objects; avoid throwing exceptions.
+- **Async Data**: Use `emit.forEach` or `emit.onEach` for streams.
+- **Concurrency**: Use `transformer` (restartable, droppable) for event debouncing.
+- **Testing**: Use `blocTest` for state transition verification.
+- **Injection**: Register BLoCs as `@injectable` (Factory).
+
+## Anti-Patterns
+
+- **No Manual Emit**: Do not call `emit()` inside `Future.then`; always use `await` or `emit.forEach`.
+- **No UI Logic**: Do not perform calculations or data formatting inside `BlocBuilder`.
+- **No Cross-Bloc Reference**: Do not pass a BLoC instance into another BLoC; use streams or the UI layer to coordinate.
+
+## Reference & Examples
+
+For full BLoC/Cubit implementations and concurrency patterns:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+feature-based-clean-architecture | dependency-injection

package/rules/flutter/bloc-state-management/references/REFERENCE.md

@@ -0,0 +1,20 @@
+# BLoC State Management Reference
+
+Detailed patterns for implementing BLoC/Cubit in production.
+
+## References
+
+- [**Full Auth BLoC (Union State)**](auth-bloc-example.md) - Best for distinct app phases.
+- [**Property-Based State (Forms)**](property-based-state.md) - Best for persistent data and forms.
+- [**Equatable Usage**](equatable-usage.md) - Lightweight alternative to Freezed.
+- [**Cubit Minimal**](cubit-minimal.md) - Simple state management without events.
+
+## **Concurrency Transformer**
+
+```dart
+// Restartable prevents multiple simultaneous requests
+on<SearchEvent>(
+  _onSearch,
+  transformer: restartable(),
+);
+```

package/rules/flutter/bloc-state-management/references/auth-bloc-example.md

@@ -0,0 +1,52 @@
+# Auth BLoC Full Implementation
+
+## **Events (@freezed)**
+
+```dart
+@freezed
+class AuthEvent with _$AuthEvent {
+  const factory AuthEvent.started() = _Started;
+  const factory AuthEvent.loginSubmitted(String email, String password) = _LoginSubmitted;
+  const factory AuthEvent.logoutPressed() = _LogoutPressed;
+}
+```
+
+## **States (@freezed)**
+
+```dart
+@freezed
+class AuthState with _$AuthState {
+  const factory AuthState.initial() = _Initial;
+  const factory AuthState.loading() = _Loading;
+  const factory AuthState.authenticated(User user) = _Authenticated;
+  const factory AuthState.unauthenticated() = _Unauthenticated;
+  const factory AuthState.error(String message) = _Error;
+}
+```
+
+## **BLoC Implementation**
+
+```dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  final IAuthRepository _repository;
+
+  AuthBloc(this._repository) : super(const AuthState.initial()) {
+    on<_LoginSubmitted>(_onLogin);
+    on<_LogoutPressed>(_onLogout);
+  }
+
+  Future<void> _onLogin(_LoginSubmitted event, Emitter<AuthState> emit) async {
+    emit(const AuthState.loading());
+    final result = await _repository.login(event.email, event.password);
+    result.fold(
+      (failure) => emit(AuthState.error(failure.message)),
+      (user) => emit(AuthState.authenticated(user)),
+    );
+  }
+
+  Future<void> _onLogout(_LogoutPressed event, Emitter<AuthState> emit) async {
+    await _repository.logout();
+    emit(const AuthState.unauthenticated());
+  }
+}
+```