forjajs 4.0.1 → 4.1.0
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 +111 -7
- package/DOC-MAP.md +1 -0
- package/README.md +7 -2
- package/dist/apps/cli/src/index.d.ts +18 -1
- package/dist/apps/cli/src/index.js +161 -26
- package/dist/apps/cli/src/params.d.ts +44 -0
- package/dist/apps/cli/src/params.js +123 -0
- package/dist/bin/forja.js +234 -13
- package/dist/bin/init-project.js +11 -62
- package/dist/lib/cli-output.d.ts +29 -0
- package/dist/lib/cli-output.js +39 -0
- package/dist/lib/core/checks.d.ts +1 -1
- package/dist/lib/core/health.d.ts +9 -0
- package/dist/lib/core/health.js +9 -0
- package/dist/lib/core/project-smoke.d.ts +6 -2
- package/dist/lib/core/project-smoke.js +83 -7
- package/dist/lib/core/registry.d.ts +38 -571
- package/dist/lib/core/registry.js +174 -25
- package/dist/lib/core/release.d.ts +1 -571
- package/dist/lib/core/release.js +0 -3
- package/dist/lib/handoffs-index.d.ts +16 -0
- package/dist/lib/handoffs-index.js +29 -0
- package/dist/lib/llm/claude-output.d.ts +8 -0
- package/dist/lib/llm/claude-output.js +54 -0
- package/dist/lib/llm/context.d.ts +22 -0
- package/dist/lib/llm/context.js +39 -0
- package/dist/lib/llm/session.d.ts +6 -1
- package/dist/lib/llm/session.js +12 -2
- package/dist/lib/multi-ai-instructions.d.ts +28 -0
- package/dist/lib/multi-ai-instructions.js +83 -0
- package/dist/lib/orchestrate.d.ts +5 -0
- package/dist/lib/orchestrate.js +18 -0
- package/dist/lib/specs-index.d.ts +20 -0
- package/dist/lib/specs-index.js +51 -0
- package/dist/lib/sprint-index.d.ts +15 -0
- package/dist/lib/sprint-index.js +34 -0
- package/dist/lib/status-model.d.ts +64 -0
- package/dist/lib/status-model.js +180 -0
- package/dist/packages/evals/src/index.d.ts +2 -0
- package/dist/packages/evals/src/index.js +21 -0
- package/dist/packages/llm/src/index.d.ts +24 -3
- package/dist/packages/llm/src/index.js +51 -5
- package/dist/scripts/cost-economy.js +12 -10
- package/dist/scripts/drift-check.d.ts +2 -0
- package/dist/scripts/drift-check.js +57 -1
- package/dist/scripts/engineer.js +7 -4
- package/dist/scripts/forja-setup.d.ts +14 -0
- package/dist/scripts/forja-setup.js +58 -0
- package/dist/scripts/forja-status.d.ts +11 -0
- package/dist/scripts/forja-status.js +70 -0
- package/dist/scripts/hook-session-start.js +20 -46
- package/dist/scripts/llm-fit.js +113 -8
- package/dist/scripts/project-smoke.js +13 -3
- package/dist/scripts/simulate.js +18 -6
- package/dist/scripts/token-economy.js +34 -28
- package/dist/scripts/tools-doctor.js +14 -6
- package/docs/2x/CLI-CAPABILITIES.md +34 -10
- package/docs/agent-operating-contract.md +1 -1
- package/docs/cli-first-operacao.md +17 -0
- package/docs/contrato-saida-cli.md +79 -0
- package/docs/llm-evolution.md +2 -1
- package/docs/llm-fit-loop.md +74 -2
- package/docs/publishing.md +0 -11
- package/docs/quick-reference.md +13 -0
- package/docs/roadmap-v4.1.md +199 -0
- package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
- package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
- package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
- package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
- package/package.json +4 -1
- package/specs/cli-intuitiva-v1/plan.md +169 -0
- package/specs/cli-intuitiva-v1/spec.md +163 -0
- package/specs/cli-intuitiva-v1/tasks.md +224 -0
- package/specs/contrato-saida-cli/plan.md +162 -0
- package/specs/contrato-saida-cli/spec.md +157 -0
- package/specs/contrato-saida-cli/tasks.md +153 -0
- package/specs/drift-sentinel/spec.md +17 -8
- package/specs/forja-status-caminho-feliz/plan.md +149 -0
- package/specs/forja-status-caminho-feliz/spec.md +158 -0
- package/specs/forja-status-caminho-feliz/tasks.md +175 -0
- package/specs/llm-adaptador-claude/plan.md +117 -0
- package/specs/llm-adaptador-claude/spec.md +144 -0
- package/specs/llm-adaptador-claude/tasks.md +100 -0
- package/specs/llm-benchmark-recomendacao/plan.md +121 -0
- package/specs/llm-benchmark-recomendacao/spec.md +141 -0
- package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
- package/specs/llm-contexto-e-sessoes/plan.md +143 -0
- package/specs/llm-contexto-e-sessoes/spec.md +139 -0
- package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
- package/specs/mcp-cobertura-nucleo/plan.md +158 -0
- package/specs/mcp-cobertura-nucleo/spec.md +161 -0
- package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
- package/specs/projeto-gerado-confiavel/plan.md +148 -0
- package/specs/projeto-gerado-confiavel/spec.md +142 -0
- package/specs/projeto-gerado-confiavel/tasks.md +139 -0
package/dist/bin/forja.js
CHANGED
|
@@ -26,11 +26,18 @@ import { McpServer } from "../packages/mcp/src/index.js";
|
|
|
26
26
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
27
27
|
const root = path.resolve(__dirname, '..');
|
|
28
28
|
const STUDIO_COMMANDS = new Set(['workspace:init', 'project:new', 'project:list', 'project:upgrade', 'workspace:project:check', 'init:project', 'demo:workspace']);
|
|
29
|
-
|
|
29
|
+
// SPEC-043: `forja help` mostra só o núcleo (`tier: 'core'`); `forja help --all` mantém a lista
|
|
30
|
+
// completa de antes. O detalhe por comando vive em `printCommandHelp`.
|
|
31
|
+
function printHelp(all = false) {
|
|
30
32
|
console.log('Forja — core executivo (ADR-0020)');
|
|
31
33
|
console.log('Uso: forja <comando> [args]\n');
|
|
32
34
|
const byDomain = new Map();
|
|
35
|
+
let hidden = 0;
|
|
33
36
|
for (const [name, cmd] of Object.entries(COMMANDS)) {
|
|
37
|
+
if (!all && cmd.tier !== 'core') {
|
|
38
|
+
hidden++;
|
|
39
|
+
continue;
|
|
40
|
+
}
|
|
34
41
|
if (!byDomain.has(cmd.domain))
|
|
35
42
|
byDomain.set(cmd.domain, []);
|
|
36
43
|
byDomain.get(cmd.domain).push([name, cmd.desc]);
|
|
@@ -45,18 +52,128 @@ function printHelp() {
|
|
|
45
52
|
}
|
|
46
53
|
console.log('');
|
|
47
54
|
}
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
55
|
+
if (all) {
|
|
56
|
+
console.log('Capabilities:');
|
|
57
|
+
console.log(' capabilities:list Lista capabilities descobríveis');
|
|
58
|
+
console.log(' capabilities:describe Descreve uma capability');
|
|
59
|
+
console.log(' capability:execute Executa uma capability com input JSON');
|
|
60
|
+
console.log(' mcp:start Inicia o transporte MCP JSON-RPC por stdio');
|
|
61
|
+
}
|
|
62
|
+
else {
|
|
63
|
+
console.log(`Detalhe de um comando: forja help <comando>`);
|
|
64
|
+
console.log(`use 'forja help --all' para os ${hidden} comandos restantes`);
|
|
65
|
+
}
|
|
53
66
|
console.log('Toda execução é auditada em .context/forja-runs.jsonl (workspace, se existir).');
|
|
54
67
|
}
|
|
68
|
+
// `forja help <comando>` — uso, argumentos, exemplos e próximos passos. Retorna o exit code.
|
|
69
|
+
function printCommandHelp(cmdName) {
|
|
70
|
+
const cmd = COMMANDS[cmdName];
|
|
71
|
+
if (!cmd) {
|
|
72
|
+
console.error(`Comando desconhecido: ${cmdName}`);
|
|
73
|
+
const near = suggest(cmdName);
|
|
74
|
+
if (near.length)
|
|
75
|
+
console.error(`Você quis dizer: ${near.join(', ')}?`);
|
|
76
|
+
console.error("Liste tudo com: forja help --all");
|
|
77
|
+
if (near.length)
|
|
78
|
+
console.error(`Detalhe do palpite: forja help ${near[0]}`);
|
|
79
|
+
return 1;
|
|
80
|
+
}
|
|
81
|
+
const label = DOMAINS[cmd.domain] ?? cmd.domain;
|
|
82
|
+
const tags = [`domínio: ${label}`];
|
|
83
|
+
if (cmd.spec)
|
|
84
|
+
tags.push(`origem: ${cmd.spec}`);
|
|
85
|
+
if (cmd.readonly)
|
|
86
|
+
tags.push('somente leitura');
|
|
87
|
+
console.log(`forja ${cmdName}`);
|
|
88
|
+
console.log(` ${cmd.desc}`);
|
|
89
|
+
console.log(` ${tags.join(' · ')}`);
|
|
90
|
+
console.log(`\nUso: ${cmd.usage ?? `forja ${cmdName}`}`);
|
|
91
|
+
if (cmd.cliArgs?.length) {
|
|
92
|
+
console.log('\nArgumentos:');
|
|
93
|
+
for (const a of cmd.cliArgs) {
|
|
94
|
+
console.log(` ${a.name.padEnd(12)} ${(a.required ? '(obrigatório)' : '(opcional) ')} ${a.desc}`);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
if (cmd.examples?.length) {
|
|
98
|
+
console.log('\nExemplos:');
|
|
99
|
+
for (const ex of cmd.examples)
|
|
100
|
+
console.log(` ${ex}`);
|
|
101
|
+
}
|
|
102
|
+
if (cmd.next?.length) {
|
|
103
|
+
console.log('\nProximos passos:');
|
|
104
|
+
for (const n of cmd.next) {
|
|
105
|
+
const nc = COMMANDS[n];
|
|
106
|
+
console.log(` forja ${n}${nc ? ` — ${nc.desc}` : ''}`);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
if (cmd.tier !== 'core')
|
|
110
|
+
console.log("\n(comando avançado — 'forja help --all' lista todos)");
|
|
111
|
+
return 0;
|
|
112
|
+
}
|
|
113
|
+
// Distância de edição (Levenshtein). ~15 linhas, sem dependência (plan §D3).
|
|
114
|
+
function levenshtein(a, b) {
|
|
115
|
+
const m = a.length, n = b.length;
|
|
116
|
+
if (m === 0)
|
|
117
|
+
return n;
|
|
118
|
+
if (n === 0)
|
|
119
|
+
return m;
|
|
120
|
+
let prev = Array.from({ length: n + 1 }, (_, i) => i);
|
|
121
|
+
let curr = new Array(n + 1);
|
|
122
|
+
for (let i = 1; i <= m; i++) {
|
|
123
|
+
curr[0] = i;
|
|
124
|
+
for (let j = 1; j <= n; j++) {
|
|
125
|
+
const cost = a[i - 1] === b[j - 1] ? 0 : 1;
|
|
126
|
+
curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
|
|
127
|
+
}
|
|
128
|
+
[prev, curr] = [curr, prev];
|
|
129
|
+
}
|
|
130
|
+
return prev[n];
|
|
131
|
+
}
|
|
132
|
+
// SPEC-043: casa por substring E distância de edição (≤ 2) sobre o nome completo e sobre o último
|
|
133
|
+
// segmento — `forja plan` passa a sugerir `spec:plan`. Determinística, teto de 5.
|
|
55
134
|
function suggest(input) {
|
|
56
|
-
const
|
|
57
|
-
const
|
|
58
|
-
|
|
59
|
-
|
|
135
|
+
const q = String(input).toLowerCase();
|
|
136
|
+
const scored = [];
|
|
137
|
+
for (const n of Object.keys(COMMANDS)) {
|
|
138
|
+
const ln = n.toLowerCase();
|
|
139
|
+
let rank;
|
|
140
|
+
if (ln === q)
|
|
141
|
+
rank = 0;
|
|
142
|
+
else if (ln.includes(q) || q.includes(ln))
|
|
143
|
+
rank = 1;
|
|
144
|
+
else {
|
|
145
|
+
const seg = ln.includes(':') ? ln.slice(ln.lastIndexOf(':') + 1) : ln;
|
|
146
|
+
const best = Math.min(levenshtein(q, ln), levenshtein(q, seg));
|
|
147
|
+
if (best > 2)
|
|
148
|
+
continue;
|
|
149
|
+
rank = 2 + best;
|
|
150
|
+
}
|
|
151
|
+
scored.push({ name: n, rank });
|
|
152
|
+
}
|
|
153
|
+
scored.sort((a, b) => a.rank - b.rank || a.name.localeCompare(b.name));
|
|
154
|
+
return scored.slice(0, 5).map((s) => s.name);
|
|
155
|
+
}
|
|
156
|
+
// Args posicionais obrigatórios em falta — verificado antes de qualquer spawn (AC-5).
|
|
157
|
+
function missingRequiredArg(cmd, rest) {
|
|
158
|
+
const required = (cmd.cliArgs ?? []).filter((a) => a.required);
|
|
159
|
+
if (required.length === 0)
|
|
160
|
+
return null;
|
|
161
|
+
const positionals = [];
|
|
162
|
+
for (let i = 0; i < rest.length; i++) {
|
|
163
|
+
const tok = rest[i];
|
|
164
|
+
if (tok === '--')
|
|
165
|
+
break;
|
|
166
|
+
if (tok.startsWith('-')) {
|
|
167
|
+
if (rest[i + 1] !== undefined && !rest[i + 1].startsWith('-'))
|
|
168
|
+
i++;
|
|
169
|
+
continue;
|
|
170
|
+
}
|
|
171
|
+
positionals.push(tok);
|
|
172
|
+
}
|
|
173
|
+
if (positionals.length >= required.length)
|
|
174
|
+
return null;
|
|
175
|
+
const missing = required.slice(positionals.length).map((a) => `<${a.name}>`).join(' ');
|
|
176
|
+
return `Faltou argumento obrigatório: ${missing}`;
|
|
60
177
|
}
|
|
61
178
|
// Gates transversais (ADR-0020). Retorna lista de erros bloqueantes.
|
|
62
179
|
function runGates(cmd) {
|
|
@@ -77,6 +194,18 @@ function runGates(cmd) {
|
|
|
77
194
|
}
|
|
78
195
|
return errors;
|
|
79
196
|
}
|
|
197
|
+
/**
|
|
198
|
+
* Contrato de saída (ADR-0082 / SPEC-045) — os exit codes que os comandos usam, em qualquer modo:
|
|
199
|
+
*
|
|
200
|
+
* 0 sucesso (`status:'ok'` no `--json`)
|
|
201
|
+
* 1 erro operacional: args inválidos, arquivo ausente, subsistema fora (`status:'error'`)
|
|
202
|
+
* 2 validação/gate do próprio comando deu negativo (`status:'rejected'`) — ex.: `llm:run`,
|
|
203
|
+
* `simulate` discard
|
|
204
|
+
* 127 binário externo obrigatório ausente (alvos `bin:` — tratado abaixo, na seção de spawn)
|
|
205
|
+
*
|
|
206
|
+
* O core repassa o exit code do filho tal e qual (`result.status ?? 1`); `2` passa direto. Ver
|
|
207
|
+
* `docs/contrato-saida-cli.md`.
|
|
208
|
+
*/
|
|
80
209
|
// Auditoria nunca bloqueia o comando (NFR da SPEC-025).
|
|
81
210
|
function audit(entry) {
|
|
82
211
|
try {
|
|
@@ -130,6 +259,46 @@ function auditArgs(command, args) {
|
|
|
130
259
|
return args;
|
|
131
260
|
return args.map((arg, index) => args[index - 1] === '--prompt' ? '<redacted>' : arg);
|
|
132
261
|
}
|
|
262
|
+
// SPEC-046 / ADR-0083: no modo --json, a saída de um comando-capability segue o contrato de
|
|
263
|
+
// saída (ADR-0082), não o ExecutionResult cru. Único ponto que conhece o mapa envelope→contrato.
|
|
264
|
+
function mergeChildStdout(stdout) {
|
|
265
|
+
const trimmed = stdout.trim();
|
|
266
|
+
if (!trimmed)
|
|
267
|
+
return {};
|
|
268
|
+
try {
|
|
269
|
+
const parsed = JSON.parse(trimmed);
|
|
270
|
+
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
|
|
271
|
+
const { status: _dropChildStatus, ...rest } = parsed;
|
|
272
|
+
return rest;
|
|
273
|
+
}
|
|
274
|
+
return { raw: parsed };
|
|
275
|
+
}
|
|
276
|
+
catch {
|
|
277
|
+
return { raw: stdout };
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
function toContract(result) {
|
|
281
|
+
const r = result;
|
|
282
|
+
// Erro antes de executar a capability (ex.: input inválido) — vem como `{ error: string }`.
|
|
283
|
+
if (r && typeof r === 'object' && typeof r.error === 'string') {
|
|
284
|
+
return { json: { status: 'error', error: { message: String(r.error) } }, exitCode: 1 };
|
|
285
|
+
}
|
|
286
|
+
const payload = r.output?.payload ?? {};
|
|
287
|
+
const childExit = typeof payload.exitCode === 'number' ? payload.exitCode : undefined;
|
|
288
|
+
const stdout = typeof payload.stdout === 'string' ? payload.stdout : '';
|
|
289
|
+
const stderr = typeof payload.stderr === 'string' ? payload.stderr : '';
|
|
290
|
+
if (stderr.trim())
|
|
291
|
+
process.stderr.write(stderr.endsWith('\n') ? stderr : `${stderr}\n`);
|
|
292
|
+
const merged = mergeChildStdout(stdout);
|
|
293
|
+
if (r.status === 'succeeded' && (childExit === undefined || childExit === 0)) {
|
|
294
|
+
return { json: { status: 'ok', ...merged }, exitCode: 0 };
|
|
295
|
+
}
|
|
296
|
+
if (r.status === 'succeeded' && childExit === 2) {
|
|
297
|
+
return { json: { status: 'rejected', ...merged }, exitCode: 2 };
|
|
298
|
+
}
|
|
299
|
+
const message = r.error?.message ?? `comando terminou com exit ${childExit ?? 1}`;
|
|
300
|
+
return { json: { status: 'error', error: { message, ...(r.error?.code ? { code: r.error.code } : {}) }, ...merged }, exitCode: 1 };
|
|
301
|
+
}
|
|
133
302
|
function printExecutionResult(result, json) {
|
|
134
303
|
if (json) {
|
|
135
304
|
console.log(JSON.stringify(result));
|
|
@@ -206,6 +375,24 @@ async function runCapabilityCommand(command, args) {
|
|
|
206
375
|
commandSucceeded = false;
|
|
207
376
|
}
|
|
208
377
|
}
|
|
378
|
+
// SPEC-046: comando-capability em --json → contrato de saída (ADR-0083), não o ExecutionResult cru.
|
|
379
|
+
if (json && !command.startsWith('capabilit')) {
|
|
380
|
+
const contract = toContract(result);
|
|
381
|
+
console.log(JSON.stringify(contract.json));
|
|
382
|
+
const exec = result;
|
|
383
|
+
audit({
|
|
384
|
+
ts: new Date().toISOString(),
|
|
385
|
+
cmd: command,
|
|
386
|
+
args,
|
|
387
|
+
capabilityId,
|
|
388
|
+
runId: exec.runId,
|
|
389
|
+
correlationId: exec.correlationId,
|
|
390
|
+
status: contract.json.status,
|
|
391
|
+
exitCode: contract.exitCode,
|
|
392
|
+
durationMs: Date.now() - started,
|
|
393
|
+
});
|
|
394
|
+
return contract.exitCode;
|
|
395
|
+
}
|
|
209
396
|
printExecutionResult(result, json || command.startsWith('capabilit'));
|
|
210
397
|
const execution = result;
|
|
211
398
|
const payload = execution.output?.payload;
|
|
@@ -290,7 +477,13 @@ function createGraphSyncComposition() {
|
|
|
290
477
|
}
|
|
291
478
|
const [name, ...rest] = process.argv.slice(2);
|
|
292
479
|
if (!name || name === 'help' || name === '--help' || name === '-h') {
|
|
293
|
-
|
|
480
|
+
if (rest[0] === '--all' || rest[0] === '-a') {
|
|
481
|
+
printHelp(true);
|
|
482
|
+
process.exit(0);
|
|
483
|
+
}
|
|
484
|
+
if (rest[0])
|
|
485
|
+
process.exit(printCommandHelp(rest[0]));
|
|
486
|
+
printHelp(false);
|
|
294
487
|
process.exit(0);
|
|
295
488
|
}
|
|
296
489
|
// O pacote instalado dentro de um projeto opera o próprio cwd. Operações que administram vários
|
|
@@ -310,7 +503,31 @@ if (!cmd) {
|
|
|
310
503
|
if (near.length) {
|
|
311
504
|
console.error(`Você quis dizer: ${near.join(', ')}?`);
|
|
312
505
|
}
|
|
313
|
-
console.error('Liste tudo com: forja help');
|
|
506
|
+
console.error('Liste tudo com: forja help --all');
|
|
507
|
+
if (near.length)
|
|
508
|
+
console.error(`Detalhe do palpite: forja help ${near[0]}`);
|
|
509
|
+
process.exit(1);
|
|
510
|
+
}
|
|
511
|
+
// `forja <cmd> --help` → detalhe do comando.
|
|
512
|
+
if (rest.includes('--help') || rest.includes('-h')) {
|
|
513
|
+
process.exit(printCommandHelp(name));
|
|
514
|
+
}
|
|
515
|
+
// SPEC-043 (AC-5): args posicionais obrigatórios em falta falham aqui, sem spawnar o filho.
|
|
516
|
+
// SPEC-045 (ADR-0082): se o comando é `json: true` e o operador pediu `--json`, o erro sai no
|
|
517
|
+
// formato do contrato (`{status:'error'}`, exit 1) em vez do texto de uso.
|
|
518
|
+
const argError = missingRequiredArg(cmd, rest);
|
|
519
|
+
if (argError) {
|
|
520
|
+
const usage = cmd.usage ?? `forja ${name}`;
|
|
521
|
+
if (cmd.json && rest.includes('--json')) {
|
|
522
|
+
process.stderr.write(`Uso: ${usage}\n`);
|
|
523
|
+
process.stdout.write(JSON.stringify({ status: 'error', error: { message: argError, code: 'MISSING_ARG' } }) + '\n');
|
|
524
|
+
}
|
|
525
|
+
else {
|
|
526
|
+
console.error(argError);
|
|
527
|
+
console.error(`Uso: ${usage}`);
|
|
528
|
+
console.error(`Detalhe: forja help ${name}`);
|
|
529
|
+
}
|
|
530
|
+
audit({ ts: new Date().toISOString(), cmd: name, args: auditArgs(name, rest), exitCode: 1, durationMs: 0 });
|
|
314
531
|
process.exit(1);
|
|
315
532
|
}
|
|
316
533
|
const gateErrors = runGates(cmd);
|
|
@@ -328,7 +545,11 @@ if (gateErrors.length) {
|
|
|
328
545
|
});
|
|
329
546
|
process.exit(1);
|
|
330
547
|
}
|
|
331
|
-
|
|
548
|
+
// SPEC-046: alguns comandos são capability (para o MCP) mas têm script próprio que já trata
|
|
549
|
+
// `--json` e a saída de texto (`status`, `next`, `engineer`). No CLI eles rodam direto — a
|
|
550
|
+
// camada de capability só serve o MCP e os comandos sem `--json` nativo.
|
|
551
|
+
const NATIVE_JSON_CAPABILITIES = new Set(['status', 'next', 'engineer']);
|
|
552
|
+
if (capabilityIdForCommand(name) !== undefined && !NATIVE_JSON_CAPABILITIES.has(name)) {
|
|
332
553
|
process.exit(await runCapabilityCommand(name, rest));
|
|
333
554
|
}
|
|
334
555
|
const started = Date.now();
|
package/dist/bin/init-project.js
CHANGED
|
@@ -16,6 +16,7 @@ import path from 'node:path';
|
|
|
16
16
|
import process from 'node:process';
|
|
17
17
|
import { execSync } from 'node:child_process';
|
|
18
18
|
import { fileURLToPath } from 'node:url';
|
|
19
|
+
import { writeAiInstructions } from "../lib/multi-ai-instructions.js";
|
|
19
20
|
import { getWorkspaceRoot, resolveProject, initWorkspace, getWorkspaceProjectsMemoryDir, assertOutsideFrameworkRepo, } from "../lib/workspace.js";
|
|
20
21
|
const __filename = fileURLToPath(import.meta.url);
|
|
21
22
|
const __dirname = path.dirname(__filename);
|
|
@@ -24,16 +25,9 @@ const kitRoot = path.resolve(__dirname, '..');
|
|
|
24
25
|
// CONFIGURAÇÃO
|
|
25
26
|
// ============================================================================
|
|
26
27
|
const DEFAULT_AI_AGENTS = ['copilot', 'claude', 'gemini', 'codex'];
|
|
27
|
-
// Conteúdo canônico único (ADR-0020): toda IA recebe a mesma explicação da
|
|
28
|
-
//
|
|
29
|
-
// ele descreve o
|
|
30
|
-
const CANONICAL_INSTRUCTIONS = '.gemini-instructions.md';
|
|
31
|
-
const AI_LABELS = {
|
|
32
|
-
copilot: 'GitHub Copilot',
|
|
33
|
-
claude: 'Claude',
|
|
34
|
-
gemini: 'Gemini',
|
|
35
|
-
codex: 'OpenAI Codex',
|
|
36
|
-
};
|
|
28
|
+
// Conteúdo canônico único (ADR-0020): toda IA recebe a mesma explicação da estrutura Forja; só o
|
|
29
|
+
// cabeçalho muda. A escrita vive em lib/multi-ai-instructions.ts (SPEC-047) e é compartilhada com
|
|
30
|
+
// o project:smoke. CLAUDE.md do framework NÃO é copiado — ele descreve o motor, não o gerado.
|
|
37
31
|
const SETUP_CHECKLIST = [
|
|
38
32
|
'00-git-init',
|
|
39
33
|
'01-generate-structure',
|
|
@@ -268,58 +262,13 @@ async function step01cEmitHarness(projectDir, opts) {
|
|
|
268
262
|
}
|
|
269
263
|
async function step02CopyInstructions(projectDir, opts) {
|
|
270
264
|
log('Copiando instruções para IAs...', 'step');
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
const
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
}
|
|
278
|
-
let copied = 0;
|
|
279
|
-
for (const ai of opts.ai) {
|
|
280
|
-
const label = AI_LABELS[ai];
|
|
281
|
-
if (!label || !canonical) {
|
|
282
|
-
log(`${ai.toUpperCase()}: não encontrado`, 'warn');
|
|
283
|
-
continue;
|
|
284
|
-
}
|
|
285
|
-
const others = Object.entries(AI_LABELS)
|
|
286
|
-
.filter(([key]) => key !== ai)
|
|
287
|
-
.map(([, name]) => name);
|
|
288
|
-
const content = canonical
|
|
289
|
-
.replace(/^# Instruções para .+ — Forja$/m, `# Instruções para ${label} — Forja`)
|
|
290
|
-
.replace(/^> Guia para .+ multi-IA por design\.$/m, `> Guia para ${label} operar a Forja. O conteúdo é o mesmo para ${others.slice(0, -1).join(', ')} e ${others.at(-1)} — a Forja é multi-IA por design.`);
|
|
291
|
-
fs.writeFileSync(path.join(instructionsDir, `${ai}.md`), content, 'utf8');
|
|
292
|
-
log(`${ai.toUpperCase()}: ✓`, 'success');
|
|
293
|
-
copied++;
|
|
294
|
-
}
|
|
295
|
-
// Criar INDEX
|
|
296
|
-
const indexContent = `# IA Assistants Configuration
|
|
297
|
-
|
|
298
|
-
Este diretório contém instruções específicas para cada IA assistant.
|
|
299
|
-
|
|
300
|
-
## Gestão de Cotas & Alternância
|
|
301
|
-
Para trocar de IA (ex: se acabar a cota), use o arquivo [models.json](./models.json) para identificar o próximo motor na fila de fallback.
|
|
302
|
-
|
|
303
|
-
## IAs Configuradas
|
|
304
|
-
|
|
305
|
-
${opts.ai.map((ai) => `- [${ai.toUpperCase()}](./${ai}.md)`).join('\n')}
|
|
306
|
-
`;
|
|
307
|
-
fs.writeFileSync(path.join(instructionsDir, 'README.md'), indexContent);
|
|
308
|
-
// Criar models.json para interoperabilidade
|
|
309
|
-
const modelsJson = {
|
|
310
|
-
active_engine: opts.ai[0] || 'copilot',
|
|
311
|
-
fallback_chain: opts.ai,
|
|
312
|
-
engines: opts.ai.reduce((acc, ai) => {
|
|
313
|
-
acc[ai] = {
|
|
314
|
-
name: ai.toUpperCase(),
|
|
315
|
-
instruction_file: `.ia-instructions/${ai}.md`,
|
|
316
|
-
status: "ready"
|
|
317
|
-
};
|
|
318
|
-
return acc;
|
|
319
|
-
}, {})
|
|
320
|
-
};
|
|
321
|
-
fs.writeFileSync(path.join(instructionsDir, 'models.json'), JSON.stringify(modelsJson, null, 2));
|
|
322
|
-
log(`${copied} instruções copiadas para .ia-instructions/`, 'success');
|
|
265
|
+
// A lógica vive em lib/multi-ai-instructions.ts (SPEC-047) — compartilhada com o project:smoke.
|
|
266
|
+
const { written, skipped } = writeAiInstructions(projectDir, opts.ai, { kitRoot });
|
|
267
|
+
for (const ai of written)
|
|
268
|
+
log(`${String(ai).toUpperCase()}: ✓`, 'success');
|
|
269
|
+
for (const ai of skipped)
|
|
270
|
+
log(`${String(ai).toUpperCase()}: não encontrado`, 'warn');
|
|
271
|
+
log(`${written.length} instruções copiadas para .ia-instructions/`, 'success');
|
|
323
272
|
}
|
|
324
273
|
async function step03InstallBackend(projectDir, opts) {
|
|
325
274
|
if (opts.skipBackend) {
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/cli-output.ts — o contrato de saída `--json` da CLI (SPEC-045, ADR-0082).
|
|
3
|
+
*
|
|
4
|
+
* Três saídas, cada uma termina o processo com o exit code certo:
|
|
5
|
+
*
|
|
6
|
+
* emitOk(fields?) → stdout {status:'ok', ...fields} · exit 0
|
|
7
|
+
* emitError(msg, opts?) → stdout {status:'error', error:{...}} · exit 1 (opts.detail → stderr)
|
|
8
|
+
* emitRejected(fields?) → stdout {status:'rejected', ...fields} · exit 2
|
|
9
|
+
*
|
|
10
|
+
* O stdout carrega **um único** objeto JSON, sempre. Diagnóstico verboso vai para o stderr.
|
|
11
|
+
* Use só no ramo `--json`; a saída de texto de cada comando continua como está.
|
|
12
|
+
*/
|
|
13
|
+
type JsonFields = Record<string, unknown>;
|
|
14
|
+
/** Sucesso. `fields` são os dados do comando, no topo, ao lado de `status`. */
|
|
15
|
+
export declare function emitOk(fields?: JsonFields): never;
|
|
16
|
+
/**
|
|
17
|
+
* Falha operacional: args inválidos, arquivo ausente, subsistema fora. `opts.detail` (rastro
|
|
18
|
+
* verboso, nunca stack trace cru) vai para o stderr; nunca para o stdout.
|
|
19
|
+
*/
|
|
20
|
+
export declare function emitError(message: string, opts?: {
|
|
21
|
+
code?: string;
|
|
22
|
+
detail?: string;
|
|
23
|
+
}): never;
|
|
24
|
+
/**
|
|
25
|
+
* Uma validação ou gate que o **próprio comando** roda deu negativo (ex.: `simulate` discard,
|
|
26
|
+
* checks de `llm:run`). O payload da avaliação segue no objeto.
|
|
27
|
+
*/
|
|
28
|
+
export declare function emitRejected(fields?: JsonFields): never;
|
|
29
|
+
export {};
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/cli-output.ts — o contrato de saída `--json` da CLI (SPEC-045, ADR-0082).
|
|
3
|
+
*
|
|
4
|
+
* Três saídas, cada uma termina o processo com o exit code certo:
|
|
5
|
+
*
|
|
6
|
+
* emitOk(fields?) → stdout {status:'ok', ...fields} · exit 0
|
|
7
|
+
* emitError(msg, opts?) → stdout {status:'error', error:{...}} · exit 1 (opts.detail → stderr)
|
|
8
|
+
* emitRejected(fields?) → stdout {status:'rejected', ...fields} · exit 2
|
|
9
|
+
*
|
|
10
|
+
* O stdout carrega **um único** objeto JSON, sempre. Diagnóstico verboso vai para o stderr.
|
|
11
|
+
* Use só no ramo `--json`; a saída de texto de cada comando continua como está.
|
|
12
|
+
*/
|
|
13
|
+
function write(payload, code) {
|
|
14
|
+
process.stdout.write(JSON.stringify(payload) + '\n');
|
|
15
|
+
process.exit(code);
|
|
16
|
+
}
|
|
17
|
+
/** Sucesso. `fields` são os dados do comando, no topo, ao lado de `status`. */
|
|
18
|
+
export function emitOk(fields = {}) {
|
|
19
|
+
return write({ status: 'ok', ...fields }, 0);
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Falha operacional: args inválidos, arquivo ausente, subsistema fora. `opts.detail` (rastro
|
|
23
|
+
* verboso, nunca stack trace cru) vai para o stderr; nunca para o stdout.
|
|
24
|
+
*/
|
|
25
|
+
export function emitError(message, opts = {}) {
|
|
26
|
+
if (opts.detail)
|
|
27
|
+
process.stderr.write(opts.detail.replace(/\s+$/, '') + '\n');
|
|
28
|
+
const error = { message };
|
|
29
|
+
if (opts.code)
|
|
30
|
+
error.code = opts.code;
|
|
31
|
+
return write({ status: 'error', error }, 1);
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Uma validação ou gate que o **próprio comando** roda deu negativo (ex.: `simulate` discard,
|
|
35
|
+
* checks de `llm:run`). O payload da avaliação segue no objeto.
|
|
36
|
+
*/
|
|
37
|
+
export function emitRejected(fields = {}) {
|
|
38
|
+
return write({ status: 'rejected', ...fields }, 2);
|
|
39
|
+
}
|
|
@@ -79,7 +79,7 @@ export declare function runChecks({ checks, scope, env }: {
|
|
|
79
79
|
* @param {Result[]} results
|
|
80
80
|
* @returns {'ok'|'warn'|'fail'}
|
|
81
81
|
*/
|
|
82
|
-
export declare function worstStatus(results: any): "
|
|
82
|
+
export declare function worstStatus(results: any): "ok" | "warn" | "fail";
|
|
83
83
|
/**
|
|
84
84
|
* Remove template literals do fonte antes de qualquer análise estática de `import`.
|
|
85
85
|
*
|
|
@@ -57,6 +57,15 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
57
57
|
export declare function isFrameworkRepo(env: any): boolean;
|
|
58
58
|
/** @type {Check[]} */
|
|
59
59
|
export declare const CHECKS: Check[];
|
|
60
|
+
/**
|
|
61
|
+
* SPEC-043 (AC-7): em qual bloco cada resultado aparece no `tools:doctor` e no hook SessionStart.
|
|
62
|
+
* `blocking` pode travar o fluxo (exit 1 quando `critical`). `first-run` é rotina de clone novo,
|
|
63
|
+
* que `forja setup` resolve. `optional` são as ferramentas ADR-0018, que nunca travam.
|
|
64
|
+
* É um mapa por `id` de propósito: não toca o tipo `Check` nem o runner (`runChecks` intacto).
|
|
65
|
+
*/
|
|
66
|
+
export type HealthBucket = 'blocking' | 'first-run' | 'optional';
|
|
67
|
+
export declare function bucketFor(id: string): HealthBucket;
|
|
68
|
+
export declare const BUCKET_LABEL: Record<HealthBucket, string>;
|
|
60
69
|
/**
|
|
61
70
|
* Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
|
|
62
71
|
* `defaultEnv` do framework, que o runner genérico não conhece nem deve conhecer.
|
package/dist/lib/core/health.js
CHANGED
|
@@ -611,6 +611,15 @@ export const CHECKS = [
|
|
|
611
611
|
adrRefs,
|
|
612
612
|
agentTopology,
|
|
613
613
|
];
|
|
614
|
+
const FIRST_RUN_CHECKS = new Set(['memory-db', 'memory-fresh', 'workspace']);
|
|
615
|
+
export function bucketFor(id) {
|
|
616
|
+
return FIRST_RUN_CHECKS.has(id) ? 'first-run' : 'blocking';
|
|
617
|
+
}
|
|
618
|
+
export const BUCKET_LABEL = {
|
|
619
|
+
blocking: 'Bloqueia o fluxo',
|
|
620
|
+
'first-run': 'Rotina de primeiro uso',
|
|
621
|
+
optional: 'Opcional (ferramentas)',
|
|
622
|
+
};
|
|
614
623
|
/**
|
|
615
624
|
* Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
|
|
616
625
|
* `defaultEnv` do framework, que o runner genérico não conhece nem deve conhecer.
|
|
@@ -20,6 +20,8 @@ interface SmokeEnv {
|
|
|
20
20
|
fs: typeof fs;
|
|
21
21
|
projectDir?: string;
|
|
22
22
|
full: boolean;
|
|
23
|
+
/** SPEC-047: lista de IAs. Presente ⇒ gera só-memória + instruções nativas; ativa `ai-instructions`. */
|
|
24
|
+
ai?: readonly string[];
|
|
23
25
|
spawn: (cmd: string, args: string[], opts?: any) => {
|
|
24
26
|
stdout: string;
|
|
25
27
|
stderr: string;
|
|
@@ -32,15 +34,17 @@ interface SmokeEnv {
|
|
|
32
34
|
*/
|
|
33
35
|
export declare function withGeneratedProject<T>(fn: (ctx: {
|
|
34
36
|
projectDir: string;
|
|
35
|
-
}) => Promise<T> | T, { root, spawn }: {
|
|
37
|
+
}) => Promise<T> | T, { root, spawn, ai }: {
|
|
36
38
|
root?: string;
|
|
37
39
|
spawn: SmokeEnv['spawn'];
|
|
40
|
+
ai?: readonly string[];
|
|
38
41
|
}): Promise<T>;
|
|
39
42
|
/** @type {Check[]} */
|
|
40
43
|
export declare const SMOKE_CHECKS: Check[];
|
|
41
44
|
export declare function defaultEnv(overrides?: Partial<SmokeEnv>): SmokeEnv;
|
|
42
45
|
/** Gera um projeto isolado, roda os checks, limpa. */
|
|
43
|
-
export declare function runProjectSmoke({ full, env: overrides }?: {
|
|
46
|
+
export declare function runProjectSmoke({ full, ai, env: overrides }?: {
|
|
44
47
|
full?: boolean;
|
|
48
|
+
ai?: string[];
|
|
45
49
|
env?: Partial<SmokeEnv>;
|
|
46
50
|
}): Promise<import("./checks.ts").Result[]>;
|