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.
- package/CHANGELOG.md +50 -0
- package/README.en.md +310 -0
- package/README.md +37 -6
- package/bin/forja.mjs +3 -3
- package/boilerplates/06-clean-arch/README.md +48 -0
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
- package/boilerplates/06-clean-arch/backend/package.json +43 -0
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
- package/boilerplates/README.md +20 -0
- package/docs/personas/architect/README.md +4 -4
- package/docs/personas/developer/README.md +3 -3
- package/docs/personas/qa/README.md +3 -3
- package/docs/quick-reference.md +9 -9
- package/docs/structure.md +3 -3
- package/lib/core/checks.mjs +20 -3
- package/lib/core/doc-graph.mjs +231 -0
- package/lib/core/health.mjs +131 -29
- package/lib/core/registry.mjs +23 -0
- package/lib/core/release.mjs +48 -8
- package/lib/templates/harness/code-intel.mjs +2 -2
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
- package/package.json +8 -1
- package/scripts/agent-harness.mjs +7 -5
- package/scripts/context-ops.mjs +7 -4
- package/scripts/dev.mjs +2 -2
- package/scripts/hook-guard-paths.mjs +1 -0
- package/scripts/hook-user-prompt.mjs +1 -1
- package/scripts/spec-cli.mjs +4 -3
- package/scripts/tools-doctor.mjs +1 -1
- package/specs/clean-arch-boilerplate/plan.md +137 -0
- package/specs/clean-arch-boilerplate/spec.md +121 -0
- package/specs/clean-arch-boilerplate/tasks.md +70 -0
- package/specs/coerencia-do-sistema/plan.md +155 -0
- package/specs/coerencia-do-sistema/spec.md +15 -14
- package/specs/coerencia-do-sistema/tasks.md +115 -0
- package/specs/ts-migration/plan.md +188 -0
- package/specs/ts-migration/spec.md +119 -0
- 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
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
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
|
|
291
|
+
## English
|
|
264
292
|
|
|
265
|
-
|
|
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 =
|
|
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();
|