@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
@@ -27,37 +27,48 @@ e o flush dela no SIGTERM), **auto-servico** (o MCP equivalente do Argos).
27
27
  configurado (`--depth 1`) e builda na raiz do repo ou no `build_path` (subpasta, para monorepo).
28
28
  Nada de arquivo gerado localmente, `.env` ou `.npmrc` com credencial. Ver **docker**.
29
29
  2. **Tipo do app decide o alvo do build.** `service`: estágio final do Dockerfile, vira container.
30
- `site`: o Ciclope builda `--target site` com `--build-arg CONFIGURATION=<nome do ambiente>`;
31
- o estágio `site` tem o build estático em **`/dist` na raiz da imagem** e nunca roda.
32
- 3. **A porta cadastrada no app é a porta em que o processo escuta dentro do container**, em
30
+ `site`: o Ciclope builda `--target site`; o estágio `site` tem o build estático em **`/dist` na raiz
31
+ da imagem** e nunca roda. Em qualquer tipo o build recebe `--build-arg CONFIGURATION=production`
32
+ (sempre o mesmo; o Dockerfile pode nem declarar o `ARG`).
33
+ 3. **Uma imagem por versão, a mesma em todos os ambientes.** O ambiente não entra no build; o front
34
+ escolhe o ambiente em runtime pelo `config.json`. Na implantação o Hefesto diz qual é: **site** →
35
+ `config_env=<ambiente>` para o Talos, que copia `brand/config/<ambiente>.json` para `config.json`
36
+ (Talos ≥ 1.1.13); **service** → o container recebe `APP_ENV=<ambiente>` (se a app cadastrou `APP_ENV`
37
+ nas variáveis dela, a dela vence) e o servidor do app serve o `config.json` da UI. `<ambiente>` = nome
38
+ cadastrado, em minúsculas. O app precisa ter `brand/config/<ambiente>.json` de cada ambiente no build
39
+ (ver **angular**).
40
+ 4. **A porta cadastrada no app é a porta em que o processo escuta dentro do container**, em
33
41
  `0.0.0.0`. O Caddy encaminha para `<nome-do-container>:<porta do app>` pela rede interna; a porta
34
42
  do worker é só o mapeamento no host. O Hefesto **não injeta `PORT`**: deixe o `ENV PORT` do
35
43
  Dockerfile igual ao cadastro (ou cadastre a variável).
36
- 4. **O path do agent chega inteiro no service** (o Caddy usa `handle`, sem tirar o prefixo). Um
44
+ 5. **O path do agent chega inteiro no service** (o Caddy usa `handle`, sem tirar o prefixo). Um
37
45
  service publicado em `/meu-app/api` precisa responder em `/meu-app/api/...` (prefixo configurável
38
46
  no app: `API_PREFIX`, `root_path`, `CONTEXT_PATH`). Para **site** o prefixo é removido, mas o
39
47
  `baseHref` do Angular tem que ser o próprio path, senão os assets saem da raiz e dão 404.
40
48
  O path é sempre o **contexto do app** (`/<app>`, `/<app>/server`, `/<app>/mcp`): nunca publique nem
41
49
  configure um serviço em `/api` genérico, nem troque o contexto para fazer uma URL funcionar.
42
- 5. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
50
+ 6. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
43
51
  `podman run` por um `--env-file` temporário (600, apagado logo depois; nunca `-e K=V` no argv) —
44
52
  **só no próximo deploy/redeploy/rollback**. Arquivos `.env.*` não vão para a imagem
45
53
  (`.dockerignore`). Segredo **sem valor padrão** no Dockerfile/código: faltou no cadastro, o app cai na
46
54
  subida em vez de aceitar `changeme`.
47
- 6. **Processo principal recebe o SIGTERM.** Toda troca de versão para a versão antiga com SIGTERM (até
55
+ 7. **Processo principal recebe o SIGTERM.** Toda troca de versão para a versão antiga com SIGTERM (até
48
56
  30 s, depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
49
57
  perde a fila de auditoria do Orfeu e atrasa todo deploy. Ver **docker**.
50
- 7. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O deploy de
58
+ 8. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O deploy de
51
59
  service é um rollout: a versão nova sobe ao lado da atual e só entra se o `health_path` responder
52
60
  < 400 (sem ele, só a porta é conferida); não ficou saudável, é descartada e a atual continua no ar.
53
- 8. **Versão é do registry**: tag `[<instalação>.]<ambiente>-<major>.<minor>.<fix>.<test>` (ex.:
54
- `hml1.homol-1.4.0.2`; o prefixo é o `HEFESTO_INSTANCE_ID`). O build escolhe qual parte incrementar e o
55
- Deploy implanta exatamente a imagem que ele produziu; a retenção mantém só as últimas N por ambiente
56
- desta instalação (padrão 5), menos as que algum worker está rodando. Rollback só para versão que ainda
57
- existe no registry.
58
- 9. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
59
- workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
60
- distribuído. Ver `references/preparar-app.md`.
61
+ 9. **Versão é do registry e da app**: tag `<registry>/<app>:<major>.<minor>.<fix>.<test>` (ex.:
62
+ `app-exemplo:1.4.0.2`), **sem ambiente nem prefixo de instalação**. O build escolhe qual parte
63
+ incrementar e o Deploy implanta exatamente a imagem que ele produziu. **Promoção**: o Build de um
64
+ ambiente reaproveita a imagem já publicada por outro quando repositório git, branch, `build_path`,
65
+ registry e commit batem — por isso o repositório de **homol aponta para `master`**, como o de prod;
66
+ deploy em homol e depois em prod do mesmo commit = um build só. Tags antigas
67
+ (`[<instalação>.]<ambiente>-x.y.z.w`, buildadas por ambiente) continuam listadas e implantáveis só no
68
+ próprio ambiente. Rollback só para versão que ainda existe no registry.
69
+ 10. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
70
+ workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
71
+ distribuído. Ver `references/preparar-app.md`.
61
72
 
62
73
  ## Fluxo em uma tela
63
74
 
@@ -66,12 +77,14 @@ Solicitação "Deploy de Serviços|Sites" Início → Build → Deploy → Fim
66
77
  Solicitação "Redeploy de Serviços|Sites" Início → Deploy → Fim (sem build: última versão)
67
78
 
68
79
  Início valida app, agent, worker e se o repositório é do MESMO ambiente do origin do worker
69
- Build Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
70
- → push <registry>/<app>:<ambiente>-<versão> → retenção das antigas
80
+ Build mesmo commit de um build já publicado (deste ou de outro ambiente, mesma fonte)? reaproveita
81
+ senão Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
82
+ CONFIGURATION=production → push <registry>/<app>:<versão> → retenção das antigas
71
83
  Deploy Hefesto → Talos do origin: pull da imagem que o Build gravou (Redeploy: a mais nova do ambiente)
72
- service: rollout — sobe <nome>-next, espera o /health, troca e remove a antiga (sem downtime;
73
- não ficou saudável = descarta a nova e a atual segue no ar)
74
- site: create (sem rodar) → copia /dist para pasta nova → troca atômica do link
84
+ service: rollout com APP_ENV=<ambiente> — sobe <nome>-next, espera o /health, troca e remove a
85
+ antiga (sem downtime; não ficou saudável = descarta a nova e a atual segue no ar)
86
+ site: create (sem rodar) → copia /dist para pasta nova → config_env: brand/config/<amb>.json
87
+ vira config.json → troca atômica do link
75
88
  → Hefesto regenera o Caddyfile do origin; o Talos valida e recarrega o Caddy
76
89
  Rollback solicitação própria (Início → Deploy → Fim) com uma versão escolhida da lista do registry
77
90
  ```
@@ -83,8 +96,12 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
83
96
 
84
97
  - [ ] Dockerfile na raiz do repo (ou do `build_path`), `.dockerignore` com `.git`, dependências
85
98
  locais, `dist` e `.env*`. Para site: estágio chamado `site` com `/dist`.
86
- - [ ] Site: uma configuração do Angular **com o nome exato de cada ambiente** do Hefesto
87
- (`dev`, `homol`, `prod`...), com `baseHref` igual ao path do agent.
99
+ - [ ] Front (site ou service com UI): `src/brand/config/<ambiente>.json` **com o nome exato de cada
100
+ ambiente** do Hefesto em minúsculas (`homol`, `prod`...), `loadRuntimeConfig` no `main.ts` e
101
+ `baseHref` igual ao path do agent. Service com UI: o servidor serve o `config.json` de `APP_ENV`.
102
+ - [ ] Repositório de homol no branch `master` (mesma URL, `build_path` e registry do de prod) para a
103
+ imagem de homol ser promovida a prod sem novo build.
104
+ - [ ] Site: Talos do origin ≥ 1.1.13 (o anterior ignora `config_env` e o site sobe sem `config.json`).
88
105
  - [ ] Service: escuta em `0.0.0.0:<porta cadastrada>`, responde sob o path do agent, tem
89
106
  `/health`, trata SIGTERM, CMD em forma exec.
90
107
  - [ ] Nenhum segredo com valor padrão (`ENV X=changeme`, `getenv("X", "...")`); `.gitattributes` com
@@ -102,8 +119,13 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
102
119
 
103
120
  ## Armadilhas mais comuns (lista completa em `references/diagnostico.md`)
104
121
 
105
- - **"Configuration 'x' is not set in the workspace"** no build de site: o ambiente do Hefesto tem
106
- um nome que não existe no `angular.json`. O `CONFIGURATION` é o nome do ambiente, sem tradução.
122
+ - **Front sobe em branco, console com erro do `config.json`**: falta o ambiente em runtime — site com
123
+ Talos antigo (sem `config_env`), `brand/config/<ambiente>.json` ausente no build (o Talos responde
124
+ `422` e a versão anterior continua), ou service sem `APP_ENV`/servidor sem a rota do `config.json`.
125
+ - **Deploy de prod buildou de novo em vez de promover**: repositórios de homol e prod com branch, URL,
126
+ `build_path` ou registry diferentes, ou commit novo no master depois do deploy de homol.
127
+ - **"Configuration 'production' is not set"**: o `angular.json` não tem a configuração `production`
128
+ (resto do modelo antigo `prod`/`homol`).
107
129
  - **502 só na rota do app**: worker cadastrado mas container parado/caindo, ou o processo escuta em
108
130
  outra porta / em `127.0.0.1`.
109
131
  - **404 em tudo do service, mas `/health` direto no container funciona**: o app responde na raiz e
@@ -134,12 +156,15 @@ nada. O agente trabalha assim:
134
156
 
135
157
  1. `getContext` → `listApps(search)` → `getApp(app_id)`: por ambiente, o repositório e os workers (servidor, status,
136
158
  versão em execução). Todo id sai daí; nunca suposição.
137
- 2. Mostre o que muda (versão atual → nova, servidor/ambiente) e **confirme**, principalmente em produção; só depois
138
- do "sim" chame a tool com `confirm: true`.
159
+ 2. Mostre o que muda (versão atual → nova, servidor/ambiente). Pedido que já diz a app e o ambiente é a confirmação;
160
+ confirme só o que ficou em aberto (qual ambiente, qual app). Aí chame a tool com `confirm: true`.
139
161
  3. `deployApp(app_id, worker_id, part)` (build + implantação) ou `redeployApp(app_id, worker_id)` (só reimplanta a
140
- mais recente); `scheduled_for` agenda. A resposta volta na hora com o `requested_id`.
162
+ mais recente), um por worker, todos juntos; `scheduled_for` agenda. A resposta volta na hora com o `requested_id`.
141
163
  4. `getRequest` até `finished=true`; falhou → etapa com erro e `getBuildLog` (final do log). Pedido de um Solicitante
142
164
  fica aguardando aprovação (`pending_approval`): avise e não espere a execução.
165
+ 5. Produto com várias apps: migrations pendentes primeiro, depois server → GraphQL → front, uma camada só quando a
166
+ anterior terminou em todos os workers. O autodeploy do próprio Hefesto pode terminar "Falhou" com a versão nova no
167
+ ar: confira antes de refazer. Os dois em `references/mcp-roteiros.md`.
143
168
 
144
169
  Também estão no MCP: `cancelRequest`, `approveRequest`/`rejectRequest` (decidem o que um Solicitante pediu; escopo
145
170
  `deploy.approvals.write`), `rollbackApp` (abre uma solicitação de Rollback; exige a permissão de
@@ -156,5 +181,5 @@ rollback no Argos), `getWorkerHistory` e `listEnvironmentVars`/`setEnvironmentVa
156
181
  | `references/preparar-app.md` | O que o app precisa ter: Dockerfile, porta, path, health, SIGTERM, variáveis, build args, site, réplicas e tarefas em background |
157
182
  | `references/diagnostico.md` | Onde olhar (histórico, logs do container, Caddyfile), mensagens de erro do Hefesto e o que significam, erros comuns com causa |
158
183
  | `references/mcp-tools.md` | hefesto-mcp: tools com argumentos, escopos, resources e prompts |
159
- | `references/mcp-roteiros.md` | hefesto-mcp: deploy, redeploy, agendamento, vários workers, falha e revisão do que está rodando |
184
+ | `references/mcp-roteiros.md` | hefesto-mcp: deploy, redeploy, agendamento, vários workers, produto com várias apps (migrations e ordem das camadas), deploy do próprio Hefesto, falha e revisão do que está rodando |
160
185
  | `references/mcp-diagnostico.md` | hefesto-mcp: erros ao conectar e nas tools, e falhas por etapa da solicitação |
@@ -43,17 +43,21 @@ header HTTP, fora da linha de comando e dos logs. Use um token **só de leitura*
43
43
  Onde as imagens são publicadas e de onde os origins puxam. Tem URL, usuário/senha, `verify_ssl`
44
44
  (desligar só para registry com certificado de CA interna que os hosts não conhecem) e, opcionalmente,
45
45
  uma URL de gerenciamento para apagar tags na retenção. Um mesmo registry pode servir vários
46
- ambientes (e até várias instalações do Hefesto): as tags levam o ambiente no nome.
46
+ ambientes (e até várias instalações do Hefesto): a tag é só a versão da app (`<app>:x.y.z.w`), a mesma
47
+ imagem para todos os ambientes; as tags antigas (`[<instalação>.]<ambiente>-x.y.z.w`) levavam o ambiente.
47
48
 
48
49
  ### Repositório (`repository`) — um por (aplicação, ambiente)
49
50
  | Campo | Significado |
50
51
  | --- | --- |
51
52
  | URL | repositório git (HTTPS) |
52
- | branch | branch clonado para esse ambiente (ex.: `develop` em homol, `main` em prod) |
53
+ | branch | branch clonado para esse ambiente. Para promover a mesma imagem de homol para prod, os dois apontam para `master` |
53
54
  | `build_path` | subpasta usada como contexto do build (monorepo). Vazio = raiz. Não pode sair do repo. |
54
55
  | conector | credencial do clone |
55
56
  | registry | destino da imagem; sem ele não há build |
56
57
 
58
+ Repositórios de ambientes diferentes com a mesma URL, branch, `build_path` e registry formam uma **mesma
59
+ fonte**: o Build de um reaproveita (promove) a imagem que o outro já publicou para o mesmo commit.
60
+
57
61
  ### Build (`build`)
58
62
  Log das tentativas de build (status `building`/`built`/`failed`, quando). **A fonte da verdade do
59
63
  que existe é o registry**: a lista de versões mostrada é reconciliada com as tags publicadas (uma
@@ -63,10 +67,12 @@ removida).
63
67
  ## Infraestrutura
64
68
 
65
69
  ### Ambiente (`environment`)
66
- `dev`, `homol`, `prod`... O **nome** importa em dois lugares:
67
- - prefixo da tag da imagem (sanitizado: sem acento/espaço);
68
- - `CONFIGURATION` do build de site, **sem sanitização** — precisa existir com esse nome exato no
69
- `angular.json`.
70
+ `dev`, `homol`, `prod`... O **nome**, em minúsculas, é o ambiente em runtime do front:
71
+ - site: `config_env=<ambiente>` no deploy; o Talos copia `brand/config/<ambiente>.json` para `config.json`;
72
+ - service: o container recebe `APP_ENV=<ambiente>` (a variável `APP_ENV` da app, se cadastrada, vence).
73
+
74
+ Precisa existir `src/brand/config/<ambiente>.json` com esse nome exato no front. O ambiente **não** entra mais
75
+ no build (sempre `CONFIGURATION=production`) nem na tag da imagem.
70
76
 
71
77
  ### Origin (`origin`)
72
78
  Um servidor com o **Talos** rodando (há também o tipo `kubernetes` no cadastro). Pertence a **um**
@@ -101,7 +107,8 @@ origin só serve os próprios agents. Agent **sem domínio vinculado** cai no bl
101
107
  Chave/valor por (aplicação, ambiente), iguais em todos os origins daquele ambiente. Aplicadas como
102
108
  um `--env-file` temporário (600, apagado logo depois) no `podman run` do próximo deploy, redeploy ou
103
109
  rollback — o valor não passa pelo argv. Não valem para site (não
104
- há processo; a configuração do site é decidida no build).
110
+ há processo; a configuração do site é o `brand/config/<ambiente>.json` do build, escolhido no deploy). O service
111
+ recebe também `APP_ENV=<ambiente>`, a menos que a app tenha a sua.
105
112
 
106
113
  ## Operação
107
114
 
@@ -125,7 +132,8 @@ ou `error`, com a mensagem (no erro de build, o fim da saída do `podman build`)
125
132
  para diagnosticar. Mudanças são publicadas em tempo real para a UI.
126
133
 
127
134
  ### Deploy, Redeploy e Rollback
128
- - **Deploy**: builda uma versão nova e implanta.
135
+ - **Deploy**: builda uma versão nova e implanta — ou, se outro ambiente já publicou o mesmo commit da mesma
136
+ fonte, reaproveita aquela imagem (promoção) e implanta.
129
137
  - **Redeploy**: implanta a versão mais recente já publicada, sem build (útil depois de mudar
130
138
  variáveis ou para recriar um container).
131
139
  - **Rollback**: implanta uma versão anterior escolhida na lista do registry daquele ambiente.
@@ -34,6 +34,7 @@
34
34
  | Deploy de `<versão>` desfeito automaticamente: A nova versão não ficou saudável (...) | a versão nova não respondeu < 400 no `health_path` (ou não abriu a porta) dentro do prazo; a anterior continua no ar | leia as últimas linhas da nova versão na mensagem; corrija a subida ou o `/health` |
35
35
  | A imagem buildada por esta solicitação (...) não está mais no registry | a retenção apagou a imagem entre o Build e o Deploy | faça um novo Deploy |
36
36
  | Interrompida: o server reiniciou durante a etapa X | o hefesto-server caiu no meio do Build/Deploy | confira o status do worker e use **Avançar** |
37
+ | Deploy de `<versão>` do próprio hefesto não confirmado: ... | autodeploy do hefesto-server: o rollout derrubou o processo e a conferência no Talos não fechou | `running_image_tag` do worker = versão do Build e `/health` 200 → está no ar, não refaça; versão antiga → falha de verdade (ver [mcp-roteiros.md](mcp-roteiros.md), "Deploy do próprio Hefesto") |
37
38
  | A solicitação já está em execução (409) | outro avanço da mesma solicitação está rodando | espere terminar |
38
39
  | O Talos recusou o Caddyfile (caddy validate) | configuração gerada inválida (domínio ou path estranho) | a mensagem traz a saída do validate; o Caddyfile anterior continua ativo |
39
40
  | Rollback exige a permissão de rollback no Argos | usuário sem `apps:agents:workers:rollback` | peça a permissão ao administrador do Argos |
@@ -51,7 +52,13 @@
51
52
  | Rota do app responde com outro app | dois agents sem path no mesmo domínio | só um handler raiz por domínio; o segundo é ignorado |
52
53
  | Site: tela branca, assets 404 | `baseHref` diferente do path do agent | o Caddy remove o prefixo, mas o navegador pede os assets com o `baseHref` do build |
53
54
  | Site: F5 numa rota dá 404 | `site_mode = static` | use `spa` para fallback no `index.html` |
54
- | Site: build falha com "Configuration 'x' is not set" | nome do ambiente sem configuração no `angular.json` | `CONFIGURATION` = nome do ambiente, exato |
55
+ | Build falha com "Configuration 'production' is not set" | `angular.json` ainda no modelo antigo (`prod`/`homol`...) | o build é sempre `production`; ver **angular** |
56
+ | Front: tela branca, console com erro ao carregar `config.json` | sem o ambiente em runtime: Talos < 1.1.13 (ignora `config_env`), service sem `APP_ENV` ou servidor sem a rota `<prefixo>/config.json` | atualize o Talos; confira o `APP_ENV` (ou a variável da app, que vence) e a rota no servidor |
57
+ | Site: deploy falha com `422` "a imagem não tem brand/config/<amb>.json" | o build não traz o arquivo do ambiente (nome diferente do cadastrado, ou fora do `assets` do `angular.json`) | `src/brand/config/<ambiente>.json` com o nome do ambiente em minúsculas; a versão anterior continua no ar |
58
+ | Service com UI cai na subida: "APP_ENV não definido" / "brand/config/x.json não existe" | `APP_ENV` sobrescrito errado nas variáveis da app, ou ambiente sem arquivo no build | remova o `APP_ENV` da app (o Hefesto injeta o nome do ambiente) ou crie o arquivo |
59
+ | Front em prod com endereços de homol | `src/config.json` local entrou na imagem e o deploy não gerou outro (Talos antigo), ou `homol.json`/`prod.json` trocados | `src/config.json` no `.dockerignore`; confira os arquivos de `src/brand/config/` |
60
+ | Deploy em prod buildou de novo em vez de reaproveitar a imagem de homol | repositórios dos ambientes com URL, branch, `build_path` ou registry diferentes; ou commit novo no branch desde o deploy de homol | repositório de homol em `master`, igual ao de prod |
61
+ | Redeploy em prod não pega a versão nova de homol | Redeploy só implanta o que foi buildado ou promovido **para o ambiente** | faça um Deploy em prod (promove) ou Rollback para a versão |
55
62
  | Site antigo depois do deploy | cache do navegador no `index.html` | arquivos com hash podem ter cache longo; `index.html` não |
56
63
  | Container reinicia em loop | variável obrigatória faltando, dependência inacessível na subida, erro de import | logs do container mostram o erro da primeira linha de settings |
57
64
  | Variável nova não aparece | variáveis só entram quando o container é criado | faça Redeploy |
@@ -71,10 +78,13 @@
71
78
  ```bash
72
79
  git clone --depth 1 --single-branch --branch <branch> <url> /tmp/x && cd /tmp/x/<build_path>
73
80
  podman build -t teste . # service
74
- podman build --target site --build-arg CONFIGURATION=homol -t teste . # site
81
+ podman build --target site -t teste . # site (sempre production)
75
82
  podman run --rm --env-file .env.teste -p 8080:<porta do app> teste # service: confira /health
76
83
  ```
77
84
 
85
+ Site: para conferir o `/dist` como o Talos publica, extraia (`podman create` + `podman cp <id>:/dist ./site`),
86
+ copie `site/brand/config/homol.json` para `site/config.json` e sirva a pasta sob o `baseHref`.
87
+
78
88
  O `.env.teste` é local (fora do repo e com permissão restrita); segredo em `-e` fica no histórico do
79
89
  shell. Com Docker local funciona igual para a maioria dos casos; diferenças do Podman/Buildah estão na
80
90
  skill **docker**.
@@ -4,7 +4,7 @@
4
4
 
5
5
  ```
6
6
  solicitação (UI) registry
7
- usuário ───────────────▶ Hefesto ──build──▶ Ciclope ──push──▶ <app>:<amb>-x.y.z.w
7
+ usuário ───────────────▶ Hefesto ──build──▶ Ciclope ──push──▶ <app>:x.y.z.w
8
8
  │ │
9
9
  └──deploy──▶ Talos (origin do ambiente) ◀─┘ pull
10
10
  │
@@ -16,30 +16,40 @@
16
16
  ## 1. Início (validação)
17
17
 
18
18
  - app, agent e worker existem e pertencem um ao outro;
19
- - no Deploy: o repositório escolhido é o **do ambiente do origin** do worker. Sem essa checagem daria
20
- para buildar a imagem de `homol` e o passo Deploy pegar a última de `prod`;
19
+ - no Deploy: o repositório escolhido é o **do ambiente do origin** do worker (é ele que diz o branch e
20
+ em que histórico de builds a versão entra);
21
21
  - sanidade (só aviso em log): tipo da solicitação (Sites/Serviços) bate com o tipo do app. Quem decide
22
22
  o comportamento é sempre o tipo do app.
23
23
 
24
24
  ## 2. Build (Ciclope)
25
25
 
26
- 1. **Versão**: o Hefesto lista as tags do app no registry, filtra as do ambiente
27
- (`<ambiente>-x.y.z.w`), pega a maior (somando builds em andamento) e incrementa a parte escolhida
28
- (`major`, `minor`, `fix`, `test`), zerando as menores: `1.2.3.4` + minor = `1.3.0.0`. Sem versão
29
- anterior parte de `0.0.0.0`. Registry fora do ar = o build não começa (chutar a versão causaria
30
- colisão com outra instalação que compartilha o registry).
31
- 2. **Clone**: branch do repositório, `--depth 1 --single-branch --no-tags`, credencial do conector
26
+ 1. **Mesmo commit = reaproveita (promoção).** Antes de buildar, o Hefesto procura um build `built` com
27
+ o mesmo commit: deste repositório, ou do repositório **de outro ambiente da app** com a mesma URL git,
28
+ branch, `build_path` e registry (só imagens no formato novo; a tag precisa continuar no registry).
29
+ Pergunta ao Ciclope o commit atual do branch (`git ls-remote`, sem clonar); bateu, **não builda**: a
30
+ etapa Build termina com "Imagem reaproveitada do build X do ambiente Y ..." e o Deploy implanta a mesma
31
+ imagem (vira uma linha `built` no repositório deste ambiente, para histórico e Redeploy). Falha na
32
+ consulta do commit nunca bloqueia: o build segue. Por isso o repositório de homol aponta para
33
+ `master`, como o de prod: deploy em homol e depois em prod do mesmo commit = um build só.
34
+ 2. **Versão**: o Hefesto lista as tags da app no registry (novas e antigas, de qualquer ambiente ou
35
+ instalação), pega a maior (somando as reservadas por builds em andamento dos outros ambientes) e
36
+ incrementa a parte escolhida (`major`, `minor`, `fix`, `test`), zerando as menores: `1.2.3.4` +
37
+ minor = `1.3.0.0`. Sem versão anterior parte de `0.0.0.0`. Registry fora do ar = o build não começa
38
+ (chutar a versão causaria colisão com outra instalação que compartilha o registry).
39
+ 3. **Clone**: branch do repositório, `--depth 1 --single-branch --no-tags`, credencial do conector
32
40
  em header (não aparece em `ps` nem em log; saídas de erro passam por redação de credenciais).
33
- 3. **Build**: `podman build` (Buildah, não Docker) com `--jobs 2` (estágios independentes em
34
- paralelo), no `build_path`. Para site: `--target site --build-arg CONFIGURATION=<ambiente>`.
41
+ 4. **Build**: `podman build` (Buildah, não Docker) com `--jobs 2` (estágios independentes em
42
+ paralelo), no `build_path`, sempre com `--build-arg CONFIGURATION=production` (qualquer tipo e
43
+ ambiente; Dockerfile que não declara o `ARG` só ganha aviso). Para site: `--target site`.
35
44
  Limite padrão de 900 s; estourou = 504 com as últimas linhas da saída.
36
- 4. **Push** para `<registry>/<app_name>:<instalação>.<ambiente>-<versão>` (o prefixo é o
37
- `HEFESTO_INSTANCE_ID`; sem ele, `<ambiente>-<versão>` como antes). A imagem fica gravada na etapa Build
38
- da solicitação (`execution_image`), e é ela que o Deploy implanta.
39
- 5. **Retenção** (best-effort, nunca derruba o build): apaga as tags **desta instalação** do ambiente além
40
- das N mais novas (padrão 5), **exceto** as que algum worker está rodando. Tags de outros ambientes, de
41
- outras instalações que dividem o registry e tags antigas sem prefixo não são tocadas. Sem
42
- `HEFESTO_INSTANCE_ID`, a retenção fica desligada.
45
+ 5. **Push** para `<registry>/<app_name>:<versão>` (ex.: `app-exemplo:1.4.2.0`), sem ambiente nem prefixo
46
+ de instalação: a tag é da app, a mesma imagem serve todos os ambientes. A imagem fica gravada na etapa
47
+ Build da solicitação (`execution_image`), e é ela que o Deploy implanta.
48
+ 6. **Retenção** (best-effort, nunca derruba o build), **exceto** as tags que algum worker está rodando:
49
+ tags novas só com opt-in (`REGISTRY_PRUNE_SHARED_TAGS=true`: a tag é de todos os ambientes e
50
+ instalações), mantendo as N mais novas da app e as N mais novas de cada ambiente (padrão 5); tags
51
+ antigas (por ambiente) desta instalação além das N mais novas, como antes. Tags de outras
52
+ instalações nunca são tocadas.
43
53
 
44
54
  O cache do build fica no host do Ciclope (camadas + `--mount=type=cache`); imagens sem tag só são
45
55
  limpas depois de dias, para não perder o cache de quem builda com frequência. Por isso a ordem dos
@@ -53,8 +63,9 @@ limpas depois de dias, para não perder o cache de quem builda com frequência.
53
63
 
54
64
  Na etapa Deploy de uma solicitação **Deploy**, o Hefesto implanta **exatamente a imagem que o Build desta
55
65
  solicitação gravou** (e confere que ela ainda está no registry). Redeploy, sem Build, usa a versão mais nova
56
- publicada para o ambiente. O worker vai para `deploying` (com `deploying_since`) e o Hefesto chama o Talos do
57
- origin.
66
+ publicada para o ambiente (buildada ou promovida para ele). O worker vai para `deploying` (com `deploying_since`)
67
+ e o Hefesto chama o Talos do origin, dizendo o ambiente (`<ambiente>` = nome cadastrado em minúsculas): o front
68
+ escolhe o ambiente em runtime pelo `config.json`.
58
69
 
59
70
  ### service: rollout sem indisponibilidade
60
71
  1. `podman login` + `pull`;
@@ -68,7 +79,9 @@ origin.
68
79
  `-next`. Se a recriação falhar, a `-next` segue atendendo pelo alias e o resultado é `degraded` (um novo
69
80
  deploy normaliza);
70
81
  5. as variáveis do (app, ambiente) vão num arquivo com permissão 600, apagado logo depois do `run` — nunca como
71
- `-e K=V` no argv;
82
+ `-e K=V` no argv. O container recebe também `APP_ENV=<ambiente>` (se a app tem `APP_ENV` nas variáveis
83
+ dela, a dela vence; não é segredo nem conta como variável faltando). Service com UI: o servidor do app
84
+ serve o `config.json` da UI a partir de `brand/config/${APP_ENV}.json`;
72
85
  6. worker `running` com a tag; o Hefesto regenera o Caddyfile do origin.
73
86
 
74
87
  Consequências:
@@ -83,9 +96,13 @@ Consequências:
83
96
 
84
97
  ### site
85
98
  1. `pull`, `podman create` (o container nunca roda — por isso o `CMD ["unused"]` no estágio `site`);
86
- 2. copia `/dist/.` da imagem para uma pasta nova e troca o link da pasta do agent por rename atômico: se a cópia
87
- falhar, a versão anterior continua no ar;
88
- 3. Caddyfile regenerado: `file_server` na pasta, `uri strip_prefix <path>`, e `try_files {path}
99
+ 2. copia `/dist/.` da imagem para uma pasta nova; com `config_env=<ambiente>` (Talos ≥ 1.1.13), copia
100
+ `brand/config/<ambiente>.json` para `config.json` nessa pasta (sobrescreve um que viesse na imagem). Arquivo
101
+ ausente ou JSON inválido = `422`, a pasta nova é apagada e a versão anterior continua. Talos antigo ignora o
102
+ campo (o site sobe sem `config.json` e o front de produção não inicia). Imagem antiga, por ambiente, vai sem
103
+ `config_env` (já traz a configuração dela);
104
+ 3. troca o link da pasta do agent por rename atômico: se a cópia falhar, a versão anterior continua no ar;
105
+ 4. Caddyfile regenerado: `file_server` na pasta, `uri strip_prefix <path>`, e `try_files {path}
89
106
  /index.html` se `site_mode = spa`.
90
107
 
91
108
  ### Caddyfile
@@ -112,7 +129,9 @@ o server reiniciou durante a etapa X"), para alguém conferir o worker antes de
112
129
  ## Redeploy
113
130
 
114
131
  Solicitação **Redeploy** (Início → Deploy → Fim): o passo 3 sem build, com a última versão publicada do
115
- ambiente. Use para:
132
+ ambiente — a mais nova entre as tags que o repositório do ambiente buildou ou recebeu por promoção (e as antigas
133
+ do ambiente). Uma versão buildada para homol e ainda não promovida **não** vai para prod num Redeploy: promover
134
+ é um Deploy (cujo Build reaproveita a imagem) ou um Rollback para a versão escolhida. Use para:
116
135
  - aplicar variáveis de ambiente alteradas;
117
136
  - recriar um container que alguém parou ou removeu à mão;
118
137
  - publicar em um worker novo uma versão que já existe.
@@ -131,7 +150,9 @@ Regras:
131
150
  - migrations de banco **não** voltam. Versão antiga contra schema novo precisa ser compatível
132
151
  (migrations aditivas, nunca destrutivas no mesmo release);
133
152
  - o rollout com health check vale igual: se a versão antiga não subir saudável, a atual continua no ar;
134
- - site: o `/dist` da versão escolhida substitui o atual (troca atômica).
153
+ - site: o `/dist` da versão escolhida substitui o atual (troca atômica);
154
+ - versão antiga, por ambiente (`prod-1.3.0.0`, de antes da imagem única): funciona como antes — já foi buildada
155
+ com a configuração do ambiente, então o site vai sem `config_env` e o service ignora o `APP_ENV`.
135
156
 
136
157
  Todo deploy, redeploy e rollback de um worker fica no **histórico do worker** (aba Histórico da aplicação,
137
158
  `getWorkerHistory` no MCP), com a origem (solicitação, tela legada, MCP, API), as tags anterior e nova e o
@@ -146,6 +167,7 @@ resultado.
146
167
  | `fix` | correção |
147
168
  | `test` | build de teste/validação em ambiente não produtivo |
148
169
 
149
- A numeração é por ambiente: `homol-1.3.0.0` e `prod-1.3.0.0` são builds diferentes (branch e
150
- `CONFIGURATION` de cada ambiente; com `HEFESTO_INSTANCE_ID`, a tag ganha o prefixo da instalação, ex.:
151
- `hml1.homol-1.3.0.0`). Promover para produção = novo build no repositório de prod.
170
+ A numeração é da **app**, não do ambiente: `app-exemplo:1.3.0.0` é a mesma imagem em homol e prod.
171
+ Promover para produção = Deploy em prod do mesmo commit (o Build reaproveita a imagem; nada é buildado de
172
+ novo). Tags antigas por ambiente (`homol-1.3.0.0`, `<instalação>.prod-1.3.0.0`) continuam listadas e
173
+ implantáveis só no próprio ambiente; a primeira tag nova é sempre maior que todas elas.
@@ -8,12 +8,17 @@ Sequências de tools para as tarefas comuns. Todas começam por `getContext`, e
8
8
  Pedido típico: "faz o deploy do pedidos-api em homologação, sobe a minor".
9
9
 
10
10
  1. `listApps(search="pedidos")`: mais de uma parecida → pergunte qual.
11
- 2. `getApp(app_id)`: ache o ambiente `homol`; mais de um worker → pergunte em qual (ou faça um por vez). Anote o
12
- `running_image_tag` do worker e o `repository_id` do ambiente.
13
- 3. `listBuilds(app_id, repository_id)`: última versão publicada (ex.: `homol-1.4.0.0`); a minor vai gerar a próxima
14
- (`homol-1.5.0.0`).
15
- 4. Mostre ao usuário: aplicação, servidor/ambiente, versão em execução → versão nova. Confirme.
16
- 5. `deployApp(app_id, worker_id, part="minor")` → `requested_id`.
11
+ 2. `getApp(app_id)`: ache o ambiente `homol`. O deploy vai para **todos os workers** do ambiente, juntos (ver "Vários
12
+ workers"); só pergunte se o pedido citar um servidor. Anote o `running_image_tag` dos workers e o `repository_id`
13
+ do ambiente.
14
+ 3. `listBuilds(app_id, repository_id)`: última versão publicada (ex.: `1.4.0.0`); a minor vai gerar a próxima
15
+ (`1.5.0.0`). A tag é da app, sem ambiente: em prod, um Deploy do mesmo commit já publicado em homol
16
+ reaproveita a imagem (promoção, sem build), desde que os repositórios dos dois ambientes sejam a mesma fonte
17
+ (URL, branch, `build_path`, registry).
18
+ 4. Mostre ao usuário: aplicação, servidor/ambiente, versão em execução → versão nova. Pedido que já diz a app e o
19
+ ambiente ("faz o deploy do pedidos-api em prod") **é** a confirmação: não pergunte de novo. Confirme só o que o
20
+ pedido deixou em aberto (qual ambiente, qual app entre parecidas).
21
+ 5. `deployApp(app_id, worker_id, part="minor", confirm=true)`, um por worker → um `requested_id` cada.
17
22
  6. `getRequest(requested_id)` a cada poucos segundos até `finished=true`. O build costuma ser a etapa mais longa;
18
23
  para ver o progresso, `getBuildLog` com o `build_id` mais recente do `listBuilds` e `offset`.
19
24
 
@@ -33,9 +38,47 @@ só entra no próximo deploy/redeploy ([fluxo.md](fluxo.md)).
33
38
 
34
39
  ## Vários workers ou vários ambientes
35
40
 
36
- Um `deployApp` por worker. O build do mesmo repositório é compartilhado: duas solicitações seguidas para workers do
37
- mesmo ambiente não buildam duas vezes (a segunda reaproveita o build em andamento ou, sem commit novo, a última
38
- versão). Para promover de `homol` para `prod`, é um deploy em cada ambiente (cada um builda do próprio repositório).
41
+ Um `deployApp` por worker, **todos de uma vez** (sem esperar um terminar para mandar o próximo). O build do mesmo
42
+ repositório é compartilhado: solicitações seguidas para workers do mesmo ambiente não buildam duas vezes (a etapa
43
+ Build das outras diz "reaproveitado: executado por outra solicitação em andamento"). Para promover de `homol` para
44
+ `prod`, é um deploy em cada ambiente (cada um builda do próprio repositório; mesmo commit = promoção, sem build).
45
+
46
+ ## Produto com várias apps (server, GraphQL, front)
47
+
48
+ Pedido típico: "faz o deploy do pedidos" (pedidos-server, pedidos-graphql, pedidos-angular), ou "deploy do A e, quando
49
+ terminar, do B".
50
+
51
+ 1. **O que vai subir está no branch do ambiente.** O Hefesto builda do branch do repositório do ambiente (`getApp` →
52
+ `repository.branch`, em geral `master`). Mudança que só está na `development` não sobe: avise antes.
53
+ 2. **Migrations antes de tudo.** O Hefesto não roda migration ([preparar-app.md](preparar-app.md)). Compare
54
+ `poe status <banco> <ambiente>` com a última de `database/<banco>/migrations/versions/`. Pendente → `poe migrate
55
+ <banco> <ambiente>` **antes** do server: o código novo que lê uma coluna nova quebra contra o banco antigo (em
56
+ geral não só a função nova: toda consulta que carrega a tabela pelo ORM pede a coluna). Migration só de índice não
57
+ tem ordem com o deploy. Em produção, aplicar migration costuma exigir autorização explícita: peça, não contorne.
58
+ 3. **Uma camada por vez: server → GraphQL → front.** O GraphQL novo pede ao server campos que só a versão nova tem; o
59
+ front novo, operações que só o GraphQL novo tem. Cada camada vai em todos os workers juntos; a próxima só começa
60
+ quando **todas** as solicitações da anterior terminaram com sucesso (`getRequest` até `finished=true` em cada
61
+ `requested_id`). Apps sem dependência entre si (um MCP, um worker de fundo) podem ir junto com o server.
62
+ 4. **Falhou uma, para.** Não suba a camada seguinte por cima de uma que falhou: diagnostique ("Deploy falhou") e
63
+ reporte. A exceção é o autodeploy do próprio Hefesto (abaixo).
64
+ 5. **Vários produtos** ("o A, depois o B"): um produto inteiro por vez, na ordem pedida.
65
+
66
+ Para acompanhar várias solicitações, guarde os `requested_id` como saíram da resposta do `deployApp` e consulte com
67
+ eles mesmos; um id corrompido (espaço ou `\r` de fim de linha colado ao copiar entre comandos) dá `VALIDATION_ERROR`
68
+ em `requested_id`, e um laço de espera que trate isso como "ainda não terminou" fica preso para sempre.
69
+
70
+ ## Deploy do próprio Hefesto
71
+
72
+ O **hefesto-server** se reimplanta: antes do rollout ele espera as outras solicitações em execução terminarem (até
73
+ 30 min), e o rollout derruba o processo que executava a etapa Deploy. A reconciliação confere o container no Talos
74
+ depois do reinício e a recuperação conclui a solicitação sozinha (sucesso ou falha) em alguns minutos — até lá,
75
+ `getRequest` mostra a etapa Deploy em andamento. O MCP e o GraphQL do Hefesto também ficam fora do ar por alguns
76
+ segundos durante o próprio deploy: `getRequest` que falhar nessa janela é para repetir, não para desistir.
77
+
78
+ Terminou "Falhou" com "Deploy de `<versão>` do próprio hefesto não confirmado"? Antes de refazer, confira:
79
+ `getApp` do hefesto-server → cada worker com `running_image_tag` = versão do Build da solicitação e o
80
+ `/hefesto/server/health` em 200. Se estiver assim, a versão nova está no ar e só a confirmação se perdeu: não refaça o
81
+ deploy; reporte como concluído e cite a mensagem. Versão antiga no worker → aí sim é falha: siga "Deploy falhou".
39
82
 
40
83
  ## Deploy falhou
41
84
 
@@ -18,10 +18,12 @@ Dockerfile está na skill **docker**; aqui fica o que o Hefesto espera dele e do
18
18
 
19
19
  | Arg | Quem manda | Uso |
20
20
  | --- | --- | --- |
21
- | `CONFIGURATION` | Hefesto, só para `site` | nome do ambiente → `ng build --configuration $CONFIGURATION` |
21
+ | `CONFIGURATION` | Hefesto, sempre `production` (qualquer tipo e ambiente) | legado: o Dockerfile novo nem declara; o Angular builda sempre `--configuration production` |
22
22
 
23
- - Declare o `ARG` **depois** da instalação de dependências (um ARG entra no ambiente de todos os
24
- `RUN` seguintes; declarado antes, cada ambiente invalida o cache do `npm ci`).
23
+ - **O ambiente não entra no build.** A imagem é uma por versão e serve todos os ambientes; o front
24
+ escolhe o ambiente em runtime (`config.json`, ver "Site" e "Front servido pelo próprio Node").
25
+ - Se precisar de um `ARG`, declare **depois** da instalação de dependências (um ARG entra no ambiente
26
+ de todos os `RUN` seguintes; declarado antes, cada valor invalida o cache do `npm ci`).
25
27
  - O Hefesto pode repassar outros build args que o Dockerfile não declara; ARG não declarado é
26
28
  ignorado (só aviso). Não declare ARG para credencial: o valor fica no histórico da imagem.
27
29
  - Nada de URL de serviço ou segredo em build arg de service: isso é configuração de **runtime**.
@@ -47,10 +49,19 @@ Prefixo por variável, com o padrão de cada stack:
47
49
  | FastAPI | `root_path` ou `APIRouter(prefix=...)` vindo de settings (ver **fastapi**) |
48
50
  | SPA servida pelo próprio Node | base path da UI (`UI_BASE_PATH`) igual ao `baseHref` do build |
49
51
 
52
+ ### Front servido pelo próprio Node (service com UI)
53
+
54
+ O container recebe `APP_ENV=<ambiente>` do Hefesto (nome cadastrado em minúsculas; se a app cadastrou
55
+ `APP_ENV`, a dela vence). O servidor lê `<dist da UI>/brand/config/${APP_ENV}.json` **na subida**, valida
56
+ (`^[a-z0-9-]+$`, arquivo existe, é objeto JSON) e serve `{UI_BASE_PATH}/config.json` com `no-store`,
57
+ registrado **antes** do `express.static`. Em produção, problema aqui derruba a subida (o rollout descarta a
58
+ versão e a atual continua); fora dela, só avisa e a rota responde 404.
59
+
50
60
  ### Variáveis de ambiente
51
61
 
52
62
  Cadastre no Hefesto, por ambiente, tudo que o app lê do ambiente: banco, Redis, URLs de outros
53
- serviços, identidade no Argos (realm e app — ver **orfeu**), nível de log, `APP_ENV`/`NODE_ENV`.
63
+ serviços, identidade no Argos (realm e app — ver **orfeu**), nível de log, `NODE_ENV`. `APP_ENV` o
64
+ Hefesto já injeta com o nome do ambiente: cadastre só se o app precisar de outro valor.
54
65
 
55
66
  - Os arquivos `.env.<ambiente>` do repo são para rodar local; a imagem não os leva. Se o app carrega
56
67
  `.env.<APP_ENV>` com `load_dotenv`, o arquivo não existe no container e o valor tem que vir do
@@ -86,9 +97,14 @@ compatível com o schema da versão anterior — é o que permite rollback.
86
97
  ## Site (estático)
87
98
 
88
99
  - Estágio `site` (nome exato) `FROM scratch`, com o build em **`/dist`** e `CMD ["unused"]`.
89
- - Uma configuração no `angular.json` **para cada nome de ambiente** do Hefesto, com:
100
+ - **Uma imagem para todos os ambientes**: `ng build --configuration production` sempre, com:
90
101
  - `baseHref` = path do agent (com barra final: `/meu-app/`); agent na raiz = `/`;
91
- - endpoints do ambiente (`environment.<amb>.ts`) — o site não recebe variável de runtime.
102
+ - `src/brand/config/<ambiente>.json` **para cada nome de ambiente** do Hefesto (minúsculas), publicado
103
+ em `brand/config/` — só o que muda no ambiente (endpoints, `production`);
104
+ - `loadRuntimeConfig` no `main.ts` (ver **angular**) e nenhum `config.json` no `/dist`.
105
+ - No deploy, o Hefesto manda `config_env=<ambiente>` e o Talos (≥ 1.1.13) copia
106
+ `brand/config/<ambiente>.json` para `config.json`. Arquivo ausente ou inválido = `422` e a versão
107
+ anterior continua. O site não recebe variável de runtime: o `config.json` é a configuração dele.
92
108
  - `site_mode = spa` para app com rotas no cliente (deep link e F5 funcionam); `static` só para HTML
93
109
  puro.
94
110
  - Mesmo build servindo dois paths diferentes não funciona: `baseHref` é fixado no build.
@@ -56,7 +56,9 @@ rotas liberadas); fora do escopo, restrições e critérios de aceite verificáv
56
56
 
57
57
  - Itens `Txx` (próximo número livre) em `docs/sdd/tasks.md`: `- [ ] **Txx** · <camada/domínio> — <alteração> (data)`.
58
58
  **Um item = uma entrega verificável**, de preferência uma camada de um domínio (ou um app, numa mudança entre apps).
59
- - Ordem: server → GraphQL → Angular → banco/Argos → fechamento. Itens de pastas **disjuntas** podem ir em paralelo.
59
+ - Ordem de **implementar**: server → GraphQL → Angular → banco/Argos → fechamento. Itens de pastas **disjuntas** podem
60
+ ir em paralelo. A ordem de **subir** é outra: migration → server → GraphQL → Angular, uma camada só depois que a
61
+ anterior terminou em todos os workers (ver "Produto com várias apps" nos roteiros do MCP da skill **hefesto**).
60
62
  - Trabalho para vários agentes: `docs/sdd/plans/<tema>.md` (de `templates/plan.md`) com decisões tomadas, mapa de
61
63
  nomes, dependências, arquivos compartilhados e uma seção "Registro" por item.
62
64
 
@@ -34,7 +34,10 @@ task_exists() { grep -qE "\*\*$1\*\*" "$LIST"; }
34
34
  owner_of() { cat "$CLAIMS/$1/owner" 2>/dev/null; }
35
35
  state_of() { cat "$CLAIMS/$1/state" 2>/dev/null; }
36
36
  valid_task() { [[ "$1" =~ ^T[0-9]{2,}$ ]] || die "item inválido: '$1' (formato Txx)"; }
37
+ # O nome do worker vira caminho ($WORKERS/<nome>, apagado no unregister): só worker-N, nunca '..' ou '/'.
38
+ valid_worker() { [[ "$1" =~ ^worker-[0-9]+$ ]] || die "worker inválido: '$1' (formato worker-N)"; }
37
39
  need_owner() {
40
+ valid_worker "$1"
38
41
  local o; o="$(owner_of "$2")"
39
42
  [ -n "$o" ] || die "$2 não está reservado"
40
43
  [ "$o" = "$1" ] || die "$2 pertence a $o, não a $1"
@@ -53,19 +56,24 @@ case "${1:-}" in
53
56
  register)
54
57
  mkdir -p "$WORKERS"
55
58
  n=1
56
- while ! mkdir "$WORKERS/worker-$n" 2>/dev/null; do n=$((n+1)); done
59
+ # mkdir falha porque o nome já existe (o próximo) -- ou por permissão/disco: aí para em vez de girar para sempre.
60
+ while ! mkdir "$WORKERS/worker-$n" 2>/dev/null; do
61
+ [ -d "$WORKERS/worker-$n" ] || die "não foi possível criar $WORKERS/worker-$n (permissão ou disco)"
62
+ n=$((n+1))
63
+ done
57
64
  now > "$WORKERS/worker-$n/since"
58
65
  echo "worker-$n"
59
66
  ;;
60
67
  unregister)
61
68
  [ -n "${2:-}" ] || die "uso: coord.sh unregister <worker>"
69
+ valid_worker "$2"
62
70
  [ -d "$WORKERS/$2" ] || die "$2 não está registrado"
63
71
  rm -rf "$WORKERS/$2" && echo "$2 liberado"
64
72
  ;;
65
73
  claim)
66
74
  w="${2:-}"; t="${3:-}"
67
75
  [ -n "$w" ] && [ -n "$t" ] || die "uso: coord.sh claim <worker> <Txx>"
68
- valid_task "$t"; need_list
76
+ valid_task "$t"; valid_worker "$w"; need_list
69
77
  [ -d "$WORKERS/$w" ] || die "$w não está registrado (rode: coord.sh register)"
70
78
  task_exists "$t" || die "$t não existe em $LIST"
71
79
  mkdir -p "$CLAIMS"