@acropole/skills 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +14 -11
  2. package/agents/revisor-orfeu.md +2 -1
  3. package/bin/install.js +41 -9
  4. package/package.json +1 -1
  5. package/skills/acropole/SKILL.md +2 -2
  6. package/skills/acropole/references/fluxos/atualizar-libs-2026-10.md +53 -17
  7. package/skills/angular/SKILL.md +4 -3
  8. package/skills/angular/references/armadilhas.md +3 -3
  9. package/skills/angular/references/dados.md +3 -3
  10. package/skills/angular/references/estrutura.md +6 -5
  11. package/skills/angular/references/features.md +5 -5
  12. package/skills/angular/references/testes-build.md +1 -1
  13. package/skills/auto-servico/SKILL.md +18 -14
  14. package/skills/auto-servico/references/roteiros.md +1 -1
  15. package/skills/auto-servico/references/tools.md +1 -1
  16. package/skills/express/references/dados.md +4 -1
  17. package/skills/express/references/estrutura.md +2 -1
  18. package/skills/fastapi/references/banco.md +6 -2
  19. package/skills/fastapi/references/estrutura.md +1 -1
  20. package/skills/hefesto/SKILL.md +13 -6
  21. package/skills/hefesto/references/diagnostico.md +1 -0
  22. package/skills/hefesto/references/mcp-roteiros.md +48 -7
  23. package/skills/orfeu/SKILL.md +43 -13
  24. package/skills/orfeu/references/angular-api.md +39 -13
  25. package/skills/orfeu/references/angular-armadilhas.md +18 -1
  26. package/skills/orfeu/references/angular-recipes.md +25 -12
  27. package/skills/orfeu/references/angular.md +37 -15
  28. package/skills/orfeu/references/diferencas.md +17 -8
  29. package/skills/orfeu/references/node-api.md +41 -9
  30. package/skills/orfeu/references/node-armadilhas.md +16 -2
  31. package/skills/orfeu/references/node-recipes.md +13 -4
  32. package/skills/orfeu/references/node.md +31 -12
  33. package/skills/orfeu/references/python-api.md +41 -16
  34. package/skills/orfeu/references/python-recipes.md +13 -9
  35. package/skills/orfeu/references/python.md +33 -12
  36. package/skills/orfeu/references/react.md +133 -0
  37. package/skills/orquestracao/SKILL.md +3 -1
  38. package/skills/orquestracao/scripts/coord.sh +10 -2
  39. package/skills/trismegisto/SKILL.md +89 -35
  40. package/skills/trismegisto/references/angular-api.md +4548 -344
  41. package/skills/trismegisto/references/angular-exports.md +8275 -2579
  42. package/skills/trismegisto/references/angular-recipes.md +327 -6
  43. package/skills/trismegisto/references/angular-types.md +92 -0
  44. package/skills/trismegisto/references/angular.md +96 -16
  45. package/skills/trismegisto/references/catalogo/icones.json +7 -0
  46. package/skills/trismegisto/references/catalogo/imports.json +1627 -0
  47. package/skills/trismegisto/references/catalogo/seletores.json +12110 -3426
  48. package/skills/trismegisto/references/catalogo/tokens.json +114 -0
  49. package/skills/trismegisto/references/react-api.md +16864 -0
  50. package/skills/trismegisto/references/react.md +237 -0
  51. package/skills/trismegisto/references/spine-api.md +5904 -1361
  52. package/skills/trismegisto/references/spine-recipes.md +140 -46
  53. package/skills/trismegisto/references/spine.md +121 -49
  54. package/skills/trismegisto/scripts/checar.mjs +66 -1
@@ -1,6 +1,8 @@
1
- # Receitas — @trismegisto/spine 2.0.1
1
+ # Receitas — spine (casca Angular, 3.4.0)
2
2
 
3
- Padrões prontos para um app que usa o spine. Todos os componentes são standalone (importe as classes no
3
+ Padrões prontos para um app Angular que usa o spine. Componentes, serviços e providers vêm da casca
4
+ (`@trismegisto/angular/spine[/sub]`); valores sem framework (`GraphqlEnvelopeError`, `AlertType`, `applyRuntimeEnvironment`…), do
5
+ núcleo `@trismegisto/spine` (`spine.md` §2). Receitas em React: `react.md` §5. Todos os componentes são standalone (importe as classes no
4
6
  `imports`). Os componentes `hm-*` usados no conteúdo das telas são do `@trismegisto/angular` — a API deles está
5
7
  em `angular.md` e `angular-api.md`. Nomes como `MeuApp`, `principal`,
6
8
  `Equipes` e os UUIDs são exemplos: troque pelos do seu app.
@@ -17,7 +19,7 @@ Detalhes de `angular.json`, scripts e Docker: skill **angular** (`references/est
17
19
  `postLogoutRedirectUri` são sempre derivados):
18
20
 
19
21
  ```ts
20
- import type { GraphqlEndpoint } from '@trismegisto/spine/graphql';
22
+ import type { GraphqlEndpoint } from '@trismegisto/angular/spine/graphql';
21
23
 
22
24
  export const environment = {
23
25
  production: false, // true vem do config.json de homol/prod
@@ -76,10 +78,10 @@ import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
76
78
  import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
77
79
  import { provideRouter } from '@angular/router';
78
80
  import { provideAuth } from '@orfeu/angular/core';
79
- import { provideUi } from '@trismegisto/spine';
80
- import { APP_ROUTES, provideShell } from '@trismegisto/spine/shell';
81
- import { provideAutoService } from '@trismegisto/spine/auto-service';
82
- import { provideGraphql } from '@trismegisto/spine/graphql';
81
+ import { provideUi } from '@trismegisto/angular/spine';
82
+ import { APP_ROUTES, provideShell } from '@trismegisto/angular/spine/shell';
83
+ import { provideAutoService } from '@trismegisto/angular/spine/auto-service';
84
+ import { provideGraphql } from '@trismegisto/angular/spine/graphql';
83
85
  import { components } from './features/features.routes';
84
86
  import { environment } from '../environments/environment';
85
87
  import packageInfo from '../../package.json';
@@ -149,8 +151,8 @@ Arquivos de marca: `src/assets/images/logo.svg` (legível sobre o cabeçalho esc
149
151
  ```ts
150
152
  import { Routes } from '@angular/router';
151
153
  import { PrivateGuard } from '@orfeu/angular/core';
152
- import { LayoutComponent } from '@trismegisto/spine/layout';
153
- import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/spine/shell';
154
+ import { LayoutComponent } from '@trismegisto/angular/spine/layout';
155
+ import { PRIVATE_ROUTES, PUBLIC_ROUTES } from '@trismegisto/angular/spine/shell';
154
156
 
155
157
  export const ROUTES: Routes = [
156
158
  { path: '', pathMatch: 'full', loadComponent: () => import('./public/landing.component').then((m) => m.LandingComponent) },
@@ -192,7 +194,7 @@ export class EquipesComponent {}
192
194
 
193
195
  ```ts
194
196
  // src/app/features/features.routes.ts
195
- import { ComponentRoute } from '@trismegisto/spine/routing';
197
+ import { ComponentRoute } from '@trismegisto/angular/spine/routing';
196
198
 
197
199
  export const components: ComponentRoute[] = [
198
200
  {
@@ -246,7 +248,7 @@ export class EquipesService {
246
248
  ```ts
247
249
  // equipes.service.ts — ListEquipesDocument/CriarEquipeDocument: TypedDocumentNode gerados pelo codegen
248
250
  import { Injectable } from '@angular/core';
249
- import { injectGraphqlClient, unwrap } from '@trismegisto/spine/graphql';
251
+ import { injectGraphqlClient, unwrap } from '@trismegisto/angular/spine/graphql';
250
252
  import { CriarEquipeDocument, ListEquipesDocument } from '../../graphql/generated';
251
253
 
252
254
  @Injectable({ providedIn: 'root' })
@@ -273,7 +275,7 @@ export class EquipesGqlService {
273
275
  // equipes.component.ts
274
276
  import { ChangeDetectionStrategy, Component, computed, inject, resource } from '@angular/core';
275
277
  import { AlertComponent, ButtonComponent, DataGridColumn, DataGridComponent, SkeletonComponent } from '@trismegisto/angular';
276
- import { GraphqlEnvelopeError } from '@trismegisto/spine/graphql';
278
+ import { GraphqlEnvelopeError } from '@trismegisto/spine/graphql'; // valor do núcleo (classe, para instanceof)
277
279
  import { EquipesGqlService } from './equipes.service';
278
280
 
279
281
  type Equipe = { id: string; nome: string; membros: number };
@@ -323,7 +325,7 @@ Os textos fixos deste exemplo estão em português por brevidade; num app com i1
323
325
  import { DestroyRef, Injectable, inject, signal } from '@angular/core';
324
326
  import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
325
327
  import { filter } from 'rxjs';
326
- import { injectGraphqlClient, unwrap, wsReconnected$ } from '@trismegisto/spine/graphql';
328
+ import { injectGraphqlClient, unwrap, wsReconnected$ } from '@trismegisto/angular/spine/graphql';
327
329
  import { EquipeAlteradaDocument, ListEquipesDocument } from '../../graphql/generated';
328
330
 
329
331
  @Injectable()
@@ -356,7 +358,7 @@ Conteúdo (o mesmo serve aos dois):
356
358
  ```ts
357
359
  import { ChangeDetectionStrategy, Component, OnInit, input, signal } from '@angular/core';
358
360
  import { InputComponent } from '@trismegisto/angular';
359
- import { ModalContent } from '@trismegisto/spine/modal';
361
+ import { ModalContent } from '@trismegisto/angular/spine/modal';
360
362
 
361
363
  @Component({
362
364
  selector: 'app-renomear-equipe',
@@ -378,8 +380,8 @@ Abrindo:
378
380
  ```ts
379
381
  import { inject } from '@angular/core';
380
382
  import { HermesLoadingState } from '@trismegisto/angular';
381
- import { ModalService } from '@trismegisto/spine/modal';
382
- import { SidePanelService } from '@trismegisto/spine/side-panel';
383
+ import { ModalService } from '@trismegisto/angular/spine/modal';
384
+ import { SidePanelService } from '@trismegisto/angular/spine/side-panel';
383
385
 
384
386
  private readonly modal = inject(ModalService);
385
387
  private readonly painel = inject(SidePanelService);
@@ -411,7 +413,8 @@ Confirmação simples ("Excluir?") não precisa do spine: `HermesDialogService.c
411
413
 
412
414
  ```ts
413
415
  import { inject } from '@angular/core';
414
- import { AlertType, NotificationService } from '@trismegisto/spine/notification';
416
+ import { NotificationService } from '@trismegisto/angular/spine/notification';
417
+ import { AlertType } from '@trismegisto/spine/notification'; // enum do núcleo
415
418
 
416
419
  private readonly toasts = inject(NotificationService);
417
420
 
@@ -425,12 +428,12 @@ Não duplique toast do GraphQL: mutation que falha (ou devolve `message`) já av
425
428
  ## 9. Auditoria numa tela (sempre lazy)
426
429
 
427
430
  Uma tela que só embrulha a auditoria. Como toda tela registrada em `ComponentRoute.load`, ela já é carregada
428
- por `import()` — então o import estático de `@trismegisto/spine/audit` **dentro dela** é seguro:
431
+ por `import()` — então o import estático de `@trismegisto/angular/spine/audit` **dentro dela** é seguro:
429
432
 
430
433
  ```ts
431
434
  // src/app/features/auditoria/auditoria.component.ts
432
435
  import { ChangeDetectionStrategy, Component } from '@angular/core';
433
- import { SpineAuditComponent } from '@trismegisto/spine/audit';
436
+ import { SpineAuditComponent } from '@trismegisto/angular/spine/audit';
434
437
  import { environment } from '../../../environments/environment';
435
438
 
436
439
  @Component({
@@ -461,7 +464,7 @@ Dentro de uma tela que **não** é só auditoria (ex.: uma aba), adie com `@defe
461
464
  }
462
465
  ```
463
466
 
464
- Nunca importe `@trismegisto/spine/audit` em `app.config.ts`, serviço `providedIn: 'root'` usado no boot ou
467
+ Nunca importe `@trismegisto/angular/spine/audit` em `app.config.ts`, serviço `providedIn: 'root'` usado no boot ou
465
468
  componente do bundle inicial. Com `provideAutoService`, a auditoria do projeto já existe (aba em Aplicações e
466
469
  página própria) — não crie outra.
467
470
 
@@ -469,7 +472,7 @@ página própria) — não crie outra.
469
472
 
470
473
  ```ts
471
474
  // app.config.ts
472
- import { provideSettingsSection } from '@trismegisto/spine/layout';
475
+ import { provideSettingsSection } from '@trismegisto/angular/spine/layout';
473
476
 
474
477
  provideSettingsSection({
475
478
  key: 'resumos', // também abre por ?settings=resumos
@@ -501,7 +504,7 @@ export class ResumosSettingsComponent {
501
504
  ```
502
505
 
503
506
  As seções do app aparecem depois das do spine e antes de "Sobre". Não repita as chaves de `SPINE_SETTINGS_KEYS`
504
- (`aparencia`, `acessibilidade`, `regiao`, `atalhos`, `ajuda`, `notificacoes`, `dados`, `conta`, `mfa`, `sessoes`,
507
+ (`aparencia`, `acessibilidade`, `regiao`, `atalhos`, `ajuda`, `notificacoes`, `dados`, `conta`, `mfa`, `sessoes`, `grupos`,
505
508
  `sobre`; `seguranca` é alias antigo de `mfa`). Abrir por código: `inject(SpineSettingsService).open('resumos')`.
506
509
 
507
510
  Antes de criar seção própria, veja se o spine já oferece (`SpineConfig.features`, `references/spine.md` §3.2):
@@ -510,31 +513,19 @@ inatividade, tela inicial, crachá padrão, atividade da conta e agente de IA ta
510
513
 
511
514
  ## 11. Novidades da versão
512
515
 
513
- ```ts
514
- import { provideSpineNews } from '@trismegisto/spine';
515
-
516
- provideSpineNews([
517
- {
518
- id: 'equipes-2026-10', // trocar o id faz reaparecer para todo mundo
519
- until: '2026-12-31', // opcional: some depois desta data
520
- slides: [
521
- {
522
- title: 'Equipes',
523
- text: 'Agora dá para organizar pessoas em equipes.',
524
- illustration: { icon: 'users', satellites: [{ icon: 'user', label: 'Membros' }] },
525
- },
526
- ],
527
- },
528
- ]),
529
- ```
530
-
531
- Abre sozinha uma vez por navegador (depois do tour) e fica no menu do perfil enquanto vigente.
516
+ Não ficam no código: quem administra o app cadastra no Argos (tela **Novidades** do auto-serviço, na raiz do menu, ou
517
+ a aba Novidades do cliente no painel central). Três tipos: **informativo** (só texto), **implementação** (abertura e a
518
+ lista "O que mudou") e **alteração** (antes e agora, lado a lado). Mais título, resumo, publicação (no futuro =
519
+ agendada), validade e público (grupos de acesso; vazio = todos). O spine lê de `argos-admin /me/news` com
520
+ `SPINE_ADMIN_API` (o `provideAutoService` já fornece): avisa uma vez por novidade na entrada, mostra "Novidades (N)" no
521
+ menu do perfil e o card do Início, e o painel lista por mês, com busca, "Não lidas" e "Favoritas" (no navegador).
522
+ Abrir por código: `inject(SpineNewsService).showAll()`.
532
523
 
533
524
  ## 12. Marca em componente
534
525
 
535
526
  ```ts
536
527
  import { ChangeDetectionStrategy, Component } from '@angular/core';
537
- import { SPINE_BRAND } from '@trismegisto/spine/layout';
528
+ import { SPINE_BRAND } from '@trismegisto/angular/spine/layout';
538
529
 
539
530
  @Component({
540
531
  selector: 'app-marca',
@@ -554,7 +545,7 @@ Tem prioridade sobre `logo`. Fica dentro do link da marca: sem link/botão dentr
554
545
 
555
546
  ```ts
556
547
  import { provideHermesI18n } from '@trismegisto/angular';
557
- import { provideSpineMessages } from '@trismegisto/spine';
548
+ import { provideSpineMessages } from '@trismegisto/angular/spine';
558
549
 
559
550
  providers: [
560
551
  provideHermesI18n({ locale: 'en' }), // idioma inicial da lib E do spine
@@ -568,14 +559,33 @@ Trocar em tempo de execução (lib + spine juntos): `inject(HermesI18nService).s
568
559
  `inject(SpinePreferencesService).setLanguage('es')` para também salvar a escolha da pessoa. Ler um texto do
569
560
  spine em código: `inject(SPINE_MESSAGES).header.search`.
570
561
 
571
- ## 14. Testes de tela
562
+ ## 14. Tela com formulário: alterações não salvas e skip link
563
+
564
+ ```ts
565
+ // app.config.ts
566
+ provideUi({ clientId, features: { skipLink: true, unsavedChanges: true } }),
567
+ ```
568
+ ```ts
569
+ import { registerSpineUnsavedChanges } from '@trismegisto/angular/spine/layout';
570
+
571
+ export class PedidoPage {
572
+ readonly form = new FormGroup({ /* … */ });
573
+ readonly #alteracoes = registerSpineUnsavedChanges(() => this.form.dirty); // presa à aba desta tela
574
+ salvar(): void { /* … grava; depois */ this.form.markAsPristine(); }
575
+ }
576
+ ```
577
+ No spine, use `registerSpineUnsavedChanges` (não o `hermesUnsavedChangesGuard` nas rotas): quem fecha a tela é a aba
578
+ do workspace, não a navegação. O resto do formulário segue `angular-recipes.md` §41 (resumo de erros, indicador de
579
+ salvamento, anúncio).
580
+
581
+ ## 15. Testes de tela
572
582
 
573
583
  As telas não dependem do layout: teste-as isoladas, trocando os serviços do spine por dublês.
574
584
 
575
585
  ```ts
576
586
  import { TestBed } from '@angular/core/testing';
577
- import { NotificationService } from '@trismegisto/spine/notification';
578
- import { ModalService } from '@trismegisto/spine/modal';
587
+ import { NotificationService } from '@trismegisto/angular/spine/notification';
588
+ import { ModalService } from '@trismegisto/angular/spine/modal';
579
589
  import { of } from 'rxjs';
580
590
  import { EquipesComponent } from './equipes.component';
581
591
  import { EquipesGqlService } from './equipes.service';
@@ -613,3 +623,87 @@ it('ids UUID únicos (sem diferenciar maiúsculas) e todo load() resolve para co
613
623
  ```
614
624
 
615
625
  O `import()` quebrado não falha o build (a tela é lazy); só aparece em runtime como "tela não publicada".
626
+
627
+ ## 16. Busca do cabeçalho com provedores, menu sem módulos e overlays presos ao conteúdo
628
+
629
+ A paleta do cabeçalho (`Ctrl K`, `/`) procura as telas e, com provedores, os itens do app. O app só diz o que procurar
630
+ e para onde o resultado leva; o Spine espera a digitação, cancela o pedido anterior, aplica tempo-limite, ordena pela
631
+ relevância (telas por último) e mostra "Ver mais".
632
+
633
+ ```ts
634
+ // app.config.ts
635
+ import { provideSpineSearch, provideUi } from '@trismegisto/angular/spine';
636
+ import type { SpineConfig, SpineSearchProvider } from '@trismegisto/spine';
637
+
638
+ export const spineConfig: SpineConfig = {
639
+ clientId: environment.authorizationServer.clientId,
640
+ navigation: { modules: false }, // menu numa árvore só, sem lista de módulos
641
+ overlays: { scope: 'content' }, // hm-drawer/hm-modal das telas presos à área de conteúdo (um palco por aba)
642
+ };
643
+
644
+ function pedidosProviders(): SpineSearchProvider[] {
645
+ const api = inject(PedidosService);
646
+ return [{
647
+ id: 'vendas.pedidos', label: 'Pedidos', icon: 'cart', prefixes: ['pedido'],
648
+ // Devolva até `limit + 1`: o item a mais faz aparecer o "Ver mais".
649
+ search: async (termo, { signal, limit }) => (await api.buscar({ q: termo, limit }, signal)).map((p) => ({
650
+ id: p.id, label: `Pedido ${p.numero}`, description: p.cliente, score: p.relevancia,
651
+ target: { route: '/vendas/pedidos', params: { pedido: p.id } },
652
+ })),
653
+ }];
654
+ }
655
+
656
+ providers: [provideUi(spineConfig), provideSpineSearch(pedidosProviders)];
657
+ ```
658
+
659
+ A tela de destino abre o item pelos parâmetros da própria aba (funciona também com a aba já aberta):
660
+
661
+ ```ts
662
+ private readonly tab = inject(SPINE_TAB, { optional: true });
663
+ constructor() {
664
+ effect(() => {
665
+ const id = this.tab?.params()['pedido'];
666
+ if (id) untracked(() => this.abrirPedido(id));
667
+ });
668
+ }
669
+ ```
670
+
671
+ - Sem `requires`, o provedor vale para todos; com `requires: { route: '/vendas/pedidos' }`, só para quem alcança a tela;
672
+ com `requires: { badges: ['Operador'] }`, só nesse crachá.
673
+ - Cache dentro do provedor (o catálogo, a resposta reaproveitada no "Ver mais") vai por crachá (`badge` do contexto) e
674
+ com prazo curto: cada nível de acesso enxerga outro recorte, e a permissão pode mudar com o app aberto.
675
+ - `hm-drawer`/`hm-modal` aceitam `scope="viewport"` para cobrir a página inteira mesmo com `overlays.scope = 'content'`.
676
+ Com o drawer preso à área, largura e limites de arraste se medem pela camada dele (`.hm-drawer`), não pela janela: o
677
+ menu lateral fixo aberto deixa a área bem menor que a janela.
678
+
679
+ ## 17. Trilha da tela na barra da página e modo apresentação
680
+
681
+ Tela com navegação interna pelos parâmetros do endereço (central › cooperativa › PA; pasta › subpasta) continua a trilha
682
+ do Spine em vez de desenhar a própria: "Módulo › Painel › Central 1003 › PA 12".
683
+
684
+ ```ts
685
+ import { SPINE_TAB, hasSpinePageTrail, spinePageTrail } from '@trismegisto/angular/spine/layout';
686
+
687
+ export class PainelComponent {
688
+ private readonly tab = inject(SPINE_TAB, { optional: true });
689
+ /** No shell a trilha vai para a barra; fora dele (teste, tela sozinha), a tela mostra a dela. */
690
+ protected readonly trilhaNaBarra = hasSpinePageTrail();
691
+
692
+ constructor() {
693
+ spinePageTrail(() => this.niveis().map((n, i, todos) => i === todos.length - 1
694
+ ? { label: n.rotulo } // onde a pessoa está: sem link
695
+ : { label: n.rotulo, params: { central: n.central, cooperativa: n.cooperativa ?? null } })); // null tira
696
+ // A tela segue o endereço da aba (o clique num degrau, o link, a busca do cabeçalho):
697
+ effect(() => {
698
+ const q = this.tab?.params() ?? {};
699
+ untracked(() => this.irPara(q['central'] ? { central: q['central'], cooperativa: q['cooperativa'] } : this.inicial()));
700
+ });
701
+ }
702
+ }
703
+ ```
704
+
705
+ - Cada degrau aplica os `params` sobre a query atual da aba (os filtros ficam). O nome da tela vira link para ela sem
706
+ parâmetros: trate o endereço sem nível como "voltar ao início" da tela.
707
+ - Modo apresentação: o botão "Apresentar em tela cheia" da barra põe a aba em `?present=1` (nome reservado pelo Spine) e
708
+ mostra só o conteúdo da tela, cobrindo a janela. Para uma TV de monitoramento, abra o link com `present=1` (o navegador
709
+ em modo quiosque cuida da tela cheia). `SpinePresentationService.active()` diz se o painel focado está apresentando.