Forgejo

O que Forgejo faz?

Wrapper fino em torno da API REST do Forgejo. Cada recurso vive em seu próprio script para que o agente possa descobri-los e invocá-los individualmente. SkillHone depende deste como skill de backend VCS, mas permanece independente para que outro backend como GitLab ou Gitea possa fornecer a mesma superfície de fluxo de trabalho.

Scripts

Script	Recurso	Uso representativo
scripts/issue.py	Issues	python3 scripts/issue.py create --title "Bug"
scripts/pr.py	Pull requests	python3 scripts/pr.py merge 1
scripts/wiki.py	Páginas wiki	python3 scripts/wiki.py get --title "Analysis"
scripts/repo.py	Metadados do repositório	python3 scripts/repo.py branches
scripts/summary.py	Painel agregado	python3 scripts/summary.py

Todo script suporta --help. Execute-o antes de chutar flags.

Configuração

Resolvido nesta ordem (primeira correspondência vence):

1. Variáveis de ambiente: FORGEJO_URL, FORGEJO_TOKEN, FORGEJO_OWNER, FORGEJO_REPO
2. ~/.skillhone/settings.json + ~/.skillhone/identities.conf
3. _data/forgejo_config.txt no diretório de trabalho atual

Se nada estiver definido, o script sai com uma mensagem clara nomeando a variável ausente.

Uso por Recurso

Issues

python3 scripts/issue.py list
python3 scripts/issue.py view <N>
python3 scripts/issue.py create --title "Corrigir: timeout" --body "## Problema\n..."
python3 scripts/issue.py close <N>
python3 scripts/issue.py comment <N> --body "Feito"

Pull Requests

python3 scripts/pr.py list
python3 scripts/pr.py view <M>
python3 scripts/pr.py create --title "Corrigir timeout" --head fix/timeout --base main --body "Fecha #1"
python3 scripts/pr.py review <M> --approve
python3 scripts/pr.py merge <M> --method merge
python3 scripts/pr.py comment <M> --body "LGTM"

Wiki

python3 scripts/wiki.py list
python3 scripts/wiki.py get --title "Iteration-1-Observation"
python3 scripts/wiki.py create --title "Página" --body "conteúdo"
python3 scripts/wiki.py edit --title "Página" --body "conteúdo atualizado"

Metadados do Repositório

python3 scripts/repo.py info
python3 scripts/repo.py branches

Resumo Combinado

python3 scripts/summary.py
# issues abertas + PRs abertos + página wiki de observação mais recente

Invocação a partir de Outras Skills

Outras skills que residem em ~/.skillhone/skills/ chamam esses scripts via seu caminho absoluto:

python3 ~/.skillhone/skills/forgejo/scripts/issue.py list

Isso mantém o backend VCS substituível. Uma skill GitLab ou Gitea pode expor uma superfície de comando equivalente sem alterar a lógica de otimização do SkillHone.

Pegadinhas

• Tokens com caracteres @ quebram a injeção de URL de clone git. Use um token sem @ ou codifique-o em URL.
• merge --method squash não é suportado por versões mais antigas do Forgejo. Se você encontrar Unknown method, volte para merge.
• As páginas wiki são armazenadas como arquivos .md em um repositório git separado (<repo>.wiki.git). wiki.py esconde isso, mas se você precisar de edição personalizada, clone o repositório wiki diretamente.

Regras Rígidas

• Nunca imprima o token Forgejo em logs stdout/stderr. Os scripts já fazem a redação; não o cole em campos --body.
• Não chame a API REST do Forgejo diretamente com curl ou HTTP artesanal em fluxos de trabalho SkillHone. Use estes scripts de backend para que o carregamento de credenciais, redação e substituição de backend permaneçam centralizados.
• Não use cat em _data/forgejo_config.txt, ~/.skillhone/settings.json ou identities.conf para descobrir credenciais. Os scripts resolvem credenciais internamente.
• Não faça push diretamente para main através de nenhum destes scripts. Apenas PRs.
• Quando você receber um 401/403, verifique novamente a ordem de resolução de configuração acima antes de alterar o script.