@acropole/skills 1.6.1 → 1.7.1

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 (37) hide show
  1. package/README.md +10 -8
  2. package/agents/revisor-deploy.md +9 -4
  3. package/bin/install.js +41 -9
  4. package/package.json +1 -1
  5. package/skills/acropole/SKILL.md +2 -2
  6. package/skills/acropole/references/arquitetura.md +3 -3
  7. package/skills/acropole/references/fluxos/app-novo.md +2 -2
  8. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +51 -15
  9. package/skills/angular/SKILL.md +34 -15
  10. package/skills/angular/references/armadilhas.md +16 -6
  11. package/skills/angular/references/estrutura.md +118 -50
  12. package/skills/angular/references/testes-build.md +25 -17
  13. package/skills/auto-servico/references/roteiros.md +1 -1
  14. package/skills/auto-servico/references/tools.md +1 -1
  15. package/skills/docker/SKILL.md +17 -7
  16. package/skills/docker/references/modelos.md +23 -9
  17. package/skills/docker/references/porques.md +19 -6
  18. package/skills/hefesto/SKILL.md +53 -28
  19. package/skills/hefesto/references/conceitos.md +16 -8
  20. package/skills/hefesto/references/diagnostico.md +12 -2
  21. package/skills/hefesto/references/fluxo.md +51 -29
  22. package/skills/hefesto/references/mcp-roteiros.md +52 -9
  23. package/skills/hefesto/references/preparar-app.md +22 -6
  24. package/skills/orquestracao/SKILL.md +3 -1
  25. package/skills/orquestracao/scripts/coord.sh +10 -2
  26. package/skills/trismegisto/SKILL.md +57 -16
  27. package/skills/trismegisto/references/angular-api.md +3666 -64
  28. package/skills/trismegisto/references/angular-exports.md +8562 -2554
  29. package/skills/trismegisto/references/angular-recipes.md +315 -0
  30. package/skills/trismegisto/references/angular-types.md +92 -0
  31. package/skills/trismegisto/references/angular.md +67 -10
  32. package/skills/trismegisto/references/catalogo/icones.json +7 -0
  33. package/skills/trismegisto/references/catalogo/seletores.json +12102 -3443
  34. package/skills/trismegisto/references/catalogo/tokens.json +114 -0
  35. package/skills/trismegisto/references/spine-api.md +1113 -157
  36. package/skills/trismegisto/references/spine-recipes.md +72 -35
  37. package/skills/trismegisto/references/spine.md +54 -27
@@ -4,8 +4,9 @@
4
4
 
5
5
  | Pasta | Conteúdo |
6
6
  | --- | --- |
7
- | `src/main.ts` | Ajuste do environment em runtime + `bootstrapApplication(CoreComponent, appConfig)` |
8
- | `src/core/` | `app.config.ts`, `core.providers.ts`, `core.component.ts` (raiz), `environments/`, e o que for global do app (ex.: `app.routes.ts` quando há rota pública, `news.ts` para novidades do shell) |
7
+ | `src/main.ts` | `config.json` do ambiente (`loadRuntimeConfig`) + ajuste do environment em runtime + import dinâmico e `bootstrapApplication(CoreComponent, appConfig)` |
8
+ | `src/core/` | `app.config.ts`, `core.providers.ts`, `core.component.ts` (raiz), `environments/` (interface + **um** `environment.ts`), e o que for global do app (ex.: `app.routes.ts` quando há rota pública, `news.ts` para novidades do shell) |
9
+ | `src/brand/` | A **instalação**: `brand.ts` (nome, título, logos, favicon), `theme.ts`/`theme.scss`, `providers.ts` (quando o app tem provedores de login a exibir), `assets/` (publicados em `brand/`) e `config/<ambiente>.json`. Não é sincronizada entre instalações: cada uma tem a sua |
9
10
  | `src/app/features/<tela>/` | Uma pasta por tela (componente principal, subcomponentes, modais, `README.md` de uso) |
10
11
  | `src/app/features/features.routes.ts` | O mapa `router_id` -> tela lazy (ver `features.md`) |
11
12
  | `src/app/services/<dominio>/` | Contrato de dados do domínio: `<dominio>.graphql`, `<dominio>.service.ts`, `<dominio>.models.ts`, `<dominio>.generated.ts` |
@@ -13,6 +14,7 @@
13
14
  | `src/shared/` | Componentes, pipes e utilitários usados por mais de uma tela do app |
14
15
  | `src/assets/` | `images/logo.svg`, `images/favicon.svg`, `favicon.ico`, fontes e tema próprio (`assets/theme/`) |
15
16
  | `src/testing/` | Helpers de spec (envelopes falsos, nome da operação) |
17
+ | `scripts/use-config.mjs` | Escolhe o ambiente do `ng serve` (copia `src/brand/config/<amb>.json` para `src/config.json`) |
16
18
 
17
19
  Regras:
18
20
  - **Services de dados ficam em `src/app/services/`**, não dentro da pasta da tela — a tela importa o
@@ -36,37 +38,59 @@ Regras:
36
38
  ## `main.ts`
37
39
 
38
40
  ```ts
41
+ import { isDevMode } from '@angular/core';
39
42
  import { bootstrapApplication } from '@angular/platform-browser';
40
43
  import { registerLocaleData } from '@angular/common';
41
44
  import localePt from '@angular/common/locales/pt';
42
- import { applyRuntimeEnvironment } from '@trismegisto/spine';
45
+ import { applyRuntimeEnvironment, loadRuntimeConfig } from '@trismegisto/spine';
43
46
 
44
- import { CoreComponent } from 'src/core/core.component';
45
- import { appConfig } from 'src/core/app.config';
46
47
  import { environment } from 'src/core/environments/environment';
47
48
 
48
49
  // Necessário se alguma tela usa DatePipe/CurrencyPipe com 'pt-BR' (senão NG0701).
49
50
  registerLocaleData(localePt);
50
51
 
51
- // Callback/logoff/authority/GraphQL derivados de onde o app está rodando.
52
- const { origin, basePath, behindProxy, unset } = applyRuntimeEnvironment(environment);
53
-
54
- // Só se o app tiver uma URL própria além das que o spine deriva (ex.: uma API REST no mesmo prefixo).
55
- if (behindProxy && unset(environment.minhaApiUrl)) {
56
- environment.minhaApiUrl = `${origin}${basePath}/server`;
57
- }
58
-
59
- bootstrapApplication(CoreComponent, appConfig)
60
- .then(() => document.getElementById('app-loading')?.remove())
52
+ // Imagem única: o ambiente vem do config.json ao lado do index.html (cópia de src/brand/config/<amb>.json,
53
+ // feita pelo deploy ou pelo scripts/use-config.mjs). Obrigatório no build de produção; no ng serve só avisa.
54
+ loadRuntimeConfig(environment, { required: !isDevMode() })
55
+ .then(async () => {
56
+ // Callback/logoff/authority/GraphQL derivados de onde o app está rodando.
57
+ const { origin, basePath, behindProxy, unset } = applyRuntimeEnvironment(environment);
58
+
59
+ // Só se o app tiver uma URL própria além das que o spine deriva (ex.: uma API REST no mesmo prefixo).
60
+ if (behindProxy && unset(environment.minhaApiUrl)) {
61
+ environment.minhaApiUrl = `${origin}${basePath}/server`;
62
+ }
63
+
64
+ // Import dinâmico: app.config/CoreComponent leem o environment ao carregar; um import estático rodaria
65
+ // antes do config.json chegar.
66
+ const [{ CoreComponent }, { appConfig }] = await Promise.all([
67
+ import('src/core/core.component'),
68
+ import('src/core/app.config'),
69
+ ]);
70
+ await bootstrapApplication(CoreComponent, appConfig);
71
+ document.getElementById('app-loading')?.remove();
72
+ })
61
73
  .catch((err) => console.error(err));
62
74
  ```
63
75
 
76
+ - `loadRuntimeConfig(environment, { file?, required? })` (do `@trismegisto/primitives`, reexportado pelo
77
+ `@trismegisto/spine`) busca `config.json` (ou `file`) relativo ao `<base href>` e o mescla no objeto
78
+ `environment`: objetos chave a chave, arrays e valores simples substituem. Com `required`, falta ou JSON
79
+ inválido rejeita a promise (o app não sobe: erro de deploy); sem, só avisa no console.
80
+ - `required: !isDevMode()`, **não** `environment.production`: o `production` também vem do `config.json`, então
81
+ só está certo depois dele.
82
+ - **Sem top-level await** no `main.ts`: o Angular não o aceita com Zone.js. Encadeie com `.then`.
83
+ - **Import dinâmico** de `app.config` e do componente raiz quando algum módulo lê o `environment` no carregamento
84
+ (ex.: `clientId`/URL num provider montado no topo do arquivo). Se nenhum lê, import estático é seguro — mas o
85
+ primeiro que passar a ler quebra em silêncio (fica com o valor vazio do build); prefira o dinâmico.
64
86
  - `applyRuntimeEnvironment` sempre reescreve `redirectUrl` (`<origem><prefixo>/callback`) e
65
87
  `postLogoutRedirectUri` (`.../logoff`). Atrás de proxy (URL sem porta) também deriva `authority` e
66
88
  cada endpoint GraphQL **ainda sem valor real** (vazio ou contendo `CHANGE_ME`). URL explícita no
67
- environment sempre ganha.
89
+ `config.json` sempre ganha. Chame **depois** do `loadRuntimeConfig`.
68
90
  - Mexa no objeto `environment` **só aqui, antes do bootstrap**. Valor que precisa ser recalculado
69
91
  depois e lido por serviços em chunks lazy vai num `InjectionToken`, não em mutação do environment.
92
+ - App sem o shell (ex.: uma tela de login que é o próprio provedor OAuth) importa `loadRuntimeConfig` direto do
93
+ `@trismegisto/primitives` e não usa `applyRuntimeEnvironment` (que deriva a config de um client OAuth).
70
94
  - A remoção do `#app-loading` (definido no `index.html`) é opcional, mas recomendada.
71
95
 
72
96
  ## `src/core/app.config.ts`
@@ -153,17 +177,39 @@ export class CoreComponent {}
153
177
  Não monte modal/side panel/notificação do shell aqui: o layout do spine já os renderiza. O título da
154
178
  aba vem do `index.html` (ou `Title` no componente, se precisar mudar em runtime).
155
179
 
156
- ## Environments
180
+ ## Environment e `src/brand/config/` (imagem única)
157
181
 
158
- Arquivos em `src/core/environments/`:
182
+ A imagem é **uma por versão** (build `production` do master), a mesma em homologação e produção. Nada de
183
+ environment por ambiente no build:
159
184
 
160
185
  | Arquivo | Uso |
161
186
  | --- | --- |
162
- | `environment.config.ts` | Interface `Environment` |
163
- | `environment.ts` | Base (é o que os imports referenciam) |
164
- | `environment.prod.ts`, `.homol.ts`, `.dev.ts`, `.local.ts` | Trocados por `fileReplacements` na configuração de build homônima |
187
+ | `src/core/environments/environment.config.ts` | Interface `Environment` |
188
+ | `src/core/environments/environment.ts` | **Único**: o que é igual em toda parte (`clientId`, `realmId`, `scope`, `production: false`) e URLs vazias |
189
+ | `src/brand/config/<ambiente>.json` | **Só o que muda** naquele ambiente (URLs, `production: true` em homol/prod), mesclado em runtime |
190
+ | `src/config.json` | Cópia local do ambiente escolhido para o `ng serve` (`scripts/use-config.mjs`); no `.gitignore` e no `.dockerignore` |
191
+
192
+ Exemplo de `src/brand/config/homol.json` (só o que difere do `environment.ts`):
193
+
194
+ ```json
195
+ {
196
+ "production": true,
197
+ "adminApi": "https://homol.exemplo.com/argos/admin/api",
198
+ "authorizationServer": { "authority": "https://homol.exemplo.com/argos" },
199
+ "graphql": {
200
+ "pedidos": { "http": "https://homol.exemplo.com/app-exemplo/graphql", "ws": "wss://homol.exemplo.com/app-exemplo/graphql" }
201
+ }
202
+ }
203
+ ```
165
204
 
166
- Campos (só os nomes; os valores são de cada ambiente):
205
+ Quem escolhe o arquivo:
206
+ - **Deploy de site**: o talos copia `brand/config/<ambiente>.json` para `config.json` no site publicado.
207
+ - **Front servido por um servidor do app** (service com UI): o container recebe `APP_ENV=<ambiente>` e o servidor
208
+ serve `<prefixo>/config.json` a partir de `brand/config/${APP_ENV}.json` (lido e validado na subida; em produção,
209
+ `APP_ENV` ausente ou arquivo inexistente derruba a subida).
210
+ - **`ng serve`**: `node scripts/use-config.mjs <ambiente>` (os scripts `start*` já chamam).
211
+
212
+ Campos da interface (só os nomes):
167
213
 
168
214
  ```ts
169
215
  import type { AuthConfig } from '@orfeu/angular'; // não redeclarar
@@ -180,16 +226,21 @@ export interface Environment {
180
226
  - O tipo do login é o `AuthConfig` da própria lib. Campos que ela não lê (`silentRenew`, `useRefreshToken`,
181
227
  `postLogoutRedirectUri`, `responseType`) não entram no environment: são configuração morta — a renovação
182
228
  é 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
-
229
+ - Ambientes da instalação = arquivos em `src/brand/config/` (`local`, `dev`, `homol`, `prod`, os que existirem).
230
+ Nome em minúsculas, `a-z0-9-` (vira nome de arquivo no deploy).
231
+ - `config/<ambiente>.json` traz **só** o que varia. `clientId`, `realmId`, `scope`, `redirectUrl` e `namedClient`
232
+ ficam no `environment.ts`.
185
233
  - A chave de `graphql` e o `namedClient` costumam ser o mesmo nome (`pedidos: { namedClient: 'pedidos', ... }`).
186
- - Use `CHANGE_ME` em URL que deve ser derivada em runtime atrás do proxy.
187
- - Segredo nunca entra em environment: tudo ali vai para o bundle público.
188
- - Layout antigo `src/environments/` (fora de `core/`) e nomes de campo diferentes (`auth` em vez de
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.
234
+ - URL vazia (ou `CHANGE_ME`) no `environment.ts` = derivada em runtime atrás do proxy; URL explícita no
235
+ `config.json` sempre ganha.
236
+ - Segredo nunca entra em environment nem em `config/*.json`: tudo ali vai para o navegador.
237
+ - Layouts antigos (`environment.<amb>.ts` trocados por `fileReplacements`, `src/environments/` fora de `core/`,
238
+ `auth` em vez de `authorizationServer`) existem em apps mais velhos; não copiar. Migrar: um `environment.ts`
239
+ base, o que diferia vira `src/brand/config/<amb>.json`, apague os `environment.<amb>.ts` e as configurações
240
+ de ambiente do `angular.json`.
241
+ - `src/brand/config.spec.ts` confere que todos os `config/*.json` têm as mesmas chaves, que nada fixo do build
242
+ (`clientId`, `realmId`, `scope`, `redirectUrl`) aparece neles, que `production` só é `true` em homol/prod e
243
+ que nenhuma URL tem barra final.
193
244
 
194
245
  ## `tsconfig.json`
195
246
 
@@ -224,30 +275,41 @@ declare module '*.md' {
224
275
  "browser": "src/main.ts",
225
276
  "polyfills": ["zone.js"],
226
277
  "inlineStyleLanguage": "scss",
227
- "assets": [{ "glob": "**/*", "input": "src/assets", "output": "assets" }],
278
+ "assets": [
279
+ { "glob": "**/*", "input": "src/assets", "output": "assets" },
280
+ { "glob": "**/*", "input": "src/brand/assets", "output": "brand" },
281
+ { "glob": "*.json", "input": "src/brand/config", "output": "brand/config" },
282
+ { "glob": "config.json", "input": "src", "output": "/" } // só existe no ng serve (use-config)
283
+ ],
228
284
  "styles": [
229
285
  "src/styles.scss",
230
286
  "@trismegisto/tokens/tokens.css",
231
287
  "@trismegisto/core/core.css"
232
288
  ],
233
- "loader": { ".md": "text" } // só se houver documentação por tela
289
+ "loader": { ".md": "text" }, // só se houver documentação por tela
290
+ "baseHref": "/meu-app/"
291
+ },
292
+ "configurations": {
293
+ "production": { "budgets": [ /* ver testes-build.md */ ], "outputHashing": "all" },
294
+ "development": { "optimization": false, "extractLicenses": false, "sourceMap": true }
234
295
  },
296
+ "defaultConfiguration": "production"
297
+ },
298
+ "serve": {
299
+ "builder": "@angular/build:dev-server",
235
300
  "configurations": {
236
- "prod": { "budgets": [ /* ver testes-build.md */ ], "outputHashing": "all",
237
- "baseHref": "/meu-app/",
238
- "fileReplacements": [{ "replace": "src/core/environments/environment.ts",
239
- "with": "src/core/environments/environment.prod.ts" }] },
240
- "homol": { "...": "idem com environment.homol.ts" },
241
- "dev": { "optimization": false, "sourceMap": true, "...": "environment.dev.ts" },
242
- "local": { "optimization": false, "sourceMap": true, "...": "environment.local.ts" },
243
- "development": { "optimization": false, "sourceMap": true }
301
+ "production": { "buildTarget": "meu-app:build:production" },
302
+ "development": { "buildTarget": "meu-app:build:development" }
244
303
  },
245
- "defaultConfiguration": "prod"
304
+ "defaultConfiguration": "development"
246
305
  },
247
- "serve": { "builder": "@angular/build:dev-server", "defaultConfiguration": "development" },
248
306
  "test": { "builder": "@angular/build:karma" }
249
307
  ```
250
308
 
309
+ - **Só `production` e `development`**, sem `fileReplacements`: o ambiente não é decidido no build. Um
310
+ `--configuration homol` (ou `ARG CONFIGURATION=homol`) é resto do modelo antigo.
311
+ - O `dist` leva `brand/config/*.json` de todos os ambientes e **nenhum** `config.json` (o `src/config.json` do
312
+ `ng serve` fica fora da imagem pelo `.dockerignore`).
251
313
  - Use o builder `@angular/build:*`; `@angular-devkit/build-angular:*` é o formato antigo.
252
314
  - `baseHref` = prefixo sob o qual o app é servido (o `applyRuntimeEnvironment` lê de `document.baseURI`).
253
315
  - `cli.cache.environment: "all"` liga o cache do CLI também no build (útil no Docker).
@@ -258,13 +320,11 @@ Os mesmos scripts, na mesma ordem, em todo app (só a porta muda):
258
320
 
259
321
  ```json
260
322
  "ng": "ng",
261
- "start": "ng serve --port 4200",
262
- "dev": "ng serve --configuration=dev --port 4200 --no-hmr",
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",
323
+ "start": "node scripts/use-config.mjs local && ng serve --host 0.0.0.0 --port 4200 --no-hmr",
324
+ "start:dev": "node scripts/use-config.mjs dev && ng serve --host 0.0.0.0 --port 4200 --no-hmr",
325
+ "start:homol": "node scripts/use-config.mjs homol && ng serve --host 0.0.0.0 --port 4200 --no-hmr",
326
+ "start:prod": "node scripts/use-config.mjs prod && ng serve --host 0.0.0.0 --port 4200 --no-hmr",
265
327
  "build": "ng build",
266
- "build:dev": "ng build --configuration dev",
267
- "build:homol": "ng build --configuration homol",
268
328
  "watch": "ng build --watch --configuration development",
269
329
  "test": "ng test",
270
330
  "lint:a11y": "eslint --config eslint.a11y.config.js \"src/**/*.html\"",
@@ -274,6 +334,14 @@ Os mesmos scripts, na mesma ordem, em todo app (só a porta muda):
274
334
 
275
335
  Ferramentas com versão exata nos `devDependencies`, iguais entre os apps: `angular-eslint`, `eslint`,
276
336
  `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.
337
+ Nada de `build:<amb>` nem `--configuration=<amb>`: o build é um só. `start:<amb>` só funciona se a instalação tiver
338
+ `src/brand/config/<amb>.json` (o `use-config` falha listando os que existem).
339
+
340
+ ### `scripts/use-config.mjs`
341
+
342
+ Recebe o ambiente (argumento; sem ele, `APP_ENV`; sem ele, `local`), valida o nome (`[\w-]+`), confere que
343
+ `src/brand/config/<amb>.json` existe e é um objeto JSON e o copia para `src/config.json`, que o `angular.json`
344
+ publica como `config.json`. É o mesmo arquivo que o deploy usa, então o `ng serve` roda com os endereços reais do
345
+ ambiente escolhido. `src/config.json` vai no `.gitignore` e no `.dockerignore`.
278
346
 
279
347
  Cada app usa uma porta fixa própria no dev-server para não colidir com os outros.
@@ -47,7 +47,7 @@ describe('features.routes', () => {
47
47
  | --- | --- |
48
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
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 |
50
+ | `src/brand/config.spec.ts` | Todos os `src/brand/config/*.json` com as mesmas chaves, nada fixo do build neles (`clientId`, `realmId`, `scope`, `redirectUrl`), `production` só em homol/prod, URLs absolutas e sem barra final, `ws` = `http` com `ws(s)://` |
51
51
  | `src/core/core.component.spec.ts` | Título da aba |
52
52
  | `src/app/features/features.routes.spec.ts` | Ids UUID únicos (sem diferenciar maiúsculas), todo `load()` standalone, documentação carregável |
53
53
 
@@ -175,22 +175,25 @@ avisa das que não têm. As URLs vêm do Argos em runtime: o `routeIdToPath` é
175
175
  }
176
176
  ```
177
177
 
178
- - `baseUrl` = origem **e** caminho base do `start:local` (o `baseHref` da configuração `local`); as rotas
178
+ - `baseUrl` = origem **e** caminho base do `npm start` (o `baseHref` do `angular.json`); as rotas
179
179
  são resolvidas a partir dele (`/login` → `…/meu-app/login`). Sem o caminho base, o axe audita a página 404.
180
180
  - Rotas logadas exigem `AXE_STORAGE_STATE=<json com cookies/localStorage>`; sem ele, o que redireciona para
181
181
  `/login` é relatado como "sem auth", não como violação. `AXE_FAIL_ON` (padrão `serious`) define a saída 1.
182
182
 
183
183
  ## Build
184
184
 
185
- | Configuração | Para quê | Environment |
186
- | --- | --- | --- |
187
- | `prod` (**padrão** do `ng build`) | produção: otimizado, `outputHashing: all`, budgets | `environment.prod.ts` |
188
- | `homol` | homologação | `environment.homol.ts` |
189
- | `dev` | ambiente de desenvolvimento em container | `environment.dev.ts` |
190
- | `local` | `ng serve` nativo apontando para serviços locais | `environment.local.ts` |
191
- | `development` | padrão do `ng serve`, sem troca de environment | `environment.ts` |
185
+ | Configuração | Para quê |
186
+ | --- | --- |
187
+ | `production` (**padrão** do `ng build`) | a imagem: otimizado, `outputHashing: all`, budgets. Uma só para todos os ambientes |
188
+ | `development` | padrão do `ng serve`: sem otimização, com source map |
189
+
190
+ Não há configuração por ambiente nem `fileReplacements`: o ambiente vem em runtime do `config.json`
191
+ (`src/brand/config/<amb>.json`, ver `estrutura.md`). `ng build` (= `--configuration production`); saída em
192
+ `dist/<outputPath>/browser`, com `brand/config/*.json` de todos os ambientes e **sem** `config.json`.
192
193
 
193
- `ng build --configuration prod` (ou só `ng build`). Saída em `dist/<outputPath>/browser`.
194
+ Conferir o build como o deploy o usa: copie `dist/<outputPath>/browser/brand/config/homol.json` para
195
+ `.../browser/config.json` e sirva a pasta sob o `baseHref`. Sem o `config.json`, o app de produção não sobe e
196
+ o console mostra o erro do `loadRuntimeConfig` — é o comportamento esperado.
194
197
 
195
198
  ### Budgets
196
199
 
@@ -228,7 +231,9 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
228
231
  timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
229
232
  COPY . .
230
233
  EXPOSE 4200
231
- CMD ["./node_modules/.bin/ng", "serve", "--configuration", "dev", "--host", "0.0.0.0", "--no-hmr", "--port", "4200"]
234
+ # Ambiente do ng serve em runtime: APP_ENV (padrão dev) escolhe src/brand/config/<APP_ENV>.json.
235
+ ENV APP_ENV=dev
236
+ CMD ["sh", "-c", "node scripts/use-config.mjs \"$APP_ENV\" && exec ./node_modules/.bin/ng serve --host 0.0.0.0 --no-hmr --port 4200"]
232
237
 
233
238
  FROM node:22-slim AS build
234
239
  WORKDIR /app
@@ -236,12 +241,13 @@ COPY package.json package-lock.json ./
236
241
  RUN --mount=type=cache,target=/root/.npm,sharing=locked \
237
242
  timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
238
243
  COPY . .
239
- # ARG depois do install: declarado antes, cada ambiente invalidaria o cache do npm ci.
240
- ARG CONFIGURATION=prod
244
+ # Imagem única: sempre production, sem ARG CONFIGURATION (um --build-arg antigo só gera aviso de argumento
245
+ # não usado). O ambiente vem em runtime do config.json que o deploy gera.
241
246
  RUN --mount=type=cache,target=/app/.angular/cache,sharing=locked \
242
- timeout -k 10 300 ./node_modules/.bin/ng build --configuration $CONFIGURATION
247
+ timeout -k 10 300 ./node_modules/.bin/ng build --configuration production
243
248
 
244
- # Imagem só para extrair o site (docker create + docker cp): o build estático em /dist.
249
+ # Imagem só para extrair o site (docker create + docker cp): o build estático em /dist, com
250
+ # brand/config/<amb>.json de todos os ambientes e nenhum config.json (o talos gera no deploy).
245
251
  FROM scratch AS site
246
252
  COPY --from=build /app/dist/meu-app/browser /dist
247
253
  CMD ["unused"]
@@ -250,8 +256,10 @@ CMD ["unused"]
250
256
  - `timeout -k` em passo que baixa/compila: build travado não fica rodando para sempre.
251
257
  - **Não copie `.npmrc`** nem passe credencial por `ARG`/`ENV`: fica gravado na imagem. Os pacotes
252
258
  `@trismegisto/*` e `@orfeu/*` vêm do npm público.
253
- - `.dockerignore` com `node_modules`, `dist`, `.angular`.
259
+ - `.dockerignore` com `node_modules`, `dist`, `.angular` e `src/config.json` (o do `ng serve` nunca entra
260
+ na imagem).
254
261
  - Para servir com nginx (ou outro servidor estático): copie `/dist` para o `root`, sirva sob o mesmo
255
262
  prefixo do `baseHref` e faça fallback de SPA para o `index.html`
256
263
  (`try_files $uri $uri/ /<prefixo>/index.html;`). Arquivos com hash podem ter cache longo;
257
- `index.html` sem cache.
264
+ `index.html` e `config.json` sem cache. Quem serve também precisa gerar o `config.json` do ambiente
265
+ (copiar `brand/config/<amb>.json`), como o talos faz.
@@ -52,7 +52,7 @@ operações, e o roteiro acima libera as operações aos grupos.
52
52
  ## Revisão de acesso (só leitura)
53
53
 
54
54
  Use a conexão `-leitura` se existir. `listAccess` → para cada acesso, `listAccessGuards`; `listGroupMembers` de
55
- cada grupo; `listApps` → `listAppConsumers` → `listConsumerPermissions`. Monte a tabela
55
+ cada grupo (paginado: siga as páginas até `total`); `listApps` → `listAppConsumers` → `listConsumerPermissions`. Monte a tabela
56
56
  grupo → membros → telas → operações e aponte excessos (grupo sem membro, tela sem guard, escrita liberada a grupo
57
57
  de consulta). **Proponha**; não remova nada sem o usuário confirmar item a item.
58
58
 
@@ -15,7 +15,7 @@ details? } }` (ver [diagnostico.md](diagnostico.md)).
15
15
  | `getContext` | `autoservice.context.read` | leitura | — |
16
16
  | `listGroups` | `autoservice.groups.read` | leitura | — |
17
17
  | `searchUsers` | `autoservice.groups.read` | leitura | search, limit |
18
- | `listGroupMembers` | `autoservice.groups.read` | leitura | **group_id** |
18
+ | `listGroupMembers` | `autoservice.groups.read` | leitura | **group_id**, search, page, limit (padrão 50, até 200; a resposta traz `total`: peça as páginas até o fim para o grupo inteiro) |
19
19
  | `addGroupMember` | `autoservice.groups.write` | escrita | **group_id**, **user_id**, role |
20
20
  | `updateGroupMemberRole` | `autoservice.groups.write` | escrita | **group_id**, **user_id**, **role** |
21
21
  | `removeGroupMember` | `autoservice.groups.write` | **destrutiva** | **group_id**, **user_id** |
@@ -37,9 +37,11 @@ motivo em `references/porques.md`; modelos completos e comentados em `references
37
37
  busybox no Alpine, `python -c` no slim). Com Podman/Buildah só é gravado em imagem formato
38
38
  `docker`; no deploy, o `/health` é verificado de fora de qualquer jeito.
39
39
  9. **`ENV PORT` + `EXPOSE`** com a porta cadastrada no Hefesto; o processo escuta em `0.0.0.0`.
40
- 10. **ARG é build, ENV é runtime.** Build arg só para o que muda o artefato (ex.:
41
- `CONFIGURATION` do Angular), declarado **depois** do install. Configuração por ambiente (URLs,
42
- banco, identidade) vem do ambiente em runtime, nunca de `ENV` fixo no Dockerfile.
40
+ 10. **ARG é build, ENV é runtime; uma imagem por versão.** A mesma imagem roda em homol e prod:
41
+ nada de ambiente no build (o Angular sai **sempre** de `ng build --configuration production`, sem
42
+ `ARG CONFIGURATION`). Build arg só para o que muda o artefato e não é ambiente, declarado **depois**
43
+ do install. Configuração por ambiente (URLs, banco, identidade) vem em runtime: variáveis do deploy
44
+ no backend, `config.json` no front (ver regra 16), nunca `ENV` fixo no Dockerfile.
43
45
  11. **`.dockerignore` na raiz do contexto** com `.git`, dependências locais, `dist`, caches e
44
46
  `.env`/`.env.*` (menos `.env.example`). Consequência intencional: o app no container lê config
45
47
  só do ambiente.
@@ -51,13 +53,19 @@ motivo em `references/porques.md`; modelos completos e comentados em `references
51
53
  apagado no `finally`), nunca `-e K=V` no argv (aparece em `ps` e em log). Nome que vira caminho é
52
54
  validado e contido na raiz (`Path.resolve()`) antes de `rmtree`/escrita.
53
55
  15. **`.gitattributes` com `*.sh text eol=lf`**: script com CRLF quebra no container.
56
+ 16. **Front Angular escolhe o ambiente em runtime.** O `dist` leva `brand/config/<amb>.json` de todos os
57
+ ambientes e **nenhum** `config.json`; quem gera o `config.json` é o deploy (site: o Talos copia
58
+ `brand/config/<amb>.json`; SPA servida por um servidor do app: o servidor serve o arquivo de
59
+ `APP_ENV`). `src/config.json` (o do `ng serve`) vai no `.dockerignore`. Estágio `dev`: `ENV APP_ENV=dev`
60
+ + `scripts/use-config.mjs "$APP_ENV"` antes do `ng serve`.
54
61
 
55
62
  ## Por stack (resumo — modelos em `references/modelos.md`)
56
63
 
57
- **Angular (site)** — estágios `dev` (`ng serve`, para compose local), `build`
58
- (`ng build --configuration $CONFIGURATION`, com `ARG CONFIGURATION=prod` depois do `npm ci` e cache
59
- do `.angular/cache`) e **`site`**: `FROM scratch`, `COPY --from=build /app/dist/<projeto>/browser
60
- /dist`, `CMD ["unused"]`. A imagem nunca roda: o Talos a cria, copia o `/dist` e o Caddy do servidor
64
+ **Angular (site)** — estágios `dev` (`use-config` + `ng serve`, para compose local; `APP_ENV`
65
+ escolhe o ambiente), `build` (sempre `ng build --configuration production`, sem `ARG CONFIGURATION`,
66
+ com cache do `.angular/cache`) e **`site`**: `FROM scratch`, `COPY --from=build
67
+ /app/dist/<projeto>/browser /dist`, `CMD ["unused"]`. Uma imagem para todos os ambientes; o
68
+ `config.json` do ambiente é gerado no deploy. A imagem nunca roda: o Talos a cria, copia o `/dist` e o Caddy do servidor
61
69
  serve os arquivos. É o **último** estágio, então compose local precisa de `target: dev`. Budget
62
70
  estourado (`maximumError`) quebra o build — conserte o bundle (ver **angular**).
63
71
 
@@ -86,6 +94,8 @@ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a taref
86
94
  | `docker create` falha: "no command specified" | estágio `scratch` sem `CMD` |
87
95
  | Site extraído sem arquivos | build não copiou para `/dist` (ou copiou `dist/<proj>` em vez de `.../browser`) |
88
96
  | Compose local sobe um container que sai na hora | estágio final é o `site`; faltou `target: dev` |
97
+ | Front sobe em branco com erro do `loadRuntimeConfig` no console | sem `config.json` ao lado do `index.html`: deploy sem o ambiente (Talos antigo, `APP_ENV` faltando) ou `brand/config/<amb>.json` ausente no build |
98
+ | Front em prod falando com os endereços de homol | `src/config.json` local entrou na imagem (faltou no `.dockerignore`) ou imagem antiga buildada por ambiente |
89
99
  | `EACCES` ao escrever arquivo | `USER` não-root e pasta sem `--chown` |
90
100
  | Tarefas agendadas executando em dobro | `uvicorn --workers N` (ou várias réplicas) com scheduler no lifespan |
91
101
  | Credencial aparece em `docker history`/`inspect` | `ARG`/`ENV` de token, ou `.npmrc` copiado |
@@ -15,24 +15,27 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
15
15
  timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
16
16
  COPY . .
17
17
  EXPOSE 4200
18
- CMD ["./node_modules/.bin/ng", "serve", "--configuration", "dev", "--host", "0.0.0.0", "--no-hmr", "--port", "4200"]
18
+ # Ambiente em runtime: APP_ENV (padrão dev) escolhe src/brand/config/<APP_ENV>.json, copiado para
19
+ # src/config.json antes do ng serve; ambiente sem arquivo derruba o container com a lista dos que existem.
20
+ ENV APP_ENV=dev
21
+ CMD ["sh", "-c", "node scripts/use-config.mjs \"$APP_ENV\" && exec ./node_modules/.bin/ng serve --host 0.0.0.0 --no-hmr --port 4200"]
19
22
 
20
- # ── build: o build de verdade, por ambiente ─────────────────────────────────────────────────
23
+ # ── build: o build de verdade, UM para todos os ambientes ───────────────────────────────────
21
24
  FROM node:22-slim AS build
22
25
  WORKDIR /app
23
26
  COPY package.json package-lock.json ./
24
27
  RUN --mount=type=cache,target=/root/.npm,sharing=locked \
25
28
  timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
26
29
  COPY . .
27
- # Depois do install: um ARG entra no ambiente dos RUN seguintes; declarado antes, cada
28
- # ambiente invalidaria o cache do npm ci. O Hefesto passa o nome do ambiente.
29
- ARG CONFIGURATION=prod
30
+ # Imagem única: sempre "production", sem ARG CONFIGURATION e sem endereço embutido. O ambiente vem em
31
+ # runtime do config.json que o deploy gera. Um --build-arg CONFIGURATION antigo só gera aviso.
30
32
  # Cache do Angular CLI fora da imagem (com cli.cache.environment = "all" no angular.json).
31
33
  RUN --mount=type=cache,target=/app/.angular/cache,sharing=locked \
32
- timeout -k 10 300 ./node_modules/.bin/ng build --configuration $CONFIGURATION
34
+ timeout -k 10 300 ./node_modules/.bin/ng build --configuration production
33
35
 
34
36
  # ── site: só transporta o /dist. Nunca roda; é o ÚLTIMO estágio (o --target do Hefesto) ──────
35
37
  FROM scratch AS site
38
+ # /dist leva brand/config/<amb>.json de todos os ambientes e NENHUM config.json (o Talos gera no deploy).
36
39
  COPY --from=build /app/dist/meu-app/browser /dist
37
40
  # `create` exige um comando no manifesto, mesmo que o container nunca rode (scratch não tem shell).
38
41
  CMD ["unused"]
@@ -103,8 +106,9 @@ COPY ui/package.json ui/package-lock.json ./
103
106
  RUN --mount=type=cache,target=/root/.npm,sharing=locked \
104
107
  timeout -k 10 600 npm ci --no-audit --no-fund
105
108
  COPY ui/. .
106
- ARG CONFIGURATION=prod
107
- RUN timeout -k 10 300 npm run build -- --configuration=$CONFIGURATION
109
+ # Imagem única: sempre production. `rm -f src/config.json`: o do ng serve nunca entra na imagem.
110
+ RUN rm -f src/config.json \
111
+ && timeout -k 10 300 ./node_modules/.bin/ng build --configuration production
108
112
 
109
113
  FROM node:22-alpine AS server-build
110
114
  WORKDIR /app
@@ -126,11 +130,19 @@ COPY --from=ui-build /ui/dist /ui/dist
126
130
  ENV NODE_ENV=production PORT=3000 \
127
131
  UI_STATIC_PATH=/ui/dist/meu-app/browser \
128
132
  UI_BASE_PATH=/meu-app
133
+ # APP_ENV (homol, prod...) NÃO vem da imagem: o deploy injeta. O servidor serve
134
+ # {UI_BASE_PATH}/config.json a partir de {UI_STATIC_PATH}/brand/config/${APP_ENV}.json.
129
135
  EXPOSE 3000
130
136
  USER node
131
137
  CMD ["node", "dist/index.js"]
132
138
  ```
133
139
 
140
+ O servidor lê e valida `brand/config/${APP_ENV}.json` **na subida** e registra a rota
141
+ `{UI_BASE_PATH}/config.json` **antes** do `express.static` (um `config.json` solto no build nunca vale no lugar
142
+ do ambiente do deploy), com `Cache-Control: no-store`. Em produção, `APP_ENV` ausente/inválido (`^[a-z0-9-]+$`) ou
143
+ arquivo inexistente/quebrado **derruba a subida** com a lista dos ambientes do build; fora dela só avisa e a rota
144
+ responde 404.
145
+
134
146
  O `.dockerignore` fica na raiz do contexto (a pasta que contém `ui/` e `server/`); os de subpastas
135
147
  não têm efeito.
136
148
 
@@ -202,10 +214,12 @@ coverage
202
214
  !.env.example
203
215
  Dockerfile
204
216
  .dockerignore
217
+ # Angular: o config.json do ng serve (use-config); o deploy é quem escolhe o ambiente
218
+ src/config.json
205
219
  ```
206
220
 
207
221
  Contexto com subpastas (`ui/` + `server/`): use `**/node_modules`, `**/dist`, `**/.env`,
208
- `**/.env.*`, `!**/.env.example`.
222
+ `**/.env.*`, `!**/.env.example`, `**/src/config.json`.
209
223
 
210
224
  Python:
211
225
 
@@ -56,7 +56,7 @@ Com `COPY . .` antes do `npm ci`, qualquer commit reinstala tudo.
56
56
  - **Cache do Angular** (`.angular/cache` montado + `cli.cache.environment: "all"`): partes que não
57
57
  mudaram não são recompiladas.
58
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.
59
+ chave de cache deles. Um `ARG` antes do `npm ci` faz cada valor diferente reinstalar tudo.
60
60
  - **Contexto pequeno** (`.dockerignore`): `.git` e `node_modules` locais mudam sempre e invalidam o
61
61
  `COPY . .`, além de inflar o envio do contexto.
62
62
 
@@ -217,13 +217,21 @@ deploy. A porta do `ENV PORT` precisa bater com a cadastrada na plataforma.
217
217
 
218
218
  | | Quando é lido | Fica na imagem | Use para |
219
219
  | --- | --- | --- | --- |
220
- | `ARG` | só durante o build | no histórico | o que muda o artefato: `CONFIGURATION` do Angular |
220
+ | `ARG` | só durante o build | no histórico | o que muda o artefato e **não** é ambiente (raro; o Angular não usa nenhum) |
221
221
  | `ENV` no Dockerfile | build e runtime | sim | padrões não sensíveis: `PORT`, `NODE_ENV`, `PYTHONUNBUFFERED`, caminhos internos |
222
222
  | 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 |
223
223
 
224
- A mesma imagem deve poder rodar em qualquer ambiente trocando só as variáveis de runtime. A exceção
225
- é o site Angular: o navegador não lê variável de ambiente do servidor, então endpoints e `baseHref`
226
- entram no build (`CONFIGURATION`), e por isso há uma imagem por ambiente.
224
+ A mesma imagem roda em qualquer ambiente trocando só o que é de runtime — **inclusive o front
225
+ Angular**. O navegador não lê variável de ambiente do servidor, então o front lê um arquivo: o `dist`
226
+ leva `brand/config/<amb>.json` de todos os ambientes, e o deploy põe o do ambiente como `config.json` ao
227
+ lado do `index.html` (site: o Talos copia; SPA servida pelo servidor do app: ele serve o arquivo de
228
+ `APP_ENV`). No bootstrap, `loadRuntimeConfig` mescla esse arquivo no `environment`. Só o `baseHref`
229
+ continua no build (é igual em todos os ambientes).
230
+
231
+ Por que uma imagem só: o que foi testado em homologação é **exatamente** o que vai para produção
232
+ (mesmo digest), o deploy de prod não builda de novo (promove a imagem do mesmo commit) e a tag é só a
233
+ versão. A configuração antiga por ambiente (`ARG CONFIGURATION=<amb>` + `fileReplacements`) gerava um
234
+ artefato diferente por ambiente: o que ia para prod nunca tinha rodado em lugar nenhum.
227
235
 
228
236
  ## `.dockerignore`
229
237
 
@@ -232,6 +240,8 @@ entram no build (`CONFIGURATION`), e por isso há uma imagem por ambiente.
232
240
  - **`node_modules`, `.venv`**: as do host são de outro sistema operacional (binários nativos de
233
241
  Windows/macOS) e sobrescreveriam as instaladas no build pelo `COPY . .`.
234
242
  - **`dist`, `.angular`, `coverage`, caches**: artefatos locais que só invalidam cache.
243
+ - **`src/config.json`** (Angular): a cópia do ambiente que o `ng serve` usa. Dentro da imagem, um site
244
+ publicado sem `config_env` (Talos antigo) subiria com o ambiente de quem buildou.
235
245
  - **`.env`, `.env.*` (menos `.env.example`)**: segredo local fora da imagem. Efeito colateral
236
246
  desejado: no container o app **só** lê configuração do ambiente; se ele carrega
237
247
  `.env.<APP_ENV>`, o arquivo não existe e cada valor precisa ser cadastrado como variável. Um app
@@ -255,7 +265,10 @@ vai para o registry com tag e versão como qualquer outra, permite rollback e au
255
265
  publicado, e o Talos extrai `/dist` sem nunca executá-la. Daí as convenções:
256
266
  - estágio chamado `site` (é o `--target`);
257
267
  - conteúdo em `/dist` na raiz;
258
- - `CMD ["unused"]` porque criar um container exige comando no manifesto, e `scratch` não tem shell.
268
+ - `CMD ["unused"]` porque criar um container exige comando no manifesto, e `scratch` não tem shell;
269
+ - `/dist` com `brand/config/<amb>.json` de todos os ambientes e sem `config.json`: o Talos copia o do
270
+ ambiente para `config.json` antes de pôr a versão no ar (arquivo ausente ou JSON inválido = `422` e a
271
+ versão anterior continua).
259
272
 
260
273
  Ser o último estágio faz um `build` sem `--target` produzir a imagem `site`; para rodar o
261
274
  dev-server localmente, `target: dev`. Budgets do `angular.json` com `maximumError` estourado fazem o