forjajs 1.2.0 → 1.3.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 (132) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +25 -0
  3. package/README.en.md +5 -0
  4. package/README.md +5 -0
  5. package/dist/bin/create-memory-nest-kit.d.ts +2 -0
  6. package/dist/bin/create-memory-nest-kit.js +110 -0
  7. package/dist/bin/forja.d.ts +13 -0
  8. package/dist/bin/forja.js +136 -0
  9. package/dist/bin/init-project.d.ts +2 -0
  10. package/dist/bin/init-project.js +516 -0
  11. package/dist/lib/audit.d.ts +67 -0
  12. package/dist/lib/audit.js +143 -0
  13. package/dist/lib/context-builder.d.ts +58 -0
  14. package/dist/lib/context-builder.js +233 -0
  15. package/dist/lib/core/checks.d.ts +91 -0
  16. package/dist/lib/core/checks.js +119 -0
  17. package/dist/lib/core/doc-graph.d.ts +60 -0
  18. package/dist/lib/core/doc-graph.js +235 -0
  19. package/dist/lib/core/health.d.ts +103 -0
  20. package/dist/lib/core/health.js +538 -0
  21. package/dist/lib/core/registry.d.ts +296 -0
  22. package/dist/lib/core/registry.js +317 -0
  23. package/dist/lib/core/release.d.ts +334 -0
  24. package/dist/lib/core/release.js +465 -0
  25. package/dist/lib/generators/memory-generator.d.ts +83 -0
  26. package/{lib → dist/lib}/generators/memory-generator.js +107 -178
  27. package/dist/lib/generators/nest-generator.d.ts +15 -0
  28. package/{lib → dist/lib}/generators/nest-generator.js +47 -71
  29. package/dist/lib/generators/readme-generator.d.ts +15 -0
  30. package/{lib → dist/lib}/generators/readme-generator.js +9 -14
  31. package/dist/lib/governance-report.d.ts +49 -0
  32. package/dist/lib/governance-report.js +170 -0
  33. package/dist/lib/templates/harness/code-intel.d.mts +2 -0
  34. package/dist/lib/templates/harness/code-intel.mjs +126 -0
  35. package/dist/lib/utils/file-helpers.d.ts +9 -0
  36. package/dist/lib/utils/file-helpers.js +34 -0
  37. package/dist/lib/validators/structure-validator.d.ts +48 -0
  38. package/dist/lib/validators/structure-validator.js +232 -0
  39. package/dist/lib/workspace.d.ts +40 -0
  40. package/dist/lib/workspace.js +174 -0
  41. package/dist/scripts/agent-harness.d.ts +2 -0
  42. package/dist/scripts/agent-harness.js +556 -0
  43. package/dist/scripts/agent-router.d.ts +30 -0
  44. package/dist/scripts/agent-router.js +208 -0
  45. package/dist/scripts/audit-query.d.ts +2 -0
  46. package/dist/scripts/audit-query.js +43 -0
  47. package/dist/scripts/audit-sync.d.ts +2 -0
  48. package/dist/scripts/audit-sync.js +19 -0
  49. package/dist/scripts/build-smart-context.d.ts +1 -0
  50. package/dist/scripts/build-smart-context.js +75 -0
  51. package/dist/scripts/check-standards.d.ts +1 -0
  52. package/dist/scripts/check-standards.js +87 -0
  53. package/dist/scripts/compress-memory.d.ts +16 -0
  54. package/dist/scripts/compress-memory.js +157 -0
  55. package/dist/scripts/compress-project-memory.d.ts +1 -0
  56. package/dist/scripts/compress-project-memory.js +48 -0
  57. package/dist/scripts/context-ops.d.ts +2 -0
  58. package/dist/scripts/context-ops.js +464 -0
  59. package/dist/scripts/dev.d.ts +96 -0
  60. package/dist/scripts/dev.js +312 -0
  61. package/dist/scripts/extract-global-knowledge.d.ts +1 -0
  62. package/dist/scripts/extract-global-knowledge.js +43 -0
  63. package/dist/scripts/generate-dashboard.d.ts +1 -0
  64. package/dist/scripts/generate-dashboard.js +48 -0
  65. package/dist/scripts/governance-dashboard.d.ts +2 -0
  66. package/dist/scripts/governance-dashboard.js +36 -0
  67. package/dist/scripts/hook-guard-paths.d.ts +17 -0
  68. package/dist/scripts/hook-guard-paths.js +68 -0
  69. package/dist/scripts/hook-post-edit.d.ts +20 -0
  70. package/dist/scripts/hook-post-edit.js +70 -0
  71. package/dist/scripts/hook-session-start.d.ts +17 -0
  72. package/dist/scripts/hook-session-start.js +108 -0
  73. package/dist/scripts/hook-user-prompt.d.ts +22 -0
  74. package/dist/scripts/hook-user-prompt.js +193 -0
  75. package/dist/scripts/memory-schema.d.ts +6 -0
  76. package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
  77. package/dist/scripts/query-universal-memory.d.ts +1 -0
  78. package/dist/scripts/query-universal-memory.js +44 -0
  79. package/dist/scripts/release-check.d.ts +14 -0
  80. package/dist/scripts/release-check.js +48 -0
  81. package/dist/scripts/spec-cli.d.ts +29 -0
  82. package/dist/scripts/spec-cli.js +261 -0
  83. package/dist/scripts/sprint-manager.d.ts +1 -0
  84. package/dist/scripts/sprint-manager.js +187 -0
  85. package/dist/scripts/sync-universal-memory.d.ts +1 -0
  86. package/dist/scripts/sync-universal-memory.js +277 -0
  87. package/dist/scripts/token-benchmark.d.ts +20 -0
  88. package/dist/scripts/token-benchmark.js +181 -0
  89. package/dist/scripts/tools-doctor.d.ts +20 -0
  90. package/dist/scripts/tools-doctor.js +120 -0
  91. package/memory/90-decisions/0028-governanca-visivel.md +84 -0
  92. package/package.json +54 -56
  93. package/specs/governanca-visivel/plan.md +122 -0
  94. package/specs/governanca-visivel/spec.md +112 -0
  95. package/specs/governanca-visivel/tasks.md +60 -0
  96. package/specs/ts-migration/plan.md +24 -13
  97. package/bin/create-memory-nest-kit.js +0 -125
  98. package/bin/forja.mjs +0 -143
  99. package/bin/init-project.js +0 -612
  100. package/lib/context-builder.js +0 -257
  101. package/lib/core/checks.mjs +0 -155
  102. package/lib/core/doc-graph.mjs +0 -231
  103. package/lib/core/health.mjs +0 -577
  104. package/lib/core/registry.mjs +0 -312
  105. package/lib/core/release.mjs +0 -492
  106. package/lib/templates/harness/code-intel.mjs +0 -119
  107. package/lib/templates/harness/mcp.json +0 -10
  108. package/lib/utils/file-helpers.js +0 -40
  109. package/lib/validators/structure-validator.js +0 -253
  110. package/lib/workspace.mjs +0 -213
  111. package/scripts/agent-harness.mjs +0 -580
  112. package/scripts/agent-router.mjs +0 -189
  113. package/scripts/build-smart-context.js +0 -87
  114. package/scripts/check-standards.js +0 -98
  115. package/scripts/compress-memory.mjs +0 -198
  116. package/scripts/compress-project-memory.js +0 -58
  117. package/scripts/context-ops.mjs +0 -466
  118. package/scripts/dev.mjs +0 -349
  119. package/scripts/extract-global-knowledge.js +0 -52
  120. package/scripts/generate-dashboard.js +0 -59
  121. package/scripts/hook-guard-paths.mjs +0 -76
  122. package/scripts/hook-post-edit.mjs +0 -79
  123. package/scripts/hook-session-start.mjs +0 -104
  124. package/scripts/hook-user-prompt.mjs +0 -185
  125. package/scripts/pre-commit.sh +0 -102
  126. package/scripts/query-universal-memory.js +0 -50
  127. package/scripts/release-check.mjs +0 -56
  128. package/scripts/spec-cli.mjs +0 -261
  129. package/scripts/sprint-manager.js +0 -200
  130. package/scripts/sync-universal-memory.js +0 -286
  131. package/scripts/token-benchmark.mjs +0 -203
  132. package/scripts/tools-doctor.mjs +0 -132
@@ -0,0 +1,465 @@
1
+ /**
2
+ * lib/core/release.mjs — o gate do tarball.
3
+ *
4
+ * Guarda a fronteira que `health.mjs` não vê: **o repositório mente sobre o pacote**. No repo tudo
5
+ * resolve — `node_modules` tem as devDeps, todo arquivo está presente, o `cwd` é a raiz. Nada disso
6
+ * vale para quem roda `npm i -g forjajs`. Essa fronteira já cedeu três vezes (SPEC-010):
7
+ *
8
+ * ADR-0021 `better-sqlite3` como devDependency → dez comandos com ERR_MODULE_NOT_FOUND na
9
+ * instalação limpa. O `forja` sem argumentos funcionava, o que mascarava a quebra.
10
+ * v1.1.1 `otplib` e `qrcode` publicados sem jamais existirem no git — `npm publish` empacota o
11
+ * disco, não o commit.
12
+ * v1.1.3 `docs/dashboard.md` e o script publicados sem a pasta `dashboard/`.
13
+ *
14
+ * O princípio que organiza tudo aqui: **grep não prova ausência; instalação prova.** Por isso o
15
+ * gate empacota e instala de verdade, e por isso ele é lento — e tudo bem ser lento, porque roda
16
+ * antes de publicar, não a cada commit.
17
+ *
18
+ * O runner é o de `checks.mjs`, o mesmo do doctor. Uma máquina, duas fronteiras.
19
+ */
20
+ import { execFileSync } from 'node:child_process';
21
+ import fs from 'node:fs';
22
+ import os from 'node:os';
23
+ import path from 'node:path';
24
+ import { fileURLToPath } from 'node:url';
25
+ import { runChecks as run, worstStatus, stripTemplateLiterals } from "./checks.js";
26
+ /** @typedef {import('./checks.ts').Check} Check */
27
+ import { COMMANDS, resolveScript } from "./registry.js";
28
+ export { worstStatus };
29
+ const __filename = fileURLToPath(import.meta.url);
30
+ const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
31
+ /** Assinaturas de tarball quebrado. Exit code não serve — ver `smokeCommands`. */
32
+ const LOADER_ERRORS = /ERR_MODULE_NOT_FOUND|ERR_DLOPEN_FAILED|Cannot find module|ERR_PACKAGE_PATH_NOT_EXPORTED/;
33
+ function git(args, cwd = repoRoot) {
34
+ return execFileSync('git', args, { cwd, encoding: 'utf8' });
35
+ }
36
+ /**
37
+ * Empacota o repo e instala o tarball num diretório temporário isolado.
38
+ *
39
+ * Isolamento importa: um gate que enxerga o `node_modules` do repo mente verde. É justamente o
40
+ * `NODE_PATH` herdado e o `node_modules` vizinho que fariam um `import` quebrado resolver mesmo
41
+ * assim — e a quebra só apareceria na máquina do usuário.
42
+ *
43
+ * Limpa o temporário **sempre**, inclusive quando o callback lança.
44
+ *
45
+ * @template T
46
+ * @param {(ctx: { pkgDir: string, installDir: string }) => Promise<T>|T} fn
47
+ * @returns {Promise<T>}
48
+ */
49
+ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
50
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-release-'));
51
+ // Isolamento de verdade — e ele vaza por onde não se espera.
52
+ //
53
+ // `NODE_PATH` é o óbvio. O traiçoeiro é o `npm_config_*`: quando o gate roda de dentro de um
54
+ // script npm (e o `prepublishOnly` é exatamente isso), o npm injeta dezenas dessas variáveis no
55
+ // ambiente. Elas carregam o `local_prefix` do repo e, sob `npm publish --dry-run`, um
56
+ // `npm_config_dry_run=true` que faz o `npm install` interno não instalar nada.
57
+ //
58
+ // Sem esta limpeza, o gate passa localmente e quebra justamente no `prepublishOnly` — o único
59
+ // lugar onde ele precisa funcionar.
60
+ const env = { ...process.env };
61
+ delete env.NODE_PATH;
62
+ for (const key of Object.keys(env)) {
63
+ if (key.startsWith('npm_'))
64
+ delete env[key];
65
+ }
66
+ const npm = (args, cwd) => {
67
+ try {
68
+ return execFileSync('npm', args, { cwd, encoding: 'utf8', env, stdio: 'pipe' });
69
+ }
70
+ catch (err) {
71
+ // Engolir o stderr aqui cega o diagnóstico exatamente quando ele importa.
72
+ const e = /** @type {any} */ (err);
73
+ const saida = `${e.stdout || ''}${e.stderr || ''}`.trim();
74
+ throw new Error(`npm ${args[0]} falhou em ${cwd}:\n${saida || e.message}`);
75
+ }
76
+ };
77
+ try {
78
+ // Antes de empacotar: se o pacote publica dist/ (SPEC-012 Fase 3), constrói o dist/ agora.
79
+ //
80
+ // `npm publish` empacota o disco, e o disco só tem dist/ depois do `tsc`. Buildar aqui deixa o
81
+ // gate self-contained: a mesma prova roda no prepublishOnly e no CI sem um step de build
82
+ // separado que alguém possa esquecer — e sem acoplar a prova a uma edição do workflow. Se o
83
+ // build falha (erro de tipo), o `npm` abaixo lança com o stderr do tsc e o gate reprova claro.
84
+ const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
85
+ const shipsDist = (manifest.files || []).some((f) => f.replace(/\/+$/, '') === 'dist');
86
+ if (shipsDist && manifest.scripts?.build)
87
+ npm(['run', 'build'], root);
88
+ const tgz = npm(['pack', '--silent', '--pack-destination', dir], root)
89
+ .trim()
90
+ .split('\n')
91
+ .pop();
92
+ if (!tgz)
93
+ throw new Error('npm pack não produziu um tarball');
94
+ npm(['init', '-y'], dir);
95
+ npm(['install', path.join(dir, tgz)], dir);
96
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
97
+ const pkgDir = path.join(dir, 'node_modules', pkg.name);
98
+ return await fn({ pkgDir, installDir: dir });
99
+ }
100
+ finally {
101
+ fs.rmSync(dir, { recursive: true, force: true });
102
+ }
103
+ }
104
+ // ---------------------------------------------------------------------------
105
+ // Checks
106
+ // ---------------------------------------------------------------------------
107
+ /**
108
+ * A falha da v1.1.1, e a única que nenhuma instalação pega: `npm publish` empacota o **disco**, não
109
+ * o commit. Um `npm install` casual entre a auditoria e o publish reescreve o `package.json`, e foi
110
+ * assim que `otplib` e `qrcode` chegaram ao npm sem jamais existirem no git.
111
+ *
112
+ * Severidade depende do modo: sob `--publish` é fatal; em dev é aviso — um gate que reprova todo
113
+ * desenvolvimento local é um gate que se contorna (a lição que o CI nos deu na SPEC-009).
114
+ */
115
+ /** @type {Check} */
116
+ const treeClean = {
117
+ id: 'tree-clean',
118
+ title: 'árvore limpa (o tarball é o commit)',
119
+ severity: 'critical',
120
+ probe(env) {
121
+ let dirty;
122
+ try {
123
+ dirty = git(['status', '--short'], env.root).trim();
124
+ }
125
+ catch {
126
+ return { status: 'skipped', detail: 'fora de um repositório git', fix: null };
127
+ }
128
+ if (!dirty)
129
+ return { status: 'ok', detail: 'nada não commitado', fix: null };
130
+ const n = dirty.split('\n').length;
131
+ const detalhe = `${n} arquivo(s) não commitado(s) — o tarball não corresponde a nenhum commit`;
132
+ return env.publish
133
+ ? { status: 'fail', detail: `${detalhe}. npm publish empacota o disco, não o commit`, fix: 'git commit' }
134
+ : { status: 'warn', detail: `${detalhe}. Ok para smoke; não para publicar`, fix: null };
135
+ },
136
+ };
137
+ /** Se o pacote não instala, todo o resto é irrelevante — daí todos dependerem deste. */
138
+ /** @type {Check} */
139
+ const install = {
140
+ id: 'install',
141
+ title: 'o pacote instala do zero',
142
+ severity: 'critical',
143
+ probe(env) {
144
+ return env.pkgDir && env.fs.existsSync(env.pkgDir)
145
+ ? { status: 'ok', detail: `instalado em ${path.basename(env.installDir)}`, fix: null }
146
+ : { status: 'fail', detail: 'o tarball não instalou', fix: 'npm pack && npm i <tgz> — investigue o erro' };
147
+ },
148
+ };
149
+ /**
150
+ * Todo comando anunciado pelo registry precisa existir no tarball. É o bug da v1.1.3, generalizado:
151
+ * `npm run dashboard` era publicado, a pasta `dashboard/` não.
152
+ */
153
+ /** @type {Check} */
154
+ const registryScripts = {
155
+ id: 'registry-scripts',
156
+ title: 'todo comando do registry existe no tarball',
157
+ severity: 'critical',
158
+ dependsOn: 'install',
159
+ probe(env) {
160
+ const faltando = [];
161
+ let total = 0;
162
+ for (const [name, def] of Object.entries(env.registry)) {
163
+ const rel = def.node || def.script;
164
+ if (!rel)
165
+ continue;
166
+ total += 1;
167
+ // Resolve extensão no tarball (SPEC-012 D2): o script pode ter sido renomeado para .ts em dev
168
+ // e compilado para .js em dist/. O resolver acha o que existe, não crava a extensão.
169
+ const resolved = resolveScript(pkgCodeRoot(env), rel);
170
+ if (!env.fs.existsSync(resolved))
171
+ faltando.push(`${name} → ${rel}`);
172
+ }
173
+ if (faltando.length) {
174
+ return {
175
+ status: 'fail',
176
+ detail: `${faltando.length} comando(s) sem script no tarball: ${faltando.join(', ')}`,
177
+ fix: 'adicione o path ao files[] do package.json',
178
+ };
179
+ }
180
+ return { status: 'ok', detail: `${total}/${total} comandos com script presente`, fix: null };
181
+ },
182
+ };
183
+ /**
184
+ * O **código executável** do pacote — `bin/`, `lib/`, `scripts/`. Nada mais.
185
+ *
186
+ * `boilerplates/` também é publicado e também é `.js`, mas é **conteúdo**: templates copiados para
187
+ * o projeto gerado. O `next.config.js` de um boilerplate importa `next` — que é dependência do
188
+ * projeto do usuário, não do Forja. Varrer essas pastas faz o gate exigir `npm i -S next` no
189
+ * framework, o que é absurdo (observado na primeira execução real do gate).
190
+ *
191
+ * Mesmo princípio de `stripTemplateLiterals`, um nível acima: o que o Forja *escreve* não é o que
192
+ * o Forja *executa*.
193
+ */
194
+ const CODE_DIRS = ['bin', 'lib', 'scripts'];
195
+ /**
196
+ * A raiz onde `bin/lib/scripts` vivem **no tarball**, derivada do campo `bin` do package.json.
197
+ *
198
+ * Fonte-na-raiz (`bin: 'bin/forja.mjs'`) → a raiz é o próprio pacote. Publicando `dist/`
199
+ * (`bin: 'dist/bin/forja.mjs'`, SPEC-012) → a raiz é `dist/`. É a mesma conta que o dispatch faz em
200
+ * runtime (`root = dirname(bin)/..`); os checks de release precisam olhar no mesmo lugar, senão
201
+ * procuram o código onde ele não está mais.
202
+ */
203
+ function pkgCodeRoot(env) {
204
+ try {
205
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
206
+ const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
207
+ if (binRel)
208
+ return path.join(env.pkgDir, path.dirname(path.dirname(binRel)));
209
+ }
210
+ catch {
211
+ /* sem package.json legível — cai no default */
212
+ }
213
+ return env.pkgDir;
214
+ }
215
+ function publishedSources(env) {
216
+ const out = [];
217
+ const root = pkgCodeRoot(env);
218
+ for (const dir of CODE_DIRS) {
219
+ const full = path.join(root, dir);
220
+ if (env.fs.existsSync(full))
221
+ walkDir(env, full, out);
222
+ }
223
+ return out;
224
+ }
225
+ function walkDir(env, dir, out) {
226
+ let entries;
227
+ try {
228
+ entries = env.fs.readdirSync(dir);
229
+ }
230
+ catch {
231
+ return;
232
+ }
233
+ for (const entry of entries) {
234
+ const p = path.join(dir, entry);
235
+ let st;
236
+ try {
237
+ st = env.fs.statSync(p);
238
+ }
239
+ catch {
240
+ continue;
241
+ }
242
+ if (st.isDirectory()) {
243
+ if (entry !== 'node_modules')
244
+ walkDir(env, p, out);
245
+ }
246
+ else if (/\.(mjs|js)$/.test(entry)) {
247
+ out.push(p);
248
+ }
249
+ }
250
+ }
251
+ const IMPORT_RE = /(?:^|\s)(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|\s)import\s*['"]([^'"]+)['"]/gm;
252
+ function importsOf(env, file) {
253
+ const src = stripTemplateLiterals(env.fs.readFileSync(file, 'utf8'));
254
+ const out = [];
255
+ for (const m of src.matchAll(IMPORT_RE))
256
+ out.push(m[1] || m[2]);
257
+ return out;
258
+ }
259
+ /** Pacote npm (não builtin, não relativo). `@scope/x/sub` → `@scope/x`. */
260
+ function packageName(specifier) {
261
+ if (!specifier || specifier.startsWith('.') || specifier.startsWith('/'))
262
+ return null;
263
+ if (specifier.startsWith('node:'))
264
+ return null;
265
+ const parts = specifier.split('/');
266
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
267
+ }
268
+ /** Import relativo que não resolve dentro do tarball = arquivo fora do `files[]` (bug da v1.1.3). */
269
+ /** @type {Check} */
270
+ const importsResolve = {
271
+ id: 'imports-resolve',
272
+ title: 'imports relativos resolvem dentro do tarball',
273
+ severity: 'critical',
274
+ dependsOn: 'install',
275
+ probe(env) {
276
+ const quebrados = [];
277
+ for (const file of publishedSources(env)) {
278
+ for (const spec of importsOf(env, file)) {
279
+ if (!spec?.startsWith('.'))
280
+ continue;
281
+ const alvo = path.resolve(path.dirname(file), spec);
282
+ const existe = env.fs.existsSync(alvo)
283
+ || ['.js', '.mjs', '.json'].some((ext) => env.fs.existsSync(alvo + ext));
284
+ if (!existe)
285
+ quebrados.push(`${path.relative(env.pkgDir, file)} → ${spec}`);
286
+ }
287
+ }
288
+ if (quebrados.length) {
289
+ return {
290
+ status: 'fail',
291
+ detail: `${quebrados.length} import(s) sem destino no tarball: ${quebrados.slice(0, 3).join('; ')}`,
292
+ fix: 'adicione o arquivo ao files[] do package.json',
293
+ };
294
+ }
295
+ return { status: 'ok', detail: 'todo import relativo resolve', fix: null };
296
+ },
297
+ };
298
+ /** O bug do ADR-0021 §2: importado por script publicado, mas declarado como devDependency. */
299
+ /** @type {Check} */
300
+ const depsDeclared = {
301
+ id: 'deps-declared',
302
+ title: 'todo import externo está em dependencies',
303
+ severity: 'critical',
304
+ dependsOn: 'install',
305
+ probe(env) {
306
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
307
+ const deps = new Set(Object.keys(pkg.dependencies || {}));
308
+ const faltando = new Map();
309
+ for (const file of publishedSources(env)) {
310
+ for (const spec of importsOf(env, file)) {
311
+ const nome = packageName(spec);
312
+ if (!nome || deps.has(nome))
313
+ continue;
314
+ faltando.set(nome, path.relative(env.pkgDir, file));
315
+ }
316
+ }
317
+ if (faltando.size) {
318
+ const lista = [...faltando].map(([n, f]) => `${n} (${f})`).join(', ');
319
+ return {
320
+ status: 'fail',
321
+ detail: `importado pelo pacote mas não declarado em dependencies: ${lista}`,
322
+ fix: `npm i -S ${[...faltando.keys()].join(' ')}`,
323
+ };
324
+ }
325
+ return { status: 'ok', detail: `${deps.size} dependência(s), todas importadas por alguém`, fix: null };
326
+ },
327
+ };
328
+ /** Peso morto viaja no tarball de todo usuário. Incomoda; não quebra — por isso `warn` (D7). */
329
+ /** @type {Check} */
330
+ const depsUnused = {
331
+ id: 'deps-unused',
332
+ title: 'nenhuma dependency é peso morto',
333
+ severity: 'warn',
334
+ dependsOn: 'install',
335
+ probe(env) {
336
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
337
+ const deps = Object.keys(pkg.dependencies || {});
338
+ const usados = new Set();
339
+ for (const file of publishedSources(env)) {
340
+ for (const spec of importsOf(env, file)) {
341
+ const nome = packageName(spec);
342
+ if (nome)
343
+ usados.add(nome);
344
+ }
345
+ }
346
+ const ociosos = deps.filter((d) => !usados.has(d));
347
+ if (ociosos.length) {
348
+ return {
349
+ status: 'warn',
350
+ detail: `declarada(s) e nunca importada(s): ${ociosos.join(', ')} — todo usuário baixa isso`,
351
+ fix: `npm rm ${ociosos.join(' ')}`,
352
+ };
353
+ }
354
+ return { status: 'ok', detail: 'nenhuma dependência ociosa', fix: null };
355
+ },
356
+ };
357
+ /**
358
+ * O check mais importante, e o mais fácil de errar.
359
+ *
360
+ * **Executar, não listar.** O `forja` sem argumentos passa mesmo com tudo quebrado — o help não
361
+ * carrega os scripts. Foi assim que a quebra do ADR-0021 §2 se escondeu: o help funcionava, e dez
362
+ * comandos estavam mortos.
363
+ *
364
+ * **Reprovar por stderr, nunca por exit code.** Numa instalação limpa não há workspace nem
365
+ * `universal.db`; `query:universal` sai com código ≠ 0 *legitimamente*, e isso é o pacote
366
+ * funcionando. O que denuncia tarball quebrado é a assinatura do carregamento. Reprovar por exit
367
+ * code reprovaria um pacote saudável — a mesma armadilha do `memory-db` na SPEC-009, um nível
368
+ * acima.
369
+ */
370
+ /** @type {Check} */
371
+ const smokeCommands = {
372
+ id: 'smoke-commands',
373
+ title: 'os comandos executam de verdade',
374
+ severity: 'critical',
375
+ dependsOn: 'install',
376
+ probe(env) {
377
+ // Lê o entry point do campo `bin` do package.json, não de um path fixo — o publicado aponta
378
+ // para dist/ (SPEC-012). Cravar `bin/forja.mjs` quebraria o smoke assim que o bin mudasse.
379
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
380
+ const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
381
+ const bin = path.join(env.pkgDir, binRel);
382
+ const quebrados = [];
383
+ for (const args of env.smokeCommands) {
384
+ const res = env.spawn(process.execPath, [bin, ...args], { cwd: env.installDir });
385
+ const saida = `${res.stdout || ''}${res.stderr || ''}`;
386
+ if (LOADER_ERRORS.test(saida)) {
387
+ const causa = saida.match(LOADER_ERRORS)?.[0] ?? 'erro de carregamento';
388
+ quebrados.push(`${args[0] || '(help)'}: ${causa}`);
389
+ }
390
+ }
391
+ if (quebrados.length) {
392
+ return {
393
+ status: 'fail',
394
+ detail: `comando(s) não carregam na instalação limpa: ${quebrados.join('; ')}`,
395
+ fix: 'verifique files[] e dependencies — o repo resolve, o tarball não',
396
+ };
397
+ }
398
+ return {
399
+ status: 'ok',
400
+ detail: `${env.smokeCommands.length} comando(s) executam sem erro de carregamento`,
401
+ fix: null,
402
+ };
403
+ },
404
+ };
405
+ /** @type {import('./checks.ts').Check[]} */
406
+ export const RELEASE_CHECKS = [
407
+ treeClean,
408
+ install,
409
+ registryScripts,
410
+ smokeCommands,
411
+ importsResolve,
412
+ depsDeclared,
413
+ depsUnused,
414
+ ];
415
+ /** Comandos sem efeito colateral. `tools:doctor` e `code:status` só leem; o help não prova nada sozinho. */
416
+ const DEFAULT_SMOKE = [[], ['tools:doctor'], ['code:status'], ['query:universal', 'teste']];
417
+ export function defaultEnv(overrides = {}) {
418
+ return {
419
+ root: repoRoot,
420
+ fs,
421
+ registry: COMMANDS,
422
+ smokeCommands: DEFAULT_SMOKE,
423
+ publish: false,
424
+ spawn: (cmd, args, opts) => {
425
+ try {
426
+ return {
427
+ stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', ...opts }),
428
+ stderr: '',
429
+ };
430
+ }
431
+ catch (err) {
432
+ const e = /** @type {any} */ (err);
433
+ return { stdout: e.stdout || '', stderr: e.stderr || String(err) };
434
+ }
435
+ },
436
+ ...overrides,
437
+ };
438
+ }
439
+ /**
440
+ * Roda o gate completo: empacota, instala isolado, checa, limpa.
441
+ *
442
+ * A aprovação é **perecível** — vale para o disco naquele instante. Por isso a árvore é reconferida
443
+ * ao final: um `npm install` entre o check e o publish invalida tudo, e foi exatamente essa a causa
444
+ * da v1.1.1.
445
+ */
446
+ export async function runReleaseChecks({ publish = false, env: overrides = {} } = {}) {
447
+ const base = defaultEnv({ publish, ...overrides });
448
+ const arvoreAntes = git(['status', '--short'], base.root);
449
+ const results = await withCleanInstall(({ pkgDir, installDir }) => run({
450
+ checks: RELEASE_CHECKS,
451
+ env: { ...base, pkgDir, installDir },
452
+ }), { root: base.root });
453
+ const arvoreDepois = git(['status', '--short'], base.root);
454
+ if (arvoreAntes !== arvoreDepois) {
455
+ results.push({
456
+ id: 'tree-stable',
457
+ title: 'a árvore não mudou durante a auditoria',
458
+ severity: 'critical',
459
+ status: 'fail',
460
+ detail: 'o disco mudou enquanto o gate rodava — este parecer está vencido',
461
+ fix: 'rode o gate de novo com a árvore parada',
462
+ });
463
+ }
464
+ return results;
465
+ }
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Retorna todos os templates combinados
3
+ */
4
+ export function getAllMemoryTemplates(): {
5
+ 'scripts/build-context-pack.mjs': string;
6
+ 'scripts/append-handoff.mjs': string;
7
+ 'scripts/lib/skill-loader.mjs': string;
8
+ 'scripts/memory-vacuum.mjs': string;
9
+ 'scripts/memory-watcher.mjs': string;
10
+ 'AGENTS.md': string;
11
+ '.memoryrc.json': string;
12
+ '.gitignore': string;
13
+ 'prompts/project-prompt-base.md': string;
14
+ 'prompts/multi-agent-orchestrator.md': string;
15
+ 'prompts/worker-task-template.md': string;
16
+ 'skills/triage-task/SKILL.md': string;
17
+ 'skills/context-compaction/SKILL.md': string;
18
+ 'skills/handoff/SKILL.md': string;
19
+ 'skills/nest-api/SKILL.md': string;
20
+ 'skills/self-healing/SKILL.md': string;
21
+ 'skills/validate-handoff/SKILL.md': string;
22
+ 'skills/ui-fidelity/SKILL.md': string;
23
+ 'skills/reasoning-protocol/SKILL.md': string;
24
+ 'skills/llm-provider-routing/SKILL.md': string;
25
+ 'skills/MANIFEST.json': string;
26
+ 'agents/README.md': string;
27
+ 'agents/orchestrator.md': string;
28
+ 'agents/backend-nest.md': string;
29
+ 'agents/frontend.md': string;
30
+ 'agents/dba.md': string;
31
+ 'agents/security.md': string;
32
+ 'agents/reviewer.md': string;
33
+ 'memory/README.md': string;
34
+ 'memory/00-global/mission.md': string;
35
+ 'memory/00-global/standards.md': string;
36
+ 'memory/00-global/context-policy.md': string;
37
+ 'memory/00-global/agent-contract.md': string;
38
+ 'memory/00-global/context-index.md': string;
39
+ 'memory/10-product/vision.md': string;
40
+ 'memory/10-product/personas.md': string;
41
+ 'memory/10-product/business-rules.md': string;
42
+ 'memory/10-product/nfrs.md': string;
43
+ 'memory/20-architecture/system-overview.md': string;
44
+ 'memory/20-architecture/frontend.md': string;
45
+ 'memory/20-architecture/backend.md': string;
46
+ 'memory/20-architecture/data.md': string;
47
+ 'memory/20-architecture/security.md': string;
48
+ 'memory/20-architecture/observability.md': string;
49
+ 'memory/30-domains/auth/context.md': string;
50
+ 'memory/30-domains/auth/rules.md': string;
51
+ 'memory/30-domains/auth/api.md': string;
52
+ 'memory/30-domains/billing/context.md': string;
53
+ 'memory/30-domains/billing/rules.md': string;
54
+ 'memory/30-domains/billing/api.md': string;
55
+ 'memory/40-delivery/roadmap.md': string;
56
+ 'memory/40-delivery/current-sprint.md': string;
57
+ 'memory/40-delivery/backlog.md': string;
58
+ 'memory/50-orchestration/topology.md': string;
59
+ 'memory/50-orchestration/routing.md': string;
60
+ 'memory/50-orchestration/handoff-protocol.md': string;
61
+ 'memory/50-orchestration/parallel-playbook.md': string;
62
+ 'memory/50-orchestration/handoffs/README.md': string;
63
+ 'memory/60-runs/README.md': string;
64
+ 'memory/70-summaries/global-summary.md': string;
65
+ 'memory/70-summaries/domain-summary.md': string;
66
+ 'memory/80-data/memory-db.md': string;
67
+ 'memory/90-decisions/ADR-0001-template.md': string;
68
+ };
69
+ /**
70
+ * Escreve a estrutura completa de memória
71
+ * @param {string} baseDir - Diretório base para geração
72
+ * @param {Object} options - Opções (force, noGitkeep)
73
+ */
74
+ export function generateMemoryStructure(baseDir: string, options?: any): {
75
+ success: boolean;
76
+ filesWritten: number;
77
+ emptyDirsCreated: number;
78
+ };
79
+ declare namespace _default {
80
+ export { generateMemoryStructure };
81
+ export { getAllMemoryTemplates };
82
+ }
83
+ export default _default;