forjajs 1.1.6 → 1.2.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 (60) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.en.md +28 -5
  3. package/README.md +30 -4
  4. package/bin/forja.mjs +3 -3
  5. package/boilerplates/06-clean-arch/README.md +48 -0
  6. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
  7. package/boilerplates/06-clean-arch/backend/package.json +43 -0
  8. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
  9. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
  10. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
  11. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
  12. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
  13. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
  14. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
  15. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
  16. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
  17. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
  18. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
  19. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
  20. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
  21. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
  22. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
  23. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
  24. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
  25. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
  26. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
  27. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
  28. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
  29. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
  30. package/boilerplates/README.md +20 -0
  31. package/docs/personas/architect/README.md +4 -4
  32. package/docs/personas/developer/README.md +3 -3
  33. package/docs/personas/qa/README.md +3 -3
  34. package/docs/quick-reference.md +9 -9
  35. package/docs/structure.md +3 -3
  36. package/lib/core/checks.mjs +20 -3
  37. package/lib/core/doc-graph.mjs +231 -0
  38. package/lib/core/health.mjs +131 -29
  39. package/lib/core/registry.mjs +23 -0
  40. package/lib/core/release.mjs +48 -8
  41. package/lib/templates/harness/code-intel.mjs +2 -2
  42. package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
  43. package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
  44. package/package.json +7 -1
  45. package/scripts/agent-harness.mjs +7 -5
  46. package/scripts/context-ops.mjs +7 -4
  47. package/scripts/dev.mjs +2 -2
  48. package/scripts/hook-guard-paths.mjs +1 -0
  49. package/scripts/hook-user-prompt.mjs +1 -1
  50. package/scripts/spec-cli.mjs +4 -3
  51. package/scripts/tools-doctor.mjs +1 -1
  52. package/specs/clean-arch-boilerplate/plan.md +137 -0
  53. package/specs/clean-arch-boilerplate/spec.md +121 -0
  54. package/specs/clean-arch-boilerplate/tasks.md +70 -0
  55. package/specs/coerencia-do-sistema/plan.md +155 -0
  56. package/specs/coerencia-do-sistema/spec.md +15 -14
  57. package/specs/coerencia-do-sistema/tasks.md +115 -0
  58. package/specs/ts-migration/plan.md +188 -0
  59. package/specs/ts-migration/spec.md +119 -0
  60. package/specs/ts-migration/tasks.md +110 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,43 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.2.0] — 2026-07-18 — Boilerplate Clean Architecture, coerência de doc e correções
8
+
9
+ Feature nova (um boilerplate), o terceiro gate de invariante (coerência da documentação), e
10
+ **correções de dois bugs vivos na 1.1.6** que o TypeScript achou. A migração TS avançou até o
11
+ pipeline de build provado — mas continua publicando a fonte `.mjs` (a troca para `dist/` é interna
12
+ e fica para uma release futura).
13
+
14
+ ### Corrigido
15
+ - **`npm run dev` estava quebrado** na 1.1.6: `scripts/dev.mjs` chamava `spawn()` sem importar —
16
+ `ReferenceError` em três caminhos (agent-harness, compress-memory, create-memory-nest-kit).
17
+ - **`context:budget` / `catalog:assets` estavam quebrados** na 1.1.6: `scripts/context-ops.mjs`
18
+ importava `dbPath` (inexistente; só há `getDbPath`) e o usava em `new Database(dbPath)`.
19
+ - Typedefs `Check`/`Result` duplicados e divergentes em `health.mjs` (resíduo da extração do runner).
20
+ - 22 links relativos quebrados em docs legadas (personas, quick-reference, structure).
21
+
22
+ ### Adicionado
23
+ - **Boilerplate `06-clean-arch`** (SPEC-013, ADR-0027): DDD por camadas onde se paga, caminho enxuto
24
+ onde não. Fatia rica (Orders) com inversão de dependência e invariante testável sem subir o Nest;
25
+ caminho enxuto (Products) lado a lado; `WHEN-CLEAN-WHEN-LEAN.md` com o critério; memória por
26
+ bounded context. A economia de token é reportada com honestidade (argumentada, não provada — o
27
+ benchmark é follow-up).
28
+ - **Gate de coerência da documentação** (SPEC-011, ADR-0025): `lib/core/doc-graph.mjs` + três checks
29
+ no `health.mjs` — `docs-commands` (critical: todo `forja <cmd>` citado existe no registry),
30
+ `commands-documented` e `docs-links` (warn). Rodam no `tools:doctor` e no CI.
31
+ - **Resolver de script agnóstico de extensão** (SPEC-012): `resolveScript` desacopla o registry da
32
+ extensão (`.ts → .js → .mjs`), preparando a migração TS. Backward-compatible.
33
+
34
+ ### Interno
35
+ - **TypeScript como gate** (SPEC-012, Fases 0-1): `checkJs` estrito sobre a fonte `.mjs`,
36
+ `types:check` no CI, contratos do núcleo (`Check`/`Probe`/`Result`) tipados. Pipeline de build
37
+ (`tsc → dist`) provado; a publicação de `dist/` e a renomeação `.mjs → .ts` ficam para depois.
38
+
39
+ ### Nota
40
+ - O `docs-links` pegou o **próprio autor**: um erro de profundidade relativa (`../../` vs `../../../`)
41
+ na correção dos links foi detectado pelo doctor antes do commit. E o `release:check` pegou o
42
+ acoplamento do dist-publish (código em `dist/scripts`, não `scripts/`) antes de qualquer publish.
43
+
7
44
  ## [1.1.6] — 2026-07-14 — README em inglês
8
45
 
9
46
  A vitrine do pacote passa a ter versão em inglês, para alcançar quem chega pelo npm.
package/README.en.md CHANGED
@@ -196,6 +196,7 @@ forja sync:universal # reindex the workspace SQLite FTS5
196
196
  forja query:universal "<query>" # FTS5 search
197
197
  forja context:smart # smart-context (3 modes, ADR-0003)
198
198
  forja memory:compress # archive old runs + VACUUM
199
+ forja memory:extract # extract global knowledge from memory
199
200
 
200
201
  # Quality & release
201
202
  forja project:check # framework standards (pre-commit)
@@ -269,11 +270,33 @@ output, code, and ADRs are readable regardless of language.
269
270
 
270
271
  ## Roadmap
271
272
 
272
- - [ ] **Core phase 2** — the `forja` CLI embedded in generated projects (today they inherit the
273
- harness + instructions)
274
- - [ ] **Audit in SQLite** — promote `forja-runs.jsonl` to a queryable FTS5 table
275
- - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow
276
- - [x] **English README** — you're reading it
273
+ The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
274
+ below either closes a framework frontier with a gate, or carries that pattern into generated projects.
275
+
276
+ **Recently shipped** (v1.2.0)
277
+
278
+ - [x] **Core gate** — `tools:doctor` fails (exit 1) when what blocks the framework is broken (ABI,
279
+ memory, runtime deps) — ADR-0023.
280
+ - [x] **Tarball gate** — `release:check` proves a clean install works before `npm publish`; the three
281
+ historical release bugs fail the gate — ADR-0024.
282
+ - [x] **Doc coherence gate** — docs can't cite a ghost command or a link to nowhere; checked in CI — ADR-0025.
283
+ - [x] **TypeScript as a gate** — strict `checkJs` in CI; core contracts typed. Found three latent bugs
284
+ no test caught (SPEC-012, in progress).
285
+ - [x] **Calibrated Clean Architecture boilerplate** — layers where they pay off, lean where they don't
286
+ (`boilerplates/06-clean-arch`, ADR-0027).
287
+
288
+ **Next** (by dependency, not by wish)
289
+
290
+ - [ ] **Finish the TypeScript migration** — publish `dist/` and rename `.mjs → .ts`. Pipeline proven;
291
+ source stays `.mjs` (Node ≥ 20) until then.
292
+ - [ ] **Token benchmark for clean-arch** — the saving is argued, not proven (ADR-0027): measure the
293
+ same feature in both architectures via `context:smart`. Prove it or recalibrate.
294
+ - [ ] **`release-auditor` consumes the gate** — the third surface from ADR-0024: the agent runs
295
+ `release:check` instead of reimplementing the procedure in prose.
296
+ - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
297
+ - [ ] **Queryable audit + generated dashboard** — promote `.context/forja-runs.jsonl` to an FTS5
298
+ table, and generate a **static** governance page on demand (read-only, no server — the ADR-0022
299
+ lesson that froze the server-dashboard).
277
300
 
278
301
  Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
279
302
 
package/README.md CHANGED
@@ -186,6 +186,7 @@ forja sync:universal # reindexa SQLite FTS5 do workspace
186
186
  forja query:universal "<query>" # busca FTS5
187
187
  forja context:smart # smart-context (3 modos, ADR-0003)
188
188
  forja memory:compress # arquiva runs antigos + VACUUM
189
+ forja memory:extract # extrai conhecimento global da memória
189
190
 
190
191
  # Qualidade & release
191
192
  forja project:check # standards do framework (pre-commit)
@@ -255,10 +256,35 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
255
256
 
256
257
  ## Roadmap
257
258
 
258
- - [ ] **Core fase 2** — CLI `forja` embutida nos projetos gerados (hoje herdam harness + instruções)
259
- - [ ] **Auditoria no SQLite** — promover `forja-runs.jsonl` a tabela consultável via FTS5
260
- - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás
261
- - [x] **README em inglês** — [`README.en.md`](README.en.md) (a documentação continua em pt-BR)
259
+ O fio condutor: **converter conhecimento que vive em convenção em invariante executável.** Cada
260
+ item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
261
+ gerados.
262
+
263
+ **Recém-entregue** (v1.2.0)
264
+
265
+ - [x] **Gate do núcleo** — `tools:doctor` reprova (exit 1) quando o que impede o framework de
266
+ trabalhar está quebrado (ABI, memória, deps de runtime) — ADR-0023.
267
+ - [x] **Gate do tarball** — `release:check` prova que uma instalação limpa funciona antes do
268
+ `npm publish`; os três bugs históricos de release reprovam o gate — ADR-0024.
269
+ - [x] **Gate de coerência da doc** — a documentação não pode citar comando fantasma nem link para o
270
+ nada; verificado no CI — ADR-0025.
271
+ - [x] **TypeScript como gate** — `checkJs` estrito no CI; os contratos do núcleo tipados. Achou três
272
+ bugs latentes que nenhum teste pegava (SPEC-012, em curso).
273
+ - [x] **Boilerplate Clean Architecture calibrado** — DDD por camadas onde se paga, enxuto onde não
274
+ (`boilerplates/06-clean-arch`, ADR-0027).
275
+
276
+ **Próximos passos** (por dependência, não por desejo)
277
+
278
+ - [ ] **Fechar a migração TypeScript** — publicar `dist/` e renomear `.mjs → .ts`. Pipeline provado;
279
+ a fonte segue `.mjs` (Node ≥ 20) até lá.
280
+ - [ ] **Benchmark de token do clean-arch** — a economia é argumentada, não provada (ADR-0027):
281
+ medir a mesma feature nas duas arquiteturas via `context:smart`. Provar ou recalibrar.
282
+ - [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
283
+ `release:check` em vez de reimplementar o procedimento em prosa.
284
+ - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
285
+ - [ ] **Auditoria consultável + painel gerado** — promover `.context/forja-runs.jsonl` a tabela
286
+ FTS5, e gerar um painel de governança **estático** por comando (leitura, sem servidor — a lição
287
+ do ADR-0022, que congelou o dashboard-servidor).
262
288
 
263
289
  Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
264
290
 
package/bin/forja.mjs CHANGED
@@ -16,7 +16,7 @@ import fs from 'node:fs';
16
16
  import path from 'node:path';
17
17
  import { spawnSync } from 'node:child_process';
18
18
  import { fileURLToPath } from 'node:url';
19
- import { COMMANDS, DOMAINS } from '../lib/core/registry.mjs';
19
+ import { COMMANDS, DOMAINS, resolveScript } from '../lib/core/registry.mjs';
20
20
  import { getWorkspaceInfo, getWorkspaceContextDir } from '../lib/workspace.mjs';
21
21
 
22
22
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -116,7 +116,7 @@ if (gateErrors.length) {
116
116
  const started = Date.now();
117
117
  let result;
118
118
  if (cmd.node) {
119
- const script = path.join(root, cmd.node);
119
+ const script = resolveScript(root, cmd.node);
120
120
  result = spawnSync('node', [script, ...(cmd.args || []), ...rest], {
121
121
  cwd: root,
122
122
  stdio: 'inherit',
@@ -126,7 +126,7 @@ if (cmd.node) {
126
126
  cwd: root,
127
127
  stdio: 'inherit',
128
128
  });
129
- if (result.error && result.error.code === 'ENOENT') {
129
+ if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') {
130
130
  console.error(`Binário não encontrado no PATH: ${cmd.bin}. Veja: forja tools:doctor`);
131
131
  result.status = 127;
132
132
  }
@@ -0,0 +1,48 @@
1
+ # 06 — Clean Architecture Calibrada
2
+
3
+ Boilerplate NestJS + TypeScript com **DDD e Clean Architecture onde se paga, e caminho enxuto onde
4
+ não** — a calibração é o ponto, não as camadas.
5
+
6
+ ## A ideia em uma frase
7
+
8
+ Camadas custam arquivos e tokens; você paga por elas quando protegem uma regra de negócio, e evita
9
+ quando é CRUD. Este boilerplate mostra **os dois padrões lado a lado** para você ver o critério, não
10
+ decorar dogma. Leia o [`WHEN-CLEAN-WHEN-LEAN.md`](WHEN-CLEAN-WHEN-LEAN.md) — é o coração.
11
+
12
+ ## Estrutura
13
+
14
+ ```
15
+ backend/src/
16
+ modules/orders/ # FATIA RICA — 4 camadas, porque há invariante de negócio
17
+ domain/ # agregado + value objects + PORTA (interface). Puro: zero @nestjs/ORM
18
+ application/ # use-cases (contratos tipados, legíveis sem a implementação)
19
+ infrastructure/ # adapter TypeORM (implementa a porta) + mapper domínio↔persistência
20
+ presentation/ # controller fino + DTOs HTTP
21
+ modules/products/ # CAMINHO ENXUTO — 1 camada, porque é CRUD sem regra
22
+ shared/ # Result, base de domínio
23
+ backend/test/ # a invariante testada SEM subir o Nest
24
+ memory/30-domains/ # o contexto de cada domínio na linguagem ubíqua (leia antes do código)
25
+ ```
26
+
27
+ ## A regra de dependência
28
+
29
+ Tudo aponta para **dentro**: `presentation` e `infrastructure` → `application` → `domain`. O domínio
30
+ não importa nada de fora. A infra **implementa** portas que o domínio declara. A inversão acontece no
31
+ módulo, numa linha: `{ provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository }`.
32
+
33
+ ## Economia de token (ADR-0009)
34
+
35
+ O agente lê `memory/30-domains/<ctx>/context.md` e a **assinatura** do use-case — e sabe o que a
36
+ feature faz sem carregar a implementação. As camadas dão pontos de entrada previsíveis (regra no
37
+ agregado, orquestração no use-case, persistência na infra). Arquitetura como compressão de contexto.
38
+
39
+ ## Rodando
40
+
41
+ ```bash
42
+ npm install
43
+ npm run start:dev # sobe o Nest (precisa de DATABASE_URL Postgres)
44
+ npm test # roda os testes de domínio — sem Postgres, sem Nest
45
+ ```
46
+
47
+ O `npm test` prova a premissa: a invariante do domínio (`test/orders/place-order.spec.ts`) roda
48
+ instanciando só o agregado. Se um teste de regra precisar do framework, o domínio vazou.
@@ -0,0 +1,42 @@
1
+ # Quando Clean Architecture, quando enxuto
2
+
3
+ Este boilerplate tem **os dois padrões lado a lado, de propósito**:
4
+
5
+ - `modules/orders/` — as quatro camadas (domain / application / infrastructure / presentation).
6
+ - `modules/products/` — uma camada só (controller → repositório direto).
7
+
8
+ Não é inconsistência. É a decisão mais importante da arquitetura, materializada em código: **camadas
9
+ custam tokens e arquivos; você paga por elas quando compram algo, e evita quando não.**
10
+
11
+ ## O critério
12
+
13
+ Use o padrão de `orders/` (camadas + porta + use-case) quando **pelo menos uma** for verdade:
14
+
15
+ - Há **invariante de negócio** — uma regra que não pode ser violada em estado nenhum ("não envia sem
16
+ pagamento", "saldo não fica negativo"). A regra precisa de um lar único: o domínio.
17
+ - Há **máquina de estados** — o objeto tem transições legais e ilegais.
18
+ - A regra precisa ser **testada sem subir o framework**, ou sobreviver a troca de infraestrutura.
19
+ - Múltiplos casos de uso operam o mesmo conceito de formas diferentes.
20
+
21
+ Use o padrão de `products/` (uma camada) quando **todas** forem verdade:
22
+
23
+ - É **CRUD** — criar, ler, atualizar, apagar, sem regra além de validação de formato.
24
+ - O "modelo" é a tabela: não há comportamento a proteger.
25
+ - Não há transição de estado que importe.
26
+
27
+ ## Por que isso é economia de token, não estética
28
+
29
+ Um agente que vai adicionar uma regra ao contexto `orders` lê o `context.md` do domínio (linguagem
30
+ ubíqua) e a **assinatura** do use-case — e sabe o que fazer sem carregar a implementação inteira. As
31
+ camadas dão pontos de entrada previsíveis: a regra vai no agregado, o caso de uso na aplicação, o
32
+ mapeamento na infra. Menos exploração, menos tokens.
33
+
34
+ O mesmo agente, num CRUD, não deveria pagar esse preço de leitura. Por isso `products/` é raso: para
35
+ um `GET /products`, quatro camadas seriam quatro arquivos a mais para ler, sem nada a proteger — o
36
+ **oposto** de economia de token, com nome de arquitetura.
37
+
38
+ ## A regra de ouro
39
+
40
+ **Comece enxuto. Promova quando a primeira invariante aparecer.** Um `products/` que ganha uma regra
41
+ de negócio de verdade (ex.: "não pode desativar produto com pedido aberto") é o sinal de promover
42
+ para o padrão de `orders/` — não antes. Arquitetura antecipada é dívida de token paga adiantado.
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "clean-arch-backend",
3
+ "version": "0.1.0",
4
+ "private": true,
5
+ "scripts": {
6
+ "build": "nest build",
7
+ "start": "nest start",
8
+ "start:dev": "nest start --watch",
9
+ "start:prod": "node dist/main",
10
+ "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
11
+ "test": "jest",
12
+ "test:watch": "jest --watch",
13
+ "test:cov": "jest --coverage",
14
+ "test:e2e": "jest --config test/jest-e2e.json"
15
+ },
16
+ "dependencies": {
17
+ "@nestjs/common": "^11.0.0",
18
+ "@nestjs/core": "^11.0.0",
19
+ "@nestjs/platform-express": "^11.0.0",
20
+ "@nestjs/typeorm": "^11.0.0",
21
+ "class-transformer": "^0.5.1",
22
+ "class-validator": "^0.14.1",
23
+ "pg": "^8.13.0",
24
+ "reflect-metadata": "^0.2.2",
25
+ "rxjs": "^7.8.1",
26
+ "typeorm": "^0.3.20"
27
+ },
28
+ "devDependencies": {
29
+ "@nestjs/testing": "^11.0.0",
30
+ "@types/jest": "^29.5.0",
31
+ "@types/node": "^22.0.0",
32
+ "jest": "^29.7.0",
33
+ "ts-jest": "^29.2.0",
34
+ "typescript": "^5.6.0"
35
+ },
36
+ "jest": {
37
+ "moduleFileExtensions": ["js", "json", "ts"],
38
+ "rootDir": ".",
39
+ "testRegex": ".*\\.spec\\.ts$",
40
+ "transform": { "^.+\\.ts$": "ts-jest" },
41
+ "testEnvironment": "node"
42
+ }
43
+ }
@@ -0,0 +1,20 @@
1
+ import { Module } from '@nestjs/common';
2
+ import { TypeOrmModule } from '@nestjs/typeorm';
3
+ import { OrdersModule } from './modules/orders/orders.module';
4
+ import { ProductsModule } from './modules/products/products.module';
5
+ import { OrderOrmEntity } from './modules/orders/infrastructure/order.orm-entity';
6
+ import { Product } from './modules/products/product.entity';
7
+
8
+ @Module({
9
+ imports: [
10
+ TypeOrmModule.forRoot({
11
+ type: 'postgres',
12
+ url: process.env.DATABASE_URL,
13
+ entities: [OrderOrmEntity, Product],
14
+ synchronize: process.env.NODE_ENV !== 'production', // dev only
15
+ }),
16
+ OrdersModule,
17
+ ProductsModule,
18
+ ],
19
+ })
20
+ export class AppModule {}
@@ -0,0 +1,10 @@
1
+ import { NestFactory } from '@nestjs/core';
2
+ import { ValidationPipe } from '@nestjs/common';
3
+ import { AppModule } from './app.module';
4
+
5
+ async function bootstrap() {
6
+ const app = await NestFactory.create(AppModule);
7
+ app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
8
+ await app.listen(process.env.PORT ?? 3000);
9
+ }
10
+ bootstrap();
@@ -0,0 +1,47 @@
1
+ import { Inject, Injectable } from '@nestjs/common';
2
+ import { randomUUID } from 'node:crypto';
3
+ import { Order, OrderLine } from '../domain/order.entity';
4
+ import { Money } from '../domain/money.vo';
5
+ import { ORDER_REPOSITORY, OrderRepository } from '../domain/order.repository';
6
+ import { Result } from '../../../shared/result';
7
+
8
+ /**
9
+ * Contratos de entrada/saída — tipados e legíveis. Um agente entende o que o use-case faz pela
10
+ * assinatura, **sem ler o corpo** (AC-5). É a compressão de contexto: o tipo é o resumo.
11
+ */
12
+ export interface PlaceOrderInput {
13
+ customerId: string;
14
+ items: Array<{ productId: string; unitPriceCents: number; quantity: number }>;
15
+ }
16
+ export interface PlaceOrderOutput {
17
+ orderId: string;
18
+ totalCents: number;
19
+ }
20
+
21
+ /**
22
+ * PlaceOrder — orquestra o domínio + a porta. O use-case não tem regra de negócio própria: ele
23
+ * traduz o input, chama o agregado (que decide), e persiste via porta. A regra ("precisa de itens")
24
+ * é do `Order`, não daqui.
25
+ */
26
+ @Injectable()
27
+ export class PlaceOrderUseCase {
28
+ // Injeta a PORTA (token), nunca o adapter concreto — a inversão de dependência.
29
+ constructor(@Inject(ORDER_REPOSITORY) private readonly orders: OrderRepository) {}
30
+
31
+ async execute(input: PlaceOrderInput): Promise<Result<PlaceOrderOutput>> {
32
+ const lines: OrderLine[] = input.items.map((i) => ({
33
+ productId: i.productId,
34
+ unitPrice: Money.of(i.unitPriceCents),
35
+ quantity: i.quantity,
36
+ }));
37
+
38
+ const created = Order.place(randomUUID(), input.customerId, lines);
39
+ if (created.isFailure) return Result.fail(created.error!);
40
+
41
+ const order = created.value;
42
+ order.confirm(); // rascunho → confirmado (a máquina de estados do domínio valida)
43
+ await this.orders.save(order);
44
+
45
+ return Result.ok({ orderId: order.id, totalCents: order.total.cents });
46
+ }
47
+ }
@@ -0,0 +1,28 @@
1
+ import { Inject, Injectable } from '@nestjs/common';
2
+ import { ORDER_REPOSITORY, OrderRepository } from '../domain/order.repository';
3
+ import { Result } from '../../../shared/result';
4
+
5
+ export interface ShipOrderInput {
6
+ orderId: string;
7
+ }
8
+
9
+ /**
10
+ * ShipOrder — demonstra a invariante-chave passando pelo domínio: `order.ship()` **falha** se o
11
+ * pedido não estiver PAID. O use-case não reimplementa a regra; ele confia no agregado e propaga a
12
+ * falha. A regra "não envia sem pagamento" existe num lugar só: `Order`.
13
+ */
14
+ @Injectable()
15
+ export class ShipOrderUseCase {
16
+ constructor(@Inject(ORDER_REPOSITORY) private readonly orders: OrderRepository) {}
17
+
18
+ async execute(input: ShipOrderInput): Promise<Result<void>> {
19
+ const order = await this.orders.byId(input.orderId);
20
+ if (!order) return Result.fail('pedido não encontrado');
21
+
22
+ const shipped = order.ship(); // domínio decide: só sai de PAID
23
+ if (shipped.isFailure) return Result.fail(shipped.error!);
24
+
25
+ await this.orders.save(order);
26
+ return Result.ok(undefined);
27
+ }
28
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Money — value object. Imutável, comparado por valor, valida a si mesmo na criação.
3
+ * Zero dependência de framework: é TypeScript puro (o ponto do domínio isolado).
4
+ */
5
+ export class Money {
6
+ private constructor(public readonly cents: number) {}
7
+
8
+ static of(cents: number): Money {
9
+ if (!Number.isInteger(cents) || cents < 0) {
10
+ throw new Error('Money exige inteiro não-negativo em centavos');
11
+ }
12
+ return new Money(cents);
13
+ }
14
+
15
+ static zero(): Money {
16
+ return new Money(0);
17
+ }
18
+
19
+ plus(other: Money): Money {
20
+ return new Money(this.cents + other.cents);
21
+ }
22
+
23
+ times(qty: number): Money {
24
+ return Money.of(this.cents * qty);
25
+ }
26
+
27
+ isZero(): boolean {
28
+ return this.cents === 0;
29
+ }
30
+ }
@@ -0,0 +1,36 @@
1
+ /**
2
+ * OrderStatus — value object que é uma máquina de estados. As transições legais moram AQUI, no
3
+ * domínio, não num `if` espalhado pelos services. Um estado inválido é impossível de construir.
4
+ *
5
+ * DRAFT ──confirm──► CONFIRMED ──pay──► PAID ──ship──► SHIPPED
6
+ * └──────────────── cancel ──────────────► CANCELLED (de qualquer não-enviado)
7
+ */
8
+ export type OrderStatusValue = 'DRAFT' | 'CONFIRMED' | 'PAID' | 'SHIPPED' | 'CANCELLED';
9
+
10
+ const TRANSITIONS: Record<OrderStatusValue, OrderStatusValue[]> = {
11
+ DRAFT: ['CONFIRMED', 'CANCELLED'],
12
+ CONFIRMED: ['PAID', 'CANCELLED'],
13
+ PAID: ['SHIPPED', 'CANCELLED'],
14
+ SHIPPED: [],
15
+ CANCELLED: [],
16
+ };
17
+
18
+ export class OrderStatus {
19
+ private constructor(public readonly value: OrderStatusValue) {}
20
+
21
+ static draft(): OrderStatus {
22
+ return new OrderStatus('DRAFT');
23
+ }
24
+
25
+ static from(value: OrderStatusValue): OrderStatus {
26
+ return new OrderStatus(value);
27
+ }
28
+
29
+ canTransitionTo(next: OrderStatusValue): boolean {
30
+ return TRANSITIONS[this.value].includes(next);
31
+ }
32
+
33
+ is(value: OrderStatusValue): boolean {
34
+ return this.value === value;
35
+ }
36
+ }
@@ -0,0 +1,85 @@
1
+ import { Result } from '../../../shared/result';
2
+ import { Money } from './money.vo';
3
+ import { OrderStatus } from './order-status.vo';
4
+
5
+ /**
6
+ * Order — o agregado. **Toda invariante de negócio mora aqui**, em TypeScript puro:
7
+ *
8
+ * - não confirma um pedido sem itens;
9
+ * - não paga o que não foi confirmado; não envia o que não foi pago;
10
+ * - o total é derivado das linhas, nunca setado de fora.
11
+ *
12
+ * Nenhum import de `@nestjs` ou de ORM. É isso que torna `place-order.spec.ts` capaz de testar a
13
+ * regra instanciando só este objeto — sem subir o Nest. Se um dia precisar do framework para testar
14
+ * a invariante, o domínio vazou.
15
+ */
16
+
17
+ export interface OrderLine {
18
+ readonly productId: string;
19
+ readonly unitPrice: Money;
20
+ readonly quantity: number;
21
+ }
22
+
23
+ export class Order {
24
+ private constructor(
25
+ public readonly id: string,
26
+ public readonly customerId: string,
27
+ private _lines: OrderLine[],
28
+ private _status: OrderStatus,
29
+ ) {}
30
+
31
+ /** Cria um pedido em rascunho. Regra: precisa de ao menos uma linha. */
32
+ static place(id: string, customerId: string, lines: OrderLine[]): Result<Order> {
33
+ if (lines.length === 0) {
34
+ return Result.fail('um pedido precisa de ao menos um item');
35
+ }
36
+ if (lines.some((l) => l.quantity <= 0)) {
37
+ return Result.fail('quantidade de item deve ser positiva');
38
+ }
39
+ return Result.ok(new Order(id, customerId, [...lines], OrderStatus.draft()));
40
+ }
41
+
42
+ /** Reconstrói do estado persistido (usado pelo mapper da infra — sem revalidar regra de criação). */
43
+ static rehydrate(id: string, customerId: string, lines: OrderLine[], status: OrderStatus): Order {
44
+ return new Order(id, customerId, lines, status);
45
+ }
46
+
47
+ get status(): OrderStatus {
48
+ return this._status;
49
+ }
50
+
51
+ get lines(): readonly OrderLine[] {
52
+ return this._lines;
53
+ }
54
+
55
+ /** Total derivado das linhas — nunca um campo setável de fora. */
56
+ get total(): Money {
57
+ return this._lines.reduce((acc, l) => acc.plus(l.unitPrice.times(l.quantity)), Money.zero());
58
+ }
59
+
60
+ confirm(): Result<void> {
61
+ return this.transition('CONFIRMED');
62
+ }
63
+
64
+ /** Invariante-chave: só paga o confirmado. */
65
+ pay(): Result<void> {
66
+ return this.transition('PAID');
67
+ }
68
+
69
+ /** Invariante-chave: **não envia sem pagamento**. A transição só é legal a partir de PAID. */
70
+ ship(): Result<void> {
71
+ return this.transition('SHIPPED');
72
+ }
73
+
74
+ cancel(): Result<void> {
75
+ return this.transition('CANCELLED');
76
+ }
77
+
78
+ private transition(to: Parameters<OrderStatus['canTransitionTo']>[0]): Result<void> {
79
+ if (!this._status.canTransitionTo(to)) {
80
+ return Result.fail(`transição inválida: ${this._status.value} → ${to}`);
81
+ }
82
+ this._status = OrderStatus.from(to);
83
+ return Result.ok(undefined);
84
+ }
85
+ }
@@ -0,0 +1,17 @@
1
+ import { Order } from './order.entity';
2
+
3
+ /**
4
+ * OrderRepository — a **PORTA** (Clean Architecture / Hexagonal). É uma `interface` no domínio: o
5
+ * domínio declara o que precisa de persistência, sem saber *como*. O adapter (TypeORM, in-memory,
6
+ * outro) a implementa na camada de infraestrutura.
7
+ *
8
+ * `ORDER_REPOSITORY` é o token de injeção do NestJS — porque interface não existe em runtime, o Nest
9
+ * injeta por token. O use-case pede o token; o módulo faz o bind token→adapter. É assim que a
10
+ * dependência aponta para DENTRO: application → domain, e a infra implementa a porta do domínio.
11
+ */
12
+ export const ORDER_REPOSITORY = Symbol('OrderRepository');
13
+
14
+ export interface OrderRepository {
15
+ save(order: Order): Promise<void>;
16
+ byId(id: string): Promise<Order | null>;
17
+ }
@@ -0,0 +1,24 @@
1
+ import { Column, Entity, PrimaryColumn } from 'typeorm';
2
+
3
+ /**
4
+ * OrderOrmEntity — a forma de PERSISTÊNCIA, decorada com TypeORM. Vive só na infraestrutura.
5
+ *
6
+ * Repare: **não é** o `Order` do domínio. O agregado de domínio é TypeScript puro, sem `@Entity`. O
7
+ * mapper (no repositório) traduz entre os dois. É essa separação que mantém o ORM fora do domínio —
8
+ * trocar o TypeORM por outra coisa mexe só aqui.
9
+ */
10
+ @Entity('orders')
11
+ export class OrderOrmEntity {
12
+ @PrimaryColumn('uuid')
13
+ id!: string;
14
+
15
+ @Column()
16
+ customerId!: string;
17
+
18
+ @Column()
19
+ status!: string;
20
+
21
+ /** Linhas serializadas — detalhe de persistência, não modelagem de domínio. */
22
+ @Column('jsonb')
23
+ lines!: Array<{ productId: string; unitPriceCents: number; quantity: number }>;
24
+ }