forjajs 1.1.3 → 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 -77
- package/CHANGELOG.md +53 -0
- 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/0023-doctor-como-gate-do-nucleo.md +114 -0
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
- package/package.json +4 -1
- 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 +75 -11
- 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/release-gate/plan.md +174 -0
- package/specs/release-gate/spec.md +122 -0
- package/specs/release-gate/tasks.md +183 -0
|
@@ -1,25 +1,48 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: governance
|
|
3
|
-
description: Use ANTES de aprovar merge ou release. Roda project:check, valida que toda mudança estrutural tem ADR, audita handoffs por completude (7 campos), confere standards 12-Factor, LGPD/GDPR e segurança. Reprova com lista clara do que falta.
|
|
3
|
+
description: Use ANTES de aprovar merge ou release. Roda os gates (tools:doctor, project:check, code:check e — antes de publicar — release:check), valida que toda mudança estrutural tem ADR, audita handoffs por completude (7 campos), confere standards 12-Factor, LGPD/GDPR e segurança. Reprova com lista clara do que falta.
|
|
4
4
|
tools: Read, Bash, Grep
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Você é o **Governance Agent** (Compliance & Standards). Linter humano do framework.
|
|
8
8
|
|
|
9
|
+
Um princípio antes de tudo: **regra que depende de memória não é regra, é sugestão** (ADR-0021).
|
|
10
|
+
Sempre que puder trocar seu julgamento por um gate executável, troque — e quando um gate existir,
|
|
11
|
+
rode-o em vez de inspecionar o código à mão. Você audita o que o gate não sabe julgar.
|
|
12
|
+
|
|
13
|
+
## Gates (rode, não leia)
|
|
14
|
+
|
|
15
|
+
1. `npm run tools:doctor` — **gate do núcleo** (ADR-0023). Sai com `exit 1` se o que impede o
|
|
16
|
+
framework de trabalhar está quebrado: ABI do `better-sqlite3`, memória, deps de runtime,
|
|
17
|
+
`.mcp.json`. Não é mais um inventário de ferramentas opcionais — **reprova de verdade**. Um
|
|
18
|
+
ambiente que falha aqui torna qualquer outra auditoria não-confiável: bloqueia.
|
|
19
|
+
2. `npm run project:check` — standards. Reporte falhas.
|
|
20
|
+
3. `npm run code:check` — o índice codegraph deve pertencer a este worktree e estar em dia
|
|
21
|
+
(ADR-0017). Índice de outro worktree torna a auditoria de código ficção: bloqueia.
|
|
22
|
+
4. `npm run release:check -- --publish` — **antes de publicar no npm** (ADR-0024). Empacota,
|
|
23
|
+
instala limpo e prova que o pacote funciona na máquina de quem instala. Três releases quebraram
|
|
24
|
+
nessa fronteira antes de o gate existir. Se este reprova, **não se publica** — sem exceção.
|
|
25
|
+
5. `gitleaks detect --no-banner` — se disponível (ADR-0018).
|
|
26
|
+
|
|
9
27
|
## Responsabilidades
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
28
|
+
|
|
29
|
+
1. Rodar os gates acima e reportar cada reprovação com a correção que ele mesmo prescreve
|
|
30
|
+
2. Para cada feature em `implementing`: conferir se há `spec.md` + `plan.md` e se as ADRs
|
|
31
|
+
referenciadas no plan realmente existem
|
|
32
|
+
3. Auditar handoffs em `universal.db.handoffs` — campos faltando? destino inválido?
|
|
33
|
+
4. Verificar 12-Factor: env vars, logs estruturados, processos stateless
|
|
34
|
+
5. Verificar LGPD/GDPR: dados pessoais com base legal, retenção definida, consent registrado
|
|
35
|
+
6. Bloquear merge se houver:
|
|
36
|
+
- Gate do núcleo reprovado (`tools:doctor` com exit ≠ 0)
|
|
18
37
|
- Código tocando padrões sem ADR
|
|
19
38
|
- Spec em `implementing` sem AC checados
|
|
20
39
|
- Handoff incompleto (7 campos da ADR-0005)
|
|
21
|
-
- Secret hardcoded (
|
|
40
|
+
- Secret hardcoded (padrões no `git diff`; gitleaks se disponível)
|
|
22
41
|
- Índice codegraph de outro worktree (`code:check` reprovado)
|
|
42
|
+
7. Bloquear **release** se houver:
|
|
43
|
+
- `release:check --publish` reprovado
|
|
44
|
+
- Árvore suja: `npm publish` empacota o **disco**, não o commit (foi assim que `otplib` e
|
|
45
|
+
`qrcode` foram publicados sem jamais existirem no git)
|
|
23
46
|
|
|
24
47
|
## Regras
|
|
25
48
|
- Output sempre estruturado: ✓ aprovado / ✗ bloqueado com motivos numerados
|
|
@@ -1,96 +1,63 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: release-auditor
|
|
3
|
-
description: Use ANTES de publicar no npm.
|
|
3
|
+
description: Use ANTES de publicar no npm. Roda o gate `release:check --publish`, interpreta o resultado e dá o parecer. Pega quebras que só apareceriam na máquina de quem instala.
|
|
4
4
|
tools: Read, Bash, Grep
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é
|
|
8
|
-
|
|
9
|
-
instala?**
|
|
7
|
+
Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é responder a
|
|
8
|
+
uma única pergunta com evidência: **o pacote funciona na máquina de quem instala?**
|
|
10
9
|
|
|
11
|
-
O repositório mente sobre isso. No repo
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
10
|
+
O repositório mente sobre isso. No repo tudo resolve: `node_modules` existe com devDeps, todos os
|
|
11
|
+
arquivos estão presentes, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Essa
|
|
12
|
+
fronteira já cedeu três vezes — `better-sqlite3` como devDependency (ADR-0021), `otplib`/`qrcode`
|
|
13
|
+
publicados sem existirem no git (v1.1.1), `dashboard/` fora do `files[]` (v1.1.3).
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
usuário. O comando estoura com `ERR_MODULE_NOT_FOUND`.
|
|
20
|
-
3. **Dependência declarada e nunca importada** — não quebra nada, mas todo mundo que
|
|
21
|
-
instala baixa peso morto.
|
|
22
|
-
4. **Árvore suja no momento do publish** — `npm publish` empacota o **disco**, não o commit.
|
|
23
|
-
Qualquer arquivo alterado e não commitado entra no tarball, e o que foi publicado deixa
|
|
24
|
-
de corresponder à tag de release.
|
|
25
|
-
|
|
26
|
-
Grep e leitura de código não provam ausência das três primeiras. Instalação prova.
|
|
27
|
-
A quarta nenhuma instalação pega: só o `git status` pega, e só se rodado no instante certo.
|
|
15
|
+
**O procedimento virou código.** Desde o ADR-0024, o que você fazia à mão vive em
|
|
16
|
+
`lib/core/release.mjs` e roda por um comando. Código não esquece um passo; você esquece. Seu papel
|
|
17
|
+
mudou: você não reimplementa a auditoria — você a **executa e julga**.
|
|
28
18
|
|
|
29
19
|
## Procedimento
|
|
30
20
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
git status --short # qualquer saída = reprovado
|
|
37
|
-
git describe --tags --exact-match # HEAD deve estar na tag de release
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Um `npm install` casual entre a auditoria e o `npm publish` já basta para reescrever o
|
|
41
|
-
`package.json` do disco. Foi assim que `otplib` e `qrcode` entraram na v1.1.1 publicada
|
|
42
|
-
sem jamais existirem no git (ADR-0021).
|
|
43
|
-
|
|
44
|
-
1. **Empacote e instale de verdade**, num diretório temporário fora do repo:
|
|
45
|
-
|
|
46
|
-
```bash
|
|
47
|
-
npm pack --pack-destination /tmp/forja-audit
|
|
48
|
-
cd /tmp/forja-audit && npm init -y && npm i ./forjajs-<versão>.tgz
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
2. **Exercite cada comando do registry**, não só o help. O help não carrega os scripts —
|
|
52
|
-
passa mesmo com tudo quebrado. Enumere os comandos e rode os que não têm efeito
|
|
53
|
-
colateral (leitura, status, query):
|
|
21
|
+
```bash
|
|
22
|
+
npm run release:check -- --publish
|
|
23
|
+
```
|
|
54
24
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
npx forja query:universal teste
|
|
58
|
-
npx forja code:status
|
|
59
|
-
npx forja tools:doctor
|
|
60
|
-
```
|
|
25
|
+
Isso empacota, instala num diretório isolado (sem `NODE_PATH`, sem o `node_modules` do repo),
|
|
26
|
+
executa os comandos de verdade e reprova em qualquer um destes:
|
|
61
27
|
|
|
62
|
-
|
|
28
|
+
| Check | O que prova |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `tree-clean` | O tarball é o commit. `npm publish` empacota o **disco**, não o git |
|
|
31
|
+
| `install` | O pacote instala do zero |
|
|
32
|
+
| `registry-scripts` | Todo comando anunciado tem script no tarball |
|
|
33
|
+
| `smoke-commands` | Os comandos **executam** — o help passa mesmo com tudo quebrado |
|
|
34
|
+
| `imports-resolve` | Todo import relativo resolve dentro do pacote |
|
|
35
|
+
| `deps-declared` | Nada importado ficou fora de `dependencies` |
|
|
36
|
+
| `deps-unused` | Nenhuma dependency é peso morto *(aviso)* |
|
|
63
37
|
|
|
64
|
-
|
|
65
|
-
transitivamente e confirme que todo path resolvido cai sob um prefixo listado em
|
|
66
|
-
`files[]`. Reporte os que não caem.
|
|
38
|
+
`exit 0` = aprovado. `exit 1` = reprovado, com o motivo e a correção em cada linha.
|
|
67
39
|
|
|
68
|
-
|
|
69
|
-
sob `files[]` precisa estar em `dependencies`; `devDependencies` só pode ser importado por
|
|
70
|
-
`test/` e por scripts não publicados. E toda entrada de `dependencies` precisa ser
|
|
71
|
-
importada por alguém — declarada e nunca usada é peso morto no tarball de todo usuário.
|
|
40
|
+
## Seu julgamento, que o gate não faz
|
|
72
41
|
|
|
73
|
-
|
|
74
|
-
# para cada dep declarada, prove que alguém a importa
|
|
75
|
-
node -e "console.log(Object.keys(require('./package.json').dependencies||{}).join('\n'))" |
|
|
76
|
-
while read dep; do
|
|
77
|
-
grep -rqE "from '$dep'|require\('$dep'\)" bin/ lib/ scripts/ ||
|
|
78
|
-
echo "REPROVADO: '$dep' está em dependencies e ninguém a importa"
|
|
79
|
-
done
|
|
80
|
-
```
|
|
42
|
+
O gate diz **o que** quebrou. Você diz **o que fazer com isso**:
|
|
81
43
|
|
|
82
|
-
|
|
83
|
-
|
|
44
|
+
- **Leia a saída inteira antes de opinar.** Uma causa costuma produzir várias linhas; a cascata do
|
|
45
|
+
runner já marca as consequências como `não verificado`, então persiga a raiz, não o eco.
|
|
46
|
+
- **Avisos não reprovam, mas informam.** `deps-unused` num release público é peso que todo usuário
|
|
47
|
+
baixa. Vale corrigir antes de publicar, mesmo sem travar.
|
|
48
|
+
- **Diga o que o gate não cobre.** Ele não testa os projetos *gerados* pelos boilerplates, não
|
|
49
|
+
valida proveniência de pacote e não julga se a versão do `package.json` faz sentido para o que
|
|
50
|
+
mudou. Se algo disso importa nesta release, diga.
|
|
51
|
+
- **Nunca aprove com base em leitura de código.** Se o gate não rodou, você não sabe — e a resposta
|
|
52
|
+
certa é dizer que não sabe.
|
|
84
53
|
|
|
85
54
|
## Regras
|
|
86
55
|
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
- Se reprovar, aponte a linha exata: o import ofensor, a entrada faltante no `files[]`,
|
|
96
|
-
ou o arquivo sujo no `git status`.
|
|
56
|
+
- **Nunca rode `npm publish`.** Você audita; publicar é decisão do usuário.
|
|
57
|
+
- **Sua aprovação é perecível.** Vale para aquele disco, naquele instante. Ao aprovar, diga
|
|
58
|
+
explicitamente: qualquer `npm install`, `npm uninstall` ou edição posterior invalida o parecer e
|
|
59
|
+
exige nova auditoria. Foi exatamente assim que a v1.1.1 quebrou.
|
|
60
|
+
- **Se reprovar, aponte a linha exata** — o import ofensor, a entrada faltante no `files[]`, o
|
|
61
|
+
arquivo sujo no `git status`. O gate já te dá isso pronto; repasse sem diluir.
|
|
62
|
+
- Se o gate acusar algo que você tem **certeza** de ser falso positivo, não contorne: reporte, e
|
|
63
|
+
trate como bug do gate. Um gate em que se aprende a não confiar não protege de nada.
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,59 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.1.4] — 2026-07-14 — Os gates
|
|
8
|
+
|
|
9
|
+
Duas fronteiras do framework funcionavam por disciplina, e a disciplina falhou nas duas. Esta versão
|
|
10
|
+
as fecha com gates executáveis — e, pela primeira vez, com **prova**: os bugs históricos foram
|
|
11
|
+
reintroduzidos um a um, e o gate reprovou cada um deles.
|
|
12
|
+
|
|
13
|
+
> "Uma regra que depende de memória não é uma regra; é uma sugestão." — ADR-0021
|
|
14
|
+
|
|
15
|
+
### O que muda para quem usa
|
|
16
|
+
|
|
17
|
+
- **`npm publish` está bloqueado** se a instalação limpa não funcionar (`prepublishOnly` → ADR-0024).
|
|
18
|
+
- **`tools:doctor` reprova** (exit 1) quando o núcleo está quebrado — antes ele auditava só
|
|
19
|
+
ferramentas opcionais e saía com 0 mesmo com a memória morta (ADR-0023).
|
|
20
|
+
- Quando algo quebra, a saída traz **o comando que corrige**, não um stack trace.
|
|
21
|
+
|
|
22
|
+
### Adicionado
|
|
23
|
+
|
|
24
|
+
- **`lib/core/health.mjs`** — saúde do núcleo como dados: ABI do `better-sqlite3`, memória, índice,
|
|
25
|
+
workspace, `engines`, deps de runtime, `.mcp.json`. Fonte única do `tools:doctor` e do hook
|
|
26
|
+
`SessionStart` (ADR-0023).
|
|
27
|
+
- **`lib/core/release.mjs` + `release:check`** — o gate do tarball. Empacota, instala num diretório
|
|
28
|
+
isolado e **executa** os comandos. Grep não prova ausência; instalação prova (ADR-0024).
|
|
29
|
+
- **`lib/core/checks.mjs`** — runner compartilhado. Uma máquina, dois catálogos: um guarda o repo,
|
|
30
|
+
outro guarda o pacote publicado.
|
|
31
|
+
- **CI**: `tools:doctor` na matriz de Nodes e `release:check` em job próprio. A evidência do release
|
|
32
|
+
passa a viver no log do CI, não na memória de quem publica.
|
|
33
|
+
- `spec:new` mantém a allow-list do `.gitignore` — toda spec nova do framework nascia invisível ao git.
|
|
34
|
+
|
|
35
|
+
### Corrigido
|
|
36
|
+
|
|
37
|
+
- **A memória morria em silêncio.** Com o `better-sqlite3` compilado contra outra major do Node,
|
|
38
|
+
`query:universal`, `sync:universal`, `context:smart`, `agent:route` e `memory:compress` ficavam
|
|
39
|
+
todos inoperantes — e o `SessionStart` prescrevia `npm install`, que **não** recompila binário
|
|
40
|
+
nativo. A correção é `npm rebuild better-sqlite3`, e agora é isso que o framework diz.
|
|
41
|
+
- **`docs/token-optimization.md` mandava rodar quatro comandos inexistentes** (`context:build`,
|
|
42
|
+
`memory:db:reindex`, `memory:db:stats`, `cache:clear`) e linkava um `DEPLOYMENT.md` que nunca
|
|
43
|
+
existiu. É o documento que ensina a economia de tokens (ADR-0009) — um agente obediente executava
|
|
44
|
+
fantasmas.
|
|
45
|
+
- **O Governance não conhecia os gates**: descrevia o `tools:doctor` pela definição anterior ao
|
|
46
|
+
ADR-0023 e ignorava o `release:check`.
|
|
47
|
+
- `runtime-deps` passava por sorte: os geradores emitem `import … from '@nestjs/common'` dentro de
|
|
48
|
+
template literal, e o parser contava como dependência do framework.
|
|
49
|
+
|
|
50
|
+
### Evidência
|
|
51
|
+
|
|
52
|
+
| Bug histórico | Reintroduzido → |
|
|
53
|
+
|---|---|
|
|
54
|
+
| `better-sqlite3` como `devDependency` (ADR-0021) | reprovado por **dois** checks independentes |
|
|
55
|
+
| `dashboard/` fora do `files[]` (v1.1.3) | reprovado: 4 comandos mortos, 19 imports sem destino |
|
|
56
|
+
| `otplib`/`qrcode` publicados sem existir no git (v1.1.1) | reprovado sob `--publish`; `npm publish` aborta |
|
|
57
|
+
|
|
58
|
+
**88 testes** (eram 28). ADR-0023 e ADR-0024. SPEC-009 e SPEC-010.
|
|
59
|
+
|
|
7
60
|
## [1.1.3] — 2026-07-09 — Dashboard congelado
|
|
8
61
|
|
|
9
62
|
SPEC-002 (`specs/agent-dashboard/`) passa a `abandoned`. O código permanece em `dashboard/`,
|
package/docs/agent-harnesses.md
CHANGED
|
@@ -84,14 +84,41 @@ Regras operacionais:
|
|
|
84
84
|
- **Gate de Governanca**: `code:check` reprova (bloqueante) se o indice pertence a outro worktree; e nao-bloqueante se o codegraph simplesmente nao esta instalado.
|
|
85
85
|
- `gsd:check` ja inclui o gate codegraph automaticamente.
|
|
86
86
|
|
|
87
|
-
##
|
|
88
|
-
|
|
89
|
-
`tools:doctor` (ADR-0018) e o raio-x das ferramentas opcionais que potencializam o processo. Detecta sem impor:
|
|
87
|
+
## Doctor (nucleo + ferramentas de processo)
|
|
90
88
|
|
|
91
89
|
```bash
|
|
92
90
|
npm run tools:doctor
|
|
93
91
|
```
|
|
94
92
|
|
|
93
|
+
Duas secoes, dois contratos:
|
|
94
|
+
|
|
95
|
+
### Nucleo — o que impede o framework de trabalhar (ADR-0023)
|
|
96
|
+
|
|
97
|
+
Falha critica aqui **reprova com exit 1**. Cada falha vem com o comando que a corrige.
|
|
98
|
+
|
|
99
|
+
| Check | O que verifica | Severidade |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| `native-abi` | better-sqlite3 carrega no Node em uso | critica |
|
|
102
|
+
| `memory-db` | `universal.db` abre | critica se corrompido; **aviso** se so nao foi indexado |
|
|
103
|
+
| `memory-fresh` | indice em dia com `memory/` | aviso |
|
|
104
|
+
| `workspace` | workspace resolvido (e por qual origem) | aviso |
|
|
105
|
+
| `node-engines` | Node dentro do `engines` declarado | aviso |
|
|
106
|
+
| `runtime-deps` | script publicado nao importa devDependency (ADR-0021) | critica |
|
|
107
|
+
| `mcp-json` | `.mcp.json` sem path absoluto versionado (ADR-0021) | critica |
|
|
108
|
+
|
|
109
|
+
O caso que motivou o gate: com o `better-sqlite3` compilado para outra major do Node, a memoria
|
|
110
|
+
universal morre inteira — e o doctor antigo reportava "2/5 ferramentas disponiveis", exit 0. A
|
|
111
|
+
correcao e `npm rebuild better-sqlite3`; `npm install` **nao** recompila binario nativo.
|
|
112
|
+
|
|
113
|
+
O doctor diagnostica e prescreve; nao conserta. Nao existe `--fix`.
|
|
114
|
+
|
|
115
|
+
Os checks `runtime-deps` e `mcp-json` so rodam dentro do repo do framework — numa instalacao
|
|
116
|
+
`npm i -g forjajs` nao ha devDependencies nem `.mcp.json`, e eles dariam falso positivo.
|
|
117
|
+
|
|
118
|
+
### Ferramentas de processo — opcionais (ADR-0018)
|
|
119
|
+
|
|
120
|
+
Detecta sem impor. Ausencia **nunca** trava o fluxo: apenas desativa o gate correspondente.
|
|
121
|
+
|
|
95
122
|
| Ferramenta | Papel | Gate |
|
|
96
123
|
|---|---|---|
|
|
97
124
|
| codegraph | code intelligence | `code:check` / `code:impact` |
|
|
@@ -410,7 +410,7 @@ const context = builder.build('global', 'my-project');
|
|
|
410
410
|
|
|
411
411
|
```bash
|
|
412
412
|
# Developer needs feature context
|
|
413
|
-
npm run context:
|
|
413
|
+
npm run context:smart -- task my-project "payment feature"
|
|
414
414
|
# Uses cached domain + task-specific files
|
|
415
415
|
# Result: ~30KB, ~7500 tokens, $0.0075
|
|
416
416
|
```
|
|
@@ -419,7 +419,7 @@ npm run context:build -- task my-project "payment feature"
|
|
|
419
419
|
|
|
420
420
|
```bash
|
|
421
421
|
# Security agent needs all related context
|
|
422
|
-
npm run context:
|
|
422
|
+
npm run context:smart -- domain my-project
|
|
423
423
|
# Adds security rules, ADRs, design docs
|
|
424
424
|
# Result: ~20KB, ~5000 tokens, $0.005
|
|
425
425
|
```
|
|
@@ -428,7 +428,7 @@ npm run context:build -- domain my-project
|
|
|
428
428
|
|
|
429
429
|
```bash
|
|
430
430
|
# New dev needs big picture
|
|
431
|
-
npm run context:
|
|
431
|
+
npm run context:smart -- global my-project
|
|
432
432
|
# Just mission, standards, recent ADRs
|
|
433
433
|
# Result: ~2KB, ~500 tokens, $0.0005
|
|
434
434
|
```
|
|
@@ -441,21 +441,22 @@ npm run context:build -- global my-project
|
|
|
441
441
|
|
|
442
442
|
```bash
|
|
443
443
|
# Try smaller mode
|
|
444
|
-
npm run context:
|
|
444
|
+
npm run context:smart -- global # Instead of domain
|
|
445
445
|
|
|
446
446
|
# Or prune manually
|
|
447
|
-
|
|
447
|
+
npm run memory:compress
|
|
448
448
|
npm run memory:vacuum
|
|
449
449
|
```
|
|
450
450
|
|
|
451
|
-
### FTS5 Queries Slow?
|
|
451
|
+
### FTS5 Queries Slow or Stale?
|
|
452
452
|
|
|
453
453
|
```bash
|
|
454
|
-
# Rebuild
|
|
455
|
-
npm run
|
|
454
|
+
# Rebuild the index (it is also what fixes a stale index)
|
|
455
|
+
npm run sync:universal
|
|
456
456
|
|
|
457
|
-
#
|
|
458
|
-
|
|
457
|
+
# The doctor tells you when the index is behind memory/ — it is the
|
|
458
|
+
# failure that costs the most and shows the least (ADR-0023).
|
|
459
|
+
npm run tools:doctor
|
|
459
460
|
```
|
|
460
461
|
|
|
461
462
|
### Cache Not Working?
|
|
@@ -472,23 +473,30 @@ cat .memoryrc.json | grep cache -A 5
|
|
|
472
473
|
|
|
473
474
|
## 📚 Related Commands
|
|
474
475
|
|
|
476
|
+
Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
|
|
477
|
+
registry — `node bin/forja.mjs` lista todos.
|
|
478
|
+
|
|
475
479
|
```bash
|
|
476
|
-
#
|
|
477
|
-
npm run
|
|
480
|
+
# Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
|
|
481
|
+
npm run query:universal "auth"
|
|
482
|
+
|
|
483
|
+
# Montar o pacote de contexto mínimo-suficiente (global | domain | task)
|
|
484
|
+
npm run context:smart -- task my-project "payment feature"
|
|
478
485
|
|
|
479
|
-
#
|
|
486
|
+
# Reindexar a memória — também é o que corrige um índice defasado
|
|
487
|
+
npm run sync:universal
|
|
488
|
+
|
|
489
|
+
# Comprimir memória antiga e recuperar espaço
|
|
490
|
+
npm run memory:compress
|
|
480
491
|
npm run memory:vacuum
|
|
481
492
|
|
|
482
|
-
#
|
|
493
|
+
# Medir a economia
|
|
483
494
|
npm run token:benchmark
|
|
484
495
|
|
|
485
|
-
#
|
|
486
|
-
npm run
|
|
487
|
-
|
|
488
|
-
# Query memory
|
|
489
|
-
npm run memory:db:query -- "auth"
|
|
496
|
+
# Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
|
|
497
|
+
npm run tools:doctor
|
|
490
498
|
```
|
|
491
499
|
|
|
492
500
|
---
|
|
493
501
|
|
|
494
|
-
**
|
|
502
|
+
**Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/checks.mjs — o runner de checks. Sem opinião sobre o que se checa.
|
|
3
|
+
*
|
|
4
|
+
* Máquina compartilhada por dois catálogos, cada um guardando uma fronteira:
|
|
5
|
+
*
|
|
6
|
+
* health.mjs o núcleo — o que impede o framework de trabalhar aqui (SPEC-009, ADR-0023)
|
|
7
|
+
* release.mjs o tarball — o que impede o pacote de funcionar na máquina de quem instala (SPEC-010)
|
|
8
|
+
*
|
|
9
|
+
* O runner foi extraído, e não copiado, de propósito: duas máquinas iguais divergem com o tempo, e
|
|
10
|
+
* divergência entre superfícies que deveriam concordar é exatamente o defeito que a SPEC-009
|
|
11
|
+
* existiu para matar (o doctor e o hook diziam coisas diferentes sobre a mesma memória).
|
|
12
|
+
*
|
|
13
|
+
* Dois princípios, que valem para qualquer check novo em qualquer catálogo:
|
|
14
|
+
*
|
|
15
|
+
* 1. **Nunca colapsar causas distintas num booleano.** Um probe classifica a causa e devolve a
|
|
16
|
+
* correção *dela*. O bug que originou tudo isso era um `catch { return null }` que engolia três
|
|
17
|
+
* causas e prescrevia a correção de uma.
|
|
18
|
+
* 2. **Uma causa, uma linha vermelha.** Check cuja dependência falhou é `skipped`, não `fail` —
|
|
19
|
+
* senão uma raiz vira três erros vermelhos e o operador não sabe qual perseguir.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
/** @typedef {'critical'|'warn'} Severity */
|
|
23
|
+
/** @typedef {'runtime'|'repo'} Scope */
|
|
24
|
+
/** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @typedef {object} Check
|
|
28
|
+
* @property {string} id
|
|
29
|
+
* @property {string} title
|
|
30
|
+
* @property {Severity} severity `critical` trava o gate; `warn` informa.
|
|
31
|
+
* @property {Scope=} scope Filtro opcional do runner.
|
|
32
|
+
* @property {string=} dependsOn Id de outro check. Se ele não passar, este vira `skipped`.
|
|
33
|
+
* @property {(env: object) => Promise<Probe>|Probe} probe
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* @typedef {object} Probe
|
|
38
|
+
* @property {Status} status
|
|
39
|
+
* @property {string} detail O que foi observado, em uma linha.
|
|
40
|
+
* @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/** @typedef {{ id, title, severity: Severity, scope: Scope, status: Status, detail: string, fix: string|null }} Result */
|
|
44
|
+
|
|
45
|
+
const SEVERITY_FALLBACK = 'critical';
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Um probe que estoura é pior que probe nenhum: derrubaria o diagnóstico justamente no ambiente
|
|
49
|
+
* quebrado que ele existe para diagnosticar. O runner blinda cada um e segue para o próximo.
|
|
50
|
+
*/
|
|
51
|
+
async function runProbe(check, env) {
|
|
52
|
+
try {
|
|
53
|
+
const probe = await check.probe(env);
|
|
54
|
+
return {
|
|
55
|
+
status: probe.status,
|
|
56
|
+
detail: probe.detail,
|
|
57
|
+
fix: probe.fix ?? null,
|
|
58
|
+
};
|
|
59
|
+
} catch (err) {
|
|
60
|
+
return {
|
|
61
|
+
status: 'fail',
|
|
62
|
+
detail: `probe falhou: ${err?.message || err}`,
|
|
63
|
+
fix: null,
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Executa os checks na ordem declarada.
|
|
70
|
+
*
|
|
71
|
+
* @param {{ checks: Check[], scope?: Scope|'all', env?: object }} opts
|
|
72
|
+
* @returns {Promise<Result[]>}
|
|
73
|
+
*/
|
|
74
|
+
export async function runChecks({ checks, scope = 'all', env = {} }) {
|
|
75
|
+
const selected = checks.filter((c) => scope === 'all' || c.scope === scope);
|
|
76
|
+
const statusById = new Map();
|
|
77
|
+
const results = [];
|
|
78
|
+
|
|
79
|
+
for (const check of selected) {
|
|
80
|
+
const base = {
|
|
81
|
+
id: check.id,
|
|
82
|
+
title: check.title,
|
|
83
|
+
severity: check.severity || SEVERITY_FALLBACK,
|
|
84
|
+
scope: check.scope,
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
// Cascata: sem a dependência de pé, este probe não tem o que observar. Propaga por cadeia, não
|
|
88
|
+
// só um nível — `skipped` conta como "não verificado" para quem depende dele.
|
|
89
|
+
const depStatus = check.dependsOn ? statusById.get(check.dependsOn) : null;
|
|
90
|
+
if (depStatus === 'fail' || depStatus === 'skipped') {
|
|
91
|
+
const motivo = depStatus === 'fail' ? 'que falhou' : 'que não foi verificado';
|
|
92
|
+
results.push({
|
|
93
|
+
...base,
|
|
94
|
+
status: 'skipped',
|
|
95
|
+
detail: `não verificado: depende de "${check.dependsOn}", ${motivo}`,
|
|
96
|
+
fix: null,
|
|
97
|
+
});
|
|
98
|
+
statusById.set(check.id, 'skipped');
|
|
99
|
+
continue;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const probe = await runProbe(check, env);
|
|
103
|
+
statusById.set(check.id, probe.status);
|
|
104
|
+
results.push({ ...base, ...probe });
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
return results;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
|
|
112
|
+
* é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
|
|
113
|
+
*
|
|
114
|
+
* @param {Result[]} results
|
|
115
|
+
* @returns {'ok'|'warn'|'fail'}
|
|
116
|
+
*/
|
|
117
|
+
export function worstStatus(results) {
|
|
118
|
+
let seenWarn = false;
|
|
119
|
+
|
|
120
|
+
for (const r of results) {
|
|
121
|
+
if (r.status === 'fail' && r.severity === 'critical') return 'fail';
|
|
122
|
+
if (r.status === 'fail' || r.status === 'warn') seenWarn = true;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
return seenWarn ? 'warn' : 'ok';
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Remove template literals do fonte antes de qualquer análise estática de `import`.
|
|
130
|
+
*
|
|
131
|
+
* Os geradores do Forja *escrevem* código NestJS dentro de crases — `import { Module } from
|
|
132
|
+
* '@nestjs/common'` é texto que eles emitem, não dependência que eles usam. Contá-lo faz o check
|
|
133
|
+
* acusar `@nestjs/core` como dependência não declarada e `./app.module` como import quebrado.
|
|
134
|
+
* Observado em campo ao auditar o tarball da 1.1.3.
|
|
135
|
+
*/
|
|
136
|
+
export function stripTemplateLiterals(source) {
|
|
137
|
+
return source.replace(/`(?:\\.|[^`\\])*`/gs, '``');
|
|
138
|
+
}
|