Modulo 1.7 - Publicando no library

🏁 printing-press publish

Comando que empacota CLI + skill + docs e abre PR no printing-press-library automaticamente. Evita esquecer arquivo de manifesto.

Comando completo

$ cd brasil-api-pp-cli
$ printing-press publish

[1/5] Validando manifesto printingpress.yaml... OK
[2/5] Rodando shipcheck...                       OK (score 87/100)
[3/5] Gerando README do library...               OK
[4/5] Fork em github.com/voce/printing-press-library criado
[5/5] PR aberto: https://github.com/mvanhorn/printing-press-library/pull/284

📄 printingpress.yaml

name: brasil-api
binary: brasil-api-pp-cli
skill: pp-brasil-api
version: 0.1.0
license: MIT
author: inematds
homepage: https://github.com/inematds/brasil-api-pp-cli
description: BrasilAPI CLI - CEP, CNPJ, bancos, feriados, DDD com cache local.
tags: [br, api, government, brasilapi]
auth: none

📏 Steinberger bar

Barra oficial de qualidade. PR que nao passa >= 80 e fechado automaticamente pelo bot do library.

Criterio	Peso	Como passar
Reliability	30%	28+ smoke tests passam, retries, timeout configurado
Token efficiency	25%	Output medio < 500 tokens; oferece `--fields`
Docs	15%	README + SKILL.md com 3+ exemplos cada
Schema stability	15%	`--api-version`, NDJSON estavel
UX	15%	--help completo, mensagens de erro, exit codes

💡 Atingir 90+

Bater 90 abre destaque no homepage do library. Para isso: cubra todos os endpoints com teste, adicione 5+ exemplos, mantenha output abaixo de 300 tokens em casos comuns.

🔀 Fluxo de PR no library

O publish faz tudo, mas se voce quer entender o fluxo manual (ou debugar erros), o caminho com gh e este.

Fork e clone

gh repo fork mvanhorn/printing-press-library --clone
cd printing-press-library

Branch e adiciona CLI

git checkout -b add-brasil-api
mkdir -p clis/brasil-api
cp ../brasil-api-pp-cli/printingpress.yaml clis/brasil-api/
cp ../brasil-api-pp-cli/README.md clis/brasil-api/

Commit assinado + PR

git add clis/brasil-api/
git commit -S -m "Add brasil-api CLI (CEP, CNPJ, bancos, feriados, DDD)"
git push origin add-brasil-api
gh pr create --title "Add brasil-api" --body-file PR_BODY.md

🏷️ Labels obrigatorias

O bot exige kind:cli + status:needs-review. O publish aplica automaticamente; no fluxo manual, use gh pr edit --add-label "kind:cli,status:needs-review".

🔒 Library privada do time

Sua CLI usa API interna? Nao publique no library publico. Hospede em repo privado e configure o starter para puxar dali.

Configurar registry privado

# 1. Crie repo privado seguindo estrutura do library publico
gh repo create acme-corp/printing-press-library --private

# 2. Configure o printing-press
printing-press config set registry.acme https://github.com/acme-corp/printing-press-library

# 3. Instale CLIs do registry privado
npx -y @mvanhorn/printing-press install acme/fatura --registry acme

✓ Quando usar privado

✓API interna (ERP, CRM proprietario)
✓CLI com logica de negocio sensivel
✓Time pequeno reusando entre projetos

📂 Estrutura igual

acme-corp/printing-press-library/
├── clis/
│   ├── fatura/
│   │   ├── printingpress.yaml
│   │   └── README.md
│   └── ...
├── bundles/
│   └── starter-acme.yaml
└── README.md

🔄 Manutencao: regen-merge

API do alvo mudou? Reexecute o pipeline mantendo seus patches manuais via three-way merge.

Comando

$ printing-press regen-merge

[1/4] Snapshot do codigo atual...    OK
[2/4] Re-research no endpoint...     OK (3 endpoints novos detectados)
[3/4] Generate em branch auxiliar... OK
[4/4] Three-way merge...
       Conflitos em 2 arquivos:
         - cmd/cnpj.go     (campo novo "porte_da_empresa")
         - internal/format/cnpj.tmpl
       Abra com VSCode? (Y/n)

🔀 Como funciona o merge

O factory compara: (A) codigo gerado original, (B) seu codigo atual (com patches), (C) novo codigo gerado. Onde A=B mas C diferente, ele aceita C. Onde voce mexeu (A != B), tenta merge ou pede resolucao manual.

🩹 patch e emboss: hotfix rapido

Bug critico em producao? patch aplica fix pontual, emboss reformata para padrao do library. Sem pipeline inteiro.

🩹 patch

$ printing-press patch \
    --file cmd/cnpj.go \
    --describe "trata 502 da Receita"

# gera diff, voce revisa
# semver bump automatico: 0.1.2 -> 0.1.3
# publish opcional na sequencia

Bom para: bug isolado, fix de regex, melhoria de mensagem.

✨ emboss

$ printing-press emboss

[OK] Aplica gofmt + lint
[OK] Padroniza cor de erros
[OK] Adiciona alias canonicos
[OK] Reordena --help

Bom para: alinhar CLI antiga com padroes novos do library.

⚠️ Rollback

Patch ruim foi publicado? printing-press rollback --version 0.1.2 remove a versao quebrada do library e marca a anterior como current. Resolva o bug, faca novo patch.

🎓 Resumo do Modulo (e da trilha!)

✓

printing-press publish — fork + PR + labels em um comando.

✓

Steinberger bar >= 80 — gate de qualidade do library publico.

✓

Library privada — para CLIs com API interna do time.

✓

regen-merge — atualiza CLI sem perder customizacao.

✓

patch + emboss — hotfix sem rodar pipeline inteiro.

Voce concluiu a trilha! 🎉

Conceitos, instalacao, primeiros comandos, criacao de CLI, caso pratico BrasilAPI, integracoes n8n + Supabase e publicacao. Agora e construir uma CLI de verdade pro seu trabalho.

← Modulo anterior Voltar para Trilha →