@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.
Files changed (92) hide show
  1. package/README.md +181 -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 +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,154 @@
1
+ # Logs, health, shutdown, testes e Docker
2
+
3
+ ## Logger
4
+
5
+ Logger mínimo, sem dependência pesada: JSON de uma linha em produção (lido pela stack de logs),
6
+ colorido em dev.
7
+
8
+ ```ts
9
+ type Ctx = Record<string, unknown>;
10
+ const isDev = process.env.NODE_ENV === 'dev' || process.env.NODE_ENV === 'local';
11
+
12
+ function write(level: 'info' | 'warn' | 'error', msg: string, ctx?: Ctx) {
13
+ const entry = { time: new Date().toISOString(), level, msg, ...ctx };
14
+ if (isDev) console.log(`[${entry.time}] ${level.toUpperCase()} | ${msg}${ctx ? ' ' + JSON.stringify(ctx) : ''}`);
15
+ else console.log(JSON.stringify(entry));
16
+ }
17
+ export const Logger = {
18
+ info: (m: string, c?: Ctx) => write('info', m, c),
19
+ warn: (m: string, c?: Ctx) => write('warn', m, c),
20
+ error: (m: string, c?: Ctx) => write('error', m, c),
21
+ };
22
+ ```
23
+
24
+ - Contexto estruturado (`{ requestId, port }`), nunca concatenado na mensagem.
25
+ - O Orfeu já emite uma linha JSON por operação protegida (com `trace_id`) — não duplique esse log no
26
+ controller. Ver orfeu.
27
+ - Proibido logar: tokens, segredos, senhas, códigos de MFA, corpo de requisição de autenticação.
28
+ - Instrumentação de performance opcional por env (ex.: `GQL_PERF=1` ou limiar em ms): mede com
29
+ `performance.now()` e só loga acima do limiar — custo quase zero desligada.
30
+
31
+ ## Health check
32
+
33
+ ```ts
34
+ router.get('/health', async (_req, res) => {
35
+ const [pg, redis] = await Promise.allSettled([db.raw('SELECT 1'), cache.ping()]);
36
+ const postgres = pg.status === 'fulfilled' ? 'ok' : 'error';
37
+ const cacheSt = redis.status === 'fulfilled' ? 'ok' : 'error';
38
+ const status = postgres === 'ok' && cacheSt === 'ok' ? 'ok' : 'degraded';
39
+ const tls = config.AUTH_TLS_VERIFY ? {} : { tls_verify: false }; // TLS do autorizador desligado: visível
40
+ res.status(status === 'ok' ? 200 : 503).json({ status, postgres, redis: cacheSt, ...tls });
41
+ });
42
+ ```
43
+
44
+ - Fica sob o prefixo da API, **sem** guard e antes dos namespaces protegidos.
45
+ - Cheque só o que o processo realmente usa (um serviço sem Redis não pinga Redis).
46
+ - Gateway que só repassa: `{ ok: true }` basta (saúde dos serviços de trás é deles).
47
+ - Não exponha versões, hosts ou mensagens de erro do banco.
48
+
49
+ ## Graceful shutdown
50
+
51
+ ```ts
52
+ for (const sig of ['SIGTERM', 'SIGINT'] as const) {
53
+ process.once(sig, async () => {
54
+ Logger.info('Encerrando', { signal: sig });
55
+ setTimeout(() => process.exit(1), 8_000).unref(); // teto estourado = falha
56
+ try { await orfeuClient.close(); } catch (err: any) { Logger.warn('encerramento do Orfeu falhou', { message: err?.message }); } // SDK antigo: flushAudit()
57
+ httpServer.close(() => process.exit(0)); // encerramento completo = sucesso
58
+ });
59
+ }
60
+ ```
61
+
62
+ - Mesma convenção em todo serviço Node do ecossistema: **0** quando drenou, **1** quando o teto estourou —
63
+ o orquestrador distingue parada limpa de travamento (o 143/130 do shell não diz se a drenagem completou).
64
+
65
+ - `flushAudit()` de **cada** `OrfeuClient` instanciado (`Promise.allSettled`).
66
+ - Com Apollo, `ApolloServerPluginDrainHttpServer` + dispose do servidor WebSocket (apollo).
67
+ - Feche também pool do Knex (`db.destroy()`) e Redis (`quit()`) se o encerramento puder demorar.
68
+ - Timer menor que o `stop timeout` do orquestrador (padrão 10 s).
69
+ - **Não** registre `process.on('uncaughtException', log)` que mantém o processo vivo; se registrar,
70
+ logue e `process.exit(1)`.
71
+
72
+ ## Testes
73
+
74
+ Estado real: os servidores Express não têm suíte automatizada; há **smoke tests** em `scripts/` que
75
+ sobem os mesmos controllers num Express efêmero contra um banco de ambiente local, sem o guard
76
+ (autorização testada à parte):
77
+
78
+ ```ts
79
+ const app = express();
80
+ const r = express.Router();
81
+ r.get('/events', AuditController.listEvents);
82
+ app.use('/audit', r);
83
+ app.use((err: any, _req: any, res: any, _next: any) => res.status(500).json({ error: err.message }));
84
+
85
+ const server = app.listen(0); // porta efêmera
86
+ const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
87
+ const r1 = await fetch(`${base}/audit/events?limit=2`);
88
+ check('lista pagina', r1.status === 200 && (await r1.json()).items.length <= 2);
89
+ // ... ao final: server.close(); await db.destroy(); process.exit(failures ? 1 : 0);
90
+ ```
91
+
92
+ Recomendado para código novo:
93
+
94
+ - `node:test` (ou vitest) + `supertest` contra o `app` exportado **sem** `listen` — por isso separe
95
+ "criar app" de "escutar porta".
96
+ - Repositórios contra Postgres real descartável (container), não mock de Knex.
97
+ - Validators zod testados isoladamente; casos de erro (400/401/403/404/409) por rota.
98
+ - Guard do Orfeu: em teste de unidade de controller, monte o router sem o guard; o comportamento de
99
+ autorização é coberto pelo próprio SDK.
100
+
101
+ ## Docker
102
+
103
+ Multi-stage, `npm ci` com cache, `npm prune --omit=dev`, runtime enxuto, `node` como PID 1:
104
+
105
+ ```dockerfile
106
+ FROM node:22-alpine AS build
107
+ WORKDIR /app
108
+ COPY package.json package-lock.json ./
109
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
110
+ timeout -k 10 600 npm ci --no-audit --no-fund
111
+ COPY tsconfig.json ./
112
+ COPY src ./src
113
+ RUN timeout -k 10 300 npm run build \
114
+ && npm prune --omit=dev --no-audit --no-fund \
115
+ && find node_modules -type f \( -name '*.d.ts' -o -name '*.map' -o -name '*.md' \) ! -iname 'LICENSE*' -delete \
116
+ && rm -rf node_modules/@types
117
+
118
+ FROM node:22-alpine
119
+ RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
120
+ /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
121
+ WORKDIR /app
122
+ COPY --from=build /app/package.json ./
123
+ COPY --from=build /app/node_modules ./node_modules
124
+ COPY --from=build /app/dist ./dist
125
+ ENV NODE_ENV=prod
126
+ EXPOSE 3000
127
+ CMD ["node", "dist/index.js"]
128
+ ```
129
+
130
+ - `timeout` em cada passo que baixa/compila: alguns builders só cancelam no passo seguinte e um
131
+ `npm ci` travado fica rodando no host.
132
+ - Limpeza do `node_modules` **por tipo de arquivo**, nunca por nome de pasta (há código de runtime em
133
+ pastas chamadas `docs`/`test`).
134
+ - SPA na mesma imagem: um estágio `ui-build` que gera o `dist` do Angular e
135
+ `ENV UI_STATIC_PATH=…`/`UI_BASE_PATH=…` no runtime.
136
+ - Usando `tsconfig-paths` em runtime: copie o `tsconfig.json` e defina `TS_NODE_BASEURL=./dist`.
137
+ - Segredos entram por env/secret do orquestrador, nunca em `ENV` do Dockerfile nem copiados na imagem.
138
+
139
+ ## Armadilhas reais (consolidado)
140
+
141
+ | Sintoma | Causa | Correção |
142
+ | --- | --- | --- |
143
+ | Corpo > 100 KB dá 413 apesar de `limit: '10mb'` | dois `bodyParser.json()`, o primeiro sem limite | um parser só, com o limite |
144
+ | SPA servida pelo próprio processo devolve 500 nos bundles | CORS global + `Origin` de scripts ESM | CORS só no prefixo da API |
145
+ | POST do login bloqueado por CORS atrás do balanceador | `Origin` same-origin não está na allowlist | aceitar same-origin via `X-Forwarded-Host`/`Host` |
146
+ | `req.protocol` sempre `http` atrás do proxy | falta `trust proxy` | `app.set('trust proxy', true)` |
147
+ | `app.get('*')` quebra ao subir | Express 5 / path-to-regexp novo | `'/*splat'` + rota da raiz separada |
148
+ | Handler async lança e a requisição fica pendurada | Express 4 não captura promise rejeitada | Express 5, ou `try/catch`/wrapper |
149
+ | `req.params.x` undefined no sub-router | falta `mergeParams` | `Router({ mergeParams: true })` |
150
+ | Deploy espera 10 s e perde auditoria | `CMD npm start` / sem handler de SIGTERM | `CMD ["node", …]` + shutdown |
151
+ | Primeira query após ociosidade trava ~20 s | conexão do pool morta por NAT/firewall | `keepAlive` no driver |
152
+ | Imports por alias quebram só no container | `tsconfig-paths` resolvendo para `src` | `TS_NODE_BASEURL=./dist` ou resolver no build |
153
+ | Middleware de header derruba tudo no cold start | consulta ao banco sem `catch` | `.catch(() => valorRestritivo)` |
154
+ | Validação passa mas controller recebe string em vez de número | `validate()` descarta o resultado do zod | atribuir `result.data` a `req.body` |
@@ -0,0 +1,115 @@
1
+ #!/usr/bin/env node
2
+ // Verificador da skill `express`: armadilhas de servidores Express.
3
+ // node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/express/scripts/checar.mjs)
4
+ // Exceção: `// acropole-ignore-next-line <regra> -- motivo` na linha anterior.
5
+ // (Rota sem guard é do verificador da skill `orfeu`; Dockerfile/CMD é da skill `docker`.)
6
+ import fs from 'node:fs';
7
+ import path from 'node:path';
8
+ import { executar } from './nucleo.mjs';
9
+
10
+ const JS = ['.ts', '.js', '.mjs', '.cjs', '.mts', '.cts'];
11
+ const ehCodigo = (a) => JS.includes(a.ext) && !/\.(spec|test)\.[cm]?[jt]s$/.test(a.nome);
12
+
13
+ /** Versão de `express` declarada no package.json mais próximo do arquivo (ou null). */
14
+ const versoes = new Map();
15
+ function versaoExpress(arquivo) {
16
+ let dir = path.dirname(arquivo);
17
+ for (;;) {
18
+ if (versoes.has(dir)) return versoes.get(dir);
19
+ const pj = path.join(dir, 'package.json');
20
+ if (fs.existsSync(pj)) {
21
+ let v = null;
22
+ try {
23
+ const p = JSON.parse(fs.readFileSync(pj, 'utf8'));
24
+ v = p.dependencies?.express ?? p.devDependencies?.express ?? null;
25
+ } catch {
26
+ /* package.json inválido: sem versão */
27
+ }
28
+ versoes.set(dir, v);
29
+ return v;
30
+ }
31
+ const pai = path.dirname(dir);
32
+ if (pai === dir) return null;
33
+ dir = pai;
34
+ }
35
+ }
36
+
37
+ const regras = [
38
+ {
39
+ id: 'json-parser-duplicado',
40
+ resumo: 'mais de um parser JSON (express.json/bodyParser.json) no mesmo arquivo',
41
+ aceita: ehCodigo,
42
+ checar(arq) {
43
+ const todos = [...arq.limpo.matchAll(/\b(?:express|bodyParser)\s*\.\s*json\s*\(/g)];
44
+ return todos.slice(1).map((m) => ({
45
+ linha: arq.linhaDe(m.index),
46
+ mensagem: `parser JSON registrado de novo (o primeiro está na linha ${arq.linhaDe(todos[0].index)}): ele consome o corpo e o \`limit\` deste nunca vale`,
47
+ correcao: "registre um só: `app.use(express.json({ limit: '10mb' }))`",
48
+ }));
49
+ },
50
+ },
51
+ {
52
+ id: 'cors-global',
53
+ resumo: 'CORS aplicado no app inteiro em vez de só no prefixo da API',
54
+ aceita: ehCodigo,
55
+ checar: (arq) =>
56
+ [...arq.limpo.matchAll(/\bapp\s*\.\s*use\(\s*cors\w*\s*[(),]/g)].map((m) => ({
57
+ linha: arq.linhaDe(m.index),
58
+ mensagem: 'CORS global: quebra a SPA servida pelo mesmo processo (script `type="module"` manda `Origin` em same-origin)',
59
+ correcao: 'aplique só no prefixo: `app.use(settings.API_PREFIX, corsMiddleware, router)`',
60
+ })),
61
+ },
62
+ {
63
+ id: 'coringa-express5',
64
+ resumo: "rota '*' no Express 5 (não existe mais; use '/*splat')",
65
+ aceita: (a) => ehCodigo(a) && /^\D*5/.test(versaoExpress(a.caminho) ?? ''),
66
+ checar: (arq) =>
67
+ [...arq.limpo.matchAll(/\.\s*(?:get|use|all)\(\s*['"`](\/?\*)['"`]/g)].map((m) => ({
68
+ linha: arq.linhaDe(m.index),
69
+ mensagem: `caminho \`'${m[1]}'\`: no Express 5 (path-to-regexp 8) o coringa sem nome lança erro na subida`,
70
+ correcao: "use `'/*splat'` (e trate a raiz do prefixo à parte)",
71
+ })),
72
+ },
73
+ {
74
+ id: 'ordenacao-objeto-literal',
75
+ resumo: 'allowlist de ordenação em objeto literal lida com chave variável (`constructor` passa)',
76
+ aceita: (a) => ehCodigo(a) && versaoExpress(a.caminho) !== null,
77
+ checar(arq) {
78
+ const t = arq.limpo;
79
+ // Objetos literais com nome de ordenação: `const SORT_COLUMNS = {`, `static readonly ORDER_BY: X = {`.
80
+ const nomes = new Set();
81
+ const decl = /(?:\b(?:const|let|var)[ \t]+|^[ \t]*(?:(?:private|public|protected|static|readonly)[ \t]+)+)([A-Za-z_$][\w$]*)[ \t]*(?::[^=\n]+)?=[ \t]*(?:Object\.freeze\(\s*)?\{/gm;
82
+ for (const m of t.matchAll(decl)) if (/sort|order|ordena/i.test(m[1])) nomes.add(m[1]);
83
+ const out = [];
84
+ for (const nome of nomes) {
85
+ const n = nome.replace(/\$/g, '\\$');
86
+ // Já conferido com hasOwn em algum ponto do arquivo: confia.
87
+ if (new RegExp(`Object\\.hasOwn\\(\\s*(?:[\\w$]+\\.)*${n}\\b|\\b${n}\\s*\\.\\s*hasOwnProperty\\(|hasOwnProperty\\.call\\(\\s*(?:[\\w$]+\\.)*${n}\\b`).test(t)) continue;
88
+ const achar = (idx) =>
89
+ out.push({
90
+ linha: arq.linhaDe(idx),
91
+ mensagem: `\`${nome}\` é objeto literal: \`${nome}[x]\`/\`x in ${nome}\` aceitam chaves do protótipo (\`constructor\`, \`toString\`, \`__proto__\`) e furam a allowlist`,
92
+ correcao: 'use `new Map([...])` + `.get(x)` (ou confira `Object.hasOwn(obj, x)` antes de ler) — references/rotas-erros.md',
93
+ });
94
+ // NOME[expr] com expr que não é string literal nem posição de tipo (keyof/typeof/number)
95
+ for (const m of t.matchAll(new RegExp(`(?<![\\w$])${n}\\s*\\[\\s*([^\\]]+)\\]`, 'g'))) {
96
+ const expr = m[1].trim();
97
+ if (/^(['"`])[^'"`]*\1$/.test(expr) || /^(?:keyof|typeof|number\b)/.test(expr)) continue;
98
+ achar(m.index);
99
+ }
100
+ // `x in NOME` (fora de `for (const x in NOME)`)
101
+ for (const m of t.matchAll(new RegExp(`(?<!(?:const|let|var)\\s+)(?<![\\w$.'"\`])[\\w$][\\w$.?]*\\s+in\\s+(?:[\\w$]+\\.)*${n}(?![\\w$])`, 'g'))) {
102
+ achar(m.index);
103
+ }
104
+ }
105
+ return out;
106
+ },
107
+ },
108
+ ];
109
+
110
+ process.exitCode = executar({
111
+ skill: 'express',
112
+ descricao: 'parser JSON duplicado, CORS global, coringa antigo no Express 5 e allowlist de ordenação em objeto literal.',
113
+ regras,
114
+ extensoes: JS,
115
+ });
@@ -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,132 @@
1
+ ---
2
+ name: fastapi
3
+ description: "Serviços Python com FastAPI da plataforma: domínios router/service/repository, settings por ambiente, SQLAlchemy síncrono + Postgres, envelope de resposta, banco por scripts SQL, chamadas a outros serviços e testes pytest. Use ao criar, alterar, revisar ou testar rota, regra, acesso a banco ou integração de um backend FastAPI. Semântica de @operation/Level/Method e orfeu_headers é da skill orfeu; serviço Node é da express; Dockerfile é da docker."
4
+ ---
5
+
6
+ # fastapi
7
+
8
+ Serviços Python do ecossistema Acrópole: uma API FastAPI por projeto, chamada pelo gateway GraphQL
9
+ (ver **apollo**), protegida e auditada pelo SDK Orfeu (ver **orfeu**). Esta skill cobre
10
+ o *esqueleto* do serviço; detalhes do SDK (níveis, métodos, claims, `orfeu_headers`, auditoria) ficam na
11
+ orfeu — não duplique aqui.
12
+
13
+ > Ainda não coberto pelo padrão: Strawberry, Django e Flask (o Orfeu tem adapters para eles, mas não há
14
+ > serviço de referência). Para serviços Node use **express**.
15
+
16
+ > **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/fastapi/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
17
+
18
+ ## Regras essenciais
19
+
20
+ 1. **Python ≥ 3.11** (piso do `orfeu` e da imagem `python:3.11-slim`). FastAPI recente (≥ 0.142) e
21
+ Starlette 1.x: **só `lifespan`** — `on_event`/`add_event_handler` não existem mais.
22
+ 2. **Dependências em `requirements.txt` + `requirements-dev.txt`**: só as **diretas**, cada uma com
23
+ **versão exata** (`fastapi==0.142.2`), `uvicorn[standard]`. É o que o Dockerfile instala. `pyproject.toml`
24
+ só com os atalhos do `poe` (`start:local|dev|homol`, `test`) — nada de Poetry em paralelo.
25
+ 3. **Estrutura por domínio**: `src/app/domains/<domínio>/{router,schemas,service,repository,models}.py`.
26
+ Router fino → service (regra, levanta erros do Orfeu, não conhece HTTP) → repository (SQLAlchemy, sem
27
+ regra). Um domínio usa outro **só pelo service**. Ver [references/estrutura.md](references/estrutura.md).
28
+ 4. **Bootstrap**: `get_application()` em `src/main.py` cria o app com `lifespan` (abre banco/Redis,
29
+ inicia tarefas; fecha no `finally`), instancia `Orfeu(app=..., ...)` **depois** do `FastAPI(...)`
30
+ (ele embrulha o lifespan: sync das operações antes, flush da auditoria depois — não chame startup à
31
+ mão), adiciona CORS, chama `install_envelope(app)` e inclui o router sob `settings.api_prefix`.
32
+ 5. **Toda rota responde no envelope** `{status, message, data}`: `return ok(dado, "Mensagem.", status)` e
33
+ `response_model=Envelope[TipoOut]`. Erros de negócio = `raise NotFound/Conflict/...` do `orfeu`; o
34
+ `install_envelope` converte tudo (inclusive 422 do Pydantic e 500 inesperado). Ver
35
+ [references/rotas-erros.md](references/rotas-erros.md).
36
+ 6. **Rota protegida** = `@router.<verbo>(...)` por cima e `@operation(id="dominio:acao", level=Level.X)`
37
+ logo abaixo. Rota sem `@operation` passa **sem autenticação**. Ids estáveis (`tags:list`,
38
+ `tags:create`...). Semântica de `Level`/`Method` → orfeu.
39
+ 7. **Status coerente nos dois lugares**: em criação use `status_code=201` no decorator **e**
40
+ `ok(..., 201)` — o `ok` só preenche o corpo, não o status HTTP.
41
+ 8. **Banco**: SQLAlchemy 2 síncrono + `psycopg2-binary`, só Postgres. Engine criada no lifespan,
42
+ `SessionLocal` em `app.state`, sessão por requisição via `Depends(get_db)`. Rotas que usam a sessão
43
+ síncrona devem ser `def` (rodam no threadpool), não `async def`. Ver
44
+ [references/banco.md](references/banco.md).
45
+ 9. **Schema do banco fora do ORM**: pasta `database/` irmã do serviço com `manifest.yml` + `scripts/
46
+ {bootstrap,delete,create,insert,migrations}` + `build.py` (gera `output/build.sql`, `--exec` aplica) + `scripts/migrations/NNN-*.sql`
47
+ manuais. Não há Alembic nem `create_all` em produção.
48
+ 10. **Configuração por ambiente**: `pydantic-settings` + `src/.env` (só `APP_ENV`) +
49
+ `src/settings/environment/.env.<APP_ENV>`; variáveis do processo vencem os arquivos. Nunca versione
50
+ valores reais; mantenha um `.env.example` só com nomes.
51
+ 11. **Chamadas a outros serviços**: `httpx.AsyncClient` reaproveitado (singleton), com timeout e
52
+ tradução de falha para `Unavailable`. Em nome do usuário, repasse `orfeu_headers(request)`; como o
53
+ próprio serviço, token de app do Argos. Ver [references/integracoes.md](references/integracoes.md).
54
+ 12. **Testes**: pytest com `pythonpath = src`, app mínimo só com o router testado + `install_envelope` +
55
+ SQLite em memória via `schema_translate_map`; testes que exigem Postgres real marcados `db`. Ver
56
+ [references/testes-deploy.md](references/testes-deploy.md).
57
+
58
+ ## Esqueleto mínimo de rota
59
+
60
+ ```python
61
+ from typing import List
62
+ from uuid import UUID
63
+
64
+ from fastapi import APIRouter, Depends
65
+ from orfeu import Level, Method, ok
66
+ from orfeu.adapters.fastapi import Envelope, operation
67
+ from sqlalchemy.orm import Session
68
+
69
+ from app.domains.tags.schemas import TagCreate, TagOut
70
+ from app.domains.tags.service import TagService
71
+ from app.shared.dependencies import get_db
72
+
73
+ router = APIRouter(prefix="/tags", tags=["Tags"])
74
+
75
+
76
+ @router.get("", response_model=Envelope[List[TagOut]])
77
+ @operation(id="tags:list", level=Level.PROTECTED, method=Method.READ)
78
+ def list_tags(db: Session = Depends(get_db)):
79
+ return ok(TagService(db).list())
80
+
81
+
82
+ @router.post("", status_code=201, response_model=Envelope[TagOut])
83
+ @operation(id="tags:create", level=Level.PROTECTED, method=Method.WRITE)
84
+ def create_tag(body: TagCreate, db: Session = Depends(get_db)):
85
+ return ok(TagService(db).create(body.name), "Tag criada.", 201)
86
+ ```
87
+
88
+ ## Armadilhas mais comuns (lista completa nas referências)
89
+
90
+ - `async def` + sessão SQLAlchemy síncrona bloqueia o event loop inteiro. Use `def`; reserve `async def`
91
+ para rotas que fazem `await` (httpx) e, dentro delas, mande trabalho bloqueante para
92
+ `run_in_threadpool`/`asyncio.to_thread`.
93
+ - `text(sql)` trata **qualquer** `:palavra` como bind param — inclusive em comentários e strings do SQL
94
+ (ex.: `-- POST /realms/:realm/...`). Script sem parâmetros: `text(sql.replace(":", r"\:"))`.
95
+ - Sem `method=` explícito, o Orfeu infere o método do **nome da função** (`get_`/`list_`/`fetch_`/`read_`
96
+ → read; `delete_`/`remove_`/`destroy_` → delete; contém `stream`/`subscribe`/`watch`/`listen` → stream;
97
+ resto → write): renomear a função muda a permissão exigida. Os serviços atuais dependem disso; em
98
+ código novo passe `method=Method.X` explícito (regra da orfeu).
99
+ - Proxy reverso que encaminha o path completo (sem strip): o serviço precisa montar rotas **e**
100
+ `docs_url`/`openapi_url`/`redoc_url` sob `api_prefix` (`/<projeto>/server`).
101
+ - `/docs`, `/openapi.json` e `/redoc` expõem o mapa da API: ligados **só em `APP_ENV=local`** (`API_DOCS`
102
+ força); `fastapi_kwargs` passa `None` nos três fora disso ([references/estrutura.md](references/estrutura.md)).
103
+ - `AUTHORIZER_TLS_VERIFY=false` (TLS do autorizador desligado): `warning` na subida e `tls_verify: false` no
104
+ `/health`. `urllib3.disable_warnings` no processo inteiro esconde isso — use aviso uma vez por host.
105
+ - `/health` (envelope `ok(message="ok")` sob o `api_prefix`) em todo serviço. Padrão do app inteiro (pastas,
106
+ portas, ambientes, scripts): skill `acropole` (`references/arquitetura.md`).
107
+ - Campo de settings não declarado entrando via `extra="allow"` (ex.: porta) funciona por acaso — declare
108
+ todo campo usado.
109
+ - `request.state.user` é o `TokenClaims` do Orfeu (objeto: `.sub`, `.groups`, `.raw`), não `dict`: `.get()` dá
110
+ 500. Nome em `user.raw.get("preferred_username")`; com `x-api-token` o user é `None` (`request.state.api_token`).
111
+ - Tarefa em segundo plano não pode usar a sessão da requisição (já fechada): abra outra a partir de
112
+ `app.state.SessionLocal`.
113
+ - `CMD` do container com `exec uvicorn ...` — sem `exec`, o `sh` vira PID 1, não repassa SIGTERM e todo
114
+ stop espera o timeout.
115
+
116
+ ## Índice de referências
117
+
118
+ | Arquivo | Conteúdo |
119
+ |---|---|
120
+ | [references/estrutura.md](references/estrutura.md) | Árvore do projeto, responsabilidades por camada, `main.py`, settings/env (nomes), dependências |
121
+ | [references/rotas-erros.md](references/rotas-erros.md) | Convenção de rotas e ids, `@operation`, Pydantic (entrada/saída, camelCase), envelope, erros e status |
122
+ | [references/banco.md](references/banco.md) | Engine/sessão, models e schemas do Postgres, transações, SQL cru, `database/` com build.py e migrations, armadilhas |
123
+ | [references/integracoes.md](references/integracoes.md) | Clientes HTTP, `orfeu_headers`, token de app, Redis, tarefas em segundo plano, collectors, logs |
124
+ | [references/testes-deploy.md](references/testes-deploy.md) | pytest (SQLite em memória, Postgres com savepoint, fakes do Orfeu), Dockerfile, uvicorn, `.dockerignore` |
125
+
126
+ ## Skills relacionadas
127
+
128
+ - **orfeu** — `@operation`, `Level`/`Method`, claims em `request.state.user`, `orfeu_headers`,
129
+ auditoria e erros do envelope.
130
+ - **apollo** — o gateway GraphQL que chama este serviço (envelope → resolvers).
131
+ - **express** — equivalente para serviços Node/Express.
132
+ - **angular** / **trismegisto** — front que consome o gateway.