forjajs 5.1.0 → 5.3.1

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.
Files changed (119) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +52 -4
  3. package/README.pt-BR.md +54 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +365 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/exec.d.ts +55 -0
  36. package/dist/lib/exec.js +141 -0
  37. package/dist/lib/project-wiring.js +6 -2
  38. package/dist/lib/session-memory.d.ts +38 -0
  39. package/dist/lib/session-memory.js +206 -0
  40. package/dist/lib/spec-trace.d.ts +46 -0
  41. package/dist/lib/spec-trace.js +184 -0
  42. package/dist/packages/adapter-git/src/index.js +13 -4
  43. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  44. package/dist/packages/adapter-nest/src/index.js +59 -1
  45. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  46. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  47. package/dist/packages/context/src/index.d.ts +2 -0
  48. package/dist/packages/context/src/index.js +36 -15
  49. package/dist/packages/contracts/src/index.d.ts +64 -0
  50. package/dist/packages/core/src/index.d.ts +9 -1
  51. package/dist/packages/core/src/index.js +28 -3
  52. package/dist/packages/graph/src/index.js +14 -5
  53. package/dist/packages/llm/src/index.js +7 -24
  54. package/dist/packages/mcp/src/index.d.ts +8 -0
  55. package/dist/packages/mcp/src/index.js +12 -1
  56. package/dist/packages/observability/src/index.d.ts +11 -0
  57. package/dist/packages/observability/src/index.js +3 -0
  58. package/dist/packages/orchestration/src/index.d.ts +15 -1
  59. package/dist/packages/orchestration/src/index.js +127 -21
  60. package/dist/packages/planner/src/index.d.ts +7 -1
  61. package/dist/packages/planner/src/index.js +67 -10
  62. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  63. package/dist/packages/planner/src/proposal-store.js +109 -0
  64. package/dist/packages/policy/src/index.d.ts +9 -16
  65. package/dist/packages/policy/src/index.js +114 -31
  66. package/dist/packages/runtime/src/index.d.ts +16 -2
  67. package/dist/packages/runtime/src/index.js +176 -61
  68. package/dist/scripts/build-smart-context.d.ts +2 -0
  69. package/dist/scripts/build-smart-context.js +12 -3
  70. package/dist/scripts/code-context.d.ts +3 -1
  71. package/dist/scripts/code-context.js +13 -3
  72. package/dist/scripts/coverage-gate.d.ts +2 -0
  73. package/dist/scripts/coverage-gate.js +101 -0
  74. package/dist/scripts/eval-agents.d.ts +11 -0
  75. package/dist/scripts/eval-agents.js +96 -0
  76. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  77. package/dist/scripts/gen-commands-doc.js +18 -0
  78. package/dist/scripts/hook-session-memory.d.ts +9 -0
  79. package/dist/scripts/hook-session-memory.js +20 -0
  80. package/dist/scripts/hook-session-start.js +34 -0
  81. package/dist/scripts/llm-fit.js +15 -6
  82. package/dist/scripts/simulate.js +16 -4
  83. package/dist/scripts/spec-trace.d.ts +10 -0
  84. package/dist/scripts/spec-trace.js +73 -0
  85. package/dist/scripts/sync-universal-memory.js +69 -4
  86. package/dist/scripts/token-benchmark.d.ts +33 -1
  87. package/dist/scripts/token-benchmark.js +179 -5
  88. package/dist/scripts/token-economy.js +3 -1
  89. package/dist/scripts/tools-doctor.d.ts +16 -1
  90. package/dist/scripts/tools-doctor.js +58 -17
  91. package/docs/commands.md +155 -0
  92. package/docs/fluxo.md +11 -7
  93. package/docs/init-project.md +3 -1
  94. package/docs/llm-fit-loop.md +20 -0
  95. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  96. package/docs/produto/factsheet-marketing.md +7 -5
  97. package/docs/produto/roteiro-demo.md +14 -5
  98. package/docs/quick-reference.md +3 -3
  99. package/docs/token-optimization.md +10 -6
  100. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  101. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  102. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  103. package/package.json +4 -2
  104. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  105. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  106. package/specs/memoria-de-sessao/spec.md +48 -0
  107. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  108. package/specs/v6-core-consolidation/spec.md +70 -0
  109. package/specs/v6-docs-drift/spec.md +85 -0
  110. package/specs/v6-quality-gates/spec.md +104 -0
  111. package/specs/v6-token-economy/spec.md +84 -0
  112. package/templates/evals/agents/adr.json +25 -0
  113. package/templates/evals/agents/memoria.json +32 -0
  114. package/templates/evals/agents/proxima-acao.json +29 -0
  115. package/templates/evals/agents/spec-nova.json +26 -0
  116. package/templates/evals/agents/teste-do-criterio.json +29 -0
  117. package/templates/project/AGENTS.md +7 -0
  118. package/templates/project/CLAUDE.md +3 -2
  119. package/templates/project/skills/testing/SKILL.md +1 -1
@@ -0,0 +1,365 @@
1
+ /**
2
+ * lib/agent-evals.ts — avaliações com agentes reais em projeto descartável (SPEC-054, ADR-0093).
3
+ *
4
+ * Cada caso é um dado (`templates/evals/agents/*.json`): prompt, semente e checks determinísticos.
5
+ * O runner cria workspace e projeto num diretório temporário, aplica a semente, roda o agente
6
+ * (Claude Code ou Codex) com escrita confinada a esses diretórios e corrige pelo que ficou no disco,
7
+ * pelos comandos executados e pela resposta. Nunca roda no projeto do usuário.
8
+ */
9
+ import crypto from 'node:crypto';
10
+ import fs from 'node:fs';
11
+ import os from 'node:os';
12
+ import path from 'node:path';
13
+ import { spawnSync } from 'node:child_process';
14
+ import { traceSpecs } from './spec-trace.js';
15
+ import { resolveCommand, runShell, quoteCmdArg } from './exec.js';
16
+ const CHECK_TYPES = new Set(['file', 'answer', 'ran', 'criterion', 'command', 'unchanged']);
17
+ export function validateCase(c, source = 'caso') {
18
+ const fail = (msg) => { throw new Error(`${source}: ${msg}`); };
19
+ if (!c || typeof c !== 'object')
20
+ fail('não é um objeto');
21
+ if (typeof c.id !== 'string' || !/^[a-z0-9-]+$/.test(c.id))
22
+ fail('id ausente ou fora de kebab-case');
23
+ if (typeof c.prompt !== 'string' || !c.prompt.trim())
24
+ fail('prompt ausente');
25
+ if (!Array.isArray(c.checks) || !c.checks.length)
26
+ fail('sem checks');
27
+ for (const k of c.checks) {
28
+ if (!CHECK_TYPES.has(k?.type))
29
+ fail(`check de tipo desconhecido: ${k?.type}`);
30
+ if (typeof k.desc !== 'string' || !k.desc)
31
+ fail(`check ${k.type} sem desc`);
32
+ for (const re of [...(k.contains ?? []), ...(k.matches ? [k.matches].flat() : [])]) {
33
+ try {
34
+ new RegExp(re);
35
+ }
36
+ catch {
37
+ fail(`regex inválida em "${k.desc}": ${re}`);
38
+ }
39
+ }
40
+ }
41
+ for (const rel of Object.keys(c.seed?.files ?? {})) {
42
+ if (path.isAbsolute(rel) || rel.split('/').includes('..'))
43
+ fail(`semente fora do projeto: ${rel}`);
44
+ }
45
+ return { title: c.id, ...c };
46
+ }
47
+ export function loadCases(dir) {
48
+ return fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort()
49
+ .map((n) => validateCase(JSON.parse(fs.readFileSync(path.join(dir, n), 'utf8')), n));
50
+ }
51
+ /** Glob mínimo: `**` atravessa pastas, `*` não; o resto é literal. */
52
+ export function globToRegExp(glob) {
53
+ let re = '';
54
+ for (let i = 0; i < glob.length; i++) {
55
+ const ch = glob[i];
56
+ if (ch === '*' && glob[i + 1] === '*') {
57
+ re += glob[i + 2] === '/' ? '(?:.*/)?' : '.*';
58
+ i += glob[i + 2] === '/' ? 2 : 1;
59
+ }
60
+ else if (ch === '*')
61
+ re += '[^/]*';
62
+ else
63
+ re += ch.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
64
+ }
65
+ return new RegExp(`^${re}$`);
66
+ }
67
+ /** Arquivos que o próprio Forja gera durante a sessão (hooks, índice): não contam como mudança do agente. */
68
+ const SNAPSHOT_SKIP = new Set(['node_modules', '.git', '.context', '.forja', '.memory']);
69
+ /** Índice SQLite (atualizado por query:universal/sync) e checkpoints de sessão (hooks). */
70
+ const FORJA_GENERATED = new Set(['memory/sqlite', 'memory/60-runs/sessions']);
71
+ export function snapshot(dir) {
72
+ const out = new Map();
73
+ const walk = (abs, rel) => {
74
+ for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
75
+ if (SNAPSHOT_SKIP.has(e.name))
76
+ continue;
77
+ const r = rel ? `${rel}/${e.name}` : e.name;
78
+ if (FORJA_GENERATED.has(r))
79
+ continue;
80
+ const p = path.join(abs, e.name);
81
+ if (e.isDirectory())
82
+ walk(p, r);
83
+ else if (e.isFile())
84
+ out.set(r, crypto.createHash('sha1').update(fs.readFileSync(p)).digest('hex'));
85
+ }
86
+ };
87
+ walk(dir, '');
88
+ return out;
89
+ }
90
+ /** Comandos que o Claude pode rodar sem perguntar. Fora disso, `-p` nega (e o caso mostra). */
91
+ export const CLAUDE_ALLOWED_TOOLS = [
92
+ 'Read', 'Grep', 'Glob', 'Edit', 'Write', 'MultiEdit', 'mcp__forja',
93
+ 'Bash(forja *)', 'Bash(node --test*)', 'Bash(npm test*)', 'Bash(npm run test*)',
94
+ 'Bash(ls*)', 'Bash(cat *)', 'Bash(mkdir *)', 'Bash(git status*)', 'Bash(git diff*)', 'Bash(git log*)',
95
+ ];
96
+ export function parseClaudeStream(stdout) {
97
+ const events = stdout.split('\n').filter(Boolean).map((l) => { try {
98
+ return JSON.parse(l);
99
+ }
100
+ catch {
101
+ return null;
102
+ } }).filter(Boolean);
103
+ const result = events.find((e) => e.type === 'result');
104
+ const denied = new Set((result?.permission_denials ?? []).map((d) => d?.tool_use_id).filter(Boolean));
105
+ const commands = [];
106
+ for (const e of events) {
107
+ if (e.type !== 'assistant' || !Array.isArray(e.message?.content))
108
+ continue;
109
+ for (const c of e.message.content) {
110
+ if (c?.type !== 'tool_use' || denied.has(c.id))
111
+ continue;
112
+ if (c.name === 'Bash' && typeof c.input?.command === 'string')
113
+ commands.push(c.input.command);
114
+ else if (typeof c.name === 'string' && c.name.startsWith('mcp__'))
115
+ commands.push(`tool:${c.name}`);
116
+ }
117
+ }
118
+ const u = result?.usage;
119
+ return {
120
+ answer: typeof result?.result === 'string' ? result.result : '',
121
+ commands,
122
+ costUsd: typeof result?.total_cost_usd === 'number' ? result.total_cost_usd : null,
123
+ tokens: u ? { input: (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0), output: u.output_tokens ?? 0 } : null,
124
+ ...(result ? (result.is_error ? { error: String(result.subtype ?? 'erro') } : {}) : { error: 'sem evento result' }),
125
+ };
126
+ }
127
+ export function parseCodexJson(stdout) {
128
+ const events = stdout.split('\n').filter(Boolean).map((l) => { try {
129
+ return JSON.parse(l);
130
+ }
131
+ catch {
132
+ return null;
133
+ } }).filter(Boolean);
134
+ const commands = [];
135
+ let answer = '';
136
+ let input = 0, output = 0, sawUsage = false, failed;
137
+ for (const e of events) {
138
+ if (e.type === 'item.completed' && e.item?.type === 'command_execution' && typeof e.item.command === 'string') {
139
+ // Codex embrulha em `bash -lc '<cmd>'`.
140
+ const m = e.item.command.match(/^(?:\/\S*\/)?(?:ba)?sh\s+-l?c\s+(['"]?)([\s\S]*)\1$/);
141
+ commands.push(m ? m[2] : e.item.command);
142
+ }
143
+ if (e.type === 'item.completed' && e.item?.type === 'agent_message' && typeof e.item.text === 'string')
144
+ answer = e.item.text;
145
+ if (e.type === 'turn.completed' && e.usage) {
146
+ sawUsage = true;
147
+ input += (e.usage.input_tokens ?? 0);
148
+ output += (e.usage.output_tokens ?? 0) + (e.usage.reasoning_output_tokens ?? 0);
149
+ }
150
+ if (e.type === 'turn.failed' || e.type === 'error')
151
+ failed = String(e.error?.message ?? e.message ?? e.type);
152
+ }
153
+ return { answer, commands, costUsd: null, tokens: sawUsage ? { input, output } : null, ...(failed ? { error: failed } : {}) };
154
+ }
155
+ function timed(bin, args, ctx) {
156
+ const t0 = Date.now();
157
+ const resolved = resolveCommand(bin) ?? bin;
158
+ const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
159
+ const r = isCmd
160
+ ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" ${args.map(quoteCmdArg).join(' ')}"`], { cwd: ctx.projectDir, env: ctx.env, encoding: 'utf8', timeout: ctx.timeoutMs, input: '', maxBuffer: 256 * 1024 * 1024, windowsVerbatimArguments: true })
161
+ : spawnSync(resolved, args, { cwd: ctx.projectDir, env: ctx.env, encoding: 'utf8', timeout: ctx.timeoutMs, input: '', maxBuffer: 256 * 1024 * 1024 });
162
+ const timedOut = r.error && r.error.code === 'ETIMEDOUT';
163
+ return { r, durationMs: Date.now() - t0, timedOut: Boolean(timedOut) };
164
+ }
165
+ function cliVersion(bin) {
166
+ const resolved = resolveCommand(bin) ?? bin;
167
+ const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
168
+ const r = isCmd
169
+ ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" --version"`], { encoding: 'utf8', timeout: 15_000, windowsVerbatimArguments: true })
170
+ : spawnSync(resolved, ['--version'], { encoding: 'utf8', timeout: 15_000 });
171
+ return r.status === 0 ? (r.stdout || '').trim().split('\n')[0] : null;
172
+ }
173
+ export const claudeAdapter = (bin = 'claude') => ({
174
+ name: 'claude',
175
+ version: () => cliVersion(bin),
176
+ run(ctx) {
177
+ const args = ['-p', ctx.prompt, '--output-format', 'stream-json', '--verbose',
178
+ '--permission-mode', 'acceptEdits', '--add-dir', ctx.workspaceDir,
179
+ '--max-budget-usd', String(ctx.budgetUsd), '--no-session-persistence',
180
+ ...(ctx.model ? ['--model', ctx.model] : []),
181
+ '--allowedTools', ...CLAUDE_ALLOWED_TOOLS];
182
+ const { r, durationMs, timedOut } = timed(bin, args, ctx);
183
+ const parsed = parseClaudeStream(r.stdout || '');
184
+ return { ...parsed, durationMs, exitCode: r.status ?? 1, ...(timedOut ? { error: `timeout (${ctx.timeoutMs} ms)` } : {}) };
185
+ },
186
+ });
187
+ export const codexAdapter = (bin = 'codex') => ({
188
+ name: 'codex',
189
+ version: () => cliVersion(bin),
190
+ run(ctx) {
191
+ const args = ['exec', '--json', '--ephemeral', '--skip-git-repo-check',
192
+ '-s', 'workspace-write', '-C', ctx.projectDir, '--add-dir', ctx.workspaceDir,
193
+ ...(ctx.model ? ['-m', ctx.model] : []), ctx.prompt];
194
+ const { r, durationMs, timedOut } = timed(bin, args, ctx);
195
+ const parsed = parseCodexJson(r.stdout || '');
196
+ return { ...parsed, durationMs, exitCode: r.status ?? 1, ...(timedOut ? { error: `timeout (${ctx.timeoutMs} ms)` } : {}) };
197
+ },
198
+ });
199
+ export const ADAPTERS = {
200
+ claude: () => claudeAdapter(process.env.FORJA_EVAL_CLAUDE_BIN || 'claude'),
201
+ codex: () => codexAdapter(process.env.FORJA_EVAL_CODEX_BIN || 'codex'),
202
+ };
203
+ const rx = (s) => new RegExp(s, 'im');
204
+ export function grade(check, projectDir, run, before, env) {
205
+ const res = (ok, detail) => ({ desc: check.desc, type: check.type, ok, detail });
206
+ switch (check.type) {
207
+ case 'file': {
208
+ const re = globToRegExp(check.glob);
209
+ const ex = (check.exclude ?? []).map(globToRegExp);
210
+ const after = snapshot(projectDir);
211
+ const files = [...after.keys()].filter((f) => re.test(f) && !ex.some((e) => e.test(f)));
212
+ if (!files.length)
213
+ return res(false, `nenhum arquivo em ${check.glob}`);
214
+ const missing = (f) => (check.contains ?? []).filter((c) => !rx(c).test(fs.readFileSync(path.join(projectDir, f), 'utf8')));
215
+ const hit = files.find((f) => missing(f).length === 0);
216
+ return hit ? res(true, hit) : res(false, `${files[0]}: falta ${missing(files[0]).join(', ')}`);
217
+ }
218
+ case 'answer': {
219
+ const miss = check.matches.filter((m) => !rx(m).test(run.answer));
220
+ return miss.length ? res(false, `resposta sem ${miss.join(', ')}`) : res(true, 'resposta confere');
221
+ }
222
+ case 'ran': {
223
+ const hit = run.commands.find((c) => rx(check.matches).test(c));
224
+ return hit ? res(true, hit.slice(0, 120)) : res(false, `nenhum comando casou /${check.matches}/ (${run.commands.length} executados)`);
225
+ }
226
+ case 'criterion': {
227
+ const spec = traceSpecs(projectDir).specs.find((s) => s.slug === check.spec || s.specId === check.spec);
228
+ const c = spec?.criteria.find((x) => x.id === check.ac);
229
+ if (!c)
230
+ return res(false, `${check.spec} ${check.ac} não existe`);
231
+ return c.tests.length ? res(true, c.tests.map((t) => `${t.file}:${t.line}`).join(', ')) : res(false, 'nenhum teste cita o critério');
232
+ }
233
+ case 'command': {
234
+ const r = runShell(check.run, { cwd: projectDir, env, timeoutMs: 120_000 });
235
+ const want = check.expectExit ?? 0;
236
+ const tail = `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-2).join(' | ').slice(0, 200);
237
+ return r.status === want ? res(true, `exit ${r.status}`) : res(false, `exit ${r.status} (esperado ${want}): ${tail}`);
238
+ }
239
+ case 'unchanged': {
240
+ const re = globToRegExp(check.glob);
241
+ const after = snapshot(projectDir);
242
+ const keys = new Set([...before.keys(), ...after.keys()].filter((f) => re.test(f)));
243
+ const changed = [...keys].filter((f) => before.get(f) !== after.get(f));
244
+ return changed.length ? res(false, `mudou: ${changed.slice(0, 5).join(', ')}`) : res(true, 'nada mudou');
245
+ }
246
+ }
247
+ }
248
+ /** Workspace + projeto descartáveis, com um `forja` no PATH apontando para a instalação em teste. */
249
+ export function prepareProject(baseDir, name, forjaBin) {
250
+ const bin = path.join(baseDir, 'bin');
251
+ fs.mkdirSync(bin, { recursive: true });
252
+ if (process.platform === 'win32') {
253
+ const shim = path.join(bin, 'forja.cmd');
254
+ if (!fs.existsSync(shim))
255
+ fs.writeFileSync(shim, `@echo off\r\n"${process.execPath}" "${forjaBin}" %*\r\n`);
256
+ }
257
+ else {
258
+ const shim = path.join(bin, 'forja');
259
+ if (!fs.existsSync(shim)) {
260
+ fs.writeFileSync(shim, `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(forjaBin)} "$@"\n`);
261
+ fs.chmodSync(shim, 0o755);
262
+ }
263
+ }
264
+ const ws = path.join(baseDir, 'ws');
265
+ const env = { ...process.env, FORJA_WORKSPACE: ws, PATH: `${bin}${path.delimiter}${process.env.PATH ?? ''}` };
266
+ for (const k of Object.keys(env))
267
+ if (k.startsWith('npm_'))
268
+ delete env[k];
269
+ const forja = (args, cwd) => {
270
+ const r = spawnSync(process.execPath, [forjaBin, ...args], { cwd, env, encoding: 'utf8', timeout: 180_000 });
271
+ if (r.status !== 0)
272
+ throw new Error(`forja ${args.join(' ')} falhou: ${`${r.stdout}${r.stderr}`.trim().split('\n').slice(-3).join(' | ')}`);
273
+ };
274
+ if (!fs.existsSync(ws))
275
+ forja(['workspace:init'], baseDir);
276
+ forja(['project:new', name, '--ai', 'claude,codex', '--skip-backend'], baseDir);
277
+ return { ws, proj: path.join(ws, 'projects', name), env };
278
+ }
279
+ const ANSWER_EXCERPT = 400;
280
+ export function runCase(c, adapter, baseDir, opts) {
281
+ const t0 = Date.now();
282
+ let prepared;
283
+ try {
284
+ prepared = prepareProject(baseDir, `caso-${c.id}`, opts.forjaBin);
285
+ }
286
+ catch (e) {
287
+ return { id: c.id, title: c.title, pass: false, checks: [], costUsd: null, durationMs: Date.now() - t0, commands: 0, answer: '', error: e.message };
288
+ }
289
+ const { ws, proj, env } = prepared;
290
+ for (const [rel, content] of Object.entries(c.seed?.files ?? {})) {
291
+ fs.mkdirSync(path.dirname(path.join(proj, rel)), { recursive: true });
292
+ fs.writeFileSync(path.join(proj, rel), content);
293
+ }
294
+ spawnSync(process.execPath, [opts.forjaBin, 'sync:universal'], { cwd: proj, env, encoding: 'utf8', timeout: 120_000 });
295
+ const before = snapshot(proj);
296
+ const run = adapter.run({ projectDir: proj, workspaceDir: ws, prompt: c.prompt, env, model: opts.model, budgetUsd: opts.budgetUsd, timeoutMs: opts.timeoutMs });
297
+ const checks = c.checks.map((k) => {
298
+ try {
299
+ return grade(k, proj, run, before, env);
300
+ }
301
+ catch (e) {
302
+ return { desc: k.desc, type: k.type, ok: false, detail: `erro no check: ${e.message}` };
303
+ }
304
+ });
305
+ return {
306
+ id: c.id, title: c.title, pass: checks.every((k) => k.ok) && !run.error, checks,
307
+ costUsd: run.costUsd, durationMs: run.durationMs, commands: run.commands.length,
308
+ answer: run.answer.slice(0, ANSWER_EXCERPT),
309
+ ...(run.error ? { error: run.error } : {}),
310
+ };
311
+ }
312
+ export function runSuite(cases, adapter, forjaVersion, opts) {
313
+ const base = fs.mkdtempSync(path.join(os.tmpdir(), `forja-eval-${adapter.name}-`));
314
+ const results = [];
315
+ try {
316
+ for (const c of cases) {
317
+ const r = runCase(c, adapter, base, opts);
318
+ results.push(r);
319
+ opts.onCase?.(c, r);
320
+ }
321
+ }
322
+ finally {
323
+ if (!opts.keep)
324
+ fs.rmSync(base, { recursive: true, force: true });
325
+ }
326
+ const costs = results.map((r) => r.costUsd).filter((x) => typeof x === 'number');
327
+ return {
328
+ ts: new Date().toISOString(), agent: adapter.name, agentVersion: adapter.version(), model: opts.model ?? null, forjaVersion,
329
+ cases: results, passed: results.filter((r) => r.pass).length,
330
+ costUsd: costs.length ? Math.round(costs.reduce((a, b) => a + b, 0) * 10_000) / 10_000 : null,
331
+ };
332
+ }
333
+ // ─── Histórico ─────────────────────────────────────────────────────────────────
334
+ export function appendHistory(file, result) {
335
+ fs.mkdirSync(path.dirname(file), { recursive: true });
336
+ fs.appendFileSync(file, `${JSON.stringify(result)}\n`, 'utf8');
337
+ }
338
+ /** Última execução do mesmo agente e modelo, para comparar. */
339
+ export function previousRun(file, agent, model) {
340
+ let lines = [];
341
+ try {
342
+ lines = fs.readFileSync(file, 'utf8').trim().split('\n');
343
+ }
344
+ catch {
345
+ return null;
346
+ }
347
+ for (let i = lines.length - 1; i >= 0; i--) {
348
+ try {
349
+ const r = JSON.parse(lines[i]);
350
+ if (r.agent === agent && (r.model ?? null) === model)
351
+ return r;
352
+ }
353
+ catch { /* linha corrompida: ignora */ }
354
+ }
355
+ return null;
356
+ }
357
+ export function compareRuns(prev, cur) {
358
+ if (!prev)
359
+ return { regressed: [], fixed: [] };
360
+ const was = new Map(prev.cases.map((c) => [c.id, c.pass]));
361
+ return {
362
+ regressed: cur.cases.filter((c) => was.get(c.id) === true && !c.pass).map((c) => c.id),
363
+ fixed: cur.cases.filter((c) => was.get(c.id) === false && c.pass).map((c) => c.id),
364
+ };
365
+ }
@@ -10,8 +10,20 @@
10
10
  * O stdout carrega **um único** objeto JSON, sempre. Diagnóstico verboso vai para o stderr.
11
11
  * Use só no ramo `--json`; a saída de texto de cada comando continua como está.
12
12
  */
13
+ import fs from 'node:fs';
14
+ /**
15
+ * Escreve até o último byte antes de devolver. `process.stdout.write` + `process.exit()` trunca no
16
+ * tamanho do buffer do pipe (64KB): o JSON de `spec:trace --json` saía cortado e quem fazia parse
17
+ * recebia "Unterminated string in JSON" — sem erro do comando, exit 0. `fs.writeSync` bloqueia, e o
18
+ * laço cobre o caso de escrita parcial.
19
+ */
20
+ function writeAll(fd, text) {
21
+ const buf = Buffer.from(text, 'utf8');
22
+ for (let offset = 0; offset < buf.length;)
23
+ offset += fs.writeSync(fd, buf, offset, buf.length - offset);
24
+ }
13
25
  function write(payload, code) {
14
- process.stdout.write(JSON.stringify(payload) + '\n');
26
+ writeAll(1, JSON.stringify(payload) + '\n');
15
27
  process.exit(code);
16
28
  }
17
29
  /** Sucesso. `fields` são os dados do comando, no topo, ao lado de `status`. */
@@ -24,7 +36,7 @@ export function emitOk(fields = {}) {
24
36
  */
25
37
  export function emitError(message, opts = {}) {
26
38
  if (opts.detail)
27
- process.stderr.write(opts.detail.replace(/\s+$/, '') + '\n');
39
+ writeAll(2, opts.detail.replace(/\s+$/, '') + '\n');
28
40
  const error = { message };
29
41
  if (opts.code)
30
42
  error.code = opts.code;
@@ -14,6 +14,28 @@ export interface CodeContextEnv {
14
14
  }
15
15
  /** Tokens ≈ bytes/4 — o mesmo proxy do resto do framework. */
16
16
  export declare function estimateTokens(text: string): number;
17
+ /**
18
+ * Orçamento do código anexado por padrão (SPEC-057 AC-4). Uma fatia grande tem dezenas de arquivos e
19
+ * `--code` lia todos por inteiro — janela gasta com apresentação e ORM antes de chegar na regra.
20
+ * `--full` devolve o comportamento antigo.
21
+ */
22
+ export declare const CODE_TOKEN_BUDGET = 6000;
23
+ export interface CodeFile {
24
+ path: string;
25
+ tokens: number;
26
+ content: string;
27
+ }
28
+ /**
29
+ * Ordem de leitura da fatia: quem casa com o termo vem primeiro (caminho pesa mais que conteúdo —
30
+ * `order.entity.ts` é sobre a entidade, um arquivo que só a menciona não), desempate por camada e
31
+ * depois por caminho, para a mesma consulta dar sempre o mesmo pacote.
32
+ */
33
+ export declare function byRelevance(files: CodeFile[], terms: string[]): CodeFile[];
34
+ /** Pega arquivos na ordem até estourar o orçamento; devolve também o que ficou de fora. */
35
+ export declare function withinBudget(files: CodeFile[], budget: number): {
36
+ kept: CodeFile[];
37
+ omitted: CodeFile[];
38
+ };
17
39
  /** Domínios disponíveis num projeto: os diretórios sob `memory/30-domains/`. */
18
40
  export declare function domainsOf(projectRoot: string, env?: CodeContextEnv): string[];
19
41
  export interface ContextPack {
@@ -22,20 +44,26 @@ export interface ContextPack {
22
44
  mapPath: string | null;
23
45
  map: string | null;
24
46
  mapTokens: number;
25
- code: {
47
+ code: CodeFile[];
48
+ codeTokens: number;
49
+ /** Arquivos da fatia que o orçamento deixou de fora — sempre à mostra, nunca corte calado. */
50
+ codeOmitted: {
26
51
  path: string;
27
52
  tokens: number;
28
- content: string;
29
53
  }[];
30
- codeTokens: number;
31
54
  totalTokens: number;
32
55
  }
33
56
  /**
34
57
  * Monta o pacote de um domínio. Por padrão só o mapa (`context.md`) — o contexto barato que substitui
35
- * a exploração. Com `includeCode`, anexa o código da fatia — o que se lê ao *editar*.
58
+ * a exploração. Com `includeCode`, anexa o código da fatia — o que se lê ao *editar* — na ordem de
59
+ * relevância e até `budget` tokens; `full: true` anexa a fatia inteira (comportamento pré-SPEC-057,
60
+ * e o que o `token:economy` precisa para medir o custo de ler tudo).
36
61
  */
37
- export declare function buildContextPack({ projectRoot, domain, includeCode }: {
62
+ export declare function buildContextPack({ projectRoot, domain, includeCode, query, full, budget, }: {
38
63
  projectRoot: string;
39
64
  domain: string;
40
65
  includeCode?: boolean;
66
+ query?: string;
67
+ full?: boolean;
68
+ budget?: number;
41
69
  }, env?: CodeContextEnv): ContextPack;
@@ -15,6 +15,62 @@ const defaultFsEnv = { fs };
15
15
  export function estimateTokens(text) {
16
16
  return Math.round(text.length / 4);
17
17
  }
18
+ /**
19
+ * Orçamento do código anexado por padrão (SPEC-057 AC-4). Uma fatia grande tem dezenas de arquivos e
20
+ * `--code` lia todos por inteiro — janela gasta com apresentação e ORM antes de chegar na regra.
21
+ * `--full` devolve o comportamento antigo.
22
+ */
23
+ export const CODE_TOKEN_BUDGET = 6000;
24
+ /**
25
+ * Camadas mais informativas primeiro: é em `domain/` que a invariante mora, e `presentation/` é a
26
+ * camada que um agente quase sempre já sabe como é.
27
+ */
28
+ const LAYER_ORDER = ['domain', 'application', 'infrastructure', 'presentation'];
29
+ /**
30
+ * Caminho relativo como o pacote o mostra: com `/`. O pack é texto colado no contexto de um agente —
31
+ * no Windows o separador nativo faria o mesmo domínio produzir dois pacotes diferentes (e quebraria
32
+ * a igualdade que os testes de contrato dependem).
33
+ */
34
+ function relFrom(root, target) {
35
+ return path.relative(root, target).split(path.sep).join('/');
36
+ }
37
+ /**
38
+ * Ordem de leitura da fatia: quem casa com o termo vem primeiro (caminho pesa mais que conteúdo —
39
+ * `order.entity.ts` é sobre a entidade, um arquivo que só a menciona não), desempate por camada e
40
+ * depois por caminho, para a mesma consulta dar sempre o mesmo pacote.
41
+ */
42
+ export function byRelevance(files, terms) {
43
+ const hits = (f) => {
44
+ const rel = f.path.toLowerCase();
45
+ const body = f.content.toLowerCase();
46
+ return terms.reduce((acc, t) => {
47
+ const inPath = rel.includes(t) ? 3 : 0;
48
+ const inBody = body.split(t).length - 1;
49
+ return acc + inPath + Math.min(inBody, 5);
50
+ }, 0);
51
+ };
52
+ const layer = (f) => {
53
+ const rel = f.path.toLowerCase();
54
+ const at = LAYER_ORDER.findIndex((l) => rel.includes(`/${l}/`));
55
+ return at === -1 ? LAYER_ORDER.length : at;
56
+ };
57
+ return [...files].sort((a, b) => hits(b) - hits(a) || layer(a) - layer(b) || a.path.localeCompare(b.path));
58
+ }
59
+ /** Pega arquivos na ordem até estourar o orçamento; devolve também o que ficou de fora. */
60
+ export function withinBudget(files, budget) {
61
+ const kept = [];
62
+ const omitted = [];
63
+ let used = 0;
64
+ for (const f of files) {
65
+ if (used + f.tokens > budget && kept.length > 0)
66
+ omitted.push(f);
67
+ else {
68
+ kept.push(f);
69
+ used += f.tokens;
70
+ }
71
+ }
72
+ return { kept, omitted };
73
+ }
18
74
  /** Domínios disponíveis num projeto: os diretórios sob `memory/30-domains/`. */
19
75
  export function domainsOf(projectRoot, env = defaultFsEnv) {
20
76
  const dir = path.join(projectRoot, 'memory', '30-domains');
@@ -69,14 +125,16 @@ function moduleFiles(projectRoot, domain, env) {
69
125
  }
70
126
  /**
71
127
  * Monta o pacote de um domínio. Por padrão só o mapa (`context.md`) — o contexto barato que substitui
72
- * a exploração. Com `includeCode`, anexa o código da fatia — o que se lê ao *editar*.
128
+ * a exploração. Com `includeCode`, anexa o código da fatia — o que se lê ao *editar* — na ordem de
129
+ * relevância e até `budget` tokens; `full: true` anexa a fatia inteira (comportamento pré-SPEC-057,
130
+ * e o que o `token:economy` precisa para medir o custo de ler tudo).
73
131
  */
74
- export function buildContextPack({ projectRoot, domain, includeCode = false }, env = defaultFsEnv) {
132
+ export function buildContextPack({ projectRoot, domain, includeCode = false, query = '', full = false, budget = CODE_TOKEN_BUDGET, }, env = defaultFsEnv) {
75
133
  // Allowlist against the domains the project actually declares (memory/30-domains/*) — rejects early
76
134
  // rather than sanitizing, since it's information this function already has and a traversal payload
77
135
  // (e.g. "../../etc") can never literally equal one of those directory names.
78
136
  if (!domainsOf(projectRoot, env).includes(domain)) {
79
- return { domain, found: false, mapPath: null, map: null, mapTokens: 0, code: [], codeTokens: 0, totalTokens: 0 };
137
+ return { domain, found: false, mapPath: null, map: null, mapTokens: 0, code: [], codeTokens: 0, codeOmitted: [], totalTokens: 0 };
80
138
  }
81
139
  const mapPath = path.join(projectRoot, 'memory', '30-domains', domain, 'context.md');
82
140
  let map = null;
@@ -87,7 +145,9 @@ export function buildContextPack({ projectRoot, domain, includeCode = false }, e
87
145
  map = null;
88
146
  }
89
147
  const code = [];
148
+ let codeOmitted = [];
90
149
  if (includeCode) {
150
+ const files = [];
91
151
  for (const file of moduleFiles(projectRoot, domain, env)) {
92
152
  let content = '';
93
153
  try {
@@ -96,19 +156,24 @@ export function buildContextPack({ projectRoot, domain, includeCode = false }, e
96
156
  catch {
97
157
  continue;
98
158
  }
99
- code.push({ path: path.relative(projectRoot, file), tokens: estimateTokens(content), content });
159
+ files.push({ path: relFrom(projectRoot, file), tokens: estimateTokens(content), content });
100
160
  }
161
+ const ordered = byRelevance(files, query.toLowerCase().split(/\s+/).filter(Boolean));
162
+ const cut = full ? { kept: ordered, omitted: [] } : withinBudget(ordered, budget);
163
+ code.push(...cut.kept);
164
+ codeOmitted = cut.omitted.map(({ path: rel, tokens }) => ({ path: rel, tokens }));
101
165
  }
102
166
  const mapTokens = map ? estimateTokens(map) : 0;
103
167
  const codeTokens = code.reduce((acc, c) => acc + c.tokens, 0);
104
168
  return {
105
169
  domain,
106
170
  found: map != null,
107
- mapPath: map != null ? path.relative(projectRoot, mapPath) : null,
171
+ mapPath: map != null ? relFrom(projectRoot, mapPath) : null,
108
172
  map,
109
173
  mapTokens,
110
174
  code,
111
175
  codeTokens,
176
+ codeOmitted,
112
177
  totalTokens: mapTokens + codeTokens,
113
178
  };
114
179
  }
@@ -13,6 +13,40 @@
13
13
  * `auth:jwt` são sintaxe FTS inválida e a query inteira lança — e o modo task voltava vazio.
14
14
  */
15
15
  export declare function ftsQuery(keyword: string): string;
16
+ /**
17
+ * Nó curto entra inteiro (SPEC-057 AC-1). ~400 tokens na régua bytes/4 que o framework usa em todo
18
+ * lugar: abaixo disso, cortar economiza migalha e perde o contexto que dava sentido ao trecho.
19
+ */
20
+ export declare const FULL_CONTENT_MAX_CHARS: number;
21
+ /** Raio do `snippet()` do FTS5 — em tokens, não em chars: ±24 tokens em volta de cada casamento. */
22
+ export declare const SNIPPET_RADIUS_TOKENS = 24;
23
+ interface MemoryNode {
24
+ title: string;
25
+ path: string;
26
+ content: string;
27
+ /** Trecho casado (FTS `snippet()` ou janela em volta do LIKE). Ausente → cabeça do nó. */
28
+ excerpt?: string;
29
+ }
30
+ export interface BuildOptions {
31
+ /** `--full-context`: injeta o conteúdo integral de todo nó, sem corte (opt-out do AC-1). */
32
+ full?: boolean;
33
+ }
34
+ /** Cabeça do nó cortada em fronteira de linha: corte no meio de uma linha parece arquivo corrompido. */
35
+ export declare function headExcerpt(content: string, max?: number): string;
36
+ /**
37
+ * Janela em volta da primeira ocorrência do termo — para os nós que o LIKE acha e o FTS não (o
38
+ * porter não casa substring no meio de palavra, e é justamente esse o caso que cai aqui). O raio é o
39
+ * mesmo do `snippet()` em chars (tokens × 4, a régua do repo): dois produtores de trecho, um orçamento.
40
+ */
41
+ export declare function excerptAround(content: string, needle: string, radius?: number): string;
42
+ /**
43
+ * O que entra no pack por nó. Retorna também quantos chars ficaram de fora — a omissão é sempre
44
+ * visível, porque corte calado é o agente raciocinando sobre metade da regra e não sabendo.
45
+ */
46
+ export declare function nodeBody(node: MemoryNode, opts?: BuildOptions): {
47
+ text: string;
48
+ omitted: number;
49
+ };
16
50
  export declare class ContextBuilder {
17
51
  projectPath: string;
18
52
  dbPath: string;
@@ -36,7 +70,7 @@ export declare class ContextBuilder {
36
70
  * @param {string} keyword - Palavra-chave para busca (modo 'task')
37
71
  * @returns {string} Conteúdo do contexto em markdown
38
72
  */
39
- build(mode: any, project: any, keyword?: string): string;
73
+ build(mode: any, project: any, keyword?: string, opts?: BuildOptions): string;
40
74
  /**
41
75
  * Obter contexto global (mission, standards, padrões)
42
76
  */
@@ -47,12 +81,23 @@ export declare class ContextBuilder {
47
81
  _getDomainNodes(project: any): any;
48
82
  /**
49
83
  * Obter contexto orientado a tarefa (busca por FTS5)
84
+ *
85
+ * Duas consultas, não uma: a do FTS já devolve o trecho casado via `snippet()` — injetar o nó
86
+ * inteiro era o maior sorvedouro de token do pack (SPEC-057). O `LIKE` cobre o que o porter não
87
+ * casa (substring no meio de palavra) e ganha uma janela calculada aqui, porque fora do FTS não
88
+ * existe `snippet()` para destacar o casamento.
50
89
  */
51
- _getTaskNodes(project: any, keyword: any): any;
90
+ _getTaskNodes(project: any, keyword: any, limit?: number): MemoryNode[];
91
+ _ftsTaskNodes(project: string, keyword: string, limit: number): MemoryNode[];
92
+ _likeTaskNodes(project: string, keyword: string, fts: string, limit: number): MemoryNode[];
52
93
  /**
53
94
  * Gerar markdown deduplicado
54
95
  */
55
- _generateMarkdown(mode: any, project: any, keyword: any, nodes: any, seenPaths: any): string;
96
+ _generateMarkdown(mode: any, project: any, keyword: any, nodes: MemoryNode[], seenPaths: Set<string>, opts?: BuildOptions): {
97
+ markdown: string;
98
+ shown: number;
99
+ excerpted: number;
100
+ };
56
101
  /**
57
102
  * Salvar contexto em arquivo
58
103
  */
@@ -60,7 +105,7 @@ export declare class ContextBuilder {
60
105
  /**
61
106
  * Estatísticas de contexto
62
107
  */
63
- stats(mode: any, project: any, keyword?: string): {
108
+ stats(mode: any, project: any, keyword?: string, opts?: BuildOptions): {
64
109
  mode: any;
65
110
  project: any;
66
111
  keyword: string;