forjajs 1.3.1 → 1.5.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 (66) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.en.md +1 -0
  3. package/README.md +10 -4
  4. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  5. package/dist/bin/create-memory-nest-kit.d.ts +11 -0
  6. package/dist/bin/create-memory-nest-kit.js +5 -5
  7. package/dist/bin/forja.js +1 -1
  8. package/dist/bin/init-project.d.ts +12 -0
  9. package/dist/bin/init-project.js +2 -2
  10. package/dist/lib/code-context.d.ts +41 -0
  11. package/dist/lib/code-context.js +108 -0
  12. package/dist/lib/context-builder.d.ts +15 -5
  13. package/dist/lib/context-builder.js +5 -0
  14. package/dist/lib/core/checks.d.ts +3 -3
  15. package/dist/lib/core/doc-graph.d.ts +13 -0
  16. package/dist/lib/core/doc-graph.js +48 -1
  17. package/dist/lib/core/health.d.ts +3 -32
  18. package/dist/lib/core/health.js +29 -15
  19. package/dist/lib/core/project-smoke.d.ts +46 -0
  20. package/dist/lib/core/project-smoke.js +248 -0
  21. package/dist/lib/core/registry.d.ts +25 -0
  22. package/dist/lib/core/registry.js +37 -12
  23. package/dist/lib/core/release.d.ts +27 -14
  24. package/dist/lib/core/release.js +0 -8
  25. package/dist/lib/generators/memory-generator.d.ts +11 -6
  26. package/dist/lib/generators/memory-generator.js +45 -1
  27. package/dist/lib/generators/nest-generator.d.ts +8 -4
  28. package/dist/lib/generators/nest-generator.js +1 -1
  29. package/dist/lib/generators/readme-generator.d.ts +7 -4
  30. package/dist/lib/generators/readme-generator.js +2 -1
  31. package/dist/lib/governance-report.d.ts +1 -1
  32. package/dist/lib/memory-audit.d.ts +31 -0
  33. package/dist/lib/memory-audit.js +81 -0
  34. package/dist/lib/project-upgrade.d.ts +28 -0
  35. package/dist/lib/project-upgrade.js +74 -0
  36. package/dist/lib/utils/file-helpers.d.ts +10 -6
  37. package/dist/lib/validators/structure-validator.d.ts +49 -27
  38. package/dist/scripts/code-context.d.ts +12 -0
  39. package/dist/scripts/code-context.js +73 -0
  40. package/dist/scripts/dev.d.ts +2 -2
  41. package/dist/scripts/dev.js +1 -1
  42. package/dist/scripts/memory-audit.d.ts +11 -0
  43. package/dist/scripts/memory-audit.js +49 -0
  44. package/dist/scripts/project-smoke.d.ts +14 -0
  45. package/dist/scripts/project-smoke.js +44 -0
  46. package/dist/scripts/project-upgrade.d.ts +11 -0
  47. package/dist/scripts/project-upgrade.js +61 -0
  48. package/dist/scripts/query-universal-memory.js +1 -1
  49. package/dist/scripts/sprint-manager.js +1 -1
  50. package/dist/scripts/token-benchmark.js +1 -1
  51. package/dist/scripts/token-economy.d.ts +20 -0
  52. package/dist/scripts/token-economy.js +140 -0
  53. package/memory/90-decisions/0025-coerencia-da-documentacao.md +4 -0
  54. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  55. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  56. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  57. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  58. package/package.json +1 -1
  59. package/specs/code-context/spec.md +56 -0
  60. package/specs/memory-audit/spec.md +54 -0
  61. package/specs/project-smoke/spec.md +96 -0
  62. package/specs/project-upgrade/spec.md +58 -0
  63. package/specs/ts-migration/plan.md +9 -8
  64. package/specs/ts-migration/spec.md +1 -1
  65. package/dist/lib/templates/harness/code-intel.d.mts +0 -2
  66. package/dist/lib/templates/harness/code-intel.mjs +0 -126
@@ -0,0 +1,59 @@
1
+ # ADR-0029: Gate do projeto gerado (`project:smoke`)
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-19
5
+ - **Autor(es)**: apk
6
+ - **Tags**: quality, gates, generators, sdd
7
+
8
+ ## Contexto
9
+
10
+ O `release:check` (ADR-0024) guarda uma fronteira com evidência: *o repositório mente sobre o
11
+ pacote*. Existe a **mesma classe de bug um nível acima, e estava descoberta**: nada provava que
12
+ `forja project:new` gera um projeto coerente.
13
+
14
+ O gerador escreve a partir de templates — `{{FEATURE}}`, blocos de `scripts`, configs. Cada
15
+ substituição é uma chance de mentira silenciosa: um placeholder que vaza, um `package.json` que não
16
+ parseia, uma estrutura incompleta. O `structure-validator` já sabia *validar* estrutura, mas nada
17
+ *executava* o gerador de ponta a ponta e reprovava. Conhecimento não faltava; execução, sim — o
18
+ mesmo diagnóstico da SPEC-010.
19
+
20
+ ## Decisão
21
+
22
+ Criar `project:smoke` (SPEC-015): um gate que **gera um projeto num diretório temporário isolado e o
23
+ inspeciona**, reusando o runner de `checks.ts` — a mesma máquina de probes do doctor e do release.
24
+
25
+ Dois tiers, espelhando o `release:check`:
26
+
27
+ - **Barato (default, roda no CI)**: sem rede. Prova que nenhum placeholder `{{...}}` vazou, que todo
28
+ `package.json` parseia, e que a estrutura passa no `validateProjectStructure`.
29
+ - **`--full` (opt-in, pré-release)**: `npm install` + `npm run build` no backend gerado, num ambiente
30
+ isolado (sem `NODE_PATH`/`npm_config_*` herdados). É o clean-install do release, na saída do gerador.
31
+
32
+ O gerador não sabe que está sendo auditado — o gate só o observa via spawn do entry real
33
+ (`create-memory-nest-kit`), como o release empacota o tarball real.
34
+
35
+ ## Alternativas consideradas
36
+
37
+ - **Importar as funções do gerador e chamá-las direto** — rejeitada: testaria as funções, não o
38
+ entry point que o usuário roda. O spawn do orquestrador pega bugs de orquestração também.
39
+ - **Rodar sempre o tier pesado (install+build)** — rejeitada: `npm install` de um NestJS é lento e
40
+ usa rede; um gate que reprova por flakiness de registry se contorna (a lição do CI na SPEC-009).
41
+ Por isso o tier barato é o gate de CI e o `--full` é opt-in.
42
+ - **Pôr no `tools:doctor`** — rejeitada: o doctor é o raio-x barato do núcleo; gerar um projeto tem
43
+ custo. É gate próprio, como o `release:check`.
44
+
45
+ ## Consequências
46
+
47
+ **Positivas**:
48
+ - A última fronteira do gerador que vivia por disciplina passa a viver no harness.
49
+ - Reuso total: runner de `checks.ts` + `structure-validator` existente — uma máquina, não duas.
50
+ - O tier barato é rápido o bastante para o CI; o `--full` dá a prova forte antes de publicar.
51
+
52
+ **Negativas / Trade-offs**:
53
+ - Cobre o caminho *default* do gerador; a matriz de boilerplates de stack fica para iteração futura.
54
+ - O `--full` depende de rede — mitigado por ser opt-in, fora do gate de CI.
55
+
56
+ ## Rastreamento
57
+ - Implementação: `lib/core/project-smoke.ts`, `scripts/project-smoke.ts`, `test/project-smoke.test.js`
58
+ - Spec: `specs/project-smoke/spec.md` (SPEC-015)
59
+ - ADRs relacionadas: ADR-0024 (gate do tarball — o padrão), ADR-0023 (doctor), ADR-0020 (core/registry)
@@ -0,0 +1,53 @@
1
+ # ADR-0030: O projeto gerado herda os gates do framework
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-19
5
+ - **Autor(es)**: apk
6
+ - **Tags**: generators, gates, memory, governance
7
+
8
+ ## Contexto
9
+
10
+ O framework construiu uma família de invariantes-que-rodam: `project:smoke`, `memory:audit`,
11
+ `adr-refs`, o `release:check`. Mas todos guardam o **framework**. O **projeto do usuário** não
12
+ herdava nenhum — gerava com mapas de memória honestos e, com o tempo, um rename sem atualizar o
13
+ `context.md` fazia o mapa mentir, silenciosamente, sem nada avisar. A economia de token da memória
14
+ (ADR-0009) se degrada, e ninguém percebe. É a mesma classe "vive por disciplina" que o ADR-0021
15
+ combate — só que na máquina do usuário, onde o framework não alcança por gate próprio.
16
+
17
+ ## Decisão
18
+
19
+ O gerador **emite um gate self-contained no projeto**: `scripts/check-memory-maps.mjs`, uma versão
20
+ sem dependências do `memory:audit` (coerência mapa↔código: mapa não cita código morto, módulo sem
21
+ mapa avisa). Zero acoplamento ao `forjajs` — Node puro, roda em qualquer CI com `node
22
+ scripts/check-memory-maps.mjs`. O `project:smoke` do framework passa a **verificar que o gate está
23
+ presente** no projeto gerado, fechando o laço: o framework prova que propaga o invariante.
24
+
25
+ A filosofia de invariantes deixa de ser só do mantenedor do Forja e passa a viajar com cada projeto.
26
+
27
+ ## Alternativas consideradas
28
+
29
+ - **Projeto depende de `forjajs` e roda `npx forja memory:audit`** — rejeitada: acopla um app NestJS
30
+ ao framework inteiro (e ao `better-sqlite3`), pesado para um gate que é Node puro.
31
+ - **Emitir um workflow `.github/` pronto** — rejeitada (por ora): imporia GitHub Actions a todo
32
+ projeto (alguns usam GitLab/outros). O script é portável; o usuário o pluga no CI que usa. Um
33
+ workflow opcional pode vir em follow-up.
34
+ - **Não propagar (deixar como doc)** — rejeitada: é exatamente o "regra que depende de memória" que
35
+ o framework existe para eliminar.
36
+
37
+ ## Consequências
38
+
39
+ **Positivas**:
40
+ - O invariante mapa↔código viaja com o projeto; a economia de token da memória fica protegida na
41
+ máquina do usuário, não só na do framework.
42
+ - Self-contained: sem dependência nova no projeto gerado.
43
+ - `project:smoke` prova a propagação (o gate está presente no output).
44
+
45
+ **Negativas / Trade-offs**:
46
+ - Duplicação de lógica (o `check-memory-maps.mjs` do projeto espelha o `lib/memory-audit.ts`). É o
47
+ preço de projetos independentes; a lógica é pequena e estável.
48
+ - O gate não roda sozinho até o usuário plugá-lo no CI — o script está presente, o wiring é dele.
49
+
50
+ ## Rastreamento
51
+ - Implementação: `lib/generators/memory-generator.ts` (emite o script),
52
+ `lib/core/project-smoke.ts` (check `gate-inherited`)
53
+ - ADRs relacionadas: ADR-0009 (economia de token), ADR-0021 (invariante > disciplina), ADR-0029 (project:smoke), SPEC-017 (memory:audit)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.3.1",
3
+ "version": "1.5.0",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -0,0 +1,56 @@
1
+ # Spec: code-context
2
+
3
+ - **ID**: SPEC-016
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0009 (economia de token), ADR-0003 (smart-context), ADR-0020 (core/registry)
7
+
8
+ ## 1. Problema
9
+
10
+ O `token:economy` mediu a economia real do framework: o `context.md` de um domínio (o mapa) faz o
11
+ contexto mínimo custar **−61%** vs varrer a fatia no frio. Mas essa economia era **potencial, não
12
+ entregue**: o mapa é só um arquivo que alguém precisa lembrar de ler, e ainda montar o contexto na
13
+ mão (mapa + os arquivos certos). A economia medida não vira lever até virar comando.
14
+
15
+ ## 2. Proposta de valor
16
+
17
+ Um comando entrega o **pacote de contexto mínimo** de um domínio, pronto para colar, com o custo em
18
+ token à mostra: o −61% deixa de ser medição e vira ferramenta do dia a dia.
19
+
20
+ ## 3. User stories
21
+
22
+ - **Como** agente que vai mexer num domínio, **quero** um comando que me dê o mapa + (sob demanda) o
23
+ código da fatia, **para que** eu não pague o custo de explorar a árvore no frio.
24
+ - **Como** dev, **quero** ver o custo em token do pacote, **para que** a economia seja visível e eu
25
+ escolha entre "só o mapa" e "mapa + código".
26
+
27
+ ## 4. Critérios de aceite (Definition of Done)
28
+
29
+ - [x] AC-1: `forja code:context <domínio>` imprime o `context.md` do domínio (o mapa), pronto para
30
+ colar, com os tokens do mapa no rodapé.
31
+ - [x] AC-2: `--code` anexa os `.ts` da fatia (`backend/src/modules/<domínio>/`) e soma os tokens.
32
+ - [x] AC-3: `--project <path>` aponta para outro projeto (default: `cwd`). Sem domínio, lista os
33
+ disponíveis; domínio inexistente reprova com a lista.
34
+ - [x] AC-4: A lógica de montagem é pura e testável (`lib/code-context.ts`), com fixtures — sem tocar
35
+ o disco real.
36
+
37
+ ## 5. Escopo
38
+
39
+ **Dentro**: o mapa + o código da fatia, com custo em token. Composição com `code:impact` (blast
40
+ radius) documentada, não embutida.
41
+
42
+ **Fora** (explícito):
43
+ - Reindexar/consultar a memória via FTS5 — isso é `context:smart`/`query:universal`; este comando lê
44
+ o mapa direto do disco do projeto.
45
+ - Chamar codegraph internamente — o blast radius fica em `code:impact`, componível (`&&`).
46
+ - Editar ou resumir o código — entrega cru; resumir é decisão do agente que consome.
47
+
48
+ ## 6. NFRs / restrições
49
+
50
+ - **Compatibilidade**: comando novo; não muda nada existente.
51
+ - **Sem dependência de rede ou de codegraph** no caminho principal (mapa + código são leitura de disco).
52
+
53
+ ## 7. Métricas de sucesso
54
+
55
+ O pacote "só o mapa" de um domínio típico custa uma fração do "mapa + código" — e ambos, uma fração
56
+ de ler a fatia no frio. O `token:economy` já mostra o −61%; este comando o torna acionável.
@@ -0,0 +1,54 @@
1
+ # Spec: memory-audit
2
+
3
+ - **ID**: SPEC-017
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0009 (economia de token), ADR-0025 (coerência da doc — a mesma classe), ADR-0020 (core/registry)
7
+
8
+ ## 1. Problema
9
+
10
+ A economia de token do Forja é o `context.md` como mapa do domínio (`token:economy` mede −61%). Mas
11
+ o mapa cita paths de código — "a regra mora em `domain/order.entity.ts`", "teste em
12
+ `test/orders/place-order.spec.ts`". Quando o código é renomeado ou movido e o mapa não acompanha, o
13
+ mapa passa a **mentir com confiança**: um agente lê o lugar errado, paga o custo, e chega à conclusão
14
+ errada. Um mapa desatualizado é *pior* que mapa nenhum. Nada verifica isso hoje — vive de disciplina.
15
+
16
+ ## 2. Proposta de valor
17
+
18
+ O mapa deixa de poder mentir em silêncio: **todo path de código citado num `context.md` é conferido**,
19
+ e uma referência pendurada reprova. É o `adr-refs` (ADR-0025) aplicado aos mapas de memória.
20
+
21
+ ## 3. User stories
22
+
23
+ - **Como** dev de um projeto gerado, **quero** um comando que reprove quando um mapa aponta para
24
+ arquivo que não existe mais, **para que** a economia de token da memória não se volte contra mim.
25
+ - **Como** CI de um projeto, **quero** rodar isso como gate, **para que** um rename sem atualizar o
26
+ mapa não passe batido.
27
+
28
+ ## 4. Critérios de aceite (Definition of Done)
29
+
30
+ - [x] AC-1: `forja memory:audit` varre `memory/30-domains/*/context.md`, extrai os paths de código
31
+ citados (entre crases, com `/` e terminando em `.ts`) e reprova (exit ≠ 0) se algum não existe.
32
+ - [x] AC-2: Resolve o path em múltiplas bases (relativo ao módulo, ao `backend/`, à raiz) — um mesmo
33
+ mapa cita as duas convenções (`domain/x.ts` e `test/x.spec.ts`).
34
+ - [x] AC-3: `--project <path>` aponta para outro projeto (default: `cwd`).
35
+ - [x] AC-4: Lógica pura e testável (`lib/memory-audit.ts`); reusa `domainsOf` de `code-context`.
36
+
37
+ ## 5. Escopo
38
+
39
+ **Dentro**: conferir paths de código `.ts` citados nos mapas de domínio.
40
+
41
+ **Fora** (explícito):
42
+ - Validar que o *conteúdo* do mapa (a linguagem ubíqua, as regras) ainda bate com o código — isso é
43
+ julgamento, não path. Este gate pega o path pendurado, que é o sinal barato e objetivo.
44
+ - Rodar dentro do `project:smoke` — lá o projeto é recém-gerado, o mapa é fresco por definição. A
45
+ divergência mapa↔código acontece com o tempo, num projeto existente; é aí que este comando roda.
46
+
47
+ ## 6. NFRs / restrições
48
+
49
+ - **Compatibilidade**: comando novo; não muda nada. Sem rede, sem codegraph — leitura de disco.
50
+
51
+ ## 7. Métricas de sucesso
52
+
53
+ Pelo menos um rename sem atualização de mapa pego antes do merge num projeto real — a prova de que a
54
+ fronteira estava descoberta.
@@ -0,0 +1,96 @@
1
+ # Spec: project-smoke
2
+
3
+ - **ID**: SPEC-015
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-19
7
+ - **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-release-gate.md) (gate do tarball — o padrão), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (doctor), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry)
8
+
9
+ ## 1. Problema
10
+
11
+ O `release:check` guarda uma fronteira: **o repositório mente sobre o pacote**. Existe a *mesma
12
+ classe de bug um nível acima*, e ela está **descoberta**: nada prova que `forja project:new` gera um
13
+ projeto que de fato **é coerente e roda**.
14
+
15
+ O gerador escreve arquivos a partir de templates (`{{FEATURE}}`, `{{ID}}`, blocos de `scripts`, configs
16
+ multi-IA). Cada um desses é uma oportunidade de mentira silenciosa:
17
+
18
+ - um placeholder `{{...}}` que vaza para o output porque o gerador esqueceu de substituir;
19
+ - um `package.json` gerado que não é JSON válido, ou sem os scripts que os docs prometem;
20
+ - a estrutura de memória incompleta (falta um diretório crítico que o resto assume);
21
+ - no limite: o projeto gerado simplesmente **não buildar**.
22
+
23
+ Hoje só descobrimos isso quando um usuário gera um projeto e ele quebra — exatamente o modo de falha
24
+ que o `release:check` existe para eliminar, só que na saída do gerador em vez do tarball. **Não é
25
+ conhecimento que falta** (o `structure-validator` já sabe validar estrutura). **É execução**: nada
26
+ roda o gerador de ponta a ponta e reprova.
27
+
28
+ ## 2. Proposta de valor
29
+
30
+ Gerar um projeto deixa de ser um ato de fé: **nenhuma mudança no gerador passa sem prova de que o
31
+ projeto gerado é coerente**, e a prova é gerada pelo harness — não pela lembrança de quem tocou no
32
+ template.
33
+
34
+ ## 3. User stories
35
+
36
+ - **Como** quem mantém o gerador, **quero** que uma mudança que quebra o output **reprove no CI**,
37
+ **para que** eu não descubra pela issue de um usuário.
38
+ - **Como** usuário do `forjajs`, **quero** que `forja project:new` me entregue um projeto sem
39
+ placeholders vazados nem `package.json` quebrado, **para que** eu não perca a primeira hora
40
+ depurando o scaffold em vez do meu produto.
41
+ - **Como** governança, **quero** a evidência de que o projeto gerado buildar **no log do CI**,
42
+ **para que** "o gerador funciona" seja um artefato verificável e não uma afirmação.
43
+
44
+ ## 4. Critérios de aceite (Definition of Done)
45
+
46
+ - [ ] AC-1: Existe `forja project:smoke` (entrada no registry, ADR-0020) que **gera um projeto num
47
+ diretório temporário isolado** e reprova com exit ≠ 0 em qualquer falha abaixo. Limpa o tmp
48
+ sempre, inclusive quando um check lança.
49
+ - [ ] AC-2: **Zero placeholder vazado.** Nenhum arquivo gerado contém `{{...}}` não substituído.
50
+ É o bug mais barato de introduzir e o mais visível para o usuário.
51
+ - [ ] AC-3: **Todo `package.json` gerado é JSON válido** e contém os scripts que o gerador anuncia.
52
+ - [ ] AC-4: **Estrutura íntegra.** `validateProjectStructure` do projeto gerado passa (reusa o
53
+ `structure-validator` existente — uma máquina, não duas).
54
+ - [ ] AC-5: **Modo `--full` (opt-in): o projeto buildar de verdade.** `npm install` + `npm run build`
55
+ no backend gerado, num ambiente isolado. É o análogo do clean-install do `release:check`:
56
+ caro, roda antes de release, não a cada commit.
57
+ - [ ] AC-6: **Reusa o runner de `checks.mjs`.** O `project:smoke` é um catálogo novo consumido pelo
58
+ mesmo runner do doctor/release — mesma máquina de probes, `severity`, cascata por `dependsOn`.
59
+ - [ ] AC-7: O gate roda no CI (tier barato) e o `tools:doctor` **não** o executa (custo alto; é um
60
+ gate próprio, como o `release:check`).
61
+
62
+ ## 5. Escopo
63
+
64
+ **Dentro**:
65
+ - Comando `project:smoke` + catálogo `lib/core/project-smoke.mjs`.
66
+ - Isolamento em tmp + limpeza garantida (padrão do `withCleanInstall`).
67
+ - Tier barato (placeholders, JSON, estrutura) no CI; tier `--full` (install+build) opt-in.
68
+
69
+ **Fora** (explícito):
70
+ - Rodar a suíte de testes do projeto gerado (`npm test`) — fica para uma iteração futura; build já
71
+ prova que os imports resolvem.
72
+ - Validar os boilerplates de stack individualmente (`api-rest`, `saas`, …) — este gate cobre o
73
+ caminho default do gerador; a matriz de stacks é escopo à parte.
74
+ - Publicar o projeto gerado em qualquer lugar.
75
+
76
+ ## 6. NFRs / restrições
77
+
78
+ - **Compatibilidade**: não muda o comportamento de `init-project`/`create-memory-nest-kit` — só os
79
+ observa. O gerador não sabe que está sendo auditado.
80
+ - **Isolamento**: o tier `--full` roda `npm install` fora do repo, com o ambiente limpo (sem
81
+ `NODE_PATH`/`npm_config_*` herdados — a lição do `release:check`).
82
+ - **Custo**: o tier barato roda em segundos (sem rede); o `--full` é minutos (baixa NestJS).
83
+
84
+ ## 7. Riscos e mitigação
85
+
86
+ | Risco | Probabilidade | Impacto | Mitigação |
87
+ |---|---|---|---|
88
+ | `--full` flaky por rede (npm registry) | M | M | tier barato é o gate de CI; `--full` é opt-in/pré-release, como o clean-install |
89
+ | Gerador tem efeitos colaterais fora do tmp | B | A | gerar sempre com destino explícito no tmp; o teste falha alto se escrever fora |
90
+ | Duplicar lógica de validação | B | M | reusar `structure-validator` e o runner de `checks.mjs` — AC-4/AC-6 |
91
+
92
+ ## 8. Métricas de sucesso
93
+
94
+ 30 dias após o release: **pelo menos uma regressão do gerador pega pelo gate antes do merge** (a
95
+ prova de que a fronteira estava mesmo descoberta), e **zero issue de usuário sobre scaffold quebrado**
96
+ (placeholder vazado, `package.json` inválido).
@@ -0,0 +1,58 @@
1
+ # Spec: project-upgrade
2
+
3
+ - **ID**: SPEC-018
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0020 (core/registry), ADR-0024 (isolamento em tmp — o padrão do gate)
7
+
8
+ ## 1. Problema
9
+
10
+ O framework **gera** projetos, mas nunca soube **atualizar** um já gerado. Quando o Forja evolui —
11
+ uma pasta de memória nova (`70-summaries/`), um agent novo, um config multi-IA novo — quem gerou numa
12
+ versão antiga fica preso nela. A única saída era regerar (e perder o código) ou copiar peças na mão
13
+ (e esquecer quais). É a metade que falta de todo scaffolder.
14
+
15
+ ## 2. Proposta de valor
16
+
17
+ Um projeto gerado consegue **incorporar as peças novas do scaffold** sem regerar e sem risco: o
18
+ comando traz o que falta, e **nunca** toca no que já existe (onde mora a edição do usuário).
19
+
20
+ ## 3. User stories
21
+
22
+ - **Como** dono de um projeto gerado numa versão antiga, **quero** puxar as peças novas do framework,
23
+ **para que** eu não fique preso na versão em que gerei nem perca meu código regerando.
24
+ - **Como** dev cauteloso, **quero** um dry-run antes de qualquer escrita, **para que** eu veja
25
+ exatamente o que será adicionado.
26
+
27
+ ## 4. Critérios de aceite (Definition of Done)
28
+
29
+ - [x] AC-1: `forja project:upgrade` gera um scaffold fresco num tmp isolado, faz o diff contra o
30
+ projeto e lista **só os arquivos que faltam** (dry-run por padrão).
31
+ - [x] AC-2: **Aditivo, nunca sobrescreve.** Um arquivo que já existe no projeto não é listado nem
32
+ tocado — é território do usuário. Provado em teste (edição preservada sob `--apply`).
33
+ - [x] AC-3: `--apply` copia as peças novas, criando diretórios; reporta quantas.
34
+ - [x] AC-4: `--project <path>` (default `cwd`); reprova cedo se o alvo não parece um projeto Forja
35
+ (sem `AGENTS.md`). Limpa o tmp sempre.
36
+ - [x] AC-5: Lógica pura e testável (`lib/project-upgrade.ts`), com fixtures.
37
+
38
+ ## 5. Escopo
39
+
40
+ **Dentro**: adicionar arquivos de scaffold ausentes (memória, agents, prompts, skills, configs).
41
+
42
+ **Fora** (explícito — a fronteira de segurança):
43
+ - **Sobrescrever ou fazer merge de arquivos existentes.** É onde vive a edição do usuário; MVP nunca
44
+ toca. Um "upgrade com 3-way merge" é trabalho de outra spec, com muito mais risco.
45
+ - Migrar dados (memória indexada, `.context`) — são runtime, ficam de fora do diff.
46
+ - Atualizar `package.json`/dependências do backend — é código do usuário.
47
+
48
+ ## 6. NFRs / restrições
49
+
50
+ - **Segurança acima de tudo**: additive-only é a invariante. `applyUpgrade` reconfere `existsSync`
51
+ antes de cada cópia (paranoia: jamais sobrescreve).
52
+ - **Isolamento**: o scaffold fresco nasce num tmp com ambiente limpo (`NODE_PATH`/`npm_config_*`
53
+ removidos — a lição do `release:check`), e o tmp é limpo sempre.
54
+
55
+ ## 7. Métricas de sucesso
56
+
57
+ Um projeto gerado numa versão antiga incorpora as peças de uma versão nova sem perder nenhuma linha
58
+ de código do usuário — e o dono revê o diff antes de commitar.
@@ -172,14 +172,15 @@ classe "dist mente") e ADR-0024 (o gate que ganha o `build-fresh`).
172
172
  no CI. Corrigir os erros com os arquivos ainda `.mjs`. Nada renomeado ainda.
173
173
  - [x] **Fase 1 — resolver.** Registry sem extensão (na verdade: registry mantém `.mjs` e o
174
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).
175
+ - [x] **Fase 2 — renomear leaf-first + endurecer.** **Concluída.** Toda a fonte do framework é `.ts`
176
+ (21 `.mjs` + 16 `.js`), e `noImplicitAny` está ON — os ~285 params foram anotados (tipo real
177
+ onde agrega, `any` explícito onde é dinâmico). Shim `lib/vendor.d.ts` para o `better-sqlite3`
178
+ sem tipos; `lib/templates` excluído do type-check (é conteúdo). O ratchet está armado.
179
+ Achados recorrentes no `.ts` estrito: `[]`→`never[]` (anotação inline), os casts-comentário
180
+ `/** @type */ (x)` não narram (viram `as`), e os typedefs JSDoc viram `interface`/`import type`
181
+ reais. Armadilha corrigida em voo: o sed que atualizava os `node:` do registry atingiu também o
182
+ array de fallback do `resolveScript` (`['.ts','.js','.mjs']`→`['.ts','.ts','.ts']`), quebrando a
183
+ resolução do `dist/*.js` — pego pelo `release:check`, não pelo type-check nem pelos testes.
183
184
  - [x] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `package.json` apontando para `dist/`;
184
185
  `prepublishOnly` = gate (o gate builda, D4 revisado). Provado por `release:check` (#15).
185
186
  - [x] Doc/persona: governança ganha o `build-fresh`; `docs/` e `CONTRIBUTING` ganham o "dev roda
@@ -1,7 +1,7 @@
1
1
  # Spec: ts-migration
2
2
 
3
3
  - **ID**: SPEC-012
4
- - **Status**: approved
4
+ - **Status**: done
5
5
  - **Owner**: apk
6
6
  - **Criado em**: 2026-07-18
7
7
  - **Sprint alvo**: S?
@@ -1,2 +0,0 @@
1
- #!/usr/bin/env node
2
- export {};
@@ -1,126 +0,0 @@
1
- #!/usr/bin/env node
2
- /**
3
- * code-intel — camada de code intelligence sobre o codegraph (ADR-0017).
4
- *
5
- * Auto-contido: depende apenas do binario `codegraph` no PATH. Se ausente,
6
- * degrada graciosamente (avisa e segue) — nunca trava o fluxo.
7
- *
8
- * Comandos:
9
- * check Valida indice (worktree + freshness)
10
- * impact <simbolo> [d] Chamadores e blast radius de um simbolo
11
- *
12
- * Emitido por forja/init-project.js. Veja docs do framework para o GSD completo.
13
- */
14
- import { spawnSync } from 'node:child_process';
15
- function runCodegraph(args) {
16
- const result = spawnSync('codegraph', args, { encoding: 'utf8' });
17
- if (result.error && /** @type {any} */ (result.error).code === 'ENOENT')
18
- return { missing: true };
19
- return {
20
- missing: false,
21
- status: result.status ?? 1,
22
- stdout: (result.stdout || '').trim(),
23
- stderr: (result.stderr || '').trim(),
24
- };
25
- }
26
- function codegraphStatus() {
27
- const res = runCodegraph(['status', '--json']);
28
- if (res.missing)
29
- return { missing: true };
30
- let data = null;
31
- try {
32
- data = JSON.parse(/** @type {string} */ (res.stdout));
33
- }
34
- catch {
35
- return { missing: false, parseError: true, raw: res.stdout || res.stderr };
36
- }
37
- const pending = data.pendingChanges || {};
38
- const pendingTotal = (pending.added || 0) + (pending.modified || 0) + (pending.removed || 0);
39
- return {
40
- missing: false,
41
- initialized: Boolean(data.initialized),
42
- worktreeMismatch: data.worktreeMismatch || null,
43
- fileCount: data.fileCount || 0,
44
- pendingTotal,
45
- reindexRecommended: Boolean(data.index && data.index.reindexRecommended),
46
- };
47
- }
48
- function fail(msg) {
49
- console.error(msg);
50
- process.exit(1);
51
- }
52
- function cmdCheck() {
53
- const s = codegraphStatus();
54
- if (s.missing) {
55
- console.log('Codegraph nao instalado no PATH. Code intelligence ignorado.');
56
- console.log('Instale com: npm i -g @codegraph/cli');
57
- process.exit(0);
58
- }
59
- if (s.parseError) {
60
- console.log('Codegraph respondeu, mas status --json nao pode ser lido.');
61
- fail(s.raw || 'sem saida');
62
- }
63
- const lines = [];
64
- let blocking = false;
65
- if (!s.initialized) {
66
- blocking = true;
67
- lines.push('FAIL indice ausente: rode `npm run code:index`.');
68
- }
69
- else {
70
- lines.push(`OK indice inicializado (${s.fileCount} arquivos).`);
71
- }
72
- if (s.worktreeMismatch) {
73
- blocking = true;
74
- lines.push(`FAIL indice de outro worktree: ${s.worktreeMismatch}. Rode \`codegraph init -i\`.`);
75
- }
76
- else if (s.initialized) {
77
- lines.push('OK indice pertence a este worktree.');
78
- }
79
- if (s.pendingTotal > 0 || s.reindexRecommended) {
80
- lines.push(`WARN indice defasado (${s.pendingTotal} pend.). Rode \`npm run code:sync\`.`);
81
- }
82
- else if (s.initialized) {
83
- lines.push('OK indice em dia.');
84
- }
85
- console.log('Codegraph check:\n');
86
- for (const line of lines)
87
- console.log(line);
88
- if (blocking)
89
- fail('\nResultado: gate de code intelligence reprovado.');
90
- console.log('\nResultado: code intelligence confiavel.');
91
- }
92
- function cmdImpact(symbol, depthArg) {
93
- if (!symbol)
94
- fail('Uso: code-intel impact <simbolo> [profundidade]');
95
- const probe = runCodegraph(['status', '--json']);
96
- if (probe.missing) {
97
- console.log('Codegraph nao instalado. Sem mapa de impacto automatico.');
98
- console.log(`Fallback manual: grep -rn "${symbol}" . e leia os chamadores.`);
99
- process.exit(0);
100
- }
101
- const depth = String(parseInt(depthArg, 10) || 2);
102
- console.log(`Mapa de impacto: ${symbol} (profundidade ${depth})\n`);
103
- const impact = runCodegraph(['impact', symbol, '-d', depth]);
104
- if (impact.stdout)
105
- console.log(impact.stdout);
106
- const callers = runCodegraph(['callers', symbol]);
107
- if (callers.stdout) {
108
- console.log('\n--- Chamadores diretos ---');
109
- console.log(callers.stdout);
110
- }
111
- if (!impact.stdout && !callers.stdout) {
112
- console.log('Nenhum no encontrado. Confirme o nome ou rode `npm run code:sync`.');
113
- }
114
- }
115
- const [cmd, ...rest] = process.argv.slice(2);
116
- switch (cmd) {
117
- case 'check':
118
- cmdCheck();
119
- break;
120
- case 'impact':
121
- cmdImpact(rest[0], rest[1]);
122
- break;
123
- default:
124
- console.log('Uso: node scripts/code-intel.mjs <check|impact> [args]');
125
- process.exit(cmd ? 1 : 0);
126
- }