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
@@ -30,7 +30,15 @@ import path from 'node:path';
30
30
  import { fileURLToPath } from 'node:url';
31
31
 
32
32
  import { getWorkspaceDbPath, getWorkspaceInfo } from '../workspace.mjs';
33
- import { runChecks as run, worstStatus, stripTemplateLiterals } from './checks.mjs';
33
+ import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from './checks.mjs';
34
+ import { COMMANDS } from './registry.mjs';
35
+ import { scanCommands, scanLinks, projectCommands } from './doc-graph.mjs';
36
+
37
+ // Os contratos vivem em checks.mjs — importados, não redefinidos. As cópias locais eram resíduo da
38
+ // extração do runner (SPEC-010) e já divergiam.
39
+ /** @typedef {import('./checks.mjs').Check} Check */
40
+ /** @typedef {import('./checks.mjs').Result} Result */
41
+ /** @typedef {import('./checks.mjs').Status} Status */
34
42
 
35
43
  // O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
36
44
  // aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
@@ -39,29 +47,6 @@ export { worstStatus };
39
47
  const __filename = fileURLToPath(import.meta.url);
40
48
  const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
41
49
 
42
- /** @typedef {'critical'|'warn'} Severity */
43
- /** @typedef {'runtime'|'repo'} Scope */
44
- /** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
45
-
46
- /**
47
- * @typedef {object} Check
48
- * @property {string} id
49
- * @property {string} title
50
- * @property {Severity} severity `critical` trava o gate; `warn` informa.
51
- * @property {Scope} scope `repo` só roda dentro do repo do framework.
52
- * @property {string=} dependsOn Id de outro check. Se ele falhar, este vira `skipped`.
53
- * @property {(env: Env) => Promise<Probe>|Probe} probe
54
- */
55
-
56
- /**
57
- * @typedef {object} Probe
58
- * @property {Status} status
59
- * @property {string} detail O que foi observado, em uma linha.
60
- * @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
61
- */
62
-
63
- /** @typedef {{ id, title, severity: Severity, scope: Scope, status: Status, detail: string, fix: string|null }} Result */
64
-
65
50
  /**
66
51
  * Ambiente injetável. Existe para que os probes sejam testáveis sem mockar o loader de módulos
67
52
  * do Node nem corromper `node_modules` de verdade — simular um ABI quebrado é passar um
@@ -101,6 +86,7 @@ export function defaultEnv(overrides = {}) {
101
86
  * Classificamos por `err.code`, nunca pela mensagem: o texto do erro varia entre versões do Node,
102
87
  * e este check existe precisamente para sobreviver a troca de versão do Node.
103
88
  */
89
+ /** @type {Check} */
104
90
  const nativeAbi = {
105
91
  id: 'native-abi',
106
92
  title: 'better-sqlite3 carrega no Node atual',
@@ -111,7 +97,7 @@ const nativeAbi = {
111
97
  try {
112
98
  ({ default: Database } = await env.importModule('better-sqlite3'));
113
99
  } catch (err) {
114
- if (err?.code === 'ERR_MODULE_NOT_FOUND') {
100
+ if (asErrno(err).code === 'ERR_MODULE_NOT_FOUND') {
115
101
  return {
116
102
  status: 'fail',
117
103
  detail: 'better-sqlite3 não está instalado — toda a memória universal fica indisponível',
@@ -124,7 +110,7 @@ const nativeAbi = {
124
110
  try {
125
111
  new Database(':memory:').close();
126
112
  } catch (err) {
127
- if (err?.code === 'ERR_DLOPEN_FAILED') {
113
+ if (asErrno(err).code === 'ERR_DLOPEN_FAILED') {
128
114
  const node = env.process.versions.node;
129
115
  return {
130
116
  status: 'fail',
@@ -142,6 +128,7 @@ const nativeAbi = {
142
128
  },
143
129
  };
144
130
 
131
+ /** @type {Check} */
145
132
  const memoryDb = {
146
133
  id: 'memory-db',
147
134
  title: 'universal.db acessível',
@@ -173,7 +160,7 @@ const memoryDb = {
173
160
  } catch (err) {
174
161
  return {
175
162
  status: 'fail',
176
- detail: `banco existe mas não abre (${err?.code || err?.message}) — provavelmente corrompido`,
163
+ detail: `banco existe mas não abre (${asErrno(err).code || asErrno(err).message}) — provavelmente corrompido`,
177
164
  fix: 'npm run sync:universal',
178
165
  };
179
166
  }
@@ -211,6 +198,7 @@ function newestMarkdownMtime(env, dir, acc = { t: 0 }) {
211
198
  *
212
199
  * É `warn`, não `critical`: responder sobre memória velha atrapalha, mas não impede trabalho.
213
200
  */
201
+ /** @type {Check} */
214
202
  const memoryFresh = {
215
203
  id: 'memory-fresh',
216
204
  title: 'índice em dia com memory/',
@@ -253,6 +241,7 @@ const memoryFresh = {
253
241
  * pensa" — um FORJA_WORKSPACE esquecido no ambiente aponta o framework para o workspace errado, e
254
242
  * tudo parece funcionar.
255
243
  */
244
+ /** @type {Check} */
256
245
  const workspace = {
257
246
  id: 'workspace',
258
247
  title: 'workspace resolvido',
@@ -274,6 +263,7 @@ const workspace = {
274
263
  };
275
264
 
276
265
  /** Compara o Node em uso com o `engines.node` declarado. Abaixo do mínimo, o resto é loteria. */
266
+ /** @type {Check} */
277
267
  const nodeEngines = {
278
268
  id: 'node-engines',
279
269
  title: 'Node dentro de engines',
@@ -347,6 +337,7 @@ function packageName(specifier) {
347
337
  * Conservador de propósito: só olha import **estático** de script publicado. Import dinâmico não
348
338
  * conta (é o padrão do carregamento lazy, e lazy é justamente o que o ADR-0021 pediu).
349
339
  */
340
+ /** @type {Check} */
350
341
  const runtimeDeps = {
351
342
  id: 'runtime-deps',
352
343
  title: 'deps de runtime declaradas',
@@ -425,6 +416,7 @@ const runtimeDeps = {
425
416
  * repo. O codegraph indexava código morto e respondia com confiança sobre ele. O path também
426
417
  * quebrava para qualquer outro contribuidor.
427
418
  */
419
+ /** @type {Check} */
428
420
  const mcpJson = {
429
421
  id: 'mcp-json',
430
422
  title: '.mcp.json sem path absoluto',
@@ -456,8 +448,118 @@ const mcpJson = {
456
448
  },
457
449
  };
458
450
 
451
+ // ---------------------------------------------------------------------------
452
+ // Coerência da documentação (SPEC-011, ADR-0025)
453
+ //
454
+ // O Forja é operado por agentes que executam o que a doc manda. Quando a doc e o registry divergem,
455
+ // o agente erra por obediência. Estes três checks trazem a classe "erra sem avisar" (ADR-0021) para
456
+ // a camada de instrução — a fronteira mais barata de corromper e a mais cara de perceber.
457
+ // ---------------------------------------------------------------------------
458
+
459
+ /**
460
+ * Comando fantasma na doc faz o agente executar o que não existe e concluir que o ambiente
461
+ * quebrou. É `critical`. A allowlist do projeto gerado é **derivada** dos geradores + boilerplates
462
+ * (nunca literal), senão `start:dev`/`test:e2e` e afins dariam falso positivo.
463
+ */
464
+ /** @type {Check} */
465
+ const docsCommands = {
466
+ id: 'docs-commands',
467
+ title: 'comandos citados na doc existem',
468
+ severity: 'critical',
469
+ scope: 'repo',
470
+ probe(env) {
471
+ if (!isFrameworkRepo(env)) {
472
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
473
+ }
474
+
475
+ const known = new Set([...Object.keys(COMMANDS), ...projectCommands(env)]);
476
+ const ghosts = scanCommands(env).filter((c) => !known.has(c.command));
477
+
478
+ if (ghosts.length) {
479
+ const amostra = ghosts.slice(0, 5).map((g) => `${g.command} (${g.file}:${g.line})`).join(', ');
480
+ return {
481
+ status: 'fail',
482
+ detail: `${ghosts.length} citação(ões) de comando inexistente: ${amostra}`,
483
+ fix: 'renomeie para um comando do registry ou remova a citação no arquivo:linha indicado',
484
+ };
485
+ }
486
+
487
+ return { status: 'ok', detail: 'toda citação de comando resolve no registry', fix: null };
488
+ },
489
+ };
490
+
491
+ /**
492
+ * Capacidade que ninguém documenta é capacidade obscura. `warn`, não `critical`: um comando
493
+ * não-documentado atrapalha (o operador não sabe que existe), mas não impede trabalho.
494
+ */
495
+ /** @type {Check} */
496
+ const commandsDocumented = {
497
+ id: 'commands-documented',
498
+ title: 'todo comando do registry é documentado',
499
+ severity: 'warn',
500
+ scope: 'repo',
501
+ probe(env) {
502
+ if (!isFrameworkRepo(env)) {
503
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
504
+ }
505
+
506
+ const citados = new Set(scanCommands(env).map((c) => c.command));
507
+ const orfaos = Object.keys(COMMANDS).filter((c) => !citados.has(c));
508
+
509
+ if (orfaos.length) {
510
+ return {
511
+ status: 'warn',
512
+ detail: `${orfaos.length} comando(s) do registry sem menção em doc/prompt/agente: ${orfaos.join(', ')}`,
513
+ fix: 'documente cada um numa superfície de instrução, ou remova do registry se morto',
514
+ };
515
+ }
516
+
517
+ return { status: 'ok', detail: 'todos os comandos do registry aparecem na doc', fix: null };
518
+ },
519
+ };
520
+
521
+ /** Link relativo para o nada é step obscuro. `warn`: atrapalha a navegação, não impede trabalho. */
522
+ /** @type {Check} */
523
+ const docsLinks = {
524
+ id: 'docs-links',
525
+ title: 'links relativos da doc resolvem',
526
+ severity: 'warn',
527
+ scope: 'repo',
528
+ probe(env) {
529
+ if (!isFrameworkRepo(env)) {
530
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
531
+ }
532
+
533
+ const quebrados = scanLinks(env).filter(
534
+ (l) => !env.fs.existsSync(path.join(env.root, l.resolved))
535
+ );
536
+
537
+ if (quebrados.length) {
538
+ const amostra = quebrados.slice(0, 5).map((q) => `${q.target} (${q.file}:${q.line})`).join(', ');
539
+ return {
540
+ status: 'warn',
541
+ detail: `${quebrados.length} link(s) relativo(s) sem alvo: ${amostra}`,
542
+ fix: 'crie o alvo ou corrija o link no arquivo:linha indicado',
543
+ };
544
+ }
545
+
546
+ return { status: 'ok', detail: 'todo link relativo resolve', fix: null };
547
+ },
548
+ };
549
+
459
550
  /** @type {Check[]} */
460
- export const CHECKS = [nativeAbi, memoryDb, memoryFresh, workspace, nodeEngines, runtimeDeps, mcpJson];
551
+ export const CHECKS = [
552
+ nativeAbi,
553
+ memoryDb,
554
+ memoryFresh,
555
+ workspace,
556
+ nodeEngines,
557
+ runtimeDeps,
558
+ mcpJson,
559
+ docsCommands,
560
+ commandsDocumented,
561
+ docsLinks,
562
+ ];
461
563
 
462
564
  /**
463
565
  * Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
@@ -466,7 +568,7 @@ export const CHECKS = [nativeAbi, memoryDb, memoryFresh, workspace, nodeEngines,
466
568
  * `scope: 'runtime'` roda só os checks baratos e portáveis — é o que o hook SessionStart usa, onde
467
569
  * há orçamento de 5s e nenhuma tolerância a travar a sessão.
468
570
  *
469
- * @param {{ scope?: Scope|'all', env?: Partial<Env>, checks?: Check[] }} [opts]
571
+ * @param {{ scope?: import('./checks.mjs').Scope|'all', env?: Partial<Env>, checks?: Check[] }} [opts]
470
572
  * @returns {Promise<Result[]>}
471
573
  */
472
574
  export async function runChecks(opts = {}) {
@@ -13,6 +13,29 @@
13
13
  * - workspace-warn avisa se o workspace não existir, mas segue
14
14
  */
15
15
 
16
+ import fs from 'node:fs';
17
+ import path from 'node:path';
18
+
19
+ /**
20
+ * Resolve o `node:` de um comando para o arquivo real, **agnóstico de extensão** (SPEC-012 D2).
21
+ * Tenta `.ts → .js → .mjs`: em dev acha a fonte `.ts`; no pacote publicado, o `.js` sob `dist/`.
22
+ * Desacopla o registry do runtime — a entrada pode manter `.mjs` que este resolver ainda acha o
23
+ * `.ts` renomeado. Sem isto, renomear um script quebraria o dispatch.
24
+ *
25
+ * @param {string} root Raiz onde os scripts vivem (repo em dev, `dist/` no publicado).
26
+ * @param {string} node Caminho do registry, com ou sem extensão.
27
+ * @returns {string} Caminho absoluto do arquivo que existe (ou o candidato original, que falha visível).
28
+ */
29
+ export function resolveScript(root, node) {
30
+ const direct = path.join(root, node);
31
+ if (fs.existsSync(direct)) return direct;
32
+ const base = direct.replace(/\.(mjs|cjs|js|ts)$/, '');
33
+ for (const ext of ['.ts', '.js', '.mjs']) {
34
+ if (fs.existsSync(base + ext)) return base + ext;
35
+ }
36
+ return direct;
37
+ }
38
+
16
39
  export const DOMAINS = {
17
40
  workspace: 'Workspace & projetos',
18
41
  sdd: 'Pipeline SDD (spec → plan → tasks → check)',
@@ -25,7 +25,9 @@ import path from 'node:path';
25
25
  import { fileURLToPath } from 'node:url';
26
26
 
27
27
  import { runChecks as run, worstStatus, stripTemplateLiterals } from './checks.mjs';
28
- import { COMMANDS } from './registry.mjs';
28
+
29
+ /** @typedef {import('./checks.mjs').Check} Check */
30
+ import { COMMANDS, resolveScript } from './registry.mjs';
29
31
 
30
32
  export { worstStatus };
31
33
 
@@ -48,6 +50,7 @@ function git(args, cwd = repoRoot) {
48
50
  *
49
51
  * Limpa o temporário **sempre**, inclusive quando o callback lança.
50
52
  *
53
+ * @template T
51
54
  * @param {(ctx: { pkgDir: string, installDir: string }) => Promise<T>|T} fn
52
55
  * @returns {Promise<T>}
53
56
  */
@@ -74,8 +77,9 @@ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
74
77
  return execFileSync('npm', args, { cwd, encoding: 'utf8', env, stdio: 'pipe' });
75
78
  } catch (err) {
76
79
  // Engolir o stderr aqui cega o diagnóstico exatamente quando ele importa.
77
- const saida = `${err.stdout || ''}${err.stderr || ''}`.trim();
78
- throw new Error(`npm ${args[0]} falhou em ${cwd}:\n${saida || err.message}`);
80
+ const e = /** @type {any} */ (err);
81
+ const saida = `${e.stdout || ''}${e.stderr || ''}`.trim();
82
+ throw new Error(`npm ${args[0]} falhou em ${cwd}:\n${saida || e.message}`);
79
83
  }
80
84
  };
81
85
 
@@ -84,6 +88,7 @@ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
84
88
  .trim()
85
89
  .split('\n')
86
90
  .pop();
91
+ if (!tgz) throw new Error('npm pack não produziu um tarball');
87
92
 
88
93
  npm(['init', '-y'], dir);
89
94
  npm(['install', path.join(dir, tgz)], dir);
@@ -109,6 +114,7 @@ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
109
114
  * Severidade depende do modo: sob `--publish` é fatal; em dev é aviso — um gate que reprova todo
110
115
  * desenvolvimento local é um gate que se contorna (a lição que o CI nos deu na SPEC-009).
111
116
  */
117
+ /** @type {Check} */
112
118
  const treeClean = {
113
119
  id: 'tree-clean',
114
120
  title: 'árvore limpa (o tarball é o commit)',
@@ -133,6 +139,7 @@ const treeClean = {
133
139
  };
134
140
 
135
141
  /** Se o pacote não instala, todo o resto é irrelevante — daí todos dependerem deste. */
142
+ /** @type {Check} */
136
143
  const install = {
137
144
  id: 'install',
138
145
  title: 'o pacote instala do zero',
@@ -148,6 +155,7 @@ const install = {
148
155
  * Todo comando anunciado pelo registry precisa existir no tarball. É o bug da v1.1.3, generalizado:
149
156
  * `npm run dashboard` era publicado, a pasta `dashboard/` não.
150
157
  */
158
+ /** @type {Check} */
151
159
  const registryScripts = {
152
160
  id: 'registry-scripts',
153
161
  title: 'todo comando do registry existe no tarball',
@@ -161,7 +169,10 @@ const registryScripts = {
161
169
  const rel = def.node || def.script;
162
170
  if (!rel) continue;
163
171
  total += 1;
164
- if (!env.fs.existsSync(path.join(env.pkgDir, rel))) faltando.push(`${name} → ${rel}`);
172
+ // Resolve extensão no tarball (SPEC-012 D2): o script pode ter sido renomeado para .ts em dev
173
+ // e compilado para .js em dist/. O resolver acha o que existe, não crava a extensão.
174
+ const resolved = resolveScript(pkgCodeRoot(env), rel);
175
+ if (!env.fs.existsSync(resolved)) faltando.push(`${name} → ${rel}`);
165
176
  }
166
177
 
167
178
  if (faltando.length) {
@@ -189,11 +200,31 @@ const registryScripts = {
189
200
  */
190
201
  const CODE_DIRS = ['bin', 'lib', 'scripts'];
191
202
 
203
+ /**
204
+ * A raiz onde `bin/lib/scripts` vivem **no tarball**, derivada do campo `bin` do package.json.
205
+ *
206
+ * Fonte-na-raiz (`bin: 'bin/forja.mjs'`) → a raiz é o próprio pacote. Publicando `dist/`
207
+ * (`bin: 'dist/bin/forja.mjs'`, SPEC-012) → a raiz é `dist/`. É a mesma conta que o dispatch faz em
208
+ * runtime (`root = dirname(bin)/..`); os checks de release precisam olhar no mesmo lugar, senão
209
+ * procuram o código onde ele não está mais.
210
+ */
211
+ function pkgCodeRoot(env) {
212
+ try {
213
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
214
+ const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
215
+ if (binRel) return path.join(env.pkgDir, path.dirname(path.dirname(binRel)));
216
+ } catch {
217
+ /* sem package.json legível — cai no default */
218
+ }
219
+ return env.pkgDir;
220
+ }
221
+
192
222
  function publishedSources(env) {
193
223
  const out = [];
224
+ const root = pkgCodeRoot(env);
194
225
 
195
226
  for (const dir of CODE_DIRS) {
196
- const full = path.join(env.pkgDir, dir);
227
+ const full = path.join(root, dir);
197
228
  if (env.fs.existsSync(full)) walkDir(env, full, out);
198
229
  }
199
230
 
@@ -241,6 +272,7 @@ function packageName(specifier) {
241
272
  }
242
273
 
243
274
  /** Import relativo que não resolve dentro do tarball = arquivo fora do `files[]` (bug da v1.1.3). */
275
+ /** @type {Check} */
244
276
  const importsResolve = {
245
277
  id: 'imports-resolve',
246
278
  title: 'imports relativos resolvem dentro do tarball',
@@ -272,6 +304,7 @@ const importsResolve = {
272
304
  };
273
305
 
274
306
  /** O bug do ADR-0021 §2: importado por script publicado, mas declarado como devDependency. */
307
+ /** @type {Check} */
275
308
  const depsDeclared = {
276
309
  id: 'deps-declared',
277
310
  title: 'todo import externo está em dependencies',
@@ -304,6 +337,7 @@ const depsDeclared = {
304
337
  };
305
338
 
306
339
  /** Peso morto viaja no tarball de todo usuário. Incomoda; não quebra — por isso `warn` (D7). */
340
+ /** @type {Check} */
307
341
  const depsUnused = {
308
342
  id: 'deps-unused',
309
343
  title: 'nenhuma dependency é peso morto',
@@ -347,20 +381,25 @@ const depsUnused = {
347
381
  * code reprovaria um pacote saudável — a mesma armadilha do `memory-db` na SPEC-009, um nível
348
382
  * acima.
349
383
  */
384
+ /** @type {Check} */
350
385
  const smokeCommands = {
351
386
  id: 'smoke-commands',
352
387
  title: 'os comandos executam de verdade',
353
388
  severity: 'critical',
354
389
  dependsOn: 'install',
355
390
  probe(env) {
356
- const bin = path.join(env.pkgDir, 'bin', 'forja.mjs');
391
+ // Lê o entry point do campo `bin` do package.json, não de um path fixo — o publicado aponta
392
+ // para dist/ (SPEC-012). Cravar `bin/forja.mjs` quebraria o smoke assim que o bin mudasse.
393
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
394
+ const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
395
+ const bin = path.join(env.pkgDir, binRel);
357
396
  const quebrados = [];
358
397
 
359
398
  for (const args of env.smokeCommands) {
360
399
  const res = env.spawn(process.execPath, [bin, ...args], { cwd: env.installDir });
361
400
  const saida = `${res.stdout || ''}${res.stderr || ''}`;
362
401
  if (LOADER_ERRORS.test(saida)) {
363
- const causa = saida.match(LOADER_ERRORS)[0];
402
+ const causa = saida.match(LOADER_ERRORS)?.[0] ?? 'erro de carregamento';
364
403
  quebrados.push(`${args[0] || '(help)'}: ${causa}`);
365
404
  }
366
405
  }
@@ -409,7 +448,8 @@ export function defaultEnv(overrides = {}) {
409
448
  stderr: '',
410
449
  };
411
450
  } catch (err) {
412
- return { stdout: err.stdout || '', stderr: err.stderr || String(err) };
451
+ const e = /** @type {any} */ (err);
452
+ return { stdout: e.stdout || '', stderr: e.stderr || String(err) };
413
453
  }
414
454
  },
415
455
  ...overrides,
@@ -16,7 +16,7 @@ import { spawnSync } from 'node:child_process';
16
16
 
17
17
  function runCodegraph(args) {
18
18
  const result = spawnSync('codegraph', args, { encoding: 'utf8' });
19
- if (result.error && result.error.code === 'ENOENT') return { missing: true };
19
+ if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') return { missing: true };
20
20
  return {
21
21
  missing: false,
22
22
  status: result.status ?? 1,
@@ -30,7 +30,7 @@ function codegraphStatus() {
30
30
  if (res.missing) return { missing: true };
31
31
  let data = null;
32
32
  try {
33
- data = JSON.parse(res.stdout);
33
+ data = JSON.parse(/** @type {string} */ (res.stdout));
34
34
  } catch {
35
35
  return { missing: false, parseError: true, raw: res.stdout || res.stderr };
36
36
  }
@@ -0,0 +1,95 @@
1
+ # ADR-0025: Coerência da documentação como gate
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-18
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: governance, docs, harness, diagnostics, registry
7
+
8
+ ## Contexto
9
+
10
+ Os ADRs 0023 e 0024 fecharam a classe "erra sem avisar" (ADR-0021) no **núcleo** e no **tarball**.
11
+ Faltava a fronteira mais barata de corromper e a mais cara de perceber: a **palavra escrita**.
12
+
13
+ O Forja é operado por agentes que leem a documentação e executam o que ela manda. Quando a doc e o
14
+ código divergem, o agente não erra por burrice — erra por **obediência**. Uma auditoria manual em
15
+ 2026-07-14 encontrou, entre outras coisas:
16
+
17
+ - `docs/token-optimization.md` — o documento que ensina a economia de tokens (ADR-0009) — mandava
18
+ rodar **quatro comandos que não existem** (`context:build`, `memory:db:reindex`, …) e linkava um
19
+ `docs/DEPLOYMENT.md` que nunca existiu.
20
+ - O Governance descrevia `tools:doctor` pela definição anterior ao ADR-0023.
21
+ - Comandos do registry sem menção em lugar nenhum — capacidade obscura é capacidade morta.
22
+
23
+ Nada disso quebrava um teste nem aparecia no `git status`. A correção manual apagou os sintomas do
24
+ dia; nada impedia a reincidência. Toda vez que um comando é renomeado ou um gate muda de contrato, a
25
+ doc pode silenciosamente passar a mentir.
26
+
27
+ ## Decisão
28
+
29
+ Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanner puro
30
+ `lib/core/doc-graph.mjs` que lê os `.md` de instrução como dado:
31
+
32
+ - **`docs-commands`** (critical): todo `forja <cmd>` / `npm run <cmd>` citado numa superfície de
33
+ instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
34
+ - **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
35
+ - **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
36
+
37
+ Princípios:
38
+
39
+ - **Scanner puro, checks finos.** `doc-graph.mjs` lê e devolve dados (`scanCommands`, `scanLinks`,
40
+ `projectCommands`); os checks julgam. Testar o parsing — a parte difícil — não exige montar o
41
+ ambiente do doctor.
42
+ - **Allowlist derivada, jamais literal.** Os comandos do projeto *gerado* (`start:dev`, `test:e2e`,
43
+ `memory:db:*`) não são do Forja e não podem reprovar. A allowlist deriva de **duas** fontes: os
44
+ blocos `"scripts"` inline dos geradores **e** os `package.json` dos boilerplates. Foi `test:e2e`
45
+ — que vive no boilerplate, não no gerador — que provou que uma fonte só produz falso positivo. Uma
46
+ lista manual mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
47
+ - **Escopo = instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
48
+ `.claude/agents/` e os `.md` de raiz. **Fora**: `boilerplates/` (conteúdo do projeto gerado),
49
+ `specs/` e `memory/90-*` (registro histórico — uma spec ou ADR pode legitimamente citar um comando
50
+ proposto ou já removido). O gate protege o que instrui o agente *agora*.
51
+ - **`:` como discriminador de comando.** Cobre 42/42 do registry e nenhuma prosa (`"forja does X"`)
52
+ casa por acidente. Inventar parser de gramática para um comando-sem-`:` inexistente seria criar o
53
+ problema que não temos.
54
+ - **Severidade honesta.** Só `docs-commands` é crítico. Comando não-documentado e link quebrado
55
+ atrapalham, não impedem — `warn`. Um gate que reprova o que não trava é um gate que se aprende a
56
+ ignorar.
57
+
58
+ ## Alternativas consideradas
59
+
60
+ - **Manter a auditoria manual** — rejeitada: ela apaga sintomas, não fecha a classe. Reincide na
61
+ próxima renomeação.
62
+ - **Lista literal de comandos do projeto gerado** — rejeitada: é a armadilha do `.gitignore` da
63
+ SPEC-009. Uma lista que não acompanha o gerador vira mentira.
64
+ - **Parsear markdown com um lexer de CommonMark** — rejeitada: peso morto. Precisamos de citações e
65
+ links, não de um AST. Regex + o discriminador `:` bastam.
66
+ - **Gerar a doc a partir do registry** — rejeitada: doc gerada por máquina descreve o *quê*, nunca o
67
+ *porquê*, e o porquê é o que importa. O gate cobra que a explicação exista; não escreve por você.
68
+ - **Escanear `specs/` e `memory/` também** — rejeitada: são registro histórico. Reprovar um ADR por
69
+ citar um comando já removido puniria a memória por lembrar.
70
+
71
+ ## Consequências
72
+
73
+ **Positivas**:
74
+ - Renomear um comando vira **ato detectável**: a doc que ficou para trás reprova o CI (o
75
+ `tools:doctor` já é step, ADR-0024) — não espera a próxima auditoria manual.
76
+ - Os quatro comandos-fantasma e os 22 links quebrados da auditoria manual viram zero, verificado a
77
+ cada CI. `memory:extract` (o único órfão) passou a ser documentado.
78
+ - O gate pegou o **próprio autor**: ao corrigir os links, um erro de profundidade relativa
79
+ (`../../` vs `../../../`) foi detectado na hora, antes do commit. É a prova de que ele mede o que
80
+ deve.
81
+
82
+ **Negativas / Trade-offs**:
83
+ - Análise estática conservadora: o `:` como discriminador deixaria escapar um futuro comando sem
84
+ `:`. Aceito — nenhum existe, e falso negativo raro é melhor que falso positivo crítico.
85
+ - Os checks leem todos os `.md` de instrução a cada `tools:doctor`. Barato hoje (< 1s); se crescer,
86
+ vira lazy por mtime. São `scope: repo`, fora do `SessionStart`.
87
+
88
+ ## Rastreamento
89
+
90
+ - Implementação: `lib/core/doc-graph.mjs`, `lib/core/health.mjs` (checks `docs-commands`,
91
+ `commands-documented`, `docs-links`), `test/doc-graph.test.js`, `test/health.test.js`
92
+ - Spec: `specs/coerencia-do-sistema/` (SPEC-011)
93
+ - ADRs relacionadas: ADR-0023 (gate do núcleo) e ADR-0024 (gate do tarball) — a mesma família, agora
94
+ na terceira fronteira: a instrução. ADR-0021 (a classe "erra sem avisar"). ADR-0020 (registry como
95
+ fonte da verdade dos comandos).
@@ -0,0 +1,96 @@
1
+ # ADR-0027: Boilerplate Clean Architecture calibrada
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-18
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: boilerplate, ddd, clean-architecture, token-economy
7
+
8
+ ## Contexto
9
+
10
+ Os boilerplates do Forja eram NestJS-flat: o `service` fala direto com a entity do ORM, a regra de
11
+ negócio fica diluída no service acoplada ao framework. Dois preços — manutenção (testar regra exige
12
+ subir o Nest; trocar ORM é cirurgia) e **tokens** (ADR-0009): um agente precisa ler a implementação
13
+ inteira para entender uma feature, porque não há contrato legível separado da execução.
14
+
15
+ A resposta ingênua — "aplicar Clean Architecture" — tem o preço oposto: quatro camadas para um CRUD
16
+ são mais arquivos para ler, não menos. Cargo-cult de arquitetura é o anti-padrão de token com nome
17
+ bonito.
18
+
19
+ ## Decisão
20
+
21
+ Um boilerplate (`boilerplates/06-clean-arch`) que demonstra **os dois padrões lado a lado**:
22
+
23
+ - **Fatia rica (Orders)**: 4 camadas (domain / application / infrastructure / presentation) com
24
+ inversão de dependência. Invariantes de negócio (não envia sem pagamento; total derivado; máquina
25
+ de estados) vivem no domínio, em TypeScript puro — **zero `@nestjs`, zero ORM**. Testáveis sem
26
+ subir o Nest.
27
+ - **Caminho enxuto (Products)**: CRUD numa camada, controller→repo direto, sem use-case nem porta.
28
+ - **`WHEN-CLEAN-WHEN-LEAN.md`**: o critério de qual padrão usar. É o coração — a calibração é a
29
+ decisão, não as camadas.
30
+ - **Memória por bounded context** (`memory/30-domains/<ctx>/context.md`): a linguagem ubíqua que o
31
+ agente lê antes do código.
32
+
33
+ Inversão via DI do Nest: a porta é `interface` no domínio + token; o adapter a implementa; o módulo
34
+ faz o bind numa linha. O domínio e a aplicação não sabem que TypeORM existe.
35
+
36
+ ## A medição de token — honesta (o que a spec exigiu)
37
+
38
+ A SPEC-013 fez da economia de token a métrica-norte e mandou **reconhecer se não cair, não maquiar**.
39
+ Então:
40
+
41
+ Medida crua (bytes/4) do custo de "ler o domínio para editar uma regra":
42
+
43
+ | | tokens aprox. |
44
+ |---|---|
45
+ | Clean-arch: `context.md` (476) + `order.entity.ts` (690) | **~1167** |
46
+ | Flat 02-saas: `billing.service.ts` (486) + `invoice.entity.ts` (244) | **~730** |
47
+
48
+ **Na contagem crua, Clean-arch não ganha — é maior.** E a comparação é injusta: o domínio de Orders
49
+ tem máquina de estados e invariantes reais; o service de billing é fino. Estamos comparando lógica
50
+ rica com lógica pobre, não arquitetura com arquitetura.
51
+
52
+ **Onde o benefício de token realmente está** (e o que a medida crua não captura):
53
+
54
+ 1. **Localização.** Para editar uma regra em Clean-arch, o agente lê o `context.md` (que aponta
55
+ "a regra está em `order.entity.ts`") e o agregado — e **não carrega** infraestrutura, controller
56
+ nem use-cases. No flat, a regra está no service misturada a acesso a dados; para ter certeza de
57
+ achar toda a lógica, o agente varre mais.
58
+ 2. **O `context.md` como mapa.** 476 tokens lidos primeiro que substituem exploração. No flat não há
59
+ mapa: o agente greps/lê para descobrir onde a regra vive.
60
+ 3. **Ler assinatura, não implementação.** Para *entender* (não editar), o `context.md` + a assinatura
61
+ do use-case bastam; no flat, lê-se o service.
62
+
63
+ **Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
64
+ não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
65
+ prova rigorosa precisa do `context:smart`/`token:benchmark` sobre uma **mesma tarefa** num projeto
66
+ gerado, com a mesma feature nas duas arquiteturas — o boilerplate flat não tem um equivalente rico ao
67
+ Order, então esse benchmark é trabalho de follow-up, não algo a forjar agora.
68
+
69
+ ## Alternativas consideradas
70
+
71
+ - **Clean Architecture em tudo** — rejeitada: é o cargo-cult que a calibração existe para evitar. O
72
+ `WHEN-CLEAN-WHEN-LEAN.md` + o Products enxuto são o guardrail.
73
+ - **Clean Architecture no framework Forja** — rejeitada (fora do escopo da SPEC-013): over-engineering
74
+ para um CLI. O framework ganha só modelos de domínio tipados, ride na migração TS (SPEC-012).
75
+ - **Refatorar os boilerplates 01-05** — rejeitada: aditivo, não migração. Os flat servem o CRUD.
76
+
77
+ ## Consequências
78
+
79
+ **Positivas**:
80
+ - Um esqueleto onde a regra de negócio é isolada, testável sem framework, e sobrevive a troca de ORM.
81
+ - A calibração é **visível em código** (Orders rico vs. Products enxuto), não só documentada.
82
+ - O guardrail contra token-bloat é explícito e reprovável (o Products *tem* que ser 1 camada).
83
+
84
+ **Negativas / Trade-offs**:
85
+ - A economia de token **não está provada** — está argumentada (navegacional) e medida cruamente com
86
+ resultado inconclusivo. O benchmark real é follow-up. Registrar isto é a honestidade que a spec
87
+ cobrou; claim de vitória não-medida seria maquiar.
88
+ - Mais conceitos para o dev absorver na fatia rica. Mitigado: uma fatia rica só; o resto enxuto.
89
+
90
+ ## Rastreamento
91
+
92
+ - Implementação: `boilerplates/06-clean-arch/`
93
+ - Spec: `specs/clean-arch-boilerplate/` (SPEC-013)
94
+ - ADRs relacionadas: ADR-0009 (economia de tokens — a métrica-norte), ADR-0001 (memória por contexto),
95
+ ADR-0016 (harness), SPEC-012 (TS — o domínio tipado)
96
+ - **Follow-up**: benchmark `context:smart` de uma tarefa-tipo, mesma feature nas duas arquiteturas.