forjajs 1.1.3 → 1.1.5
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 +84 -0
- package/README.md +40 -35
- package/docs/agent-harnesses.md +30 -3
- package/docs/capacidades-externas.md +44 -28
- 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 +7 -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
|
@@ -0,0 +1,452 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/release.mjs — o gate do tarball.
|
|
3
|
+
*
|
|
4
|
+
* Guarda a fronteira que `health.mjs` não vê: **o repositório mente sobre o pacote**. No repo tudo
|
|
5
|
+
* resolve — `node_modules` tem as devDeps, todo arquivo está presente, o `cwd` é a raiz. Nada disso
|
|
6
|
+
* vale para quem roda `npm i -g forjajs`. Essa fronteira já cedeu três vezes (SPEC-010):
|
|
7
|
+
*
|
|
8
|
+
* ADR-0021 `better-sqlite3` como devDependency → dez comandos com ERR_MODULE_NOT_FOUND na
|
|
9
|
+
* instalação limpa. O `forja` sem argumentos funcionava, o que mascarava a quebra.
|
|
10
|
+
* v1.1.1 `otplib` e `qrcode` publicados sem jamais existirem no git — `npm publish` empacota o
|
|
11
|
+
* disco, não o commit.
|
|
12
|
+
* v1.1.3 `docs/dashboard.md` e o script publicados sem a pasta `dashboard/`.
|
|
13
|
+
*
|
|
14
|
+
* O princípio que organiza tudo aqui: **grep não prova ausência; instalação prova.** Por isso o
|
|
15
|
+
* gate empacota e instala de verdade, e por isso ele é lento — e tudo bem ser lento, porque roda
|
|
16
|
+
* antes de publicar, não a cada commit.
|
|
17
|
+
*
|
|
18
|
+
* O runner é o de `checks.mjs`, o mesmo do doctor. Uma máquina, duas fronteiras.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
import { execFileSync } from 'node:child_process';
|
|
22
|
+
import fs from 'node:fs';
|
|
23
|
+
import os from 'node:os';
|
|
24
|
+
import path from 'node:path';
|
|
25
|
+
import { fileURLToPath } from 'node:url';
|
|
26
|
+
|
|
27
|
+
import { runChecks as run, worstStatus, stripTemplateLiterals } from './checks.mjs';
|
|
28
|
+
import { COMMANDS } from './registry.mjs';
|
|
29
|
+
|
|
30
|
+
export { worstStatus };
|
|
31
|
+
|
|
32
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
33
|
+
const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
|
|
34
|
+
|
|
35
|
+
/** Assinaturas de tarball quebrado. Exit code não serve — ver `smokeCommands`. */
|
|
36
|
+
const LOADER_ERRORS = /ERR_MODULE_NOT_FOUND|ERR_DLOPEN_FAILED|Cannot find module|ERR_PACKAGE_PATH_NOT_EXPORTED/;
|
|
37
|
+
|
|
38
|
+
function git(args, cwd = repoRoot) {
|
|
39
|
+
return execFileSync('git', args, { cwd, encoding: 'utf8' });
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Empacota o repo e instala o tarball num diretório temporário isolado.
|
|
44
|
+
*
|
|
45
|
+
* Isolamento importa: um gate que enxerga o `node_modules` do repo mente verde. É justamente o
|
|
46
|
+
* `NODE_PATH` herdado e o `node_modules` vizinho que fariam um `import` quebrado resolver mesmo
|
|
47
|
+
* assim — e a quebra só apareceria na máquina do usuário.
|
|
48
|
+
*
|
|
49
|
+
* Limpa o temporário **sempre**, inclusive quando o callback lança.
|
|
50
|
+
*
|
|
51
|
+
* @param {(ctx: { pkgDir: string, installDir: string }) => Promise<T>|T} fn
|
|
52
|
+
* @returns {Promise<T>}
|
|
53
|
+
*/
|
|
54
|
+
export async function withCleanInstall(fn, { root = repoRoot } = {}) {
|
|
55
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-release-'));
|
|
56
|
+
|
|
57
|
+
// Isolamento de verdade — e ele vaza por onde não se espera.
|
|
58
|
+
//
|
|
59
|
+
// `NODE_PATH` é o óbvio. O traiçoeiro é o `npm_config_*`: quando o gate roda de dentro de um
|
|
60
|
+
// script npm (e o `prepublishOnly` é exatamente isso), o npm injeta dezenas dessas variáveis no
|
|
61
|
+
// ambiente. Elas carregam o `local_prefix` do repo e, sob `npm publish --dry-run`, um
|
|
62
|
+
// `npm_config_dry_run=true` que faz o `npm install` interno não instalar nada.
|
|
63
|
+
//
|
|
64
|
+
// Sem esta limpeza, o gate passa localmente e quebra justamente no `prepublishOnly` — o único
|
|
65
|
+
// lugar onde ele precisa funcionar.
|
|
66
|
+
const env = { ...process.env };
|
|
67
|
+
delete env.NODE_PATH;
|
|
68
|
+
for (const key of Object.keys(env)) {
|
|
69
|
+
if (key.startsWith('npm_')) delete env[key];
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const npm = (args, cwd) => {
|
|
73
|
+
try {
|
|
74
|
+
return execFileSync('npm', args, { cwd, encoding: 'utf8', env, stdio: 'pipe' });
|
|
75
|
+
} catch (err) {
|
|
76
|
+
// Engolir o stderr aqui cega o diagnóstico exatamente quando ele importa.
|
|
77
|
+
const saida = `${err.stdout || ''}${err.stderr || ''}`.trim();
|
|
78
|
+
throw new Error(`npm ${args[0]} falhou em ${cwd}:\n${saida || err.message}`);
|
|
79
|
+
}
|
|
80
|
+
};
|
|
81
|
+
|
|
82
|
+
try {
|
|
83
|
+
const tgz = npm(['pack', '--silent', '--pack-destination', dir], root)
|
|
84
|
+
.trim()
|
|
85
|
+
.split('\n')
|
|
86
|
+
.pop();
|
|
87
|
+
|
|
88
|
+
npm(['init', '-y'], dir);
|
|
89
|
+
npm(['install', path.join(dir, tgz)], dir);
|
|
90
|
+
|
|
91
|
+
const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
|
|
92
|
+
const pkgDir = path.join(dir, 'node_modules', pkg.name);
|
|
93
|
+
|
|
94
|
+
return await fn({ pkgDir, installDir: dir });
|
|
95
|
+
} finally {
|
|
96
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// ---------------------------------------------------------------------------
|
|
101
|
+
// Checks
|
|
102
|
+
// ---------------------------------------------------------------------------
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* A falha da v1.1.1, e a única que nenhuma instalação pega: `npm publish` empacota o **disco**, não
|
|
106
|
+
* o commit. Um `npm install` casual entre a auditoria e o publish reescreve o `package.json`, e foi
|
|
107
|
+
* assim que `otplib` e `qrcode` chegaram ao npm sem jamais existirem no git.
|
|
108
|
+
*
|
|
109
|
+
* Severidade depende do modo: sob `--publish` é fatal; em dev é aviso — um gate que reprova todo
|
|
110
|
+
* desenvolvimento local é um gate que se contorna (a lição que o CI nos deu na SPEC-009).
|
|
111
|
+
*/
|
|
112
|
+
const treeClean = {
|
|
113
|
+
id: 'tree-clean',
|
|
114
|
+
title: 'árvore limpa (o tarball é o commit)',
|
|
115
|
+
severity: 'critical',
|
|
116
|
+
probe(env) {
|
|
117
|
+
let dirty;
|
|
118
|
+
try {
|
|
119
|
+
dirty = git(['status', '--short'], env.root).trim();
|
|
120
|
+
} catch {
|
|
121
|
+
return { status: 'skipped', detail: 'fora de um repositório git', fix: null };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (!dirty) return { status: 'ok', detail: 'nada não commitado', fix: null };
|
|
125
|
+
|
|
126
|
+
const n = dirty.split('\n').length;
|
|
127
|
+
const detalhe = `${n} arquivo(s) não commitado(s) — o tarball não corresponde a nenhum commit`;
|
|
128
|
+
|
|
129
|
+
return env.publish
|
|
130
|
+
? { status: 'fail', detail: `${detalhe}. npm publish empacota o disco, não o commit`, fix: 'git commit' }
|
|
131
|
+
: { status: 'warn', detail: `${detalhe}. Ok para smoke; não para publicar`, fix: null };
|
|
132
|
+
},
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
/** Se o pacote não instala, todo o resto é irrelevante — daí todos dependerem deste. */
|
|
136
|
+
const install = {
|
|
137
|
+
id: 'install',
|
|
138
|
+
title: 'o pacote instala do zero',
|
|
139
|
+
severity: 'critical',
|
|
140
|
+
probe(env) {
|
|
141
|
+
return env.pkgDir && env.fs.existsSync(env.pkgDir)
|
|
142
|
+
? { status: 'ok', detail: `instalado em ${path.basename(env.installDir)}`, fix: null }
|
|
143
|
+
: { status: 'fail', detail: 'o tarball não instalou', fix: 'npm pack && npm i <tgz> — investigue o erro' };
|
|
144
|
+
},
|
|
145
|
+
};
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Todo comando anunciado pelo registry precisa existir no tarball. É o bug da v1.1.3, generalizado:
|
|
149
|
+
* `npm run dashboard` era publicado, a pasta `dashboard/` não.
|
|
150
|
+
*/
|
|
151
|
+
const registryScripts = {
|
|
152
|
+
id: 'registry-scripts',
|
|
153
|
+
title: 'todo comando do registry existe no tarball',
|
|
154
|
+
severity: 'critical',
|
|
155
|
+
dependsOn: 'install',
|
|
156
|
+
probe(env) {
|
|
157
|
+
const faltando = [];
|
|
158
|
+
let total = 0;
|
|
159
|
+
|
|
160
|
+
for (const [name, def] of Object.entries(env.registry)) {
|
|
161
|
+
const rel = def.node || def.script;
|
|
162
|
+
if (!rel) continue;
|
|
163
|
+
total += 1;
|
|
164
|
+
if (!env.fs.existsSync(path.join(env.pkgDir, rel))) faltando.push(`${name} → ${rel}`);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
if (faltando.length) {
|
|
168
|
+
return {
|
|
169
|
+
status: 'fail',
|
|
170
|
+
detail: `${faltando.length} comando(s) sem script no tarball: ${faltando.join(', ')}`,
|
|
171
|
+
fix: 'adicione o path ao files[] do package.json',
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
return { status: 'ok', detail: `${total}/${total} comandos com script presente`, fix: null };
|
|
176
|
+
},
|
|
177
|
+
};
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* O **código executável** do pacote — `bin/`, `lib/`, `scripts/`. Nada mais.
|
|
181
|
+
*
|
|
182
|
+
* `boilerplates/` também é publicado e também é `.js`, mas é **conteúdo**: templates copiados para
|
|
183
|
+
* o projeto gerado. O `next.config.js` de um boilerplate importa `next` — que é dependência do
|
|
184
|
+
* projeto do usuário, não do Forja. Varrer essas pastas faz o gate exigir `npm i -S next` no
|
|
185
|
+
* framework, o que é absurdo (observado na primeira execução real do gate).
|
|
186
|
+
*
|
|
187
|
+
* Mesmo princípio de `stripTemplateLiterals`, um nível acima: o que o Forja *escreve* não é o que
|
|
188
|
+
* o Forja *executa*.
|
|
189
|
+
*/
|
|
190
|
+
const CODE_DIRS = ['bin', 'lib', 'scripts'];
|
|
191
|
+
|
|
192
|
+
function publishedSources(env) {
|
|
193
|
+
const out = [];
|
|
194
|
+
|
|
195
|
+
for (const dir of CODE_DIRS) {
|
|
196
|
+
const full = path.join(env.pkgDir, dir);
|
|
197
|
+
if (env.fs.existsSync(full)) walkDir(env, full, out);
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
return out;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
function walkDir(env, dir, out) {
|
|
204
|
+
let entries;
|
|
205
|
+
try {
|
|
206
|
+
entries = env.fs.readdirSync(dir);
|
|
207
|
+
} catch {
|
|
208
|
+
return;
|
|
209
|
+
}
|
|
210
|
+
for (const entry of entries) {
|
|
211
|
+
const p = path.join(dir, entry);
|
|
212
|
+
let st;
|
|
213
|
+
try {
|
|
214
|
+
st = env.fs.statSync(p);
|
|
215
|
+
} catch {
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
if (st.isDirectory()) {
|
|
219
|
+
if (entry !== 'node_modules') walkDir(env, p, out);
|
|
220
|
+
} else if (/\.(mjs|js)$/.test(entry)) {
|
|
221
|
+
out.push(p);
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
const IMPORT_RE = /(?:^|\s)(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|\s)import\s*['"]([^'"]+)['"]/gm;
|
|
227
|
+
|
|
228
|
+
function importsOf(env, file) {
|
|
229
|
+
const src = stripTemplateLiterals(env.fs.readFileSync(file, 'utf8'));
|
|
230
|
+
const out = [];
|
|
231
|
+
for (const m of src.matchAll(IMPORT_RE)) out.push(m[1] || m[2]);
|
|
232
|
+
return out;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** Pacote npm (não builtin, não relativo). `@scope/x/sub` → `@scope/x`. */
|
|
236
|
+
function packageName(specifier) {
|
|
237
|
+
if (!specifier || specifier.startsWith('.') || specifier.startsWith('/')) return null;
|
|
238
|
+
if (specifier.startsWith('node:')) return null;
|
|
239
|
+
const parts = specifier.split('/');
|
|
240
|
+
return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** Import relativo que não resolve dentro do tarball = arquivo fora do `files[]` (bug da v1.1.3). */
|
|
244
|
+
const importsResolve = {
|
|
245
|
+
id: 'imports-resolve',
|
|
246
|
+
title: 'imports relativos resolvem dentro do tarball',
|
|
247
|
+
severity: 'critical',
|
|
248
|
+
dependsOn: 'install',
|
|
249
|
+
probe(env) {
|
|
250
|
+
const quebrados = [];
|
|
251
|
+
|
|
252
|
+
for (const file of publishedSources(env)) {
|
|
253
|
+
for (const spec of importsOf(env, file)) {
|
|
254
|
+
if (!spec?.startsWith('.')) continue;
|
|
255
|
+
const alvo = path.resolve(path.dirname(file), spec);
|
|
256
|
+
const existe = env.fs.existsSync(alvo)
|
|
257
|
+
|| ['.js', '.mjs', '.json'].some((ext) => env.fs.existsSync(alvo + ext));
|
|
258
|
+
if (!existe) quebrados.push(`${path.relative(env.pkgDir, file)} → ${spec}`);
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
if (quebrados.length) {
|
|
263
|
+
return {
|
|
264
|
+
status: 'fail',
|
|
265
|
+
detail: `${quebrados.length} import(s) sem destino no tarball: ${quebrados.slice(0, 3).join('; ')}`,
|
|
266
|
+
fix: 'adicione o arquivo ao files[] do package.json',
|
|
267
|
+
};
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
return { status: 'ok', detail: 'todo import relativo resolve', fix: null };
|
|
271
|
+
},
|
|
272
|
+
};
|
|
273
|
+
|
|
274
|
+
/** O bug do ADR-0021 §2: importado por script publicado, mas declarado como devDependency. */
|
|
275
|
+
const depsDeclared = {
|
|
276
|
+
id: 'deps-declared',
|
|
277
|
+
title: 'todo import externo está em dependencies',
|
|
278
|
+
severity: 'critical',
|
|
279
|
+
dependsOn: 'install',
|
|
280
|
+
probe(env) {
|
|
281
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
|
|
282
|
+
const deps = new Set(Object.keys(pkg.dependencies || {}));
|
|
283
|
+
const faltando = new Map();
|
|
284
|
+
|
|
285
|
+
for (const file of publishedSources(env)) {
|
|
286
|
+
for (const spec of importsOf(env, file)) {
|
|
287
|
+
const nome = packageName(spec);
|
|
288
|
+
if (!nome || deps.has(nome)) continue;
|
|
289
|
+
faltando.set(nome, path.relative(env.pkgDir, file));
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
if (faltando.size) {
|
|
294
|
+
const lista = [...faltando].map(([n, f]) => `${n} (${f})`).join(', ');
|
|
295
|
+
return {
|
|
296
|
+
status: 'fail',
|
|
297
|
+
detail: `importado pelo pacote mas não declarado em dependencies: ${lista}`,
|
|
298
|
+
fix: `npm i -S ${[...faltando.keys()].join(' ')}`,
|
|
299
|
+
};
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
return { status: 'ok', detail: `${deps.size} dependência(s), todas importadas por alguém`, fix: null };
|
|
303
|
+
},
|
|
304
|
+
};
|
|
305
|
+
|
|
306
|
+
/** Peso morto viaja no tarball de todo usuário. Incomoda; não quebra — por isso `warn` (D7). */
|
|
307
|
+
const depsUnused = {
|
|
308
|
+
id: 'deps-unused',
|
|
309
|
+
title: 'nenhuma dependency é peso morto',
|
|
310
|
+
severity: 'warn',
|
|
311
|
+
dependsOn: 'install',
|
|
312
|
+
probe(env) {
|
|
313
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
|
|
314
|
+
const deps = Object.keys(pkg.dependencies || {});
|
|
315
|
+
const usados = new Set();
|
|
316
|
+
|
|
317
|
+
for (const file of publishedSources(env)) {
|
|
318
|
+
for (const spec of importsOf(env, file)) {
|
|
319
|
+
const nome = packageName(spec);
|
|
320
|
+
if (nome) usados.add(nome);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
const ociosos = deps.filter((d) => !usados.has(d));
|
|
325
|
+
if (ociosos.length) {
|
|
326
|
+
return {
|
|
327
|
+
status: 'warn',
|
|
328
|
+
detail: `declarada(s) e nunca importada(s): ${ociosos.join(', ')} — todo usuário baixa isso`,
|
|
329
|
+
fix: `npm rm ${ociosos.join(' ')}`,
|
|
330
|
+
};
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
return { status: 'ok', detail: 'nenhuma dependência ociosa', fix: null };
|
|
334
|
+
},
|
|
335
|
+
};
|
|
336
|
+
|
|
337
|
+
/**
|
|
338
|
+
* O check mais importante, e o mais fácil de errar.
|
|
339
|
+
*
|
|
340
|
+
* **Executar, não listar.** O `forja` sem argumentos passa mesmo com tudo quebrado — o help não
|
|
341
|
+
* carrega os scripts. Foi assim que a quebra do ADR-0021 §2 se escondeu: o help funcionava, e dez
|
|
342
|
+
* comandos estavam mortos.
|
|
343
|
+
*
|
|
344
|
+
* **Reprovar por stderr, nunca por exit code.** Numa instalação limpa não há workspace nem
|
|
345
|
+
* `universal.db`; `query:universal` sai com código ≠ 0 *legitimamente*, e isso é o pacote
|
|
346
|
+
* funcionando. O que denuncia tarball quebrado é a assinatura do carregamento. Reprovar por exit
|
|
347
|
+
* code reprovaria um pacote saudável — a mesma armadilha do `memory-db` na SPEC-009, um nível
|
|
348
|
+
* acima.
|
|
349
|
+
*/
|
|
350
|
+
const smokeCommands = {
|
|
351
|
+
id: 'smoke-commands',
|
|
352
|
+
title: 'os comandos executam de verdade',
|
|
353
|
+
severity: 'critical',
|
|
354
|
+
dependsOn: 'install',
|
|
355
|
+
probe(env) {
|
|
356
|
+
const bin = path.join(env.pkgDir, 'bin', 'forja.mjs');
|
|
357
|
+
const quebrados = [];
|
|
358
|
+
|
|
359
|
+
for (const args of env.smokeCommands) {
|
|
360
|
+
const res = env.spawn(process.execPath, [bin, ...args], { cwd: env.installDir });
|
|
361
|
+
const saida = `${res.stdout || ''}${res.stderr || ''}`;
|
|
362
|
+
if (LOADER_ERRORS.test(saida)) {
|
|
363
|
+
const causa = saida.match(LOADER_ERRORS)[0];
|
|
364
|
+
quebrados.push(`${args[0] || '(help)'}: ${causa}`);
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
if (quebrados.length) {
|
|
369
|
+
return {
|
|
370
|
+
status: 'fail',
|
|
371
|
+
detail: `comando(s) não carregam na instalação limpa: ${quebrados.join('; ')}`,
|
|
372
|
+
fix: 'verifique files[] e dependencies — o repo resolve, o tarball não',
|
|
373
|
+
};
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
return {
|
|
377
|
+
status: 'ok',
|
|
378
|
+
detail: `${env.smokeCommands.length} comando(s) executam sem erro de carregamento`,
|
|
379
|
+
fix: null,
|
|
380
|
+
};
|
|
381
|
+
},
|
|
382
|
+
};
|
|
383
|
+
|
|
384
|
+
/** @type {import('./checks.mjs').Check[]} */
|
|
385
|
+
export const RELEASE_CHECKS = [
|
|
386
|
+
treeClean,
|
|
387
|
+
install,
|
|
388
|
+
registryScripts,
|
|
389
|
+
smokeCommands,
|
|
390
|
+
importsResolve,
|
|
391
|
+
depsDeclared,
|
|
392
|
+
depsUnused,
|
|
393
|
+
];
|
|
394
|
+
|
|
395
|
+
/** Comandos sem efeito colateral. `tools:doctor` e `code:status` só leem; o help não prova nada sozinho. */
|
|
396
|
+
const DEFAULT_SMOKE = [[], ['tools:doctor'], ['code:status'], ['query:universal', 'teste']];
|
|
397
|
+
|
|
398
|
+
export function defaultEnv(overrides = {}) {
|
|
399
|
+
return {
|
|
400
|
+
root: repoRoot,
|
|
401
|
+
fs,
|
|
402
|
+
registry: COMMANDS,
|
|
403
|
+
smokeCommands: DEFAULT_SMOKE,
|
|
404
|
+
publish: false,
|
|
405
|
+
spawn: (cmd, args, opts) => {
|
|
406
|
+
try {
|
|
407
|
+
return {
|
|
408
|
+
stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', ...opts }),
|
|
409
|
+
stderr: '',
|
|
410
|
+
};
|
|
411
|
+
} catch (err) {
|
|
412
|
+
return { stdout: err.stdout || '', stderr: err.stderr || String(err) };
|
|
413
|
+
}
|
|
414
|
+
},
|
|
415
|
+
...overrides,
|
|
416
|
+
};
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* Roda o gate completo: empacota, instala isolado, checa, limpa.
|
|
421
|
+
*
|
|
422
|
+
* A aprovação é **perecível** — vale para o disco naquele instante. Por isso a árvore é reconferida
|
|
423
|
+
* ao final: um `npm install` entre o check e o publish invalida tudo, e foi exatamente essa a causa
|
|
424
|
+
* da v1.1.1.
|
|
425
|
+
*/
|
|
426
|
+
export async function runReleaseChecks({ publish = false, env: overrides = {} } = {}) {
|
|
427
|
+
const base = defaultEnv({ publish, ...overrides });
|
|
428
|
+
|
|
429
|
+
const arvoreAntes = git(['status', '--short'], base.root);
|
|
430
|
+
|
|
431
|
+
const results = await withCleanInstall(
|
|
432
|
+
({ pkgDir, installDir }) => run({
|
|
433
|
+
checks: RELEASE_CHECKS,
|
|
434
|
+
env: { ...base, pkgDir, installDir },
|
|
435
|
+
}),
|
|
436
|
+
{ root: base.root }
|
|
437
|
+
);
|
|
438
|
+
|
|
439
|
+
const arvoreDepois = git(['status', '--short'], base.root);
|
|
440
|
+
if (arvoreAntes !== arvoreDepois) {
|
|
441
|
+
results.push({
|
|
442
|
+
id: 'tree-stable',
|
|
443
|
+
title: 'a árvore não mudou durante a auditoria',
|
|
444
|
+
severity: 'critical',
|
|
445
|
+
status: 'fail',
|
|
446
|
+
detail: 'o disco mudou enquanto o gate rodava — este parecer está vencido',
|
|
447
|
+
fix: 'rode o gate de novo com a árvore parada',
|
|
448
|
+
});
|
|
449
|
+
}
|
|
450
|
+
|
|
451
|
+
return results;
|
|
452
|
+
}
|
|
@@ -1,16 +1,22 @@
|
|
|
1
1
|
# Sprint Atual
|
|
2
2
|
|
|
3
3
|
## Projeto
|
|
4
|
-
framework-root
|
|
4
|
+
framework-root (o repo do Forja — produtos vivem no workspace, ADR-0019)
|
|
5
5
|
|
|
6
6
|
## Objetivos
|
|
7
|
-
-
|
|
7
|
+
- Fechar a classe de falha "erra sem avisar" (ADR-0021) com gates executáveis, não correções pontuais.
|
|
8
8
|
|
|
9
9
|
## Itens da Sprint
|
|
10
|
-
- [
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- [
|
|
10
|
+
- [x] SPEC-009 — Doctor do núcleo (`specs/doctor-do-nucleo/`, ADR-0023)
|
|
11
|
+
`tools:doctor` deixa de auditar só ferramentas opcionais e passa a ser gate do núcleo:
|
|
12
|
+
ABI nativa, memória, workspace, deps de runtime, `.mcp.json`. Exit 1 no que trava o fluxo.
|
|
13
|
+
- [x] `spec:new` mantém a allow-list do `.gitignore` — spec nova do framework nascia invisível ao git.
|
|
14
|
+
|
|
15
|
+
## Próximos candidatos (sem spec ainda)
|
|
16
|
+
- `release-auditor` consumindo `lib/core/health.mjs` em vez de heurística própria — é a terceira
|
|
17
|
+
superfície prevista no ADR-0023 e a única que ainda não migrou.
|
|
18
|
+
- Checks de núcleo no CI (`tools:doctor` como step), fechando o ciclo: hoje o CI roda os testes,
|
|
19
|
+
mas não o gate.
|
|
14
20
|
|
|
15
21
|
## Ritual CLI
|
|
16
22
|
- Planejar: npm run gsd:plan -- <slug> "<objetivo>"
|
|
@@ -18,4 +24,4 @@ framework-root
|
|
|
18
24
|
- Handoff plan: npm run gsd:handoff -- plan <slug>
|
|
19
25
|
- Handoff implement: npm run gsd:handoff -- implement <slug>
|
|
20
26
|
- Validar: npm run gsd:check -- <slug>
|
|
21
|
-
-
|
|
27
|
+
- Governança: npm run project:check && npm run tools:doctor
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# ADR-0023: Doctor como gate do núcleo, não relatório de ferramentas
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-13
|
|
5
|
+
- **Autor(es)**: Allan Pablo
|
|
6
|
+
- **Tags**: harness, governance, memory, hooks, diagnostics
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O ADR-0021 nomeou uma classe de falha do framework: erros que **erram sem avisar** — nenhum teste
|
|
11
|
+
quebra, nada aparece no `git status`, e o resultado é trabalho errado com aparência de trabalho
|
|
12
|
+
certo. Quatro casos foram corrigidos individualmente.
|
|
13
|
+
|
|
14
|
+
Em 2026-07-13 apareceu o quinto, e ele revelou por que corrigir caso a caso não fecha a classe.
|
|
15
|
+
|
|
16
|
+
Com o `better-sqlite3` compilado contra o ABI do Node 24 num runtime Node 26, a memória universal
|
|
17
|
+
morreu inteira: `query:universal`, `sync:universal`, `context:smart`, `agent:route`,
|
|
18
|
+
`memory:compress` e `project:dashboard`, todos inoperantes. A aposta nº 1 da visão — *"memória que
|
|
19
|
+
sobrevive"* — simplesmente não existia. As três superfícies de diagnóstico reagiram assim:
|
|
20
|
+
|
|
21
|
+
| Superfície | O que fez |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `tools:doctor` | Reportou `2/5 ferramentas disponíveis` e saiu com **exit 0** |
|
|
24
|
+
| `SessionStart` | Detectou, mas prescreveu `npm install` — que **não** recompila binário nativo |
|
|
25
|
+
| `npm test` | Stack trace cru de `ERR_DLOPEN_FAILED` |
|
|
26
|
+
|
|
27
|
+
A correção real era `npm rebuild better-sqlite3`.
|
|
28
|
+
|
|
29
|
+
Dois problemas estruturais, não um bug:
|
|
30
|
+
|
|
31
|
+
1. **O doctor auditava o que não importa.** Ele checava cinco ferramentas *opcionais*, sobre as
|
|
32
|
+
quais ele mesmo declarava: *"o fluxo nunca trava por elas"*. Era cego para tudo que trava. Um
|
|
33
|
+
raio-x que só olha o que não pode quebrar.
|
|
34
|
+
2. **Cada superfície tinha heurística própria.** O hook resolvia a saúde da memória com um
|
|
35
|
+
`catch { return null }` que colapsava *sem `node_modules`*, *ABI incompatível* e *banco ausente*
|
|
36
|
+
no mesmo `null` — e então prescrevia a correção de apenas uma das três. Um operador seguindo a
|
|
37
|
+
instrução do próprio framework não consertaria nada, e concluiria que o problema era outro.
|
|
38
|
+
Uma prescrição errada é pior que silêncio: consome o tempo do operador e ainda desvia a
|
|
39
|
+
investigação.
|
|
40
|
+
|
|
41
|
+
## Decisão
|
|
42
|
+
|
|
43
|
+
**O doctor passa a ser o gate do núcleo. As três superfícies passam a ler a mesma fonte.**
|
|
44
|
+
|
|
45
|
+
- **`lib/core/health.mjs`** — os checks viram **dados** (`CHECKS[]`), com um runner que os executa
|
|
46
|
+
e devolve resultados estruturados. `tools:doctor`, `SessionStart` e (futuramente) o
|
|
47
|
+
`release-auditor` são apenas apresentação. Nenhuma superfície volta a ter heurística local.
|
|
48
|
+
- **Probes classificam a causa; o runner nunca colapsa em booleano.** `ERR_DLOPEN_FAILED` →
|
|
49
|
+
`npm rebuild better-sqlite3`. `ERR_MODULE_NOT_FOUND` → `npm install`. Banco ausente →
|
|
50
|
+
`npm run sync:universal`. Causas distintas, correções distintas.
|
|
51
|
+
- **Cascata via `dependsOn`.** Um check cuja dependência falhou é `skipped`, não `fail`. Com o ABI
|
|
52
|
+
quebrado, os checks de memória não têm o que observar; reportá-los como falha multiplicaria uma
|
|
53
|
+
causa em três linhas vermelhas e esconderia a raiz. **Uma causa, uma linha vermelha.**
|
|
54
|
+
- **Dois contratos de exit code.** Núcleo crítico quebrado → `exit 1`. Ferramenta opcional ausente
|
|
55
|
+
→ `exit 0`, preservando o ADR-0018 à risca. Só `critical` trava: `workspace` ausente e Node fora
|
|
56
|
+
do `engines` são avisos, porque não impedem trabalho.
|
|
57
|
+
- **Ausente ≠ quebrado.** Num clone novo — ou num CI — a memória simplesmente nunca foi indexada.
|
|
58
|
+
Isso é o ponto de partida de qualquer instalação, não uma falha, e um comando resolve. `memory-db`
|
|
59
|
+
distingue *não indexado* (aviso) de *existe mas não abre* (crítico). A primeira versão tratava os
|
|
60
|
+
dois como crítico e o CI reprovou de imediato: um gate que reprova todo mundo no primeiro dia é um
|
|
61
|
+
gate em que ninguém confia.
|
|
62
|
+
- **`scope: repo | runtime`.** `runtime-deps` e `mcp-json` — que convertem em gate executável dois
|
|
63
|
+
invariantes que o ADR-0021 corrigiu à mão — só rodam dentro do repo do framework. Numa instalação
|
|
64
|
+
`npm i -g forjajs` não há `devDependencies` nem `.mcp.json`, e rodá-los produziria falso positivo
|
|
65
|
+
crítico na máquina do usuário final.
|
|
66
|
+
- **`spec:new` mantém a allow-list do `.gitignore`.** Descoberto durante a implementação: `/specs/*`
|
|
67
|
+
é ignorado e as specs do framework entram por lista manual, então **toda spec nova nascia
|
|
68
|
+
invisível ao git** — inclusive a desta ADR. Aplicando o princípio do próprio ADR-0021 ("mover a
|
|
69
|
+
aplicação das regras do texto para o harness"), o comando passa a manter a lista.
|
|
70
|
+
|
|
71
|
+
## Alternativas consideradas
|
|
72
|
+
|
|
73
|
+
- **Melhorar só a mensagem do hook** — rejeitada: produziria uma prescrição *genérica*, e o
|
|
74
|
+
problema foi exatamente uma prescrição genérica aplicada a um caso específico. A causa era o
|
|
75
|
+
`catch` que apagava a informação, não o texto.
|
|
76
|
+
- **Doctor com `--fix` que roda `npm rebuild` sozinho** — rejeitada: executar comandos de build sem
|
|
77
|
+
consentimento é a classe de risco oposta à que este ADR fecha. O doctor diagnostica e prescreve.
|
|
78
|
+
- **Fazer o índice defasado reprovar (`critical`)** — rejeitada: um gate que trava por aquilo que
|
|
79
|
+
não impede trabalho é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
|
|
80
|
+
- **Check `spec-allowlist` avisando que a spec está fora do `.gitignore`** — rejeitada em favor de
|
|
81
|
+
o `spec:new` manter a lista: trocaria uma falha silenciosa por um lembrete recorrente. Eliminar a
|
|
82
|
+
classe de erro é melhor que reportá-la.
|
|
83
|
+
- **Um novo comando (`core:doctor`) separado** — rejeitada: dois doctores é como se chega a duas
|
|
84
|
+
verdades divergentes sobre o mesmo sistema, que é precisamente o defeito que este ADR corrige.
|
|
85
|
+
|
|
86
|
+
## Consequências
|
|
87
|
+
|
|
88
|
+
**Positivas**:
|
|
89
|
+
- A quebra do núcleo aparece no **primeiro** comando executado, com a correção certa ao lado — não
|
|
90
|
+
num sintoma indireto trinta minutos depois.
|
|
91
|
+
- Os invariantes do ADR-0021 ganham cobertura executável. Regressão em `.mcp.json` ou nas deps de
|
|
92
|
+
runtime passa a reprovar o gate, em vez de reaparecer em produção.
|
|
93
|
+
- Uma só definição de "saudável". O hook e o doctor não podem mais divergir, porque leem a mesma
|
|
94
|
+
lista.
|
|
95
|
+
- Check novo = entrada nova em `CHECKS[]`, e as três superfícies o ganham de graça.
|
|
96
|
+
|
|
97
|
+
**Negativas / Trade-offs**:
|
|
98
|
+
- `tools:doctor` pode agora **reprovar** (exit 1). Um ambiente já quebrado passa a falhar
|
|
99
|
+
explicitamente onde antes passava calado — é o objetivo, mas muda o contrato de quem o usasse em
|
|
100
|
+
script.
|
|
101
|
+
- `runtime-deps` usa parser estático conservador: import dinâmico não conta. Trocamos cobertura por
|
|
102
|
+
ausência de falso positivo, deliberadamente — um crítico que mente é pior que um warning honesto.
|
|
103
|
+
- O `SessionStart` ganhou uma dependência a mais no caminho quente. Mitigado por rodar só
|
|
104
|
+
`scope: 'runtime'` e nunca lançar: se a própria lib de health não carregar, o hook segue com o
|
|
105
|
+
resto do briefing.
|
|
106
|
+
|
|
107
|
+
## Rastreamento
|
|
108
|
+
|
|
109
|
+
- Implementação: `lib/core/health.mjs`, `scripts/tools-doctor.mjs`, `scripts/hook-session-start.mjs`,
|
|
110
|
+
`scripts/spec-cli.mjs`, `test/health.test.js`
|
|
111
|
+
- Spec: `specs/doctor-do-nucleo/` (SPEC-009)
|
|
112
|
+
- ADRs relacionadas: ADR-0018 (ferramentas de processo — estendido), ADR-0021 (guardrails de
|
|
113
|
+
harness — a classe de falha que este fecha), ADR-0020 (core/registry), ADR-0009 (economia de
|
|
114
|
+
tokens: `query:universal` é o primeiro passo, e índice defasado o corrompe em silêncio)
|