forjajs 1.1.2 → 1.1.4
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 -45
- package/CHANGELOG.md +74 -0
- package/DOC-MAP.md +2 -2
- package/README.md +2 -2
- package/docs/agent-harnesses.md +30 -3
- 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/0021-guardrails-de-harness.md +5 -1
- package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -0
- 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 -7
- 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 +80 -13
- 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/reestruturacao-forja-v2/plan.md +1 -1
- package/specs/reestruturacao-forja-v2/spec.md +16 -12
- package/specs/reestruturacao-forja-v2/tasks.md +1 -1
- package/specs/release-gate/plan.md +174 -0
- package/specs/release-gate/spec.md +122 -0
- package/specs/release-gate/tasks.md +183 -0
- package/docs/dashboard.md +0 -102
- package/specs/agent-dashboard/plan.md +0 -165
- package/specs/agent-dashboard/spec.md +0 -89
- package/specs/agent-dashboard/tasks.md +0 -168
|
@@ -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
|
|
@@ -59,7 +59,11 @@ para a execução.
|
|
|
59
59
|
atualizada, eliminando a dependência de `lastInsertRowid`. O sync passa a purgar linhas órfãs
|
|
60
60
|
do `search_idx` ao final, e o `title` volta a ser atualizado no conflito.
|
|
61
61
|
- **Subagent `release-auditor`.** Audita o pacote instalando o tarball de verdade e exercitando
|
|
62
|
-
comandos reais. Proibido aprovar por leitura de código.
|
|
62
|
+
comandos reais. Proibido aprovar por leitura de código. Exige árvore git limpa antes e depois:
|
|
63
|
+
`npm publish` empacota o **disco**, não o commit, e sua aprovação é perecível. A v1.1.1 saiu
|
|
64
|
+
publicada com `otplib` e `qrcode` em `dependencies` — instalados na árvore de trabalho para
|
|
65
|
+
gerar o código OTP do 2FA, nunca commitados, nunca importados por linha alguma do projeto.
|
|
66
|
+
A auditoria havia passado minutos antes, sobre um disco que deixou de existir.
|
|
63
67
|
- **Skills `new-adr` e `new-command`.** Os dois rituais do repo viram etapas executáveis.
|
|
64
68
|
|
|
65
69
|
## Alternativas consideradas
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# ADR-0022: Congelar o dashboard web
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-09
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: dashboard, cli, release, security, sdd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O dashboard web (`dashboard/`, SPEC-002) foi implementado por inteiro: 15 rotas Fastify,
|
|
11
|
+
12 telas React, 68 testes verdes, bundle de 190KB gzip. Entrou no repositório no commit
|
|
12
|
+
`b732e08` ("Forja v1.1 — release público inicial", 2026-07-06) e **nunca recebeu uma única
|
|
13
|
+
iteração** nos 12 commits seguintes. Não foi abandonado após uso — nasceu sem uso.
|
|
14
|
+
|
|
15
|
+
Três problemas concretos motivaram a decisão:
|
|
16
|
+
|
|
17
|
+
1. **Bug de release já publicado.** O `files[]` do `package.json` nunca incluiu `dashboard/`,
|
|
18
|
+
mas incluía `docs/dashboard.md`, e o `package.json` publicado trazia o script
|
|
19
|
+
`"dashboard": "cd dashboard && npm start"`. O `README.md` documentava o comando. Resultado:
|
|
20
|
+
quem instalou o `forja` v1.1.2 do npm recebeu a documentação e o comando, mas não o código.
|
|
21
|
+
O comando quebra. O `release-auditor` não pegou porque valida o que os binários importam,
|
|
22
|
+
não o que a documentação promete.
|
|
23
|
+
|
|
24
|
+
2. **Segunda fonte de verdade para comandos, já divergente.** O ADR-0020 estabeleceu que todo
|
|
25
|
+
comando de processo passa pelo core (`bin/forja.mjs` + `lib/core/registry.mjs`), com gates
|
|
26
|
+
transversais e auditoria em `.context/forja-runs.jsonl`. O dashboard mantém sua própria
|
|
27
|
+
`COMMAND_ALLOWLIST` hard-coded (decisão D4 da SPEC-002, por razões legítimas de segurança).
|
|
28
|
+
Na auditoria de 2026-07-09: o registry tem 41 comandos, a allowlist expõe 11, e
|
|
29
|
+
**`context:build` existe na allowlist mas não no registry** — executa via
|
|
30
|
+
`node scripts/dev.mjs context:build`, contornando os gates e a trilha de auditoria do core.
|
|
31
|
+
Um comando disparado pelo botão do dashboard não aparece na auditoria.
|
|
32
|
+
|
|
33
|
+
3. **A documentação pública descrevia errado a superfície.** O `README.md` chamava o dashboard
|
|
34
|
+
de "visão opcional read-only". Ele expõe `POST /api/workflow/:project/run/:role` (dispara
|
|
35
|
+
execução de papéis), além de mutações em status de specs, notas de projeto e comandos.
|
|
36
|
+
A auditoria de RCE prevista na T12 da SPEC-002 nunca foi executada, e teria coberto apenas
|
|
37
|
+
`/api/commands` — as rotas `workflow` e `stacks` sequer existiam quando aquela task foi escrita.
|
|
38
|
+
|
|
39
|
+
## Decisão
|
|
40
|
+
|
|
41
|
+
**Congelar o dashboard.** O código permanece em `dashboard/`, versionado e com os testes
|
|
42
|
+
passando, mas deixa de ser superfície pública e de ser tratado como parte do produto:
|
|
43
|
+
|
|
44
|
+
- `docs/dashboard.md` e `specs/agent-dashboard/` saem do `files[]` do pacote npm.
|
|
45
|
+
- Os cinco scripts `dashboard*` saem do `package.json` do root (o `package.json` é publicado
|
|
46
|
+
inteiro; não há como ter script "só local").
|
|
47
|
+
- `README.md` e `DOC-MAP.md` deixam de prometer o dashboard ao usuário do npm.
|
|
48
|
+
- SPEC-002 passa a `abandoned`. O status `parked` não existe no `spec-cli`
|
|
49
|
+
(`draft|review|approved|implementing|done|abandoned`), e `abandoned` é o único que não mente.
|
|
50
|
+
|
|
51
|
+
**Não unificar `registry` ↔ `allowlist` agora.** Era o caminho tecnicamente correto se o
|
|
52
|
+
dashboard tivesse futuro. Sem consumidor, seria infraestrutura elegante sustentando código
|
|
53
|
+
que ninguém roda. O `context:build` fantasma deixa de causar dano ao ser congelado junto.
|
|
54
|
+
|
|
55
|
+
## Alternativas consideradas
|
|
56
|
+
|
|
57
|
+
- **Arquivar de vez** (mover para `docs/archive/`, fechar a spec como wontfix) — rejeitada
|
|
58
|
+
porque descarta 69 arquivos funcionais e testados por uma decisão reversível. O custo de
|
|
59
|
+
manter o código parado no repo é próximo de zero, uma vez removido das superfícies públicas.
|
|
60
|
+
- **Reviver: derivar a allowlist do registry** (campo `exposedToDashboard` + schema de args,
|
|
61
|
+
publicar `dashboard/` no `files[]`, auditar `workflow`/`stacks`) — rejeitada *por ora*
|
|
62
|
+
porque o dashboard nunca teve um usuário. Construir a infraestrutura antes da demanda inverte
|
|
63
|
+
a ordem. Continua sendo o caminho certo **se** a demanda aparecer; ver "Condições de retomada".
|
|
64
|
+
- **Manter como está** — rejeitada porque deixa um comando quebrado publicado no npm e um
|
|
65
|
+
bypass da auditoria do ADR-0020 em pé.
|
|
66
|
+
|
|
67
|
+
## Consequências
|
|
68
|
+
|
|
69
|
+
**Positivas**:
|
|
70
|
+
- O pacote npm para de prometer um comando que não funciona.
|
|
71
|
+
- Some a segunda fonte de verdade para comandos; o `bin/forja.mjs` volta a ser a única.
|
|
72
|
+
- O bypass de auditoria do `context:build` deixa de ser alcançável.
|
|
73
|
+
- A documentação pública passa a descrever a realidade (CLI-first, sem front).
|
|
74
|
+
- Zero manutenção contínua: o código congelado não drifta porque não é superfície.
|
|
75
|
+
|
|
76
|
+
**Negativas / Trade-offs**:
|
|
77
|
+
- 69 arquivos funcionais ficam parados no repositório. É dívida visível, mas inerte.
|
|
78
|
+
- Quem clonar o repo vê uma pasta `dashboard/` sem entrada óbvia; mitigado por
|
|
79
|
+
`dashboard/README.md` explicando o estado e como subir manualmente.
|
|
80
|
+
- Se a demanda por uma interface visual voltar, parte do trabalho de reconciliação
|
|
81
|
+
(rotas novas × allowlist × registry) terá crescido no intervalo.
|
|
82
|
+
|
|
83
|
+
## Condições de retomada
|
|
84
|
+
|
|
85
|
+
Descongelar exige, nesta ordem:
|
|
86
|
+
|
|
87
|
+
1. Um usuário real e um caso de uso que o CLI não atenda. Sem isso, não retomar.
|
|
88
|
+
2. Derivar a allowlist do registry — comando novo entra em `lib/core/registry.mjs` com
|
|
89
|
+
`exposedToDashboard: true` e schema de args declarado. Preserva a garantia do D4
|
|
90
|
+
(nada dinâmico, nada de regex, tudo em código) e mata a classe de bugs de sincronização.
|
|
91
|
+
3. Auditoria de segurança das rotas mutáveis, com escopo explícito em `/api/commands`,
|
|
92
|
+
`/api/workflow/:project/run/:role` e `/api/stacks` — não apenas a primeira, como previa a T12.
|
|
93
|
+
4. Incluir `dashboard/` no `files[]` **antes** de voltar a documentá-lo publicamente.
|
|
94
|
+
|
|
95
|
+
## Rastreamento
|
|
96
|
+
|
|
97
|
+
- Implementação congelada: `dashboard/` (15 rotas, 12 telas, 68 testes)
|
|
98
|
+
- Spec: `specs/agent-dashboard/` (status `abandoned`)
|
|
99
|
+
- Docs: `docs/dashboard.md` (mantido no repo, fora do tarball)
|
|
100
|
+
- ADRs relacionadas: ADR-0020 (core CLI única — cuja fronteira o dashboard violava),
|
|
101
|
+
ADR-0021 (guardrails de harness)
|