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.
- package/.claude/settings.json +7 -7
- package/CHANGELOG.md +62 -0
- package/README.en.md +33 -5
- package/README.md +35 -4
- package/boilerplates/06-clean-arch/README.md +48 -0
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
- package/boilerplates/06-clean-arch/backend/package.json +43 -0
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
- package/boilerplates/README.md +20 -0
- package/dist/bin/create-memory-nest-kit.d.ts +2 -0
- package/dist/bin/create-memory-nest-kit.js +110 -0
- package/dist/bin/forja.d.ts +13 -0
- package/dist/bin/forja.js +136 -0
- package/dist/bin/init-project.d.ts +2 -0
- package/dist/bin/init-project.js +516 -0
- package/dist/lib/audit.d.ts +67 -0
- package/dist/lib/audit.js +143 -0
- package/dist/lib/context-builder.d.ts +58 -0
- package/dist/lib/context-builder.js +233 -0
- package/dist/lib/core/checks.d.ts +91 -0
- package/dist/lib/core/checks.js +119 -0
- package/dist/lib/core/doc-graph.d.ts +60 -0
- package/dist/lib/core/doc-graph.js +235 -0
- package/dist/lib/core/health.d.ts +103 -0
- package/dist/lib/core/health.js +538 -0
- package/dist/lib/core/registry.d.ts +296 -0
- package/dist/lib/core/registry.js +317 -0
- package/dist/lib/core/release.d.ts +334 -0
- package/dist/lib/core/release.js +465 -0
- package/dist/lib/generators/memory-generator.d.ts +83 -0
- package/{lib → dist/lib}/generators/memory-generator.js +107 -178
- package/dist/lib/generators/nest-generator.d.ts +15 -0
- package/{lib → dist/lib}/generators/nest-generator.js +47 -71
- package/dist/lib/generators/readme-generator.d.ts +15 -0
- package/{lib → dist/lib}/generators/readme-generator.js +9 -14
- package/dist/lib/governance-report.d.ts +49 -0
- package/dist/lib/governance-report.js +170 -0
- package/dist/lib/templates/harness/code-intel.d.mts +2 -0
- package/dist/lib/templates/harness/code-intel.mjs +126 -0
- package/dist/lib/utils/file-helpers.d.ts +9 -0
- package/dist/lib/utils/file-helpers.js +34 -0
- package/dist/lib/validators/structure-validator.d.ts +48 -0
- package/dist/lib/validators/structure-validator.js +232 -0
- package/dist/lib/workspace.d.ts +40 -0
- package/dist/lib/workspace.js +174 -0
- package/dist/scripts/agent-harness.d.ts +2 -0
- package/dist/scripts/agent-harness.js +556 -0
- package/dist/scripts/agent-router.d.ts +30 -0
- package/dist/scripts/agent-router.js +208 -0
- package/dist/scripts/audit-query.d.ts +2 -0
- package/dist/scripts/audit-query.js +43 -0
- package/dist/scripts/audit-sync.d.ts +2 -0
- package/dist/scripts/audit-sync.js +19 -0
- package/dist/scripts/build-smart-context.d.ts +1 -0
- package/dist/scripts/build-smart-context.js +75 -0
- package/dist/scripts/check-standards.d.ts +1 -0
- package/dist/scripts/check-standards.js +87 -0
- package/dist/scripts/compress-memory.d.ts +16 -0
- package/dist/scripts/compress-memory.js +157 -0
- package/dist/scripts/compress-project-memory.d.ts +1 -0
- package/dist/scripts/compress-project-memory.js +48 -0
- package/dist/scripts/context-ops.d.ts +2 -0
- package/dist/scripts/context-ops.js +464 -0
- package/dist/scripts/dev.d.ts +96 -0
- package/dist/scripts/dev.js +312 -0
- package/dist/scripts/extract-global-knowledge.d.ts +1 -0
- package/dist/scripts/extract-global-knowledge.js +43 -0
- package/dist/scripts/generate-dashboard.d.ts +1 -0
- package/dist/scripts/generate-dashboard.js +48 -0
- package/dist/scripts/governance-dashboard.d.ts +2 -0
- package/dist/scripts/governance-dashboard.js +36 -0
- package/dist/scripts/hook-guard-paths.d.ts +17 -0
- package/dist/scripts/hook-guard-paths.js +68 -0
- package/dist/scripts/hook-post-edit.d.ts +20 -0
- package/dist/scripts/hook-post-edit.js +70 -0
- package/dist/scripts/hook-session-start.d.ts +17 -0
- package/dist/scripts/hook-session-start.js +108 -0
- package/dist/scripts/hook-user-prompt.d.ts +22 -0
- package/dist/scripts/hook-user-prompt.js +193 -0
- package/dist/scripts/memory-schema.d.ts +6 -0
- package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
- package/dist/scripts/query-universal-memory.d.ts +1 -0
- package/dist/scripts/query-universal-memory.js +44 -0
- package/dist/scripts/release-check.d.ts +14 -0
- package/dist/scripts/release-check.js +48 -0
- package/dist/scripts/spec-cli.d.ts +29 -0
- package/dist/scripts/spec-cli.js +261 -0
- package/dist/scripts/sprint-manager.d.ts +1 -0
- package/dist/scripts/sprint-manager.js +187 -0
- package/dist/scripts/sync-universal-memory.d.ts +1 -0
- package/dist/scripts/sync-universal-memory.js +277 -0
- package/dist/scripts/token-benchmark.d.ts +20 -0
- package/dist/scripts/token-benchmark.js +181 -0
- package/dist/scripts/tools-doctor.d.ts +20 -0
- package/dist/scripts/tools-doctor.js +120 -0
- package/docs/personas/architect/README.md +4 -4
- package/docs/personas/developer/README.md +3 -3
- package/docs/personas/qa/README.md +3 -3
- package/docs/quick-reference.md +9 -9
- package/docs/structure.md +3 -3
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
- package/memory/90-decisions/0028-governanca-visivel.md +84 -0
- package/package.json +60 -56
- package/specs/clean-arch-boilerplate/plan.md +137 -0
- package/specs/clean-arch-boilerplate/spec.md +121 -0
- package/specs/clean-arch-boilerplate/tasks.md +70 -0
- package/specs/coerencia-do-sistema/plan.md +155 -0
- package/specs/coerencia-do-sistema/spec.md +15 -14
- package/specs/coerencia-do-sistema/tasks.md +115 -0
- package/specs/governanca-visivel/plan.md +122 -0
- package/specs/governanca-visivel/spec.md +112 -0
- package/specs/governanca-visivel/tasks.md +60 -0
- package/specs/ts-migration/plan.md +199 -0
- package/specs/ts-migration/spec.md +119 -0
- package/specs/ts-migration/tasks.md +110 -0
- package/bin/create-memory-nest-kit.js +0 -125
- package/bin/forja.mjs +0 -143
- package/bin/init-project.js +0 -612
- package/lib/context-builder.js +0 -257
- package/lib/core/checks.mjs +0 -138
- package/lib/core/health.mjs +0 -475
- package/lib/core/registry.mjs +0 -289
- package/lib/core/release.mjs +0 -452
- package/lib/templates/harness/code-intel.mjs +0 -119
- package/lib/templates/harness/mcp.json +0 -10
- package/lib/utils/file-helpers.js +0 -40
- package/lib/validators/structure-validator.js +0 -253
- package/lib/workspace.mjs +0 -213
- package/scripts/agent-harness.mjs +0 -578
- package/scripts/agent-router.mjs +0 -189
- package/scripts/build-smart-context.js +0 -87
- package/scripts/check-standards.js +0 -98
- package/scripts/compress-memory.mjs +0 -198
- package/scripts/compress-project-memory.js +0 -58
- package/scripts/context-ops.mjs +0 -463
- package/scripts/dev.mjs +0 -349
- package/scripts/extract-global-knowledge.js +0 -52
- package/scripts/generate-dashboard.js +0 -59
- package/scripts/hook-guard-paths.mjs +0 -75
- package/scripts/hook-post-edit.mjs +0 -79
- package/scripts/hook-session-start.mjs +0 -104
- package/scripts/hook-user-prompt.mjs +0 -185
- package/scripts/pre-commit.sh +0 -102
- package/scripts/query-universal-memory.js +0 -50
- package/scripts/release-check.mjs +0 -56
- package/scripts/spec-cli.mjs +0 -260
- package/scripts/sprint-manager.js +0 -200
- package/scripts/sync-universal-memory.js +0 -286
- package/scripts/token-benchmark.mjs +0 -203
- 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).
|