@acropole/skills 0.0.0-stage → 1.0.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 (90) hide show
  1. package/README.md +180 -2
  2. package/agents/revisor-deploy.md +73 -0
  3. package/agents/revisor-documentacao.md +78 -0
  4. package/agents/revisor-orfeu.md +80 -0
  5. package/agents/revisor-trismegisto.md +81 -0
  6. package/bin/install.js +252 -0
  7. package/package.json +15 -4
  8. package/skills/acropole/SKILL.md +75 -0
  9. package/skills/acropole/references/fluxos/doctor.md +55 -0
  10. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  11. package/skills/acropole/references/fluxos/revisar.md +56 -0
  12. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  13. package/skills/acropole/scripts/doctor.mjs +439 -0
  14. package/skills/angular/SKILL.md +152 -0
  15. package/skills/angular/references/armadilhas.md +95 -0
  16. package/skills/angular/references/dados.md +251 -0
  17. package/skills/angular/references/estrutura.md +260 -0
  18. package/skills/angular/references/features.md +219 -0
  19. package/skills/angular/references/testes-build.md +230 -0
  20. package/skills/angular/scripts/checar.mjs +182 -0
  21. package/skills/angular/scripts/nucleo.mjs +227 -0
  22. package/skills/apollo/SKILL.md +222 -0
  23. package/skills/apollo/references/armadilhas.md +95 -0
  24. package/skills/apollo/references/envelope-erros.md +120 -0
  25. package/skills/apollo/references/estrutura-bootstrap.md +299 -0
  26. package/skills/apollo/references/schema-resolvers.md +183 -0
  27. package/skills/apollo/references/subscriptions.md +224 -0
  28. package/skills/apollo/references/testes-build.md +180 -0
  29. package/skills/apollo/scripts/checar.mjs +160 -0
  30. package/skills/apollo/scripts/nucleo.mjs +227 -0
  31. package/skills/docker/SKILL.md +102 -0
  32. package/skills/docker/references/modelos.md +251 -0
  33. package/skills/docker/references/porques.md +282 -0
  34. package/skills/documentacao/SKILL.md +146 -0
  35. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  36. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  37. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  38. package/skills/documentacao/references/modelo-readme.md +75 -0
  39. package/skills/documentacao/scripts/checar.mjs +454 -0
  40. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  41. package/skills/express/SKILL.md +154 -0
  42. package/skills/express/references/dados.md +180 -0
  43. package/skills/express/references/estrutura.md +154 -0
  44. package/skills/express/references/middlewares.md +227 -0
  45. package/skills/express/references/rotas-erros.md +274 -0
  46. package/skills/express/references/testes-deploy.md +150 -0
  47. package/skills/express/scripts/checar.mjs +115 -0
  48. package/skills/express/scripts/nucleo.mjs +227 -0
  49. package/skills/fastapi/SKILL.md +129 -0
  50. package/skills/fastapi/references/banco.md +185 -0
  51. package/skills/fastapi/references/estrutura.md +281 -0
  52. package/skills/fastapi/references/integracoes.md +145 -0
  53. package/skills/fastapi/references/rotas-erros.md +140 -0
  54. package/skills/fastapi/references/testes-deploy.md +190 -0
  55. package/skills/fastapi/scripts/checar.mjs +108 -0
  56. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  57. package/skills/hefesto/SKILL.md +119 -0
  58. package/skills/hefesto/references/conceitos.md +131 -0
  59. package/skills/hefesto/references/diagnostico.md +70 -0
  60. package/skills/hefesto/references/fluxo.md +122 -0
  61. package/skills/hefesto/references/preparar-app.md +105 -0
  62. package/skills/orfeu/SKILL.md +162 -0
  63. package/skills/orfeu/references/angular-api.md +201 -0
  64. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  65. package/skills/orfeu/references/angular-recipes.md +474 -0
  66. package/skills/orfeu/references/angular.md +212 -0
  67. package/skills/orfeu/references/diferencas.md +56 -0
  68. package/skills/orfeu/references/node-api.md +348 -0
  69. package/skills/orfeu/references/node-armadilhas.md +158 -0
  70. package/skills/orfeu/references/node-recipes.md +534 -0
  71. package/skills/orfeu/references/node.md +204 -0
  72. package/skills/orfeu/references/python-api.md +346 -0
  73. package/skills/orfeu/references/python-recipes.md +479 -0
  74. package/skills/orfeu/references/python.md +234 -0
  75. package/skills/orfeu/scripts/checar.mjs +126 -0
  76. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  77. package/skills/trismegisto/SKILL.md +194 -0
  78. package/skills/trismegisto/references/angular-api.md +2788 -0
  79. package/skills/trismegisto/references/angular-exports.md +4020 -0
  80. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  81. package/skills/trismegisto/references/angular-types.md +492 -0
  82. package/skills/trismegisto/references/angular.md +390 -0
  83. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  84. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  85. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  86. package/skills/trismegisto/references/spine-api.md +1530 -0
  87. package/skills/trismegisto/references/spine-recipes.md +581 -0
  88. package/skills/trismegisto/references/spine.md +343 -0
  89. package/skills/trismegisto/scripts/checar.mjs +216 -0
  90. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: trismegisto
3
+ description: "Interface de apps Angular com o design system Trismegisto (@trismegisto/*, componentes hm-*, tokens --hm-*, ícones) e o shell @trismegisto/spine. Use ao criar ou alterar a parte visual de uma tela — formulário, listagem, modal, menu, navegação, tema/família/fonte/densidade, ícone, gráfico, mapa, texto de interface — e antes de escrever HTML/CSS próprio nesses apps. Estrutura do app, rotas, serviços de dados e build são da skill angular (numa tela nova use as duas); login e sessão, da orfeu."
4
+ ---
5
+
6
+ # Trismegisto — interface dos apps Angular
7
+
8
+ O Trismegisto é o design system Angular publicado no npm sob o scope `@trismegisto` (no código as classes
9
+ ainda levam o nome histórico **Hermes**: `HermesThemeService`, `provideHermesIcons`…). Entrega componentes
10
+ standalone com prefixo **`hm-*`**, tokens CSS **`--hm-*`** (cor, espaço, tipografia, movimento, camadas) em
11
+ tema claro/escuro, 12 famílias de cor, duas densidades e quatro fontes, textos próprios em pt-BR/en/es e
12
+ acessibilidade (teclado, leitor de tela, alto contraste, `prefers-reduced-motion`) já resolvida.
13
+
14
+ Divisão de trabalho entre as skills:
15
+ - **angular** — arquitetura do app (estrutura de pastas, serviços, estado, rotas, build). Esta skill
16
+ não repete isso.
17
+ - **trismegisto** (esta) — tudo que é **interface**: qual componente usar, tokens, tema, shell.
18
+ - **orfeu** — sessão, token, guard e logout do `@orfeu/angular` (o spine depende dele).
19
+ - Interface em React (`@trismegisto/react`) ainda não é coberta.
20
+
21
+ > **Antes de dar por terminado:** `node scripts/checar.mjs <arquivos alterados>` (caminho relativo a esta skill: instalada, fica em `~/.claude/skills/trismegisto/scripts/checar.mjs`; `--help` lista as regras, `--json` para máquina).
22
+ >
23
+ > **Mexeu numa tela?** Rode também a skill `documentacao`: rótulo, ação ou estado que mudou precisa mudar no README da tela.
24
+
25
+ ## 1. Pacotes
26
+
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.
29
+
30
+ | Pacote | Para quê |
31
+ |---|---|
32
+ | `@trismegisto/tokens` | variáveis CSS `--hm-*`, famílias de cor (`HERMES_FAMILIES`), breakpoints em TS. Sem framework |
33
+ | `@trismegisto/icons` | catálogo de ícones SVG 24×24 (`@trismegisto/icons/catalog`). Sem framework |
34
+ | `@trismegisto/primitives` | lógica sem framework: tema (`extendThemeConfig`), i18n (catálogos, `formatMessage`), máscaras, datas, árvore… |
35
+ | `@trismegisto/core` | CSS dos componentes e utilitários (`.hm-stack`, `.hm-row`, `.hm-text-*`, `.hm-visually-hidden`…) |
36
+ | `@trismegisto/angular` | os componentes `hm-*`, diretivas, pipes, serviços (`HermesThemeService`, `HermesDialogService`, `HermesToastService`…) e harnesses de teste (`/testing`) |
37
+ | `@trismegisto/charts` | gráficos (`hm-bar-chart`, `hm-line-chart`…) com tabela acessível. Pesado: carregue sob demanda |
38
+ | `@trismegisto/maps` | mapas (`hm-map`, coroplético, marcadores, GeoJSON) com mapas base embutidos |
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
+
41
+ ## 2. Instalação (1.0.0)
42
+
43
+ ```bash
44
+ # sem shell pronto
45
+ npm install @trismegisto/angular @trismegisto/core @trismegisto/tokens @trismegisto/primitives @trismegisto/icons
46
+ # com o shell (app que autentica no Argos)
47
+ npm install @trismegisto/spine @trismegisto/angular @trismegisto/core @trismegisto/tokens \
48
+ @trismegisto/primitives @trismegisto/icons @orfeu/angular
49
+ # opcionais, na mesma versão
50
+ npm install @trismegisto/charts @trismegisto/maps
51
+ ```
52
+
53
+ Peers: Angular **≥ 21** (`core`, `common`, `forms`, `router`, `platform-browser`), `rxjs` `^7.8`.
54
+ `@angular/cdk` é peer **opcional** (só os harnesses de `@trismegisto/angular/testing`; instale como
55
+ `devDependency`). O spine pede ainda `@orfeu/angular` `^1.0.0` (**uma cópia só** no app) e, só se usar
56
+ `@trismegisto/spine/graphql`, `@apollo/client` `^4.2`, `apollo-angular` `^14.2`, `graphql` `^16`, `graphql-ws` `^6`.
57
+
58
+ `angular.json` → `styles`, nesta ordem:
59
+
60
+ ```json
61
+ "node_modules/@trismegisto/tokens/dist/tokens.css",
62
+ "node_modules/@trismegisto/core/dist/core.css"
63
+ ```
64
+
65
+ Bootstrap: sem spine, veja `references/angular.md` §1; com spine, `references/spine.md` §3 (o spine já
66
+ registra ícones, tema e toasts — não repita).
67
+
68
+ ## 3. Regras de ouro
69
+
70
+ 1. **Procure o `hm-*` antes de escrever HTML/CSS.** A tabela "Preciso de… / Use" em `references/angular.md` §4
71
+ cobre ~100 casos; o nome exato de cada input/output está em `references/angular-api.md`. Não invente um
72
+ `hm-*` que não esteja lá (o build quebra). Faltou mesmo? Componha com `hm-*` + classes do core; só então
73
+ CSS próprio, com tokens e marcado `// TODO(hermes): substituir por hm-<nome> quando existir`.
74
+ 2. **Nenhum valor visual cravado.** Cor, espaço, raio, sombra, duração e altura vêm de `var(--hm-*)`. `#hex`
75
+ ou `px` de espaçamento no SCSS de tela é bug (não acompanha tema escuro, família, densidade nem alto
76
+ contraste). Cores de série de gráfico/mapa: `--hm-data-*`. Lista dos grupos: `references/angular.md` §2.
77
+ 3. **Ícones só do catálogo.** `<hm-icon shape="add-text">` (kebab-case no template; o export em TS é
78
+ camelCase, `addText`). Nome inexistente não quebra o build: vira ícone genérico com aviso `[hermes-icons]`
79
+ no console. Confira em `@trismegisto/icons/catalog`.
80
+ 4. **i18n:** a lib traz os próprios textos (fechar, paginação, erros) em pt-BR/en/es; os rótulos que você
81
+ passa são do i18n do app. Ao trocar de idioma, chame também `inject(HermesI18nService).setLocale(locale)`
82
+ (o spine troca junto). Não monte texto da lib por concatenação.
83
+ 5. **Acessibilidade:** todo controle tem `label` real (use `labelHidden` para esconder, nunca `label=""`);
84
+ não aninhe interativo em interativo (`hm-card` não é clicável); landmarks com nome único; ação destrutiva
85
+ com `intent="danger"` **e confirmação** (`HermesDialogService.confirm({ …, danger: true })`); evento de
86
+ botão é `(clicked)`, não `(click)`. O `(clicked)` não traz o evento: botão dentro de linha/cartão clicável
87
+ contém a propagação com `(click)="$event.stopPropagation()"` **junto** do `(clicked)` (a ação fica no
88
+ `(clicked)`; o verificador aceita esse `(click)`).
89
+ 6. **Standalone e lazy:** importe a classe no `imports` do componente (não existe `HermesModule`); importe da
90
+ raiz `@trismegisto/angular` ou do ponto da peça (`@trismegisto/angular/data-grid`). Gráficos, mapas e
91
+ telas pesadas em `@defer`/rota lazy.
92
+ 7. **Teste por harness** (`@trismegisto/angular/testing`), nunca por classe interna do DOM da lib.
93
+ 8. **Estados da tela**: carregando (`hm-skeleton`), vazio (`hm-empty`) e erro (`hm-alert variant="error"` com
94
+ o botão "Tentar novamente") são três estados distintos; skeleton nunca fica no lugar de uma falha. Campo
95
+ `hm-*` ligado a formulário reativo desabilita por `control.disable()`, não por `[disabled]` (skill
96
+ `angular`).
97
+
98
+ ## 4. Tema, família, fonte e densidade
99
+
100
+ `data-theme` (claro/escuro/sistema), `data-family` (12 famílias: `hera` é o padrão), `data-density`
101
+ (`comfortable`/`compact`) e `data-font` (`geist` padrão, `roboto`, `rubik`, `figtree`) são aplicados num
102
+ elemento raiz e herdados pelos tokens. A escolha da pessoa fica no `localStorage` com um prefixo por app.
103
+ Usar só tokens e a escala `--hm-space-*` já faz a tela acompanhar tudo isso.
104
+
105
+ - **Com spine:** nada a fazer — o `provideUi` aplica no `<body>`, prefixa as chaves com o `clientId` e a
106
+ pessoa escolhe em Configurações › Aparência. Por código: `ThemeService`, `DensityService`,
107
+ `ThemePresetService` (`@trismegisto/spine`).
108
+ - **Sem spine:** um `hermesTheme` no elemento raiz + `HERMES_THEME_CONFIG`; troca por `HermesThemeService`
109
+ (`setMode`, `setFamily`, `setDensity`, `toggle`); seletor pronto: `hm-theme-picker`.
110
+
111
+ **Famílias e fontes próprias do app** (`HermesThemeExtension`, tudo opcional):
112
+
113
+ | Campo | Efeito |
114
+ |---|---|
115
+ | `families` | acrescenta no fim do seletor (mesmo `id` de uma da lib = substitui aquela) |
116
+ | `replace: { poseidon: minha }` | troca uma família **na mesma posição**; quem tinha escolhido a antiga passa para a nova (alias). Id inexistente é ignorado com aviso |
117
+ | `defaultFamily` | família inicial de quem ainda não escolheu |
118
+ | `fonts` | acrescenta fontes (arquivos do app; o `@font-face` e o `[data-font]` são gerados) |
119
+ | `replaceFonts: { roboto: minha }` | troca uma fonte na mesma posição; a preferência salva passa junto |
120
+ | `defaultFont` | fonte inicial |
121
+
122
+ ```ts
123
+ import type { HermesFamily, HermesFontDefinition } from '@trismegisto/primitives';
124
+
125
+ const MINHA_FAMILIA: HermesFamily = /* exportada pelo hm-theme-builder */;
126
+ const MINHA_SANS: HermesFontDefinition = {
127
+ id: 'minha-sans', label: 'Minha Sans', family: 'Minha Sans',
128
+ faces: [
129
+ { src: 'assets/fonts/minha-sans-regular.woff2', weight: 400 },
130
+ { src: 'assets/fonts/minha-sans-bold.woff2', weight: 700 }, // variável: weight: '100 900'
131
+ ],
132
+ };
133
+
134
+ // Com spine
135
+ provideUi({
136
+ clientId: environment.authorizationServer.clientId,
137
+ theme: {
138
+ replace: { poseidon: MINHA_FAMILIA }, defaultFamily: MINHA_FAMILIA.id,
139
+ replaceFonts: { roboto: MINHA_SANS }, defaultFont: 'minha-sans',
140
+ },
141
+ });
142
+
143
+ // Sem spine (mesmo objeto, composto à mão)
144
+ import { DEFAULT_THEME_CONFIG, extendThemeConfig } from '@trismegisto/primitives';
145
+ import { HERMES_THEME_CONFIG } from '@trismegisto/angular';
146
+ { provide: HERMES_THEME_CONFIG,
147
+ useValue: extendThemeConfig({ ...DEFAULT_THEME_CONFIG, storagePrefix: 'meu-app' },
148
+ { families: [MINHA_FAMILIA], defaultFamily: MINHA_FAMILIA.id, fonts: [MINHA_SANS] }) }
149
+ ```
150
+
151
+ - Monte a família no `hm-theme-builder` (confere contraste e distância das outras). O objeto exportado vai
152
+ no `theme`; o CSS exportado (`[data-family='minha']…`, superfícies próprias) entra no `styles` do app — sem
153
+ ele valem as superfícies neutras.
154
+ - `src` da fonte é relativo ao `<base href>`; `format` sai da extensão. Com spine, **não** registre
155
+ `HERMES_THEME_CONFIG` à mão: o `provideUi` já compõe com o prefixo do app.
156
+
157
+ ## 5. Páginas de estado e ilustrações
158
+
159
+ - **`hm-state-page kind="…"`** — página pronta com ilustração, título, descrição e ação do catálogo
160
+ (pt-BR/en/es, segue `setLocale`). Kinds: `not-found`, `no-content`, `no-rights`, `no-results`,
161
+ `session-expired`, `logged-out`, `error`, `blocked`, **`outdated`** ("Nova versão disponível": saiu um
162
+ build novo e o arquivo da tela sumiu do servidor; a ação deve recarregar). Inputs `heading`,
163
+ `description`, `action`, `actionIcon` sobrescrevem (`""` apaga; `action=""` tira o botão); `(actionTriggered)`.
164
+ ```html
165
+ <hm-state-page kind="no-rights" (actionTriggered)="voltar()" />
166
+ <hm-state-page kind="outdated" (actionTriggered)="recarregar()" /> <!-- window.location.reload() -->
167
+ ```
168
+ O spine já mostra `outdated` sozinho quando a rota não carrega por chunk ausente; em `import()` dinâmico
169
+ próprio, detecte com `isChunkLoadError(err)` (`@trismegisto/spine/routing`). Em código, os textos:
170
+ `statePagePreset(kind, inject(HERMES_MESSAGES))` (o `STATE_PAGE_PRESETS` fixo em pt-BR está depreciado).
171
+ - **`hm-state-screen situation="…"`** — o bloco genérico (título/descrição/ação livres): `empty`, `success`,
172
+ `error`, `attention`, `done`, `locked`, `unlocked`, `forbidden`, `not-found`, `session-expired`; outro
173
+ desenho vai no slot `[illustration]`. Vazio **dentro** de cartão/tabela é `hm-empty`; falha ao carregar é
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
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
+ da raiz (`@trismegisto/angular/illustration-error`…); prefira `hm-state-screen`/`hm-state-page`, que as
179
+ carregam sob demanda.
180
+
181
+ ## 6. Índice das referências (leia sob demanda)
182
+
183
+ | Arquivo | Quando ler |
184
+ |---|---|
185
+ | `references/angular.md` | **Primeiro**, ao construir qualquer tela: setup sem spine, tokens em detalhe, formulários (Reactive/template/sem form), tabela "Preciso de… / Use", depreciações, harnesses, armadilhas |
186
+ | `references/angular-recipes.md` | Ao montar um padrão completo: shell sem spine, listagem com data grid, formulário, wizard, filtros, kanban, árvore, agenda, upload, atalhos, login, theme builder, i18n/pipes, testes, gráficos e mapas (§1–§37) |
187
+ | `references/angular-types.md` | Ao montar dados para um componente (`MenuItem`, `GridColumn`, `SidebarNode`, enums de variante) |
188
+ | `references/angular-api.md` | Para conferir seletor, inputs/models/outputs, slots e métodos exatos de um `hm-*` (gerado do código; busque pelo seletor) |
189
+ | `references/angular-exports.md` | Para conferir o nome/assinatura de serviço, função, constante, token ou tipo antes de importar, por ponto de import (gerado; busque pelo nome) |
190
+ | `references/spine.md` | App com `@trismegisto/spine`: pontos de entrada, bootstrap (`provideUi`/`provideShell`/`provideAutoService`/`provideGraphql`), telas por `router_id`, `X-Route-Id`/`X-Client-Id`, GraphQL com `unwrap`, serviços do shell, auditoria, i18n, armadilhas |
191
+ | `references/spine-recipes.md` | Receitas do spine: bootstrap completo, página pública, tela nova com documentação, serviço REST/GraphQL, subscription, modal/painel, auditoria lazy, seção de configurações, novidades, marca, testes |
192
+ | `references/spine-api.md` | Para conferir exports exatos de cada `@trismegisto/spine/*` (gerado do código) |
193
+
194
+ Os arquivos `*-api.md` e `angular-exports.md` são grandes: use busca por nome em vez de ler inteiros.