@acropole/skills 1.7.0 → 1.8.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 (54) hide show
  1. package/README.md +14 -11
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/bin/install.js +41 -9
  4. package/package.json +1 -1
  5. package/skills/acropole/SKILL.md +2 -2
  6. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
  7. package/skills/angular/SKILL.md +4 -3
  8. package/skills/angular/references/armadilhas.md +3 -3
  9. package/skills/angular/references/dados.md +3 -3
  10. package/skills/angular/references/estrutura.md +6 -5
  11. package/skills/angular/references/features.md +5 -5
  12. package/skills/angular/references/testes-build.md +1 -1
  13. package/skills/auto-servico/SKILL.md +18 -14
  14. package/skills/auto-servico/references/roteiros.md +1 -1
  15. package/skills/auto-servico/references/tools.md +1 -1
  16. package/skills/express/references/dados.md +4 -1
  17. package/skills/express/references/estrutura.md +2 -1
  18. package/skills/fastapi/references/banco.md +6 -2
  19. package/skills/fastapi/references/estrutura.md +1 -1
  20. package/skills/hefesto/SKILL.md +13 -6
  21. package/skills/hefesto/references/diagnostico.md +1 -0
  22. package/skills/hefesto/references/mcp-roteiros.md +48 -7
  23. package/skills/orfeu/SKILL.md +43 -13
  24. package/skills/orfeu/references/angular-api.md +39 -13
  25. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  26. package/skills/orfeu/references/angular-recipes.md +25 -12
  27. package/skills/orfeu/references/angular.md +37 -15
  28. package/skills/orfeu/references/diferencas.md +17 -8
  29. package/skills/orfeu/references/node-api.md +41 -9
  30. package/skills/orfeu/references/node-armadilhas.md +16 -2
  31. package/skills/orfeu/references/node-recipes.md +13 -4
  32. package/skills/orfeu/references/node.md +31 -12
  33. package/skills/orfeu/references/python-api.md +41 -16
  34. package/skills/orfeu/references/python-recipes.md +13 -9
  35. package/skills/orfeu/references/python.md +33 -12
  36. package/skills/orfeu/references/react.md +133 -0
  37. package/skills/orquestracao/SKILL.md +3 -1
  38. package/skills/orquestracao/scripts/coord.sh +10 -2
  39. package/skills/trismegisto/SKILL.md +89 -35
  40. package/skills/trismegisto/references/angular-api.md +4548 -344
  41. package/skills/trismegisto/references/angular-exports.md +8275 -2579
  42. package/skills/trismegisto/references/angular-recipes.md +327 -6
  43. package/skills/trismegisto/references/angular-types.md +92 -0
  44. package/skills/trismegisto/references/angular.md +96 -16
  45. package/skills/trismegisto/references/catalogo/icones.json +7 -0
  46. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  47. package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
  48. package/skills/trismegisto/references/catalogo/tokens.json +114 -0
  49. package/skills/trismegisto/references/react-api.md +16864 -0
  50. package/skills/trismegisto/references/react.md +237 -0
  51. package/skills/trismegisto/references/spine-api.md +5904 -1361
  52. package/skills/trismegisto/references/spine-recipes.md +140 -46
  53. package/skills/trismegisto/references/spine.md +121 -49
  54. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -1,25 +1,33 @@
1
- # @trismegisto/spine — guia do shell
1
+ # Spine — guia do shell (casca Angular)
2
2
 
3
- Escrito para a **API 2.0.1**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
3
+ Escrito para a **3.4.0**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
4
4
  prontas: `spine-recipes.md`. O conteúdo das telas (componentes `hm-*`, tokens, formulários) é do
5
5
  `@trismegisto/angular`: `angular.md`. Sessão, token, `PrivateGuard`, logout e troca de crachá são do
6
- `@orfeu/angular` — skill **orfeu**.
6
+ `@orfeu/angular` — skill **orfeu**. Shell em React: `react.md` §5.
7
+
8
+ **Forma desde a 3.4.0 (decisão A19):** o pacote `@trismegisto/spine` virou só o **núcleo sem framework** (tipos, regras,
9
+ constantes, catálogos de texto); a **casca Angular** (componentes, serviços, providers, rotas) mora no
10
+ `@trismegisto/angular`, nos pontos `@trismegisto/angular/spine` e `@trismegisto/angular/spine/<sub>`, fora do barrel
11
+ `@trismegisto/angular`. Os nomes da casca são os de antes; só o caminho mudou. Migração da 3.3.x: §11.
7
12
 
8
13
  O spine é o **esqueleto pronto** de um app Angular: cabeçalho (marca, busca de telas, apps,
9
14
  tema, perfil), menu lateral montado da árvore de rotas do servidor de autorização (Argos), área de trabalho
10
15
  em abas (`hm-workspace`), barra da página (título, descrição, trilha, favoritar, copiar link, documentação),
11
16
  telas de login/callback/saída/sem permissão/bloqueado, modal, painel lateral e toasts por serviço, painel
12
- de configurações, tour de boas-vindas, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
17
+ de configurações, novidades e atalhos de teclado. O app entrega **só as telas**; o resto
13
18
  vem do spine.
14
19
 
15
- Ele fica na ponta da cadeia `tokens ← icons ← primitives ← core ← angular ← spine` e é **acoplado à
20
+ A casca fica na ponta da cadeia `tokens ← icons ← primitives (+ núcleo spine) ← core ← angular` e é **acoplada à
16
21
  autenticação** do `@orfeu/angular` (OIDC + PKCE contra o Argos). Não serve a app que não se autentica no
17
22
  Argos — para esse caso, monte o shell à mão com o `@trismegisto/angular` (`angular-recipes.md` §1).
18
23
 
19
24
  ## 1. Instalação
20
25
 
21
- Pacotes, peers e `styles` do `angular.json`: `../SKILL.md` §2. Dependências diretas (vêm sozinhas): `marked` e
22
- `dompurify` (documentação das telas). `@orfeu/angular` precisa ser **uma cópia só** no app (ver armadilhas).
26
+ Pacotes, peers e `styles` do `angular.json`: `../SKILL.md` §2. Para o shell o app instala, além dos pacotes base:
27
+ `@trismegisto/spine` (núcleo), `@orfeu/angular`, `marked` e `dompurify` — todos **peers opcionais** do
28
+ `@trismegisto/angular`, então não vêm sozinhos: declare cada um no `package.json` do app (até a 3.3.x `marked` e
29
+ `dompurify` vinham como dependência do spine). Só com `/graphql`: `@apollo/client`, `apollo-angular`, `graphql`,
30
+ `graphql-ws`. `@orfeu/angular` precisa ser **uma cópia só** no app (ver armadilhas).
23
31
 
24
32
  Se as telas tiverem documentação (`document.load` com `import('./README.md')`), o loader de texto em
25
33
  `build.options`: `"loader": { ".md": "text" }` + um `src/markdown.d.ts` com
@@ -27,18 +35,37 @@ Se as telas tiverem documentação (`document.load` com `import('./README.md')`)
27
35
 
28
36
  ## 2. Pontos de entrada
29
37
 
38
+ **Casca Angular** (componentes, serviços, providers; a casca reexporta também os **tipos** do núcleo que usa):
39
+
30
40
  | Import | Para quê |
31
41
  |---|---|
32
- | `@trismegisto/spine` | `provideUi`, `SpineConfig`/`SPINE_CONFIG`, `Route` + `routerIdOf`, `applyRuntimeEnvironment`, `SPINE_ADMIN_API`, `provideSpineNews`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, catálogos), `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, logo/favicon (`SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon`) |
33
- | `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
34
- | `@trismegisto/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`, resolução de cadeia (`resolveRouteChain`, `findFirstNavigable`…) |
35
- | `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `OnboardingService`, `ShortcutService` e as peças do layout |
36
- | `@trismegisto/spine/modal` | `ModalService`, `ModalConfig`, `ModalContent` |
37
- | `@trismegisto/spine/side-panel` | `SidePanelService`, `SidePanelConfig`, `SidePanelContent` |
38
- | `@trismegisto/spine/notification` | `NotificationService`, `AlertType`, `Notification` |
39
- | `@trismegisto/spine/graphql` | `provideGraphql`, `injectGraphqlClient`, `unwrap`, `GraphqlEnvelopeError`, `wsReconnected$`, tipos `GraphqlEndpoint`/`GraphqlEnvelope` |
40
- | `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`, `AutoServiceService`, ids de router do template, `AUTO_SERVICE_SCREENS` |
41
- | `@trismegisto/spine/audit` | `SpineAuditComponent` (`spine-audit`), `SpineAuditService`, tipos e funções puras da auditoria — **importe só de código lazy** |
42
+ | `@trismegisto/angular/spine` | `provideUi`, `SPINE_CONFIG`, `SPINE_ADMIN_API`, `APP_PACKAGE_INFO`, i18n (`SPINE_MESSAGES`, `provideSpineMessages`, `currentSpineMessages`), `provideSpineSearch`, `ThemeService`, `DensityService`, `ThemePresetService`, `SpinePreferencesService`, `SpineQuickAccessService`, `SpineUserStorage`, `SPINE_ICONS` |
43
+ | `@trismegisto/angular/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, `ShellOptions`, telas públicas e de estado |
44
+ | `@trismegisto/angular/spine/routing` | `ComponentRoute`, `RouteDocument`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor` + `ROUTE_ID_HEADER`/`CLIENT_ID_HEADER`, `LoggerService`, `ComponentDistributorService`, `resolveSpineRoute`, `isChunkLoadError` |
45
+ | `@trismegisto/angular/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `SPINE_TAB`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `SpineInitialSetupService`, `ShortcutService`, `SpineLogoutService`, `SpineNoticesService`, `SpineWorkspaceNavService`, `registerSpineUnsavedChanges`, `spinePageTrail` e as peças do layout |
46
+ | `@trismegisto/angular/spine/modal` | `ModalService`, `ModalConfig`, `ModalContent` |
47
+ | `@trismegisto/angular/spine/side-panel` | `SidePanelService`, `SidePanelConfig`, `SidePanelContent` |
48
+ | `@trismegisto/angular/spine/notification` | `NotificationService` |
49
+ | `@trismegisto/angular/spine/graphql` | `provideGraphql`, `injectGraphqlClient`, `unwrap`, `failedEnvelopes`, `wsReconnected$`, `GraphqlClient`; tipos `GraphqlEndpoint`/`GraphqlEnvelope` (reexportados do núcleo) |
50
+ | `@trismegisto/angular/spine/auto-service` | `provideAutoService({ adminApi })`, `AutoServiceService`, `AUTO_SERVICE_SCREENS`, `AUTO_SERVICE_DOCUMENTS` |
51
+ | `@trismegisto/angular/spine/audit` | `SpineAuditComponent` (`spine-audit`), `SpineLoginAttemptsComponent`, `SpineAuditService`, `AUDIT_PAGE_SIZE` — **importe só de código lazy** |
52
+
53
+ **Núcleo sem framework** (`@trismegisto/spine` e `@trismegisto/spine/<módulo>`): tipos e **valores** (constante, função,
54
+ classe) que não dependem de Angular. A casca **não** reexporta valor do núcleo (só tipo): esses se importam daqui.
55
+ A raiz reexporta quase todos os módulos (fora `ai-agent`, `ai-agent-transcript`, `markdown`, `markdown-sanitize`).
56
+
57
+ | Módulo | Exemplos |
58
+ |---|---|
59
+ | `@trismegisto/spine` (raiz) / `runtime-environment` | `loadRuntimeConfig` (do primitives, só na raiz), `applyRuntimeEnvironment` |
60
+ | `config`, `brand` | tipos `SpineConfig`, `SpineFeatures`, `SpineMcpServer`, `SpineNoticeType`, `PackageInfo`; `SpineLogoConfig`, `resolveSpineLogo`, `applySpineFavicon` |
61
+ | `route`, `route-chain` | `Route`, `routerIdOf`, `resolveRouteChain`, `findFirstNavigable` |
62
+ | `notification` | `AlertType`, `Notification` |
63
+ | `graphql` | `GraphqlEnvelopeError`, `isEnvelopeOk`, `envelopesOf` |
64
+ | `settings`, `workspace-nav`, `search`, `quick-access` | `SPINE_SETTINGS_KEYS`, `SPINE_SETTINGS_ALIASES`; `SPINE_WORKSPACE_LIMITS`; `SpineSearchProvider`, `SpineSearchResult`; `QuickAccessItem` |
65
+ | `auto-service`, `audit`, `login-attempts` | `AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`; `buildAuditQuery`, `auditApiBase`… |
66
+ | `messages` (`/en`, `/es`) | `SpineMessages`, `SPINE_MESSAGES_PT_BR`/`_EN`/`_ES` |
67
+
68
+ Lista completa dos valores que saíram da casca na 3.4.0: §11.
42
69
 
43
70
  ## 3. Bootstrap
44
71
 
@@ -65,7 +92,7 @@ loadRuntimeConfig(environment, { required: !isDevMode() })
65
92
  .catch((err) => console.error(err));
66
93
  ```
67
94
 
68
- `loadRuntimeConfig(environment, { file?, required? })` (3.1.0; do `@trismegisto/primitives`, reexportado aqui)
95
+ `loadRuntimeConfig(environment, { file?, required? })` (3.1.0; do `@trismegisto/primitives`, reexportado na raiz do núcleo `@trismegisto/spine`)
69
96
  busca `config.json` (ou `file`) relativo ao `<base href>` e o mescla no `environment` (objetos chave a chave;
70
97
  arrays e valores simples substituem). É o que permite **uma imagem por versão**: o build não sabe o ambiente, o
71
98
  deploy põe ao lado do `index.html` a cópia de `src/brand/config/<ambiente>.json`. Com `required`, falta ou JSON
@@ -88,10 +115,10 @@ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
88
115
  import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
89
116
  import { provideRouter } from '@angular/router';
90
117
  import { provideAuth } from '@orfeu/angular/core';
91
- import { provideUi } from '@trismegisto/spine';
92
- import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
93
- import { provideAutoService } from '@trismegisto/spine/auto-service';
94
- import { provideGraphql } from '@trismegisto/spine/graphql';
118
+ import { provideUi } from '@trismegisto/angular/spine';
119
+ import { APP_ROUTES, provideShell } from '@trismegisto/angular/spine/shell';
120
+ import { provideAutoService } from '@trismegisto/angular/spine/auto-service';
121
+ import { provideGraphql } from '@trismegisto/angular/spine/graphql';
95
122
  import { components } from './features/features.routes';
96
123
  import { environment } from '../environments/environment';
97
124
  import packageInfo from '../../package.json';
@@ -114,8 +141,9 @@ export const appConfig: ApplicationConfig = {
114
141
 
115
142
  O que cada provider faz:
116
143
 
117
- - **`provideUi(config?: SpineConfig)`** — registra o catálogo de ícones **inteiro** (`HERMES_ICONS`; o app
118
- não precisa de `provideHermesIcons`), aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
144
+ - **`provideUi(config?: SpineConfig)`** — registra os ícones do próprio spine (`SPINE_ICONS`) e carrega o catálogo
145
+ inteiro **sob demanda** (`provideHermesIconLoader`, desde a 3.3.1): ícone do app não registrado aparece quando o
146
+ chunk chega (para desenhar já no 1º quadro, `provideHermesIcons(...)` com os do app); aplica tema/família/densidade/fonte no `<body>` (`ThemeService`),
119
147
  fornece `SPINE_CONFIG` e usa `hermes_<clientId>` como prefixo de **todas** as chaves salvas (tema, menu
120
148
  lateral, abas do workspace, idioma, fuso, novidades, favoritos…): apps na mesma origem não misturam
121
149
  preferências. Aplica `favicon` no bootstrap se configurado. Opções de `SpineConfig`:
@@ -135,13 +163,15 @@ O que cada provider faz:
135
163
 
136
164
  | Campo | O que liga |
137
165
  |---|---|
138
- | `aiAgent: { servers: SpineMcpServer[] }` | Sessões › "Conectar um agente de IA": token de aplicação + `.mcp.json` pronto (precisa de `SPINE_ADMIN_API`) |
166
+ | `mcpConnect: { servers: SpineMcpServer[] }` | Sessões › "Conectar um agente de IA": token de aplicação + `.mcp.json` pronto (precisa de `SPINE_ADMIN_API`). `onlyBadges`/`exceptBadges` em cada servidor (nome do badge) mostram só os servidores do nível da pessoa; com um só, sem seletor |
139
167
  | `accountActivity: true` | MFA › "Atividade da conta": entradas e tentativas que falharam (últimos 90 dias) |
140
168
  | `idleTimeout: true \| { min?, max? }` | Conta › "Encerrar por inatividade" (com `max`, some o "Nunca") |
141
169
  | `startPage: true` | Conta › "Tela inicial" depois do login: início, um favorito ou a última tela |
142
170
  | `defaultBadge: true` | Conta › "Crachá padrão" (nível de acesso do login, guardado no Argos) |
143
- | `notices: { types: SpineNoticeType[] }` | seção Notificações: liga/desliga cada tipo de aviso e o aviso do navegador; o app emite com `SpineNoticesService.notify(tipo, { title, body?, url?, intent? })` (`@trismegisto/spine/layout`) |
171
+ | `notices: { types: SpineNoticeType[] }` | seção Notificações: liga/desliga cada tipo de aviso e o aviso do navegador; o app emite com `SpineNoticesService.notify(tipo, { title, body?, url?, intent? })` (`@trismegisto/angular/spine/layout`) |
144
172
  | `accountPreferences: true` | guarda as preferências (aparência, região, acessibilidade, favoritos, tela inicial…) também na conta do Argos |
173
+ | `skipLink: true` | link "Pular para o conteúdo" (`hm-skip-link`) como primeira parada do Tab, levando à área de trabalho |
174
+ | `unsavedChanges: true` | aviso de alterações não salvas: a tela registra com `registerSpineUnsavedChanges(() => form.dirty)` (`@trismegisto/angular/spine/layout`, num campo da classe); fechar a aba/painel dela ou trocar de tela dentro dela pergunta antes, e o navegador avisa ao recarregar |
145
175
 
146
176
  - **`provideRouter(APP_ROUTES)`** — `APP_ROUTES` = `PUBLIC_ROUTES` (`/login`, `/callback`, `/logoff`,
147
177
  `/blocked`, `''` → `login`) + `{ path: '', component: LayoutComponent, canActivate/canActivateChild:
@@ -157,10 +187,16 @@ O que cada provider faz:
157
187
  se um `id` do app repetir um id das telas base do shell.
158
188
  - **`provideAutoService({ adminApi })`** — liga as 6 telas do auto-serviço (Início, Grupos, Aplicações,
159
189
  Cliente, Auditoria, Tentativas de login) pelo `source_template_router_id` do template do Argos, todas **lazy**, e fornece
160
- `SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação). O app não declara
161
- nada disso em `features.routes.ts`: basta o client estar vinculado ao template de auto-serviço no Argos.
162
- Sem auto-serviço, o painel de configurações ainda pode listar tokens se o app fornecer
163
- `{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essa parte se esconde.
190
+ `SPINE_ADMIN_API` (usado também pelo painel de configurações para os tokens de aplicação e para a seção
191
+ **Grupos**). O app não declara nada disso em `features.routes.ts`: basta o client estar vinculado ao template de
192
+ auto-serviço no Argos. Sem auto-serviço, o painel de configurações ainda pode listar tokens e grupos se o app
193
+ fornecer `{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso, essas partes se escondem.
194
+ - **Seção Grupos** (desde a 3.2.0, `?settings=grupos`): vem pronta, sem nada no app. Lista os grupos da aplicação
195
+ logada de que a pessoa é membro (argos-admin `/me/groups`); cada um abre a tela de membros. A **função** no grupo
196
+ (não o crachá) decide: Administrador inclui como Administrador, Editor ou membro, troca funções e remove qualquer
197
+ um menos a si mesmo; Editor inclui e remove só membros sem função; o membro sem função só vê. A regra é do
198
+ argos-admin; a seção some sem grupo nenhum ou com um argos-admin que ainda não tem a rota. A lista de membros é
199
+ carregada inteira em páginas de 200 do servidor, uma depois da outra, com a busca local (desde a 3.3.4).
164
200
  - **`provideGraphql({ endpoints })`** — um cliente Apollo nomeado por backend (seção 6).
165
201
 
166
202
  ### 3.3 Componente raiz
@@ -171,9 +207,9 @@ export class AppComponent {}
171
207
  ```
172
208
 
173
209
  Só isso. O tema já está no `<body>`: **não** ponha `hermesTheme`, `hm-header`, `hm-sidebar` nem
174
- `hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace,
175
- `spine-notification`, `spine-modal`, `spine-side-panel`, painel de atalhos, configurações, documentação,
176
- novidades e tour.
210
+ `hm-toast-stack` no app — o `spine-layout` já monta cabeçalho, aviso de conexão, menu, workspace, a pilha de
211
+ toasts (`hm-toast-stack`, onde saem o `NotificationService` e o `HermesToastService`), `spine-modal`,
212
+ `spine-side-panel`, painel de atalhos, configurações, documentação e novidades.
177
213
 
178
214
  ### 3.4 Sessão e aviso de conexão (`@orfeu/angular`)
179
215
 
@@ -206,7 +242,7 @@ A árvore de navegação **não está no app**: vem do `/view` do Argos (`ViewSe
206
242
  router. Chunk que sumiu do servidor (build novo com a aba aberta, `isChunkLoadError`): página pronta
207
243
  `hm-state-page kind="outdated"` ("Nova versão disponível") com o botão "Recarregar" (`window.location.reload()`).
208
244
  Não há nada a configurar; em telas próprias que fazem `import()` dinâmico, use `isChunkLoadError(err)` para
209
- mostrar a mesma página (`isChunkLoadError` sai de `@trismegisto/spine/routing`).
245
+ mostrar a mesma página (`isChunkLoadError` sai de `@trismegisto/angular/spine/routing`).
210
246
  - **Título e descrição** da tela aparecem na `spine-page-bar` do painel: título = `route_display_name`,
211
247
  descrição = `Route.description` (`web.router.description`, editada no Argos), ícone = `route_icon` (ou o do
212
248
  módulo). **A tela não repete título nem descrição** no próprio template — comece direto pelo conteúdo
@@ -237,7 +273,7 @@ interceptor em silêncio e nenhum evento de auditoria sai com tela/app.
237
273
  O interceptor **não** põe o token. Nas APIs REST do app, mande `x-access-token` com
238
274
  `inject(AuthorizationService).getToken()` (receitas §4; detalhes na skill orfeu).
239
275
 
240
- ## 6. GraphQL (`@trismegisto/spine/graphql`)
276
+ ## 6. GraphQL (`@trismegisto/angular/spine/graphql`)
241
277
 
242
278
  ```ts
243
279
  // environment.ts (vazio = derivado atrás do proxy; URL explícita vem do config.json do ambiente)
@@ -277,13 +313,14 @@ async listTeams() {
277
313
  - Trate o erro como **estado da tela** (`resource().error()`, `catch` → `hm-alert`/`hm-state-screen`), não
278
314
  `console.error` nem `?? []`. Decida por `err.status` (403 sem acesso, 404 vazio, 5xx tentar de novo). Mostre
279
315
  `message` como texto, nunca por `innerHTML`.
280
- - Utilitários: `isEnvelopeOk(status)`, `envelopesOf(data)`, `failedEnvelopes(data)`.
316
+ - Utilitários: `failedEnvelopes(data)` (casca); `isEnvelopeOk(status)`, `envelopesOf(data)` e a classe
317
+ `GraphqlEnvelopeError` (para `instanceof`) vêm do núcleo `@trismegisto/spine/graphql` (desde a 3.4.0 a casca não os reexporta).
281
318
 
282
319
  ## 7. Serviços do shell para as telas
283
320
 
284
321
  | Preciso de… | Use |
285
322
  |---|---|
286
- | Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos. `processErrorNotification()` = erro genérico do catálogo |
323
+ | Toast | `NotificationService.addNotification({ timer, hermesAlertType, message, hermesAlertClosable? })` (`@trismegisto/angular/spine/notification`). `timer` em segundos; `hermesAlertType` = `AlertType` ou um status HTTP (vira tipo por faixa). A mensagem passa por redação de segredos e sai na pilha de toasts do `HermesToastService` (3.3.0; antes era uma coluna de `hm-alert` à parte). `processErrorNotification()` = erro genérico do catálogo |
287
324
  | Modal com componente | `ModalService.open<R, D>({ title, component, data, size: 'sm'\|'md'\|'lg'\|'xl', closable, showActions })` → `Observable<R \| null>` (`null` = cancelado/substituído). O componente implementa `ModalContent` (`getResult()`, `isValid?()`), recebe `data` por `readonly data = input<D>()` e o botão Confirmar fica desabilitado enquanto `isValid()` for falso. Só um aberto por vez |
288
325
  | Modal só texto | `ModalService.open({ title, text })` |
289
326
  | Painel lateral | `SidePanelService.open(...)` — mesma API (`SidePanelContent` = `ModalContent`), `size` aceita também `'full'` |
@@ -291,10 +328,10 @@ async listTeams() {
291
328
  | Diálogo de confirmação simples | `HermesDialogService.confirm(...)` do `@trismegisto/angular` (não precisa do spine) |
292
329
  | Abrir configurações | `SpineSettingsService.open(SPINE_SETTINGS_KEYS.appearance)` ou link `?settings=aparencia` |
293
330
  | Abrir documentação | `SpineDocsService.openIndex()` / `openForRoute(routerId)` |
294
- | Reabrir tour / novidades | `OnboardingService.restart()` / `SpineNewsService.showAll()` |
331
+ | Reabrir novidades | `SpineNewsService.showAll()` (tour guiado de uma tela: `hm-tour`, do `@trismegisto/angular`; o spine não tem tour próprio) |
295
332
  | Fuso e idioma da pessoa | `SpinePreferencesService.effectiveTimeZone()` (sinal; IANA) e `language()`; também `hourCycle()`, `weekStart()`, `textScale()`, `motion()` |
296
333
  | Avisar a pessoa de um acontecimento | `SpineNoticesService.notify('tipo', { title, body?, url? })` com o tipo declarado em `SpineConfig.features.notices` — respeita o liga/desliga de Configurações › Notificações |
297
- | Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/spine/routing`) |
334
+ | Página atual | `LoggerService.page`, `.routerId`, `.routeId` (`@trismegisto/angular/spine/routing`) |
298
335
  | Tema/densidade por código | `ThemeService.setMode('light'\|'dark'\|'system')`, `setTheme`, `DensityService.setDensity('comfortable'\|'compact')`, `toggleDensity()`, `ThemePresetService.setPreset(family)` — sincronizam entre abas. Em geral **não precisa**: o painel de configurações já oferece tudo |
299
336
 
300
337
  Atalhos globais já registrados: `G H` (início), `G 1…9` (favoritos), `Mod+K` (busca), `Mod+,`
@@ -308,7 +345,7 @@ sozinho no painel `?`. Não reuse essas combinações.
308
345
  (`AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`) e ficam em chunks próprios (`AUTO_SERVICE_SCREENS`). As classes das
309
346
  telas **não são exportadas** de propósito. `AutoServiceService` expõe o HTTP (`{adminApi}/auto-service/...`)
310
347
  para quem precisar.
311
- - **Auditoria** (`@trismegisto/spine/audit`): `<spine-audit scope="admin" />` (todos os apps,
348
+ - **Auditoria** (`@trismegisto/angular/spine/audit`): `<spine-audit scope="admin" />` (todos os apps,
312
349
  `{adminApi}/admin/audit/*`) ou `<spine-audit scope="client" [clientId]="id" />` (apps do projeto do client,
313
350
  `{adminApi}/auto-service/:clientId/audit/*`, recorte no servidor). `adminApi` pelo input `[adminApi]` ou
314
351
  pelo `SPINE_ADMIN_API`. Inclui período rápido, filtros (com filtros salvos), KPIs, linha do tempo,
@@ -346,16 +383,17 @@ sozinho no painel `?`. Não reuse essas combinações.
346
383
  2. **Telas sempre lazy.** `ComponentRoute.load` é `() => import('./x.component').then((m) => m.X)`. Nunca
347
384
  importe a classe de uma tela estaticamente em `features.routes.ts`, `app.config.ts` ou serviço global.
348
385
  Um `features.routes.spec.ts` confere que todo `load()` resolve e que os `id` são UUID únicos, sem
349
- diferenciar maiúsculas (receitas §14).
350
- 3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/spine/audit` em código do bundle
386
+ diferenciar maiúsculas (receitas §15).
387
+ 3. **Auditoria e auto-serviço continuam lazy.** Não importe `@trismegisto/angular/spine/audit` em código do bundle
351
388
  inicial (só em rota/`import()`/`@defer`). As telas do auto-serviço nem são exportadas; não tente
352
- alcançá-las por caminho interno. (O pacote confere isso no próprio build com `scripts/check-lazy.mjs`: um
353
- `export` estático de tela faria o rollup trocar o `import()` por `Promise.resolve()` e colar a tela no
354
- bundle inicial de todo app.)
389
+ alcançá-las por caminho interno. (O `@trismegisto/angular` confere isso no próprio build com
390
+ `scripts/check-spine-lazy.mjs`: um `export` estático de tela faria o bundler colar a tela no bundle inicial de
391
+ todo app.) Pelo mesmo motivo, código que entra no `main` importa do ponto (`@trismegisto/angular/spine/...`),
392
+ nunca do barrel `@trismegisto/angular`.
355
393
  4. **`COMPONENT_ROUTES` é `multi`.** Contribua pelo `provideShell` (ou com `{ provide: COMPONENT_ROUTES,
356
394
  useValue: [...], multi: true }`). Sem `multi: true` o Angular lança erro de provider inconsistente.
357
395
  5. **Id da tela = `router_id`** (`routerIdOf`). `routed_id`/`web.routes.route_id` não acha componente; é o que
358
- vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` são nomes antigos depreciados (use `id`/`load`).
396
+ vai no `X-Route-Id`. `ComponentRoute.route_id`/`component` saíram na 3.3.1 (use `id`/`load`).
359
397
  6. **Uma cópia do `@orfeu/angular`.** App e spine precisam resolver o mesmo pacote; duas cópias (versões
360
398
  diferentes, `file:` duplicado, SDK antigo no app) dão `NullInjectorError` em `AUTH_CONFIG` ou uma segunda
361
399
  sessão. Confira com `npm ls @orfeu/angular`.
@@ -367,13 +405,47 @@ sozinho no painel `?`. Não reuse essas combinações.
367
405
  troca de aba (`keepAlive`): recarregue dados por ação da pessoa, `wsReconnected$` ou sinal, não por
368
406
  `ngOnInit` a cada visita.
369
407
  10. **Envelope GraphQL sempre por `unwrap`.** Não confie no HTTP 200.
370
- 11. **Detecção de mudanças:** os apps de referência usam `provideZoneChangeDetection`; parte do shell ainda usa
371
- a estratégia `Eager` e `NgZone`. Funcionamento sem zone.js não é garantido.
408
+ 11. **Detecção de mudanças:** desde a 3.3.1 todo o shell é `OnPush` (os apps de referência usam
409
+ `provideZoneChangeDetection`). Tela e componente aberto no `ModalService`/`SidePanelService` ficam sob pai
410
+ `OnPush`: estado que muda depois de `await`/`subscribe` vai em signal (ou `markForCheck()`).
372
411
  12. **Documentação de tela** é markdown cru importado como texto (loader `.md: "text"`); o texto vai no chunk
373
412
  da tela e o índice só lista telas que a pessoa enxerga.
374
- 13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e tour.
413
+ 13. **Chaves salvas** usam o `clientId`: trocar o `clientId` de um app "zera" tema, abas, favoritos e novidades vistas.
375
414
  14. **Logo** é arquivo do app (`src/assets/images/logo.svg` por convenção), legível sobre o fundo escuro do
376
415
  cabeçalho **nos dois temas**; marca em componente via `SPINE_BRAND` (sem link/botão dentro).
377
416
 
417
+ 15. **Valor do núcleo vem do núcleo.** `GraphqlEnvelopeError`, `isEnvelopeOk`, `AlertType`, `routerIdOf`,
418
+ `SPINE_SETTINGS_KEYS`, `AUTO_SERVICE_*_TEMPLATE_ROUTER_ID`… se importam de `@trismegisto/spine[/módulo]`. Importados
419
+ da casca, dão `TS1362 ('X' cannot be used as a value because it was exported using 'export type')` ou `has no
420
+ exported member`. Tipos podem vir de qualquer um dos dois.
421
+
422
+ ## 11. Migração da 3.3.x para a 3.4.0
423
+
424
+ 1. **`package.json`:** todos os `@trismegisto/*` em `^3.4.0`; acrescente `marked` e `dompurify` (antes vinham com o
425
+ spine; agora são peers opcionais) e mantenha `@trismegisto/spine` e `@orfeu/angular` (peers opcionais da casca).
426
+ 2. **Imports da casca** (troca mecânica, mesmos nomes):
427
+
428
+ | 3.3.x | 3.4.0 |
429
+ |---|---|
430
+ | `@trismegisto/spine` (`provideUi`, `SPINE_CONFIG`, `SPINE_ADMIN_API`, `SPINE_MESSAGES`, `provideSpineMessages`, `provideSpineSearch`, `ThemeService`…) | `@trismegisto/angular/spine` |
431
+ | `@trismegisto/spine/<sub>` (`layout`, `shell`, `routing`, `modal`, `notification`, `side-panel`, `graphql`, `auto-service`, `audit`) | `@trismegisto/angular/spine/<sub>` |
432
+ | `@trismegisto/spine` (`applyRuntimeEnvironment`, `loadRuntimeConfig`, `Route`, `routerIdOf`, tipos de `SpineConfig`…) | continua `@trismegisto/spine` (núcleo) |
433
+
434
+ 3. **Valores que saíram da casca** (agora só no núcleo; tabela completa no `docs/migration/apps-impact.md` do Trismegisto):
435
+
436
+ | Estavam em | Agora em | Exemplos |
437
+ |---|---|---|
438
+ | `…/spine/graphql` | `@trismegisto/spine/graphql` | `GraphqlEnvelopeError`, `isEnvelopeOk`, `envelopesOf` |
439
+ | `…/spine/notification` | `@trismegisto/spine/notification` | `AlertType` |
440
+ | `…/spine/audit` | `@trismegisto/spine/audit` e `/login-attempts` | `AUDIT_*` (menos `AUDIT_PAGE_SIZE`, que fica na casca), `buildAuditQuery`, `auditApiBase`, `LOGIN_ATTEMPT_*` |
441
+ | `…/spine/auto-service` | `@trismegisto/spine/auto-service` | `AUTO_SERVICE_*_TEMPLATE_ROUTER_ID` |
442
+ | `…/spine/layout` | `@trismegisto/spine/settings`, `/workspace-nav`, `/suggestions`, `/ratings`, `/markdown-sanitize`, `/idle`, `/inbox`, `/account-preferences`, `/account-security`, `/app-tokens`, `/start-page`, `/ai-agent-page` | `SPINE_SETTINGS_KEYS`, `SPINE_SETTINGS_ALIASES`, `resolveSettingsSection`, `SPINE_WORKSPACE_LIMITS`, `SPINE_PRESENT_PARAM`, `SPINE_SUGGESTION_*`, `spineStarFills`, `SPINE_MARKDOWN_PURIFY_CONFIG`, `SPINE_IDLE_WARNING_SECONDS`, `SPINE_INBOX_POLL_MS`, `argosAccountApi`, `buildMcpConfig`, `isInternalPath`, `SPINE_AI_AGENT_PAGE_PATH` |
443
+
444
+ Os documentos do auto-serviço (`news|ratings|suggestions.{usage,technical}`) ficam só em
445
+ `@trismegisto/spine/auto-service-docs/*`.
446
+ 4. **Gráficos, mapas e terminal**, se usados: `angular.md` §9.
447
+ 5. `npm install`, `ng build` e os testes: qualquer import esquecido vira erro de compilação (nada falha em silêncio).
448
+ Para conferir: `grep -rn "@trismegisto/spine/" src` só pode achar módulos do núcleo.
449
+
378
450
  Se você está **desenvolvendo o próprio spine** (não um app consumidor), siga as convenções do repositório
379
451
  dele; este guia é para quem consome o pacote.
@@ -29,6 +29,34 @@ for (const s of SELETORES) {
29
29
  }
30
30
  }
31
31
 
32
+ /** Caminhos de import desde a 3.4.0: o que cada casca Angular exporta e os valores/tipos de cada módulo do núcleo do spine. */
33
+ const IMPORTS = ler('imports.json');
34
+ const NUCLEO_SPINE = '@trismegisto/spine';
35
+ /** Nome → pontos da casca do spine que o exportam. */
36
+ const NA_CASCA = new Map();
37
+ for (const [ponto, nomes] of Object.entries(IMPORTS.casca)) {
38
+ if (!ponto.startsWith('@trismegisto/angular/spine')) continue;
39
+ for (const n of nomes) NA_CASCA.set(n, [...(NA_CASCA.get(n) ?? []), ponto]);
40
+ }
41
+ /** Valor do núcleo → módulos que o exportam. Tudo o que a raiz `@trismegisto/spine` pode exportar. */
42
+ const VALOR_NO_NUCLEO = new Map();
43
+ const NA_RAIZ_DO_NUCLEO = new Set(['loadRuntimeConfig', 'LoadRuntimeConfigOptions']);
44
+ for (const [modulo, { valores, tipos }] of Object.entries(IMPORTS.nucleo)) {
45
+ for (const n of valores) VALOR_NO_NUCLEO.set(n, [...(VALOR_NO_NUCLEO.get(n) ?? []), modulo]);
46
+ for (const n of [...valores, ...tipos]) NA_RAIZ_DO_NUCLEO.add(n);
47
+ }
48
+ /** Componentes e providers das cascas de gráficos, mapas e terminal (que até a 3.3.x saíam do pacote do núcleo). */
49
+ const CASCA_DA_PECA = { '@trismegisto/charts': '@trismegisto/angular/charts', '@trismegisto/maps': '@trismegisto/angular/map', '@trismegisto/terminal': '@trismegisto/angular/terminal' };
50
+ const PROPRIO_DA_CASCA = /Component$|^HM_|^provide\w+Messages$|I18nService$|_I18N_CONFIG$|^(?:MAPS|TERMINAL)_MESSAGES$/;
51
+
52
+ /** `import { a, type b } from 'x'` (também `import type`), com a posição de cada um. */
53
+ function* importsNomeados(texto) {
54
+ for (const m of texto.matchAll(/\bimport\s+(type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g)) {
55
+ const nomes = m[2].split(',').map((n) => n.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim()).filter(Boolean);
56
+ yield { origem: m[3], nomes, pos: m.index };
57
+ }
58
+ }
59
+
32
60
  /** Distância de edição (para sugerir o nome mais próximo). */
33
61
  function distancia(a, b) {
34
62
  const d = Array.from({ length: a.length + 1 }, (_, i) => [i]);
@@ -195,6 +223,43 @@ const regras = [
195
223
  return out;
196
224
  },
197
225
  },
226
+ {
227
+ id: 'import-3-4',
228
+ resumo: 'import pelo caminho anterior à 3.4.0 (casca do spine, gráficos, mapas e terminal no @trismegisto/angular; valores no núcleo)',
229
+ aceita: (a) => a.ext === '.ts',
230
+ checar(arq) {
231
+ const out = [];
232
+ const achado = (pos, mensagem, correcao) => out.push({ linha: arq.linhaDe(pos), mensagem, correcao });
233
+ for (const imp of importsNomeados(arq.limpo)) {
234
+ const { origem, nomes, pos } = imp;
235
+ // 1. Casca do spine importada pelo pacote do núcleo (`@trismegisto/spine[/sub]`).
236
+ if (origem === NUCLEO_SPINE || origem.startsWith(NUCLEO_SPINE + '/')) {
237
+ const doModulo = origem === NUCLEO_SPINE ? NA_RAIZ_DO_NUCLEO : new Set([...(IMPORTS.nucleo[origem]?.valores ?? []), ...(IMPORTS.nucleo[origem]?.tipos ?? [])]);
238
+ for (const n of nomes) {
239
+ if (doModulo.has(n) || !NA_CASCA.has(n)) continue;
240
+ const destino = NA_CASCA.get(n).find((p) => p.endsWith(origem.slice(NUCLEO_SPINE.length))) ?? NA_CASCA.get(n)[0];
241
+ achado(pos, `\`${n}\` não está em \`${origem}\` desde a 3.4.0: o pacote virou só o núcleo do spine e a casca Angular mudou de lugar`, `importe de \`${destino}\` (references/spine.md §11)`);
242
+ }
243
+ }
244
+ // 2. Valor do núcleo importado da casca (a casca só reexporta tipos: TS1362).
245
+ if (IMPORTS.casca[origem] && origem.startsWith('@trismegisto/angular/spine')) {
246
+ for (const n of nomes) {
247
+ if (IMPORTS.casca[origem].includes(n) || !VALOR_NO_NUCLEO.has(n)) continue;
248
+ achado(pos, `\`${n}\` é valor do núcleo e não sai de \`${origem}\` (a casca reexporta só tipos)`, `importe de \`${VALOR_NO_NUCLEO.get(n)[0]}\` (references/spine.md §11)`);
249
+ }
250
+ }
251
+ // 3. Componente/provider de gráfico, mapa ou terminal importado do pacote do núcleo.
252
+ const casca = CASCA_DA_PECA[origem];
253
+ if (casca) {
254
+ for (const n of nomes) {
255
+ if (!PROPRIO_DA_CASCA.test(n) || !IMPORTS.casca[casca]?.includes(n)) continue;
256
+ achado(pos, `\`${n}\` saiu de \`${origem}\` na 3.4.0 (o pacote virou só o núcleo sem framework)`, `importe de \`${casca}\`; tipos de dados e catálogos continuam em \`${origem}\` (references/angular.md §9)`);
257
+ }
258
+ }
259
+ }
260
+ return out;
261
+ },
262
+ },
198
263
  ];
199
264
 
200
265
  /** Tokens `--hm-*` que o próprio app declara (tema/família exportados do theme builder etc.). */
@@ -209,7 +274,7 @@ function preparar(arquivos, ctx) {
209
274
 
210
275
  process.exitCode = executar({
211
276
  skill: 'trismegisto',
212
- descricao: 'cores cravadas, tokens/seletores/ícones inexistentes e (click) em botão do Trismegisto.',
277
+ descricao: 'cores cravadas, tokens/seletores/ícones inexistentes, (click) em botão do Trismegisto e imports anteriores à 3.4.0.',
213
278
  regras,
214
279
  extensoes: ['.ts', '.html', '.css', '.scss', '.less'],
215
280
  preparar,