forjajs 1.1.6 → 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 (172) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +62 -0
  3. package/README.en.md +33 -5
  4. package/README.md +35 -4
  5. package/boilerplates/06-clean-arch/README.md +48 -0
  6. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
  7. package/boilerplates/06-clean-arch/backend/package.json +43 -0
  8. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
  9. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
  10. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
  11. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
  12. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
  13. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
  14. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
  15. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
  16. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
  17. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
  18. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
  19. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
  20. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
  21. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
  22. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
  23. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
  24. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
  25. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
  26. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
  27. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
  28. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
  29. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
  30. package/boilerplates/README.md +20 -0
  31. package/dist/bin/create-memory-nest-kit.d.ts +2 -0
  32. package/dist/bin/create-memory-nest-kit.js +110 -0
  33. package/dist/bin/forja.d.ts +13 -0
  34. package/dist/bin/forja.js +136 -0
  35. package/dist/bin/init-project.d.ts +2 -0
  36. package/dist/bin/init-project.js +516 -0
  37. package/dist/lib/audit.d.ts +67 -0
  38. package/dist/lib/audit.js +143 -0
  39. package/dist/lib/context-builder.d.ts +58 -0
  40. package/dist/lib/context-builder.js +233 -0
  41. package/dist/lib/core/checks.d.ts +91 -0
  42. package/dist/lib/core/checks.js +119 -0
  43. package/dist/lib/core/doc-graph.d.ts +60 -0
  44. package/dist/lib/core/doc-graph.js +235 -0
  45. package/dist/lib/core/health.d.ts +103 -0
  46. package/dist/lib/core/health.js +538 -0
  47. package/dist/lib/core/registry.d.ts +296 -0
  48. package/dist/lib/core/registry.js +317 -0
  49. package/dist/lib/core/release.d.ts +334 -0
  50. package/dist/lib/core/release.js +465 -0
  51. package/dist/lib/generators/memory-generator.d.ts +83 -0
  52. package/{lib → dist/lib}/generators/memory-generator.js +107 -178
  53. package/dist/lib/generators/nest-generator.d.ts +15 -0
  54. package/{lib → dist/lib}/generators/nest-generator.js +47 -71
  55. package/dist/lib/generators/readme-generator.d.ts +15 -0
  56. package/{lib → dist/lib}/generators/readme-generator.js +9 -14
  57. package/dist/lib/governance-report.d.ts +49 -0
  58. package/dist/lib/governance-report.js +170 -0
  59. package/dist/lib/templates/harness/code-intel.d.mts +2 -0
  60. package/dist/lib/templates/harness/code-intel.mjs +126 -0
  61. package/dist/lib/utils/file-helpers.d.ts +9 -0
  62. package/dist/lib/utils/file-helpers.js +34 -0
  63. package/dist/lib/validators/structure-validator.d.ts +48 -0
  64. package/dist/lib/validators/structure-validator.js +232 -0
  65. package/dist/lib/workspace.d.ts +40 -0
  66. package/dist/lib/workspace.js +174 -0
  67. package/dist/scripts/agent-harness.d.ts +2 -0
  68. package/dist/scripts/agent-harness.js +556 -0
  69. package/dist/scripts/agent-router.d.ts +30 -0
  70. package/dist/scripts/agent-router.js +208 -0
  71. package/dist/scripts/audit-query.d.ts +2 -0
  72. package/dist/scripts/audit-query.js +43 -0
  73. package/dist/scripts/audit-sync.d.ts +2 -0
  74. package/dist/scripts/audit-sync.js +19 -0
  75. package/dist/scripts/build-smart-context.d.ts +1 -0
  76. package/dist/scripts/build-smart-context.js +75 -0
  77. package/dist/scripts/check-standards.d.ts +1 -0
  78. package/dist/scripts/check-standards.js +87 -0
  79. package/dist/scripts/compress-memory.d.ts +16 -0
  80. package/dist/scripts/compress-memory.js +157 -0
  81. package/dist/scripts/compress-project-memory.d.ts +1 -0
  82. package/dist/scripts/compress-project-memory.js +48 -0
  83. package/dist/scripts/context-ops.d.ts +2 -0
  84. package/dist/scripts/context-ops.js +464 -0
  85. package/dist/scripts/dev.d.ts +96 -0
  86. package/dist/scripts/dev.js +312 -0
  87. package/dist/scripts/extract-global-knowledge.d.ts +1 -0
  88. package/dist/scripts/extract-global-knowledge.js +43 -0
  89. package/dist/scripts/generate-dashboard.d.ts +1 -0
  90. package/dist/scripts/generate-dashboard.js +48 -0
  91. package/dist/scripts/governance-dashboard.d.ts +2 -0
  92. package/dist/scripts/governance-dashboard.js +36 -0
  93. package/dist/scripts/hook-guard-paths.d.ts +17 -0
  94. package/dist/scripts/hook-guard-paths.js +68 -0
  95. package/dist/scripts/hook-post-edit.d.ts +20 -0
  96. package/dist/scripts/hook-post-edit.js +70 -0
  97. package/dist/scripts/hook-session-start.d.ts +17 -0
  98. package/dist/scripts/hook-session-start.js +108 -0
  99. package/dist/scripts/hook-user-prompt.d.ts +22 -0
  100. package/dist/scripts/hook-user-prompt.js +193 -0
  101. package/dist/scripts/memory-schema.d.ts +6 -0
  102. package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
  103. package/dist/scripts/query-universal-memory.d.ts +1 -0
  104. package/dist/scripts/query-universal-memory.js +44 -0
  105. package/dist/scripts/release-check.d.ts +14 -0
  106. package/dist/scripts/release-check.js +48 -0
  107. package/dist/scripts/spec-cli.d.ts +29 -0
  108. package/dist/scripts/spec-cli.js +261 -0
  109. package/dist/scripts/sprint-manager.d.ts +1 -0
  110. package/dist/scripts/sprint-manager.js +187 -0
  111. package/dist/scripts/sync-universal-memory.d.ts +1 -0
  112. package/dist/scripts/sync-universal-memory.js +277 -0
  113. package/dist/scripts/token-benchmark.d.ts +20 -0
  114. package/dist/scripts/token-benchmark.js +181 -0
  115. package/dist/scripts/tools-doctor.d.ts +20 -0
  116. package/dist/scripts/tools-doctor.js +120 -0
  117. package/docs/personas/architect/README.md +4 -4
  118. package/docs/personas/developer/README.md +3 -3
  119. package/docs/personas/qa/README.md +3 -3
  120. package/docs/quick-reference.md +9 -9
  121. package/docs/structure.md +3 -3
  122. package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
  123. package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
  124. package/memory/90-decisions/0028-governanca-visivel.md +84 -0
  125. package/package.json +60 -56
  126. package/specs/clean-arch-boilerplate/plan.md +137 -0
  127. package/specs/clean-arch-boilerplate/spec.md +121 -0
  128. package/specs/clean-arch-boilerplate/tasks.md +70 -0
  129. package/specs/coerencia-do-sistema/plan.md +155 -0
  130. package/specs/coerencia-do-sistema/spec.md +15 -14
  131. package/specs/coerencia-do-sistema/tasks.md +115 -0
  132. package/specs/governanca-visivel/plan.md +122 -0
  133. package/specs/governanca-visivel/spec.md +112 -0
  134. package/specs/governanca-visivel/tasks.md +60 -0
  135. package/specs/ts-migration/plan.md +199 -0
  136. package/specs/ts-migration/spec.md +119 -0
  137. package/specs/ts-migration/tasks.md +110 -0
  138. package/bin/create-memory-nest-kit.js +0 -125
  139. package/bin/forja.mjs +0 -143
  140. package/bin/init-project.js +0 -612
  141. package/lib/context-builder.js +0 -257
  142. package/lib/core/checks.mjs +0 -138
  143. package/lib/core/health.mjs +0 -475
  144. package/lib/core/registry.mjs +0 -289
  145. package/lib/core/release.mjs +0 -452
  146. package/lib/templates/harness/code-intel.mjs +0 -119
  147. package/lib/templates/harness/mcp.json +0 -10
  148. package/lib/utils/file-helpers.js +0 -40
  149. package/lib/validators/structure-validator.js +0 -253
  150. package/lib/workspace.mjs +0 -213
  151. package/scripts/agent-harness.mjs +0 -578
  152. package/scripts/agent-router.mjs +0 -189
  153. package/scripts/build-smart-context.js +0 -87
  154. package/scripts/check-standards.js +0 -98
  155. package/scripts/compress-memory.mjs +0 -198
  156. package/scripts/compress-project-memory.js +0 -58
  157. package/scripts/context-ops.mjs +0 -463
  158. package/scripts/dev.mjs +0 -349
  159. package/scripts/extract-global-knowledge.js +0 -52
  160. package/scripts/generate-dashboard.js +0 -59
  161. package/scripts/hook-guard-paths.mjs +0 -75
  162. package/scripts/hook-post-edit.mjs +0 -79
  163. package/scripts/hook-session-start.mjs +0 -104
  164. package/scripts/hook-user-prompt.mjs +0 -185
  165. package/scripts/pre-commit.sh +0 -102
  166. package/scripts/query-universal-memory.js +0 -50
  167. package/scripts/release-check.mjs +0 -56
  168. package/scripts/spec-cli.mjs +0 -260
  169. package/scripts/sprint-manager.js +0 -200
  170. package/scripts/sync-universal-memory.js +0 -286
  171. package/scripts/token-benchmark.mjs +0 -203
  172. package/scripts/tools-doctor.mjs +0 -132
@@ -0,0 +1,277 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import crypto from 'node:crypto';
4
+ import Database from 'better-sqlite3';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { ensureSchema, getDbPath } from "./memory-schema.js";
7
+ import { initWorkspace, getProjectsDir, getWorkspaceSpecsDir, getWorkspaceProjectsMemoryDir, } from "../lib/workspace.js";
8
+ const __filename = fileURLToPath(import.meta.url);
9
+ const __dirname = path.dirname(__filename);
10
+ const root = path.resolve(__dirname, '..');
11
+ initWorkspace();
12
+ const dbPath = getDbPath();
13
+ const args = process.argv.slice(2);
14
+ const projectArgIndex = args.indexOf('--project');
15
+ const onlyProject = projectArgIndex >= 0 ? args[projectArgIndex + 1] : null;
16
+ const syncGlobal = !onlyProject || args.includes('--global');
17
+ const syncProjects = !args.includes('--global') || Boolean(onlyProject);
18
+ // Schema simplificado para a Memória Universal
19
+ const schema = `
20
+ CREATE TABLE IF NOT EXISTS projects (
21
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
22
+ name TEXT NOT NULL UNIQUE,
23
+ path TEXT NOT NULL,
24
+ created_at TEXT NOT NULL
25
+ );
26
+
27
+ CREATE TABLE IF NOT EXISTS memory_nodes (
28
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
29
+ project_id INTEGER, -- NULL se for global
30
+ path TEXT NOT NULL UNIQUE,
31
+ kind TEXT NOT NULL, -- 'global', 'project', 'domain', 'adr', 'summary'
32
+ title TEXT,
33
+ content TEXT NOT NULL,
34
+ content_hash TEXT NOT NULL,
35
+ updated_at TEXT NOT NULL,
36
+ FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
37
+ );
38
+
39
+ CREATE VIRTUAL TABLE IF NOT EXISTS search_idx USING fts5(
40
+ node_id UNINDEXED,
41
+ title,
42
+ content,
43
+ tokenize='porter'
44
+ );
45
+ `;
46
+ function log(msg, level = 'info') {
47
+ const prefix = { info: 'INFO', success: 'OK', warn: 'WARN', error: 'ERROR' }[level] || 'INFO';
48
+ console.log(`${prefix} ${msg}`);
49
+ }
50
+ function ensureDir(dir) {
51
+ if (!fs.existsSync(dir))
52
+ fs.mkdirSync(dir, { recursive: true });
53
+ }
54
+ function walk(dir, out = []) {
55
+ if (!fs.existsSync(dir))
56
+ return out;
57
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
58
+ if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.memory')
59
+ continue;
60
+ const abs = path.join(dir, entry.name);
61
+ if (entry.isDirectory())
62
+ walk(abs, out);
63
+ else if (entry.isFile() && entry.name.endsWith('.md'))
64
+ out.push(abs);
65
+ }
66
+ return out;
67
+ }
68
+ const dbDir = path.dirname(dbPath);
69
+ ensureDir(dbDir);
70
+ ensureSchema({ silent: true });
71
+ const db = new Database(dbPath);
72
+ db.exec(schema);
73
+ const upsertProject = db.prepare('INSERT INTO projects (name, path, created_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET path=excluded.path');
74
+ // RETURNING id devolve a linha realmente afetada, inserida ou atualizada.
75
+ // Sem ele restaria `lastInsertRowid`, que num upsert-que-atualizou guarda o id do
76
+ // último INSERT da conexão — um id alheio, e o FTS acabava indexando o conteúdo de
77
+ // um documento sob o node_id de outro (ADR-0021).
78
+ const upsertNode = db.prepare('INSERT INTO memory_nodes (project_id, path, kind, title, content, content_hash, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(path) DO UPDATE SET title=excluded.title, content=excluded.content, content_hash=excluded.content_hash, updated_at=excluded.updated_at RETURNING id');
79
+ const getProjectId = db.prepare('SELECT id FROM projects WHERE name = ?');
80
+ const deleteFts = db.prepare('DELETE FROM search_idx WHERE node_id = ?');
81
+ const insertFts = db.prepare('INSERT INTO search_idx (node_id, title, content) VALUES (?, ?, ?)');
82
+ const purgeFtsOrphans = db.prepare('DELETE FROM search_idx WHERE node_id NOT IN (SELECT id FROM memory_nodes)');
83
+ const upsertSpecSummary = db.prepare(`
84
+ INSERT INTO spec_summaries (slug, status, title, summary, source_path, updated_at)
85
+ VALUES (?, ?, ?, ?, ?, ?)
86
+ ON CONFLICT(slug) DO UPDATE SET
87
+ status=excluded.status,
88
+ title=excluded.title,
89
+ summary=excluded.summary,
90
+ source_path=excluded.source_path,
91
+ updated_at=excluded.updated_at
92
+ `);
93
+ const upsertAsset = db.prepare(`
94
+ INSERT INTO asset_catalog (type, name, path, summary, tags, updated_at)
95
+ VALUES (?, ?, ?, ?, ?, ?)
96
+ ON CONFLICT(path) DO UPDATE SET
97
+ type=excluded.type,
98
+ name=excluded.name,
99
+ summary=excluded.summary,
100
+ tags=excluded.tags,
101
+ updated_at=excluded.updated_at
102
+ `);
103
+ const now = new Date().toISOString();
104
+ function getKind(relPath) {
105
+ if (relPath.startsWith('memory/00-global'))
106
+ return 'global';
107
+ if (relPath.includes('/design-md/') || relPath.startsWith('design-md/'))
108
+ return 'design';
109
+ if (relPath.includes('90-decisions'))
110
+ return 'adr';
111
+ if (relPath.includes('70-summaries'))
112
+ return 'summary';
113
+ if (relPath.includes('30-domains'))
114
+ return 'domain';
115
+ return 'general';
116
+ }
117
+ function firstHeading(content, fallback) {
118
+ const match = content.match(/^#\s+(.+)$/m);
119
+ return match ? match[1].trim() : fallback;
120
+ }
121
+ function specStatus(content) {
122
+ const match = content.match(/-\s+\*\*Status\*\*:\s+([^\n]+)/);
123
+ return match ? match[1].trim() : 'unknown';
124
+ }
125
+ function extractSection(content, heading, maxChars = 1200) {
126
+ const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
127
+ const re = new RegExp(`^##\\s+${escaped}\\s*\\n([\\s\\S]*?)(?=^##\\s+|$)`, 'm');
128
+ const match = content.match(re);
129
+ return match ? match[1].trim().slice(0, maxChars) : '';
130
+ }
131
+ function summarizeReadme(relPath) {
132
+ const full = path.join(root, relPath);
133
+ if (!fs.existsSync(full))
134
+ return null;
135
+ const content = fs.readFileSync(full, 'utf8');
136
+ return content.split('\n')
137
+ .filter((line) => line.trim() && !line.startsWith('```'))
138
+ .slice(0, 10)
139
+ .join(' ')
140
+ .replace(/\s+/g, ' ')
141
+ .slice(0, 450);
142
+ }
143
+ function readJson(relPath) {
144
+ const full = path.join(root, relPath);
145
+ if (!fs.existsSync(full))
146
+ return null;
147
+ try {
148
+ return JSON.parse(fs.readFileSync(full, 'utf8'));
149
+ }
150
+ catch {
151
+ return null;
152
+ }
153
+ }
154
+ function syncSpecSummaries() {
155
+ const specsDir = path.join(root, 'specs');
156
+ if (!fs.existsSync(specsDir))
157
+ return;
158
+ let count = 0;
159
+ for (const entry of fs.readdirSync(specsDir, { withFileTypes: true })) {
160
+ if (!entry.isDirectory() || entry.name.startsWith('_'))
161
+ continue;
162
+ const slug = entry.name;
163
+ const rel = path.join('specs', slug, 'spec.md');
164
+ const full = path.join(root, rel);
165
+ if (!fs.existsSync(full))
166
+ continue;
167
+ const content = fs.readFileSync(full, 'utf8');
168
+ const title = firstHeading(content, slug);
169
+ const status = specStatus(content);
170
+ const summary = [
171
+ `## Problema\n${extractSection(content, '1. Problema', 900)}`,
172
+ `## Valor\n${extractSection(content, '2. Proposta de valor', 700)}`,
173
+ `## AC\n${extractSection(content, '4. Criterios de aceite', 1200) || extractSection(content, '4. Critérios de aceite', 1200)}`,
174
+ ].join('\n\n').slice(0, 3500);
175
+ upsertSpecSummary.run(slug, status, title, summary, rel, now);
176
+ count++;
177
+ }
178
+ log(`Spec summaries sincronizados: ${count}`, 'info');
179
+ }
180
+ function syncAssetCatalog() {
181
+ const assets = [];
182
+ const boilerRoot = path.join(root, 'boilerplates');
183
+ if (fs.existsSync(boilerRoot)) {
184
+ for (const entry of fs.readdirSync(boilerRoot, { withFileTypes: true })) {
185
+ if (!entry.isDirectory())
186
+ continue;
187
+ const rel = path.join('boilerplates', entry.name, 'README.md');
188
+ const summary = summarizeReadme(rel);
189
+ if (!summary)
190
+ continue;
191
+ const manifest = readJson(path.join('boilerplates', entry.name, 'boilerplate.manifest.json'));
192
+ const tags = manifest ? [...(manifest.stack || []), ...(manifest.useCases || [])].join(',') : firstHeading(summary, entry.name);
193
+ assets.push({ type: 'boilerplate', name: entry.name, path: rel, summary, tags });
194
+ }
195
+ }
196
+ const designRoot = path.join(root, 'design-md');
197
+ if (fs.existsSync(designRoot)) {
198
+ for (const entry of fs.readdirSync(designRoot, { withFileTypes: true })) {
199
+ if (!entry.isDirectory())
200
+ continue;
201
+ const rel = path.join('design-md', entry.name, 'README.md');
202
+ const summary = summarizeReadme(rel);
203
+ if (!summary)
204
+ continue;
205
+ const manifest = readJson(path.join('design-md', entry.name, 'design.manifest.json'));
206
+ const tags = manifest ? [...(manifest.surfaces || []), ...(manifest.traits || [])].join(',') : entry.name;
207
+ assets.push({ type: 'design-reference', name: entry.name, path: rel, summary, tags });
208
+ }
209
+ }
210
+ for (const asset of assets) {
211
+ upsertAsset.run(asset.type, asset.name, asset.path, asset.summary, asset.tags, now);
212
+ }
213
+ log(`Asset catalog sincronizado: ${assets.length}`, 'info');
214
+ }
215
+ function syncFiles(files, projectId = null) {
216
+ for (const abs of files) {
217
+ const rel = path.relative(root, abs);
218
+ const raw = fs.readFileSync(abs, 'utf8');
219
+ const hash = crypto.createHash('sha256').update(raw).digest('hex');
220
+ const titleMatch = raw.match(/^#\s+(.+)$/m);
221
+ const title = titleMatch ? titleMatch[1].trim() : path.basename(rel, '.md');
222
+ try {
223
+ const { id: nodeId } = upsertNode.get(projectId, rel, getKind(rel), title, raw, hash, now);
224
+ deleteFts.run(nodeId);
225
+ insertFts.run(nodeId, title, raw);
226
+ }
227
+ catch (e) {
228
+ log(`Erro sincronizando ${rel}: ${e.message}`, 'error');
229
+ }
230
+ }
231
+ }
232
+ // 1. Sincronizar Memória/Docs/Prompts Globais
233
+ if (syncGlobal) {
234
+ log('Sincronizando Memória Global...', 'info');
235
+ const globalFiles = [
236
+ ...walk(path.join(root, 'memory')),
237
+ ...walk(path.join(root, 'docs')),
238
+ ...walk(path.join(root, 'prompts')),
239
+ ];
240
+ syncFiles(globalFiles);
241
+ syncSpecSummaries();
242
+ syncAssetCatalog();
243
+ }
244
+ // 2. Sincronizar Projetos do Workspace
245
+ const projectsDir = getProjectsDir();
246
+ if (syncProjects && fs.existsSync(projectsDir)) {
247
+ const projects = fs.readdirSync(projectsDir, { withFileTypes: true })
248
+ .filter(e => e.isDirectory())
249
+ .filter(e => !onlyProject || e.name === onlyProject);
250
+ if (onlyProject && projects.length === 0) {
251
+ log(`Projeto nao encontrado para sync: ${onlyProject}`, 'warn');
252
+ }
253
+ for (const p of projects) {
254
+ log(`Sincronizando Projeto: ${p.name}...`, 'info');
255
+ const projectPath = path.join(projectsDir, p.name);
256
+ upsertProject.run(p.name, projectPath, now);
257
+ const pid = getProjectId.get(p.name).id;
258
+ // Indexa memória, documentação, spec SDD e referências de design do projeto (somente .md)
259
+ const projectMemFiles = walk(path.join(projectPath, 'memory'));
260
+ const projectDocsFiles = walk(path.join(projectPath, 'docs'));
261
+ const projectSpecFiles = walk(path.join(getWorkspaceSpecsDir(), p.name));
262
+ const projectDesignFiles = walk(path.join(projectPath, 'design-md'));
263
+ syncFiles([...projectMemFiles, ...projectDocsFiles, ...projectSpecFiles, ...projectDesignFiles], pid);
264
+ }
265
+ }
266
+ // 3. Sincronizar fichas de projetos no workspace memory/30-projects
267
+ const workspaceProjectsMemoryDir = getWorkspaceProjectsMemoryDir();
268
+ if (fs.existsSync(workspaceProjectsMemoryDir)) {
269
+ const fichaFiles = walk(workspaceProjectsMemoryDir);
270
+ syncFiles(fichaFiles);
271
+ }
272
+ // Nós removidos deixam linhas órfãs no FTS: matches que apontam para nada.
273
+ const orphans = purgeFtsOrphans.run().changes;
274
+ if (orphans)
275
+ log(`Índice FTS: ${orphans} linhas órfãs removidas`, 'info');
276
+ db.close();
277
+ log('Sincronização Universal Concluída!', 'success');
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Token Economy Benchmark - Measure token savings from smart context
4
+ *
5
+ * Compara:
6
+ * 1. Full context (antes) vs 3 modos (depois)
7
+ * 2. Mede tamanho, tokens, tempo de geração
8
+ * 3. Calcula redução %
9
+ *
10
+ * Uso: npm run token:benchmark
11
+ */
12
+ /**
13
+ * Estimar tokens (1KB ≈ 250 tokens, aproximação)
14
+ */
15
+ declare function estimateTokens(content: any): number;
16
+ /**
17
+ * Executar benchmark
18
+ */
19
+ declare function benchmark(): Promise<void>;
20
+ export { benchmark, estimateTokens };
@@ -0,0 +1,181 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Token Economy Benchmark - Measure token savings from smart context
4
+ *
5
+ * Compara:
6
+ * 1. Full context (antes) vs 3 modos (depois)
7
+ * 2. Mede tamanho, tokens, tempo de geração
8
+ * 3. Calcula redução %
9
+ *
10
+ * Uso: npm run token:benchmark
11
+ */
12
+ import fs from 'node:fs';
13
+ import path from 'node:path';
14
+ import ContextBuilder from '../lib/context-builder.js';
15
+ import { fileURLToPath } from 'node:url';
16
+ import { getDbPath, ensureSchema } from "./memory-schema.js";
17
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
18
+ const root = path.resolve(__dirname, '..');
19
+ /**
20
+ * Estimar tokens (1KB ≈ 250 tokens, aproximação)
21
+ */
22
+ function estimateTokens(content) {
23
+ const size = typeof content === 'number' ? content : content.length;
24
+ return Math.round(size / 4); // 1 token ~= 4 bytes
25
+ }
26
+ /**
27
+ * Formatar bytes em legível
28
+ */
29
+ function formatBytes(bytes) {
30
+ if (bytes === 0)
31
+ return '0 B';
32
+ const k = 1024;
33
+ const sizes = ['B', 'KB', 'MB'];
34
+ const i = Math.floor(Math.log(bytes) / Math.log(k));
35
+ return (bytes / Math.pow(k, i)).toFixed(2) + ' ' + sizes[i];
36
+ }
37
+ function walkMarkdown(dir, out = []) {
38
+ if (!fs.existsSync(dir))
39
+ return out;
40
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
41
+ if (['node_modules', '.git', '.memory', 'archive'].includes(entry.name))
42
+ continue;
43
+ const abs = path.join(dir, entry.name);
44
+ if (entry.isDirectory())
45
+ walkMarkdown(abs, out);
46
+ else if (entry.isFile() && entry.name.endsWith('.md'))
47
+ out.push(abs);
48
+ }
49
+ return out;
50
+ }
51
+ /**
52
+ * Executar benchmark
53
+ */
54
+ async function benchmark() {
55
+ console.log('Token Economy Benchmark\n');
56
+ ensureSchema({ silent: true });
57
+ const dbPath = getDbPath();
58
+ const project = 'benchmark-project';
59
+ if (!fs.existsSync(dbPath)) {
60
+ console.warn('Database not found at:', dbPath);
61
+ console.log(' Run: npm run memory:db:init');
62
+ process.exit(1);
63
+ }
64
+ const builder = new ContextBuilder(root, dbPath);
65
+ try {
66
+ // 1. Simular contexto "antigo" (sem smart context)
67
+ console.log('Scenario 1: Full Context (Baseline - No Optimization)\n');
68
+ const baselineStart = Date.now();
69
+ let fullContext = '';
70
+ const baselineRoots = ['AGENTS.md', 'README.md', 'DOC-MAP.md', 'memory', 'docs', 'prompts', 'specs'];
71
+ const baselineFiles = [];
72
+ for (const rel of baselineRoots) {
73
+ const abs = path.join(root, rel);
74
+ if (!fs.existsSync(abs))
75
+ continue;
76
+ const stat = fs.statSync(abs);
77
+ if (stat.isDirectory())
78
+ walkMarkdown(abs, baselineFiles);
79
+ else if (stat.isFile() && abs.endsWith('.md'))
80
+ baselineFiles.push(abs);
81
+ }
82
+ for (const filePath of baselineFiles) {
83
+ const rel = path.relative(root, filePath);
84
+ const content = fs.readFileSync(filePath, 'utf8');
85
+ fullContext += `\n\n## ${rel}\n${content}`;
86
+ }
87
+ const baselineDuration = Date.now() - baselineStart;
88
+ const baselineSize = fullContext.length;
89
+ const baselineTokens = estimateTokens(fullContext);
90
+ const baselineCost = (baselineTokens * 0.00001).toFixed(5);
91
+ console.log(` Size: ${formatBytes(baselineSize)}`);
92
+ console.log(` Tokens: ${baselineTokens.toLocaleString()}`);
93
+ console.log(` Files: ${baselineFiles.length}`);
94
+ console.log(` Time: ${baselineDuration}ms`);
95
+ console.log(` Cost: $${baselineCost}\n`);
96
+ // 2. Testar 3 modos de contexto inteligente
97
+ const modes = ['global', 'domain', 'task'];
98
+ const results = [];
99
+ for (const mode of modes) {
100
+ console.log(`Scenario: ${mode.toUpperCase()} Mode\n`);
101
+ const keyword = mode === 'task' ? 'architecture implementation' : '';
102
+ const start = Date.now();
103
+ let context = '';
104
+ try {
105
+ context = builder.build(mode, project, keyword);
106
+ }
107
+ catch (e) {
108
+ console.warn(` Error building context: ${e.message}`);
109
+ console.log(' Skipping this mode.\n');
110
+ continue;
111
+ }
112
+ const duration = Date.now() - start;
113
+ const size = context.length;
114
+ const tokens = estimateTokens(size);
115
+ const cost = (tokens * 0.00001).toFixed(5);
116
+ const savings = (((baselineTokens - tokens) / baselineTokens) * 100).toFixed(1);
117
+ console.log(` Size: ${formatBytes(size)}`);
118
+ console.log(` Tokens: ${tokens.toLocaleString()}`);
119
+ console.log(` Time: ${duration}ms`);
120
+ console.log(` Cost: $${cost}`);
121
+ console.log(` Savings: ${savings}% (vs baseline)\n`);
122
+ results.push({
123
+ mode,
124
+ size,
125
+ tokens,
126
+ time: duration,
127
+ cost: parseFloat(cost),
128
+ savings: parseFloat(savings),
129
+ });
130
+ }
131
+ // 3. Sumário
132
+ console.log('Summary\n');
133
+ const avgSavings = results.reduce((sum, r) => sum + r.savings, 0) / results.length;
134
+ const avgTokens = results.reduce((sum, r) => sum + r.tokens, 0) / results.length;
135
+ const avgCost = results.reduce((sum, r) => sum + r.cost, 0) / results.length;
136
+ const bestMode = results.reduce((best, r) => (r.tokens < best.tokens ? r : best));
137
+ console.log(`Baseline (Full Context)`);
138
+ console.log(` Tokens: ${baselineTokens.toLocaleString()}`);
139
+ console.log(` Cost: $${baselineCost}\n`);
140
+ console.log(`Smart Context Average`);
141
+ console.log(` Tokens: ${avgTokens.toLocaleString()}`);
142
+ console.log(` Cost: $${avgCost.toFixed(5)}`);
143
+ console.log(` Savings: ${avgSavings.toFixed(1)}%\n`);
144
+ console.log(`Best Mode: ${bestMode.mode.toUpperCase()}`);
145
+ console.log(` Tokens: ${bestMode.tokens.toLocaleString()}`);
146
+ console.log(` Cost: $${bestMode.cost.toFixed(5)}`);
147
+ console.log(` Savings: ${bestMode.savings.toFixed(1)}%\n`);
148
+ // 4. Cálculo de ROI
149
+ const monthlyRequests = 1000;
150
+ const savedCostPerMonth = (baselineTokens - avgTokens) * 0.00001 * monthlyRequests;
151
+ console.log('ROI Analysis (1000 requests/month)');
152
+ console.log(` Baseline cost: $${(baselineTokens * 0.00001 * monthlyRequests).toFixed(2)}`);
153
+ console.log(` Smart cost: $${(avgTokens * 0.00001 * monthlyRequests).toFixed(2)}`);
154
+ console.log(` Monthly savings: $${savedCostPerMonth.toFixed(2)}`);
155
+ console.log(` Annual savings: $${(savedCostPerMonth * 12).toFixed(2)}\n`);
156
+ // 5. Recomendação
157
+ console.log('Recommendation');
158
+ if (avgSavings > 40) {
159
+ console.log(` Deploy: ${avgSavings.toFixed(1)}% savings exceeds 40% target.`);
160
+ }
161
+ else if (avgSavings > 20) {
162
+ console.log(` Good savings (${avgSavings.toFixed(1)}%) but optimize further.`);
163
+ }
164
+ else {
165
+ console.log(` Savings too low (${avgSavings.toFixed(1)}%). Review strategy.`);
166
+ }
167
+ console.log('\nBenchmark complete.\n');
168
+ }
169
+ catch (e) {
170
+ console.error('Benchmark error:', e.message);
171
+ process.exit(1);
172
+ }
173
+ finally {
174
+ builder.close();
175
+ }
176
+ }
177
+ // Run if called via CLI
178
+ if (import.meta.url === `file://${process.argv[1]}`) {
179
+ benchmark().catch(console.error);
180
+ }
181
+ export { benchmark, estimateTokens };
@@ -0,0 +1,20 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * tools-doctor — raio-x do núcleo (SPEC-009) e das ferramentas de processo (ADR-0018).
4
+ *
5
+ * Duas seções, dois contratos distintos:
6
+ *
7
+ * Núcleo O que impede o framework de trabalhar. Falha crítica → exit 1.
8
+ * Ferramentas Binários opcionais que potencializam o harness. Ausência nunca trava.
9
+ *
10
+ * A separação é o ponto. Este comando auditava só as ferramentas — sobre as quais ele mesmo
11
+ * dizia "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o better-sqlite3
12
+ * ficou com ABI de outra major do Node e a memória universal morreu inteira, o doctor reportou
13
+ * "2/5 ferramentas disponíveis" e saiu com 0.
14
+ *
15
+ * Diagnostica e prescreve; não conserta. Rodar `npm rebuild` sem consentimento é a classe de
16
+ * risco oposta à que este comando existe para fechar.
17
+ *
18
+ * Uso: node scripts/tools-doctor.mjs
19
+ */
20
+ export {};
@@ -0,0 +1,120 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * tools-doctor — raio-x do núcleo (SPEC-009) e das ferramentas de processo (ADR-0018).
4
+ *
5
+ * Duas seções, dois contratos distintos:
6
+ *
7
+ * Núcleo O que impede o framework de trabalhar. Falha crítica → exit 1.
8
+ * Ferramentas Binários opcionais que potencializam o harness. Ausência nunca trava.
9
+ *
10
+ * A separação é o ponto. Este comando auditava só as ferramentas — sobre as quais ele mesmo
11
+ * dizia "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o better-sqlite3
12
+ * ficou com ABI de outra major do Node e a memória universal morreu inteira, o doctor reportou
13
+ * "2/5 ferramentas disponíveis" e saiu com 0.
14
+ *
15
+ * Diagnostica e prescreve; não conserta. Rodar `npm rebuild` sem consentimento é a classe de
16
+ * risco oposta à que este comando existe para fechar.
17
+ *
18
+ * Uso: node scripts/tools-doctor.mjs
19
+ */
20
+ import { spawnSync } from 'node:child_process';
21
+ import { runChecks, worstStatus } from "../lib/core/health.js";
22
+ const TOOLS = [
23
+ {
24
+ name: 'codegraph',
25
+ probe: ['codegraph', ['--version']],
26
+ role: 'Code intelligence: chamadores, blast radius, mapa de impacto (ADR-0017).',
27
+ install: 'npm i -g @codegraph/cli',
28
+ gate: 'npm run code:check / code:impact',
29
+ },
30
+ {
31
+ name: 'gitleaks',
32
+ probe: ['gitleaks', ['version']],
33
+ role: 'Varredura de segredos antes de merge/release.',
34
+ install: 'https://github.com/gitleaks/gitleaks (binario) ou: brew install gitleaks',
35
+ gate: 'gitleaks detect --no-banner (gate de Governance)',
36
+ },
37
+ {
38
+ name: 'ast-grep',
39
+ probe: ['ast-grep', ['--version']],
40
+ role: 'Busca e codemod estrutural por AST — refactor seguro do Worker.',
41
+ install: 'npm i -g @ast-grep/cli (binarios: ast-grep / sg)',
42
+ gate: 'ast-grep run -p "<pattern>" -r "<rewrite>"',
43
+ },
44
+ {
45
+ name: 'lefthook',
46
+ probe: ['lefthook', ['version']],
47
+ role: 'Pre-commit rodando project:check / spec:check automaticamente.',
48
+ install: 'npm i -g lefthook (depois: lefthook install)',
49
+ gate: '.lefthook.yml (pre-commit)',
50
+ },
51
+ {
52
+ name: 'markdownlint',
53
+ probe: ['markdownlint-cli2', ['--version']],
54
+ role: 'Lint da documentacao (docs e memory sao centrais aqui).',
55
+ install: 'npm i -g markdownlint-cli2',
56
+ gate: 'markdownlint-cli2 "docs/**/*.md"',
57
+ },
58
+ ];
59
+ function detect(cmd, args) {
60
+ const res = spawnSync(cmd, args, { encoding: 'utf8' });
61
+ if (res.error && res.error.code === 'ENOENT')
62
+ return { ok: false };
63
+ const version = (res.stdout || res.stderr || '').trim().split('\n')[0] || 'instalado';
64
+ return { ok: true, version };
65
+ }
66
+ const TAG = {
67
+ ok: 'OK ',
68
+ warn: 'AVISO',
69
+ fail: 'FALHA',
70
+ skipped: '— ',
71
+ };
72
+ function printCore(results) {
73
+ console.log('Núcleo — o que impede o framework de trabalhar (SPEC-009)\n');
74
+ for (const r of results) {
75
+ console.log(`${TAG[r.status]} ${r.id.padEnd(13)} ${r.detail}`);
76
+ if (r.fix)
77
+ console.log(` corrigir: ${r.fix}`);
78
+ console.log('');
79
+ }
80
+ }
81
+ function printTools() {
82
+ console.log('Ferramentas de processo — opcionais (ADR-0018)\n');
83
+ let installed = 0;
84
+ for (const tool of TOOLS) {
85
+ const [cmd, args] = tool.probe;
86
+ const { ok, version } = detect(cmd, args);
87
+ if (ok)
88
+ installed += 1;
89
+ console.log(`${ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
90
+ console.log(` papel: ${tool.role}`);
91
+ console.log(` gate: ${tool.gate}`);
92
+ if (!ok)
93
+ console.log(` instalar: ${tool.install}`);
94
+ console.log('');
95
+ }
96
+ console.log(`${installed}/${TOOLS.length} ferramentas disponíveis.`);
97
+ console.log('Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.\n');
98
+ }
99
+ async function main() {
100
+ console.log('\nForja doctor\n');
101
+ const core = await runChecks();
102
+ printCore(core);
103
+ printTools();
104
+ // Só o núcleo decide o exit code. Ferramenta ausente nunca reprova — o contrato do ADR-0018
105
+ // é preservado à risca.
106
+ const verdict = worstStatus(core);
107
+ if (verdict === 'fail') {
108
+ const raiz = core.filter((r) => r.status === 'fail' && r.severity === 'critical');
109
+ console.log(`Núcleo quebrado — ${raiz.length} ${raiz.length === 1 ? 'falha' : 'falhas'} crítica(s).`);
110
+ for (const r of raiz)
111
+ console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
112
+ process.exit(1);
113
+ }
114
+ if (verdict === 'warn') {
115
+ console.log('Núcleo operante, com ressalvas. Nada trava o fluxo.');
116
+ return;
117
+ }
118
+ console.log('Núcleo saudável.');
119
+ }
120
+ main();
@@ -309,10 +309,10 @@ Seguir [Guia de Developer](../developer/README.md)
309
309
 
310
310
  | Documento | Quando ler |
311
311
  |-----------|-----------|
312
- | [REFINAMENTO-v1.0.md](../../REFINAMENTO-v1.0.md) | Especificação técnica completa |
313
- | [ESTRUTURA-PROJETO.md](../../ESTRUTURA-PROJETO.md) | Hierarquia de diretórios |
314
- | [memory/20-architecture/](../../memory/20-architecture/) | Design do seu projeto |
315
- | [EXEMPLOS-CODIGO.md](../../EXEMPLOS-CODIGO.md) | Padrões prontos |
312
+ | [AGENTS.md](../../../AGENTS.md) | Os 6 papéis e a topologia |
313
+ | [memory/90-decisions/](../../../memory/90-decisions/) | ADRs com rationale |
314
+ | [structure.md](../../structure.md) | Estrutura de diretórios |
315
+ | [agent-harnesses.md](../../agent-harnesses.md) | Harness e ferramentas de processo |
316
316
 
317
317
  ---
318
318
 
@@ -294,9 +294,9 @@ open coverage/index.html
294
294
 
295
295
  | Recurso | Quando usar |
296
296
  |---------|------------|
297
- | [EXEMPLOS-CODIGO.md](../../EXEMPLOS-CODIGO.md) | "Como faço X?" |
298
- | [REFERENCIA-RAPIDA.md](../../REFERENCIA-RAPIDA.md) | Atalhos de comandos |
299
- | [IMPLEMENTACAO-FASE1.md](../../IMPLEMENTACAO-FASE1.md) | Roteiros práticos |
297
+ | [boilerplates/](../../../boilerplates/README.md) | Padrões prontos por stack |
298
+ | [quick-reference.md](../../quick-reference.md) | Atalhos de comandos |
299
+ | [fluxo.md](../../fluxo.md) | Roteiro do ciclo CLI-first |
300
300
  | [NestJS Docs](https://docs.nestjs.com) | Dúvidas NestJS |
301
301
 
302
302
  ---
@@ -339,9 +339,9 @@ POST /api/seu-endpoint com payload { "campo": "valor especial" }
339
339
 
340
340
  | Recurso | Quando usar |
341
341
  |---------|------------|
342
- | [CHECKLIST-FINAL.md](../../CHECKLIST-FINAL.md) | Critérios globais |
343
- | [DASHBOARD-PROGRESSO.md](../../DASHBOARD-PROGRESSO.md) | Status do projeto |
344
- | [REFINAMENTO-v1.0.md](../../REFINAMENTO-v1.0.md) | Segurança (SEC-*) |
342
+ | [agent-harnesses.md](../../agent-harnesses.md) | Gates e ferramentas de processo |
343
+ | [DOC-MAP.md](../../../DOC-MAP.md) | Mapa da documentação |
344
+ | [memory/90-decisions/](../../../memory/90-decisions/) | Decisões e rationale |
345
345
 
346
346
  ---
347
347