SkillSpectorWeb

Metodologia de Portabilidade e Atualização do SkillSpector para o Navegador

Esta skill fornece instruções passo a passo para portar uma nova versão do scanner de segurança Python SkillSpector para uma aplicação web executada 100% no navegador via WebAssembly/JavaScript (SkillSpectorWeb).

---

🎯 Princípios Arquiteturais

1. Execução 100% no Lado do Cliente:

   • O scanner deve ser executado inteiramente no navegador do usuário, sem necessidade de servidor backend.
   • Todo o conteúdo do repositório GitHub é obtido via APIs REST do GitHub (api.github.com e raw.githubusercontent.com).

2. Isolamento Estrito de Módulos:

   • Mecanismo Central do Scanner (docs/js/skillspector-engine.js): Regras de análise estática traduzidas diretamente, correspondendo a nodes/analyzers/ do Python.
   • Filtro de Repositório Isolado (docs/js/repo-filter.js): Mantém a filtragem personalizada de arquivos não relacionados à skill (README.md, CHANGELOG.md, .git/, etc.) separada do código do scanner traduzido.
   • Buscador GitHub (docs/js/github-fetcher.js): Lida com análise de URL, expansão de árvores e download em lote.

3. Suporte a Repositórios com Múltiplas Skills:

   • Deve espelhar src/skillspector/multi_skill.py para descobrir todas as skills aninhadas em um repositório (resources/skills/*.md, skills/*.md, agents/*.md).

4. Paridade de Versão e Licenciamento:

   • Manter números de versão exatos (vX.Y.Z) correspondentes à versão upstream do SkillSpector Python.
   • Preservar o arquivo LICENSE upstream inalterado (Apache 2.0).

---

📋 Fluxo de Trabalho de Portabilidade Passo a Passo

Fase 1: Extração de Regras e Análise AST

1. Inspecionar novas regras de análise no upstream src/skillspector/nodes/analyzers/:
   • pattern_defaults.py (IDs de regra: P1-P8, E1-E5, PE1-PE3, SC1-SC7, EA1-EA4, OH1-OH3, MP1-MP3, TM1-TM4, RA1-RA2, TR1-TR3, MCP1).
2. Traduzir novas regexes Python e verificações AST para padrões RegExp JavaScript dentro de docs/js/skillspector-engine.js.
3. Atualizar listas de categorias, descrições de regras, explicações e guias de remediação.

Fase 2: Buscador GitHub e Expansão de Árvore

1. Garantir que docs/js/github-fetcher.js obtenha estruturas de árvore recursivas via https://api.github.com/repos/{owner}/{repo}/git/trees/{branch}?recursive=1.
2. NÃO limitar a busca a limites pequenos e arbitrários de arquivos (usar um limite alto de até 250 arquivos para suportar repositórios grandes com múltiplas skills).
3. Usar busca paralela em lotes (ex.: 10 arquivos por lote) com callbacks de progresso de UI em tempo real (onProgress(current, total, filename)).

Fase 3: Mecanismo de Descoberta de Múltiplas Skills

1. Implementar discoverSkills(filesMap) em skillspector-engine.js.
2. Analisar o frontmatter YAML do Markdown (--- name: ... description: ... ---) para todos os arquivos .md no repositório.
3. Renderizar uma barra de seleção de múltiplas skills em index.html, permitindo que os usuários filtrem descobertas por skill individual ou inspecionem todo o contexto do repositório.

Fase 4: Filtragem Isolada de Arquivos de Repositório

1. Manter docs/js/repo-filter.js completamente separado do mecanismo central do scanner.
2. Fornecer caixas de seleção de UI em index.html:
   • Omitir Documentos Padrão do Repositório (README, CHANGELOG, LICENSE)
   • Omitir Metadados do Sistema (.git/, .github/, dotfiles)
3. Registrar arquivos omitidos no Livro de Inspeção como itens ignorados com motivos explícitos.

Fase 5: Empacotamento para GitHub Pages (docs/)

1. Garantir que todos os ativos estáticos do site estejam dentro de SkillSpectorWeb/docs/:
   • docs/index.html
   • docs/css/styles.css
   • docs/js/*.js
   • docs/CNAME (skillspector.niyogilabs.com)
   • docs/sitemap.xml
   • docs/robots.txt
   • docs/.nojekyll
   • docs/LICENSE
2. Garantir que server.py sirva o diretório docs/ por padrão.

---

🧪 Lista de Verificação

• python3 server.py 8090 inicia e serve corretamente a partir de docs/.
• Escanear um repositório com múltiplas skills (ex.: Bhanunamikaze/Agentic-SEO-Skill) descobre todas as skills aninhadas.
• Tema claro definido como padrão; alternância para tema escuro funciona e persiste em localStorage.
• Endpoints SEO (/sitemap.xml, /robots.txt, /CNAME) retornam 200 OK.
• Funções de exportação SARIF 2.1.0, JSON e Markdown são executadas corretamente.
• Arquivo LICENSE raiz inalterado está intacto.