forjajs 1.3.2 → 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.
- package/CHANGELOG.md +52 -0
- package/README.en.md +1 -0
- package/README.md +10 -4
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
- package/dist/lib/code-context.d.ts +41 -0
- package/dist/lib/code-context.js +108 -0
- package/dist/lib/core/doc-graph.d.ts +13 -0
- package/dist/lib/core/doc-graph.js +47 -0
- package/dist/lib/core/health.js +29 -1
- package/dist/lib/core/project-smoke.d.ts +46 -0
- package/dist/lib/core/project-smoke.js +248 -0
- package/dist/lib/core/registry.d.ts +25 -0
- package/dist/lib/core/registry.js +25 -0
- package/dist/lib/core/release.d.ts +25 -0
- package/dist/lib/generators/memory-generator.d.ts +1 -0
- package/dist/lib/generators/memory-generator.js +44 -0
- package/dist/lib/generators/readme-generator.js +1 -0
- package/dist/lib/memory-audit.d.ts +31 -0
- package/dist/lib/memory-audit.js +81 -0
- package/dist/lib/project-upgrade.d.ts +28 -0
- package/dist/lib/project-upgrade.js +74 -0
- package/dist/scripts/code-context.d.ts +12 -0
- package/dist/scripts/code-context.js +73 -0
- package/dist/scripts/memory-audit.d.ts +11 -0
- package/dist/scripts/memory-audit.js +49 -0
- package/dist/scripts/project-smoke.d.ts +14 -0
- package/dist/scripts/project-smoke.js +44 -0
- package/dist/scripts/project-upgrade.d.ts +11 -0
- package/dist/scripts/project-upgrade.js +61 -0
- package/dist/scripts/token-economy.d.ts +20 -0
- package/dist/scripts/token-economy.js +140 -0
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +4 -0
- package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
- package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
- package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
- package/package.json +1 -1
- package/specs/code-context/spec.md +56 -0
- package/specs/memory-audit/spec.md +54 -0
- package/specs/project-smoke/spec.md +96 -0
- package/specs/project-upgrade/spec.md +58 -0
|
@@ -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
|
@@ -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.
|