forjajs 1.6.0 → 1.6.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 CHANGED
@@ -4,6 +4,16 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [1.6.1] — 2026-07-20 — Correção: `project:upgrade` no pacote publicado
8
+
9
+ ### Corrigido
10
+ - **`project:upgrade` quebrava com `Cannot find module .../create-memory-nest-kit.ts`** no pacote
11
+ instalado. O spawn do gerador cravava a extensão `.ts`; em dev funciona, mas o `dist/` publicado
12
+ tem `.js`. Agora resolve dinamicamente via `resolveScript` (`.ts` em dev, `.js` no publicado). O
13
+ `project:smoke` tinha o mesmo defeito, também corrigido. Teste de regressão guarda a classe.
14
+
15
+ ---
16
+
7
17
  ## [1.6.0] — 2026-07-20 — A orquestração coerente e a governança num comando
8
18
 
9
19
  A governança do framework ganha um ponto de entrada e o namesake — orquestração multiagente — deixa
package/README.en.md CHANGED
@@ -88,11 +88,16 @@ process followed?", the answer is a file, not a promise.
88
88
  - **Hierarchical memory** — global → domain → task → summary, with FTS5 search and *smart-context*
89
89
  in 3 modes (ADR-0003).
90
90
  - **SDD + GSD pipeline** — `spec → plan → tasks → check`, decisions recorded as ADRs.
91
- - **Project generation** — `project:new` scaffolds a full project in the workspace (memory, agents,
92
- multi-AI instructions, a NestJS backend as the default boilerplate) and registers the project
93
- record automatically.
94
- - **Release gates** — `tools:doctor` fails when the core is broken (native ABI, memory, runtime
95
- deps); `release:check` proves a clean install works before `npm publish` (ADR-0023, ADR-0024).
91
+ - **Self-verification (invariants that run)** — the framework proves itself: a family of gates guards
92
+ each frontier (core, tarball, doc coherence, agent topology, generated project), and `check:all`
93
+ runs the whole battery into a single verdict. Governance stops depending on discipline — it becomes
94
+ harness.
95
+ - **Token economy measured, not asserted** — memory (the `context.md` as a map) saves ~60% vs
96
+ exploring cold, and `token:economy` **proves** it across your domains. `code:context` delivers the
97
+ map ready to paste; `memory:audit` guarantees it doesn't lie about the code.
98
+ - **Project generation** — `project:new` scaffolds a full project (memory, agents, multi-AI
99
+ instructions, a NestJS backend as the default boilerplate) and registers the record; `project:upgrade`
100
+ brings new scaffold pieces to already-generated projects without touching the user's code.
96
101
  - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
97
102
  (agent-team design), **ai-engineering** (knowledge base).
98
103
 
@@ -117,7 +122,10 @@ forja spec:check my-feature
117
122
  ```
118
123
 
119
124
  > Cloned the repo instead of installing? The same commands run as
120
- > `node bin/forja.mjs <command>` — the npm scripts are just thin aliases of the core.
125
+ > `node bin/forja.ts <command>` — the npm scripts are just thin aliases of the core.
126
+ > The source is TypeScript and runs natively: **dev needs Node ≥ 22.6** (type stripping). The
127
+ > *published* package ships `dist/*.js` and runs on **Node ≥ 20** — the `release-gate` proves it
128
+ > every release (SPEC-012).
121
129
 
122
130
  Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
123
131
 
@@ -160,7 +168,7 @@ Every process command goes through a single entry point (ADR-0020):
160
168
 
161
169
  ```bash
162
170
  forja # help grouped by domain
163
- forja <command> [args] # in a cloned repo: node bin/forja.mjs <command>
171
+ forja <command> [args] # in a cloned repo: node bin/forja.ts <command>
164
172
  ```
165
173
 
166
174
  The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
@@ -230,8 +238,8 @@ See ADR-0019 for the architectural decision.
230
238
  ## Repository structure (framework)
231
239
 
232
240
  ```
233
- bin/ CLIs (init-project, create-memory-nest-kit)
234
- lib/ Reusable modules (workspace, generators, validators, context-builder)
241
+ bin/ CLIs (forja — the core; init-project, create-memory-nest-kit)
242
+ lib/ Reusable modules; lib/core/ is the invariant engine (registry, checks, health, release, doc-graph, gates)
235
243
  scripts/ Automation (sprint-manager, agent-router, sync-universal-memory, …)
236
244
  specs/ The framework's own SDD pipeline (spec → plan → tasks)
237
245
  boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
@@ -279,30 +287,32 @@ output, code, and ADRs are readable regardless of language.
279
287
  The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
280
288
  below either closes a framework frontier with a gate, or carries that pattern into generated projects.
281
289
 
282
- **Recently shipped** (v1.2.0)
283
-
284
- - [x] **Core gate** — `tools:doctor` fails (exit 1) when what blocks the framework is broken (ABI,
285
- memory, runtime deps) — ADR-0023.
286
- - [x] **Tarball gate** — `release:check` proves a clean install works before `npm publish`; the three
287
- historical release bugs fail the gate — ADR-0024.
288
- - [x] **Doc coherence gate** — docs can't cite a ghost command or a link to nowhere; checked in CI — ADR-0025.
289
- - [x] **TypeScript as a gate** — strict `checkJs` in CI; core contracts typed. Found three latent bugs
290
- no test caught (SPEC-012, in progress).
291
- - [x] **Calibrated Clean Architecture boilerplate** — layers where they pay off, lean where they don't
292
- (`boilerplates/06-clean-arch`, ADR-0027).
290
+ **Shipped** (through v1.6.0)
291
+
292
+ - [x] **Gate family** — every framework frontier is guarded by an invariant that runs: core
293
+ (`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), doc + ADR + agent-topology
294
+ coherence (ADR-0025, SPEC-019), generated project (`project:smoke`, ADR-0029). And `check:all`
295
+ runs the whole battery into one verdict (SPEC-020).
296
+ - [x] **TypeScript migration complete** — source 100% `.ts`, ships `dist/`, `noImplicitAny` ON. Found
297
+ latent bugs no test caught (SPEC-012).
298
+ - [x] **Memory economy as a system** — **measured** (`token:economy` proves ~60% vs cold),
299
+ **delivered** (`code:context`), **protected** (`memory:audit`, both directions), and **propagated**:
300
+ the generated project inherits the maps gate (ADR-0030).
301
+ - [x] **`project:upgrade`** — update an already-generated project without losing code: additive, never
302
+ overwrites (SPEC-018).
303
+ - [x] **Calibrated Clean Architecture** — layers where they pay off, lean where they don't; and the
304
+ token claim **measured and corrected** — the saving is memory's, not the layers' (ADR-0027).
293
305
 
294
306
  **Next** (by dependency, not by wish)
295
307
 
296
- - [ ] **Finish the TypeScript migration** — publish `dist/` and rename `.mjs → .ts`. Pipeline proven;
297
- source stays `.mjs` (Node ≥ 20) until then.
298
- - [ ] **Token benchmark for clean-arch** — the saving is argued, not proven (ADR-0027): measure the
299
- same feature in both architectures via `context:smart`. Prove it or recalibrate.
308
+ - [ ] **Generated backend `builds` under new toolchains** — `check:all --full` flags that
309
+ `better-sqlite3` won't compile on very new Node (no prebuild); pin the version or document the build
310
+ requirement.
300
311
  - [ ] **`release-auditor` consumes the gate** — the third surface from ADR-0024: the agent runs
301
312
  `release:check` instead of reimplementing the procedure in prose.
302
313
  - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
303
- - [ ] **Queryable audit + generated dashboard** — promote `.context/forja-runs.jsonl` to an FTS5
304
- table, and generate a **static** governance page on demand (read-only, no server — the ADR-0022
305
- lesson that froze the server-dashboard).
314
+ - [ ] **(vision) the orchestration engine** — the handoff chain that **runs**, not just is coherent
315
+ (SPEC-019 left it as future). The namesake executing: a 2.0 candidate.
306
316
 
307
317
  Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
308
318
 
package/README.md CHANGED
@@ -83,7 +83,9 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
83
83
  - **Orquestração multiagente** — 6 papéis (orchestrator, context-engineer, sdd-architect, product, marketing, governance) com handoffs rastreados (7 campos, ADR-0005).
84
84
  - **Memória hierárquica** — global → domínio → tarefa → resumo, com busca FTS5 e *smart-context* em 3 modos (ADR-0003).
85
85
  - **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
86
- - **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 do projeto automaticamente.
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
+ - **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
+ - **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.
87
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).
88
90
 
89
91
  ## ⚡ Quick start
@@ -107,7 +109,9 @@ forja spec:check minha-feature
107
109
  ```
108
110
 
109
111
  > Clonou o repo em vez de instalar? Os mesmos comandos rodam como
110
- > `node bin/forja.mjs <comando>` — os scripts npm são apenas aliases finos do core.
112
+ > `node bin/forja.ts <comando>` — os scripts npm são apenas aliases finos do core.
113
+ > A fonte é TypeScript e roda nativa: **dev exige Node ≥ 22.6** (strip-types). O pacote *publicado*
114
+ > embarca `dist/*.js` e roda em **Node ≥ 20** — o `release-gate` prova isso a cada release (SPEC-012).
111
115
 
112
116
  Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
113
117
 
@@ -150,7 +154,7 @@ Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
150
154
 
151
155
  ```bash
152
156
  forja # help agrupado por domínio
153
- forja <comando> [args] # no repo clonado: node bin/forja.mjs <comando>
157
+ forja <comando> [args] # no repo clonado: node bin/forja.ts <comando>
154
158
  ```
155
159
 
156
160
  O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
@@ -224,8 +228,8 @@ Veja ADR-0019 para a decisão arquitetural.
224
228
  ## Estrutura do repositório (framework)
225
229
 
226
230
  ```
227
- bin/ CLIs (init-project, create-memory-nest-kit)
228
- lib/ Módulos reutilizáveis (workspace, generators, validators, context-builder)
231
+ bin/ CLIs (forja — o core; init-project, create-memory-nest-kit)
232
+ lib/ Módulos reutilizáveis; lib/core/ é o motor de invariantes (registry, checks, health, release, doc-graph, gates)
229
233
  scripts/ Automação (sprint-manager, agent-router, sync-universal-memory, …)
230
234
  specs/ Pipeline SDD do próprio framework (spec → plan → tasks)
231
235
  boilerplates/ Templates de stack (api-rest, saas, ecommerce, microservices, monorepo)
@@ -271,32 +275,32 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
271
275
  item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
272
276
  gerados.
273
277
 
274
- **Recém-entregue** (v1.2.0)
275
-
276
- - [x] **Gate do núcleo** — `tools:doctor` reprova (exit 1) quando o que impede o framework de
277
- trabalhar está quebrado (ABI, memória, deps de runtime) — ADR-0023.
278
- - [x] **Gate do tarball** — `release:check` prova que uma instalação limpa funciona antes do
279
- `npm publish`; os três bugs históricos de release reprovam o gate — ADR-0024.
280
- - [x] **Gate de coerência da doc** — a documentação não pode citar comando fantasma nem link para o
281
- nada; verificado no CI — ADR-0025.
282
- - [x] **TypeScript como gate** — `checkJs` estrito no CI; os contratos do núcleo tipados. Achou três
283
- bugs latentes que nenhum teste pegava (SPEC-012, em curso).
284
- - [x] **Boilerplate Clean Architecture calibrado** — DDD por camadas onde se paga, enxuto onde não
285
- (`boilerplates/06-clean-arch`, ADR-0027).
278
+ **Entregue** (até v1.6.0)
279
+
280
+ - [x] **Família de gates** — cada fronteira do framework guarda por um invariante que roda: núcleo
281
+ (`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), coerência de doc + ADRs + topologia
282
+ de agentes (ADR-0025, SPEC-019), projeto gerado (`project:smoke`, ADR-0029). E `check:all` reúne a
283
+ bateria num veredito (SPEC-020).
284
+ - [x] **Migração TypeScript completa** — fonte 100% `.ts`, publica `dist/`, `noImplicitAny` ON. Achou
285
+ bugs latentes que nenhum teste pegava (SPEC-012).
286
+ - [x] **Economia de memória como sistema** — **medida** (`token:economy` prova ~60% vs frio),
287
+ **entregue** (`code:context`), **protegida** (`memory:audit`, nas duas direções) e **propagada**: o
288
+ projeto gerado herda o gate dos mapas (ADR-0030).
289
+ - [x] **`project:upgrade`** — atualizar um projeto já gerado sem perder código: aditivo, nunca
290
+ sobrescreve (SPEC-018).
291
+ - [x] **Clean Architecture calibrado** — camadas onde se pagam, enxuto onde não; e a claim de token
292
+ **medida e corrigida** — a economia é da memória, não das camadas (ADR-0027).
286
293
 
287
294
  **Próximos passos** (por dependência, não por desejo)
288
295
 
289
- - [x] **Migração TypeScript fechada** — fonte 100% `.ts`, publica `dist/`, `noImplicitAny` ON
290
- (SPEC-012, v1.3.x).
291
- - [x] **Benchmark de token do clean-arch** — medido, não mais argumentado (`forja token:economy`,
292
- ADR-0027). Veredito honesto: para feature pequena o flat é mais barato; a economia do clean-arch é
293
- função da escala, e a justificativa das camadas é **isolamento**, não token.
296
+ - [ ] **`builds` do backend gerado sob toolchain novo** — o `check:all --full` flagra que o
297
+ `better-sqlite3` não compila em Node muito novo (sem prebuild); fixar a versão ou documentar o
298
+ requisito de build.
294
299
  - [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
295
300
  `release:check` em vez de reimplementar o procedimento em prosa.
296
301
  - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
297
- - [ ] **Auditoria consultável + painel gerado** — promover `.context/forja-runs.jsonl` a tabela
298
- FTS5, e gerar um painel de governança **estático** por comando (leitura, sem servidor — a lição
299
- do ADR-0022, que congelou o dashboard-servidor).
302
+ - [ ] **(visão) o motor de orquestração** — a cadeia de handoffs que **roda**, não só é coerente
303
+ (SPEC-019 deixou como futuro). O namesake executando: candidato ao 2.0.
300
304
 
301
305
  Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
302
306
 
@@ -17,6 +17,7 @@ import os from 'node:os';
17
17
  import path from 'node:path';
18
18
  import { fileURLToPath } from 'node:url';
19
19
  import { runChecks as run, worstStatus } from "./checks.js";
20
+ import { resolveScript } from "./registry.js";
20
21
  // @ts-ignore — validador legado sem tipos exportados; usado só pela forma { isValid, errors }.
21
22
  import { validateProjectStructure } from "../validators/structure-validator.js";
22
23
  export { worstStatus };
@@ -32,7 +33,8 @@ export async function withGeneratedProject(fn, { root = repoRoot, spawn }) {
32
33
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-smoke-'));
33
34
  const projectDir = path.join(dir, 'smoke-proj');
34
35
  try {
35
- const gen = path.join(root, 'bin', 'create-memory-nest-kit.ts');
36
+ // resolveScript acha .ts em dev e .js no dist — cravar .ts quebrava no pacote publicado.
37
+ const gen = resolveScript(root, 'bin/create-memory-nest-kit');
36
38
  const res = spawn(process.execPath, [gen, projectDir, '--force'], { cwd: dir });
37
39
  if (res.code !== 0) {
38
40
  throw new Error(`o gerador saiu com código ${res.code}:\n${(res.stderr || res.stdout).slice(0, 800)}`);
@@ -14,6 +14,7 @@ import os from 'node:os';
14
14
  import path from 'node:path';
15
15
  import { fileURLToPath } from 'node:url';
16
16
  import { planUpgrade, applyUpgrade } from "../lib/project-upgrade.js";
17
+ import { resolveScript } from "../lib/core/registry.js";
17
18
  const __filename = fileURLToPath(import.meta.url);
18
19
  const repoRoot = path.resolve(path.dirname(__filename), '..');
19
20
  function main() {
@@ -34,7 +35,10 @@ function main() {
34
35
  for (const k of Object.keys(env))
35
36
  if (k.startsWith('npm_'))
36
37
  delete env[k];
37
- execFileSync(process.execPath, [path.join(repoRoot, 'bin', 'create-memory-nest-kit.ts'), fresh, '--force'], {
38
+ // resolveScript acha .ts em dev e dist/bin/create-memory-nest-kit.js no publicado — cravar .ts
39
+ // quebrava o comando instalado com module-not-found (o dist não tem .ts).
40
+ const generator = resolveScript(repoRoot, 'bin/create-memory-nest-kit');
41
+ execFileSync(process.execPath, [generator, fresh, '--force'], {
38
42
  cwd: tmp,
39
43
  env,
40
44
  stdio: 'pipe',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.6.0",
3
+ "version": "1.6.1",
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",