@trismegisto/spine 2.0.0

package/LICENSE

@@ -0,0 +1,56 @@
+Hermes License 1.0
+
+Copyright (c) 2026 Lucas Ribeiro. All rights reserved except as granted below.
+
+1. Use. You may, free of charge, install and use this software (the "Library"),
+   unmodified, for any purpose, including commercial purposes.
+
+2. Applications. You may include the unmodified Library in an application or
+   service you build and distribute or make that application available to others
+   (for example, a compiled web application bundle, a container image or an
+   installed program), provided the Library is not offered as a separate,
+   standalone component and this license notice is kept with it.
+
+3. No modification. You may not modify, adapt, translate or create derivative
+   works of the Library.
+
+4. No redistribution. Except as allowed in section 2, you may not publish,
+   redistribute, sublicense, sell or otherwise make available the Library —
+   including as a package in a public or private registry, a fork or a copy of
+   its source code.
+
+5. Notice. You must keep this license and the copyright notice with every copy
+   of the Library.
+
+6. No warranty. The Library is provided "as is", without warranty of any kind,
+   express or implied. In no event shall the author be liable for any claim,
+   damages or other liability arising from the use of the Library.
+
+7. Third-party components. Some files in the Library are, or are derived from,
+   third-party software and fonts. They are identified in the NOTICE files, in
+   the LICENSES folders and in the font license files shipped with the package,
+   and remain under their own licenses. Nothing in this license limits the
+   rights those licenses grant for those parts.
+
+---
+
+Licença Hermes 1.0 (tradução de referência; em caso de divergência vale o texto em inglês)
+
+1. Uso. Você pode, gratuitamente, instalar e usar esta biblioteca, sem modificações,
+   para qualquer finalidade, inclusive comercial.
+2. Aplicações. Você pode incluir a biblioteca, sem modificações, numa aplicação ou
+   serviço seu e distribuir ou disponibilizar essa aplicação (por exemplo, o bundle de
+   um app web, uma imagem de container ou um programa instalado), desde que a biblioteca
+   não seja oferecida como componente avulso e este aviso de licença a acompanhe.
+3. Sem modificação. Você não pode modificar, adaptar, traduzir nem criar obras
+   derivadas da biblioteca.
+4. Sem redistribuição. Fora o permitido no item 2, você não pode publicar, redistribuir,
+   sublicenciar, vender ou disponibilizar a biblioteca — inclusive como pacote num
+   registry público ou privado, fork ou cópia do código-fonte.
+5. Aviso. Mantenha esta licença e o aviso de copyright em todas as cópias.
+6. Sem garantia. A biblioteca é fornecida "como está", sem garantia de qualquer tipo.
+7. Componentes de terceiros. Alguns arquivos da biblioteca são, ou derivam de, software
+   e fontes de terceiros. Eles estão identificados nos arquivos NOTICE, nas pastas
+   LICENSES e nos arquivos de licença das fontes que acompanham o pacote, e continuam
+   sob as licenças originais. Nada nesta licença limita os direitos que elas concedem
+   sobre essas partes.

package/README.md

@@ -0,0 +1,207 @@
+# @trismegisto/spine
+
+Shell de aplicação pronto sobre o `@trismegisto/angular`: cabeçalho, menu lateral, área de trabalho em abas
+(`hm-workspace`), roteamento hierárquico a partir da árvore de rotas do servidor de autorização, telas de
+login/estado (sem permissão, bloqueado, carregando), modal, painel lateral e notificações por serviço,
+configurações (tema, família, densidade, fonte, atalhos), tour de boas-vindas, novidades e documentação por
+tela.
+
+Na cadeia de camadas (`tokens ← icons ← primitives ← core ← angular ← maps · charts · spine`) é a ponta: monta
+peças grandes sobre o `@trismegisto/angular` e é o que os apps da organização usam como esqueleto. Ao contrário
+dos outros pacotes, é acoplado à autenticação (`@orfeu/angular` ≥ 0.9.9, OIDC + PKCE contra o Argos): serve a
+apps que se autenticam nesse servidor. O app e o spine precisam usar a **mesma** cópia do `@orfeu/angular` — com o
+app ainda no SDK antigo (`@caronte-sdk/angular`) os serviços seriam outros e o shell quebraria
+(`NullInjectorError` em `AUTH_CONFIG` ou uma segunda sessão); migre os dois juntos.
+
+## Instalação
+
+```bash
+npm install @trismegisto/spine @trismegisto/angular @trismegisto/core @trismegisto/tokens @trismegisto/primitives @trismegisto/icons
+```
+
+Peers: os cinco pacotes base do Hermes (mesma versão), `@angular/core`, `common` e `router` ≥ 21, `rxjs` e
+`@orfeu/angular` (`^0.9.9`). Só para o ponto `@trismegisto/spine/graphql`: `@apollo/client`, `apollo-angular`,
+`graphql` e `graphql-ws` (opcionais). O CSS é o mesmo dos pacotes base (`tokens.css` e `core.css` no
+`angular.json`, ver o [README do `@trismegisto/angular`](../angular/README.md)).
+
+## Configuração do app
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideAuth } from '@orfeu/angular/core';
+import { provideUi, provideSpineNews } from '@trismegisto/spine';
+import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
+import { components } from './features/features.routes';
+import { environment } from './environments/environment';
+import packageInfo from '../../package.json';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideUi({ clientId: environment.authorizationServer.clientId, appName: 'Meu App' }),
+    provideRouter(APP_ROUTES),
+    provideAuth(environment.authorizationServer),
+    provideShell({ appComponents: components, packageInfo }),
+    // provideSpineNews([...]),  // novidades exibidas uma vez por pessoa
+  ],
+};
+```
+
+- **`provideUi(config)`** registra o catálogo de ícones inteiro (o shell usa ícones de vários grupos), aplica
+  o tema no `<body>` e usa `clientId` como prefixo de **todas** as chaves salvas (tema, menu lateral, abas):
+  apps diferentes na mesma origem não misturam preferências. Opções: `clientId`, `appName` (nome ao lado do
+  logo no cabeçalho), `logo`, `showAppName` e `favicon` (ver "Logo e favicon" abaixo), `technicalDocs` (mostra a
+  especificação técnica das telas; padrão `isDevMode()`).
+- **`APP_ROUTES`** traz login, callback, saída e as rotas privadas sob o `spine-layout`
+  (`LayoutComponent`). O `/callback` usa o `handleCallback()` do `@orfeu/angular`: confere state/verifier, volta
+  para a URL pedida antes do login e, no `login_required` da reautorização silenciosa, segue sozinho para o login
+  interativo. Callback recusado nunca desloga: com sessão viva volta para a URL de retorno; sem sessão mostra a
+  página de erro com "Entrar novamente". O `spine-layout` traz o **aviso de conexão** (`spine-connection-banner`,
+  entre o cabeçalho e o corpo): `hm-alert` em faixa quando o `connectionState$` está `offline`, `reconnecting` ou
+  `reauthorizing`, e "Entrar novamente" (sem deslogar) quando o `reauthorizationRequired$` pede — textos em
+  `SpineMessages.session`. O componente raiz do app só precisa de um `<router-outlet />`: o tema já está no
+  `<body>`, então não use `hermesTheme` por cima.
+- **`provideShell({ appComponents, packageInfo })`** liga cada tela do app a um `id` da árvore de rotas — o
+  **`router_id`** da tela (`web.router` do client, o `router_id` do nó 'page' da view), nunca o `web.routes.route_id`.
+  Tela de template (auto-serviço) registra `source_template_router_id` (o router do template, igual em todo client
+  vinculado). O título e a **descrição** da tela (`web.router.description`, editada no Argos) aparecem na barra da
+  página (`spine-page-bar`): a tela não repete título/descrição internos.
+
+```ts
+import { ComponentRoute } from '@trismegisto/spine/routing';
+
+export const components: ComponentRoute[] = [
+  {
+    id: '<router_id da tela>',
+    load: () => import('./dashboard/dashboard.component').then((m) => m.DashboardComponent),
+    document: { load: () => import('./dashboard/README.md').then((m) => m.default) }, // opcional
+  },
+];
+```
+
+## Logo e favicon
+
+O spine não traz marca nenhuma: o logo do cabeçalho e o favicon são arquivos do app.
+
+```ts
+provideUi({
+  clientId: environment.authorizationServer.clientId,
+  appName: 'Meu App',
+  // Omitido = convenção 'assets/images/logo.svg' (arquivo em src/assets/images/logo.svg).
+  logo: { light: 'assets/images/logo.svg', dark: 'assets/images/logo-dark.svg' },
+  favicon: 'assets/favicon.ico',
+}),
+```
+
+| Opção | Padrão | O que faz |
+| --- | --- | --- |
+| `logo` | `'assets/images/logo.svg'` | String (os dois temas), `{ light, dark?, alt? }` (`dark` no tema escuro) ou `false` (sem imagem). SVG, PNG, WebP… — qualquer imagem que o navegador abra |
+| `showAppName` | `true` | Mostra `appName` ao lado do logo. Com `false`, o nome só aparece quando não há logo visível |
+| `favicon` | — | Atualiza (ou cria) o `<link rel="icon">` no bootstrap. Sem ele, vale o do `index.html` (`assets/favicon.ico` nos apps) |
+
+- **Onde pôr os arquivos:** `src/assets/images/logo.svg` (e `logo-dark.svg`, opcional) e `src/assets/favicon.ico`,
+  com `src/assets` publicado em `assets/` no `angular.json`. O `href` é relativo ao `<base href>`.
+- **Sem arquivo / erro:** imagem que não carrega (404) some e fica só o nome — sem ícone quebrado; o console mostra só
+  o 404 do navegador. A variante `dark` que falha cai para a `light`. Para não ter nem o 404, use `logo: false`.
+- **Tamanho e contraste:** altura fixa de 28px (`--hm-icon-xl`), largura proporcional com teto (6× a altura; 4× no
+  celular). O fundo do cabeçalho é a banda escura (`--hm-navbar-surface`) **nos dois temas**: o logo precisa ser
+  legível sobre ela (versão clara/branca); `dark` serve para um ajuste fino no tema escuro.
+- **Acessibilidade:** a marca é um link para a primeira rota da view (dica `SpineMessages.header.home`). Texto
+  alternativo = `logo.alt`; sem ele, vazio quando o nome está ao lado (o leitor de tela não repete) e o `appName`
+  quando o nome está escondido.
+- **Marca em componente:** `{ provide: SPINE_BRAND, useValue: MarcaComponent }` (`@trismegisto/spine/layout`) tem
+  prioridade sobre a imagem (ex.: SVG inline com `currentColor`). Ele fica dentro do link — sem link/botão dentro.
+
+## Pontos de entrada
+
+| Import | Conteúdo |
+| --- | --- |
+| `@trismegisto/spine` | `provideUi`, `SpineConfig`, `ThemeService`, `DensityService`, `SpinePreferencesService`, `provideSpineNews`, textos (`SPINE_MESSAGES`, `provideSpineMessages`) |
+| `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, telas de login e de estado |
+| `@trismegisto/spine/routing` | `ComponentRoute`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor`, resolução de rota |
+| `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), cabeçalho, menu lateral, onboarding, atalhos, configurações, novidades, documentação |
+| `@trismegisto/spine/modal` | `ModalService` (`open(config)` devolve um `Observable` com o resultado), `ModalContent` |
+| `@trismegisto/spine/side-panel` | `SidePanelService`, `SidePanelContent` |
+| `@trismegisto/spine/notification` | `NotificationService` (`addNotification`) |
+| `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`: telas prontas de autosserviço (início, grupos, aplicações, cliente, auditoria), sempre carregadas sob demanda (`AUTO_SERVICE_SCREENS`); as classes das telas não são exportadas. `AutoServiceService` e o tipo `AutoServiceClient` são |
+| `@trismegisto/spine/audit` | A tela de Auditoria (`SpineAuditComponent`, `spine-audit`), a mesma para o painel central (`scope="admin"`) e o auto-serviço (`scope="client"`), + `SpineAuditService` e os tipos/funções puras (`AuditEvent`, `AuditQuery`, `buildAuditQuery`, `auditApiBase`…). **Exporta o componente: importe só de código lazy** |
+| `@trismegisto/spine/graphql` | `provideGraphql({ endpoints })`: um cliente Apollo nomeado por backend |
+
+## Auditoria (`@trismegisto/spine/audit`)
+
+Uma tela só para os dois públicos — o dono/membro de projeto (auto-serviço) e o administrador do argos (painel
+central). Lê `audit.events` pelo argos admin-server; só muda o escopo:
+
+| `scope` | Endpoints | Apps do filtro |
+| --- | --- | --- |
+| `client` (+ `clientId`) | `{adminApi}/auto-service/:clientId/audit/*` — o servidor recorta aos apps do projeto (`app_id` de fora → 403) | `GET /auto-service/:clientId/apps` |
+| `admin` | `{adminApi}/admin/audit/*` — todos os apps (guard `admin:audit:*`) | `GET /admin/apps` |
+
+`adminApi` vem do input `[adminApi]` ou do `SPINE_ADMIN_API` (o `provideAutoService` já fornece).
+
+```ts
+// rota lazy do app (ex.: argos admin/ui)
+component: async () => (await import('./admin-audit-page.component')).AdminAuditPageComponent,
+// …e no template da página: <spine-audit scope="admin" [adminApi]="environment.adminApi" />
+```
+
+- **No auto-serviço:** aba **Auditoria** na página de Aplicações (`import('@trismegisto/spine/audit')` só ao abrir
+  a aba) e página própria ligada a `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID` (`ad100004-…`), que aparece no menu
+  "Administração" quando o template `auto-service` do banco tiver esse router. O app não configura nada além do
+  `provideAutoService`.
+- **Conteúdo:** período rápido (1h/6h/24h/7d/30d; as datas da faixa de filtros vencem), "Atualizar" + atualização
+  automática opcional (30 s), filtros (datas, aplicação — multisseleção —, usuário, operação, método, resultado, só
+  ações do usuário, nível, permissão, tipo de ator, status HTTP, trace, ID do usuário; filtros salvos por escopo),
+  KPIs (eventos; falhas e negados clicáveis viram filtro de resultado), linha do tempo em barras CSS, **3 rankings
+  paginados no servidor** (operações, usuários e, com mais de um app, por aplicação — 5 por página, "x–y de N",
+  anterior/próxima; clicar vira filtro), tabela paginada no servidor (cursor; 25/50/100/200 por página = `limit`) e o
+  detalhe do evento num `hm-drawer` (identificador + descrição da operação, "Ver cadeia (trace)", "Filtrar a tabela
+  por este trace", aviso de `hidden_count`).
+- **Colunas:** Operação mostra só o identificador (`operation_identifier`; a descrição fica na dica da célula e no
+  detalhe); Resultado é um `hm-tag` com o texto ("Sucesso"/"Falha"/"Negado", nos 3 idiomas) na cor de status.
+- **Sem piscar:** trocar de página, de ranking ou atualizar mantém as linhas atuais à vista (esmaecidas, com
+  `hm-progress` indeterminado por cima e `aria-busy`); esqueleto só na 1ª carga. Respostas fora de ordem (página,
+  ranking, consulta ou detalhe já trocados) são descartadas por número de sequência.
+- **Estados:** carregando, vazio (com "Limpar filtros"), erro com "Tentar de novo", janela acima de 31 dias (barrada
+  antes de ir ao servidor e `range_too_large`), filtro inválido (`invalid_filter`, com a explicação do servidor) e
+  403 (texto diferente por escopo).
+- **Bundle:** o ponto `audit` exporta o componente de propósito; o `check-lazy` falha se o arquivo do ponto
+  principal ou do `auto-service` passar a importá-lo estaticamente.
+
+## Regras que o app precisa saber
+
+- **`COMPONENT_ROUTES` é sempre `multi`.** O app contribui pelo `provideShell` e pacotes plugáveis (como o
+  `provideAutoService`) pelo deles. Nunca forneça o token sem `multi: true`. Um `id` igual ao de uma tela
+  base do shell faz o `provideShell` lançar erro.
+- **Documentação de tela** (`document.load`) é markdown cru importado como texto: configure o loader
+  `".md": "text"` no `angular.json` do app. O texto vai no chunk lazy da tela.
+- **Idioma:** os textos do spine seguem `HermesI18nService.setLocale` (o idioma em si se configura com
+  `provideHermesI18n` do `@trismegisto/angular`). `provideSpineMessages({ override, catalogs })` só sobrescreve
+  textos ou acrescenta idiomas.
+- **Ícones do app** já estão cobertos pelo catálogo inteiro que o `provideUi` registra.
+- `ModalService`/`SidePanelService` abrem um componente que implementa `ModalContent` (`getResult()`,
+  `isValid?()`). Para diálogos fora do shell, o `@trismegisto/angular` tem `HermesDialogService`.
+
+## Documentação
+
+- A skill de uso para agentes (Claude Code) está no pacote `@acropole/skills`: `npx @acropole/skills`
+  (skill `trismegisto`, que cobre o spine). Ela não vai mais dentro deste pacote.
+- Componentes que o shell usa: site de documentação (`docs/website`) e o
+  [README do `@trismegisto/angular`](../angular/README.md).
+- Mudanças por versão: [`CHANGELOG.md`](./CHANGELOG.md).
+- Arquitetura: [`docs/architecture`](../../docs/architecture/README.md). Pendências do pacote:
+  [`docs/status/open-items.md`](../../docs/status/open-items.md).
+
+## Desenvolvimento do pacote
+
+O código fica em `projects/ui/` (um ponto de entrada por pasta). `npm run build` roda o `check-strings`,
+empacota com ng-packagr em `dist/ui/` (o que vai publicado) e copia este README para lá
+(`scripts/copy-readme.mjs`); `npm run check-strings` sozinho confere que
+nenhum texto de interface está fora do catálogo. O build termina com `scripts/check-lazy.mjs`, que falha se uma
+tela carregada por `import()` (as do auto-serviço) acabar colada no arquivo do ponto de entrada, ou se o ponto
+principal/`auto-service` importar `@trismegisto/spine/audit` estaticamente — acontece quando
+ela é exportada no `public-api.ts` (o rollup troca o `import()` por `Promise.resolve()` e a tela vai para o bundle
+inicial do app).
+
+O catálogo de API da skill (`spine-api.md`) é gerado pelo `@acropole/skills`, que lê o `projects/ui/` deste pacote
+(rode `npm run sync -- --trismegisto <pasta do trismegisto>` em `packages/acropole`).