@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.
- package/README.md +10 -8
- package/agents/revisor-deploy.md +9 -4
- package/bin/install.js +41 -9
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +2 -2
- package/skills/acropole/references/arquitetura.md +3 -3
- package/skills/acropole/references/fluxos/app-novo.md +2 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +51 -15
- package/skills/angular/SKILL.md +34 -15
- package/skills/angular/references/armadilhas.md +16 -6
- package/skills/angular/references/estrutura.md +118 -50
- package/skills/angular/references/testes-build.md +25 -17
- package/skills/auto-servico/references/roteiros.md +1 -1
- package/skills/auto-servico/references/tools.md +1 -1
- package/skills/docker/SKILL.md +17 -7
- package/skills/docker/references/modelos.md +23 -9
- package/skills/docker/references/porques.md +19 -6
- package/skills/hefesto/SKILL.md +53 -28
- package/skills/hefesto/references/conceitos.md +16 -8
- package/skills/hefesto/references/diagnostico.md +12 -2
- package/skills/hefesto/references/fluxo.md +51 -29
- package/skills/hefesto/references/mcp-roteiros.md +52 -9
- package/skills/hefesto/references/preparar-app.md +22 -6
- package/skills/orquestracao/SKILL.md +3 -1
- package/skills/orquestracao/scripts/coord.sh +10 -2
- package/skills/trismegisto/SKILL.md +57 -16
- package/skills/trismegisto/references/angular-api.md +3666 -64
- package/skills/trismegisto/references/angular-exports.md +8562 -2554
- package/skills/trismegisto/references/angular-recipes.md +315 -0
- package/skills/trismegisto/references/angular-types.md +92 -0
- package/skills/trismegisto/references/angular.md +67 -10
- package/skills/trismegisto/references/catalogo/icones.json +7 -0
- package/skills/trismegisto/references/catalogo/seletores.json +12102 -3443
- package/skills/trismegisto/references/catalogo/tokens.json +114 -0
- package/skills/trismegisto/references/spine-api.md +1113 -157
- package/skills/trismegisto/references/spine-recipes.md +72 -35
- package/skills/trismegisto/references/spine.md +54 -27
package/skills/hefesto/SKILL.md
CHANGED
|
@@ -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`
|
|
31
|
-
|
|
32
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
54
|
-
`
|
|
55
|
-
Deploy implanta exatamente a imagem que ele produziu
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
70
|
-
→
|
|
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
|
|
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 →
|
|
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
|
-
- [ ]
|
|
87
|
-
(`
|
|
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
|
-
- **
|
|
106
|
-
|
|
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
|
|
138
|
-
|
|
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):
|
|
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
|
|
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
|
|
67
|
-
-
|
|
68
|
-
-
|
|
69
|
-
|
|
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 é
|
|
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
|
-
|
|
|
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
|
|
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
|
|
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
|
|
20
|
-
|
|
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. **
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
34
|
-
paralelo), no `build_path
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
da solicitação (`execution_image`), e é ela que o Deploy implanta.
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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`)
|
|
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
|
|
87
|
-
|
|
88
|
-
|
|
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
|
|
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 é
|
|
150
|
-
|
|
151
|
-
`
|
|
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
|
|
12
|
-
`running_image_tag`
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
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
|
|
37
|
-
|
|
38
|
-
|
|
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,
|
|
21
|
+
| `CONFIGURATION` | Hefesto, sempre `production` (qualquer tipo e ambiente) | legado: o Dockerfile novo nem declara; o Angular builda sempre `--configuration production` |
|
|
22
22
|
|
|
23
|
-
-
|
|
24
|
-
|
|
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, `
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
-
|
|
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"
|