@acropole/skills 1.2.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.
Files changed (41) hide show
  1. package/README.md +4 -3
  2. package/package.json +4 -4
  3. package/skills/acropole/SKILL.md +2 -0
  4. package/skills/acropole/references/arquitetura.md +29 -5
  5. package/skills/acropole/references/fluxos/app-novo.md +4 -4
  6. package/skills/acropole/references/fluxos/tela-nova.md +1 -1
  7. package/skills/apollo/references/subscriptions.md +10 -4
  8. package/skills/apollo/references/testes-build.md +1 -0
  9. package/skills/auto-servico/SKILL.md +153 -0
  10. package/skills/auto-servico/references/diagnostico.md +42 -0
  11. package/skills/auto-servico/references/roteiros.md +63 -0
  12. package/skills/auto-servico/references/tools.md +108 -0
  13. package/skills/docker/SKILL.md +3 -0
  14. package/skills/docker/references/podman-local.md +73 -0
  15. package/skills/express/references/dados.md +3 -1
  16. package/skills/fastapi/SKILL.md +4 -4
  17. package/skills/fastapi/references/banco.md +53 -50
  18. package/skills/fastapi/references/estrutura.md +2 -2
  19. package/skills/fastapi/references/integracoes.md +8 -0
  20. package/skills/hefesto/SKILL.md +49 -14
  21. package/skills/hefesto/references/diagnostico.md +15 -5
  22. package/skills/hefesto/references/fluxo.md +64 -35
  23. package/skills/hefesto/references/mcp-diagnostico.md +44 -0
  24. package/skills/hefesto/references/mcp-roteiros.md +53 -0
  25. package/skills/hefesto/references/mcp-tools.md +94 -0
  26. package/skills/orfeu/SKILL.md +1 -1
  27. package/skills/orfeu/references/diferencas.md +1 -1
  28. package/skills/orfeu/references/node.md +1 -1
  29. package/skills/orquestracao/SKILL.md +1 -1
  30. package/skills/orquestracao/templates/spec.md +1 -1
  31. package/skills/trismegisto/SKILL.md +4 -4
  32. package/skills/trismegisto/references/angular-api.md +653 -507
  33. package/skills/trismegisto/references/angular-exports.md +541 -130
  34. package/skills/trismegisto/references/angular-types.md +1 -1
  35. package/skills/trismegisto/references/angular.md +28 -8
  36. package/skills/trismegisto/references/catalogo/icones.json +5 -0
  37. package/skills/trismegisto/references/catalogo/seletores.json +452 -31
  38. package/skills/trismegisto/references/catalogo/tokens.json +136 -16
  39. package/skills/trismegisto/references/spine-api.md +181 -44
  40. package/skills/trismegisto/references/spine-recipes.md +1 -1
  41. package/skills/trismegisto/references/spine.md +4 -3
@@ -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 | 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`) | 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
@@ -172,8 +172,8 @@ import { HERMES_THEME_CONFIG } from '@trismegisto/angular';
172
172
  `error`, `attention`, `done`, `locked`, `unlocked`, `forbidden`, `not-found`, `session-expired`; outro
173
173
  desenho vai no slot `[illustration]`. Vazio **dentro** de cartão/tabela é `hm-empty`; falha ao carregar é
174
174
  `hm-alert`.
175
- - **Ilustrações** são "adesivos": traço escuro e brancos **fixos**, iguais no claro e no escuro (no escuro
176
- ganham contorno claro). Só a cor acompanha o tema: roupa/objetos seguem a família (`--hm-accent`), o
175
+ - **Ilustrações** têm tinta e personagem **fixos**, iguais no claro e no escuro; no escuro, um contorno na cor
176
+ do texto (traço por baixo da silhueta) separa o desenho do fundo. Só a cor acompanha o tema: roupa/objetos seguem a família (`--hm-accent`), o
177
177
  símbolo-chave segue a cor de estado. Não recolora o traço por CSS. Os componentes de ilustração não saem
178
178
  da raiz (`@trismegisto/angular/illustration-error`…); prefira `hm-state-screen`/`hm-state-page`, que as
179
179
  carregam sob demanda.