forjajs 2.0.2 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +22 -0
  2. package/README.pt-BR.md +22 -0
  3. package/dist/apps/server/src/main.d.ts +3 -2
  4. package/dist/apps/server/src/main.js +8 -6
  5. package/dist/bin/forja.js +8 -3
  6. package/dist/lib/core/registry.d.ts +10 -0
  7. package/dist/lib/core/registry.js +10 -0
  8. package/dist/lib/core/release.d.ts +10 -0
  9. package/dist/packages/adapter-git/src/index.d.ts +2 -0
  10. package/dist/packages/adapter-git/src/index.js +22 -1
  11. package/dist/packages/contracts/src/index.d.ts +1 -1
  12. package/dist/packages/plugin-docker/src/index.d.ts +3 -0
  13. package/dist/packages/plugin-docker/src/index.js +13 -0
  14. package/dist/packages/plugin-github/src/index.d.ts +3 -0
  15. package/dist/packages/plugin-github/src/index.js +13 -0
  16. package/dist/packages/sandbox/src/index.d.ts +2 -0
  17. package/dist/packages/sandbox/src/index.js +10 -0
  18. package/dist/scripts/context-benchmark.d.ts +2 -0
  19. package/dist/scripts/context-benchmark.js +39 -0
  20. package/dist/scripts/demo-autonomy.d.ts +15 -0
  21. package/dist/scripts/demo-autonomy.js +200 -0
  22. package/dist/scripts/server-persistence-probe.d.mts +1 -0
  23. package/dist/scripts/server-persistence-probe.d.ts +1 -0
  24. package/dist/scripts/server-persistence-probe.js +52 -0
  25. package/dist/scripts/server-persistence-probe.mjs +52 -0
  26. package/docs/2x/IMPLEMENTATION-AUDIT.md +36 -128
  27. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -0
  28. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -0
  29. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -0
  30. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -0
  31. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -0
  32. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -0
  33. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -0
  34. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -0
  35. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -0
  36. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -0
  37. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -0
  38. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -0
  39. package/memory/90-decisions/0071-server-persistence-composition.md +12 -0
  40. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -0
  41. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -0
  42. package/package.json +13 -3
@@ -0,0 +1,25 @@
1
+ # Sprint 16 — Última milha verificável
2
+
3
+ ## Objetivo
4
+
5
+ Fechar três lacunas objetivas da avaliação 10/10 sem criar novos módulos: rollback explícito do sandbox, benchmark reproduzível de contexto e plugins oficiais permissionados.
6
+
7
+ ## Escopo
8
+
9
+ - `promoted → rolled_back` no contrato e no `SandboxEngine`;
10
+ - reversão de patch real no `GitWorktreeBackend`;
11
+ - benchmark JSON determinístico em `npm run benchmark:context`;
12
+ - manifests oficiais `@forja/plugin-github` e `@forja/plugin-docker`;
13
+ - testes de contrato, rollback, benchmark e isolamento de permissões.
14
+
15
+ ## Critérios de aceite
16
+
17
+ - rollback rejeita sessão que não foi promovida;
18
+ - Git recebe o patch reverso antes da limpeza da worktree;
19
+ - benchmark mede baseline, contexto selecionado, checksum, cache hit e economia;
20
+ - plugins são descobertos pelo `PluginRegistry` e não acessam serviços sem permissão;
21
+ - `npm test -- --test-concurrency=1`, build e `git diff --check` passam.
22
+
23
+ ## Fora do escopo
24
+
25
+ Integrações de rede com GitHub, execução de Docker e rollback automático de qualquer comando externo. Esses handlers dependem de adapters do host e continuam governados pelo Policy Engine.
@@ -0,0 +1,16 @@
1
+ # Handoff — Sprint 12: autonomia real
2
+
3
+ - **from:** autonomy-integration-engineer
4
+ - **to:** mcp-and-recovery-engineer
5
+ - **intent:** continuar a prova de última milha do ForjaJS 2.x
6
+ - **context:** `scripts/demo-autonomy.ts`, `test/demo-autonomy.test.js`,
7
+ `docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md`, ADR-0069
8
+ - **acceptance:** demo cria fixture externa, usa worktree Git real, bloqueia escrita
9
+ até aprovação, edita arquivo, executa npm test, valida, promove diff, persiste
10
+ estado, atualiza GraphLoop e cria handoff
11
+ - **constraints:** sem LLM; sem mocks no caminho principal; escopo limitado ao
12
+ arquivo `tests/math.test.js`; promoção somente após Validator `accepted`
13
+ - **return:** implementar Sprint 13 para transporte MCP stdio real e shutdown limpo;
14
+ depois provar restart do servidor e recuperação de execução/approval/contexto
15
+ - **evidence:** `npm run demo:autonomy` retornou `accepted`, uma alteração promovida,
16
+ 18 nós e 14 arestas; teste automatizado repete e limpa a fixture
@@ -0,0 +1,14 @@
1
+ # Handoff — Sprint 13: MCP stdio real
2
+
3
+ - **from:** autonomy-integration-engineer
4
+ - **to:** persistence-chaos-engineer
5
+ - **intent:** continuar a prova de última milha do ForjaJS 2.x
6
+ - **context:** `bin/forja.ts`, `test/mcp-stdio.test.js`, Sprint 13, ADR-0070
7
+ - **acceptance:** cliente filho inicia MCP real, negocia initialize, lista tools,
8
+ descreve e executa capability, lê resource e encerra por EOF sem ruído em stdout
9
+ - **constraints:** stdio newline-delimited JSON-RPC; notificações não recebem resposta;
10
+ nenhuma regra de negócio nova no transporte
11
+ - **return:** provar restart abrupto do servidor e retomada de runtime/approval/contexto
12
+ com SQLite; adicionar casos de desconexão e payload inválido
13
+ - **evidence:** teste de processo real aprovado; stdout parseável; stderr vazio;
14
+ shutdown exit code 0
@@ -0,0 +1,15 @@
1
+ # Handoff — Sprint 14: persistência oficial e restart
2
+
3
+ - **from:** persistence-composition-engineer
4
+ - **to:** chaos-and-security-engineer
5
+ - **intent:** continuar o fechamento 10/10 com falhas e recuperação
6
+ - **context:** `apps/server/src/main.ts`, `test/server-persistence.test.js`, Sprint 14,
7
+ ADR-0071
8
+ - **acceptance:** duas composições oficiais compartilham SQLite; runtime e approval
9
+ pendente são recuperados; contexto, grafo, eventos e observações permanecem
10
+ - **constraints:** stores em memória apenas para testes; adapter SQLite permanece fora
11
+ do domínio; probe executa com loader Nest real
12
+ - **return:** adicionar processo morto, approval expirada, SQLite bloqueado,
13
+ checkpoint corrompido, timeout e payload malicioso; registrar rollback e recuperação
14
+ - **evidence:** probe passou com run `awaiting_approval`, approval 1, contexto
15
+ preservado, grafo 1 nó, eventos e observações persistidos
@@ -0,0 +1,13 @@
1
+ # Handoff — Sprint 15: caos e segurança
2
+
3
+ - **from:** chaos-and-security-engineer
4
+ - **to:** release-hardening-engineer
5
+ - **intent:** fechar os casos de falha restantes antes do próximo release
6
+ - **context:** adapter Git, policy, SQLite, MCP stdio, Sprint 15, ADR-0072
7
+ - **acceptance:** approval expirada, payload corrompido, deny-by-default,
8
+ path traversal e herança de secrets têm comportamento determinístico e testado
9
+ - **constraints:** sem mascarar corrupção; sem secrets no ambiente padrão do sandbox;
10
+ nenhuma leitura fora da raiz; alterações críticas continuam sob Policy Engine
11
+ - **return:** implementar SQLite lock/timeout, processo morto no meio do step,
12
+ checkpoint rollback, fuzz MCP, plugins maliciosos e threat model formal
13
+ - **evidence:** testes de chaos/security e 291+ testes de integração existentes
@@ -0,0 +1,11 @@
1
+ # Handoff — Sprint 16: última milha
2
+
3
+ - objetivo: fechar lacunas verificáveis para a avaliação 10/10;
4
+ - concluído: rollback explícito de sandbox; reversão Git por patch binário; benchmark JSON determinístico; manifests oficiais GitHub/Docker; testes de isolamento;
5
+ - decisões: `promoted → rolled_back` é terminal; plugins oficiais são boundaries sem rede implícita; benchmark usa checksum e proxy bytes/4;
6
+ - restrições: rollback exige diff da mesma sessão; handlers externos dependem de adapters permissionados;
7
+ - evidências: testes `sandbox`, `adapter-git`, `context-benchmark`, `official-plugins`; `npm test` 300/300; build TypeScript aprovado; benchmark mediu 95,72% de redução nesta árvore;
8
+ - pendências: executar `release:check --publish` em árvore limpa e decidir publicação 2.0.3; integrar handlers externos reais apenas com credenciais e sandbox apropriadas;
9
+ - critérios de aceite: todos os testes e build aprovados;
10
+ - bloqueios: nenhum bloqueio técnico nesta sprint;
11
+ - próximo agente: Governance/Release Auditor.
@@ -0,0 +1,16 @@
1
+ # ADR-0069 — Demonstração de autonomia com sandbox Git real
2
+
3
+ - **Status:** aceito
4
+ - **Data:** 2026-08-01
5
+ - **Decisão:** o caminho demonstrável de autonomia deve usar uma fixture externa, Git
6
+ worktree real, comandos reais, aprovação persistida, Validator independente e
7
+ promoção explícita. O agente da fixture pode ser determinístico para manter a prova
8
+ offline e repetível.
9
+ - **Motivo:** os testes anteriores validavam o contrato do sandbox, mas usavam store e
10
+ backend simulados; isso não comprovava isolamento, subprocesso, diff ou promoção.
11
+ - **Consequências:** `npm run demo:autonomy` é uma prova operacional e não depende de
12
+ LLM. O cenário usa um teste Node nativo para evitar instalação de dependências na
13
+ fixture e deixa SQLite, Git e npm observáveis.
14
+ - **Evidências:** `scripts/demo-autonomy.ts` e `test/demo-autonomy.test.js`.
15
+ - **Próximos passos:** repetir a mesma composição no MCP stdio e no bootstrap oficial
16
+ do servidor; adicionar rollback e cenários de caos.
@@ -0,0 +1,11 @@
1
+ # ADR-0070 — MCP stdio como transporte testado por processo real
2
+
3
+ - **Status:** aceito
4
+ - **Decisão:** o transporte MCP local usa JSON-RPC delimitado por newline em
5
+ stdin/stdout; logs operacionais não podem ocupar stdout. Notificações sem `id`
6
+ não recebem resposta. EOF é o shutdown normal.
7
+ - **Motivo:** testes unitários do adapter não provavam compatibilidade do processo
8
+ lançado pelo usuário nem isolamento do canal de protocolo.
9
+ - **Consequências:** o teste inicia o binário real, envia mensagens em sequência e
10
+ rejeita stdout não parseável; diagnósticos devem usar stderr.
11
+ - **Evidência:** `test/mcp-stdio.test.js`.
@@ -0,0 +1,12 @@
1
+ # ADR-0071 — Bootstrap Nest com persistência SQLite completa
2
+
3
+ - **Status:** aceito
4
+ - **Decisão:** o bootstrap oficial injeta `SqliteRuntimePersistence`,
5
+ `SqliteGraphStore`, `SqliteApprovalStore`, `SqliteEventStore`,
6
+ `SqliteContextCache`, `SqliteOrchestrationStore` e `SqliteObservationStore`.
7
+ Stores em memória ficam restritos a defaults de testes e composição isolada.
8
+ - **Motivo:** a composição anterior persistia runtime, approvals, eventos, grafo e
9
+ contexto, mas criava orquestração e observabilidade em memória.
10
+ - **Consequências:** Sprint/Task/Handoff e métricas sobrevivem ao restart; shutdown
11
+ deve drenar publicações assíncronas do Event Bus antes de fechar SQLite.
12
+ - **Evidência:** `apps/server/src/main.ts` e `test/server-persistence.test.js`.
@@ -0,0 +1,9 @@
1
+ # ADR-0072 — Limites de ambiente e caminho no adapter Git
2
+
3
+ - **Status:** aceito
4
+ - **Decisão:** `SpawnCommandRunner` herda apenas variáveis operacionais mínimas
5
+ (`PATH`, temporários e `NODE_PATH`) e permite overrides explícitos. O
6
+ `GitGraphDocumentSource` rejeita locators que escapem da raiz resolvida.
7
+ - **Motivo:** comandos de sandbox não devem copiar secrets do processo e fontes
8
+ Git não devem transformar um locator malicioso em leitura fora do workspace.
9
+ - **Evidência:** testes de segurança em `test/adapter-git.test.js`.
@@ -0,0 +1,17 @@
1
+ # ADR-0073 — Última milha: rollback, benchmark e plugins permissionados
2
+
3
+ ## Status
4
+
5
+ Accepted
6
+
7
+ ## Contexto
8
+
9
+ O ForjaJS já comprovava promoção de uma alteração em Git worktree, contexto com cache e isolamento de plugins, mas não possuía uma operação de rollback formal, um artefato de benchmark estável nem plugins oficiais registráveis.
10
+
11
+ ## Decisão
12
+
13
+ Adicionar `rollback` ao contrato `SandboxBackend` e ao `SandboxEngine`, com estado terminal `rolled_back`. O backend Git reverte o patch binário na raiz do repositório através do mesmo `PatchApplier` usado na promoção. O benchmark de contexto emite JSON determinístico com checksum e estimativa documentada de tokens. GitHub e Docker são manifests oficiais mínimos; handlers de rede/daemon são injetados pelo host e nunca implícitos.
14
+
15
+ ## Consequências
16
+
17
+ Rollback permanece explícito e auditável. A medição pode ser reproduzida em CI, mas tokens continuam uma estimativa bytes/4. Os plugins são extensíveis e permissionados, porém não afirmam uma integração externa até que um adapter real seja fornecido.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "2.0.2",
4
- "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
3
+ "version": "2.0.3",
4
+ "description": "ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento",
5
5
  "type": "module",
6
6
  "main": "index.js",
7
7
  "bin": {
@@ -89,10 +89,20 @@
89
89
  "dashboard:start": "npm --prefix apps/dashboard run start",
90
90
  "build": "tsc -p tsconfig.build.json",
91
91
  "types:check": "tsc --noEmit",
92
- "test": "node --test test/*.test.js"
92
+ "test": "node --test test/*.test.js",
93
+ "demo:autonomy": "node scripts/demo-autonomy.ts",
94
+ "benchmark:context": "node scripts/context-benchmark.ts"
93
95
  },
94
96
  "keywords": [
95
97
  "agents",
98
+ "agentic",
99
+ "agent-runtime",
100
+ "mcp",
101
+ "graph-memory",
102
+ "context-engineering",
103
+ "local-first",
104
+ "developer-tools",
105
+ "autonomous-agents",
96
106
  "orchestration",
97
107
  "memory",
98
108
  "sqlite",