@acropole/skills 1.6.0 → 1.7.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.
@@ -18,10 +18,12 @@ Dockerfile está na skill **docker**; aqui fica o que o Hefesto espera dele e do
18
18
 
19
19
  | Arg | Quem manda | Uso |
20
20
  | --- | --- | --- |
21
- | `CONFIGURATION` | Hefesto, só para `site` | nome do ambiente → `ng build --configuration $CONFIGURATION` |
21
+ | `CONFIGURATION` | Hefesto, sempre `production` (qualquer tipo e ambiente) | legado: o Dockerfile novo nem declara; o Angular builda sempre `--configuration production` |
22
22
 
23
- - Declare o `ARG` **depois** da instalação de dependências (um ARG entra no ambiente de todos os
24
- `RUN` seguintes; declarado antes, cada ambiente invalida o cache do `npm ci`).
23
+ - **O ambiente não entra no build.** A imagem é uma por versão e serve todos os ambientes; o front
24
+ escolhe o ambiente em runtime (`config.json`, ver "Site" e "Front servido pelo próprio Node").
25
+ - Se precisar de um `ARG`, declare **depois** da instalação de dependências (um ARG entra no ambiente
26
+ de todos os `RUN` seguintes; declarado antes, cada valor invalida o cache do `npm ci`).
25
27
  - O Hefesto pode repassar outros build args que o Dockerfile não declara; ARG não declarado é
26
28
  ignorado (só aviso). Não declare ARG para credencial: o valor fica no histórico da imagem.
27
29
  - Nada de URL de serviço ou segredo em build arg de service: isso é configuração de **runtime**.
@@ -47,10 +49,19 @@ Prefixo por variável, com o padrão de cada stack:
47
49
  | FastAPI | `root_path` ou `APIRouter(prefix=...)` vindo de settings (ver **fastapi**) |
48
50
  | SPA servida pelo próprio Node | base path da UI (`UI_BASE_PATH`) igual ao `baseHref` do build |
49
51
 
52
+ ### Front servido pelo próprio Node (service com UI)
53
+
54
+ O container recebe `APP_ENV=<ambiente>` do Hefesto (nome cadastrado em minúsculas; se a app cadastrou
55
+ `APP_ENV`, a dela vence). O servidor lê `<dist da UI>/brand/config/${APP_ENV}.json` **na subida**, valida
56
+ (`^[a-z0-9-]+$`, arquivo existe, é objeto JSON) e serve `{UI_BASE_PATH}/config.json` com `no-store`,
57
+ registrado **antes** do `express.static`. Em produção, problema aqui derruba a subida (o rollout descarta a
58
+ versão e a atual continua); fora dela, só avisa e a rota responde 404.
59
+
50
60
  ### Variáveis de ambiente
51
61
 
52
62
  Cadastre no Hefesto, por ambiente, tudo que o app lê do ambiente: banco, Redis, URLs de outros
53
- serviços, identidade no Argos (realm e app — ver **orfeu**), nível de log, `APP_ENV`/`NODE_ENV`.
63
+ serviços, identidade no Argos (realm e app — ver **orfeu**), nível de log, `NODE_ENV`. `APP_ENV` o
64
+ Hefesto já injeta com o nome do ambiente: cadastre só se o app precisar de outro valor.
54
65
 
55
66
  - Os arquivos `.env.<ambiente>` do repo são para rodar local; a imagem não os leva. Se o app carrega
56
67
  `.env.<APP_ENV>` com `load_dotenv`, o arquivo não existe no container e o valor tem que vir do
@@ -86,9 +97,14 @@ compatível com o schema da versão anterior — é o que permite rollback.
86
97
  ## Site (estático)
87
98
 
88
99
  - Estágio `site` (nome exato) `FROM scratch`, com o build em **`/dist`** e `CMD ["unused"]`.
89
- - Uma configuração no `angular.json` **para cada nome de ambiente** do Hefesto, com:
100
+ - **Uma imagem para todos os ambientes**: `ng build --configuration production` sempre, com:
90
101
  - `baseHref` = path do agent (com barra final: `/meu-app/`); agent na raiz = `/`;
91
- - endpoints do ambiente (`environment.<amb>.ts`) — o site não recebe variável de runtime.
102
+ - `src/brand/config/<ambiente>.json` **para cada nome de ambiente** do Hefesto (minúsculas), publicado
103
+ em `brand/config/` — só o que muda no ambiente (endpoints, `production`);
104
+ - `loadRuntimeConfig` no `main.ts` (ver **angular**) e nenhum `config.json` no `/dist`.
105
+ - No deploy, o Hefesto manda `config_env=<ambiente>` e o Talos (≥ 1.1.13) copia
106
+ `brand/config/<ambiente>.json` para `config.json`. Arquivo ausente ou inválido = `422` e a versão
107
+ anterior continua. O site não recebe variável de runtime: o `config.json` é a configuração dele.
92
108
  - `site_mode = spa` para app com rotas no cliente (deep link e F5 funcionam); `static` só para HTML
93
109
  puro.
94
110
  - Mesmo build servindo dois paths diferentes não funciona: `baseHref` é fixado no build.
@@ -1,7 +1,7 @@
1
1
  # Catálogo de API — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 2.1.2, a cada `npm run sync` do @acropole/skills.
4
- > Gerado do código-fonte do `@trismegisto/angular` 2.1.2. Confira a versão instalada no `package.json` do pacote em `node_modules`.
3
+ > **Gerado** a partir do código-fonte da versão 3.1.0, a cada `npm run sync` do @acropole/skills.
4
+ > Gerado do código-fonte do `@trismegisto/angular` 3.1.0. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
5
 
6
6
  Legenda: `input` = `[prop]`; `model` = two-way `[(prop)]`; `output` = `(evento)`.
7
7
  Slots são os seletores de `<ng-content>`: projete com o atributo (ex.: `<div footer>`).
@@ -1,6 +1,6 @@
1
1
  # Exports por ponto de import — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 2.1.2, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
3
+ > **Gerado** a partir do código-fonte da versão 3.1.0, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
4
4
 
5
5
  Tudo que cada `@trismegisto/angular/<ponto>` exporta: serviços (com os membros públicos), funções, constantes,
6
6
  tokens de injeção e tipos (com a declaração). Componentes, diretivas e pipes aparecem só pelo nome — inputs,
@@ -1,6 +1,6 @@
1
1
  # Catálogo de API — @trismegisto/spine
2
2
 
3
- > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 2.1.2, a cada `npm run sync` do @acropole/skills.
3
+ > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 3.1.0, a cada `npm run sync` do @acropole/skills.
4
4
  > Gerado do código-fonte do `@trismegisto/spine`. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
5
 
6
6
  Uma seção por ponto de entrada (o `import` exato). Dentro dela: componentes (seletor, inputs/outputs),
@@ -100,7 +100,7 @@ Chaves de `localStorage` do shell por usuário: `<clientId>_<lista>_<sub>`, com
100
100
  - `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…
101
101
  - `function resolveSpineLogo(logo: SpineLogoConfig | false | null | undefined): SpineLogoSources | null` — Normaliza `SpineConfig.logo`: omitido → convenção; `false`/vazio → sem imagem (`null`).
102
102
  - `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…
103
- - `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…
103
+ - `function applyRuntimeEnvironment(environment: RuntimeEnvironmentShape): RuntimeEnvironmentInfo` — Ajusta o `environment` ao lugar onde o app está rodando — chamar no `main.ts`, ANTES do `bootstrapApplication` e DEPOIS do `loadRuntimeConfig` (que traz o `config.json` do deploy: o que ele definir explicitamente não é derivado aqui). Antes cada app tinha a s…
104
104
  - `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.
105
105
  - `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…
106
106
  - `function provideSpineMessages(config: SpineI18nConfig): Provider` — Sobrescreve textos do spine e/ou acrescenta idiomas. O idioma em si vem de `provideHermesI18n`.
@@ -377,7 +377,7 @@ interface RuntimeEnvironmentShape {
377
377
  interface RuntimeEnvironmentInfo {
378
378
  /** `window.location.origin`. */
379
379
  readonly origin: string;
380
- /** Prefixo do app (base href sem a barra final), ex.: `/meu-app`. Vazio na raiz. */
380
+ /** Prefixo do app (base href sem a barra final), ex.: `/app-exemplo`. Vazio na raiz. */
381
381
  readonly basePath: string;
382
382
  /** Sem porta na URL: o app está atrás do proxy reverso, não na porta direta do container. */
383
383
  readonly behindProxy: boolean;
@@ -452,6 +452,11 @@ interface SpineI18nConfig {
452
452
  }
453
453
  ```
454
454
 
455
+ ### Reexportados
456
+
457
+ - `loadRuntimeConfig` — o mesmo símbolo de `@trismegisto/primitives`
458
+ - `LoadRuntimeConfigOptions` — o mesmo símbolo de `@trismegisto/primitives`
459
+
455
460
  ## `@trismegisto/spine/audit`
456
461
 
457
462
  @trismegisto/spine/audit — as telas de auditoria do argos admin-server, as mesmas para o painel central (`scope="admin"`) e para o auto-serviço (`scope="client"` + `clientId`): Ações (`SpineAuditComponent`, leitura de `audit.events`) e Tentativas de login (`SpineLoginAttemptsComponent`, leitura de `auth.auth_attempts`).
@@ -1091,7 +1096,7 @@ interface AutoServiceGroupType { id: string; name: string; level: number; assign
1091
1096
  Corpo de `POST /groups` (o projeto é sempre o do client).
1092
1097
 
1093
1098
  ```ts
1094
- interface AutoServiceGroupCreate { name: string; type_id: string; description?: string }
1099
+ interface AutoServiceGroupCreate { group_id?: string; name: string; type_id: string; description?: string }
1095
1100
  ```
1096
1101
 
1097
1102
  #### `AutoServiceGroupUpdate` (interface)
@@ -1209,7 +1214,7 @@ interface GraphqlCallOptions {
1209
1214
 
1210
1215
  #### `GraphqlClient` (interface)
1211
1216
 
1212
- 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); }
1217
+ 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('main'); async listTeams() { return unwrap((await this.gql.query(ListTeamsDocument)).teams); }
1213
1218
 
1214
1219
  ```ts
1215
1220
  interface GraphqlClient {
@@ -1258,7 +1263,7 @@ _Sem inputs/outputs._
1258
1263
 
1259
1264
  #### `spine-app-launcher` — `AppLauncherComponent`
1260
1265
 
1261
- 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).
1266
+ Seletor de aplicações do realm: um `hm-menu-button` próprio, só com o ícone de grade, que abre a lista das aplicações num `hm-menu` dele (o mesmo componente — e o mesmo visual — do menu do perfil, mas um menu à parte; teclado, foco e `role="menu"` vêm do `hm-menu`). Escolher um item abre a aplicação em nova aba, sem `opener`.
1262
1267
 
1263
1268
  _Sem inputs/outputs._
1264
1269
 
@@ -7,40 +7,66 @@ em `angular.md` e `angular-api.md`. Nomes como `MeuApp`, `principal`,
7
7
 
8
8
  ## 1. Bootstrap completo
9
9
 
10
- `src/environments/environment.ts` (valores `CHANGE_ME` são derivados em tempo de execução por
11
- `applyRuntimeEnvironment` quando o app está atrás de proxy, sem porta na URL):
10
+ Imagem única (desde a 3.1.0): um build `production` serve todos os ambientes. O `environment.ts` é **um só**
11
+ (o que não muda + URLs vazias); o que varia por ambiente fica em `src/brand/config/<ambiente>.json` e chega em
12
+ runtime como `config.json` (o deploy copia o do ambiente; no `ng serve`, `scripts/use-config.mjs <amb>`).
13
+ Detalhes de `angular.json`, scripts e Docker: skill **angular** (`references/estrutura.md`).
14
+
15
+ `src/environments/environment.ts` (URLs vazias são derivadas em tempo de execução por
16
+ `applyRuntimeEnvironment` quando o app está atrás de proxy, sem porta na URL; `redirectUrl` e
17
+ `postLogoutRedirectUri` são sempre derivados):
12
18
 
13
19
  ```ts
14
20
  import type { GraphqlEndpoint } from '@trismegisto/spine/graphql';
15
21
 
16
22
  export const environment = {
17
- production: false,
18
- adminApi: 'https://auth.exemplo.com/argos/admin/api',
23
+ production: false, // true vem do config.json de homol/prod
24
+ adminApi: '',
19
25
  authorizationServer: {
20
- authority: 'https://auth.exemplo.com/argos',
26
+ authority: '',
21
27
  realmId: '<realmId do app no Argos>',
22
28
  clientId: '<clientId do app no Argos>',
23
- redirectUrl: 'CHANGE_ME', // derivado: <origem><base href>/callback
24
- postLogoutRedirectUri: 'CHANGE_ME', // derivado: <origem><base href>/logoff
29
+ redirectUrl: '', // derivado: <origem><base href>/callback
30
+ postLogoutRedirectUri: '', // derivado: <origem><base href>/logoff
25
31
  scope: 'openid profile email offline_access',
26
32
  },
27
33
  graphql: {
28
- principal: { namedClient: 'principal', http: 'CHANGE_ME', ws: 'CHANGE_ME' },
34
+ principal: { namedClient: 'principal', http: '', ws: '' },
29
35
  } satisfies Record<string, GraphqlEndpoint>,
30
36
  };
31
37
  ```
32
38
 
39
+ `src/brand/config/homol.json` (só o que muda; mesclado chave a chave, arrays e valores simples substituem):
40
+
41
+ ```json
42
+ {
43
+ "production": true,
44
+ "adminApi": "https://homol.exemplo.com/argos/admin/api",
45
+ "authorizationServer": { "authority": "https://homol.exemplo.com/argos" }
46
+ }
47
+ ```
48
+
33
49
  `src/main.ts`:
34
50
 
35
51
  ```ts
52
+ import { isDevMode } from '@angular/core';
36
53
  import { bootstrapApplication } from '@angular/platform-browser';
37
- import { applyRuntimeEnvironment } from '@trismegisto/spine';
38
- import { AppComponent } from './app/app.component';
39
- import { appConfig } from './app/app.config';
54
+ import { applyRuntimeEnvironment, loadRuntimeConfig } from '@trismegisto/spine';
40
55
  import { environment } from './environments/environment';
41
56
 
42
- applyRuntimeEnvironment(environment);
43
- bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
57
+ // Sem top-level await (Zone.js): encadeie. required: !isDevMode() — não environment.production, que só fica
58
+ // certo depois do config.json.
59
+ loadRuntimeConfig(environment, { required: !isDevMode() })
60
+ .then(async () => {
61
+ applyRuntimeEnvironment(environment); // DEPOIS do config.json, ANTES do bootstrap
62
+ // Import dinâmico: app.config lê o environment ao carregar (clientId, URLs).
63
+ const [{ appConfig }, { AppComponent }] = await Promise.all([
64
+ import('./app/app.config'),
65
+ import('./app/app.component'),
66
+ ]);
67
+ return bootstrapApplication(AppComponent, appConfig);
68
+ })
69
+ .catch((err) => console.error(err));
44
70
  ```
45
71
 
46
72
  `src/app/app.config.ts`:
@@ -91,7 +117,11 @@ export class AppComponent {}
91
117
  `angular.json` (trechos de `architect.build.options`):
92
118
 
93
119
  ```json
94
- "assets": [{ "glob": "**/*", "input": "src/assets", "output": "assets" }],
120
+ "assets": [
121
+ { "glob": "**/*", "input": "src/assets", "output": "assets" },
122
+ { "glob": "*.json", "input": "src/brand/config", "output": "brand/config" },
123
+ { "glob": "config.json", "input": "src", "output": "/" }
124
+ ],
95
125
  "styles": [
96
126
  "node_modules/@trismegisto/tokens/dist/tokens.css",
97
127
  "node_modules/@trismegisto/core/dist/core.css",
@@ -45,23 +45,40 @@ Se as telas tiverem documentação (`document.load` com `import('./README.md')`)
45
45
  ### 3.1 `main.ts`
46
46
 
47
47
  ```ts
48
+ import { isDevMode } from '@angular/core';
48
49
  import { bootstrapApplication } from '@angular/platform-browser';
49
- import { applyRuntimeEnvironment } from '@trismegisto/spine';
50
- import { AppComponent } from './app/app.component';
51
- import { appConfig } from './app/app.config';
50
+ import { applyRuntimeEnvironment, loadRuntimeConfig } from '@trismegisto/spine';
52
51
  import { environment } from './environments/environment';
53
52
 
54
- applyRuntimeEnvironment(environment); // ANTES do bootstrap
55
- bootstrapApplication(AppComponent, appConfig).catch((err) => console.error(err));
53
+ // Sem top-level await (Zone.js): encadeie. required: !isDevMode() — não environment.production, que só fica
54
+ // certo depois do config.json.
55
+ loadRuntimeConfig(environment, { required: !isDevMode() })
56
+ .then(async () => {
57
+ applyRuntimeEnvironment(environment); // DEPOIS do config.json, ANTES do bootstrap
58
+ // Import dinâmico: app.config lê o environment ao carregar (clientId, URLs).
59
+ const [{ appConfig }, { AppComponent }] = await Promise.all([
60
+ import('./app/app.config'),
61
+ import('./app/app.component'),
62
+ ]);
63
+ return bootstrapApplication(AppComponent, appConfig);
64
+ })
65
+ .catch((err) => console.error(err));
56
66
  ```
57
67
 
68
+ `loadRuntimeConfig(environment, { file?, required? })` (3.1.0; do `@trismegisto/primitives`, reexportado aqui)
69
+ busca `config.json` (ou `file`) relativo ao `<base href>` e o mescla no `environment` (objetos chave a chave;
70
+ arrays e valores simples substituem). É o que permite **uma imagem por versão**: o build não sabe o ambiente, o
71
+ deploy põe ao lado do `index.html` a cópia de `src/brand/config/<ambiente>.json`. Com `required`, falta ou JSON
72
+ inválido rejeita a promise e o app não sobe; sem, só avisa. App sem o shell (ex.: tela de login que é o próprio
73
+ provedor OAuth) importa direto do `@trismegisto/primitives` e não usa `applyRuntimeEnvironment`.
74
+
58
75
  `applyRuntimeEnvironment(environment)` deriva do endereço em que o app está rodando:
59
76
  - **sempre:** `authorizationServer.redirectUrl = <origem><base href>/callback` e
60
77
  `postLogoutRedirectUri = <origem><base href>/logoff` (o servidor exige `redirect_uri` absoluto e o app pode
61
78
  viver sob um prefixo);
62
79
  - **sem porta na URL** (atrás de proxy reverso): `authority = <origem>/argos` e cada endpoint GraphQL **ainda
63
80
  sem valor** (vazio ou contendo `CHANGE_ME`) vira `<origem><base href>/graphql` (HTTP e WS). URL explícita no
64
- environment sempre vence.
81
+ environment (inclusive vinda do `config.json`) sempre vence.
65
82
  Devolve `{ origin, basePath, behindProxy, unset }` para o que for específico do app.
66
83
 
67
84
  ### 3.2 `app.config.ts`
@@ -223,8 +240,8 @@ O interceptor **não** põe o token. Nas APIs REST do app, mande `x-access-token
223
240
  ## 6. GraphQL (`@trismegisto/spine/graphql`)
224
241
 
225
242
  ```ts
226
- // environment.ts
227
- graphql: { principal: { namedClient: 'principal', http: 'CHANGE_ME', ws: 'CHANGE_ME' } }
243
+ // environment.ts (vazio = derivado atrás do proxy; URL explícita vem do config.json do ambiente)
244
+ graphql: { principal: { namedClient: 'principal', http: '', ws: '' } }
228
245
  // app.config.ts
229
246
  provideGraphql({ endpoints: environment.graphql })
230
247
  ```