@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.
- package/README.md +14 -11
- package/agents/revisor-orfeu.md +2 -1
- package/bin/install.js +41 -9
- package/package.json +1 -1
- package/skills/acropole/SKILL.md +2 -2
- package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
- package/skills/angular/SKILL.md +4 -3
- package/skills/angular/references/armadilhas.md +3 -3
- package/skills/angular/references/dados.md +3 -3
- package/skills/angular/references/estrutura.md +6 -5
- package/skills/angular/references/features.md +5 -5
- package/skills/angular/references/testes-build.md +1 -1
- package/skills/auto-servico/SKILL.md +18 -14
- package/skills/auto-servico/references/roteiros.md +1 -1
- package/skills/auto-servico/references/tools.md +1 -1
- package/skills/express/references/dados.md +4 -1
- package/skills/express/references/estrutura.md +2 -1
- package/skills/fastapi/references/banco.md +6 -2
- package/skills/fastapi/references/estrutura.md +1 -1
- package/skills/hefesto/SKILL.md +13 -6
- package/skills/hefesto/references/diagnostico.md +1 -0
- package/skills/hefesto/references/mcp-roteiros.md +48 -7
- package/skills/orfeu/SKILL.md +43 -13
- package/skills/orfeu/references/angular-api.md +39 -13
- package/skills/orfeu/references/angular-armadilhas.md +18 -1
- package/skills/orfeu/references/angular-recipes.md +25 -12
- package/skills/orfeu/references/angular.md +37 -15
- package/skills/orfeu/references/diferencas.md +17 -8
- package/skills/orfeu/references/node-api.md +41 -9
- package/skills/orfeu/references/node-armadilhas.md +16 -2
- package/skills/orfeu/references/node-recipes.md +13 -4
- package/skills/orfeu/references/node.md +31 -12
- package/skills/orfeu/references/python-api.md +41 -16
- package/skills/orfeu/references/python-recipes.md +13 -9
- package/skills/orfeu/references/python.md +33 -12
- package/skills/orfeu/references/react.md +133 -0
- package/skills/orquestracao/SKILL.md +3 -1
- package/skills/orquestracao/scripts/coord.sh +10 -2
- package/skills/trismegisto/SKILL.md +89 -35
- package/skills/trismegisto/references/angular-api.md +4548 -344
- package/skills/trismegisto/references/angular-exports.md +8275 -2579
- package/skills/trismegisto/references/angular-recipes.md +327 -6
- package/skills/trismegisto/references/angular-types.md +92 -0
- package/skills/trismegisto/references/angular.md +96 -16
- package/skills/trismegisto/references/catalogo/icones.json +7 -0
- package/skills/trismegisto/references/catalogo/imports.json +1627 -0
- package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
- package/skills/trismegisto/references/catalogo/tokens.json +114 -0
- package/skills/trismegisto/references/react-api.md +16864 -0
- package/skills/trismegisto/references/react.md +237 -0
- package/skills/trismegisto/references/spine-api.md +5904 -1361
- package/skills/trismegisto/references/spine-recipes.md +140 -46
- package/skills/trismegisto/references/spine.md +121 -49
- package/skills/trismegisto/scripts/checar.mjs +66 -1
|
@@ -1,25 +1,33 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Spine — guia do shell (casca Angular)
|
|
2
2
|
|
|
3
|
-
Escrito para a **
|
|
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,
|
|
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
|
-
|
|
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.
|
|
22
|
-
`
|
|
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`, `
|
|
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`,
|
|
35
|
-
| `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), `SPINE_BRAND`, `provideSettingsSection`, `SpineSettingsService`, `SpineDocsService`, `SpineNewsService`, `
|
|
36
|
-
| `@trismegisto/spine/modal` | `ModalService`, `ModalConfig`, `ModalContent` |
|
|
37
|
-
| `@trismegisto/spine/side-panel` | `SidePanelService`, `SidePanelConfig`, `SidePanelContent` |
|
|
38
|
-
| `@trismegisto/spine/notification` | `NotificationService
|
|
39
|
-
| `@trismegisto/spine/graphql` | `provideGraphql`, `injectGraphqlClient`, `unwrap`, `
|
|
40
|
-
| `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`, `AutoServiceService`,
|
|
41
|
-
| `@trismegisto/spine/audit` | `SpineAuditComponent` (`spine-audit`), `SpineAuditService`,
|
|
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
|
|
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
|
|
118
|
-
|
|
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
|
-
| `
|
|
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
|
|
161
|
-
nada disso em `features.routes.ts`: basta o client estar vinculado ao template de
|
|
162
|
-
Sem auto-serviço, o painel de configurações ainda pode listar tokens se o app
|
|
163
|
-
`{ provide: SPINE_ADMIN_API, useValue: environment.adminApi }`; sem isso,
|
|
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
|
-
|
|
176
|
-
|
|
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)
|
|
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
|
|
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 §
|
|
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
|
|
353
|
-
`export` estático de tela faria o
|
|
354
|
-
|
|
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`
|
|
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:**
|
|
371
|
-
|
|
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
|
|
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
|
|
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,
|