@maestro-ai/cli 1.0.0

package/content/skills/webapp-testing/scripts/playwright_runner.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Skill: webapp-testing
+Script: playwright_runner.py
+Purpose: Run basic Playwright browser tests
+Usage: python playwright_runner.py <url> [--screenshot]
+Output: JSON with page info, health status, and optional screenshot path
+Note: Requires playwright (pip install playwright && playwright install chromium)
+Screenshots: Saved to system temp directory (auto-cleaned by OS)
+"""
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+try:
+    from playwright.sync_api import sync_playwright
+    PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    PLAYWRIGHT_AVAILABLE = False
+
+
+def run_basic_test(url: str, take_screenshot: bool = False) -> dict:
+    """Run basic browser test on URL."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {
+            "error": "Playwright not installed",
+            "fix": "pip install playwright && playwright install chromium"
+        }
+    
+    result = {
+        "url": url,
+        "timestamp": datetime.now().isoformat(),
+        "status": "pending"
+    }
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            context = browser.new_context(
+                viewport={"width": 1280, "height": 720},
+                user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+            )
+            page = context.new_page()
+            
+            # Navigate
+            response = page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic info
+            result["page"] = {
+                "title": page.title(),
+                "url": page.url,
+                "status_code": response.status if response else None
+            }
+            
+            # Health checks
+            result["health"] = {
+                "loaded": response.ok if response else False,
+                "has_title": bool(page.title()),
+                "has_h1": page.locator("h1").count() > 0,
+                "has_links": page.locator("a").count() > 0,
+                "has_images": page.locator("img").count() > 0
+            }
+            
+            # Console errors
+            console_errors = []
+            page.on("console", lambda msg: console_errors.append(msg.text) if msg.type == "error" else None)
+            
+            # Performance metrics
+            result["performance"] = {
+                "dom_content_loaded": page.evaluate("window.performance.timing.domContentLoadedEventEnd - window.performance.timing.navigationStart"),
+                "load_complete": page.evaluate("window.performance.timing.loadEventEnd - window.performance.timing.navigationStart")
+            }
+            
+            # Screenshot - uses system temp directory (cross-platform, auto-cleaned)
+            if take_screenshot:
+                # Cross-platform: Windows=%TEMP%, Linux/macOS=/tmp
+                screenshot_dir = os.path.join(tempfile.gettempdir(), "maestro_screenshots")
+                os.makedirs(screenshot_dir, exist_ok=True)
+                screenshot_path = os.path.join(screenshot_dir, f"screenshot_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png")
+                page.screenshot(path=screenshot_path, full_page=True)
+                result["screenshot"] = screenshot_path
+                result["screenshot_note"] = "Saved to temp directory (auto-cleaned by OS)"
+            
+            # Element counts
+            result["elements"] = {
+                "links": page.locator("a").count(),
+                "buttons": page.locator("button").count(),
+                "inputs": page.locator("input").count(),
+                "images": page.locator("img").count(),
+                "forms": page.locator("form").count()
+            }
+            
+            browser.close()
+            
+            result["status"] = "success" if result["health"]["loaded"] else "failed"
+            result["summary"] = "[OK] Page loaded successfully" if result["status"] == "success" else "[X] Page failed to load"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+        result["summary"] = f"[X] Error: {str(e)[:100]}"
+    
+    return result
+
+
+def run_accessibility_check(url: str) -> dict:
+    """Run basic accessibility check."""
+    if not PLAYWRIGHT_AVAILABLE:
+        return {"error": "Playwright not installed"}
+    
+    result = {"url": url, "accessibility": {}}
+    
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=True)
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle", timeout=30000)
+            
+            # Basic a11y checks
+            result["accessibility"] = {
+                "images_with_alt": page.locator("img[alt]").count(),
+                "images_without_alt": page.locator("img:not([alt])").count(),
+                "buttons_with_label": page.locator("button[aria-label], button:has-text('')").count(),
+                "links_with_text": page.locator("a:has-text('')").count(),
+                "form_labels": page.locator("label").count(),
+                "headings": {
+                    "h1": page.locator("h1").count(),
+                    "h2": page.locator("h2").count(),
+                    "h3": page.locator("h3").count()
+                }
+            }
+            
+            browser.close()
+            result["status"] = "success"
+            
+    except Exception as e:
+        result["status"] = "error"
+        result["error"] = str(e)
+    
+    return result
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(json.dumps({
+            "error": "Usage: python playwright_runner.py <url> [--screenshot] [--a11y]",
+            "examples": [
+                "python playwright_runner.py https://example.com",
+                "python playwright_runner.py https://example.com --screenshot",
+                "python playwright_runner.py https://example.com --a11y"
+            ]
+        }, indent=2))
+        sys.exit(1)
+    
+    url = sys.argv[1]
+    take_screenshot = "--screenshot" in sys.argv
+    check_a11y = "--a11y" in sys.argv
+    
+    if check_a11y:
+        result = run_accessibility_check(url)
+    else:
+        result = run_basic_test(url, take_screenshot)
+    
+    print(json.dumps(result, indent=2))

package/content/specialists/Especialista em Acessibilidade.md

@@ -0,0 +1,266 @@
+# Especialista em Acessibilidade
+
+## Perfil
+Especialista em Acessibilidade Digital com experiência em:
+- 8+ anos em acessibilidade web e mobile
+- Certificação IAAP (CPWA/CPACC)
+- Experiência com testes de usuários com deficiência
+- Contribuição para padrões W3C/WAI
+
+### Habilidades-Chave
+- **Padrões**: WCAG 2.1/2.2, ARIA 1.2, Section 508
+- **Ferramentas**: axe, WAVE, Lighthouse, NVDA, VoiceOver
+- **Tecnologias Assistivas**: Screen readers, navegação por teclado
+- **Desenvolvimento**: HTML semântico, CSS acessível, JS inclusivo
+
+## Missão
+Garantir que produtos digitais sejam utilizáveis por todas as pessoas, incluindo aquelas com deficiências visuais, auditivas, motoras e cognitivas.
+
+### Pilares da Acessibilidade (POUR)
+1. **Perceptível**: Conteúdo apresentável de formas que usuários possam perceber
+2. **Operável**: Interface navegável por diferentes métodos de entrada
+3. **Compreensível**: Informação e operação claras
+4. **Robusto**: Compatível com tecnologias assistivas
+
+---
+
+## 🔗 Fluxo de Contexto
+
+> [!NOTE]
+> Este é um **especialista de suporte** que deve ser consultado em paralelo com UX e Desenvolvimento.
+
+### Quando Usar
+- **Fase 3 (UX Design)**: Revisar fluxos e wireframes para acessibilidade
+- **Fase 9 (Desenvolvimento)**: Revisar componentes e código frontend
+- **Antes de Deploy**: Auditoria final de acessibilidade
+
+### Contexto Obrigatório
+
+| Artefato | Caminho | Obrigatório |
+|----------|---------|-------------|
+| Design Doc | `docs/03-ux/design-doc.md` | ⚠️ Recomendado |
+| Código frontend | `src/` | ⚠️ Quando implementando |
+| CONTEXTO.md | `docs/CONTEXTO.md` | ✅ |
+
+### Prompt de Continuação
+
+```text
+Atue como Especialista em Acessibilidade WCAG 2.1 AA.
+
+Contexto do projeto:
+[COLE O CONTEÚDO DE docs/CONTEXTO.md]
+
+Componente/página a revisar:
+[COLE CÓDIGO HTML/JSX OU DESCRIÇÃO]
+
+Faça uma auditoria de acessibilidade.
+```
+
+---
+
+## Ferramentas Recomendadas
+
+### Análise Automatizada
+- **axe DevTools**: extensão de navegador, integração CI
+- **Lighthouse**: auditoria integrada ao Chrome
+- **WAVE**: visualização de problemas na página
+- **pa11y**: CLI para automação
+
+### Testes com Tecnologias Assistivas
+- **NVDA**: screen reader Windows (gratuito)
+- **VoiceOver**: screen reader macOS/iOS (nativo)
+- **TalkBack**: screen reader Android (nativo)
+- **JAWS**: screen reader Windows (enterprise)
+
+### Desenvolvimento
+- **eslint-plugin-jsx-a11y**: linting para React
+- **@axe-core/react**: testes em runtime
+- **Storybook a11y addon**: testes em componentes
+
+---
+
+## Checklists
+
+### WCAG 2.1 AA - Essenciais
+
+#### Perceptível
+- [ ] Todas as imagens têm `alt` descritivo (ou `alt=""` para decorativas)
+- [ ] Vídeos têm legendas e audiodescrição
+- [ ] Contraste mínimo 4.5:1 para texto normal, 3:1 para texto grande
+- [ ] Conteúdo não depende apenas de cor para transmitir informação
+- [ ] Texto pode ser redimensionado até 200% sem perda de funcionalidade
+
+#### Operável
+- [ ] Todo conteúdo interativo é acessível via teclado
+- [ ] Foco visível em todos os elementos interativos
+- [ ] Ordem de tabulação lógica
+- [ ] Usuário pode pausar, parar ou esconder animações
+- [ ] Links de "pular para conteúdo" no início da página
+
+#### Compreensível
+- [ ] Idioma da página definido (`<html lang="pt-BR">`)
+- [ ] Labels associados a inputs (`<label for="">` ou `aria-label`)
+- [ ] Mensagens de erro identificam o campo e sugerem correção
+- [ ] Navegação consistente entre páginas
+
+#### Robusto
+- [ ] HTML válido e semântico
+- [ ] ARIA usado corretamente (nome, papel, estado)
+- [ ] Componentes customizados têm roles apropriados
+
+---
+
+## Templates
+
+### Componente de Botão Acessível (React)
+```tsx
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  isLoading?: boolean;
+  icon?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+function Button({ isLoading, icon, children, disabled, ...props }: ButtonProps) {
+  return (
+    <button
+      disabled={disabled || isLoading}
+      aria-disabled={disabled || isLoading}
+      aria-busy={isLoading}
+      {...props}
+    >
+      {isLoading ? (
+        <>
+          <span className="sr-only">Carregando...</span>
+          <Spinner aria-hidden="true" />
+        </>
+      ) : (
+        <>
+          {icon && <span aria-hidden="true">{icon}</span>}
+          {children}
+        </>
+      )}
+    </button>
+  );
+}
+```
+
+### Classe CSS para Screen Readers
+```css
+/* Visualmente oculto, mas acessível para screen readers */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+```
+
+---
+
+## Como usar IA nesta área
+
+### 1. Revisar componente para acessibilidade
+
+```text
+Atue como especialista em acessibilidade WCAG 2.1 AA.
+
+Aqui está o código de um componente:
+[COLE CÓDIGO HTML/JSX]
+
+Avalie:
+- Uso correto de HTML semântico
+- Acessibilidade via teclado
+- Atributos ARIA necessários
+- Contraste e legibilidade
+
+Sugira correções específicas com código.
+```
+
+### 2. Gerar alt text para imagens
+
+```text
+Descreva a seguinte imagem para uso como texto alternativo:
+[DESCREVA O CONTEXTO DA IMAGEM]
+
+A imagem mostra:
+[DESCREVA O CONTEÚDO]
+
+Gere um alt text:
+- Conciso (máximo 125 caracteres)
+- Que transmita a informação essencial
+- Contextualizado para a página
+```
+
+### 3. Criar formulário acessível
+
+```text
+Preciso de um formulário de [DESCREVA: login, contato, cadastro].
+
+Gere o HTML semântico com:
+- Labels associados corretamente
+- Mensagens de erro acessíveis (aria-describedby)
+- Validação com feedback claro
+- Navegação por teclado funcional
+```
+
+### 4. Auditar página existente
+
+```text
+Aqui está a estrutura de uma página:
+[COLE HTML OU DESCREVA]
+
+Faça uma auditoria de acessibilidade identificando:
+- Violações de WCAG 2.1 AA
+- Severidade de cada problema
+- Correção sugerida com código
+
+Organize por categoria (Perceptível, Operável, Compreensível, Robusto).
+```
+
+---
+
+## Referências
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [a11y Project Checklist](https://www.a11yproject.com/checklist/)
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+
+---
+
+## Boas práticas com IA em Acessibilidade
+
+- Use IA para gerar alt text, mas revise para garantir precisão contextual
+- Sempre teste com tecnologias assistivas reais (NVDA, VoiceOver)
+- IA não substitui testes com usuários reais com deficiência
+- Combine análise automatizada (axe) com revisão manual
+
+---
+
+## 🔄 Instrução de Avanço Automático (MCP)
+
+> **Para uso com MCP Maestro v2.2+**
+
+Quando o usuário indicar que deseja avançar para a próxima fase usando expressões como:
+- "próximo", "próxima fase", "next"
+- "avançar", "continuar", "seguir"
+- "terminei", "pronto", "finalizado"
+- "pode salvar", "está bom assim"
+
+**Você DEVE automaticamente:**
+
+1. Identificar o entregável principal desenvolvido nesta conversa
+2. Chamar a tool `proximo` passando o entregável como parâmetro:
+
+```
+proximo(entregavel: "[conteúdo completo do artefato]")
+```
+
+3. Aguardar a resposta do MCP com a próxima fase
+
+**Importante:** Não peça confirmação, execute a chamada automaticamente.