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.
- package/.claude/agents/release-auditor.md +19 -10
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +80 -0
- package/DOC-MAP.md +9 -0
- package/README.md +85 -5
- package/README.pt-BR.md +34 -5
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
- package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
- package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
- package/dist/apps/server/src/forja-nest.module.js +9 -4
- package/dist/apps/server/src/main.js +10 -1
- package/dist/bin/forja.js +14 -2
- package/dist/lib/code-context.js +6 -0
- package/dist/lib/core/architecture-gate.d.ts +20 -0
- package/dist/lib/core/architecture-gate.js +60 -0
- package/dist/lib/core/doc-graph.js +6 -4
- package/dist/lib/core/drift-gate.d.ts +18 -0
- package/dist/lib/core/drift-gate.js +55 -0
- package/dist/lib/core/gates.d.ts +9 -2
- package/dist/lib/core/gates.js +13 -2
- package/dist/lib/core/health.js +15 -0
- package/dist/lib/core/incident-search.d.ts +19 -0
- package/dist/lib/core/incident-search.js +32 -0
- package/dist/lib/core/model-pricing.d.ts +31 -0
- package/dist/lib/core/model-pricing.js +74 -0
- package/dist/lib/core/registry.d.ts +248 -0
- package/dist/lib/core/registry.js +249 -0
- package/dist/lib/core/release.d.ts +247 -0
- package/dist/lib/core/release.js +5 -1
- package/dist/lib/core/risk-collect.d.ts +19 -0
- package/dist/lib/core/risk-collect.js +173 -0
- package/dist/lib/drift-sentinel.d.ts +59 -0
- package/dist/lib/drift-sentinel.js +126 -0
- package/dist/lib/generators/memory-generator.js +8 -6
- package/dist/lib/generators/nest-generator.js +24 -10
- package/dist/lib/project-upgrade.js +1 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +34 -5
- package/dist/packages/adapter-git/src/index.d.ts +1 -1
- package/dist/packages/adapter-git/src/index.js +11 -6
- package/dist/packages/adapter-nest/src/index.d.ts +19 -0
- package/dist/packages/adapter-nest/src/index.js +26 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
- package/dist/packages/adapter-sqlite/src/index.js +49 -0
- package/dist/packages/contracts/src/index.d.ts +33 -0
- package/dist/packages/contracts/src/index.js +13 -0
- package/dist/packages/core/src/index.d.ts +12 -0
- package/dist/packages/core/src/index.js +29 -0
- package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
- package/dist/packages/engineering/architecture/src/index.js +131 -0
- package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
- package/dist/packages/engineering/evidence/src/index.js +31 -0
- package/dist/packages/engineering/identity/src/index.d.ts +57 -0
- package/dist/packages/engineering/identity/src/index.js +88 -0
- package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
- package/dist/packages/engineering/monitoring/src/index.js +40 -0
- package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
- package/dist/packages/engineering/provenance/src/index.js +21 -0
- package/dist/packages/engineering/risk/src/index.d.ts +89 -0
- package/dist/packages/engineering/risk/src/index.js +120 -0
- package/dist/packages/graph/src/index.d.ts +23 -1
- package/dist/packages/graph/src/index.js +88 -15
- package/dist/packages/llm/src/index.d.ts +43 -0
- package/dist/packages/llm/src/index.js +131 -0
- package/dist/packages/mcp/src/index.js +27 -8
- package/dist/packages/orchestration/src/index.d.ts +11 -1
- package/dist/packages/orchestration/src/index.js +34 -7
- package/dist/packages/policy/src/index.d.ts +40 -0
- package/dist/packages/policy/src/index.js +39 -4
- package/dist/packages/runtime/src/index.js +3 -0
- package/dist/packages/sandbox/src/index.d.ts +47 -0
- package/dist/packages/sandbox/src/index.js +59 -0
- package/dist/packages/validator/src/index.d.ts +8 -0
- package/dist/packages/validator/src/index.js +21 -6
- package/dist/scripts/adr.d.ts +17 -0
- package/dist/scripts/adr.js +152 -0
- package/dist/scripts/agent-harness.js +14 -4
- package/dist/scripts/agent.d.ts +27 -0
- package/dist/scripts/agent.js +249 -0
- package/dist/scripts/architecture.d.ts +16 -0
- package/dist/scripts/architecture.js +186 -0
- package/dist/scripts/cost-economy.d.ts +2 -0
- package/dist/scripts/cost-economy.js +79 -0
- package/dist/scripts/demo-autonomy.js +15 -8
- package/dist/scripts/demo-workspace.d.ts +6 -0
- package/dist/scripts/demo-workspace.js +101 -0
- package/dist/scripts/drift-check.d.ts +17 -0
- package/dist/scripts/drift-check.js +63 -0
- package/dist/scripts/engineer.d.ts +20 -0
- package/dist/scripts/engineer.js +208 -0
- package/dist/scripts/evidence.d.ts +12 -0
- package/dist/scripts/evidence.js +55 -0
- package/dist/scripts/gates.d.ts +6 -2
- package/dist/scripts/gates.js +14 -4
- package/dist/scripts/incident.d.ts +19 -0
- package/dist/scripts/incident.js +103 -0
- package/dist/scripts/llm-fit.js +160 -0
- package/dist/scripts/provenance.d.ts +14 -0
- package/dist/scripts/provenance.js +114 -0
- package/dist/scripts/risk.d.ts +15 -0
- package/dist/scripts/risk.js +81 -0
- package/dist/scripts/simulate.d.ts +20 -0
- package/dist/scripts/simulate.js +150 -0
- package/dist/scripts/sync-universal-memory.js +19 -6
- package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
- package/docs/llm-fit-loop.md +41 -0
- package/docs/modos-de-operacao.md +52 -0
- package/docs/produto/factsheet-marketing.md +151 -0
- package/docs/produto/roteiro-demo.md +47 -0
- package/memory/40-delivery/current-sprint.md +3 -6
- package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
- package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
- package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
- package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
- package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
- package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
- package/package.json +9 -2
- package/specs/agent-identity-reputation/plan.md +133 -0
- package/specs/agent-identity-reputation/spec.md +125 -0
- package/specs/agent-identity-reputation/tasks.md +51 -0
- package/specs/agent-runtime-monitoring/plan.md +78 -0
- package/specs/agent-runtime-monitoring/spec.md +92 -0
- package/specs/agent-runtime-monitoring/tasks.md +39 -0
- package/specs/ai-code-provenance/plan.md +71 -0
- package/specs/ai-code-provenance/spec.md +97 -0
- package/specs/ai-code-provenance/tasks.md +39 -0
- package/specs/architecture-constitution/plan.md +110 -0
- package/specs/architecture-constitution/spec.md +114 -0
- package/specs/architecture-constitution/tasks.md +58 -0
- package/specs/change-risk-engine/plan.md +130 -0
- package/specs/change-risk-engine/spec.md +119 -0
- package/specs/change-risk-engine/tasks.md +72 -0
- package/specs/cost-aware-autonomy-budget/spec.md +102 -0
- package/specs/drift-sentinel/spec.md +117 -0
- package/specs/engineer-facade-extension/plan.md +71 -0
- package/specs/engineer-facade-extension/spec.md +98 -0
- package/specs/engineer-facade-extension/tasks.md +36 -0
- package/specs/engineering-evidence-ledger/plan.md +121 -0
- package/specs/engineering-evidence-ledger/spec.md +90 -0
- package/specs/engineering-evidence-ledger/tasks.md +54 -0
- package/specs/engineering-graph-extensions/plan.md +92 -0
- package/specs/engineering-graph-extensions/spec.md +101 -0
- package/specs/engineering-graph-extensions/tasks.md +60 -0
- package/specs/engineering-intelligence/spec.md +177 -0
- package/specs/learning-loop-incidents/plan.md +59 -0
- package/specs/learning-loop-incidents/spec.md +93 -0
- package/specs/learning-loop-incidents/tasks.md +36 -0
- package/specs/predictive-change-simulation/plan.md +109 -0
- package/specs/predictive-change-simulation/spec.md +107 -0
- package/specs/predictive-change-simulation/tasks.md +41 -0
- package/specs/release-auditor-health/plan.md +88 -0
- package/specs/release-auditor-health/spec.md +82 -0
- package/specs/release-auditor-health/tasks.md +72 -0
- package/specs/smart-agent-routing/plan.md +55 -0
- package/specs/smart-agent-routing/spec.md +85 -0
- package/specs/smart-agent-routing/tasks.md +26 -0
- package/dist/scripts/server-persistence-probe.d.ts +0 -1
- package/dist/scripts/server-persistence-probe.js +0 -52
- package/dist/scripts/server-persistence-probe.mjs +0 -52
- /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
|
@@ -1,29 +1,37 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: release-auditor
|
|
3
|
-
description: Use ANTES de publicar no npm.
|
|
3
|
+
description: Use ANTES de publicar no npm. Valida a saúde canônica com `tools:doctor`, roda `release:check --publish` e interpreta os dois resultados antes de dar o parecer.
|
|
4
4
|
tools: Read, Bash, Grep
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
Você é o **Release Auditor**. O Forja é publicado como `forjajs` no npm. Seu trabalho é responder a
|
|
8
|
-
|
|
8
|
+
duas perguntas com evidência: **o núcleo está saudável e o pacote funciona na máquina de quem
|
|
9
|
+
instala?**
|
|
9
10
|
|
|
10
11
|
O repositório mente sobre isso. No repo tudo resolve: `node_modules` existe com devDeps, todos os
|
|
11
12
|
arquivos estão presentes, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Essa
|
|
12
13
|
fronteira já cedeu três vezes — `better-sqlite3` como devDependency (ADR-0021), `otplib`/`qrcode`
|
|
13
14
|
publicados sem existirem no git (v1.1.1), `dashboard/` fora do `files[]` (v1.1.3).
|
|
14
15
|
|
|
15
|
-
**O procedimento virou código.**
|
|
16
|
-
`lib/core/release.
|
|
17
|
-
|
|
16
|
+
**O procedimento virou código.** A saúde vive em `lib/core/health.ts` (ADR-0023) e a prova do
|
|
17
|
+
tarball em `lib/core/release.ts` (ADR-0024). Código não esquece um passo; você esquece. Seu papel é
|
|
18
|
+
executar os gates que apresentam essas fontes e julgá-los, nunca reimplementar seus checks.
|
|
18
19
|
|
|
19
20
|
## Procedimento
|
|
20
21
|
|
|
21
22
|
```bash
|
|
23
|
+
npm run tools:doctor
|
|
22
24
|
npm run release:check -- --publish
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
Execute nessa ordem:
|
|
28
|
+
|
|
29
|
+
1. **Saúde canônica.** `tools:doctor` apresenta os checks de `lib/core/health.ts`. Se sair com código
|
|
30
|
+
diferente de zero, a auditoria está **reprovada**: pare, cite o check crítico e repasse a correção
|
|
31
|
+
que ele forneceu. Avisos não bloqueiam, mas entram no parecer. Não reproduza probes no prompt.
|
|
32
|
+
2. **Tarball estrito.** Só após o doctor permitir trabalho, `release:check --publish` empacota e
|
|
33
|
+
instala num diretório isolado (sem `NODE_PATH`, sem o `node_modules` do repo), executa os comandos
|
|
34
|
+
de verdade e reprova em qualquer um destes:
|
|
27
35
|
|
|
28
36
|
| Check | O que prova |
|
|
29
37
|
|---|---|
|
|
@@ -36,7 +44,8 @@ executa os comandos de verdade e reprova em qualquer um destes:
|
|
|
36
44
|
| `deps-declared` | Nada importado ficou fora de `dependencies` |
|
|
37
45
|
| `deps-unused` | Nenhuma dependency é peso morto *(aviso)* |
|
|
38
46
|
|
|
39
|
-
|
|
47
|
+
Os dois gates precisam sair com código zero para aprovação. Uma falha reprova com motivo e correção;
|
|
48
|
+
um aviso não reprova, mas precisa aparecer no parecer.
|
|
40
49
|
|
|
41
50
|
## Seu julgamento, que o gate não faz
|
|
42
51
|
|
|
@@ -44,8 +53,8 @@ O gate diz **o que** quebrou. Você diz **o que fazer com isso**:
|
|
|
44
53
|
|
|
45
54
|
- **Leia a saída inteira antes de opinar.** Uma causa costuma produzir várias linhas; a cascata do
|
|
46
55
|
runner já marca as consequências como `não verificado`, então persiga a raiz, não o eco.
|
|
47
|
-
- **Avisos não reprovam, mas informam.** `deps-unused` num release
|
|
48
|
-
baixa
|
|
56
|
+
- **Avisos não reprovam, mas informam.** Isso vale para ambos os gates. `deps-unused` num release
|
|
57
|
+
público é peso que todo usuário baixa; índice defasado também precisa aparecer no parecer.
|
|
49
58
|
- **Diga o que o gate não cobre.** Ele não valida proveniência de pacote nem julga se a versão do
|
|
50
59
|
`package.json` faz sentido para o que mudou. O projeto *gerado* tem gate próprio — antes de uma
|
|
51
60
|
release que toca os generators, peça também `forja project:smoke --full` (ou `forja check:all
|
package/AGENTS.md
CHANGED
|
@@ -68,7 +68,7 @@ Handoffs entre eles passam pela tabela `handoffs` em `~/forja-workspace/memory/s
|
|
|
68
68
|
|
|
69
69
|
## 7. Release Auditor
|
|
70
70
|
**Quando**: antes de publicar no npm — o especialista de release da governança.
|
|
71
|
-
**Faz**: roda `release:check --publish`, interpreta
|
|
71
|
+
**Faz**: roda `tools:doctor` e depois `release:check --publish`, interpreta os dois pareceres e autoriza (ou barra) a publicação. Valida o núcleo pela fonte canônica e pega quebras que só apareceriam na máquina de quem instala (SPEC-022, ADR-0023, ADR-0024).
|
|
72
72
|
**Não faz**: publicar — `npm publish` é ato humano. Ele diagnostica e autoriza.
|
|
73
73
|
|
|
74
74
|
---
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,86 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [3.0.0] — 2026-09-01 — Engineering Control Plane
|
|
8
|
+
|
|
9
|
+
Fundação inteira da visão ForjaJS 3.0 (ADR-0078): a Forja passa a responder, de forma estruturada
|
|
10
|
+
e com evidência, *por que* um código existe, *se* uma mudança viola a arquitetura pretendida,
|
|
11
|
+
*qual o risco* de uma mudança antes dela acontecer, e *quem/o quê* a produziu. Major version pelo
|
|
12
|
+
critério já registrado no ADR-0078 — mudança de modelo mental, não quebra de compatibilidade:
|
|
13
|
+
**nenhum comando/contrato existente muda de assinatura ou comportamento**; toda extensão é aditiva.
|
|
14
|
+
|
|
15
|
+
### Adicionado
|
|
16
|
+
|
|
17
|
+
**Fundação P0 — Engineering Graph, Architecture Constitution, Change Risk Engine, Evidence Ledger**
|
|
18
|
+
- `adr:list`/`:show`/`:impact`/`:graph` — ADRs/SPECs como nós de primeira classe do Engineering
|
|
19
|
+
Graph, extração determinística (sem LLM).
|
|
20
|
+
- `architecture:compile`/`:check`/`:status`/`:explain`/`:approve` — decisões de ADR (`##
|
|
21
|
+
Constraints`) viram regras executáveis, checadas contra o código real.
|
|
22
|
+
- `risk:assess`/`:explain` — score de risco 0-100 explicável, 7 fatores nomeados com evidência.
|
|
23
|
+
- `evidence:show`, `forja engineer "<objetivo>"` — view agregada por run e façade única que compõe
|
|
24
|
+
contexto + ADRs relevantes + arquitetura + risco + fluxo recomendado.
|
|
25
|
+
|
|
26
|
+
**Fase 3 — Agent Identity, Reputation, Smart Routing**
|
|
27
|
+
- `agent:register`/`:list`/`:show`/`:score`/`:history`/`:recommend` — identidade de agente
|
|
28
|
+
persistente com reputação derivada de comportamento real (nunca auto-declarada), e recomendação
|
|
29
|
+
de agente por adequação a papel/domínio.
|
|
30
|
+
|
|
31
|
+
**Fase 4 — Predictive Change Simulation**
|
|
32
|
+
- `forja simulate <ref>` — testa+arquitetura+risco de um ref num worktree git isolado, nunca
|
|
33
|
+
promove automaticamente.
|
|
34
|
+
|
|
35
|
+
**Fase 5 — AI Code Provenance, Runtime Monitoring**
|
|
36
|
+
- `forja blame <file>`, `forja sbom`, `provenance:record` — proveniência de código gerado por IA
|
|
37
|
+
(granularidade de arquivo).
|
|
38
|
+
- `agent:monitor` — compara comportamento recente de um agente contra sua própria linha de base,
|
|
39
|
+
informação para `PolicyEngine` consultar (`riskScoreRange`/`anomalyScoreRange`), nunca decisão
|
|
40
|
+
automática.
|
|
41
|
+
|
|
42
|
+
**Fase 6 — Learning Loop**
|
|
43
|
+
- `incident:record`/`:list`/`:similar` — registro de incidentes e sugestão por palavra-chave,
|
|
44
|
+
nunca aplicação automática.
|
|
45
|
+
|
|
46
|
+
**`forja engineer` estendida** — passa a compor também agentes recomendados e incidentes parecidos
|
|
47
|
+
conforme essas capacidades passaram a existir.
|
|
48
|
+
|
|
49
|
+
**Fase 7 — Autonomous Maintenance**: documentada em ADR-0079 como prontidão arquitetural
|
|
50
|
+
("arquitetura preparatória, nunca habilitação automática", por desenho explícito da visão
|
|
51
|
+
original) — os guardrails que qualquer manutenção autônoma real precisará respeitar.
|
|
52
|
+
|
|
53
|
+
### Corrigido
|
|
54
|
+
|
|
55
|
+
Achados reais descobertos e corrigidos ao longo da implementação, não deixados como dívida:
|
|
56
|
+
- `SqliteGraphStore` gravava nó a nó sem transação — reindexação do Engineering Graph 2,8× mais
|
|
57
|
+
rápida (7,65s → 2,75s medido contra este repositório), tempo de sistema caindo ~36×.
|
|
58
|
+
- `memory-db` (gate de saúde) reportava "corrompido" quando na verdade só faltava sincronizar uma
|
|
59
|
+
tabela — diagnóstico corrigido.
|
|
60
|
+
- `sandboxEnvironment` (isolamento de sandbox) não passava `HOME`/`USERPROFILE`, travando `npm`
|
|
61
|
+
indefinidamente dentro de um worktree isolado.
|
|
62
|
+
- `security_sensitivity` (fator de risco) não reconhecia auth/session/shutdown como sensíveis —
|
|
63
|
+
vocabulário expandido, limitação estrutural remanescente documentada.
|
|
64
|
+
|
|
65
|
+
### Validação
|
|
66
|
+
|
|
67
|
+
461 testes, `tsc --noEmit`, `check:all`, `spec:check` e `release:check` verdes. 15 PRs (#45-#59),
|
|
68
|
+
cada sprint seguindo o próprio processo SDD da Forja (spec → plan → tasks → implementação → testes)
|
|
69
|
+
e validado contra dado real ou sintético explicitamente documentado como tal.
|
|
70
|
+
|
|
71
|
+
## [2.0.4] — 2026-08-17 — Auditoria de release e handoffs confiáveis
|
|
72
|
+
|
|
73
|
+
### Alterado
|
|
74
|
+
- **Release Auditor consome a saúde canônica** (SPEC-022): executa `tools:doctor` antes de
|
|
75
|
+
`release:check --publish`, interrompe a auditoria em falha crítica e preserva avisos no parecer.
|
|
76
|
+
A prova estrita do tarball continua separada e `npm publish` permanece um ato humano.
|
|
77
|
+
|
|
78
|
+
### Corrigido
|
|
79
|
+
- **`gsd:handoff` voltou a registrar handoffs após a migração TypeScript**: o harness ainda tentava
|
|
80
|
+
executar `scripts/agent-router.mjs`, inexistente no repositório atual. Agora usa `resolveScript`
|
|
81
|
+
para resolver `.ts` em desenvolvimento e `.js` no pacote publicado, com teste de regressão.
|
|
82
|
+
|
|
83
|
+
### Validação
|
|
84
|
+
- 313 testes, `types:check`, `project:check`, `gsd:check` e `tools:doctor` verdes.
|
|
85
|
+
- `npm audit --omit=dev`: zero vulnerabilidades de produção.
|
|
86
|
+
|
|
7
87
|
## [2.0.2] — 2026-08-01 — Integração operacional das Sprints 1–11
|
|
8
88
|
|
|
9
89
|
Consolida a evolução do ForjaJS 2.x após a fundação 2.0.1, conectando a CLI,
|
package/DOC-MAP.md
CHANGED
|
@@ -7,6 +7,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
7
7
|
## Por papel
|
|
8
8
|
|
|
9
9
|
### Operacao CLI / Orquestracao
|
|
10
|
+
- `docs/modos-de-operacao.md` — escolha entre uso embedded no projeto consumidor e studio multi-projeto
|
|
10
11
|
- `docs/processo-projeto.md` — **processo nível 0**: criar vs atualizar projeto com a IA (decisão de entrada)
|
|
11
12
|
- `docs/fluxo.md` — **mapa do ciclo** (CLI-first) com as 3 capacidades integradas (codegraph/harness/ai-engineering)
|
|
12
13
|
- `docs/manual-operacional-cli-sdd-gsd.md` — manual principal para operar CLI-first, SDD, GSD, sprints, handoffs e governanca
|
|
@@ -14,11 +15,17 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
14
15
|
|
|
15
16
|
### Executivo / PM
|
|
16
17
|
- `docs/personas/executive/README.md` — overview, ROI, status
|
|
18
|
+
- `docs/produto/factsheet-marketing.md` — posicionamento, capacidades comprovadas e claims de marketing
|
|
19
|
+
- `docs/produto/roteiro-demo.md` — cenário sintético e roteiro de apresentação
|
|
17
20
|
|
|
18
21
|
### Arquiteto / Tech Lead
|
|
19
22
|
- `docs/personas/architect/README.md`
|
|
20
23
|
- `docs/token-optimization.md` — economia de tokens e cache
|
|
21
24
|
- `docs/structure.md` — hierarquia de diretórios gerados
|
|
25
|
+
- `docs/architecture/FORJA-2.0-ARCHITECTURE.md` — arquitetura de referência 2.0
|
|
26
|
+
- `docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md` — auditoria, gap analysis e
|
|
27
|
+
arquitetura proposta para a evolução 3.0 (Engineering Twin/Control Plane — ver ADR-0078,
|
|
28
|
+
SPEC-031)
|
|
22
29
|
- `memory/90-decisions/` — ADRs
|
|
23
30
|
|
|
24
31
|
### Developer
|
|
@@ -46,6 +53,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
46
53
|
| Tópico | Arquivo |
|
|
47
54
|
|---|---|
|
|
48
55
|
| Manual operacional CLI-first | `docs/manual-operacional-cli-sdd-gsd.md` |
|
|
56
|
+
| Modos embedded e studio | `docs/modos-de-operacao.md` |
|
|
49
57
|
| Guia curto CLI-first | `docs/cli-first-operacao.md` |
|
|
50
58
|
| Mudanças recentes | `CHANGELOG.md` |
|
|
51
59
|
| Decisões arquiteturais | `memory/90-decisions/` |
|
|
@@ -57,6 +65,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
57
65
|
| Estrutura gerada | `docs/structure.md` |
|
|
58
66
|
| Exemplos de código | `docs/examples.md` |
|
|
59
67
|
| Dashboard web (congelado) | `docs/dashboard.md` |
|
|
68
|
+
| Factsheet de produto e marketing | `docs/produto/factsheet-marketing.md` |
|
|
60
69
|
|
|
61
70
|
---
|
|
62
71
|
|
package/README.md
CHANGED
|
@@ -100,6 +100,15 @@ process followed?", the answer is a file, not a promise.
|
|
|
100
100
|
brings new scaffold pieces to already-generated projects without touching the user's code.
|
|
101
101
|
- **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
|
|
102
102
|
(agent-team design), **ai-engineering** (knowledge base).
|
|
103
|
+
- **LLM Fit Loop** — adapters de CLI, perfis no workspace, probes sem custo, observações e
|
|
104
|
+
recomendação determinística por papel/tarefa; credenciais nunca entram no Forja.
|
|
105
|
+
- **Engineering Control Plane** (v3.0, ADR-0078) — the Engineering Graph turns ADRs/SPECs into
|
|
106
|
+
first-class, queryable nodes; the Architecture Constitution checks real code against decisions
|
|
107
|
+
already recorded; the Change Risk Engine scores a change 0-100 with named, evidenced factors;
|
|
108
|
+
`forja simulate` tests a ref in an isolated worktree and never promotes on its own. One façade,
|
|
109
|
+
`forja engineer "<goal>"`, composes all of it — context, relevant ADRs, architecture check, risk,
|
|
110
|
+
recommended agents, similar past incidents — before you start. Every score is information for a
|
|
111
|
+
human/policy rule to consult, never an autonomous decision on its own.
|
|
103
112
|
|
|
104
113
|
## ⚡ Quick start
|
|
105
114
|
|
|
@@ -121,6 +130,16 @@ forja spec:tasks my-feature
|
|
|
121
130
|
forja spec:check my-feature
|
|
122
131
|
```
|
|
123
132
|
|
|
133
|
+
### Maintenance commands
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
forja project:upgrade <project> --apply
|
|
137
|
+
forja code:context <domain> --code
|
|
138
|
+
forja memory:audit
|
|
139
|
+
forja token:economy --project <project>
|
|
140
|
+
forja spec:set-status <feature> <spec|plan|tasks> <draft|approved>
|
|
141
|
+
```
|
|
142
|
+
|
|
124
143
|
### Prove supervised autonomy locally
|
|
125
144
|
|
|
126
145
|
The deterministic offline proof uses an external fixture, a real Git worktree,
|
|
@@ -223,6 +242,34 @@ forja orchestrate:advance <slug> # run the stage gate; green → next;
|
|
|
223
242
|
forja code:check # trustworthy index (worktree + freshness)
|
|
224
243
|
forja code:impact <symbol> # callers + blast radius before you edit
|
|
225
244
|
forja code:query "<term>" # also: code:index · code:sync · code:status
|
|
245
|
+
forja drift:check [--domain <d>] # reindex + flag 'verified' relations that stopped being true
|
|
246
|
+
forja adr:list # ADRs as first-class graph nodes, with status (SPEC-032)
|
|
247
|
+
forja adr:show <id> # status, source file, constraints
|
|
248
|
+
forja adr:impact <id> # who/what depends on this ADR — GraphLoop.impact()
|
|
249
|
+
forja adr:graph [<id>] # ADR/SPEC subgraph as JSON
|
|
250
|
+
forja architecture:compile # ADRs (## Constraints) → constitution.json (SPEC-033)
|
|
251
|
+
forja architecture:check # real code vs. the compiled Constitution
|
|
252
|
+
forja architecture:status # active/proposed rules, last compile
|
|
253
|
+
forja architecture:explain <rule-id> # source ADR, original text, severity
|
|
254
|
+
forja architecture:approve <rule-id> # promotes a proposed rule to active (via ApprovalLedger)
|
|
255
|
+
forja risk:assess [ref] # 0-100 change risk score, 7 named factors (SPEC-034)
|
|
256
|
+
forja risk:explain <assessment-id> # replays a computed assessment, factor by factor
|
|
257
|
+
forja evidence:show <run-id> # aggregated view of a persisted run (SPEC-035)
|
|
258
|
+
forja engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json] # façade: context + relevant ADRs + architecture check + risk + recommended agents + similar incidents + recommended flow (SPEC-035, SPEC-042)
|
|
259
|
+
forja agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>] # register/update an agent (SPEC-036)
|
|
260
|
+
forja agent:list # registered agents, with trustLevel if already scored
|
|
261
|
+
forja agent:show <id> # detail of one registered agent
|
|
262
|
+
forja agent:score <id> [--domain <d>] # computes and persists trustLevel/autonomyLevel from real Observations
|
|
263
|
+
forja agent:history <id> # an agent's Observations, most recent first
|
|
264
|
+
forja agent:recommend --role <role> [--domain <d>] # ranks registered agents by fit — information, not assignment (SPEC-037)
|
|
265
|
+
forja simulate <ref> [--command "npm test"] [--json] # test+architecture+risk against an isolated worktree, never promotes (SPEC-038)
|
|
266
|
+
forja provenance:record <run-id> # extracts file<->agent provenance from a persisted RuntimeRun (SPEC-039)
|
|
267
|
+
forja blame <file> # provenance history for a file — file granularity, not line
|
|
268
|
+
forja sbom [--json] # AI-SBOM: provenance report aggregated by agent
|
|
269
|
+
forja agent:monitor <id> [--window-hours <n>] # compares recent behavior against historical baseline — information, never blocks (SPEC-040)
|
|
270
|
+
forja incident:record --title <t> [--description <d>] # records an incident in the Engineering Graph (SPEC-041)
|
|
271
|
+
forja incident:list # recorded incidents, most recent first
|
|
272
|
+
forja incident:similar "<query>" # keyword-based similar-incident suggestion — never applies anything
|
|
226
273
|
|
|
227
274
|
# Memory & context (workspace)
|
|
228
275
|
forja sync:universal # reindex the workspace SQLite FTS5
|
|
@@ -231,6 +278,14 @@ forja context:smart # smart-context (3 modes, ADR-0003)
|
|
|
231
278
|
forja memory:compress # archive old runs + VACUUM
|
|
232
279
|
forja memory:extract # extract global knowledge from memory
|
|
233
280
|
|
|
281
|
+
# LLM adapters and evidence
|
|
282
|
+
forja llm:profiles:init # create workspace-local adapter profiles
|
|
283
|
+
forja llm:doctor # verify configured CLIs without invoking a model
|
|
284
|
+
forja llm:recommend --role worker --task implementation
|
|
285
|
+
forja llm:run --profile codex --task specs/my-feature/spec.md
|
|
286
|
+
forja llm:eval --scope model --id codex:default
|
|
287
|
+
forja cost:economy # real $ cost per model, from the observation store
|
|
288
|
+
|
|
234
289
|
# Quality & release
|
|
235
290
|
forja project:check # framework standards (pre-commit)
|
|
236
291
|
forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
|
|
@@ -312,6 +367,31 @@ output, code, and ADRs are readable regardless of language.
|
|
|
312
367
|
The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
|
|
313
368
|
below either closes a framework frontier with a gate, or carries that pattern into generated projects.
|
|
314
369
|
|
|
370
|
+
**Shipped** (v3.0.0 — Engineering Control Plane, ADR-0078)
|
|
371
|
+
|
|
372
|
+
- [x] **Engineering Graph** — ADRs/SPECs as first-class, queryable nodes (`adr:list/show/impact/graph`),
|
|
373
|
+
deterministic extraction, no LLM (SPEC-032).
|
|
374
|
+
- [x] **Architecture Constitution** — ADR `## Constraints` compile into rules checked against real
|
|
375
|
+
code (`architecture:compile/check/status/explain/approve`), reusing `ApprovalLedger`, not a
|
|
376
|
+
parallel approval system (SPEC-033).
|
|
377
|
+
- [x] **Change Risk Engine** — a 0-100 score with 7 named, evidenced factors (`risk:assess/explain`);
|
|
378
|
+
`PolicyEngine` can optionally consult it (`riskScoreRange`), never a parallel decision engine
|
|
379
|
+
(SPEC-034).
|
|
380
|
+
- [x] **Evidence Ledger + `forja engineer`** — a per-run aggregated view, and the façade that
|
|
381
|
+
composes context + relevant ADRs + architecture + risk + recommended agents + similar incidents +
|
|
382
|
+
recommended flow before you start (SPEC-035, extended in SPEC-042).
|
|
383
|
+
- [x] **Agent Identity & Reputation, Smart Routing** — persistent agent registry with reputation
|
|
384
|
+
derived from real behavior, never self-declared (`agent:register/score/recommend`, SPEC-036/037).
|
|
385
|
+
- [x] **Predictive Change Simulation** — `forja simulate <ref>` tests a ref in an isolated git
|
|
386
|
+
worktree; never promotes on its own (SPEC-038).
|
|
387
|
+
- [x] **AI Code Provenance + Runtime Monitoring** — `forja blame`/`sbom` (file-granularity
|
|
388
|
+
provenance), `agent:monitor` (behavior-anomaly detection vs. an agent's own baseline) — both
|
|
389
|
+
information for `PolicyEngine`/a human to consult, never automatic (SPEC-039/040).
|
|
390
|
+
- [x] **Learning Loop** — `incident:record/list/similar`, keyword-based suggestion, never automatic
|
|
391
|
+
application (SPEC-041).
|
|
392
|
+
- [x] **Autonomous Maintenance readiness** — ADR-0079 documents the guardrails any future real
|
|
393
|
+
autonomous-maintenance spec must respect; deliberately not enabled yet, by the vision's own design.
|
|
394
|
+
|
|
315
395
|
**Shipped** (through v1.6.0)
|
|
316
396
|
|
|
317
397
|
- [x] **Gate family** — every framework frontier is guarded by an invariant that runs: core
|
|
@@ -327,17 +407,17 @@ below either closes a framework frontier with a gate, or carries that pattern in
|
|
|
327
407
|
overwrites (SPEC-018).
|
|
328
408
|
- [x] **Calibrated Clean Architecture** — layers where they pay off, lean where they don't; and the
|
|
329
409
|
token claim **measured and corrected** — the saving is memory's, not the layers' (ADR-0027).
|
|
330
|
-
|
|
331
|
-
**Next** (by dependency, not by wish)
|
|
332
|
-
|
|
333
410
|
- [x] **Generated backend `builds` under new toolchains** — the template now matches the
|
|
334
411
|
framework's `better-sqlite3` (^12, with prebuilds); `check:all --full` compiles the generated
|
|
335
412
|
backend on Node 26.
|
|
336
413
|
- [x] **`release-auditor` consumes the gate** — the agent runs and judges `release:check --publish`
|
|
337
414
|
(ADR-0024), including `consumer-spec-new`; it doesn't reimplement the procedure.
|
|
415
|
+
|
|
416
|
+
**Next** (by dependency, not by wish)
|
|
417
|
+
|
|
418
|
+
- [ ] **Cross-project Intelligence** (Phase 6 remainder) — correlating incidents across multiple
|
|
419
|
+
repositories; needs a data source this single-repo workspace doesn't have yet.
|
|
338
420
|
- [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
|
|
339
|
-
- [ ] **(vision) the orchestration engine** — the handoff chain that **runs**, not just is coherent
|
|
340
|
-
(SPEC-019 left it as future). The namesake executing: a 2.0 candidate.
|
|
341
421
|
|
|
342
422
|
Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
|
|
343
423
|
|
package/README.pt-BR.md
CHANGED
|
@@ -87,6 +87,7 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
87
87
|
- **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
|
|
88
88
|
- **Geração de projetos** — `project:new` cria scaffold completo no workspace (memória, agentes, instruções multi-IA, backend NestJS como boilerplate padrão) e registra a ficha; `project:upgrade` traz peças novas para projetos já gerados sem tocar no código do usuário.
|
|
89
89
|
- **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
|
|
90
|
+
- **Engineering Control Plane** (v3.0, ADR-0078) — o Engineering Graph vira ADRs/SPECs em nós de primeira classe consultáveis; a Architecture Constitution checa o código real contra decisões já registradas; o Change Risk Engine pontua uma mudança 0-100 com fatores nomeados e evidenciados; `forja simulate` testa um ref num worktree isolado e nunca promove sozinho. Uma façade só, `forja engineer "<objetivo>"`, compõe tudo isso — contexto, ADRs relevantes, checagem de arquitetura, risco, agentes recomendados, incidentes parecidos — antes de você começar. Todo score é informação pra um humano/regra de política consultar, nunca uma decisão autônoma por si só.
|
|
90
91
|
|
|
91
92
|
## ⚡ Quick start
|
|
92
93
|
|
|
@@ -300,6 +301,34 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
|
|
|
300
301
|
item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
|
|
301
302
|
gerados.
|
|
302
303
|
|
|
304
|
+
**Entregue** (v3.0.0 — Engineering Control Plane, ADR-0078)
|
|
305
|
+
|
|
306
|
+
- [x] **Engineering Graph** — ADRs/SPECs como nós de primeira classe consultáveis
|
|
307
|
+
(`adr:list/show/impact/graph`), extração determinística, sem LLM (SPEC-032).
|
|
308
|
+
- [x] **Architecture Constitution** — `## Constraints` de ADR viram regras checadas contra o código
|
|
309
|
+
real (`architecture:compile/check/status/explain/approve`), reaproveitando o `ApprovalLedger`, não
|
|
310
|
+
um sistema de aprovação paralelo (SPEC-033).
|
|
311
|
+
- [x] **Change Risk Engine** — score 0-100 com 7 fatores nomeados e evidenciados
|
|
312
|
+
(`risk:assess/explain`); o `PolicyEngine` pode opcionalmente consultá-lo (`riskScoreRange`), nunca
|
|
313
|
+
um motor de decisão paralelo (SPEC-034).
|
|
314
|
+
- [x] **Evidence Ledger + `forja engineer`** — view agregada por run, e a façade que compõe contexto
|
|
315
|
+
+ ADRs relevantes + arquitetura + risco + agentes recomendados + incidentes parecidos + fluxo
|
|
316
|
+
recomendado antes de você começar (SPEC-035, estendida em SPEC-042).
|
|
317
|
+
- [x] **Agent Identity & Reputation, Smart Routing** — registro persistente de agente com reputação
|
|
318
|
+
derivada de comportamento real, nunca auto-declarada (`agent:register/score/recommend`,
|
|
319
|
+
SPEC-036/037).
|
|
320
|
+
- [x] **Predictive Change Simulation** — `forja simulate <ref>` testa um ref num worktree git
|
|
321
|
+
isolado; nunca promove sozinho (SPEC-038).
|
|
322
|
+
- [x] **AI Code Provenance + Runtime Monitoring** — `forja blame`/`sbom` (proveniência em
|
|
323
|
+
granularidade de arquivo), `agent:monitor` (detecção de anomalia de comportamento contra a
|
|
324
|
+
própria linha de base do agente) — os dois são informação pro `PolicyEngine`/um humano consultar,
|
|
325
|
+
nunca automático (SPEC-039/040).
|
|
326
|
+
- [x] **Learning Loop** — `incident:record/list/similar`, sugestão por palavra-chave, nunca
|
|
327
|
+
aplicação automática (SPEC-041).
|
|
328
|
+
- [x] **Prontidão de Autonomous Maintenance** — ADR-0079 documenta os guardrails que qualquer spec
|
|
329
|
+
futura de manutenção autônoma real precisará respeitar; deliberadamente não habilitada ainda, por
|
|
330
|
+
desenho explícito da própria visão.
|
|
331
|
+
|
|
303
332
|
**Entregue** (até v1.6.0)
|
|
304
333
|
|
|
305
334
|
- [x] **Família de gates** — cada fronteira do framework guarda por um invariante que roda: núcleo
|
|
@@ -315,16 +344,16 @@ gerados.
|
|
|
315
344
|
sobrescreve (SPEC-018).
|
|
316
345
|
- [x] **Clean Architecture calibrado** — camadas onde se pagam, enxuto onde não; e a claim de token
|
|
317
346
|
**medida e corrigida** — a economia é da memória, não das camadas (ADR-0027).
|
|
318
|
-
|
|
319
|
-
**Próximos passos** (por dependência, não por desejo)
|
|
320
|
-
|
|
321
347
|
- [x] **`builds` do backend gerado sob toolchain novo** — o template alinhou o `better-sqlite3` ao
|
|
322
348
|
do framework (^12, com prebuilds); o `check:all --full` compila o backend gerado em Node 26.
|
|
323
349
|
- [x] **`release-auditor` consome o gate** — o agente executa e julga `release:check --publish`
|
|
324
350
|
(ADR-0024), incluindo o `consumer-spec-new`; não reimplementa o procedimento.
|
|
351
|
+
|
|
352
|
+
**Próximos passos** (por dependência, não por desejo)
|
|
353
|
+
|
|
354
|
+
- [ ] **Cross-project Intelligence** (resto da Fase 6) — correlacionar incidentes entre múltiplos
|
|
355
|
+
repositórios; exige uma fonte de dado que este workspace de um único repositório ainda não tem.
|
|
325
356
|
- [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
|
|
326
|
-
- [ ] **(visão) o motor de orquestração** — a cadeia de handoffs que **roda**, não só é coerente
|
|
327
|
-
(SPEC-019 deixou como futuro). O namesake executando: candidato ao 2.0.
|
|
328
357
|
|
|
329
358
|
Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
|
|
330
359
|
|
|
@@ -1,11 +1,18 @@
|
|
|
1
1
|
// @ts-expect-error Next resolves the adjacent TypeScript helper.
|
|
2
2
|
import { buildApprovalDecisionBody } from '../approval';
|
|
3
|
+
// @ts-expect-error Next resolves the adjacent TypeScript helper.
|
|
4
|
+
import { isCallerAuthorized, matchesAllowedPrefix } from '../guard';
|
|
3
5
|
const allowedPrefixes = ['/control-plane/metrics', '/observability/observations', '/events/stream', '/executions/', '/graph/query', '/graph/impact', '/approvals'];
|
|
4
6
|
export async function GET(request, context) { return forward(request, await context.params, 'GET'); }
|
|
5
7
|
export async function POST(request, context) { return forward(request, await context.params, 'POST'); }
|
|
6
8
|
async function forward(request, params, method) {
|
|
9
|
+
// Fails closed: without FORJA_DASHBOARD_TOKEN configured, or without the caller presenting it,
|
|
10
|
+
// this route refuses every request rather than silently forwarding the server's own backend
|
|
11
|
+
// credential (FORJA_API_TOKEN, below) on an unauthenticated caller's behalf.
|
|
12
|
+
if (!isCallerAuthorized(request))
|
|
13
|
+
return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: 'Dashboard caller authentication required' } }), { status: 403, headers: { 'content-type': 'application/json' } });
|
|
7
14
|
const path = `/${params.path.join('/')}`;
|
|
8
|
-
if (!allowedPrefixes.some((prefix) => path
|
|
15
|
+
if (!allowedPrefixes.some((prefix) => matchesAllowedPrefix(path, prefix)))
|
|
9
16
|
return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: 'Dashboard route is not allowed' } }), { status: 403, headers: { 'content-type': 'application/json' } });
|
|
10
17
|
const backend = process.env.FORJA_API_URL ?? 'http://localhost:3000';
|
|
11
18
|
const token = process.env.FORJA_API_TOKEN;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure helpers backing the dashboard's `/api/forja/[...path]` proxy route. Kept out of route.ts
|
|
3
|
+
* (which only wires Next's Request/Response) so they're directly unit-testable, same pattern as
|
|
4
|
+
* `approval.ts`.
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* True when `pathname` is `prefix` itself or a path segment nested under it. Plain
|
|
8
|
+
* `pathname.startsWith(prefix)` is not enough: it also matches an unrelated sibling like
|
|
9
|
+
* `/control-plane/metrics-extra` against the `/control-plane/metrics` prefix, since string
|
|
10
|
+
* prefixing doesn't respect segment boundaries. `isPathWithinRoot` (packages/contracts) isn't
|
|
11
|
+
* reused here — it resolves inputs as filesystem paths via `path.resolve`, which is the wrong
|
|
12
|
+
* semantics for URL path segments (and platform-dependent via `path.sep`); this applies the same
|
|
13
|
+
* boundary principle directly on `/`, which is always the URL path separator.
|
|
14
|
+
*/
|
|
15
|
+
export declare function matchesAllowedPrefix(pathname: string, prefix: string): boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Authenticates the *caller of this dashboard route*, not the backend it proxies to.
|
|
18
|
+
* FORJA_API_TOKEN (forwarded as a Bearer header below) is the server's own credential to the
|
|
19
|
+
* backend; without this check, anyone who can reach the deployed dashboard gets that credential
|
|
20
|
+
* applied on their behalf, including approval decisions. Fails closed on both ends: an
|
|
21
|
+
* unconfigured FORJA_DASHBOARD_TOKEN means the route refuses every request rather than allowing
|
|
22
|
+
* all of them, and a present-but-non-matching credential is rejected the same way as a missing one.
|
|
23
|
+
*/
|
|
24
|
+
export declare function isCallerAuthorized(request: Request, expectedToken?: string | undefined): boolean;
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure helpers backing the dashboard's `/api/forja/[...path]` proxy route. Kept out of route.ts
|
|
3
|
+
* (which only wires Next's Request/Response) so they're directly unit-testable, same pattern as
|
|
4
|
+
* `approval.ts`.
|
|
5
|
+
*/
|
|
6
|
+
import { timingSafeEqual } from 'node:crypto';
|
|
7
|
+
/**
|
|
8
|
+
* True when `pathname` is `prefix` itself or a path segment nested under it. Plain
|
|
9
|
+
* `pathname.startsWith(prefix)` is not enough: it also matches an unrelated sibling like
|
|
10
|
+
* `/control-plane/metrics-extra` against the `/control-plane/metrics` prefix, since string
|
|
11
|
+
* prefixing doesn't respect segment boundaries. `isPathWithinRoot` (packages/contracts) isn't
|
|
12
|
+
* reused here — it resolves inputs as filesystem paths via `path.resolve`, which is the wrong
|
|
13
|
+
* semantics for URL path segments (and platform-dependent via `path.sep`); this applies the same
|
|
14
|
+
* boundary principle directly on `/`, which is always the URL path separator.
|
|
15
|
+
*/
|
|
16
|
+
export function matchesAllowedPrefix(pathname, prefix) {
|
|
17
|
+
if (pathname === prefix)
|
|
18
|
+
return true;
|
|
19
|
+
const boundary = prefix.endsWith('/') ? prefix : `${prefix}/`;
|
|
20
|
+
return pathname.startsWith(boundary);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Authenticates the *caller of this dashboard route*, not the backend it proxies to.
|
|
24
|
+
* FORJA_API_TOKEN (forwarded as a Bearer header below) is the server's own credential to the
|
|
25
|
+
* backend; without this check, anyone who can reach the deployed dashboard gets that credential
|
|
26
|
+
* applied on their behalf, including approval decisions. Fails closed on both ends: an
|
|
27
|
+
* unconfigured FORJA_DASHBOARD_TOKEN means the route refuses every request rather than allowing
|
|
28
|
+
* all of them, and a present-but-non-matching credential is rejected the same way as a missing one.
|
|
29
|
+
*/
|
|
30
|
+
export function isCallerAuthorized(request, expectedToken = process.env.FORJA_DASHBOARD_TOKEN) {
|
|
31
|
+
if (expectedToken === undefined || expectedToken.length === 0)
|
|
32
|
+
return false;
|
|
33
|
+
const header = request.headers.get('x-forja-dashboard-token');
|
|
34
|
+
if (header !== null)
|
|
35
|
+
return constantTimeEqual(header, expectedToken);
|
|
36
|
+
const cookie = readCookie(request.headers.get('cookie'), 'forja_dashboard_token');
|
|
37
|
+
if (cookie !== undefined)
|
|
38
|
+
return constantTimeEqual(cookie, expectedToken);
|
|
39
|
+
return false;
|
|
40
|
+
}
|
|
41
|
+
function constantTimeEqual(left, right) {
|
|
42
|
+
const leftBuffer = Buffer.from(left);
|
|
43
|
+
const rightBuffer = Buffer.from(right);
|
|
44
|
+
return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
|
|
45
|
+
}
|
|
46
|
+
function readCookie(cookieHeader, name) {
|
|
47
|
+
if (cookieHeader === null)
|
|
48
|
+
return undefined;
|
|
49
|
+
for (const part of cookieHeader.split(';')) {
|
|
50
|
+
const separator = part.indexOf('=');
|
|
51
|
+
if (separator === -1)
|
|
52
|
+
continue;
|
|
53
|
+
if (part.slice(0, separator).trim() !== name)
|
|
54
|
+
continue;
|
|
55
|
+
try {
|
|
56
|
+
return decodeURIComponent(part.slice(separator + 1).trim());
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
return part.slice(separator + 1).trim();
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
@@ -13,7 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
|
|
|
13
13
|
var ForjaNestModule_1;
|
|
14
14
|
import { Controller, Get, Global, Inject, Injectable, Module, Optional, Post, Req, Res, Sse, UnauthorizedException, UseGuards } from '@nestjs/common';
|
|
15
15
|
import { Observable as RxObservable } from 'rxjs';
|
|
16
|
-
import { ForjaNestAdapter } from "../../../packages/adapter-nest/src/index.js";
|
|
16
|
+
import { ForjaNestAdapter, isLoopbackAddress } from "../../../packages/adapter-nest/src/index.js";
|
|
17
17
|
export const FORJA_MCP = Symbol('FORJA_MCP');
|
|
18
18
|
export const FORJA_EVENT_STREAM = Symbol('FORJA_EVENT_STREAM');
|
|
19
19
|
export const FORJA_AUTHENTICATOR = Symbol('FORJA_AUTHENTICATOR');
|
|
@@ -25,9 +25,14 @@ let ForjaLocalAuthGuard = class ForjaLocalAuthGuard {
|
|
|
25
25
|
authenticator;
|
|
26
26
|
constructor(authenticator) { this.authenticator = authenticator; }
|
|
27
27
|
async canActivate(context) {
|
|
28
|
-
if (this.authenticator === undefined)
|
|
29
|
-
return true;
|
|
30
28
|
const request = context.switchToHttp().getRequest();
|
|
29
|
+
if (this.authenticator === undefined) {
|
|
30
|
+
// Fail closed, not open: no FORJA_AUTH_TOKEN configured means loopback-only, not allow-all —
|
|
31
|
+
// otherwise a port-forward or container-network hop reaches this server fully unauthenticated.
|
|
32
|
+
if (isLoopbackAddress(request.socket?.remoteAddress))
|
|
33
|
+
return true;
|
|
34
|
+
throw new UnauthorizedException('Local authentication required (no FORJA_AUTH_TOKEN configured; only loopback requests are allowed)');
|
|
35
|
+
}
|
|
31
36
|
if (await this.authenticator.authenticate(headers(request)))
|
|
32
37
|
return true;
|
|
33
38
|
throw new UnauthorizedException('Local authentication required');
|
|
@@ -80,7 +85,7 @@ let ForjaNestController = class ForjaNestController {
|
|
|
80
85
|
});
|
|
81
86
|
}
|
|
82
87
|
async route(request, response, method, path, body) {
|
|
83
|
-
const result = await this.adapter.handle({ method, path, query: request.query, body, headers: headers(request), correlationId: this.correlation(request) });
|
|
88
|
+
const result = await this.adapter.handle({ method, path, query: request.query, body, headers: headers(request), correlationId: this.correlation(request), remoteAddress: request.socket?.remoteAddress });
|
|
84
89
|
response.status(result.status);
|
|
85
90
|
for (const [key, value] of Object.entries(result.headers))
|
|
86
91
|
response.setHeader(key, value);
|
|
@@ -146,10 +146,19 @@ export async function bootstrap(port = Number(process.env.FORJA_PORT ?? 3000)) {
|
|
|
146
146
|
registerGraphSyncCapability(registry, graph, new GitGraphDocumentSource(process.env.FORJA_GRAPH_ROOT ?? process.cwd(), new SpawnCommandRunner()));
|
|
147
147
|
const context = new ContextEngine({ graph: new GraphContextSource({ searchContext: (objective) => graph.contextRecords(objective) }), cache: new SqliteContextCache(runtimeDatabase) });
|
|
148
148
|
const mcp = createDefaultMcp(registry, policy, graph, mcpAudit, context);
|
|
149
|
-
const
|
|
149
|
+
const authenticator = createLocalAuthenticator();
|
|
150
|
+
if (authenticator === undefined)
|
|
151
|
+
console.warn('[forja] FORJA_AUTH_TOKEN is not set — only loopback (127.0.0.1/::1) requests will be accepted. Set FORJA_AUTH_TOKEN before exposing this server beyond localhost.');
|
|
152
|
+
const app = await NestFactory.create(AppModule.register({ mcp, eventStream, authenticator, controlPlane: createDefaultControlPlane(eventStream, registry, policy, runtimePersistence, approvals, events, graph, context, orchestrationStore, observationStore) }));
|
|
150
153
|
const config = new DocumentBuilder().setTitle('ForjaJS 2.0 API').setDescription('Local-first agent control plane').setVersion('2.0.0').build();
|
|
151
154
|
SwaggerModule.setup('docs', app, SwaggerModule.createDocument(app, config));
|
|
152
155
|
await app.listen(port, '127.0.0.1');
|
|
156
|
+
const shutdown = (signal) => {
|
|
157
|
+
console.log(`[forja] received ${signal}, closing database and shutting down`);
|
|
158
|
+
void app.close().finally(() => { runtimeDatabase.close(); process.exit(0); });
|
|
159
|
+
};
|
|
160
|
+
process.on('SIGINT', shutdown);
|
|
161
|
+
process.on('SIGTERM', shutdown);
|
|
153
162
|
return app;
|
|
154
163
|
}
|
|
155
164
|
if (import.meta.url === `file://${process.argv[1]}`)
|
package/dist/bin/forja.js
CHANGED
|
@@ -25,6 +25,7 @@ import { getWorkspaceDbDir, getWorkspaceDbPath } from "../lib/workspace.js";
|
|
|
25
25
|
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
|
+
const STUDIO_COMMANDS = new Set(['workspace:init', 'project:new', 'project:list', 'project:upgrade', 'workspace:project:check', 'init:project', 'demo:workspace']);
|
|
28
29
|
function printHelp() {
|
|
29
30
|
console.log('Forja — core executivo (ADR-0020)');
|
|
30
31
|
console.log('Uso: forja <comando> [args]\n');
|
|
@@ -122,6 +123,13 @@ function jsonFlag(args) {
|
|
|
122
123
|
function withoutFlag(args, flag) {
|
|
123
124
|
return args.filter((arg) => arg !== flag);
|
|
124
125
|
}
|
|
126
|
+
// Prompts podem conter dados do projeto. A execução recebe o texto, mas a trilha de auditoria só prova
|
|
127
|
+
// que um prompt foi enviado; nunca preserva seu conteúdo.
|
|
128
|
+
function auditArgs(command, args) {
|
|
129
|
+
if (command !== 'llm:run')
|
|
130
|
+
return args;
|
|
131
|
+
return args.map((arg, index) => args[index - 1] === '--prompt' ? '<redacted>' : arg);
|
|
132
|
+
}
|
|
125
133
|
function printExecutionResult(result, json) {
|
|
126
134
|
if (json) {
|
|
127
135
|
console.log(JSON.stringify(result));
|
|
@@ -285,6 +293,10 @@ if (!name || name === 'help' || name === '--help' || name === '-h') {
|
|
|
285
293
|
printHelp();
|
|
286
294
|
process.exit(0);
|
|
287
295
|
}
|
|
296
|
+
// O pacote instalado dentro de um projeto opera o próprio cwd. Operações que administram vários
|
|
297
|
+
// projetos permanecem no studio global; FORJA_MODE/FORJA_WORKSPACE sempre vencem a inferência.
|
|
298
|
+
if (STUDIO_COMMANDS.has(name) && !process.env.FORJA_MODE && !process.env.FORJA_WORKSPACE)
|
|
299
|
+
process.env.FORJA_MODE = 'studio';
|
|
288
300
|
if (name === 'capabilities:list' || name === 'capabilities:describe' || name === 'capability:execute') {
|
|
289
301
|
process.exit(await runCapabilityCommand(name, rest));
|
|
290
302
|
}
|
|
@@ -309,7 +321,7 @@ if (gateErrors.length) {
|
|
|
309
321
|
audit({
|
|
310
322
|
ts: new Date().toISOString(),
|
|
311
323
|
cmd: name,
|
|
312
|
-
args: rest,
|
|
324
|
+
args: auditArgs(name, rest),
|
|
313
325
|
exitCode: 1,
|
|
314
326
|
durationMs: 0,
|
|
315
327
|
gate: 'blocked',
|
|
@@ -347,7 +359,7 @@ const exitCode = result.status ?? 1;
|
|
|
347
359
|
audit({
|
|
348
360
|
ts: new Date().toISOString(),
|
|
349
361
|
cmd: name,
|
|
350
|
-
args: rest,
|
|
362
|
+
args: auditArgs(name, rest),
|
|
351
363
|
exitCode,
|
|
352
364
|
durationMs: Date.now() - started,
|
|
353
365
|
});
|