forjajs 1.3.2 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/AGENTS.md +5 -0
  2. package/CHANGELOG.md +74 -0
  3. package/README.en.md +1 -0
  4. package/README.md +11 -4
  5. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  6. package/dist/lib/agent-topology.d.ts +38 -0
  7. package/dist/lib/agent-topology.js +65 -0
  8. package/dist/lib/code-context.d.ts +41 -0
  9. package/dist/lib/code-context.js +108 -0
  10. package/dist/lib/core/doc-graph.d.ts +13 -0
  11. package/dist/lib/core/doc-graph.js +47 -0
  12. package/dist/lib/core/gates.d.ts +36 -0
  13. package/dist/lib/core/gates.js +35 -0
  14. package/dist/lib/core/health.js +64 -1
  15. package/dist/lib/core/project-smoke.d.ts +46 -0
  16. package/dist/lib/core/project-smoke.js +248 -0
  17. package/dist/lib/core/registry.d.ts +30 -0
  18. package/dist/lib/core/registry.js +30 -0
  19. package/dist/lib/core/release.d.ts +30 -0
  20. package/dist/lib/generators/memory-generator.d.ts +1 -0
  21. package/dist/lib/generators/memory-generator.js +44 -0
  22. package/dist/lib/generators/readme-generator.js +1 -0
  23. package/dist/lib/memory-audit.d.ts +31 -0
  24. package/dist/lib/memory-audit.js +81 -0
  25. package/dist/lib/project-upgrade.d.ts +28 -0
  26. package/dist/lib/project-upgrade.js +74 -0
  27. package/dist/scripts/agent-router.js +1 -1
  28. package/dist/scripts/code-context.d.ts +12 -0
  29. package/dist/scripts/code-context.js +73 -0
  30. package/dist/scripts/gates.d.ts +10 -0
  31. package/dist/scripts/gates.js +44 -0
  32. package/dist/scripts/memory-audit.d.ts +11 -0
  33. package/dist/scripts/memory-audit.js +49 -0
  34. package/dist/scripts/project-smoke.d.ts +14 -0
  35. package/dist/scripts/project-smoke.js +44 -0
  36. package/dist/scripts/project-upgrade.d.ts +11 -0
  37. package/dist/scripts/project-upgrade.js +61 -0
  38. package/dist/scripts/token-economy.d.ts +20 -0
  39. package/dist/scripts/token-economy.js +140 -0
  40. package/memory/90-decisions/0025-coerencia-da-documentacao.md +10 -0
  41. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  42. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  43. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  44. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  45. package/package.json +1 -1
  46. package/specs/code-context/spec.md +56 -0
  47. package/specs/gates/spec.md +63 -0
  48. package/specs/memory-audit/spec.md +54 -0
  49. package/specs/orchestration-coherent/spec.md +95 -0
  50. package/specs/project-smoke/spec.md +96 -0
  51. package/specs/project-upgrade/spec.md +58 -0
@@ -0,0 +1,81 @@
1
+ /**
2
+ * lib/memory-audit.ts — os mapas de memória não podem mentir sobre o código (SPEC-017, ADR-0009).
3
+ *
4
+ * A economia de token do Forja é o `context.md` como mapa (`token:economy` mede −61%). Mas um mapa
5
+ * que aponta "a regra mora em `domain/order.entity.ts`" **depois** que o arquivo foi renomeado é
6
+ * *pior* que mapa nenhum: engana com confiança, e um agente vai ler o lugar errado — pagando o custo
7
+ * e chegando à conclusão errada.
8
+ *
9
+ * Este módulo é o `adr-refs` dos mapas: extrai os paths de código que cada `context.md` cita e
10
+ * confere que eles existem. Referência pendurada num mapa é a economia de token se voltando contra si.
11
+ */
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import { domainsOf } from "./code-context.js";
15
+ const defaultEnv = { fs };
16
+ /** Paths de código citados num mapa: tokens entre crases que terminam em `.ts` e têm ao menos um `/`. */
17
+ const CODE_REF_RE = /`([a-z][a-zA-Z0-9/._-]*\/[a-zA-Z0-9/._-]*\.ts)`/g;
18
+ /**
19
+ * Resolve um path citado num mapa contra as bases plausíveis: relativo ao módulo
20
+ * (`backend/src/modules/<domain>/`), ao `backend/`, e à raiz do projeto. Basta existir numa.
21
+ */
22
+ function refResolves(projectRoot, domain, ref, env) {
23
+ const bases = [
24
+ path.join(projectRoot, 'backend', 'src', 'modules', domain),
25
+ path.join(projectRoot, 'backend'),
26
+ projectRoot,
27
+ ];
28
+ return bases.some((base) => env.fs.existsSync(path.join(base, ref)));
29
+ }
30
+ /** Módulos de código de um projeto: os diretórios sob `backend/src/modules/`. */
31
+ export function modulesOf(projectRoot, env = defaultEnv) {
32
+ const dir = path.join(projectRoot, 'backend', 'src', 'modules');
33
+ try {
34
+ return env.fs
35
+ .readdirSync(dir)
36
+ .filter((e) => {
37
+ try {
38
+ return env.fs.statSync(path.join(dir, e)).isDirectory();
39
+ }
40
+ catch {
41
+ return false;
42
+ }
43
+ })
44
+ .sort();
45
+ }
46
+ catch {
47
+ return [];
48
+ }
49
+ }
50
+ /**
51
+ * A direção reversa da coerência: módulo de código **sem** `context.md`. Não é uma mentira (o mapa
52
+ * não existe para mentir), mas é a economia de token perdida em silêncio — um domínio que cresceu e
53
+ * ninguém mapeou. `warn`, não `fail`.
54
+ */
55
+ export function modulesWithoutMap(projectRoot, env = defaultEnv) {
56
+ const mapped = new Set(domainsOf(projectRoot, env));
57
+ return modulesOf(projectRoot, env).filter((m) => !mapped.has(m));
58
+ }
59
+ /** Audita os mapas de todos os domínios de um projeto. */
60
+ export function auditMemoryMaps(projectRoot, env = defaultEnv) {
61
+ const out = [];
62
+ for (const domain of domainsOf(projectRoot, env)) {
63
+ const mapPath = path.join(projectRoot, 'memory', '30-domains', domain, 'context.md');
64
+ let src;
65
+ try {
66
+ src = env.fs.readFileSync(mapPath, 'utf8');
67
+ }
68
+ catch {
69
+ continue;
70
+ }
71
+ const refs = [...new Set([...src.matchAll(CODE_REF_RE)].map((m) => m[1]))];
72
+ const dangling = refs.filter((ref) => !refResolves(projectRoot, domain, ref, env));
73
+ out.push({
74
+ domain,
75
+ mapPath: path.relative(projectRoot, mapPath),
76
+ refs: refs.length,
77
+ dangling,
78
+ });
79
+ }
80
+ return out;
81
+ }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * lib/project-upgrade.ts — a metade que falta do scaffolder (SPEC-018).
3
+ *
4
+ * O framework GERA projetos, mas nunca soube ATUALIZAR um projeto já gerado quando ele evolui: uma
5
+ * memória nova (`70-summaries/`), um agent novo, um config multi-IA novo. Quem gerou na v1.2 ficava
6
+ * preso na v1.2. Aqui a regra é simples e segura: **aditivo, nunca sobrescreve.** O upgrade só traz
7
+ * peças de scaffold que FALTAM no projeto; um arquivo que já existe pode ter edição do usuário, e o
8
+ * código do usuário é intocável.
9
+ */
10
+ import fs from 'node:fs';
11
+ export interface UpgradeEnv {
12
+ fs: typeof fs;
13
+ }
14
+ /** Todos os arquivos (rel) sob um root, menos os SKIP_DIRS. */
15
+ export declare function listFiles(root: string, env?: UpgradeEnv): string[];
16
+ export interface UpgradePlan {
17
+ /** Arquivos que o scaffold atual traz e o projeto não tem — as peças novas, seguras de adicionar. */
18
+ newFiles: string[];
19
+ /** Presentes nos dois — não tocados (podem ter edição do usuário). */
20
+ existing: number;
21
+ }
22
+ /**
23
+ * Planeja o upgrade: o que o scaffold fresco tem que o projeto-alvo não tem. **Só adições** — nunca
24
+ * lista sobrescritas, porque um arquivo existente é território do usuário.
25
+ */
26
+ export declare function planUpgrade(freshRoot: string, targetRoot: string, env?: UpgradeEnv): UpgradePlan;
27
+ /** Aplica o plano: copia as peças novas para o alvo, criando diretórios. Nunca sobrescreve. */
28
+ export declare function applyUpgrade(freshRoot: string, targetRoot: string, plan: UpgradePlan, env?: UpgradeEnv): string[];
@@ -0,0 +1,74 @@
1
+ /**
2
+ * lib/project-upgrade.ts — a metade que falta do scaffolder (SPEC-018).
3
+ *
4
+ * O framework GERA projetos, mas nunca soube ATUALIZAR um projeto já gerado quando ele evolui: uma
5
+ * memória nova (`70-summaries/`), um agent novo, um config multi-IA novo. Quem gerou na v1.2 ficava
6
+ * preso na v1.2. Aqui a regra é simples e segura: **aditivo, nunca sobrescreve.** O upgrade só traz
7
+ * peças de scaffold que FALTAM no projeto; um arquivo que já existe pode ter edição do usuário, e o
8
+ * código do usuário é intocável.
9
+ */
10
+ import fs from 'node:fs';
11
+ import path from 'node:path';
12
+ const defaultEnv = { fs };
13
+ /** Dirs que são runtime/build/deps — não são scaffold a copiar. */
14
+ const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', '.memory', '.context']);
15
+ /** Todos os arquivos (rel) sob um root, menos os SKIP_DIRS. */
16
+ export function listFiles(root, env = defaultEnv) {
17
+ const out = [];
18
+ const walk = (dir) => {
19
+ let entries;
20
+ try {
21
+ entries = env.fs.readdirSync(dir);
22
+ }
23
+ catch {
24
+ return;
25
+ }
26
+ for (const e of entries) {
27
+ if (SKIP_DIRS.has(e))
28
+ continue;
29
+ const p = path.join(dir, e);
30
+ let st;
31
+ try {
32
+ st = env.fs.statSync(p);
33
+ }
34
+ catch {
35
+ continue;
36
+ }
37
+ if (st.isDirectory())
38
+ walk(p);
39
+ else
40
+ out.push(path.relative(root, p));
41
+ }
42
+ };
43
+ walk(root);
44
+ return out.sort();
45
+ }
46
+ /**
47
+ * Planeja o upgrade: o que o scaffold fresco tem que o projeto-alvo não tem. **Só adições** — nunca
48
+ * lista sobrescritas, porque um arquivo existente é território do usuário.
49
+ */
50
+ export function planUpgrade(freshRoot, targetRoot, env = defaultEnv) {
51
+ const fresh = listFiles(freshRoot, env);
52
+ const newFiles = [];
53
+ let existing = 0;
54
+ for (const rel of fresh) {
55
+ if (env.fs.existsSync(path.join(targetRoot, rel)))
56
+ existing += 1;
57
+ else
58
+ newFiles.push(rel);
59
+ }
60
+ return { newFiles, existing };
61
+ }
62
+ /** Aplica o plano: copia as peças novas para o alvo, criando diretórios. Nunca sobrescreve. */
63
+ export function applyUpgrade(freshRoot, targetRoot, plan, env = defaultEnv) {
64
+ const applied = [];
65
+ for (const rel of plan.newFiles) {
66
+ const dst = path.join(targetRoot, rel);
67
+ if (env.fs.existsSync(dst))
68
+ continue; // paranoia: nunca sobrescreve
69
+ env.fs.mkdirSync(path.dirname(dst), { recursive: true });
70
+ env.fs.copyFileSync(path.join(freshRoot, rel), dst);
71
+ applied.push(rel);
72
+ }
73
+ return applied;
74
+ }
@@ -39,7 +39,7 @@ const root = path.resolve(__dirname, '..');
39
39
  ensureSchema({ silent: true });
40
40
  const dbPath = getDbPath();
41
41
  const REQUIRED = ['from', 'to', 'intent', 'context', 'acceptance', 'constraints', 'return'];
42
- const VALID_AGENTS = ['orchestrator', 'context-engineer', 'sdd-architect', 'product', 'marketing', 'governance', 'worker', 'user'];
42
+ const VALID_AGENTS = ['orchestrator', 'context-engineer', 'sdd-architect', 'product', 'marketing', 'governance', 'release-auditor', 'worker', 'user'];
43
43
  const VALID_INTENTS = ['implement', 'review', 'plan', 'research', 'spec', 'route'];
44
44
  const BUSY_ATTEMPTS = 8;
45
45
  const BUSY_DELAY_MS = 150;
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * code:context — entrega o pacote de contexto mínimo de um domínio (SPEC-016, ADR-0009).
4
+ *
5
+ * forja code:context <domínio> só o mapa (context.md) — o contexto barato
6
+ * forja code:context <domínio> --code + o código da fatia (para editar)
7
+ * forja code:context <domínio> --project <path> aponta para outro projeto
8
+ *
9
+ * O −61% do `token:economy` virado ferramenta: o mapa que substitui a exploração, pronto para colar.
10
+ * Para o blast radius de um símbolo específico, componha com `forja code:impact <símbolo>`.
11
+ */
12
+ export {};
@@ -0,0 +1,73 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * code:context — entrega o pacote de contexto mínimo de um domínio (SPEC-016, ADR-0009).
4
+ *
5
+ * forja code:context <domínio> só o mapa (context.md) — o contexto barato
6
+ * forja code:context <domínio> --code + o código da fatia (para editar)
7
+ * forja code:context <domínio> --project <path> aponta para outro projeto
8
+ *
9
+ * O −61% do `token:economy` virado ferramenta: o mapa que substitui a exploração, pronto para colar.
10
+ * Para o blast radius de um símbolo específico, componha com `forja code:impact <símbolo>`.
11
+ */
12
+ import path from 'node:path';
13
+ import { buildContextPack, domainsOf } from "../lib/code-context.js";
14
+ function arg(name) {
15
+ const i = process.argv.indexOf(name);
16
+ return i >= 0 ? process.argv[i + 1] ?? null : null;
17
+ }
18
+ function main() {
19
+ // Positionals = tudo que não é flag nem valor de flag. `--project` consome o próximo arg.
20
+ const argv = process.argv.slice(2);
21
+ const positional = [];
22
+ for (let i = 0; i < argv.length; i += 1) {
23
+ if (argv[i] === '--project') {
24
+ i += 1; // pula o valor
25
+ continue;
26
+ }
27
+ if (argv[i].startsWith('--'))
28
+ continue;
29
+ positional.push(argv[i]);
30
+ }
31
+ const domain = positional[0];
32
+ const projectRoot = path.resolve(arg('--project') || process.cwd());
33
+ const includeCode = process.argv.includes('--code');
34
+ const available = domainsOf(projectRoot);
35
+ if (!domain) {
36
+ if (!available.length) {
37
+ console.error(`Nenhum domínio em ${path.join(projectRoot, 'memory/30-domains')}.`);
38
+ console.error('Rode dentro de um projeto gerado, ou aponte com --project <path>.');
39
+ process.exit(1);
40
+ }
41
+ console.log('Uso: forja code:context <domínio> [--code] [--project <path>]\n');
42
+ console.log(`Domínios disponíveis: ${available.join(', ')}`);
43
+ return;
44
+ }
45
+ const pack = buildContextPack({ projectRoot, domain, includeCode });
46
+ if (!pack.found) {
47
+ console.error(`Domínio "${domain}" não tem context.md em ${projectRoot}.`);
48
+ if (available.length)
49
+ console.error(`Disponíveis: ${available.join(', ')}`);
50
+ process.exit(1);
51
+ }
52
+ // O pacote em si — pronto para colar no contexto de um agente.
53
+ console.log(`# Contexto do domínio: ${domain}\n`);
54
+ console.log(`> Mapa: ${pack.mapPath} (${pack.mapTokens} tokens)\n`);
55
+ console.log(pack.map);
56
+ if (includeCode) {
57
+ for (const c of pack.code) {
58
+ console.log(`\n\n---\n\n## ${c.path} (${c.tokens} tokens)\n`);
59
+ console.log('```ts');
60
+ console.log(c.content);
61
+ console.log('```');
62
+ }
63
+ }
64
+ // Rodapé de economia — o custo à mostra (dogfood do token:economy).
65
+ console.error(''); // separa do stdout colável
66
+ if (includeCode) {
67
+ console.error(`— pacote completo: ${pack.totalTokens} tokens (mapa ${pack.mapTokens} + código ${pack.codeTokens}, ${pack.code.length} arquivos).`);
68
+ }
69
+ else {
70
+ console.error(`— só o mapa: ${pack.mapTokens} tokens. Para editar, adicione o código com --code, ou o blast radius com \`forja code:impact <símbolo>\`.`);
71
+ }
72
+ }
73
+ main();
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * check:all — a bateria inteira de gates do framework, um veredito (SPEC-020).
4
+ *
5
+ * forja check:all coerência (doctor) + projeto gerado (smoke barato)
6
+ * forja check:all --full + tarball (release:check) + build do gerado (smoke --full)
7
+ *
8
+ * Não substitui os gates focados — os agrega. "A casa está coerente?" num comando só.
9
+ */
10
+ export {};
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * check:all — a bateria inteira de gates do framework, um veredito (SPEC-020).
4
+ *
5
+ * forja check:all coerência (doctor) + projeto gerado (smoke barato)
6
+ * forja check:all --full + tarball (release:check) + build do gerado (smoke --full)
7
+ *
8
+ * Não substitui os gates focados — os agrega. "A casa está coerente?" num comando só.
9
+ */
10
+ import { runGates, overallStatus } from "../lib/core/gates.js";
11
+ const TAG = { ok: 'OK ', warn: 'AVISO', fail: 'FALHA', skipped: '— ' };
12
+ async function main() {
13
+ const full = process.argv.includes('--full');
14
+ console.log(`\nForja check:all${full ? ' (--full)' : ''} — a bateria inteira, um veredito\n`);
15
+ if (full)
16
+ console.log('Inclui os gates caros (empacota o tarball, builda o backend gerado) — leva minutos.\n');
17
+ const groups = await runGates({ full });
18
+ for (const g of groups) {
19
+ console.log(`▚ ${g.name}`);
20
+ for (const r of g.results) {
21
+ console.log(` ${TAG[r.status] ?? r.status} ${String(r.id).padEnd(18)} ${r.detail}`);
22
+ }
23
+ console.log('');
24
+ }
25
+ const verdict = overallStatus(groups);
26
+ if (verdict === 'fail') {
27
+ const criticos = groups.flatMap((g) => g.results).filter((r) => r.status === 'fail' && r.severity === 'critical');
28
+ console.log(`REPROVADO — ${criticos.length} gate(s) crítico(s) falharam:`);
29
+ for (const r of criticos)
30
+ console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
31
+ process.exit(1);
32
+ }
33
+ if (verdict === 'warn') {
34
+ console.log('Aprovado com ressalvas. Nada crítico falhou.');
35
+ if (!full)
36
+ console.log('Para os gates caros (tarball, build do gerado), rode com --full.');
37
+ return;
38
+ }
39
+ console.log(full ? 'APROVADO — a bateria inteira passou.' : 'APROVADO. Para os gates caros, rode com --full.');
40
+ }
41
+ main().catch((err) => {
42
+ console.error(`\ncheck:all falhou: ${err.message}`);
43
+ process.exit(1);
44
+ });
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * memory:audit — os mapas de memória não mentem sobre o código (SPEC-017, ADR-0009).
4
+ *
5
+ * forja memory:audit audita os mapas do projeto no cwd
6
+ * forja memory:audit --project <path> aponta para outro projeto
7
+ *
8
+ * Para cada `memory/30-domains/<d>/context.md`, confere que todo path de código citado existe.
9
+ * Um mapa que aponta para arquivo renomeado/deletado engana com confiança — este comando reprova.
10
+ */
11
+ export {};
@@ -0,0 +1,49 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * memory:audit — os mapas de memória não mentem sobre o código (SPEC-017, ADR-0009).
4
+ *
5
+ * forja memory:audit audita os mapas do projeto no cwd
6
+ * forja memory:audit --project <path> aponta para outro projeto
7
+ *
8
+ * Para cada `memory/30-domains/<d>/context.md`, confere que todo path de código citado existe.
9
+ * Um mapa que aponta para arquivo renomeado/deletado engana com confiança — este comando reprova.
10
+ */
11
+ import path from 'node:path';
12
+ import { auditMemoryMaps, modulesWithoutMap } from "../lib/memory-audit.js";
13
+ function main() {
14
+ const i = process.argv.indexOf('--project');
15
+ const projectRoot = path.resolve(i >= 0 ? process.argv[i + 1] : process.cwd());
16
+ const audits = auditMemoryMaps(projectRoot);
17
+ if (!audits.length) {
18
+ console.log(`Nenhum mapa de domínio em ${path.join(projectRoot, 'memory/30-domains')}.`);
19
+ console.log('Rode dentro de um projeto gerado, ou aponte com --project <path>.');
20
+ return;
21
+ }
22
+ let totalDangling = 0;
23
+ for (const a of audits) {
24
+ if (a.dangling.length) {
25
+ totalDangling += a.dangling.length;
26
+ console.log(`✗ ${a.domain} (${a.mapPath}) — ${a.dangling.length}/${a.refs} referência(s) pendurada(s):`);
27
+ for (const d of a.dangling)
28
+ console.log(` ${d} — o mapa aponta, o arquivo não existe`);
29
+ }
30
+ else {
31
+ console.log(`✓ ${a.domain} — ${a.refs} referência(s), todas resolvem`);
32
+ }
33
+ }
34
+ // Direção reversa: módulo de código sem mapa. Aviso, não falha — é economia perdida, não mentira.
35
+ const semMapa = modulesWithoutMap(projectRoot);
36
+ if (semMapa.length) {
37
+ console.log('');
38
+ for (const m of semMapa) {
39
+ console.log(`⚠ módulo "${m}" não tem context.md — a economia de token da memória está perdida para ele`);
40
+ }
41
+ console.log(` crie memory/30-domains/${semMapa[0]}/context.md (o mapa do domínio).`);
42
+ }
43
+ if (totalDangling) {
44
+ console.log(`\nREPROVADO — ${totalDangling} referência(s) pendurada(s). O mapa mente; corrija o context.md ou o path.`);
45
+ process.exit(1);
46
+ }
47
+ console.log(`\nAPROVADO — todo mapa aponta para código que existe${semMapa.length ? ` (${semMapa.length} módulo(s) ainda sem mapa — veja acima)` : ''}.`);
48
+ }
49
+ main();
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * project-smoke — o gate do projeto gerado (SPEC-015).
4
+ *
5
+ * Responde a uma pergunta com evidência: **o que `forja project:new` gera é coerente?**
6
+ * Gera um projeto num diretório isolado e reprova se um template vazou, um `package.json` não
7
+ * parseia, a estrutura está incompleta — ou, no tier `--full`, se o backend não buildar.
8
+ *
9
+ * forja project:smoke tier barato (placeholders, JSON, estrutura) — roda no CI
10
+ * forja project:smoke -- --full + npm install && npm run build do backend gerado (lento, rede)
11
+ *
12
+ * É o `release:check` da saída do gerador, um nível acima do tarball.
13
+ */
14
+ export {};
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * project-smoke — o gate do projeto gerado (SPEC-015).
4
+ *
5
+ * Responde a uma pergunta com evidência: **o que `forja project:new` gera é coerente?**
6
+ * Gera um projeto num diretório isolado e reprova se um template vazou, um `package.json` não
7
+ * parseia, a estrutura está incompleta — ou, no tier `--full`, se o backend não buildar.
8
+ *
9
+ * forja project:smoke tier barato (placeholders, JSON, estrutura) — roda no CI
10
+ * forja project:smoke -- --full + npm install && npm run build do backend gerado (lento, rede)
11
+ *
12
+ * É o `release:check` da saída do gerador, um nível acima do tarball.
13
+ */
14
+ import { runProjectSmoke, worstStatus } from "../lib/core/project-smoke.js";
15
+ const TAG = { ok: 'OK ', warn: 'AVISO', fail: 'FALHA', skipped: '— ' };
16
+ async function main() {
17
+ const full = process.argv.includes('--full');
18
+ console.log(`\nForja project smoke${full ? ' (tier --full)' : ''}\n`);
19
+ console.log(`Gerando um projeto num diretório isolado${full ? ' e buildando o backend — isto leva minutos' : ''}.\n`);
20
+ const results = await runProjectSmoke({ full });
21
+ for (const r of results) {
22
+ console.log(`${TAG[r.status]} ${r.id.padEnd(16)} ${r.detail}`);
23
+ if (r.fix)
24
+ console.log(` corrigir: ${r.fix}`);
25
+ console.log('');
26
+ }
27
+ const verdict = worstStatus(results);
28
+ if (verdict === 'fail') {
29
+ const raiz = results.filter((r) => r.status === 'fail' && r.severity === 'critical');
30
+ console.log(`REPROVADO — ${raiz.length} falha(s) crítica(s). O gerador está entregando um projeto quebrado.`);
31
+ for (const r of raiz)
32
+ console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
33
+ process.exit(1);
34
+ }
35
+ if (verdict === 'warn') {
36
+ console.log('Aprovado com ressalvas.');
37
+ return;
38
+ }
39
+ console.log(full ? 'APROVADO — o projeto gerado instala e compila.' : 'APROVADO — o projeto gerado é coerente. Para provar o build, rode com --full.');
40
+ }
41
+ main().catch((err) => {
42
+ console.error(`\nproject-smoke falhou: ${err.message}`);
43
+ process.exit(1);
44
+ });
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * project:upgrade — traz peças novas de scaffold para um projeto já gerado (SPEC-018).
4
+ *
5
+ * forja project:upgrade dry-run: lista o que falta (cwd)
6
+ * forja project:upgrade --apply copia as peças novas
7
+ * forja project:upgrade --project <path> aponta para outro projeto
8
+ *
9
+ * Aditivo, nunca sobrescreve: só traz arquivos que o projeto não tem. O código do usuário é intocável.
10
+ */
11
+ export {};
@@ -0,0 +1,61 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * project:upgrade — traz peças novas de scaffold para um projeto já gerado (SPEC-018).
4
+ *
5
+ * forja project:upgrade dry-run: lista o que falta (cwd)
6
+ * forja project:upgrade --apply copia as peças novas
7
+ * forja project:upgrade --project <path> aponta para outro projeto
8
+ *
9
+ * Aditivo, nunca sobrescreve: só traz arquivos que o projeto não tem. O código do usuário é intocável.
10
+ */
11
+ import { execFileSync } from 'node:child_process';
12
+ import fs from 'node:fs';
13
+ import os from 'node:os';
14
+ import path from 'node:path';
15
+ import { fileURLToPath } from 'node:url';
16
+ import { planUpgrade, applyUpgrade } from "../lib/project-upgrade.js";
17
+ const __filename = fileURLToPath(import.meta.url);
18
+ const repoRoot = path.resolve(path.dirname(__filename), '..');
19
+ function main() {
20
+ const i = process.argv.indexOf('--project');
21
+ const target = path.resolve(i >= 0 ? process.argv[i + 1] : process.cwd());
22
+ const apply = process.argv.includes('--apply');
23
+ if (!fs.existsSync(path.join(target, 'AGENTS.md'))) {
24
+ console.error(`${target} não parece um projeto Forja (sem AGENTS.md).`);
25
+ console.error('Rode dentro de um projeto gerado, ou aponte com --project <path>.');
26
+ process.exit(1);
27
+ }
28
+ // Gera um scaffold fresco num tmp isolado, com o ambiente limpo (a lição do release:check).
29
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-upgrade-'));
30
+ const fresh = path.join(tmp, 'fresh');
31
+ try {
32
+ const env = { ...process.env };
33
+ delete env.NODE_PATH;
34
+ for (const k of Object.keys(env))
35
+ if (k.startsWith('npm_'))
36
+ delete env[k];
37
+ execFileSync(process.execPath, [path.join(repoRoot, 'bin', 'create-memory-nest-kit.ts'), fresh, '--force'], {
38
+ cwd: tmp,
39
+ env,
40
+ stdio: 'pipe',
41
+ });
42
+ const plan = planUpgrade(fresh, target);
43
+ if (!plan.newFiles.length) {
44
+ console.log(`Projeto já em dia — ${plan.existing} arquivo(s) de scaffold presentes, nenhuma peça nova.`);
45
+ return;
46
+ }
47
+ console.log(`${plan.newFiles.length} peça(s) de scaffold nova(s) que este projeto ainda não tem:\n`);
48
+ for (const rel of plan.newFiles)
49
+ console.log(` + ${rel}`);
50
+ if (!apply) {
51
+ console.log(`\nDry-run. Rode com --apply para copiar. Aditivo: nada existente é sobrescrito.`);
52
+ return;
53
+ }
54
+ const applied = applyUpgrade(fresh, target, plan);
55
+ console.log(`\n✓ ${applied.length} arquivo(s) copiado(s). Revise o diff antes de commitar.`);
56
+ }
57
+ finally {
58
+ fs.rmSync(tmp, { recursive: true, force: true });
59
+ }
60
+ }
61
+ main();
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * token-economy — mede, não argumenta (fecha a dívida do ADR-0027; ADR-0009 e ADR-0003).
4
+ *
5
+ * Dois eixos, porque a economia de token do Forja tem dois eixos e eles são diferentes:
6
+ *
7
+ * 1. ARQUITETURA (clean vs flat) — camadas custam tokens. Numa feature pequena, o flat é mais
8
+ * barato. É honesto, e desmente a versão ingênua de "Clean Architecture economiza tokens".
9
+ *
10
+ * 2. MEMÓRIA (frio vs quente) — o `context.md` é o mapa. Sem ele, um agente varre o código da
11
+ * fatia para localizar a regra; com ele, vai direto ao agregado. AQUI está a economia real do
12
+ * framework (ADR-0009), e ela COMPÕE: paga-se o scaffold uma vez, e o mapa economiza a cada
13
+ * tarefa futura pela vida do projeto.
14
+ *
15
+ * O `token:economy` sozinho não captura o custo de gerar do zero (isso é custo líquido, único). Ele
16
+ * captura o regime permanente — o projeto já levantado, onde a memória persistente paga de volta.
17
+ *
18
+ * Token ≈ bytes/4 (o mesmo proxy do resto do framework). Não é preciso; é reproduzível e honesto.
19
+ */
20
+ export {};