@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/image-processing.md

@@ -0,0 +1,350 @@
+---
+name: image-processing
+description: Image processing patterns with Sharp for resizing, format conversion, CDN optimization, responsive images, and lazy loading.
+---
+
+# Image Processing Patterns
+
+## When to Use
+Apply image processing when your application handles user uploads, serves responsive images, or needs to optimize assets for web delivery. Sharp is the go-to library for server-side processing due to its speed (libvips-based). These patterns cover resizing, format conversion (WebP/AVIF), CDN integration, responsive srcset generation, and lazy loading strategies. Implement these patterns at upload time and at build time to minimize runtime processing.
+
+## How It Works
+
+### Sharp Processing Pipeline
+
+```typescript
+// src/images/processor.ts
+import sharp from 'sharp';
+import path from 'path';
+
+interface ProcessOptions {
+  width?: number;
+  height?: number;
+  quality?: number;
+  format?: 'webp' | 'avif' | 'jpeg' | 'png';
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+}
+
+export async function processImage(input: Buffer | string, options: ProcessOptions): Promise<Buffer> {
+  let pipeline = sharp(input);
+
+  // Auto-rotate based on EXIF
+  pipeline = pipeline.rotate();
+
+  // Resize
+  if (options.width || options.height) {
+    pipeline = pipeline.resize({
+      width: options.width,
+      height: options.height,
+      fit: options.fit ?? 'cover',
+      withoutEnlargement: true,
+    });
+  }
+
+  // Format conversion
+  const quality = options.quality ?? 80;
+  switch (options.format ?? 'webp') {
+    case 'webp':
+      pipeline = pipeline.webp({ quality, effort: 4 });
+      break;
+    case 'avif':
+      pipeline = pipeline.avif({ quality, effort: 4 });
+      break;
+    case 'jpeg':
+      pipeline = pipeline.jpeg({ quality, progressive: true, mozjpeg: true });
+      break;
+    case 'png':
+      pipeline = pipeline.png({ quality, compressionLevel: 9, palette: true });
+      break;
+  }
+
+  return pipeline.toBuffer();
+}
+
+export async function getImageMetadata(input: Buffer | string) {
+  const metadata = await sharp(input).metadata();
+  return {
+    width: metadata.width ?? 0,
+    height: metadata.height ?? 0,
+    format: metadata.format ?? 'unknown',
+    size: metadata.size ?? 0,
+    hasAlpha: metadata.hasAlpha ?? false,
+  };
+}
+```
+
+### Responsive Image Generation
+
+```typescript
+// src/images/responsive.ts
+import sharp from 'sharp';
+import path from 'path';
+import fs from 'fs/promises';
+
+interface ResponsiveConfig {
+  widths: number[];
+  formats: Array<'webp' | 'avif' | 'jpeg'>;
+  quality: number;
+}
+
+const defaultConfig: ResponsiveConfig = {
+  widths: [320, 640, 768, 1024, 1280, 1920],
+  formats: ['avif', 'webp', 'jpeg'],
+  quality: 80,
+};
+
+export async function generateResponsiveSet(
+  inputPath: string,
+  outputDir: string,
+  config: ResponsiveConfig = defaultConfig
+): Promise<Array<{ width: number; format: string; path: string; size: number }>> {
+  const results: Array<{ width: number; format: string; path: string; size: number }> = [];
+  const baseName = path.basename(inputPath, path.extname(inputPath));
+  const input = sharp(inputPath).rotate();
+  const metadata = await input.metadata();
+
+  await fs.mkdir(outputDir, { recursive: true });
+
+  for (const width of config.widths) {
+    if (width > (metadata.width ?? 0)) continue; // skip upscaling
+
+    for (const format of config.formats) {
+      const fileName = `${baseName}-${width}w.${format}`;
+      const outputPath = path.join(outputDir, fileName);
+
+      const buffer = await sharp(inputPath)
+        .rotate()
+        .resize({ width, withoutEnlargement: true })
+        [format]({ quality: config.quality })
+        .toBuffer();
+
+      await fs.writeFile(outputPath, buffer);
+
+      results.push({
+        width,
+        format,
+        path: outputPath,
+        size: buffer.length,
+      });
+    }
+  }
+
+  return results;
+}
+
+// Generate HTML picture element
+export function generatePictureElement(
+  images: Array<{ width: number; format: string; path: string }>,
+  alt: string,
+  sizes: string = '(max-width: 768px) 100vw, 50vw'
+): string {
+  const byFormat = new Map<string, typeof images>();
+  for (const img of images) {
+    const list = byFormat.get(img.format) ?? [];
+    list.push(img);
+    byFormat.set(img.format, list);
+  }
+
+  const sources = ['avif', 'webp'].map((format) => {
+    const formatImages = byFormat.get(format);
+    if (!formatImages) return '';
+    const srcset = formatImages.map((i) => `${i.path} ${i.width}w`).join(', ');
+    return `<source type="image/${format}" srcset="${srcset}" sizes="${sizes}" />`;
+  }).filter(Boolean).join('\n  ');
+
+  const fallback = byFormat.get('jpeg')?.[0];
+
+  return `<picture>
+  ${sources}
+  <img src="${fallback?.path}" alt="${alt}" loading="lazy" decoding="async" sizes="${sizes}" />
+</picture>`;
+}
+```
+
+### Upload Processing Pipeline
+
+```typescript
+// src/images/upload-handler.ts
+import { Router } from 'express';
+import multer from 'multer';
+import { processImage, getImageMetadata } from './processor';
+
+const upload = multer({
+  limits: { fileSize: 10 * 1024 * 1024 }, // 10MB max
+  fileFilter: (_req, file, cb) => {
+    const allowed = ['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/avif'];
+    cb(null, allowed.includes(file.mimetype));
+  },
+});
+
+const router = Router();
+
+router.post('/api/images/upload', upload.single('image'), async (req, res) => {
+  if (!req.file) return res.status(400).json({ error: 'No image file provided' });
+
+  const metadata = await getImageMetadata(req.file.buffer);
+
+  // Generate multiple sizes
+  const variants = await Promise.all([
+    processImage(req.file.buffer, { width: 150, height: 150, format: 'webp', fit: 'cover' })
+      .then((buf) => ({ name: 'thumbnail', buffer: buf })),
+    processImage(req.file.buffer, { width: 800, format: 'webp' })
+      .then((buf) => ({ name: 'medium', buffer: buf })),
+    processImage(req.file.buffer, { width: 1920, format: 'webp' })
+      .then((buf) => ({ name: 'large', buffer: buf })),
+    processImage(req.file.buffer, { width: 1920, format: 'avif' })
+      .then((buf) => ({ name: 'large-avif', buffer: buf })),
+  ]);
+
+  // Upload all variants to storage
+  const urls: Record<string, string> = {};
+  for (const variant of variants) {
+    const key = `images/${req.userId}/${Date.now()}-${variant.name}`;
+    urls[variant.name] = await uploadToStorage(key, variant.buffer);
+  }
+
+  // Generate blur placeholder
+  const placeholder = await sharp(req.file.buffer)
+    .resize(20, 20, { fit: 'inside' })
+    .blur()
+    .toBuffer();
+  const blurDataURL = `data:image/jpeg;base64,${placeholder.toString('base64')}`;
+
+  res.json({
+    urls,
+    metadata: { width: metadata.width, height: metadata.height, format: metadata.format },
+    placeholder: blurDataURL,
+  });
+});
+
+export default router;
+```
+
+### CDN-Optimized Image Serving
+
+```typescript
+// src/images/cdn-handler.ts
+import { Router } from 'express';
+import sharp from 'sharp';
+
+const router = Router();
+
+// On-demand image transformation: /images/:key?w=800&f=webp&q=80
+router.get('/images/:key(*)', async (req, res) => {
+  const { w, h, f, q, fit } = req.query;
+  const width = w ? parseInt(w as string) : undefined;
+  const height = h ? parseInt(h as string) : undefined;
+  const format = (f as 'webp' | 'avif' | 'jpeg') ?? 'webp';
+  const quality = q ? parseInt(q as string) : 80;
+
+  // Check cache first
+  const cacheKey = `img:${req.params.key}:${width}:${height}:${format}:${quality}`;
+  const cached = await cache.get(cacheKey);
+  if (cached) {
+    res.set({
+      'Content-Type': `image/${format}`,
+      'Cache-Control': 'public, max-age=31536000, immutable',
+    });
+    return res.send(cached);
+  }
+
+  // Fetch original
+  const original = await fetchFromStorage(req.params.key);
+  if (!original) return res.status(404).send('Image not found');
+
+  // Transform
+  const result = await processImage(original, {
+    width, height, format, quality,
+    fit: (fit as any) ?? 'cover',
+  });
+
+  // Cache transformed result
+  await cache.set(cacheKey, result, 86400);
+
+  res.set({
+    'Content-Type': `image/${format}`,
+    'Cache-Control': 'public, max-age=31536000, immutable',
+    'Vary': 'Accept',
+  });
+
+  res.send(result);
+});
+
+export default router;
+```
+
+### React Lazy Loading Component
+
+```tsx
+// src/components/OptimizedImage.tsx
+import { useState, useRef, useEffect } from 'react';
+
+interface OptimizedImageProps {
+  src: string;
+  alt: string;
+  width: number;
+  height: number;
+  placeholder?: string; // blur data URL
+  sizes?: string;
+  className?: string;
+  priority?: boolean;
+}
+
+export function OptimizedImage({
+  src, alt, width, height, placeholder, sizes, className, priority,
+}: OptimizedImageProps) {
+  const [loaded, setLoaded] = useState(false);
+  const imgRef = useRef<HTMLImageElement>(null);
+
+  useEffect(() => {
+    if (imgRef.current?.complete) setLoaded(true);
+  }, []);
+
+  const srcSet = [320, 640, 1024, 1920]
+    .map((w) => `${src}?w=${w}&f=webp ${w}w`)
+    .join(', ');
+
+  return (
+    <div className="relative overflow-hidden" style={{ aspectRatio: `${width}/${height}` }}>
+      {placeholder && !loaded && (
+        <img src={placeholder} alt="" aria-hidden className="absolute inset-0 w-full h-full object-cover blur-lg scale-110" />
+      )}
+      <picture>
+        <source type="image/avif" srcSet={srcSet.replace(/f=webp/g, 'f=avif')} sizes={sizes} />
+        <source type="image/webp" srcSet={srcSet} sizes={sizes} />
+        <img
+          ref={imgRef}
+          src={`${src}?w=1024&f=jpeg`}
+          alt={alt}
+          width={width}
+          height={height}
+          sizes={sizes ?? '100vw'}
+          loading={priority ? 'eager' : 'lazy'}
+          decoding={priority ? 'sync' : 'async'}
+          onLoad={() => setLoaded(true)}
+          className={`${className ?? ''} transition-opacity duration-300 ${loaded ? 'opacity-100' : 'opacity-0'}`}
+        />
+      </picture>
+    </div>
+  );
+}
+```
+
+## Examples
+
+| Format | Quality 80 Size | Browser Support | Use Case |
+|--------|----------------|-----------------|----------|
+| AVIF | ~40% of JPEG | Chrome, Firefox | Best compression, modern browsers |
+| WebP | ~60% of JPEG | All modern | Good balance of quality and support |
+| JPEG | Baseline | Universal | Fallback for all browsers |
+| PNG | Lossless | Universal | Screenshots, graphics with transparency |
+
+## Checklist
+- [ ] Images auto-rotated based on EXIF orientation before processing
+- [ ] Multiple sizes generated at upload time (thumbnail, medium, large)
+- [ ] AVIF and WebP variants served with JPEG fallback via `<picture>`
+- [ ] Blur placeholder generated for progressive loading experience
+- [ ] `loading="lazy"` and `decoding="async"` on below-fold images
+- [ ] Width and height attributes set to prevent layout shift (CLS)
+- [ ] CDN Cache-Control headers set with long TTL and immutable
+- [ ] Upload handler validates file type and enforces size limits

package/assets/skills/java-springboot.md

@@ -0,0 +1,226 @@
+---
+name: java-springboot
+description: Spring Boot patterns for dependency injection, JPA, security, actuator, profiles, and testing.
+---
+
+# Spring Boot Patterns
+
+## When to Use
+
+Apply these patterns when building Spring Boot 3.x applications with Java 17+.
+Use this skill for structuring services with dependency injection, mapping JPA
+entities, configuring Spring Security, exposing health checks via Actuator, and
+writing integration tests.
+
+## How It Works
+
+### Dependency Injection
+
+Use constructor injection exclusively. Avoid `@Autowired` on fields. Spring
+auto-detects single-constructor beans. Use `@Qualifier` only when multiple
+implementations exist.
+
+```java
+@Service
+public class OrderService {
+    private final OrderRepository orderRepo;
+    private final PaymentGateway paymentGateway;
+
+    // No @Autowired needed with single constructor
+    public OrderService(OrderRepository orderRepo, PaymentGateway paymentGateway) {
+        this.orderRepo = orderRepo;
+        this.paymentGateway = paymentGateway;
+    }
+
+    public Order place(CreateOrderRequest req) {
+        Order order = Order.from(req);
+        paymentGateway.charge(order.total());
+        return orderRepo.save(order);
+    }
+}
+```
+
+### JPA Entities
+
+Use `@Entity` with explicit table and column names. Prefer `IDENTITY` generation
+for PostgreSQL. Always override `equals`/`hashCode` based on the business key,
+not the generated ID.
+
+```java
+@Entity
+@Table(name = "orders")
+public class Order {
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false, unique = true, length = 36)
+    private String orderNumber;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false)
+    private OrderStatus status;
+
+    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
+    private List<OrderItem> items = new ArrayList<>();
+
+    @Override
+    public boolean equals(Object o) {
+        if (this == o) return true;
+        if (!(o instanceof Order other)) return false;
+        return orderNumber != null && orderNumber.equals(other.orderNumber);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(orderNumber);
+    }
+}
+```
+
+### Repository Layer
+
+Use Spring Data JPA interfaces. Add custom queries with `@Query` for complex
+lookups. Use projections for read-only DTOs.
+
+```java
+public interface OrderRepository extends JpaRepository<Order, Long> {
+    Optional<Order> findByOrderNumber(String orderNumber);
+
+    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.status = :status")
+    List<Order> findByStatusWithItems(@Param("status") OrderStatus status);
+
+    @Query("SELECT new com.example.dto.OrderSummary(o.orderNumber, o.status, o.createdAt) FROM Order o")
+    Page<OrderSummary> findSummaries(Pageable pageable);
+}
+```
+
+### Spring Security
+
+Use `SecurityFilterChain` bean configuration (not `WebSecurityConfigurerAdapter`).
+Extract JWT claims into a custom `UserDetails`.
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class SecurityConfig {
+    @Bean
+    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(csrf -> csrf.disable())
+            .sessionManagement(sm -> sm.sessionCreationPolicy(STATELESS))
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public/**").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated()
+            )
+            .oauth2ResourceServer(oauth -> oauth.jwt(Customizer.withDefaults()))
+            .build();
+    }
+}
+```
+
+### Actuator and Health Checks
+
+Expose `/actuator/health` for load balancers. Add custom health indicators for
+downstream dependencies.
+
+```java
+@Component
+public class DatabaseHealthIndicator implements HealthIndicator {
+    private final DataSource dataSource;
+
+    public DatabaseHealthIndicator(DataSource dataSource) {
+        this.dataSource = dataSource;
+    }
+
+    @Override
+    public Health health() {
+        try (Connection conn = dataSource.getConnection()) {
+            if (conn.isValid(2)) {
+                return Health.up().withDetail("database", "reachable").build();
+            }
+        } catch (SQLException e) {
+            return Health.down(e).build();
+        }
+        return Health.down().build();
+    }
+}
+```
+
+### Profiles
+
+Use `application-{profile}.yml` for environment-specific config. Activate with
+`SPRING_PROFILES_ACTIVE=prod`. Keep `application.yml` for defaults.
+
+```yaml
+# application.yml (defaults)
+spring:
+  jpa:
+    open-in-view: false
+
+# application-prod.yml
+spring:
+  datasource:
+    url: ${DATABASE_URL}
+    hikari:
+      maximum-pool-size: 20
+```
+
+### Testing
+
+Use `@SpringBootTest` sparingly (slow). Prefer `@WebMvcTest` for controllers,
+`@DataJpaTest` for repositories. Use `@MockBean` to replace dependencies.
+
+```java
+@WebMvcTest(OrderController.class)
+class OrderControllerTest {
+    @Autowired MockMvc mockMvc;
+    @MockBean OrderService orderService;
+
+    @Test
+    void getOrder_returnsOrder() throws Exception {
+        when(orderService.findByNumber("ORD-001"))
+            .thenReturn(Optional.of(testOrder()));
+
+        mockMvc.perform(get("/api/orders/ORD-001"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.orderNumber").value("ORD-001"));
+    }
+
+    @Test
+    void getOrder_notFound_returns404() throws Exception {
+        when(orderService.findByNumber("MISSING"))
+            .thenReturn(Optional.empty());
+
+        mockMvc.perform(get("/api/orders/MISSING"))
+            .andExpect(status().isNotFound());
+    }
+}
+```
+
+## Examples
+
+**Pattern: Global exception handler**
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+    @ExceptionHandler(EntityNotFoundException.class)
+    ResponseEntity<ErrorResponse> handleNotFound(EntityNotFoundException ex) {
+        return ResponseEntity.status(404).body(new ErrorResponse("NOT_FOUND", ex.getMessage()));
+    }
+}
+```
+
+## Checklist
+
+- [ ] Constructor injection only (no `@Autowired` on fields)
+- [ ] JPA entities have `equals`/`hashCode` on business key, not generated ID
+- [ ] `@Query` with `JOIN FETCH` to prevent N+1 queries
+- [ ] `open-in-view: false` in application config
+- [ ] Security config uses `SecurityFilterChain` bean, not deprecated adapter
+- [ ] Actuator health endpoint exposed; custom indicators for critical dependencies
+- [ ] Profile-specific configs in `application-{profile}.yml`
+- [ ] `@WebMvcTest` / `@DataJpaTest` over `@SpringBootTest` where possible
+- [ ] `@Transactional` on service methods that do multiple writes
+- [ ] `@RestControllerAdvice` for centralized exception handling