forjajs 5.1.0 → 5.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +108 -0
- package/README.md +52 -4
- package/README.pt-BR.md +54 -4
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +365 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +26 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/exec.d.ts +55 -0
- package/dist/lib/exec.js +141 -0
- package/dist/lib/project-wiring.js +6 -2
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/packages/adapter-git/src/index.js +13 -4
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/llm/src/index.js +7 -24
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/llm-fit.js +15 -6
- package/dist/scripts/simulate.js +16 -4
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +20 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +104 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +7 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/skills/testing/SKILL.md +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -13,6 +13,114 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
|
|
|
13
13
|
|
|
14
14
|
---
|
|
15
15
|
|
|
16
|
+
## [5.3.1] — 2026-11-16 — Windows funcional
|
|
17
|
+
|
|
18
|
+
### O que melhorou
|
|
19
|
+
|
|
20
|
+
- **`llm:run`, `llm:doctor` e `eval:agents` funcionam no Windows.** O Forja encontra e executa
|
|
21
|
+
os CLIs de agente instalados pelo npm (`codex.cmd`, `claude.cmd`, `gemini.cmd`) sem WSL.
|
|
22
|
+
O timeout derruba a árvore inteira do processo — um agente estourado para de queimar token.
|
|
23
|
+
- **`forja simulate` funciona no Windows.** O worktree Git é criado, o comando roda e a
|
|
24
|
+
limpeza fecha sem EPERM. O npm é resolvido pelo shim `.cmd` correto.
|
|
25
|
+
- **`spec:trace` conta critérios em checkouts CRLF.** Projetos clonados no Windows não
|
|
26
|
+
reportam mais 0/0 critérios por causa do separador de linha.
|
|
27
|
+
- **O CI bloqueia em toda célula.** Windows deixou de ser tolerância informacional e agora
|
|
28
|
+
segura o merge como ubuntu e macOS. Regressões de plataforma não chegam ao release.
|
|
29
|
+
|
|
30
|
+
### Corrigido
|
|
31
|
+
|
|
32
|
+
- Spawn de `.cmd`/`.bat` sem `shell: true` (CVE-2024-27980) resolvido por launcher próprio
|
|
33
|
+
com quoting de cmd.exe testado contra injeção de argumentos (#86).
|
|
34
|
+
- `resolveCommand` prefere extensão executável (`.cmd`/`.exe`) sobre scripts sem extensão
|
|
35
|
+
que o `where` lista primeiro (#86).
|
|
36
|
+
- `sandboxEnvironment` inclui `APPDATA`, `LOCALAPPDATA`, `COMSPEC`, `PATHEXT` — npm e git
|
|
37
|
+
funcionam dentro do worktree sem herdar secrets (#86).
|
|
38
|
+
- Caminhos 8.3 (`RUNNER~1`) canonicalizados com `realpathSync` antes de comparação (#86).
|
|
39
|
+
- `parseCriteria` aceita CRLF (`\r?\n`) no checklist de specs (#86).
|
|
40
|
+
|
|
41
|
+
### Adicionado
|
|
42
|
+
|
|
43
|
+
- `lib/exec.ts`: módulo portável de subprocesso — `resolveCommand`, `spawnAgent`, `runShell`,
|
|
44
|
+
`killTree`. Sem dependência nova. 14 testes incluindo roundtrip de argumentos hostis (#86).
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## [5.3.0] — 2026-11-14 — Supervisão, execução vinculada e qualidade verificável
|
|
49
|
+
|
|
50
|
+
### O que melhorou
|
|
51
|
+
|
|
52
|
+
- **Supervisão num painel de leitura.** Cinco abas reúnem próxima ação, rastreabilidade dos
|
|
53
|
+
critérios, custos observados, gates e operação. O painel usa as capacidades de leitura
|
|
54
|
+
declaradas pelo servidor, exige autenticação e não inventa custo quando não há uso medido.
|
|
55
|
+
- **Planejamento conectado ao contexto real.** A composição do servidor pode produzir propostas
|
|
56
|
+
revisáveis a partir de tarefas, handoffs e memória, com orçamento e proveniência. A revisão
|
|
57
|
+
fica persistida e verifica mudanças nas fontes; aprovar um plano não dispara execução nem
|
|
58
|
+
substitui a autorização das capacidades.
|
|
59
|
+
- **Tarefas acompanham a execução supervisionada.** Runtime, tarefa e handoff mantêm vínculos e
|
|
60
|
+
recuperação persistente. Conclusão exige validação independente; falha ou ausência de checks
|
|
61
|
+
não libera dependências. Uma sprint pausada impede novos pedidos de execução ou retomada,
|
|
62
|
+
sem impedir cancelamento nem reconciliação de resultados terminais.
|
|
63
|
+
- **Contexto mais enxuto e qualidade mensurável.** Trechos FTS5, sincronização incremental e
|
|
64
|
+
orçamento no contexto de código reduzem conteúdo desnecessário. A documentação de comandos
|
|
65
|
+
é derivada do registro; o diagnóstico detecta divergências e a cobertura tem piso versionado.
|
|
66
|
+
- **Quem vem da 5.1.0 também recebe as melhorias descritas na seção 5.2.0:** checkpoints de
|
|
67
|
+
sessão, critérios de aceite ligados a testes, avaliação de agentes e isolamento da auditoria
|
|
68
|
+
durante a suíte de testes.
|
|
69
|
+
|
|
70
|
+
### Segurança e correções
|
|
71
|
+
|
|
72
|
+
- A autorização de capacidades usa categorias registradas pelo host, não a classificação
|
|
73
|
+
fornecida pelo cliente. A correção protege o caminho de execução supervisionada contra
|
|
74
|
+
autorização incorreta de operações de escrita.
|
|
75
|
+
- Aprovações ficam vinculadas à operação, entrada validada e escopo. Mudanças incompatíveis
|
|
76
|
+
com uma aprovação anterior exigem nova aprovação; evidências contraditórias não sustentam aceite.
|
|
77
|
+
- Falhas do CLI preservam o diagnóstico e não são convertidas em sucesso do runtime.
|
|
78
|
+
- Caminhos e leitura de documentos toleram diferenças de separadores e CRLF; a saída JSON
|
|
79
|
+
extensa não é truncada ao encerrar o processo.
|
|
80
|
+
|
|
81
|
+
### Uso e limites conhecidos
|
|
82
|
+
|
|
83
|
+
- Integrações que registram capacidades podem declarar `CapabilityRegistration.categories`;
|
|
84
|
+
quando ausente, a classificação usa `definition.permissions`. `categories` enviado numa
|
|
85
|
+
requisição não altera a autorização. Preserve as categorias específicas no registro do host.
|
|
86
|
+
- O servidor padrão continua somente leitura. Planejamento com escrita, revisão e conclusão
|
|
87
|
+
validada exigem política, revisor confiável e validator configurados na composição do host.
|
|
88
|
+
- O dashboard é opcional e operado a partir do checkout; a instalação npm continua CLI-first.
|
|
89
|
+
- Pausar uma sprint não interrompe um handler já em andamento nem torna atômicas pausas
|
|
90
|
+
concorrentes com um pedido de execução.
|
|
91
|
+
- O inventário Windows de runtime de agentes, `simulate` e jornada `spec:trace` permanece
|
|
92
|
+
aberto em `specs/v6-quality-gates/spec.md`; esta versão não declara portabilidade completa.
|
|
93
|
+
|
|
94
|
+
## [5.2.0] — 2026-10-22 — Memória de sessão, critérios ligados a testes e avaliação de agentes
|
|
95
|
+
|
|
96
|
+
### O que melhorou
|
|
97
|
+
|
|
98
|
+
- **A IA não perde o fio quando o contexto é compactado.** Em projetos conectados ao Claude Code, cada
|
|
99
|
+
sessão que muda alguma coisa deixa um checkpoint em `memory/60-runs/sessions/` (arquivos editados,
|
|
100
|
+
specs tocadas, comandos `forja`, commits), atualizado ao fim de cada turno e antes de compactar.
|
|
101
|
+
Depois da compactação o checkpoint volta para a IA; numa sessão nova, ela vê onde a anterior parou.
|
|
102
|
+
Nenhum texto de prompt nem comando inteiro entra na memória. Projetos existentes ganham os hooks com
|
|
103
|
+
`forja project:upgrade --apply` (SPEC-052, ADR-0091).
|
|
104
|
+
- **Dá para saber quais critérios de aceite têm teste.** `forja spec:trace` lista, para cada `AC-N`
|
|
105
|
+
de cada spec, os testes que o citam (`SPEC-NNN AC-N` no nome ou num comentário), os critérios sem
|
|
106
|
+
teste e as citações a critérios que não existem mais. `--strict` vira gate: spec aprovada ou pronta
|
|
107
|
+
com lacuna sai com 2. O `AGENTS.md` e a skill `testing` do projeto ensinam a convenção (SPEC-053,
|
|
108
|
+
ADR-0092). Fixture com citações de exemplo fica entre `spec-trace:off` e `spec-trace:on`. No
|
|
109
|
+
próprio Forja, 48 de 340 critérios têm teste citando — o ponto de partida.
|
|
110
|
+
- **Dá para medir se os agentes seguem o Forja.** `forja eval:agents --agent claude|codex` roda uma
|
|
111
|
+
suíte de tarefas (registrar decisão, começar feature, testar um critério, responder pela memória,
|
|
112
|
+
achar a próxima ação) com o agente real num projeto descartável, corrige pelo que ficou no disco e
|
|
113
|
+
guarda o histórico em `.context/agent-evals.jsonl`, comparando com a execução anterior. Custa uma
|
|
114
|
+
sessão real por caso: há teto de custo por caso no Claude e timeout nos dois (SPEC-054, ADR-0093).
|
|
115
|
+
|
|
116
|
+
### Corrigido
|
|
117
|
+
|
|
118
|
+
- **`npm test` não grava mais na sua trilha de auditoria.** Dois testes chamavam o CLI com o ambiente
|
|
119
|
+
do shell e deixavam entradas `spec:new` e `simulate --json` em `~/forja-workspace/.context/forja-runs.jsonl`
|
|
120
|
+
a cada execução da suíte. A suíte agora roda inteira com um workspace isolado
|
|
121
|
+
(`test/isolate-workspace.mjs`, pré-carregado pelo script `test`), e `test/test-isolation.test.js`
|
|
122
|
+
falha se o isolamento sair.
|
|
123
|
+
|
|
16
124
|
## [5.1.0] — 2026-10-21 — Skills, template de SaaS e mais agentes
|
|
17
125
|
|
|
18
126
|
### O que melhorou
|
package/README.md
CHANGED
|
@@ -98,7 +98,8 @@ process followed?", the answer is a file, not a promise.
|
|
|
98
98
|
- **Projects born connected to your AI** — `project:new` scaffolds a full project (memory, agents,
|
|
99
99
|
a NestJS backend as the default boilerplate) and wires it to the AI you use: native instructions
|
|
100
100
|
(`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), Claude Code hooks that open every session with the
|
|
101
|
-
project state
|
|
101
|
+
project state, attach the spec you mention and save a checkpoint of each session to memory
|
|
102
|
+
(returned to the AI after compaction), six role sub-agents, and the Forja MCP server in
|
|
102
103
|
Claude, Codex, Gemini and Copilot (VS Code). The
|
|
103
104
|
memory is indexed from the first minute. `project:wire --check` proves it; `project:upgrade --apply`
|
|
104
105
|
re-wires older projects without touching the user's code — or the whole workspace with `--all`
|
|
@@ -112,8 +113,10 @@ process followed?", the answer is a file, not a promise.
|
|
|
112
113
|
against the installed tarball, and fail if any command writes into the package itself.
|
|
113
114
|
- **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
|
|
114
115
|
(agent-team design), **ai-engineering** (knowledge base).
|
|
115
|
-
- **LLM Fit Loop** — adapters
|
|
116
|
-
|
|
116
|
+
- **LLM Fit Loop** — CLI adapters (Codex, Claude; Gemini, Copilot CLI, Cursor and opencode in
|
|
117
|
+
read-only mode), workspace profiles, no-cost probes, observations and deterministic recommendation
|
|
118
|
+
per role/task; credentials never enter Forja. `eval:agents` measures whether real agents follow the
|
|
119
|
+
Forja method on a task suite in a throwaway project (ADR-0093).
|
|
117
120
|
- **Engineering Control Plane** (v3.0, ADR-0078) — the Engineering Graph turns ADRs/SPECs into
|
|
118
121
|
first-class, queryable nodes; the Architecture Constitution checks real code against decisions
|
|
119
122
|
already recorded; the Change Risk Engine scores a change 0-100 with named, evidenced factors;
|
|
@@ -122,6 +125,31 @@ process followed?", the answer is a file, not a promise.
|
|
|
122
125
|
recommended agents, similar past incidents — before you start. Every score is information for a
|
|
123
126
|
human/policy rule to consult, never an autonomous decision on its own.
|
|
124
127
|
|
|
128
|
+
## What's new in 5.3.0
|
|
129
|
+
|
|
130
|
+
- **Read-only supervision dashboard:** overview, acceptance-criteria traceability, observed costs,
|
|
131
|
+
gates and operations share the server's capability registry. The optional dashboard runs from
|
|
132
|
+
this checkout and requires an access token; see the [demo guide](docs/produto/roteiro-demo.md).
|
|
133
|
+
Installing the npm package remains a CLI-first workflow.
|
|
134
|
+
- **Context-backed planning and linked execution:** server composition connects tasks, handoffs,
|
|
135
|
+
memory and budgets to persisted, reviewable proposals. Plan review does not authorize execution;
|
|
136
|
+
completion requires independent checks. The default server remains read-only: writable planning,
|
|
137
|
+
trusted review and validation require explicit host configuration.
|
|
138
|
+
- **Authorization belongs to the host:** registered capability categories determine policy, not
|
|
139
|
+
request-supplied categories. Custom registrations can set `CapabilityRegistration.categories`;
|
|
140
|
+
otherwise classification uses `definition.permissions`. Preserve custom categories in the host
|
|
141
|
+
registration rather than passing them only with execution requests.
|
|
142
|
+
- **Paused sprints reject new execute/resume requests** for linked runs, while cancellation and
|
|
143
|
+
terminal reconciliation remain available. This does not interrupt an in-flight handler or make
|
|
144
|
+
concurrent sprint changes atomic with dispatch.
|
|
145
|
+
- **Smaller context and measurable quality:** FTS5 snippets, incremental memory indexing, generated
|
|
146
|
+
command documentation and a versioned coverage floor. Upgrading from 5.1.0 also includes session
|
|
147
|
+
checkpoints, acceptance-criteria tracing and agent evaluations documented in the changelog.
|
|
148
|
+
|
|
149
|
+
Windows is fully supported since 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` and
|
|
150
|
+
`spec:trace` work without WSL. The CI matrix blocks on all three OSes.
|
|
151
|
+
Details and upgrade notes: [CHANGELOG](CHANGELOG.md).
|
|
152
|
+
|
|
125
153
|
## ⚡ Quick start
|
|
126
154
|
|
|
127
155
|
```bash
|
|
@@ -129,7 +157,10 @@ process followed?", the answer is a file, not a promise.
|
|
|
129
157
|
npm install -g forjajs
|
|
130
158
|
forja # help grouped by domain
|
|
131
159
|
|
|
132
|
-
#
|
|
160
|
+
# First run: creates the workspace and indexes the memory, confirming each step
|
|
161
|
+
forja setup # add --yes to accept every default
|
|
162
|
+
|
|
163
|
+
# Or prepare the production workspace by hand (the fixed home for your projects)
|
|
133
164
|
forja workspace:init
|
|
134
165
|
|
|
135
166
|
# Create a new project (generated in ~/forja-workspace/projects/<name>, already wired to your AI)
|
|
@@ -143,6 +174,7 @@ forja spec:new my-feature
|
|
|
143
174
|
forja spec:plan my-feature
|
|
144
175
|
forja spec:tasks my-feature
|
|
145
176
|
forja spec:check my-feature
|
|
177
|
+
forja spec:trace my-feature # AC-N criteria × tests that cite them (SPEC-NNN AC-N)
|
|
146
178
|
```
|
|
147
179
|
|
|
148
180
|
### Already have a repository?
|
|
@@ -408,6 +440,7 @@ The docs are written in **Brazilian Portuguese** — that's part of the project'
|
|
|
408
440
|
output, code, and ADRs are readable regardless of language.
|
|
409
441
|
|
|
410
442
|
- [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
|
|
443
|
+
- [`docs/commands.md`](docs/commands.md) — full command reference, generated from the registry (never hand-edited)
|
|
411
444
|
- [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
|
|
412
445
|
- [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
|
|
413
446
|
- [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
|
|
@@ -429,6 +462,21 @@ output, code, and ADRs are readable regardless of language.
|
|
|
429
462
|
The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
|
|
430
463
|
below either closes a framework frontier with a gate, or carries that pattern into generated projects.
|
|
431
464
|
|
|
465
|
+
**Shipped** (v5.3.0 — Supervised execution)
|
|
466
|
+
|
|
467
|
+
- [x] **Read-only supervision dashboard** — overview, acceptance-criteria traceability, observed
|
|
468
|
+
costs, gates and operations share the server's capability registry; optional, token-gated,
|
|
469
|
+
runs from the checkout (CLI-first install unchanged).
|
|
470
|
+
- [x] **Context-backed planning & linked execution** — tasks, handoffs, memory and budgets connect
|
|
471
|
+
to persisted, reviewable proposals; plan review does not authorize execution; completion requires
|
|
472
|
+
independent checks. Default server remains read-only.
|
|
473
|
+
- [x] **Host-owned authorization** — registered capability categories determine policy, not
|
|
474
|
+
request-supplied categories; custom registrations declare `CapabilityRegistration.categories`.
|
|
475
|
+
- [x] **Paused-sprint guards** — linked runs reject execute/resume while the sprint is paused;
|
|
476
|
+
cancellation and terminal reconciliation remain available.
|
|
477
|
+
- [x] **Compact context & measurable quality** — FTS5 snippets, incremental memory indexing,
|
|
478
|
+
generated command documentation and a versioned coverage floor.
|
|
479
|
+
|
|
432
480
|
**Shipped** (v3.0.0 — Engineering Control Plane, ADR-0078)
|
|
433
481
|
|
|
434
482
|
- [x] **Engineering Graph** — ADRs/SPECs as first-class, queryable nodes (`adr:list/show/impact/graph`),
|
package/README.pt-BR.md
CHANGED
|
@@ -85,13 +85,38 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
85
85
|
- **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
|
|
86
86
|
- **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
|
|
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
|
-
- **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto
|
|
88
|
+
- **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto, anexam a spec citada no prompt e gravam um checkpoint de cada sessão na memória (devolvido à IA depois da compactação), seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
|
|
89
89
|
- **Templates validados** — `project:new <nome> --template clean-arch` (DDD) ou `--template saas-starter` (SaaS multi-tenant com assinatura e faturamento) parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
|
|
90
|
-
- **LLM Fit Loop** — `llm:run` executa tarefas supervisionadas por CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), com perfis no workspace, probes sem custo, observações e recomendação por papel/tarefa; credenciais nunca entram no Forja (ADR-0090).
|
|
90
|
+
- **LLM Fit Loop** — `llm:run` executa tarefas supervisionadas por CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), com perfis no workspace, probes sem custo, observações e recomendação por papel/tarefa; credenciais nunca entram no Forja (ADR-0090). `eval:agents` mede se agentes reais seguem o método do Forja numa suíte de tarefas em projeto descartável (ADR-0093).
|
|
91
91
|
- **A jornada do usuário é gate** — `npm test` e `release:check` percorrem a jornada inteira (workspace → projeto → memória, contexto, specs, hooks, MCP e handoffs dentro do projeto), contra o fonte e contra o pacote instalado, e reprovam se algum comando escrever dentro do pacote.
|
|
92
92
|
- **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
|
|
93
93
|
- **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ó.
|
|
94
94
|
|
|
95
|
+
## Novidades da 5.3.0
|
|
96
|
+
|
|
97
|
+
- **Painel de supervisão somente leitura:** visão, rastreabilidade de critérios, custos observados,
|
|
98
|
+
gates e operação usam o registro de capacidades do servidor. O dashboard opcional roda pelo
|
|
99
|
+
checkout e exige token de acesso; veja o [roteiro de demonstração](docs/produto/roteiro-demo.md).
|
|
100
|
+
A instalação do pacote npm continua CLI-first.
|
|
101
|
+
- **Planejamento com contexto e execução vinculada:** a composição do servidor conecta tarefas,
|
|
102
|
+
handoffs, memória e orçamento a propostas persistidas e revisáveis. Revisar um plano não autoriza
|
|
103
|
+
execução; concluir exige checks independentes. O servidor padrão continua somente leitura:
|
|
104
|
+
planejamento com escrita, revisão confiável e validação exigem configuração explícita do host.
|
|
105
|
+
- **A autorização pertence ao host:** as categorias registradas da capacidade determinam a
|
|
106
|
+
política, não as categorias enviadas na requisição. Registros próprios podem declarar
|
|
107
|
+
`CapabilityRegistration.categories`; na ausência, a classificação usa `definition.permissions`.
|
|
108
|
+
Preserve categorias próprias no registro do host, em vez de enviá-las só nos pedidos de execução.
|
|
109
|
+
- **Sprint pausada recusa novos pedidos de execução e retomada** de runs vinculados, preservando
|
|
110
|
+
cancelamento e reconciliação terminal. Isso não interrompe um handler em andamento nem torna
|
|
111
|
+
atômicas as mudanças concorrentes na sprint e o disparo de execução.
|
|
112
|
+
- **Contexto menor e qualidade mensurável:** trechos FTS5, indexação incremental de memória,
|
|
113
|
+
documentação de comandos gerada e piso de cobertura versionado. Quem atualiza da 5.1.0 também
|
|
114
|
+
recebe checkpoints de sessão, rastreabilidade de critérios e avaliação de agentes descritos no changelog.
|
|
115
|
+
|
|
116
|
+
O Windows é suportado desde a 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` e
|
|
117
|
+
`spec:trace` funcionam sem WSL. O CI bloqueia nos três SOs.
|
|
118
|
+
Detalhes e notas de atualização: [CHANGELOG](CHANGELOG.md).
|
|
119
|
+
|
|
95
120
|
## ⚡ Quick start
|
|
96
121
|
|
|
97
122
|
```bash
|
|
@@ -99,7 +124,10 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
99
124
|
npm install -g forjajs
|
|
100
125
|
forja # help agrupado por domínio
|
|
101
126
|
|
|
102
|
-
#
|
|
127
|
+
# Primeiro uso: cria o workspace e indexa a memória, confirmando cada passo
|
|
128
|
+
forja setup # com --yes aceita todos os padrões
|
|
129
|
+
|
|
130
|
+
# Ou preparar o workspace de produção à mão (canto fixo dos projetos)
|
|
103
131
|
forja workspace:init
|
|
104
132
|
|
|
105
133
|
# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>, já conectado à sua IA)
|
|
@@ -113,6 +141,7 @@ forja spec:new minha-feature
|
|
|
113
141
|
forja spec:plan minha-feature
|
|
114
142
|
forja spec:tasks minha-feature
|
|
115
143
|
forja spec:check minha-feature
|
|
144
|
+
forja spec:trace minha-feature # critérios AC-N × testes que os citam (SPEC-NNN AC-N)
|
|
116
145
|
```
|
|
117
146
|
|
|
118
147
|
### Já tem um repositório?
|
|
@@ -203,6 +232,11 @@ Os scripts npm do repo são aliases finos que roteiam pelo core.
|
|
|
203
232
|
## Comandos essenciais
|
|
204
233
|
|
|
205
234
|
```bash
|
|
235
|
+
# Orientação — o caminho feliz
|
|
236
|
+
forja status # onde estou: workspace, sprint, specs, runs, handoffs
|
|
237
|
+
forja next # o que agora: uma linha — a próxima ação + o comando exato
|
|
238
|
+
forja help [<comando>|--all] # os essenciais, ou uso/args/exemplos de um comando
|
|
239
|
+
|
|
206
240
|
# Workspace & projetos
|
|
207
241
|
forja workspace:init # cria ~/forja-workspace
|
|
208
242
|
forja project:new <nome> --ai claude,copilot # cria projeto no workspace, conectado à IA
|
|
@@ -213,7 +247,7 @@ forja project:list # lista projetos do workspace
|
|
|
213
247
|
forja workspace:project:check <nome> # valida padrões num projeto do workspace
|
|
214
248
|
|
|
215
249
|
# Pipeline SDD
|
|
216
|
-
forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
|
|
250
|
+
forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check · spec:trace
|
|
217
251
|
|
|
218
252
|
# Sprint & handoffs (GSD)
|
|
219
253
|
forja sprint:start # também: sprint:status · sprint:complete
|
|
@@ -324,6 +358,7 @@ A parte gerenciada pelo Forja em cada arquivo de instrução fica entre `<!-- fo
|
|
|
324
358
|
## Documentação
|
|
325
359
|
|
|
326
360
|
- [`DOC-MAP.md`](DOC-MAP.md) — mapa por papel e por tópico (comece aqui)
|
|
361
|
+
- [`docs/commands.md`](docs/commands.md) — referência completa de comandos, gerada do registry (nunca editada à mão)
|
|
327
362
|
- [`docs/processo-projeto.md`](docs/processo-projeto.md) — criar vs atualizar projeto
|
|
328
363
|
- [`docs/fluxo.md`](docs/fluxo.md) — mapa do ciclo CLI-first
|
|
329
364
|
- [`AGENTS.md`](AGENTS.md) — os 6 papéis e a topologia
|
|
@@ -346,6 +381,21 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
|
|
|
346
381
|
item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
|
|
347
382
|
gerados.
|
|
348
383
|
|
|
384
|
+
**Entregue** (v5.3.0 — Execução supervisionada)
|
|
385
|
+
|
|
386
|
+
- [x] **Painel de supervisão somente leitura** — visão, rastreabilidade de critérios, custos
|
|
387
|
+
observados, gates e operação usam o registro de capacidades do servidor; opcional, com token,
|
|
388
|
+
roda pelo checkout (instalação CLI-first inalterada).
|
|
389
|
+
- [x] **Planejamento com contexto e execução vinculada** — tarefas, handoffs, memória e orçamento
|
|
390
|
+
conectam-se a propostas persistidas e revisáveis; revisar plano não autoriza execução; concluir
|
|
391
|
+
exige checks independentes. Servidor padrão continua somente leitura.
|
|
392
|
+
- [x] **Autorização pertence ao host** — categorias registradas da capacidade determinam a política,
|
|
393
|
+
não as categorias da requisição; registros próprios declaram `CapabilityRegistration.categories`.
|
|
394
|
+
- [x] **Guardas de sprint pausada** — runs vinculados recusam execute/resume com a sprint pausada;
|
|
395
|
+
cancelamento e reconciliação terminal permanecem disponíveis.
|
|
396
|
+
- [x] **Contexto compacto e qualidade mensurável** — trechos FTS5, indexação incremental de memória,
|
|
397
|
+
documentação de comandos gerada e piso de cobertura versionado.
|
|
398
|
+
|
|
349
399
|
**Entregue** (v3.0.0 — Engineering Control Plane, ADR-0078)
|
|
350
400
|
|
|
351
401
|
- [x] **Engineering Graph** — ADRs/SPECs como nós de primeira classe consultáveis
|
|
@@ -57,5 +57,4 @@ export declare function parseLegacyCommandInput(command: string, args: readonly
|
|
|
57
57
|
readonly payload: InputRecord;
|
|
58
58
|
};
|
|
59
59
|
export declare function executeCliCapability(runtime: CliCapabilityRuntime, capabilityId: CapabilityId, payload: unknown, correlationId?: string): Promise<ExecutionResult>;
|
|
60
|
-
export declare function normalizeCliResult(result: ExecutionResult): ExecutionResult;
|
|
61
60
|
export {};
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto';
|
|
2
2
|
import { spawnSync } from 'node:child_process';
|
|
3
3
|
import { CONTRACT_VERSION, } from '../../../packages/contracts/src/index.js';
|
|
4
|
-
import { CapabilityRegistry, } from '../../../packages/core/src/index.js';
|
|
4
|
+
import { CapabilityRegistry, CapabilityExecutionFailure, } from '../../../packages/core/src/index.js';
|
|
5
5
|
import { PolicyEngine } from '../../../packages/policy/src/index.js';
|
|
6
6
|
import { COMMANDS, resolveScript } from '../../../lib/core/registry.js';
|
|
7
7
|
import { GraphIndexer } from '../../../packages/graph/src/index.js';
|
|
@@ -28,8 +28,7 @@ export const CLI_CAPABILITY_SPECS = [
|
|
|
28
28
|
permissions: ['read'],
|
|
29
29
|
risk: 'low',
|
|
30
30
|
sideEffects: [],
|
|
31
|
-
params: [],
|
|
32
|
-
validateInput: emptyInput,
|
|
31
|
+
params: [{ name: 'json', kind: 'flag' }],
|
|
33
32
|
},
|
|
34
33
|
{
|
|
35
34
|
id: 'code.impact',
|
|
@@ -130,14 +129,20 @@ export const CLI_CAPABILITY_SPECS = [
|
|
|
130
129
|
{
|
|
131
130
|
id: 'code.context',
|
|
132
131
|
command: 'code:context',
|
|
133
|
-
description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code).',
|
|
132
|
+
description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code, fatia inteira com --full).',
|
|
134
133
|
categories: ['read'],
|
|
135
134
|
permissions: ['read'],
|
|
136
135
|
risk: 'low',
|
|
137
136
|
sideEffects: [],
|
|
137
|
+
// Cada flag que `usage` anuncia tem que estar aqui: o roteador rebuilda o argv a partir destes
|
|
138
|
+
// params, e o que não é declarado é descartado em silêncio — `--full` existir no help e não chegar
|
|
139
|
+
// ao script é o pior tipo de flag (o usuário jura que pediu).
|
|
138
140
|
params: [
|
|
139
141
|
{ name: 'domain', kind: 'positional' },
|
|
142
|
+
{ name: 'query', kind: 'positional' },
|
|
140
143
|
{ name: 'code', kind: 'flag' },
|
|
144
|
+
{ name: 'full', kind: 'flag' },
|
|
145
|
+
{ name: 'project', kind: 'flag-value', flag: '--project' },
|
|
141
146
|
],
|
|
142
147
|
},
|
|
143
148
|
{
|
|
@@ -218,7 +223,7 @@ export const CLI_CAPABILITY_SPECS = [
|
|
|
218
223
|
permissions: ['read'],
|
|
219
224
|
risk: 'low',
|
|
220
225
|
sideEffects: [],
|
|
221
|
-
params: [],
|
|
226
|
+
params: [{ name: 'json', kind: 'flag' }],
|
|
222
227
|
},
|
|
223
228
|
{
|
|
224
229
|
id: 'forja.next',
|
|
@@ -228,7 +233,32 @@ export const CLI_CAPABILITY_SPECS = [
|
|
|
228
233
|
permissions: ['read'],
|
|
229
234
|
risk: 'low',
|
|
230
235
|
sideEffects: [],
|
|
231
|
-
params: [],
|
|
236
|
+
params: [{ name: 'json', kind: 'flag' }],
|
|
237
|
+
},
|
|
238
|
+
// --- SPEC-057: os dois relatórios read-only que só existiam como script (dashboard/MCP) ---
|
|
239
|
+
{
|
|
240
|
+
id: 'spec.trace',
|
|
241
|
+
command: 'spec:trace',
|
|
242
|
+
description: 'Critérios de aceite × testes que os citam: cobertos, sem teste e órfãos.',
|
|
243
|
+
categories: ['read'],
|
|
244
|
+
permissions: ['read'],
|
|
245
|
+
risk: 'low',
|
|
246
|
+
sideEffects: [],
|
|
247
|
+
params: [
|
|
248
|
+
{ name: 'slug', kind: 'positional' },
|
|
249
|
+
{ name: 'strict', kind: 'flag' },
|
|
250
|
+
{ name: 'json', kind: 'flag' },
|
|
251
|
+
],
|
|
252
|
+
},
|
|
253
|
+
{
|
|
254
|
+
id: 'cost.economy',
|
|
255
|
+
command: 'cost:economy',
|
|
256
|
+
description: 'Custo real acumulado (USD) das execuções LLM registradas, por modelo.',
|
|
257
|
+
categories: ['read', 'database'],
|
|
258
|
+
permissions: ['read'],
|
|
259
|
+
risk: 'low',
|
|
260
|
+
sideEffects: [],
|
|
261
|
+
params: [{ name: 'json', kind: 'flag' }],
|
|
232
262
|
},
|
|
233
263
|
];
|
|
234
264
|
export const CLI_COMMAND_TO_CAPABILITY = Object.freeze(Object.fromEntries(CLI_CAPABILITY_SPECS.map((spec) => [spec.command, spec.id])));
|
|
@@ -298,7 +328,7 @@ export function parseLegacyCommandInput(command, args) {
|
|
|
298
328
|
export async function executeCliCapability(runtime, capabilityId, payload, correlationId) {
|
|
299
329
|
const definition = runtime.registry.describe(capabilityId);
|
|
300
330
|
const categories = categoriesFor(definition.id);
|
|
301
|
-
|
|
331
|
+
return runtime.registry.execute({
|
|
302
332
|
input: { capabilityId, payload },
|
|
303
333
|
agent: runtime.agent,
|
|
304
334
|
policy: runtime.policy,
|
|
@@ -307,23 +337,6 @@ export async function executeCliCapability(runtime, capabilityId, payload, corre
|
|
|
307
337
|
categories,
|
|
308
338
|
files: [],
|
|
309
339
|
});
|
|
310
|
-
return normalizeCliResult(result);
|
|
311
|
-
}
|
|
312
|
-
export function normalizeCliResult(result) {
|
|
313
|
-
if (result.status !== 'succeeded' || result.output === undefined || !isRecord(result.output.payload))
|
|
314
|
-
return result;
|
|
315
|
-
const exitCode = result.output.payload.exitCode;
|
|
316
|
-
if (typeof exitCode !== 'number' || exitCode === 0)
|
|
317
|
-
return result;
|
|
318
|
-
return {
|
|
319
|
-
...result,
|
|
320
|
-
status: 'failed',
|
|
321
|
-
error: {
|
|
322
|
-
code: 'LEGACY_COMMAND_FAILED',
|
|
323
|
-
message: `Legacy command exited with status ${exitCode}`,
|
|
324
|
-
retryable: false,
|
|
325
|
-
},
|
|
326
|
-
};
|
|
327
340
|
}
|
|
328
341
|
function registerCliCapability(registry, runner, spec) {
|
|
329
342
|
const now = new Date().toISOString();
|
|
@@ -347,6 +360,7 @@ function registerCliCapability(registry, runner, spec) {
|
|
|
347
360
|
};
|
|
348
361
|
const registration = {
|
|
349
362
|
definition,
|
|
363
|
+
categories: spec.categories,
|
|
350
364
|
validateInput: spec.validateInput ?? makeValidator(spec.params),
|
|
351
365
|
validateOutput: validateCliPayload,
|
|
352
366
|
handler: async (input) => {
|
|
@@ -360,11 +374,15 @@ function registerCliCapability(registry, runner, spec) {
|
|
|
360
374
|
capturedAt,
|
|
361
375
|
status: result.exitCode === 0 ? 'verified' : 'contradicted',
|
|
362
376
|
};
|
|
363
|
-
|
|
377
|
+
const output = {
|
|
364
378
|
capabilityId: spec.id,
|
|
365
379
|
payload: { command: spec.command, args, ...result },
|
|
366
380
|
evidence: [evidence],
|
|
367
381
|
};
|
|
382
|
+
if (result.exitCode !== 0) {
|
|
383
|
+
throw new CapabilityExecutionFailure({ code: 'LEGACY_COMMAND_FAILED', message: `Legacy command exited with status ${result.exitCode}`, retryable: false }, output);
|
|
384
|
+
}
|
|
385
|
+
return output;
|
|
368
386
|
},
|
|
369
387
|
};
|
|
370
388
|
registry.register(registration);
|
|
@@ -372,13 +390,6 @@ function registerCliCapability(registry, runner, spec) {
|
|
|
372
390
|
function categoriesFor(id) {
|
|
373
391
|
return CLI_CAPABILITY_SPECS.find((spec) => spec.id === id)?.categories ?? ['read'];
|
|
374
392
|
}
|
|
375
|
-
function emptyInput(value) {
|
|
376
|
-
if (value === undefined || value === null)
|
|
377
|
-
return {};
|
|
378
|
-
if (!isRecord(value) || Object.keys(value).length > 0)
|
|
379
|
-
throw new Error('Input must be an empty object');
|
|
380
|
-
return {};
|
|
381
|
-
}
|
|
382
393
|
function validateCodeImpactInput(value) {
|
|
383
394
|
const input = requireRecord(value);
|
|
384
395
|
const symbol = input.symbol;
|
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
import { buildApprovalDecisionBody } from '../approval';
|
|
3
3
|
// @ts-expect-error Next resolves the adjacent TypeScript helper.
|
|
4
4
|
import { isCallerAuthorized, matchesAllowedPrefix } from '../guard';
|
|
5
|
-
|
|
5
|
+
// @ts-expect-error Next resolves the adjacent TypeScript helper.
|
|
6
|
+
import { capabilityIdFromExecutePath, isReadOnlyCapability } from '../capabilities';
|
|
7
|
+
const allowedPrefixes = ['/control-plane/metrics', '/observability/observations', '/events', '/executions/', '/graph/query', '/graph/impact', '/approvals', '/capabilities'];
|
|
6
8
|
export async function GET(request, context) { return forward(request, await context.params, 'GET'); }
|
|
7
9
|
export async function POST(request, context) { return forward(request, await context.params, 'POST'); }
|
|
8
10
|
async function forward(request, params, method) {
|
|
@@ -16,6 +18,19 @@ async function forward(request, params, method) {
|
|
|
16
18
|
return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: 'Dashboard route is not allowed' } }), { status: 403, headers: { 'content-type': 'application/json' } });
|
|
17
19
|
const backend = process.env.FORJA_API_URL ?? 'http://localhost:3000';
|
|
18
20
|
const token = process.env.FORJA_API_TOKEN;
|
|
21
|
+
// ADR-0022, condição de retomada #2: o que o painel alcança é derivado do que o servidor declara,
|
|
22
|
+
// nunca de uma lista escrita à mão aqui. O dashboard anterior mantinha allowlist própria e por ela
|
|
23
|
+
// rodava comando que não passava pelos gates nem aparecia na auditoria; este portão existe para
|
|
24
|
+
// que executar pela UI seja o mesmo caminho auditado de sempre, e só para capacidades que não
|
|
25
|
+
// escrevem. Falha fechada: catálogo que não responde é 403, não é liberado.
|
|
26
|
+
if (method === 'POST') {
|
|
27
|
+
const capabilityId = capabilityIdFromExecutePath(path);
|
|
28
|
+
if (capabilityId !== null) {
|
|
29
|
+
const surface = await readCapabilitySurface(`${backend}/api/capabilities`, token, capabilityId);
|
|
30
|
+
if (surface === null || !isReadOnlyCapability(surface))
|
|
31
|
+
return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: `Capability is not read-only: ${capabilityId}` } }), { status: 403, headers: { 'content-type': 'application/json' } });
|
|
32
|
+
}
|
|
33
|
+
}
|
|
19
34
|
const headers = new Headers({ accept: request.headers.get('accept') ?? 'application/json' });
|
|
20
35
|
if (token !== undefined)
|
|
21
36
|
headers.set('authorization', `Bearer ${token}`);
|
|
@@ -41,3 +56,21 @@ async function forward(request, params, method) {
|
|
|
41
56
|
responseHeaders.set('cache-control', cacheControl);
|
|
42
57
|
return new Response(response.body, { status: response.status, headers: responseHeaders });
|
|
43
58
|
}
|
|
59
|
+
/** A definição que o servidor declara para a capacidade, ou null quando o catálogo não responde. */
|
|
60
|
+
async function readCapabilitySurface(catalogUrl, token, id) {
|
|
61
|
+
const headers = new Headers({ accept: 'application/json' });
|
|
62
|
+
if (token !== undefined)
|
|
63
|
+
headers.set('authorization', `Bearer ${token}`);
|
|
64
|
+
try {
|
|
65
|
+
const catalog = await fetch(catalogUrl, { headers, cache: 'no-store' });
|
|
66
|
+
if (!catalog.ok)
|
|
67
|
+
return null;
|
|
68
|
+
const definitions = await catalog.json();
|
|
69
|
+
if (!Array.isArray(definitions))
|
|
70
|
+
return null;
|
|
71
|
+
return definitions.find((definition) => definition.id === id) ?? null;
|
|
72
|
+
}
|
|
73
|
+
catch {
|
|
74
|
+
return null;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure helpers backing the dashboard's read-only capability access, same pattern as `guard.ts`
|
|
3
|
+
* and `approval.ts`: no Next types in here, so the rules are unit-testable directly.
|
|
4
|
+
*
|
|
5
|
+
* ADR-0022 congelou o dashboard anterior porque ele mantinha uma allowlist de comandos própria,
|
|
6
|
+
* paralela ao registry — e nela existia comando que o registry não tinha, executado por fora dos
|
|
7
|
+
* gates e da trilha de auditoria. A condição de retomada #2 era derivar a exposição do registry.
|
|
8
|
+
* Aqui não há lista: o que o painel pode executar é decidido pelo que o próprio servidor declara
|
|
9
|
+
* em `/api/capabilities`, filtrado pela regra abaixo.
|
|
10
|
+
*/
|
|
11
|
+
/** O mínimo de uma `CapabilityDefinition` (packages/contracts) que a regra precisa. */
|
|
12
|
+
export interface CapabilitySurface {
|
|
13
|
+
readonly id: string;
|
|
14
|
+
readonly permissions: readonly string[];
|
|
15
|
+
readonly sideEffects: readonly string[];
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Read-only de verdade: sem permissão de escrita e sem efeito colateral declarado. `risk` não
|
|
19
|
+
* entra na regra porque é julgamento do autor da capacidade, não um fato sobre o que ela toca —
|
|
20
|
+
* `context.budget` é risk low e ainda assim grava `context_run_record`. Definição que não declara
|
|
21
|
+
* os dois campos é recusada: o portão falha fechado, não por falta de evidência de que escreve.
|
|
22
|
+
*/
|
|
23
|
+
export declare function isReadOnlyCapability(capability: CapabilitySurface | null): boolean;
|
|
24
|
+
/** `/capabilities/spec.validate/execute` → `spec.validate`; qualquer outra forma → null. */
|
|
25
|
+
export declare function capabilityIdFromExecutePath(pathname: string): string | null;
|
|
26
|
+
export declare function isCapabilityListPath(pathname: string): boolean;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure helpers backing the dashboard's read-only capability access, same pattern as `guard.ts`
|
|
3
|
+
* and `approval.ts`: no Next types in here, so the rules are unit-testable directly.
|
|
4
|
+
*
|
|
5
|
+
* ADR-0022 congelou o dashboard anterior porque ele mantinha uma allowlist de comandos própria,
|
|
6
|
+
* paralela ao registry — e nela existia comando que o registry não tinha, executado por fora dos
|
|
7
|
+
* gates e da trilha de auditoria. A condição de retomada #2 era derivar a exposição do registry.
|
|
8
|
+
* Aqui não há lista: o que o painel pode executar é decidido pelo que o próprio servidor declara
|
|
9
|
+
* em `/api/capabilities`, filtrado pela regra abaixo.
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Read-only de verdade: sem permissão de escrita e sem efeito colateral declarado. `risk` não
|
|
13
|
+
* entra na regra porque é julgamento do autor da capacidade, não um fato sobre o que ela toca —
|
|
14
|
+
* `context.budget` é risk low e ainda assim grava `context_run_record`. Definição que não declara
|
|
15
|
+
* os dois campos é recusada: o portão falha fechado, não por falta de evidência de que escreve.
|
|
16
|
+
*/
|
|
17
|
+
export function isReadOnlyCapability(capability) {
|
|
18
|
+
if (capability === null)
|
|
19
|
+
return false;
|
|
20
|
+
if (!Array.isArray(capability.permissions) || !Array.isArray(capability.sideEffects))
|
|
21
|
+
return false;
|
|
22
|
+
if (capability.permissions.includes('write'))
|
|
23
|
+
return false;
|
|
24
|
+
return capability.sideEffects.length === 0;
|
|
25
|
+
}
|
|
26
|
+
/** `/capabilities/spec.validate/execute` → `spec.validate`; qualquer outra forma → null. */
|
|
27
|
+
export function capabilityIdFromExecutePath(pathname) {
|
|
28
|
+
const prefix = '/capabilities/';
|
|
29
|
+
const suffix = '/execute';
|
|
30
|
+
if (!pathname.startsWith(prefix) || !pathname.endsWith(suffix))
|
|
31
|
+
return null;
|
|
32
|
+
const id = pathname.slice(prefix.length, -suffix.length);
|
|
33
|
+
if (id.length === 0 || id.includes('/'))
|
|
34
|
+
return null;
|
|
35
|
+
return id;
|
|
36
|
+
}
|
|
37
|
+
export function isCapabilityListPath(pathname) {
|
|
38
|
+
return pathname === '/capabilities';
|
|
39
|
+
}
|