@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
@@ -8,8 +8,9 @@
8
8
  Dockerfile
9
9
  .dockerignore
10
10
  .env.example só NOMES das variáveis
11
- requirements.txt dependências de runtime (o que a imagem instala)
12
- requirements-dev.txt -r requirements.txt + pytest (+ pytest-asyncio se houver teste async)
11
+ requirements.txt dependências DIRETAS de runtime, versão exata (o que a imagem instala)
12
+ requirements-dev.txt -r requirements.txt + pytest + poethepoet (+ pytest-asyncio se houver teste async)
13
+ pyproject.toml SÓ os atalhos do poe (start:local/dev/homol, test); nada de dependência aqui
13
14
  pytest.ini testpaths = tests · pythonpath = src
14
15
  src/
15
16
  main.py get_application() + `app = get_application()`
@@ -17,7 +18,7 @@
17
18
  settings/
18
19
  __init__.py reexporta AppSettings
19
20
  settings.py AppSettings (pydantic-settings) + carga dos .env
20
- environment/.env.<APP_ENV>
21
+ environment/.env.<APP_ENV> NÃO versionados; environment/.env.example (só nomes) versionado
21
22
  core/
22
23
  config.py get_app_settings() com @lru_cache
23
24
  connections/
@@ -68,7 +69,11 @@ def catalog_service(request: Request, db: Session = Depends(get_db)) -> CatalogS
68
69
  return CatalogService(db, getattr(request.state, "user", None))
69
70
  ```
70
71
 
71
- `request.state.user` é preenchido pelo middleware do Orfeu (detalhes na orfeu).
72
+ `request.state.user` é preenchido pelo middleware do Orfeu (detalhes na orfeu, `references/python.md`): é um
73
+ **`TokenClaims`** (objeto, não `dict` — `.sub`, `.groups`, `.realm_id`, `.exp`, `.raw` com o JWT); `None` quando quem
74
+ chamou usou `x-api-token` (a identidade está em `request.state.api_token`); ausente em rota `public`/`optional`
75
+ anônima. Nome do usuário: `user.raw.get("preferred_username") or user.sub`. Nunca `user.get(...)` (500).
76
+ Sempre `getattr(request.state, "user", None)`.
72
77
 
73
78
  ## `main.py`
74
79
 
@@ -148,26 +153,32 @@ Pontos de atenção:
148
153
  aguardadas com `suppress(asyncio.CancelledError)`.
149
154
  - Middlewares adicionados por último ficam mais externos. Middleware de trace/tempo que deve envolver
150
155
  tudo é adicionado depois do CORS.
151
- - Não use `urllib3.disable_warnings(...)` como “solução” de TLS; prefira configurar a CA. Se o ambiente
152
- realmente exige, deixe explícito por settings (`*_TLS_VERIFY`, default `True`).
153
- - **TLS do autorizador desligado só fora de produção, e com aviso.** `AUTHORIZER_TLS_VERIFY=false` em
154
- `prod` é erro de configuração: o serviço recusa subir. Fora de produção, sobe com um `warning` no log
155
- (quem lê o log de homologação vê que a verificação está desligada):
156
+ - **Nunca `urllib3.disable_warnings(...)` no processo inteiro**: esconde também o caso perigoso (o
157
+ autorizador sem verificação). Prefira configurar a CA (`SSL_CERT_FILE`/`REQUESTS_CA_BUNDLE`). Se o serviço
158
+ fala de propósito com destinos de CA interna (`verify=False`, ex.: appliances de rede), troque o
159
+ silenciamento por **um aviso por host**, registrado uma vez na subida (`main.py` e entrada de collector):
156
160
 
157
161
  ```python
158
- # core/config.py (validação das settings)
159
- @model_validator(mode="after")
160
- def _tls_do_autorizador(self) -> "AppSettings":
161
- if not self.authorizer_tls_verify and self.app_env == AppEnvTypes.prod:
162
- raise ValueError("AUTHORIZER_TLS_VERIFY=false não é permitido em produção")
163
- return self
164
-
165
- # main.py, em get_application(), depois do configure_logging()
162
+ # core/logging.py
163
+ def warn_insecure_requests_once() -> None:
164
+ import warnings
165
+ from urllib3.exceptions import InsecureRequestWarning
166
+ warnings.filterwarnings("once", category=InsecureRequestWarning) # o texto traz o host: 1 aviso por host
167
+ ```
168
+
169
+ - **TLS do autorizador desligado é opt-out explícito, com aviso.** `AUTHORIZER_TLS_VERIFY` (default `True`)
170
+ existe só para CA interna fora do bundle. Desligado, o serviço loga um `warning` na subida e o `/health`
171
+ devolve `data: {"tls_verify": false}` — a monitoração vê, não fica escondido:
172
+
173
+ ```python
174
+ # main.py, logo depois de settings = get_app_settings()
166
175
  if not settings.authorizer_tls_verify:
167
- logger.warning("TLS do autorizador DESLIGADO (APP_ENV=%s): aceitável só fora de produção", settings.app_env.value)
176
+ logger.warning("AUTHORIZER_TLS_VERIFY=false: o certificado do Argos NÃO é verificado (inclusive o JWKS).")
168
177
  ```
169
178
 
170
- Vale igual para todo `*_TLS_VERIFY` de outro destino.
179
+ Recusar a subida em produção exige um sinal confiável de ambiente: `APP_ENV` é digitado à mão no deploy e
180
+ não serve como trava. Só adote a recusa quando a plataforma injetar o ambiente. Vale igual para todo
181
+ `*_TLS_VERIFY` de outro destino.
171
182
 
172
183
  ## Roteador raiz (`app/__init__.py`)
173
184
 
@@ -183,11 +194,13 @@ router.include_router(tags_router) # cada router de domínio tem o próprio pre
183
194
 
184
195
  @router.get("/health")
185
196
  def health():
186
- return ok(message="ok")
197
+ # tls_verify:false só quando a verificação do certificado do Argos está desligada
198
+ from core.config import get_app_settings
199
+ return ok(data=None if get_app_settings().authorizer_tls_verify else {"tls_verify": False}, message="ok")
187
200
  ```
188
201
 
189
- `/health` sem `@operation` é público de propósito (healthcheck do orquestrador). Nem todo serviço tinha;
190
- inclua sempre.
202
+ `/health` sem `@operation` é público de propósito (healthcheck do orquestrador) e fica sob o `api_prefix`
203
+ (`/<projeto>/server/health`). Obrigatório em todo serviço, com teste.
191
204
 
192
205
  ## Settings e variáveis de ambiente
193
206
 
@@ -215,18 +228,26 @@ class AppSettings(BaseSettings):
215
228
  def configure_logging(self) -> None: ...
216
229
  ```
217
230
 
218
- - Ambientes: `local`, `dev`, `homol`, `prod` (um serviço usava também `devel`/`ti` — padronize nos quatro).
231
+ - Ambientes: **só** `local`, `dev`, `homol`, `prod` (o enum tem exatamente esses quatro). Sem `APP_ENV`, `local`;
232
+ arquivo `.env.<APP_ENV>` ausente (container) é ignorado, sem quebrar a subida.
219
233
  - `get_app_settings()` com `@lru_cache` em `core/config.py`; nunca instancie `AppSettings()` solto.
220
234
  - **Declare todo campo usado.** Depender de `extra="allow"` para ler, por exemplo, a porta faz o código
221
235
  funcionar só enquanto a variável existir no ambiente, sem default nem validação.
222
- - `fastapi_kwargs` põe `docs_url`, `openapi_url` e `redoc_url` sob `api_prefix` — e **desliga os três em
223
- produção** (`None`). O `/openapi.json` entrega o mapa inteiro da API (rotas, parâmetros, modelos) a quem
224
- chegar; em produção ninguém precisa dele, e o `/docs` ainda carrega script de CDN:
236
+ - `fastapi_kwargs` põe `docs_url`, `openapi_url` e `redoc_url` sob `api_prefix` — e **liga os três só em
237
+ `local`** (seguro por padrão: `dev`, `homol` e `prod` desligados; `API_DOCS=true/false` força). O
238
+ `/openapi.json` entrega o mapa inteiro da API (rotas, parâmetros, modelos) a quem chegar, e o `/docs` ainda
239
+ carrega script de CDN:
225
240
 
226
241
  ```python
242
+ api_docs: Optional[bool] = None # API_DOCS
243
+
244
+ @property
245
+ def docs_enabled(self) -> bool:
246
+ return self.api_docs if self.api_docs is not None else self.app_env == AppEnvTypes.local
247
+
227
248
  @property
228
249
  def fastapi_kwargs(self) -> dict:
229
- docs = self.app_env != AppEnvTypes.prod # /docs, /openapi.json e /redoc só fora de produção
250
+ docs = self.docs_enabled
230
251
  return {
231
252
  "debug": self.debug,
232
253
  "title": "meu-servico",
@@ -236,16 +257,17 @@ class AppSettings(BaseSettings):
236
257
  }
237
258
  ```
238
259
 
239
- Teste: com `APP_ENV=prod`, `GET <prefixo>/docs`, `/openapi.json` e `/redoc` respondem 404.
260
+ Teste parametrizado (`tests/test_api_docs.py`): `local` ligado; `dev`/`homol`/`prod` desligados (`None`);
261
+ `API_DOCS` força nos dois sentidos.
240
262
 
241
263
  Nomes de variáveis usados (sem valores):
242
264
 
243
265
  | Grupo | Variáveis |
244
266
  |---|---|
245
- | Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS` |
267
+ | Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS`, `API_DOCS` |
246
268
  | Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
247
269
  | Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT`, `MAX_CONNECTION_COUNT` |
248
- | Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (+ timeouts/prefixo de canal se usar pub/sub) |
270
+ | Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
249
271
  | Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
250
272
 
251
273
  Serviço com **vários bancos** usa o padrão de prefixo: `DB_ENTRIES=<nome1>,<nome2>` e, para cada nome,
@@ -255,27 +277,49 @@ com um banco, `DB_*` + `get_db`.
255
277
 
256
278
  ## Dependências
257
279
 
258
- `requirements.txt` mínimo:
280
+ `requirements.txt` = **dependências diretas** (o que o código importa), cada uma com **versão exata** — build
281
+ reproduzível, sem pacote morto e sem `pip freeze` de ambiente inteiro. As transitivas o pip resolve. Para
282
+ atualizar: troque a versão, recrie o ambiente do zero e rode a suíte.
259
283
 
260
284
  ```
261
- fastapi>=0.142
262
- uvicorn[standard]
263
- python-dotenv
264
- pydantic-settings
265
- orfeu[fastapi]>=1.0,<2
266
- sqlalchemy>=2
267
- psycopg2-binary
268
- httpx
269
- loguru # se usar loguru (ver logs em integracoes.md)
270
- redis # se usar Redis
271
- python-multipart # se houver upload (Form/File)
285
+ # Dependências DIRETAS (o que o código importa), com versão exata.
286
+ fastapi==0.142.2
287
+ uvicorn[standard]==0.54.0 # [standard]: uvloop + httptools (HTTP mais rápido no Linux)
288
+ orfeu[fastapi]==1.0.0
289
+ pydantic-settings==2.15.0
290
+ python-dotenv==1.2.4
291
+ loguru==0.7.3
292
+ SQLAlchemy==2.1.3
293
+ psycopg2-binary==2.9.13
294
+ redis==8.1.0 # se usar Redis
295
+ httpx==0.28.1
296
+ python-multipart==0.0.32 # só se houver upload (Form/File)
272
297
  ```
273
298
 
299
+ `requirements-dev.txt`: `-r requirements.txt`, `pytest==…`, `poethepoet==…` (e `pytest-asyncio==…` se
300
+ houver teste async). Os serviços de um mesmo ecossistema usam **as mesmas versões** das libs em comum.
301
+
302
+ Atalhos de execução no `pyproject.toml` (só `[tool.poe.tasks]`, sem `[project]`/Poetry):
303
+
304
+ ```toml
305
+ [tool.poe.tasks."start:local"]
306
+ cmd = "uvicorn main:app --host 0.0.0.0 --port 8000 --reload"
307
+ cwd = "src"
308
+ env = { APP_ENV = "local" }
309
+ # idem start:dev e start:homol (APP_ENV=dev/homol)
310
+
311
+ [tool.poe.tasks.test]
312
+ cmd = "python -m pytest"
313
+ ```
314
+
315
+ `poe start:homol` escolhe o ambiente pelo comando, como os `npm run start:<ambiente>` do Node — sem editar o
316
+ `src/.env`. Serviço que sobe processo filho (collector) fica **sem** `--reload` (o reload duplicaria o filho).
317
+
274
318
  Divergências observadas e recomendação:
275
319
 
276
320
  | Tema | Visto | Recomendado |
277
321
  |---|---|---|
278
- | Gerenciador | `requirements.txt` solto (2 serviços) vs `requirements.txt` congelado + `pyproject.toml` Poetry (1 serviço) | **pip + requirements.txt/requirements-dev.txt**; versões de topo, travando só o que tem motivo (`orfeu`, `fastapi`). Se quiser lock, gere com `pip freeze` num arquivo à parte, não com Poetry paralelo |
322
+ | Gerenciador | `requirements.txt` sem versão, ou congelado com transitivas e pacotes mortos, + `pyproject.toml` Poetry paralelo | **pip**: diretas com versão exata; `pyproject.toml` só com o poe; nada de Poetry/`poetry.lock` |
279
323
  | Python | 3.11 na imagem; local rodando 3.14 | piso 3.11; teste local na mesma menor da imagem quando possível |
280
324
  | Pasta | `server/` (2) vs `fastapi/` (1) | `server/` |
281
325
  | Imports diretos | pacote importado no código que só vinha como dependência transitiva (já corrigido num serviço) | declare no requirements tudo que o código importa diretamente |
@@ -18,8 +18,8 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
18
18
  | Timeouts das chamadas ao Argos | só a auditoria tem (10 s); token do serviço, sync, operações e introspecção **sem timeout** | 10 s em todas (introspecção: 5 s) |
19
19
  | Erro de rede na subida | erro cru do `fetch` (não é `OrfeuError`) | embrulhado: `OrfeuAuthError` / `OrfeuSyncError` / `OrfeuError` |
20
20
  | Quem chama a subida | o app: `client.startup()` / `OrfeuClient.create()` depois de declarar as rotas; Nest: `OrfeuModule.forRootAsync` | FastAPI: automático no lifespan (`Orfeu(app, ...)`); Flask e Django: **na construção**, síncrono; Strawberry: o app chama `startup_async()` no lifespan |
21
- | Permissões (`allowed_groups`) | lidas **só** na subida ou em `fetchOperations()` manual | idem: só na subida ou em `fetch_operations()` manual |
22
- | `fetchOperations` / `fetch_operations` com token do serviço vencido (401) | **não** reautentica: lança `OrfeuError`; chame `authenticate()` antes | idem: não reautentica, lança `OrfeuError` |
21
+ | Permissões (`allowed_groups`) | revalidadas a cada 60 s por padrão (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; opção `permissionsRefresh`); antes, só na subida ou em `fetchOperations()` manual | idem (`permissions_refresh`); antes, só na subida ou em `fetch_operations()` manual |
22
+ | `fetchOperations` / `fetch_operations` com token do serviço vencido (401) | reautentica uma vez e repete (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1); antes lançava `OrfeuError` | idem (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) |
23
23
  | Reautenticação automática no 401 | só na auditoria e na introspecção | idem |
24
24
  | Inferência de `Method` sem `method` explícito | pelo **último segmento do id** após `:` (`tasks:list` → `read`); Apollo: pelo tipo raiz (Query → `read`, Mutation → `write`/`delete`, Subscription → `stream`) | pelo **nome da função** (`get_`/`list_`/... → `read`) |
25
25
  | Convenção de id nos exemplos | `recurso:acao` | `recurso.acao` |
@@ -38,7 +38,7 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
38
38
  | Classes de erro | 401 do `createGuard` é `Error` comum; não existe `OrfeuUnauthorizedError` | existe `OrfeuUnauthorizedError` (e as negações também são `PermissionError`) |
39
39
  | WebSocket negado | Apollo/graphql-ws: `GraphQLError` | FastAPI: fecha com **1008** antes do `accept` |
40
40
  | Envelope de resposta do app | não existe no SDK | `install_envelope(app)`, `ok`/`fail`, `NotFound`, `Conflict`… |
41
- | Flush da auditoria no encerramento | **manual**: `await client.flushAudit()` no SIGTERM do app | automático no shutdown do lifespan (FastAPI) e no `atexit`; `flush_audit()` força |
41
+ | Flush da auditoria no encerramento | `await client.close()` no SIGTERM do app (para a recarga + flush; `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) — Fastify/Nest/Apollo fazem sozinhos; antes, `flushAudit()` manual | automático no shutdown do lifespan (FastAPI); Flask `orfeu.shutdown()`/`atexit`; Django `atexit` |
42
42
  | Log de operação padrão | uma linha JSON no **stdout** (`jsonLineLogger`); `logger: false` desliga | `logging` padrão (`orfeu.operation`), **sem handler**: sem configurar, as linhas INFO não aparecem; `JsonLogFormatter` opcional |
43
43
  | `traceparent` repassado | flags propagadas como chegaram | só o bit *sampled* é propagado |
44
44
  | `orfeuHeaders` / `orfeu_headers` fora de operação protegida | Express/Fastify: funciona em qualquer rota que passou pela captura global (mesmo sem guard); Nest: só em método com `@Operation`; Apollo: com o plugin/contexto instalado | devolve `{}` fora de chamada guardada |
@@ -32,7 +32,11 @@ class OrfeuClient {
32
32
  startup(): Promise<void>;
33
33
  authenticate(): Promise<void>;
34
34
  syncOperations(): Promise<void>;
35
- fetchOperations(): Promise<void>;
35
+ fetchOperations(): Promise<boolean>; // true se o catálogo mudou; reautentica uma vez no 401
36
+ refreshOperations(): Promise<boolean>; // revalidação (If-None-Match); nunca lança; true = sucesso
37
+ startPermissionsRefresh(): void; stopPermissionsRefresh(): void;
38
+ readonly lastPermissionsSyncAt: Date | null; readonly permissionsStale: boolean;
39
+ close(timeoutMs?: number): Promise<void>; // para a recarga + flushAudit
36
40
  validateToken(token: string): Promise<TokenClaims>;
37
41
  validateAppToken(token: string): Promise<TokenClaims>;
38
42
  validateApiToken(token: string, identifier: string, method: string): Promise<ApiTokenClaims | null>;
@@ -56,7 +60,9 @@ class OrfeuClient {
56
60
  | `checkPermission(claims, id, method)` | usa o cache do `fetchOperations()`: operação desconhecida → `false`; `public` → `true`; `private`/`optional` → `claims.groups.length > 0`; `protected` → algum grupo em `allowed_groups`. |
57
61
  | `operationIdOf(id, method)` | UUID da operação no Argos (depois do `fetchOperations()`), para logs. |
58
62
  | `recordAudit(event)` | põe um evento na fila (no-op com `audit: false`). Nunca bloqueia. |
59
- | `flushAudit(timeoutMs = 3000)` | envia o que estiver na fila, esperando no máximo `timeoutMs`. Use no encerramento. |
63
+ | `flushAudit(timeoutMs = 3000)` | envia o que estiver na fila, esperando no máximo `timeoutMs`. |
64
+ | `close(timeoutMs = 3000)` | (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) para a recarga de permissões e faz o `flushAudit`. Use no encerramento. |
65
+ | `permissionsRefresh` (opção) | (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) `true` (padrão: 60 s, ±20%), `false` ou `{ enabled, intervalMs, jitter }`. O `startup()` agenda a recarga; timer com `unref()`. |
60
66
 
61
67
  ### Tipos de identidade
62
68
 
@@ -30,8 +30,8 @@ constantes; em TypeScript, variáveis `string` precisam do tipo `Level`/`Method`
30
30
  ## 401 / 403 inesperados
31
31
 
32
32
  **403 para todo mundo numa operação nova `protected`.** A operação acabou de ser sincronizada e ainda não tem
33
- grupos em `allowed_groups` no Argos. Libere os grupos no Argos **e** recarregue as permissões no serviço
34
- (reinício ou `fetchOperations()` periódico — `node-recipes.md` §10).
33
+ grupos em `allowed_groups` no Argos. Libere os grupos no Argos; com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 o serviço recarrega sozinho em até
34
+ ~1 min (antes: reinício ou `fetchOperations()` periódico — `node-recipes.md` §10).
35
35
 
36
36
  **403 em `private` para um usuário logado.** `private`/`optional` exigem **pelo menos um grupo** na claim
37
37
  `groups`. Usuário sem grupo no client/badge recebe 403.
@@ -41,7 +41,7 @@ registrado tarde, módulo carregado com `import()` dinâmico): ela não está no
41
41
  `checkPermission` devolve `false` (só `public` escapa). Declare tudo antes do `startup()`.
42
42
 
43
43
  **Permissão mudou no Argos e o serviço não percebeu.** O catálogo com `allowed_groups` é lido no `startup()`.
44
- Recarregue com `fetchOperations()` (reautenticando se der 401). Grupos do **usuário** mudam quando o token dele
44
+ Com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1 a recarga é automática; antes, recarregue com `fetchOperations()` (reautenticando se der 401). Grupos do **usuário** mudam quando o token dele
45
45
  é renovado.
46
46
 
47
47
  **401 com token válido.**
@@ -127,7 +127,7 @@ descartados do evento, mas continuam no log).
127
127
 
128
128
  ## Auditoria e log
129
129
 
130
- **Eventos perdidos ao reiniciar.** Faltou `await client.flushAudit()` no SIGTERM (`node-recipes.md` §11).
130
+ **Eventos perdidos ao reiniciar.** Faltou `await client.close()` (ou `flushAudit()` em versão antiga) no SIGTERM (`node-recipes.md` §11).
131
131
 
132
132
  **Aviso `[orfeu] authorizer has no audit endpoint (404); auditing paused for 10 min`.** O Argos não tem a
133
133
  ingestão de auditoria; a fila é descartada e o SDK tenta de novo depois. Se a auditoria não é desejada:
@@ -146,7 +146,7 @@ export class ClientesController {
146
146
  módulo do app. Métodos sem `@Operation` continuam **abertos** — confira todos.
147
147
  - `OrfeuClient` é injetável (`constructor(private readonly orfeu: OrfeuClient) {}`) para `checkPermission`,
148
148
  `flushAudit` etc.
149
- - Encerramento: `app.enableShutdownHooks()` e, num provider, `async onApplicationShutdown() { await this.orfeu.flushAudit(); }`.
149
+ - Encerramento: `app.enableShutdownHooks()`; o `OrfeuModule` para a recarga e envia a auditoria no `onModuleDestroy` (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1). Antes, num provider, `async onApplicationShutdown() { await this.orfeu.flushAudit(); }`.
150
150
 
151
151
  ## 4. Apollo Server (HTTP + WebSocket)
152
152
 
@@ -400,19 +400,24 @@ async function startOrfeu(): Promise<void> {
400
400
  }
401
401
  }
402
402
 
403
- // grupos liberados (allowed_groups) só são lidos no startup: recarregue de tempos em tempos
404
- async function refreshPermissions(): Promise<void> {
405
- try {
406
- await client.fetchOperations();
407
- } catch {
408
- await client.authenticate(); // token do serviço vence; fetchOperations não reautentica sozinho
409
- await client.fetchOperations();
410
- }
411
- }
412
- setInterval(() => { refreshPermissions().catch((e) => console.warn('[app] permissões não recarregadas', e)); }, 5 * 60_000).unref();
413
403
  ```
414
404
 
415
405
  Um `OrfeuAuthError` com HTTP 401 na subida quase sempre é `APP_ID`/`APP_SECRET` errados; repetir não resolve.
406
+ HTTP 400 `invalid_request` no `/apps/token` é `APP_ID` que não é UUID ou `APP_SECRET` **vazio** (variável não preenchida).
407
+
408
+ **Permissões atualizadas** (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1): o client revalida sozinho o catálogo com os grupos liberados a cada 60 s
409
+ (±20%), com `If-None-Match` (304 quando nada mudou), troca o catálogo de uma vez, reautentica no 401 e, se o Argos
410
+ estiver fora, mantém o catálogo anterior (`permissionsStale` vira `true` depois de 5 ciclos sem sucesso). Liberar ou
411
+ **revogar** um grupo no Argos vale em até ~1 min, sem reiniciar. Ajuste ou desligue no construtor:
412
+
413
+ ```ts
414
+ const client = new OrfeuClient({ /* … */, permissionsRefresh: { intervalMs: 60_000, jitter: 0.2 } }); // ou false
415
+ client.lastPermissionsSyncAt; // Date | null — último sucesso
416
+ client.permissionsStale; // true após 5 intervalos sem sucesso (bom para o /health, sem derrubar)
417
+ ```
418
+
419
+ Versão anterior a essa: as permissões só eram lidas no `startup()` — recarregue com `fetchOperations()` num
420
+ `setInterval` (`unref()`), chamando `authenticate()` antes de repetir quando der 401 (o token do serviço vence).
416
421
 
417
422
  ## 11. Encerramento sem perder eventos
418
423
 
@@ -420,13 +425,15 @@ Um `OrfeuAuthError` com HTTP 401 na subida quase sempre é `APP_ID`/`APP_SECRET`
420
425
  for (const signal of ['SIGTERM', 'SIGINT'] as const) {
421
426
  process.once(signal, async () => {
422
427
  server.close(); // para de aceitar conexões
423
- await client.flushAudit(5_000); // envia a fila de auditoria (espera no máximo 5 s)
428
+ await client.close(5_000); // para a recarga de permissões e envia a fila de auditoria (máx. 5 s)
424
429
  process.exit(0);
425
430
  });
426
431
  }
427
432
  ```
428
433
 
429
434
  Em container sem init, o processo Node é o PID 1 e só termina no SIGTERM se tratar o sinal (como acima).
435
+ `close()` existe a partir de `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1; antes, `flushAudit()` (não havia recarga para parar). Fastify (`fastify.close()`),
436
+ Nest (`app.close()`) e o `orfeuPlugin` do Apollo (`server.stop()`) já chamam o encerramento do client sozinhos.
430
437
 
431
438
  ## 12. Testes
432
439
 
@@ -51,6 +51,7 @@ A lib **não lê variáveis de ambiente**. Tudo entra pelo construtor (`Orfeu(..
51
51
  | `secret` | sim | Segredo do backend, em texto puro. Nunca no código: venha de variável de ambiente/cofre. |
52
52
  | `tls_verify` | não, só por nome (`*`) | `True` (padrão). `False` desliga a verificação TLS **só** nas chamadas ao Argos (certificado autoassinado em desenvolvimento). Não é global. |
53
53
  | `audit` | não, só por nome | `True` (padrão), `False` (desliga a auditoria) ou `AuditOptions(...)` (ajusta lote/buffer). |
54
+ | `permissions_refresh` | não, só por nome (`@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1) | `True` (padrão: revalida o catálogo com os grupos liberados a cada 60 s ±20%, com `If-None-Match`; mantém o anterior se o Argos cair), `False` ou `PermissionsRefreshOptions(enabled, interval_s, jitter)`. Django: `ORFEU_PERMISSIONS_REFRESH`. |
54
55
 
55
56
  Django: settings `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (obrigatórios —
56
57
  sem eles o middleware levanta `RuntimeError`), `ORFEU_TLS_VERIFY` e `ORFEU_AUDIT` (opcionais).
@@ -84,8 +85,8 @@ async def list_items(request: Request):
84
85
  ```
85
86
 
86
87
  - `Orfeu(app, ...)` instala um middleware ASGI e **embrulha o lifespan** do app: no startup roda
87
- token do app → JWKS → sync das operações → busca das operações com grupos; no shutdown faz o flush da
88
- auditoria. Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
88
+ token do app → JWKS → sync das operações → busca das operações com grupos (e, com `@orfeu/node` ≥ 1.1 / `orfeu` ≥ 1.1, agenda a recarga
89
+ periódica delas); no shutdown para a recarga e faz o flush da auditoria (`client.close()`). Funciona com `lifespan=` e com `on_startup`. Não chame nada no seu lifespan.
89
90
  - O startup **falha** (e o app não sobe) se o Argos recusar as credenciais (`OrfeuAuthError`), o sync falhar
90
91
  (`OrfeuSyncError`), o JWKS não vier (`OrfeuError`) ou **nenhuma** `@operation` estiver registrada
91
92
  (`OrfeuConfigError`). Não há retentativa: o Argos precisa estar acessível no boot.
@@ -133,6 +134,11 @@ O que o handler FastAPI recebe (`request.state` / `websocket.state`):
133
134
 
134
135
  Por isso, em `public`/`optional` leia com `getattr(request.state, "user", None)`.
135
136
 
137
+ `TokenClaims` é um **objeto** (dataclass), não um `dict`: `user.sub`, `user.realm_id`, `user.groups`, `user.exp` e
138
+ `user.raw` (o JWT decodificado inteiro). Nome/e-mail do usuário estão em `raw`:
139
+ `user.raw.get("preferred_username") or user.raw.get("email") or user.sub`. `user.get(...)` lança
140
+ `AttributeError: 'TokenClaims' object has no attribute 'get'` (500 na rota).
141
+
136
142
  ## 6. Respostas, erros e status
137
143
 
138
144
  | Situação | Resposta |
@@ -0,0 +1,118 @@
1
+ ---
2
+ name: orquestracao
3
+ description: Orquestra uma mudança grande do pedido à entrega no estilo spec-driven — especificação do contrato nas camadas (server, GraphQL, Angular, banco, Argos), plano em itens Txx, execução por vários agentes/sessões em paralelo com reserva atômica de itens (scripts/coord.sh), verificação com provas e fechamento. Use quando o pedido atravessa mais de uma camada ou mais de um app, quando for dividir trabalho entre subagentes ou sessões paralelas, quando o usuário pedir "spec", "plano", "SDD", "paraleliza", "orquestra", ou quando houver uma lista de itens Txx a distribuir entre workers.
4
+ ---
5
+
6
+ # orquestracao
7
+
8
+ Leva uma mudança grande do pedido à entrega, com vários agentes trabalhando ao mesmo tempo sem pisar um no outro.
9
+ Esta skill diz **o que fazer, em que ordem e como dividir**; o **como** de cada camada está nas skills da stack
10
+ (`angular`, `trismegisto`, `apollo`, `express`, `fastapi`, `orfeu`, `docker`, `hefesto`, `documentacao`) e o desenho
11
+ do app inteiro na skill `acropole` (`references/arquitetura.md`). Carregue a skill da camada antes de mexer nela.
12
+
13
+ Responda em português. Pergunte só o que é decisão do usuário (escopo, nível de acesso, regra de negócio, apagar algo);
14
+ o resto resolva com o padrão e diga o que escolheu.
15
+
16
+ ## Ordem de dependência de uma mudança
17
+
18
+ ```
19
+ server/ (regra, banco, envelope, @operation) → graphql/ (repasse, operation()) → angular/ (tela, service, toast)
20
+ ↘ database/ (schema, seed, migration) Argos (operações, permissões, rotas) ↙
21
+ ```
22
+
23
+ ## Onde fica cada coisa (no repositório do app)
24
+
25
+ | O quê | Onde | Git |
26
+ |---|---|---|
27
+ | Itens de trabalho (Txx) e protocolo dos workers | `docs/sdd/tasks.md` (de `templates/tasks.md`) | versionado |
28
+ | Pendências e decisões em aberto | `docs/sdd/pending.md` | versionado |
29
+ | Specs | `docs/sdd/specs/<tema>.md` (de `templates/spec.md`) | versionado |
30
+ | Planos para vários agentes | `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) | versionado |
31
+ | Travas de coordenação | `.sdd/coord/` (criado pelo `coord.sh`) | **fora do git** |
32
+
33
+ `coord.sh` = `bash <pasta desta skill>/scripts/coord.sh` (instalada: `~/.claude/skills/orquestracao/scripts/coord.sh`,
34
+ ou `./.claude/skills/...` com `--project`). Ele acha a raiz pelo git da pasta atual; `coord.sh init` cria a lista e põe
35
+ `.sdd/` no `.gitignore`. Trabalho que atravessa vários repositórios: uma lista por repositório, ou `COORD_ROOT` apontando
36
+ para uma pasta comum (e `COORD_TASKS` para a lista).
37
+
38
+ ## Fase 0 — Contexto (antes de qualquer arquivo)
39
+
40
+ 1. README/`CLAUDE.md` do repositório e das pastas que vai tocar.
41
+ 2. `docs/sdd/pending.md` e `docs/sdd/tasks.md`: o pedido pode já estar descrito ou bloqueado por uma decisão.
42
+ 3. Trabalho em andamento: `coord.sh status` (e `coord.sh stale` para reserva parada/órfã). Não mexa em
43
+ arquivo/recurso reservado por outro worker.
44
+ 4. O domínio mais parecido já existente nas camadas: ele é o molde.
45
+ 5. `git status` de cada repositório envolvido: mudança pendente que não é sua não entra no seu commit.
46
+
47
+ ## Fase 1 — Especificação (o quê)
48
+
49
+ `docs/sdd/specs/<tema>.md` a partir de `templates/spec.md`. Define o **contrato**, não o código: comportamento
50
+ observável; rotas do server (método, caminho, entrada, `data`, operação e nível, mensagens e erros); campos do GraphQL e
51
+ canais; telas, ações e toasts do Angular (`router_id` se tela nova); dados; Argos (operações, níveis, grupos, tokens,
52
+ rotas liberadas); fora do escopo, restrições e critérios de aceite verificáveis. Um nome por domínio nas camadas
53
+ (`pedidos` / `pedidos` / `pedidos:*`). Mostre ao usuário quando houver decisão dele dentro; senão siga.
54
+
55
+ ## Fase 2 — Plano (como, em itens)
56
+
57
+ - Itens `Txx` (próximo número livre) em `docs/sdd/tasks.md`: `- [ ] **Txx** · <camada/domínio> — <alteração> (data)`.
58
+ **Um item = uma entrega verificável**, de preferência uma camada de um domínio (ou um app, numa mudança entre apps).
59
+ - Ordem: server → GraphQL → Angular → banco/Argos → fechamento. Itens de pastas **disjuntas** podem ir em paralelo.
60
+ - Trabalho para vários agentes: `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) com decisões tomadas, mapa de
61
+ nomes, dependências, arquivos compartilhados e uma seção "Registro" por item.
62
+
63
+ ## Fase 3 — Execução (um ou vários workers)
64
+
65
+ Para cada item:
66
+
67
+ 1. Reservar: `coord.sh register` (uma vez por sessão) → `coord.sh claim <worker> Txx` → `coord.sh check <worker> Txx`
68
+ responde `OK` → só então implementar.
69
+ 2. Implementar seguindo a skill da camada.
70
+ 3. Provas da camada (Fase 4) passando.
71
+ 4. Registrar no plano (seção do item) ou na resposta: o que mudou, provas, o que ficou para o usuário.
72
+ 5. `coord.sh done <worker> Txx` e `[x]` na linha. Bloqueado: `coord.sh release`. Ao encerrar: `coord.sh unregister`.
73
+
74
+ Como dividir entre subagentes/sessões, o que vai no prompt de cada um e os recursos que travam (dev server segurando
75
+ `node_modules`, banco e Redis compartilhados, git): [references/paralelismo.md](references/paralelismo.md).
76
+
77
+ ## Fase 4 — Verificação (provas, não impressão)
78
+
79
+ | Camada | Prova |
80
+ |---|---|
81
+ | server | `pytest` inteiro (ambiente recriado do zero se mudou dependência) |
82
+ | GraphQL | `tsc --noEmit`, `vitest`, `build`; todo campo com `operation()` |
83
+ | Angular | codegen sem erro, `ng test`, `ng build`, `lint:a11y` |
84
+ | banco | `python build.py` e a suíte da pasta (PGlite) |
85
+ | ponta a ponta | serviços locais de pé com o código novo; o usuário valida no navegador |
86
+
87
+ Relate falha como falha, com a saída. Teste que depende de dado/ambiente externo (Redis real, equipamento): diga qual e
88
+ por quê; rode-o isolado antes de concluir que a mudança quebrou algo (carga de várias suítes em paralelo derruba teste de
89
+ tempo).
90
+
91
+ ## Fase 5 — Argos (permissões e telas)
92
+
93
+ - O sync do Orfeu cria as operações novas e **desativa** as que o app não declara mais; **não dá permissão**.
94
+ `protected` precisa de permissão por grupo; **token de API (`x-api-token`) precisa de permissão em qualquer nível**;
95
+ operação renomeada perde as permissões da antiga (`templates/permissoes-argos.sql` leva para a nova).
96
+ - Tela nova: rota e roteador do client **e** a liberação do roteador para os grupos (sem ela o menu vem vazio);
97
+ `router_id` no `features.routes.ts`. Client novo: redirect URIs (inclusive `localhost`) e acesso dos grupos.
98
+ - Banco de produção: só leitura. Quem aplica migration é o usuário, no deploy.
99
+
100
+ ## Fase 6 — Fechamento
101
+
102
+ - `docs/sdd/pending.md`: apague o resolvido; registre o que ficou (decisões do usuário, dívidas) com **o quê / onde /
103
+ o que falta**.
104
+ - README/`CLAUDE.md` que mudaram de verdade; variáveis de ambiente novas (lista para o deploy).
105
+ - Relatório ao usuário: o que foi feito, provas (números), o que é dele (validar no navegador, Argos, deploy, commits).
106
+
107
+ ## Regras que não se quebram
108
+
109
+ - **Sem commit nem push** sem pedido explícito (vale só para aquele pedido). Commit, quando pedido: confira antes o
110
+ `git status` — mudança de outra pessoa ou pasta que o projeto não versiona por combinado não entra sem confirmação;
111
+ um commit por repositório, mensagem no padrão do repositório.
112
+ - Working tree compartilhado: nunca `git reset/stash/clean/checkout -- .`.
113
+ - Banco, Redis e serviços compartilhados não recebem dado de teste: SQLite em memória, Redis falso, mocks.
114
+ - Credencial nunca em código, log ou resposta; ao mexer em `.env`, não imprima valores. Segredo gerado para o usuário
115
+ vai para arquivo fora de qualquer repositório.
116
+ - Processo do usuário (dev server, Argos local) não se derruba sem pedir; diga qual processo e por quê.
117
+ - Mudança fora do escopo do item (outro repositório, desenho novo): proponha antes de fazer.
118
+ - Ações reais em servidores/containers (deploy, rollback, restart) não se testam contra ambiente real: mocks.
@@ -0,0 +1,48 @@
1
+ # Paralelismo: subagentes, sessões e recursos compartilhados
2
+
3
+ ## Quando paralelizar
4
+
5
+ - **Pode** ir em paralelo: itens em pastas disjuntas (o `server/` de um app e o `angular/` de outro; libs diferentes;
6
+ documentação × código), validações independentes (a suíte de cada app), leitura/levantamento.
7
+ - **Não** vai em paralelo: dois agentes no mesmo arquivo, item que depende da saída de outro (o codegen do front precisa
8
+ do schema do GraphQL), qualquer coisa que mexa no mesmo `package.json`/lockfile ao mesmo tempo.
9
+ - Tarefa pequena e sequencial: faça você mesmo; subagente começa sem contexto e custa caro para reconstruí-lo.
10
+
11
+ ## Subagente (Agent/Task) — o prompt é tudo o que ele sabe
12
+
13
+ Inclua sempre:
14
+
15
+ 1. **Objetivo e escopo fechado**: repositório e pastas que pode tocar; o que **não** pode (outros repositórios, pastas
16
+ que o projeto não versiona, `.env` de verdade).
17
+ 2. **Contexto mínimo**: onde está a spec/plano, o domínio molde, as skills a seguir (nome), comandos de teste/venv.
18
+ 3. **Decisões já tomadas** (o subagente não deve reabrir) e **o que deixar para o usuário**.
19
+ 4. **Provas exigidas**: quais suítes rodar e que tudo passe; o que fazer se uma falha não for dele.
20
+ 5. **Proibições**: sem commit/push/publicação/bump; sem `git reset/stash/clean`; sem dado de teste em recurso real.
21
+ 6. **Formato do relatório**: arquivos alterados, decisões, números das suítes, o que não deu para fazer, riscos.
22
+
23
+ Rode em segundo plano quando houver outra coisa útil a fazer; não faça em paralelo o mesmo trabalho dele. Complemento do
24
+ usuário no meio do caminho: mande para o subagente (mensagem) em vez de recomeçar. O relatório dele é pista: confira os
25
+ pontos críticos (rode a suíte) antes de dar como feito.
26
+
27
+ ## Sessões paralelas (vários terminais/agentes no mesmo working tree)
28
+
29
+ - Cada sessão: `coord.sh register` → um item por vez (`claim`/`check`/`done`) → `unregister` ao sair.
30
+ - Reserva parada: `coord.sh stale [horas]`. Worker que morreu sem `unregister`: `coord.sh orphans --release` devolve os
31
+ itens dele (confira antes que a sessão realmente acabou).
32
+ - Trabalho entre repositórios: `COORD_ROOT=<pasta comum> COORD_TASKS=<lista>` em todas as sessões.
33
+
34
+ ## Recursos que travam (e como contornar sem derrubar o usuário)
35
+
36
+ | Recurso | Sintoma | O que fazer |
37
+ |---|---|---|
38
+ | Dev server (`ng serve`, `nodemon`, `uvicorn --reload`) rodando | `EBUSY`/`EPERM` no `npm install` (Windows trava `.node`/`sass-embedded`) | `npm install --package-lock-only` (lock e `package.json` certos, `node_modules` depois); avise para reiniciar |
39
+ | Dependência trocada com processo de pé | `uvicorn --reload` antigo + pacote novo = erro estranho (`'Config' object has no attribute ...`); `nodemon` compilou antes do install | reiniciar o processo (Ctrl+C e subir de novo); não é bug do código |
40
+ | Processo órfão (pai morreu) | porta ocupada, código antigo respondendo | listar processo + pai (PowerShell `Get-CimInstance Win32_Process`, `ps -o ppid`); encerrar só com o ok do usuário |
41
+ | Banco/Redis compartilhado | teste "falha" por dado ausente ou sujo | teste isolado com SQLite/Redis falso; teste que lê dado real é ambiental — diga isso |
42
+ | Git | dois agentes commitando | commit só por caminho, um repositório por vez, sem `add -A` cego |
43
+ | CPU | suítes em paralelo derrubam teste de tempo | rode o teste que falhou isolado antes de concluir |
44
+
45
+ ## Validação em lote (vários apps)
46
+
47
+ Dispare as suítes de cada app em paralelo (um processo por app, saída em arquivo), depois resuma em tabela
48
+ (app → testes/build → resultado). Falhou um: rode isolado, leia o erro, separe "quebrou com a mudança" de "ambiental".