forjajs 1.1.5 → 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 +50 -0
  2. package/README.en.md +310 -0
  3. package/README.md +37 -6
  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 +8 -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,56 @@ 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
+
44
+ ## [1.1.6] — 2026-07-14 — README em inglês
45
+
46
+ A vitrine do pacote passa a ter versão em inglês, para alcançar quem chega pelo npm.
47
+
48
+ ### Adicionado
49
+ - `README.en.md` — adaptação fiel do README em português, no estilo canônico `forja <comando>`.
50
+ Seletor de idioma no topo dos dois arquivos. Incluído no `files[]` do pacote.
51
+
52
+ ### Nota
53
+ - A **documentação** (`docs/`) permanece em pt-BR — é parte da identidade do projeto. Só a capa
54
+ ganhou inglês. O README inglês foi verificado contra o registry: zero comandos inexistentes,
55
+ zero links quebrados.
56
+
7
57
  ## [1.1.5] — 2026-07-14 — O comando é forja
8
58
 
9
59
  A documentação pública ainda falava a língua interna do repo: `npm run x -- args` onde o usuário
package/README.en.md ADDED
@@ -0,0 +1,310 @@
1
+ <h1 align="center">🔨 Forja</h1>
2
+
3
+ <p align="center">
4
+ <strong>Turn coding AI into an engineering team with process and memory:<br>every project starts from a spec, every decision becomes an ADR, and nothing is lost between sessions.</strong>
5
+ </p>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/forjajs"><img src="https://img.shields.io/npm/v/forjajs?style=flat-square&color=cb3837&logo=npm" alt="npm"></a>
9
+ <img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
10
+ <img src="https://img.shields.io/badge/operation-CLI--first-3553ff?style=flat-square" alt="CLI-first">
11
+ <img src="https://img.shields.io/badge/agents-6_roles-orange?style=flat-square" alt="6 agents">
12
+ <img src="https://img.shields.io/badge/pipeline-SDD_+_GSD-teal?style=flat-square" alt="SDD+GSD">
13
+ <img src="https://img.shields.io/badge/memory-SQLite_FTS5-green?style=flat-square" alt="Memory">
14
+ <img src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 20">
15
+ <img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
16
+ <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
17
+ </p>
18
+
19
+ <p align="center"><sub>🌐 <strong>English</strong> · <a href="README.md">Português</a></sub></p>
20
+
21
+ ---
22
+
23
+ ## Why Forja exists
24
+
25
+ Coding agents are **amnesiac and undisciplined**: every session starts from zero, architecture
26
+ decisions evaporate, code drifts from intent — and if you run several products at once, you pay
27
+ that tax multiplied by N.
28
+
29
+ **Forja** is the studio around the AI. It coordinates **6 agent roles** through a
30
+ **Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)** pipeline, keeps a **hierarchical memory** indexed
31
+ in SQLite that survives across sessions, and ties it all together behind **a single core CLI with
32
+ gates and an audit trail** (`forja`, ADR-0020). Multi-AI by design (Claude, Copilot, Gemini,
33
+ Codex). Everything is driven from the CLI.
34
+
35
+ **Who it's for**: the solo dev or small team running multiple products with AI as the main
36
+ workforce — and needing the discipline of a big team without having one.
37
+
38
+ ## The 3 pillars
39
+
40
+ | Pillar | What it delivers | Proof |
41
+ |---|---|---|
42
+ | **Memory that survives** | hierarchical, searchable context, shared across sessions and AIs | SQLite FTS5, smart-context (ADR-0003) |
43
+ | **Process that governs** | nothing becomes code without a spec; nothing structural without an ADR; every command audited | SDD+GSD, 7-field handoffs (ADR-0005), `forja` core (ADR-0020) |
44
+ | **A factory, not a single project** | multi-product workspace, per-project agent teams | ADR-0019, harness, codegraph (ADR-0017) |
45
+
46
+ > This repository is the **engine (framework)** — it does not host production apps.
47
+ > Your products live in the **Forja workspace** (`~/forja-workspace` by default), outside this repo.
48
+ > See ADR-0019 for the rationale.
49
+
50
+ ## Forja in 60 seconds
51
+
52
+ ```console
53
+ $ forja spec:new pix-payments
54
+ ✓ Spec created: specs/pix-payments/spec.md # nothing becomes code without this
55
+
56
+ $ forja gsd:handoff plan pix-payments
57
+ Handoff recorded: product → sdd-architect # 7 fields, auditable (ADR-0005)
58
+
59
+ $ forja code:impact processPayment
60
+ Impact map: processPayment (depth 2) # blast radius BEFORE you edit
61
+ --- Direct callers ---
62
+ BillingController.charge · RetryWorker.run
63
+
64
+ $ forja gsd:check pix-payments
65
+ OK GSD runbook OK Spec directory
66
+ OK SDD spec check OK Codegraph
67
+ Result: baseline gates ready. # executable governance, not a checklist
68
+ ```
69
+
70
+ And each command above was recorded in `.context/forja-runs.jsonl` — when governance asks "was the
71
+ process followed?", the answer is a file, not a promise.
72
+
73
+ ## Why not just…?
74
+
75
+ | Alternative | Where it stops | What Forja adds |
76
+ |---|---|---|
77
+ | **Plain Claude Code / Copilot** | brilliant in-session, amnesiac between sessions | FTS5 memory + process + audit around the AI |
78
+ | **LangGraph / CrewAI** | infrastructure to *build* agents | the layer above: it *operates* the agent team day to day |
79
+ | **Templates & spec kits** | stop once the spec is written | the full pipeline through governance, with gates that execute |
80
+
81
+ ## Key capabilities
82
+
83
+ - **Single core CLI** — every process command goes through `forja <command>`: a declarative
84
+ registry, cross-cutting gates (workspace), and append-only audit in
85
+ `.context/forja-runs.jsonl` (ADR-0020).
86
+ - **Multi-agent orchestration** — 6 roles (orchestrator, context-engineer, sdd-architect, product,
87
+ marketing, governance) with tracked handoffs (7 fields, ADR-0005).
88
+ - **Hierarchical memory** — global → domain → task → summary, with FTS5 search and *smart-context*
89
+ in 3 modes (ADR-0003).
90
+ - **SDD + GSD pipeline** — `spec → plan → tasks → check`, decisions recorded as ADRs.
91
+ - **Project generation** — `project:new` scaffolds a full project in the workspace (memory, agents,
92
+ multi-AI instructions, a NestJS backend as the default boilerplate) and registers the project
93
+ record automatically.
94
+ - **Release gates** — `tools:doctor` fails when the core is broken (native ABI, memory, runtime
95
+ deps); `release:check` proves a clean install works before `npm publish` (ADR-0023, ADR-0024).
96
+ - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
97
+ (agent-team design), **ai-engineering** (knowledge base).
98
+
99
+ ## ⚡ Quick start
100
+
101
+ ```bash
102
+ # Install (the package is forjajs; the command is forja)
103
+ npm install -g forjajs
104
+ forja # help grouped by domain
105
+
106
+ # Prepare the production workspace (the fixed home for your projects)
107
+ forja workspace:init
108
+
109
+ # Create a new project (generated in ~/forja-workspace/projects/<name>)
110
+ forja project:new my-project --ai claude,copilot
111
+
112
+ # Enter the SDD/GSD cycle for the first feature
113
+ forja spec:new my-feature
114
+ forja spec:plan my-feature
115
+ forja spec:tasks my-feature
116
+ forja spec:check my-feature
117
+ ```
118
+
119
+ > Cloned the repo instead of installing? The same commands run as
120
+ > `node bin/forja.mjs <command>` — the npm scripts are just thin aliases of the core.
121
+
122
+ Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
123
+
124
+ ## How it works — the process
125
+
126
+ ```
127
+ 💡 Demand
128
+ ├─ project does NOT exist ─► project:new + boilerplate + harness (designs the team)
129
+ └─ project DOES exist ─────► overlay --only-memory + codegraph init (understands the code)
130
+ │
131
+ ▼
132
+ CLI-first CYCLE (docs/fluxo.md):
133
+ 1·Understand → 2·Specify → 3·Architect → 4·Decompose → 5·Implement → 6·Govern → ✅
134
+ ```
135
+
136
+ | Step | Role | Capability |
137
+ |------|------|------------|
138
+ | 1 Understand | context-engineer | codegraph · ai-engineering |
139
+ | 2 Specify | product | — |
140
+ | 3 Architect | sdd-architect | harness · ADR |
141
+ | 4 Decompose | sdd-architect | — |
142
+ | 5 Implement | orchestrator + worker | codegraph (MCP) |
143
+ | 6 Govern | governance | codegraph (`affected`) |
144
+
145
+ Full cycle map: [`docs/fluxo.md`](docs/fluxo.md).
146
+
147
+ ## The 3 integrated capabilities
148
+
149
+ | Capability | Role | How to use |
150
+ |---|---|---|
151
+ | **codegraph** | code analysis (local MCP) | `forja code:index` · `codegraph explore "<area>"` · MCP tools `codegraph_explore`/`codegraph_node` |
152
+ | **harness** | agent-team design (plugin) | in a Claude Code session: _"build a harness for this project"_ → generates `.claude/agents` + `.claude/skills` |
153
+ | **ai-engineering** | knowledge base (reference) | see [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
154
+
155
+ Details and reinstall: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
156
+
157
+ ## The `forja` core
158
+
159
+ Every process command goes through a single entry point (ADR-0020):
160
+
161
+ ```bash
162
+ forja # help grouped by domain
163
+ forja <command> [args] # in a cloned repo: node bin/forja.mjs <command>
164
+ ```
165
+
166
+ The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
167
+ records an **audit** of each run (command, args, exit code, duration) in
168
+ `<workspace>/.context/forja-runs.jsonl` — the trail governance uses at review. The repo's npm
169
+ scripts are thin aliases that route through the core.
170
+
171
+ ## Essential commands
172
+
173
+ ```bash
174
+ # Workspace & projects
175
+ forja workspace:init # create ~/forja-workspace
176
+ forja project:new <name> --ai claude,copilot # create a project in the workspace
177
+ forja project:list # list workspace projects
178
+ forja workspace:project:check <name> # validate standards in a workspace project
179
+
180
+ # SDD pipeline
181
+ forja spec:new <slug> # also: spec:plan · spec:tasks · spec:check
182
+
183
+ # Sprint & handoffs (GSD)
184
+ forja sprint:start # also: sprint:status · sprint:complete
185
+ forja gsd:plan <slug> # GSD runbook in .context/
186
+ forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
187
+ forja gsd:check <slug> # baseline runbook gates
188
+
189
+ # Code analysis (codegraph)
190
+ forja code:check # trustworthy index (worktree + freshness)
191
+ forja code:impact <symbol> # callers + blast radius before you edit
192
+ forja code:query "<term>" # also: code:index · code:sync · code:status
193
+
194
+ # Memory & context (workspace)
195
+ forja sync:universal # reindex the workspace SQLite FTS5
196
+ forja query:universal "<query>" # FTS5 search
197
+ forja context:smart # smart-context (3 modes, ADR-0003)
198
+ forja memory:compress # archive old runs + VACUUM
199
+ forja memory:extract # extract global knowledge from memory
200
+
201
+ # Quality & release
202
+ forja project:check # framework standards (pre-commit)
203
+ forja tools:doctor # core X-ray; exit 1 if broken
204
+ forja release:check --publish # tarball gate before publishing
205
+ forja project:dashboard # static status report
206
+ ```
207
+
208
+ ## Framework vs workspace separation
209
+
210
+ Forja is split in two:
211
+
212
+ 1. **Framework** (this repository): the engine, conventions, scripts, and the framework's own memory.
213
+ 2. **Workspace** (`~/forja-workspace` by default): the "fixed home" where product projects, their
214
+ universal memory, and product specs live.
215
+
216
+ The workspace path is resolved by priority:
217
+
218
+ 1. `FORJA_WORKSPACE` environment variable
219
+ 2. `workspaceRoot` field in `~/.forjarc.json`
220
+ 3. Default: `~/forja-workspace`
221
+
222
+ See ADR-0019 for the architectural decision.
223
+
224
+ ## Repository structure (framework)
225
+
226
+ ```
227
+ bin/ CLIs (init-project, create-memory-nest-kit)
228
+ lib/ Reusable modules (workspace, generators, validators, context-builder)
229
+ scripts/ Automation (sprint-manager, agent-router, sync-universal-memory, …)
230
+ specs/ The framework's own SDD pipeline (spec → plan → tasks)
231
+ boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
232
+ memory/ Framework memory (00-global … 90-decisions/ADRs)
233
+ docs/ Documentation by persona and by topic (see DOC-MAP.md)
234
+ prompts/ Portable prompts for the 6 roles
235
+ .claude/ Claude Code sub-agents and settings
236
+ projects/ LEGACY — do not use; projects live in the external workspace
237
+ ```
238
+
239
+ ## Workspace structure
240
+
241
+ ```
242
+ ~/forja-workspace/
243
+ projects/ # generated products
244
+ memory/
245
+ sqlite/universal.db # SQLite FTS5 for the products
246
+ 30-projects/ # project records
247
+ specs/ # product specs
248
+ .context/ # product GSD runbooks
249
+ README.md
250
+ ```
251
+
252
+ ## Documentation
253
+
254
+ The docs are written in **Brazilian Portuguese** — that's part of the project's identity. The CLI
255
+ output, code, and ADRs are readable regardless of language.
256
+
257
+ - [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
258
+ - [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
259
+ - [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
260
+ - [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
261
+ - [`memory/90-decisions/`](memory/90-decisions/) — ADRs with rationale
262
+ - [`CHANGELOG.md`](CHANGELOG.md) — history
263
+
264
+ ## Conventions
265
+
266
+ - **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
267
+ - **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
268
+ - **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
269
+ - **pt-BR** — communication and documentation in Portuguese.
270
+
271
+ ## Roadmap
272
+
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).
300
+
301
+ Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
302
+
303
+ ---
304
+
305
+ <p align="center">
306
+ <strong>Did Forja help you tame your agents?</strong><br>
307
+ A ⭐ is what carries the project to more devs still paying the amnesiac-AI tax.
308
+ </p>
309
+
310
+ <p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contributing</a></sub></p>
package/README.md CHANGED
@@ -16,6 +16,8 @@
16
16
  <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
17
17
  </p>
18
18
 
19
+ <p align="center"><sub>🌐 <a href="README.en.md">English</a> · <strong>Português</strong></sub></p>
20
+
19
21
  ---
20
22
 
21
23
  ## Por que a Forja existe
@@ -184,6 +186,7 @@ forja sync:universal # reindexa SQLite FTS5 do workspace
184
186
  forja query:universal "<query>" # busca FTS5
185
187
  forja context:smart # smart-context (3 modos, ADR-0003)
186
188
  forja memory:compress # arquiva runs antigos + VACUUM
189
+ forja memory:extract # extrai conhecimento global da memória
187
190
 
188
191
  # Qualidade & release
189
192
  forja project:check # standards do framework (pre-commit)
@@ -253,16 +256,44 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
253
256
 
254
257
  ## Roadmap
255
258
 
256
- - [ ] **Core fase 2** — CLI `forja` embutida nos projetos gerados (hoje herdam harness + instruções)
257
- - [ ] **Auditoria no SQLite** — promover `forja-runs.jsonl` a tabela consultável via FTS5
258
- - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás
259
- - [ ] **Docs em inglês** — pt-BR continua sendo a língua do projeto
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).
260
288
 
261
289
  Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
262
290
 
263
- ## English summary
291
+ ## English
264
292
 
265
- **Forja** turns coding AI into an engineering team with process and memory: every project starts from a spec, every structural decision becomes an ADR, and nothing is lost between sessions. It orchestrates 6 agent roles through a Spec-Driven + GSD pipeline, keeps hierarchical memory indexed in SQLite FTS5, routes every command through a single audited core CLI (`forja`), and works with Claude, Copilot, Gemini and Codex by design. Documentation is in Brazilian Portuguese — that's part of the project's identity; the CLI and the code are readable regardless.
293
+ Full English version: **[README.en.md](README.en.md)**. In short — **Forja** turns coding AI into an
294
+ engineering team with process and memory: every project starts from a spec, every structural
295
+ decision becomes an ADR, and nothing is lost between sessions. Documentation is in Brazilian
296
+ Portuguese — that's part of the project's identity; the CLI and the code are readable regardless.
266
297
 
267
298
  ---
268
299
 
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();