@acropole/skills 1.3.0 → 1.4.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 (33) hide show
  1. package/README.md +5 -4
  2. package/package.json +2 -3
  3. package/skills/acropole/SKILL.md +1 -0
  4. package/skills/acropole/references/arquitetura.md +29 -5
  5. package/skills/acropole/references/fluxos/app-novo.md +4 -4
  6. package/skills/apollo/references/subscriptions.md +10 -4
  7. package/skills/apollo/references/testes-build.md +1 -0
  8. package/skills/docker/SKILL.md +3 -0
  9. package/skills/docker/references/podman-local.md +73 -0
  10. package/skills/express/references/dados.md +3 -1
  11. package/skills/fastapi/SKILL.md +4 -4
  12. package/skills/fastapi/references/banco.md +53 -50
  13. package/skills/fastapi/references/estrutura.md +2 -2
  14. package/skills/fastapi/references/integracoes.md +8 -0
  15. package/skills/hefesto/SKILL.md +49 -14
  16. package/skills/hefesto/references/diagnostico.md +15 -5
  17. package/skills/hefesto/references/fluxo.md +64 -35
  18. package/skills/hefesto/references/mcp-diagnostico.md +44 -0
  19. package/skills/hefesto/references/mcp-roteiros.md +53 -0
  20. package/skills/hefesto/references/mcp-tools.md +94 -0
  21. package/skills/orfeu/SKILL.md +1 -1
  22. package/skills/orfeu/references/diferencas.md +1 -1
  23. package/skills/orfeu/references/node.md +1 -1
  24. package/skills/orquestracao/SKILL.md +1 -1
  25. package/skills/orquestracao/templates/spec.md +1 -1
  26. package/skills/trismegisto/SKILL.md +2 -2
  27. package/skills/trismegisto/references/angular-api.md +7 -5
  28. package/skills/trismegisto/references/angular-exports.md +12 -1
  29. package/skills/trismegisto/references/angular.md +10 -0
  30. package/skills/trismegisto/references/catalogo/seletores.json +8 -0
  31. package/skills/trismegisto/references/spine-api.md +148 -9
  32. package/skills/trismegisto/references/spine-recipes.md +1 -1
  33. package/skills/trismegisto/references/spine.md +1 -1
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: hefesto
3
- description: Processo de deploy pela plataforma Hefesto (build pelo Ciclope, entrega pelo Talos, roteamento pelo Caddy de cada origin) — conceitos (projeto, aplicação service/site, repositório por ambiente, registry, origin, agent com path, worker, domínio, variáveis por ambiente, grupos), o que um app precisa ter para ser implantado, solicitações de Deploy/Redeploy, versões e tags de imagem, rollback, logs e diagnóstico de falhas. Use ao preparar um app para entrar no Hefesto, cadastrar ou revisar o deploy dele, ou investigar build/deploy/rota que falhou. Não use para escrever o Dockerfile em si (use docker), nem para o código do app (angular, express, apollo, fastapi) ou autenticação (orfeu).
3
+ description: Processo de deploy pela plataforma Hefesto (build pelo Ciclope, entrega pelo Talos, roteamento pelo Caddy de cada origin) — conceitos (projeto, aplicação service/site, repositório por ambiente, registry, origin, agent com path, worker, domínio, variáveis por ambiente, grupos), o que um app precisa ter para ser implantado, solicitações de Deploy/Redeploy, versões e tags de imagem, rollback, logs e diagnóstico de falhas — e o MCP de deploy (hefesto-mcp), com que um agente de IA consulta e faz deploy/redeploy das aplicações que a pessoa opera (x-app-token pessoal, escopos deploy.*). Use ao preparar um app para entrar no Hefesto, cadastrar ou revisar o deploy dele, investigar build/deploy/rota que falhou, configurar o .mcp.json de um agente para o Hefesto ou fazer deploy pelas tools do hefesto-mcp. Não use para escrever o Dockerfile em si (use docker), nem para o código do app (angular, express, apollo, fastapi) ou autenticação (orfeu).
4
4
  ---
5
5
 
6
6
  # hefesto
@@ -19,7 +19,7 @@ contrato entre os dois: o que não foi publicado lá não pode ser implantado.
19
19
 
20
20
  Skills relacionadas: **docker** (como escrever o Dockerfile que o Hefesto builda), **fastapi**,
21
21
  **express**, **apollo**, **angular** (o app em si), **orfeu** (identidade do app no Argos, auditoria
22
- e o flush dela no SIGTERM).
22
+ e o flush dela no SIGTERM), **auto-servico** (o MCP equivalente do Argos).
23
23
 
24
24
  ## Regras essenciais
25
25
 
@@ -37,19 +37,24 @@ e o flush dela no SIGTERM).
37
37
  service publicado em `/meu-app/api` precisa responder em `/meu-app/api/...` (prefixo configurável
38
38
  no app: `API_PREFIX`, `root_path`, `CONTEXT_PATH`). Para **site** o prefixo é removido, mas o
39
39
  `baseHref` do Angular tem que ser o próprio path, senão os assets saem da raiz e dão 404.
40
+ O path é sempre o **contexto do app** (`/<app>`, `/<app>/server`, `/<app>/mcp`): nunca publique nem
41
+ configure um serviço em `/api` genérico, nem troque o contexto para fazer uma URL funcionar.
40
42
  5. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
41
43
  `podman run` por um `--env-file` temporário (600, apagado logo depois; nunca `-e K=V` no argv) —
42
44
  **só no próximo deploy/redeploy/rollback**. Arquivos `.env.*` não vão para a imagem
43
45
  (`.dockerignore`). Segredo **sem valor padrão** no Dockerfile/código: faltou no cadastro, o app cai na
44
46
  subida em vez de aceitar `changeme`.
45
- 6. **Processo principal recebe o SIGTERM.** Toda troca de versão faz `podman stop` (10 s de prazo e
46
- depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
47
+ 6. **Processo principal recebe o SIGTERM.** Toda troca de versão para a versão antiga com SIGTERM (até
48
+ 30 s, depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
47
49
  perde a fila de auditoria do Orfeu e atrasa todo deploy. Ver **docker**.
48
- 7. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O Talos
49
- não espera health: "Deploy concluído" significa container criado, não app saudável — confira.
50
- 8. **Versão é do registry**: tag `<ambiente>-<major>.<minor>.<fix>.<test>` (ex.: `homol-1.4.0.2`).
51
- O build escolhe qual parte incrementar; a retenção mantém só as últimas N por ambiente (padrão 5),
52
- menos as que algum worker está rodando. Rollback só para versão que ainda existe no registry.
50
+ 7. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O deploy de
51
+ service é um rollout: a versão nova sobe ao lado da atual e só entra se o `health_path` responder
52
+ < 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.
53
58
  9. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
54
59
  workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
55
60
  distribuído. Ver `references/preparar-app.md`.
@@ -63,11 +68,12 @@ Solicitação "Redeploy de Serviços|Sites" Início → Deploy → Fim
63
68
  Início valida app, agent, worker e se o repositório é do MESMO ambiente do origin do worker
64
69
  Build Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
65
70
  → push <registry>/<app>:<ambiente>-<versão> → retenção das antigas
66
- Deploy Hefesto → Talos do origin: pull da versão mais nova do ambiente
67
- service: stop + rm do container antigo → run -d --restart unless-stopped -e ... -p host:app
68
- site: create (sem rodar) → copia /dist para o volume do Caddy
69
- → Hefesto regenera o Caddyfile do origin e o Talos recarrega o Caddy (sem downtime)
70
- Rollback mesmo passo Deploy, com uma versão escolhida da lista do registry
71
+ 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
75
+ → Hefesto regenera o Caddyfile do origin; o Talos valida e recarrega o Caddy
76
+ Rollback solicitação própria (Início → Deploy → Fim) com uma versão escolhida da lista do registry
71
77
  ```
72
78
 
73
79
  Cada etapa grava o histórico (`current` → `processing` → `success`/`error`, com a mensagem) e
@@ -109,6 +115,32 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
109
115
  - **Build passa local e falha no Ciclope**: depende de arquivo ignorado pelo git, de `.npmrc` local
110
116
  ou de `node_modules` do contexto.
111
117
 
118
+ ## Deploy por um agente de IA (MCP)
119
+
120
+ O **hefesto-mcp** (`POST <host>/hefesto/mcp`, Streamable HTTP) deixa um agente fazer, por tools, o que o Operador faz
121
+ na tela de Operação. Não tem regra própria: cada tool chama o hefesto-server **com o token da pessoa**, então ela só
122
+ vê e opera as aplicações dos grupos dela (Desenvolvedor/Administrador: todas). **Uma conexão por pessoa**, com o
123
+ token de aplicação pessoal (`x-app-token`, criado logado no Hefesto, em variável de ambiente, nunca no git):
124
+
125
+ ```json
126
+ { "mcpServers": { "hefesto": { "type": "http", "url": "https://<host>/hefesto/mcp",
127
+ "headers": { "x-app-token": "${HEFESTO_TOKEN}" } } } }
128
+ ```
129
+
130
+ `x-mcp-scopes: deploy.*.read` dá uma conexão só de consulta. O agente trabalha assim:
131
+
132
+ 1. `getContext` → `listApps(search)` → `getApp(app_id)`: por ambiente, o repositório e os workers (servidor, status,
133
+ versão em execução). Todo id sai daí; nunca suposição.
134
+ 2. Mostre o que muda (versão atual → nova, servidor/ambiente) e **confirme**, principalmente em produção.
135
+ 3. `deployApp(app_id, worker_id, part)` (build + implantação) ou `redeployApp(app_id, worker_id)` (só reimplanta a
136
+ mais recente); `scheduled_for` agenda. A resposta volta na hora com o `requested_id`.
137
+ 4. `getRequest` até `finished=true`; falhou → etapa com erro e `getBuildLog` (final do log).
138
+
139
+ Também estão no MCP: `cancelRequest`, `rollbackApp` (abre uma solicitação de Rollback; exige a permissão de
140
+ rollback no Argos), `getWorkerHistory` e `listEnvironmentVars`/`setEnvironmentVars` (segredos sem valor). Cadastros
141
+ (app, repositório, domínio, catálogos do motor) ficam na tela. Tools, roteiros e erros:
142
+ `references/mcp-tools.md`, `references/mcp-roteiros.md`, `references/mcp-diagnostico.md`.
143
+
112
144
  ## Índice de referências
113
145
 
114
146
  | Arquivo | Conteúdo |
@@ -117,3 +149,6 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
117
149
  | `references/fluxo.md` | Deploy ponta a ponta (Ciclope, registry, Talos, Caddy), versões e retenção, redeploy, rollback, solicitações e seus estados |
118
150
  | `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 |
119
151
  | `references/diagnostico.md` | Onde olhar (histórico, logs do container, Caddyfile), mensagens de erro do Hefesto e o que significam, erros comuns com causa |
152
+ | `references/mcp-tools.md` | hefesto-mcp: tools com argumentos, escopos, resources e prompts |
153
+ | `references/mcp-roteiros.md` | hefesto-mcp: deploy, redeploy, agendamento, vários workers, falha e revisão do que está rodando |
154
+ | `references/mcp-diagnostico.md` | hefesto-mcp: erros ao conectar e nas tools, e falhas por etapa da solicitação |
@@ -10,8 +10,11 @@
10
10
  3. **Status/estatísticas do container**: reiniciando em loop = processo morrendo na subida (config,
11
11
  porta, dependência).
12
12
  4. **Caddyfile do origin** (Origins → configuração do Caddy): confirma path, upstream
13
- (`<app>-<porta>:<porta do app>`) e domínio que o Hefesto gerou.
14
- 5. **`/health` pelo domínio e pelo path**: separa "app quebrado" de "rota errada".
13
+ (`<app>-<porta>:<porta do app>`) e domínio que o Hefesto gerou. Origin marcado **"Caddy desatualizado"**:
14
+ o último envio falhou (a aba Caddy mostra o erro e a próxima tentativa); use **Ressincronizar Caddy**.
15
+ 5. **Status do worker e o motivo** (tela de Aplicações, embaixo do status; `status_message` no MCP): deploy
16
+ desfeito pelo health check, falha do Talos ou reconciliação depois de um restart.
17
+ 6. **`/health` pelo domínio e pelo path**: separa "app quebrado" de "rota errada".
15
18
 
16
19
  ## Mensagens do Hefesto
17
20
 
@@ -28,6 +31,12 @@
28
31
  | podman login failed | usuário/senha do registry | cadastro do registry |
29
32
  | podman pull/run failed (na etapa Deploy) | origin sem acesso ao registry, porta do host ocupada, imagem sem o estágio certo | ver detalhe; porta → troque a do worker |
30
33
  | podman cp ... /dist ... no such file | site buildado sem `/dist` na raiz | estágio `site` precisa de `COPY --from=build .../browser /dist` |
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
+ | 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
+ | 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
+ | A solicitação já está em execução (409) | outro avanço da mesma solicitação está rodando | espere terminar |
38
+ | 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
+ | 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 |
31
40
  | nenhuma função registrada para este step | etapa adicionada ao fluxo sem implementação no servidor | remova a etapa do fluxo ou implemente |
32
41
  | Você não tem acesso a esta aplicação. / Agente ou worker não pertencem à aplicação informada. | usuário sem grupo do app, ou ids misturados | vincule o grupo ao app |
33
42
 
@@ -45,9 +54,10 @@
45
54
  | Site: build falha com "Configuration 'x' is not set" | nome do ambiente sem configuração no `angular.json` | `CONFIGURATION` = nome do ambiente, exato |
46
55
  | Site antigo depois do deploy | cache do navegador no `index.html` | arquivos com hash podem ter cache longo; `index.html` não |
47
56
  | 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 |
48
- | Variável nova não aparece | variáveis só entram no `run` | faça Redeploy |
49
- | Deploy "concluído" mas app fora | o Talos não espera health | sempre confira logs e `/health` depois |
50
- | Cada deploy demora 10 s a mais; auditoria perdida | SIGTERM não chega ao processo | CMD em forma exec, app trata SIGTERM (ver **docker**) |
57
+ | Variável nova não aparece | variáveis só entram quando o container é criado | faça Redeploy |
58
+ | Worker preso em "deploying" | o server caiu no meio do rollout | a reconciliação resolve sozinha em até ~15 min (vira `running` ou `failed`, com o motivo) |
59
+ | Deploy "concluído" mas app fora | o `/health` responde < 400 antes de a app estar pronta (ou não há `health_path` e a porta abre cedo) | faça o `/health` conferir as dependências de verdade; sem ele, o Talos só confere a porta |
60
+ | Cada deploy demora 30 s a mais; auditoria perdida | SIGTERM não chega ao processo (o rollout espera até 30 s antes de matar) | CMD em forma exec, app trata SIGTERM (ver **docker**) |
51
61
  | Job/coleta executando em dobro | mais de um worker (ou `--workers`) com agendador no lifespan | separe o papel ou use lock (ver `preparar-app.md`) |
52
62
  | Build lento sempre do zero | `COPY . .` antes do install, ARG antes do install, contexto com `node_modules`/`.git` | ver **docker** |
53
63
  | Build passa local, falha no Ciclope | arquivo não versionado, `.npmrc` local, lockfile desatualizado (`npm ci` exige lockfile em sincronia) | builde a partir de um clone limpo |
@@ -8,7 +8,7 @@
8
8
  │ │
9
9
  └──deploy──▶ Talos (origin do ambiente) ◀─┘ pull
10
10
  │
11
- ├─ service: podman run ─┐
11
+ ├─ service: rollout ─┐
12
12
  ├─ site: /dist → volume ├─▶ Caddy do origin ─▶ usuários
13
13
  └─ Caddyfile (do Hefesto)┘
14
14
  ```
@@ -33,44 +33,58 @@
33
33
  3. **Build**: `podman build` (Buildah, não Docker) com `--jobs 2` (estágios independentes em
34
34
  paralelo), no `build_path`. Para site: `--target site --build-arg CONFIGURATION=<ambiente>`.
35
35
  Limite padrão de 900 s; estourou = 504 com as últimas linhas da saída.
36
- 4. **Push** para `<registry>/<app_name>:<ambiente>-<versão>`.
37
- 5. **Retenção** (best-effort, nunca derruba o build): apaga as tags do ambiente além das N mais
38
- novas (padrão 5), **exceto** as que algum worker está rodando. Tags de outros ambientes nunca são
39
- tocadas.
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.
40
43
 
41
44
  O cache do build fica no host do Ciclope (camadas + `--mount=type=cache`); imagens sem tag só são
42
45
  limpas depois de dias, para não perder o cache de quem builda com frequência. Por isso a ordem dos
43
46
  `COPY` no Dockerfile faz diferença real no tempo de build (ver **docker**).
44
47
 
45
- > O Podman só cancela um build no **próximo** passo do Dockerfile. Um `npm ci` ou `ng build` travado
46
- > continua rodando no host mesmo depois do timeout do Ciclope — por isso os passos longos levam
47
- > `timeout -k` no próprio Dockerfile.
48
+ > Cancelar a solicitação durante o Build fecha o stream: o Ciclope encerra o comando em andamento e não
49
+ > publica a imagem. Mesmo assim, os passos longos do Dockerfile levam `timeout -k`, para um `npm ci` ou
50
+ > `ng build` travado não segurar o host até o limite do Ciclope.
48
51
 
49
52
  ## 3. Deploy (Talos)
50
53
 
51
- O Hefesto resolve a **versão mais nova publicada** para o ambiente do origin e chama o Talos daquele
54
+ Na etapa Deploy de uma solicitação **Deploy**, o Hefesto implanta **exatamente a imagem que o Build desta
55
+ 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
52
57
  origin.
53
58
 
54
- ### service
55
- 1. `podman login` + `pull` da imagem;
56
- 2. `podman stop` do container atual (SIGTERM, 10 s, depois SIGKILL) e `rm`;
57
- 3. `podman run -d --name <app>-<porta> -p <porta do worker>:<porta do app> --restart unless-stopped
58
- --network <rede do origin> --env-file <arquivo temporário> <imagem>`; as variáveis do (app,
59
- ambiente) vão num arquivo com permissão 600, apagado assim que o `run` termina — nunca como `-e K=V`
60
- no argv, onde apareceriam em `ps` no host e no log de comandos;
61
- 4. worker vira `running` com a tag; o Hefesto regenera o Caddyfile do origin e o Talos recarrega o
62
- Caddy.
59
+ ### service: rollout sem indisponibilidade
60
+ 1. `podman login` + `pull`;
61
+ 2. sobe `<app>-<porta>-next` com a imagem nova, sem porta no host e com o alias de rede do container atual: o
62
+ Caddy passa a balancear entre as duas versões;
63
+ 3. espera a nova ficar **saudável**: HTTP < 400 no `health_path` da aplicação ou, sem ele, a porta aceitando
64
+ conexão por 5 s (até 90 s). Não ficou: remove a `-next` e responde **422** com o fim do log dela — a versão
65
+ atual **nunca saiu do ar** e o worker volta ao status anterior (rollback automático; a solicitação falha com
66
+ a mensagem);
67
+ 4. para a atual (SIGTERM, até 30 s), recria `<app>-<porta>` com a porta do host, espera saudável e remove a
68
+ `-next`. Se a recriação falhar, a `-next` segue atendendo pelo alias e o resultado é `degraded` (um novo
69
+ deploy normaliza);
70
+ 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;
72
+ 6. worker `running` com a tag; o Hefesto regenera o Caddyfile do origin.
63
73
 
64
74
  Consequências:
65
- - há uma janela de indisponibilidade entre o stop e o processo novo ficar pronto (um worker só). Com
66
- dois ou mais workers, faça o deploy **um de cada vez**: o Caddy tira da rotação o que estiver fora;
67
- - `running` = container criado. Se o processo cair logo depois, o `--restart` fica reiniciando e o
68
- Hefesto não percebe: confira os logs e o `/health`;
69
- - a rede do origin permite que o app alcance outros serviços daquele servidor pelo nome do container.
75
+ - não há janela de indisponibilidade pela rota do Caddy, nem com um worker só; não é preciso deployar "um de
76
+ cada vez" para evitar queda;
77
+ - a app precisa de um `/health` que responda < 400 só quando está pronta de verdade (ver `preparar-app.md`): é
78
+ ele que decide se a versão nova entra ou é descartada;
79
+ - sem `DOCKER_NETWORK` no Talos (sem alias) ou com Talos antigo, cai no caminho antigo (`/deploy/run`: para e
80
+ sobe, com janela de indisponibilidade);
81
+ - se o processo do Hefesto morrer no meio, a reconciliação confere o inventário do Talos e tira o worker de
82
+ `deploying` (vira `running` ou `failed`, com o motivo em `status_message`).
70
83
 
71
84
  ### site
72
85
  1. `pull`, `podman create` (o container nunca roda — por isso o `CMD ["unused"]` no estágio `site`);
73
- 2. esvazia a pasta do agent no volume do Caddy e copia `/dist/.` da imagem para lá;
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;
74
88
  3. Caddyfile regenerado: `file_server` na pasta, `uri strip_prefix <path>`, e `try_files {path}
75
89
  /index.html` se `site_mode = spa`.
76
90
 
@@ -82,32 +96,46 @@ Gerado inteiro a cada mudança (agent, domínio, vínculo, deploy, remoção), u
82
96
  - `/p` sem barra também casa;
83
97
  - `encode gzip` em todos os blocos.
84
98
 
85
- Falha ao sincronizar o Caddy não falha o deploy (o próximo evento tenta de novo).
99
+ O Talos valida o Caddyfile (`caddy validate`) antes de trocar o ativo: inválido é recusado e o último válido
100
+ continua no ar. Falha ao sincronizar não falha o deploy: o origin fica marcado **"Caddy desatualizado"** e o
101
+ Hefesto reenvia com backoff (ou na hora, pelo botão **Ressincronizar Caddy** na tela de Origens). Remover a
102
+ última rota de um origin envia um Caddyfile vazio.
86
103
 
87
104
  ## 4. Fim
88
105
 
89
- Marca a solicitação como Finalizada. Em qualquer etapa com erro: execução `error` com a mensagem e
90
- solicitação Falhou. Uma solicitação parada pode ser **avançada** de novo: retoma da etapa que falhou
91
- (ou da seguinte, se a última deu certo).
106
+ Marca a solicitação como Concluída. Em qualquer etapa com erro: execução `error` com a mensagem e solicitação
107
+ Falhou. Uma solicitação parada pode ser **avançada** de novo: retoma da etapa que falhou (ou da seguinte, se a
108
+ última deu certo). A mesma solicitação não roda duas vezes ao mesmo tempo (um segundo "Avançar" responde 409).
109
+ Se o server reiniciar no meio, a recuperação retoma Início/Fim ou marca Build/Deploy como falha ("Interrompida:
110
+ o server reiniciou durante a etapa X"), para alguém conferir o worker antes de avançar.
92
111
 
93
112
  ## Redeploy
94
113
 
95
- Mesmo passo 3 sem passar pelo build: implanta a última versão publicada do ambiente. Use para:
114
+ Solicitação **Redeploy** (Início → Deploy → Fim): o passo 3 sem build, com a última versão publicada do
115
+ ambiente. Use para:
96
116
  - aplicar variáveis de ambiente alteradas;
97
117
  - recriar um container que alguém parou ou removeu à mão;
98
118
  - publicar em um worker novo uma versão que já existe.
99
119
 
100
120
  ## Rollback
101
121
 
102
- Escolha a versão na lista de builds do ambiente (vem do registry) e o Hefesto roda o passo 3 com
103
- ela. Regras:
104
- - só versões que ainda existem no registry; a retenção apaga as antigas, menos as que estão rodando;
122
+ Solicitação **Rollback** (Início → Deploy → Fim) com a versão escolhida na lista de builds do ambiente
123
+ (vem do registry); aparece no histórico de solicitações e no tempo real, como as outras. Pelo MCP,
124
+ `rollbackApp` abre a mesma solicitação (sem versão, vai para a publicada anterior à que o worker roda).
125
+ Regras:
126
+ - exige a permissão de rollback no Argos (`apps:agents:workers:rollback`), além do acesso à aplicação;
127
+ - só versões que ainda existem no registry; a retenção apaga as antigas desta instalação, menos as que estão
128
+ rodando;
105
129
  - variáveis de ambiente são as **atuais**, não as da época da versão. Se a versão antiga precisa de
106
130
  uma variável que foi removida/renomeada, ajuste antes;
107
131
  - migrations de banco **não** voltam. Versão antiga contra schema novo precisa ser compatível
108
132
  (migrations aditivas, nunca destrutivas no mesmo release);
109
- - site: o `/dist` da versão escolhida substitui o atual.
110
- - No perfil Operador a tela não oferece rollback.
133
+ - 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).
135
+
136
+ Todo deploy, redeploy e rollback de um worker fica no **histórico do worker** (aba Histórico da aplicação,
137
+ `getWorkerHistory` no MCP), com a origem (solicitação, tela legada, MCP, API), as tags anterior e nova e o
138
+ resultado.
111
139
 
112
140
  ## Versões: qual parte incrementar
113
141
 
@@ -119,4 +147,5 @@ ela. Regras:
119
147
  | `test` | build de teste/validação em ambiente não produtivo |
120
148
 
121
149
  A numeração é por ambiente: `homol-1.3.0.0` e `prod-1.3.0.0` são builds diferentes (branch e
122
- `CONFIGURATION` de cada ambiente). Promover para produção = novo build no repositório de prod.
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.
@@ -0,0 +1,44 @@
1
+ # Diagnóstico do hefesto-mcp
2
+
3
+ Formato de erro (MES): `{ "error": { "code", "message", "details"? } }`. Antes da sessão (credencial, sessão,
4
+ origem) vem no corpo HTTP; dentro de uma tool vem como resultado `isError: true`. Quando quem recusa é o
5
+ hefesto-server, a `message` é a dele e `details.status` traz o HTTP original.
6
+
7
+ ## Ao conectar (HTTP)
8
+
9
+ | Sintoma | Causa | Ação |
10
+ | --- | --- | --- |
11
+ | 401 `AUTHENTICATION_ERROR` | Header ausente ou com nome errado (é `x-app-token`, não `Authorization`); token expirado, revogado ou de outro realm (criado fora do Hefesto); dono desativado | Confira o header e a variável de ambiente; crie o token logado no Hefesto |
12
+ | 403 "Origem não permitida" | Chamada de navegador (header `Origin`) | Use um cliente MCP de linha de comando/desktop |
13
+ | 400 `x-mcp-scopes inválido` | Caractere fora de `a-z . *` no header | Ex.: `deploy.*.read` |
14
+ | 400 "Mcp-Session-Id obrigatório" | Cliente sem suporte a sessão do Streamable HTTP | Atualize o cliente MCP |
15
+ | 404 com `Mcp-Session-Id` | Sessão expirada (padrão 8 h, nunca além da validade do token), encerrada ou de outro token | Normal: o cliente refaz o `initialize` |
16
+ | `/hefesto/mcp/health` 503 | `checks.server` ou `checks.auth` = `error`: hefesto-server ou argos-auth fora/inacessível pelo MCP | Quem opera a plataforma |
17
+
18
+ ## Dentro de uma tool
19
+
20
+ | Código | Mensagem típica | Causa | Ação |
21
+ | --- | --- | --- | --- |
22
+ | `AUTHORIZATION_ERROR` | "Escopo insuficiente" (`details.missing`) | Conexão com `x-mcp-scopes` restrito (ex.: `deploy.*.read`) | Use a conexão sem restrição |
23
+ | `AUTHORIZATION_ERROR` | "Você não tem acesso a esta aplicação." | A pessoa não está num grupo do Hefesto ligado à aplicação | Quem administra o Hefesto vincula o grupo |
24
+ | `AUTHORIZATION_ERROR` | "Insufficient permissions." | O nível do token não tem a operação no Argos | Token com outro nível, ou liberar a operação para o grupo |
25
+ | `AUTHORIZATION_ERROR` | "Agente ou worker não pertencem à aplicação informada." | `worker_id` de outra aplicação | Pegue o worker do `getApp` da aplicação certa |
26
+ | `RESOURCE_NOT_FOUND` | "Worker não encontrado nesta aplicação" | `worker_id` que não está em nenhum agent da aplicação | Idem |
27
+ | `RESOURCE_NOT_FOUND` | "Solicitação não encontrada." | Id errado, ou solicitação de aplicação que a pessoa não opera | Use `listRequests` |
28
+ | `VALIDATION_ERROR` | `details.issues` | Argumento fora do contrato: id que não é UUID, `part` inválido, horário sem fuso | Corrija o argumento |
29
+ | `VALIDATION_ERROR` | "Nenhum repositório configurado para o ambiente deste worker" | Ambiente sem repositório: não há de onde buildar | `redeployApp`, ou cadastrar o repositório ([conceitos.md](conceitos.md)) |
30
+ | `VALIDATION_ERROR` | "O horário do agendamento precisa ser no futuro." / "até 30 dias" | `scheduled_for` a menos de 30 s ou além de 30 dias | Ajuste o horário |
31
+ | `TIMEOUT` | "não respondeu em 15s" | hefesto-server lento | Tente de novo; deploy/redeploy não ficam presos (rodam em segundo plano) |
32
+
33
+ ## Solicitação que terminou com falha
34
+
35
+ `getRequest` → etapa com `state=error`:
36
+
37
+ | Etapa | Mensagens comuns | Onde olhar |
38
+ | --- | --- | --- |
39
+ | Início | repositório de outro ambiente; agent/worker inválidos | `getApp` (ambiente do agent x repositório) |
40
+ | Build | "Falha no build", "nenhuma alteração desde o build X" (pulou: não é erro) | `getBuildLog` sem offset; skill **docker** |
41
+ | Deploy | versão que não existe mais no registry; porta ocupada; container que não sobe | [diagnostico.md](diagnostico.md) |
42
+
43
+ O hefesto-server também grava cada chamada do MCP na auditoria do Argos, com o mesmo `trace_id` do
44
+ `_meta.trace_id` da tool.
@@ -0,0 +1,53 @@
1
+ # Roteiros de deploy pelo MCP
2
+
3
+ Sequências de tools para as tarefas comuns. Todas começam por `getContext`, e todo id vem de uma listagem
4
+ (`listApps`, `getApp`, `listBuilds`, `listRequests`), nunca de suposição.
5
+
6
+ ## Deploy de uma versão nova
7
+
8
+ Pedido típico: "faz o deploy do pedidos-api em homologação, sobe a minor".
9
+
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`.
17
+ 6. `getRequest(requested_id)` a cada poucos segundos até `finished=true`. O build costuma ser a etapa mais longa;
18
+ para ver o progresso, `getBuildLog` com o `build_id` mais recente do `listBuilds` e `offset`.
19
+
20
+ Ambiente sem repositório (`repository: null` no `getApp`) não tem de onde buildar: só redeploy.
21
+
22
+ ## Redeploy (mesma versão)
23
+
24
+ Para aplicar variável de ambiente alterada ou reiniciar a aplicação com a versão que já está publicada:
25
+ `getApp` → worker → confirme → `redeployApp(app_id, worker_id)` → `getRequest` até `finished`. Variável de ambiente
26
+ só entra no próximo deploy/redeploy ([fluxo.md](fluxo.md)).
27
+
28
+ ## Agendar
29
+
30
+ "Faz o deploy do pedidos-api em produção hoje às 22h": mesmo roteiro, com `scheduled_for` no fuso do usuário
31
+ (`2026-10-07T22:00:00-03:00`). A resposta vem com `request.scheduled=true`. Pendentes:
32
+ `listRequests(only_open=true)`. Cancelar uma agendada é pela interface (operação protegida).
33
+
34
+ ## Vários workers ou vários ambientes
35
+
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).
39
+
40
+ ## Deploy falhou
41
+
42
+ 1. `getRequest`: a etapa com `state=error` e a `message`.
43
+ 2. **Build**: `getApp` → `repository_id`; `listBuilds` → o build `failed` mais recente; `getBuildLog` sem `offset`
44
+ (final do log). Causas comuns: dependência não instalada, arquivo ignorado pelo git, teste quebrado no Dockerfile
45
+ (skill **docker**).
46
+ 3. **Deploy**: compare o `running_image_tag` do worker com a versão do build; mensagens comuns em
47
+ [mcp-diagnostico.md](mcp-diagnostico.md) e [diagnostico.md](diagnostico.md).
48
+ 4. Explique a causa e sugira a correção. Não refaça o deploy sem o usuário pedir.
49
+
50
+ ## Revisão do que está rodando
51
+
52
+ "O que está em produção?": `listApps` → `getApp` de cada uma → tabela aplicação × ambiente × worker ×
53
+ `running_image_tag` × `deployed_at`. Só leitura — dá para usar a conexão `-leitura`.
@@ -0,0 +1,94 @@
1
+ # Tools, escopos e resources do hefesto-mcp
2
+
3
+ Tabela do contrato `1.0.0` de todas as tools. O contrato completo, com JSON Schema draft 2020-12 de entrada e saída,
4
+ sai do próprio servidor: `GET <host>/hefesto/mcp/manifest` (público) ou `tools/list` numa sessão.
5
+
6
+ Resultado de sucesso: `structuredContent` com o objeto do contrato (o mesmo JSON em `content[0].text`) e
7
+ `_meta.trace_id`/`span_id` para achar a ação nos logs. Falha: `isError: true` e `{ error: { code, message,
8
+ details? } }` (ver [mcp-diagnostico.md](mcp-diagnostico.md)).
9
+
10
+ ## Contexto e catálogo
11
+
12
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
13
+ | --- | --- | --- | --- |
14
+ | `getContext` | `deploy.context.read` | leitura | — |
15
+ | `listProjects` | `deploy.apps.read` | leitura | — |
16
+ | `listApps` | `deploy.apps.read` | leitura | project_id, search |
17
+ | `getApp` | `deploy.apps.read` | leitura | **app_id** |
18
+
19
+ `getApp` devolve `environments[]`: `{ environment_id, name, repository: { repository_id, repository_url, branch,
20
+ build_path } | null, agents: [{ agent_id, origin_id, origin_name, path, workers: [{ worker_id, worker_name,
21
+ worker_port, status, running_image_tag, deployed_at }] }] }`.
22
+
23
+ ## Versões
24
+
25
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
26
+ | --- | --- | --- | --- |
27
+ | `listBuilds` | `deploy.builds.read` | leitura | **app_id**, **repository_id**, limit (padrão 10) |
28
+ | `getBuildLog` | `deploy.builds.read` | leitura | **app_id**, **repository_id**, **build_id**, offset, max_chars (padrão 20000) |
29
+
30
+ `getBuildLog` sem `offset` devolve o **final** do log (o que interessa num build que falhou); com `offset`, o que
31
+ veio depois dele, e `next_offset` para a próxima chamada (acompanhar um build em andamento).
32
+
33
+ ## Solicitações
34
+
35
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
36
+ | --- | --- | --- | --- |
37
+ | `listRequests` | `deploy.requests.read` | leitura | app_id, only_open, mine, limit (padrão 20) |
38
+ | `getRequest` | `deploy.requests.read` | leitura | **requested_id** |
39
+ | `deployApp` | `deploy.requests.write` | **destrutiva** | **app_id**, **worker_id**, **part** (`major`/`minor`/`fix`/`test`), scheduled_for |
40
+ | `redeployApp` | `deploy.requests.write` | **destrutiva** | **app_id**, **worker_id**, scheduled_for |
41
+ | `cancelRequest` | `deploy.requests.write` | **destrutiva** | **requested_id** |
42
+ | `rollbackApp` | `deploy.workers.write` | **destrutiva** | **app_id**, **worker_id**, image_tag (versão, tag ou imagem completa), scheduled_for |
43
+
44
+ - `deployApp`/`redeployApp` resolvem sozinhas o tipo (Sites ou Serviços), o agent e o repositório do ambiente do
45
+ worker; respondem na hora com `{ message, request, steps, next }` e o fluxo segue no servidor.
46
+ - `scheduled_for`: ISO 8601 **com fuso** (`2026-10-07T18:00:00-03:00`), de 30 s a 30 dias à frente.
47
+ - `getRequest`: `request.finished` (Concluída, Falhou ou Cancelada), `request.scheduled` e `steps[]` com
48
+ `{ step, state (current|processing|success|error), message, at, image }`.
49
+ - `cancelRequest`: agendada cancela na hora; em execução, para no próximo ponto seguro (o Build é interrompido e não
50
+ publica a imagem; o Deploy em andamento termina). Finalizada responde `CONFLICT`.
51
+ - `rollbackApp`: abre uma solicitação de Rollback (responde como `deployApp`, mais `previous_tag` e `new_tag`); sem
52
+ `image_tag`, vai para a versão publicada anterior à que o worker roda. Exige `apps:agents:workers:rollback` no
53
+ Argos, além do escopo.
54
+
55
+ ## Workers e variáveis
56
+
57
+ | Tool | Escopo | Tipo | Argumentos (obrigatórios em **negrito**) |
58
+ | --- | --- | --- | --- |
59
+ | `getWorkerHistory` | `deploy.apps.read` | leitura | **app_id**, worker_id, limit |
60
+ | `listEnvironmentVars` | `deploy.vars.read` | leitura | **app_id**, **environment_id** |
61
+ | `setEnvironmentVars` | `deploy.vars.write` | **destrutiva** | **app_id**, **environment_id**, **vars** |
62
+
63
+ - `getWorkerHistory`: deploys, redeploys e rollbacks de cada worker, de qualquer origem (solicitação, tela, MCP),
64
+ com tags anterior e nova e o resultado.
65
+ - Valor de segredo nunca sai; em `setEnvironmentVars`, mande `value: null` para manter o que está gravado. Variável
66
+ só entra no próximo deploy/redeploy.
67
+
68
+ ## Escopos
69
+
70
+ | Escopo | Libera |
71
+ | --- | --- |
72
+ | `deploy.context.read` | `getContext` e os resources |
73
+ | `deploy.apps.read` | Projetos, aplicações e onde rodam |
74
+ | `deploy.builds.read` | Versões e log de build |
75
+ | `deploy.requests.read` | Listar e acompanhar solicitações |
76
+ | `deploy.requests.write` | Deploy, redeploy e cancelamento |
77
+ | `deploy.workers.write` | Rollback de um worker |
78
+ | `deploy.vars.read` | Ver variáveis de ambiente (segredos sem valor) |
79
+ | `deploy.vars.write` | Criar, alterar e remover variáveis de ambiente |
80
+
81
+ Header `x-mcp-scopes`: lista separada por vírgula ou espaço, curinga `*` num segmento (`deploy.*.read`). Sem o
82
+ header, a sessão tem todos.
83
+
84
+ ## Resources e prompts
85
+
86
+ | Resource | Conteúdo |
87
+ | --- | --- |
88
+ | `hefesto-deploy://catalog` | Todas as tools/resources/prompts com versão, escopos e criticidade |
89
+ | `hefesto-deploy://ownership` | Dono e contato do servidor |
90
+ | `hefesto-deploy://dependencies` | hefesto-server e argos-auth |
91
+ | `hefesto-deploy://runbooks` | Erros comuns |
92
+ | `hefesto-deploy://playbooks` | Sequências de tools |
93
+
94
+ Prompts: `deploy-app` (app, environment, part?, when?) e `investigate-failure` (requested_id?).
@@ -75,7 +75,7 @@ o guard **nunca** lê `Authorization: Bearer` (esse header só aparece nas chama
75
75
  | Header | Quem manda | Validação | Permissão |
76
76
  |---|---|---|---|
77
77
  | `x-access-token` | usuário numa UI (token do `@orfeu/angular`) | local: JWT + JWKS do realm | grupos do token |
78
- | `x-app-token` | usuário fora da UI (script, MCP) — token pessoal, preso a uma aplicação | introspecção no Argos (cache) | grupos do usuário no client (MCP do auto-serviço: skill **auto-servico**) |
78
+ | `x-app-token` | usuário fora da UI (script, MCP) — token pessoal, preso a uma aplicação | introspecção no Argos (cache) | grupos do usuário no client (MCPs: skills **auto-servico** e **hefesto**) |
79
79
  | `x-api-token` | outro backend / integração | introspecção no Argos (cache) | só as operações concedidas ao token **neste** serviço |
80
80
 
81
81
  | Situação | Resultado |
@@ -13,7 +13,7 @@ introspecção (60 s; inativo 10 s), parâmetros do lote de auditoria e campos d
13
13
  | Nomes da API | camelCase: `orfeuHeaders`, `annotateOperation({ ... })` (objeto), `flushAudit()`, `fetchOperations()` | snake_case: `orfeu_headers`, `annotate_operation(target_type=..., ...)` (kwargs), `flush_audit()`, `fetch_operations()` |
14
14
  | Configuração | objeto `{ authorizerUrl, realmId, appId, secret, ... }`; nunca lê variável de ambiente | parâmetros `authorizer_url, realm_id, app_id, secret, *, tls_verify, audit`; não lê variável de ambiente, **exceto** o Django (settings `ORFEU_*`) |
15
15
  | Nomes de variáveis de ambiente nos exemplos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET` | `ORFEU_AUTHORIZER_URL`, `ORFEU_REALM_ID`, `ORFEU_APP_ID`, `ORFEU_SECRET` (convenção do Django) |
16
- | Token de outro realm | `acceptAnyRealm: true` aceita (busca o JWKS do realm da claim `realm_id`) | sempre recusado; não há opção equivalente |
16
+ | Token de outro realm | `acceptAnyRealm: true` aceita (busca o JWKS do realm da claim `realm_id`) | `accept_any_realm=True` (Django: `ORFEU_ACCEPT_ANY_REALM`), mesmo comportamento e mesmos limites (realm só `[A-Za-z0-9_-]`, cache de 64, realm sem JWKS bloqueado 30 s, 20 realms novos/min); exige `orfeu` >= 1.2.0 (no Node, os limites valem a partir do `@orfeu/node` 1.1.1) |
17
17
  | Validação do JWT | `jose` com JWKS remoto (cache interno da lib); JWKS buscado **sob demanda** | exige `kid` e RS256; JWKS buscado **na subida** (falha a subida se não vier), cache de 1 h e nova busca se o `kid` for desconhecido |
18
18
  | Timeouts das chamadas ao Argos | só a auditoria tem (10 s); token do serviço, sync, operações e introspecção **sem timeout** | 10 s em todas (introspecção: 5 s) |
19
19
  | Erro de rede na subida | erro cru do `fetch` (não é `OrfeuError`) | embrulhado: `OrfeuAuthError` / `OrfeuSyncError` / `OrfeuError` |
@@ -30,7 +30,7 @@ Leia sob demanda:
30
30
  ## 1. Instalação
31
31
 
32
32
  ```bash
33
- npm install @orfeu/node@^1.0.1
33
+ npm install @orfeu/node@^1.1.1
34
34
  npm install express # se usar @orfeu/node/express
35
35
  npm install fastify # @orfeu/node/fastify
36
36
  npm install @nestjs/common @nestjs/core reflect-metadata rxjs # @orfeu/node/nest
@@ -81,7 +81,7 @@ Como dividir entre subagentes/sessões, o que vai no prompt de cada um e os recu
81
81
  | server | `pytest` inteiro (ambiente recriado do zero se mudou dependência) |
82
82
  | GraphQL | `tsc --noEmit`, `vitest`, `build`; todo campo com `operation()` |
83
83
  | Angular | codegen sem erro, `ng test`, `ng build`, `lint:a11y` |
84
- | banco | `python build.py` e a suíte da pasta (PGlite) |
84
+ | banco | `poe migrate local` e a suíte da pasta (`poe test`) |
85
85
  | ponta a ponta | serviços locais de pé com o código novo; o usuário valida no navegador |
86
86
 
87
87
  Relate falha como falha, com a saída. Teste que depende de dado/ambiente externo (Redis real, equipamento): diga qual e
@@ -33,7 +33,7 @@ Regras de negócio: <validações, quem pode o quê, efeitos colaterais, integra
33
33
 
34
34
  ## Dados
35
35
 
36
- - Tabelas/colunas: <...> — `database/scripts/create/`, e migration se o banco já existe.
36
+ - Tabelas/colunas: <...> — migration nova em `database/migrations/versions/` (`poe nova "<descrição>"`).
37
37
 
38
38
  ## Argos
39
39
 
@@ -25,7 +25,7 @@ Divisão de trabalho entre as skills:
25
25
  ## 1. Pacotes
26
26
 
27
27
  Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular ← (maps, charts, spine)`. Todos na
28
- **mesma versão** (`^1.0.0`); as 0.9.x foram retiradas do registry.
28
+ **mesma versão** (`^2.0.1`); as 0.9.x foram retiradas do registry.
29
29
 
30
30
  | Pacote | Para quê |
31
31
  |---|---|
@@ -38,7 +38,7 @@ Cadeia de dependência: `tokens ← icons ← primitives ← core ← angular
38
38
  | `@trismegisto/maps` | mapas (`hm-map`, coroplético, marcadores, GeoJSON) com mapas base embutidos |
39
39
  | `@trismegisto/spine` | o **shell pronto**: cabeçalho, menu lateral vindo do servidor de autorização (Argos), workspace em abas, barra da página, login/callback, modal/painel/toast por serviço, configurações, tour, auditoria, cliente GraphQL. O app entrega só as telas |
40
40
 
41
- ## 2. Instalação (1.0.0)
41
+ ## 2. Instalação (2.0.1)
42
42
 
43
43
  ```bash
44
44
  # sem shell pronto