Repository Maintainer
Fluxo de trabalho sistemático para transformar perfis GitHub fragmentados em repositórios limpos, sustentáveis e profissionais.
Visão Geral
Execute a limpeza em 6 fases. Pule fases que não se aplicam. Sempre obtenha confirmação do usuário em ações destrutivas (exclusão, renomeação, mesclagem).
Princípios Essenciais (Innegociáveis)
Todo repositório — novo ou antigo, ativo ou arquivado — deve ter estes quatro documentos de base. Não considere uma limpeza concluída até que todos os quatro sejam verificados.
| Documento | Regra | Porquê |
|---|---|---|
| LICENSE | Todo repositório público recebe uma LICENSE. Padrão MIT, a menos que o usuário especifique o contrário. | Sem uma licença, o código é "todos os direitos reservados" por padrão. Ninguém pode usá-lo legalmente. |
| README.md | Deve existir com pelo menos: nome do projeto, descrição de uma frase e instruções de uso/instalação, se aplicável. | A primeira coisa que todo visitante vê. Um README vazio ou ausente sinaliza abandono. |
| .gitignore | Deve corresponder à linguagem primária (Python/PHP/Node/etc.). Nunca faça commit de artefatos de build, cache, arquivos de ambiente ou configurações de IDE. | Previne vazamento acidental de segredos e mantém diffs legíveis. |
| Descrição do GitHub | O campo description nunca deve estar vazio. Uma frase, em português claro (ou no idioma do repositório). | Aparece em resultados de busca, pins de perfil e cartões sociais. |
Se um repositório estiver faltando qualquer um dos quatro, corrigir isso tem prioridade sobre mesclar, renomear ou refatorar.
Fase 1: Escanear e Diagnosticar
Buscar lista completa de repositórios via API do GitHub:
curl -sH "Authorization: Bearer TOKEN" \
"https://api.github.com/user/repos?per_page=100&affiliation=owner"
Verificar em cada repositório:
- Faltando
LICENSE,.gitignore,README.md - Campo
descriptionvazio - Inconsistências de nomenclatura (maiúsculas/minúsculas misturadas, nomes muito longos)
- Duplicatas ou séries óbvias (ex.:
projeto,projeto-v2,projeto-mineru) - Nomes contendo
outdated,deprecated,old,test
Fase 2: Padronizar Arquivos de Base
Para cada repositório ativo, garantir que o conjunto mínimo de arquivos exista:
| Arquivo | Regra |
|---|---|
LICENSE | Padrão MIT, a menos que o usuário especifique o contrário |
.gitignore | Corresponder à linguagem primária (Python/PHP/Node) |
README.md | Deve existir; reescrever se for apenas um placeholder |
| Descrição do GitHub | Resumo de uma frase via API |
Atualização em lote via GitHub Contents API (PUT /repos/{owner}/{repo}/contents/{path}).
Crítico: Here-strings do PowerShell corrompem blocos de código com três crases em Markdown. Use scripts Python para geração em massa de README para evitar falhas de escape de ` → ```.
Fase 3: Lidar com Repositórios Desatualizados
Árvore de decisão:
| Condição | Ação |
|---|---|
Nome contém outdated / deprecated / old | Arquivar ou excluir |
| Substituído por repositório mais novo | Arquivar + link no README para o sucessor |
| Histórico de repositório público contém segredos vazados (chaves de API) | Excluir (arquivar deixa o histórico intacto) |
| Repositório privado contém chaves, senhas, configuração privada ou dados pessoais | Usuário pode ignorar regras de vazamento; tratar como estado privado aceitável, a menos que peça para sanitizar |
| Útil como referência, mas não mantido | Arquivar |
Repositórios arquivados são somente leitura. Para modificar um repositório arquivado (renomear, atualizar README), desarquive primeiro (PATCH {"archived": false}), faça as alterações e depois re-arquive.
Fase 4: Mesclar Repositórios Relacionados
Quando 2+ repositórios são variantes do mesmo sistema (diferentes backends, engines, adaptadores):
Opção A — Monorepo (Recomendado)
Crie um novo repositório limpo (sem histórico). Coloque cada variante no subdiretório engines/{nome}/.
projeto-suite/
├── main.py # engine padrão
├── engines/
│ ├── babeldoc/
│ └── mineru/
└── README.md
Preserve o ponto de entrada e a configuração de cada engine. Atualize o README raiz para explicar como alternar.
Opção B — Submódulo Git Mantenha repositórios independentes. Adicione submódulos no repositório pai. Use quando a preservação do histórico for mais importante que a simplicidade.
Opção C — Manter Independente + Link Não mescle. Adicione links cruzados nos READMEs. Use quando as variantes divergiram significativamente.
Se o histórico contém segredos: Crie sempre um novo repositório limpo e copie o snapshot atual (via download zip + novo commit). Não use git merge ou git submodule, pois o vazamento do histórico persistirá.
Fase 5: Renomear Repositórios
API Patch: PATCH /repos/{owner}/{repo} com {"name": "novo-nome"}.
Diretrizes:
- Tudo minúsculo, apenas hífens
- Máximo 3-4 palavras
- Remover palavras redundantes (
baseado-em,design-e-desenvolvimento) - Adicionar sufixo
outdateda repositórios arquivados, se ainda não estiver presente
O GitHub redireciona URLs antigas automaticamente por um período, mas bookmarks e scripts podem quebrar. Confirme com o usuário antes de renomear repositórios estrelados ou bifurcados.
Fase 6: Refatoração em Nível de Código
Após a estrutura remota estar limpa, refatore o código dentro dos repositórios:
- Terminologia unificada — Substitua nomes de marca hardcoded por termos genéricos (
GPTProcessor→LLMProcessor) preservando IDs de modelos de API reais (gpt-4,gpt-5). - Renomeação de arquivos — GitHub Contents API não tem renomeação; crie novo arquivo com conteúdo atualizado, exclua o antigo.
- Reorganização de diretórios — Use padrões
engines/,variants/oucore/+adapters/para projetos com múltiplas variações.
Enviando Grandes Refatorações Locais para o Remoto
Quando o usuário baixa o código localmente, faz alterações pesadas (renomeações de arquivos, renomeações de variáveis, reescritas estruturais) e precisa enviar de volta para o repositório remoto.
Varredura de Segredos Pré-Push (OBRIGATÓRIA)
Antes de enviar, deve-se escanear vazamentos de segredos; qualquer descoberta deve ser imediatamente relatada, e o push não deve prosseguir.
Exceção para repositório privado: Se o repositório alvo for confirmadamente privado, pode-se ignorar regras de vazamento de chaves, senhas, configuração privada, dados pessoais e outras informações sensíveis. A varredura pode servir como aviso, mas acertos não bloqueiam o push, não exigem recriação do repositório, nem exigem substituição por variáveis de ambiente, a menos que o usuário peça explicitamente para limpar ou planeje tornar o repositório público.
Modos de varredura (ambos devem ser executados — executar apenas o regex de token pode perder senhas em texto claro):
① Token de alta entropia / chave de API:
grep -rn "sk-[A-Za-z0-9]\{20,\}\|ghp_[A-Za-z0-9]\{36\}\|ghu_\|github_pat_\|Bearer [A-Za-z0-9+/=]\{40,\}" \
--include="*.py" --include="*.js" --include="*.ts" --include="*.yaml" \
--include="*.env" --include="*.json" --include="*.bat" --include="*.sh" \
--exclude-dir=".git" .
② Senhas em texto claro / helpers de credenciais (regex de token não pega; na prática, já vazou uma linha echo "<senha_sudo>" em askpass.sh que foi enviada com o commit init no GitHub):
git ls-files -z | xargs -0 grep -nIE "password|passwd|senha|SUDO_ASKPASS|sshpass|^[[:space:]]*echo[[:space:]]+[\"'][^\"']{6,}[\"]'" 2>/dev/null \
| grep -vE "\.md:|getenv|getpass|placeholder|example"
# E verifique manualmente arquivos isolados como askpass.sh / *_secret* / .pgpass / .npmrc — o arquivo inteiro é uma credencial
Em repositório público, qualquer acerto em qualquer modo aciona o fluxo obrigatório abaixo. Em repositório privado, apenas notifique o usuário, sem bloqueio. Observe que a varredura usa git ls-files (arquivos rastreados); o .gitignore exclui os que não são rastreados, mas arquivos já commitados, mesmo que agora no .gitignore, ainda estão no histórico.
Formato do relatório:
[LEAK] scripts/eval.py:15 — sk-xxxx (fallback hardcoded)
[LEAK] ui/ui_backend.py:33 — sk-xxxx (default hardcoded)
Fluxo obrigatório após descoberta de vazamento:
- Informe imediatamente ao usuário qual arquivo e linha
- Substitua por variável de ambiente (
os.getenv("API_KEY")sem valor padrão) - Se já tiver sido enviado para o remoto: informe o usuário e, após confirmação explícita, exclua e recrie o repositório (o histórico do git não pode ser completamente removido com force push)
- O usuário deve revogar a chave no serviço correspondente
Checklist Pré-Push
Antes de enviar, execute:
git status
Confirme que não há:
- Untracked files — Novos arquivos não rastreados (omissão comum: docs/, scripts/, modelos de config)
- Changes not staged — Modificações não adicionadas
- Changes to be committed contendo arquivos que não deveriam ser enviados (chaves, dados pessoais, scripts temporários)
Antes de confirmar, não prossiga com o push.
Árvore de Decisão
| Situação | Ação Recomendada |
|---|---|
Repositório local não tem .git (zip baixado / arquivos copiados) | Veja Cenário A abaixo |
Local é git clone com histórico, remoto inalterado | git add → commit → push normal |
Local é git clone, remoto tem novos commits | git pull --rebase ou merge, resolva conflitos, push |
Local é git clone, alterações são renomeações massivas + reescritas | Veja Cenário B abaixo |
| Quer preservar o histórico remoto, mas substituir todo o código | Veja Cenário C abaixo |
Cenário A: Local Não Tem Histórico Git
Mais comum quando o usuário baixa um zip, edita extensivamente e depois quer sincronizar de volta.
Opção A1 — Force Push (Projetos Pessoais / Solo)
# Na pasta do projeto local
git init
git add .
git commit -m "refactor: reescrita principal"
git remote add origin https://github.com/OWNER/REPO.git
git branch -M main
git push -u origin main --force
⚠️ Destrói o histórico remoto. Use apenas quando o usuário confirmar que o histórico remoto é descartável.
Opção A2 — Preservar Histórico Remoto (Recomendado para Repositórios Valiosos)
git clone https://github.com/OWNER/REPO.git temp-repo
cp -r temp-repo/.git ./seu-projeto-local/
cd seu-projeto-local
git add .
git commit -m "refactor: reescrita principal"
git push
Isso mantém todos os commits anteriores e anexa a refatoração como um único novo commit.
Opção A3 — Novo Repositório Limpo Se a reescrita for tão radical que é essencialmente um novo projeto:
- Crie novo repositório no GitHub (deve incluir
descriptionno corpo da criação ou fazer PATCH imediatamente após) - Envie o código local para lá
- Arquive o repositório antigo com um link para o sucessor no README
Cenário B: Renomeações Massivas + Reescritas em um Repositório Clonado
Regra crítica: nunca misture renomeações de arquivos e alterações de conteúdo no mesmo commit. O Git tratará como "excluir arquivo antigo + criar novo arquivo" e perderá a ligação do histórico.
Estratégia de commit passo a passo:
# Passo 1: Apenas renomear
git mv modulo_antigo.py novo_modulo.py
git mv utilitarios_antigos/ novos_utilitarios/
git commit -m "refactor: renomear módulos"
# Passo 2: Renomeações de variáveis/classes
git add .
git commit -m "refactor: renomear variáveis e classes"
# Passo 3: Alterações de lógica
git add .
git commit -m "feat: atualizar lógica principal"
Se o usuário já misturou tudo na árvore de trabalho:
# Guarde as alterações atuais e reproduza em etapas
git stash push -m "refatoração misturada"
# Restaure apenas renomeações (use git mv ou mv manual + git add)
git mv arquivo_antigo arquivo_novo
git commit -m "refactor: renomear arquivos"
# Restaure alterações de conteúdo
git stash pop
# Resolva conflitos, se houver, e faça commit
Cenário C: Substituir Todo o Código, mas Manter o Histórico
Útil quando o usuário quer começar com código novo, mas manter estrelas/issues/URL.
git checkout --orphan novo-inicio
git rm -rf .
# Copie o novo código local aqui
git add .
git commit -m "init: reescrita limpa"
git branch -D main
git branch -m main
git push -u origin main --force
Verificando a Detecção de Renomeação
Após o push, verifique se o Git rastreou as renomeações corretamente:
git log --follow -- novo_arquivo.py
Se o histórico estiver quebrado (mostrar o arquivo como totalmente novo), a renomeação e a alteração de conteúdo foram commitadas juntas.
Segurança e Conformidade
- Token do GitHub: Quando um PAT for necessário, procure na memória do agente (não escreva caminho/usuário/valor específico aqui). Nunca escreva o valor do token em nenhum arquivo que será enviado (incluindo esta skill, README, configurações) — conteúdo com token, uma vez enviado, será revogado pela varredura de segredos do GitHub.
- Higiene de token: Após operações em lote, instrua o usuário a revogar o PAT imediatamente em
https://github.com/settings/tokens. - Exceção para repositório privado: Se um repositório for privado, o agente pode ignorar regras de vazamento de chaves, senhas, configuração privada, dados pessoais e outras informações sensíveis. Não bloqueie push, não force sanitização, nem recomende exclusão apenas porque o histórico privado contém segredos, a menos que o usuário peça ou se o repositório puder se tornar público.
- Histórico público com segredos: Se um repositório público já commitou chaves de API, excluir o repositório é a única maneira de purgar o histórico do GitHub. Force-push de histórico sanitizado não garante remoção dos sistemas de backup do GitHub.
- Repositórios públicos arquivados com segredos: Se a exclusão for inaceitável, no mínimo remova o repositório da visibilidade pública (torne privado) ou exclua e recrie vazio com código limpo.
Referência Técnica
Armadilhas de Codificação (Windows)
O PowerShell usa CP1252 como padrão para stdout, destruindo caracteres chineses e blocos de código Markdown. Sempre reconfigurar:
import sys
sys.stdout.reconfigure(encoding='utf-8')
Ao usar Invoke-RestMethod no PowerShell com corpos JSON contendo crases ou três crases, prefira scripts Python para geração de conteúdo para evitar que a serialização JSON transforme ``` em `.
Padrões da API do GitHub
Criar repositório (nunca omita description):
api_call("POST", "/user/repos", {
"name": "nome-do-repo",
"private": True,
"description": "Resumo em uma frase."
})
Criar/atualizar arquivo:
import base64, json, urllib.request
payload = {
"message": "mensagem do commit",
"content": base64.b64encode(content.encode('utf-8')).decode(),
"sha": sha_existente # necessário para atualizações
}
req = urllib.request.Request(
f"https://api.github.com/repos/{owner}/{repo}/contents/{path}",
method="PUT",
data=json.dumps(payload).encode(),
headers={"Authorization": f"Bearer {token}", ...}
)
Arquivar/desarquivar:
api_call("PATCH", f"/repos/{owner}/{repo}", {"archived": True})
Renomear repositório:
api_call("PATCH", f"/repos/{owner}/{repo}", {"name": "novo-nome"})
Excluir repositório:
api_call("DELETE", f"/repos/{owner}/{repo}")
Download em Massa Sem Clone
Baixe o snapshot do repositório como zip para evitar git clone lento em redes instáveis:
curl -sL "https://github.com/{owner}/{repo}/archive/refs/heads/main.zip" -o {repo}.zip
Recursos Inclusos
scripts/repo_analyzer.py— Escaneia repositórios GitHub do usuário e gera recomendações de limpezascripts/bulk_file_updater.py— Cria/atualiza LICENSE, .gitignore, README em lote via API do GitHub
Como Usar
- Ative a habilidade no seu agente de IA (ex.: adicione ao arquivo de configuração do agente ou habilite via comando).
- Execute o fluxo solicitando ao agente: "Limpe meu perfil do GitHub" ou "Organize meus repositórios".
- Siga as confirmações — O agente solicitará aprovação antes de qualquer ação destrutiva.
- Revise as recomendações — O agente pode sugerir mesclagens, renomeações ou exclusões.
Dependências
- Acesso a um terminal com
curl,gite Python instalados. - Token de acesso pessoal (PAT) do GitHub com escopos
repoedelete_repo.
Notas
- Esta habilidade foi projetada para ser usada com agentes de IA que têm acesso ao sistema de arquivos e à API do GitHub.
- Para perfis com muitos repositórios, execute a varredura inicial para identificar rapidamente quais repositórios precisam de atenção.