oss-prep

Preparação para open source

Uma verificação de pré-lançamento para um repositório que está prestes a se tornar público. Um script executa as verificações mecânicas; você lê o projeto, julga o que o script não consegue, relata e preenche apenas o que o usuário escolher.

A ordem importa porque um erro não pode ser desfeito: uma vez que um repositório é público, tudo em seu histórico já foi visto. Credenciais vazadas e dados pessoais vêm primeiro; itens padronizados vêm por último.

1. Escanear

Execute o scanner incluído a partir da raiz do repositório (Node 20 ou mais recente, sem dependências, somente leitura):

node <skill-dir>/scripts/scan.mjs <repo-dir>

Ele imprime JSON: summary conta as descobertas com falha por nível, e cada descoberta tem um id, um level (block, warn, info), um status (pass, fail, skip) e evidence. Adicione --no-history para um histórico muito grande apenas se o usuário concordar em pular essa parte, e informe que foi pulado. Se o gitleaks estiver instalado, execute também gitleaks git <repo-dir> --redact --no-banner e mescle suas descobertas; ele reconhece muitos mais formatos de token.

As regras de segredo do scanner são padrões, portanto, espere falsos positivos (acessórios de teste, exemplos de documentação) e não presuma que ele capturou tudo. Veja cada ocorrência você mesmo antes de relatá-la. Uma linha pode ser marcada como intencional com um comentário oss-prep: allow.

2. Ler e julgar

Leia referências/checklist.md para entender o que cada verificação significa, como distinguir um problema real de ruído, e as verificações que só você pode fazer. Resumindo, além das descobertas do script:

• O que o histórico e os arquivos revelam. Abra cada ocorrência de segredo e cada arquivo sensível no histórico (git show <commit>:<path>). Procure por nomes reais, e-mails, números de telefone, endereços, dados de clientes ou financeiros, nomes de host internos e capturas de tela com dados privados em documentos ou acessórios.
• Consistência da licença. O texto LICENSE, package.json, frontmatter do SKILL.md, README e quaisquer cabeçalhos por arquivo devem concordar. Observe código de terceiros empacotado, fontes ou imagens e se suas licenças permitem redistribuição.
• README para um estranho. Alguém que chega de uma pesquisa deve aprender o que é, vê-lo (uma captura de tela ou link de demonstração), instalá-lo e executá-lo, e encontrar a licença, sem contexto privado.
• Coisas que só funcionaram para o autor. Caminhos locais codificados, valores de .env que o projeto precisa mas não documenta, scripts que assumem a máquina do autor.

3. Relatar

Escreva o relatório no idioma do usuário, neste formato:

# Prontidão para open source: <repo>

**Veredito:** <Pronto / Pronto após os itens bloqueantes / Não pronto>, uma frase explicando por quê.

## Bloqueante (corrigir antes de tornar público)
- ❌ <título>: <o que foi encontrado, com arquivo:linha ou commit> → <a correção>

## Deve corrigir
- ⚠️ ...

## Bom ter
- 💡 ...

## Já implementado
- ✅ <uma linha cada, agrupados>

## Precisa de você no GitHub
<configurações que o usuário altera sozinho, com o comando gh exato ou caminho de configuração>

Coloque o item mais grave primeiro. Seja específico: "src/config.ts:12 tem uma chave OpenAI, também no commit a1b2c3d" em vez de "segredos encontrados". Diga o que você não verificou (sem gh, histórico pulado, arquivos binários).

Em seguida, pergunte quais itens devem ser preenchidos. Ofereça o conjunto óbvio como padrão ("todos os arquivos ausentes") e liste cada escolha para que o usuário possa selecionar.

4. Preencher o que o usuário selecionou

Use os modelos em assets/templates/ como ponto de partida e adapte-os a este projeto; leia referências/fixing.md primeiro. Resumindo:

• Escreva arquivos, nunca publique. Crie ou edite arquivos apenas na árvore de trabalho. Não faça commit, push, altere a visibilidade ou configurações do repositório, nem crie releases, a menos que o usuário peça essa etapa específica.
• Corresponda ao projeto. Use seus comandos reais, versão do Node, gerenciador de pacotes, licença e rota de contato; escreva no idioma do README (ambos, se o README for bilíngue). Deixe de fora as seções que não se aplicam, em vez de enviar placeholders.
• Nunca escolha uma licença para o usuário. Se não houver nenhuma, explique as opções comuns em uma frase cada (MIT, Apache-2.0, GPL-3.0, AGPL-3.0, licenciamento duplo) e pergunte. Copie o texto oficial da licença exatamente; não parafraseie ou redigite de memória.
• Segredos no histórico não são corrigidos excluindo o arquivo. A credencial deve ser revogada e substituída primeiro; isso é trabalho do usuário no console do provedor. Reescrever o histórico (git filter-repo) ou publicar um repositório novo são decisões dele; explique ambos e não faça nenhum sem um sim claro.
• As configurações do GitHub pertencem ao usuário. Forneça os comandos gh exatos ou caminhos de configuração da referência; execute-os apenas se o usuário solicitar.

Termine executando o scanner novamente e mostrando quais descobertas mudaram, além do que ainda resta para o usuário.