Imported from eyglys/chrome-gsa-plus (AGENTS.md). Install upstream with npx skills add eyglys/chrome-gsa-plus. Copyright stays with the author.

Instruções para agentes

Idioma e estilo

• Escreva código, nomes de variáveis e funções, comentários, documentação e mensagens técnicas em português do Brasil, salvo quando uma API, biblioteca ou convenção do projeto exigir outro idioma.
• Use TypeScript como linguagem padrão. Use JavaScript somente quando houver uma exigência técnica ou de configuração que justifique isso.
• Antes de alterar arquivos, inspecione a estrutura do projeto, as configurações existentes e as convenções já adotadas.
• Faça mudanças pequenas, focadas e compatíveis com o código existente. Não faça refatorações não relacionadas ao objetivo da tarefa.
• Prefira tipos explícitos, interfaces claras e validação em limites entre sistemas. Evite any; quando ele for inevitável, documente a razão e restrinja seu alcance.

Arquitetura do projeto

• Mantenha src/entradas/service-worker.ts e src/entradas/content-script.ts apenas como entrypoints de inicialização e registro.
• Implemente cada funcionalidade em src/funcionalidades/<nome>/, separando, quando aplicável, contratos, dominio, pagina e worker.
• Não coloque regras de negócio, seletores do Classroom ou lógica de rede diretamente nos entrypoints.
• Funcionalidades com código no service worker devem expor uma função registrar... e registrar seus handlers no roteador tipado de src/infraestrutura/mensagens/.
• Funcionalidades de página devem expor uma função inicializar... e manter DOM, seletores, estado visual e observadores dentro do próprio módulo.
• Os contratos de mensagens devem ficar junto da funcionalidade que os utiliza. O roteador compartilhado deve conhecer apenas tipos genéricos de entrada, saída e contexto.
• APIs Chrome, rede, DOM compartilhado e bibliotecas externas devem ser encapsulados em src/infraestrutura/ quando forem usados por mais de uma funcionalidade.
• Prefira interfaces injetáveis para rede, mensagens, armazenamento e observação do DOM, permitindo testes sem depender diretamente do ambiente Chrome.
• Novas funcionalidades devem incluir testes próximos ao domínio ou contrato testado e não devem ampliar o entrypoint além do registro do módulo.
• A funcionalidade de baixar entregas usa exclusivamente a Google Classroom API para listar alunos, atividade, submissões e materiais; não reintroduza coletores HTML, iframes, rotas /g/tg ou cliques em páginas internas.
• O download dos anexos deve continuar isolado no cliente Google Drive do contexto worker, recebendo apenas IDs validados pela Classroom API.
• A instrumentação detalhada é opcional e deve ser protegida por VITE_DEBUG=true; o comportamento padrão não deve gerar arquivos de diagnóstico no ZIP nem mensagens de tempo decorrido.

Ícones e elementos visuais

• Use Lucide como biblioteca padrão de ícones, instalada via npm e empacotada localmente pelo Vite.
• Importe ícones somente por meio de src/infraestrutura/icones/; funcionalidades não devem importar lucide diretamente.
• Importe apenas os ícones utilizados para preservar tree-shaking e reduzir o bundle.
• Não carregue ícones por CDN, URL remota ou script externo.
• Use a API DOM segura para criar os SVGs. Não use innerHTML, scripts inline ou execução dinâmica para renderizar ícones.
• Ícones decorativos devem possuir aria-hidden="true". Nunca substitua o texto acessível de um botão somente por um ícone.
• Padronize tamanho, espessura, classes e estados visuais no adaptador de ícones.
• Ao adicionar um novo ícone, atualize o tipo e o catálogo do adaptador, inclua teste quando necessário e justifique a escolha no módulo consumidor.

Extensões do Google Chrome

• Trate o projeto como uma extensão do Google Chrome e prefira Manifest V3, APIs oficiais e práticas recomendadas pela documentação atual do Chrome.
• Entenda e respeite as diferenças entre os contextos da extensão: service worker, content scripts, páginas da extensão, popups, options pages e páginas web.
• Use a menor quantidade possível de permissões e host permissions. Cada nova permissão deve ter justificativa funcional e impacto de segurança considerado.
• Defina e preserve uma Content Security Policy restritiva. Não use eval, new Function, scripts inline ou outros mecanismos de execução dinâmica de código.
• Use mensagens entre contextos com contratos tipados, validação do remetente e validação do conteúdo recebido. Não confie em dados vindos de content scripts, páginas web, armazenamento ou mensagens.
• Respeite as limitações de ciclo de vida, persistência e suspensão do service worker. Não dependa de estado apenas em memória quando ele precisar sobreviver à suspensão.
• Use chrome.storage ou outro mecanismo apropriado para persistência, evitando expor dados sensíveis a contextos que não precisam deles.
• Considere compatibilidade com as versões suportadas do Chrome e valide mudanças no manifest.json, no service worker, nos content scripts e nas permissões.

Segurança web

• Aplique o princípio do menor privilégio a permissões, acesso a sites, APIs e dados.
• Trate toda entrada externa como não confiável: parâmetros de URL, DOM da página, mensagens, respostas de rede, dados do armazenamento e conteúdo selecionado pelo usuário.
• Evite XSS, injeção de HTML e JavaScript, DOM clobbering, injeção de comandos, CSRF e vazamento de dados. Prefira textContent, APIs DOM seguras e serialização estruturada em vez de montar HTML com strings.
• Valide origem, esquema, formato, tamanho e contexto dos dados antes de processá-los. Faça validação também no servidor quando houver backend.
• Não coloque chaves privadas, tokens permanentes, credenciais ou segredos no código-fonte, no bundle ou no pacote da extensão.
• Use HTTPS, valide respostas de rede e reduza ao mínimo os dados coletados, armazenados e enviados.
• Não desative controles de segurança para fazer uma implementação funcionar. Ao identificar uma vulnerabilidade ou uma solução insegura, corrija a abordagem e comunique o risco.
• Ao modificar autenticação, comunicação entre contextos, permissões, CSP, armazenamento ou acesso a conteúdo remoto, inclua uma revisão de segurança e testes adequados.

Limitações da plataforma

• Verifique primeiro se a solicitação é compatível com as APIs, permissões, políticas e modelo de segurança de extensões do Chrome.
• Se algo não puder ser implementado por uma limitação arquitetural da extensão, informe claramente:
  • qual é a limitação;
  • por que ela impede o comportamento solicitado;
  • qual alternativa suportada é possível, se houver.
• Não gere código fictício, incompleto ou inseguro para simular uma capacidade que a plataforma não oferece.
• Não contorne restrições de segurança, permissões, CSP, isolamento de contextos ou políticas da Chrome Web Store.
• Diferencie explicitamente entre uma solução implementável, uma solução que exige backend ou configuração adicional e uma solicitação impossível dentro da arquitetura atual.

Processo de implementação

• Reproduza ou confirme o comportamento atual antes de modificar código quando houver uma implementação existente.
• Preserve alterações feitas por outras pessoas e não reverta mudanças não relacionadas.
• Atualize tipos, documentação e testes quando a mudança alterar contratos ou comportamento observável.
• Execute os comandos de validação disponíveis no projeto, como type-check, lint, testes e build. Se não puder executar algum deles, informe o motivo.
• Verifique o pacote final da extensão, especialmente o manifesto, permissões, arquivos gerados, CSP e ausência de segredos.
• Ao concluir, descreva objetivamente os arquivos alterados, as validações executadas, limitações encontradas e riscos residuais.

Qualidade e testes

• Priorize testes para regras de negócio, validação de entradas, comunicação entre contextos, permissões e fluxos que lidam com dados sensíveis.
• Cubra casos válidos, entradas malformadas, falhas de rede, mensagens de origem inválida, ausência de permissões e reinicialização ou suspensão do service worker quando aplicável.
• Não considere uma implementação concluída apenas porque compila: valide o comportamento e os controles de segurança relevantes.
• Testes da coleta devem cobrir a extração dos identificadores da rota, validação das respostas API, associação aluno-submissão-arquivo, deduplicação e falhas do Drive. Testes de diagnóstico devem verificar os modos VITE_DEBUG=false e VITE_DEBUG=true.