forjajs 1.2.0 → 1.3.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.
Files changed (132) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +41 -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,312 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Dev Workflow CLI - Orchestrador Unificado de Comandos
4
+ *
5
+ * Unifica todos os commands de desenvolvimento em uma interface única:
6
+ * - context:build → Gerar contexto inteligente
7
+ * - memory:vacuum → Comprimir e limpar memória
8
+ * - memory:sync → Sincronizar índices
9
+ * - project:health → Validar saúde do projeto
10
+ * - project:init → Inicializar novo projeto
11
+ *
12
+ * Uso: npm run dev -- <command> [args]
13
+ * node scripts/dev.mjs context:build global my-project
14
+ */
15
+ import fs from 'node:fs';
16
+ import path from 'node:path';
17
+ import { spawn } from 'node:child_process';
18
+ import { fileURLToPath } from 'node:url';
19
+ import { getDbPath, ensureSchema } from "./memory-schema.js";
20
+ const __filename = fileURLToPath(import.meta.url);
21
+ const __dirname = path.dirname(__filename);
22
+ const root = path.resolve(__dirname, '..');
23
+ const COMMANDS = {
24
+ 'context:build': {
25
+ desc: 'Gerar contexto inteligente (global|domain|task)',
26
+ handler: contextBuild,
27
+ example: 'context:build task my-project "auth backend"',
28
+ },
29
+ 'memory:vacuum': {
30
+ desc: 'Comprimir e limpar memória (archive + cleanup)',
31
+ handler: memoryVacuum,
32
+ example: 'memory:vacuum',
33
+ },
34
+ 'memory:sync': {
35
+ desc: 'Sincronizar índices de busca (FTS5)',
36
+ handler: memorySync,
37
+ example: 'memory:sync my-project',
38
+ },
39
+ 'project:health': {
40
+ desc: 'Validar saúde do projeto (estrutura, config, permissões)',
41
+ handler: projectHealth,
42
+ example: 'project:health',
43
+ },
44
+ 'project:init': {
45
+ desc: 'Inicializar novo projeto com templates',
46
+ handler: projectInit,
47
+ example: 'project:init my-project --force',
48
+ },
49
+ 'design:select': {
50
+ desc: 'Selecionar referencias design-md por superficie',
51
+ handler: harnessCommand('design:select'),
52
+ example: 'design:select agent-console tecnico',
53
+ },
54
+ 'design:check': {
55
+ desc: 'Validar brief visual antes do handoff',
56
+ handler: harnessCommand('design:check'),
57
+ example: 'design:check design-md/examples/agent-console-brief.md',
58
+ },
59
+ 'hermes:handoff': {
60
+ desc: 'Registrar handoff ADR-0005 via Hermes',
61
+ handler: harnessCommand('hermes:handoff'),
62
+ example: 'hermes:handoff \'{"from":"orchestrator","to":"product","intent":"spec","context":"...","acceptance":"...","constraints":"...","return":"orchestrator"}\'',
63
+ },
64
+ 'gsd:plan': {
65
+ desc: 'Criar runbook GSD para uma feature/spec',
66
+ handler: harnessCommand('gsd:plan'),
67
+ example: 'gsd:plan minha-feature "objetivo da execucao"',
68
+ },
69
+ 'gsd:handoff': {
70
+ desc: 'Registrar handoff padrao do fluxo GSD',
71
+ handler: harnessCommand('gsd:handoff'),
72
+ example: 'gsd:handoff spec minha-feature',
73
+ },
74
+ 'gsd:check': {
75
+ desc: 'Validar gates basicos de GSD/spec/design',
76
+ handler: harnessCommand('gsd:check'),
77
+ example: 'gsd:check minha-feature design-md/examples/agent-console-brief.md',
78
+ },
79
+ };
80
+ /**
81
+ * Mostrar help
82
+ */
83
+ function showHelp() {
84
+ console.log('Dev Workflow CLI');
85
+ console.log('');
86
+ console.log('Sintaxe: npm run dev -- <command> [args]');
87
+ console.log(' node scripts/dev.mjs <command> [args]');
88
+ console.log('');
89
+ console.log('Comandos disponiveis:');
90
+ console.log('');
91
+ for (const [cmd, info] of Object.entries(COMMANDS)) {
92
+ console.log(` ${cmd.padEnd(20)} - ${info.desc}`);
93
+ console.log(` ${' '.repeat(20)} Exemplo: npm run dev -- ${info.example}\n`);
94
+ }
95
+ console.log(`Variaveis de ambiente:
96
+ DEBUG=1 - Habilita verbose output
97
+ DRY_RUN=1 - Simula execução sem fazer mudanças
98
+
99
+ Exemplos:
100
+
101
+ npm run dev -- context:build task my-project "payment feature"
102
+ npm run dev -- memory:vacuum
103
+ npm run dev -- memory:sync my-project
104
+ npm run dev -- project:health
105
+ npm run dev -- project:init awesome-app
106
+ DEBUG=1 npm run dev -- project:health
107
+
108
+ `);
109
+ }
110
+ /**
111
+ * Run subprocess
112
+ */
113
+ function runScript(scriptPath, args = []) {
114
+ return new Promise((resolve, reject) => {
115
+ const proc = spawn('node', [scriptPath, ...args], {
116
+ stdio: 'inherit',
117
+ cwd: root,
118
+ });
119
+ proc.on('close', (code) => {
120
+ if (code === 0) {
121
+ resolve();
122
+ }
123
+ else {
124
+ reject(new Error(`Script exited with code ${code}`));
125
+ }
126
+ });
127
+ proc.on('error', reject);
128
+ });
129
+ }
130
+ function harnessCommand(command) {
131
+ return async function runHarness(args = []) {
132
+ await runScript(path.join(root, 'scripts', 'agent-harness.mjs'), [command, ...args]);
133
+ };
134
+ }
135
+ /**
136
+ * Context Build Handler
137
+ */
138
+ async function contextBuild([mode, project, keyword] = []) {
139
+ if (!mode || !project) {
140
+ console.error('Uso: context:build <global|domain|task> <project> [keyword]');
141
+ process.exit(1);
142
+ }
143
+ console.log(`Building ${mode} context for ${project}...`);
144
+ try {
145
+ ensureSchema({ silent: true });
146
+ const builder = (await import('../lib/context-builder.js')).default;
147
+ const dbPath = getDbPath();
148
+ const ctx = new builder(root, dbPath);
149
+ ctx.connect();
150
+ const content = ctx.build(mode, project, keyword);
151
+ const stats = ctx.stats(mode, project, keyword);
152
+ const outDir = path.join(root, '.context');
153
+ if (!fs.existsSync(outDir))
154
+ fs.mkdirSync(outDir, { recursive: true });
155
+ const outFile = path.join(outDir, `context-${mode}.md`);
156
+ fs.writeFileSync(outFile, content, 'utf8');
157
+ ctx.close();
158
+ console.log(`Context saved: ${outFile}`);
159
+ console.log('Stats:', stats);
160
+ }
161
+ catch (e) {
162
+ console.error('Error:', e.message);
163
+ process.exit(1);
164
+ }
165
+ }
166
+ /**
167
+ * Memory Vacuum Handler
168
+ */
169
+ async function memoryVacuum() {
170
+ console.log('Running memory vacuum...');
171
+ try {
172
+ await runScript(path.join(root, 'scripts', 'compress-memory.mjs'));
173
+ console.log('Memory vacuum complete');
174
+ }
175
+ catch (e) {
176
+ console.error('Error:', e.message);
177
+ process.exit(1);
178
+ }
179
+ }
180
+ /**
181
+ * Memory Sync Handler
182
+ */
183
+ async function memorySync([project] = []) {
184
+ console.log(`Syncing memory indexes${project ? ` for ${project}` : ''}...`);
185
+ try {
186
+ ensureSchema({ silent: true });
187
+ const dbPath = getDbPath();
188
+ if (!fs.existsSync(dbPath)) {
189
+ console.warn('Database not found. Run: npm run memory:db:init');
190
+ return;
191
+ }
192
+ // TODO: Implementar sync com FTS5 rebuild
193
+ console.log('Memory indexes synced');
194
+ }
195
+ catch (e) {
196
+ console.error('Error:', e.message);
197
+ process.exit(1);
198
+ }
199
+ }
200
+ /**
201
+ * Project Health Check
202
+ */
203
+ async function projectHealth() {
204
+ console.log('Running project health checks...\n');
205
+ const checks = [];
206
+ let healthy = true;
207
+ // 1. Check estrutura
208
+ console.log('Checking structure...');
209
+ const requiredDirs = [
210
+ 'lib',
211
+ 'scripts',
212
+ 'docs',
213
+ 'memory',
214
+ 'agents',
215
+ 'skills',
216
+ 'prompts',
217
+ ];
218
+ for (const dir of requiredDirs) {
219
+ const exists = fs.existsSync(path.join(root, dir));
220
+ const status = exists ? 'OK ' : 'FAIL';
221
+ console.log(` ${status} ${dir}/`);
222
+ if (!exists)
223
+ healthy = false;
224
+ }
225
+ // 2. Check config
226
+ console.log('\nChecking config...');
227
+ const configFiles = ['.memoryrc.json', 'package.json'];
228
+ for (const file of configFiles) {
229
+ const exists = fs.existsSync(path.join(root, file));
230
+ const status = exists ? 'OK ' : 'FAIL';
231
+ console.log(` ${status} ${file}`);
232
+ if (!exists)
233
+ healthy = false;
234
+ }
235
+ // 3. Check key files
236
+ console.log('\nChecking key files...');
237
+ const keyFiles = ['bin/create-memory-nest-kit.js', 'lib/context-builder.js'];
238
+ for (const file of keyFiles) {
239
+ const exists = fs.existsSync(path.join(root, file));
240
+ const status = exists ? 'OK ' : 'FAIL';
241
+ console.log(` ${status} ${file}`);
242
+ if (!exists)
243
+ healthy = false;
244
+ }
245
+ // 4. Check database
246
+ console.log('\nChecking database...');
247
+ ensureSchema({ silent: true });
248
+ const dbPath = getDbPath();
249
+ const dbExists = fs.existsSync(dbPath);
250
+ console.log(` ${dbExists ? 'OK ' : 'WARN'} ${dbPath}`);
251
+ // 5. Summary
252
+ console.log('');
253
+ if (healthy) {
254
+ console.log('Project health: GOOD');
255
+ }
256
+ else {
257
+ console.log('Project health: Issues found - run: npm run project:init');
258
+ }
259
+ console.log('');
260
+ process.exit(healthy ? 0 : 1);
261
+ }
262
+ /**
263
+ * Project Init Handler
264
+ */
265
+ async function projectInit([projectName, ...flags] = []) {
266
+ if (!projectName) {
267
+ console.error('Uso: project:init <project-name> [--force] [--only-memory]');
268
+ process.exit(1);
269
+ }
270
+ console.log(`Initializing project: ${projectName}...\n`);
271
+ try {
272
+ await runScript(path.join(root, 'bin', 'create-memory-nest-kit.js'), [
273
+ projectName,
274
+ ...flags,
275
+ ]);
276
+ console.log(`\nProject ${projectName} initialized.`);
277
+ }
278
+ catch (e) {
279
+ console.error('Error:', e.message);
280
+ process.exit(1);
281
+ }
282
+ }
283
+ /**
284
+ * Main entrypoint
285
+ */
286
+ async function main() {
287
+ const args = process.argv.slice(2);
288
+ const [command, ...cmdArgs] = args;
289
+ if (!command || command === '--help' || command === '-h') {
290
+ showHelp();
291
+ return;
292
+ }
293
+ const commandInfo = COMMANDS[command];
294
+ if (!commandInfo) {
295
+ console.error(`Unknown command: ${command}`);
296
+ console.error(`\nRun: npm run dev -- --help\n`);
297
+ process.exit(1);
298
+ }
299
+ if (process.env.DEBUG) {
300
+ console.log(`DEBUG: command=${command}, args=${JSON.stringify(cmdArgs)}\n`);
301
+ }
302
+ try {
303
+ await commandInfo.handler(cmdArgs);
304
+ }
305
+ catch (e) {
306
+ console.error(`Error: ${e.message}`);
307
+ process.exit(1);
308
+ }
309
+ }
310
+ // Run
311
+ main().catch(console.error);
312
+ export { COMMANDS, runScript };
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,43 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import Database from 'better-sqlite3';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { getDbPath, ensureSchema } from "./memory-schema.js";
6
+ const __filename = fileURLToPath(import.meta.url);
7
+ const __dirname = path.dirname(__filename);
8
+ const root = path.resolve(__dirname, '..');
9
+ ensureSchema({ silent: true });
10
+ const dbPath = getDbPath();
11
+ function extractGlobalLessons() {
12
+ console.log('🧠 Extraindo lições aprendidas de todos os projetos para Memória Global...');
13
+ const db = new Database(dbPath, { readonly: true });
14
+ // Busca ADRs (Decisões) de todos os projetos
15
+ const adrs = db.prepare(`
16
+ SELECT n.title, n.content, p.name as project
17
+ FROM memory_nodes n
18
+ JOIN projects p ON p.id = n.project_id
19
+ WHERE n.kind = 'adr'
20
+ `).all();
21
+ let knowledgeBase = `# Base de Conhecimento Compartilhada (Patterns)\n\n`;
22
+ knowledgeBase += `> Gerado automaticamente via Cross-Project Analysis em: ${new Date().toISOString()}\n\n`;
23
+ for (const adr of adrs) {
24
+ knowledgeBase += `### [Proveniente de: ${adr.project}] ${adr.title}\n\n`;
25
+ // Pega apenas o resumo ou contexto da decisão
26
+ const contextMatch = adr.content.match(/## Contexto\n([\s\S]*?)(?=##|$)/);
27
+ const decisionMatch = adr.content.match(/## Decisao\n([\s\S]*?)(?=##|$)/);
28
+ if (contextMatch && decisionMatch) {
29
+ knowledgeBase += `**Contexto:** ${contextMatch[1].trim().slice(0, 300)}...\n\n`;
30
+ knowledgeBase += `**Padrao Adotado:** ${decisionMatch[1].trim()}\n\n`;
31
+ }
32
+ }
33
+ const outFile = path.join(root, 'memory/00-global/shared-knowledge.md');
34
+ fs.writeFileSync(outFile, knowledgeBase, 'utf8');
35
+ console.log(`✅ Base de conhecimento global atualizada em: ${outFile}`);
36
+ db.close();
37
+ }
38
+ try {
39
+ extractGlobalLessons();
40
+ }
41
+ catch (e) {
42
+ console.error('Erro ao extrair lições:', e.message);
43
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,48 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import Database from 'better-sqlite3';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { getDbPath, ensureSchema } from "./memory-schema.js";
6
+ const __filename = fileURLToPath(import.meta.url);
7
+ const __dirname = path.dirname(__filename);
8
+ const root = path.resolve(__dirname, '..');
9
+ ensureSchema({ silent: true });
10
+ const dbPath = getDbPath();
11
+ function generate() {
12
+ console.log('📊 Gerando Dashboard Global do Ecossistema...');
13
+ const db = new Database(dbPath, { readonly: true });
14
+ const projects = db.prepare('SELECT * FROM projects').all();
15
+ let md = `# 🛰️ Dashboard do Ecossistema de Agentes\n\n`;
16
+ md += `> Gerado em: ${new Date().toISOString()}\n\n`;
17
+ md += `| Projeto | ADRs | Summaries | Docs | Última Atividade |\n`;
18
+ md += `|---------|------|-----------|------|-------------------|\n`;
19
+ for (const p of projects) {
20
+ const stats = db.prepare(`
21
+ SELECT
22
+ SUM(CASE WHEN kind = 'adr' THEN 1 ELSE 0 END) as adrs,
23
+ SUM(CASE WHEN kind = 'summary' THEN 1 ELSE 0 END) as summaries,
24
+ COUNT(*) as total,
25
+ MAX(updated_at) as last_update
26
+ FROM memory_nodes
27
+ WHERE project_id = ?
28
+ `).get(p.id);
29
+ md += `| **${p.name}** | ${stats.adrs} | ${stats.summaries} | ${stats.total} | ${stats.last_update.split('T')[0]} |\n`;
30
+ }
31
+ md += `\n## 🧠 Lições Globais Recentes\n\n`;
32
+ const recentLessons = db.prepare(`
33
+ SELECT title, path FROM memory_nodes
34
+ WHERE kind = 'global' AND path LIKE '%shared-knowledge.md'
35
+ `).get();
36
+ if (recentLessons) {
37
+ md += `- [Clique aqui para ver a Base de Conhecimento Compartilhada](${recentLessons.path})\n`;
38
+ }
39
+ fs.writeFileSync(path.join(root, 'DASHBOARD-PROGRESSO.md'), md, 'utf8');
40
+ console.log('✅ Dashboard atualizado: DASHBOARD-PROGRESSO.md');
41
+ db.close();
42
+ }
43
+ try {
44
+ generate();
45
+ }
46
+ catch (e) {
47
+ console.error('Erro ao gerar dashboard:', e.message);
48
+ }
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,36 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * governance:dashboard — gera um painel HTML estático de governança (SPEC-014).
4
+ *
5
+ * Lê specs, ADRs, o registry e a trilha de auditoria; escreve um arquivo. **Não executa nada** — é
6
+ * a resposta correta ao ADR-0022 (o dashboard antigo era servidor com rotas; este é artefato).
7
+ *
8
+ * Uso: forja governance:dashboard [--out <arquivo>]
9
+ */
10
+ import fs from 'node:fs';
11
+ import path from 'node:path';
12
+ import { collect, renderHtml } from "../lib/governance-report.js";
13
+ import { getWorkspaceContextDir, ensureDir } from "../lib/workspace.js";
14
+ const argv = process.argv.slice(2);
15
+ const outIdx = argv.indexOf('--out');
16
+ let out = outIdx >= 0 ? argv[outIdx + 1] : null;
17
+ if (!out) {
18
+ try {
19
+ out = path.join(ensureDir(getWorkspaceContextDir()), 'governance.html');
20
+ }
21
+ catch {
22
+ out = path.join(process.cwd(), 'governance.html');
23
+ }
24
+ }
25
+ try {
26
+ const data = await collect();
27
+ fs.writeFileSync(out, renderHtml(data), 'utf8');
28
+ const audit = data.audit ? `${data.audit.total} runs auditados` : 'sem atividade auditada ainda';
29
+ console.log(`Painel gerado: ${out}`);
30
+ console.log(` ${data.metrics.specs} specs · ${data.metrics.adrs} ADRs · ${data.gates.length} gates · ${audit}`);
31
+ console.log(' Abra com file:// — é estático, sem servidor (ADR-0022).');
32
+ }
33
+ catch (err) {
34
+ console.error(`governance:dashboard falhou: ${ /** @type {any} */(err).message}`);
35
+ process.exit(1);
36
+ }
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook PreToolUse — guarda de caminhos protegidos (ADR-0021).
4
+ *
5
+ * O CLAUDE.md declara `projects/` off-limits e `docs/archive/` como material
6
+ * histórico congelado. Até aqui isso era prosa: valia enquanto a IA lembrasse.
7
+ * Este hook torna a regra determinística — a escrita é barrada antes de acontecer,
8
+ * não corrigida depois.
9
+ *
10
+ * Protocolo:
11
+ * - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
12
+ * - exit 0: liberado (silencioso)
13
+ * - exit 2: bloqueado — stderr volta para a IA como feedback acionável
14
+ *
15
+ * Escape hatch: FORJA_GUARD=0 desliga (útil para manutenção deliberada do archive).
16
+ */
17
+ export {};
@@ -0,0 +1,68 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook PreToolUse — guarda de caminhos protegidos (ADR-0021).
4
+ *
5
+ * O CLAUDE.md declara `projects/` off-limits e `docs/archive/` como material
6
+ * histórico congelado. Até aqui isso era prosa: valia enquanto a IA lembrasse.
7
+ * Este hook torna a regra determinística — a escrita é barrada antes de acontecer,
8
+ * não corrigida depois.
9
+ *
10
+ * Protocolo:
11
+ * - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
12
+ * - exit 0: liberado (silencioso)
13
+ * - exit 2: bloqueado — stderr volta para a IA como feedback acionável
14
+ *
15
+ * Escape hatch: FORJA_GUARD=0 desliga (útil para manutenção deliberada do archive).
16
+ */
17
+ import path from 'node:path';
18
+ import process from 'node:process';
19
+ /** Cada regra explica o porquê: a IA recebe o motivo, não só a negativa. */
20
+ const PROTECTED = [
21
+ {
22
+ test: (rel) => rel === 'projects' || rel.startsWith('projects/'),
23
+ reason: 'projects/ é off-limits (CLAUDE.md): contém produtos em desenvolvimento ativo do usuário. ' +
24
+ 'Aplicações reais vivem no workspace externo — use `npm run project:new` (ADR-0019).',
25
+ },
26
+ {
27
+ test: (rel) => rel.startsWith('docs/archive/'),
28
+ reason: 'docs/archive/ é material histórico congelado (ex.: legacy-bin/, mantido só para referência). ' +
29
+ 'Se a mudança é real, ela pertence ao código vivo em bin/ ou lib/.',
30
+ },
31
+ ];
32
+ function readStdin() {
33
+ return new Promise((resolve) => {
34
+ let data = '';
35
+ process.stdin.setEncoding('utf8');
36
+ process.stdin.on('data', (c) => { data += c; });
37
+ process.stdin.on('end', () => resolve(data));
38
+ });
39
+ }
40
+ /** Falha aberta: um guard quebrado não pode travar a sessão inteira. */
41
+ /** @returns {never} */
42
+ function allow() { process.exit(0); }
43
+ (async function main() {
44
+ if (process.env.FORJA_GUARD === '0')
45
+ allow();
46
+ let payload;
47
+ try {
48
+ payload = JSON.parse((await readStdin()));
49
+ }
50
+ catch {
51
+ allow();
52
+ }
53
+ const filePath = payload?.tool_input?.file_path;
54
+ if (typeof filePath !== 'string' || !filePath)
55
+ allow();
56
+ const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
57
+ const abs = path.resolve(root, filePath);
58
+ const rel = path.relative(root, abs);
59
+ // Fora do repo: não é competência deste guard.
60
+ if (rel.startsWith('..') || path.isAbsolute(rel))
61
+ allow();
62
+ const relPosix = rel.split(path.sep).join('/');
63
+ const hit = PROTECTED.find((rule) => rule.test(relPosix));
64
+ if (!hit)
65
+ allow();
66
+ process.stderr.write(`Escrita bloqueada em \`${relPosix}\`.\n\n${hit.reason}\n`);
67
+ process.exit(2);
68
+ })();
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook PostToolUse — fecha o loop do registry (ADR-0021).
4
+ *
5
+ * ADR-0020 estabelece a invariante: "comando novo = entrada nova no registry".
6
+ * `test/forja-core.test.js` valida isso, mas só rodava no pre-commit — e o
7
+ * lefthook é opt-in, então na prática podia nunca rodar. Resultado: a quebra
8
+ * aparecia minutos ou commits depois, longe da edição que a causou.
9
+ *
10
+ * Aqui o teste roda no instante em que o registry (ou o package.json que o
11
+ * espelha) é tocado. Custo: um único arquivo de teste, poucos segundos.
12
+ *
13
+ * Protocolo:
14
+ * - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
15
+ * - exit 0: nada a fazer, ou teste passou (silencioso)
16
+ * - exit 2: teste falhou — stderr volta para a IA, que corrige antes de seguir
17
+ *
18
+ * Escape hatch: FORJA_HOOK_TEST=0 desliga.
19
+ */
20
+ export {};
@@ -0,0 +1,70 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook PostToolUse — fecha o loop do registry (ADR-0021).
4
+ *
5
+ * ADR-0020 estabelece a invariante: "comando novo = entrada nova no registry".
6
+ * `test/forja-core.test.js` valida isso, mas só rodava no pre-commit — e o
7
+ * lefthook é opt-in, então na prática podia nunca rodar. Resultado: a quebra
8
+ * aparecia minutos ou commits depois, longe da edição que a causou.
9
+ *
10
+ * Aqui o teste roda no instante em que o registry (ou o package.json que o
11
+ * espelha) é tocado. Custo: um único arquivo de teste, poucos segundos.
12
+ *
13
+ * Protocolo:
14
+ * - stdin: JSON com { tool_name, tool_input: { file_path }, cwd }
15
+ * - exit 0: nada a fazer, ou teste passou (silencioso)
16
+ * - exit 2: teste falhou — stderr volta para a IA, que corrige antes de seguir
17
+ *
18
+ * Escape hatch: FORJA_HOOK_TEST=0 desliga.
19
+ */
20
+ import path from 'node:path';
21
+ import process from 'node:process';
22
+ import { spawnSync } from 'node:child_process';
23
+ /** Arquivos cuja edição invalida a integridade do core. */
24
+ const WATCHED = ['lib/core/registry.ts', 'package.json'];
25
+ const SUITE = 'test/forja-core.test.js';
26
+ function readStdin() {
27
+ return new Promise((resolve) => {
28
+ let data = '';
29
+ process.stdin.setEncoding('utf8');
30
+ process.stdin.on('data', (c) => { data += c; });
31
+ process.stdin.on('end', () => resolve(data));
32
+ });
33
+ }
34
+ function skip() { process.exit(0); }
35
+ (async function main() {
36
+ if (process.env.FORJA_HOOK_TEST === '0')
37
+ skip();
38
+ let payload;
39
+ try {
40
+ payload = JSON.parse((await readStdin()));
41
+ }
42
+ catch {
43
+ skip();
44
+ }
45
+ const filePath = payload?.tool_input?.file_path;
46
+ if (typeof filePath !== 'string' || !filePath)
47
+ skip();
48
+ const root = process.env.CLAUDE_PROJECT_DIR || payload?.cwd || process.cwd();
49
+ const rel = path.relative(root, path.resolve(root, filePath)).split(path.sep).join('/');
50
+ if (!WATCHED.includes(rel))
51
+ skip();
52
+ const res = spawnSync(process.execPath, ['--test', SUITE], {
53
+ cwd: root,
54
+ encoding: 'utf8',
55
+ // Evita recursão: o teste roda `bin/forja.mjs`, que não deve reentrar no hook.
56
+ env: { ...process.env, FORJA_HOOK_TEST: '0' },
57
+ });
58
+ if (res.status === 0)
59
+ skip();
60
+ const detail = (res.stdout || '') + (res.stderr || '');
61
+ const failures = detail
62
+ .split('\n')
63
+ .filter((l) => /^not ok |^\s+error:|AssertionError/.test(l))
64
+ .slice(0, 12)
65
+ .join('\n');
66
+ process.stderr.write(`\`${rel}\` foi editado e \`${SUITE}\` quebrou — a integridade do registry (ADR-0020) está violada.\n\n` +
67
+ `${failures || detail.slice(-1500)}\n\n` +
68
+ `Um comando novo precisa de: entrada em lib/core/registry.ts + alias em package.json + script existente.\n`);
69
+ process.exit(2);
70
+ })();
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Hook SessionStart — imprime status do framework no início da sessão.
4
+ *
5
+ * Roda uma vez por sessão. Lê specs em aberto + handoffs pendentes do universal.db.
6
+ * Output vai para additionalContext (carregado pelo Claude no system).
7
+ *
8
+ * Regra de ouro: este hook nunca pode derrubar a sessão. Todo acesso a SQLite é
9
+ * lazy e envolto em try/catch — sem `node_modules`, degrada para o modo só-specs
10
+ * em vez de abortar (ADR-0021).
11
+ *
12
+ * A saúde do núcleo vem de `lib/core/health.mjs` — zero heurística local (SPEC-009). O hook tinha
13
+ * a sua, e ela mentia: um `catch { return null }` colapsava "sem node_modules", "ABI incompatível"
14
+ * e "banco ausente" no mesmo `null`, e então prescrevia `npm install` — que não recompila binário
15
+ * nativo. Quem seguisse o conselho do próprio framework não consertava nada.
16
+ */
17
+ export {};