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,475 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/health.mjs — saúde do núcleo do Forja.
|
|
3
|
+
*
|
|
4
|
+
* Fonte única de verdade sobre o que impede o framework de trabalhar. Consumida por
|
|
5
|
+
* `tools:doctor` (gate, com exit code), pelo hook `SessionStart` (aviso, nunca trava) e,
|
|
6
|
+
* futuramente, pelo release-auditor.
|
|
7
|
+
*
|
|
8
|
+
* Por que existir (SPEC-009):
|
|
9
|
+
*
|
|
10
|
+
* O `tools:doctor` auditava cinco ferramentas *opcionais* — sobre as quais ele mesmo dizia
|
|
11
|
+
* "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o `better-sqlite3`
|
|
12
|
+
* ficou com ABI de outra major do Node, a memória universal morreu inteira: o doctor reportou
|
|
13
|
+
* "2/5 ferramentas disponíveis", e o SessionStart prescreveu `npm install`, que não recompila
|
|
14
|
+
* binário nativo. A correção real era `npm rebuild better-sqlite3`. Cada superfície tinha sua
|
|
15
|
+
* própria heurística, e por isso uma delas pôde mentir sozinha.
|
|
16
|
+
*
|
|
17
|
+
* Dois princípios, que valem para qualquer check novo:
|
|
18
|
+
*
|
|
19
|
+
* 1. **Nunca colapsar causas distintas num booleano.** O bug original era um `catch { return
|
|
20
|
+
* null }` que engolia "sem node_modules", "ABI incompatível" e "banco ausente" no mesmo
|
|
21
|
+
* `null` — e então prescrevia a correção de apenas uma das três. Um probe classifica a causa
|
|
22
|
+
* e devolve a correção *dela*.
|
|
23
|
+
* 2. **Uma causa, uma linha vermelha.** Com o ABI quebrado, os checks de memória também
|
|
24
|
+
* falhariam, e o operador veria três erros sem saber qual é a raiz. Daí `dependsOn`: check
|
|
25
|
+
* cuja dependência falhou é `skipped`, não `fail`.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
import fs from 'node:fs';
|
|
29
|
+
import path from 'node:path';
|
|
30
|
+
import { fileURLToPath } from 'node:url';
|
|
31
|
+
|
|
32
|
+
import { getWorkspaceDbPath, getWorkspaceInfo } from '../workspace.mjs';
|
|
33
|
+
import { runChecks as run, worstStatus, stripTemplateLiterals } from './checks.mjs';
|
|
34
|
+
|
|
35
|
+
// O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
|
|
36
|
+
// aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
|
|
37
|
+
export { worstStatus };
|
|
38
|
+
|
|
39
|
+
const __filename = fileURLToPath(import.meta.url);
|
|
40
|
+
const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
|
|
41
|
+
|
|
42
|
+
/** @typedef {'critical'|'warn'} Severity */
|
|
43
|
+
/** @typedef {'runtime'|'repo'} Scope */
|
|
44
|
+
/** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* @typedef {object} Check
|
|
48
|
+
* @property {string} id
|
|
49
|
+
* @property {string} title
|
|
50
|
+
* @property {Severity} severity `critical` trava o gate; `warn` informa.
|
|
51
|
+
* @property {Scope} scope `repo` só roda dentro do repo do framework.
|
|
52
|
+
* @property {string=} dependsOn Id de outro check. Se ele falhar, este vira `skipped`.
|
|
53
|
+
* @property {(env: Env) => Promise<Probe>|Probe} probe
|
|
54
|
+
*/
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* @typedef {object} Probe
|
|
58
|
+
* @property {Status} status
|
|
59
|
+
* @property {string} detail O que foi observado, em uma linha.
|
|
60
|
+
* @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
|
|
61
|
+
*/
|
|
62
|
+
|
|
63
|
+
/** @typedef {{ id, title, severity: Severity, scope: Scope, status: Status, detail: string, fix: string|null }} Result */
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* Ambiente injetável. Existe para que os probes sejam testáveis sem mockar o loader de módulos
|
|
67
|
+
* do Node nem corromper `node_modules` de verdade — simular um ABI quebrado é passar um
|
|
68
|
+
* `importModule` que lança `ERR_DLOPEN_FAILED`.
|
|
69
|
+
*
|
|
70
|
+
* @typedef {object} Env
|
|
71
|
+
* @property {string} root Raiz do repo do framework.
|
|
72
|
+
* @property {typeof fs} fs
|
|
73
|
+
* @property {(specifier: string) => Promise<unknown>} importModule
|
|
74
|
+
* @property {object} process Só o que os probes leem: `versions`, `env`.
|
|
75
|
+
* @property {{ dbPath: () => string, info: () => object }} workspace
|
|
76
|
+
*/
|
|
77
|
+
|
|
78
|
+
/** @returns {Env} */
|
|
79
|
+
export function defaultEnv(overrides = {}) {
|
|
80
|
+
return {
|
|
81
|
+
root: repoRoot,
|
|
82
|
+
fs,
|
|
83
|
+
importModule: (specifier) => import(specifier),
|
|
84
|
+
process: globalThis.process,
|
|
85
|
+
workspace: { dbPath: getWorkspaceDbPath, info: getWorkspaceInfo },
|
|
86
|
+
...overrides,
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
// ---------------------------------------------------------------------------
|
|
91
|
+
// Probes
|
|
92
|
+
// ---------------------------------------------------------------------------
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* O check que teria pego a quebra de 2026-07-13.
|
|
96
|
+
*
|
|
97
|
+
* Importar `better-sqlite3` **não** basta: o binding nativo só é aberto no construtor — o
|
|
98
|
+
* `ERR_DLOPEN_FAILED` original vinha de `new Database`, não do import. Um probe que só importasse
|
|
99
|
+
* o módulo daria verde num ambiente quebrado.
|
|
100
|
+
*
|
|
101
|
+
* Classificamos por `err.code`, nunca pela mensagem: o texto do erro varia entre versões do Node,
|
|
102
|
+
* e este check existe precisamente para sobreviver a troca de versão do Node.
|
|
103
|
+
*/
|
|
104
|
+
const nativeAbi = {
|
|
105
|
+
id: 'native-abi',
|
|
106
|
+
title: 'better-sqlite3 carrega no Node atual',
|
|
107
|
+
severity: 'critical',
|
|
108
|
+
scope: 'runtime',
|
|
109
|
+
async probe(env) {
|
|
110
|
+
let Database;
|
|
111
|
+
try {
|
|
112
|
+
({ default: Database } = await env.importModule('better-sqlite3'));
|
|
113
|
+
} catch (err) {
|
|
114
|
+
if (err?.code === 'ERR_MODULE_NOT_FOUND') {
|
|
115
|
+
return {
|
|
116
|
+
status: 'fail',
|
|
117
|
+
detail: 'better-sqlite3 não está instalado — toda a memória universal fica indisponível',
|
|
118
|
+
fix: 'npm install',
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
throw err;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
try {
|
|
125
|
+
new Database(':memory:').close();
|
|
126
|
+
} catch (err) {
|
|
127
|
+
if (err?.code === 'ERR_DLOPEN_FAILED') {
|
|
128
|
+
const node = env.process.versions.node;
|
|
129
|
+
return {
|
|
130
|
+
status: 'fail',
|
|
131
|
+
detail:
|
|
132
|
+
`binário nativo compilado para outra versão do Node (rodando v${node}). ` +
|
|
133
|
+
'A memória universal está morta: query:universal, sync:universal e context:smart não funcionam. ' +
|
|
134
|
+
'npm install NÃO corrige isto — ele não recompila binário nativo quando o lock já bate.',
|
|
135
|
+
fix: 'npm rebuild better-sqlite3',
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
throw err;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
return { status: 'ok', detail: `carrega em Node v${env.process.versions.node}`, fix: null };
|
|
142
|
+
},
|
|
143
|
+
};
|
|
144
|
+
|
|
145
|
+
const memoryDb = {
|
|
146
|
+
id: 'memory-db',
|
|
147
|
+
title: 'universal.db acessível',
|
|
148
|
+
severity: 'critical',
|
|
149
|
+
scope: 'runtime',
|
|
150
|
+
dependsOn: 'native-abi',
|
|
151
|
+
async probe(env) {
|
|
152
|
+
const dbPath = env.workspace.dbPath();
|
|
153
|
+
|
|
154
|
+
// Ausente ≠ quebrado. Num clone novo (ou num CI) a memória simplesmente nunca foi indexada:
|
|
155
|
+
// é o estado natural, não uma falha, e um comando resolve. Reprovar aqui faria o gate travar
|
|
156
|
+
// por aquilo que não impede trabalho — que é como um gate deixa de ser levado a sério.
|
|
157
|
+
if (!env.fs.existsSync(dbPath)) {
|
|
158
|
+
return {
|
|
159
|
+
status: 'warn',
|
|
160
|
+
detail: `banco ainda não indexado (${dbPath}) — normal em clone novo`,
|
|
161
|
+
fix: 'npm run sync:universal',
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// Existir não é abrir: um banco corrompido ou sem permissão dá o mesmo `existsSync` de um
|
|
166
|
+
// banco saudável, e o operador merece saber qual dos dois é.
|
|
167
|
+
const { default: Database } = await env.importModule('better-sqlite3');
|
|
168
|
+
try {
|
|
169
|
+
const db = new Database(dbPath, { readonly: true });
|
|
170
|
+
const { n } = db.prepare('SELECT count(*) AS n FROM memory_nodes').get();
|
|
171
|
+
db.close();
|
|
172
|
+
return { status: 'ok', detail: `${n} nós indexados`, fix: null };
|
|
173
|
+
} catch (err) {
|
|
174
|
+
return {
|
|
175
|
+
status: 'fail',
|
|
176
|
+
detail: `banco existe mas não abre (${err?.code || err?.message}) — provavelmente corrompido`,
|
|
177
|
+
fix: 'npm run sync:universal',
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
},
|
|
181
|
+
};
|
|
182
|
+
|
|
183
|
+
/** mtime do .md mais recente sob um diretório, ignorando arquivados. */
|
|
184
|
+
function newestMarkdownMtime(env, dir, acc = { t: 0 }) {
|
|
185
|
+
let entries;
|
|
186
|
+
try {
|
|
187
|
+
entries = env.fs.readdirSync(dir);
|
|
188
|
+
} catch {
|
|
189
|
+
return acc.t;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
for (const entry of entries) {
|
|
193
|
+
if (entry.startsWith('.') || entry === 'archive') continue;
|
|
194
|
+
const p = path.join(dir, entry);
|
|
195
|
+
let st;
|
|
196
|
+
try {
|
|
197
|
+
st = env.fs.statSync(p);
|
|
198
|
+
} catch {
|
|
199
|
+
continue;
|
|
200
|
+
}
|
|
201
|
+
if (st.isDirectory()) newestMarkdownMtime(env, p, acc);
|
|
202
|
+
else if (entry.endsWith('.md') && st.mtimeMs > acc.t) acc.t = st.mtimeMs;
|
|
203
|
+
}
|
|
204
|
+
return acc.t;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* Índice defasado é a falha mais barata de corrigir e a mais cara de ignorar: `query:universal`
|
|
209
|
+
* é o primeiro passo da economia de tokens (ADR-0009), então um índice velho alimenta os agentes
|
|
210
|
+
* com o documento errado — sem erro, sem log, sem sintoma.
|
|
211
|
+
*
|
|
212
|
+
* É `warn`, não `critical`: responder sobre memória velha atrapalha, mas não impede trabalho.
|
|
213
|
+
*/
|
|
214
|
+
const memoryFresh = {
|
|
215
|
+
id: 'memory-fresh',
|
|
216
|
+
title: 'índice em dia com memory/',
|
|
217
|
+
severity: 'warn',
|
|
218
|
+
scope: 'runtime',
|
|
219
|
+
dependsOn: 'memory-db',
|
|
220
|
+
probe(env) {
|
|
221
|
+
const dbPath = env.workspace.dbPath();
|
|
222
|
+
|
|
223
|
+
// `memory-db` passa com aviso quando o banco nunca foi indexado, então a cascata não nos pula:
|
|
224
|
+
// um índice que não existe não pode estar defasado.
|
|
225
|
+
if (!env.fs.existsSync(dbPath)) {
|
|
226
|
+
return { status: 'skipped', detail: 'não há índice para comparar', fix: null };
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
const dbMtime = env.fs.statSync(dbPath).mtimeMs;
|
|
230
|
+
const newest = newestMarkdownMtime(env, path.join(env.root, 'memory'));
|
|
231
|
+
|
|
232
|
+
if (newest > dbMtime) {
|
|
233
|
+
const horas = Math.round((newest - dbMtime) / 36e5);
|
|
234
|
+
return {
|
|
235
|
+
status: 'warn',
|
|
236
|
+
detail:
|
|
237
|
+
`memory/ mudou depois do último sync (${horas}h) — query:universal vai responder ` +
|
|
238
|
+
'sobre memória velha, calado',
|
|
239
|
+
fix: 'npm run sync:universal',
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
return { status: 'ok', detail: 'índice em dia', fix: null };
|
|
244
|
+
},
|
|
245
|
+
};
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* `warn`, não `critical`: o framework trabalha sem workspace — só `project:new` e a memória de
|
|
249
|
+
* produto precisam dele.
|
|
250
|
+
*
|
|
251
|
+
* Reporta a **origem** da resolução (FORJA_WORKSPACE / ~/.forjarc.json / default), que é metade do
|
|
252
|
+
* diagnóstico: o modo de falha interessante não é "não existe", é "existe, mas não é o que você
|
|
253
|
+
* pensa" — um FORJA_WORKSPACE esquecido no ambiente aponta o framework para o workspace errado, e
|
|
254
|
+
* tudo parece funcionar.
|
|
255
|
+
*/
|
|
256
|
+
const workspace = {
|
|
257
|
+
id: 'workspace',
|
|
258
|
+
title: 'workspace resolvido',
|
|
259
|
+
severity: 'warn',
|
|
260
|
+
scope: 'runtime',
|
|
261
|
+
probe(env) {
|
|
262
|
+
const { root, source, exists } = env.workspace.info();
|
|
263
|
+
|
|
264
|
+
if (!exists) {
|
|
265
|
+
return {
|
|
266
|
+
status: 'warn',
|
|
267
|
+
detail: `workspace não existe em ${root} (origem: ${source})`,
|
|
268
|
+
fix: 'npm run workspace:init',
|
|
269
|
+
};
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
return { status: 'ok', detail: `${root} (origem: ${source})`, fix: null };
|
|
273
|
+
},
|
|
274
|
+
};
|
|
275
|
+
|
|
276
|
+
/** Compara o Node em uso com o `engines.node` declarado. Abaixo do mínimo, o resto é loteria. */
|
|
277
|
+
const nodeEngines = {
|
|
278
|
+
id: 'node-engines',
|
|
279
|
+
title: 'Node dentro de engines',
|
|
280
|
+
severity: 'warn',
|
|
281
|
+
scope: 'runtime',
|
|
282
|
+
probe(env) {
|
|
283
|
+
const current = env.process.versions.node;
|
|
284
|
+
const pkgPath = path.join(env.root, 'package.json');
|
|
285
|
+
|
|
286
|
+
let range;
|
|
287
|
+
try {
|
|
288
|
+
range = JSON.parse(env.fs.readFileSync(pkgPath, 'utf8'))?.engines?.node;
|
|
289
|
+
} catch {
|
|
290
|
+
return { status: 'ok', detail: 'package.json sem engines — nada a comparar', fix: null };
|
|
291
|
+
}
|
|
292
|
+
if (!range) return { status: 'ok', detail: 'sem engines declarado', fix: null };
|
|
293
|
+
|
|
294
|
+
// Só o caso que importa: `>=N`. Ranges mais ricos não são usados aqui, e reimplementar semver
|
|
295
|
+
// para um caso que não existe seria inventar problema.
|
|
296
|
+
const min = /^>=\s*(\d+)/.exec(range)?.[1];
|
|
297
|
+
if (!min) return { status: 'ok', detail: `engines: ${range}`, fix: null };
|
|
298
|
+
|
|
299
|
+
const major = Number(current.split('.')[0]);
|
|
300
|
+
if (major < Number(min)) {
|
|
301
|
+
return {
|
|
302
|
+
status: 'warn',
|
|
303
|
+
detail: `Node v${current} abaixo do declarado (engines: ${range})`,
|
|
304
|
+
fix: `atualize o Node para ${min} ou superior`,
|
|
305
|
+
};
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
return { status: 'ok', detail: `Node v${current} (engines: ${range})`, fix: null };
|
|
309
|
+
},
|
|
310
|
+
};
|
|
311
|
+
|
|
312
|
+
// ---------------------------------------------------------------------------
|
|
313
|
+
// Checks de regressão do repositório (scope: repo)
|
|
314
|
+
//
|
|
315
|
+
// Convertem em gate executável dois invariantes que o ADR-0021 corrigiu à mão e que hoje podem
|
|
316
|
+
// reincidir sem que nada perceba. São `scope: repo` porque não fazem sentido numa instalação
|
|
317
|
+
// `npm i -g forjajs` — lá não há devDependencies instaladas nem .mcp.json versionado, e rodá-los
|
|
318
|
+
// produziria falso positivo crítico na máquina do usuário final.
|
|
319
|
+
// ---------------------------------------------------------------------------
|
|
320
|
+
|
|
321
|
+
/** Estamos dentro do repo do framework, e não numa instalação do pacote? */
|
|
322
|
+
export function isFrameworkRepo(env) {
|
|
323
|
+
try {
|
|
324
|
+
if (!env.fs.existsSync(path.join(env.root, '.git'))) return false;
|
|
325
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.root, 'package.json'), 'utf8'));
|
|
326
|
+
return pkg.name === 'forjajs';
|
|
327
|
+
} catch {
|
|
328
|
+
return false;
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
const IMPORT_RE = /^\s*import\s+(?:[\w*{}\n\r\t, ]+from\s+)?['"]([^'"]+)['"]/gm;
|
|
333
|
+
|
|
334
|
+
/** Pacote npm (não builtin, não relativo). `@scope/x/sub` → `@scope/x`; `x/sub` → `x`. */
|
|
335
|
+
function packageName(specifier) {
|
|
336
|
+
if (specifier.startsWith('.') || specifier.startsWith('/')) return null;
|
|
337
|
+
if (specifier.startsWith('node:')) return null;
|
|
338
|
+
const parts = specifier.split('/');
|
|
339
|
+
return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* ADR-0021 §2: dez scripts sob `files[]` importavam `better-sqlite3` estaticamente, e o pacote
|
|
344
|
+
* declarava zero `dependencies`. Numa instalação limpa, metade dos comandos estourava com
|
|
345
|
+
* `ERR_MODULE_NOT_FOUND` — e o `forja` sem argumentos funcionava, o que mascarava a quebra.
|
|
346
|
+
*
|
|
347
|
+
* Conservador de propósito: só olha import **estático** de script publicado. Import dinâmico não
|
|
348
|
+
* conta (é o padrão do carregamento lazy, e lazy é justamente o que o ADR-0021 pediu).
|
|
349
|
+
*/
|
|
350
|
+
const runtimeDeps = {
|
|
351
|
+
id: 'runtime-deps',
|
|
352
|
+
title: 'deps de runtime declaradas',
|
|
353
|
+
severity: 'critical',
|
|
354
|
+
scope: 'repo',
|
|
355
|
+
probe(env) {
|
|
356
|
+
if (!isFrameworkRepo(env)) {
|
|
357
|
+
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.root, 'package.json'), 'utf8'));
|
|
361
|
+
const deps = new Set(Object.keys(pkg.dependencies || {}));
|
|
362
|
+
const devDeps = new Set(Object.keys(pkg.devDependencies || {}));
|
|
363
|
+
|
|
364
|
+
// Diretórios publicados que contêm código executável.
|
|
365
|
+
const published = (pkg.files || [])
|
|
366
|
+
.filter((f) => !f.startsWith('!') && /^(bin|lib|scripts)\//.test(f))
|
|
367
|
+
.map((f) => path.join(env.root, f.replace(/\/+$/, '')));
|
|
368
|
+
|
|
369
|
+
const offenders = new Map();
|
|
370
|
+
|
|
371
|
+
const walk = (dir) => {
|
|
372
|
+
let entries;
|
|
373
|
+
try {
|
|
374
|
+
entries = env.fs.readdirSync(dir);
|
|
375
|
+
} catch {
|
|
376
|
+
return;
|
|
377
|
+
}
|
|
378
|
+
for (const entry of entries) {
|
|
379
|
+
const p = path.join(dir, entry);
|
|
380
|
+
let st;
|
|
381
|
+
try {
|
|
382
|
+
st = env.fs.statSync(p);
|
|
383
|
+
} catch {
|
|
384
|
+
continue;
|
|
385
|
+
}
|
|
386
|
+
if (st.isDirectory()) {
|
|
387
|
+
walk(p);
|
|
388
|
+
continue;
|
|
389
|
+
}
|
|
390
|
+
if (!/\.(mjs|js)$/.test(entry)) continue;
|
|
391
|
+
|
|
392
|
+
// Sem apagar os template literals, os geradores acusam a si mesmos: `nest-generator.js`
|
|
393
|
+
// emite `import { INestApplication } from '@nestjs/common'` dentro de crases — código que
|
|
394
|
+
// ele *escreve* para o projeto gerado, não que ele importa. Como a linha começa com
|
|
395
|
+
// `import`, a âncora do parser casa. Hoje passaria por sorte (`@nestjs/*` não está nas
|
|
396
|
+
// devDeps); no dia em que estivesse, este check travaria o gate sem motivo.
|
|
397
|
+
const src = stripTemplateLiterals(env.fs.readFileSync(p, 'utf8'));
|
|
398
|
+
for (const [, specifier] of src.matchAll(IMPORT_RE)) {
|
|
399
|
+
const name = packageName(specifier);
|
|
400
|
+
if (!name || deps.has(name)) continue;
|
|
401
|
+
if (devDeps.has(name)) {
|
|
402
|
+
offenders.set(name, path.relative(env.root, p));
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
};
|
|
407
|
+
|
|
408
|
+
published.forEach(walk);
|
|
409
|
+
|
|
410
|
+
if (offenders.size) {
|
|
411
|
+
const lista = [...offenders].map(([n, f]) => `${n} (${f})`).join(', ');
|
|
412
|
+
return {
|
|
413
|
+
status: 'fail',
|
|
414
|
+
detail: `importado por script publicado, mas declarado em devDependencies: ${lista}`,
|
|
415
|
+
fix: `npm i -S ${[...offenders.keys()].join(' ')}`,
|
|
416
|
+
};
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
return { status: 'ok', detail: 'imports de scripts publicados estão em dependencies', fix: null };
|
|
420
|
+
},
|
|
421
|
+
};
|
|
422
|
+
|
|
423
|
+
/**
|
|
424
|
+
* ADR-0021 §1: `.mcp.json` versionado com `-p /home/apk/.../projects/forja`, uma cópia parada do
|
|
425
|
+
* repo. O codegraph indexava código morto e respondia com confiança sobre ele. O path também
|
|
426
|
+
* quebrava para qualquer outro contribuidor.
|
|
427
|
+
*/
|
|
428
|
+
const mcpJson = {
|
|
429
|
+
id: 'mcp-json',
|
|
430
|
+
title: '.mcp.json sem path absoluto',
|
|
431
|
+
severity: 'critical',
|
|
432
|
+
scope: 'repo',
|
|
433
|
+
probe(env) {
|
|
434
|
+
if (!isFrameworkRepo(env)) {
|
|
435
|
+
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
const file = path.join(env.root, '.mcp.json');
|
|
439
|
+
if (!env.fs.existsSync(file)) {
|
|
440
|
+
return { status: 'ok', detail: '.mcp.json ausente — nada a validar', fix: null };
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
const raw = env.fs.readFileSync(file, 'utf8');
|
|
444
|
+
// Um path absoluto num arquivo versionado só pode estar certo na máquina de quem escreveu.
|
|
445
|
+
const hits = raw.match(/["'](\/(?:home|Users)\/[^"']+)["']/g);
|
|
446
|
+
|
|
447
|
+
if (hits) {
|
|
448
|
+
return {
|
|
449
|
+
status: 'fail',
|
|
450
|
+
detail: `path absoluto versionado: ${hits.join(', ')} — aponta para a máquina de quem commitou`,
|
|
451
|
+
fix: 'remova o path de .mcp.json (o MCP resolve o projeto pelo rootUri do cliente)',
|
|
452
|
+
};
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
return { status: 'ok', detail: 'sem paths absolutos', fix: null };
|
|
456
|
+
},
|
|
457
|
+
};
|
|
458
|
+
|
|
459
|
+
/** @type {Check[]} */
|
|
460
|
+
export const CHECKS = [nativeAbi, memoryDb, memoryFresh, workspace, nodeEngines, runtimeDeps, mcpJson];
|
|
461
|
+
|
|
462
|
+
/**
|
|
463
|
+
* Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
|
|
464
|
+
* `defaultEnv` do framework, que o runner genérico não conhece nem deve conhecer.
|
|
465
|
+
*
|
|
466
|
+
* `scope: 'runtime'` roda só os checks baratos e portáveis — é o que o hook SessionStart usa, onde
|
|
467
|
+
* há orçamento de 5s e nenhuma tolerância a travar a sessão.
|
|
468
|
+
*
|
|
469
|
+
* @param {{ scope?: Scope|'all', env?: Partial<Env>, checks?: Check[] }} [opts]
|
|
470
|
+
* @returns {Promise<Result[]>}
|
|
471
|
+
*/
|
|
472
|
+
export async function runChecks(opts = {}) {
|
|
473
|
+
const { scope = 'all', checks = CHECKS } = opts;
|
|
474
|
+
return run({ checks, scope, env: defaultEnv(opts.env) });
|
|
475
|
+
}
|
package/lib/core/registry.mjs
CHANGED
|
@@ -266,9 +266,14 @@ export const COMMANDS = {
|
|
|
266
266
|
},
|
|
267
267
|
'tools:doctor': {
|
|
268
268
|
domain: 'governanca',
|
|
269
|
-
desc: 'Raio-x
|
|
269
|
+
desc: 'Raio-x do núcleo (gate, exit 1) + ferramentas de processo (ADR-0023, ADR-0018)',
|
|
270
270
|
node: 'scripts/tools-doctor.mjs',
|
|
271
271
|
},
|
|
272
|
+
'release:check': {
|
|
273
|
+
domain: 'governanca',
|
|
274
|
+
desc: 'Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito',
|
|
275
|
+
node: 'scripts/release-check.mjs',
|
|
276
|
+
},
|
|
272
277
|
'project:dashboard': {
|
|
273
278
|
domain: 'governanca',
|
|
274
279
|
desc: 'Gera dashboard estático de status',
|