@acropole/skills 0.0.0-stage → 1.0.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 (90) hide show
  1. package/README.md +180 -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 +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,282 @@
1
+ # O porquê de cada decisão
2
+
3
+ ## Imagem base
4
+
5
+ | Uso | Base | Por quê |
6
+ | --- | --- | --- |
7
+ | Runtime Node | `node:22-alpine` | ~50 MB a menos que `slim`; o runtime só precisa de `node` + JS puro |
8
+ | Build do Angular | `node:22-slim` | esbuild, sass e outros binários opcionais publicam builds glibc; em Alpine (musl) às vezes caem para fallback lento ou falham |
9
+ | Python | `python:3.12-slim` | as dependências vêm como wheel `manylinux` (glibc). Em Alpine o pip compila tudo do fonte: build lento e imagem maior |
10
+ | Site final | `scratch` | só transporta arquivos; não há processo |
11
+
12
+ - Fixe a versão maior (`node:22`, `python:3.12`): `latest` muda sem aviso e quebra build antigo
13
+ (rollback que não builda mais).
14
+ - Pacote nativo do Node com binário glibc pré-compilado (ex.: alguns drivers) não carrega em Alpine:
15
+ use `node:22-slim` no build **e** no runtime desse app.
16
+
17
+ ## Multi-stage
18
+
19
+ O estágio de build tem compilador TypeScript, devDependencies, cache, código-fonte. O final copia só
20
+ `dist` + `node_modules` de produção. Ganhos: imagem menor (pull mais rápido em cada deploy), menos
21
+ superfície de ataque (sem ferramenta de build para um invasor usar) e nada do código-fonte/testes
22
+ em produção.
23
+
24
+ Uma instalação só: `npm ci` completo no build, `npm prune --omit=dev` depois do `tsc`, e o runtime
25
+ copia o `node_modules` pronto. Instalar de novo no estágio final dobra o tempo e pode resolver versões
26
+ diferentes se o lock não for usado. A limpeza por tipo de arquivo (`.d.ts`, `.map`, `.md`) reduz
27
+ bastante (medido ~118 → ~70 MB num gateway GraphQL) sem tocar em código: apagar por nome de pasta
28
+ (`docs/`, `test/`) quebra pacote que tem código de runtime nessas pastas.
29
+
30
+ Remover npm/yarn/corepack do runtime economiza ~20 MB e impede o `CMD npm start` por engano.
31
+
32
+ ## Cache de dependências
33
+
34
+ Cada instrução gera uma camada; uma camada é reaproveitada se a instrução e tudo que ela copia não
35
+ mudaram — e invalida todas as seguintes.
36
+
37
+ ```
38
+ COPY package.json package-lock.json ./ ← muda raramente
39
+ RUN npm ci ← reaproveitado enquanto o lock não muda
40
+ COPY . . ← muda a cada commit
41
+ RUN npm run build
42
+ ```
43
+
44
+ Com `COPY . .` antes do `npm ci`, qualquer commit reinstala tudo.
45
+
46
+ - **`npm ci`** e não `npm install`: instala exatamente o lockfile, apaga `node_modules` antes,
47
+ falha se `package.json` e lock divergirem (melhor quebrar no build do que subir versão diferente
48
+ da testada). Lockfile no repo é obrigatório.
49
+ - **`--mount=type=cache,target=/root/.npm`**: o cache de download fica no host do builder, fora da
50
+ imagem. Mesmo quando o lock muda, só o que é novo é baixado. `sharing=locked` evita dois builds
51
+ simultâneos corrompendo o cache. Como o cache não vai para a camada, `--no-cache-dir` (pip) é
52
+ desnecessário.
53
+ - **`--prefer-offline`**: usa o que está no cache sem revalidar cada pacote no registry (rede lenta
54
+ ou com proxy).
55
+ - **`--no-audit --no-fund`**: chamadas de rede e saída que não servem num build.
56
+ - **Cache do Angular** (`.angular/cache` montado + `cli.cache.environment: "all"`): partes que não
57
+ mudaram não são recompiladas.
58
+ - **ARG depois do install**: um `ARG` vira variável de ambiente de todos os `RUN` seguintes e entra na
59
+ chave de cache deles. `ARG CONFIGURATION` antes do `npm ci` faz cada ambiente reinstalar tudo.
60
+ - **Contexto pequeno** (`.dockerignore`): `.git` e `node_modules` locais mudam sempre e invalidam o
61
+ `COPY . .`, além de inflar o envio do contexto.
62
+
63
+ ## Sem credencial na imagem
64
+
65
+ Tudo que entra por `COPY`, `ARG` ou `ENV` fica recuperável por quem puxa a imagem:
66
+ - arquivo copiado e apagado num `RUN` seguinte continua na camada anterior;
67
+ - `ARG` aparece em `history` (o valor usado em cada `RUN`);
68
+ - `ENV` aparece em `inspect` e no ambiente do container.
69
+
70
+ Por isso: sem `COPY .npmrc`, sem `ARG NPM_TOKEN`, sem `ENV PIP_INDEX_URL=https://user:senha@...`.
71
+ As libs da plataforma são públicas, o build não precisa de credencial nenhuma. Se um dia precisar de
72
+ registry privado: `RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci` (o segredo existe só
73
+ durante aquele `RUN`, não vai para camada).
74
+
75
+ ## Segredo sem valor padrão
76
+
77
+ `ENV AGENT_TOKEN=changeme` (ou `os.getenv("AGENT_TOKEN", "changeme")`, `process.env.X ?? 'dev-secret'`) parece
78
+ inofensivo — "em produção a variável é cadastrada". Mas se o cadastro faltar, o serviço sobe **aceitando um
79
+ segredo que está no repositório e na imagem pública**, e ninguém percebe. O padrão é o inverso:
80
+
81
+ - nenhum segredo (token, senha, chave, `secret` do Orfeu) tem valor no Dockerfile nem no código;
82
+ - o serviço lê o segredo na subida e **falha no boot** sem ele, com mensagem que diz qual variável falta
83
+ (settings com campo obrigatório no Pydantic, zod `.min(1)` no Node);
84
+ - valor de desenvolvimento fica no `.env.local` (fora da imagem pelo `.dockerignore`), nunca como default.
85
+
86
+ ```python
87
+ # ERRADO: sobe com o segredo de exemplo se a variável não vier
88
+ AGENT_TOKEN = os.getenv("AGENT_TOKEN", "changeme")
89
+
90
+ # CERTO: sem a variável, o processo para na subida
91
+ AGENT_TOKEN = os.environ.get("AGENT_TOKEN", "")
92
+ if not AGENT_TOKEN:
93
+ raise RuntimeError("AGENT_TOKEN não definido: configure a variável no ambiente do container")
94
+ ```
95
+
96
+ ## Variáveis de ambiente por arquivo, não no argv
97
+
98
+ Quem **roda** containers por código (agente de deploy, script de CI) não monta `podman run -e K=V ...`
99
+ com os valores na linha de comando: o argv aparece em `ps` para qualquer usuário do host, em logs de
100
+ comando e em mensagens de erro que repetem o comando. Use `--env-file` com um arquivo temporário:
101
+
102
+ - criado com permissão **600** (`tempfile.mkstemp`, `fs.mkdtempSync` + `writeFileSync(..., { mode: 0o600 })`);
103
+ - apagado no `finally` (com ou sem erro), logo depois do `run` — o CLI lê o arquivo do lado do cliente e
104
+ manda as variáveis resolvidas ao engine, então ele só precisa existir durante o comando;
105
+ - validado antes de gravar: nome de variável sem espaço/`=`, valor sem quebra de linha (o formato do
106
+ `--env-file` é uma variável por linha, sem escape — uma quebra viraria outra variável).
107
+
108
+ ```python
109
+ @contextmanager
110
+ def env_file(pares):
111
+ conteudo = linhas_validadas(pares) # valida antes de criar qualquer arquivo
112
+ fd, caminho = tempfile.mkstemp(prefix="deploy-env-", suffix=".env") # 600
113
+ try:
114
+ with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
115
+ fh.write(conteudo)
116
+ yield caminho
117
+ finally:
118
+ with suppress(FileNotFoundError):
119
+ os.remove(caminho)
120
+
121
+ with env_file(env.items()) as caminho:
122
+ subprocess.run(["podman", "run", "-d", "--env-file", caminho, imagem], check=True)
123
+ ```
124
+
125
+ ## Nome que vira caminho: validar e conter
126
+
127
+ Serviço que recebe um nome (app, ambiente, serviço) e usa como pasta para clonar, gravar `.env` ou
128
+ `rmtree` precisa de duas defesas, **antes** de qualquer escrita ou remoção:
129
+
130
+ 1. **Nome**: só `[A-Za-z0-9._-]`, sem começar com `.` (`.` e `..` apontam para a própria raiz ou para o
131
+ pai), conferido com `fullmatch` — `re.match(r"...$")` aceita `"api\n"`.
132
+ 2. **Contenção**: `alvo = (raiz / nome).resolve()` e exija `raiz.resolve() in alvo.parents` (nem a própria
133
+ raiz, nem fora dela, nem via symlink). Sem isso, `service=".."` faz o `rmtree` apagar o pai da raiz.
134
+
135
+ ```python
136
+ def caminho_dentro(raiz: str, nome: str) -> Path:
137
+ if not re.fullmatch(r"[A-Za-z0-9._-]+", nome) or nome.startswith("."):
138
+ raise ValueError(f"nome inválido: {nome!r}")
139
+ base = Path(raiz).resolve()
140
+ alvo = (base / nome).resolve()
141
+ if alvo == base or base not in alvo.parents:
142
+ raise ValueError(f"nome inválido: {nome!r}")
143
+ return alvo
144
+ ```
145
+
146
+ ## Scripts `.sh` com fim de linha LF
147
+
148
+ Script de entrypoint ou de build salvo com CRLF (editado no Windows, `core.autocrlf=true`) quebra no
149
+ container: `/bin/sh^M: bad interpreter` ou `$'\r': command not found`. Fixe no repositório, não na máquina
150
+ de cada um:
151
+
152
+ ```gitattributes
153
+ # .gitattributes — scripts rodam em Linux
154
+ *.sh text eol=lf
155
+ ```
156
+
157
+ ## Sinais, PID 1 e forma exec
158
+
159
+ No `stop`, o engine manda **SIGTERM ao PID 1** do container, espera o prazo (10 s no Podman/Docker)
160
+ e manda SIGKILL. O que precisa acontecer nesse intervalo: parar de aceitar conexões, terminar as
161
+ requisições em andamento, **enviar a fila de auditoria do Orfeu** (`flushAudit()` / shutdown do
162
+ lifespan), fechar pool de banco.
163
+
164
+ | CMD | PID 1 | SIGTERM chega ao app? |
165
+ | --- | --- | --- |
166
+ | `CMD ["node", "dist/index.js"]` | node | sim |
167
+ | `CMD node dist/index.js` (shell form) | `/bin/sh -c` | não: o sh não repassa |
168
+ | `CMD ["npm", "start"]` | npm | não confiável: o npm não repassa como deveria e ainda soma um processo |
169
+ | `CMD ["sh", "-c", "uvicorn ..."]` | sh | não |
170
+ | `CMD ["sh", "-c", "exec uvicorn ..."]` | uvicorn (o `exec` substitui o sh) | sim |
171
+
172
+ Sintoma do erro: todo deploy/stop demora exatamente o prazo (10 s) e termina com código 137;
173
+ auditoria das últimas requisições não chega.
174
+
175
+ **Node como PID 1** não ganha as ações padrão do kernel para sinais: sem handler, SIGTERM e SIGINT
176
+ são **ignorados**. O app precisa de `process.once('SIGTERM', ...)` com timer de segurança
177
+ (`setTimeout(...).unref()`) menor que o prazo do stop. Alternativa: um init mínimo (`tini`,
178
+ `--init`) — dispensável quando o app trata o sinal e não cria processos filhos (o init também colhe
179
+ zumbis). Uvicorn trata SIGTERM sozinho e executa o shutdown do lifespan.
180
+
181
+ `sh -c` só é necessário para expandir variável (`$PORT`). Com porta fixa, use a forma exec pura.
182
+
183
+ ## Usuário não-root
184
+
185
+ Root no container é root no host em caso de fuga do container (em engine rootful) e pode escrever em
186
+ qualquer lugar da imagem. Com `USER`:
187
+ - as imagens `node` já têm o usuário `node` (uid 1000); em `python:slim`, crie um
188
+ (`useradd --system`);
189
+ - portas abaixo de 1024 exigem privilégio — use 3000/8000 etc. (o Caddy é quem fica na 443);
190
+ - arquivos copiados como root continuam legíveis; pasta em que o app **escreve** precisa de
191
+ `COPY --chown=...` ou `RUN chown`;
192
+ - coloque `USER` depois dos `RUN` que precisam de root (remover npm, `apt-get`, `useradd`).
193
+
194
+ ## HEALTHCHECK
195
+
196
+ Faz o engine marcar o container como `healthy`/`unhealthy` (visível no inventário e em `ps`).
197
+ - Use o que já existe na imagem: `wget` (busybox) no Alpine; `python -c urllib...` no slim — não
198
+ instale `curl` só para isso.
199
+ - Chame `127.0.0.1`, não o domínio, e inclua o prefixo do app no path.
200
+ - `--start-period` cobre a subida (conexões, registro no Argos).
201
+ - **Podman/Buildah** gravam `HEALTHCHECK` apenas em imagem formato `docker`; no formato OCI (padrão)
202
+ a instrução é descartada com aviso. E o deploy não espera `healthy` para concluir. Na prática o
203
+ `/health` do app é o que importa: é ele que você consulta depois do deploy (ver **hefesto**).
204
+
205
+ ## Porta
206
+
207
+ `ENV PORT=<porta>` + `EXPOSE <porta>` + o app lendo `PORT` e escutando em `0.0.0.0`. Escutar em
208
+ `127.0.0.1` só aceita conexões vindas de dentro do próprio container: o proxy na rede do servidor
209
+ recebe conexão recusada (502). `EXPOSE` não publica nada, só documenta; quem publica é o `-p` do
210
+ deploy. A porta do `ENV PORT` precisa bater com a cadastrada na plataforma.
211
+
212
+ ## ARG x ENV, build x runtime
213
+
214
+ | | Quando é lido | Fica na imagem | Use para |
215
+ | --- | --- | --- | --- |
216
+ | `ARG` | só durante o build | no histórico | o que muda o artefato: `CONFIGURATION` do Angular |
217
+ | `ENV` no Dockerfile | build e runtime | sim | padrões não sensíveis: `PORT`, `NODE_ENV`, `PYTHONUNBUFFERED`, caminhos internos |
218
+ | variável no deploy (`--env-file`/`-e`) | runtime | não | tudo que muda por ambiente ou é segredo: banco, URLs, identidade no Argos — segredo **sem** valor padrão no Dockerfile |
219
+
220
+ A mesma imagem deve poder rodar em qualquer ambiente trocando só as variáveis de runtime. A exceção
221
+ é o site Angular: o navegador não lê variável de ambiente do servidor, então endpoints e `baseHref`
222
+ entram no build (`CONFIGURATION`), e por isso há uma imagem por ambiente.
223
+
224
+ ## `.dockerignore`
225
+
226
+ - **`.git`**: o clone raso ainda tem a pasta `.git`; sem ignorar, o `COPY . .` leva o histórico para
227
+ a imagem.
228
+ - **`node_modules`, `.venv`**: as do host são de outro sistema operacional (binários nativos de
229
+ Windows/macOS) e sobrescreveriam as instaladas no build pelo `COPY . .`.
230
+ - **`dist`, `.angular`, `coverage`, caches**: artefatos locais que só invalidam cache.
231
+ - **`.env`, `.env.*` (menos `.env.example`)**: segredo local fora da imagem. Efeito colateral
232
+ desejado: no container o app **só** lê configuração do ambiente; se ele carrega
233
+ `.env.<APP_ENV>`, o arquivo não existe e cada valor precisa ser cadastrado como variável. Um app
234
+ que "funciona local e não sobe no container" geralmente é isso.
235
+ - **`tests`** (Python) e o próprio `Dockerfile`: não rodam em produção.
236
+ - Só o `.dockerignore` da **raiz do contexto** vale; em contexto com `ui/` + `server/`, use padrões
237
+ `**/`.
238
+
239
+ ## `timeout -k` nos passos longos
240
+
241
+ O builder (Podman/Buildah) só verifica cancelamento entre passos. Se um `npm ci` ou `ng build` trava
242
+ (rede, proxy), o cliente desiste mas o passo continua rodando no host do builder indefinidamente.
243
+ `timeout -k 10 600 npm ci` manda SIGTERM aos 600 s e SIGKILL 10 s depois — o build falha com
244
+ mensagem em vez de travar. Valores típicos: 600 s para download, 300 s para compilar.
245
+
246
+ ## Angular: estágio final `scratch` com `/dist`
247
+
248
+ A plataforma não roda um servidor web por app: o Caddy de cada servidor já está lá e serve os
249
+ arquivos com `file_server` (e fallback de SPA). A imagem é só o **pacote versionado** do build:
250
+ vai para o registry com tag e versão como qualquer outra, permite rollback e auditoria do que está
251
+ publicado, e o Talos extrai `/dist` sem nunca executá-la. Daí as convenções:
252
+ - estágio chamado `site` (é o `--target`);
253
+ - conteúdo em `/dist` na raiz;
254
+ - `CMD ["unused"]` porque criar um container exige comando no manifesto, e `scratch` não tem shell.
255
+
256
+ Ser o último estágio faz um `build` sem `--target` produzir a imagem `site`; para rodar o
257
+ dev-server localmente, `target: dev`. Budgets do `angular.json` com `maximumError` estourado fazem o
258
+ `ng build` falhar e, com ele, o build da imagem: reduza o bundle inicial em vez de subir o limite
259
+ (ver **angular**).
260
+
261
+ ## Python: `exec uvicorn` e workers
262
+
263
+ - `exec`: ver "Sinais". O uvicorn recebe o SIGTERM, para de aceitar conexões, espera as em andamento
264
+ e roda o shutdown do lifespan (onde o Orfeu envia a auditoria pendente).
265
+ - `PYTHONUNBUFFERED=1`: sem ele o stdout é bufferizado e os logs aparecem atrasados ou se perdem
266
+ quando o processo é morto.
267
+ - **`--workers N`** cria N processos, cada um com o app inteiro e **o lifespan inteiro**: tudo que o
268
+ startup dispara (agendador, coletor, consumidor de fila, `asyncio.create_task` em loop) roda N
269
+ vezes — escrita duplicada, chamadas externas em dobro, locks disputados. Também multiplica
270
+ memória e conexões de banco, e caches/rate limits em memória ficam por processo.
271
+ - Padrão: **um processo por container**; para escalar, mais réplicas (workers do Hefesto) — e, se
272
+ houver tarefa em background, separe o papel (`APP_ROLE=api` com réplicas, um único processo de
273
+ tarefas) ou proteja cada ciclo com lock distribuído. Ver **fastapi** e **hefesto**.
274
+
275
+ ## Podman/Buildah x Docker
276
+
277
+ O build da plataforma usa `podman build` (Buildah). Para o Dockerfile, as diferenças que importam:
278
+ - `RUN --mount=type=cache|secret` funciona nos dois;
279
+ - estágios independentes rodam em paralelo com `--jobs` — vale separar build da UI e do servidor em
280
+ estágios sem dependência entre si;
281
+ - `HEALTHCHECK` só é gravado no formato `docker` (ver acima);
282
+ - o `.dockerignore` (ou `.containerignore`) da raiz do contexto é respeitado.
@@ -0,0 +1,146 @@
1
+ ---
2
+ name: documentacao
3
+ description: "Documentação das telas Angular ligadas ao shell @trismegisto/spine: README.md de uso e ESPECIFICACAO.md técnica por tela, a ligação no campo document do features.routes.ts, o loader .md e o registro de revisão. Use ao criar ou alterar uma tela, rota ou componente de feature Angular, ao revisar a documentação de uma tela e antes de dar uma tela por terminada. Estrutura e rotas do app são da skill angular; a interface (hm-*), da trismegisto."
4
+ ---
5
+
6
+ # documentacao — manual de cada tela
7
+
8
+ Cada tela do app tem um manual que abre pelo botão de documentação da barra da página (spine). O texto
9
+ mora **ao lado do componente**, é markdown cru e vai no chunk lazy da própria tela. Esta skill diz como
10
+ escrever esse manual, como ligá-lo na rota e como garantir que ele continua dizendo a verdade quando a
11
+ tela muda.
12
+
13
+ Divisão de trabalho: registro da tela, `router_id` e build são da skill **angular**; componentes e
14
+ rótulos da interface, da **trismegisto**. Aqui fica só o que é documentação.
15
+
16
+ > **Antes de dar por terminado:** `node scripts/checar.mjs <pasta-do-app>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/documentacao/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
17
+
18
+ ## 1. A regra
19
+
20
+ **Mudou a tela, revise a doc.** Mexeu em `.ts`, `.html` ou `.scss` da pasta de uma feature documentada:
21
+
22
+ 1. Releia o `README.md` (e a `ESPECIFICACAO.md`, se houver) com a tela nova na cabeça.
23
+ 2. **Atualize** se mudou algo que o usuário vê (ação, rótulo, coluna, filtro, estado, mensagem,
24
+ permissão) ou algo que a especificação descreve (origem dos dados, regra, o que a tela decide).
25
+ Refatoração interna, troca de estilo sem efeito visível e teste novo não pedem mudança no texto.
26
+ 3. **Registre a revisão**: `node scripts/checar.mjs <app> --registrar-revisao <pasta-da-feature>`.
27
+
28
+ O registro de revisão grava em `src/app/features/.documentacao.json` o hash dos `.ts`/`.html`/`.scss` da pasta
29
+ (sem `.spec.ts`, sem `.md`, CRLF normalizado) — e também da pasta do documento, quando a tela é um
30
+ invólucro que reaproveita a lista de outra pasta e o README mora lá. Service ou componente compartilhado
31
+ fora dessas pastas não entra: aí quem pega é o `revisor-documentacao`. Na próxima mudança o hash muda e o verificador acusa
32
+ `documentacao-desatualizada` até alguém revisar de novo. **Registre a revisão só depois de revisar de verdade** —
33
+ registrar para calar o verificador é deixar a doc mentir com aval.
34
+
35
+ O `.documentacao.json` é commitado junto com a mudança da tela; num PR, a linha alterada nele mostra que a
36
+ doc foi revista.
37
+
38
+ ## 2. O padrão
39
+
40
+ Na pasta da tela (`src/app/features/<tela>/`):
41
+
42
+ | Arquivo | Para quem | Obrigatório |
43
+ | --- | --- | --- |
44
+ | `README.md` | quem **usa** a tela | sim |
45
+ | `ESPECIFICACAO.md` | quem **desenvolve** (aba "Especificação técnica", só com `technicalDocs`) | não |
46
+
47
+ **`README.md`**, em português, curto, na voz de quem opera:
48
+
49
+ - `# <nome da tela>` — o mesmo nome do menu;
50
+ - uma ou duas frases dizendo para que a tela serve;
51
+ - `## Como usar` em passos numerados (ou lista curta), com os rótulos **exatamente** como aparecem na
52
+ tela, em negrito: "Clique em **Novo pedido**", "na aba **Faturados**";
53
+ - tabela de status ou legenda quando a tela mostra estados, cores ou ícones com significado;
54
+ - uma dica final em `>` (o erro mais comum, o que acontece de irreversível, onde fica o cadastro).
55
+
56
+ Modelo comentado: `references/modelo-readme.md`.
57
+
58
+ **`ESPECIFICACAO.md`**, quando há regra que não cabe no manual: origem dos dados (serviço, query,
59
+ tabela), regras de negócio, **o que a tela decide e o que fica com o servidor** (permissão, validação
60
+ final, cálculo). Modelo: `references/modelo-especificacao.md`.
61
+
62
+ O renderizador do spine é markdown GFM sanitizado: títulos, listas, tabelas, citação, código e links
63
+ funcionam; HTML cru é filtrado, imagem e link relativo para outro `.md` não resolvem. Detalhes no modelo.
64
+
65
+ ## 3. A ligação
66
+
67
+ ```ts
68
+ // src/app/features/features.routes.ts
69
+ {
70
+ id: '<router_id>',
71
+ load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
72
+ document: {
73
+ load: () => import('src/app/features/pedidos/README.md').then(m => m.default),
74
+ loadTechnical: () => import('src/app/features/pedidos/ESPECIFICACAO.md').then(m => m.default), // se existir
75
+ },
76
+ },
77
+ ```
78
+
79
+ E no app, uma vez só:
80
+
81
+ - `angular.json`: `"loader": { ".md": "text" }` em `build.options` **e** em `test.options` (senão o
82
+ teste de rotas não consegue importar o README);
83
+ - `src/markdown.d.ts` com `declare module '*.md' { const content: string; export default content; }`;
84
+ - um teste de rotas que chama `document.load()`/`loadTechnical()` de cada rota e confere texto não vazio.
85
+
86
+ Passo a passo para um app que ainda não tem nada disso: `references/ligar-app-novo.md`.
87
+
88
+ ## 4. O verificador
89
+
90
+ ```bash
91
+ node scripts/checar.mjs <pasta-do-app> # ou o próprio features.routes.ts
92
+ node scripts/checar.mjs <pasta-do-app> --json
93
+ node scripts/checar.mjs <pasta-do-app> --registrar-revisao pedidos # depois de revisar; ou --registrar-revisao todas
94
+ ```
95
+
96
+ | Regra | O que acusa |
97
+ | --- | --- |
98
+ | `rota-sem-documento` | rota com `load` de tela e sem `document` |
99
+ | `documento-inexistente` | `import()` de `.md` (inclusive `loadTechnical`) para arquivo que não existe |
100
+ | `especificacao-desligada` | `ESPECIFICACAO.md` na pasta da tela, rota sem `loadTechnical` |
101
+ | `readme-fora-do-padrao` | README vazio, sem `# ` ou sem `## Como usar` |
102
+ | `rotulo-inexistente` | "clique em **X**", "botão **X**", "aba **X**" cujo texto não está nos templates da pasta |
103
+ | `md-sem-loader` | `document` sem loader `.md` no build/test ou sem a declaração `*.md` |
104
+ | `documentacao-desatualizada` | tela documentada fora do `.documentacao.json` ou com hash diferente |
105
+
106
+ Fluxo de uso:
107
+
108
+ 1. Rode o verificador sobre o app depois de mexer numa tela.
109
+ 2. Regras estruturais (as seis primeiras): corrija o que ele apontou.
110
+ 3. `documentacao-desatualizada`: abra a tela e a doc lado a lado e siga `references/checklist-coerencia.md`
111
+ (ou peça ao subagente `revisor-documentacao`, que faz essa leitura e diz o que mudar).
112
+ 4. Atualize o texto se for o caso e só então registre a revisão da feature.
113
+
114
+ Exceção consciente, na linha anterior e sempre com motivo:
115
+
116
+ ```ts
117
+ // acropole-ignore-next-line rota-sem-documento -- tela de diagnóstico, só para quem mantém o app
118
+ load: () => import('./interna/interna.component').then(m => m.InternaComponent),
119
+ ```
120
+
121
+ ```md
122
+ <!-- acropole-ignore-next-line rotulo-inexistente -- o botão é do shell, não da tela -->
123
+ > Use o botão **Favoritar** da barra da página.
124
+ ```
125
+
126
+ O verificador nunca escreve nada sem `--registrar-revisao`, e com ele escreve só o `.documentacao.json`.
127
+
128
+ ## 5. Armadilhas
129
+
130
+ - **Rótulo inventado.** O README é lido com a tela aberta ao lado: botão que não existe com aquele nome
131
+ faz a pessoa procurar à toa. Copie o texto do template, não do nome do método.
132
+ - **Duas rotas na mesma pasta** (ex.: visão completa e visão de operador): a pasta tem um registro de revisão só,
133
+ mas cada rota precisa do próprio `document` — o mesmo README pode servir as duas, com a diferença
134
+ explicada nele.
135
+ - **Doc descrevendo permissão como regra da tela.** Quem pode ver ou fazer é decidido no servidor; o
136
+ README diz o efeito ("só aparecem as aplicações dos seus grupos"), a especificação diz onde é decidido.
137
+ - **Caminho de menu** ("Infraestrutura > Origens") não é rótulo da tela: fica em negrito sem "clique em".
138
+
139
+ ## 6. Referências
140
+
141
+ | Arquivo | Quando ler |
142
+ | --- | --- |
143
+ | `references/modelo-readme.md` | Ao escrever ou reescrever o manual de uma tela |
144
+ | `references/modelo-especificacao.md` | Quando a tela tem regra, origem de dados ou divisão tela/servidor que valha registrar |
145
+ | `references/checklist-coerencia.md` | Ao revisar uma doc contra a tela (antes de registrar a revisão) |
146
+ | `references/ligar-app-novo.md` | App que ainda não tem documentação de tela (loader, `markdown.d.ts`, teste de rotas, primeiro registro de revisão) |
@@ -0,0 +1,59 @@
1
+ # Checklist de coerência: a doc ainda descreve a tela?
2
+
3
+ Use quando o verificador acusar `documentacao-desatualizada` ou ao revisar uma tela à mão. Abra lado a
4
+ lado: o template (`.html` ou `template:` inline) e o `.ts` da pasta da feature, e o `README.md`/
5
+ `ESPECIFICACAO.md`. Quando possível, olhe o que mudou (`git diff` da pasta) antes de reler tudo.
6
+
7
+ ## 1. Ações
8
+
9
+ - [ ] Todo botão, item de menu e ação de linha citado no README existe, com o mesmo rótulo.
10
+ - [ ] Ação nova que a pessoa precisa conhecer (principalmente as destrutivas ou irreversíveis) está no
11
+ README.
12
+ - [ ] Ação removida saiu do README.
13
+ - [ ] A ordem dos passos ainda é a ordem possível na tela (ex.: o seletor de projeto continua antes da lista).
14
+
15
+ ## 2. Rótulos e textos
16
+
17
+ - [ ] Nome da tela no `#` igual ao do menu.
18
+ - [ ] Abas, seções, títulos de modal e campos citados batem com o template (maiúsculas incluídas).
19
+ - [ ] Mensagens citadas (aviso, confirmação, estado vazio) ainda são essas.
20
+
21
+ ## 3. Estados
22
+
23
+ - [ ] Tabela de status/legenda tem exatamente os estados que a tela mostra (rótulo e significado).
24
+ - [ ] Estados de carregamento, vazio e erro descritos (se o README fala deles) batem com o template.
25
+ - [ ] Cores ou ícones com significado citados ainda são os mesmos.
26
+
27
+ ## 4. Colunas e filtros
28
+
29
+ - [ ] Colunas citadas existem; coluna nova importante está explicada.
30
+ - [ ] Filtros e busca: campos pesquisados ("por nome, tag ou status") são os que o código filtra de fato.
31
+ - [ ] Ordenação padrão e paginação, se citadas, conferem.
32
+
33
+ ## 5. Permissões e visões
34
+
35
+ - [ ] Diferença entre visões (operador, administrador, somente leitura) descrita como efeito.
36
+ - [ ] Ação que passou a depender de permissão está mencionada ("só aparece para quem...").
37
+ - [ ] Nada no README promete que a tela barra algo que só o servidor barra.
38
+
39
+ ## 6. Especificação (se existir)
40
+
41
+ - [ ] Origem dos dados: serviço, query/mutation ou rota continuam os que o `.ts` chama.
42
+ - [ ] Regras descritas ainda são as aplicadas (validações, limites, intervalos de atualização).
43
+ - [ ] "O que a tela decide / o que fica com o servidor" continua verdadeiro.
44
+ - [ ] Está ligada na rota (`loadTechnical`).
45
+
46
+ ## 7. Decisão
47
+
48
+ | Situação | O que fazer |
49
+ | --- | --- |
50
+ | Mudança só interna (refatoração, estilo sem efeito visível, tipagem) | Nada no texto; registre a revisão |
51
+ | Mudou algo visível ou descrito | Atualize o README/ESPECIFICACAO; depois registre a revisão |
52
+ | Dúvida se a mudança é visível | Rode a tela ou pergunte; não registre a revisão no escuro |
53
+ | A doc estava errada antes da mudança | Corrija também; o registro de revisão atesta a doc inteira, não só o diff |
54
+
55
+ Registro da revisão, depois de revisar:
56
+
57
+ ```bash
58
+ node <skill documentacao>/scripts/checar.mjs <pasta-do-app> --registrar-revisao <pasta-da-feature>
59
+ ```
@@ -0,0 +1,107 @@
1
+ # Ligar a documentação de telas num app
2
+
3
+ Para um app Angular com `@trismegisto/spine` que ainda não tem documentação de tela. Uma vez por app;
4
+ depois, cada tela nova só precisa do README e do `document` na rota.
5
+
6
+ ## 1. Loader `.md` no `angular.json`
7
+
8
+ Importar um `.md` precisa devolver o texto cru. Nos dois targets, em `options`:
9
+
10
+ ```json
11
+ "build": {
12
+ "builder": "@angular/build:application",
13
+ "options": {
14
+ "loader": { ".md": "text" }
15
+ }
16
+ },
17
+ "test": {
18
+ "builder": "@angular/build:karma",
19
+ "options": {
20
+ "loader": { ".md": "text" }
21
+ }
22
+ }
23
+ ```
24
+
25
+ Sem o do `test`, o build passa e o teste de rotas quebra ao importar o README. Com o builder
26
+ `@angular/build:unit-test` (que herda as opções do `buildTarget`), basta o do build.
27
+
28
+ ## 2. Declaração de tipo
29
+
30
+ `src/markdown.d.ts` (precisa estar coberto pelo `include`/`files` do `tsconfig.app.json` e do
31
+ `tsconfig.spec.json`; em `src/` normalmente já está):
32
+
33
+ ```ts
34
+ // Loader `.md: "text"` (angular.json): importar um .md devolve o texto cru — documentação das telas.
35
+ declare module '*.md' {
36
+ const content: string;
37
+ export default content;
38
+ }
39
+ ```
40
+
41
+ ## 3. Rota com `document`
42
+
43
+ ```ts
44
+ {
45
+ id: '<router_id>',
46
+ load: () => import('src/app/features/pedidos/pedidos.component').then(m => m.PedidosComponent),
47
+ document: {
48
+ load: () => import('src/app/features/pedidos/README.md').then(m => m.default),
49
+ // loadTechnical: () => import('src/app/features/pedidos/ESPECIFICACAO.md').then(m => m.default),
50
+ // title/group: opcionais; sem eles valem o nome da rota e o módulo da árvore do Argos
51
+ },
52
+ },
53
+ ```
54
+
55
+ O `import()` precisa ser literal (o bundler gera o chunk a partir dele). Não monte o caminho em
56
+ variável. O texto só é baixado quando alguém abre a documentação.
57
+
58
+ A aba técnica aparece conforme `provideUi({ technicalDocs })` (padrão `isDevMode()`).
59
+
60
+ ## 4. Teste de rotas
61
+
62
+ Em `src/app/features/features.routes.spec.ts`, ao lado das conferências de `id` e `load`:
63
+
64
+ ```ts
65
+ it('documentação (README e especificação técnica) carrega como texto não vazio', async () => {
66
+ for (const route of components.filter(c => c.document)) {
67
+ const doc = route.document!;
68
+ const readme = await doc.load();
69
+ expect(typeof readme).withContext(route.id ?? '').toBe('string');
70
+ expect(readme.trim().length).withContext(route.id ?? '').toBeGreaterThan(0);
71
+ if (doc.loadTechnical) {
72
+ expect((await doc.loadTechnical()).trim().length).withContext(route.id ?? '').toBeGreaterThan(0);
73
+ }
74
+ }
75
+ });
76
+ ```
77
+
78
+ ## 5. Primeiro registro de revisão
79
+
80
+ Escreva os READMEs (`modelo-readme.md`), rode o verificador até sobrar só
81
+ `documentacao-desatualizada`, revise cada doc contra a tela (`checklist-coerencia.md`) e registre a revisão:
82
+
83
+ ```bash
84
+ node <skill documentacao>/scripts/checar.mjs <pasta-do-app>
85
+ node <skill documentacao>/scripts/checar.mjs <pasta-do-app> --registrar-revisao todas
86
+ ```
87
+
88
+ Isso cria `src/app/features/.documentacao.json` (chaves ordenadas, uma por pasta de tela documentada).
89
+ Commite junto. A partir daí, cada mudança numa tela documentada volta a acusar até a doc ser revista.
90
+
91
+ ## 6. Telas sem documentação de propósito
92
+
93
+ Tela técnica ou interna que não precisa de manual: marque a rota com a exceção, com motivo:
94
+
95
+ ```ts
96
+ // acropole-ignore-next-line rota-sem-documento -- tela de diagnóstico, só para quem mantém o app
97
+ load: () => import('./interna/interna.component').then(m => m.InternaComponent),
98
+ ```
99
+
100
+ ## 7. Opcional: no CI ou num hook
101
+
102
+ ```bash
103
+ node <skill documentacao>/scripts/checar.mjs <pasta-do-app> --json
104
+ ```
105
+
106
+ Sai com código 1 quando acha algo. Num PR, uma tela alterada sem a linha correspondente do
107
+ `.documentacao.json` alterada é sinal de que a doc não foi revista.
@@ -0,0 +1,51 @@
1
+ # Modelo de ESPECIFICACAO de tela
2
+
3
+ A `ESPECIFICACAO.md` é para quem **desenvolve** ou dá suporte à tela. Aparece na aba "Especificação
4
+ técnica" do modal de documentação, que o spine só mostra com `SpineConfig.technicalDocs` (padrão: fora
5
+ de produção). É opcional: escreva quando houver regra, origem de dados ou divisão tela/servidor que não
6
+ seja óbvia lendo o componente.
7
+
8
+ Existindo o arquivo, ligue-o na rota com `loadTechnical` — o verificador acusa
9
+ `especificacao-desligada` se ele estiver na pasta e fora da rota.
10
+
11
+ ## Esqueleto
12
+
13
+ ```md
14
+ # <Nome da tela> — especificação técnica
15
+
16
+ ## Origem dos dados
17
+
18
+ | Dado | Fonte |
19
+ | --- | --- |
20
+ | <Lista de pedidos> | <serviço/GraphQL `vendas`, query `pedidos`> |
21
+ | <Totais do cabeçalho> | <calculados na tela a partir da lista> |
22
+
23
+ ## Regras
24
+
25
+ - <Regra de negócio que a tela aplica ou exibe, com o caso de borda.>
26
+ - <Ordenação padrão, paginação, limite, atualização automática (intervalo).>
27
+
28
+ ## O que a tela decide
29
+
30
+ - <Só apresentação: filtros, aba, seleção, quais modais abrir.>
31
+
32
+ ## O que fica com o servidor
33
+
34
+ - <Permissão (quem vê, quem executa), validação final, cálculo oficial, auditoria.>
35
+ ```
36
+
37
+ ## O que entra e o que não entra
38
+
39
+ | Entra | Não entra |
40
+ | --- | --- |
41
+ | serviço, query/mutation, rota REST, tabela de origem | passo a passo de uso (é do README) |
42
+ | regra de negócio e caso de borda que a tela trata | segredo, credencial, URL interna, IP |
43
+ | o que a tela decide e o que só o servidor decide | código copiado do componente |
44
+ | eventos/subscriptions e intervalos de atualização | histórico de mudanças (é do git) |
45
+ | dependência de outra tela ou cadastro | nome de pessoa ou equipe |
46
+
47
+ A seção **"o que a tela decide / o que fica com o servidor"** é a mais útil: evita que alguém "corrija"
48
+ uma permissão escondendo um botão no front, e diz onde procurar quando o comportamento muda.
49
+
50
+ Caminho de arquivo do backend pode aparecer (ajuda quem vai mexer), mas fica velho fácil: prefira o nome
51
+ do módulo ou da operação.