forjajs 1.7.1 → 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 +53 -0
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/dist/lib/core/health.js +25 -3
- package/dist/lib/core/release.js +55 -0
- package/dist/scripts/agent-harness.js +25 -14
- package/dist/scripts/context-ops.js +17 -12
- package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -0
- package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -0
- package/package.json +1 -1
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.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
|
+
|
|
32
|
+
## [1.7.2] — 2026-07-22 — Fechando a classe: superfícies do projeto usam `cwd`
|
|
33
|
+
|
|
34
|
+
A auditoria sistemática dos comandos consumer-facing (o passo estrutural após os fixes caso-a-caso
|
|
35
|
+
de `spec:new`/`project:check`) achou **mais três instâncias vivas** da mesma classe — todas escondidas
|
|
36
|
+
num `const root = __dirname/..` que misturava "recurso do framework" com "projeto do usuário". Agora a
|
|
37
|
+
regra é explícita e tem gate (ADR-0032).
|
|
38
|
+
|
|
39
|
+
### Corrigido
|
|
40
|
+
- **`gsd:plan`/`gsd:handoff`/`gsd:check`** (agent-harness) gravavam o runbook e liam `specs/` dentro
|
|
41
|
+
do pacote no consumidor; o `gsd:check` ainda spawava o `spec:check` com `cwd` do pacote e caminho
|
|
42
|
+
`.mjs` cravado (inexistente no dist). Agora operam em `process.cwd()` e resolvem o script via
|
|
43
|
+
`resolveScript` (`.ts` no dev, `.js` no dist).
|
|
44
|
+
- **`context:budget`/`agent:brief`/`context:sprint`** (context-ops) resolviam `.context/`, `specs/`,
|
|
45
|
+
`memory/` e o `.memoryrc.json` no pacote; o `cmdBudget` ainda validava travessia contra a raiz do
|
|
46
|
+
pacote e rejeitava arquivos do projeto. Agora usam `projectRoot = process.cwd()`; `catalog:*`
|
|
47
|
+
(recurso do framework) segue em `root`.
|
|
48
|
+
- **`design:check`** rejeitava o brief do consumidor ("caminho fora do projeto") por ancorar a
|
|
49
|
+
travessia no pacote — agora ancora no projeto.
|
|
50
|
+
|
|
51
|
+
### Adicionado
|
|
52
|
+
- **Gate `consumer-project-surfaces`** no `release:check`: executa `gsd:plan` + `context:budget` no
|
|
53
|
+
cwd de um consumidor instalado e prova que o runbook cai em `<cwd>/.context/` e que o budget o lê de
|
|
54
|
+
lá. Testemunha cruzada, independente do banco — reprova a classe inteira antes do publish.
|
|
55
|
+
- **ADR-0032** e `test/consumer-project-surfaces.test.js`: a regra `projectRoot` (cwd) vs `root`
|
|
56
|
+
(framework) como invariante que roda. `sprint-manager` foi auditado e está são (opera pelo workspace).
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
7
60
|
## [1.7.1] — 2026-07-22 — Correção: `project:check` em projetos consumidores
|
|
8
61
|
|
|
9
62
|
### Corrigido
|
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
|
}
|
package/dist/lib/core/release.js
CHANGED
|
@@ -466,6 +466,60 @@ const consumerProjectCheck = {
|
|
|
466
466
|
return { status: 'ok', detail: 'project:check audita o cwd (o AGENTS.md do consumidor foi visto)', fix: null };
|
|
467
467
|
},
|
|
468
468
|
};
|
|
469
|
+
/**
|
|
470
|
+
* A mesma classe, generalizada além de `spec:new`/`project:check`: TODO comando que opera nas
|
|
471
|
+
* superfícies do projeto (`.context/`, `specs/`, `memory/`) tem de fazê-lo no cwd do consumidor, não
|
|
472
|
+
* no pacote. Aqui a testemunha é CRUZADA e independente do banco: `gsd:plan` grava o runbook em
|
|
473
|
+
* `<cwd>/.context/` (prova `agent-harness`), e `context:budget <slug>` só ACHA esse runbook se
|
|
474
|
+
* resolver o alvo por `projectRoot` (prova `context-ops`, cujo `cmdBudget` cravava `root`). Se qualquer
|
|
475
|
+
* um ainda usasse `__dirname/..`, o efeito cairia no pacote e o budget diria "nao encontrado".
|
|
476
|
+
*/
|
|
477
|
+
const consumerProjectSurfaces = {
|
|
478
|
+
id: 'consumer-project-surfaces',
|
|
479
|
+
title: 'gsd:* e context:* operam nas superfícies do projeto (cwd), não do pacote',
|
|
480
|
+
severity: 'critical',
|
|
481
|
+
dependsOn: 'install',
|
|
482
|
+
probe(env) {
|
|
483
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
|
|
484
|
+
const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
|
|
485
|
+
const bin = path.join(env.pkgDir, binRel);
|
|
486
|
+
const slug = 'smoke-consumer-surface';
|
|
487
|
+
const runbookRel = path.join('.context', `gsd-${slug}.md`);
|
|
488
|
+
// context:budget grava um context_run no universal.db; contém o efeito num workspace descartável
|
|
489
|
+
// para não tocar o do runner (onde ensureSchema criaria um banco sem memory_nodes).
|
|
490
|
+
const opts = { cwd: env.installDir, env: { ...process.env, FORJA_WORKSPACE: path.join(env.installDir, '.forja-workspace') } };
|
|
491
|
+
// 1. gsd:plan grava o runbook — deve cair no cwd, nunca dentro do pacote.
|
|
492
|
+
env.spawn(process.execPath, [bin, 'gsd:plan', slug, 'objetivo de fumaça'], opts);
|
|
493
|
+
const noProjeto = env.fs.existsSync(path.join(env.installDir, runbookRel));
|
|
494
|
+
const noPacote = env.fs.existsSync(path.join(env.pkgDir, runbookRel))
|
|
495
|
+
|| env.fs.existsSync(path.join(env.pkgDir, 'dist', runbookRel));
|
|
496
|
+
if (noPacote) {
|
|
497
|
+
return {
|
|
498
|
+
status: 'fail',
|
|
499
|
+
detail: 'gsd:plan gravou o runbook DENTRO de node_modules/forjajs — opera no mundo errado',
|
|
500
|
+
fix: 'agent-harness deve usar projectRoot=process.cwd() para .context/ e specs/, não __dirname/..',
|
|
501
|
+
};
|
|
502
|
+
}
|
|
503
|
+
if (!noProjeto) {
|
|
504
|
+
return {
|
|
505
|
+
status: 'fail',
|
|
506
|
+
detail: 'gsd:plan não gravou o runbook em <cwd>/.context/ — a raiz do projeto está errada',
|
|
507
|
+
fix: 'confira projectRoot no agent-harness (cmdGsdPlan)',
|
|
508
|
+
};
|
|
509
|
+
}
|
|
510
|
+
// 2. context:budget precisa ACHAR o runbook que o gsd escreveu no cwd — só acha via projectRoot.
|
|
511
|
+
const budget = env.spawn(process.execPath, [bin, 'context:budget', slug], opts);
|
|
512
|
+
const saida = `${budget.stdout || ''}${budget.stderr || ''}`;
|
|
513
|
+
if (/nao encontrado|não encontrado|fora do projeto/i.test(saida)) {
|
|
514
|
+
return {
|
|
515
|
+
status: 'fail',
|
|
516
|
+
detail: 'context:budget não achou o runbook do cwd — está resolvendo o alvo dentro do pacote',
|
|
517
|
+
fix: 'context-ops deve resolver .context/specs/memory por projectRoot=process.cwd(), não por root',
|
|
518
|
+
};
|
|
519
|
+
}
|
|
520
|
+
return { status: 'ok', detail: 'gsd:plan grava no cwd e context:budget o lê de lá — superfícies no projeto', fix: null };
|
|
521
|
+
},
|
|
522
|
+
};
|
|
469
523
|
/** @type {import('./checks.ts').Check[]} */
|
|
470
524
|
export const RELEASE_CHECKS = [
|
|
471
525
|
treeClean,
|
|
@@ -474,6 +528,7 @@ export const RELEASE_CHECKS = [
|
|
|
474
528
|
smokeCommands,
|
|
475
529
|
consumerSpecNew,
|
|
476
530
|
consumerProjectCheck,
|
|
531
|
+
consumerProjectSurfaces,
|
|
477
532
|
importsResolve,
|
|
478
533
|
depsDeclared,
|
|
479
534
|
depsUnused,
|
|
@@ -4,8 +4,13 @@ import path from 'node:path';
|
|
|
4
4
|
import { spawnSync } from 'node:child_process';
|
|
5
5
|
import { fileURLToPath } from 'node:url';
|
|
6
6
|
import { initWorkspace, getWorkspaceInfo, listProjects, resolveProject, getWorkspaceProjectsMemoryDir, } from "../lib/workspace.js";
|
|
7
|
+
import { resolveScript } from "../lib/core/registry.js";
|
|
7
8
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
9
|
+
// `root` = recursos do FRAMEWORK (ex.: design:* lê design-md/) — resolvidos por __dirname.
|
|
10
|
+
// `projectRoot` = o PROJETO do usuário (gsd:* opera em specs/ e .context/ dele) — onde foi invocado.
|
|
11
|
+
// Sem essa separação o gsd escrevia no PACOTE no consumidor (classe spec-cli v1.6.2/check-standards v1.7.1).
|
|
8
12
|
const root = path.resolve(__dirname, '..');
|
|
13
|
+
const projectRoot = process.cwd();
|
|
9
14
|
const DESIGN_REQUIRED = [
|
|
10
15
|
'Feature/superficie',
|
|
11
16
|
'Persona principal',
|
|
@@ -69,8 +74,10 @@ function rel(file) {
|
|
|
69
74
|
return path.relative(root, file);
|
|
70
75
|
}
|
|
71
76
|
function readText(file) {
|
|
72
|
-
|
|
73
|
-
|
|
77
|
+
// O brief do `design:check` é do PROJETO do usuário (cwd), não do pacote — a âncora e o guardrail
|
|
78
|
+
// de travessia são o projectRoot. Cravar `root` rejeitava o brief do consumidor ("fora do projeto").
|
|
79
|
+
const full = path.resolve(projectRoot, file);
|
|
80
|
+
if (!full.startsWith(projectRoot))
|
|
74
81
|
fail(`Caminho fora do projeto: ${file}`);
|
|
75
82
|
if (!fs.existsSync(full))
|
|
76
83
|
fail(`Arquivo nao encontrado: ${file}`);
|
|
@@ -264,15 +271,15 @@ function appendHandoff(payload) {
|
|
|
264
271
|
function cmdGsdPlan([slug = 'run', ...goalParts]) {
|
|
265
272
|
const goal = goalParts.join(' ') || 'execucao orientada por agentes';
|
|
266
273
|
const safeSlug = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
|
|
267
|
-
const outDir = path.join(
|
|
274
|
+
const outDir = path.join(projectRoot, '.context');
|
|
268
275
|
fs.mkdirSync(outDir, { recursive: true });
|
|
269
276
|
const outFile = path.join(outDir, `gsd-${safeSlug}.md`);
|
|
270
|
-
const specPath = path.join(
|
|
277
|
+
const specPath = path.join(projectRoot, 'specs', safeSlug, 'spec.md');
|
|
271
278
|
const hasSpec = fs.existsSync(specPath);
|
|
272
279
|
const content = `# GSD Runbook: ${safeSlug}
|
|
273
280
|
|
|
274
281
|
- **Objetivo**: ${goal}
|
|
275
|
-
- **Spec**: ${hasSpec ?
|
|
282
|
+
- **Spec**: ${hasSpec ? path.relative(projectRoot, specPath) : 'nao encontrada'}
|
|
276
283
|
- **Gerado em**: ${new Date().toISOString()}
|
|
277
284
|
|
|
278
285
|
## Gates
|
|
@@ -304,7 +311,7 @@ function cmdGsdPlan([slug = 'run', ...goalParts]) {
|
|
|
304
311
|
- Rode \`npm run gsd:check -- ${safeSlug} <brief.md>\` antes de entregar para Governance.
|
|
305
312
|
`;
|
|
306
313
|
fs.writeFileSync(outFile, content, 'utf8');
|
|
307
|
-
console.log(`GSD runbook criado: ${
|
|
314
|
+
console.log(`GSD runbook criado: ${path.relative(projectRoot, outFile)}`);
|
|
308
315
|
if (!hasSpec)
|
|
309
316
|
console.log(`Aviso: spec nao encontrada em specs/${safeSlug}/spec.md`);
|
|
310
317
|
}
|
|
@@ -315,12 +322,12 @@ function cmdGsdHandoff([phase, slug, ...contextParts]) {
|
|
|
315
322
|
if (!template)
|
|
316
323
|
fail(`Fase invalida: ${phase}. Use: ${Object.keys(GSD_HANDOFFS).join('|')}`);
|
|
317
324
|
const safeSlug = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
|
|
318
|
-
const specDir = path.join(
|
|
319
|
-
const runbook = path.join(
|
|
325
|
+
const specDir = path.join(projectRoot, 'specs', safeSlug);
|
|
326
|
+
const runbook = path.join(projectRoot, '.context', `gsd-${safeSlug}.md`);
|
|
320
327
|
const contextExtra = contextParts.join(' ').trim();
|
|
321
328
|
const context = [
|
|
322
329
|
fs.existsSync(specDir) ? `specs/${safeSlug}` : `specs/${safeSlug} (nao encontrado)`,
|
|
323
|
-
fs.existsSync(runbook) ?
|
|
330
|
+
fs.existsSync(runbook) ? path.relative(projectRoot, runbook) : `.context/gsd-${safeSlug}.md (nao encontrado)`,
|
|
324
331
|
contextExtra,
|
|
325
332
|
].filter(Boolean).join('; ');
|
|
326
333
|
const payload = {
|
|
@@ -335,20 +342,24 @@ function cmdGsdCheck([slug, briefPath]) {
|
|
|
335
342
|
fail('Uso: agent-harness gsd:check <slug> [brief.md]');
|
|
336
343
|
const safeSlug = slug.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
|
|
337
344
|
const checks = [];
|
|
338
|
-
const runbook = path.join(
|
|
345
|
+
const runbook = path.join(projectRoot, '.context', `gsd-${safeSlug}.md`);
|
|
339
346
|
checks.push({
|
|
340
347
|
name: 'GSD runbook',
|
|
341
348
|
ok: fs.existsSync(runbook),
|
|
342
|
-
detail:
|
|
349
|
+
detail: path.relative(projectRoot, runbook),
|
|
343
350
|
});
|
|
344
|
-
const specDir = path.join(
|
|
351
|
+
const specDir = path.join(projectRoot, 'specs', safeSlug);
|
|
345
352
|
checks.push({
|
|
346
353
|
name: 'Spec directory',
|
|
347
354
|
ok: fs.existsSync(specDir),
|
|
348
355
|
detail: `specs/${safeSlug}`,
|
|
349
356
|
});
|
|
350
|
-
|
|
351
|
-
|
|
357
|
+
// O spec:check tem de rodar no PROJETO do usuário (cwd), não no pacote, e resolver o script pela
|
|
358
|
+
// extensão certa (`.ts` no dev, `.js` no dist publicado). Cravar `cwd: root` + `scripts/spec-cli.mjs`
|
|
359
|
+
// auditava/carregava o pacote no consumidor (mesma classe spec-cli v1.6.2).
|
|
360
|
+
const specCli = resolveScript(root, 'scripts/spec-cli');
|
|
361
|
+
const specCheck = spawnSync(process.execPath, [specCli, 'check', safeSlug], {
|
|
362
|
+
cwd: projectRoot,
|
|
352
363
|
encoding: 'utf8',
|
|
353
364
|
});
|
|
354
365
|
checks.push({
|
|
@@ -5,14 +5,19 @@ import Database from 'better-sqlite3';
|
|
|
5
5
|
import { fileURLToPath } from 'node:url';
|
|
6
6
|
import { ensureSchema, getDbPath } from "./memory-schema.js";
|
|
7
7
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
8
|
+
// `root` = recursos do FRAMEWORK (catalog: boilerplates/, design-md/) — resolvidos por __dirname.
|
|
9
|
+
// `projectRoot` = o PROJETO do usuário (.context/, specs/, memory/, .memoryrc.json) — onde foi invocado.
|
|
10
|
+
// Cravar `root` para as superfícies do projeto auditava/gravava no PACOTE no consumidor (classe de bug
|
|
11
|
+
// spec-cli v1.6.2 / check-standards v1.7.1). No repo do framework os dois coincidem (cwd = raiz).
|
|
8
12
|
const root = path.resolve(__dirname, '..');
|
|
9
|
-
const
|
|
13
|
+
const projectRoot = process.cwd();
|
|
14
|
+
const outDir = path.join(projectRoot, '.context');
|
|
10
15
|
const defaultLimit = readTokenLimit();
|
|
11
16
|
function estimateTokens(content) {
|
|
12
17
|
return Math.ceil(content.length / 4);
|
|
13
18
|
}
|
|
14
19
|
function readTokenLimit() {
|
|
15
|
-
const configPath = path.join(
|
|
20
|
+
const configPath = path.join(projectRoot, '.memoryrc.json');
|
|
16
21
|
if (!fs.existsSync(configPath))
|
|
17
22
|
return 8000;
|
|
18
23
|
try {
|
|
@@ -27,7 +32,7 @@ function ensureOutDir() {
|
|
|
27
32
|
fs.mkdirSync(outDir, { recursive: true });
|
|
28
33
|
}
|
|
29
34
|
function readIfExists(relPath, maxChars = 12000) {
|
|
30
|
-
const full = path.join(
|
|
35
|
+
const full = path.join(projectRoot, relPath);
|
|
31
36
|
if (!fs.existsSync(full))
|
|
32
37
|
return '';
|
|
33
38
|
return fs.readFileSync(full, 'utf8').slice(0, maxChars);
|
|
@@ -47,7 +52,7 @@ function extractSection(content, heading, maxChars = 2200) {
|
|
|
47
52
|
return match ? match[1].trim().slice(0, maxChars) : '';
|
|
48
53
|
}
|
|
49
54
|
function listSpecs() {
|
|
50
|
-
const specsDir = path.join(
|
|
55
|
+
const specsDir = path.join(projectRoot, 'specs');
|
|
51
56
|
if (!fs.existsSync(specsDir))
|
|
52
57
|
return [];
|
|
53
58
|
return fs.readdirSync(specsDir, { withFileTypes: true })
|
|
@@ -64,7 +69,7 @@ function listSpecs() {
|
|
|
64
69
|
status: spec ? specStatus(spec) : 'missing',
|
|
65
70
|
hasPlan: fs.existsSync(planPath),
|
|
66
71
|
hasTasks: fs.existsSync(tasksPath),
|
|
67
|
-
path: path.relative(
|
|
72
|
+
path: path.relative(projectRoot, specPath),
|
|
68
73
|
};
|
|
69
74
|
});
|
|
70
75
|
}
|
|
@@ -80,7 +85,7 @@ function recordContextRun(kind, slug, filePath, content, limitTokens = null) {
|
|
|
80
85
|
db.prepare(`
|
|
81
86
|
INSERT INTO context_runs (created_at, kind, slug, path, bytes, estimated_tokens, limit_tokens, status)
|
|
82
87
|
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
|
|
83
|
-
`).run(new Date().toISOString(), kind, slug || null, path.relative(
|
|
88
|
+
`).run(new Date().toISOString(), kind, slug || null, path.relative(projectRoot, filePath), content.length, tokens, limitTokens, status);
|
|
84
89
|
db.close();
|
|
85
90
|
}
|
|
86
91
|
function upsertSpecSummary(slug, content) {
|
|
@@ -123,7 +128,7 @@ function getOpenHandoffs(slug = null) {
|
|
|
123
128
|
return rows;
|
|
124
129
|
}
|
|
125
130
|
function latestAdrs() {
|
|
126
|
-
const dir = path.join(
|
|
131
|
+
const dir = path.join(projectRoot, 'memory', '90-decisions');
|
|
127
132
|
if (!fs.existsSync(dir))
|
|
128
133
|
return [];
|
|
129
134
|
return fs.readdirSync(dir)
|
|
@@ -148,8 +153,8 @@ function cmdBudget([target, limitArg]) {
|
|
|
148
153
|
`.context/agent-brief-${target}.md`,
|
|
149
154
|
`.context/context-task.md`,
|
|
150
155
|
];
|
|
151
|
-
const file = candidates.map((candidate) => path.resolve(
|
|
152
|
-
if (!file || !file.startsWith(
|
|
156
|
+
const file = candidates.map((candidate) => path.resolve(projectRoot, candidate)).find((candidate) => fs.existsSync(candidate));
|
|
157
|
+
if (!file || !file.startsWith(projectRoot)) {
|
|
153
158
|
console.error(`Arquivo ou slug nao encontrado: ${target}`);
|
|
154
159
|
process.exit(1);
|
|
155
160
|
}
|
|
@@ -157,7 +162,7 @@ function cmdBudget([target, limitArg]) {
|
|
|
157
162
|
const tokens = estimateTokens(content);
|
|
158
163
|
const status = tokens <= limit ? 'OK' : 'FAIL';
|
|
159
164
|
recordContextRun('budget', path.basename(target), file, content, limit);
|
|
160
|
-
console.log(`${status} ${path.relative(
|
|
165
|
+
console.log(`${status} ${path.relative(projectRoot, file)}: ${tokens} tokens estimados / limite ${limit}`);
|
|
161
166
|
if (tokens > limit)
|
|
162
167
|
process.exit(1);
|
|
163
168
|
}
|
|
@@ -189,7 +194,7 @@ function cmdSprintPack() {
|
|
|
189
194
|
const outFile = path.join(outDir, 'sprint-pack.md');
|
|
190
195
|
fs.writeFileSync(outFile, md, 'utf8');
|
|
191
196
|
recordContextRun('sprint-pack', null, outFile, md, defaultLimit);
|
|
192
|
-
console.log(`Sprint pack gerado: ${path.relative(
|
|
197
|
+
console.log(`Sprint pack gerado: ${path.relative(projectRoot, outFile)} (${estimateTokens(md)} tokens estimados)`);
|
|
193
198
|
}
|
|
194
199
|
function cmdAgentBrief([role, slug]) {
|
|
195
200
|
if (!role || !slug) {
|
|
@@ -234,7 +239,7 @@ function cmdAgentBrief([role, slug]) {
|
|
|
234
239
|
const outFile = path.join(outDir, `agent-brief-${role}-${slug}.md`);
|
|
235
240
|
fs.writeFileSync(outFile, md, 'utf8');
|
|
236
241
|
recordContextRun('agent-brief', slug, outFile, md, defaultLimit);
|
|
237
|
-
console.log(`Agent brief gerado: ${path.relative(
|
|
242
|
+
console.log(`Agent brief gerado: ${path.relative(projectRoot, outFile)} (${estimateTokens(md)} tokens estimados)`);
|
|
238
243
|
}
|
|
239
244
|
function summarizeReadme(relPath) {
|
|
240
245
|
const content = readIfExists(relPath, 2500);
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# ADR-0032: superfícies do projeto usam `cwd`; recursos do framework usam `__dirname`
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-22
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: cli, consumer, dist, invariants, release-gate
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Uma mesma classe de bug voltou quatro vezes: um comando funciona no repo do framework (onde `cwd`
|
|
11
|
+
e `__dirname/..` coincidem) e quebra no pacote **publicado** de um consumidor, porque resolve as
|
|
12
|
+
superfícies do projeto do usuário por `__dirname`, apontando para `node_modules/forjajs/dist`.
|
|
13
|
+
Já mordeu `spec:new` (v1.6.2, escrevia dentro do pacote), `project:upgrade` (v1.6.0, extensão `.ts`
|
|
14
|
+
cravada) e `project:check` (v1.7.1, auditava o pacote — travou uma corrida do `orchestrate`).
|
|
15
|
+
|
|
16
|
+
Corrigir caso a caso não fecha a classe. Uma auditoria sistemática dos comandos consumer-facing
|
|
17
|
+
revelou **mais três instâncias vivas**, todas escondidas atrás de um `const root = __dirname/..` que
|
|
18
|
+
misturava dois papéis: em `agent-harness` o `gsd:*`/`design:check` gravavam/liam no pacote; em
|
|
19
|
+
`context-ops` o `cmdBudget` resolvia o alvo e o guardrail de travessia contra o pacote. `sprint-manager`
|
|
20
|
+
saiu limpo — ele opera pelo workspace (`resolveProject`/`getWorkspaceRoot`, caminhos absolutos).
|
|
21
|
+
|
|
22
|
+
## Decisão
|
|
23
|
+
|
|
24
|
+
Todo script separa **dois papéis de raiz**, com nomes distintos:
|
|
25
|
+
|
|
26
|
+
- **`root` = recursos do FRAMEWORK** (templates, `design-md/`, `boilerplates/`, `specs/_templates`) —
|
|
27
|
+
resolvidos por `__dirname`, porque viajam dentro do pacote.
|
|
28
|
+
- **`projectRoot = process.cwd()` = o PROJETO do usuário** (`.context/`, `specs/`, `memory/`,
|
|
29
|
+
`.memoryrc.json`, briefs) — onde o comando foi invocado.
|
|
30
|
+
|
|
31
|
+
Cravar `__dirname/..` para uma superfície do projeto é o bug; cravar `cwd` para um recurso do
|
|
32
|
+
framework é o bug espelhado. O nome da variável passa a **declarar** o papel — some o `root`
|
|
33
|
+
ambíguo que dava para ler dos dois jeitos.
|
|
34
|
+
|
|
35
|
+
A regra vira **invariante que roda**: o gate `consumer-project-surfaces` (em `release:check`) empacota,
|
|
36
|
+
instala isolado e EXECUTA `gsd:plan` + `context:budget` no cwd do consumidor, conferindo que o runbook
|
|
37
|
+
cai em `<cwd>/.context/` e que o budget o encontra de lá. Testemunha cruzada e independente do banco.
|
|
38
|
+
|
|
39
|
+
## Alternativas consideradas
|
|
40
|
+
- **Só corrigir os dois novos offenders** — rejeitada: é o caso-a-caso que deixou a classe reabrir.
|
|
41
|
+
- **Um único `root` esperto (heurística cwd-vs-pacote)** — rejeitada: a ambiguidade É o bug; dois
|
|
42
|
+
nomes explícitos custam nada e removem a decisão do call site.
|
|
43
|
+
- **Gate só a nível de fonte (grep de `__dirname`)** — rejeitada como suficiente: `__dirname` é
|
|
44
|
+
legítimo para recursos do framework; só EXECUTAR no mundo do consumidor separa certo de errado.
|
|
45
|
+
|
|
46
|
+
## Consequências
|
|
47
|
+
|
|
48
|
+
**Positivas**:
|
|
49
|
+
- `gsd:*`, `context:*`, `design:check` passam a operar no projeto do consumidor, como já faziam
|
|
50
|
+
`spec:new`/`project:check`.
|
|
51
|
+
- A classe inteira ganha um gate que a reprova antes do publish — não depende de um consumidor relatar.
|
|
52
|
+
- O código fica auto-documentado: `projectRoot` vs `root` diz o papel sem comentário.
|
|
53
|
+
|
|
54
|
+
**Negativas / Trade-offs**:
|
|
55
|
+
- `catalog:*` (varre `boilerplates/`/`design-md/` do framework) só faz sentido rodado do repo; no
|
|
56
|
+
pacote publicado é inócuo — aceitável, é comando de manutenção, não de consumidor.
|
|
57
|
+
- O gate custa um `npm pack` + install por corrida de `release:check` (já era o caso dos outros dois).
|
|
58
|
+
|
|
59
|
+
## Rastreamento
|
|
60
|
+
- Implementação: `scripts/agent-harness.ts`, `scripts/context-ops.ts`, `lib/core/release.ts`
|
|
61
|
+
(`consumerProjectSurfaces`), `test/consumer-project-surfaces.test.js`
|
|
62
|
+
- ADRs relacionadas: ADR-0021 (invariante > disciplina), ADR-0026 (dual-runtime TS), ADR-0031 (motor
|
|
63
|
+
de orquestração — a corrida que o bug do `project:check` travou)
|
|
@@ -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)
|