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.
@@ -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:build -- task my-project "payment feature"
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:build -- domain my-project
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:build -- global my-project
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:build -- global # Instead of domain
444
+ npm run context:smart -- global # Instead of domain
445
445
 
446
446
  # Or prune manually
447
- node scripts/compress-memory.mjs
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 search index
455
- npm run memory:db:reindex
454
+ # Rebuild the index (it is also what fixes a stale index)
455
+ npm run sync:universal
456
456
 
457
- # Check stats
458
- npm run memory:db:stats
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
- # Build context
477
- npm run context:build -- global my-project
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
- # Compress memory
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
- # Benchmark tokens
493
+ # Medir a economia
483
494
  npm run token:benchmark
484
495
 
485
- # Clean cache
486
- npm run cache:clear
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
- **Next**: See [DEPLOYMENT.md](DEPLOYMENT.md) for integration with CI/CD.
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
+ }