forjajs 2.0.3 → 3.0.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.
Files changed (160) hide show
  1. package/.claude/agents/release-auditor.md +19 -10
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +80 -0
  4. package/DOC-MAP.md +9 -0
  5. package/README.md +85 -5
  6. package/README.pt-BR.md +34 -5
  7. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  8. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  9. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  10. package/dist/apps/server/src/forja-nest.module.js +9 -4
  11. package/dist/apps/server/src/main.js +10 -1
  12. package/dist/bin/forja.js +14 -2
  13. package/dist/lib/code-context.js +6 -0
  14. package/dist/lib/core/architecture-gate.d.ts +20 -0
  15. package/dist/lib/core/architecture-gate.js +60 -0
  16. package/dist/lib/core/doc-graph.js +6 -4
  17. package/dist/lib/core/drift-gate.d.ts +18 -0
  18. package/dist/lib/core/drift-gate.js +55 -0
  19. package/dist/lib/core/gates.d.ts +9 -2
  20. package/dist/lib/core/gates.js +13 -2
  21. package/dist/lib/core/health.js +15 -0
  22. package/dist/lib/core/incident-search.d.ts +19 -0
  23. package/dist/lib/core/incident-search.js +32 -0
  24. package/dist/lib/core/model-pricing.d.ts +31 -0
  25. package/dist/lib/core/model-pricing.js +74 -0
  26. package/dist/lib/core/registry.d.ts +248 -0
  27. package/dist/lib/core/registry.js +249 -0
  28. package/dist/lib/core/release.d.ts +247 -0
  29. package/dist/lib/core/release.js +5 -1
  30. package/dist/lib/core/risk-collect.d.ts +19 -0
  31. package/dist/lib/core/risk-collect.js +173 -0
  32. package/dist/lib/drift-sentinel.d.ts +59 -0
  33. package/dist/lib/drift-sentinel.js +126 -0
  34. package/dist/lib/generators/memory-generator.js +8 -6
  35. package/dist/lib/generators/nest-generator.js +24 -10
  36. package/dist/lib/project-upgrade.js +1 -1
  37. package/dist/lib/workspace.d.ts +7 -0
  38. package/dist/lib/workspace.js +34 -5
  39. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  40. package/dist/packages/adapter-git/src/index.js +11 -6
  41. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  42. package/dist/packages/adapter-nest/src/index.js +26 -1
  43. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  44. package/dist/packages/adapter-sqlite/src/index.js +49 -0
  45. package/dist/packages/contracts/src/index.d.ts +33 -0
  46. package/dist/packages/contracts/src/index.js +13 -0
  47. package/dist/packages/core/src/index.d.ts +12 -0
  48. package/dist/packages/core/src/index.js +29 -0
  49. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  50. package/dist/packages/engineering/architecture/src/index.js +131 -0
  51. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  52. package/dist/packages/engineering/evidence/src/index.js +31 -0
  53. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  54. package/dist/packages/engineering/identity/src/index.js +88 -0
  55. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  56. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  57. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  58. package/dist/packages/engineering/provenance/src/index.js +21 -0
  59. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  60. package/dist/packages/engineering/risk/src/index.js +120 -0
  61. package/dist/packages/graph/src/index.d.ts +23 -1
  62. package/dist/packages/graph/src/index.js +88 -15
  63. package/dist/packages/llm/src/index.d.ts +43 -0
  64. package/dist/packages/llm/src/index.js +131 -0
  65. package/dist/packages/mcp/src/index.js +27 -8
  66. package/dist/packages/orchestration/src/index.d.ts +11 -1
  67. package/dist/packages/orchestration/src/index.js +34 -7
  68. package/dist/packages/policy/src/index.d.ts +40 -0
  69. package/dist/packages/policy/src/index.js +39 -4
  70. package/dist/packages/runtime/src/index.js +3 -0
  71. package/dist/packages/sandbox/src/index.d.ts +47 -0
  72. package/dist/packages/sandbox/src/index.js +59 -0
  73. package/dist/packages/validator/src/index.d.ts +8 -0
  74. package/dist/packages/validator/src/index.js +21 -6
  75. package/dist/scripts/adr.d.ts +17 -0
  76. package/dist/scripts/adr.js +152 -0
  77. package/dist/scripts/agent-harness.js +14 -4
  78. package/dist/scripts/agent.d.ts +27 -0
  79. package/dist/scripts/agent.js +249 -0
  80. package/dist/scripts/architecture.d.ts +16 -0
  81. package/dist/scripts/architecture.js +186 -0
  82. package/dist/scripts/cost-economy.d.ts +2 -0
  83. package/dist/scripts/cost-economy.js +79 -0
  84. package/dist/scripts/demo-autonomy.js +15 -8
  85. package/dist/scripts/demo-workspace.d.ts +6 -0
  86. package/dist/scripts/demo-workspace.js +101 -0
  87. package/dist/scripts/drift-check.d.ts +17 -0
  88. package/dist/scripts/drift-check.js +63 -0
  89. package/dist/scripts/engineer.d.ts +20 -0
  90. package/dist/scripts/engineer.js +208 -0
  91. package/dist/scripts/evidence.d.ts +12 -0
  92. package/dist/scripts/evidence.js +55 -0
  93. package/dist/scripts/gates.d.ts +6 -2
  94. package/dist/scripts/gates.js +14 -4
  95. package/dist/scripts/incident.d.ts +19 -0
  96. package/dist/scripts/incident.js +103 -0
  97. package/dist/scripts/llm-fit.js +160 -0
  98. package/dist/scripts/provenance.d.ts +14 -0
  99. package/dist/scripts/provenance.js +114 -0
  100. package/dist/scripts/risk.d.ts +15 -0
  101. package/dist/scripts/risk.js +81 -0
  102. package/dist/scripts/simulate.d.ts +20 -0
  103. package/dist/scripts/simulate.js +150 -0
  104. package/dist/scripts/sync-universal-memory.js +19 -6
  105. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  106. package/docs/llm-fit-loop.md +41 -0
  107. package/docs/modos-de-operacao.md +52 -0
  108. package/docs/produto/factsheet-marketing.md +151 -0
  109. package/docs/produto/roteiro-demo.md +47 -0
  110. package/memory/40-delivery/current-sprint.md +3 -6
  111. package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
  112. package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
  113. package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
  114. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  115. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  116. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  117. package/package.json +9 -2
  118. package/specs/agent-identity-reputation/plan.md +133 -0
  119. package/specs/agent-identity-reputation/spec.md +125 -0
  120. package/specs/agent-identity-reputation/tasks.md +51 -0
  121. package/specs/agent-runtime-monitoring/plan.md +78 -0
  122. package/specs/agent-runtime-monitoring/spec.md +92 -0
  123. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  124. package/specs/ai-code-provenance/plan.md +71 -0
  125. package/specs/ai-code-provenance/spec.md +97 -0
  126. package/specs/ai-code-provenance/tasks.md +39 -0
  127. package/specs/architecture-constitution/plan.md +110 -0
  128. package/specs/architecture-constitution/spec.md +114 -0
  129. package/specs/architecture-constitution/tasks.md +58 -0
  130. package/specs/change-risk-engine/plan.md +130 -0
  131. package/specs/change-risk-engine/spec.md +119 -0
  132. package/specs/change-risk-engine/tasks.md +72 -0
  133. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  134. package/specs/drift-sentinel/spec.md +117 -0
  135. package/specs/engineer-facade-extension/plan.md +71 -0
  136. package/specs/engineer-facade-extension/spec.md +98 -0
  137. package/specs/engineer-facade-extension/tasks.md +36 -0
  138. package/specs/engineering-evidence-ledger/plan.md +121 -0
  139. package/specs/engineering-evidence-ledger/spec.md +90 -0
  140. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  141. package/specs/engineering-graph-extensions/plan.md +92 -0
  142. package/specs/engineering-graph-extensions/spec.md +101 -0
  143. package/specs/engineering-graph-extensions/tasks.md +60 -0
  144. package/specs/engineering-intelligence/spec.md +177 -0
  145. package/specs/learning-loop-incidents/plan.md +59 -0
  146. package/specs/learning-loop-incidents/spec.md +93 -0
  147. package/specs/learning-loop-incidents/tasks.md +36 -0
  148. package/specs/predictive-change-simulation/plan.md +109 -0
  149. package/specs/predictive-change-simulation/spec.md +107 -0
  150. package/specs/predictive-change-simulation/tasks.md +41 -0
  151. package/specs/release-auditor-health/plan.md +88 -0
  152. package/specs/release-auditor-health/spec.md +82 -0
  153. package/specs/release-auditor-health/tasks.md +72 -0
  154. package/specs/smart-agent-routing/plan.md +55 -0
  155. package/specs/smart-agent-routing/spec.md +85 -0
  156. package/specs/smart-agent-routing/tasks.md +26 -0
  157. package/dist/scripts/server-persistence-probe.d.ts +0 -1
  158. package/dist/scripts/server-persistence-probe.js +0 -52
  159. package/dist/scripts/server-persistence-probe.mjs +0 -52
  160. /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
@@ -0,0 +1,103 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * incident:record / :list / :similar (SPEC-041)
4
+ *
5
+ * forja incident:record --title <t> [--description <d>] grava um incidente no Engineering Graph
6
+ * forja incident:list incidentes registrados, mais recentes primeiro
7
+ * forja incident:similar "<busca>" sugere incidentes parecidos por palavra-chave
8
+ *
9
+ * `GraphNode.type` já é vocabulário livre (`packages/graph`, já existente) — nenhum contrato novo,
10
+ * só um adapter que grava/consulta o tipo `Incident` via `GraphLoop.upsertNode`/`addEvidence`, no
11
+ * mesmo `SqliteGraphStore` compartilhado já usado por `adr:*`/`architecture:*`. Sem reindexação de
12
+ * documentos aqui — incidentes não vêm de arquivo, são escritos diretamente.
13
+ *
14
+ * `incident:similar` é sugestão por palavra-chave — determinístico, nunca aplica nada sozinho
15
+ * (AC-4). Matching local (D1 do plan): nós `Incident` desta versão não têm aresta nenhuma, então
16
+ * `GraphLoop.contextRecords` (que casa contra arestas) não encontraria nada — o estilo de scoring é
17
+ * o mesmo (sobreposição de termos), só a fonte é o nó, não a aresta.
18
+ */
19
+ import fs from 'node:fs';
20
+ import { randomUUID } from 'node:crypto';
21
+ import Database from 'better-sqlite3';
22
+ import { GraphLoop } from "../packages/graph/src/index.js";
23
+ import { SqliteGraphStore, SqliteMigrationRunner } from "../packages/adapter-sqlite/src/index.js";
24
+ import { getWorkspaceDbDir, getWorkspaceDbPath } from "../lib/workspace.js";
25
+ import { incidentRecords, rankIncidentsByQuery, titleOf } from "../lib/core/incident-search.js";
26
+ function flag(args, name) {
27
+ const index = args.indexOf(name);
28
+ return index === -1 ? undefined : args[index + 1];
29
+ }
30
+ function withGraph(fn) {
31
+ fs.mkdirSync(getWorkspaceDbDir(), { recursive: true });
32
+ const database = new Database(process.env.FORJA_RUNTIME_DB ?? getWorkspaceDbPath());
33
+ new SqliteMigrationRunner(database).apply();
34
+ const store = new SqliteGraphStore(database);
35
+ const graph = new GraphLoop(store);
36
+ try {
37
+ return fn(graph, store);
38
+ }
39
+ finally {
40
+ database.close();
41
+ }
42
+ }
43
+ function cmdRecord(args) {
44
+ const title = flag(args, '--title');
45
+ const description = flag(args, '--description');
46
+ if (!title) {
47
+ console.error('Uso: forja incident:record --title <t> [--description <d>]');
48
+ process.exitCode = 1;
49
+ return;
50
+ }
51
+ withGraph((graph) => {
52
+ const id = randomUUID();
53
+ const now = new Date().toISOString();
54
+ graph.addEvidence({ id: `${id}:evidence`, source: 'forja.cli', locator: 'incident:record', capturedAt: now, status: 'verified' });
55
+ graph.upsertNode({ id, type: 'Incident', label: description === undefined ? title : `${title}\n${description}`, status: 'verified' });
56
+ console.log(`Incidente registrado: ${id}`);
57
+ console.log(`título: ${title}`);
58
+ });
59
+ }
60
+ function cmdList() {
61
+ withGraph((_graph, store) => {
62
+ const records = incidentRecords(store);
63
+ if (records.length === 0) {
64
+ console.log('Nenhum incidente registrado ainda — rode forja incident:record --title <t> primeiro.');
65
+ return;
66
+ }
67
+ for (const record of records)
68
+ console.log(`${record.createdAt} ${record.id} ${titleOf(record)}`);
69
+ });
70
+ }
71
+ function cmdSimilar(args) {
72
+ const [query] = args;
73
+ if (!query) {
74
+ console.error('Uso: forja incident:similar "<busca>"');
75
+ process.exitCode = 1;
76
+ return;
77
+ }
78
+ withGraph((_graph, store) => {
79
+ const ranked = rankIncidentsByQuery(incidentRecords(store), query);
80
+ if (ranked.length === 0) {
81
+ console.log('Nenhum incidente parecido encontrado (busca por palavra-chave, sem entendimento semântico — AC-3).');
82
+ return;
83
+ }
84
+ for (const item of ranked)
85
+ console.log(`[${item.relevance.toFixed(2)}] ${item.record.id} ${titleOf(item.record)}`);
86
+ console.log('\n(sugestão por palavra-chave, não uma alegação de causa igual — leitura, nunca aplicação automática, SPEC-041 AC-4)');
87
+ });
88
+ }
89
+ async function main() {
90
+ const [subcommand, ...rest] = process.argv.slice(2);
91
+ switch (subcommand) {
92
+ case 'record': return cmdRecord(rest);
93
+ case 'list': return cmdList();
94
+ case 'similar': return cmdSimilar(rest);
95
+ default:
96
+ console.error('Uso: forja incident:<record|list|similar> [args]');
97
+ process.exitCode = 1;
98
+ }
99
+ }
100
+ main().catch((error) => {
101
+ console.error(`\nincident: falhou: ${error instanceof Error ? error.message : String(error)}`);
102
+ process.exitCode = 1;
103
+ });
@@ -0,0 +1,160 @@
1
+ /** CLI-first LLM Fit Loop. Credentials stay in the provider CLI; Forja stores only profiles and observations. */
2
+ import fs from 'node:fs';
3
+ import path from 'node:path';
4
+ import { spawnSync } from 'node:child_process';
5
+ import Database from 'better-sqlite3';
6
+ import { createHash, randomUUID } from 'node:crypto';
7
+ import { DEFAULT_LLM_PROFILES, buildLlmExecution, recommendProfile, runLlm, validateProfiles } from "../packages/llm/src/index.js";
8
+ import { EvaluationEngine } from "../packages/evals/src/index.js";
9
+ import { ObservabilityRecorder } from "../packages/observability/src/index.js";
10
+ import { SqliteMigrationRunner, SqliteObservationStore } from "../packages/adapter-sqlite/src/index.js";
11
+ import { getWorkspaceContextDir, getWorkspaceDbDir, getWorkspaceDbPath } from "../lib/workspace.js";
12
+ import { computeCostUsd, isPriceStale, loadPricingTable, lookupPrice, STALE_PRICE_MAX_AGE_DAYS } from "../lib/core/model-pricing.js";
13
+ const profilePath = () => path.join(getWorkspaceContextDir(), 'llm-profiles.json');
14
+ function usage() {
15
+ console.error('Uso: forja llm:<doctor|profiles:init|probe|recommend|run|eval>');
16
+ process.exit(1);
17
+ }
18
+ function profiles() {
19
+ if (!fs.existsSync(profilePath()))
20
+ throw new Error(`Perfis ausentes: execute forja llm:profiles:init (${profilePath()})`);
21
+ return validateProfiles(JSON.parse(fs.readFileSync(profilePath(), 'utf8')));
22
+ }
23
+ function profile(name) {
24
+ const value = profiles().profiles[name];
25
+ if (!value)
26
+ throw new Error(`Perfil não encontrado: ${name}`);
27
+ return value;
28
+ }
29
+ function flags(args) {
30
+ const output = new Map();
31
+ for (let index = 0; index < args.length; index += 1) {
32
+ const flag = args[index];
33
+ if (!flag.startsWith('--'))
34
+ throw new Error(`Argumento inválido: ${flag}`);
35
+ const value = args[index + 1];
36
+ if (!value || value.startsWith('--'))
37
+ throw new Error(`Valor ausente para ${flag}`);
38
+ output.set(flag, [...(output.get(flag) ?? []), value]);
39
+ index += 1;
40
+ }
41
+ return output;
42
+ }
43
+ function option(input, name) { return input.get(name)?.at(-1); }
44
+ function storage() {
45
+ fs.mkdirSync(getWorkspaceDbDir(), { recursive: true });
46
+ const db = new Database(process.env.FORJA_RUNTIME_DB ?? getWorkspaceDbPath());
47
+ new SqliteMigrationRunner(db).apply();
48
+ return { db, store: new SqliteObservationStore(db) };
49
+ }
50
+ /**
51
+ * Aviso de preço (SPEC-029, AC-4 e risco "tabela desatualizada"): não bloqueia nada — `doctor()`
52
+ * segue reportando disponibilidade dos adapters como sempre. `pricing.missing`/`pricing.stale` são
53
+ * só o ponto onde um humano descobre "atualize lib/core/model-pricing.json" antes que o gap vire
54
+ * surpresa na fatura, sem que a checagem de disponibilidade dependa de ter preço conhecido.
55
+ */
56
+ function pricingInfo(model) {
57
+ const price = lookupPrice(loadPricingTable(), model);
58
+ if (price === undefined)
59
+ return { known: false };
60
+ return { known: true, asOf: price.asOf, stale: isPriceStale(price) };
61
+ }
62
+ function doctor(name) {
63
+ const configured = profiles().profiles;
64
+ if (name && !configured[name])
65
+ throw new Error(`Perfil não encontrado: ${name}`);
66
+ const result = Object.entries(configured).filter(([profileName]) => name === undefined || profileName === name).map(([profileName, value]) => {
67
+ const probe = spawnSync(value.command, ['--version'], { encoding: 'utf8', timeout: 10_000, shell: false });
68
+ const errorCode = probe.error?.code;
69
+ const model = `${value.provider}:${value.model}`;
70
+ const pricing = pricingInfo(model);
71
+ return { name: profileName, provider: value.provider, model: value.model, enabled: value.enabled, executable: value.command, available: !probe.error && probe.status === 0, detail: errorCode ?? (probe.status === 0 ? String(probe.stdout).trim().split('\n')[0] : String(probe.stderr).trim().split('\n')[0]), pricing };
72
+ });
73
+ console.log(JSON.stringify({ profiles: result }, null, 2));
74
+ for (const item of result) {
75
+ if (!item.pricing.known)
76
+ console.warn(`Aviso: sem preço local para ${item.provider}:${item.model} (lib/core/model-pricing.json) — custo dessas execuções não é computado. Adicione uma entrada quando souber o preço real.`);
77
+ else if (item.pricing.stale)
78
+ console.warn(`Aviso: preço de ${item.provider}:${item.model} não é revisado desde ${item.pricing.asOf} (> ${STALE_PRICE_MAX_AGE_DAYS} dias) — confira se ainda reflete o preço real do provider.`);
79
+ }
80
+ if (result.some((item) => item.enabled && !item.available))
81
+ process.exitCode = 1;
82
+ }
83
+ async function run() {
84
+ const input = flags(process.argv.slice(3));
85
+ const name = option(input, '--profile');
86
+ const prompt = option(input, '--prompt') ?? (option(input, '--task') ? fs.readFileSync(path.resolve(option(input, '--task')), 'utf8') : undefined);
87
+ if (!name || !prompt)
88
+ usage();
89
+ const selected = profile(name);
90
+ const result = await runLlm(buildLlmExecution(selected, prompt), process.cwd());
91
+ const { db, store } = storage();
92
+ try {
93
+ const recorder = new ObservabilityRecorder(store);
94
+ const refs = (input.get('--context') ?? []).map((value) => path.resolve(value));
95
+ const model = `${selected.provider}:${selected.model}`;
96
+ const inputTokens = Math.ceil(Buffer.byteLength(prompt) / 4);
97
+ const outputTokens = Math.ceil(Buffer.byteLength(result.stdout) / 4);
98
+ // AC-6/AC-4 (SPEC-029): custo real quando a tabela local conhece o preço; fail-open (undefined,
99
+ // não bloqueia, apenas avisa) quando não conhece — mesma tabela usada por `checkLimits`/AC-2.
100
+ const costUsd = computeCostUsd(loadPricingTable(), model, inputTokens, outputTokens);
101
+ if (costUsd === undefined)
102
+ console.warn(`Aviso: preço desconhecido para ${model} — custo desta execução não computado. Rode \`forja llm:doctor\` ou adicione uma entrada em lib/core/model-pricing.json.`);
103
+ const observation = await recorder.record({ traceId: `llm:${name}:${randomUUID()}`, model, inputHash: createHash('sha256').update(prompt).digest('hex'), contextRefs: refs, inputTokens, outputTokens, durationMs: result.durationMs, cost: costUsd, tools: [selected.command], commands: [selected.command], outcome: result.exitCode === 0 ? 'succeeded' : 'failed', errorCode: result.errorCode });
104
+ console.log(JSON.stringify({ profile: name, model: observation.model, exitCode: result.exitCode, durationMs: result.durationMs, costUsd: observation.cost, observationId: observation.id, stdout: result.stdout, stderr: result.stderr }, null, 2));
105
+ if (result.exitCode !== 0)
106
+ process.exitCode = result.exitCode;
107
+ }
108
+ finally {
109
+ db.close();
110
+ }
111
+ }
112
+ function recommend() {
113
+ const input = flags(process.argv.slice(3));
114
+ const role = option(input, '--role');
115
+ const task = option(input, '--task');
116
+ if (!role || !task)
117
+ usage();
118
+ const { db, store } = storage();
119
+ try {
120
+ console.log(JSON.stringify({ role, task, recommendations: recommendProfile(profiles(), store.list(), role, task, option(input, '--privacy')) }, null, 2));
121
+ }
122
+ finally {
123
+ db.close();
124
+ }
125
+ }
126
+ async function evaluate() {
127
+ const input = flags(process.argv.slice(3));
128
+ const scope = option(input, '--scope') ?? 'workspace';
129
+ const scopeId = option(input, '--id');
130
+ if (!['workspace', 'model', 'agent', 'task', 'sprint', 'run', 'capability', 'strategy'].includes(scope))
131
+ throw new Error(`Escopo inválido: ${scope}`);
132
+ const { db, store } = storage();
133
+ try {
134
+ console.log(JSON.stringify(await new EvaluationEngine(store).evaluate({ scope: scope, scopeId }), null, 2));
135
+ }
136
+ finally {
137
+ db.close();
138
+ }
139
+ }
140
+ async function main() {
141
+ const command = process.argv[2];
142
+ if (command === 'profiles:init') {
143
+ fs.mkdirSync(path.dirname(profilePath()), { recursive: true });
144
+ if (fs.existsSync(profilePath()) && !process.argv.includes('--force'))
145
+ throw new Error(`Perfis já existem: ${profilePath()} (use --force para substituir)`);
146
+ fs.writeFileSync(profilePath(), `${JSON.stringify(DEFAULT_LLM_PROFILES, null, 2)}\n`);
147
+ console.log(`Perfis LLM criados: ${profilePath()}`);
148
+ }
149
+ else if (command === 'doctor' || command === 'probe')
150
+ doctor(process.argv[3]);
151
+ else if (command === 'recommend')
152
+ recommend();
153
+ else if (command === 'run')
154
+ await run();
155
+ else if (command === 'eval')
156
+ await evaluate();
157
+ else
158
+ usage();
159
+ }
160
+ main().catch((error) => { console.error(error instanceof Error ? error.message : String(error)); process.exit(1); });
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * provenance:record / blame / sbom (SPEC-039)
4
+ *
5
+ * forja provenance:record <run-id> extrai proveniência de um RuntimeRun já persistido e grava
6
+ * forja blame <file> histórico de proveniência de um arquivo, mais recente primeiro
7
+ * forja sbom [--json] relatório agregado por agente
8
+ *
9
+ * `packages/engineering/provenance` faz o mapeamento puro (`extractProvenance`); este script busca
10
+ * o `RuntimeRun` real (`SqliteRuntimeRunStore`, já existente) e persiste via `SqliteProvenanceStore`
11
+ * (reaproveita `SqliteJsonRepository`, sem migration nova). Granularidade é arquivo, não linha —
12
+ * ver AC-2 da spec: nenhuma fonte de dado real deste repositório rastreia hunks de linha por run.
13
+ */
14
+ export {};
@@ -0,0 +1,114 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * provenance:record / blame / sbom (SPEC-039)
4
+ *
5
+ * forja provenance:record <run-id> extrai proveniência de um RuntimeRun já persistido e grava
6
+ * forja blame <file> histórico de proveniência de um arquivo, mais recente primeiro
7
+ * forja sbom [--json] relatório agregado por agente
8
+ *
9
+ * `packages/engineering/provenance` faz o mapeamento puro (`extractProvenance`); este script busca
10
+ * o `RuntimeRun` real (`SqliteRuntimeRunStore`, já existente) e persiste via `SqliteProvenanceStore`
11
+ * (reaproveita `SqliteJsonRepository`, sem migration nova). Granularidade é arquivo, não linha —
12
+ * ver AC-2 da spec: nenhuma fonte de dado real deste repositório rastreia hunks de linha por run.
13
+ */
14
+ import fs from 'node:fs';
15
+ import Database from 'better-sqlite3';
16
+ import { extractProvenance } from "../packages/engineering/provenance/src/index.js";
17
+ import { SqliteMigrationRunner, SqliteProvenanceStore, SqliteRuntimeRunStore } from "../packages/adapter-sqlite/src/index.js";
18
+ import { getWorkspaceDbDir, getWorkspaceDbPath } from "../lib/workspace.js";
19
+ function openDatabase() {
20
+ fs.mkdirSync(getWorkspaceDbDir(), { recursive: true });
21
+ const database = new Database(process.env.FORJA_RUNTIME_DB ?? getWorkspaceDbPath());
22
+ new SqliteMigrationRunner(database).apply();
23
+ return database;
24
+ }
25
+ function cmdRecord([runId]) {
26
+ if (!runId) {
27
+ console.error('Uso: forja provenance:record <run-id>');
28
+ process.exitCode = 1;
29
+ return;
30
+ }
31
+ const database = openDatabase();
32
+ try {
33
+ const run = new SqliteRuntimeRunStore(database).get(runId);
34
+ if (run === undefined) {
35
+ console.error(`Run não encontrado: ${runId}.`);
36
+ process.exitCode = 1;
37
+ return;
38
+ }
39
+ const records = extractProvenance(run);
40
+ const store = new SqliteProvenanceStore(database);
41
+ for (const record of records)
42
+ store.save(record);
43
+ console.log(`${records.length} registro(s) de proveniência gravado(s) para ${runId} (${records.map((r) => r.file).join(', ') || '(nenhum arquivo alterado)'})`);
44
+ }
45
+ finally {
46
+ database.close();
47
+ }
48
+ }
49
+ function cmdBlame([file]) {
50
+ if (!file) {
51
+ console.error('Uso: forja blame <file>');
52
+ process.exitCode = 1;
53
+ return;
54
+ }
55
+ const database = openDatabase();
56
+ try {
57
+ const records = new SqliteProvenanceStore(database).list().filter((record) => record.file === file).sort((left, right) => right.recordedAt.localeCompare(left.recordedAt));
58
+ if (records.length === 0) {
59
+ console.log(`Nenhum registro de proveniência para ${file} ainda (granularidade de arquivo, não linha — rode forja provenance:record <run-id> primeiro).`);
60
+ return;
61
+ }
62
+ for (const record of records)
63
+ console.log(`${record.recordedAt} ${record.agentName} (${record.agentId}) run:${record.runId}`);
64
+ }
65
+ finally {
66
+ database.close();
67
+ }
68
+ }
69
+ function cmdSbom(args) {
70
+ const json = args.includes('--json');
71
+ const database = openDatabase();
72
+ try {
73
+ const records = new SqliteProvenanceStore(database).list();
74
+ const byAgent = new Map();
75
+ for (const record of records) {
76
+ const entry = byAgent.get(record.agentId) ?? { agentId: record.agentId, agentName: record.agentName, files: new Set() };
77
+ entry.files.add(record.file);
78
+ byAgent.set(record.agentId, entry);
79
+ }
80
+ const report = [...byAgent.values()].map((entry) => ({ agentId: entry.agentId, agentName: entry.agentName, fileCount: entry.files.size, files: [...entry.files].sort() })).sort((left, right) => right.fileCount - left.fileCount);
81
+ if (json) {
82
+ console.log(JSON.stringify({ totalRecords: records.length, byAgent: report }, null, 2));
83
+ return;
84
+ }
85
+ if (report.length === 0) {
86
+ console.log('Nenhum registro de proveniência ainda — rode forja provenance:record <run-id> primeiro.');
87
+ return;
88
+ }
89
+ console.log(`AI-SBOM — ${records.length} registro(s) de proveniência, ${report.length} agente(s)\n`);
90
+ for (const entry of report) {
91
+ console.log(`${entry.agentName} (${entry.agentId}) — ${entry.fileCount} arquivo(s)`);
92
+ for (const file of entry.files)
93
+ console.log(` ${file}`);
94
+ }
95
+ }
96
+ finally {
97
+ database.close();
98
+ }
99
+ }
100
+ async function main() {
101
+ const [subcommand, ...rest] = process.argv.slice(2);
102
+ switch (subcommand) {
103
+ case 'record': return cmdRecord(rest);
104
+ case 'blame': return cmdBlame(rest);
105
+ case 'sbom': return cmdSbom(rest);
106
+ default:
107
+ console.error('Uso: forja provenance:record <run-id> | forja blame <file> | forja sbom [--json]');
108
+ process.exitCode = 1;
109
+ }
110
+ }
111
+ main().catch((error) => {
112
+ console.error(`\nprovenance: falhou: ${error instanceof Error ? error.message : String(error)}`);
113
+ process.exitCode = 1;
114
+ });
@@ -0,0 +1,15 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * risk:assess / risk:explain (SPEC-034)
4
+ *
5
+ * forja risk:assess [ref] score de risco 0-100 sobre o diff de <ref> (default: working tree vs HEAD)
6
+ * forja risk:explain <id> reexibe um assessment já calculado, com todos os fatores
7
+ *
8
+ * `packages/engineering/risk` faz o cálculo puro (7 fatores, pesos configuráveis, D1-D4 do plan);
9
+ * `lib/core/risk-collect.ts` coleta os números reais (grafo, constitution, histórico) — reaproveitado
10
+ * também por `scripts/engineer.ts` (SPEC-035), daí viver em `lib/core` e não aqui. Este script só
11
+ * cuida do ciclo de vida do assessment em si: diff via git, persistência efêmera
12
+ * (`.context/risk/<id>.json`, mesma categoria de `.context/forja-runs.jsonl` — fora do git, D2 do
13
+ * plan de SPEC-034), e a CLI.
14
+ */
15
+ export {};
@@ -0,0 +1,81 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * risk:assess / risk:explain (SPEC-034)
4
+ *
5
+ * forja risk:assess [ref] score de risco 0-100 sobre o diff de <ref> (default: working tree vs HEAD)
6
+ * forja risk:explain <id> reexibe um assessment já calculado, com todos os fatores
7
+ *
8
+ * `packages/engineering/risk` faz o cálculo puro (7 fatores, pesos configuráveis, D1-D4 do plan);
9
+ * `lib/core/risk-collect.ts` coleta os números reais (grafo, constitution, histórico) — reaproveitado
10
+ * também por `scripts/engineer.ts` (SPEC-035), daí viver em `lib/core` e não aqui. Este script só
11
+ * cuida do ciclo de vida do assessment em si: diff via git, persistência efêmera
12
+ * (`.context/risk/<id>.json`, mesma categoria de `.context/forja-runs.jsonl` — fora do git, D2 do
13
+ * plan de SPEC-034), e a CLI.
14
+ */
15
+ import fs from 'node:fs';
16
+ import path from 'node:path';
17
+ import { randomUUID } from 'node:crypto';
18
+ import Database from 'better-sqlite3';
19
+ import { assessRisk, explainAssessment } from "../packages/engineering/risk/src/index.js";
20
+ import { SqliteMigrationRunner } from "../packages/adapter-sqlite/src/index.js";
21
+ import { getWorkspaceDbDir, getWorkspaceDbPath } from "../lib/workspace.js";
22
+ import { buildRiskInput, changedFiles, graphRoot } from "../lib/core/risk-collect.js";
23
+ const RISK_DIR = '.context/risk';
24
+ function assessmentPath(id) {
25
+ return path.join(graphRoot(), RISK_DIR, `${id}.json`);
26
+ }
27
+ function saveAssessment(assessment) {
28
+ fs.mkdirSync(path.join(graphRoot(), RISK_DIR), { recursive: true });
29
+ fs.writeFileSync(assessmentPath(assessment.id), `${JSON.stringify(assessment, null, 2)}\n`);
30
+ }
31
+ async function cmdAssess([ref]) {
32
+ const paths = changedFiles(ref);
33
+ if (paths.length === 0) {
34
+ console.log('Nenhum arquivo alterado — nada para avaliar (compare contra HEAD, ou passe um ref de commit).');
35
+ return;
36
+ }
37
+ fs.mkdirSync(getWorkspaceDbDir(), { recursive: true });
38
+ const database = new Database(process.env.FORJA_RUNTIME_DB ?? getWorkspaceDbPath());
39
+ new SqliteMigrationRunner(database).apply();
40
+ let input;
41
+ try {
42
+ input = await buildRiskInput(paths, database);
43
+ }
44
+ finally {
45
+ database.close();
46
+ }
47
+ const id = randomUUID();
48
+ const assessment = assessRisk(input, { id, changeId: ref ?? 'working-tree', now: new Date().toISOString() });
49
+ saveAssessment(assessment);
50
+ console.log(explainAssessment(assessment));
51
+ console.log(`\n${paths.length} arquivo(s) avaliado(s). Assessment salvo — forja risk:explain ${id}`);
52
+ }
53
+ function cmdExplain([id]) {
54
+ if (!id) {
55
+ console.error('Uso: forja risk:explain <assessment-id>');
56
+ process.exitCode = 1;
57
+ return;
58
+ }
59
+ const file = assessmentPath(id);
60
+ if (!fs.existsSync(file)) {
61
+ console.error(`Assessment não encontrado: ${id}. Rode forja risk:assess primeiro.`);
62
+ process.exitCode = 1;
63
+ return;
64
+ }
65
+ const assessment = JSON.parse(fs.readFileSync(file, 'utf8'));
66
+ console.log(explainAssessment(assessment));
67
+ }
68
+ async function main() {
69
+ const [subcommand, ...rest] = process.argv.slice(2);
70
+ switch (subcommand) {
71
+ case 'assess': return cmdAssess(rest);
72
+ case 'explain': return cmdExplain(rest);
73
+ default:
74
+ console.error('Uso: forja risk:<assess|explain> [args]');
75
+ process.exitCode = 1;
76
+ }
77
+ }
78
+ main().catch((error) => {
79
+ console.error(`\nrisk: falhou: ${error instanceof Error ? error.message : String(error)}`);
80
+ process.exitCode = 1;
81
+ });
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * simulate (SPEC-038) — Predictive Change Simulation.
4
+ *
5
+ * forja simulate <ref> [--command "npm test"] [--json]
6
+ *
7
+ * Composição pura de engines já existentes (gap analysis §3 do doc de arquitetura): `SandboxEngine`
8
+ * + `GitWorktreeBackend` (isolamento real, packages/sandbox+adapter-git) para checar out `<ref>`
9
+ * num worktree isolado e rodar o comando de teste; `checkConstitution` (SPEC-033) + `assessRisk`
10
+ * (SPEC-034, via `lib/core/risk-collect.ts`) para avaliar o estado resultante. Nada disso é lógica
11
+ * nova — só orquestração.
12
+ *
13
+ * Ciclo do sandbox (D1 do plan): create→prepare→execute→reject→destroy. `promote()` **nunca** é
14
+ * chamado neste arquivo — a única escrita na árvore real é a remoção do próprio worktree (AC-3).
15
+ *
16
+ * Grafo/SQLite da simulação são temporários (`mkdtemp`, D3 do plan) — nunca `getWorkspaceDbPath()`,
17
+ * pra não contaminar o Engineering Graph persistente com o estado de um ref que pode nunca ser
18
+ * integrado (AC-2).
19
+ */
20
+ export {};
@@ -0,0 +1,150 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * simulate (SPEC-038) — Predictive Change Simulation.
4
+ *
5
+ * forja simulate <ref> [--command "npm test"] [--json]
6
+ *
7
+ * Composição pura de engines já existentes (gap analysis §3 do doc de arquitetura): `SandboxEngine`
8
+ * + `GitWorktreeBackend` (isolamento real, packages/sandbox+adapter-git) para checar out `<ref>`
9
+ * num worktree isolado e rodar o comando de teste; `checkConstitution` (SPEC-033) + `assessRisk`
10
+ * (SPEC-034, via `lib/core/risk-collect.ts`) para avaliar o estado resultante. Nada disso é lógica
11
+ * nova — só orquestração.
12
+ *
13
+ * Ciclo do sandbox (D1 do plan): create→prepare→execute→reject→destroy. `promote()` **nunca** é
14
+ * chamado neste arquivo — a única escrita na árvore real é a remoção do próprio worktree (AC-3).
15
+ *
16
+ * Grafo/SQLite da simulação são temporários (`mkdtemp`, D3 do plan) — nunca `getWorkspaceDbPath()`,
17
+ * pra não contaminar o Engineering Graph persistente com o estado de um ref que pode nunca ser
18
+ * integrado (AC-2).
19
+ */
20
+ import fs from 'node:fs';
21
+ import os from 'node:os';
22
+ import path from 'node:path';
23
+ import { randomUUID } from 'node:crypto';
24
+ import Database from 'better-sqlite3';
25
+ import { checkConstitution } from "../packages/engineering/architecture/src/index.js";
26
+ import { assessRisk } from "../packages/engineering/risk/src/index.js";
27
+ import { SandboxEngine, InMemorySandboxStore } from "../packages/sandbox/src/index.js";
28
+ import { GitWorktreeBackend, SpawnCommandRunner } from "../packages/adapter-git/src/index.js";
29
+ import { GitGraphDocumentSource } from "../packages/adapter-git/src/index.js";
30
+ import { GraphIndexer, GraphLoop } from "../packages/graph/src/index.js";
31
+ import { SqliteGraphStore, SqliteMigrationRunner } from "../packages/adapter-sqlite/src/index.js";
32
+ import { buildRiskInput, changedFiles } from "../lib/core/risk-collect.js";
33
+ const CONSTITUTION_PATH = '.context/architecture/constitution.json';
34
+ function repoRoot() {
35
+ return process.env.FORJA_GRAPH_ROOT ?? process.cwd();
36
+ }
37
+ /** Roda `buildRiskInput`/`checkConstitution` contra `worktreeRoot`, isolado do workspace real (D3). */
38
+ async function assessWorktree(worktreeRoot, paths) {
39
+ const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-db-'));
40
+ const database = new Database(path.join(tempBase, 'simulate.db'));
41
+ new SqliteMigrationRunner(database).apply();
42
+ const previousGraphRoot = process.env.FORJA_GRAPH_ROOT;
43
+ try {
44
+ process.env.FORJA_GRAPH_ROOT = worktreeRoot;
45
+ const store = new SqliteGraphStore(database);
46
+ const graph = new GraphLoop(store);
47
+ await new GraphIndexer(graph).sync(new GitGraphDocumentSource(worktreeRoot, new SpawnCommandRunner()));
48
+ let architectureCheck;
49
+ const constitutionFile = path.join(worktreeRoot, CONSTITUTION_PATH);
50
+ if (fs.existsSync(constitutionFile)) {
51
+ const { rules } = JSON.parse(fs.readFileSync(constitutionFile, 'utf8'));
52
+ const edges = store.listEdges().flatMap((edge) => {
53
+ if (edge.type !== 'DEPENDS_ON')
54
+ return [];
55
+ const fromNode = store.getNode(edge.from);
56
+ const toNode = store.getNode(edge.to);
57
+ return fromNode === undefined || toNode === undefined ? [] : [{ fromPath: fromNode.label, targetLabel: toNode.label }];
58
+ });
59
+ architectureCheck = checkConstitution(rules, edges);
60
+ }
61
+ else {
62
+ architectureCheck = { note: 'Constitution não compilada no ref simulado.' };
63
+ }
64
+ const riskInput = await buildRiskInput(paths, database);
65
+ const risk = assessRisk(riskInput, { id: randomUUID(), changeId: 'simulation', now: new Date().toISOString() });
66
+ return { architectureCheck, risk };
67
+ }
68
+ finally {
69
+ process.env.FORJA_GRAPH_ROOT = previousGraphRoot;
70
+ database.close();
71
+ fs.rmSync(tempBase, { recursive: true, force: true });
72
+ }
73
+ }
74
+ function recommendationFor(testPassed, architectureCheck, risk) {
75
+ if (!testPassed)
76
+ return 'discard';
77
+ const hasViolation = 'violations' in architectureCheck && architectureCheck.violations.length > 0;
78
+ if (hasViolation)
79
+ return 'review';
80
+ if (risk.autonomyBand === 'supervised' || risk.autonomyBand === 'human_in_the_loop')
81
+ return 'review';
82
+ return 'promote';
83
+ }
84
+ async function cmdSimulate(args) {
85
+ const json = args.includes('--json');
86
+ const commandIndex = args.indexOf('--command');
87
+ const testCommand = commandIndex === -1 ? 'npm test' : args[commandIndex + 1];
88
+ const ref = args.filter((arg, index) => arg !== '--json' && (commandIndex === -1 || (index !== commandIndex && index !== commandIndex + 1)))[0];
89
+ if (!ref) {
90
+ console.error('Uso: forja simulate <ref> [--command "npm test"] [--json]');
91
+ process.exitCode = 1;
92
+ return;
93
+ }
94
+ const paths = changedFiles(ref);
95
+ const runner = new SpawnCommandRunner();
96
+ const patchApplier = { apply: () => { throw new Error('simulate nunca promove — patchApplier.apply não deveria ser chamado'); }, revert: () => { } };
97
+ const sandbox = new SandboxEngine(new InMemorySandboxStore(), new GitWorktreeBackend(runner, { repositoryRoot: repoRoot(), sourceRef: ref, patchApplier }));
98
+ const tempBase = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-simulate-'));
99
+ const worktreeRoot = path.join(tempBase, 'worktree');
100
+ const runId = randomUUID();
101
+ const session = await sandbox.create({ runId, root: worktreeRoot });
102
+ try {
103
+ await sandbox.prepare(session.id);
104
+ const [executable, ...cmdArgs] = testCommand.split(' ');
105
+ const execution = await sandbox.execute(session.id, { executable, args: cmdArgs, cwd: worktreeRoot });
106
+ const testResult = { exitCode: execution.exitCode, durationMs: execution.durationMs, passed: execution.exitCode === 0 };
107
+ const { architectureCheck, risk } = await assessWorktree(worktreeRoot, paths);
108
+ const recommendation = recommendationFor(testResult.passed, architectureCheck, risk);
109
+ const report = { ref, changedFiles: paths, testCommand, testResult, architectureCheck, risk, recommendation };
110
+ if (json)
111
+ console.log(JSON.stringify(report, null, 2));
112
+ else
113
+ printText(report);
114
+ }
115
+ finally {
116
+ // best-effort — reject() pode já ter deixado a sessão num estado terminal se execute() lançou,
117
+ // e destroy() pode achar o worktree já removido pelo reject(); nenhum dos dois é fatal aqui. O
118
+ // erro é logado (não silenciado) porque uma falha real de cleanup deixaria um worktree/branch
119
+ // órfão na árvore real — algo que vale saber, mesmo sem abortar a simulação por causa disso.
120
+ await sandbox.reject(session.id).catch((error) => { console.error(`simulate: aviso — reject do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
121
+ await sandbox.destroy(session.id).catch((error) => { console.error(`simulate: aviso — destroy do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
122
+ fs.rmSync(tempBase, { recursive: true, force: true });
123
+ }
124
+ }
125
+ function printText(report) {
126
+ console.log(`simulate ${report.ref}`);
127
+ console.log(`${report.changedFiles.length} arquivo(s) alterado(s)`);
128
+ console.log('');
129
+ console.log(`teste (${report.testCommand}): ${report.testResult.passed ? 'PASSOU' : 'FALHOU'} (exit ${report.testResult.exitCode}, ${report.testResult.durationMs}ms)`);
130
+ console.log('');
131
+ console.log('ARCHITECTURE CHECK');
132
+ if ('note' in report.architectureCheck)
133
+ console.log(` ${report.architectureCheck.note}`);
134
+ else {
135
+ console.log(` ${report.architectureCheck.compliant} regra(s) active em conformidade, ${report.architectureCheck.violations.length} violação(ões)`);
136
+ for (const violation of report.architectureCheck.violations)
137
+ console.log(` ${violation.severity.toUpperCase()} ${violation.file} viola ${violation.ruleId}`);
138
+ }
139
+ console.log('');
140
+ console.log(`RISCO: score ${report.risk.score}/100 → ${report.risk.autonomyBand} (confidence ${(report.risk.confidence * 100).toFixed(0)}%)`);
141
+ console.log('');
142
+ console.log(`RECOMENDAÇÃO: ${report.recommendation.toUpperCase()} — informação, não decisão automática (nenhuma mudança foi aplicada à árvore real)`);
143
+ }
144
+ async function main() {
145
+ await cmdSimulate(process.argv.slice(2));
146
+ }
147
+ main().catch((error) => {
148
+ console.error(`\nsimulate: falhou: ${error instanceof Error ? error.message : String(error)}`);
149
+ process.exitCode = 1;
150
+ });