jarvis-ai-framework 2.0.0 → 2.1.1

package/skills/eng-frontend-microfrontend/SKILL.md

@@ -85,465 +85,19 @@ O que será feito?
 
 ---
 
-## Criando um Remote
+## Referências (leia só o tema que a tarefa pedir)
 
-### Estrutura de um remote
+Leia **só** o arquivo do tema que a tarefa pedir; o restante fica fora do contexto.
 
-```
-apps/
-└── {nome-remote}/
-    ├── src/
-    │   ├── bootstrap.ts        ← entry point async (necessário para Module Federation)
-    │   ├── index.ts            ← importa e executa bootstrap
-    │   ├── App.tsx             ← root do remote (para modo standalone)
-    │   ├── routes/             ← rotas do remote
-    │   ├── components/         ← componentes locais do remote
-    │   └── exposed/            ← o que será exposto via Module Federation
-    │       ├── index.ts        ← re-exporta tudo que é público
-    │       └── RemoteApp.tsx   ← componente raiz exposto ao shell
-    ├── vite.config.ts          ← ou webpack.config.ts
-    ├── package.json
-    └── tsconfig.json
-```
-
-### Por que `bootstrap.ts` é obrigatório?
-
-```typescript
-// src/index.ts — entry point síncrono
-import('./bootstrap')  // import() dinâmico é necessário para Module Federation funcionar
-
-// src/bootstrap.ts — inicialização real
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import App from './App'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-)
-```
-
-> Sem o `bootstrap.ts`, o eager consumption de shared libs causa erro em runtime.
-
-### Configuração Vite (vite-plugin-federation)
-
-```typescript
-// vite.config.ts do remote
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import federation from '@originjs/vite-plugin-federation'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    federation({
-      name: '{nome-remote}',        // identificador único do remote
-      filename: 'remoteEntry.js',   // arquivo gerado
-      exposes: {
-        './App': './src/exposed/RemoteApp',   // o que o shell pode importar
-        './routes': './src/exposed/routes',   // rotas para shell carregar
-      },
-      shared: {
-        react: { singleton: true, requiredVersion: '^18.0.0' },
-        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
-        'react-router-dom': { singleton: true },
-        // design system — sempre singleton para evitar instâncias duplicadas
-        '@{org}/design-system': { singleton: true },
-      },
-    }),
-  ],
-  build: {
-    target: 'esnext',
-    minify: false,       // facilita debug; ativar em prod via CI flag
-    cssCodeSplit: false, // evita problemas com CSS em remotes
-  },
-})
-```
-
-### Modo standalone (obrigatório para dev local)
-
-```typescript
-// src/App.tsx — funciona sem shell
-import { BrowserRouter } from 'react-router-dom'
-import { AppRoutes } from './routes'
-
-export default function App() {
-  return (
-    <BrowserRouter>
-      <AppRoutes />
-    </BrowserRouter>
-  )
-}
-```
-
-```json
-// package.json do remote
-{
-  "scripts": {
-    "dev": "vite --port 3001",          // standalone
-    "dev:federated": "vite --port 3001 --mode federated",  // com Module Federation ativo
-    "build": "vite build",
-    "preview": "vite preview --port 3001"
-  }
-}
-```
-
----
-
-## Configurando o Shell
-
-```typescript
-// vite.config.ts do shell
-import federation from '@originjs/vite-plugin-federation'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    federation({
-      name: 'shell',
-      remotes: {
-        '{nome-remote}': 'http://localhost:3001/assets/remoteEntry.js',
-        // Em produção, usar variável de ambiente:
-        // '{nome-remote}': process.env.VITE_REMOTE_URL_NOME_REMOTE,
-      },
-      shared: {
-        react: { singleton: true },
-        'react-dom': { singleton: true },
-        'react-router-dom': { singleton: true },
-        '@{org}/design-system': { singleton: true },
-      },
-    }),
-  ],
-})
-```
-
-### Lazy loading de remotes no shell
-
-```typescript
-// src/routes/index.tsx — shell monta remotes por rota
-import { lazy, Suspense } from 'react'
-import { Routes, Route } from 'react-router-dom'
-
-// Tipagem do remote (importar do contrato de interface)
-const RemoteApp = lazy(() =>
-  import('{nome-remote}/App').then((m) => ({ default: m.default }))
-)
-
-function ErrorFallback({ error }: { error: Error }) {
-  return (
-    <div role="alert">
-      <p>Falha ao carregar módulo. <button onClick={() => window.location.reload()}>Tentar novamente</button></p>
-    </div>
-  )
-}
-
-export function ShellRoutes() {
-  return (
-    <Routes>
-      <Route
-        path="/{caminho-remote}/*"
-        element={
-          <Suspense fallback={<div>Carregando...</div>}>
-            <ErrorBoundary FallbackComponent={ErrorFallback}>
-              <RemoteApp />
-            </ErrorBoundary>
-          </Suspense>
-        }
-      />
-    </Routes>
-  )
-}
-```
-
----
-
-## Contratos de Interface
-
-O contrato é o **acordo formal** entre shell e remote — define o que o remote expõe e o que espera receber.
-
-### Estrutura do pacote de contratos
-
-```
-packages/
-└── mfe-contracts/
-    ├── src/
-    │   ├── remotes/
-    │   │   ├── {nome-remote}.contract.ts    ← contrato do remote
-    │   │   └── index.ts
-    │   ├── shell/
-    │   │   └── shell.context.ts             ← o que o shell injeta nos remotes
-    │   └── index.ts
-    ├── package.json
-    └── tsconfig.json
-```
-
-### Definindo um contrato
-
-```typescript
-// packages/mfe-contracts/src/remotes/{nome-remote}.contract.ts
-
-// O que o remote expõe ao shell
-export interface {NomeRemote}Exports {
-  default: React.ComponentType<{NomeRemote}Props>
-}
-
-// Props que o shell passa ao montar o remote
-export interface {NomeRemote}Props {
-  basePath: string
-  onNavigate?: (path: string) => void
-}
-
-// Eventos que o remote emite no event bus
-export interface {NomeRemote}Events {
-  '{nome-remote}:action-completed': { id: string; result: unknown }
-  '{nome-remote}:error': { code: string; message: string }
-}
-```
-
-### Contexto do shell (injetado em todos os remotes)
-
-```typescript
-// packages/mfe-contracts/src/shell/shell.context.ts
-export interface ShellContext {
-  user: {
-    id: string
-    name: string
-    permissions: string[]
-  }
-  theme: 'light' | 'dark'
-  locale: string
-  onNavigate: (path: string) => void
-}
-
-// Hook disponível em todos os remotes
-export const ShellContextReact = React.createContext<ShellContext | null>(null)
-
-export function useShellContext(): ShellContext {
-  const ctx = React.useContext(ShellContextReact)
-  if (!ctx) throw new Error('useShellContext deve ser usado dentro do ShellProvider')
-  return ctx
-}
-```
-
----
-
-## Shared Dependencies
-
-### Regras críticas
-
-```
-singleton: true   → apenas uma instância em toda a aplicação (obrigatório para React, React DOM)
-eager: false      → NÃO usar eager para shared libs (causa bootstrap error)
-requiredVersion   → sempre declarar para evitar conflitos silenciosos
-```
-
-### Checklist de shared deps
-
-```typescript
-shared: {
-  // Core React — sempre singleton
-  'react': { singleton: true, requiredVersion: '^18.0.0' },
-  'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
-
-  // Router — singleton para evitar múltiplos contextos de roteamento
-  'react-router-dom': { singleton: true, requiredVersion: '^6.0.0' },
-
-  // Design system — singleton obrigatório (CSS e contexto de tema)
-  '@{org}/design-system': { singleton: true },
-
-  // Estado global — singleton se compartilhado entre remotes
-  'zustand': { singleton: true },
-
-  // NÃO compartilhar: libs utilitárias pequenas (date-fns, lodash)
-  // → melhor cada remote ter sua versão para evitar lock de versão
-}
-```
-
-### Conflito de versão (diagnóstico)
-
-```bash
-# Ver qual versão de react cada remote está carregando
-# No DevTools → Network → filtrar por "remoteEntry.js"
-# Abrir arquivo e buscar por "shared"
-
-# Via CLI — verificar versões no monorepo
-pnpm list react --recursive
-```
-
----
-
-## Event Bus
-
-Remote e shell se comunicam via evento — nunca via import direto.
-
-```typescript
-// packages/mfe-contracts/src/event-bus.ts
-
-type EventHandler<T> = (payload: T) => void
-
-class MFEEventBus {
-  private listeners = new Map<string, Set<EventHandler<unknown>>>()
-
-  emit<T>(event: string, payload: T): void {
-    this.listeners.get(event)?.forEach((handler) => handler(payload as unknown))
-  }
-
-  on<T>(event: string, handler: EventHandler<T>): () => void {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, new Set())
-    }
-    this.listeners.get(event)!.add(handler as EventHandler<unknown>)
-
-    // retorna função de cleanup
-    return () => this.listeners.get(event)?.delete(handler as EventHandler<unknown>)
-  }
-}
-
-// Singleton global — compartilhado via shell context
-export const eventBus = new MFEEventBus()
-```
-
-```typescript
-// Uso em um remote
-import { useShellContext } from '@{org}/mfe-contracts'
-
-function CheckoutButton({ orderId }: { orderId: string }) {
-  const { eventBus } = useShellContext()
-
-  return (
-    <button onClick={() => eventBus.emit('checkout:initiated', { orderId })}>
-      Finalizar compra
-    </button>
-  )
-}
-
-// Uso no shell — escutar eventos de remotes
-useEffect(() => {
-  const unsubscribe = eventBus.on('checkout:initiated', ({ orderId }) => {
-    navigate(`/checkout/${orderId}`)
-  })
-  return unsubscribe
-}, [])
-```
-
----
-
-## Monorepo Frontend
-
-### Estrutura recomendada
-
-```
-{repo}/
-├── apps/
-│   ├── shell/              ← host application
-│   ├── {remote-a}/         ← micro frontend A
-│   └── {remote-b}/         ← micro frontend B
-├── packages/
-│   ├── design-system/      ← componentes e tokens compartilhados
-│   ├── mfe-contracts/      ← tipos TypeScript de contratos de interface
-│   └── utils/              ← utilitários compartilhados
-├── pnpm-workspace.yaml
-└── turbo.json
-```
-
-```yaml
-# pnpm-workspace.yaml
-packages:
-  - 'apps/*'
-  - 'packages/*'
-```
-
-```json
-// turbo.json
-{
-  "pipeline": {
-    "build": {
-      "dependsOn": ["^build"],
-      "outputs": ["dist/**"]
-    },
-    "dev": {
-      "cache": false,
-      "persistent": true
-    },
-    "test": {
-      "dependsOn": ["^build"]
-    }
-  }
-}
-```
-
----
-
-## Estratégia de Deploy
-
-### Deploy independente (objetivo central do micro frontend)
-
-```
-Cada remote tem seu próprio pipeline de CI/CD:
-  push → build → test → deploy → atualizar URL no shell (via env var ou config service)
-
-Shell NÃO precisa ser re-deployed quando um remote é atualizado.
-```
-
-### Variáveis de ambiente por remote
-
-```bash
-# .env.production do shell
-VITE_REMOTE_URL_NOME_REMOTE=https://cdn.example.com/nome-remote/remoteEntry.js
-VITE_REMOTE_URL_OUTRO_REMOTE=https://cdn.example.com/outro-remote/remoteEntry.js
-```
-
-### Versionamento de remotes
-
-```
-Sem breaking change na API exposta → patch ou minor → URL permanece a mesma
-Breaking change na API exposta (props, eventos) → major → nova URL + migração no shell
-```
-
----
-
-## Troubleshooting
-
-### Erro: "Shared module is not available for eager consumption"
-
-```typescript
-// ❌ Causa: eager: true em shared lib com React
-shared: { react: { singleton: true, eager: true } }  // NÃO FAZER
-
-// ✅ Solução: usar bootstrap.ts com import() dinâmico
-// src/index.ts
-import('./bootstrap')  // async bootstrap resolve o problema
-```
-
-### Erro: "Remote container is not available"
-
-```bash
-# 1. Verificar se o remote está rodando
-curl http://localhost:3001/assets/remoteEntry.js
-
-# 2. Verificar CORS no servidor do remote
-# O remoteEntry.js precisa ser acessível pelo shell
-
-# 3. Verificar se a URL no shell está correta
-grep -r "remoteEntry" vite.config.ts
-```
-
-### Componente do remote não re-renderiza após update de state do shell
-
-```typescript
-// Causa provável: contexto do shell não está sendo re-injetado no remote
-// Solução: passar o contexto via props no ponto de montagem, não via módulo compartilhado
-
-// ❌ Problemático
-import { useShellStore } from 'shell/store'  // import direto entre remote e shell
-
-// ✅ Correto
-// Shell passa estado via props ao montar o remote
-<RemoteApp user={currentUser} onNavigate={navigate} />
-```
-
----
+| Tema | Quando ler | Arquivo |
+|------|-----------|---------|
+| Criando um Remote | A tarefa criar um remote novo (estrutura, bootstrap, Vite e modo standalone) | `references/1-criando-remote.md` |
+| Configurando o Shell | A tarefa configurar o shell ou o lazy loading de remotes | `references/2-configurando-shell.md` |
+| Contratos de Interface | A tarefa definir ou alterar contratos entre shell e remotes | `references/3-contratos-interface.md` |
+| Shared Dependencies | A tarefa envolver dependências compartilhadas ou conflito de versão | `references/4-shared-dependencies.md` |
+| Event Bus | A tarefa envolver comunicação entre remotes por eventos | `references/5-event-bus.md` |
+| Monorepo e Estratégia de Deploy | A tarefa envolver a estrutura do monorepo, o deploy independente ou o versionamento de remotes | `references/6-monorepo-deploy.md` |
+| Troubleshooting de Micro Frontend | Houver erro de módulo compartilhado, remote indisponível ou componente que não re-renderiza | `references/7-troubleshooting.md` |
 
 ## Checklist de Novo Remote
 
@@ -557,6 +111,12 @@ import { useShellStore } from 'shell/store'  // import direto entre remote e she
 - [ ] URL de deploy configurada via variável de ambiente
 - [ ] Breaking changes documentadas e comunicadas ao time do shell
 
+### Skills invocados durante a execução do skill
+
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
+
 ---
 
 ## Regras

package/skills/eng-frontend-microfrontend/references/1-criando-remote.md

@@ -0,0 +1,109 @@
+# Criando um Remote
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando a tarefa criar um remote novo (estrutura, bootstrap, Vite e modo standalone).
+
+## Criando um Remote
+
+### Estrutura de um remote
+
+```
+apps/
+└── {nome-remote}/
+    ├── src/
+    │   ├── bootstrap.ts        ← entry point async (necessário para Module Federation)
+    │   ├── index.ts            ← importa e executa bootstrap
+    │   ├── App.tsx             ← root do remote (para modo standalone)
+    │   ├── routes/             ← rotas do remote
+    │   ├── components/         ← componentes locais do remote
+    │   └── exposed/            ← o que será exposto via Module Federation
+    │       ├── index.ts        ← re-exporta tudo que é público
+    │       └── RemoteApp.tsx   ← componente raiz exposto ao shell
+    ├── vite.config.ts          ← ou webpack.config.ts
+    ├── package.json
+    └── tsconfig.json
+```
+
+### Por que `bootstrap.ts` é obrigatório?
+
+```typescript
+// src/index.ts — entry point síncrono
+import('./bootstrap')  // import() dinâmico é necessário para Module Federation funcionar
+
+// src/bootstrap.ts — inicialização real
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+)
+```
+
+> Sem o `bootstrap.ts`, o eager consumption de shared libs causa erro em runtime.
+
+### Configuração Vite (vite-plugin-federation)
+
+```typescript
+// vite.config.ts do remote
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import federation from '@originjs/vite-plugin-federation'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    federation({
+      name: '{nome-remote}',        // identificador único do remote
+      filename: 'remoteEntry.js',   // arquivo gerado
+      exposes: {
+        './App': './src/exposed/RemoteApp',   // o que o shell pode importar
+        './routes': './src/exposed/routes',   // rotas para shell carregar
+      },
+      shared: {
+        react: { singleton: true, requiredVersion: '^18.0.0' },
+        'react-dom': { singleton: true, requiredVersion: '^18.0.0' },
+        'react-router-dom': { singleton: true },
+        // design system — sempre singleton para evitar instâncias duplicadas
+        '@{org}/design-system': { singleton: true },
+      },
+    }),
+  ],
+  build: {
+    target: 'esnext',
+    minify: false,       // facilita debug; ativar em prod via CI flag
+    cssCodeSplit: false, // evita problemas com CSS em remotes
+  },
+})
+```
+
+### Modo standalone (obrigatório para dev local)
+
+```typescript
+// src/App.tsx — funciona sem shell
+import { BrowserRouter } from 'react-router-dom'
+import { AppRoutes } from './routes'
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <AppRoutes />
+    </BrowserRouter>
+  )
+}
+```
+
+```json
+// package.json do remote
+{
+  "scripts": {
+    "dev": "vite --port 3001",          // standalone
+    "dev:federated": "vite --port 3001 --mode federated",  // com Module Federation ativo
+    "build": "vite build",
+    "preview": "vite preview --port 3001"
+  }
+}
+```
+
+---

package/skills/eng-frontend-microfrontend/references/2-configurando-shell.md

@@ -0,0 +1,70 @@
+# Configurando o Shell
+
+> Parte do skill `eng-frontend-microfrontend`. Leia este arquivo quando a tarefa configurar o shell ou o lazy loading de remotes.
+
+## Configurando o Shell
+
+```typescript
+// vite.config.ts do shell
+import federation from '@originjs/vite-plugin-federation'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    federation({
+      name: 'shell',
+      remotes: {
+        '{nome-remote}': 'http://localhost:3001/assets/remoteEntry.js',
+        // Em produção, usar variável de ambiente:
+        // '{nome-remote}': process.env.VITE_REMOTE_URL_NOME_REMOTE,
+      },
+      shared: {
+        react: { singleton: true },
+        'react-dom': { singleton: true },
+        'react-router-dom': { singleton: true },
+        '@{org}/design-system': { singleton: true },
+      },
+    }),
+  ],
+})
+```
+
+### Lazy loading de remotes no shell
+
+```typescript
+// src/routes/index.tsx — shell monta remotes por rota
+import { lazy, Suspense } from 'react'
+import { Routes, Route } from 'react-router-dom'
+
+// Tipagem do remote (importar do contrato de interface)
+const RemoteApp = lazy(() =>
+  import('{nome-remote}/App').then((m) => ({ default: m.default }))
+)
+
+function ErrorFallback({ error }: { error: Error }) {
+  return (
+    <div role="alert">
+      <p>Falha ao carregar módulo. <button onClick={() => window.location.reload()}>Tentar novamente</button></p>
+    </div>
+  )
+}
+
+export function ShellRoutes() {
+  return (
+    <Routes>
+      <Route
+        path="/{caminho-remote}/*"
+        element={
+          <Suspense fallback={<div>Carregando...</div>}>
+            <ErrorBoundary FallbackComponent={ErrorFallback}>
+              <RemoteApp />
+            </ErrorBoundary>
+          </Suspense>
+        }
+      />
+    </Routes>
+  )
+}
+```
+
+---