@acropole/skills 0.0.0-stage → 1.1.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 (92) hide show
  1. package/README.md +181 -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 +80 -0
  9. package/skills/acropole/references/arquitetura.md +174 -0
  10. package/skills/acropole/references/fluxos/app-novo.md +34 -0
  11. package/skills/acropole/references/fluxos/doctor.md +55 -0
  12. package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
  13. package/skills/acropole/references/fluxos/revisar.md +56 -0
  14. package/skills/acropole/references/fluxos/tela-nova.md +27 -0
  15. package/skills/acropole/scripts/doctor.mjs +439 -0
  16. package/skills/angular/SKILL.md +155 -0
  17. package/skills/angular/references/armadilhas.md +99 -0
  18. package/skills/angular/references/dados.md +251 -0
  19. package/skills/angular/references/estrutura.md +279 -0
  20. package/skills/angular/references/features.md +219 -0
  21. package/skills/angular/references/testes-build.md +257 -0
  22. package/skills/angular/scripts/checar.mjs +182 -0
  23. package/skills/angular/scripts/nucleo.mjs +227 -0
  24. package/skills/apollo/SKILL.md +226 -0
  25. package/skills/apollo/references/armadilhas.md +99 -0
  26. package/skills/apollo/references/envelope-erros.md +120 -0
  27. package/skills/apollo/references/estrutura-bootstrap.md +310 -0
  28. package/skills/apollo/references/schema-resolvers.md +183 -0
  29. package/skills/apollo/references/subscriptions.md +224 -0
  30. package/skills/apollo/references/testes-build.md +181 -0
  31. package/skills/apollo/scripts/checar.mjs +160 -0
  32. package/skills/apollo/scripts/nucleo.mjs +227 -0
  33. package/skills/docker/SKILL.md +102 -0
  34. package/skills/docker/references/modelos.md +251 -0
  35. package/skills/docker/references/porques.md +286 -0
  36. package/skills/documentacao/SKILL.md +146 -0
  37. package/skills/documentacao/references/checklist-coerencia.md +59 -0
  38. package/skills/documentacao/references/ligar-app-novo.md +107 -0
  39. package/skills/documentacao/references/modelo-especificacao.md +51 -0
  40. package/skills/documentacao/references/modelo-readme.md +75 -0
  41. package/skills/documentacao/scripts/checar.mjs +454 -0
  42. package/skills/documentacao/scripts/nucleo.mjs +227 -0
  43. package/skills/express/SKILL.md +156 -0
  44. package/skills/express/references/dados.md +180 -0
  45. package/skills/express/references/estrutura.md +157 -0
  46. package/skills/express/references/middlewares.md +227 -0
  47. package/skills/express/references/rotas-erros.md +286 -0
  48. package/skills/express/references/testes-deploy.md +154 -0
  49. package/skills/express/scripts/checar.mjs +115 -0
  50. package/skills/express/scripts/nucleo.mjs +227 -0
  51. package/skills/fastapi/SKILL.md +132 -0
  52. package/skills/fastapi/references/banco.md +197 -0
  53. package/skills/fastapi/references/estrutura.md +325 -0
  54. package/skills/fastapi/references/integracoes.md +145 -0
  55. package/skills/fastapi/references/rotas-erros.md +140 -0
  56. package/skills/fastapi/references/testes-deploy.md +190 -0
  57. package/skills/fastapi/scripts/checar.mjs +108 -0
  58. package/skills/fastapi/scripts/nucleo.mjs +227 -0
  59. package/skills/hefesto/SKILL.md +119 -0
  60. package/skills/hefesto/references/conceitos.md +131 -0
  61. package/skills/hefesto/references/diagnostico.md +70 -0
  62. package/skills/hefesto/references/fluxo.md +122 -0
  63. package/skills/hefesto/references/preparar-app.md +105 -0
  64. package/skills/orfeu/SKILL.md +162 -0
  65. package/skills/orfeu/references/angular-api.md +201 -0
  66. package/skills/orfeu/references/angular-armadilhas.md +116 -0
  67. package/skills/orfeu/references/angular-recipes.md +474 -0
  68. package/skills/orfeu/references/angular.md +212 -0
  69. package/skills/orfeu/references/diferencas.md +56 -0
  70. package/skills/orfeu/references/node-api.md +354 -0
  71. package/skills/orfeu/references/node-armadilhas.md +158 -0
  72. package/skills/orfeu/references/node-recipes.md +541 -0
  73. package/skills/orfeu/references/node.md +204 -0
  74. package/skills/orfeu/references/python-api.md +346 -0
  75. package/skills/orfeu/references/python-recipes.md +479 -0
  76. package/skills/orfeu/references/python.md +240 -0
  77. package/skills/orfeu/scripts/checar.mjs +126 -0
  78. package/skills/orfeu/scripts/nucleo.mjs +227 -0
  79. package/skills/trismegisto/SKILL.md +194 -0
  80. package/skills/trismegisto/references/angular-api.md +2788 -0
  81. package/skills/trismegisto/references/angular-exports.md +4020 -0
  82. package/skills/trismegisto/references/angular-recipes.md +1883 -0
  83. package/skills/trismegisto/references/angular-types.md +492 -0
  84. package/skills/trismegisto/references/angular.md +390 -0
  85. package/skills/trismegisto/references/catalogo/icones.json +912 -0
  86. package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
  87. package/skills/trismegisto/references/catalogo/tokens.json +240 -0
  88. package/skills/trismegisto/references/spine-api.md +1530 -0
  89. package/skills/trismegisto/references/spine-recipes.md +581 -0
  90. package/skills/trismegisto/references/spine.md +343 -0
  91. package/skills/trismegisto/scripts/checar.mjs +216 -0
  92. package/skills/trismegisto/scripts/nucleo.mjs +227 -0
@@ -0,0 +1,1530 @@
1
+ # Catálogo de API — @trismegisto/spine
2
+
3
+ > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 1.0.0, a cada `npm run sync` do @acropole/skills.
4
+ > Gerado do código-fonte do `@trismegisto/spine`. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
+
6
+ Uma seção por ponto de entrada (o `import` exato). Dentro dela: componentes (seletor, inputs/outputs),
7
+ serviços (membros públicos), funções (assinatura), constantes/tokens e tipos (corpo quando curto).
8
+ Legenda das tabelas: `input` = `[prop]`; `model` = two-way `[(prop)]`; `output` = `(evento)`.
9
+ Componentes do layout (`spine-header`, `spine-sidebar`…) já vêm montados pelo `spine-layout`: estão aqui
10
+ para referência, não para o app pôr no template.
11
+
12
+ ## `@trismegisto/spine`
13
+
14
+ ### Serviços e classes
15
+
16
+ #### `ThemeService` · `providedIn: root`
17
+
18
+ Wrapper fino sobre `HermesThemeService` (que já persiste em `localStorage` e aplica `data-theme`/`--hm-*` via `HermesThemeDirective`): mantém o mesmo nome/API de injeção do spine antigo, e adiciona só o que o DS novo não cobre — sincronização entre ABAS do navegador via `BroadcastChannel` (o `ThemeService` antigo tinha isso; `HermesThemeService` é por-aba). Aplica os atributos diretamente no `<body>` em vez de exigir que cada app consumidor lembre de colocar `hermesTheme` no template — mesmo es…
19
+
20
+ - `get current: HermesThemeName`
21
+ - `get mode: HermesThemeMode` — Escolha do usuário: `light`, `dark` ou `system` (acompanha o sistema operacional).
22
+ - `setMode(mode: HermesThemeMode)`
23
+ - `setTheme(theme: HermesThemeName)`
24
+
25
+ #### `ThemePresetService` · `providedIn: root`
26
+
27
+ Wrapper fino sobre `HermesThemeService.family`/`setFamily`/`families` — substitui o `applyThemePreset`/`PRESETS` do addon `theme-builder` antigo (que já expunha só paletas FIXAS pré-definidas, nunca cor arbitrária digitada pelo usuário: o spine antigo usava só essa lista fixa, então trocar para `family` do DS novo é a mesma mecânica de UX — grid de paletas prontas —, só muda o catálogo de opções e como cada uma deriva claro/escuro internamente). Persistência entre abas já vem de `HermesThemeSer…
28
+
29
+ - `get current: HermesFamily`
30
+ - `get families: readonly HermesFamily[]`
31
+ - `setPreset(family: HermesFamily): void`
32
+
33
+ #### `DensityService` · `providedIn: root`
34
+
35
+ Wrapper fino sobre `HermesThemeService.density`/`setDensity` (já persistido em `localStorage` pelo DS novo) — mantém o nome/API do spine antigo e adiciona a sincronização entre abas via `BroadcastChannel` que `HermesThemeService` não tem (é por-aba). Ver `ThemeService` (mesmo padrão, mesmo motivo).
36
+
37
+ - `get current: DensitySetting`
38
+ - `setDensity(density: HermesDensity)`
39
+ - `toggleDensity()` — Só alterna entre comfortable e compact — mesmo comportamento do spine antigo (que chamava a densidade não-compacta de "regular"; o DS novo chama de "comfortable").
40
+
41
+ #### `SpinePreferencesService` · `providedIn: root`
42
+
43
+ Preferências do usuário que não são de tema (tema/família/densidade continuam no `HermesThemeService`; modo do menu lateral no `HermesSidebarService`): fuso horário, idioma e o interruptor dos atalhos de tecla única (WCAG 2.1.4) do `HermesShortcutService`.
44
+
45
+ - `readonly appLanguage` — Idioma com que o app subiu (`provideHermesI18n`) — vale quando a pessoa não escolheu nenhum.
46
+ - `readonly timeZone: signal(…)` — Fuso escolhido (IANA, ex.: "America/Sao_Paulo"). Vazio = o do navegador.
47
+ - `readonly browserTimeZone` — Fuso do navegador, para mostrar ao lado da opção "automático".
48
+ - `readonly effectiveTimeZone: computed(…)` — O fuso que vale de fato: o escolhido ou, sem escolha, o do navegador.
49
+ - `readonly language: signal(…)` — Idioma escolhido (BCP 47: `pt-BR`, `en`, `es`). Vazio = o padrão do app.
50
+ - `readonly characterKeys: signal(…)` — Atalhos de tecla única (`?`, `G H`) ligados — WCAG 2.1.4. Guardado por app (`'on'`/`'off'`); sem escolha salva, vale o padrão do `HermesShortcutService` (`provideHermesShortcuts`).
51
+ - `setCharacterKeys(enabled: boolean): void` — Liga/desliga os atalhos de tecla única na hora, guarda e avisa as outras abas.
52
+ - `setLanguage(value: string): void` — Troca o idioma da lib e do spine na hora, guarda e avisa as outras abas. Vazio = padrão do app.
53
+ - `setTimeZone(value: string): void`
54
+ - `supportedTimeZones(): string[]` — Todos os fusos IANA que o navegador conhece (vazio em navegador antigo).
55
+
56
+ #### `SpineQuickAccessService` · `providedIn: root`
57
+
58
+ Favoritos e páginas abertas por último. Um serviço só, e não cada componente com a sua cópia do `localStorage`: é o que faz o coração da trilha (`spine-page-bar`) e a tela inicial mostrarem a mesma coisa na hora, sem recarregar.
59
+
60
+ - `readonly favorites: Signal (somente leitura)`
61
+ - `readonly recents: Signal (somente leitura)`
62
+ - `isFavorite(id: string | null | undefined): boolean`
63
+ - `toggleFavorite(item: QuickAccessItem): void`
64
+ - `recordVisit(item: QuickAccessItem): void` — Registra a visita: o mais recente vai pro topo e a lista não repete página.
65
+ - `forgetRecent(id: string): void`
66
+
67
+ ### Funções
68
+
69
+ - `function routerIdOf(route: Route | null | undefined): string | null` — `router_id` da tela (nó 'page'), aceitando o argos antigo (que só mandava `route_id`, mesmo valor).
70
+ - `function provideUi(config?: SpineConfig): EnvironmentProviders` — Registra o catálogo de ícones inteiro — o spine (header/sidebar/navegação/modal/onboarding) usa ícones de várias origens (shield, pencil, trash, floppy, chevrons...) que não vêm embutidos de graça (os componentes do hermes só registram os ícones que eles próp…
71
+ - `function resolveSpineLogo(logo: SpineLogoConfig | false | null | undefined): SpineLogoSources | null` — Normaliza `SpineConfig.logo`: omitido → convenção; `false`/vazio → sem imagem (`null`).
72
+ - `function applySpineFavicon(doc: Document, href: string): HTMLLinkElement | null` — Aponta o favicon do documento para `href`: atualiza o primeiro `<link rel="icon">` (ou `shortcut icon`) e remove os outros (senão o navegador pode continuar escolhendo um deles); sem nenhum, cria um no `<head>`. O `type` acompanha a extensão (some quando ela…
73
+ - `function applyRuntimeEnvironment(environment: RuntimeEnvironmentShape): RuntimeEnvironmentInfo` — Ajusta o `environment` ao lugar onde o app está rodando — chamar no `main.ts`, ANTES do `bootstrapApplication`. Antes cada app tinha a sua versão; agora a regra é uma só: - **Sempre:** `redirectUrl`/`postLogoutRedirectUri` = or…
74
+ - `function provideSpineNews(items: readonly SpineNewsItem[]): EnvironmentProviders` — Registra as novidades do app (no `app.config.ts`, junto do `provideUi`). Ficam no código, no mesmo commit da funcionalidade que anunciam. A ordem da lista é a ordem dos slides.
75
+ - `function currentSpineMessages(): SpineMessages` — Textos do spine no idioma ativo para quem não tem injeção (funções puras como o `unwrap` do `@trismegisto/spine/graphql`, chamado em qualquer lugar do app). É o mesmo catálogo vivo do `SPINE_MESSAGES` — segue `setLocale` — assim que o shell o injetou; antes d…
76
+ - `function provideSpineMessages(config: SpineI18nConfig): Provider` — Sobrescreve textos do spine e/ou acrescenta idiomas. O idioma em si vem de `provideHermesI18n`.
77
+
78
+ ### Constantes e tokens
79
+
80
+ - `HERMES_DS_IMPORTS`: `readonly Type<unknown>[]` — Ponto único de import dos componentes standalone do `@trismegisto/angular` usados nos templates do spine. O DS novo é standalone-only (sem agregador), então este array cumpre o mesmo papel prático: um `@Component({ imports: [...HERMES_DS_IMPORTS] })` em vez d…
81
+ - `SPINE_CONFIG`: `InjectionToken<SpineConfig>`
82
+ - `SPINE_DEFAULT_LOGO`: `'assets/images/logo.svg'` — Convenção quando o app não configura `logo`: `src/assets/images/logo.svg` servido em `assets/images/`.
83
+ - `APP_PACKAGE_INFO`: `InjectionToken<PackageInfo>`
84
+ - `SPINE_ADMIN_API`: `InjectionToken<string>` — Base da API do argos-admin-server (ex.: `https://exemplo.com.br/argos/admin/api`) — recursos do próprio usuário (`/me/*`, hoje os tokens de aplicação) que o painel de configurações usa. Quem chama `provideAutoService({ adminApi })` já fornece este token (é a…
85
+ - `SPINE_NEWS`: `InjectionToken<readonly (readonly SpineNewsItem[])[]>` — Multi: cada chamada de `provideSpineNews` contribui com uma lista.
86
+ - `SPINE_MESSAGES_PT_BR`: `SpineMessages`
87
+ - `SPINE_MESSAGES_EN`: `SpineMessages`
88
+ - `SPINE_MESSAGES_ES`: `SpineMessages`
89
+ - `SPINE_I18N_CONFIG`: `InjectionToken<SpineI18nConfig>`
90
+ - `SPINE_MESSAGES`: `InjectionToken<SpineMessages>` — Textos do spine no idioma ativo da lib (`HermesI18nService.locale`): uma troca de idioma com `setLocale` atualiza a lib e o spine juntos, sem recarregar. Leitura igual à do `HERMES_MESSAGES` (`inject(SPINE_MESSAGES).header.settings`), viva também em template.
91
+
92
+ ### Tipos
93
+
94
+ #### `Route` (interface)
95
+
96
+ ```ts
97
+ interface Route {
98
+ route_display_name?: string | null;
99
+ route_icon?: string | null;
100
+ /**
101
+ * @deprecated use `router_id` (ou `routerIdOf`). Nome histórico: no nó 'page' o argos-auth-server
102
+ * sempre mandou aqui o `router_id` (nunca o `web.routes.route_id`, que é `routed_id`). Continua
103
+ * vindo, com o mesmo valor, para spines/Orfeu antigos.
104
+ */
105
+ route_id?: string | null;
106
+ route_name?: string | null;
107
+ route_order?: number | null;
108
+ route_path?: string | null;
109
+ route_redirect?: string | null;
110
+ route_redirect_to?: string | null;
111
+ route_type?: string | null;
112
+ /** A ROTA do nó (`web.routes.route_id`): nome/ícone/path. Reaproveitável em vários routers. */
113
+ routed_id: string;
114
+ routes?: Route[] | null;
115
+ /**
116
+ * Identidade da TELA: o router do client (`web.router.router_id`, a posição da tela na
117
+ * navegação). Só no nó 'page' -- nó de grupo (navigation/menu/...) é compartilhado por vários
118
+ * routers e não tem um próprio. É por ele que o spine acha o componente (`COMPONENT_ROUTES`),
119
+ * o documento e a descrição. Argos anterior a 2026-10-05 não manda: use `routerIdOf`, que cai
120
+ * no `route_id` (mesmo valor).
121
+ */
122
+ router_id?: string | null;
123
+ /** Texto curto da tela (`web.router.description`), exibido na barra da página abaixo do título. */
124
+ description?: string | null;
125
+ // Presente só no nó 'page' -- proveniência de template (web.router.source_template_router_id),
126
+ // estável entre todos os clients vinculados ao mesmo template, ao contrário de router_id (que é
127
+ // o router CLONADO, específico de cada client). Usado como fallback de resolução de componente
128
+ // quando nenhum app registrou esse router_id diretamente, ver ComponentDistributorService.
129
+ source_template_router_id?: string | null;
130
+ }
131
+ ```
132
+
133
+ #### `DensitySetting` (interface)
134
+
135
+ ```ts
136
+ interface DensitySetting {
137
+ name: HermesDensity;
138
+ }
139
+ ```
140
+
141
+ #### `SpineConfig` (interface)
142
+
143
+ ```ts
144
+ interface SpineConfig {
145
+ clientId: string;
146
+ /**
147
+ * Famílias de cor próprias do app (opcional): acrescentar (`families`), trocar uma existente
148
+ * (`replace: { poseidon: minhaFamilia }` — posição e preferência salva passam para a nova) e a
149
+ * família inicial (`defaultFamily`). Ver `extendThemeConfig` do `@trismegisto/primitives`; a família
150
+ * se monta e exporta no `hm-theme-builder`.
151
+ */
152
+ theme?: HermesThemeExtension;
153
+ /** Nome do app exibido ao lado do logo no header (ex.: "Meu App"). Padrão: "Hermes". */
154
+ appName?: string;
155
+ /**
156
+ * Logo do header, servido pelo próprio app (caminho relativo ao `<base href>`, ex.: arquivo em
157
+ * `src/assets/images/`). Formas:
158
+ * - omitido: convenção `assets/images/logo.svg` (`SPINE_DEFAULT_LOGO`);
159
+ * - `'assets/images/logo.png'`: um arquivo só, para os dois temas;
160
+ * - `{ light, dark?, alt? }`: `dark` é usado no tema escuro (do `ThemeService`); `alt` substitui o texto
161
+ * alternativo padrão;
162
+ * - `false`: sem imagem (só o nome, sem nenhuma requisição).
163
+ * Se a imagem não carregar (404/erro), o header esconde a imagem e mostra só o nome. Um componente de
164
+ * marca em `SPINE_BRAND` (`@trismegisto/spine/layout`) tem prioridade sobre a imagem.
165
+ */
166
+ logo?: SpineLogoConfig | false;
167
+ /** Mostra o `appName` ao lado do logo. Padrão: `true`. Com `false` o nome só aparece se não houver logo
168
+ * visível (sem imagem, ou imagem que falhou) — o link da marca nunca fica sem texto. */
169
+ showAppName?: boolean;
170
+ /** Favicon do app (ex.: `'assets/favicon.ico'`). Se definido, o `provideUi` atualiza o `<link rel="icon">`
171
+ * do `index.html` (ou cria um) no bootstrap; sem isto o spine não mexe no favicon. */
172
+ favicon?: string;
173
+ /** Exibe a aba "Especificação técnica" da documentação das telas (`RouteDocument.loadTechnical`).
174
+ * Padrão: `isDevMode()`. Apps com build de produção em homologação passam
175
+ * `!environment.production` (ou equivalente) para mostrá-la fora de produção. */
176
+ technicalDocs?: boolean;
177
+ }
178
+ ```
179
+
180
+ #### `SpineLogoConfig` (type)
181
+
182
+ Logo do header: um caminho (os dois temas) ou as variantes clara/escura + texto alternativo.
183
+
184
+ ```ts
185
+ type SpineLogoConfig = string | { light: string; dark?: string; alt?: string };
186
+ ```
187
+
188
+ #### `SpineLogoSources` (interface)
189
+
190
+ Logo já normalizado.
191
+
192
+ ```ts
193
+ interface SpineLogoSources {
194
+ light: string;
195
+ dark: string | null;
196
+ /** Texto alternativo explícito; `null` usa o padrão (o nome do app). */
197
+ alt: string | null;
198
+ }
199
+ ```
200
+
201
+ #### `PackageInfo` (interface)
202
+
203
+ Dados do `package.json` do app (nome, versão, dependências...), passados em `provideShell({ packageInfo })`. Mora no pacote raiz (e não em `@trismegisto/spine/shell`, onde nasceu) porque o painel de configurações do `@trismegisto/spine/layout` também lê — e o shell importa o layout, então o layout importar o shell fecharia um ciclo. O shell reexporta o MESMO token (mesma instância), então quem im…
204
+
205
+ ```ts
206
+ interface PackageInfo {
207
+ name?: string;
208
+ version?: string;
209
+ description?: string;
210
+ license?: string;
211
+ buildDate?: string;
212
+ environment?: string;
213
+ repository?: { url?: string };
214
+ developer?: { name?: string; homepage?: string; email?: string };
215
+ docs?: string;
216
+ issues?: string;
217
+ dependencies?: Record<string, string>;
218
+ [key: string]: any;
219
+ }
220
+ ```
221
+
222
+ #### `QuickAccessItem` (interface)
223
+
224
+ Uma página guardada no navegador (favorito ou recente). Cópia, e não referência à árvore: a árvore pode mudar, e uma página que saiu do crachá atual continua listada até que se navegue pra ela -- melhor mostrar e receber "sem permissão" do que o favorito sumir sem explicação.
225
+
226
+ ```ts
227
+ interface QuickAccessItem {
228
+ /** Identidade do item: o endereço da página (`route_redirect`). */
229
+ readonly id: string;
230
+ readonly icon: string;
231
+ readonly displayName: string;
232
+ readonly redirect: string;
233
+ /** Rótulos dos ancestrais, do topo pra baixo ("Rede › DNS"). Vazio = página de nível 1. */
234
+ readonly trail?: readonly string[];
235
+ }
236
+ ```
237
+
238
+ #### `RuntimeEnvironmentShape` (interface)
239
+
240
+ O mínimo do `environment` de um app que dá pra derivar em tempo de execução. Estrutural de propósito (não importa o `Environment` de nenhum app): serve pra todos.
241
+
242
+ ```ts
243
+ interface RuntimeEnvironmentShape {
244
+ authorizationServer: { authority?: string; redirectUrl?: string; postLogoutRedirectUri?: string };
245
+ graphql?: Record<string, { http: string; ws?: string }>;
246
+ }
247
+ ```
248
+
249
+ #### `RuntimeEnvironmentInfo` (interface)
250
+
251
+ ```ts
252
+ interface RuntimeEnvironmentInfo {
253
+ /** `window.location.origin`. */
254
+ readonly origin: string;
255
+ /** Prefixo do app (base href sem a barra final), ex.: `/meu-app`. Vazio na raiz. */
256
+ readonly basePath: string;
257
+ /** Sem porta na URL: o app está atrás do proxy reverso, não na porta direta do container. */
258
+ readonly behindProxy: boolean;
259
+ /** URL ainda sem valor real (vazia ou `CHANGE_ME`) — a única que pode ser derivada. */
260
+ readonly unset: (url: string | undefined) => boolean;
261
+ }
262
+ ```
263
+
264
+ #### `SpineNewsIllustration` (interface)
265
+
266
+ Ilustração gerada pelo spine, nas cores do tema em vigor: o ícone da novidade no centro e, opcionalmente, selos (ícone + rótulo) orbitando em volta. Ícones são nomes do @trismegisto/icons.
267
+
268
+ ```ts
269
+ interface SpineNewsIllustration {
270
+ readonly icon: string;
271
+ readonly satellites?: readonly { readonly icon: string; readonly label: string }[];
272
+ }
273
+ ```
274
+
275
+ #### `SpineNewsSlide` (interface)
276
+
277
+ Um slide do painel de novidades.
278
+
279
+ ```ts
280
+ interface SpineNewsSlide {
281
+ readonly title: string;
282
+ readonly text: string;
283
+ /** Ilustração desenhada pelo spine (recomendado — acompanha tema claro/escuro e família). */
284
+ readonly illustration?: SpineNewsIllustration;
285
+ /** Imagem própria (caminho em `assets/` do app); vence a `illustration`. Sem nenhuma das duas, o
286
+ * slide é só texto. */
287
+ readonly image?: string;
288
+ /** Descrição da imagem pra quem não a vê. Vazia marca a imagem como decorativa. */
289
+ readonly alt?: string;
290
+ }
291
+ ```
292
+
293
+ #### `SpineNewsItem` (interface)
294
+
295
+ Uma novidade do app: aparece sozinha uma vez por navegador, depois do tour de boas-vindas, e fica marcada como vista ao ser exibida.
296
+
297
+ ```ts
298
+ interface SpineNewsItem {
299
+ /** Chave estável. Trocar o id faz a novidade aparecer de novo para todo mundo. */
300
+ readonly id: string;
301
+ readonly slides: readonly SpineNewsSlide[];
302
+ /** Data (AAAA-MM-DD) a partir da qual a novidade deixa de ser oferecida. Opcional. */
303
+ readonly until?: string;
304
+ }
305
+ ```
306
+
307
+ #### `SpineMessages` (interface)
308
+
309
+ Textos do próprio spine (cabeçalho, navegação, configurações, tour, telas do auto-serviço…), no mesmo formato do `HermesMessages` da lib: seção → chave, parâmetros nomeados (`{name}`) e plural por `PluralMessage`. Alguns textos levam marcação simples (`<b>`, `<strong>`, `<code>`) e são exibidos com `[innerHTML]` — estão indicados no comentário.
310
+
311
+ _Declaração longa — veja `@trismegisto/spine` em `node_modules` (arquivo de tipos do ponto de entrada)._
312
+
313
+ #### `SpineMessagesOverride` (type)
314
+
315
+ ```ts
316
+ type SpineMessagesOverride = CatalogOverride<SpineMessages>;
317
+ ```
318
+
319
+ #### `SpineI18nConfig` (interface)
320
+
321
+ ```ts
322
+ interface SpineI18nConfig {
323
+ /** Catálogos extras ou substitutos, por idioma (mesmas chaves do `SpineMessages`). */
324
+ readonly catalogs?: Readonly<Record<string, SpineMessages>>;
325
+ /** Textos avulsos sobrescritos por cima do catálogo ativo, em qualquer idioma. */
326
+ readonly override?: SpineMessagesOverride;
327
+ }
328
+ ```
329
+
330
+ ## `@trismegisto/spine/audit`
331
+
332
+ @trismegisto/spine/audit — a tela de Auditoria (leitura de `audit.events` do argos admin-server), a mesma para o painel central (`scope="admin"`) e para o auto-serviço (`scope="client"` + `clientId`).
333
+
334
+ ### Componentes e diretivas
335
+
336
+ #### `spine-audit` — `SpineAuditComponent`
337
+
338
+ A tela de Auditoria — a MESMA no auto-serviço e no painel central do argos admin. Só muda o escopo: - `scope="client"` + `clientId`: `{adminApi}/auto-service/:clientId/audit/*`, apps do projeto do client (recorte feito no servidor); - `scope="admin"`: `{adminApi}/admin/audit/*`, todos os apps (guard `admin:audit:*` no servidor). `adminApi` vem do input ou do `SPINE_ADMIN_API` (que o `provideAutoService` já fornece).
339
+
340
+ | Nome | Tipo | Tipo TS | Padrão | Descrição |
341
+ |---|---|---|---|---|
342
+ | `scope` | input (obrigatório) | `SpineAuditScope` | | `admin` = painel central (todos os apps); `client` = apps do projeto do `clientId`. |
343
+ | `clientId` | input | `string \| null` | `null` | Obrigatório com `scope="client"`. |
344
+ | `adminApi` | input | `string \| null` | `null` | Base do argos admin-server; sem ele, vale o `SPINE_ADMIN_API`. |
345
+
346
+ #### `spine-audit-top-card` — `SpineAuditTopCardComponent`
347
+
348
+ Card de ranking da Auditoria ("Operações", "Usuários", "Por aplicação") com paginação compacta no servidor: `x–y de N` + anterior/próxima. Durante a troca de página as linhas atuais continuam (esmaecidas, `aria-busy`), sem esqueleto. A barra é proporcional ao `max` (o 1º item da 1ª página), então as páginas seguintes não "enchem" de novo. Clicar num item emite `picked` (vira filtro).
349
+
350
+ | Nome | Tipo | Tipo TS | Padrão | Descrição |
351
+ |---|---|---|---|---|
352
+ | `heading` | input (obrigatório) | `string` | | |
353
+ | `rows` | input (obrigatório) | `readonly AuditTopRow[]` | | |
354
+ | `total` | input | `number` | `0` | Quantos itens o ranking tem no total (todas as páginas). |
355
+ | `offset` | input | `number` | `0` | |
356
+ | `pageSize` | input | `number` | `5` | |
357
+ | `max` | input | `number` | `0` | Referência da barra (o maior total do ranking); 0 = o maior da página. |
358
+ | `loading` | input | `boolean` | `false` | |
359
+ | `failed` | input | `boolean` | `false` | |
360
+ | `picked` | output | `AuditTopRow` | | |
361
+ | `offsetChange` | output | `number` | | Novo `offset` pedido (anterior/próxima). |
362
+
363
+ ### Serviços e classes
364
+
365
+ #### `SpineAuditService` · `providedIn: root`
366
+
367
+ HTTP da auditoria (só leitura), igual nos dois escopos: cada método recebe a `base` já resolvida por `auditApiBase` (`{adminApi}/admin/audit` ou `{adminApi}/auto-service/:clientId/audit`). O recorte do escopo `client` é do servidor — nada aqui decide o que a pessoa pode ver.
368
+
369
+ - `events(base: string, query: AuditQuery, page: { limit?: number; cursor?: string | null } = {}): Promise<AuditPage>`
370
+ - `actions(base: string, query: AuditQuery, page: { limit?: number; cursor?: string | null } = {}): Promise<AuditActionPage>` — Uma linha por AÇÃO (raiz do trace + agregados dos spans), mesmos filtros/cursor de `events`.
371
+ - `event(base: string, eventId: string, occurredAt: string): Promise<AuditEventDetail>`
372
+ - `trace(base: string, traceId: string, occurredAt?: string | null): Promise<AuditTrace>` — `occurredAt` (opcional) = o do evento de origem: o servidor limita a busca da cadeia a ±1 dia dele.
373
+ - `stats(base: string, query: AuditQuery, opts: { tops?: boolean } = {}): Promise<AuditStats>` — Resumo (KPIs + linha do tempo). `tops: false` pula os rankings — a tela os pagina por `tops()`.
374
+ - `tops(base: string, kind: AuditTopKind, query: AuditQuery, page: { offset: number; limit: number }): Promise<AuditTopPage>` — Um ranking paginado (`apps` \| `operations` \| `users`) com os mesmos filtros/janela do resumo.
375
+
376
+ #### `AuditCursorPager`
377
+
378
+ Paginação numerada ("página N de M") sobre a lista por cursor (keyset) do servidor, que não tem OFFSET. Guarda o cursor de cada posição já vista (posição 0 = sem cursor); para abrir uma página nunca vista, anda a partir da posição conhecida mais próxima em saltos de até 200 (o cursor só depende do último evento lido, não do `limit`). Vale para UMA consulta (`from`/`to` + filtros fixos): consulta nova = pager novo.
379
+
380
+ - `get end: number | null` — Total exato, conhecido depois de alguma página chegar ao fim da lista.
381
+ - `page(offset: number, size: number, fetch: AuditPageFetcher, retry = true): Promise<AuditPagerResult>`
382
+
383
+ ### Funções
384
+
385
+ - `function auditApiBase(adminApi: string | null | undefined, scope: SpineAuditScope, clientId?: string | null): string | null` — Base dos endpoints da auditoria para o escopo (sem barra no fim). `null` quando falta o necessário (sem `adminApi`, ou escopo `client` sem `clientId`).
386
+ - `function auditAppsUrl(adminApi: string | null | undefined, scope: SpineAuditScope, clientId?: string | null): string | null` — Lista de apps para o filtro: todos (`admin`, `GET /admin/apps`) ou os do projeto do client.
387
+ - `function auditParams(query: AuditQuery, page: { limit?: number; cursor?: string | null; offset?: number } = {}): HttpParams` — Monta a query string: vazio/`null` some, lista repete a chave (`app_id=a&app_id=b`).
388
+ - `function buildAuditQuery(period: AuditPeriod, filters: AuditFilterInput, now: Date): BuiltAuditQuery` — Período + filtros da tela → consulta do contrato. As datas da faixa (dia local inteiro) vencem a escolha rápida; o fim nunca passa de `now`. A janela vira `from`/`to` absolutos, então as páginas seguintes (cursor) e o resumo enxergam exatamente o mesmo interv…
389
+ - `function parseAuditDate(iso: string | null | undefined): Date | null` — Lê as datas do servidor, que vêm em ISO UTC com MICROssegundos (`2026-10-05T13:18:40.564281Z`): o formato de data do ECMAScript só garante 3 casas, então a fração é cortada em milissegundos antes.
390
+ - `function auditPagerTotal(statsTotal: number | null | undefined, end: number | null, loaded: AuditPagerResult | null): number` — Total do rodapé: o exato quando a lista já chegou ao fim; senão o do resumo (`stats.total`, mesma consulta), nunca menor do que o que já se sabe existir (página atual + "tem mais").
391
+ - `function worstOutcome(outcomes: readonly (string | null | undefined)[]): AuditOutcome` — Pior resultado (denied > failure > success) — o `outcome` de uma ação.
392
+ - `function buildSpanTimeline(items: readonly AuditEvent[]): AuditSpanTimeline` — Spans de um trace → linha do tempo: ordem em árvore (pai antes dos filhos, irmãos por início), com profundidade pela cadeia parent_span_id → span_id. Span cujo pai não está na lista (de fora do escopo, fora da janela) vira raiz. Fim do span = início + duratio…
393
+ - `function auditErrorCode(err: unknown): { status: number; code: string; detail: string }` — Código de erro do envelope do admin-server (`{ error, detail }`), quando houver.
394
+
395
+ ### Constantes e tokens
396
+
397
+ - `AUDIT_METHODS`: `readonly AuditMethod[]`
398
+ - `AUDIT_OUTCOMES`: `readonly AuditOutcome[]`
399
+ - `AUDIT_UNITS`: `readonly AuditUnit[]`
400
+ - `AUDIT_TOP_KINDS`: `readonly AuditTopKind[]`
401
+ - `AUDIT_TOP_PAGE_SIZE`: `5` — Itens por página dos cards de ranking (o servidor aceita até 50).
402
+ - `AUDIT_PERIOD_MS`: `Readonly<Record<AuditPeriod, number>>`
403
+ - `AUDIT_MAX_WINDOW_MS` — Janela máxima aceita pelo servidor (acima: 400 `range_too_large`).
404
+ - `AUDIT_MAX_PAGE_SIZE`: `200` — Maior `limit` aceito por `GET .../audit/events`.
405
+ - `AUDIT_PAGE_SIZE`: `10` — Eventos por página da tabela, de saída (o servidor aceita até 200 — `AUDIT_MAX_PAGE_SIZE`).
406
+ - `AUDIT_PAGE_SIZES`: `readonly number[]` — Opções do seletor de eventos por página (todas dentro do `limit` máximo do servidor).
407
+ - `AUDIT_AUTO_REFRESH_MS`: `30_000` — Intervalo da atualização automática (opcional, desligada por padrão).
408
+
409
+ ### Tipos
410
+
411
+ #### `AuditOutcome` (type)
412
+
413
+ ```ts
414
+ type AuditOutcome = 'success' | 'failure' | 'denied';
415
+ ```
416
+
417
+ #### `AuditMethod` (type)
418
+
419
+ ```ts
420
+ type AuditMethod = 'read' | 'write' | 'delete' | 'stream';
421
+ ```
422
+
423
+ #### `AuditLevel` (type)
424
+
425
+ ```ts
426
+ type AuditLevel = 'public' | 'private' | 'protected' | 'optional';
427
+ ```
428
+
429
+ #### `AuditPermissionResult` (type)
430
+
431
+ ```ts
432
+ type AuditPermissionResult = 'allowed' | 'forbidden' | 'unauthorized' | 'public';
433
+ ```
434
+
435
+ #### `AuditActorType` (type)
436
+
437
+ ```ts
438
+ type AuditActorType = 'user' | 'app_token' | 'api_token' | 'public' | 'unauthenticated';
439
+ ```
440
+
441
+ #### `AuditEvent` (interface)
442
+
443
+ Um evento como vem na lista (`GET .../audit/events`). Datas em ISO-8601 UTC.
444
+
445
+ ```ts
446
+ interface AuditEvent {
447
+ event_id: string;
448
+ occurred_at: string;
449
+ duration_ms: number | null;
450
+ trace_id: string | null;
451
+ span_id: string | null;
452
+ parent_span_id: string | null;
453
+ /** `true` = a ação de entrada (feita pela pessoa); `false` = chamada entre apps dentro da cadeia. */
454
+ entry: boolean;
455
+ realm_id: string | null;
456
+ actor_type: AuditActorType | string | null;
457
+ user_id: string | null;
458
+ user_name: string | null;
459
+ token_id: string | null;
460
+ client_ip: string | null;
461
+ app_id: string | null;
462
+ app_name: string | null;
463
+ client_id: string | null;
464
+ route_id: string | null;
465
+ route_name: string | null;
466
+ operation_id: string | null;
467
+ operation_identifier: string | null;
468
+ operation_method: AuditMethod | string | null;
469
+ operation_level: AuditLevel | string | null;
470
+ operation_label: string | null;
471
+ target_type: string | null;
472
+ target_id: string | null;
473
+ permission_result: AuditPermissionResult | string | null;
474
+ outcome: AuditOutcome;
475
+ status: number | null;
476
+ message: string | null;
477
+ }
478
+ ```
479
+
480
+ #### `AuditUnit` (type)
481
+
482
+ Unidade da leitura: `actions` (uma por trace, padrão) ou `events` (cada registro).
483
+
484
+ ```ts
485
+ type AuditUnit = 'actions' | 'events';
486
+ ```
487
+
488
+ #### `AuditAction` (interface)
489
+
490
+ Uma AÇÃO (`GET .../audit/actions`): os campos do evento raiz (entry=true) do trace, com os agregados dos spans do mesmo trace dentro da janela. `outcome` = o pior dos spans (denied > failure > success); `root_outcome` = o do próprio raiz. `orphan` = trace sem raiz na janela (a linha é o 1º span interno). No escopo `client`, spans de apps de fora não entram nos agregados, só em `hidden_count`.
491
+
492
+ ```ts
493
+ interface AuditAction extends AuditEvent {
494
+ root_outcome?: AuditOutcome;
495
+ orphan?: boolean;
496
+ span_count: number;
497
+ hidden_count?: number;
498
+ apps?: string[];
499
+ failures?: number;
500
+ denied?: number;
501
+ }
502
+ ```
503
+
504
+ #### `AuditActionPage` (interface)
505
+
506
+ ```ts
507
+ interface AuditActionPage {
508
+ items: AuditAction[];
509
+ next_cursor: string | null;
510
+ }
511
+ ```
512
+
513
+ #### `AuditEventDetail` (interface)
514
+
515
+ O evento completo (`GET .../audit/events/:eventId?occurred_at=`).
516
+
517
+ ```ts
518
+ interface AuditEventDetail extends AuditEvent {
519
+ details?: unknown;
520
+ received_at?: string | null;
521
+ service_instance?: string | null;
522
+ sdk?: string | null;
523
+ }
524
+ ```
525
+
526
+ #### `AuditPage` (interface)
527
+
528
+ ```ts
529
+ interface AuditPage {
530
+ items: AuditEvent[];
531
+ next_cursor: string | null;
532
+ }
533
+ ```
534
+
535
+ #### `AuditTrace` (interface)
536
+
537
+ A cadeia (trace) recortada ao escopo do projeto; `hidden_count` = eventos de apps de fora.
538
+
539
+ ```ts
540
+ interface AuditTrace {
541
+ items: AuditEvent[];
542
+ hidden_count?: number;
543
+ }
544
+ ```
545
+
546
+ #### `AuditStats` (interface)
547
+
548
+ ```ts
549
+ interface AuditStats {
550
+ total: number;
551
+ /** Com `tops=false` na consulta, `by_app`/`top_operations`/`top_users` vêm vazios (use `tops/:kind`). */
552
+ by_outcome: { success: number; failure: number; denied: number };
553
+ by_app: { app_id: string; app_name: string | null; total: number; failures: number; denied: number }[];
554
+ top_operations: { operation_identifier: string | null; operation_label: string | null; app_name: string | null; total: number; failures: number }[];
555
+ top_users: { user_id: string | null; user_name: string | null; total: number }[];
556
+ timeline: { bucket: string; total: number; failures: number; denied: number }[];
557
+ }
558
+ ```
559
+
560
+ #### `AuditTopKind` (type)
561
+
562
+ Os rankings paginados de `GET .../audit/tops/:kind`.
563
+
564
+ ```ts
565
+ type AuditTopKind = 'apps' | 'operations' | 'users';
566
+ ```
567
+
568
+ #### `AuditTopItem` (interface)
569
+
570
+ Um item de ranking: os campos de identificação variam com o `kind`; contagens sempre presentes.
571
+
572
+ ```ts
573
+ interface AuditTopItem {
574
+ total: number;
575
+ failures: number;
576
+ denied: number;
577
+ /** `apps` e `operations`. */
578
+ app_id?: string | null;
579
+ app_name?: string | null;
580
+ /** `operations`. */
581
+ operation_identifier?: string | null;
582
+ operation_label?: string | null;
583
+ /** `users`. */
584
+ user_id?: string | null;
585
+ user_name?: string | null;
586
+ }
587
+ ```
588
+
589
+ #### `AuditTopPage` (interface)
590
+
591
+ Uma página de ranking; `total` = quantos itens (grupos) existem na consulta.
592
+
593
+ ```ts
594
+ interface AuditTopPage {
595
+ items: AuditTopItem[];
596
+ total: number;
597
+ }
598
+ ```
599
+
600
+ #### `SpineAuditScope` (type)
601
+
602
+ De onde a tela lê: o painel central (`admin`) ou o projeto de um client (`client`).
603
+
604
+ ```ts
605
+ type SpineAuditScope = 'admin' | 'client';
606
+ ```
607
+
608
+ #### `AuditQuery` (interface)
609
+
610
+ Filtros da query string (todos opcionais). `app_id` repete o parâmetro.
611
+
612
+ ```ts
613
+ interface AuditQuery {
614
+ from?: string;
615
+ to?: string;
616
+ app_id?: readonly string[];
617
+ user_id?: string;
618
+ user?: string;
619
+ operation?: string;
620
+ method?: AuditMethod | string;
621
+ level?: AuditLevel | string;
622
+ outcome?: AuditOutcome | string;
623
+ permission_result?: AuditPermissionResult | string;
624
+ actor_type?: AuditActorType | string;
625
+ entry?: boolean;
626
+ trace_id?: string;
627
+ route_id?: string;
628
+ target_type?: string;
629
+ target_id?: string;
630
+ status?: number | string;
631
+ /** Agregações (stats/tops/daily): padrão do servidor = `actions`. Ignorado nas listas. */
632
+ unit?: AuditUnit;
633
+ }
634
+ ```
635
+
636
+ #### `AuditPeriod` (type)
637
+
638
+ Escolhas rápidas de período da tela.
639
+
640
+ ```ts
641
+ type AuditPeriod = '1h' | '6h' | '24h' | '7d' | '30d';
642
+ ```
643
+
644
+ #### `AuditFilterInput` (interface)
645
+
646
+ Valor da faixa de filtros da tela (`hm-filter-bar`), por chave. `dates` é `{ start, end }` em AAAA-MM-DD (dia local); `app` é lista (multisseleção; aceita um id só); `entry` é booleano; o resto é texto.
647
+
648
+ ```ts
649
+ interface AuditFilterInput {
650
+ dates?: { start: string | null; end: string | null } | null;
651
+ app?: string | readonly string[] | null;
652
+ user?: string | null;
653
+ user_id?: string | null;
654
+ operation?: string | null;
655
+ method?: string | null;
656
+ level?: string | null;
657
+ outcome?: string | null;
658
+ permission_result?: string | null;
659
+ actor_type?: string | null;
660
+ status?: string | number | null;
661
+ trace_id?: string | null;
662
+ entry?: boolean | null;
663
+ }
664
+ ```
665
+
666
+ #### `BuiltAuditQuery` (type)
667
+
668
+ ```ts
669
+ type BuiltAuditQuery = { ok: true; query: AuditQuery } | { ok: false; reason: 'range_too_large' };
670
+ ```
671
+
672
+ #### `AuditPageFetcher` (type)
673
+
674
+ Busca uma fatia da lista (`cursor` `null` = do começo).
675
+
676
+ ```ts
677
+ type AuditPageFetcher = (cursor: string | null, limit: number) => Promise<AuditPage>;
678
+ ```
679
+
680
+ #### `AuditPagerResult` (interface)
681
+
682
+ Uma página resolvida por `AuditCursorPager.page`. `offset` pode ser menor que o pedido (pedido além do fim).
683
+
684
+ ```ts
685
+ interface AuditPagerResult {
686
+ items: AuditEvent[];
687
+ offset: number;
688
+ hasMore: boolean;
689
+ }
690
+ ```
691
+
692
+ #### `AuditSpanRow` (interface)
693
+
694
+ Um span na linha do tempo de uma ação (`buildSpanTimeline`).
695
+
696
+ ```ts
697
+ interface AuditSpanRow {
698
+ event: AuditEvent;
699
+ /** Profundidade na hierarquia (parent_span_id → span_id); 0 = raiz(es). */
700
+ depth: number;
701
+ /** Início relativo ao 1º span, em ms. */
702
+ offsetMs: number;
703
+ /** Posição/largura da barra, em % da duração total (largura mínima para continuar visível). */
704
+ left: number;
705
+ width: number;
706
+ }
707
+ ```
708
+
709
+ #### `AuditSpanTimeline` (interface)
710
+
711
+ ```ts
712
+ interface AuditSpanTimeline {
713
+ rows: AuditSpanRow[];
714
+ /** Do início do 1º span ao fim do último, em ms. */
715
+ totalMs: number;
716
+ }
717
+ ```
718
+
719
+ #### `AuditTopRow` (interface)
720
+
721
+ Uma linha de ranking já pronta para mostrar (o card não sabe de que tipo é).
722
+
723
+ ```ts
724
+ interface AuditTopRow {
725
+ key: string;
726
+ name: string;
727
+ /** Texto secundário ao lado do nome (ex.: o app de uma operação). */
728
+ suffix?: string | null;
729
+ /** Dica (tooltip) do item — ex.: a descrição da operação. */
730
+ hint?: string | null;
731
+ total: number;
732
+ failures: number;
733
+ denied: number;
734
+ /** Sem como virar filtro (ex.: usuário sem nome nem id). */
735
+ disabled?: boolean;
736
+ }
737
+ ```
738
+
739
+ ## `@trismegisto/spine/auto-service`
740
+
741
+ ### Serviços e classes
742
+
743
+ #### `AutoServiceService` · `providedIn: root`
744
+
745
+ - `getMyClients()`
746
+ - `getWebRoutes(clientId: string)`
747
+ - `createWebRoute(clientId: string, body: any)`
748
+ - `updateWebRoute(clientId: string, id: string, body: any)`
749
+ - `deleteWebRoute(clientId: string, id: string)`
750
+ - `getRouters(clientId: string)`
751
+ - `createRouter(clientId: string, body: any)`
752
+ - `updateRouter(clientId: string, id: string, body: any)`
753
+ - `deleteRouter(clientId: string, id: string)`
754
+ - `getGroups(clientId: string)`
755
+ - `getGroupMembers(clientId: string, groupId: string)`
756
+ - `addGroupMember(clientId: string, groupId: string, userId: string, role: string | null)`
757
+ - `updateGroupMemberRole(clientId: string, groupId: string, userId: string, role: string | null)`
758
+ - `removeGroupMember(clientId: string, groupId: string, userId: string)`
759
+ - `searchUsers(clientId: string, opts: { search?: string; limit?: number } = {})`
760
+ - `getAccess(clientId: string)`
761
+ - `createAccess(clientId: string, groupId: string)`
762
+ - `deleteAccess(clientId: string, accessId: string)`
763
+ - `getGuards(clientId: string, accessId: string)`
764
+ - `addGuard(clientId: string, accessId: string, routerId: string)`
765
+ - `removeGuard(clientId: string, accessId: string, guardId: string)`
766
+ - `getApps(clientId: string)`
767
+ - `createApp(clientId: string, body: { name: string; allowed_grants?: string[] })`
768
+ - `updateApp(clientId: string, appId: string, body: any)`
769
+ - `deleteApp(clientId: string, appId: string)`
770
+ - `getAppOperations(clientId: string, appId: string)`
771
+ - `getAppConsumers(clientId: string, appId: string)`
772
+ - `createAppConsumer(clientId: string, appId: string, groupId: string)`
773
+ - `deleteAppConsumer(clientId: string, consumerId: string)`
774
+ - `getAppPermissions(clientId: string, consumerId: string)`
775
+ - `addAppPermission(clientId: string, consumerId: string, operationId: string)`
776
+ - `removeAppPermission(clientId: string, consumerId: string, permissionId: string)`
777
+
778
+ ### Funções
779
+
780
+ - `function provideAutoService(config: AutoServiceConfig): EnvironmentProviders`
781
+
782
+ ### Constantes e tokens
783
+
784
+ - `AUTO_SERVICE_CONFIG`: `InjectionToken<AutoServiceConfig>`
785
+ - `AUTO_SERVICE_GROUPS_TEMPLATE_ROUTER_ID`: `'ad100001-0000-4000-8000-000000000001'`
786
+ - `AUTO_SERVICE_APPS_TEMPLATE_ROUTER_ID`: `'ad100002-0000-4000-8000-000000000001'`
787
+ - `AUTO_SERVICE_CLIENT_TEMPLATE_ROUTER_ID`: `'ad100003-0000-4000-8000-000000000001'`
788
+ - `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID`: `'ad100004-0000-4000-8000-000000000001'`
789
+ - `AUTO_SERVICE_HOME_TEMPLATE_ROUTER_ID`: `'6a9a13db-f31b-494e-b51c-79af0ac28b60'`
790
+ - `AUTO_SERVICE_SCREENS`: `Readonly<Record<'home' | 'groups' | 'apps' | 'client' | 'audit', () => Promise<Type<unknown>>>>` — As 5 telas do auto-serviço, carregadas sob demanda. Cada `import()` relativo vira um chunk próprio no FESM publicado (`trismegisto-spine-auto-service-<tela>-<hash>.mjs`), que o bundler do app mantém fora do carregamento inicial. Não exporte as telas no `publi…
791
+
792
+ ### Tipos
793
+
794
+ #### `AutoServiceConfig` (interface)
795
+
796
+ ```ts
797
+ interface AutoServiceConfig {
798
+ // Base URL do argos-admin-server (o mesmo backend central que atende
799
+ // /admin/*) -- /auto-service/* já existe lá, escopado por client_id, servindo
800
+ // qualquer aplicação que instale este pacote, não só o argos-admin.
801
+ adminApi: string;
802
+ }
803
+ ```
804
+
805
+ #### `AutoServiceClient` (interface)
806
+
807
+ ```ts
808
+ interface AutoServiceClient {
809
+ id: string;
810
+ name: string;
811
+ display_name: string | null;
812
+ realm_id: string;
813
+ }
814
+ ```
815
+
816
+ ## `@trismegisto/spine/graphql`
817
+
818
+ ### Serviços e classes
819
+
820
+ #### `GraphqlEnvelopeError` · extends Error
821
+
822
+ Falha de negócio devolvida pelo backend, com o status do envelope preservado — a tela decide pelo `status` (403 = sem acesso, 404 = vazio, 500 = tente de novo). `message` é texto do backend: exibir como texto, nunca por `innerHTML`.
823
+
824
+ ### Funções
825
+
826
+ - `function isEnvelopeOk(status: GraphqlEnvelope<unknown>['status']): boolean` — O status do envelope indica sucesso? Número: 2xx. Texto: qualquer coisa que não seja erro.
827
+ - `function unwrap<T>(envelope: GraphqlEnvelope<T> | null | undefined): T` — Confere o envelope e devolve o `data`.
828
+ - `function envelopesOf(data: unknown): { field: string; status: number | string; message: string; ok: boolean }[]` — Os envelopes `{ status, message }` de primeiro nível de uma resposta (um por operação raiz).
829
+ - `function failedEnvelopes(data: unknown, fallbackMessage: string = currentSpineMessages().graphql.serviceFailure): { field: string; status: unknown; message: string }[]` — Os envelopes com falha dentro de uma resposta (`result.data` inteiro, um campo por operação raiz). Usado pelo link de aviso do `provideGraphql`; exportado pra quem quiser o mesmo diagnóstico.
830
+ - `function injectGraphqlClient(namedClient: string): GraphqlClient` — O `GraphqlClient` do backend `namedClient` (`environment.graphql.<chave>.namedClient`). Chamar em contexto de injeção.
831
+ - `function provideGraphql(options: GraphqlOptions): Provider` — Clientes Apollo dos apps — UM lugar pra configuração que antes vivia copiada (e divergindo) em cada app: - token do Orfeu em `x-access-token` (o `@orfeu/node` não lê `Authorization`), no HTT…
832
+
833
+ ### Constantes e tokens
834
+
835
+ - `wsReconnected$`: `Subject<string>` — Emite o `namedClient` toda vez que o WebSocket RECONECTA depois de uma queda (não na 1ª conexão). O graphql-ws reassina as subscriptions sozinho, mas não reenvia o que foi publicado durante a queda — a tela usa isto pra ressincronizar.
836
+
837
+ ### Tipos
838
+
839
+ #### `GraphqlEnvelope` (interface)
840
+
841
+ O envelope que os GraphQL dos apps devolvem: `{ status, message, data }`. **O status vem dentro do payload, não no transporte** — uma resposta HTTP 200 pode carregar `status: 403` ou `500`. Ler o `data` sem conferir o `status` é o que faz a tela mostrar "lista vazia" onde devia dizer que faltou permissão ou que o serviço falhou.
842
+
843
+ ```ts
844
+ interface GraphqlEnvelope<T> {
845
+ readonly status?: number | string | null;
846
+ readonly message?: string | null;
847
+ readonly data?: T | null;
848
+ }
849
+ ```
850
+
851
+ #### `GraphqlCallOptions` (interface)
852
+
853
+ Opções de uma chamada. `silenceEnvelope`: a tela trata a falha sozinha, sem o toast automático.
854
+
855
+ ```ts
856
+ interface GraphqlCallOptions {
857
+ readonly silenceEnvelope?: boolean;
858
+ readonly context?: DefaultContext;
859
+ }
860
+ ```
861
+
862
+ #### `GraphqlClient` (interface)
863
+
864
+ Cliente GraphQL de UM backend do app, tipado pelo documento gerado no codegen (`TypedDocumentNode`): o retorno é o `data` da operação, sem `<any>`. Junto com o `unwrap` do envelope, é o caminho padrão dos serviços de domínio: private readonly gql = injectGraphqlClient('principal'); async listTeams() { return unwrap((await this.gql.query(ListTeamsDocument)).teams); }
865
+
866
+ ```ts
867
+ interface GraphqlClient {
868
+ query<T, V extends OperationVariables = OperationVariables>(
869
+ document: TypedDocumentNode<T, V>, variables?: V, options?: GraphqlCallOptions): Promise<T>;
870
+ mutate<T, V extends OperationVariables = OperationVariables>(
871
+ document: TypedDocumentNode<T, V>, variables?: V, options?: GraphqlCallOptions): Promise<T>;
872
+ /** Eventos da subscription (sem envelope: evento não é resposta). Mensagem sem `data` é ignorada. */
873
+ subscribe<T, V extends OperationVariables = OperationVariables>(
874
+ document: TypedDocumentNode<T, V>, variables?: V): Observable<T>;
875
+ }
876
+ ```
877
+
878
+ #### `GraphqlEndpoint` (interface)
879
+
880
+ Um backend GraphQL do app — o tipo de `environment.graphql.<chave>` em TODO app (importar daqui, não redeclarar). Campos mutáveis de propósito: o `main.ts` pode derivar `http`/`ws` do domínio em tempo de execução antes do bootstrap.
881
+
882
+ ```ts
883
+ interface GraphqlEndpoint {
884
+ /** Nome do cliente Apollo (`apollo.use(namedClient)`). */
885
+ namedClient: string;
886
+ http: string;
887
+ /** Sem `ws`, o cliente não tem subscription (só HTTP). */
888
+ ws?: string;
889
+ }
890
+ ```
891
+
892
+ #### `GraphqlOptions` (interface)
893
+
894
+ Sem opções de comportamento DE PROPÓSITO: o padrão é o mesmo em todo app (lote, toast do envelope, reconexão, no-cache). O que varia entre apps é só QUAIS backends existem (`endpoints`).
895
+
896
+ ```ts
897
+ interface GraphqlOptions {
898
+ /** `environment.graphql` do app: um cliente Apollo nomeado por entrada. */
899
+ readonly endpoints: Readonly<Record<string, GraphqlEndpoint>>;
900
+ }
901
+ ```
902
+
903
+ ## `@trismegisto/spine/layout`
904
+
905
+ ### Componentes e diretivas
906
+
907
+ #### `spine-layout` — `LayoutComponent`
908
+
909
+ Shell do spine — MESMA estrutura do `docs/website`'s `app.component.html`/`.scss` (decisão de 2026-09-28): `.shell` com altura de viewport de verdade (`100dvh`, não `%` cascateado — `@trismegisto/core` não fixa altura de `html`/`body`, é responsabilidade de quem consome, mesmo tanto quanto o docs faz no próprio `styles.scss`), `hm-header` (utilitários — tema/densidade/, nunca navegação de página) + `.body` (`hm-sidebar` fixa + `.main` com `hm-workspac…
910
+
911
+ _Sem inputs/outputs._
912
+
913
+ #### `spine-header` — `HeaderComponent`
914
+
915
+ _Sem inputs/outputs._
916
+
917
+ #### `spine-app-launcher` — `AppLauncherComponent`
918
+
919
+ A grade de apps não cabe no `MenuItem` de linha única do `hm-menu` (ícone grande + nome embaixo, em coluna) — em vez de forçar isso num componente pensado pra lista de ações, usa um popover próprio (mesmo padrão do backdrop-fecha-fora da busca global do header).
920
+
921
+ _Sem inputs/outputs._
922
+
923
+ #### `spine-brand` — `SpineBrandComponent`
924
+
925
+ Marca do header: logo do app (`SpineConfig.logo`, padrão `assets/images/logo.svg`) + `appName`, dentro de um link para a home. Ordem: componente de `SPINE_BRAND` > imagem > só o nome.
926
+
927
+ | Nome | Tipo | Tipo TS | Padrão | Descrição |
928
+ |---|---|---|---|---|
929
+ | `homeRoute` | input | `string \| null` | `null` | Rota da home (primeira rota navegável); `null` desenha a marca sem link. |
930
+ | `label` | input | `string` | `''` | Dica do link (ex.: "Página inicial"). |
931
+
932
+ #### `spine-sidebar` — `SidebarComponent`
933
+
934
+ Menu lateral fixo — TODA a navegação do shell mora aqui agora, nunca no header (decisão explícita do usuário: "não deve ter ícones de navegação no menu superior, deve ter um menu lateral de navegação fixa" — o antigo `h-nav`/`hm-menu-button` de nível 'header'/'menu' do `header.component.html` foi removido, essa navegação virou `modules` abaixo).
935
+
936
+ _Sem inputs/outputs._
937
+
938
+ #### `spine-connection-banner` — `SpineConnectionBannerComponent`
939
+
940
+ Aviso discreto de conexão no topo do shell, sobre o `connectionState$` e o `reauthorizationRequired$` do `@orfeu/angular`. A sessão nunca cai por nada disto (sem rede, Argos fora do ar, refresh recusado): a lib segue tentando sozinha e este banner só conta o que está acontecendo.
941
+
942
+ _Sem inputs/outputs._
943
+
944
+ #### `spine-onboarding-overlay` — `OnboardingOverlayComponent`
945
+
946
+ Onboarding próprio: escurece a tela (holofote via box-shadow gigante no recorte do alvo) e posiciona um balão explicativo perto do elemento — ou centralizado nos passos sem alvo (boas-vindas/encerramento). Sem dependência externa, sem sequestrar o scroll da página.
947
+
948
+ _Sem inputs/outputs._
949
+
950
+ #### `spine-shortcuts-cheatsheet` — `ShortcutsCheatsheetComponent`
951
+
952
+ Painel de atalhos (cheatsheet). Abre com "?" (via `ShortcutService.help$`) e lista, com o `hm-shortcut-list` da lib, os atalhos agrupados — com busca e o interruptor dos atalhos de tecla única (WCAG 2.1.4; a escolha persiste no `SpinePreferencesService`). Também é o último passo do onboarding.
953
+
954
+ _Sem inputs/outputs._
955
+
956
+ #### `spine-settings-panel` — `SettingsPanelComponent`
957
+
958
+ Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Aparência, Região, Atalhos, Conta e Sobre, mais as seções que o app registrar com `provideSettingsSection`. Tudo vale na hora — cada controle chama o serviço que já persiste aquela preferência (tema, densidade, menu lateral, fuso).
959
+
960
+ _Sem inputs/outputs._
961
+
962
+ #### `spine-news` — `SpineNewsComponent`
963
+
964
+ Painel de novidades: um diálogo com carrossel — "olha o que mudou", não tutorial (esse é o tour de boas-vindas). Montado uma vez no layout; quem decide quando abre é o `SpineNewsService`.
965
+
966
+ _Sem inputs/outputs._
967
+
968
+ #### `spine-docs` — `SpineDocsComponent`
969
+
970
+ Modal de documentação: índice com busca à esquerda — ele não some ao abrir um documento, é por ele que se pula de uma tela para outra — e a leitura à direita, com a aba técnica só quando `SpineDocsService.showTechnical`.
971
+
972
+ _Sem inputs/outputs._
973
+
974
+ #### `spine-markdown` — `SpineMarkdownComponent`
975
+
976
+ Markdown → HTML sanitizado. O HTML vem de `innerHTML`, que o encapsulamento de view não alcança: por isso `ViewEncapsulation.None` com tudo escopado em `.spine-markdown`.
977
+
978
+ | Nome | Tipo | Tipo TS | Padrão | Descrição |
979
+ |---|---|---|---|---|
980
+ | `content` | input | `string` | `''` | |
981
+
982
+ ### Serviços e classes
983
+
984
+ #### `OnboardingService` · `providedIn: root`
985
+
986
+ Onboarding interativo próprio (sem dependência externa). O overlay/holofote e o balão são renderizados pelo OnboardingOverlayComponent, que escuta este serviço. Aparece uma vez por máquina (flag em localStorage), namespaced por cliente.
987
+
988
+ - `readonly current$: BehaviorSubject` — Passo atual (null = tour inativo). O overlay component reage a isto.
989
+ - `maybeStart(): void` — Dispara o tour só se ainda não foi visto nesta máquina. Chamar após o login.
990
+ - `restart(): void` — Reabre o tour manualmente (menu Ajuda), ignorando a flag.
991
+ - `next(): void`
992
+ - `prev(): void`
993
+ - `finish(): void` — Encerra o tour (concluído ou pulado) e marca como visto.
994
+ - `get isFirst: boolean`
995
+ - `get isLast: boolean`
996
+
997
+ #### `ShortcutService` · `providedIn: root` · implements OnDestroy
998
+
999
+ Atalhos de teclado globais do sistema, sobre o `HermesShortcutService` da lib (um listener só, sequência `G H`, conflito, campo editável, interruptor de tecla única da WCAG 2.1.4).
1000
+
1001
+ - `readonly help$: Subject<void>` — Emite quando o usuário pede o painel de atalhos (tecla "?" ou menu do perfil).
1002
+ - `readonly panelItems: computed<readonly HermesShortcutItem[]>(…)` — O que o painel lista (`<hm-shortcut-list [registered]="false" [items]="panelItems()">`): os atalhos registrados no `HermesShortcutService`, com os favoritos numa linha só, e os só exibidos. Acompanha registro/remoção e…
1003
+ - `get shortcuts: ShortcutItem[]` — Lista do painel em texto, no idioma e na plataforma atuais. @deprecated Use o `hm-shortcut-list` com `panelItems()` (ou `HermesShortcutService.list()`). Mantido para quem montava o próprio painel; sai numa próxima versã…
1004
+ - `groups(): ShortcutGroup[]` — Atalhos por grupo, na ordem navegação → ações → geral, com o nome do grupo traduzido. @deprecated Use o `hm-shortcut-list` (agrupa, traduz e desenha as teclas). Sai numa próxima versão.
1005
+ - `setActions(actions: ShortcutActions): void` — Liga as ações e registra os atalhos no `HermesShortcutService` (idempotente: chamadas seguintes só trocam as ações).
1006
+
1007
+ #### `SpineSettingsService` · `providedIn: root`
1008
+
1009
+ Abre/fecha o painel de configurações de qualquer lugar (menu do perfil, atalho, link).
1010
+
1011
+ - `readonly isOpen: signal(…)`
1012
+ - `readonly section: signal(…)` — Seção pedida na abertura (vazio = a primeira).
1013
+ - `open(section = ''): void`
1014
+ - `close(): void`
1015
+ - `toggle(): void`
1016
+
1017
+ #### `SpineAppTokensService` · `providedIn: root`
1018
+
1019
+ Tokens de aplicação pessoais (`x-app-token`) do usuário logado — `argos-admin /me/app-tokens`. Sempre da aplicação LOGADA: o servidor tira o client do próprio access-token da sessão, então aqui não existe escolha de aplicação. Autentica com o access-token da sessão (o servidor recusa um app-token aqui: token não cria token). `available` é falso quando o app não tem a URL do argos-admin (`SPINE_ADMIN_API`).
1020
+
1021
+ - `readonly available`
1022
+ - `list(): Promise<AppTokenList>`
1023
+ - `options(): Promise<AppTokenOptions>`
1024
+ - `create(body: { badge_id: string; name: string; validity_days: number }): Promise<CreatedAppToken>`
1025
+ - `revoke(id: string): Promise<void>`
1026
+
1027
+ #### `SpineDocsService` · `providedIn: root`
1028
+
1029
+ Documentação das telas. A fonte é o próprio mapa de componentes (`COMPONENT_ROUTES`, campo `document`), e o índice só lista o que está na árvore de rotas da pessoa — documento de tela sem acesso nunca é oferecido nem baixado.
1030
+
1031
+ - `readonly technicalAvailable`
1032
+ - `readonly isOpen: Signal (somente leitura)`
1033
+ - `readonly current: Signal (somente leitura)`
1034
+ - `readonly view: Signal (somente leitura)`
1035
+ - `readonly content: Signal (somente leitura)`
1036
+ - `readonly loading: Signal (somente leitura)`
1037
+ - `readonly error: computed(…)` — Texto do erro de carregamento (vazio = sem erro), no idioma ativo.
1038
+ - `readonly showTechnical: computed(…)`
1039
+ - `readonly index: computed<DocsGroup[]>(…)`
1040
+ - `documentFor(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): DocsEntry | null` — Documento da tela (router_id do client e, como alternativa, o router do template de origem), ou `null` quando ela não tem (ou a pessoa não tem acesso).
1041
+ - `openForRoute(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): void` — Abre o modal no documento da tela; sem documento, no índice.
1042
+ - `openIndex(): void`
1043
+ - `close(): void`
1044
+ - `open(entry: DocsEntry, view: DocsView = 'usage'): Promise<void>`
1045
+ - `show(view: DocsView): Promise<void>`
1046
+
1047
+ #### `SpineNewsService` · `providedIn: root`
1048
+
1049
+ Painel de novidades do app (ver `provideSpineNews`). Decide o que está devido — ainda não visto NESTE navegador e ainda dentro do `until` — e abre sozinho uma vez, depois do tour de boas-vindas. O "já visto" é por app (`hermes_<clientId>_news_seen`): novidade de um app não some por ter sido vista em outro no mesmo domínio.
1050
+
1051
+ - `readonly slides: signal<readonly SpineNewsSlide[]>(…)` — Slides em exibição (os devidos, ou todos os vigentes quando reaberto pelo menu).
1052
+ - `readonly isOpen: signal(…)`
1053
+ - `readonly hasAny: computed(…)` — Há alguma novidade vigente — o item "Novidades" do menu só aparece com isto.
1054
+ - `scheduleOnEntry(): void` — Chamado uma vez pelo layout na entrada: abre as devidas, esperando o tour terminar.
1055
+ - `showDue(): void` — Abre as devidas e as marca como vistas (vistas juntas, marcadas juntas).
1056
+ - `showAll(): void` — Reabre todas as vigentes (menu do perfil), vistas ou não.
1057
+ - `close(): void`
1058
+
1059
+ ### Funções
1060
+
1061
+ - `function findTourTarget(selector: string): HTMLElement | null` — Primeiro elemento do seletor que está de fato na tela (tem tamanho e conteúdo). Não usa `offsetParent`: ele é `null` pra `position: fixed` (a sidebar) e pra `display: contents`, e o passo sumia do tour mesmo com o alvo visível. Com as abas vivas do workspace…
1062
+ - `function provideSettingsSection(section: SpineSettingsSection): Provider` — Registra uma seção do app no painel de configurações (aparece depois das do spine, antes de "Sobre"). Pode ser chamado várias vezes, uma por seção.
1063
+
1064
+ ### Constantes e tokens
1065
+
1066
+ - `SPINE_BRAND`: `InjectionToken<Type<unknown> | null>` — Componente de marca que o header do shell desenha no lugar da imagem de `SpineConfig.logo` (tem prioridade sobre ela). Injeção em vez de projeção de conteúdo porque o `LayoutComponent` é montado pelo `Router`, não pelo template do app — não existe `<ng-conten…
1067
+ - `SPINE_SETTINGS_KEYS` — Seções que o próprio spine já traz. `key` é também o valor de `?settings=` na URL.
1068
+ - `SPINE_SETTINGS_SECTIONS`: `InjectionToken<SpineSettingsSection[]>`
1069
+
1070
+ ### Tipos
1071
+
1072
+ #### `OnboardingStep` (interface)
1073
+
1074
+ ```ts
1075
+ interface OnboardingStep {
1076
+ /** seletor CSS do alvo; ausente = passo centralizado (boas-vindas/encerramento). */
1077
+ target?: string;
1078
+ title: string;
1079
+ /** pode conter HTML simples (<b>). */
1080
+ description: string;
1081
+ }
1082
+ ```
1083
+
1084
+ #### `ShortcutGroupId` (type)
1085
+
1086
+ Grupo do painel de atalhos. Id estável; o nome exibido vem do catálogo da lib (`shortcuts.groups`).
1087
+
1088
+ ```ts
1089
+ type ShortcutGroupId = 'navigation' | 'actions' | 'general';
1090
+ ```
1091
+
1092
+ #### `ShortcutItem` (interface)
1093
+
1094
+ Item exibido no painel de atalhos (cheatsheet, aberto com "?").
1095
+
1096
+ ```ts
1097
+ interface ShortcutItem {
1098
+ /** Teclas já em texto, na plataforma atual (`'Ctrl + K'`, `'⌘K'`, `'G depois H'`). */
1099
+ keys: string;
1100
+ description: string;
1101
+ group: ShortcutGroupId;
1102
+ }
1103
+ ```
1104
+
1105
+ #### `ShortcutGroup` (interface)
1106
+
1107
+ Atalhos agrupados, já com o nome do grupo no idioma ativo.
1108
+
1109
+ ```ts
1110
+ interface ShortcutGroup {
1111
+ id: ShortcutGroupId;
1112
+ name: string;
1113
+ items: ShortcutItem[];
1114
+ }
1115
+ ```
1116
+
1117
+ #### `ShortcutActions` (interface)
1118
+
1119
+ Ações concretas que o atalho dispara — ligadas pelo LayoutComponent.
1120
+
1121
+ ```ts
1122
+ interface ShortcutActions {
1123
+ navigate?: (url: string) => void; // navega para uma rota (ex.: '/home', favorito)
1124
+ toggleTheme?: () => void; // alterna claro/escuro
1125
+ toggleFullscreen?: () => void; // tela cheia
1126
+ logout?: () => void; // sair
1127
+ openSettings?: () => void; // painel de configurações
1128
+ }
1129
+ ```
1130
+
1131
+ #### `SpineSettingsSection` (interface)
1132
+
1133
+ Seção extra do painel, registrada pelo app (ex.: preferências de deploy do app).
1134
+
1135
+ ```ts
1136
+ interface SpineSettingsSection {
1137
+ /** Identificador estável; também o que `?settings=<key>` abre. Não repetir os do spine. */
1138
+ key: string;
1139
+ label: string;
1140
+ /** Ícone do hermes-icon na navegação. */
1141
+ icon?: string;
1142
+ description?: string;
1143
+ /** Termos extras que acham a seção inteira na busca. */
1144
+ keywords?: string;
1145
+ /** Conteúdo da seção — de preferência `hm-settings-row`s, para a busca achar cada linha. */
1146
+ component: Type<unknown>;
1147
+ }
1148
+ ```
1149
+
1150
+ #### `AppToken` (interface)
1151
+
1152
+ Um token de aplicação do usuário, como o argos-admin devolve (nunca o valor, só o prefixo).
1153
+
1154
+ ```ts
1155
+ interface AppToken {
1156
+ id: string;
1157
+ name: string;
1158
+ description: string | null;
1159
+ prefix: string;
1160
+ badge_id: string;
1161
+ badge_name: string;
1162
+ expires_at: string;
1163
+ created_at: string;
1164
+ last_used_at: string | null;
1165
+ expired: boolean;
1166
+ }
1167
+ ```
1168
+
1169
+ #### `AppTokenList` (interface)
1170
+
1171
+ ```ts
1172
+ interface AppTokenList {
1173
+ tokens: AppToken[];
1174
+ max_active: number;
1175
+ max_days: number;
1176
+ }
1177
+ ```
1178
+
1179
+ #### `AppTokenOptions` (interface)
1180
+
1181
+ A aplicação logada e os níveis de acesso que o usuário pode escolher nela ao criar um token.
1182
+
1183
+ ```ts
1184
+ interface AppTokenOptions {
1185
+ client: { id: string; name: string | null };
1186
+ badges: { id: string; name: string }[];
1187
+ max_days: number;
1188
+ }
1189
+ ```
1190
+
1191
+ #### `CreatedAppToken` (interface)
1192
+
1193
+ ```ts
1194
+ interface CreatedAppToken {
1195
+ id: string;
1196
+ /** Valor bruto — só existe nesta resposta. */
1197
+ token: string;
1198
+ expires_at: string;
1199
+ }
1200
+ ```
1201
+
1202
+ #### `DocsEntry` (interface)
1203
+
1204
+ Documento de tela já resolvido contra a árvore de rotas: título e grupo sempre presentes.
1205
+
1206
+ ```ts
1207
+ interface DocsEntry extends RouteDocument {
1208
+ readonly id: string;
1209
+ readonly title: string;
1210
+ readonly group: string;
1211
+ }
1212
+ ```
1213
+
1214
+ #### `DocsGroup` (interface)
1215
+
1216
+ ```ts
1217
+ interface DocsGroup {
1218
+ readonly title: string;
1219
+ readonly entries: readonly DocsEntry[];
1220
+ }
1221
+ ```
1222
+
1223
+ #### `DocsView` (type)
1224
+
1225
+ ```ts
1226
+ type DocsView = 'usage' | 'technical';
1227
+ ```
1228
+
1229
+ ## `@trismegisto/spine/modal`
1230
+
1231
+ ### Componentes e diretivas
1232
+
1233
+ #### `spine-modal` — `ModalComponent`
1234
+
1235
+ _Sem inputs/outputs._
1236
+
1237
+ ### Serviços e classes
1238
+
1239
+ #### `ModalService` · `providedIn: root`
1240
+
1241
+ - `readonly visible$: Observable<boolean>`
1242
+ - `readonly state$: Observable<HermesLoadingState>`
1243
+ - `get config: ModalConfig | null`
1244
+ - `open<TResult = any, TData = any>(config: ModalConfig<TData>): Observable<TResult | null>`
1245
+ - `confirm(result: any): void`
1246
+ - `close(): void`
1247
+ - `setState(state: HermesLoadingState): void`
1248
+
1249
+ ### Tipos
1250
+
1251
+ #### `ModalConfig` (interface)
1252
+
1253
+ ```ts
1254
+ interface ModalConfig<TData = any> {
1255
+ title?: string;
1256
+ size?: 'sm' | 'md' | 'lg' | 'xl';
1257
+ closable?: boolean;
1258
+ text?: string;
1259
+ component?: Type<ModalContent>;
1260
+ data?: TData;
1261
+ showActions?: boolean;
1262
+ }
1263
+ ```
1264
+
1265
+ #### `ModalContent` (interface)
1266
+
1267
+ ```ts
1268
+ interface ModalContent<TResult = any> {
1269
+ getResult(): TResult;
1270
+ isValid?(): boolean;
1271
+ }
1272
+ ```
1273
+
1274
+ ## `@trismegisto/spine/notification`
1275
+
1276
+ ### Componentes e diretivas
1277
+
1278
+ #### `spine-notification` — `NotificationComponent`
1279
+
1280
+ _Sem inputs/outputs._
1281
+
1282
+ ### Serviços e classes
1283
+
1284
+ #### `NotificationService` · `providedIn: root`
1285
+
1286
+ - `readonly notifications$: Observable<Notification[]>`
1287
+ - `resolveAlertType(status: number): AlertType` — O `status` do envelope `{ status, message, data }` dos GraphQL decide o tipo do toast — o mesmo contrato em todo app: 2xx sucesso, 3xx atenção (concluiu com ressalva), 4xx/5xx erro, o resto informação. Por faixa (antes…
1288
+ - `addNotification(notification: NotificationInput): void`
1289
+ - `processErrorNotification(): void`
1290
+
1291
+ ### Tipos
1292
+
1293
+ #### `AlertType` (enum)
1294
+
1295
+ ```ts
1296
+ enum AlertType {
1297
+ INFO = 'info',
1298
+ WARNING = 'warning',
1299
+ SUCCESS = 'success',
1300
+ DANGER = 'danger',
1301
+ }
1302
+ ```
1303
+
1304
+ #### `Notification` (interface)
1305
+
1306
+ ```ts
1307
+ interface Notification {
1308
+ timer: number;
1309
+ expirer?: number;
1310
+ hermesAlertType: AlertType;
1311
+ message: string;
1312
+ hermesAlertAppLevel?: boolean;
1313
+ hermesAlertClosable?: boolean;
1314
+ }
1315
+ ```
1316
+
1317
+ #### `NotificationInput` (type)
1318
+
1319
+ ```ts
1320
+ type NotificationInput = Omit<Notification, 'hermesAlertType' | 'expirer'> & {
1321
+ hermesAlertType: AlertType | number;
1322
+ };
1323
+ ```
1324
+
1325
+ ## `@trismegisto/spine/routing`
1326
+
1327
+ ### Serviços e classes
1328
+
1329
+ #### `LoggerService` · `providedIn: root`
1330
+
1331
+ - `get logger: Route[]`
1332
+ - `setLogger(logger: Route[])`
1333
+ - `get page: Route | null` — A página atual (último nó da cadeia do painel focado).
1334
+ - `get routerId: string | null` — `router_id` da página atual -- a identidade da TELA no spine (componente, documento, descrição).
1335
+ - `get routeId: string | null` — A ROTA da página atual (`web.routes.route_id`, o `routed_id` do nó) -- o que vai em `x-route-id` e vira `audit.events.route_id`/`route_name`. Só quando o último nó é uma página de verdade (tem router): grupo puramente o…
1336
+
1337
+ #### `RouteIdInterceptor` · `@Injectable` (fornecido por quem usa) · implements HttpInterceptor
1338
+
1339
+ Attaches the current screen's ROUTE id — `web.routes.route_id` of the page node (`routed_id`), NOT the `router_id` the spine uses to identify the screen (see `LoggerService.routeId`) — and the app's `clientId` from `SpineConfig` as headers on every outgoing HTTP request, read from `LoggerService` (updated by `ViewGuard` on every navigation — see view.guard.ts). This is a caller-supplied correlation tag consumed by Orfeu's structured operation logs to correlate an operation_id with the route tha…
1340
+
1341
+ - `intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>`
1342
+
1343
+ #### `ViewGuard` · `providedIn: root` · implements CanActivate
1344
+
1345
+ Gate de navegação REAL (deep link, F5, `router.navigateByUrl` do painel focado — ver `SpineWorkspaceNavService`). Não desenha mais nada nem alimenta breadcrumb/sidebar: isso agora é responsabilidade de cada painel do workspace (`resolveSpineRoute`, chamado direto por quem precisa da cadeia). O guard só confirma que a URL resolve contra a view atual — senão redireciona pro fallback navegável ou pra `/no-permission` — e existe numa única rota coringa (ver `private.routes.ts`), não mais em 6 nívei…
1346
+
1347
+ - `canActivate(_route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean`
1348
+ - `canActivateChild(_route: ActivatedRouteSnapshot, state: RouterStateSnapshot): boolean`
1349
+ - `canLoad(route: NgRoute): boolean`
1350
+
1351
+ #### `ComponentDistributorService` · `providedIn: root`
1352
+
1353
+ - `readonly lastMissingRouterId: signal(…)` — `router_id` da última falha (sem entrada registrada ou import quebrado) — lido por `NoContentComponent` pra montar a descrição (ver comentário dela). Sinal só, não por instância: se dois painéis erram ao mesmo tempo, o…
1354
+ - `get lastMissingRouteId` — Depreciado: use `lastMissingRouterId` (sempre foi o router_id).
1355
+ - `get entries: readonly ComponentRoute[]` — Todas as entradas registradas (app + pacotes plugáveis) -- lidas pela documentação.
1356
+ - `getComponent(routerId: string, source_template_router_id?: string | null): Promise<Type<any>>`
1357
+
1358
+ ### Funções
1359
+
1360
+ - `function componentRouterId(route: ComponentRoute): string | undefined` — `id` (router_id) da entrada, aceitando o formato antigo (`route_id`).
1361
+ - `function componentRouteLoader(route: ComponentRoute): (() => Promise<Type<any>>) | undefined` — Carregador da entrada, aceitando o formato antigo (`component`).
1362
+ - `function isChunkLoadError(err: unknown): boolean` — O import dinâmico falhou porque o arquivo da tela não existe mais no servidor — saiu um build novo enquanto a aba estava aberta e os chunks antigos foram trocados. Mensagens dos navegadores: Chrome/Edge "Failed to fetch dynamically imported module", Firefox "…
1363
+ - `function findRouteThrough(routes: Route[], urlAtLevel: string): Route | null` — Acha uma rota cujo `route_redirect` bate com `urlAtLevel`, atravessando ancestrais "transparentes" (sem `route_redirect` próprio — só agrupam os filhos).
1364
+ - `function findFirstNavigable(routes: Route[]): string | null` — Primeira rota navegável (DFS), atravessando grupos transparentes — usada como fallback quando a URL alvo não bate com nada na view atual.
1365
+ - `function resolveRouteChain(currentRoutes: Route[], getLevel: (url: string) => number, getUrlAtLevel: (url: string, level: number) => string, url: string): Route[] | null` — Resolve a cadeia INTEIRA de rotas (header→navigation→menu→item→submenu→page, até onde a URL for funda) pra uma URL qualquer, lendo só `currentRoutes`/`getLevel`/`getUrlAtLevel` — as mesmas três primitivas que `ViewGuard` já usava, sem tocar no `Router`. `chai…
1366
+ - `function resolveEffectiveRouteChain(currentRoutes: Route[], getLevel: (url: string) => number, getUrlAtLevel: (url: string, level: number) => string, url: string): Route[] | null` — `resolveRouteChain`, mas descendo sozinho quando o nó final tem filhos e nenhum conteúdo próprio — o mesmo comportamento que o `RouterComponent` antigo tinha (cada nível, ao pousar numa rota com `routes.length > 0`, `router.navigate([routes[0].route_redirect]…
1367
+ - `async function resolveSpineRoute(currentRoutes: Route[], getLevel: (url: string) => number, getUrlAtLevel: (url: string, level: number) => string, distributor: ComponentDistributorService, url: string): Promise<ResolvedSpineRoute | null>`
1368
+
1369
+ ### Constantes e tokens
1370
+
1371
+ - `ROUTE_ID_HEADER`: `'X-Route-Id'` — Must match `@orfeu/node`/`orfeu` (Python)'s `ROUTE_ID_HEADER` (`x-route-id`).
1372
+ - `CLIENT_ID_HEADER`: `'X-Client-Id'` — Must match `@orfeu/node`/`orfeu` (Python)'s `CLIENT_ID_HEADER` (`x-client-id`): which app (client) the action came from.
1373
+ - `componentRouteId` — Depreciado: use `componentRouterId` (o id da entrada é o router_id da tela).
1374
+ - `COMPONENT_ROUTES`: `InjectionToken<ComponentRoute[]>`
1375
+
1376
+ ### Tipos
1377
+
1378
+ #### `RouteDocument` (interface)
1379
+
1380
+ Documentação de uma tela, carregada sob demanda. O texto é markdown cru — no app, `import('./README.md')` com o loader `.md: "text"` no `angular.json` —, então viaja no chunk lazy da própria tela e só é baixado quando alguém abre a documentação.
1381
+
1382
+ ```ts
1383
+ interface RouteDocument {
1384
+ /** Nome no índice. Opcional: sem ele vale o `route_display_name` da rota na árvore. */
1385
+ title?: string;
1386
+ /** Agrupa o índice. Opcional: sem ele vale o módulo (nó raiz) da rota na árvore. */
1387
+ group?: string;
1388
+ /** Manual de uso, para quem opera a tela (o `README.md`). */
1389
+ load: () => Promise<string>;
1390
+ /** Especificação técnica, para quem desenvolve (o `ESPECIFICACAO.md`). Só exibida quando
1391
+ * `SpineConfig.technicalDocs` (padrão: fora de produção, `isDevMode()`). */
1392
+ loadTechnical?: () => Promise<string>;
1393
+ }
1394
+ ```
1395
+
1396
+ #### `ComponentRoute` (interface)
1397
+
1398
+ Uma tela do app. A chave é o ROUTER (`web.router.router_id` do client -- a posição da tela na navegação, o `router_id` do nó 'page' da view), nunca o `web.routes.route_id` (a rota é só nome/ícone/path, reaproveitável em vários routers). Tela de template (ex.: auto-serviço) usa `source_template_router_id` -- o router do TEMPLATE, igual em todos os clients vinculados.
1399
+
1400
+ ```ts
1401
+ interface ComponentRoute {
1402
+ /** `router_id` (web.router do client) da tela. */
1403
+ id?: string;
1404
+ /** Componente da tela, via `import()` dinâmico (code-splitting por tela). */
1405
+ load?: () => Promise<Type<any>>;
1406
+ /** Documentação da tela, exibida pelo botão de documentação da barra da página. */
1407
+ document?: RouteDocument;
1408
+
1409
+ /** @deprecated use `id`. Mantido para os mapas antigos (o valor sempre foi o router_id); `id` vence
1410
+ * quando os dois vêm. */
1411
+ route_id?: string;
1412
+ /** @deprecated use `load`. */
1413
+ component?: () => Promise<Type<any>>;
1414
+
1415
+ // Alternativa a `id`: source_template_router_id casa com QUALQUER client vinculado ao
1416
+ // template de origem daquele router (uso por pacotes plugáveis tipo @trismegisto/spine/auto-service,
1417
+ // que não conhecem o router_id materializado de cada client -- só o router_id do próprio
1418
+ // template, estável). Ver ComponentDistributorService.getComponent.
1419
+ source_template_router_id?: string;
1420
+ }
1421
+ ```
1422
+
1423
+ #### `ResolvedSpineRoute` (interface)
1424
+
1425
+ Traduz uma URL na cadeia de rotas do backend (header→navigation→menu→item→submenu→page) e no componente da folha — sem passar pelo `Router` do Angular. É o que torna o painel do workspace possível — o `Router` tem uma URL só; um painel não-focado precisa resolver a dele de forma independente. Anda-se na árvore `Route[]` que o backend manda (`ViewService.currentView`), a mesma que `ViewGuard` lia.
1426
+
1427
+ ```ts
1428
+ interface ResolvedSpineRoute {
1429
+ /** A cadeia inteira, nível 1 (header) até onde a URL alcançar. `chain.at(-1)` é sempre o nível
1430
+ * 'page' — é dele que `component` vem. Níveis intermediários (`item`/`submenu`) com mais de um
1431
+ * irmão são o que vira aba de submenu/multipágina no painel. */
1432
+ readonly chain: Route[];
1433
+ readonly component: Type<unknown>;
1434
+ }
1435
+ ```
1436
+
1437
+ ## `@trismegisto/spine/shell`
1438
+
1439
+ ### Componentes e diretivas
1440
+
1441
+ #### `app-callback` — `CallbackComponent`
1442
+
1443
+ Rota de retorno do Argos (`/callback?code&state` ou `?error`). Tudo passa pelo `handleCallback()` do `@orfeu/angular`, que confere state e verifier, troca o code e navega para a URL pedida antes do login (ou para a 1ª rota do `/view`).
1444
+
1445
+ _Sem inputs/outputs._
1446
+
1447
+ #### `app-login` — `LoginComponent`
1448
+
1449
+ _Sem inputs/outputs._
1450
+
1451
+ #### `loggedout` — `LoggedOutComponent`
1452
+
1453
+ _Sem inputs/outputs._
1454
+
1455
+ #### `no-rights` — `NoRightsComponent`
1456
+
1457
+ _Sem inputs/outputs._
1458
+
1459
+ #### `blocked` — `BlockedComponent`
1460
+
1461
+ "Acesso bloqueado" (`/blocked`): a pessoa entrou, mas não faz parte de nenhum grupo vinculado a esta aplicação — o `ViewGuard` manda pra cá quando o token vem sem nenhum crachá (`badges` vazio), mesmo que o app tenha rotas públicas.
1462
+
1463
+ _Sem inputs/outputs._
1464
+
1465
+ #### `loading-page` — `LoadingPageComponent`
1466
+
1467
+ _Sem inputs/outputs._
1468
+
1469
+ ### Funções
1470
+
1471
+ - `function provideShell(options: ShellOptions = {}): EnvironmentProviders`
1472
+
1473
+ ### Constantes e tokens
1474
+
1475
+ - `APP_ROUTES`: `Routes`
1476
+ - `PUBLIC_ROUTES`: `Routes`
1477
+ - `PRIVATE_ROUTES`: `Routes` — Quem desenha o conteúdo agora é o `hm-workspace` (ver `LayoutComponent`/ `layout/src/workspace/`), nunca um `<router-outlet>` aninhado — a árvore de 6 níveis (header/navigation/menu/item/submenu/page) que existia aqui foi substituída por `resolveSpineRoute`,…
1478
+ - `BASE_COMPONENTS`: `ComponentRoute[]` — Componentes que o próprio shell traz, ligados pelo `router_id` (web.router) da árvore de rotas do argos.
1479
+
1480
+ ### Tipos
1481
+
1482
+ #### `ShellOptions` (interface)
1483
+
1484
+ ```ts
1485
+ interface ShellOptions {
1486
+ appComponents?: ComponentRoute[];
1487
+ packageInfo?: PackageInfo;
1488
+ }
1489
+ ```
1490
+
1491
+ ### Reexportados
1492
+
1493
+ - `APP_PACKAGE_INFO` — o mesmo símbolo de `@trismegisto/spine`
1494
+ - `PackageInfo` — o mesmo símbolo de `@trismegisto/spine`
1495
+
1496
+ ## `@trismegisto/spine/side-panel`
1497
+
1498
+ ### Componentes e diretivas
1499
+
1500
+ #### `spine-side-panel` — `SidePanelComponent`
1501
+
1502
+ _Sem inputs/outputs._
1503
+
1504
+ ### Serviços e classes
1505
+
1506
+ #### `SidePanelService` · `providedIn: root`
1507
+
1508
+ - `readonly visible$: Observable<boolean>`
1509
+ - `readonly state$: Observable<HermesLoadingState>`
1510
+ - `get config: SidePanelConfig | null`
1511
+ - `open<TResult = any, TData = any>(config: SidePanelConfig<TData>): Observable<TResult | null>`
1512
+ - `confirm(result: any): void`
1513
+ - `close(): void`
1514
+ - `setState(state: HermesLoadingState): void`
1515
+
1516
+ ### Tipos
1517
+
1518
+ #### `SidePanelConfig` (interface)
1519
+
1520
+ ```ts
1521
+ interface SidePanelConfig<TData = any> {
1522
+ title?: string;
1523
+ size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
1524
+ closable?: boolean;
1525
+ text?: string;
1526
+ component?: Type<ModalContent>;
1527
+ data?: TData;
1528
+ showActions?: boolean;
1529
+ }
1530
+ ```