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
|
@@ -410,7 +410,7 @@ const context = builder.build('global', 'my-project');
|
|
|
410
410
|
|
|
411
411
|
```bash
|
|
412
412
|
# Developer needs feature context
|
|
413
|
-
npm run context:
|
|
413
|
+
npm run context:smart -- task my-project "payment feature"
|
|
414
414
|
# Uses cached domain + task-specific files
|
|
415
415
|
# Result: ~30KB, ~7500 tokens, $0.0075
|
|
416
416
|
```
|
|
@@ -419,7 +419,7 @@ npm run context:build -- task my-project "payment feature"
|
|
|
419
419
|
|
|
420
420
|
```bash
|
|
421
421
|
# Security agent needs all related context
|
|
422
|
-
npm run context:
|
|
422
|
+
npm run context:smart -- domain my-project
|
|
423
423
|
# Adds security rules, ADRs, design docs
|
|
424
424
|
# Result: ~20KB, ~5000 tokens, $0.005
|
|
425
425
|
```
|
|
@@ -428,7 +428,7 @@ npm run context:build -- domain my-project
|
|
|
428
428
|
|
|
429
429
|
```bash
|
|
430
430
|
# New dev needs big picture
|
|
431
|
-
npm run context:
|
|
431
|
+
npm run context:smart -- global my-project
|
|
432
432
|
# Just mission, standards, recent ADRs
|
|
433
433
|
# Result: ~2KB, ~500 tokens, $0.0005
|
|
434
434
|
```
|
|
@@ -441,21 +441,22 @@ npm run context:build -- global my-project
|
|
|
441
441
|
|
|
442
442
|
```bash
|
|
443
443
|
# Try smaller mode
|
|
444
|
-
npm run context:
|
|
444
|
+
npm run context:smart -- global # Instead of domain
|
|
445
445
|
|
|
446
446
|
# Or prune manually
|
|
447
|
-
|
|
447
|
+
npm run memory:compress
|
|
448
448
|
npm run memory:vacuum
|
|
449
449
|
```
|
|
450
450
|
|
|
451
|
-
### FTS5 Queries Slow?
|
|
451
|
+
### FTS5 Queries Slow or Stale?
|
|
452
452
|
|
|
453
453
|
```bash
|
|
454
|
-
# Rebuild
|
|
455
|
-
npm run
|
|
454
|
+
# Rebuild the index (it is also what fixes a stale index)
|
|
455
|
+
npm run sync:universal
|
|
456
456
|
|
|
457
|
-
#
|
|
458
|
-
|
|
457
|
+
# The doctor tells you when the index is behind memory/ — it is the
|
|
458
|
+
# failure that costs the most and shows the least (ADR-0023).
|
|
459
|
+
npm run tools:doctor
|
|
459
460
|
```
|
|
460
461
|
|
|
461
462
|
### Cache Not Working?
|
|
@@ -472,23 +473,30 @@ cat .memoryrc.json | grep cache -A 5
|
|
|
472
473
|
|
|
473
474
|
## 📚 Related Commands
|
|
474
475
|
|
|
476
|
+
Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
|
|
477
|
+
registry — `node bin/forja.mjs` lista todos.
|
|
478
|
+
|
|
475
479
|
```bash
|
|
476
|
-
#
|
|
477
|
-
npm run
|
|
480
|
+
# Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
|
|
481
|
+
npm run query:universal "auth"
|
|
482
|
+
|
|
483
|
+
# Montar o pacote de contexto mínimo-suficiente (global | domain | task)
|
|
484
|
+
npm run context:smart -- task my-project "payment feature"
|
|
478
485
|
|
|
479
|
-
#
|
|
486
|
+
# Reindexar a memória — também é o que corrige um índice defasado
|
|
487
|
+
npm run sync:universal
|
|
488
|
+
|
|
489
|
+
# Comprimir memória antiga e recuperar espaço
|
|
490
|
+
npm run memory:compress
|
|
480
491
|
npm run memory:vacuum
|
|
481
492
|
|
|
482
|
-
#
|
|
493
|
+
# Medir a economia
|
|
483
494
|
npm run token:benchmark
|
|
484
495
|
|
|
485
|
-
#
|
|
486
|
-
npm run
|
|
487
|
-
|
|
488
|
-
# Query memory
|
|
489
|
-
npm run memory:db:query -- "auth"
|
|
496
|
+
# Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
|
|
497
|
+
npm run tools:doctor
|
|
490
498
|
```
|
|
491
499
|
|
|
492
500
|
---
|
|
493
501
|
|
|
494
|
-
**
|
|
502
|
+
**Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/checks.mjs — o runner de checks. Sem opinião sobre o que se checa.
|
|
3
|
+
*
|
|
4
|
+
* Máquina compartilhada por dois catálogos, cada um guardando uma fronteira:
|
|
5
|
+
*
|
|
6
|
+
* health.mjs o núcleo — o que impede o framework de trabalhar aqui (SPEC-009, ADR-0023)
|
|
7
|
+
* release.mjs o tarball — o que impede o pacote de funcionar na máquina de quem instala (SPEC-010)
|
|
8
|
+
*
|
|
9
|
+
* O runner foi extraído, e não copiado, de propósito: duas máquinas iguais divergem com o tempo, e
|
|
10
|
+
* divergência entre superfícies que deveriam concordar é exatamente o defeito que a SPEC-009
|
|
11
|
+
* existiu para matar (o doctor e o hook diziam coisas diferentes sobre a mesma memória).
|
|
12
|
+
*
|
|
13
|
+
* Dois princípios, que valem para qualquer check novo em qualquer catálogo:
|
|
14
|
+
*
|
|
15
|
+
* 1. **Nunca colapsar causas distintas num booleano.** Um probe classifica a causa e devolve a
|
|
16
|
+
* correção *dela*. O bug que originou tudo isso era um `catch { return null }` que engolia três
|
|
17
|
+
* causas e prescrevia a correção de uma.
|
|
18
|
+
* 2. **Uma causa, uma linha vermelha.** Check cuja dependência falhou é `skipped`, não `fail` —
|
|
19
|
+
* senão uma raiz vira três erros vermelhos e o operador não sabe qual perseguir.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
/** @typedef {'critical'|'warn'} Severity */
|
|
23
|
+
/** @typedef {'runtime'|'repo'} Scope */
|
|
24
|
+
/** @typedef {'ok'|'warn'|'fail'|'skipped'} Status */
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @typedef {object} Check
|
|
28
|
+
* @property {string} id
|
|
29
|
+
* @property {string} title
|
|
30
|
+
* @property {Severity} severity `critical` trava o gate; `warn` informa.
|
|
31
|
+
* @property {Scope=} scope Filtro opcional do runner.
|
|
32
|
+
* @property {string=} dependsOn Id de outro check. Se ele não passar, este vira `skipped`.
|
|
33
|
+
* @property {(env: object) => Promise<Probe>|Probe} probe
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* @typedef {object} Probe
|
|
38
|
+
* @property {Status} status
|
|
39
|
+
* @property {string} detail O que foi observado, em uma linha.
|
|
40
|
+
* @property {string|null=} fix Comando exato que corrige. `null` quando não há o que corrigir.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/** @typedef {{ id, title, severity: Severity, scope: Scope, status: Status, detail: string, fix: string|null }} Result */
|
|
44
|
+
|
|
45
|
+
const SEVERITY_FALLBACK = 'critical';
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Um probe que estoura é pior que probe nenhum: derrubaria o diagnóstico justamente no ambiente
|
|
49
|
+
* quebrado que ele existe para diagnosticar. O runner blinda cada um e segue para o próximo.
|
|
50
|
+
*/
|
|
51
|
+
async function runProbe(check, env) {
|
|
52
|
+
try {
|
|
53
|
+
const probe = await check.probe(env);
|
|
54
|
+
return {
|
|
55
|
+
status: probe.status,
|
|
56
|
+
detail: probe.detail,
|
|
57
|
+
fix: probe.fix ?? null,
|
|
58
|
+
};
|
|
59
|
+
} catch (err) {
|
|
60
|
+
return {
|
|
61
|
+
status: 'fail',
|
|
62
|
+
detail: `probe falhou: ${err?.message || err}`,
|
|
63
|
+
fix: null,
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Executa os checks na ordem declarada.
|
|
70
|
+
*
|
|
71
|
+
* @param {{ checks: Check[], scope?: Scope|'all', env?: object }} opts
|
|
72
|
+
* @returns {Promise<Result[]>}
|
|
73
|
+
*/
|
|
74
|
+
export async function runChecks({ checks, scope = 'all', env = {} }) {
|
|
75
|
+
const selected = checks.filter((c) => scope === 'all' || c.scope === scope);
|
|
76
|
+
const statusById = new Map();
|
|
77
|
+
const results = [];
|
|
78
|
+
|
|
79
|
+
for (const check of selected) {
|
|
80
|
+
const base = {
|
|
81
|
+
id: check.id,
|
|
82
|
+
title: check.title,
|
|
83
|
+
severity: check.severity || SEVERITY_FALLBACK,
|
|
84
|
+
scope: check.scope,
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
// Cascata: sem a dependência de pé, este probe não tem o que observar. Propaga por cadeia, não
|
|
88
|
+
// só um nível — `skipped` conta como "não verificado" para quem depende dele.
|
|
89
|
+
const depStatus = check.dependsOn ? statusById.get(check.dependsOn) : null;
|
|
90
|
+
if (depStatus === 'fail' || depStatus === 'skipped') {
|
|
91
|
+
const motivo = depStatus === 'fail' ? 'que falhou' : 'que não foi verificado';
|
|
92
|
+
results.push({
|
|
93
|
+
...base,
|
|
94
|
+
status: 'skipped',
|
|
95
|
+
detail: `não verificado: depende de "${check.dependsOn}", ${motivo}`,
|
|
96
|
+
fix: null,
|
|
97
|
+
});
|
|
98
|
+
statusById.set(check.id, 'skipped');
|
|
99
|
+
continue;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const probe = await runProbe(check, env);
|
|
103
|
+
statusById.set(check.id, probe.status);
|
|
104
|
+
results.push({ ...base, ...probe });
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
return results;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
|
|
112
|
+
* é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
|
|
113
|
+
*
|
|
114
|
+
* @param {Result[]} results
|
|
115
|
+
* @returns {'ok'|'warn'|'fail'}
|
|
116
|
+
*/
|
|
117
|
+
export function worstStatus(results) {
|
|
118
|
+
let seenWarn = false;
|
|
119
|
+
|
|
120
|
+
for (const r of results) {
|
|
121
|
+
if (r.status === 'fail' && r.severity === 'critical') return 'fail';
|
|
122
|
+
if (r.status === 'fail' || r.status === 'warn') seenWarn = true;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
return seenWarn ? 'warn' : 'ok';
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Remove template literals do fonte antes de qualquer análise estática de `import`.
|
|
130
|
+
*
|
|
131
|
+
* Os geradores do Forja *escrevem* código NestJS dentro de crases — `import { Module } from
|
|
132
|
+
* '@nestjs/common'` é texto que eles emitem, não dependência que eles usam. Contá-lo faz o check
|
|
133
|
+
* acusar `@nestjs/core` como dependência não declarada e `./app.module` como import quebrado.
|
|
134
|
+
* Observado em campo ao auditar o tarball da 1.1.3.
|
|
135
|
+
*/
|
|
136
|
+
export function stripTemplateLiterals(source) {
|
|
137
|
+
return source.replace(/`(?:\\.|[^`\\])*`/gs, '``');
|
|
138
|
+
}
|