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)
|
package/dist/lib/core/health.js
CHANGED
|
@@ -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
|
|
143
|
-
// banco saudável
|
|
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 (${
|
|
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)
|