forjajs 4.0.1 → 4.1.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 (96) hide show
  1. package/CHANGELOG.md +170 -7
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +10 -2
  4. package/README.pt-BR.md +3 -0
  5. package/dist/apps/cli/src/index.d.ts +18 -1
  6. package/dist/apps/cli/src/index.js +161 -26
  7. package/dist/apps/cli/src/params.d.ts +44 -0
  8. package/dist/apps/cli/src/params.js +123 -0
  9. package/dist/bin/forja.js +234 -13
  10. package/dist/bin/init-project.js +11 -62
  11. package/dist/lib/cli-output.d.ts +29 -0
  12. package/dist/lib/cli-output.js +39 -0
  13. package/dist/lib/core/checks.d.ts +1 -1
  14. package/dist/lib/core/health.d.ts +9 -0
  15. package/dist/lib/core/health.js +9 -0
  16. package/dist/lib/core/project-smoke.d.ts +6 -2
  17. package/dist/lib/core/project-smoke.js +83 -7
  18. package/dist/lib/core/registry.d.ts +38 -571
  19. package/dist/lib/core/registry.js +174 -25
  20. package/dist/lib/core/release.d.ts +1 -571
  21. package/dist/lib/core/release.js +0 -3
  22. package/dist/lib/handoffs-index.d.ts +16 -0
  23. package/dist/lib/handoffs-index.js +29 -0
  24. package/dist/lib/llm/claude-output.d.ts +8 -0
  25. package/dist/lib/llm/claude-output.js +54 -0
  26. package/dist/lib/llm/context.d.ts +22 -0
  27. package/dist/lib/llm/context.js +39 -0
  28. package/dist/lib/llm/session.d.ts +6 -1
  29. package/dist/lib/llm/session.js +12 -2
  30. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  31. package/dist/lib/multi-ai-instructions.js +83 -0
  32. package/dist/lib/orchestrate.d.ts +5 -0
  33. package/dist/lib/orchestrate.js +18 -0
  34. package/dist/lib/specs-index.d.ts +20 -0
  35. package/dist/lib/specs-index.js +51 -0
  36. package/dist/lib/sprint-index.d.ts +15 -0
  37. package/dist/lib/sprint-index.js +34 -0
  38. package/dist/lib/status-model.d.ts +64 -0
  39. package/dist/lib/status-model.js +180 -0
  40. package/dist/packages/evals/src/index.d.ts +2 -0
  41. package/dist/packages/evals/src/index.js +21 -0
  42. package/dist/packages/llm/src/index.d.ts +24 -3
  43. package/dist/packages/llm/src/index.js +51 -5
  44. package/dist/scripts/cost-economy.js +12 -10
  45. package/dist/scripts/drift-check.d.ts +2 -0
  46. package/dist/scripts/drift-check.js +57 -1
  47. package/dist/scripts/engineer.js +7 -4
  48. package/dist/scripts/forja-setup.d.ts +14 -0
  49. package/dist/scripts/forja-setup.js +58 -0
  50. package/dist/scripts/forja-status.d.ts +11 -0
  51. package/dist/scripts/forja-status.js +70 -0
  52. package/dist/scripts/hook-session-start.js +20 -46
  53. package/dist/scripts/llm-fit.js +113 -8
  54. package/dist/scripts/project-smoke.js +13 -3
  55. package/dist/scripts/simulate.js +18 -6
  56. package/dist/scripts/token-economy.js +34 -28
  57. package/dist/scripts/tools-doctor.js +14 -6
  58. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  59. package/docs/agent-operating-contract.md +3 -1
  60. package/docs/cli-first-operacao.md +17 -0
  61. package/docs/contrato-saida-cli.md +79 -0
  62. package/docs/llm-evolution.md +2 -1
  63. package/docs/llm-fit-loop.md +74 -2
  64. package/docs/publishing.md +13 -16
  65. package/docs/quick-reference.md +13 -0
  66. package/docs/roadmap-v4.1.md +199 -0
  67. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  68. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  69. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  70. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  71. package/package.json +4 -1
  72. package/specs/cli-intuitiva-v1/plan.md +169 -0
  73. package/specs/cli-intuitiva-v1/spec.md +163 -0
  74. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  75. package/specs/contrato-saida-cli/plan.md +162 -0
  76. package/specs/contrato-saida-cli/spec.md +157 -0
  77. package/specs/contrato-saida-cli/tasks.md +153 -0
  78. package/specs/drift-sentinel/spec.md +17 -8
  79. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  80. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  81. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  82. package/specs/llm-adaptador-claude/plan.md +117 -0
  83. package/specs/llm-adaptador-claude/spec.md +144 -0
  84. package/specs/llm-adaptador-claude/tasks.md +100 -0
  85. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  86. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  87. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  88. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  89. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  90. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  91. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  92. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  93. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  94. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  95. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  96. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -0,0 +1,123 @@
1
+ /**
2
+ * apps/cli/src/params.ts — mapeamento declarativo argv↔payload de um comando-capability
3
+ * (SPEC-046, ADR-0083).
4
+ *
5
+ * `parseArgv` e `argvFor` são inversas. Um teste de round-trip
6
+ * (`argvFor(params, parseArgv(params, argv)) === argv`) para todo spec é o contrato que impede
7
+ * as duas de divergirem — o `if/else` por comando que existia antes não tinha esse contrato.
8
+ *
9
+ * Convenção de ordem em `argvFor`: os params são emitidos na ordem em que aparecem em `params`.
10
+ * Um `positional` opcional só é seguro antes de outro `positional` se o anterior estiver sempre
11
+ * presente — na prática, opcionais ficam por último.
12
+ */
13
+ function coerce(value, parse) {
14
+ return parse === 'int' ? Number(value) : value;
15
+ }
16
+ /** argv → `{ [param.name]: value }`. Flags desconhecidas são ignoradas. */
17
+ export function parseArgv(params, argv) {
18
+ const positionals = params.filter((p) => p.kind === 'positional');
19
+ const rest = params.find((p) => p.kind === 'rest');
20
+ const flagValues = new Map(params
21
+ .filter((p) => p.kind === 'flag-value')
22
+ .map((p) => [p.flag, p]));
23
+ const flags = new Map(params
24
+ .filter((p) => p.kind === 'flag')
25
+ .map((p) => [`--${p.name}`, p]));
26
+ const out = {};
27
+ const restParts = [];
28
+ let posIdx = 0;
29
+ for (let i = 0; i < argv.length; i += 1) {
30
+ const tok = argv[i];
31
+ if (tok.startsWith('--')) {
32
+ const fv = flagValues.get(tok);
33
+ if (fv !== undefined) {
34
+ const raw = argv[i + 1];
35
+ if (raw !== undefined) {
36
+ out[fv.name] = coerce(raw, fv.parse);
37
+ i += 1;
38
+ }
39
+ continue;
40
+ }
41
+ const fl = flags.get(tok);
42
+ if (fl !== undefined) {
43
+ out[fl.name] = true;
44
+ continue;
45
+ }
46
+ continue; // flag desconhecida — ignora
47
+ }
48
+ if (posIdx < positionals.length) {
49
+ const p = positionals[posIdx];
50
+ posIdx += 1;
51
+ out[p.name] = coerce(tok, p.parse);
52
+ }
53
+ else if (rest !== undefined) {
54
+ restParts.push(tok);
55
+ }
56
+ }
57
+ if (rest !== undefined && restParts.length > 0)
58
+ out[rest.name] = restParts.join(' ');
59
+ return out;
60
+ }
61
+ /** `{ [param.name]: value }` → argv, na ordem de `params`. */
62
+ export function argvFor(params, input) {
63
+ const argv = [];
64
+ for (const p of params) {
65
+ const value = input[p.name];
66
+ if (p.kind === 'positional') {
67
+ if (value !== undefined)
68
+ argv.push(String(value));
69
+ }
70
+ else if (p.kind === 'flag-value') {
71
+ if (value !== undefined)
72
+ argv.push(p.flag, String(value));
73
+ }
74
+ else if (p.kind === 'flag') {
75
+ if (value === true)
76
+ argv.push(`--${p.name}`);
77
+ }
78
+ else {
79
+ // rest
80
+ const text = value === undefined ? '' : String(value);
81
+ if (text.length > 0)
82
+ argv.push(...text.split(' '));
83
+ }
84
+ }
85
+ return argv;
86
+ }
87
+ /**
88
+ * Validador base a partir de `params`: exige os `required` presentes e o tipo certo
89
+ * (`int` → número finito; resto → string). Specs com limite adicional (range, enum) embrulham
90
+ * esta função.
91
+ */
92
+ export function makeValidator(params) {
93
+ return (value) => {
94
+ if (value === undefined || value === null)
95
+ value = {};
96
+ if (typeof value !== 'object' || Array.isArray(value))
97
+ throw new Error('input deve ser um objeto');
98
+ const input = value;
99
+ const out = {};
100
+ for (const p of params) {
101
+ const v = input[p.name];
102
+ if (v === undefined) {
103
+ if ('required' in p && p.required)
104
+ throw new Error(`campo obrigatório ausente: ${p.name}`);
105
+ continue;
106
+ }
107
+ const wantsInt = (p.kind === 'positional' || p.kind === 'flag-value') && p.parse === 'int';
108
+ if (wantsInt) {
109
+ if (typeof v !== 'number' || !Number.isFinite(v))
110
+ throw new Error(`${p.name} deve ser um número`);
111
+ }
112
+ else if (p.kind === 'flag') {
113
+ if (typeof v !== 'boolean')
114
+ throw new Error(`${p.name} deve ser booleano`);
115
+ }
116
+ else if (typeof v !== 'string' || v.trim().length === 0) {
117
+ throw new Error(`${p.name} deve ser uma string não-vazia`);
118
+ }
119
+ out[p.name] = v;
120
+ }
121
+ return out;
122
+ };
123
+ }
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
- function printHelp() {
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
- console.log('Capabilities:');
49
- console.log(' capabilities:list Lista capabilities descobríveis');
50
- console.log(' capabilities:describe Descreve uma capability');
51
- console.log(' capability:execute Executa uma capability com input JSON');
52
- console.log(' mcp:start Inicia o transporte MCP JSON-RPC por stdio');
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 names = Object.keys(COMMANDS);
57
- const prefix = input.split(':')[0];
58
- const near = names.filter((n) => n.startsWith(prefix) || n.includes(input));
59
- return near.slice(0, 5);
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
- printHelp();
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
- if (capabilityIdForCommand(name) !== undefined) {
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();
@@ -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
- // estrutura Forja; só o cabeçalho muda. CLAUDE.md do framework NÃO é copiado —
29
- // ele descreve o repo do motor, não o projeto gerado.
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
- const instructionsDir = path.join(projectDir, '.ia-instructions');
272
- ensureDir(instructionsDir);
273
- const canonicalPath = path.join(kitRoot, CANONICAL_INSTRUCTIONS);
274
- let canonical = null;
275
- if (fs.existsSync(canonicalPath)) {
276
- canonical = fs.readFileSync(canonicalPath, 'utf8');
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): "warn" | "ok" | "fail";
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.
@@ -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[]>;