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,112 @@
1
+ # Spec: governanca-visivel
2
+
3
+ - **ID**: SPEC-014
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-18
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry + auditoria), [ADR-0022](../../memory/90-decisions/0022-congelar-dashboard-web.md) (dashboard congelado), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens), [ADR-0002](../../memory/90-decisions/0002-sqlite-fts5-busca.md) (SQLite FTS5)
9
+
10
+ ## 1. Problema
11
+
12
+ O core grava **toda execução** em `.context/forja-runs.jsonl` (ADR-0020): comando, args, exit code,
13
+ duração, timestamp. São 255 runs registrados hoje. É o dado mais rico de governança que o framework
14
+ tem — a resposta viva para *"o processo foi seguido? o que rodou? o que reprovou? quanto custou?"*.
15
+
16
+ E é **write-only.** Nada lê. Para responder "quantas vezes o `release:check` reprovou este mês" ou
17
+ "qual gate está mais lento", alguém abre um `.jsonl` de 255 linhas e conta na mão. O dado existe e é
18
+ inerte — a mesma classe do problema que a sessão inteira atacou (conhecimento que existe mas não é
19
+ consultável vira conhecimento morto).
20
+
21
+ E há uma segunda ausência: o Forja **não tem superfície visual**. A tentativa anterior (SPEC-002) foi
22
+ **congelada** (ADR-0022) — mas não por ser visual, e sim por ser um **servidor** com rotas que
23
+ *executam* processos (`POST .../run/:role`): virou passivo de manutenção e de segurança. A lição não
24
+ é "sem visual"; é "sem servidor, sem execução". Um artefato **estático, gerado por comando**, de
25
+ leitura, não repete o erro — é a mesma natureza do `project:dashboard` (que já gera um relatório),
26
+ só que sobre governança e legível de relance.
27
+
28
+ ## 2. Proposta de valor
29
+
30
+ A trilha de auditoria deixa de ser um arquivo que ninguém abre: vira **consultável** por comando, e
31
+ **visível** num painel de governança **estático e gerado** — leitura, sem servidor (a lição do
32
+ ADR-0022). "O processo foi seguido?" passa a ter resposta de relance, do dado real.
33
+
34
+ ## 3. User stories
35
+
36
+ - **Como** governança, **quero** consultar a auditoria por comando/gate/período, **para que**
37
+ "quantas vezes o `release:check` reprovou" seja uma query, não uma contagem manual.
38
+ - **Como** operador, **quero** um painel de relance com o estado dos gates, do pipeline SDD e da
39
+ atividade recente, **para que** eu veja a saúde do framework sem ler dez arquivos.
40
+ - **Como** quem opera vários projetos, **quero** que o painel seja um **artefato gerado** (HTML
41
+ estático, sem servidor), **para que** eu não reintroduza o passivo que congelou o dashboard antigo.
42
+ - **Como** agente, **quero** ler o resumo da auditoria em vez do `.jsonl` cru, **para que** eu gaste
43
+ menos tokens entendendo o que já rodou.
44
+
45
+ ## 4. Critérios de aceite (Definition of Done)
46
+
47
+ - [x] AC-1: **Ingest** — um comando (`audit:sync`) lê `.context/forja-runs.jsonl` (a fonte de verdade
48
+ append-only) e o projeta numa tabela SQLite consultável no workspace. Idempotente: rodar duas
49
+ vezes não duplica.
50
+ - [x] AC-2: **Query** — `audit:query` responde por comando, gate, exit code e janela de tempo
51
+ (ex.: `--since 7d`, `--cmd release:check`, `--failed`). Saída legível + contagem.
52
+ - [x] AC-3: **Painel gerado** — um comando gera um **HTML estático e self-contained** (CSS/JS
53
+ inline, zero asset externo) com: estado dos gates, quadro do pipeline SDD (specs × stages),
54
+ atividade recente da auditoria (últimos runs, reprovações, gates mais lentos) e as métricas
55
+ (comandos, testes, ADRs).
56
+ - [x] AC-4: **Sem servidor, leitura, gerado** (ADR-0022): o painel é um arquivo escrito em disco,
57
+ regenerado sob demanda. **Zero** rota, zero processo executável, zero `POST`. O rodapé declara
58
+ isso.
59
+ - [x] AC-5: **Dado real, não fixture** — o painel e as queries leem a auditoria e as specs de
60
+ verdade; nada hard-coded. Um repo sem runs mostra "sem atividade", não quebra.
61
+ - [x] AC-6: **Degrada sem workspace/db** — como todo o resto (ADR-0021): sem `universal.db`, os
62
+ comandos avisam com a correção (`sync:universal`/`audit:sync`), não estouram.
63
+ - [x] AC-7: Entradas no registry (ADR-0020); os comandos passam pelo core e são auditados como os
64
+ demais.
65
+ - [x] AC-8: Gates do próprio Forja: `release:check` (scripts no `files[]`), `tools:doctor`
66
+ (docs-commands não acusa fantasma), `npm test` verde. Testes dos comandos novos.
67
+ - [x] AC-9: ADR-0028 registrando a decisão (auditoria consultável; painel estático-gerado como a
68
+ resposta correta ao ADR-0022).
69
+
70
+ ## 5. Escopo
71
+
72
+ **Dentro**:
73
+ - `audit:sync` (ingest jsonl → tabela) e `audit:query` (consulta).
74
+ - O comando gerador do painel HTML estático de governança.
75
+ - Schema da tabela de auditoria (no `memory-schema`/workspace db).
76
+ - ADR-0028 + testes.
77
+
78
+ **Fora** (explícito):
79
+ - **Servidor, rotas, execução pela web.** É exatamente o que o ADR-0022 congelou. Inegociável.
80
+ - **Instrumentar token por tarefa.** O painel tem lugar para isso, mas medir o custo de token de
81
+ cada tarefa é outra frente (o audit hoje grava duração, não tokens). Follow-up.
82
+ - **Substituir o `project:dashboard`** (markdown, ecossistema de projetos). Este é sobre governança
83
+ do framework; coexistem. Uma futura unificação é outra decisão.
84
+ - **Tempo real / auto-refresh.** O painel é gerado sob demanda; quem quer atualizar, regenera.
85
+
86
+ ## 6. NFRs / restrições
87
+
88
+ - **Estático e self-contained (inegociável)**: o HTML abre com `file://`, sem rede, sem servidor. É o
89
+ que separa esta spec da SPEC-002 congelada.
90
+ - **Fonte de verdade preservada**: o `.jsonl` continua sendo o log append-only; a tabela é uma
91
+ projeção reconstruível (`audit:sync` do zero recria).
92
+ - **Token-aware**: o resumo da auditoria que o agente lê é menor que o `.jsonl` cru — a própria
93
+ feature serve o ADR-0009.
94
+ - **Resiliência (ADR-0021)**: sem workspace/db, avisa e segue; nunca estoura.
95
+
96
+ ## 7. Riscos e mitigação
97
+
98
+ | Risco | Prob | Impacto | Mitigação |
99
+ |---|---|---|---|
100
+ | Virar "dashboard servidor" de novo | B | **A** | AC-4 é gate: zero rota/processo. O painel é arquivo, não serviço |
101
+ | FTS5 vs SQL estruturado — over-engineering | M | B | O dado é estruturado (cmd/exit/duração); query por coluna. FTS só nos args, se valer |
102
+ | Painel gerado fica pesado/externo | M | M | Self-contained obrigatório (AC-3); mesmo princípio do prototipo já validado |
103
+ | Auditoria esparsa deixa o painel vazio | M | B | AC-5: "sem atividade" é estado válido, não erro. O dado cresce com o uso |
104
+
105
+ ## 8. Métricas de sucesso
106
+
107
+ - "O `release:check` reprovou quantas vezes?" passa de contagem manual num `.jsonl` a **uma query**.
108
+ - O painel responde "o framework está saudável?" de relance, do dado real — e é um **arquivo**, não
109
+ um serviço rodando (a lição do ADR-0022, aplicada).
110
+ - O resumo de auditoria que o agente lê é menor em tokens que o `.jsonl` cru — a governança visível
111
+ também economiza contexto (ADR-0009).
112
+ - 90 dias: ninguém abre o `forja-runs.jsonl` na mão; a pergunta de governança vira comando ou painel.
@@ -0,0 +1,60 @@
1
+ # Tasks: governanca-visivel
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: done
6
+ - **Criado em**: 2026-07-19
7
+
8
+ > Ordem: dado consultável primeiro (audit), painel depois (que lê o audit). Env injetável em toda a
9
+ > lógica pura, para os testes não tocarem o workspace real.
10
+
11
+ ---
12
+
13
+ ## T1 — Schema + `lib/audit.mjs`
14
+ - **Owner**: Worker · **Estimativa**: M · **Depende de**: —
15
+ - **Paths**: `scripts/memory-schema.mjs`, `lib/audit.mjs`, `test/audit.test.js`
16
+ - **Done**:
17
+ - [ ] Tabela `audit_runs` (`line_hash` PK, `ts`, `cmd`, `args`, `exit_code`, `duration_ms`; índices em `cmd`/`ts`).
18
+ - [ ] `syncAudit(env)`: lê o jsonl, `INSERT OR IGNORE` por `line_hash` — idempotente (AC-1). Linha malformada é pulada, não derruba.
19
+ - [ ] `queryAudit(env, {since,cmd,gate,failed})` e `auditSummary(env)` (total, fails, byCmd, slowest, recent) — AC-2.
20
+ - [ ] `env` injetável (`fs`/`dbPath`/`jsonlPath`); testes com jsonl de fixture, incl. idempotência e linha corrompida.
21
+
22
+ ## T2 — `audit:sync` + `audit:query` (registry)
23
+ - **Owner**: Worker · **Estimativa**: P · **Depende de**: T1
24
+ - **Paths**: `scripts/audit-sync.mjs`, `scripts/audit-query.mjs`, `lib/core/registry.mjs`
25
+ - **Done**:
26
+ - [ ] CLIs finos sobre `lib/audit.mjs`; entradas no registry (domínio `governanca`), passam pelo core.
27
+ - [ ] Degradam sem workspace/db: avisam com `sync:universal`/`audit:sync`, não estouram (AC-6).
28
+ - [ ] **Prova real**: `audit:sync` ingere os 255 runs do workspace; `audit:query --failed` e `--cmd release:check` respondem.
29
+
30
+ ## T3 — `lib/governance-report.mjs` (coleta + render)
31
+ - **Owner**: Worker · **Estimativa**: M · **Depende de**: T1
32
+ - **Paths**: `lib/governance-report.mjs`, `test/governance-report.test.js`
33
+ - **Done**:
34
+ - [ ] `collect(env)`: specs (status por stage), ADRs (contagem/lista de `memory/90-decisions`), gates (checks de `health`/`release` + último exit da auditoria — **sem reexecutar**, D4), métricas (comandos do registry).
35
+ - [ ] `renderHtml(data)`: HTML **self-contained** — CSS/JS inline, **zero asset externo** (AC-3/AC-4). Tema claro/escuro. Reaproveita o design do protótipo.
36
+ - [ ] Dado real, não fixture (AC-5): repo sem runs → seção "sem atividade", não quebra.
37
+ - [ ] Teste: `renderHtml` não emite `http`/`src=`/`@import` externo; `collect` degrada sem db.
38
+
39
+ ## T4 — `governance:dashboard` (registry)
40
+ - **Owner**: Worker · **Estimativa**: P · **Depende de**: T3
41
+ - **Paths**: `scripts/governance-dashboard.mjs`, `lib/core/registry.mjs`
42
+ - **Done**:
43
+ - [ ] Escreve o HTML num arquivo (default `<workspace>/.context/governance.html`), reporta o caminho.
44
+ - [ ] **Zero execução** na geração — só lê e escreve (AC-4 / kill criteria). Entrada no registry.
45
+ - [ ] **Prova real**: gera o arquivo, abre e confere que os gates/SDD/auditoria refletem o repo.
46
+
47
+ ## T5 — ADR-0028
48
+ - **Owner**: SDD Architect · **Estimativa**: P · **Depende de**: T2, T4
49
+ - **Paths**: `memory/90-decisions/0028-*.md`
50
+ - **Done**: registra D1 (tabela = projeção), D4 (painel não executa), D5 (comando novo); referencia
51
+ ADR-0022 (a resposta correta ao dashboard congelado), ADR-0020, ADR-0021.
52
+
53
+ ## T6 — Gates (Governance)
54
+ - **Owner**: Governance · **Estimativa**: P · **Depende de**: T2, T4, T5
55
+ - **Done**: `release:check` (scripts no `files[]`), `tools:doctor` (docs-commands não acusa fantasma
56
+ nos comandos novos), `npm test` verde. spec → `done`.
57
+
58
+ ---
59
+ ## Handoffs
60
+ Worker (T1-T4), SDD Architect (T5), Governance (T6). `forja agent:route` a cada fronteira (ADR-0005).
@@ -0,0 +1,199 @@
1
+ # Plan: ts-migration
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
+ O nó da migração não é renomear `.mjs → .ts` — é **como o core acha o script de um comando em dois
12
+ runtimes**. Hoje `bin/forja.mjs:118` faz `spawnSync('node', [path.join(root, cmd.node)])`, e o
13
+ registry guarda a extensão literal (`scripts/tools-doctor.mjs`). Em dev o alvo é `.ts`; no pacote
14
+ publicado é `dist/scripts/tools-doctor.js`. O mesmo registry não pode cravar as duas.
15
+
16
+ A saída é **desacoplar o registry da extensão**: a entrada passa a ser `scripts/tools-doctor` (sem
17
+ extensão), e o core resolve o arquivo real tentando `.ts → .js → .mjs` conforme o que existe. Em dev
18
+ acha o `.ts`; no publicado acha o `.js` sob `dist/`. Isso resolve o runtime duplo com uma mudança
19
+ pequena e contida, e ainda limpa o registry.
20
+
21
+ Tudo o mais é disciplina: `checkJs` primeiro para achar os erros de tipo com os arquivos ainda
22
+ rodando como `.mjs`, depois renomear **leaf-first** com a suíte verde a cada passo. A rede de
23
+ segurança é que a migração não muda semântica — se os 109 testes passam sem edição de lógica, a
24
+ renomeação não quebrou nada.
25
+
26
+ ## 2. Módulos afetados
27
+
28
+ | Caminho | Mudança | Risco |
29
+ |---|---|---|
30
+ | `tsconfig.json` | **criar** — `checkJs` on-ramp, depois `outDir: dist`, `.d.ts` | M |
31
+ | `lib/core/registry.mjs` → `.ts` | `node:` sem extensão; tipos `Command`/`Domain` | **A** |
32
+ | `bin/forja.mjs` → `.ts` | resolver extension-agnostic (`.ts→.js→.mjs`) no dispatch | **A** |
33
+ | `lib/core/checks.mjs` → `.ts` | `Check`/`Probe`/`Result`/`Env` viram tipos reais | M |
34
+ | `lib/core/{health,release,doc-graph,workspace}.mjs` → `.ts` | tipam contra `checks.ts` | M |
35
+ | `lib/core/release` | `build-fresh` novo; `smoke-commands` usa o `bin` do package.json, não path fixo | M |
36
+ | `scripts/*.{mjs,js}` → `.ts` | ~20 arquivos, leaf-first; hooks incluídos | M |
37
+ | `lib/generators/*.js` → `.ts` | tipa a assinatura; o **conteúdo** (template string) fica string | B |
38
+ | `package.json` | `main`/`types`/`exports`/`bin` → `dist/`; `build`; `files[]` dist; `prepublishOnly` | **A** |
39
+ | `.claude/settings.json` | hooks → `.ts` (dev roda nativo) | B |
40
+ | `.github/workflows/ci.yml` | só o step `types:check` (o build vive no `release:check`, D4) | B |
41
+ | `memory/90-decisions/0026-*.md` | **criar** — ADR | B |
42
+
43
+ Os três `A` são o registry, o dispatch e o `package.json` — a tríade que decide se o comando roda
44
+ nos dois runtimes. Tudo passa por eles.
45
+
46
+ ## 3. Diagrama de fluxo
47
+
48
+ ```
49
+ DEV (Node 26, sem build) PUBLICADO (Node >=20, dist/)
50
+ ────────────────────── ────────────────────────────
51
+ node bin/forja.ts forja → dist/bin/forja.js
52
+ │ │
53
+ │ registry: 'scripts/tools-doctor' │ (mesma entrada, sem extensão)
54
+ ▼ ▼
55
+ resolve('<root>/scripts/tools-doctor')
56
+ tenta .ts → .js → .mjs
57
+ │ dev: acha .ts │ publicado: root=dist/, acha dist/scripts/tools-doctor.js
58
+ ▼ ▼
59
+ spawn node <arquivo resolvido> spawn node <arquivo resolvido>
60
+
61
+ build (só p/ publicar): tsc rootDir=. outDir=dist → dist/ espelha a árvore
62
+ build-fresh (release:check): recompila e compara com dist/ commitado → reprova se difere
63
+ ```
64
+
65
+ ## 4. Contratos (API/CLI/Schema)
66
+
67
+ ```ts
68
+ // lib/core/registry.ts
69
+ export interface Command {
70
+ domain: string;
71
+ desc: string;
72
+ node?: string; // caminho SEM extensão, relativo à raiz (dev) / a dist/ (publicado)
73
+ bin?: string;
74
+ args?: string[];
75
+ }
76
+ export const COMMANDS: Record<string, Command>;
77
+
78
+ // lib/core/checks.ts — os contratos que hoje são @typedef viram tipos verificados
79
+ export type Severity = 'critical' | 'warn';
80
+ export type Status = 'ok' | 'warn' | 'fail' | 'skipped';
81
+ export interface Probe { status: Status; detail: string; fix?: string | null; }
82
+ export interface Check { id: string; title: string; severity: Severity; scope?: string;
83
+ dependsOn?: string; probe: (env: Env) => Probe | Promise<Probe>; }
84
+ ```
85
+
86
+ **Resolução de script (o coração)** — `bin/forja.ts` calcula `root = dirname(selfPath)/..`
87
+ (dev: repo; publicado: `dist/`) e resolve `cmd.node` tentando as extensões na ordem `.ts, .js,
88
+ .mjs`. A primeira que existe vence. Sem extensão no registry, sem `if (isDev)`.
89
+
90
+ **`package.json`**:
91
+
92
+ | Campo | Valor |
93
+ |---|---|
94
+ | `bin.forja` | `dist/bin/forja.js` |
95
+ | `main` / `types` | `dist/lib/index.js` / `.d.ts` |
96
+ | `files[]` | troca `bin/ lib/ scripts/` por `dist/` (o resto — memory/, docs/, boilerplates/ — fica) |
97
+ | `scripts.build` | `tsc` |
98
+ | `scripts.prepublishOnly` | `node bin/forja.mjs release:check -- --publish` (o gate builda, D4) |
99
+
100
+ ## 5. Decisões e alternativas
101
+
102
+ **D1: Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
103
+ `dist/lib`, `dist/scripts`. Alternativa rejeitada: mover a fonte para `src/`. Isso trocaria todo
104
+ import, todo path do registry, os hooks do `settings.json`, o `files[]` e as smoke-commands do
105
+ release — blast radius enorme, contra o "verde contínuo". O layout plano mantém a migração mecânica.
106
+
107
+ **D2: Registry sem extensão + resolver (o coração).** `node: 'scripts/tools-doctor'`; o core tenta
108
+ `.ts→.js→.mjs`. Desacopla o registry do runtime e limpa a entrada. Alternativa rejeitada: guardar
109
+ `.js` e exigir build em dev — mata o "roda sem build" (o NFR inegociável). Alternativa rejeitada:
110
+ dois registries — é como se chega a duas verdades divergentes, o defeito que a SPEC-009 matou.
111
+
112
+ **D3: Runtime duplo.** Dev roda `.ts` nativo (confirmado: Node 26 executa `.ts` e `node --test`
113
+ roda `.ts`); publicado roda `dist/.js`. `engines.node` fica `>=20` — por isso publicamos compilado.
114
+ O usuário final não é obrigado a Node novo; o dev sim.
115
+
116
+ **D4 (revisado na implementação): o gate builda o `dist/`, e o `dist/` não é commitado.** O plano
117
+ original commitava `dist/` e um check `build-fresh` fazia diff contra a fonte — mas isso guarda um
118
+ artefato de build no git e reintroduz staleness ("o `dist/` commitado bate com o `src/`?"). A versão
119
+ que shipou é mais simples: `dist/` é gitignored e o `release:check` roda `npm run build` **antes de
120
+ empacotar** (só quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
121
+ empacota o mesmo disco recém-buildado, o tarball provado é exatamente o publicado — sem diff, sem
122
+ artefato no git, sem janela de staleness. Efeito colateral que destravou a Fase 3: a prova fica
123
+ self-contained e **não precisa de um step de `build` no `ci.yml`** (que exigiria escopo de workflow e
124
+ acoplaria a prova ao CI). Uma máquina — o gate — constrói e prova.
125
+
126
+ **D5: `checkJs` antes de renomear; leaf-first depois.** Ordem por dependência:
127
+ `workspace → checks → registry → doc-graph → health/release → scripts → hooks → bin → generators`.
128
+ Verde a cada arquivo. Alternativa rejeitada: renomear tudo e consertar no fim — big-bang, sinal sujo.
129
+
130
+ **D6: `tsc` com `rewriteRelativeImportExtensions` (TS 5.7+).** A fonte importa `./x.ts`; o `tsc`
131
+ reescreve para `./x.js` no emit. É o mecanismo oficial para fonte-`.ts`-roda-nativo + build. Sem
132
+ ele, os imports estáticos não resolveriam nos dois mundos.
133
+
134
+ **D7: `smoke-commands` do release usa o `bin` do package.json.** Hoje ele monta
135
+ `path.join(pkgDir, 'bin', 'forja.mjs')` — quebraria com `dist/bin/forja.js`. Passa a ler o campo
136
+ `bin`. Correção de robustez que a migração torna obrigatória.
137
+
138
+ **D8: Fase 2 e Fase 3 se fundem (achado da implementação).** O plano tratava renomear (Fase 2) e
139
+ buildar (Fase 3) como fases separadas. Não são: `.ts` **não roda em Node < 22.18**, e o
140
+ `engines.node` é `>=20`. No instante em que a fonte vira `.ts`, um pacote publicado **sem `dist/`**
141
+ quebra para quem está em Node 20/21, e o `release:check` (instalação limpa no CI) reprova. Não
142
+ existe estado intermediário *publicável* meio-renomeado. Então a renomeação e o `dist/` andam
143
+ juntos, mantendo o `release:check` verde o tempo todo. Em dev nada muda (Node 26 roda `.ts`); o
144
+ acoplamento é só na fronteira do publicado. Estratégia de menor risco: **provar o pipeline de build
145
+ + runtime duplo primeiro** (a parte nova e arriscada), depois a renomeação leaf-first vira grind
146
+ mecânico sobre trilho provado.
147
+
148
+ **D9: Publicar `dist/` desde já desacopla o risco (achado ao provar o pipeline).** O `tsc` emite um
149
+ `dist/` que espelha a árvore, e `node dist/bin/forja.mjs` roda (o `resolveScript` acha
150
+ `dist/scripts/`). A consequência: se o pacote **sempre embarca `dist/`** — mesmo enquanto a fonte
151
+ ainda é `.mjs` (o build vira uma cópia) — o artefato publicado é sempre JS runnable, e o
152
+ acoplamento de Node-floor do D8 **nunca morde**. Então a ordem certa inverte a intuição: primeiro a
153
+ **infra de release** (build → `dist/`, `package.json` apontando para `dist/`, `prepublishOnly`),
154
+ com a fonte ainda `.mjs` — a plumbing de release provada sobre código que não pode quebrar em
155
+ runtime. **Depois** a renomeação `.mjs → .ts` vira mudança **interna**: a fonte muda, o `dist/`
156
+ regenera como `.js`, e o publicado nunca vê `.ts` cru. O `.ts`-não-roda-em-Node-20 deixa de ser
157
+ risco porque o publicado é sempre `dist/`.
158
+
159
+ D2, D3 e D4 são estruturais → **ADR-0026**, referenciando ADR-0021 (o NFR "roda sem build" e a
160
+ classe "dist mente") e ADR-0024 (o gate que ganha o `build-fresh`).
161
+
162
+ ## 6. Dependências
163
+
164
+ - **Specs**: SPEC-011 (o catálogo de doc-graph já na main — migra junto). Já `done`.
165
+ - **Pacotes npm**: `typescript` como **devDependency** (≥ 5.7, por D6). Zero dependência de runtime
166
+ nova — o publicado segue só com `better-sqlite3`.
167
+ - **Migrações de dado**: nenhuma.
168
+
169
+ ## 7. Rollout
170
+
171
+ - [x] **Fase 0 — on-ramp.** `tsconfig` com `checkJs, strict, noEmit`; `types:check` no registry e
172
+ no CI. Corrigir os erros com os arquivos ainda `.mjs`. Nada renomeado ainda.
173
+ - [x] **Fase 1 — resolver.** Registry sem extensão (na verdade: registry mantém `.mjs` e o
174
+ `resolveScript` faz strip + tenta `.ts/.js/.mjs`), dispatch pelo resolver. Suíte verde.
175
+ - [~] **Fase 2 — renomear leaf-first.** Um módulo por vez (D5), `npm test` verde a cada um.
176
+ **Entregue: todos os 21 módulos `.mjs` do framework** (`lib/core/`, `lib/{audit,governance-report,
177
+ workspace}`, `bin/forja`, todos os `scripts/` incl. hooks). Os typedefs JSDoc viraram `interface`
178
+ real; `allowImportingTsExtensions` no type-check (build reescreve `.ts→.js`). Dois achados
179
+ recorrentes no `.ts` estrito: `[]`→`never[]` (anotação inline) e os casts-comentário
180
+ `/** @type */ (x)` não narram (viram `as`). **Restam**: os 16 `.js` (entries públicos
181
+ `init-project`/`create-memory-nest-kit` + generators + scaffolding), que seguem no checkJs; e o
182
+ `noImplicitAny: true` (endurecimento final — hoje off, ~280 params a tipar).
183
+ - [x] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `package.json` apontando para `dist/`;
184
+ `prepublishOnly` = gate (o gate builda, D4 revisado). Provado por `release:check` (#15).
185
+ - [x] Doc/persona: governança ganha o `build-fresh`; `docs/` e `CONTRIBUTING` ganham o "dev roda
186
+ `.ts`, publicado roda `dist`".
187
+ - [ ] **Prova final**: `release:check` aprova o tarball com `dist/` fresco; reintroduzir um `dist/`
188
+ defasado e confirmar que o `build-fresh` reprova.
189
+
190
+ ## 8. Sinais de fracasso (kill criteria)
191
+
192
+ - **O hook passa a exigir build em dev.** Se em algum ponto o `SessionStart` não rodar sem `dist/`,
193
+ o design falhou o NFR inegociável — pausa e reavalia o runtime duplo antes de seguir.
194
+ - **O resolver de extensão fica ambíguo** (um `.ts` e um `.js` do mesmo nome convivendo em dev).
195
+ Mitigação: `.gitignore` do `dist/` em dev + o `build-fresh` garante que dist não anda solto.
196
+ - **`strict` vira um poço sem fundo.** Se a Fase 0 não estabilizar em tempo razoável, afrouxa para
197
+ `strict` incremental (por arquivo via `// @ts-expect-error` pontual), nunca desligando o gate.
198
+ - **A migração começa a mudar comportamento pra agradar o compilador.** Se um teste precisar mudar
199
+ de semântica, parou de ser migração — isola aquela mudança numa spec própria e segue.
@@ -0,0 +1,119 @@
1
+ # Spec: ts-migration
2
+
3
+ - **ID**: SPEC-012
4
+ - **Status**: approved
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-18
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry)
9
+
10
+ ## 1. Problema
11
+
12
+ O framework tem ~8.500 LOC em 38 arquivos, e **os contratos que o sustentam são convenção, não
13
+ código**. A forma de um check (`{ id, severity, probe, fix }`), o handoff de 7 campos (ADR-0005), o
14
+ `Env` injetável, as entradas do registry — nada disso é verificado até rodar. Nesta sessão, três
15
+ frentes seguidas (ADR-0023/0024/0025) fizeram o mesmo movimento: converter conhecimento que vivia em
16
+ prosa num invariante executável. **A migração para TypeScript é esse movimento aplicado aos
17
+ contratos do próprio código** — drift de contrato deixa de ser surpresa em runtime e vira erro de
18
+ compilação.
19
+
20
+ Já há 9 arquivos com `@typedef` de JSDoc: a tipagem manual já começou, só não é verificada. E o repo
21
+ está a meio caminho de `.js → .mjs` (21 vs 16), então já se mexe na camada de módulos.
22
+
23
+ **A tensão que a migração precisa respeitar.** Um princípio carrega o framework desde o ADR-0021: o
24
+ `tools:doctor` e o hook `SessionStart` rodam **sem build e sem `node_modules`**. Foi isso que tornou
25
+ a morte da memória (ABI) sobrevivível e o hook resiliente. Uma migração ingênua ("compila pra
26
+ `dist/`, roda `dist/`") fritaria esse princípio — e pior, reintroduziria a classe que passamos a
27
+ sessão matando: **um `dist/` que mente sobre o `src/`.**
28
+
29
+ ## 2. Proposta de valor
30
+
31
+ TypeScript de verdade — tipos exportáveis para quem consome o `forjajs` — **sem** perder o "roda sem
32
+ build" que faz o Forja resiliente, e **sem** deixar o artefato compilado divergir da fonte.
33
+
34
+ ## 3. User stories
35
+
36
+ - **Como** quem mantém o framework, **quero** que um `probe` que devolve a forma errada seja **erro
37
+ de compilação**, não bug silencioso, **para que** o contrato dos checks pare de ser convenção.
38
+ - **Como** quem instala `forjajs`, **quero** tipos (`.d.ts`) no pacote, **para que** meu editor
39
+ saiba a forma da API.
40
+ - **Como** agente rodando o hook `SessionStart`, **quero** que ele funcione **sem build e sem
41
+ `node_modules`**, **para que** o diagnóstico sobreviva ao ambiente quebrado (ADR-0021).
42
+ - **Como** quem publica, **quero** que `dist/` desatualizado **reprove** o `release:check`, **para
43
+ que** o pacote publicado nunca minta sobre a fonte.
44
+
45
+ ## 4. Critérios de aceite (Definition of Done)
46
+
47
+ - [ ] AC-1: **Runtime duplo.** Em dev e nos hooks, o Forja roda a fonte `.ts` via type-stripping do
48
+ Node (confirmado: Node 26 executa `.ts` nativo). **Zero build em dev.** O pacote publicado
49
+ embarca `dist/` compilado por `tsc`, para o piso `engines.node >= 20`.
50
+ - [ ] AC-2: **`build-fresh` no catálogo `RELEASE_CHECKS`** (ADR-0024): recompila e compara com o
51
+ `dist/` versionado; se `src/` mudou e `dist/` não, **reprova** com `fix: "npm run build"`. O
52
+ artefato compilado não pode ser publicado defasado.
53
+ - [ ] AC-3: **On-ramp por `checkJs` antes de renomear.** `tsconfig` com `checkJs: true, strict: true,
54
+ noEmit` roda sobre os `.mjs` atuais; os erros de tipo são corrigidos **antes** de qualquer
55
+ renomeação. `types:check` vira **npm script** (como `test`) e step do CI — **fora do registry
56
+ publicado**, porque precisa do devDep `typescript` e seria comando quebrado numa instalação
57
+ `forjajs` (a classe da v1.1.3). *(Correção de rota da Fase 0.)*
58
+ - [ ] AC-4: **Contratos tipados.** `Check`, `Probe`, `Result`, `Env`, `Command` (registry) e o
59
+ handoff de 7 campos (ADR-0005) viram tipos reais, não `@typedef` de convenção.
60
+ - [ ] AC-5: `tsc` emite `.d.ts` no `dist/`; o `package.json` aponta `types`/`exports` para eles.
61
+ - [ ] AC-6: **`release:check` cobre o build.** O gate compila antes de empacotar; `prepublishOnly`
62
+ roda build → gate (ordem correta, sem recursão — o gate não dispara `prepack`, ADR-0024).
63
+ - [ ] AC-7: Suíte verde em cada passo da renomeação (leaf-first). O `node --test` roda sobre `.ts`.
64
+ **É a rede de segurança da migração**: se todos os testes passam sem edição de semântica, a
65
+ renomeação não mudou nada.
66
+ - [ ] AC-8: `tools:doctor`, `release:check` e `spec:check` verdes ao final; instalação limpa do
67
+ tarball funciona (o próprio `release:check` prova).
68
+ - [ ] AC-9: ADR-0026 registrando a decisão (runtime duplo, `build-fresh`, `tsc`).
69
+
70
+ ## 5. Escopo
71
+
72
+ **Dentro**:
73
+ - `tsconfig.json` + `checkJs` on-ramp; migração `.mjs/.js → .ts` leaf-first.
74
+ - `tsc` como toolchain (build → `dist/`, emite `.d.ts`).
75
+ - `build-fresh` em `lib/core/release`; `types:check` no registry; steps no CI.
76
+ - `package.json`: `main`/`types`/`exports`/`bin` → `dist/`; `build`; `prepublishOnly` build→gate.
77
+ - ADR-0026 + ajustes de teste.
78
+
79
+ **Fora** (explícito):
80
+ - **Bumpar o piso de Node.** Fica em `>= 20`; por isso publicamos `dist/` compilado. Dev usa Node
81
+ novo (strip nativo), mas o usuário final não é obrigado.
82
+ - **Geradores como template string.** A fragilidade real (o `@nestjs` falso-positivo, o
83
+ `stripTemplateLiterals`) é separável e ganha spec própria — misturá-la aqui explode o escopo.
84
+ - **Reescrever lógica.** É migração de tipos, não refator de comportamento. Todo teste existente
85
+ passa sem mudança de semântica.
86
+ - **Consolidar o scanner duplicado** (`IMPORT_RE` em `health` e `release`). Vale, mas é refactor —
87
+ e misturá-lo à migração polui o sinal "todos os testes passam sem mudança de semântica", que é a
88
+ rede de segurança da migração inteira (AC-7). Vira fast-follow, spec própria.
89
+ - **esbuild/swc.** `tsc` basta — é framework, não hot path; e precisamos do type-check de qualquer
90
+ forma.
91
+
92
+ ## 6. NFRs / restrições
93
+
94
+ - **"Roda sem build" preservado (inegociável).** O `SessionStart` e o `tools:doctor` nunca podem
95
+ depender de `dist/` nem de `node_modules` para funcionar em dev. É o NFR que mata ou aprova o
96
+ design (AC-1).
97
+ - **`dist/` nunca mente.** Coberto pelo `build-fresh` (AC-2). Sem esse check, a migração reintroduz
98
+ a classe do ADR-0021 — e aí não vale a pena.
99
+ - **Verde contínuo.** Renomeação leaf-first, suíte verde a cada arquivo. Nada de big-bang.
100
+ - **Zero dependência de runtime nova.** `typescript` é `devDependency` (só o build a usa); o pacote
101
+ publicado continua com uma dependência de runtime (`better-sqlite3`).
102
+
103
+ ## 7. Riscos e mitigação
104
+
105
+ | Risco | Prob | Impacto | Mitigação |
106
+ |---|---|---|---|
107
+ | `dist/` publicado defasado da fonte | M | **A** | `build-fresh` no `release:check` (AC-2) — a classe do ADR-0021, fechada |
108
+ | Hook passa a exigir build/`dist` em dev | M | A | Runtime duplo: dev roda `.ts` nativo; `dist/` só no tarball (AC-1). NFR de bloqueio |
109
+ | `bin` aponta pra `dist/` e dev roda sem build | M | M | Dev usa `node bin/forja.ts` / script; `bin` do published → `dist/` |
110
+ | Migração big-bang quebra tudo de uma vez | M | A | `checkJs` primeiro, renomeia leaf-first, verde a cada passo (AC-3, AC-8) |
111
+ | `node --test` não roda `.ts` | B | A | Confirmar cedo; Node novo roda `.ts` de teste nativo (mesmo strip) |
112
+ | `strict` acusa centenas de erros de uma vez | M | M | On-ramp `checkJs` isola os erros antes da renomeação; corrige incremental |
113
+
114
+ ## 8. Métricas de sucesso
115
+
116
+ - Um `probe` com a forma errada **não compila** — o contrato dos checks deixou de ser convenção.
117
+ - `dist/` publicado é sempre igual ao `src/` compilado, provado pelo `build-fresh` a cada release.
118
+ - O `tools:doctor` e o `SessionStart` seguem rodando **sem build** em dev — o NFR inegociável, medido.
119
+ - Consumidores do `forjajs` recebem `.d.ts` — a API deixa de ser adivinhação.
@@ -0,0 +1,110 @@
1
+ # Tasks: ts-migration
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-07-18
7
+
8
+ > Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
9
+
10
+ Ordem das fases do plano §7. As Fases 0 e 1 (T1-T2) são o destravador de menor risco: provam a
11
+ arquitetura **sem** renomear nada. A renomeação (T3) só começa com elas verdes.
12
+
13
+ ---
14
+
15
+ ## T1 — Fase 0: on-ramp `checkJs`
16
+ - **Owner**: Worker
17
+ - **Estimativa**: M
18
+ - **Depende de**: —
19
+ - **Paths**: `tsconfig.json`, `lib/core/registry.mjs`, `package.json`, `.github/workflows/ci.yml`
20
+ - **Escopo**: liga o type-check sobre os `.mjs` atuais. **Nada é renomeado.** Mede o tamanho real
21
+ do problema de tipos antes de comprometer a migração.
22
+ - **Done quando**:
23
+ - [ ] `tsconfig.json`: `allowJs, checkJs, strict, noEmit, module/moduleResolution` nodenext
24
+ - [ ] `typescript` em `devDependencies` (≥ 5.7, por D6)
25
+ - [ ] `types:check` no registry (`tsc --noEmit`) e como step do CI
26
+ - [ ] Os erros de tipo apontados são **corrigidos com os arquivos ainda `.mjs`** (ou anotados com
27
+ `@ts-expect-error` pontual se `strict` for poço sem fundo — kill criteria §8)
28
+ - [ ] `npm test` verde, `types:check` verde
29
+
30
+ ## T2 — Fase 1: resolver extension-agnostic
31
+ - **Owner**: Worker
32
+ - **Estimativa**: M
33
+ - **Depende de**: T1
34
+ - **Paths**: `lib/core/registry.mjs`, `bin/forja.mjs`, `lib/core/release.mjs`, `test/forja-core.test.js`
35
+ - **Escopo**: a **única** mudança de comportamento da migração, isolada e **ainda em `.mjs`**. Se
36
+ algo quebrar aqui, é o resolver — não a renomeação.
37
+ - **Done quando**:
38
+ - [ ] Registry: `node:` sem extensão (`scripts/tools-doctor`, não `.mjs`) — D2
39
+ - [ ] Dispatch (`bin/forja.mjs`): resolve `cmd.node` tentando `.ts → .js → .mjs`, a 1ª que existe
40
+ - [ ] `registry-scripts` (release.mjs) resolve extension-agnostic também — hoje casa a extensão
41
+ - [ ] `smoke-commands` (release.mjs) usa o campo `bin` do package.json, não path fixo — D7
42
+ - [ ] Teste: um comando roda com o registry sem extensão; `test/forja-core.test.js` verde
43
+ - [ ] `npm test` + `tools:doctor` + `release:check` verdes
44
+
45
+ ## T3 — Fase 2: renomear leaf-first
46
+ - **Owner**: Worker
47
+ - **Estimativa**: G
48
+ - **Depende de**: T2
49
+ - **Paths**: `lib/`, `scripts/`, `bin/`, `.claude/settings.json`
50
+ - **Escopo**: renomear `.mjs/.js → .ts` na ordem de dependência, **verde a cada arquivo**. Migração
51
+ de tipos, não de lógica: nenhum teste muda de semântica (a rede de segurança, AC-7).
52
+ - **Ordem** (D5): `workspace → checks → registry → doc-graph → health → release → scripts/* → hooks
53
+ → bin/forja → generators`.
54
+ - **Done quando**:
55
+ - [ ] Cada módulo renomeado com imports `./x.ts` (D6); `npm test` verde após cada um
56
+ - [ ] `Check`/`Probe`/`Result`/`Env`/`Command` e o handoff de 7 campos viram tipos reais (AC-4)
57
+ - [ ] Hooks do `.claude/settings.json` apontam para `.ts` (dev roda nativo)
58
+ - [ ] Geradores: assinatura tipada; o conteúdo template-string permanece string
59
+ - [ ] Ao final: `npm test`, `tools:doctor`, `spec:check` verdes; nenhum `.mjs`/`.js` de código
60
+ remanescente em `lib`/`scripts`/`bin`
61
+
62
+ ## T4 — Fase 3: build + dist + build-fresh
63
+ - **Owner**: Worker
64
+ - **Estimativa**: M
65
+ - **Depende de**: T3
66
+ - **Paths**: `tsconfig.json`, `package.json`, `lib/core/release.ts`, `.gitignore`, CI
67
+ - **Done quando**:
68
+ - [ ] `tsconfig`: `outDir: dist`, `rootDir: .`, `declaration: true`, `rewriteRelativeImportExtensions`
69
+ - [ ] `scripts.build` = `tsc`; `dist/` espelha a árvore (`dist/bin`, `dist/lib`, `dist/scripts`)
70
+ - [ ] `package.json`: `bin`/`main`/`types`/`exports` → `dist/`; `files[]` troca código por `dist/`
71
+ - [ ] **`build-fresh`** no `RELEASE_CHECKS` (D4): recompila num temp, faz diff com `dist/` commitado,
72
+ reprova defasado com `fix: npm run build`
73
+ - [ ] `prepublishOnly` = `npm run build && release:check -- --publish` (ordem, sem recursão — D7/ADR-0024)
74
+ - [ ] Decidir e registrar: `dist/` versionado (commitado) vs gerado no publish. Se versionado, o
75
+ `build-fresh` o guarda; se gerado, o `prepublishOnly` o produz. **Um ou outro, não os dois**
76
+ - [ ] `release:check --publish` aprova; `npm publish --dry-run` monta o tarball com `dist/`
77
+
78
+ ## T5 — ADR-0026 e docs
79
+ - **Owner**: SDD Architect + Worker
80
+ - **Estimativa**: P
81
+ - **Depende de**: T2, T4
82
+ - **Paths**: `memory/90-decisions/0026-*.md`, `docs/`, `CONTRIBUTING.md`, `CLAUDE.md`
83
+ - **Done quando**:
84
+ - [ ] ADR-0026 registra D2 (registry sem extensão), D3 (runtime duplo) e D4 (`build-fresh`);
85
+ referencia ADR-0021 (NFR "roda sem build" + classe "dist mente") e ADR-0024
86
+ - [ ] `CONTRIBUTING`/`docs`: "dev roda `.ts` nativo (Node novo); publicado roda `dist/`"
87
+ - [ ] `CLAUDE.md`: comando de dev atualizado se mudou (`node bin/forja.ts`)
88
+
89
+ ## T6 — Prova final (Governance)
90
+ - **Owner**: Governance
91
+ - **Estimativa**: P
92
+ - **Depende de**: T4, T5
93
+ - **Done quando**:
94
+ - [ ] `release:check --publish` aprova o tarball com `dist/` fresco
95
+ - [ ] **Reintroduzir um `dist/` defasado** (editar `src`, não rebuildar) e confirmar que o
96
+ `build-fresh` **reprova** — o gate que nunca viu a falha que promete pegar não está testado
97
+ - [ ] O hook `SessionStart` roda **sem `dist/` e sem build** em dev (o NFR inegociável, medido)
98
+ - [ ] `npm test`, `project:check`, `tools:doctor`, `gitleaks` verdes; spec → `done`
99
+
100
+ ---
101
+
102
+ ## Nota de sequência
103
+ As Fases 0-1 (T1-T2) podem ir num PR próprio — provam a arquitetura (checkJs + resolver) sem tocar
104
+ em extensão de arquivo, e são revertíveis com baixo custo. A renomeação (T3) é o commit grande; vale
105
+ PR separado. T4 (build/publish) é o de maior risco de release — vai por último, com o `build-fresh`
106
+ como rede.
107
+
108
+ ## Handoffs entre agentes
109
+ Worker (T1-T4), SDD Architect (T5), Governance (T6). Handoff a cada fronteira via `forja agent:route`
110
+ — 7 campos (ADR-0005).