@acropole/skills 1.0.0 → 1.2.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 (36) hide show
  1. package/README.md +4 -2
  2. package/bin/install.js +4 -3
  3. package/package.json +2 -2
  4. package/skills/acropole/SKILL.md +9 -3
  5. package/skills/acropole/references/arquitetura.md +174 -0
  6. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  7. package/skills/acropole/references/fluxos/tela-nova.md +1 -1
  8. package/skills/angular/SKILL.md +6 -3
  9. package/skills/angular/references/armadilhas.md +5 -1
  10. package/skills/angular/references/estrutura.md +33 -14
  11. package/skills/angular/references/testes-build.md +31 -4
  12. package/skills/apollo/SKILL.md +12 -8
  13. package/skills/apollo/references/armadilhas.md +5 -1
  14. package/skills/apollo/references/estrutura-bootstrap.md +47 -36
  15. package/skills/apollo/references/testes-build.md +12 -11
  16. package/skills/docker/references/porques.md +4 -0
  17. package/skills/express/SKILL.md +9 -7
  18. package/skills/express/references/estrutura.md +4 -1
  19. package/skills/express/references/rotas-erros.md +13 -1
  20. package/skills/express/references/testes-deploy.md +9 -5
  21. package/skills/fastapi/SKILL.md +12 -9
  22. package/skills/fastapi/references/banco.md +24 -12
  23. package/skills/fastapi/references/estrutura.md +87 -43
  24. package/skills/orfeu/references/diferencas.md +3 -3
  25. package/skills/orfeu/references/node-api.md +8 -2
  26. package/skills/orfeu/references/node-armadilhas.md +4 -4
  27. package/skills/orfeu/references/node-recipes.md +19 -12
  28. package/skills/orfeu/references/python.md +8 -2
  29. package/skills/orquestracao/SKILL.md +118 -0
  30. package/skills/orquestracao/references/paralelismo.md +48 -0
  31. package/skills/orquestracao/scripts/coord.sh +131 -0
  32. package/skills/orquestracao/templates/permissoes-argos.sql +28 -0
  33. package/skills/orquestracao/templates/plan.md +45 -0
  34. package/skills/orquestracao/templates/spec.md +54 -0
  35. package/skills/orquestracao/templates/tasks.md +21 -0
  36. package/skills/trismegisto/references/angular-exports.md +143 -143
package/README.md CHANGED
@@ -5,7 +5,7 @@ cobrindo a stack da plataforma: apps Angular com o design system Trismegisto, ga
5
5
  e servidores Express em Node, serviços FastAPI em Python, autorização/auditoria com o SDK Orfeu,
6
6
  Dockerfiles e deploy pelo Hefesto.
7
7
 
8
- Cada skill cobre uma parte da stack e elas se complementam: numa tela Angular entram `angular`,
8
+ Cada skill cobre uma parte da stack e elas se complementam (a `orquestracao` encadeia todas numa mudança grande): numa tela Angular entram `angular`,
9
9
  `trismegisto` e `orfeu`; num resolver GraphQL, `apollo`, `express` e `orfeu`; no deploy, `docker` e
10
10
  `hefesto`; ao mexer numa tela, `documentacao` mantém o manual dela em dia. A skill `acropole` é a porta de entrada: descobre a stack e encadeia as outras.
11
11
 
@@ -13,7 +13,7 @@ Cada skill cobre uma parte da stack e elas se complementam: numa tela Angular en
13
13
 
14
14
  | Skill | Assunto | Exemplo de pedido que a dispara |
15
15
  | --- | --- | --- |
16
- | `acropole` | Porta de entrada: menu pelo contexto, fluxos `tela-nova`, `endpoint-novo`, `revisar`, `doctor` | `/acropole`, "por onde começo?", "faz um doctor no projeto" |
16
+ | `acropole` | Porta de entrada e padrão arquitetural dos apps (pastas, ambientes, saúde, segurança, dependências, scripts, testes); fluxos `app-novo`, `tela-nova`, `endpoint-novo`, `revisar`, `doctor` | `/acropole`, "cria a estrutura do app novo", "esse app segue o padrão?" |
17
17
  | `angular` | Estrutura dos apps Angular, bootstrap com o spine, telas por `router_id`, serviços GraphQL, signals, testes, build | "cria a tela de pedidos no app de vendas" |
18
18
  | `trismegisto` | Interface com o design system (`@trismegisto/*`, componentes `hm-*`, tokens `--hm-*`, tema, ícones, a11y) e o shell spine | "troca essa tabela por um data grid", "o botão some no tema escuro" |
19
19
  | `orfeu` | SDK Orfeu: login/sessão no front, operações e níveis no backend, auditoria, `traceparent`, propagação entre serviços | "protege essa rota", "o usuário toma 403", "audita a exclusão" |
@@ -22,6 +22,7 @@ Cada skill cobre uma parte da stack e elas se complementam: numa tela Angular en
22
22
  | `fastapi` | Serviços Python com FastAPI: domínios, settings, SQLAlchemy, envelope, pytest | "adiciona o domínio de faturas no serviço Python" |
23
23
  | `docker` | Dockerfile e `.dockerignore` (Angular estático, Node, Python): multi-stage, CMD exec, não-root, healthcheck | "escreve o Dockerfile desse serviço", "o container demora a parar" |
24
24
  | `hefesto` | Deploy pela plataforma Hefesto: aplicação, ambientes, variáveis, deploy/redeploy, rollback, diagnóstico | "prepara esse app para subir no Hefesto", "o deploy falhou" |
25
+ | `orquestracao` | Mudança grande do pedido à entrega (spec → plano em itens Txx → execução por vários agentes/sessões com reserva atômica via `coord.sh` → provas → Argos → fechamento) e como paralelizar com subagentes | "faz a spec e o plano", "paraleliza entre agentes", "distribui esses itens" |
25
26
  | `documentacao` | Manual das telas Angular: `README.md`/`ESPECIFICACAO.md` ligados no `document` da rota, loader `.md`, revisão da doc a cada mudança da tela (registro de revisão em `.documentacao.json`) | "documenta a tela de pedidos", "a doc dessa tela ainda vale?" |
26
27
 
27
28
  ## Subagentes revisores
@@ -45,6 +46,7 @@ O Claude Code chama o revisor quando a tarefa bate com a descrição dele; você
45
46
  | Comando | O que faz |
46
47
  | --- | --- |
47
48
  | `/acropole` | Lê `package.json`/`pyproject.toml`/`requirements.txt`, identifica a stack e sugere 2–3 fluxos. Não executa nada sozinho |
49
+ | `/acropole app-novo` | Estrutura inicial no padrão: `angular/`, `graphql/`, `server/`, `database/` copiados de um app de referência, sem domínio, com specs fixos, `/health`, ambientes e README; tudo testado |
48
50
  | `/acropole tela-nova` | Argos (`router_id`) → `features.routes` → `.graphql` + codegen → service → componente `hm-*` → operação no backend → testes |
49
51
  | `/acropole endpoint-novo` | Rota/resolver (fastapi, express ou apollo) + operação do Orfeu + propagação de headers + auditoria + teste |
50
52
  | `/acropole revisar [caminho]` | Roda os verificadores sobre o diff/arquivos e chama os revisores. Relata; não corrige sem pedido |
package/bin/install.js CHANGED
@@ -127,10 +127,11 @@ function compareVersions(a, b) {
127
127
  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) < (pb[i] || 0) ? -1 : 1;
128
128
  return 0;
129
129
  }
130
- function describe(installed) {
130
+ function describe(installed, feminino = true) {
131
+ const defasado = feminino ? 'defasada' : 'defasado';
131
132
  if (!installed) return 'versão desconhecida';
132
133
  const c = compareVersions(installed, version);
133
- if (c < 0) return `${installed} — defasada (este pacote é ${version}; atualize com npx ${name}@latest)`;
134
+ if (c < 0) return `${installed} — ${defasado} (este pacote é ${version}; atualize com npx ${name}@latest)`;
134
135
  if (c > 0) return `${installed} — mais nova que este pacote (${version})`;
135
136
  return `${installed} — em dia`;
136
137
  }
@@ -160,7 +161,7 @@ if (has('--status')) {
160
161
  else {
161
162
  const v = mark ? mark.version : '';
162
163
  if (v && compareVersions(v, version) < 0) outdated++;
163
- console.log(` ${a}: ${describe(v)}`);
164
+ console.log(` ${a}: ${describe(v, false)}`);
164
165
  }
165
166
  }
166
167
  const orphans = manifest.agents.filter((a) => !availableAgents.includes(a) && fs.existsSync(agentFile(a)));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@acropole/skills",
3
- "version": "1.0.0",
3
+ "version": "1.2.0",
4
4
  "description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto e documentação das telas. Instale com: npx @acropole/skills",
5
5
  "bin": { "acropole-skills": "bin/install.js" },
6
6
  "files": ["bin", "skills", "agents"],
@@ -11,7 +11,7 @@
11
11
  "scripts": {
12
12
  "bump": "node scripts/bump.mjs",
13
13
  "sync": "node scripts/sync-generated.mjs",
14
- "test": "node --test test/install.test.mjs test/integridade.test.mjs"
14
+ "test": "node --test test/install.test.mjs test/integridade.test.mjs test/coord.test.mjs"
15
15
  },
16
16
  "publishConfig": { "access": "public" }
17
17
  }
@@ -1,19 +1,23 @@
1
1
  ---
2
2
  name: acropole
3
- description: Porta de entrada das skills da Acrópole — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor) do projeto. Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", uma tela ou endpoint de ponta a ponta, uma revisão geral, ou um diagnóstico de versões/configuração do projeto.
3
+ description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, e diagnóstico (doctor). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, ou um diagnóstico de versões/configuração do projeto.
4
4
  user-invocable: true
5
- argument-hint: "[tela-nova | endpoint-novo | revisar | doctor] [alvo]"
5
+ argument-hint: "[app-novo | tela-nova | endpoint-novo | revisar | doctor] [alvo]"
6
6
  ---
7
7
 
8
8
  # acropole — fluxos entre as skills
9
9
 
10
10
  As skills da Acrópole cobrem uma parte da stack cada uma. Esta skill não repete regra de nenhuma
11
- delas: diz **qual** convocar, **em que ordem**, e onde estão os verificadores e os revisores.
11
+ delas: diz **qual** convocar, **em que ordem**, e onde estão os verificadores e os revisores — e guarda o
12
+ **padrão arquitetural** que vale para o app inteiro: [references/arquitetura.md](references/arquitetura.md)
13
+ (pastas, fluxo entre camadas, caminhos/portas, ambientes, subida/saúde/encerramento, segurança, desempenho,
14
+ dependências, scripts, testes mínimos, pendências e checklist). Divergência entre apps se resolve por ele.
12
15
 
13
16
  ## Comandos
14
17
 
15
18
  | Comando | O que faz | Playbook |
16
19
  | --- | --- | --- |
20
+ | `/acropole app-novo [nome]` | Estrutura inicial de um app no padrão (angular, graphql, server, database), sem domínio, tudo subindo e testado | [references/fluxos/app-novo.md](references/fluxos/app-novo.md) |
17
21
  | `/acropole tela-nova [nome]` | Tela Angular de ponta a ponta: Argos → rota → GraphQL → service → componente `hm-*` → operação no backend → testes | [references/fluxos/tela-nova.md](references/fluxos/tela-nova.md) |
18
22
  | `/acropole endpoint-novo [recurso]` | Endpoint/resolver no backend com operação do Orfeu, propagação de headers, auditoria e teste | [references/fluxos/endpoint-novo.md](references/fluxos/endpoint-novo.md) |
19
23
  | `/acropole revisar [caminho]` | Roda os verificadores das skills sobre o diff/arquivos e chama os subagentes revisores; só relata | [references/fluxos/revisar.md](references/fluxos/revisar.md) |
@@ -43,6 +47,8 @@ acima e pergunte.
43
47
 
44
48
  | No pedido aparece… | Skills, nesta ordem |
45
49
  | --- | --- |
50
+ | mudança grande (várias camadas/apps), spec, plano, "paraleliza", itens Txx para vários agentes | orquestracao (+ as skills de cada camada) |
51
+ | app novo, estrutura do projeto, "segue o padrão?", pastas/portas/ambientes, divergência entre apps | `references/arquitetura.md` (+ o fluxo `app-novo` para criar) |
46
52
  | tela, página, listagem, formulário, modal, menu, rota do app | angular → trismegisto → orfeu → documentacao |
47
53
  | manual/README da tela, documentação desatualizada, `ESPECIFICACAO.md` | documentacao |
48
54
  | botão, cor, tema, ícone, densidade, `hm-*`, `--hm-*`, acessibilidade de tela | trismegisto (+ angular se mexer em estrutura) |
@@ -0,0 +1,174 @@
1
+ # Padrão arquitetural dos apps
2
+
3
+ O que todo app da plataforma tem, igual entre eles. As skills de cada stack (**angular**, **apollo**,
4
+ **express**, **fastapi**, **docker**, **hefesto**) detalham o código; aqui fica o desenho do app inteiro e as
5
+ decisões que valem para todas as camadas. Divergiu de um app para outro? Este arquivo é o desempate.
6
+
7
+ ## 1. Um repositório por app, sempre as mesmas pastas
8
+
9
+ ```
10
+ <app>/
11
+ ├── angular/ front: Angular 22 + @trismegisto/* + @orfeu/angular
12
+ ├── graphql/ gateway: Apollo Server sobre Express + @orfeu/node — só repassa para o server
13
+ ├── server/ API e regra de negócio: FastAPI + orfeu[fastapi] + SQLAlchemy
14
+ ├── database/ schema, seed e migrations do Postgres (estrutura idêntica entre os apps)
15
+ ├── compose/ (opcional) docker-compose da stack num host
16
+ └── README.md componentes, portas, como rodar, padrões seguidos e pendências
17
+ ```
18
+
19
+ - Nomes de pasta fixos (`server/`, nunca `fastapi/` ou `api/`): ferramentas, deploy e as próprias skills
20
+ contam com eles. App só com parte da stack omite a pasta, não renomeia.
21
+ - Cada pasta tem o próprio `.gitignore` (da stack dela), `Dockerfile` e `.dockerignore`. A raiz só ignora
22
+ estado de ferramenta e de editor.
23
+ - Um serviço que é de fato outro produto (agente de build, agente de deploy) vive em repositório próprio.
24
+
25
+ ## 2. Fluxo entre as camadas
26
+
27
+ ```
28
+ navegador ──> angular (estático) ──GraphQL HTTP/WS──> graphql ──REST + orfeuHeaders──> server ──> Postgres
29
+ ▲ │
30
+ └──── Redis pub/sub (canais <app>:*) ◄┘
31
+ ```
32
+
33
+ - O **front** só fala com o gateway (e com a API administrativa do Argos, para o auto-serviço do shell).
34
+ - O **gateway** não tem regra nem banco: cada operação é `operation(Level.X, …)` do Orfeu e repassa ao server
35
+ com `orfeuHeaders(ctx)` (credencial, `traceparent`, `x-route-id`, `x-client-id`). Respostas no envelope
36
+ `{ status, message, data }`.
37
+ - O **server** tem a regra, o banco e as integrações; publica eventos no Redis, que o gateway entrega às
38
+ subscriptions. Rota protegida = `@operation`.
39
+ - **Argos** autentica todas as camadas: um *client* para o front e um *app* para cada backend (gateway e
40
+ server), no mesmo realm. Os IDs (não segredos) ficam nos environments do front e nos `.env.example`.
41
+
42
+ ## 3. Caminhos, proxy e portas
43
+
44
+ | Camada | Caminho público | Prefixo no código |
45
+ | --- | --- | --- |
46
+ | angular | `/<app>/` | `baseHref` das configurações de build |
47
+ | graphql | `/<app>/graphql` (HTTP **e** WebSocket) | `GRAPHQL_PATH` |
48
+ | server | `/<app>/server` | `api_prefix` (rotas, `/health` e documentação) |
49
+
50
+ - O proxy encaminha o caminho **completo** (sem strip): cada serviço responde sob o próprio prefixo.
51
+ - Atrás do proxy, o front deriva callback, logoff, authority e URLs ainda `CHANGE_ME` da própria origem
52
+ (`applyRuntimeEnvironment`); URL explícita no environment sempre ganha.
53
+ - Cada app tem **uma porta fixa e única por camada** no desenvolvimento local, registrada no README da raiz,
54
+ para vários apps rodarem juntos sem colisão. A porta do container é a mesma variável (`PORT`) que o código lê.
55
+
56
+ ## 3.1 Redis compartilhado: um índice por app
57
+
58
+ O Redis de um ambiente costuma ser **o mesmo para vários apps**. Para um app não ler, sobrescrever nem apagar as
59
+ chaves de outro (cache, dedup de eventos, `FLUSHDB` de teste):
60
+
61
+ - cada app tem o **próprio `REDIS_DB`** (índice 0–15) em cada ambiente — **dois apps nunca usam o mesmo índice**
62
+ no mesmo Redis; gateway e server do **mesmo** app usam o mesmo índice (é por ele que conversam);
63
+ - canais de pub/sub e chaves sempre com o prefixo do app (`<app>:…`) — pub/sub ignora o índice (`PUBLISH` vale
64
+ para o servidor inteiro), então o prefixo é o que isola as subscriptions;
65
+ - o índice de cada app por ambiente fica registrado no README da raiz do app; ao criar um app, escolha um índice
66
+ livre conferindo os outros apps do mesmo ambiente (`.env.<ambiente>`), não "o próximo número".
67
+
68
+ ## 4. Ambientes
69
+
70
+ Só **`local`**, **`dev`**, **`homol`** e **`prod`** — em toda camada, com o mesmo nome.
71
+
72
+ | Camada | Escolha do ambiente | Arquivos |
73
+ | --- | --- | --- |
74
+ | angular | `--configuration <ambiente>` (build/serve) | `src/core/environments/environment.<ambiente>.ts` (versionados, sem segredo); `environment.ts` = `local` |
75
+ | graphql | `NODE_ENV` (`cross-env` nos scripts) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
76
+ | server | `APP_ENV` (comando, `poe start:<ambiente>` ou `src/.env`) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
77
+ | database | — | `env/.env` (não versionado) + `env/.env.example` |
78
+
79
+ - Em container nenhum arquivo `.env` existe (o `.dockerignore` tira): as variáveis vêm do deploy. Arquivo
80
+ ausente não pode quebrar a subida.
81
+ - Variável do processo vence arquivo (`override=False`, `dotenv` sem override).
82
+ - `NODE_ENV`/`APP_ENV` **não são trava de segurança**: são digitados no deploy e o Dockerfile do Node fixa
83
+ `NODE_ENV=dev`. Decisão de segurança "só em produção" precisa de sinal injetado pela plataforma.
84
+
85
+ ## 5. Subida, saúde e encerramento
86
+
87
+ | | graphql | server | front |
88
+ | --- | --- | --- | --- |
89
+ | Argos/Orfeu fora na subida | **sobe negando** tudo; nova tentativa 5 s → 10 s → 20 s → 30 s; `OrfeuConfigError` derruba (saída 1) | o adapter faz o sync no lifespan; falha derruba a subida | — |
90
+ | `/health` | `503 {status:'starting', orfeu:'unavailable'}` até o Orfeu conectar; depois `200 {ok:true}` | `<api_prefix>/health` → envelope `ok(message="ok")` | — |
91
+ | TLS do Argos desligado | aviso na subida + `tls_verify: false` no `/health` | idem (`data: {tls_verify: false}`) | — |
92
+ | SIGTERM/SIGINT | `close()` (ou `flushAudit()` no SDK antigo) + `apollo.server.stop()`; sai **0**; teto de 8 s sai **1** | uvicorn como PID 1 (`exec`), lifespan fecha banco/Redis | — |
93
+
94
+ - Nunca um "modo degradado" que libera sem autorização. Nunca `/health` 200 num serviço que nega tudo.
95
+ - O 503 da subida é informação para a monitoração: healthcheck que reinicia container precisa tolerá-lo
96
+ (`--start-period`/`--retries`), senão Argos fora vira loop de restart.
97
+ - Express (APIs do próprio IdP e afins): `/health` checa as dependências reais (`SELECT 1`, `PING`) e mesma
98
+ convenção de saída 0/1.
99
+
100
+ ## 6. Segurança
101
+
102
+ - **Documentação de API** (`/docs`, `/openapi.json`, `/redoc`, Swagger) **só em `local`** por padrão, em todo
103
+ backend; `API_DOCS=true/false` força. O mapa da API não fica aberto nos ambientes publicados.
104
+ - **TLS** do autorizador: verificação ligada; desligar é opt-out explícito (`AUTH_TLS_VERIFY` /
105
+ `AUTHORIZER_TLS_VERIFY`), escopado ao client do Orfeu, com aviso e visível no `/health`. Prefira apontar a CA
106
+ (`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`). Nada de `NODE_TLS_REJECT_UNAUTHORIZED=0` nem
107
+ `urllib3.disable_warnings` no processo inteiro (destino com CA interna: aviso **uma vez por host**).
108
+ - **Segredo** nunca no front (environment vai para o bundle), nunca com valor padrão, nunca na imagem
109
+ (`.npmrc`, `.env`). `.env.example` só com nomes e IDs públicos.
110
+ - **Front sem recurso de terceiros** em tempo de execução (CDN de imagem, fonte ou script): expõe o IP do
111
+ usuário e faz requisição a cada tela — principalmente na tela de login.
112
+ - Credencial do usuário nunca em `localStorage`/`sessionStorage`.
113
+
114
+ ## 7. Desempenho
115
+
116
+ - **Gateway**: `compression()` antes do Apollo; build = `tsc --noEmit` + **esbuild** em bundle único (rápido de
117
+ buildar e de subir). Clientes (Redis, axios) criados uma vez, dentro do builder.
118
+ - **Server**: `uvicorn[standard]` (uvloop + httptools); rotas com sessão síncrona em `def` (threadpool);
119
+ clientes HTTP reaproveitados.
120
+ - **Front**: telas lazy (`load: () => import(…)`), `provideAnimationsAsync()`, `OnPush` + signals, sem
121
+ biblioteca pesada no bundle inicial (`import()` sob demanda).
122
+
123
+ ## 8. Dependências
124
+
125
+ | Camada | Regra |
126
+ | --- | --- |
127
+ | angular | Angular e TypeScript na mesma major em todos os apps; ferramentas (`angular-eslint`, `eslint`, `typescript-eslint`, `axe-core`, `puppeteer`) com versão exata; pacotes do npm público, sem `.npmrc` com credencial |
128
+ | graphql / express | faixa explícita da versão em uso (`^16.14.2`, nunca `^16`); `cross-env` e `@types/node` na mesma major em todos (o `@types/node` na major do Node da imagem) |
129
+ | server | `requirements.txt` só com dependências **diretas**, versão exata; `requirements-dev.txt` com pytest e poethepoet; `pyproject.toml` só com tarefas do poe; mesmas versões das libs comuns entre os apps |
130
+ | database | `requirements*.txt` idênticos entre os apps |
131
+
132
+ Pacote sem uso sai (inclusive `@types/*` de lib que já traz tipos). Lockfile sempre em sincronia: o `npm ci`
133
+ do Dockerfile falha com `package.json` e lock divergentes.
134
+
135
+ ## 9. Scripts
136
+
137
+ | Camada | Scripts (mesmo conjunto em todo app) |
138
+ | --- | --- |
139
+ | angular | `start`, `dev`, `start:local`, `start:homol`, `build` (prod), `build:dev`, `build:homol`, `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
140
+ | graphql | `dev`, `start`, `start:local`, `start:homol`, `build` (typecheck + esbuild), `typecheck`, `start:prod`, `test` |
141
+ | server | `poe start:local`, `poe start:dev`, `poe start:homol`, `poe test` |
142
+ | database | `python build.py [--exec\|--reset\|--seed\|--bootstrap]`, `python -m pytest` |
143
+
144
+ ## 10. Testes mínimos
145
+
146
+ | Camada | Obrigatório |
147
+ | --- | --- |
148
+ | angular | `app.config.spec`, `core.providers.spec`, `environments.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
149
+ | graphql | `builder.test` (subida, path, CORS, introspecção desligada, lote, 400 de sintaxe, 401/403 antes do resolver, encerramento), `builder-falha.test` (Orfeu fora → 503 → 200; campo sem `operation()` não sobe), `builder-padroes.test`, `shutdown.test` (teto → 1), `resolvers.test` (tabela campo → chamada REST) |
150
+ | server | `test_health`, `test_api_docs` (só `local`; `API_DOCS` força), testes de domínio com SQLite em memória |
151
+ | database | suíte compartilhada (estrutura, build, migrations, PGlite) + `test_app.py` |
152
+
153
+ Validação antes de entregar: suíte e build de cada camada alterada (`ng test` + `ng build`; `vitest` +
154
+ `typecheck` + `build`; `pytest` em ambiente recriado do zero quando dependência mudou).
155
+
156
+ ## 11. Pendências conhecidas do padrão
157
+
158
+ - **Permissões só lidas na subida** (SDK antigo): com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 os serviços revalidam sozinhos os grupos liberados a cada
159
+ ~60 s (`If-None-Match`/ETag no Argos, 304 quando nada mudou) e o encerramento usa `client.close()`. Ao atualizar o
160
+ SDK num app, troque `flushAudit()` por `close()` no SIGTERM e confira se o `/health` deve mostrar `permissionsStale`.
161
+ - **Recusar TLS desligado em produção** depende de a plataforma injetar o ambiente no container (sinal
162
+ confiável); até lá, aviso + `/health`.
163
+
164
+ ## 12. Checklist de conformidade (revisão de um app)
165
+
166
+ - [ ] Pastas `angular/`, `graphql/`, `server/`, `database/` e README da raiz com portas e pendências
167
+ - [ ] Só `local`/`dev`/`homol`/`prod`; `.env.example` em cada backend; nenhum `.env` versionado
168
+ - [ ] `REDIS_DB` próprio por ambiente (nenhum outro app no mesmo índice) e prefixo `<app>:` nas chaves/canais
169
+ - [ ] Gateway sobe negando com `/health` 503 → 200; server com `/health` sob o prefixo
170
+ - [ ] Encerramento 0/1 com teto de 8 s; `CMD` em forma exec
171
+ - [ ] Documentação de API só em `local`; TLS desligado avisado; sem `disable_warnings` global
172
+ - [ ] `compression()` no gateway; build typecheck + esbuild; `uvicorn[standard]`
173
+ - [ ] Dependências no formato da seção 8; scripts da seção 9; testes da seção 10
174
+ - [ ] Front: `tsconfig` com `paths` (sem `baseUrl`), environment tipado com `AuthConfig`, nenhum CDN externo
@@ -0,0 +1,34 @@
1
+ # Fluxo: app novo
2
+
3
+ Estrutura inicial de um app no padrão da plataforma — front, gateway, server e banco, sem domínio nenhum,
4
+ tudo subindo e testado. O desenho completo (pastas, ambientes, saúde, segurança, scripts, testes) está em
5
+ [../arquitetura.md](../arquitetura.md); este fluxo diz a ordem e de onde vem cada peça.
6
+
7
+ Antes de começar, confirme com o usuário: nome do app (vira caminho `/<app>/`, schema do banco e prefixo dos
8
+ canais Redis), quais camadas ele terá, e se o app já está cadastrado no Argos (client do front + um app para o
9
+ gateway e outro para o server, no mesmo realm dos outros). **Não invente ID**: peça o client e os apps, ou
10
+ leia o cadastro que o usuário indicar. Pergunte também as portas locais livres (uma por camada) e escolha um
11
+ `REDIS_DB` livre em cada ambiente (nenhum outro app no mesmo índice — `arquitetura.md` §3.1).
12
+
13
+ **Base**: copie de um app que já segue o padrão (o mais completo disponível), **sem** `node_modules`,
14
+ `dist`, `.angular`, `.venv`, `__pycache__`, `.env`/`.env.*`, `output/`, pasta de domínio, migrations e seeds do
15
+ app de origem — e depois remova o que for específico dele. Copiar do zero de memória gera divergência.
16
+
17
+ | # | Passo | Skill | Onde |
18
+ | --- | --- | --- | --- |
19
+ | 1 | **Esqueleto** `angular/`, `graphql/`, `server/`, `database/` + `.gitignore` da raiz, copiados da base sem artefatos nem domínio | acropole | `arquitetura.md` §1 |
20
+ | 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), environments dos quatro ambientes com o client/realm do app e o cliente GraphQL `<app>` (`CHANGE_ME` onde a URL deve ser derivada atrás do proxy), `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
21
+ | 3 | **Specs fixos do front** (`app.config`, `core.providers`, `environments`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
22
+ | 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
23
+ | 5 | **Testes do gateway**: manter os genéricos (subida, autorização com `_noop`, falha de subida, padrões, encerramento), tabela de rotas REST vazia, tirar os de domínio | apollo | apollo `references/testes-build.md` |
24
+ | 6 | **Server**: settings só com Argos, Postgres, Redis e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
25
+ | 7 | **Testes do server**: `conftest` com a base do app, `test_health`, `test_api_docs` | fastapi | fastapi `references/testes-deploy.md` |
26
+ | 8 | **Banco**: `bootstrap` (role e database `<app>`), `delete/reset.sql`, `create/<app>/01-core.sql` só com `CREATE SCHEMA`, `manifest.yml` com `insert: []`, `env/.env.example`, `test_app.py`, seções "Schemas"/"Particularidades" do `CLAUDE.md` da pasta; `python build.py` para gerar `output/build.sql` | fastapi | fastapi `references/banco.md` |
27
+ | 9 | **Dockerfiles** das três camadas com as portas novas e o caminho do build do front | docker | docker `references/modelos.md` |
28
+ | 10 | **README da raiz**: componentes e portas, cadastro no Argos (IDs públicos), como rodar, padrões, pendências | acropole | `arquitetura.md` |
29
+ | 11 | **Validação**: instalar e rodar tudo — `ng test` + `ng build` + `lint:a11y`; `vitest` + `typecheck` + `build`; ambiente Python novo + `pytest`; `pytest` do banco (PGlite); importar o `main.py` com variáveis fictícias. Procure no app novo o nome da base (`grep -ri`) e o que sobrar de domínio | acropole | `arquitetura.md` §10 |
30
+
31
+ Fora do código (diga ao usuário no fim): **redirect URIs** do client no Argos (`<origem>/<app>/callback` e
32
+ `/logoff`, inclusive `localhost` para o desenvolvimento), **acesso** dos grupos ao client e cada roteador privado
33
+ **liberado** para esses acessos (sem essa liberação o login funciona e o menu vem vazio), permissões das operações para os grupos, URLs reais de
34
+ `homol`/`prod` quando houver deploy, e o `PRODUCT.md` do front quando o escopo do produto estiver definido.
@@ -9,7 +9,7 @@ schema.
9
9
 
10
10
  | # | Passo | Skill | Onde |
11
11
  | --- | --- | --- | --- |
12
- | 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código | angular | `SKILL.md` "Receita: tela nova", `references/features.md` |
12
+ | 1 | **Roteador no Argos**: cadastrar o roteador do client (com descrição), **liberá-lo para os grupos** que devem ver a tela (roteador privado sem liberação não aparece no menu) e anotar o `router_id`. É feito no painel do Argos pelo usuário — peça o id, não crie por código | angular | `SKILL.md` "Receita: tela nova", `references/features.md` |
13
13
  | 2 | **Operação no backend** que a tela vai chamar (Query/Mutation ou rota REST), com operação do Orfeu, `Method` explícito, `Level` e auditoria. Se ainda não existe, rode antes o fluxo [endpoint-novo](endpoint-novo.md) | apollo / fastapi / express + orfeu | ver endpoint-novo |
14
14
  | 3 | **Documento GraphQL** em `src/app/services/<dominio>/<dominio>.graphql` + `npm run codegen` com o GraphQL local de pé (gera `<dominio>.generated.ts`, commitado) | angular | `references/dados.md` |
15
15
  | 4 | **Service** `providedIn: 'root'` com `injectGraphqlClient` + `unwrap`; erro vira estado da tela | angular | `SKILL.md` "Dados", `references/dados.md` |
@@ -32,7 +32,7 @@ meu-app/
32
32
  ├── codegen.ts # graphql-codegen (tipos + TypedDocumentNode), roda à mão
33
33
  ├── Dockerfile # estágios dev / build / site (só o /dist estático)
34
34
  ├── eslint.a11y.config.js # regras de acessibilidade de template (angular-eslint)
35
- ├── tsconfig.json # strict, baseUrl "./", resolveJsonModule
35
+ ├── tsconfig.json # strict, paths src/* e package.json (sem baseUrl), resolveJsonModule
36
36
  └── src/
37
37
  ├── main.ts # applyRuntimeEnvironment(environment) + bootstrapApplication
38
38
  ├── index.html # lang="pt-BR", favicon, tela #app-loading
@@ -96,8 +96,11 @@ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md
96
96
  `development` (só para `ng serve`).
97
97
  - `angular.json` > `styles`: `src/styles.scss`, `@trismegisto/tokens/tokens.css`,
98
98
  `@trismegisto/core/core.css`.
99
- - Testes: Karma + Jasmine (`@angular/build:karma`, `ng test`). Acessibilidade: `lint:a11y` e
100
- `axe:check`. Ver [references/testes-build.md](references/testes-build.md).
99
+ - Testes: Karma + Jasmine (`@angular/build:karma`, `ng test`), com specs fixos do core (`app.config`,
100
+ `core.providers`, `environments`, `features.routes`). Acessibilidade: `lint:a11y` e `axe:check`, com os
101
+ mesmos arquivos em todo app. Ver [references/testes-build.md](references/testes-build.md).
102
+ - Padrão do app inteiro (pastas do repo, portas, ambientes, scripts, saúde dos backends):
103
+ skill `acropole` (`references/arquitetura.md`).
101
104
 
102
105
  ## Receita: tela nova "pedidos"
103
106
 
@@ -82,7 +82,11 @@
82
82
  | Animações | `provideAnimationsAsync()` x `importProvidersFrom(BrowserAnimationsModule)` | `provideAnimationsAsync()` |
83
83
  | Change detection global | `provideZoneChangeDetection` uma vez x repetido no `main.ts` | uma vez, em `app.config.ts`, com `eventCoalescing` |
84
84
  | Auth | `provideAuth(environment.authorizationServer)` x `AUTH_CONFIG` + `APP_INITIALIZER` | `provideAuth` |
85
- | Environment | `src/core/environments/` com `authorizationServer` x `src/environments/` com `auth` | `src/core/environments/`, `authorizationServer`, `GraphqlEndpoint` do spine |
85
+ | Environment | `src/core/environments/` com `authorizationServer` x `src/environments/` com `auth` | `src/core/environments/`, `authorizationServer` tipado como `AuthConfig` do `@orfeu/angular`, `GraphqlEndpoint` do spine |
86
+ | Campos de login | interface própria com `silentRenew`/`useRefreshToken`/`postLogoutRedirectUri`/`responseType` | só o `AuthConfig` (os outros a lib não lê) |
87
+ | Imports absolutos | `baseUrl: "./"` (+ `ignoreDeprecations: "6.0"`) x `paths` | `paths` com `src/*` e `package.json`, sem `baseUrl` |
88
+ | Scripts | apps sem `start:homol`, com `start:prod`, `dev` sem `--configuration=dev` | o mesmo conjunto em todo app (`references/estrutura.md`) |
89
+ | Ferramentas de a11y | `@angular-eslint/*` avulsos, `@axe-core/puppeteer`, três `axe-check` diferentes | `angular-eslint` + `axe-core` com versão exata; `axe-check.js` e `eslint.a11y.config.js` idênticos |
86
90
  | Ajuste de URL em runtime | `applyRuntimeEnvironment` x cálculo manual no `main.ts` | `applyRuntimeEnvironment` (+ só o específico do app) |
87
91
  | Services | `src/app/services/<dominio>/` x dentro de `features/` | `src/app/services/<dominio>/` |
88
92
  | Componentes | signals/`input()`/`inject()` x `@Input` + construtor + `standalone: true` | signals/`input()`/`inject()` |
@@ -21,8 +21,9 @@ Regras:
21
21
  - Pasta de feature segue o **domínio**, em kebab-case e em inglês ou português de forma consistente no
22
22
  app (`pedidos/`, `order-history/`). A URL vem do Argos, então renomear pasta não muda rota.
23
23
  - Imports **sempre absolutos a partir de `src/`** (`import { X } from 'src/app/services/pedidos/pedidos.service'`),
24
- graças a `"baseUrl": "./"` no `tsconfig.json`. Exceções do próprio Angular: `templateUrl`,
25
- `styleUrl` e `@use` de SCSS, que são relativos ao arquivo.
24
+ graças a `"paths": { "src/*": ["./src/*"], "package.json": ["./package.json"] }` no `tsconfig.json`
25
+ (**sem `baseUrl`**: deprecado no TypeScript 6 e removido no 7 — não silencie com `ignoreDeprecations`).
26
+ Exceções do próprio Angular: `templateUrl`, `styleUrl` e `@use` de SCSS, que são relativos ao arquivo.
26
27
 
27
28
  ## Nomes
28
29
 
@@ -109,8 +110,8 @@ export const appConfig: ApplicationConfig = {
109
110
  `trismegisto`. `provideAuth()` e suas opções (ex.: `{ eagerInit: false }` para app com
110
111
  página pública) ficam na `orfeu`.
111
112
  - `provideZoneChangeDetection` **uma vez**, aqui. Não repita no `bootstrapApplication`.
112
- - `import packageInfo from 'package.json'` depende de `resolveJsonModule` + `baseUrl: "./"`; o shell
113
- usa a versão do app na tela "sobre".
113
+ - `import packageInfo from 'package.json'` depende de `resolveJsonModule` + o `paths` de `package.json`; o
114
+ shell usa a versão do app na tela "sobre".
114
115
  - Formato legado a evitar: `{ provide: AUTH_CONFIG, useValue }` + `APP_INITIALIZER` chamando
115
116
  `auth.initialize()` à mão. Use `provideAuth()`.
116
117
 
@@ -158,41 +159,50 @@ Arquivos em `src/core/environments/`:
158
159
 
159
160
  | Arquivo | Uso |
160
161
  | --- | --- |
161
- | `environment.config.ts` | Interfaces (`Environment`, `AuthorizationServer`) |
162
+ | `environment.config.ts` | Interface `Environment` |
162
163
  | `environment.ts` | Base (é o que os imports referenciam) |
163
164
  | `environment.prod.ts`, `.homol.ts`, `.dev.ts`, `.local.ts` | Trocados por `fileReplacements` na configuração de build homônima |
164
165
 
165
166
  Campos (só os nomes; os valores são de cada ambiente):
166
167
 
167
168
  ```ts
169
+ import type { AuthConfig } from '@orfeu/angular'; // não redeclarar
168
170
  import type { GraphqlEndpoint } from '@trismegisto/spine/graphql'; // não redeclarar
169
171
 
170
- export interface AuthorizationServer {
171
- authority: string; redirectUrl: string; postLogoutRedirectUri: string;
172
- clientId: string; realmId: string; scope: string;
173
- silentRenew: boolean; useRefreshToken: boolean;
174
- }
175
-
176
172
  export interface Environment {
177
173
  production: boolean;
178
- authorizationServer: AuthorizationServer;
174
+ authorizationServer: AuthConfig; // authority, realmId, clientId, redirectUrl, scope
179
175
  graphql: Record<string, GraphqlEndpoint>; // { namedClient, http, ws? } por backend
180
176
  adminApi: string; // API administrativa do Argos (auto-serviço)
181
177
  }
182
178
  ```
183
179
 
180
+ - O tipo do login é o `AuthConfig` da própria lib. Campos que ela não lê (`silentRenew`, `useRefreshToken`,
181
+ `postLogoutRedirectUri`, `responseType`) não entram no environment: são configuração morta — a renovação
182
+ é automática e o `applyRuntimeEnvironment` cuida de callback/logoff.
183
+ - Um arquivo por ambiente, **só** `local`, `dev`, `homol` e `prod`; `environment.ts` é igual ao `local`.
184
+
184
185
  - A chave de `graphql` e o `namedClient` costumam ser o mesmo nome (`pedidos: { namedClient: 'pedidos', ... }`).
185
186
  - Use `CHANGE_ME` em URL que deve ser derivada em runtime atrás do proxy.
186
187
  - Segredo nunca entra em environment: tudo ali vai para o bundle público.
187
188
  - Layout antigo `src/environments/` (fora de `core/`) e nomes de campo diferentes (`auth` em vez de
188
189
  `authorizationServer`) existem em apps mais velhos; não copiar.
190
+ - `src/core/environments/environments.spec.ts` confere que os cinco arquivos têm as mesmas chaves, que só o
191
+ `prod` é `production`, que `environment.ts` é igual ao `local`, client/realm iguais em todos e nenhuma URL
192
+ com barra final.
189
193
 
190
194
  ## `tsconfig.json`
191
195
 
192
196
  Base: `strict: true`, `noImplicitOverride`, `noPropertyAccessFromIndexSignature`, `noImplicitReturns`,
193
197
  `noFallthroughCasesInSwitch`, `resolveJsonModule`, `isolatedModules`, `moduleResolution: "bundler"`,
194
- `baseUrl: "./"`, `target/module: ES2022`; `angularCompilerOptions` com `strictTemplates`,
195
- `strictInjectionParameters`, `strictInputAccessModifiers`.
198
+ `target/module: ES2022`, e os imports absolutos por `paths` (sem `baseUrl`):
199
+
200
+ ```jsonc
201
+ "paths": { "src/*": ["./src/*"], "package.json": ["./package.json"] },
202
+ ```
203
+
204
+ `angularCompilerOptions` com `strictTemplates`, `strictInjectionParameters`, `strictInputAccessModifiers`.
205
+ TypeScript na mesma major em todos os apps (`~6.0`).
196
206
 
197
207
  `tsconfig.app.json`: `files: ["src/main.ts"]` + `include: ["src/**/*.d.ts"]`. Se o app importa `.md`
198
208
  como texto, declare em `src/markdown.d.ts`:
@@ -244,17 +254,26 @@ declare module '*.md' {
244
254
 
245
255
  ## Scripts do `package.json`
246
256
 
257
+ Os mesmos scripts, na mesma ordem, em todo app (só a porta muda):
258
+
247
259
  ```json
260
+ "ng": "ng",
248
261
  "start": "ng serve --port 4200",
249
262
  "dev": "ng serve --configuration=dev --port 4200 --no-hmr",
250
263
  "start:local": "ng serve --configuration=local --host 0.0.0.0 --port 4200 --no-hmr",
264
+ "start:homol": "ng serve --configuration=homol --host 0.0.0.0 --port 4200 --no-hmr",
251
265
  "build": "ng build",
252
266
  "build:dev": "ng build --configuration dev",
253
267
  "build:homol": "ng build --configuration homol",
268
+ "watch": "ng build --watch --configuration development",
254
269
  "test": "ng test",
255
270
  "lint:a11y": "eslint --config eslint.a11y.config.js \"src/**/*.html\"",
256
271
  "axe:check": "node scripts/axe-check.js",
257
272
  "codegen": "graphql-codegen --config codegen.ts"
258
273
  ```
259
274
 
275
+ Ferramentas com versão exata nos `devDependencies`, iguais entre os apps: `angular-eslint`, `eslint`,
276
+ `typescript-eslint`, `axe-core`, `puppeteer` (nada de `@angular-eslint/*` avulsos nem `@axe-core/puppeteer`).
277
+ Script de serve com configuração inexistente no `angular.json` quebra só quando alguém roda: confira.
278
+
260
279
  Cada app usa uma porta fixa própria no dev-server para não colidir com os outros.
@@ -41,6 +41,20 @@ describe('features.routes', () => {
41
41
  importar a classe estaticamente.
42
42
  - Com `document`, confira também que `document.load()` devolve texto não vazio.
43
43
 
44
+ ### Specs fixos do core (todo app tem)
45
+
46
+ | Spec | Confere |
47
+ | --- | --- |
48
+ | `src/core/app.config.spec.ts` | Monta os providers num `createEnvironmentInjector` filho do TestBed (sem bootstrap; filtra o `CORE_PROVIDERS[0]`, as animações) e lê os tokens: `SPINE_CONFIG` (clientId, appName, logo), `ROUTES` contém `APP_ROUTES`, `AUTH_CONFIG` = `environment.authorizationServer` e `AUTH_OPTIONS.eagerInit`, `AUTO_SERVICE_CONFIG`/`SPINE_ADMIN_API`, `COMPONENT_ROUTES` com as telas do app + `BASE_COMPONENTS`, `APP_PACKAGE_INFO` |
49
+ | `src/core/core.providers.spec.ts` | São três (animações, HttpClient, GraphQL); `ANIMATION_MODULE_TYPE` = `BrowserAnimations`; o HttpClient passa pelos interceptors do DI; um cliente Apollo por endpoint do environment (`PLATFORM_ID` = `server` para não abrir WebSocket) |
50
+ | `src/core/environments/environments.spec.ts` | Mesmas chaves nos cinco arquivos, só `prod` é `production`, `environment.ts` = `local`, client/realm iguais, URLs sem barra final |
51
+ | `src/core/core.component.spec.ts` | Título da aba |
52
+ | `src/app/features/features.routes.spec.ts` | Ids UUID únicos (sem diferenciar maiúsculas), todo `load()` standalone, documentação carregável |
53
+
54
+ Teste de initializer que mexe em login (`provideAppInitializer`): troque `AuthorizationService` e `Title`
55
+ por dublês no injetor, rode os `APP_INITIALIZER` com `runInInjectionContext` e confira o efeito — inclusive
56
+ quando o login falha (o título não pode depender do login).
57
+
44
58
  ### Componente que usa service GraphQL: Apollo falso
45
59
 
46
60
  O `injectGraphqlClient` chama `apollo.use(nome).query(...)` e espera um Observable. Substitua o
@@ -148,10 +162,23 @@ quando a associação é feita em runtime pelo componente: confira o DOM renderi
148
162
 
149
163
  ### axe no navegador
150
164
 
151
- `scripts/axe-check.js` (puppeteer + `@axe-core/puppeteer`) abre o app servido localmente, espera o
152
- login manual e roda o axe em cada rota de um JSON (`scripts/axe-routes.json`). Como as URLs vêm do
153
- Argos em runtime, o JSON mapeia `router_id -> path` preenchido à mão; rotas sem path são puladas.
154
- Rotas fixas do shell (`/login`, `/home`, `/callback`, `/logoff`) podem ir direto.
165
+ `scripts/axe-check.js` é **o mesmo arquivo em todo app** (puppeteer + `axe-core`). Lê as telas do
166
+ `features.routes.ts` (cada `{ id, load }`, pelo `id:` e o `.then(m => m.X)`), cruza com o `routeIdToPath` do
167
+ `axe-routes.config.json` (na raiz do app) e roda o axe em `staticRoutes` + nas telas com path conhecido;
168
+ avisa das que não têm. As URLs vêm do Argos em runtime: o `routeIdToPath` é preenchido navegando logado.
169
+
170
+ ```json
171
+ {
172
+ "baseUrl": "http://localhost:4200/meu-app/",
173
+ "staticRoutes": ["/login", "/home", "/no-permission"],
174
+ "routeIdToPath": {}
175
+ }
176
+ ```
177
+
178
+ - `baseUrl` = origem **e** caminho base do `start:local` (o `baseHref` da configuração `local`); as rotas
179
+ são resolvidas a partir dele (`/login` → `…/meu-app/login`). Sem o caminho base, o axe audita a página 404.
180
+ - Rotas logadas exigem `AXE_STORAGE_STATE=<json com cookies/localStorage>`; sem ele, o que redireciona para
181
+ `/login` é relatado como "sem auth", não como violação. `AXE_FAIL_ON` (padrão `serious`) define a saída 1.
155
182
 
156
183
  ## Build
157
184
 
@@ -78,15 +78,19 @@ Domínios com os mesmos nomes do serviço de trás e do front. Detalhes e códig
78
78
  7. **Introspecção só com `GRAPHQL_INTROSPECTION=true`** (no `.env.local` de quem roda o codegen), nunca
79
79
  derivada de `NODE_ENV`. `allowBatchedHttpRequests: true` sempre (o front envia em lote).
80
80
  8. **Encerramento**: o `node` é PID 1 no container — trate `SIGTERM`/`SIGINT`: `orfeu.flushAudit()`,
81
- `apollo.server.stop()` (o plugin de drain fecha HTTP e WS), teto de 8 s.
81
+ `apollo.server.stop()` (o plugin de drain fecha HTTP e WS); sai com **0** ao completar e com **1** se
82
+ estourar o teto de 8 s.
82
83
  9. Tudo que lê `process.env` em escopo de módulo quebra (ESM roda imports antes do `dotenv.config`): crie
83
84
  clientes (Redis, axios) **dentro** do builder ou de forma preguiçosa.
84
- 10. **Orfeu fora do ar na subida é decisão do builder**, escrita no código: cair (`exit 1`, o padrão) ou
85
- subir negando tudo e tentar o `startup()` de novo em segundo plano. Se subir, `/health` responde **503**
86
- até o Orfeu conectar. Nunca um modo que libera sem autorização
85
+ 10. **Orfeu fora do ar na subida: sobe negando** (padrão único). O servidor sobe, `/health` responde **503**
86
+ até o Orfeu conectar, toda operação não pública é negada e o `startup()` é tentado de novo com espera
87
+ crescente (5 s → 30 s). `OrfeuConfigError` derruba a subida. Nunca um modo que libera sem autorização
87
88
  ([references/estrutura-bootstrap.md](references/estrutura-bootstrap.md)).
88
89
  11. **Contexto é do servidor, não do cliente**: nada de `ctx.orfeuUser` gravado à mão (usuário validado por
89
90
  fora entra por `trustUser`) nem `connectionParams` espalhado no contexto do WebSocket.
91
+ 12. **`compression()` antes do Apollo** em todo gateway, e `AUTH_TLS_VERIFY=false` (se existir) com aviso na
92
+ subida e `tls_verify: false` no `/health`. Padrão completo do app (pastas, portas, scripts, saúde):
93
+ skill `acropole` (`references/arquitetura.md`).
90
94
 
91
95
  ## Esqueleto de um recurso
92
96
 
@@ -187,10 +191,10 @@ A autorização é **por campo** (preguiçosa), não na conexão. Canais Redis c
187
191
  ## Comandos
188
192
 
189
193
  ```bash
190
- npm run dev # tsx watch, NODE_ENV=local
191
- npm run build # tsc (ou esbuild --bundle) → dist/
194
+ npm run dev # tsx watch, NODE_ENV=local (também start:local / start:homol)
195
+ npm run build # typecheck + esbuild --bundle → dist/index.js (um arquivo, em milissegundos)
192
196
  npm run start:prod # node dist/index.js
193
- npm run typecheck # tsc --noEmit (obrigatório quando o build é esbuild)
197
+ npm run typecheck # tsc --noEmit
194
198
  npx vitest run # unitários
195
199
  ```
196
200
 
@@ -205,7 +209,7 @@ variáveis de ambiente e logs: [references/testes-build.md](references/testes-bu
205
209
  - Contexto do WS sem `App` → `ctx.App` indefinido só nas subscriptions.
206
210
  - `connectionParams` espalhado no contexto do WS → cliente forja chaves do `ctx` (com `@orfeu/node` 1.0.0,
207
211
  até o usuário).
208
- - Orfeu fora na subida com `/health` em 200 → o deploy vê saudável um gateway que nega tudo.
212
+ - Orfeu fora na subida com `/health` em 200 → o deploy vê saudável um gateway que nega tudo (o padrão é 503).
209
213
  - Campo novo sem `operation()` → servidor não sobe (correto); campo reaproveitando função → erro de marca dupla.
210
214
  - Esquecer `resolve` na subscription → `null` (o resolver padrão procura a chave com o nome do campo).
211
215
  - Envelope sem `data` anulável ou sem `Response` no nome → codegen/`unwrap` do front quebram.
@@ -32,7 +32,11 @@ Cada item aconteceu em servidor GraphQL de verdade. Formato: sintoma → causa
32
32
  - **"Modo degradado" que libera tudo quando o Argos está fora** → nunca; tente o `startup()` de novo em
33
33
  segundo plano e mantenha negado até conectar.
34
34
  - **Serviço "saudável" negando tudo** → subiu sem o Orfeu (startup em segundo plano) e o `/health` dizia
35
- 200 → enquanto o Orfeu não conecta, `/health` responde 503; ou escolha cair (`exit 1`) na subida.
35
+ 200 → enquanto o Orfeu não conecta, `/health` responde 503 (padrão: sobe negando, nova tentativa 5 s → 30 s).
36
+ - **Loop de restart com o Argos fora** → gateway que cai (`exit 1`) quando o `startup()` falha → suba negando
37
+ e tente de novo; só `OrfeuConfigError` (configuração errada) derruba a subida.
38
+ - **Encerramento por teto saindo com 0** → o orquestrador não distingue drenagem completa de travamento →
39
+ `exit(0)` ao completar, `exit(1)` no teto de 8 s.
36
40
  - **401 em todo campo depois de atualizar o `@orfeu/node` para 1.0.1** → o `context()` gravava
37
41
  `orfeuUser` à mão → `trustUser(ctx, claims)`, ou deixe o `orfeuPlugin` capturar a credencial.
38
42
  - **Validação de token duplicada no `context()`** (montando `{ token, user }` à mão) → diverge do guard e