@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.
- package/README.md +4 -3
- package/package.json +4 -4
- package/skills/acropole/SKILL.md +2 -0
- package/skills/acropole/references/arquitetura.md +29 -5
- package/skills/acropole/references/fluxos/app-novo.md +4 -4
- package/skills/acropole/references/fluxos/tela-nova.md +1 -1
- package/skills/apollo/references/subscriptions.md +10 -4
- package/skills/apollo/references/testes-build.md +1 -0
- package/skills/auto-servico/SKILL.md +153 -0
- package/skills/auto-servico/references/diagnostico.md +42 -0
- package/skills/auto-servico/references/roteiros.md +63 -0
- package/skills/auto-servico/references/tools.md +108 -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 +4 -4
- package/skills/trismegisto/references/angular-api.md +653 -507
- package/skills/trismegisto/references/angular-exports.md +541 -130
- package/skills/trismegisto/references/angular-types.md +1 -1
- package/skills/trismegisto/references/angular.md +28 -8
- package/skills/trismegisto/references/catalogo/icones.json +5 -0
- package/skills/trismegisto/references/catalogo/seletores.json +452 -31
- package/skills/trismegisto/references/catalogo/tokens.json +136 -16
- package/skills/trismegisto/references/spine-api.md +181 -44
- package/skills/trismegisto/references/spine-recipes.md +1 -1
- 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:
|
|
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 | 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
|
|
@@ -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**
|
|
176
|
-
|
|
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.
|