@nimbuslab/cli 0.6.2 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/publish.yml +2 -0
- package/dist/index.js +115 -115
- package/docs/CI-CD.md +172 -0
- package/package.json +1 -1
- package/src/commands/create.ts +95 -95
- package/src/index.ts +20 -20
package/docs/CI-CD.md
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# CI/CD - Publicacao no npm
|
|
2
|
+
|
|
3
|
+
Documentacao do pipeline de publicacao automatica no npm.
|
|
4
|
+
|
|
5
|
+
## Como Funciona
|
|
6
|
+
|
|
7
|
+
Ao fazer merge na branch `main`, o GitHub Actions publica automaticamente no npm.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
develop → main → GitHub Actions → npm publish
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Workflow
|
|
14
|
+
|
|
15
|
+
Arquivo: `.github/workflows/publish.yml`
|
|
16
|
+
|
|
17
|
+
```yaml
|
|
18
|
+
name: Publish to npm
|
|
19
|
+
|
|
20
|
+
on:
|
|
21
|
+
push:
|
|
22
|
+
branches:
|
|
23
|
+
- main
|
|
24
|
+
|
|
25
|
+
jobs:
|
|
26
|
+
publish:
|
|
27
|
+
runs-on: ubuntu-latest
|
|
28
|
+
permissions:
|
|
29
|
+
contents: read
|
|
30
|
+
id-token: write # Necessario para OIDC
|
|
31
|
+
|
|
32
|
+
steps:
|
|
33
|
+
- uses: actions/checkout@v4
|
|
34
|
+
- uses: oven-sh/setup-bun@v2
|
|
35
|
+
- uses: actions/setup-node@v4
|
|
36
|
+
with:
|
|
37
|
+
node-version: "24"
|
|
38
|
+
registry-url: "https://registry.npmjs.org"
|
|
39
|
+
|
|
40
|
+
- run: bun install
|
|
41
|
+
- run: bun run typecheck
|
|
42
|
+
- run: bun run build
|
|
43
|
+
|
|
44
|
+
- name: Publish to npm
|
|
45
|
+
run: npm publish --access public
|
|
46
|
+
env:
|
|
47
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Requisitos
|
|
51
|
+
|
|
52
|
+
### 1. Secret NPM_TOKEN
|
|
53
|
+
|
|
54
|
+
Configurar no GitHub:
|
|
55
|
+
1. Acesse: `Settings > Secrets and variables > Actions`
|
|
56
|
+
2. Criar secret `NPM_TOKEN` com um Granular Access Token do npm
|
|
57
|
+
|
|
58
|
+
Para criar o token no npm:
|
|
59
|
+
1. Acesse: https://www.npmjs.com/settings/tokens
|
|
60
|
+
2. Clique em "Generate New Token" > "Granular Access Token"
|
|
61
|
+
3. Selecione permissao de publish para `@nimbuslab/cli`
|
|
62
|
+
4. Copie o token e adicione como secret no GitHub
|
|
63
|
+
|
|
64
|
+
### 2. Permissoes do Workflow
|
|
65
|
+
|
|
66
|
+
O workflow precisa de:
|
|
67
|
+
- `contents: read` - para checkout
|
|
68
|
+
- `id-token: write` - para OIDC (opcional, mas recomendado)
|
|
69
|
+
|
|
70
|
+
## Fluxo de Release
|
|
71
|
+
|
|
72
|
+
1. Desenvolva na branch `develop`
|
|
73
|
+
2. Atualize a versao no `package.json` e `src/index.ts`
|
|
74
|
+
3. Commit e push: `git push origin develop`
|
|
75
|
+
4. Merge para main:
|
|
76
|
+
```bash
|
|
77
|
+
git checkout main
|
|
78
|
+
git merge develop
|
|
79
|
+
git push origin main
|
|
80
|
+
git checkout develop
|
|
81
|
+
```
|
|
82
|
+
5. GitHub Actions publica automaticamente
|
|
83
|
+
|
|
84
|
+
## Versionamento
|
|
85
|
+
|
|
86
|
+
Seguimos [Semantic Versioning](https://semver.org/):
|
|
87
|
+
|
|
88
|
+
| Tipo | Quando usar | Exemplo |
|
|
89
|
+
|------|-------------|---------|
|
|
90
|
+
| Patch | Bug fixes | 0.6.3 → 0.6.4 |
|
|
91
|
+
| Minor | Novas features | 0.6.3 → 0.7.0 |
|
|
92
|
+
| Major | Breaking changes | 0.6.3 → 1.0.0 |
|
|
93
|
+
|
|
94
|
+
**IMPORTANTE:** Atualizar a versao em DOIS lugares:
|
|
95
|
+
- `package.json` → campo `version`
|
|
96
|
+
- `src/index.ts` → constante `CURRENT_VERSION`
|
|
97
|
+
|
|
98
|
+
## Troubleshooting
|
|
99
|
+
|
|
100
|
+
### Erro: "You cannot publish over the previously published versions"
|
|
101
|
+
|
|
102
|
+
A versao ja foi publicada. Bump a versao e tente novamente.
|
|
103
|
+
|
|
104
|
+
### Erro: "E401 Unauthorized"
|
|
105
|
+
|
|
106
|
+
O token NPM_TOKEN esta invalido ou expirado.
|
|
107
|
+
1. Gere um novo token no npmjs.com
|
|
108
|
+
2. Atualize a secret no GitHub
|
|
109
|
+
|
|
110
|
+
### Erro: "E403 Forbidden"
|
|
111
|
+
|
|
112
|
+
O token nao tem permissao de publish.
|
|
113
|
+
1. Verifique se o token tem permissao para `@nimbuslab/cli`
|
|
114
|
+
2. Verifique se voce e maintainer do pacote
|
|
115
|
+
|
|
116
|
+
### CI passa mas versao nao aparece no npm
|
|
117
|
+
|
|
118
|
+
Isso pode acontecer quando:
|
|
119
|
+
1. **OIDC sem NODE_AUTH_TOKEN**: O OIDC pode falhar silenciosamente
|
|
120
|
+
2. **Trusted Publisher mal configurado**: Verificar no npmjs.com
|
|
121
|
+
|
|
122
|
+
**Solucao**: Sempre usar `NODE_AUTH_TOKEN` como fallback:
|
|
123
|
+
```yaml
|
|
124
|
+
- name: Publish to npm
|
|
125
|
+
run: npm publish --access public
|
|
126
|
+
env:
|
|
127
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Verificar se publicou
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
# Ver ultimas versoes
|
|
134
|
+
curl -s "https://registry.npmjs.org/@nimbuslab/cli" | jq '.versions | keys | .[-5:]'
|
|
135
|
+
|
|
136
|
+
# Ver versao latest
|
|
137
|
+
curl -s "https://registry.npmjs.org/@nimbuslab/cli" | jq -r '.["dist-tags"].latest'
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## OIDC Trusted Publishing (Opcional)
|
|
141
|
+
|
|
142
|
+
O npm suporta autenticacao via OIDC, eliminando necessidade de tokens.
|
|
143
|
+
|
|
144
|
+
### Configuracao no npmjs.com
|
|
145
|
+
|
|
146
|
+
1. Acesse: https://www.npmjs.com/package/@nimbuslab/cli/access
|
|
147
|
+
2. Em "Trusted Publisher", configure:
|
|
148
|
+
- Organization: `nimbuslab`
|
|
149
|
+
- Repository: `cli`
|
|
150
|
+
- Workflow: `publish.yml`
|
|
151
|
+
|
|
152
|
+
### Limitacoes do OIDC
|
|
153
|
+
|
|
154
|
+
- Nao funciona para publicar a versao inicial do pacote
|
|
155
|
+
- Pode falhar silenciosamente em alguns casos
|
|
156
|
+
- Requer `id-token: write` no workflow
|
|
157
|
+
|
|
158
|
+
**Recomendacao**: Mesmo usando OIDC, manter `NODE_AUTH_TOKEN` como fallback.
|
|
159
|
+
|
|
160
|
+
## Historico de Problemas
|
|
161
|
+
|
|
162
|
+
### 2026-01-26: Publicacao falhando silenciosamente
|
|
163
|
+
|
|
164
|
+
**Problema**: CI mostrava sucesso mas versao nao aparecia no npm.
|
|
165
|
+
|
|
166
|
+
**Causa**: OIDC Trusted Publishing falhando silenciosamente (config no npmjs.com ou bug do npm).
|
|
167
|
+
|
|
168
|
+
**Solucao**: Adicionar `NODE_AUTH_TOKEN` como fallback junto com OIDC.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
*Ultima atualizacao: 2026-01-26*
|