@ngxtm/devkit 3.4.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngxtm/devkit",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Per-project AI skills with smart tech detection - lightweight and context-optimized",
   "main": "cli/index.js",
   "bin": {
@@ -20,6 +20,7 @@
     "merged-commands/",
     "templates/",
     "skills/",
+    "rules/",
     "scripts/merge-commands.js",
     "scripts/organize-rules.js",
     "scripts/generate-index.js",

package/rules/README.md

@@ -0,0 +1,141 @@
+# Agent Skills Registry
+
+This directory contains the source of truth for all AI agent skills. Skills are organized by **Category** (Language or Framework) and then by **Domain**.
+
+## 📂 Structure
+
+Each skill must follow the standard directory structure:
+`skills/{category}/{skill-name}/SKILL.md`
+
+## 🛠 Active Categories
+
+### 🎯 Flutter (Framework)
+
+High-density standards for modern Flutter development.
+
+- [**Layer-based Clean Architecture**](flutter/layer-based-clean-architecture/SKILL.md) (P0) - Dependency flow & modularity.
+- [**BLoC State Management**](flutter/bloc-state-management/SKILL.md) (P0) - Predictable state flows.
+- [**Security**](flutter/security/SKILL.md) (P0) - OWASP & data safety.
+- [**Feature-based Clean Architecture**](flutter/feature-based-clean-architecture/SKILL.md) (P1) - Scalable directory structures.
+- [**Idiomatic Flutter**](flutter/idiomatic-flutter/SKILL.md) (P1) - Modern layout & composition.
+- [**Performance**](flutter/performance/SKILL.md) (P1) - 60fps & memory optimization.
+- [**Widgets**](flutter/widgets/SKILL.md) (P1) - Reusable components.
+- [**Error Handling**](flutter/error-handling/SKILL.md) (P1) - Functional error handling.
+- [**Retrofit Networking**](flutter/retrofit-networking/SKILL.md) (P1) - API client standards.
+- [**Dependency Injection**](flutter/dependency-injection/SKILL.md) (P1) - GetIt & Provider patterns.
+- [**CI/CD**](flutter/cicd/SKILL.md) (P1) - GitHub Actions, Fastlane, Automation.
+- [**Testing**](flutter/testing/SKILL.md) (P1) - Unit, Widget & Integration Strategies.
+- [**AutoRoute Navigation**](flutter/auto-route-navigation/SKILL.md) (P2) - Type-safe routing.
+- [**GoRouter Navigation**](flutter/go-router-navigation/SKILL.md) (P2) - URI-based routing.
+
+### 🔷 Dart (Language)
+
+Core language idioms and patterns.
+
+- [**Language Patterns**](dart/language/SKILL.md) (P0) - Records, Patterns, Sealed classes.
+- [**Best Practices**](dart/best-practices/SKILL.md) (P1) - Scoping, Imports, Config.
+- [**Tooling**](dart/tooling/SKILL.md) (P1) - Linting, Formatting, Analysis.
+
+### 🔷 TypeScript (Language)
+
+Modern TypeScript standards for type-safe development.
+
+- [**Language Patterns**](typescript/language/SKILL.md) (P0) - Types, Generics, Type Guards.
+- [**Security**](typescript/security/SKILL.md) (P0) - Input Validation, Auth, Secrets.
+- [**Best Practices**](typescript/best-practices/SKILL.md) (P1) - Naming, Modules, Conventions.
+- [**Tooling**](typescript/tooling/SKILL.md) (P1) - ESLint, Testing, Build Tools.
+
+### 🟨 JavaScript (Language)
+
+Modern JavaScript (ES2022+) patterns.
+
+- [**Language Patterns**](javascript/language/SKILL.md) (P0) - Modern Syntax, Async/Await.
+- [**Best Practices**](javascript/best-practices/SKILL.md) (P1) - Conventions, Error Handling.
+- [**Tooling**](javascript/tooling/SKILL.md) (P1) - ESLint, Jest, Build Tools.
+
+### ⚛️ React (Framework)
+
+Modern React development patterns.
+
+- [**Component Patterns**](react/component-patterns/SKILL.md) (P0) - Function Components, Composition.
+- [**State Management**](react/state-management/SKILL.md) (P0) - useState, Context, Zustand.
+- [**TypeScript**](react/typescript/SKILL.md) (P0) - React-specific Types.
+- [**Security**](react/security/SKILL.md) (P0) - XSS Prevention, Auth Patterns.
+- [**Hooks**](react/hooks/SKILL.md) (P1) - Custom Hooks, Best Practices.
+- [**Performance**](react/performance/SKILL.md) (P1) - Memoization, Code Splitting.
+- [**Tooling**](react/tooling/SKILL.md) (P1) - Debugging & Profiling.
+- [**Testing**](react/testing/SKILL.md) (P2) - React Testing Library, Jest.
+
+### 🦁 NestJS (Framework)
+
+Enterprise-grade Node.js backend development.
+
+- [**Architecture**](nestjs/architecture/SKILL.md) (P0) - Modules, DI, Scalability.
+- [**Controllers & Services**](nestjs/controllers-services/SKILL.md) (P0) - Layer separation standards.
+- [**Database**](nestjs/database/SKILL.md) (P0) - TypeORM, Prisma, Mongoose patterns.
+- [**Security**](nestjs/security/SKILL.md) (P0) - Auth, Guards, Headers.
+- [**Configuration**](nestjs/configuration/SKILL.md) (P1) - Environment management.
+- [**Error Handling**](nestjs/error-handling/SKILL.md) (P1) - Global filters.
+- [**Performance**](nestjs/performance/SKILL.md) (P1) - Fastify, Caching.
+- [**Testing**](nestjs/testing/SKILL.md) (P2) - Unit & E2E strategies.
+
+### ▲ Next.js (Framework)
+
+Modern fullstack React framework standards (App Router).
+
+- [**App Router**](nextjs/app-router/SKILL.md) (P0) - Routing conventions, Layouts, Loading.
+- [**Server Components**](nextjs/server-components/SKILL.md) (P0) - RSC patterns, "use client" boundaries.
+- [**Rendering**](nextjs/rendering/SKILL.md) (P0) - SSG, SSR, PPR, Streaming.
+- [**Data Fetching**](nextjs/data-fetching/SKILL.md) (P0) - Extended fetch, Caching control.
+- [**Authentication**](nextjs/authentication/SKILL.md) (P0) - Auth.js / Middleware patterns.
+- [**Data Access Layer**](nextjs/data-access-layer/SKILL.md) (P1) - DAL patterns & DTOs.
+- [**Caching**](nextjs/caching/SKILL.md) (P1) - Request & Data caching layers.
+- [**Styling**](nextjs/styling/SKILL.md) (P1) - Tailwind, Fonts, CSS-in-JS constraints.
+- [**Optimization**](nextjs/optimization/SKILL.md) (P1) - Images, Scripts, Core Web Vitals.
+- [**Server Actions**](nextjs/server-actions/SKILL.md) (P1) - Mutations & Forms.
+- [**Internationalization**](nextjs/internationalization/SKILL.md) (P2) - i18n routing.
+- [**Architecture**](nextjs/architecture/SKILL.md) (P2) - Feature-Sliced Design (FSD).
+- [**State Management**](nextjs/state-management/SKILL.md) (P2) - URL-state, avoiding global stores.
+
+### ☕ Java (Language & Frameworks)
+
+Modern Java development with Spring Boot, Quarkus, and Micronaut.
+
+- [**Core Language**](java/java-core-language/SKILL.md) (P0) - Records, Sealed Classes, Pattern Matching.
+- [**Collections & Streams**](java/java-collections-streams/SKILL.md) (P0) - Stream API, Collectors, Optional.
+- [**Concurrency**](java/java-concurrency/SKILL.md) (P0) - Executors, CompletableFuture, Virtual Threads.
+- [**Project Structure**](java/java-project-structure/SKILL.md) (P0) - Maven/Gradle layout, Modules.
+- [**Spring Boot Architecture**](java/spring-boot-architecture/SKILL.md) (P0) - Auto-configuration, Profiles.
+- [**Spring Boot Web**](java/spring-boot-web/SKILL.md) (P0) - REST Controllers, Validation.
+- [**Spring Security**](java/spring-security/SKILL.md) (P0) - JWT, OAuth2, Method Security.
+- [**Spring Data JPA**](java/spring-data-jpa/SKILL.md) (P0) - Entities, Repositories, Transactions.
+- [**Spring Batch**](java/spring-batch/SKILL.md) (P1) - Job Configuration, Chunk Processing.
+- [**Spring Cloud**](java/spring-cloud/SKILL.md) (P1) - Service Discovery, Circuit Breakers.
+- [**Quarkus Core**](java/quarkus-core/SKILL.md) (P1) - CDI, Configuration, Dev Mode.
+- [**Quarkus Reactive**](java/quarkus-reactive/SKILL.md) (P1) - Mutiny, Reactive Routes.
+- [**Micronaut Core**](java/micronaut-core/SKILL.md) (P1) - Compile-time DI, Configuration.
+- [**Micronaut Reactive**](java/micronaut-reactive/SKILL.md) (P1) - Reactive Types, HTTP Clients.
+- [**GraalVM Native**](java/graalvm-native/SKILL.md) (P1) - Native Image, Reflection Config.
+- [**Maven Build**](java/build-maven/SKILL.md) (P2) - POM, Dependency Management.
+- [**Gradle Build**](java/build-gradle/SKILL.md) (P2) - Kotlin DSL, Tasks.
+- [**Testing (JUnit & Mockito)**](java/testing-junit-mockito/SKILL.md) (P2) - JUnit 5, Test Slices.
+
+### 🚀 Coming Soon
+
+- **Angular** (Framework)
+- **Kotlin** (Language)
+
+---
+
+## ✍️ Contribution Guide
+
+To add or update a skill:
+
+1. **Format**: Ensure the `SKILL.md` uses the high-density format (YAML frontmatter + concise Markdown).
+2. **Progressive Disclosure**: Move large code samples or templates to `references/REFERENCE.md` inside the skill folder. This keeps the primary context small and token-efficient.
+3. **Naming**: Category folders must be lowercase. Skill folders use `kebab-case`.
+4. **Discovery**: Ensure the `triggers` in the YAML frontmatter are accurate for the AI agent to pick it up.
+5. **Priority**:
+   - **P0**: Foundational (Architecture, Types, Security).
+   - **P1**: Operational (Performance, Idioms, UI).
+   - **P2**: Maintenance (Testing, Tooling, Docs).

package/rules/dart/best-practices/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: Dart Best Practices
+description: General purity standards for Dart development.
+metadata:
+  labels: [dart, clean-code]
+  triggers:
+    files: ['**/*.dart']
+    keywords: [import, final, const, var, global]
+---
+
+# Dart Best Practices (P1)
+
+- **Scoping**:
+  - No global variables.
+  - Private globals (if required) must start with `_`.
+- **Immutability**: Use `const` > `final` > `var`.
+- **Config**: Use `--dart-define` for secrets. Never hardcode API keys.
+- **Naming**: Follow [effective-dart](https://dart.dev/guides/language/effective-dart) (PascalCase classes, camelCase members).
+
+```dart
+import 'models/user.dart'; // Good
+import 'package:app/models/user.dart'; // Avoid local absolute
+```

package/rules/dart/language/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: Dart Language Patterns
+description: Modern Dart standards (3.x+) including null safety and patterns.
+metadata:
+  labels: [dart, language, idioms]
+  triggers:
+    files: ['**/*.dart']
+    keywords: [sealed, record, switch, pattern, extension, final, late, async, await]
+---
+
+# Dart Language Patterns
+
+## **Priority: P0 (CRITICAL)**
+
+Modern Dart standards for safety, performance, and readability.
+
+## Implementation Guidelines
+
+- **Null Safety**: Avoid `!`. Use `?.`, `??`, or short-circuiting. Use `late` only if necessary.
+- **Immutability**: Use `final` for all variables. Use `@freezed` for data classes.
+- **Pattern Matching (3.x)**: Use `switch (value)` with patterns and destructuring.
+- **Records**: Use Records (e.g., `(String, int)`) for returning multiple values.
+- **Sealed Classes**: Use `sealed class` for exhaustive state handling in domain logic.
+- **Extensions**: Use `extension` to add utility methods to third-party types.
+- **Wildcards (3.7+)**: Use `_` for unused variables in declarations and patterns.
+- **Tear-offs**: Prefer using tear-offs (e.g., `list.forEach(print)`) over anonymous lambdas (e.g., `list.forEach((e) => print(e))`).
+- **Asynchrony**: Prefer `async/await` over raw `Future.then`. Use `unawaited` for fire-and-forget logic if necessary.
+- **Collections**: Use `collection-if`, `collection-for`, and spread operators `...`.
+
+## Anti-Patterns
+
+- **No ! Operator**: Do not use the bang operator `!` unless you can prove the value is non-null via `if` or `assert`.
+- **No var for members**: Do not use `var` for class members; use `final` or explicit types.
+- **No logic in constructors**: Do not perform complex calculations or async work inside constructors.
+
+## Code
+
+```dart
+// Sealed class and Switch expression
+sealed class Result {}
+class Success extends Result { final String data; Success(this.data); }
+class Failure extends Result {}
+
+String message(Result r) => switch (r) {
+  Success(data: var d) => "Got $d",
+  Failure() => "Error",
+};
+```
+
+## Related Topics
+
+feature-based-clean-architecture | tooling

package/rules/dart/tooling/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: Dart Tooling & CI
+description: Standards for analysis, linting, formatting, and automation.
+metadata:
+  labels: [tooling, linting, automation]
+  triggers:
+    files: ['analysis_options.yaml', 'pubspec.yaml', 'build.yaml']
+    keywords: [analysis_options, lints, format, build_runner, cider, husky]
+---
+
+# Tooling & CI
+
+## **Priority: P1 (HIGH)**
+
+Standards for code quality, formatting, and generation.
+
+## Implementation Guidelines
+
+- **Linter**: Use `analysis_options.yaml`. Enforce `always_use_package_imports` and `require_trailing_commas`.
+- **Formatting**: Use `dart format . --line-length 80`. Run on every commit.
+- **DCM**: Use `dart_code_metrics` for complexity checks (Max cyclomatic complexity: 15).
+- **Build Runner**: Always use `--delete-conflicting-outputs` with code generation.
+- **CI Pipeline**: All PRs MUST pass `analyze`, `format`, and `test` steps.
+- **Imports**: Group imports: `dart:`, `package:`, then relative.
+- **Documentation**: Use `///` for public APIs. Link symbols using `[Class]`.
+
+## Code
+
+```yaml
+# analysis_options.yaml
+analyzer:
+  errors:
+    todo: ignore
+    missing_required_param: error
+linter:
+  rules:
+    - prefer_single_quotes
+    - unawaited_futures
+```
+
+## Related Topics
+
+language | testing

package/rules/dotnet/aspnet-core/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: ASP.NET Core Web API
+description: Modern ASP.NET Core patterns for building RESTful APIs.
+metadata:
+  labels: [aspnet, webapi, rest, minimal-api]
+  triggers:
+    files: ['**/*.cs', 'Program.cs']
+    keywords: [WebApplication, MapGet, MapPost, Controller, ApiController]
+---
+
+# ASP.NET Core Web API
+
+## **Priority: P1 (OPERATIONAL)**
+
+Modern ASP.NET Core patterns for building RESTful APIs.
+
+## Implementation Guidelines
+
+- **Minimal APIs**: Use for simple endpoints. `app.MapGet()`, route groups, endpoint filters.
+- **Controllers**: Use `[ApiController]` for automatic model validation and binding.
+- **Middleware**: Order matters. Custom middleware with `app.Use()`.
+- **Filters**: Action filters for cross-cutting concerns. Exception filters for error handling.
+- **Validation**: FluentValidation or DataAnnotations. Return `ProblemDetails` on errors.
+- **Versioning**: URL-based (`/api/v1/`) or header-based versioning.
+- **OpenAPI**: Always configure Swagger for API documentation.
+- **Response Types**: Use `TypedResults` for compile-time safety.
+
+## Anti-Patterns
+
+- **No `HttpClient` without `IHttpClientFactory`**: Socket exhaustion risk.
+- **No blocking async**: Never `.Result` or `.Wait()` in controllers.
+- **No business logic in controllers**: Controllers should only orchestrate.
+- **No returning `Task` without `async`**: Use `async` keyword or return directly.
+
+## Code
+
+```csharp
+// Minimal API with route groups
+var app = WebApplication.CreateBuilder(args).Build();
+
+var users = app.MapGroup("/api/users")
+    .WithTags("Users")
+    .RequireAuthorization();
+
+users.MapGet("/", async (IUserService service) =>
+    TypedResults.Ok(await service.GetAllAsync()));
+
+users.MapGet("/{id:int}", async (int id, IUserService service) =>
+    await service.GetByIdAsync(id) is { } user
+        ? TypedResults.Ok(user)
+        : TypedResults.NotFound());
+
+users.MapPost("/", async (CreateUserDto dto, IUserService service) =>
+{
+    var user = await service.CreateAsync(dto);
+    return TypedResults.Created($"/api/users/{user.Id}", user);
+}).AddEndpointFilter<ValidationFilter<CreateUserDto>>();
+
+// Controller with proper patterns
+[ApiController]
+[Route("api/[controller]")]
+[Produces("application/json")]
+public class OrdersController(IOrderService orderService) : ControllerBase
+{
+    [HttpGet("{id:int}")]
+    [ProducesResponseType<OrderDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetOrder(int id, CancellationToken ct)
+    {
+        var order = await orderService.GetByIdAsync(id, ct);
+        return order is null ? NotFound() : Ok(order);
+    }
+
+    [HttpPost]
+    [ProducesResponseType<OrderDto>(StatusCodes.Status201Created)]
+    [ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> CreateOrder(CreateOrderDto dto, CancellationToken ct)
+    {
+        var order = await orderService.CreateAsync(dto, ct);
+        return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
+    }
+}
+```
+
+## Reference & Examples
+
+For middleware, exception handling, and HttpClientFactory:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+security | razor-pages | blazor