forjajs 1.1.2 → 1.1.4
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/agents/governance.md +33 -10
- package/.claude/agents/release-auditor.md +44 -45
- package/CHANGELOG.md +74 -0
- package/DOC-MAP.md +2 -2
- package/README.md +2 -2
- package/docs/agent-harnesses.md +30 -3
- package/docs/token-optimization.md +28 -20
- package/lib/core/checks.mjs +138 -0
- package/lib/core/health.mjs +475 -0
- package/lib/core/registry.mjs +6 -1
- package/lib/core/release.mjs +452 -0
- package/memory/40-delivery/current-sprint.md +13 -7
- package/memory/90-decisions/0021-guardrails-de-harness.md +5 -1
- package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -0
- package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -0
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
- package/package.json +7 -7
- package/prompts/governance-agent.md +2 -1
- package/scripts/hook-session-start.mjs +29 -39
- package/scripts/release-check.mjs +56 -0
- package/scripts/spec-cli.mjs +80 -13
- package/scripts/tools-doctor.mjs +65 -10
- package/specs/coerencia-do-sistema/spec.md +122 -0
- package/specs/doctor-do-nucleo/plan.md +165 -0
- package/specs/doctor-do-nucleo/spec.md +139 -0
- package/specs/doctor-do-nucleo/tasks.md +172 -0
- package/specs/reestruturacao-forja-v2/plan.md +1 -1
- package/specs/reestruturacao-forja-v2/spec.md +16 -12
- package/specs/reestruturacao-forja-v2/tasks.md +1 -1
- package/specs/release-gate/plan.md +174 -0
- package/specs/release-gate/spec.md +122 -0
- package/specs/release-gate/tasks.md +183 -0
- package/docs/dashboard.md +0 -102
- package/specs/agent-dashboard/plan.md +0 -165
- package/specs/agent-dashboard/spec.md +0 -89
- package/specs/agent-dashboard/tasks.md +0 -168
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# Tasks: doctor-do-nucleo
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: done
|
|
6
|
+
- **Criado em**: 2026-07-13
|
|
7
|
+
|
|
8
|
+
> Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
|
|
9
|
+
|
|
10
|
+
Convenção de IDs: `T1`, `T2`, … A sequência reflete a **ordem de merge do plano §7**: a lib e os
|
|
11
|
+
testes primeiro (nada a consome ainda), depois as superfícies, e o hook por último — é o de maior
|
|
12
|
+
risco e o único que roda em toda sessão.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## T1 — Runner e contrato de `lib/core/health.mjs`
|
|
17
|
+
- **Owner**: Worker
|
|
18
|
+
- **Estimativa**: M
|
|
19
|
+
- **Depende de**: —
|
|
20
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
21
|
+
- **Escopo**: o esqueleto sem nenhum probe real — `CHECKS[]` vazio ou com um probe de fixture.
|
|
22
|
+
- **Done quando**:
|
|
23
|
+
- [x] `runChecks({ scope, env })` e `worstStatus(results)` exportados conforme plano §4 (AC-1)
|
|
24
|
+
- [x] Cascata: check com `dependsOn` que falhou é reportado `skipped`, nunca `fail`
|
|
25
|
+
- [x] Runner blinda o probe: probe que **lança** vira `fail` com o erro no `detail`, e o runner
|
|
26
|
+
continua os demais — nunca propaga exceção (NFR de resiliência)
|
|
27
|
+
- [x] `worstStatus` só devolve `fail` para `critical`; `warn` nunca escala
|
|
28
|
+
- [x] `env` injetável (`{ root, importModule, fs, workspace }`) com default real (D5)
|
|
29
|
+
- [x] `test/health.test.js` cobre cascata, blindagem e `worstStatus` com probes de fixture
|
|
30
|
+
- [x] Zero dependências novas (plano §6)
|
|
31
|
+
|
|
32
|
+
## T2 — Probes de memória: `native-abi`, `memory-db`, `memory-fresh`
|
|
33
|
+
- **Owner**: Worker
|
|
34
|
+
- **Estimativa**: M
|
|
35
|
+
- **Depende de**: T1
|
|
36
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
37
|
+
- **Escopo**: os três checks que teriam pego a quebra de hoje. É o núcleo do núcleo.
|
|
38
|
+
- **Done quando**:
|
|
39
|
+
- [x] `native-abi` (critical) classifica por `err.code`, **não** por string de mensagem (risco da
|
|
40
|
+
spec): `ERR_DLOPEN_FAILED` → `npm rebuild better-sqlite3`; `ERR_MODULE_NOT_FOUND` →
|
|
41
|
+
`npm install` (AC-3)
|
|
42
|
+
- [x] `memory-db` (critical, `dependsOn: native-abi`) distingue **ausente** de **inacessível**,
|
|
43
|
+
cada um com sua correção (AC-4)
|
|
44
|
+
- [x] `memory-fresh` (**warn**, `dependsOn: memory-db`): `memory/` alterado depois do último sync
|
|
45
|
+
→ `npm run sync:universal`. Reaproveita a lógica de `newestMemoryMtime` que hoje vive no
|
|
46
|
+
hook (AC-4)
|
|
47
|
+
- [x] Teste do ABI quebrado injeta `env.importModule` que lança `ERR_DLOPEN_FAILED` — sem mock de
|
|
48
|
+
módulo, sem corromper `node_modules` (D5)
|
|
49
|
+
- [x] Cada probe testado nos dois estados: são e quebrado (AC-9)
|
|
50
|
+
|
|
51
|
+
## T3 — Probes de ambiente: `workspace`, `node-engines`
|
|
52
|
+
- **Owner**: Worker
|
|
53
|
+
- **Estimativa**: P
|
|
54
|
+
- **Depende de**: T1
|
|
55
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
56
|
+
- **Done quando**:
|
|
57
|
+
- [x] `workspace` (**warn**, D4) usa `getWorkspaceInfo()` de `lib/workspace.mjs`; se não resolve
|
|
58
|
+
para diretório existente → `npm run workspace:init`. Reporta também a **origem** da
|
|
59
|
+
resolução (`FORJA_WORKSPACE` / `~/.forjarc.json` / default), que é metade do diagnóstico
|
|
60
|
+
quando o workspace certo existe mas não é o que está sendo usado (AC-5)
|
|
61
|
+
- [x] `node-engines` (**warn**) compara `process.versions.node` com `engines.node` do
|
|
62
|
+
`package.json`
|
|
63
|
+
- [x] Ambos testados nos dois estados via `env.fs` / `env.workspace` injetados
|
|
64
|
+
|
|
65
|
+
## T4 — Probes de regressão do repo: `runtime-deps`, `mcp-json`
|
|
66
|
+
- **Owner**: Worker
|
|
67
|
+
- **Estimativa**: M
|
|
68
|
+
- **Depende de**: T1
|
|
69
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
70
|
+
- **Escopo**: converte em gate executável os dois invariantes que o ADR-0021 corrigiu à mão e que
|
|
71
|
+
hoje podem reincidir sem que nada perceba.
|
|
72
|
+
- **Done quando**:
|
|
73
|
+
- [x] Ambos com `scope: 'repo'` — **não** rodam fora do repo do framework, onde produziriam falso
|
|
74
|
+
positivo crítico na máquina do usuário final (D3). Detecção: `.git` + `package.json` com
|
|
75
|
+
`name: forjajs`
|
|
76
|
+
- [x] `runtime-deps` (critical): todo módulo importado **estaticamente** por script sob `files[]`
|
|
77
|
+
está em `dependencies`, não em `devDependencies` (AC-6). Parser **conservador**: import
|
|
78
|
+
dinâmico ou não resolvido → `warn`, nunca `fail` (risco da spec)
|
|
79
|
+
- [x] `mcp-json` (critical): nenhum path absoluto versionado em `.mcp.json` (AC-7)
|
|
80
|
+
- [x] Teste com fixture de `package.json`/`.mcp.json` quebrados, via `env.fs` e `env.root`
|
|
81
|
+
- [x] Teste garantindo que ambos são `skipped` quando `scope: 'runtime'`
|
|
82
|
+
|
|
83
|
+
## T5 — `tools:doctor` consome a lib e vira gate
|
|
84
|
+
- **Owner**: Worker
|
|
85
|
+
- **Estimativa**: M
|
|
86
|
+
- **Depende de**: T2, T3, T4
|
|
87
|
+
- **Paths**: `scripts/tools-doctor.mjs`
|
|
88
|
+
- **Done quando**:
|
|
89
|
+
- [x] Duas seções na saída: **Núcleo** e **Ferramentas** (AC-2)
|
|
90
|
+
- [x] `exit 1` **se e somente se** algum check `critical` do núcleo falhar. Ferramenta opcional
|
|
91
|
+
ausente segue `exit 0` — contrato do ADR-0018 preservado (AC-2, D4)
|
|
92
|
+
- [x] `TOOLS[]` das cinco ferramentas opcionais permanece intocado (spec §5, fora de escopo)
|
|
93
|
+
- [x] Cada falha imprime o comando de correção ao lado
|
|
94
|
+
- [x] Roda em < 2s (NFR)
|
|
95
|
+
- [x] Funciona **sem `node_modules`** — é justamente aí que ele mais importa (NFR)
|
|
96
|
+
|
|
97
|
+
## T6 — `SessionStart` consome a lib e perde a heurística própria
|
|
98
|
+
- **Owner**: Worker
|
|
99
|
+
- **Estimativa**: M
|
|
100
|
+
- **Depende de**: T2, T3
|
|
101
|
+
- **Paths**: `scripts/hook-session-start.mjs`
|
|
102
|
+
- **Escopo**: a task de maior risco. O hook roda em toda sessão e o ADR-0021 o marcou como "nunca
|
|
103
|
+
pode derrubar a sessão".
|
|
104
|
+
- **Done quando**:
|
|
105
|
+
- [x] `resolveDbPath()` e `staleIndex()` **deixam de existir** — o `catch { return null }` que
|
|
106
|
+
colapsa três causas distintas é a raiz do problema (plano §1)
|
|
107
|
+
- [x] A prescrição errada (`npm install` para ABI quebrado, linha 91) não existe mais no código
|
|
108
|
+
(AC-8)
|
|
109
|
+
- [x] Chama `runChecks({ scope: 'runtime' })` — zero heurística própria (AC-8)
|
|
110
|
+
- [x] **Sempre `exit 0`**: o hook reporta, nunca trava a sessão (ADR-0021)
|
|
111
|
+
- [x] Cabe com folga no timeout de 5s; se não couber, ver kill criteria do plano §8
|
|
112
|
+
- [x] `test/hooks.test.js` estendido: sem `node_modules` o hook degrada, não estoura
|
|
113
|
+
|
|
114
|
+
## T7 — ADR-0023
|
|
115
|
+
- **Owner**: SDD Architect
|
|
116
|
+
- **Estimativa**: P
|
|
117
|
+
- **Depende de**: T5, T6
|
|
118
|
+
- **Paths**: `memory/90-decisions/0023-doctor-como-gate-do-nucleo.md`
|
|
119
|
+
- **Done quando**:
|
|
120
|
+
- [x] Registra D1 (checks como dados), D3 (`scope` repo/runtime) e a mudança de contrato do exit
|
|
121
|
+
code (AC-10)
|
|
122
|
+
- [x] Referencia ADR-0018 (que estende) e ADR-0021 (a classe de falha que fecha)
|
|
123
|
+
- [x] Segue `memory/90-decisions/_template.md`
|
|
124
|
+
|
|
125
|
+
## T8 — Registry e documentação
|
|
126
|
+
- **Owner**: Worker
|
|
127
|
+
- **Estimativa**: P
|
|
128
|
+
- **Depende de**: T5
|
|
129
|
+
- **Paths**: `lib/core/registry.mjs`, `CLAUDE.md`, `docs/`
|
|
130
|
+
- **Done quando**:
|
|
131
|
+
- [x] `desc` do `tools:doctor` no registry reflete o novo papel (deixa de ser só "ferramentas de
|
|
132
|
+
processo")
|
|
133
|
+
- [x] `CLAUDE.md` e `docs/` onde o comando é descrito como "raio-x de ferramentas"
|
|
134
|
+
- [x] `npm test` verde, incluindo `test/forja-core.test.js` (integridade do registry, ADR-0020)
|
|
135
|
+
|
|
136
|
+
## T9 — Validação no cenário real
|
|
137
|
+
- **Owner**: Governance
|
|
138
|
+
- **Estimativa**: P
|
|
139
|
+
- **Depende de**: T5, T6, T7, T8
|
|
140
|
+
- **Paths**: —
|
|
141
|
+
- **Done quando**:
|
|
142
|
+
- [x] `tools:doctor` roda sob um Node de **major diferente** e reporta o ABI quebrado com a
|
|
143
|
+
prescrição certa. Um doctor de ABI que nunca viu um ABI quebrado não está testado, está
|
|
144
|
+
escrito (plano §7)
|
|
145
|
+
- [x] `npm run project:check` e `npm test` verdes
|
|
146
|
+
- [x] `gitleaks detect --no-banner` limpo
|
|
147
|
+
- [x] Suíte completa verde (AC-9); spec → `done`
|
|
148
|
+
|
|
149
|
+
## T10 — `spec:new` mantém a allow-list do `.gitignore`
|
|
150
|
+
- **Owner**: Worker
|
|
151
|
+
- **Estimativa**: P
|
|
152
|
+
- **Depende de**: — *(independente da lib; pode ir primeiro)*
|
|
153
|
+
- **Paths**: `scripts/spec-cli.mjs`, `test/spec-cli.test.js`
|
|
154
|
+
- **Contexto**: descoberto ao escrever o plano. O `.gitignore` ignora `/specs/*` e mantém uma
|
|
155
|
+
allow-list manual; **toda spec nova do framework nasce invisível ao git**. Aconteceu com esta
|
|
156
|
+
própria spec. Emenda de 2026-07-13 à spec (AC-11).
|
|
157
|
+
- **Done quando**:
|
|
158
|
+
- [x] `spec:new <slug>` acrescenta `!/specs/<slug>` ao bloco de allow-list do `.gitignore`
|
|
159
|
+
- [x] **Idempotente**: rodar duas vezes não duplica a linha
|
|
160
|
+
- [x] Insere **dentro do bloco existente** (após a última `!/specs/…`), não no fim do arquivo —
|
|
161
|
+
as regras seguintes do `.gitignore` dependem da ordem
|
|
162
|
+
- [x] Se o bloco não existir (ou o `.gitignore` sumir), **não falha** a criação da spec: avisa e
|
|
163
|
+
segue. Criar spec é o trabalho; manter o gitignore é o efeito colateral
|
|
164
|
+
- [x] Teste: cria spec num `.gitignore` de fixture e verifica a linha, a idempotência e a posição
|
|
165
|
+
- [x] `git status` mostra a spec recém-criada, sem passo manual (AC-11)
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Handoffs entre agentes
|
|
170
|
+
|
|
171
|
+
Este conjunto atravessa Worker (T1-T6, T8, T10), SDD Architect (T7) e Governance (T9). Registrar
|
|
172
|
+
handoff a cada fronteira via `npm run agent:route` — 7 campos obrigatórios (ADR-0005).
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Spec: reestruturacao-forja-v2
|
|
2
2
|
|
|
3
3
|
- **ID**: SPEC-028
|
|
4
|
-
- **Status**:
|
|
4
|
+
- **Status**: done
|
|
5
5
|
- **Owner**: apk
|
|
6
6
|
- **Criado em**: 2026-07-01
|
|
7
7
|
- **Sprint alvo**: <S?>
|
|
8
|
-
- **ADRs relacionadas**:
|
|
8
|
+
- **ADRs relacionadas**: ADR-0019 (workspace separado), ADR-0020 (core CLI única)
|
|
9
9
|
|
|
10
10
|
## 1. Problema
|
|
11
11
|
O Forja hoje mistura o **framework** (motor) com os **produtos gerados** dentro do mesmo repositório. A pasta `projects/` é gitignored, a memória universal dos produtos (`memory/30-projects/`, `.memory/sqlite/universal.db`) fica no repo do framework e não há um "canto fixo" claro onde os projetos vão parar. Isso causa:
|
|
@@ -23,16 +23,20 @@ Separar o framework Forja do workspace de produção em um diretório fixo (`~/f
|
|
|
23
23
|
- **Como** arquiteto, **quero** um comando `forja workspace:init` e `forja project:new`, **para que** o harness GSD seja operado de forma unificada.
|
|
24
24
|
|
|
25
25
|
## 4. Critérios de aceite (Definition of Done)
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
26
|
+
|
|
27
|
+
> Verificados em 2026-07-09. A spec estava `approved` com o trabalho já concluído — os checkboxes
|
|
28
|
+
> nunca foram marcados. Auditoria confirmou os 10 critérios contra o código.
|
|
29
|
+
|
|
30
|
+
- [x] AC-1: Workspace padrão `~/forja-workspace` é criado e configurado automaticamente na primeira operação.
|
|
31
|
+
- [x] AC-2: `init-project` cria projetos obrigatoriamente dentro de `~/forja-workspace/projects/<nome>` (não mais dentro do repo do framework).
|
|
32
|
+
- [x] AC-3: Memória universal (SQLite) e `memory/30-projects/` dos produtos são movidos/criados no workspace, não no repo do framework.
|
|
33
|
+
- [x] AC-4: Scripts `sync:universal`, `query:universal`, `context:smart` e `build-smart-context` passam a operar sobre o workspace. — `query-universal-memory.js` não referencia o workspace diretamente; delega a `getDbPath()` de `memory-schema.mjs`, que resolve para `~/forja-workspace/memory/sqlite/universal.db`.
|
|
34
|
+
- [x] AC-5: Novo módulo `lib/workspace.mjs` centraliza a descoberta do workspace (env `FORJA_WORKSPACE` > `.forjarc.json` > default `~/forja-workspace`).
|
|
35
|
+
- [x] AC-6: ~~`npm run dev -- workspace:init`~~ → **interface mudou** para `node bin/forja.mjs workspace:init` (ADR-0020, core CLI única). Comando presente no registry.
|
|
36
|
+
- [x] AC-7: ~~`npm run dev -- project:new <nome>`~~ → **interface mudou** para `node bin/forja.mjs project:new`. Presente no registry, junto de `project:list` e `workspace:project:check`.
|
|
37
|
+
- [x] AC-8: AGENTS.md, README.md, .gitignore, docs/ e ADRs são atualizados para refletir a separação framework/workspace. — ADR-0019 documenta a decisão.
|
|
38
|
+
- [x] AC-9: `project:check` continua passando no framework e passa a aceitar projeto alvo pelo path absoluto/relativo ao workspace.
|
|
39
|
+
- [x] AC-10: Teste de fumaça: criar um projeto de exemplo no workspace e rodar `project:check` sobre ele. — `~/forja-workspace/projects/forja-smoke-test`.
|
|
36
40
|
|
|
37
41
|
## 5. Escopo
|
|
38
42
|
**Dentro**:
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
# Plan: release-gate
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Criado em**: 2026-07-14
|
|
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 runner já existe.** `runChecks({ checks, env })` em `lib/core/health.mjs` foi escrito genérico
|
|
12
|
+
— recebe a lista de checks por parâmetro e já é exercitado com fixtures nos testes. O gate de
|
|
13
|
+
release não precisa de máquina nova: precisa de **outro catálogo de checks** rodando na mesma
|
|
14
|
+
máquina.
|
|
15
|
+
|
|
16
|
+
Então extraímos o runner para `lib/core/checks.mjs` e deixamos dois catálogos: `health.mjs` (o
|
|
17
|
+
núcleo, fronteira *repo*) e `release.mjs` (o tarball, fronteira *pacote publicado*). Mesma
|
|
18
|
+
severidade, mesma cascata, mesmo contrato de `fix`. Uma máquina, duas fronteiras.
|
|
19
|
+
|
|
20
|
+
A diferença essencial em relação ao doctor: o gate de release **não inspeciona; ele instala**. Grep
|
|
21
|
+
não prova ausência — instalação prova. O `release-auditor` já diz isso, e é a razão de o gate ser
|
|
22
|
+
lento e de tudo bem ser lento.
|
|
23
|
+
|
|
24
|
+
## 2. Módulos afetados
|
|
25
|
+
|
|
26
|
+
| Caminho | Mudança | Risco |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| `lib/core/checks.mjs` | **criar** — runner extraído de `health.mjs` (`runChecks`, `worstStatus`) | M |
|
|
29
|
+
| `lib/core/health.mjs` | editar — passa a importar o runner; re-exporta para não quebrar consumidores | M |
|
|
30
|
+
| `lib/core/release.mjs` | **criar** — catálogo dos checks de tarball | M |
|
|
31
|
+
| `scripts/release-check.mjs` | **criar** — apresentação + exit code | B |
|
|
32
|
+
| `lib/core/registry.mjs` | editar — `release:check` (ADR-0020) | B |
|
|
33
|
+
| `package.json` | editar — `prepublishOnly` | **A** |
|
|
34
|
+
| `.github/workflows/ci.yml` | editar — steps `tools:doctor` e `release:check` | B |
|
|
35
|
+
| `.claude/agents/release-auditor.md` | reescrever — consome o gate, não reimplementa | B |
|
|
36
|
+
| `test/release.test.js` | **criar** — os três bugs históricos como fixture | B |
|
|
37
|
+
|
|
38
|
+
Risco alto no `prepublishOnly`: se ele falhar indevidamente, **ninguém consegue publicar**. É o
|
|
39
|
+
único ponto onde um falso positivo trava a operação inteira em vez de só incomodar.
|
|
40
|
+
|
|
41
|
+
## 3. Diagrama de fluxo
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
npm run release:check [--publish]
|
|
45
|
+
│
|
|
46
|
+
▼
|
|
47
|
+
┌─ preflight ───────────────────────────────────────┐
|
|
48
|
+
│ árvore limpa? --publish → fail senão → warn │ ← v1.1.1 morreu aqui
|
|
49
|
+
└───────────────────────────────────────────────────┘
|
|
50
|
+
│
|
|
51
|
+
▼
|
|
52
|
+
npm pack → /tmp/forja-release-<pid>/
|
|
53
|
+
│
|
|
54
|
+
▼
|
|
55
|
+
npm init + npm i <tgz> (isolado: sem NODE_PATH, sem node_modules do repo)
|
|
56
|
+
│
|
|
57
|
+
▼
|
|
58
|
+
┌──────────── RELEASE_CHECKS[] (lib/core/release.mjs) ──────────┐
|
|
59
|
+
│ id severity o que prova │
|
|
60
|
+
│ tree-clean critical* tarball == commit (*warn sem --publish)
|
|
61
|
+
│ install critical o pacote instala do zero │
|
|
62
|
+
│ registry-scripts critical os 41 comandos existem no tarball │
|
|
63
|
+
│ smoke-commands critical os comandos EXECUTAM (não só help) │
|
|
64
|
+
│ reprova por stderr, não exit code │
|
|
65
|
+
│ deps-declared critical importado ⊆ dependencies │
|
|
66
|
+
│ deps-unused warn dependency que ninguém importa │
|
|
67
|
+
│ imports-resolve critical import relativo resolve no tarball │
|
|
68
|
+
└───────────────────────────────────────────────────────────────┘
|
|
69
|
+
│
|
|
70
|
+
▼
|
|
71
|
+
re-check árvore limpa ← a aprovação é perecível
|
|
72
|
+
│
|
|
73
|
+
▼
|
|
74
|
+
exit 0 / exit 1 + limpa o /tmp
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## 4. Contratos (API/CLI/Schema)
|
|
78
|
+
|
|
79
|
+
```js
|
|
80
|
+
// lib/core/checks.mjs — o runner, sem opinião sobre o que checa
|
|
81
|
+
export async function runChecks(opts); // { checks, scope, env } -> Result[]
|
|
82
|
+
export function worstStatus(results); // -> 'ok' | 'warn' | 'fail'
|
|
83
|
+
|
|
84
|
+
// lib/core/health.mjs — inalterado para quem consome
|
|
85
|
+
export { runChecks, worstStatus } from './checks.mjs'; // re-export: tools-doctor e o hook seguem iguais
|
|
86
|
+
export const CHECKS; // os 7 do núcleo
|
|
87
|
+
|
|
88
|
+
// lib/core/release.mjs
|
|
89
|
+
export const RELEASE_CHECKS;
|
|
90
|
+
export async function withCleanInstall(fn); // empacota, instala isolado, executa, limpa. Sempre limpa.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**CLI**:
|
|
94
|
+
|
|
95
|
+
| Comando | Árvore suja | Uso |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `npm run release:check` | `warn` | Dev quer o smoke test sem commitar. Reprova o resto normalmente. |
|
|
98
|
+
| `npm run release:check -- --publish` | **`fail`** | `prepublishOnly` e CI de release. |
|
|
99
|
+
|
|
100
|
+
A distinção existe porque um gate que reprova todo desenvolvimento local vira um gate que se
|
|
101
|
+
contorna — a lição que o CI nos deu na SPEC-009, quando `memory-db` reprovava qualquer clone novo.
|
|
102
|
+
Mas na hora de publicar, árvore suja é **fatal**: foi assim que `otplib` e `qrcode` entraram na
|
|
103
|
+
v1.1.1 sem existirem no git.
|
|
104
|
+
|
|
105
|
+
## 5. Decisões e alternativas
|
|
106
|
+
|
|
107
|
+
**D1: Extrair o runner em vez de duplicá-lo.** `health.mjs` já tem cascata, blindagem de probe e
|
|
108
|
+
`worstStatus` testados. Copiar tudo para `release.mjs` criaria duas máquinas que divergem com o
|
|
109
|
+
tempo — exatamente o defeito que a SPEC-009 matou quando o doctor e o hook divergiram. Alternativa
|
|
110
|
+
rejeitada: `release.mjs` importar de `health.mjs`, deixando o núcleo dono de um runner que não é
|
|
111
|
+
dele.
|
|
112
|
+
|
|
113
|
+
**D2: Instalar, não inspecionar.** O gate faz `npm pack` + `npm i` de verdade. Alternativa
|
|
114
|
+
rejeitada: análise estática do tarball — foi o que eu fiz à mão hoje e produziu **falso positivo
|
|
115
|
+
imediato** (os geradores contêm `import` dentro de template string). Grep não prova ausência.
|
|
116
|
+
|
|
117
|
+
**D3: Template literals são removidos antes do parse.** Onde a análise estática for inevitável
|
|
118
|
+
(`deps-declared`), o conteúdo entre crases é apagado do fonte antes de casar `import`. Os geradores
|
|
119
|
+
*escrevem* código NestJS; não o executam. Sem isso, o check acusa `@nestjs/core` como dependência
|
|
120
|
+
não declarada — e é o bug latente que já existe hoje no `runtime-deps` (AC-11).
|
|
121
|
+
|
|
122
|
+
**D4: Dois modos (`--publish`).** Ver §4. Severidade do `tree-clean` muda com o contexto; o resto
|
|
123
|
+
é idêntico.
|
|
124
|
+
|
|
125
|
+
**D5: A aprovação é perecível.** O `git status` é reconferido **ao final**, porque a auditoria vale
|
|
126
|
+
para o disco no instante em que rodou. Um `npm install` entre o check e o publish invalida tudo — e
|
|
127
|
+
essa foi literalmente a causa da v1.1.1.
|
|
128
|
+
|
|
129
|
+
**D6: O gate nunca publica.** Ele autoriza. `npm publish` continua sendo um ato humano deliberado.
|
|
130
|
+
|
|
131
|
+
**D7: `deps-unused` é `warn`, não `fail`.** Peso morto no tarball incomoda, não quebra. Reprovar um
|
|
132
|
+
release por causa disso é o tipo de rigor que ensina o time a usar `--no-verify`.
|
|
133
|
+
|
|
134
|
+
**D8: `smoke-commands` reprova por padrão no stderr, nunca por exit code.** Numa instalação limpa
|
|
135
|
+
não existe workspace nem `universal.db` — então `query:universal` sai com código ≠ 0 *legitimamente*,
|
|
136
|
+
e `tools:doctor` avisa sobre memória não indexada. Isso é o pacote **funcionando**. O que denuncia
|
|
137
|
+
tarball quebrado é a assinatura do carregamento: `ERR_MODULE_NOT_FOUND`, `ERR_DLOPEN_FAILED`,
|
|
138
|
+
`Cannot find module`. Reprovar por exit code faria o gate reprovar um pacote saudável — é a mesma
|
|
139
|
+
armadilha do `memory-db` na SPEC-009, um nível acima.
|
|
140
|
+
|
|
141
|
+
**D9: `prepublishOnly`, nunca `prepack`.** O gate roda `npm pack`. Amarrá-lo ao `prepack` faria o
|
|
142
|
+
`npm pack` do gate disparar o `prepack`, que chama o gate, que roda `npm pack`… `npm pack` **não**
|
|
143
|
+
dispara `prepublishOnly`, então o hook correto é o único seguro. Vale um comentário no
|
|
144
|
+
`package.json`: a alternativa "óbvia" é uma bomba-relógio.
|
|
145
|
+
|
|
146
|
+
D1 e a mudança de contrato do `prepublishOnly` são estruturais → **ADR-0024**, referenciando
|
|
147
|
+
ADR-0023 (mesma filosofia, fronteira seguinte) e ADR-0021 (a classe que ambos fecham).
|
|
148
|
+
|
|
149
|
+
## 6. Dependências
|
|
150
|
+
|
|
151
|
+
- **Specs**: SPEC-009 (`lib/core/health.mjs` é a base do runner). Já em `done`.
|
|
152
|
+
- **Pacotes npm**: **nenhum novo.** `npm pack`/`npm i` via `child_process`.
|
|
153
|
+
- **Migrações**: nenhuma.
|
|
154
|
+
|
|
155
|
+
## 7. Rollout
|
|
156
|
+
|
|
157
|
+
- [ ] **Ordem**: `checks.mjs` extraído + suíte verde (refactor puro, nada muda de comportamento) →
|
|
158
|
+
`release.mjs` + testes → `release-check.mjs` → CI → `prepublishOnly` **por último**.
|
|
159
|
+
- [x] Doc/persona impactada: `docs/publishing.md`, `CLAUDE.md`, persona **governança**.
|
|
160
|
+
- [ ] **Validar reintroduzindo os três bugs históricos** (better-sqlite3 em devDeps; arquivo fora do
|
|
161
|
+
`files[]`; árvore suja). Cada um deve reprovar. Um gate que nunca viu a falha que promete
|
|
162
|
+
pegar não está testado — está escrito.
|
|
163
|
+
- [ ] `prepublishOnly` entra **depois** de o gate rodar verde no CI por um ciclo. Ele é a única
|
|
164
|
+
peça que, com falso positivo, impede publicar qualquer coisa.
|
|
165
|
+
|
|
166
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
167
|
+
|
|
168
|
+
- **O gate reprova um release saudável.** Um falso positivo no `prepublishOnly` trava a operação
|
|
169
|
+
inteira. Se acontecer uma vez, o `tree-clean` estrito sai do `prepublishOnly` e fica só no CI.
|
|
170
|
+
- **`deps-declared` volta a acusar os geradores.** Se o D3 não bastar, o check é rebaixado a `warn`
|
|
171
|
+
e a cobertura passa a vir do `smoke-commands` (que executa e não mente).
|
|
172
|
+
- **O gate leva minutos.** O custo real não é o `npm pack` — é o `npm i` compilando o
|
|
173
|
+
`better-sqlite3` do zero (o CI já gasta ~1min45 nisso). Se ficar caro demais, o gate sai do fluxo
|
|
174
|
+
de PR e fica só no release: a instalação limpa é inegociável, a frequência não.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Spec: release-gate
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-010
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-13
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (doctor como gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails de harness), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry), [ADR-0018](../../memory/90-decisions/0018-ferramentas-de-processo.md) (ferramentas de processo)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
**O repositório mente sobre o pacote.** No repo tudo resolve: `node_modules` tem as devDeps, todo
|
|
13
|
+
arquivo está presente, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Entre o
|
|
14
|
+
repo e o tarball existe uma fronteira que nenhum teste atravessa — e ela já cedeu **três vezes**:
|
|
15
|
+
|
|
16
|
+
| Versão | O que foi publicado | Consequência |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| ADR-0021 §2 | `better-sqlite3` como `devDependency` | Dez comandos estouravam com `ERR_MODULE_NOT_FOUND` numa instalação limpa. O `forja` sem argumentos funcionava — o help não carrega os scripts — o que mascarava a quebra. |
|
|
19
|
+
| v1.1.1 | `otplib` e `qrcode` no tarball, **sem jamais existirem no git** | `npm publish` empacota o *disco*, não o commit. Um `npm install` casual entre a auditoria e o publish reescreveu o `package.json`. |
|
|
20
|
+
| v1.1.3 | `docs/dashboard.md` e o script `npm run dashboard`, sem a pasta `dashboard/` | Quem instalava recebia a documentação e o comando, sem o código. |
|
|
21
|
+
|
|
22
|
+
Três ocorrências, uma classe: **o que é publicado não é o que o repositório promete.** Todas
|
|
23
|
+
descobertas *depois* do publish, na máquina de quem instalou.
|
|
24
|
+
|
|
25
|
+
O agente `.claude/agents/release-auditor.md` descreve essa classe com precisão cirúrgica — as
|
|
26
|
+
quatro variantes, o procedimento, os comandos. Mas ele é **um agente**: prosa, opt-in, invocado por
|
|
27
|
+
quem lembrar. Pelo critério do próprio ADR-0021 — *"uma regra que depende de memória não é uma
|
|
28
|
+
regra; é uma sugestão"* — isto não é gate. É a última fronteira do framework que ainda funciona por
|
|
29
|
+
disciplina em vez de por harness.
|
|
30
|
+
|
|
31
|
+
Não é conhecimento que falta. É **execução**.
|
|
32
|
+
|
|
33
|
+
## 2. Proposta de valor
|
|
34
|
+
|
|
35
|
+
Publicar deixa de ser um ato de fé: **nenhuma versão sai sem prova de que uma instalação limpa
|
|
36
|
+
funciona**, e a prova é gerada pelo harness, não pela lembrança de quem publica.
|
|
37
|
+
|
|
38
|
+
## 3. User stories
|
|
39
|
+
|
|
40
|
+
- **Como** quem publica, **quero** que o `npm publish` seja **bloqueado** quando o tarball está
|
|
41
|
+
quebrado, **para que** eu não descubra pela issue de um usuário.
|
|
42
|
+
- **Como** quem publica, **quero** que árvore suja reprove antes de qualquer outra checagem,
|
|
43
|
+
**para que** não se repita a v1.1.1 — auditar um tarball que não é o que será publicado é
|
|
44
|
+
auditar ficção.
|
|
45
|
+
- **Como** usuário do `forjajs`, **quero** que todo comando anunciado exista de verdade no pacote,
|
|
46
|
+
**para que** `npm i -g forjajs` não me entregue documentação sem código.
|
|
47
|
+
- **Como** governança, **quero** a evidência da instalação limpa **no log do CI**, **para que**
|
|
48
|
+
"testado" seja um artefato verificável e não uma afirmação.
|
|
49
|
+
|
|
50
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
51
|
+
|
|
52
|
+
- [ ] AC-1: Existe `npm run release:check` (entrada no registry, ADR-0020) que empacota, instala num
|
|
53
|
+
diretório temporário isolado e **reprova com exit ≠ 0** em qualquer uma das falhas abaixo.
|
|
54
|
+
- [ ] AC-2: **Árvore limpa é pré-condição.** Qualquer saída de `git status --short` reprova
|
|
55
|
+
imediatamente, antes de empacotar. Foi a falha da v1.1.1, e nenhuma instalação a pega.
|
|
56
|
+
- [ ] AC-3: **Instalação limpa real**: `npm pack` → `npm i <tgz>` fora do repo, sem devDeps.
|
|
57
|
+
- [ ] AC-4: **Comandos são executados, não listados.** O `forja` sem argumentos passa mesmo com tudo
|
|
58
|
+
quebrado (o help não carrega os scripts). O gate roda os comandos sem efeito colateral
|
|
59
|
+
(`tools:doctor`, `code:status`, `query:universal`, help) e reprova em `ERR_MODULE_NOT_FOUND`.
|
|
60
|
+
- [ ] AC-5: **Todo comando do registry tem seu script no tarball.** Hoje são 41/41 — o gate torna
|
|
61
|
+
isso permanente, em vez de verdade acidental.
|
|
62
|
+
- [ ] AC-6: **Fronteira deps/devDeps nos dois sentidos**: todo pacote importado por código sob
|
|
63
|
+
`files[]` está em `dependencies`; e toda `dependency` declarada é importada por alguém — peso
|
|
64
|
+
morto viaja no tarball de todo usuário.
|
|
65
|
+
- [ ] AC-7: **Imports em template literal não contam.** Os geradores contêm código NestJS que eles
|
|
66
|
+
*escrevem*, não que *executam*. Contá-los produz falso positivo.
|
|
67
|
+
- [ ] AC-8: `release:check` roda como **`prepublishOnly`** e como **step do CI**. Um gate que só roda
|
|
68
|
+
quando alguém lembra é o problema, não a solução.
|
|
69
|
+
- [ ] AC-9: `tools:doctor` também vira step do CI — o gate do ADR-0023 existe e hoje nada o executa
|
|
70
|
+
automaticamente.
|
|
71
|
+
- [ ] AC-10: O agente `release-auditor` passa a **consumir o gate**, em vez de manter procedimento
|
|
72
|
+
próprio em prosa. Deixa de ser a fonte da verdade e passa a interpretá-la.
|
|
73
|
+
- [ ] AC-11: `runtime-deps` (ADR-0023) endurecido contra o falso positivo do AC-7. Hoje ele passa
|
|
74
|
+
**por sorte**: `@nestjs/*` não está nas devDeps. No dia em que estiver, ele trava o gate.
|
|
75
|
+
- [ ] AC-12: Testes cobrindo cada reprovação com tarball de fixture deliberadamente quebrado.
|
|
76
|
+
|
|
77
|
+
## 5. Escopo
|
|
78
|
+
|
|
79
|
+
**Dentro**:
|
|
80
|
+
- `lib/core/release.mjs` — as checagens como dados, no mesmo formato de `lib/core/health.mjs`
|
|
81
|
+
(`{ id, severity, probe, fix }`). Mesma filosofia, fronteira diferente.
|
|
82
|
+
- `scripts/release-check.mjs` — superfície de apresentação + exit code.
|
|
83
|
+
- `package.json` (`prepublishOnly`) e `.github/workflows/` (steps de `release:check` e `tools:doctor`).
|
|
84
|
+
- `lib/core/health.mjs` — endurecer `runtime-deps` (AC-11).
|
|
85
|
+
- `.claude/agents/release-auditor.md` — reescrito para consumir o gate.
|
|
86
|
+
|
|
87
|
+
**Fora** (explícito):
|
|
88
|
+
- **Publicar automaticamente.** O gate autoriza; quem publica é humano. Automatizar o `npm publish`
|
|
89
|
+
é a classe de risco oposta à que esta spec fecha.
|
|
90
|
+
- Mudar o conteúdo de `files[]` — o gate *verifica* o que está lá; não decide o que deveria estar.
|
|
91
|
+
- Assinatura/proveniência de pacote (npm provenance) — vale a pena, mas é outra spec.
|
|
92
|
+
- Testar os projetos **gerados** pelos boilerplates. É uma fronteira real e descoberta, mas grande
|
|
93
|
+
demais para entrar aqui de carona.
|
|
94
|
+
|
|
95
|
+
## 6. NFRs / restrições
|
|
96
|
+
|
|
97
|
+
- **Honestidade acima de velocidade**: o gate instala de verdade. Vai levar dezenas de segundos, e
|
|
98
|
+
tudo bem — roda antes de publicar e no CI, não a cada commit.
|
|
99
|
+
- **Isolamento**: a instalação acontece fora do repo, em diretório temporário, sem herdar
|
|
100
|
+
`node_modules` nem `NODE_PATH`. Um gate que enxerga o repo não prova nada.
|
|
101
|
+
- **Zero falso positivo crítico**: melhor deixar passar um caso duvidoso do que reprovar um release
|
|
102
|
+
saudável. Análise estática ambígua vira `warn`, nunca `fail`.
|
|
103
|
+
- **Compatibilidade**: não altera nenhum comando existente. `release:check` é aditivo.
|
|
104
|
+
|
|
105
|
+
## 7. Riscos e mitigação
|
|
106
|
+
|
|
107
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
108
|
+
|---|---|---|---|
|
|
109
|
+
| Gate lento e as pessoas o contornam | M | A | Só em `prepublishOnly` e CI; nunca no pre-commit |
|
|
110
|
+
| Falso positivo por template literal nos geradores | **A** | A | AC-7 e AC-11; ambíguo vira `warn`. **Já observado em campo** |
|
|
111
|
+
| Instalação "vaza" para o repo (cache, `NODE_PATH`) e o gate mente verde | M | A | Diretório temporário + `npm init` próprio; teste que injeta tarball quebrado e **exige** reprovação |
|
|
112
|
+
| `prepublishOnly` não roda em todos os fluxos de publish | B | A | Duplicado como step de CI — duas portas, não uma |
|
|
113
|
+
| Escopo escorrega para "testar os projetos gerados" | M | M | Explicitamente fora |
|
|
114
|
+
|
|
115
|
+
## 8. Métricas de sucesso
|
|
116
|
+
|
|
117
|
+
- **Zero** bugs da classe "publicado ≠ repositório" nos 90 dias após a 1.1.4. Foram três em três
|
|
118
|
+
releases; a régua é chegar a zero — e provar.
|
|
119
|
+
- A evidência da instalação limpa passa a existir **no log do CI de cada release**, em vez de na
|
|
120
|
+
memória de quem publicou.
|
|
121
|
+
- Os três bugs históricos viram fixture: cada um, reintroduzido, **reprova** o gate. Um gate que
|
|
122
|
+
nunca viu a falha que promete pegar não está testado — está escrito.
|