@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
package/README.md CHANGED
@@ -14,7 +14,7 @@ Cada skill cobre uma parte da stack e elas se complementam (a `orquestracao` enc
14
14
  | Skill | Assunto | Exemplo de pedido que a dispara |
15
15
  | --- | --- | --- |
16
16
  | `acropole` | Porta de entrada e padrão arquitetural dos apps (pastas, ambientes, saúde, segurança, dependências, scripts, testes); fluxos `app-novo`, `tela-nova`, `endpoint-novo`, `revisar`, `doctor`, `atualizar-libs` | `/acropole`, "cria a estrutura do app novo", "esse app segue o padrão?" |
17
- | `angular` | Estrutura dos apps Angular, bootstrap com o spine, telas por `router_id`, serviços GraphQL, signals, testes, build | "cria a tela de pedidos no app de vendas" |
17
+ | `angular` | Estrutura dos apps Angular, bootstrap com o spine, ambiente em runtime (`config.json`, imagem única por versão), telas por `router_id`, serviços GraphQL, signals, testes, build | "cria a tela de pedidos no app de vendas" |
18
18
  | `trismegisto` | Interface com o design system (`@trismegisto/*`, componentes `hm-*`, tokens `--hm-*`, tema, ícones, a11y) e o shell spine | "troca essa tabela por um data grid", "o botão some no tema escuro" |
19
19
  | `orfeu` | SDK Orfeu: login/sessão no front, operações e níveis no backend, auditoria, `traceparent`, propagação entre serviços | "protege essa rota", "o usuário toma 403", "audita a exclusão" |
20
20
  | `apollo` | Servidores GraphQL (Apollo Server): schema, resolvers, envelope `{ status, message, data }`, subscriptions | "expõe uma mutation para cancelar pedido" |
@@ -52,7 +52,7 @@ O Claude Code chama o revisor quando a tarefa bate com a descrição dele; você
52
52
  | `/acropole endpoint-novo` | Rota/resolver (fastapi, express ou apollo) + operação do Orfeu + propagação de headers + auditoria + teste |
53
53
  | `/acropole revisar [caminho]` | Roda os verificadores sobre o diff/arquivos e chama os revisores. Relata; não corrige sem pedido |
54
54
  | `/acropole doctor [pasta]` | Diagnostica versões `@trismegisto/*`, cópias de `@orfeu/angular`, ordem de `styles`, `provideHttpClient(withInterceptorsFromDi())`, Dockerfile, `orfeu` Python. Achados em `corrige` (aplicados com `--fix`, só se você pedir), `avisa` e `pergunta` |
55
- | `/acropole atualizar-libs [pasta]` | Guia para levar um app às libs de 2026-10 (`@trismegisto/*` 2.1.2, `@orfeu/*` e `orfeu` 1.4.0): o que muda em cada camada, configuração no Argos, variáveis novas, verificação, armadilhas e checklist |
55
+ | `/acropole atualizar-libs [pasta]` | Guia para levar um app às libs de 2026-10 (`@trismegisto/*` 4.0.0, `@orfeu/*` e `orfeu` 1.4.0): o que muda em cada camada, configuração no Argos, variáveis novas, verificação, armadilhas e checklist |
56
56
 
57
57
  ## Verificadores
58
58
 
@@ -129,7 +129,7 @@ fonte do Trismegisto) copia para `skills/<skill>/scripts/nucleo.mjs`. Fixtures d
129
129
 
130
130
  ### Build e release
131
131
 
132
- No disco, este repo fica em `astra/packages/acropole` (`github.com/konvndor/acropole`, branch `master`).
132
+ No disco, este repo fica em `konvndor/packages/acropole` (`github.com/konvndor/acropole`, branch `master`).
133
133
 
134
134
  ```bash
135
135
  scripts/build-publish.sh build # npm test + npm pack -> tarballs/acropole-skills-<versão>.tgz (fora do git)
@@ -155,8 +155,8 @@ Trusted Publisher do npm (dono `konvndor`, repositório `acropole`, workflow `re
155
155
  o npm só aceita o token OIDC vindo dele. A aprovação é o clique em *Run workflow*. O repositório é privado: o npm
156
156
  não gera proveniência e o `package.json` publicado não leva `repository` (não acrescente).
157
157
 
158
- **Primeira publicação (1.0.0).** O Trusted Publisher só pode ser usado depois que o pacote existe no npm, então a
159
- 1.0.0 sai pelo script local, com token:
158
+ **Publicação manual (só emergência).** Fora do CI, o script local publica com token (foi assim que saiu a 1.0.0,
159
+ antes de o Trusted Publisher existir para o pacote):
160
160
 
161
161
  ```bash
162
162
  cp scripts/.env.example scripts/.env # preencha NPM_TOKEN; scripts/.env é ignorado pelo git
@@ -178,9 +178,11 @@ aplicar por analogia o padrão de outra stack.
178
178
  doctor. (Quem baixa o pacote é o `npx`.)
179
179
  - O instalador só escreve em `.claude/skills/<skill>/` e `.claude/agents/<agente>.md` dos itens do
180
180
  pacote, mais o manifesto `.claude/agents/.acropole-manifest.json`.
181
- - Cada pasta de skill instalada leva um arquivo `.acropole` e cada agente uma linha
181
+ - Cada pasta de skill instalada leva um arquivo `.acropole` (com o nome do pacote) e cada agente uma linha
182
182
  `<!-- acropole: instalado por @acropole/skills <versão> -->` logo após o frontmatter. Pasta ou arquivo
183
- de mesmo nome sem essa marca (de outra origem) não é substituído nem removido, a menos que você use
184
- `--force`. A verificação acontece antes de qualquer escrita: não há instalação parcial.
183
+ de mesmo nome sem essa marca, ou com o nome de outro pacote, não é substituído nem removido, a menos que
184
+ você use `--force`. A verificação acontece antes de qualquer escrita: não há instalação parcial.
185
+ - Skill ou agente que uma versão anterior instalou e saiu do pacote é removido no próximo install completo
186
+ (sem `--only`), e só se tiver a marca deste pacote.
185
187
  - Os verificadores e o doctor só leem arquivos do projeto; o doctor nunca lê `.env` ou `.npmrc` (só
186
188
  verifica se entram na imagem) e só altera arquivos com `--fix`, e apenas nas correções mecânicas.
@@ -45,12 +45,17 @@ pista: abra o arquivo e confirme.
45
45
  5. **Healthcheck e porta.** Endpoint de saúde que o serviço realmente expõe; `EXPOSE`/porta coerente
46
46
  com a que o processo escuta e com a configuração do deploy. Serviço que sobe sem o Orfeu conectado
47
47
  (startup em segundo plano) responde 503 no `/health` até conectar.
48
- 6. **Configuração em runtime.** URL, segredo e ambiente lidos de variável de ambiente na subida, não
49
- gravados no build (`ARG` virando `ENV` com valor de produção, `environment.prod.ts` com segredo).
50
- Front estático: só o `/dist` no estágio final. FastAPI em produção com `/docs`, `/openapi.json` e
48
+ 6. **Configuração em runtime; uma imagem por versão.** URL, segredo e ambiente lidos de variável de
49
+ ambiente na subida, não gravados no build (`ARG` virando `ENV` com valor de produção). Front Angular:
50
+ build sempre `--configuration production`, sem `ARG CONFIGURATION` escolhendo ambiente, sem
51
+ `fileReplacements`/`environment.<amb>.ts`; o ambiente vem do `config.json` (`src/brand/config/<amb>.json`
52
+ no build, nenhum `config.json` no `/dist`, `src/config.json` no `.dockerignore`, nada de segredo nesses
53
+ JSON — vão ao navegador). Service que serve a UI lê `brand/config/${APP_ENV}.json` na subida. Front
54
+ estático: só o `/dist` no estágio final. FastAPI em produção com `/docs`, `/openapi.json` e
51
55
  `/redoc` desligados; TLS do autorizador desligado só fora de produção.
52
56
  7. **Higiene.** Multi-stage quando há build; imagem base com versão fixa; `npm ci`/`pip install -r`
53
- com lockfile; `.dockerignore` cobrindo `node_modules`, `.git`, `dist`, `.env*`; script `.sh` no
57
+ com lockfile; `.dockerignore` cobrindo `node_modules`, `.git`, `dist`, `.env*` (e `src/config.json` no
58
+ Angular); script `.sh` no
54
59
  repositório com `.gitattributes` `*.sh text eol=lf`.
55
60
 
56
61
  ## 3. Julgamento
package/bin/install.js CHANGED
@@ -71,21 +71,31 @@ const skillsRoot = path.join(base, '.claude', 'skills');
71
71
  const agentsRoot = path.join(base, '.claude', 'agents');
72
72
 
73
73
  // --- Propriedade -----------------------------------------------------------------------------------
74
- // Skills: as pastas criadas por este pacote levam um arquivo `.acropole`. Sem ele, a pasta é de outra
75
- // origem e só é substituída/removida com --force.
74
+ // Skills: as pastas criadas por este pacote levam um arquivo `.acropole` com o nome do pacote. Sem ele (ou
75
+ // com o nome de outro pacote), a pasta é de outra origem e só é substituída/removida com --force.
76
76
  // Agentes: são arquivos soltos em `.claude/agents/`, então a posse fica registrada de dois jeitos
77
- // (qualquer um basta): o manifesto `.acropole-manifest.json` e um comentário-marca logo após o
78
- // frontmatter do arquivo instalado.
77
+ // (qualquer um basta): o manifesto `.acropole-manifest.json` (com `package` igual a este) e um
78
+ // comentário-marca, com o nome deste pacote, logo após o frontmatter do arquivo instalado.
79
79
  const SKILL_MARKER = '.acropole';
80
80
  const MANIFEST = path.join(agentsRoot, '.acropole-manifest.json');
81
81
  const AGENT_MARK_RE = /^<!-- acropole: instalado por (\S+) (\S+) -->$/m;
82
82
 
83
- const skillOwnedOrAbsent = (dest) => !fs.existsSync(dest) || fs.existsSync(path.join(dest, SKILL_MARKER));
83
+ /** Conteúdo do `.acropole` da pasta (`null` sem o arquivo). */
84
+ const skillMarker = (dest) => {
85
+ try {
86
+ return fs.readFileSync(path.join(dest, SKILL_MARKER), 'utf8').trim();
87
+ } catch {
88
+ return null;
89
+ }
90
+ };
91
+ const skillOwned = (dest) => skillMarker(dest) === name;
92
+ const skillOwnedOrAbsent = (dest) => !fs.existsSync(dest) || skillOwned(dest);
84
93
 
85
94
  function readManifest() {
86
95
  try {
87
96
  const data = JSON.parse(fs.readFileSync(MANIFEST, 'utf8'));
88
- return Array.isArray(data.agents) ? data : { agents: [] };
97
+ // Manifesto de outro pacote (ou sem `package`) não dá posse de nada.
98
+ return data.package === name && Array.isArray(data.agents) ? data : { agents: [] };
89
99
  } catch {
90
100
  return { agents: [] };
91
101
  }
@@ -110,9 +120,19 @@ const agentMark = (file) => {
110
120
  };
111
121
  const agentOwnedOrAbsent = (agent, manifest) => {
112
122
  const file = agentFile(agent);
113
- return !fs.existsSync(file) || manifest.agents.includes(agent) || agentMark(file) !== null;
123
+ return !fs.existsSync(file) || manifest.agents.includes(agent) || agentMark(file)?.pkg === name;
114
124
  };
115
125
 
126
+ /** Pastas de `.claude/skills/` instaladas por este pacote que não existem mais nele (versão anterior). */
127
+ function orphanSkills() {
128
+ if (!fs.existsSync(skillsRoot)) return [];
129
+ return fs.readdirSync(skillsRoot, { withFileTypes: true })
130
+ .filter((d) => d.isDirectory() && !availableSkills.includes(d.name))
131
+ .map((d) => d.name)
132
+ .filter((s) => skillOwned(path.join(skillsRoot, s)))
133
+ .sort();
134
+ }
135
+
116
136
  /** Insere a marca de posse logo após o frontmatter (o Claude Code lê o frontmatter na 1ª linha). */
117
137
  function stampAgent(src) {
118
138
  const mark = `<!-- acropole: instalado por ${name} ${version} -->`;
@@ -143,7 +163,7 @@ if (has('--status')) {
143
163
  for (const s of availableSkills) {
144
164
  const dest = path.join(skillsRoot, s);
145
165
  if (!fs.existsSync(dest)) console.log(` ${s}: não instalada`);
146
- else if (!fs.existsSync(path.join(dest, SKILL_MARKER))) console.log(` ${s}: pasta de outra origem (não é deste pacote)`);
166
+ else if (!skillOwned(dest)) console.log(` ${s}: pasta de outra origem (não é deste pacote)`);
147
167
  else {
148
168
  let v = '';
149
169
  try { v = fs.readFileSync(path.join(dest, 'VERSION'), 'utf8').trim(); } catch { /* sem VERSION */ }
@@ -151,11 +171,13 @@ if (has('--status')) {
151
171
  console.log(` ${s}: ${describe(v)}`);
152
172
  }
153
173
  }
174
+ for (const s of orphanSkills()) console.log(` ${s}: instalada por versão anterior, não existe mais no pacote (sai no próximo install)`);
154
175
  const manifest = readManifest();
155
176
  console.log('agentes:');
156
177
  for (const a of availableAgents) {
157
178
  const file = agentFile(a);
158
- const mark = fs.existsSync(file) ? agentMark(file) : null;
179
+ const found = fs.existsSync(file) ? agentMark(file) : null;
180
+ const mark = found?.pkg === name ? found : null;
159
181
  if (!fs.existsSync(file)) console.log(` ${a}: não instalado`);
160
182
  else if (!mark && !manifest.agents.includes(a)) console.log(` ${a}: arquivo de outra origem (não é deste pacote)`);
161
183
  else {
@@ -216,6 +238,16 @@ for (const skill of skills) {
216
238
  console.log(`${skill} ${version} instalada em ${dest}`);
217
239
  }
218
240
 
241
+ // Skills de versão anterior que saíram do pacote: só as com a marca deste pacote (nunca pasta de outra origem).
242
+ if (!has('--only')) {
243
+ for (const skill of orphanSkills()) {
244
+ const dest = path.join(skillsRoot, skill);
245
+ if (path.dirname(dest) !== skillsRoot) continue;
246
+ fs.rmSync(dest, { recursive: true, force: true });
247
+ console.log(`Removida (não existe mais no pacote): ${dest}`);
248
+ }
249
+ }
250
+
219
251
  let owned = manifest.agents.slice();
220
252
  for (const agent of agents) {
221
253
  const dest = agentFile(agent);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@acropole/skills",
3
- "version": "1.6.1",
3
+ "version": "1.7.1",
4
4
  "description": "Skills e revisores para Claude Code: Angular, Apollo, Express, FastAPI, Trismegisto, Orfeu, Docker, deploy no Hefesto, documentação das telas e os MCPs do auto-serviço do Argos e de deploy do Hefesto. Instale com: npx @acropole/skills",
5
5
  "bin": { "acropole-skills": "bin/install.js" },
6
6
  "files": ["bin", "skills", "agents"],
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: acropole
3
- description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, diagnóstico (doctor) e atualização das libs (@trismegisto 2.1.2, Orfeu 1.4.0). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, um diagnóstico de versões/configuração do projeto, ou subir as libs @trismegisto/@orfeu/orfeu de um app.
3
+ description: Porta de entrada das skills da Acrópole e dono do padrão arquitetural dos apps (pastas angular/graphql/server/database, ambientes, saúde e subida, encerramento, segurança, dependências, scripts e testes iguais em todo app) — descobre a stack do projeto (Angular + Trismegisto, Apollo, Express, FastAPI, Orfeu, Docker/Hefesto), sugere o fluxo certo e encadeia as skills na ordem — app novo, tela nova, endpoint novo, revisão com os verificadores e os subagentes revisores, diagnóstico (doctor) e atualização das libs (@trismegisto 4.0.0, Orfeu 1.4.0). Use quando o usuário chamar /acropole, pedir "por onde começo", "qual skill uso", um app ou estrutura nova, "segue o padrão?", uma tela ou endpoint de ponta a ponta, uma revisão geral, um diagnóstico de versões/configuração do projeto, ou subir as libs @trismegisto/@orfeu/orfeu de um app.
4
4
  user-invocable: true
5
5
  argument-hint: "[app-novo | tela-nova | endpoint-novo | revisar | doctor | atualizar-libs] [alvo]"
6
6
  ---
@@ -22,7 +22,7 @@ dependências, scripts, testes mínimos, pendências e checklist). Divergência
22
22
  | `/acropole endpoint-novo [recurso]` | Endpoint/resolver no backend com operação do Orfeu, propagação de headers, auditoria e teste | [references/fluxos/endpoint-novo.md](references/fluxos/endpoint-novo.md) |
23
23
  | `/acropole revisar [caminho]` | Roda os verificadores das skills sobre o diff/arquivos e chama os subagentes revisores; só relata | [references/fluxos/revisar.md](references/fluxos/revisar.md) |
24
24
  | `/acropole doctor [pasta]` | Diagnostica o projeto (versões, `angular.json`, `provideHttpClient`, Dockerfile, `orfeu` Python) | [references/fluxos/doctor.md](references/fluxos/doctor.md) |
25
- | `/acropole atualizar-libs [pasta]` | Atualiza um app para as libs de 2026-10 (`@trismegisto/*` 2.1.2, `@orfeu/*` e `orfeu` 1.4.0): front, gateway, server, Argos, variáveis, verificação, armadilhas e checklist | [references/fluxos/atualizar-libs-2026-10.md](references/fluxos/atualizar-libs-2026-10.md) |
25
+ | `/acropole atualizar-libs [pasta]` | Atualiza um app para as libs de 2026-10 (`@trismegisto/*` 4.0.0, `@orfeu/*` e `orfeu` 1.4.0): front, gateway, server, Argos, variáveis, verificação, armadilhas e checklist | [references/fluxos/atualizar-libs-2026-10.md](references/fluxos/atualizar-libs-2026-10.md) |
26
26
 
27
27
  Com argumento: carregue **só** o playbook do comando e siga-o. Argumento desconhecido: mostre a tabela
28
28
  acima e pergunte.
@@ -93,7 +93,7 @@ Só **`local`**, **`dev`**, **`homol`** e **`prod`** — em toda camada, com o m
93
93
 
94
94
  | Camada | Escolha do ambiente | Arquivos |
95
95
  | --- | --- | --- |
96
- | angular | `--configuration <ambiente>` (build/serve) | `src/core/environments/environment.<ambiente>.ts` (versionados, sem segredo); `environment.ts` = `local` |
96
+ | angular | em runtime: `config.json` (deploy: `config_env` no site, `APP_ENV` no service; local: `npm run start:<ambiente>`) | `src/core/environments/environment.ts` único + `src/brand/config/<ambiente>.json` (versionados, sem segredo, só o que muda); build sempre `production`, uma imagem para todos os ambientes |
97
97
  | graphql | `NODE_ENV` (`cross-env` nos scripts) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
98
98
  | server | `APP_ENV` (comando, `poe start:<ambiente>` ou `src/.env`) | `src/settings/environment/.env.<ambiente>` (não versionados) + `.env.example` |
99
99
  | database | `-x env=<ambiente>` / `poe migrate <ambiente>` (padrão `local`) | `env/.env.<ambiente>` (não versionados) + `env/.env.example` |
@@ -158,7 +158,7 @@ do Dockerfile falha com `package.json` e lock divergentes.
158
158
 
159
159
  | Camada | Scripts (mesmo conjunto em todo app) |
160
160
  | --- | --- |
161
- | angular | `start`, `dev`, `start:local`, `start:homol`, `build` (prod), `build:dev`, `build:homol`, `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
161
+ | angular | `start` (= `local`), `start:dev`, `start:homol`, `start:prod` (todos `scripts/use-config.mjs <amb>` + `ng serve`), `build` (production), `watch`, `test`, `lint:a11y`, `axe:check`, `codegen` |
162
162
  | graphql | `dev`, `start`, `start:local`, `start:homol`, `build` (typecheck + esbuild), `typecheck`, `start:prod`, `test` |
163
163
  | server | `poe start:local`, `poe start:dev`, `poe start:homol`, `poe test` |
164
164
  | database | `poe migrate <ambiente>`, `poe status <ambiente>`, `poe nova "<descrição>"`, `poe bootstrap <ambiente>`, `poe seed <ambiente>`, `poe seed-regerar <ambiente>`, `poe test` |
@@ -167,7 +167,7 @@ do Dockerfile falha com `package.json` e lock divergentes.
167
167
 
168
168
  | Camada | Obrigatório |
169
169
  | --- | --- |
170
- | angular | `app.config.spec`, `core.providers.spec`, `environments.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
170
+ | angular | `app.config.spec`, `core.providers.spec`, `brand/config.spec`, `core.component.spec`, `features.routes.spec` (UUID único, `load()` standalone, documento carregável) + spec de toda tela nova/alterada |
171
171
  | graphql | `builder.test` (subida, path, CORS, introspecção desligada, lote, 400 de sintaxe, 401/403 antes do resolver, encerramento), `builder-falha.test` (Orfeu fora → 503 → 200; campo sem `operation()` não sobe), `builder-padroes.test`, `shutdown.test` (teto → 1), `resolvers.test` (tabela campo → chamada REST) |
172
172
  | server | `test_health`, `test_api_docs` (só `local`; `API_DOCS` força), testes de domínio com SQLite em memória |
173
173
  | database | suíte compartilhada: migrations do zero, de novo sem efeito, `stamp`, migration nova numerada, confirmação em prod, seed (idempotente, regerar estável) — num Postgres em memória (PGlite por socket) |
@@ -17,8 +17,8 @@ app de origem — e depois remova o que for específico dele. Copiar do zero de
17
17
  | # | Passo | Skill | Onde |
18
18
  | --- | --- | --- | --- |
19
19
  | 1 | **Esqueleto** `angular/`, `graphql/`, `server/`, `database/` + `.gitignore` da raiz, copiados da base sem artefatos nem domínio | acropole | `arquitetura.md` §1 |
20
- | 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), environments dos quatro ambientes com o client/realm do app e o cliente GraphQL `<app>` (`CHANGE_ME` onde a URL deve ser derivada atrás do proxy), `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
21
- | 3 | **Specs fixos do front** (`app.config`, `core.providers`, `environments`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
20
+ | 2 | **Front**: nome do projeto no `angular.json` (`outputPath`, `buildTarget`), `baseHref` `/<app>/`, porta nos scripts, `package.json` (nome, versão `0.1.0`), `environment.ts` único com o client/realm do app e o cliente GraphQL `<app>` (URL vazia onde deve ser derivada atrás do proxy), `src/brand/` da instalação com `config/<ambiente>.json` de cada ambiente (só o que muda), `scripts/use-config.mjs` e `src/config.json` no `.gitignore`/`.dockerignore`, `features.routes.ts` vazio com o exemplo comentado, `styles.scss` mínimo, título/`lang="pt-BR"` no `index.html`, `axe-routes.config.json` com a porta e o caminho base. Tire dependências que só a base usava (editor, gráficos) | angular + trismegisto | angular `references/estrutura.md`, `references/testes-build.md` |
21
+ | 3 | **Specs fixos do front** (`app.config`, `core.providers`, `brand/config`, `core.component`, `features.routes`) ajustados ao app | angular | angular `references/testes-build.md` |
22
22
  | 4 | **Gateway**: `AppModules` e `ExtendedSchema` vazios (base `_health` público, `_noop` privado em Mutation **e** Subscription — o GraphQL não aceita tipo raiz vazio), porta, `GRAPHQL_PATH`, prefixo `<app>:` nos canais, conexões Redis nomeadas por papel (`<app>-graphql-publisher`/`-subscriber`, `REDIS_CLIENT_NAME`), mensagens do `response.ts`, `.env.example` com o app do gateway no Argos | apollo + orfeu | apollo `references/estrutura-bootstrap.md` |
23
23
  | 5 | **Testes do gateway**: manter os genéricos (subida, autorização com `_noop`, falha de subida, padrões, encerramento), tabela de rotas REST vazia, tirar os de domínio | apollo | apollo `references/testes-build.md` |
24
24
  | 6 | **Server**: settings só com Argos, Postgres, Redis (com `redis_client_name` = `<app>-server`, `client_name` no `ConnectionPool`) e `api_docs` (`api_prefix` `/<app>/server`, porta), `AppSettings`/base declarativa do schema `<app>`, router raiz só com `/health`, `main.py` sem tarefas da base, `.env.example` com o app do server, `pyproject.toml` (poe) com a porta | fastapi + orfeu | fastapi `references/estrutura.md` |
@@ -1,17 +1,53 @@
1
1
  # Fluxo: atualizar um app para as libs de 2026-10
2
2
 
3
- Guia para levar **qualquer** app da plataforma às versões publicadas em 2026-10-13:
3
+ Guia para levar **qualquer** app da plataforma às versões atuais (escrito em 2026-10-13 para a 2.1.2; faixas
4
+ atualizadas em 2026-10-22 para a 4.0.0):
4
5
 
5
6
  | Pacote | Versão | Regra |
6
7
  | --- | --- | --- |
7
- | `@trismegisto/*` (tokens, icons, primitives, core, angular, charts, maps, spine) | **2.1.2** | as 8 andam juntas: todas na mesma versão |
8
+ | `@trismegisto/*` (tokens, icons, primitives, core, angular, charts, maps, spine) | **4.0.0** | as 8 andam juntas: todas na mesma versão |
8
9
  | `@orfeu/angular`, `@orfeu/node`, `orfeu` (PyPI) | **1.4.0** | as 3 andam juntas desde a 1.3.0 |
9
- | `@acropole/skills` | **1.5.0** | onde este guia mora |
10
+ | `@acropole/skills` | **1.7.1** ou mais nova | onde este guia mora |
10
11
 
11
12
  O que muda de comportamento veio na **2.1.0** e na **1.3.0** (auditoria de segurança). A **2.1.2** do spine trata
12
13
  a falha de logout e monta a pilha de toasts (§2.3 item 8); a **1.4.0** do Orfeu traz a validação do **token de
13
14
  serviço** (máquina-a-máquina), que a 1.3 passou a recusar como usuário (§3.3). A skill `orfeu` já descreve a 1.4.0 e
14
- os catálogos de API da skill `trismegisto` (`*-api.md`, `angular-exports.md`) já estão na 2.1.
15
+ os catálogos de API da skill `trismegisto` (`*-api.md`, `angular-exports.md`) estão na 4.0.0.
16
+
17
+ **Vindo da 2.x para a 3.x** (além do que está abaixo, que continua valendo):
18
+
19
+ - **3.0.0** — `hm-data-grid`: a coluna de ações (o ⋮ de `rowActions`) passou a ser a **primeira** coluna, em toda
20
+ grade. Testes do app que procuravam o ⋮ na última célula (`td:last-child`, `cells.at(-1)`) ou liam a 1ª célula como a
21
+ 1ª coluna de dados precisam mudar; o seletor `.hm-data-grid__actions-trigger` é o mesmo. No spine, o painel de
22
+ configurações separou **MFA** e **Sessões**, e o auto-serviço deixou de mostrar o grupo de administração do projeto
23
+ (gerido só no Argos).
24
+ - **3.3.0** — uma pilha de avisos só: as mensagens de resposta do `NotificationService` (envelope dos GraphQL, falha do
25
+ logout) saem no `hm-toast-stack`, junto com os do `HermesToastService`. O `spine-layout` não monta mais o
26
+ `spine-notification`; app que monta o seu continua funcionando (ele só monta uma pilha). Apague CSS que posicionava
27
+ a coluna antiga de alertas.
28
+
29
+ **Vindo da 3.x para a 4.0.0** (major: remoções; o "Migrando da 3.x" de cada CHANGELOG tem a tabela completa):
30
+
31
+ - **`hm-session-recovery`** só volta para a **mesma origem** por padrão. Se o `origin` é outro app (o login central
32
+ devolvendo para o app de origem), passe `[allowedOrigins]` com as origens aceitas — sem a lista o botão some.
33
+ - **Removidos do `@trismegisto/angular`**: `hm-field` (→ `hm-input`), `STATE_PAGE_PRESETS` (→ `statePagePreset(kind,
34
+ inject(HERMES_MESSAGES))`), `provideHermesMessages` (→ `provideHermesI18n`), `[requiredManual]` do `hm-combobox`
35
+ (→ `required`), `[help]` do `hm-combobox-multi` (→ `hint`), `[(start)]`/`[(end)]` do `hm-date-range-picker` (→
36
+ `[(value)]` com `DateRange`), `HermesSidebarService.doc`. Continuam (depreciados, com aviso no console): `busy` do
37
+ `hm-button`, `color="error"` do `hm-tag`, `help` do `hm-combobox`/`hm-textarea`/`hm-radio`/`hm-switch` e
38
+ `[startControl]`/`[endControl]` do `hm-date-range-picker` — troque quando mexer na tela.
39
+ - **Removidos do `@trismegisto/primitives`**: as funções de teclado/arrasto do `reorder.ts` (fica `moveItem`), chaves sem
40
+ uso do `HERMES_MESSAGES` (`reorderList.instructions`/`grabbed`/`moved`/`dropped`/`cancelled`, `dataGrid.sort*`,
41
+ `workspace.closeOtherPanels`, `codeDiff.showAbove`/`showBelow`) e helpers sem consumidor (`toPreviousPage`,
42
+ `kanbanTotal`, `stepperProgress`, `timelineProgress`, `zoomLevelForWidth`...). Catálogo/`override` do app com essas
43
+ chaves não compila: apague-as.
44
+ - **Spine**: o `provideUi()` registra só os ícones do próprio spine (`SPINE_ICONS`) e carrega o catálogo inteiro sob
45
+ demanda; ícone do app não registrado aparece quando o chunk chega (registre os do app com `provideHermesIcons` para
46
+ desenhar já no 1º quadro). Todos os componentes do spine são `OnPush`: o componente aberto no
47
+ `ModalService`/`SidePanelService` atualiza por signal/`markForCheck`, como as telas. Saíram `route_id`/`component`
48
+ do mapa de telas (→ `id`/`load`), `componentRouteId`, `lastMissingRouteId`, `SPINE_SETTINGS_KEYS.security` (o link
49
+ `?settings=seguranca` continua abrindo MFA), a API antiga do painel de atalhos (`ShortcutService.shortcuts`/`groups()`)
50
+ e textos sem uso do `SPINE_MESSAGES`.
15
51
 
16
52
  Faça camada por camada, na ordem do documento, e rode a verificação (§7) de cada uma antes de ir para a próxima.
17
53
  Não mescle nada sem o PR do repositório do app (branch → `development` → `master`).
@@ -44,17 +80,17 @@ FastAPI com `orfeu`, pasta `database/`). Antes de mexer:
44
80
  ### 2.1 Dependências
45
81
 
46
82
  ```bash
47
- # só os pacotes que o app já usa, todos em 2.1.2
48
- npm install @trismegisto/tokens@2.1.2 @trismegisto/icons@2.1.2 @trismegisto/primitives@2.1.2 \
49
- @trismegisto/core@2.1.2 @trismegisto/angular@2.1.2 @trismegisto/spine@2.1.2 @orfeu/angular@1.4.0
83
+ # só os pacotes que o app já usa, todos em 4.0.0
84
+ npm install @trismegisto/tokens@4.0.0 @trismegisto/icons@4.0.0 @trismegisto/primitives@4.0.0 \
85
+ @trismegisto/core@4.0.0 @trismegisto/angular@4.0.0 @trismegisto/spine@4.0.0 @orfeu/angular@1.4.0
50
86
  # opcionais, se já estão no package.json
51
- npm install @trismegisto/charts@2.1.2 @trismegisto/maps@2.1.2
87
+ npm install @trismegisto/charts@4.0.0 @trismegisto/maps@4.0.0
52
88
  npm ls @orfeu/angular # UMA cópia só (o spine aceita ^1.0.0; duas cópias = NullInjectorError/segunda sessão)
53
89
  ```
54
90
 
55
- No `package.json`, faixa `^2.1.2` e `^1.4.0` (nunca `^2`/`^1`). Lockfile no mesmo commit — revise o diff dele
56
- (§8, campos `libc`). App que já está em `^2.1.1` não quebra: pega a 2.1.2 no próximo `npm install`, mas suba a faixa
57
- para não depender do lockfile.
91
+ No `package.json`, faixa `^4.0.0` e `^1.4.0` (nunca `^4`/`^1`). Lockfile no mesmo commit — revise o diff dele
92
+ (§8, campos `libc`). Uma faixa `^2.x`/`^3.x` **não** aceita a 4.x (major): suba a faixa, rode
93
+ `npm install` e confira o app e os testes pelas listas "Vindo da 2.x para a 3.x" e "Vindo da 3.x para a 4.0.0" acima.
58
94
 
59
95
  ### 2.2 Só se o app vier de `@trismegisto` 1.x: quebras da 2.0
60
96
 
@@ -85,8 +121,8 @@ Nenhuma delas dá erro de build — procure à mão:
85
121
  chave antiga é apagada no primeiro uso — **favoritos e recentes somem uma vez**. Avise as pessoas (uma novidade
86
122
  em `provideSpineNews` serve). Código do app que lia a chave antiga do `localStorage` passa a usar
87
123
  `SpineQuickAccessService`. No logout, recentes e buscas saem; favoritos ficam.
88
- 5. **`hm-session-recovery`**: `origin` só `http(s)`. Quando o `origin` vem da URL/referrer, declare
89
- `[allowedOrigins]` com as origens aceitas (sem a lista, qualquer `http(s)` vale — redirect aberto). `returned` emite
124
+ 5. **`hm-session-recovery`**: `origin` só `http(s)` e, desde a 4.0.0, só a mesma origem da página sem lista. Origem
125
+ externa (o app de volta, um `?returnTo=`) só se estiver em `[allowedOrigins]`; sem ela o botão some. `returned` emite
90
126
  o endereço normalizado; `safeReturnUrl` está exportada.
91
127
  6. **Texto com marcação em `[innerHTML]`**: `formatMessage`/`fmt`/`pluralMessage` **com parâmetros** num
92
128
  `[innerHTML]` é XSS (parâmetro vindo do servidor não é escapado). Troque por `formatMessageHtml`/
@@ -358,12 +394,12 @@ Toda variável nova vai no `.env.example` da camada (só nomes e IDs públicos)
358
394
 
359
395
  - [ ] Skills em dia (`@acropole/skills` 1.5.0+) e `/acropole doctor` rodado antes e depois
360
396
  - [ ] Argos do ambiente com `iss`, conta por Bearer e CORS por client (§1)
361
- - [ ] `@trismegisto/*` todas em `^2.1.2`; `@orfeu/angular` `^1.4.0` com uma cópia; lockfile commitado e com o diff
397
+ - [ ] `@trismegisto/*` todas em `^4.0.0`; `@orfeu/angular` `^1.4.0` com uma cópia; lockfile commitado e com o diff
362
398
  revisado (`libc`)
363
399
  - [ ] (vindo da 1.x) `quarck` → `micro`, slots `shortcuts`/`actions`, sem `hm-wizard [orientation]` nem `hm-opening-scene`
364
400
  - [ ] `[innerHTML]` com parâmetro só por `formatMessageHtml`/`pluralMessageHtml`/`escapeHtml`
365
401
  - [ ] Ações destrutivas do `hm-data-grid` com `confirm` (sem confirmação dupla)
366
- - [ ] `hm-session-recovery` com `allowedOrigins` quando o `origin` vem de fora
402
+ - [ ] `hm-session-recovery` com `allowedOrigins` quando o `origin` é de outra origem (4.0.0: sem a lista, o botão some)
367
403
  - [ ] Falha de logout com o spine 2.1.2 (nada no app; botão próprio usa `SpineLogoutService`, sem toast próprio nem
368
404
  `logoutFailed$`); sem `<hm-toast-stack>` montado pelo app; callback próprio por `handleCallback`, sem
369
405
  `error_description`
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: angular
3
- description: "Arquitetura de apps Angular da plataforma (22+, standalone, shell spine): estrutura de pastas, bootstrap, registro de tela por router_id, serviços GraphQL/REST com unwrap, signals, formulários, testes e build. Use ao criar ou alterar um app Angular, a parte de rotas/estado/dados de uma tela, um serviço de dados ou o build. A parte visual da tela (componentes hm-*, tokens, tema, ícones) é da skill trismegisto — numa tela nova use as duas; login/sessão/token é da orfeu."
3
+ description: "Arquitetura de apps Angular da plataforma (22+, standalone, shell spine): estrutura de pastas, bootstrap, registro de tela por router_id, serviços GraphQL/REST com unwrap, signals, formulários, testes, build e ambiente em runtime (imagem única por versão, config.json de src/brand/config). Use ao criar ou alterar um app Angular, a parte de rotas/estado/dados de uma tela, um serviço de dados, o build ou a configuração por ambiente. A parte visual da tela (componentes hm-*, tokens, tema, ícones) é da skill trismegisto — numa tela nova use as duas; login/sessão/token é da orfeu."
4
4
  ---
5
5
 
6
6
  # angular
@@ -28,16 +28,18 @@ Ainda não coberto por nenhuma skill: React, Strawberry, Fastify, Django, Flask.
28
28
 
29
29
  ```
30
30
  meu-app/
31
- ├── angular.json # builder @angular/build:application, configs prod/dev/homol/local/development
31
+ ├── angular.json # builder @angular/build:application, só configs production/development
32
32
  ├── codegen.ts # graphql-codegen (tipos + TypedDocumentNode), roda à mão
33
- ├── Dockerfile # estágios dev / build / site (só o /dist estático)
33
+ ├── Dockerfile # estágios dev / build / site (só o /dist estático); build sempre production
34
+ ├── scripts/use-config.mjs # ng serve: copia src/brand/config/<amb>.json para src/config.json (fora do git)
34
35
  ├── eslint.a11y.config.js # regras de acessibilidade de template (angular-eslint)
35
36
  ├── tsconfig.json # strict, paths src/* e package.json (sem baseUrl), resolveJsonModule
36
37
  └── src/
37
- ├── main.ts # applyRuntimeEnvironment(environment) + bootstrapApplication
38
+ ├── main.ts # loadRuntimeConfig -> applyRuntimeEnvironment -> import dinâmico -> bootstrap
38
39
  ├── index.html # lang="pt-BR", favicon, tela #app-loading
39
40
  ├── styles.scss # só estilos globais do app, com tokens --hm-*
40
- ├── core/ # app.config.ts, core.providers.ts, core.component.ts, environments/
41
+ ├── core/ # app.config.ts, core.providers.ts, core.component.ts, environments/ (um environment.ts)
42
+ ├── brand/ # a instalação: brand.ts, theme.ts/.scss, assets/, config/<amb>.json (não sincronizada)
41
43
  ├── app/
42
44
  │ ├── features/ # uma pasta por tela + features.routes.ts (mapa router_id -> tela lazy)
43
45
  │ └── services/ # <dominio>/<dominio>.graphql|.service.ts|.models.ts|.generated.ts
@@ -49,10 +51,19 @@ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md
49
51
 
50
52
  ## Regras essenciais
51
53
 
52
- **Bootstrap** (`src/core/`)
53
- - `main.ts` chama `applyRuntimeEnvironment(environment)` (de `@trismegisto/spine`) **antes** do
54
- `bootstrapApplication`: deriva `redirectUrl`/`postLogoutRedirectUri` da origem atual e, atrás do
55
- proxy, `authority` e endpoints GraphQL ainda com `CHANGE_ME`. Não grave URL de callback fixa.
54
+ **Imagem única e bootstrap** (`src/main.ts`, `src/core/`, `src/brand/`)
55
+ - **Uma imagem por versão** (build `production` do master), a mesma em homol e prod: nada de environment
56
+ por ambiente no build. Um `environment.ts` base (o que não muda + URLs vazias); o que varia fica em
57
+ `src/brand/config/<ambiente>.json` (**só** o que muda; mesclado chave a chave, arrays/valores simples
58
+ substituem), publicado em `brand/config/`. Em runtime o app lê o `config.json` ao lado do `index.html`.
59
+ - `main.ts`: `loadRuntimeConfig(environment, { required: !isDevMode() })` (de `@trismegisto/spine`, que
60
+ reexporta o do `@trismegisto/primitives`) **antes de tudo**; no `.then`, `applyRuntimeEnvironment(environment)`
61
+ (deriva `redirectUrl`/`postLogoutRedirectUri` da origem e, atrás do proxy, `authority`/GraphQL vazios) e só
62
+ então `import()` dinâmico de `app.config`/componente raiz e `bootstrapApplication`. Sem top-level await
63
+ (Zone.js); `required: !isDevMode()`, não `environment.production` (ele só fica certo depois do config.json).
64
+ Não grave URL de callback fixa.
65
+ - `src/brand/` é a **instalação** (marca, tema, `providers.ts` quando há, assets, `config/`): cada instalação
66
+ tem a sua e o sync entre instalações não a copia.
56
67
  - `app.config.ts`: `provideZoneChangeDetection({ eventCoalescing: true })` (uma vez só),
57
68
  `provideRouter(APP_ROUTES)`, `...CORE_PROVIDERS`, `provideUi(spineConfig)`, `provideAuth(...)`,
58
69
  `provideAutoService(...)` se o client usa auto-serviço, `provideShell({ appComponents, packageInfo })`.
@@ -91,13 +102,17 @@ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md
91
102
  sequência). Ver [references/dados.md](references/dados.md).
92
103
 
93
104
  **Build e qualidade**
94
- - Build de produção: `ng build --configuration prod` (é a `defaultConfiguration`, então `ng build`
95
- basta). Outras: `dev`, `homol`, `local` (troca o `environment.ts` por `fileReplacements`) e
96
- `development` (só para `ng serve`).
105
+ - `angular.json` só com as configurações `production` (padrão do `ng build`) e `development` (padrão do
106
+ `ng serve`), **sem `fileReplacements`**; `assets` publica `src/brand/config/*.json` em `brand/config/` e
107
+ `src/config.json` na raiz. A imagem sempre `ng build --configuration production`; o `dist` leva todos os
108
+ `brand/config/*.json` e nenhum `config.json` (quem escolhe é o deploy).
109
+ - Rodar local: `npm start` (= `local`), `start:dev`, `start:homol`, `start:prod` — cada um roda
110
+ `node scripts/use-config.mjs <amb>` (copia para `src/config.json`, no `.gitignore` e no `.dockerignore`)
111
+ e depois `ng serve`.
97
112
  - `angular.json` > `styles`: `src/styles.scss`, `@trismegisto/tokens/tokens.css`,
98
113
  `@trismegisto/core/core.css`.
99
114
  - Testes: Karma + Jasmine (`@angular/build:karma`, `ng test`), com specs fixos do core (`app.config`,
100
- `core.providers`, `environments`, `features.routes`). Acessibilidade: `lint:a11y` e `axe:check`, com os
115
+ `core.providers`, `brand/config`, `features.routes`). Acessibilidade: `lint:a11y` e `axe:check`, com os
101
116
  mesmos arquivos em todo app. Ver [references/testes-build.md](references/testes-build.md).
102
117
  - Padrão do app inteiro (pastas do repo, portas, ambientes, scripts, saúde dos backends):
103
118
  skill `acropole` (`references/arquitetura.md`).
@@ -131,7 +146,8 @@ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md
131
146
  - **`input()` não popula `ngOnChanges`**: `changes['x']` vira código morto; reaja com `effect()`.
132
147
  - **`new DatePipe('pt-BR')`** sem `registerLocaleData(localePt)` no `main.ts` lança NG0701.
133
148
  - **`HermesToastService` sem `<hm-toast-stack />`** montado uma vez no componente raiz: o toast é
134
- aceito e nunca aparece. (O `NotificationService` do spine já é renderizado pelo layout.)
149
+ aceito e nunca aparece. (Dentro do `spine-layout` a pilha já vem montada, e o `NotificationService` do spine
150
+ sai nela também, desde a 3.3.0.)
135
151
  - **`provideHttpClient()` sem `withInterceptorsFromDi()`** perde o `x-route-id` da auditoria.
136
152
  - **Mensagem do backend** (`message` do envelope) é texto: nunca via `innerHTML`.
137
153
  - **`@defer`** encolhe chunks de telas lazy, mas **não** resolve aviso de budget `initial` (o grosso
@@ -139,13 +155,16 @@ Detalhes e exemplos completos: [references/estrutura.md](references/estrutura.md
139
155
  - **`tsconfig.app.json` com `files: ["src/main.ts"]`**: só compila o que é alcançável a partir das
140
156
  rotas. Tela fora do `features.routes.ts` não quebra o build — e apodrece em silêncio.
141
157
  - **`.npmrc` copiado no Dockerfile** grava credencial na imagem; os pacotes vêm do npm público.
158
+ - **Import estático de `app.config`/componente raiz no `main.ts`**: o módulo lê o `environment` ao carregar,
159
+ antes do `config.json` chegar, e fica com as URLs vazias. Importe depois do `loadRuntimeConfig`.
160
+ - **Segredo em `src/brand/config/*.json`**: o arquivo é servido ao navegador. Só endereços e flags públicas.
142
161
 
143
162
  Lista completa com contexto: [references/armadilhas.md](references/armadilhas.md).
144
163
 
145
164
  ## Referências
146
165
 
147
166
  - [references/estrutura.md](references/estrutura.md) — pastas, `main.ts`, `app.config.ts`,
148
- `core.providers.ts`, environments, `tsconfig`, `angular.json`, convenções de nome e imports.
167
+ `core.providers.ts`, environment + `src/brand/config`, `tsconfig`, `angular.json`, scripts, convenções.
149
168
  - [references/features.md](references/features.md) — registro no shell, rotas próprias/públicas,
150
169
  documentação por tela, anatomia de componente, signals, templates, formulários, a11y, i18n.
151
170
  - [references/dados.md](references/dados.md) — GraphQL (`injectGraphqlClient`, `unwrap`, envelope,
@@ -18,6 +18,15 @@
18
18
  - **Reescrever `environment` depois do bootstrap** ou esperar que uma mutação feita em um lugar seja
19
19
  vista por serviços de chunks lazy. Derive tudo no `main.ts` antes do bootstrap; valor dinâmico de
20
20
  verdade vai num `InjectionToken`.
21
+ - **Ler o `environment` antes do `config.json`**: import estático de `app.config`/componente raiz no
22
+ `main.ts` (o módulo lê `clientId`/URLs ao carregar) ou `required: environment.production` (o `production`
23
+ ainda é o do build). Bootstrap dentro do `.then` do `loadRuntimeConfig`, com `import()` dinâmico e
24
+ `required: !isDevMode()`. Top-level await não serve (Zone.js).
25
+ - **Configuração de ambiente no build** (`environment.<amb>.ts`, `fileReplacements`, `--configuration homol`):
26
+ gera uma imagem por ambiente e impede a promoção da mesma imagem de homol para prod.
27
+ - **Segredo em `src/brand/config/*.json`**: é servido ao navegador como `config.json`.
28
+ - **`src/config.json` commitado ou dentro da imagem**: o deploy precisa escolher o ambiente; ele fica no
29
+ `.gitignore` e no `.dockerignore`.
21
30
  - **`provideZoneChangeDetection` duplicado** (no `bootstrapApplication` e no `appConfig`). Um só, no
22
31
  `appConfig`, com `eventCoalescing: true`.
23
32
  - **Remover `zone.js`** "porque tudo é OnPush". Zoneless exige migração dedicada e testada; libs de
@@ -65,14 +74,14 @@
65
74
 
66
75
  ### Notificações
67
76
  - **`HermesToastService` sem `<hm-toast-stack />`** no componente raiz: o serviço aceita o toast e
68
- nada aparece. O `NotificationService` do spine não tem esse problema (o layout o renderiza), mas só
69
- existe dentro da área privada.
77
+ nada aparece. Dentro do `spine-layout` não há esse problema: ele já monta a pilha, e desde a 3.3.0 o
78
+ `NotificationService` do spine também sai nela (uma pilha só; nunca monte `hm-alert` flutuante próprio).
70
79
 
71
80
  ### Build e entrega
72
81
  - **Achar que `@defer` resolve o aviso de budget `initial`.** Não resolve (é CSS global + shell/auth).
73
82
  - **Copiar `.npmrc` / credencial de registry no Dockerfile.**
74
- - **`ng build` esperando configuração de dev**: o padrão do build é `prod`; o padrão do `serve` é
75
- `development`.
83
+ - **`ng build` esperando configuração de dev**: o padrão do build é `production`; o padrão do `serve` é
84
+ `development`. Ambiente local é o `config.json` (`npm run start:<amb>`), não uma configuração do build.
76
85
 
77
86
  ## Divergências encontradas entre os apps (e o padrão recomendado)
78
87
 
@@ -83,14 +92,15 @@
83
92
  | Change detection global | `provideZoneChangeDetection` uma vez x repetido no `main.ts` | uma vez, em `app.config.ts`, com `eventCoalescing` |
84
93
  | Auth | `provideAuth(environment.authorizationServer)` x `AUTH_CONFIG` + `APP_INITIALIZER` | `provideAuth` |
85
94
  | Environment | `src/core/environments/` com `authorizationServer` x `src/environments/` com `auth` | `src/core/environments/`, `authorizationServer` tipado como `AuthConfig` do `@orfeu/angular`, `GraphqlEndpoint` do spine |
95
+ | Ambiente no build | `environment.<amb>.ts` + `fileReplacements` + configuração `homol`/`prod` no `angular.json` (uma imagem por ambiente) | imagem única: um `environment.ts` base, `src/brand/config/<amb>.json` e `loadRuntimeConfig` no `main.ts` |
86
96
  | Campos de login | interface própria com `silentRenew`/`useRefreshToken`/`postLogoutRedirectUri`/`responseType` | só o `AuthConfig` (os outros a lib não lê) |
87
97
  | Imports absolutos | `baseUrl: "./"` (+ `ignoreDeprecations: "6.0"`) x `paths` | `paths` com `src/*` e `package.json`, sem `baseUrl` |
88
- | Scripts | apps sem `start:homol`, com `start:prod`, `dev` sem `--configuration=dev` | o mesmo conjunto em todo app (`references/estrutura.md`) |
98
+ | Scripts | `ng serve --configuration=<amb>`, `build:<amb>`, conjuntos diferentes por app | `start`, `start:dev`, `start:homol`, `start:prod` com `scripts/use-config.mjs` (`references/estrutura.md`) |
89
99
  | Ferramentas de a11y | `@angular-eslint/*` avulsos, `@axe-core/puppeteer`, três `axe-check` diferentes | `angular-eslint` + `axe-core` com versão exata; `axe-check.js` e `eslint.a11y.config.js` idênticos |
90
100
  | Ajuste de URL em runtime | `applyRuntimeEnvironment` x cálculo manual no `main.ts` | `applyRuntimeEnvironment` (+ só o específico do app) |
91
101
  | Services | `src/app/services/<dominio>/` x dentro de `features/` | `src/app/services/<dominio>/` |
92
102
  | Componentes | signals/`input()`/`inject()` x `@Input` + construtor + `standalone: true` | signals/`input()`/`inject()` |
93
- | Notificação manual | `NotificationService` (spine) x `HermesToastService` + `hm-toast-stack` | um por app; com `HermesToastService`, monte o stack na raiz |
103
+ | Notificação manual | `NotificationService` (spine) x `HermesToastService` + `hm-toast-stack` | os dois saem na mesma pilha desde a 3.3.0; fora do `spine-layout`, monte o stack na raiz |
94
104
  | `anyComponentStyle` | 4/8 kB, 16/32 kB, 24/32 kB | 16/32 kB |
95
105
  | Budget `initial` | 2.1 MB x 4 MB de aviso | 4 MB aviso / 5 MB erro |
96
106
  | Dockerfile | com e sem `.npmrc` copiado | sem `.npmrc` |