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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forjajs",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
".github/copilot-instructions.md",
|
|
28
28
|
".memoryrc.json",
|
|
29
29
|
"AGENTS.md",
|
|
30
|
+
"README.en.md",
|
|
30
31
|
"DOC-MAP.md",
|
|
31
32
|
"CHANGELOG.md",
|
|
32
33
|
"CONTRIBUTING.md",
|
|
@@ -84,6 +85,8 @@
|
|
|
84
85
|
"code:impact": "node bin/forja.mjs code:impact",
|
|
85
86
|
"tools:doctor": "node bin/forja.mjs tools:doctor",
|
|
86
87
|
"release:check": "node bin/forja.mjs release:check",
|
|
88
|
+
"build": "tsc -p tsconfig.build.json",
|
|
89
|
+
"types:check": "tsc --noEmit",
|
|
87
90
|
"test": "node --test test/*.test.js"
|
|
88
91
|
},
|
|
89
92
|
"keywords": [
|
|
@@ -107,5 +110,9 @@
|
|
|
107
110
|
},
|
|
108
111
|
"allowScripts": {
|
|
109
112
|
"better-sqlite3@12.11.1": true
|
|
113
|
+
},
|
|
114
|
+
"devDependencies": {
|
|
115
|
+
"@types/node": "^26.1.1",
|
|
116
|
+
"typescript": "^5.9.3"
|
|
110
117
|
}
|
|
111
118
|
}
|
|
@@ -94,10 +94,10 @@ function readText(file) {
|
|
|
94
94
|
|
|
95
95
|
function runCodegraph(args) {
|
|
96
96
|
const result = spawnSync('codegraph', args, { cwd: root, encoding: 'utf8' });
|
|
97
|
-
if (result.error && result.error.code === 'ENOENT') {
|
|
97
|
+
if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') {
|
|
98
98
|
return { missing: true };
|
|
99
99
|
}
|
|
100
|
-
if (result.error && result.error.code === 'EPERM') {
|
|
100
|
+
if (result.error && /** @type {any} */ (result.error).code === 'EPERM') {
|
|
101
101
|
const quote = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
|
|
102
102
|
const fallback = spawnSync('/bin/sh', ['-lc', ['codegraph', ...args.map(quote)].join(' ')], {
|
|
103
103
|
cwd: root,
|
|
@@ -125,7 +125,7 @@ function codegraphStatus() {
|
|
|
125
125
|
if (res.missing) return { missing: true };
|
|
126
126
|
let data = null;
|
|
127
127
|
try {
|
|
128
|
-
data = JSON.parse(res.stdout);
|
|
128
|
+
data = JSON.parse(/** @type {string} */ (res.stdout));
|
|
129
129
|
} catch {
|
|
130
130
|
return { missing: false, parseError: true, raw: res.stdout || res.stderr };
|
|
131
131
|
}
|
|
@@ -533,7 +533,9 @@ Design / Code intelligence:
|
|
|
533
533
|
`);
|
|
534
534
|
}
|
|
535
535
|
|
|
536
|
-
const [command, ...
|
|
536
|
+
const [command, ...rest] = process.argv.slice(2);
|
|
537
|
+
/** dispatch heterogêneo: cada cmd consome os args do seu jeito (Fase 1) */
|
|
538
|
+
const args = /** @type {any} */ (rest);
|
|
537
539
|
|
|
538
540
|
switch (command) {
|
|
539
541
|
case 'workspace:init':
|
|
@@ -567,7 +569,7 @@ switch (command) {
|
|
|
567
569
|
cmdGsdCheck(args);
|
|
568
570
|
break;
|
|
569
571
|
case 'code:check':
|
|
570
|
-
cmdCodeCheck(
|
|
572
|
+
cmdCodeCheck();
|
|
571
573
|
break;
|
|
572
574
|
case 'code:impact':
|
|
573
575
|
cmdCodeImpact(args);
|
package/scripts/context-ops.mjs
CHANGED
|
@@ -4,7 +4,7 @@ import fs from 'node:fs';
|
|
|
4
4
|
import path from 'node:path';
|
|
5
5
|
import Database from 'better-sqlite3';
|
|
6
6
|
import { fileURLToPath } from 'node:url';
|
|
7
|
-
import { ensureSchema,
|
|
7
|
+
import { ensureSchema, getDbPath } from './memory-schema.mjs';
|
|
8
8
|
|
|
9
9
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
10
10
|
const root = path.resolve(__dirname, '..');
|
|
@@ -77,9 +77,10 @@ function listSpecs() {
|
|
|
77
77
|
|
|
78
78
|
function openDb() {
|
|
79
79
|
ensureSchema({ silent: true });
|
|
80
|
-
return new Database(
|
|
80
|
+
return new Database(getDbPath(), { timeout: 5000 });
|
|
81
81
|
}
|
|
82
82
|
|
|
83
|
+
/** @param {number|null} [limitTokens] */
|
|
83
84
|
function recordContextRun(kind, slug, filePath, content, limitTokens = null) {
|
|
84
85
|
const db = openDb();
|
|
85
86
|
const tokens = estimateTokens(content);
|
|
@@ -116,7 +117,7 @@ function upsertSpecSummary(slug, content) {
|
|
|
116
117
|
}
|
|
117
118
|
|
|
118
119
|
function getOpenHandoffs(slug = null) {
|
|
119
|
-
if (!fs.existsSync(
|
|
120
|
+
if (!fs.existsSync(getDbPath())) return [];
|
|
120
121
|
const db = openDb();
|
|
121
122
|
let rows;
|
|
122
123
|
try {
|
|
@@ -450,7 +451,9 @@ Comandos:
|
|
|
450
451
|
`);
|
|
451
452
|
}
|
|
452
453
|
|
|
453
|
-
const [cmd, ...
|
|
454
|
+
const [cmd, ...rest] = process.argv.slice(2);
|
|
455
|
+
/** dispatch heterogêneo: cada cmd consome os args do seu jeito (Fase 1) */
|
|
456
|
+
const args = /** @type {any} */ (rest);
|
|
454
457
|
switch (cmd) {
|
|
455
458
|
case 'budget': cmdBudget(args); break;
|
|
456
459
|
case 'sprint-pack': cmdSprintPack(); break;
|
package/scripts/dev.mjs
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
import fs from 'node:fs';
|
|
18
18
|
import path from 'node:path';
|
|
19
|
-
import { spawnSync } from 'node:child_process';
|
|
19
|
+
import { spawn, spawnSync } from 'node:child_process';
|
|
20
20
|
import { fileURLToPath } from 'node:url';
|
|
21
21
|
import { getDbPath, ensureSchema } from './memory-schema.mjs';
|
|
22
22
|
|
|
@@ -119,7 +119,7 @@ Exemplos:
|
|
|
119
119
|
* Run subprocess
|
|
120
120
|
*/
|
|
121
121
|
function runScript(scriptPath, args = []) {
|
|
122
|
-
return new Promise((resolve, reject) => {
|
|
122
|
+
return new Promise((/** @type {(v?: unknown) => void} */ resolve, reject) => {
|
|
123
123
|
const proc = spawn('node', [scriptPath, ...args], {
|
|
124
124
|
stdio: 'inherit',
|
|
125
125
|
cwd: root,
|
|
@@ -110,7 +110,7 @@ function buildTaskContext(slug, capBytes) {
|
|
|
110
110
|
[`specs/${slug}/tasks.md`, 2500],
|
|
111
111
|
[`.context/gsd-${slug}.md`, 1500],
|
|
112
112
|
];
|
|
113
|
-
for (const [rel, sliceCap] of candidates) {
|
|
113
|
+
for (const [rel, sliceCap] of /** @type {[string, number][]} */ (candidates)) {
|
|
114
114
|
try {
|
|
115
115
|
const c = fs.readFileSync(path.join(root, rel), 'utf8');
|
|
116
116
|
pieces.push(`### ${rel}\n\n${c.slice(0, sliceCap)}`);
|
package/scripts/spec-cli.mjs
CHANGED
|
@@ -28,6 +28,7 @@ const STAGES = ['spec', 'plan', 'tasks'];
|
|
|
28
28
|
const STATUS_RE = /-\s*\*\*Status\*\*:\s*([a-z]+)[^\n]*/i;
|
|
29
29
|
const VALID_STATUSES = ['draft', 'review', 'approved', 'implementing', 'done', 'abandoned'];
|
|
30
30
|
|
|
31
|
+
/** @returns {never} */
|
|
31
32
|
function fail(msg) {
|
|
32
33
|
fs.writeSync(2, `[spec-cli] ${msg}\n`);
|
|
33
34
|
process.exit(1);
|
|
@@ -178,7 +179,7 @@ function cmdNextStage(stage, feature) {
|
|
|
178
179
|
|
|
179
180
|
function checkFeature(slug) {
|
|
180
181
|
const dir = path.join(specsDir, slug);
|
|
181
|
-
const result = { slug, stages: {}, ok: true, errors: [] };
|
|
182
|
+
const result = { slug, stages: /** @type {Record<string,string|null>} */ ({}), ok: true, errors: /** @type {string[]} */ ([]) };
|
|
182
183
|
for (const stage of STAGES) {
|
|
183
184
|
const status = readStatus(path.join(dir, `${stage}.md`));
|
|
184
185
|
result.stages[stage] = status;
|
|
@@ -191,11 +192,11 @@ function checkFeature(slug) {
|
|
|
191
192
|
result.ok = false;
|
|
192
193
|
result.errors.push('spec.md ausente');
|
|
193
194
|
}
|
|
194
|
-
if (result.stages.plan && !ALLOWS_NEXT_STAGE.includes(result.stages.spec)) {
|
|
195
|
+
if (result.stages.plan && !ALLOWS_NEXT_STAGE.includes(result.stages.spec ?? '')) {
|
|
195
196
|
result.ok = false;
|
|
196
197
|
result.errors.push(`plan.md existe mas spec status = ${result.stages.spec}`);
|
|
197
198
|
}
|
|
198
|
-
if (result.stages.tasks && !ALLOWS_NEXT_STAGE.includes(result.stages.plan)) {
|
|
199
|
+
if (result.stages.tasks && !ALLOWS_NEXT_STAGE.includes(result.stages.plan ?? '')) {
|
|
199
200
|
result.ok = false;
|
|
200
201
|
result.errors.push(`tasks.md existe mas plan status = ${result.stages.plan}`);
|
|
201
202
|
}
|
package/scripts/tools-doctor.mjs
CHANGED
|
@@ -62,7 +62,7 @@ const TOOLS = [
|
|
|
62
62
|
|
|
63
63
|
function detect(cmd, args) {
|
|
64
64
|
const res = spawnSync(cmd, args, { encoding: 'utf8' });
|
|
65
|
-
if (res.error && res.error.code === 'ENOENT') return { ok: false };
|
|
65
|
+
if (res.error && /** @type {any} */ (res.error).code === 'ENOENT') return { ok: false };
|
|
66
66
|
const version = (res.stdout || res.stderr || '').trim().split('\n')[0] || 'instalado';
|
|
67
67
|
return { ok: true, version };
|
|
68
68
|
}
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Plan: clean-arch-boilerplate
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-07-18
|
|
6
|
+
|
|
7
|
+
> Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
|
|
8
|
+
|
|
9
|
+
## 1. Abordagem técnica
|
|
10
|
+
|
|
11
|
+
Um boilerplate NestJS + TypeScript com a **regra de dependência para dentro** (Clean Architecture /
|
|
12
|
+
Hexagonal). A fatia rica é **Order** (invariante: não confirma sem estoque, não envia sem
|
|
13
|
+
pagamento) — vive no domínio, testável sem Nest. O contraponto enxuto é **Product** (CRUD),
|
|
14
|
+
demonstrando o caminho de 1 camada. O `WHEN-CLEAN-WHEN-LEAN.md` é o coração da spec: ensina o
|
|
15
|
+
critério, não a ceremônia.
|
|
16
|
+
|
|
17
|
+
O mecanismo de inversão no Nest: a **porta é uma `interface` no domínio + um token de injeção**; o
|
|
18
|
+
adapter (repo ORM) a implementa; o módulo faz o bind `{ provide: ORDER_REPO, useClass: TypeOrmOrderRepo }`.
|
|
19
|
+
O use-case injeta a porta, nunca o adapter. É o padrão documentado uma vez e repetido.
|
|
20
|
+
|
|
21
|
+
## 2. Estrutura de diretórios (o contrato visual)
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
boilerplates/06-clean-arch/
|
|
25
|
+
backend/src/
|
|
26
|
+
modules/orders/ # FATIA RICA — as 4 camadas
|
|
27
|
+
domain/
|
|
28
|
+
order.entity.ts # agregado: invariantes vivem aqui (pure TS, zero Nest/ORM)
|
|
29
|
+
order-status.vo.ts # value object (máquina de estados)
|
|
30
|
+
order.repository.ts # PORTA (interface) + token ORDER_REPOSITORY
|
|
31
|
+
application/
|
|
32
|
+
place-order.usecase.ts # input/output tipados; orquestra domínio + porta
|
|
33
|
+
ship-order.usecase.ts
|
|
34
|
+
dtos.ts # contratos de aplicação (não HTTP)
|
|
35
|
+
infrastructure/
|
|
36
|
+
typeorm-order.repository.ts # ADAPTER: implementa a porta
|
|
37
|
+
order.orm-entity.ts # entity do ORM (mapper domínio↔persistência)
|
|
38
|
+
presentation/
|
|
39
|
+
orders.controller.ts # HTTP DTOs + mapeia p/ use-case
|
|
40
|
+
orders.http.dto.ts
|
|
41
|
+
orders.module.ts # bind porta→adapter (inversão)
|
|
42
|
+
modules/products/ # CAMINHO ENXUTO — CRUD, 1 camada
|
|
43
|
+
products.controller.ts # controller → repo direto; sem use-case/porta
|
|
44
|
+
product.entity.ts
|
|
45
|
+
products.module.ts
|
|
46
|
+
shared/ # Result/Either, base VO, erros de domínio
|
|
47
|
+
main.ts · app.module.ts
|
|
48
|
+
backend/test/
|
|
49
|
+
orders/place-order.spec.ts # testa a INVARIANTE sem subir o Nest (AC-8)
|
|
50
|
+
memory/30-domains/orders/context.md # linguagem ubíqua — o agente lê ISTO antes do código
|
|
51
|
+
memory/30-domains/products/context.md
|
|
52
|
+
WHEN-CLEAN-WHEN-LEAN.md # o critério de calibração
|
|
53
|
+
boilerplate.manifest.json · README.md
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
O `orders/` e o `products/` lado a lado **são** a spec: um mostra Clean Architecture onde se paga, o
|
|
57
|
+
outro mostra o custo evitado. O dev/agente vê os dois e entende o critério pela estrutura.
|
|
58
|
+
|
|
59
|
+
## 3. Fluxo de dependência (a regra)
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
presentation ─┐
|
|
63
|
+
├─► application ─► domain ◄─ (ports: interfaces)
|
|
64
|
+
infrastructure┘ ▲
|
|
65
|
+
(adapters implementam ports) ─┘
|
|
66
|
+
dependências apontam p/ DENTRO. domain não importa nada de fora.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## 4. Contratos (o que se lê sem a implementação)
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
// domain/order.repository.ts — a PORTA
|
|
73
|
+
export const ORDER_REPOSITORY = Symbol('OrderRepository');
|
|
74
|
+
export interface OrderRepository {
|
|
75
|
+
save(order: Order): Promise<void>;
|
|
76
|
+
byId(id: OrderId): Promise<Order | null>;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// application/place-order.usecase.ts — o contrato legível (AC-5)
|
|
80
|
+
export interface PlaceOrderInput { customerId: string; items: OrderLine[]; }
|
|
81
|
+
export interface PlaceOrderOutput { orderId: string; total: Money; }
|
|
82
|
+
// a assinatura basta para o agente saber o que a feature faz — sem ler o corpo
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## 5. Decisões e alternativas
|
|
86
|
+
|
|
87
|
+
**D1: Order como fatia rica.** Invariante cross-aggregate universal e reconhecível ("não envia sem
|
|
88
|
+
pagamento"). Alternativa (Subscription/máquina de estados) é boa mas menos imediata; fica como VO
|
|
89
|
+
dentro de Order (`order-status.vo.ts`), aproveitando os dois.
|
|
90
|
+
|
|
91
|
+
**D2: Product como caminho enxuto — lado a lado, não escondido.** A calibração precisa ser *visível*.
|
|
92
|
+
Um CRUD que atravessa controller→repo direto, sem use-case nem porta, no mesmo boilerplate. É o AC-4
|
|
93
|
+
materializado em código, não só no doc.
|
|
94
|
+
|
|
95
|
+
**D3: Porta = interface no domínio + token Nest.** O domínio define o contrato; o Nest só faz o bind.
|
|
96
|
+
Alternativa rejeitada: repositório abstrato como classe base (acopla o domínio ao mecanismo de
|
|
97
|
+
herança e, na prática, ao Nest). Interface + token mantém o domínio puro.
|
|
98
|
+
|
|
99
|
+
**D4: Domínio puro, zero `@nestjs` e zero ORM.** É o que torna o teste-sem-Nest (AC-8) possível e é a
|
|
100
|
+
prova concreta do isolamento. O ORM vive só em `infrastructure/`, com mapper explícito
|
|
101
|
+
domínio↔orm-entity. Sem `@Entity` decorando o agregado de domínio.
|
|
102
|
+
|
|
103
|
+
**D5: Memória por contexto é o vetor de token (AC-6).** `context.md` descreve o domínio na linguagem
|
|
104
|
+
ubíqua. O agente lê ele + a assinatura do use-case; só desce ao código quando vai *editar*. É onde a
|
|
105
|
+
economia de token se materializa — e onde a mediremos.
|
|
106
|
+
|
|
107
|
+
**D6: Aditivo, sem tocar 01-05.** Novo diretório, novo manifesto. Os geradores existentes não mudam;
|
|
108
|
+
só o catálogo de boilerplates ganha uma entrada.
|
|
109
|
+
|
|
110
|
+
D1–D5 são estruturais → **ADR-0027** (Clean Architecture calibrada; o porquê da calibração e do token).
|
|
111
|
+
|
|
112
|
+
## 6. Dependências
|
|
113
|
+
|
|
114
|
+
- **Specs**: SPEC-012 (TS) — o domínio é tipado; alinhado, não bloqueante.
|
|
115
|
+
- **Pacotes** (do projeto *gerado*, não do Forja): `@nestjs/*`, `typeorm`, `jest`. Ficam no
|
|
116
|
+
`package.json` do boilerplate — e por isso entram na allowlist derivada do `docs-commands` (SPEC-011).
|
|
117
|
+
- **Migrações**: nenhuma no framework.
|
|
118
|
+
|
|
119
|
+
## 7. Rollout
|
|
120
|
+
|
|
121
|
+
- [ ] Esqueleto + `shared/` (Result, erros de domínio, base VO) primeiro.
|
|
122
|
+
- [ ] Fatia rica Orders (domain → application → infra → presentation), com o teste-sem-Nest a cada camada.
|
|
123
|
+
- [ ] Caminho enxuto Products.
|
|
124
|
+
- [ ] Memória por contexto + `WHEN-CLEAN-WHEN-LEAN.md`.
|
|
125
|
+
- [ ] Manifesto + entrada no catálogo + `boilerplates/README.md`.
|
|
126
|
+
- [ ] **Medir (AC-6/métrica-norte)**: `context:smart` para "adicionar regra ao contexto orders" aqui
|
|
127
|
+
vs. no `02-saas-starter` flat. Registrar os números no ADR. Se não cair, recalibra antes de fechar.
|
|
128
|
+
- [ ] Gates: `release:check` (boilerplate no `files[]`, instala limpo), `tools:doctor` (coerência de doc).
|
|
129
|
+
|
|
130
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
131
|
+
|
|
132
|
+
- **O caminho enxuto não existe de verdade** — se no fim tudo virou 4 camadas, a spec falhou (o
|
|
133
|
+
cargo-cult que ela existe para evitar). Products tem que ser genuinamente 1 camada.
|
|
134
|
+
- **O token não cai** (AC-6). Se o pacote de contexto não encolher vs. o flat, a arquitetura virou
|
|
135
|
+
custo. Reconhecer e recalibrar, não maquiar.
|
|
136
|
+
- **O domínio importa `@nestjs` ou ORM.** Qualquer import de framework no `domain/` quebra a premissa
|
|
137
|
+
inteira; o teste-sem-Nest é o detector.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# Spec: clean-arch-boilerplate
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-013
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-18
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens), [ADR-0016](../../memory/90-decisions/0016-integracao-capacidades-externas.md) (harness), [ADR-0001](../../memory/90-decisions/0001-memoria-hierarquica.md) (memória hierárquica)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
Os boilerplates atuais são **NestJS-flat**: `modules/<x>/{controller, service, entities, dto}`, com o
|
|
13
|
+
service falando direto com a entity do TypeORM. A infraestrutura (ORM) vaza para dentro da regra de
|
|
14
|
+
negócio, não há inversão de dependência, e a regra de domínio — quando existe — fica presa dentro de
|
|
15
|
+
um `service` acoplado ao framework. Isso cobra dois preços:
|
|
16
|
+
|
|
17
|
+
1. **De manutenção**: trocar ORM, testar regra sem subir o Nest, ou mover uma invariante para onde
|
|
18
|
+
ela pertence exige cirurgia.
|
|
19
|
+
2. **De tokens** — o que mais importa aqui (ADR-0009). Um agente que opera um projeto flat precisa
|
|
20
|
+
**ler a implementação inteira** para entender o que uma feature faz, porque a regra está diluída
|
|
21
|
+
no service junto do acesso a dados e do HTTP. Não há contrato legível separado da execução.
|
|
22
|
+
|
|
23
|
+
Ao mesmo tempo, a resposta ingênua — "aplicar Clean Architecture" — tem um preço oposto e igualmente
|
|
24
|
+
real: **quatro camadas para um CRUD são mais arquivos para ler, não menos.** Um boilerplate que força
|
|
25
|
+
use-case + porta + adapter + mapper por endpoint trivial é o anti-padrão de token que estamos tentando
|
|
26
|
+
evitar, com nome bonito.
|
|
27
|
+
|
|
28
|
+
## 2. Proposta de valor
|
|
29
|
+
|
|
30
|
+
Um boilerplate Clean Architecture que **sabe quando NÃO ser Clean Architecture.** Camadas ricas onde
|
|
31
|
+
há regra de negócio de verdade; caminho enxuto explícito onde é CRUD. Estruturado para **navegação
|
|
32
|
+
barata por agente**: o contrato de um use-case se lê pela assinatura de tipo, não pela implementação;
|
|
33
|
+
cada bounded context tem um doc de memória na linguagem ubíqua que o agente lê **em vez** do código.
|
|
34
|
+
Arquitetura como compressão de contexto, não como cerimônia.
|
|
35
|
+
|
|
36
|
+
## 3. User stories
|
|
37
|
+
|
|
38
|
+
- **Como** dev iniciando um produto, **quero** um esqueleto com domínio isolado de framework e ORM,
|
|
39
|
+
**para que** a regra de negócio seja testável e sobreviva a troca de infraestrutura.
|
|
40
|
+
- **Como** agente operando o projeto gerado, **quero** ler o contrato tipado de um use-case e o doc
|
|
41
|
+
de contexto do módulo, **para que** eu entenda a feature sem carregar a implementação inteira —
|
|
42
|
+
menos tokens por tarefa.
|
|
43
|
+
- **Como** dev com uma feature CRUD trivial, **quero** um caminho enxuto documentado, **para que** eu
|
|
44
|
+
não pague 4 camadas por um `GET /x`.
|
|
45
|
+
- **Como** arquiteto, **quero** uma fatia vertical rica de referência (com invariante de negócio de
|
|
46
|
+
verdade), **para que** o padrão Clean Architecture seja demonstrado onde ele se paga, não abstrato.
|
|
47
|
+
|
|
48
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
49
|
+
|
|
50
|
+
- [ ] AC-1: Novo boilerplate `boilerplates/06-clean-arch/` com as 4 camadas e a **regra de
|
|
51
|
+
dependência** para dentro: `domain` (puro: entities, value objects, ports/interfaces — zero
|
|
52
|
+
NestJS, zero ORM) → `application` (use-cases orquestrando domínio + portas) → `infrastructure`
|
|
53
|
+
(adapters: repos ORM, mappers, serviços externos) + `presentation` (controllers, DTOs HTTP).
|
|
54
|
+
- [ ] AC-2: **Inversão de dependência real** via DI do NestJS: as portas são tokens de injeção
|
|
55
|
+
(`interface` no domínio), os adapters as implementam e são bound no módulo. O use-case depende
|
|
56
|
+
da porta, nunca da implementação.
|
|
57
|
+
- [ ] AC-3: **Fatia vertical rica de referência** — um bounded context com invariante de negócio
|
|
58
|
+
genuína (não CRUD) que vive **no domínio** (ex.: um `Order` que não pode ser enviado sem
|
|
59
|
+
pagamento; ou `Subscription` como máquina de estados). Prova que a separação se paga.
|
|
60
|
+
- [ ] AC-4: **Caminho enxuto explícito** (a calibração). Um módulo CRUD simples demonstrado com o
|
|
61
|
+
mínimo de camadas, e um doc `WHEN-CLEAN-WHEN-LEAN.md` que ensina o critério de escolha. O
|
|
62
|
+
boilerplate não força ceremônia.
|
|
63
|
+
- [ ] AC-5: **Contratos legíveis** — todo use-case tem input/output tipados (TS) que se leem sem a
|
|
64
|
+
implementação. O domínio é a linguagem ubíqua tipada.
|
|
65
|
+
- [ ] AC-6: **Memória por bounded context** (ADR-0001): cada contexto tem um doc em
|
|
66
|
+
`memory/30-domains/<ctx>/context.md` na linguagem ubíqua, que o agente lê **antes** do código.
|
|
67
|
+
Medir: o pacote de contexto de uma tarefa cai vs. o boilerplate flat (ADR-0009).
|
|
68
|
+
- [ ] AC-7: Manifesto (`boilerplate.manifest.json`) + integração com o gerador (o boilerplate aparece
|
|
69
|
+
como opção, gera com a memória e os agentes multi-IA como os outros).
|
|
70
|
+
- [ ] AC-8: **Testes de domínio sem framework**: a invariante da AC-3 tem teste unitário que roda
|
|
71
|
+
**sem subir o Nest** — a prova concreta de que o domínio está isolado.
|
|
72
|
+
- [ ] AC-9: O boilerplate passa pelos gates do próprio Forja: `release:check` (está no `files[]`,
|
|
73
|
+
instala limpo) e a coerência de doc (SPEC-011) não acusa comando fantasma nos seus docs.
|
|
74
|
+
- [ ] AC-10: ADR registrando a decisão (Clean Architecture calibrada como boilerplate; o *porquê* da
|
|
75
|
+
calibração e do ângulo de token).
|
|
76
|
+
|
|
77
|
+
## 5. Escopo
|
|
78
|
+
|
|
79
|
+
**Dentro**:
|
|
80
|
+
- `boilerplates/06-clean-arch/` completo: as 4 camadas, a fatia rica, o módulo enxuto, o
|
|
81
|
+
`WHEN-CLEAN-WHEN-LEAN.md`, a memória por contexto, o manifesto.
|
|
82
|
+
- Integração com o gerador (`lib/generators/`) para o boilerplate ser selecionável.
|
|
83
|
+
- ADR + a atualização de `boilerplates/README.md`.
|
|
84
|
+
|
|
85
|
+
**Fora** (explícito):
|
|
86
|
+
- **Refatorar os boilerplates existentes** (01-05). Eles ficam; este é aditivo. Migrar os antigos é
|
|
87
|
+
outra decisão.
|
|
88
|
+
- **Aplicar Clean Architecture ao framework Forja.** Decidido: over-engineering para um CLI; o
|
|
89
|
+
framework ganha só modelos de domínio tipados, e isso ride na migração TS (SPEC-012), não aqui.
|
|
90
|
+
- **Frontend.** Este boilerplate é backend (NestJS). Um par frontend é outra spec.
|
|
91
|
+
- **Prescrever ORM único.** O ponto é o domínio não saber do ORM; qual ORM o adapter usa é detalhe do
|
|
92
|
+
boilerplate, não da arquitetura.
|
|
93
|
+
|
|
94
|
+
## 6. NFRs / restrições
|
|
95
|
+
|
|
96
|
+
- **Token-first (a régua)**: o ganho tem que ser *medível*. AC-6 exige comparar o pacote de contexto
|
|
97
|
+
de uma tarefa-tipo neste boilerplate vs. no flat. Se não cair, a arquitetura virou custo, não
|
|
98
|
+
economia — e aí recalibra.
|
|
99
|
+
- **Calibração inegociável**: a existência do caminho enxuto (AC-4) é o que separa esta spec de um
|
|
100
|
+
cargo-cult. Sem ele, reprovado.
|
|
101
|
+
- **TypeScript**: alinhado com a migração em curso (SPEC-012) — o domínio é tipado de primeira classe.
|
|
102
|
+
- **Compatibilidade**: aditivo; não muda os geradores dos boilerplates existentes.
|
|
103
|
+
|
|
104
|
+
## 7. Riscos e mitigação
|
|
105
|
+
|
|
106
|
+
| Risco | Prob | Impacto | Mitigação |
|
|
107
|
+
|---|---|---|---|
|
|
108
|
+
| Vira cargo-cult: 4 camadas por CRUD, +tokens | **A** | A | AC-4 (caminho enxuto) + AC-6 (medir tokens) são gate; sem eles, reprova |
|
|
109
|
+
| Complexidade assusta o dev/agente | M | M | A fatia rica é 1 só; o resto é enxuto. `WHEN-CLEAN-WHEN-LEAN.md` guia |
|
|
110
|
+
| Inversão de dependência no Nest fica verbosa | M | M | Padrão de porta-como-token documentado uma vez; repetível |
|
|
111
|
+
| O ganho de token não se materializa | M | A | Medir cedo (AC-6). Se não cair, a spec falhou seu propósito — honesto reconhecer |
|
|
112
|
+
|
|
113
|
+
## 8. Métricas de sucesso
|
|
114
|
+
|
|
115
|
+
- **Tokens por tarefa** num projeto gerado com este boilerplate **caem** vs. o flat, para uma
|
|
116
|
+
tarefa-tipo ("adicionar uma regra ao contexto X") — medido via `context:smart`/`token:benchmark`.
|
|
117
|
+
É a métrica-norte; sem ela a arquitetura não se justifica.
|
|
118
|
+
- Um dev pega a fatia rica e adiciona uma invariante de negócio **sem tocar em infraestrutura**.
|
|
119
|
+
- A invariante de domínio é testável **sem subir o Nest** (AC-8).
|
|
120
|
+
- 90 dias depois: os projetos novos do usuário escolhem este boilerplate quando há regra de negócio,
|
|
121
|
+
e o flat quando é CRUD puro — a calibração usada na prática, não só documentada.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Tasks: clean-arch-boilerplate
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-07-18
|
|
7
|
+
|
|
8
|
+
> Decomposição executável. O boilerplate é **conteúdo de template** (código do projeto gerado), não
|
|
9
|
+
> código do framework — não roda na CI do Forja. Escrever para ser referência idiomática correta.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## T1 — Esqueleto + `shared/`
|
|
14
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: —
|
|
15
|
+
- **Paths**: `boilerplates/06-clean-arch/backend/src/{shared,main.ts,app.module.ts}`
|
|
16
|
+
- **Done**: `Result`/erros de domínio/base VO; `main.ts`/`app.module.ts`; `package.json` + `tsconfig`
|
|
17
|
+
do projeto (com `test:e2e`, `start:dev` etc. — entram na allowlist derivada do SPEC-011).
|
|
18
|
+
|
|
19
|
+
## T2 — Fatia rica: Orders (as 4 camadas) — AC-1/2/3/5
|
|
20
|
+
- **Owner**: Worker · **Estimativa**: M · **Depende de**: T1
|
|
21
|
+
- **Paths**: `.../modules/orders/{domain,application,infrastructure,presentation}/*`, `orders.module.ts`
|
|
22
|
+
- **Done**:
|
|
23
|
+
- [ ] `domain/`: `Order` (agregado, invariantes: não confirma sem estoque, não envia sem pagamento),
|
|
24
|
+
`order-status.vo.ts`, `order.repository.ts` (porta = interface + token). **Zero `@nestjs`/ORM.**
|
|
25
|
+
- [ ] `application/`: `place-order`/`ship-order` use-cases com input/output tipados (contrato legível).
|
|
26
|
+
- [ ] `infrastructure/`: adapter TypeORM implementa a porta + mapper domínio↔orm-entity.
|
|
27
|
+
- [ ] `presentation/`: controller + HTTP DTOs mapeando p/ use-case.
|
|
28
|
+
- [ ] `orders.module.ts`: bind `{ provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository }`.
|
|
29
|
+
|
|
30
|
+
## T3 — Teste da invariante sem Nest — AC-8
|
|
31
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T2
|
|
32
|
+
- **Paths**: `.../backend/test/orders/place-order.spec.ts`
|
|
33
|
+
- **Done**: testa a invariante de domínio **instanciando só o agregado** (sem `Test.createTestingModule`,
|
|
34
|
+
sem ORM). É a prova concreta do isolamento — se precisar do Nest, o domínio vazou.
|
|
35
|
+
|
|
36
|
+
## T4 — Caminho enxuto: Products (1 camada) — AC-4
|
|
37
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T1
|
|
38
|
+
- **Paths**: `.../modules/products/*`, `WHEN-CLEAN-WHEN-LEAN.md`
|
|
39
|
+
- **Done**: CRUD controller→repo direto, **sem** use-case/porta; o doc ensina o critério de escolha.
|
|
40
|
+
Kill criteria: se Products virar 4 camadas, a spec falhou.
|
|
41
|
+
|
|
42
|
+
## T5 — Memória por contexto (o vetor de token) — AC-6
|
|
43
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T2, T4
|
|
44
|
+
- **Paths**: `.../memory/30-domains/{orders,products}/context.md`
|
|
45
|
+
- **Done**: cada contexto descrito na linguagem ubíqua — o que o agente lê **antes** do código.
|
|
46
|
+
Orders documenta as invariantes e os use-cases; Products, o CRUD raso.
|
|
47
|
+
|
|
48
|
+
## T6 — Manifesto + catálogo + README — AC-7
|
|
49
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T1-T5
|
|
50
|
+
- **Paths**: `.../boilerplate.manifest.json`, `.../README.md`, `boilerplates/README.md`
|
|
51
|
+
- **Done**: manifesto no schema 1.0 (stack/useCases/commands); entrada no catálogo; README explicando
|
|
52
|
+
a estrutura e apontando o `WHEN-CLEAN-WHEN-LEAN.md`.
|
|
53
|
+
|
|
54
|
+
## T7 — Medir o token (métrica-norte) + ADR-0027 — AC-6/AC-10
|
|
55
|
+
- **Owner**: SDD Architect + Governance · **Estimativa**: P · **Depende de**: T5, T6
|
|
56
|
+
- **Paths**: `memory/90-decisions/0027-*.md`
|
|
57
|
+
- **Done**:
|
|
58
|
+
- [ ] Medir o pacote de contexto de "adicionar uma regra ao contexto orders" aqui vs. no
|
|
59
|
+
`02-saas-starter` flat. **Registrar os números.**
|
|
60
|
+
- [ ] ADR-0027: Clean Architecture calibrada; o porquê da calibração e o resultado da medição.
|
|
61
|
+
Se o token não caiu, o ADR diz isso e recalibra — não maquia.
|
|
62
|
+
|
|
63
|
+
## T8 — Gates (Governance) — AC-9
|
|
64
|
+
- **Owner**: Governance · **Estimativa**: P · **Depende de**: T6
|
|
65
|
+
- **Done**: `release:check` (boilerplate no `files[]`, instala limpo), `tools:doctor` (docs-commands
|
|
66
|
+
não acusa fantasma), `npm test` do Forja verde. spec → `done`.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
## Handoffs
|
|
70
|
+
Worker (T1-T6), SDD Architect + Governance (T7-T8). `forja agent:route` a cada fronteira (ADR-0005).
|