forjajs 1.1.6 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (172) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +62 -0
  3. package/README.en.md +33 -5
  4. package/README.md +35 -4
  5. package/boilerplates/06-clean-arch/README.md +48 -0
  6. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
  7. package/boilerplates/06-clean-arch/backend/package.json +43 -0
  8. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
  9. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
  10. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
  11. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
  12. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
  13. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
  14. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
  15. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
  16. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
  17. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
  18. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
  19. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
  20. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
  21. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
  22. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
  23. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
  24. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
  25. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
  26. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
  27. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
  28. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
  29. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
  30. package/boilerplates/README.md +20 -0
  31. package/dist/bin/create-memory-nest-kit.d.ts +2 -0
  32. package/dist/bin/create-memory-nest-kit.js +110 -0
  33. package/dist/bin/forja.d.ts +13 -0
  34. package/dist/bin/forja.js +136 -0
  35. package/dist/bin/init-project.d.ts +2 -0
  36. package/dist/bin/init-project.js +516 -0
  37. package/dist/lib/audit.d.ts +67 -0
  38. package/dist/lib/audit.js +143 -0
  39. package/dist/lib/context-builder.d.ts +58 -0
  40. package/dist/lib/context-builder.js +233 -0
  41. package/dist/lib/core/checks.d.ts +91 -0
  42. package/dist/lib/core/checks.js +119 -0
  43. package/dist/lib/core/doc-graph.d.ts +60 -0
  44. package/dist/lib/core/doc-graph.js +235 -0
  45. package/dist/lib/core/health.d.ts +103 -0
  46. package/dist/lib/core/health.js +538 -0
  47. package/dist/lib/core/registry.d.ts +296 -0
  48. package/dist/lib/core/registry.js +317 -0
  49. package/dist/lib/core/release.d.ts +334 -0
  50. package/dist/lib/core/release.js +465 -0
  51. package/dist/lib/generators/memory-generator.d.ts +83 -0
  52. package/{lib → dist/lib}/generators/memory-generator.js +107 -178
  53. package/dist/lib/generators/nest-generator.d.ts +15 -0
  54. package/{lib → dist/lib}/generators/nest-generator.js +47 -71
  55. package/dist/lib/generators/readme-generator.d.ts +15 -0
  56. package/{lib → dist/lib}/generators/readme-generator.js +9 -14
  57. package/dist/lib/governance-report.d.ts +49 -0
  58. package/dist/lib/governance-report.js +170 -0
  59. package/dist/lib/templates/harness/code-intel.d.mts +2 -0
  60. package/dist/lib/templates/harness/code-intel.mjs +126 -0
  61. package/dist/lib/utils/file-helpers.d.ts +9 -0
  62. package/dist/lib/utils/file-helpers.js +34 -0
  63. package/dist/lib/validators/structure-validator.d.ts +48 -0
  64. package/dist/lib/validators/structure-validator.js +232 -0
  65. package/dist/lib/workspace.d.ts +40 -0
  66. package/dist/lib/workspace.js +174 -0
  67. package/dist/scripts/agent-harness.d.ts +2 -0
  68. package/dist/scripts/agent-harness.js +556 -0
  69. package/dist/scripts/agent-router.d.ts +30 -0
  70. package/dist/scripts/agent-router.js +208 -0
  71. package/dist/scripts/audit-query.d.ts +2 -0
  72. package/dist/scripts/audit-query.js +43 -0
  73. package/dist/scripts/audit-sync.d.ts +2 -0
  74. package/dist/scripts/audit-sync.js +19 -0
  75. package/dist/scripts/build-smart-context.d.ts +1 -0
  76. package/dist/scripts/build-smart-context.js +75 -0
  77. package/dist/scripts/check-standards.d.ts +1 -0
  78. package/dist/scripts/check-standards.js +87 -0
  79. package/dist/scripts/compress-memory.d.ts +16 -0
  80. package/dist/scripts/compress-memory.js +157 -0
  81. package/dist/scripts/compress-project-memory.d.ts +1 -0
  82. package/dist/scripts/compress-project-memory.js +48 -0
  83. package/dist/scripts/context-ops.d.ts +2 -0
  84. package/dist/scripts/context-ops.js +464 -0
  85. package/dist/scripts/dev.d.ts +96 -0
  86. package/dist/scripts/dev.js +312 -0
  87. package/dist/scripts/extract-global-knowledge.d.ts +1 -0
  88. package/dist/scripts/extract-global-knowledge.js +43 -0
  89. package/dist/scripts/generate-dashboard.d.ts +1 -0
  90. package/dist/scripts/generate-dashboard.js +48 -0
  91. package/dist/scripts/governance-dashboard.d.ts +2 -0
  92. package/dist/scripts/governance-dashboard.js +36 -0
  93. package/dist/scripts/hook-guard-paths.d.ts +17 -0
  94. package/dist/scripts/hook-guard-paths.js +68 -0
  95. package/dist/scripts/hook-post-edit.d.ts +20 -0
  96. package/dist/scripts/hook-post-edit.js +70 -0
  97. package/dist/scripts/hook-session-start.d.ts +17 -0
  98. package/dist/scripts/hook-session-start.js +108 -0
  99. package/dist/scripts/hook-user-prompt.d.ts +22 -0
  100. package/dist/scripts/hook-user-prompt.js +193 -0
  101. package/dist/scripts/memory-schema.d.ts +6 -0
  102. package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
  103. package/dist/scripts/query-universal-memory.d.ts +1 -0
  104. package/dist/scripts/query-universal-memory.js +44 -0
  105. package/dist/scripts/release-check.d.ts +14 -0
  106. package/dist/scripts/release-check.js +48 -0
  107. package/dist/scripts/spec-cli.d.ts +29 -0
  108. package/dist/scripts/spec-cli.js +261 -0
  109. package/dist/scripts/sprint-manager.d.ts +1 -0
  110. package/dist/scripts/sprint-manager.js +187 -0
  111. package/dist/scripts/sync-universal-memory.d.ts +1 -0
  112. package/dist/scripts/sync-universal-memory.js +277 -0
  113. package/dist/scripts/token-benchmark.d.ts +20 -0
  114. package/dist/scripts/token-benchmark.js +181 -0
  115. package/dist/scripts/tools-doctor.d.ts +20 -0
  116. package/dist/scripts/tools-doctor.js +120 -0
  117. package/docs/personas/architect/README.md +4 -4
  118. package/docs/personas/developer/README.md +3 -3
  119. package/docs/personas/qa/README.md +3 -3
  120. package/docs/quick-reference.md +9 -9
  121. package/docs/structure.md +3 -3
  122. package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
  123. package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
  124. package/memory/90-decisions/0028-governanca-visivel.md +84 -0
  125. package/package.json +60 -56
  126. package/specs/clean-arch-boilerplate/plan.md +137 -0
  127. package/specs/clean-arch-boilerplate/spec.md +121 -0
  128. package/specs/clean-arch-boilerplate/tasks.md +70 -0
  129. package/specs/coerencia-do-sistema/plan.md +155 -0
  130. package/specs/coerencia-do-sistema/spec.md +15 -14
  131. package/specs/coerencia-do-sistema/tasks.md +115 -0
  132. package/specs/governanca-visivel/plan.md +122 -0
  133. package/specs/governanca-visivel/spec.md +112 -0
  134. package/specs/governanca-visivel/tasks.md +60 -0
  135. package/specs/ts-migration/plan.md +199 -0
  136. package/specs/ts-migration/spec.md +119 -0
  137. package/specs/ts-migration/tasks.md +110 -0
  138. package/bin/create-memory-nest-kit.js +0 -125
  139. package/bin/forja.mjs +0 -143
  140. package/bin/init-project.js +0 -612
  141. package/lib/context-builder.js +0 -257
  142. package/lib/core/checks.mjs +0 -138
  143. package/lib/core/health.mjs +0 -475
  144. package/lib/core/registry.mjs +0 -289
  145. package/lib/core/release.mjs +0 -452
  146. package/lib/templates/harness/code-intel.mjs +0 -119
  147. package/lib/templates/harness/mcp.json +0 -10
  148. package/lib/utils/file-helpers.js +0 -40
  149. package/lib/validators/structure-validator.js +0 -253
  150. package/lib/workspace.mjs +0 -213
  151. package/scripts/agent-harness.mjs +0 -578
  152. package/scripts/agent-router.mjs +0 -189
  153. package/scripts/build-smart-context.js +0 -87
  154. package/scripts/check-standards.js +0 -98
  155. package/scripts/compress-memory.mjs +0 -198
  156. package/scripts/compress-project-memory.js +0 -58
  157. package/scripts/context-ops.mjs +0 -463
  158. package/scripts/dev.mjs +0 -349
  159. package/scripts/extract-global-knowledge.js +0 -52
  160. package/scripts/generate-dashboard.js +0 -59
  161. package/scripts/hook-guard-paths.mjs +0 -75
  162. package/scripts/hook-post-edit.mjs +0 -79
  163. package/scripts/hook-session-start.mjs +0 -104
  164. package/scripts/hook-user-prompt.mjs +0 -185
  165. package/scripts/pre-commit.sh +0 -102
  166. package/scripts/query-universal-memory.js +0 -50
  167. package/scripts/release-check.mjs +0 -56
  168. package/scripts/spec-cli.mjs +0 -260
  169. package/scripts/sprint-manager.js +0 -200
  170. package/scripts/sync-universal-memory.js +0 -286
  171. package/scripts/token-benchmark.mjs +0 -203
  172. package/scripts/tools-doctor.mjs +0 -132
@@ -0,0 +1,119 @@
1
+ /**
2
+ * lib/core/checks.mjs — o runner de checks. Sem opinião sobre o que se checa.
3
+ *
4
+ * Máquina compartilhada por dois catálogos, cada um guardando uma fronteira:
5
+ *
6
+ * health.mjs o núcleo — o que impede o framework de trabalhar aqui (SPEC-009, ADR-0023)
7
+ * release.mjs o tarball — o que impede o pacote de funcionar na máquina de quem instala (SPEC-010)
8
+ *
9
+ * O runner foi extraído, e não copiado, de propósito: duas máquinas iguais divergem com o tempo, e
10
+ * divergência entre superfícies que deveriam concordar é exatamente o defeito que a SPEC-009
11
+ * existiu para matar (o doctor e o hook diziam coisas diferentes sobre a mesma memória).
12
+ *
13
+ * Dois princípios, que valem para qualquer check novo em qualquer catálogo:
14
+ *
15
+ * 1. **Nunca colapsar causas distintas num booleano.** Um probe classifica a causa e devolve a
16
+ * correção *dela*. O bug que originou tudo isso era um `catch { return null }` que engolia três
17
+ * causas e prescrevia a correção de uma.
18
+ * 2. **Uma causa, uma linha vermelha.** Check cuja dependência falhou é `skipped`, não `fail` —
19
+ * senão uma raiz vira três erros vermelhos e o operador não sabe qual perseguir.
20
+ */
21
+ const SEVERITY_FALLBACK = 'critical';
22
+ /**
23
+ * Estreita um valor capturado num `catch` (que o TS tipa como `unknown`) para a forma de erro do
24
+ * Node — `code`/`message` opcionais. Não muda comportamento: só dá ao compilador o que o runtime
25
+ * já assume ao ler `err.code`.
26
+ *
27
+ * @param {unknown} e
28
+ * @returns {NodeJS.ErrnoException}
29
+ */
30
+ export function asErrno(e) {
31
+ return /** @type {NodeJS.ErrnoException} */ (e);
32
+ }
33
+ /**
34
+ * Um probe que estoura é pior que probe nenhum: derrubaria o diagnóstico justamente no ambiente
35
+ * quebrado que ele existe para diagnosticar. O runner blinda cada um e segue para o próximo.
36
+ */
37
+ async function runProbe(check, env) {
38
+ try {
39
+ const probe = await check.probe(env);
40
+ return {
41
+ status: probe.status,
42
+ detail: probe.detail,
43
+ fix: probe.fix ?? null,
44
+ };
45
+ }
46
+ catch (err) {
47
+ const e = asErrno(err);
48
+ return {
49
+ status: 'fail',
50
+ detail: `probe falhou: ${e.message || e}`,
51
+ fix: null,
52
+ };
53
+ }
54
+ }
55
+ /**
56
+ * Executa os checks na ordem declarada.
57
+ *
58
+ * @param {{ checks: Check[], scope?: Scope|'all', env?: object }} opts
59
+ * @returns {Promise<Result[]>}
60
+ */
61
+ export async function runChecks({ checks, scope = 'all', env = {} }) {
62
+ const selected = checks.filter((c) => scope === 'all' || c.scope === scope);
63
+ const statusById = new Map();
64
+ const results = [];
65
+ for (const check of selected) {
66
+ const base = {
67
+ id: check.id,
68
+ title: check.title,
69
+ severity: check.severity || SEVERITY_FALLBACK,
70
+ scope: check.scope,
71
+ };
72
+ // Cascata: sem a dependência de pé, este probe não tem o que observar. Propaga por cadeia, não
73
+ // só um nível — `skipped` conta como "não verificado" para quem depende dele.
74
+ const depStatus = check.dependsOn ? statusById.get(check.dependsOn) : null;
75
+ if (depStatus === 'fail' || depStatus === 'skipped') {
76
+ const motivo = depStatus === 'fail' ? 'que falhou' : 'que não foi verificado';
77
+ results.push({
78
+ ...base,
79
+ status: 'skipped',
80
+ detail: `não verificado: depende de "${check.dependsOn}", ${motivo}`,
81
+ fix: null,
82
+ });
83
+ statusById.set(check.id, 'skipped');
84
+ continue;
85
+ }
86
+ const probe = await runProbe(check, env);
87
+ statusById.set(check.id, probe.status);
88
+ results.push({ ...base, ...probe });
89
+ }
90
+ return results;
91
+ }
92
+ /**
93
+ * Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
94
+ * é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
95
+ *
96
+ * @param {Result[]} results
97
+ * @returns {'ok'|'warn'|'fail'}
98
+ */
99
+ export function worstStatus(results) {
100
+ let seenWarn = false;
101
+ for (const r of results) {
102
+ if (r.status === 'fail' && r.severity === 'critical')
103
+ return 'fail';
104
+ if (r.status === 'fail' || r.status === 'warn')
105
+ seenWarn = true;
106
+ }
107
+ return seenWarn ? 'warn' : 'ok';
108
+ }
109
+ /**
110
+ * Remove template literals do fonte antes de qualquer análise estática de `import`.
111
+ *
112
+ * Os geradores do Forja *escrevem* código NestJS dentro de crases — `import { Module } from
113
+ * '@nestjs/common'` é texto que eles emitem, não dependência que eles usam. Contá-lo faz o check
114
+ * acusar `@nestjs/core` como dependência não declarada e `./app.module` como import quebrado.
115
+ * Observado em campo ao auditar o tarball da 1.1.3.
116
+ */
117
+ export function stripTemplateLiterals(source) {
118
+ return source.replace(/`(?:\\.|[^`\\])*`/gs, '``');
119
+ }
@@ -0,0 +1,60 @@
1
+ /**
2
+ * lib/core/doc-graph.mjs — a documentação lida como dado.
3
+ *
4
+ * O `health.mjs` já lê código (imports, package.json, .mcp.json). Este módulo lê os `.md` que
5
+ * **instruem** o agente e extrai o que é verificável contra o código: comandos citados e links
6
+ * relativos. Leitura pura — nenhum juízo de severidade mora aqui; os checks de `health.mjs` é que
7
+ * julgam (SPEC-011, ADR-0025).
8
+ *
9
+ * Por que existir: o Forja é operado por agentes que executam o que a doc manda. Quando a doc e o
10
+ * registry divergem, o agente não erra por burrice — erra por obediência. Em 2026-07-14 uma
11
+ * auditoria manual achou quatro comandos fantasma no doc que ensina a economia de tokens. Nada
12
+ * quebrou um teste. É a classe do ADR-0021 — erra sem avisar — na camada de instrução.
13
+ */
14
+ import fs from 'node:fs';
15
+ /**
16
+ * Superfícies de instrução. Escaneia o que orienta o agente **agora** — não o histórico.
17
+ *
18
+ * Fora de propósito (plano §D3): `docs/archive/` (legado), `boilerplates/` (conteúdo do projeto
19
+ * gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/` (registro histórico: uma
20
+ * spec ou ADR pode legitimamente citar um comando proposto ou já removido).
21
+ */
22
+ export declare const DOC_SURFACES: string[];
23
+ /** Todos os `.md` das superfícies de instrução, caminhos relativos à raiz. */
24
+ export declare function docFiles(env: any): string[];
25
+ /**
26
+ * Comandos citados nas superfícies de instrução.
27
+ * @returns {{ file: string, line: number, command: string }[]}
28
+ */
29
+ export declare function scanCommands(env: any): {
30
+ file: string;
31
+ line: number;
32
+ command: string;
33
+ }[];
34
+ /**
35
+ * Links markdown relativos nas superfícies de instrução, com o alvo já resolvido à raiz.
36
+ * @returns {{ file: string, line: number, target: string, resolved: string }[]}
37
+ */
38
+ export declare function scanLinks(env: any): {
39
+ file: string;
40
+ line: number;
41
+ target: string;
42
+ resolved: string;
43
+ }[];
44
+ /**
45
+ * Allowlist **derivada** dos comandos que pertencem ao projeto que o Forja *gera* (`start:dev`,
46
+ * `test:cov`, `test:e2e`, `memory:db:*`), não ao Forja. Nunca uma lista literal — uma lista manual
47
+ * mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
48
+ *
49
+ * Duas fontes, porque o projeto gerado tem duas: os `"scripts"` inline que os **geradores** escrevem
50
+ * e os `package.json` dos **boilerplates**. Derivar de só uma delas produz falso positivo na outra —
51
+ * foi `test:e2e` (vive no boilerplate, não no gerador) que revelou isso.
52
+ *
53
+ * @returns {Set<string>}
54
+ */
55
+ export declare function projectCommands(env: any): Set<unknown>;
56
+ /** Ambiente padrão para uso fora do runner de checks (o CLI, testes de integração). */
57
+ export declare function defaultEnv(overrides?: {}): {
58
+ root: string;
59
+ fs: typeof fs;
60
+ };
@@ -0,0 +1,235 @@
1
+ /**
2
+ * lib/core/doc-graph.mjs — a documentação lida como dado.
3
+ *
4
+ * O `health.mjs` já lê código (imports, package.json, .mcp.json). Este módulo lê os `.md` que
5
+ * **instruem** o agente e extrai o que é verificável contra o código: comandos citados e links
6
+ * relativos. Leitura pura — nenhum juízo de severidade mora aqui; os checks de `health.mjs` é que
7
+ * julgam (SPEC-011, ADR-0025).
8
+ *
9
+ * Por que existir: o Forja é operado por agentes que executam o que a doc manda. Quando a doc e o
10
+ * registry divergem, o agente não erra por burrice — erra por obediência. Em 2026-07-14 uma
11
+ * auditoria manual achou quatro comandos fantasma no doc que ensina a economia de tokens. Nada
12
+ * quebrou um teste. É a classe do ADR-0021 — erra sem avisar — na camada de instrução.
13
+ */
14
+ import fs from 'node:fs';
15
+ import path from 'node:path';
16
+ /**
17
+ * Superfícies de instrução. Escaneia o que orienta o agente **agora** — não o histórico.
18
+ *
19
+ * Fora de propósito (plano §D3): `docs/archive/` (legado), `boilerplates/` (conteúdo do projeto
20
+ * gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/` (registro histórico: uma
21
+ * spec ou ADR pode legitimamente citar um comando proposto ou já removido).
22
+ */
23
+ export const DOC_SURFACES = [
24
+ 'docs',
25
+ 'prompts',
26
+ '.claude/agents',
27
+ 'AGENTS.md',
28
+ 'CLAUDE.md',
29
+ 'README.md',
30
+ 'README.en.md',
31
+ 'DOC-MAP.md',
32
+ ];
33
+ const EXCLUDED_DIRS = new Set(['archive', 'node_modules']);
34
+ /** Um comando do Forja: `forja x:y` ou `npm run x:y`, com ao menos um `:` (o discriminador, §D4). */
35
+ const COMMAND_RE = /(?:\bforja\s+|npm run\s+)([a-z][a-z0-9]*(?::[a-z0-9-]+)+)/g;
36
+ /** Link markdown relativo. Ignora http(s):// e âncoras puras; a âncora de um path é descartada. */
37
+ const LINK_RE = /\]\(([^)]+)\)/g;
38
+ function safeRead(env, file) {
39
+ try {
40
+ return env.fs.readFileSync(file, 'utf8');
41
+ }
42
+ catch {
43
+ return null;
44
+ }
45
+ }
46
+ /** Coleta os `.md` sob uma superfície (arquivo direto ou diretório varrido, menos EXCLUDED_DIRS). */
47
+ function collectMarkdown(env, surface) {
48
+ const abs = path.join(env.root, surface);
49
+ const out = [];
50
+ const walk = (p) => {
51
+ let st;
52
+ try {
53
+ st = env.fs.statSync(p);
54
+ }
55
+ catch {
56
+ return;
57
+ }
58
+ if (st.isDirectory()) {
59
+ let entries;
60
+ try {
61
+ entries = env.fs.readdirSync(p);
62
+ }
63
+ catch {
64
+ return;
65
+ }
66
+ for (const entry of entries) {
67
+ if (EXCLUDED_DIRS.has(entry))
68
+ continue;
69
+ walk(path.join(p, entry));
70
+ }
71
+ }
72
+ else if (p.endsWith('.md')) {
73
+ out.push(p);
74
+ }
75
+ };
76
+ walk(abs);
77
+ return out;
78
+ }
79
+ /** Todos os `.md` das superfícies de instrução, caminhos relativos à raiz. */
80
+ export function docFiles(env) {
81
+ const seen = new Set();
82
+ for (const surface of DOC_SURFACES) {
83
+ for (const file of collectMarkdown(env, surface)) {
84
+ seen.add(path.relative(env.root, file));
85
+ }
86
+ }
87
+ return [...seen];
88
+ }
89
+ /**
90
+ * Comandos citados nas superfícies de instrução.
91
+ * @returns {{ file: string, line: number, command: string }[]}
92
+ */
93
+ export function scanCommands(env) {
94
+ const hits = [];
95
+ for (const rel of docFiles(env)) {
96
+ const src = safeRead(env, path.join(env.root, rel));
97
+ if (src == null)
98
+ continue;
99
+ const lines = src.split('\n');
100
+ lines.forEach((text, i) => {
101
+ for (const m of text.matchAll(COMMAND_RE)) {
102
+ hits.push({ file: rel, line: i + 1, command: m[1] });
103
+ }
104
+ });
105
+ }
106
+ return hits;
107
+ }
108
+ /**
109
+ * Links markdown relativos nas superfícies de instrução, com o alvo já resolvido à raiz.
110
+ * @returns {{ file: string, line: number, target: string, resolved: string }[]}
111
+ */
112
+ export function scanLinks(env) {
113
+ const hits = [];
114
+ for (const rel of docFiles(env)) {
115
+ const src = safeRead(env, path.join(env.root, rel));
116
+ if (src == null)
117
+ continue;
118
+ const dir = path.dirname(rel);
119
+ const lines = src.split('\n');
120
+ lines.forEach((text, i) => {
121
+ for (const m of text.matchAll(LINK_RE)) {
122
+ const raw = m[1].trim();
123
+ if (!raw || raw.startsWith('#'))
124
+ continue; // âncora pura
125
+ if (/^[a-z][a-z0-9+.-]*:/i.test(raw))
126
+ continue; // http:, mailto:, etc. — externo
127
+ const target = raw.split('#')[0]; // descarta âncora do path
128
+ if (!target)
129
+ continue;
130
+ hits.push({
131
+ file: rel,
132
+ line: i + 1,
133
+ target,
134
+ resolved: path.normalize(path.join(dir, target)),
135
+ });
136
+ }
137
+ });
138
+ }
139
+ return hits;
140
+ }
141
+ /** Extrai as keys de todo bloco `"scripts": { … }` de um fonte de gerador. */
142
+ function scriptKeys(source) {
143
+ const keys = new Set();
144
+ const block = source.match(/"scripts"\s*:\s*\{([\s\S]*?)\}/g);
145
+ if (!block)
146
+ return keys;
147
+ for (const b of block) {
148
+ for (const m of b.matchAll(/"([a-z][a-z0-9]*(?::[a-z0-9-]+)+)"\s*:/g)) {
149
+ keys.add(m[1]);
150
+ }
151
+ }
152
+ return keys;
153
+ }
154
+ /** Todo `package.json` sob um diretório (boilerplates têm vários, aninhados). */
155
+ function findPackageJsons(env, dir, acc = []) {
156
+ let entries;
157
+ try {
158
+ entries = env.fs.readdirSync(dir);
159
+ }
160
+ catch {
161
+ return acc;
162
+ }
163
+ for (const entry of entries) {
164
+ if (EXCLUDED_DIRS.has(entry))
165
+ continue;
166
+ const p = path.join(dir, entry);
167
+ let st;
168
+ try {
169
+ st = env.fs.statSync(p);
170
+ }
171
+ catch {
172
+ continue;
173
+ }
174
+ if (st.isDirectory())
175
+ findPackageJsons(env, p, acc);
176
+ else if (entry === 'package.json')
177
+ acc.push(p);
178
+ }
179
+ return acc;
180
+ }
181
+ /**
182
+ * Allowlist **derivada** dos comandos que pertencem ao projeto que o Forja *gera* (`start:dev`,
183
+ * `test:cov`, `test:e2e`, `memory:db:*`), não ao Forja. Nunca uma lista literal — uma lista manual
184
+ * mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
185
+ *
186
+ * Duas fontes, porque o projeto gerado tem duas: os `"scripts"` inline que os **geradores** escrevem
187
+ * e os `package.json` dos **boilerplates**. Derivar de só uma delas produz falso positivo na outra —
188
+ * foi `test:e2e` (vive no boilerplate, não no gerador) que revelou isso.
189
+ *
190
+ * @returns {Set<string>}
191
+ */
192
+ export function projectCommands(env) {
193
+ const commands = new Set();
194
+ // Fonte 1: blocos "scripts" inline dos geradores.
195
+ const genDir = path.join(env.root, 'lib', 'generators');
196
+ let genEntries = [];
197
+ try {
198
+ genEntries = env.fs.readdirSync(genDir);
199
+ }
200
+ catch {
201
+ /* sem geradores — segue */
202
+ }
203
+ for (const entry of genEntries) {
204
+ if (!/\.(mjs|js)$/.test(entry))
205
+ continue;
206
+ const src = safeRead(env, path.join(genDir, entry));
207
+ if (src == null)
208
+ continue;
209
+ for (const key of scriptKeys(src))
210
+ commands.add(key);
211
+ }
212
+ // Fonte 2: package.json dos boilerplates.
213
+ for (const pkgPath of findPackageJsons(env, path.join(env.root, 'boilerplates'))) {
214
+ const src = safeRead(env, pkgPath);
215
+ if (src == null)
216
+ continue;
217
+ try {
218
+ const scripts = JSON.parse(src).scripts || {};
219
+ for (const key of Object.keys(scripts))
220
+ commands.add(key);
221
+ }
222
+ catch {
223
+ /* package.json inválido no boilerplate — ignora */
224
+ }
225
+ }
226
+ return commands;
227
+ }
228
+ /** Ambiente padrão para uso fora do runner de checks (o CLI, testes de integração). */
229
+ export function defaultEnv(overrides = {}) {
230
+ return {
231
+ root: path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..'),
232
+ fs,
233
+ ...overrides,
234
+ };
235
+ }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * lib/core/health.mjs — saúde do núcleo do Forja.
3
+ *
4
+ * Fonte única de verdade sobre o que impede o framework de trabalhar. Consumida por
5
+ * `tools:doctor` (gate, com exit code), pelo hook `SessionStart` (aviso, nunca trava) e,
6
+ * futuramente, pelo release-auditor.
7
+ *
8
+ * Por que existir (SPEC-009):
9
+ *
10
+ * O `tools:doctor` auditava cinco ferramentas *opcionais* — sobre as quais ele mesmo dizia
11
+ * "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o `better-sqlite3`
12
+ * ficou com ABI de outra major do Node, a memória universal morreu inteira: o doctor reportou
13
+ * "2/5 ferramentas disponíveis", e o SessionStart prescreveu `npm install`, que não recompila
14
+ * binário nativo. A correção real era `npm rebuild better-sqlite3`. Cada superfície tinha sua
15
+ * própria heurística, e por isso uma delas pôde mentir sozinha.
16
+ *
17
+ * Dois princípios, que valem para qualquer check novo:
18
+ *
19
+ * 1. **Nunca colapsar causas distintas num booleano.** O bug original era um `catch { return
20
+ * null }` que engolia "sem node_modules", "ABI incompatível" e "banco ausente" no mesmo
21
+ * `null` — e então prescrevia a correção de apenas uma das três. Um probe classifica a causa
22
+ * e devolve a correção *dela*.
23
+ * 2. **Uma causa, uma linha vermelha.** Com o ABI quebrado, os checks de memória também
24
+ * falhariam, e o operador veria três erros sem saber qual é a raiz. Daí `dependsOn`: check
25
+ * cuja dependência falhou é `skipped`, não `fail`.
26
+ */
27
+ import fs from 'node:fs';
28
+ import { getWorkspaceDbPath, getWorkspaceInfo } from '../workspace.ts';
29
+ import { worstStatus } from './checks.ts';
30
+ /** @typedef {import('./checks.ts').Check} Check */
31
+ /** @typedef {import('./checks.ts').Result} Result */
32
+ /** @typedef {import('./checks.ts').Status} Status */
33
+ export { worstStatus };
34
+ /**
35
+ * Ambiente injetável. Existe para que os probes sejam testáveis sem mockar o loader de módulos
36
+ * do Node nem corromper `node_modules` de verdade — simular um ABI quebrado é passar um
37
+ * `importModule` que lança `ERR_DLOPEN_FAILED`.
38
+ *
39
+ * @typedef {object} Env
40
+ * @property {string} root Raiz do repo do framework.
41
+ * @property {typeof fs} fs
42
+ * @property {(specifier: string) => Promise<unknown>} importModule
43
+ * @property {object} process Só o que os probes leem: `versions`, `env`.
44
+ * @property {{ dbPath: () => string, info: () => object }} workspace
45
+ */
46
+ /** @returns {Env} */
47
+ export declare function defaultEnv(overrides?: {}): {
48
+ root: string;
49
+ fs: typeof fs;
50
+ importModule: (specifier: any) => Promise<any>;
51
+ process: NodeJS.Process;
52
+ workspace: {
53
+ dbPath: typeof getWorkspaceDbPath;
54
+ info: typeof getWorkspaceInfo;
55
+ };
56
+ };
57
+ /** Estamos dentro do repo do framework, e não numa instalação do pacote? */
58
+ export declare function isFrameworkRepo(env: any): boolean;
59
+ /** @type {Check[]} */
60
+ export declare const CHECKS: ({
61
+ id: string;
62
+ title: string;
63
+ severity: string;
64
+ scope: string;
65
+ probe(env: any): Promise<{
66
+ status: string;
67
+ detail: string;
68
+ fix: string;
69
+ } | {
70
+ status: string;
71
+ detail: string;
72
+ fix: null;
73
+ }>;
74
+ } | {
75
+ id: string;
76
+ title: string;
77
+ severity: string;
78
+ scope: string;
79
+ probe(env: any): {
80
+ status: string;
81
+ detail: string;
82
+ fix: string;
83
+ } | {
84
+ status: string;
85
+ detail: string;
86
+ fix: null;
87
+ };
88
+ })[];
89
+ /**
90
+ * Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
91
+ * `defaultEnv` do framework, que o runner genérico não conhece nem deve conhecer.
92
+ *
93
+ * `scope: 'runtime'` roda só os checks baratos e portáveis — é o que o hook SessionStart usa, onde
94
+ * há orçamento de 5s e nenhuma tolerância a travar a sessão.
95
+ *
96
+ * @param {{ scope?: import('./checks.ts').Scope|'all', env?: Partial<Env>, checks?: Check[] }} [opts]
97
+ * @returns {Promise<Result[]>}
98
+ */
99
+ export declare function runChecks(opts?: {
100
+ scope?: import('./checks.ts').Scope | 'all';
101
+ env?: any;
102
+ checks?: import('./checks.ts').Check[];
103
+ }): Promise<import("./checks.ts").Result[]>;