jarvis-ai-framework 2.1.0 → 3.0.0

package/agents/engineering/qa/eng.qa.cypress-specialist.md

@@ -1,109 +0,0 @@
----
-name: cypress-specialist
-description: Especialista em Cypress + TypeScript. Conhece Page Objects, Custom Commands, fixtures, cy.intercept, viewport, CI config e debugging de testes flaky. Referencia eng.qa.cypress-standards-rules.md como fonte de verdade das convenções do projeto.
-tools: Read, Glob, Grep, Bash, Write, Edit
-model: sonnet
----
-
-# Cypress Specialist — Especialista em Testes E2E Cypress
-
-Você é o **especialista em Cypress + TypeScript do time**. Sua expertise cobre toda a stack
-de testes E2E: desde escrita de specs até configuração de CI e debugging de testes instáveis.
-
-> 🔒 **Fonte de verdade de convenções**: `$RULES_FOLDER/engineering/qa/eng.qa.cypress-standards-rules.md`
-> Sempre ler antes de sugerir padrões ou gerar código.
-
----
-
-## Skills de Referência
-
-| Situação | Skill |
-|----------|-------|
-| Gerar nova spec Cypress | `eng-qa-cypress-e2e` |
-| Orientar dev sobre cobertura | `eng-qa-dev-guide` |
-
----
-
-## Domínios de Expertise
-
-### Page Objects
-- Estrutura fluent (retorno `this`)
-- Organização por domínio vs. por página
-- Herança e composição entre Page Objects
-- Quando criar vs. quando estender um existente
-
-### Custom Commands
-- Tipagem com TypeScript (`Cypress.Commands.add`)
-- Declaração em `support/index.d.ts`
-- Commands de autenticação via `cy.request` (não via UI)
-- Commands de setup de estado (seed de dados, limpeza)
-
-### Fixtures e Intercepts
-- Estrutura de pastas de fixtures por domínio
-- Tipagem de fixtures com tipos do projeto (`cy.fixture<T>`)
-- Padrões de `cy.intercept` para REST e GraphQL
-- Gestão de aliases e `cy.wait`
-- Estratégia de intercept para diferentes cenários (sucesso, erro, timeout)
-
-### Viewport e Responsividade
-- `cy.viewport()` para testes multi-device
-- Breakpoints a cobrir conforme o projeto
-- Configuração em `cypress.config.ts`
-
-### Configuração e CI
-- `cypress.config.ts` — baseUrl, env, retries, video
-- Estratégia de retries para flakiness (retry ≠ resolver o problema)
-- Paralelização com Cypress Cloud ou via CI nativo
-- Variáveis de ambiente seguras (`Cypress.env()` vs. hardcode)
-- Artefatos de CI: screenshots, vídeos, relatórios
-
-### Debugging de Testes Flaky
-
-Causas comuns e soluções:
-
-| Causa | Sintoma | Solução |
-|-------|---------|---------|
-| Race condition | Teste falha 1 em 5 vezes | Usar `cy.wait('@alias')` em vez de `cy.wait(ms)` |
-| Estado compartilhado | Teste passa isolado, falha em suite | `beforeEach` garante estado limpo |
-| Animação/transição | Clique em elemento não dispara | `.should('be.visible')` antes de `.click()` |
-| Dados dinâmicos | Assertion em texto que muda | Usar `contain` em vez de `eq`, ou mockar dado |
-| API real | Falha intermitente por timeout | Interceptar sempre — nunca depender de API real |
-| Seletor frágil | Falha após deploy de UI | Migrar para `data-testid` |
-
----
-
-## Como Responder
-
-### Para dúvidas de padrão
-Verificar `eng.qa.cypress-standards-rules.md` e responder com base nas convenções definidas.
-Se o padrão não cobrir o caso, sugerir uma extensão consistente com o que já existe.
-
-### Para debugging
-1. Perguntar: o teste falha sempre ou às vezes? (determina se é flaky ou quebrado)
-2. Pedir o erro e o trecho de código relevante
-3. Identificar a causa raiz antes de sugerir solução
-4. Nunca recomendar aumentar retry como solução definitiva
-
-### Para revisão de spec
-Ler a spec fornecida e verificar:
-- Seletores: algum usando classe/id? → migrar para `data-testid`
-- Intercepts: alguma API não interceptada? → adicionar
-- Dependência entre testes: algum `it` depende de outro? → corrigir
-- `cy.wait(ms)` hardcoded? → substituir por alias
-- Page Object ausente? → criar ou indicar onde adicionar
-
----
-
-## Regras
-
-### Nunca
-- Sugerir `cy.wait({número})` como solução — identificar a causa real da espera
-- Aceitar seletores por classe CSS em specs novas
-- Recomendar retry como fix de flakiness — é um paliativo, não solução
-- Ignorar tipagem TypeScript — fixtures, commands e Page Objects devem ser tipados
-
-### Sempre
-- Ler `eng.qa.cypress-standards-rules.md` antes de qualquer sugestão de padrão
-- Justificar por que uma prática é ruim antes de sugerir a alternativa
-- Verificar se já existe Page Object/command para o domínio antes de criar novo
-- Considerar manutenibilidade: um teste bom é um teste que não falha sem razão

package/bin/lib/docs/fetch-file.sh

@@ -1,41 +0,0 @@
-#!/bin/bash
-# Busca arquivo do central-docs (GitLab / GitHub / Bitbucket) + cache Redis
-
-FILE_PATH="$1"
-REF="${2:-main}"
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-if [ -z "$FILE_PATH" ]; then
-  echo "Uso: fetch-file.sh <file-path> [ref]" >&2
-  exit 1
-fi
-
-if [ -z "$CENTRAL_DOCS_REPO" ]; then
-  echo "Erro: CENTRAL_DOCS_REPO não definido no ENV.md" >&2
-  exit 1
-fi
-
-CACHE_KEY="docs:${FILE_PATH}:${REF}"
-CACHED=$(redis-cli GET "$CACHE_KEY" 2>/dev/null || echo "")
-
-if [ -n "$CACHED" ]; then
-  echo "$CACHED"
-  exit 0
-fi
-
-ERR_FILE=$(mktemp)
-RESPONSE=$(node "${SCRIPT_DIR}/../vcs/fetch-raw.js" "$FILE_PATH" "$REF" 2>"$ERR_FILE")
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -eq 0 ]; then
-  TTL="${CENTRAL_DOCS_CACHE_TTL:-3600}"
-  echo "$RESPONSE" | redis-cli -x SETEX "$CACHE_KEY" "$TTL" >/dev/null 2>&1 || true
-  rm -f "$ERR_FILE"
-  echo "$RESPONSE"
-  exit 0
-fi
-
-cat "$ERR_FILE" >&2
-rm -f "$ERR_FILE"
-exit $EXIT_CODE

package/bin/lib/docs/publish-file.sh

@@ -1,284 +0,0 @@
-#!/bin/bash
-# Publica documento no central-docs (GitLab / GitHub / Bitbucket) via branch + MR/PR
-
-set -e
-
-LOCAL_FILE="$1"      # Ex: ./docs/engineering/ard-api-wallet.md
-TIPO="$2"            # prd|frd|ard|rfc
-FEATURE="$3"         # Ex: api-wallet-auth-jwt
-
-# Resolver path absoluto do script (independente de cwd)
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-if [ -z "$LOCAL_FILE" ] || [ -z "$TIPO" ] || [ -z "$FEATURE" ]; then
-  echo "Uso: publish-file.sh <local-file> <tipo> <feature>" >&2
-  echo "Tipos válidos: prd, frd, ard, rfc, swagger, qa-report" >&2
-  exit 1
-fi
-
-if [ ! -f "$LOCAL_FILE" ]; then
-  echo "Erro: Arquivo não encontrado: $LOCAL_FILE" >&2
-  exit 1
-fi
-
-# Detectar IDE directory
-if [ -d ".windsurf" ]; then
-  IDE=".windsurf"
-elif [ -d ".claude" ]; then
-  IDE=".claude"
-elif [ -d ".cursor" ]; then
-  IDE=".cursor"
-elif [ -d ".vscode" ]; then
-  IDE=".vscode"
-else
-  echo "Erro: IDE directory não encontrado (.windsurf, .claude, .cursor, .vscode)" >&2
-  exit 1
-fi
-
-# 1. Ler ENV.md (se não houver override)
-if [ -n "$SQUAD_OVERRIDE" ] && [ -n "$WORKSPACE_OVERRIDE" ]; then
-  # Usar override das variáveis de ambiente
-  SQUAD="$SQUAD_OVERRIDE"
-  WORKSPACE="$WORKSPACE_OVERRIDE"
-else
-  # Ler do ENV.md
-  if [ ! -f "$IDE/ENV.md" ]; then
-    echo "Erro: ENV.md não encontrado em $IDE/" >&2
-    echo "Ou passe --squad e --workspace via CLI" >&2
-    exit 1
-  fi
-
-  SQUAD=$(grep '^SQUAD=' "$IDE/ENV.md" | cut -d'=' -f2 | tr -d ' ')
-  WORKSPACE=$(grep '^WORKSPACE=' "$IDE/ENV.md" | cut -d'=' -f2 | tr -d ' ')
-  
-  if [ -z "$SQUAD" ] || [ -z "$WORKSPACE" ]; then
-    echo "Erro: SQUAD ou WORKSPACE não definidos no ENV.md" >&2
-    echo "Ou passe --squad e --workspace via CLI" >&2
-    exit 1
-  fi
-fi
-
-TARGET_BRANCH="${CENTRAL_DOCS_TARGET_BRANCH:-dev}"
-
-if [ -z "$CENTRAL_DOCS_REPO" ]; then
-  echo "Erro: CENTRAL_DOCS_REPO não definido no ENV.md" >&2
-  exit 1
-fi
-
-# 2. Validar frontmatter
-echo "Validando frontmatter..."
-node --input-type=module -e "
-  import { validateFrontmatter } from 'file://${SCRIPT_DIR}/validate-frontmatter.js';
-  try {
-    validateFrontmatter('$LOCAL_FILE', '$TIPO');
-    console.log('✅ Frontmatter válido');
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-"
-
-if [ $? -ne 0 ]; then
-  exit 1
-fi
-
-# 3. Extrair metadados
-METADATA=$(node --input-type=module -e "
-  import { extractMetadata } from 'file://${SCRIPT_DIR}/validate-frontmatter.js';
-  const metadata = extractMetadata('$LOCAL_FILE');
-  console.log(JSON.stringify(metadata));
-")
-
-VERSION=$(echo "$METADATA" | jq -r '.version // "1.0.0"')
-STATUS=$(echo "$METADATA" | jq -r '.status // "draft"')
-JIRA=$(echo "$METADATA" | jq -r '.jira // ""')
-DOC_NAME=$(echo "$METADATA" | jq -r '.name // ""')
-
-# 4. Definir paths
-if [ "$TIPO" = "prd" ] || [ "$TIPO" = "frd" ]; then
-  DEST_PATH="${SQUAD}/${WORKSPACE}/product/${TIPO}-${FEATURE}.md"
-  AREA="product"
-elif [ "$TIPO" = "ard" ]; then
-  DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/ARD/${TIPO}-${FEATURE}.md"
-  AREA="engineering"
-elif [ "$TIPO" = "rfc" ]; then
-  DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/RFC/${TIPO}-${FEATURE}.md"
-  AREA="engineering"
-elif [ "$TIPO" = "swagger" ]; then
-  # Detectar extensão do arquivo (yaml, json ou md)
-  FILE_EXT="${LOCAL_FILE##*.}"
-  if [ "$FILE_EXT" = "yaml" ] || [ "$FILE_EXT" = "yml" ]; then
-    DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/swagger/api-${FEATURE}.yaml"
-  elif [ "$FILE_EXT" = "json" ]; then
-    DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/swagger/api-${FEATURE}.json"
-  else
-    # Default para .md (wrapper com metadados)
-    DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/swagger/swagger-${FEATURE}.md"
-  fi
-  AREA="engineering"
-elif [ "$TIPO" = "qa-report" ]; then
-  DEST_PATH="${SQUAD}/${WORKSPACE}/engineering/qa/qa-report-${FEATURE}.md"
-  AREA="engineering"
-else
-  echo "Erro: Tipo inválido: $TIPO" >&2
-  echo "Tipos válidos: prd, frd, ard, rfc, swagger, qa-report" >&2
-  exit 1
-fi
-
-INDEX_PATH="${SQUAD}/${WORKSPACE}/index.md"
-BRANCH_NAME="docs/${SQUAD}/${WORKSPACE}/${TIPO}-${FEATURE}"
-
-echo ""
-echo "📋 Resumo da Publicação:"
-echo "  Squad: $SQUAD"
-echo "  Workspace: $WORKSPACE"
-echo "  Tipo: $TIPO"
-echo "  Feature: $FEATURE"
-echo "  Destino: $DEST_PATH"
-echo "  Branch: $BRANCH_NAME → $TARGET_BRANCH"
-echo ""
-
-# 5–6. Token e parse do repo ficam no adapter VCS (api.js)
-
-# 7. Ler conteúdo do arquivo local e encodar em base64
-FILE_CONTENT=$(cat "$LOCAL_FILE" | base64)
-
-# 8. Buscar index.md atual
-echo "Buscando index.md do workspace..."
-INDEX_CONTENT=$(bash "${SCRIPT_DIR}/fetch-file.sh" "$INDEX_PATH" "$TARGET_BRANCH" 2>/dev/null || echo "")
-
-if [ -z "$INDEX_CONTENT" ]; then
-  echo "⚠️  index.md não encontrado, será criado"
-  INDEX_ACTION="create"
-  INDEX_CONTENT="# $WORKSPACE
-
-**Squad:** $SQUAD
-
-## $AREA
-
-"
-else
-  INDEX_ACTION="update"
-fi
-
-# 9. Adicionar nova linha ao index.md
-NEW_LINE="- [${TIPO}-${FEATURE}.md](${AREA}/${TIPO}-${FEATURE}.md) | v${VERSION} | ${STATUS}"
-[ -n "$JIRA" ] && NEW_LINE="${NEW_LINE} | jira: ${JIRA}"
-[ -n "$DOC_NAME" ] && NEW_LINE="${NEW_LINE} | ${DOC_NAME}"
-
-# Adicionar linha na seção correta
-UPDATED_INDEX=$(echo "$INDEX_CONTENT" | awk -v line="$NEW_LINE" -v area="$AREA" '
-  /^## (product|engineering)/ {
-    print
-    if ($2 == area) {
-      found = 1
-      getline
-      print line
-    }
-    next
-  }
-  { print }
-  END {
-    if (!found) {
-      print ""
-      print "## " area
-      print line
-    }
-  }
-')
-
-UPDATED_INDEX_B64=$(echo "$UPDATED_INDEX" | base64)
-
-# 10. Criar commit via adapter VCS
-echo "Criando branch e commit..."
-
-COMMIT_JSON=$(mktemp)
-cat > "$COMMIT_JSON" <<EOF
-{
-  "branch": $(printf '%s' "$BRANCH_NAME" | jq -Rs .),
-  "startBranch": $(printf '%s' "$TARGET_BRANCH" | jq -Rs .),
-  "message": $(printf '%s' "docs(${SQUAD}): add ${TIPO} ${FEATURE}" | jq -Rs .),
-  "files": [
-    {
-      "path": $(printf '%s' "$DEST_PATH" | jq -Rs .),
-      "contentBase64": $(printf '%s' "$FILE_CONTENT" | jq -Rs .),
-      "action": "create"
-    },
-    {
-      "path": $(printf '%s' "$INDEX_PATH" | jq -Rs .),
-      "contentBase64": $(printf '%s' "$UPDATED_INDEX_B64" | jq -Rs .),
-      "action": $(printf '%s' "$INDEX_ACTION" | jq -Rs .)
-    }
-  ]
-}
-EOF
-
-COMMIT_RESULT=$(node --input-type=module -e "
-  import { readFileSync } from 'node:fs';
-  import { commitFiles } from 'file://${SCRIPT_DIR}/../vcs/api.js';
-  const opts = JSON.parse(readFileSync('$COMMIT_JSON', 'utf-8'));
-  const result = await commitFiles(process.env.CENTRAL_DOCS_REPO, opts);
-  console.log(JSON.stringify(result));
-" 2>&1)
-COMMIT_EXIT=$?
-rm -f "$COMMIT_JSON"
-
-if [ $COMMIT_EXIT -ne 0 ]; then
-  echo "❌ Erro ao criar commit:" >&2
-  echo "$COMMIT_RESULT" >&2
-  exit 1
-fi
-
-COMMIT_SHA=$(echo "$COMMIT_RESULT" | jq -r '.sha')
-echo "✅ Commit criado: $COMMIT_SHA"
-
-# 11. Criar MR/PR
-echo "Criando Merge/Pull Request..."
-
-MR_DESCRIPTION="## Documento
-
-- **Tipo**: ${TIPO}
-- **Workspace**: ${WORKSPACE}
-- **Feature**: ${FEATURE}"
-
-[ -n "$JIRA" ] && MR_DESCRIPTION="${MR_DESCRIPTION}
-- **Card**: ${JIRA}"
-
-[ -n "$DOC_NAME" ] && MR_DESCRIPTION="${MR_DESCRIPTION}
-- **Nome**: ${DOC_NAME}"
-
-BODY_FILE=$(mktemp)
-printf '%s' "$MR_DESCRIPTION" > "$BODY_FILE"
-
-MR_RESULT=$(node "${SCRIPT_DIR}/../vcs/create-merge.js" \
-  --repo "$CENTRAL_DOCS_REPO" \
-  --source "$BRANCH_NAME" \
-  --target "$TARGET_BRANCH" \
-  --title "docs(${SQUAD}): ${TIPO} ${FEATURE}" \
-  --body-file "$BODY_FILE" 2>&1)
-MR_EXIT=$?
-rm -f "$BODY_FILE"
-
-if [ $MR_EXIT -ne 0 ]; then
-  echo "❌ Erro ao criar MR/PR:" >&2
-  echo "$MR_RESULT" >&2
-  exit 1
-fi
-
-MR_URL=$(echo "$MR_RESULT" | tail -1 | jq -r '.url // empty')
-MR_IID=$(echo "$MR_RESULT" | tail -1 | jq -r '.iid // empty')
-
-echo ""
-echo "✅ Merge/Pull Request criado com sucesso!"
-echo ""
-echo "  #${MR_IID}: ${BRANCH_NAME} → ${TARGET_BRANCH}"
-echo "  URL: ${MR_URL}"
-echo ""
-
-# 12. Invalidar cache Redis
-redis-cli DEL "docs:${INDEX_PATH}:${TARGET_BRANCH}" >/dev/null 2>&1 || true
-redis-cli DEL "docs:${INDEX_PATH}:main" >/dev/null 2>&1 || true
-
-echo "🔄 Cache Redis invalidado"
-echo ""
-echo "✅ Publicação concluída!"