pulse-libs/.learnings/LEARNINGS.md

Learnings — Padrões bem-sucedidos

Registro de padrões que funcionam, para replicar.

---

[LRN-20260520-003] gitea-api-autenticacao-completa

Logged: 2026-05-20T12:31:00-03:00 Priority: high Status: reference Area: devops | api

Summary

Gitea API suporta 5 métodos de autenticação — todos usam o mesmo API token

Details

Fontes estudadas: https://docs.gitea.com/development/api-usage

Métodos de autenticação (ordem de preferência):

1. Authorization: token <hash> — mais comum, não usa username na URL
2. token=<hash> query string — simples para curl/GETs
3. access_token=<hash> query string — compat OAuth2 consumers
4. HTTP Basic (username:password) — cria token, admin
5. HTTP Basic + OTP — quando 2FA habilitado (X-Gitea-OTP: 123456)
6. SSH HTTP Signature — chaves SSH registradas, draft-cavage-http-signatures

Token nunca é reexibido — apare | |:"name":"meu-token","sha1":"9fcb11..." — só sha1 na listagem /**/ Scopes: formato <read|write>:<permission>, ou all para tudo. Permissions: activitypub, admin, issue, misc, notification, organization, package, repository, user

Pagination: ?page=N&limit=N, header Link (rel=next/last), x-total-count

Sudo (admin): adicionar Sudo: username header ou param sudo=username

Suggested Action

Usar sempre scopes:["all"] para automação, guardar token em segredo, preferir header Authorization: token sobre query string.

Metadata

• Source: documentation
• Tags: gitea, api, auth, token, swagger, devops
• Pattern-Key: gitea-api.authentication
• Recurrence-Count: 1

---

[LRN-20260520-004] gitea-api-endpoints-reference

Logged: 2026-05-20T12:31:00-03:00 Priority: medium Status: reference Area: devops | api

Summary

Mapa dos endpoints Gitea API v1 por domínio

Details

• Usuário: GET /api/v1/user, GET /api/v1/users/:username
• Repos: GET/POST /api/v1/user/repos, GET /api/v1/repos/:owner/:repo
• Issues: GET/POST /api/v1/repos/:owner/:repo/issues
• Pulls: GET/POST /api/v1/repos/:owner/:repo/pulls
• Webhooks: GET/POST /api/v1/repos/:owner/:repo/hooks
• Admin users: GET/POST/PUT/DELETE /api/v1/admin/users
• Swagger: https://host/api/swagger
• OpenAPI JSON: https://host/swagger.v1.json

Suggested Action

Consultar SKILL.md skills/gitea-api/SKILL.md antes de usar a API.

Metadata

• Source: documentation
• Tags: gitea, api, endpoints, rest
• Pattern-Key: gitea-api.endpoints
• Recurrence-Count: 1

---

[LRN-20260519-001] clawhub.cli_path

Logged: 2026-05-19T20:39:00-03:00 Priority: high Status: pending Area: config

Summary

Instalar skills do Clawhub com /var/lib/openclaw/tools/node/npm/bin/clawhub

Details

O CLI clawhub não está no $PATH global, mas existe instalado em /var/lib/openclaw/tools/node/npm/bin/clawhub. Sempre usar o caminho completo.

Suggested Action

Adicionar symlink ou alias para clawhub no PATH do agente, ou sempre usar o caminho completo.

Metadata

• Source: error
• Tags: clawhub, cli, path, install
• Pattern-Key: clawhub.cli_path

---

[LRN-20260519-002] clawhub-search-qc

Logged: 2026-05-19T20:42:00-03:00 Priority: medium Status: pending Area: config

Summary

clawhub search com termos muito específicos retorna vazio; usar termos genéricos primeiro

Details

Pesquisas com termos combinados como "programming developer full-stack" retornaram vazio. Termos simples como "autonomous agent" retornaram resultados. Melhor abordar a pesquisa em múltiplas queries curtas.

Suggested Action

Fazer múltiplas searches com termos curtos e depois filtrar manualmente.

Metadata

• Source: error
• Tags: clawhub, search, query
• Pattern-Key: clawhub.search_strategy

---

[LRN-20260519-003] biblioteca-compartilhada-libs

Logged: 2026-05-19T21:30:00-03:00 Priority: medium Status: pending Area: config

Summary

Criar biblioteca inteligente compartilhada em libs/ para reuso entre projetos

Details

Toda skill instalada tem conhecimento valioso. Centralizar em libs/<dominio>/:

• skills são extraídas e promovidas para arquivos .md limpos
• novos projetos copiam libs/ como template
• o agente consulta libs/ antes de implementar

Metadata

• Source: best_practice
• Tags: biblioteca, reuso, padroes
• Pattern-Key: libs.shared_knowledge_base

---

[LRN-20260519-004] vitest-jsdom-global-mocks

Logged: 2026-05-19T23:10:00-03:00 Priority: high Status: applied Area: testing

Summary

Vitest jsdom — mocks globais obrigatórios antes de renderizar hooks que usam APIs do navegador

Details

localStorage, navigator.clipboard, window.matchMedia não existem no jsdom puro — mockar em beforeAll/beforeEach global.

Metadata

• Source: best_practice
• Tags: vitest, jsdom, mocks, testing
• Pattern-Key: vitest.jsdom.mocks
• Recurrence-Count: 3 → promoted

---

[LRN-20260519-005] react-testing-library-hooks-async

Logged: 2026-05-19T23:10:00-03:00 Priority: medium Status: pending Area: testing

Summary

React Testing Library — renderHook + act() para testar hooks assíncronos

Details

Sempre envolver awaits em act(async () => { ... }), nunca acessar result.current após await diretamente fora de act().

Metadata

• Source: best_practice
• Tags: react, testing-library, hooks, async, vitest
• Pattern-Key: react.testing-library
• Recurrence-Count: 3 → promoted

---

[LRN-20260520-001] vitest-pure-dom-matchers

Logged: 2026-05-20T00:52:00-03:00 Priority: high Status: applied Area: testing

Summary

Vitest jsdom puro — matchers nativos DOM funcionam sem @testing-library/jest-dom

Details

Usar .classList.contains(), .getAttribute(), .textContent, container.querySelector() ao invés de matchers RTL. 56/56 testes verdes, 0 dependências extras.

Metadata

• Source: best_practice
• Tags: vitest, jsdom, testing, matchers
• Pattern-Key: vitest.pure-dom-matchers
• Recurrence-Count: 1

---

[LRN-20260520-002] jsdom-fireEvent-writable-value

Logged: 2026-05-20T00:52:00-03:00 Priority: low Status: workaround Area: testing

Summary

No jsdom, Object.defineProperty(input, 'value', { writable: true }) permite fireEvent.change

Details

Workaround mínimo para testar onChange em inputs no jsdom puro, onde .value é readonly.

Metadata

• Source: error
• Tags: jsdom, fireEvent, input, value
• Pattern-Key: jsdom.fireEvent-change-writable
• Recurrence-Count: 1