forjajs 1.3.1 → 1.5.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 (66) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.en.md +1 -0
  3. package/README.md +10 -4
  4. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  5. package/dist/bin/create-memory-nest-kit.d.ts +11 -0
  6. package/dist/bin/create-memory-nest-kit.js +5 -5
  7. package/dist/bin/forja.js +1 -1
  8. package/dist/bin/init-project.d.ts +12 -0
  9. package/dist/bin/init-project.js +2 -2
  10. package/dist/lib/code-context.d.ts +41 -0
  11. package/dist/lib/code-context.js +108 -0
  12. package/dist/lib/context-builder.d.ts +15 -5
  13. package/dist/lib/context-builder.js +5 -0
  14. package/dist/lib/core/checks.d.ts +3 -3
  15. package/dist/lib/core/doc-graph.d.ts +13 -0
  16. package/dist/lib/core/doc-graph.js +48 -1
  17. package/dist/lib/core/health.d.ts +3 -32
  18. package/dist/lib/core/health.js +29 -15
  19. package/dist/lib/core/project-smoke.d.ts +46 -0
  20. package/dist/lib/core/project-smoke.js +248 -0
  21. package/dist/lib/core/registry.d.ts +25 -0
  22. package/dist/lib/core/registry.js +37 -12
  23. package/dist/lib/core/release.d.ts +27 -14
  24. package/dist/lib/core/release.js +0 -8
  25. package/dist/lib/generators/memory-generator.d.ts +11 -6
  26. package/dist/lib/generators/memory-generator.js +45 -1
  27. package/dist/lib/generators/nest-generator.d.ts +8 -4
  28. package/dist/lib/generators/nest-generator.js +1 -1
  29. package/dist/lib/generators/readme-generator.d.ts +7 -4
  30. package/dist/lib/generators/readme-generator.js +2 -1
  31. package/dist/lib/governance-report.d.ts +1 -1
  32. package/dist/lib/memory-audit.d.ts +31 -0
  33. package/dist/lib/memory-audit.js +81 -0
  34. package/dist/lib/project-upgrade.d.ts +28 -0
  35. package/dist/lib/project-upgrade.js +74 -0
  36. package/dist/lib/utils/file-helpers.d.ts +10 -6
  37. package/dist/lib/validators/structure-validator.d.ts +49 -27
  38. package/dist/scripts/code-context.d.ts +12 -0
  39. package/dist/scripts/code-context.js +73 -0
  40. package/dist/scripts/dev.d.ts +2 -2
  41. package/dist/scripts/dev.js +1 -1
  42. package/dist/scripts/memory-audit.d.ts +11 -0
  43. package/dist/scripts/memory-audit.js +49 -0
  44. package/dist/scripts/project-smoke.d.ts +14 -0
  45. package/dist/scripts/project-smoke.js +44 -0
  46. package/dist/scripts/project-upgrade.d.ts +11 -0
  47. package/dist/scripts/project-upgrade.js +61 -0
  48. package/dist/scripts/query-universal-memory.js +1 -1
  49. package/dist/scripts/sprint-manager.js +1 -1
  50. package/dist/scripts/token-benchmark.js +1 -1
  51. package/dist/scripts/token-economy.d.ts +20 -0
  52. package/dist/scripts/token-economy.js +140 -0
  53. package/memory/90-decisions/0025-coerencia-da-documentacao.md +4 -0
  54. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  55. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  56. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  57. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  58. package/package.json +1 -1
  59. package/specs/code-context/spec.md +56 -0
  60. package/specs/memory-audit/spec.md +54 -0
  61. package/specs/project-smoke/spec.md +96 -0
  62. package/specs/project-upgrade/spec.md +58 -0
  63. package/specs/ts-migration/plan.md +9 -8
  64. package/specs/ts-migration/spec.md +1 -1
  65. package/dist/lib/templates/harness/code-intel.d.mts +0 -2
  66. package/dist/lib/templates/harness/code-intel.mjs +0 -126
@@ -38,11 +38,7 @@ import { fileURLToPath } from 'node:url';
38
38
  import { getWorkspaceDbPath, getWorkspaceInfo } from "../workspace.js";
39
39
  import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from "./checks.js";
40
40
  import { COMMANDS } from "./registry.js";
41
- import { scanCommands, scanLinks, projectCommands } from "./doc-graph.js";
42
- // Os contratos vivem em checks.mjs — importados, não redefinidos. As cópias locais eram resíduo da
43
- // extração do runner (SPEC-010) e já divergiam.
44
- /** @typedef {import('./checks.ts').Check} Check */
45
- /** @typedef {import('./checks.ts').Result} Result */
41
+ import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers } from "./doc-graph.js";
46
42
  /** @typedef {import('./checks.ts').Status} Status */
47
43
  // O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
48
44
  // aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
@@ -85,7 +81,6 @@ export function defaultEnv(overrides = {}) {
85
81
  * Classificamos por `err.code`, nunca pela mensagem: o texto do erro varia entre versões do Node,
86
82
  * e este check existe precisamente para sobreviver a troca de versão do Node.
87
83
  */
88
- /** @type {Check} */
89
84
  const nativeAbi = {
90
85
  id: 'native-abi',
91
86
  title: 'better-sqlite3 carrega no Node atual',
@@ -125,7 +120,6 @@ const nativeAbi = {
125
120
  return { status: 'ok', detail: `carrega em Node v${env.process.versions.node}`, fix: null };
126
121
  },
127
122
  };
128
- /** @type {Check} */
129
123
  const memoryDb = {
130
124
  id: 'memory-db',
131
125
  title: 'universal.db acessível',
@@ -196,7 +190,6 @@ function newestMarkdownMtime(env, dir, acc = { t: 0 }) {
196
190
  *
197
191
  * É `warn`, não `critical`: responder sobre memória velha atrapalha, mas não impede trabalho.
198
192
  */
199
- /** @type {Check} */
200
193
  const memoryFresh = {
201
194
  id: 'memory-fresh',
202
195
  title: 'índice em dia com memory/',
@@ -233,7 +226,6 @@ const memoryFresh = {
233
226
  * pensa" — um FORJA_WORKSPACE esquecido no ambiente aponta o framework para o workspace errado, e
234
227
  * tudo parece funcionar.
235
228
  */
236
- /** @type {Check} */
237
229
  const workspace = {
238
230
  id: 'workspace',
239
231
  title: 'workspace resolvido',
@@ -252,7 +244,6 @@ const workspace = {
252
244
  },
253
245
  };
254
246
  /** Compara o Node em uso com o `engines.node` declarado. Abaixo do mínimo, o resto é loteria. */
255
- /** @type {Check} */
256
247
  const nodeEngines = {
257
248
  id: 'node-engines',
258
249
  title: 'Node dentro de engines',
@@ -324,7 +315,6 @@ function packageName(specifier) {
324
315
  * Conservador de propósito: só olha import **estático** de script publicado. Import dinâmico não
325
316
  * conta (é o padrão do carregamento lazy, e lazy é justamente o que o ADR-0021 pediu).
326
317
  */
327
- /** @type {Check} */
328
318
  const runtimeDeps = {
329
319
  id: 'runtime-deps',
330
320
  title: 'deps de runtime declaradas',
@@ -398,7 +388,6 @@ const runtimeDeps = {
398
388
  * repo. O codegraph indexava código morto e respondia com confiança sobre ele. O path também
399
389
  * quebrava para qualquer outro contribuidor.
400
390
  */
401
- /** @type {Check} */
402
391
  const mcpJson = {
403
392
  id: 'mcp-json',
404
393
  title: '.mcp.json sem path absoluto',
@@ -437,7 +426,6 @@ const mcpJson = {
437
426
  * quebrou. É `critical`. A allowlist do projeto gerado é **derivada** dos geradores + boilerplates
438
427
  * (nunca literal), senão `start:dev`/`test:e2e` e afins dariam falso positivo.
439
428
  */
440
- /** @type {Check} */
441
429
  const docsCommands = {
442
430
  id: 'docs-commands',
443
431
  title: 'comandos citados na doc existem',
@@ -464,7 +452,6 @@ const docsCommands = {
464
452
  * Capacidade que ninguém documenta é capacidade obscura. `warn`, não `critical`: um comando
465
453
  * não-documentado atrapalha (o operador não sabe que existe), mas não impede trabalho.
466
454
  */
467
- /** @type {Check} */
468
455
  const commandsDocumented = {
469
456
  id: 'commands-documented',
470
457
  title: 'todo comando do registry é documentado',
@@ -487,7 +474,6 @@ const commandsDocumented = {
487
474
  },
488
475
  };
489
476
  /** Link relativo para o nada é step obscuro. `warn`: atrapalha a navegação, não impede trabalho. */
490
- /** @type {Check} */
491
477
  const docsLinks = {
492
478
  id: 'docs-links',
493
479
  title: 'links relativos da doc resolvem',
@@ -509,6 +495,33 @@ const docsLinks = {
509
495
  return { status: 'ok', detail: 'todo link relativo resolve', fix: null };
510
496
  },
511
497
  };
498
+ /**
499
+ * Referência a decisão que não existe é trilha que apodrece. Uma spec ou doc cita `ADR-0026`, o ADR
500
+ * nunca foi escrito (ou foi renumerado), e o paper trail mente em silêncio. `warn`, não `critical`:
501
+ * confunde o registro, não impede o framework de trabalhar — mesma família de `docs-links`.
502
+ */
503
+ const adrRefs = {
504
+ id: 'adr-refs',
505
+ title: 'toda citação ADR-NNNN aponta para um ADR existente',
506
+ severity: 'warn',
507
+ scope: 'repo',
508
+ probe(env) {
509
+ if (!isFrameworkRepo(env)) {
510
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
511
+ }
512
+ const existing = adrNumbers(env);
513
+ const dangling = scanAdrRefs(env).filter((r) => !existing.has(r.num));
514
+ if (dangling.length) {
515
+ const amostra = dangling.slice(0, 5).map((d) => `${d.ref} (${d.file}:${d.line})`).join(', ');
516
+ return {
517
+ status: 'warn',
518
+ detail: `${dangling.length} citação(ões) de ADR inexistente: ${amostra}`,
519
+ fix: 'escreva o ADR referenciado ou corrija o número no arquivo:linha indicado',
520
+ };
521
+ }
522
+ return { status: 'ok', detail: `toda referência a ADR resolve (${existing.size} ADRs)`, fix: null };
523
+ },
524
+ };
512
525
  /** @type {Check[]} */
513
526
  export const CHECKS = [
514
527
  nativeAbi,
@@ -521,6 +534,7 @@ export const CHECKS = [
521
534
  docsCommands,
522
535
  commandsDocumented,
523
536
  docsLinks,
537
+ adrRefs,
524
538
  ];
525
539
  /**
526
540
  * Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
@@ -0,0 +1,46 @@
1
+ /**
2
+ * lib/core/project-smoke.ts — o gate do projeto gerado.
3
+ *
4
+ * Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
5
+ * O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
6
+ * — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
7
+ *
8
+ * O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
9
+ * `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
10
+ * princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
11
+ *
12
+ * O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
13
+ */
14
+ import fs from 'node:fs';
15
+ import { worstStatus } from './checks.ts';
16
+ import type { Check } from './checks.ts';
17
+ export { worstStatus };
18
+ interface SmokeEnv {
19
+ root: string;
20
+ fs: typeof fs;
21
+ projectDir?: string;
22
+ full: boolean;
23
+ spawn: (cmd: string, args: string[], opts?: any) => {
24
+ stdout: string;
25
+ stderr: string;
26
+ code: number;
27
+ };
28
+ }
29
+ /**
30
+ * Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
31
+ * temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
32
+ */
33
+ export declare function withGeneratedProject<T>(fn: (ctx: {
34
+ projectDir: string;
35
+ }) => Promise<T> | T, { root, spawn }: {
36
+ root?: string;
37
+ spawn: SmokeEnv['spawn'];
38
+ }): Promise<T>;
39
+ /** @type {Check[]} */
40
+ export declare const SMOKE_CHECKS: Check[];
41
+ export declare function defaultEnv(overrides?: Partial<SmokeEnv>): SmokeEnv;
42
+ /** Gera um projeto isolado, roda os checks, limpa. */
43
+ export declare function runProjectSmoke({ full, env: overrides }?: {
44
+ full?: boolean;
45
+ env?: Partial<SmokeEnv>;
46
+ }): Promise<import("./checks.ts").Result[]>;
@@ -0,0 +1,248 @@
1
+ /**
2
+ * lib/core/project-smoke.ts — o gate do projeto gerado.
3
+ *
4
+ * Guarda a fronteira que `release:check` não vê, um nível acima: **o gerador mente sobre o projeto**.
5
+ * O `release:check` prova que o pacote `forjajs` instala e roda. Este prova que o que ele *gera*
6
+ * — via `create-memory-nest-kit` — é coerente e buildar. É a mesma classe da SPEC-010, na saída.
7
+ *
8
+ * O gerador escreve a partir de templates. Cada substituição é uma chance de mentira silenciosa: um
9
+ * `{{FEATURE}}` que vaza, um `package.json` que não parseia, uma estrutura de memória incompleta. O
10
+ * princípio é o mesmo do release: **grep não prova ausência; gerar e inspecionar prova.**
11
+ *
12
+ * O runner é o de `checks.ts`, o mesmo do doctor e do release. Uma máquina, três fronteiras.
13
+ */
14
+ import { execFileSync } from 'node:child_process';
15
+ import fs from 'node:fs';
16
+ import os from 'node:os';
17
+ import path from 'node:path';
18
+ import { fileURLToPath } from 'node:url';
19
+ import { runChecks as run, worstStatus } from "./checks.js";
20
+ // @ts-ignore — validador legado sem tipos exportados; usado só pela forma { isValid, errors }.
21
+ import { validateProjectStructure } from "../validators/structure-validator.js";
22
+ export { worstStatus };
23
+ const __filename = fileURLToPath(import.meta.url);
24
+ const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
25
+ /** Placeholders do gerador: identificadores MAIÚSCULOS entre chaves duplas (`{{FEATURE}}`). */
26
+ const PLACEHOLDER_RE = /\{\{[A-Z][A-Z0-9_]*\}\}/;
27
+ /**
28
+ * Gera um projeto num diretório temporário isolado e entrega o caminho ao callback. Limpa o
29
+ * temporário **sempre**, inclusive quando o callback lança — o mesmo contrato do `withCleanInstall`.
30
+ */
31
+ export async function withGeneratedProject(fn, { root = repoRoot, spawn }) {
32
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-smoke-'));
33
+ const projectDir = path.join(dir, 'smoke-proj');
34
+ try {
35
+ const gen = path.join(root, 'bin', 'create-memory-nest-kit.ts');
36
+ const res = spawn(process.execPath, [gen, projectDir, '--force'], { cwd: dir });
37
+ if (res.code !== 0) {
38
+ throw new Error(`o gerador saiu com código ${res.code}:\n${(res.stderr || res.stdout).slice(0, 800)}`);
39
+ }
40
+ return await fn({ projectDir });
41
+ }
42
+ finally {
43
+ fs.rmSync(dir, { recursive: true, force: true });
44
+ }
45
+ }
46
+ // ---------------------------------------------------------------------------
47
+ // Walk — arquivos de texto do projeto, menos node_modules
48
+ // ---------------------------------------------------------------------------
49
+ function walkFiles(env, dir, out) {
50
+ let entries;
51
+ try {
52
+ entries = env.fs.readdirSync(dir);
53
+ }
54
+ catch {
55
+ return out;
56
+ }
57
+ for (const entry of entries) {
58
+ if (entry === 'node_modules' || entry === '.git')
59
+ continue;
60
+ const p = path.join(dir, entry);
61
+ let st;
62
+ try {
63
+ st = env.fs.statSync(p);
64
+ }
65
+ catch {
66
+ continue;
67
+ }
68
+ if (st.isDirectory())
69
+ walkFiles(env, p, out);
70
+ else
71
+ out.push(p);
72
+ }
73
+ return out;
74
+ }
75
+ /** Lê como texto; devolve null para binário/ilegível (não é competência deste gate). */
76
+ function readText(env, file) {
77
+ try {
78
+ const buf = env.fs.readFileSync(file);
79
+ if (buf.includes(0))
80
+ return null; // binário
81
+ return buf.toString('utf8');
82
+ }
83
+ catch {
84
+ return null;
85
+ }
86
+ }
87
+ // ---------------------------------------------------------------------------
88
+ // Checks
89
+ // ---------------------------------------------------------------------------
90
+ /** Se o projeto não nasceu, todo o resto é irrelevante — daí os outros dependerem deste. */
91
+ const generated = {
92
+ id: 'generated',
93
+ title: 'o gerador produz um projeto',
94
+ severity: 'critical',
95
+ probe(env) {
96
+ const marker = path.join(env.projectDir, 'AGENTS.md');
97
+ return env.fs.existsSync(marker)
98
+ ? { status: 'ok', detail: `projeto gerado em ${path.basename(env.projectDir)}`, fix: null }
99
+ : { status: 'fail', detail: 'o gerador rodou mas não produziu AGENTS.md', fix: 'investigue create-memory-nest-kit' };
100
+ },
101
+ };
102
+ /** O bug mais barato de introduzir e o mais visível ao usuário: um template não substituído. */
103
+ const noPlaceholders = {
104
+ id: 'no-placeholders',
105
+ title: 'nenhum placeholder {{...}} vazou',
106
+ severity: 'critical',
107
+ dependsOn: 'generated',
108
+ probe(env) {
109
+ const leaked = [];
110
+ for (const file of walkFiles(env, env.projectDir, [])) {
111
+ const src = readText(env, file);
112
+ if (src == null)
113
+ continue;
114
+ const m = src.match(PLACEHOLDER_RE);
115
+ if (m)
116
+ leaked.push(`${path.relative(env.projectDir, file)} → ${m[0]}`);
117
+ }
118
+ if (leaked.length) {
119
+ return {
120
+ status: 'fail',
121
+ detail: `${leaked.length} placeholder(s) não substituído(s): ${leaked.slice(0, 3).join('; ')}`,
122
+ fix: 'o gerador esqueceu um replace — confira o fillTemplate do gerador correspondente',
123
+ };
124
+ }
125
+ return { status: 'ok', detail: 'todo template foi substituído', fix: null };
126
+ },
127
+ };
128
+ /** `package.json` gerado que não parseia entrega um projeto morto no `npm install`. */
129
+ const jsonValid = {
130
+ id: 'json-valid',
131
+ title: 'todo package.json gerado é JSON válido',
132
+ severity: 'critical',
133
+ dependsOn: 'generated',
134
+ probe(env) {
135
+ const broken = [];
136
+ let total = 0;
137
+ for (const file of walkFiles(env, env.projectDir, [])) {
138
+ if (path.basename(file) !== 'package.json')
139
+ continue;
140
+ total += 1;
141
+ const src = readText(env, file);
142
+ try {
143
+ JSON.parse(src ?? '');
144
+ }
145
+ catch (e) {
146
+ broken.push(`${path.relative(env.projectDir, file)}: ${e.message}`);
147
+ }
148
+ }
149
+ if (broken.length) {
150
+ return { status: 'fail', detail: `package.json inválido: ${broken.join('; ')}`, fix: 'corrija o template do package.json no gerador' };
151
+ }
152
+ return { status: 'ok', detail: `${total} package.json válido(s)`, fix: null };
153
+ },
154
+ };
155
+ /** Reusa o validador que o próprio gerador roda no fim — uma máquina, não duas (SPEC-009). */
156
+ const structure = {
157
+ id: 'structure',
158
+ title: 'a estrutura do projeto gerado é íntegra',
159
+ severity: 'critical',
160
+ dependsOn: 'generated',
161
+ probe(env) {
162
+ const report = validateProjectStructure(env.projectDir, { includeNest: true });
163
+ if (!report.isValid) {
164
+ return {
165
+ status: 'fail',
166
+ detail: `${report.errors.length} problema(s): ${report.errors.slice(0, 3).join('; ')}`,
167
+ fix: 'um arquivo/diretório crítico não foi gerado — confira o gerador de estrutura',
168
+ };
169
+ }
170
+ return { status: 'ok', detail: 'estrutura de memória e backend completas', fix: null };
171
+ },
172
+ };
173
+ /**
174
+ * O projeto gerado **herda o gate** dos mapas (ADR-0030): `scripts/check-memory-maps.mjs` viaja com
175
+ * ele. Sem isso, a coerência mapa↔código do usuário volta a viver por disciplina. Este check prova
176
+ * que a propagação aconteceu — o framework não só tem gates, ele os transmite.
177
+ */
178
+ const gateInherited = {
179
+ id: 'gate-inherited',
180
+ title: 'o projeto gerado carrega o gate dos mapas (ADR-0030)',
181
+ severity: 'critical',
182
+ dependsOn: 'generated',
183
+ probe(env) {
184
+ const gate = path.join(env.projectDir, 'scripts', 'check-memory-maps.mjs');
185
+ return env.fs.existsSync(gate)
186
+ ? { status: 'ok', detail: 'scripts/check-memory-maps.mjs presente — o invariante viaja com o projeto', fix: null }
187
+ : { status: 'fail', detail: 'o projeto gerado não trouxe o gate dos mapas', fix: 'confira o scriptTemplates do memory-generator' };
188
+ },
189
+ };
190
+ /**
191
+ * A prova final, e a mais cara: o backend gerado **buildar de verdade**. Só no tier `--full` —
192
+ * `npm install` de um projeto NestJS é lento e usa rede, então roda antes de release, não a cada
193
+ * commit. É o análogo do clean-install do `release:check`, na saída do gerador.
194
+ */
195
+ const builds = {
196
+ id: 'builds',
197
+ title: 'o backend gerado instala e buildar (--full)',
198
+ severity: 'critical',
199
+ dependsOn: 'structure',
200
+ probe(env) {
201
+ if (!env.full) {
202
+ return { status: 'skipped', detail: 'tier --full desligado (custo de rede); rode com --full antes de publicar', fix: null };
203
+ }
204
+ const backend = path.join(env.projectDir, 'backend');
205
+ if (!env.fs.existsSync(path.join(backend, 'package.json'))) {
206
+ return { status: 'skipped', detail: 'sem backend/ (projeto só-memória)', fix: null };
207
+ }
208
+ const install = env.spawn('npm', ['install', '--no-audit', '--no-fund'], { cwd: backend });
209
+ if (install.code !== 0) {
210
+ return { status: 'fail', detail: `npm install falhou no backend gerado:\n${(install.stderr || install.stdout).slice(0, 500)}`, fix: 'confira as dependências no template do package.json' };
211
+ }
212
+ const build = env.spawn('npm', ['run', 'build'], { cwd: backend });
213
+ if (build.code !== 0) {
214
+ return { status: 'fail', detail: `npm run build falhou no backend gerado:\n${(build.stderr || build.stdout).slice(0, 500)}`, fix: 'o código gerado não compila — confira os templates do nest-generator' };
215
+ }
216
+ return { status: 'ok', detail: 'backend gerado instala e compila', fix: null };
217
+ },
218
+ };
219
+ /** @type {Check[]} */
220
+ export const SMOKE_CHECKS = [generated, noPlaceholders, jsonValid, structure, gateInherited, builds];
221
+ export function defaultEnv(overrides = {}) {
222
+ return {
223
+ root: repoRoot,
224
+ fs,
225
+ full: false,
226
+ spawn: (cmd, args, opts) => {
227
+ // Isolamento como no release: sem NODE_PATH nem npm_config_* herdados vazando para o install.
228
+ const env = { ...process.env };
229
+ delete env.NODE_PATH;
230
+ for (const key of Object.keys(env))
231
+ if (key.startsWith('npm_'))
232
+ delete env[key];
233
+ try {
234
+ return { stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', env, ...opts }), stderr: '', code: 0 };
235
+ }
236
+ catch (err) {
237
+ const e = err;
238
+ return { stdout: e.stdout || '', stderr: e.stderr || String(err), code: e.status ?? 1 };
239
+ }
240
+ },
241
+ ...overrides,
242
+ };
243
+ }
244
+ /** Gera um projeto isolado, roda os checks, limpa. */
245
+ export async function runProjectSmoke({ full = false, env: overrides = {} } = {}) {
246
+ const base = defaultEnv({ full, ...overrides });
247
+ return withGeneratedProject(({ projectDir }) => run({ checks: SMOKE_CHECKS, env: { ...base, projectDir } }), { root: base.root, spawn: base.spawn });
248
+ }
@@ -54,6 +54,11 @@ export declare const COMMANDS: {
54
54
  node: string;
55
55
  args: string[];
56
56
  };
57
+ 'project:upgrade': {
58
+ domain: string;
59
+ desc: string;
60
+ node: string;
61
+ };
57
62
  'workspace:project:check': {
58
63
  domain: string;
59
64
  desc: string;
@@ -156,6 +161,11 @@ export declare const COMMANDS: {
156
161
  node: string;
157
162
  args: string[];
158
163
  };
164
+ 'code:context': {
165
+ domain: string;
166
+ desc: string;
167
+ node: string;
168
+ };
159
169
  'code:index': {
160
170
  domain: string;
161
171
  desc: string;
@@ -212,6 +222,11 @@ export declare const COMMANDS: {
212
222
  desc: string;
213
223
  node: string;
214
224
  };
225
+ 'memory:audit': {
226
+ domain: string;
227
+ desc: string;
228
+ node: string;
229
+ };
215
230
  'context:smart': {
216
231
  domain: string;
217
232
  desc: string;
@@ -253,6 +268,11 @@ export declare const COMMANDS: {
253
268
  desc: string;
254
269
  node: string;
255
270
  };
271
+ 'token:economy': {
272
+ domain: string;
273
+ desc: string;
274
+ node: string;
275
+ };
256
276
  'project:check': {
257
277
  domain: string;
258
278
  desc: string;
@@ -268,6 +288,11 @@ export declare const COMMANDS: {
268
288
  desc: string;
269
289
  node: string;
270
290
  };
291
+ 'project:smoke': {
292
+ domain: string;
293
+ desc: string;
294
+ node: string;
295
+ };
271
296
  'project:dashboard': {
272
297
  domain: string;
273
298
  desc: string;
@@ -29,7 +29,7 @@ export function resolveScript(root, node) {
29
29
  if (fs.existsSync(direct))
30
30
  return direct;
31
31
  const base = direct.replace(/\.(mjs|cjs|js|ts)$/, '');
32
- for (const ext of ['.ts', '.js', '.ts']) {
32
+ for (const ext of ['.ts', '.js', '.mjs']) {
33
33
  if (fs.existsSync(base + ext))
34
34
  return base + ext;
35
35
  }
@@ -67,6 +67,11 @@ export const COMMANDS = {
67
67
  node: 'scripts/agent-harness.ts',
68
68
  args: ['project:list'],
69
69
  },
70
+ 'project:upgrade': {
71
+ domain: 'workspace',
72
+ desc: 'Traz peças novas de scaffold para um projeto gerado — aditivo (SPEC-018). --apply para copiar',
73
+ node: 'scripts/project-upgrade.ts',
74
+ },
70
75
  'workspace:project:check': {
71
76
  domain: 'workspace',
72
77
  desc: 'Valida padrões em um projeto do workspace',
@@ -132,19 +137,19 @@ export const COMMANDS = {
132
137
  'sprint:start': {
133
138
  domain: 'gsd',
134
139
  desc: 'Inicia sprint',
135
- node: 'scripts/sprint-manager.js',
140
+ node: 'scripts/sprint-manager.ts',
136
141
  args: ['start'],
137
142
  },
138
143
  'sprint:status': {
139
144
  domain: 'gsd',
140
145
  desc: 'Status da sprint atual',
141
- node: 'scripts/sprint-manager.js',
146
+ node: 'scripts/sprint-manager.ts',
142
147
  args: ['status'],
143
148
  },
144
149
  'sprint:complete': {
145
150
  domain: 'gsd',
146
151
  desc: 'Encerra sprint',
147
- node: 'scripts/sprint-manager.js',
152
+ node: 'scripts/sprint-manager.ts',
148
153
  args: ['complete'],
149
154
  },
150
155
  // --- Design ---------------------------------------------------------------
@@ -173,6 +178,11 @@ export const COMMANDS = {
173
178
  node: 'scripts/agent-harness.ts',
174
179
  args: ['code:impact'],
175
180
  },
181
+ 'code:context': {
182
+ domain: 'code',
183
+ desc: 'Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009)',
184
+ node: 'scripts/code-context.ts',
185
+ },
176
186
  'code:index': {
177
187
  domain: 'code',
178
188
  desc: 'Inicializa índice codegraph',
@@ -201,19 +211,19 @@ export const COMMANDS = {
201
211
  'sync:universal': {
202
212
  domain: 'memoria',
203
213
  desc: 'Reindexa a memória universal (SQLite FTS5)',
204
- node: 'scripts/sync-universal-memory.js',
214
+ node: 'scripts/sync-universal-memory.ts',
205
215
  gates: ['workspace-warn'],
206
216
  },
207
217
  'query:universal': {
208
218
  domain: 'memoria',
209
219
  desc: 'Busca FTS5 na memória universal',
210
- node: 'scripts/query-universal-memory.js',
220
+ node: 'scripts/query-universal-memory.ts',
211
221
  gates: ['workspace-warn'],
212
222
  },
213
223
  'memory:compress': {
214
224
  domain: 'memoria',
215
225
  desc: 'Arquiva runs antigos e compacta memória de projeto',
216
- node: 'scripts/compress-project-memory.js',
226
+ node: 'scripts/compress-project-memory.ts',
217
227
  },
218
228
  'memory:vacuum': {
219
229
  domain: 'memoria',
@@ -228,13 +238,18 @@ export const COMMANDS = {
228
238
  'memory:extract': {
229
239
  domain: 'memoria',
230
240
  desc: 'Extrai conhecimento global da memória',
231
- node: 'scripts/extract-global-knowledge.js',
241
+ node: 'scripts/extract-global-knowledge.ts',
242
+ },
243
+ 'memory:audit': {
244
+ domain: 'memoria',
245
+ desc: 'Coerência mapa↔código: mapa não cita código morto (falha) + módulo sem mapa (aviso). SPEC-017',
246
+ node: 'scripts/memory-audit.ts',
232
247
  },
233
248
  // --- Contexto & token economy ---------------------------------------------
234
249
  'context:smart': {
235
250
  domain: 'contexto',
236
251
  desc: 'Gera smart-context (3 modos, ADR-0003)',
237
- node: 'scripts/build-smart-context.js',
252
+ node: 'scripts/build-smart-context.ts',
238
253
  gates: ['workspace-warn'],
239
254
  },
240
255
  'context:budget': {
@@ -272,11 +287,16 @@ export const COMMANDS = {
272
287
  desc: 'Benchmark de consumo de tokens',
273
288
  node: 'scripts/token-benchmark.ts',
274
289
  },
290
+ 'token:economy': {
291
+ domain: 'contexto',
292
+ desc: 'Economia de token: eixos arquitetura + memória; --project mede seus domínios reais (ADR-0009/0027)',
293
+ node: 'scripts/token-economy.ts',
294
+ },
275
295
  // --- Governança & qualidade ---------------------------------------------------
276
296
  'project:check': {
277
297
  domain: 'governanca',
278
298
  desc: 'Standards check do framework (pre-commit)',
279
- node: 'scripts/check-standards.js',
299
+ node: 'scripts/check-standards.ts',
280
300
  },
281
301
  'tools:doctor': {
282
302
  domain: 'governanca',
@@ -288,10 +308,15 @@ export const COMMANDS = {
288
308
  desc: 'Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito',
289
309
  node: 'scripts/release-check.ts',
290
310
  },
311
+ 'project:smoke': {
312
+ domain: 'governanca',
313
+ desc: 'Gate do projeto gerado: gera isolado e prova que é coerente (SPEC-015). --full instala e builda o backend',
314
+ node: 'scripts/project-smoke.ts',
315
+ },
291
316
  'project:dashboard': {
292
317
  domain: 'governanca',
293
318
  desc: 'Gera dashboard estático de status',
294
- node: 'scripts/generate-dashboard.js',
319
+ node: 'scripts/generate-dashboard.ts',
295
320
  },
296
321
  'audit:sync': {
297
322
  domain: 'governanca',
@@ -312,6 +337,6 @@ export const COMMANDS = {
312
337
  'init:project': {
313
338
  domain: 'geracao',
314
339
  desc: 'Gera projeto direto num path (prefira project:new)',
315
- node: 'bin/init-project.js',
340
+ node: 'bin/init-project.ts',
316
341
  },
317
342
  };