aigroup-workflow 2.1.1 → 2.2.0

package/skills/java/spring-boot-engineer/references/web.md

@@ -0,0 +1,295 @@
+# Web Layer - Controllers & REST APIs
+
+## REST Controller Pattern
+
+```java
+@RestController
+@RequestMapping("/api/v1/users")
+@Validated
+@RequiredArgsConstructor
+public class UserController {
+    private final UserService userService;
+
+    @GetMapping
+    public ResponseEntity<Page<UserResponse>> getUsers(
+            @PageableDefault(size = 20, sort = "createdAt") Pageable pageable) {
+        Page<UserResponse> users = userService.findAll(pageable);
+        return ResponseEntity.ok(users);
+    }
+
+    @GetMapping("/{id}")
+    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
+        UserResponse user = userService.findById(id);
+        return ResponseEntity.ok(user);
+    }
+
+    @PostMapping
+    public ResponseEntity<UserResponse> createUser(
+            @Valid @RequestBody UserCreateRequest request) {
+        UserResponse user = userService.create(request);
+        URI location = ServletUriComponentsBuilder
+                .fromCurrentRequest()
+                .path("/{id}")
+                .buildAndExpand(user.id())
+                .toUri();
+        return ResponseEntity.created(location).body(user);
+    }
+
+    @PutMapping("/{id}")
+    public ResponseEntity<UserResponse> updateUser(
+            @PathVariable Long id,
+            @Valid @RequestBody UserUpdateRequest request) {
+        UserResponse user = userService.update(id, request);
+        return ResponseEntity.ok(user);
+    }
+
+    @DeleteMapping("/{id}")
+    @ResponseStatus(HttpStatus.NO_CONTENT)
+    public void deleteUser(@PathVariable Long id) {
+        userService.delete(id);
+    }
+}
+```
+
+## Request DTOs with Validation
+
+```java
+public record UserCreateRequest(
+    @NotBlank(message = "Email is required")
+    @Email(message = "Email must be valid")
+    String email,
+
+    @NotBlank(message = "Password is required")
+    @Size(min = 8, max = 100, message = "Password must be 8-100 characters")
+    @Pattern(regexp = "^(?=.*[A-Z])(?=.*[a-z])(?=.*\\d).*$",
+             message = "Password must contain uppercase, lowercase, and digit")
+    String password,
+
+    @NotBlank(message = "Username is required")
+    @Size(min = 3, max = 50)
+    @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "Username must be alphanumeric")
+    String username,
+
+    @Min(value = 18, message = "Must be at least 18")
+    @Max(value = 120, message = "Must be at most 120")
+    Integer age
+) {}
+
+public record UserUpdateRequest(
+    @Email(message = "Email must be valid")
+    String email,
+
+    @Size(min = 3, max = 50)
+    String username
+) {}
+```
+
+## Response DTOs
+
+```java
+public record UserResponse(
+    Long id,
+    String email,
+    String username,
+    Integer age,
+    Boolean active,
+    LocalDateTime createdAt,
+    LocalDateTime updatedAt
+) {
+    public static UserResponse from(User user) {
+        return new UserResponse(
+            user.getId(),
+            user.getEmail(),
+            user.getUsername(),
+            user.getAge(),
+            user.getActive(),
+            user.getCreatedAt(),
+            user.getUpdatedAt()
+        );
+    }
+}
+```
+
+## Global Exception Handling
+
+```java
+@RestControllerAdvice
+@Slf4j
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(ResourceNotFoundException.class)
+    public ResponseEntity<ErrorResponse> handleNotFound(
+            ResourceNotFoundException ex, WebRequest request) {
+        log.error("Resource not found: {}", ex.getMessage());
+        ErrorResponse error = new ErrorResponse(
+            HttpStatus.NOT_FOUND.value(),
+            ex.getMessage(),
+            request.getDescription(false),
+            LocalDateTime.now()
+        );
+        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ValidationErrorResponse> handleValidation(
+            MethodArgumentNotValidException ex) {
+        Map<String, String> errors = ex.getBindingResult()
+            .getFieldErrors()
+            .stream()
+            .collect(Collectors.toMap(
+                FieldError::getField,
+                error -> error.getDefaultMessage() != null
+                    ? error.getDefaultMessage()
+                    : "Invalid value"
+            ));
+
+        ValidationErrorResponse response = new ValidationErrorResponse(
+            HttpStatus.BAD_REQUEST.value(),
+            "Validation failed",
+            errors,
+            LocalDateTime.now()
+        );
+        return new ResponseEntity<>(response, HttpStatus.BAD_REQUEST);
+    }
+
+    @ExceptionHandler(DataIntegrityViolationException.class)
+    public ResponseEntity<ErrorResponse> handleDataIntegrity(
+            DataIntegrityViolationException ex, WebRequest request) {
+        log.error("Data integrity violation", ex);
+        ErrorResponse error = new ErrorResponse(
+            HttpStatus.CONFLICT.value(),
+            "Data integrity violation - resource may already exist",
+            request.getDescription(false),
+            LocalDateTime.now()
+        );
+        return new ResponseEntity<>(error, HttpStatus.CONFLICT);
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ErrorResponse> handleGlobalException(
+            Exception ex, WebRequest request) {
+        log.error("Unexpected error", ex);
+        ErrorResponse error = new ErrorResponse(
+            HttpStatus.INTERNAL_SERVER_ERROR.value(),
+            "An unexpected error occurred",
+            request.getDescription(false),
+            LocalDateTime.now()
+        );
+        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
+    }
+}
+
+record ErrorResponse(
+    int status,
+    String message,
+    String path,
+    LocalDateTime timestamp
+) {}
+
+record ValidationErrorResponse(
+    int status,
+    String message,
+    Map<String, String> errors,
+    LocalDateTime timestamp
+) {}
+```
+
+## Custom Validation
+
+```java
+@Target({ElementType.FIELD, ElementType.PARAMETER})
+@Retention(RetentionPolicy.RUNTIME)
+@Constraint(validatedBy = UniqueEmailValidator.class)
+public @interface UniqueEmail {
+    String message() default "Email already exists";
+    Class<?>[] groups() default {};
+    Class<? extends Payload>[] payload() default {};
+}
+
+@Component
+@RequiredArgsConstructor
+public class UniqueEmailValidator implements ConstraintValidator<UniqueEmail, String> {
+    private final UserRepository userRepository;
+
+    @Override
+    public boolean isValid(String email, ConstraintValidatorContext context) {
+        if (email == null) return true;
+        return !userRepository.existsByEmail(email);
+    }
+}
+```
+
+## WebClient for External APIs
+
+```java
+@Configuration
+public class WebClientConfig {
+    @Bean
+    public WebClient webClient(WebClient.Builder builder) {
+        return builder
+            .baseUrl("https://api.example.com")
+            .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
+            .filter(logRequest())
+            .build();
+    }
+
+    private ExchangeFilterFunction logRequest() {
+        return ExchangeFilterFunction.ofRequestProcessor(request -> {
+            log.info("Request: {} {}", request.method(), request.url());
+            return Mono.just(request);
+        });
+    }
+}
+
+@Service
+@RequiredArgsConstructor
+public class ExternalApiService {
+    private final WebClient webClient;
+
+    public Mono<ExternalDataResponse> fetchData(String id) {
+        return webClient
+            .get()
+            .uri("/data/{id}", id)
+            .retrieve()
+            .onStatus(HttpStatusCode::is4xxClientError, response ->
+                Mono.error(new ResourceNotFoundException("External resource not found")))
+            .onStatus(HttpStatusCode::is5xxServerError, response ->
+                Mono.error(new ServiceUnavailableException("External service unavailable")))
+            .bodyToMono(ExternalDataResponse.class)
+            .timeout(Duration.ofSeconds(5))
+            .retry(3);
+    }
+}
+```
+
+## CORS Configuration
+
+```java
+@Configuration
+public class WebConfig implements WebMvcConfigurer {
+
+    @Override
+    public void addCorsMappings(CorsRegistry registry) {
+        registry.addMapping("/api/**")
+            .allowedOrigins("http://localhost:3000", "https://example.com")
+            .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
+            .allowedHeaders("*")
+            .allowCredentials(true)
+            .maxAge(3600);
+    }
+}
+```
+
+## Quick Reference
+
+| Annotation | Purpose |
+|------------|---------|
+| `@RestController` | Marks class as REST controller (combines @Controller + @ResponseBody) |
+| `@RequestMapping` | Maps HTTP requests to handler methods |
+| `@GetMapping/@PostMapping` | HTTP method-specific mappings |
+| `@PathVariable` | Extracts values from URI path |
+| `@RequestParam` | Extracts query parameters |
+| `@RequestBody` | Binds request body to method parameter |
+| `@Valid` | Triggers validation on request body |
+| `@RestControllerAdvice` | Global exception handling for REST controllers |
+| `@ResponseStatus` | Sets HTTP status code for method |

package/skills/javascript/javascript-pro/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: javascript-pro
+description: Writes, debugs, and refactors JavaScript code using modern ES2023+ features, async/await patterns, ESM module systems, and Node.js APIs. Use when building vanilla JavaScript applications, implementing Promise-based async flows, optimising browser or Node.js performance, working with Web Workers or Fetch API, or reviewing .js/.mjs/.cjs files for correctness and best practices.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: language
+  triggers: JavaScript, ES2023, async await, Node.js, vanilla JavaScript, Web Workers, Fetch API, browser API, module system
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian
+---
+
+# JavaScript Pro
+
+## When to Use This Skill
+
+- Building vanilla JavaScript applications
+- Implementing async/await patterns and Promise handling
+- Working with modern module systems (ESM/CJS)
+- Optimizing browser performance and memory usage
+- Developing Node.js backend services
+- Implementing Web Workers, Service Workers, or browser APIs
+
+## Core Workflow
+
+1. **Analyze requirements** — Review `package.json`, module system, Node version, browser targets; confirm `.js`/`.mjs`/`.cjs` conventions
+2. **Design architecture** — Plan modules, async flows, and error handling strategies
+3. **Implement** — Write ES2023+ code with proper patterns and optimisations
+4. **Validate** — Run linter (`eslint --fix`); if linter fails, fix all reported issues and re-run before proceeding. Check for memory leaks with DevTools or `--inspect`, verify bundle size; if leaks are found, resolve them before continuing
+5. **Test** — Write comprehensive tests with Jest achieving 85%+ coverage; if coverage falls short, add missing cases and re-run. Confirm no unhandled Promise rejections
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Modern Syntax | `references/modern-syntax.md` | ES2023+ features, optional chaining, private fields |
+| Async Patterns | `references/async-patterns.md` | Promises, async/await, error handling, event loop |
+| Modules | `references/modules.md` | ESM vs CJS, dynamic imports, package.json exports |
+| Browser APIs | `references/browser-apis.md` | Fetch, Web Workers, Storage, IntersectionObserver |
+| Node Essentials | `references/node-essentials.md` | fs/promises, streams, EventEmitter, worker threads |
+
+## Constraints
+
+### MUST DO
+- Use ES2023+ features exclusively
+- Use `X | null` or `X | undefined` patterns
+- Use optional chaining (`?.`) and nullish coalescing (`??`)
+- Use async/await for all asynchronous operations
+- Use ESM (`import`/`export`) for new projects
+- Implement proper error handling with try/catch
+- Add JSDoc comments for complex functions
+- Follow functional programming principles
+
+### MUST NOT DO
+- Use `var` (always use `const` or `let`)
+- Use callback-based patterns (prefer Promises)
+- Mix CommonJS and ESM in the same module
+- Ignore memory leaks or performance issues
+- Skip error handling in async functions
+- Use synchronous I/O in Node.js
+- Mutate function parameters
+- Create blocking operations in the browser
+
+## Key Patterns with Examples
+
+### Async/Await Error Handling
+```js
+// ✅ Correct — always handle async errors explicitly
+async function fetchUser(id) {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return await response.json();
+  } catch (err) {
+    console.error("fetchUser failed:", err);
+    return null;
+  }
+}
+
+// ❌ Incorrect — unhandled rejection, no null guard
+async function fetchUser(id) {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();
+}
+```
+
+### Optional Chaining & Nullish Coalescing
+```js
+// ✅ Correct
+const city = user?.address?.city ?? "Unknown";
+
+// ❌ Incorrect — throws if address is undefined
+const city = user.address.city || "Unknown";
+```
+
+### ESM Module Structure
+```js
+// ✅ Correct — named exports, no default-only exports for libraries
+// utils/math.mjs
+export const add = (a, b) => a + b;
+export const multiply = (a, b) => a * b;
+
+// consumer.mjs
+import { add } from "./utils/math.mjs";
+
+// ❌ Incorrect — mixing require() with ESM
+const { add } = require("./utils/math.mjs");
+```
+
+### Avoid var / Prefer const
+```js
+// ✅ Correct
+const MAX_RETRIES = 3;
+let attempts = 0;
+
+// ❌ Incorrect
+var MAX_RETRIES = 3;
+var attempts = 0;
+```
+
+## Output Templates
+
+When implementing JavaScript features, provide:
+1. Module file with clean exports
+2. Test file with comprehensive coverage
+3. JSDoc documentation for public APIs
+4. Brief explanation of patterns used