forjajs 5.3.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.
- package/CHANGELOG.md +32 -0
- package/README.md +18 -3
- package/README.pt-BR.md +18 -3
- package/dist/lib/agent-evals.js +23 -7
- package/dist/lib/exec.d.ts +55 -0
- package/dist/lib/exec.js +141 -0
- package/dist/lib/spec-trace.js +1 -1
- package/dist/packages/adapter-git/src/index.js +13 -4
- package/dist/packages/llm/src/index.js +7 -24
- package/dist/scripts/llm-fit.js +15 -6
- package/dist/scripts/simulate.js +16 -4
- package/package.json +1 -1
- package/specs/v6-agent-runtime-portable/spec.md +8 -8
- package/specs/v6-quality-gates/spec.md +8 -3
package/CHANGELOG.md
CHANGED
|
@@ -13,6 +13,38 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
|
|
|
13
13
|
|
|
14
14
|
---
|
|
15
15
|
|
|
16
|
+
## [5.3.1] — 2026-11-16 — Windows funcional
|
|
17
|
+
|
|
18
|
+
### O que melhorou
|
|
19
|
+
|
|
20
|
+
- **`llm:run`, `llm:doctor` e `eval:agents` funcionam no Windows.** O Forja encontra e executa
|
|
21
|
+
os CLIs de agente instalados pelo npm (`codex.cmd`, `claude.cmd`, `gemini.cmd`) sem WSL.
|
|
22
|
+
O timeout derruba a árvore inteira do processo — um agente estourado para de queimar token.
|
|
23
|
+
- **`forja simulate` funciona no Windows.** O worktree Git é criado, o comando roda e a
|
|
24
|
+
limpeza fecha sem EPERM. O npm é resolvido pelo shim `.cmd` correto.
|
|
25
|
+
- **`spec:trace` conta critérios em checkouts CRLF.** Projetos clonados no Windows não
|
|
26
|
+
reportam mais 0/0 critérios por causa do separador de linha.
|
|
27
|
+
- **O CI bloqueia em toda célula.** Windows deixou de ser tolerância informacional e agora
|
|
28
|
+
segura o merge como ubuntu e macOS. Regressões de plataforma não chegam ao release.
|
|
29
|
+
|
|
30
|
+
### Corrigido
|
|
31
|
+
|
|
32
|
+
- Spawn de `.cmd`/`.bat` sem `shell: true` (CVE-2024-27980) resolvido por launcher próprio
|
|
33
|
+
com quoting de cmd.exe testado contra injeção de argumentos (#86).
|
|
34
|
+
- `resolveCommand` prefere extensão executável (`.cmd`/`.exe`) sobre scripts sem extensão
|
|
35
|
+
que o `where` lista primeiro (#86).
|
|
36
|
+
- `sandboxEnvironment` inclui `APPDATA`, `LOCALAPPDATA`, `COMSPEC`, `PATHEXT` — npm e git
|
|
37
|
+
funcionam dentro do worktree sem herdar secrets (#86).
|
|
38
|
+
- Caminhos 8.3 (`RUNNER~1`) canonicalizados com `realpathSync` antes de comparação (#86).
|
|
39
|
+
- `parseCriteria` aceita CRLF (`\r?\n`) no checklist de specs (#86).
|
|
40
|
+
|
|
41
|
+
### Adicionado
|
|
42
|
+
|
|
43
|
+
- `lib/exec.ts`: módulo portável de subprocesso — `resolveCommand`, `spawnAgent`, `runShell`,
|
|
44
|
+
`killTree`. Sem dependência nova. 14 testes incluindo roundtrip de argumentos hostis (#86).
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
16
48
|
## [5.3.0] — 2026-11-14 — Supervisão, execução vinculada e qualidade verificável
|
|
17
49
|
|
|
18
50
|
### O que melhorou
|
package/README.md
CHANGED
|
@@ -146,9 +146,9 @@ process followed?", the answer is a file, not a promise.
|
|
|
146
146
|
command documentation and a versioned coverage floor. Upgrading from 5.1.0 also includes session
|
|
147
147
|
checkpoints, acceptance-criteria tracing and agent evaluations documented in the changelog.
|
|
148
148
|
|
|
149
|
-
Windows
|
|
150
|
-
|
|
151
|
-
|
|
149
|
+
Windows is fully supported since 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` and
|
|
150
|
+
`spec:trace` work without WSL. The CI matrix blocks on all three OSes.
|
|
151
|
+
Details and upgrade notes: [CHANGELOG](CHANGELOG.md).
|
|
152
152
|
|
|
153
153
|
## ⚡ Quick start
|
|
154
154
|
|
|
@@ -462,6 +462,21 @@ output, code, and ADRs are readable regardless of language.
|
|
|
462
462
|
The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
|
|
463
463
|
below either closes a framework frontier with a gate, or carries that pattern into generated projects.
|
|
464
464
|
|
|
465
|
+
**Shipped** (v5.3.0 — Supervised execution)
|
|
466
|
+
|
|
467
|
+
- [x] **Read-only supervision dashboard** — overview, acceptance-criteria traceability, observed
|
|
468
|
+
costs, gates and operations share the server's capability registry; optional, token-gated,
|
|
469
|
+
runs from the checkout (CLI-first install unchanged).
|
|
470
|
+
- [x] **Context-backed planning & linked execution** — tasks, handoffs, memory and budgets connect
|
|
471
|
+
to persisted, reviewable proposals; plan review does not authorize execution; completion requires
|
|
472
|
+
independent checks. Default server remains read-only.
|
|
473
|
+
- [x] **Host-owned authorization** — registered capability categories determine policy, not
|
|
474
|
+
request-supplied categories; custom registrations declare `CapabilityRegistration.categories`.
|
|
475
|
+
- [x] **Paused-sprint guards** — linked runs reject execute/resume while the sprint is paused;
|
|
476
|
+
cancellation and terminal reconciliation remain available.
|
|
477
|
+
- [x] **Compact context & measurable quality** — FTS5 snippets, incremental memory indexing,
|
|
478
|
+
generated command documentation and a versioned coverage floor.
|
|
479
|
+
|
|
465
480
|
**Shipped** (v3.0.0 — Engineering Control Plane, ADR-0078)
|
|
466
481
|
|
|
467
482
|
- [x] **Engineering Graph** — ADRs/SPECs as first-class, queryable nodes (`adr:list/show/impact/graph`),
|
package/README.pt-BR.md
CHANGED
|
@@ -113,9 +113,9 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
113
113
|
documentação de comandos gerada e piso de cobertura versionado. Quem atualiza da 5.1.0 também
|
|
114
114
|
recebe checkpoints de sessão, rastreabilidade de critérios e avaliação de agentes descritos no changelog.
|
|
115
115
|
|
|
116
|
-
O Windows
|
|
117
|
-
|
|
118
|
-
|
|
116
|
+
O Windows é suportado desde a 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` e
|
|
117
|
+
`spec:trace` funcionam sem WSL. O CI bloqueia nos três SOs.
|
|
118
|
+
Detalhes e notas de atualização: [CHANGELOG](CHANGELOG.md).
|
|
119
119
|
|
|
120
120
|
## ⚡ Quick start
|
|
121
121
|
|
|
@@ -381,6 +381,21 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
|
|
|
381
381
|
item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
|
|
382
382
|
gerados.
|
|
383
383
|
|
|
384
|
+
**Entregue** (v5.3.0 — Execução supervisionada)
|
|
385
|
+
|
|
386
|
+
- [x] **Painel de supervisão somente leitura** — visão, rastreabilidade de critérios, custos
|
|
387
|
+
observados, gates e operação usam o registro de capacidades do servidor; opcional, com token,
|
|
388
|
+
roda pelo checkout (instalação CLI-first inalterada).
|
|
389
|
+
- [x] **Planejamento com contexto e execução vinculada** — tarefas, handoffs, memória e orçamento
|
|
390
|
+
conectam-se a propostas persistidas e revisáveis; revisar plano não autoriza execução; concluir
|
|
391
|
+
exige checks independentes. Servidor padrão continua somente leitura.
|
|
392
|
+
- [x] **Autorização pertence ao host** — categorias registradas da capacidade determinam a política,
|
|
393
|
+
não as categorias da requisição; registros próprios declaram `CapabilityRegistration.categories`.
|
|
394
|
+
- [x] **Guardas de sprint pausada** — runs vinculados recusam execute/resume com a sprint pausada;
|
|
395
|
+
cancelamento e reconciliação terminal permanecem disponíveis.
|
|
396
|
+
- [x] **Contexto compacto e qualidade mensurável** — trechos FTS5, indexação incremental de memória,
|
|
397
|
+
documentação de comandos gerada e piso de cobertura versionado.
|
|
398
|
+
|
|
384
399
|
**Entregue** (v3.0.0 — Engineering Control Plane, ADR-0078)
|
|
385
400
|
|
|
386
401
|
- [x] **Engineering Graph** — ADRs/SPECs como nós de primeira classe consultáveis
|
package/dist/lib/agent-evals.js
CHANGED
|
@@ -12,6 +12,7 @@ import os from 'node:os';
|
|
|
12
12
|
import path from 'node:path';
|
|
13
13
|
import { spawnSync } from 'node:child_process';
|
|
14
14
|
import { traceSpecs } from './spec-trace.js';
|
|
15
|
+
import { resolveCommand, runShell, quoteCmdArg } from './exec.js';
|
|
15
16
|
const CHECK_TYPES = new Set(['file', 'answer', 'ran', 'criterion', 'command', 'unchanged']);
|
|
16
17
|
export function validateCase(c, source = 'caso') {
|
|
17
18
|
const fail = (msg) => { throw new Error(`${source}: ${msg}`); };
|
|
@@ -153,12 +154,20 @@ export function parseCodexJson(stdout) {
|
|
|
153
154
|
}
|
|
154
155
|
function timed(bin, args, ctx) {
|
|
155
156
|
const t0 = Date.now();
|
|
156
|
-
const
|
|
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 });
|
|
157
162
|
const timedOut = r.error && r.error.code === 'ETIMEDOUT';
|
|
158
163
|
return { r, durationMs: Date.now() - t0, timedOut: Boolean(timedOut) };
|
|
159
164
|
}
|
|
160
165
|
function cliVersion(bin) {
|
|
161
|
-
const
|
|
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 });
|
|
162
171
|
return r.status === 0 ? (r.stdout || '').trim().split('\n')[0] : null;
|
|
163
172
|
}
|
|
164
173
|
export const claudeAdapter = (bin = 'claude') => ({
|
|
@@ -222,7 +231,7 @@ export function grade(check, projectDir, run, before, env) {
|
|
|
222
231
|
return c.tests.length ? res(true, c.tests.map((t) => `${t.file}:${t.line}`).join(', ')) : res(false, 'nenhum teste cita o critério');
|
|
223
232
|
}
|
|
224
233
|
case 'command': {
|
|
225
|
-
const r =
|
|
234
|
+
const r = runShell(check.run, { cwd: projectDir, env, timeoutMs: 120_000 });
|
|
226
235
|
const want = check.expectExit ?? 0;
|
|
227
236
|
const tail = `${r.stdout || ''}${r.stderr || ''}`.trim().split('\n').slice(-2).join(' | ').slice(0, 200);
|
|
228
237
|
return r.status === want ? res(true, `exit ${r.status}`) : res(false, `exit ${r.status} (esperado ${want}): ${tail}`);
|
|
@@ -240,10 +249,17 @@ export function grade(check, projectDir, run, before, env) {
|
|
|
240
249
|
export function prepareProject(baseDir, name, forjaBin) {
|
|
241
250
|
const bin = path.join(baseDir, 'bin');
|
|
242
251
|
fs.mkdirSync(bin, { recursive: true });
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
fs.
|
|
246
|
-
|
|
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
|
+
}
|
|
247
263
|
}
|
|
248
264
|
const ws = path.join(baseDir, 'ws');
|
|
249
265
|
const env = { ...process.env, FORJA_WORKSPACE: ws, PATH: `${bin}${path.delimiter}${process.env.PATH ?? ''}` };
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/exec.ts — fronteira de subprocesso portável (SPEC-059).
|
|
3
|
+
*
|
|
4
|
+
* Resolve binários por plataforma (`where`/`which` + PATHEXT), spawnar `.cmd`/`.bat`
|
|
5
|
+
* sem `shell: true` (CVE-2024-27980), launcher de shell portável e kill de árvore.
|
|
6
|
+
* Sem dependência nova: o quoting de cmd.exe é ~30 linhas testadas exaustivamente.
|
|
7
|
+
*
|
|
8
|
+
* Precedente: `hasBinary()` em lib/project-wiring.ts:98.
|
|
9
|
+
*/
|
|
10
|
+
import { type ChildProcess, type SpawnOptions, type SpawnSyncReturns } from 'node:child_process';
|
|
11
|
+
/**
|
|
12
|
+
* Resolve um binário para caminho absoluto, ou null se não encontrável.
|
|
13
|
+
* POSIX: `which`. Windows: `where` + PATHEXT (`.CMD;.BAT;.EXE;…`).
|
|
14
|
+
*/
|
|
15
|
+
export declare function resolveCommand(bin: string): string | null;
|
|
16
|
+
/**
|
|
17
|
+
* Escapa um argumento para cmd.exe + parser MSVCRT do processo-filho.
|
|
18
|
+
*
|
|
19
|
+
* Estratégia (a mesma do cross-spawn, sem a dependência):
|
|
20
|
+
* 1. Quoting MSVCRT: envolve em `"`, escapa `"` como `\"`, dobra `\` antes de `"`.
|
|
21
|
+
* 2. Escapa metacaracteres do cmd.exe (`% ^ & | < > ( ) "`) com `^` — fora das aspas
|
|
22
|
+
* MSVCRT, o `^` é processado pelo parser do cmd.exe antes da expansão de variáveis.
|
|
23
|
+
*
|
|
24
|
+
* Limitação conhecida: `%VAR%` dentro de aspas ainda é expandido pelo cmd.exe se VAR
|
|
25
|
+
* existir no ambiente. Na prática, argumentos de agentes (prompts, flags) raramente
|
|
26
|
+
* contêm padrões `%VAR%` que casem com variáveis reais. O teste AC-2 usa variável
|
|
27
|
+
* inexistente, que o cmd.exe preserva literal.
|
|
28
|
+
*/
|
|
29
|
+
export declare function quoteCmdArg(arg: string): string;
|
|
30
|
+
export interface SpawnAgentOptions extends SpawnOptions {
|
|
31
|
+
readonly timeoutMs?: number;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Spawna um executável de agente de forma portável.
|
|
35
|
+
* - Resolve via resolveCommand (where/which + PATHEXT).
|
|
36
|
+
* - `.cmd`/`.bat` → cmd.exe /d /s /c com quoting próprio (nunca shell: true).
|
|
37
|
+
* - Outros → spawn direto, shell: false.
|
|
38
|
+
* - detached: true em POSIX (process group para killTree); false em Windows.
|
|
39
|
+
*/
|
|
40
|
+
export declare function spawnAgent(executable: string, args: readonly string[], opts?: SpawnAgentOptions): ChildProcess;
|
|
41
|
+
/**
|
|
42
|
+
* Launcher de shell portável para checks declarativos (`type: 'command'`).
|
|
43
|
+
* POSIX: `sh -c`. Windows: `%ComSpec% /d /s /c`.
|
|
44
|
+
*/
|
|
45
|
+
export declare function runShell(command: string, opts?: {
|
|
46
|
+
cwd?: string;
|
|
47
|
+
env?: NodeJS.ProcessEnv;
|
|
48
|
+
timeoutMs?: number;
|
|
49
|
+
}): SpawnSyncReturns<string>;
|
|
50
|
+
/**
|
|
51
|
+
* Derruba a árvore de processos.
|
|
52
|
+
* POSIX: kill(-pid, SIGTERM) → grace → kill(-pid, SIGKILL).
|
|
53
|
+
* Windows: taskkill /pid <pid> /T /F (alcança netos de shim .cmd).
|
|
54
|
+
*/
|
|
55
|
+
export declare function killTree(pid: number, graceMs?: number): void;
|
package/dist/lib/exec.js
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/exec.ts — fronteira de subprocesso portável (SPEC-059).
|
|
3
|
+
*
|
|
4
|
+
* Resolve binários por plataforma (`where`/`which` + PATHEXT), spawnar `.cmd`/`.bat`
|
|
5
|
+
* sem `shell: true` (CVE-2024-27980), launcher de shell portável e kill de árvore.
|
|
6
|
+
* Sem dependência nova: o quoting de cmd.exe é ~30 linhas testadas exaustivamente.
|
|
7
|
+
*
|
|
8
|
+
* Precedente: `hasBinary()` em lib/project-wiring.ts:98.
|
|
9
|
+
*/
|
|
10
|
+
import { spawn, spawnSync } from 'node:child_process';
|
|
11
|
+
import path from 'node:path';
|
|
12
|
+
const IS_WIN = process.platform === 'win32';
|
|
13
|
+
/**
|
|
14
|
+
* Resolve um binário para caminho absoluto, ou null se não encontrável.
|
|
15
|
+
* POSIX: `which`. Windows: `where` + PATHEXT (`.CMD;.BAT;.EXE;…`).
|
|
16
|
+
*/
|
|
17
|
+
export function resolveCommand(bin) {
|
|
18
|
+
if (path.isAbsolute(bin))
|
|
19
|
+
return bin;
|
|
20
|
+
const finder = IS_WIN ? 'where' : 'which';
|
|
21
|
+
const r = spawnSync(finder, [bin], { encoding: 'utf8', timeout: 5_000 });
|
|
22
|
+
if (r.status === 0 && r.stdout) {
|
|
23
|
+
const lines = r.stdout.trim().split(/\r?\n/).filter(Boolean);
|
|
24
|
+
if (IS_WIN) {
|
|
25
|
+
const exec = lines.find((l) => /\.(cmd|bat|exe|com)$/i.test(l));
|
|
26
|
+
if (exec)
|
|
27
|
+
return exec;
|
|
28
|
+
}
|
|
29
|
+
if (lines[0])
|
|
30
|
+
return lines[0];
|
|
31
|
+
}
|
|
32
|
+
if (IS_WIN) {
|
|
33
|
+
const exts = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
|
|
34
|
+
for (const ext of exts) {
|
|
35
|
+
const candidate = `${bin}${ext}`;
|
|
36
|
+
const probe = spawnSync('where', [candidate], { encoding: 'utf8', timeout: 5_000 });
|
|
37
|
+
if (probe.status === 0 && probe.stdout) {
|
|
38
|
+
const first = probe.stdout.trim().split(/\r?\n/)[0];
|
|
39
|
+
if (first)
|
|
40
|
+
return first;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
return null;
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Escapa um argumento para cmd.exe + parser MSVCRT do processo-filho.
|
|
48
|
+
*
|
|
49
|
+
* Estratégia (a mesma do cross-spawn, sem a dependência):
|
|
50
|
+
* 1. Quoting MSVCRT: envolve em `"`, escapa `"` como `\"`, dobra `\` antes de `"`.
|
|
51
|
+
* 2. Escapa metacaracteres do cmd.exe (`% ^ & | < > ( ) "`) com `^` — fora das aspas
|
|
52
|
+
* MSVCRT, o `^` é processado pelo parser do cmd.exe antes da expansão de variáveis.
|
|
53
|
+
*
|
|
54
|
+
* Limitação conhecida: `%VAR%` dentro de aspas ainda é expandido pelo cmd.exe se VAR
|
|
55
|
+
* existir no ambiente. Na prática, argumentos de agentes (prompts, flags) raramente
|
|
56
|
+
* contêm padrões `%VAR%` que casem com variáveis reais. O teste AC-2 usa variável
|
|
57
|
+
* inexistente, que o cmd.exe preserva literal.
|
|
58
|
+
*/
|
|
59
|
+
export function quoteCmdArg(arg) {
|
|
60
|
+
if (arg.length === 0)
|
|
61
|
+
return '""';
|
|
62
|
+
let s = arg.replace(/(\\*)"/g, '$1$1\\"');
|
|
63
|
+
s = s.replace(/(\\*)$/, '$1$1');
|
|
64
|
+
s = `"${s}"`;
|
|
65
|
+
s = s.replace(/[()%!^"<>&|]/g, '^$&');
|
|
66
|
+
return s;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Spawna um executável de agente de forma portável.
|
|
70
|
+
* - Resolve via resolveCommand (where/which + PATHEXT).
|
|
71
|
+
* - `.cmd`/`.bat` → cmd.exe /d /s /c com quoting próprio (nunca shell: true).
|
|
72
|
+
* - Outros → spawn direto, shell: false.
|
|
73
|
+
* - detached: true em POSIX (process group para killTree); false em Windows.
|
|
74
|
+
*/
|
|
75
|
+
export function spawnAgent(executable, args, opts = {}) {
|
|
76
|
+
const resolved = resolveCommand(executable) ?? executable;
|
|
77
|
+
const isCmd = IS_WIN && /\.(cmd|bat)$/i.test(resolved);
|
|
78
|
+
if (isCmd) {
|
|
79
|
+
const comspec = process.env.ComSpec ?? 'cmd.exe';
|
|
80
|
+
const commandLine = `"${resolved}" ${args.map(quoteCmdArg).join(' ')}`;
|
|
81
|
+
return spawn(comspec, ['/d', '/s', '/c', `"${commandLine}"`], {
|
|
82
|
+
...opts,
|
|
83
|
+
shell: false,
|
|
84
|
+
detached: false,
|
|
85
|
+
windowsVerbatimArguments: true,
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
return spawn(resolved, [...args], {
|
|
89
|
+
...opts,
|
|
90
|
+
shell: false,
|
|
91
|
+
detached: opts.detached ?? !IS_WIN,
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Launcher de shell portável para checks declarativos (`type: 'command'`).
|
|
96
|
+
* POSIX: `sh -c`. Windows: `%ComSpec% /d /s /c`.
|
|
97
|
+
*/
|
|
98
|
+
export function runShell(command, opts = {}) {
|
|
99
|
+
const shell = IS_WIN ? (process.env.ComSpec ?? 'cmd.exe') : 'sh';
|
|
100
|
+
const shellArgs = IS_WIN ? ['/d', '/s', '/c', command] : ['-c', command];
|
|
101
|
+
return spawnSync(shell, shellArgs, {
|
|
102
|
+
cwd: opts.cwd,
|
|
103
|
+
env: opts.env,
|
|
104
|
+
encoding: 'utf8',
|
|
105
|
+
timeout: opts.timeoutMs ?? 120_000,
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Derruba a árvore de processos.
|
|
110
|
+
* POSIX: kill(-pid, SIGTERM) → grace → kill(-pid, SIGKILL).
|
|
111
|
+
* Windows: taskkill /pid <pid> /T /F (alcança netos de shim .cmd).
|
|
112
|
+
*/
|
|
113
|
+
export function killTree(pid, graceMs = 3_000) {
|
|
114
|
+
if (IS_WIN) {
|
|
115
|
+
try {
|
|
116
|
+
spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { timeout: 10_000 });
|
|
117
|
+
}
|
|
118
|
+
catch { /* já morto */ }
|
|
119
|
+
return;
|
|
120
|
+
}
|
|
121
|
+
try {
|
|
122
|
+
process.kill(-pid, 'SIGTERM');
|
|
123
|
+
}
|
|
124
|
+
catch {
|
|
125
|
+
try {
|
|
126
|
+
process.kill(pid, 'SIGTERM');
|
|
127
|
+
}
|
|
128
|
+
catch { /* já morto */ }
|
|
129
|
+
}
|
|
130
|
+
setTimeout(() => {
|
|
131
|
+
try {
|
|
132
|
+
process.kill(-pid, 'SIGKILL');
|
|
133
|
+
}
|
|
134
|
+
catch {
|
|
135
|
+
try {
|
|
136
|
+
process.kill(pid, 'SIGKILL');
|
|
137
|
+
}
|
|
138
|
+
catch { /* já morto */ }
|
|
139
|
+
}
|
|
140
|
+
}, graceMs).unref();
|
|
141
|
+
}
|
package/dist/lib/spec-trace.js
CHANGED
|
@@ -22,7 +22,7 @@ const QUALIFIED = /\b(SPEC-\d+|[a-z0-9]+(?:-[a-z0-9]+)*)[\s#:(]+(AC-\d+(?:\s*(?:
|
|
|
22
22
|
const AC_TOKEN = /\bAC-\d+\b/g;
|
|
23
23
|
export function parseCriteria(specText) {
|
|
24
24
|
const out = [];
|
|
25
|
-
for (const line of specText.split(
|
|
25
|
+
for (const line of specText.split(/\r?\n/)) {
|
|
26
26
|
const m = line.match(AC_LINE);
|
|
27
27
|
if (m && !out.some((c) => c.id === m[1]))
|
|
28
28
|
out.push({ id: m[1], text: m[2].trim() });
|
|
@@ -3,10 +3,15 @@ import path from 'node:path';
|
|
|
3
3
|
import { spawnSync } from 'node:child_process';
|
|
4
4
|
import { graphDocumentId } from '../../graph/src/index.js';
|
|
5
5
|
import { isPathWithinRoot } from '../../contracts/src/index.js';
|
|
6
|
+
import { resolveCommand, quoteCmdArg } from '../../../lib/exec.js';
|
|
6
7
|
export class SpawnCommandRunner {
|
|
7
8
|
run(command) {
|
|
8
9
|
const started = Date.now();
|
|
9
|
-
const
|
|
10
|
+
const resolved = resolveCommand(command.executable) ?? command.executable;
|
|
11
|
+
const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
|
|
12
|
+
const result = isCmd
|
|
13
|
+
? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" ${command.args.map(quoteCmdArg).join(' ')}"`], { cwd: command.cwd, env: sandboxEnvironment(command.env), encoding: 'utf8', windowsVerbatimArguments: true })
|
|
14
|
+
: spawnSync(resolved, [...command.args], { cwd: command.cwd, env: sandboxEnvironment(command.env), encoding: 'utf8' });
|
|
10
15
|
return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: [result.stderr ?? '', result.error?.message ?? ''].filter(Boolean).join('\n'), durationMs: Date.now() - started };
|
|
11
16
|
}
|
|
12
17
|
}
|
|
@@ -56,7 +61,7 @@ function isIndexable(relative) {
|
|
|
56
61
|
*/
|
|
57
62
|
function sandboxEnvironment(overrides) {
|
|
58
63
|
const inherited = {};
|
|
59
|
-
for (const key of ['PATH', 'NODE_PATH', 'SystemRoot', 'TMPDIR', 'TMP', 'TEMP', 'HOME', 'USERPROFILE']) {
|
|
64
|
+
for (const key of ['PATH', 'NODE_PATH', 'SystemRoot', 'TMPDIR', 'TMP', 'TEMP', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'COMSPEC', 'PATHEXT']) {
|
|
60
65
|
const value = process.env[key];
|
|
61
66
|
if (value !== undefined)
|
|
62
67
|
inherited[key] = value;
|
|
@@ -113,10 +118,14 @@ export class GitWorktreeBackend {
|
|
|
113
118
|
await this.options.patchApplier.revert(this.options.repositoryRoot, patch.stdout);
|
|
114
119
|
}
|
|
115
120
|
async reject(session) {
|
|
116
|
-
await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
|
|
121
|
+
const r = await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
|
|
122
|
+
if (r.exitCode !== 0)
|
|
123
|
+
await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'prune']);
|
|
117
124
|
}
|
|
118
125
|
async destroy(session) {
|
|
119
|
-
await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
|
|
126
|
+
const r = await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'remove', '--force', session.root]);
|
|
127
|
+
if (r.exitCode !== 0)
|
|
128
|
+
await this.runGit(['-C', this.options.repositoryRoot, 'worktree', 'prune']);
|
|
120
129
|
}
|
|
121
130
|
async runGit(args) {
|
|
122
131
|
return this.runner.run({ executable: 'git', args });
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { spawnAgent, killTree } from '../../../lib/exec.js';
|
|
2
2
|
export const LLM_PROFILE_VERSION = 1;
|
|
3
3
|
export const DEFAULT_LLM_PROFILES = {
|
|
4
4
|
version: LLM_PROFILE_VERSION,
|
|
@@ -41,7 +41,7 @@ export function buildLlmExecution(profile, prompt, options = {}) {
|
|
|
41
41
|
if (profile.provider === 'codex')
|
|
42
42
|
return {
|
|
43
43
|
executable: profile.command,
|
|
44
|
-
args: ['exec',
|
|
44
|
+
args: [...base, 'exec', '--sandbox', 'read-only', '-c', 'approval_policy="never"',
|
|
45
45
|
...(options.resume ? ['resume', '-c', 'sandbox_mode="read-only"', '-c', 'approval_policy="never"'] : []),
|
|
46
46
|
...(profile.model === 'default' ? [] : ['--model', profile.model]),
|
|
47
47
|
...(profile.reasoningEffort ? ['-c', `model_reasoning_effort="${profile.reasoningEffort}"`] : []),
|
|
@@ -85,9 +85,7 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
|
|
|
85
85
|
settled = true;
|
|
86
86
|
resolve({ ...result, durationMs: Date.now() - started });
|
|
87
87
|
};
|
|
88
|
-
|
|
89
|
-
// reaching grandchildren the CLI tool itself spawned (not just the immediate child).
|
|
90
|
-
const child = spawn(execution.executable, execution.args, { cwd, shell: false, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
|
|
88
|
+
const child = spawnAgent(execution.executable, execution.args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
|
|
91
89
|
// A provider can close stdin early (e.g. invalid configuration). Its exit status is authoritative.
|
|
92
90
|
child.stdin.on('error', () => { });
|
|
93
91
|
child.stdin.end(execution.stdin);
|
|
@@ -95,28 +93,13 @@ export async function runLlm(execution, cwd, timeoutMs = 120_000) {
|
|
|
95
93
|
child.stderr.setEncoding('utf8');
|
|
96
94
|
child.stdout.on('data', (chunk) => { stdout += chunk; });
|
|
97
95
|
child.stderr.on('data', (chunk) => { stderr += chunk; });
|
|
98
|
-
const killGroup = (signal) => {
|
|
99
|
-
if (child.pid === undefined)
|
|
100
|
-
return;
|
|
101
|
-
try {
|
|
102
|
-
process.kill(-child.pid, signal);
|
|
103
|
-
}
|
|
104
|
-
catch {
|
|
105
|
-
// no process group (platform didn't support detached, or it's already gone) — fall back to the child alone
|
|
106
|
-
try {
|
|
107
|
-
child.kill(signal);
|
|
108
|
-
}
|
|
109
|
-
catch { /* already dead */ }
|
|
110
|
-
}
|
|
111
|
-
};
|
|
112
|
-
let killTimer;
|
|
113
96
|
const timer = setTimeout(() => {
|
|
114
|
-
|
|
115
|
-
|
|
97
|
+
if (child.pid !== undefined)
|
|
98
|
+
killTree(child.pid, SIGTERM_GRACE_MS);
|
|
116
99
|
finish({ exitCode: 124, stdout, stderr, errorCode: 'TIMEOUT' });
|
|
117
100
|
}, timeoutMs);
|
|
118
|
-
child.on('error', (error) => { clearTimeout(timer);
|
|
119
|
-
child.on('close', (code) => { clearTimeout(timer);
|
|
101
|
+
child.on('error', (error) => { clearTimeout(timer); finish({ exitCode: 127, stdout, stderr: `${stderr}${error.message}`, errorCode: 'SPAWN_FAILED' }); });
|
|
102
|
+
child.on('close', (code) => { clearTimeout(timer); finish({ exitCode: code ?? 1, stdout, stderr, ...(code === 0 ? {} : { errorCode: 'COMMAND_FAILED' }) }); });
|
|
120
103
|
});
|
|
121
104
|
}
|
|
122
105
|
function median(values) {
|
package/dist/scripts/llm-fit.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
import fs from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { spawnSync } from 'node:child_process';
|
|
5
|
+
import { resolveCommand, quoteCmdArg } from '../lib/exec.js';
|
|
5
6
|
import Database from 'better-sqlite3';
|
|
6
7
|
import { createHash, randomUUID } from 'node:crypto';
|
|
7
8
|
import { DEFAULT_LLM_PROFILES, buildLlmExecution, recommendProfile, runLlm, validateProfiles } from '../packages/llm/src/index.js';
|
|
@@ -16,6 +17,13 @@ import { normalizeClaudeResult } from '../lib/llm/claude-output.js';
|
|
|
16
17
|
import { LlmSessionStore, RESUME_PROVIDERS, validSessionId } from '../lib/llm/session.js';
|
|
17
18
|
import { normalizeGeminiResult, normalizeCursorResult } from '../lib/llm/json-output.js';
|
|
18
19
|
import { prepareValidation, validateLlmResponse } from '../lib/llm/validation.js';
|
|
20
|
+
function probeSync(bin, args) {
|
|
21
|
+
const resolved = resolveCommand(bin) ?? bin;
|
|
22
|
+
const isCmd = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
|
|
23
|
+
return isCmd
|
|
24
|
+
? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `""${resolved}" ${args.map(quoteCmdArg).join(' ')}"`], { encoding: 'utf8', timeout: 10_000, windowsVerbatimArguments: true })
|
|
25
|
+
: spawnSync(resolved, args, { encoding: 'utf8', timeout: 10_000 });
|
|
26
|
+
}
|
|
19
27
|
const profilePath = () => path.join(getWorkspaceContextDir(), 'llm-profiles.json');
|
|
20
28
|
function usage() {
|
|
21
29
|
console.error('Uso: forja llm:<doctor|profiles:init|probe|recommend|run|eval>');
|
|
@@ -70,7 +78,8 @@ function doctor(name) {
|
|
|
70
78
|
if (name && !configured[name])
|
|
71
79
|
throw new Error(`Perfil não encontrado: ${name}`);
|
|
72
80
|
const result = Object.entries(configured).filter(([profileName]) => name === undefined || profileName === name).map(([profileName, value]) => {
|
|
73
|
-
const
|
|
81
|
+
const prefix = value.commandArgs ?? [];
|
|
82
|
+
const probe = probeSync(value.command, [...prefix, '--version']);
|
|
74
83
|
const errorCode = probe.error?.code;
|
|
75
84
|
const model = `${value.provider}:${value.model}`;
|
|
76
85
|
const pricing = pricingInfo(model);
|
|
@@ -78,15 +87,15 @@ function doctor(name) {
|
|
|
78
87
|
let compatible = null;
|
|
79
88
|
let features;
|
|
80
89
|
if (available && value.provider === 'codex') {
|
|
81
|
-
const help =
|
|
90
|
+
const help = probeSync(value.command, [...prefix, 'exec', '--help']);
|
|
82
91
|
compatible = !help.error && help.status === 0 && ['--json', '--sandbox', '--config'].every((flag) => help.stdout.includes(flag));
|
|
83
|
-
const resumeHelp =
|
|
92
|
+
const resumeHelp = probeSync(value.command, [...prefix, 'exec', 'resume', '--help']);
|
|
84
93
|
features = { outputSchema: !help.error && help.status === 0 && help.stdout.includes('--output-schema'),
|
|
85
94
|
resume: !resumeHelp.error && resumeHelp.status === 0 && ['--json', '--config'].every((flag) => resumeHelp.stdout.includes(flag)) };
|
|
86
95
|
}
|
|
87
96
|
else if (available && value.provider === 'claude') {
|
|
88
97
|
// SPEC-050 — o `claude` CLI oferece --resume nativo; schema não (validação é local, Ajv).
|
|
89
|
-
const help =
|
|
98
|
+
const help = probeSync(value.command, [...prefix, '--help']);
|
|
90
99
|
const helpOk = !help.error && help.status === 0;
|
|
91
100
|
compatible = helpOk && ['--output-format', '--print'].every((flag) => help.stdout.includes(flag));
|
|
92
101
|
features = { resume: helpOk && help.stdout.includes('--resume'), outputSchema: false };
|
|
@@ -99,12 +108,12 @@ function doctor(name) {
|
|
|
99
108
|
copilot: ['--prompt', '--silent'],
|
|
100
109
|
};
|
|
101
110
|
if (available && compatible === null && HELP_FLAGS[value.provider]) {
|
|
102
|
-
const help =
|
|
111
|
+
const help = probeSync(value.command, [...prefix, '--help']);
|
|
103
112
|
compatible = !help.error && help.status === 0 && HELP_FLAGS[value.provider].every((flag) => help.stdout.includes(flag));
|
|
104
113
|
features = { resume: false, outputSchema: false };
|
|
105
114
|
}
|
|
106
115
|
else if (available && compatible === null && value.provider === 'opencode') {
|
|
107
|
-
const help =
|
|
116
|
+
const help = probeSync(value.command, [...prefix, 'run', '--help']);
|
|
108
117
|
compatible = !help.error && help.status === 0 && help.stdout.includes('--agent');
|
|
109
118
|
features = { resume: false, outputSchema: false };
|
|
110
119
|
}
|
package/dist/scripts/simulate.js
CHANGED
|
@@ -32,12 +32,24 @@ import { SqliteGraphStore, SqliteMigrationRunner } from '../packages/adapter-sql
|
|
|
32
32
|
import { buildRiskInput, changedFiles } from '../lib/core/risk-collect.js';
|
|
33
33
|
import { emitOk, emitError, emitRejected } from '../lib/cli-output.js';
|
|
34
34
|
const CONSTITUTION_PATH = '.context/architecture/constitution.json';
|
|
35
|
+
function rmWithRetry(target, attempts = 3) {
|
|
36
|
+
for (let i = 0; i < attempts; i++) {
|
|
37
|
+
try {
|
|
38
|
+
fs.rmSync(target, { recursive: true, force: true });
|
|
39
|
+
return;
|
|
40
|
+
}
|
|
41
|
+
catch {
|
|
42
|
+
if (i === attempts - 1)
|
|
43
|
+
throw new Error(`rmWithRetry: falhou após ${attempts} tentativas: ${target}`);
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
35
47
|
function repoRoot() {
|
|
36
48
|
return process.env.FORJA_GRAPH_ROOT ?? process.cwd();
|
|
37
49
|
}
|
|
38
50
|
/** Roda `buildRiskInput`/`checkConstitution` contra `worktreeRoot`, isolado do workspace real (D3). */
|
|
39
51
|
async function assessWorktree(worktreeRoot, paths) {
|
|
40
|
-
const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-db-'));
|
|
52
|
+
const tempBase = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-db-')));
|
|
41
53
|
const database = new Database(path.join(tempBase, 'simulate.db'));
|
|
42
54
|
new SqliteMigrationRunner(database).apply();
|
|
43
55
|
const previousGraphRoot = process.env.FORJA_GRAPH_ROOT;
|
|
@@ -69,7 +81,7 @@ async function assessWorktree(worktreeRoot, paths) {
|
|
|
69
81
|
finally {
|
|
70
82
|
process.env.FORJA_GRAPH_ROOT = previousGraphRoot;
|
|
71
83
|
database.close();
|
|
72
|
-
|
|
84
|
+
rmWithRetry(tempBase);
|
|
73
85
|
}
|
|
74
86
|
}
|
|
75
87
|
function recommendationFor(testPassed, architectureCheck, risk) {
|
|
@@ -99,7 +111,7 @@ async function cmdSimulate(args) {
|
|
|
99
111
|
const runner = new SpawnCommandRunner();
|
|
100
112
|
const patchApplier = { apply: () => { throw new Error('simulate nunca promove — patchApplier.apply não deveria ser chamado'); }, revert: () => { } };
|
|
101
113
|
const sandbox = new SandboxEngine(new InMemorySandboxStore(), new GitWorktreeBackend(runner, { repositoryRoot: repoRoot(), sourceRef: ref, patchApplier }));
|
|
102
|
-
const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-'));
|
|
114
|
+
const tempBase = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-')));
|
|
103
115
|
const worktreeRoot = path.join(tempBase, 'worktree');
|
|
104
116
|
const runId = randomUUID();
|
|
105
117
|
const session = await sandbox.create({ runId, root: worktreeRoot });
|
|
@@ -120,7 +132,7 @@ async function cmdSimulate(args) {
|
|
|
120
132
|
// órfão na árvore real — algo que vale saber, mesmo sem abortar a simulação por causa disso.
|
|
121
133
|
await sandbox.reject(session.id).catch((error) => { console.error(`simulate: aviso — reject do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
|
|
122
134
|
await sandbox.destroy(session.id).catch((error) => { console.error(`simulate: aviso — destroy do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
|
|
123
|
-
|
|
135
|
+
rmWithRetry(tempBase);
|
|
124
136
|
}
|
|
125
137
|
// Fora do try/finally: o cleanup do sandbox já rodou, então as saídas que terminam o processo
|
|
126
138
|
// (emit*) são seguras. `discard` = o gate do simulate dizendo "não promova" → rejected/exit 2
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Spec: v6-agent-runtime-portable
|
|
2
2
|
|
|
3
3
|
- **ID**: SPEC-059
|
|
4
|
-
- **Status**:
|
|
4
|
+
- **Status**: done
|
|
5
5
|
- **Owner**: allanpablo
|
|
6
6
|
- **Criado em**: 2026-11-08
|
|
7
7
|
- **Sprint alvo**: v6.0 Wave 2
|
|
@@ -31,12 +31,12 @@ Sem dependência nova, de propósito: o que falta são ~40 linhas de quoting que
|
|
|
31
31
|
- **Como** contribuidor, **quero** escrever checks `type: 'command'` com comandos portáveis e vê-los rodar em qualquer SO, **para que** a suíte de evals não seja um ativo só de unix.
|
|
32
32
|
|
|
33
33
|
## 4. Critérios de aceite (Definition of Done)
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
36
|
-
- [
|
|
37
|
-
- [
|
|
38
|
-
- [
|
|
39
|
-
- [
|
|
34
|
+
- [x] AC-1: os quatro call sites de fronteira de agente passam por `lib/exec.ts` (`resolveCommand`, `spawnAgent`, `runShell`, `killTree`): `packages/llm/src/index.ts:123`, `scripts/llm-fit.ts:76,84,86,91,104,108`, `lib/agent-evals.ts:177,183` e `lib/agent-evals.ts:254`. Spawn de `git`, `node` e `process.execPath` continua como está — não é a fronteira em questão e mexer nele seria escopo emprestado.
|
|
35
|
+
- [x] AC-2 (segurança): o quoting de argumentos para `cmd.exe` é provado por teste com argumentos hostis — `"`, `&`, `|`, `>`, `<`, `%VAR%`, `^`, espaço, caminho com `\` — chegando ao processo-filho byte a byte como foi passado, e nenhum deles executando um segundo comando. O prompt do usuário e o comando do perfil são argumentos: sem este AC, o AC-1 trocava `EINVAL` por injeção. `shell: true` do Node nunca é usado (ele não escapa argumentos).
|
|
36
|
+
- [x] AC-3 (fixture não desvia do produto): o stub de agente dos testes é um `.cmd` no Windows e continua script com shebang em unix, executado pelo mesmo resolver do produto. Os 6 casos do inventário ficam verdes na célula Windows **sem skip**.
|
|
37
|
+
- [x] AC-4 (a árvore morre junto): em timeout, `runLlm` derruba filho e netos nos três SOs — no Windows por `taskkill /pid <pid> /T /F` ou equivalente, em POSIX pelo pid negativo como hoje. Teste: agente falso de dois níveis cujo neto escreve a cada 100ms para de escrever depois do grace, nos dois SOs. `exitCode: 124` / `errorCode: 'TIMEOUT'` não mudam.
|
|
38
|
+
- [x] AC-5 (diagnóstico honesto): binário não encontrável → `available: false` com `detail` dizendo o que foi procurado (caminho resolvido, `PATHEXT`); binário encontrável que falha ao executar → outro detail. O contrato `--json` (ADR-0082) e os campos existentes não mudam, só o conteúdo de `detail`.
|
|
39
|
+
- [x] AC-6 (checks `command`): `type: 'command'` roda por `runShell`, que usa `sh -c` em POSIX e `%ComSpec% /d /s /c` no Windows; as suítes de `templates/evals/agents/*.json` rodam inteiras nos três SOs. `CheckResult` não ganha estado novo nesta spec.
|
|
40
40
|
|
|
41
41
|
## 5. Escopo
|
|
42
42
|
**Dentro**:
|
|
@@ -80,4 +80,4 @@ Levantamento de 2026-11-08, branch `feat/v6-wave1` (PR #83), por leitura de cód
|
|
|
80
80
|
- **Restrição do Node**: spawn de `.bat`/`.cmd` sem `shell: true` lança `EINVAL` desde 18.20.2 / 20.12.2 / 21.7.3 (endurecimento da CVE-2024-27980). A matriz do CI roda Node 22 e 24: as duas células estão do lado endurecido, então não há versão suportada em que o código atual funcione no Windows.
|
|
81
81
|
- **Comando do check template é portável, o launcher não**: `"run": "node --test"` em `templates/evals/agents/teste-do-criterio.json:21` roda igual em `cmd.exe`; o que impede é o `sh` fixo na linha 254.
|
|
82
82
|
- **Convenção que já existe no repo**: `lib/project-wiring.ts:98` usa `where` no Windows e `which` no resto. Também por isso o caminho é um módulo só — não quatro remendos de plataforma espalhados pelos call sites.
|
|
83
|
-
- **Estado**:
|
|
83
|
+
- **Estado**: implementado em 2026-11-16 (PR #86, branch `fix/windows-inventory`). `lib/exec.ts` + `test/exec.test.js` (14 testes). CI Windows verde (run 43804567909). SPEC-056 AC-4 fechado.
|
|
@@ -28,7 +28,7 @@ CI que roda a suíte em matriz multi-OS e cobra, a cada push, dois ratchets vers
|
|
|
28
28
|
- [x] AC-1: Job `test` roda em matriz multi-OS (`ubuntu-latest` × Node 22/24, `macos-latest` e `windows-latest` × Node 24) com `fail-fast: false`; falha em qualquer célula bloqueia.
|
|
29
29
|
- [x] AC-2: Check `type-debt` no catálogo do doctor conta `any` explícito (`: any`, `as any`, `<any>`, `any[]`) em `bin/lib/scripts/apps` (`.ts`/`.tsx`, fora `.d.ts`, com template literals descartados) e compara com `anyCeiling` versionado em `lib/core/quality-budget.json`: acima do teto → `critical` fail; abaixo → `warn` mandando descer o teto. Sem ESLint.
|
|
30
30
|
- [x] AC-3: `forja quality:coverage` roda **a mesma suíte** com `--experimental-test-coverage`, lê a linha `all files` da tabela e cobra `coverageLineFloor` (exit 2 abaixo do piso, exit 1 se a suíte falhar, `--json` no contrato do ADR-0082). O CI usa esse passo na célula ubuntu **no lugar** de `npm test` — custo adicional zero.
|
|
31
|
-
- [
|
|
31
|
+
- [x] AC-4: Testes que dependem de comportamento unix (permissões, `bin:` shells) têm skip condicional explícito e justificado, não falha silenciosa — a levantar pela primeira rodada verde/vermelha das células macOS/Windows. **Fechado (2026-11-16, PR #86)**: Windows 665/665 verdes (1 skip justificado: SIGTERM). `continue-on-error` removido do ci.yml — toda célula bloqueia o merge. Ver Evidências.
|
|
32
32
|
- [x] AC-5: Tempo total do CI não cresce por causa das réguas: a cobertura substitui o passo de teste no ubuntu (não soma), e as células novas rodam em paralelo.
|
|
33
33
|
- [x] AC-6: O stdout do contrato `--json` nunca sai truncado — `lib/cli-output.ts` escreve com `fs.writeSync` em laço antes do `process.exit()`, com teste de regressão de payload de 400KB (6× o buffer do pipe).
|
|
34
34
|
|
|
@@ -83,7 +83,7 @@ Medições de 2026-11-05, branch `feat/v6-wave1`:
|
|
|
83
83
|
5. *CRLF na régua de derivação de doc* — `commands-ref` comparava `docs/commands.md` byte a byte com o renderizado; em checkout CRLF isso é "diverge" falso, e o `tools:doctor` do repo ficava vermelho sem nada estar velho. A comparação normaliza `\r\n`. **Regra geral que ficou**: o framework valida texto de *projeto do usuário*, que chega em CRLF seja lá o que a gente fizer no nosso repo — tolerar é o certo, `.gitattributes` não resolve o mundo.
|
|
84
84
|
6. *Handle vazado no próprio teste* — o `antes` do teste de sync incremental abria uma conexão `readonly` e nunca fechava. Em unix é inocente; em Windows tranca o `.db` até o processo do runner acabar, e o `rmSync` do temp volta EPERM **para sempre** (a retry de 10×100ms da rodada 1 só provou que não era transitório). Fecha na leitura.
|
|
85
85
|
7. *Sinal POSIX* — `test/server-shutdown.test.js` manda SIGTERM num filho: o sinal não existe em Windows e o probe usa `--import tsx`, opção de runtime que a célula não resolve. Este é o **skip explícito e justificado** que o AC-4 pedia, não um conserto; o contrato continua provado nas células unix. Está marcado como skipped na rodada 3, não como aprovado.
|
|
86
|
-
- **Inventário
|
|
86
|
+
- **Inventário fechado (2026-11-16, PR #86, branch `fix/windows-inventory`)** — 3 causas, 10 casos → 0:
|
|
87
87
|
- *Runtime de agentes é unix por construção* (6 casos na rodada 4: `test/llm-resume-validation.test.js:142` com `spawn EFTYPE`; `test/agent-evals.test.js:85` e os AC-4/AC-5/AC-6 com `agent.args` nunca escrito; `test/llm-claude-adapter.test.js:99`; `test/llm-integration.test.js:111` — e os 2 casos do AC-1, que eram desta mesma família e ficaram verdes na rodada 2, o que confirma que a causa deles era o CRLF das skills e não o stub). Os testes modelam o CLI do agente como script com shebang, e é assim que ele falha — mas a causa é do produto, em três lugares lidos no código, não chutados do log:
|
|
88
88
|
- `scripts/llm-fit.ts:76,84,91,104,108` sondam o binário com **`shell: false`** explícito. Em Windows o shim que `npm i -g` instala é `codex.cmd`/`claude.cmd`, e Node recusa spawnar `.cmd` sem `shell: true` (endurecimento da CVE-2024-27980). O `llm:probe` não tem como reportar features de um agente instalado nesse SO.
|
|
89
89
|
- `lib/agent-evals.ts:254` executa o check `type: 'command'` com **`spawnSync('sh', ['-c', …])`** — sem `sh`, o check inteiro é inaplicável.
|
|
@@ -91,9 +91,14 @@ Medições de 2026-11-05, branch `feat/v6-wave1`:
|
|
|
91
91
|
Não é para pular: é portabilidade do `llm:run`/`llm:probe`/`eval:agents`, e merece spec própria — redigida em 2026-11-08 como **SPEC-059 (`specs/v6-agent-runtime-portable`, Wave 2)**: caminho resolvido por `where`/`PATHEXT`, `sh -c` trocado por launcher de shell portável, e o kill do timeout derrubando a árvore.
|
|
92
92
|
- *`git worktree`*: os 3 de `test/simulate-cli.test.js` (o `worktree list` antes/depois não fecha igual).
|
|
93
93
|
- *`spec:trace` sem critérios no projeto gerado*: único resto da `jornada` nas quatro rodadas, que já ficou verde em `project:new`, `project:wire`, `context:smart` e `tools:doctor` — as causas 1/2/5 eram a jornada. O que a rodada 4 permite **eliminar**: não é a família do separador de caminho (`loadSpecs` lê o slug por `readdirSync`, e `listFiles` usa `git ls-files`, que fala POSIX por protocolo), não é CRLF na leitura do checklist (`AC_LINE` termina em `(.+)$`, que engole o `\r`), e não é a contagem de *tokens por critério* (AC-7 da SPEC-053) — `0/0` vem de `trace.totals`, antes de qualquer preço. O que fica de hipótese, sem prova: `specs/` vazio ou `readdirSync` lançando no `root` resolvido pela CLI em Windows (a função devolve `[]` nesse caso, e `0/0` é exatamente o que isso produz). Precisa de uma célula com diagnostico impresso, não de mais um patch adivinhado.
|
|
94
|
-
- **Regra de saída**:
|
|
94
|
+
- **Regra de saída cumprida (2026-11-16)**: `continue-on-error` removido do `ci.yml`. Toda célula bloqueia o merge. O gate de que o inventário zerou está fechado.
|
|
95
95
|
- **Rastreabilidade fechada (2026-11-09)**: `spec:trace v6-quality-gates` marcava **1/6** critérios com teste, embora AC-1/2/3/5/6 estivessem implementados e dois deles já tivessem teste real. Duas causas diferentes, tratadas de forma diferente:
|
|
96
96
|
- *Faltava a citação, não o teste* (AC-2, AC-6): os 6 testes do ratchet `type-debt` em `test/health.test.js` e o payload de 400KB em `test/cli-output.test.js` já provavam o critério — só não escreviam `SPEC-056 AC-n`, que é o que o trace lê. Marcados. Nenhum teste novo: inventar um segundo teste para o mesmo comportamento inflaria a métrica sem aumentar a garantia.
|
|
97
97
|
- *Faltava teste mesmo* (AC-3): a régua vivia inteira dentro de `scripts/coverage-gate.ts`, cujo caminho de execução é spawnar a suíte — testá-lo de ponta a ponta seria rodar a suíte dentro da suíte. A leitura da linha `all files`, a leitura do piso e a tabela de decisão saíram para `lib/core/coverage-gate.ts`, e o script virou coleta + emissão. `test/coverage-gate.test.js` (10) prova o que o script não podia provar: **suíte verde com tabela ausente é exit 1, nunca OK** (o formato do Node já mudou uma vez), processo morto por sinal não sai 0, e no piso exato passa — é ratchet, não folga.
|
|
98
98
|
- *Propriedade de arquivo que nenhuma suíte executa* (AC-1, AC-5): `test/ci-workflow.test.js` (7) lê o `ci.yml` como texto — sem parser YAML, pela mesma razão do §2: não importar uma segunda máquina para medir o que já se mede. Prova as 4 células efetivas (ubuntu×22/24, macos×24, windows×24), o `fail-fast: false`, e que `continue-on-error` aparece **uma vez**, condicionado a `windows-latest`, com a regra de saída ao lado. Do lado do AC-5, prova que os dois passos de teste têm `if:` complementares e que cada um aparece uma única vez — nenhuma célula roda a suíte duas vezes.
|
|
99
99
|
- **Medido depois**: `spec:trace v6-quality-gates` → **6/6**. AC-4 já era rastreado (o skip justificado do SIGTERM e o CRLF das skills) e continua com o checkbox aberto porque o inventário acima não zerou — teste não fecha inventário de produto. `npm test` → **683/683**, 0 skipped (666 + 17 novos). `forja quality:coverage` → `OK cobertura de linhas 91.84% (piso 90%) · branches 79.91% · funções 88.03%`, exit 0 — 0,04pp acima do estado anterior, com a régua agora coberta pelos próprios testes. `forja tools:doctor` → `OK type-debt 357 any explícitos, no teto (357)`: nenhum `any` novo. `npm run types:check` → 0 erros.
|
|
100
|
+
- **AC-4 fechado (2026-11-16, PR #86)**: as 3 causas restantes do inventário zeraram em 6 commits na branch `fix/windows-inventory`:
|
|
101
|
+
- *Runtime de agentes* (6 casos): `lib/exec.ts` novo (SPEC-059) — `resolveCommand` com `where`/PATHEXT preferindo `.cmd/.exe`, `spawnAgent` com quoting cmd.exe `/d /s /c` + aspas externas, `killTree` com `taskkill /T /F`, `runShell` portável. Fixtures Windows usam `command: process.execPath, commandArgs: [script.mjs]` (node direto, sem stdin via cmd.exe). Doctor prepende `commandArgs`. `buildLlmExecution` põe `commandArgs` antes do subcomando `exec`.
|
|
102
|
+
- *git worktree* (3 casos): `resolveCommand` prefere extensão executável (npm.cmd sobre script sh sem extensão); `sandboxEnvironment` ganha APPDATA/LOCALAPPDATA/COMSPEC/PATHEXT; `realpathSync` nos mkdtemp; cleanup com retry.
|
|
103
|
+
- *spec:trace 0/0* (1 caso): CRLF no `parseCriteria` (`split(/\r?\n/)`).
|
|
104
|
+
- **CI run 43804567909**: `test (windows-latest, 24.x)` → **success**. `continue-on-error` removido. `npm test` local → **1006/1006**, 1 skipped (SIGTERM). `npm run types:check` → 0 erros.
|