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,67 @@
1
+ /**
2
+ * lib/audit.mjs — a trilha de auditoria como dado consultável (SPEC-014).
3
+ *
4
+ * O core grava toda execução em `.context/forja-runs.jsonl` (ADR-0020): `{ts, cmd, args, exitCode,
5
+ * durationMs}`, uma linha por run. É o dado mais rico de governança do framework — e era write-only.
6
+ *
7
+ * Aqui ele vira consultável, sem deixar de ser resiliente: o `.jsonl` continua a **fonte de
8
+ * verdade** append-only (sobrevive ao banco morto, ADR-0021); a tabela `audit_runs` é uma
9
+ * **projeção reconstruível** por `syncAudit`. Idempotência por `line_hash` (hash do conteúdo da
10
+ * linha): re-sincronizar não duplica, e truncar/reescrever o log não corrompe a tabela.
11
+ *
12
+ * Puro e com `env` injetável — os testes rodam sobre um jsonl de fixture, sem tocar o workspace.
13
+ */
14
+ import fs from 'node:fs';
15
+ /** @typedef {{ ts: string, cmd: string, args: string[], exitCode: number, durationMs: number }} Run */
16
+ /** @returns {{ fs: typeof fs, dbPath: string, jsonlPath: string }} */
17
+ export declare function defaultEnv(overrides?: {}): {
18
+ fs: typeof fs;
19
+ dbPath: string;
20
+ jsonlPath: string;
21
+ };
22
+ /**
23
+ * Ingere o `.jsonl` na tabela `audit_runs`. Idempotente (INSERT OR IGNORE por line_hash).
24
+ * Linha malformada é pulada — um log corrompido no meio não impede o resto.
25
+ *
26
+ * @returns {Promise<{ ingested: number, total: number, skipped: number }>}
27
+ */
28
+ export declare function syncAudit(env?: {
29
+ fs: typeof fs;
30
+ dbPath: string;
31
+ jsonlPath: string;
32
+ }): Promise<{
33
+ ingested: number;
34
+ total: any;
35
+ skipped: number;
36
+ }>;
37
+ /**
38
+ * Consulta estruturada. `{ since, cmd, gate, failed }`.
39
+ * @returns {Promise<Run[]>}
40
+ */
41
+ export declare function queryAudit(env?: {
42
+ fs: typeof fs;
43
+ dbPath: string;
44
+ jsonlPath: string;
45
+ }, opts?: {
46
+ since?: string;
47
+ cmd?: string;
48
+ failed?: boolean;
49
+ gate?: string;
50
+ }): Promise<any>;
51
+ /**
52
+ * Resumo para o painel: total, falhas, por comando, mais lentos, recentes.
53
+ * @returns {Promise<{ total, fails, byCmd, slowest, recent }>}
54
+ */
55
+ export declare function auditSummary(env?: {
56
+ fs: typeof fs;
57
+ dbPath: string;
58
+ jsonlPath: string;
59
+ }): Promise<{
60
+ total: any;
61
+ fails: any;
62
+ byCmd: any;
63
+ slowest: any;
64
+ recent: any;
65
+ }>;
66
+ /** Último exit code de um comando (para o painel mostrar o estado sem reexecutar — D4). */
67
+ export declare function lastExit(env: any, cmd: any): Promise<any>;
@@ -0,0 +1,143 @@
1
+ /**
2
+ * lib/audit.mjs — a trilha de auditoria como dado consultável (SPEC-014).
3
+ *
4
+ * O core grava toda execução em `.context/forja-runs.jsonl` (ADR-0020): `{ts, cmd, args, exitCode,
5
+ * durationMs}`, uma linha por run. É o dado mais rico de governança do framework — e era write-only.
6
+ *
7
+ * Aqui ele vira consultável, sem deixar de ser resiliente: o `.jsonl` continua a **fonte de
8
+ * verdade** append-only (sobrevive ao banco morto, ADR-0021); a tabela `audit_runs` é uma
9
+ * **projeção reconstruível** por `syncAudit`. Idempotência por `line_hash` (hash do conteúdo da
10
+ * linha): re-sincronizar não duplica, e truncar/reescrever o log não corrompe a tabela.
11
+ *
12
+ * Puro e com `env` injetável — os testes rodam sobre um jsonl de fixture, sem tocar o workspace.
13
+ */
14
+ import fs from 'node:fs';
15
+ import { createHash } from 'node:crypto';
16
+ import { getWorkspaceDbPath, getWorkspaceContextDir } from "./workspace.js";
17
+ /** @typedef {{ ts: string, cmd: string, args: string[], exitCode: number, durationMs: number }} Run */
18
+ /** @returns {{ fs: typeof fs, dbPath: string, jsonlPath: string }} */
19
+ export function defaultEnv(overrides = {}) {
20
+ return {
21
+ fs,
22
+ dbPath: getWorkspaceDbPath(),
23
+ jsonlPath: `${getWorkspaceContextDir()}/forja-runs.jsonl`,
24
+ ...overrides,
25
+ };
26
+ }
27
+ function lineHash(line) {
28
+ return createHash('sha1').update(line).digest('hex');
29
+ }
30
+ async function openDb(env) {
31
+ const { default: Database } = await import('better-sqlite3');
32
+ const db = new Database(env.dbPath);
33
+ // Auto-suficiente: cria a própria tabela no db que abre. Idempotente, e desacopla o audit do
34
+ // ensureSchema do workspace — é o que torna a lógica testável contra um db temporário.
35
+ db.exec(`CREATE TABLE IF NOT EXISTS audit_runs (
36
+ line_hash TEXT PRIMARY KEY, ts TEXT, cmd TEXT, args TEXT,
37
+ exit_code INTEGER, duration_ms INTEGER
38
+ )`);
39
+ return db;
40
+ }
41
+ /**
42
+ * Ingere o `.jsonl` na tabela `audit_runs`. Idempotente (INSERT OR IGNORE por line_hash).
43
+ * Linha malformada é pulada — um log corrompido no meio não impede o resto.
44
+ *
45
+ * @returns {Promise<{ ingested: number, total: number, skipped: number }>}
46
+ */
47
+ export async function syncAudit(env = defaultEnv()) {
48
+ if (!env.fs.existsSync(env.jsonlPath)) {
49
+ return { ingested: 0, total: 0, skipped: 0 };
50
+ }
51
+ const lines = env.fs.readFileSync(env.jsonlPath, 'utf8').split('\n').filter((l) => l.trim());
52
+ const db = await openDb(env);
53
+ const insert = db.prepare(`INSERT OR IGNORE INTO audit_runs (line_hash, ts, cmd, args, exit_code, duration_ms)
54
+ VALUES (@line_hash, @ts, @cmd, @args, @exit_code, @duration_ms)`);
55
+ let ingested = 0;
56
+ let skipped = 0;
57
+ const run = db.transaction((rows) => {
58
+ for (const row of rows) {
59
+ const res = insert.run(row);
60
+ ingested += res.changes;
61
+ }
62
+ });
63
+ const rows = [];
64
+ for (const line of lines) {
65
+ try {
66
+ const r = JSON.parse(line);
67
+ rows.push({
68
+ line_hash: lineHash(line),
69
+ ts: r.ts ?? null,
70
+ cmd: r.cmd ?? r.command ?? null,
71
+ args: JSON.stringify(r.args ?? []),
72
+ exit_code: r.exitCode ?? null,
73
+ duration_ms: r.durationMs ?? null,
74
+ });
75
+ }
76
+ catch {
77
+ skipped += 1; // linha corrompida — pula, não derruba o sync
78
+ }
79
+ }
80
+ run(rows);
81
+ const total = db.prepare('SELECT count(*) AS n FROM audit_runs').get().n;
82
+ db.close();
83
+ return { ingested, total, skipped };
84
+ }
85
+ /** Converte `7d` / `24h` / `30m` num timestamp ISO de corte, ou null. */
86
+ function sinceCutoff(since) {
87
+ if (!since)
88
+ return null;
89
+ const m = /^(\d+)([dhm])$/.exec(since);
90
+ if (!m)
91
+ return null;
92
+ const [, n, unit] = m;
93
+ const ms = { d: 864e5, h: 36e5, m: 6e4 }[unit] * Number(n);
94
+ return new Date(Date.now() - ms).toISOString();
95
+ }
96
+ /**
97
+ * Consulta estruturada. `{ since, cmd, gate, failed }`.
98
+ * @returns {Promise<Run[]>}
99
+ */
100
+ export async function queryAudit(env = defaultEnv(), opts = {}) {
101
+ const db = await openDb(env);
102
+ const where = [];
103
+ const params = {};
104
+ const cutoff = sinceCutoff(opts.since);
105
+ if (cutoff) {
106
+ where.push('ts >= @cutoff');
107
+ params.cutoff = cutoff;
108
+ }
109
+ if (opts.cmd) {
110
+ where.push('cmd = @cmd');
111
+ params.cmd = opts.cmd;
112
+ }
113
+ if (opts.failed)
114
+ where.push('exit_code != 0');
115
+ const sql = `SELECT ts, cmd, args, exit_code AS exitCode, duration_ms AS durationMs
116
+ FROM audit_runs ${where.length ? 'WHERE ' + where.join(' AND ') : ''}
117
+ ORDER BY ts DESC`;
118
+ const rows = db.prepare(sql).all(params);
119
+ db.close();
120
+ return rows.map((r) => ({ ...r, args: JSON.parse(r.args || '[]') }));
121
+ }
122
+ /**
123
+ * Resumo para o painel: total, falhas, por comando, mais lentos, recentes.
124
+ * @returns {Promise<{ total, fails, byCmd, slowest, recent }>}
125
+ */
126
+ export async function auditSummary(env = defaultEnv()) {
127
+ const db = await openDb(env);
128
+ const total = db.prepare('SELECT count(*) AS n FROM audit_runs').get().n;
129
+ const fails = db.prepare('SELECT count(*) AS n FROM audit_runs WHERE exit_code != 0').get().n;
130
+ const byCmd = db.prepare(`SELECT cmd, count(*) AS runs, sum(exit_code != 0) AS fails, round(avg(duration_ms)) AS avgMs
131
+ FROM audit_runs GROUP BY cmd ORDER BY runs DESC`).all();
132
+ const slowest = db.prepare('SELECT cmd, max(duration_ms) AS ms FROM audit_runs GROUP BY cmd ORDER BY ms DESC LIMIT 5').all();
133
+ const recent = db.prepare('SELECT ts, cmd, exit_code AS exitCode, duration_ms AS durationMs FROM audit_runs ORDER BY ts DESC LIMIT 12').all();
134
+ db.close();
135
+ return { total, fails, byCmd, slowest, recent };
136
+ }
137
+ /** Último exit code de um comando (para o painel mostrar o estado sem reexecutar — D4). */
138
+ export async function lastExit(env, cmd) {
139
+ const db = await openDb(env);
140
+ const row = db.prepare('SELECT exit_code AS exitCode, ts FROM audit_runs WHERE cmd = ? ORDER BY ts DESC LIMIT 1').get(cmd);
141
+ db.close();
142
+ return row ?? null;
143
+ }
@@ -0,0 +1,58 @@
1
+ export class ContextBuilder {
2
+ constructor(projectPath: any, dbPath: any);
3
+ projectPath: any;
4
+ dbPath: any;
5
+ db: any;
6
+ cache: Map<any, any>;
7
+ maxCacheSize: number;
8
+ /**
9
+ * Abrir conexão com banco de dados (readonly)
10
+ */
11
+ connect(): void;
12
+ /**
13
+ * Fechar conexão
14
+ */
15
+ close(): void;
16
+ /**
17
+ * Construir contexto no modo especificado
18
+ *
19
+ * @param {string} mode - 'global', 'domain', 'task'
20
+ * @param {string} project - Nome do projeto
21
+ * @param {string} keyword - Palavra-chave para busca (modo 'task')
22
+ * @returns {string} Conteúdo do contexto em markdown
23
+ */
24
+ build(mode: string, project: string, keyword?: string): string;
25
+ /**
26
+ * Obter contexto global (mission, standards, padrões)
27
+ */
28
+ _getGlobalNodes(): any;
29
+ /**
30
+ * Obter contexto de domínio (vision, design, rules do projeto)
31
+ */
32
+ _getDomainNodes(project: any): any;
33
+ /**
34
+ * Obter contexto orientado a tarefa (busca por FTS5)
35
+ */
36
+ _getTaskNodes(project: any, keyword: any): any;
37
+ /**
38
+ * Gerar markdown deduplicado
39
+ */
40
+ _generateMarkdown(mode: any, project: any, keyword: any, nodes: any, seenPaths: any): string;
41
+ /**
42
+ * Salvar contexto em arquivo
43
+ */
44
+ save(content: any, outputPath: any): void;
45
+ /**
46
+ * Estatísticas de contexto
47
+ */
48
+ stats(mode: any, project: any, keyword?: string): {
49
+ mode: any;
50
+ project: any;
51
+ keyword: string;
52
+ bytes: number;
53
+ lines: number;
54
+ tokens: number;
55
+ estimatedCost: string;
56
+ };
57
+ }
58
+ export default ContextBuilder;
@@ -0,0 +1,233 @@
1
+ /**
2
+ * Context Builder - API Reutilizável para Construção de Contexto Inteligente
3
+ *
4
+ * Suporta 3 modos de contexto:
5
+ * - 'global': Apenas contexto global (mission, standards, decisões recentes)
6
+ * - 'domain': Contexto de domínio específico + globais
7
+ * - 'task': Contexto orientado a tarefa + domain + globais (mais compacto)
8
+ *
9
+ * Usa SQLite FTS5 para busca eficiente e cache local para reutilização.
10
+ */
11
+ import fs from 'node:fs';
12
+ import path from 'node:path';
13
+ import Database from 'better-sqlite3';
14
+ import { getDbPath, ensureSchema } from "../scripts/memory-schema.js";
15
+ export class ContextBuilder {
16
+ constructor(projectPath, dbPath) {
17
+ this.projectPath = projectPath;
18
+ this.dbPath = dbPath;
19
+ this.db = null;
20
+ this.cache = new Map();
21
+ this.maxCacheSize = 50; // MB
22
+ }
23
+ /**
24
+ * Abrir conexão com banco de dados (readonly)
25
+ */
26
+ connect() {
27
+ if (this.db)
28
+ return;
29
+ if (!fs.existsSync(this.dbPath)) {
30
+ throw new Error(`Database not found: ${this.dbPath}`);
31
+ }
32
+ this.db = new Database(this.dbPath, { readonly: true });
33
+ }
34
+ /**
35
+ * Fechar conexão
36
+ */
37
+ close() {
38
+ if (this.db) {
39
+ this.db.close();
40
+ this.db = null;
41
+ }
42
+ }
43
+ /**
44
+ * Construir contexto no modo especificado
45
+ *
46
+ * @param {string} mode - 'global', 'domain', 'task'
47
+ * @param {string} project - Nome do projeto
48
+ * @param {string} keyword - Palavra-chave para busca (modo 'task')
49
+ * @returns {string} Conteúdo do contexto em markdown
50
+ */
51
+ build(mode, project, keyword = '') {
52
+ this.connect();
53
+ const started = Date.now();
54
+ const nodes = [];
55
+ const seenPaths = new Set();
56
+ // 1. Contexto global obrigatório
57
+ const globalNodes = this._getGlobalNodes();
58
+ nodes.push(...globalNodes);
59
+ // 2. Contexto específico por modo
60
+ if (mode === 'domain' || mode === 'task') {
61
+ const domainNodes = this._getDomainNodes(project);
62
+ nodes.push(...domainNodes);
63
+ }
64
+ if (mode === 'task' && keyword) {
65
+ const taskNodes = this._getTaskNodes(project, keyword);
66
+ nodes.push(...taskNodes);
67
+ }
68
+ // 3. Gerar markdown deduplicado
69
+ let context = this._generateMarkdown(mode, project, keyword, nodes, seenPaths);
70
+ const duration = Date.now() - started;
71
+ // 4. Adicionar footer com metadata
72
+ const footer = `\n\n---\n\n## 📊 Context Metadata\n\n` +
73
+ `- **Mode**: ${mode}\n` +
74
+ `- **Project**: ${project}\n` +
75
+ `- **Keyword**: ${keyword || 'none'}\n` +
76
+ `- **Generated**: ${new Date().toISOString()}\n` +
77
+ `- **Duration**: ${duration}ms\n` +
78
+ `- **Files**: ${seenPaths.size}\n` +
79
+ `- **Size**: ${Math.round(context.length / 1024)}KB\n`;
80
+ return context + footer;
81
+ }
82
+ /**
83
+ * Obter contexto global (mission, standards, padrões)
84
+ */
85
+ _getGlobalNodes() {
86
+ try {
87
+ const stmt = this.db.prepare(`
88
+ SELECT title, content, path FROM memory_nodes
89
+ WHERE project_id IS NULL
90
+ AND (
91
+ path LIKE '%mission.md'
92
+ OR path LIKE '%standards.md'
93
+ OR path LIKE '%ADR-%'
94
+ )
95
+ ORDER BY updated_at DESC
96
+ LIMIT 10
97
+ `);
98
+ return stmt.all() || [];
99
+ }
100
+ catch (e) {
101
+ console.warn('⚠️ No global nodes found:', e.message);
102
+ return [];
103
+ }
104
+ }
105
+ /**
106
+ * Obter contexto de domínio (vision, design, rules do projeto)
107
+ */
108
+ _getDomainNodes(project) {
109
+ try {
110
+ const stmt = this.db.prepare(`
111
+ SELECT DISTINCT n.title, n.content, n.path
112
+ FROM memory_nodes n
113
+ JOIN projects p ON p.id = n.project_id
114
+ WHERE p.name = ?
115
+ AND (
116
+ n.path LIKE '%vision.md'
117
+ OR n.path LIKE '%design%'
118
+ OR n.path LIKE '%rules.md'
119
+ OR n.path LIKE '%summary%'
120
+ )
121
+ ORDER BY n.updated_at DESC
122
+ LIMIT 15
123
+ `);
124
+ return stmt.all(project) || [];
125
+ }
126
+ catch (e) {
127
+ console.warn(`⚠️ No domain nodes found for ${project}:`, e.message);
128
+ return [];
129
+ }
130
+ }
131
+ /**
132
+ * Obter contexto orientado a tarefa (busca por FTS5)
133
+ */
134
+ _getTaskNodes(project, keyword) {
135
+ try {
136
+ const stmt = this.db.prepare(`
137
+ SELECT DISTINCT n.title, n.content, n.path
138
+ FROM memory_nodes n
139
+ JOIN projects p ON p.id = n.project_id
140
+ LEFT JOIN search_idx s ON s.node_id = n.id
141
+ WHERE p.name = ?
142
+ AND (n.content LIKE ? OR s.content MATCH ?)
143
+ ORDER BY n.updated_at DESC
144
+ LIMIT 20
145
+ `);
146
+ const pattern = `%${keyword}%`;
147
+ return stmt.all(project, pattern, keyword) || [];
148
+ }
149
+ catch (e) {
150
+ console.warn(`⚠️ No task nodes found for "${keyword}":`, e.message);
151
+ return [];
152
+ }
153
+ }
154
+ /**
155
+ * Gerar markdown deduplicado
156
+ */
157
+ _generateMarkdown(mode, project, keyword, nodes, seenPaths) {
158
+ let md = `# CONTEXT PACK: ${project.toUpperCase()}\n\n`;
159
+ md += `**Mode**: \`${mode}\`\n`;
160
+ if (keyword)
161
+ md += `**Search**: \`${keyword}\`\n`;
162
+ md += `\n`;
163
+ for (const node of nodes) {
164
+ if (seenPaths.has(node.path))
165
+ continue;
166
+ seenPaths.add(node.path);
167
+ md += `## 📄 ${node.title}\n`;
168
+ md += `**Path**: \`${node.path}\`\n\n`;
169
+ md += `${node.content}\n\n`;
170
+ md += `---\n\n`;
171
+ }
172
+ return md;
173
+ }
174
+ /**
175
+ * Salvar contexto em arquivo
176
+ */
177
+ save(content, outputPath) {
178
+ const dir = path.dirname(outputPath);
179
+ if (!fs.existsSync(dir)) {
180
+ fs.mkdirSync(dir, { recursive: true });
181
+ }
182
+ fs.writeFileSync(outputPath, content, 'utf8');
183
+ }
184
+ /**
185
+ * Estatísticas de contexto
186
+ */
187
+ stats(mode, project, keyword = '') {
188
+ const content = this.build(mode, project, keyword);
189
+ const lines = content.split('\n').length;
190
+ const tokens = Math.round(content.length / 4); // Aproximação simples
191
+ return {
192
+ mode,
193
+ project,
194
+ keyword,
195
+ bytes: content.length,
196
+ lines,
197
+ tokens,
198
+ estimatedCost: (tokens * 0.00001).toFixed(4), // Assumindo $0.00001 por token
199
+ };
200
+ }
201
+ }
202
+ /**
203
+ * Modo CLI - Executar via node scripts/context-builder.mjs
204
+ */
205
+ if (import.meta.url === `file://${process.argv[1]}`) {
206
+ const [mode, project, keyword] = process.argv.slice(2);
207
+ if (!mode || !project) {
208
+ console.error('Usage: node context-builder.mjs <mode> <project> [keyword]');
209
+ console.error('Modes: global, domain, task');
210
+ process.exit(1);
211
+ }
212
+ ensureSchema({ silent: true });
213
+ const dbPath = getDbPath();
214
+ const builder = new ContextBuilder(process.cwd(), dbPath);
215
+ try {
216
+ console.log(`🔨 Building ${mode} context for ${project}...`);
217
+ const content = builder.build(mode, project, keyword);
218
+ const stats = builder.stats(mode, project, keyword);
219
+ const outDir = path.join(process.cwd(), '.context');
220
+ const outFile = path.join(outDir, `context-${mode}.md`);
221
+ builder.save(content, outFile);
222
+ console.log(`✅ Context saved: ${outFile}`);
223
+ console.log(`📊 Stats:`, stats);
224
+ }
225
+ catch (e) {
226
+ console.error('❌ Error:', e.message);
227
+ process.exit(1);
228
+ }
229
+ finally {
230
+ builder.close();
231
+ }
232
+ }
233
+ export default ContextBuilder;
@@ -0,0 +1,91 @@
1
+ /**
2
+ * lib/core/checks.mjs — o runner de checks. Sem opinião sobre o que se checa.
3
+ *
4
+ * Máquina compartilhada por dois catálogos, cada um guardando uma fronteira:
5
+ *
6
+ * health.mjs o núcleo — o que impede o framework de trabalhar aqui (SPEC-009, ADR-0023)
7
+ * release.mjs o tarball — o que impede o pacote de funcionar na máquina de quem instala (SPEC-010)
8
+ *
9
+ * O runner foi extraído, e não copiado, de propósito: duas máquinas iguais divergem com o tempo, e
10
+ * divergência entre superfícies que deveriam concordar é exatamente o defeito que a SPEC-009
11
+ * existiu para matar (o doctor e o hook diziam coisas diferentes sobre a mesma memória).
12
+ *
13
+ * Dois princípios, que valem para qualquer check novo em qualquer catálogo:
14
+ *
15
+ * 1. **Nunca colapsar causas distintas num booleano.** Um probe classifica a causa e devolve a
16
+ * correção *dela*. O bug que originou tudo isso era um `catch { return null }` que engolia três
17
+ * causas e prescrevia a correção de uma.
18
+ * 2. **Uma causa, uma linha vermelha.** Check cuja dependência falhou é `skipped`, não `fail` —
19
+ * senão uma raiz vira três erros vermelhos e o operador não sabe qual perseguir.
20
+ */
21
+ export type Severity = 'critical' | 'warn';
22
+ export type Scope = 'runtime' | 'repo';
23
+ export type Status = 'ok' | 'warn' | 'fail' | 'skipped';
24
+ export interface Probe {
25
+ status: Status;
26
+ /** O que foi observado, em uma linha. */
27
+ detail: string;
28
+ /** Comando exato que corrige. `null` quando não há o que corrigir. */
29
+ fix?: string | null;
30
+ }
31
+ export interface Check {
32
+ id: string;
33
+ title: string;
34
+ /** `critical` trava o gate; `warn` informa. */
35
+ severity: Severity;
36
+ /** Filtro opcional do runner. */
37
+ scope?: Scope;
38
+ /** Id de outro check. Se ele não passar, este vira `skipped`. */
39
+ dependsOn?: string;
40
+ /**
41
+ * `env` é injetado e polimórfico entre os catálogos (health/release/doc) — daí `any`. Tipagem
42
+ * por-catálogo com generics fica para uma fase posterior; o valor aqui é o contrato do resultado.
43
+ */
44
+ probe: (env: any) => Promise<Probe> | Probe;
45
+ }
46
+ export interface Result {
47
+ id: string;
48
+ title: string;
49
+ severity: Severity;
50
+ scope?: Scope;
51
+ status: Status;
52
+ detail: string;
53
+ fix: string | null;
54
+ }
55
+ /**
56
+ * Estreita um valor capturado num `catch` (que o TS tipa como `unknown`) para a forma de erro do
57
+ * Node — `code`/`message` opcionais. Não muda comportamento: só dá ao compilador o que o runtime
58
+ * já assume ao ler `err.code`.
59
+ *
60
+ * @param {unknown} e
61
+ * @returns {NodeJS.ErrnoException}
62
+ */
63
+ export declare function asErrno(e: any): any;
64
+ /**
65
+ * Executa os checks na ordem declarada.
66
+ *
67
+ * @param {{ checks: Check[], scope?: Scope|'all', env?: object }} opts
68
+ * @returns {Promise<Result[]>}
69
+ */
70
+ export declare function runChecks({ checks, scope, env }: {
71
+ checks: any;
72
+ scope?: string | undefined;
73
+ env?: {} | undefined;
74
+ }): Promise<Result[]>;
75
+ /**
76
+ * Veredito agregado. Só `critical` reprova — um gate que trava por aquilo que não impede trabalho
77
+ * é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
78
+ *
79
+ * @param {Result[]} results
80
+ * @returns {'ok'|'warn'|'fail'}
81
+ */
82
+ export declare function worstStatus(results: any): "warn" | "ok" | "fail";
83
+ /**
84
+ * Remove template literals do fonte antes de qualquer análise estática de `import`.
85
+ *
86
+ * Os geradores do Forja *escrevem* código NestJS dentro de crases — `import { Module } from
87
+ * '@nestjs/common'` é texto que eles emitem, não dependência que eles usam. Contá-lo faz o check
88
+ * acusar `@nestjs/core` como dependência não declarada e `./app.module` como import quebrado.
89
+ * Observado em campo ao auditar o tarball da 1.1.3.
90
+ */
91
+ export declare function stripTemplateLiterals(source: any): any;