forjajs 1.1.0 → 1.1.1
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/release-auditor.md +64 -0
- package/.claude/settings.json +35 -0
- package/.claude/skills/new-adr/SKILL.md +61 -0
- package/.claude/skills/new-command/SKILL.md +67 -0
- package/README.md +9 -0
- package/memory/90-decisions/0021-guardrails-de-harness.md +107 -0
- package/package.json +6 -3
- package/scripts/hook-guard-paths.mjs +75 -0
- package/scripts/hook-post-edit.mjs +79 -0
- package/scripts/hook-session-start.mjs +51 -7
- package/scripts/sync-universal-memory.js +12 -4
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release-auditor
|
|
3
|
+
description: Use ANTES de publicar no npm. Simula uma instalação limpa do tarball e valida que o files[] do package.json cobre tudo que os binários importam. Pega quebras que só apareceriam na máquina do usuário.
|
|
4
|
+
tools: Read, Bash, Grep
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é
|
|
8
|
+
responder a uma única pergunta com evidência: **o pacote funciona na máquina de quem
|
|
9
|
+
instala?**
|
|
10
|
+
|
|
11
|
+
O repositório mente sobre isso. No repo, tudo resolve: `node_modules` existe com devDeps,
|
|
12
|
+
todos os arquivos estão presentes, o `cwd` é a raiz do projeto. Nada disso vale para quem
|
|
13
|
+
roda `npm i -g forjajs`. Duas classes de bug vivem exatamente nessa lacuna e só aparecem
|
|
14
|
+
em produção:
|
|
15
|
+
|
|
16
|
+
1. **Arquivo fora do `files[]`** — o `package.json` lista os paths publicados à mão. Um
|
|
17
|
+
`import` para um arquivo não listado quebra só depois do publish.
|
|
18
|
+
2. **Dependência de runtime declarada como `devDependency`** — não é instalada pelo
|
|
19
|
+
usuário. O comando estoura com `ERR_MODULE_NOT_FOUND`.
|
|
20
|
+
|
|
21
|
+
Grep e leitura de código não provam ausência dessas falhas. Instalação prova.
|
|
22
|
+
|
|
23
|
+
## Procedimento
|
|
24
|
+
|
|
25
|
+
1. **Empacote e instale de verdade**, num diretório temporário fora do repo:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm pack --pack-destination /tmp/forja-audit
|
|
29
|
+
cd /tmp/forja-audit && npm init -y && npm i ./forjajs-<versão>.tgz
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
2. **Exercite cada comando do registry**, não só o help. O help não carrega os scripts —
|
|
33
|
+
passa mesmo com tudo quebrado. Enumere os comandos e rode os que não têm efeito
|
|
34
|
+
colateral (leitura, status, query):
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npx forja # lista os comandos
|
|
38
|
+
npx forja query:universal teste
|
|
39
|
+
npx forja code:status
|
|
40
|
+
npx forja tools:doctor
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Um `ERR_MODULE_NOT_FOUND` aqui é reprovação imediata.
|
|
44
|
+
|
|
45
|
+
3. **Cruze imports contra `files[]`.** Para cada binário em `bin/`, siga os imports
|
|
46
|
+
transitivamente e confirme que todo path resolvido cai sob um prefixo listado em
|
|
47
|
+
`files[]`. Reporte os que não caem.
|
|
48
|
+
|
|
49
|
+
4. **Confira a fronteira deps/devDeps.** Todo pacote importado por código sob `files[]`
|
|
50
|
+
precisa estar em `dependencies`. `devDependencies` só pode ser importado por `test/`
|
|
51
|
+
e por scripts que não são publicados.
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
grep -rn "from 'better-sqlite3'\|require('better-sqlite3')" bin/ lib/ scripts/
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Regras
|
|
58
|
+
|
|
59
|
+
- Output estruturado: ✓ aprovado / ✗ reprovado, com motivos numerados.
|
|
60
|
+
- Nunca rode `npm publish`. Você audita; publicar é decisão do usuário.
|
|
61
|
+
- Nunca aprove com base em leitura de código. Se você não instalou o tarball e rodou
|
|
62
|
+
um comando real, você não sabe — diga que não sabe.
|
|
63
|
+
- Limpe `/tmp/forja-audit` ao final.
|
|
64
|
+
- Se reprovar, aponte a linha exata: o import ofensor ou a entrada faltante no `files[]`.
|
package/.claude/settings.json
CHANGED
|
@@ -22,10 +22,35 @@
|
|
|
22
22
|
}
|
|
23
23
|
]
|
|
24
24
|
}
|
|
25
|
+
],
|
|
26
|
+
"PreToolUse": [
|
|
27
|
+
{
|
|
28
|
+
"matcher": "Edit|Write|NotebookEdit",
|
|
29
|
+
"hooks": [
|
|
30
|
+
{
|
|
31
|
+
"type": "command",
|
|
32
|
+
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-guard-paths.mjs",
|
|
33
|
+
"timeout": 5000
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
}
|
|
37
|
+
],
|
|
38
|
+
"PostToolUse": [
|
|
39
|
+
{
|
|
40
|
+
"matcher": "Edit|Write",
|
|
41
|
+
"hooks": [
|
|
42
|
+
{
|
|
43
|
+
"type": "command",
|
|
44
|
+
"command": "node $CLAUDE_PROJECT_DIR/scripts/hook-post-edit.mjs",
|
|
45
|
+
"timeout": 60000
|
|
46
|
+
}
|
|
47
|
+
]
|
|
48
|
+
}
|
|
25
49
|
]
|
|
26
50
|
},
|
|
27
51
|
"permissions": {
|
|
28
52
|
"allow": [
|
|
53
|
+
"Bash(node bin/forja.mjs *)",
|
|
29
54
|
"Bash(node scripts/spec-cli.mjs *)",
|
|
30
55
|
"Bash(node scripts/agent-router.mjs *)",
|
|
31
56
|
"Bash(npm run spec:*)",
|
|
@@ -33,6 +58,16 @@
|
|
|
33
58
|
"Bash(npm run sprint:*)",
|
|
34
59
|
"Bash(npm run project:*)",
|
|
35
60
|
"Bash(npm run context:*)",
|
|
61
|
+
"Bash(npm run code:*)",
|
|
62
|
+
"Bash(npm run design:*)",
|
|
63
|
+
"Bash(npm run gsd:*)",
|
|
64
|
+
"Bash(npm run ops:*)",
|
|
65
|
+
"Bash(npm run agent:*)",
|
|
66
|
+
"Bash(npm run catalog:*)",
|
|
67
|
+
"Bash(npm run workspace:*)",
|
|
68
|
+
"Bash(npm run hermes:handoff *)",
|
|
69
|
+
"Bash(npm run token:benchmark)",
|
|
70
|
+
"Bash(npm run tools:doctor)",
|
|
36
71
|
"Bash(npm run sync:universal)",
|
|
37
72
|
"Bash(npm run query:universal *)",
|
|
38
73
|
"Bash(npm test)"
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: new-adr
|
|
3
|
+
description: Cria um ADR numerado em memory/90-decisions/ a partir do _template.md, preenchendo contexto, decisão, alternativas e consequências.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Novo ADR
|
|
8
|
+
|
|
9
|
+
Registra uma decisão arquitetural em `memory/90-decisions/NNNN-titulo.md`.
|
|
10
|
+
|
|
11
|
+
Um ADR existe para preservar o **rationale**, não o resultado. O código já diz o que
|
|
12
|
+
foi feito; só o ADR diz por que as alternativas foram rejeitadas. Se não há alternativa
|
|
13
|
+
rejeitada, provavelmente não há decisão — e não há ADR a escrever.
|
|
14
|
+
|
|
15
|
+
## Quando usar
|
|
16
|
+
|
|
17
|
+
Toda mudança estrutural: novo comando no core, mudança de contrato entre agentes,
|
|
18
|
+
troca de armazenamento, nova convenção de memória. O subagent `governance` reprova
|
|
19
|
+
merge de mudança estrutural sem ADR.
|
|
20
|
+
|
|
21
|
+
## Passos
|
|
22
|
+
|
|
23
|
+
1. **Descobrir o próximo número.** Nunca reutilize nem adivinhe:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
ls memory/90-decisions/ | grep -E '^[0-9]{4}-' | sort | tail -1
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
O próximo é esse + 1, com zero-padding em 4 dígitos.
|
|
30
|
+
|
|
31
|
+
2. **Verificar se já existe ADR sobre o tema.** Uma decisão que revisa outra não
|
|
32
|
+
ganha ADR novo do zero — ela *supersedes* a anterior:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm run query:universal "<tema da decisão>"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Se encontrar, o ADR novo declara `superseded by` no antigo e o antigo passa a
|
|
39
|
+
`Status: superseded by ADR-NNNN`.
|
|
40
|
+
|
|
41
|
+
3. **Copiar o template** `memory/90-decisions/_template.md` para o novo caminho.
|
|
42
|
+
O slug do arquivo é o título em kebab-case, sem artigos: `0021-guardrails-de-harness.md`.
|
|
43
|
+
|
|
44
|
+
4. **Preencher.** Regras que importam:
|
|
45
|
+
- `Status`: `proposed` até haver merge; `accepted` depois.
|
|
46
|
+
- `Contexto`: o problema e as restrições. Sem solução aqui.
|
|
47
|
+
- `Decisão`: no imperativo, direto. "Adotar X", não "decidimos que talvez X".
|
|
48
|
+
- `Alternativas consideradas`: no mínimo uma, com o motivo real da rejeição.
|
|
49
|
+
"Rejeitada porque é pior" não é motivo.
|
|
50
|
+
- `Consequências`: inclua os trade-offs negativos. Um ADR só com positivas mente.
|
|
51
|
+
- `Rastreamento`: paths reais de implementação.
|
|
52
|
+
|
|
53
|
+
5. **Reindexar a memória**, senão o ADR fica invisível para `query:universal`:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npm run sync:universal
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
6. **Referenciar de volta.** Se o ADR muda uma convenção descrita no `CLAUDE.md`
|
|
60
|
+
ou no `AGENTS.md`, atualize esses arquivos no mesmo commit. Documentação que
|
|
61
|
+
contradiz o ADR é pior que documentação ausente.
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: new-command
|
|
3
|
+
description: Adiciona um comando ao core Forja (registry + alias npm + script + teste), respeitando a invariante do ADR-0020.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Novo comando do core
|
|
8
|
+
|
|
9
|
+
O ADR-0020 estabelece uma invariante: **todo comando de processo passa por
|
|
10
|
+
`bin/forja.mjs`**. Não existe script solto. Adicionar um comando é um ato de quatro
|
|
11
|
+
partes acopladas — esquecer qualquer uma quebra `test/forja-core.test.js`.
|
|
12
|
+
|
|
13
|
+
## As quatro partes
|
|
14
|
+
|
|
15
|
+
| Parte | Onde | Por quê |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| Entrada no registry | `lib/core/registry.mjs` | É a fonte da verdade: help, gates e auditoria derivam dela |
|
|
18
|
+
| Script alvo | `scripts/<nome>.mjs` | O trabalho de fato |
|
|
19
|
+
| Alias npm | `package.json` → `scripts` | Ergonomia; deve delegar ao core, nunca ao script direto |
|
|
20
|
+
| Teste | `test/forja-core.test.js` | Já cobre integridade automaticamente — só precisa passar |
|
|
21
|
+
|
|
22
|
+
## Passos
|
|
23
|
+
|
|
24
|
+
1. **Escolher o domínio.** Os válidos estão em `DOMAINS` no topo de
|
|
25
|
+
`lib/core/registry.mjs`: `workspace`, `sdd`, `gsd`, `design`, `code`, `memoria`,
|
|
26
|
+
`contexto`, `governanca`, `geracao`. Um domínio novo é mudança estrutural — peça
|
|
27
|
+
um ADR primeiro (skill `new-adr`).
|
|
28
|
+
|
|
29
|
+
2. **Escrever o script** em `scripts/`. ESM, imports com prefixo `node:`, cabeçalho
|
|
30
|
+
comentando o *porquê* do script. Ele recebe os args depois de `args[]`.
|
|
31
|
+
|
|
32
|
+
3. **Declarar no registry**, em ordem, dentro do bloco do domínio:
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
'dominio:acao': {
|
|
36
|
+
domain: 'memoria',
|
|
37
|
+
desc: 'Frase curta no infinitivo, aparece no help',
|
|
38
|
+
node: 'scripts/meu-script.mjs',
|
|
39
|
+
args: ['subcomando'], // opcional: args fixos antes dos do usuário
|
|
40
|
+
gate: 'workspace', // opcional: 'workspace' | 'workspace-warn'
|
|
41
|
+
},
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Use `gate: 'workspace'` se o comando escreve no workspace externo (ADR-0019);
|
|
45
|
+
`workspace-warn` se apenas lê.
|
|
46
|
+
|
|
47
|
+
4. **Adicionar o alias** em `package.json`. Ele delega ao core, nunca ao script:
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
"dominio:acao": "node bin/forja.mjs dominio:acao"
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Chamar `node scripts/meu-script.mjs` direto pula os gates e a auditoria em
|
|
54
|
+
`.context/forja-runs.jsonl` — é exatamente o que o ADR-0020 proíbe.
|
|
55
|
+
|
|
56
|
+
5. **Verificar.** O hook `PostToolUse` já dispara o teste ao salvar o registry, mas
|
|
57
|
+
confirme o conjunto e o help:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
node --test test/forja-core.test.js
|
|
61
|
+
node bin/forja.mjs # o comando deve aparecer sob seu domínio
|
|
62
|
+
node bin/forja.mjs dominio:acao # execução real
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
6. **Permissão.** Se o comando será chamado por agentes, acrescente
|
|
66
|
+
`Bash(npm run dominio:*)` em `.claude/settings.json` → `permissions.allow`,
|
|
67
|
+
senão cada chamada vira um prompt.
|
package/README.md
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
+
<a href="https://www.npmjs.com/package/forjajs"><img src="https://img.shields.io/npm/v/forjajs?style=flat-square&color=cb3837&logo=npm" alt="npm"></a>
|
|
8
9
|
<img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
|
|
9
10
|
<img src="https://img.shields.io/badge/operação-CLI--first-3553ff?style=flat-square" alt="CLI-first">
|
|
10
11
|
<img src="https://img.shields.io/badge/agentes-6_papéis-orange?style=flat-square" alt="6 agentes">
|
|
@@ -85,6 +86,14 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
85
86
|
|
|
86
87
|
## ⚡ Quick start
|
|
87
88
|
|
|
89
|
+
```bash
|
|
90
|
+
# Instalar (o pacote é forjajs; o comando é forja)
|
|
91
|
+
npm install -g forjajs
|
|
92
|
+
forja # help agrupado por domínio
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Ou clonando o repo:
|
|
96
|
+
|
|
88
97
|
```bash
|
|
89
98
|
# Preparar o workspace de produção (canto fixo dos projetos)
|
|
90
99
|
npm run workspace:init
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# ADR-0021: Guardrails de harness e dependência de runtime explícita
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-09
|
|
5
|
+
- **Autor(es)**: Allan Pablo
|
|
6
|
+
- **Tags**: harness, hooks, npm, memory, governance
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Três falhas silenciosas foram encontradas com o framework já publicado como `forjajs` no npm.
|
|
11
|
+
As três compartilham a mesma natureza: **erram sem avisar**. Nenhuma quebrava um teste,
|
|
12
|
+
nenhuma aparecia no `git status`, e todas produziam trabalho errado com aparência de trabalho certo.
|
|
13
|
+
|
|
14
|
+
1. **`.mcp.json` com path absoluto obsoleto.** O codegraph era iniciado com
|
|
15
|
+
`-p /home/apk/.../2-Projeto-Agents/projects/forja`, uma cópia parada no commit `282c265`
|
|
16
|
+
(anterior ao ADR-0020). Consequência: `bin/forja.mjs` e `lib/core/` — o core inteiro que o
|
|
17
|
+
`CLAUDE.md` manda todo agente usar — eram invisíveis ao índice. Qualquer `codegraph_explore`
|
|
18
|
+
respondia sobre código morto, com confiança. O path também era versionado, quebrando para
|
|
19
|
+
qualquer outro contribuidor.
|
|
20
|
+
|
|
21
|
+
2. **`better-sqlite3` como `devDependency`.** Dez scripts sob `files[]` a importam
|
|
22
|
+
estaticamente, e o pacote declarava zero `dependencies`. Numa instalação limpa
|
|
23
|
+
(`npm i -g forjajs`), `query:universal`, `sync:universal`, `context:smart`, `agent:route`,
|
|
24
|
+
`memory:compress` e `project:dashboard` estouravam com `ERR_MODULE_NOT_FOUND`. O `forja`
|
|
25
|
+
sem argumentos funcionava — o help não carrega os scripts — o que mascarava a quebra.
|
|
26
|
+
|
|
27
|
+
3. **Regras de repositório existiam só como prosa.** `projects/` é declarado off-limits no
|
|
28
|
+
`CLAUDE.md`, e a invariante do ADR-0020 ("comando novo = entrada no registry") era validada
|
|
29
|
+
apenas no pre-commit via lefthook, que é opt-in. Ambas dependiam de a IA lembrar. Uma regra
|
|
30
|
+
que depende de memória não é uma regra; é uma sugestão.
|
|
31
|
+
|
|
32
|
+
4. **Índice FTS5 cruzado com o conteúdo errado.** `sync-universal-memory.js` obtinha o id do nó
|
|
33
|
+
recém-gravado via `result.lastInsertRowid || SELECT id ...`. Num `INSERT ... ON CONFLICT DO
|
|
34
|
+
UPDATE` que *atualiza*, o SQLite não redefine `lastInsertRowid` — mantém o id do último INSERT
|
|
35
|
+
da conexão. Sendo truthy, o fallback nunca disparava. Toda execução com um insert seguido de
|
|
36
|
+
updates gravava o conteúdo de um documento sob o `node_id` de outro. Efeito medido: o ADR-0021
|
|
37
|
+
indexado com o corpo de "Harnesses: Hermes e GSD"; `query:universal "registry"` não encontrava
|
|
38
|
+
o ADR-0020; 135 linhas órfãs acumuladas. Como `query:universal` é o **primeiro passo** da
|
|
39
|
+
economia de tokens do ADR-0009, o framework vinha alimentando os agentes com o documento
|
|
40
|
+
errado — sem erro, sem log, sem sintoma.
|
|
41
|
+
|
|
42
|
+
## Decisão
|
|
43
|
+
|
|
44
|
+
Mover a aplicação das regras do texto para o harness, e a verificação da publicação da leitura
|
|
45
|
+
para a execução.
|
|
46
|
+
|
|
47
|
+
- **`.mcp.json` sem `-p`.** Em modo MCP o codegraph resolve o projeto pelo `rootUri` do cliente.
|
|
48
|
+
Remover o path elimina a classe inteira de erro em vez de corrigir uma instância.
|
|
49
|
+
- **`better-sqlite3` em `dependencies`.** É dependência de runtime; era só declaração errada.
|
|
50
|
+
- **`PreToolUse` → `scripts/hook-guard-paths.mjs`.** Bloqueia escrita em `projects/` e
|
|
51
|
+
`docs/archive/` com exit 2, devolvendo o motivo e a alternativa. Falha aberta.
|
|
52
|
+
- **`PostToolUse` → `scripts/hook-post-edit.mjs`.** Ao editar `lib/core/registry.mjs` ou
|
|
53
|
+
`package.json`, roda `test/forja-core.test.js` na hora. A quebra chega junto da edição que
|
|
54
|
+
a causou, não commits depois.
|
|
55
|
+
- **`SessionStart` resiliente e honesto.** Todo acesso a SQLite passa a ser lazy — o hook
|
|
56
|
+
degradava para stack trace sem `node_modules`. Além disso, passa a avisar quando `memory/`
|
|
57
|
+
mudou depois do último `sync:universal`: índice defasado é a versão local do problema (1).
|
|
58
|
+
- **`RETURNING id` no upsert de `memory_nodes`.** Devolve a linha realmente afetada, inserida ou
|
|
59
|
+
atualizada, eliminando a dependência de `lastInsertRowid`. O sync passa a purgar linhas órfãs
|
|
60
|
+
do `search_idx` ao final, e o `title` volta a ser atualizado no conflito.
|
|
61
|
+
- **Subagent `release-auditor`.** Audita o pacote instalando o tarball de verdade e exercitando
|
|
62
|
+
comandos reais. Proibido aprovar por leitura de código.
|
|
63
|
+
- **Skills `new-adr` e `new-command`.** Os dois rituais do repo viram etapas executáveis.
|
|
64
|
+
|
|
65
|
+
## Alternativas consideradas
|
|
66
|
+
|
|
67
|
+
- **Path relativo (`-p .`) no `.mcp.json`** — rejeitada porque ainda depende do `cwd` do processo
|
|
68
|
+
do servidor, que não é contratual. Omitir a flag delega ao protocolo, que é.
|
|
69
|
+
- **`better-sqlite3` como `optionalDependency` com degradação** — rejeitada porque a memória
|
|
70
|
+
hierárquica com FTS5 é a proposta central do Forja, não um extra. Um `forjajs` sem memória
|
|
71
|
+
não é uma instalação degradada; é uma instalação errada.
|
|
72
|
+
- **Manter as regras no `CLAUDE.md` e confiar na leitura do agente** — rejeitada por evidência:
|
|
73
|
+
as regras já estavam escritas e ainda assim o índice ficou apontando para a árvore errada por
|
|
74
|
+
mais de uma semana.
|
|
75
|
+
- **Rodar a suíte inteira no `PostToolUse`** — rejeitada por custo. O gate é `forja-core.test.js`,
|
|
76
|
+
um arquivo, poucos segundos. Um hook lento é um hook que alguém desliga.
|
|
77
|
+
- **Reconstruir o `search_idx` do zero a cada sync** — rejeitada porque esconderia a causa. O
|
|
78
|
+
índice ficaria correto sem que o upsert deixasse de devolver o id errado, e o próximo consumidor
|
|
79
|
+
de `lastInsertRowid` reencontraria o mesmo bug.
|
|
80
|
+
|
|
81
|
+
## Consequências
|
|
82
|
+
|
|
83
|
+
**Positivas**:
|
|
84
|
+
- O pacote publicado passa a funcionar numa instalação limpa — verificado via `npm pack` + install.
|
|
85
|
+
- `query:universal` volta a devolver o documento que casou com a busca. Medido: 709 pares
|
|
86
|
+
título↔conteúdo alinhados, 0 cruzados, 0 órfãos (antes: 3 cruzados, 135 órfãos).
|
|
87
|
+
- Violações de `projects/` e do registry tornam-se impossíveis, não improváveis.
|
|
88
|
+
- O índice de memória defasado passa a se anunciar em vez de responder errado calado.
|
|
89
|
+
- Contribuidores externos clonam e o codegraph indexa o repo certo, sem editar nada.
|
|
90
|
+
|
|
91
|
+
**Negativas / Trade-offs**:
|
|
92
|
+
- `npm i forjajs` agora compila/baixa um módulo nativo (`better-sqlite3`): instalação mais lenta
|
|
93
|
+
e sujeita a prebuilds por plataforma. É o preço de o produto funcionar.
|
|
94
|
+
- O hook `PostToolUse` acrescenta poucos segundos a cada edição de `registry.mjs` ou `package.json`.
|
|
95
|
+
- Guardrails têm escape hatch (`FORJA_GUARD=0`, `FORJA_HOOK_TEST=0`). Um guard sem escape vira
|
|
96
|
+
um guard contornado por caminhos piores.
|
|
97
|
+
- `.claude/skills/` entra em `files[]`, aumentando o tarball.
|
|
98
|
+
|
|
99
|
+
## Rastreamento
|
|
100
|
+
- Implementação: `.mcp.json`, `package.json`, `.claude/settings.json`,
|
|
101
|
+
`scripts/sync-universal-memory.js`, `scripts/hook-guard-paths.mjs`, `scripts/hook-post-edit.mjs`,
|
|
102
|
+
`scripts/hook-session-start.mjs`, `.claude/agents/release-auditor.md`,
|
|
103
|
+
`.claude/skills/new-adr/`, `.claude/skills/new-command/`
|
|
104
|
+
- Testes: `test/hooks.test.js`, `test/memory-index.test.js`
|
|
105
|
+
- ADRs relacionadas: ADR-0009 (economia de tokens — a corrupção do FTS a invalidava na prática),
|
|
106
|
+
ADR-0017 (codegraph no harness), ADR-0018 (ferramentas de processo),
|
|
107
|
+
ADR-0019 (workspace separado), ADR-0020 (forja core CLI única)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forjajs",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.1",
|
|
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",
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
"docs/",
|
|
21
21
|
"specs/",
|
|
22
22
|
".claude/agents/",
|
|
23
|
+
".claude/skills/",
|
|
23
24
|
".claude/settings.json",
|
|
24
25
|
".gemini-instructions.md",
|
|
25
26
|
".openai-instructions.md",
|
|
@@ -101,7 +102,9 @@
|
|
|
101
102
|
},
|
|
102
103
|
"author": "Allan Pablo",
|
|
103
104
|
"license": "MIT",
|
|
104
|
-
"
|
|
105
|
-
"better-sqlite3": "^12.11.1"
|
|
105
|
+
"dependencies": {
|
|
106
|
+
"better-sqlite3": "^12.11.1",
|
|
107
|
+
"otplib": "^13.4.1",
|
|
108
|
+
"qrcode": "^1.5.4"
|
|
106
109
|
}
|
|
107
110
|
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Hook PreToolUse — guarda de caminhos protegidos (ADR-0021).
|
|
4
|
+
*
|
|
5
|
+
* O CLAUDE.md declara `projects/` off-limits e `docs/archive/` como material
|
|
6
|
+
* histórico congelado. Até aqui isso era prosa: valia enquanto a IA lembrasse.
|
|
7
|
+
* Este hook torna a regra determinística — a escrita é barrada antes de acontecer,
|
|
8
|
+
* não corrigida depois.
|
|
9
|
+
*
|
|
10
|
+
* Protocolo:
|
|
11
|
+
* - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
|
|
12
|
+
* - exit 0: liberado (silencioso)
|
|
13
|
+
* - exit 2: bloqueado — stderr volta para a IA como feedback acionável
|
|
14
|
+
*
|
|
15
|
+
* Escape hatch: FORJA_GUARD=0 desliga (útil para manutenção deliberada do archive).
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import path from 'node:path';
|
|
19
|
+
import process from 'node:process';
|
|
20
|
+
|
|
21
|
+
/** Cada regra explica o porquê: a IA recebe o motivo, não só a negativa. */
|
|
22
|
+
const PROTECTED = [
|
|
23
|
+
{
|
|
24
|
+
test: (rel) => rel === 'projects' || rel.startsWith('projects/'),
|
|
25
|
+
reason:
|
|
26
|
+
'projects/ é off-limits (CLAUDE.md): contém produtos em desenvolvimento ativo do usuário. ' +
|
|
27
|
+
'Aplicações reais vivem no workspace externo — use `npm run project:new` (ADR-0019).',
|
|
28
|
+
},
|
|
29
|
+
{
|
|
30
|
+
test: (rel) => rel.startsWith('docs/archive/'),
|
|
31
|
+
reason:
|
|
32
|
+
'docs/archive/ é material histórico congelado (ex.: legacy-bin/, mantido só para referência). ' +
|
|
33
|
+
'Se a mudança é real, ela pertence ao código vivo em bin/ ou lib/.',
|
|
34
|
+
},
|
|
35
|
+
];
|
|
36
|
+
|
|
37
|
+
function readStdin() {
|
|
38
|
+
return new Promise((resolve) => {
|
|
39
|
+
let data = '';
|
|
40
|
+
process.stdin.setEncoding('utf8');
|
|
41
|
+
process.stdin.on('data', (c) => { data += c; });
|
|
42
|
+
process.stdin.on('end', () => resolve(data));
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Falha aberta: um guard quebrado não pode travar a sessão inteira. */
|
|
47
|
+
function allow() { process.exit(0); }
|
|
48
|
+
|
|
49
|
+
(async function main() {
|
|
50
|
+
if (process.env.FORJA_GUARD === '0') allow();
|
|
51
|
+
|
|
52
|
+
let payload;
|
|
53
|
+
try {
|
|
54
|
+
payload = JSON.parse(await readStdin());
|
|
55
|
+
} catch {
|
|
56
|
+
allow();
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const filePath = payload?.tool_input?.file_path;
|
|
60
|
+
if (typeof filePath !== 'string' || !filePath) allow();
|
|
61
|
+
|
|
62
|
+
const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
|
|
63
|
+
const abs = path.resolve(root, filePath);
|
|
64
|
+
const rel = path.relative(root, abs);
|
|
65
|
+
|
|
66
|
+
// Fora do repo: não é competência deste guard.
|
|
67
|
+
if (rel.startsWith('..') || path.isAbsolute(rel)) allow();
|
|
68
|
+
|
|
69
|
+
const relPosix = rel.split(path.sep).join('/');
|
|
70
|
+
const hit = PROTECTED.find((rule) => rule.test(relPosix));
|
|
71
|
+
if (!hit) allow();
|
|
72
|
+
|
|
73
|
+
process.stderr.write(`Escrita bloqueada em \`${relPosix}\`.\n\n${hit.reason}\n`);
|
|
74
|
+
process.exit(2);
|
|
75
|
+
})();
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Hook PostToolUse — fecha o loop do registry (ADR-0021).
|
|
4
|
+
*
|
|
5
|
+
* ADR-0020 estabelece a invariante: "comando novo = entrada nova no registry".
|
|
6
|
+
* `test/forja-core.test.js` valida isso, mas só rodava no pre-commit — e o
|
|
7
|
+
* lefthook é opt-in, então na prática podia nunca rodar. Resultado: a quebra
|
|
8
|
+
* aparecia minutos ou commits depois, longe da edição que a causou.
|
|
9
|
+
*
|
|
10
|
+
* Aqui o teste roda no instante em que o registry (ou o package.json que o
|
|
11
|
+
* espelha) é tocado. Custo: um único arquivo de teste, poucos segundos.
|
|
12
|
+
*
|
|
13
|
+
* Protocolo:
|
|
14
|
+
* - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
|
|
15
|
+
* - exit 0: nada a fazer, ou teste passou (silencioso)
|
|
16
|
+
* - exit 2: teste falhou — stderr volta para a IA, que corrige antes de seguir
|
|
17
|
+
*
|
|
18
|
+
* Escape hatch: FORJA_HOOK_TEST=0 desliga.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import path from 'node:path';
|
|
22
|
+
import process from 'node:process';
|
|
23
|
+
import { spawnSync } from 'node:child_process';
|
|
24
|
+
|
|
25
|
+
/** Arquivos cuja edição invalida a integridade do core. */
|
|
26
|
+
const WATCHED = ['lib/core/registry.mjs', 'package.json'];
|
|
27
|
+
const SUITE = 'test/forja-core.test.js';
|
|
28
|
+
|
|
29
|
+
function readStdin() {
|
|
30
|
+
return new Promise((resolve) => {
|
|
31
|
+
let data = '';
|
|
32
|
+
process.stdin.setEncoding('utf8');
|
|
33
|
+
process.stdin.on('data', (c) => { data += c; });
|
|
34
|
+
process.stdin.on('end', () => resolve(data));
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function skip() { process.exit(0); }
|
|
39
|
+
|
|
40
|
+
(async function main() {
|
|
41
|
+
if (process.env.FORJA_HOOK_TEST === '0') skip();
|
|
42
|
+
|
|
43
|
+
let payload;
|
|
44
|
+
try {
|
|
45
|
+
payload = JSON.parse(await readStdin());
|
|
46
|
+
} catch {
|
|
47
|
+
skip();
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const filePath = payload?.tool_input?.file_path;
|
|
51
|
+
if (typeof filePath !== 'string' || !filePath) skip();
|
|
52
|
+
|
|
53
|
+
const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
|
|
54
|
+
const rel = path.relative(root, path.resolve(root, filePath)).split(path.sep).join('/');
|
|
55
|
+
if (!WATCHED.includes(rel)) skip();
|
|
56
|
+
|
|
57
|
+
const res = spawnSync(process.execPath, ['--test', SUITE], {
|
|
58
|
+
cwd: root,
|
|
59
|
+
encoding: 'utf8',
|
|
60
|
+
// Evita recursão: o teste roda `bin/forja.mjs`, que não deve reentrar no hook.
|
|
61
|
+
env: { ...process.env, FORJA_HOOK_TEST: '0' },
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
if (res.status === 0) skip();
|
|
65
|
+
|
|
66
|
+
const detail = (res.stdout || '') + (res.stderr || '');
|
|
67
|
+
const failures = detail
|
|
68
|
+
.split('\n')
|
|
69
|
+
.filter((l) => /^not ok |^\s+error:|AssertionError/.test(l))
|
|
70
|
+
.slice(0, 12)
|
|
71
|
+
.join('\n');
|
|
72
|
+
|
|
73
|
+
process.stderr.write(
|
|
74
|
+
`\`${rel}\` foi editado e \`${SUITE}\` quebrou — a integridade do registry (ADR-0020) está violada.\n\n` +
|
|
75
|
+
`${failures || detail.slice(-1500)}\n\n` +
|
|
76
|
+
`Um comando novo precisa de: entrada em lib/core/registry.mjs + alias em package.json + script existente.\n`
|
|
77
|
+
);
|
|
78
|
+
process.exit(2);
|
|
79
|
+
})();
|
|
@@ -4,12 +4,15 @@
|
|
|
4
4
|
*
|
|
5
5
|
* Roda uma vez por sessão. Lê specs em aberto + handoffs pendentes do universal.db.
|
|
6
6
|
* Output vai para additionalContext (carregado pelo Claude no system).
|
|
7
|
+
*
|
|
8
|
+
* Regra de ouro: este hook nunca pode derrubar a sessão. Todo acesso a SQLite é
|
|
9
|
+
* lazy e envolto em try/catch — sem `node_modules`, degrada para o modo só-specs
|
|
10
|
+
* em vez de abortar (ADR-0021).
|
|
7
11
|
*/
|
|
8
12
|
|
|
9
13
|
import fs from 'node:fs';
|
|
10
14
|
import path from 'node:path';
|
|
11
15
|
import { fileURLToPath } from 'node:url';
|
|
12
|
-
import { getDbPath, ensureSchema } from './memory-schema.mjs';
|
|
13
16
|
|
|
14
17
|
const __filename = fileURLToPath(import.meta.url);
|
|
15
18
|
const __dirname = path.dirname(__filename);
|
|
@@ -31,10 +34,18 @@ function listSpecs() {
|
|
|
31
34
|
return out;
|
|
32
35
|
}
|
|
33
36
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
37
|
+
/** Lazy: sem better-sqlite3 instalado, devolve null em vez de estourar. */
|
|
38
|
+
async function resolveDbPath() {
|
|
39
|
+
try {
|
|
40
|
+
const { getDbPath, ensureSchema } = await import('./memory-schema.mjs');
|
|
41
|
+
ensureSchema({ silent: true });
|
|
42
|
+
const dbPath = getDbPath();
|
|
43
|
+
return fs.existsSync(dbPath) ? dbPath : null;
|
|
44
|
+
} catch { return null; }
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
async function openHandoffs(dbPath) {
|
|
48
|
+
if (!dbPath) return [];
|
|
38
49
|
try {
|
|
39
50
|
const { default: Database } = await import('better-sqlite3');
|
|
40
51
|
const db = new Database(dbPath, { readonly: true });
|
|
@@ -44,11 +55,44 @@ async function openHandoffs() {
|
|
|
44
55
|
} catch { return []; }
|
|
45
56
|
}
|
|
46
57
|
|
|
58
|
+
/** mtime do arquivo .md mais recente sob memory/, ignorando o que é arquivado. */
|
|
59
|
+
function newestMemoryMtime(dir = path.join(root, 'memory'), acc = { t: 0 }) {
|
|
60
|
+
for (const entry of safeReadDir(dir)) {
|
|
61
|
+
if (entry.startsWith('.') || entry === 'archive') continue;
|
|
62
|
+
const p = path.join(dir, entry);
|
|
63
|
+
let st;
|
|
64
|
+
try { st = fs.statSync(p); } catch { continue; }
|
|
65
|
+
if (st.isDirectory()) newestMemoryMtime(p, acc);
|
|
66
|
+
else if (entry.endsWith('.md') && st.mtimeMs > acc.t) acc.t = st.mtimeMs;
|
|
67
|
+
}
|
|
68
|
+
return acc.t;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Índice defasado = `query:universal` responde sobre memória velha, calado.
|
|
73
|
+
* É a falha mais cara do framework: erra sem avisar. Então avisamos.
|
|
74
|
+
*/
|
|
75
|
+
function staleIndex(dbPath) {
|
|
76
|
+
if (!dbPath) return false;
|
|
77
|
+
try {
|
|
78
|
+
const dbMtime = fs.statSync(dbPath).mtimeMs;
|
|
79
|
+
return newestMemoryMtime() > dbMtime;
|
|
80
|
+
} catch { return false; }
|
|
81
|
+
}
|
|
82
|
+
|
|
47
83
|
(async function main() {
|
|
48
84
|
const specs = listSpecs();
|
|
49
|
-
const
|
|
85
|
+
const dbPath = await resolveDbPath();
|
|
86
|
+
const handoffs = await openHandoffs(dbPath);
|
|
50
87
|
const lines = ['<framework-status>'];
|
|
51
|
-
lines.push(`Framework:
|
|
88
|
+
lines.push(`Framework: forja (SDD + orquestração)`);
|
|
89
|
+
|
|
90
|
+
if (!dbPath) {
|
|
91
|
+
lines.push('\n⚠ Memória indisponível: universal.db não abriu. Rode `npm install` e `npm run sync:universal`.');
|
|
92
|
+
} else if (staleIndex(dbPath)) {
|
|
93
|
+
lines.push('\n⚠ Índice defasado: memory/ mudou depois do último sync. `query:universal` vai responder sobre memória velha — rode `npm run sync:universal`.');
|
|
94
|
+
}
|
|
95
|
+
|
|
52
96
|
if (specs.length) {
|
|
53
97
|
lines.push('\nSpecs ativas:');
|
|
54
98
|
for (const s of specs) lines.push(` - ${s.slug} [${s.status}]`);
|
|
@@ -79,10 +79,15 @@ const db = new Database(dbPath);
|
|
|
79
79
|
db.exec(schema);
|
|
80
80
|
|
|
81
81
|
const upsertProject = db.prepare('INSERT INTO projects (name, path, created_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET path=excluded.path');
|
|
82
|
-
|
|
82
|
+
// RETURNING id devolve a linha realmente afetada, inserida ou atualizada.
|
|
83
|
+
// Sem ele restaria `lastInsertRowid`, que num upsert-que-atualizou guarda o id do
|
|
84
|
+
// último INSERT da conexão — um id alheio, e o FTS acabava indexando o conteúdo de
|
|
85
|
+
// um documento sob o node_id de outro (ADR-0021).
|
|
86
|
+
const upsertNode = db.prepare('INSERT INTO memory_nodes (project_id, path, kind, title, content, content_hash, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(path) DO UPDATE SET title=excluded.title, content=excluded.content, content_hash=excluded.content_hash, updated_at=excluded.updated_at RETURNING id');
|
|
83
87
|
const getProjectId = db.prepare('SELECT id FROM projects WHERE name = ?');
|
|
84
88
|
const deleteFts = db.prepare('DELETE FROM search_idx WHERE node_id = ?');
|
|
85
89
|
const insertFts = db.prepare('INSERT INTO search_idx (node_id, title, content) VALUES (?, ?, ?)');
|
|
90
|
+
const purgeFtsOrphans = db.prepare('DELETE FROM search_idx WHERE node_id NOT IN (SELECT id FROM memory_nodes)');
|
|
86
91
|
const upsertSpecSummary = db.prepare(`
|
|
87
92
|
INSERT INTO spec_summaries (slug, status, title, summary, source_path, updated_at)
|
|
88
93
|
VALUES (?, ?, ?, ?, ?, ?)
|
|
@@ -219,9 +224,8 @@ function syncFiles(files, projectId = null) {
|
|
|
219
224
|
const title = titleMatch ? titleMatch[1].trim() : path.basename(rel, '.md');
|
|
220
225
|
|
|
221
226
|
try {
|
|
222
|
-
const
|
|
223
|
-
|
|
224
|
-
|
|
227
|
+
const { id: nodeId } = upsertNode.get(projectId, rel, getKind(rel), title, raw, hash, now);
|
|
228
|
+
|
|
225
229
|
deleteFts.run(nodeId);
|
|
226
230
|
insertFts.run(nodeId, title, raw);
|
|
227
231
|
} catch (e) {
|
|
@@ -274,5 +278,9 @@ if (fs.existsSync(workspaceProjectsMemoryDir)) {
|
|
|
274
278
|
syncFiles(fichaFiles);
|
|
275
279
|
}
|
|
276
280
|
|
|
281
|
+
// Nós removidos deixam linhas órfãs no FTS: matches que apontam para nada.
|
|
282
|
+
const orphans = purgeFtsOrphans.run().changes;
|
|
283
|
+
if (orphans) log(`Índice FTS: ${orphans} linhas órfãs removidas`, 'info');
|
|
284
|
+
|
|
277
285
|
db.close();
|
|
278
286
|
log('Sincronização Universal Concluída!', 'success');
|