forjajs 1.7.2 → 1.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,31 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.7.3] — 2026-07-23 — Doctor: permissão/lock não é corrupção
8
+
9
+ O check `memory-db` (consumido por `tools:doctor` e pelo `SessionStart`) tratava **qualquer** falha
10
+ de abertura do `universal.db` como corrupção e prescrevia `sync:universal`. Num ambiente sem escrita
11
+ (sandbox, FS read-only, diretório protegido) o driver lança `SQLITE_CANTOPEN` — e a prescrição é
12
+ ativamente errada: `sync:universal` *escreve* no banco, reencenaria o mesmo erro sem curar nada, e
13
+ levaria o operador a "reindexar" um banco íntegro. Reportado a partir de uma sessão real em sandbox.
14
+
15
+ ### Corrigido
16
+ - **`memory-db` classifica a falha de abertura por `err.code`** em vez de colapsar tudo em
17
+ "corrompido" (ADR-0033):
18
+ - `SQLITE_CANTOPEN` / `EACCES` → **permissão/sandbox**, não corrupção; o fix orienta garantir
19
+ leitura no path e **desaconselha** `sync:universal`.
20
+ - `SQLITE_BUSY` → `warn` (lock temporário de outro processo; não trava o gate); o fix é aguardar.
21
+ - `SQLITE_CORRUPT` / `SQLITE_NOTADB` / resto → corrupção; fix `npm run sync:universal`.
22
+ O `err.code` já vinha impresso no `detail`, mas não decidia nada — a informação existia, faltava
23
+ ramificar. É a mesma classe do bug de ABI que motivou a SPEC-009, sobrevivendo dentro do arquivo
24
+ escrito para fechá-la.
25
+
26
+ ### Adicionado
27
+ - **ADR-0033** e quatro casos em `test/health.test.js` (CANTOPEN, EACCES, BUSY, NOTADB): a distinção
28
+ vira invariante que roda.
29
+
30
+ ---
31
+
7
32
  ## [1.7.2] — 2026-07-22 — Fechando a classe: superfícies do projeto usam `cwd`
8
33
 
9
34
  A auditoria sistemática dos comandos consumer-facing (o passo estrutural após os fixes caso-a-caso
package/README.en.md CHANGED
@@ -211,7 +211,7 @@ forja memory:extract # extract global knowledge from memor
211
211
 
212
212
  # Quality & release
213
213
  forja project:check # framework standards (pre-commit)
214
- forja tools:doctor # core X-ray; exit 1 if broken
214
+ forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
215
215
  forja release:check --publish # tarball gate before publishing
216
216
  forja project:smoke # generated-project gate; --full installs and builds the backend
217
217
  forja project:dashboard # static status report
package/README.md CHANGED
@@ -201,7 +201,7 @@ forja memory:audit # coerência mapa↔código: mapa nã
201
201
 
202
202
  # Qualidade & release
203
203
  forja project:check # standards do framework (pre-commit)
204
- forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
204
+ forja tools:doctor # raio-x do núcleo; separa permissão/lock de corrupção; exit 1 se quebrou
205
205
  forja release:check --publish # gate do tarball antes de publicar
206
206
  forja project:smoke # gate do projeto gerado; --full instala e builda o backend
207
207
  forja check:all # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
@@ -139,8 +139,9 @@ const memoryDb = {
139
139
  fix: 'npm run sync:universal',
140
140
  };
141
141
  }
142
- // Existir não é abrir: um banco corrompido ou sem permissão dá o mesmo `existsSync` de um
143
- // banco saudável, e o operador merece saber qual dos dois é.
142
+ // Existir não é abrir: um banco corrompido, sem permissão ou travado dá o mesmo `existsSync`
143
+ // de um banco saudável. Os três reprovam a abertura por motivos opostos e pedem correções
144
+ // opostas — o `catch` abaixo classifica por `err.code`, nunca colapsa num "corrompido" único.
144
145
  const { default: Database } = await env.importModule('better-sqlite3');
145
146
  try {
146
147
  const db = new Database(dbPath, { readonly: true });
@@ -149,9 +150,30 @@ const memoryDb = {
149
150
  return { status: 'ok', detail: `${n} nós indexados`, fix: null };
150
151
  }
151
152
  catch (err) {
153
+ const code = asErrno(err).code || '';
154
+ // CANTOPEN/EACCES: o arquivo está íntegro, o processo é que não o alcança — sandbox, FS
155
+ // read-only, diretório sem permissão. sync:universal *escreve* no banco: prescrito aqui,
156
+ // reencenaria o mesmo CANTOPEN sem curar nada. Colapsar isso em "corrompido" é o bug que
157
+ // este ramo fecha — a integridade nunca foi tocada.
158
+ if (code === 'SQLITE_CANTOPEN' || code === 'EACCES') {
159
+ return {
160
+ status: 'fail',
161
+ detail: `banco existe mas não abre (${code}) — sem permissão de acesso, não corrupção`,
162
+ fix: `garanta leitura em ${dbPath} (sandbox? FS read-only?) — NÃO rode sync:universal`,
163
+ };
164
+ }
165
+ // BUSY: outro processo mantém o lock. O banco está são; esperar resolve.
166
+ if (code === 'SQLITE_BUSY') {
167
+ return {
168
+ status: 'warn',
169
+ detail: `banco ocupado (${code}) — outro processo o mantém travado`,
170
+ fix: 'aguarde o processo concorrente liberar o lock e rode de novo',
171
+ };
172
+ }
173
+ // Só o que sobra — SQLITE_CORRUPT, SQLITE_NOTADB, o resto — é integridade. Aí sim reindexar.
152
174
  return {
153
175
  status: 'fail',
154
- detail: `banco existe mas não abre (${asErrno(err).code || asErrno(err).message}) — provavelmente corrompido`,
176
+ detail: `banco existe mas não abre (${code || asErrno(err).message}) — provavelmente corrompido`,
155
177
  fix: 'npm run sync:universal',
156
178
  };
157
179
  }
@@ -0,0 +1,64 @@
1
+ # ADR-0033: `memory-db` distingue permissão/lock de corrupção
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-23
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: doctor, memory, diagnostics, sqlite
7
+
8
+ ## Contexto
9
+
10
+ O check `memory-db` (`lib/core/health.ts`), consumido por `tools:doctor` e pelo hook
11
+ `SessionStart`, abria `universal.db` e tratava **qualquer** exceção do `better-sqlite3` como
12
+ corrupção:
13
+
14
+ ```ts
15
+ } catch (err) {
16
+ return {
17
+ status: 'fail',
18
+ detail: `... (${asErrno(err).code}) — provavelmente corrompido`,
19
+ fix: 'npm run sync:universal',
20
+ };
21
+ }
22
+ ```
23
+
24
+ O `err.code` — que já distingue os casos — estava impresso no `detail`, mas não decidia nada.
25
+ Num ambiente sem permissão de escrita (sandbox, FS read-only, diretório protegido) o driver
26
+ lança `SQLITE_CANTOPEN`, e o doctor diagnosticava "provavelmente corrompido" prescrevendo
27
+ `sync:universal`. A prescrição é ativamente errada: `sync:universal` **escreve** no banco — no
28
+ mesmo ambiente ele reencena o `CANTOPEN` sem curar nada, e ainda confunde o operador levando-o a
29
+ "reindexar" um banco íntegro. Reportado a partir de uma sessão real em sandbox restrito.
30
+
31
+ É a violação do princípio 1 do próprio `health.ts` ("nunca colapsar causas distintas num
32
+ booleano"), a mesma classe do bug de ABI que motivou a SPEC-009 — sobrevivendo dentro do arquivo
33
+ escrito para fechá-la.
34
+
35
+ ## Decisão
36
+
37
+ Classificar a falha de abertura por `err.code`, uma causa por prescrição:
38
+
39
+ - `SQLITE_CANTOPEN` / `EACCES` → `fail`, **permissão/sandbox**, não corrupção; fix orienta
40
+ garantir leitura no path e **desaconselha** `sync:universal`.
41
+ - `SQLITE_BUSY` → `warn` (lock temporário de outro processo; não trava o gate); fix é aguardar.
42
+ - Resto (`SQLITE_CORRUPT`, `SQLITE_NOTADB`, …) → `fail`, **corrupção**; fix `npm run sync:universal`.
43
+
44
+ ## Alternativas consideradas
45
+
46
+ - **Testar a integridade com `PRAGMA quick_check` antes de classificar** — rejeitada: um banco que
47
+ nem abre (CANTOPEN) não chega ao pragma; o `err.code` da abertura já carrega a distinção sem I/O extra.
48
+ - **Discriminar por mensagem de erro** — rejeitada: mensagens do SQLite variam entre versões e
49
+ locale; `err.code` é o contrato estável, como o resto do `health.ts` já assume.
50
+
51
+ ## Consequências
52
+
53
+ **Positivas**:
54
+ - Sandbox/permissão deixa de ser confundido com corrupção; o operador recebe a correção da causa real.
55
+ - `sync:universal` nunca é prescrito para um banco íntegro-mas-inacessível.
56
+ - Lock concorrente vira `warn`, não reprova o núcleo.
57
+
58
+ **Negativas / Trade-offs**:
59
+ - Mais um `err.code` (`SQLITE_BUSY`) a manter caso o driver mude a taxonomia — coberto por teste.
60
+
61
+ ## Rastreamento
62
+ - Implementação: `lib/core/health.ts` (check `memory-db`)
63
+ - Testes: `test/health.test.js` (CANTOPEN, EACCES, BUSY, NOTADB)
64
+ - ADRs relacionadas: ADR-0023 (doctor como gate do núcleo), SPEC-009 (doctor-do-nucleo)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.7.2",
3
+ "version": "1.7.3",
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",