maestro-bundle 1.3.0 → 1.4.0

package/templates/bundle-frontend-spa/skills/responsive-layout/references/breakpoint-guide.md

@@ -0,0 +1,63 @@
+# Tailwind Breakpoint Guide
+
+## Breakpoints
+| Prefix | Min-width | Device Target |
+|---|---|---|
+| (none) | 0px | Mobile phones (portrait) |
+| `sm:` | 640px | Mobile phones (landscape) |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Laptops / small desktops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large monitors |
+
+## Mobile-First Pattern
+```html
+<!-- Start with mobile, add overrides -->
+<div class="
+  grid grid-cols-1    /* mobile: 1 column */
+  sm:grid-cols-2      /* 640px+: 2 columns */
+  lg:grid-cols-4      /* 1024px+: 4 columns */
+  gap-4
+">
+```
+
+## Common Responsive Patterns
+
+### Sidebar Layout
+```html
+<!-- Hidden on mobile, visible on desktop -->
+<aside class="hidden lg:block w-64">
+
+<!-- Full-width on mobile, fixed width on desktop -->
+<aside class="fixed lg:static w-64 -translate-x-full lg:translate-x-0">
+```
+
+### Content Padding
+```html
+<main class="p-4 md:p-6 lg:p-8">
+```
+
+### Text Sizing
+```html
+<h1 class="text-xl md:text-2xl lg:text-3xl">
+```
+
+### Show/Hide Elements
+```html
+<!-- Mobile only -->
+<button class="lg:hidden">Menu</button>
+
+<!-- Desktop only -->
+<nav class="hidden lg:flex">
+```
+
+### Container
+```html
+<div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+```
+
+## Testing Responsive Design
+1. Browser DevTools device toolbar (Ctrl+Shift+M)
+2. Drag browser edge to resize manually
+3. Test at exact breakpoints: 639px, 640px, 767px, 768px, 1023px, 1024px
+4. Test with actual mobile devices if possible

package/templates/bundle-frontend-spa/skills/state-management/SKILL.md

@@ -1,66 +1,144 @@
 ---
 name: state-management
-description: Gerenciar estado com Zustand para estado global e React Query para server state. Use quando precisar gerenciar estado da aplicação, cache de API, ou estado compartilhado entre componentes.
+description: Manage application state with Zustand for global UI state and React Query for server state. Use when you need to manage global state, cache API data, sync real-time WebSocket data, or decide which state solution to use.
+version: 1.0.0
+author: Maestro
 ---
 
 # State Management
 
-## Regra de ouro
+Choose and implement the right state management solution for each type of state using Zustand, React Query, and React Hook Form.
 
-| Tipo de estado | Solução | Exemplo |
+## When to Use
+- User needs to decide between Zustand, React Query, or useState
+- User wants to create a global UI store (sidebar, theme, selections)
+- User needs to set up server state caching with React Query
+- User wants to add real-time WebSocket state
+- User needs to manage complex form state
+
+## Available Operations
+1. Set up React Query provider and hooks for server state
+2. Create Zustand stores for global UI state
+3. Build WebSocket-connected stores for real-time data
+4. Configure React Hook Form for form state
+5. Diagnose and fix state management anti-patterns
+
+## Multi-Step Workflow
+
+### Step 1: Install Dependencies
+```bash
+npm install @tanstack/react-query zustand react-hook-form @hookform/resolvers zod socket.io-client
+npm install -D @tanstack/react-query-devtools
+```
+
+### Step 2: Understand the State Decision Matrix
+
+| State Type | Solution | Example |
 |---|---|---|
-| Server state (API data) | React Query | Lista de demands, dados de agentes |
-| UI state global | Zustand | Sidebar aberta, tema, user logado |
-| UI state local | useState | Modal aberto, input controlado |
-| Form state | React Hook Form | Dados do formulário, validação |
-| Real-time state | Zustand + WebSocket | Status dos agentes, eventos ao vivo |
+| Server data (API) | React Query | List of items, user profiles, search results |
+| Global UI state | Zustand | Sidebar open/closed, theme, selected item ID |
+| Local UI state | useState | Modal visibility, input value, toggle |
+| Form state | React Hook Form | Form inputs, validation, submission |
+| Real-time data | Zustand + WebSocket | Live agent status, event feed |
 
-## React Query — Server State
+### Step 3: Set Up React Query Provider
+```tsx
+// src/main.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 30_000,      // 30 seconds
+      retry: 2,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Router />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
+
+### Step 4: Create API Service and Query Hooks
 ```tsx
-// services/demandApi.ts
-export const demandApi = {
-  list: (filters?: DemandFilters) =>
-    api.get<PaginatedResponse<Demand>>('/api/v1/demands', { params: filters }),
+// src/services/itemApi.ts
+import { api } from '@/lib/api';
+
+export const itemApi = {
+  list: (filters?: ItemFilters) =>
+    api.get<PaginatedResponse<Item>>('/api/v1/items', { params: filters }),
   get: (id: string) =>
-    api.get<Demand>(`/api/v1/demands/${id}`),
-  create: (data: CreateDemandDto) =>
-    api.post<Demand>('/api/v1/demands', data),
+    api.get<Item>(`/api/v1/items/${id}`),
+  create: (data: CreateItemDto) =>
+    api.post<Item>('/api/v1/items', data),
 };
 
-// hooks/useDemands.ts — nunca duplicar dados da API no Zustand
-export function useDemands(filters?: DemandFilters) {
+// src/hooks/useItems.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+export function useItems(filters?: ItemFilters) {
   return useQuery({
-    queryKey: ['demands', filters],
-    queryFn: () => demandApi.list(filters),
+    queryKey: ['items', filters],
+    queryFn: () => itemApi.list(filters),
   });
 }
-```
 
-## Zustand — UI State Global
+export function useCreateItem() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: itemApi.create,
+    onSuccess: () => qc.invalidateQueries({ queryKey: ['items'] }),
+  });
+}
+```
 
+### Step 5: Create Zustand Store for UI State
 ```tsx
+// src/stores/useAppStore.ts
+import { create } from 'zustand';
+
 interface AppStore {
   sidebarOpen: boolean;
   toggleSidebar: () => void;
-  selectedDemandId: string | null;
-  selectDemand: (id: string | null) => void;
+  selectedItemId: string | null;
+  selectItem: (id: string | null) => void;
+  theme: 'light' | 'dark';
+  setTheme: (theme: 'light' | 'dark') => void;
 }
 
 export const useAppStore = create<AppStore>((set) => ({
   sidebarOpen: true,
   toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
-  selectedDemandId: null,
-  selectDemand: (id) => set({ selectedDemandId: id }),
+  selectedItemId: null,
+  selectItem: (id) => set({ selectedItemId: id }),
+  theme: 'light',
+  setTheme: (theme) => set({ theme }),
 }));
-```
 
-## WebSocket — Real-time
+// Usage in components:
+// const { sidebarOpen, toggleSidebar } = useAppStore();
+// Or with selector for performance:
+// const sidebarOpen = useAppStore((s) => s.sidebarOpen);
+```
 
+### Step 6: Add Real-Time WebSocket Store
 ```tsx
+// src/stores/useRealtimeStore.ts
+import { create } from 'zustand';
+import { io, type Socket } from 'socket.io-client';
+
 interface RealtimeStore {
   agentStatuses: Record<string, AgentStatus>;
   events: TrackingEvent[];
+  connected: boolean;
   connect: () => void;
   disconnect: () => void;
 }
@@ -71,8 +149,12 @@ export const useRealtimeStore = create<RealtimeStore>((set) => {
   return {
     agentStatuses: {},
     events: [],
+    connected: false,
+
     connect: () => {
-      socket = io(WS_URL);
+      socket = io(import.meta.env.VITE_WS_URL || 'http://localhost:8000');
+      socket.on('connect', () => set({ connected: true }));
+      socket.on('disconnect', () => set({ connected: false }));
       socket.on('agent:status', (data) =>
         set((s) => ({ agentStatuses: { ...s.agentStatuses, [data.agentId]: data.status } }))
       );
@@ -80,7 +162,53 @@ export const useRealtimeStore = create<RealtimeStore>((set) => {
         set((s) => ({ events: [event, ...s.events].slice(0, 100) }))
       );
     },
-    disconnect: () => socket?.disconnect(),
+
+    disconnect: () => {
+      socket?.disconnect();
+      socket = null;
+      set({ connected: false });
+    },
   };
 });
 ```
+
+### Step 7: Verify State Management
+```bash
+npm run dev
+# Open http://localhost:5173
+# Open React Query DevTools (floating button in bottom-right)
+# Verify: queries are cached, mutations invalidate correctly
+
+npx tsc --noEmit
+# Check for TypeScript errors in stores and hooks
+```
+
+## Resources
+- `references/state-patterns.md` - Common state patterns and anti-patterns
+- `references/react-query-config.md` - React Query configuration reference
+
+## Examples
+### Example 1: Add a Global Store
+User asks: "Create a store for managing the notification panel state"
+Response approach:
+1. Create `useNotificationStore` with Zustand
+2. Add state: `isOpen`, `unreadCount`, `notifications[]`
+3. Add actions: `toggle()`, `markRead(id)`, `addNotification()`
+4. Show usage in the NotificationPanel component
+5. Use selector pattern for performance
+
+### Example 2: Fix State Duplication
+User asks: "We have user data in both Zustand and React Query, which should we keep?"
+Response approach:
+1. Identify that server data belongs in React Query, not Zustand
+2. Remove user data from Zustand store
+3. Create `useCurrentUser()` hook with React Query
+4. Keep only the auth token in Zustand (UI state)
+5. Update components to use the new hook
+
+## Notes
+- Never duplicate API data in Zustand -- React Query is the source of truth for server state
+- Use selectors with Zustand to prevent unnecessary re-renders: `useAppStore(s => s.sidebarOpen)`
+- React Query DevTools are essential for debugging cache behavior
+- Keep Zustand stores small and focused -- one store per domain, not one mega-store
+- For WebSocket stores, always handle disconnect cleanup

package/templates/bundle-frontend-spa/skills/state-management/references/react-query-config.md

@@ -0,0 +1,64 @@
+# React Query Configuration Reference
+
+## QueryClient Defaults
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 30_000,          // how long data is "fresh" (ms)
+      gcTime: 5 * 60_000,         // garbage collection time (was cacheTime)
+      retry: 2,                   // retry failed requests
+      refetchOnWindowFocus: false, // disable refetch on tab focus
+      refetchOnReconnect: true,    // refetch on network reconnect
+    },
+    mutations: {
+      retry: 0,                   // don't retry mutations
+    },
+  },
+});
+```
+
+## Common Query Patterns
+```tsx
+// Basic query
+useQuery({ queryKey: ['items'], queryFn: api.list })
+
+// Query with parameters
+useQuery({ queryKey: ['items', filters], queryFn: () => api.list(filters) })
+
+// Conditional query
+useQuery({ queryKey: ['item', id], queryFn: () => api.get(id), enabled: !!id })
+
+// Polling
+useQuery({ queryKey: ['status'], queryFn: api.getStatus, refetchInterval: 5000 })
+```
+
+## Query Key Conventions
+```tsx
+// Entity list
+['items']
+['items', { status: 'active', page: 1 }]
+
+// Single entity
+['items', itemId]
+
+// Nested resource
+['items', itemId, 'comments']
+```
+
+## Cache Invalidation
+```tsx
+const qc = useQueryClient();
+
+// Invalidate all items queries
+qc.invalidateQueries({ queryKey: ['items'] });
+
+// Invalidate specific item
+qc.invalidateQueries({ queryKey: ['items', itemId] });
+
+// Set data directly (optimistic update)
+qc.setQueryData(['items', itemId], updatedItem);
+
+// Remove from cache
+qc.removeQueries({ queryKey: ['items', itemId] });
+```

package/templates/bundle-frontend-spa/skills/state-management/references/state-patterns.md

@@ -0,0 +1,78 @@
+# State Patterns and Anti-Patterns
+
+## Pattern: Selector-Based Zustand Access
+```tsx
+// GOOD: only re-renders when sidebarOpen changes
+const sidebarOpen = useAppStore((s) => s.sidebarOpen);
+
+// BAD: re-renders on ANY store change
+const { sidebarOpen } = useAppStore();
+```
+
+## Pattern: Optimistic Updates
+```tsx
+const mutation = useMutation({
+  mutationFn: api.update,
+  onMutate: async (newData) => {
+    await qc.cancelQueries({ queryKey: ['items'] });
+    const previous = qc.getQueryData(['items']);
+    qc.setQueryData(['items'], (old) => ({ ...old, ...newData }));
+    return { previous };
+  },
+  onError: (_, __, context) => {
+    qc.setQueryData(['items'], context?.previous);
+  },
+  onSettled: () => {
+    qc.invalidateQueries({ queryKey: ['items'] });
+  },
+});
+```
+
+## Anti-Pattern: Duplicating Server State
+```tsx
+// BAD: duplicating API data in Zustand
+const useStore = create((set) => ({
+  users: [],
+  fetchUsers: async () => {
+    const users = await api.getUsers();
+    set({ users });
+  },
+}));
+
+// GOOD: use React Query for server state
+function useUsers() {
+  return useQuery({ queryKey: ['users'], queryFn: api.getUsers });
+}
+```
+
+## Anti-Pattern: Mega Store
+```tsx
+// BAD: one store for everything
+const useMegaStore = create((set) => ({
+  sidebar: true,
+  theme: 'light',
+  users: [],
+  notifications: [],
+  // ...50 more fields
+}));
+
+// GOOD: separate stores by domain
+const useUIStore = create(/* UI state */);
+const useNotificationStore = create(/* notification state */);
+// Server state in React Query hooks
+```
+
+## Pattern: Persisted Zustand Store
+```tsx
+import { persist } from 'zustand/middleware';
+
+const useSettingsStore = create(
+  persist(
+    (set) => ({
+      theme: 'light',
+      setTheme: (theme) => set({ theme }),
+    }),
+    { name: 'settings-storage' }
+  )
+);
+```

package/templates/bundle-jhipster-microservices/skills/ci-cd-pipeline/SKILL.md

@@ -1,11 +1,31 @@
 ---
 name: ci-cd-pipeline
-description: Criar pipelines CI/CD com GitLab CI incluindo lint, test, build, compliance check e deploy. Use quando for configurar CI/CD, criar pipelines, ou automatizar deploy.
+description: Create CI/CD pipelines with GitLab CI for JHipster microservices including lint, test, build, compliance check, and deploy. Use when setting up CI/CD, creating pipelines, automating deployments, or adding quality gates.
+version: 1.0.0
+author: Maestro
 ---
 
-# CI/CD Pipeline — GitLab CI
+# CI/CD Pipeline
 
-## Pipeline completo
+Create and configure GitLab CI pipelines for JHipster microservices with stages for lint, test, security, compliance, build, and deploy.
+
+## When to Use
+- When setting up CI/CD for a new microservice
+- When adding quality gates (lint, test, security scan)
+- When automating Docker builds and pushes
+- When configuring deployment to K3s/Kubernetes
+- When adding compliance checks
+
+## Available Operations
+1. Create `.gitlab-ci.yml` with all stages
+2. Configure lint and test stages
+3. Set up Docker image build with Jib
+4. Configure deployment to Kubernetes
+5. Add security scanning
+
+## Multi-Step Workflow
+
+### Step 1: Create Pipeline File
 
 ```yaml
 # .gitlab-ci.yml
@@ -13,7 +33,6 @@ stages:
   - lint
   - test
   - security
-  - compliance
   - build
   - deploy-staging
   - deploy-prod
@@ -21,15 +40,23 @@ stages:
 variables:
   DOCKER_IMAGE: $CI_REGISTRY_IMAGE
   K3S_NAMESPACE: maestro
+  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"
 
-# ===== LINT =====
-lint:python:
+cache:
+  paths:
+    - .m2/repository/
+    - node_modules/
+```
+
+### Step 2: Add Lint and Test Stages
+
+```yaml
+lint:backend:
   stage: lint
-  image: python:3.11-slim
+  image: maven:3.9-eclipse-temurin-21
   script:
-    - pip install ruff mypy
-    - ruff check src/
-    - mypy src/ --ignore-missing-imports
+    - ./mvnw checkstyle:check -DskipTests
+    - ./mvnw pmd:check -DskipTests
 
 lint:frontend:
   stage: lint
@@ -37,76 +64,139 @@ lint:frontend:
   script:
     - npm ci
     - npm run lint
-    - npm run type-check
 
-# ===== TEST =====
 test:backend:
   stage: test
-  image: python:3.11-slim
+  image: maven:3.9-eclipse-temurin-21
   services:
     - postgres:16
-    - redis:7
   variables:
-    DATABASE_URL: postgresql://test:test@postgres/testdb
-    REDIS_URL: redis://redis:6379
+    SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/testdb
+    SPRING_DATASOURCE_USERNAME: test
+    SPRING_DATASOURCE_PASSWORD: test
   script:
-    - pip install -r requirements.txt
-    - pytest --cov=src --cov-report=xml --cov-fail-under=80
+    - ./mvnw verify -Pprod -DskipTests=false
+    - ./mvnw test -Dtest="*IT" -DfailIfNoTests=false
   artifacts:
     reports:
-      coverage_report:
-        coverage_format: cobertura
-        path: coverage.xml
+      junit: target/surefire-reports/*.xml
 
 test:frontend:
   stage: test
   image: node:20-slim
   script:
     - npm ci
-    - npm run test -- --coverage
+    - npm test -- --coverage
+```
+
+### Step 3: Add Security Scanning
 
-# ===== SECURITY =====
-security:scan:
+```yaml
+security:dependencies:
   stage: security
-  image: python:3.11-slim
+  image: maven:3.9-eclipse-temurin-21
   script:
-    - pip install bandit safety
-    - bandit -r src/ -ll
-    - safety check
+    - ./mvnw org.owasp:dependency-check-maven:check
+  allow_failure: true
+  artifacts:
+    paths:
+      - target/dependency-check-report.html
+```
 
-# ===== COMPLIANCE =====
-compliance:bundle:
-  stage: compliance
-  script:
-    - python scripts/check_bundle_compliance.py --bundle $BUNDLE_NAME
-    - python scripts/check_structure.py
-  allow_failure: false
+### Step 4: Add Docker Build
 
-# ===== BUILD =====
-build:api:
+```yaml
+build:image:
   stage: build
   script:
-    - docker build -f docker/Dockerfile.api -t $DOCKER_IMAGE/api:$CI_COMMIT_SHA .
-    - docker push $DOCKER_IMAGE/api:$CI_COMMIT_SHA
+    # Build with Jib (no Docker daemon needed)
+    - ./mvnw -ntp verify -DskipTests jib:build
+        -Djib.to.image=$DOCKER_IMAGE:$CI_COMMIT_SHA
+        -Djib.to.auth.username=$CI_REGISTRY_USER
+        -Djib.to.auth.password=$CI_REGISTRY_PASSWORD
   only:
     - main
     - develop
+```
+
+### Step 5: Add Deployment Stages
 
-# ===== DEPLOY =====
+```yaml
 deploy:staging:
   stage: deploy-staging
+  image: bitnami/kubectl:latest
   script:
-    - kubectl -n $K3S_NAMESPACE-staging set image deployment/api api=$DOCKER_IMAGE/api:$CI_COMMIT_SHA
-    - kubectl -n $K3S_NAMESPACE-staging rollout status deployment/api --timeout=120s
+    - kubectl -n $K3S_NAMESPACE-staging set image
+        deployment/$CI_PROJECT_NAME
+        app=$DOCKER_IMAGE:$CI_COMMIT_SHA
+    - kubectl -n $K3S_NAMESPACE-staging rollout status
+        deployment/$CI_PROJECT_NAME --timeout=120s
   only:
     - develop
 
 deploy:prod:
   stage: deploy-prod
+  image: bitnami/kubectl:latest
   script:
-    - kubectl -n $K3S_NAMESPACE set image deployment/api api=$DOCKER_IMAGE/api:$CI_COMMIT_SHA
-    - kubectl -n $K3S_NAMESPACE rollout status deployment/api --timeout=120s
+    - kubectl -n $K3S_NAMESPACE set image
+        deployment/$CI_PROJECT_NAME
+        app=$DOCKER_IMAGE:$CI_COMMIT_SHA
+    - kubectl -n $K3S_NAMESPACE rollout status
+        deployment/$CI_PROJECT_NAME --timeout=120s
   only:
     - main
-  when: manual
+  when: manual  # Requires manual approval
+```
+
+### Step 6: Verify Pipeline
+
+```bash
+# Validate gitlab-ci.yml syntax
+gitlab-ci-lint .gitlab-ci.yml
+
+# Or validate via GitLab API
+curl --header "PRIVATE-TOKEN: $TOKEN" \
+  "https://gitlab.local/api/v4/ci/lint" \
+  --form "content=@.gitlab-ci.yml"
+
+# Check pipeline status
+git push && echo "Check pipeline at: https://gitlab.local/$PROJECT/pipelines"
 ```
+
+## Resources
+- `references/gitlab-ci-templates.md` - Reusable GitLab CI templates and patterns
+
+## Examples
+
+### Example 1: Setup CI for New Service
+User asks: "Set up CI/CD for the new notification-service"
+Response approach:
+1. Create `.gitlab-ci.yml` in service root
+2. Add lint, test, build stages
+3. Configure PostgreSQL service for tests
+4. Add Jib build step
+5. Push and verify pipeline runs
+
+### Example 2: Add Deployment Stage
+User asks: "Add automatic deploy to staging on develop branch"
+Response approach:
+1. Add `deploy:staging` stage with kubectl
+2. Configure K8s credentials as CI variables
+3. Set `only: develop` trigger
+4. Test with a push to develop
+
+### Example 3: Pipeline is Failing
+User asks: "Tests are failing in CI but pass locally"
+Response approach:
+1. Check CI logs for the specific failure
+2. Compare CI environment (Java version, PostgreSQL version)
+3. Verify environment variables are set in CI
+4. Check if test depends on local-only resources
+5. Fix and push to re-trigger pipeline
+
+## Notes
+- Use `cache` for Maven/npm dependencies to speed up builds
+- `when: manual` for production deploys (requires human approval)
+- Store secrets in GitLab CI variables, never in `.gitlab-ci.yml`
+- Use Jib for Docker builds (no Docker daemon required)
+- Each microservice has its own pipeline