@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,224 @@
1
+ # Subscriptions (graphql-ws + Redis)
2
+
3
+ ## Fluxo
4
+
5
+ ```
6
+ serviço de trás grava → publica no Redis (canal <prefixo>:<recurso>[:<escopo>])
7
+ → RedisPubSub do gateway → resolver Subscription → graphql-ws → navegador
8
+ ```
9
+
10
+ O gateway **não gera eventos**: só repassa o que o serviço de trás publica. Isso permite várias réplicas do
11
+ gateway e mantém a regra de negócio num lugar só.
12
+
13
+ ## Servidor WebSocket
14
+
15
+ - `graphql-ws` (protocolo `graphql-transport-ws`) sobre `ws`, no **mesmo** `http.Server` e no **mesmo path**
16
+ do HTTP (`GRAPHQL_PATH`). O proxy reverso precisa encaminhar o upgrade de WebSocket nesse path.
17
+ - O `graphql-ws` executa o schema **sem os plugins do Apollo**: o contexto vem do
18
+ `orfeuWsContext(orfeu, extra)`, que faz no WS o que o `orfeuPlugin` faz no HTTP (credencial, trace,
19
+ routeId/clientId). Sem ele toda subscription não pública é negada.
20
+
21
+ ```ts
22
+ // App disponível também nas subscriptions; do connectionParams, só a allowlist (abaixo)
23
+ const wsContext = orfeuWsContext(orfeu, (ctx) => ({ App: appMods, ...wsContextParams(ctx) }));
24
+ const ws = new WsServer(http.server, schema, wsContext, graphqlPath);
25
+ ```
26
+
27
+ - O `apollo.server.stop()` chama `ws.serverCleanup.dispose()` pelo plugin `drainServer` — fecha os sockets
28
+ no encerramento.
29
+ - Não rejeite a conexão sem token no `onConnect`: subscriptions `OPTIONAL` (páginas públicas) usam o mesmo
30
+ socket. A autorização acontece **por campo**, a cada `subscribe`.
31
+
32
+ ## `connectionParams` (o que o front manda no `connection_init`)
33
+
34
+ ```json
35
+ {
36
+ "x-access-token": "<token>",
37
+ "routeId": "<id da rota da página>",
38
+ "clientId": "<id do app no Argos>",
39
+ "headers": { "x-access-token": "<token>" }
40
+ }
41
+ ```
42
+
43
+ - Credencial lida pelo `orfeuWsContext` na raiz **ou** em `headers` (`x-access-token` → `x-app-token` →
44
+ `x-api-token`). O cliente padrão do front manda nos dois lugares; um servidor novo não precisa ler os dois
45
+ à mão.
46
+ - `routeId`/`clientId` vão para a auditoria de cada evento. Também aceitos como `x-route-id`/`x-client-id`.
47
+ - `traceparent` pode vir em `connectionParams`; sem ele cada inscrição abre trace novo.
48
+ - Os parâmetros são lidos **uma vez por conexão**. Token renovado só entra na próxima conexão — o front
49
+ derruba e recria o socket em 401/4401/4403 e quando a aba volta de segundo plano longo.
50
+
51
+ ### Nunca espalhe o `connectionParams` no contexto
52
+
53
+ `({ connectionParams }) => ({ ...connectionParams })` no `extra` do `orfeuWsContext` (ou no `context` do
54
+ `useServer`) põe no `ctx` **qualquer chave que o cliente escrever** no `connection_init`. Com o
55
+ `@orfeu/node` 1.0.0 isso era uma falha de autorização: um cliente sem token mandava
56
+ `orfeuUser: { groups: [...] }` e passava nas operações `private`/`protected`. A 1.0.1 descarta as chaves
57
+ reservadas do Orfeu (`ORFEU_RESERVED_CONTEXT_KEYS`), mas qualquer outra chave (`App`, `user`, `tenantId`, um
58
+ nome que o seu resolver lê) continua forjável. Exija `@orfeu/node` `^1.0.1` **e** repasse só uma allowlist,
59
+ e só valor string:
60
+
61
+ ```ts
62
+ // src/core/context/ws-context.ts
63
+ // Do connectionParams (graphql-ws) só passam para o contexto os headers de credencial e de rastreio.
64
+ // O orfeuWsContext já lê credencial, traceparent e correlação sozinho; esta lista não deixa o cliente
65
+ // escrever chave nenhuma além dessas no ctx dos resolvers.
66
+ const WS_ALLOWED_PARAMS = [
67
+ 'x-access-token', 'x-app-token', 'x-api-token', // credencial
68
+ 'traceparent', 'x-route-id', 'x-client-id', // rastreio e correlação
69
+ ] as const;
70
+
71
+ export type WsAllowedParam = (typeof WS_ALLOWED_PARAMS)[number];
72
+
73
+ export function wsContextParams(
74
+ { connectionParams }: { connectionParams?: Record<string, unknown> },
75
+ ): Partial<Record<WsAllowedParam, string>> {
76
+ const out: Partial<Record<WsAllowedParam, string>> = {};
77
+ if (!connectionParams || typeof connectionParams !== 'object') return out;
78
+ const headers = connectionParams.headers as Record<string, unknown> | undefined;
79
+ for (const key of WS_ALLOWED_PARAMS) {
80
+ // mesma ordem do Orfeu: raiz do connectionParams primeiro, depois connectionParams.headers
81
+ const value = connectionParams[key] ?? (headers && typeof headers === 'object' ? headers[key] : undefined);
82
+ if (typeof value === 'string') out[key] = value; // objeto, número, array: descartado
83
+ }
84
+ return out;
85
+ }
86
+ ```
87
+
88
+ - Teste unitário da função: chave fora da lista (`orfeuUser`, `user`, `App`) não passa; valor não string
89
+ não passa; `headers` é lido quando a raiz não tem a chave.
90
+ - O verificador da skill (regra `ws-connection-params-espalhado`) acusa o spread de `connectionParams` no
91
+ argumento do `orfeuWsContext`/`useServer` e em função de contexto de WS.
92
+ - Precisa de um usuário que o app validou por fora no contexto do WS? Não grave `orfeuUser`: use
93
+ `trustUser` (skill `orfeu` em `references/node-recipes.md` §4).
94
+
95
+ ## PubSub no Redis (preguiçoso)
96
+
97
+ ```ts
98
+ // src/core/pubsub.ts
99
+ import { RedisPubSub } from 'graphql-redis-subscriptions';
100
+ import { Redis } from 'ioredis';
101
+
102
+ function options() {
103
+ return {
104
+ host: process.env.REDIS_HOST,
105
+ port: Number(process.env.REDIS_PORT ?? 6379),
106
+ password: process.env.REDIS_PASSWORD || undefined,
107
+ db: Number(process.env.REDIS_DB ?? 0), // o MESMO db do serviço que publica
108
+ retryStrategy: (attempt: number) => Math.min(attempt * 200, 5000), // retry infinito, frequência limitada
109
+ };
110
+ }
111
+
112
+ function throttleErrors(client: Redis, label: string) {
113
+ let last = 0;
114
+ client.on('error', (err) => {
115
+ if (Date.now() - last > 30_000) { console.error(`[pubsub:${label}] Redis: ${err.message}`); last = Date.now(); }
116
+ });
117
+ }
118
+
119
+ let instance: RedisPubSub | undefined;
120
+ /** Criado no primeiro uso: em escopo de módulo leria process.env antes do dotenv.config(). */
121
+ export function getPubSub(): RedisPubSub {
122
+ if (!instance) {
123
+ const publisher = new Redis(options());
124
+ const subscriber = new Redis(options());
125
+ throttleErrors(publisher, 'publisher');
126
+ throttleErrors(subscriber, 'subscriber');
127
+ instance = new RedisPubSub({ publisher, subscriber });
128
+ }
129
+ return instance;
130
+ }
131
+
132
+ export const channel = (name: string) => `${process.env.REDIS_CHANNEL_PREFIX ?? 'meuapp:'}${name}`;
133
+ ```
134
+
135
+ - Instância Redis compartilhada → **prefixo de canal** por app, igual no publicador e no gateway.
136
+ - `REDIS_DB` diferente entre publicador e gateway = eventos que nunca chegam, sem erro. Redis Cluster só tem
137
+ o db 0.
138
+ - Para Cluster: `new Redis.Cluster(nodes, { redisOptions: { password } })` escolhido por variável
139
+ (`REDIS_CLUSTER=true`, `REDIS_HOSTS=h1:p,h2:p`).
140
+ - Sem o listener de `error`, Redis fora do ar em dev inunda o console com "Unhandled error event".
141
+
142
+ ## Resolver de Subscription
143
+
144
+ ```ts
145
+ import { Level } from '@orfeu/node';
146
+ import { operation } from '@orfeu/node/apollo';
147
+ import { channel, getPubSub } from '../../../../core/pubsub.js';
148
+
149
+ export const schema = [`#graphql
150
+ type OrderEvent { id: ID!, kind: String! } # kind: changed | removed
151
+ extend type Subscription { orderChanged: OrderEvent! }
152
+ `];
153
+
154
+ export const resolvers = {
155
+ Subscription: {
156
+ orderChanged: operation(Level.PRIVATE, {
157
+ subscribe: () => getPubSub().asyncIterableIterator(channel('orders')),
158
+ resolve: (payload: { id: string; kind: string }) => ({ id: payload.id, kind: payload.kind }),
159
+ }),
160
+ },
161
+ };
162
+ ```
163
+
164
+ - `operation()` no objeto `{ subscribe, resolve }` (a marca vai na função `subscribe`).
165
+ - **`resolve` explícito**: sem ele o resolver padrão procura `payload.orderChanged` e devolve `null`.
166
+ - `asyncIterableIterator` (graphql-subscriptions 3); `asyncIterator` é o nome antigo e ainda existe no
167
+ `graphql-redis-subscriptions` 2.7.
168
+ - Canal parametrizado por argumento: `subscribe: (_, { input }) => getPubSub().asyncIterableIterator(channel(\`map:${input?.environment ?? 'default'}\`))`.
169
+ - Subscription negada é sempre `GraphQLError` (sem envelope).
170
+
171
+ ## Evento magro + refetch (recomendado)
172
+
173
+ O evento leva só `{ id, kind }`; quem recebe busca o item pela query (`getOrder(id)`), que reaplica permissão
174
+ e regras de visibilidade. Assim um rascunho nunca vaza pelo WebSocket. Evento "gordo" (o dado inteiro) só
175
+ quando todos os inscritos podem ver tudo e o volume justifica (painéis de monitoramento).
176
+
177
+ ## Filtro por escopo do usuário
178
+
179
+ Quando cada usuário só pode receber parte dos eventos, pergunte o escopo ao serviço de trás **uma vez** no
180
+ `subscribe` e filtre o iterator:
181
+
182
+ ```ts
183
+ function filtered<T>(it: AsyncIterator<T>, accept: (v: T) => boolean): AsyncIterableIterator<T> {
184
+ return {
185
+ async next() { for (;;) { const r = await it.next(); if (r.done || accept(r.value)) return r; } },
186
+ return: (v?: any) => (it.return ? it.return(v) : Promise.resolve({ done: true, value: v })),
187
+ throw: (e?: any) => (it.throw ? it.throw(e) : Promise.reject(e)),
188
+ [Symbol.asyncIterator]() { return this; },
189
+ };
190
+ }
191
+
192
+ orderChangedMine: operation(Level.PRIVATE, {
193
+ subscribe: async (_: unknown, __: unknown, ctx: GraphQLContext) => {
194
+ const scope = await ctx.App.Orders.watchScope(ctx); // GET autenticado com orfeuHeaders(ctx)
195
+ const teams = new Set(scope.teamIds);
196
+ return filtered(getPubSub().asyncIterableIterator<OrderPayload>(channel('orders:manage')),
197
+ (e) => scope.unrestricted || (!!e.teamId && teams.has(e.teamId)));
198
+ },
199
+ resolve: (p: OrderPayload) => ({ id: p.id, kind: p.kind }),
200
+ }),
201
+ ```
202
+
203
+ - `return`/`throw` repassados ao iterator de baixo — senão a inscrição no Redis não é liberada quando o
204
+ cliente cancela.
205
+ - Mudança de escopo (usuário trocou de time) vale na próxima conexão.
206
+ - Inclua o escopo anterior no payload (`previousTeamId`) para quem perdeu acesso saber que o item saiu.
207
+
208
+ ## Dedup entre réplicas
209
+
210
+ Se mais de uma instância do serviço de trás pode publicar o mesmo evento, mande `event_id` no payload e
211
+ deduplique no gateway com `SET NX`:
212
+
213
+ ```ts
214
+ const seen = await redis.set(`{pub}:seen:${eventId}`, '1', 'NX', 'PX', 30_000);
215
+ if (seen === 'OK') return result; // primeira vez: entrega; senão, descarta e lê o próximo
216
+ ```
217
+
218
+ Evento sem `event_id` passa direto.
219
+
220
+ ## Reconexão
221
+
222
+ O `graphql-ws` do front reassina sozinho, mas eventos publicados durante a queda **não** são reenviados.
223
+ O front ressincroniza (refaz a query) quando o socket reconecta. Do lado do servidor: toda subscription deve
224
+ ter uma query equivalente que devolva o estado atual.
@@ -0,0 +1,181 @@
1
+ # Codegen, testes, build, Docker, ambiente e logs
2
+
3
+ ## Codegen
4
+
5
+ O servidor **não gera tipos** a partir do schema: a fonte da verdade é o SDL em TypeScript. O codegen é do
6
+ **front** (`@graphql-codegen/cli`, preset `near-operation-file`, `typed-document-node`), que lê o schema por
7
+ **introspecção do GraphQL local rodando**:
8
+
9
+ 1. no `.env.local` do servidor: `GRAPHQL_INTROSPECTION=true`;
10
+ 2. `npm run dev` no servidor;
11
+ 3. `npm run codegen` no front (URL do GraphQL local por variável de ambiente do front);
12
+ 4. os `*.generated.ts` vão para o commit; o build não gera nada.
13
+
14
+ Introspecção **nunca** ligada por `NODE_ENV` (nem sempre é `prod` em produção). Alternativa sem subir o
15
+ servidor: um script que monta o schema a partir do código (`makeExecutableSchema` com os mesmos typeDefs) e
16
+ imprime `printSchema(schema)` — útil em CI. Detalhes do lado do front: **angular**.
17
+
18
+ Mudou SDL → rode o codegen do front no mesmo trabalho. Campo renomeado/removido quebra o build do front, o
19
+ que é o objetivo.
20
+
21
+ ## Testes (vitest)
22
+
23
+ ```ts
24
+ // vitest.config.ts
25
+ import { defineConfig } from 'vitest/config';
26
+ export default defineConfig({
27
+ test: {
28
+ globals: true,
29
+ environment: 'node',
30
+ include: ['tests/**/*.test.ts'],
31
+ exclude: ['tests/integration/**', 'node_modules/**'],
32
+ pool: 'forks',
33
+ },
34
+ });
35
+ ```
36
+
37
+ Integração em config separada (`vitest.integration.config.ts`, `testTimeout` maior).
38
+
39
+ ### Unitário: resolver chamado direto
40
+
41
+ ```ts
42
+ import { describe, it, expect, vi } from 'vitest';
43
+ import { resolvers as Q } from '../../src/web/orders/schemas/order/queries.js';
44
+
45
+ const CALLER = { orfeuCredential: { header: 'x-access-token', value: 'tok' } };
46
+
47
+ it('listOrders: repassa o envelope e aplica os padrões de página', async () => {
48
+ const list = vi.fn(async () => ({ status: 200, message: '', data: { items: [], total: 0, offset: 0 } }));
49
+ const r = await (Q.Query.listOrders as any)(null, {}, { App: { Orders: { list } }, ...CALLER });
50
+ expect(r.status).toBe(200);
51
+ expect(list).toHaveBeenCalledWith(undefined, 0, 50, expect.objectContaining(CALLER));
52
+ });
53
+ ```
54
+
55
+ `operation()` devolve o próprio resolver (só marca a função), então dá para chamá-lo sem Orfeu. Teste também
56
+ o `resolve` de subscriptions que remodelam payload e o `failure`/`forward` (`isAxiosError` sem `response` →
57
+ 503; `response.data.message` e `detail` em lista → mensagem).
58
+
59
+ ### Integração: headers repassados ao serviço de trás
60
+
61
+ Monte um `ApolloServer` real com `orfeuPlugin` e um servidor HTTP local no lugar do serviço, que só registra
62
+ os headers; confira `traceparent`, credencial, `x-route-id`/`x-client-id`:
63
+
64
+ ```ts
65
+ const apollo = new ApolloServer({ typeDefs, resolvers, plugins: [orfeuPlugin({} as OrfeuClient)] });
66
+ await apollo.start();
67
+ const res = await apollo.executeOperation(
68
+ { query: '{ ping }', http: { method: 'POST', headers: new HeaderMap(Object.entries(headers)), search: '', body: {} } },
69
+ { contextValue: { App: { Orders: orders } } },
70
+ );
71
+ expect(received[0].traceparent).toBe(`00-${TRACE_ID}-${seenTrace.spanId}-01`);
72
+ ```
73
+
74
+ (O plugin não chama o Argos; a validação é por campo, no `secureResolvers`, que aqui não é usado.)
75
+
76
+ ### O que testar sempre
77
+
78
+ - `assertSchemaSecured` passa com o schema montado (teste que importa o `ExtendedSchema`, monta com um
79
+ `OrfeuClient` falso e chama `secureResolvers` + `makeExecutableSchema` + `assertSchemaSecured`).
80
+ - Funções puras de remodelagem/filtro de payload.
81
+
82
+ Validação focada: rode os testes do que mudou e `npm run typecheck`.
83
+
84
+ ## Build
85
+
86
+ Padrão: **`typecheck` + bundle com esbuild** no mesmo script de build. O esbuild gera um arquivo só em
87
+ milissegundos (build de imagem mais rápido, subida sem resolver centenas de módulos) mas **não** checa tipos —
88
+ por isso o `build` roda o `tsc --noEmit` antes, e um erro de tipo nunca chega à imagem. Código que lê arquivo
89
+ relativo ao `dist/` em runtime (`readFileSync`, `__dirname`) quebra no bundle: confira antes de migrar.
90
+
91
+ ```json
92
+ {
93
+ "type": "module",
94
+ "scripts": {
95
+ "dev": "cross-env NODE_ENV=local tsx watch src/index.ts",
96
+ "start": "cross-env NODE_ENV=local tsx src/index.ts",
97
+ "start:local": "cross-env NODE_ENV=local tsx watch src/index.ts",
98
+ "start:homol": "cross-env NODE_ENV=homol tsx watch src/index.ts",
99
+ "build": "npm run typecheck && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --target=es2022 --tsconfig=tsconfig.json --sourcemap --outfile=dist/index.js",
100
+ "typecheck": "tsc --noEmit",
101
+ "start:prod": "node dist/index.js",
102
+ "test": "vitest run"
103
+ }
104
+ }
105
+ ```
106
+
107
+ `tsconfig`: `target ES2022`, `module NodeNext`, `strict`, `esModuleInterop`, `skipLibCheck`, `outDir dist`,
108
+ `rootDir src`. Imports relativos com `.js` (o esbuild também resolveria alias `src/*`, mas relativo funciona
109
+ igual no `tsx`, no `vitest` e no `tsc`). Dependências com faixa explícita da versão em uso (`^16.14.2`, não
110
+ `^16`); `@types/node` na major do Node da imagem (`node:22` → `^22`).
111
+
112
+ ## Migração Apollo Server 4 → 5
113
+
114
+ - `@apollo/server` `^5` + `@as-integrations/express4` (Express 4) ou `@as-integrations/express5`.
115
+ - `import { expressMiddleware } from '@apollo/server/express4'` → `from '@as-integrations/express4'`.
116
+ - Node ≥ 20. Plugins (`drainHttpServer`) e `executeOperation` não mudam no uso deste padrão.
117
+ - `graphql-ws` 6 muda o import para `graphql-ws/use/ws` e exige Node ≥ 20; o cliente do front fala os dois.
118
+
119
+ ## Docker (multi-stage)
120
+
121
+ ```dockerfile
122
+ FROM node:22-alpine AS build
123
+ WORKDIR /app
124
+ COPY package.json package-lock.json ./
125
+ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
126
+ timeout -k 10 600 npm ci --no-audit --no-fund
127
+ COPY tsconfig.json ./
128
+ COPY src ./src
129
+ RUN timeout -k 10 300 npm run build \
130
+ && npm prune --omit=dev --no-audit --no-fund \
131
+ && find node_modules -type f \( -name '*.d.ts' -o -name '*.d.mts' -o -name '*.d.cts' -o -name '*.map' \
132
+ -o -name '*.md' -o -name '*.markdown' -o -name '*.tsbuildinfo' \) ! -iname 'LICENSE*' -delete \
133
+ && rm -rf node_modules/@types
134
+
135
+ FROM node:22-alpine
136
+ RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack \
137
+ /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack \
138
+ /opt/yarn-* /usr/local/bin/yarn /usr/local/bin/yarnpkg
139
+ WORKDIR /app
140
+ COPY --from=build /app/package.json ./
141
+ COPY --from=build /app/node_modules ./node_modules
142
+ COPY --from=build /app/dist ./dist
143
+ ENV PORT=3000
144
+ EXPOSE 3000
145
+ CMD ["node", "dist/index.js"]
146
+ ```
147
+
148
+ - `CMD` na forma exec com `node` direto (PID 1): `npm start` não repassa `SIGTERM`. O app trata o sinal
149
+ (ver [estrutura-bootstrap.md](estrutura-bootstrap.md)).
150
+ - `timeout` em cada passo que baixa/compila: alguns orquestradores só cancelam o build no passo seguinte.
151
+ - Limpeza do `node_modules` por **tipo de arquivo**, nunca por nome de pasta (pacotes têm código em `docs/`).
152
+ - `.dockerignore`: `.git`, `node_modules`, `dist`, `coverage`, `*.log`, `.env`, `.env.*`, `!.env.example`.
153
+ - A variável de porta do Dockerfile tem de ser a mesma que o código lê.
154
+
155
+ ## Variáveis de ambiente (nomes)
156
+
157
+ | Variável | Uso |
158
+ | --- | --- |
159
+ | `NODE_ENV` | escolhe `src/settings/environment/.env.<NODE_ENV>` em dev (`local`, `dev`, `homol`, `prod`) |
160
+ | `PORT` | porta HTTP/WS |
161
+ | `GRAPHQL_PATH` | path do GraphQL **e** do WS (`/graphql`, ou `/<app>/graphql` atrás de proxy) |
162
+ | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET` | `OrfeuClient` (app registrado no Argos) |
163
+ | `AUTH_TLS_VERIFY` | `false` só se a CA do Argos não está no bundle do Node (prefira `NODE_EXTRA_CA_CERTS`); loga aviso e aparece no `/health` |
164
+ | `PLATFORM_SERVICE_URL` (ou `<SERVICO>_URL`) | `baseURL` dos módulos REST |
165
+ | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB`, `REDIS_CHANNEL_PREFIX` | pub/sub; `REDIS_DB` próprio do app (nunca o mesmo de outro app no mesmo Redis), igual ao do server do app |
166
+ | `REDIS_CLUSTER`, `REDIS_HOSTS` | modo cluster |
167
+ | `GRAPHQL_INTROSPECTION` | `true` só onde se roda o codegen |
168
+
169
+ `.env.*` fora do git (`.gitignore`), com `.env.example` só com nomes. Variáveis que o gateway não usa (banco,
170
+ integrações externas) não ficam no `.env` dele.
171
+
172
+ ## Logs
173
+
174
+ - Uma linha por operação vem do **logger do Orfeu** (JSON no stdout) e a auditoria vai ao Argos — não
175
+ duplique log por resolver.
176
+ - `console.error` só em erro inesperado (`failure` sem `response`) e falhas de infraestrutura (Redis com log
177
+ limitado a 1x/30s).
178
+ - Nunca logue token, `connectionParams` ou corpo de requisição.
179
+ - Medição de desempenho opcional por variável (`GQL_PERF=1`, limite de lentidão em ms): plugin do Apollo
180
+ (`requestDidStart` → `didResolveOperation`/`willSendResponse`) separando parse/validação de execução, e
181
+ middleware Express antes do `compression()` para o tempo total e bytes enviados.
@@ -0,0 +1,160 @@
1
+ #!/usr/bin/env node
2
+ // Verificador da skill `apollo`: armadilhas de gateways Apollo Server.
3
+ // node checar.mjs [caminhos...] [--json] (instalado: ~/.claude/skills/apollo/scripts/checar.mjs)
4
+ // Exceção: `// acropole-ignore-next-line <regra> -- motivo` na linha anterior.
5
+ // (Campo sem `operation()` já impede a subida pelo `assertSchemaSecured`; não precisa de regra aqui.)
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
+ /** O package.json mais próximo depende de @apollo/server? (cache por pasta) */
14
+ const cache = new Map();
15
+ function projetoApollo(arquivo) {
16
+ let dir = path.dirname(arquivo);
17
+ for (;;) {
18
+ if (cache.has(dir)) return cache.get(dir);
19
+ const pj = path.join(dir, 'package.json');
20
+ if (fs.existsSync(pj)) {
21
+ let sim = false;
22
+ try {
23
+ sim = Boolean(JSON.parse(fs.readFileSync(pj, 'utf8')).dependencies?.['@apollo/server']);
24
+ } catch {
25
+ /* package.json inválido */
26
+ }
27
+ cache.set(dir, sim);
28
+ return sim;
29
+ }
30
+ const pai = path.dirname(dir);
31
+ if (pai === dir) return false;
32
+ dir = pai;
33
+ }
34
+ }
35
+ // Código do servidor Apollo: fora de testes, scripts e benchmarks.
36
+ const ehServidor = (a) => ehCodigo(a) && !/(^|\/)(tests?|__tests__|scripts|bench\w*)\//.test(a.relRaiz) && projetoApollo(a.caminho);
37
+
38
+ /** Índice do `)`/`]`/`}` que fecha o `(`/`[`/`{` em `inicio`, ignorando strings (texto já sem comentários). */
39
+ function fecha(t, inicio) {
40
+ const par = { '(': ')', '[': ']', '{': '}' };
41
+ const pilha = [];
42
+ let aspas = '';
43
+ for (let i = inicio; i < t.length; i++) {
44
+ const ch = t[i];
45
+ if (aspas) {
46
+ if (ch === '\\') i++;
47
+ else if (ch === aspas) aspas = '';
48
+ } else if (ch === '"' || ch === "'" || ch === '`') aspas = ch;
49
+ else if (par[ch]) pilha.push(par[ch]);
50
+ else if (ch === ')' || ch === ']' || ch === '}') {
51
+ if (pilha.pop() !== ch || !pilha.length) return i; // fechou (ou desbalanceou): para aqui
52
+ }
53
+ }
54
+ return t.length - 1;
55
+ }
56
+
57
+ // Função, método ou constante com nome de contexto de WS: wsContext, buildWsContext, contextForWs, forConnection...
58
+ const NOME_CONTEXTO_WS =
59
+ /^[ \t]*(?:export[ \t]+)?(?:(?:public|private|protected|static|readonly)[ \t]+)*(?:async[ \t]+)?(?:function[ \t]*\*?[ \t]*|(?:const|let|var)[ \t]+)?(\w*(?:ws\w*context|context\w*ws|forconnection)\w*)[ \t]*[=(:<]/gim;
60
+
61
+ /**
62
+ * Trechos que montam o contexto do WebSocket: os argumentos de `orfeuWsContext(...)`/`useServer(...)` e o corpo
63
+ * de função/método/constante com nome de contexto de WS. Devolve `[inicio, fim]`.
64
+ */
65
+ function trechosDeContextoWs(t) {
66
+ const out = [];
67
+ for (const m of t.matchAll(/\b(?:orfeuWsContext|useServer)\s*\(/g)) {
68
+ const abre = m.index + m[0].length - 1;
69
+ out.push([abre, fecha(t, abre)]);
70
+ }
71
+ for (const m of t.matchAll(NOME_CONTEXTO_WS)) {
72
+ const abre = t.indexOf('(', m.index + m[0].length - 1);
73
+ if (abre < 0) continue;
74
+ const fimParams = fecha(t, abre);
75
+ // Depois dos parâmetros só pode vir tipo de retorno e então `{` (corpo) ou `=>`; senão é chamada/outra
76
+ // coisa e vale só o que está entre os parênteses.
77
+ const resto = t.slice(fimParams + 1);
78
+ const corpo = resto.search(/=>|\{/);
79
+ if (corpo < 0 || !/^\s*(?::[^;]*?)?\s*$/.test(resto.slice(0, corpo))) {
80
+ out.push([abre, fimParams]);
81
+ continue;
82
+ }
83
+ let j = fimParams + 1 + corpo;
84
+ if (t.startsWith('=>', j)) {
85
+ j += 2;
86
+ while (/\s/.test(t[j] ?? '')) j++;
87
+ if (t[j] === '(' || t[j] === '{') out.push([m.index, fecha(t, j)]);
88
+ else {
89
+ const fimLinha = t.indexOf('\n', j);
90
+ out.push([m.index, fimLinha < 0 ? t.length - 1 : fimLinha]);
91
+ }
92
+ } else out.push([m.index, fecha(t, j)]);
93
+ }
94
+ return out;
95
+ }
96
+
97
+ const regras = [
98
+ {
99
+ id: 'apollo-express4-legado',
100
+ resumo: "import de '@apollo/server/express4' (Apollo Server 4, fora de suporte)",
101
+ aceita: ehCodigo,
102
+ checar: (arq) =>
103
+ [...arq.limpo.matchAll(/['"]@apollo\/server\/express4['"]/g)].map((m) => ({
104
+ linha: arq.linhaDe(m.index),
105
+ mensagem: '`@apollo/server/express4` é do Apollo Server 4, fora de suporte',
106
+ correcao: 'migre para `@apollo/server` 5 + `@as-integrations/express5` (ou `express4`) — references/testes-build.md',
107
+ })),
108
+ },
109
+ {
110
+ id: 'env-no-topo',
111
+ resumo: 'process.env lido em constante de topo de módulo (ESM roda antes do dotenv)',
112
+ aceita: (a) => ehServidor(a) && !/\bdotenv\b/.test(a.limpo),
113
+ checar(arq) {
114
+ const out = [];
115
+ for (const m of arq.limpo.matchAll(/^(?:export[ \t]+)?(?:const|let|var)[ \t]+[^\n=]+=([^\n]*)$/gm)) {
116
+ const resto = m[1];
117
+ const env = resto.search(/\bprocess\.env\b/);
118
+ if (env < 0 || /=>|\bfunction\b/.test(resto.slice(0, env))) continue;
119
+ if (/^\s*process\.env\.NODE_ENV\b/.test(resto.slice(env))) continue;
120
+ out.push({
121
+ linha: arq.linhaDe(m.index),
122
+ mensagem: '`process.env` lido no topo do módulo: em ESM os imports rodam antes do `dotenv.config()` e o valor sai vazio (Redis cai em localhost em silêncio)',
123
+ correcao: 'leia dentro do builder ou de forma preguiçosa (função `getX()` chamada depois da configuração)',
124
+ });
125
+ }
126
+ return out;
127
+ },
128
+ },
129
+ {
130
+ id: 'ws-connection-params-espalhado',
131
+ resumo: '...connectionParams no contexto do WebSocket (orfeuWsContext/useServer ou função de contexto de WS)',
132
+ aceita: ehServidor,
133
+ checar(arq) {
134
+ const t = arq.limpo;
135
+ const vistos = new Set();
136
+ const out = [];
137
+ for (const [ini, fim] of trechosDeContextoWs(t)) {
138
+ // `...connectionParams`, `...ctx.connectionParams`, `...(ctx?.connectionParams ?? {})`, `...connectionParams.headers`
139
+ for (const m of t.slice(ini, fim + 1).matchAll(/\.\.\.\s*\(?\s*(?:[\w$]+\s*\??\.\s*)*connectionParams\b/g)) {
140
+ const idx = ini + m.index;
141
+ if (vistos.has(idx)) continue;
142
+ vistos.add(idx);
143
+ out.push({
144
+ linha: arq.linhaDe(idx),
145
+ mensagem: '`connectionParams` espalhado no contexto do WebSocket: o cliente escreve no `connection_init` qualquer chave, que chega ao `ctx` dos resolvers (com `@orfeu/node` 1.0.0, até o `orfeuUser`)',
146
+ correcao: 'repasse só a allowlist `x-access-token`, `x-app-token`, `x-api-token`, `traceparent`, `x-route-id`, `x-client-id`, com valor string (`wsContextParams`, references/subscriptions.md), e exija `@orfeu/node` ^1.0.1',
147
+ });
148
+ }
149
+ }
150
+ return out;
151
+ },
152
+ },
153
+ ];
154
+
155
+ process.exitCode = executar({
156
+ skill: 'apollo',
157
+ descricao: 'Apollo Server 4 legado, process.env lido no topo do módulo e connectionParams espalhado no contexto do WebSocket.',
158
+ regras,
159
+ extensoes: JS,
160
+ });