@acropole/skills 0.0.0-stage → 1.1.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/README.md +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- 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,156 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: express
|
|
3
|
+
description: "Servidores REST em Node/TypeScript com Express: bootstrap, ordem de middlewares, rotas, validação com zod, formato de erro, paginação, Knex, chamadas a outros serviços, health check, graceful shutdown. Use ao escrever ou revisar app.ts/server.ts, router, controller, middleware ou repositório de um backend Express — inclusive a camada HTTP de um gateway Apollo. Schema e resolvers GraphQL são da skill apollo; guard, operação e auditoria do Orfeu, da orfeu; serviço Python, da fastapi."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# express
|
|
7
|
+
|
|
8
|
+
Padrões extraídos de servidores Express em produção (APIs REST que também servem uma SPA Angular, e
|
|
9
|
+
gateways GraphQL que montam o Apollo sobre Express). Onde os projetos divergem, esta skill indica
|
|
10
|
+
**o padrão recomendado**.
|
|
11
|
+
|
|
12
|
+
Skills relacionadas (não duplicamos o conteúdo delas):
|
|
13
|
+
|
|
14
|
+
- **orfeu** — autenticação, autorização por operação (`guard`), auditoria, `traceparent`,
|
|
15
|
+
headers de correlação e `flushAudit()`. Toda rota protegida passa por ela.
|
|
16
|
+
- **apollo** — schema, resolvers, envelope `{ status, message, data }`, subscriptions.
|
|
17
|
+
Aqui só aparece a parte Express do gateway (montagem, CORS, rotas REST auxiliares).
|
|
18
|
+
- **fastapi** — serviços Python que costumam estar atrás dos gateways Node.
|
|
19
|
+
- Fastify: **ainda não coberto**.
|
|
20
|
+
|
|
21
|
+
> **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/express/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
|
|
22
|
+
|
|
23
|
+
## Regras essenciais
|
|
24
|
+
|
|
25
|
+
1. **Express 5** em serviço novo. Ele encaminha promises rejeitadas ao error handler; no Express 4 um
|
|
26
|
+
`async` handler que lança derruba a requisição sem resposta (precisa de `try/catch` ou wrapper).
|
|
27
|
+
2. **Configuração validada na subida** com `zod` (`safeParse(process.env)` → falha com a lista de
|
|
28
|
+
campos → `process.exit(1)`). Nada de `process.env.X!` espalhado pelo código.
|
|
29
|
+
3. **Camadas**: `routes/<recurso>/index.ts` (só wiring: método + caminho + guard + validação +
|
|
30
|
+
handler) → `*.controller.ts` (HTTP: lê `req`, chama serviço/repositório, monta resposta) →
|
|
31
|
+
`services/` (regra de negócio, chamadas externas) → `repositories/` (Knex) com
|
|
32
|
+
`*.entity.ts` + `*.mapper.ts` (snake_case do banco ⇄ camelCase do domínio).
|
|
33
|
+
4. **Ordem dos middlewares**: request-id → logger → body parsers → security headers → cookies →
|
|
34
|
+
estáticos (se servir SPA) → **CORS só no prefixo da API** → router da API → fallback da SPA →
|
|
35
|
+
error handler (sempre o último). Detalhes em `references/middlewares.md`.
|
|
36
|
+
5. **Toda rota protegida declara uma operação** com o `guard(identificador, Level, Method?)` do
|
|
37
|
+
Orfeu, na linha da própria rota. Identificador `area:recurso:acao` (ex.: `admin:groups:list`).
|
|
38
|
+
Ver orfeu.
|
|
39
|
+
6. **Erro em JSON com código estável**: `{ "error": "snake_case_code", "detail": "texto para humano" }`.
|
|
40
|
+
Status HTTP correto (400 entrada inválida, 401 sem/token inválido, 403 sem permissão, 404, 409
|
|
41
|
+
conflito, 429, 503 dependência fora). Ver `references/rotas-erros.md`.
|
|
42
|
+
7. **Paginação**: cursor opaco (keyset) para listas grandes/ordenadas por tempo —
|
|
43
|
+
`{ items, next_cursor }`; offset (`page`/`limit` com teto) para telas administrativas pequenas.
|
|
44
|
+
8. **Banco via Knex** com pool configurado e `keepAlive`; transação com `db.transaction(async trx => …)`
|
|
45
|
+
e repositórios aceitando `trx?` opcional. Migrations são SQL versionado aplicado **fora** do boot.
|
|
46
|
+
9. **Chamadas a outros serviços repassam credencial e trace** (`orfeuHeaders(ctx)` dentro do contexto
|
|
47
|
+
do Orfeu; repasse explícito dos headers nas rotas que não passam por ele). Nunca gere um span
|
|
48
|
+
próprio que ninguém audita.
|
|
49
|
+
10. **Graceful shutdown** em `SIGTERM`/`SIGINT`: timer de segurança `unref()` (8 s, sai com **1**),
|
|
50
|
+
`flushAudit()` do Orfeu, `server.close()` (sai com **0**). No container o `node` é PID 1 e roda direto
|
|
51
|
+
(`CMD ["node", …]`), nunca via `npm start`.
|
|
52
|
+
11. **Health check** em `GET <prefixo>/health`: verifica as dependências reais (`SELECT 1`, `PING`) com
|
|
53
|
+
`Promise.allSettled` e responde `200`/`503` com o estado de cada uma (+ `tls_verify: false` quando
|
|
54
|
+
`AUTH_TLS_VERIFY=false`). **Swagger (`<prefixo>/docs`) só com `API_DOCS`**, que por padrão liga só em
|
|
55
|
+
`NODE_ENV=local`. Padrão do app inteiro: skill `acropole` (`references/arquitetura.md`).
|
|
56
|
+
12. **Logs JSON de uma linha** em produção (`{ time, level, msg, ...ctx }`), coloridos só em dev;
|
|
57
|
+
nunca logar token, senha, segredo ou corpo de requisição de autenticação.
|
|
58
|
+
13. **Rota escopada por recurso pai** (`/:clientId/...`) confere a posse de **todo** id da URL e do corpo
|
|
59
|
+
(`WHERE id = ? AND client_id = ?`). Recurso de outro escopo responde **404**, igual ao inexistente
|
|
60
|
+
(IDOR). Ver `references/rotas-erros.md`.
|
|
61
|
+
14. **Entrada inválida é 400, nunca 500**: params UUID validados num lugar só (`router.param`, 400
|
|
62
|
+
`invalid_id`, sem cast no banco); PUT/PATCH com corpo vazio → 400; erros do multer → 400/413 com `detail`.
|
|
63
|
+
15. **Allowlist indexada por valor do cliente** (ordenação, coluna, tipo) em `Map`/`Set` ou com
|
|
64
|
+
`Object.hasOwn`: objeto literal aceita `constructor`, `toString`, `__proto__`.
|
|
65
|
+
16. **CORS recusa sem erro**: origem não permitida fica sem o header (nunca 500) e método não seguro dessa
|
|
66
|
+
origem recebe 403. Ver `references/middlewares.md`.
|
|
67
|
+
17. **Conferir e alterar na mesma transação** (contar e apagar, checar limite e inserir), com lock — senão
|
|
68
|
+
duas requisições simultâneas passam pela checagem (TOCTOU). Ver `references/dados.md`.
|
|
69
|
+
|
|
70
|
+
## Esqueleto mínimo recomendado
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
// src/index.ts — carrega config primeiro; erro de env é fatal e legível
|
|
74
|
+
import builder from './core';
|
|
75
|
+
try {
|
|
76
|
+
const { config } = require('./config');
|
|
77
|
+
builder(config);
|
|
78
|
+
} catch (error: any) {
|
|
79
|
+
process.stderr.write(`[FATAL] Environment load failed: ${error.message}\n`);
|
|
80
|
+
process.exit(1);
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
// src/core/index.ts
|
|
86
|
+
export default async (settings: EnvConfig) => {
|
|
87
|
+
await orfeuClient.startup(); // operações já registradas pelos guard() importados nas rotas
|
|
88
|
+
const server = await Server.start(settings);
|
|
89
|
+
for (const sig of ['SIGTERM', 'SIGINT'] as const) {
|
|
90
|
+
process.once(sig, async () => {
|
|
91
|
+
setTimeout(() => process.exit(1), 8_000).unref(); // teto estourado = falha (1)
|
|
92
|
+
await orfeuClient.close().catch(() => undefined); // recarga de permissões + auditoria (SDK antigo: flushAudit())
|
|
93
|
+
server.http.close(() => process.exit(0)); // encerramento completo = 0
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
return server;
|
|
97
|
+
};
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
// src/core/server/index.ts (trecho)
|
|
102
|
+
const app = express();
|
|
103
|
+
app.set('trust proxy', true); // atrás de reverse proxy com TLS
|
|
104
|
+
app.use(requestId);
|
|
105
|
+
app.use(requestLogger);
|
|
106
|
+
app.use(express.json({ limit: '10mb' })); // UM parser JSON, já com o limite
|
|
107
|
+
app.use(express.urlencoded({ extended: true }));
|
|
108
|
+
app.use(securityHeaders());
|
|
109
|
+
app.use(cookieParser());
|
|
110
|
+
app.use(settings.API_PREFIX, corsMiddleware, blockForeignWrites, router); // CORS só na API
|
|
111
|
+
app.use(handleErrors); // por último
|
|
112
|
+
const http = createServer(app);
|
|
113
|
+
http.listen(settings.PORT, () => Logger.info('Server started', { port: settings.PORT }));
|
|
114
|
+
return { app, http }; // http: http.Server (usado no shutdown)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
// src/app/routes/groups/index.ts — wiring declarativo, uma linha por rota
|
|
119
|
+
const router = Router({ mergeParams: true });
|
|
120
|
+
router.get('/', guard('admin:groups:list', Level.PROTECTED), GroupsController.list);
|
|
121
|
+
router.post('/', guard('admin:groups:create', Level.PROTECTED), validate(createGroupSchema), GroupsController.create);
|
|
122
|
+
router.get('/:groupId', guard('admin:groups:get', Level.PROTECTED), GroupsController.get);
|
|
123
|
+
router.delete('/:groupId', guard('admin:groups:remove', Level.PROTECTED), GroupsController.remove);
|
|
124
|
+
export default router;
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Armadilhas mais comuns (lista completa nas referências)
|
|
128
|
+
|
|
129
|
+
- **Dois `bodyParser.json()`** (um sem limite e outro com `limit`) — o primeiro consome o corpo e o
|
|
130
|
+
limite do segundo nunca vale. Registre um só.
|
|
131
|
+
- **CORS global** quebra a própria SPA servida pelo mesmo processo: scripts `type="module"` mandam
|
|
132
|
+
`Origin` mesmo em same-origin. Aplique CORS só no prefixo da API.
|
|
133
|
+
- **Coringa no Express 5**: `'*'` não existe mais; use `'/*splat'` (e trate a raiz do prefixo à parte).
|
|
134
|
+
- **`validate()` que só checa** e não substitui `req.body` pelo resultado do `parse` perde coerções e
|
|
135
|
+
defaults do zod. Atribua o resultado (ver `references/rotas-erros.md`).
|
|
136
|
+
- **`tsconfig-paths` em runtime** compilado precisa apontar o `baseUrl` para `dist`
|
|
137
|
+
(`TS_NODE_BASEURL=./dist`) ou os imports por alias quebram só no container.
|
|
138
|
+
- **`npm start` como CMD** não repassa `SIGTERM`: deploy espera o SIGKILL e a fila de auditoria se perde.
|
|
139
|
+
- **`process.on('uncaughtException', log)`** que só loga mantém o processo vivo em estado inválido.
|
|
140
|
+
Deixe morrer e o orquestrador reiniciar.
|
|
141
|
+
- **`PUT /clients/<meu>/groups/<de outro>`** alterando o grupo de outro client: o middleware de escopo
|
|
142
|
+
conferiu só o `clientId` e o repositório buscou o filho só pelo id.
|
|
143
|
+
- **`?sort=constructor`** passando pela allowlist em objeto literal (`SORT[x]` devolve a função `Object`).
|
|
144
|
+
- **500 em upload grande** (erro do multer sem `status`) e **500 em id malformado** (cast do Postgres).
|
|
145
|
+
- **`cb(new Error('Origem não permitida'))` no CORS** vira 500; e só tirar o header não impede que um
|
|
146
|
+
POST de outra origem execute.
|
|
147
|
+
|
|
148
|
+
## Índice de referências
|
|
149
|
+
|
|
150
|
+
| Arquivo | Conteúdo |
|
|
151
|
+
| --- | --- |
|
|
152
|
+
| `references/estrutura.md` | Árvore de pastas, bootstrap, TypeScript/build (CJS vs ESM), configuração por env, divergências |
|
|
153
|
+
| `references/rotas-erros.md` | Convenção de URL, validação com zod, formato de resposta e erro, status HTTP, paginação offset/cursor |
|
|
154
|
+
| `references/middlewares.md` | Ordem, request-id, logger, CORS dinâmico, security headers, rate limit, escopo de client, integração Orfeu, SPA |
|
|
155
|
+
| `references/dados.md` | Knex (pool, keepAlive), repositório/entity/mapper, transações, upsert, migrations, chamadas HTTP a outros serviços |
|
|
156
|
+
| `references/testes-deploy.md` | Health check, logs, graceful shutdown, smoke test, Dockerfile multi-stage, armadilhas de deploy |
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Dados: banco, transações, migrations e chamadas a outros serviços
|
|
2
|
+
|
|
3
|
+
## Driver / query builder
|
|
4
|
+
|
|
5
|
+
Padrão real: **Knex** sobre **PostgreSQL** (`pg`). Sem ORM — consultas explícitas nos repositórios,
|
|
6
|
+
conversão por mapper. (Suporte a um segundo dialeto existiu e foi removido por não ser usado: não
|
|
7
|
+
mantenha dualidade de banco sem necessidade real.)
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// config/database/db.pg.config.ts
|
|
11
|
+
import type { Knex } from 'knex';
|
|
12
|
+
import { config } from '../index';
|
|
13
|
+
|
|
14
|
+
const pgConfig: Knex.Config = {
|
|
15
|
+
client: 'pg',
|
|
16
|
+
connection: {
|
|
17
|
+
host: config.DB_HOST, port: config.DB_PORT,
|
|
18
|
+
user: config.DB_USER, password: config.DB_PASSWORD, database: config.DB_DATABASE,
|
|
19
|
+
// Sem keepalive, conexão ociosa do pool é derrubada em silêncio por firewall/NAT e a próxima
|
|
20
|
+
// query trava ~20 s até "Connection terminated unexpectedly".
|
|
21
|
+
keepAlive: true,
|
|
22
|
+
keepAliveInitialDelayMillis: 10_000,
|
|
23
|
+
},
|
|
24
|
+
pool: { min: config.DB_POOL_MIN, max: config.DB_POOL_MAX },
|
|
25
|
+
};
|
|
26
|
+
export default pgConfig;
|
|
27
|
+
|
|
28
|
+
// config/database/connection.ts
|
|
29
|
+
import knex from 'knex';
|
|
30
|
+
export const db = knex(pgConfig); // singleton do processo
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- Use **schemas** do Postgres para separar domínios (`<schema>.<tabela>`), referenciados nas queries.
|
|
34
|
+
- Pool `min` baixo em serviços com muitas réplicas; o total (réplicas × `max`) precisa caber no
|
|
35
|
+
`max_connections` do banco.
|
|
36
|
+
|
|
37
|
+
## Repositório, entity e mapper
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
// group.entity.ts
|
|
41
|
+
export class GroupEntity {
|
|
42
|
+
groupId!: string; realmId!: string; name!: string; enabled!: boolean; createdAt!: Date;
|
|
43
|
+
constructor(props: Partial<GroupEntity>) { Object.assign(this, props); }
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// group.mapper.ts
|
|
47
|
+
export class GroupMapper {
|
|
48
|
+
static toEntity(row: any): GroupEntity | null {
|
|
49
|
+
if (!row) return null;
|
|
50
|
+
return new GroupEntity({ groupId: row.group_id, realmId: row.realm_id, name: row.name,
|
|
51
|
+
enabled: row.enabled, createdAt: row.created_at });
|
|
52
|
+
}
|
|
53
|
+
static toEntities(rows: any[]) { return (rows ?? []).map(GroupMapper.toEntity).filter(Boolean) as GroupEntity[]; }
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// group.repository.ts
|
|
57
|
+
const BASE_QUERY = () => db('app.groups as g')
|
|
58
|
+
.join('app.group_types as gt', 'g.type_id', 'gt.type_id')
|
|
59
|
+
.select('g.group_id', 'g.realm_id', 'g.name', 'g.enabled', 'g.created_at', 'gt.name as type_name');
|
|
60
|
+
|
|
61
|
+
export class GroupRepository {
|
|
62
|
+
static async findById(id: string) {
|
|
63
|
+
return GroupMapper.toEntity(await BASE_QUERY().where('g.group_id', id).first());
|
|
64
|
+
}
|
|
65
|
+
static async create(data: { realmId: string; name: string }, trx?: Knex.Transaction) {
|
|
66
|
+
const runner = trx ?? db;
|
|
67
|
+
const [row] = await runner('app.groups').insert({ realm_id: data.realmId, name: data.name }).returning('*');
|
|
68
|
+
return GroupMapper.toEntity(row)!;
|
|
69
|
+
}
|
|
70
|
+
static async update(id: string, data: Partial<{ name: string; enabled: boolean }>, trx?: Knex.Transaction) {
|
|
71
|
+
const patch: Record<string, unknown> = {};
|
|
72
|
+
if (data.name !== undefined) patch.name = data.name; // só o que veio: PATCH semântico
|
|
73
|
+
if (data.enabled !== undefined) patch.enabled = data.enabled;
|
|
74
|
+
const [row] = await (trx ?? db)('app.groups').where({ group_id: id }).update(patch).returning('*');
|
|
75
|
+
return GroupMapper.toEntity(row ?? null);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Regras:
|
|
81
|
+
|
|
82
|
+
- `BASE_QUERY()` como **função** (um builder novo por chamada; builder Knex é mutável).
|
|
83
|
+
- Contagem: `count('x as count')` devolve string no `pg` → `parseInt(String(row.count), 10)`.
|
|
84
|
+
- Todo método de escrita aceita `trx?: Knex.Transaction` e usa `const runner = trx ?? db`.
|
|
85
|
+
- Valores do usuário sempre por binding (`where(col, valor)`, `whereRaw('… ?', [v])`); nunca
|
|
86
|
+
interpolação em `raw`.
|
|
87
|
+
- Comparações de UUID/identificadores vindos de token: normalize o case quando a origem pode variar.
|
|
88
|
+
|
|
89
|
+
## Transações
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
await db.transaction(async trx => {
|
|
93
|
+
const group = await GroupRepository.create({ realmId, name }, trx);
|
|
94
|
+
await GroupRepository.addMember(group.groupId, userId, trx);
|
|
95
|
+
}); // commit no retorno, rollback se lançar
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- Transação no **serviço/controller** que orquestra; repositórios só recebem o `trx`.
|
|
99
|
+
- **Conferir e alterar na mesma transação (TOCTOU).** Regra do tipo "não apagar o último admin", "no
|
|
100
|
+
máximo N tokens", "só remove se não tiver vínculo": contar fora da transação e apagar depois deixa duas
|
|
101
|
+
requisições simultâneas passarem pela checagem. Conte com lock (`forUpdate()`) e apague no mesmo `trx`:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
await db.transaction(async trx => {
|
|
105
|
+
const admins = await trx('memberships').where({ group_id: groupId, role: 'admin' }).forUpdate().select('user_id');
|
|
106
|
+
if (admins.length <= 1 && admins.some(a => a.user_id === userId)) {
|
|
107
|
+
throw new HttpError(409, 'last_admin', 'O grupo precisa de pelo menos um administrador.');
|
|
108
|
+
}
|
|
109
|
+
await trx('memberships').where({ group_id: groupId, user_id: userId }).del();
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Alternativa sem lock explícito: um único `DELETE ... WHERE ... AND (SELECT count(*) ...) > 1` e conferir
|
|
114
|
+
as linhas afetadas.
|
|
115
|
+
- Nada de chamada HTTP externa dentro de transação (segura a conexão e o lock).
|
|
116
|
+
- No Postgres, um erro dentro da transação a envenena até rollback; para "tentar inserir e, se
|
|
117
|
+
violar unicidade, atualizar", use transação aninhada (SAVEPOINT):
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
export async function upsertRow(db: Knex, { table, uniqueBy, insert, merge }: UpsertOptions) {
|
|
121
|
+
return db.transaction(async trx => {
|
|
122
|
+
try {
|
|
123
|
+
return await trx.transaction(async nested => (await nested(table).insert(insert).returning('*'))[0]);
|
|
124
|
+
} catch (err: any) {
|
|
125
|
+
if (err?.code !== '23505') throw err; // unique_violation
|
|
126
|
+
if (!merge) return null; // equivalente a ON CONFLICT DO NOTHING
|
|
127
|
+
const where = Object.fromEntries(uniqueBy.map(c => [c, (insert as any)[c]]));
|
|
128
|
+
return (await trx(table).where(where).update(merge).returning('*'))[0] ?? null;
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Só Postgres: `.onConflict(cols).merge()` / `.ignore()` do Knex é mais simples e atômico — prefira.
|
|
135
|
+
Traduza `23505` em `409` e `23503` (FK) em `400`/`409` no controller, com `error` próprio.
|
|
136
|
+
|
|
137
|
+
## Migrations
|
|
138
|
+
|
|
139
|
+
Padrão adotado (genérico):
|
|
140
|
+
|
|
141
|
+
- O schema vive num **projeto de banco separado** do servidor: scripts `create/` com a forma final
|
|
142
|
+
das tabelas, `insert/` com dados estáticos idempotentes (`INSERT … ON CONFLICT (pk) DO UPDATE`), e
|
|
143
|
+
`migrations/NNN-descricao.sql` com o `ALTER`/`DROP` real para bancos existentes.
|
|
144
|
+
- Toda mudança de schema em produção = editar a forma final **e** escrever a migration numerada,
|
|
145
|
+
com data e aviso no cabeçalho se for destrutiva.
|
|
146
|
+
- Aplicação **fora do boot** do servidor (passo de deploy/CI), nunca `migrate.latest()` no
|
|
147
|
+
`listen` de várias réplicas ao mesmo tempo.
|
|
148
|
+
- Serviço novo pode usar `knex migrate` com `tableName`/`schemaName` próprios, desde que o passo de
|
|
149
|
+
aplicação continue separado da subida.
|
|
150
|
+
|
|
151
|
+
## Cache
|
|
152
|
+
|
|
153
|
+
Redis (`ioredis`) num módulo singleton iniciado antes do servidor; usado para rate limit, sessões
|
|
154
|
+
curtas e pub/sub. Cache em memória com TTL curto (ex.: 30 s) é aceitável para listas pequenas lidas a
|
|
155
|
+
cada requisição (allowlist de CORS), sabendo que cada réplica tem o seu.
|
|
156
|
+
|
|
157
|
+
## Chamadas a outros serviços
|
|
158
|
+
|
|
159
|
+
- Cliente: `axios` (padrão dos projetos) ou `fetch` nativo. Sempre com `timeout`.
|
|
160
|
+
- **Propague credencial e trace.** Com o Orfeu:
|
|
161
|
+
|
|
162
|
+
```ts
|
|
163
|
+
import { orfeuHeaders } from '@orfeu/node';
|
|
164
|
+
const { data } = await axios.get(`${config.PLATFORM_SERVICE_URL}/items`, {
|
|
165
|
+
headers: orfeuHeaders(req), // req do Express, ou o ctx do Apollo nos resolvers
|
|
166
|
+
timeout: 10_000,
|
|
167
|
+
});
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`orfeuHeaders` repassa `x-access-token`/`x-app-token`, `traceparent`, `x-route-id` e `x-client-id`
|
|
171
|
+
(nunca `x-api-token`). Detalhes: orfeu.
|
|
172
|
+
- Rota que **não** passa pelo guard/middleware do Orfeu (ex.: proxy de upload no gateway) repassa os
|
|
173
|
+
mesmos headers como chegaram, sem gerar span novo — senão o evento de auditoria do serviço de
|
|
174
|
+
destino aponta para um pai que não existe.
|
|
175
|
+
- Erro do upstream: preserve o status e a mensagem real (`err.response.status`,
|
|
176
|
+
`err.response.data.detail ?? .message`); upstream inacessível (`isAxiosError && !response`) → 503.
|
|
177
|
+
- URL base vinda de configuração editável em runtime: instancie o client **por requisição** com a URL
|
|
178
|
+
lida na hora, em vez de guardar estado global desatualizado.
|
|
179
|
+
- Interpolação de parâmetro do usuário em linguagem de consulta de outro serviço (PromQL, TraceQL,
|
|
180
|
+
LogQL…) precisa de escape/allowlist — é injeção do mesmo jeito que SQL.
|