@acropole/skills 1.0.0 → 1.2.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 (36) hide show
  1. package/README.md +4 -2
  2. package/bin/install.js +4 -3
  3. package/package.json +2 -2
  4. package/skills/acropole/SKILL.md +9 -3
  5. package/skills/acropole/references/arquitetura.md +174 -0
  6. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  7. package/skills/acropole/references/fluxos/tela-nova.md +1 -1
  8. package/skills/angular/SKILL.md +6 -3
  9. package/skills/angular/references/armadilhas.md +5 -1
  10. package/skills/angular/references/estrutura.md +33 -14
  11. package/skills/angular/references/testes-build.md +31 -4
  12. package/skills/apollo/SKILL.md +12 -8
  13. package/skills/apollo/references/armadilhas.md +5 -1
  14. package/skills/apollo/references/estrutura-bootstrap.md +47 -36
  15. package/skills/apollo/references/testes-build.md +12 -11
  16. package/skills/docker/references/porques.md +4 -0
  17. package/skills/express/SKILL.md +9 -7
  18. package/skills/express/references/estrutura.md +4 -1
  19. package/skills/express/references/rotas-erros.md +13 -1
  20. package/skills/express/references/testes-deploy.md +9 -5
  21. package/skills/fastapi/SKILL.md +12 -9
  22. package/skills/fastapi/references/banco.md +24 -12
  23. package/skills/fastapi/references/estrutura.md +87 -43
  24. package/skills/orfeu/references/diferencas.md +3 -3
  25. package/skills/orfeu/references/node-api.md +8 -2
  26. package/skills/orfeu/references/node-armadilhas.md +4 -4
  27. package/skills/orfeu/references/node-recipes.md +19 -12
  28. package/skills/orfeu/references/python.md +8 -2
  29. package/skills/orquestracao/SKILL.md +118 -0
  30. package/skills/orquestracao/references/paralelismo.md +48 -0
  31. package/skills/orquestracao/scripts/coord.sh +131 -0
  32. package/skills/orquestracao/templates/permissoes-argos.sql +28 -0
  33. package/skills/orquestracao/templates/plan.md +45 -0
  34. package/skills/orquestracao/templates/spec.md +54 -0
  35. package/skills/orquestracao/templates/tasks.md +21 -0
  36. package/skills/trismegisto/references/angular-exports.md +143 -143
@@ -0,0 +1,131 @@
1
+ #!/usr/bin/env bash
2
+ # Coordenação entre sessões/agentes (workers) que implementam os itens Txx de uma lista de tarefas do repositório.
3
+ #
4
+ # A trava é um DIRETÓRIO por item em <raiz>/.sdd/coord/claims/<Txx>: mkdir é atômico (falha se já existe), então dois
5
+ # workers nunca reservam o mesmo item, mesmo rodando ao mesmo tempo. A lista (docs/sdd/tasks.md) é só a visão legível;
6
+ # quem manda na reserva é .sdd/coord/ (estado local, fora do git).
7
+ #
8
+ # Raiz = repositório git da pasta atual (COORD_ROOT sobrescreve). Lista = COORD_TASKS (padrão docs/sdd/tasks.md).
9
+ #
10
+ # Uso (bash/Git Bash, de qualquer pasta do repositório):
11
+ # coord.sh init -> cria docs/sdd/tasks.md (do modelo) e põe .sdd/ no .gitignore
12
+ # coord.sh register -> reserva e imprime o próximo worker-N livre
13
+ # coord.sh claim <worker> <Txx> -> reserva o item (exit 1 se já tem dono)
14
+ # coord.sh check <worker> <Txx> -> confirma que o item é seu (exit 1 se não)
15
+ # coord.sh done <worker> <Txx> -> marca o item como concluído
16
+ # coord.sh release <worker> <Txx> -> devolve o item (desistiu/bloqueado)
17
+ # coord.sh unregister <worker> -> libera o nome do worker ao encerrar
18
+ # coord.sh status -> situação de todos os itens e workers
19
+ # coord.sh stale [horas] -> itens "em andamento" há mais de N horas (padrão 4) ou com dono não registrado
20
+ # coord.sh orphans --release -> devolve os itens em andamento cujo worker não está mais registrado
21
+ set -u
22
+ HERE="$(cd "$(dirname "$0")" && pwd)"
23
+ ROOT="${COORD_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
24
+ LIST="$ROOT/${COORD_TASKS:-docs/sdd/tasks.md}"
25
+ STATE="$ROOT/.sdd/coord"
26
+ CLAIMS="$STATE/claims"
27
+ WORKERS="$STATE/workers"
28
+
29
+ now() { date '+%Y-%m-%d %H:%M:%S'; }
30
+ epoch() { date -d "$1" +%s 2>/dev/null || date -j -f '%Y-%m-%d %H:%M:%S' "$1" +%s 2>/dev/null || echo 0; }
31
+ die() { echo "ERRO: $*" >&2; exit 1; }
32
+ need_list() { [ -f "$LIST" ] || die "não existe $LIST -- rode: coord.sh init"; }
33
+ task_exists() { grep -qE "\*\*$1\*\*" "$LIST"; }
34
+ owner_of() { cat "$CLAIMS/$1/owner" 2>/dev/null; }
35
+ state_of() { cat "$CLAIMS/$1/state" 2>/dev/null; }
36
+ valid_task() { [[ "$1" =~ ^T[0-9]{2,}$ ]] || die "item inválido: '$1' (formato Txx)"; }
37
+ need_owner() {
38
+ local o; o="$(owner_of "$2")"
39
+ [ -n "$o" ] || die "$2 não está reservado"
40
+ [ "$o" = "$1" ] || die "$2 pertence a $o, não a $1"
41
+ }
42
+ age_hours() { local s; s="$(epoch "$(cat "$1" 2>/dev/null)")"; [ "$s" -gt 0 ] && echo $(( ( $(date +%s) - s ) / 3600 )) || echo "?"; }
43
+
44
+ case "${1:-}" in
45
+ init)
46
+ mkdir -p "$(dirname "$LIST")"
47
+ if [ -f "$LIST" ]; then echo "já existe: $LIST"; else cp "$HERE/../templates/tasks.md" "$LIST" && echo "criado: $LIST"; fi
48
+ if ! grep -qxE '/?\.sdd/?' "$ROOT/.gitignore" 2>/dev/null; then
49
+ printf '\n# Estado local de coordenação entre agentes (coord.sh)\n.sdd/\n' >> "$ROOT/.gitignore"
50
+ echo ".sdd/ acrescentado ao .gitignore"
51
+ fi
52
+ ;;
53
+ register)
54
+ mkdir -p "$WORKERS"
55
+ n=1
56
+ while ! mkdir "$WORKERS/worker-$n" 2>/dev/null; do n=$((n+1)); done
57
+ now > "$WORKERS/worker-$n/since"
58
+ echo "worker-$n"
59
+ ;;
60
+ unregister)
61
+ [ -n "${2:-}" ] || die "uso: coord.sh unregister <worker>"
62
+ [ -d "$WORKERS/$2" ] || die "$2 não está registrado"
63
+ rm -rf "$WORKERS/$2" && echo "$2 liberado"
64
+ ;;
65
+ claim)
66
+ w="${2:-}"; t="${3:-}"
67
+ [ -n "$w" ] && [ -n "$t" ] || die "uso: coord.sh claim <worker> <Txx>"
68
+ valid_task "$t"; need_list
69
+ [ -d "$WORKERS/$w" ] || die "$w não está registrado (rode: coord.sh register)"
70
+ task_exists "$t" || die "$t não existe em $LIST"
71
+ mkdir -p "$CLAIMS"
72
+ if ! mkdir "$CLAIMS/$t" 2>/dev/null; then
73
+ die "$t já reservado por $(owner_of "$t") ($(state_of "$t"))"
74
+ fi
75
+ echo "$w" > "$CLAIMS/$t/owner"
76
+ echo "em andamento" > "$CLAIMS/$t/state"
77
+ now > "$CLAIMS/$t/since"
78
+ # Garantia de que ninguém sobrescreveu: relê o dono depois de gravar.
79
+ [ "$(owner_of "$t")" = "$w" ] || die "$t foi sobrescrito por $(owner_of "$t") -- NÃO implemente"
80
+ echo "OK: $t reservado para $w"
81
+ ;;
82
+ check)
83
+ valid_task "${3:-}"; need_owner "${2:-}" "${3:-}"
84
+ [ "$(state_of "$3")" = "em andamento" ] || die "$3 está '$(state_of "$3")'"
85
+ echo "OK: ${3} é de ${2}"
86
+ ;;
87
+ done)
88
+ valid_task "${3:-}"; need_owner "${2:-}" "${3:-}"
89
+ echo "concluído" > "$CLAIMS/$3/state"; now > "$CLAIMS/$3/finished"
90
+ echo "OK: $3 concluído por $2"
91
+ ;;
92
+ release)
93
+ valid_task "${3:-}"; need_owner "${2:-}" "${3:-}"
94
+ rm -rf "$CLAIMS/$3" && echo "OK: $3 devolvido"
95
+ ;;
96
+ status)
97
+ need_list
98
+ grep -oE '\*\*T[0-9]{2,}\*\*.{0,90}' "$LIST" | while IFS= read -r line; do
99
+ t="$(echo "$line" | grep -oE 'T[0-9]{2,}' | head -1)"
100
+ desc="$(echo "$line" | sed 's/\*\*//g')"
101
+ if [ -d "$CLAIMS/$t" ]; then
102
+ st="$(state_of "$t") · $(owner_of "$t")"
103
+ [ "$(state_of "$t")" = "em andamento" ] && st="$st · $(age_hours "$CLAIMS/$t/since")h"
104
+ else st="livre"; fi
105
+ printf '%-34s %s\n' "[$st]" "$desc"
106
+ done
107
+ echo; echo "workers registrados: $(ls "$WORKERS" 2>/dev/null | tr '\n' ' ')"
108
+ ;;
109
+ stale)
110
+ limit="${2:-4}"
111
+ for d in "$CLAIMS"/T*; do
112
+ [ -d "$d" ] || continue
113
+ t="$(basename "$d")"; [ "$(state_of "$t")" = "em andamento" ] || continue
114
+ o="$(owner_of "$t")"; h="$(age_hours "$d/since")"
115
+ if [ ! -d "$WORKERS/$o" ]; then echo "$t · $o · ${h}h · worker NÃO registrado (órfão)"
116
+ elif [ "$h" != "?" ] && [ "$h" -ge "$limit" ]; then echo "$t · $o · ${h}h · em andamento há mais de ${limit}h"; fi
117
+ done
118
+ ;;
119
+ orphans)
120
+ [ "${2:-}" = "--release" ] || die "uso: coord.sh orphans --release (devolve itens de workers não registrados)"
121
+ for d in "$CLAIMS"/T*; do
122
+ [ -d "$d" ] || continue
123
+ t="$(basename "$d")"; [ "$(state_of "$t")" = "em andamento" ] || continue
124
+ o="$(owner_of "$t")"
125
+ [ -d "$WORKERS/$o" ] || { rm -rf "$d"; echo "devolvido: $t (era de $o)"; }
126
+ done
127
+ ;;
128
+ *)
129
+ sed -n '2,22p' "$0"; exit 1
130
+ ;;
131
+ esac
@@ -0,0 +1,28 @@
1
+ -- NNN -- <tema> (AAAA-MM-DD): operações e permissões de <app> no Argos.
2
+ --
3
+ -- Migration para um banco do Argos que JÁ EXISTE, com o mesmo resultado das linhas novas no seed
4
+ -- (auth/operations.sql e auth/permissions.sql). Idempotente e só ACRESCENTA: pode rodar antes do deploy do app novo.
5
+ --
6
+ -- O sync do Orfeu cria as operações quando o app sobe e DESATIVA as que ele não declara mais -- mas não dá permissão.
7
+ -- Esta migration existe para: (1) a operação já existir com o id fixo da seed; (2) levar permissões de operação
8
+ -- renomeada para a nova (protected por grupo, e qualquer nível para token de API, x-api-token).
9
+
10
+ BEGIN;
11
+
12
+ -- 1. Operações (resolve por (app_id, identifier, method): se o sync já criou com id aleatório, só atualiza o nível)
13
+ INSERT INTO auth.operations (operation_id, app_id, identifier, method, level)
14
+ VALUES
15
+ ('<UUID fixo>', '<app_id>', '<dominio>:<recurso>:<acao>', '<read|write|delete|stream>', '<private|protected|optional|public>')
16
+ ON CONFLICT (app_id, identifier, method) DO UPDATE SET level = EXCLUDED.level, active = true;
17
+
18
+ -- 2. Permissões: copia de cada operação antiga para a nova equivalente (mesmo método), consumer por consumer
19
+ INSERT INTO auth.permissions (id, consumer_id, operation_id)
20
+ SELECT gen_random_uuid(), p.consumer_id, n.operation_id
21
+ FROM auth.permissions p
22
+ JOIN auth.operations o ON o.operation_id = p.operation_id
23
+ JOIN (VALUES ('<id antigo>', '<id novo>')) m(old_id, new_id) ON m.old_id = o.identifier
24
+ JOIN auth.operations n ON n.app_id = o.app_id AND n.identifier = m.new_id AND n.method = o.method
25
+ WHERE o.app_id = '<app_id>'
26
+ ON CONFLICT (consumer_id, operation_id) DO NOTHING;
27
+
28
+ COMMIT;
@@ -0,0 +1,45 @@
1
+ # <Tema> — plano (AAAA-MM-DD)
2
+
3
+ > Plano para um ou mais agentes. Spec: `docs/sdd/specs/<tema>.md`. Itens: `docs/sdd/tasks.md` (Txx). Cada agente lê
4
+ > este arquivo inteiro antes de reservar um item e escreve **só** na seção "Registro" do próprio item.
5
+
6
+ ## 1. Contexto e decisões já tomadas (não rediscutir)
7
+
8
+ - <decisão do usuário, com data e as palavras dele quando for restrição>
9
+
10
+ ## 2. Arquitetura alvo
11
+
12
+ <Domínios novos/alterados por camada. Copie a forma de um domínio existente deste repositório — não invente.>
13
+
14
+ ## 3. Mapa de nomes (fonte única — use exatamente estes)
15
+
16
+ | Domínio | server (`domains/`) | GraphQL / Angular | Prefixo das operações no Orfeu |
17
+ |---|---|---|---|
18
+ | <...> | `<snake_case>` | `<kebab-case>` | `<kebab-case>:` |
19
+
20
+ ## 4. Fases e itens
21
+
22
+ | Fase | Itens | Depende de | Pode ir em paralelo? |
23
+ |---|---|---|---|
24
+ | F0 | T01 | — | — |
25
+
26
+ ## 5. Convivência entre agentes
27
+
28
+ - Reserva pelo `coord.sh` (skill orquestracao); um item por vez por agente.
29
+ - Arquivos compartilhados entre itens (só quem tem o item mexe): <lista>.
30
+ - Recursos de execução (servidor local, Redis, banco, navegador de teste, codegen, git): <como reservar>.
31
+
32
+ ## 6. Itens
33
+
34
+ ### T01 · <título>
35
+ - O quê: <...>
36
+ - Arquivos: <...>
37
+ - Pronto quando: <provas — testes, typecheck, build, codegen>
38
+
39
+ ## 7. Riscos conhecidos
40
+
41
+ - <...>
42
+
43
+ ## 8. Registro (cada agente escreve só na seção do seu item)
44
+
45
+ ### T01
@@ -0,0 +1,54 @@
1
+ # <App> — <tema> (spec, AAAA-MM-DD)
2
+
3
+ ## Objetivo
4
+
5
+ <Uma ou duas frases: o problema e o resultado esperado para quem usa.>
6
+
7
+ ## Comportamento
8
+
9
+ - <O que o usuário vê e faz, passo a passo. Estados vazio, carregando e erro (com "Tentar novamente").>
10
+
11
+ ## Contrato
12
+
13
+ ### server (`server/src/app/domains/<domínio>/`)
14
+
15
+ | Método e caminho | Entrada | `data` | Operação (id · nível) | Mensagem de sucesso | Erros (status · frase) |
16
+ |---|---|---|---|---|---|
17
+ | `GET /<domínio>/...` | query: ... | `[...]` | `<domínio>:...:list` · private | — | 404 · "..." |
18
+ | `POST /<domínio>/...` | corpo: ... | `{...}` | `<domínio>:...:create` · protected | "... criado." | 409 · "Já existe ..." |
19
+
20
+ Regras de negócio: <validações, quem pode o quê, efeitos colaterais, integrações externas>.
21
+
22
+ ### GraphQL (`graphql/src/web/<domínio>/`)
23
+
24
+ | Campo | Argumentos | Retorno | Operação (nível) |
25
+ |---|---|---|---|
26
+ | `query <campo>` | ... | `<Tipo>Response` (envelope) | private |
27
+ | `subscription <campo>` | — | `<Tipo>` (sem envelope) — canal Redis `<app>:<canal>` | private |
28
+
29
+ ### Angular (`angular/src/app/features/<domínio>/`)
30
+
31
+ - Tela: <nome> — `router_id` <existente | novo no Argos, liberado para os grupos>.
32
+ - Ações e toasts: <ação> → toast com a mensagem do servidor; <polling/lote> silenciado.
33
+
34
+ ## Dados
35
+
36
+ - Tabelas/colunas: <...> — `database/scripts/create/`, e migration se o banco já existe.
37
+
38
+ ## Argos
39
+
40
+ - Operações novas/renomeadas: <ids>. `protected` → grupos: <...>. Token de API → permissão em qualquer nível.
41
+ - Tela nova: rota + roteador do client, **liberado** para os grupos.
42
+
43
+ ## Fora do escopo
44
+
45
+ - <...>
46
+
47
+ ## Restrições
48
+
49
+ - <O que não pode ser tocado/testado (equipamento real, banco compartilhado, backups...).>
50
+
51
+ ## Critérios de aceite
52
+
53
+ - [ ] <verificável: teste, typecheck, build, comportamento no navegador>
54
+ - [ ] Uma ação = um toast; nenhum toast em polling.
@@ -0,0 +1,21 @@
1
+ # Itens de trabalho
2
+
3
+ Fila de itens das mudanças planejadas com a skill `orquestracao`. Quem manda na reserva é o `coord.sh` da skill
4
+ (travas em `.sdd/coord/`, fora do git), não este arquivo.
5
+
6
+ ## Protocolo dos workers
7
+
8
+ 1. `coord.sh register` → `worker-N` (diga ao usuário qual é o seu).
9
+ 2. `coord.sh status` → escolha um item livre respeitando as dependências do plano.
10
+ 3. `coord.sh claim worker-N Txx` e depois `coord.sh check worker-N Txx` (tem que responder `OK`) — só então implemente.
11
+ 4. Ao terminar: `coord.sh done worker-N Txx` e marque `[x]` na linha do item. Bloqueado: `coord.sh release worker-N Txx`.
12
+ 5. Ao encerrar a sessão: `coord.sh unregister worker-N`.
13
+
14
+ Todos os workers usam o mesmo working tree: nunca `git reset`, `git checkout -- .`, `git stash`, `git clean`; commit só
15
+ dos seus arquivos, por caminho, e só com pedido do usuário.
16
+
17
+ <!-- Formato: - [ ] **Txx** · <camada/domínio> — <alteração> (AAAA-MM-DD) -->
18
+
19
+ ## <Tema> (spec: docs/sdd/specs/<tema>.md)
20
+
21
+ - [ ] **T01** · <camada> — <alteração> (AAAA-MM-DD)