forjajs 1.1.6 → 1.3.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 (172) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +62 -0
  3. package/README.en.md +33 -5
  4. package/README.md +35 -4
  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/dist/bin/create-memory-nest-kit.d.ts +2 -0
  32. package/dist/bin/create-memory-nest-kit.js +110 -0
  33. package/dist/bin/forja.d.ts +13 -0
  34. package/dist/bin/forja.js +136 -0
  35. package/dist/bin/init-project.d.ts +2 -0
  36. package/dist/bin/init-project.js +516 -0
  37. package/dist/lib/audit.d.ts +67 -0
  38. package/dist/lib/audit.js +143 -0
  39. package/dist/lib/context-builder.d.ts +58 -0
  40. package/dist/lib/context-builder.js +233 -0
  41. package/dist/lib/core/checks.d.ts +91 -0
  42. package/dist/lib/core/checks.js +119 -0
  43. package/dist/lib/core/doc-graph.d.ts +60 -0
  44. package/dist/lib/core/doc-graph.js +235 -0
  45. package/dist/lib/core/health.d.ts +103 -0
  46. package/dist/lib/core/health.js +538 -0
  47. package/dist/lib/core/registry.d.ts +296 -0
  48. package/dist/lib/core/registry.js +317 -0
  49. package/dist/lib/core/release.d.ts +334 -0
  50. package/dist/lib/core/release.js +465 -0
  51. package/dist/lib/generators/memory-generator.d.ts +83 -0
  52. package/{lib → dist/lib}/generators/memory-generator.js +107 -178
  53. package/dist/lib/generators/nest-generator.d.ts +15 -0
  54. package/{lib → dist/lib}/generators/nest-generator.js +47 -71
  55. package/dist/lib/generators/readme-generator.d.ts +15 -0
  56. package/{lib → dist/lib}/generators/readme-generator.js +9 -14
  57. package/dist/lib/governance-report.d.ts +49 -0
  58. package/dist/lib/governance-report.js +170 -0
  59. package/dist/lib/templates/harness/code-intel.d.mts +2 -0
  60. package/dist/lib/templates/harness/code-intel.mjs +126 -0
  61. package/dist/lib/utils/file-helpers.d.ts +9 -0
  62. package/dist/lib/utils/file-helpers.js +34 -0
  63. package/dist/lib/validators/structure-validator.d.ts +48 -0
  64. package/dist/lib/validators/structure-validator.js +232 -0
  65. package/dist/lib/workspace.d.ts +40 -0
  66. package/dist/lib/workspace.js +174 -0
  67. package/dist/scripts/agent-harness.d.ts +2 -0
  68. package/dist/scripts/agent-harness.js +556 -0
  69. package/dist/scripts/agent-router.d.ts +30 -0
  70. package/dist/scripts/agent-router.js +208 -0
  71. package/dist/scripts/audit-query.d.ts +2 -0
  72. package/dist/scripts/audit-query.js +43 -0
  73. package/dist/scripts/audit-sync.d.ts +2 -0
  74. package/dist/scripts/audit-sync.js +19 -0
  75. package/dist/scripts/build-smart-context.d.ts +1 -0
  76. package/dist/scripts/build-smart-context.js +75 -0
  77. package/dist/scripts/check-standards.d.ts +1 -0
  78. package/dist/scripts/check-standards.js +87 -0
  79. package/dist/scripts/compress-memory.d.ts +16 -0
  80. package/dist/scripts/compress-memory.js +157 -0
  81. package/dist/scripts/compress-project-memory.d.ts +1 -0
  82. package/dist/scripts/compress-project-memory.js +48 -0
  83. package/dist/scripts/context-ops.d.ts +2 -0
  84. package/dist/scripts/context-ops.js +464 -0
  85. package/dist/scripts/dev.d.ts +96 -0
  86. package/dist/scripts/dev.js +312 -0
  87. package/dist/scripts/extract-global-knowledge.d.ts +1 -0
  88. package/dist/scripts/extract-global-knowledge.js +43 -0
  89. package/dist/scripts/generate-dashboard.d.ts +1 -0
  90. package/dist/scripts/generate-dashboard.js +48 -0
  91. package/dist/scripts/governance-dashboard.d.ts +2 -0
  92. package/dist/scripts/governance-dashboard.js +36 -0
  93. package/dist/scripts/hook-guard-paths.d.ts +17 -0
  94. package/dist/scripts/hook-guard-paths.js +68 -0
  95. package/dist/scripts/hook-post-edit.d.ts +20 -0
  96. package/dist/scripts/hook-post-edit.js +70 -0
  97. package/dist/scripts/hook-session-start.d.ts +17 -0
  98. package/dist/scripts/hook-session-start.js +108 -0
  99. package/dist/scripts/hook-user-prompt.d.ts +22 -0
  100. package/dist/scripts/hook-user-prompt.js +193 -0
  101. package/dist/scripts/memory-schema.d.ts +6 -0
  102. package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
  103. package/dist/scripts/query-universal-memory.d.ts +1 -0
  104. package/dist/scripts/query-universal-memory.js +44 -0
  105. package/dist/scripts/release-check.d.ts +14 -0
  106. package/dist/scripts/release-check.js +48 -0
  107. package/dist/scripts/spec-cli.d.ts +29 -0
  108. package/dist/scripts/spec-cli.js +261 -0
  109. package/dist/scripts/sprint-manager.d.ts +1 -0
  110. package/dist/scripts/sprint-manager.js +187 -0
  111. package/dist/scripts/sync-universal-memory.d.ts +1 -0
  112. package/dist/scripts/sync-universal-memory.js +277 -0
  113. package/dist/scripts/token-benchmark.d.ts +20 -0
  114. package/dist/scripts/token-benchmark.js +181 -0
  115. package/dist/scripts/tools-doctor.d.ts +20 -0
  116. package/dist/scripts/tools-doctor.js +120 -0
  117. package/docs/personas/architect/README.md +4 -4
  118. package/docs/personas/developer/README.md +3 -3
  119. package/docs/personas/qa/README.md +3 -3
  120. package/docs/quick-reference.md +9 -9
  121. package/docs/structure.md +3 -3
  122. package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
  123. package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
  124. package/memory/90-decisions/0028-governanca-visivel.md +84 -0
  125. package/package.json +60 -56
  126. package/specs/clean-arch-boilerplate/plan.md +137 -0
  127. package/specs/clean-arch-boilerplate/spec.md +121 -0
  128. package/specs/clean-arch-boilerplate/tasks.md +70 -0
  129. package/specs/coerencia-do-sistema/plan.md +155 -0
  130. package/specs/coerencia-do-sistema/spec.md +15 -14
  131. package/specs/coerencia-do-sistema/tasks.md +115 -0
  132. package/specs/governanca-visivel/plan.md +122 -0
  133. package/specs/governanca-visivel/spec.md +112 -0
  134. package/specs/governanca-visivel/tasks.md +60 -0
  135. package/specs/ts-migration/plan.md +199 -0
  136. package/specs/ts-migration/spec.md +119 -0
  137. package/specs/ts-migration/tasks.md +110 -0
  138. package/bin/create-memory-nest-kit.js +0 -125
  139. package/bin/forja.mjs +0 -143
  140. package/bin/init-project.js +0 -612
  141. package/lib/context-builder.js +0 -257
  142. package/lib/core/checks.mjs +0 -138
  143. package/lib/core/health.mjs +0 -475
  144. package/lib/core/registry.mjs +0 -289
  145. package/lib/core/release.mjs +0 -452
  146. package/lib/templates/harness/code-intel.mjs +0 -119
  147. package/lib/templates/harness/mcp.json +0 -10
  148. package/lib/utils/file-helpers.js +0 -40
  149. package/lib/validators/structure-validator.js +0 -253
  150. package/lib/workspace.mjs +0 -213
  151. package/scripts/agent-harness.mjs +0 -578
  152. package/scripts/agent-router.mjs +0 -189
  153. package/scripts/build-smart-context.js +0 -87
  154. package/scripts/check-standards.js +0 -98
  155. package/scripts/compress-memory.mjs +0 -198
  156. package/scripts/compress-project-memory.js +0 -58
  157. package/scripts/context-ops.mjs +0 -463
  158. package/scripts/dev.mjs +0 -349
  159. package/scripts/extract-global-knowledge.js +0 -52
  160. package/scripts/generate-dashboard.js +0 -59
  161. package/scripts/hook-guard-paths.mjs +0 -75
  162. package/scripts/hook-post-edit.mjs +0 -79
  163. package/scripts/hook-session-start.mjs +0 -104
  164. package/scripts/hook-user-prompt.mjs +0 -185
  165. package/scripts/pre-commit.sh +0 -102
  166. package/scripts/query-universal-memory.js +0 -50
  167. package/scripts/release-check.mjs +0 -56
  168. package/scripts/spec-cli.mjs +0 -260
  169. package/scripts/sprint-manager.js +0 -200
  170. package/scripts/sync-universal-memory.js +0 -286
  171. package/scripts/token-benchmark.mjs +0 -203
  172. package/scripts/tools-doctor.mjs +0 -132
@@ -6,7 +6,7 @@
6
6
  "hooks": [
7
7
  {
8
8
  "type": "command",
9
- "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-session-start.mjs",
9
+ "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-session-start.ts",
10
10
  "timeout": 5000
11
11
  }
12
12
  ]
@@ -17,7 +17,7 @@
17
17
  "hooks": [
18
18
  {
19
19
  "type": "command",
20
- "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-user-prompt.mjs",
20
+ "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-user-prompt.ts",
21
21
  "timeout": 3000
22
22
  }
23
23
  ]
@@ -29,7 +29,7 @@
29
29
  "hooks": [
30
30
  {
31
31
  "type": "command",
32
- "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-guard-paths.mjs",
32
+ "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-guard-paths.ts",
33
33
  "timeout": 5000
34
34
  }
35
35
  ]
@@ -41,7 +41,7 @@
41
41
  "hooks": [
42
42
  {
43
43
  "type": "command",
44
- "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-post-edit.mjs",
44
+ "command": "node $CLAUDE_PROJECT_DIR/scripts/hook-post-edit.ts",
45
45
  "timeout": 60000
46
46
  }
47
47
  ]
@@ -50,9 +50,9 @@
50
50
  },
51
51
  "permissions": {
52
52
  "allow": [
53
- "Bash(node bin/forja.mjs *)",
54
- "Bash(node scripts/spec-cli.mjs *)",
55
- "Bash(node scripts/agent-router.mjs *)",
53
+ "Bash(node bin/forja.ts *)",
54
+ "Bash(node scripts/spec-cli.ts *)",
55
+ "Bash(node scripts/agent-router.ts *)",
56
56
  "Bash(npm run spec:*)",
57
57
  "Bash(npm run memory:*)",
58
58
  "Bash(npm run sprint:*)",
package/CHANGELOG.md CHANGED
@@ -4,6 +4,68 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.3.0] — 2026-07-19 — Governança visível e o núcleo em TypeScript
8
+
9
+ Duas frentes que amadurecem o framework: a governança sai do arquivo que ninguém abre para
10
+ **consultável e visível**, e o motor de invariantes (`lib/core/`) passa a ser **TypeScript de
11
+ verdade**, com o pacote publicando `dist/` compilado.
12
+
13
+ ### Adicionado
14
+ - **Auditoria consultável + painel de governança** (SPEC-014, ADR-0028): `audit:sync` projeta o
15
+ `.context/forja-runs.jsonl` na tabela `audit_runs` (idempotente por `line_hash` — o `.jsonl` segue
16
+ sendo a fonte de verdade); `audit:query` filtra a trilha por `--failed`/`--cmd`/`--since`/`--gate`;
17
+ `governance:dashboard` gera um HTML **estático e self-contained** (sem servidor — a lição do
18
+ ADR-0022) com o estado de specs, ADRs, gates e métricas.
19
+ - **`lib/core/` em TypeScript** (SPEC-012 Fase 2, leaf-first): `checks`, `health`, `release`,
20
+ `doc-graph` e `registry` viram `.ts` com `interface Check/Probe/Result` reais. Dev roda `.ts`
21
+ nativo (Node ≥22.6); o publicado embarca `dist/*.js` (Node ≥20).
22
+
23
+ ### Alterado
24
+ - **O pacote publica `dist/` compilado** (SPEC-012 Fase 3): `bin`/`files[]` apontam para `dist/`. O
25
+ `release:check` **builda o `dist/` antes de empacotar**, então o tarball provado é exatamente o
26
+ publicado — sem step de build no CI, sem `dist/` no git, sem janela de staleness.
27
+ - **CI**: o job `test` roda em Node 22.x/24.x (a fonte `.ts` exige strip-types ≥22.6). O suporte a
28
+ Node 20 do pacote publicado (que é `dist/*.js`) segue provado pelo job `release-gate`.
29
+
30
+ ---
31
+
32
+ ## [1.2.0] — 2026-07-18 — Boilerplate Clean Architecture, coerência de doc e correções
33
+
34
+ Feature nova (um boilerplate), o terceiro gate de invariante (coerência da documentação), e
35
+ **correções de dois bugs vivos na 1.1.6** que o TypeScript achou. A migração TS avançou até o
36
+ pipeline de build provado — mas continua publicando a fonte `.mjs` (a troca para `dist/` é interna
37
+ e fica para uma release futura).
38
+
39
+ ### Corrigido
40
+ - **`npm run dev` estava quebrado** na 1.1.6: `scripts/dev.mjs` chamava `spawn()` sem importar —
41
+ `ReferenceError` em três caminhos (agent-harness, compress-memory, create-memory-nest-kit).
42
+ - **`context:budget` / `catalog:assets` estavam quebrados** na 1.1.6: `scripts/context-ops.mjs`
43
+ importava `dbPath` (inexistente; só há `getDbPath`) e o usava em `new Database(dbPath)`.
44
+ - Typedefs `Check`/`Result` duplicados e divergentes em `health.mjs` (resíduo da extração do runner).
45
+ - 22 links relativos quebrados em docs legadas (personas, quick-reference, structure).
46
+
47
+ ### Adicionado
48
+ - **Boilerplate `06-clean-arch`** (SPEC-013, ADR-0027): DDD por camadas onde se paga, caminho enxuto
49
+ onde não. Fatia rica (Orders) com inversão de dependência e invariante testável sem subir o Nest;
50
+ caminho enxuto (Products) lado a lado; `WHEN-CLEAN-WHEN-LEAN.md` com o critério; memória por
51
+ bounded context. A economia de token é reportada com honestidade (argumentada, não provada — o
52
+ benchmark é follow-up).
53
+ - **Gate de coerência da documentação** (SPEC-011, ADR-0025): `lib/core/doc-graph.mjs` + três checks
54
+ no `health.mjs` — `docs-commands` (critical: todo `forja <cmd>` citado existe no registry),
55
+ `commands-documented` e `docs-links` (warn). Rodam no `tools:doctor` e no CI.
56
+ - **Resolver de script agnóstico de extensão** (SPEC-012): `resolveScript` desacopla o registry da
57
+ extensão (`.ts → .js → .mjs`), preparando a migração TS. Backward-compatible.
58
+
59
+ ### Interno
60
+ - **TypeScript como gate** (SPEC-012, Fases 0-1): `checkJs` estrito sobre a fonte `.mjs`,
61
+ `types:check` no CI, contratos do núcleo (`Check`/`Probe`/`Result`) tipados. Pipeline de build
62
+ (`tsc → dist`) provado; a publicação de `dist/` e a renomeação `.mjs → .ts` ficam para depois.
63
+
64
+ ### Nota
65
+ - O `docs-links` pegou o **próprio autor**: um erro de profundidade relativa (`../../` vs `../../../`)
66
+ na correção dos links foi detectado pelo doctor antes do commit. E o `release:check` pegou o
67
+ acoplamento do dist-publish (código em `dist/scripts`, não `scripts/`) antes de qualquer publish.
68
+
7
69
  ## [1.1.6] — 2026-07-14 — README em inglês
8
70
 
9
71
  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,12 +196,18 @@ 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)
202
203
  forja tools:doctor # core X-ray; exit 1 if broken
203
204
  forja release:check --publish # tarball gate before publishing
204
205
  forja project:dashboard # static status report
206
+
207
+ # Governance & audit
208
+ forja audit:sync # project the audit trail into a queryable table
209
+ forja audit:query --failed # query: --failed, --cmd <x>, --since 7d
210
+ forja governance:dashboard # static HTML panel (gates, SDD, audit) — no server
205
211
  ```
206
212
 
207
213
  ## Framework vs workspace separation
@@ -269,11 +275,33 @@ output, code, and ADRs are readable regardless of language.
269
275
 
270
276
  ## Roadmap
271
277
 
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
278
+ The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
279
+ below either closes a framework frontier with a gate, or carries that pattern into generated projects.
280
+
281
+ **Recently shipped** (v1.2.0)
282
+
283
+ - [x] **Core gate** — `tools:doctor` fails (exit 1) when what blocks the framework is broken (ABI,
284
+ memory, runtime deps) — ADR-0023.
285
+ - [x] **Tarball gate** — `release:check` proves a clean install works before `npm publish`; the three
286
+ historical release bugs fail the gate — ADR-0024.
287
+ - [x] **Doc coherence gate** — docs can't cite a ghost command or a link to nowhere; checked in CI — ADR-0025.
288
+ - [x] **TypeScript as a gate** — strict `checkJs` in CI; core contracts typed. Found three latent bugs
289
+ no test caught (SPEC-012, in progress).
290
+ - [x] **Calibrated Clean Architecture boilerplate** — layers where they pay off, lean where they don't
291
+ (`boilerplates/06-clean-arch`, ADR-0027).
292
+
293
+ **Next** (by dependency, not by wish)
294
+
295
+ - [ ] **Finish the TypeScript migration** — publish `dist/` and rename `.mjs → .ts`. Pipeline proven;
296
+ source stays `.mjs` (Node ≥ 20) until then.
297
+ - [ ] **Token benchmark for clean-arch** — the saving is argued, not proven (ADR-0027): measure the
298
+ same feature in both architectures via `context:smart`. Prove it or recalibrate.
299
+ - [ ] **`release-auditor` consumes the gate** — the third surface from ADR-0024: the agent runs
300
+ `release:check` instead of reimplementing the procedure in prose.
301
+ - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
302
+ - [ ] **Queryable audit + generated dashboard** — promote `.context/forja-runs.jsonl` to an FTS5
303
+ table, and generate a **static** governance page on demand (read-only, no server — the ADR-0022
304
+ lesson that froze the server-dashboard).
277
305
 
278
306
  Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
279
307
 
package/README.md CHANGED
@@ -186,12 +186,18 @@ 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)
192
193
  forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
193
194
  forja release:check --publish # gate do tarball antes de publicar
194
195
  forja project:dashboard # relatório estático de status
196
+
197
+ # Governança & auditoria
198
+ forja audit:sync # projeta a trilha de auditoria numa tabela consultável
199
+ forja audit:query --failed # consulta: --failed, --cmd <x>, --since 7d
200
+ forja governance:dashboard # painel HTML estático (gates, SDD, auditoria) — sem servidor
195
201
  ```
196
202
 
197
203
  ## Separação framework × workspace
@@ -255,10 +261,35 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
255
261
 
256
262
  ## Roadmap
257
263
 
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)
264
+ O fio condutor: **converter conhecimento que vive em convenção em invariante executável.** Cada
265
+ item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
266
+ gerados.
267
+
268
+ **Recém-entregue** (v1.2.0)
269
+
270
+ - [x] **Gate do núcleo** — `tools:doctor` reprova (exit 1) quando o que impede o framework de
271
+ trabalhar está quebrado (ABI, memória, deps de runtime) — ADR-0023.
272
+ - [x] **Gate do tarball** — `release:check` prova que uma instalação limpa funciona antes do
273
+ `npm publish`; os três bugs históricos de release reprovam o gate — ADR-0024.
274
+ - [x] **Gate de coerência da doc** — a documentação não pode citar comando fantasma nem link para o
275
+ nada; verificado no CI — ADR-0025.
276
+ - [x] **TypeScript como gate** — `checkJs` estrito no CI; os contratos do núcleo tipados. Achou três
277
+ bugs latentes que nenhum teste pegava (SPEC-012, em curso).
278
+ - [x] **Boilerplate Clean Architecture calibrado** — DDD por camadas onde se paga, enxuto onde não
279
+ (`boilerplates/06-clean-arch`, ADR-0027).
280
+
281
+ **Próximos passos** (por dependência, não por desejo)
282
+
283
+ - [ ] **Fechar a migração TypeScript** — publicar `dist/` e renomear `.mjs → .ts`. Pipeline provado;
284
+ a fonte segue `.mjs` (Node ≥ 20) até lá.
285
+ - [ ] **Benchmark de token do clean-arch** — a economia é argumentada, não provada (ADR-0027):
286
+ medir a mesma feature nas duas arquiteturas via `context:smart`. Provar ou recalibrar.
287
+ - [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
288
+ `release:check` em vez de reimplementar o procedimento em prosa.
289
+ - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
290
+ - [ ] **Auditoria consultável + painel gerado** — promover `.context/forja-runs.jsonl` a tabela
291
+ FTS5, e gerar um painel de governança **estático** por comando (leitura, sem servidor — a lição
292
+ do ADR-0022, que congelou o dashboard-servidor).
262
293
 
263
294
  Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
264
295
 
@@ -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
+ }