@acropole/skills 1.3.0 → 1.4.0
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 +3 -3
- package/package.json +3 -3
- package/skills/acropole/SKILL.md +1 -0
- package/skills/acropole/references/arquitetura.md +29 -5
- package/skills/acropole/references/fluxos/app-novo.md +4 -4
- package/skills/apollo/references/subscriptions.md +10 -4
- package/skills/apollo/references/testes-build.md +1 -0
- package/skills/docker/SKILL.md +3 -0
- package/skills/docker/references/podman-local.md +73 -0
- package/skills/express/references/dados.md +3 -1
- package/skills/fastapi/SKILL.md +4 -4
- package/skills/fastapi/references/banco.md +53 -50
- package/skills/fastapi/references/estrutura.md +2 -2
- package/skills/fastapi/references/integracoes.md +8 -0
- package/skills/hefesto/SKILL.md +49 -14
- package/skills/hefesto/references/diagnostico.md +15 -5
- package/skills/hefesto/references/fluxo.md +64 -35
- package/skills/hefesto/references/mcp-diagnostico.md +44 -0
- package/skills/hefesto/references/mcp-roteiros.md +53 -0
- package/skills/hefesto/references/mcp-tools.md +94 -0
- package/skills/orfeu/SKILL.md +1 -1
- package/skills/orfeu/references/diferencas.md +1 -1
- package/skills/orfeu/references/node.md +1 -1
- package/skills/orquestracao/SKILL.md +1 -1
- package/skills/orquestracao/templates/spec.md +1 -1
- package/skills/trismegisto/SKILL.md +2 -2
- package/skills/trismegisto/references/angular-api.md +7 -5
- package/skills/trismegisto/references/angular-exports.md +12 -1
- package/skills/trismegisto/references/angular.md +10 -0
- package/skills/trismegisto/references/catalogo/seletores.json +8 -0
- package/skills/trismegisto/references/spine-api.md +148 -9
- package/skills/trismegisto/references/spine-recipes.md +1 -1
- package/skills/trismegisto/references/spine.md +1 -1
package/skills/hefesto/SKILL.md
CHANGED
|
@@ -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,
|
|
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
|
|
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
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
|
67
|
-
service:
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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
|
|
49
|
-
|
|
|
50
|
-
|
|
|
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:
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
>
|
|
46
|
-
>
|
|
47
|
-
> `
|
|
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
|
-
|
|
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
|
|
56
|
-
2.
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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á
|
|
66
|
-
|
|
67
|
-
-
|
|
68
|
-
|
|
69
|
-
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
-
|
|
110
|
-
-
|
|
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
|
|
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?).
|
package/skills/orfeu/SKILL.md
CHANGED
|
@@ -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 (
|
|
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`) |
|
|
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.
|
|
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 | `
|
|
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/
|
|
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** (`^
|
|
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 (
|
|
41
|
+
## 2. Instalação (2.0.1)
|
|
42
42
|
|
|
43
43
|
```bash
|
|
44
44
|
# sem shell pronto
|