@acropole/skills 0.0.0-stage → 1.0.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.
Files changed (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,227 @@
1
+ // Núcleo dos verificadores das skills (`skills/<skill>/scripts/checar.mjs`). Sem dependências, só Node ≥ 18.
2
+ // FONTE ÚNICA: este arquivo é copiado para `skills/<skill>/scripts/nucleo.mjs` pelo `npm run sync`
3
+ // (cada skill é instalada sozinha, então leva a própria cópia). Edite aqui, nunca a cópia.
4
+ //
5
+ // Uso (pelo checar.mjs de cada skill): node checar.mjs [caminhos...] [--json]
6
+ // sem caminhos: a pasta atual (ignora node_modules, dist, .angular, .git, venvs e caches).
7
+ // saída: `arquivo:linha regra mensagem → correção`; código de saída 1 se achar algo.
8
+ // Exceção pontual, na linha ANTERIOR, em comentário da linguagem:
9
+ // // acropole-ignore-next-line <regra>[,<regra>] -- motivo
10
+ // Sem motivo depois de `--`, a exceção não vale.
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+
14
+ const PASTAS_IGNORADAS = new Set(['node_modules', 'dist', '.angular', '.git', '.venv', 'venv', '__pycache__', '.pytest_cache', '.mypy_cache', 'coverage', '.nx', '.turbo']);
15
+
16
+ const C_LIKE = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.scss', '.less']);
17
+
18
+ /** Troca cada caractere (menos quebras de linha) de `s[a..b)` por espaço. */
19
+ function apagar(chars, a, b) {
20
+ for (let i = a; i < b; i++) if (chars[i] !== '\n') chars[i] = ' ';
21
+ }
22
+
23
+ /** Texto com os comentários apagados (mesmo tamanho, mesmas linhas). Strings ficam. */
24
+ export function semComentarios(texto, ext) {
25
+ const c = texto.split('');
26
+ const n = texto.length;
27
+ if (ext === '.html' || ext === '.htm') {
28
+ for (const m of texto.matchAll(/<!--[\s\S]*?(-->|$)/g)) apagar(c, m.index, m.index + m[0].length);
29
+ return c.join('');
30
+ }
31
+ if (ext === '.py') {
32
+ for (let i = 0; i < n; i++) {
33
+ const ch = texto[i];
34
+ if (ch === '#') {
35
+ const fim = texto.indexOf('\n', i);
36
+ apagar(c, i, fim < 0 ? n : fim);
37
+ i = fim < 0 ? n : fim;
38
+ } else if (ch === '"' || ch === "'") {
39
+ const triplo = texto.startsWith(ch.repeat(3), i);
40
+ const fecha = triplo ? ch.repeat(3) : ch;
41
+ let j = i + fecha.length;
42
+ while (j < n && !texto.startsWith(fecha, j)) {
43
+ if (texto[j] === '\\') j++;
44
+ else if (!triplo && texto[j] === '\n') break;
45
+ j++;
46
+ }
47
+ i = j + fecha.length - 1;
48
+ }
49
+ }
50
+ return c.join('');
51
+ }
52
+ const barraDupla = C_LIKE.has(ext); // .css puro só tem /* */
53
+ for (let i = 0; i < n; i++) {
54
+ const ch = texto[i];
55
+ if (ch === '/' && texto[i + 1] === '*') {
56
+ const fim = texto.indexOf('*/', i + 2);
57
+ const f = fim < 0 ? n : fim + 2;
58
+ apagar(c, i, f);
59
+ i = f - 1;
60
+ } else if (barraDupla && ch === '/' && texto[i + 1] === '/' && texto[i - 1] !== ':') {
61
+ const fim = texto.indexOf('\n', i);
62
+ apagar(c, i, fim < 0 ? n : fim);
63
+ i = fim < 0 ? n : fim;
64
+ } else if (ch === '"' || ch === "'" || ch === '`') {
65
+ let j = i + 1;
66
+ while (j < n && texto[j] !== ch) {
67
+ if (texto[j] === '\\') j++;
68
+ else if (ch !== '`' && texto[j] === '\n') break;
69
+ j++;
70
+ }
71
+ i = j;
72
+ }
73
+ }
74
+ let out = c.join('');
75
+ // Comentário HTML dentro de template inline.
76
+ if (ext === '.ts') out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '));
77
+ return out;
78
+ }
79
+
80
+ /** Monta o objeto de arquivo que as regras recebem. */
81
+ export function lerArquivo(caminho, rel, raiz = path.dirname(caminho)) {
82
+ const texto = fs.readFileSync(caminho, 'utf8').replace(/\r\n?/g, '\n');
83
+ const ext = path.extname(caminho).toLowerCase();
84
+ const inicios = [0];
85
+ for (let i = 0; i < texto.length; i++) if (texto[i] === '\n') inicios.push(i + 1);
86
+ const linhaDe = (idx) => {
87
+ let lo = 0;
88
+ let hi = inicios.length - 1;
89
+ while (lo < hi) {
90
+ const mid = (lo + hi + 1) >> 1;
91
+ if (inicios[mid] <= idx) lo = mid;
92
+ else hi = mid - 1;
93
+ }
94
+ return lo + 1;
95
+ };
96
+ // relRaiz: relativo ao caminho pedido na linha de comando (para regras que olham pastas, ex.: tests/).
97
+ const relRaiz = path.relative(raiz, caminho).split(path.sep).join('/') || path.basename(caminho);
98
+ return { caminho, rel, relRaiz, ext, nome: path.basename(caminho), texto, limpo: semComentarios(texto, ext), linhaDe };
99
+ }
100
+
101
+ /** Trechos de template HTML: o arquivo `.html` inteiro ou `template: \`...\`` de um `.ts`. `{ texto, inicio }`. */
102
+ export function templates(arq) {
103
+ if (arq.ext === '.html') return [{ texto: arq.limpo, inicio: 0 }];
104
+ if (arq.ext !== '.ts') return [];
105
+ const out = [];
106
+ for (const m of arq.limpo.matchAll(/\btemplate\s*:\s*`/g)) {
107
+ const ini = m.index + m[0].length;
108
+ const fim = arq.limpo.indexOf('`', ini);
109
+ if (fim > ini) out.push({ texto: arq.limpo.slice(ini, fim), inicio: ini });
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /** Trechos de CSS: `.css`/`.scss` inteiros ou `styles: \`...\`` / `styles: [\`...\`]` de um `.ts`. */
115
+ export function estilos(arq) {
116
+ if (arq.ext === '.css' || arq.ext === '.scss' || arq.ext === '.less') return [{ texto: arq.limpo, inicio: 0 }];
117
+ if (arq.ext !== '.ts') return [];
118
+ const out = [];
119
+ for (const m of arq.limpo.matchAll(/\bstyles\s*:\s*\[?/g)) {
120
+ let i = m.index + m[0].length;
121
+ for (;;) {
122
+ while (/[\s,]/.test(arq.limpo[i] ?? '')) i++;
123
+ const q = arq.limpo[i];
124
+ if (q !== '`' && q !== "'" && q !== '"') break;
125
+ const fim = arq.limpo.indexOf(q, i + 1);
126
+ if (fim < 0) break;
127
+ // O conteúdo da string é CSS: apaga os /* */ dele.
128
+ out.push({ texto: semComentarios(arq.limpo.slice(i + 1, fim), '.css'), inicio: i + 1 });
129
+ i = fim + 1;
130
+ if (arq.limpo[m.index + m[0].length - 1] !== '[') break;
131
+ }
132
+ }
133
+ return out;
134
+ }
135
+
136
+ /** Lista os arquivos a verificar: `[{ caminho, raiz }]` (raiz = o caminho pedido que o contém). */
137
+ export function listarArquivos(caminhos, cwd, aceita) {
138
+ const out = new Map();
139
+ let raiz = '';
140
+ const visitar = (p, explicito) => {
141
+ let st;
142
+ try {
143
+ st = fs.statSync(p);
144
+ } catch {
145
+ throw new Error(`caminho não encontrado: ${p}`);
146
+ }
147
+ if (st.isDirectory()) {
148
+ if (!explicito && PASTAS_IGNORADAS.has(path.basename(p))) return;
149
+ if (explicito) raiz = p;
150
+ for (const e of fs.readdirSync(p).sort()) visitar(path.join(p, e), false);
151
+ } else if ((explicito || aceita(p)) && !out.has(p)) out.set(p, explicito ? path.dirname(p) : raiz);
152
+ };
153
+ for (const c of caminhos.length ? caminhos : ['.']) visitar(path.resolve(cwd, c), true);
154
+ return [...out].filter(([p]) => aceita(p)).map(([caminho, r]) => ({ caminho, raiz: r }));
155
+ }
156
+
157
+ const IGNORE = /acropole-ignore-next-line\s+([\w,-]+)(?:\s+--(.*?))?\s*(?:\*\/|-->)?\s*$/;
158
+
159
+ /** Exceção declarada na linha anterior: `{ regras: Set, motivo }` ou null. */
160
+ function excecao(arq, linha) {
161
+ const anterior = arq.texto.split('\n')[linha - 2];
162
+ const m = anterior && anterior.match(IGNORE);
163
+ if (!m) return null;
164
+ return { regras: new Set(m[1].split(',').filter(Boolean)), motivo: (m[2] ?? '').trim() };
165
+ }
166
+
167
+ /**
168
+ * Roda as regras. `regras`: `[{ id, aceita(arq) => bool, checar(arq, ctx) => [{ linha, mensagem, correcao }] }]`.
169
+ * `preparar(arquivos, ctx)` opcional roda antes, com todos os arquivos lidos (ex.: coletar declarações).
170
+ */
171
+ export function verificar({ regras, caminhos = [], cwd = process.cwd(), extensoes, preparar }) {
172
+ const aceita = (p) => extensoes.includes(path.extname(p).toLowerCase()) || extensoes.includes(path.basename(p));
173
+ const arquivos = listarArquivos(caminhos, cwd, aceita).map(({ caminho, raiz }) =>
174
+ lerArquivo(caminho, path.relative(cwd, caminho).split(path.sep).join('/') || path.basename(caminho), raiz),
175
+ );
176
+ const ctx = {};
177
+ if (preparar) preparar(arquivos, ctx);
178
+ const achados = [];
179
+ for (const arq of arquivos) {
180
+ for (const regra of regras) {
181
+ if (regra.aceita && !regra.aceita(arq)) continue;
182
+ for (const a of regra.checar(arq, ctx) ?? []) {
183
+ const exc = excecao(arq, a.linha);
184
+ let correcao = a.correcao;
185
+ if (exc && exc.regras.has(regra.id)) {
186
+ if (exc.motivo) continue;
187
+ correcao += ' (a exceção acropole-ignore-next-line precisa de motivo depois de "--")';
188
+ }
189
+ achados.push({ arquivo: arq.rel, linha: a.linha, regra: regra.id, mensagem: a.mensagem, correcao });
190
+ }
191
+ }
192
+ }
193
+ achados.sort((a, b) => (a.arquivo < b.arquivo ? -1 : a.arquivo > b.arquivo ? 1 : a.linha - b.linha || (a.regra < b.regra ? -1 : 1)));
194
+ // Mesmo achado duas vezes na mesma linha (ex.: duas cores) vira um só por regra+mensagem.
195
+ const unicos = [...new Map(achados.map((a) => [`${a.arquivo}:${a.linha}:${a.regra}:${a.mensagem}`, a])).values()];
196
+ return { arquivos: arquivos.length, achados: unicos };
197
+ }
198
+
199
+ /** Ponto de entrada dos checar.mjs: lê argv, imprime e define o código de saída. */
200
+ export function executar({ skill, descricao, regras, extensoes, preparar, argv = process.argv.slice(2) }) {
201
+ if (argv.includes('--help') || argv.includes('-h')) {
202
+ console.log(`Verificador da skill ${skill}: ${descricao}
203
+
204
+ Uso: node checar.mjs [caminhos...] [--json]
205
+ sem caminhos, verifica a pasta atual (ignora node_modules, dist, .angular...).
206
+ Exceção (linha anterior, em comentário): acropole-ignore-next-line <regra> -- motivo
207
+
208
+ Regras:
209
+ ${regras.map((r) => ` ${r.id.padEnd(28)} ${r.resumo}`).join('\n')}`);
210
+ return 0;
211
+ }
212
+ const json = argv.includes('--json');
213
+ const caminhos = argv.filter((a) => a !== '--json');
214
+ let r;
215
+ try {
216
+ r = verificar({ regras, caminhos, extensoes, preparar });
217
+ } catch (e) {
218
+ console.error(`checar (${skill}): ${e.message}`);
219
+ return 2;
220
+ }
221
+ if (json) console.log(JSON.stringify({ skill, arquivos: r.arquivos, achados: r.achados }, null, 2));
222
+ else {
223
+ for (const a of r.achados) console.log(`${a.arquivo}:${a.linha} ${a.regra} ${a.mensagem} → ${a.correcao}`);
224
+ console.log(r.achados.length ? `\n${r.achados.length} problema(s) em ${r.arquivos} arquivo(s) verificado(s).` : `Nada encontrado (${r.arquivos} arquivo(s) verificado(s)).`);
225
+ }
226
+ return r.achados.length ? 1 : 0;
227
+ }
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: docker
3
+ description: Como escrever (e revisar) os Dockerfiles e o .dockerignore dos apps — Angular estático, Node (Express/Apollo) e Python (FastAPI) — e o porquê de cada decisão - multi-stage, imagem base, cache de dependências, sem credencial na imagem, CMD em forma exec para o SIGTERM chegar ao processo, usuário não-root, HEALTHCHECK, porta, ARG x ENV, workers do uvicorn. Use ao criar, alterar ou revisar um Dockerfile/.dockerignore, ou ao investigar build lento, imagem grande, deploy que demora a parar ou container que não sobe. Não use para o processo de deploy, cadastro ou rollback na plataforma (use hefesto), nem para o código do app (angular, express, apollo, fastapi).
4
+ ---
5
+
6
+ # docker
7
+
8
+ Padrão dos Dockerfiles dos apps, extraído do que funciona no build pelo Ciclope (Podman/Buildah) e
9
+ na execução pelo Talos (ver **hefesto**). Vale também para Docker/BuildKit local. Cada regra tem o
10
+ motivo em `references/porques.md`; modelos completos e comentados em `references/modelos.md`.
11
+
12
+ ## Regras essenciais
13
+
14
+ 1. **Multi-stage**: um estágio instala e compila; o final leva só o que roda (`dist` +
15
+ dependências de produção). Ferramenta de build, devDependencies e cache nunca chegam à imagem
16
+ final.
17
+ 2. **Base por stack**: Node runtime em `node:22-alpine`; build do Angular em `node:22-slim`
18
+ (binários nativos do esbuild/sass são glibc); Python em `python:3.12-slim` (wheels prontas;
19
+ Alpine obriga a compilar). Fixe a versão maior, nunca `latest`.
20
+ 3. **Cache de dependências**: copie **só os manifestos** (`package.json` + `package-lock.json`,
21
+ `requirements.txt`), instale, e só depois copie o código. Use `npm ci` (lockfile, determinístico)
22
+ e `RUN --mount=type=cache,...` para o cache de download sobreviver entre builds.
23
+ 4. **Nenhuma credencial na imagem**: sem `COPY .npmrc`, sem `ARG`/`ENV` de token, senha, índice
24
+ privado com usuário. `@trismegisto/*`, `@orfeu/*` e `orfeu` vêm do npm/PyPI público. Se algum dia
25
+ precisar, `RUN --mount=type=secret` (não fica em camada).
26
+ 5. **CMD/ENTRYPOINT em forma exec** — `CMD ["node", "dist/index.js"]`. Nunca `CMD npm start`,
27
+ `CMD node dist/index.js` (shell form) nem `sh -c` sem `exec`: o PID 1 vira o `npm`/`sh`, que não
28
+ repassa o SIGTERM; o `podman stop` espera 10 s e mata com SIGKILL, sem graceful shutdown e sem
29
+ o flush da auditoria do Orfeu. Se precisar expandir variável: `CMD ["sh", "-c", "exec uvicorn ...
30
+ --port $PORT"]`.
31
+ 6. **O processo trata SIGTERM**. Node como PID 1 **não tem ação padrão para sinais**: sem
32
+ `process.once('SIGTERM', ...)` o sinal é ignorado. Uvicorn trata sozinho e roda o shutdown do
33
+ lifespan. Ver **express**/**fastapi** para o handler.
34
+ 7. **Usuário não-root** no estágio final (`USER node`; em Python, um usuário criado). Porta acima de
35
+ 1024; diretório gravável com `--chown`.
36
+ 8. **`HEALTHCHECK`** chamando o `/health` do app com ferramenta que existe na imagem (`wget` do
37
+ busybox no Alpine, `python -c` no slim). Com Podman/Buildah só é gravado em imagem formato
38
+ `docker`; no deploy, o `/health` é verificado de fora de qualquer jeito.
39
+ 9. **`ENV PORT` + `EXPOSE`** com a porta cadastrada no Hefesto; o processo escuta em `0.0.0.0`.
40
+ 10. **ARG é build, ENV é runtime.** Build arg só para o que muda o artefato (ex.:
41
+ `CONFIGURATION` do Angular), declarado **depois** do install. Configuração por ambiente (URLs,
42
+ banco, identidade) vem do ambiente em runtime, nunca de `ENV` fixo no Dockerfile.
43
+ 11. **`.dockerignore` na raiz do contexto** com `.git`, dependências locais, `dist`, caches e
44
+ `.env`/`.env.*` (menos `.env.example`). Consequência intencional: o app no container lê config
45
+ só do ambiente.
46
+ 12. **`timeout -k 10 <s>`** em todo `RUN` que baixa ou compila: o Podman só cancela um build no passo
47
+ seguinte; um `npm ci` travado ficaria rodando no host.
48
+ 13. **Segredo sem valor padrão**: nada de `ENV AGENT_TOKEN=changeme` nem `getenv("X", "changeme")`. Sem a
49
+ variável, o serviço **falha no boot** dizendo qual falta.
50
+ 14. **Quem roda container por código** passa env e segredos por `--env-file` temporário (permissão 600,
51
+ apagado no `finally`), nunca `-e K=V` no argv (aparece em `ps` e em log). Nome que vira caminho é
52
+ validado e contido na raiz (`Path.resolve()`) antes de `rmtree`/escrita.
53
+ 15. **`.gitattributes` com `*.sh text eol=lf`**: script com CRLF quebra no container.
54
+
55
+ ## Por stack (resumo — modelos em `references/modelos.md`)
56
+
57
+ **Angular (site)** — estágios `dev` (`ng serve`, para compose local), `build`
58
+ (`ng build --configuration $CONFIGURATION`, com `ARG CONFIGURATION=prod` depois do `npm ci` e cache
59
+ do `.angular/cache`) e **`site`**: `FROM scratch`, `COPY --from=build /app/dist/<projeto>/browser
60
+ /dist`, `CMD ["unused"]`. A imagem nunca roda: o Talos a cria, copia o `/dist` e o Caddy do servidor
61
+ serve os arquivos. É o **último** estágio, então compose local precisa de `target: dev`. Budget
62
+ estourado (`maximumError`) quebra o build — conserte o bundle (ver **angular**).
63
+
64
+ **Node (Express/Apollo)** — `build`: `npm ci` → `COPY tsconfig.json` + `src` → `npm run build` →
65
+ `npm prune --omit=dev` → remover `.d.ts`/`.map`/`*.md` e `@types` do `node_modules`. Final:
66
+ `node:22-alpine`, sem npm/yarn/corepack, `COPY --from=build` de `package.json`, `node_modules` e
67
+ `dist`, `USER node`, `CMD ["node", "dist/index.js"]` (com aliases de path em runtime:
68
+ `["node", "-r", "tsconfig-paths/register", "dist/index.js"]` e `ENV TS_NODE_BASEURL=./dist`).
69
+
70
+ **Python (FastAPI)** — estágio único quando todas as dependências têm wheel; `COPY
71
+ requirements.txt` → `pip install` com cache montado → `COPY src`. `PYTHONUNBUFFERED=1` (log sai na
72
+ hora), `PYTHONDONTWRITEBYTECODE=1`. `CMD ["sh", "-c", "exec uvicorn src.main:app --host 0.0.0.0
73
+ --port $PORT"]`. **Um processo por container** (sem `--workers` > 1) se o app tem tarefa em
74
+ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a tarefa duplica.
75
+
76
+ ## Erros comuns (sintoma → causa)
77
+
78
+ | Sintoma | Causa |
79
+ | --- | --- |
80
+ | Todo deploy/stop leva ~10 s e a auditoria some | CMD em shell form, `npm start` ou `sh -c` sem `exec`; ou Node sem handler de SIGTERM |
81
+ | Build sempre reinstala tudo | `COPY . .` antes do `npm ci`/`pip install`; `ARG` declarado antes do install; contexto com `node_modules`/`.git` |
82
+ | `npm ci` falha: lock fora de sincronia | `package.json` mudou sem atualizar o `package-lock.json` |
83
+ | Funciona local, quebra no container com erro de binário nativo | `node_modules` do host (Windows/macOS) entrou pelo `COPY . .` — faltou no `.dockerignore`; ou módulo glibc em Alpine |
84
+ | Imagem enorme | estágio único com devDependencies, `.git` no contexto, cache do pip/npm gravado em camada |
85
+ | Container sobe e cai: settings sem variável | config estava em `.env.*` (fora da imagem) e não foi cadastrada no ambiente |
86
+ | `docker create` falha: "no command specified" | estágio `scratch` sem `CMD` |
87
+ | Site extraído sem arquivos | build não copiou para `/dist` (ou copiou `dist/<proj>` em vez de `.../browser`) |
88
+ | Compose local sobe um container que sai na hora | estágio final é o `site`; faltou `target: dev` |
89
+ | `EACCES` ao escrever arquivo | `USER` não-root e pasta sem `--chown` |
90
+ | Tarefas agendadas executando em dobro | `uvicorn --workers N` (ou várias réplicas) com scheduler no lifespan |
91
+ | Credencial aparece em `docker history`/`inspect` | `ARG`/`ENV` de token, ou `.npmrc` copiado |
92
+ | Serviço sobe sem a variável de segredo e aceita `changeme` | default de segredo no `ENV` ou no `getenv` |
93
+ | Segredo visível em `ps aux` no host | `podman run -e SEGREDO=...` montado por código; use `--env-file` temporário |
94
+ | `/bin/sh^M: bad interpreter` / `$'\r': command not found` | `.sh` com CRLF; falta `*.sh text eol=lf` no `.gitattributes` |
95
+ | HEALTHCHECK ignorado com aviso no build | Podman/Buildah em formato OCI (padrão); só o formato `docker` grava |
96
+
97
+ ## Índice de referências
98
+
99
+ | Arquivo | Conteúdo |
100
+ | --- | --- |
101
+ | `references/modelos.md` | Dockerfiles comentados: Angular (dev/build/site), Node (Express/Apollo), Node servindo SPA + API, Python (FastAPI, com e sem compilação); `.dockerignore` por stack |
102
+ | `references/porques.md` | Cada decisão explicada: base, multi-stage, cache, `npm ci`, credenciais, segredo sem default, `--env-file`, nome que vira caminho, `.sh` em LF, sinais e PID 1, exec form, não-root, HEALTHCHECK, porta, ARG x ENV, `.dockerignore`, `timeout`, scratch no Angular, workers do uvicorn, Podman x Docker |
@@ -0,0 +1,251 @@
1
+ # Modelos de Dockerfile
2
+
3
+ Genéricos: troque `meu-app`, portas e prefixos. O porquê de cada linha está em `porques.md`.
4
+ Todos supõem o build pelo Hefesto (Podman/Buildah) ou Docker com BuildKit (`--mount=type=cache`).
5
+
6
+ ## Angular (site estático)
7
+
8
+ ```dockerfile
9
+ # ── dev: ng serve com live-reload, só para compose local (target: dev) ──────────────────────
10
+ FROM node:22-slim AS dev
11
+ WORKDIR /app
12
+ # Só os manifestos: enquanto eles não mudam, a camada do npm ci vem do cache.
13
+ COPY package.json package-lock.json ./
14
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
15
+ timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
16
+ COPY . .
17
+ EXPOSE 4200
18
+ CMD ["./node_modules/.bin/ng", "serve", "--configuration", "dev", "--host", "0.0.0.0", "--no-hmr", "--port", "4200"]
19
+
20
+ # ── build: o build de verdade, por ambiente ─────────────────────────────────────────────────
21
+ FROM node:22-slim AS build
22
+ WORKDIR /app
23
+ COPY package.json package-lock.json ./
24
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
25
+ timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
26
+ COPY . .
27
+ # Depois do install: um ARG entra no ambiente dos RUN seguintes; declarado antes, cada
28
+ # ambiente invalidaria o cache do npm ci. O Hefesto passa o nome do ambiente.
29
+ ARG CONFIGURATION=prod
30
+ # Cache do Angular CLI fora da imagem (com cli.cache.environment = "all" no angular.json).
31
+ RUN --mount=type=cache,target=/app/.angular/cache,sharing=locked \
32
+ timeout -k 10 300 ./node_modules/.bin/ng build --configuration $CONFIGURATION
33
+
34
+ # ── site: só transporta o /dist. Nunca roda; é o ÚLTIMO estágio (o --target do Hefesto) ──────
35
+ FROM scratch AS site
36
+ COPY --from=build /app/dist/meu-app/browser /dist
37
+ # `create` exige um comando no manifesto, mesmo que o container nunca rode (scratch não tem shell).
38
+ CMD ["unused"]
39
+ ```
40
+
41
+ Fora do Hefesto (servir com nginx próprio), troque o estágio `site` por um `nginx:alpine` com o
42
+ `/dist` no `root` e fallback de SPA — ver **angular** (`references/testes-build.md`).
43
+
44
+ ## Node — Express/Apollo (TypeScript compilado)
45
+
46
+ ```dockerfile
47
+ # ── build: uma instalação só; compila e enxuga o node_modules ───────────────────────────────
48
+ FROM node:22-alpine AS build
49
+ WORKDIR /app
50
+ COPY package.json package-lock.json ./
51
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
52
+ timeout -k 10 600 npm ci --no-audit --no-fund
53
+ COPY tsconfig.json ./
54
+ COPY src ./src
55
+ # prune tira as devDependencies; o find tira o que nunca executa (tipos, source maps, markdown)
56
+ # por TIPO de arquivo — nunca por nome de pasta, algum pacote tem código em "docs"/"test".
57
+ RUN timeout -k 10 300 npm run build \
58
+ && npm prune --omit=dev --no-audit --no-fund \
59
+ && find node_modules -type f \( -name '*.d.ts' -o -name '*.d.mts' -o -name '*.d.cts' -o -name '*.map' \
60
+ -o -name '*.md' -o -name '*.markdown' -o -name '*.tsbuildinfo' \) ! -iname 'LICENSE*' -delete \
61
+ && rm -rf node_modules/@types
62
+
63
+ # ── runtime ─────────────────────────────────────────────────────────────────────────────────
64
+ FROM node:22-alpine
65
+ # Sem npm/yarn/corepack (~20 MB): ninguém roda `npm start` aqui por engano.
66
+ RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
67
+ /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack \
68
+ /opt/yarn-* /usr/local/bin/yarn /usr/local/bin/yarnpkg
69
+ WORKDIR /app
70
+ COPY --from=build /app/package.json ./
71
+ COPY --from=build /app/node_modules ./node_modules
72
+ COPY --from=build /app/dist ./dist
73
+ # Padrões não sensíveis; o que muda por ambiente vem das variáveis do deploy.
74
+ ENV NODE_ENV=production \
75
+ PORT=3000
76
+ EXPOSE 3000
77
+ USER node
78
+ # wget do busybox existe no Alpine; o path inclui o prefixo em que o app responde.
79
+ HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
80
+ CMD wget -qO- "http://127.0.0.1:${PORT}/meu-app/api/health" > /dev/null || exit 1
81
+ # Forma exec: node é o PID 1 e recebe o SIGTERM. O app registra o handler (flushAudit + close).
82
+ CMD ["node", "dist/index.js"]
83
+ ```
84
+
85
+ Com aliases de path (`@core/*`) resolvidos em runtime por `tsconfig-paths`:
86
+
87
+ ```dockerfile
88
+ COPY --from=build /app/package.json /app/tsconfig.json ./
89
+ ENV TS_NODE_BASEURL=./dist
90
+ CMD ["node", "-r", "tsconfig-paths/register", "dist/index.js"]
91
+ ```
92
+
93
+ (`tsconfig-paths` precisa estar em `dependencies`, não em `devDependencies`, senão o prune o remove.)
94
+
95
+ ## Node servindo a SPA + API no mesmo container
96
+
97
+ Dois estágios de build independentes (o Buildah com `--jobs` roda em paralelo) e um runtime:
98
+
99
+ ```dockerfile
100
+ FROM node:22-slim AS ui-build
101
+ WORKDIR /ui
102
+ COPY ui/package.json ui/package-lock.json ./
103
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
104
+ timeout -k 10 600 npm ci --no-audit --no-fund
105
+ COPY ui/. .
106
+ ARG CONFIGURATION=prod
107
+ RUN timeout -k 10 300 npm run build -- --configuration=$CONFIGURATION
108
+
109
+ FROM node:22-alpine AS server-build
110
+ WORKDIR /app
111
+ COPY server/package.json server/package-lock.json server/tsconfig.json ./
112
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
113
+ timeout -k 10 600 npm ci --no-audit --no-fund
114
+ COPY server/src ./src
115
+ RUN timeout -k 10 300 npm run build && npm prune --omit=dev --no-audit --no-fund
116
+
117
+ FROM node:22-alpine
118
+ RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
119
+ /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack \
120
+ /opt/yarn-* /usr/local/bin/yarn /usr/local/bin/yarnpkg
121
+ WORKDIR /app
122
+ COPY --from=server-build /app/package.json ./
123
+ COPY --from=server-build /app/node_modules ./node_modules
124
+ COPY --from=server-build /app/dist ./dist
125
+ COPY --from=ui-build /ui/dist /ui/dist
126
+ ENV NODE_ENV=production PORT=3000 \
127
+ UI_STATIC_PATH=/ui/dist/meu-app/browser \
128
+ UI_BASE_PATH=/meu-app
129
+ EXPOSE 3000
130
+ USER node
131
+ CMD ["node", "dist/index.js"]
132
+ ```
133
+
134
+ O `.dockerignore` fica na raiz do contexto (a pasta que contém `ui/` e `server/`); os de subpastas
135
+ não têm efeito.
136
+
137
+ ## Python — FastAPI (dependências com wheel pronta)
138
+
139
+ ```dockerfile
140
+ FROM python:3.12-slim
141
+ ENV PYTHONDONTWRITEBYTECODE=1 \
142
+ PYTHONUNBUFFERED=1 \
143
+ PIP_DISABLE_PIP_VERSION_CHECK=1
144
+ WORKDIR /app
145
+ COPY requirements.txt .
146
+ # Cache do pip montado: fica fora da imagem (dispensa --no-cache-dir) e acelera o próximo build.
147
+ RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
148
+ timeout -k 10 600 pip install -r requirements.txt
149
+ COPY src ./src
150
+ RUN useradd --system --uid 10001 --no-create-home app
151
+ ENV PORT=8000 \
152
+ PYTHONPATH=/app/src
153
+ EXPOSE 8000
154
+ USER app
155
+ HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
156
+ CMD python -c "import os,urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/meu-app/health' % os.environ['PORT'], timeout=3)"
157
+ # sh só para expandir $PORT; o exec troca o sh pelo uvicorn, que vira PID 1 e recebe o SIGTERM.
158
+ # Sem --workers: um processo por container (tarefas do lifespan não duplicam).
159
+ CMD ["sh", "-c", "exec uvicorn src.main:app --host 0.0.0.0 --port $PORT"]
160
+ ```
161
+
162
+ Porta fixa dispensa o shell: `CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]`.
163
+
164
+ ## Python — com dependência que compila
165
+
166
+ ```dockerfile
167
+ FROM python:3.12-slim AS build
168
+ RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
169
+ && rm -rf /var/lib/apt/lists/*
170
+ RUN python -m venv /opt/venv
171
+ ENV PATH=/opt/venv/bin:$PATH
172
+ COPY requirements.txt .
173
+ RUN --mount=type=cache,target=/root/.cache/pip,sharing=locked \
174
+ timeout -k 10 900 pip install -r requirements.txt
175
+
176
+ FROM python:3.12-slim
177
+ ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PATH=/opt/venv/bin:$PATH
178
+ # (instale aqui só as bibliotecas de RUNTIME do sistema, ex.: libpq5 — nunca o compilador)
179
+ COPY --from=build /opt/venv /opt/venv
180
+ WORKDIR /app
181
+ COPY src ./src
182
+ RUN useradd --system --uid 10001 --no-create-home app
183
+ ENV PORT=8000 PYTHONPATH=/app/src
184
+ EXPOSE 8000
185
+ USER app
186
+ CMD ["sh", "-c", "exec uvicorn src.main:app --host 0.0.0.0 --port $PORT"]
187
+ ```
188
+
189
+ ## `.dockerignore`
190
+
191
+ Node / Angular:
192
+
193
+ ```
194
+ .git
195
+ node_modules
196
+ dist
197
+ .angular
198
+ coverage
199
+ *.log
200
+ .env
201
+ .env.*
202
+ !.env.example
203
+ Dockerfile
204
+ .dockerignore
205
+ ```
206
+
207
+ Contexto com subpastas (`ui/` + `server/`): use `**/node_modules`, `**/dist`, `**/.env`,
208
+ `**/.env.*`, `!**/.env.example`.
209
+
210
+ Python:
211
+
212
+ ```
213
+ .git
214
+ .venv
215
+ venv
216
+ **/__pycache__
217
+ **/*.pyc
218
+ .pytest_cache
219
+ .mypy_cache
220
+ .ruff_cache
221
+ tests
222
+ **/.env
223
+ **/.env.*
224
+ !**/.env.example
225
+ *.log
226
+ Dockerfile
227
+ .dockerignore
228
+ ```
229
+
230
+ ## `.gitattributes` (raiz do repositório)
231
+
232
+ ```gitattributes
233
+ # Scripts rodam em Linux (bash/sh do container): com CRLF falham em "\r" ("$'\r': command not found").
234
+ *.sh text eol=lf
235
+ ```
236
+
237
+ ## Compose local
238
+
239
+ ```yaml
240
+ services:
241
+ meu-app-angular:
242
+ build: { context: ./angular, target: dev } # o último estágio é o "site", que não roda
243
+ ports: ["4200:4200"]
244
+ meu-app-api:
245
+ build: { context: ./api }
246
+ environment: # config de runtime, igual ao que o deploy injeta
247
+ PORT: "3000"
248
+ DB_HOST: postgres
249
+ ports: ["3000:3000"]
250
+ stop_grace_period: 15s # maior que o timeout de shutdown do app
251
+ ```