forjajs 1.1.4 → 1.1.5

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 CHANGED
@@ -4,6 +4,37 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.1.5] — 2026-07-14 — O comando é forja
8
+
9
+ A documentação pública ainda falava a língua interna do repo: `npm run x -- args` onde o usuário
10
+ do pacote tem `forja x args`. Esta versão alinha o que o README promete com o que o binário faz.
11
+
12
+ ### Corrigido
13
+
14
+ - **README inteiro migrado para `forja` como forma canônica** — os scripts npm continuam
15
+ existindo como aliases do repo clonado, mas deixam de ser a vitrine.
16
+ - **Exemplos do "60 segundos" estavam quebrados**: `forja gsd:handoff -- plan …` passa o `--`
17
+ cru para o script (o core não filtra separador) e o comando falha. O `--` só era necessário
18
+ na forma `npm run`; removido dos exemplos diretos.
19
+ - **Comando errado na lista de essenciais**: validar projeto do workspace é
20
+ `workspace:project:check <nome>`, não `project:check <nome>` (que é o standards check do framework).
21
+ - **Links mortos**: `projects/ai-engineering-from-scratch-main/` não existe no repo;
22
+ `docs/capacidades-externas.md` agora aponta para as fontes upstream (ADR-0016) e a
23
+ reinstalação segue a prescrição do `tools:doctor` (`npm i -g @codegraph/cli`) em vez do
24
+ symlink manual antigo.
25
+ - **`package-lock.json` preso em 1.1.3** desde o bump da 1.1.4; sincronizado.
26
+
27
+ ### Adicionado
28
+
29
+ - Seção "Comandos essenciais" do README ampliada com o que já existia no registry mas não
30
+ aparecia: `gsd:plan`/`gsd:check`, `code:check`/`code:impact`, `memory:compress`,
31
+ `tools:doctor`, `release:check --publish`.
32
+ - `allowScripts` no `package.json`: instalações com política allow-scripts ativa deixam de
33
+ bloquear silenciosamente o prebuild do `better-sqlite3` — exatamente o modo de falha que
34
+ matava a memória (ADR-0023).
35
+
36
+ ---
37
+
7
38
  ## [1.1.4] — 2026-07-14 — Os gates
8
39
 
9
40
  Duas fronteiras do framework funcionavam por disciplina, e a disciplina falhou nas duas. Esta versão
package/README.md CHANGED
@@ -51,15 +51,15 @@ principal força de trabalho — e precisa da disciplina de um time grande sem t
51
51
  $ forja spec:new pagamentos-pix
52
52
  ✓ Spec criada: specs/pagamentos-pix/spec.md # nada vira código sem isso
53
53
 
54
- $ forja gsd:handoff -- plan pagamentos-pix
54
+ $ forja gsd:handoff plan pagamentos-pix
55
55
  Handoff registrado: product → sdd-architect # 7 campos, auditável (ADR-0005)
56
56
 
57
- $ forja code:impact -- processPayment
57
+ $ forja code:impact processPayment
58
58
  Mapa de impacto: processPayment (profundidade 2) # blast radius ANTES de editar
59
59
  --- Chamadores diretos ---
60
60
  BillingController.charge · RetryWorker.run
61
61
 
62
- $ forja gsd:check -- pagamentos-pix
62
+ $ forja gsd:check pagamentos-pix
63
63
  OK GSD runbook OK Spec directory
64
64
  OK SDD spec check OK Codegraph
65
65
  Resultado: gates básicos prontos. # governança executável, não checklist
@@ -90,31 +90,30 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
90
90
  # Instalar (o pacote é forjajs; o comando é forja)
91
91
  npm install -g forjajs
92
92
  forja # help agrupado por domínio
93
- ```
94
-
95
- Ou clonando o repo:
96
93
 
97
- ```bash
98
94
  # Preparar o workspace de produção (canto fixo dos projetos)
99
- npm run workspace:init
95
+ forja workspace:init
100
96
 
101
97
  # Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
102
- npm run project:new meu-projeto -- --ai claude,copilot
98
+ forja project:new meu-projeto --ai claude,copilot
103
99
 
104
100
  # Entrar no ciclo SDD/GSD da primeira feature
105
- npm run spec:new -- minha-feature
106
- npm run spec:plan -- minha-feature
107
- npm run spec:tasks -- minha-feature
108
- npm run spec:check -- minha-feature
101
+ forja spec:new minha-feature
102
+ forja spec:plan minha-feature
103
+ forja spec:tasks minha-feature
104
+ forja spec:check minha-feature
109
105
  ```
110
106
 
107
+ > Clonou o repo em vez de instalar? Os mesmos comandos rodam como
108
+ > `node bin/forja.mjs <comando>` — os scripts npm são apenas aliases finos do core.
109
+
111
110
  Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
112
111
 
113
112
  ## Como funciona — o processo
114
113
 
115
114
  ```
116
115
  💡 Demanda
117
- ├─ projeto NÃO existe ─► init:project + boilerplate + harness (desenha o time)
116
+ ├─ projeto NÃO existe ─► project:new + boilerplate + harness (desenha o time)
118
117
  └─ projeto JÁ existe ──► overlay --only-memory + codegraph init (entende o código)
119
118
  │
120
119
  ▼
@@ -137,9 +136,9 @@ Mapa completo do ciclo: [`docs/fluxo.md`](docs/fluxo.md).
137
136
 
138
137
  | Capacidade | Papel | Como usar |
139
138
  |---|---|---|
140
- | **codegraph** | análise de código (MCP local) | `npm run code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
139
+ | **codegraph** | análise de código (MCP local) | `forja code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
141
140
  | **harness** | desenho de times de agentes (plugin) | na sessão Claude Code: _"build a harness for this project"_ → gera `.claude/agents` + `.claude/skills` |
142
- | **ai-engineering** | base de conhecimento (referência) | `projects/ai-engineering-from-scratch-main/` (ROADMAP, phases, glossary) |
141
+ | **ai-engineering** | base de conhecimento (referência) | ver [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
143
142
 
144
143
  Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
145
144
 
@@ -148,43 +147,49 @@ Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-ext
148
147
  Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
149
148
 
150
149
  ```bash
151
- node bin/forja.mjs # help agrupado por domínio
152
- node bin/forja.mjs <comando> # ou, com o pacote linkado: forja <comando>
150
+ forja # help agrupado por domínio
151
+ forja <comando> [args] # no repo clonado: node bin/forja.mjs <comando>
153
152
  ```
154
153
 
155
154
  O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
156
155
  workspace) e grava **auditoria** de cada execução (comando, args, exit code, duração)
157
156
  em `<workspace>/.context/forja-runs.jsonl` — a trilha que a governança usa no review.
158
- Os scripts npm abaixo são aliases finos que roteiam pelo core.
157
+ Os scripts npm do repo são aliases finos que roteiam pelo core.
159
158
 
160
159
  ## Comandos essenciais
161
160
 
162
161
  ```bash
163
162
  # Workspace & projetos
164
- npm run workspace:init # cria ~/forja-workspace
165
- npm run project:new <nome> -- --ai claude,copilot # cria projeto no workspace
166
- npm run project:list # lista projetos do workspace
167
- npm run project:check <nome> # valida padrões no projeto
163
+ forja workspace:init # cria ~/forja-workspace
164
+ forja project:new <nome> --ai claude,copilot # cria projeto no workspace
165
+ forja project:list # lista projetos do workspace
166
+ forja workspace:project:check <nome> # valida padrões num projeto do workspace
168
167
 
169
168
  # Pipeline SDD
170
- npm run spec:new|plan|tasks|check -- <slug>
169
+ forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
171
170
 
172
171
  # Sprint & handoffs (GSD)
173
- npm run sprint:start | sprint:status | sprint:complete
174
- npm run gsd:handoff -- <intent> <slug> # handoff entre papéis (ADR-0005)
172
+ forja sprint:start # também: sprint:status · sprint:complete
173
+ forja gsd:plan <slug> # runbook GSD em .context/
174
+ forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
175
+ forja gsd:check <slug> # gates básicos do runbook
175
176
 
176
177
  # Análise de código (codegraph)
177
- npm run code:index | code:sync | code:status
178
- npm run code:query "<termo>"
178
+ forja code:check # índice confiável (worktree + freshness)
179
+ forja code:impact <símbolo> # chamadores + blast radius antes de editar
180
+ forja code:query "<termo>" # também: code:index · code:sync · code:status
179
181
 
180
182
  # Memória & contexto (workspace)
181
- npm run sync:universal # reindexa SQLite FTS5 do workspace
182
- npm run query:universal "<query>"
183
- npm run context:smart # smart-context
184
-
185
- # Qualidade & visão
186
- npm run project:check # standards do framework
187
- npm run project:dashboard # relatório estático de status
183
+ forja sync:universal # reindexa SQLite FTS5 do workspace
184
+ forja query:universal "<query>" # busca FTS5
185
+ forja context:smart # smart-context (3 modos, ADR-0003)
186
+ forja memory:compress # arquiva runs antigos + VACUUM
187
+
188
+ # Qualidade & release
189
+ forja project:check # standards do framework (pre-commit)
190
+ forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
191
+ forja release:check --publish # gate do tarball antes de publicar
192
+ forja project:dashboard # relatório estático de status
188
193
  ```
189
194
 
190
195
  ## Separação framework × workspace
@@ -1,38 +1,47 @@
1
1
  # Capacidades externas integradas
2
2
 
3
- Três produtos open-source foram alocados ao `2-projeto-agents` como capacidades de
3
+ Três produtos open-source foram integrados ao framework como capacidades de
4
4
  primeira classe (ver [ADR-0016](../memory/90-decisions/0016-integracao-capacidades-externas.md)).
5
- Antigamente viviam em `projects/`; agora estão no workspace Forja
6
- (`~/forja-workspace`, configurável — ver [ADR-0019](../memory/90-decisions/0019-workspace-separado.md)).
7
- Aqui ficam só a fiação e o modo de uso.
5
+ Os produtos em si **não são versionados neste repo** — são instalados por máquina.
6
+ O que o repo versiona é a **fiação**: `.mcp.json` (servidor MCP do codegraph),
7
+ os comandos `code:*` no registry do core e este guia. O estado da instalação na
8
+ sua máquina é reportado por `forja tools:doctor`.
9
+
10
+ | Capacidade | Eixo | Fonte |
11
+ |---|---|---|
12
+ | **codegraph** | análise de código (MCP + CLI) | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) |
13
+ | **harness** | desenho de times de agentes (plugin Claude Code) | [revfactory/harness](https://github.com/revfactory/harness) |
14
+ | **ai-engineering-from-scratch** | base de conhecimento (referência) | [rohitg00/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) |
8
15
 
9
16
  ## 1. codegraph — análise de código (MCP)
10
17
 
11
18
  Grafo de código semântico, 100% local. Registrado como **servidor MCP** no repo
12
- (`.mcp.json`) e disponível no PATH (`~/.local/bin/codegraph`).
19
+ (`.mcp.json`, comando `codegraph serve --mcp`) — quem clona o repo herda o registro;
20
+ basta ter o binário `codegraph` no PATH.
13
21
 
14
22
  **Ferramentas MCP** (aparecem automaticamente em sessões Claude Code neste repo):
15
23
  - `codegraph_explore` — símbolos relevantes + call paths de uma área, num disparo só.
16
24
  - `codegraph_node` — fonte de um símbolo + trilha de callers/callees, ou leitura de arquivo.
17
25
 
18
- **CLI / npm scripts:**
26
+ **CLI (via core `forja`):**
19
27
  ```bash
20
- npm run code:index # codegraph init — constrói o índice inicial (respeita .gitignore)
21
- npm run code:sync # sincroniza mudanças desde o último índice
22
- npm run code:status # status e estatísticas do índice
23
- npm run code:query "<termo>" # busca símbolos
24
- codegraph explore "<query>" # exploração ad-hoc
25
- codegraph callers <símbolo> # quem chama um símbolo
28
+ forja code:index # codegraph init — constrói o índice inicial (respeita .gitignore)
29
+ forja code:sync # sincroniza mudanças desde o último índice
30
+ forja code:status # status e estatísticas do índice
31
+ forja code:query "<termo>" # busca símbolos
32
+ forja code:check # gate: índice confiável (worktree + freshness, ADR-0017)
33
+ forja code:impact <símbolo> # chamadores + blast radius antes de editar
34
+ codegraph explore "<query>" # exploração ad-hoc direto no binário
35
+ codegraph callers <símbolo> # quem chama um símbolo
26
36
  ```
27
37
 
28
- O índice fica em `.codegraph/` (já coberto por `.gitignore` do projeto, se necessário).
38
+ O índice fica em `.codegraph/` (coberto pelo `.gitignore` do projeto).
29
39
 
30
40
  ## 2. harness — orquestração de times de agentes (plugin)
31
41
 
32
- Plugin do Claude Code (`harness@harness-marketplace`, instalado e habilitado) que
33
- transforma uma descrição de domínio em um time de agentes + skills, a partir de 6
34
- padrões: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor,
35
- Hierarchical Delegation.
42
+ Plugin do Claude Code (`harness@harness-marketplace`) que transforma uma descrição
43
+ de domínio em um time de agentes + skills, a partir de 6 padrões: Pipeline,
44
+ Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation.
36
45
 
37
46
  **Uso:** numa sessão Claude Code, peça _"build a harness for this project"_ (ou
38
47
  _"configure um harness para X"_) e ele gera `.claude/agents/` e `.claude/skills/`
@@ -46,25 +55,32 @@ claude plugin update harness@harness-marketplace
46
55
  ```
47
56
 
48
57
  Complementa o sistema de orquestração nativo do framework (AGENTS.md, handoffs,
49
- `scripts/agent-router.mjs`): harness ajuda a *desenhar* novos times; o framework
50
- *opera* os handoffs.
58
+ `forja gsd:handoff` / `forja agent:route`): harness ajuda a *desenhar* novos times;
59
+ o framework *opera* os handoffs.
51
60
 
52
61
  ## 3. ai-engineering-from-scratch — base de conhecimento (referência)
53
62
 
54
63
  Currículo de AI engineering: 503 lições, 20 fases, 4 linguagens (Python, TypeScript,
55
64
  Rust, Julia). Material de referência para fundamentar decisões técnicas de IA do
56
- framework. Não há instalação — consultar diretamente:
65
+ framework. Não há instalação nem fiação — consultar direto no repositório upstream:
66
+
67
+ - [`ROADMAP.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/ROADMAP.md) — índice das 20 fases.
68
+ - `phases/` — lições por fase.
69
+ - `glossary/` — glossário.
57
70
 
58
- - `projects/ai-engineering-from-scratch-main/ROADMAP.md` — índice das 20 fases.
59
- - `projects/ai-engineering-from-scratch-main/phases/` — lições por fase.
60
- - `projects/ai-engineering-from-scratch-main/glossary/` — glossário.
71
+ ## Instalação / reinstalação
61
72
 
62
- ## Reinstalação
73
+ O `forja tools:doctor` diz o que falta e como instalar. Para as capacidades deste guia:
63
74
 
64
- Se `projects/` for limpo, recriar a fiação:
65
75
  ```bash
66
- ln -sf "$PWD/projects/codegraph-linux-x64/bin/codegraph" ~/.local/bin/codegraph
67
- claude mcp add codegraph --scope project -- codegraph serve --mcp
68
- claude plugin marketplace add "$PWD/projects/harness-main"
76
+ # codegraph — binário no PATH (o .mcp.json versionado faz o resto)
77
+ npm i -g @codegraph/cli
78
+
79
+ # harness — clonar o repo e registrar como marketplace local
80
+ git clone https://github.com/revfactory/harness ~/tools/harness
81
+ claude plugin marketplace add ~/tools/harness
69
82
  claude plugin install harness@harness-marketplace
70
83
  ```
84
+
85
+ Depois, confira com `forja tools:doctor` (codegraph) e `claude plugin list` (harness).
86
+ Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.1.4",
3
+ "version": "1.1.5",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -104,5 +104,8 @@
104
104
  "license": "MIT",
105
105
  "dependencies": {
106
106
  "better-sqlite3": "^12.11.1"
107
+ },
108
+ "allowScripts": {
109
+ "better-sqlite3@12.11.1": true
107
110
  }
108
111
  }